dsh-plugin-subagent-bridge 0.7.1 → 0.7.2

package/README.md

@@ -114,7 +114,7 @@ codex mcp remove dsh-bridge
 | `maxWorkersPerRoot` | `4` | **每个工作目录**的 worker 上限（`cwd` 自动分桶，调用方不需要传 owner） |
 | `maxWorkers` | `12` | 全局兜底上限，防止多个项目一起把机器压满 |
 | `workerTtlMs` | `86400000` | 记录超过这个时间没更新就不再占名额（过期自动释放，无需手动清理） |
-| `waitTimeoutMs` | `30000` | `dsh_wait` 的默认超时（1s ~ 1h，客户端可用 `timeoutMs` 覆盖） |
+| `waitTimeoutMs` | `240000` | `dsh_wait` 的默认超时（1s ~ 240s，客户端可用 `timeoutMs` 覆盖） |
 | `readWaitSeconds` | `25` | `dsh_read_result` 的默认长轮询时长（上限 55，客户端可用 `waitSeconds` 覆盖） |
 | `codexBin` | `codex` | Codex 可执行文件；含 `/` 时按路径严格解析，找不到就报错而不回退 |
 | `codexSandbox` | `workspace-write` | `codex_dispatch` 的默认 sandbox（`resume` 时无效） |
@@ -233,7 +233,7 @@ mkdir -p ~/.dsh/skills && cp -R skills/delegate-to-codex ~/.dsh/skills/
 node --test "test/*.test.mjs"
 ```
 
-55 项：握手与版本协商、通知处理、工具清单、未知方法与未知工具、参数校验、元数据列表不含消息内容、派发调用形状、拒绝与错误透出、结果读取的时间基线、未派发会话的拒绝、长轮询（文本晚到即返回 / 超时 / 调用方取消）、真实 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 计入同一预算、握手版本号取自 `package.json`（不再硬编码）、阻塞式 `dsh_task` 不占 spawn 名额（重启后也不占）、按 `cwd` 分桶的每项目预算与全局上限、过期记录到期释放名额。
+57 项：握手与版本协商、通知处理、工具清单、未知方法与未知工具、参数校验、元数据列表不含消息内容、派发调用形状、拒绝与错误透出、结果读取的时间基线、未派发会话的拒绝、长轮询（文本晚到即返回 / 超时 / 调用方取消）、真实 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 计入同一预算、握手版本号取自 `package.json`（不再硬编码）、阻塞式 `dsh_task` 不占 spawn 名额（重启后也不占）、按 `cwd` 分桶的每项目预算与全局上限、过期记录到期释放名额、超时返回 `running: true` 与续等指引、阻塞时长被夹到 240 秒以内。
 `test/persistence.test.mjs` 单独覆盖持久化：文件权限 0600、缺失/损坏/畸形记录、spawn 返回时文件已落盘、完成即缓存、followup 清缓存、close 后重启仍为 closed、冷会话走缓存或 `offline`、并发写不串。
 
 ---

package/index.js

@@ -37,6 +37,9 @@ const PROTOCOL_VERSIONS = ['2025-06-18', '2025-03-26', '2024-11-05']
 /** Largest JSON-RPC body accepted on the bridge endpoint. */
 const MAX_BODY_BYTES = 1024 * 1024
 
+/** Longest a single tool call may block: the MCP client gives up at 300s. */
+const MAX_BLOCKING_SECONDS = 240
+
 /** Worker records kept on disk; the oldest closed ones drop off first. */
 const MAX_PERSISTED_WORKERS = 200
 
@@ -60,12 +63,12 @@ const DEFAULTS = {
   port: 47821,
   endpointFile: join(homedir(), '.dsh', 'bridge', 'endpoint.json'),
   maxResultChars: MAX_RESULT_CHARS,
-  readWaitSeconds: 25,
+  readWaitSeconds: 45,
   codexBin: 'codex',
   codexSandbox: 'workspace-write',
   codexTimeoutMs: 300000,
-  taskTimeoutSeconds: 300,
-  waitTimeoutMs: 30000,
+  taskTimeoutSeconds: MAX_BLOCKING_SECONDS,
+  waitTimeoutMs: MAX_BLOCKING_SECONDS * 1000,
   maxWorkers: 12,
   maxWorkersPerRoot: 4,
   workerTtlMs: 24 * 60 * 60 * 1000,
@@ -80,7 +83,7 @@ const TOOLS = [
   {
     name: 'dsh_task',
     description:
-      'Delegate one self-contained task to DeepSeek Harness and wait for the finished answer, exactly like spawning a subagent: the bridge opens a fresh DSH session in `cwd`, delivers the task, blocks until that turn ends, and returns the answer. Use this for real work delegation; no session id is needed. The prompt is delivered verbatim as an ordinary user message in that session, so write it as a work order for a colleague: do not mention your own tools, skills, or role framing — the worker has no such skill and will only waste a turn looking for it.',
+      'Delegate one self-contained task to DeepSeek Harness and wait for the finished answer, exactly like spawning a subagent: the bridge opens a fresh DSH session in `cwd`, delivers the task, blocks up to 240 seconds, and returns the answer. A result with status "timeout" and running:true means the worker is STILL WORKING: keep the turn open and call dsh_wait or dsh_task again until it is no longer running. Never pass a timeout above 240 seconds — the MCP client aborts tool calls after 300. The prompt is delivered verbatim as an ordinary user message in that session, so write it as a work order for a colleague: do not mention your own tools, skills, or role framing — the worker has no such skill and will only waste a turn looking for it.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -100,7 +103,7 @@ const TOOLS = [
   {
     name: 'dsh_spawn',
     description:
-      'Start a worker and return immediately with its task_name, so several workers can run in parallel; collect answers with dsh_wait. Use fork_turns "all" with `from` to start the worker from a copy of an existing DSH session instead of an empty one.',
+      'Start a worker and return immediately with its task_name, so several workers can run in parallel. This tool does NOT wait and the result is never pushed back, so you must collect it in this same turn with dsh_wait (each call blocks up to 240 seconds; repeat until every target is no longer "running") before you end the turn. Use fork_turns "all" with `from` to start the worker from a copy of an existing DSH session.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -170,7 +173,7 @@ const TOOLS = [
   {
     name: 'dsh_wait',
     description:
-      'Wait until any of the given workers reaches a final state, then return per-worker status. A finished worker carries its final answer only. Prefer long waits over polling.',
+      'Wait until any of the given workers reaches a final state, then return per-worker status. A finished worker carries its final answer only. Long waits beat polling: pass timeoutMs: 240000, and when the reply still lists "running" workers, call this again instead of ending the turn.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -679,7 +682,10 @@ export function createApi(ctx, state, settings) {
     async task({ prompt, cwd, sessionId, agentPreset, timeoutSeconds }) {
       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))
+      const seconds = Math.min(
+        MAX_BLOCKING_SECONDS,
+        Math.max(1, Number.isFinite(timeoutSeconds) ? timeoutSeconds : settings.taskTimeoutSeconds),
+      )
       guardDepth(state, settings, 0, 'dsh_task')
       takeDispatchSlot(state, settings)
       const started = Date.now()
@@ -725,10 +731,18 @@ export function createApi(ctx, state, settings) {
       const collected = finalAnswer(ctx, targetId, before, settings)
       const turnReason = end?.reason?.kind ?? null
       const durationMs = Date.now() - started
+      const status = end === undefined ? 'timeout' : turnReason === 'completed' ? 'completed' : `turn-${String(turnReason)}`
       return {
         sessionId: targetId,
         created,
-        status: end === undefined ? 'timeout' : turnReason === 'completed' ? 'completed' : `turn-${String(turnReason)}`,
+        status,
+        /* A timeout means "still running": say so, and say what to call next. */
+        ...(status === 'timeout'
+          ? {
+              running: true,
+              next: `the worker is still running; do not end the turn. Call dsh_wait({targets:["${targetId}"],timeoutMs:${String(MAX_BLOCKING_SECONDS * 1000)}}) and repeat until it is not "running".`,
+            }
+          : {}),
         text: collected.text,
         truncated: collected.truncated,
         turns: lastTurn(ctx, targetId),
@@ -738,7 +752,10 @@ export function createApi(ctx, state, settings) {
     },
 
     async wait({ targets, timeoutMs }) {
-      const budget = Math.min(3600000, Math.max(1000, Number.isFinite(timeoutMs) ? timeoutMs : settings.waitTimeoutMs))
+      const budget = Math.min(
+        MAX_BLOCKING_SECONDS * 1000,
+        Math.max(1000, Number.isFinite(timeoutMs) ? timeoutMs : settings.waitTimeoutMs),
+      )
       const started = Date.now()
       for (;;) {
         const status = {}
@@ -755,7 +772,20 @@ export function createApi(ctx, state, settings) {
         }
         const waitedMs = Date.now() - started
         if (settled) return { status, timedOut: false, waitedMs }
-        if (waitedMs >= budget) return { status, timedOut: true, waitedMs }
+        if (waitedMs >= budget) {
+          const still = targets.filter((target) => status[target] === 'running' || status[target] === 'pending')
+          return {
+            status,
+            timedOut: true,
+            waitedMs,
+            ...(still.length === 0
+              ? {}
+              : {
+                  running: true,
+                  next: `still running: ${still.join(', ')}; call dsh_wait again with the same targets until none of them are "running"`,
+                }),
+          }
+        }
         await sleep(Math.min(300, budget - waitedMs))
       }
     },
@@ -1604,11 +1634,11 @@ function resolveSettings(config) {
     }
     if (key === 'waitTimeoutMs') {
       const ms = Number(value)
-      if (Number.isFinite(ms) && ms > 0) merged.waitTimeoutMs = Math.min(3600000, Math.max(1000, ms))
+      if (Number.isFinite(ms) && ms > 0) merged.waitTimeoutMs = Math.min(MAX_BLOCKING_SECONDS * 1000, Math.max(1000, ms))
     }
     if (key === 'taskTimeoutSeconds') {
       const seconds = Number(value)
-      if (Number.isFinite(seconds) && seconds > 0) merged.taskTimeoutSeconds = Math.min(600, seconds)
+      if (Number.isFinite(seconds) && seconds > 0) merged.taskTimeoutSeconds = Math.min(MAX_BLOCKING_SECONDS, seconds)
     }
     if (key === 'codexTimeoutMs') {
       const ms = Number(value)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-subagent-bridge",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "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": [

package/skills/deepseek-worker/SKILL.md

@@ -5,7 +5,12 @@ description: 交给 DSH / 开个 worker 时使用；把自足任务当 subagent
 
 # 把任务交给 DSH（subagent 用法）
 
-DSH 是通过 `dsh-bridge` MCP 接上来的另一个编码代理。用法和"给自己开一个 subagent"一样：**一次调用，给它一个自足的任务，等它把这一轮干完并返回结论。**
+DSH 是通过 `dsh-bridge` MCP 接上来的另一个编码代理。用法和"给自己开一个 subagent"一样：**给它一个自足的任务，等它把这一轮干完并返回结论。**
+
+> **最重要的一条：任务没跑完，不许结束回合。**
+> Codex 原生的 subagent 会把结果**推送**回来、自动唤醒你；这个桥是**拉取**式的 —— 你结束回合，结果就没人接收了，用户只能人工来叫你回去。所以：只要还有 `running` 的 worker，就必须继续调 `dsh_wait` / `dsh_task` / `dsh_read_result`，直到全部到终态。
+
+> **单次调用最长 240 秒。** Codex 的 MCP 客户端在 **300 秒**时会把工具调用判为失败（`timed out awaiting tools/call after 300s`）。所以 `timeoutSeconds` / `timeoutMs` / `waitSeconds` 一律不要超过 240，超了也不会生效（会被夹到 240）。
 
 ## 先确认工具在
 
@@ -36,7 +41,22 @@ dsh_task({
 }
 ```
 
-`dsh_task` **阻塞到 DSH 那一轮结束**再返回，不需要轮询。默认最多等 300 秒，更重的任务传 `timeoutSeconds`（上限 600）。
+`dsh_task` **阻塞到 DSH 那一轮结束**再返回，最多等 **240 秒**（默认值，也是上限）。超时它不会假装成功，而是明确告诉你还在跑：
+
+```jsonc
+{ "status": "timeout", "running": true, "text": "",
+  "next": "the worker is still running; do not end the turn. Call dsh_wait(...) and repeat until it is not running." }
+```
+
+**看到 `running: true` 就继续等**，不要结束回合、也不要把空 `text` 当成"它没干成"。
+
+最省事的续等方式（`dsh_task` 本身会阻塞，再调一次同一个 sessionId 等价于继续等）：
+
+```jsonc
+dsh_task({ "sessionId": "session-…", "prompt": "继续", "timeoutSeconds": 240 })
+```
+
+更好的方式是不用 `dsh_task` 的续做语义，而是直接用 `dsh_wait` 等它（见下节）。
 
 ## 多件活：并行开 worker
 
@@ -64,7 +84,7 @@ dsh_close({ "worker": "audit_api" })
 
 - **并发上限 4 个 worker**（`maxWorkers`）。**已完成但没 `dsh_close` 的也占名额** —— 用完就关，别一直挂着。
 - `dsh_task` 是阻塞的、一次一件；它**不占**那 4 个名额，适合"我就等着这一件"。
-- `dsh_wait` 给**长一点的超时**（默认 30 秒偏短，重活用 2~5 分钟），不要用短超时反复轮询 —— Codex 的原话是 "prefer longer waits (minutes) to avoid busy polling"。
+- `dsh_wait` 每次给满 **240000**（毫秒）。**它返回 `timedOut: true` / 仍有 `"running"` 时，不代表结束，只代表"还没好"** —— 继续调它，直到没有任何 target 是 `running`/`pending`。短超时反复轮询是错的（Codex 原话：prefer longer waits (minutes) to avoid busy polling）。
 - `dsh_wait` 只要**任意一个**到终态就返回，所以它是"收割完成项"的循环，而不是"等全部"。
 
 **不要并行的情况**
@@ -114,11 +134,21 @@ worker 收到的是**一条普通用户消息**，它看不到你这边有没有
 
 一旦 prompt 里出现 `deepseek-worker`，worker 会以为那是它自己的技能或工具，白费一轮去确认「本会话没有这个技能」。
 
+## 收工的判断标准
+
+下面三件事同时成立，才可以结束回合：
+
+1. 所有派出去的 worker 状态都是 `{completed}` / `{errored}` / `"closed"` / `"not_found"` / `"offline"`；
+2. 没有任何 worker 是 `"running"` 或 `"pending"`；
+3. 你已经对每个完成的 worker 做过必要的复核（跑测试、看 diff）。
+
+只要还有 `running`，就继续 `dsh_wait`。**宁可多等一轮，也不要留一个没人收的 worker。**
+
 ## 拿到结果之后
 
 - `completed` → 读 `text`，判断是否真的达成交付；需要复核就自己跑一遍验证命令。
 - `turn-…`（如 `turn-aborted`、`turn-error`）→ 那一轮没正常结束，把 `text` 里的信息转述给用户，必要时自己接手。
-- `timeout` → 工作**没有丢**，DSH 那边还在跑。用同一个 `sessionId` 再调一次问进度，或先用低阶工具看一眼。
+- `timeout`（带 `running: true`）→ 工作**没有丢**，DSH 那边还在跑。**必须继续等**：`dsh_wait({targets:[…]})` 或再调一次 `dsh_task({sessionId, …})`，直到不是 running。
 
 ## 同一个 worker 继续干