@volter/supercode-interchange 0.1.22 → 0.1.24

package/session-write-grok.mjs

@@ -0,0 +1,70 @@
+import { nativeInteger } from './native-json.mjs';
+import { NATIVE_RESIDUE_KEY, NATIVE_RESIDUE_SUMMARY_KEY } from './session-native-residue.mjs';
+import { nativeResidueEnvelope, nativeResidueSummary } from './session-write-residue.mjs';
+import { replayExcluded, parsedJsonField, targetMessageExtension, splicedPrefixLengths, jsonLine, injectFirstJsonLine } from './session-write-utils.mjs';
+
+function grokRecords(session, messages) {
+  let text = '';
+  for (const message of messages) {
+    if (replayExcluded(message)) continue;
+    let value;
+    switch (message.role) {
+      case 'system': value = { type: 'user', content: [{ type: 'text', text: message.content ?? '' }],
+        synthetic_reason: 'supercode_system_event' }; break;
+      case 'user':
+        value = { type: 'user', content: [{ type: 'text', text: message.content ?? '' }] };
+        for (const [metadata, field] of [['grok_prompt_index', 'prompt_index'], ['grok_prior_turn_interrupt', 'prior_turn_interrupt'],
+          ['grok_synthetic_reason', 'synthetic_reason']]) {
+          const raw = message.metadata[metadata];
+          if (raw != null) parsedJsonField(value, field, raw);
+        }
+        break;
+      case 'assistant':
+        value = { type: 'assistant', content: message.content ?? '', tool_calls: (message.tool_calls ?? []).map(call => ({
+          id: call.id, name: call.function.name, arguments: call.function.arguments,
+        })), model_id: message.metadata.grok_model_id ?? session.meta.model ?? 'unknown' };
+        for (const [metadata, field] of [['grok_model_fingerprint', 'model_fingerprint'], ['grok_reasoning_effort', 'reasoning_effort']]) {
+          if (message.metadata[metadata] != null) value[field] = message.metadata[metadata];
+        }
+        break;
+      case 'tool': {
+        value = { type: 'tool_result', tool_call_id: message.tool_call_id ?? '', content: message.content ?? '' };
+        const images = (message.content_parts ?? []).filter(part => part?.type === 'image_url')
+          .map(part => part?.image_url?.url).filter(url => typeof url === 'string').map(url => ({ type: 'image', url }));
+        if (images.length) value.images = images;
+        break;
+      }
+      default: throw new TypeError(`unknown message role: ${message.role}`);
+    }
+    targetMessageExtension(value, message); text += jsonLine(value);
+  }
+  return text;
+}
+
+export function toGrokJsonl(session) {
+  let text = session.meta.system_prompt ? jsonLine({ type: 'system', content: session.meta.system_prompt }) : '';
+  text += grokRecords(session, session.messages);
+  if (session.meta.native_residue_source === 'grok') {
+    const recordIndex = record => nativeInteger(record, 'record_index') ?? ((1n << 64n) - 1n);
+    const records = [...session.meta.native_residue].sort((left, right) => {
+      const a = recordIndex(left), b = recordIndex(right); return a < b ? -1 : a > b ? 1 : 0;
+    });
+    for (const entry of records) if (typeof entry?.raw === 'string') text += entry.raw + '\n';
+  } else {
+    const envelope = nativeResidueEnvelope(session.meta);
+    if (envelope != null) {
+      if (!text) text = jsonLine({ type: 'system', content: '' });
+      text = injectFirstJsonLine(text, NATIVE_RESIDUE_SUMMARY_KEY, nativeResidueSummary(envelope));
+      text = injectFirstJsonLine(text, NATIVE_RESIDUE_KEY, envelope);
+    }
+  }
+  return text;
+}
+
+/** Grok keeps its identity in the directory; its raw records have no session id to rewrite. */
+export function toGrokJsonlSpliced(session) {
+  const prefix = splicedPrefixLengths(session);
+  if (!prefix.raw) return toGrokJsonl(session);
+  return session.raw.slice(0, prefix.raw).map(line => line + '\n').join('')
+    + grokRecords(session, session.messages.slice(prefix.messages));
+}

package/session-write-native.mjs

@@ -0,0 +1,41 @@
+import { blake3 } from '@noble/hashes/blake3.js';
+import { cloneNativeJson, stringifyNativeJson } from './native-json.mjs';
+import { jsonLine, orderedMessageMetadata } from './session-write-utils.mjs';
+
+export function toNativeJsonl(session) {
+  return jsonLine({ supercode_native: 1, source: session.meta.source, raw_trailing_newline: session.raw_trailing_newline })
+    + session.raw.map(line => line + '\n').join('');
+}
+
+function nativeTurnUuid(message, timestamp, index) {
+  const identity = { role: message.role, content: message.content, content_parts: message.content_parts,
+    tool_calls: message.tool_calls, tool_call_id: message.tool_call_id, name: message.name };
+  const ordinal = Buffer.alloc(8); ordinal.writeBigUInt64LE(BigInt(index));
+  const digest = Buffer.from(blake3(Buffer.concat([Buffer.from('supercode-native-turn-uuid-v1\0'), Buffer.from(timestamp),
+    ordinal, Buffer.from(stringifyNativeJson(identity))])));
+  const bytes = digest.subarray(0, 16); bytes[6] = (bytes[6] & 0x0f) | 0x40; bytes[8] = (bytes[8] & 0x3f) | 0x80;
+  const hex = bytes.toString('hex'); return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+/** Pure container construction; this does not open or append a sidecar file. */
+export function toNativeJsonlV2(session, appended, fixedTimestamp = null) {
+  const header = { supercode_native: 2, source: session.meta.source, session_id: session.meta.session_id,
+    created: fixedTimestamp ?? new Date().toISOString(), raw_trailing_newline: session.raw_trailing_newline };
+  if (session.meta.agent_id != null) header.agent_id = session.meta.agent_id;
+  if (session.meta.parent_tool_use_id != null) header.parent_tool_use_id = session.meta.parent_tool_use_id;
+  if (Object.keys(session.meta.lineage).length) header.lineage = orderedMessageMetadata(session.meta.lineage);
+  let text = jsonLine(header) + session.raw.map(line => line + '\n').join('');
+  for (const [index, message] of appended.entries()) {
+    const timestamp = fixedTimestamp ?? new Date().toISOString();
+    const metadata = cloneNativeJson(message.metadata);
+    if (!Object.hasOwn(metadata, 'timestamp')) metadata.timestamp = timestamp;
+    if (!Object.hasOwn(metadata, 'supercode_native_uuid')) metadata.supercode_native_uuid = nativeTurnUuid(message, timestamp, index);
+    const turn = { supercode_turn: 1, ts: timestamp, role: message.role };
+    for (const key of ['content', 'content_parts', 'tool_calls', 'tool_call_id', 'name']) {
+      if (message[key] != null) turn[key] = cloneNativeJson(message[key]);
+    }
+    if (Object.keys(metadata).length) turn.metadata = orderedMessageMetadata(metadata);
+    text += jsonLine(turn);
+  }
+  return text;
+}

package/session-write-opencode.mjs

@@ -0,0 +1,197 @@
+import { cloneNativeJson, nativeInteger, nativeObjectKeys, setNativeInteger, setNativeJsonText, stringifyNativeJsonPretty } from './native-json.mjs';
+import emitterVersion from './session-emission-version.json' with { type: 'json' };
+import { isToolError, toolOutcome } from './message.mjs';
+import { nativeTrim } from './text.mjs';
+import { usageTimestamp } from './session-usage-time.mjs';
+import { NATIVE_RESIDUE_KEY, NATIVE_RESIDUE_SUMMARY_KEY } from './session-native-residue.mjs';
+import { nativeResidueEnvelope, nativeResidueSummary } from './session-write-residue.mjs';
+import { SYNTH_TS_MS, replayExcluded, sessionCwd, tryNativeJson, sourceMessageExtension, splicedPrefixLengths,
+  parsedJsonField } from './session-write-utils.mjs';
+
+const utf8Order = (left, right) => Buffer.compare(Buffer.from(left), Buffer.from(right));
+const object = value => value != null && typeof value === 'object' && !Array.isArray(value);
+const clock = fields => {
+  const result = {};
+  for (const [key, value] of Object.entries(fields)) setNativeInteger(result, key, value);
+  return result;
+};
+const largest = values => values.reduce((max, next) => next == null ? max : max == null || next > max ? next : max, null);
+
+function maxTimestamp(value) {
+  const maxNumber = (parent, key) => {
+    const child = parent[key];
+    if (typeof child === 'number') return nativeInteger(parent, String(key), { signed: true });
+    return child == null || typeof child !== 'object' ? null : largest(nativeObjectKeys(child).map(key => maxNumber(child, key)));
+  };
+  if (value == null || typeof value !== 'object') return null;
+  return largest(nativeObjectKeys(value).map(key => key === 'time' ? maxNumber(value, key) : maxTimestamp(value[key])));
+}
+
+function synthesizedInfo(session) {
+  const info = { id: session.meta.session_id ?? 'ses_supercode00000000000001', projectID: session.meta.lineage.projectID ?? 'global',
+    slug: session.meta.lineage.slug ?? 'supercode-export', directory: sessionCwd(session), title: 'supercode export',
+    version: emitterVersion, time: clock({ created: SYNTH_TS_MS, updated: SYNTH_TS_MS }) };
+  if (session.meta.agent_id != null) info.agent = session.meta.agent_id;
+  const model = session.meta.model, slash = model?.indexOf('/') ?? -1;
+  if (slash >= 0) info.model = { providerID: model.slice(0, slash), id: model.slice(slash + 1) };
+  if (session.meta.lineage.parent_session_id != null) info.parentID = session.meta.lineage.parent_session_id;
+  if (session.meta.lineage.claude_fork_context_ref_raw != null) parsedJsonField(info, 'claude_fork_context_ref', session.meta.lineage.claude_fork_context_ref_raw);
+  const envelope = nativeResidueEnvelope(session.meta);
+  if (envelope != null) { info[NATIVE_RESIDUE_SUMMARY_KEY] = nativeResidueSummary(envelope); info[NATIVE_RESIDUE_KEY] = envelope; }
+  return info;
+}
+
+function recordsFromRaw(session) {
+  let info; const values = new Map(), parts = new Map();
+  for (const line of session.raw) {
+    const envelope = tryNativeJson(line); if (!Array.isArray(envelope?.key)) continue;
+    const value = envelope.value ?? null;
+    switch (envelope.key[0]) {
+      case 'session': info = value; break;
+      case 'message': if (typeof value?.id === 'string') values.set(value.id, value); break;
+      case 'part': if (typeof value?.messageID === 'string') {
+        const list = parts.get(value.messageID) ?? []; list.push(value); parts.set(value.messageID, list);
+      } break;
+    }
+  }
+  const created = value => nativeInteger(value?.time, 'created', { signed: true }) ?? 0n;
+  const records = [...values].sort(([aId, a], [bId, b]) => created(a) < created(b) ? -1 : created(a) > created(b) ? 1 : utf8Order(aId, bId))
+    .map(([id, value]) => ({ info: value, parts: (parts.get(id) ?? []).sort((a, b) => utf8Order(typeof a?.id === 'string' ? a.id : '', typeof b?.id === 'string' ? b.id : '')) }));
+  return { info, records };
+}
+
+function restoreFields(info, message, assistant) {
+  const metadata = message.metadata;
+  if (metadata.agent != null) info.agent = metadata.agent;
+  if (metadata.model != null) {
+    if (assistant) {
+      const slash = metadata.model.indexOf('/');
+      if (slash >= 0) { info.providerID = metadata.model.slice(0, slash); info.modelID = metadata.model.slice(slash + 1); }
+    } else try { setNativeJsonText(info, 'model', metadata.model); } catch { /* Unparseable source model is omitted. */ }
+  }
+  if (!assistant) return;
+  if (metadata.is_summary === 'true') info.summary = true;
+  if (metadata.finish != null) info.finish = metadata.finish;
+  for (const key of ['cost', 'tokens']) if (metadata[key] != null) {
+    try { setNativeJsonText(info, key, metadata[key]); } catch { /* The native writer likewise omits invalid JSON. */ }
+  }
+}
+
+function imageAttachments(parts) {
+  return (parts ?? []).filter(part => part?.type === 'image_url' && typeof part?.image_url?.url === 'string').map(part => {
+    const url = part.image_url.url, comma = url.indexOf(',', 5);
+    const mime = url.startsWith('data:') && comma >= 0 ? url.slice(5, comma).replace(/(?:;base64)+$/u, '') : 'application/octet-stream';
+    return { mime, url };
+  });
+}
+
+function appendMessages(session, messages, sessionId, cursor) {
+  const calls = new Map(), results = new Map(), paired = new Map();
+  for (const [index, message] of messages.entries()) {
+    if (message.role === 'assistant') for (const [toolIndex, call] of (message.tool_calls ?? []).entries()) {
+      const occurrences = calls.get(call.id) ?? []; occurrences.push([index, toolIndex]); calls.set(call.id, occurrences);
+    }
+    else if (message.role === 'tool' && message.tool_call_id != null) {
+      const occurrences = results.get(message.tool_call_id) ?? []; occurrences.push([index, message]); results.set(message.tool_call_id, occurrences);
+    }
+  }
+  for (const [id, occurrences] of calls) {
+    const outputs = results.get(id) ?? [];
+    for (let index = 0; index < Math.min(occurrences.length, outputs.length); index++) paired.set(occurrences[index].join(':'), outputs[index]);
+  }
+  let counter = 0n, position = cursor; const out = [];
+  const freshId = prefix => `${prefix}_synth${String(++counter).padStart(6, '0')}`;
+  const timestamp = message => {
+    const real = usageTimestamp(message.metadata.timestamp);
+    if (real != null && !(Object.hasOwn(message.metadata, 'supercode_native_uuid') && real <= position)) {
+      if (real > position) position = real; return real;
+    }
+    if (position === (1n << 63n) - 1n) throw new Error('cannot synthesize an OpenCode continuation timestamp after i64::MAX');
+    position++;
+    if (real == null && position < SYNTH_TS_MS) position = SYNTH_TS_MS;
+    return position;
+  };
+  const partBase = (messageID, type) => ({ id: freshId('prt'), sessionID: sessionId, messageID, type });
+  for (const [index, message] of messages.entries()) {
+    if (replayExcluded(message) || message.role === 'tool') continue;
+    if (message.role === 'system' && !nativeTrim(message.content ?? '')) continue;
+    const id = freshId('msg'), parts = []; let created;
+    if (message.role === 'system') {
+      const part = { ...partBase(id, 'text'), text: message.content, synthetic: true,
+        metadata: { supercode_claude_system_subtype: message.metadata.systemSubtype ?? 'local_command' } };
+      parts.push(part); created = timestamp(message);
+    } else if (message.role === 'user') {
+      if (message.content_parts != null) for (const part of message.content_parts) {
+        if (part?.type === 'text' && typeof part.text === 'string') parts.push({ ...partBase(id, 'text'), text: part.text });
+        else if (part?.type === 'image_url' && typeof part?.image_url?.url === 'string') {
+          const attachment = imageAttachments([part])[0]; parts.push({ ...partBase(id, 'file'), ...attachment });
+        }
+      }
+      else if (message.content) parts.push({ ...partBase(id, 'text'), text: message.content });
+      created = timestamp(message);
+    } else if (message.role === 'assistant') {
+      created = timestamp(message);
+      if (message.metadata.thinking != null) {
+        const part = { ...partBase(id, 'reasoning'), text: message.metadata.thinking, time: clock({ start: created, end: created }) };
+        if (message.metadata.thinking_signature != null) part.metadata = { anthropic: { signature: message.metadata.thinking_signature } };
+        parts.push(part);
+      }
+      if (message.content) parts.push({ ...partBase(id, 'text'), text: message.content });
+      for (const [toolIndex, call] of (message.tool_calls ?? []).entries()) {
+        const output = paired.get(`${index}:${toolIndex}`); let state;
+        if (output != null) {
+          const result = output[1], end = timestamp(result);
+          state = isToolError(result) ? { status: 'error', input: null, error: result.content ?? '', time: clock({ end }) }
+            : { status: 'completed', input: null, output: result.content ?? '', title: call.function.name, time: clock({ end }) };
+          if (!isToolError(result)) { const attachments = imageAttachments(result.content_parts); if (attachments.length) state.attachments = attachments; }
+        } else state = { status: 'pending', input: null };
+        const args = nativeTrim(call.function.arguments);
+        if (!args) state.input = {}; else parsedJsonField(state, 'input', args, {});
+        const part = { ...partBase(id, 'tool'), callID: call.id, tool: call.function.name, state };
+        if (output != null) {
+          part._supercode_result_position = output[0];
+          if (toolOutcome(output[1]) === 'unknown') part._supercode_tool_outcome = 'unknown';
+          sourceMessageExtension(part, session.meta.source, output[1]);
+        }
+        parts.push(part);
+      }
+    } else throw new TypeError(`unknown message role: ${message.role}`);
+    const info = { id, sessionID: sessionId, role: message.role === 'assistant' ? 'assistant' : 'user',
+      time: clock({ created }), _supercode_message_position: index };
+    if (message.role !== 'system') { restoreFields(info, message, message.role === 'assistant'); sourceMessageExtension(info, session.meta.source, message); }
+    out.push({ info, parts });
+  }
+  return { messages: out, cursor: position };
+}
+
+function touchUpdated(info, cursor) {
+  if (!object(info.time)) info.time = {};
+  setNativeInteger(info.time, 'updated', cursor);
+}
+
+export function toOpenCodeJson(session) {
+  const info = synthesizedInfo(session), cursor = maxTimestamp(info) ?? (SYNTH_TS_MS - 1n);
+  const result = appendMessages(session, session.messages, typeof info.id === 'string' ? info.id : 'ses_new', cursor);
+  if (result.messages.length) touchUpdated(info, result.cursor);
+  return stringifyNativeJsonPretty({ info, messages: result.messages });
+}
+
+export function toOpenCodeJsonSpliced(session, sessionId = null) {
+  if (!session.raw.length) return toOpenCodeJson(session);
+  const retained = recordsFromRaw(session);
+  let info = retained.info === undefined ? synthesizedInfo(session) : cloneNativeJson(retained.info);
+  if (sessionId != null) {
+    if (info == null) info = {};
+    if (!object(info)) throw new Error('OpenCode session info is not an object');
+    info.id = sessionId;
+  }
+  const cursor = largest([maxTimestamp(info), ...retained.records.flatMap(record => [maxTimestamp(record.info), ...record.parts.map(maxTimestamp)])])
+    ?? (SYNTH_TS_MS - 1n);
+  const prefix = splicedPrefixLengths(session);
+  const result = appendMessages(session, session.messages.slice(prefix.messages), typeof info?.id === 'string' ? info.id : 'ses_new', cursor);
+  if (result.messages.length) {
+    if (info == null) info = {};
+    touchUpdated(info, result.cursor);
+  }
+  return stringifyNativeJsonPretty({ info, messages: [...retained.records, ...result.messages] });
+}

package/session-write-pi.mjs

@@ -0,0 +1,130 @@
+import { nativeInteger, setNativeInteger, parseNativeJson } from './native-json.mjs';
+import { isToolError, toolOutcome } from './message.mjs';
+import { nativeTrim } from './text.mjs';
+import { NATIVE_RESIDUE_KEY, NATIVE_RESIDUE_SUMMARY_KEY } from './session-native-residue.mjs';
+import { nativeResidueEnvelope, nativeResidueSummary } from './session-write-residue.mjs';
+import { SYNTH_TS, SYNTH_TS_MS, replayExcluded, sessionCwd, tryNativeJson, metadataI64, sourceMessageExtension,
+  splicedPrefixLengths, jsonLine, injectFirstJsonLine, synthUuid, messageTimestamp, parseDataUri, parsedJsonField } from './session-write-utils.mjs';
+
+function piHeader(session) {
+  const header = { type: 'session', version: 3, id: session.meta.session_id ?? synthUuid(0),
+    timestamp: session.meta.lineage.created_at ?? SYNTH_TS, cwd: sessionCwd(session) };
+  const parent = session.meta.lineage.parent_session_path;
+  if (parent != null) header.parentSession = parent;
+  const fork = session.meta.lineage.claude_fork_context_ref_raw;
+  if (fork != null) parsedJsonField(header, 'claude_fork_context_ref', fork);
+  return jsonLine(header);
+}
+
+function piContent(message) {
+  if (message.content_parts == null) return message.content ?? '';
+  const parts = [];
+  for (const part of message.content_parts) {
+    if (part?.type === 'text' && typeof part.text === 'string') parts.push({ type: 'text', text: part.text });
+    else if (part?.type === 'image_url') {
+      const image = parseDataUri(part?.image_url?.url);
+      if (image != null) parts.push({ type: 'image', mimeType: image.mimeType, data: image.data });
+    }
+  }
+  return parts;
+}
+
+function assistantContent(message) {
+  const content = [], metadata = message.metadata;
+  if (metadata.thinking != null) {
+    const block = { type: 'thinking', thinking: metadata.thinking };
+    if (metadata.thinking_signature != null) block.thinkingSignature = metadata.thinking_signature;
+    if (metadata.pi_thinking_redacted === 'true') block.redacted = true;
+    content.push(block);
+  }
+  if (message.content) {
+    const block = { type: 'text', text: message.content };
+    if (metadata.pi_text_signature != null) block.textSignature = metadata.pi_text_signature;
+    content.push(block);
+  }
+  for (const call of message.tool_calls ?? []) {
+    const block = { type: 'toolCall', id: call.id, name: call.function.name };
+    const args = nativeTrim(call.function.arguments);
+    if (args === '') block.arguments = {}; else parsedJsonField(block, 'arguments', args, {});
+    if (metadata.pi_thought_signature != null) block.thoughtSignature = metadata.pi_thought_signature;
+    content.push(block);
+  }
+  return content;
+}
+
+function defaultUsage() {
+  return parseNativeJson('{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"totalTokens":0,"cost":{"input":0.0,"output":0.0,"cacheRead":0.0,"cacheWrite":0.0,"total":0.0}}');
+}
+
+function piEntries(session, messages, parent = null, used = new Set()) {
+  let text = '', counter = 0n; const names = new Map();
+  const freshId = () => {
+    for (;;) {
+      counter = BigInt.asUintN(64, counter + 1n);
+      const id = (BigInt.asUintN(64, counter * 0x9e3779b97f4a7c15n) >> 32n).toString(16).padStart(8, '0');
+      if (!used.has(id)) { used.add(id); return id; }
+    }
+  };
+  for (const message of messages) {
+    if (replayExcluded(message)) continue;
+    for (const call of message.tool_calls ?? []) names.set(call.id, call.function.name);
+    const id = freshId(), metadata = message.metadata;
+    let native;
+    switch (message.role) {
+      case 'system': {
+        const content = message.content ?? ''; if (!nativeTrim(content)) continue;
+        native = { role: 'custom', customType: 'supercode_claude_system', content, display: true,
+          details: { claude_system_subtype: metadata.systemSubtype ?? 'local_command' } };
+        break;
+      }
+      case 'user': native = { role: 'user', content: piContent(message) }; break;
+      case 'assistant':
+        native = { role: 'assistant', content: assistantContent(message), api: metadata.pi_api ?? 'anthropic-messages',
+          provider: metadata.pi_provider ?? 'anthropic', model: session.meta.model ?? 'unknown' };
+        parsedJsonField(native, 'usage', metadata.pi_usage, defaultUsage());
+        native.stopReason = metadata.pi_stop_reason ?? 'stop';
+        break;
+      case 'tool': {
+        let content = piContent(message);
+        if (typeof content === 'string') content = content ? [{ type: 'text', text: content }] : [];
+        native = { role: 'toolResult', toolCallId: message.tool_call_id ?? '',
+          toolName: message.name ?? names.get(message.tool_call_id) ?? '', content,
+          isError: metadata.pi_is_error === 'true' || isToolError(message) };
+        break;
+      }
+      default: throw new TypeError(`unknown message role: ${message.role}`);
+    }
+    setNativeInteger(native, 'timestamp', metadataI64(metadata.pi_msg_timestamp) ?? SYNTH_TS_MS);
+    const entry = { type: 'message', id, parentId: parent, timestamp: messageTimestamp(message), message: native };
+    if (message.role === 'tool' && toolOutcome(message) === 'unknown') entry._supercode_tool_outcome = 'unknown';
+    sourceMessageExtension(entry, session.meta.source, message); text += jsonLine(entry); parent = id;
+    if (message.role === 'tool' && message.tool_call_id != null) names.delete(message.tool_call_id);
+  }
+  return text;
+}
+
+export function toPiJsonl(session) {
+  let text = piHeader(session) + piEntries(session, session.messages);
+  const envelope = nativeResidueEnvelope(session.meta);
+  if (envelope != null) {
+    text = injectFirstJsonLine(text, NATIVE_RESIDUE_SUMMARY_KEY, nativeResidueSummary(envelope));
+    text = injectFirstJsonLine(text, NATIVE_RESIDUE_KEY, envelope);
+  }
+  return text;
+}
+
+export function toPiJsonlSpliced(session, sessionId = null) {
+  const prefix = splicedPrefixLengths(session);
+  if (!prefix.raw) return toPiJsonl(session);
+  let text = '', leaf = null; const used = new Set();
+  for (const [index, line] of session.raw.slice(0, prefix.raw).entries()) {
+    const value = tryNativeJson(line);
+    if (!index && value?.type === 'session' && (nativeInteger(value, 'version') !== 3n || sessionId != null)) {
+      setNativeInteger(value, 'version', 3n); if (sessionId != null) value.id = sessionId;
+      text += jsonLine(value); continue;
+    }
+    text += line + '\n';
+    if (typeof value?.id === 'string') { used.add(value.id); leaf = value.id; }
+  }
+  return text + piEntries(session, session.messages.slice(prefix.messages), leaf, used);
+}

package/session-write-residue.mjs

@@ -0,0 +1,19 @@
+import { cloneNativeJson } from './native-json.mjs';
+import { residueRecordsDigest } from './session-native-residue.mjs';
+
+/** The existing verified envelope remains independent of the portable segment cache. */
+export function nativeResidueEnvelope(meta) {
+  const records = meta.codex_provenance.length ? meta.codex_provenance : meta.native_residue;
+  const source = meta.codex_provenance.length ? 'codex' : meta.native_residue_source;
+  return source == null || !records.length ? null : {
+    version: 2, source, records: cloneNativeJson(records), records_sha256: residueRecordsDigest(records),
+  };
+}
+
+export function nativeResidueSummary(envelope) {
+  const records = Array.isArray(envelope.records) ? envelope.records : [];
+  const kinds = [...new Set(records.map(record => record?.kind).filter(kind => typeof kind === 'string'))]
+    .sort((left, right) => Buffer.compare(Buffer.from(left), Buffer.from(right)));
+  return { version: 2, source: envelope.source ?? null, kinds, records: records.length,
+    records_sha256: envelope.records_sha256 ?? null };
+}

package/session-write-utils.mjs

@@ -0,0 +1,77 @@
+// Shared emission helpers. Source bytes and native numeric facts stay separate from synthesis.
+import { cloneNativeJson, parseNativeJson, setNativeJsonText, stringifyNativeJson, stringifyNativeJsonMember } from './native-json.mjs';
+import { usageTimestamp } from './session-usage-time.mjs';
+
+export const SYNTH_TS = '2026-01-01T00:00:00.000Z';
+export const SYNTH_TS_MS = 1_767_225_600_000n;
+export const replayExcluded = message => message.metadata.compacted_out === 'true'
+  || message.metadata.pi_exclude_from_context === 'true';
+export const sessionCwd = session => session.meta.cwd ?? '.';
+export const synthUuid = counter => `00000000-0000-4000-8000-${BigInt(counter).toString(16).padStart(12, '0')}`;
+export const messageTimestamp = message => usageTimestamp(message.metadata.timestamp) == null ? SYNTH_TS : message.metadata.timestamp;
+export const tryNativeJson = text => { try { return parseNativeJson(text); } catch { return undefined; } };
+export function parsedJsonField(destination, key, text, fallback = text) {
+  try { setNativeJsonText(destination, key, text); }
+  catch { Object.defineProperty(destination, key, { value: fallback, enumerable: true, writable: true, configurable: true }); }
+}
+export function metadataI64(value) {
+  if (typeof value !== 'string' || !/^[+-]?[0-9]+$/u.test(value)) return null;
+  const integer = BigInt(value);
+  return integer >= -(1n << 63n) && integer <= (1n << 63n) - 1n ? integer : null;
+}
+
+/** ChatMessage metadata is a native BTreeMap, including numeric-looking keys. */
+export function orderedMessageMetadata(metadata) {
+  const keys = Object.keys(metadata).sort((a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b)));
+  return parseNativeJson(`{${keys.map(key => `${JSON.stringify(key)}:${stringifyNativeJsonMember(metadata, key)}`).join(',')}}`);
+}
+
+/** Full canonical envelope tolerated by foreign writers, separate from stock fields. */
+export function targetMessageExtension(value, message) {
+  value._supercode_grok_message = messageEnvelope(message, 2);
+}
+
+export function messageEnvelope(message, schema) {
+  return {
+    schema, role: message.role, content: message.content,
+    content_parts: cloneNativeJson(message.content_parts), tool_calls: cloneNativeJson(message.tool_calls),
+    tool_call_id: message.tool_call_id, name: message.name, metadata: orderedMessageMetadata(message.metadata),
+  };
+}
+
+export const jsonLine = value => `${stringifyNativeJson(value)}\n`;
+export function injectFirstJsonLine(text, key, extension) {
+  const end = text.indexOf('\n');
+  if (end < 0) return text;
+  const value = tryNativeJson(text.slice(0, end));
+  if (value == null || typeof value !== 'object' || Array.isArray(value)) return text;
+  Object.defineProperty(value, key, { value: extension, writable: true, enumerable: true, configurable: true });
+  return stringifyNativeJson(value) + text.slice(end);
+}
+
+export function inlineDataUrl(part) {
+  const url = part?.image_url?.url;
+  if (typeof url !== 'string' || !url.startsWith('data:')) return null;
+  const separator = url.indexOf(';base64,', 5);
+  return separator < 0 ? null : { mimeType: url.slice(5, separator), data: url.slice(separator + 8) };
+}
+
+/** The native Pi/Claude helper also accepts non-base64 data URIs. */
+export function parseDataUri(url) {
+  if (typeof url !== 'string' || !url.startsWith('data:')) return null;
+  const comma = url.indexOf(',', 5); if (comma < 0) return null;
+  const meta = url.slice(5, comma);
+  return { mimeType: meta.endsWith(';base64') ? meta.slice(0, -7) : meta, data: url.slice(comma + 1) };
+}
+
+/** Carry portable source fields even after a second foreign-container hop. */
+export function sourceMessageExtension(value, source, message) {
+  const portable = Object.keys(message.metadata).some(key => /^(?:gemini|grok|goose)_/u.test(key))
+    || Object.hasOwn(message.metadata, 'codex_custom_tool_call_ids');
+  if (['gemini', 'grok', 'goose'].includes(source) || portable || message.content_parts != null) targetMessageExtension(value, message);
+}
+
+export function splicedPrefixLengths(session) {
+  const messages = Math.min(session.imported_message_count ?? session.messages.length, session.messages.length);
+  return { messages, raw: Math.max(0, session.raw.length - (session.messages.length - messages)) };
+}

package/session-write.d.ts

@@ -0,0 +1,10 @@
+import type { Session, ChatMessage, SessionFormat } from './session-model.js';
+
+/** Full target synthesis. This does not execute or install a vendor session. */
+export function toSessionJsonl(session: Session, format: SessionFormat): string;
+/** Same-format raw prefix plus appended turns; parse loss refuses. */
+export function toSessionJsonlSpliced(session: Session, format: SessionFormat, sessionId?: string | null): string;
+/** Header and original source records, retaining the original trailing-newline flag. */
+export function toNativeJsonl(session: Session): string;
+/** Pure recovery container; caller supplies appended messages, no file is opened. */
+export function toNativeJsonlV2(session: Session, appended: ChatMessage[], fixedTimestamp?: string | null): string;

package/session-write.mjs

@@ -0,0 +1,37 @@
+import { cloneNativeJson } from './native-json.mjs';
+import { SESSION_FORMATS } from './session-model.mjs';
+import { toClaudeCodeJsonl, toClaudeCodeJsonlSpliced } from './session-write-claude.mjs';
+import { toCodexJsonl, toCodexJsonlSpliced } from './session-write-codex.mjs';
+import { toPiJsonl, toPiJsonlSpliced } from './session-write-pi.mjs';
+import { toOpenCodeJson, toOpenCodeJsonSpliced } from './session-write-opencode.mjs';
+import { toGrokJsonl, toGrokJsonlSpliced } from './session-write-grok.mjs';
+import { toGeminiJsonl, toGeminiJsonlSpliced } from './session-write-gemini.mjs';
+import { toGooseJson, toGooseJsonSpliced } from './session-write-goose.mjs';
+
+export { toNativeJsonl, toNativeJsonlV2 } from './session-write-native.mjs';
+const writers = Object.freeze({ claude_code: toClaudeCodeJsonl, codex: toCodexJsonl, pi: toPiJsonl,
+  opencode: toOpenCodeJson, grok: toGrokJsonl, gemini: toGeminiJsonl, goose: toGooseJson });
+const spliceWriters = Object.freeze({ claude_code: toClaudeCodeJsonlSpliced, codex: toCodexJsonlSpliced, pi: toPiJsonlSpliced,
+  opencode: toOpenCodeJsonSpliced, grok: toGrokJsonlSpliced, gemini: toGeminiJsonlSpliced, goose: toGooseJsonSpliced });
+const invalid = message => { throw Object.assign(new Error(message), { code: 'invalid_session' }); };
+function formatWriter(table, format) {
+  if (!SESSION_FORMATS.includes(format)) throw new TypeError(`unknown session format: ${format}`);
+  return table[format];
+}
+
+/** Full synthesis follows each native target's schema; raw recovery is a separate container. */
+export function toSessionJsonl(session, format) { return formatWriter(writers, format)(session); }
+
+/** Refuse parse loss, preserve a same-format source prefix, and synthesize only appended turns. */
+export function toSessionJsonlSpliced(session, format, sessionId = null) {
+  const writer = formatWriter(spliceWriters, format);
+  if (session.parse_error_lines > 0 || session.subagents.some(child => child.parse_error_lines > 0)) {
+    invalid('refusing spliced export because the loaded session contains parse loss');
+  }
+  if (!session.raw.length || format !== session.meta.source) {
+    if (sessionId == null) return toSessionJsonl(session, format);
+    const rewritten = cloneNativeJson(session); rewritten.meta.session_id = sessionId;
+    return toSessionJsonl(rewritten, format);
+  }
+  return writer(session, sessionId);
+}