trajectories 0.0.0 → 0.1.2

package/dist/readers/fx.js

@@ -0,0 +1,573 @@
+import { canonicalFromRecords } from './canonical.js';
+function fail(message) {
+    throw new Error(`FX native session: ${message}`);
+}
+function object(value, label) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        fail(`${label} must be an object`);
+    return value;
+}
+function string(value, label) {
+    if (typeof value !== 'string')
+        fail(`${label} must be a string`);
+    return value;
+}
+function array(value, label) {
+    if (!Array.isArray(value))
+        fail(`${label} must be an array`);
+    return value;
+}
+function integer(value, label) {
+    if (!Number.isSafeInteger(value) || value < 0)
+        fail(`${label} must be a non-negative safe integer`);
+    return value;
+}
+function iso(milliseconds, label) {
+    const value = new Date(milliseconds).toISOString();
+    if (!Number.isFinite(Date.parse(value)))
+        fail(`${label} is invalid`);
+    return value;
+}
+function parseJson(raw, label) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return fail(`${label} is invalid JSON`);
+    }
+    return object(parsed, label);
+}
+function parseIdentity(value, label) {
+    const result = string(value, label);
+    if (!result || new TextEncoder().encode(result).byteLength > 256 || /[\x00-\x1f]/.test(result))
+        fail(`${label} is invalid`);
+    return result;
+}
+function exactKeys(value, allowed, label) {
+    const permitted = new Set(allowed);
+    const unknown = Object.keys(value).find((key) => !permitted.has(key));
+    if (unknown !== undefined)
+        fail(`${label} has unknown field ${JSON.stringify(unknown)}`);
+}
+function parseProvider(value, label) {
+    if (typeof value === 'string') {
+        if (!['gateway', 'codex', 'grok'].includes(value.toLowerCase()))
+            fail(`${label} builtin name is invalid`);
+        return value;
+    }
+    const configured = object(value, label);
+    exactKeys(configured, ['name', 'binding'], label);
+    if (typeof configured.name !== 'string' || !/^[A-Za-z][A-Za-z0-9_-]{0,63}$/.test(configured.name) ||
+        ['gateway', 'codex', 'grok'].includes(configured.name.toLowerCase()) ||
+        typeof configured.binding !== 'string' || !/^[0-9a-f]{64}$/.test(configured.binding)) {
+        fail(`${label} configured binding is invalid`);
+    }
+    return { name: configured.name, binding: configured.binding };
+}
+function parseSession(root) {
+    if (root.schema_version !== 1 && root.schema_version !== 2)
+        fail(`unsupported legacy schema_version ${String(root.schema_version)}`);
+    const id = parseIdentity(root.id, 'id');
+    if (id === '.' || id === '..' || /[/\\]/.test(id))
+        fail('id is unsafe');
+    const workspace = root.workspace_root === undefined || root.workspace_root === null
+        ? undefined : string(root.workspace_root, 'workspace_root');
+    if (workspace !== undefined && !workspace.startsWith('/'))
+        fail('workspace_root must be absolute');
+    string(root.conversation_language, 'conversation_language');
+    const createdMs = integer(root.created_at_ms, 'created_at_ms');
+    const updatedMs = integer(root.updated_at_ms, 'updated_at_ms');
+    const history = array(root.history, 'history');
+    if (integer(root.history_len, 'history_len') !== history.length)
+        fail('history_len does not match history');
+    return { id, workspace, created: iso(createdMs, 'created_at_ms'), updated: iso(updatedMs, 'updated_at_ms'), history };
+}
+function decodeLegacy(root) {
+    const session = parseSession(root);
+    const diagnostics = [];
+    const portabilityIssues = [];
+    const entries = [{
+            record: { role: 'meta', source: 'fx', ...(session.workspace ? { cwd: session.workspace } : {}) },
+            nativeId: 'meta', sourceSequence: 0,
+        }];
+    let sequence = 1;
+    if (session.history.length) {
+        diagnostics.push({
+            code: 'timestamps_synthesized',
+            message: '[trajectories/fx-native-session-json-v1] FX session.json has session and tool-result timestamps but no per-message timestamps; user and assistant record timestamps use the session bounds.',
+        });
+    }
+    const issue = (code, message) => {
+        diagnostics.push({ code: 'noise_record_dropped', message: `[trajectories/fx-native-session-json-v1:${code}] ${message}` });
+        portabilityIssues.push(message);
+    };
+    const emit = (record, nativeId, sourceTimestamp) => {
+        entries.push({ record, nativeId, sourceTimestamp, sourceSequence: sequence++ });
+    };
+    for (const [turnIndex, value] of session.history.entries()) {
+        const turn = object(value, `history[${turnIndex}]`);
+        const kind = string(turn.kind, `history[${turnIndex}].kind`);
+        if (kind === 'compacted_summary') {
+            issue('fx-unsupported-compaction', `history[${turnIndex}] is a compacted summary whose removed turns cannot be reconstructed.`);
+            continue;
+        }
+        if (kind === 'interrupted') {
+            issue('fx-unsupported-interrupted-turn', `history[${turnIndex}] is interrupted and is not a completed portable turn.`);
+            continue;
+        }
+        if (kind !== 'assistant') {
+            issue('fx-unsupported-history-kind', `history[${turnIndex}] has unsupported kind ${JSON.stringify(kind)}.`);
+            continue;
+        }
+        const user = object(turn.user, `history[${turnIndex}].user`);
+        const userText = string(user.text, `history[${turnIndex}].user.text`);
+        const images = user.images === undefined ? [] : array(user.images, `history[${turnIndex}].user.images`);
+        if (images.length)
+            issue('fx-unsupported-images', `history[${turnIndex}] contains ${images.length} image attachment(s).`);
+        emit({ role: 'user', content: userText, timestamp: session.created }, `turn:${turnIndex}:user`, session.created);
+        const execution = turn.execution;
+        if (execution !== undefined && execution !== null) {
+            const memory = object(execution, `history[${turnIndex}].execution`);
+            const schema = integer(memory.schema_version ?? 1, `history[${turnIndex}].execution.schema_version`);
+            if (schema < 1 || schema > 3) {
+                issue('fx-unsupported-execution-schema', `history[${turnIndex}] uses execution schema ${schema}; this codec supports presentation schemas 1 through 3.`);
+            }
+            else {
+                const files = memory.files === undefined ? [] : array(memory.files, `history[${turnIndex}].execution.files`);
+                const steering = memory.steering === undefined ? [] : array(memory.steering, `history[${turnIndex}].execution.steering`);
+                if (files.length)
+                    issue('fx-unsupported-file-evidence', `history[${turnIndex}] contains ${files.length} execution file-evidence record(s).`);
+                if (steering.length)
+                    issue('fx-unsupported-steering', `history[${turnIndex}] contains ${steering.length} steering record(s).`);
+                const steps = memory.tool_steps === undefined ? [] : array(memory.tool_steps, `history[${turnIndex}].execution.tool_steps`);
+                for (const [stepIndex, stepValue] of steps.entries()) {
+                    const step = object(stepValue, `history[${turnIndex}].execution.tool_steps[${stepIndex}]`);
+                    const calls = array(step.tool_calls, `history[${turnIndex}].execution.tool_steps[${stepIndex}].tool_calls`);
+                    const results = array(step.tool_results, `history[${turnIndex}].execution.tool_steps[${stepIndex}].tool_results`);
+                    const normalizedCalls = [];
+                    const callNames = new Map();
+                    let portableStep = true;
+                    for (const [callIndex, callValue] of calls.entries()) {
+                        const call = object(callValue, `history[${turnIndex}].execution.tool_steps[${stepIndex}].tool_calls[${callIndex}]`);
+                        const id = string(call.id, `tool call ${callIndex} id`);
+                        const name = string(call.name, `tool call ${callIndex} name`);
+                        const args = string(call.arguments_json, `tool call ${callIndex} arguments_json`);
+                        let parsedArgs;
+                        try {
+                            parsedArgs = JSON.parse(args);
+                        }
+                        catch {
+                            parsedArgs = null;
+                        }
+                        if (parsedArgs === null || typeof parsedArgs !== 'object' || Array.isArray(parsedArgs)) {
+                            issue('fx-unsupported-tool-arguments', `history[${turnIndex}] tool call ${JSON.stringify(id)} has arguments that are not a JSON object.`);
+                            portableStep = false;
+                        }
+                        if (!id || !name || callNames.has(id))
+                            fail(`history[${turnIndex}] has an invalid or duplicate tool call id`);
+                        callNames.set(id, name);
+                        normalizedCalls.push({ id, name, args });
+                        if (call.provider_result !== undefined && call.provider_result !== null) {
+                            issue('fx-unsupported-provider-result', `history[${turnIndex}] tool call ${JSON.stringify(id)} contains provider replay state.`);
+                        }
+                    }
+                    const normalizedResults = [];
+                    const seenResults = new Set();
+                    for (const [resultIndex, resultValue] of results.entries()) {
+                        const result = object(resultValue, `history[${turnIndex}].execution.tool_steps[${stepIndex}].tool_results[${resultIndex}]`);
+                        const id = string(result.tool_call_id, `tool result ${resultIndex} tool_call_id`);
+                        const name = string(result.tool_name, `tool result ${resultIndex} tool_name`);
+                        const content = string(result.output, `tool result ${resultIndex} output`);
+                        if (!callNames.has(id) || callNames.get(id) !== name || seenResults.has(id)) {
+                            issue('fx-incomplete-tool-step', `history[${turnIndex}] tool result ${JSON.stringify(id)} is orphaned, duplicated, or names a different tool.`);
+                            portableStep = false;
+                        }
+                        seenResults.add(id);
+                        if (result.status !== 'success' && result.status !== 'failure')
+                            fail(`tool result ${JSON.stringify(id)} has invalid status`);
+                        const createdMs = integer(result.created_at_ms, `tool result ${JSON.stringify(id)} created_at_ms`);
+                        normalizedResults.push({ id, content, ok: result.status === 'success', timestamp: iso(createdMs, 'tool result timestamp') });
+                        const permission = result.permission_feedback === undefined ? [] : array(result.permission_feedback, `tool result ${JSON.stringify(id)} permission_feedback`);
+                        if (permission.length || result.provider_native === true || result.truncated === true || result.output_handle != null || result.preview != null || result.committed_file_presentation != null) {
+                            issue('fx-unsupported-tool-result-metadata', `history[${turnIndex}] tool result ${JSON.stringify(id)} contains runtime-only result metadata.`);
+                        }
+                    }
+                    if (seenResults.size !== callNames.size || [...callNames.keys()].some((id) => !seenResults.has(id))) {
+                        issue('fx-incomplete-tool-step', `history[${turnIndex}] execution step ${stepIndex} does not contain one terminal result per call.`);
+                        portableStep = false;
+                    }
+                    if (!portableStep)
+                        continue;
+                    const assistant = step.assistant === undefined || step.assistant === null
+                        ? null : string(step.assistant, `history[${turnIndex}].execution.tool_steps[${stepIndex}].assistant`);
+                    if (assistant)
+                        emit({ role: 'assistant', content: assistant, timestamp: session.updated }, `turn:${turnIndex}:step:${stepIndex}:assistant`, session.updated);
+                    if (normalizedCalls.length)
+                        emit({ role: 'assistant', content: null, tool_calls: normalizedCalls, timestamp: session.updated }, `turn:${turnIndex}:step:${stepIndex}:calls`, session.updated);
+                    for (const result of normalizedResults) {
+                        emit({ role: 'tool', tool_call_id: result.id, content: result.content, ok: result.ok, timestamp: result.timestamp }, `turn:${turnIndex}:step:${stepIndex}:result:${result.id}`, result.timestamp);
+                    }
+                }
+            }
+        }
+        const assistant = string(turn.assistant, `history[${turnIndex}].assistant`);
+        emit({ role: 'assistant', content: assistant, timestamp: session.updated }, `turn:${turnIndex}:assistant`, session.updated);
+    }
+    return { session, entries, diagnostics, portabilityIssues };
+}
+function parseV4Session(root) {
+    const allowed = new Set(['schema_version', 'id', 'origin_workspace_root', 'workspace_root', 'created_at_ms', 'updated_at_ms', 'conversation_language', 'provider', 'model', 'effort', 'fast_mode', 'ultrafast_mode', 'title', 'subagent_child']);
+    if (Object.keys(root).some((key) => !allowed.has(key)))
+        fail('session.json schema 4 has unknown fields');
+    const id = parseIdentity(root.id, 'id');
+    if (id === '.' || id === '..' || /[/\\]/.test(id))
+        fail('id is unsafe');
+    const origin = string(root.origin_workspace_root, 'origin_workspace_root');
+    const workspace = string(root.workspace_root, 'workspace_root');
+    if (!origin.startsWith('/') || !workspace.startsWith('/'))
+        fail('workspace roots must be absolute');
+    const createdMs = integer(root.created_at_ms, 'created_at_ms');
+    const updatedMs = integer(root.updated_at_ms, 'updated_at_ms');
+    if (updatedMs < createdMs)
+        fail('updated_at_ms precedes created_at_ms');
+    string(root.conversation_language, 'conversation_language');
+    const provider = parseProvider(root.provider, 'provider');
+    const model = string(root.model, 'model');
+    if (!model)
+        fail('model is empty');
+    string(root.effort, 'effort');
+    if (typeof root.fast_mode !== 'boolean')
+        fail('fast_mode must be a boolean');
+    if (root.ultrafast_mode !== undefined && root.ultrafast_mode !== null && typeof root.ultrafast_mode !== 'boolean')
+        fail('ultrafast_mode must be a boolean or null');
+    if (root.title !== undefined && root.title !== null && (typeof root.title !== 'string' || !root.title))
+        fail('title is invalid');
+    if (root.subagent_child !== undefined && typeof root.subagent_child !== 'boolean')
+        fail('subagent_child must be a boolean');
+    return { id, workspace, model, provider, created: iso(createdMs, 'created_at_ms'), updated: iso(updatedMs, 'updated_at_ms'), history: [] };
+}
+function decodeV4(root, companions) {
+    const session = parseV4Session(root);
+    if (companions.events === undefined)
+        fail('schema_version 4 requires sibling events.jsonl');
+    const diagnostics = [];
+    const portabilityIssues = [];
+    const entries = [{
+            record: { role: 'meta', source: 'fx', ...(session.workspace ? { cwd: session.workspace } : {}), ...(session.model ? { model: session.model } : {}) },
+            nativeId: 'meta', sourceSequence: 0,
+        }];
+    const pending = new Map();
+    let pendingReplay = null;
+    let turnEntries = [];
+    let turnOpen = false;
+    let toolResultsStarted = false;
+    let expectedSeq = 1;
+    let latestCheckpointCoverage = 0;
+    const note = (code, message, blocksPortability = false) => {
+        diagnostics.push({ code: 'noise_record_dropped', message: `[trajectories/fx-native-session-json-v4:${code}] ${message}` });
+        if (blocksPortability)
+            portabilityIssues.push(message);
+    };
+    const emit = (record, nativeId, timestamp, sequence) => {
+        turnEntries.push({ record, nativeId, sourceTimestamp: timestamp, sourceSequence: sequence });
+    };
+    const finishReplayAssociation = () => {
+        if (!pendingReplay)
+            return;
+        const replay = pendingReplay;
+        pendingReplay = null;
+        const matches = replay.callIds.length === replay.seenCallIds.length &&
+            replay.callIds.every((id, index) => id === replay.seenCallIds[index]);
+        if (!matches) {
+            note('fx-unsupported-provider-replay', `assistant event ${replay.seq} provider replay call association does not exactly match its following tool-call batch.`, true);
+            return;
+        }
+        turnEntries.splice(replay.insertionIndex, 0, ...replay.reasoning);
+        note('fx-provider-replay-projected', `assistant event ${replay.seq} provider replay contains visible reasoning projected into canonical history; its original bytes remain in events.jsonl.`);
+    };
+    if (!companions.events.endsWith('\n'))
+        fail('events.jsonl final frame is unterminated');
+    const lines = companions.events.split('\n');
+    lines.pop();
+    for (const [lineIndex, line] of lines.entries()) {
+        if (!line.trim())
+            fail(`events.jsonl line ${lineIndex + 1} is blank`);
+        const envelope = parseJson(line, `events.jsonl line ${lineIndex + 1}`);
+        exactKeys(envelope, ['schema_version', 'seq', 'timestamp_ms', 'event'], `events.jsonl line ${lineIndex + 1}`);
+        const eventSchema = integer(envelope.schema_version, `events.jsonl line ${lineIndex + 1} schema_version`);
+        if (eventSchema < 1 || eventSchema > 3)
+            fail(`events.jsonl line ${lineIndex + 1} has unsupported conversation schema ${eventSchema}`);
+        const seq = integer(envelope.seq, `events.jsonl line ${lineIndex + 1} seq`);
+        if (seq !== expectedSeq)
+            fail(`events.jsonl sequence ${seq} is not contiguous after ${expectedSeq - 1}`);
+        expectedSeq += 1;
+        const timestampMs = integer(envelope.timestamp_ms, `events.jsonl line ${lineIndex + 1} timestamp_ms`);
+        const timestamp = iso(timestampMs, `events.jsonl line ${lineIndex + 1} timestamp_ms`);
+        const event = object(envelope.event, `events.jsonl line ${lineIndex + 1} event`);
+        const kinds = Object.keys(event);
+        if (kinds.length !== 1)
+            fail(`events.jsonl line ${lineIndex + 1} must contain exactly one event variant`);
+        const kind = kinds[0];
+        const value = object(event[kind], `events.jsonl line ${lineIndex + 1} ${kind}`);
+        if (pendingReplay && kind !== 'tool_call')
+            finishReplayAssociation();
+        if (kind === 'user') {
+            exactKeys(value, ['text', 'images', 'work_id'], `user event ${seq}`);
+            if (turnOpen || pending.size)
+                fail(`user event ${seq} begins before the previous turn completed`);
+            const content = string(value.text, `user event ${seq} text`);
+            const images = value.images === undefined ? [] : array(value.images, `user event ${seq} images`);
+            if (images.length)
+                note('fx-unsupported-images', `user event ${seq} contains ${images.length} image attachment(s).`, true);
+            if (value.work_id != null)
+                note('fx-work-id', `user event ${seq} carries native work provenance retained in events.jsonl.`);
+            turnOpen = true;
+            toolResultsStarted = false;
+            turnEntries = [];
+            emit({ role: 'user', content, timestamp }, `event:${seq}:user`, timestamp, seq);
+            continue;
+        }
+        if (kind === 'context_checkpoint') {
+            exactKeys(value, ['covers_through_seq', 'summary'], `context_checkpoint event ${seq}`);
+            const coverage = integer(value.covers_through_seq, `context_checkpoint event ${seq} covers_through_seq`);
+            if (coverage < latestCheckpointCoverage || coverage >= seq || [...pending.values()].some((call) => call.seq <= coverage)) {
+                fail(`context_checkpoint event ${seq} has invalid coverage`);
+            }
+            latestCheckpointCoverage = coverage;
+            string(value.summary, `context_checkpoint event ${seq} summary`);
+            note('fx-unsupported-compaction', `context_checkpoint event ${seq} replaces earlier active context with a summary.`, true);
+            continue;
+        }
+        if (!turnOpen)
+            fail(`${kind} event ${seq} occurs outside a turn`);
+        if (kind === 'assistant') {
+            exactKeys(value, ['text', 'provider_replay', 'standalone_response'], `assistant event ${seq}`);
+            if (pending.size)
+                fail(`assistant event ${seq} occurs before all tool results`);
+            const content = string(value.text, `assistant event ${seq} text`);
+            if (eventSchema === 1 && (!content || value.provider_replay != null))
+                fail(`assistant event ${seq} violates conversation schema 1`);
+            if (value.provider_replay != null) {
+                const replay = object(value.provider_replay, `assistant event ${seq} provider_replay`);
+                exactKeys(replay, ['source', 'parts_json'], `assistant event ${seq} provider_replay`);
+                const replaySource = object(replay.source, `assistant event ${seq} provider_replay source`);
+                exactKeys(replaySource, ['provider', 'model'], `assistant event ${seq} provider_replay source`);
+                const replayModel = parseIdentity(replaySource.model, `assistant event ${seq} provider replay model`);
+                const replayProvider = parseProvider(replaySource.provider, `assistant event ${seq} provider replay provider`);
+                const partsRaw = string(replay.parts_json, `assistant event ${seq} provider replay parts_json`);
+                if (!partsRaw)
+                    fail(`assistant event ${seq} provider replay parts_json is empty`);
+                const configuredSource = typeof session.provider !== 'string' && typeof replayProvider !== 'string' &&
+                    session.provider?.name === replayProvider.name && session.provider.binding === replayProvider.binding && session.model === replayModel;
+                let parts = null;
+                let canonicalParts = false;
+                if (configuredSource) {
+                    try {
+                        const parsed = JSON.parse(partsRaw);
+                        if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                            parts = parsed;
+                            // The pinned chat adapter emits compact JSON and rejects duplicate
+                            // keys. Re-encoding equality keeps this narrow projection from
+                            // accepting bytes the native replay parser would refuse.
+                            canonicalParts = JSON.stringify(parsed) === partsRaw;
+                        }
+                    }
+                    catch {
+                        // Conversation events deliberately retain provider replay as opaque
+                        // UTF-8. Only the configured chat subset below interprets it.
+                    }
+                }
+                const allowedPartKeys = new Set(['reasoning', 'reasoning_content', 'reasoning_details', '_tool_call_ids']);
+                const knownKeys = parts !== null && Object.keys(parts).every((key) => allowedPartKeys.has(key));
+                const rawCallIds = parts?._tool_call_ids;
+                const callIds = Array.isArray(rawCallIds) && rawCallIds.length <= 256 && rawCallIds.every((id) => typeof id === 'string' && id.length > 0 && new TextEncoder().encode(id).byteLength <= 256 && !/[\x00-\x1f]/.test(id))
+                    ? rawCallIds : null;
+                const distinctCallIds = callIds === null ? null : new Set(callIds);
+                const reasoningFields = ['reasoning', 'reasoning_content'];
+                const reasoningShape = parts !== null && reasoningFields.every((field) => parts[field] === undefined || parts[field] === null || typeof parts[field] === 'string');
+                const visible = parts === null || !reasoningShape ? [] : reasoningFields.flatMap((field) => {
+                    const part = parts[field];
+                    return typeof part === 'string' && part ? [{ field, content: part }] : [];
+                });
+                const portableSubset = configuredSource && new TextEncoder().encode(partsRaw).byteLength <= 4 * 1024 * 1024 &&
+                    parts !== null && canonicalParts && knownKeys && callIds !== null &&
+                    distinctCallIds?.size === callIds.length && reasoningShape && parts.reasoning_details == null && visible.length === 1;
+                if (!portableSubset) {
+                    note('fx-unsupported-provider-replay', `assistant event ${seq} carries provider replay state outside the lossless configured-provider visible-reasoning subset.`, true);
+                }
+                else {
+                    pendingReplay = {
+                        seq,
+                        callIds: callIds,
+                        seenCallIds: [],
+                        insertionIndex: turnEntries.length,
+                        reasoning: visible.map(({ field, content: reasoning }) => ({
+                            record: { role: 'reasoning', content: reasoning, timestamp },
+                            nativeId: `event:${seq}:provider_replay:${field}`,
+                            sourceTimestamp: timestamp,
+                            sourceSequence: seq,
+                        })),
+                    };
+                }
+            }
+            if (value.standalone_response !== undefined && typeof value.standalone_response !== 'boolean')
+                fail(`assistant event ${seq} standalone_response must be a boolean`);
+            if (value.standalone_response === true)
+                finishReplayAssociation();
+            if (content)
+                emit({ role: 'assistant', content, timestamp }, `event:${seq}:assistant`, timestamp, seq);
+            toolResultsStarted = false;
+            continue;
+        }
+        if (kind === 'tool_call') {
+            exactKeys(value, ['call_id', 'tool_name', 'arguments_json', 'argument_integrity', 'provisional_id', 'provider_result', 'final_identity', 'provenance'], `tool_call event ${seq}`);
+            const id = parseIdentity(value.call_id, `tool_call event ${seq} call_id`);
+            const name = parseIdentity(value.tool_name, `tool_call event ${seq} tool_name`);
+            if (toolResultsStarted)
+                fail(`tool_call event ${seq} occurs after results started for its assistant step`);
+            if (pending.has(id))
+                fail(`tool_call event ${seq} duplicates call ${JSON.stringify(id)}`);
+            if (pendingReplay)
+                pendingReplay.seenCallIds.push(id);
+            const args = string(value.arguments_json, `tool_call event ${seq} arguments_json`);
+            let parsedArgs;
+            try {
+                parsedArgs = JSON.parse(args);
+            }
+            catch {
+                parsedArgs = null;
+            }
+            if (parsedArgs === null || typeof parsedArgs !== 'object' || Array.isArray(parsedArgs))
+                fail(`tool_call event ${seq} arguments_json is not a JSON object`);
+            const argumentIntegrity = string(value.argument_integrity ?? 'valid', `tool_call event ${seq} argument_integrity`);
+            const finalIdentity = string(value.final_identity ?? 'valid', `tool_call event ${seq} final_identity`);
+            const provenance = string(value.provenance ?? 'fx_local', `tool_call event ${seq} provenance`);
+            if (argumentIntegrity !== 'valid')
+                note('fx-tool-argument-integrity', `tool_call event ${seq} marks arguments as ${JSON.stringify(argumentIntegrity)}.`, true);
+            if (finalIdentity !== 'valid')
+                note('fx-tool-final-identity', `tool_call event ${seq} marks its final identity as ${JSON.stringify(finalIdentity)}.`, true);
+            if (value.provisional_id != null || value.provider_result != null || provenance !== 'fx_local') {
+                note('fx-tool-call-provenance', `tool_call event ${seq} carries native execution provenance retained in events.jsonl.`);
+            }
+            pending.set(id, { name, seq });
+            emit({ role: 'assistant', content: null, tool_calls: [{ id, name, args }], timestamp }, `event:${seq}:tool_call:${id}`, timestamp, seq);
+            continue;
+        }
+        if (kind === 'tool_result') {
+            exactKeys(value, ['call_id', 'tool_name', 'status', 'artifact_ref', 'tool_image_handle', 'output_bytes', 'stored_bytes', 'completeness', 'preview', 'provider_native', 'review_feedback', 'created_at_ms', 'permission_feedback', 'committed_file_presentation', 'command_replay_ref', 'command_replay_bytes', 'command_process_presentation', 'terminal_action_presentation'], `tool_result event ${seq}`);
+            const id = parseIdentity(value.call_id, `tool_result event ${seq} call_id`);
+            toolResultsStarted = true;
+            const name = parseIdentity(value.tool_name, `tool_result event ${seq} tool_name`);
+            if (pending.get(id)?.name !== name)
+                fail(`tool_result event ${seq} is orphaned or names a different tool`);
+            const status = string(value.status, `tool_result event ${seq} status`);
+            if (status !== 'success' && status !== 'failure')
+                fail(`tool_result event ${seq} has invalid status`);
+            const providerNative = value.provider_native ?? false;
+            const reviewFeedback = value.review_feedback ?? false;
+            if (typeof providerNative !== 'boolean')
+                fail(`tool_result event ${seq} provider_native must be a boolean`);
+            if (typeof reviewFeedback !== 'boolean')
+                fail(`tool_result event ${seq} review_feedback must be a boolean`);
+            if (reviewFeedback && (status !== 'failure' || providerNative))
+                fail(`tool_result event ${seq} has invalid review_feedback state`);
+            const artifactRef = parseIdentity(value.artifact_ref, `tool_result event ${seq} artifact_ref`);
+            if (artifactRef === '.' || artifactRef === '..' || /[/\\]/.test(artifactRef))
+                fail(`tool_result event ${seq} artifact_ref is unsafe`);
+            const content = companions.toolResults && Object.hasOwn(companions.toolResults, artifactRef)
+                ? companions.toolResults[artifactRef] : undefined;
+            if (typeof content !== 'string')
+                fail(`tool_result event ${seq} requires tool-results/${artifactRef}; preview fallback is not lossless`);
+            const storedBytes = integer(value.stored_bytes, `tool_result event ${seq} stored_bytes`);
+            if (new TextEncoder().encode(content).byteLength !== storedBytes)
+                fail(`tool-results/${artifactRef} byte length does not match event ${seq}`);
+            if (value.output_bytes !== undefined && value.output_bytes !== null)
+                integer(value.output_bytes, `tool_result event ${seq} output_bytes`);
+            const completeness = string(value.completeness, `tool_result event ${seq} completeness`);
+            if (!['complete', 'partial', 'unknown'].includes(completeness))
+                fail(`tool_result event ${seq} has invalid completeness`);
+            if (completeness !== 'complete')
+                note('fx-result-completeness', `tool_result event ${seq} records ${JSON.stringify(completeness)} completeness; the exact stored artifact is retained.`);
+            const permission = value.permission_feedback === undefined ? [] : array(value.permission_feedback, `tool_result event ${seq} permission_feedback`);
+            if (permission.some((feedback) => typeof feedback !== 'string'))
+                fail(`tool_result event ${seq} permission_feedback must contain only strings`);
+            if (value.preview !== undefined && value.preview !== null && typeof value.preview !== 'string')
+                fail(`tool_result event ${seq} preview must be a string or null`);
+            if (typeof value.preview === 'string' && new TextEncoder().encode(value.preview).byteLength > 4096)
+                fail(`tool_result event ${seq} preview is too large`);
+            if (value.tool_image_handle !== undefined && value.tool_image_handle !== null)
+                parseIdentity(value.tool_image_handle, `tool_result event ${seq} tool_image_handle`);
+            if (permission.length || providerNative || reviewFeedback || value.preview != null || value.committed_file_presentation != null) {
+                note('fx-tool-result-provenance', `tool_result event ${seq} carries native result provenance retained in events.jsonl.`);
+            }
+            if (value.tool_image_handle != null)
+                note('fx-unsupported-tool-image', `tool_result event ${seq} references a native tool image.`, true);
+            if (value.command_replay_ref != null || value.command_replay_bytes != null || value.command_process_presentation != null || value.terminal_action_presentation != null) {
+                if ((value.command_replay_ref == null) !== (value.command_replay_bytes == null))
+                    fail(`tool_result event ${seq} has an incomplete command replay pair`);
+                note('fx-unsupported-command-replay', `tool_result event ${seq} carries command replay or terminal state.`, true);
+            }
+            integer(value.created_at_ms ?? 0, `tool_result event ${seq} created_at_ms`);
+            pending.delete(id);
+            emit({ role: 'tool', tool_call_id: id, content, ok: status === 'success', timestamp }, `event:${seq}:tool_result:${id}`, timestamp, seq);
+            continue;
+        }
+        if (kind === 'turn_completed') {
+            exactKeys(value, ['files', 'turn_summary'], `turn_completed event ${seq}`);
+            if (pending.size)
+                fail(`turn_completed event ${seq} has unresolved tool calls`);
+            const files = value.files === undefined ? [] : array(value.files, `turn_completed event ${seq} files`);
+            if (files.length || value.turn_summary != null)
+                note('fx-turn-provenance', `turn_completed event ${seq} carries native file evidence or a turn summary retained in events.jsonl.`);
+            entries.push(...turnEntries);
+            turnEntries = [];
+            turnOpen = false;
+            toolResultsStarted = false;
+            continue;
+        }
+        if (kind === 'steering') {
+            exactKeys(value, ['text'], `steering event ${seq}`);
+            string(value.text, `steering event ${seq} text`);
+            note('fx-unsupported-steering', `steering event ${seq} affects active context and has no canonical role.`, true);
+            continue;
+        }
+        if (kind === 'interrupted') {
+            exactKeys(value, ['reason', 'partial_text', 'command_replay_ref', 'command_replay_bytes', 'command_artifact_ref', 'files', 'turn_summary', 'cancellation_origin'], `interrupted event ${seq}`);
+            note('fx-unsupported-interrupted-turn', `interrupted event ${seq} does not complete a portable turn.`, true);
+            pending.clear();
+            turnEntries = [];
+            turnOpen = false;
+            toolResultsStarted = false;
+            continue;
+        }
+        fail(`events.jsonl line ${lineIndex + 1} has unknown event variant ${JSON.stringify(kind)}`);
+    }
+    finishReplayAssociation();
+    if (turnOpen || pending.size) {
+        portabilityIssues.push('events.jsonl ends with an incomplete turn.');
+        turnEntries = [];
+    }
+    return { session, entries, diagnostics, portabilityIssues };
+}
+function decode(raw, companions) {
+    const root = parseJson(raw, 'session.json');
+    if (root.schema_version === 1 || root.schema_version === 2)
+        return decodeLegacy(root);
+    if (root.schema_version === 4)
+        return decodeV4(root, companions);
+    if (root.schema_version === 3)
+        fail('schema_version 3 is the event_log_v1 manifest and requires its generation log/checkpoint reader');
+    return fail(`unsupported schema_version ${String(root.schema_version)}`);
+}
+/** Parse a native FX session for archival inspection, retaining unsupported-feature diagnostics. */
+export function readFx(raw, companions = {}) {
+    const decoded = decode(raw, companions);
+    return canonicalFromRecords('fx', decoded.session.id, decoded.entries, decoded.diagnostics);
+}
+/** Fail closed before converting FX history whose native context cannot be represented completely. */
+export function assertFxPortable(raw, companions = {}) {
+    const issues = decode(raw, companions).portabilityIssues;
+    if (issues.length)
+        throw new Error(`FX native session is not portable: ${issues.join(' ')}`);
+}

package/dist/readers/github-copilot.d.ts

@@ -0,0 +1,8 @@
+import { type CanonicalResult } from '@letta-ai/trajectory';
+/** Extend Letta's archive projection with native direct prompts and system text.
+ * A hook is only a duplicate when its next submission carries the same prompt.
+ * Repeated user messages remain distinct and keep their own native identities.
+ */
+export declare function readGitHubCopilot(raw: string): CanonicalResult;
+/** Reject native state that the supported text projection cannot continue. */
+export declare function assertGitHubCopilotHistory(raw: string): void;