dsh-remote-bridge 2.2.1 → 2.2.3

package/docs/api/asyncapi.yaml

@@ -1,8 +1,15 @@
 asyncapi: 3.0.0
 info:
   title: DeepSeek Harness Mobile Events
-  version: 2.2.1
-  description: Live file and authorized DSH chat events. Reconnect clients must refresh REST state; unbounded replay is not provided.
+  version: 2.2.3
+  description: |
+    Live file and authorized DSH chat events. Reconnect clients must refresh
+    REST state; unbounded replay is not provided.
+
+    `chat.turn.failed` carries the terminal failure of a model turn (rate
+    limit, quota exhausted, invalid API key, signed-out stop). Without it a
+    remote client sees an ordinary `chat.turn.end` and keeps waiting on a run
+    that already failed.
 servers:
   local:
     host: 127.0.0.1:3090
@@ -32,7 +39,7 @@ components:
           id: { type: string }
           type:
             type: string
-            examples: [file.changed, file.trashed, chat.message.delta, chat.message.committed, chat.session.status, chat.approval.requested, chat.approval.resolved, connection.ready]
+            examples: [file.changed, file.trashed, chat.message.delta, chat.message.committed, chat.session.status, chat.approval.requested, chat.approval.resolved, chat.turn.failed, connection.ready]
           time: { type: integer }
           data:
             oneOf:
@@ -40,6 +47,7 @@ components:
               - $ref: '#/components/schemas/ChatMessageCommitted'
               - $ref: '#/components/schemas/ChatApprovalRequested'
               - $ref: '#/components/schemas/ChatApprovalResolved'
+              - $ref: '#/components/schemas/ChatTurnFailed'
               - type: object
                 additionalProperties: true
   schemas:
@@ -84,3 +92,30 @@ components:
         sessionId: { type: string }
         approvalId: { type: string }
         outcome: { type: string, enum: [allowed-once, rejected, cancelled, unavailable] }
+    ChatTurnFailed:
+      type: object
+      description: |
+        Terminal failure of a model turn. Emitted instead of a plain
+        `chat.turn.end` when the host reports `reason.kind === 'error'` (rate
+        limit, quota exhausted, invalid key) or an abort caused by signing out
+        of the DeepSeek account. Clients must stop their running indicator and
+        show the message; otherwise a failed run keeps looking like it is in
+        flight.
+      required: [sessionId, eventType, failure]
+      properties:
+        sessionId: { type: string }
+        eventType: { type: string, const: turn/end }
+        seq: { type: integer }
+        failure:
+          type: object
+          description: |
+            `message` is the host's own wording, forwarded verbatim so clients
+            can decide localization. `code` is present only when the host
+            supplies one; an empty string is meaningful and must not be
+            treated as absent. `stopped` marks an account-sign-out stop, which
+            is not a model fault.
+          required: [message]
+          properties:
+            message: { type: string }
+            code: { type: string }
+            stopped: { type: boolean, const: true }

package/docs/api/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: DeepSeek Harness Mobile API
-  version: 2.2.1
+  version: 2.2.3
   description: Versioned file and chat BFF for mobile and third-party DSH clients. HTTP and HTTPS are both supported.
 servers:
   - url: http://127.0.0.1:3090/api/v1
@@ -582,6 +582,102 @@ paths:
       responses:
         '202': { description: Decision accepted by DSH. }
         '409': { $ref: '#/components/responses/Error' }
+  /chat/sessions/{sessionId}/questions:
+    get:
+      operationId: listUserQuestions
+      description: |
+        Lists questions an agent is waiting on, from two sources merged together:
+        the ones this bridge is holding open (an `ask_user_question` call with no
+        `timeout`, taken over from the host's `user-questions/request` waterfall),
+        and the ones the kernel still accepts a late answer for (`continued`).
+        A question held open is reported first; the same `callId` never appears twice.
+        The `viaBridge` flag distinguishes the two. An unknown or inactive session
+        yields an empty list rather than an error.
+      parameters:
+        - name: sessionId
+          in: path
+          required: true
+          schema: { type: string }
+      responses:
+        '200':
+          description: Questions the current device may answer.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [items]
+                properties:
+                  items:
+                    type: array
+                    items:
+                      type: object
+                      required: [callId, state, questions]
+                      properties:
+                        callId: { type: string }
+                        state: { type: string, enum: [continued] }
+                        viaBridge:
+                          type: boolean
+                          description: True when the bridge is holding this question open, so the agent is blocked on it right now.
+                        questions:
+                          type: array
+                          items:
+                            type: object
+                            required: [id, question]
+                            properties:
+                              id: { type: string }
+                              question: { type: string }
+                              header: { type: string }
+                              detail: { type: string }
+                              multiSelect: { type: boolean }
+                              options:
+                                type: array
+                                items:
+                                  type: object
+                                  required: [label]
+                                  properties:
+                                    label: { type: string }
+                                    description: { type: string }
+        '404': { $ref: '#/components/responses/Error' }
+  /chat/sessions/{sessionId}/questions/{callId}/answer:
+    post:
+      operationId: answerUserQuestion
+      description: |
+        Answers one question set. Answers for a question the bridge holds open are
+        delivered as the return value of the tool call that is waiting; answers for a
+        `continued` question are steered into the session as a new turn. The
+        `selected` array carries option labels and must match the question's own
+        options; use `custom` for free text.
+      parameters:
+        - name: sessionId
+          in: path
+          required: true
+          schema: { type: string }
+        - name: callId
+          in: path
+          required: true
+          schema: { type: string }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [answers]
+              properties:
+                answers:
+                  type: array
+                  items:
+                    type: object
+                    required: [id, selected]
+                    properties:
+                      id: { type: string }
+                      selected: { type: array, items: { type: string } }
+                      custom: { type: string }
+      responses:
+        '202': { description: Answer accepted. }
+        '400': { $ref: '#/components/responses/Error' }
+        '409': { $ref: '#/components/responses/Error' }
+        '503': { $ref: '#/components/responses/Error' }
   /chat/sessions/{sessionId}/commands:
     get:
       operationId: listSessionCommands

package/lib/index.d.ts

@@ -220,16 +220,37 @@ interface DshApiProxy {
      *
      * `attachmentId` 形如 `sha256:<hex>`（**含冒号**，客户端必须 URL 编码）。
      * 返回 `Uint8Array` 而不是 base64：图片动辄上百 KB，多一次编解码纯属浪费。
+     *
+     * **必须带 `sessionId`**：内核要靠它读会话事件、取出这张图的真实 ref，
+     * 再据此做完整性校验（详见 chat-adapter 的 readAttachment 注释）。
      */
     readAttachment(request: {
       rpcId: string;
       payload: {
+        sessionId: string;
         attachmentId: string;
       };
     }): Promise<RpcResponse<{
       bytes: Uint8Array;
       mediaType: string;
     }>>;
+    /**
+     * 取回一张**交接图片**的字节（纯文本模型发图时，图片被落成工作区文件）。
+     *
+     * 与 [readAttachment] 的区别：那一个取内核附件存储里的图（走
+     * `sessionController.attachment`），这一个取插件自己写进 `.dsh-images/`
+     * 的交接件。手机端用它把图片**显示**给人看；消息里的路径文本照旧留给模型。
+     */
+    readHandoffImage(request: {
+      rpcId: string;
+      payload: {
+        sessionId: string;
+        name: string;
+      };
+    }): Promise<RpcResponse<{
+      bytes: Uint8Array;
+      mediaType: string;
+    }>>;
     cancel(request: {
       rpcId: string;
       payload: {
@@ -337,6 +358,36 @@ interface DshApiProxy {
       agentPreset: string;
     }>>;
   };
+  /**
+   * 用户问题（内核 `ctx.userQuestions`，即 ask_user_question 工具）。
+   *
+   * 为什么单开一个命名空间而不是塞进 `sessions`：它由**另一个内核服务**提供
+   * （`@deepseek-ai/dsh-user-questions`），在一条没装它的 profile 上是**可选能力** ——
+   * 分开之后，「这个能力不在」和「这个会话有问题」在类型上就分得开。
+   */
+  userQuestions: {
+    /**
+     * 列出还能回答的问题（内核 `continued(agent)`）。
+     * 没有 live agent、或没有该服务时返回空列表 —— 冷会话是常态，不该报错。
+     */
+    list(request: {
+      rpcId: string;
+      payload: {
+        sessionId: string;
+      };
+    }): Promise<RpcResponse<{
+      items: UserQuestionView[];
+    }>>;
+    /** 提交答案；失败原因见 [UserQuestionAnswerOutcome]。 */
+    answer(request: {
+      rpcId: string;
+      payload: {
+        sessionId: string;
+        callId: string;
+        answer: UserQuestionAnswer;
+      };
+    }): Promise<RpcResponse<UserQuestionAnswerOutcome>>;
+  };
   events: {
     mux(request: {
       rpcId: string;
@@ -468,6 +519,60 @@ interface PendingApprovalView {
   risk: 'standard' | 'full-access';
   requestedAt: number;
 }
+/**
+ * 一条「还能回答」的用户问题 —— 内核 `userQuestions.continued()` 的一行。
+ *
+ * 为什么类型是宽松的、而不是照抄内核的 `AskUserQuestionItem`：内核往 item 或
+ * question 上加过字段（`intent` 就是一例），手机端该自己决定要不要用，
+ * 不该等插件跟着发版。所以这里只钉住三个**契约字段**，其余原样透传。
+ */
+interface UserQuestionView {
+  callId: string;
+  /** 内核 `UserQuestionState`：'open' 或 'continued'；本端点只返回 continued。 */
+  state: string;
+  /** 问题项**原样**透传（id / question / detail? / header? / options? / multiSelect? / intent?）。 */
+  questions: unknown[];
+  /** 内核以后加的字段照样透传，不在这里裁剪。 */
+  [key: string]: unknown;
+}
+/** 一条问题的答案（内核 `AskUserQuestionAnswerItem`）。 */
+interface UserQuestionAnswerItem {
+  /** 被回答的问题 id，必须与请求里的问题 id 对上。 */
+  id: string;
+  /** 选中的选项 label；多选时可能多项。 */
+  selected: string[];
+  /** 可选的「其他」自由文本。 */
+  custom?: string;
+}
+/** 一次提交的完整答案批次（内核 `AskUserQuestionAnswer`）：一次调用里的每个问题各占一项。 */
+interface UserQuestionAnswer {
+  answers: UserQuestionAnswerItem[];
+}
+/**
+ * 「把答案送进内核」的结果。
+ *
+ * 刻意**不走 RpcResponse 的 error 通道**：`unwrapDsh` 只认 `not-found` /
+ * `busy` / `locked` 三种 code 去映射 HTTP 状态，其余一律 400 —— 而这里需要区分
+ * 409 / 400 / 503。做成**值**之后由 adapter 决定 HTTP 状态，
+ * 和 approvals 的 `respond()` 返回 `{ accepted: false, reason }` 是同一个套路。
+ */
+type UserQuestionAnswerFailure =
+/** 内核里没有这个 callId 的悬空问题（`answer()` 返回了 false）。 */
+'not-pending' |
+/** 已经有一条回复在排队（内核 `REPLY_QUEUED`）。重复提交不是服务器故障。 */
+'reply-queued' |
+/** 答案批次没有「一问一答」地对齐（内核 `BAD_ANSWER`）。 */
+'answer-invalid' |
+/** 这个 agent 现在不接受人工回答（非 live root / 被别的 agent 拥有），或会话没有 live agent。 */
+'not-answerable' |
+/** 这套 DSH 构建里压根没有 `ctx.userQuestions` 服务。 */
+'unavailable';
+type UserQuestionAnswerOutcome = {
+  accepted: true;
+} | {
+  accepted: false;
+  reason: UserQuestionAnswerFailure;
+};
 interface ChatWorkspaceView {
   id: string;
   title: string;
@@ -538,12 +643,28 @@ declare class DshChatAdapter {
   /**
    * 取回会话历史里某个图片附件的字节。
    *
-   * 这里不做会话归属校验：附件 id 是内容哈希，拿到 id 就等于拿到内容，
-   * 而且调用方必须已经通过 `files.read` 鉴权并主动持有该 id（它只出现在其有权读取的
-   * 会话事件里）。多一层会话校验并不能提升安全性，却会让「在别的会话里引用同一张图」
-   * 这种正常情况莫名失败。
+   * **为什么会走内核的 `sessionController.attachment()`，而不自己调
+   * `ctx.attachments.readImage()`**：
+   * 1. 实测本机 profile 里 `ctx.attachments` 是 **MISSING**（拿不到注入属性）——
+   *    自己拼 ref 那条路根本走不通；
+   * 2. 内核那个方法内部一次做完三件事：校验该会话确实引用了这张图、
+   *    读出字节、用**会话事件里那条真实 ref** 做完整性校验
+   *    （`mediaType` / `bytes` / `width` / `height` 四项逐项比对）。
+   *    绕开它就得把这三件事全复刻 —— 先前正是漏了第三件，于是每张图
+   *    `ATTACHMENT_CORRUPT`：「字节读到了，却被校验拒之门外」。
+   *
+   * 因此 **sessionId 是必需参数**（内核要拿它读会话事件、找到那张图的真实 ref）；
+   * 早先设计的「客户端把四项元数据带上来」是多余的 —— 内核手里本来就有。
+   */
+  readAttachment(principal: Principal, sessionId: string, attachmentId: string): Promise<{
+    bytes: Uint8Array;
+    mediaType: string;
+  }>;
+  /**
+   * 取回一张**交接图片**（纯文本模型发图时落在工作区 `.dsh-images/` 的那份）。
+   * 与 [readAttachment] 同样要求会话归属；文件名在桥里还有一道白名单校验。
    */
-  readAttachment(principal: Principal, attachmentId: string): Promise<{
+  readHandoffImage(principal: Principal, sessionId: string, name: string): Promise<{
     bytes: Uint8Array;
     mediaType: string;
   }>;
@@ -556,6 +677,22 @@ declare class DshChatAdapter {
   archiveSession(principal: Principal, sessionId: string): Promise<string[]>;
   listPendingApprovals(principal: Principal, sessionId: string): Promise<PendingApprovalView[]>;
   decideApproval(principal: Principal, sessionId: string, approvalId: string, outcome: 'allowed-once' | 'rejected'): Promise<PendingApprovalView>;
+  /**
+   * 列出「agent 正在等、且还能回答」的用户问题。
+   *
+   * 口径与 [listPendingApprovals] 一致：先 requireSession（会话对本设备不可见 → 404），
+   * 再问内核；字段一个都不裁 —— 客户端照着渲染，内核加字段不用改插件。
+   */
+  listUserQuestions(principal: Principal, sessionId: string): Promise<UserQuestionView[]>;
+  /**
+   * 把一次答案提交给内核。
+   *
+   * 失败原因全部由 `api.userQuestions.answer` 以**值**给出（见 [UserQuestionAnswerOutcome]），
+   * 这里翻成 HTTP 语义：503 能力缺失 / 409 状态冲突 / 400 批次不合法。
+   * 为什么不在 bridge 里直接抛：`unwrapDsh` 只把 `not-found` / `busy` / `locked`
+   * 映成 404/409，其余一律 400 —— 表达不了这几种区别。
+   */
+  answerUserQuestion(principal: Principal, sessionId: string, callId: string, answer: UserQuestionAnswer): Promise<void>;
   models(principal: Principal, sessionId: string): Promise<SessionModelsView>;
   selectModel(principal: Principal, sessionId: string, selection: ModelSelectionView): Promise<ModelSelectionView>;
   listCommands(principal: Principal, sessionId: string): Promise<CommandDescriptorView[]>;
@@ -802,8 +939,21 @@ interface FileUploadsLike {
  * 否则历史里的图片一律显示不出来。
  */
 interface AttachmentStoreLike {
-  readImage(ref: {
+  readImage(
+  /**
+   * 附件引用。
+   *
+   * `attachmentId` 是唯一的**定位**字段（内核用 `ID_PATTERN.exec()` 取出 sha256
+   * 再拼 `objects/<前两位>/<sha>`）；而 `mediaType` / `bytes` / `width` / `height`
+   * 参与读后**完整性校验** —— 缺任何一项都会抛 `ATTACHMENT_CORRUPT`，
+   * 哪怕字节已经正确读出来了。
+   */
+  ref: {
     attachmentId: string;
+    mediaType?: string;
+    bytes?: number;
+    width?: number;
+    height?: number;
   }, signal?: AbortSignal): Promise<{
     ref: {
       mediaType: string;
@@ -878,6 +1028,33 @@ interface SessionControllerLike {
   }): Promise<{
     sessionId: string;
   }>;
+  /**
+   * 取一张**被这个会话引用过**的图片字节（内核主机端方法，名字就叫 `attachment`）。
+   *
+   * 这是取历史图片的**正路**，它内部一次做完三件事：校验会话确实引用了这张图、
+   * 调 `ctx.attachments.readImage`、用**会话事件里那条真实 ref**做完整性校验
+   *（`mediaType` / `bytes` / `width` / `height` 四项逐项比对）。
+   *
+   * 为什么必须走它、不能自己调 `ctx.attachments`：实测本机这条 profile 里
+   * `ctx.attachments` 是 **MISSING**（诊断日志
+   * `ctx.attachments MISSING（所以改走内核 sessionController.readAttachment）`），
+   * 自己拼 ref 那条路根本走不通；而且绕开内核就得把它内部三件事全复刻一遍，
+   * 早先正是只传了 id、缺四项元数据，导致 `ATTACHMENT_CORRUPT`。
+   *
+   * 注意方法名：**主机端叫 `attachment`**，客户端契约里才叫 `readAttachment`
+   *（`dsh-api-session-controller/lib/types/client/contract/session.d.ts`）。
+   * `data` 是 **base64 字符串**（主机端实现里 `Buffer.from(stored.data).toString("base64")`），
+   * 不是 Uint8Array —— 调用方要自己解码。
+   */
+  attachment(request: {
+    sessionId: string;
+    attachmentId: string;
+  }): Promise<{
+    attachment: {
+      mediaType: string;
+    };
+    data: string;
+  }>;
   selectModel(request: {
     sessionId: string;
     provider: string;
@@ -985,6 +1162,17 @@ interface LlmLike {
     error?: string;
   }[];
   discoverModels(settingsNs: string, request: unknown, signal?: AbortSignal): Promise<readonly unknown[]>;
+  /**
+   * 一个路由 + 模型 id 的**真实元数据**。
+   *
+   * 为什么必须用它、而不是自己猜模型能不能看图：内核拒绝「给纯文本模型发图片」时
+   * 用的就是**这个方法**（`SessionController` 的 prompt 准入里
+   * `this.ctx.llm.resolveModelInfo(...)` 再查 `inputModalities`）。入口要与内核
+   * 得出同一个结论，只能查同一份元数据 —— 名字、前缀、家族表都是启发式，会漂。
+   */
+  resolveModelInfo(provider: string, model: string, signal?: AbortSignal): Promise<{
+    inputModalities?: readonly string[];
+  } | undefined>;
 }
 /** Host services the bridge consumes; assembled by `src/index.ts` from `ctx`. */
 interface Dsh02HostServices {

package/lib/index.js

@@ -1,11 +1,11 @@
-import path from "node:path";
+import path, { join } from "node:path";
 import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { chmod, copyFile, lstat, mkdir, open, readFile, readdir, readlink, realpath, rename, rm, stat, symlink, unlink, writeFile } from "node:fs/promises";
-import { createReadStream, mkdirSync } from "node:fs";
+import { createReadStream, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { DatabaseSync } from "node:sqlite";
+import os, { homedir, hostname, networkInterfaces } from "node:os";
 import { pipeline } from "node:stream/promises";
 import { isIP } from "node:net";
-import os, { hostname, networkInterfaces } from "node:os";
 import { createServer } from "node:http";
 import { WebSocket, WebSocketServer } from "ws";
 //#region src/shared/contracts.ts
@@ -424,16 +424,45 @@ var DshChatAdapter = class {
 	/**
 	* 取回会话历史里某个图片附件的字节。
 	*
-	* 这里不做会话归属校验：附件 id 是内容哈希，拿到 id 就等于拿到内容，
-	* 而且调用方必须已经通过 `files.read` 鉴权并主动持有该 id（它只出现在其有权读取的
-	* 会话事件里）。多一层会话校验并不能提升安全性，却会让「在别的会话里引用同一张图」
-	* 这种正常情况莫名失败。
+	* **为什么会走内核的 `sessionController.attachment()`，而不自己调
+	* `ctx.attachments.readImage()`**：
+	* 1. 实测本机 profile 里 `ctx.attachments` 是 **MISSING**（拿不到注入属性）——
+	*    自己拼 ref 那条路根本走不通；
+	* 2. 内核那个方法内部一次做完三件事：校验该会话确实引用了这张图、
+	*    读出字节、用**会话事件里那条真实 ref** 做完整性校验
+	*    （`mediaType` / `bytes` / `width` / `height` 四项逐项比对）。
+	*    绕开它就得把这三件事全复刻 —— 先前正是漏了第三件，于是每张图
+	*    `ATTACHMENT_CORRUPT`：「字节读到了，却被校验拒之门外」。
+	*
+	* 因此 **sessionId 是必需参数**（内核要拿它读会话事件、找到那张图的真实 ref）；
+	* 早先设计的「客户端把四项元数据带上来」是多余的 —— 内核手里本来就有。
 	*/
-	async readAttachment(principal, attachmentId) {
+	async readAttachment(principal, sessionId, attachmentId) {
 		if (attachmentId.trim() === "") throw new ApiError(400, "BODY_INVALID", "attachmentId is required.");
+		if (sessionId.trim() === "") throw new ApiError(400, "BODY_INVALID", "sessionId is required.");
+		await this.requireSession(principal, sessionId);
 		return unwrapDsh(await this.api.sessions.readAttachment({
 			rpcId: randomUUID(),
-			payload: { attachmentId }
+			payload: {
+				sessionId,
+				attachmentId
+			}
+		}));
+	}
+	/**
+	* 取回一张**交接图片**（纯文本模型发图时落在工作区 `.dsh-images/` 的那份）。
+	* 与 [readAttachment] 同样要求会话归属；文件名在桥里还有一道白名单校验。
+	*/
+	async readHandoffImage(principal, sessionId, name) {
+		if (name.trim() === "") throw new ApiError(400, "BODY_INVALID", "name is required.");
+		if (sessionId.trim() === "") throw new ApiError(400, "BODY_INVALID", "sessionId is required.");
+		await this.requireSession(principal, sessionId);
+		return unwrapDsh(await this.api.sessions.readHandoffImage({
+			rpcId: randomUUID(),
+			payload: {
+				sessionId,
+				name
+			}
 		}));
 	}
 	async cancel(principal, sessionId) {
@@ -513,6 +542,46 @@ var DshChatAdapter = class {
 		this.pendingApprovals.delete(key);
 		return publicApproval(pending);
 	}
+	/**
+	* 列出「agent 正在等、且还能回答」的用户问题。
+	*
+	* 口径与 [listPendingApprovals] 一致：先 requireSession（会话对本设备不可见 → 404），
+	* 再问内核；字段一个都不裁 —— 客户端照着渲染，内核加字段不用改插件。
+	*/
+	async listUserQuestions(principal, sessionId) {
+		await this.requireSession(principal, sessionId);
+		return unwrapDsh(await this.api.userQuestions.list({
+			rpcId: randomUUID(),
+			payload: { sessionId }
+		})).items;
+	}
+	/**
+	* 把一次答案提交给内核。
+	*
+	* 失败原因全部由 `api.userQuestions.answer` 以**值**给出（见 [UserQuestionAnswerOutcome]），
+	* 这里翻成 HTTP 语义：503 能力缺失 / 409 状态冲突 / 400 批次不合法。
+	* 为什么不在 bridge 里直接抛：`unwrapDsh` 只把 `not-found` / `busy` / `locked`
+	* 映成 404/409，其余一律 400 —— 表达不了这几种区别。
+	*/
+	async answerUserQuestion(principal, sessionId, callId, answer) {
+		await this.requireSession(principal, sessionId);
+		const outcome = unwrapDsh(await this.api.userQuestions.answer({
+			rpcId: randomUUID(),
+			payload: {
+				sessionId,
+				callId,
+				answer
+			}
+		}));
+		if (outcome.accepted) return;
+		switch (outcome.reason) {
+			case "unavailable": throw new ApiError(503, "USER_QUESTIONS_UNAVAILABLE", "This DSH build provides no ctx.userQuestions service, so questions cannot be answered.");
+			case "not-pending": throw new ApiError(409, "QUESTION_NOT_PENDING", "This question is no longer pending.");
+			case "reply-queued": throw new ApiError(409, "QUESTION_REPLY_QUEUED", "A reply is already queued for this question.");
+			case "not-answerable": throw new ApiError(409, "QUESTION_NOT_ANSWERABLE", "This session cannot answer questions right now: its agent is not the live root.");
+			case "answer-invalid": throw new ApiError(400, "QUESTION_ANSWER_INVALID", "The answer batch must name each question of the call exactly once.");
+		}
+	}
 	async models(principal, sessionId) {
 		await this.requireSession(principal, sessionId);
 		return unwrapDsh(await this.api.sessions.models({
@@ -767,12 +836,30 @@ function normalizeDshEvent(frame, fallback, time = Date.now()) {
 				}
 			};
 		}
-		if (eventType === "turn/start" || eventType === "turn/end") return {
-			id: frame.rpcId,
-			type: eventType === "turn/start" ? "chat.turn.start" : "chat.turn.end",
-			time,
-			data: base
-		};
+		if (eventType === "turn/start" || eventType === "turn/end") {
+			if (eventType === "turn/end") {
+				const failure = turnFailureOf(event);
+				if (failure !== void 0) {
+					const data = {
+						...base,
+						failure
+					};
+					if (failure.stopped === true) data.stopped = true;
+					return {
+						id: `${frame.rpcId}:failed`,
+						type: "chat.turn.failed",
+						time,
+						data
+					};
+				}
+			}
+			return {
+				id: frame.rpcId,
+				type: eventType === "turn/start" ? "chat.turn.start" : "chat.turn.end",
+				time,
+				data: base
+			};
+		}
 		return {
 			id: frame.rpcId,
 			type: "chat.session.event",
@@ -808,6 +895,39 @@ function normalizeDshEvent(frame, fallback, time = Date.now()) {
 		data: payload
 	};
 }
+/**
+* `turn/end` 里的终局失败摘要，取不到就返回 undefined（这轮是正常结束的）。
+*
+* 内核 `turn-error.js` 的 match 判据只认两种：`reason.kind === 'error'`，
+* 以及 `aborted` 且取消原因是「退出 DeepSeek 登录」这个钩子。这里**同一判据**，
+* 不多不少 ——
+* - 不能少：漏掉任一形态，客户端就又回到「傻等」状态；
+* - 不能多：`max-tokens` 是「回答被截断，已有输出保留」，官方单独渲染成黄色警示，
+*   不是失败（客户端按普通 turn/end 收尾即可）；普通取消（用户点了停止）更不是。
+*
+* `code === 'AUTH'` 时内核把 message 抹成空串（`displayFailure`），客户端那边
+* 用本地化文案「API 密钥无效」顶上。这里保持原样转发，不替客户端猜。
+*/
+function turnFailureOf(event) {
+	const reason = isRecord$1(event.data) ? event.data.reason : void 0;
+	if (!isRecord$1(reason)) return void 0;
+	const kind = reason.kind;
+	if (kind === "error") {
+		const error = reason.error;
+		if (!isRecord$1(error)) return { message: String(error ?? "本轮运行失败") };
+		const code = typeof error.code === "string" ? error.code : void 0;
+		const message = typeof error.message === "string" ? error.message : JSON.stringify(error);
+		return code === void 0 ? { message } : {
+			message,
+			code
+		};
+	}
+	if (kind === "aborted" && isRecord$1(reason.reason) && reason.reason.kind === "hook" && reason.reason.reason === "deepseek-account/signed-out") return {
+		message: "Stopped because you signed out of DeepSeek.",
+		code: "ACCOUNT_SIGNED_OUT",
+		stopped: true
+	};
+}
 function isRecord$1(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -1187,6 +1307,72 @@ function optionalService(host, name) {
 		return null;
 	}
 }
+/**
+* 容错取 Agent 作用域上的 `userQuestions` 服务；拿不到就返回 `null`。
+*
+* 依据（全部实测，不是推断）：
+* - `agent.ctx` 是内核声明的字段：`@deepseek-ai/dsh-agent` 的
+*   `lib/types/runtime-types.d.ts`（`interface Agent { readonly ctx: Context }`）。
+* - `ctx.get(name)` 由 cordis 混入 `ctx`：`@deepseek-ai/cordis/lib/index.js` 里
+*   `this.mixin("reflect", ["get", "set", "provide", "accessor", "mixin"])`；
+*   同一文件的 `get(name, strict = true)` 在没人提供该服务时返回 `undefined`，**不抛**。
+* - 内核自己也这么取：`dsh-user-questions/lib/types/index.js` 里
+*   `this.ctx.get('agents')` / `this.ctx.get('sessionProjections')`。
+*
+* 即便如此仍做三层防御（ctx 形状 → get 是不是函数 → try/catch）：这是**可选能力**，
+* 没装它的 profile 只该少一个功能，不该让整个插件激活失败 —— attachments /
+* fileUploads 已经用两次线上事故教过这个道理。
+*/
+function userQuestionsOf(agent) {
+	if (agent === null || typeof agent !== "object") return null;
+	const ctx = agent.ctx;
+	if (ctx === null || ctx === void 0 || typeof ctx !== "object") return null;
+	const get = ctx.get;
+	if (typeof get !== "function") return null;
+	try {
+		const service = get.call(ctx, "userQuestions");
+		return service !== null && typeof service === "object" ? service : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* 内核的一行 `PendingUserQuestion` → 对外 view。
+*
+* 只钉三个契约字段（callId / state / questions），其余**原样透传**：内核以后往 item
+* 或 question 上加字段，手机端自己决定要不要用，插件不用跟着发版。
+* 缺 callId 或 questions 的行直接丢掉，而不是把残缺的行发给客户端。
+*/
+function toUserQuestionView(value) {
+	if (value === null || typeof value !== "object") return void 0;
+	const row = value;
+	const callId = row["callId"];
+	const questions = row["questions"];
+	if (typeof callId !== "string" || callId === "" || !Array.isArray(questions)) return void 0;
+	const state = row["state"];
+	return {
+		...row,
+		callId,
+		state: typeof state === "string" ? state : "continued",
+		questions: [...questions]
+	};
+}
+/**
+* 内核异常的 `code`，取不到就 `undefined`。
+*
+* 不看 `instanceof`（跨包副本 / 跨 realm 会失手），只认 `HarnessError` 上那个
+* 「稳定、可编程路由」的 `code`：`@deepseek-ai/dsh-llm` 的 `lib/types/error.js` 里
+* `HarnessError` 就是 `this.code = code`（`name` 也被设成子类名）。
+*/
+function errorCodeOf(error) {
+	if (error === null || typeof error !== "object") return void 0;
+	const code = error.code;
+	return typeof code === "string" ? code : void 0;
+}
+/** 会话没有 live agent —— `agentFor()` 抛的正是这个 code。 */
+function isAgentUnavailable(error) {
+	return errorCodeOf(error) === "session/agent-unavailable";
+}
 function ok(value) {
 	return { result: {
 		ok: true,
@@ -1443,6 +1629,175 @@ var ApprovalBridge = class {
 		return { accepted: true };
 	}
 };
+/**
+* 同一时刻最多挂起多少条前台提问：超了就把后来的直接委托给官方 UI。
+* 不做无上限的挂起表 —— 失控的 agent 能问出任意多问题，每条都吊着一个 Promise。
+*/
+const MAX_PENDING_QUESTIONS = 32;
+/**
+* `user-questions/request` 的接管者 —— 形状照 [ApprovalBridge]。
+*
+* 为什么非接不可：`ask_user_question` 只有在**参数 schema 声明了 `timeout`** 时才走
+* 「前台限时等待 → 超时转 `continued`」那条路（`dsh-user-questions/lib/types/projection.js`
+* 的 `isTimedAskUserQuestionSchema` 查 `tool.parameters.properties.timeout`），
+* 而实测 15 个真实调用的参数键清一色只有 `questions`。也就是说绝大多数提问**不进投影**，
+* `GET /questions` 永远查不到它们；它们只经过这条 Cordis waterfall 事件
+* （`types.d.ts:136-147`）。官方 WebUI 接了这个事件 → 电脑端看得到、手机端看不到。
+*
+* 三处与 approvals 不同，都是内核契约决定的、不是选择：
+* 1. **先委托，再竞速 —— 两端都能答**：进入时立刻调一次 `next()`（把这条请求交给
+*    后面的监听者，也就是官方 WebUI 那条远端 answerer），同时自己挂一张卡给 App，
+*    然后 `Promise.race`：谁先给出答案就算谁的。
+*    这与 ApprovalBridge 不同（它是「接管 = 否决下游」，cordis `lib/index.js:307-325`
+*    的文档原话：a listener that does not call next() vetoes the rest of the chain）——
+*    审批那边先不调，问题这边先调。代价是两端各有一张卡，后答的那张会变陈旧
+*    （客户端会收到 409「已不再等待」，语义正确）。
+* 2. **`this` 不能当 agent 用**：dispatcher 把它绑成 `scopeTarget(agent, agent)`
+*    （`lib/types/index.js:327`），而 `Scoped<T>` 明确写着
+*    「routing-only … does not expose the subject's properties」
+*    （`@deepseek-ai/dsh-scope/lib/types/index.d.ts:14-20`）。
+*    真 agent 只在 `request.agent` 里；官方 WebUI 也是另找 session
+*    （`ctx.sessions.scopeOf(this)`），而不是读 `this.session`。
+* 3. 回调必须是**普通函数**：cordis 用 `callback.bind(thisArg)` 绑定作用域载体
+*   （cordis `lib/index.js:263`）。本实现不依赖 `this`，但签名保持与内核契约一致。
+*/
+var QuestionBridge = class {
+	host;
+	mux;
+	pending = /* @__PURE__ */ new Map();
+	constructor(host, mux) {
+		this.host = host;
+		this.mux = mux;
+	}
+	/** Register the answerer once, during plugin activation. */
+	attach() {
+		const bridge = this;
+		this.host.on("user-questions/request", async function(...args) {
+			const request = args[0];
+			const next = args[args.length - 1];
+			const delegate = (async () => {
+				if (typeof next !== "function") throw new Error("user-questions/request was dispatched without a next() delegate");
+				return next();
+			})();
+			delegate.catch(() => {});
+			const sessionId = sessionIdOfAgent(request?.agent);
+			const questions = Array.isArray(request?.questions) ? [...request.questions] : void 0;
+			const callId = (typeof request?.wait?.callId === "string" && request.wait.callId !== "" ? request.wait.callId : void 0) ?? `bridge-${randomUUID()}`;
+			if (sessionId === void 0 || questions === void 0 || questions.length === 0) return delegate;
+			if (request?.signal?.aborted === true) return delegate;
+			if (bridge.pending.size >= MAX_PENDING_QUESTIONS) return delegate;
+			const rpcId = randomUUID();
+			const held = new Promise((resolve) => {
+				let done = false;
+				const settle = (value) => {
+					if (done) return;
+					done = true;
+					resolve(value);
+				};
+				bridge.pending.set(rpcId, {
+					sessionId,
+					callId,
+					questions,
+					settle
+				});
+				request?.signal?.addEventListener("abort", () => {
+					bridge.pending.delete(rpcId);
+					settle({ kind: "dismissed" });
+				}, { once: true });
+				bridge.mux.push({
+					type: "userQuestions/requested",
+					sessionId,
+					callId,
+					rpcId,
+					questions
+				});
+			});
+			const first = await Promise.race([delegate.then(() => ({ kind: "delegated" }), () => new Promise(() => {})), held]);
+			if (first.kind === "answered") {
+				bridge.pending.delete(rpcId);
+				bridge.mux.push({
+					type: "userQuestions/answered",
+					sessionId,
+					callId,
+					rpcId
+				});
+				return first.answer;
+			}
+			bridge.pending.delete(rpcId);
+			bridge.mux.push({
+				type: "userQuestions/dismissed",
+				sessionId,
+				callId,
+				rpcId
+			});
+			return await delegate;
+		});
+	}
+	/**
+	* 回答一条**正挂在前台等待**的提问（App 通过 `POST …/answer` 打进来）。
+	*
+	* 与 [ApprovalBridge.respond] 同形：按 (sessionId, callId) **精确**找挂起项；
+	* 找不到就报 `not-pending`，绝不挑一条最近的来答 —— 答错会话的代价太大。
+	*/
+	answer(request) {
+		if (!isUserQuestionAnswerLike(request.answer)) return {
+			accepted: false,
+			reason: "bad-response"
+		};
+		for (const [rpcId, entry] of this.pending) {
+			if (entry.sessionId !== request.sessionId || entry.callId !== request.callId) continue;
+			this.pending.delete(rpcId);
+			entry.settle({
+				kind: "answered",
+				answer: request.answer
+			});
+			return { accepted: true };
+		}
+		return {
+			accepted: false,
+			reason: "not-pending"
+		};
+	}
+	/**
+	* 某会话当前挂起中的提问（供 `GET /questions` 合并）。
+	*
+	* `state` 刻意报 `'continued'`：客户端（dsh-companion 的 HarnessViewModel:1314）
+	* 只认这一个值（`sets.filter { it.state == QUESTION_STATE_CONTINUED }`），
+	* 报 `'open'` 等于这张卡片永远不显示 —— 而它恰恰是**此刻真正阻塞着 agent** 的那条。
+	* 「这是插件接管的」由新增的 `viaBridge` 标记表达（客户端 decode 是
+	* `ignoreUnknownKeys = true`，加字段安全），将来客户端想换文案/单独过滤都有依据。
+	*/
+	pendingFor(sessionId) {
+		const out = [];
+		for (const entry of this.pending.values()) {
+			if (entry.sessionId !== sessionId) continue;
+			out.push({
+				callId: entry.callId,
+				state: "continued",
+				questions: [...entry.questions],
+				viaBridge: true
+			});
+		}
+		return out;
+	}
+};
+/**
+* 答案批次的最小校验（路由层已校验过一遍，这里是防御性第二道）。
+*
+* 只查「能不能安全喂给内核」：对象、`answers` 非空数组、每项 `id` 是非空字符串、
+* `selected` 是字符串数组。更细的「一问一答对齐」由内核自己判（BAD_ANSWER）。
+*/
+function isUserQuestionAnswerLike(value) {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+	const answers = value.answers;
+	if (!Array.isArray(answers) || answers.length === 0) return false;
+	return answers.every((item) => {
+		if (item === null || typeof item !== "object" || Array.isArray(item)) return false;
+		const entry = item;
+		if (typeof entry.id !== "string" || entry.id === "") return false;
+		return Array.isArray(entry.selected) && entry.selected.every((label) => typeof label === "string");
+	});
+}
 /** Best-effort projection of an Agent identity to its session id. */
 function sessionIdOfAgent(agent) {
 	if (!agent || typeof agent !== "object") return void 0;
@@ -1457,6 +1812,183 @@ function sessionIdOf(summary) {
 	return typeof id === "string" ? id : void 0;
 }
 /**
+* 内核在 prompt 准入里会因为「模型看不到图」拒收整条消息
+* （`MODEL_DOES_NOT_SUPPORT_IMAGES`）。手机端拿不到桌面 WebUI 那套
+* 「粘贴即落成临时文件、路径进输入框」的浏览器半边，所以图片在手机上
+* **直接发不出去** —— 而用户明明装了识图插件。
+*
+* 这里补上手机端缺的那一步，但**刻意不引用任何插件的 API**：
+* 判定用内核自己的 `llm.resolveModelInfo()`（与内核拒收时查的是同一份元数据），
+* 动作只是「图片落成文件 + 消息里给路径」—— 任何「按路径读图」的工具都能接手。
+* 哪天换插件、甚至不用插件，这段代码都不需要改。
+*
+* 三条保守原则（宁可退回原样、也不要自作聪明）：
+* 1. 元数据拿不到 / 解析不出模型 → **不动**（内核这时也不会拒，交给它）；
+* 2. 模型声明了 image → **不动**（原生图片能显示缩略图，别抢它的活）；
+* 3. 落盘失败 → **不动**（退回内核自己的报错，至少用户能看懂发生了什么）。
+*
+* 两个落点（按优先级）：
+* - **会话工作目录下的 `.dsh-images/`**（首选）：文件在用户的项目里，
+*   人和 agent 都找得到，也符合「产物放工作目录、别塞进 DSH 私有目录」；
+* - 解析不出工作目录时退回 DSH 目录（[DEFAULT_IMAGE_HANDOFF_DIR]）——
+*   宁可落到私有目录也不能让「发消息」本身失败。
+*/
+const HANDOFF_SUBDIR = ".dsh-images";
+const DEFAULT_IMAGE_HANDOFF_DIR = join(homedir(), ".dsh", "image-handoff");
+const IMAGE_EXTENSIONS = {
+	"image/png": "png",
+	"image/jpeg": "jpg",
+	"image/webp": "webp",
+	"image/gif": "gif",
+	"image/heic": "heic",
+	"image/heif": "heif",
+	"image/bmp": "bmp",
+	"image/avif": "avif"
+};
+/** 扩展名优先按声明的 mediaType，认不出再从魔数嗅，最后 .bin。 */
+function handoffExtension(mediaType, bytes) {
+	const declared = IMAGE_EXTENSIONS[mediaType.trim().toLowerCase()];
+	if (declared !== void 0) return declared;
+	if (bytes.length >= 8 && bytes[0] === 137 && bytes[1] === 80) return "png";
+	if (bytes.length >= 3 && bytes[0] === 255 && bytes[1] === 216) return "jpg";
+	if (bytes.length >= 12 && bytes.toString("ascii", 0, 4) === "RIFF" && bytes.toString("ascii", 8, 12) === "WEBP") return "webp";
+	if (bytes.length >= 6 && bytes.toString("ascii", 0, 3) === "GIF") return "gif";
+	return "bin";
+}
+/**
+* 把一张内联图片写成文件，返回 `{ absolute, relative }`。
+*
+* 文件名用**内容哈希**：同一张图重复发不会堆副本（与内核附件存储同一思路），
+* 也让「同一路径 → 同一内容」对下游工具成立（可安全缓存）。
+* `relative` 是相对会话工作目录的短路径，给人看；`absolute` 给读图工具用。
+* 目录 0700、文件 0600：这些字节可能包含用户隐私。
+*/
+function writeHandoffFile(dir, workspace, mediaType, data) {
+	const bytes = Buffer.from(data, "base64");
+	if (bytes.length === 0) throw new Error("EMPTY_IMAGE");
+	mkdirSync(dir, {
+		recursive: true,
+		mode: 448
+	});
+	const fileName = `${createHash("sha256").update(bytes).digest("hex")}.${handoffExtension(mediaType, bytes)}`;
+	const absolute = join(dir, fileName);
+	if (!existsSync(absolute)) writeFileSync(absolute, bytes, { mode: 384 });
+	return {
+		absolute,
+		relative: workspace !== void 0 && absolute.startsWith(workspace + "/") ? absolute.slice(workspace.length + 1) : fileName
+	};
+}
+/** 交接文件名只允许「内容哈希 + 图片扩展名」：挡住一切路径穿越。 */
+const HANDOFF_NAME = /^[0-9a-f]{64}\.(png|jpe?g|webp|gif|heic|heif|bmp|avif)$/i;
+const HANDOFF_MEDIA_TYPES = {
+	png: "image/png",
+	jpg: "image/jpeg",
+	jpeg: "image/jpeg",
+	webp: "image/webp",
+	gif: "image/gif",
+	heic: "image/heic",
+	heif: "image/heif",
+	bmp: "image/bmp",
+	avif: "image/avif"
+};
+/**
+* 读出一张交接图片的字节（供手机端把它**显示**出来）。
+*
+* 只接受裸文件名，目录永远由「会话工作目录 + `.dsh-images`」（或兜底目录）推出，
+* 客户端给绝对路径也不认 —— 否则这条读文件的口子会变成任意文件读取。
+* 工作目录与 [writeHandoffFile] 用的是同一套解析，保证「写在哪、从哪读」。
+*/
+async function readHandoffImageFile(host, roots, fallbackDir, sessionId, name) {
+	const fileName = name.split(/[/\\]/).pop() ?? name;
+	const match = HANDOFF_NAME.exec(fileName);
+	if (match === null) throw new Error("BAD_HANDOFF_NAME");
+	const ext = (match[1] ?? "").toLowerCase();
+	const mediaType = HANDOFF_MEDIA_TYPES[ext] ?? "application/octet-stream";
+	const workspace = await sessionWorkspaceDir(host, roots, sessionId);
+	const target = [...workspace !== void 0 ? [join(workspace, HANDOFF_SUBDIR, fileName)] : [], join(fallbackDir, fileName)].find((candidate) => existsSync(candidate));
+	if (target === void 0) throw new Error("HANDOFF_IMAGE_NOT_FOUND");
+	return {
+		bytes: new Uint8Array(readFileSync(target)),
+		mediaType
+	};
+}
+/**
+* 解析会话当前的工作目录（绝对路径），冷会话也能用。
+*
+* 不走 live agent（冷会话没有 agent）：直接用 `sessionController.list()`
+* 里那条会话的 `cwd`（相对授权根的 wire 路径），再与数据库里的根拼出真实路径。
+* 解析不出来（没有授权根 / cwd 不在任何根下）就返回 undefined —— 交给上层兜底。
+*/
+async function sessionWorkspaceDir(host, roots, sessionId) {
+	if (roots.length === 0) return void 0;
+	const item = (await host.sessionController.list({}, new AbortController().signal)).items?.find((entry) => entry.sessionId === sessionId);
+	const cwd = typeof item?.cwd === "string" ? item.cwd : void 0;
+	if (cwd === void 0) return void 0;
+	for (const root of roots) {
+		const relative = wireRelative(root.realPath, cwd);
+		if (relative !== void 0) return join(root.realPath, relative);
+	}
+}
+/** 会话当前生效的模型（pending > lastUsed > 目录默认），取不到返回 undefined。 */
+async function currentModelSelection(host, sessionId) {
+	const selection = (await host.sessionController.projections({ sessionId }, new AbortController().signal))?.values?.["modelSelection"];
+	const catalog = await host.sessionController.modelCatalog();
+	const current = selection?.next ?? selection?.lastUsed ?? catalog.default;
+	const provider = current?.provider;
+	const model = current?.model;
+	if (typeof provider !== "string" || typeof model !== "string") return void 0;
+	return {
+		provider,
+		model
+	};
+}
+/**
+* 内核会不会因为「这个模型看不到图」拒收？判据与内核**逐字一致**：
+* `inputModalities` 已声明且不含 `image`。
+*
+* 元数据缺失（`undefined`）**不算**「确认看不到图」—— 内核在那种情况下也不拒，
+* 我们跟着不插手（拿不准就走原路）。
+*/
+async function modelIsConfirmedTextOnly(host, sessionId) {
+	const selection = await currentModelSelection(host, sessionId);
+	if (selection === void 0) return false;
+	const modalities = (await host.llm.resolveModelInfo(selection.provider, selection.model))?.inputModalities;
+	if (!Array.isArray(modalities)) return false;
+	return !modalities.includes("image");
+}
+/**
+* 需要交接时，把每个 `image` 部件换成**两行文本**；否则原样返回。
+*
+* 同一行路径要同时伺候两类读者：
+* - **给人看**（第一行）：图片序号、原始文件名、工作目录里的短路径；
+* - **给机器看**（第二行 `[Image: source: <绝对路径>]`）：这是读图技能明确
+*   识别的占位形状之一（带图片扩展名的绝对路径同样触发），任何按路径读图的
+*   工具都能接手，不出现任何具体插件名。
+*
+* 任何一步抛错都退回原内容：这个功能的失败**不该**把「发消息」本身弄坏。
+*/
+async function handoffImagesForTextOnlyModel(host, roots, fallbackDir, sessionId, content) {
+	if (!content.some((part) => part.type === "image")) return content;
+	try {
+		if (!await modelIsConfirmedTextOnly(host, sessionId)) return content;
+		const workspace = await sessionWorkspaceDir(host, roots, sessionId);
+		const dir = workspace !== void 0 ? join(workspace, HANDOFF_SUBDIR) : fallbackDir;
+		let index = 0;
+		return content.map((part) => {
+			if (part.type !== "image") return part;
+			index += 1;
+			const { absolute, relative } = writeHandoffFile(dir, workspace, part.mediaType, part.data);
+			const name = typeof part.name === "string" && part.name.trim() !== "" ? part.name.trim() : `图片 ${index}`;
+			return {
+				type: "text",
+				text: [`🖼️ 图片 ${index}「${name}」（当前模型不支持图片输入，已保存到工作目录 ${relative}；请先用读图工具打开下面那行的绝对路径，看清内容再回答）`, `[Image: source: ${absolute}]`].join("\n")
+			};
+		});
+	} catch {
+		return content;
+	}
+}
+/**
 * Build the `apiProxy` replacement out of 0.2.x host services.
 *
 * Every method keeps the old `{ rpcId, payload }` request shape and the old
@@ -1464,15 +1996,20 @@ function sessionIdOf(summary) {
 * `chat-adapter.ts` and `settings-adapter.ts` are written against.
 *
 * @param host - host services resolved from the plugin context.
+* @param host - host services resolved from the plugin context.
 * @returns a `SettingsApiProxy` (i.e. `DshApiProxy` plus the settings surfaces).
 */
-function createDsh02ApiProxy(host) {
+function createDsh02ApiProxy(host, options = {}) {
 	const mux = new FrameHub();
 	const hostFrames = new FrameHub();
-	const attachmentStore = optionalService(host, "attachments");
+	const imageHandoff = options.imageHandoff !== false;
+	const handoffRoots = options.handoffRoots ?? [];
+	const imageHandoffDir = options.imageHandoffDir ?? DEFAULT_IMAGE_HANDOFF_DIR;
 	const fileUploadService = optionalService(host, "fileUploads");
 	const approvals = new ApprovalBridge(host, mux);
 	approvals.attach();
+	const questions = new QuestionBridge(host, mux);
+	questions.attach();
 	const relay = new SessionEventRelay(host, mux);
 	host.on("api-session/added", (summary) => {
 		const sessionId = sessionIdOf(summary);
@@ -1517,6 +2054,21 @@ function createDsh02ApiProxy(host) {
 		if (agent === void 0 || agent === null) throw Object.assign(/* @__PURE__ */ new Error(`no live Agent for session ${sessionId}`), { code: "session/agent-unavailable" });
 		return agent;
 	}
+	/**
+	* `agentFor` 的宽松版：把「这个会话没有 live agent」当成**正常情况**（返回 null）。
+	*
+	* 为什么 list 需要它：手机端会对每个会话各拉一次问题列表，而冷会话（没在跑）没有
+	* agent 是常态。把常态报成错误，客户端只会看到一片红。
+	* 只放过 `session/agent-unavailable` 这一个 code，其它异常照旧往上抛。
+	*/
+	async function agentForQuestions(sessionId) {
+		try {
+			return await agentFor(sessionId);
+		} catch (error) {
+			if (isAgentUnavailable(error)) return null;
+			throw error;
+		}
+	}
 	return {
 		respond: (message) => approvals.respond(message),
 		sessions: {
@@ -1555,13 +2107,15 @@ function createDsh02ApiProxy(host) {
 			prompt: (request) => call(async () => {
 				const requestId = randomUUID();
 				const receiptIds = request.payload.content.filter((part) => part.type === "file").map((part) => part.receiptId);
+				const content = imageHandoff ? await handoffImagesForTextOnlyModel(host, handoffRoots, imageHandoffDir, request.payload.sessionId, request.payload.content) : request.payload.content;
 				const binding = receiptIds.length === 0 ? void 0 : await (async () => {
 					if (fileUploadService == null) throw new Error("FILE_UPLOADS_UNAVAILABLE: this DSH build provides no ctx.fileUploads service, so file attachments cannot be sent");
 					return fileUploadService.bindPrompt(await agentFor(request.payload.sessionId), receiptIds, requestId);
 				})();
 				await host.sessionController.prompt({
 					requestId,
-					...request.payload
+					...request.payload,
+					content
 				}, new AbortController().signal);
 				binding?.commit();
 				return { accepted: true };
@@ -1578,13 +2132,20 @@ function createDsh02ApiProxy(host) {
 				};
 			}),
 			readAttachment: (request) => call(async () => {
-				if (attachmentStore == null) throw new Error("ATTACHMENT_STORE_UNAVAILABLE: this DSH build provides no ctx.attachments service, so stored image bytes cannot be read");
-				const stored = await attachmentStore.readImage({ attachmentId: request.payload.attachmentId }, new AbortController().signal);
+				const { sessionId, attachmentId } = request.payload;
+				const value = await host.sessionController.attachment({
+					sessionId,
+					attachmentId
+				});
 				return {
-					bytes: stored.data,
-					mediaType: stored.ref.mediaType
+					bytes: new Uint8Array(Buffer.from(value.data, "base64")),
+					mediaType: value.attachment.mediaType
 				};
 			}),
+			readHandoffImage: (request) => call(async () => {
+				const { sessionId, name } = request.payload;
+				return readHandoffImageFile(host, handoffRoots, imageHandoffDir, sessionId, name);
+			}),
 			cancel: (request) => call(() => host.sessionController.cancel(request.payload)),
 			rename: (request) => call(() => host.sessionController.rename(request.payload)),
 			fork: (request) => call(() => host.sessionController.fork(request.payload)),
@@ -1596,7 +2157,7 @@ function createDsh02ApiProxy(host) {
 				const catalog = await host.sessionController.modelCatalog();
 				const selection = (await host.sessionController.projections({ sessionId }, new AbortController().signal))?.values?.["modelSelection"];
 				return {
-					current: selection?.pending ?? selection?.lastUsed ?? catalog.default,
+					current: selection?.next ?? selection?.lastUsed ?? catalog.default,
 					routable: Array.isArray(catalog.routableProviders) && catalog.routableProviders.length > 0,
 					groups: Array.isArray(catalog.groups) ? catalog.groups : [],
 					failures: Array.isArray(catalog.failures) ? catalog.failures.map((entry) => ({
@@ -1655,6 +2216,65 @@ function createDsh02ApiProxy(host) {
 				return { agentPreset: await host.agentPresets.select(agent, request.payload.agentPreset) };
 			})
 		},
+		userQuestions: {
+			list: (request) => call(async () => {
+				const { sessionId } = request.payload;
+				const bridged = questions.pendingFor(sessionId);
+				const bridgedIds = new Set(bridged.map((item) => item.callId));
+				const agent = await agentForQuestions(sessionId);
+				if (agent === null) return { items: bridged };
+				const service = userQuestionsOf(agent);
+				if (service === null || typeof service.continued !== "function") return { items: bridged };
+				const rows = service.continued(agent);
+				const continued = Array.isArray(rows) ? rows.map(toUserQuestionView).filter((item) => item !== void 0) : [];
+				return { items: [...bridged, ...continued.filter((item) => !bridgedIds.has(item.callId))] };
+			}),
+			answer: (request) => call(async () => {
+				const { sessionId, callId, answer } = request.payload;
+				const agent = await agentForQuestions(sessionId);
+				let kernelCouldNotAnswer = false;
+				if (agent !== null) {
+					const service = userQuestionsOf(agent);
+					if (service !== null && typeof service.answer === "function") {
+						let answered;
+						try {
+							answered = await service.answer(agent, callId, answer);
+						} catch (error) {
+							const code = errorCodeOf(error);
+							if (code === "REPLY_QUEUED") return {
+								accepted: false,
+								reason: "reply-queued"
+							};
+							if (code === "BAD_ANSWER") return {
+								accepted: false,
+								reason: "answer-invalid"
+							};
+							if (code === "CALLER_NOT_LIVE" || code === "DELEGATED_CALLER") kernelCouldNotAnswer = true;
+							else throw error;
+						}
+						if (answered === true) return { accepted: true };
+					}
+				}
+				const bridged = questions.answer({
+					sessionId,
+					callId,
+					answer
+				});
+				if (bridged.accepted) return { accepted: true };
+				if (bridged.reason === "bad-response") return {
+					accepted: false,
+					reason: "answer-invalid"
+				};
+				if (kernelCouldNotAnswer) return {
+					accepted: false,
+					reason: "not-answerable"
+				};
+				return {
+					accepted: false,
+					reason: "not-pending"
+				};
+			})
+		},
 		settings: {
 			describe: () => call(() => host.settingsController.describe()),
 			mutate: (request) => call(() => host.settingsController.mutate(request.payload.ns, request.payload.ops, request.payload.expectedRevision))
@@ -2750,7 +3370,9 @@ var ApiRouter = class {
 		if (attachmentRoute !== null && method === "GET") {
 			this.options.auth.requireScope(principal, "files.read");
 			const attachmentId = decodeURIComponent(attachmentRoute[1]);
-			const { bytes, mediaType } = await this.options.chat.readAttachment(principal, attachmentId);
+			const sessionId = url.searchParams.get("sessionId")?.trim();
+			if (!sessionId) throw new ApiError(400, "BODY_INVALID", "sessionId query parameter is required.");
+			const { bytes, mediaType } = await this.options.chat.readAttachment(principal, sessionId, attachmentId);
 			res.statusCode = 200;
 			res.setHeader("Content-Type", mediaType);
 			res.setHeader("Content-Length", String(bytes.byteLength));
@@ -2758,6 +3380,19 @@ var ApiRouter = class {
 			res.end(Buffer.from(bytes));
 			return;
 		}
+		if (pathname === "/api/v1/image-handoff" && method === "GET") {
+			this.options.auth.requireScope(principal, "files.read");
+			const name = url.searchParams.get("name")?.trim();
+			const sessionId = url.searchParams.get("sessionId")?.trim();
+			if (!name || !sessionId) throw new ApiError(400, "BODY_INVALID", "name and sessionId query parameters are required.");
+			const { bytes, mediaType } = await this.options.chat.readHandoffImage(principal, sessionId, name);
+			res.statusCode = 200;
+			res.setHeader("Content-Type", mediaType);
+			res.setHeader("Content-Length", String(bytes.byteLength));
+			res.setHeader("Cache-Control", "private, max-age=3600");
+			res.end(Buffer.from(bytes));
+			return;
+		}
 		const attachmentsRoute = pathname.match(/^\/api\/v1\/chat\/sessions\/([^/]+)\/attachments$/);
 		if (attachmentsRoute !== null && method === "POST") {
 			this.options.auth.requireScope(principal, "chat.write");
@@ -2813,6 +3448,29 @@ var ApiRouter = class {
 			sendJson(res, 202, { accepted: true });
 			return;
 		}
+		const questionsRoute = pathname.match(/^\/api\/v1\/chat\/sessions\/([^/]+)\/questions$/);
+		if (method === "GET" && questionsRoute !== null) {
+			this.options.auth.requireScope(principal, "chat.read");
+			const sessionId = decodeURIComponent(questionsRoute[1]);
+			sendJson(res, 200, { items: await this.options.chat.listUserQuestions(principal, sessionId) });
+			return;
+		}
+		const questionAnswerRoute = pathname.match(/^\/api\/v1\/chat\/sessions\/([^/]+)\/questions\/([^/]+)\/answer$/);
+		if (method === "POST" && questionAnswerRoute !== null) {
+			this.options.auth.requireScope(principal, "chat.write");
+			const sessionId = decodeURIComponent(questionAnswerRoute[1]);
+			const callId = decodeURIComponent(questionAnswerRoute[2]);
+			const answer = readUserQuestionAnswer(await readJson(req, 64e3));
+			await this.options.chat.answerUserQuestion(principal, sessionId, callId, answer);
+			this.audit(principal, "chat.question.answer", void 0, void 0, requestId, {
+				sessionId,
+				callId,
+				answers: answer.answers.length,
+				questionIds: answer.answers.map((item) => item.id)
+			});
+			sendJson(res, 202, { accepted: true });
+			return;
+		}
 		const sessionModelsRoute = pathname.match(/^\/api\/v1\/chat\/sessions\/([^/]+)\/model(?:s)?$/);
 		if (sessionModelsRoute !== null) {
 			const sessionId = decodeURIComponent(sessionModelsRoute[1]);
@@ -3168,6 +3826,33 @@ function readPromptParts(body) {
 		throw new ApiError(400, "BODY_INVALID", `content[${index}].type is not supported.`);
 	});
 }
+/**
+* 校验一次答案提交：`{ answers: [{ id, selected[], custom? }] }`。
+*
+* 为什么要逐项校验，而不是把 body 直接透传给内核：这是**用户输入**，
+* 形状不对时内核给的报错更难懂；而且内核的 `answer()` 会检查「一问一答」的对齐，
+* 类型层面能先挡掉的就不要等到那一步。
+*
+* 入参故意收 `unknown`：`readJson` 的返回值可能是 null / 数字 / 数组，
+* 当对象取字段会抛 TypeError 变成 500 —— 非法输入必须是 400。
+*/
+function readUserQuestionAnswer(body) {
+	if (body === null || typeof body !== "object" || Array.isArray(body)) throw new ApiError(400, "BODY_INVALID", "The request body must be a JSON object with an answers array.");
+	const answers = body.answers;
+	if (!Array.isArray(answers) || answers.length === 0) throw new ApiError(400, "BODY_INVALID", "answers must be a non-empty array.");
+	return { answers: answers.map((raw, index) => {
+		if (raw === null || typeof raw !== "object" || Array.isArray(raw)) throw new ApiError(400, "BODY_INVALID", `answers[${index}] must be an object.`);
+		const item = raw;
+		if (typeof item.id !== "string" || item.id === "") throw new ApiError(400, "BODY_INVALID", `answers[${index}].id is required.`);
+		if (!Array.isArray(item.selected) || item.selected.some((value) => typeof value !== "string")) throw new ApiError(400, "BODY_INVALID", `answers[${index}].selected must be an array of strings.`);
+		if (item.custom !== void 0 && typeof item.custom !== "string") throw new ApiError(400, "BODY_INVALID", `answers[${index}].custom must be a string.`);
+		return {
+			id: item.id,
+			selected: [...item.selected],
+			...item.custom === void 0 ? {} : { custom: item.custom }
+		};
+	}) };
+}
 function validateStringArray(value, name) {
 	if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) throw new ApiError(400, "BODY_INVALID", `${name} must be an array of strings.`);
 	return [...new Set(value)];
@@ -3964,7 +4649,13 @@ async function apply(ctx, config = {}) {
 	const events = new WorkspaceEventBus();
 	const auth = new AuthService(database);
 	const files = new FileService(database, (event) => events.emit(event));
-	const apiProxy = createDsh02ApiProxy(ctx);
+	const apiProxy = createDsh02ApiProxy(ctx, {
+		handoffRoots: database.listRoots().map((root) => ({
+			id: root.id,
+			realPath: root.realPath
+		})),
+		imageHandoffDir: path.join(dataDir, "image-handoff")
+	});
 	const chat = new DshChatAdapter(apiProxy, database, {
 		agents: ctx.agents,
 		commands: ctx.commands

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-remote-bridge",
-  "version": "2.2.1",
+  "version": "2.2.3",
   "description": "Versioned REST bridge for DeepSeek Harness: remote access for trusted clients (chat, files, devices) plus a Phone-settings panel inside the DSH WebUI.",
   "type": "module",
   "packageManager": "pnpm@11.19.0",