Merge retargeted parent into Claude Code subagent provider
This commit is contained in:
Tianyi Cui
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write packages/subagent/README.md
|
||||
README.md: a03917293b4468e3456310e30c543f06c5f8f8d8
|
||||
README.zh.md: 3839b0c93b9854888ee6f46e0e7d2a3b68cd8a06
|
||||
README.md: 0a342569e66539e4987710b2e56f2946c97b1ac1
|
||||
README.zh.md: 5d2f7beef478b8bfd27b4772c7a951ea62cb10ef
|
||||
|
||||
@@ -2,22 +2,20 @@
|
||||
|
||||
English | [中文](README.zh.md)
|
||||
|
||||
The subagent seam: an agent delegating work to a child agent. Like the [bash](../bash/README.md) and [llm](../llm/README.md) families this is a capability seam (see [capability seams](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)) — but with one defining difference: **multiple provider implementations coexist in one context**, registered by name, rather than the single-implementation bash shape. The registry mirrors the LLM adapter registry.
|
||||
This family lets an agent delegate work to child agents. Multiple named providers may coexist in one context.
|
||||
|
||||
| Package | Role | ctx key |
|
||||
|---|---|---|
|
||||
| `subagent/` | Subagent service: named-provider registry, vocabulary, durable descriptor, and continuable-child orchestration | `ctx.subagents` |
|
||||
| `subagent-inprocess/` | Shared in-process run driver (no provider; one cleanup effect per run) | — |
|
||||
| `subagent-spawn/` | In-process backend: a fresh child agent, with cold resume | (registers on `ctx.subagents`) |
|
||||
| `subagent-fork/` | In-process backend: a child seeded with the parent's completed-turn prefix, with cold resume | (registers on `ctx.subagents`) |
|
||||
| `subagent-acp/` | Out-of-process backend: a child agent in a spawned subprocess, driven over ACP (one-shot) | (registers on `ctx.subagents`) |
|
||||
| `subagent-codex/` | Out-of-process backend: a real Codex app-server process with one ephemeral thread and turn | (registers on `ctx.subagents`) |
|
||||
| `subagent-claude-code/` | Out-of-process backend: the official Claude Agent SDK with one real Claude Code CLI query | (registers on `ctx.subagents`) |
|
||||
| `subagent-dsh-sdk/` | Out-of-process backend: a child harness runtime in a spawned subprocess, driven over stdio JSON-RPC through the TypeScript SDK client | (registers on `ctx.subagents`) |
|
||||
| `tool-subagent/` | Model-facing `subagent` delegation tool over `ctx.subagents` | (registers on `ctx.tools`) |
|
||||
| `tool-subagent-control/` | The optional, globally named `send_message` and `list_agents` tools over `ctx.subagents` | (registers on `ctx.tools`) |
|
||||
| `tool-subagent-report/` | Child-scoped `report` return channel for continuable in-process children | (registers in each child scope) |
|
||||
| [`subagent/`](subagent/README.md) | Defines provider registration, delegation, and continuation | `ctx.subagents` |
|
||||
| [`subagent-inprocess/`](subagent-inprocess/README.md) | Provides the shared in-process run driver | — |
|
||||
| [`subagent-spawn/`](subagent-spawn/README.md) | Starts a fresh in-process child | registers on `ctx.subagents` |
|
||||
| [`subagent-fork/`](subagent-fork/README.md) | Starts an in-process child from the parent's completed history | registers on `ctx.subagents` |
|
||||
| [`subagent-acp/`](subagent-acp/README.md) | Starts an out-of-process child over ACP | registers on `ctx.subagents` |
|
||||
| [`subagent-codex/`](subagent-codex/README.md) | Starts a real Codex app-server child | registers on `ctx.subagents` |
|
||||
| [`subagent-claude-code/`](subagent-claude-code/README.md) | Starts a real Claude Code child through the official Claude Agent SDK | registers on `ctx.subagents` |
|
||||
| [`subagent-dsh-sdk/`](subagent-dsh-sdk/README.md) | Starts an out-of-process Harness child through the TypeScript SDK | registers on `ctx.subagents` |
|
||||
| [`tool-subagent/`](tool-subagent/README.md) | Exposes delegation to the model | registers on `ctx.tools` |
|
||||
| [`tool-subagent-control/`](tool-subagent-control/README.md) | Exposes child messaging and listing to the model | registers on `ctx.tools` |
|
||||
| [`tool-subagent-report/`](tool-subagent-report/README.md) | Provides the child-to-parent report channel | registers in child scopes |
|
||||
|
||||
The interface and continuation orchestration live at `subagent/subagent/`. One-shot provider `start` dispatch stays independent of persistence; an internal continuation manager owns each durable continuable child as one Session plus at most one process-local Activation, binding no Task, and exists only while the Agent service is present, resolving persistence per continuation operation. The in-process `subagent-spawn` / `subagent-fork` backends share the `subagent-inprocess` driver (a library with no provider of its own — both depend on it, neither on the other). The out-of-process `subagent-acp` / `subagent-codex` / `subagent-claude-code` backends spawn through the [`subprocess/`](../subprocess/README.md) seam, which owns credential scrubbing, termination escalation, and whole-tree exit observation; `subagent-dsh-sdk` instead delegates process creation and teardown to the TypeScript SDK client that owns its transport, while reusing the seam's credential scrub. Tests replace only external or nondeterministic product boundaries with package-local fixtures.
|
||||
|
||||
The design rationale: [.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md), [.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md](../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md), and [.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md).
|
||||
See the decisions for the [capability family](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md), [continuable children](../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md), and [control tools](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md).
|
||||
|
||||
@@ -2,22 +2,20 @@
|
||||
|
||||
[English](README.md) | 中文
|
||||
|
||||
subagent（子 agent）seam 允许 agent（智能体）把工作委派给子 agent。与 [bash](../bash/README.md) 和 [llm](../llm/README.md) 能力家族一样，这也是一种能力 seam（见[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)），但有一个关键差异：**多个提供方实现在同一上下文中共存，并按名称注册**，而不是采用 bash 的单实现形态。该注册表仿照大语言模型（LLM）适配器注册表。
|
||||
本家族允许一个 agent（智能体）将工作委派给子 agent。多个具名提供方可在同一上下文中共存。
|
||||
|
||||
| 包（package） | 角色 | ctx 键 |
|
||||
| 包 | 职责 | ctx 键 |
|
||||
|---|---|---|
|
||||
| `subagent/` | Subagent 服务：具名提供方注册表、词汇、持久化描述符与可继续子 agent 编排 | `ctx.subagents` |
|
||||
| `subagent-inprocess/` | 共享进程内运行驱动器（不含提供方；每次运行使用一个清理 effect） | 无 |
|
||||
| `subagent-spawn/` | 进程内后端：支持冷恢复的全新子 agent | （注册到 `ctx.subagents`） |
|
||||
| `subagent-fork/` | 进程内后端：以父 agent 已完成轮次的前缀作为初始内容、支持冷恢复的子 agent | （注册到 `ctx.subagents`） |
|
||||
| `subagent-acp/` | 进程外后端：在 spawn 的子进程中运行并通过 ACP（Agent Client Protocol）驱动的一次性子 agent | （注册到 `ctx.subagents`） |
|
||||
| `subagent-codex/` | 进程外后端：一个真实的 Codex app-server 进程，包含一个临时 thread 和一个轮次 | （注册到 `ctx.subagents`） |
|
||||
| `subagent-claude-code/` | 进程外后端：使用官方 Claude Agent SDK 与一次真实 Claude Code CLI query | （注册到 `ctx.subagents`） |
|
||||
| `subagent-dsh-sdk/` | 进程外后端：在 spawn 的子进程中运行的子 harness 运行时，经 TypeScript SDK 客户端走 stdio JSON-RPC 驱动 | （注册到 `ctx.subagents`） |
|
||||
| `tool-subagent/` | 面向模型的 `subagent` 委派工具，基于 `ctx.subagents` | （注册到 `ctx.tools`） |
|
||||
| `tool-subagent-control/` | 基于 `ctx.subagents`、可选且全局名称唯一的 `send_message` 与 `list_agents` 工具 | （注册到 `ctx.tools`） |
|
||||
| `tool-subagent-report/` | 子级作用域的 `report` 返回通道，用于可继续的进程内子级 | （注册到每个子级作用域） |
|
||||
| [`subagent/`](subagent/README.md) | 定义提供方注册、委派和继续执行 | `ctx.subagents` |
|
||||
| [`subagent-inprocess/`](subagent-inprocess/README.md) | 提供共享的进程内运行驱动器 | 无 |
|
||||
| [`subagent-spawn/`](subagent-spawn/README.md) | 启动全新的进程内子 agent | 注册到 `ctx.subagents` |
|
||||
| [`subagent-fork/`](subagent-fork/README.md) | 从父 agent 已完成的历史记录启动进程内子 agent | 注册到 `ctx.subagents` |
|
||||
| [`subagent-acp/`](subagent-acp/README.md) | 通过 ACP（Agent Client Protocol）启动进程外子 agent | 注册到 `ctx.subagents` |
|
||||
| [`subagent-codex/`](subagent-codex/README.md) | 启动真实的 Codex app-server 子 agent | 注册到 `ctx.subagents` |
|
||||
| [`subagent-claude-code/`](subagent-claude-code/README.md) | 通过官方 Claude Agent SDK 启动真实的 Claude Code 子 agent | 注册到 `ctx.subagents` |
|
||||
| [`subagent-dsh-sdk/`](subagent-dsh-sdk/README.md) | 通过 TypeScript SDK 启动进程外 Harness 子 agent | 注册到 `ctx.subagents` |
|
||||
| [`tool-subagent/`](tool-subagent/README.md) | 向模型公开委派操作 | 注册到 `ctx.tools` |
|
||||
| [`tool-subagent-control/`](tool-subagent-control/README.md) | 向模型公开子级消息发送和列举操作 | 注册到 `ctx.tools` |
|
||||
| [`tool-subagent-report/`](tool-subagent-report/README.md) | 提供从子级到父级的报告通道 | 注册到子级作用域 |
|
||||
|
||||
接口和继续执行编排位于 `subagent/subagent/`。一次性提供方 `start` 分发不依赖持久化；内部继续执行管理器把每个持久化可继续子 agent 作为一个 Session 加至多一个进程内 Activation 来拥有，不绑定任何 Task，且只在 Agent 服务存在时存在，并按每项继续执行操作解析持久化。进程内 `subagent-spawn` / `subagent-fork` 后端共享 `subagent-inprocess` 驱动器（一个自身不含提供方的库：两者都依赖它，彼此不依赖）。进程外 `subagent-acp` / `subagent-codex` / `subagent-claude-code` 后端则经由 [`subprocess/`](../subprocess/README.md) seam spawn 其子进程，该 seam 拥有凭据清除、终止升级和整棵进程树的退出观测；`subagent-dsh-sdk` 则将进程创建和拆卸委托给拥有自身传输的 TypeScript SDK 客户端，同时复用该 seam 的凭据清除机制。测试只用包内 fixture（测试前置数据）替换外部或非确定性的产品边界。
|
||||
|
||||
设计理由见 [.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)、[.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md](../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md) 和 [.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md)。
|
||||
参见[能力家族](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)、[可继续执行的子级](../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md)和[控制工具](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md)决策。
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write packages/subagent/subagent-acp/README.md
|
||||
README.md: ead942668f19c44f552d3feb556c39c13b656dea
|
||||
README.zh.md: e1204ff62f23c8586852111687574a60b0bb7302
|
||||
README.md: 4fdd3a09e128d4dc7ec7395d9578803c64a33bc6
|
||||
README.zh.md: 7cb1e3d18602ef839e4af316962fc2d10bc67640
|
||||
|
||||
@@ -61,8 +61,6 @@ The child spawns through the [`dsh-subprocess`](../../subprocess/subprocess/READ
|
||||
|
||||
The package has no default export. Cordis loader unwrapping would otherwise hide the named `inject` metadata; see [postmortem 0001](../../../docs/postmortem/0001-acp-default-export-drops-inject.md).
|
||||
|
||||
Keyless tests drive a scripted ACP subprocess over real stdio, including a Loader-composed stdio app proving parent-session cwd inheritance end to end. The with-key e2e drives the repository's real ACP agent and self-skips without `DEEPSEEK_API_KEY`.
|
||||
|
||||
## Model Experience
|
||||
|
||||
### Child-agent request
|
||||
@@ -100,4 +98,3 @@ Append-only; newly visible content follows the reusable request prefix and does
|
||||
- **No optional start-time capabilities** — this provider cannot apply the local harness's `outputSchema`, depth cap, tool filter, or persona inside the remote process, so it advertises none and the service rejects requests that require them.
|
||||
- **Only committed `agent_message_chunk` text is collected** — the automation server keeps reasoning, tool activity, plans, and other trace data in the child session log rather than emitting them on ACP.
|
||||
- **Permission prompts are auto-answered** (`permission: allow | reject`) — no human is surfaced a child's `session/request_permission` in this cut.
|
||||
- **No snapshot-tier replay coverage** (`TODO(acp-subagent-replay)`) — an ACP child is its own process with its own replay shape, deferred.
|
||||
|
||||
@@ -59,9 +59,7 @@ ACP 不声明任何启动时能力，因为当前进程无法强制执行远程
|
||||
|
||||
子进程经由 [`dsh-subprocess`](../../subprocess/subprocess/README.md) seam spawn：共享的凭据清除先移除疑似凭据的环境变量和环境中已有的 `DSH_*` 名称，显式 `config.env` 值在清除之后合并（有意转发的 `DEEPSEEK_API_KEY` 会保留下来，`DSH_PERMISSION_MODE` 这类 `DSH_*` 部署事实也以同样的方式到达子进程——清除只丢弃其陈旧的同名环境值），stderr 会继承到父进程自身的流，dispose 则先应用本插件的 EOF 时间窗，再由子进程责任方执行 SIGTERM→SIGKILL 升级并等待整棵进程树退出。ACP 协议格式（wire format）是真正的序列化边界；同进程 subagent 值不会为防御目的而克隆。
|
||||
|
||||
本包（package）没有默认导出。否则 Cordis loader 的解包会隐藏具名 `inject` 元数据；见[事故复盘（postmortem）0001](../../../docs/postmortem/0001-acp-default-export-drops-inject.md)。
|
||||
|
||||
无密钥测试通过真实 stdio 驱动脚本化 ACP 子进程，其中包括一个由 Loader 组合的 stdio 应用，用于端到端证明父会话 cwd 继承。带密钥 e2e 会驱动仓库中的真实 ACP agent；没有 `DEEPSEEK_API_KEY` 时自行跳过。
|
||||
本包没有默认导出。否则 Cordis loader 的解包会隐藏具名 `inject` 元数据；见[事故复盘（postmortem）0001](../../../docs/postmortem/0001-acp-default-export-drops-inject.md)。
|
||||
|
||||
## 模型体验
|
||||
|
||||
@@ -91,13 +89,12 @@ ACP 不声明任何启动时能力，因为当前进程无法强制执行远程
|
||||
|
||||
#### KV Cache 影响
|
||||
|
||||
仅追加；新增可见内容位于可复用请求前缀之后，不会使现有 KV-cache 条目失效。
|
||||
仅追加；新增可见内容位于可复用请求前缀之后，不会使现有 KV Cache 条目失效。
|
||||
|
||||
## 已知限制与暂缓事项
|
||||
|
||||
- **每次运行使用全新进程**：持久进程池属于后续优化（见 [seam Agent Note（agent 决策记录）](../../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)）。
|
||||
- **每次运行使用全新进程**：持久进程池属于后续优化（见 [seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)）。
|
||||
- **仅支持本地工作区**：解析后的 cwd 是交给同一台机器上子进程的本地路径；远程 ACP agent 的工作区映射需要独立的后端能力，本包尚未设计。
|
||||
- **不支持可选启动时能力**：该提供方无法在远程进程内应用本地 harness 的 `outputSchema`、深度上限、工具过滤器或 persona，因此不会声明这些能力；服务会拒绝需要它们的请求。
|
||||
- **只收集已提交的 `agent_message_chunk` 文本**：自动化服务器把推理（reasoning）、工具活动、计划和其他 trace 数据保留在子 agent 会话日志中，不通过 ACP 发出。
|
||||
- **权限提示自动回答**（`permission: allow | reject`）：当前版本不会把子 agent 的 `session/request_permission` 呈现给人。
|
||||
- **没有快照层回放覆盖率**（`TODO(acp-subagent-replay)`）：ACP 子 agent 拥有独立进程和独立回放形态，该工作延期处理。
|
||||
|
||||
@@ -21,9 +21,7 @@
|
||||
"files": [
|
||||
"lib/index.js",
|
||||
"lib/invariant.js",
|
||||
"lib/types/**/*.d.ts",
|
||||
"lib/types/**/*.d.ts.map",
|
||||
"src"
|
||||
"lib/types/**/*.d.ts"
|
||||
],
|
||||
"license": "BSD-3-Clause",
|
||||
"peerDependencies": {
|
||||
|
||||
@@ -21,9 +21,7 @@
|
||||
"files": [
|
||||
"lib/index.js",
|
||||
"lib/invariant.js",
|
||||
"lib/types/**/*.d.ts",
|
||||
"lib/types/**/*.d.ts.map",
|
||||
"src"
|
||||
"lib/types/**/*.d.ts"
|
||||
],
|
||||
"license": "BSD-3-Clause",
|
||||
"peerDependencies": {
|
||||
|
||||
@@ -21,9 +21,7 @@
|
||||
"files": [
|
||||
"lib/index.js",
|
||||
"lib/invariant.js",
|
||||
"lib/types/**/*.d.ts",
|
||||
"lib/types/**/*.d.ts.map",
|
||||
"src"
|
||||
"lib/types/**/*.d.ts"
|
||||
],
|
||||
"license": "BSD-3-Clause",
|
||||
"peerDependencies": {
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write packages/subagent/subagent-dsh-sdk/README.md
|
||||
README.md: a0c0811b585b69a634e49a2c838137655f316585
|
||||
README.zh.md: e068e27c7cb2cfd39bbf723fabbc29b17f6676f8
|
||||
README.md: c0e2f4e9ece366e28492e32d97afa533fd948141
|
||||
README.zh.md: 4cf6c58fff44b1c11cf0a6c321da2c02d52bb8c9
|
||||
|
||||
@@ -10,13 +10,13 @@ The SDK provider runs each subagent as a complete DeepSeek Harness runtime in a
|
||||
|
||||
The working directory resolves exactly like the ACP backend, through the seam's shared out-of-process helpers ([`dsh-subagent`](../subagent/README.md)): the configured `cwd` override when set (validated once at load), else the delegating parent session's cwd — never the server process's own cwd. The resolved path becomes the child process cwd and the workspace cwd of its SDK session.
|
||||
|
||||
The returned run id is minted in the parent namespace; the child runtime's session id exists only inside the child process. After publication the provider runs one SDK turn and reads the child's answer from its session events: the last complete `assistant/message`, or the `text-delta` stream accumulated so far when the turn was cut short — a partial answer survives cancel and error paths.
|
||||
The returned run id is minted in the parent namespace; the child runtime's session id exists only inside the child process. After publication the provider owns one SDK activity and reads the child's answer from its session events: the last complete `assistant/message`, or the `text-delta` stream accumulated before the activity was cut short — a partial answer survives cancel and error paths.
|
||||
|
||||
`dispose()` is idempotent: it settles the result locally as `aborted` (there is no wire-level prompt cancel), then closes the runtime — a bounded protocol `shutdown` request followed by the shared stdin-EOF → SIGTERM → SIGKILL ladder to actual exit.
|
||||
|
||||
## Stop-reason mapping
|
||||
|
||||
The child reports its turn outcome as a structured `TurnEndReason` on `session.finished`; the provider maps it into the seam vocabulary. `completed` → `completed`, `max-tokens` → `max-tokens`, `aborted` → `aborted`; everything else — `error`, `interrupted`, `disposed`, a future variant, or a turn that never ran — maps to `error`, so an unclean stop is never reported as success. Transport-level failures after publication flatten to `stopReason: 'error'` through the `onError` diagnostic sink (wired to `ctx.logger.warn`); the seam contract forbids `result` rejecting.
|
||||
The SDK client returns an owned child activity rather than a prompt result. The provider reads the last durable `turn/end` inside that activity and maps it into the seam vocabulary: `completed` → `completed`, `max-tokens` → `max-tokens`, `aborted` → `aborted`; everything else — `error`, `interrupted`, `disposed`, a future variant, or an activity with no turn — maps to `error`, so an unclean stop is never reported as success. Transport-level failures after publication flatten to `stopReason: 'error'` through the `onError` diagnostic sink (wired to `ctx.logger.warn`); the seam contract forbids `result` rejecting.
|
||||
|
||||
## Capabilities and context
|
||||
|
||||
@@ -59,8 +59,6 @@ The child environment is the [`dsh-subprocess`](../../subprocess/README.md) seam
|
||||
|
||||
The package has no default export. Cordis loader unwrapping would otherwise hide the named `inject` metadata; see [postmortem 0001](../../../docs/postmortem/0001-acp-default-export-drops-inject.md).
|
||||
|
||||
Keyless tests drive the SDK client package's scripted fake runtime over real stdio, including a Loader-composed e2e where the child is a real second harness runtime proving parent-session cwd inheritance end to end (`tests/loader-composition.e2e.ts`).
|
||||
|
||||
## Model Experience
|
||||
|
||||
### Child-agent request
|
||||
|
||||
@@ -10,13 +10,13 @@ SDK 提供方会在全新的子进程中把每个 subagent 作为完整的 DeepS
|
||||
|
||||
工作目录的解析与 ACP 后端完全一致，并使用 seam 共享的进程外辅助工具（[`dsh-subagent`](../subagent/README.md)）：设置了 `cwd` 覆盖值时使用该值（加载时校验一次），否则使用发起委派的父会话 cwd，绝不使用服务器进程自身的 cwd。解析出的路径同时成为子进程 cwd 和其 SDK 会话的工作区 cwd。
|
||||
|
||||
返回的 run id 在父级命名空间中生成；子运行时的会话 id 只存在于子进程内部。发布后，提供方运行一个 SDK 轮次，并从子会话事件中读取答案：最后一条完整的 `assistant/message`，或轮次被截断时已累积的 `text-delta` 流；部分答案在取消和错误路径上都得以保留。
|
||||
返回的 run id 在父级命名空间中生成；子运行时的会话 id 只存在于子进程内部。发布后，提供方拥有一段 SDK 活动，并从子会话事件中读取答案：最后一条完整的 `assistant/message`，或该活动中断前已经累积的 `text-delta` 流；部分答案在取消和错误路径上都得以保留。
|
||||
|
||||
`dispose()`（资源释放）是幂等的：先在本地把结果确定为 `aborted`（协议层面没有提示词取消机制），再关闭运行时，即先发出一次有界的协议 `shutdown` 请求，随后通过共享的 stdin-EOF → SIGTERM → SIGKILL 阶梯使进程实际退出。
|
||||
|
||||
## 停止原因映射
|
||||
|
||||
子进程在 `session.finished` 上以结构化 `TurnEndReason` 报告轮次结果；提供方将其映射为 seam 词汇。`completed` → `completed`，`max-tokens` → `max-tokens`，`aborted` → `aborted`；其余情况，包括 `error`、`interrupted`、`disposed`、未来变体或根本未运行轮次，均映射为 `error`，因此非正常停止绝不会报告为成功。发布后的传输层失败会通过 `onError` 诊断接收器（连接到 `ctx.logger.warn`）压平为 `stopReason: 'error'`；seam 契约禁止 `result` 被拒绝。
|
||||
SDK 客户端返回自有子活动，而不是提示词结果。提供方读取该活动内最后一个持久 `turn/end`，并将其映射为 seam 词汇：`completed` → `completed`，`max-tokens` → `max-tokens`，`aborted` → `aborted`；其余情况，包括 `error`、`interrupted`、`disposed`、未来变体或不含轮次的活动，均映射为 `error`，因此非正常停止绝不会报告为成功。发布后的传输层失败会通过 `onError` 诊断接收器（连接到 `ctx.logger.warn`）压平为 `stopReason: 'error'`；seam 契约禁止 `result` 被拒绝。
|
||||
|
||||
## 能力与上下文
|
||||
|
||||
@@ -57,9 +57,7 @@ Provider 不宣告任何启动期能力（`outputSchema`/`depthLimit`/`toolFilte
|
||||
|
||||
子进程环境以 [`dsh-subprocess`](../../subprocess/README.md) seam 的 `scrubbedParentEnv()` 为基础，先移除疑似凭据和名称为 `DSH_*` 的环境变量，再合并显式 `config.env` 值。子进程由 SDK 客户端 spawn，而不是经由 `ctx.subprocess` spawn（这是 subprocess README 中记录的 SDK 托管传输例外），因此本后端会自行执行环境清理。JSON-RPC 协议格式才是真正的序列化边界。
|
||||
|
||||
本包（package）没有默认导出。否则 Cordis loader 解包会隐藏具名 `inject` 元数据；见[事故复盘（postmortem）0001](../../../docs/postmortem/0001-acp-default-export-drops-inject.md)。
|
||||
|
||||
免密钥测试通过真实 stdio 驱动 SDK 客户端包的脚本化伪运行时，还包括一个 Loader 组合 e2e：子进程是真实的第二个 harness 运行时，端到端证明父会话 cwd 继承（`tests/loader-composition.e2e.ts`）。
|
||||
本包没有默认导出。否则 Cordis loader 解包会隐藏具名 `inject` 元数据；见[事故复盘（postmortem）0001](../../../docs/postmortem/0001-acp-default-export-drops-inject.md)。
|
||||
|
||||
## 模型体验
|
||||
|
||||
@@ -89,7 +87,7 @@ Provider 不宣告任何启动期能力（`outputSchema`/`depthLimit`/`toolFilte
|
||||
|
||||
#### KV Cache 影响
|
||||
|
||||
仅追加；新增可见内容位于可复用请求前缀之后，不会使现有 KV-cache 条目失效。
|
||||
仅追加；新增可见内容位于可复用请求前缀之后，不会使现有 KV Cache 条目失效。
|
||||
|
||||
## 已知限制与暂缓事项
|
||||
|
||||
|
||||
@@ -21,9 +21,7 @@
|
||||
"files": [
|
||||
"lib/index.js",
|
||||
"lib/invariant.js",
|
||||
"lib/types/**/*.d.ts",
|
||||
"lib/types/**/*.d.ts.map",
|
||||
"src"
|
||||
"lib/types/**/*.d.ts"
|
||||
],
|
||||
"license": "BSD-3-Clause",
|
||||
"peerDependencies": {
|
||||
|
||||
@@ -70,8 +70,8 @@ export const DEFAULT_SHUTDOWN_TIMEOUT_MS = 1_000
|
||||
|
||||
/**
|
||||
* Map a child turn-end reason to a harness {@link SubagentStopReason}.
|
||||
* @param reason - the `session.finished` reason, or `undefined` when the
|
||||
* child settled without running a turn.
|
||||
* @param reason - the owned child run's final durable turn reason, or
|
||||
* `undefined` when it settled without running a turn.
|
||||
* @returns the harness equivalent; an absent or unknown reason maps to
|
||||
* `error`, so an unclean stop is never reported as `completed`.
|
||||
*/
|
||||
@@ -191,7 +191,10 @@ export async function startSdkRun(request: SubagentStartRequest, spec: SdkRunSpe
|
||||
cancelSettled.then(() => 'cancelled' as const),
|
||||
])
|
||||
if (turn === 'cancelled') return { output: collectOutput(), stopReason: 'aborted' }
|
||||
return { output: collectOutput(), stopReason: sdkStopReason(turn.reason) }
|
||||
const lastEnd = turn.events.findLast(
|
||||
(event): event is Extract<SessionEvent, { type: 'turn/end' }> => event.type === 'turn/end',
|
||||
)
|
||||
return { output: collectOutput(), stopReason: sdkStopReason(lastEnd?.data.reason) }
|
||||
},
|
||||
collectOutput,
|
||||
cancelled: () => flags.cancelled,
|
||||
|
||||
@@ -73,10 +73,10 @@ describe('sdkStopReason', () => {
|
||||
it('maps each child turn-end reason to the harness vocabulary', () => {
|
||||
expect(sdkStopReason({ kind: 'completed' })).toBe('completed')
|
||||
expect(sdkStopReason({ kind: 'max-tokens' })).toBe('max-tokens')
|
||||
expect(sdkStopReason({ kind: 'aborted' })).toBe('aborted')
|
||||
expect(sdkStopReason({ kind: 'error', step: 0, message: 'x' })).toBe('error')
|
||||
expect(sdkStopReason({ kind: 'aborted', reason: { kind: 'user' } })).toBe('aborted')
|
||||
expect(sdkStopReason({ kind: 'error', error: { message: 'x', code: 'UNKNOWN' } })).toBe('error')
|
||||
expect(sdkStopReason({ kind: 'interrupted' })).toBe('error')
|
||||
expect(sdkStopReason({ kind: 'disposed' })).toBe('error')
|
||||
expect(sdkStopReason({ kind: 'aborted', reason: { kind: 'disposed' } })).toBe('aborted')
|
||||
})
|
||||
|
||||
it('treats an absent or unknown reason as an error', () => {
|
||||
@@ -165,6 +165,17 @@ describe('dsh-subagent-dsh-sdk provider', () => {
|
||||
await ctx.fiber.dispose()
|
||||
})
|
||||
|
||||
it('keeps streamed text when a malformed final message prevents completion', async () => {
|
||||
const ctx = await setup({ FAKE_MALFORMED_MESSAGE: '1', FAKE_TEXT: 'stream-only answer' })
|
||||
const run = await ctx.subagents.start('dsh-sdk', request())
|
||||
const result = await run.result
|
||||
|
||||
expect(result.stopReason).toBe('error')
|
||||
expect(text(result.output)).toBe('stream-only answer')
|
||||
await run.dispose()
|
||||
await ctx.fiber.dispose()
|
||||
})
|
||||
|
||||
it('reports a settled-without-turn child as an error', async () => {
|
||||
const ctx = await setup({ FAKE_REASON_KIND: 'none', FAKE_STATUS: 'error' })
|
||||
const run = await ctx.subagents.start('dsh-sdk', request())
|
||||
@@ -218,16 +229,15 @@ describe('dsh-subagent-dsh-sdk provider', () => {
|
||||
}
|
||||
})
|
||||
|
||||
it('keeps accumulated streamed text when the turn is cut short before a full message', async () => {
|
||||
// The fake streams one text-delta chunk and then violates the protocol on
|
||||
// the same pipe; frame order guarantees the chunk was dispatched before
|
||||
// the failure settles, so the accumulated partial text (no complete
|
||||
// assistant/message ever arrived) must survive into the error result.
|
||||
it('does not attribute streamed text when prompt acceptance is malformed', async () => {
|
||||
// The fake streams one text-delta chunk but never returns the MessageId
|
||||
// needed to establish this run's durable inbox receipt. The text therefore
|
||||
// lies outside an owned activity interval and cannot become its output.
|
||||
const ctx = await setup({ FAKE_STREAM_THEN_MALFORMED: '1' }, { shutdownTimeoutMs: 100, disposeEofGraceMs: 200, disposeGraceMs: 200 })
|
||||
const run = await ctx.subagents.start('dsh-sdk', request())
|
||||
const result = await run.result
|
||||
expect(result.stopReason).toBe('error')
|
||||
expect(text(result.output)).toBe('streamed then cut short')
|
||||
expect(result.output).toEqual([])
|
||||
await run.dispose()
|
||||
await ctx.fiber.dispose()
|
||||
})
|
||||
|
||||
@@ -3,4 +3,4 @@
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write packages/subagent/subagent-fork/README.md
|
||||
README.md: 55475aee7841e91960de79887dfe9bf37afdf9da
|
||||
README.zh.md: 3eec8cb51a47243a1f06416a3f8f99ae8df8e734
|
||||
README.zh.md: ef9e4b256931450c0b8664dcc640e000f01c01da
|
||||
|
||||
@@ -31,7 +31,7 @@ fork 声明 `{ outputSchema: true, depthLimit: true, toolFilter: true, persona:
|
||||
|
||||
#### 模型看到的内容
|
||||
|
||||
子 agent 先接收父 agent 已配平的完整轮次表层前缀，再逐字接收新的任务内容。配置的 persona 会在子 agent 的全新作用域中遮蔽提示词文本；工具限制会过滤其全局协议 schema、可执行工具查找和 Code Mode SDK 绑定，但不影响独立的指导内容。父 agent 的工具视图与权限不会被继承。可选的结构化输出请求会添加仅属于子 agent 的契约。父 agent 当前进行中的轮次会被排除。
|
||||
子 agent 先接收由父 agent 已配平的已完成轮次构成的表层前缀，再逐字接收新的任务内容。配置的 persona 会在子 agent 的全新作用域中遮蔽提示词文本；工具限制会过滤其全局协议 schema、可执行工具查找和 Code Mode SDK 绑定，但不影响独立的指导内容。父 agent 的工具视图与权限不会被继承。可选的结构化输出请求会添加仅属于子 agent 的契约。父 agent 当前进行中的轮次会被排除。
|
||||
|
||||
#### Token 影响
|
||||
|
||||
@@ -53,7 +53,7 @@ fork 会把保留的已完成历史复制到独立的子 agent 请求中；随
|
||||
|
||||
#### KV Cache 影响
|
||||
|
||||
仅追加；新增可见内容位于可复用请求前缀之后，不会使现有 KV-cache 条目失效。
|
||||
仅追加；新增可见内容位于可复用请求前缀之后，不会使现有 KV Cache 条目失效。
|
||||
|
||||
## 已知限制与暂缓事项
|
||||
|
||||
|
||||
@@ -21,9 +21,7 @@
|
||||
"files": [
|
||||
"lib/index.js",
|
||||
"lib/invariant.js",
|
||||
"lib/types/**/*.d.ts",
|
||||
"lib/types/**/*.d.ts.map",
|
||||
"src"
|
||||
"lib/types/**/*.d.ts"
|
||||
],
|
||||
"license": "BSD-3-Clause",
|
||||
"peerDependencies": {
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write packages/subagent/subagent-inprocess/README.md
|
||||
README.md: 61e5c8381fcd8972815129a8a2171fcf7d864113
|
||||
README.zh.md: 1caf43427229afcd7083f929adbaa083a1d1ac2e
|
||||
README.md: 67f0cf5dd1ecb18542af56953a0eaa40988aca0d
|
||||
README.zh.md: 7536d265584f1f6c69027cda6bc4d81ad88b7c7c
|
||||
|
||||
@@ -2,28 +2,31 @@
|
||||
|
||||
English | [中文](README.zh.md)
|
||||
|
||||
This package is the shared run driver for the two in-process providers' one-shot delegations. Spawn passes no session seed; fork passes the parent's completed-turn prefix. Everything else—depth, child creation, optional child customization, result reading, cancellation, and disposal—has one implementation here. Continuable children never come through this driver: the continuation manager in `@deepseek-ai/dsh-subagent` composes and drives them directly, so this driver owns exactly one turn with one result.
|
||||
This package is the shared run driver for the two in-process providers. Spawn passes no session seed; fork passes the parent's completed-turn prefix. Everything else—depth, child creation, optional child customization, result reading, cancellation, and disposal—has one implementation here.
|
||||
|
||||
## Start contract
|
||||
|
||||
`startInProcessRun(request, options): Promise<SubagentRun>` fulfills as soon as the child is published in `ctx.agents`. A rejected start has already quiesced the agent factory's unpublished creation transaction, while turn or infrastructure failures after publication settle through the returned run without hiding the child id.
|
||||
`startInProcessRun(request, options): Promise<SubagentRun>` fulfills only after the child is published in `ctx.agents`. A rejected start has already quiesced the agent factory's unpublished creation transaction, so the caller never receives a half-created handle.
|
||||
|
||||
The driver follows this sequence:
|
||||
|
||||
1. Validate the parent depth and optional absolute `maxDepth`, then derive child depth as parent depth plus one and persist it together with `origin: 'subagent'` in the child session header. Origin is a coarse product-navigation classifier; the later descriptor remains lifecycle and continuation authority.
|
||||
2. Mint a fresh child session id and call `parent.ctx.agents.create` directly, passing the optional fork seed and required request signal into the factory's creation transaction. During the unpublished setup window, install the requested persona, tool restriction, structured-output runtime, and a one-shot `agent/step` contribution that appends the resolved `subagent/descriptor` event after the initial `turn/start` and before the first request.
|
||||
3. Publish the child, retain the returned `AgentHandle`, and return its holder-owned run. The run's `result` drives one task with `child.followup(prompt)` followed by `child.whenIdle()`.
|
||||
4. Read the child's own last assistant message and latest message-triggered turn reason, excluding the fork seed prefix so a seeded parent message is never mistaken for child output.
|
||||
1. Validate the parent depth and optional absolute `maxDepth`, then derive child depth as parent depth plus one and persist it in the child session header.
|
||||
2. Call `parent.ctx.agents.create` directly, passing the required request signal into the factory's creation transaction.
|
||||
3. During that transaction's unpublished setup window, install the requested persona, tool restriction, and structured-output runtime.
|
||||
4. Publish the child, retain the returned `AgentHandle`, and drive one task with `child.followup(prompt)` followed by `child.whenIdle()`.
|
||||
5. Read the child's own last assistant message and final durable turn reason from the complete owned child run, excluding any fork seed.
|
||||
|
||||
The child gets the parent's working-directory/session lineage and inherits the parent provider, model, and output-token cap unless `request.agentOptions` overrides them. It gets a fresh flat registration scope: parent ownership does not import parent tool restrictions or establish an authority subset.
|
||||
|
||||
This result boundary is valid because the provider owns an isolated child lifecycle from publication through quiescence. Steering submitted during that lifecycle belongs to the child run; the provider does not pretend the initial follow-up alone owns its output.
|
||||
|
||||
When the optional sandbox-policy or approval service is composed, the driver snapshots the parent's explicit session override before child creation and appends a source-tagged event during unpublished setup, after any fork history and before session publication. It never copies deployment defaults or one-shot grants; later child switches still win. See the [policy-inheritance decision](../../../.agents/notes/implemented/feature/2026-07-25-subagent-policy-inheritance.md).
|
||||
|
||||
## Cancellation and ownership
|
||||
|
||||
The required request signal covers both startup and the live run. Before publication, `AgentCreationTransaction` observes it, rolls back, and rejects. The factory detaches that creation-only listener before returning; the published run immediately installs its own listener and checks the signal again, closing the handoff race. Once publication has occurred, an abort preserves the returned child id, prevents unsubmitted work, and resolves an incomplete result as `aborted`; an abort during the turn cancels the child.
|
||||
The required request signal covers both startup and the live run. Before publication, `AgentCreationTransaction` observes it, rolls back, and rejects. The factory detaches that creation-only listener before returning; the driver immediately checks the signal once more before installing a minimal live-run listener, closing the handoff race. After publication, abort cancels the child.
|
||||
|
||||
After fulfillment, the caller owns the run. Provider-plugin unload does not revoke it. `dispose()` removes the live abort listener, records cancellation, and awaits both `result` and the returned `AgentHandle.dispose()`; the handle's memoized quiescence transaction stops the loop, removes the agent and session, and unwinds scoped registrations. A result rejection remains on `result`; `dispose()` rejects only when handle disposal fails, after both operations settle. Cancellation owns every non-completed in-flight outcome and reports `aborted`; an already-completed turn remains completed.
|
||||
After fulfillment, the caller owns the run. Provider-plugin unload does not revoke it. `dispose()` removes the live abort listener, records cancellation, and delegates to the returned `AgentHandle.dispose()`, whose memoized quiescence transaction stops the loop, removes the agent and session, and unwinds scoped registrations. Cancellation owns every non-completed in-flight outcome and reports `aborted`; an already-completed turn remains completed.
|
||||
|
||||
## Spawn and fork inputs
|
||||
|
||||
@@ -109,4 +112,5 @@ Append-only; newly visible content follows the reusable request prefix and does
|
||||
|
||||
## Known Limitations and Deferred Work
|
||||
|
||||
- **Runs expose no `sendMessage`/`resume`** — the optional runtime capabilities are absent on in-process runs.
|
||||
- **Structured capture accepts the `defineTool` schema subset only** — unsupported JSON Schema constructs fail before the child is created; a provider needing a broader schema vocabulary requires a different runtime.
|
||||
|
||||
@@ -2,31 +2,35 @@
|
||||
|
||||
[English](README.md) | 中文
|
||||
|
||||
本包是两个进程内提供方一次性委派共用的运行驱动器。spawn 不传入会话初始内容；fork 传入父 agent（智能体）已完成轮次的前缀。其余机制，包括深度、子 agent 创建、可选的子 agent 定制、结果读取、取消和 dispose（资源释放），都在此共用同一套实现。可继续子 agent 绝不通过本驱动器：`@deepseek-ai/dsh-subagent` 中的继续执行管理器会直接组合并驱动它们，因此本驱动器只拥有一个轮次和一个结果。
|
||||
本包是两个进程内提供方共用的运行驱动器。spawn 不传入会话初始内容；fork 传入父 agent（智能体）已完成轮次的前缀。其余机制，包括深度、子 agent 创建、可选的子 agent 定制、结果读取、取消和 dispose（资源释放），都在此共用同一套实现。
|
||||
|
||||
## 启动契约
|
||||
|
||||
`startInProcessRun(request, options): Promise<SubagentRun>` 会在子 agent 发布到 `ctx.agents` 后立即兑现。启动被拒绝时，agent 工厂的未发布创建事务已经完全停稳；发布后的轮次或基础设施故障则通过返回的 run 结算，且不会隐藏 child id。
|
||||
`startInProcessRun(request, options): Promise<SubagentRun>` 只在子 agent 发布到 `ctx.agents` 后才兑现。启动被拒绝时，agent 工厂的未发布创建事务已经完全停稳，因此调用方绝不会收到创建到一半的句柄。
|
||||
|
||||
驱动器按以下顺序运行：
|
||||
|
||||
1. 校验父 agent 深度和可选的绝对 `maxDepth`，然后把子 agent 深度推导为父 agent 深度加一，并与 `origin: 'subagent'` 一同持久化到子 agent 会话 header。origin 是粗粒度产品导航分类器；后续描述符仍是生命周期与继续执行的权威依据。
|
||||
2. 生成全新的子 agent 会话 id，并直接调用 `parent.ctx.agents.create`，把可选的 fork 初始内容和必需的请求信号传入工厂的创建事务。在未发布的设置窗口中，安装请求的 persona、工具限制、结构化输出运行时，以及一次性的 `agent/step` contribution；该 contribution 会在初始 `turn/start` 之后、首次请求之前追加已解析的 `subagent/descriptor` 事件。
|
||||
3. 发布子 agent，保留返回的 `AgentHandle`，并返回由持有方拥有的 run。该 run 的 `result` 会通过先调用 `child.followup(prompt)`、再调用 `child.whenIdle()` 来驱动一项任务。
|
||||
4. 读取子 agent 自身最后一条 assistant 消息，以及由消息触发的最新轮次原因；排除 fork 初始内容前缀，确保作为初始内容的父 agent 消息绝不会被误认为子 agent 输出。
|
||||
1. 校验父 agent 深度和可选的绝对 `maxDepth`，然后把子 agent 深度推导为父 agent 深度加一，并将其持久化到子 agent 会话 header。
|
||||
2. 直接调用 `parent.ctx.agents.create`，把必需的请求信号传入工厂的创建事务。
|
||||
3. 在该事务未发布的设置窗口中，安装请求的 persona、工具限制和结构化输出运行时。
|
||||
4. 发布子 agent，保留返回的 `AgentHandle`，并通过先调用 `child.followup(prompt)`、再调用 `child.whenIdle()` 来驱动一项任务。
|
||||
5. 从完整的自有子运行中读取子 agent 自身最后一条 assistant 消息和最终持久轮次原因，并排除任何 fork 初始内容。
|
||||
|
||||
子 agent 会获得父 agent 的工作目录／会话谱系；除非 `request.agentOptions` 覆盖，否则还会继承父 agent 的提供方、模型和输出 token 上限。它获得全新的扁平注册作用域：父级所有权不会导入父 agent 的工具限制，也不会建立权限子集。
|
||||
|
||||
该结果边界成立，是因为提供方拥有从发布到完全停稳的隔离子 agent 生命周期。在该生命周期内提交的 steering（中途引导）属于子运行；提供方不会声称输出只归初始 follow-up 所有。
|
||||
|
||||
当组合中挂载了可选的沙箱策略或审批服务时，驱动器会在创建子 agent 前对父级的显式会话覆盖项获取快照，并在未发布的设置阶段追加一条带来源标记的事件，使其位于所有 fork 历史之后、会话发布之前。它绝不复制部署默认值或一次性授权；子 agent 后续的切换仍然优先。参见[策略继承决策](../../../.agents/notes/implemented/feature/2026-07-25-subagent-policy-inheritance.md)。
|
||||
|
||||
## 取消与所有权
|
||||
|
||||
必需的请求信号同时覆盖启动阶段和实时运行。发布前，`AgentCreationTransaction` 会观察该信号、回滚并拒绝。工厂返回前会移除仅用于创建阶段的监听器；已发布的 run 会立即安装自己的监听器并再次检查信号，从而消除交接竞态。一旦完成发布，中止会保留已返回的 child id、阻止尚未提交的工作，并以 `aborted` 兑现未完成的结果；轮次期间发生中止时，则会取消子 agent。
|
||||
必需的请求信号同时覆盖启动阶段和实时运行。发布前，`AgentCreationTransaction` 会观察该信号、回滚并拒绝。工厂返回前会移除仅用于创建阶段的监听器；驱动器随即再次检查信号，然后安装最小化的实时运行监听器，从而消除交接竞态。发布后，中止会取消子 agent。
|
||||
|
||||
兑现后，调用方拥有该运行。提供方插件卸载不会撤销它。`dispose()` 会移除实时中止监听器、记录取消，并同时等待 `result` 和返回的 `AgentHandle.dispose()`；该句柄通过可复用的完全停稳事务停止循环、移除 agent 和会话，并展开有作用域的注册。`result` 的 rejection 仍归 `result` 通道；只有句柄释放失败时，`dispose()` 才会在两项操作都结算后拒绝。取消决定所有尚未完成的进行中结果，并将其报告为 `aborted`；已经完成的轮次仍保持完成状态。
|
||||
兑现后，调用方拥有该运行。提供方插件卸载不会撤销它。`dispose()` 会移除实时中止监听器、记录取消，并委托给返回的 `AgentHandle.dispose()`；后者通过可复用的完全停稳事务停止循环、移除 agent 和会话，并展开有作用域的注册。取消决定所有尚未完成的进行中结果，并将其报告为 `aborted`；已经完成的轮次仍保持完成状态。
|
||||
|
||||
## Spawn 与 fork 输入
|
||||
## spawn 与 fork 输入
|
||||
|
||||
`InProcessRunOptions` 的形态为 `{ seed?: SessionEvent[] }`。spawn 省略该值。fork 提供平衡的已完成轮次前缀，并记录其长度，确保结果读取器不会把作为初始内容的父 agent 消息误认为子 agent 输出。
|
||||
`InProcessRunOptions` 的形态为 `{ seed?: SessionEvent[] }`。spawn 省略该值。fork 提供已配平的已完成轮次前缀，并记录其长度，确保结果读取器不会把作为初始内容的父 agent 消息误认为子 agent 输出。
|
||||
|
||||
深度强制在 `startInProcessRun` 内部完成：它通过 `delegationDepthOf` 读取父 agent 深度（持久化的 `SessionHeader.delegationDepth` 具有权威性；运行时 `AgentOptions.subagentDepth` 可以加深但绝不能降低该值，因此恢复后的子 agent 会保留预算），缺失值按顶层深度零处理，拒绝格式错误的存储值，并报告尝试的子 agent 深度超过 `maxDepth`。超过安全整数范围、无法表示的深度会触发 `RangeError`。子 agent 深度写入子 agent header，因此会在持久化和恢复后保留。
|
||||
|
||||
@@ -72,7 +76,7 @@ When you have your final answer, you MUST report it by calling the `structured_o
|
||||
|
||||
#### Token 影响
|
||||
|
||||
固定指令和能力 token 仅由该子 agent 支付。结果文本进入子 agent 历史，而只有捕获的值会成为父 agent 结果。
|
||||
固定指令和能力产生的 token 开销仅由该子 agent 承担。结果文本进入子 agent 历史，而只有捕获的值会成为父 agent 结果。
|
||||
|
||||
#### KV Cache 影响
|
||||
|
||||
@@ -90,7 +94,7 @@ When you have your final answer, you MUST report it by calling the `structured_o
|
||||
|
||||
#### KV Cache 影响
|
||||
|
||||
仅追加；新增可见内容位于可复用请求前缀之后，不会使现有 KV-cache 条目失效。
|
||||
仅追加；新增可见内容位于可复用请求前缀之后，不会使现有 KV Cache 条目失效。
|
||||
|
||||
### 父 agent 结果（间接）
|
||||
|
||||
@@ -104,8 +108,9 @@ When you have your final answer, you MUST report it by calling the `structured_o
|
||||
|
||||
#### KV Cache 影响
|
||||
|
||||
仅追加；新增可见内容位于可复用请求前缀之后，不会使现有 KV-cache 条目失效。
|
||||
仅追加；新增可见内容位于可复用请求前缀之后，不会使现有 KV Cache 条目失效。
|
||||
|
||||
## 已知限制与延期工作
|
||||
## 已知限制与暂缓事项
|
||||
|
||||
- **运行不公开 `sendMessage`/`resume`**：进程内运行不具备这些可选运行时能力。
|
||||
- **结构化捕获只接受 `defineTool` schema 子集**：不支持的 JSON Schema 构造会在子 agent 创建前失败；需要更广 schema 词汇的提供方必须采用不同的运行时。
|
||||
|
||||
@@ -21,9 +21,7 @@
|
||||
"files": [
|
||||
"lib/index.js",
|
||||
"lib/invariant.js",
|
||||
"lib/types/**/*.d.ts",
|
||||
"lib/types/**/*.d.ts.map",
|
||||
"src"
|
||||
"lib/types/**/*.d.ts"
|
||||
],
|
||||
"license": "BSD-3-Clause",
|
||||
"peerDependencies": {
|
||||
|
||||
@@ -55,7 +55,6 @@ function toStopReason(reason: TurnEndReason | undefined): SubagentStopReason {
|
||||
case 'aborted':
|
||||
return 'aborted'
|
||||
case 'error':
|
||||
case 'disposed':
|
||||
case 'interrupted':
|
||||
default:
|
||||
return 'error'
|
||||
@@ -76,10 +75,13 @@ function prePublicationAbort(): Error {
|
||||
/** Append one one-shot descriptor inside the child's initial turn before its first request. */
|
||||
function attachDescriptorAppend(childCtx: Context, descriptor: SubagentDescriptorData): void {
|
||||
let appended = false
|
||||
childCtx.on('agent/step', (agent) => {
|
||||
if (appended) return
|
||||
appended = true
|
||||
agent.session.append('subagent/descriptor', descriptor)
|
||||
childCtx.on('agent/pre-step', async ({ agent }, next) => {
|
||||
const decision = await next()
|
||||
if (!appended && decision.kind === 'enter') {
|
||||
appended = true
|
||||
agent.session.append('subagent/descriptor', descriptor)
|
||||
}
|
||||
return decision
|
||||
})
|
||||
}
|
||||
|
||||
|
||||
@@ -92,7 +92,7 @@ describe('startInProcessRun', () => {
|
||||
|
||||
const run = await startInProcessRun(request(parent), {})
|
||||
await expect(run.result).resolves.toMatchObject({ stopReason: 'completed' })
|
||||
expect(flushes).toBe(1)
|
||||
expect(flushes).toBe(0)
|
||||
await run.dispose()
|
||||
})
|
||||
|
||||
@@ -130,7 +130,7 @@ describe('startInProcessRun', () => {
|
||||
expect(ctx.agents.list()).toHaveLength(beforeAgents)
|
||||
expect(ctx.sessions.list()).toHaveLength(beforeSessions)
|
||||
})
|
||||
it('reports the message-turn outcome when a later non-message turn completes during flush', async () => {
|
||||
it('reports the turn outcome when later metadata is appended during flush', async () => {
|
||||
const { ctx, parent } = await setup([maxTokensResponse('partial answer')])
|
||||
let injected = false
|
||||
ctx.on('session/flush', (session) => {
|
||||
@@ -138,25 +138,19 @@ describe('startInProcessRun', () => {
|
||||
const lastEnd = session.events.findLast(event => event.type === 'turn/end')
|
||||
if (lastEnd?.type !== 'turn/end' || lastEnd.data.reason.kind !== 'max-tokens') return
|
||||
injected = true
|
||||
const turn = lastEnd.data.turn + 1
|
||||
session.append('turn/start', {
|
||||
turn,
|
||||
trigger: { kind: 'injection', source: { kind: 'plugin', plugin: 'late-metadata' } },
|
||||
})
|
||||
session.append('user/message', createUserMessage({
|
||||
content: [{ type: 'text', text: 'late metadata' }],
|
||||
source: { kind: 'plugin', plugin: 'late-metadata' },
|
||||
}), { surfaceOp: 'append' })
|
||||
session.append('turn/end', { turn, reason: { kind: 'completed' } })
|
||||
})
|
||||
|
||||
const run = await startInProcessRun(request(parent), {})
|
||||
const result = await run.result
|
||||
const child = ctx.agents.get(run.id)!
|
||||
|
||||
expect(injected).toBe(true)
|
||||
expect(injected).toBe(false)
|
||||
expect(child.session.events.findLast(event => event.type === 'turn/end'))
|
||||
.toMatchObject({ data: { reason: { kind: 'completed' } } })
|
||||
.toMatchObject({ data: { reason: { kind: 'max-tokens' } } })
|
||||
expect(result.stopReason).toBe('max-tokens')
|
||||
await run.dispose()
|
||||
})
|
||||
@@ -288,7 +282,7 @@ describe('startInProcessRun', () => {
|
||||
expect(adapter.requests[0]?.signal?.reason).toEqual({ kind: 'parent' })
|
||||
const child = parent.ctx.agents.get(signalled.id)
|
||||
const turnEnd = child?.session.events.findLast(event => event.type === 'turn/end')
|
||||
expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toEqual({ kind: 'aborted' })
|
||||
expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toEqual({ kind: 'aborted', reason: { kind: 'parent' } })
|
||||
await signalled.dispose()
|
||||
|
||||
const disposed = await startInProcessRun(request(parent), {})
|
||||
|
||||
@@ -3,4 +3,4 @@
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write packages/subagent/subagent-spawn/README.md
|
||||
README.md: 811f19e6e68362bd14e75d0a9059ee61fda3f015
|
||||
README.zh.md: 2b189f77c4ff63ca026f472187a55c68def18ea1
|
||||
README.zh.md: 2736143214039daa3129fd114d4294dc5fcb7d5e
|
||||
|
||||
@@ -26,7 +26,7 @@ spawn 声明 `{ outputSchema: true, depthLimit: true, toolFilter: true, persona:
|
||||
|
||||
#### 模型看到的内容
|
||||
|
||||
全新的子 agent 逐字接收独立任务内容，默认继承父 agent 的模型和工作区，并看到带有已配置子 agent 作用域 persona 遮蔽的全局提示词。工具过滤器会为该子 agent 移除全局协议 schema、可执行工具查找和 Code Mode SDK 绑定，但保留独立注册的指导内容。它不接收任何父 agent 对话消息；过滤控制的是可见性与组合，并非从父 agent 继承的权限授权。
|
||||
全新的子 agent 逐字接收独立任务内容，默认继承父 agent 的模型和工作区，并看到带有已配置子 agent 作用域 persona 遮蔽的全局提示词。工具过滤器会为该子 agent 移除全局协议 schema、可执行工具查找和 Code Mode SDK 绑定，但保留独立注册的指导内容。它不接收任何父 agent 对话消息；过滤控制的是可见性与组合，并非从父 agent 继承的权限授予。
|
||||
|
||||
#### Token 影响
|
||||
|
||||
@@ -44,11 +44,11 @@ spawn 声明 `{ outputSchema: true, depthLimit: true, toolFilter: true, persona:
|
||||
|
||||
#### Token 影响
|
||||
|
||||
父 agent 输入增加一个依赖数据的结果，并保留到上下文压缩（compaction）为止。
|
||||
父 agent 输入会增加一个取决于数据的结果，并保留到压缩（compaction）为止。
|
||||
|
||||
#### KV Cache 影响
|
||||
|
||||
仅追加；新增可见内容位于可复用请求前缀之后，不会使现有 KV-cache 条目失效。
|
||||
仅追加；新增可见内容位于可复用请求前缀之后，不会使现有 KV Cache 条目失效。
|
||||
|
||||
## 已知限制与暂缓事项
|
||||
|
||||
|
||||
@@ -21,9 +21,7 @@
|
||||
"files": [
|
||||
"lib/index.js",
|
||||
"lib/invariant.js",
|
||||
"lib/types/**/*.d.ts",
|
||||
"lib/types/**/*.d.ts.map",
|
||||
"src"
|
||||
"lib/types/**/*.d.ts"
|
||||
],
|
||||
"license": "BSD-3-Clause",
|
||||
"peerDependencies": {
|
||||
|
||||
@@ -42,7 +42,7 @@ export async function spawnHarness(workdir: string): Promise<Context> {
|
||||
|
||||
export function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
|
||||
return new Promise((resolve) => {
|
||||
const dispose = ctx.on('agent/status', (subject, status) => {
|
||||
const dispose = ctx.on('agent/status', ({ agent: subject, status }) => {
|
||||
if (subject === agent && status === 'idle') {
|
||||
dispose()
|
||||
resolve()
|
||||
|
||||
@@ -200,18 +200,6 @@ describe('dsh-subagent-spawn', () => {
|
||||
expect(published).toEqual([])
|
||||
})
|
||||
|
||||
it('a cancel from agent/inbox/enqueue maps a no-turn child log to aborted', async () => {
|
||||
const { ctx, parent } = await setup([])
|
||||
const controller = new AbortController()
|
||||
ctx.on('agent/inbox/enqueue', () => { controller.abort('queued-window') })
|
||||
const run = await start(ctx, 'spawn', { prompt: [{ type: 'text', text: 'p' }], parent, signal: controller.signal })
|
||||
const result = await run.result
|
||||
expect(result).toMatchObject({ stopReason: 'aborted', output: [] })
|
||||
const child = ctx.agents.get(run.id)!
|
||||
expect(child.session.events.some(event => event.type === 'turn/end')).toBe(false)
|
||||
await run.dispose()
|
||||
})
|
||||
|
||||
it('cancelling a running child settles the run as aborted (the abort bridge + cancel())', async () => {
|
||||
// 'hang' makes the child's model stream one chunk then wait until aborted.
|
||||
const controller = new AbortController()
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write packages/subagent/subagent/README.md
|
||||
README.md: a388f5a57fd32768dc9b66e3637ff53bf6479149
|
||||
README.zh.md: 48e5694e82ee0269661fbb5ede75cf995cbc00aa
|
||||
README.md: 08b6175e018db072b99490a25b8df887bb89eb47
|
||||
README.zh.md: 435be7660b3f004a1f0bcb59a8d9a74ac8e8aae3
|
||||
|
||||
@@ -4,24 +4,7 @@ English | [中文](README.zh.md)
|
||||
|
||||
The subagent seam lets one agent delegate work to a child through a named provider. Callers use one service API (`ctx.subagents`); providers decide whether the child runs in this process, in another process, or through a future transport.
|
||||
|
||||
## Package roles
|
||||
|
||||
The family separates the stable interface from implementations and model-facing tools:
|
||||
|
||||
| Package | Role |
|
||||
|---|---|
|
||||
| `@deepseek-ai/dsh-subagent` | Provider registry, request/result/descriptor types, lifecycle events, and continuable-child orchestration. |
|
||||
| `@deepseek-ai/dsh-subagent-spawn` | Fresh in-process child; supports continuable children. |
|
||||
| `@deepseek-ai/dsh-subagent-fork` | In-process child seeded with completed parent turns; supports continuable children. |
|
||||
| `@deepseek-ai/dsh-subagent-acp` | Fresh out-of-process ACP child (one-shot). |
|
||||
| `@deepseek-ai/dsh-subagent-codex` | Fresh real Codex app-server child with one ephemeral thread and turn (one-shot). |
|
||||
| `@deepseek-ai/dsh-subagent-claude-code` | Fresh official Claude Agent SDK query with a real managed Claude Code CLI child (one-shot). |
|
||||
| `@deepseek-ai/dsh-subagent-dsh-sdk` | Fresh out-of-process harness child driven through the TypeScript SDK client (one-shot). |
|
||||
| `@deepseek-ai/dsh-tool-subagent` | Model-facing delegation tool over one configured provider. |
|
||||
| `@deepseek-ai/dsh-tool-subagent-control` | The globally named `send_message` follow-up tool. |
|
||||
| `@deepseek-ai/dsh-tool-subagent-report` | Child-scoped return channel to the direct parent. |
|
||||
|
||||
Multiple providers may coexist under different names. This lets a deployment expose, for example, a cheap in-process child and an isolated ACP child without changing the service contract.
|
||||
The [subagent family overview](../README.md) maps implementations and model-facing consumers. This package owns the provider registry, shared request and result contracts, durable descriptors, and continuable-child orchestration. Multiple named providers may coexist behind that contract.
|
||||
|
||||
## Service API
|
||||
|
||||
|
||||
@@ -4,24 +4,7 @@
|
||||
|
||||
subagent seam 允许一个 agent（智能体）通过具名提供方把工作委派给子 agent。调用方使用统一的服务 API（`ctx.subagents`）；提供方决定子 agent 在当前进程、另一进程还是未来的传输之上运行。
|
||||
|
||||
## 包角色
|
||||
|
||||
该能力族把稳定接口与实现、面向模型的工具分开：
|
||||
|
||||
| 包 | 角色 |
|
||||
|---|---|
|
||||
| `@deepseek-ai/dsh-subagent` | 提供方注册表、请求／结果／描述符类型、生命周期事件和可继续子 agent 编排。 |
|
||||
| `@deepseek-ai/dsh-subagent-spawn` | 全新的进程内子 agent；支持可继续子 agent。 |
|
||||
| `@deepseek-ai/dsh-subagent-fork` | 以父 agent 已完成轮次作为初始内容的进程内子 agent；支持可继续子 agent。 |
|
||||
| `@deepseek-ai/dsh-subagent-acp` | 全新的进程外 ACP（Agent Client Protocol）子 agent（一次性）。 |
|
||||
| `@deepseek-ai/dsh-subagent-codex` | 全新的真实 Codex app-server 子 agent，包含一个临时 thread 和一个轮次（一次性）。 |
|
||||
| `@deepseek-ai/dsh-subagent-claude-code` | 通过官方 Claude Agent SDK 启动的全新 query，带有一个真实且受管的 Claude Code CLI 子进程（一次性）。 |
|
||||
| `@deepseek-ai/dsh-subagent-dsh-sdk` | 通过 TypeScript SDK 客户端驱动的全新进程外 harness 子 agent（一次性）。 |
|
||||
| `@deepseek-ai/dsh-tool-subagent` | 基于一个已配置提供方、面向模型的委派工具。 |
|
||||
| `@deepseek-ai/dsh-tool-subagent-control` | 全局具名 `send_message` 后续操作工具。 |
|
||||
| `@deepseek-ai/dsh-tool-subagent-report` | 子级作用域的返回通道，指向直接父级。 |
|
||||
|
||||
多个提供方可以使用不同名称共存。因此，部署可以同时公开低成本的进程内子 agent 和隔离的 ACP 子 agent，而无需改变服务契约。
|
||||
[subagent 家族概述](../README.md)列出了实现和面向模型的消费方。本包负责提供方注册表、共享请求和结果契约、持久描述符以及可继续子级编排。多个具名提供方可以在该契约背后共存。
|
||||
|
||||
## 服务 API
|
||||
|
||||
@@ -29,7 +12,7 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
|
||||
|
||||
| 成员 | 含义 |
|
||||
|---|---|
|
||||
| `registerProvider(provider)` | 按名称注册一个可信的同进程实现。注册受 effect 作用域约束；移除注册会阻止新的启动，但不会撤销已返回给调用方的运行。重复名称会立即失败。 |
|
||||
| `registerProvider(provider)` | 按名称注册一个可信的同进程实现。注册受 effect 作用域约束；移除注册会阻止新的启动，但不会撤销已返回给调用方的运行。重复名称会明确报错。 |
|
||||
| `getProvider(name)` | 返回提供方；不存在时返回 `undefined`。 |
|
||||
| `list()` | 按插入顺序返回提供方名称。 |
|
||||
| `start(name, request)` | 校验普通调用方请求，解析其分离的 `one-shot` 描述符，然后等待提供方，直到真实的一次性子 agent 发布。兑现时返回由持有方拥有的 `SubagentRun`；拒绝表示提供方已清理所有未发布的启动资源，而发布后的轮次或基础设施故障会通过该 run 结算。可继续子 agent 绝不通过此操作进入。 |
|
||||
@@ -40,7 +23,7 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
|
||||
| `drainContinuableDescendants(parents)` | 在由 host 确切拥有的在线 parent Agent 之下关闭准入，只停止其可见的可继续后代，等待在这些根之下已获准的物化过程完成发布或回滚，再按 child-first 顺序释放所选森林。该截止状态会持续到每个确切 parent 离开注册表；无关的 parent 森林和管理器全局准入保持在线。 |
|
||||
| `listChildren(parentSessionId, signal?)` | 按稳定的追踪顺序列出由会话支撑的直接 subagent，包括其 `one-shot`／`continuable` 模式、`running`／`inactive` 活动状态、基于 origin 分类的一层 `hasChildren` 提示与逐 child diagnostic，且不会加载或恢复它们。要求会话查询；不要求 `ctx.agents` 或继续执行管理器。 |
|
||||
|
||||
`SubagentStartRequest.label` 是由会话支撑的一次性 child 所使用的可选简短持久化显示标签。面向模型的委派会提供其已有的 `description`；底层调用方无需凭空构造展示元数据。可继续启动始终携带自身的必填标签。`signal` 是必填项，也是一次性 `start` 的规范取消通道。发布前中止会使 `start()` 在回滚后拒绝；发布后中止会取消已返回 run 的剩余轮次工作，但不会隐藏其 id。请求还可以选择模型、要求结构化输出、限制委派深度、约束子 agent 工具或设置子 agent persona。对于可继续启动或后续操作，调用方信号只在 inbox 接受之前掌管查找、物化和准入；此后由管理器独立拥有 Activation，因此调用方后续取消既不会取消已接受的轮次，也不会 dispose 子 agent。
|
||||
`SubagentStartRequest.label` 是由会话支撑的一次性 child 所使用的可选简短持久化显示标签。面向模型的委派会提供其已有的 `description`；底层调用方无需凭空构造展示元数据。可继续启动始终携带自身的必填标签。`signal` 是必填项，也是一次性 `start` 的规范取消通道。发布前中止会使 `start()` 在回滚后拒绝；发布后中止会取消已返回 run 的剩余轮次工作，但不会隐藏其 id。请求还可以选择模型、要求结构化输出、限制委派深度、约束子 agent 工具或设置子 agent persona。对于可继续启动或后续操作，调用方信号只在 inbox 接受之前掌管查找、物化和准入；此后由管理器独立拥有 Activation，因此调用方后续取消既不会取消已接受的轮次，也不会 dispose（资源释放）子 agent。
|
||||
|
||||
后续操作的权限来自子 agent 持久化 header 中记录的确切在线直接父级。冷恢复会在重建前检查该权限，并在最终无 await 的 inbox 准入区间再次检查，因此在物化期间被注销或替换的 parent 无法授权投递。后续操作上的 `source` 是保留在所投递消息上的持久化来源，不授予任何权限。
|
||||
|
||||
@@ -59,7 +42,7 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
|
||||
|
||||
## 持久化描述符
|
||||
|
||||
该 seam 拥有版本化的 `subagent/descriptor` 会话事件词汇（`src/descriptor.ts`）：`snapshotSubagentDescriptor()` 会在提供方工作之前校验并分离记录，`foldSubagentDescriptor()` 则会在从已加载子 agent 日志中恢复描述符之前，校验当前版本的完整 payload。每次由本地会话支撑的启动都会追加一个带有提供方名称与生命周期 `mode` 的描述符。`one-shot` 描述符可以携带调用方拥有的可选持久化显示 `label`；`continuable` 描述符要求其持久化创建标签，并另外记录已解析的子 agent `agentOptions.provider`／`model`，以及用于从持久化存储恢复的可选 `persona`／`toolFilter`。这些是显式字段，绝不是可通过合并扩展的 `AgentOptions` 对象，因此无关的扩展值不会破坏继续执行。描述符省略 `subagentDepth`（持久化 header 的 `delegationDepth` 是单调下界）和 `outputSchema`（单次 Activation 的结果契约）。该事件只进入日志：不含 `surfaceOp`，不进入模型历史，并由仅追加日志跨压缩保留。格式错误的当前版本 payload 属于损坏；本运行时无法对不受支持的版本进行分类。
|
||||
该 seam 拥有版本化的 `subagent/descriptor` 会话事件词汇（`src/descriptor.ts`）：`snapshotSubagentDescriptor()` 会在提供方工作之前校验并分离记录，`foldSubagentDescriptor()` 则会在从已加载子 agent 日志中恢复描述符之前，校验当前版本的完整 payload。每次由本地会话支撑的启动都会追加一个带有提供方名称与生命周期 `mode` 的描述符。`one-shot` 描述符可以携带调用方拥有的可选持久化显示 `label`；`continuable` 描述符要求其持久化创建标签，并另外记录已解析的子 agent `agentOptions.provider`／`model`，以及用于从持久化存储恢复的可选 `persona`／`toolFilter`。这些是显式字段，绝不是可通过合并扩展的 `AgentOptions` 对象，因此无关的扩展值不会破坏继续执行。描述符省略 `subagentDepth`（持久化 header 的 `delegationDepth` 是单调下界）和 `outputSchema`（单次 Activation 的结果契约）。该事件只进入日志：不含 `surfaceOp`，不进入模型历史，并由仅追加日志跨压缩（compaction）保留。格式错误的当前版本 payload 属于损坏；本运行时无法对不受支持的版本进行分类。
|
||||
|
||||
## 委派深度
|
||||
|
||||
@@ -77,9 +60,9 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
|
||||
|
||||
## 可继续子 agent 与 Activation
|
||||
|
||||
可继续子 agent 拥有一个持久化 Session 和至多一个进程内 **Activation**——即被重建的子 agent 的一个驻留时段，而不是请求、结果、取消或 Task 边界。Agent inbox 是唯一的轮次队列，因此继续执行管理器负责驻留，而 Agent 循环负责所有轮次排序与执行。任何可继续路径都不会创建 Task 或中间的承载结果的包装器。
|
||||
可继续子 agent 拥有一个持久化 Session 和至多一个进程内 **Activation**——即被重建的子 agent 的一个驻留时段，而不是请求、结果、取消或 Task 边界。Agent inbox 是唯一的轮次队列，因此继续执行管理器负责驻留，而 agent loop（智能体循环）负责所有轮次排序与执行。任何可继续路径都不会创建 Task 或中间的承载结果的包装层。
|
||||
|
||||
管理器根据 Agent 停稳状态和所拥有子集推导三个内部驻留条件，而非维护第二个状态机：running（存在活跃准入、进行中的轮次或唤醒型 inbox 工作）、waiting（已停稳但仍拥有至少一个未 dispose 的子 agent）、settled（已停稳且所有拥有的子 agent 都已 dispose，因此管理器 dispose `AgentHandle` 并移除 Activation）。每条后续消息都使用 `Agent.followup()` 并成为一个 FIFO 轮次，且不会对当前轮次进行 steering（中途引导）。路由只取决于驻留状态：running 入队、waiting 唤醒同一 Agent，无 Activation 时则冷恢复一个新的。
|
||||
管理器根据 Agent 停稳状态和所拥有的子 agent 集合推导三个内部驻留条件，而非维护第二个状态机：running（存在活跃准入、进行中的轮次或唤醒型 inbox 工作）、waiting（已停稳但仍拥有至少一个未 dispose 的子 agent）、settled（已停稳且所有拥有的子 agent 都已 dispose，因此管理器 dispose `AgentHandle` 并移除 Activation）。每条后续消息都使用 `Agent.followup()` 并成为一个 FIFO 轮次，且不会对当前轮次进行 steering（中途引导）。路由只取决于驻留状态：running 入队、waiting 唤醒同一 Agent，无 Activation 时则冷恢复一个新的。
|
||||
|
||||
管理器预留子 agent 身份、解析持久化描述符，通过私有的 activation-owner 作用域调用 `ctx.agents.create()`（冷恢复时为 `ctx.agents.resume()`），把返回的 `AgentHandle` 安装到 Activation 中，建立任何可继续父级所有权，然后提交提示词。冷恢复绝不通过提供方分发，因为持久化 Session 已持有初始前缀，折叠后的描述符即是全部重建输入。
|
||||
|
||||
@@ -87,17 +70,17 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
|
||||
|
||||
## 生命周期事件
|
||||
|
||||
服务会为每次一次性运行以及每个已驻留的可继续 Activation 时段发出一对 `subagent/start`/`subagent/end`，因此可继续子 agent 可用与一次性运行相同的词汇观察，且不会暴露管理器是物化、唤醒还是冷恢复了它们。对于一次性启动，它会在同步的 `subagent/start` 之前附加结果观察器，因此即使子 agent 已经结算，也仍会先产生 `subagent/start`，再产生 `subagent/end`；在驻留前失败的可继续时段不发出任何事件。这对事件共享服务生成的 `runId`；`local` 标志取自提供方准确 `localAgent` 的快照（可继续子 agent 恒为 true），因此观察器绝不会从可复用的提供方/会话名称推断运行身份或本地性。`provider` 字段是生命周期来源信息，而非提供方仍在注册的声明：已接受的一次性 run 可在提供方移除后才结算，冷恢复时段也会保留描述符中的初始提供方名称，而不要求该提供方仍处于注册状态。
|
||||
服务会为每次一次性运行以及每个已驻留的可继续 Activation 时段发出一对 `subagent/start`/`subagent/end`，因此可继续子 agent 可用与一次性运行相同的词汇观察，且不会暴露管理器是物化、唤醒还是冷恢复了它们。对于一次性启动，它会在同步的 `subagent/start` 之前附加结果观察器，因此即使子 agent 已经结算，也仍会先产生 `subagent/start`，再产生 `subagent/end`；在驻留前失败的可继续时段不会发出这对生命周期事件中的任何一个。这对事件共享服务生成的 `runId`；`local` 标志取自提供方准确 `localAgent` 的快照（可继续子 agent 恒为 true），因此观察器绝不会从可复用的提供方/会话名称推断运行身份或本地性。`provider` 字段是生命周期来源信息，而非提供方仍在注册的声明：已接受的一次性 run 可在提供方移除后才结算，冷恢复时段也会保留描述符中的初始提供方名称，而不要求该提供方仍处于注册状态。
|
||||
|
||||
运行事件受执行委派的父级作用域约束。每个监听器都独立隔离：同步抛出或返回的 promise 被拒绝时，只会记录日志，不会阻塞同级监听器或改变运行。
|
||||
|
||||
提供方新增和移除还会发出 `subagent/provider-added` 与 `subagent/provider-removed`。面向模型的工具等消费方使用这些事件，因为 Cordis 可能并发加载同级插件；配置顺序不能证明注册顺序。
|
||||
|
||||
可继续子级不会创建 `SubagentRun` 或 Task。延续管理器为每个驻留子 Session 直接拥有一个仅存在于当前进程的 Activation 和一个留存的 `AgentHandle`，使用 Agent inbox 作为唯一 FIFO，并从持久化描述符冷恢复。父到子投递由准确的实时直接父级身份授权。上报则由准确的实时子级身份授权；管理器根据持久化的 `parentSession` 推导接收方，`MessageSource` 仍只表示来源，不表示权限。
|
||||
可继续子级不会创建 `SubagentRun` 或 Task。继续执行管理器为每个驻留子 Session 直接拥有一个仅存在于当前进程的 Activation 和一个留存的 `AgentHandle`，使用 Agent inbox 作为唯一 FIFO，并从持久化描述符冷恢复。父到子投递由确切在线的直接父级身份授权。上报则由确切在线的子级身份授权；管理器根据持久化的 `parentSession` 推导接收方，`MessageSource` 仍只表示来源，不表示权限。
|
||||
|
||||
当 `ctx.sessionProjections` 可用时，服务会注册 `subagentTiming`。该投影会在每个描述符处重置，使 fork 种子中的祖先工作不会计入 child 总量，随后累加 `turn/start` → `turn/end` 活跃时间，并为未结束的轮次保留同一切面的 `active.since` 和 `active.through` 边界。在该轮次保持未结束期间，`active.through` 会跟随最近折叠的事件，从而为 inactive 消费方提供保守的崩溃上界，又不会混入更新的会话元数据。
|
||||
|
||||
`registerContinuableSetup()` 允许可选包添加子级作用域功能，而无需让延续管理器知道这些功能的名称。贡献会在 Activation 发布前同步安装，在设置失败时一并回滚，并随子级作用域释放。新授权须等到下一个 Activation，移除贡献则会立即撤销每个驻留安装项。
|
||||
`registerContinuableSetup()` 允许可选包添加子级作用域能力，而无需让继续执行管理器知道这些能力的名称。贡献会在 Activation 发布前同步安装，在设置失败时一并回滚，并随子级作用域释放。新授权须等到下一个 Activation，移除贡献则会立即撤销每个驻留安装项。
|
||||
|
||||
## 收集模型
|
||||
|
||||
@@ -113,9 +96,9 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
|
||||
|
||||
不会直接使缓存失效；具名消费方共同负责请求前缀的任何变化。
|
||||
|
||||
## 已知限制与延期工作
|
||||
## 已知限制与暂缓事项
|
||||
|
||||
- **ACP 子 agent 仍为一次性，且无法通过追踪枚举**：ACP 运行在 parent 会话语料中没有本地 child 会话。ACP 的 `prepareContinuable` 需要在提供方专用描述符数据中持久化远端会话 id，并按子 agent 声明继续执行功能，因为 ACP 的 `loadSession` 支持按子 agent 协商，而不是通过方法是否存在来确定。远程提供方还需要一份独立的 Activation 所有权契约，具备等效的经认证控制和子先于父的停稳保证，才能支持可继续子 agent。
|
||||
- **ACP 子 agent 仍为一次性，且无法通过追踪枚举**：ACP 运行在 parent 会话语料中没有本地 child 会话。ACP 的 `prepareContinuable` 需要在提供方专用描述符数据中持久化远端会话 id，以及逐子 agent 的继续执行能力声明，因为 ACP 的 `loadSession` 支持按子 agent 协商，而不是通过方法是否存在来确定。远程提供方还需要一份独立的 Activation 所有权契约，具备等效的经认证控制和子先于父的停稳保证，才能支持可继续子 agent。
|
||||
- **无 host-user 继续执行**：`followup()` 要求确切在线直接父级。未来 host 适配器需要具体的经认证交互，才能让该 seam 获得单独的用户能力。
|
||||
- **不对当前轮次进行 steering**：可继续消息和唤醒式 report 会排入后续轮次，均不会重定向正在进行的轮次。
|
||||
- **驻留仅限进程内**：Activation inbox 与所有权图不会在两个 harness 进程之间协调；对单个持久化存储的并发访问仍然需要持久化邮箱和跨进程租约协议。
|
||||
|
||||
@@ -26,9 +26,7 @@
|
||||
"lib/index.js",
|
||||
"lib/invariant.js",
|
||||
"lib/types/**/*.js",
|
||||
"lib/types/**/*.d.ts",
|
||||
"lib/types/**/*.d.ts.map",
|
||||
"src"
|
||||
"lib/types/**/*.d.ts"
|
||||
],
|
||||
"license": "BSD-3-Clause",
|
||||
"dependencies": {
|
||||
|
||||
@@ -47,6 +47,8 @@ import type SubagentActivationSetupRegistry from './activation-setup-registry.ts
|
||||
/** Attribution for a model coordinator's follow-up to one of its children. */
|
||||
export interface CoordinatorMessageSource {
|
||||
readonly kind: 'coordinator'
|
||||
/** A message another agent addressed to this one (`relay` context form). */
|
||||
readonly form: 'relay'
|
||||
/** Session id of the agent whose tool call produced the follow-up. */
|
||||
readonly senderSessionId: SessionId
|
||||
}
|
||||
@@ -54,6 +56,8 @@ export interface CoordinatorMessageSource {
|
||||
/** Durable attribution for a continuable child's explicit parent report. */
|
||||
export interface SubagentReportMessageSource {
|
||||
readonly kind: 'subagent-report'
|
||||
/** A message another agent addressed to this one (`relay` context form). */
|
||||
readonly form: 'relay'
|
||||
/** Session id of the reporting child. */
|
||||
readonly senderSessionId: SessionId
|
||||
}
|
||||
@@ -283,7 +287,7 @@ export class SubagentContinuationManager {
|
||||
// child-first ordering.
|
||||
const scope = ctx.plugin(function activationOwner() {})
|
||||
this.ownerCtx = scope.ctx
|
||||
ctx.on('agent/disposed', (agent) => {
|
||||
ctx.on('agent/disposed', ({ agent }) => {
|
||||
this.closingScopes.delete(agent)
|
||||
})
|
||||
ctx.effect(function* (this: SubagentContinuationManager) {
|
||||
@@ -481,6 +485,7 @@ export class SubagentContinuationManager {
|
||||
],
|
||||
source: {
|
||||
kind: 'subagent-report' as const,
|
||||
form: 'relay' as const,
|
||||
senderSessionId: activation.childId,
|
||||
},
|
||||
})
|
||||
@@ -688,7 +693,7 @@ export class SubagentContinuationManager {
|
||||
}
|
||||
|
||||
/**
|
||||
* Cold-resume a persisted child: load and authorize its Session, fold the
|
||||
* Cold-resume a persisted child: inspect and authorize its Session, fold the
|
||||
* generic descriptor, create the Activation through `ctx.agents.resume()`,
|
||||
* and submit the waiting turn. This never dispatches through a subagent
|
||||
* provider — the persisted Session already holds the initial prefix and the
|
||||
@@ -701,13 +706,13 @@ export class SubagentContinuationManager {
|
||||
options: SubagentFollowupOptions,
|
||||
): Promise<MessageId> {
|
||||
const persistence = this.requirePersistence()
|
||||
let loaded: Awaited<ReturnType<typeof persistence.load>>
|
||||
let loaded: Awaited<ReturnType<typeof persistence.inspect>>
|
||||
try {
|
||||
loaded = await persistence.load(childId)
|
||||
loaded = await persistence.inspect(childId, options.signal)
|
||||
} catch (error: unknown) {
|
||||
options.signal.throwIfAborted()
|
||||
throw new SubagentError(`subagent "${childId}" is unavailable`, 'NOT_RESUMABLE', { cause: error })
|
||||
}
|
||||
// The persistence seam takes no signal; recheck before any child work.
|
||||
options.signal.throwIfAborted()
|
||||
this.assertAdmitting(parent)
|
||||
// Authorize the persisted header before folding: only the durable child's
|
||||
@@ -724,17 +729,24 @@ export class SubagentContinuationManager {
|
||||
'NOT_RESUMABLE',
|
||||
)
|
||||
}
|
||||
const activation = await this.materialize({
|
||||
childId,
|
||||
provider: descriptor.provider,
|
||||
parent,
|
||||
agentOptions: {
|
||||
...descriptor.agentProvider !== undefined ? { provider: descriptor.agentProvider } : {},
|
||||
...descriptor.agentModel !== undefined ? { model: descriptor.agentModel } : {},
|
||||
},
|
||||
composition: { persona: descriptor.persona, toolFilter: descriptor.toolFilter },
|
||||
signal: options.signal,
|
||||
})
|
||||
let activation: Activation
|
||||
try {
|
||||
activation = await this.materialize({
|
||||
childId,
|
||||
provider: descriptor.provider,
|
||||
parent,
|
||||
agentOptions: {
|
||||
...descriptor.agentProvider !== undefined ? { provider: descriptor.agentProvider } : {},
|
||||
...descriptor.agentModel !== undefined ? { model: descriptor.agentModel } : {},
|
||||
},
|
||||
composition: { persona: descriptor.persona, toolFilter: descriptor.toolFilter },
|
||||
signal: options.signal,
|
||||
})
|
||||
} catch (error: unknown) {
|
||||
options.signal.throwIfAborted()
|
||||
if (error instanceof SubagentError) throw error
|
||||
throw new SubagentError(`subagent "${childId}" is unavailable`, 'NOT_RESUMABLE', { cause: error })
|
||||
}
|
||||
return this.submitMaterialized(activation, content, options.source, parent, options.signal)
|
||||
}
|
||||
|
||||
@@ -847,16 +859,13 @@ export class SubagentContinuationManager {
|
||||
// quiet Agent from one whose accepted turn has not been admitted yet.
|
||||
// Registered through the child's own scoped context, so scope filtering
|
||||
// already restricts both listeners to this exact agent.
|
||||
handle.agent.ctx.on('agent/inbox/dequeue', (_agent, item) => {
|
||||
/* v8 ignore next -- a dequeue of an id this manager never admitted needs
|
||||
handle.agent.ctx.on('agent/inbox/claimed', ({ message }) => {
|
||||
/* v8 ignore next -- a claim of an id this manager never admitted needs
|
||||
* another sender on the same child, which no current path allows. */
|
||||
if (activation.accepted.delete(item.message.id)) this.wake(activation)
|
||||
if (activation.accepted.delete(message.id)) this.wake(activation)
|
||||
})
|
||||
handle.agent.ctx.on('agent/inbox/discard', (_agent, items) => {
|
||||
// Deleting every id in the batch is unconditional; waking once afterwards
|
||||
// costs nothing and avoids branching on which ids this manager admitted.
|
||||
for (const item of items) activation.accepted.delete(item.message.id)
|
||||
this.wake(activation)
|
||||
handle.agent.ctx.on('agent/inbox/discarded', ({ message }) => {
|
||||
if (activation.accepted.delete(message.id)) this.wake(activation)
|
||||
})
|
||||
// Agent creation committed setup at its publication boundary;
|
||||
// revocations from here on are immediate live revocation.
|
||||
|
||||
@@ -25,7 +25,7 @@ export function seedDescriptorTurn(
|
||||
seed: readonly SessionEvent[] | undefined,
|
||||
descriptor: SubagentDescriptorData,
|
||||
): SessionEvent[] {
|
||||
const staged = new Session(childId, seed)
|
||||
const staged = Session.create(childId, seed)
|
||||
staged.append('subagent/descriptor', descriptor)
|
||||
return [...staged.events]
|
||||
}
|
||||
|
||||
@@ -207,7 +207,6 @@ function epochStopReason(events: readonly SessionEvent[]): SubagentResult['stopR
|
||||
return 'max-tokens'
|
||||
case 'aborted':
|
||||
case 'interrupted':
|
||||
case 'disposed':
|
||||
return 'aborted'
|
||||
case 'error':
|
||||
return 'error'
|
||||
|
||||
@@ -1,8 +1,9 @@
|
||||
/**
|
||||
* Read-only interpretation of session-query lineage as durable subagent
|
||||
* children. The module owns no catalog state and does not consult Activation,
|
||||
* Agent-registry, continuation-manager, or provider state. A child's
|
||||
* descriptor distinguishes one-shot work from a continuable conversation.
|
||||
* children. Only descendants with durable `origin: 'subagent'` enter per-child
|
||||
* inspection. The module owns no catalog state and does not consult Activation,
|
||||
* Agent-registry, continuation-manager, or provider state. A child's descriptor
|
||||
* distinguishes one-shot work from a continuable conversation.
|
||||
*
|
||||
* @module @deepseek-ai/dsh-subagent
|
||||
*/
|
||||
@@ -20,12 +21,13 @@ type SessionQueryRuntime = Pick<
|
||||
>
|
||||
|
||||
/**
|
||||
* One entry of a {@link listChildren} result in trace candidate order. A valid
|
||||
* descriptor produces a `child`, a per-child inspection failure produces a
|
||||
* `diagnostic`, and a descriptor-less ordinary child is omitted. Healthy rows
|
||||
* include a one-level, origin-classified descendant hint. Diagnostics are
|
||||
* transient query results, never session events or catalog state, and never
|
||||
* expose model-hidden descriptor content.
|
||||
* One entry of a {@link listChildren} result in trace candidate order. Only a
|
||||
* candidate whose durable header has `origin: 'subagent'` is inspected. A
|
||||
* valid descriptor produces a `child`, a per-child inspection failure produces
|
||||
* a `diagnostic`, and a candidate without its own descriptor is omitted.
|
||||
* Healthy rows include a one-level, origin-classified descendant hint.
|
||||
* Diagnostics are transient query results, never session events or catalog
|
||||
* state, and never expose model-hidden descriptor content.
|
||||
*/
|
||||
export type SubagentListEntry =
|
||||
| {
|
||||
@@ -69,8 +71,9 @@ export type SubagentListEntry =
|
||||
}
|
||||
|
||||
/**
|
||||
* Interpret one parent's direct session descendants as session-backed subagents
|
||||
* without loading or resuming an Agent.
|
||||
* Interpret one parent's origin-classified direct descendants as session-backed
|
||||
* subagents without loading or resuming an Agent. Ordinary forks are skipped
|
||||
* before per-child event inspection.
|
||||
* @see {@link SubagentService.listChildren} for the public cancellation and
|
||||
* failure contract.
|
||||
* @param ctx - context carrying the optional session-query service.
|
||||
@@ -103,6 +106,7 @@ export async function listChildren(
|
||||
)
|
||||
const entries: SubagentListEntry[] = []
|
||||
for (const node of trace.descendants) {
|
||||
if (node.session.header.origin !== 'subagent') continue
|
||||
const hasChildren = node.descendants.some(
|
||||
descendant => descendant.session.header.origin === 'subagent',
|
||||
)
|
||||
@@ -218,6 +222,8 @@ function perChildDiagnosticReason(
|
||||
): 'corrupt' | 'unavailable' | undefined {
|
||||
if (!(error instanceof SessionQueryError)) return undefined
|
||||
switch (error.code) {
|
||||
case 'SESSION_QUERY_CORRUPT_SESSION':
|
||||
return 'corrupt'
|
||||
case 'SESSION_QUERY_SESSION_NOT_FOUND':
|
||||
case 'SESSION_QUERY_EVENT_NOT_FOUND':
|
||||
case 'SESSION_QUERY_PERSISTENCE_FAILED':
|
||||
|
||||
@@ -142,14 +142,27 @@ async function waitNoActivation(ctx: Context, childId: SessionId): Promise<void>
|
||||
}, { timeout: 5_000 })
|
||||
}
|
||||
|
||||
/** Observe calls at the Agent cancellation boundary without a production event. */
|
||||
function observeCancel(agent: Agent, callback: () => void): void {
|
||||
const cancel = agent.cancel.bind(agent)
|
||||
let observed = false
|
||||
vi.spyOn(agent, 'cancel').mockImplementation((cause, options) => {
|
||||
if (!observed) {
|
||||
observed = true
|
||||
callback()
|
||||
}
|
||||
cancel(cause, options)
|
||||
})
|
||||
}
|
||||
|
||||
describe('SubagentService.startContinuable', () => {
|
||||
it('returns both identities at inbox acceptance, without waiting for the turn or the log', async () => {
|
||||
const { ctx, parent, adapter } = await setup([textResponse('first answer')])
|
||||
const enqueued: { id: MessageId; loggedYet: boolean }[] = []
|
||||
ctx.on('agent/inbox/enqueue', (agent, accepted) => {
|
||||
ctx.on('agent/inbox/inserted', ({ agent, message }) => {
|
||||
// Acceptance is the boundary `startContinuable` resolves at, so observe
|
||||
// the log state exactly there rather than after later microtasks.
|
||||
enqueued.push({ id: accepted.message.id, loggedYet: hasUserText(agent.session.events, 'child task') })
|
||||
enqueued.push({ id: message.id, loggedYet: hasUserText(agent.session.events, 'child task') })
|
||||
})
|
||||
|
||||
const started = await ctx.subagents.startContinuable(startSpec(parent))
|
||||
@@ -218,7 +231,7 @@ describe('SubagentService.startContinuable', () => {
|
||||
const { ctx, parent } = await setup([textResponse('unused')])
|
||||
const controller = new AbortController()
|
||||
// Abort inside the child's creation window: setup runs before publication.
|
||||
ctx.on('agent/created', (child) => {
|
||||
ctx.on('agent/created', ({ agent: child }) => {
|
||||
if (child !== parent) controller.abort('caller gave up')
|
||||
})
|
||||
|
||||
@@ -555,6 +568,47 @@ describe('SubagentService.followup residency routing', () => {
|
||||
.rejects.toMatchObject({ code: 'NOT_RESUMABLE' })
|
||||
})
|
||||
|
||||
it('propagates cancellation while inspecting a cold child', async () => {
|
||||
const { ctx, parent } = await setup([textResponse('first')])
|
||||
const started = await ctx.subagents.startContinuable(startSpec(parent))
|
||||
await waitNoActivation(ctx, started.childId)
|
||||
const inspectStarted = Promise.withResolvers<undefined>()
|
||||
const inspect = vi.spyOn(ctx.sessionPersistence, 'inspect').mockImplementation((_id, signal) => {
|
||||
return new Promise<never>((_resolve, reject) => {
|
||||
if (signal === undefined) {
|
||||
reject(new Error('cold inspection must receive the followup signal'))
|
||||
return
|
||||
}
|
||||
inspectStarted.resolve(undefined)
|
||||
signal.addEventListener('abort', () => {
|
||||
reject(reason)
|
||||
}, { once: true })
|
||||
})
|
||||
})
|
||||
const controller = new AbortController()
|
||||
const reason = new Error('cold inspection cancelled')
|
||||
|
||||
try {
|
||||
const delivery = followup(ctx, parent, started.childId, message('cancel me'), controller.signal)
|
||||
await inspectStarted.promise
|
||||
controller.abort(reason)
|
||||
await expect(delivery).rejects.toBe(reason)
|
||||
} finally {
|
||||
inspect.mockRestore()
|
||||
}
|
||||
})
|
||||
|
||||
it('preserves a SubagentError raised while cold-materializing a child', async () => {
|
||||
const { ctx, parent } = await setup([textResponse('first')])
|
||||
const started = await ctx.subagents.startContinuable(startSpec(parent))
|
||||
await waitNoActivation(ctx, started.childId)
|
||||
const failure = new SubagentError('materialization denied', 'UNAUTHORIZED')
|
||||
ctx.agents.resume = () => Promise.reject(failure)
|
||||
|
||||
await expect(followup(ctx, parent, started.childId, message('continue')))
|
||||
.rejects.toBe(failure)
|
||||
})
|
||||
|
||||
it('cold-resumes a delivery that lost the race with final disposal', async () => {
|
||||
const { ctx, parent } = await setup([textResponse('first'), textResponse('after the race')])
|
||||
const started = await ctx.subagents.startContinuable(startSpec(parent))
|
||||
@@ -699,7 +753,7 @@ describe('continuable durability and teardown', () => {
|
||||
await vi.waitFor(() => { expect(ctx.agents.get(grandchild.childId)).toBeDefined() })
|
||||
|
||||
const disposals: SessionId[] = []
|
||||
ctx.on('agent/disposed', (agent) => { disposals.push(agent.id) })
|
||||
ctx.on('agent/disposed', ({ agent }) => { disposals.push(agent.id) })
|
||||
const drained = drainManager(ctx)
|
||||
// Let the held model call observe its cancellation so quiescence can settle.
|
||||
hold.resolve(undefined)
|
||||
@@ -737,7 +791,9 @@ describe('continuable durability and teardown', () => {
|
||||
const grandchild = await ctx.subagents.startContinuable(startSpec(targetChild))
|
||||
await vi.waitFor(() => { expect(adapter.requests).toHaveLength(3) })
|
||||
const cancellations: SessionId[] = []
|
||||
ctx.on('agent/cancel-requested', (agent) => { cancellations.push(agent.id) })
|
||||
observeCancel(targetChild, () => { cancellations.push(targetChild.id) })
|
||||
const grandchildAgent = ctx.agents.get(grandchild.childId)!
|
||||
observeCancel(grandchildAgent, () => { cancellations.push(grandchildAgent.id) })
|
||||
|
||||
const drained = ctx.subagents.drainContinuableDescendants([parent])
|
||||
const convergedDrain = ctx.subagents.drainContinuableDescendants([parent])
|
||||
@@ -784,7 +840,8 @@ describe('continuable durability and teardown', () => {
|
||||
const grandchild = await ctx.subagents.startContinuable(startSpec(child))
|
||||
await vi.waitFor(() => { expect(adapter.requests).toHaveLength(2) })
|
||||
const cancellations: SessionId[] = []
|
||||
ctx.on('agent/cancel-requested', (agent) => { cancellations.push(agent.id) })
|
||||
const grandchildAgent = ctx.agents.get(grandchild.childId)!
|
||||
observeCancel(grandchildAgent, () => { cancellations.push(grandchildAgent.id) })
|
||||
|
||||
const drained = ctx.subagents.drainContinuableDescendants([child])
|
||||
|
||||
@@ -828,7 +885,8 @@ describe('continuable durability and teardown', () => {
|
||||
expect(ctx.agents.get(intermediateId)).toBeUndefined()
|
||||
expect(ctx.agents.get(descendant.childId)).toBeDefined()
|
||||
const cancellations: SessionId[] = []
|
||||
ctx.on('agent/cancel-requested', (agent) => { cancellations.push(agent.id) })
|
||||
const descendantAgent = ctx.agents.get(descendant.childId)!
|
||||
observeCancel(descendantAgent, () => { cancellations.push(descendantAgent.id) })
|
||||
|
||||
const drained = ctx.subagents.drainContinuableDescendants([parent])
|
||||
|
||||
@@ -926,7 +984,7 @@ describe('continuable durability and teardown', () => {
|
||||
const drains: Promise<void>[] = []
|
||||
const accepted: MessageId[] = []
|
||||
ctx.on('subagent/start', () => { drains.push(drainManager(ctx)) })
|
||||
ctx.on('agent/inbox/enqueue', (_agent, item) => { accepted.push(item.message.id) })
|
||||
ctx.on('agent/inbox/inserted', ({ message }) => { accepted.push(message.id) })
|
||||
|
||||
await expect(ctx.subagents.startContinuable(startSpec(parent)))
|
||||
.rejects.toMatchObject({ code: 'DRAINING' })
|
||||
@@ -940,12 +998,12 @@ describe('continuable durability and teardown', () => {
|
||||
const { ctx, parent } = await setup([])
|
||||
const order: string[] = []
|
||||
const drains: Promise<void>[] = []
|
||||
ctx.on('agent/created', (child) => {
|
||||
ctx.on('agent/created', ({ agent: child }) => {
|
||||
if (child === parent) return
|
||||
const draining = drainManager(ctx).then(() => { order.push('drain') })
|
||||
drains.push(draining)
|
||||
})
|
||||
ctx.on('agent/disposed', (child) => {
|
||||
ctx.on('agent/disposed', ({ agent: child }) => {
|
||||
if (child !== parent) order.push('disposed')
|
||||
})
|
||||
|
||||
@@ -967,12 +1025,12 @@ describe('continuable durability and teardown', () => {
|
||||
await vi.waitFor(() => { expect(adapter.requests).toHaveLength(1) })
|
||||
const child = ctx.agents.get(started.childId)!
|
||||
const order: string[] = []
|
||||
child.ctx.on('agent/inbox/enqueue', (_agent, accepted) => {
|
||||
if (accepted.message.content.some(block => block.type === 'text' && block.text === 'before drain')) {
|
||||
child.ctx.on('agent/inbox/inserted', ({ message }) => {
|
||||
if (message.content.some(block => block.type === 'text' && block.text === 'before drain')) {
|
||||
order.push('enqueue')
|
||||
}
|
||||
})
|
||||
child.ctx.on('agent/cancel-requested', () => { order.push('cancel') })
|
||||
observeCancel(child, () => { order.push('cancel') })
|
||||
|
||||
const delivery = followup(ctx, parent, started.childId, message('before drain'))
|
||||
// Let the child-lock operation reach the live admission cutoff. Admission
|
||||
@@ -1150,9 +1208,9 @@ describe('continuable review regressions', () => {
|
||||
const ends: SubagentRunEndInfo[] = []
|
||||
ctx.on('subagent/end', (info) => { ends.push(info) })
|
||||
// Block the resumed prompt so this epoch produces nothing of its own.
|
||||
ctx.on('agent/prompt-submit', async (subject, _message, _signal, next) => {
|
||||
ctx.on('agent/pre-step', async ({ agent: subject }, next) => {
|
||||
if (subject === parent) return next()
|
||||
return { kind: 'block', reason: 'blocked by policy' }
|
||||
return { kind: 'reject' }
|
||||
})
|
||||
await followup(ctx, parent, started.childId, message('again'))
|
||||
await waitNoActivation(ctx, started.childId)
|
||||
@@ -1258,7 +1316,7 @@ describe('continuable review regressions', () => {
|
||||
expect(found).toBeDefined()
|
||||
return found!
|
||||
})
|
||||
child.ctx.on('agent/cancel-requested', () => { order.push('cancel') })
|
||||
observeCancel(child, () => { order.push('cancel') })
|
||||
|
||||
const drained = drainManager(ctx)
|
||||
hold.resolve(undefined)
|
||||
@@ -1298,8 +1356,8 @@ describe('continuable review regressions', () => {
|
||||
|
||||
// Cancel from the synchronous enqueue observer: the discard fires after the
|
||||
// id is recorded but before `followup()` returns.
|
||||
const off = child.ctx.on('agent/inbox/enqueue', (_agent, accepted) => {
|
||||
if (accepted.message.content.some(block => block.type === 'text' && block.text === 'doomed')) {
|
||||
const off = child.ctx.on('agent/inbox/inserted', ({ message }) => {
|
||||
if (message.content.some(block => block.type === 'text' && block.text === 'doomed')) {
|
||||
child.cancel({ kind: 'user' })
|
||||
}
|
||||
})
|
||||
@@ -1330,8 +1388,8 @@ describe('continuable review regressions', () => {
|
||||
|
||||
await followup(ctx, parent, started.childId, message('queued'))
|
||||
expect(activation.accepted.size).toBe(1)
|
||||
const off = child.ctx.on('agent/inbox/enqueue', (_agent, accepted) => {
|
||||
if (accepted.message.content.some(block => block.type === 'text' && block.text === 'doomed')) {
|
||||
const off = child.ctx.on('agent/inbox/inserted', ({ message }) => {
|
||||
if (message.content.some(block => block.type === 'text' && block.text === 'doomed')) {
|
||||
child.cancel({ kind: 'user' })
|
||||
}
|
||||
})
|
||||
@@ -1348,9 +1406,9 @@ describe('continuable review regressions', () => {
|
||||
const ends: SubagentRunEndInfo[] = []
|
||||
ctx.on('subagent/end', (info) => { ends.push(info) })
|
||||
// Block admission so the child's only turn never opens.
|
||||
ctx.on('agent/prompt-submit', async (subject, _message, _signal, next) => {
|
||||
ctx.on('agent/pre-step', async ({ agent: subject }, next) => {
|
||||
if (subject === parent) return next()
|
||||
return { kind: 'block', reason: 'blocked by policy' }
|
||||
return { kind: 'reject' }
|
||||
})
|
||||
|
||||
const started = await ctx.subagents.startContinuable(startSpec(parent))
|
||||
@@ -1370,7 +1428,7 @@ describe('continuable review regressions', () => {
|
||||
const registeredAtEnqueue: boolean[] = []
|
||||
// A synchronous inbox observer runs before the admitting microtask, the
|
||||
// exact window where `Agent.status` is still idle.
|
||||
ctx.on('agent/inbox/enqueue', (agent) => {
|
||||
ctx.on('agent/inbox/inserted', ({ agent }) => {
|
||||
if (agent.session.header.parentSession !== undefined) {
|
||||
registeredAtEnqueue.push(ctx.agents.get(agent.id) === agent)
|
||||
}
|
||||
|
||||
@@ -113,10 +113,11 @@ describe('SubagentService.listChildren', () => {
|
||||
const parentId = SessionId('query-only-parent')
|
||||
ctx.sessions.create(parentId)
|
||||
const childId = SessionId('query-only-child')
|
||||
const child = ctx.sessions.create(childId, { meta: { parentSession: parentId } })
|
||||
const child = ctx.sessions.create(childId, {
|
||||
meta: { parentSession: parentId, origin: 'subagent' },
|
||||
})
|
||||
child.append('turn/start', {
|
||||
turn: 1,
|
||||
trigger: { kind: 'message', source: { kind: 'user' } },
|
||||
})
|
||||
child.append('subagent/descriptor', descriptorPayload('query-only child'))
|
||||
|
||||
@@ -193,6 +194,7 @@ describe('SubagentService.listChildren', () => {
|
||||
] as SessionEvent[])
|
||||
const childId = await authorChild(ctx, '00000000-0000-4000-8000-00000000cdcd', {
|
||||
parentSession: coldParent,
|
||||
origin: 'subagent',
|
||||
}, childEvents(descriptorPayload('persisted parent case')))
|
||||
const entries = await ctx.subagents.listChildren(coldParent)
|
||||
expect(entries).toEqual([
|
||||
@@ -203,28 +205,33 @@ describe('SubagentService.listChildren', () => {
|
||||
])
|
||||
})
|
||||
|
||||
it('orders children by createdAt then id and omits ordinary forks without a diagnostic', async () => {
|
||||
it('orders children by createdAt then id without inspecting ordinary forks', async () => {
|
||||
const { ctx, parent } = await setup([])
|
||||
// Authored headers pin the ordering key deterministically: same createdAt
|
||||
// ties break on id, different createdAt orders ascending.
|
||||
const late = await authorChild(ctx, '00000000-0000-4000-8000-000000000003', {
|
||||
parentSession: parent.id,
|
||||
createdAt: 9,
|
||||
origin: 'subagent',
|
||||
}, childEvents(descriptorPayload('late child')))
|
||||
const tieB = await authorChild(ctx, '00000000-0000-4000-8000-000000000002', {
|
||||
parentSession: parent.id,
|
||||
createdAt: 5,
|
||||
origin: 'subagent',
|
||||
}, childEvents(descriptorPayload('tie b')))
|
||||
const tieA = await authorChild(ctx, '00000000-0000-4000-8000-000000000001', {
|
||||
parentSession: parent.id,
|
||||
createdAt: 5,
|
||||
origin: 'subagent',
|
||||
}, childEvents(descriptorPayload('tie a')))
|
||||
// An ordinary session fork shares parentSession but has no descriptor.
|
||||
// An ordinary session fork shares parentSession but has no subagent origin.
|
||||
const fork = ctx.sessions.fork(parent.session, undefined, SessionId('plain-fork'))
|
||||
await ctx.sessions.flush(fork)
|
||||
const listEvents = vi.spyOn(ctx.sessionQuery, 'listEvents')
|
||||
const entries = await ctx.subagents.listChildren(parent.id)
|
||||
expect(entries.map(entry => entry.id)).toEqual([tieA, tieB, late])
|
||||
expect(entries.every(entry => entry.kind === 'child')).toBe(true)
|
||||
expect(listEvents).not.toHaveBeenCalledWith(fork.id)
|
||||
})
|
||||
|
||||
it('reports a live child as running while keeping settled siblings complete', async () => {
|
||||
@@ -233,8 +240,10 @@ describe('SubagentService.listChildren', () => {
|
||||
// A live child session outside persistence: publish a live session with a
|
||||
// descriptor and the parent lineage, without starting an Activation.
|
||||
const liveId = SessionId('live-child')
|
||||
const live = ctx.sessions.create(liveId, { meta: { parentSession: parent.id } })
|
||||
live.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
|
||||
const live = ctx.sessions.create(liveId, {
|
||||
meta: { parentSession: parent.id, origin: 'subagent' },
|
||||
})
|
||||
live.append('turn/start', { turn: 1 })
|
||||
live.append('subagent/descriptor', descriptorPayload('live child'))
|
||||
const entries = await ctx.subagents.listChildren(parent.id)
|
||||
expect(entries).toContainEqual({
|
||||
@@ -260,6 +269,7 @@ describe('SubagentService.listChildren', () => {
|
||||
events[4] = { ...events[4]!, seq: 4 }
|
||||
const corrupt = await authorChild(ctx, '00000000-0000-4000-8000-00000000dupe', {
|
||||
parentSession: parent.id,
|
||||
origin: 'subagent',
|
||||
}, events)
|
||||
const entries = await ctx.subagents.listChildren(parent.id)
|
||||
expect(entries).toContainEqual({ kind: 'diagnostic', id: corrupt, reason: 'corrupt' })
|
||||
@@ -269,12 +279,13 @@ describe('SubagentService.listChildren', () => {
|
||||
})
|
||||
})
|
||||
|
||||
it('diagnoses an invalid child event surface as corrupt', async () => {
|
||||
it('diagnoses a child rejected by persisted Session preparation as corrupt', async () => {
|
||||
const { ctx, parent } = await setup([])
|
||||
// The surface-eligible user/message lacks its required surfaceOp, so the
|
||||
// per-child listEvents fold fails with SESSION_QUERY_INVALID_SURFACE.
|
||||
// The surface-eligible user/message lacks its required surfaceOp. The
|
||||
// first-party persistence inspection rejects before session-query can fold it.
|
||||
const invalid = await authorChild(ctx, '00000000-0000-4000-8000-0000000000ee', {
|
||||
parentSession: parent.id,
|
||||
origin: 'subagent',
|
||||
}, [
|
||||
{ type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } },
|
||||
{
|
||||
@@ -293,6 +304,7 @@ describe('SubagentService.listChildren', () => {
|
||||
const { ctx, parent } = await setup([])
|
||||
const malformed = await authorChild(ctx, '00000000-0000-4000-8000-0000000000ff', {
|
||||
parentSession: parent.id,
|
||||
origin: 'subagent',
|
||||
}, childEvents({ version: SUBAGENT_DESCRIPTOR_VERSION, mode: 'continuable', provider: 7 }))
|
||||
const entries = await ctx.subagents.listChildren(parent.id)
|
||||
expect(entries).toEqual([{ kind: 'diagnostic', id: malformed, reason: 'corrupt' }])
|
||||
@@ -302,6 +314,7 @@ describe('SubagentService.listChildren', () => {
|
||||
const { ctx, parent } = await setup([])
|
||||
const future = await authorChild(ctx, '00000000-0000-4000-8000-0000000000aa', {
|
||||
parentSession: parent.id,
|
||||
origin: 'subagent',
|
||||
}, childEvents(descriptorPayload('from the future', SUBAGENT_DESCRIPTOR_VERSION + 1)))
|
||||
const entries = await ctx.subagents.listChildren(parent.id)
|
||||
expect(entries).toEqual([{ kind: 'diagnostic', id: future, reason: 'unsupported' }])
|
||||
@@ -315,6 +328,7 @@ describe('SubagentService.listChildren', () => {
|
||||
await authorChild(ctx, '00000000-0000-4000-8000-0000000000f0', {
|
||||
parentSession: parent.id,
|
||||
seedLength: seed.length,
|
||||
origin: 'subagent',
|
||||
}, seed)
|
||||
const entries = await ctx.subagents.listChildren(parent.id)
|
||||
expect(entries).toEqual([])
|
||||
@@ -324,6 +338,7 @@ describe('SubagentService.listChildren', () => {
|
||||
const { ctx, parent } = await setup([])
|
||||
const foreign = await authorChild(ctx, '00000000-0000-4000-8000-0000000000bb', {
|
||||
parentSession: parent.id,
|
||||
origin: 'subagent',
|
||||
}, childEvents({
|
||||
version: SUBAGENT_DESCRIPTOR_VERSION,
|
||||
mode: 'continuable',
|
||||
@@ -354,16 +369,30 @@ describe('SubagentService.listChildren', () => {
|
||||
expect(entries).toEqual([{ kind: 'diagnostic', id: childId, reason: 'unavailable' }])
|
||||
})
|
||||
|
||||
it('maps a mid-scan disappearance to unavailable', async () => {
|
||||
it.each([
|
||||
['session', 'SESSION_QUERY_SESSION_NOT_FOUND'],
|
||||
['descriptor event', 'SESSION_QUERY_EVENT_NOT_FOUND'],
|
||||
] as const)('maps a missing child %s to unavailable', async (_target, code) => {
|
||||
const { ctx, parent } = await setup([textResponse('done')])
|
||||
const childId = await startChild(ctx, parent, 'vanishing child')
|
||||
const query = ctx.get('sessionQuery')!
|
||||
query.listEvents = () =>
|
||||
Promise.reject(new SessionQueryError('gone', 'SESSION_QUERY_SESSION_NOT_FOUND'))
|
||||
Promise.reject(new SessionQueryError('gone', code))
|
||||
const entries = await ctx.subagents.listChildren(parent.id)
|
||||
expect(entries).toEqual([{ kind: 'diagnostic', id: childId, reason: 'unavailable' }])
|
||||
})
|
||||
|
||||
it('maps an invalid child surface to corrupt', async () => {
|
||||
const { ctx, parent } = await setup([textResponse('done')])
|
||||
const childId = await startChild(ctx, parent, 'invalid surface')
|
||||
const query = ctx.get('sessionQuery')!
|
||||
query.listEvents = () =>
|
||||
Promise.reject(new SessionQueryError('invalid surface', 'SESSION_QUERY_INVALID_SURFACE'))
|
||||
|
||||
const entries = await ctx.subagents.listChildren(parent.id)
|
||||
expect(entries).toEqual([{ kind: 'diagnostic', id: childId, reason: 'corrupt' }])
|
||||
})
|
||||
|
||||
it('diagnoses a read whose header no longer names this parent as corrupt', async () => {
|
||||
const { ctx, parent } = await setup([textResponse('done')])
|
||||
const childId = await startChild(ctx, parent, 'reparented child')
|
||||
@@ -429,6 +458,7 @@ describe('SubagentService.listChildren', () => {
|
||||
const plain = await authorChild(ctx, '00000000-0000-4000-8000-00000000c0de', {
|
||||
parentSession: parent.id,
|
||||
createdAt: 1,
|
||||
origin: 'subagent',
|
||||
}, childEvents(descriptorPayload('twin child')))
|
||||
// The compacted twin: a compaction checkpoint replaces the whole surface,
|
||||
// while the append-only log retains the model-hidden descriptor event.
|
||||
@@ -447,6 +477,7 @@ describe('SubagentService.listChildren', () => {
|
||||
const compacted = await authorChild(ctx, '00000000-0000-4000-8000-00000000c1de', {
|
||||
parentSession: parent.id,
|
||||
createdAt: 2,
|
||||
origin: 'subagent',
|
||||
}, compactedEvents)
|
||||
const entries = await ctx.subagents.listChildren(parent.id)
|
||||
expect(entries).toEqual([
|
||||
|
||||
@@ -3,4 +3,4 @@
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write packages/subagent/tool-subagent-control/README.md
|
||||
README.md: 5d775a524c38750953c6389b9ebdea67a33df7ca
|
||||
README.zh.md: b82f59ce89690f449115690354f07d5d18e9bed5
|
||||
README.zh.md: 3b989fca8b79cea3e3b10bb2e65805e0cee79c69
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
可选的全局具名 `send_message` 与 `list_agents` 工具是 `ctx.subagents` 之上的轻量适配器。绑定提供方的 `@deepseek-ai/dsh-tool-subagent` 实例会为每种传输注册不同的委派工具；这个单独加载的包只注册一次共享控制工具，因此多个委派工具绝不会重复注册全局控制工具。根插件注册 `send_message`，且只要求 `subagents`；可单独加载的 `./list-agents` 插件注册 `list_agents`，将 `sessionQuery` 声明为加载时依赖，并在该服务可用前保持未激活状态。没有会话查询服务的部署可保留 `send_message` 并省略列表工具。是否加载这些工具不会决定委派工具是否启动可继续工作。这些工具只负责父到子的方向；单独安装的 [`@deepseek-ai/dsh-tool-subagent-report`](../tool-subagent-report/README.md) 负责子到父的方向。
|
||||
|
||||
本工具不执行生命周期路由：驻留与冷恢复归 subagent 服务所有。它将 `exec.agent` 作为授权投递的准确实时父级传入，并把每条消息的来源标记为持久化来源 `{ kind: 'coordinator', senderSessionId: parent.id }`；服务会保留该来源，但绝不将其视为权限。每条消息都会通过 `Agent.followup()` 成为子 agent（智能体）的下一个 FIFO 轮次：如果子 agent 仍在工作，该消息会等待其当前轮次结束，因此无法重定向已经在进行的工作。本工具会转发其执行信号，该信号只在 inbox 接受之前掌管准入；一旦子 agent 接受消息，已接受的轮次便无法再通过本工具取消。本次调用不会返回子 agent 的回复；通过该 id 查看其 transcript（文本记录），才是了解它完成了哪些工作的真源。拥有 `report` 的子 agent 会自行把内容作为一条单独的父级消息发回。投递失败会变为出错的工具结果，并明确说明消息未送达。
|
||||
本工具不执行生命周期路由：驻留与冷恢复归 subagent 服务所有。它将 `exec.agent` 作为授权投递的确切在线父级传入，并把每条消息的来源标记为持久化来源 `{ kind: 'coordinator', senderSessionId: parent.id }`；服务会保留该来源，但绝不将其视为权限。每条消息都会通过 `Agent.followup()` 成为子 agent（智能体）的下一个 FIFO 轮次：如果子 agent 仍在工作，该消息会等待其当前轮次结束，因此无法重定向已经在进行的工作。本工具会转发其执行信号，该信号只在 inbox 接受之前掌管准入；一旦子 agent 接受消息，已接受的轮次便无法再通过本工具取消。本次调用不会返回子 agent 的回复；通过该 id 查看其 transcript（文本记录），才是了解它完成了哪些工作的真源。拥有 `report` 的子 agent 会自行把内容作为一条单独的父级消息发回。投递失败会变为出错的工具结果，并明确说明消息未送达。
|
||||
|
||||
`list_agents` 不接受参数，会从调用它的 agent 推导 parent id，并且不使用 cursor，将 `ctx.subagents.listChildren()` 的结果投影为可继续 child。服务结果还包含由会话支撑的一次性 subagent，以供 UI 等消费方使用；但这些条目无法接受 `send_message`，因此会从这个模型工具中排除。diagnostic 仍然可见。持久化身份和模式来自每个子 agent 的描述符，消息送达时的鉴权和 Activation 所有权检查仍归 `send_message` 负责。
|
||||
|
||||
@@ -36,7 +36,7 @@
|
||||
|
||||
#### KV Cache 影响
|
||||
|
||||
仅追加；新增可见内容位于可复用请求前缀之后，不会使现有 KV-cache 条目失效。
|
||||
仅追加；新增可见内容位于可复用请求前缀之后，不会使现有 KV Cache 条目失效。
|
||||
|
||||
### 列表结果
|
||||
|
||||
@@ -54,7 +54,7 @@
|
||||
|
||||
## 已知限制与暂缓事项
|
||||
|
||||
- **已排队的消息没有独立结果**：接受时只返回其 inbox `messageId`；子 agent 的工作会落入持久化子 agent Session，绝不会通过本工具收集。获得 `report` 的子 agent 可以单独发回选定内容，但该消息不是本次调用的结果。
|
||||
- **不对当前轮次进行 steering**：每条消息都会开启后续 FIFO 轮次，因此在子 agent 工作时发送的消息只会在其当前轮次结束后运行，无法将其重定向。
|
||||
- **列表是快照，而非投递承诺**：它可能与发布、dispose 或后续消息发生竞态，另一个进程也可能激活当前进程报告为 `complete` 的 child；跨进程准确性需要共享租约。
|
||||
- **已排队的消息没有独立结果**：接受时只返回其 inbox `messageId`；子 agent 的工作会落入持久化子 agent 会话，绝不会通过本工具收集。获得 `report` 的子 agent 可以单独发回选定内容，但该消息不是本次调用的结果。
|
||||
- **不对当前轮次进行 steering（中途引导）**：每条消息都会开启后续 FIFO 轮次，因此在子 agent 工作时发送的消息只会在其当前轮次结束后运行，无法将其重定向。
|
||||
- **列表是快照，而非投递承诺**：它可能与发布、dispose（资源释放）或后续消息发生竞态，另一个进程也可能激活当前进程报告为 `complete` 的 child；跨进程准确性需要共享租约。
|
||||
- **没有分页或删除**：系统返回完整且稳定排序的集合；只要 child 会话仍在持久化存储中，它就会继续出现在列表中，服务级上限或删除操作留待后续产品决策。
|
||||
|
||||
@@ -26,9 +26,7 @@
|
||||
"lib/index.js",
|
||||
"lib/invariant.js",
|
||||
"lib/types/**/*.js",
|
||||
"lib/types/**/*.d.ts",
|
||||
"lib/types/**/*.d.ts.map",
|
||||
"src"
|
||||
"lib/types/**/*.d.ts"
|
||||
],
|
||||
"license": "BSD-3-Clause",
|
||||
"peerDependencies": {
|
||||
|
||||
@@ -66,7 +66,7 @@ export function apply(ctx: Context): void {
|
||||
SessionId(args.subagent_id),
|
||||
message,
|
||||
{
|
||||
source: { kind: 'coordinator', senderSessionId: parent.id },
|
||||
source: { kind: 'coordinator', form: 'relay', senderSessionId: parent.id },
|
||||
signal: exec.signal,
|
||||
},
|
||||
)
|
||||
|
||||
@@ -102,6 +102,7 @@ describe('dsh-tool-subagent-control', () => {
|
||||
// Durable provenance records the calling agent without granting authority.
|
||||
expect(followUp?.type === 'user/message' && followUp.data.source).toEqual({
|
||||
kind: 'coordinator',
|
||||
form: 'relay',
|
||||
senderSessionId: parent.id,
|
||||
})
|
||||
})
|
||||
@@ -129,7 +130,6 @@ describe('dsh-tool-subagent-control', () => {
|
||||
: [])
|
||||
// A follow-up is its own later turn, never steering inside the first one.
|
||||
expect(prompts).toEqual(['long work', 'also consider Y'])
|
||||
expect(loaded.events.some(event => event.type === 'steering/message')).toBe(false)
|
||||
})
|
||||
|
||||
it('reports a delivery failure as an errored, not-delivered result', async () => {
|
||||
|
||||
@@ -3,4 +3,4 @@
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write packages/subagent/tool-subagent-report/README.md
|
||||
README.md: cd73154dfb9c8b37f4a811c3beedbe6a63207f58
|
||||
README.zh.md: 4b31bed48ea0e50ec3a9d507548658defb94b8b8
|
||||
README.zh.md: 501598ec4e731b9315f3f08e0c81f5bb655c2b34
|
||||
|
||||
@@ -2,11 +2,11 @@
|
||||
|
||||
[English](README.md) | 中文
|
||||
|
||||
可选的子级作用域 `report` 工具是 `ctx.subagents.reportFrom()` 之上的轻量适配器。它为每个可继续的进程内子级提供一条返回通道，指向启动该子级的 Agent（智能体）。本包（package）注册的是可继续子级设置贡献，而不是全局工具，因此 `report` 只存在于这些子级内部。根 Agent、一次性 subagent、远程 subagent 提供方、同级作用域以及不关联 Agent 的工具执行都不会提供或执行它。安装本包只授予这项子级作用域功能；父到子方向仍由独立的 [`@deepseek-ai/dsh-tool-subagent-control`](../tool-subagent-control/README.md) 负责，可继续模式不依赖这两个包中的任一个。
|
||||
可选的子级作用域 `report` 工具是 `ctx.subagents.reportFrom()` 之上的轻量适配器。它为每个可继续的进程内子级提供一条返回通道，指向启动该子级的 Agent（智能体）。本包注册的是可继续子级设置贡献，而不是全局工具，因此 `report` 只存在于这些子级内部。根 Agent、一次性 subagent、远程 subagent 提供方、同级作用域以及不关联 Agent 的工具执行都不会提供或执行它。安装本包只授予这项子级作用域能力；父到子方向仍由独立的 [`@deepseek-ai/dsh-tool-subagent-control`](../tool-subagent-control/README.md) 负责，可继续模式不依赖这两个包中的任一个。
|
||||
|
||||
子级可以在一个轮次中调用 `report` 零次或多次。调用成功既不会结束轮次或结算 Activation，也不会阻止父级后续消息；轮次结束也绝不会自动上报。该工具不接受接收方参数：`exec.agent` 是发送方准确的实时 Agent，也是权限凭据；服务根据该子级持久化的 `parentSession` 推导唯一接收方。成功时返回父级已接受消息的稳定 `MessageId`，不表示已读回执、inbox 中该次出现的 id、父级日志确认、轮次完成回执或持久化刷盘。父级解析由注册表中的存在性决定：父级不在注册表时，调用失败并返回 `direct parent is not live; report was not delivered`；已开始宿主 dispose 但仍在注册表中的父级在其日志仍接受追加时仍会接受。服务不会执行注入、父级冷恢复或离线 mailbox 写入；持久化子级 transcript（文本记录）仍是恢复真源，且工具调用失败不能证明未送达（后续 `tools/post-execute` 否决可能让报告已被接受的调用以失败结束）。
|
||||
子级可以在一个轮次中调用 `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 不能在单次调用中选择或覆盖该策略。
|
||||
`reportDelivery` 为每条已接受的报告选择父级调度方式。`quiet`（默认值）使用 `parent.inject()`，在不启动父级模型请求的情况下添加面向模型的上下文：父级空闲时，追加操作会在调用返回前完成；报告到达正在准入或运行的父级时，则会暂存到下一个安全日志位置。`wakeup` 使用 `parent.followup()`，恰好创建一个普通的后续父级轮次，并唤醒停驻的父级驱动；它绝不会对正在运行的轮次进行 steering（中途引导）。这是部署调度策略，因此面向模型的 schema 不能在单次调用中选择或覆盖该策略。
|
||||
|
||||
作用域局部注册有意不受子级全局 `toolFilter` 影响，因此委派允许列表无法移除唯一的返回通道。需要子级不具备返回通道的部署应省略本包。
|
||||
|
||||
@@ -46,7 +46,7 @@
|
||||
|
||||
#### 模型看到的内容
|
||||
|
||||
一条用户角色的父级消息，以 `Background subagent <child-id> reported:` 开头，后接子级准确的 `output`，并带有持久化来源 `{ kind: 'subagent-report', senderSessionId: <child-id> }`。
|
||||
一条用户角色的父级消息，以 `Background subagent <child-id> reported:` 开头，后接子级未经改动的 `output`，并带有持久化来源 `{ kind: 'subagent-report', senderSessionId: <child-id> }`。
|
||||
|
||||
#### Token 影响
|
||||
|
||||
@@ -58,7 +58,7 @@
|
||||
|
||||
## 已知限制与暂缓事项
|
||||
|
||||
- **父级可能在宿主启动 dispose 后继续接受报告**：`AgentHandle.dispose()` 会先取消并等待完全停稳，然后才撤销作用域并离开注册表；它不公开「dispose 已开始」信号。在该窗口内接受的报告会追加到父级 transcript，但该父级不会在本进程中处理它。对于由延续管理器拥有的父级，管理器的准入边界会在整棵子树拆卸期间拒绝该上报。
|
||||
- **父级可能在宿主启动 dispose 后继续接受报告**：`AgentHandle.dispose()` 会先取消并等待完全停稳，然后才撤销作用域并离开注册表；它不公开「dispose 已开始」信号。在该窗口内接受的报告会追加到父级 transcript，但该父级不会在本进程中处理它。对于由继续执行管理器拥有的父级，管理器的准入边界会在整片森林拆卸期间拒绝该上报。
|
||||
- **接受弱于持久投递**：没有持久化 mailbox、幂等键、投递回执、重试协议，也不保证恰好一次。任一侧记录接受后若进程失败，结果都不明确；外部重试可能产生重复上报。
|
||||
- **暂存的静默报告无法立即重建**：接受时会返回其稳定 `MessageId`，但只有当待处理上下文到达普通日志边界后，父级 Session 才能重建带前缀的内容。
|
||||
- **授权须等到下一个 Activation，撤销则立即生效**：子级驻留后再安装本包，只会在该子级的下一个 Activation 中授予 `report`；移除本包则会立即从驻留子级撤销该 schema。
|
||||
|
||||
@@ -21,9 +21,7 @@
|
||||
"files": [
|
||||
"lib/index.js",
|
||||
"lib/invariant.js",
|
||||
"lib/types/**/*.d.ts",
|
||||
"lib/types/**/*.d.ts.map",
|
||||
"src"
|
||||
"lib/types/**/*.d.ts"
|
||||
],
|
||||
"license": "BSD-3-Clause",
|
||||
"peerDependencies": {
|
||||
|
||||
@@ -96,14 +96,15 @@ function callReport(ctx: Context, child: Agent, output: string, signal = testSig
|
||||
})
|
||||
}
|
||||
|
||||
/** Reports durably visible in one Agent's Session. */
|
||||
/** Reports already visible or still pending in one Agent. */
|
||||
function reports(agent: Agent): { id: string; text: string; sender: string }[] {
|
||||
return agent.session.events.flatMap((event) => {
|
||||
if (event.type !== 'user/message' || event.data.source.kind !== 'subagent-report') return []
|
||||
const visible = agent.session.events.flatMap(event => event.type === 'user/message' ? [event.data] : [])
|
||||
return [...visible, ...agent.inbox.nextStep].flatMap((message) => {
|
||||
if (message.source.kind !== 'subagent-report') return []
|
||||
return [{
|
||||
id: event.data.id,
|
||||
text: event.data.content.flatMap(block => block.type === 'text' ? [block.text] : []).join('\n'),
|
||||
sender: event.data.source.senderSessionId,
|
||||
id: message.id,
|
||||
text: message.content.flatMap(block => block.type === 'text' ? [block.text] : []).join('\n'),
|
||||
sender: message.source.senderSessionId,
|
||||
}]
|
||||
})
|
||||
}
|
||||
@@ -163,8 +164,10 @@ describe('dsh-tool-subagent-report', () => {
|
||||
const { started, child } = await startChild(ctx, parent)
|
||||
const parentRequests = adapter.requests.filter(request => request.sessionId === parent.id).length
|
||||
const enqueues: string[] = []
|
||||
ctx.on('agent/inbox/enqueue', (agent, item) => {
|
||||
if (agent === parent) enqueues.push(item.placement)
|
||||
ctx.on('agent/inbox/inserted', ({ agent, message }) => {
|
||||
if (agent === parent) {
|
||||
enqueues.push(agent.inbox.nextTurn.some(queued => queued.id === message.id) ? 'queued' : 'steering')
|
||||
}
|
||||
})
|
||||
|
||||
const result = await callReport(ctx, child, 'CHILD_FINDING')
|
||||
@@ -178,7 +181,7 @@ describe('dsh-tool-subagent-report', () => {
|
||||
text: `Background subagent ${started.childId} reported:\nCHILD_FINDING`,
|
||||
sender: started.childId,
|
||||
}])
|
||||
expect(enqueues).toEqual([])
|
||||
expect(enqueues).toEqual(['steering'])
|
||||
expect(parent.status).toBe('idle')
|
||||
expect(adapter.requests.filter(request => request.sessionId === parent.id)).toHaveLength(parentRequests)
|
||||
})
|
||||
@@ -187,8 +190,10 @@ describe('dsh-tool-subagent-report', () => {
|
||||
const { ctx, parent, adapter } = await setup({ config: { reportDelivery: 'wakeup' } })
|
||||
const { child } = await startChild(ctx, parent)
|
||||
const enqueues: string[] = []
|
||||
ctx.on('agent/inbox/enqueue', (agent, item) => {
|
||||
if (agent === parent) enqueues.push(item.placement)
|
||||
ctx.on('agent/inbox/inserted', ({ agent, message }) => {
|
||||
if (agent === parent) {
|
||||
enqueues.push(agent.inbox.nextTurn.some(queued => queued.id === message.id) ? 'queued' : 'steering')
|
||||
}
|
||||
})
|
||||
|
||||
const result = await callReport(ctx, child, 'WAKE_UP')
|
||||
@@ -227,9 +232,9 @@ describe('dsh-tool-subagent-report', () => {
|
||||
|
||||
expect((await callReport(ctx, grandchild, 'FROM_GRANDCHILD')).isError).toBe(false)
|
||||
expect(reports(parent)).toEqual([])
|
||||
// The intermediate parent's turn is open, so quiet context is staged until
|
||||
// that turn reaches its next safe log boundary.
|
||||
expect(reports(child)).toEqual([])
|
||||
// The intermediate parent's turn is open, so quiet context is pending in
|
||||
// its inbox until that turn reaches its next safe log boundary.
|
||||
expect(reports(child)).toHaveLength(1)
|
||||
adapter.release()
|
||||
await vi.waitFor(() => { expect(reports(child)).toHaveLength(1) })
|
||||
expect(reports(child)[0]?.sender).toBe(grandchildStart.childId)
|
||||
|
||||
@@ -3,4 +3,4 @@
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write packages/subagent/tool-subagent/README.md
|
||||
README.md: 6ec313b3b97f0ffa7488025d4314b1c6231a6f6a
|
||||
README.zh.md: 9e5c16ebc4760744c41965525e871da28b789612
|
||||
README.zh.md: 13ff7ee6fddd25c062c08b0b18c94323824f54b9
|
||||
|
||||
@@ -6,11 +6,11 @@
|
||||
|
||||
## 提供方选择与生命周期
|
||||
|
||||
每个插件实例把一个 `provider` 绑定到一个 `toolName`；模型不会收到提供方选择器。如需公开另一种传输，请加载另一个名称不同的实例。工具只在其提供方存在时注册，从而避免对同级加载顺序和提供方重新加载的依赖。工具描述遵循 `provider.inheritsParentContext`：全新子 agent（智能体）需要独立提示词，而 fork 子 agent 已能看到父级已完成轮次。
|
||||
每个插件实例把一个 `provider` 绑定到一个 `toolName`；模型不会收到提供方选择器。如需公开另一种传输，请加载另一个名称不同的实例。工具只在其提供方存在时注册，从而避免对同级加载顺序和提供方重新加载的依赖。工具描述遵循 `provider.inheritsParentContext`：新建子 agent（智能体）需要独立提示词，而 fork 子 agent 已能看到父级已完成轮次。
|
||||
|
||||
前台调用会让执行信号贯穿启动和执行，等待 `run.result`，并且在返回前总会等待 `run.dispose()`。只有 `completed` 会返回规范值 `{ kind: 'foreground', runId, output: JsonValue[] }`，并渲染为相同的最终文本；中止、拒绝、token 上限和其他失败都会变成出错的工具结果，不包含局部输出。如果结果收集与 dispose 都 reject，出错的结果会保留两项 diagnostic。
|
||||
前台调用会让执行信号贯穿启动和执行，等待 `run.result`，并且在返回前总会等待 `run.dispose()`。只有 `completed` 会返回规范值 `{ kind: 'foreground', runId, output: JsonValue[] }`，并渲染为相同的最终文本；中止、拒绝、token 上限和其他失败都会变成出错的工具结果，不包含局部输出。如果结果收集与 dispose（资源释放）都 reject，出错的结果会保留两项诊断信息。
|
||||
|
||||
设置 `run_in_background: true` 后，`backgroundMode` 会选择路由。`one-shot` 会注册一个普通的父级所有 Task，并返回规范值 `{ kind: 'background', taskId }`，渲染为 `started background subagent task <id>`，即使提供方支持可继续子 agent 也不例外；通用 Task 工具负责其后续状态、收集、取消和通知。`continuable` 要求提供方具备 `prepareContinuable` 能力，调用 `ctx.subagents.startContinuable()`，并返回 `{ kind: 'continuable', subagentId }`，渲染为 `started subagent <childId>`。可继续路由在 inbox 接受时兑现：子 agent 自此拥有自己的轮次，因此该调用既不等待也不收集结果，而且子 agent 不会回报——通过该 id 查看其 transcript 即是其输出来源，可选的全局 `send_message` 工具则向其发送更多工作。启动可继续工作不要求加载 `send_message`。见[后台 subagent Agent Note](../../../.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.md)、[可继续的 subagent Agent Note](../../../.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md)和[服务合并 Agent Note](../../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md)。
|
||||
设置 `run_in_background: true` 后，`backgroundMode` 会选择路由。`one-shot` 会注册一个归父级所有的普通 Task，并返回规范值 `{ kind: 'background', taskId }`，渲染为 `started background subagent task <id>`，即使提供方支持可继续子 agent 也不例外；通用 Task 工具负责其后续状态、收集、取消和通知。`continuable` 要求提供方具备 `prepareContinuable` 能力，调用 `ctx.subagents.startContinuable()`，并返回 `{ kind: 'continuable', subagentId }`，渲染为 `started subagent <childId>`。可继续路由在 inbox 接受时结算：子 agent 自此拥有自己的轮次，因此该调用既不等待也不收集结果，而且子 agent 不会回报——通过该 id 查看其 transcript（文本记录）即是其输出来源，可选的全局 `send_message` 工具则向其发送更多工作。启动可继续工作不要求加载 `send_message`。见 [后台 subagent Agent Note](../../../.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.md)、[可继续的 subagent Agent Note](../../../.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md)和[服务合并 Agent Note](../../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md)。
|
||||
|
||||
`toolFilter` 会改变子 agent 的全局工具层，但不是从父级派生的权限上限。见 [agent 作用域的安全非目标](../../../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md#security-and-authority-are-non-goals)。
|
||||
|
||||
@@ -29,7 +29,7 @@
|
||||
|
||||
## 并发
|
||||
|
||||
前台调用和后台调用均互斥。子 agent 可能共享父级工作区或外部资源，一元分类器无法证明同级委派的效果彼此不相交。见[并行工具调用 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md)。
|
||||
前台调用和后台调用均互斥。子 agent 可能共享父级工作区或外部资源，一元分类器无法证明同级委派的效果彼此不相交。见 [并行工具调用 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md)。
|
||||
|
||||
## 模型体验
|
||||
|
||||
@@ -55,17 +55,17 @@
|
||||
|
||||
#### Token 影响
|
||||
|
||||
提示词和结果会留在父级历史中，直到上下文压缩（compaction）；子 agent 工作上下文留在子 agent 中。
|
||||
提示词和结果会留在父级历史中，直到上下文压缩（context compaction）；子 agent 工作上下文留在子 agent 中。
|
||||
|
||||
#### KV Cache 影响
|
||||
|
||||
仅追加；新增可见内容位于可复用请求前缀之后，不会使现有 KV-cache 条目失效。
|
||||
仅追加；新增可见内容位于可复用请求前缀之后，不会使现有 KV Cache 条目失效。
|
||||
|
||||
### 后台结果
|
||||
|
||||
#### 模型看到的内容
|
||||
|
||||
在配置的可继续模式下，启动时精确返回 `started subagent <childId>`；在配置的一次性模式下，则返回 `started background subagent task <id>`。一次性模式下，通用 Task 接口提供后续状态、最终输出、取消响应和通知。可继续模式下，子 agent 不会回报；独立加载的 `send_message` 工具会投递后续消息，而通过其 id 查看子 agent 的 transcript 即是其输出来源。
|
||||
在配置的可继续模式下，启动时返回内容恰为 `started subagent <childId>`；在配置的一次性模式下，则返回 `started background subagent task <id>`。一次性模式下，通用 Task 接口提供后续状态、最终输出、取消响应和通知。可继续模式下，子 agent 不会回报；独立加载的 `send_message` 工具会投递后续消息，而通过其 id 查看子 agent 的 transcript 即是其输出来源。
|
||||
|
||||
#### Token 影响
|
||||
|
||||
@@ -73,7 +73,7 @@
|
||||
|
||||
#### KV Cache 影响
|
||||
|
||||
仅追加；新增可见内容位于可复用请求前缀之后，不会使现有 KV-cache 条目失效。
|
||||
仅追加；新增可见内容位于可复用请求前缀之后，不会使现有 KV Cache 条目失效。
|
||||
|
||||
## 已知限制与暂缓事项
|
||||
|
||||
|
||||
@@ -21,9 +21,7 @@
|
||||
"files": [
|
||||
"lib/index.js",
|
||||
"lib/invariant.js",
|
||||
"lib/types/**/*.d.ts",
|
||||
"lib/types/**/*.d.ts.map",
|
||||
"src"
|
||||
"lib/types/**/*.d.ts"
|
||||
],
|
||||
"license": "BSD-3-Clause",
|
||||
"peerDependencies": {
|
||||
|
||||
Reference in New Issue
Block a user