trajectories 0.0.0 → 0.1.2

package/dist/writers/claude-code.d.ts

@@ -0,0 +1,5 @@
+import type { NativeWriter } from '../types.js';
+/** Claude's project bucket algorithm, mirrored in its official Agent SDK. */
+export declare function claudeProjectKey(cwd: string): string;
+/** Claude Code's parentUuid transcript chain; resume uses an isolated config directory. */
+export declare const writeClaudeCode: NativeWriter;

package/dist/writers/claude-code.js

@@ -0,0 +1,51 @@
+import { destination, droppedRecord, jsonl, parseArguments, timestampOf, toolNames, usageDiagnostic } from './helpers.js';
+import { randomNativeEntropy } from './entropy.js';
+/** Claude's project bucket algorithm, mirrored in its official Agent SDK. */
+export function claudeProjectKey(cwd) {
+    const sanitized = cwd.replace(/[^a-zA-Z0-9]/g, '-');
+    if (sanitized.length <= 200)
+        return sanitized;
+    let hash = 0;
+    for (let i = 0; i < cwd.length; i++)
+        hash = ((hash << 5) - hash + cwd.charCodeAt(i)) | 0;
+    return `${sanitized.slice(0, 200)}-${Math.abs(hash).toString(36)}`;
+}
+/** Claude Code's parentUuid transcript chain; resume uses an isolated config directory. */
+export const writeClaudeCode = (records, options, entropy = randomNativeEntropy) => {
+    const { id, timestamp } = destination(options, entropy);
+    toolNames(records);
+    const diagnostics = [usageDiagnostic()];
+    const entries = [];
+    let parentUuid = null;
+    for (const record of records) {
+        if (droppedRecord(record, diagnostics) || record.role === 'meta')
+            continue;
+        const at = timestampOf(record);
+        let type;
+        let message;
+        if (record.role === 'user') {
+            type = 'user';
+            message = { role: 'user', content: record.content };
+        }
+        else if (record.role === 'assistant') {
+            type = 'assistant';
+            message = { id: `msg_${entropy.uuid().replaceAll('-', '')}`, type: 'message', role: 'assistant', model: 'trajectories-import',
+                content: 'tool_calls' in record ? record.tool_calls.map((call) => ({ type: 'tool_use', id: call.id, name: call.name, input: parseArguments(call.args) })) : [{ type: 'text', text: record.content }],
+                stop_reason: 'tool_calls' in record ? 'tool_use' : 'end_turn', stop_sequence: null,
+                usage: { input_tokens: 0, output_tokens: 0 } };
+        }
+        else if (record.role === 'tool') {
+            type = 'user';
+            message = { role: 'user', content: [{ type: 'tool_result', tool_use_id: record.tool_call_id, content: record.content, ...(record.ok === undefined ? {} : { is_error: !record.ok }) }] };
+        }
+        else
+            continue;
+        const uuid = entropy.uuid();
+        entries.push({ type, uuid, parentUuid, sessionId: id, cwd: options.cwd, timestamp: at || timestamp,
+            isSidechain: false, userType: 'external', version: '2.1.285', message });
+        parentUuid = uuid;
+    }
+    const entrypoint = `projects/${claudeProjectKey(options.cwd)}/${id}.jsonl`;
+    return { harness: 'claude-code', sessionId: id, files: [{ path: entrypoint, content: jsonl(entries) }], entrypoint,
+        resume: { cwd: options.cwd, command: 'env', args: [`CLAUDE_CONFIG_DIR=${options.directory}`, 'claude', '--resume', id, ...(options.model ? ['--model', options.model] : [])] }, diagnostics };
+};

package/dist/writers/cline.d.ts

@@ -0,0 +1,3 @@
+import type { NativeWriter } from '../types.js';
+/** Native Cline Core persisted messages plus the AgentRuntime history used by HarnessAgent. */
+export declare const writeCline: NativeWriter;

package/dist/writers/cline.js

@@ -0,0 +1,77 @@
+import { resolve } from 'node:path';
+import { destination, droppedRecord, parseArguments, timestampOf, toolNames } from './helpers.js';
+import { randomNativeEntropy } from './entropy.js';
+/** Native Cline Core persisted messages plus the AgentRuntime history used by HarnessAgent. */
+export const writeCline = (records, options, entropy = randomNativeEntropy) => {
+    const { id, timestamp } = destination(options, entropy);
+    const names = toolNames(records);
+    const diagnostics = [];
+    if (!options.provider)
+        diagnostics.push({ code: 'unknown-provider', message: 'No target provider was supplied; the manifest records unknown. Select the provider when resuming.' });
+    const messages = [];
+    const history = [];
+    let previous = '';
+    for (const record of records) {
+        if (droppedRecord(record, diagnostics))
+            continue;
+        if (record.role === 'meta')
+            continue;
+        const at = Date.parse(timestampOf(record));
+        const calls = record.role === 'assistant' && 'tool_calls' in record;
+        const kind = calls ? 'calls' : record.role === 'tool' ? 'results' : 'text';
+        const nativeRole = record.role === 'tool' ? 'user' : record.role;
+        let message = messages.at(-1), agentMessage = history.at(-1);
+        if (kind === 'text' || previous !== kind) {
+            const messageId = entropy.uuid();
+            message = { id: messageId, role: nativeRole, content: [], ts: at, agent: 'lead', sessionId: id };
+            agentMessage = { id: messageId, role: record.role, content: [], createdAt: at };
+            messages.push(message);
+            history.push(agentMessage);
+        }
+        if (calls) {
+            for (const call of record.tool_calls) {
+                const input = parseArguments(call.args);
+                message.content.push({ type: 'tool_use', id: call.id, name: call.name, input });
+                agentMessage.content.push({ type: 'tool-call', toolCallId: call.id, toolName: call.name, input });
+            }
+        }
+        else if (record.role === 'tool') {
+            message.content.push({ type: 'tool_result', tool_use_id: record.tool_call_id, name: names.get(record.tool_call_id), content: record.content, ...(record.ok !== undefined ? { is_error: !record.ok } : {}) });
+            agentMessage.content.push({ type: 'tool-result', toolCallId: record.tool_call_id, toolName: names.get(record.tool_call_id), output: record.content, ...(record.ok !== undefined ? { isError: !record.ok } : {}) });
+        }
+        else {
+            message.content.push({ type: 'text', text: record.content });
+            agentMessage.content.push({ type: 'text', text: record.content });
+        }
+        previous = kind;
+    }
+    const root = '.cline/data/sessions';
+    const entrypoint = `${root}/${id}/${id}.messages.json`;
+    const manifest = { version: 1, session_id: id, source: 'cli', pid: 0, started_at: timestamp, ended_at: timestamp, exit_code: 0, status: 'completed', interactive: true,
+        provider: options.provider ?? 'unknown', model: options.model ?? 'unknown', cwd: options.cwd, workspace_root: options.cwd,
+        enable_tools: true, enable_spawn: false, enable_teams: false, messages_path: resolve(options.directory, entrypoint), metadata: { title: 'Imported conversation' } };
+    const origin = { source: 'cli', mode: 'user', sessionId: id };
+    const payload = { version: 1, updated_at: timestamp, agent: 'lead', sessionId: id, origin, messages };
+    const importer = `import { readFile } from 'node:fs/promises';
+import { CoreSessionService, SqliteSessionStore } from '@cline/core';
+const [directory, id] = process.argv.slice(2);
+const path = directory + '/' + id + '/' + id;
+const payload = JSON.parse(await readFile(path + '.messages.json', 'utf8'));
+const manifest = JSON.parse(await readFile(path + '.json', 'utf8'));
+const store = new SqliteSessionStore({ sessionsDir: directory });
+store.init();
+try {
+  if (store.get(id)) throw new Error('Cline destination session is already indexed.');
+  const service = new CoreSessionService(store, { sessionArtifactsDir: directory });
+  await service.createRootSessionWithArtifacts({ sessionId: id, source: 'cli', pid: 0, startedAt: manifest.started_at, endedAt: manifest.ended_at, exitCode: 0, status: 'completed', interactive: true,
+    provider: manifest.provider, model: manifest.model, cwd: manifest.cwd, workspaceRoot: manifest.workspace_root, enableTools: true, enableSpawn: false, enableTeams: false, metadata: manifest.metadata });
+  await service.persistSessionMessages(id, payload.messages);
+} finally { store.close(); }
+`;
+    return { harness: 'cline', sessionId: id, entrypoint,
+        files: [{ path: entrypoint, content: JSON.stringify(payload, null, 2) + '\n' }, { path: `${root}/${id}/${id}.json`, content: JSON.stringify(manifest, null, 2) + '\n' },
+            { path: 'history.json', content: JSON.stringify(history, null, 2) + '\n' }, { path: 'prepare-cline.mjs', content: importer }],
+        prepare: [{ command: 'node', args: [resolve(options.directory, 'prepare-cline.mjs'), resolve(options.directory, root), id], cwd: options.cwd }],
+        resume: { command: 'env', args: [`HOME=${options.directory}`, `CLINE_SESSION_DATA_DIR=${resolve(options.directory, root)}`, 'cline', '--data-dir', resolve(options.directory, '.cline/data'), '--id', id,
+                ...(options.provider ? ['--provider', options.provider] : []), ...(options.model ? ['--model', options.model] : [])], cwd: options.cwd }, diagnostics };
+};

package/dist/writers/codex.d.ts

@@ -0,0 +1,3 @@
+import type { NativeWriter } from '../types.js';
+/** Codex rollout JSONL, consumed by the native rollout loader on resume. */
+export declare const writeCodex: NativeWriter;

package/dist/writers/codex.js

@@ -0,0 +1,32 @@
+import { destination, droppedRecord, jsonl, timestampOf, toolNames } from './helpers.js';
+/** Codex rollout JSONL, consumed by the native rollout loader on resume. */
+export const writeCodex = (records, options, entropy) => {
+    const { id, timestamp } = destination(options, entropy);
+    toolNames(records);
+    const diagnostics = [{ code: 'codex-rollout-format', message: 'Codex rollout import targets the tested native version. Internal persisted formats are not a stable public interchange API.' }];
+    const entries = [{ timestamp, type: 'session_meta', payload: {
+                id, session_id: id, timestamp, cwd: options.cwd, originator: 'trajectories', cli_version: 'imported', source: 'cli',
+                model_provider: options.provider ?? null,
+            } }];
+    for (const record of records) {
+        if (droppedRecord(record, diagnostics) || record.role === 'meta')
+            continue;
+        const at = timestampOf(record);
+        const append = (payload) => entries.push({ timestamp: at, type: 'response_item', payload });
+        if (record.role === 'user' || (record.role === 'assistant' && !('tool_calls' in record))) {
+            append({ type: 'message', role: record.role, content: [{ type: record.role === 'user' ? 'input_text' : 'output_text', text: record.content }] });
+        }
+        else if (record.role === 'assistant' && 'tool_calls' in record) {
+            for (const call of record.tool_calls)
+                append({ type: 'function_call', name: call.name, call_id: call.id, arguments: call.args });
+        }
+        else if (record.role === 'tool') {
+            append({ type: 'function_call_output', call_id: record.tool_call_id, output: record.content });
+            if (record.ok !== undefined && !diagnostics.some((d) => d.code === 'untranslated-tool-status'))
+                diagnostics.push({ code: 'untranslated-tool-status', message: 'Codex function_call_output has no portable success flag; source status remains in the central snapshot.' });
+        }
+    }
+    const entrypoint = `sessions/${timestamp.slice(0, 10).replaceAll('-', '/')}/rollout-${timestamp.replaceAll(':', '-')}-${id}.jsonl`;
+    return { harness: 'codex', sessionId: id, files: [{ path: entrypoint, content: jsonl(entries) }], entrypoint,
+        resume: { cwd: options.cwd, command: 'env', args: [`CODEX_HOME=${options.directory}`, 'codex', 'resume', id, ...(options.model ? ['--model', options.model] : [])] }, diagnostics };
+};

package/dist/writers/cursor.d.ts

@@ -0,0 +1,3 @@
+import type { NativeWriter } from '../types.js';
+/** Cursor AgentKv import for the exact runtime whose serializer and loader were verified. */
+export declare const writeCursor: NativeWriter;

package/dist/writers/cursor.js

@@ -0,0 +1,197 @@
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import { destination, parseArguments, timestampOf, toolNames } from './helpers.js';
+import { randomNativeEntropy } from './entropy.js';
+const TESTED_RUNTIME = '2026.10.01-e373342';
+const FORMAT = 'cursor-agent-sqlite-readout-v1';
+function concat(parts) { return Buffer.concat(parts.map(part => Buffer.from(part))); }
+function varint(input) {
+    if (input < 0n)
+        throw new Error('Cursor protobuf integers must be non-negative.');
+    const bytes = [];
+    do {
+        const byte = Number(input & 0x7fn);
+        input >>= 7n;
+        bytes.push(byte | (input ? 0x80 : 0));
+    } while (input);
+    return Buffer.from(bytes);
+}
+function tag(number, wire) { return varint(BigInt(number * 8 + wire)); }
+function bytes(number, value) { return concat([tag(number, 2), varint(BigInt(value.length)), value]); }
+function text(number, value) { return bytes(number, Buffer.from(value, 'utf8')); }
+function flag(number, value) { return concat([tag(number, 0), varint(value ? 1n : 0n)]); }
+function digest(value) { return createHash('sha256').update(value).digest('hex'); }
+function jsonValue(value) {
+    if (value === null)
+        return concat([tag(1, 0), varint(0n)]);
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            throw new Error('Cursor tool arguments cannot contain non-finite numbers.');
+        const encoded = Buffer.alloc(8);
+        encoded.writeDoubleLE(value);
+        return concat([tag(2, 1), encoded]);
+    }
+    if (typeof value === 'string')
+        return text(3, value);
+    if (typeof value === 'boolean')
+        return flag(4, value);
+    if (Array.isArray(value))
+        return bytes(6, concat(value.map(item => bytes(1, jsonValue(item)))));
+    if (typeof value === 'object') {
+        const entries = Object.entries(value)
+            .map(([key, item]) => bytes(1, concat([text(1, key), bytes(2, jsonValue(item))])));
+        return bytes(5, concat(entries));
+    }
+    throw new Error(`Cursor tool arguments cannot encode ${typeof value}.`);
+}
+function blob(value, blobs) {
+    const id = digest(value);
+    blobs.set(id, Buffer.from(value));
+    return Buffer.from(id, 'hex');
+}
+function encodeTool(step) {
+    if (step.result === undefined || step.ok === undefined)
+        throw new Error(`Cursor tool call ${step.id} has no terminal result.`);
+    const args = concat([text(1, step.name), ...Object.entries(step.args).map(([key, value]) => bytes(2, concat([text(1, key), bytes(2, jsonValue(value))]))), text(3, step.id), text(5, step.name)]);
+    const content = bytes(1, text(1, step.result));
+    const success = concat([bytes(1, content), ...(step.ok ? [] : [flag(2, true)])]);
+    const mcp = concat([bytes(1, args), bytes(2, bytes(1, success))]);
+    return concat([bytes(15, mcp), text(57, step.id)]);
+}
+function nativeReadout(records, id, cwd, timestamp, model, entropy) {
+    const turns = [];
+    const calls = new Map();
+    let current;
+    for (const record of records) {
+        if (record.role === 'meta' || record.role === 'system' || record.role === 'observation' || record.role === 'reasoning')
+            continue;
+        if (record.role === 'user') {
+            timestampOf(record);
+            current = { user: record.content, steps: [] };
+            turns.push(current);
+            continue;
+        }
+        if (!current)
+            throw new Error(`Cursor native history cannot place ${record.role} before the first user turn.`);
+        timestampOf(record);
+        if (record.role === 'assistant' && !('tool_calls' in record))
+            current.steps.push({ kind: 'assistant', text: record.content });
+        else if (record.role === 'assistant') {
+            for (const call of record.tool_calls) {
+                const step = { kind: 'tool', id: call.id, name: call.name, args: parseArguments(call.args) };
+                current.steps.push(step);
+                calls.set(call.id, step);
+            }
+        }
+        else if (record.role === 'tool') {
+            const step = calls.get(record.tool_call_id);
+            if (!step)
+                throw new Error(`Cursor native history has an orphan tool result: ${record.tool_call_id}`);
+            if (record.ok === undefined)
+                throw new Error(`Cursor native history cannot infer tool status: ${record.tool_call_id}`);
+            step.result = record.content;
+            step.ok = record.ok;
+        }
+    }
+    if (!turns.length)
+        throw new Error('Cursor native history requires at least one user turn.');
+    if (turns.some(turn => turn.steps.length === 0))
+        throw new Error('Cursor native history contains an unanswered user turn.');
+    const blobs = new Map();
+    const turnRefs = [];
+    for (const turn of turns) {
+        const userRef = blob(text(1, turn.user), blobs);
+        const stepRefs = turn.steps.map(step => {
+            const payload = step.kind === 'assistant' ? bytes(1, text(1, step.text))
+                : step.kind === 'thinking' ? bytes(3, text(1, step.text)) : bytes(2, encodeTool(step));
+            return blob(payload, blobs);
+        });
+        const agent = concat([bytes(1, userRef), ...stepRefs.map(ref => bytes(2, ref))]);
+        turnRefs.push(blob(bytes(1, agent), blobs));
+    }
+    const root = concat(turnRefs.map(ref => bytes(8, ref)));
+    const rootBlobId = digest(root);
+    blobs.set(rootBlobId, root);
+    const metadata = {
+        agentId: id, latestRootBlobId: rootBlobId, name: 'Imported trajectory', mode: 'default', isRunEverything: false,
+        createdAt: Date.parse(timestamp), blobEncryptionKey: Buffer.from(entropy.bytes(32)).toString('hex'), ...(model ? { lastUsedModel: model } : {}),
+    };
+    const metadataHex = Buffer.from(JSON.stringify(metadata), 'utf8').toString('hex');
+    return JSON.stringify({ format: FORMAT,
+        source: { runtime: 'cursor-agent', version: TESTED_RUNTIME, schema: 1, store: 'store.db' },
+        sessionId: id, metadataHex, metaRows: [{ key: '0', value: metadataHex }], rootBlobId,
+        blobs: [...blobs].sort(([a], [b]) => a.localeCompare(b)).map(([blobId, data]) => ({ id: blobId, dataBase64: data.toString('base64') })),
+        provenance: { cwd, createdAt: timestamp, sourceRecords: records },
+    }, null, 2) + '\n';
+}
+const PREPARE = String.raw `import { createHash } from 'node:crypto';
+import { copyFile, lstat, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { DatabaseSync } from 'node:sqlite';
+
+const artifact = resolve(process.argv[2] ?? '');
+const output = resolve(process.argv[3] ?? '');
+if (!artifact || !output) throw new Error('usage: node prepare-cursor.mjs <readout.json> <output-directory>');
+const runtime = process.env.CURSOR_AGENT_BIN || 'cursor-agent';
+const version = spawnSync(runtime, ['--version'], { encoding: 'utf8' });
+if (version.status !== 0) throw new Error('cursor-agent is unavailable; set CURSOR_AGENT_BIN to the tested executable');
+if (String(version.stdout).trim() !== '2026.10.01-e373342' && process.env.CURSOR_NATIVE_ALLOW_UNTESTED !== '1') {
+  throw new Error('Cursor native import was verified only with cursor-agent 2026.10.01-e373342');
+}
+const readout = JSON.parse(await readFile(artifact, 'utf8'));
+if (readout.format !== 'cursor-agent-sqlite-readout-v1' || readout.source?.schema !== 1 || !readout.provenance?.cwd) {
+  throw new Error('unsupported Cursor readout');
+}
+for (const row of readout.blobs) {
+  if (createHash('sha256').update(Buffer.from(row.dataBase64, 'base64')).digest('hex') !== row.id) throw new Error('corrupt Cursor blob ' + row.id);
+}
+const project = createHash('md5').update(resolve(readout.provenance.cwd)).digest('hex');
+const cliDir = join(output, 'home', '.cursor', 'chats', project, readout.sessionId);
+const acpDir = join(output, 'home', '.cursor', 'acp-sessions', readout.sessionId);
+const temp = cliDir + '.tmp-' + process.pid;
+if (await lstat(cliDir).then(() => true, () => false) || await lstat(acpDir).then(() => true, () => false)) {
+  throw new Error('refusing to replace an existing Cursor session: ' + readout.sessionId);
+}
+await mkdir(dirname(cliDir), { recursive: true });
+await mkdir(dirname(acpDir), { recursive: true });
+await rm(temp, { recursive: true, force: true });
+await mkdir(temp);
+const db = new DatabaseSync(join(temp, 'store.db'));
+try {
+  db.exec('PRAGMA journal_mode=WAL; PRAGMA user_version=1; CREATE TABLE blobs (id TEXT PRIMARY KEY, data BLOB); CREATE TABLE meta (key TEXT PRIMARY KEY, value TEXT); BEGIN IMMEDIATE');
+  const insertBlob = db.prepare('INSERT INTO blobs (id, data) VALUES (?, ?)');
+  for (const row of readout.blobs) insertBlob.run(row.id, Buffer.from(row.dataBase64, 'base64'));
+  const insertMeta = db.prepare('INSERT INTO meta (key, value) VALUES (?, ?)');
+  for (const row of readout.metaRows) insertMeta.run(row.key, row.value);
+  db.exec('COMMIT; PRAGMA wal_checkpoint(TRUNCATE)');
+} catch (error) { try { db.exec('ROLLBACK') } catch {} throw error } finally { db.close() }
+try { await rename(temp, cliDir) } catch (error) { await rm(temp, { recursive: true, force: true }); throw new Error('refusing to replace an existing Cursor session: ' + cliDir, { cause: error }) }
+try {
+  await mkdir(acpDir);
+  await copyFile(join(cliDir, 'store.db'), join(acpDir, 'store.db'));
+  await writeFile(join(acpDir, 'meta.json'), JSON.stringify({ schemaVersion: 1, cwd: resolve(readout.provenance.cwd) }) + '\n');
+} catch (error) { await rm(cliDir, { recursive: true, force: true }); await rm(acpDir, { recursive: true, force: true }); throw error }
+console.log(readout.sessionId);
+`;
+/** Cursor AgentKv import for the exact runtime whose serializer and loader were verified. */
+export const writeCursor = (records, options, entropy = randomNativeEntropy) => {
+    if (options.provider)
+        throw new Error(`Cursor CLI has no provider-routing option; cannot honor provider ${options.provider}.`);
+    const { id, timestamp } = destination(options, entropy);
+    toolNames(records);
+    const diagnostics = [{ code: 'cursor-version-pinned',
+            message: `Cursor AgentKv import is pinned to cursor-agent ${TESTED_RUNTIME}; prepare refuses other versions unless the caller explicitly sets CURSOR_NATIVE_ALLOW_UNTESTED=1.` }];
+    for (const role of ['system', 'observation', 'reasoning'])
+        if (records.some(record => record.role === role))
+            diagnostics.push({
+                code: `untranslated-${role}`, message: `Source ${role} records remain verbatim in the import readout; they are not installed as target instructions or provider reasoning.`
+            });
+    const entrypoint = `cursor/${id}.readout.json`;
+    const helper = 'cursor/prepare-cursor.mjs';
+    const content = nativeReadout(records, id, options.cwd, timestamp, options.model, entropy);
+    return { harness: 'cursor', sessionId: id, files: [{ path: entrypoint, content }, { path: helper, content: PREPARE }], entrypoint,
+        prepare: [{ command: 'node', args: [join(options.directory, helper), join(options.directory, entrypoint), options.directory], cwd: options.cwd }],
+        resume: { command: 'env', args: [`HOME=${join(options.directory, 'home')}`, 'cursor-agent', '--resume', id,
+                ...(options.model ? ['--model', options.model] : [])], cwd: options.cwd }, diagnostics };
+};

package/dist/writers/deepagents.d.ts

@@ -0,0 +1,3 @@
+import type { NativeWriter } from '../types.js';
+/** A portable seed plus an explicit importer using Deep Agents' official checkpoint APIs. */
+export declare const writeDeepAgents: NativeWriter;

package/dist/writers/deepagents.js

@@ -0,0 +1,116 @@
+import { resolve } from 'node:path';
+import { assertDeepAgentsPortable, normalizeDeepAgentsSeed } from '../readers/deepagents.js';
+import { destination, droppedRecord, parseArguments, timestampOf, toolNames } from './helpers.js';
+const importer = `#!/usr/bin/env python3
+import asyncio
+import json
+import os
+import sys
+from pathlib import Path
+
+def fail(message):
+    raise SystemExit(message)
+
+async def main():
+    if len(sys.argv) != 3:
+        fail("usage: import_deepagents.py CHECKPOINT_JSON SESSIONS_DB")
+    seed_path = Path(sys.argv[1]).resolve()
+    database = Path(sys.argv[2]).resolve()
+    if database.name != "sessions.db" or database.parent.name != ".state":
+        fail("destination must end in .state/sessions.db")
+    os.environ["DEEPAGENTS_HOME"] = str(database.parent.parent)
+    from deepagents_code.sessions import get_checkpointer, save_thread_seed
+    from langchain_core.messages import AIMessage, HumanMessage, ToolMessage
+    seed = json.loads(seed_path.read_text(encoding="utf-8"))
+    if seed.get("version") != 1 or seed.get("source") != "deepagents":
+        fail("invalid Deep Agents seed")
+    session = seed["session"]
+    messages = []
+    message_ids = set()
+    for item in seed["messages"]:
+        if not item.get("id"):
+            fail("Deep Agents seed message is missing its native id")
+        if item["id"] in message_ids:
+            fail("Deep Agents seed contains a duplicate native message id")
+        message_ids.add(item["id"])
+        metadata = {"timestamp": item["timestamp"]}
+        if item["role"] == "human":
+            messages.append(HumanMessage(id=item["id"], content=item["content"], additional_kwargs=metadata))
+        elif item["role"] == "ai":
+            response = {**metadata}
+            if item.get("model"):
+                response["model_name"] = item["model"]
+            messages.append(AIMessage(id=item["id"], content=item["content"], tool_calls=[
+                {"id": call["id"], "name": call["name"], "args": call["args"], "type": "tool_call"}
+                for call in item["toolCalls"]
+            ], response_metadata=response))
+        elif item["role"] == "tool":
+            messages.append(ToolMessage(id=item["id"], content=item["content"], tool_call_id=item["toolCallId"], additional_kwargs=metadata))
+        else:
+            fail("unsupported Deep Agents message role")
+    values = {"messages": messages}
+    if session.get("model"):
+        values["model"] = session["model"]
+    config = {"configurable": {"thread_id": session["threadId"], "checkpoint_ns": ""}}
+    async with get_checkpointer() as checkpointer:
+        if await checkpointer.aget_tuple(config) is not None:
+            fail("destination already contains the requested Deep Agents thread")
+    await save_thread_seed(session["threadId"], values, agent_name="default", cwd=session["cwd"])
+    async with get_checkpointer() as checkpointer:
+        stored = await checkpointer.aget_tuple(config)
+        if stored is None:
+            fail("Deep Agents did not persist the seeded checkpoint")
+        metadata = dict(stored.metadata or {})
+        metadata.update({"acp_session": True, "cwd": session["cwd"]})
+        await checkpointer.aput(
+            config,
+            stored.checkpoint,
+            metadata,
+            stored.checkpoint["channel_versions"],
+        )
+
+asyncio.run(main())
+`;
+/** A portable seed plus an explicit importer using Deep Agents' official checkpoint APIs. */
+export const writeDeepAgents = (records, options, entropy) => {
+    const { id, timestamp } = destination(options, entropy);
+    toolNames(records);
+    const diagnostics = [];
+    const messages = [];
+    const nextMessageId = () => `trajectory:${id}:${messages.length + 1}`;
+    for (const record of records) {
+        if (droppedRecord(record, diagnostics) || record.role === 'meta')
+            continue;
+        if (record.role === 'user')
+            messages.push({ id: nextMessageId(), role: 'human', content: record.content, timestamp: timestampOf(record) });
+        else if (record.role === 'assistant') {
+            messages.push('tool_calls' in record
+                ? { id: nextMessageId(), role: 'ai', content: '', reasoning: [], toolCalls: record.tool_calls.map(call => ({
+                        id: call.id, name: call.name, args: parseArguments(call.args),
+                    })), ...(options.model ? { model: options.model } : {}), timestamp: timestampOf(record) }
+                : { id: nextMessageId(), role: 'ai', content: record.content, reasoning: [], toolCalls: [],
+                    ...(options.model ? { model: options.model } : {}), timestamp: timestampOf(record) });
+        }
+        else if (record.role === 'tool') {
+            messages.push({ id: nextMessageId(), role: 'tool', content: record.content, toolCallId: record.tool_call_id, timestamp: timestampOf(record) });
+            if (record.ok !== undefined && !diagnostics.some(item => item.code === 'untranslated-tool-status')) {
+                diagnostics.push({ code: 'untranslated-tool-status', message: 'Deep Agents ToolMessage does not carry source success status. The central snapshot retains it.' });
+            }
+        }
+    }
+    const session = { threadId: id, checkpointNamespace: '', cwd: options.cwd, createdAt: timestamp,
+        ...(options.model ? { model: options.model } : {}) };
+    const seed = { version: 1, source: 'deepagents', session, messages };
+    assertDeepAgentsPortable(JSON.stringify(seed));
+    normalizeDeepAgentsSeed(seed);
+    const entrypoint = 'checkpoint.json';
+    const database = resolve(options.directory, '.state', 'sessions.db');
+    return { harness: 'deepagents', sessionId: id, entrypoint,
+        files: [{ path: entrypoint, content: JSON.stringify(seed, null, 2) + '\n' },
+            { path: 'import_deepagents.py', content: importer }],
+        prepare: [{ command: 'python3', args: [resolve(options.directory, 'import_deepagents.py'),
+                    resolve(options.directory, entrypoint), database], cwd: options.cwd }],
+        resume: { command: 'env', args: [`DEEPAGENTS_HOME=${options.directory}`, 'dcode', '-r', id,
+                ...(options.model ? ['--model', options.provider ? `${options.provider}:${options.model}` : options.model] : [])], cwd: options.cwd },
+        diagnostics: [...diagnostics, { code: 'native-prepare-required', message: 'Run the explicit importer with the Python environment that contains deepagents-code before resuming.' }] };
+};

package/dist/writers/entropy.d.ts

@@ -0,0 +1,5 @@
+import type { NativeEntropy } from '../types.js';
+export declare const NATIVE_ENTROPY_VERSION = "trajectories-native-entropy-v1";
+export declare const randomNativeEntropy: NativeEntropy;
+/** A frozen 32-byte seed reproduces native identities without storing their bodies. */
+export declare function createSeededNativeEntropy(seed: string): NativeEntropy;

package/dist/writers/entropy.js

@@ -0,0 +1,33 @@
+import { createHmac, randomBytes, randomUUID } from 'node:crypto';
+export const NATIVE_ENTROPY_VERSION = 'trajectories-native-entropy-v1';
+export const randomNativeEntropy = Object.freeze({
+    uuid: () => randomUUID(),
+    bytes: (length) => randomBytes(length),
+});
+/** A frozen 32-byte seed reproduces native identities without storing their bodies. */
+export function createSeededNativeEntropy(seed) {
+    if (!/^[0-9a-f]{64}$/i.test(seed))
+        throw new Error('Native entropy seed must contain 32 hexadecimal bytes.');
+    const key = Buffer.from(seed, 'hex');
+    let counter = 0n;
+    const bytes = (length) => {
+        if (!Number.isSafeInteger(length) || length < 0)
+            throw new Error('Invalid native entropy byte length.');
+        const output = Buffer.alloc(length);
+        for (let offset = 0; offset < length; offset += 32) {
+            const block = createHmac('sha256', key).update(`${NATIVE_ENTROPY_VERSION}\0${counter++}`).digest();
+            block.copy(output, offset, 0, Math.min(32, length - offset));
+        }
+        return output;
+    };
+    return {
+        bytes,
+        uuid: () => {
+            const value = bytes(16);
+            value[6] = (value[6] & 0x0f) | 0x40;
+            value[8] = (value[8] & 0x3f) | 0x80;
+            const hex = value.toString('hex');
+            return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+        },
+    };
+}

package/dist/writers/fx.d.ts

@@ -0,0 +1,3 @@
+import type { NativeWriter } from '../types.js';
+/** FX legacy session.json schema 1 with presentation execution-memory schema 3. */
+export declare const writeFx: NativeWriter;