dsh-plugin-subagent-bridge 0.5.0 → 0.6.0

package/README.md

@@ -108,6 +108,9 @@ codex mcp remove dsh-bridge
 | `maxResultChars` | `20000` | 单次 `dsh_read_result` 返回的最大字符数（超出保留尾部） |
 | `taskTimeoutSeconds` | `300` | `dsh_task` 等待一轮结束的默认上限（客户端可用 `timeoutSeconds` 覆盖，最大 600） |
 | `workersFile` | `~/.dsh/bridge/workers.json` | worker 注册表与重基线的落盘位置（0600） |
+| `maxHops` | `1` | 跨工具委派层数上限（1 = 只允许一层，和 Codex / DSH 的默认 `maxDepth: 1` 一致） |
+| `dispatchPerMinute` | `10` | 滚动窗口内允许的派发次数（spawn / task / dispatch / followup / codex_dispatch 合计） |
+| `dispatchWindowMs` | `60000` | 上述窗口长度 |
 | `maxWorkers` | `4` | 同时打开的 worker 上限；**已完成但未 `dsh_close` 的也占名额**（与 Codex 一致） |
 | `waitTimeoutMs` | `30000` | `dsh_wait` 的默认超时（1s ~ 1h，客户端可用 `timeoutMs` 覆盖） |
 | `readWaitSeconds` | `25` | `dsh_read_result` 的默认长轮询时长（上限 55，客户端可用 `waitSeconds` 覆盖） |
@@ -119,6 +122,30 @@ codex mcp remove dsh-bridge
 
 ---
 
+## 防环护栏
+
+两个 agent 都接了同一个桥时，存在真实的环路：DSH worker → `codex_dispatch` → 那次 Codex 运行也能看到 `dsh-bridge` → 又 `dsh_spawn` → …。两边**各自进程内**的深度规则都管不到这条链（Codex 的 `agent_max_depth` 只数自己的 `spawn_agent`，DSH 的 `maxDepth` 只看 `delegationDepth`，而桥建的 worker 是顶层会话，深度恒为 0）。
+
+所以桥自带两道：
+
+**① 深度（`maxHops`，默认 1）**
+
+- 每次都计算这次派发会产生的深度：`max(当前在飞的链路深度, 调用方深度) + 1`；
+- 调用方是桥建的 worker 时按其深度 1 起算；
+- `codex_dispatch` 运行期间会把链路标记为"在飞"，嵌套回来的调用继承该深度；
+- 超限直接报错，措辞可执行：
+  `codex_dispatch would create delegation depth 2, but maxHops is 1. Carry the work out directly instead of delegating again.`
+
+默认 1 的含义：**Codex 可以派给 DSH，但 DSH 不能再用桥派回去** —— 与两个产品各自的 `maxDepth: 1` 语义对齐。
+
+**② 速率（`dispatchPerMinute`，默认 10 / 60s）**
+
+拦截广度型失控（一次开很多 worker）和客户端紧循环重试，与提示词无关，是纯兜底：
+
+```
+rate limit: 10 dispatches per 60s reached; retry in 23s
+```
+
 ## 跨重启
 
 worker 注册表（`task_name` / `sessionId` / 终态结果）和每轮的时间基线都落在 `~/.dsh/bridge/workers.json`：
@@ -192,7 +219,7 @@ mkdir -p ~/.dsh/skills && cp -R skills/delegate-to-codex ~/.dsh/skills/
 node --test "test/*.test.mjs"
 ```
 
-45 项：握手与版本协商、通知处理、工具清单、未知方法与未知工具、参数校验、元数据列表不含消息内容、派发调用形状、拒绝与错误透出、结果读取的时间基线、未派发会话的拒绝、长轮询（文本晚到即返回 / 超时 / 调用方取消）、真实 HTTP 往返（含 404/405/202 与 bearer 分支）、`codex exec` 事件解析、二进制解析、成功/失败/超时三种运行结果、resume 的参数分叉、工具结果的 lossless JSON 约束、**只回最终回答**（多步叙述被丢弃）、`dsh_wait` 的任一完成 / 超时 / 错误 / 未派发四种状态、`dsh_spawn` 立即返回与注册、`fork_turns=all` 走 fork、并发上限与 `dsh_close` 释放名额、`dsh_followup` 的重基线与最终回答切换、注册表落盘与重启后复原、冷会话下的缓存回答与 `offline` 状态、注册表 200 条上限的淘汰顺序。
+50 项：握手与版本协商、通知处理、工具清单、未知方法与未知工具、参数校验、元数据列表不含消息内容、派发调用形状、拒绝与错误透出、结果读取的时间基线、未派发会话的拒绝、长轮询（文本晚到即返回 / 超时 / 调用方取消）、真实 HTTP 往返（含 404/405/202 与 bearer 分支）、`codex exec` 事件解析、二进制解析、成功/失败/超时三种运行结果、resume 的参数分叉、工具结果的 lossless JSON 约束、**只回最终回答**（多步叙述被丢弃）、`dsh_wait` 的任一完成 / 超时 / 错误 / 未派发四种状态、`dsh_spawn` 立即返回与注册、`fork_turns=all` 走 fork、并发上限与 `dsh_close` 释放名额、`dsh_followup` 的重基线与最终回答切换、注册表落盘与重启后复原、冷会话下的缓存回答与 `offline` 状态、注册表 200 条上限的淘汰顺序、`maxHops` 拒绝回派而放行首层、在飞链路阻塞嵌套派发、速率突发的拒绝与窗口过期、followup 计入同一预算。
 `test/persistence.test.mjs` 单独覆盖持久化：文件权限 0600、缺失/损坏/畸形记录、spawn 返回时文件已落盘、完成即缓存、followup 清缓存、close 后重启仍为 closed、冷会话走缓存或 `offline`、并发写不串。
 
 ---

package/index.js

@@ -58,6 +58,9 @@ const DEFAULTS = {
   taskTimeoutSeconds: 300,
   waitTimeoutMs: 30000,
   maxWorkers: 4,
+  maxHops: 1,
+  dispatchPerMinute: 10,
+  dispatchWindowMs: 60000,
   workersFile: join(homedir(), '.dsh', 'bridge', 'workers.json'),
 }
 
@@ -545,6 +548,8 @@ export function createApi(ctx, state, settings) {
   state.dispatched = state.dispatched ?? new Set()
   state.baseline = state.baseline ?? new Map()
   state.workers = state.workers ?? new Map()
+  state.chain = state.chain ?? { depth: 0, active: 0, until: 0 }
+  state.recent = state.recent ?? []
   const controller = () => ctx.get('sessionController')
   const sessions = () => ctx.get('sessions')
 
@@ -576,6 +581,8 @@ export function createApi(ctx, state, settings) {
       const service = controller()
       if (service === undefined || service === null) throw new Error('session controller is unavailable')
       if (state.workers.has(taskName)) throw new Error(`task_name ${JSON.stringify(taskName)} is already in use`)
+      guardDepth(state, settings, 0, 'dsh_spawn')
+      takeDispatchSlot(state, settings)
       assertCapacity(state, settings)
 
       let sessionId
@@ -611,6 +618,7 @@ export function createApi(ctx, state, settings) {
       if (target === undefined) throw new Error(`unknown worker ${JSON.stringify(worker)}`)
       const service = controller()
       if (service === undefined || service === null) throw new Error('session controller is unavailable')
+      takeDispatchSlot(state, settings)
       const before = Number(sessions()?.get?.(target.sessionId)?.seq ?? 0)
       const requestId = randomUUID()
       const accepted = await service.prompt(
@@ -652,6 +660,8 @@ export function createApi(ctx, state, settings) {
       const service = controller()
       if (service === undefined || service === null) throw new Error('session controller is unavailable')
       const seconds = Math.min(600, Math.max(1, Number.isFinite(timeoutSeconds) ? timeoutSeconds : settings.taskTimeoutSeconds))
+      guardDepth(state, settings, 0, 'dsh_task')
+      takeDispatchSlot(state, settings)
       const started = Date.now()
 
       let targetId = sessionId
@@ -723,6 +733,8 @@ export function createApi(ctx, state, settings) {
     async dispatch({ sessionId, text, mode }) {
       const service = controller()
       if (service === undefined || service === null) throw new Error('session controller is unavailable')
+      guardDepth(state, settings, 0, 'dsh_dispatch')
+      takeDispatchSlot(state, settings)
       const before = Number(sessions()?.get?.(sessionId)?.seq ?? 0)
       const requestId = randomUUID()
       const result = await service.prompt(
@@ -757,17 +769,24 @@ export function createApi(ctx, state, settings) {
 
     async dispatchCodex(args, exec) {
       const prompt = requireString(args?.prompt, 'prompt')
+      const depth = guardDepth(state, settings, callerDepth(state, exec?.agent?.id), 'codex_dispatch')
+      takeDispatchSlot(state, settings)
       const cwd = await resolveCwd(ctx, args?.cwd, exec)
-      return runCodex({
+      enterChain(state, depth, settings.codexTimeoutMs + 5000)
+      try {
+        return await runCodex({
         bin: resolveCodex(settings.codexBin),
         prompt,
         cwd,
         resume: typeof args?.resume === 'string' && args.resume !== '' ? args.resume : undefined,
         sandbox: typeof args?.sandbox === 'string' ? args.sandbox : settings.codexSandbox,
         timeoutMs: settings.codexTimeoutMs,
-        signal: exec?.signal,
-        children: state.children,
-      })
+          signal: exec?.signal,
+          children: state.children,
+        })
+      } finally {
+        leaveChain(state)
+      }
     },
   }
 }
@@ -848,6 +867,91 @@ function collectAssistant(ctx, sessionId, sinceSeq, settings) {
 }
 
 
+/** Deepest cross-tool delegation currently in flight, or 0 when no chain is open. */
+export function ambientDepth(state) {
+  const chain = state.chain
+  if (chain === undefined || chain.active <= 0) return 0
+  return Date.now() < chain.until ? chain.depth : 0
+}
+
+/**
+ * Mark one outbound delegation as in flight, so anything it triggers inherits its depth.
+ * @param state - bridge bookkeeping.
+ * @param depth - depth of the run that is starting.
+ * @param ttlMs - how long the run may last.
+ */
+export function enterChain(state, depth, ttlMs) {
+  const chain = state.chain
+  chain.active += 1
+  chain.depth = Math.max(chain.depth, depth)
+  chain.until = Date.now() + ttlMs
+}
+
+/**
+ * Release one outbound delegation, closing the chain when the last one ends.
+ * @param state - bridge bookkeeping.
+ */
+export function leaveChain(state) {
+  const chain = state.chain
+  chain.active = Math.max(0, chain.active - 1)
+  if (chain.active === 0) {
+    chain.depth = 0
+    chain.until = 0
+  }
+}
+
+/**
+ * Refuse a delegation that would exceed the configured depth.
+ * @param state - bridge bookkeeping.
+ * @param settings - resolved settings.
+ * @param callerDepth - depth of the caller, when it is known to be a worker.
+ * @param action - tool name used in the message.
+ * @returns the depth this delegation would create.
+ */
+function guardDepth(state, settings, callerDepth, action) {
+  const depth = Math.max(ambientDepth(state), callerDepth ?? 0) + 1
+  if (depth > settings.maxHops) {
+    throw new Error(
+      `${action} would create delegation depth ${String(depth)}, but maxHops is ${String(settings.maxHops)}. ` +
+        'Carry the work out directly instead of delegating again.',
+    )
+  }
+  return depth
+}
+
+/**
+ * Charge one dispatch against the rolling rate limit.
+ * @param state - bridge bookkeeping.
+ * @param settings - resolved settings.
+ */
+function takeDispatchSlot(state, settings) {
+  const now = Date.now()
+  const windowMs = settings.dispatchWindowMs
+  state.recent = state.recent.filter((time) => now - time < windowMs)
+  if (state.recent.length >= settings.dispatchPerMinute) {
+    const retrySeconds = Math.max(1, Math.ceil((windowMs - (now - state.recent[0])) / 1000))
+    throw new Error(
+      `rate limit: ${String(settings.dispatchPerMinute)} dispatches per ${String(Math.round(windowMs / 1000))}s reached; retry in ${String(retrySeconds)}s`,
+    )
+  }
+  state.recent.push(now)
+}
+
+/**
+ * Depth of a session the bridge already knows: workers start one level down.
+ * @param state - bridge bookkeeping.
+ * @param sessionId - calling session, when known.
+ * @returns 1 for a bridge worker, otherwise 0.
+ */
+function callerDepth(state, sessionId) {
+  if (typeof sessionId !== 'string' || sessionId === '') return 0
+  for (const record of state.workers.values()) {
+    if (record.sessionId === sessionId) return 1
+  }
+  return 0
+}
+
+
 /**
  * Restore the worker registry written by a previous process.
  * @param settings - resolved settings.
@@ -1427,6 +1531,18 @@ function resolveSettings(config) {
     if (key === 'codexBin' && typeof value === 'string' && value !== '') merged.codexBin = value
     if (key === 'codexSandbox' && typeof value === 'string' && value !== '') merged.codexSandbox = value
     if (key === 'workersFile' && typeof value === 'string' && value !== '') merged.workersFile = expandHome(value)
+    if (key === 'maxHops') {
+      const hops = Number(value)
+      if (Number.isInteger(hops) && hops >= 0) merged.maxHops = hops
+    }
+    if (key === 'dispatchPerMinute') {
+      const count = Number(value)
+      if (Number.isInteger(count) && count > 0) merged.dispatchPerMinute = count
+    }
+    if (key === 'dispatchWindowMs') {
+      const ms = Number(value)
+      if (Number.isFinite(ms) && ms > 0) merged.dispatchWindowMs = ms
+    }
     if (key === 'maxWorkers') {
       const count = Number(value)
       if (Number.isInteger(count) && count > 0) merged.maxWorkers = count

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-subagent-bridge",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
   "description": "Subagent bridge: lets Codex delegate a task to DeepSeek Harness the way it would spawn a subagent (one call, waits for the answer), plus a codex_dispatch tool for the reverse direction.",
   "keywords": [