dsh-mobile-plugin 0.0.0-stage → 0.1.57

package/lib/mobile/stream.js

@@ -0,0 +1,268 @@
+'use strict';
+
+/**
+ * dsh-mobile 流式：SSE 转发目标会话的增量事件。
+ *
+ * 订阅宿主事件流，仅转发目标会话的 session/event 帧（增量事件），
+ * 每 15s 发一行注释保持连接；客户端断开即取消订阅。
+ *
+ * 断线恢复：SSE 客户端重连时携带 `Last-Event-ID: <sessionId>:<seq>`（或查询参数
+ * `lastSeq=<seq>`）。服务端先在 history 中回放 `seq > lastSeq` 的事件（收敛状态），
+ * 再无缝接入实时流，并用 seq 去重避免回放/实时交界处重复交付。由于宿主 history
+ * 只支持窗口回放，若断线窗口超过回放上限，客户端仍应在其 SSRD 重连补偿刷新
+ * 权威快照（/session/messages、/workspaces）兜底。
+ *
+ * 生命周期：所有失败路径都必须经 logStream 留痕（守卫 test/stream-liveness.test.cjs
+ * 逐条钉着字面量），收尾一定给客户端一帧 `session/resync-required`；keepAlive 定时器
+ * 要 unref —— 它只是保活，不该把进程退出按在 15s 一拍上。
+ */
+
+const crypto = require('crypto');
+
+const { sendJson } = require('../shared/http-util');
+const { resolveEventAttachments } = require('./sessions.js');
+const { callSessions } = require('./rpc.js');
+const { unwrap } = require('./envelope.js');
+const { normalizeJobs } = require('./jobs.js');
+
+const SSE_RETRY_MS = 3000;
+// Android React Native's XHR may buffer tiny chunked responses until its
+// internal progress threshold. Pad each SSE record so onprogress exposes it
+// promptly; the padding is an SSE comment and is ignored by clients.
+const SSE_FLUSH_PADDING_BYTES = 2048;
+const REPLAY_WINDOW = 3000; // 断线补偿回放的最大事件数
+
+/**
+ * 可回答的审批请求帧类型。宿主 apiProxy 的 `requestedFrame()` 发的是 mux 帧
+ * `approval/requested`（`rpcId` 在帧级、`approvalId` 在 payload）；会话事件
+ * `approval/asked` 只是同一件事的持久化形态，且**不带** rpcId。
+ *
+ * 两种形态都必须把帧级 rpcId 透给客户端：`/approval/respond` 的 rpcId 是宿主
+ * `pendingApprovals` 表的键，用 approvalId 冒充它会被判 `not-pending` 并回 409
+ * 「该审批已完成或不可回答」。旧实现只给 `approval/asked` 合入 rpcId，而宿主
+ * 实际发的是 `approval/requested` —— 于是 App 拿到的审批帧永远没有 rpcId。
+ */
+const ANSWERABLE_APPROVAL_TYPES = new Set(['approval/requested', 'approval/asked']);
+
+/**
+ * 诊断日志。这条流过去把三处失败都静默吞掉（keepalive 写失败、mux 循环抛错、
+ * res.end 失败），于是「preamble 之后既不产出也不终止」这种状态在宿主侧没有任何
+ * 痕迹，只能靠 relay/nginx 侧反推。任何一条异常路径都必须留下可 grep 的行。
+ */
+function logStream(sessionId, message, error) {
+  const detail = error instanceof Error ? (error.stack || error.message) : (error == null ? '' : String(error));
+  try {
+    process.stderr.write(`[dsh-mobile-plugin] session/stream ${sessionId} ${message}${detail ? `: ${detail}` : ''}\n`);
+  } catch { /* ignore */ }
+}
+
+function stableEventId(payload, frame) {
+  const source = payload && payload.type === 'session/event' ? payload : frame?.payload;
+  if (source && typeof source === 'object') {
+    if (source.type === 'session/event' && source.sessionId && source.event && Number.isFinite(source.event.seq)) {
+      return `${source.sessionId}:${source.event.seq}`;
+    }
+  }
+  if (payload && typeof payload === 'object') {
+    for (const key of ['eventId', 'rpcId', 'id', 'approvalId']) {
+      if (typeof payload[key] === 'string' && payload[key]) return payload[key];
+    }
+    const sessionId = typeof payload.sessionId === 'string' ? payload.sessionId : 'session';
+    const digest = crypto.createHash('sha256').update(JSON.stringify(payload)).digest('hex').slice(0, 24);
+    return `${sessionId}:${payload.type || 'event'}:${digest}`;
+  }
+  return frame && typeof frame.rpcId === 'string' && frame.rpcId ? frame.rpcId : undefined;
+}
+
+function writeSse(res, payload, frame) {
+  const id = stableEventId(payload, frame);
+  const fields = [`retry: ${SSE_RETRY_MS}`];
+  if (id) fields.push(`id: ${id}`);
+  fields.push(`data: ${JSON.stringify(payload)}`);
+  fields.push(`: ${' '.repeat(SSE_FLUSH_PADDING_BYTES)}`, '', '');
+  try { res.write(`${fields.join('\n')}\n`); return true; } catch { return false; }
+}
+
+/**
+ * 解析断线续传位置：
+ *  - `Last-Event-ID: <sessionId>:<seq>`（标准 SSE 头）；
+ *  - 或查询参数 `lastSeq=<seq>`。
+ * 返回安全非负整数 seq，缺失/非法返回 null。
+ */
+function parseResumeSeq(req, sessionId) {
+  const header = req?.headers?.['last-event-id'];
+  if (typeof header === 'string' && header) {
+    // 只认 `<sessionId>:<seq>` 形式，防止别的 `id:` 误判。
+    const m = /^(?:[^:]*):([0-9]+)$/.exec(header.trim());
+    if (m) {
+      const seq = Number(m[1]);
+      if (Number.isSafeInteger(seq) && seq >= 0) return seq;
+    }
+  }
+  const lastSeq = new URL(req.url, 'http://x').searchParams.get('lastSeq');
+  if (lastSeq !== null && lastSeq !== '') {
+    const seq = Number(lastSeq);
+    if (Number.isSafeInteger(seq) && seq >= 0) return seq;
+  }
+  return null;
+}
+
+/**
+ * GET /api/mobile/v1/session/stream?sessionId=…&lastSeq=…（token）
+ * SSE：订阅宿主事件流，仅转发目标会话的 session/event 帧（增量事件），
+ * 每 15s 发一行注释保持连接；客户端断开即取消订阅。
+ */
+async function handleStream(ctx, req, res) {
+  const url = new URL(req.url, 'http://x');
+  const sessionId = url.searchParams.get('sessionId');
+  if (!sessionId) return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: '缺少 sessionId' } });
+  try {
+    res.writeHead(200, {
+      'content-type': 'text/event-stream; charset=utf-8',
+      'cache-control': 'no-cache',
+      connection: 'keep-alive',
+      'x-accel-buffering': 'no',
+      'content-encoding': 'identity',
+    });
+  } catch (error) { logStream(sessionId, 'writeHead failed', error); return; }
+  res.write(': connected\n\n');
+  const ac = new AbortController();
+  res.on('close', () => ac.abort());
+  // 与设备级流（mobile/events.js）对齐：写坏掉的连接不该让 'error' 在 res 上无人接住
+  // 而变成未捕获异常，那时 aborted 仍是 false，收尾分支会以为客户端还在、白写一帧 resync。
+  res.on('error', () => ac.abort());
+  const keepAlive = setInterval(() => {
+    try {
+      res.write(': keepalive\n\n');
+    } catch (error) {
+      // 写失败 = 客户端已经不在了。旧实现把它吞掉，interval 继续空转，连接既不
+      // 产出也不终止；这里立刻收尾，别把它留在 relay 的 pending 里等超时。
+      logStream(sessionId, 'keepalive write failed', error);
+      clearInterval(keepAlive);
+      ac.abort();
+      try { res.end(); } catch { /* ignore */ }
+    }
+  }, 15_000);
+  // 定时器不该拖住进程退出：宿主/worker 关停时若这条 SSE 还挂着，事件循环会被它按在
+  // 15s 一拍上，收尾要等到下一次 tick 才发生（lib/sidecar-facade-worker.cjs 的
+  // shutdown 就是这么做的）。测试里的 setInterval 桩没有 unref，所以先判类型。
+  if (keepAlive && typeof keepAlive.unref === 'function') keepAlive.unref();
+
+  const resumeSeq = parseResumeSeq(req, sessionId);
+  // 已交付的 seq 水位：从续传位置开始，重连时先回放、后接入实时流，并用它去重。
+  let lastDeliveredSeq = resumeSeq != null ? resumeSeq : 0;
+  // 「客户端已经走了」与「mux 循环正常结束」必须分开：前者不必再回写 resync，
+  // 后者必须回写，否则客户端会把一次静默断流当成正常状态一直等下去。
+  let clientGone = false;
+  let loopEnded = false;
+
+  try {
+    // 断线续传：先回放 history 中 seq > resumeSeq 的事件（收敛状态）。
+    if (resumeSeq != null && resumeSeq > 0) {
+      const replay = await replaySince(ctx, sessionId, resumeSeq, res, ac.signal, (seq) => { lastDeliveredSeq = Math.max(lastDeliveredSeq, seq); });
+      if (replay.gap && !ac.signal.aborted) {
+        const value = { type: 'session/resync-required', sessionId, resumeSeq, oldestSeq: replay.oldestSeq };
+        // 旧实现在这里直接 `return`：既不清 keepAlive 也不 end，漏出一条永不收尾的连接。
+        if (!writeSse(res, value, { payload: value })) clientGone = true;
+      }
+    }
+
+    if (!clientGone) {
+      // payload 里带 sessionId：0.2.0 的宿主没有设备级事件流了，兼容桥据此收窄成
+      // 这一条会话的 follow + 投影 + 任务三条流（见 mobile/host-bridge.js 的 muxFrames）。
+      // 不带就是设备级视角，只会给工作区基线与全局投影 —— 这里反正只要单会话。
+      const frames = ctx.apiProxy.events.mux({ rpcId: 'mobile-stream', payload: { sessionId } }, ac.signal);
+      for await (const frame of frames) {
+        const p = frame.payload;
+        if (!p || p.sessionId !== sessionId) continue;
+        // 增量事件保持原 wire：data 仍是原事件 JSON，SSE 元数据独立于 data。
+        if (p.type === 'session/event') {
+          const seq = p.event && Number.isFinite(p.event.seq) ? p.event.seq : null;
+          // 回放已覆盖该 seq（回放与实时交界处）→ 跳过，避免重复交付。
+          if (seq !== null && seq <= lastDeliveredSeq) continue;
+          const event = await resolveEventAttachments(ctx, sessionId, p.event);
+          if (!writeSse(res, event, { ...frame, payload: { ...p, event } })) { clientGone = true; break; }
+          if (seq !== null) lastDeliveredSeq = seq;
+        } else if (p.type === 'session/queue' || p.type === 'session/projection') {
+          // 队列/投影整帧转发；不假定存在可重放的宿主 API。
+          if (!writeSse(res, p, frame)) { clientGone = true; break; }
+        } else if (p.type === 'session/jobs') {
+          // 后台任务整帧（桌面端会话头部任务面板的数据源）。宿主只在任务有变化时发，
+          // 且**空数组也要转发** —— 那是「任务都结束了」的唯一信号，丢掉它就永远清不掉。
+          const value = { type: 'session/jobs', sessionId, jobs: normalizeJobs(p.jobs) };
+          if (!writeSse(res, value, frame)) { clientGone = true; break; }
+        } else if (p.type === 'question/requested') {
+          // 问题是可回答的 mux server-request，而非 session/event；保留 rpcId 供回答关联。
+          const value = { ...p, rpcId: frame.rpcId };
+          if (!writeSse(res, value, { ...frame, payload: value })) { clientGone = true; break; }
+        } else if (p.type === 'question/resolved' || p.type === 'approval/requested' || p.type === 'approval/asked' || p.type === 'approval/decided' || p.type === 'approval/resolved') {
+          // Approval frames are server requests/resolutions, not session/event frames;
+          // forward the rpcId and approval identity so the mobile client can answer safely.
+          const value = ANSWERABLE_APPROVAL_TYPES.has(p.type) && frame.rpcId ? { ...p, rpcId: frame.rpcId } : p;
+          if (!writeSse(res, value, { ...frame, payload: value })) { clientGone = true; break; }
+        }
+      }
+      if (!clientGone) loopEnded = true;
+    }
+  } catch (error) {
+    // 旧实现是 `catch { }`：mux 循环一旦抛错（底层 /api/events.mux 的 HTTP SSE 连接
+    // 中断、返回非异步可迭代、signal abort），连接就永远停在 preamble 之后 ——
+    // 客户端无限期静默挂起，relay 侧条目也一直挂着，两边都查不出原因。
+    logStream(sessionId, 'mux loop threw', error);
+  }
+  clearInterval(keepAlive);
+  try {
+    if (!res.writableEnded) {
+      // 明确告诉客户端「流到此为止，请带 lastSeq 重连」：它会走已验证可用的 replay
+      // 路径补上缺口，而不是把静默断流当成正常状态。
+      if (!ac.signal.aborted && !clientGone) {
+        writeSse(res, { type: 'session/resync-required', sessionId, oldestSeq: lastDeliveredSeq + 1 });
+      }
+      res.end();
+      logStream(sessionId, `stream closed (loopEnded=${loopEnded}, aborted=${ac.signal.aborted}, clientGone=${clientGone}, deliveredSeq=${lastDeliveredSeq})`, null);
+    }
+  } catch (error) {
+    // 旧实现把 end 失败也吞了 —— 这正是「relay 永远收不到 httpEnd」的直接原因。
+    logStream(sessionId, 'stream end failed', error);
+  }
+}
+
+/**
+ * 从会话 history 回放 seq > sinceSeq 的事件（升序），逐个经附件解析后写 SSE。
+ * 通过 onDelivered(seq) 回报已交付的最大 seq，供上层去重。
+ */
+async function replaySince(ctx, sessionId, sinceSeq, res, signal, onDelivered) {
+  try {
+    const { value } = unwrap(await callSessions(ctx, 'history', { sessionId, maxMessages: REPLAY_WINDOW }));
+    const events = (value && Array.isArray(value.events)) ? value.events : [];
+    const seqs = events
+      .map((entry) => (entry?.event || entry)?.seq)
+      .filter((seq) => Number.isSafeInteger(seq) && seq >= 0);
+    const oldestSeq = seqs.length ? Math.min(...seqs) : null;
+    // hasMore means the retained history starts before this page. If its first
+    // sequence is more than one past the cursor, replay cannot be contiguous.
+    const gap = Boolean(value && value.hasMore === true && (oldestSeq === null || oldestSeq - sinceSeq > 1));
+    const candidates = events
+      .filter((entry) => {
+        const e = entry?.event || entry;
+        return e && Number.isFinite(e.seq) && e.seq > sinceSeq;
+      })
+      .sort((a, b) => ((a?.event || a).seq) - ((b?.event || b).seq));
+    for (const entry of candidates) {
+      if (signal.aborted) break;
+      const e = entry?.event || entry;
+      const event = await resolveEventAttachments(ctx, sessionId, e);
+      // Keep replay data identical to live SSE data: the client reducer consumes
+      // the event's own type (turn/start, assistant/message, etc.).
+      const payload = { type: 'session/event', sessionId, event };
+      if (!writeSse(res, event, { payload })) break;
+      if (Number.isFinite(event.seq)) onDelivered(event.seq);
+    }
+    return { gap, oldestSeq };
+  } catch (error) { /* 回放尽力而为；失败不阻塞实时流 */
+    logStream(sessionId, 'replay failed', error);
+    return { gap: false, oldestSeq: null };
+  }
+}
+
+module.exports = { handleStream, parseResumeSeq };

package/lib/mobile/subagents.js

@@ -0,0 +1,265 @@
+'use strict';
+
+/**
+ * 移动端「子代理」API：把某个会话派出去的子代理目录转给手机。
+ *
+ * 桌面端会话标题栏里挂着一个「N 个子代理」下拉（@deepseek-ai/dsh-client-ui-subagent
+ * 的 SubagentHeaderLineage）：父会话头部按 `origin === "subagent" && parentId ===
+ * 当前会话` 把子代理收成一棵树，点进去能读子会话的完整记录。手机端此前把
+ * `origin === 'subagent'` 的行在侧栏里直接 continue 掉（app/src/drawerGroups.ts:122），
+ * 于是用户既不知道这个会话派过子代理，也没有任何入口能打开它 —— 子代理在手机上
+ * 等于不存在。
+ *
+ * 子会话本身其实早就读得到：/sessions 会带上 origin/parentSessionId，/session 与
+ * /session/messages 也能直接读子会话的记录。缺的只是「这个会话有哪些子代理」——
+ * 那正是 subagent.list 的返回值（entries + parentAvailable），这里只做形状收敛、
+ * 限长与限条数，避免异常宿主把手机端列表撑爆。
+ *
+ * 宿主 subagent.list 的第二个形参是取消信号（内部 listChildren 会读 signal），
+ * 故与 session.search 一样显式传一个 AbortController 的 signal，不裸传 undefined。
+ *
+ * DSH 0.2.0 没有 subagent.list 这个 RPC 了，目录改由 host-bridge.js 从会话投影的
+ * subagentCatalog 重建（形状仍是 entries + parentAvailable），本文件对它的形状收敛、
+ * 限长与限条数一字未动。
+ */
+
+const { sendJson, readJsonBody } = require('../shared/http-util');
+const { unwrap } = require('./sessions.js');
+
+const SUBAGENT_MAX_ENTRIES = 100;  // 子代理条数上限（正常宿主只有个位数）
+const SUBAGENT_ID_MAX = 200;       // 会话 id 长度上限
+const SUBAGENT_LABEL_MAX = 200;    // 条目显示名截断长度
+// 0.2.0 的会话投影多了第三种 mode 'unknown'：目录说这条子会话存在，但宿主还没读到
+// 它的子代理身份（session/subagent 投影没算出来），所以既不能当成一次性也不能当成
+// 可继续。桌面端对它的处理是当只读 + 显示「模式未知」，这里跟着放行。
+const SUBAGENT_MODES = new Set(['one-shot', 'continuable', 'unknown']);
+const SUBAGENT_ACTIVITIES = new Set(['running', 'inactive']);
+const SUBAGENT_REASONS = new Set(['corrupt', 'unsupported', 'unavailable']);
+const SUBAGENT_PROMPT_MAX_BODY = 256 * 1024;  // 续话请求体上限（只有文本，图片已拒）
+const SUBAGENT_PROMPT_MAX_BLOCKS = 32;        // content 块数上限
+const SUBAGENT_PROMPT_MAX_TEXT = 64 * 1024;   // 单条 text 块字符上限
+const SUBAGENT_INTERRUPT_MAX_BODY = 64 * 1024;
+
+/** 会话 id：必须是非空字符串；超长截断（纯防御异常宿主）。 */
+function normalizeId(value) {
+  if (typeof value !== 'string') return '';
+  const id = value.trim();
+  if (!id) return '';
+  return id.length > SUBAGENT_ID_MAX ? id.slice(0, SUBAGENT_ID_MAX) : id;
+}
+
+/** 显示名：非字符串或空白当「没有」；超长截断补省略号。 */
+function normalizeLabel(value) {
+  if (typeof value !== 'string') return undefined;
+  const label = value.trim();
+  if (!label) return undefined;
+  return label.length > SUBAGENT_LABEL_MAX ? `${label.slice(0, SUBAGENT_LABEL_MAX)}…` : label;
+}
+
+/**
+ * 把 subagent.list 的一条条目压成手机需要的形状；坏条目直接丢掉。
+ *
+ * 两种 kind 的必填字段不同：child 要 mode/activity/hasChildren 都合法才留，
+ * diagnostic 只要有 id + 认识的 reason。child 的 label 保持可选（宿主对
+ * continuable 才保证有），App 侧缺省回落到 id —— 与桌面端 `entry.label ?? entry.id`
+ * 一致，猜一个假名字反而会误导用户。
+ */
+function normalizeSubagentEntry(item) {
+  if (!item || typeof item !== 'object' || Array.isArray(item)) return null;
+  const id = normalizeId(item.id);
+  if (!id) return null;
+
+  if (item.kind === 'diagnostic') {
+    if (!SUBAGENT_REASONS.has(item.reason)) return null;
+    return { kind: 'diagnostic', id, reason: item.reason };
+  }
+
+  if (item.kind !== 'child') return null;
+  if (!SUBAGENT_MODES.has(item.mode)) return null;
+  if (!SUBAGENT_ACTIVITIES.has(item.activity)) return null;
+  if (typeof item.hasChildren !== 'boolean') return null;
+
+  const label = normalizeLabel(item.label);
+  return {
+    kind: 'child',
+    id,
+    mode: item.mode,
+    activity: item.activity,
+    hasChildren: item.hasChildren,
+    ...(label === undefined ? {} : { label }),
+  };
+}
+
+/**
+ * 收敛 subagent.list 的 value：非数组当空目录，坏条目丢掉，按 id 去重（保留先出现的），
+ * 再截到上限。parentAvailable 用严格比较 —— 宿主漏字段时按「父会话不在线」处理，
+ * 与桌面端「父会话不在线 → 只读」的判定方向一致，猜真值会让手机端误以为还能发消息。
+ */
+function normalizeSubagentList(value) {
+  const raw = value && typeof value === 'object' && Array.isArray(value.entries) ? value.entries : [];
+  const entries = [];
+  const seen = new Set();
+  for (const item of raw) {
+    const entry = normalizeSubagentEntry(item);
+    if (!entry || seen.has(entry.id)) continue;
+    seen.add(entry.id);
+    entries.push(entry);
+    if (entries.length >= SUBAGENT_MAX_ENTRIES) break;
+  }
+  return { entries, parentAvailable: Boolean(value && value.parentAvailable === true) };
+}
+
+/** GET /api/mobile/v1/subagents?sessionId=… —— 这个会话派出去的子代理目录（只读）。 */
+async function handleSubagents(ctx, req, res) {
+  const url = new URL(req.url, 'http://x');
+  const sessionId = (url.searchParams.get('sessionId') || '').trim();
+  if (!sessionId) return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: '需要 sessionId' } });
+
+  const controller = new AbortController();
+  // 注意命名空间是复数 subagents（apiProxy.subagents.list），而 RPC 方法名是单数
+  // subagent.list —— 宿主两处不对称，写错只会得到 "Cannot read properties of
+  // undefined (reading 'list')" 这种 500，所以这里别按方法名顺手改成单数。
+  const { value, error } = unwrap(await ctx.apiProxy.subagents.list({
+    rpcId: 'mobile',
+    method: 'subagent.list',
+    payload: { parentSessionId: sessionId },
+  }, controller.signal));
+  if (error) return sendJson(res, 400, { ok: false, error });
+
+  sendJson(res, 200, { ok: true, ...normalizeSubagentList(value) });
+}
+
+/** 从请求体里取一个必填的会话 id（trim 后仍为空就当没给）。 */
+function readId(body, key) {
+  const value = body && body[key];
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+/**
+ * 把续话请求的 content 收敛成宿主 subagent.prompt 认的形状。
+ *
+ * 与 /session/send 同一套规则，但**图片一律拒绝**：桌面端在路由之前就把带 image 的
+ * 续话判成 attachment-error / SUBAGENT_IMAGE_UNSUPPORTED（runtime 的 subagent 分支
+ * 只把 text 块 flatMap 出去，图片根本到不了宿主）。这里跟着拒，免得静默丢块让用户
+ * 以为图发出去了。
+ */
+function normalizePromptContent(body) {
+  let content;
+  if (Array.isArray(body.content)) content = body.content;
+  else if (typeof body.text === 'string' && body.text.trim()) content = [{ type: 'text', text: body.text }];
+  else return { error: { code: 'bad-request', message: '需要 content 数组或 text' } };
+
+  if (content.length === 0) return { error: { code: 'bad-request', message: 'content 不能为空' } };
+  if (content.length > SUBAGENT_PROMPT_MAX_BLOCKS) {
+    return { error: { code: 'bad-request', message: `content 一次最多 ${SUBAGENT_PROMPT_MAX_BLOCKS} 块` } };
+  }
+
+  const blocks = [];
+  for (const block of content) {
+    if (!block || typeof block.type !== 'string') {
+      return { error: { code: 'bad-request', message: 'content 块缺少 type' } };
+    }
+    if (block.type === 'image') {
+      return {
+        error: {
+          code: 'attachment-error',
+          message: '子代理续话不支持图片输入。',
+          details: { reason: 'SUBAGENT_IMAGE_UNSUPPORTED' },
+        },
+      };
+    }
+    if (block.type !== 'text') {
+      return { error: { code: 'bad-request', message: `不支持的 content 块类型: ${block.type}` } };
+    }
+    if (typeof block.text !== 'string' || !block.text.trim()) {
+      return { error: { code: 'bad-request', message: 'text 块内容为空' } };
+    }
+    if (block.text.length > SUBAGENT_PROMPT_MAX_TEXT) {
+      return { error: { code: 'bad-request', message: `text 块最长 ${SUBAGENT_PROMPT_MAX_TEXT} 个字符` } };
+    }
+    blocks.push({ type: 'text', text: block.text });
+  }
+  return { blocks };
+}
+
+/**
+ * POST /api/mobile/v1/subagents/prompt —— 给「可继续」子代理续一条消息。
+ *
+ * 手机端的输入框平时只会发 session.send，而宿主对子会话的 session.prompt /
+ * session.models 一律回 agent-busy（"use subagent delivery for this child session"），
+ * 所以续话必须走 subagent.prompt。mode 固定 continuable：一次性子代理宿主压根
+ * 不接受续话（桌面端也是先判 one-shot 再拒绝），这里不给客户端挑的机会。
+ *
+ * 宿主还要求父会话「在线」（ctx.agents.get(parentSessionId) 有值），否则回
+ * subagent-parent-unavailable —— 这一条原样透传给 App，由它决定提示什么。
+ */
+async function handleSubagentPrompt(ctx, req, res) {
+  const body = await readJsonBody(req, SUBAGENT_PROMPT_MAX_BODY);
+  const parentSessionId = readId(body, 'parentSessionId');
+  const childSessionId = readId(body, 'childSessionId');
+  if (!parentSessionId || !childSessionId) {
+    return sendJson(res, 400, {
+      ok: false,
+      error: { code: 'bad-request', message: '需要 { parentSessionId, childSessionId, content | text }' },
+    });
+  }
+  const normalized = normalizePromptContent(body);
+  if (normalized.error) return sendJson(res, 400, { ok: false, error: normalized.error });
+
+  const clientTimeZone = typeof body.clientTimeZone === 'string' && body.clientTimeZone.trim()
+    ? body.clientTimeZone.trim()
+    : undefined;
+
+  const controller = new AbortController();
+  const { error } = unwrap(await ctx.apiProxy.subagents.prompt({
+    rpcId: 'mobile',
+    method: 'subagent.prompt',
+    payload: {
+      parentSessionId,
+      childSessionId,
+      mode: 'continuable',
+      content: normalized.blocks,
+      ...(clientTimeZone === undefined ? {} : { clientTimeZone }),
+    },
+  }, controller.signal));
+  if (error) return sendJson(res, 400, { ok: false, error });
+
+  // 宿主回的是 { messageId }，但手机端自己生成乐观行的 clientMessageId，用不上它。
+  sendJson(res, 200, { ok: true, accepted: true });
+}
+
+/**
+ * POST /api/mobile/v1/subagents/interrupt —— 打断可继续子代理当前这一轮。
+ *
+ * 宿主的 subagents.interrupt(request) 只声明了一个形参（与 prompt 不同），所以这里
+ * 不传 signal —— 多传一个参数不会报错，但会让人误以为它有取消语义。
+ */
+async function handleSubagentInterrupt(ctx, req, res) {
+  const body = await readJsonBody(req, SUBAGENT_INTERRUPT_MAX_BODY);
+  const parentSessionId = readId(body, 'parentSessionId');
+  const childSessionId = readId(body, 'childSessionId');
+  if (!parentSessionId || !childSessionId) {
+    return sendJson(res, 400, {
+      ok: false,
+      error: { code: 'bad-request', message: '需要 { parentSessionId, childSessionId }' },
+    });
+  }
+
+  const { error } = unwrap(await ctx.apiProxy.subagents.interrupt({
+    rpcId: 'mobile',
+    method: 'subagent.interrupt',
+    payload: { parentSessionId, childSessionId, mode: 'continuable' },
+  }));
+  if (error) return sendJson(res, 400, { ok: false, error });
+
+  sendJson(res, 200, { ok: true, accepted: true });
+}
+
+module.exports = {
+  handleSubagents,
+  handleSubagentPrompt,
+  handleSubagentInterrupt,
+  normalizeSubagentEntry,
+  normalizeSubagentList,
+  normalizePromptContent,
+};