llm-api-gateway-cli 1.0.0

package/lib/tasksession.js

@@ -0,0 +1,594 @@
+/**
+ * 任务会话（模型态消息）落盘 —— 方案 C 的存储层
+ *
+ * 为什么需要它：任务页原来是**无状态**的 —— 每轮请求都拿浏览器里的渲染态消息重建上下文，
+ * 而渲染态里只有「对白」（role + content），工具调用与工具结果（steps）在 `public/task.js`
+ * 和 `lib/hub.js` 两处被剥掉。于是 `read_file` / `grep` 读回来的文件正文从没进过模型上下文，
+ * 模型每轮只能重新 `list_dir` / `grep` —— 时间和 token 都浪费在重复探索上。
+ *
+ * 这里存的是**模型态**：`assistant.tool_calls` + `{role:'tool', tool_call_id, content}`，
+ * 与 `lib/agent.js` 往 `run.messages` 里 push 的形状完全一致。服务端持有它、每轮 append、
+ * 每轮落盘，前端只发「新指令 + taskId」。
+ *
+ * 与渲染态的关系：**两份并存，不合并**。
+ *   · 渲染态独有 label / note / pending / notices —— 从原生消息反推不回来；
+ *   · 模型态独有 tool_call_id / arguments / 完整工具输出 —— 渲染态（`sanitizeStep`）把它丢了。
+ * 所以渲染态继续留在 `tasks/<id>.json`（见 `lib/taskstore.js`），这里只放模型态。
+ *
+ * 文件布局：`<taskStoreDir>/sessions/<taskId>.json`
+ * —— 放在任务存储根**内部**而不是 `<root>/sessions/`：后者已经被 `lib/sessionstore.js`
+ * 的 CLI 会占用（`sessionstore.js` 的 resolveSessionDir）。放里面还能天然跟随任务的删除与 TTL。
+ */
+
+import { randomUUID } from 'node:crypto';
+import { statSync } from 'node:fs';
+import path from 'node:path';
+import { createMessageStore } from './sessionstore.js';
+import { isSafeId, TTL_MS as TASK_TTL_MS } from './taskstore.js';
+
+/** 单会话落盘硬闸：防跑飞的兜底，真正的成本控制在 history.maxChars */
+export const TASK_SESSION_MAX_BYTES = 8 * 1024 * 1024;
+export const TASK_SESSION_MAX_MESSAGES = 4000;
+/** 单条消息正文的落盘上限（工具结果可能是几十万字符的文件正文） */
+export const MAX_MESSAGE_CHARS = 400000;
+/** 迁移旧数据时，单条工具结果正文保留多少（超了就截断并标注） */
+export const MIGRATE_STEP_CHARS = 20000;
+
+export const HISTORY_MAX_CHARS = 60000;
+export const HISTORY_KEEP_RECENT_TURNS = 3;
+/** 是否注入「已读文件清单」（history.readFileDigest 的默认值） */
+export const HISTORY_READ_FILE_DIGEST = true;
+
+/** 压缩后的工具结果长这样，靠这个前缀识别「已经压过了」（压缩是幂等的） */
+const COMPACTED_MARK = '[已压缩的历史工具结果] ';
+/** 已读文件清单最多列几条、最多占多少字符 —— 它要进 system，不能自己变成大头 */
+const DIGEST_MAX_FILES = 20;
+const DIGEST_MAX_CHARS = 2000;
+
+/** 迁移时给工具记录套的分隔符：要显眼到模型一眼能认出「这是历史工具输出」 */
+const STEP_BLOCK_HEAD = '[工具调用记录（由旧版本迁移，调用参数已丢失）]';
+const STEP_BLOCK_TAIL = '[记录结束]';
+
+const clip = (s, max) => (s.length > max ? `${s.slice(0, max)}\n…（已截断，原文 ${s.length} 字符）` : s);
+
+/* ---------- 会话对象 ---------- */
+
+/**
+ * 新建一个任务会话。`id` 与 `taskId` 是两件事：
+ *   · `id` 是**本次运行**的标识（挂起态落盘、baggage 头都用它，`lib/agent.js` 依赖它）；
+ *   · `taskId` 是**这条任务**的标识（会话文件按它命名，跨轮次稳定）。
+ */
+export function createTaskSession({ taskId, workDir, model, mode, system, limits = {} } = {}) {
+  if (!isSafeId(taskId)) throw Object.assign(new Error('任务 id 非法'), { status: 400 });
+  const base = typeof system === 'string' ? system : '';
+  return {
+    version: 1,
+    id: randomUUID(),
+    taskId,
+    // 字段名跟 lib/agent.js / lib/runner.js 对齐：它们读的都是 run.workingDir
+    workingDir: workDir || '',
+    model: model || '',
+    mode: mode || 'manual',
+    // system 单独存「干净」的那份：迁移说明与已读文件清单是每轮现拼的，
+    // 混进来会让「system 变没变」这个判断失去意义（每次都被当成变了 → 压缩标记反复作废）
+    system: base,
+    // 计划模式落盘的计划文档（相对工作目录，如 docs/20260916-xx.md）。
+    // 由 lib/hub.js 在收尾时写入，下一轮拼 system 时用它把模型按回计划上，见 lib/plandoc.js。
+    planFile: '',
+    messages: [{ role: 'system', content: base }],
+    usage: { prompt: 0, completion: 0 },
+    history: {
+      maxChars: limits.historyMaxChars ?? HISTORY_MAX_CHARS,
+      keepRecentTurns: limits.keepRecentTurns ?? HISTORY_KEEP_RECENT_TURNS,
+      compactedAt: null,
+      compactedTurns: 0,
+    },
+    // 已读文件快照：path → { lines, mtimeMs, atIndex }。用来判断「这份内容还在上文里」
+    // 以及「是不是被外部改过了」，见 readFileDigestBlock。
+    readFiles: {},
+    migrated: 'none',
+    degradedTurns: 0,
+    // 迁移说明单独存字段，而不是揉进 system 正文 ——
+    // 否则第二轮的 refreshSessionContext 重建 system 时会把它冲掉，
+    // 模型就以为那些「历史工具输出」是它自己读的当前内容了。
+    migrationNote: '',
+    needsRebuild: false,
+    touchedAt: Date.now(),
+  };
+}
+
+/**
+ * 把请求里的工作目录 / 模式 / 系统提示词同步进会话。
+ *
+ * 换了模式（比如从计划模式切到自动模式）必须换掉 system，否则模型还按上一轮的约束干活。
+ * 注意比的是 `session.system` 而不是 `messages[0].content` —— 后者每轮都会被拼上
+ * 迁移说明与已读文件清单，拿它比会「每次都认为变了」，把压缩标记冲掉，prompt 缓存也就没了。
+ */
+export function refreshSessionContext(session, { workDir, model, mode, system }) {
+  if (typeof workDir === 'string' && workDir) session.workingDir = workDir;
+  if (typeof model === 'string' && model) session.model = model;
+  if (typeof mode === 'string' && mode) session.mode = mode;
+  if (typeof system !== 'string') return session;
+  if (typeof session.system !== 'string') session.system = deriveBaseSystem(session);
+  if (session.system === system) return session;
+
+  session.system = system;
+  // system 是发出去的第一条消息，它一变，之前那份压缩结果就不再是「同一个前缀」了
+  session.history.compactedAt = null;
+  session.history.compactedTurns = 0;
+  return session;
+}
+
+/** 老会话没存 `system`：从 messages[0] 里把迁移说明剥掉反推出来 */
+function deriveBaseSystem(session) {
+  const head = Array.isArray(session.messages) ? session.messages[0] : null;
+  let base = head?.role === 'system' && typeof head.content === 'string' ? head.content : '';
+  const note = typeof session.migrationNote === 'string' ? session.migrationNote : '';
+  if (note && base.endsWith(note)) base = base.slice(0, -note.length).trimEnd();
+  return base;
+}
+
+/* ---------- 清洗与落盘 ---------- */
+
+/**
+ * 从消息数组最前面丢一条，但**不能让历史以 tool 消息开头** ——
+ * `{role:'tool'}` 必须紧跟在带 `tool_calls` 的 assistant 后面，
+ * 否则严格校验的上游会直接 400。丢 assistant 时把它的 tool 回包一起丢掉。
+ * 返回实际丢掉的条数。
+ */
+function dropOldestTurn(messages) {
+  if (messages.length <= 1) return 0;
+  let removed = 0;
+  messages.splice(1, 1);
+  removed++;
+  while (messages.length > 1 && messages[1]?.role === 'tool') {
+    messages.splice(1, 1);
+    removed++;
+  }
+  return removed;
+}
+
+function trimMessage(m) {
+  const copy = { ...m };
+  if (typeof copy.content === 'string' && copy.content.length > MAX_MESSAGE_CHARS) {
+    copy.content = `${copy.content.slice(0, MAX_MESSAGE_CHARS)}\n…（落盘时截断）`;
+  }
+  return copy;
+}
+
+/** 已读文件快照是「模型读过的路径 + 当时的 mtime」，封顶并只留数值字段，别让它长成又一个上下文 */
+function sanitizeReadFiles(input) {
+  if (!input || typeof input !== 'object') return {};
+  const out = {};
+  let n = 0;
+  for (const [k, v] of Object.entries(input)) {
+    if (n++ >= 200) break; // 清单本身也是会长的，封个顶
+    if (typeof k !== 'string' || !k || !v || typeof v !== 'object') continue;
+    out[k.slice(0, 400)] = {
+      lines: Number(v.lines) || 0,
+      mtimeMs: Number(v.mtimeMs) || 0,
+      atIndex: Number(v.atIndex) || 0,
+    };
+  }
+  return out;
+}
+
+/** 只留认识的字段，避免把上游 / 页面塞进来的任意对象原样写盘 */
+export function sanitizeTaskSession(session, { maxBytes = TASK_SESSION_MAX_BYTES, maxMessages = TASK_SESSION_MAX_MESSAGES } = {}) {
+  if (!session || typeof session !== 'object' || !isSafeId(session.taskId)) return null;
+  const raw = Array.isArray(session.messages) ? session.messages.filter((m) => m && typeof m === 'object') : [];
+  const messages = raw.slice(-maxMessages).map(trimMessage);
+
+  const history = session.history && typeof session.history === 'object' ? session.history : {};
+  const base = typeof session.system === 'string' ? session.system : deriveBaseSystem(session);
+  const record = {
+    version: 1,
+    id: isSafeId(session.id) ? session.id : randomUUID(),
+    taskId: session.taskId,
+    workingDir: typeof session.workingDir === 'string' ? session.workingDir : '',
+    model: typeof session.model === 'string' ? session.model : '',
+    mode: typeof session.mode === 'string' ? session.mode : 'manual',
+    system: base,
+    // 计划文档路径（相对工作目录）：落盘时一并记住，跨轮次/重启后仍能「按计划执行」
+    planFile: typeof session.planFile === 'string' ? session.planFile.slice(0, 200) : '',
+    messages,
+    usage: { prompt: Number(session.usage?.prompt) || 0, completion: Number(session.usage?.completion) || 0 },
+    history: {
+      maxChars: Number(history.maxChars) > 0 ? Number(history.maxChars) : HISTORY_MAX_CHARS,
+      keepRecentTurns: Number(history.keepRecentTurns) >= 0 ? Number(history.keepRecentTurns) : HISTORY_KEEP_RECENT_TURNS,
+      compactedAt: Number(history.compactedAt) || null,
+      compactedTurns: Number(history.compactedTurns) || 0,
+    },
+    // 已读文件快照：几公里外的 mtime 变化全靠它认出来，所以必须落盘（不然每次重启都当作「第一次读」）
+    readFiles: sanitizeReadFiles(session.readFiles),
+    // 迁移质量：none 全新 / native 逐条还原 / partial 有降级轮（工具参数不可恢复）
+    migrated: ['none', 'native', 'partial'].includes(session.migrated) ? session.migrated : 'none',
+    degradedTurns: Number(session.degradedTurns) || 0,
+    migrationNote: typeof session.migrationNote === 'string' ? session.migrationNote.slice(0, 4000) : '',
+    needsRebuild: Boolean(session.needsRebuild),
+    touchedAt: Number(session.touchedAt) || Date.now(),
+  };
+
+  // 体积兜底：从最老的整轮开始丢，system 与「最近 keepRecentTurns 轮」不丢
+  let dropped = 0;
+  const keepAtLeast = 1 + record.history.keepRecentTurns * 2; // system + 每轮至少 user + assistant
+  while (Buffer.byteLength(JSON.stringify(record)) > maxBytes && record.messages.length > keepAtLeast + 1) {
+    const n = dropOldestTurn(record.messages);
+    if (!n) break;
+    dropped += n;
+  }
+  return { record, dropped };
+}
+
+/**
+ * 任务会话存储（目录建议传 `<taskStoreDir>/sessions`）。
+ * `limits` 可以是对象，也可以是函数 —— 传函数是为了让配置改了之后立刻生效，
+ * 而不必重建 store。
+ */
+export function createTaskSessionStore(dir, limits = {}) {
+  const limitsOf = typeof limits === 'function' ? limits : () => limits;
+  return createMessageStore({
+    dir,
+    sanitize: (s) => sanitizeTaskSession(s, limitsOf()),
+    idOf: (r) => r.taskId,
+    maxItems: 0, // 按任务而不是按数量淘汰：任务被删/被 prune 时我们主动删会话
+    label: '任务会话',
+  });
+}
+
+/* ---------- 历史预算与「已读文件」清单（M3） ---------- */
+
+const charCount = (messages) => (Array.isArray(messages) ? messages.reduce((n, m) => n + (typeof m?.content === 'string' ? m.content.length : 0), 0) : 0);
+
+/**
+ * 保留区起点：最近 keepTurns 轮的第一条 user 消息的下标。
+ *
+ * 「一轮」按 user 消息切。压缩只动这个下标**之前**的工具结果 ——
+ * 最近几轮必须保全文，否则模型刚读完文件、下一轮就看不见内容了，等于逼它重读。
+ */
+function turnStartIndex(messages, keepTurns) {
+  if (!(keepTurns > 0)) return messages.length;
+  let seen = 0;
+  for (let i = messages.length - 1; i >= 1; i--) {
+    if (messages[i]?.role !== 'user') continue;
+    seen++;
+    if (seen === keepTurns) return i;
+  }
+  return 1; // 还没攒够这么多轮，全在保留区
+}
+
+/** tool_call_id → 工具名与参数。工具结果本身不带名字，得回头找它的调用 */
+function toolCallIndex(messages) {
+  const map = new Map();
+  for (const m of Array.isArray(messages) ? messages : []) {
+    if (m?.role !== 'assistant' || !Array.isArray(m.tool_calls)) continue;
+    for (const tc of m.tool_calls) {
+      const name = tc?.function?.name;
+      if (tc?.id && name) map.set(tc.id, { name, args: tc.function.arguments });
+    }
+  }
+  return map;
+}
+
+/** 从工具参数 JSON 里取路径；取不到就退回原始串（宁可难看，也别让模型以为没读过） */
+function pathFromArgs(argsJson) {
+  try {
+    const v = JSON.parse(String(argsJson || ''));
+    if (v && typeof v.path === 'string' && v.path) return v.path;
+    if (v && typeof v.file === 'string' && v.file) return v.file;
+  } catch {
+    /* 参数不是合法 JSON：老数据或模型写坏了 */
+  }
+  return '';
+}
+
+/** 压成一行时给个规模感：「120 行」比「6120 字符」对模型更有用 */
+function sizeLabel(content) {
+  const text = typeof content === 'string' ? content : '';
+  const lines = text ? text.split('\n').length : 0;
+  if (lines > 1) return `${lines} 行`;
+  return `${text.length} 字符`;
+}
+
+function isCompacted(m) {
+  return typeof m?.content === 'string' && m.content.startsWith(COMPACTED_MARK);
+}
+
+/**
+ * 历史预算：把「较早的工具结果正文」压成一行，但**保留记录**。
+ *
+ * 为什么保留记录而不是丢掉整条：模型必须知道「这个文件我读过」。丢掉记录会让它
+ * 以为从没读过，于是又去 `list_dir` / `read_file` —— 正是我们要治的病。
+ * 压缩只削正文，命令行与结果规模都留在那里。
+ *
+ * prompt 缓存：只在总量超过预算时才动手（没超就一个字都不改）。一旦每轮都重新裁剪，
+ * 已经发出去的前缀就会漂移，上游的 prefix cache 全部失效 —— 省下的 token 还不如赔的多。
+ */
+export function compactHistory(session, limits = {}) {
+  const h = session.history && typeof session.history === 'object' ? session.history : (session.history = {});
+  // 以**当前配置**为准（R1-V8）：会话里那份只是上次的快照，用户改了配置就该立刻生效
+  if (Number(limits.historyMaxChars) > 0) h.maxChars = Number(limits.historyMaxChars);
+  if (Number(limits.keepRecentTurns) >= 0) h.keepRecentTurns = Number(limits.keepRecentTurns);
+  if (!(Number(h.maxChars) > 0)) h.maxChars = HISTORY_MAX_CHARS;
+  if (!(Number(h.keepRecentTurns) >= 0)) h.keepRecentTurns = HISTORY_KEEP_RECENT_TURNS;
+
+  const before = charCount(session.messages);
+  if (before <= h.maxChars) return { compacted: false, before, after: before, pruned: 0 };
+
+  const calls = toolCallIndex(session.messages);
+  const boundary = turnStartIndex(session.messages, h.keepRecentTurns);
+  const snap = session.readFiles && typeof session.readFiles === 'object' ? session.readFiles : (session.readFiles = {});
+  let pruned = 0;
+  for (let i = 1; i < boundary; i++) {
+    const m = session.messages[i];
+    if (m?.role !== 'tool' || isCompacted(m)) continue;
+    const c = calls.get(m.tool_call_id);
+    const name = c?.name || 'tool';
+    const p = pathFromArgs(c?.args);
+    const lines = (typeof m.content === 'string' ? m.content : '').split('\n').length;
+    // 规模要在压缩**之前**记下来 —— 压完之后从正文里再也数不出来，
+    // 而「已读文件清单」还欠用户一个「这文件多大」
+    if (p) {
+      const prev = snap[p];
+      if (!prev || i > prev.atIndex) snap[p] = { lines, mtimeMs: prev?.mtimeMs || 0, atIndex: i };
+    }
+    const target = p || (c?.args ? clip(String(c.args), 120) : '');
+    m.content = `${COMPACTED_MARK}${name}${target ? ` ${target}` : ''} → ${sizeLabel(m.content)}（正文已压缩；需要内容请重新读取这个文件）`;
+    pruned++;
+  }
+
+  const after = charCount(session.messages);
+  if (pruned) {
+    h.compactedAt = Date.now();
+    h.compactedTurns = (Number(h.compactedTurns) || 0) + pruned;
+  }
+  return { compacted: pruned > 0, before, after, pruned };
+}
+
+/**
+ * 「已读文件清单」：告诉模型哪些文件在上文里、多大、什么时候改过。
+ *
+ * 这一条直接对着用户的抱怨（每轮都去读目录、搜文件）：模型看不见「我读过」，
+ * 就只好再读一遍。清单不塞正文，只给路径 + 行数 + mtime，成本极低。
+ *
+ * mtime 变化要能报出来，否则模型会拿旧内容当现状。判断方式：
+ *   · 先记下「第一次读到它」时的 mtime 与消息下标；
+ *   · 之后模型自己又读过（下标变大）→ 刷新快照，不再报警（它手里的是新内容）；
+ *   · 下标没变而 mtime 变了 → 说明是外部改的，标注「已被外部修改」。
+ */
+export function readFileDigestBlock(session, { cwd } = {}) {
+  const msgs = Array.isArray(session.messages) ? session.messages : [];
+  const calls = toolCallIndex(msgs);
+  const files = new Map(); // path → { lines, atIndex, compacted }
+  msgs.forEach((m, i) => {
+    if (m?.role !== 'tool') return;
+    const c = calls.get(m.tool_call_id);
+    if (!c || c.name !== 'read_file') return;
+    const p = pathFromArgs(c.args);
+    if (!p) return;
+    files.set(p, {
+      lines: (typeof m.content === 'string' ? m.content : '').split('\n').length,
+      atIndex: i,
+      compacted: isCompacted(m),
+    });
+  });
+  if (!files.size) return '';
+
+  const snap = session.readFiles && typeof session.readFiles === 'object' ? session.readFiles : (session.readFiles = {});
+  const base = cwd || session.workingDir || '';
+  const rows = [];
+  for (const p of [...files.keys()].sort()) {
+    const cur = files.get(p);
+    const prev = snap[p];
+    const abs = path.isAbsolute(p) ? p : path.join(base, p);
+    // 正文被压过时行数只能沿用当初记下的那份：压缩后那一行数出来永远是「1 行」
+    const lines = cur.compacted && prev ? prev.lines : cur.lines;
+    let note;
+    try {
+      const st = statSync(abs);
+      if (!prev || cur.atIndex > prev.atIndex || !prev.mtimeMs) {
+        // 三种情况都以「当前」为准，且不报警：
+        //   · 第一次读到它；
+        //   · 模型自己又读了一遍（下标变大）；
+        //   · 快照是压缩时留下的，当时没记 mtime（mtimeMs = 0），拿现在这份补上
+        snap[p] = { lines, mtimeMs: st.mtimeMs, atIndex: cur.atIndex };
+        note = `${lines} 行`;
+      } else if (st.mtimeMs !== prev.mtimeMs) {
+        note = `${lines} 行，已被外部修改（现在 ${new Date(st.mtimeMs).toISOString().slice(0, 16).replace('T', ' ')}，请重新读取）`;
+      } else {
+        note = `${lines} 行`;
+      }
+    } catch {
+      note = `${lines} 行，文件已不存在`;
+    }
+    // 压过的条目必须说清楚 —— 否则清单在上面说「不必重复读取」，
+    // 而它的正文其实已经被压缩掉了，模型会拿一段不存在的记忆当依据
+    if (cur.compacted) note += '，正文已压缩，需要时请重新读取';
+    rows.push(`- ${p}（${note}）`);
+  }
+  if (!rows.length) return '';
+
+  const shown = rows.slice(-DIGEST_MAX_FILES);
+  let text =
+    '【已读文件清单】下面这些文件已经读过，正文在上下文里，**不必重复读取**（标注「已压缩」的除外）：\n' +
+    shown.join('\n') +
+    (rows.length > shown.length ? `\n（另有 ${rows.length - shown.length} 个更早的文件未列出）` : '');
+  if (text.length > DIGEST_MAX_CHARS) text = `${text.slice(0, DIGEST_MAX_CHARS)}\n…（清单过长已截断）`;
+  return text;
+}
+
+/**
+ * 把要发出去的消息组装好：system（+迁移说明+已读文件清单）永远在最前。
+ *
+ * 会就地更新 `session.messages[0]`，于是「会话文件里存的」与「实际发出去的」始终一致，
+ * 下一轮也就不会因为前缀漂移而废掉 prompt 缓存；而 `session.system` 保持干净，
+ * 用来判断用户的系统提示词到底变没变。
+ */
+export function buildOutgoingMessages(session, { cwd, readFileDigest = HISTORY_READ_FILE_DIGEST } = {}) {
+  const parts = [];
+  if (typeof session.system === 'string' && session.system.trim()) parts.push(session.system);
+  if (typeof session.migrationNote === 'string' && session.migrationNote.trim()) parts.push(session.migrationNote);
+  if (readFileDigest) {
+    const digest = readFileDigestBlock(session, { cwd });
+    if (digest) parts.push(digest);
+  }
+  const content = parts.join('\n\n');
+  const msgs = Array.isArray(session.messages) ? session.messages : (session.messages = []);
+  if (msgs[0]?.role === 'system') msgs[0] = { role: 'system', content };
+  else msgs.unshift({ role: 'system', content });
+  return msgs;
+}
+
+/**
+ * 每轮开跑前的统一准备：先按预算压缩，再拼出要发出去的消息。
+ * 让调用方只记一个入口，免得出现「压了没拼」或「拼了没压」的半套状态。
+ */
+export function prepareTaskSession(session, { limits = {}, cwd, readFileDigest = HISTORY_READ_FILE_DIGEST } = {}) {
+  const compaction = compactHistory(session, limits);
+  buildOutgoingMessages(session, { cwd: cwd || session.workingDir, readFileDigest });
+  return compaction;
+}
+
+/* ---------- 旧数据懒迁移 ---------- */
+
+/** 把一条渲染态的 step 渲染成文本记录（方案 B 形态，仅用于迁移） */
+function renderStepBlock(steps) {
+  const lines = [];
+  for (const s of Array.isArray(steps) ? steps : []) {
+    if (!s || typeof s !== 'object') continue;
+    const name = typeof s.label === 'string' && s.label ? s.label : typeof s.name === 'string' ? s.name : '工具调用';
+    const mark = s.status === 'ok' ? '✓' : s.status === 'fail' ? '✗' : '·';
+    const brief = typeof s.summary === 'string' && s.summary ? ` ${s.summary}` : '';
+    lines.push(`- ${mark} ${name}${brief}`);
+    if (typeof s.content === 'string' && s.content) lines.push(clip(s.content, MIGRATE_STEP_CHARS));
+  }
+  if (!lines.length) return '';
+  return `${STEP_BLOCK_HEAD}\n${lines.join('\n')}\n${STEP_BLOCK_TAIL}`;
+}
+
+/**
+ * 一条渲染态 step 能不能还原成原生 tool_call。
+ *
+ * `id` 就是模型给的 tool_call_id，`args` 是当时那份原始 JSON 参数串
+ * （lib/taskstore.js 的 sanitizeStep 会把它一起存下来）。三个都要有才敢还原，
+ * 缺一个就只能退回「折成文本」。
+ */
+function nativeStep(s) {
+  if (!s || typeof s !== 'object') return null;
+  const id = typeof s.id === 'string' ? s.id.trim() : '';
+  const name = typeof s.name === 'string' ? s.name.trim() : '';
+  const args = typeof s.args === 'string' ? s.args.trim() : '';
+  if (!id || !name || !args) return null;
+  return { id, name, args, content: typeof s.content === 'string' ? s.content : '' };
+}
+
+/**
+ * 把渲染态消息反推成模型态消息。
+ *
+ * 两条路：
+ *  1. **能还原成原生 tool_calls 就还原** —— 记录里 `id`/`args` 齐全时（新版本存过的任务），
+ *     重建出来的对话与当时发给模型的一致，含调用参数；
+ *  2. 只有 name / label / summary / content 时（更老的记录），把工具记录折成文本块附在
+ *     assistant 正文后面。这是**迁移产物**，不是长期方案 —— 新产生的数据不再走这条路。
+ *
+ * 但「折成文本」也远好于丢掉：关键是模型能重新看到读过的文件内容，
+ * 而不是第二轮又去 `grep` 一遍。
+ */
+export function migrateFromRenderState(renderMessages, { system } = {}) {
+  const out = [{ role: 'system', content: typeof system === 'string' ? system : '' }];
+  let degraded = 0;
+  let restored = 0;
+  let skipped = 0;
+  let note = '';
+
+  for (const m of Array.isArray(renderMessages) ? renderMessages : []) {
+    if (!m || typeof m !== 'object') continue;
+    const text = typeof m.content === 'string' ? m.content : '';
+    if (m.role === 'user') {
+      if (text.trim()) out.push({ role: 'user', content: text });
+      continue;
+    }
+    if (m.role !== 'assistant') continue;
+
+    const steps = Array.isArray(m.steps) ? m.steps : [];
+    const natives = steps.map(nativeStep);
+    if (natives.length && natives.every(Boolean)) {
+      out.push({
+        role: 'assistant',
+        content: text,
+        tool_calls: natives.map((n) => ({ id: n.id, type: 'function', function: { name: n.name, arguments: n.args } })),
+      });
+      for (const n of natives) out.push({ role: 'tool', tool_call_id: n.id, content: clip(n.content, MIGRATE_STEP_CHARS) });
+      restored++;
+      continue;
+    }
+
+    const block = renderStepBlock(steps);
+    let content = text;
+    if (block) {
+      content = content.trim() ? `${content}\n\n${block}` : block;
+      degraded++;
+    }
+    // 纯工具轮（正文为空）也不能整条丢 —— 那正是原来「每次都要重新探索」的成因之一
+    if (!content.trim()) {
+      skipped++;
+      continue;
+    }
+    out.push({ role: 'assistant', content });
+  }
+
+  if (degraded) {
+    // 说明单独返回，由调用方存进 session.migrationNote 并拼到 system 后面。
+    // 揉进 out[0] 是不行的：下一轮 refreshSessionContext 重建 system 时会把它冲掉。
+    note =
+      '【历史迁移说明】\n上面的对话里有一部分工具结果由旧版本迁移而来，' +
+      '其调用参数已丢失、只保留了结果正文。它们反映的是**当时**的文件内容；' +
+      '如果你需要确认某个文件现在的内容，请重新读取，不要在没读的情况下假设它没变。';
+  }
+  return { messages: out, degraded, restored, skipped, migrated: degraded ? 'partial' : out.length > 1 ? 'native' : 'none', note };
+}
+
+/**
+ * 载入会话；没有就按需创建。
+ *
+ * `renderTask` 传一个「取渲染态任务」的函数（通常 `() => store.get(taskId)`）：
+ * 存在却没会话文件时，说明这条任务是 C 之前建的 —— 现场懒迁移一次并落盘。
+ * 懒迁移而不是启动时批量迁移：任务有 TTL、上限 20 条，用户可能永远不再打开其中一些，
+ * 批量读全部文件既慢又可能留下半成品。
+ */
+export function loadOrCreateTaskSession({ sessions, taskId, workDir, model, mode, system, renderTask, limits = {} }) {
+  const existing = sessions.read(taskId);
+  if (existing) {
+    refreshSessionContext(existing, { workDir, model, mode, system });
+    // 会话文件来自更早的版本时补齐新增字段
+    if (!existing.history || typeof existing.history !== 'object') {
+      existing.history = { maxChars: HISTORY_MAX_CHARS, keepRecentTurns: HISTORY_KEEP_RECENT_TURNS, compactedAt: null, compactedTurns: 0 };
+    }
+    if (!existing.migrated) existing.migrated = 'none';
+    if (!existing.readFiles || typeof existing.readFiles !== 'object') existing.readFiles = {};
+    if (typeof existing.system !== 'string') existing.system = deriveBaseSystem(existing);
+    return { session: existing, created: false };
+  }
+
+  const fresh = createTaskSession({ taskId, workDir, model, mode, system, limits });
+  let task = null;
+  try {
+    task = typeof renderTask === 'function' ? renderTask() : null;
+  } catch {
+    task = null; // 渲染态读不出来不该阻塞这一轮
+  }
+
+  if (task && Array.isArray(task.messages) && task.messages.length) {
+    const built = migrateFromRenderState(task.messages, { system });
+    fresh.migrationNote = built.note;
+    fresh.messages = built.messages;
+    fresh.migrated = built.migrated;
+    fresh.degradedTurns = built.degraded;
+    // system 存干净的那份，迁移说明交给 buildOutgoingMessages 每轮现拼
+    fresh.messages[0] = { role: 'system', content: fresh.system };
+  }
+  return { session: fresh, created: true };
+}
+
+/** 任务会话的过期时间与任务一致（滑动 15 天） */
+export const TASK_SESSION_TTL_MS = TASK_TTL_MS;