dsh-mobile-plugin 0.0.0-stage → 0.1.58

package/lib/mirror-snapshot.cjs

@@ -0,0 +1,39 @@
+'use strict'
+
+// 桌面推送的「移动端镜像快照」新鲜度判定。这一个小模块独立存在，是为了能被 test/ 直接驱动
+// （与 reconnect-scheduler.cjs 同样的做法），而不是把判定散在 sidecar 的读取函数里。
+//
+// 背景（真机缺陷）：sidecar 把 /sessions、/workspaces 两个高频读请求直接从这份镜像回，
+// 不去打扰主进程。但镜像**只能靠隧道推来**：
+//   - host 侧 pushMirrorPayload 在 `!tunnelConnected()` 时直接短路（lib/index.js:132）；
+//   - 它依赖的 sidecar `/tunnel/send` 自己也要求 `tunnel && tunnel.connected`，否则 503
+//     （sidecar-facade-worker.cjs:186-190）。
+// 于是「中转断掉、局域网仍然健康」时快照被永久冻结在最后一个版本，而 snapshotRead 依旧把
+// 它当权威读：新建的会话/工作区在 App 里**永远不出现**。实测证据（Mac 宿主，kill 掉中转后
+// 走局域网新建并发送）：
+//   POST /session/new → session-1c9b048a-…，POST /session/send → {"ok":true,"accepted":true}
+//   GET /sessions    → count 9（与 kill 之前一模一样），新会话 absent，+70s 仍 absent
+//   GET /app         → 设备侧同样看不到
+//   GET /session/messages?sessionId=<新的> → 能读到 user 'SNAPSHOT-STALE-1'
+// 最后一条说明回源主进程的通道是好的（快照里没有这个 sessionId 就自然回源），坏的只是
+// 「列表类读被冻结的镜像顶掉」。
+//
+// 修法：把镜像当**短时代读缓存**，不是权威存储——超过 TTL 就当作缺失，让调用方回源主进程。
+// 隧道连着时快照每几百毫秒就被重推一次（processBgQueue 的 500ms tick），所以 15s 足够长，
+// 快路径照常生效；一旦中转断开，最多 15s 后所有读都回源，数据重新变准。
+
+const MIRROR_SNAPSHOT_TTL_MS = 15_000
+
+// 只有带可信时间戳 `at` 且在 TTL 内的快照才可用。
+// 缺 `at` 的载荷一律按陈旧处理：host 的三个推送点（lib/index.js:212 / :267 / :302）都会写
+// `at: Date.now()`，没有 `at` 说明这不是预期的镜像载荷，宁可回源也不要拿它当权威。
+// 时间戳来自同一台机器，不存在跨机时钟偏移，所以未来时间戳按不可信处理。
+function isMirrorSnapshotFresh(snapshot, now = Date.now()) {
+  if (!snapshot || typeof snapshot !== 'object') return false
+  const at = snapshot.at
+  if (typeof at !== 'number' || !Number.isFinite(at) || at <= 0) return false
+  const age = now - at
+  return age >= 0 && age <= MIRROR_SNAPSHOT_TTL_MS
+}
+
+module.exports = { MIRROR_SNAPSHOT_TTL_MS, isMirrorSnapshotFresh }

package/lib/mobile/agent-presets.js

@@ -0,0 +1,182 @@
+'use strict';
+
+/**
+ * 移动端「Agent 预设管理」API：把桌面端设置页里那个预设管理分区补齐到手机上。
+ *
+ * 桌面端由 dsh-client-ui-agent-preset 渲染四个表层，本仓库此前只补了前三个：
+ *  1. 设置里的一行 / 新建会话芯片  → 手机：**已下线**。App 侧曾有一颗 composer 的
+ *     AgentPresetChip（list + select），现已整颗删除 —— 手机端一律吃宿主默认档，
+ *     `POST /session/select-agent-preset` 路由也一并删除（消费端没了就是死路由）。
+ *  2. 会话标题旁的只读标签        → 手机：随 1 一起下线
+ *  3. 名单本身                    → 手机：GET /agent-presets
+ *  4. **管理分区**：名单卡片 + 只读查看器 + 复制对话框 + 删除确认
+ *     —— 这才是现在手机上唯一与预设有关的界面（app 的 PresetManager）。
+ *
+ * 三跳接口（都只是转发宿主的 agentPreset 域，转发函数在 lib/mobile/rpc.js，
+ * 与会话域的 callSessions 住在一起）：
+ *  - POST /agent-presets/read   { agentPreset }               → agentPreset.read
+ *  - POST /agent-presets/copy   { from, agentPreset, name? }  → agentPreset.copy
+ *  - POST /agent-presets/remove { agentPreset }               → agentPreset.remove
+ *
+ * 语义按宿主原文透传，不在这里自作主张：
+ *  - copy 是「整份复制」，标识符会成为目录名且事后无法更改；宿主自己会重校验 id
+ *    规则与重名（PresetExistsError → agent-preset-invalid），这里只做便利检查。
+ *  - remove 只对 user 预设有效：随附预设宿主回 agent-preset-read-only，删不掉。
+ *  - openDocument 不做。它打开的是**宿主机器**上的目录（与 host.openPath 同性质），
+ *    手机点了也看不见；桌面端在没有打开器时（hasDocument:false）本来就是把目录
+ *    当文本显示，手机端照此办理即可，不需要这条 RPC。
+ *
+ * 宿主的失败对象是「code + details」：not-found 带 available[]、read-only 带 reason、
+ * invalid 带 reason（可能是 id 非法，也可能是重名），都不是给用户看的文案；
+ * 按 code 说中文，同时把原文留在 details.hostMessage 里备查。
+ */
+
+const { sendJson, readJsonBody } = require('../shared/http-util');
+// apiProxy 的回执信封拆解在 lib/mobile/envelope.js（唯一实现）。
+const { unwrap } = require('./envelope.js');
+const { callAgentPresets } = require('./rpc.js');
+
+const PRESET_ID_MAX_CHARS = 64;          // 宿主的目录名上限远大于此，这里只是防呆
+const PRESET_NAME_MAX_CHARS = 200;       // 显示名上限
+const PRESET_BODY_MAX_CHARS = 256 * 1024; // 预设正文（YAML + 文档）字符数兜底
+const PRESET_MAX_BODY = 64 * 1024;       // 请求体字节上限：三个接口都只送几个小字段
+
+/**
+ * 宿主 id 规则：`[a-z0-9][a-z0-9-]*`。
+ * 桌面端的复制对话框复刻了同一条（dsh-client-ui-agent-preset 的 id 校验），宿主会再校验一次。
+ */
+const PRESET_ID_RE = /^[a-z0-9][a-z0-9-]*$/;
+
+/** 宿主失败码 → HTTP 状态；没见过的码一律 400，不假装成功。 */
+function statusOf(code) {
+  if (code === 'agent-preset-not-found') return 404;
+  if (code === 'agent-preset-read-only') return 403;
+  if (code === 'agent-preset-locked') return 409;
+  return 400;
+}
+
+/** 宿主失败码 → 中文一句话。 */
+function presetMessage(code, error) {
+  if (code === 'agent-preset-not-found') return '这台宿主没有这个 Agent 预设';
+  if (code === 'agent-preset-read-only') return '随附预设是安装目录的一部分，不能删除';
+  if (code === 'agent-preset-invalid') return '预设标识不合法，或者这个标识已经被占用';
+  if (code === 'agent-preset-locked') return '会话已经开跑，Agent 预设固定为开始时的那一档';
+  if (code === 'bad-request') return 'Agent 预设请求不合法';
+  const message = error && typeof error.message === 'string' ? error.message : '';
+  return message || 'Agent 预设请求失败';
+}
+
+/** 失败回执：中文 message 在外，宿主原文与 details 原样留在里面。 */
+function failure(error) {
+  const code = error && typeof error.code === 'string' && error.code ? error.code : 'internal';
+  const details = error && error.details && typeof error.details === 'object' ? error.details : undefined;
+  const hostMessage = error && typeof error.message === 'string' && error.message ? error.message : undefined;
+  return {
+    code,
+    message: presetMessage(code, error),
+    ...(details || hostMessage ? { details: { ...(details || {}), ...(hostMessage ? { hostMessage } : {}) } } : {}),
+  };
+}
+
+/**
+ * 收窄客户端给的预设标识。
+ * @param raw 请求体里的字段。
+ * @returns { value } 或 { problem }（problem 是给用户看的中文）。
+ */
+function normalizeId(raw) {
+  if (typeof raw !== 'string') return { problem: '需要预设标识' };
+  const value = raw.trim();
+  if (!value) return { problem: '需要预设标识' };
+  if (value.length > PRESET_ID_MAX_CHARS) return { problem: `预设标识最长 ${PRESET_ID_MAX_CHARS} 个字符` };
+  if (!PRESET_ID_RE.test(value)) return { problem: '预设标识只能用小写字母、数字和连字符，且以字母或数字开头' };
+  return { value };
+}
+
+/** 显示名可有可无；给了就收窄，别把 undefined / 数字塞给宿主。 */
+function normalizeName(raw) {
+  if (raw === undefined || raw === null) return { value: undefined };
+  if (typeof raw !== 'string') return { value: undefined };
+  const value = raw.trim();
+  if (!value) return { value: undefined };
+  if (value.length > PRESET_NAME_MAX_CHARS) return { problem: `名称最长 ${PRESET_NAME_MAX_CHARS} 个字符` };
+  return { value };
+}
+
+/** 读回执里的正文与元数据：缺字段就按缺处理，不编造。 */
+function normalizeRead(value, fallbackId) {
+  const id = value && typeof value.agentPreset === 'string' && value.agentPreset ? value.agentPreset : fallbackId;
+  const content = value && typeof value.content === 'string' ? value.content : '';
+  return {
+    agentPreset: id,
+    trust: value && value.trust === 'user' ? 'user' : 'system',
+    content: content.length > PRESET_BODY_MAX_CHARS ? content.slice(0, PRESET_BODY_MAX_CHARS) : content,
+    ...(value && typeof value.name === 'string' && value.name ? { name: value.name } : {}),
+    ...(value && typeof value.description === 'string' && value.description ? { description: value.description } : {}),
+  };
+}
+
+/**
+ * POST /api/mobile/v1/agent-presets/read（token）{ agentPreset } → { ok, agentPreset, trust, content, name?, description? }
+ * 桌面端「查看」：随附预设的正文是副本据以出发的已知良好组装，能读到它正是意义所在。
+ */
+async function handleAgentPresetRead(ctx, req, res) {
+  const body = await readJsonBody(req, PRESET_MAX_BODY);
+  const id = normalizeId(body && body.agentPreset);
+  if (!id.value) return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: id.problem } });
+  const { value, error } = unwrap(await callAgentPresets(ctx, 'read', { agentPreset: id.value }));
+  if (error) return sendJson(res, statusOf(error.code), { ok: false, error: failure(error) });
+  sendJson(res, 200, { ok: true, ...normalizeRead(value, id.value) });
+}
+
+/**
+ * POST /api/mobile/v1/agent-presets/copy（token）{ from, agentPreset, name? } → { ok, agentPreset }
+ * 桌面端「复制预设」：整份复制到本机，标识符即目录名、事后无法更改，所以当场取好。
+ */
+async function handleAgentPresetCopy(ctx, req, res) {
+  const body = await readJsonBody(req, PRESET_MAX_BODY);
+  const from = normalizeId(body && body.from);
+  if (!from.value) {
+    return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: '需要被复制的预设标识 from' } });
+  }
+  const id = normalizeId(body && body.agentPreset);
+  if (!id.value) return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: id.problem } });
+  const name = normalizeName(body && body.name);
+  if (name.problem) return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: name.problem } });
+  const payload = { from: from.value, agentPreset: id.value, ...(name.value ? { name: name.value } : {}) };
+  const { value, error } = unwrap(await callAgentPresets(ctx, 'copy', payload));
+  if (error) return sendJson(res, statusOf(error.code), { ok: false, error: failure(error) });
+  const copied = value && typeof value.agentPreset === 'string' && value.agentPreset ? value.agentPreset : id.value;
+  sendJson(res, 200, { ok: true, agentPreset: copied });
+}
+
+/**
+ * POST /api/mobile/v1/agent-presets/remove（token）{ agentPreset } → { ok, agentPreset }
+ * 只对 user 预设有效：随附预设是安装目录的一部分，宿主回 agent-preset-read-only。
+ * 已在其上运行的会话不受影响，只是新会话不能再选它（宿主不改写既有会话）。
+ */
+async function handleAgentPresetRemove(ctx, req, res) {
+  const body = await readJsonBody(req, PRESET_MAX_BODY);
+  const id = normalizeId(body && body.agentPreset);
+  if (!id.value) return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: id.problem } });
+  const { error } = unwrap(await callAgentPresets(ctx, 'remove', { agentPreset: id.value }));
+  if (error) return sendJson(res, statusOf(error.code), { ok: false, error: failure(error) });
+  sendJson(res, 200, { ok: true, agentPreset: id.value });
+}
+
+module.exports = {
+  handleAgentPresetRead,
+  handleAgentPresetCopy,
+  handleAgentPresetRemove,
+  // 下面这些是给守卫测试直接驱动的纯函数（与 references.js 同做法）
+  normalizeId,
+  normalizeName,
+  normalizeRead,
+  failure,
+  unwrap,
+  statusOf,
+  presetMessage,
+  PRESET_ID_RE,
+  PRESET_ID_MAX_CHARS,
+  PRESET_NAME_MAX_CHARS,
+  PRESET_BODY_MAX_CHARS,
+};

package/lib/mobile/attachments.js

@@ -0,0 +1,116 @@
+'use strict';
+
+/**
+ * 图片归一：会话历史存的是 `{type:'image', attachment}` 而不是内联字节，
+ * 手机端拿到后要经 session attachment RPC 把图片取回来。
+ *
+ * 宿主事件里图片可能出现在四处：message/content、inserted 上下文项、
+ * assistant chunk 的 block，以及更深的嵌套 content。全部在这里归一，
+ * 这样历史与 SSE 暴露给手机端的内联图片形状是同一个。
+ *
+ * 另外一类图片在正文里：`![](/abs/path.png)` 这种指向**宿主本机文件**的写法
+ * （本机绝对路径、file://、~）在手机上取不到字节，也会被 App 当成非 http 图片降级成字面
+ * markdown。这里顺手按同一形状内联成 data URI（实现与预算见 local-images.js）。
+ */
+
+const { unwrap } = require('./envelope.js');
+const { callSessions } = require('./rpc.js');
+const { inlineTextImages, createTextImageBudget } = require('./local-images.js');
+
+/**
+ * Resolve durable image references before exposing messages to mobile clients.
+ * Session history stores `{type:'image', attachment}` rather than inline bytes;
+ * the mobile client resolves these through the session attachment RPC.
+ *
+ * Host events can carry content in several places: message/content, inserted
+ * context items, or an assistant/chunk block. Keep this normalization here so
+ * history and SSE expose the same inline-image shape to mobile clients.
+ *
+ * Text blocks additionally get local-file image syntax inlined as data URIs
+ * (see local-images.js); `opts.budget` is a shared per-response budget so one
+ * paged history response or mirror snapshot stays bounded.
+ */
+async function resolveEventAttachments(ctx, sessionId, event, opts = {}) {
+  if (!event || !event.data || typeof event.data !== 'object') return event;
+  const data = event.data;
+  const budget = opts.budget || createTextImageBudget();
+  let nextData = data;
+  let eventChanged = false;
+
+  const resolveBlock = async (block) => {
+    if (!block || typeof block !== 'object') return block;
+    if (block.type === 'text' && typeof block.text === 'string') {
+      const text = await inlineTextImages(block.text, budget);
+      return text === block.text ? block : { ...block, text };
+    }
+    if (block.type === 'image' && !block.data && block.attachment) {
+      const attachmentId = block.attachment.attachmentId;
+      if (typeof attachmentId !== 'string' || !attachmentId) return block;
+      let result;
+      try {
+        result = unwrap(await callSessions(ctx, 'attachment', { sessionId, attachmentId }));
+      } catch {
+        return block;
+      }
+      if (result.error || !result.value || typeof result.value.data !== 'string') return block;
+      const attachment = result.value.attachment || block.attachment;
+      return {
+        type: 'image',
+        attachment,
+        mediaType: attachment.mediaType || block.attachment.mediaType,
+        data: result.value.data,
+        ...(typeof attachment.name === 'string' ? { name: attachment.name } : {}),
+      };
+    }
+    if (Array.isArray(block.content)) {
+      const nested = await Promise.all(block.content.map(resolveBlock));
+      return nested.some((part, index) => part !== block.content[index]) ? { ...block, content: nested } : block;
+    }
+    return block;
+  };
+
+  const resolveContent = async (content) => {
+    if (!Array.isArray(content)) return content;
+    const resolved = await Promise.all(content.map(resolveBlock));
+    return resolved.some((part, index) => part !== content[index]) ? resolved : content;
+  };
+
+  const replaceContent = async (owner, key = 'content') => {
+    if (!owner || typeof owner !== 'object' || !Array.isArray(owner[key])) return;
+    const content = await resolveContent(owner[key]);
+    if (content === owner[key]) return;
+    eventChanged = true;
+    return { ...owner, [key]: content };
+  };
+
+  if (data.message && typeof data.message === 'object') {
+    const message = await replaceContent(data.message);
+    if (message) nextData = { ...nextData, message };
+  }
+  const root = await replaceContent(nextData);
+  if (root) nextData = root;
+
+  if (Array.isArray(nextData.inserted)) {
+    const inserted = await Promise.all(nextData.inserted.map(async (entry) => {
+      if (!entry || typeof entry !== 'object') return entry;
+      return (await replaceContent(entry)) || entry;
+    }));
+    if (inserted.some((entry, index) => entry !== nextData.inserted[index])) {
+      eventChanged = true;
+      nextData = { ...nextData, inserted };
+    }
+  }
+
+  const chunk = nextData.chunk;
+  if (chunk && typeof chunk === 'object' && chunk.block && typeof chunk.block === 'object') {
+    const block = await resolveBlock(chunk.block);
+    if (block !== chunk.block) {
+      eventChanged = true;
+      nextData = { ...nextData, chunk: { ...chunk, block } };
+    }
+  }
+
+  return eventChanged ? { ...event, data: nextData } : event;
+}
+
+module.exports = { resolveEventAttachments };

package/lib/mobile/auth.js

@@ -0,0 +1,78 @@
+'use strict';
+
+/**
+ * dsh-mobile 鉴权：移动 token 校验（HMAC，与中转同构）。
+ *
+ * token 格式 <instanceId>.<exp>.<hmac(lanSecret)>，算法/常数时间比较收在
+ * ../shared/dshtoken.js；本模块保留原公开导出面、内部改调共享实现。
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const sharedToken = require('../shared/dshtoken');
+const credentials = require('../shared/credentials-entry.js').credentialsEntry();
+
+// Resolved lazily: freezing the path at module load ignored a later DSH_HOME
+// change and made the lookup order-dependent on import timing.
+function relayStatePath() {
+  return require('../shared/paths').relayStateFile();
+}
+
+function loadRelayState() {
+  try {
+    return JSON.parse(fs.readFileSync(relayStatePath(), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/** 校验移动 token：格式 <instanceId>.<exp>.<hmac(lanSecret)>，且 instanceId 与当前实例一致。 */
+function verifyMobileToken(token) {
+  if (!token) return false;
+  const state = loadRelayState();
+  if (!state || !state.lanSecret || !state.instanceId) return false;
+  return sharedToken.verifyLanToken(state.lanSecret, token, state.instanceId);
+}
+
+/**
+ * 请求出示的设备凭据（`dshc_…`），取不到返回 null。
+ *
+ * App 把设备凭据放在独立的 `X-Dsh-Device-Credential` 头里，`Authorization` 留给
+ * 宿主 token；`Authorization` 分支仅用于兼容早期客户端。
+ */
+function presentedCredential(req) {
+  const raw = req.headers['x-dsh-device-credential'];
+  const header = Array.isArray(raw) ? raw[0] : raw;
+  if (typeof header === 'string' && header.startsWith('dshc_')) return header;
+  const m = /^Bearer\s+([^\s]+)$/.exec(req.headers.authorization || '');
+  return m && m[1].startsWith('dshc_') ? m[1] : null;
+}
+
+/**
+ * 请求是否持有有效凭据。两条路径：
+ *  1) `Authorization: Bearer <instanceId>.<exp>.<hmac>` —— 与中转同构的 HMAC token；
+ *  2) `X-Dsh-Device-Credential: dshc_…` —— 宿主本机凭据库中按 instanceId 核对。
+ *
+ * 顺序是这里唯一的要点。出示了**本机签发过**的设备凭据时必须以它为准：一经吊销
+ * 或过期立即拒绝，不再回退到无状态 token。HMAC token 有效期一年，若允许回退，
+ * 吊销就永远不生效，第 2 条也就形同虚设。
+ *
+ * 「本机不认识这张凭据」则必须回退：公网配对时凭据由中转签发、存在中转的凭据库
+ * 里（`dsh-mobile-server/lib/tunnel-handler.js`），宿主这里查不到；若一律拒绝，
+ * 「公网配对后回到局域网直连」会直接 401。
+ */
+function authorized(req) {
+  const presented = presentedCredential(req);
+  if (presented) {
+    const state = loadRelayState();
+    if (!state || !state.instanceId) return false;
+    const known = credentials.lookup(presented, state.instanceId);
+    if (known) return credentials.isLive(known);
+  }
+  const m = /^Bearer\s+([^\s]+)$/.exec(req.headers.authorization || '');
+  return Boolean(m && verifyMobileToken(m[1]));
+}
+
+module.exports = { loadRelayState, presentedCredential, verifyMobileToken, authorized };

package/lib/mobile/completion.js

@@ -0,0 +1,114 @@
+'use strict';
+
+/**
+ * 完成提醒状态机：从宿主会话列表快照与 history 事件日志里确认「跑完了」。
+ *
+ * 三条铁律写在代码注释里，这里也复述一遍，因为它们各自都防过一次误报：
+ *  1. **不**从 running→idle 的状态边沿推断完成。agent-loop 是先 append 最终
+ *     assistant/message 再 append turn/end，所以必须由 history 折出同一轮的这两个事件
+ *     才算完成；
+ *  2. `wasRunning` 是进程内边沿标记，只有本次 Host 存活期间观察到的轮次才有资格报完成，
+ *     否则冷启动的一份旧列表会把上次开机前的轮次当成新完成弹一遍通知；
+ *  3. 一轮的结局由 `turn/end` 的 `reason.kind` 说了算：`error` 记失败（宿主会话列表里
+ *     没有任何失败字段，App 侧栏的红点全靠这里折出来），`completed` 才算完成，其余
+ *     kind（max-tokens / aborted）既不算完成也不算失败。
+ */
+
+const { completionStateOf } = require('./session-cache.js');
+
+/** Update shared completion reminders from one Host session-list snapshot. */
+function updateCompletionStates(ctx, items, deviceKey = 'legacy') {
+  const states = completionStateOf(ctx, deviceKey);
+  const seen = new Set();
+  for (const summary of items || []) {
+    if (!summary || typeof summary.sessionId !== 'string' || !summary.sessionId) continue;
+    seen.add(summary.sessionId);
+    const running = !!summary.running;
+    const previous = states.get(summary.sessionId);
+    // Do not infer completion from the status edge. The history fold below
+    // must prove the matching turn/end plus its final assistant message.
+    const completed = previous?.completed === true;
+    // `wasRunning` is an internal edge marker.  A completed notification is
+    // only eligible for a turn observed while this Host was alive; a cold
+    // list snapshot must not replay an old turn as a new completion.
+    states.set(summary.sessionId, {
+      running,
+      completed: running ? false : completed,
+      turn: previous?.turn,
+      wasRunning: previous?.running === true,
+      // 「上一轮失败」是历史事实：宿主列表摘要里没有这个信息，唯一来源是下面的 history
+      // 折叠。它必须跨快照、跨下一轮延续 —— 否则「失败之后用户又发一句话」会让
+      // state.turn 前进，红点还没被看见就没了。
+      failure: previous?.failure,
+    });
+  }
+  // The Host list is canonical for this device scope; discard detached
+  // sessions so completion state cannot leak across reused session IDs.
+  for (const sessionId of states.keys()) {
+    if (!seen.has(sessionId)) states.delete(sessionId);
+  }
+  return states;
+}
+
+/**
+ * Confirm the running -> idle edge against the event log.  Agent status is a
+ * coarse activity signal: the agent-loop appends the final assistant/message
+ * and only then appends turn/end.  Keep the edge tied to that exact turn so a
+ * late/stale list response cannot complete a newer (or an older) turn.
+ */
+function confirmCompletionFromHistory(state, events, running) {
+  if (!state || !Array.isArray(events)) return;
+  let latestTurn;
+  const ends = new Map();
+  const assistants = new Map();
+  for (const entry of events) {
+    const event = entry?.event || entry;
+    if (!event || !event.data || typeof event.data !== 'object') continue;
+    const turn = event.data.turn;
+    if (typeof turn !== 'number') continue;
+    if (event.type === 'turn/start') latestTurn = turn;
+    else if (event.type === 'assistant/message') {
+      assistants.set(turn, event);
+      if (latestTurn === undefined) latestTurn = turn;
+    } else if (event.type === 'turn/end') {
+      ends.set(turn, event);
+      if (latestTurn === undefined) latestTurn = turn;
+    }
+  }
+  if (latestTurn !== undefined) state.turn = latestTurn;
+  if (running || !state.wasRunning || state.turn === undefined) return;
+  const end = ends.get(state.turn);
+  const assistant = assistants.get(state.turn);
+  const reason = end && end.data ? end.data.reason : undefined;
+  const kind = reason && typeof reason.kind === 'string' ? reason.kind : undefined;
+  // 本轮以错误收尾：宿主不会再补一条最终消息，但它刚刚追加过 turn/end —— 下面那条
+  // 「assistant 早于 turn/end 就算完成」的规则会把这种轮次判成「已完成待读」，侧栏于是
+  // 把一次失败显示成绿点。失败是宿主列表摘要里没有的信息，只能在这里折出来交给 App。
+  if (end && kind === 'error') {
+    const error = reason && reason.error && typeof reason.error === 'object' ? reason.error : {};
+    state.completed = false;
+    state.failure = {
+      turn: state.turn,
+      code: typeof error.code === 'string' ? error.code : null,
+      message: typeof error.message === 'string' ? error.message : null,
+      at: typeof end.time === 'number' ? end.time : Date.now(),
+    };
+    return;
+  }
+  // max-tokens / aborted 等：这一轮没跑完，同样不能报完成；但它没有错误码可显示，
+  // 所以只清完成标记，不产生红点。
+  if (end && kind !== undefined && kind !== 'completed') {
+    state.completed = false;
+    state.failure = undefined;
+    return;
+  }
+  // The assistant message must be the settled message for this turn, not an
+  // interrupted partial and not merely a preceding turn's message.
+  if (end && assistant && assistant.seq <= end.seq && assistant.data.interrupted !== true) {
+    state.completed = true;
+    // 成功收尾的轮次覆盖旧失败：标记必须跟着最新一次运行走。
+    state.failure = undefined;
+  }
+}
+
+module.exports = { updateCompletionStates, confirmCompletionFromHistory };