memhouse 0.18.12 → 0.20.1

package/editors/normalise/vscode.js

@@ -0,0 +1,549 @@
+'use strict';
+// v4 wave 1: VS Code, Local chat engine → normalised session log records (docs/design/sessions-log.md).
+//
+// Store: <user-data>/User/workspaceStorage/<ws>/chatSessions/<sid>.jsonl (and
+// User/globalStorage/emptyWindowChatSessions/ for chats opened with no folder). The Copilot engine's
+// sessions live in ~/.copilot/session-state and are captured by the copilot-cli normaliser, not here
+// (sessions-model §1 rule 3: the vscode harness covers only chatSessions, engine local).
+// Spec: docs/design/editor-shapes.md "VS Code 1.142", "The Local change log" (repository),
+// sessions-model v0 and its annex row "vscode (engine local)".
+//
+// Rules from the spec:
+// - the file is a change log: kind 0 = snapshot, 1 = set at path k, 2 = splice at k (truncate at i
+//   when given, then append v), 3 = delete at k. The conversation is the fold's `requests[]`;
+// - a kind 2 with i is an explicit, append-only retraction (an edited request or a restored
+//   checkpoint; sessions-model §2.6 (a)): the fold remembers the cut requests, they stay in the log as
+//   messages with state 'retracted', and a lifecycle record {event: 'rewind'} follows them. A cut
+//   request whose id the same splice re-appends is an in-place update, not a retraction. What leaves
+//   the store for real (a new kind 0 snapshot) is left to vanish;
+// - one speaker per message: the user message is `requestId`, the reply is `responseId`, falling back
+//   to `<requestId>:response`;
+// - `toolInvocationSerialized` holds the call and its result (`toolCallId`). Arguments and the result
+//   the model saw are in `result.metadata.toolCallRounds` / `toolCallResults`, keyed by the call id
+//   plus a `__vscode-<n>` suffix;
+// - thinking parts are empty plus an opaque id: a reasoning part with `opaque: true`;
+// - the model is the one Auto resolved (`result.metadata.resolvedModel`, the `autoModeResolution`
+//   part), never the `copilot/auto` placeholder, which is kept as `model_requested`;
+// - usage: per request `promptTokens` / `completionTokens` (not `result.metadata.outputTokens`),
+//   basis unknown, and `copilotCredits` as `credits`; a stored zero is null;
+// - `hiddenFromTranscript` marks the request's messages `hidden`; a tool shown with presentation
+//   `hidden` marks its part; a terminal tool keeps `terminalCommandState.exitCode` as `exit_code`;
+// - an MCP tool's `server` is its ToolDataSource label (`source: {type: 'mcp', label, serverLabel}`:
+//   the configured name, else the name the server reports). The toolId prefix (`mcp_<label>_<tool>`,
+//   sanitised and cut to a length) is not split: a label with '_' in it would be cut wrong. No
+//   `source` is written on messages: the Local store marks no request as injected or automated
+//   (hiddenFromTranscript is kept as `hidden`, not read as a source);
+// - writes lag the UI by up to ~2 minutes: a reply with no result and no final state is held back;
+// - title: the last `customTitle`; the file name stem is the session id; no fork link exists
+//   (a fork mints new ids and timestamps, in one kind 0 snapshot);
+// - redaction by field path: `selectedModel.metadata.auth`, wherever a `selectedModel` sits.
+
+const fs = require('fs');
+const path = require('path');
+const { fileURLToPath } = require('url');
+
+const HARNESS = 'vscode';
+const ENGINE = 'local';
+const SECRET_PATHS = [['selectedModel', 'metadata', 'auth']];
+const CLIENTS = { Code: 'vscode', 'Code - Insiders': 'vscode-insiders', 'Code - OSS': 'code-oss', VSCodium: 'vscodium' };
+// modelState.value, as VS Code's ResponseModelState: 0 pending, 1 complete, 2 cancelled, 3 failed,
+// 4 needs input. Only 1 is observed in the fixtures; the rest is UNVERIFIED.
+const MS = { PENDING: 0, COMPLETE: 1, CANCELLED: 2, FAILED: 3, NEEDS_INPUT: 4 };
+// isConfirmed.type, as VS Code's ToolConfirmKind: 0 denied, 1 not needed, 2 setting, 3 per tool,
+// 4 user action, 5 skipped. 1 and 4 are observed; 0 and 5 are UNVERIFIED.
+const CONFIRM_DENIED = 0;
+const CONFIRM_SKIPPED = 5;
+const UNSAFE_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+
+/** The default user-data folder of VS Code stable on this platform. */
+function storeRootDefault() {
+  // harness-paths' data folder: Application Support, APPDATA or XDG_CONFIG_HOME, as VS Code resolves it.
+  return require('../harness-paths').dataFolder(HARNESS);
+}
+
+/** A workspace's folder from workspaceStorage/<ws>/workspace.json: a path for file URIs, else the URI. */
+function workspaceFolder(wsDir) {
+  let j;
+  try { j = JSON.parse(fs.readFileSync(path.join(wsDir, 'workspace.json'), 'utf-8')); } catch { return ''; }
+  const uri = typeof j.folder === 'string' ? j.folder : (typeof j.workspace === 'string' ? j.workspace : '');
+  if (!uri.startsWith('file:')) return uri;
+  try { return fileURLToPath(uri); } catch { return decodeURIComponent(uri.replace(/^file:\/\//, '')); }
+}
+
+/**
+ * Sessions in one store (a VS Code user-data folder, the parent of User/). One entry per chat file;
+ * where one id has both a .json (pre-change-log) and a .jsonl file, the .jsonl wins. Each entry names
+ * its own chat file, so the runner re-reads it when that changes. The workspace.json is shared by the
+ * workspace's chats and not named; the cwd read from it is in the entry. Nothing in an entry moves
+ * while the file stays the same (the mtime only picks between two files).
+ */
+function list(storeRoot = storeRootDefault()) {
+  let harnessPath;
+  try { harnessPath = fs.realpathSync.native(storeRoot); } catch { return []; }
+  const client = CLIENTS[path.basename(harnessPath)] || 'vscode';
+  const user = path.join(harnessPath, 'User');
+  const wsRoot = path.join(user, 'workspaceStorage');
+  const dirs = [];
+  let wss = [];
+  try { wss = fs.readdirSync(wsRoot).sort(); } catch { wss = []; }
+  for (const ws of wss) dirs.push({ dir: path.join(wsRoot, ws, 'chatSessions'), wsDir: path.join(wsRoot, ws), workspace: ws });
+  dirs.push({ dir: path.join(user, 'globalStorage', 'emptyWindowChatSessions'), wsDir: null, workspace: '' });
+
+  const bySid = new Map();
+  for (const d of dirs) {
+    let names;
+    try { names = fs.readdirSync(d.dir).sort(); } catch { continue; }
+    let cwd = null;
+    for (const name of names) {
+      const m = /^(.+)\.(jsonl|json)$/.exec(name);
+      if (!m) continue;
+      const file = path.join(d.dir, name);
+      let st;
+      try { st = fs.statSync(file); } catch { continue; }
+      if (!st.isFile()) continue;
+      if (cwd === null) cwd = d.wsDir ? workspaceFolder(d.wsDir) : '';
+      const e = {
+        harness: HARNESS, session_id: m[1], file, format: m[2], workspace: d.workspace, cwd, client, harness_path: harnessPath, mtime: st.mtimeMs,
+      };
+      const prev = bySid.get(e.session_id);
+      const better = !prev || (e.format === 'jsonl' && prev.format !== 'jsonl') || (e.format === prev.format && e.mtime > prev.mtime);
+      if (better) bySid.set(e.session_id, e);
+    }
+  }
+  return [...bySid.values()].map(({ mtime, ...e }) => e);
+}
+
+/** Change-log lines: complete lines only (a partial last line is held back), malformed ones skipped. */
+function parseLog(text) {
+  const end = text.lastIndexOf('\n');
+  if (end < 0) return [];
+  const out = [];
+  for (const line of text.slice(0, end).split('\n')) {
+    if (!line.trim()) continue;
+    try { out.push(JSON.parse(line)); } catch { /* malformed: skipped */ }
+  }
+  return out;
+}
+
+/** Apply one change-log op to the state; returns the new state. */
+function applyOp(state, o) {
+  if (!o || typeof o !== 'object') return state;
+  if (o.kind === 0) return o.v && typeof o.v === 'object' ? o.v : null;
+  if (!state || typeof state !== 'object') return state;
+  const p = Array.isArray(o.k) ? o.k : null;
+  if (!p || !p.length || p.some((s) => UNSAFE_KEYS.has(String(s)))) return state;
+  let t = state;
+  for (let j = 0; j < p.length - 1; j++) {
+    if (t[p[j]] == null || typeof t[p[j]] !== 'object') {
+      if (o.kind === 3) return state;
+      t[p[j]] = typeof p[j + 1] === 'number' ? [] : {};
+    }
+    t = t[p[j]];
+  }
+  const last = p[p.length - 1];
+  if (o.kind === 1) t[last] = o.v;
+  else if (o.kind === 2) {
+    if (!Array.isArray(t[last])) t[last] = [];
+    const a = t[last];
+    if (Number.isInteger(o.i) && o.i >= 0 && o.i < a.length) a.length = o.i;
+    if (Array.isArray(o.v)) for (const x of o.v) a.push(x);
+  } else if (o.kind === 3) {
+    if (Array.isArray(t) && Number.isInteger(last)) t.splice(last, 1);
+    else delete t[last];
+  }
+  return state;
+}
+
+const reqId = (r) => (r && typeof r === 'object' && r.requestId ? String(r.requestId) : '');
+
+/**
+ * Fold a change log, and keep the requests' timeline beside the state: every request in the order it
+ * entered, and a `cut` entry where a kind 2 with i truncated `requests` (the cut requests, the time
+ * of the send that wrote it, the last request kept). Each kind 0 resets both.
+ */
+function replay(ops) {
+  let state = null;
+  let timeline = [];
+  const swap = (from, to) => { const e = timeline.find((x) => x.req === from); if (e) e.req = to; };
+  for (const o of ops) {
+    if (!o || typeof o !== 'object') continue;
+    if (o.kind === 0) {
+      state = applyOp(state, o);
+      timeline = state && Array.isArray(state.requests) ? state.requests.map((req) => ({ req })) : [];
+      continue;
+    }
+    const p = Array.isArray(o.k) ? o.k : [];
+    const reqs = state && Array.isArray(state.requests) ? state.requests : null;
+    if (p.length === 1 && p[0] === 'requests' && o.kind === 2) {
+      const added = Array.isArray(o.v) ? o.v : [];
+      const placed = new Set();
+      if (reqs && Number.isInteger(o.i) && o.i >= 0 && o.i < reqs.length) {
+        const cut = [];
+        for (const old of reqs.slice(o.i)) {
+          const same = reqId(old) ? added.find((x) => reqId(x) === reqId(old) && !placed.has(x)) : null;
+          if (same) { swap(old, same); placed.add(same); } else cut.push(old);
+        }
+        const first = added.find((x) => x && typeof x === 'object');
+        if (cut.length) timeline.push({ cut, at: first ? num(first.timestamp) : null, through: o.i > 0 ? reqs[o.i - 1] : null });
+      }
+      state = applyOp(state, o);
+      for (const x of added) if (!placed.has(x)) timeline.push({ req: x });
+      continue;
+    }
+    if (p.length === 2 && p[0] === 'requests' && reqs && (o.kind === 1 || o.kind === 3)) {
+      const old = reqs[p[1]];
+      state = applyOp(state, o);
+      if (o.kind === 1) { if (old) swap(old, state.requests[p[1]]); else timeline.push({ req: state.requests[p[1]] }); }
+      else timeline = timeline.filter((e) => e.req !== old);   // a delete: it vanishes
+      continue;
+    }
+    state = applyOp(state, o);
+    if (p[0] === 'requests' && p.length === 1) {
+      // The whole array replaced (never observed): what left it vanishes, what is new is appended.
+      const now = state && Array.isArray(state.requests) ? state.requests : [];
+      const nowSet = new Set(now);
+      timeline = timeline.filter((e) => e.cut || nowSet.has(e.req));
+      const known = new Set(timeline.map((e) => e.req));
+      for (const r of now) if (!known.has(r)) timeline.push({ req: r });
+    }
+  }
+  return { state, timeline };
+}
+
+/** Fold a change log into the session state. Each kind 0 resets everything before it. */
+function fold(ops) {
+  return replay(ops).state;
+}
+
+function canonical(v) {
+  if (Array.isArray(v)) return `[${v.map(canonical).join(',')}]`;
+  if (v && typeof v === 'object') return `{${Object.keys(v).sort().map((k) => `${JSON.stringify(k)}:${canonical(v[k])}`).join(',')}}`;
+  return JSON.stringify(v === undefined ? null : v);
+}
+const isMarker = (v) => typeof v === 'string' && /^<redacted len=\d+>$/.test(v);
+function marker(v) {
+  const n = typeof v === 'string' ? Buffer.byteLength(v, 'utf-8') : Buffer.byteLength(canonical(v), 'utf-8');
+  return `<redacted len=${n}>`;
+}
+
+/** Redact every declared secret path in place, at any depth (sessions-model §4). Returns the state. */
+function redact(state) {
+  const stack = [state];
+  while (stack.length) {
+    const o = stack.pop();
+    if (!o || typeof o !== 'object') continue;
+    for (const sp of SECRET_PATHS) {
+      let t = o;
+      for (let j = 0; j < sp.length - 1 && t && typeof t === 'object'; j++) t = Object.prototype.hasOwnProperty.call(t, sp[j]) ? t[sp[j]] : null;
+      const leaf = sp[sp.length - 1];
+      if (t && typeof t === 'object' && Object.prototype.hasOwnProperty.call(t, leaf) && t[leaf] != null && !isMarker(t[leaf])) t[leaf] = marker(t[leaf]);
+    }
+    for (const v of Array.isArray(o) ? o : Object.values(o)) if (v && typeof v === 'object') stack.push(v);
+  }
+  return state;
+}
+
+const num = (v) => { const x = Number(v); return Number.isFinite(x) && x > 0 ? Math.trunc(x) : null; };
+const str = (v) => (typeof v === 'string' ? v : '');
+function argsOf(a) {
+  if (a == null) return null;
+  if (typeof a === 'string') { try { return JSON.parse(a); } catch { return { raw: a }; } }
+  return a;
+}
+function uriPath(u) {
+  if (!u) return '';
+  if (typeof u === 'string') return u;
+  if (typeof u !== 'object') return '';
+  return str(u.fsPath) || str(u.path) || str(u.external) || (u.uri ? uriPath(u.uri) : '');
+}
+
+/** A prompt-tsx node tree ($mid 23) as text: its text leaves in order, honouring lineBreakBefore. */
+function tsxText(node) {
+  let out = '';
+  const walk = (n) => {
+    if (!n || typeof n !== 'object') return;
+    if (typeof n.text === 'string') {
+      if (n.lineBreakBefore && out && !out.endsWith('\n')) out += '\n';
+      out += n.text;
+    }
+    if (Array.isArray(n.children)) n.children.forEach(walk);
+  };
+  walk(node);
+  return out;
+}
+/** The text of one toolCallResults entry, as the model saw it. */
+function toolResultText(r) {
+  if (r == null) return null;
+  if (typeof r === 'string') return r;
+  const content = Array.isArray(r.content) ? r.content : [];
+  return content.map((c) => {
+    if (!c || typeof c !== 'object') return typeof c === 'string' ? c : '';
+    if (typeof c.value === 'string') return c.value;
+    if (c.value && typeof c.value === 'object' && c.value.node) return tsxText(c.value.node);
+    return typeof c.text === 'string' ? c.text : '';
+  }).join('');
+}
+
+/** The model's own tool calls, by the call id VS Code shows (the round id without `__vscode-<n>`). */
+function roundCalls(meta) {
+  const map = new Map();
+  const results = meta.toolCallResults && typeof meta.toolCallResults === 'object' ? meta.toolCallResults : {};
+  for (const rd of Array.isArray(meta.toolCallRounds) ? meta.toolCallRounds : []) {
+    for (const tc of (rd && Array.isArray(rd.toolCalls)) ? rd.toolCalls : []) {
+      const full = String((tc && tc.id) || '');
+      if (!full) continue;
+      const base = full.split('__vscode-')[0];
+      if (!map.has(base)) map.set(base, { name: str(tc.name), arguments: tc.arguments, ts: num(rd.timestamp), result: Object.prototype.hasOwnProperty.call(results, full) ? results[full] : null });
+    }
+  }
+  return map;
+}
+
+/** The served model: Auto's resolution, never the `copilot/auto` placeholder. */
+function servedModel(r, resp, meta) {
+  if (str(meta.resolvedModel)) return meta.resolvedModel;
+  for (const p of resp) if (p && p.kind === 'autoModeResolution' && p.resolved && str(p.resolved.id)) return p.resolved.id;
+  const rounds = Array.isArray(meta.toolCallRounds) ? meta.toolCallRounds : [];
+  for (let i = rounds.length - 1; i >= 0; i--) if (rounds[i] && str(rounds[i].modelId)) return rounds[i].modelId;
+  const id = str(r.modelId);
+  return id && !/(^|\/)auto$/.test(id) ? id : '';
+}
+
+/**
+ * How the reply ended, or null while it is still being written (held back). A reply that a later
+ * request follows has ended even without a result.
+ */
+function replyStatus(r, isLast) {
+  const ms = r.modelState && typeof r.modelState === 'object' ? r.modelState.value : undefined;
+  if (r.isCanceled === true || ms === MS.CANCELLED) return 'cancelled';
+  if (ms === MS.FAILED) return 'error';
+  const running = ms === MS.PENDING || ms === MS.NEEDS_INPUT || (ms == null && !r.result);
+  if (running && isLast) return null;
+  if (r.result && r.result.errorDetails) return 'error';
+  if (running) return r.result ? 'complete' : 'interrupted';
+  return 'complete';
+}
+
+function toolPart(p, partId, callId, call) {
+  const tsd = p.toolSpecificData && typeof p.toolSpecificData === 'object' ? p.toolSpecificData : {};
+  let args = call ? argsOf(call.arguments) : null;
+  if (args == null && tsd.kind === 'terminal' && tsd.commandLine) {
+    const cl = tsd.commandLine;
+    args = { command: typeof cl === 'string' ? cl : str(cl.original) || str(cl.toolEdited) || str(cl.forDisplay) };
+  }
+  let output = call && call.result != null ? toolResultText(call.result) : null;
+  if (output == null && tsd.kind === 'terminal' && tsd.terminalCommandOutput && typeof tsd.terminalCommandOutput.text === 'string') output = tsd.terminalCommandOutput.text;
+  if (output == null && typeof p.resultError === 'string' && p.resultError) output = p.resultError;
+  const confirm = p.isConfirmed && typeof p.isConfirmed === 'object' ? p.isConfirmed.type : undefined;
+  const denied = confirm === CONFIRM_DENIED;
+  const skipped = confirm === CONFIRM_SKIPPED;
+  const isError = denied || p.resultError === true || (typeof p.resultError === 'string' && p.resultError !== '');
+  const done = p.isComplete === true || output != null;
+  const tstate = tsd.kind === 'terminal' && tsd.terminalCommandState && typeof tsd.terminalCommandState === 'object' ? tsd.terminalCommandState : {};
+  const exit = typeof tstate.exitCode === 'number' && Number.isFinite(tstate.exitCode) ? tstate.exitCode : null;
+  const src = p.source && typeof p.source === 'object' ? p.source : {};
+  const server = src.type === 'mcp' ? str(src.label) || str(src.serverLabel) : '';
+  return {
+    part_id: partId, kind: 'tool', call_id: callId, tool: (call && call.name) || str(p.toolId), args: args || {},
+    output, is_error: isError,
+    status: denied ? 'denied' : skipped ? 'cancelled' : isError ? 'error' : done ? 'completed' : 'interrupted',
+    ...(exit !== null ? { exit_code: exit } : {}),
+    ...(server ? { server } : {}),
+    ...(p.presentation === 'hidden' || p.presentation === 'hiddenAfterComplete' ? { hidden: true } : {}),
+    ...(call && call.ts ? { ts: call.ts } : {}),
+  };
+}
+
+function inlineLabel(p) {
+  const ir = p.inlineReference && typeof p.inlineReference === 'object' ? p.inlineReference : {};
+  const name = str(p.name) || str(ir.name);
+  if (name) return `\`${name}\``;
+  const ref = uriPath(ir.uri || ir.location || ir);
+  return ref ? path.posix.basename(ref) : '';
+}
+function thinkingText(v) {
+  if (typeof v === 'string') return v;
+  if (Array.isArray(v)) return v.map((x) => (typeof x === 'string' ? x : str(x && x.value))).join('');
+  return '';
+}
+
+/** The reply's parts in native order; a sub-agent's own calls are split out by subAgentInvocationId. */
+function replyParts(resp, aid, calls) {
+  const main = [];
+  const subs = new Map();
+  let run = null;
+  const close = () => { run = null; };
+  const addText = (i, s) => {
+    if (!s) return;
+    if (!run) { run = { part_id: String(i), kind: 'text', text: '' }; main.push(run); }
+    run.text += s;
+  };
+  for (let i = 0; i < resp.length; i++) {
+    const p = resp[i];
+    if (!p || typeof p !== 'object') continue;
+    const kind = p.kind;
+    if (kind == null || kind === 'markdownContent') { addText(i, str(p.value) || str(p.content && p.content.value)); continue; }
+    if (kind === 'markdownVuln') { addText(i, str(p.content && p.content.value) || str(p.value)); continue; }
+    if (kind === 'inlineReference') { addText(i, inlineLabel(p)); continue; }
+    if (kind === 'thinking') {
+      const text = thinkingText(p.value);
+      if (!text && !p.id) continue;   // the reasoning-done marker, not a block
+      close();
+      main.push(text ? { part_id: String(i), kind: 'reasoning', text } : { part_id: String(i), kind: 'reasoning', opaque: true });
+      continue;
+    }
+    if (kind === 'toolInvocationSerialized' || kind === 'toolInvocation') {
+      close();
+      const id = str(p.toolCallId);
+      const part = toolPart(p, String(i), id || `@${aid}:${i}`, id ? calls.get(id) : null);
+      const sub = str(p.subAgentInvocationId);
+      if (sub) { if (!subs.has(sub)) subs.set(sub, []); subs.get(sub).push(part); } else main.push(part);
+      continue;
+    }
+    if (kind === 'warning') {
+      const text = str(p.content && p.content.value) || str(p.value);
+      if (text) { close(); main.push({ part_id: String(i), kind: 'notice', text }); }
+      continue;
+    }
+    // Bookkeeping and UI state (mcpServersStarting, autoModeResolution, undoStop, codeblockUri,
+    // textEditGroup, progressMessage, confirmation, …): not conversation, and it does not split text.
+  }
+  return { main: main.filter((x) => x.kind !== 'text' || x.text.trim()), subs };
+}
+
+function userParts(r) {
+  const parts = [];
+  const msg = r.message && typeof r.message === 'object' ? r.message : {};
+  const text = typeof msg.text === 'string' ? msg.text
+    : (Array.isArray(msg.parts) ? msg.parts.map((x) => str(x && x.text)).join('') : (typeof r.message === 'string' ? r.message : ''));
+  if (text) parts.push({ part_id: '0', kind: 'text', text });
+  const vars = r.variableData && Array.isArray(r.variableData.variables) ? r.variableData.variables : [];
+  vars.forEach((v, j) => {
+    if (!v || typeof v !== 'object') return;
+    const image = v.kind === 'image' || v.isImage === true;
+    const file = v.kind === 'file' || v.kind === 'directory' || v.isFile === true || v.isDirectory === true;
+    if (!image && !file) return;
+    const ref = uriPath(v.value) || uriPath(Array.isArray(v.references) && v.references[0] && v.references[0].reference) || str(v.name);
+    // The store keeps no image bytes (a path and an asset id only), so there is no sha to give.
+    parts.push({ part_id: `var:${j}`, kind: 'file', media_type: str(v.mimeType), att_sha: null, att_len: null, ref });
+  });
+  return parts;
+}
+
+/** The folded state and the requests' timeline (a snapshot alone gives a timeline with no cuts). */
+function load(session) {
+  const snap = (state) => ({ state, timeline: state && Array.isArray(state.requests) ? state.requests.map((req) => ({ req })) : [] });
+  if (session.state && typeof session.state === 'object') return snap(JSON.parse(JSON.stringify(session.state)));
+  if (Array.isArray(session.ops)) return replay(session.ops.map((o) => (typeof o === 'string' ? JSON.parse(o) : JSON.parse(JSON.stringify(o)))));
+  let text = typeof session.text === 'string' ? session.text : null;
+  if (text == null) {
+    try { text = fs.readFileSync(session.file, 'utf-8'); } catch { return snap(null); }
+  }
+  const json = session.format === 'json' || (session.file && /\.json$/.test(session.file));
+  if (json) { try { return snap(JSON.parse(text)); } catch { return snap(null); } }
+  return replay(parseLog(text));
+}
+
+/** One request's messages: the user message, then (once it has ended) the reply and its sub-agents. */
+function requestMessages(r, { isLast, retracted, next }) {
+  const uid = String(r.requestId);
+  const state = retracted ? 'retracted' : 'current';
+  const hidden = r.hiddenFromTranscript === true ? { hidden: true } : {};
+  const out = [{ k: 'message', message_id: uid, role: 'user', ts: num(r.timestamp), order: next(), state, status: 'complete', ...hidden, parts: userParts(r) }];
+
+  const status = replyStatus(r, isLast);
+  if (!status) return out;   // still being written: held back until it has a result
+  const aid = r.responseId ? String(r.responseId) : `${uid}:response`;
+  const meta = (r.result && r.result.metadata && typeof r.result.metadata === 'object') ? r.result.metadata : {};
+  const resp = Array.isArray(r.response) ? r.response : (r.response && typeof r.response === 'object' ? Object.values(r.response) : []);
+  const model = servedModel(r, resp, meta);
+  const requested = str(r.modelId);
+  const { main, subs } = replyParts(resp, aid, roundCalls(meta));
+  const err = r.result && r.result.errorDetails;
+  if (err && str(err.message)) main.push({ part_id: 'error', kind: 'error', text: err.message });
+  const summary = typeof meta.summary === 'string' ? meta.summary : str(meta.summary && meta.summary.text);
+  if (summary) main.push({ part_id: 'summary', kind: 'summary', text: summary, replaces: 'unknown' });
+  const input = num(r.promptTokens) ?? num(meta.promptTokens);
+  const output = num(r.completionTokens);
+  const credits = typeof r.copilotCredits === 'number' && Number.isFinite(r.copilotCredits) && r.copilotCredits > 0 ? r.copilotCredits : null;
+  const ts = num(r.responseTimestamp) ?? num(r.timestamp);
+  out.push({
+    k: 'message', message_id: aid, role: 'assistant', ts, order: next(), parent_id: uid, state, status,
+    model, model_requested: requested, effort: '', ...hidden,
+    usage: input != null || output != null || credits != null
+      ? { basis: 'unknown', input, output, cache_read: null, cache_write: null, reasoning: null, cost: null, credits } : null,
+    parts: main,
+  });
+  // A sub-agent's calls carry subAgentInvocationId: its own speaker, anchored to the reply's id.
+  let s = 0;
+  for (const [agent, parts] of subs) {
+    out.push({ k: 'message', message_id: `${aid}+${++s}`, role: 'assistant', ts, order: next(), parent_id: aid, agent_id: agent, state, status, model, model_requested: requested, effort: '', ...hidden, usage: null, parts });
+  }
+  return out;
+}
+
+/**
+ * Normalise one session. `session` is a list() entry, or `{ session_id, ops: [...] }` / `{ session_id,
+ * text }` / `{ session_id, state }` already loaded (tests), with optional `cwd` and `client`. Returns the
+ * log records: the session record first, then the messages and lifecycle records in native order (the
+ * order requests entered the change log); null if there is no state.
+ */
+function normalise(session) {
+  const { state, timeline } = load(session);
+  if (!state || typeof state !== 'object' || Array.isArray(state)) return null;
+  redact(state);
+  for (const e of timeline) if (e.cut) redact(e.cut);
+  const reqs = Array.isArray(state.requests) ? state.requests : [];
+  const current = new Set(reqs);
+  const lastReq = reqs[reqs.length - 1];
+  const retractedReqs = new Set(timeline.flatMap((e) => e.cut || []));
+  // Keys stay unique: a retracted copy never shadows a current message with the same id.
+  const currentIds = new Set();
+  for (const r of reqs) if (reqId(r)) { currentIds.add(reqId(r)); currentIds.add(r.responseId ? String(r.responseId) : `${reqId(r)}:response`); }
+
+  const records = [];
+  const idsOf = new Map();   // request → the message ids written for it
+  const seen = new Set();
+  let order = 0;
+  const next = () => order++;
+  let version = '';
+  for (const e of timeline) {
+    if (e.req) {
+      const r = e.req;
+      if (!reqId(r)) continue;   // no native id: nothing to key it by
+      const live = current.has(r);
+      const retracted = !live && retractedReqs.has(r);
+      if (!live && !retracted) continue;
+      if (retracted && (currentIds.has(reqId(r)) || seen.has(reqId(r)))) continue;
+      // The FIRST request's extension version: an extension update must not rewrite the session line.
+      if (live && !version && r.agent && str(r.agent.extensionVersion)) version = r.agent.extensionVersion;
+      const msgs = requestMessages(r, { isLast: r === lastReq, retracted, next });
+      for (const m of msgs) seen.add(m.message_id);
+      idsOf.set(r, msgs.map((m) => m.message_id));
+      records.push(...msgs);
+      continue;
+    }
+    // A kind 2 with i: the requests it cut stay above, retracted; this records the act.
+    const ids = e.cut.flatMap((r) => idsOf.get(r) || []);
+    if (!ids.length) continue;
+    const kept = e.through ? idsOf.get(e.through) : null;
+    records.push({ k: 'lifecycle', event: 'rewind', at: e.at, message_ids: ids, through: kept && kept.length ? kept[kept.length - 1] : null });
+  }
+  const messages = records;
+
+  const head = {
+    k: 'session',
+    title: str(state.customTitle),
+    cwd: str(session.cwd),
+    created: num(state.creationDate),
+    updated: null, archived: null,
+    version,
+    incarnation: '',
+    engine: ENGINE,
+    client: str(session.client),
+    links: [],
+  };
+  return [head, ...messages];
+}
+
+module.exports = { HARNESS, ENGINE, SECRET_PATHS, list, normalise, parseLog, replay, fold, applyOp, redact, storeRootDefault };