dsh-plugin-subagent-bridge 0.10.1 → 0.11.1

package/README.md

@@ -56,6 +56,28 @@ dsh_task({ prompt: "…", cwd: "/repo/clawer" })
 - 返回结果里带上 `workspace: { id, title, path }`，方便确认落在哪个项目；
 - 项目操作失败不影响派发本身（分组是外观，不因此让任务失败）。
 
+## 排队还是立刻打断（`mode`）
+
+DSH 的 prompt 有两种投递模式，桥把它们交给调用方选：
+
+| `mode` | 行为 |
+| --- | --- |
+| `queue`（默认） | 等当前回合跑完再处理这条消息 |
+| `steer` | **立刻打断**当前回合，把这条消息插进去 |
+
+`dsh_task`、`dsh_spawn`、`dsh_followup` 都支持：
+
+```js
+dsh_followup({ worker: "w1", message: "别改了，先把现在的结果汇报一下", mode: "steer" })
+dsh_task({ sessionId: "session-…", prompt: "停一下，改成只跑单测", mode: "steer" })
+```
+
+和 `dsh_dispatch` 的关系：`dsh_dispatch` 一直有 `mode`，但它只投递、不等待；`dsh_task` 会阻塞到回合结束，所以以前对正在运行的会话直接拒绝。现在传 `mode: "steer"` 就允许插进运行中的会话——**它会先打断当前回合**，然后等这一轮结束才返回。
+
+一个容易踩的细节：`steer` 的消息会被**当前回合直接吸收**（不会新开一轮），所以等待条件不能是"下一个回合结束"。早期实现就是这么写的，结果答案已经回来了、调用却一直等到 120 秒超时才知道。现在 steer 等的是「当前回合结束」。
+
+返回里带 `mode` 字段，方便确认这次是排队还是打断。
+
 ## 指定模型
 
 `dsh_task`、`dsh_spawn`、`dsh_followup` 都可以带 `model`，让 worker 跑在指定模型上：

package/index.js

@@ -115,6 +115,13 @@ const TOOLS = [
           description:
             'Grouping for the new session. true creates a DSH project (workspace) for `cwd`, titled after its last path segment, when none owns that directory yet; a string uses that title instead. Omit (or false) to only reuse an existing project, leaving the session ungrouped when the directory has none.',
         },
+        mode: {
+          type: 'string',
+          enum: ['queue', 'steer'],
+          description:
+            'delivery: "queue" (default) waits for the running turn to finish, "steer" interrupts it and inserts this message now.',
+        },
+
         reasoningEffort: {
           type: 'string',
           description: 'Reasoning level for `model`, if that model offers levels (low, medium, high, max...).',
@@ -151,6 +158,13 @@ const TOOLS = [
           description:
             'Grouping for the new worker. true creates a DSH project (workspace) for `cwd` when none owns it; a string uses that title. Omit to only reuse an existing project.',
         },
+        mode: {
+          type: 'string',
+          enum: ['queue', 'steer'],
+          description:
+            'delivery: "queue" (default) waits for the running turn to finish, "steer" interrupts it and inserts this message now.',
+        },
+
         reasoningEffort: { type: 'string', description: 'Reasoning level for `model`, when that model offers levels.' },
       },
       required: ['task_name', 'message'],
@@ -171,6 +185,12 @@ const TOOLS = [
           description: 'Switch this worker to another model before the turn, as "provider/model". Omit to keep its current one.',
         },
         reasoningEffort: { type: 'string', description: 'Reasoning level for `model`, when that model offers levels.' },
+        mode: {
+          type: 'string',
+          enum: ['queue', 'steer'],
+          description:
+            'delivery: "queue" (default) waits for the running turn to finish, "steer" interrupts it and inserts this message now.',
+        },
       },
       required: ['worker', 'message'],
       additionalProperties: false,
@@ -590,6 +610,7 @@ async function callTool(id, params, api, signal) {
               from: args.from,
               cwd: args.cwd,
               workspace: args.workspace === true || (typeof args.workspace === 'string' && args.workspace !== '') ? args.workspace : undefined,
+              mode: args.mode === 'steer' ? 'steer' : undefined,
               model: typeof args.model === 'string' && args.model !== '' ? args.model : undefined,
               reasoningEffort:
                 typeof args.reasoningEffort === 'string' && args.reasoningEffort !== '' ? args.reasoningEffort : undefined,
@@ -606,6 +627,7 @@ async function callTool(id, params, api, signal) {
             await api.followup({
               worker,
               message,
+              mode: args.mode === 'steer' ? 'steer' : undefined,
               model: typeof args.model === 'string' && args.model !== '' ? args.model : undefined,
               reasoningEffort:
                 typeof args.reasoningEffort === 'string' && args.reasoningEffort !== '' ? args.reasoningEffort : undefined,
@@ -644,6 +666,7 @@ async function callTool(id, params, api, signal) {
               sessionId,
               agentPreset: typeof args.agentPreset === 'string' && args.agentPreset !== '' ? args.agentPreset : undefined,
               workspace: args.workspace === true || (typeof args.workspace === 'string' && args.workspace !== '') ? args.workspace : undefined,
+              mode: args.mode === 'steer' ? 'steer' : undefined,
               model: typeof args.model === 'string' && args.model !== '' ? args.model : undefined,
               reasoningEffort:
                 typeof args.reasoningEffort === 'string' && args.reasoningEffort !== '' ? args.reasoningEffort : undefined,
@@ -718,7 +741,7 @@ export function createApi(ctx, state, settings) {
       })
     },
 
-    async spawn({ taskName, message, forkTurns, from, cwd, model, reasoningEffort, workspace }) {
+    async spawn({ taskName, message, forkTurns, from, cwd, model, reasoningEffort, workspace, mode }) {
       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`)
@@ -750,7 +773,7 @@ export function createApi(ctx, state, settings) {
       const before = Number(sessions()?.get?.(sessionId)?.seq ?? 0)
       const requestId = randomUUID()
       const accepted = await service.prompt(
-        { sessionId, requestId, mode: 'queue', content: [{ type: 'text', text: message }] },
+        { sessionId, requestId, mode: mode === 'steer' ? 'steer' : 'queue', content: [{ type: 'text', text: message }] },
         AbortSignal.timeout(30000),
       )
       state.dispatched.add(sessionId)
@@ -775,7 +798,7 @@ export function createApi(ctx, state, settings) {
       }
     },
 
-    async followup({ worker, message, model, reasoningEffort }) {
+    async followup({ worker, message, model, reasoningEffort, mode }) {
       const target = resolveWorker(state, worker)
       if (target === undefined) throw new Error(`unknown worker ${JSON.stringify(worker)}`)
       const service = controller()
@@ -785,7 +808,7 @@ export function createApi(ctx, state, settings) {
       const before = Number(sessions()?.get?.(target.sessionId)?.seq ?? 0)
       const requestId = randomUUID()
       const accepted = await service.prompt(
-        { sessionId: target.sessionId, requestId, mode: 'queue', content: [{ type: 'text', text: message }] },
+        { sessionId: target.sessionId, requestId, mode: mode === 'steer' ? 'steer' : 'queue', content: [{ type: 'text', text: message }] },
         AbortSignal.timeout(30000),
       )
       state.baseline.set(target.sessionId, before)
@@ -824,7 +847,7 @@ export function createApi(ctx, state, settings) {
       return rows
     },
 
-    async task({ prompt, cwd, sessionId, agentPreset, timeoutSeconds, model, reasoningEffort, workspace }) {
+    async task({ prompt, cwd, sessionId, agentPreset, timeoutSeconds, model, reasoningEffort, workspace, mode }) {
       const service = controller()
       if (service === undefined || service === null) throw new Error('session controller is unavailable')
       const seconds = Math.min(
@@ -846,17 +869,23 @@ export function createApi(ctx, state, settings) {
         }
         if (typeof targetId !== 'string' || targetId === '') throw new Error('session controller did not return a session id')
         created = true
-      } else if (ctx.get('agents')?.get?.(targetId)?.status === 'running') {
-        throw new Error('that session is running; use dsh_dispatch plus dsh_read_result instead')
+      } else if (mode !== 'steer' && ctx.get('agents')?.get?.(targetId)?.status === 'running') {
+        /* Steering exists precisely to reach a running session; queueing into one would
+         * silently wait for a turn this call is not tracking. */
+        throw new Error('that session is running; pass mode:"steer" to interrupt it, or use dsh_dispatch plus dsh_read_result')
       }
 
       const appliedModel = await applyModelSpec(ctx, targetId, model, reasoningEffort)
+      const deliveryMode = mode === 'steer' ? 'steer' : 'queue'
       const turnBefore = lastTurn(ctx, targetId)
+      /* A steered message is absorbed by the turn that is already running, so waiting for
+       * a strictly newer turn would hang until the timeout even after the answer landed. */
+      const waitAfter = deliveryMode === 'steer' ? Math.max(0, turnBefore - 1) : turnBefore
       const before = Number(sessions()?.get?.(targetId)?.seq ?? 0)
-      const finished = waitForTurnEnd(ctx, targetId, turnBefore, seconds * 1000)
+      const finished = waitForTurnEnd(ctx, targetId, waitAfter, seconds * 1000)
       const requestId = randomUUID()
       const accepted = await service.prompt(
-        { sessionId: targetId, requestId, mode: 'queue', content: [{ type: 'text', text: prompt }] },
+        { sessionId: targetId, requestId, mode: deliveryMode, content: [{ type: 'text', text: prompt }] },
         AbortSignal.timeout(30000),
       )
       state.dispatched.add(targetId)
@@ -895,6 +924,7 @@ export function createApi(ctx, state, settings) {
           : {}),
         ...(appliedModel === undefined ? {} : { model: appliedModel }),
         ...(placed === undefined ? {} : { workspace: placed }),
+        mode: deliveryMode,
         text: collected.text,
         truncated: collected.truncated,
         turns: lastTurn(ctx, targetId),

package/package.json

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