@volter/supercode-interchange 0.1.1 → 0.1.2

package/session-codex-display.mjs

@@ -0,0 +1,81 @@
+import { createMessage } from './message.mjs';
+import { parseNativeJson } from './native-json.mjs';
+import { createSession } from './session-model.mjs';
+import { nonEmptyLines } from './session-lines.mjs';
+import { field, stringField, extractTextContent, restoreGrokMessageExtension, truncateMessagesWithAnchor } from './session-codec-utils.mjs';
+import { captureCodexMeta } from './session-codex.mjs';
+import { codexUserWithImages, pushCodexItem, pushCodexAssistant, stampCodexMessages, clearCodexBookkeeping } from './session-codex-items.mjs';
+import { codexUserContext } from './session-codex-context.mjs';
+import { pushCodexDisplayItem } from './session-codex-display-items.mjs';
+import { nativeTrim } from './text.mjs';
+
+/** Bounded human-visible history, never a continuation or export artifact.
+ * Durable TurnItems and legacy typed-user events retain their distinct paths. */
+export function fromCodexDisplayStr(text, messageLimit) {
+  if (!Number.isSafeInteger(messageLimit) || messageLimit < 0) throw new RangeError('invalid Codex display message limit');
+  const session = createSession('codex'), { meta, messages } = session, precedingUsers = [], canonicalTexts = new Set();
+  const retain = Math.min(Number.MAX_SAFE_INTEGER, Math.max(messageLimit, 1) + 64);
+  let paginated = false, recordCount = 0, total = 0;
+  for (const line of nonEmptyLines(text)) {
+    recordCount++;
+    let value; try { value = parseNativeJson(line); } catch { session.parse_error_lines++; continue; }
+    const kind = stringField(value, 'type'), payload = field(value, 'payload'), type = stringField(payload, 'type'), timestamp = stringField(value, 'timestamp');
+    if (kind === 'session_meta') { paginated = stringField(payload, 'history_mode') === 'paginated'; captureCodexMeta(payload, meta); }
+    else if (kind === 'event_msg' && paginated && type === 'item_completed') {
+      const item = field(payload, 'item'), id = stringField(item, 'id');
+      if (id != null) {
+        const position = messages.findIndex((message) => message.metadata.codex_display_item === id), projected = [];
+        pushCodexDisplayItem(item, projected);
+        for (const message of projected) message.metadata.codex_display_item = id;
+        stampCodexMessages(projected, 0, timestamp);
+        let removed = 0;
+        for (let index = messages.length - 1; index >= 0; index--) if (messages[index].metadata.codex_display_item === id) { messages.splice(index, 1); removed++; }
+        total = Math.max(0, total - removed) + projected.length;
+        const at = Math.min(position === -1 ? messages.length : position, messages.length);
+        for (let index = 0; index < projected.length; index++) messages.splice(at + index, 0, projected[index]);
+      }
+    } else if (['response_item', 'event_msg'].includes(kind) && paginated) { /* Model stream is separate from display history. */ }
+    else if (kind === 'turn_context' && meta.model == null) meta.model = stringField(payload, 'model');
+    else if (kind === 'event_msg' && type === 'user_message') {
+      const urls = [];
+      for (const key of ['images', 'local_images']) {
+        const images = field(payload, key); if (Array.isArray(images)) for (const image of images) if (typeof image === 'string') urls.push(image);
+      }
+      const text = stringField(payload, 'message') ?? '';
+      messages.push(urls.length ? codexUserWithImages(text, urls) : createMessage('user', text)); total++;
+    } else if (kind === 'response_item' && type !== 'reasoning') {
+      const isAssistant = type === 'message' && stringField(payload, 'role') === 'assistant';
+      const assistantText = isAssistant ? extractTextContent(payload, 'content') : null;
+      if (assistantText != null && nativeTrim(assistantText) !== '') {
+        const duplicate = messages.findLastIndex((message) => Object.hasOwn(message.metadata, 'codex_event_message') && message.content === assistantText);
+        if (duplicate !== -1) { messages.splice(duplicate, 1); total = Math.max(0, total - 1); }
+        canonicalTexts.add(nativeTrim(assistantText));
+      }
+      const before = messages.length;
+      if (type === 'message' && stringField(payload, 'role') === 'user') {
+        const context = codexUserContext(payload);
+        if (context.kind === 'hook_prompt') pushCodexDisplayItem(context.item, messages);
+      } else pushCodexItem(payload, messages);
+      total += Math.max(0, messages.length - before); stampCodexMessages(messages, before, timestamp);
+      if (messages.length === before + 1) restoreGrokMessageExtension(payload, messages[before]);
+    } else if (kind === 'event_msg' && type === 'agent_message') {
+      const text = extractTextContent(payload, 'message');
+      if (nativeTrim(text) !== '' && !canonicalTexts.has(nativeTrim(text))) {
+        const before = messages.length; pushCodexAssistant(messages, text); total++;
+        messages.at(-1).metadata.codex_event_message = 'true';
+        const phase = stringField(payload, 'phase'); if (phase != null) messages.at(-1).metadata.phase = phase;
+        stampCodexMessages(messages, before, timestamp);
+      }
+    }
+    if (messages.length > retain) {
+      for (const message of messages.splice(0, messages.length - retain)) {
+        if (message.role !== 'user') continue;
+        precedingUsers.push(message); if (precedingUsers.length > 2) precedingUsers.shift();
+      }
+    }
+  }
+  clearCodexBookkeeping(messages, { display: true }); truncateMessagesWithAnchor(messages, messageLimit, precedingUsers);
+  session.raw = Array(recordCount).fill(''); session.raw_trailing_newline = text.endsWith('\n'); session.imported_message_count = total;
+  session.load_residue = ['display history is a bounded native-record projection, not resumable model context'];
+  return session;
+}

package/session-codex-items.mjs

@@ -0,0 +1,117 @@
+import { createMessage, markToolOutcomeUnknown } from './message.mjs';
+import { cloneNativeJson, stringifyNativeJson, stringifyNativeJsonMember } from './native-json.mjs';
+import { field, stringField, extractTextContent, functionCall, toolMessage, valueString } from './session-codec-utils.mjs';
+import { codexUserContext } from './session-codex-context.mjs';
+import { nativeTrim } from './text.mjs';
+
+export const codexTurnId = (payload) => stringField(field(payload, 'metadata'), 'turn_id');
+export function codexImages(content) {
+  if (!Array.isArray(content)) return [];
+  const images = [];
+  for (const item of content) {
+    const url = stringField(item, 'image_url');
+    if (stringField(item, 'type') === 'input_image' && url != null && url !== '') images.push({ type: 'image_url', image_url: { url } });
+  }
+  return images;
+}
+
+export function codexUserWithImages(text, urls) {
+  const message = createMessage('user');
+  message.content_parts = [{ type: 'text', text }];
+  for (const url of urls) message.content_parts.push({ type: 'image_url', image_url: { url } });
+  return message;
+}
+
+export function pushCodexAssistant(out, text, calls = []) {
+  const hasText = nativeTrim(text) !== '';
+  if (!hasText && !calls.length) return;
+  const message = createMessage('assistant', hasText ? text : null); message.tool_calls = calls.length ? calls : null; out.push(message);
+}
+
+function mergeCall(payload, call, out) {
+  const last = out.at(-1), turn = codexTurnId(payload);
+  if (last?.role === 'assistant' && Object.hasOwn(last.metadata, '__codex_open_turn') && (turn == null || last.metadata.turn_id === turn)) {
+    last.tool_calls ??= []; last.tool_calls.push(call);
+  } else {
+    pushCodexAssistant(out, '', [call]);
+    if (turn != null) { out.at(-1).metadata.__codex_open_turn = 'true'; out.at(-1).metadata.turn_id = turn; }
+  }
+}
+
+export function pushCodexItem(payload, out) {
+  const kind = stringField(payload, 'type');
+  if (kind === 'local_shell_call') {
+    const id = field(payload, 'call_id') === undefined ? stringField(payload, 'id') : stringField(payload, 'call_id');
+    const action = cloneNativeJson(field(payload, 'action') ?? null);
+    if (action != null && typeof action === 'object' && !Array.isArray(action)) delete action.type;
+    pushCodexItem({ type: 'function_call', call_id: id ?? '', name: 'local_shell', arguments: stringifyNativeJson(action) }, out);
+  } else if (kind === 'message') {
+    const nativeRole = stringField(payload, 'role'), role = ['user', 'assistant'].includes(nativeRole) ? nativeRole : 'system';
+    const text = extractTextContent(payload, 'content'), images = codexImages(field(payload, 'content'));
+    const emptyAssistant = role === 'assistant' && nativeTrim(text) === '' && !images.length;
+    if (nativeTrim(text) === '' && !images.length && !emptyAssistant) return;
+    const message = createMessage(role, images.length || text === '' ? null : text);
+    if (images.length) {
+      message.content_parts = nativeTrim(text) === '' ? [] : [{ type: 'text', text }];
+      for (const image of images) message.content_parts.push(image);
+    }
+    if (role === 'assistant') {
+      const phase = stringField(payload, 'phase'); if (phase != null) message.metadata.phase = phase;
+      message.metadata.__codex_open_turn = 'true';
+    }
+    const turn = codexTurnId(payload); if (turn != null) message.metadata.turn_id = turn;
+    if (role === 'system') {
+      const subtype = stringField(field(payload, 'metadata'), 'claude_system_subtype'); if (subtype != null) message.metadata.systemSubtype = subtype;
+    }
+    if (emptyAssistant) message.metadata.empty_assistant_record = 'true';
+    out.push(message);
+  } else if (kind === 'function_call' || kind === 'tool_search_call') {
+    const id = stringField(payload, 'call_id') ?? '', rawName = stringField(payload, 'name') ?? '', namespace = stringField(payload, 'namespace');
+    const name = kind === 'tool_search_call' ? 'tool_search' : namespace != null && namespace !== '' && !rawName.startsWith(namespace) ? `${namespace}__${rawName}` : rawName;
+    mergeCall(payload, functionCall(id, name, field(payload, 'arguments') === undefined ? '{}' : valueString(payload, 'arguments')), out);
+  } else if (kind === 'function_call_output' || kind === 'custom_tool_call_output') {
+    const message = toolMessage(stringField(payload, 'call_id') ?? '', extractTextContent(payload, 'output'));
+    const images = codexImages(field(payload, 'output'));
+    if (images.length) {
+      message.content_parts = message.content === '' ? [] : [{ type: 'text', text: message.content }];
+      for (const image of images) message.content_parts.push(image);
+    }
+    markToolOutcomeUnknown(message); out.push(message);
+  } else if (kind === 'custom_tool_call') {
+    const id = stringField(payload, 'call_id') ?? '';
+    pushCodexAssistant(out, '', [functionCall(id, stringField(payload, 'name') ?? '', field(payload, 'input') === undefined ? '{}' : stringifyNativeJsonMember(payload, 'input'))]);
+    out.at(-1).metadata.codex_custom_tool_call_ids = stringifyNativeJson([id]);
+  } else if (kind === 'tool_search_output') out.push(toolMessage(stringField(payload, 'call_id') ?? '', field(payload, 'tools') === undefined ? '' : valueString(payload, 'tools')));
+  else if (kind === 'web_search_call') pushCodexAssistant(out, '[web_search]');
+  else if (kind === 'image_generation_call') pushCodexAssistant(out, nativeTrim(`[image_generation] ${stringField(payload, 'revised_prompt') ?? ''}`));
+}
+
+export function pushCodexModelItem(payload, out, contentItem) {
+  const before = out.length; pushCodexItem(payload, out);
+  if (stringField(payload, 'type') !== 'message' || stringField(payload, 'role') !== 'user') return;
+  const context = codexUserContext(payload); if (context.kind === 'ordinary') return;
+  const hookText = context.kind === 'hook_prompt' ? stringField(contentItem(context.item), 'text') : null;
+  for (let index = before; index < out.length; index++) {
+    out[index].metadata.codex_contextual_kind = context.kind;
+    if (hookText != null) out[index].metadata.codex_hook_prompt_text = hookText;
+  }
+}
+
+export function stampCodexMessages(messages, from, timestamp) {
+  if (timestamp == null) return;
+  for (let index = from; index < messages.length; index++) if (!Object.hasOwn(messages[index].metadata, 'timestamp')) messages[index].metadata.timestamp = timestamp;
+}
+
+export function removeLastCodexTurn(messages) {
+  const index = messages.findLastIndex((message) => message.role === 'user');
+  messages.length = index === -1 ? 0 : index;
+  if (messages.length) delete messages.at(-1).metadata.__codex_open_turn;
+}
+
+export function clearCodexBookkeeping(messages, { display = false } = {}) {
+  for (const message of messages) {
+    delete message.metadata.__codex_open_turn;
+    if (display) delete message.metadata.codex_event_message;
+    if (Object.hasOwn(message.metadata, '__grok_remove_synthetic_turn_id')) { delete message.metadata.__grok_remove_synthetic_turn_id; delete message.metadata.turn_id; }
+  }
+}

package/session-codex-user-history.mjs

@@ -0,0 +1,62 @@
+import { messageWire } from './message.mjs';
+import { nativeInteger, stringifyNativeJson } from './native-json.mjs';
+import { field, stringField } from './session-codec-utils.mjs';
+import { codexTurnId, codexUserWithImages } from './session-codex-items.mjs';
+import { codexItemKind, pushCodexDisplayItem } from './session-codex-display-items.mjs';
+
+export class CodexUserHistory {
+  turn = null;
+  pending = [];
+  legacyPending = null;
+  typed = new Map();
+
+  observeBoundary(record) {
+    const kind = stringField(record, 'type'), payload = field(record, 'payload'), type = stringField(payload, 'type');
+    if (!(kind === 'event_msg' && type === 'user_message')) this.legacyPending = null;
+    if (kind === 'compacted' || (kind === 'event_msg' && type === 'thread_rolled_back')) {
+      this.pending = []; this.typed.clear(); this.turn = null;
+    } else if (kind === 'event_msg' && type === 'task_started') { this.pending = []; this.turn = stringField(payload, 'turn_id'); }
+    else if (kind === 'event_msg' && type === 'task_complete') { this.pending = []; this.turn = null; }
+    else if (!((kind === 'response_item' && type === 'message' && stringField(payload, 'role') === 'user')
+      || (kind === 'event_msg' && (type === 'user_message' || (['item_started', 'item_completed'].includes(type) && codexItemKind(field(payload, 'item')) === 'usermessage'))))) this.pending = [];
+  }
+
+  recordModelInput(record, before, messages) {
+    const payload = field(record, 'payload');
+    if (stringField(payload, 'type') !== 'message' || stringField(payload, 'role') !== 'user') return;
+    const annotations = field(payload, 'internal_chat_message_metadata_passthrough'), kinds = field(annotations, 'content_item_kinds'), content = field(payload, 'content');
+    const order = field(field(record, 'metadata'), 'user_input_order');
+    const userOrigin = nativeInteger(field(record, 'metadata'), 'user_input_order') != null || (Array.isArray(kinds) && kinds.length > 0 && Array.isArray(content) && kinds.length === content.length && kinds.some((kind) => typeof kind === 'string' && kind.startsWith('user.')));
+    const turn = stringField(annotations, 'turn_id') ?? codexTurnId(payload);
+    if (order === undefined && field(annotations, 'content_item_kinds') === undefined && messages.length === before + 1 && messages[before].role === 'user') this.legacyPending = [before, turn ?? this.turn];
+    if (turn != null && userOrigin) {
+      for (let index = before; index < messages.length; index++) if (messages[index].role === 'user') this.pending.push([index, turn]);
+    } else this.pending = [];
+  }
+
+  recordTypedInput(payload, messages) {
+    const durable = stringField(payload, 'type') === 'item_completed', item = durable ? field(payload, 'item') : payload, projected = [];
+    if (durable) pushCodexDisplayItem(item, projected);
+    else {
+      const images = field(item, 'images'), urls = Array.isArray(images) ? images.filter((image) => typeof image === 'string') : [];
+      projected.push(codexUserWithImages(stringField(item, 'message') ?? '', urls));
+    }
+    const message = projected[0]; if (message == null) return;
+    const id = durable ? stringField(item, 'id') : null, client = stringField(item, 'client_id');
+    const keys = [id != null ? `item:${id}` : null, client != null ? `client:${client}` : null].filter((key) => key != null);
+    const existing = keys.map((key) => this.typed.get(key)).find((index) => index !== undefined);
+    const turn = stringField(payload, 'turn_id') ?? this.turn;
+    const candidates = this.pending.filter(([, id]) => id === turn).map(([index]) => index);
+    const legacy = this.legacyPending; this.legacyPending = null;
+    const pair = candidates.length === 1 ? candidates[0] : !durable && legacy?.[1] === turn ? legacy[0] : undefined;
+    const display = stringifyNativeJson(messageWire(message));
+    let index = existing ?? pair;
+    if (index === undefined) { messages.push(message); index = messages.length - 1; }
+    const target = messages[index];
+    delete target.metadata.codex_contextual_kind; delete target.metadata.codex_hook_prompt_text;
+    target.metadata.codex_typed_user = display; target.metadata.codex_typed_user_source = durable ? 'item_completed' : 'user_message';
+    if (keys.length) target.metadata.codex_typed_user_id = keys[0];
+    for (const key of keys) this.typed.set(key, index);
+    if (existing === undefined) this.pending = this.pending.filter(([, id]) => id !== turn);
+  }
+}

package/session-codex.mjs

@@ -0,0 +1,135 @@
+import { createMessage } from './message.mjs';
+import { cloneNativeJson, nativeInteger, parseNativeJson, stringifyNativeJsonMember } from './native-json.mjs';
+import { createSession, codexStartTrigger } from './session-model.mjs';
+import { splitLinesVerbatim, nonEmptyLines } from './session-lines.mjs';
+import { field, stringField, extractTextContent, restoreGrokMessageExtension, ensureToolResultsPaired, stampMessageRecords, takeMessageRecords } from './session-codec-utils.mjs';
+import { restoreTopLevelResidue, captureCodexProvenance } from './session-native-residue.mjs';
+import { pushCodexModelItem, pushCodexAssistant, stampCodexMessages, removeLastCodexTurn, clearCodexBookkeeping } from './session-codex-items.mjs';
+import { codexContentItem, codexItemKind } from './session-codex-display-items.mjs';
+import { CodexUserHistory } from './session-codex-user-history.mjs';
+import { nativeTrim } from './text.mjs';
+
+const append = (current, part) => current + (current === '' ? '' : '\n') + part;
+const restoreSingle = (value, messages, before) => { if (messages.length === before + 1) restoreGrokMessageExtension(value, messages[before]); };
+
+export function captureCodexMeta(payload, meta) {
+  meta.session_id ??= stringField(payload, 'id'); meta.cwd ??= stringField(payload, 'cwd'); meta.model ??= stringField(payload, 'model');
+  const base = field(payload, 'base_instructions');
+  meta.system_prompt ??= typeof base === 'string' ? base : stringField(base, 'text');
+  for (const key of ['parent_thread_id', 'forked_from_id', 'thread_source']) {
+    const value = stringField(payload, key); if (value != null) meta.lineage[key] = value;
+  }
+  meta.trigger ??= codexStartTrigger(payload);
+  if (!Object.hasOwn(meta.lineage, 'claude_fork_context_ref_raw') && field(payload, 'claude_fork_context_ref') !== undefined) meta.lineage.claude_fork_context_ref_raw = stringifyNativeJsonMember(payload, 'claude_fork_context_ref');
+  const spawn = field(field(field(payload, 'source'), 'subagent'), 'thread_spawn');
+  for (const key of ['parent_thread_id', 'agent_role', 'agent_nickname']) {
+    const value = stringField(spawn, key); if (value != null) meta.lineage[key] = value;
+  }
+  const depth = nativeInteger(spawn, 'depth', { signed: true }); if (depth != null) meta.lineage.depth = String(depth);
+}
+
+function assistantTexts(text) {
+  const result = new Set();
+  for (const line of nonEmptyLines(text)) {
+    let value; try { value = parseNativeJson(line); } catch { continue; }
+    const payload = field(value, 'payload');
+    if (stringField(value, 'type') !== 'response_item' || stringField(payload, 'type') !== 'message' || stringField(payload, 'role') !== 'assistant') continue;
+    const text = nativeTrim(extractTextContent(payload, 'content')); if (text !== '') result.add(text);
+  }
+  return result;
+}
+
+function floatDisplay(value) {
+  const text = String(value); if (!/[eE]/.test(text)) return Object.is(value, -0) ? '-0' : text;
+  const [coefficient, exponent] = text.split(/[eE]/), negative = coefficient.startsWith('-');
+  const unsigned = negative ? coefficient.slice(1) : coefficient, point = unsigned.indexOf('.');
+  const digits = unsigned.replace('.', ''), position = (point === -1 ? unsigned.length : point) + Number(exponent);
+  const body = position <= 0 ? `0.${'0'.repeat(-position)}${digits}` : position >= digits.length ? digits + '0'.repeat(position - digits.length) : digits.slice(0, position) + '.' + digits.slice(position);
+  return (negative ? '-' : '') + body;
+}
+
+/** Resumable model history. Display TurnItems have a separate bounded reader;
+ * compaction replacement applies here and never rewrites retained raw bytes. */
+export function fromCodexStr(text, { applyCompaction = true } = {}) {
+  const session = createSession('codex'), { meta, messages } = session, capture = splitLinesVerbatim(text);
+  session.raw = capture.lines; session.raw_trailing_newline = capture.trailingNewline; session.raw_is_verbatim = true;
+  const canonicalTexts = assistantTexts(text), users = new CodexUserHistory();
+  let reasoning = '', reasoningContent = '', encrypted = false, restored = false;
+  const orphan = () => {
+    const message = createMessage('system', '[reasoning] (turn ended without a reply)');
+    if (reasoning !== '') message.metadata.reasoning = reasoning;
+    if (reasoningContent !== '') message.metadata.reasoning_content = reasoningContent;
+    if (encrypted) message.metadata.reasoning_encrypted = 'true';
+    reasoning = ''; reasoningContent = ''; encrypted = false; return message;
+  };
+  capture.lines.forEach((raw, index) => {
+    if (index > 0) stampMessageRecords(messages, index - 1);
+    const line = nativeTrim(raw); if (line === '') return;
+    let value; try { value = parseNativeJson(line); } catch { session.parse_error_lines++; return; }
+    const kind = stringField(value, 'type'), payload = field(value, 'payload'), type = stringField(payload, 'type'), timestamp = stringField(value, 'timestamp');
+    if (!restored && kind === 'session_meta' && restoreTopLevelResidue(payload, meta)) restored = true;
+    if (!restored) captureCodexProvenance(meta, index, raw, value);
+    users.observeBoundary(value);
+    if (kind === 'session_meta') { captureCodexMeta(payload, meta); if (!restored) meta.codex_headers.push(cloneNativeJson(value)); }
+    else if (kind === 'turn_context') { meta.model ??= stringField(payload, 'model'); if (!restored) meta.codex_headers.push(cloneNativeJson(value)); }
+    else if (kind === 'response_item' && type === 'reasoning') {
+      const summary = extractTextContent(payload, 'summary'); if (nativeTrim(summary) !== '') reasoning = append(reasoning, summary);
+      if (field(payload, 'content') != null) { const text = extractTextContent(payload, 'content'); if (nativeTrim(text) !== '') reasoningContent = append(reasoningContent, text); }
+      if (field(payload, 'encrypted_content') != null) encrypted = true;
+    } else if (kind === 'response_item') {
+      const before = messages.length; pushCodexModelItem(payload, messages, codexContentItem);
+      if (messages.length > before && (reasoning !== '' || reasoningContent !== '' || encrypted)) {
+        if (messages.at(-1).role === 'assistant') {
+          const last = messages.at(-1);
+          if (reasoning !== '') last.metadata.reasoning = reasoning;
+          if (reasoningContent !== '') last.metadata.reasoning_content = reasoningContent;
+          if (encrypted) last.metadata.reasoning_encrypted = 'true';
+          reasoning = ''; reasoningContent = ''; encrypted = false;
+        } else messages.splice(before, 0, orphan());
+      }
+      stampCodexMessages(messages, before, timestamp); restoreSingle(payload, messages, before);
+      users.recordModelInput(value, before, messages);
+    } else if (kind === 'compacted' && applyCompaction) {
+      messages.length = 0;
+      const history = field(payload, 'replacement_history');
+      if (Array.isArray(history)) for (const item of history) pushCodexModelItem(item, messages, codexContentItem);
+      stampCodexMessages(messages, 0, timestamp);
+      if (messages.length) delete messages.at(-1).metadata.__codex_open_turn;
+    } else if (kind === 'event_msg' && type === 'agent_message') {
+      const before = messages.length, text = extractTextContent(payload, 'message');
+      if (nativeTrim(text) !== '' && !canonicalTexts.has(nativeTrim(text))) {
+        pushCodexAssistant(messages, text); const phase = stringField(payload, 'phase'); if (phase != null) messages.at(-1).metadata.phase = phase;
+      }
+      stampCodexMessages(messages, before, timestamp);
+    } else if (kind === 'event_msg' && type === 'thread_rolled_back') {
+      const turns = nativeInteger(payload, 'num_turns') ?? 1n;
+      for (let left = turns; left > 0n && messages.length; left--) removeLastCodexTurn(messages);
+    } else if (kind === 'event_msg' && type === 'thread_goal_updated') {
+      const before = messages.length, goal = field(payload, 'goal'), objective = stringField(goal, 'objective');
+      if (objective != null && nativeTrim(objective) !== '') {
+        const message = createMessage('system', `[thread goal] ${objective}`), status = stringField(goal, 'status'), budget = nativeInteger(goal, 'tokenBudget', { signed: true });
+        if (status != null) message.metadata.goal_status = status;
+        if (budget != null) message.metadata.goal_token_budget = String(budget);
+        messages.push(message);
+      }
+      stampCodexMessages(messages, before, timestamp);
+    } else if (kind === 'event_msg' && type === 'exited_review_mode') {
+      const before = messages.length, review = field(payload, 'review_output');
+      if (review !== undefined) {
+        pushCodexAssistant(messages, `[code review] ${stringField(review, 'overall_explanation') ?? stringifyNativeJsonMember(payload, 'review_output')}`);
+        const last = messages.at(-1), findings = field(review, 'findings');
+        if (Array.isArray(findings) && findings.length) last.metadata.review_findings = stringifyNativeJsonMember(review, 'findings');
+        const correctness = stringField(review, 'overall_correctness'), score = field(review, 'overall_confidence_score');
+        if (correctness != null) last.metadata.review_overall_correctness = correctness;
+        if (typeof score === 'number') last.metadata.review_overall_confidence_score = floatDisplay(score);
+      }
+      stampCodexMessages(messages, before, timestamp);
+    } else if (kind === 'event_msg' && (type === 'user_message' || (type === 'item_completed' && codexItemKind(field(payload, 'item')) === 'usermessage'))) {
+      const before = messages.length; users.recordTypedInput(payload, messages); stampCodexMessages(messages, before, timestamp);
+    }
+  });
+  if (reasoning !== '' || reasoningContent !== '' || encrypted) messages.push(orphan());
+  stampMessageRecords(messages, Math.max(0, capture.lines.length - 1)); ensureToolResultsPaired(messages);
+  meta.message_records = takeMessageRecords(messages); clearCodexBookkeeping(messages); session.imported_message_count = messages.length;
+  return session;
+}

package/session-display.mjs

@@ -0,0 +1,135 @@
+import { withSessionFile } from './file-io.mjs';
+import { sourceStat } from './store-registry.mjs';
+import { verifySources } from './source-files.mjs';
+import { sessionFileLines, decodeSessionUtf8 } from './session-file.mjs';
+import { field, stringField, truncateMessagesWithAnchor } from './session-codec-utils.mjs';
+import { parseNativeJson } from './native-json.mjs';
+import { nativeTrim } from './text.mjs';
+import { detectSessionSource } from './session-source.mjs';
+import { isCompressedSessionPath, sessionReaderText, looksLikeSessionSqlite, loadSessionPath, loadLocatorDisplayStore, captureGrokPathMetadata } from './session-path.mjs';
+import { fromCodexDisplayStr } from './session-codex-display.mjs';
+import { fromGeminiStr } from './session-gemini.mjs';
+import { fromPiStr } from './session-pi.mjs';
+import { fromGrokStr } from './session-grok.mjs';
+import { fromOpenCodeStr } from './session-opencode.mjs';
+import { fromClaudeCodeStr } from './session-claude.mjs';
+
+const MAX_BYTES = 64 * 1024 * 1024, MIN_BYTES = 4 * 1024 * 1024;
+function humanLine(line, source, paginated) {
+  if (!['"user"', '"UserMessage"', '"user_message"'].some((literal) => line.includes(literal))) return false;
+  let value; try { value = parseNativeJson(line); } catch { return false; }
+  const kind = stringField(value, 'type'), payload = field(value, 'payload');
+  if (source === 'codex') {
+    if (kind === 'event_msg' && stringField(payload, 'type') === 'item_completed') return stringField(field(payload, 'item'), 'type') === 'UserMessage';
+    if (paginated) return false;
+    if (kind === 'event_msg' && stringField(payload, 'type') === 'user_message') return true;
+    return kind === 'response_item' && stringField(payload, 'type') === 'message' && stringField(payload, 'role') === 'user';
+  }
+  if (kind !== 'user') return false;
+  const content = source === 'claude_code' ? field(field(value, 'message'), 'content') : source === 'gemini' ? field(value, 'content') : null;
+  return typeof content === 'string' ? nativeTrim(content) !== '' : Array.isArray(content) && content.some((part) => (source !== 'claude_code' || stringField(part, 'type') === 'text') && typeof field(part, 'text') === 'string' && nativeTrim(part.text) !== '');
+}
+async function firstLine(reader) {
+  for await (const line of sessionFileLines(reader)) return line.text;
+  return '';
+}
+
+async function displayJsonl(reader, readLimit) {
+  if (isCompressedSessionPath(reader.path)) {
+    const text = await sessionReaderText(reader); return { source: detectSessionSource(text), text, omitted: false };
+  }
+  const first = await firstLine(reader), source = detectSessionSource(first);
+  let header; try { header = parseNativeJson(first); } catch { header = null; }
+  const paginated = source === 'codex' && stringField(field(header, 'payload'), 'history_mode') === 'paginated';
+  const requested = Math.min(MAX_BYTES, Math.max(MIN_BYTES, Math.max(1, readLimit) * 16 * 1024));
+  if (!['claude_code', 'codex', 'gemini'].includes(source) || reader.size <= requested) {
+    const text = await sessionReaderText(reader);
+    return { source: ['claude_code', 'codex', 'gemini'].includes(source) ? source : detectSessionSource(text), text, omitted: false };
+  }
+  const start = reader.size - requested;
+  let bytes = await reader.read(start, requested);
+  const newline = bytes.indexOf(10); if (newline !== -1) bytes = bytes.subarray(newline + 1);
+  let tail;
+  try { tail = decodeSessionUtf8(bytes); } catch (error) { throw new Error(`${reader.path} contains non-UTF-8 data in its display window`, { cause: error }); }
+  const maximum = Math.min(start, MAX_BYTES); let searchSize = Math.min(requested, maximum), anchors = [];
+  while (searchSize > 0) {
+    const searchStart = start - searchSize; let search = await reader.read(searchStart, searchSize);
+    if (searchStart > 0) { const newline = search.indexOf(10); search = newline === -1 ? Buffer.alloc(0) : search.subarray(newline + 1); }
+    const end = search.lastIndexOf(10); search = end === -1 ? Buffer.alloc(0) : search.subarray(0, end + 1);
+    let text; try { text = decodeSessionUtf8(search); } catch { text = ''; }
+    anchors = [];
+    const lines = text.split('\n');
+    for (let at = lines.length - 1; at >= 0 && anchors.length < 2; at--) {
+      const line = lines[at].endsWith('\r') ? lines[at].slice(0, -1) : lines[at];
+      if (humanLine(line, source, paginated)) anchors.push(line);
+    }
+    anchors.reverse();
+    if (anchors.length >= 2 || searchStart === 0 || searchSize === maximum) break;
+    searchSize = Math.min(searchSize * 2, maximum);
+  }
+  if (anchors.length) tail = `${anchors.join('\n')}\n${tail}`;
+  return { source, text: source === 'codex' || source === 'gemini' ? first + tail : tail, omitted: true };
+}
+
+async function decodeDisplay(source, text, path, fidelity, limit, metrics, sources) {
+  if (source === 'codex') return fromCodexDisplayStr(text, limit);
+  if (source === 'gemini') {
+    const session = fromGeminiStr(text); session.raw_is_verbatim = false;
+    session.load_residue.push('display history is a bounded native-record projection, not a complete Gemini artifact'); return session;
+  }
+  if (source === 'pi') return fromPiStr(text);
+  if (source === 'grok') {
+    const session = fromGrokStr(text); sources.push(await captureGrokPathMetadata(session, path, metrics)); return session;
+  }
+  if (source === 'opencode') return fromOpenCodeStr(text);
+  // Native display admission uses this fallback; adding a new dialect to
+  // display mode is separate from moving the existing complete-read contract.
+  return fromClaudeCodeStr(text, { fidelity });
+}
+
+export async function loadSessionDisplayPath(path, messageLimit, { fidelity = 'byte_lossless', metrics, env } = {}) {
+  if (!Number.isSafeInteger(messageLimit) || messageLimit < 0) throw new TypeError('display message limit must be a nonnegative exact integer');
+  if ((await sourceStat(path))?.isDirectory() || await looksLikeSessionSqlite(path, metrics)) {
+    const session = await loadSessionPath(path, { fidelity, includeSubagents: false, metrics, env });
+    truncateMessagesWithAnchor(session.messages, messageLimit); return session;
+  }
+  return (await withSessionFile(path, async (reader) => {
+    let readLimit = Math.max(1, messageLimit), previousBytes = 0, session, omitted;
+    const sources = [];
+    while (true) {
+      const read = await displayJsonl(reader, readLimit);
+      session = await decodeDisplay(read.source, read.text, path, fidelity, messageLimit, metrics, sources); omitted = read.omitted;
+      const count = Math.max(session.imported_message_count ?? session.messages.length, session.messages.length), humans = session.messages.filter((message) => message.role === 'user').length;
+      const bytes = Buffer.byteLength(read.text), sufficient = !omitted || (count > Math.max(1, messageLimit) && humans >= 2);
+      if (sufficient || (bytes <= previousBytes && readLimit >= 4096)) {
+        if (omitted) session.imported_message_count = Math.max(count, Math.max(1, messageLimit) + 1); break;
+      }
+      previousBytes = bytes; readLimit = Math.min(Number.MAX_SAFE_INTEGER, readLimit * 2);
+    }
+    if (omitted) session.load_residue.push('older native records remain outside this bounded display window');
+    await verifySources(sources);
+    truncateMessagesWithAnchor(session.messages, messageLimit); return session;
+  }, metrics)).result;
+}
+
+export async function loadSessionDisplayLocator(locator, messageLimit, options = {}) {
+  return await loadLocatorDisplayStore(locator, messageLimit, options) ?? loadSessionDisplayPath(locator.storage.path, messageLimit, options);
+}
+
+export async function loadSessionDisplayFrom(locator, fromByte, options = {}) {
+  const { path, kind } = locator.storage, unbounded = 1_000_000;
+  if (!Number.isSafeInteger(fromByte) || fromByte < 0) throw new TypeError('display anchor must be a nonnegative exact byte offset');
+  if (kind !== 'file' || locator.harness === 'hermes') return loadSessionDisplayLocator(locator, unbounded, options);
+  if ((await sourceStat(path))?.isDirectory() || await looksLikeSessionSqlite(path, options.metrics) || isCompressedSessionPath(path) || fromByte === 0) return loadSessionDisplayPath(path, unbounded, options);
+  // Keep the fixed anchor and detection under one open file identity.
+  const captured = await withSessionFile(path, async (reader) => {
+    const first = await firstLine(reader); if (detectSessionSource(first) !== 'codex') return null;
+    if (fromByte >= reader.size) throw new Error(`${path} is shorter than its display anchor (${fromByte})`);
+    let bytes = await reader.read(fromByte, reader.size - fromByte);
+    const newline = bytes.indexOf(10); bytes = newline === -1 ? Buffer.alloc(0) : bytes.subarray(newline + 1);
+    let tail; try { tail = decodeSessionUtf8(bytes); } catch (error) { throw new Error(`${path} contains non-UTF-8 data after its display anchor`, { cause: error }); }
+    const session = fromCodexDisplayStr(first + tail, unbounded);
+    session.load_residue.push(`older native records remain before this display anchor (${fromByte})`); return session;
+  }, options.metrics);
+  return captured.result ?? loadSessionDisplayPath(path, unbounded, options);
+}

package/session-document.mjs

@@ -0,0 +1,19 @@
+import { fromClaudeCodeStr } from './session-claude.mjs';
+import { fromCodexStr } from './session-codex.mjs';
+import { fromGeminiStr } from './session-gemini.mjs';
+import { fromGooseStr } from './session-goose.mjs';
+import { fromGrokStr } from './session-grok.mjs';
+import { fromOpenCodeStr } from './session-opencode.mjs';
+import { fromPiStr, fromOpenClawStr } from './session-pi.mjs';
+import { detectSessionSource } from './session-source.mjs';
+
+export function readSessionDocument(text, { source = detectSessionSource(text), fidelity = 'byte_lossless' } = {}) {
+  if (source === 'codex') return fromCodexStr(text);
+  if (source === 'gemini') return fromGeminiStr(text);
+  if (source === 'goose') return fromGooseStr(text);
+  if (source === 'grok') return fromGrokStr(text);
+  if (source === 'opencode') return fromOpenCodeStr(text);
+  if (source === 'pi') return fromPiStr(text);
+  if (source === 'openclaw') return fromOpenClawStr(text);
+  return fromClaudeCodeStr(text, { fidelity });
+}

package/session-file.mjs

@@ -0,0 +1,27 @@
+import { withSessionFile } from './file-io.mjs';
+
+export const decodeSessionUtf8 = (bytes) => new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
+
+/** One physical line at a time, including an unterminated final line. LF and
+ * CR remain in the bytes; offsets always address the verified open file. */
+export async function* sessionFileLines(reader) {
+  let pieces = [], pending = 0, start = 0;
+  for (let offset = 0; offset < reader.size;) {
+    const chunk = await reader.read(offset, Math.min(64 * 1024, reader.size - offset));
+    const chunkStart = offset; offset += chunk.length;
+    let from = 0, end;
+    while ((end = chunk.indexOf(10, from)) !== -1) {
+      pieces.push(chunk.subarray(from, end + 1)); pending += end + 1 - from;
+      const bytes = pieces.length === 1 ? pieces[0] : Buffer.concat(pieces, pending);
+      yield { offset: start, length: pending, text: decodeSessionUtf8(bytes) };
+      start = chunkStart + end + 1; from = end + 1; pieces = []; pending = 0;
+    }
+    if (from < chunk.length) { pieces.push(chunk.subarray(from)); pending += chunk.length - from; }
+  }
+  if (pending) yield { offset: start, length: pending, text: decodeSessionUtf8(Buffer.concat(pieces, pending)) };
+}
+
+export async function readSessionText(path, metrics) {
+  const capture = await withSessionFile(path, async (reader) => decodeSessionUtf8(await reader.read(0, reader.size)), metrics);
+  return capture.result;
+}