Tianyi Cui
a7a5be1703
Run the dsh-archive-agent-notes audit over every active Agent Note on current master, judging each record by whether its rationale still guides work rather than by size or age. - Archive 453 implemented bilingual triplets (417,882 English words): completed UI chrome, narrow adapters, closed bug fixes, implementation walkthroughs whose package READMEs, docs pages, generators, or successor notes now carry the useful behavior, and 51 records fully superseded by a later active note. Keep 201 implemented notes whose ownership rules, negative guarantees, durable or wire semantics, security rules, reintroduction conditions, or still-tempting rejected alternatives remain useful. - Reject 7 proposals whose premise is gone or whose work shipped in amended form under other records; delete 2 rejected notes that no longer prevent a plausible mistake. - Retarget every remaining inbound link to the archived path, and repair active prose that named an archived record as the owner of a live fact: parenthetical citations drop, ownership sentences redirect to the README, docs page, or active note that states the fact, and history citations say so. Chinese files link the English archived path because the pairing gate treats the frozen tree as outside the bilingual corpus. - Seal 1,359 new frozen artifacts; existing seals are unchanged and outbound links from archived notes are neither inspected nor repaired. - Regenerate docs/config-catalog.md after the hook-bridge comment edits shifted two source line numbers.
9.2 KiB
Agent Teams
English | 中文
实验性隐式 Root Team 领域、模型工具与宿主适配器共享的类型。Agent Teams Agent Note负责身份、mailbox、task 与共享 checkout 决策；本页记录 packages/experimental/agent-team/src/types.ts 中的字面持久形式。
身份与 roster
TeamId 是具有独立品牌的 Root SessionId。TeamTaskId 在 Team 内按 task-<n> 单调分配；TeamMessageId 是全局随机值。teammate 的 Session id 始终是持久身份，而 name 是不可变的模型／UI 标签。
/** 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。运行时 running／idle／inactive 状态单独派生，绝不会重写该记录。
持久 mailbox
Lead Session 首先存储完整 queued message。只有 target 的 pending inbox 条目或已记录用户消息完成持久化，才会写入独立 acknowledgement event，queued-minus-delivered 因而构成恢复 mailbox。
/** One peer message retained until its target Session records it. */
interface TeamMessageSnapshot {
readonly id: TeamMessageId
readonly senderId: SessionId
readonly senderName: string
readonly targetId: SessionId
readonly content: ContentBlock[]
}
每条消息都会尝试 Steer 投递。running target 在最近的步骤边界收到消息，idle target 启动一个轮次，inactive teammate 则冷恢复。调用方不能选择其他模式，因此持久记录不存储调度方式。
target Session 会在 pending inbox 条目和最终用户消息上保留消息身份与发送者归因。跨 inbox 与历史折叠该 source 构成 target 侧去重键；模型可见的 framing 会重复 id 和发送者。
/** Source retained by the target Session for durable mailbox de-duplication. */
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 携带 owner，completed 满足 blocker，deleted 是保留的 tombstone。view 会添加 owner name、readiness 和 write-scope 重叠警告，但不会改变持久快照。
回放
foldTeam() 把一个 Root Session 回放成每个 Team 操作所读取的 roster、任务板与 queued-minus-delivered mailbox。它按 TeamId 选取记录，因此普通 fork 继承的 event 保留 ancestor id，绝不会进入新 Root 的状态。Session event 的 seq 与 time 继续负责顺序和时间记录，Team snapshot 不再重复保存它们。roster 与 task 读取以 view 形式到达调用方，而 pending 邮件仅供投递与恢复内部使用。包 README负责 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, 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 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<SpawnTeammateResult>
/**
* Queue one durable peer message, then attempt immediate delivery.
* @param caller - exact live sending Team member.
* @param request - target name, content, and pre-queue cancellation.
* @returns durable message identity and immediate-delivery observation.
*/
async sendMessage(caller: Agent, request: SendTeamMessageRequest): Promise<SendTeamMessageResult>
/**
* 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 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<TeamWaitResult>
/**
* 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' | 'idle' | '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
/**
* Read the current roster and non-deleted task board through the generated Remote API.
* @param agent - exact live Team member used as the authority credential.
* @returns detached current roster and task views.
*/
@Remote('view') remoteView(agent: Agent): TeamView
/**
* Create one shared task through the generated Remote API.
* @param agent - exact live Team member creating the task.
* @param request - task text, blockers, and advisory write scopes.
* @returns the revision-one task or a typed Team rejection.
*/
@Remote('createTask') remoteCreateTask(agent: Agent, request: CreateTeamTaskRequest): Promise<TeamTaskMutationResult>
/**
* Apply one task mutation and preserve Team rejections as business results.
* @param agent - exact live Team member authorizing the mutation.
* @param request - task identity, expected revision, action, and action fields.
* @returns the committed task or a typed Team rejection.
*/
@Remote('updateTask') remoteUpdateTask(agent: Agent, request: UpdateTeamTaskRequest): Promise<TeamTaskMutationResult>
Types: Agent