dsh-mobile-plugin 0.4.9 → 0.5.0

package/lib/mobile/history-derive.js

@@ -12,6 +12,11 @@
  */
 
 const { cutAssistantBlock, cutToolResultEvent, createToolNameIndex } = require('./wire-cut.js');
+const {
+  reasoningStepSummary,
+  toolStepSummary,
+  toolStepState,
+} = require('./step-index.js');
 
 /**
  * 从 session.list 摘要行取会话标题（与桌面端侧栏同源，不再从 history 窗口猜）：
@@ -117,7 +122,14 @@ function buildToolResultMap(events) {
       return '';
     }).filter(Boolean).join('');
     const images = toolResultImages(parts);
-    map.set(src.callId, { isError, code, ...(output ? { output } : {}), ...(images.length ? { images } : {}) });
+    // `seq` 只给「按需取详情」用：手机点开这一步时拿它去回拉那一小窗事件。
+    map.set(src.callId, {
+      isError,
+      code,
+      ...(Number.isSafeInteger(e.seq) ? { seq: e.seq } : {}),
+      ...(output ? { output } : {}),
+      ...(images.length ? { images } : {}),
+    });
   }
   return map;
 }
@@ -428,8 +440,59 @@ function deriveMessages(events) {
   // 命令行按 commandId 唯一：command/run 发出行，command/done 原地升级（保 run 的 name，位置随 done 事件 seq 归位）。
   const commandAt = new Map();
 
+  /**
+   * 每一轮的「过程清单」：一步一行摘要，正文仍然一个字节都不下发。
+   *
+   * 清单挂在**这一轮开头那条消息**上（App 的头条行就是它派生的），收口后点开清单再按
+   * `seq` / `resultSeq` 去 `/session/step` 取那一步的详情 —— 这就是「按需获取」的那一半。
+   * 只做摘要不做正文：一条推理正文平均几万字、一次 `write` 的参数就是整份文件，把它们
+   * 塞进消息响应里正是 2026-10-27 砍掉它的理由。
+   */
+  const stepsByTurn = new Map();
+  const openerByTurn = new Map();
+  let lastOpener = null;
+  const collectSteps = (content, e) => {
+    if (!Array.isArray(content)) return;
+    const turn = e.data && typeof e.data.turn === 'number' ? e.data.turn : undefined;
+    if (turn === undefined) return;
+    if (!openerByTurn.has(turn) && lastOpener) openerByTurn.set(turn, lastOpener);
+    const list = stepsByTurn.get(turn) || [];
+    content.forEach((raw, index) => {
+      if (!raw || typeof raw !== 'object') return;
+      if (raw.type === 'reasoning') {
+        const text = typeof raw.text === 'string' ? raw.text : '';
+        // 空推理块（只有零宽字符那种）不算一步：App 点开一条什么都没有的行没有意义。
+        if (text.trim() === '') return;
+        list.push({
+          kind: 'think',
+          ...(Number.isSafeInteger(e.seq) ? { seq: e.seq } : {}),
+          index,
+          summary: reasoningStepSummary(text),
+        });
+        return;
+      }
+      if (raw.type !== 'tool-call') return;
+      const callId = raw.id != null ? String(raw.id) : undefined;
+      const result = callId ? toolResults.get(callId) : undefined;
+      const rawArgs = typeof raw.arguments === 'string'
+        ? raw.arguments
+        : (raw.arguments != null ? JSON.stringify(raw.arguments) : '');
+      list.push({
+        kind: 'tool',
+        ...(callId ? { callId } : {}),
+        ...(typeof raw.name === 'string' && raw.name ? { name: raw.name } : {}),
+        summary: toolStepSummary(raw.name, rawArgs),
+        state: toolStepState(result),
+        ...(Number.isSafeInteger(e.seq) ? { seq: e.seq } : {}),
+        ...(result && Number.isSafeInteger(result.seq) ? { resultSeq: result.seq } : {}),
+      });
+    });
+    if (list.length > 0) stepsByTurn.set(turn, list);
+  };
+
   // 普通消息（user/assistant）沿用原折叠逻辑。
   const pushMessage = (msg, e) => {
+    collectSteps(msg.content, e);
     const parsed = parseBlocks(msg.content, toolResults);
     // 工具产出的图挂成这条消息的图片附件：App 把它画在气泡上方（缩略图 + 文件名，点开全屏），
     // 与用户自己发的图同一种形状。工具卡里不再重复画同一张图 —— 一张图两处画会把字节也翻倍。
@@ -501,6 +564,8 @@ function deriveMessages(events) {
       if (timing) item.timing = timing;
     }
     out.push(item);
+    // 这一轮的过程清单挂在**开启这一轮的那条消息**上：App 的头条行按它派生。
+    if (item.role === 'user') lastOpener = item;
   };
 
   // 放入一行 compaction：同一 compactionId 只保留一行，检查点行原地替换 start 行（最终按 seq 排序归位）。
@@ -747,6 +812,19 @@ function deriveMessages(events) {
     }
     // tool/result 等其余类型照旧忽略（工具结果在预扫描里配对回填；compaction 行由 start/end 发出）。
   }
+  // 过程清单按轮回填：`steps` 只带摘要与位置，正文要用户点开某一步时再去取。
+  if (stepsByTurn.size > 0) {
+    for (const [turn, steps] of stepsByTurn) {
+      const opener = openerByTurn.get(turn);
+      if (!opener || steps.length === 0) continue;
+      opener.turnProcess = {
+        ...(opener.turnProcess && typeof opener.turnProcess === 'object' ? opener.turnProcess : {}),
+        count: steps.length,
+        steps,
+        ...(Number.isSafeInteger(opener.seq) ? { startSeq: opener.seq } : {}),
+      };
+    }
+  }
   // 产出清单按轮回填：这一轮所有 write / edit 的并集，挂到这一轮每条 assistant 消息上。
   // 挂「整轮」而不是「从写那一刻起」，与桌面 `selectProducedFiles(owner)` 同口径；正文里
   // 提到这一轮写的文件就能解析成可点（App 侧按文件名或整条路径唯一命中才画，见
@@ -869,13 +947,19 @@ function thinEntryMessages(items, options = {}) {
       const endSeq = Number.isSafeInteger(last.seq) ? last.seq : opener.seq;
       const at = kept.indexOf(opener);
       if (at >= 0) {
+        // 清单（`steps`）随入口窗口一起下发：过程正文不在线上，这一行摘要就是用户
+        // 「值不值得点开」的全部依据，摘掉它这一轮就没法点开了。
+        const steps = opener.turnProcess && Array.isArray(opener.turnProcess.steps)
+          ? opener.turnProcess.steps
+          : null;
         kept[at] = {
           ...kept[at],
           turnProcess: {
             startSeq: opener.seq,
             endSeq,
-            count: processCount,
+            count: steps ? steps.length : processCount,
             ...(typeof last.time === 'number' ? { endTime: last.time } : {}),
+            ...(steps ? { steps } : {}),
           },
         };
       }

package/lib/mobile/host-settings.js

@@ -16,6 +16,9 @@ const { unwrap } = require('./sessions.js');
 
 const HOST_SETTINGS_MAX_NAMESPACES = 60; // 命名空间数量上限（避免异常宿主把响应撑爆）
 const HOST_SETTINGS_MAX_MODELS_PER_GROUP = 200; // 单个提供方下的模型条数上限
+const HOST_SETTINGS_MAX_FIELDS = 40;     // 单个命名空间透出的字段元数据条数上限
+const HOST_SETTINGS_MAX_CHOICES = 40;    // 单个字段的候选值上限
+const HOST_SETTINGS_MAX_EFFORTS = 8;     // 单个模型的推理强度档位上限
 const HOST_SETTINGS_VALUE_DEPTH = 4;     // 值递归深度上限
 const HOST_SETTINGS_VALUE_KEYS = 40;     // 每层键/元素数量上限
 const HOST_SETTINGS_VALUE_CHARS = 4000;  // 单个字符串长度上限
@@ -51,6 +54,21 @@ function boundValue(value, depth = 0) {
   return null;
 }
 
+/**
+ * 取出序列化 zod 树的根字段表。
+ *
+ * 宿主 `settings.describe` 里的 schema 是 schemastery 的 `{ uid, refs }` 形状：refs 以数字 id
+ * 存放每个节点，根节点的 `dict` 是「字段名 → 子节点 id」。凭据引用与字段控件都要先摸到这张表。
+ */
+function schemaDict(schema) {
+  const refs = schema && typeof schema === 'object' && !Array.isArray(schema) ? schema.refs : null;
+  if (!refs || typeof refs !== 'object' || Array.isArray(refs)) return null;
+  const root = refs[String(schema.uid)];
+  const dict = root && typeof root === 'object' ? root.dict : null;
+  if (!dict || typeof dict !== 'object' || Array.isArray(dict)) return null;
+  return { refs, dict };
+}
+
 /**
  * 从序列化的 zod 树里读出「这个命名空间的密钥写到哪个凭据引用上」。
  *
@@ -62,11 +80,9 @@ function boundValue(value, depth = 0) {
  * 没有密钥槽的设置项画密码框。
  */
 function credentialRefOf(schema, value) {
-  const refs = schema && typeof schema === 'object' && !Array.isArray(schema) ? schema.refs : null;
-  if (!refs || typeof refs !== 'object' || Array.isArray(refs)) return null;
-  const root = refs[String(schema.uid)];
-  const dict = root && typeof root === 'object' ? root.dict : null;
-  if (!dict || typeof dict !== 'object' || Array.isArray(dict)) return null;
+  const shape = schemaDict(schema);
+  if (!shape) return null;
+  const { refs, dict } = shape;
 
   let refField = '';
   let refDefault = '';
@@ -90,6 +106,65 @@ function credentialRefOf(schema, value) {
   return ref ? { ref, refField } : null;
 }
 
+/**
+ * 一个字段该画什么控件，按宿主 schema 的形状定。
+ *
+ * 手机端把设置项直接铺成卡片，靠这张表决定控件，不再一律给文本框：
+ * - `boolean` → 开关
+ * - `union` 且每一支都是常量（`z.union(['standard', 'compact'])`）→ 点选，候选就是那些常量
+ * - `number` → 数字输入（带宿主的 min / max / step）
+ * - `string` → 文本框
+ *
+ * 其它形状（嵌套对象 / 数组 / transform）不出现：那种字段在手机上本来就不给控件。只描述
+ * 根那一层的字段，不透整棵树——宿主 schema 里对手机没用的东西仍然留在插件这一侧。
+ */
+function describeField(node, refs) {
+  const meta = node && typeof node === 'object' && node.meta && typeof node.meta === 'object' ? node.meta : {};
+  let type = '';
+  const out = {};
+  if (node && node.type === 'boolean') type = 'boolean';
+  else if (node && node.type === 'string') type = 'string';
+  else if (node && node.type === 'number') {
+    type = 'number';
+    if (typeof meta.min === 'number' && Number.isFinite(meta.min)) out.min = meta.min;
+    if (typeof meta.max === 'number' && Number.isFinite(meta.max)) out.max = meta.max;
+    if (typeof meta.step === 'number' && Number.isFinite(meta.step)) out.step = meta.step;
+  } else if (node && node.type === 'const') {
+    type = 'enum';
+    out.options = [node.value];
+  } else if (node && node.type === 'union') {
+    // 只有「每一支都是常量」才算候选集合；带 transform / 对象的联合没法枚举。
+    const options = [];
+    const list = Array.isArray(node.list) ? node.list : [];
+    let allConst = list.length > 0;
+    for (const uid of list) {
+      const child = refs[String(uid)];
+      if (child && child.type === 'const') options.push(child.value);
+      else { allConst = false; break; }
+    }
+    if (!allConst) return null;
+    type = 'enum';
+    out.options = options.slice(0, HOST_SETTINGS_MAX_CHOICES);
+  } else return null;
+  if (type === 'enum' && (!Array.isArray(out.options) || out.options.length < 2)) return null;
+  if (meta.required === true) out.required = true;
+  out.type = type;
+  return out;
+}
+
+/** 一个命名空间里各字段的控件形状；推不出来（老宿主 / 畸形 schema）就是 null。 */
+function fieldsOf(schema) {
+  const shape = schemaDict(schema);
+  if (!shape) return null;
+  const fields = [];
+  for (const key of Object.keys(shape.dict).slice(0, HOST_SETTINGS_MAX_FIELDS)) {
+    const node = shape.refs[String(shape.dict[key])];
+    const field = describeField(node, shape.refs);
+    if (field) fields.push({ key, ...field });
+  }
+  return fields.length > 0 ? fields : null;
+}
+
 /**
  * 把 settings.describe 的一条命名空间视图压成手机需要的形状。
  *
@@ -124,6 +199,10 @@ function normalizeNamespace(item) {
   };
   if (item.base !== undefined) out.base = boundValue(item.base);
   if (item.user !== undefined) out.user = boundValue(item.user);
+  // 每个字段该画什么控件（开关 / 点选 / 数字 / 文本框）：只描述根这一层，宿主整棵 schema 的
+  // 其余部分仍然留在插件这一侧，不透给手机。推不出来就不给，App 回退成文本框。
+  const fields = fieldsOf(item.schema);
+  if (fields) out.fields = fields;
   // 只有「宿主确实报了密钥槽」且「schema 里能推导出凭据引用」时才给出引用名；
   // 两者缺一，App 就不该显示写密钥的入口。
   if (secrets.length > 0) {
@@ -181,6 +260,21 @@ async function handleLlmProviders(ctx, req, res) {
   sendJson(res, 200, { ok: true, providers });
 }
 
+/**
+ * 一个模型支持的推理强度档位。
+ *
+ * 宿主给的是一张「id → 显示名」的表（如 `{ low: 'low', high: 'high', max: 'max' }`），偶尔是
+ * 数组。手机只要档位 id：设置里写的是 id，显示名归 App 的字典。没有就返回空数组。
+ */
+function normalizeReasoningEfforts(value) {
+  const ids = Array.isArray(value)
+    ? value
+    : (value && typeof value === 'object' && !Array.isArray(value) ? Object.keys(value) : []);
+  return ids
+    .filter((id) => typeof id === 'string' && id !== '')
+    .slice(0, HOST_SETTINGS_MAX_EFFORTS);
+}
+
 /** 把 llm.models 的一组渠道压成手机选择器要的形状；没有模型的组丢掉。 */
 function normalizeModelGroup(group) {
   if (!group || typeof group !== 'object') return null;
@@ -193,7 +287,10 @@ function normalizeModelGroup(group) {
       const id = typeof item.id === 'string' ? item.id.trim() : '';
       if (!id) return null;
       const name = typeof item.name === 'string' && item.name.trim() ? item.name.trim() : id;
-      return { id, name };
+      // 推理强度档位给设置页里的「推理强度」用：那个字段在宿主 schema 里只是普通字符串，
+      // 唯一知道有哪些档位的地方就是模型目录这一份。
+      const reasoningEfforts = normalizeReasoningEfforts(item.reasoningEfforts);
+      return { id, name, ...(reasoningEfforts.length > 0 ? { reasoningEfforts } : {}) };
     })
     .filter(Boolean)
     .slice(0, HOST_SETTINGS_MAX_MODELS_PER_GROUP);

package/lib/mobile/live-steps.js

@@ -0,0 +1,356 @@
+'use strict';
+
+/**
+ * 直播时那一轮的过程副本：**只在内存里**，收下一轮就换掉。
+ *
+ * 为什么需要它：录制里的推理正文与工具参数在落盘之前只存在于直播流里，宿主的
+ * `session.history` 取不到跑到一半的那一步 —— 用户点开「正在读取文件」这一行时，
+ * 详情接口只能从这份副本里答。落定以后按 `seq` 回拉历史，这份副本就不必再管。
+ *
+ * 它同时是**跑着那一轮的过程清单**：手机上那条「过程 · 已跑 3 步」要每一行一步的摘要，
+ * 而推理块整块不上线路、工具参数也不上（见 `wire-cut.js`），所以摘要与状态只能在这里
+ * 算好再按步发出去（`drainLiveSteps` → `session/live-steps` 帧）。**摘要由电脑算**
+ * 这条不变：手机上根本没有参数可拼。
+ *
+ * 容量口径：只留**当前这一轮**（`turn/start` 覆盖），整个进程里最多留几条会话。它复制
+ * 的本就是宿主此刻正在攒的东西，所以量级与「这一轮有多长」同一档，收口后不再增长。
+ */
+
+/** 进程里同时留几条会话的直播副本（多开的会话不会一起跑，留几条够来回切）。 */
+const MAX_SESSIONS = 4;
+
+/** 单段文本的上限：详情是给人看的，超长输出照旧截断，别把一份 20MB 的结果塞回手机。 */
+const TEXT_MAX = 200_000;
+
+const { liveStepTurnOf } = require('./session-cache.js');
+const { reasoningStepSummary, toolStepSummary } = require('./step-index.js');
+
+function bucketOf(ctx) {
+  return liveStepTurnOf(ctx);
+}
+
+function turnOf(ctx, sessionId) {
+  const bucket = bucketOf(ctx);
+  let turn = bucket.get(sessionId);
+  if (!turn) {
+    turn = {
+      tools: new Map(),
+      /** 推理正文：键是**这一轮里的第几段思考**（不是内容块序号，块序号每步从 0 重数）。 */
+      thoughts: new Map(),
+      /** 内容块序号 → 那一段思考的编号（只在当前这一步内有效，落定即清）。 */
+      thoughtOfBlock: new Map(),
+      nextThought: 0,
+      callIdByIndex: new Map(),
+      activeCallId: '',
+      /** 这一轮跑过的步（按发生顺序），一步一条，`key` 是它在 App 侧的稳定身份。 */
+      steps: [],
+      stepByKey: new Map(),
+      /** 还没发出去的那几步（`drainLiveSteps` 取走）。 */
+      pending: [],
+      ended: false,
+    };
+    bucket.delete(sessionId);
+    bucket.set(sessionId, turn);
+    // 只留几条会话（Map 按插入顺序，最老的先丢）。
+    while (bucket.size > MAX_SESSIONS) bucket.delete(bucket.keys().next().value);
+  }
+  return turn;
+}
+
+/** 把一段文本接到已有的那段后面，超过上限就只留尾巴。 */
+function appendText(prev, next) {
+  if (typeof next !== 'string' || next === '') return prev || '';
+  const joined = (prev || '') + next;
+  return joined.length > TEXT_MAX ? joined.slice(joined.length - TEXT_MAX) : joined;
+}
+
+/**
+ * 记一步：没有就追加到清单末尾，有就改它（同一处只占一条）。
+ *
+ * 只有**真的变了**的那个字段才进待发清单 —— 工具身份帧会来好几发，每发都推送一遍等于
+ * 把同一行反复发给你。
+ */
+function putStep(turn, key, patch) {
+  let entry = turn.stepByKey.get(key);
+  if (!entry) {
+    entry = { key, step: {} };
+    turn.stepByKey.set(key, entry);
+    turn.steps.push(entry);
+    Object.assign(entry.step, patch);
+    turn.pending.push({ key, step: { ...entry.step } });
+    return entry;
+  }
+  const before = entry.step;
+  const changed = Object.keys(patch).some((field) => patch[field] !== before[field]);
+  if (changed) {
+    Object.assign(entry.step, patch);
+    turn.pending.push({ key, step: { ...entry.step } });
+  }
+  return entry;
+}
+
+function toolKey(callId) {
+  return `tool:${callId}`;
+}
+
+function thinkKey(ordinal) {
+  return `think:${ordinal}`;
+}
+
+/**
+ * 工具步的摘要与状态：摘要参数齐了才拼（读到哪算哪的一行「读文件」等于没写）。
+ *
+ * `error` 是**三态**：没有这一格 = 结果还没来（还在跑）；`null` = 结果到了、成功了；
+ * `'error'` / `'stopped'` = 结果到了、失败了。别把 `null` 当成「还在跑」。
+ */
+function refreshToolStep(turn, callId) {
+  const tool = turn.tools.get(callId);
+  if (!tool) return;
+  const summary = toolStepSummary(tool.name, tool.argsRaw);
+  const state = tool.error === undefined
+    ? 'running'
+    : (tool.error === null ? 'ok' : (tool.error === 'stopped' ? 'stopped' : 'error'));
+  putStep(turn, toolKey(callId), {
+    kind: 'tool',
+    callId,
+    ...(tool.name ? { name: tool.name } : {}),
+    summary,
+    state,
+  });
+}
+
+/** 一段思考落定：摘要补上，状态收成成功。 */
+function settleThought(turn, ordinal) {
+  const text = turn.thoughts.get(ordinal);
+  if (typeof text !== 'string' || text === '') {
+    putStep(turn, thinkKey(ordinal), { state: 'ok' });
+    return;
+  }
+  putStep(turn, thinkKey(ordinal), { summary: reasoningStepSummary(text), state: 'ok' });
+}
+
+/** 这一步的所有思考都收尾（一步的块序号只在这一步内有效，落定即清）。 */
+function closeThoughtsOfStep(turn) {
+  for (const ordinal of turn.thoughtOfBlock.values()) settleThought(turn, ordinal);
+  turn.thoughtOfBlock.clear();
+}
+
+/** 工具结果两种形状都认（与 history-derive 的 toolResultParts 同一口径）。 */
+function resultParts(message) {
+  const direct = Array.isArray(message.content) ? message.content : [];
+  const envelope = direct.length === 1 && direct[0] && typeof direct[0] === 'object'
+    && typeof direct[0].type !== 'string' ? direct[0] : null;
+  if (!envelope) return { parts: direct, isError: message.isError === true };
+  return {
+    parts: Array.isArray(envelope.content) ? envelope.content : [],
+    isError: envelope.isError === true || message.isError === true,
+  };
+}
+
+/**
+ * 收一帧直播事件（在 `wire-cut` 之前看原始内容，所以这里什么都拿得到）。
+ *
+ * 只有这几类事件有料：工具参数增量、推理增量、块边界、助手消息、工具结果、回合结束。
+ * 其余一概忽略。
+ */
+function noteLiveEvent(ctx, sessionId, event) {
+  if (!ctx || typeof sessionId !== 'string' || !sessionId) return;
+  if (!event || typeof event !== 'object') return;
+  const data = event.data && typeof event.data === 'object' ? event.data : null;
+  if (event.type === 'turn/start') {
+    // 新的一轮开始：上一轮的过程副本作废（换掉了，就别再让人点开旧内容）。
+    bucketOf(ctx).delete(sessionId);
+    turnOf(ctx, sessionId);
+    return;
+  }
+  if (!data) return;
+  const turn = turnOf(ctx, sessionId);
+  if (event.type === 'assistant/message') {
+    // 一步落定：这一步的思考按块序号收尾（后面那一步的块序号从 0 重新数）。
+    closeThoughtsOfStep(turn);
+    // 块序号 → 调用 的对照也随之作废：下一步的 0 号块是另一个块，留着它会让一条正文
+    // 的块边界把上一步的工具重新标成「运行中」。
+    turn.callIdByIndex.clear();
+    turn.activeCallId = '';
+    const message = data.message;
+    const content = message && Array.isArray(message.content) ? message.content : [];
+    for (const block of content) {
+      if (!block || block.type !== 'tool-call' || block.id == null) continue;
+      const callId = String(block.id);
+      const current = turn.tools.get(callId) || { name: '', argsRaw: '' };
+      // 参数到这里是齐的 —— 摘要该按它拼出来了。身份帧可能在断线 / 合并里丢过，
+      // 所以这里也顺手把这一步补进清单（有就只更新）。
+      turn.tools.set(callId, {
+        name: typeof block.name === 'string' && block.name ? block.name : current.name,
+        argsRaw: typeof block.arguments === 'string'
+          ? block.arguments
+          : (block.arguments != null ? JSON.stringify(block.arguments) : current.argsRaw),
+      });
+      refreshToolStep(turn, callId);
+    }
+    return;
+  }
+  if (event.type === 'assistant/chunk') {
+    const chunk = data.chunk;
+    if (!chunk || typeof chunk !== 'object') return;
+    if (chunk.type === 'tool-call-delta') {
+      // 宿主只在**第一帧**带 `id` / `name`，后面那些帧只剩 `index` 与 `argumentsDelta`
+      // （见 wire-cut.js 的同一条注释）。所以按块序号记住「这个 index 是哪个调用」，
+      // 没有 id 的帧接到上一次那个调用上；一步里并行两个调用时按 index 各归各的。
+      const index = Number.isSafeInteger(chunk.index) ? chunk.index : null;
+      let callId = chunk.id != null ? String(chunk.id) : '';
+      if (callId) {
+        turn.activeCallId = callId;
+        if (index !== null) turn.callIdByIndex.set(index, callId);
+      } else if (index !== null && turn.callIdByIndex.has(index)) {
+        callId = turn.callIdByIndex.get(index);
+      } else if (turn.activeCallId) {
+        callId = turn.activeCallId;
+      }
+      if (!callId) return;
+      const current = turn.tools.get(callId) || { name: '', argsRaw: '' };
+      turn.tools.set(callId, {
+        name: typeof chunk.name === 'string' && chunk.name ? chunk.name : current.name,
+        argsRaw: appendText(current.argsRaw, chunk.argumentsDelta),
+        ...(current.output !== undefined ? { output: current.output } : {}),
+        ...(current.diffs !== undefined ? { diffs: current.diffs } : {}),
+        ...(current.error !== undefined ? { error: current.error } : {}),
+      });
+      // 参数还在流：这一步照实说「运行中」，摘要等参数齐了再补。
+      const tool = turn.tools.get(callId);
+      putStep(turn, toolKey(callId), {
+        kind: 'tool',
+        callId,
+        ...(tool.name ? { name: tool.name } : {}),
+        summary: '',
+        state: 'running',
+      });
+      return;
+    }
+    if (chunk.type === 'reasoning-delta') {
+      if (!Number.isSafeInteger(chunk.index)) return;
+      let ordinal = turn.thoughtOfBlock.get(chunk.index);
+      if (ordinal === undefined) {
+        ordinal = turn.nextThought;
+        turn.nextThought += 1;
+        turn.thoughtOfBlock.set(chunk.index, ordinal);
+        turn.thoughts.set(ordinal, '');
+        // **思考也算一步**：从第一段推理就开始算，不必等到它调工具。
+        putStep(turn, thinkKey(ordinal), { kind: 'think', index: ordinal, summary: '', state: 'running' });
+      }
+      turn.thoughts.set(ordinal, appendText(turn.thoughts.get(ordinal), chunk.text));
+      return;
+    }
+    if (chunk.type === 'block-end') {
+      const index = Number.isSafeInteger(chunk.index) ? chunk.index : null;
+      if (index === null) return;
+      const callId = turn.callIdByIndex.get(index);
+      if (callId) {
+        // 参数流完了（接下来才是执行）：这一刻的摘要就是用户要看的那个路径 / 命令。
+        refreshToolStep(turn, callId);
+        return;
+      }
+      const ordinal = turn.thoughtOfBlock.get(index);
+      if (ordinal !== undefined) {
+        settleThought(turn, ordinal);
+        turn.thoughtOfBlock.delete(index);
+      }
+    }
+    return;
+  }
+  if (event.type === 'tool/result') {
+    const message = data.message;
+    const src = message && message.source;
+    if (!src || typeof src.callId !== 'string') return;
+    const current = turn.tools.get(src.callId) || { name: '', argsRaw: '' };
+    const { parts, isError } = resultParts(message);
+    const output = parts
+      .map((part) => (part && typeof part.text === 'string' ? part.text : ''))
+      .filter(Boolean)
+      .join('');
+    const diffs = data.meta && Array.isArray(data.meta.diffs) ? data.meta.diffs : undefined;
+    const code = data.error && typeof data.error.code === 'string' ? data.error.code : undefined;
+    // 失败有两种写法：`message.isError` 与 `data.error.code`（宿主两种都发过），任一都算失败。
+    const failed = isError || code !== undefined;
+    turn.tools.set(src.callId, {
+      ...current,
+      output: output.length > TEXT_MAX ? output.slice(0, TEXT_MAX) : output,
+      ...(failed ? { error: code === 'interrupted' ? 'stopped' : 'error' } : { error: null }),
+      ...(diffs ? { diffs } : {}),
+    });
+    refreshToolStep(turn, src.callId);
+    return;
+  }
+  if (event.type === 'turn/end') {
+    turn.ended = true;
+    // 这一轮收口：还在跑的那几步按成功收尾（宿主不会再补一条结果给它们）。
+    closeThoughtsOfStep(turn);
+    for (const [callId, tool] of turn.tools) {
+      if (tool.error === undefined) putStep(turn, toolKey(callId), { state: 'ok' });
+    }
+  }
+}
+
+/**
+ * 这一轮到目前为止跑过的步（App 侧的过程清单）。
+ *
+ * 只给「一行摘要 + 状态 + 位置」：正文一个字节都不在这里，点开某一步才走 `/session/step`。
+ */
+function liveStepsOf(ctx, sessionId) {
+  if (!ctx || typeof sessionId !== 'string' || !sessionId) return [];
+  const turn = liveStepTurnOf(ctx).get(sessionId);
+  if (!turn) return [];
+  return turn.steps.map((entry) => ({ key: entry.key, step: { ...entry.step } }));
+}
+
+/**
+ * 取走「还没告诉过手机」的那几步。
+ *
+ * 每条都是 `{ key, step }`：新的一步就是追加，同一步的状态变化就是按 `key` 替换。
+ */
+function drainLiveSteps(ctx, sessionId) {
+  if (!ctx || typeof sessionId !== 'string' || !sessionId) return [];
+  const turn = liveStepTurnOf(ctx).get(sessionId);
+  if (!turn || turn.pending.length === 0) return [];
+  const out = turn.pending.slice();
+  turn.pending.length = 0;
+  return out;
+}
+
+/**
+ * 取一步的直播详情；没有这一份（换了一轮、或这一步已经落盘）返回 null，由调用方转历史。
+ */
+function liveStepOf(ctx, sessionId, query) {
+  if (!ctx || typeof sessionId !== 'string' || !sessionId) return null;
+  const bucket = liveStepTurnOf(ctx);
+  const turn = bucket.get(sessionId);
+  if (!turn) return null;
+  if (query && query.kind === 'think') {
+    const index = Number.isSafeInteger(query.index) ? query.index : null;
+    if (index === null) return null;
+    const text = turn.thoughts.get(index);
+    if (typeof text !== 'string' || text === '') return null;
+    return { kind: 'think', text, live: true, state: turn.ended ? 'ok' : 'running' };
+  }
+  const callId = query && typeof query.callId === 'string' ? query.callId : '';
+  if (!callId) return null;
+  const tool = turn.tools.get(callId);
+  if (!tool) return null;
+  const state = tool.error === undefined ? (turn.ended ? 'ok' : 'running') : (tool.error || 'ok');
+  return {
+    kind: 'tool',
+    live: true,
+    ...(tool.name ? { name: tool.name } : {}),
+    state,
+    ...(tool.argsRaw ? { argsRaw: tool.argsRaw } : {}),
+    ...(typeof tool.output === 'string' && tool.output ? { output: tool.output } : {}),
+    ...(Array.isArray(tool.diffs) && tool.diffs.length > 0 ? { diffs: tool.diffs } : {}),
+  };
+}
+
+/** 丢掉一条会话的直播副本（会话关掉、或者换设备时用）。 */
+function clearLiveSteps(ctx, sessionId) {
+  liveStepTurnOf(ctx).delete(sessionId);
+}
+
+module.exports = { noteLiveEvent, liveStepOf, liveStepsOf, drainLiveSteps, clearLiveSteps };