dsh-subagent-control 1.0.3 → 1.0.4

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 1.0.4
+
+- The single optional `extras` row is split into four independent components, each with its own
+  switch in the plugin panel and its own localized title and description: Cross-layer relay,
+  Wait for subagents, Release subagents, Delegation budget. Enabling one registers exactly one
+  tool instead of all four.
+- Removed the `dsh-subagent-control/extras` export in favour of `./relay`, `./wait`, `./drain`
+  and `./budget`, each also exporting `package.json` and `locale/*.json` for the panel.
+- Unchanged: the base row still registers exactly the three original tools, and every component
+  still starts disabled.
+
 ## 1.0.3
 
 - `list_subagents` marks Team members, which are continuable subagents: each row carries

package/README.md

@@ -82,18 +82,19 @@ 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)
+### Optional components (each 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:
+Four extra tools ship as **separate components**, each with its own row and switch in the plugin
+panel (`Cross-layer relay`, `Wait for subagents`, `Release subagents`, `Delegation budget`).
+All four start disabled; turning one on registers exactly one tool, so you can enable only what
+you need.
 
-| 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 |
+| Component | Tool | What it does | Risk |
+| --- | --- | --- | --- |
+| Cross-layer relay | `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 for subagents | `wait_subagents` | Wait for descendants (bounded by `timeout_seconds`) instead of ending your turn first | blocks up to the timeout |
+| Release subagents | `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 |
+| Delegation budget | `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
@@ -180,16 +181,16 @@ 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` | 只读报告：深度上限、树有多深、运行/空闲数量 | 无 |
+| 组件 | 工具 | 作用 | 风险 |
+| --- | --- | --- | --- |
+| 跨层补话 | `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` 行，这种事不该偷偷发生。
 

package/components/budget/index.js

@@ -0,0 +1,90 @@
+/**
+ * Delegation budget: a read-only look at what the caller has below it.
+ *
+ * Use it before planning a fan-out: how deep the chain already goes, how many
+ * agents sit on each level, and how many are running. It never starts, stops or
+ * messages anything.
+ */
+import { childrenOf, requireAgent } from '../shared.js'
+
+export const name = 'subagent-control-budget'
+
+export const inject = ['tools', 'subagents', 'agents']
+
+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' },
+        },
+      },
+    },
+  },
+}
+
+export function apply(ctx) {
+  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
+    },
+  })
+}

package/components/budget/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Delegation budget",
+    "description": "Read-only report of the delegation budget: depth limit, levels, running and inactive counts."
+  }
+}

package/components/budget/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "委派预算",
+    "description": "只读报告：深度上限、各层人数、最深一层、运行中与已停止的数量。规划扇出前先看一眼。"
+  }
+}

package/components/budget/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "Delegation budget",
+  "description": "Read-only report of the delegation budget: depth limit, levels, running and inactive counts.",
+  "type": "module"
+}

package/components/drain/index.js

@@ -0,0 +1,56 @@
+/**
+ * Drain: stop and release direct children, freeing their run.
+ *
+ * interrupt_subagent only ends the current turn and keeps the activation, so a
+ * stopped subagent stays in the catalog. Drain removes the run itself, which is
+ * why a released child can never be woken with another message.
+ */
+import { requireAgent } from '../shared.js'
+
+export const name = 'subagent-control-drain'
+
+export const inject = ['tools', 'subagents', 'agents']
+
+const DRAIN_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['released'],
+  properties: {
+    released: { type: 'array', items: { type: 'string' } },
+  },
+}
+
+export function apply(ctx) {
+  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/components/drain/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Release subagents",
+    "description": "Stop and release direct children, freeing their run; a released agent cannot be woken again."
+  }
+}

package/components/drain/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "释放子代理",
+    "description": "停止并释放直接子代理，真正腾出运行实例；释放后不能再唤醒，只想停当前回合请用 interrupt_subagent。"
+  }
+}

package/components/drain/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "Release subagents",
+  "description": "Stop and release direct children, freeing their run; a released agent cannot be woken again.",
+  "type": "module"
+}

package/components/relay/index.js

@@ -0,0 +1,108 @@
+/**
+ * Cross-layer relay: hand a message to the first hop and ask it to forward.
+ *
+ * The subagent service only accepts messages for a direct child, so a deeper
+ * descendant is reached by a prompt-level relay. It is best effort by nature:
+ * the middle agent has to cooperate, and may summarize instead of forwarding.
+ */
+import { childrenOf, pathToTarget, requireAgent } from '../shared.js'
+
+export const name = 'subagent-control-relay'
+
+export const inject = ['tools', 'subagents', 'agents']
+
+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' },
+  },
+}
+
+export function apply(ctx) {
+  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,
+      }
+    },
+  })
+}

package/components/relay/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Cross-layer relay",
+    "description": "Best-effort message relay to a deeper descendant; the middle hop must forward it, and may summarize instead."
+  }
+}

package/components/relay/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "跨层补话",
+    "description": "把消息交给中间层，请它继续传给更深的后代。送达属于尽力而为，中间层可能概括内容。"
+  }
+}

package/components/relay/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "Cross-layer relay",
+  "description": "Best-effort message relay to a deeper descendant; the middle hop must forward it.",
+  "type": "module"
+}

package/components/shared.js

@@ -0,0 +1,37 @@
+/**
+ * Helpers shared by the optional components.
+ *
+ * Plain relative module: this package imports no bare specifier, so a linked
+ * checkout and an npm install resolve exactly the same way.
+ */
+
+/** A tool needs a calling agent; a schedule or an external call has none. */
+export 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. */
+export function childrenOf(rows) {
+  return rows.filter((row) => row.kind === 'child')
+}
+
+/** Build the chain from the caller's direct child down to the target. */
+export 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
+}

package/components/wait/index.js

@@ -0,0 +1,81 @@
+/**
+ * Wait for subagents inside the current turn.
+ *
+ * The wait is bounded and never cancels anything: it only decides whether this
+ * turn keeps going or reports a timeout with what is still running.
+ */
+import { childrenOf, requireAgent } from '../shared.js'
+
+export const name = 'subagent-control-wait'
+
+export const inject = ['tools', 'subagents', 'agents']
+
+const WAIT_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['joined', 'timedOut', 'running'],
+  properties: {
+    joined: { type: 'boolean' },
+    timedOut: { type: 'boolean' },
+    running: { type: 'number' },
+  },
+}
+
+export function apply(ctx) {
+  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 }
+    },
+  })
+}

package/components/wait/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Wait for subagents",
+    "description": "Wait for your subagents in this turn instead of ending it; a timeout never cancels them."
+  }
+}

package/components/wait/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "等待子代理",
+    "description": "在当前回合里等子代理跑完再继续，而不是先结束回合；超时也不会取消它们。"
+  }
+}

package/components/wait/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "Wait for subagents",
+  "description": "Wait for your subagents in this turn instead of ending it; a timeout never cancels them.",
+  "type": "module"
+}

package/cordis.patch.yml

@@ -1,6 +1,18 @@
+# Four opt-in components, each with its own switch in the plugin panel.
+# The base row is the three core tools; every component below starts disabled,
+# so a default install registers nothing beyond those three.
 - insert:
     - id: subagent-control
       name: 'dsh-subagent-control'
-    - id: subagent-control-extras
-      name: 'dsh-subagent-control/extras'
+    - id: subagent-control-relay
+      name: 'dsh-subagent-control/relay'
+      disabled: true
+    - id: subagent-control-wait
+      name: 'dsh-subagent-control/wait'
+      disabled: true
+    - id: subagent-control-drain
+      name: 'dsh-subagent-control/drain'
+      disabled: true
+    - id: subagent-control-budget
+      name: 'dsh-subagent-control/budget'
       disabled: true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-subagent-control",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "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,14 +12,25 @@
   "icon": "./icon.svg",
   "exports": {
     ".": "./index.js",
-    "./extras": "./extras.js",
     "./package.json": "./package.json",
     "./locale/*.json": "./locale/*.json",
-    "./icon": "./icon.svg"
+    "./icon": "./icon.svg",
+    "./relay": "./components/relay/index.js",
+    "./relay/package.json": "./components/relay/package.json",
+    "./relay/locale/*.json": "./components/relay/locale/*.json",
+    "./wait": "./components/wait/index.js",
+    "./wait/package.json": "./components/wait/package.json",
+    "./wait/locale/*.json": "./components/wait/locale/*.json",
+    "./drain": "./components/drain/index.js",
+    "./drain/package.json": "./components/drain/package.json",
+    "./drain/locale/*.json": "./components/drain/locale/*.json",
+    "./budget": "./components/budget/index.js",
+    "./budget/package.json": "./components/budget/package.json",
+    "./budget/locale/*.json": "./components/budget/locale/*.json"
   },
   "files": [
     "index.js",
-    "extras.js",
+    "components",
     "cordis.patch.yml",
     "locale/*.json",
     "icon.svg",

package/extras.js

@@ -1,343 +0,0 @@
-/**
- * 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 }
-    },
-  })
-}