dsh-subagent-control 0.0.0-stage → 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## 1.0.1
+
+- Documentation: bilingual README (English + 简体中文) with usage examples, the
+  security model, and the name-collision note.
+- Release: publishing now runs on GitHub Actions with npm trusted publishing
+  (OIDC) and provenance. No npm token is stored in the repository.
+- No runtime change: the three tools and their JSON Schemas are identical to
+  1.0.0.
+
+## 1.0.0
+
+First release.
+
+- `list_subagents` — list the caller's direct children or its whole descendant tree, with `running` / `inactive` status.
+- `send_subagent_message` — send a follow-up message to a subagent the caller started.
+- `interrupt_subagent` — stop a subagent (or any descendant) the caller started.
+- Registers three new global tool names instead of shadowing the team bundle's `list_agents` / `send_message` / `interrupt_agent`.
+- No runtime or peer dependencies; the module imports nothing.
+- Localized display metadata (zh / en) and an SVG icon.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-subagent-control contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,165 @@
-# Temporary Holding Version
+# dsh-subagent-control
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**English** · [简体中文](#简体中文)
+
+Three tools that let any DSH agent — **including a team member** — list, steer and stop the subagents it started.
+
+`list_subagents` · `send_subagent_message` · `interrupt_subagent`
+
+---
+
+## English
+
+### The problem
+
+The Harness ships `list_agents`, `send_message` and `interrupt_agent`. When the Agent Team bundle is active, it registers tools with **those same three names** in every team member's exact Agent scope, and the more specific registration wins. Inside a teammate scope the team versions take over: they resolve `target` against the team roster only, and interrupting is a Lead-only operation.
+
+The result: a teammate can start a subagent with `subagent`, but cannot list it, follow up with it, or stop it — even though the subagent service (`ctx.subagents`) has supported all three for any live agent all along, and its authority rules already allow an ancestor to manage its own descendants.
+
+This bundle does not fight over the taken names. It registers three **new** names, globally, so the Lead and every teammate get them at once.
+
+### Tools
+
+| Tool | Parameters | Underlying call |
+| --- | --- | --- |
+| `list_subagents` | `scope?`: `"children"` \| `"descendants"` (default `children`) | `ctx.subagents.listChildren()` / `listDescendants()` |
+| `send_subagent_message` | `subagent_id`, `message` (both required) | `ctx.subagents.sendMessage()` |
+| `interrupt_subagent` | `subagent_id` (required) | `ctx.subagents.interrupt()` with ancestor authority |
+
+### Usage
+
+```
+list_subagents
+→ 3b0f9c1e  running  "review the patch"  depth=1
+
+list_subagents scope=descendants
+→ 3b0f9c1e  running  "review the patch"  depth=1
+  7d2a44b0  inactive "check the tests"    depth=2
+
+send_subagent_message subagent_id=3b0f9c1e message="also look at locale/zh.json"
+→ messageId=...
+
+interrupt_subagent subagent_id=3b0f9c1e
+→ accepted=true
+```
+
+Each listing line is `id  status  "label"  depth=`. `status` is `running` or `inactive` — **inactive means no turn is executing, not that the subagent is gone**. Use `send_subagent_message` to wake it.
+
+### Behaviour and limits
+
+- **One-shot subagents are hidden.** They cannot accept a follow-up message, so listing them would only invite a call that is guaranteed to fail.
+- **A broken record is reported, not thrown.** A child whose state cannot be read comes back as a diagnostic entry (`corrupt` / `unsupported` / `unavailable`) instead of turning the whole listing into an error.
+- **`send_subagent_message` reaches direct children only.** That is the service's own rule; the plugin does not widen it.
+- **`interrupt_subagent` reaches descendants**, so a team Lead can also stop a grandchild.
+- **Every failure names its cause**: no calling agent, unknown id, or an id that is not yours.
+- **No config, no storage.** The bundle writes nothing and reads nothing outside the three services.
+
+### Install
+
+Through the plugin panel / market, or by asking the agent:
+
+```
+plugin_manager install_bundle target "dsh-subagent-control@1.0.0"
+```
+
+From a checkout, pass the **directory path** instead of the npm spec. The bundle applies immediately — no restart needed. Afterwards the three tool names are visible and the plugin row is enabled.
+
+### Compatibility
+
+- DSH with the `tools`, `subagents` and `agents` services (0.2.x and later).
+- Node `^22.19.0 || >=24.0.0`.
+- **Zero dependencies** — no runtime dependency, no peer dependency, not a single `import`. The tools are plain tool-table objects with explicit JSON Schemas, so they install and behave identically from npm or from a linked checkout.
+
+### Name collisions
+
+`dsh-subagent-library` also registers a global `list_subagents` tool. Two global registrations of one name cannot both win: install one of them, or remember that the other may shadow this one.
+
+The three new names were chosen precisely because they do **not** collide with the built-in `list_agents` / `send_message` / `interrupt_agent`.
+
+### Uninstall
+
+Remove or disable the bundle in the plugin panel. Nothing is left behind.
+
+### License
+
+MIT — see [LICENSE](./LICENSE). Issues and source live at
+[github.com/SpaceRelay/dsh-subagent-control](https://github.com/SpaceRelay/dsh-subagent-control).
+
+---
+
+## 简体中文
+
+### 它解决什么问题
+
+Harness 自带 `list_agents`、`send_message`、`interrupt_agent`。开启 Agent Team 后，团队插件会把**同名的三个工具**注册进每个团队成员的精确作用域，而更具体的作用域优先。于是在成员作用域里生效的是团队版：`target` 只认队友名，打断只有组长能做。
+
+结果是：团队成员能用 `subagent` 派出子代理，却列不出、追问不了、也打断不了它。而底层的子代理服务（`ctx.subagents`）本来就支持这三件事，权限规则也允许祖先管理自己的后代。
+
+本插件不去抢那三个被占用的名字，而是全局注册三个**新名字**，组长和每个组员立刻都能用。
+
+### 工具
+
+| 工具 | 参数 | 底层调用 |
+| --- | --- | --- |
+| `list_subagents` | `scope?`：`"children"` 或 `"descendants"`，默认 `children` | `ctx.subagents.listChildren()` / `listDescendants()` |
+| `send_subagent_message` | `subagent_id`、`message`（均必填） | `ctx.subagents.sendMessage()` |
+| `interrupt_subagent` | `subagent_id`（必填） | `ctx.subagents.interrupt()`（祖先权限） |
+
+### 用法
+
+```
+list_subagents
+→ 3b0f9c1e  running  "review the patch"  depth=1
+
+list_subagents scope=descendants
+→ 3b0f9c1e  running  "review the patch"  depth=1
+  7d2a44b0  inactive "check the tests"    depth=2
+
+send_subagent_message subagent_id=3b0f9c1e message="顺手看一下 locale/zh.json"
+→ messageId=...
+
+interrupt_subagent subagent_id=3b0f9c1e
+→ accepted=true
+```
+
+每行格式是 `id  status  "label"  depth=`。`status` 为 `running` 或 `inactive`——**inactive 表示当前没有在跑，不代表子代理已经消失**；用 `send_subagent_message` 可以把它叫醒。
+
+### 行为与边界
+
+- **一次性子代理不会被列出。** 它们无法接收后续消息，列出来只会诱导一次注定失败的调用。
+- **记录损坏时报告，而不是抛错。** 某个子代理状态读不出来，会作为诊断条目（`corrupt` / `unsupported` / `unavailable`）返回，而不是让整个列表失败。
+- **`send_subagent_message` 只能发给直接子代理。** 这是服务本身的规则，插件没有放宽。
+- **`interrupt_subagent` 覆盖所有后代**，所以组长也能打断孙代。
+- **任何失败都说明原因**：没有调用者、id 不存在、或者不是你的子代理。
+- **不写配置、不落存储。** 除了这三个服务，插件不读写任何东西。
+
+### 安装
+
+在插件面板 / 市场中安装，或者让智能体执行：
+
+```
+plugin_manager install_bundle target "dsh-subagent-control@1.0.0"
+```
+
+从本地目录安装时，把 npm 规格换成**目录路径**。安装即时生效，无需重启；装完后三个工具名可见、插件行为已启用。
+
+### 兼容性
+
+- 具备 `tools`、`subagents`、`agents` 三个服务的 DSH（0.2.x 及以上）。
+- Node `^22.19.0 || >=24.0.0`。
+- **零依赖**：没有运行时依赖、没有 peer 依赖，模块里一行 `import` 都没有。工具是带显式 JSON Schema 的普通定义对象，所以 npm 安装与软链安装行为完全一致。
+
+### 撞名
+
+`dsh-subagent-library` 也注册了全局的 `list_subagents`。同一个名字的两个全局注册不可能同时生效——二选一安装，或记住其中一个可能被另一个覆盖。
+
+这三个新名字是特意挑的，**不会**和内置的 `list_agents` / `send_message` / `interrupt_agent` 冲突。
+
+### 卸载
+
+在插件面板里移除或停用即可，不会留下任何残留。
+
+### 许可
+
+MIT，见 [LICENSE](./LICENSE)。源码与问题反馈：
+[github.com/SpaceRelay/dsh-subagent-control](https://github.com/SpaceRelay/dsh-subagent-control)。

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: subagent-control
+      name: 'dsh-subagent-control'

package/icon.svg

@@ -0,0 +1,13 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="Subagent control">
+  <rect x="2" y="2" width="60" height="60" rx="14" fill="#1f6feb"/>
+  <g fill="none" stroke="#ffffff" stroke-width="3.5" stroke-linecap="round">
+    <path d="M32 20v9"/>
+    <path d="M32 29H16v8"/>
+    <path d="M32 29h16v8"/>
+    <path d="M32 29v8"/>
+  </g>
+  <circle cx="32" cy="15" r="6" fill="#ffffff"/>
+  <circle cx="16" cy="43" r="5" fill="#ffffff"/>
+  <circle cx="32" cy="43" r="5" fill="#ffffff"/>
+  <circle cx="48" cy="43" r="5" fill="#ffffff"/>
+</svg>

package/index.js

@@ -0,0 +1,214 @@
+/**
+ * Subagent control tools.
+ *
+ * The Harness already registers `list_agents` / `send_message` /
+ * `interrupt_agent`, but the Agent Team plugin registers tools with those same
+ * three names in each team member's exact Agent scope, so inside a teammate
+ * scope the team versions win: they resolve `target` against the team roster
+ * only, and `interrupt_agent` is Lead-only. A team member therefore cannot
+ * list, steer, or stop the subagents it started, even though
+ * `ctx.subagents` already supports all three operations for any live agent.
+ *
+ * This plugin registers three differently named tools instead of fighting over
+ * the taken names. They are registered globally, so the Lead and every team
+ * member get them; the subagent service itself enforces that a caller can only
+ * reach its own direct children (`sendMessage`) or its own descendants
+ * (`interrupt`).
+ *
+ * This module deliberately imports nothing: the tool definitions below are
+ * plain registry-ready objects with explicit JSON Schemas, so the package has
+ * no runtime or peer dependencies and installs the same way from npm or from a
+ * linked checkout.
+ */
+
+export const name = 'subagent-control'
+
+export const inject = ['tools', 'subagents', 'agents']
+
+/** Detail rows returned by the subagent catalog. */
+const CHILD_ITEM = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['kind', 'id', 'label', 'status'],
+  properties: {
+    kind: { type: 'string', enum: ['child'] },
+    id: { type: 'string' },
+    label: { type: 'string' },
+    status: { type: 'string', enum: ['running', 'inactive'] },
+    parent: { type: 'string' },
+    depth: { type: 'number' },
+  },
+}
+
+const DIAGNOSTIC_ITEM = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['kind', 'id', 'reason'],
+  properties: {
+    kind: { type: 'string', enum: ['diagnostic'] },
+    id: { type: 'string' },
+    reason: { type: 'string', enum: ['corrupt', 'unsupported', 'unavailable'] },
+    parent: { type: 'string' },
+    depth: { type: 'number' },
+  },
+}
+
+/** A tool needs a calling agent; a schedule or an external call has none. */
+function requireAgent(exec, tool) {
+  const agent = exec.agent
+  if (agent === undefined) {
+    throw new Error(`${tool} requires a calling agent (exec.agent was undefined)`)
+  }
+  return agent
+}
+
+/** Report only whether the subagent is working, never whether it is loaded. */
+function statusOf(agents, id) {
+  return agents.get(id)?.status === 'running' ? 'running' : 'inactive'
+}
+
+/** One catalog row to one model-visible entry; one-shot children are omitted. */
+function project(agents, entry, position) {
+  const at = position === undefined ? {} : { parent: position.parentId, depth: position.depth }
+  if (entry.kind === 'diagnostic') {
+    return { kind: 'diagnostic', id: entry.id, reason: entry.reason, ...at }
+  }
+  if (entry.mode !== 'continuable') return undefined
+  return {
+    kind: 'child',
+    id: entry.id,
+    label: entry.label,
+    status: statusOf(agents, entry.id),
+    ...at,
+  }
+}
+
+function renderEntry(entry) {
+  if (entry.kind === 'diagnostic') {
+    const at = entry.parent === undefined ? '' : `  parent=${entry.parent}`
+    return `[${entry.reason}] ${entry.id}${at}`
+  }
+  const depth = entry.depth === undefined ? '' : `  depth=${entry.depth}`
+  return `${entry.id}  ${entry.status}  ${JSON.stringify(entry.label)}${depth}`
+}
+
+export function apply(ctx) {
+  /* ---------------------------------------------------------------- list */
+
+  ctx.tools.register({
+    name: 'list_subagents',
+    description:
+      'List the subagents you started, with their ids, labels and status. ' +
+      'running means it is working; inactive means it is not working right now, which does not mean it is gone. ' +
+      'You are notified when a subagent finishes, so there is no need to poll. ' +
+      'Use send_subagent_message to continue a conversation with one of them.',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        scope: {
+          type: 'string',
+          enum: ['children', 'descendants'],
+          description:
+            'children (default) lists your direct children, which accept send_subagent_message in any status. ' +
+            'descendants lists the whole tree below you with each entry parent and depth; ' +
+            'entries deeper than one level accept only interrupt_subagent.',
+        },
+      },
+    },
+    output: {
+      schema: { type: 'array', items: { oneOf: [CHILD_ITEM, DIAGNOSTIC_ITEM] } },
+      render: (_args, entries) => [
+        {
+          type: 'text',
+          text: entries.length === 0 ? '(no subagents)' : entries.map(renderEntry).join('\n'),
+        },
+      ],
+    },
+    async execute(args, exec) {
+      const caller = requireAgent(exec, 'list_subagents')
+      if ((args.scope ?? 'children') === 'descendants') {
+        const rows = await ctx.subagents.listDescendants(caller.id, exec.signal)
+        return rows.map((row) => project(ctx.agents, row, row)).filter(Boolean)
+      }
+      const rows = await ctx.subagents.listChildren(caller.id, exec.signal)
+      return rows.map((row) => project(ctx.agents, row)).filter(Boolean)
+    },
+  })
+
+  /* ---------------------------------------------------------------- send */
+
+  ctx.tools.register({
+    name: 'send_subagent_message',
+    description:
+      'Send a follow-up message to a subagent you started. ' +
+      'A running subagent receives it at its next step; a finished one is resumed with it. ' +
+      'Only a direct child accepts a message; use list_subagents to find its id. ' +
+      'This returns delivery confirmation, not the answer — the answer arrives as a new message.',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['subagent_id', 'message'],
+      properties: {
+        subagent_id: {
+          type: 'string',
+          description: 'The id of your direct subagent, from list_subagents.',
+        },
+        message: { type: 'string', description: 'The message to deliver.' },
+      },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['messageId'],
+        properties: { messageId: { type: 'string' } },
+      },
+      render: (args) => [{ type: 'text', text: `message delivered to subagent ${args.subagent_id}` }],
+    },
+    async execute(args, exec) {
+      const caller = requireAgent(exec, 'send_subagent_message')
+      const content = [{ type: 'text', text: args.message }]
+      const messageId = await ctx.subagents.sendMessage(caller, args.subagent_id, content, {
+        signal: exec.signal,
+      })
+      return { messageId }
+    },
+  })
+
+  /* ----------------------------------------------------------- interrupt */
+
+  ctx.tools.register({
+    name: 'interrupt_subagent',
+    description:
+      'Ask a subagent under you to stop its current work. Returns without waiting for it to stop. ' +
+      'A subagent that finished on its own is unaffected. ' +
+      'Subagents it started keep running; interrupt those separately with their own ids.',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['subagent_id'],
+      properties: {
+        subagent_id: {
+          type: 'string',
+          description:
+            'The id of a subagent created under you: a direct child or any deeper descendant.',
+        },
+      },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['accepted'],
+        properties: { accepted: { type: 'boolean' } },
+      },
+      render: (args) => [{ type: 'text', text: `interrupt requested for subagent ${args.subagent_id}` }],
+    },
+    execute(args, exec) {
+      const caller = requireAgent(exec, 'interrupt_subagent')
+      ctx.subagents.interrupt(args.subagent_id, { kind: 'ancestor', agent: caller })
+      return Promise.resolve({ accepted: true })
+    },
+  })
+}

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Subagent Control",
+    "description": "Lets any agent — including a team member — list, steer and stop the subagents it started."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "子代理管理",
+    "description": "让任意智能体（包括团队成员）能列出、追问并中止自己派出的子代理。"
+  }
+}

package/package.json

@@ -1,6 +1,60 @@
 {
   "name": "dsh-subagent-control",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "Three tools — list_subagents, send_subagent_message, interrupt_subagent — that let any agent, including a team member, list, steer and stop the subagents it started.",
+  "license": "MIT",
+  "author": {
+    "name": "SpaceRelay",
+    "url": "https://github.com/SpaceRelay"
+  },
+  "type": "module",
+  "main": "index.js",
+  "icon": "./icon.svg",
+  "exports": {
+    ".": "./index.js",
+    "./package.json": "./package.json",
+    "./locale/*.json": "./locale/*.json",
+    "./icon": "./icon.svg"
+  },
+  "files": [
+    "index.js",
+    "cordis.patch.yml",
+    "locale/*.json",
+    "icon.svg",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "cordis-plugin",
+    "subagent",
+    "agents",
+    "agent-team",
+    "orchestration"
+  ],
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "scripts": {
+    "test": "node test/smoke.mjs"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SpaceRelay/dsh-subagent-control.git"
+  },
+  "homepage": "https://github.com/SpaceRelay/dsh-subagent-control#readme",
+  "bugs": {
+    "url": "https://github.com/SpaceRelay/dsh-subagent-control/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}