b54381f3e7
Agent setup may await while a mutable contribution registry changes. The previous subagent path validated and committed its provisioning batch inside the setup callback. A revocation queued after that callback returned therefore treated the installation as resident and released it, even though AgentLoop had not published the child yet. AgentLoop could then admit and announce a child whose required capability had already disappeared. Introduce AgentSetupCommit as the optional synchronous result of create and resume setup. AgentLoop now awaits setup, invokes that commit with no intervening asynchronous boundary, and only then enters the Session and Agent registries. A commit failure follows the existing private-transaction rollback, so neither identity is published and the caller can reuse the id. Keep continuable-subagent installations provisional until this publication commit. Contribution removal still releases every installation immediately, but now marks an unpublished batch invalid so its commit rejects with ACTIVATION_SETUP_REVOKED. Once the commit succeeds, later removal remains ordinary live revocation. Cover create and resume ordering, resume commit rejection and identity reuse, and an assembled microtask revocation that leaves only the parent Agent and Session. Update the public JSDoc, architecture flow, package contracts, current Agent Notes, Chinese counterparts, pairing records, and generated Cordis API to describe the new boundary. Validated with the four focused Agent/subagent test files (91 tests), the isolated assembled regression, targeted TypeScript project builds, generated Cordis API freshness, export JSDoc verification, scoped translation pairing, Markdown wrapping, and Mermaid parsing.
6.4 KiB
@deepseek-ai/dsh-tool-subagent-report
English | 中文
可选的子级作用域 report 工具是 ctx.subagents.reportFrom() 之上的轻量适配器。它为每个可继续的进程内子级提供一条返回通道，指向启动该子级的 Agent（智能体）。本包（package）注册的是可继续子级设置贡献，而不是全局工具，因此 report 只存在于这些子级内部。根 Agent、一次性 subagent、远程 subagent 提供方、同级作用域以及不关联 Agent 的工具执行都不会提供或执行它。安装本包只授予这项子级作用域功能；父到子方向仍由独立的 @deepseek-ai/dsh-tool-subagent-control 负责，可继续模式不依赖这两个包中的任一个。
子级可以在一个轮次中调用 report 零次或多次。调用成功既不会结束轮次或结算 Activation，也不会阻止父级后续消息；轮次结束也绝不会自动上报。该工具不接受接收方参数：exec.agent 是发送方准确的实时 Agent，也是权限凭据；服务根据该子级持久化的 parentSession 推导唯一接收方。成功时返回父级已接受消息的稳定 MessageId，不表示已读回执、inbox 中该次出现的 id、父级日志确认、轮次完成回执或持久化刷盘。父级解析由注册表中的存在性决定：父级不在注册表时，调用失败并返回 direct parent is not live; report was not delivered；已开始宿主 dispose 但仍在注册表中的父级在其日志仍接受追加时仍会接受。服务不会执行注入、父级冷恢复或离线 mailbox 写入；持久化子级 transcript（文本记录）仍是恢复真源，且工具调用失败不能证明未送达（后续 tools/post-execute 否决可能让报告已被接受的调用以失败结束）。
reportDelivery 为每条已接受的报告选择父级调度方式。quiet（默认值）使用 parent.inject()，在不启动父级模型请求的情况下添加面向模型的上下文：父级空闲时，追加操作会在调用返回前完成；报告到达正在准入或运行的父级时，则会暂存到下一个安全日志位置。wakeup 使用 parent.followup()，准确创建一个普通的后续父级轮次，并唤醒停驻的父级驱动；它绝不会对正在运行的轮次进行 steering（中途引导）。这是部署调度策略，因此面向模型的 schema 不能在单次调用中选择或覆盖该策略。
作用域局部注册有意不受子级全局 toolFilter 影响，因此委派允许列表无法移除唯一的返回通道。需要子级不具备返回通道的部署应省略本包。
贡献体以 installReportTool(childCtx, ctx, delivery) 导出，以便检查类消费方把 report 安装到新创建的子级作用域中。全局注册表无法公开作用域局部 schema，因此生成的工具目录会使用这条路径。生产组合仍通过 apply() 进入；subagent seam 的贡献注册表保持私有。
模型体验
工具 schema
模型看到的内容
已生成的 report schema：包含一个必填 output 字符串。其描述说明上报需要显式调用且可以重复，只会到达启动该子级的 Agent，并且不会结束轮次。它不包含接收方或投递模式参数。
Token 影响
每个可继续子级请求支付固定的 schema 成本，其他任何 Agent 的请求均无此成本。
KV Cache 影响
子级中的前缀保持稳定；schema 不会在运行时改变。移除本包会从驻留子级中撤销该 schema，从而改变其下一次请求前缀。
上报结果
模型看到的内容
接受时返回 report accepted by the agent that started you as message <messageId>；规范输出携带稳定的 messageId。发送方未授权、父级不可用或生命周期正在关闭时，失败会成为出错的结果。描述中会说明，失败的调用仍可能已经送达，因为 reportFrom() 接受消息后，后续 tools/post-execute 失败可能替换工具结果。
Token 影响
每次调用都会在执行上报的子级中产生一条简短确认消息。父级还会为上报内容支付 token 成本：静默投递会把内容加入父级的下一次请求，唤醒投递则会使该内容成为一个新父级轮次中唯一的普通消息。
KV Cache 影响
在子级中仅追加。在父级中，带前缀的报告位于现有历史之后，并保留可复用前缀。
父级可见的报告
模型看到的内容
一条用户角色的父级消息，以 Background subagent <child-id> reported: 开头，后接子级准确的 output，并带有持久化来源 { kind: 'subagent-report', senderSessionId: <child-id> }。
Token 影响
子级的完整 output 加上一行前缀；本包不设上限。
KV Cache 影响
仅追加；报告位于父级可复用请求前缀之后。唤醒投递会启动一次独立的父级模型请求，静默投递则不会。
已知限制与暂缓事项
- 父级可能在宿主启动 dispose 后继续接受报告：
AgentHandle.dispose()会先取消并等待完全停稳，然后才撤销作用域并离开注册表；它不公开「dispose 已开始」信号。在该窗口内接受的报告会追加到父级 transcript，但该父级不会在本进程中处理它。对于由延续管理器拥有的父级，管理器的准入边界会在整棵子树拆卸期间拒绝该上报。 - 接受弱于持久投递：没有持久化 mailbox、幂等键、投递回执、重试协议，也不保证恰好一次。任一侧记录接受后若进程失败，结果都不明确；外部重试可能产生重复上报。
- 暂存的静默报告无法立即重建：接受时会返回其稳定
MessageId，但只有当待处理上下文到达普通日志边界后，父级 Session 才能重建带前缀的内容。 - 授权须等到下一个 Activation，撤销则立即生效：子级驻留后再安装本包，只会在该子级的下一个 Activation 中授予
report；移除本包则会立即从驻留子级撤销该 schema。 - 嵌套上报只向上到达一条直接边：孙级只向作为其直接父级的子级上报，不会直接到达顶层协调器；该直接父级必须随后显式发出一条衍生更新。
- 没有速率限制：嵌套子级频繁上报时，
wakeup模式会放大模型工作量；部署通过选择模式自行承担这一取舍。