@volter/supercode-interchange 0.1.1 → 0.1.3

package/session-claude-index.mjs

@@ -0,0 +1,173 @@
+import { withSessionFile } from './file-io.mjs';
+import { sessionFileLines, decodeSessionUtf8 } from './session-file.mjs';
+import { parseNativeJson, cloneNativeJson } from './native-json.mjs';
+import { createSession } from './session-model.mjs';
+import { messageHasContent } from './session-views.mjs';
+import { nativeTrim } from './text.mjs';
+import { field, stringField, ensureToolResultsPaired } from './session-codec-utils.mjs';
+import { captureNativeResidue, claudeResidueKind } from './session-native-residue.mjs';
+import { captureClaudeMeta } from './session-claude.mjs';
+import { ClaudeReplayIndex } from './session-claude-graph.mjs';
+import { captureClaudeProvenance, pushClaudeUser, pushClaudeAttachment, pushClaudeSystem, mergeClaudeAssistantChunk, flushClaudeAssistant, reorderClaudeToolResults } from './session-claude-content.mjs';
+import { sourceStat } from './store-registry.mjs';
+import { looksLikeSessionSqlite } from './session-path.mjs';
+import { detectSessionSource } from './session-source.mjs';
+
+const REFERENCE = 'supercode.internal.read_index';
+
+export async function supportsClaudeReadIndex(path, { metrics } = {}) {
+  if (!(await sourceStat(path))?.isFile() || await looksLikeSessionSqlite(path, metrics)) return false;
+  return (await withSessionFile(path, async (reader) => {
+    for await (const line of sessionFileLines(reader)) {
+      const source = detectSessionSource(line.text);
+      if (source != null) return source === 'claude_code';
+    }
+    return false;
+  }, metrics)).result;
+}
+
+class ClaudeReadIndex {
+  #reader;
+  #records = [];
+  #groups = [];
+  #skeleton = [];
+  #meta = createSession('claude_code').meta;
+  #parseErrors = 0;
+  #residue = [];
+
+  constructor(reader) { this.#reader = reader; }
+  get length() { return this.#skeleton.length; }
+  get rawRecordCount() { return this.#records.length; }
+
+  async open(fidelity) {
+    const graph = new ClaudeReplayIndex(), residueRecords = [];
+    for await (const line of sessionFileLines(this.#reader)) {
+      const index = this.#records.length;
+      const record = { offset: line.offset, length: line.length, assistant: false, error: false, messageId: null };
+      if (nativeTrim(line.text) !== '') {
+        let value;
+        try { value = parseNativeJson(line.text); } catch { this.#parseErrors++; }
+        if (value !== undefined) {
+          captureClaudeMeta(value, this.#meta, line.text.endsWith('\n') ? line.text.slice(0, -1) : line.text);
+          graph.observe(index, value);
+          record.assistant = stringField(value, 'type') === 'assistant';
+          record.error = field(value, 'isApiErrorMessage') === true;
+          record.messageId = stringField(field(value, 'message'), 'id');
+          if (claudeResidueKind(value) != null) residueRecords.push(index);
+        }
+      }
+      this.#records.push(record);
+    }
+    const selection = graph.selectLines(fidelity); this.#residue = selection.residue;
+    for (const index of residueRecords) {
+      const text = await this.#raw(index), raw = text.endsWith('\n') ? text.slice(0, -1) : text;
+      const value = parseNativeJson(raw);
+      captureNativeResidue(this.#meta, 'claude_code', index, raw, value, claudeResidueKind(value));
+    }
+    let pending = [], pendingId = null;
+    for (const index of selection.lines) {
+      const record = this.#records[index];
+      if (record.assistant && !record.error) {
+        if (pending.length && !(pendingId != null && pendingId === record.messageId)) { await this.#addGroup(pending); pending = []; }
+        pendingId = record.messageId; pending.push(index);
+      } else {
+        await this.#addGroup(pending); pending = []; pendingId = null;
+        if (!record.error || !record.assistant) await this.#addGroup([index]);
+      }
+    }
+    await this.#addGroup(pending);
+    reorderClaudeToolResults(this.#skeleton); ensureToolResultsPaired(this.#skeleton);
+  }
+
+  async #raw(index) {
+    const record = this.#records[index];
+    return decodeSessionUtf8(await this.#reader.read(record.offset, record.length));
+  }
+
+  async #decodeGroup(group) {
+    const messages = []; let pending = null;
+    for (const index of group) {
+      const value = parseNativeJson(await this.#raw(index)), kind = stringField(value, 'type');
+      if (kind === 'assistant') {
+        if (pending == null) pending = value; else mergeClaudeAssistantChunk(pending, value);
+      } else {
+        const before = messages.length;
+        if (kind === 'user') pushClaudeUser(value, messages);
+        else if (kind === 'attachment') pushClaudeAttachment(value, messages);
+        else if (kind === 'system') pushClaudeSystem(value, messages);
+        captureClaudeProvenance(value, messages, before);
+      }
+    }
+    flushClaudeAssistant(pending, messages);
+    return messages;
+  }
+
+  async #addGroup(group) {
+    if (!group.length) return;
+    const groupId = this.#groups.length, decoded = await this.#decodeGroup(group);
+    this.#groups.push(group);
+    decoded.forEach((message, ordinal) => {
+      if (message.content != null) message.content = nativeTrim(message.content) === '' ? '' : 'x';
+      if (message.content_parts != null) message.content_parts = message.content_parts.length ? [null] : [];
+      for (const call of message.tool_calls ?? []) call.function.arguments = '';
+      message.metadata = Object.create(null); message.metadata[REFERENCE] = `${groupId}:${ordinal}`;
+      this.#skeleton.push(message);
+    });
+  }
+
+  itemCount(from, end) {
+    if (!Number.isSafeInteger(from) || !Number.isSafeInteger(end) || from < 0 || end < from || end > this.length) throw new RangeError('invalid Claude message range');
+    let count = 0;
+    for (let index = from; index < end; index++) {
+      const message = this.#skeleton[index];
+      count += (['user', 'assistant', 'tool'].includes(message.role) && messageHasContent(message) ? 1 : 0) + (message.tool_calls?.length ?? 0);
+    }
+    return count;
+  }
+
+  async readMessages(indices) {
+    const session = createSession('claude_code'); session.meta = cloneNativeJson(this.#meta);
+    let cachedId = null, cached = null;
+    for (const index of indices) {
+      if (!Number.isSafeInteger(index) || index < 0 || index >= this.length) throw new RangeError('invalid Claude message position');
+      const message = this.#skeleton[index], reference = message.metadata[REFERENCE];
+      if (reference === undefined) session.messages.push(cloneNativeJson(message));
+      else {
+        const [group, ordinal] = reference.split(':').map(Number);
+        if (cachedId !== group) { cached = await this.#decodeGroup(this.#groups[group]); cachedId = group; }
+        session.messages.push(cloneNativeJson(cached[ordinal]));
+      }
+    }
+    session.imported_message_count = this.length; session.raw_trailing_newline = false;
+    session.parse_error_lines = this.#parseErrors; session.load_residue = [...this.#residue];
+    return session;
+  }
+
+  async readSummary() {
+    const indices = new Set();
+    for (const assistantOnly of [false, true]) {
+      let first = null, last = null;
+      this.#skeleton.forEach((message, index) => {
+        if ((message.role === 'assistant' || (!assistantOnly && message.role === 'user')) && messageHasContent(message)) {
+          first ??= index; last = index;
+        }
+      });
+      if (first != null) indices.add(first);
+      if (last != null) indices.add(last);
+    }
+    const latest = this.#skeleton.findLastIndex((message) => message.role !== 'system');
+    if (latest !== -1) indices.add(latest);
+    return this.readMessages([...indices].sort((a, b) => a - b));
+  }
+}
+
+/** The index and its file handle live only inside this callback. Payloads
+ * are decoded one assistant group at a time. Handle and path fingerprints
+ * are verified before the result leaves the scope; any change refuses it. */
+export async function withClaudeReadIndex(path, work, { fidelity = 'byte_lossless', metrics } = {}) {
+  if (!['byte_lossless', 'value_lossless', 'semantic'].includes(fidelity)) throw new TypeError(`unknown session fidelity: ${fidelity}`);
+  return withSessionFile(path, async (reader) => {
+    const index = new ClaudeReadIndex(reader); await index.open(fidelity);
+    return work(index);
+  }, metrics);
+}

package/session-claude.mjs

@@ -0,0 +1,73 @@
+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, ensureToolResultsPaired } from './session-codec-utils.mjs';
+import { restoreTopLevelResidue, captureNativeResidue, claudeResidueKind } from './session-native-residue.mjs';
+import { ClaudeReplayIndex } from './session-claude-graph.mjs';
+import { captureClaudeProvenance, pushClaudeUser, pushClaudeAssistant, pushClaudeAttachment, pushClaudeSystem, mergeClaudeAssistantChunk, flushClaudeAssistant, reorderClaudeToolResults } from './session-claude-content.mjs';
+
+export function captureClaudeMeta(value, meta, rawLine) {
+  restoreTopLevelResidue(value, meta);
+  meta.session_id ??= stringField(value, 'sessionId');
+  meta.cwd ??= stringField(value, 'cwd');
+  meta.model ??= stringField(field(value, 'message'), 'model');
+  if (stringField(value, 'type') === 'fork-context-ref' && !Object.hasOwn(meta.lineage, 'claude_fork_context_ref_raw')) meta.lineage.claude_fork_context_ref_raw = rawLine;
+}
+
+/** Full native transcript is retained verbatim. Only the graph-selected
+ * replay branch becomes messages; semantic degradation is named separately. */
+export function fromClaudeCodeStr(text, { fidelity = 'byte_lossless' } = {}) {
+  if (!['byte_lossless', 'value_lossless', 'semantic'].includes(fidelity)) throw new TypeError(`unknown session fidelity: ${fidelity}`);
+  const session = createSession('claude_code'), { meta, messages } = session, capture = splitLinesVerbatim(text);
+  session.raw = capture.lines; session.raw_trailing_newline = capture.trailingNewline; session.raw_is_verbatim = true;
+  const graph = new ClaudeReplayIndex(), residueLines = [];
+  capture.lines.forEach((line, index) => {
+    if (nativeTrim(line) === '') return;
+    let value;
+    try { value = parseNativeJson(line); } catch { session.parse_error_lines++; return; }
+    captureClaudeMeta(value, meta, line);
+    graph.observe(index, value);
+    if (claudeResidueKind(value) != null) residueLines.push(index);
+  });
+  const selection = graph.selectLines(fidelity);
+  session.load_residue = selection.residue;
+  for (const index of residueLines) {
+    const value = parseNativeJson(capture.lines[index]);
+    captureNativeResidue(meta, 'claude_code', index, capture.lines[index], value, claudeResidueKind(value));
+  }
+  let pending = null;
+  for (const index of selection.lines) {
+    const value = parseNativeJson(capture.lines[index]), kind = stringField(value, 'type');
+    if (kind === 'assistant') {
+      if (field(value, 'isApiErrorMessage') === true) { flushClaudeAssistant(pending, messages); pending = null; continue; }
+      if (pending != null) {
+        const messageId = stringField(field(pending, 'message'), 'id');
+        if (messageId != null && stringField(field(value, 'message'), 'id') === messageId) { mergeClaudeAssistantChunk(pending, value); continue; }
+        flushClaudeAssistant(pending, messages);
+      }
+      pending = value; continue;
+    }
+    flushClaudeAssistant(pending, messages); pending = null;
+    const before = messages.length;
+    if (kind === 'user') pushClaudeUser(value, messages);
+    else if (kind === 'assistant') pushClaudeAssistant(value, messages);
+    else if (kind === 'attachment') pushClaudeAttachment(value, messages);
+    else if (kind === 'system') pushClaudeSystem(value, messages);
+    captureClaudeProvenance(value, messages, before);
+  }
+  flushClaudeAssistant(pending, messages);
+  reorderClaudeToolResults(messages); ensureToolResultsPaired(messages);
+  // Keep the native creating-record lookup: compact literal UUID spelling,
+  // last raw occurrence wins, and synthetic results have no source record.
+  const records = new Map();
+  capture.lines.forEach((line, index) => {
+    const marker = line.indexOf('"uuid":"');
+    if (marker === -1) return;
+    const from = marker + 8, end = line.indexOf('"', from);
+    if (end !== -1) records.set(line.slice(from, end), index);
+  });
+  meta.message_records = messages.map((message) => records.get(message.metadata.claude_uuid) ?? null);
+  session.imported_message_count = messages.length;
+  return session;
+}

package/session-codec-utils.mjs

@@ -0,0 +1,115 @@
+import { createMessage, deserializeMessage, markToolError, ROLES } from './message.mjs';
+import { cloneNativeJson, nativeInteger, nativeObjectKeys, stringifyNativeJsonMember } from './native-json.mjs';
+
+export const isObject = (value) => value != null && typeof value === 'object' && !Array.isArray(value);
+export const field = (value, key) => isObject(value) && Object.hasOwn(value, key) ? value[key] : undefined;
+export const stringField = (value, key) => typeof field(value, key) === 'string' ? value[key] : null;
+export function valueString(value, key) { return typeof value[key] === 'string' ? value[key] : stringifyNativeJsonMember(value, key); }
+export const functionCall = (id, name, args) => ({ id, type: 'function', function: { name, arguments: args } });
+export function toolMessage(id, content) { const result = createMessage('tool', content); result.tool_call_id = id; return result; }
+
+export function extractTextContent(value, key) {
+  const content = field(value, key);
+  if (content === undefined) return '';
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) return content.map((part) => typeof part === 'string' ? part : stringField(part, 'text')).filter((part) => part != null).join('\n');
+  return stringifyNativeJsonMember(value, key);
+}
+
+/** Native loaders retain unanswered calls and stamp the existing structured
+ * interrupted outcome; they never manufacture a successful tool receipt. */
+export function ensureToolResultsPaired(messages) {
+  const answered = new Set(messages.filter((message) => message.role === 'tool' && message.tool_call_id != null).map((message) => message.tool_call_id));
+  if (!messages.some((message) => (message.tool_calls ?? []).some((call) => call.id !== '' && !answered.has(call.id)))) return;
+  const result = [];
+  for (const message of messages) {
+    result.push(message);
+    for (const call of message.tool_calls ?? []) {
+      if (call.id === '' || answered.has(call.id)) continue;
+      const missing = toolMessage(call.id, '[no tool result recorded — turn interrupted]');
+      missing.name = call.function.name;
+      markToolError(missing);
+      result.push(missing);
+    }
+  }
+  messages.length = 0;
+  for (const message of result) messages.push(message);
+}
+
+const recordKey = '__supercode_record';
+export function stampMessageRecords(messages, record) {
+  for (let index = messages.length - 1; index >= 0; index--) {
+    if (Object.hasOwn(messages[index].metadata, recordKey)) break;
+    messages[index].metadata[recordKey] = String(record);
+  }
+}
+export function takeMessageRecords(messages) {
+  return messages.map((message) => {
+    const value = message.metadata[recordKey];
+    delete message.metadata[recordKey];
+    if (typeof value !== 'string' || !/^\+?\d+$/.test(value)) return null;
+    const record = BigInt(value);
+    if (record > 18446744073709551615n) return null;
+    return record <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(record) : record;
+  });
+}
+
+/** A display tail keeps up to two human boundaries from before the numeric
+ * window. This is a bounded view, never the input to a continuation writer. */
+export function truncateMessagesWithAnchor(messages, messageLimit, precedingUsers = []) {
+  const limit = Math.max(1, messageLimit), rawTail = Math.max(0, messages.length - limit);
+  const anchorLimit = messages.length < limit ? Math.min(limit - messages.length, 2) : Math.min(limit, 2);
+  const candidates = [...precedingUsers];
+  for (let index = 0; index < rawTail; index++) if (messages[index].role === 'user') candidates.push(messages[index]);
+  const anchors = candidates.slice(Math.max(0, candidates.length - anchorLimit)).map(cloneNativeJson);
+  if (messages.length <= limit && !anchors.length) return;
+  const tailCount = Math.min(Math.max(0, limit - anchors.length), messages.length), tail = messages.slice(messages.length - tailCount);
+  messages.length = 0;
+  for (const message of anchors) messages.push(message);
+  for (const message of tail) messages.push(message);
+}
+
+function restoreFields(extension, message, { calls }) {
+  const role = field(extension, 'role');
+  if (ROLES.includes(role)) message.role = role;
+  message.content = stringField(extension, 'content');
+  const parts = field(extension, 'content_parts');
+  message.content_parts = Array.isArray(parts) ? cloneNativeJson(parts) : null;
+  if (calls) {
+    try { message.tool_calls = deserializeMessage({ role: message.role, tool_calls: field(extension, 'tool_calls') }).tool_calls; }
+    catch { message.tool_calls = null; }
+  }
+  message.tool_call_id = stringField(extension, 'tool_call_id');
+  message.name = stringField(extension, 'name');
+  message.metadata = Object.create(null);
+}
+function restoreMetadata(extension, message) {
+  const metadata = field(extension, 'metadata');
+  if (!isObject(metadata)) return;
+  for (const key of nativeObjectKeys(metadata)) {
+    if (typeof metadata[key] === 'string') message.metadata[key] = metadata[key];
+  }
+}
+
+export function restoreGeminiMessageExtension(value, message) {
+  const extension = field(value, '_supercode_gemini_message');
+  if (nativeInteger(extension, 'schema') !== 1n) return;
+  restoreFields(extension, message, { calls: true });
+  restoreMetadata(extension, message);
+}
+
+export function restoreGrokMessageExtension(value, message) {
+  const extension = field(value, '_supercode_grok_message');
+  if (extension === undefined) return;
+  const openTurn = message.metadata.__codex_open_turn, turnId = message.metadata.turn_id;
+  const extensionHasTurn = isObject(field(extension, 'metadata')) && Object.hasOwn(extension.metadata, 'turn_id');
+  if (nativeInteger(extension, 'schema') === 2n) restoreFields(extension, message, { calls: false });
+  restoreMetadata(extension, message);
+  const name = stringField(extension, 'name');
+  if (name != null) message.name = name;
+  if (openTurn !== undefined) message.metadata.__codex_open_turn = openTurn;
+  if (turnId !== undefined) {
+    message.metadata.turn_id = turnId;
+    if (!extensionHasTurn) message.metadata.__grok_remove_synthetic_turn_id = 'true';
+  }
+}

package/session-codecs.d.ts

@@ -0,0 +1,64 @@
+import type { Session, ChatMessage, SessionSource } from './session-model.js';
+import type { IndexMetrics, StoreRead } from './index.js';
+export interface ReadLocator { harness: string; session_id: string; storage: { kind: 'file'; path: string } | { kind: 'sqlite'; path: string; selector: string } }
+export interface SessionReadOptions { fidelity?: 'byte_lossless' | 'value_lossless' | 'semantic'; includeSubagents?: boolean; metrics?: IndexMetrics; env?: Record<string, string | undefined> }
+export interface SessionFollowOptions extends SessionReadOptions { messageLimit?: number | null; maxMessageChars?: number | null; displayHistory?: boolean; selector?: string | null; store?: 'opencode' | 'goose' | 'hermes' }
+/** Passive polling only: no timer, process control, or inferred activity. */
+export class SessionFollower {
+  static open(path: string, options?: SessionFollowOptions): Promise<SessionFollower>;
+  static openLocator(locator: ReadLocator, options?: SessionFollowOptions): Promise<SessionFollower>;
+  poll(): Promise<Record<string, unknown> | null>;
+  close(): void;
+}
+export interface SessionFileRead<T> {
+  result: T;
+  fingerprint: { device: string; inode: string; size: string; mtime_ns: string };
+  size: number;
+  modified_ms: number | null;
+}
+/** Pure document readers. They retain raw source text and native extensions;
+ * these are not service entrypoints or format-auto-detection fallbacks. */
+export function fromGeminiStr(text: string): Session;
+export function fromGooseStr(text: string): Session;
+/** Grok's document view; directory/summary overlays belong to the path reader. */
+export function fromGrokStr(text: string): Session;
+/** Strict graph reconstruction by default; semantic views name degradation. */
+export function fromClaudeCodeStr(text: string, options?: { fidelity?: 'byte_lossless' | 'value_lossless' | 'semantic' }): Session;
+/** Attaches native subagent files, preserving strict versus semantic refusal. */
+export function readClaudeCodeFile(path: string, options?: { fidelity?: 'byte_lossless' | 'value_lossless' | 'semantic'; metrics?: IndexMetrics }): Promise<SessionFileRead<Session>>;
+export interface ClaudeReadIndex {
+  readonly length: number;
+  readonly rawRecordCount: number;
+  itemCount(from: number, end: number): number;
+  readMessages(indices: Iterable<number>): Promise<Session>;
+  readSummary(): Promise<Session>;
+}
+export function supportsClaudeReadIndex(path: string, options?: { metrics?: IndexMetrics }): Promise<boolean>;
+/** The index is valid only during the callback; no source file handle escapes. */
+export function withClaudeReadIndex<T>(path: string, work: (index: ClaudeReadIndex) => T | Promise<T>, options?: { fidelity?: 'byte_lossless' | 'value_lossless' | 'semantic'; metrics?: IndexMetrics }): Promise<SessionFileRead<T>>;
+/** Resumable model context, including compaction replacement by default. */
+export function fromCodexStr(text: string, options?: { applyCompaction?: boolean }): Session;
+/** Typed human-visible history; bounded display values cannot be exported. */
+export function fromCodexDisplayStr(text: string, messageLimit: number): Session;
+export function fromPiStr(text: string): Session;
+/** Read-only dialect: leaf redirects, side appends and inert vendor metadata. */
+export function fromOpenClawStr(text: string): Session;
+/** Envelope JSONL or the native export document; synthesized raw is named. */
+export function fromOpenCodeStr(text: string): Session;
+export function resolveOpenCodeParentToolUseIds(sessions: Session[]): void;
+export function readOpenCodeSqlite(path: string, sessionId?: string | null, options?: { metrics?: IndexMetrics; onDiagnostic?: (detail: { message: string; column?: string; context?: string; path?: string; error: string }) => void }): Promise<StoreRead<Session>>;
+export function detectSessionSource(text: string): SessionSource | null;
+export function fromNativeStr(text: string): Session;
+export function fromSidecarStr(text: string): Session;
+export function fromNativeMessages(messages: ChatMessage[]): Session;
+export function loadNativeStoreFamily(path: string, options?: SessionReadOptions): Promise<Session | null>;
+export function detectOpenCodeStorageSurface(root: string, options?: Pick<SessionReadOptions, 'env'>): Promise<{ kind: 'sqlite' | 'json_tree_a' | 'json_tree_b'; path: string } | null>;
+export function loadSessionPath(path: string, options?: SessionReadOptions): Promise<Session>;
+export function loadSessionLocator(locator: ReadLocator, options?: SessionReadOptions): Promise<Session>;
+export function loadSessionDisplayPath(path: string, messageLimit: number, options?: SessionReadOptions): Promise<Session>;
+export function loadSessionDisplayLocator(locator: ReadLocator, messageLimit: number, options?: SessionReadOptions): Promise<Session>;
+export function loadSessionDisplayFrom(locator: ReadLocator, fromByte: number, options?: SessionReadOptions): Promise<Session>;
+/** Verified read-only DB/WAL snapshot; a changed source refuses the read. */
+export function readGooseSqlite(path: string, sessionId: string, options?: { messageLimit?: number | null; metrics?: IndexMetrics }): Promise<StoreRead<Session>>;
+/** Active native rows form the replay view; all rows remain in raw. No write tier. */
+export function readHermesSqlite(path: string, sessionId?: string | null, options?: { metrics?: IndexMetrics }): Promise<StoreRead<Session>>;

package/session-codecs.mjs

@@ -0,0 +1,19 @@
+// Importable document/store readers and passive following, shared by the
+// caller-owned read service. There is no native parser fallback.
+export { fromGeminiStr } from './session-gemini.mjs';
+export { fromGooseStr, readGooseSqlite } from './session-goose.mjs';
+export { readHermesSqlite } from './session-hermes.mjs';
+export { fromGrokStr } from './session-grok.mjs';
+export { fromClaudeCodeStr } from './session-claude.mjs';
+export { readClaudeCodeFile } from './session-claude-files.mjs';
+export { withClaudeReadIndex, supportsClaudeReadIndex } from './session-claude-index.mjs';
+export { fromCodexStr } from './session-codex.mjs';
+export { fromCodexDisplayStr } from './session-codex-display.mjs';
+export { fromPiStr, fromOpenClawStr } from './session-pi.mjs';
+export { fromOpenCodeStr, resolveOpenCodeParentToolUseIds } from './session-opencode.mjs';
+export { readOpenCodeSqlite } from './session-opencode-store.mjs';
+export { fromNativeStr, fromSidecarStr, fromNativeMessages } from './session-native.mjs';
+export { detectSessionSource } from './session-source.mjs';
+export { loadSessionPath, loadSessionLocator, loadNativeStoreFamily, detectOpenCodeStorageSurface } from './session-path.mjs';
+export { loadSessionDisplayPath, loadSessionDisplayLocator, loadSessionDisplayFrom } from './session-display.mjs';
+export { SessionFollower } from './session-follower.mjs';

package/session-codex-context.mjs

@@ -0,0 +1,68 @@
+import { SaxesParser } from 'saxes';
+import { field, stringField } from './session-codec-utils.mjs';
+import { nativeTrim } from './text.mjs';
+
+const asciiLower = (value) => value.replace(/[A-Z]/g, (letter) => letter.toLowerCase());
+const markers = [
+  ['# AGENTS.md instructions', '</INSTRUCTIONS>'], ['<environment_context>', '</environment_context>'],
+  ['<agent_message_board_notification>', '</agent_message_board_notification>'], ['<skill>', '</skill>'],
+  ['<user_shell_command>', '</user_shell_command>'], ['<turn_aborted>', '</turn_aborted>'],
+  ['<subagent_notification>', '</subagent_notification>'], ['<recommended_plugins>', '</recommended_plugins>'],
+];
+
+function standardContext(raw) {
+  const text = nativeTrim(raw), folded = asciiLower(text);
+  if (markers.some(([first, last]) => folded.startsWith(asciiLower(first)) && folded.endsWith(asciiLower(last)))) return true;
+  if (text.startsWith('<external_')) {
+    const end = text.indexOf('>', 10);
+    if (end !== -1 && text.slice(end + 1).endsWith(`</external_${text.slice(10, end)}>`)) return true;
+  }
+  if (text.startsWith('<goal_context>') && text.endsWith('</goal_context>')) return true;
+  const internal = /^<codex_internal_context source="([a-z][a-z0-9_]*)">/.exec(text);
+  if (internal && text.endsWith('</codex_internal_context>')) return true;
+  return text.startsWith('Warning: The maximum number of unified exec processes you can keep open is')
+    || (text.startsWith('Warning: apply_patch was requested via ') && text.endsWith('Use the apply_patch tool instead of exec_command.'))
+    || text.startsWith('Warning: Your account was flagged for potentially high-risk cyber activity');
+}
+
+// quick_xml's struct deserializer consumes the first element, ignores its
+// name/unknown fields, and requires both @hook_run_id and $text. XML parsing
+// handles quoting, entities and CDATA; a prefix regex cannot establish this.
+function parseHook(raw) {
+  const parser = new SaxesParser(), complete = {}, segments = [];
+  let depth = 0, id = null, text = '', hasText = false;
+  const flush = () => { if (hasText) segments.push(text); text = ''; hasText = false; };
+  parser.on('opentag', (tag) => {
+    if (depth === 0) id = typeof tag.attributes.hook_run_id === 'string' ? tag.attributes.hook_run_id : null;
+    else if (depth === 1) flush();
+    depth++;
+  });
+  const take = (part) => { if (depth === 1) { text += part; hasText = true; } };
+  parser.on('text', take); parser.on('cdata', take);
+  parser.on('closetag', () => {
+    depth--;
+    if (depth === 0) { flush(); throw complete; }
+  });
+  try { parser.write(nativeTrim(raw)).close(); }
+  catch (error) { if (error !== complete) return null; }
+  return id != null && nativeTrim(id) !== '' && segments.length === 1 ? { text: segments[0], hook_run_id: id } : null;
+}
+
+/** The same classification serves full model metadata and display history.
+ * Typed native user events/items have already crossed this boundary. */
+export function codexUserContext(item) {
+  const content = field(item, 'content');
+  if (!Array.isArray(content)) return { kind: 'ordinary' };
+  let contextual = false, hooksOnly = true;
+  const hooks = [];
+  for (const part of content) {
+    const text = stringField(part, 'type') === 'input_text' ? stringField(part, 'text') : null;
+    if (text == null) { hooksOnly = false; continue; }
+    const hook = parseHook(text);
+    if (hook != null) { contextual = true; hooks.push(hook); }
+    else if (standardContext(text)) contextual = true;
+    else hooksOnly = false;
+  }
+  return hooksOnly && hooks.length ? { kind: 'hook_prompt', item: { type: 'HookPrompt', id: field(item, 'id') ?? null, fragments: hooks } }
+    : { kind: contextual ? 'hidden' : 'ordinary' };
+}

package/session-codex-display-items.mjs

@@ -0,0 +1,89 @@
+import { createMessage, markToolError } from './message.mjs';
+import { nativeInteger, parseNativeJson, stringifyNativeJson, stringifyNativeJsonMember } from './native-json.mjs';
+import { field, stringField, toolMessage, functionCall } from './session-codec-utils.mjs';
+import { pushCodexItem, pushCodexAssistant } from './session-codex-items.mjs';
+
+const asciiLower = (value) => value.replace(/[A-Z]/g, (letter) => letter.toLowerCase());
+const render = (value, key) => field(value, key) == null ? '' : typeof field(value, key) === 'string' ? value[key] : stringifyNativeJsonMember(value, key);
+const selectedJson = (value, keys) => `{${keys.map((key) => `${JSON.stringify(key)}:${field(value, key) === undefined ? 'null' : stringifyNativeJsonMember(value, key)}`).join(',')}}`;
+
+export function codexItemKind(item) {
+  const kind = asciiLower(stringField(item, 'type') ?? '');
+  if (kind !== 'extension') return kind;
+  const known = { 'image_gen.generation': 'imagegeneration', 'clock.sleep': 'sleep', 'web.search': 'websearch' };
+  const extension = stringField(item, 'kind');
+  return extension != null && Object.hasOwn(known, extension) ? known[extension] : 'extension';
+}
+
+function contentText(value, key) {
+  return contentValue(field(value, key), value, key);
+}
+
+function contentValue(content, parent, key) {
+  if (Array.isArray(content)) return content.map((part, index) => contentValue(part, content, String(index))).filter((text) => text !== '').join('\n');
+  if (content != null && typeof content === 'object') {
+    if (field(content, 'text') !== undefined) return contentText(content, 'text');
+    if (field(content, 'content') !== undefined) return contentText(content, 'content');
+  }
+  return content == null ? '' : typeof content === 'string' ? content : stringifyNativeJsonMember(parent, key);
+}
+
+export function codexContentItem(item) {
+  const kind = codexItemKind(item); let type = 'text_delta', text;
+  if (kind === 'agentmessage') text = field(item, 'text') === undefined ? contentText(item, 'content') : render(item, 'text');
+  else if (kind === 'reasoning') { type = 'reasoning'; text = contentText(item, field(item, 'summary') === undefined ? 'summary_text' : 'summary'); }
+  else if (kind === 'plan') { const body = render(item, 'text'); if (body === '') return null; text = `\n\n**Plan**\n\n${body}\n\n`; }
+  else if (kind === 'hookprompt') text = `\n\n**Hook context**\n\n${contentText(item, 'fragments')}\n\n`;
+  else if (kind === 'subagentactivity') text = `\n\n**Subagent activity** · ${render(item, field(item, 'agentPath') === undefined ? 'agent_path' : 'agentPath')} · ${render(item, 'kind')}\n\n`;
+  else if (kind === 'contextcompaction') text = '\n\n_Context compacted._\n\n';
+  else return null;
+  return text === '' ? null : { type, id: field(item, 'id') ?? null, text };
+}
+
+function commandOutput(item) {
+  const key = field(item, 'aggregatedOutput') === undefined ? 'aggregated_output' : 'aggregatedOutput';
+  const aggregate = field(item, key) != null;
+  let output = render(item, aggregate ? key : 'stdout');
+  const stderr = render(item, 'stderr');
+  if (stderr !== '' && (!aggregate || !output.includes(stderr))) output += stderr;
+  return output;
+}
+
+function toolItem(item) {
+  const id = stringField(item, 'id'); if (id == null) return null;
+  const kind = codexItemKind(item); let name, args, output;
+  if (kind === 'commandexecution') { name = 'Shell'; args = selectedJson(item, ['command', 'cwd']); output = commandOutput(item); }
+  else if (kind === 'filechange') { name = 'apply_patch'; args = selectedJson(item, ['changes']); output = field(item, 'stdout') !== undefined || field(item, 'stderr') !== undefined ? render(item, 'stdout') + render(item, 'stderr') : render(item, 'changes'); }
+  else if (kind === 'mcptoolcall') { name = `${render(item, 'server')} · ${render(item, 'tool')}`; args = field(item, 'arguments') === undefined ? 'null' : stringifyNativeJsonMember(item, 'arguments'); output = render(item, field(item, 'error') != null ? 'error' : 'result'); }
+  else if (kind === 'dynamictoolcall') { name = render(item, 'tool'); args = field(item, 'arguments') === undefined ? 'null' : stringifyNativeJsonMember(item, 'arguments'); output = render(item, field(item, 'contentItems') === undefined ? 'content_items' : 'contentItems'); }
+  else if (kind === 'collabagenttoolcall') { name = render(item, 'tool'); args = stringifyNativeJson(item); output = render(item, field(item, 'agentsStates') === undefined ? 'agents_states' : 'agentsStates'); }
+  else if (kind === 'websearch') { name = 'Web search'; args = selectedJson(item, ['query', 'action']); output = render(item, 'results'); }
+  else if (kind === 'imageview') { name = 'View image'; args = selectedJson(item, ['path']); output = ''; }
+  else if (kind === 'imagegeneration') { name = 'Generate image'; args = stringifyNativeJson(item); output = render(item, field(item, 'failure') != null ? 'failure' : 'result'); }
+  else return null;
+  const exitKey = field(item, 'exitCode') === undefined ? 'exit_code' : 'exitCode';
+  const exit = nativeInteger(item, exitKey, { signed: true });
+  const error = ['failed', 'declined', 'denied', 'error'].includes(asciiLower(render(item, 'status'))) || (exit != null && exit !== 0n) || field(item, 'error') != null || field(item, 'success') === false;
+  return { id, name, args, output, error };
+}
+
+export function pushCodexDisplayItem(item, out) {
+  if (codexItemKind(item) === 'usermessage') {
+    // Preserve parsed numeric facts in any source parts.
+    const content = field(item, 'content') === undefined ? 'null' : stringifyNativeJsonMember(item, 'content');
+    pushCodexItem(parseNativeJson(`{"type":"message","role":"user","content":${content}}`), out);
+    return;
+  }
+  const content = codexContentItem(item);
+  if (content != null) {
+    const message = createMessage('assistant', content.text);
+    if (content.type === 'reasoning') { message.content = null; message.content_parts = [{ type: 'reasoning', text: content.text }]; }
+    const phase = stringField(item, 'phase'); if (phase != null) message.metadata.phase = phase;
+    out.push(message); return;
+  }
+  const tool = toolItem(item); if (tool == null) return;
+  pushCodexAssistant(out, '', [functionCall(tool.id, tool.name, tool.args)]);
+  const message = toolMessage(tool.id, tool.output); message.name = tool.name;
+  if (tool.error) { markToolError(message); message.content = null; message.content_parts = [{ type: 'text', text: tool.output, is_error: true }]; }
+  out.push(message);
+}