dsh-mobile-plugin 0.0.0-stage → 0.1.57

package/lib/mobile/history-derive.js

@@ -0,0 +1,608 @@
+'use strict';
+
+/**
+ * 会话历史的纯派生逻辑：从 host history 事件折叠出 v1 移动端的消息/结构化项。
+ *
+ * 本模块只做「事件 → 展示结构」的纯计算，不碰 ctx、不发 RPC，因此可以单独测；
+ * 原先这些函数与路由 handler 混在 lib/mobile/sessions.js 里（该文件 1964 行），
+ * 拆出来后 handler 层只负责 HTTP 与宿主交互。
+ */
+
+/**
+ * 从 session.list 摘要行取会话标题（与桌面端侧栏同源，不再从 history 窗口猜）：
+ *  - 优先读 title 投影（dsh-session-title 在「完整日志」上折叠的最新 session/title
+ *    事件，正是桌面端侧栏显示的同一个值；空白会话恒为 ''，由前端显示「新会话」占位）；
+ *  - 无正式标题时回退到工作区目录 basename，最后回退到 sessionId
+ *    （对齐 dsh-client-runtime displayTitleOf 的兜底链）。
+ * 注意：不能从 history 的 30 条窗口里找标题——长会话会把标题事件挤出窗口（桌面端无此问题）。
+ */
+function listTitle(s) {
+  if (!s || s.blank) return '';
+  const t = s.projections && s.projections.values ? s.projections.values.title : undefined;
+  if (typeof t === 'string' && t !== '') return t;
+  if (typeof s.cwd === 'string' && s.cwd !== '') {
+    const base = s.cwd.replace(/[/\\]+$/, '').split(/[/\\]/).pop();
+    if (base !== undefined && base !== '') return base;
+  }
+  return s.sessionId || '';
+}
+
+/** 单文件一行文本的传输上限：整文件 create/overwrite 的 newText 可能极大，超出即截断并标记。 */
+const DIFF_TEXT_MAX_LINES = 400;
+/** 一次工具调用最多回传的 diff 文件数（对齐桌面「一行一张卡」的粒度，避免畸形 meta 撑爆载荷）。 */
+const DIFF_MAX_FILES = 20;
+
+/** 按行数截断一段 diff 文本；未超限原样返回，超限保留前 MAX 行并标记 truncated。 */
+function capDiffText(text) {
+  if (typeof text !== 'string') return undefined;
+  let lines = 0;
+  for (let i = 0; i < text.length; i += 1) {
+    if (text.charCodeAt(i) === 10) lines += 1;
+    if (lines >= DIFF_TEXT_MAX_LINES) {
+      return { text: text.slice(0, i), truncated: true };
+    }
+  }
+  return { text, truncated: false };
+}
+
+/**
+ * 收窄 tool/result 的 `data.meta`（write/edit 的 FsDiffMeta）为可回传的 diff 列表。
+ *
+ * 桌面 diff 卡的数据源头就是这里：fs 工具把「已应用的分块上下文 diff」挂在
+ * `result.meta` 上（dsh-tool-fs 的 computeHunkDiffs，DIFF_CONTEXT=3），
+ * agent loop 原样写进 tool/result 事件（dsh-agent-loop/lib/index.js:313
+ * `...result.meta !== void 0 ? { meta: result.meta } : {}`），并随会话日志持久化。
+ * 此前移动端投影只读 message.content，把 meta 整个丢掉——于是 App 里 write/edit
+ * 只剩一坨 JSON 参数，而桌面显示的是真正改了什么。
+ *
+ * 只接受形状正确的条目（path 非空字符串、newText 字符串、oldText 字符串或 null），
+ * 畸形数据返回 undefined 让调用方退回通用卡片，绝不抛错。
+ */
+function normalizeResultDiffs(meta) {
+  if (!meta || typeof meta !== 'object' || !Array.isArray(meta.diffs)) return undefined;
+  const out = [];
+  for (const raw of meta.diffs) {
+    if (!raw || typeof raw !== 'object') continue;
+    const path = typeof raw.path === 'string' && raw.path !== '' ? raw.path : undefined;
+    const newText = capDiffText(raw.newText);
+    if (path === undefined || newText === undefined) continue;
+    const oldText = typeof raw.oldText === 'string' ? capDiffText(raw.oldText) : undefined;
+    if (raw.oldText !== null && raw.oldText !== undefined && typeof raw.oldText !== 'string') continue;
+    out.push({
+      path,
+      oldText: oldText === undefined ? null : oldText.text,
+      newText: newText.text,
+      ...newText.truncated || (oldText && oldText.truncated) ? { truncated: true } : {},
+    });
+    if (out.length >= DIFF_MAX_FILES) break;
+  }
+  return out.length > 0 ? out : undefined;
+}
+
+/** 预扫描 tool/result 事件，构建 callId → {isError, code} 映射（对接桌面 toolRowModel 状态派生）。 */
+function buildToolResultMap(events) {
+  const map = new Map();
+  for (const entry of events) {
+    const e = entry.event || entry;
+    if (e.type !== 'tool/result' || !e.data || !e.data.message) continue;
+    const msg = e.data.message;
+    const src = msg.source;
+    if (!src || typeof src.callId !== 'string') continue;
+    const content = Array.isArray(msg.content) ? msg.content[0] : null;
+    const isError = content && content.isError === true;
+    const code = e.data.error && typeof e.data.error.code === 'string' ? e.data.error.code : undefined;
+    const parts = content && Array.isArray(content.content) ? content.content : content ? [content] : [];
+     const output = parts.map((part) => {
+       if (part && typeof part.text === 'string') return part.text;
+       if (part && typeof part === 'object' && part.type === 'image') return '';
+        try { return JSON.stringify(part); } catch { return ''; }
+     }).filter(Boolean).join('');
+     const images = parts
+        .filter((part) => part && typeof part === 'object' && part.type === 'image'
+          && typeof part.data === 'string' && typeof part.mediaType === 'string')
+        .map((part) => ({ mediaType: part.mediaType, data: part.data, ...(typeof part.name === 'string' ? { name: part.name } : {}) }));
+      const diffs = normalizeResultDiffs(e.data.meta);
+      map.set(src.callId, { isError, code, ...(output ? { output } : {}), ...(images.length ? { images } : {}), ...(diffs ? { diffs } : {}) });
+  }
+  return map;
+}
+
+/** 把 assistant message.content 解析为一个结构块数组（text/reasoning/tool-call/image）。 */
+function parseBlocks(blocks, toolResults) {
+  if (!Array.isArray(blocks)) return [];
+  const out = [];
+  for (const b of blocks) {
+    if (!b || typeof b.type !== 'string') continue;
+    if (b.type === 'text' && typeof b.text === 'string' && b.text) {
+      out.push({ type: 'text', text: b.text });
+    } else if (b.type === 'reasoning') {
+      // Reasoning blocks may be emitted as empty placeholders when the provider
+      // does not expose chain-of-thought. They are known blocks, not unsupported
+      // content; silently omit empty placeholders and avoid leaking their JSON.
+      if (typeof b.text === 'string' && b.text) out.push({ type: 'reasoning', text: b.text });
+    } else if (b.type === 'image' && typeof b.data === 'string' && typeof b.mediaType === 'string') {
+      out.push({ type: 'image', mediaType: b.mediaType, data: b.data, name: typeof b.name === 'string' ? b.name : undefined });
+    } else if (b.type === 'tool-call') {
+      // tool-call 块字段为 id/name/arguments（与 harness toAssistantBlock 同口径）。
+      const callId = b.id != null ? String(b.id) : undefined;
+      let state;
+       let output;
+       let images;
+       let diffs;
+      if (callId && toolResults) {
+        const result = toolResults.get(callId);
+        if (result) {
+          output = result.output;
+           images = result.images;
+           // write/edit 的已应用分块 diff（桌面 diff 卡的数据源）；结果侧权威，
+           // 有它就替换掉仅凭 arguments 猜出来的调用态。
+           diffs = result.diffs;
+           // 对齐桌面 toolRowModel 状态派生：error.code === 'interrupted' → stopped, isError → error, ok
+          if (result.isError) {
+            state = result.code === 'interrupted' ? 'stopped' : 'error';
+          } else {
+            state = 'ok';
+          }
+        }
+      }
+      out.push({
+        type: 'tool-call',
+        callId,
+        name: typeof b.name === 'string' ? b.name : undefined,
+        argsRaw: typeof b.arguments === 'string' ? b.arguments : (b.arguments != null ? JSON.stringify(b.arguments) : undefined),
+        ...state ? { state } : {},
+         ...typeof output === 'string' && output ? { output } : {},
+         ...images && images.length ? { images } : {},
+         ...diffs && diffs.length ? { diffs } : {},
+      });
+    } else {
+      // 桌面端对未知 assistant block 使用 JsonBlock 兜底；移动端没有对应组件，
+      // 先保留原始内容为可见文本，避免历史重同步后该节点整体消失。
+      out.push({ type: 'text', text: `[未支持的内容块]\n${JSON.stringify(b)}` });
+    }
+  }
+  return out;
+}
+
+/** 从结构块里拼接纯文本（列表预览/标题回退用，仍只取 text 块）。 */
+function blocksToText(blocks) {
+  return blocks.filter((b) => b.type === 'text' && typeof b.text === 'string').map((b) => b.text).join('\n');
+}
+
+/** 从 compaction/summary 的 summary 字段提取展示文本（数组=文本块列表，字符串直接取；空→null）。 */
+function compactionSummaryText(summary) {
+  if (Array.isArray(summary)) {
+    const text = summary.filter((b) => b && b.type === 'text' && typeof b.text === 'string').map((b) => b.text).join('');
+    return text.trim() === '' ? null : text;
+  }
+  if (typeof summary === 'string') return summary.trim() === '' ? null : summary;
+  return null;
+}
+
+/** 从 shadowedSeqs 取被压缩条数（数组长度；缺失→null）。 */
+function shadowedCount(seqs) {
+  return Array.isArray(seqs) ? seqs.length : null;
+}
+
+/** 取安全非负整数的 token 数（与桌面端同口径：safe integer 且 >= 0，否则 null）。 */
+function shadowedTokens(n) {
+  return Number.isSafeInteger(n) && n >= 0 ? n : null;
+}
+
+/** retry failure 字段：{code?, message?} 或 null（字段缺失/非字符串则省略）。 */
+function retryFailure(failure) {
+  if (!failure || typeof failure !== 'object') return null;
+  const out = {};
+  if (typeof failure.code === 'string' && failure.code !== '') out.code = failure.code;
+  if (typeof failure.message === 'string' && failure.message !== '') out.message = failure.message;
+  return out.code !== undefined || out.message !== undefined ? out : null;
+}
+
+/** 上下文行的 label 提取（与桌面 contextProvenance 同口径；取不到为 null）。 */
+function contextLabelOf(source) {
+  const kind = source.kind;
+  if (kind === 'session-reference') {
+    for (const ref of Array.isArray(source.references) ? source.references : []) {
+      if (ref && typeof ref.label === 'string' && ref.label) return ref.label;
+    }
+    return null;
+  }
+  if (kind === 'agent-instructions') {
+    for (const change of Array.isArray(source.changes) ? source.changes : []) {
+      if (change && typeof change.path === 'string' && change.path) return change.path;
+    }
+    return null;
+  }
+  if (kind === 'plugin') return typeof source.plugin === 'string' && source.plugin ? source.plugin : null;
+  if (kind === 'skill-invocation') return typeof source.name === 'string' && source.name ? source.name : null;
+  return typeof kind === 'string' ? kind : null;
+}
+
+/** 列表/概览的 lastMessage 预览只取有 role 的消息项（结构化行不参与预览）。 */
+function lastMessageOf(messages) {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (messages[i] && messages[i].role) return messages[i];
+  }
+  return null;
+}
+
+/**
+ * 从 history 事件折叠出消息与「结构化行」（wire v1 扩展，向后兼容）：
+ *  - 普通消息维持现状：{ id, seq, time, role, text, blocks?, images?, clientMessageId? }（user/assistant）；
+ *  - compaction：{ kind:'compaction', id, seq, time, state:'running'|'done', summary?, shadowedItemCount?, shadowedTokenCount? }；
+ *    压缩检查点 user/message（source.kind==='plugin' && source.plugin==='compact'）绝不渲染成用户气泡，
+ *    渲染成 compaction 行（id=compactionId，state='done'），并用同 compactionId 的 compaction/summary 补 counts；
+ *  - retry：{ kind:'retry', id: retryId, seq, time, status:'scheduled'|'started', retry, maxRetries, delayMs?, failure? }；
+ *  - turn-error / max-tokens：{ kind:'turn-error', id:'turn-<turn>', message, code? } / { kind:'max-tokens', id:'turn-<turn>' }；
+ *  - context：{ kind:'context', id:'ctx-<msgId>', contextRole:'inject'|'recall', contextLabel, text }；
+ *  - command：{ kind:'command', id:commandId, name, status:'running'|'done', resultKind?, text? }
+ *    （command/run 发出行，command/done 原地升级：name 保 run 的，resultKind/text 取 done 的）。
+ * 结构化项与消息按事件 seq 升序混排返回；旧载荷字段缺失时跳过对应项，绝不抛错。
+ */
+function deriveMessages(events) {
+  const out = [];
+  // 预扫描 tool/result 事件（同批次事件内，结果可能在调用块之前/之后出现）。
+  const toolResults = buildToolResultMap(events);
+  // 预扫描 compaction/summary：检查点 user/message 与 summary 事件在日志里的先后不固定，
+  // 用 compactionId → summary 数据把 counts 补全到同一压缩行上。
+  const summaries = new Map();
+  for (const entry of events) {
+    const e = entry.event || entry;
+    if (e.type !== 'compaction/summary' || !e.data || typeof e.data.compactionId !== 'string') continue;
+    summaries.set(e.data.compactionId, e.data);
+  }
+  // 单步计时预扫描：为每条 assistant 消息派生「本轮」的 ttft / decode / 输出 token
+  // （对齐桌面 turn-metrics/assistant-timing：ttftMs = 首个非空 delta − step/start；
+  // decodeMs = 落定 − 首个 delta；outputTokens = assistant/message.usage.outputTokens）。
+  // 会话累计 stats 属于输入区常驻统计条，绝不能拿来冒充单轮指标（否则每条历史消息
+  // 都会显示同一份累计行并随轮询刷新——正是移动端此前「统计行一直出现」的根因）。
+  const stepStartTime = new Map();
+  const turnStartTime = new Map();
+  const turnEndTime = new Map();
+  const firstDeltaTime = new Map();
+  const stepOutputTokens = new Map();
+  const stepKey = (turn, step) => `${turn}:${step}`;
+  for (const entry of events) {
+    const e = entry.event || entry;
+    if (!e || typeof e.data !== 'object' || e.data === null) continue;
+    const turn = e.data.turn;
+    const step = e.data.step;
+    if (typeof turn !== 'number') continue;
+    if (e.type === 'turn/start') turnStartTime.set(turn, e.time);
+    if (e.type === 'turn/end') turnEndTime.set(turn, e.time);
+    if (typeof step !== 'number') continue;
+    if (e.type === 'step/start') {
+      const k = stepKey(turn, step);
+      if (!stepStartTime.has(k)) stepStartTime.set(k, e.time);
+    } else if (e.type === 'assistant/chunk' && e.data.chunk) {
+      const c = e.data.chunk;
+      if (c.type === 'text-delta' || c.type === 'reasoning-delta' || c.type === 'tool-call-delta') {
+        const k = stepKey(turn, step);
+        if (!firstDeltaTime.has(k)) firstDeltaTime.set(k, e.time);
+      }
+    } else if (e.type === 'assistant/message' && e.data.usage) {
+      const tokens = e.data.usage.outputTokens;
+      if (typeof tokens === 'number' && tokens > 0) {
+        const k = stepKey(turn, step);
+        if (!stepOutputTokens.has(k)) stepOutputTokens.set(k, tokens);
+      }
+    }
+  }
+  /** 派生一条 assistant 消息所在 step 的单轮计时；缺记录（非流式落定/无 step 边界）返回 undefined。 */
+  const timingOf = (e) => {
+    if (!e || typeof e.data !== 'object' || e.data === null) return undefined;
+    const turn = e.data.turn;
+    const step = e.data.step;
+    if (typeof turn !== 'number' || typeof step !== 'number') return undefined;
+    const k = stepKey(turn, step);
+    const start = stepStartTime.get(k);
+    const first = firstDeltaTime.get(k);
+    const timing = {};
+    const turnStart = turnStartTime.get(turn);
+    const turnEnd = turnEndTime.get(turn);
+    if (turnStart != null && turnEnd != null && turnEnd >= turnStart) timing.runMs = turnEnd - turnStart;
+    if (start == null || first == null) return Object.keys(timing).length > 0 ? timing : undefined;
+    const ttftMs = Math.max(0, first - start);
+    if (ttftMs > 0) timing.ttftMs = ttftMs;
+    const decodeMs = Math.max(0, e.time - first);
+    if (decodeMs > 0) timing.decodeMs = decodeMs;
+    const outputTokens = stepOutputTokens.get(k);
+    if (typeof outputTokens === 'number' && outputTokens > 0) timing.outputTokens = outputTokens;
+    return Object.keys(timing).length > 0 ? timing : undefined;
+  };
+  // 结构化行按 id 唯一：compactionId → 行索引（检查点行原地替换 start 行）、retryId → 行索引（原地升级）。
+  const compactionAt = new Map();
+  const retryAt = new Map();
+  // 命令行按 commandId 唯一：command/run 发出行，command/done 原地升级（保 run 的 name，位置随 done 事件 seq 归位）。
+  const commandAt = new Map();
+
+  // 普通消息（user/assistant）沿用原折叠逻辑。
+  const pushMessage = (msg, e) => {
+    const blocks = parseBlocks(msg.content, toolResults);
+    const text = blocksToText(blocks);
+    const images = blocks.filter((b) => b.type === 'image').map(({ mediaType, data, name }) => ({ mediaType, data, name }));
+    // 只要存在可识别或保留的 block 就入列表；纯推理/工具调用也必须保留，
+    // 否则流式标签在重同步后会消失。
+    const hasContent = blocks.length > 0;
+    if (!hasContent) return;
+    const clientMessageId = msg.role === 'user' ? clientMessageIdFromSource(msg.source, msg) : undefined;
+    const item = {
+      id: String(msg.id),
+      role: msg.role || 'assistant',
+      text,
+      blocks,
+      images: images.length > 0 ? images : undefined,
+      ...(clientMessageId ? { clientMessageId } : {}),
+      seq: e.seq,
+      time: e.time,
+    };
+    const producedFiles = blocks.filter((block) => block.type === 'tool-call' && (block.name === 'write' || block.name === 'edit') && block.state === 'ok').map((block) => {
+       try {
+         const args = JSON.parse(block.argsRaw || '{}');
+         return typeof args.path === 'string' ? args.path : typeof args.file_path === 'string' ? args.file_path : null;
+       } catch { return null; }
+     }).filter((path) => typeof path === 'string');
+     if (producedFiles.length > 0) item.producedFiles = [...new Set(producedFiles)];
+     // 单轮计时只挂 assistant 消息（user/message 无 step 计时）。
+    if (item.role !== 'user') {
+      const timing = timingOf(e);
+      if (timing) item.timing = timing;
+    }
+    out.push(item);
+  };
+
+  // 放入一行 compaction：同一 compactionId 只保留一行，检查点行原地替换 start 行（最终按 seq 排序归位）。
+  const placeCompaction = (item) => {
+    const existing = compactionAt.get(item.id);
+    if (existing !== undefined) out[existing] = item;
+    else {
+      compactionAt.set(item.id, out.length);
+      out.push(item);
+    }
+  };
+
+  for (const entry of events) {
+    const e = entry.event || entry;
+    const seq = e.seq;
+    const time = e.time;
+    if (e.type === 'user/message' && e.data) {
+      const msg = e.data;
+      const src = msg.source;
+      if (src && typeof src === 'object' && src.kind === 'plugin' && src.plugin === 'compact') {
+        // 压缩检查点本身是一条 user/message，绝不能渲染成用户气泡，渲染成 compaction 行。
+        const id = typeof src.compactionId === 'string' && src.compactionId !== ''
+          ? src.compactionId
+          : (msg.id != null ? String(msg.id) : null);
+        if (id === null) continue;
+        const s = summaries.get(id);
+        placeCompaction({
+          id,
+          kind: 'compaction',
+          state: 'done',
+          summary: s ? compactionSummaryText(s.summary) : null,
+          shadowedItemCount: s ? shadowedCount(s.shadowedSeqs) : null,
+          shadowedTokenCount: s ? shadowedTokens(s.shadowedTokenCount) : null,
+          seq,
+          time,
+        });
+        continue;
+      }
+      if (src && typeof src === 'object' && src.kind !== 'user') {
+        // 上下文注入/召回（session-reference→召回，其余 kind→注入）；无文本或无可唯一 id 则跳过该项。
+        const text = blocksToText(parseBlocks(msg.content));
+        if (text === '' || msg.id == null) continue;
+        out.push({
+          id: `ctx-${String(msg.id)}`,
+          kind: 'context',
+          contextRole: src.kind === 'session-reference' ? 'recall' : 'inject',
+          contextLabel: contextLabelOf(src),
+          text,
+          seq,
+          time,
+        });
+        continue;
+      }
+      // 普通用户消息（source 缺失或 kind==='user'）沿用原折叠。
+      pushMessage(msg, e);
+    } else if (e.type === 'assistant/message' && e.data && e.data.message && e.data.message.content) {
+      pushMessage(e.data.message, e);
+    } else if (e.type === 'compaction/start' && e.data && typeof e.data.compactionId === 'string' && e.data.compactionId !== '') {
+      // 行已由检查点发出（done）时跳过，避免重复行。
+      if (!compactionAt.has(e.data.compactionId)) {
+        placeCompaction({
+          id: e.data.compactionId,
+          kind: 'compaction',
+          state: 'running',
+          summary: null,
+          shadowedItemCount: null,
+          shadowedTokenCount: null,
+          seq,
+          time,
+        });
+      }
+    } else if (e.type === 'compaction/summary' && e.data && typeof e.data.compactionId === 'string' && e.data.compactionId !== '') {
+      // 已有同 compactionId 的行（start 或检查点发出）→ 升级为 done 并补 counts；否则新增 done 行。
+      const id = e.data.compactionId;
+      const existing = compactionAt.has(id) ? out[compactionAt.get(id)] : null;
+      if (existing) {
+        existing.state = 'done';
+        existing.summary = compactionSummaryText(e.data.summary);
+        existing.shadowedItemCount = shadowedCount(e.data.shadowedSeqs);
+        existing.shadowedTokenCount = shadowedTokens(e.data.shadowedTokenCount);
+      } else {
+        placeCompaction({
+          id,
+          kind: 'compaction',
+          state: 'done',
+          summary: compactionSummaryText(e.data.summary),
+          shadowedItemCount: shadowedCount(e.data.shadowedSeqs),
+          shadowedTokenCount: shadowedTokens(e.data.shadowedTokenCount),
+          seq,
+          time,
+        });
+      }
+    } else if (e.type === 'llm/retry' && e.data && typeof e.data.retryId === 'string' && e.data.retryId !== '' && typeof e.data.retry === 'number') {
+      // 同 retryId 的后续重试（retry=2…）原地更新，保持一行。
+      const id = e.data.retryId;
+      const existing = retryAt.has(id) ? out[retryAt.get(id)] : null;
+      if (existing) {
+        existing.status = 'scheduled';
+        existing.retry = e.data.retry;
+        if (typeof e.data.maxRetries === 'number') existing.maxRetries = e.data.maxRetries;
+        if (typeof e.data.delayMs === 'number') existing.delayMs = e.data.delayMs;
+        existing.failure = retryFailure(e.data.failure);
+      } else {
+        const item = {
+          id,
+          kind: 'retry',
+          status: 'scheduled',
+          retry: e.data.retry,
+          maxRetries: typeof e.data.maxRetries === 'number' ? e.data.maxRetries : null,
+          failure: retryFailure(e.data.failure),
+          seq,
+          time,
+        };
+        if (typeof e.data.delayMs === 'number') item.delayMs = e.data.delayMs;
+        retryAt.set(id, out.length);
+        out.push(item);
+      }
+    } else if (e.type === 'llm/retry-started' && e.data && typeof e.data.retryId === 'string' && e.data.retryId !== '' && typeof e.data.retry === 'number') {
+      const id = e.data.retryId;
+      const existing = retryAt.has(id) ? out[retryAt.get(id)] : null;
+      if (existing) existing.status = 'started';
+      else {
+        retryAt.set(id, out.length);
+        out.push({
+          id,
+          kind: 'retry',
+          status: 'started',
+          retry: e.data.retry,
+          maxRetries: typeof e.data.maxRetries === 'number' ? e.data.maxRetries : null,
+          failure: null,
+          seq,
+          time,
+        });
+      }
+    } else if (e.type === 'command/run' && e.data && typeof e.data.commandId === 'string' && e.data.commandId !== '' && typeof e.data.name === 'string') {
+      // 命令行：root 行（running）。同 commandId 重复 run（罕见）只更新位置字段。
+      const id = e.data.commandId;
+      const item = { id, kind: 'command', name: e.data.name, status: 'running', seq, time };
+      const existing = commandAt.has(id) ? out[commandAt.get(id)] : null;
+      if (existing) Object.assign(existing, { status: 'running', seq, time });
+      else {
+        commandAt.set(id, out.length);
+        out.push(item);
+      }
+    } else if (e.type === 'command/done' && e.data && typeof e.data.commandId === 'string' && e.data.commandId !== '') {
+      // 升级同 commandId 行（name 保 run 的）；done 先到（罕见）则按 done 内容建行。
+      const id = e.data.commandId;
+      const done = { kind: 'command', status: 'done', seq, time };
+      if (e.data.kind === 'error' || e.data.kind === 'success') done.resultKind = e.data.kind;
+      if (typeof e.data.text === 'string' && e.data.text !== '') done.text = e.data.text;
+      const existing = commandAt.has(id) ? out[commandAt.get(id)] : null;
+      if (existing) Object.assign(existing, done);
+      else {
+        commandAt.set(id, out.length);
+        out.push(done);
+      }
+    } else if (e.type === 'turn/end' && e.data && e.data.reason && e.data.turn != null) {
+      // turn/end 每轮一次，一条消息只对应一条行：error → turn-error；max-tokens → max-tokens；其余 kind 忽略。
+      if (e.data.reason.kind === 'error') {
+        const err = e.data.reason.error;
+        if (!err || typeof err.message !== 'string') continue;
+        const item = { id: `turn-${e.data.turn}`, kind: 'turn-error', message: err.message, seq, time };
+        if (typeof err.code === 'string' && err.code !== '') item.code = err.code;
+        out.push(item);
+      } else if (e.data.reason.kind === 'max-tokens') {
+        out.push({ id: `turn-${e.data.turn}`, kind: 'max-tokens', seq, time });
+      }
+    }
+    // tool/result、compaction/end 等其余类型照旧忽略（compaction 行已由 start 发出）。
+  }
+  // 严格按事件 seq 升序（与消息混排；compaction 行升级/替换后位置以最终事件为准）。
+  out.sort((a, b) => (a.seq ?? 0) - (b.seq ?? 0));
+  return out;
+}
+
+// 信封拆解的唯一实现在 lib/mobile/envelope.js。这里只是为了让既有
+// `require('./history-derive.js').unwrap` 继续可用（对外导出面不变）。
+const { unwrap } = require('./envelope.js');
+
+const MODEL_UNAVAILABLE_ERROR = {
+  code: 'model-unavailable',
+  message: '当前没有可用的模型，请先在模型选择器中选择一个可用模型',
+};
+
+/**
+ * 宿主错误的 details 原样透传。移动端据此把 attachment-error 映射成中文提示，
+ * 读的是与桌面端 attachmentErrorText 同一个 details.reason 契约
+ * （MODEL_DOES_NOT_SUPPORT_IMAGES / TOO_MANY_IMAGES / IMAGE_TOO_LARGE …）。
+ * 只接受纯对象：Error 实例、数组一律丢弃，避免污染 JSON 响应。
+ */
+function errorDetails(error) {
+  const details = error && typeof error === 'object' ? error.details : undefined;
+  if (!details || typeof details !== 'object' || Array.isArray(details)) return undefined;
+  const proto = Object.getPrototypeOf(details);
+  if (proto !== Object.prototype && proto !== null) return undefined;
+  return details;
+}
+
+function promptErrorObject(error) {
+  if (error && typeof error === 'object') {
+    const code = typeof error.code === 'string' ? error.code : '';
+    const message = typeof error.message === 'string' ? error.message : '';
+    const text = `${code} ${message}`.toLowerCase();
+    if (
+      ['no-model', 'model-unavailable', 'model-not-found', 'model-not-routable', 'no-provider', 'provider-unavailable', 'not-routable'].includes(code.toLowerCase())
+      || /no (?:usable |available |selected |configured )?model|model[^\n]*(?:unavailable|not found|not configured|not routable|missing|required)|no provider|provider[^\n]*(?:unavailable|not found|not configured|missing|required)|没有(?:可用的)?模型|模型[^\n]*(?:不可用|未配置|不存在|缺失|必需)|提供商[^\n]*(?:不可用|未配置|缺失)/i.test(text)
+    ) return { ...MODEL_UNAVAILABLE_ERROR };
+    if (code || message) {
+      const details = errorDetails(error);
+      return {
+        ...(code ? { code } : { code: 'prompt-failed' }),
+        message: message || '消息发送失败',
+        ...(details ? { details } : {}),
+      };
+    }
+  }
+  const message = error instanceof Error ? error.message : String(error || '');
+  const text = message.toLowerCase();
+  if (/no (?:usable |available |selected |configured )?model|no provider|没有(?:可用的)?模型|模型[^\n]*(?:不可用|未配置|不存在|缺失)/i.test(text)) return { ...MODEL_UNAVAILABLE_ERROR };
+  return { code: 'prompt-failed', message: message || '消息发送失败' };
+}
+
+/**
+ * 移动端提示词用的 rpcId 前缀。宿主把 source.rpcId 原样回带在 user 消息上，
+ * 移动端据此把乐观行和历史里的真消息对上号。
+ */
+const MOBILE_PROMPT_RPC_PREFIX = 'mobile:';
+
+/**
+ * 从 user 消息里取回移动端的 clientMessageId。优先用显式字段；老宿主只把它塞在
+ * source.rpcId 里，两条路都认，历史重同步才不会把乐观行变成重复行。
+ */
+function clientMessageIdFromSource(source, message) {
+  if (message && typeof message.clientMessageId === 'string' && message.clientMessageId) return message.clientMessageId;
+  if (!source || typeof source !== 'object' || source.kind !== 'user' || typeof source.rpcId !== 'string') return undefined;
+  return source.rpcId.startsWith(MOBILE_PROMPT_RPC_PREFIX)
+    ? source.rpcId.slice(MOBILE_PROMPT_RPC_PREFIX.length) || undefined
+    : undefined;
+}
+
+module.exports = {
+  listTitle,
+  deriveMessages,
+  unwrap,
+  errorDetails,
+  promptErrorObject,
+  MODEL_UNAVAILABLE_ERROR,
+  capDiffText,
+  normalizeResultDiffs,
+  buildToolResultMap,
+  parseBlocks,
+  blocksToText,
+  contextLabelOf,
+  lastMessageOf,
+  MOBILE_PROMPT_RPC_PREFIX,
+  clientMessageIdFromSource,
+};