@volter/supercode-interchange 0.1.1 → 0.1.3

package/session-follower.mjs

@@ -0,0 +1,181 @@
+// Passive persisted-history following. The owner chooses when to poll; this
+// object starts no timer, runtime, process or filesystem watcher.
+import { stat, lstat, readdir } from 'node:fs/promises';
+import { basename, dirname, extname, join, resolve } from 'node:path';
+import { nativeJsonEqual, setNativeInteger } from './native-json.mjs';
+import { normalizedSessionJson } from './session-model.mjs';
+import { messageJson } from './message.mjs';
+import { boundSessionView } from './session-views.mjs';
+import { looksLikeSessionSqlite, loadNativeStoreFamily, loadSessionPath } from './session-path.mjs';
+import { loadSessionDisplayPath } from './session-display.mjs';
+import { readGooseSqlite } from './session-goose.mjs';
+import { readHermesSqlite } from './session-hermes.mjs';
+import { readOpenCodeSqlite } from './session-opencode-store.mjs';
+import { ClaudeAppendState } from './session-claude-append.mjs';
+
+const pathOrder = (a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b));
+const identityKeys = ['source', 'session_id', 'model', 'cwd', 'system_prompt', 'agent_id', 'parent_tool_use_id', 'lineage'];
+const sameIdentity = (left, right) => identityKeys.every((key) => nativeJsonEqual(left.meta[key], right.meta[key]));
+const sameChildren = (left, right) => left.subagents.length === right.subagents.length
+  && left.subagents.every((child, at) => normalizedEqual(child, right.subagents[at]));
+function normalizedEqual(left, right) {
+  return sameIdentity(left, right) && nativeJsonEqual(left.messages, right.messages) && sameChildren(left, right)
+    && left.parse_error_lines === right.parse_error_lines && nativeJsonEqual(left.load_residue, right.load_residue);
+}
+
+/** Longest suffix of the retained window which is a prefix of the successor.
+ * KMP keeps repetitive histories linear in message comparisons. */
+function overlap(current, next) {
+  if (!current.length || !next.length) return 0;
+  const prefix = new Uint32Array(next.length);
+  for (let at = 1, length = 0; at < next.length; at++) {
+    while (length && !nativeJsonEqual(next[at], next[length])) length = prefix[length - 1];
+    if (nativeJsonEqual(next[at], next[length])) length++;
+    prefix[at] = length;
+  }
+  let length = 0;
+  for (const message of current) {
+    while (length && (length === next.length || !nativeJsonEqual(message, next[length]))) length = prefix[length - 1];
+    if (nativeJsonEqual(message, next[length])) length++;
+  }
+  return length;
+}
+function appendPrefix(current, next) {
+  const plain = overlap(current, next);
+  const anchored = next.length > 1 && current.length > 1 && nativeJsonEqual(current[0], next[0])
+    ? overlap(current.slice(1), next.slice(1)) : 0;
+  return Math.max(plain, anchored ? anchored + 1 : 0);
+}
+
+async function pathStamp(path, follow = true) {
+  let info;
+  try { info = await (follow ? stat : lstat)(path, { bigint: true }); }
+  catch (error) { if (error.code !== 'ENOENT') throw error; return { path, kind: 'missing' }; }
+  return { path, kind: info.isFile() ? 'file' : info.isDirectory() ? 'directory' : 'other',
+    device: String(info.dev), inode: String(info.ino), size: String(info.size),
+    modified_ns: info.mtimeNs < 0n ? null : String(info.mtimeNs) };
+}
+async function collectTree(path, out) {
+  const pending = [{ path, follow: true }];
+  while (pending.length) {
+    const entry = pending.pop(), stamp = await pathStamp(entry.path, entry.follow); out.push(stamp);
+    // Follow the named root, never a nested symlink (or its cycle).
+    if (stamp.kind !== 'directory') continue;
+    const children = (await readdir(entry.path)).sort(pathOrder);
+    for (let at = children.length - 1; at >= 0; at--) pending.push({ path: join(entry.path, children[at]), follow: false });
+  }
+}
+async function sourceFingerprint(path, session, selected, includeSubagents) {
+  const stamps = [await pathStamp(path)], source = session.meta.source;
+  const directory = dirname(path), name = basename(path, extname(path));
+  if (source === 'claude_code' && includeSubagents) await collectTree(join(directory, name, 'subagents'), stamps);
+  if (['opencode', 'hermes', 'goose'].includes(source) && await looksLikeSessionSqlite(path)) {
+    // All supported SQLite stores can commit to their WAL before checkpointing.
+    stamps.push(await pathStamp(`${path}-wal`), await pathStamp(`${path}-shm`));
+    if (source === 'opencode' && selected != null) stamps.push(await pathStamp(join(directory, 'storage', 'session_diff', `${selected}.json`)));
+  }
+  if (source === 'grok') stamps.push(await pathStamp(join(directory, 'updates.jsonl')), await pathStamp(join(directory, 'summary.json')));
+  if (source === 'native') {
+    stamps.push(await pathStamp(join(directory, `${name}.sidecar.jsonl`)), await pathStamp(join(directory, `${name}.meta.json`)));
+    await collectTree(join(directory, `${name}.subagents`), stamps);
+  }
+  return stamps.sort((a, b) => pathOrder(a.path, b.path));
+}
+
+export class SessionFollower {
+  static async open(path, options = {}) { return this.#open(path, options.selector ?? null, options.store ?? 'opencode', options); }
+  static async openLocator(locator, options = {}) {
+    const hermes = locator.harness === 'hermes', sqlite = locator.storage.kind === 'sqlite';
+    return this.#open(locator.storage.path, hermes ? locator.session_id : sqlite ? locator.storage.selector : null,
+      hermes ? 'hermes' : sqlite && locator.harness === 'goose' ? 'goose' : 'opencode', options);
+  }
+  static async #open(path, selected, store, options) {
+    if (typeof path !== 'string') throw new TypeError('a session follower requires a path');
+    for (const key of ['messageLimit', 'maxMessageChars']) if (options[key] != null && (!Number.isSafeInteger(options[key]) || options[key] < 0)) throw new TypeError(`${key} must be a nonnegative exact integer`);
+    if (!['opencode', 'hermes', 'goose'].includes(store)) throw new TypeError(`unknown session store: ${store}`);
+    const follower = new SessionFollower();
+    follower.path = resolve(path); follower.selected = selected; follower.store = store;
+    follower.options = { ...options, fidelity: options.fidelity ?? 'byte_lossless', includeSubagents: options.includeSubagents ?? true };
+    const sqlite = await looksLikeSessionSqlite(follower.path);
+    if (selected != null && !sqlite) throw new Error(`an OpenCode session selector requires a SQLite store; ${follower.path} is not one`);
+    follower.current = await follower.#load();
+    if (sqlite && selected == null) follower.selected = follower.current.meta.session_id;
+    // Discover the dialect/default selector, then bracket the opening read's
+    // actual companions. Unrelated neighboring files are never admission
+    // dependencies, and one OpenCode follow never walks every diff sidecar.
+    const before = await sourceFingerprint(follower.path, follower.current, follower.selected, follower.options.includeSubagents);
+    const opening = await follower.#load();
+    if (opening.meta.source !== follower.current.meta.source
+      || !nativeJsonEqual(before, await sourceFingerprint(follower.path, follower.current, follower.selected, follower.options.includeSubagents))) throw new Error(`${follower.path} changed while opening its follower; retry the read`);
+    follower.current = opening;
+    follower.appendState = follower.#appendState(opening);
+    boundSessionView(follower.current, options.messageLimit, options.maxMessageChars);
+    follower.fingerprint = before;
+    follower.initialPending = true; follower.nextSequence = 1n; follower.closed = false;
+    return follower;
+  }
+  async #load() {
+    const { path, selected, store, options } = this;
+    if (await looksLikeSessionSqlite(path)) {
+      if (store === 'goose') {
+        if (selected == null) throw new Error('a Goose SQLite locator requires a session selector');
+        return (await readGooseSqlite(path, selected, options)).result;
+      }
+      if (store === 'hermes') {
+        if (selected == null) throw new Error('a Hermes SQLite locator requires a session selector');
+        return (await readHermesSqlite(path, selected, options)).result;
+      }
+      return (await readOpenCodeSqlite(path, selected, options)).result;
+    }
+    const native = await loadNativeStoreFamily(path, options); if (native != null) return native;
+    return options.displayHistory ? loadSessionDisplayPath(path, options.messageLimit ?? 500, options) : loadSessionPath(path, options);
+  }
+  #sequence(event) { setNativeInteger(event, 'sequence', this.nextSequence++); return event; }
+  #appendState(session) {
+    if (this.options.displayHistory) return null;
+    try { return ClaudeAppendState.fromSession(session, this.options.fidelity); } catch { return null; }
+  }
+  #snapshot(reason) { return this.#sequence({ type: 'session_snapshot', reason, session: normalizedSessionJson(this.current) }); }
+  #error(message) { return this.#sequence({ type: 'watch_error', recoverable: true, message }); }
+  /** Serial polls only; a service serializes them per follower. */
+  async poll() {
+    if (this.closed) throw new Error('the session follower is closed');
+    if (this.initialPending) { this.initialPending = false; return this.#snapshot('initial'); }
+    const observed = await sourceFingerprint(this.path, this.current, this.selected, this.options.includeSubagents);
+    if (nativeJsonEqual(observed, this.fingerprint)) return null;
+    const companionsSame = nativeJsonEqual(observed.filter((stamp) => stamp.path !== this.path), this.fingerprint.filter((stamp) => stamp.path !== this.path));
+    this.fingerprint = observed;
+    let next;
+    try {
+      const appended = companionsSame && this.appendState
+        ? await this.appendState.append(this.path, this.current, this.options.fidelity, this.options).catch(() => null) : null;
+      next = appended?.session ?? await this.#load();
+      if (next.parse_error_lines > 0) return this.#error(`${this.path} contains ${next.parse_error_lines} malformed or truncated JSON line(s); retaining the last good snapshot`);
+      const after = await sourceFingerprint(this.path, this.current, this.selected, this.options.includeSubagents);
+      const stale = () => Object.assign(new Error('the source or its companions changed during the follow read'), { code: 'ESTALE' });
+      if (!nativeJsonEqual(observed, after)) throw stale();
+      if (next.meta.source !== this.current.meta.source) {
+        // A changed dialect has a different companion set. Bracket a read
+        // under that set before publishing it, rather than stamping new
+        // companions beside a snapshot which preceded their last mutation.
+        const source = next.meta.source, before = await sourceFingerprint(this.path, next, this.selected, this.options.includeSubagents);
+        next = await this.#load();
+        if (next.meta.source !== source || !nativeJsonEqual(before, await sourceFingerprint(this.path, next, this.selected, this.options.includeSubagents))) throw stale();
+        this.fingerprint = before;
+      }
+      this.appendState = appended?.state ?? this.#appendState(next);
+      boundSessionView(next, this.options.messageLimit, this.options.maxMessageChars);
+    } catch (error) {
+      if (error.code === 'ESTALE') this.fingerprint = []; // retry a raced read even if the last writer then stopped
+      return this.#error(`could not reload ${this.path}: ${error.message}; retaining the last good snapshot`);
+    }
+    if (normalizedEqual(this.current, next)) { this.current = next; return null; }
+    const identitySame = sameIdentity(this.current, next);
+    const prefix = identitySame && sameChildren(this.current, next) ? appendPrefix(this.current.messages, next.messages) : 0;
+    this.current = next;
+    if (prefix > 0 && next.messages.length > prefix) return this.#sequence({ type: 'messages_appended', session_id: next.meta.session_id,
+      messages: next.messages.slice(prefix).map(messageJson), total_message_count: Math.max(next.imported_message_count ?? next.messages.length, next.messages.length) });
+    return this.#snapshot(identitySame ? 'history_rewritten' : 'source_changed');
+  }
+  close() { this.closed = true; this.current = null; this.fingerprint = []; this.appendState = null; }
+}

package/session-gemini.mjs

@@ -0,0 +1,93 @@
+import { createMessage } from './message.mjs';
+import { parseNativeJson, stringifyNativeJsonMember } from './native-json.mjs';
+import { createSession } from './session-model.mjs';
+import { splitLinesVerbatim } from './session-lines.mjs';
+import { nativeTrim } from './text.mjs';
+import {
+  field, stringField, valueString, functionCall, toolMessage, ensureToolResultsPaired,
+  stampMessageRecords, takeMessageRecords, restoreGeminiMessageExtension,
+} from './session-codec-utils.mjs';
+
+function pushUserParts(messages, parts, timestamp, source) {
+  if (!parts.length) return;
+  const message = createMessage('user');
+  message.content_parts = parts;
+  if (timestamp != null) message.metadata.timestamp = timestamp;
+  restoreGeminiMessageExtension(source, message);
+  messages.push(message);
+}
+
+/** Gemini's document reader. Unknown native records stay in the exact raw
+ * capture; this decoder does not open a store or a service. */
+export function fromGeminiStr(text) {
+  const session = createSession('gemini'), { meta, messages } = session;
+  const capture = splitLinesVerbatim(text);
+  session.raw = capture.lines; session.raw_trailing_newline = capture.trailingNewline; session.raw_is_verbatim = true;
+  const records = capture.lines.map((line, index) => ({ line: nativeTrim(line), index })).filter((record) => record.line !== '');
+  const pending = new Map();
+  for (let lineIndex = 0; lineIndex < records.length; lineIndex++) {
+    if (lineIndex > 0) stampMessageRecords(messages, records[lineIndex - 1].index);
+    let value;
+    try { value = parseNativeJson(records[lineIndex].line); } catch { session.parse_error_lines++; continue; }
+    const kind = stringField(value, 'type');
+    if (kind == null) {
+      meta.session_id ??= stringField(value, 'sessionId');
+      for (const [key, target] of [['projectHash', 'gemini_project_hash'], ['startTime', 'created_at'], ['lastUpdated', 'updated_at'], ['kind', 'gemini_session_kind']]) {
+        if (field(value, key) !== undefined) meta.lineage[target] = valueString(value, key);
+      }
+      continue;
+    }
+    if (kind !== 'user' && kind !== 'gemini') continue;
+    const timestamp = stringField(value, 'timestamp'), model = stringField(value, 'model');
+    if (model != null) meta.model = model;
+    const content = field(value, 'content'), parts = Array.isArray(content) ? content : null;
+    const contentText = typeof content === 'string' ? content : parts ? nativeTrim(parts.map((part) => stringField(part, 'text')).filter((part) => part != null).join(' ')) : '';
+    if (kind === 'gemini') {
+      const nativeCalls = field(value, 'toolCalls'), calls = [];
+      const candidates = [...(Array.isArray(nativeCalls) ? nativeCalls : []), ...(parts ?? []).filter((part) => field(part, 'functionCall') !== undefined).map((part) => part.functionCall)];
+      for (let callIndex = 0; callIndex < candidates.length; callIndex++) {
+        const call = candidates[callIndex], name = stringField(call, 'name');
+        if (name == null) continue;
+        const id = stringField(call, 'id') ?? `gemini-${lineIndex}-${callIndex}`;
+        if (!pending.has(name)) pending.set(name, []);
+        pending.get(name).push(id);
+        calls.push(functionCall(id, name, field(call, 'args') === undefined ? '{}' : valueString(call, 'args')));
+      }
+      const message = createMessage('assistant', contentText === '' ? null : contentText);
+      message.tool_calls = calls.length ? calls : null;
+      if (timestamp != null) message.metadata.timestamp = timestamp;
+      if (model != null) message.metadata.gemini_model = model;
+      if (field(value, 'thoughts') != null) message.metadata.gemini_thoughts = stringifyNativeJsonMember(value, 'thoughts');
+      restoreGeminiMessageExtension(value, message);
+      if (message.content != null || message.tool_calls != null) messages.push(message);
+      continue;
+    }
+    let userParts = [];
+    if (parts) {
+      for (const part of parts) {
+        const response = field(part, 'functionResponse');
+        if (response !== undefined) {
+          pushUserParts(messages, userParts, timestamp, value); userParts = [];
+          const name = stringField(response, 'name') ?? 'tool', explicitId = stringField(response, 'id'), ids = pending.get(name);
+          if (explicitId != null && ids) { const at = ids.indexOf(explicitId); if (at >= 0) ids.splice(at, 1); }
+          const id = explicitId ?? (ids?.length ? ids.shift() : `gemini-${lineIndex}-response`);
+          const payload = field(response, 'response'), output = field(payload, 'output');
+          const body = output !== undefined ? valueString(payload, 'output') : payload !== undefined ? stringifyNativeJsonMember(response, 'response') : '';
+          const message = toolMessage(id, body); message.name = name;
+          if (timestamp != null) message.metadata.timestamp = timestamp;
+          restoreGeminiMessageExtension(value, message); messages.push(message);
+          continue;
+        }
+        const partText = stringField(part, 'text');
+        if (partText != null) { userParts.push({ type: 'text', text: partText }); continue; }
+        const inline = field(part, 'inlineData'), data = stringField(inline, 'data');
+        if (data != null) userParts.push({ type: 'image_url', image_url: { url: `data:${stringField(inline, 'mimeType') ?? 'application/octet-stream'};base64,${data}` } });
+      }
+    } else if (contentText !== '') userParts.push({ type: 'text', text: contentText });
+    pushUserParts(messages, userParts, timestamp, value);
+  }
+  if (records.length) stampMessageRecords(messages, records.at(-1).index);
+  ensureToolResultsPaired(messages);
+  meta.message_records = takeMessageRecords(messages); session.imported_message_count = messages.length;
+  return session;
+}

package/session-goose.mjs

@@ -0,0 +1,139 @@
+import { createMessage, markToolError } from './message.mjs';
+import { cloneNativeJson, nativeInteger, parseNativeJson, setNativeInteger, stringifyNativeJson, stringifyNativeJsonMember, stringifyNativeJsonPretty } from './native-json.mjs';
+import { createSession } from './session-model.mjs';
+import { splitLinesVerbatim } from './session-lines.mjs';
+import { readStore, statement, text as columnText, integer as columnInteger } from './sqlite-reader.mjs';
+import { isObject, field, stringField, valueString, functionCall, toolMessage, ensureToolResultsPaired, restoreGrokMessageExtension } from './session-codec-utils.mjs';
+
+function captureMetadata(native, message) {
+  const created = nativeInteger(native, 'created', { signed: true }), id = stringField(native, 'id');
+  if (created != null) message.metadata.goose_created = String(created);
+  if (id != null) message.metadata.goose_message_id = id;
+  if (field(native, 'metadata') !== undefined) message.metadata.goose_metadata = stringifyNativeJsonMember(native, 'metadata');
+}
+
+function normalizeMessage(native, nativeIndex, out) {
+  const role = stringField(native, 'role') === 'assistant' ? 'assistant' : 'user';
+  const content = field(native, 'content'), parts = [], text = [], calls = [], results = [];
+  const blocks = Array.isArray(content) ? content : [];
+  for (let blockIndex = 0; blockIndex < blocks.length; blockIndex++) {
+    const block = blocks[blockIndex], kind = stringField(block, 'type');
+    if (kind === 'text') {
+      const value = stringField(block, 'text');
+      if (value != null) { text.push(value); parts.push({ type: 'text', text: value }); }
+    } else if (kind === 'image') {
+      const data = stringField(block, 'data') ?? '';
+      const media = field(block, 'mimeType') !== undefined ? stringField(block, 'mimeType') : stringField(block, 'mime_type');
+      parts.push({ type: 'image_url', image_url: { url: `data:${media ?? 'application/octet-stream'};base64,${data}` } });
+    } else if (kind === 'toolRequest' || kind === 'frontendToolRequest') {
+      const id = stringField(block, 'id') ?? `goose-${nativeIndex}-${blockIndex}`, nativeCall = field(block, 'toolCall');
+      const call = stringField(nativeCall, 'status') === 'success' && field(nativeCall, 'value') !== undefined ? nativeCall.value : nativeCall;
+      if (call === undefined) continue;
+      calls.push(functionCall(id, stringField(call, 'name') ?? 'tool', field(call, 'arguments') === undefined ? '{}' : valueString(call, 'arguments')));
+    } else if (kind === 'toolResponse') results.push(block);
+  }
+  if (text.length || parts.length || calls.length) {
+    const message = createMessage(role, text.length ? text.join('\n') : null);
+    message.content_parts = parts.some((part) => part.type !== 'text') ? parts : null;
+    message.tool_calls = calls.length ? calls : null;
+    captureMetadata(native, message); out.push(message);
+  }
+  for (let index = 0; index < results.length; index++) {
+    const block = results[index], id = stringField(block, 'id') ?? `goose-${nativeIndex}-result-${index}`;
+    const result = field(block, 'toolResult') ?? null, statusError = stringField(result, 'status') === 'error';
+    const value = field(result, 'value') !== undefined ? result.value : result;
+    const isError = statusError || field(value, 'isError') === true;
+    let output;
+    if (statusError) output = stringField(result, 'error') ?? 'Goose tool call failed';
+    else {
+      const content = field(value, 'content');
+      output = Array.isArray(content) ? content.map((part, at) => stringField(part, 'text') ?? stringifyNativeJsonMember(content, at)).join('\n')
+        : field(result, 'value') !== undefined ? stringifyNativeJsonMember(result, 'value')
+          : field(block, 'toolResult') !== undefined ? stringifyNativeJsonMember(block, 'toolResult') : 'null';
+    }
+    const message = toolMessage(id, output);
+    if (isError) markToolError(message);
+    captureMetadata(native, message); out.push(message);
+  }
+}
+
+/** Goose's official export document is the normalization boundary for its
+ * files and SQLite store. Unknown blocks remain in native-message metadata. */
+export function fromGooseStr(json) {
+  const document = parseNativeJson(json);
+  if (!isObject(document)) throw Object.assign(new Error('Goose session export must be a JSON object'), { code: 'invalid_session' });
+  if (!Array.isArray(document.conversation)) throw Object.assign(new Error('Goose session export must contain a conversation array'), { code: 'invalid_session' });
+  const session = createSession('goose'), { meta, messages } = session;
+  meta.session_id = stringField(document, 'id');
+  meta.cwd = field(document, 'working_dir') !== undefined ? stringField(document, 'working_dir') : stringField(document, 'workingDir');
+  const config = field(document, 'model_config') !== undefined ? document.model_config : document.modelConfig;
+  meta.model = field(config, 'model_name') !== undefined ? stringField(config, 'model_name') : stringField(config, 'modelName');
+  for (const [key, target] of [['name', 'session_name'], ['created_at', 'created_at'], ['updated_at', 'updated_at'], ['session_type', 'goose_session_type'], ['goose_mode', 'goose_mode'], ['provider_name', 'goose_provider_name'], ['parent_session_id', 'parent_session_id']]) {
+    if (field(document, key) !== undefined) meta.lineage[target] = valueString(document, key);
+  }
+  const header = cloneNativeJson(document); delete header.conversation;
+  meta.goose_header = header;
+  for (let nativeIndex = 0; nativeIndex < document.conversation.length; nativeIndex++) {
+    const native = document.conversation[nativeIndex], before = messages.length;
+    normalizeMessage(native, nativeIndex, messages);
+    if (messages[before]) {
+      const first = messages[before];
+      first.metadata.goose_native_message = stringifyNativeJsonMember(document.conversation, nativeIndex);
+      first.metadata.goose_native_index = String(nativeIndex);
+      if (nativeIndex === 0) first.metadata.goose_session_header = stringifyNativeJson(header);
+      restoreGrokMessageExtension(native, first);
+    }
+    for (let index = before + 1; index < messages.length; index++) messages[index].metadata.goose_native_index = String(nativeIndex);
+  }
+  ensureToolResultsPaired(messages);
+  const capture = splitLinesVerbatim(json);
+  session.raw = capture.lines; session.raw_trailing_newline = capture.trailingNewline;
+  session.raw_is_verbatim = true; session.imported_message_count = messages.length;
+  return session;
+}
+
+/** One read-only, fingerprint-verified SQLite snapshot. Display callers may
+ * select a newest native-row window; a full artifact never silently uses it. */
+export async function readGooseSqlite(path, sessionId, { messageLimit = null, metrics = {} } = {}) {
+  if (typeof sessionId !== 'string') throw new TypeError('Goose session selector must be a string');
+  if (messageLimit != null && (!Number.isSafeInteger(messageLimit) || messageLimit < 0)) throw new TypeError('Goose display limit must be a nonnegative exact integer');
+  const limit = messageLimit == null ? null : Math.max(1, messageLimit);
+  return readStore(path, (db) => {
+    const row = statement(db, `SELECT id, name, working_dir, created_at, updated_at, session_type,
+      extension_data, goose_mode, provider_name, model_config_json FROM sessions WHERE id = ?`).get(sessionId);
+    if (!row) throw Object.assign(new Error('failed to load Goose session: query returned no rows'), { code: 'invalid_session' });
+    const document = {
+      id: columnText(row.id), working_dir: columnText(row.working_dir), name: columnText(row.name), user_set_name: false,
+      session_type: columnText(row.session_type), created_at: columnText(row.created_at), updated_at: columnText(row.updated_at),
+      extension_data: parseColumn(columnText(row.extension_data, true), {}), usage: {}, accumulated_usage: {}, accumulated_cost: null,
+      schedule_id: null, recipe: null, user_recipe_values: null, conversation: [], message_count: 0, last_message_at: null,
+      provider_name: columnText(row.provider_name, true), model_config: parseColumn(columnText(row.model_config_json, true), null),
+      goose_mode: columnText(row.goose_mode), archived_at: null, project_id: null, parent_session_id: null, last_message_snippet: null,
+    };
+    const sql = limit == null
+      ? 'SELECT message_id, role, content_json, created_timestamp, metadata_json FROM messages WHERE session_id = ? ORDER BY created_timestamp, id'
+      : `SELECT message_id, role, content_json, created_timestamp, metadata_json FROM
+          (SELECT id AS native_row_id, message_id, role, content_json, created_timestamp, metadata_json
+           FROM messages WHERE session_id = ? ORDER BY created_timestamp DESC, id DESC LIMIT ?)
+         ORDER BY created_timestamp, native_row_id`;
+    const rows = statement(db, sql).all(...(limit == null ? [sessionId] : [sessionId, limit]));
+    for (const row of rows) {
+      const native = {
+        id: columnText(row.message_id, true), role: columnText(row.role), created: 0,
+        content: parseColumn(columnText(row.content_json), []),
+        metadata: parseColumn(columnText(row.metadata_json, true), { userVisible: true, agentVisible: true }),
+      };
+      setNativeInteger(native, 'created', columnInteger(row.created_timestamp));
+      document.conversation.push(native);
+    }
+    document.message_count = document.conversation.length;
+    const session = fromGooseStr(stringifyNativeJsonPretty(document));
+    session.raw_is_verbatim = false;
+    return session;
+  }, metrics);
+}
+
+function parseColumn(text, fallback) {
+  if (text == null) return fallback;
+  try { return parseNativeJson(text); } catch { return fallback; }
+}

package/session-grok.mjs

@@ -0,0 +1,72 @@
+import { createMessage } from './message.mjs';
+import { parseNativeJson } from './native-json.mjs';
+import { createSession } from './session-model.mjs';
+import { splitLinesVerbatim } from './session-lines.mjs';
+import { nativeTrim } from './text.mjs';
+import { field, stringField, valueString, extractTextContent, functionCall, toolMessage, restoreGrokMessageExtension, ensureToolResultsPaired, stampMessageRecords, takeMessageRecords } from './session-codec-utils.mjs';
+import { restoreTopLevelResidue, captureNativeResidue, grokResidueKind } from './session-native-residue.mjs';
+
+function humanText(raw) {
+  const text = nativeTrim(raw);
+  if (text === '' || text.startsWith('<user_info>') || text.startsWith('<system-reminder>')) return null;
+  const unwrapped = text.startsWith('<user_query>') && text.endsWith('</user_query>') ? nativeTrim(text.slice(12, -13)) : text;
+  return unwrapped === '' ? null : unwrapped;
+}
+function captureScalars(value, message, keys) {
+  for (const key of keys) if (field(value, key) !== undefined) message.metadata[`grok_${key}`] = valueString(value, key);
+}
+
+/** Conversation turns and source-native residue are separate; reasoning and
+ * backend records survive raw capture without becoming replay messages. */
+export function fromGrokStr(text) {
+  const session = createSession('grok'), { meta, messages } = session, capture = splitLinesVerbatim(text);
+  session.raw = capture.lines; session.raw_trailing_newline = capture.trailingNewline; session.raw_is_verbatim = true;
+  const records = capture.lines.map((line, index) => ({ line: nativeTrim(line), index })).filter((record) => record.line !== '');
+  const toolNames = new Map();
+  for (let index = 0; index < records.length; index++) {
+    if (index > 0) stampMessageRecords(messages, records[index - 1].index);
+    let value;
+    try { value = parseNativeJson(records[index].line); } catch { session.parse_error_lines++; continue; }
+    restoreTopLevelResidue(value, meta);
+    const residue = grokResidueKind(value);
+    if (residue != null) captureNativeResidue(meta, 'grok', index, records[index].line, value, residue);
+    const kind = stringField(value, 'type');
+    if (kind === 'system') { meta.system_prompt ??= stringField(value, 'content'); continue; }
+    let message;
+    if (kind === 'user') {
+      const role = stringField(value, 'synthetic_reason') === 'supercode_system_event' ? 'system' : 'user';
+      let content = extractTextContent(value, 'content');
+      if (role === 'user') {
+        content = humanText(content);
+        if (content == null && field(value, '_supercode_grok_message') === undefined) continue;
+        content ??= '';
+      }
+      message = createMessage(role, content);
+      captureScalars(value, message, ['prompt_index', 'prior_turn_interrupt', 'synthetic_reason']);
+    } else if (kind === 'assistant') {
+      const nativeCalls = field(value, 'tool_calls'), calls = [];
+      if (Array.isArray(nativeCalls)) for (const call of nativeCalls) {
+        const id = stringField(call, 'id'), name = stringField(call, 'name');
+        if (id == null || name == null) continue;
+        calls.push(functionCall(id, name, field(call, 'arguments') === undefined ? '{}' : valueString(call, 'arguments')));
+        toolNames.set(id, name);
+      }
+      const content = stringField(value, 'content'); message = createMessage('assistant', content === '' ? null : content);
+      message.tool_calls = calls.length ? calls : null;
+      captureScalars(value, message, ['model_id', 'model_fingerprint', 'reasoning_effort']);
+      const model = stringField(value, 'model_id'); if (model != null) meta.model = model;
+    } else if (kind === 'tool_result') {
+      const id = stringField(value, 'tool_call_id') ?? '';
+      message = toolMessage(id, extractTextContent(value, 'content')); message.name = toolNames.get(id) ?? null;
+      const nativeImages = field(value, 'images'), images = [];
+      if (Array.isArray(nativeImages)) for (const image of nativeImages) {
+        const url = stringField(image, 'url'); if (url != null && url !== '') images.push({ type: 'image_url', image_url: { url } });
+      }
+      if (images.length) message.content_parts = [...(message.content !== '' ? [{ type: 'text', text: message.content }] : []), ...images];
+    } else continue;
+    restoreGrokMessageExtension(value, message); messages.push(message);
+  }
+  if (records.length) stampMessageRecords(messages, records.at(-1).index);
+  ensureToolResultsPaired(messages); meta.message_records = takeMessageRecords(messages); session.imported_message_count = messages.length;
+  return session;
+}

package/session-hermes.mjs

@@ -0,0 +1,116 @@
+import { createMessage } from './message.mjs';
+import { createSession } from './session-model.mjs';
+import { field, stringField, ensureToolResultsPaired } from './session-codec-utils.mjs';
+import { parseNativeJson, setNativeInteger, setNativeFloat, stringifyNativeJson } from './native-json.mjs';
+import { readStore, statement, tableColumns, text, integer } from './sqlite-reader.mjs';
+import { sourceStat } from './store-registry.mjs';
+import { hermesLineageKind, hermesSessionNouns } from './hermes-store.mjs';
+import { bindingEpoch, messageEpoch } from './session-time.mjs';
+
+const extendedColumns = ['session_key', 'chat_id', 'chat_type', 'thread_id', 'user_id', 'profile_name', 'handoff_state', 'handoff_platform', 'handoff_error'];
+function epoch(value) {
+  if (value == null) return null;
+  if (typeof value !== 'number' && typeof value !== 'bigint') throw new Error('Hermes returned a non-numeric native epoch');
+  return Number(value);
+}
+function configJson(value) { try { return value == null ? null : parseNativeJson(value); } catch { return null; } }
+
+function captureNouns(db, row, relationship, config, meta) {
+  let extended = false, ended = null, reason = null;
+  try {
+    const values = statement(db, `SELECT ${extendedColumns.join(',')} FROM sessions WHERE id=?`).get(row.id);
+    if (values) {
+      // A wrong column type refuses this optional extended reading whole.
+      const selected = Object.fromEntries(extendedColumns.map((column) => [column, text(values[column], true)]));
+      Object.assign(row, selected); extended = true;
+    }
+  } catch { /* Older schemas have no gateway columns; source still names trigger. */ }
+  try {
+    const values = statement(db, 'SELECT ended_at, end_reason FROM sessions WHERE id=?').get(row.id);
+    if (values) { const time = epoch(values.ended_at), word = text(values.end_reason, true); ended = time; reason = word; }
+  } catch { /* No recorded lifecycle reading remains unknown. */ }
+  const nouns = hermesSessionNouns(row, relationship, config, extended);
+  meta.ended_at = ended == null ? null : bindingEpoch(ended); meta.end_reason = reason;
+  meta.trigger = nouns.trigger; meta.recurrence = nouns.recurrence ?? null;
+  if (extended) {
+    meta.surface = nouns.surface ?? null; meta.profile = nouns.profile ?? null; meta.cross_surface = nouns.cross_surface ?? null;
+  }
+}
+
+/** Hermes rescue remains read-only. Inactive rows are retained in raw but
+ * only active=1 rows, ordered by native id, enter its replay conversation. */
+export async function readHermesSqlite(path, sessionId = null, { metrics = {} } = {}) {
+  if (sessionId != null && typeof sessionId !== 'string') throw new TypeError('Hermes session selector must be a string');
+  const info = await sourceStat(path);
+  if (!info?.isFile()) throw new Error(`Hermes SQLite store not found at ${path} — expected a \`state.db\` file`);
+  return readStore(path, (db) => {
+    const tables = new Set(db.prepare("SELECT name FROM sqlite_master WHERE type='table'").all().map((row) => row.name));
+    if (!['sessions', 'messages', 'schema_version'].every((table) => tables.has(table)) || tables.has('schema_meta')) {
+      throw new Error(`${path} is SQLite but not a Hermes state.db (missing sessions/messages/schema_version, or it carries OpenClaw's schema_meta)`);
+    }
+    const id = sessionId ?? (() => {
+      const newest = statement(db, 'SELECT id FROM sessions ORDER BY started_at DESC LIMIT 1').get();
+      if (!newest) throw new Error(`${path} contains no Hermes sessions`);
+      return text(newest.id);
+    })();
+    const row = statement(db, `SELECT source, model, cwd, system_prompt, title, parent_session_id, model_config, started_at
+      FROM sessions WHERE id=?`).get(id);
+    if (!row) throw new Error(`Hermes session \`${id}\` not found in ${path}`);
+    const session = createSession('hermes'), { meta, messages } = session;
+    for (const key of ['source', 'model', 'cwd', 'system_prompt', 'title', 'parent_session_id', 'model_config']) row[key] = text(row[key], true);
+    row.started_at = epoch(row.started_at); row.id = id;
+    const config = configJson(row.model_config);
+    meta.session_id = id; meta.model = row.model; meta.system_prompt = row.system_prompt;
+    meta.cwd = row.cwd !== '' && row.cwd != null ? row.cwd : stringField(config, 'cwd');
+    if (meta.cwd === '') meta.cwd = null;
+    if (row.title != null && row.title !== '') meta.lineage.session_name = row.title;
+    if (row.source != null && row.source !== '') meta.lineage.hermes_source = row.source;
+    let relationship = null;
+    if (row.parent_session_id != null) {
+      meta.lineage.hermes_parent_session_id = row.parent_session_id;
+      try { relationship = hermesLineageKind(db, tableColumns(db, 'sessions'), row, config); } catch { relationship = 'unknown'; }
+      meta.lineage.hermes_lineage_kind = relationship;
+    }
+    captureNouns(db, row, relationship, config, meta);
+    const header = { id, cwd: meta.cwd, parent_session_id: row.parent_session_id, started_at: row.started_at };
+    if (row.started_at != null) setNativeFloat(header, 'started_at', row.started_at);
+    session.raw.push(stringifyNativeJson({ hermes_session: header }));
+    const rows = statement(db, `SELECT id, role, content, tool_call_id, tool_calls, tool_name, timestamp, reasoning_content, active, compacted
+      FROM messages WHERE session_id=? ORDER BY id`).all(id);
+    for (const row of rows) {
+      for (const key of ['role', 'content', 'tool_call_id', 'tool_calls', 'tool_name', 'reasoning_content']) row[key] = text(row[key], true);
+      const rowId = integer(row.id), timestamp = epoch(row.timestamp), active = integer(row.active, true), compacted = integer(row.compacted, true);
+      const native = {
+        id: 0, role: row.role, content: row.content, tool_call_id: row.tool_call_id, tool_calls: row.tool_calls,
+        tool_name: row.tool_name, timestamp, active: null, compacted: null,
+      };
+      setNativeInteger(native, 'id', rowId);
+      if (active != null) setNativeInteger(native, 'active', active);
+      if (compacted != null) setNativeInteger(native, 'compacted', compacted);
+      if (timestamp != null) setNativeFloat(native, 'timestamp', timestamp);
+      session.raw.push(stringifyNativeJson({ hermes_message: native }));
+      if (active !== 1n) continue;
+      let message;
+      if (row.role === 'user' || row.role === 'assistant') message = createMessage(row.role, row.content ?? '');
+      else if (row.role === 'tool') {
+        message = createMessage('tool', row.content ?? ''); message.tool_call_id = row.tool_call_id ?? ''; message.name = row.tool_name ?? 'tool';
+      } else continue;
+      if (row.role === 'assistant') {
+        const calls = configJson(row.tool_calls), selected = [];
+        if (Array.isArray(calls)) for (const call of calls) {
+          const id = stringField(call, 'id'), fn = field(call, 'function'), name = stringField(fn, 'name');
+          if (id == null || name == null) continue;
+          selected.push({ id, type: stringField(call, 'type') ?? 'function', function: { name, arguments: stringField(fn, 'arguments') ?? '{}' } });
+        }
+        if (selected.length) message.tool_calls = selected;
+        if (row.reasoning_content != null && row.reasoning_content !== '') message.metadata.reasoning_content = row.reasoning_content;
+      }
+      message.metadata.hermes_message_id = String(rowId);
+      if (timestamp != null) message.metadata.timestamp = messageEpoch(timestamp);
+      if (compacted === 1n) message.metadata.compacted_out = 'true';
+      messages.push(message);
+    }
+    ensureToolResultsPaired(messages); session.imported_message_count = messages.length;
+    return session;
+  }, metrics);
+}

package/session-lines.mjs

@@ -0,0 +1,20 @@
+import { nativeTrim } from './text.mjs';
+
+/** Split only LF, retaining CR, blanks and trailing spaces in the raw lines. */
+export function splitLinesVerbatim(text) {
+  if (text === '') return { lines: [], trailingNewline: false };
+  const trailingNewline = text.endsWith('\n');
+  return { lines: (trailingNewline ? text.slice(0, -1) : text).split('\n'), trailingNewline };
+}
+
+export function joinLinesVerbatim(lines, trailingNewline) {
+  return lines.join('\n') + (trailingNewline ? '\n' : '');
+}
+
+/** Parsing view only. Never use these trimmed lines for retained source bytes. */
+export function* nonEmptyLines(text) {
+  for (const line of text.split('\n')) {
+    const trimmed = nativeTrim(line);
+    if (trimmed !== '') yield trimmed;
+  }
+}