docs/agent-projects.md

Rama master · réplica de lectura del repositorio original.

# Agent-oriented projects

Projects persist `mode` as `chat` or `agents`. Missing legacy modes resolve to chat; mode is immutable after creation. The optional starter team creates Coordinator, Planner, Software Engineer and Tester atomically. Arbitrary custom roles are supported.

Each project agent has a stable identity, a normal persistent Metis chat, name, role, system prompt, avatar color, and an optional supervisor. Models and their options are selected in the normal chat controls and persisted on the agent's chat; the agent editor has no separate model/provider picker. Project instructions and agent configuration enter actual native and alternative provider prompts. Supervision is descriptive; it grants no permissions. Handoffs inherit the sender's execution mode and account tool policy, and the model and options selected in the recipient's chat. Legacy model fields in agent profiles do not override chat selections.

Agent-project settings include **Allow agents to manage the team**, persisted as `allowAgentManagement` and off by default for new and existing projects. This gates automated creation, profile edits and archival; manual owner management and existing colleague assignments remain available. Every automated mutation rechecks the latest setting, project/account scope, active sender run and write permission. New teammates inherit the active run’s model selection, model parameters and runtime approval policy. Agents cannot change this permission themselves.

The canonical `project_handoff` MCP tool supports delegate, list, status, cancel and retry, plus `create_agent` with `agent` fields, `update_agent` with `agentId` and an `agent` patch, and `archive_agent` with `agentId` when team management is enabled. Profile fields are name, role, systemPrompt, color and supervisorId; model selection remains in the regular chat controls. Archival preserves history and cancels active work. An agent cannot archive its own active identity. The internal route validates owner, sender chat, running job and worker lease; callers cannot spoof identities or ancestry. Assignments enter the existing durable queue and worker. Results come from persisted worker output. Deterministic assistant mirrors in both chats never enqueue another execution. `wait:true` on delegate/retry awaits a real child result; status/list are immediate, read-only queries, including when a recipient checks its own incoming task. Asynchronous work uses the existing subagent review lifecycle. Generic anonymous delegation is unavailable in team chats.

Limits: 32 active agents, delegation depth 4 (also constrained by available worker slots), 8 handoffs per parent, 32 per root, three linked retries and at most 60 minutes per handoff (10 minutes by default). A worker sweep enforces persisted deadlines after reload/restart, including queued tasks. Errors and cancellation remain visible in activity. User retries of a terminal sender start an actual sender run, preserving the failed record.

Version one serializes project writers. A waiting parent yields its project slot to its child; unrelated roots remain queued. The existing chat guard allows one queued/active run per agent; assigning a busy agent returns an explicit error for the sender to retry. Direct chat follow-ups use Metis’s existing queue. Team agents never execute overlapping writes inside the project. Separate projects retain the existing workspace permission boundaries; shared external resources still require coordination.

Stop cancels a task and descendants; stopping a Coordinator cancels its child chain. Pending approvals are denied and questions cancelled. Removing an agent archives it and its chat, preserves history and named handoff references, cancels work and removes subordinate supervisor references. Archived agents cannot execute; their histories remain accessible. Deleting a team project follows existing project removal conventions but first cancels all team work and archives preserved chats. Mode switching and a freeform organizational canvas are intentionally outside this version.

Endpoints: `/api/projects/:id/agents` (GET/POST), `/agents/:agentId` (PATCH/DELETE archive), `/activity` (GET/POST cancel or retry), and authenticated internal `/api/internal/project-handoff`.

## Reusable team presets and AI drafts

Projects → three-dot menu → Team presets is an account-private library. New projects and existing agent teams can browse the library and review or import a team. Save current team snapshots names, roles, prompts, colors and internal reporting relationships; it never copies chat history, runtime identity, permissions or model overrides. Import allocates fresh identities/chats and remaps relationships in one transaction, adding to existing teams without replacing them. The project-wide 32-agent limit applies before import. Deleting a saved preset does not change any imported team.

Make a preset with AI selects a discovered, account-accessible model from the normal model picker. Generation creates an archived draft chat and a standard Ask-mode job using the existing queue, provider adapters and worker. It requests JSON; generated text is strictly parsed and validated as data. Generation never imports agents or saves a preset automatically. The user can edit agent configuration/relationships, remove agents (detaching their draft subordinates), add arbitrary roles, then save or import. Generation is limited to two active requests per account and five minutes per job, with persisted status, errors, cancellation and a session-resumable progress view. Cancelled/timed-out records stay traceable. Models for imported agents remain controlled by their normal chat controls.

API: account-scoped `/api/team-presets` (GET/POST), `/:id` (PATCH/DELETE); `/generate` (POST enqueue/cancel, GET status). `/api/projects` accepts a reviewed `teamDraft`; `/api/projects/:id/agents` accepts `draft` for transactional import. No provider output is executed as a tool call.