@deepseek-ai/dsh-tool-subagent-control 0.0.1-rc.1 → 0.0.1-rc.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/README.i18n.yaml +2 -2
  2. package/README.md +3 -3
  3. package/README.zh.md +3 -3
  4. package/lib/index.js +1 -1
  5. package/lib/types/index.d.ts +1 -1
  6. package/lib/types/index.js +1 -1
  7. package/lib/types/list-agents.js +10 -6
  8. package/package.json +18 -18
package/README.i18n.yaml CHANGED
@@ -2,5 +2,5 @@
2
2
  # side as of the last confirmed-consistent state. Both languages carry equal authority;
3
3
  # after editing either side, bring the other along and re-record with:
4
4
  # pnpm run verify-translation-pairing --write packages/subagent/tool-subagent-control/README.md
5
- README.md: 460617378841b791f7d8750962a9e4549643928e
6
- README.zh.md: 5939a1636a5f92dc797e5788c88bba7048ec7c96
5
+ README.md: 91f8d23ac092049e5315418070cdaae025054860
6
+ README.zh.md: 981e3f4efa2a904918d3f4174a2188fc2965c626
package/README.md CHANGED
@@ -8,7 +8,7 @@ The tool performs no lifecycle routing — residency and cold resume belong to t
8
8
 
9
9
  `interrupt_agent(agent_id)` passes `exec.agent` as the exact live ancestor authority for `ctx.subagents.interrupt()`: the target may be a direct child or a deeper descendant, and the service — never this tool — verifies the caller against the target Activation's recorded lineage. Only the target's current turn stops (`keepInbox`): queued messages stay parked until a later `send_message`, published descendants keep running, and the child stays available for follow-ups. The call returns as soon as the stop request is accepted, without waiting for target quiescence; an absent or already-settled target is an accepted no-op, while self, sibling, stale, and non-ancestor callers become errored results.
10
10
 
11
- `list_agents` takes one optional `scope` argument, derives the root id from the calling agent, and projects the service catalog to continuable children without a cursor. The default `children` scope reads `ctx.subagents.listChildren()`; `descendants` reads `ctx.subagents.listDescendants()`, whose one-corpus walk crosses ordinary sessions and one-shot children and renders surviving rows in stable pre-order with `parent=<id> depth=<n>`. The `parent` annotation is the durable direct-parent session id and may name an ordinary session omitted from the output. For the calling agent, only depth-1 child entries are `send_message` candidates; deeper child entries are `interrupt_agent` candidates only. Status comes from the live Agent registry: `running` (active driver), `idle` (resident between turns, possibly waiting on agents it started), `complete` (storage only). The service result also contains one-shot session-backed subagents for consumers such as a UI, but those entries are omitted from this model tool because they cannot accept `send_message`. Diagnostics remain visible, with positions in the descendants scope. Durable identity and mode come from each child's descriptor, while delivery-time authority and Activation ownership checks remain the service's.
11
+ `list_agents` takes one optional `scope` argument, derives the root id from the calling agent, and projects the service catalog to continuable children without a cursor. The default `children` scope reads `ctx.subagents.listChildren()`; `descendants` reads `ctx.subagents.listDescendants()`, whose one-corpus walk crosses ordinary sessions and one-shot children and renders surviving rows in stable pre-order with `parent=<id> depth=<n>`. The `parent` annotation is the durable direct-parent session id and may name an ordinary session omitted from the output. For the calling agent, only depth-1 child entries are `send_message` candidates; deeper child entries are `interrupt_agent` candidates only. Status comes from the live Agent registry: `running` (active driver), `idle` (resident between turns, possibly waiting on agents it started), or `ready` (storage only and resumable rather than terminal). The service result also contains one-shot session-backed subagents for consumers such as a UI, but those entries are omitted from this model tool because they cannot accept `send_message`. Diagnostics remain visible, with positions in the descendants scope. Durable identity and mode come from each child's descriptor, while delivery-time authority and Activation ownership checks remain the service's.
12
12
 
13
13
  ## Model Experience
14
14
 
@@ -58,7 +58,7 @@ Append-only; newly visible content follows the reusable request prefix and does
58
58
 
59
59
  #### What the model sees
60
60
 
61
- One line per continuable child in stable catalog order: `<id> [<status>] — <label>` (`running` = active driver, `idle` = resident between turns, `complete` = storage only; a direct child in that state can be resumed by `send_message`), plus `<id> [diagnostic: <reason>]` for a candidate that could not be read (`corrupt`, `unsupported`, or `unavailable`). The `descendants` scope inserts ` parent=<id> depth=<n>` before the label dash on every line, in pre-order. One-shot children are intentionally absent; `(no subagents)` means no continuable child or diagnostic survived the projection. Diagnostics never expose descriptor contents.
61
+ One line per continuable child in stable catalog order: `<id> [<status>] — <label>` (`running` = active driver, `idle` = resident between turns, `ready` = storage only; resumable rather than terminal, not a result waiting to be collected — a direct child in that state can be resumed by `send_message`), plus `<id> [diagnostic: <reason>]` for a candidate that could not be read (`corrupt`, `unsupported`, or `unavailable`). The `descendants` scope inserts ` parent=<id> depth=<n>` before the label dash on every line, in pre-order. One-shot children are intentionally absent; `(no subagents)` means no continuable child or diagnostic survived the projection. Diagnostics never expose descriptor contents.
62
62
 
63
63
  #### Token effect
64
64
 
@@ -72,5 +72,5 @@ Append-only; each result follows the reusable request prefix.
72
72
 
73
73
  - **A queued message has no independent result** — acceptance returns only its inbox `messageId`; the child's work lands in the durable child Session and is never collected through this tool. A child granted `report` may send selected content back separately, but that message is not this call's result.
74
74
  - **No steering of the current turn** — every message opens a later FIFO turn, so a message sent while the child is working runs only after its current turn finishes and cannot redirect it.
75
- - **Listing is a snapshot, not a delivery promise** — it may race publication, disposal, or a later message, and another process may activate a child this process reports as `complete`; cross-process accuracy requires a shared lease. `interrupt_agent` performs the authoritative live-lineage check itself, so discovery staleness cannot grant authority.
75
+ - **Listing is a snapshot, not a delivery promise** — it may race publication, disposal, or a later message, and another process may activate a child this process reports as `ready`; cross-process accuracy requires a shared lease. `interrupt_agent` performs the authoritative live-lineage check itself, so discovery staleness cannot grant authority.
76
76
  - **No pagination or deletion** — the complete stably ordered set is returned, and persisted children remain listed for as long as their sessions remain in persistence; a service-level bound or delete operation is a later product decision.
package/README.zh.md CHANGED
@@ -8,7 +8,7 @@
8
8
 
9
9
  `interrupt_agent(agent_id)` 将 `exec.agent` 作为 `ctx.subagents.interrupt()` 的确切在线 ancestor 授权传入：目标可以是直接 child 或更深的后代，由服务——而不是本工具——依据目标 Activation 记录的 lineage 校验调用方。只有目标的当前轮次会停止（`keepInbox`）：已排队的消息保持暂停直到之后的 `send_message`，已发布的后代继续运行，child 也仍可接受后续消息。调用在停止请求被接受后立即返回，不等待目标完全停稳；目标不存在或已结算是被接受的 no-op，而 self、sibling、过期与非 ancestor 调用方会成为出错结果。
10
10
 
11
- `list_agents` 接受一个可选的 `scope` 参数，会从调用它的 agent 推导根 id，并且不使用 cursor，将服务目录投影为可继续 child。默认的 `children` scope 读取 `ctx.subagents.listChildren()`；`descendants` 读取 `ctx.subagents.listDescendants()`，其单份语料的遍历会穿过普通会话与一次性 child，并按稳定 pre-order 以 `parent=<id> depth=<n>` 渲染保留下来的条目。`parent` 注释是持久化直接 parent 会话 id，可能指向输出中省略的普通会话。对于调用本工具的 agent，只有 depth-1 child 条目可作为 `send_message` 候选；更深的 child 条目只能作为 `interrupt_agent` 候选。状态来自在线 Agent 注册表：`running`（driver 活跃）、`idle`（驻留但处于轮次之间，可能在等待它启动的 agent）、`complete`（仅存于存储）。服务结果还包含由会话支撑的一次性 subagent，以供 UI 等消费方使用；但这些条目无法接受 `send_message`，因此会从这个模型工具中排除。diagnostic 仍然可见，并在 descendants scope 中带有位置。持久化身份和模式来自每个子 agent 的描述符，消息送达时的鉴权和 Activation 所有权检查仍归服务负责。
11
+ `list_agents` 接受一个可选的 `scope` 参数，会从调用它的 agent 推导根 id，并且不使用 cursor，将服务目录投影为可继续 child。默认的 `children` scope 读取 `ctx.subagents.listChildren()`；`descendants` 读取 `ctx.subagents.listDescendants()`，其单份语料的遍历会穿过普通会话与一次性 child，并按稳定 pre-order 以 `parent=<id> depth=<n>` 渲染保留下来的条目。`parent` 注释是持久化直接 parent 会话 id，可能指向输出中省略的普通会话。对于调用本工具的 agent，只有 depth-1 child 条目可作为 `send_message` 候选；更深的 child 条目只能作为 `interrupt_agent` 候选。状态来自在线 Agent 注册表：`running`（driver 活跃）、`idle`（驻留但处于轮次之间，可能在等待它启动的 agent）或 `ready`（仅存于存储，表示可恢复而非终态）。服务结果还包含由会话支撑的一次性 subagent，以供 UI 等消费方使用；但这些条目无法接受 `send_message`，因此会从这个模型工具中排除。diagnostic 仍然可见，并在 descendants scope 中带有位置。持久化身份和模式来自每个子 agent 的描述符，消息送达时的鉴权和 Activation 所有权检查仍归服务负责。
12
12
 
13
13
  ## 模型体验
14
14
 
@@ -58,7 +58,7 @@
58
58
 
59
59
  #### 模型看到的内容
60
60
 
61
- 按稳定目录顺序，每个可继续 child 占一行：渲染为 `<id> [<status>] — <label>`（`running` 表示 driver 活跃，`idle` 表示驻留但处于轮次之间，`complete` 表示仅存于存储；处于该状态的直接 child 可通过 `send_message` 恢复），另为无法读取的候选项渲染 `<id> [diagnostic: <reason>]`（`corrupt`、`unsupported` 或 `unavailable`）。`descendants` scope 会在每行 label 破折号之前插入 ` parent=<id> depth=<n>`，按 pre-order 排列。一次性 child 会被有意排除；`(no subagents)` 表示投影后没有留下可继续 child 或 diagnostic。诊断信息绝不会暴露描述符内容。
61
+ 按稳定目录顺序，每个可继续 child 占一行：渲染为 `<id> [<status>] — <label>`（`running` 表示 driver 活跃，`idle` 表示驻留但处于轮次之间，`ready` 表示仅存于存储；可恢复而非终态，也不表示有结果等待收集——处于该状态的直接 child 可通过 `send_message` 恢复），另为无法读取的候选项渲染 `<id> [diagnostic: <reason>]`（`corrupt`、`unsupported` 或 `unavailable`）。`descendants` scope 会在每行 label 破折号之前插入 ` parent=<id> depth=<n>`，按 pre-order 排列。一次性 child 会被有意排除；`(no subagents)` 表示投影后没有留下可继续 child 或 diagnostic。诊断信息绝不会暴露描述符内容。
62
62
 
63
63
  #### Token 影响
64
64
 
@@ -72,5 +72,5 @@
72
72
 
73
73
  - **已排队的消息没有独立结果**：接受时只返回其 inbox `messageId`；子 agent 的工作会落入持久化子 agent 会话，绝不会通过本工具收集。获得 `report` 的子 agent 可以单独发回选定内容，但该消息不是本次调用的结果。
74
74
  - **不对当前轮次进行 steering（中途引导）**：每条消息都会开启后续 FIFO 轮次，因此在子 agent 工作时发送的消息只会在其当前轮次结束后运行，无法将其重定向。
75
- - **列表是快照，而非投递承诺**：它可能与发布、dispose（资源释放）或后续消息发生竞态，另一个进程也可能激活当前进程报告为 `complete` 的 child；跨进程准确性需要共享租约。`interrupt_agent` 自己执行权威的在线 lineage 检查，因此过期的发现结果不会授予权限。
75
+ - **列表是快照，而非投递承诺**：它可能与发布、dispose（资源释放）或后续消息发生竞态，另一个进程也可能激活当前进程报告为 `ready` 的 child；跨进程准确性需要共享租约。`interrupt_agent` 自己执行权威的在线 lineage 检查，因此过期的发现结果不会授予权限。
76
76
  - **没有分页或删除**：系统返回完整且稳定排序的集合；只要 child 会话仍在持久化存储中，它就会继续出现在列表中，服务级上限或删除操作留待后续产品决策。
package/lib/index.js CHANGED
@@ -8,7 +8,7 @@ import { SessionId } from "@deepseek-ai/dsh-session";
8
8
  * residency, cold resume, and interrupt authorization belong to the subagent
9
9
  * service — and they live apart from the provider-bound
10
10
  * `@deepseek-ai/dsh-tool-subagent` instances so multiple delegation tools share
11
- * one control surface.
11
+ * one control API.
12
12
  * @module @deepseek-ai/dsh-tool-subagent-control
13
13
  */
14
14
  const name = "tool-subagent-control";
package/lib/types/index.d.ts CHANGED
@@ -5,7 +5,7 @@
5
5
  * residency, cold resume, and interrupt authorization belong to the subagent
6
6
  * service — and they live apart from the provider-bound
7
7
  * `@deepseek-ai/dsh-tool-subagent` instances so multiple delegation tools share
8
- * one control surface.
8
+ * one control API.
9
9
  * @module @deepseek-ai/dsh-tool-subagent-control
10
10
  */
11
11
  import type { Context } from '@deepseek-ai/cordis';
package/lib/types/index.js CHANGED
@@ -5,7 +5,7 @@
5
5
  * residency, cold resume, and interrupt authorization belong to the subagent
6
6
  * service — and they live apart from the provider-bound
7
7
  * `@deepseek-ai/dsh-tool-subagent` instances so multiple delegation tools share
8
- * one control surface.
8
+ * one control API.
9
9
  * @module @deepseek-ai/dsh-tool-subagent-control
10
10
  */
11
11
  import { defineTool } from '@deepseek-ai/dsh-tools';
package/lib/types/list-agents.js CHANGED
@@ -17,12 +17,14 @@ function resolveListAgentsRequest(request) {
17
17
  /**
18
18
  * Refine one candidate's status through the live Agent registry: `running`
19
19
  * for an active driver, `idle` for a resident Agent between turns (possibly
20
- * waiting on agents it started), and `complete` when no live Agent remains.
20
+ * waiting on agents it started), and `ready` when no live Agent remains.
21
+ * `ready` preserves resumability without presenting an inactive conversation
22
+ * as a terminal result to collect.
21
23
  */
22
24
  function statusOf(agents, id) {
23
25
  const agent = agents.get(id);
24
26
  if (agent === undefined)
25
- return 'complete';
27
+ return 'ready';
26
28
  return agent.status === 'running' ? 'running' : 'idle';
27
29
  }
28
30
  /** Project one service row into the model-facing entry, or omit a one-shot child. */
@@ -50,10 +52,12 @@ function project(agents, entry, position) {
50
52
  export function apply(ctx) {
51
53
  ctx.tools.register(defineTool({
52
54
  name: 'list_agents',
53
- description: 'List your continuable background subagents by durable id and label. Status comes from the live '
55
+ description: 'List your continuable background subagents by durable id and label. Use it to recall which ones '
56
+ + 'you started, not to poll for completion — you are told when one finishes. Status comes from the live '
54
57
  + 'registry: running means the agent is working right now, idle means it is loaded but between turns '
55
- + '(it may be waiting on agents it started), and complete means it exists only in storage — a '
56
- + 'direct child remains a `send_message` candidate in every status. The snapshot is not a delivery '
58
+ + '(it may be waiting on agents it started), and ready means it exists only in storage — resumable, not '
59
+ + 'terminal, and not a result waiting to be collected; a `send_message` starts a new turn on the same '
60
+ + 'conversation, and a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery '
57
61
  + 'promise — `send_message` performs the authoritative check and may still fail. Children that could '
58
62
  + 'not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` '
59
63
  + 'walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent '
@@ -78,7 +82,7 @@ export function apply(ctx) {
78
82
  kind: { type: 'string', required: true, enum: ['child'] },
79
83
  id: { type: 'string', required: true },
80
84
  label: { type: 'string', required: true },
81
- status: { type: 'string', required: true, enum: ['running', 'idle', 'complete'] },
85
+ status: { type: 'string', required: true, enum: ['running', 'idle', 'ready'] },
82
86
  parent: { type: 'string' },
83
87
  depth: { type: 'number' },
84
88
  },
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@deepseek-ai/dsh-tool-subagent-control",
3
3
  "description": "Globally named send_message, interrupt_agent, and list_agents tools over ctx.subagents continuations",
4
- "version": "0.0.1-rc.1",
4
+ "version": "0.0.1-rc.2",
5
5
  "publishConfig": {
6
6
  "access": "restricted"
7
7
  },
@@ -37,26 +37,26 @@
37
37
  ],
38
38
  "license": "BSD-3-Clause",
39
39
  "peerDependencies": {
40
- "@deepseek-ai/dsh-llm": "^0.0.1-rc.1",
41
- "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
42
- "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
43
- "@deepseek-ai/dsh-subagent": "^0.0.1-rc.1",
40
+ "@deepseek-ai/dsh-invariants": "^0.0.1-rc.2",
41
+ "@deepseek-ai/dsh-session": "^0.0.1-rc.2",
42
+ "@deepseek-ai/dsh-tools": "^0.0.1-rc.2",
44
43
  "@deepseek-ai/cordis": "^4.0.1-rc.1",
45
- "@deepseek-ai/dsh-tools": "^0.0.1-rc.1"
44
+ "@deepseek-ai/dsh-subagent": "^0.0.1-rc.2",
45
+ "@deepseek-ai/dsh-llm": "^0.0.1-rc.2"
46
46
  },
47
47
  "devDependencies": {
48
- "@deepseek-ai/dsh-agent": "^0.0.1-rc.1",
49
- "@deepseek-ai/dsh-agent-loop-testkit": "^0.0.1-rc.1",
50
- "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
51
- "@deepseek-ai/dsh-llm": "^0.0.1-rc.1",
52
- "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
53
- "@deepseek-ai/dsh-agent-loop": "^0.0.1-rc.1",
54
- "@deepseek-ai/dsh-session-persistence": "^0.0.1-rc.1",
55
- "@deepseek-ai/dsh-session-persistence-jsonl": "^0.0.1-rc.1",
56
- "@deepseek-ai/dsh-session-projection": "^0.0.1-rc.1",
57
- "@deepseek-ai/dsh-subagent": "^0.0.1-rc.1",
58
- "@deepseek-ai/dsh-subagent-spawn": "^0.0.1-rc.1",
59
- "@deepseek-ai/dsh-tools": "^0.0.1-rc.1",
48
+ "@deepseek-ai/dsh-agent": "^0.0.1-rc.2",
49
+ "@deepseek-ai/dsh-agent-loop-testkit": "^0.0.1-rc.2",
50
+ "@deepseek-ai/dsh-agent-loop": "^0.0.1-rc.2",
51
+ "@deepseek-ai/dsh-invariants": "^0.0.1-rc.2",
52
+ "@deepseek-ai/dsh-llm": "^0.0.1-rc.2",
53
+ "@deepseek-ai/dsh-session": "^0.0.1-rc.2",
54
+ "@deepseek-ai/dsh-session-persistence": "^0.0.1-rc.2",
55
+ "@deepseek-ai/dsh-session-persistence-jsonl": "^0.0.1-rc.2",
56
+ "@deepseek-ai/dsh-session-projection": "^0.0.1-rc.2",
57
+ "@deepseek-ai/dsh-subagent": "^0.0.1-rc.2",
58
+ "@deepseek-ai/dsh-subagent-spawn": "^0.0.1-rc.2",
59
+ "@deepseek-ai/dsh-tools": "^0.0.1-rc.2",
60
60
  "@deepseek-ai/cordis": "^4.0.1-rc.1"
61
61
  }
62
62
  }