8.5 KiB
Agent Teams
English | 中文
实验性隐式 Root Team 领域、模型工具与宿主适配器共享的类型。subagent teammate Agent Note负责成员关系、roster 与消息决策；本页记录 packages/experimental/agent-team/src/types.ts 中的持久与客户端可见形式。
身份与 roster
TeamId 为根 SessionId 添加品牌；TeamTaskId 使用 task-<n>。TeamMessageId 仅供历史邮箱记录保留。Team 不写成员记录：视图包含 Lead、以 id 和 description 构成 TeamChild 的直接可继续子级，以及历史成员。描述可以重复；id 用于寻址成员。
/** Historical roster value written by earlier Team builds 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
}
历史记录保留 provisioning、active 或 failed 阶段；直接可继续子级为 active。轮次活动（running 或 inactive）单独派生。
消息与历史 mailbox
成员之间交换普通的 subagent 消息：目标保存包含真实发送者 Session id 的 agent-message source。Team 没有 outbox、mailbox 或重发去重。以下 mailbox 类型继续可读，以便历史 Lead 日志仍能回放；Team 从不投递其中的 pending 记录。
/** 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[]
}
历史 team-message source 保留旧消息 id 与发送者归属；客户端用它们展示消息标题和图标。
/** 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 是规范化的提示性路径前缀，不是锁。
/** 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 携带负责人，completed 满足依赖，deleted 是保留的墓碑记录。视图提供 ownerId、就绪性和写入范围重叠提示，不改变持久快照。
Web 投影
Lead Session 通过 SessionProjectionMap.agentTeam 发布 roster 行与未删除任务视图。failure 在最后有效状态旁报告被拒绝的持久记录。成员活动来自 Session 状态；模型标签来自各成员的 modelSelection 投影。
/**
* One roster row published through the `agentTeam` Session projection: the
* Lead, each continuable direct child of the Lead, and each historical roster member.
*/
interface TeamMemberProjection {
readonly id: SessionId
/** Delegated responsibility; absent for the Lead. Never used as an address. */
readonly description?: string
readonly role: 'lead' | 'teammate'
/** The Lead and continuable children are always `active`. Turn activity comes from Session status. */
readonly phase: TeamMemberPhase
readonly error?: string
}
/** 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 ownerId?: SessionId
readonly ready: boolean
readonly writeScopeWarnings: string[]
}
/**
* 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 投影回放根的可继续目录子级、历史成员、任务和历史邮箱。Team 记录按 TeamId 选取；继承的目录事实被跳过。描述不参与身份校验。Session 事件的 seq 和 time 负责顺序与时间。调用方获得成员和任务视图，不获得待投递邮件。包 README定义操作、授权和限制。
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, and the framework-inherited ctx API lives in cordis-api/inherited.md.
ctx.agentTeams — TeamService
Agent Teams service backed by the exact live Lead Session log.
/**
* Resolve one exact live Agent's Team role.
* @param agent - exact live Agent used as the authority credential.
* @returns its Lead, Team identity, and role.
*/
membership(agent: Agent): TeamMembership
/**
* Resolve a caller without throwing, used by scoped-tool installation and observers.
* @param agent - candidate exact live Agent.
* @returns Team membership, or undefined for stale identities and children whose parent left the registry.
*/
tryMembership(agent: Agent): TeamMembership | undefined
/**
* Whether another live member of the caller's Team is currently running a turn.
* @param caller - exact live Team member.
* @returns whether a peer can still produce a Team change.
*/
hasActivePeer(caller: Agent): boolean
/**
* 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<TeamTaskView>
/**
* 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<TeamTaskView>
/**
* Wait for the next task change, member status change, or message a member's inbox accepts.
* @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<TeamWaitResult>
Types: Agent