{"_id":"@buddhilive/dsh-tool-subagent-control","name":"@buddhilive/dsh-tool-subagent-control","dist-tags":{"alpha":"0.1.2-alpha.3","latest":"0.1.2-alpha.3"},"versions":{"0.1.2-alpha.3":{"name":"@buddhilive/dsh-tool-subagent-control","description":"Globally named send_message, interrupt_agent, and list_agents tools over ctx.subagents continuations","version":"0.1.2-alpha.3","publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/Buddhilive/buddhi-ai-harness.git","directory":"packages/subagent/tool-subagent-control"},"type":"module","main":"lib/index.js","types":"lib/types/index.d.ts","exports":{".":{"types":"./lib/types/index.d.ts","default":"./lib/index.js"},"./invariant":{"types":"./lib/types/invariant.d.ts","default":"./lib/invariant.js"},"./list-agents":{"types":"./lib/types/list-agents.d.ts","default":"./lib/types/list-agents.js"},"./src/*":"./src/*","./package.json":"./package.json"},"license":"MIT","peerDependencies":{"@deepseek-ai/cordis":"^4.0.2","@buddhilive/dsh-invariants":"^0.1.2-alpha.3","@buddhilive/dsh-llm":"^0.1.2-alpha.3","@buddhilive/dsh-session":"^0.1.2-alpha.3","@buddhilive/dsh-subagent":"^0.1.2-alpha.3","@buddhilive/dsh-tools":"^0.1.2-alpha.3"},"devDependencies":{"@buddhilive/dsh-agent":"^0.1.2-alpha.3","@deepseek-ai/cordis":"^4.0.2","@buddhilive/dsh-agent-loop":"^0.1.2-alpha.3","@buddhilive/dsh-invariants":"^0.1.2-alpha.3","@buddhilive/dsh-llm":"^0.1.2-alpha.3","@buddhilive/dsh-agent-loop-testkit":"^0.1.2-alpha.3","@buddhilive/dsh-session":"^0.1.2-alpha.3","@buddhilive/dsh-session-persistence":"^0.1.2-alpha.3","@buddhilive/dsh-session-persistence-jsonl":"^0.1.2-alpha.3","@buddhilive/dsh-subagent":"^0.1.2-alpha.3","@buddhilive/dsh-session-projection":"^0.1.2-alpha.3","@buddhilive/dsh-session-query":"^0.1.2-alpha.3","@buddhilive/dsh-tools":"^0.1.2-alpha.3","@buddhilive/dsh-subagent-spawn-in-process":"^0.1.2-alpha.3"},"dependencies":{"@buddhilive/dsh-brand":"^0.1.2-alpha.3","@buddhilive/dsh-util-values":"^0.1.2-alpha.3"},"_id":"@buddhilive/dsh-tool-subagent-control@0.1.2-alpha.3","bugs":{"url":"https://github.com/Buddhilive/buddhi-ai-harness/issues"},"homepage":"https://github.com/Buddhilive/buddhi-ai-harness#readme","_integrity":"sha512-JtBe4la9YYdw4c4Mc5SJVnIRLOMiUHK9Nx3VoyE5GZ8NAiYEIlabV5XWGUhF1NRFpACQafGrmGL70p0g8dojHw==","_resolved":"C:\\DevDojo\\Buddhi\\buddhi-ai-harness\\dist\\npm\\buddhilive-dsh-tool-subagent-control-0.1.2-alpha.3.tgz","_from":"file:C:/DevDojo/Buddhi/buddhi-ai-harness/dist/npm/buddhilive-dsh-tool-subagent-control-0.1.2-alpha.3.tgz","_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-JtBe4la9YYdw4c4Mc5SJVnIRLOMiUHK9Nx3VoyE5GZ8NAiYEIlabV5XWGUhF1NRFpACQafGrmGL70p0g8dojHw==","shasum":"b89525bf32267bfa5e924eba596f2034f9e98122","tarball":"https://registry.npmjs.org/@buddhilive/dsh-tool-subagent-control/-/dsh-tool-subagent-control-0.1.2-alpha.3.tgz","fileCount":13,"unpackedSize":44084,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCky1/V3IMRziWVj167QtufCL95ngeZB9lyNCOASwJnUQIhAO5QxIFTsC95iio2WLBEofR8Ji/KhKv8vXaGW3Bn00p9"}]},"_npmUser":{"name":"buddhilive","email":"visitbudkavin@gmail.com"},"directories":{},"maintainers":[{"name":"buddhilive","email":"visitbudkavin@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/dsh-tool-subagent-control_0.1.2-alpha.3_1788165918005_0.46405447147682133"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-31T08:45:17.821Z","0.1.2-alpha.3":"2026-08-31T08:45:18.162Z","modified":"2026-08-31T08:45:18.431Z"},"maintainers":[{"name":"buddhilive","email":"visitbudkavin@gmail.com"}],"description":"Globally named send_message, interrupt_agent, and list_agents tools over ctx.subagents continuations","homepage":"https://github.com/Buddhilive/buddhi-ai-harness#readme","repository":{"type":"git","url":"git+https://github.com/Buddhilive/buddhi-ai-harness.git","directory":"packages/subagent/tool-subagent-control"},"bugs":{"url":"https://github.com/Buddhilive/buddhi-ai-harness/issues"},"license":"MIT","readme":"---\ndescription: \"全局 send_message、interrupt_agent 与 list_agents 工具，供用户与维护者组合或排查可继续子级的控制。\"\nkind: \"package-reference\"\n---\n\n# @buddhilive/dsh-tool-subagent-control\n\n[English](README.md) | 中文\n\n## 概述\n\n`dsh-tool-subagent-control` 为可继续子级添加全局控制工具：`send_message` 投递一条成为子级下一轮次的后续消息，`interrupt_agent` 停止子级当前轮次但保留其队列与后代，`list_agents`（来自可单独加载的 `list-agents` 插件）按持久化 id 与标签列出可继续子级。这些工具是全局的，因此任意数量的委派工具都不会产生重复。这些工具只覆盖父到子方向；子到父方向属于独立安装的 `dsh-tool-subagent-report`。是否加载这些工具不会决定委派工具是否启动可继续工作。\n\n## 目录\n\n- [使用本包](#use-this-package)\n- [理解实现](#understand-the-implementation)\n- [进一步探索](#further-exploration)\n- [模型体验](#model-experience)\n- [已知限制与延期工作](#known-limitations-and-deferred-work)\n- [开发备注](#dev-note)\n\n-----\n\n<a id=\"use-this-package\"></a>\n## 使用本包\n\n在模型需要对可继续子级发消息、中断或列出的任何组合中挂载本包。根插件只需要 subagent 服务；列表工具是独立插件，部署方可以省略。\n\n### 最小配置\n\n先加载 subagent 服务、一个后端、委派工具与本包。加上独立的列表插件即可公开全部三个工具：\n\n```yaml\n- name: '@buddhilive/dsh-subagent'\n- name: '@buddhilive/dsh-subagent-spawn-in-process'\n- name: '@buddhilive/dsh-tool-subagent'\n  config:\n    provider: spawn\n    backgroundMode: continuable\n- name: '@buddhilive/dsh-tool-subagent-control'\n- name: '@buddhilive/dsh-tool-subagent-control/list-agents'\n```\n\n本包不接收任何配置：根插件提供 `send_message` 与 `interrupt_agent`，列表插件提供 `list_agents`。\n\n### send_message\n\n发送一条消息，使之成为子级的下一 FIFO 轮次：正在工作的子级会先完成其当前轮次，因此消息无法重定向已经进行的工作。调用只返回接受结果（被接受消息的稳定 `messageId`），绝不返回子级的回复——通过其 id 查看子级 transcript（文本记录）才是它完成了哪些工作的真源。失败——未授权或未知子级、缺少描述符而无法恢复的子级，或准入被拒——会明确说明消息未送达。\n\n### interrupt_agent\n\n只停止目标当前轮次：已排队消息保持暂停直到之后的 `send_message`，后代继续运行，子级仍可接受后续消息。调用在停止请求被接受后立即返回，不等待目标完全停稳；中断已结束的 agent 是被接受的 no-op，而 self、sibling、陈旧与非 ancestor 调用方会收到出错结果。\n\n### list_agents\n\n列出调用 agent 下方的可继续子级：`children`（默认）只显示直接子级，`descendants` 按稳定 pre-order 遍历整棵树，并为每个条目标注其持久化直接父级会话 id 与深度。状态来自在线 Agent 注册表——`running`、`idle` 或 `ready`。一次性子级因无法接受 `send_message` 而被有意排除，无法读取的候选项以 diagnostic 呈现。\n\n-----\n\n<a id=\"understand-the-implementation\"></a>\n## 理解实现\n\n<details>\n<summary>实现细节——点击展开</summary>\n\n本节解释工具把什么委托给 subagent 服务；可观察行为已在[使用本包](#use-this-package)中说明。\n\n### 设计理念\n\n`ctx.subagents.followup()`、`interrupt()` 与列表投影之上的轻量适配器；工具不执行任何生命周期路由。驻留、冷恢复与中断授权归服务所有，工具把确切在线的调用 agent（`exec.agent`）作为服务对照目标已记录 lineage 校验的权限凭据传入。\n\n### 投递与信号所有权\n\n工具转发其执行信号，该信号只在 inbox 接受之前掌管准入。子级一旦接受消息，已接受的轮次便无法再通过本工具取消。每条消息都记录协调者来源 `{ kind: 'coordinator', senderSessionId: parent.id }`；服务会保留该来源，但绝不将其视为权限。\n\n### 列表投影\n\n`list_agents` 从调用 agent 推导根 id，不使用 cursor 读取服务目录，通过在线 Agent 注册表细化每个候选的状态，并省略无法接受 `send_message` 的一次性子级。diagnostic 在 descendants scope 中保留其位置，且绝不暴露描述符内容。\n\n### 源码地图\n\n| 文件 | 职责 |\n|---|---|\n| [`src/index.ts`](src/index.ts) | `send_message` 与 `interrupt_agent` 注册 |\n| [`src/list-agents.ts`](src/list-agents.ts) | `list_agents` 注册：作用域、状态细化、投影 |\n| [`src/invariant.ts`](src/invariant.ts) | 不变式伴生插件 |\n\n</details>\n\n-----\n\n<a id=\"further-exploration\"></a>\n## 进一步探索\n\n当包级约定不够用时阅读以下页面；它们从工具 schema 进入其背后的继续执行服务。\n\n- [Subagent 子系统](../../../docs/subsystems/subagent.zh.md)——可继续子级、Activation、inbox、中断与后续消息权限。\n- [dsh-tool-subagent](../tool-subagent/README.zh.md)——启动可继续子级的委派工具。\n- [dsh-tool-subagent-report](../tool-subagent-report/README.zh.md)——子到父的上报通道。\n- [生成工具目录](../../../docs/tool-catalog.zh.md#buddhilivedsh-tool-subagent-control)——三个工具的 schema。\n\n-----\n\n<a id=\"model-experience\"></a>\n## 模型体验\n\n### 工具 schema\n\n#### 模型看到什么\n\n已生成的 [schema](../../../docs/tool-catalog.zh.md#buddhilivedsh-tool-subagent-control)：`send_message` 接受 `subagent_id` 与 `message`；`interrupt_agent` 接受 `agent_id`；`list_agents` 接受可选的 `scope` 枚举。\n\n#### Token 影响\n\n每个父级请求支付固定的 schema 成本。\n\n#### KV Cache 影响\n\n前缀保持稳定；schema 不会在运行时改变。\n\n### 中断结果\n\n#### 模型看到什么\n\n接受时返回 `interrupt requested for agent <agent_id>`。未授权的调用方——self、sibling、陈旧或非 ancestor——会成为指明拒绝原因的出错结果；目标不存在或已结算仍渲染接受行。\n\n#### Token 影响\n\n每次调用产生一条简短确认消息；被中断轮次的中止只在子级自己的 transcript 中可见。\n\n#### KV Cache 影响\n\n仅追加；每个结果都位于可复用请求前缀之后。\n\n### 投递结果\n\n#### 模型看到什么\n\n接受时返回 `message queued as the next turn for subagent <subagent_id>`；规范输出携带被接受的 `messageId`。失败——未授权或未知子级、缺少描述符而无法恢复的子级，或准入被拒——会成为出错的结果，其消息说明该消息未送达。\n\n#### Token 影响\n\n每次调用产生一条简短确认消息；子级的响应绝不会通过本次调用返回。单独授予的 `report` 可以把选定内容追加到父级历史中。\n\n#### KV Cache 影响\n\n仅追加；新增可见内容位于可复用请求前缀之后，不会使现有 KV Cache 条目失效。\n\n### 列表结果\n\n#### 模型看到什么\n\n按稳定目录顺序，每个可继续子级占一行：`<id> [<status>] — <label>`（`running` 表示 driver 活跃，`idle` 表示驻留但处于轮次之间，`ready` 表示仅存于存储，可恢复而非终态），另为无法读取的候选项渲染 `<id> [diagnostic: <reason>]`。`descendants` scope 会在每行 label 破折号之前按 pre-order 插入 ` parent=<id> depth=<n>`。一次性子级会被有意排除；`(no subagents)` 表示投影后没有留下可继续子级或 diagnostic。\n\n#### Token 影响\n\n随所列可继续子级数量线性增长——`descendants` scope 下为整棵树；没有 cursor 或上限，因此长期存活且有许多持久化子级的父级每次调用都会承担完整列表成本。\n\n#### KV Cache 影响\n\n仅追加；每个结果都位于可复用请求前缀之后。\n\n## 已知限制与延期工作\n\n<a id=\"known-limitations-and-deferred-work\"></a>\n\n\n这些限制说明控制工具无法观察或引导什么；它们是当前包约束。\n\n- **已排队的消息没有独立结果**——接受时只返回其 inbox `messageId`；子级的工作会落入持久化子级会话，绝不会通过本工具收集。获得 `report` 的子级可以单独发回选定内容，但该消息不是本次调用的结果。\n- **不对当前轮次进行 steering（中途引导）**——每条消息都会开启后续 FIFO 轮次，因此在子级工作时发送的消息只会在其当前轮次结束后运行，无法将其重定向。\n- **列表是快照，而非投递承诺**——它可能与发布、dispose（资源释放）或后续消息发生竞态，另一个进程也可能激活当前进程报告为 `ready` 的子级；跨进程准确性需要共享租约。`interrupt_agent` 自己执行权威的在线 lineage 检查，因此过期的发现结果不会授予权限。\n- **没有分页或删除**——系统返回完整且稳定排序的集合；只要子级会话仍在持久化存储中，它就会继续出现在列表中，服务级上限或删除操作留待后续产品决策。\n\n<a id=\"dev-note\"></a>\n### 开发备注\n\n<details>\n<summary>维护者的工作上下文——点击展开</summary>\n\n无。\n\n</details>\n","readmeFilename":"README.zh.md","_rev":"1-b7b91b5ded7bb5e5de1bb197b255763b"}