trajectories 0.0.0 → 0.1.2

package/dist/convert.d.ts

@@ -0,0 +1,31 @@
+import { type NormalizedRecord } from '@letta-ai/trajectory';
+import { type Harness, type Snapshot, type NativeExport, type WriteOptions } from './types.js';
+export declare const sha256: (value: string) => string;
+export interface SnapshotEvidence {
+    harness: Harness;
+    raw: string;
+    nativeSessionId?: string;
+    attachments?: readonly NonNullable<Snapshot['attachments']>[number][];
+}
+/** Reconstruct captured native evidence without reading a path or writing an archive. */
+export declare function snapshotFromEvidence(input: SnapshotEvidence): Snapshot;
+/** Read an in-memory generated export through the same evidence contract as capture. */
+export declare function readNativeExportSnapshot(native: NativeExport): Snapshot;
+export declare function readSnapshot(input: {
+    harness: Harness;
+    path?: string;
+    transcript?: string;
+    /** Select one native session in a database, or verify a file's native identity. */
+    nativeSessionId?: string;
+    /** Python containing the native Deep Agents checkpoint dependencies. */
+    pythonExecutable?: string;
+}): Promise<Snapshot>;
+export declare function assertSnapshot(snapshot: Snapshot): void;
+/** Complete portable context, stricter than an archive's integrity-only validation. */
+export declare function assertPortableSnapshot(snapshot: Snapshot): void;
+export declare function convert(snapshot: Snapshot, target: Harness, options: WriteOptions): NativeExport;
+/** Internal managed-store codec; its caller freezes the destination identity and time. */
+export declare function convertManaged(snapshot: Snapshot, target: Harness, options: WriteOptions, entropySeed: string, records?: readonly NormalizedRecord[]): NativeExport;
+/** Write only to a new directory; an existing destination is never modified. */
+export declare function writeNativeExport(output: NativeExport, directory: string): Promise<void>;
+export declare function writeSnapshot(snapshot: Snapshot, target: Harness, options: WriteOptions): Promise<NativeExport>;

package/dist/convert.js

@@ -0,0 +1,431 @@
+import { createHash } from 'node:crypto';
+import { readFile, mkdir, writeFile, realpath } from 'node:fs/promises';
+import { resolve, dirname, relative, isAbsolute, sep, join, basename } from 'node:path';
+import { normalizeToCanonical, validateTranscript } from '@letta-ai/trajectory';
+import { HARNESSES } from './types.js';
+import { createSeededNativeEntropy } from './writers/entropy.js';
+import { writePi } from './writers/pi.js';
+import { writeOmp } from './writers/omp.js';
+import { writeCodex } from './writers/codex.js';
+import { writeClaudeCode } from './writers/claude-code.js';
+import { writeOpenCode } from './writers/opencode.js';
+import { writeGrokBuild } from './writers/grok-build.js';
+import { writeCursor } from './writers/cursor.js';
+import { writeDeepAgents } from './writers/deepagents.js';
+import { writeGitHubCopilot } from './writers/github-copilot.js';
+import { writeCline } from './writers/cline.js';
+import { writeFx } from './writers/fx.js';
+import { normalizeGrokBuild } from './readers/grok-build.js';
+import { readCursor, readCursorNative } from './readers/cursor.js';
+import { readDeepAgents, readDeepAgentsSeed } from './readers/deepagents.js';
+import { readCline } from './readers/cline.js';
+import { readGitHubCopilot } from './readers/github-copilot.js';
+import { readFx } from './readers/fx.js';
+import { assertPortableHistory } from './readers/guards.js';
+import { projectPiProviderContext, normalizePiArchive } from './readers/pi-context.js';
+import { piCompactedContext } from './readers/pi-compaction.js';
+import { toolNames } from './writers/helpers.js';
+export const sha256 = (value) => createHash('sha256').update(value).digest('hex');
+function exactUtf8(bytes, label) {
+    const content = bytes.toString('utf8');
+    if (!Buffer.from(content, 'utf8').equals(bytes))
+        throw new Error(`${label} is not valid UTF-8.`);
+    return content;
+}
+function fxArtifactRefs(events) {
+    const refs = new Set();
+    for (const [index, line] of events.split('\n').entries()) {
+        if (!line)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            throw new Error(`FX events.jsonl line ${index + 1} is invalid JSON.`);
+        }
+        const ref = parsed?.event?.tool_result?.artifact_ref;
+        if (ref === undefined)
+            continue;
+        if (typeof ref !== 'string' || !ref || basename(ref) !== ref || ref === '.' || ref === '..' || /[\x00-\x1f]/.test(ref)) {
+            throw new Error(`FX events.jsonl line ${index + 1} has an unsafe tool-result artifact_ref.`);
+        }
+        refs.add(ref);
+    }
+    return [...refs];
+}
+function fxCompanionsFromAttachments(attachments) {
+    let events;
+    const toolResults = Object.create(null);
+    for (const attachment of attachments) {
+        if (attachment.name === 'events.jsonl') {
+            if (events !== undefined)
+                throw new Error('FX snapshot has duplicate events.jsonl attachments.');
+            events = attachment.content;
+        }
+        else if (attachment.name.startsWith('tool-results/')) {
+            const ref = attachment.name.slice('tool-results/'.length);
+            if (!ref || basename(ref) !== ref || Object.hasOwn(toolResults, ref))
+                throw new Error('FX snapshot has an unsafe or duplicate tool-result attachment.');
+            toolResults[ref] = attachment.content;
+        }
+    }
+    return { ...(events === undefined ? {} : { events }), ...(Object.keys(toolResults).length ? { toolResults } : {}) };
+}
+async function captureFxCompanions(sessionPath, raw) {
+    let root;
+    try {
+        root = JSON.parse(raw);
+    }
+    catch {
+        return { attachments: [], companions: {} };
+    }
+    if (root?.schema_version !== 4)
+        return { attachments: [], companions: {} };
+    const sessionDirectory = await realpath(dirname(sessionPath));
+    const eventsPath = await realpath(join(sessionDirectory, 'events.jsonl'));
+    if (relative(sessionDirectory, eventsPath) !== 'events.jsonl')
+        throw new Error('FX events.jsonl resolves outside its native session directory.');
+    const events = exactUtf8(await readFile(eventsPath), 'FX events.jsonl');
+    const attachments = [{ name: 'events.jsonl', content: events, sha256: sha256(events) }];
+    const refs = fxArtifactRefs(events);
+    if (refs.length) {
+        const resultDirectory = await realpath(join(sessionDirectory, 'tool-results'));
+        const relativeResultDirectory = relative(sessionDirectory, resultDirectory);
+        if (!relativeResultDirectory || relativeResultDirectory === '..' || relativeResultDirectory.startsWith(`..${sep}`) || isAbsolute(relativeResultDirectory)) {
+            throw new Error('FX tool-results resolves outside its native session directory.');
+        }
+        for (const ref of refs) {
+            const artifactPath = await realpath(join(resultDirectory, ref));
+            if (relative(resultDirectory, artifactPath) !== ref)
+                throw new Error(`FX tool-results/${ref} resolves outside its native result directory.`);
+            const content = exactUtf8(await readFile(artifactPath), `FX tool-results/${ref}`);
+            attachments.push({ name: `tool-results/${ref}`, content, sha256: sha256(content) });
+        }
+    }
+    return { attachments, companions: fxCompanionsFromAttachments(attachments) };
+}
+function provenance(harness, canonical) {
+    const meta = canonical.records.find(record => record.record_type === 'meta');
+    let nativeSessionId = meta?.source_group_id && meta.source_group_id !== 'default' ? meta.source_group_id : undefined;
+    if (harness === 'deepagents' && nativeSessionId) {
+        const group = JSON.parse(nativeSessionId);
+        if (!Array.isArray(group) || group.length !== 2 || typeof group[0] !== 'string' || group[1] !== '')
+            throw new Error('Deep Agents requires an identified root checkpoint namespace.');
+        nativeSessionId = group[0];
+    }
+    const cwd = meta ? JSON.parse(meta.record_json).cwd : undefined;
+    return { nativeSessionId, cwd };
+}
+/** Reconstruct captured native evidence without reading a path or writing an archive. */
+export function snapshotFromEvidence(input) {
+    if (!HARNESSES.includes(input.harness) || typeof input.raw !== 'string')
+        throw new Error('Invalid snapshot evidence harness or transcript.');
+    const attachments = input.attachments ?? [];
+    for (const attachment of attachments) {
+        if (typeof attachment.content !== 'string' || sha256(attachment.content) !== attachment.sha256)
+            throw new Error('Snapshot attachment integrity check failed.');
+    }
+    const manifest = input.harness === 'cline'
+        ? attachments.find(attachment => attachment.name.endsWith('.json') && !attachment.name.endsWith('.compaction.json')) : undefined;
+    const cline = manifest ? JSON.parse(manifest.content) : {};
+    if (input.nativeSessionId && cline.session_id && cline.session_id !== input.nativeSessionId)
+        throw new Error('Selected Cline session disagrees with its manifest.');
+    const summary = input.harness === 'grok-build' ? attachments.find(attachment => attachment.name === 'summary.json') : undefined;
+    const grok = summary ? JSON.parse(summary.content) : {};
+    let archived;
+    switch (input.harness) {
+        case 'grok-build':
+            archived = normalizeGrokBuild(input.raw, { sessionId: grok.info?.id, cwd: grok.info?.cwd, model: grok.current_model_id });
+            break;
+        case 'cursor':
+            archived = readCursor(input.raw);
+            break;
+        case 'deepagents':
+            archived = readDeepAgentsSeed(input.raw).canonical;
+            break;
+        case 'github-copilot':
+            archived = readGitHubCopilot(input.raw);
+            break;
+        case 'fx':
+            archived = readFx(input.raw, fxCompanionsFromAttachments(attachments));
+            break;
+        case 'cline':
+            archived = readCline(input.raw, { sessionId: cline.session_id, cwd: cline.cwd, model: cline.model,
+                ...(input.nativeSessionId ? { sessionId: input.nativeSessionId } : {}) });
+            break;
+        default: archived = normalizeToCanonical({ source: input.harness, transcript: input.raw,
+            ...(input.nativeSessionId ? { sourceContext: { groupId: input.nativeSessionId } } : {}),
+            bounds: { toolArguments: { maxCharacters: null }, toolResults: { maxCharacters: null } },
+            filters: { systemMessages: 'include', toolResults: 'include' },
+        });
+    }
+    return finalizeSnapshot(input, archived, Boolean(cline.compaction_path));
+}
+/** Read an in-memory generated export through the same evidence contract as capture. */
+export function readNativeExportSnapshot(native) {
+    const files = new Map();
+    for (const file of native.files) {
+        if (files.has(file.path))
+            throw new Error('Native export has duplicate file paths.');
+        files.set(file.path, file.content);
+    }
+    const raw = files.get(native.entrypoint);
+    if (raw === undefined)
+        throw new Error('Native export entrypoint is missing.');
+    const attachments = [];
+    const attach = (path, name = basename(path), required = false) => {
+        const content = files.get(path);
+        if (content === undefined) {
+            if (required)
+                throw new Error(`Native export is missing required sidecar ${path}.`);
+            return;
+        }
+        attachments.push({ name, content, sha256: sha256(content) });
+        return content;
+    };
+    const directory = dirname(native.entrypoint);
+    if (native.harness === 'grok-build' && basename(native.entrypoint) === 'chat_history.jsonl')
+        attach(join(directory, 'summary.json'));
+    if (native.harness === 'cline' && native.entrypoint.endsWith('.messages.json')) {
+        const content = attach(native.entrypoint.slice(0, -'.messages.json'.length) + '.json');
+        const manifest = content ? JSON.parse(content) : {};
+        if (manifest.compaction_path && !isAbsolute(manifest.compaction_path)) {
+            const declared = join(directory, manifest.compaction_path);
+            if (declared !== '..' && !declared.startsWith(`..${sep}`))
+                attach(declared, 'declared.compaction.json');
+        }
+        attach(native.entrypoint.slice(0, -'.messages.json'.length) + '.compaction.json');
+    }
+    if (native.harness === 'fx' && JSON.parse(raw)?.schema_version === 4) {
+        const events = attach(join(directory, 'events.jsonl'), 'events.jsonl', true);
+        for (const ref of fxArtifactRefs(events))
+            attach(join(directory, 'tool-results', ref), `tool-results/${ref}`, true);
+    }
+    return snapshotFromEvidence({ harness: native.harness, raw, nativeSessionId: native.sessionId, attachments });
+}
+function finalizeSnapshot(input, archived, clineCompaction = false) {
+    const raw = input.raw, attachments = [...(input.attachments ?? [])];
+    const fxCompanions = input.harness === 'fx' ? fxCompanionsFromAttachments(attachments) : {};
+    // Corrupted source bytes are not a usable checkpoint, even when the normalizer
+    // can recover enough lines to render a transcript.
+    const invalid = archived.diagnostics.filter(d => d.code === 'invalid_json_line' || d.code === 'non_object_json_line');
+    if (invalid.length)
+        throw new Error(`Invalid native transcript: ${invalid.map(d => d.message).join('; ')}`);
+    const canonical = input.harness === 'pi' ? projectPiProviderContext(raw, archived) : archived;
+    const metadata = provenance(input.harness, canonical);
+    if (input.nativeSessionId && metadata.nativeSessionId !== input.nativeSessionId)
+        throw new Error('Selected native session does not match source provenance.');
+    const hash = sha256(raw);
+    const portabilityIssues = [];
+    try {
+        assertPortableHistory(input.harness, raw, fxCompanions);
+    }
+    catch (error) {
+        portabilityIssues.push({ code: 'unsupported_active_context', message: error instanceof Error ? error.message : String(error) });
+    }
+    if (clineCompaction || attachments.some(attachment => attachment.name.endsWith('.compaction.json')))
+        portabilityIssues.push({ code: 'unsupported_active_context', message: 'Cline has native compaction state requiring context reconstruction.' });
+    return {
+        version: 1,
+        id: sha256(`${input.harness}\0${hash}\0${JSON.stringify(canonical)}\0${JSON.stringify(attachments)}`),
+        createdAt: new Date().toISOString(),
+        source: {
+            harness: input.harness,
+            ...(metadata.nativeSessionId ? { nativeSessionId: metadata.nativeSessionId } : {}),
+            sha256: hash,
+        },
+        ...(metadata.cwd ? { cwd: metadata.cwd } : {}),
+        raw,
+        ...(attachments.length ? { attachments } : {}),
+        canonical,
+        ...(portabilityIssues.length ? { portabilityIssues } : {}),
+    };
+}
+export async function readSnapshot(input) {
+    if (!HARNESSES.includes(input.harness))
+        throw new Error(`Unsupported harness: ${input.harness}`);
+    if ((input.path === undefined) === (input.transcript === undefined)) {
+        throw new Error('Supply exactly one of path or transcript.');
+    }
+    let raw;
+    const attachments = [];
+    if (input.harness === 'cursor' && input.path && !input.path.endsWith('.json')) {
+        const captured = await readCursorNative(input.path, input.nativeSessionId);
+        raw = captured.raw;
+        attachments.push(...captured.attachments);
+    }
+    else if (input.harness === 'deepagents' && input.path && !input.path.endsWith('.json')) {
+        if (!input.nativeSessionId)
+            throw new Error('Deep Agents SQLite input requires nativeSessionId (the thread ID).');
+        const captured = await readDeepAgents({ path: input.path, threadId: input.nativeSessionId, pythonExecutable: input.pythonExecutable });
+        raw = captured.raw;
+    }
+    else {
+        raw = input.transcript ?? await readFile(input.path, 'utf8');
+        if (input.harness === 'fx' && input.path) {
+            const captured = await captureFxCompanions(input.path, raw);
+            attachments.push(...captured.attachments);
+        }
+        if (input.harness === 'grok-build' && input.path && basename(input.path) === 'chat_history.jsonl') {
+            try {
+                const content = await readFile(join(dirname(input.path), 'summary.json'), 'utf8');
+                attachments.push({ name: 'summary.json', content, sha256: sha256(content) });
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+        }
+        switch (input.harness) {
+            case 'cline': {
+                if (input.path && input.path.endsWith('.messages.json')) {
+                    const manifestPath = input.path.slice(0, -'.messages.json'.length) + '.json';
+                    try {
+                        const content = await readFile(manifestPath, 'utf8');
+                        const manifest = JSON.parse(content);
+                        attachments.push({ name: basename(manifestPath), content, sha256: sha256(content) });
+                        if (manifest.compaction_path) {
+                            // A declared compaction state blocks conversion even if unavailable.
+                            // Archive contained state only; a manifest cannot redirect reads elsewhere.
+                            const parent = resolve(dirname(input.path));
+                            const declared = resolve(parent, manifest.compaction_path);
+                            const rel = relative(parent, declared);
+                            if (rel && rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel)) {
+                                try {
+                                    const real = await realpath(declared);
+                                    const realRel = relative(await realpath(parent), real);
+                                    if (realRel && realRel !== '..' && !realRel.startsWith(`..${sep}`) && !isAbsolute(realRel)) {
+                                        const content = await readFile(real, 'utf8');
+                                        attachments.push({ name: 'declared.compaction.json', content, sha256: sha256(content) });
+                                    }
+                                }
+                                catch (error) {
+                                    if (error.code !== 'ENOENT')
+                                        throw error;
+                                }
+                            }
+                        }
+                    }
+                    catch (error) {
+                        if (error.code !== 'ENOENT')
+                            throw error;
+                    }
+                    const compactionPath = input.path.slice(0, -'.messages.json'.length) + '.compaction.json';
+                    try {
+                        const content = await readFile(compactionPath, 'utf8');
+                        attachments.push({ name: basename(compactionPath), content, sha256: sha256(content) });
+                    }
+                    catch (error) {
+                        if (error.code !== 'ENOENT')
+                            throw error;
+                    }
+                }
+                break;
+            }
+        }
+    }
+    const snapshot = snapshotFromEvidence({ harness: input.harness, raw, nativeSessionId: input.nativeSessionId, attachments });
+    return input.path ? { ...snapshot, source: { ...snapshot.source, path: resolve(input.path) } } : snapshot;
+}
+const writers = {
+    'claude-code': writeClaudeCode, codex: writeCodex, pi: writePi,
+    omp: writeOmp, opencode: writeOpenCode, 'grok-build': writeGrokBuild,
+    cursor: writeCursor, deepagents: writeDeepAgents, 'github-copilot': writeGitHubCopilot,
+    cline: writeCline, fx: writeFx,
+};
+export function assertSnapshot(snapshot) {
+    if (!snapshot || snapshot.version !== 1 || !HARNESSES.includes(snapshot.source?.harness))
+        throw new Error('Invalid snapshot version or harness.');
+    if (typeof snapshot.raw !== 'string' || sha256(snapshot.raw) !== snapshot.source.sha256)
+        throw new Error('Snapshot native transcript integrity check failed.');
+    const canonical = snapshot.canonical;
+    const id = sha256(`${snapshot.source.harness}\0${snapshot.source.sha256}\0${JSON.stringify(canonical)}\0${JSON.stringify(snapshot.attachments ?? [])}`);
+    if (snapshot.id !== id)
+        throw new Error('Snapshot identity check failed.');
+    if (!canonical.records.length)
+        throw new Error('Snapshot has no canonical records.');
+    const metadata = provenance(snapshot.source.harness, canonical);
+    if (snapshot.source.nativeSessionId !== metadata.nativeSessionId || snapshot.cwd !== metadata.cwd)
+        throw new Error('Snapshot source metadata disagrees with canonical provenance.');
+    for (const attachment of snapshot.attachments ?? []) {
+        if (sha256(attachment.content) !== attachment.sha256)
+            throw new Error('Snapshot attachment integrity check failed.');
+    }
+    for (const record of canonical.records) {
+        if (sha256(record.record_json) !== record.record_hash)
+            throw new Error('Snapshot canonical record integrity check failed.');
+    }
+    validateTranscript(canonical.records.map(r => JSON.parse(r.record_json)));
+}
+/** Complete portable context, stricter than an archive's integrity-only validation. */
+export function assertPortableSnapshot(snapshot) {
+    assertSnapshot(snapshot);
+    const clineCompaction = snapshot.source.harness === 'cline' && snapshot.attachments?.some(attachment => attachment.name.endsWith('.compaction.json') || (attachment.name.endsWith('.json') && JSON.parse(attachment.content).compaction_path));
+    if (snapshot.portabilityIssues?.length || clineCompaction)
+        throw new Error(`Unsupported active context: ${snapshot.portabilityIssues?.map(issue => issue.message).join('; ') ?? 'native Cline compaction state'}`);
+    assertPortableHistory(snapshot.source.harness, snapshot.raw, snapshot.source.harness === 'fx' ? fxCompanionsFromAttachments(snapshot.attachments ?? []) : {});
+    if (snapshot.source.harness === 'pi' && piCompactedContext(snapshot.raw)
+        && JSON.stringify(projectPiProviderContext(snapshot.raw, normalizePiArchive(snapshot.raw))) !== JSON.stringify(snapshot.canonical)) {
+        throw new Error('Compacted Pi snapshot must be recaptured with its verified native active context before conversion.');
+    }
+    if (snapshot.source.harness === 'github-copilot' && JSON.stringify(readGitHubCopilot(snapshot.raw)) !== JSON.stringify(snapshot.canonical)) {
+        throw new Error('Copilot snapshot must be recaptured with complete native messages before conversion.');
+    }
+    toolNames(snapshot.canonical.records.map(record => JSON.parse(record.record_json)));
+}
+export function convert(snapshot, target, options) {
+    return convertWithEntropy(snapshot, target, options);
+}
+/** Internal managed-store codec; its caller freezes the destination identity and time. */
+export function convertManaged(snapshot, target, options, entropySeed, records) {
+    if (!options.sessionId || !options.timestamp)
+        throw new Error('Managed native conversion requires a frozen sessionId and timestamp.');
+    return convertWithEntropy(snapshot, target, options, createSeededNativeEntropy(entropySeed), records);
+}
+function convertWithEntropy(snapshot, target, options, entropy, retainedRecords) {
+    assertPortableSnapshot(snapshot);
+    if (!HARNESSES.includes(target))
+        throw new Error(`Unsupported target: ${target}`);
+    if (!isAbsolute(options.cwd) || !isAbsolute(options.directory))
+        throw new Error('cwd and directory must be absolute paths.');
+    const records = retainedRecords ?? snapshot.canonical.records.map(r => JSON.parse(r.record_json));
+    if (retainedRecords) {
+        validateTranscript([...retainedRecords]);
+        toolNames(retainedRecords);
+    }
+    const output = writers[target](records, options, entropy);
+    output.diagnostics.unshift({ code: 'history_only', message: 'Converted conversation history. Runtime caches, credentials, permissions, tools, and workspace files are not transferred.' });
+    for (const diagnostic of snapshot.canonical.diagnostics) {
+        output.diagnostics.push({ code: `source_${diagnostic.code}`, message: diagnostic.message });
+    }
+    return output;
+}
+/** Write only to a new directory; an existing destination is never modified. */
+export async function writeNativeExport(output, directory) {
+    const root = resolve(directory);
+    const names = new Set();
+    for (const file of output.files) {
+        const local = relative(root, resolve(root, file.path));
+        if (!local || local === '..' || local.startsWith(`..${sep}`) || isAbsolute(file.path) || names.has(local)) {
+            throw new Error(`Unsafe or duplicate native export path: ${file.path}`);
+        }
+        names.add(local);
+    }
+    if (!names.has(output.entrypoint))
+        throw new Error('Native export entrypoint is missing.');
+    await mkdir(dirname(root), { recursive: true });
+    await mkdir(root, { mode: 0o700 });
+    // Root is new and owned by this operation. All files are private and exclusive.
+    for (const file of output.files) {
+        const destination = resolve(root, file.path);
+        await mkdir(dirname(destination), { recursive: true, mode: 0o700 });
+        await writeFile(destination, file.content, { flag: 'wx', mode: 0o600 });
+    }
+}
+export async function writeSnapshot(snapshot, target, options) {
+    await realpath(options.cwd); // Validate an existing workspace, not a guessed remap.
+    const output = convert(snapshot, target, options);
+    await writeNativeExport(output, options.directory);
+    return output;
+}