dsh-subagent-control 1.0.1 → 1.0.3

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 1.0.3
+
+- `list_subagents` marks Team members, which are continuable subagents: each row carries
+  `team=teammate` (or `team=lead`) when the Agent Teams service can resolve it.
+- New `include_teammates` parameter (default `true`); set it to `false` to keep only plain
+  subagents. Existing behaviour is unchanged for callers that pass nothing.
+
+## 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

@@ -45,6 +45,8 @@ interrupt_subagent subagent_id=3b0f9c1e
 
 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.
 
+Team members are continuable subagents too, so they also appear in this list, marked `team=teammate` (or `team=lead`). Pass `include_teammates: false` when you want only the plain subagents you started.
+
 ### 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.
@@ -80,6 +82,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
@@ -124,6 +143,8 @@ interrupt_subagent subagent_id=3b0f9c1e
 
 每行格式是 `id  status  "label"  depth=`。`status` 为 `running` 或 `inactive`——**inactive 表示当前没有在跑，不代表子代理已经消失**；用 `send_subagent_message` 可以把它叫醒。
 
+团队成员本身也是可续子代理，所以同样会出现在列表里，并带 `team=teammate`（或 `team=lead`）标记；只想看自己派的普通子代理时，传 `include_teammates: false`。
+
 ### 行为与边界
 
 - **一次性子代理不会被列出。** 它们无法接收后续消息，列出来只会诱导一次注定失败的调用。
@@ -159,6 +180,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/index.js

@@ -37,6 +37,7 @@ const CHILD_ITEM = {
     status: { type: 'string', enum: ['running', 'inactive'] },
     parent: { type: 'string' },
     depth: { type: 'number' },
+    team: { type: 'string', enum: ['lead', 'teammate'] },
   },
 }
 
@@ -83,13 +84,42 @@ function project(agents, entry, position) {
   }
 }
 
+/**
+ * Team members are continuable subagents, so the subagent catalog cannot tell a
+ * teammate from a worker on its own. Resolve the Team role when the Agent Teams
+ * service is present, and answer `undefined` when the agent is not in a Team.
+ */
+function teamRoleResolver(ctx, caller) {
+  const teams = typeof ctx.get === 'function' ? ctx.get('agentTeams') : undefined
+  if (teams === undefined) return () => undefined
+  const roster = new Map()
+  try {
+    for (const member of teams.listMembers(caller) ?? []) roster.set(member.id, member.role)
+  } catch {
+    /* the caller is not part of a Team; the per-agent lookup below still works */
+  }
+  return (id) => {
+    const known = roster.get(id)
+    if (known !== undefined) return known
+    const agent = ctx.agents.get(id)
+    if (agent === undefined) return undefined
+    try {
+      const membership = teams.tryMembership?.(agent)
+      return membership === undefined ? undefined : membership.role
+    } catch {
+      return undefined
+    }
+  }
+}
+
 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}`
+  const team = entry.team === undefined ? '' : `  team=${entry.team}`
+  return `${entry.id}  ${entry.status}  ${JSON.stringify(entry.label)}${depth}${team}`
 }
 
 export function apply(ctx) {
@@ -100,6 +130,8 @@ export function apply(ctx) {
     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. ' +
+      'Team members are continuable subagents too, so they appear here marked team=teammate or team=lead; ' +
+      'use include_teammates:false when you only want the workers you started. ' +
       '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: {
@@ -114,6 +146,11 @@ export function apply(ctx) {
             'descendants lists the whole tree below you with each entry parent and depth; ' +
             'entries deeper than one level accept only interrupt_subagent.',
         },
+        include_teammates: {
+          type: 'boolean',
+          description:
+            'When false, leave out agents that belong to the current Team, keeping only plain subagents. Default true.',
+        },
       },
     },
     output: {
@@ -127,12 +164,22 @@ export function apply(ctx) {
     },
     async execute(args, exec) {
       const caller = requireAgent(exec, 'list_subagents')
+      const roleOf = teamRoleResolver(ctx, caller)
+      const wantsTeammates = args.include_teammates !== false
+      const emit = (entry, position) => {
+        const item = project(ctx.agents, entry, position)
+        if (item === undefined) return undefined
+        const role = roleOf(item.id)
+        if (role !== undefined) item.team = role
+        if (!wantsTeammates && role !== undefined) return undefined
+        return item
+      }
       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)
+        return rows.map((row) => emit(row, row)).filter(Boolean)
       }
       const rows = await ctx.subagents.listChildren(caller.id, exec.signal)
-      return rows.map((row) => project(ctx.agents, row)).filter(Boolean)
+      return rows.map((row) => emit(row)).filter(Boolean)
     },
   })
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-subagent-control",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "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": {