# Agent Teams [English](agent-team.md) | 中文 实验性隐式 Root Team 领域、模型工具与宿主适配器共享的类型。[Agent Teams Agent Note](../../.agents/notes/implemented/feature/2026-08-05-agent-teams.zh.md)负责身份、mailbox、task 与共享 checkout 决策；本页记录 [`packages/experimental/agent-team/src/types.ts`](../../packages/experimental/agent-team/src/types.ts) 中的持久与客户端可见形式。 ## 身份与 roster `TeamId` 是使用独立[品牌类型](core.zh.md#branded-ids)的 root `SessionId`。`TeamTaskId` 按 `task-` 分配。新发送返回目标 inbox 的 `MessageId`；`TeamMessageId` 仅供历史 mailbox 记录保留。teammate 名称是不可变标签。 ```ts type-equiv /** Whole durable value written on every teammate lifecycle change. */ interface TeamMemberSnapshot { readonly id: SessionId readonly name: string readonly description: string readonly provider: string readonly context: 'fresh' | 'fork' readonly phase: TeamMemberPhase readonly error?: string } ``` 每个 member 都从 `provisioning` 开始，并且只到达一个终态 roster phase：`active` 或 `failed`。roster 的 `running`／`inactive` 状态单独派生，绝不会重写该记录。 ## 消息与历史 mailbox 新发送返回 inbox 接收结果或拒绝。目标保存现有 `agent-message` source，包含真实发送者 Session id 和发送者名称正文前缀。Team 不为新消息提供 outbox 或重发去重。[包约定](../../packages/experimental/agent-team/README.zh.md#understand-the-implementation)定义持久化。以下 mailbox 类型继续可读，以便历史 Lead 日志仍能回放；Team 不投递其中的 pending 记录。 ```ts type-equiv /** One peer message recorded by the historical Team mailbox. */ interface TeamMessageSnapshot { readonly id: TeamMessageId readonly senderId: SessionId readonly senderName: string readonly targetId: SessionId readonly content: ContentBlock[] } ``` 每条消息都会尝试 Steer 投递。running target 在最近的步骤边界收到消息，inactive target 在已加载时启动一个轮次，否则冷恢复。调用方不能选择其他模式，因此持久记录不存储调度方式。 历史 `team-message` source 保留旧消息 id 与发送者归属；客户端用它们展示消息标题和图标。 ```ts type-equiv /** Source recorded by a target Session for one historical Team mailbox delivery. */ interface TeamMessageSource { readonly kind: 'team-message' readonly teamId: TeamId readonly messageId: TeamMessageId readonly senderId: SessionId readonly senderName: string } ``` ## 共享任务 DAG 每条 task event 都存储完整快照。`revision` 是 compare-and-set 值，每次变更递增 1。`blockedBy` edge 必须指向未删除任务，并维持无环图。`writeScopes` 是规范化的提示性路径前缀，不是锁。 ```ts type-equiv /** Whole durable task snapshot; every mutation increments {@link revision}. */ interface TeamTaskSnapshot { readonly id: TeamTaskId readonly revision: number readonly subject: string readonly description: string readonly status: TeamTaskStatus readonly ownerId?: SessionId readonly blockedBy: TeamTaskId[] readonly writeScopes: string[] } ``` `pending` 表示尚未开始或已经释放，`in_progress` 携带 owner，`completed` 满足 blocker，`deleted` 是保留的 tombstone。view 会添加 owner name、readiness 和 write-scope 重叠警告，但不会改变持久快照。 ## Web 投影 Lead Session 通过 `SessionProjectionMap.agentTeam` 发布持久 roster 行与未删除任务视图。`failure` 在最后有效状态旁报告被拒绝的持久记录。成员活动来自 Session 状态；模型标签来自各成员的 `modelSelection` 投影。 ```ts type-equiv /** One durable roster row published through the `agentTeam` Session projection. */ interface TeamMemberProjection { readonly id: SessionId readonly name: string readonly role: 'lead' | 'teammate' /** Durable lifecycle; the Lead row is always `active`. Turn activity comes from Session status. */ readonly phase: TeamMemberPhase readonly error?: string } ``` ```ts type-equiv /** Runtime-enriched task view returned to tools and hosts. */ interface TeamTaskView { readonly id: TeamTaskId readonly revision: number readonly subject: string readonly description: string readonly status: TeamTaskStatus readonly blockedBy: TeamTaskId[] readonly writeScopes: string[] readonly ownerName?: string readonly ready: boolean readonly writeScopeWarnings: string[] } ``` ```ts type-equiv /** * Durable Team state published to browser clients through the Lead Session's * `agentTeam` projection. `failure` names the first rejected persisted Team * record; members and tasks then stay at the last valid state. */ interface TeamProjection { readonly members: TeamMemberProjection[] readonly tasks: TeamTaskView[] readonly failure?: string } ``` ## 回放 `agentTeam` Session 投影把一个 Root Session 回放成roster、任务板与历史 queued-minus-delivered mailbox。它按 `TeamId` 选取记录，因此普通 fork 继承的 event 保留 ancestor id，绝不会进入新 Root 的状态。Session event 的 `seq` 与 `time` 继续负责顺序和时间记录，Team snapshot 不再重复保存它们。roster 与 task 读取以 view 形式到达调用方，而 pending 邮件不对调用方公开。包 [README](../../packages/experimental/agent-team/README.zh.md)负责 operation、authorization、recovery 和限制行为。 ## Cordis API Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.zh.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md). ### `ctx.agentTeams` — `TeamService` Agent Teams service backed by the exact live Lead Session log. ```ts cordis-catalog /** * Resolve one exact live Agent's Team role. * @param agent - exact live Agent used as the authority credential. * @returns its root, Team identity, role, and model-facing name. */ membership(agent: Agent): TeamMembership /** * List the runtime-enriched roster visible to one Team member. * @param agent - exact live Team member. * @returns Lead and teammate rows in creation order. */ listMembers(agent: Agent): TeamMemberView[] /** * Create one named, continuable direct child of the Team Lead. * @param caller - exact live Lead Agent. * @param request - immutable name, description, prompt, context mode, provider, and cancellation. * @returns the active roster row. */ async spawnTeammate(caller: Agent, request: SpawnTeammateRequest): Promise /** * Steer one peer message into the target inbox or reject the attempt. * @param caller - exact live sending Team member. * @param request - target name, content, and cancellation before acceptance. * @returns accepted inbox identity; acceptance follows normal Agent persistence and does not await model processing. */ async sendMessage(caller: Agent, request: SendTeamMessageRequest): Promise /** * Create one unowned pending task in the Team Lead log. * @param caller - exact live Team member creating the task. * @param request - task text, blockers, and advisory write scopes. * @returns the revision-one task view. */ async createTask(caller: Agent, request: CreateTeamTaskRequest): Promise /** * Return one task, including a deleted tombstone. * @param caller - exact live Team member reading the task. * @param id - Team-local task identity. * @returns the latest task value and derived readiness diagnostics. */ getTask(caller: Agent, id: TeamTaskId): TeamTaskView /** * List current non-deleted tasks in numeric creation order. * @param caller - exact live Team member reading the board. * @returns detached current task views. */ listTasks(caller: Agent): TeamTaskView[] /** * Compare-and-set one authorized task transition. * @param caller - exact live Team member authorizing the mutation. * @param request - task identity, expected revision, action, and action fields. * @returns the committed next task revision. */ async updateTask(caller: Agent, request: UpdateTeamTaskRequest): Promise /** * Wait for the next Team-domain or member-status change. * @param caller - exact live Team member waiting for activity. * @param timeoutMs - bounded wait duration from ten seconds through one hour. * @param signal - caller cancellation for the wait only. * @returns one observed change or a timeout result. */ async waitForChange(caller: Agent, timeoutMs: number, signal: AbortSignal): Promise /** * Interrupt one live teammate turn without clearing its pending inbox. * @param caller - exact live Lead Agent. * @param targetName - durable teammate name. * @returns the target status sampled before cancellation. */ interrupt(caller: Agent, targetName: string): { previousStatus: 'running' | 'inactive' } /** * Resolve a caller without throwing, used by scoped-tool installation and observers. * @param agent - candidate exact live Agent. * @returns Team membership, or undefined for non-Team subagents and stale identities. */ tryMembership(agent: Agent): TeamMembership | undefined ``` Types: [Agent](core.zh.md) Source: [`packages/experimental/agent-team/src/index.ts`](../../packages/experimental/agent-team/src/index.ts)