dsh-plugin-subagent-bridge 0.13.0 → 0.14.0

package/README.md

@@ -56,6 +56,48 @@ dsh_task({ prompt: "…", cwd: "/repo/clawer" })
 - 返回结果里带上 `workspace: { id, title, path }`，方便确认落在哪个项目；
 - 项目操作失败不影响派发本身（分组是外观，不因此让任务失败）。
 
+## 回答 worker 的问题（`dsh_answer`）
+
+worker 需要用户拍板时会调用 `ask_user_question`，然后**卡在那里等**。如果人不在，任务就停住了。
+
+桥把这种情况暴露出来：
+
+```jsonc
+// dsh_wait 的返回
+{
+  "status": { "w1": "running" },
+  "timedOut": true,
+  "pendingQuestion": {
+    "callId": "call_abc",
+    "questions": [
+      {
+        "id": "mode",
+        "question": "用哪种模式？",
+        "header": "Choose Mode",
+        "options": [{ "label": "快速", "description": "只跑单测" }, { "label": "完整" }]
+      }
+    ]
+  },
+  "next": "blocked on a question: answer it with dsh_answer, or call dsh_wait again"
+}
+```
+
+调用方（Codex / Claude）看到 `pendingQuestion` 就可以代用户回答：
+
+```jsonc
+dsh_answer({
+  "worker": "w1",
+  "answers": [{ "id": "mode", "selected": ["快速"] }]   // custom 可用于自由文本
+})
+```
+
+细节：
+
+- 一个问题的 id 必须**恰好出现一次**，否则底层会报 `BAD_ANSWER`；
+- `selected` 是选项 label 数组，多选时给多个；跳过一个问题就给空数组；
+- 回答是插进正在等待的那个回合的（底层用 `steer`），worker 立刻继续；
+- 只有真卡在 `ask_user_question` 上才算「等待中」——工具一旦返回结果就不再报。
+
 ## 排队还是插话（`mode`）
 
 DSH 的「繁忙时的发送行为」只有两种，桥把它们原样交给调用方：
@@ -79,6 +121,8 @@ dsh_task({ sessionId: "session-…", prompt: "停一下，改成只跑单测", m
 
 `dsh_task` 对正在运行的会话默认会拒绝，错误信息里会提示改用 `steer`。
 
+第三个细节是返回值：插话的回复和原任务在**同一个回合**里，所以不能简单取"这一轮最后一条 assistant 文本"——那可能是原任务后面的步骤。桥会在插话后定位到**自己那条 user/message**，只取它之后的 assistant 文本作为回答。
+
 ## 创建项目（workspace）
 
 DSH 的侧边栏分组是"项目（workspace）"，和会话的工作目录是两回事：新建会话默认落在「未分组」，除非它所在的目录已经是一个项目。

package/index.js

@@ -207,6 +207,37 @@ const TOOLS = [
       additionalProperties: false,
     },
   },
+  {
+    name: 'dsh_answer',
+    description:
+      'Answer a question a worker is blocked on (ask_user_question) on the user behalf. dsh_wait reports such a question as pendingQuestion; every question id in it must appear exactly once in answers.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        worker: { type: 'string', description: 'task_name or session id of the blocked worker.' },
+        answers: {
+          type: 'array',
+          description: 'One entry per pending question.',
+          items: {
+            type: 'object',
+            properties: {
+              id: { type: 'string', description: 'Question id, copied from pendingQuestion.' },
+              selected: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Chosen option labels; empty when the question is being skipped.',
+              },
+              custom: { type: 'string', description: 'Free-form answer when no option fits.' },
+            },
+            required: ['id', 'selected'],
+            additionalProperties: false,
+          },
+        },
+      },
+      required: ['worker', 'answers'],
+      additionalProperties: false,
+    },
+  },
   {
     name: 'dsh_list_workers',
     description: 'List the workers this bridge started, with their task_name, session id, and live status.',
@@ -278,6 +309,81 @@ const TOOLS = [
   },
 ]
 
+/**
+ * The question a worker is currently blocked on, if any.
+ * `ask_user_question` records a tool call and waits for an answer; while it waits the call
+ * has no result yet, which is exactly the signal used here.
+ * @param ctx - Host context.
+ * @param sessionId - session to inspect.
+ * @returns the pending call and its questions, or undefined.
+ */
+function askable(state, ctx, targets) {
+  for (const target of targets) {
+    const resolved = resolveWorker(state, target)
+    const sessionId = resolved === undefined ? target : resolved.sessionId
+    const asked = pendingQuestion(ctx, sessionId)
+    if (asked !== undefined) return { worker: target, ...asked }
+  }
+  return undefined
+}
+
+export function pendingQuestion(ctx, sessionId) {
+  const session = ctx.get('sessions')?.get?.(sessionId)
+  if (session === undefined || session === null) return undefined
+  const settled = new Set()
+  let waiting
+  for (const event of session.snapshotEvents()) {
+    if (event.type === 'tool/result' && typeof event.data?.callId === 'string') settled.add(event.data.callId)
+    if (event.type === 'tool/call' && event.data?.name === 'ask_user_question') waiting = event.data
+  }
+  if (waiting === undefined || settled.has(waiting.callId)) return undefined
+  let parsed
+  try {
+    parsed = JSON.parse(typeof waiting.arguments === 'string' ? waiting.arguments : '{}')
+  } catch {
+    return undefined
+  }
+  const questions = Array.isArray(parsed?.questions) ? parsed.questions : []
+  if (questions.length === 0) return undefined
+  return {
+    callId: String(waiting.callId),
+    questions: questions.map((question) => ({
+      id: String(question?.id ?? ''),
+      question: String(question?.question ?? ''),
+      ...(typeof question?.header === 'string' ? { header: question.header } : {}),
+      ...(question?.multi_select === true ? { multiSelect: true } : {}),
+      ...(Array.isArray(question?.options)
+        ? {
+            options: question.options.map((option) => ({
+              label: String(option?.label ?? ''),
+              ...(typeof option?.description === 'string' ? { description: option.description } : {}),
+            })),
+          }
+        : {}),
+    })),
+  }
+}
+
+/**
+ * Sequence number of the first message the caller itself delivered after `sinceSeq`.
+ * With steer the reply shares the running turn, so "the last assistant text of the turn"
+ * can be a step of the original task; anchoring on our own message keeps it exact.
+ * @param ctx - Host context.
+ * @param sessionId - session to read.
+ * @param sinceSeq - sequence captured before the prompt was delivered.
+ * @returns the sequence, or the original value when nothing matches.
+ */
+function firstDeliveredMessageSeq(ctx, sessionId, sinceSeq) {
+  const session = ctx.get('sessions')?.get?.(sessionId)
+  if (session === undefined || session === null) return sinceSeq
+  for (const event of session.snapshotEvents()) {
+    if (Number(event.seq) <= sinceSeq) continue
+    if (event.type !== 'user/message') continue
+    return Number(event.seq)
+  }
+  return sinceSeq
+}
+
 /**
  * Start the bridge.
  * @param ctx - Host context.
@@ -639,6 +745,20 @@ async function callTool(id, params, api, signal) {
         const worker = requireString(args.worker, 'worker')
         return ok(id, text(await api.close({ worker })))
       }
+      case 'dsh_answer': {
+        const worker = requireString(args.worker, 'worker')
+        if (!Array.isArray(args.answers) || args.answers.length === 0) throw new Error('answers must be a non-empty array')
+        const answers = args.answers.map((entry, index) => {
+          const questionId = requireString(entry?.id, `answers[${index}].id`)
+          if (!Array.isArray(entry?.selected)) throw new Error(`answers[${index}].selected must be an array`)
+          return {
+            id: questionId,
+            selected: entry.selected.map((label, at) => requireString(label, `answers[${index}].selected[${at}]`)),
+            ...(typeof entry.custom === 'string' && entry.custom !== '' ? { custom: entry.custom } : {}),
+          }
+        })
+        return ok(id, text(await api.answer({ worker, answers })))
+      }
       case 'dsh_list_workers':
         return ok(id, text(await api.listWorkers()))
       case 'dsh_wait': {
@@ -908,7 +1028,10 @@ export function createApi(ctx, state, settings) {
       }
 
       const end = await finished
-      const collected = finalAnswer(ctx, targetId, before, settings)
+      /* A steered reply lives inside the turn that was already running, so anchor the
+       * answer on the message we delivered instead of the turn's last assistant text. */
+      const answerFrom = deliveryMode === 'steer' ? firstDeliveredMessageSeq(ctx, targetId, before) : before
+      const collected = finalAnswer(ctx, targetId, answerFrom, settings)
       const turnReason = end?.reason?.kind ?? null
       const durationMs = Date.now() - started
       const status = end === undefined ? 'timeout' : turnReason === 'completed' ? 'completed' : `turn-${String(turnReason)}`
@@ -954,18 +1077,23 @@ export function createApi(ctx, state, settings) {
           if (typeof value !== 'string' || final) settled = true
         }
         const waitedMs = Date.now() - started
-        if (settled) return { status, timedOut: false, waitedMs }
+        const asked = askable(state, ctx, targets)
+        if (settled) return { status, timedOut: false, waitedMs, ...(asked === undefined ? {} : { pendingQuestion: asked }) }
         if (waitedMs >= budget) {
           const still = targets.filter((target) => status[target] === 'running' || status[target] === 'pending')
           return {
             status,
             timedOut: true,
             waitedMs,
+            ...(asked === undefined ? {} : { pendingQuestion: asked }),
             ...(still.length === 0
               ? {}
               : {
                   running: true,
-                  next: `still running: ${still.join(', ')}; call dsh_wait again with the same targets until none of them are "running"`,
+                  next:
+                    asked === undefined
+                      ? `still running: ${still.join(', ')}; call dsh_wait again with the same targets until none of them are "running"`
+                      : `blocked on a question: answer it with dsh_answer, or call dsh_wait again`,
                 }),
           }
         }
@@ -973,6 +1101,20 @@ export function createApi(ctx, state, settings) {
       }
     },
 
+    async answer({ worker, sessionId, answers }) {
+      const target = worker === undefined ? sessionId : (resolveWorker(state, worker)?.sessionId ?? worker)
+      if (typeof target !== 'string' || target === '') throw new Error('name a worker or a sessionId')
+      const asked = pendingQuestion(ctx, target)
+      if (asked === undefined) throw new Error('that worker is not waiting on a question')
+      const service = ctx.get('userQuestions')
+      const agent = ctx.get('agents')?.get?.(target)
+      if (service === undefined || service === null || agent === undefined) {
+        throw new Error('the question service is unavailable')
+      }
+      const accepted = service.answer(agent, asked.callId, { answers })
+      return { answered: accepted === true, callId: asked.callId, sessionId: target }
+    },
+
     async dispatch({ sessionId, text, mode }) {
       const service = controller()
       if (service === undefined || service === null) throw new Error('session controller is unavailable')

package/package.json

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