@volter/supercode-interchange 0.1.1 → 0.1.3

package/session-model.d.ts

@@ -0,0 +1,114 @@
+import type { SessionSurface, SessionTrigger } from './index.js';
+
+/** Native JSON numeric token information is retained privately by the reader.
+ * Source bytes are stored separately; a display object is not an export. */
+export type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue };
+export type SessionSource = 'claude_code' | 'codex' | 'opencode' | 'pi' | 'grok' | 'gemini' | 'goose' | 'openclaw' | 'hermes' | 'native';
+/** Only sources with a declared read/write translation format. */
+export type SessionFormat = 'claude_code' | 'codex' | 'opencode' | 'pi' | 'grok' | 'gemini' | 'goose';
+export type LoadFidelity = 'byte_lossless' | 'value_lossless' | 'semantic';
+export type MessageRole = 'system' | 'user' | 'assistant' | 'tool';
+export interface FunctionCall { name: string; arguments: string }
+export interface ToolCall { id: string; type: string; function: FunctionCall }
+export interface ChatMessage {
+  role: MessageRole; content: string | null; content_parts: JsonValue[] | null;
+  tool_calls: ToolCall[] | null; tool_call_id: string | null; name: string | null;
+  metadata: Record<string, string>;
+}
+export interface MessageWire {
+  role: MessageRole; content?: string | JsonValue[]; tool_calls?: ToolCall[];
+  tool_call_id?: string; name?: string;
+}
+export interface MessageJson extends MessageWire { metadata: Record<string, string> }
+export type ToolOutcome = 'known_success' | 'known_error' | 'unknown';
+export interface SessionMeta {
+  source: SessionSource; session_id: string | null; ended_at: string | null; end_reason: string | null;
+  model: string | null; cwd: string | null; system_prompt: string | null;
+  codex_headers: JsonValue[]; codex_provenance: JsonValue[];
+  native_residue: JsonValue[]; native_residue_source: string | null;
+  message_records: Array<number | bigint | null>; opencode_headers: JsonValue[]; goose_header: JsonValue | null;
+  agent_id: string | null; parent_tool_use_id: string | null; lineage: Record<string, string>;
+  trigger: SessionTrigger | null; surface: SessionSurface | null; profile: string | null;
+  recurrence: { job_id: string; kind: string } | null;
+  cross_surface: { state: string; platform?: string; error?: string } | null;
+}
+/** Complete retained representation, distinct from its bounded read view. */
+export interface Session {
+  meta: SessionMeta; messages: ChatMessage[]; subagents: Session[]; raw: string[];
+  raw_trailing_newline: boolean; imported_message_count: number | null;
+  raw_is_verbatim: boolean; parse_error_lines: number; load_residue: string[];
+}
+export interface NormalizedSession {
+  source: SessionSource; session_id: string | null; ended_at: string | null; end_reason: string | null;
+  model: string | null; cwd: string | null; system_prompt: string | null;
+  agent_id: string | null; parent_tool_use_id: string | null; lineage: Record<string, string>;
+  trigger: SessionTrigger; surface: SessionSurface | null; profile: string | null;
+  recurrence: SessionMeta['recurrence']; cross_surface: SessionMeta['cross_surface'];
+  workspace: { kind: 'repo' | 'channel' | 'none'; value?: string };
+  messages: MessageJson[]; subagents: NormalizedSession[]; raw_record_count: number;
+  total_message_count: number; parse_error_lines: number; fidelity: LoadFidelity; residue: string[];
+}
+/** Service parsing validates nonnegative integral sizes and rejects tail plus
+ * offset/limit. These representation helpers consume already parsed options. */
+export interface SessionLoadOptions {
+  include_subagents?: boolean | null; inline_media?: 'full' | 'metadata'; max_inline_media_bytes?: number | null;
+  message_limit?: number | null; message_offset?: number | null; message_tail?: number | null;
+}
+export interface RecordedSessionProfile {
+  worker: { harness: string; model: string | null; cwd: string | null; binary: { version: string | null } };
+  permissions: { native: { approval: JsonValue; sandbox: JsonValue } }; source: 'native-session';
+}
+export interface RecordedSessionProfileChange { native_key: string; at: string | null; profile: RecordedSessionProfile }
+export interface ProjectedSession {
+  source: SessionSource; session_id: string | null; ended_at: string | null; end_reason: string | null;
+  model: string | null; resolved_profile: RecordedSessionProfile; resolved_profile_history: RecordedSessionProfileChange[];
+  cwd: string | null; system_prompt: string | null; agent_id: string | null; parent_tool_use_id: string | null;
+  lineage: Record<string, string>; messages: MessageJson[]; subagents: ProjectedSession[];
+  raw_record_count: number; parse_error_lines: number;
+}
+export interface SessionSummary {
+  end_of_turn: boolean; first_assistant_message: MessageJson | null; first_message: MessageJson | null;
+  last_assistant_message: MessageJson | null; last_assistant_text: string; last_message: MessageJson | null;
+}
+export interface SessionMessageWindow {
+  has_more: boolean; has_newer: boolean; has_older: boolean; newer_items: number; offset: number;
+  older_items: number; returned: number; total_messages: number;
+}
+export interface ProjectedSessionResult { session: ProjectedSession; summary: SessionSummary; window: SessionMessageWindow }
+
+export const SESSION_SOURCES: readonly SessionSource[];
+export const SESSION_FORMATS: readonly SessionFormat[];
+export const ROLES: readonly MessageRole[];
+export const TOOL_ERROR_METADATA_KEY: 'sc.tool_error';
+export const TOOL_OUTCOME_UNKNOWN_METADATA_KEY: 'sc.tool_outcome_unknown';
+export function sourceFormat(source: SessionSource): SessionFormat | null;
+export function createMessage(role: MessageRole, content?: string | null): ChatMessage;
+export function deserializeMessage(value: unknown): ChatMessage;
+export function messageWire(message: ChatMessage): MessageWire;
+export function messageJson(message: ChatMessage): MessageJson;
+export function parsedArguments(call: ToolCall): JsonValue;
+export function markToolError(message: ChatMessage): void;
+export function markToolOutcomeUnknown(message: ChatMessage): void;
+export function isToolError(message: ChatMessage): boolean;
+export function toolOutcome(message: ChatMessage): ToolOutcome;
+export function splitLinesVerbatim(text: string): { lines: string[]; trailingNewline: boolean };
+export function joinLinesVerbatim(lines: readonly string[], trailingNewline: boolean): string;
+export function nonEmptyLines(text: string): Generator<string>;
+export function createSession(source: SessionSource, messages?: ChatMessage[]): Session;
+export function rawVerbatim(session: Session): string;
+export function loadFidelity(session: Session): LoadFidelity;
+export function sessionTrigger(meta: SessionMeta): SessionTrigger;
+export function sessionWorkspace(meta: SessionMeta): NormalizedSession['workspace'];
+export function codexStartTrigger(payload: JsonValue): SessionTrigger | null;
+export function normalizedSessionJson(session: Session): NormalizedSession;
+export function boundSessionView(session: Session, messageLimit?: number | null, maxMessageChars?: number | null): void;
+export function messageHasContent(message: ChatMessage): boolean;
+export function messageText(message: ChatMessage): string;
+export function normalizedItemCount(messages: readonly ChatMessage[]): number;
+export function projectedMessageWindow(total: number, options: SessionLoadOptions): [number, number];
+export function projectInlineMedia(message: MessageJson, options: SessionLoadOptions): MessageJson;
+export function projectedSessionSummary(session: Session, options: SessionLoadOptions): SessionSummary;
+export function recordedSessionProfile(session: Session): RecordedSessionProfile;
+export function recordedSessionProfileHistory(session: Session): RecordedSessionProfileChange[];
+export function projectedSessionJson(session: Session, options: SessionLoadOptions): ProjectedSession;
+export function projectedSessionResult(session: Session, options: SessionLoadOptions): ProjectedSessionResult;

package/session-model.mjs

@@ -0,0 +1,70 @@
+import { messageJson } from './message.mjs';
+import { cloneNativeJson } from './native-json.mjs';
+import { joinLinesVerbatim } from './session-lines.mjs';
+
+export const SESSION_SOURCES = Object.freeze(['claude_code', 'codex', 'opencode', 'pi', 'grok', 'gemini', 'goose', 'openclaw', 'hermes', 'native']);
+export const SESSION_FORMATS = Object.freeze(['claude_code', 'codex', 'opencode', 'pi', 'grok', 'gemini', 'goose']);
+export const sourceFormat = (source) => SESSION_FORMATS.includes(source) ? source : null;
+
+export function createSession(source, messages = []) {
+  if (!SESSION_SOURCES.includes(source)) throw new TypeError(`unknown session source: ${source}`);
+  return {
+    meta: {
+      source, session_id: null, ended_at: null, end_reason: null, model: null, cwd: null, system_prompt: null,
+      codex_headers: [], codex_provenance: [], native_residue: [], native_residue_source: null,
+      message_records: [], opencode_headers: [], goose_header: null, agent_id: null, parent_tool_use_id: null,
+      lineage: Object.create(null), trigger: null, surface: null, profile: null, recurrence: null, cross_surface: null,
+    },
+    messages, subagents: [], raw: [], raw_trailing_newline: true, imported_message_count: null,
+    raw_is_verbatim: false, parse_error_lines: 0, load_residue: [],
+  };
+}
+
+export function rawVerbatim(session) { return joinLinesVerbatim(session.raw, session.raw_trailing_newline); }
+
+export function loadFidelity(session) {
+  if (session.load_residue.length || session.subagents.some((child) => loadFidelity(child) === 'semantic')) return 'semantic';
+  return session.raw_is_verbatim ? 'byte_lossless' : 'value_lossless';
+}
+
+export function sessionTrigger(meta) {
+  if (meta.trigger != null) return meta.trigger;
+  return meta.agent_id != null || meta.parent_tool_use_id != null || meta.lineage.hermes_lineage_kind === 'delegate' ? 'parent' : 'human';
+}
+
+export function sessionWorkspace(meta) {
+  if (meta.cwd != null) return { kind: 'repo', value: meta.cwd };
+  if (meta.surface?.platform != null) return {
+    kind: 'channel', value: meta.surface.platform + (meta.surface.chat_id != null ? `:${meta.surface.chat_id}` : ''),
+  };
+  return { kind: 'none' };
+}
+
+export function codexStartTrigger(payload) {
+  if (payload?.source != null && typeof payload.source === 'object' && Object.hasOwn(payload.source, 'subagent')) return 'parent';
+  const originator = payload?.originator;
+  return typeof originator === 'string' && (originator === 'codex_exec' || originator === 'supercode' || originator.startsWith('supercode_')) ? 'api' : null;
+}
+
+export function normalizedSessionJson(session) {
+  const { meta } = session;
+  return {
+    source: meta.source, session_id: meta.session_id, ended_at: meta.ended_at, end_reason: meta.end_reason,
+    model: meta.model, cwd: meta.cwd, system_prompt: meta.system_prompt, agent_id: meta.agent_id,
+    parent_tool_use_id: meta.parent_tool_use_id, lineage: cloneNativeJson(meta.lineage), trigger: sessionTrigger(meta),
+    surface: cloneNativeJson(meta.surface), profile: meta.profile, recurrence: cloneNativeJson(meta.recurrence),
+    cross_surface: cloneNativeJson(meta.cross_surface), workspace: sessionWorkspace(meta),
+    messages: session.messages.map(messageJson), subagents: session.subagents.map(normalizedSessionJson),
+    raw_record_count: session.raw.length,
+    total_message_count: Math.max(session.imported_message_count ?? session.messages.length, session.messages.length),
+    parse_error_lines: session.parse_error_lines, fidelity: loadFidelity(session), residue: [...session.load_residue],
+  };
+}
+
+export { createMessage, deserializeMessage, messageWire, messageJson, parsedArguments, markToolError, markToolOutcomeUnknown, isToolError, toolOutcome, ROLES, TOOL_ERROR_METADATA_KEY, TOOL_OUTCOME_UNKNOWN_METADATA_KEY } from './message.mjs';
+export { splitLinesVerbatim, joinLinesVerbatim, nonEmptyLines } from './session-lines.mjs';
+export {
+  boundSessionView, messageHasContent, messageText, normalizedItemCount, projectedMessageWindow,
+  projectInlineMedia, projectedSessionSummary, recordedSessionProfile, recordedSessionProfileHistory,
+  projectedSessionJson, projectedSessionResult,
+} from './session-views.mjs';

package/session-native-residue.mjs

@@ -0,0 +1,109 @@
+import { blake3 } from '@noble/hashes/blake3.js';
+import { cloneNativeJson, nativeInteger, nativeObjectKeys, parseNativeJson, setNativeInteger, stringifyNativeJson, stringifyNativeJsonMember } from './native-json.mjs';
+import { field, isObject, stringField } from './session-codec-utils.mjs';
+
+export const NATIVE_RESIDUE_KEY = '_supercode_native_residue';
+export const NATIVE_RESIDUE_SUMMARY_KEY = '_supercode_native_residue_summary';
+export const CODEX_PROVENANCE_KEY = '_supercode_codex_provenance';
+const fail = (message) => { throw Object.assign(new Error(message), { code: 'invalid_session' }); };
+const utf8Order = (left, right) => Buffer.compare(Buffer.from(left), Buffer.from(right));
+
+function canonical(value, parent = null, key = null) {
+  if (Array.isArray(value)) return `[${value.map((child, at) => canonical(child, value, at)).join(',')}]`;
+  if (isObject(value)) return `{${nativeObjectKeys(value).sort(utf8Order).map((key) => `${JSON.stringify(key)}:${canonical(value[key], value, key)}`).join(',')}}`;
+  return parent == null ? stringifyNativeJson(value) : stringifyNativeJsonMember(parent, key);
+}
+
+/** The historical field says sha256; the shipped contract uses BLAKE3. */
+export function residueRecordsDigest(records) { return Buffer.from(blake3(Buffer.from(canonical(records)))).toString('hex'); }
+
+export function claudeResidueKind(record) {
+  const kind = stringField(record, 'type');
+  return ['file-history-snapshot', 'queue-operation', 'last-prompt', 'mode', 'fork-context-ref'].includes(kind) ? kind : null;
+}
+export function grokResidueKind(record) {
+  if (!isObject(record)) return null;
+  const kind = stringField(record, 'type');
+  return kind == null ? 'untyped' : ['system', 'user', 'assistant', 'tool_result'].includes(kind) ? null : kind;
+}
+export function codexProvenanceKind(record) {
+  const kind = stringField(record, 'type');
+  if (['session_meta', 'turn_context', 'compacted'].includes(kind)) return kind;
+  const event = stringField(field(record, 'payload'), 'type');
+  return kind === 'event_msg' && ['thread_rolled_back', 'thread_goal_updated', 'entered_review_mode', 'exited_review_mode'].includes(event) ? `event_msg/${event}` : null;
+}
+
+export function captureNativeResidue(meta, source, recordIndex, raw, record, kind) {
+  if ([NATIVE_RESIDUE_KEY, NATIVE_RESIDUE_SUMMARY_KEY, CODEX_PROVENANCE_KEY].some((key) => field(record, key) !== undefined)) return;
+  if (meta.native_residue_source != null && meta.native_residue_source !== source) return;
+  const entry = { record_index: 0, kind, raw }; setNativeInteger(entry, 'record_index', BigInt(recordIndex));
+  meta.native_residue.push(entry); meta.native_residue_source = source;
+}
+export function captureCodexProvenance(meta, recordIndex, raw, record) {
+  const kind = codexProvenanceKind(record);
+  if (kind == null) return;
+  const entry = { record_index: 0, kind, raw }; setNativeInteger(entry, 'record_index', BigInt(recordIndex));
+  meta.codex_provenance.push(entry);
+}
+
+export function restoreCodexProvenance(extension, meta) {
+  if (nativeInteger(extension, 'version') !== 1n) fail('invalid portable Codex provenance: expected version 1');
+  const records = field(extension, 'records');
+  if (!Array.isArray(records)) fail('invalid portable Codex provenance: `records` must be an array');
+  if (!records.length) fail('invalid portable Codex provenance: `records` must not be empty');
+  const restored = [], headers = [];
+  for (const entry of records) {
+    if (nativeInteger(entry, 'record_index') == null) fail('invalid portable Codex provenance: record_index must be an integer');
+    const kind = stringField(entry, 'kind'), raw = stringField(entry, 'raw');
+    if (kind == null) fail('invalid portable Codex provenance: kind must be a string');
+    if (raw == null) fail('invalid portable Codex provenance: raw must be a string');
+    let record;
+    try { record = parseNativeJson(raw); } catch { fail('invalid portable Codex provenance: raw is not valid JSON'); }
+    if (codexProvenanceKind(record) !== kind) fail(`invalid portable Codex provenance: kind \`${kind}\` does not match raw record`);
+    restored.push(cloneNativeJson(entry));
+    if (['session_meta', 'turn_context'].includes(stringField(record, 'type'))) headers.push(record);
+  }
+  meta.codex_provenance = restored; meta.codex_headers = headers;
+  return true;
+}
+
+export function restoreNativeResidue(extension, meta) {
+  const version = nativeInteger(extension, 'version');
+  if (version !== 2n) fail(`invalid portable native residue: expected version 2, found ${version == null ? 'None' : `Some(${version})`} — source-native records cannot be restored from this envelope`);
+  const source = stringField(extension, 'source');
+  if (!['codex', 'claude_code', 'grok'].includes(source)) fail(`invalid portable native residue: unsupported source ${source == null ? 'None' : `Some(${JSON.stringify(source)})`} — this build restores codex, claude_code and grok residue; the records are preserved raw but not replayed`);
+  const records = field(extension, 'records');
+  if (!Array.isArray(records)) fail('invalid portable native residue: `records` must be an array');
+  const claimed = stringField(extension, 'records_sha256');
+  if (claimed == null) fail('invalid portable native residue: `records_sha256` digest is missing — cannot verify the residue was not tampered with; refusing to restore');
+  if (claimed !== residueRecordsDigest(records)) fail('invalid portable native residue: records digest mismatch — the residue was modified or corrupted after export; refusing to restore source-native records');
+  if (source === 'codex') {
+    const v1 = { version: 0, records }; setNativeInteger(v1, 'version', 1n);
+    return restoreCodexProvenance(v1, meta);
+  }
+  const restored = [];
+  for (const entry of records) {
+    const kind = stringField(entry, 'kind'), raw = stringField(entry, 'raw');
+    if (nativeInteger(entry, 'record_index') == null || kind == null || raw == null) fail('invalid portable native residue: each record needs record_index/kind/raw');
+    let record;
+    try { record = parseNativeJson(raw); } catch { fail('invalid portable native residue: raw is not valid JSON'); }
+    const expected = source === 'claude_code' ? claudeResidueKind(record) : grokResidueKind(record);
+    if (expected !== kind) fail(`invalid portable native residue: kind \`${kind}\` does not match raw record`);
+    restored.push(cloneNativeJson(entry));
+  }
+  if (!restored.length) fail('invalid portable native residue: `records` must not be empty');
+  meta.native_residue = restored; meta.native_residue_source = source;
+  return true;
+}
+
+export function restoreTopLevelResidue(record, meta) {
+  if (field(record, NATIVE_RESIDUE_KEY) !== undefined) return restoreNativeResidue(record[NATIVE_RESIDUE_KEY], meta);
+  if (field(record, CODEX_PROVENANCE_KEY) !== undefined) return restoreCodexProvenance(record[CODEX_PROVENANCE_KEY], meta);
+  const summary = field(record, NATIVE_RESIDUE_SUMMARY_KEY);
+  if (summary !== undefined) {
+    const kinds = field(summary, 'kinds'), count = nativeInteger(summary, 'records') ?? 0n, source = stringField(summary, 'source') ?? 'unknown';
+    const names = Array.isArray(kinds) ? kinds.filter((kind) => typeof kind === 'string').join(', ') : '';
+    meta.lineage.residue_loss = `portable ${source} residue deleted: ${count} record(s) of kind(s) [${names}] can no longer be restored`;
+  }
+  return false;
+}

package/session-native.mjs

@@ -0,0 +1,62 @@
+import { createSession } from './session-model.mjs';
+import { deserializeMessage } from './message.mjs';
+import { parseNativeJson, cloneNativeJson, nativeInteger, nativeObjectKeys } from './native-json.mjs';
+import { field, stringField, isObject } from './session-codec-utils.mjs';
+import { splitLinesVerbatim, joinLinesVerbatim } from './session-lines.mjs';
+import { readSessionDocument } from './session-document.mjs';
+
+const invalid = (message) => { throw Object.assign(new Error(message), { code: 'invalid_session' }); };
+function nativeTurn(value) {
+  const discriminant = nativeInteger(value, 'supercode_turn');
+  if (discriminant == null || discriminant > 255n || stringField(value, 'ts') == null) invalid('native turn needs an unsigned byte discriminator and a string ts');
+  const content = field(value, 'content'), parts = field(value, 'content_parts');
+  if (content != null && typeof content !== 'string') invalid('native turn content must be text');
+  if (parts != null && !Array.isArray(parts)) invalid('native turn content_parts must be an array');
+  const message = deserializeMessage(value);
+  message.content_parts = parts == null ? null : cloneNativeJson(parts);
+  const metadata = field(value, 'metadata');
+  if (metadata !== undefined) {
+    if (!isObject(metadata)) invalid('native turn metadata must be an object');
+    for (const key of nativeObjectKeys(metadata)) {
+      if (typeof metadata[key] !== 'string') invalid('native turn metadata values must be strings');
+      message.metadata[key] = metadata[key];
+    }
+  }
+  return message;
+}
+
+/** Tolerant native wrapper reader; persisted sidecars use the strict framing
+ * entrypoint below. Rejected appended turns survive in raw and parse loss. */
+export function fromNativeStr(text) {
+  const lines = splitLinesVerbatim(text).lines;
+  let header; try { header = parseNativeJson(lines[0] ?? ''); } catch { header = null; }
+  const trailing = typeof field(header, 'raw_trailing_newline') === 'boolean' ? header.raw_trailing_newline : true;
+  const body = [], turns = [];
+  for (const line of lines.slice(1)) {
+    let value; try { value = parseNativeJson(line); } catch { /* Broken body records are handled by the source codec. */ }
+    (field(value, 'supercode_turn') === undefined ? body : turns).push(line);
+  }
+  const source = stringField(header, 'source'), original = joinLinesVerbatim(body, trailing);
+  const known = ['claude_code', 'codex', 'pi', 'opencode', 'grok', 'gemini', 'goose', 'openclaw'];
+  const session = readSessionDocument(original, source === 'native' ? { source: 'claude_code' } : known.includes(source) ? { source } : {});
+  if (source === 'native') session.meta.source = 'native';
+  for (const line of turns) {
+    session.raw.push(line);
+    try { session.messages.push(nativeTurn(parseNativeJson(line))); } catch { session.parse_error_lines++; }
+  }
+  for (const key of ['agent_id', 'parent_tool_use_id']) { const value = stringField(header, key); if (value != null) session.meta[key] = value; }
+  const lineage = field(header, 'lineage');
+  if (isObject(lineage)) for (const key of nativeObjectKeys(lineage)) if (typeof lineage[key] === 'string') session.meta.lineage[key] = lineage[key];
+  return session;
+}
+
+export function fromSidecarStr(text) {
+  const first = splitLinesVerbatim(text).lines[0];
+  if (first === undefined) invalid('sidecar header is missing from an empty artifact');
+  let header; try { header = parseNativeJson(first); } catch (error) { invalid(`sidecar header is not valid JSON: ${error.message}`); }
+  if (![1n, 2n].includes(nativeInteger(header, 'supercode_native'))) invalid('sidecar header must declare supported `supercode_native` version 1 or 2');
+  if (!['native', 'claude_code', 'codex', 'gemini', 'goose', 'opencode', 'pi', 'grok'].includes(stringField(header, 'source'))) invalid('sidecar header must declare a supported `source`');
+  return fromNativeStr(text);
+}
+
+export function fromNativeMessages(messages) { return createSession('native', messages); }

package/session-opencode-content.mjs

@@ -0,0 +1,115 @@
+import { createMessage, markToolError, isToolError, markToolOutcomeUnknown } from './message.mjs';
+import { nativeInteger, stringifyNativeJsonMember } from './native-json.mjs';
+import { field, stringField, functionCall, restoreGrokMessageExtension } from './session-codec-utils.mjs';
+import { messageMilliseconds } from './session-time.mjs';
+import { nativeTrim } from './text.mjs';
+
+export const OPENCODE_ORIGINAL_POSITION = '__supercode_original_position';
+export const OPENCODE_COMPACTED_TOOL_PLACEHOLDER = '[Old tool result content cleared]';
+const append = (text, part) => typeof part === 'string' ? text + (text === '' ? '' : '\n') + part : text;
+const partsOf = (value) => Array.isArray(value) ? value : [];
+
+export function opencodeImagePart(part) {
+  const mime = stringField(part, 'mime'), url = stringField(part, 'url');
+  return mime?.startsWith('image/') && url?.startsWith('data:') ? { type: 'image_url', image_url: { url } } : null;
+}
+function timestamp(value, message) {
+  const ms = nativeInteger(field(value, 'time'), 'created', { signed: true });
+  if (ms != null) message.metadata.timestamp = messageMilliseconds(ms);
+}
+function retainJson(value, message, key) {
+  if (field(value, key) != null) message.metadata[key] = stringifyNativeJsonMember(value, key);
+}
+
+export function pushOpenCodeUser(value, parts, session) {
+  // The namespaced single synthetic part is our portable Claude system marker.
+  const only = parts.length === 1 ? parts[0] : null;
+  const subtype = stringField(field(only, 'metadata'), 'supercode_claude_system_subtype');
+  if (stringField(only, 'type') === 'text' && field(only, 'synthetic') === true && subtype != null) {
+    const text = stringField(only, 'text');
+    if (text == null || nativeTrim(text) === '') return;
+    const message = createMessage('system', text); message.metadata.systemSubtype = subtype;
+    timestamp(value, message); session.messages.push(message); return;
+  }
+  let text = '', ignored = false;
+  const images = [];
+  for (const part of parts) {
+    if (stringField(part, 'type') === 'text') {
+      if (field(part, 'ignored') === true) ignored = true;
+      else text = append(text, stringField(part, 'text'));
+    } else if (stringField(part, 'type') === 'file') {
+      const image = opencodeImagePart(part); if (image != null) images.push(image);
+    }
+  }
+  if (nativeTrim(text) === '' && !images.length) return;
+  const message = createMessage('user', images.length ? null : text);
+  if (images.length) message.content_parts = [...(nativeTrim(text) === '' ? [] : [{ type: 'text', text }]), ...images];
+  if (ignored) message.metadata.oc_has_ignored_part = 'true';
+  const id = stringField(value, 'id'), agent = stringField(value, 'agent'), system = stringField(value, 'system');
+  if (id != null) message.metadata.oc_message_id = id;
+  if (agent != null) message.metadata.agent = agent;
+  retainJson(value, message, 'model');
+  if (system != null) {
+    if (!session.firstSystemSeen) { session.meta.system_prompt = system; session.firstSystemSeen = true; }
+    message.metadata.system = system;
+  }
+  for (const part of parts) if (stringField(part, 'type') === 'compaction') {
+    message.metadata.phase = 'compaction';
+    const tail = stringField(part, 'tail_start_id'); if (tail != null) message.metadata.tail_start_id = tail;
+  }
+  timestamp(value, message); restoreGrokMessageExtension(value, message); session.messages.push(message);
+}
+
+export function pushOpenCodeAssistant(value, parts, session) {
+  let text = '', thinking = '', reasoningSeen = false, signature = null;
+  const calls = [], results = [];
+  for (const part of parts) {
+    const kind = stringField(part, 'type');
+    if (kind === 'text' && field(part, 'ignored') !== true) text = append(text, stringField(part, 'text'));
+    else if (kind === 'reasoning') {
+      reasoningSeen = true; thinking = append(thinking, stringField(part, 'text'));
+      signature = stringField(field(field(part, 'metadata'), 'anthropic'), 'signature') ?? signature;
+    } else if (kind === 'tool') {
+      const id = stringField(part, 'callID') ?? '', name = stringField(part, 'tool') ?? '', state = field(part, 'state'), status = stringField(state, 'status');
+      if (id === '' || !['pending', 'running', 'completed', 'error'].includes(status)) continue;
+      calls.push(functionCall(id, name, field(state, 'input') === undefined ? '{}' : stringifyNativeJsonMember(state, 'input')));
+      if (status === 'completed' || status === 'error') results.push({ id, name, part, state, status });
+    }
+  }
+  const message = createMessage('assistant', nativeTrim(text) === '' ? null : text);
+  message.tool_calls = calls.length ? calls : null;
+  if (message.content == null && !calls.length && !reasoningSeen) message.metadata.empty_assistant_record = 'true';
+  if (reasoningSeen) message.metadata.thinking = thinking;
+  if (signature != null) message.metadata.thinking_signature = signature;
+  const id = stringField(value, 'id'), agent = stringField(value, 'agent'), provider = stringField(value, 'providerID'), model = stringField(value, 'modelID');
+  if (id != null) message.metadata.oc_message_id = id;
+  if (agent != null) { message.metadata.agent = agent; session.meta.agent_id ??= agent; }
+  if (provider != null && model != null) { message.metadata.model = `${provider}/${model}`; session.meta.model ??= message.metadata.model; }
+  session.meta.cwd ??= stringField(field(value, 'path'), 'cwd');
+  if (field(value, 'summary') === true) message.metadata.is_summary = 'true';
+  for (const key of ['finish', 'variant', 'mode']) { const text = stringField(value, key); if (text != null) message.metadata[key] = text; }
+  for (const key of ['cost', 'tokens', 'error', 'structured']) retainJson(value, message, key);
+  for (const part of parts) if (stringField(part, 'type') === 'tool' && stringField(part, 'tool') === 'task') {
+    const call = stringField(part, 'callID'), child = stringField(field(part, 'metadata'), 'sessionId');
+    if (call != null && child != null) message.metadata[`oc_task_child_session_id__${call}`] = child;
+  }
+  timestamp(value, message); restoreGrokMessageExtension(value, message); session.messages.push(message);
+  for (const { id, name, part, state, status } of results) {
+    const compacted = nativeInteger(field(state, 'time'), 'compacted', { signed: true }), output = stringField(state, 'output') ?? '';
+    const content = status === 'error' ? stringField(state, 'error') ?? '' : compacted != null ? OPENCODE_COMPACTED_TOOL_PLACEHOLDER : output;
+    const tool = createMessage('tool', content); tool.tool_call_id = id; tool.name = name;
+    const position = nativeInteger(part, '_supercode_result_position');
+    if (position != null) tool.metadata[OPENCODE_ORIGINAL_POSITION] = String(position);
+    if (status === 'error') markToolError(tool);
+    if (!isToolError(tool) && stringField(part, '_supercode_tool_outcome') === 'unknown') markToolOutcomeUnknown(tool);
+    if (compacted != null) { tool.metadata.oc_tool_output_compacted = output; tool.metadata.oc_tool_time_compacted = String(compacted); }
+    if (status === 'completed') {
+      const images = partsOf(field(state, 'attachments')).map(opencodeImagePart).filter((image) => image != null);
+      if (images.length) tool.content_parts = [...(content === '' ? [] : [{ type: 'text', text: content }]), ...images];
+    }
+    const partId = stringField(part, 'id'); if (partId != null) tool.metadata.oc_part_id = partId;
+    const time = field(state, 'time'), clock = field(time, 'end') === undefined ? 'start' : 'end';
+    const ms = nativeInteger(time, clock, { signed: true }); if (ms != null) tool.metadata.timestamp = messageMilliseconds(ms);
+    restoreGrokMessageExtension(part, tool); session.messages.push(tool);
+  }
+}

package/session-opencode-store.mjs

@@ -0,0 +1,101 @@
+import { dirname, join } from 'node:path';
+import { readStore, statement, tableColumns, text, integer } from './sqlite-reader.mjs';
+import { sourceStat } from './store-registry.mjs';
+import { optionalFile, verifySources } from './source-files.mjs';
+import { decodeSessionUtf8 } from './session-file.mjs';
+import { parseNativeJson, setNativeInteger, setNativeFloat } from './native-json.mjs';
+import { isObject, stringField } from './session-codec-utils.mjs';
+import { fromOpenCodeStr, opencodeEnvelope } from './session-opencode.mjs';
+
+function diagnostic(options, detail) {
+  if (options.onDiagnostic) options.onDiagnostic(detail);
+  else process.emitWarning(`${detail.message}: ${detail.context ?? detail.path} (${detail.column ?? 'session_diff'}): ${detail.error}`, { code: 'SUPERCODE_OPENCODE_JSON' });
+}
+function jsonColumn(value, column, context, options) {
+  const source = text(value, true); if (source == null) return null;
+  try { return parseNativeJson(source); }
+  catch (error) { diagnostic(options, { message: 'opencode SQLite column failed to parse as JSON — treating as absent', column, context, error: error.message }); return null; }
+}
+const stamp = (value, key, number) => { if (number == null) value[key] = null; else setNativeInteger(value, key, number); };
+
+function sessionInfo(db, id, options) {
+  const columns = tableColumns(db, 'session'), row = statement(db, 'SELECT * FROM session WHERE id=?').get(id);
+  if (!row) throw new Error(`OpenCode session \`${id}\` not found in this SQLite store`);
+  for (const key of ['id', 'project_id', 'parent_id', 'slug', 'directory', 'title', 'version', 'share_url', 'summary_additions', 'summary_deletions', 'summary_files', 'summary_diffs', 'revert', 'time_created', 'time_updated']) {
+    if (!columns.has(key)) throw new Error(`OpenCode session table has no required native column ${key}`);
+  }
+  const optional = (key) => columns.has(key) ? row[key] : null;
+  const additions = integer(row.summary_additions, true), deletions = integer(row.summary_deletions, true), files = integer(row.summary_files, true);
+  const diff = text(row.summary_diffs, true), share = text(row.share_url, true);
+  const summary = additions != null || deletions != null || files != null ? { additions: 0, deletions: 0, files: 0, diffs: jsonColumn(diff, 'summary_diffs', id, options) } : null;
+  if (summary) { stamp(summary, 'additions', additions ?? 0n); stamp(summary, 'deletions', deletions ?? 0n); stamp(summary, 'files', files ?? 0n); }
+  const tokens = { input: 0, output: 0, reasoning: 0, cache: { read: 0, write: 0 } };
+  for (const key of ['input', 'output', 'reasoning']) stamp(tokens, key, columns.has(`tokens_${key}`) ? integer(row[`tokens_${key}`]) : 0n);
+  for (const key of ['read', 'write']) stamp(tokens.cache, key, columns.has(`tokens_cache_${key}`) ? integer(row[`tokens_cache_${key}`]) : 0n);
+  const time = { created: 0, updated: 0, compacting: null, archived: null };
+  stamp(time, 'created', integer(row.time_created)); stamp(time, 'updated', integer(row.time_updated));
+  stamp(time, 'compacting', integer(optional('time_compacting'), true)); stamp(time, 'archived', integer(optional('time_archived'), true));
+  const cost = columns.has('cost') ? row.cost : 0;
+  if (typeof cost !== 'number' && typeof cost !== 'bigint') throw new Error('OpenCode returned a non-numeric cost column');
+  const info = {
+    id: text(row.id), slug: text(row.slug), projectID: text(row.project_id), workspaceID: text(optional('workspace_id'), true),
+    directory: text(row.directory), path: text(optional('path'), true), parentID: text(row.parent_id, true), summary, cost: 0, tokens,
+    share: share == null ? null : { url: share }, title: text(row.title), agent: text(optional('agent'), true),
+    model: jsonColumn(optional('model'), 'model', id, options), version: text(row.version), metadata: jsonColumn(optional('metadata'), 'metadata', id, options),
+    time, permission: jsonColumn(optional('permission'), 'permission', id, options), revert: jsonColumn(row.revert, 'revert', id, options),
+  };
+  setNativeFloat(info, 'cost', Number(cost)); return info;
+}
+
+function nativeRow(row, sessionId, messageId, options) {
+  const id = text(row.id), value = jsonColumn(text(row.data), messageId == null ? 'message.data' : 'part.data', id, options);
+  // A malformed/non-object data column remains diagnostically absent, as native.
+  if (isObject(value)) {
+    value.id = id; value.sessionID = sessionId;
+    if (messageId != null) value.messageID = messageId;
+    stamp(value, 'time_created', integer(row.time_created)); stamp(value, 'time_updated', integer(row.time_updated));
+  } else { integer(row.time_created); integer(row.time_updated); }
+  return value;
+}
+
+function envelopeLines(db, sessionId, options) {
+  const info = sessionInfo(db, sessionId, options), lines = [opencodeEnvelope(['session', stringField(info, 'projectID') ?? 'global', sessionId], info)];
+  const messages = statement(db, 'SELECT id, data, time_created, time_updated FROM message WHERE session_id=? ORDER BY time_created,id');
+  const parts = statement(db, 'SELECT id, data, time_created, time_updated FROM part WHERE message_id=? ORDER BY id');
+  for (const row of messages.iterate(sessionId)) {
+    const id = text(row.id); lines.push(opencodeEnvelope(['message', sessionId, id], nativeRow(row, sessionId, null, options)));
+    for (const part of parts.iterate(id)) lines.push(opencodeEnvelope(['part', id, text(part.id)], nativeRow(part, sessionId, id, options)));
+  }
+  for (const row of statement(db, 'SELECT content,status,priority,position,time_created,time_updated FROM todo WHERE session_id=? ORDER BY position').iterate(sessionId)) {
+    const value = { sessionID: sessionId, content: text(row.content), status: text(row.status), priority: text(row.priority), position: 0, time: { created: 0, updated: 0 } };
+    const position = integer(row.position); stamp(value, 'position', position);
+    stamp(value.time, 'created', integer(row.time_created)); stamp(value.time, 'updated', integer(row.time_updated));
+    const key = ['todo', sessionId, 0]; setNativeInteger(key, 2, position); lines.push(opencodeEnvelope(key, value));
+  }
+  return lines;
+}
+
+/** Reconstructs every native SQL field inside a read-only DB/WAL snapshot.
+ * The external revert sidecar and the database are verified together. */
+export async function readOpenCodeSqlite(path, sessionId = null, options = {}) {
+  if (sessionId != null && typeof sessionId !== 'string') throw new TypeError('OpenCode session selector must be a string');
+  if (!(await sourceStat(path))?.isFile()) throw new Error(`OpenCode SQLite store not found at ${path} — expected an \`opencode*.db\` file`);
+  const captured = await readStore(path, (db) => {
+    if (!statement(db, "SELECT count(*) AS count FROM sqlite_master WHERE type='table' AND name='session'").get().count) throw new Error(`${path} is a SQLite database but has no \`session\` table — not a recognized OpenCode store`);
+    const id = sessionId ?? (() => {
+      const row = statement(db, 'SELECT id FROM session ORDER BY (parent_id IS NULL) DESC,time_updated DESC LIMIT 1').get();
+      if (!row) throw new Error('OpenCode SQLite store contains no sessions'); return text(row.id);
+    })();
+    return { id, lines: envelopeLines(db, id, options) };
+  }, options.metrics);
+  const { id, lines } = captured.result, sidecarPath = join(dirname(path), 'storage', 'session_diff', `${id}.json`);
+  const sidecar = await optionalFile(sidecarPath, async (reader) => {
+    const source = decodeSessionUtf8(await reader.read(0, reader.size));
+    try { return { parsed: true, value: parseNativeJson(source) }; }
+    catch (error) { diagnostic(options, { message: 'opencode session_diff sidecar failed to parse as JSON — skipping', path: sidecarPath, error: error.message }); return { parsed: false }; }
+  }, options.metrics);
+  if (sidecar.result?.parsed) lines.push(opencodeEnvelope(['session_diff', id], sidecar.result.value));
+  const sources = [...captured.sources, sidecar]; await verifySources(sources);
+  const session = fromOpenCodeStr(`${lines.join('\n')}\n`); session.raw_is_verbatim = false;
+  return { result: session, sources };
+}