trajectories 0.0.0 → 0.1.2

package/dist/readers/deepagents.d.ts

@@ -0,0 +1,41 @@
+import { type CanonicalResult, type DeepAgentsCheckpointData } from '@letta-ai/trajectory';
+export interface DeepAgentsSeed {
+    version: 1;
+    source: 'deepagents';
+    session: {
+        threadId: string;
+        checkpointNamespace: '';
+        cwd: string;
+        createdAt: string;
+        model?: string;
+        checkpointId?: string;
+        checkpointTimestamp?: string;
+    };
+    messages: Array<DeepAgentsCheckpointData['messages'][number] & {
+        id?: string;
+    }>;
+}
+export interface DeepAgentsReadResult {
+    raw: string;
+    canonical: CanonicalResult;
+    nativeSessionId: string;
+    cwd?: string;
+    checkpoint: {
+        id?: string;
+        namespace: string;
+        timestamp?: string;
+    };
+    diagnostics: Array<{
+        code: string;
+        message: string;
+    }>;
+}
+export declare function normalizeDeepAgentsSeed(seed: DeepAgentsSeed): CanonicalResult;
+export declare function readDeepAgentsSeed(raw: string): DeepAgentsReadResult;
+export declare function assertDeepAgentsPortable(raw: string): void;
+/** Read either a portable checkpoint.json seed or one selected thread from sessions.db. */
+export declare function readDeepAgents(input: {
+    path: string;
+    threadId: string;
+    pythonExecutable?: string;
+}): Promise<DeepAgentsReadResult>;

package/dist/readers/deepagents.js

@@ -0,0 +1,163 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { loadDeepAgentsCheckpoint, } from '@letta-ai/trajectory';
+import { canonicalFromRecords } from './canonical.js';
+function object(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function requireString(value, label, allowEmpty = false) {
+    if (typeof value !== 'string' || (!allowEmpty && !value.trim()))
+        throw new Error(`Deep Agents seed requires ${label}.`);
+    return value;
+}
+function decodeSeed(value) {
+    if (!object(value) || value.version !== 1 || value.source !== 'deepagents' || !object(value.session)
+        || !Array.isArray(value.messages))
+        throw new Error('Invalid Deep Agents checkpoint seed.');
+    const session = value.session;
+    if (requireString(session.checkpointNamespace, 'root checkpoint namespace', true) !== '') {
+        throw new Error('Deep Agents continuation only supports the root checkpoint namespace.');
+    }
+    const decoded = { version: 1, source: 'deepagents', session: {
+            threadId: requireString(session.threadId, 'threadId'), checkpointNamespace: '',
+            cwd: requireString(session.cwd, 'cwd'), createdAt: requireString(session.createdAt, 'createdAt'),
+            ...(session.model === undefined ? {} : { model: requireString(session.model, 'model') }),
+            ...(session.checkpointId === undefined ? {} : { checkpointId: requireString(session.checkpointId, 'checkpointId') }),
+            ...(session.checkpointTimestamp === undefined ? {} : { checkpointTimestamp: requireString(session.checkpointTimestamp, 'checkpointTimestamp') }),
+        }, messages: [] };
+    if (!Number.isFinite(Date.parse(decoded.session.createdAt)))
+        throw new Error('Invalid Deep Agents seed createdAt.');
+    for (const [index, message] of value.messages.entries()) {
+        if (!object(message))
+            throw new Error(`Invalid Deep Agents seed message ${index}.`);
+        const timestamp = message.timestamp === undefined ? undefined : requireString(message.timestamp, `message ${index} timestamp`);
+        const id = message.id === undefined ? undefined : requireString(message.id, `message ${index} id`);
+        if (timestamp && !Number.isFinite(Date.parse(timestamp)))
+            throw new Error(`Invalid Deep Agents seed message ${index} timestamp.`);
+        if (message.role === 'human') {
+            decoded.messages.push({ role: 'human', content: requireString(message.content, `message ${index} content`, true), timestamp,
+                ...(id ? { id } : {}) });
+        }
+        else if (message.role === 'ai') {
+            if (!Array.isArray(message.reasoning) || message.reasoning.some(item => typeof item !== 'string') || !Array.isArray(message.toolCalls)) {
+                throw new Error('Deep Agents seed contains malformed reasoning or tool calls.');
+            }
+            const toolCalls = message.toolCalls.map((call, callIndex) => {
+                if (!object(call) || !object(call.args))
+                    throw new Error(`Invalid Deep Agents seed tool call ${index}:${callIndex}.`);
+                return { id: requireString(call.id, `tool call ${index}:${callIndex} id`),
+                    name: requireString(call.name, `tool call ${index}:${callIndex} name`), args: call.args };
+            });
+            decoded.messages.push({ role: 'ai', content: requireString(message.content, `message ${index} content`, true),
+                reasoning: message.reasoning, toolCalls,
+                ...(message.model === undefined ? {} : { model: requireString(message.model, `message ${index} model`) }),
+                ...(timestamp ? { timestamp } : {}), ...(id ? { id } : {}) });
+        }
+        else if (message.role === 'tool') {
+            decoded.messages.push({ role: 'tool', content: requireString(message.content, `message ${index} content`, true),
+                toolCallId: requireString(message.toolCallId, `message ${index} toolCallId`), timestamp, ...(id ? { id } : {}) });
+        }
+        else
+            throw new Error(`Unsupported Deep Agents seed role at message ${index}.`);
+    }
+    return decoded;
+}
+function seedEntries(seed) {
+    const entries = [{ record: { role: 'meta', source: 'deepagents', cwd: seed.session.cwd,
+                ...(seed.session.model ? { model: seed.session.model } : {}) }, nativeId: 'meta', sourceSequence: 0 }];
+    let sequence = 0;
+    let synthesized = 0;
+    for (const message of seed.messages) {
+        const timestamp = message.timestamp ?? seed.session.checkpointTimestamp ?? seed.session.createdAt;
+        if (!message.timestamp)
+            synthesized += 1;
+        const common = () => ({ ...(message.id ? { nativeId: message.id } : {}),
+            ...(message.timestamp ? { sourceTimestamp: message.timestamp } : {}), sourceSequence: ++sequence });
+        if (message.role === 'human')
+            entries.push({ ...common(),
+                record: { role: 'user', content: message.content, timestamp } });
+        else if (message.role === 'ai') {
+            for (const reasoning of message.reasoning)
+                entries.push({ ...common(),
+                    record: { role: 'reasoning', content: reasoning, timestamp } });
+            if (message.content)
+                entries.push({ ...common(),
+                    record: { role: 'assistant', content: message.content, timestamp } });
+            if (message.toolCalls.length)
+                entries.push({ ...common(),
+                    record: { role: 'assistant', content: null, tool_calls: message.toolCalls.map(call => ({
+                            id: call.id, name: call.name, args: JSON.stringify(call.args),
+                        })), timestamp } });
+        }
+        else
+            entries.push({ ...common(),
+                record: { role: 'tool', tool_call_id: message.toolCallId, content: message.content, timestamp } });
+    }
+    const diagnostics = synthesized ? [{ code: 'timestamps_synthesized',
+            message: `Synthesized timestamps for ${synthesized} Deep Agents checkpoint messages from the checkpoint timestamp.`,
+            count: synthesized }] : [];
+    return { entries, diagnostics };
+}
+export function normalizeDeepAgentsSeed(seed) {
+    const { entries, diagnostics } = seedEntries(seed);
+    return canonicalFromRecords('deepagents', JSON.stringify([seed.session.threadId, '']), entries, diagnostics);
+}
+export function readDeepAgentsSeed(raw) {
+    const seed = decodeSeed(JSON.parse(raw));
+    const canonical = normalizeDeepAgentsSeed(seed);
+    return { raw, canonical, nativeSessionId: seed.session.threadId, cwd: seed.session.cwd,
+        checkpoint: { id: seed.session.checkpointId, namespace: '', timestamp: seed.session.checkpointTimestamp },
+        diagnostics: [{ code: 'checkpoint-seed', message: 'Read the portable Deep Agents seed. Run its explicit prepare step before native resume.' },
+            ...canonical.diagnostics.map(item => ({ code: item.code, message: item.message }))] };
+}
+export function assertDeepAgentsPortable(raw) {
+    const seed = decodeSeed(JSON.parse(raw));
+    const pending = new Set();
+    const messageIds = new Set();
+    for (const message of seed.messages) {
+        if (message.id && messageIds.has(message.id)) {
+            throw new Error('Unsupported deepagents continuation history: duplicate native message id.');
+        }
+        if (message.id)
+            messageIds.add(message.id);
+        if (message.role === 'ai' && message.toolCalls.length) {
+            for (const call of message.toolCalls) {
+                if (!call.id || !call.name || !object(call.args) || pending.has(call.id)) {
+                    throw new Error('Unsupported deepagents continuation history: malformed or duplicate tool call.');
+                }
+                pending.add(call.id);
+            }
+        }
+        else if (message.role === 'tool') {
+            if (!pending.delete(message.toolCallId))
+                throw new Error('Unsupported deepagents continuation history: orphan or duplicate tool result.');
+        }
+        else if (pending.size && (message.role === 'human' || message.role === 'ai')) {
+            throw new Error('Unsupported deepagents continuation history: unfinished tool batch.');
+        }
+    }
+    if (pending.size)
+        throw new Error(`Unsupported deepagents continuation history: pending tool calls: ${[...pending].join(', ')}.`);
+}
+/** Read either a portable checkpoint.json seed or one selected thread from sessions.db. */
+export async function readDeepAgents(input) {
+    const path = resolve(input.path);
+    if (path.endsWith('.json')) {
+        const selected = readDeepAgentsSeed(await readFile(path, 'utf8'));
+        if (selected.nativeSessionId !== input.threadId)
+            throw new Error('Deep Agents seed threadId does not match the requested selector.');
+        return selected;
+    }
+    const location = { path, threadId: input.threadId, ...(input.pythonExecutable ? { pythonExecutable: input.pythonExecutable } : {}) };
+    const checkpoint = await loadDeepAgentsCheckpoint(location);
+    const readout = { version: 1, source: 'deepagents', session: {
+            threadId: checkpoint.threadId, checkpointNamespace: '', cwd: checkpoint.cwd ?? '',
+            createdAt: checkpoint.checkpointTimestamp, checkpointId: checkpoint.checkpointId,
+            checkpointTimestamp: checkpoint.checkpointTimestamp, ...(checkpoint.model ? { model: checkpoint.model } : {}),
+        }, messages: checkpoint.messages };
+    const canonical = normalizeDeepAgentsSeed(readout);
+    return { raw: JSON.stringify(readout, null, 2) + '\n', canonical, nativeSessionId: checkpoint.threadId,
+        ...(checkpoint.cwd ? { cwd: checkpoint.cwd } : {}), checkpoint: { id: checkpoint.checkpointId,
+            namespace: checkpoint.checkpointNamespace, timestamp: checkpoint.checkpointTimestamp },
+        diagnostics: canonical.diagnostics.map(item => ({ code: item.code, message: item.message })) };
+}

package/dist/readers/fx.d.ts

@@ -0,0 +1,11 @@
+import type { CanonicalResult } from '@letta-ai/trajectory';
+export interface FxNativeCompanions {
+    /** Native schema-4 conversation log (`events.jsonl`). */
+    events?: string;
+    /** Exact `tool-results/<artifact_ref>` bodies, keyed by artifact_ref. */
+    toolResults?: Readonly<Record<string, string>>;
+}
+/** Parse a native FX session for archival inspection, retaining unsupported-feature diagnostics. */
+export declare function readFx(raw: string, companions?: FxNativeCompanions): CanonicalResult;
+/** Fail closed before converting FX history whose native context cannot be represented completely. */
+export declare function assertFxPortable(raw: string, companions?: FxNativeCompanions): void;