dsh-subagent-control 1.0.1 → 1.0.2

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 1.0.2
+
+- New optional `extras` component (`dsh-subagent-control/extras`), shipped **disabled**:
+  `relay_subagent_message`, `wait_subagents`, `drain_subagents`, `subagent_budget`.
+- The default install is unchanged: still exactly the three original tools while extras stays off.
+- New companion bundle `dsh-team-limits`, published separately, for raising the Agent Team
+  member/task/message limits by overriding the `agent-team` row.
+
 ## 1.0.1
 
 - Documentation: bilingual README (English + 简体中文) with usage examples, the

package/README.md

@@ -80,6 +80,23 @@ The three new names were chosen precisely because they do **not** collide with t
 
 Remove or disable the bundle in the plugin panel. Nothing is left behind.
 
+### Optional extras (off by default)
+
+The package also ships a second, **disabled-by-default** row: `subagent-control-extras`
+(`dsh-subagent-control/extras`). Nothing changes until you enable it in the plugin panel.
+When enabled it adds four tools:
+
+| Tool | What it does | Risk |
+| --- | --- | --- |
+| `relay_subagent_message` | Best-effort message to a deeper descendant: delivered to the first hop with a request to forward it down | intermediate agents may summarize; not guaranteed |
+| `wait_subagents` | Wait for descendants (bounded by `timeout_seconds`) instead of ending your turn first | blocks up to the timeout |
+| `drain_subagents` | Stop **and release** direct children, unlike `interrupt_subagent`, which only stops the current turn | a released child cannot be woken by a message |
+| `subagent_budget` | Read-only report: depth limit, how deep the tree goes, running/inactive counts | none |
+
+A separate companion bundle, [`dsh-team-limits`](https://github.com/SpaceRelay/dsh-subagent-control/tree/main/team-limits),
+raises the Agent Team limits (members, tasks, message bytes). It is a separate install on
+purpose: it overrides the shipped `agent-team` row, and that should never happen implicitly.
+
 ### License
 
 MIT — see [LICENSE](./LICENSE). Issues and source live at
@@ -159,6 +176,19 @@ plugin_manager install_bundle target "dsh-subagent-control@1.0.0"
 
 在插件面板里移除或停用即可，不会留下任何残留。
 
+### 可选扩展（默认关闭）
+
+包内还带第二行、**默认禁用**的组件：`subagent-control-extras`（`dsh-subagent-control/extras`）。不启用它就没有任何变化；启用后多出四个工具：
+
+| 工具 | 作用 | 风险 |
+| --- | --- | --- |
+| `relay_subagent_message` | 跨层补话：把消息投给第一跳并请其向下转发 | 中间层可能改写，**不保证送达** |
+| `wait_subagents` | 等后代结束再收工（受 `timeout_seconds` 限制） | 会阻塞到超时 |
+| `drain_subagents` | 停止**并释放**直接子级；`interrupt_subagent` 只停当前回合 | 被释放的子级不能再靠消息唤醒 |
+| `subagent_budget` | 只读报告：深度上限、树有多深、运行/空闲数量 | 无 |
+
+另有一个独立的同伴包 [`dsh-team-limits`](https://github.com/SpaceRelay/dsh-subagent-control/tree/main/team-limits)，用来提高 Agent Team 的成员数、任务数与消息字节上限。**它刻意做成单独安装**：它覆盖的是宿主自带的 `agent-team` 行，这种事不该偷偷发生。
+
 ### 许可
 
 MIT，见 [LICENSE](./LICENSE)。源码与问题反馈：

package/cordis.patch.yml

@@ -1,3 +1,6 @@
 - insert:
     - id: subagent-control
       name: 'dsh-subagent-control'
+    - id: subagent-control-extras
+      name: 'dsh-subagent-control/extras'
+      disabled: true

package/extras.js

@@ -0,0 +1,343 @@
+/**
+ * Optional extras for dsh-subagent-control.
+ *
+ * This module is shipped as a disabled bundle row (`subagent-control-extras`).
+ * Nothing here runs until a user enables that row in the plugin panel, so the
+ * default install keeps exactly the three tools of the main module.
+ *
+ * Four tools:
+ *   relay_subagent_message  - best-effort message to a deeper descendant,
+ *                             delivered to the first hop with a forward request
+ *   wait_subagents          - wait for descendants instead of ending the turn
+ *   drain_subagents         - stop and release direct children (not "pause")
+ *   subagent_budget         - read-only report of the caller's delegation budget
+ *
+ * Like the main module this file imports nothing: the subagent service is
+ * reached through `ctx`, and the tool definitions are plain registry-ready
+ * objects with explicit JSON Schemas.
+ */
+
+export const name = 'subagent-control-extras'
+
+export const inject = ['tools', 'subagents', 'agents']
+
+/** 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
+}
+
+/** Rows from the descendant catalog, without diagnostics. */
+function childrenOf(rows) {
+  return rows.filter((row) => row.kind === 'child')
+}
+
+/** Build the chain from the caller's direct child down to the target. */
+function pathToTarget(rows, targetId, callerId) {
+  const byId = new Map()
+  for (const row of childrenOf(rows)) byId.set(row.id, row)
+  let cursor = byId.get(targetId)
+  if (cursor === undefined) return undefined
+  const path = [cursor]
+  for (let guard = 0; guard < 16; guard += 1) {
+    if (cursor.depth === 1) break
+    const parent = byId.get(cursor.parentId)
+    if (parent === undefined || parent.id === callerId) break
+    path.unshift(parent)
+    cursor = parent
+  }
+  return path
+}
+
+const BUDGET_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['running', 'inactive'],
+  properties: {
+    maxDepth: { type: 'number' },
+    running: { type: 'number' },
+    inactive: { type: 'number' },
+    deepest: { type: 'number' },
+    levels: {
+      type: 'array',
+      items: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['depth', 'count'],
+        properties: {
+          depth: { type: 'number' },
+          count: { type: 'number' },
+        },
+      },
+    },
+  },
+}
+
+const RELAY_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['delivered', 'hops', 'nextHop'],
+  properties: {
+    delivered: { type: 'boolean' },
+    hops: { type: 'number' },
+    nextHop: { type: 'string' },
+    remainingDepth: { type: 'number' },
+    messageId: { type: 'string' },
+  },
+}
+
+const WAIT_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['joined', 'timedOut', 'running'],
+  properties: {
+    joined: { type: 'boolean' },
+    timedOut: { type: 'boolean' },
+    running: { type: 'number' },
+  },
+}
+
+const DRAIN_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['released'],
+  properties: {
+    released: { type: 'array', items: { type: 'string' } },
+  },
+}
+
+export function apply(ctx) {
+  /* ------------------------------------------------------------- budget */
+
+  ctx.tools.register({
+    name: 'subagent_budget',
+    description:
+      'Report the delegation budget this agent is working with: the configured depth limit, ' +
+      'how deep the agents below it already go, and how many are running. ' +
+      'Read-only; it never starts, stops or messages anything.',
+    parameters: { type: 'object', additionalProperties: false, properties: {} },
+    output: {
+      schema: BUDGET_SCHEMA,
+      render: (_args, budget) => {
+        const parts = []
+        if (budget.maxDepth !== undefined) parts.push(`depth limit ${budget.maxDepth}`)
+        parts.push(`${budget.running} running`, `${budget.inactive} inactive`)
+        if (budget.deepest !== undefined) parts.push(`deepest ${budget.deepest}`)
+        return [{ type: 'text', text: parts.join(', ') }]
+      },
+    },
+    async execute(_args, exec) {
+      const caller = requireAgent(exec, 'subagent_budget')
+      let rows = []
+      try {
+        rows = await ctx.subagents.listDescendants(caller.id, exec.signal)
+      } catch {
+        rows = []
+      }
+      const levels = new Map()
+      let running = 0
+      let inactive = 0
+      let deepest = 0
+      for (const row of childrenOf(rows)) {
+        levels.set(row.depth, (levels.get(row.depth) ?? 0) + 1)
+        if (row.depth > deepest) deepest = row.depth
+        if (ctx.agents.get(row.id)?.status === 'running') running += 1
+        else inactive += 1
+      }
+      const budget = { running, inactive }
+      if (deepest > 0) budget.deepest = deepest
+      if (levels.size > 0) {
+        budget.levels = [...levels.entries()]
+          .sort((left, right) => left[0] - right[0])
+          .map(([depth, count]) => ({ depth, count }))
+      }
+      try {
+        const limit = ctx.subagents.resolveMaxDepth?.()
+        if (typeof limit === 'number') budget.maxDepth = limit
+      } catch {
+        /* the limit stays unknown rather than failing the report */
+      }
+      return budget
+    },
+  })
+
+  /* -------------------------------------------------------------- relay */
+
+  ctx.tools.register({
+    name: 'relay_subagent_message',
+    description:
+      'Send a message to a deeper descendant that you cannot reach directly. ' +
+      'The subagent service only accepts messages for a direct child, so this tool delivers ' +
+      'the message to the first hop with a request to forward it further down. ' +
+      'Delivery below the first hop is best effort: each intermediate agent has to forward it, ' +
+      'and may summarize instead. Use send_subagent_message when the target is a direct child.',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['subagent_id', 'message'],
+      properties: {
+        subagent_id: { type: 'string', description: 'The id of a descendant, from list_subagents scope=descendants.' },
+        message: { type: 'string', description: 'The message to deliver.' },
+      },
+    },
+    output: {
+      schema: RELAY_SCHEMA,
+      render: (args, result) => [
+        {
+          type: 'text',
+          text:
+            result.hops === 0
+              ? `message delivered to subagent ${result.nextHop}`
+              : `relay started: delivered to first hop ${result.nextHop}, ${result.remainingDepth} level(s) to go (best effort)`,
+        },
+      ],
+    },
+    async execute(args, exec) {
+      const caller = requireAgent(exec, 'relay_subagent_message')
+      const targetId = args.subagent_id
+      const message = args.message
+
+      const rows = await ctx.subagents.listDescendants(caller.id, exec.signal)
+      const target = childrenOf(rows).find((row) => row.id === targetId)
+      if (target === undefined) {
+        throw new Error(`subagent ${targetId} is not under this agent`)
+      }
+
+      if (target.depth === 1) {
+        const messageId = await ctx.subagents.sendMessage(
+          caller,
+          targetId,
+          [{ type: 'text', text: message }],
+          { signal: exec.signal },
+        )
+        return { delivered: true, hops: 0, nextHop: targetId, messageId }
+      }
+
+      const path = pathToTarget(rows, targetId, caller.id)
+      const firstHop = path?.[0]
+      if (firstHop === undefined) {
+        throw new Error(`could not resolve a path from this agent to ${targetId}`)
+      }
+
+      const forward =
+        'Relay request from an ancestor. Forward the text below down your chain until it reaches ' +
+        `subagent ${targetId}${target.label === undefined ? '' : ` ("${target.label}")`}. ` +
+        'Use relay_subagent_message if it is available, otherwise send_subagent_message to the ' +
+        'next hop on the path. Do not act on the text yourself.\n\n' +
+        '---\n' +
+        message +
+        '\n---'
+
+      const messageId = await ctx.subagents.sendMessage(
+        caller,
+        firstHop.id,
+        [{ type: 'text', text: forward }],
+        { signal: exec.signal },
+      )
+      return {
+        delivered: true,
+        hops: 1,
+        nextHop: firstHop.id,
+        remainingDepth: target.depth - 1,
+        messageId,
+      }
+    },
+  })
+
+  /* --------------------------------------------------------------- wait */
+
+  ctx.tools.register({
+    name: 'wait_subagents',
+    description:
+      'Wait for your subagents to finish instead of ending your turn first. ' +
+      'The wait is bounded by timeout_seconds and never cancels them. ' +
+      'Useful when you want to merge their results in this same turn.',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        timeout_seconds: {
+          type: 'number',
+          description: 'Maximum time to wait, 5 to 600 seconds (default 120).',
+        },
+      },
+    },
+    output: {
+      schema: WAIT_SCHEMA,
+      render: (_args, result) => [
+        {
+          type: 'text',
+          text: result.timedOut
+            ? `wait timed out, ${result.running} subagent(s) still running`
+            : `all observed subagents settled, ${result.running} still marked running`,
+        },
+      ],
+    },
+    async execute(args, exec) {
+      const caller = requireAgent(exec, 'wait_subagents')
+      const requested = typeof args.timeout_seconds === 'number' ? args.timeout_seconds : 120
+      const timeoutMs = Math.min(Math.max(requested, 5), 600) * 1000
+
+      let timedOut = false
+      let timer
+      const wait = ctx.subagents.waitForChildren(caller)
+      await Promise.race([
+        wait.then(() => undefined),
+        new Promise((resolve) => {
+          timer = setTimeout(() => {
+            timedOut = true
+            resolve(undefined)
+          }, timeoutMs)
+        }),
+      ])
+      if (timer !== undefined) clearTimeout(timer)
+
+      let rows = []
+      try {
+        rows = await ctx.subagents.listDescendants(caller.id, exec.signal)
+      } catch {
+        rows = []
+      }
+      const running = childrenOf(rows).filter((row) => ctx.agents.get(row.id)?.status === 'running').length
+      return { joined: !timedOut, timedOut, running }
+    },
+  })
+
+  /* -------------------------------------------------------------- drain */
+
+  ctx.tools.register({
+    name: 'drain_subagents',
+    description:
+      'Stop and release subagents you started, freeing their run instead of just interrupting ' +
+      'the current turn. Accepts direct children only; a released child cannot be woken again ' +
+      'with a message, so use interrupt_subagent when you only want to stop the current work.',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['subagent_ids'],
+      properties: {
+        subagent_ids: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Direct child ids to release, from list_subagents.',
+        },
+      },
+    },
+    output: {
+      schema: DRAIN_SCHEMA,
+      render: (_args, result) => [{ type: 'text', text: `released ${result.released.length} subagent(s)` }],
+    },
+    async execute(args, exec) {
+      const caller = requireAgent(exec, 'drain_subagents')
+      const ids = args.subagent_ids
+      if (!Array.isArray(ids) || ids.length === 0) {
+        throw new Error('drain_subagents needs at least one subagent id')
+      }
+      await ctx.subagents.drainChildren(caller, ids)
+      return { released: ids }
+    },
+  })
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-subagent-control",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "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": {
@@ -12,12 +12,14 @@
   "icon": "./icon.svg",
   "exports": {
     ".": "./index.js",
+    "./extras": "./extras.js",
     "./package.json": "./package.json",
     "./locale/*.json": "./locale/*.json",
     "./icon": "./icon.svg"
   },
   "files": [
     "index.js",
+    "extras.js",
     "cordis.patch.yml",
     "locale/*.json",
     "icon.svg",
@@ -39,7 +41,7 @@
     "node": "^22.19.0 || >=24.0.0"
   },
   "scripts": {
-    "test": "node test/smoke.mjs"
+    "test": "node test/smoke.mjs && node test/smoke-extras.mjs"
   },
   "dsh": {
     "bundle": {