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

package/README.i18n.yaml

@@ -1,6 +1,106 @@
-# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
-# 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:
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# 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: 2cfa000f1ba9f7950b28369a9b7bd3523610b579
-README.zh.md: f2154fde965899e7b4f30271846bce52414b010d
+/:
+  en: 5413b8e52a0c8e3d
+  zh: 9b6d0385209ff9bb
+/deepseek-ai-dsh-tool-subagent-control:
+  en: 465d36925c792167
+  zh: 269cac314f638827
+/deepseek-ai-dsh-tool-subagent-control/summary:
+  en: 7464eb99b6f618eb
+  zh: 8c7628c8e9f163ca
+/deepseek-ai-dsh-tool-subagent-control/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 09388d293f9be9cb
+/deepseek-ai-dsh-tool-subagent-control/use-this-package:
+  en: 27c5bbe682f0b72b
+  zh: b16aeb2c43f3692e
+/deepseek-ai-dsh-tool-subagent-control/use-this-package/minimal-configuration:
+  en: 4a52c81317ec9001
+  zh: ebd9f1ba920da50a
+/deepseek-ai-dsh-tool-subagent-control/use-this-package/send-message:
+  en: d80bb1df2eb740b7
+  zh: e3203d9868a82910
+/deepseek-ai-dsh-tool-subagent-control/use-this-package/interrupt-agent:
+  en: 01dd41fe11f294d7
+  zh: f45a2e4073c0b206
+/deepseek-ai-dsh-tool-subagent-control/use-this-package/list-agents:
+  en: b777ad75f0eb7a59
+  zh: 19275aba6573a917
+/deepseek-ai-dsh-tool-subagent-control/understand-the-implementation:
+  en: c5cdf01a78c990f2
+  zh: 53c180d726ce4502
+/deepseek-ai-dsh-tool-subagent-control/understand-the-implementation/design-concept:
+  en: 0af7238c690ee8d6
+  zh: 5049eea23770ffed
+/deepseek-ai-dsh-tool-subagent-control/understand-the-implementation/delivery-and-signal-ownership:
+  en: 4c7698ccea49a60b
+  zh: fbf129ff583e6ab9
+/deepseek-ai-dsh-tool-subagent-control/understand-the-implementation/listing-projection:
+  en: 70e344022e6e535e
+  zh: 355488590648a82e
+/deepseek-ai-dsh-tool-subagent-control/understand-the-implementation/source-map:
+  en: a2a918cbad1a8313
+  zh: 5bcddba1b2bdd26e
+/deepseek-ai-dsh-tool-subagent-control/further-exploration:
+  en: df2bf39d0ffffd43
+  zh: 4cd02551f7433c90
+/deepseek-ai-dsh-tool-subagent-control/model-experience:
+  en: 215e7ba838619b7b
+  zh: a311da3843709f90
+/deepseek-ai-dsh-tool-subagent-control/model-experience/tool-schema:
+  en: e4c7376d4f29dbd5
+  zh: 6b7a9eaf69c9ea53
+/deepseek-ai-dsh-tool-subagent-control/model-experience/tool-schema/what-the-model-sees:
+  en: a63be096ee9c4873
+  zh: cd1bd116ccc66318
+/deepseek-ai-dsh-tool-subagent-control/model-experience/tool-schema/token-effect:
+  en: db207dc8d5860684
+  zh: ad2663b4967fbca9
+/deepseek-ai-dsh-tool-subagent-control/model-experience/tool-schema/kv-cache-effect:
+  en: 4b77d42b96b3519d
+  zh: dd393d8f0f6536c1
+/deepseek-ai-dsh-tool-subagent-control/model-experience/interrupt-result:
+  en: d64e936e83e89a2b
+  zh: b9905c33af6cca45
+/deepseek-ai-dsh-tool-subagent-control/model-experience/interrupt-result/what-the-model-sees:
+  en: 89305619897680ba
+  zh: e610a844fc09c53f
+/deepseek-ai-dsh-tool-subagent-control/model-experience/interrupt-result/token-effect:
+  en: 5d1bcef28b5f18da
+  zh: 027d67d93d660e76
+/deepseek-ai-dsh-tool-subagent-control/model-experience/interrupt-result/kv-cache-effect:
+  en: 4a629edb36a17e32
+  zh: 5a7539cfbf404c54
+/deepseek-ai-dsh-tool-subagent-control/model-experience/delivery-result:
+  en: ab964e307bd37dca
+  zh: 03f975252f838a42
+/deepseek-ai-dsh-tool-subagent-control/model-experience/delivery-result/what-the-model-sees:
+  en: 4a0a4955589012ae
+  zh: 2bbbb5196a8aa4fd
+/deepseek-ai-dsh-tool-subagent-control/model-experience/delivery-result/token-effect:
+  en: 0f134e37e4bd9965
+  zh: ceb858d01266e976
+/deepseek-ai-dsh-tool-subagent-control/model-experience/delivery-result/kv-cache-effect:
+  en: f5d5f97a153f7c70
+  zh: 3d6bc05b9eadfbc2
+/deepseek-ai-dsh-tool-subagent-control/model-experience/listing-result:
+  en: 094e55d258f2ec2e
+  zh: f364bc9046530bff
+/deepseek-ai-dsh-tool-subagent-control/model-experience/listing-result/what-the-model-sees:
+  en: efbbd1e36c7b2edd
+  zh: a8a95475666ed1dc
+/deepseek-ai-dsh-tool-subagent-control/model-experience/listing-result/token-effect:
+  en: 4688e849b3143dfc
+  zh: f22b5520c454f9e7
+/deepseek-ai-dsh-tool-subagent-control/model-experience/listing-result/kv-cache-effect:
+  en: 4a629edb36a17e32
+  zh: 5a7539cfbf404c54
+/deepseek-ai-dsh-tool-subagent-control/known-limitations-and-deferred-work:
+  en: 31cd8a1934cf0093
+  zh: 2fd07e05c8e58e9a
+/deepseek-ai-dsh-tool-subagent-control/known-limitations-and-deferred-work/dev-note:
+  en: e67f633dc6fe7773
+  zh: 3bb0c20c93f16f98

package/README.md

@@ -54,7 +54,7 @@ Stops only the target's current turn: queued messages stay parked until a later
 
 ### list_agents
 
-Lists the continuable children below the calling agent: `children` (default) reads direct children from the parent catalog without opening child logs; `descendants` walks the whole tree in stable pre-order, annotating each entry with its durable direct-parent session id and depth. Status comes from the live Agent registry — `running` or `inactive`. One-shot children are intentionally absent because they cannot accept `send_message`, and unreadable candidates appear as diagnostics only in `descendants` scope.
+Lists the continuable children below the calling agent: `children` (default) reads direct children from the parent catalog without opening child logs; `descendants` recursively reads child catalogs in stable pre-order, annotating each entry with its durable direct-parent session id and depth. Status comes from the live Agent registry — `running` or `inactive`. Readable one-shot children are omitted from output but their catalogs remain traversal nodes. Unknown modes and unreadable child catalogs, including one-shot children, appear as diagnostics only in `descendants` scope. Ordinary Session forks are not catalog entries, so neither those forks nor their descendants are listed from the source Session.
 
 -----
 
@@ -76,7 +76,7 @@ The tool forwards its execution signal, which owns admission only until inbox ac
 
 ### Listing projection
 
-`list_agents` derives the root id from the calling agent, reads the service catalog without a cursor, refines each candidate's status through the live Agent registry, and omits one-shot children because they cannot accept `send_message`. Diagnostics keep their positions in the descendants scope and never expose descriptor contents.
+`list_agents` derives the root id from the calling agent, reads the service catalog without a cursor, refines each candidate's status through the live Agent registry, and omits one-shot children because they cannot accept `send_message`. Descendant traversal preserves each parent catalog's event order. Unknown modes produce diagnostics while their catalogs remain traversable; unreadable catalogs produce diagnostics and stop that branch. Descendants absent from reachable catalogs cannot be discovered.
 
 ### Source map
 
@@ -150,11 +150,11 @@ Append-only; newly visible content follows the reusable request prefix and does
 
 #### What the model sees
 
-One line per continuable child in stable catalog order: `<id> [<status>] — <label>` (`running` = executing a turn; `inactive` = no turn executing, whether loaded or stored; neither status describes task completion or outcome). Only `descendants` scope adds `<id> [diagnostic: <reason>]` for a candidate that could not be read. 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.
+One line per continuable child in stable catalog order: `<id> [<status>] — <label>` (`running` = executing a turn; `inactive` = no turn executing, whether loaded or stored; neither status describes task completion or outcome). Only `descendants` scope adds `<id> [diagnostic: <reason>]` for an unknown mode or unreadable child catalog, including an unreadable one-shot child. The `descendants` scope inserts ` parent=<id> depth=<n>` before the label dash on every line, in pre-order. Readable one-shot children are omitted; `(no subagents)` means no continuable child or diagnostic survived the projection.
 
 #### Token effect
 
-Grows linearly with the listed continuable children — the whole tree under the `descendants` scope; there is no cursor or cap, so long-lived parents with many persisted children pay the full list each call.
+Grows linearly with the listed continuable children and diagnostics — reachable catalog descendants under the `descendants` scope; there is no cursor or cap, so long-lived parents with many persisted children pay the full list each call.
 
 #### KV Cache effect
 

package/README.zh.md

@@ -54,7 +54,7 @@ kind: "package-reference"
 
 ### list_agents
 
-列出调用方 agent 下方的可继续子级：`children`（默认）从父目录读取直接子级，不打开子日志；`descendants` 按稳定前序遍历整棵树，并为每个条目标注其持久化直接父级会话 ID 与深度。状态来自在线 Agent 注册表——`running` 或 `inactive`。一次性子级因无法接受 `send_message` 而被有意排除，无法读取的候选项仅在 `descendants` 作用域中以诊断信息呈现。
+列出调用方 agent 下方的可继续子级：`children`（默认）从父目录读取直接子级，不打开子日志；`descendants` 按稳定前序递归读取子级目录，并为每个条目标注其持久化直接父级会话 ID 与深度。状态来自在线 Agent 注册表——`running` 或 `inactive`。可读取的一次性子级不出现在输出中，但其目录仍是遍历节点。未知模式与无法读取的子级目录（包括一次性子级）仅在 `descendants` 作用域中以诊断信息呈现。普通 Session fork 不是目录条目，因此从源 Session 列表中既无法发现这些 fork，也无法发现其后代。
 
 -----
 
@@ -76,7 +76,7 @@ kind: "package-reference"
 
 ### 列表投影
 
-`list_agents` 从调用 agent 推导根 id，不使用 cursor 读取服务目录，通过在线 Agent 注册表细化每个候选的状态，并省略无法接受 `send_message` 的一次性子级。diagnostic 在 descendants scope 中保留其位置，且绝不暴露描述符内容。
+`list_agents` 从调用 agent 推导根 id，不使用 cursor 读取服务目录，通过在线 Agent 注册表细化每个候选的状态，并省略无法接受 `send_message` 的一次性子级。后代遍历保留每个父目录的事件顺序。未知模式产生诊断，但其目录仍可遍历；无法读取的目录产生诊断，并停止该分支。可达目录中不存在的后代无法被发现。
 
 ### 源码地图
 
@@ -150,11 +150,11 @@ kind: "package-reference"
 
 #### 模型看到什么
 
-按稳定目录顺序，每个可继续子级占一行：`<id> [<status>] — <label>`（`running` 表示正在执行轮次；`inactive` 表示没有轮次在执行，包括已加载和仅存于存储的情况；两种状态均不表示任务完成或结果）。仅 `descendants` 作用域会为无法读取的候选项添加 `<id> [diagnostic: <reason>]`。`descendants` 作用域会在每行标签的破折号之前按前序插入 ` parent=<id> depth=<n>`。一次性子级会被有意排除；`(no subagents)` 表示投影后没有留下可继续子级或诊断信息。
+按稳定目录顺序，每个可继续子级占一行：`<id> [<status>] — <label>`（`running` 表示正在执行轮次；`inactive` 表示没有轮次在执行，包括已加载和仅存于存储的情况；两种状态均不表示任务完成或结果）。仅 `descendants` 作用域会为未知模式或无法读取的子级目录添加 `<id> [diagnostic: <reason>]`，包括无法读取的一次性子级。`descendants` 作用域会在每行标签的破折号之前按前序插入 ` parent=<id> depth=<n>`。可读取的一次性子级会被省略；`(no subagents)` 表示投影后没有留下可继续子级或诊断信息。
 
 #### Token 影响
 
-随所列可继续子级数量线性增长——`descendants` 作用域下为整棵树；没有游标或上限，因此长期存活且有许多持久化子级的父级每次调用都会承担完整列表成本。
+随所列可继续子级和诊断数量线性增长——`descendants` 作用域下为目录可达后代；没有游标或上限，因此长期存活且有许多持久化子级的父级每次调用都会承担完整列表成本。
 
 #### KV Cache 影响
 

package/lib/index.js

@@ -21,7 +21,7 @@ const inject = ["tools", "subagents"];
 function apply(ctx) {
 	ctx.tools.register(markAdjacentAgentSendMessageTool(defineTool({
 		name: "send_message",
-		description: "Send a message to a direct continuable child by its agent id. If you are a resident continuable child, you may also target your direct parent. If the target is still working, the message steers its nearest step; if it is inactive, the message starts or resumes a turn. This call returns no answer from the agent — only confirmation that the message was delivered. A failure means the message was NOT delivered.",
+		description: "Send a message to an agent. A working agent receives it at its next step; an idle agent starts a new turn with it. Returns delivery confirmation, not the agent's answer.",
 		parameters: {
 			agent_id: {
 				type: "string",
@@ -60,11 +60,11 @@ function apply(ctx) {
 	})));
 	ctx.tools.register(defineTool({
 		name: "interrupt_agent",
-		description: "Request cancellation of a background agent's current turn by its agent id. The target may be your direct child or a deeper agent created under you. Only the current turn stops: messages already queued for the agent stay parked until a later send_message, agents it started keep running, and the agent itself stays available for follow-ups. This call returns as soon as the stop request is accepted, so the target may keep running briefly; interrupting an agent that already finished is an accepted no-op.",
+		description: "Ask a subagent to stop its current work. This call returns without waiting for it to stop. You can continue a direct child's conversation later with send_message. Subagents it started will keep running.",
 		parameters: { agent_id: {
 			type: "string",
 			required: true,
-			description: "The agent id of the running agent to interrupt."
+			description: "The id of an agent created under you: your direct child or a deeper descendant."
 		} },
 		output: {
 			schema: {

package/lib/types/index.js

@@ -20,10 +20,8 @@ export const inject = ['tools', 'subagents'];
 export function apply(ctx) {
     ctx.tools.register(markAdjacentAgentSendMessageTool(defineTool({
         name: 'send_message',
-        description: 'Send a message to a direct continuable child by its agent id. If you are a resident continuable child, '
-            + 'you may also target your direct parent. If the target is still working, the message steers its nearest step; '
-            + 'if it is inactive, the message starts or resumes a turn. This call returns no answer from the agent — only confirmation '
-            + 'that the message was delivered. A failure means the message was NOT delivered.',
+        description: 'Send a message to an agent. A working agent receives it at its next step; an idle agent starts a new turn with it. '
+            + 'Returns delivery confirmation, not the agent\'s answer.',
         parameters: {
             agent_id: {
                 type: 'string',
@@ -61,17 +59,14 @@ export function apply(ctx) {
     })));
     ctx.tools.register(defineTool({
         name: 'interrupt_agent',
-        description: 'Request cancellation of a background agent\'s current turn by its agent id. The target may be your '
-            + 'direct child or a deeper agent created under you. Only the current turn stops: messages already '
-            + 'queued for the agent stay parked until a later send_message, agents it started keep running, and '
-            + 'the agent itself stays available for follow-ups. This call returns as soon as the stop request is '
-            + 'accepted, so the target may keep running briefly; interrupting an agent that already finished is '
-            + 'an accepted no-op.',
+        description: 'Ask a subagent to stop its current work. This call returns without waiting for it to stop. '
+            + 'You can continue a direct child\'s conversation later with send_message. '
+            + 'Subagents it started will keep running.',
         parameters: {
             agent_id: {
                 type: 'string',
                 required: true,
-                description: 'The agent id of the running agent to interrupt.',
+                description: 'The id of an agent created under you: your direct child or a deeper descendant.',
             },
         },
         output: {

package/lib/types/list-agents.js

@@ -43,23 +43,16 @@ function project(agents, entry, position) {
 export function apply(ctx) {
     ctx.tools.register(defineTool({
         name: 'list_agents',
-        description: 'List your continuable background subagents by durable id and label. Use it to recall which ones '
-            + 'you started, not to poll for completion — you are told when one finishes. Status comes from the live '
-            + 'registry: running means the agent is working right now; inactive means no turn is executing, whether '
-            + 'the child is loaded or must be resumed. inactive does not describe task completion, success, failure, '
-            + 'or waiting for other agents. A `send_message` steers a running child at its nearest step boundary '
-            + 'or starts or resumes a turn for an inactive child, and a direct child remains a `send_message` '
-            + 'candidate in every status. The snapshot is not a delivery '
-            + 'promise — `send_message` performs the authoritative check and may still fail. Children that could '
-            + 'not be read are reported as diagnostics only in `descendants` scope. Scope `descendants` '
-            + 'walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent '
-            + 'session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are '
-            + 'candidates for `interrupt_agent` only.',
+        description: 'List subagents you started, with their ids, labels, and status. '
+            + 'running means it is working; inactive means it is not currently working. '
+            + 'You will be notified when a subagent finishes; there is no need to keep checking its status. '
+            + 'Use send_message to continue the conversation.',
         parameters: {
             scope: {
                 type: 'string',
                 enum: ['children', 'descendants'],
-                description: 'children (default) lists direct children only; descendants walks the complete tree below you.',
+                description: 'children (default) lists direct children, which accept send_message in any status. '
+                    + 'descendants lists the whole tree below you with each entry\'s parent session id and depth; entries deeper than 1 accept only interrupt_agent.',
             },
         },
         output: {
@@ -128,7 +121,6 @@ export function apply(ctx) {
                         .filter(entry => entry !== undefined);
                 }
                 case 'descendants': {
-                    // Complete-corpus reads can await storage, so they observe tool cancellation.
                     const entries = await ctx.subagents.listDescendants(parent.id, exec.signal);
                     return entries
                         .map(entry => project(ctx.agents, entry, entry))

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-tool-subagent-control",
   "description": "Globally named send_message, interrupt_agent, and list_agents tools over ctx.subagents continuations",
-  "version": "0.1.7-rc.1",
+  "version": "0.1.7-rc.2",
   "publishConfig": {
     "access": "public"
   },
@@ -32,30 +32,30 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/cordis": "~4.0.4",
-    "@deepseek-ai/dsh-llm": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-session": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-subagent": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-tools": "0.1.7-rc.1"
+    "@deepseek-ai/dsh-llm": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-session": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-subagent": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-tools": "0.1.7-rc.2",
+    "@deepseek-ai/cordis": "~4.0.4"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "~4.0.4",
-    "@deepseek-ai/dsh-agent": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-agent-loop": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-agent-loop-testkit": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-llm": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-session": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-session-projection": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-session-query": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-subagent": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-subagent-fork-in-process": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-subagent-spawn-in-process": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-tools": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-session-persistence": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-session-persistence-jsonl": "0.1.7-rc.1"
+    "@deepseek-ai/dsh-agent-loop": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-agent-loop-testkit": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-agent": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-session": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-session-persistence-jsonl": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-llm": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-session-persistence": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-session-projection": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-session-query": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-subagent": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-subagent-spawn-in-process": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-subagent-fork-in-process": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-tools": "0.1.7-rc.2"
   },
   "dependencies": {
-    "@deepseek-ai/dsh-brand": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-util-values": "0.1.7-rc.1"
+    "@deepseek-ai/dsh-brand": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-util-values": "0.1.7-rc.2"
   }
 }