@volter/supercode-interchange 0.1.1 → 0.1.3

package/session-opencode.mjs

@@ -0,0 +1,115 @@
+import { createSession } from './session-model.mjs';
+import { parseNativeJson, nativeInteger, stringifyNativeJson, stringifyNativeJsonMember } from './native-json.mjs';
+import { splitLinesVerbatim } from './session-lines.mjs';
+import { field, stringField, ensureToolResultsPaired } from './session-codec-utils.mjs';
+import { restoreTopLevelResidue } from './session-native-residue.mjs';
+import { nativeTrim } from './text.mjs';
+import { OPENCODE_ORIGINAL_POSITION, pushOpenCodeUser, pushOpenCodeAssistant } from './session-opencode-content.mjs';
+
+const utf8Order = (left, right) => Buffer.compare(Buffer.from(left), Buffer.from(right));
+const byInteger = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+export const opencodeEnvelope = (key, value) => stringifyNativeJson({ key, value });
+const record = (id, value, parts = []) => ({ id, value, parts, created: nativeInteger(field(value, 'time'), 'created', { signed: true }) ?? 0n });
+
+function guard(nonempty, info, records, sides) {
+  if (nonempty && info == null && !records.length && !sides.length) throw Object.assign(new Error('opencode input was recognized as an OpenCode source (envelope or export-document form) but no session/message/part record could be parsed from it — refusing to silently return an empty session'), { code: 'invalid_session' });
+}
+function captureInfo(value, meta) {
+  restoreTopLevelResidue(value, meta);
+  for (const [source, target] of [['id', 'session_id'], ['directory', 'cwd'], ['agent', 'agent_id']]) { const text = stringField(value, source); if (text != null) meta[target] = text; }
+  const model = field(value, 'model'), provider = stringField(model, 'providerID'), id = stringField(model, 'id');
+  if (provider != null && id != null) meta.model = `${provider}/${id}`;
+  for (const key of ['projectID', 'slug', 'workspaceID']) { const text = stringField(value, key); if (text != null) meta.lineage[key] = text; }
+  const parent = stringField(value, 'parentID'); if (parent != null) { meta.lineage.parent_session_id = parent; meta.lineage.parent_thread_id = parent; }
+  if (!Object.hasOwn(meta.lineage, 'claude_fork_context_ref_raw') && field(value, 'claude_fork_context_ref') !== undefined) meta.lineage.claude_fork_context_ref_raw = stringifyNativeJsonMember(value, 'claude_fork_context_ref');
+}
+
+function fromRecords(info, sides, records, raw, trailing, verbatim, errors) {
+  const session = createSession('opencode'), positions = new Map(records.map((item, at) => [item.id, at]));
+  // Native compaction references use pre-sort positions; retain that contract.
+  records.sort((left, right) => byInteger(left.created, right.created) || utf8Order(left.id, right.id));
+  for (const item of records) item.parts.sort((left, right) => utf8Order(stringField(left, 'id') ?? '', stringField(right, 'id') ?? ''));
+  session.meta.opencode_headers.push(info ?? null); for (const side of sides) session.meta.opencode_headers.push(side);
+  if (info != null) captureInfo(info, session.meta);
+  let tail = null;
+  for (const item of records) for (const part of item.parts) if (stringField(part, 'type') === 'compaction') {
+    const at = positions.get(stringField(part, 'tail_start_id')); if (at !== undefined) tail = Math.max(tail ?? at, at);
+  }
+  session.firstSystemSeen = false;
+  records.forEach((item, at) => {
+    const before = session.messages.length, role = stringField(item.value, 'role');
+    if (role === 'user') pushOpenCodeUser(item.value, item.parts, session);
+    else if (role === 'assistant') pushOpenCodeAssistant(item.value, item.parts, session);
+    const original = nativeInteger(item.value, '_supercode_message_position');
+    if (original != null) {
+      const message = session.messages.slice(before).find((message) => message.role !== 'tool');
+      if (message != null) message.metadata[OPENCODE_ORIGINAL_POSITION] = String(original);
+    }
+    for (let index = before; index < session.messages.length; index++) if (tail != null && at < tail && session.messages[index].metadata.is_summary !== 'true') session.messages[index].metadata.compacted_out = 'true';
+  });
+  delete session.firstSystemSeen;
+  const slots = [], marked = [];
+  session.messages.forEach((message, at) => { if (Object.hasOwn(message.metadata, OPENCODE_ORIGINAL_POSITION)) { slots.push(at); marked.push(message); } });
+  const position = (message) => {
+    const text = message.metadata[OPENCODE_ORIGINAL_POSITION], maximum = 18446744073709551615n;
+    if (typeof text !== 'string' || !/^\+?\d+$/.test(text)) return maximum;
+    const value = BigInt(text); return value <= maximum ? value : maximum;
+  };
+  marked.sort((left, right) => byInteger(position(left), position(right)));
+  slots.forEach((at, index) => { session.messages[at] = marked[index]; });
+  for (const message of session.messages) delete message.metadata[OPENCODE_ORIGINAL_POSITION];
+  ensureToolResultsPaired(session.messages);
+  session.raw = raw; session.raw_trailing_newline = trailing; session.raw_is_verbatim = verbatim;
+  session.parse_error_lines = errors; session.imported_message_count = session.messages.length;
+  return session;
+}
+
+function fromExport(document) {
+  const info = field(document, 'info') ?? null, id = stringField(info, 'id') ?? 'ses_unknown', project = stringField(info, 'projectID') ?? 'global', raw = [], records = [];
+  if (info != null) raw.push(opencodeEnvelope(['session', project, id], info));
+  for (const entry of document.messages) {
+    const value = field(entry, 'info'), messageId = stringField(value, 'id'); if (messageId == null) continue;
+    const parts = Array.isArray(field(entry, 'parts')) ? entry.parts.slice() : [];
+    raw.push(opencodeEnvelope(['message', id, messageId], value));
+    for (const part of parts) raw.push(opencodeEnvelope(['part', messageId, stringField(part, 'id') ?? ''], part));
+    records.push(record(messageId, value, parts));
+  }
+  guard(true, info, records, []); return fromRecords(info, [], records, raw, true, false, 0);
+}
+
+/** Both native read surfaces share one canonicalization and residue boundary. */
+export function fromOpenCodeStr(text) {
+  const trimmed = nativeTrim(text);
+  let document; try { document = parseNativeJson(trimmed); } catch { /* The envelope form is parsed per line. */ }
+  if (field(document, 'info') !== undefined && Array.isArray(field(document, 'messages'))) return fromExport(document);
+  const capture = splitLinesVerbatim(text), records = [], byId = new Map(), sides = [];
+  let info = null, errors = 0;
+  for (const line of capture.lines) {
+    if (nativeTrim(line) === '') continue;
+    let envelope; try { envelope = parseNativeJson(nativeTrim(line)); } catch { errors++; continue; }
+    const key = field(envelope, 'key'); if (!Array.isArray(key)) continue;
+    const value = field(envelope, 'value') ?? null;
+    if (key[0] === 'session') info = value;
+    else if (key[0] === 'message') {
+      const id = stringField(value, 'id'); if (id == null) continue;
+      byId.set(id, records.length); records.push(record(id, value));
+    } else if (key[0] === 'part') {
+      const at = byId.get(stringField(value, 'messageID')); if (at !== undefined) records[at].parts.push(value);
+    } else if (key[0] === 'session_diff' || key[0] === 'todo') sides.push({ key, value });
+  }
+  guard(trimmed !== '', info, records, sides);
+  return fromRecords(info, sides, records, capture.lines, capture.trailingNewline, true, errors);
+}
+
+/** Task linkage is provenance only; nesting is a separate session-tree step. */
+export function resolveOpenCodeParentToolUseIds(sessions) {
+  const ids = sessions.map((session) => session.meta.session_id);
+  for (const session of sessions) {
+    const child = session.meta.session_id, parent = session.meta.lineage.parent_session_id;
+    if (child == null || parent == null) continue;
+    const at = ids.indexOf(parent); if (at === -1) continue;
+    for (const message of sessions[at].messages) for (const key of Object.keys(message.metadata).sort(utf8Order)) {
+      if (key.startsWith('oc_task_child_session_id__') && message.metadata[key] === child) session.meta.parent_tool_use_id = key.slice('oc_task_child_session_id__'.length);
+    }
+  }
+}

package/session-path.mjs

@@ -0,0 +1,129 @@
+import { readdir } from 'node:fs/promises';
+import { basename, dirname, extname, join, sep } from 'node:path';
+import { promisify } from 'node:util';
+import * as zlib from 'node:zlib';
+import { withSessionFile, fileFingerprint } from './file-io.mjs';
+import { sourceStat } from './store-registry.mjs';
+import { optionalFile, verifySources, decodeWorkspaceFolder } from './source-files.mjs';
+import { readStore, statement } from './sqlite-reader.mjs';
+import { decodeSessionUtf8 } from './session-file.mjs';
+import { field, stringField, valueString } from './session-codec-utils.mjs';
+import { parseNativeJson } from './native-json.mjs';
+import { nonEmptyLines } from './session-lines.mjs';
+import { deserializeMessage } from './message.mjs';
+import { fromNativeMessages, fromSidecarStr } from './session-native.mjs';
+import { readSessionDocument } from './session-document.mjs';
+import { attachClaudeSubagents } from './session-claude-files.mjs';
+import { readOpenCodeSqlite } from './session-opencode-store.mjs';
+import { readGooseSqlite } from './session-goose.mjs';
+import { readHermesSqlite } from './session-hermes.mjs';
+
+export const isCompressedSessionPath = (path) => extname(path) === '.zst';
+export async function sessionReaderText(reader) {
+  let bytes = await reader.read(0, reader.size);
+  if (isCompressedSessionPath(reader.path)) {
+    if (typeof zlib.zstdDecompress !== 'function') throw new Error('compressed transcripts require Node 22.15 or later with zstdDecompress');
+    try { bytes = await promisify(zlib.zstdDecompress)(bytes); }
+    catch (error) { throw new Error(`${reader.path} is not a readable zstd stream: ${error.message}`, { cause: error }); }
+  }
+  try { return decodeSessionUtf8(bytes); }
+  catch (error) { throw new Error(`${reader.path} is not valid UTF-8 text, and is not a recognized OpenCode SQLite store (no \`SQLite format 3\` header) — supercode reads session logs as UTF-8 JSONL, or an OpenCode \`opencode*.db\` SQLite file`, { cause: error }); }
+}
+
+export async function looksLikeSessionSqlite(path, metrics) {
+  if (!(await sourceStat(path))?.isFile()) return false;
+  if (extname(path) === '.db') return true;
+  return (await withSessionFile(path, async (reader) => (await reader.read(0, 16)).equals(Buffer.from('SQLite format 3\0')), metrics)).result;
+}
+
+/** Legacy JSON trees are classified so their supported refusal survives;
+ * this port does not silently add a direct-write or legacy-reader tier. */
+export async function detectOpenCodeStorageSurface(root, { env = process.env } = {}) {
+  if (typeof env.OPENCODE_DB === 'string' && (await sourceStat(env.OPENCODE_DB))?.isFile()) return { kind: 'sqlite', path: env.OPENCODE_DB };
+  let names;
+  try { names = await readdir(root); } catch (error) { if (error.code !== 'ENOENT' && error.code !== 'ENOTDIR') throw error; names = []; }
+  const candidates = names.filter((name) => name.startsWith('opencode') && name.endsWith('.db')).sort((a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b)));
+  if (candidates.length) return { kind: 'sqlite', path: join(root, candidates.includes('opencode.db') ? 'opencode.db' : candidates[0]) };
+  if ((await sourceStat(join(root, 'storage', 'migration')))?.isFile()) return { kind: 'json_tree_b', path: join(root, 'storage') };
+  if ((await sourceStat(join(root, 'project')))?.isDirectory()) return { kind: 'json_tree_a', path: join(root, 'project') };
+  return null;
+}
+
+export async function captureGrokPathMetadata(session, path, metrics) {
+  const directory = dirname(path);
+  session.meta.session_id = directory === '.' || directory === sep ? null : basename(directory);
+  const workspace = dirname(directory);
+  session.meta.cwd = workspace === '.' || workspace === sep ? null : decodeWorkspaceFolder(basename(workspace));
+  const summary = await optionalFile(join(directory, 'summary.json'), async (reader) => {
+    const source = decodeSessionUtf8(await reader.read(0, reader.size));
+    try { return parseNativeJson(source); } catch { return null; }
+  }, metrics);
+  const model = stringField(summary.result, 'current_model_id'); if (model != null) session.meta.model = model;
+  for (const [source, target] of [['generated_title', 'session_name'], ['created_at', 'created_at'], ['updated_at', 'updated_at'], ['chat_format_version', 'grok_chat_format_version']]) {
+    if (field(summary.result, source) !== undefined) session.meta.lineage[target] = valueString(summary.result, source);
+  }
+  return summary;
+}
+
+/** Metadata-file presence chooses the native family; its content is not a
+ * caller claim. The sidecar, transcript and metadata identities are verified. */
+export async function loadNativeStoreFamily(path, { metrics } = {}) {
+  const name = basename(path, extname(path)), directory = dirname(path), metaPath = join(directory, `${name}.meta.json`), sidecarPath = join(directory, `${name}.sidecar.jsonl`);
+  const meta = await sourceStat(metaPath); if (!meta?.isFile()) return null;
+  const sidecar = await sourceStat(sidecarPath), sources = [{ path: metaPath, fingerprint: fileFingerprint(meta) }];
+  sources.push(sidecar ? { path: sidecarPath, fingerprint: fileFingerprint(sidecar) } : { path: sidecarPath, missing: true });
+  const session = (await withSessionFile(sidecar?.isFile() ? sidecarPath : path, async (reader) => {
+    const text = decodeSessionUtf8(await reader.read(0, reader.size));
+    return sidecar?.isFile() ? fromSidecarStr(text) : fromNativeMessages([...nonEmptyLines(text)].map((line) => deserializeMessage(parseNativeJson(line))));
+  }, metrics)).result;
+  await verifySources(sources); session.meta.session_id = name; return session;
+}
+
+export async function loadSessionPath(path, { fidelity = 'byte_lossless', includeSubagents = true, metrics, env = process.env } = {}) {
+  if (!['byte_lossless', 'value_lossless', 'semantic'].includes(fidelity)) throw new TypeError(`unknown session fidelity: ${fidelity}`);
+  if ((await sourceStat(path))?.isDirectory()) {
+    const surface = await detectOpenCodeStorageSurface(path, { env });
+    if (surface?.kind === 'sqlite') return (await readOpenCodeSqlite(surface.path, null, { metrics })).result;
+    if (surface) throw new Error(`${path} is an OpenCode data root using a legacy JSON storage tree, which supercode does not load directly — point inspect/convert/resume at the store's opencode*.db SQLite file if this install has one, or use audit --format opencode ${path} instead`);
+    throw new Error(`${path} is a directory, but no session file or OpenCode store was found in it (expected an opencode*.db SQLite file, or an OpenCode legacy JSON storage tree)`);
+  }
+  if (await looksLikeSessionSqlite(path, metrics)) {
+    const probe = await readStore(path, (db) => {
+      const names = new Set(statement(db, "SELECT name FROM sqlite_master WHERE type='table'").all().map((row) => row.name));
+      return ['sessions', 'messages', 'schema_version'].every((name) => names.has(name)) && !names.has('schema_meta');
+    }, metrics);
+    const session = (await (probe.result ? readHermesSqlite(path, null, { metrics }) : readOpenCodeSqlite(path, null, { metrics }))).result;
+    await verifySources(probe.sources); return session;
+  }
+  return (await withSessionFile(path, async (reader) => {
+    const text = await sessionReaderText(reader), session = readSessionDocument(text, { fidelity });
+    const sources = [];
+    if (session.meta.source === 'claude_code' && includeSubagents) await attachClaudeSubagents(session, path, text, fidelity, metrics);
+    if (session.meta.source === 'grok') sources.push(await captureGrokPathMetadata(session, path, metrics));
+    if (session.meta.source === 'openclaw' && session.meta.profile == null) {
+      const parts = path.split(sep), at = parts.indexOf('agents'); if (at !== -1 && at + 1 < parts.length) session.meta.profile = parts[at + 1];
+    }
+    await verifySources(sources); return session;
+  }, metrics)).result;
+}
+
+/** Catalog routing pins a store selector instead of accidentally following
+ * its newest row. The locator's other harness spelling does not force a codec. */
+export async function loadSessionLocator(locator, options = {}) {
+  const { path, kind, selector } = locator.storage;
+  if (locator.harness === 'hermes' && kind === 'file') return (await readHermesSqlite(path, locator.session_id, options)).result;
+  if (kind === 'sqlite') return (await (locator.harness === 'goose' ? readGooseSqlite(path, selector, options) : readOpenCodeSqlite(path, selector, options))).result;
+  return await loadNativeStoreFamily(path, options) ?? loadSessionPath(path, options);
+}
+
+export async function loadLocatorDisplayStore(locator, messageLimit, options = {}) {
+  let session;
+  if (locator.harness === 'hermes' && locator.storage.kind === 'file') session = (await readHermesSqlite(locator.storage.path, locator.session_id, options)).result;
+  else if (locator.storage.kind === 'sqlite') session = (await (locator.harness === 'goose' ? readGooseSqlite(locator.storage.path, locator.storage.selector, { ...options, messageLimit }) : readOpenCodeSqlite(locator.storage.path, locator.storage.selector, options))).result;
+  else session = await loadNativeStoreFamily(locator.storage.path, options);
+  if (session == null) return null;
+  // Catalog store/native display paths use a plain tail; file display paths
+  // apply the native two-human-anchor projector separately.
+  if (session.messages.length > Math.max(1, messageLimit)) session.messages.splice(0, session.messages.length - Math.max(1, messageLimit));
+  return session;
+}

package/session-pi-content.mjs

@@ -0,0 +1,129 @@
+import { createMessage, markToolError } from './message.mjs';
+import { nativeInteger, stringifyNativeJsonMember } from './native-json.mjs';
+import { field, stringField, valueString, functionCall } from './session-codec-utils.mjs';
+import { nativeTrim } from './text.mjs';
+
+const append = (text, part) => typeof part === 'string' ? text + (text === '' ? '' : '\n') + part : text;
+function stampNativeClock(value, message) {
+  const timestamp = nativeInteger(value, 'timestamp');
+  if (timestamp != null) message.metadata.pi_msg_timestamp = String(timestamp);
+}
+function retainJson(value, message, source, target) {
+  if (field(value, source) != null) message.metadata[target] = stringifyNativeJsonMember(value, source);
+}
+
+function contentParts(content) {
+  if (typeof content === 'string') return { text: content, parts: null, unknown: false };
+  if (!Array.isArray(content)) return { text: '', parts: null, unknown: false };
+  let text = '', hasImage = false;
+  const parts = [];
+  for (const block of content) {
+    const kind = stringField(block, 'type');
+    if (kind === 'text') text = append(text, stringField(block, 'text'));
+    else if (kind === 'image') {
+      hasImage = true;
+      const mime = stringField(block, 'mimeType'), data = stringField(block, 'data');
+      if (mime == null || mime === '' || data == null || data === '' || !/^[A-Za-z0-9+/=]+$/.test(data)) return { text: '', parts: null, unknown: true };
+      parts.push({ type: 'image_url', image_url: { url: `data:${mime};base64,${data}` } });
+    }
+  }
+  if (hasImage && nativeTrim(text) !== '') parts.unshift({ type: 'text', text });
+  return { text, parts: hasImage ? parts : null, unknown: false };
+}
+
+function userContent(value) {
+  const content = contentParts(field(value, 'content'));
+  if (content.unknown || (nativeTrim(content.text) === '' && content.parts == null)) return null;
+  const message = createMessage('user', content.parts == null ? content.text : null);
+  message.content_parts = content.parts; return message;
+}
+
+function pushAssistant(value, out) {
+  let text = '', thinking = '', thinkingSeen = false, thinkingSignature = null, redacted = false, textSignature = null, thoughtSignature = null;
+  const calls = [], content = field(value, 'content');
+  if (Array.isArray(content)) for (const block of content) {
+    const kind = stringField(block, 'type');
+    if (kind === 'text') {
+      text = append(text, stringField(block, 'text'));
+      if (field(block, 'textSignature') !== undefined) textSignature = valueString(block, 'textSignature');
+    } else if (kind === 'thinking') {
+      thinkingSeen = true; thinking = append(thinking, stringField(block, 'thinking'));
+      thinkingSignature = stringField(block, 'thinkingSignature') ?? thinkingSignature;
+      if (field(block, 'redacted') === true) redacted = true;
+    } else if (kind === 'toolCall') {
+      calls.push(functionCall(stringField(block, 'id') ?? '', stringField(block, 'name') ?? '', field(block, 'arguments') === undefined ? '{}' : stringifyNativeJsonMember(block, 'arguments')));
+      thoughtSignature = stringField(block, 'thoughtSignature') ?? thoughtSignature;
+    }
+  }
+  const hasText = nativeTrim(text) !== '';
+  if (!hasText && !calls.length && !thinkingSeen && stringField(value, 'stopReason') === 'error') return;
+  const message = createMessage('assistant', hasText ? text : null); message.tool_calls = calls.length ? calls : null;
+  if (!hasText && !calls.length && !thinkingSeen) message.metadata.empty_assistant_record = 'true';
+  if (thinkingSeen) message.metadata.thinking = thinking;
+  if (thinkingSignature != null) message.metadata.thinking_signature = thinkingSignature;
+  if (redacted) message.metadata.pi_thinking_redacted = 'true';
+  if (textSignature != null) message.metadata.pi_text_signature = textSignature;
+  if (thoughtSignature != null) message.metadata.pi_thought_signature = thoughtSignature;
+  for (const [key, source] of [['pi_api', 'api'], ['pi_provider', 'provider'], ['pi_response_model', 'responseModel'], ['pi_response_id', 'responseId'], ['pi_stop_reason', 'stopReason'], ['pi_error_message', 'errorMessage']]) {
+    const text = stringField(value, source); if (text != null) message.metadata[key] = text;
+  }
+  retainJson(value, message, 'diagnostics', 'pi_diagnostics'); retainJson(value, message, 'usage', 'pi_usage');
+  stampNativeClock(value, message); out.push(message);
+}
+
+function pushTool(value, out) {
+  const content = contentParts(field(value, 'content')); if (content.unknown) return;
+  const message = createMessage('tool', content.text); message.content_parts = content.parts;
+  message.tool_call_id = stringField(value, 'toolCallId') ?? ''; message.name = stringField(value, 'toolName') ?? '';
+  retainJson(value, message, 'details', 'pi_tool_details');
+  const error = field(value, 'isError') === true; message.metadata.pi_is_error = String(error);
+  if (error) markToolError(message);
+  stampNativeClock(value, message); out.push(message);
+}
+
+function pushBash(value, out) {
+  const command = stringField(value, 'command') ?? '', output = stringField(value, 'output') ?? '', exit = nativeInteger(value, 'exitCode', { signed: true });
+  const cancelled = field(value, 'cancelled') === true, truncated = field(value, 'truncated') === true;
+  let text = `$ ${command}\n${output}`;
+  if (exit != null && exit !== 0n) text += `\n[exit code: ${exit}]`;
+  if (cancelled) text += '\n[cancelled]'; if (truncated) text += '\n[truncated]';
+  const message = createMessage('user', text);
+  message.metadata.pi_bash_command = command; message.metadata.pi_bash_output = output;
+  if (exit != null) message.metadata.pi_bash_exit_code = String(exit);
+  message.metadata.pi_bash_cancelled = String(cancelled); message.metadata.pi_bash_truncated = String(truncated);
+  const path = stringField(value, 'fullOutputPath'); if (path != null) message.metadata.pi_bash_full_output_path = path;
+  if (field(value, 'excludeFromContext') === true) message.metadata.pi_exclude_from_context = 'true';
+  stampNativeClock(value, message); out.push(message);
+}
+
+export function pushPiCustom(value, out) {
+  if (stringField(value, 'customType') === 'supercode_claude_system') {
+    const content = stringField(value, 'content') ?? ''; if (nativeTrim(content) === '') return;
+    const message = createMessage('system', content); message.metadata.systemSubtype = stringField(field(value, 'details'), 'claude_system_subtype') ?? 'local_command'; out.push(message); return;
+  }
+  const message = userContent(value); if (message == null) return;
+  const kind = stringField(value, 'customType'); if (kind != null) message.metadata.pi_custom_type = kind;
+  const display = field(value, 'display'); if (typeof display === 'boolean') message.metadata.pi_display = String(display);
+  retainJson(value, message, 'details', 'pi_details'); stampNativeClock(value, message); out.push(message);
+}
+
+export function pushPiMessage(value, out) {
+  const role = stringField(value, 'role');
+  if (role === 'user') { const message = userContent(value); if (message != null) { stampNativeClock(value, message); out.push(message); } }
+  else if (role === 'assistant') pushAssistant(value, out);
+  else if (role === 'toolResult') pushTool(value, out);
+  else if (role === 'bashExecution') pushBash(value, out);
+  else if (role === 'custom') pushPiCustom(value, out);
+}
+
+export function pushPiSummary(value, out, kind) {
+  const summary = stringField(value, 'summary') ?? ''; if (nativeTrim(summary) === '') return;
+  const compaction = kind === 'compaction', message = createMessage('user', `[${compaction ? 'compaction' : 'branch'} summary]\n${summary}`);
+  message.metadata.pi_type = kind;
+  const key = compaction ? 'firstKeptEntryId' : 'fromId', id = stringField(value, key);
+  if (id != null) message.metadata[compaction ? 'pi_first_kept_entry_id' : 'pi_from_id'] = id;
+  if (compaction) { const tokens = nativeInteger(value, 'tokensBefore'); if (tokens != null) message.metadata.pi_tokens_before = String(tokens); }
+  retainJson(value, message, 'details', 'pi_details');
+  if (field(value, 'fromHook') === true) message.metadata.pi_from_hook = 'true';
+  out.push(message);
+}

package/session-pi.mjs

@@ -0,0 +1,86 @@
+import { createSession } from './session-model.mjs';
+import { parseNativeJson, nativeInteger, nativeObjectKeys, stringifyNativeJsonMember } from './native-json.mjs';
+import { splitLinesVerbatim } from './session-lines.mjs';
+import { field, stringField, isObject, valueString, restoreGrokMessageExtension, ensureToolResultsPaired } from './session-codec-utils.mjs';
+import { isToolError, markToolOutcomeUnknown } from './message.mjs';
+import { restoreTopLevelResidue } from './session-native-residue.mjs';
+import { messageMilliseconds } from './session-time.mjs';
+import { openclawNouns } from './openclaw.mjs';
+import { pushPiMessage, pushPiCustom, pushPiSummary } from './session-pi-content.mjs';
+import { nativeTrim } from './text.mjs';
+
+function captureHeader(value, meta, openclaw) {
+  restoreTopLevelResidue(value, meta);
+  meta.session_id = stringField(value, 'id'); meta.cwd = stringField(value, 'cwd');
+  meta.lineage.pi_version = String(nativeInteger(value, 'version') ?? 1n);
+  const time = stringField(value, 'timestamp'), parent = stringField(value, 'parentSession');
+  if (time != null) meta.lineage.created_at = time;
+  if (parent != null) meta.lineage.parent_session_path = parent;
+  if (!Object.hasOwn(meta.lineage, 'claude_fork_context_ref_raw') && field(value, 'claude_fork_context_ref') !== undefined) meta.lineage.claude_fork_context_ref_raw = stringifyNativeJsonMember(value, 'claude_fork_context_ref');
+  if (openclaw && isObject(value)) {
+    const nouns = openclawNouns(value, '');
+    if (nouns.profile != null) meta.profile ??= nouns.profile;
+    if (nouns.trigger != null) { meta.surface = nouns.surface; meta.trigger = nouns.trigger; meta.recurrence = nouns.recurrence ?? null; }
+  }
+}
+
+function fromPiDialect(text, openclaw) {
+  const session = createSession(openclaw ? 'openclaw' : 'pi'), { meta, messages } = session, capture = splitLinesVerbatim(text), values = [], records = new Map();
+  session.raw = capture.lines; session.raw_trailing_newline = capture.trailingNewline; session.raw_is_verbatim = true;
+  capture.lines.forEach((line, index) => {
+    if (nativeTrim(line) === '') return;
+    let value; try { value = parseNativeJson(nativeTrim(line)); } catch { session.parse_error_lines++; return; }
+    values.push(value);
+    const id = stringField(value, 'id'); if (id != null) records.set(id, index);
+  });
+  if (values.length) captureHeader(values[0], meta, openclaw);
+  const entries = [], byId = new Map();
+  for (const value of values.slice(1)) {
+    const id = stringField(value, 'id'); if (id == null) continue;
+    byId.set(id, entries.length); entries.push({ id, parent: stringField(value, 'parentId'), value });
+  }
+  if (!entries.length) { session.imported_message_count = 0; return session; }
+  const defaultLeaf = openclaw ? entries.findLastIndex(({ value }) => stringField(value, 'type') !== 'leaf' && stringField(value, 'appendMode') !== 'side') : entries.length - 1;
+  const redirect = openclaw ? entries.findLast(({ value }) => stringField(value, 'type') === 'leaf') : null;
+  const target = byId.get(stringField(redirect?.value, 'targetId'));
+  const leaf = target ?? (defaultLeaf === -1 ? entries.length - 1 : defaultLeaf), active = [];
+  let cursor = entries[leaf].id;
+  while (cursor != null) {
+    const index = byId.get(cursor); if (index === undefined) break;
+    active.push(index); cursor = entries[index].parent;
+    if (active.length > entries.length + 1) break;
+  }
+  active.reverse();
+  const positions = new Map(); active.forEach((index, position) => positions.set(entries[index].id, position));
+  let keptFrom = 0, model = null;
+  for (const index of active) {
+    const value = entries[index].value;
+    if (stringField(value, 'type') === 'compaction') keptFrom = Math.max(keptFrom, positions.get(stringField(value, 'firstKeptEntryId')) ?? 0);
+  }
+  active.forEach((index, position) => {
+    const entry = entries[index], value = entry.value, kind = stringField(value, 'type'), nested = field(value, 'message'), before = messages.length;
+    if (kind === 'message') { pushPiMessage(nested, messages); if (stringField(nested, 'role') === 'assistant') model = stringField(nested, 'model') ?? model; }
+    else if (kind === 'custom_message') pushPiCustom(value, messages);
+    else if (kind === 'compaction' || kind === 'branch_summary') pushPiSummary(value, messages, kind);
+    else if (kind === 'model_change') model = stringField(value, 'modelId') ?? model;
+    else if (kind === 'session_info') { const name = stringField(value, 'name'); if (name != null && name !== '') meta.lineage.session_name = name; }
+    const timestamp = stringField(value, 'timestamp'), nativeTimestamp = nativeInteger(nested, 'timestamp'), vendor = field(nested, '__openclaw');
+    for (let at = before; at < messages.length; at++) {
+      const message = messages[at]; message.metadata.pi_entry_id = entry.id;
+      if (openclaw && isObject(vendor)) for (const key of nativeObjectKeys(vendor)) message.metadata[`openclaw_${key}`] = valueString(vendor, key);
+      if (entry.parent != null) message.metadata.pi_parent_id = entry.parent;
+      if (timestamp != null && !Object.hasOwn(message.metadata, 'timestamp')) message.metadata.timestamp = timestamp;
+      if (nativeTimestamp != null && !Object.hasOwn(message.metadata, 'timestamp')) message.metadata.timestamp = messageMilliseconds(BigInt.asIntN(64, nativeTimestamp));
+      if (!['compaction', 'branch_summary'].includes(kind) && position < keptFrom) message.metadata.compacted_out = 'true';
+    }
+    if (messages.length === before + 1) restoreGrokMessageExtension(value, messages[before]);
+    for (let at = before; at < messages.length; at++) if (!isToolError(messages[at]) && stringField(value, '_supercode_tool_outcome') === 'unknown') markToolOutcomeUnknown(messages[at]);
+  });
+  meta.model = model; ensureToolResultsPaired(messages);
+  meta.message_records = messages.map((message) => records.get(message.metadata.pi_entry_id) ?? null); session.imported_message_count = messages.length;
+  return session;
+}
+
+export function fromPiStr(text) { return fromPiDialect(text, false); }
+/** OpenClaw's read-only Pi dialect; session-key references remain inert. */
+export function fromOpenClawStr(text) { return fromPiDialect(text, true); }

package/session-read.d.ts

@@ -0,0 +1,12 @@
+import type { ReadLocator, SessionFollowOptions } from './session-codecs.js';
+import { SessionFollower } from './session-codecs.js';
+import type { ProjectedSessionResult, NormalizedSession, RecordedSessionProfile, RecordedSessionProfileChange } from './session-model.js';
+export const SESSION_READ_METHODS: readonly string[];
+export const SESSION_READ_EVENT: 'harness.v1.sessions.event';
+export const SESSION_READ_CAPABILITY: Readonly<{ version: 1; owner: 'caller'; language: 'typescript'; native_parser: false }>;
+export interface SessionReadContext { cwd?: string; env?: Record<string, string | undefined> }
+export function parseSessionWire(text: string): unknown;
+export function stringifySessionWire(value: unknown): string;
+export function parseSessionReadParams(params: unknown, context?: SessionReadContext): { locator: ReadLocator; fidelity: string; view: (SessionFollowOptions & { fromByte: number | null }) | null; options: import('./session-model.js').SessionLoadOptions | null };
+export function loadSessionRead(params: unknown, context?: SessionReadContext): Promise<ProjectedSessionResult | { session: NormalizedSession & { resolved_profile: RecordedSessionProfile; resolved_profile_history: RecordedSessionProfileChange[] } }>;
+export function openSessionReadFollower(params: unknown, context?: SessionReadContext): Promise<SessionFollower>;

package/session-read.mjs

@@ -0,0 +1,104 @@
+// Caller-owned public read operations. Parsing never goes to a native service
+// or to a machine daemon carrying another caller's home/environment.
+import { resolve } from 'node:path';
+import { nativeInteger, nativeNumberKind, parseNativeJson, stringifyNativeJson } from './native-json.mjs';
+import { loadSessionLocator } from './session-path.mjs';
+import { loadSessionDisplayLocator, loadSessionDisplayFrom } from './session-display.mjs';
+import { withClaudeReadIndex, supportsClaudeReadIndex } from './session-claude-index.mjs';
+import { SessionFollower } from './session-follower.mjs';
+import { normalizedSessionJson } from './session-model.mjs';
+import { boundSessionView, projectedMessageWindow, projectedSessionJson, projectedSessionResult, projectedSessionSummary, recordedSessionProfile, recordedSessionProfileHistory } from './session-views.mjs';
+
+export const SESSION_READ_METHODS = Object.freeze(['harness.v1.sessions.load', 'harness.v1.sessions.follow', 'harness.v1.sessions.unfollow']);
+export const SESSION_READ_EVENT = 'harness.v1.sessions.event';
+export const SESSION_READ_CAPABILITY = Object.freeze({ version: 1, owner: 'caller', language: 'typescript', native_parser: false });
+export { parseNativeJson as parseSessionWire, stringifyNativeJson as stringifySessionWire };
+const invalid = (message) => { throw Object.assign(new Error(message), { rpcCode: -32602 }); };
+const object = (value, name) => {
+  if (value == null || typeof value !== 'object' || Array.isArray(value)) invalid(`${name} must be an object`);
+  return value;
+};
+const string = (value, name) => { if (typeof value !== 'string') invalid(`${name} must be a string`); return value; };
+function boolean(parent, key, fallback, nullable = false) {
+  if (!Object.hasOwn(parent, key) || nullable && parent[key] == null) return fallback;
+  if (typeof parent[key] !== 'boolean') invalid(`${key} must be a boolean`);
+  return parent[key];
+}
+function unsigned(parent, key, maximum = Number.MAX_SAFE_INTEGER) {
+  if (parent[key] == null) return null;
+  const exact = nativeInteger(parent, key);
+  if (exact != null) return Number(exact > BigInt(maximum) ? BigInt(maximum) : exact);
+  if (nativeNumberKind(parent, key) != null) invalid(`${key} must be an unsigned 64-bit integer`);
+  if (!Number.isSafeInteger(parent[key]) || parent[key] < 0) invalid(`${key} must be an unsigned 64-bit integer`);
+  return Math.min(parent[key], maximum);
+}
+
+export function parseSessionReadParams(params, { cwd = process.cwd() } = {}) {
+  object(params, 'session read params'); const supplied = object(params.locator, 'locator'), storage = object(supplied.storage, 'locator.storage');
+  string(supplied.harness, 'locator.harness'); // HarnessId is extensible, including third-party names.
+  if (!['file', 'sqlite'].includes(storage.kind)) invalid('locator.storage.kind must be file or sqlite');
+  const locator = { harness: supplied.harness, session_id: string(supplied.session_id, 'locator.session_id'),
+    storage: { kind: storage.kind, path: resolve(cwd, string(storage.path, 'locator.storage.path')) } };
+  if (storage.kind === 'sqlite') locator.storage.selector = string(storage.selector, 'locator.storage.selector');
+  const fidelity = params.fidelity ?? 'semantic';
+  if (!['semantic', 'value_lossless', 'byte_lossless'].includes(fidelity)) invalid(`unknown fidelity: ${fidelity}`);
+  let view = null;
+  if (params.view != null) {
+    const suppliedView = object(params.view, 'view');
+    view = { includeSubagents: boolean(suppliedView, 'include_subagents', false), displayHistory: boolean(suppliedView, 'display_history', false),
+      messageLimit: unsigned(suppliedView, 'tail_messages', 5000), maxMessageChars: unsigned(suppliedView, 'max_message_chars', 64000),
+      fromByte: unsigned(suppliedView, 'from_byte') };
+    if (view.messageLimit != null) view.messageLimit = Math.max(1, view.messageLimit);
+    if (view.maxMessageChars != null) view.maxMessageChars = Math.max(256, view.maxMessageChars);
+  }
+  let options = null;
+  if (params.options != null) {
+    const suppliedOptions = object(params.options, 'options');
+    const inline = Object.hasOwn(suppliedOptions, 'inline_media') ? suppliedOptions.inline_media : 'full'; if (!['full', 'metadata'].includes(inline)) invalid('inline_media must be full or metadata');
+    options = { include_subagents: boolean(suppliedOptions, 'include_subagents', null, true), inline_media: inline };
+    for (const key of ['max_inline_media_bytes', 'message_limit', 'message_offset', 'message_tail']) options[key] = unsigned(suppliedOptions, key);
+    if (options.message_tail != null && (options.message_limit != null || options.message_offset != null)) invalid('sessions.load options.message_tail cannot be combined with message_limit or message_offset');
+  }
+  return { locator, fidelity, view, options };
+}
+
+async function indexedWindow(locator, options, context) {
+  if (locator.harness !== 'claude-code' || options.include_subagents !== false || locator.storage.kind !== 'file'
+    || !await supportsClaudeReadIndex(locator.storage.path, context)) return null;
+  return (await withClaudeReadIndex(locator.storage.path, async (index) => {
+    const total = index.length, [offset, end] = projectedMessageWindow(total, options);
+    const indices = (function* () { for (let at = offset; at < end; at++) yield at; })();
+    const session = await index.readMessages(indices), summary = await index.readSummary();
+    const selected = projectedSessionJson(session, { ...options, message_offset: null, message_limit: null, message_tail: null });
+    selected.raw_record_count = index.rawRecordCount;
+    return { session: selected, summary: projectedSessionSummary(summary, options),
+      window: { has_more: offset > 0 || end < total, has_newer: end < total, has_older: offset > 0,
+        newer_items: index.itemCount(end, total), offset, older_items: index.itemCount(0, offset), returned: end - offset, total_messages: total } };
+  }, { ...context, fidelity: 'byte_lossless' })).result;
+}
+
+export async function loadSessionRead(params, context = {}) {
+  const { locator, fidelity, view, options } = parseSessionReadParams(params, context);
+  if (options != null) {
+    const indexed = await indexedWindow(locator, options, context); if (indexed != null) return indexed;
+    // The exact options lane is the historical lossless load, independently
+    // of the read-view fidelity knob. Projection happens after reconstruction.
+    return projectedSessionResult(await loadSessionLocator(locator, { ...context, fidelity: 'byte_lossless' }), options);
+  }
+  const readOptions = { ...context, fidelity, includeSubagents: view?.includeSubagents ?? true };
+  const session = view?.displayHistory
+    ? view.fromByte != null ? await loadSessionDisplayFrom(locator, view.fromByte, readOptions)
+      : await loadSessionDisplayLocator(locator, view.messageLimit ?? 500, readOptions)
+    : await loadSessionLocator(locator, readOptions);
+  if (view?.fromByte == null) boundSessionView(session, view?.messageLimit, view?.maxMessageChars);
+  return { session: { ...normalizedSessionJson(session), resolved_profile: recordedSessionProfile(session),
+    resolved_profile_history: recordedSessionProfileHistory(session) } };
+}
+export async function openSessionReadFollower(params, context = {}) {
+  object(params, 'session read params');
+  // Follow's native grammar ignores load-only options, including unknown
+  // fields. Only its LocatorParams fields participate in admission.
+  const { locator, fidelity, view } = parseSessionReadParams({ locator: params.locator, fidelity: params.fidelity, view: params.view }, context);
+  return SessionFollower.openLocator(locator, { ...context, fidelity, includeSubagents: view?.includeSubagents ?? true,
+    displayHistory: view?.displayHistory ?? false, messageLimit: view?.messageLimit, maxMessageChars: view?.maxMessageChars });
+}

package/session-source.mjs

@@ -0,0 +1,30 @@
+import { parseNativeJson } from './native-json.mjs';
+import { field, stringField } from './session-codec-utils.mjs';
+import { nonEmptyLines } from './session-lines.mjs';
+import { nativeTrim } from './text.mjs';
+
+/** Source provenance is recovered structurally; discussing a harness never
+ * selects its dialect. Corrupt lines are tolerated by the native detector. */
+export function detectSessionSource(text) {
+  let document; try { document = parseNativeJson(nativeTrim(text)); } catch { /* JSONL is considered below. */ }
+  if (Array.isArray(field(document, 'conversation')) && (field(document, 'working_dir') !== undefined || field(document, 'workingDir') !== undefined)) return 'goose';
+  if (field(document, 'info') !== undefined && Array.isArray(field(document, 'messages'))) return 'opencode';
+  for (const line of nonEmptyLines(text)) {
+    let value; try { value = parseNativeJson(line); } catch { continue; }
+    if (Array.isArray(field(value, 'key')) && field(value, 'value') !== undefined) return 'opencode';
+    if (field(value, 'payload') !== undefined) return 'codex';
+    const kind = stringField(value, 'type');
+    if (stringField(value, 'sessionId') != null && ['projectHash', 'startTime', 'lastUpdated'].some((key) => field(value, key) !== undefined) && field(value, 'type') === undefined) return 'gemini';
+    if (kind === 'gemini' && field(value, 'content') !== undefined) return 'gemini';
+    if (['message', 'uuid', 'sessionId'].every((key) => field(value, key) === undefined) && ['system', 'user', 'assistant', 'tool_result', 'reasoning', 'backend_tool_call'].includes(kind) && ['content', 'tool_calls', 'tool_call_id', 'encrypted_content', 'kind'].some((key) => field(value, key) !== undefined)) return 'grok';
+    if (kind === 'session' && stringField(value, 'id') != null && field(value, 'message') === undefined && field(value, 'uuid') === undefined) {
+      for (const body of nonEmptyLines(text)) {
+        let entry; try { entry = parseNativeJson(body); } catch { continue; }
+        if ((stringField(entry, 'type') === 'leaf' && field(entry, 'targetId') !== undefined) || (stringField(entry, 'type') === 'message' && field(field(entry, 'message'), '__openclaw') !== undefined)) return 'openclaw';
+      }
+      return 'pi';
+    }
+    if (field(value, 'type') !== undefined || field(value, 'message') !== undefined) return 'claude_code';
+  }
+  return null;
+}