trajectories 0.0.0 → 0.1.1

package/dist/portable.d.ts

@@ -0,0 +1,9 @@
+import type { NormalizedRecord } from '@letta-ai/trajectory';
+export interface PortableConversationToken {
+    readonly semantic: string;
+    readonly recordIndex: number;
+    /** A tool-call ordinal within the record; all other records use zero. */
+    readonly componentIndex: number;
+}
+/** Compare portable conversation positions without native record IDs or timestamps. */
+export declare function portableConversationTokens(records: readonly NormalizedRecord[]): PortableConversationToken[];

package/dist/portable.js

@@ -0,0 +1,26 @@
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(',')}]`;
+    if (value && typeof value === 'object')
+        return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(',')}}`;
+    return JSON.stringify(value);
+}
+/** Compare portable conversation positions without native record IDs or timestamps. */
+export function portableConversationTokens(records) {
+    const result = [];
+    for (const [recordIndex, record] of records.entries()) {
+        if (record.role === 'user' || record.role === 'system' || record.role === 'reasoning' || record.role === 'observation'
+            || (record.role === 'assistant' && typeof record.content === 'string')) {
+            result.push({ semantic: canonicalJson([record.role, record.content]), recordIndex, componentIndex: 0 });
+        }
+        else if (record.role === 'assistant' && 'tool_calls' in record && Array.isArray(record.tool_calls)) {
+            for (const [componentIndex, call] of record.tool_calls.entries()) {
+                result.push({ semantic: canonicalJson(['call', call.id, call.name, JSON.parse(call.args)]), recordIndex, componentIndex });
+            }
+        }
+        else if (record.role === 'tool') {
+            result.push({ semantic: canonicalJson(['tool', record.tool_call_id, record.content, record.ok ?? null]), recordIndex, componentIndex: 0 });
+        }
+    }
+    return result;
+}

package/dist/readers/canonical.d.ts

@@ -0,0 +1,13 @@
+import { type CanonicalResult, type Diagnostic, type NormalizedRecord } from '@letta-ai/trajectory';
+export interface DecodedRecord {
+    record: NormalizedRecord;
+    nativeId?: string;
+    sourceTimestamp?: string;
+    /** Position in the native store, never transport arrival order. */
+    sourceSequence?: number;
+}
+/** Canonical schema shared with trajectory; custom codecs retain their own provenance.
+ * Semantic hashes/component keys follow @letta-ai/trajectory 0.4.3's canonical.ts
+ * (Apache-2.0). Native identities belong to the decoder, never a surrogate source.
+ */
+export declare function canonicalFromRecords(source: string, sessionId: string, entries: readonly DecodedRecord[], diagnostics?: Diagnostic[]): CanonicalResult;

package/dist/readers/canonical.js

@@ -0,0 +1,54 @@
+import { createHash } from 'node:crypto';
+import { CANONICAL_SCHEMA_VERSION, validateTranscript } from '@letta-ai/trajectory';
+const hash = (value) => createHash('sha256').update(value).digest('hex');
+function json(value) {
+    if (Array.isArray(value))
+        return `[${value.map(json).join(',')}]`;
+    if (value && typeof value === 'object')
+        return `{${Object.entries(value).filter(([, item]) => item !== undefined).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([key, item]) => `${JSON.stringify(key)}:${json(item)}`).join(',')}}`;
+    return JSON.stringify(value);
+}
+/** Canonical schema shared with trajectory; custom codecs retain their own provenance.
+ * Semantic hashes/component keys follow @letta-ai/trajectory 0.4.3's canonical.ts
+ * (Apache-2.0). Native identities belong to the decoder, never a surrogate source.
+ */
+export function canonicalFromRecords(source, sessionId, entries, diagnostics = []) {
+    if (typeof source !== 'string' || !source.trim() || typeof sessionId !== 'string' || !sessionId.trim())
+        throw new Error('Decoded history requires a source and session identity.');
+    if (entries[0]?.record.role !== 'meta' || entries.filter(entry => entry.record.role === 'meta').length !== 1)
+        throw new Error('Decoded history requires one leading metadata record.');
+    validateTranscript(entries.map(entry => entry.record));
+    const records = [];
+    for (const [index, entry] of entries.entries()) {
+        const sequence = entry.sourceSequence ?? index;
+        if (!Number.isSafeInteger(sequence) || sequence < 0)
+            throw new Error('Invalid native record sequence.');
+        const original = entry.record;
+        const components = original.role === 'assistant' && 'tool_calls' in original
+            ? original.tool_calls.map(call => ({ ...original, tool_calls: [call] })) : [original];
+        for (const [component, record] of components.entries()) {
+            const type = record.role === 'assistant' && 'tool_calls' in record ? 'assistant-tool-call' : record.role;
+            const call = record.role === 'assistant' && 'tool_calls' in record ? record.tool_calls[0] : undefined;
+            const meta = type === 'meta';
+            const stableId = meta ? 'meta' : entry.nativeId ?? hash(`${sessionId}|ordinal|${sequence}|decoded|${index}`);
+            const componentKey = call ? `tool-call:${call.id}` : record.role === 'tool' ? `tool-result:${record.tool_call_id}` : meta ? 'meta' : `${type === 'reasoning' || type === 'observation' ? type : 'message'}:0`;
+            const semantic = record.role === 'meta' ? { source: record.source, ...(record.cwd !== undefined ? { cwd: record.cwd } : {}), ...(record.git_branch !== undefined ? { git_branch: record.git_branch } : {}), ...(record.model !== undefined ? { model: record.model } : {}) } : call ? { name: call.name, args: call.args } : record.role === 'tool' ? { content: record.content, ...(record.ok !== undefined ? { ok: record.ok } : {}) } : { content: 'content' in record ? record.content : null };
+            const recordJson = json(record);
+            const sourceTime = entry.sourceTimestamp ?? null;
+            records.push({
+                source_type: source, source_group_id: sessionId, stable_source_record_id: stableId,
+                source_identity_kind: meta ? 'synthetic' : entry.nativeId ? 'native' : 'location',
+                source_order_id: `${meta ? '0' : '1'}|${meta ? '0000-00-00T00:00:00.000Z' : sourceTime ?? '0000-00-00T00:00:00.001Z'}|${String(sequence).padStart(20, '0')}|${stableId}`,
+                component_index: component, record_type: type, record_id: hash(json([sessionId, stableId, componentKey])),
+                record_hash: hash(recordJson), content_hash: hash(json({ type, content: semantic })),
+                source_timestamp: sourceTime, record_timestamp: 'timestamp' in record ? record.timestamp : null,
+                content: ['user', 'assistant', 'system', 'observation', 'reasoning'].includes(type) && 'content' in record ? record.content : null,
+                tool_call_id: call?.id ?? (record.role === 'tool' ? record.tool_call_id : null), tool_name: call?.name ?? null,
+                tool_arguments_json: call?.args ?? null, tool_result_json: record.role === 'tool' ? record.content : null,
+                tool_result_ok: record.role === 'tool' ? record.ok ?? null : null, record_json: recordJson,
+            });
+        }
+    }
+    return { records, diagnostics, normalizer_version: 'trajectories/0.1.0', canonical_schema_version: CANONICAL_SCHEMA_VERSION,
+        config: { bounds: { toolArguments: { maxCharacters: null }, toolResults: { maxCharacters: null, strategy: 'head' } }, filters: { systemMessages: 'include', toolResults: 'include' } } };
+}

package/dist/readers/cline.d.ts

@@ -0,0 +1,10 @@
+import type { CanonicalResult } from '@letta-ai/trajectory';
+/** Cline Core messages.json and @cline/agents AgentMessage[] (0.0.79).
+ * Both are native formats; the Vercel adapter persists the latter as history.json.
+ */
+export declare function readCline(raw: string, metadata?: {
+    sessionId?: string;
+    cwd?: string;
+    model?: string;
+}): CanonicalResult;
+export declare function assertClinePortable(raw: string): void;

package/dist/readers/cline.js

@@ -0,0 +1,107 @@
+import { createHash } from 'node:crypto';
+import { canonicalFromRecords } from './canonical.js';
+import { toolNames } from '../writers/helpers.js';
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const epoch = '1970-01-01T00:00:00.000Z';
+/** Cline Core messages.json and @cline/agents AgentMessage[] (0.0.79).
+ * Both are native formats; the Vercel adapter persists the latter as history.json.
+ */
+export function readCline(raw, metadata = {}) {
+    const data = JSON.parse(raw);
+    const messages = Array.isArray(data) ? data : data?.messages;
+    if (!Array.isArray(messages) || !messages.length)
+        throw new Error('Cline history requires native messages.');
+    if (!Array.isArray(data) && data.version !== 1)
+        throw new Error('Unsupported Cline messages file version.');
+    for (const value of [metadata.sessionId, data.sessionId]) {
+        if (value !== undefined && (typeof value !== 'string' || !value.trim()))
+            throw new Error('Invalid Cline session identity.');
+    }
+    const id = metadata.sessionId ?? data.sessionId ?? `cline-${createHash('sha256').update(raw).digest('hex')}`;
+    if (metadata.sessionId && data.sessionId && metadata.sessionId !== data.sessionId)
+        throw new Error('Cline session identities disagree.');
+    const diagnostics = [];
+    const entries = [{ record: { role: 'meta', source: 'cline', ...(metadata.cwd ? { cwd: metadata.cwd } : {}), ...(metadata.model ? { model: metadata.model } : {}) } }];
+    if (data.origin?.sessionId !== undefined && data.origin.sessionId !== id)
+        throw new Error('Cline origin session identity disagrees with its history.');
+    if (typeof data.system_prompt === 'string' && data.system_prompt)
+        entries.push({ record: { role: 'system', content: data.system_prompt, timestamp: epoch } });
+    const add = (record, message, index, part, sourceTimestamp) => entries.push({ record, ...(message.id ? { nativeId: `${message.id}:${part}` } : {}), sourceSequence: entries.length, ...(sourceTimestamp ? { sourceTimestamp } : {}) });
+    for (const [index, unknown] of messages.entries()) {
+        if (!object(unknown) || !['user', 'assistant', 'tool'].includes(unknown.role))
+            throw new Error(`Invalid Cline message ${index}.`);
+        const message = unknown;
+        if (message.id !== undefined && (typeof message.id !== 'string' || !message.id.trim()))
+            throw new Error('Invalid Cline message identity.');
+        if (message.sessionId !== undefined && message.sessionId !== id)
+            throw new Error('Cline message session identity disagrees with its history.');
+        const at = message.createdAt ?? message.ts;
+        const sourceTimestamp = typeof at === 'number' && Number.isFinite(at) ? new Date(at).toISOString() : undefined;
+        const timestamp = sourceTimestamp ?? epoch;
+        if (!sourceTimestamp)
+            diagnostics.push({ code: 'timestamps_synthesized', message: `Cline message ${index} has no native timestamp.`, inputLine: index + 1 });
+        const parts = typeof message.content === 'string' ? [{ type: 'text', text: message.content }] : message.content;
+        if (!Array.isArray(parts))
+            throw new Error(`Invalid Cline content at message ${index}.`);
+        for (const [partIndex, part] of parts.entries()) {
+            if (!object(part))
+                throw new Error('Invalid Cline content block.');
+            if (part.type === 'text') {
+                if (typeof part.text !== 'string' || message.role === 'tool')
+                    throw new Error('Invalid Cline text block.');
+                add({ role: message.role, content: part.text, timestamp }, message, index, partIndex, sourceTimestamp);
+            }
+            else if (part.type === 'thinking' || part.type === 'reasoning') {
+                const content = part.thinking ?? part.text;
+                if (typeof content !== 'string')
+                    throw new Error('Invalid Cline reasoning block.');
+                add({ role: 'reasoning', content, timestamp }, message, index, partIndex, sourceTimestamp);
+            }
+            else if (part.type === 'tool_use' || part.type === 'tool-call') {
+                const callId = part.tool_use_id ?? part.toolCallId ?? part.id;
+                const name = part.toolName ?? part.name;
+                if (message.role !== 'assistant' || typeof callId !== 'string' || !callId || typeof name !== 'string' || !name || !object(part.input))
+                    throw new Error('Invalid Cline tool call.');
+                add({ role: 'assistant', content: null, tool_calls: [{ id: callId, name, args: JSON.stringify(part.input) }], timestamp }, message, index, partIndex, sourceTimestamp);
+            }
+            else if (part.type === 'tool_result' || part.type === 'tool-result') {
+                const callId = part.toolCallId ?? part.tool_use_id;
+                const output = part.type === 'tool-result' ? part.output : part.content;
+                const isError = part.isError ?? part.is_error;
+                if (!['user', 'tool'].includes(message.role) || typeof callId !== 'string' || !callId || output === undefined)
+                    throw new Error('Invalid Cline tool result.');
+                const content = typeof output === 'string' ? output : Array.isArray(output) && output.every(item => object(item) && item.type === 'text' && typeof item.text === 'string') ? output.map(item => item.text).join('\n') : JSON.stringify(output);
+                // Canonical tool content is text; raw retains the original structured output.
+                add({ role: 'tool', tool_call_id: callId, content, ...(typeof isError === 'boolean' ? { ok: !isError } : {}), timestamp }, message, index, partIndex, sourceTimestamp);
+            }
+            else
+                throw new Error(`Unsupported Cline content block: ${String(part.type)}. Raw input remains available to the caller.`);
+        }
+    }
+    return canonicalFromRecords('cline', id, entries, diagnostics);
+}
+export function assertClinePortable(raw) {
+    const data = JSON.parse(raw);
+    for (const message of Array.isArray(data) ? data : data.messages ?? []) {
+        if (message.metadata?.displayOnly || message.metadata?.compaction || message.metadata?.compactionSummary)
+            throw new Error('Unsupported Cline compaction/display-only history requires native context reconstruction.');
+        for (const part of Array.isArray(message.content) ? message.content : []) {
+            if (['signature', 'call_id', 'details', 'summary'].some(key => part[key] !== undefined))
+                throw new Error('Cline provider replay state requires native context reconstruction.');
+            if (!['tool_result', 'tool-result'].includes(part.type))
+                continue;
+            const output = part.type === 'tool-result' ? part.output : part.content;
+            const textBlocks = Array.isArray(output) && output.every(block => object(block) && block.type === 'text' && typeof block.text === 'string');
+            // Pinned Core read_files emits ToolOperationResult[], including plain text reads.
+            const operationResults = Array.isArray(output) && output.every(block => object(block) &&
+                typeof block.query === 'string' && typeof block.result === 'string' && typeof block.success === 'boolean' &&
+                (block.error === undefined || typeof block.error === 'string') &&
+                (block.duration === undefined || typeof block.duration === 'number' && Number.isFinite(block.duration) && block.duration >= 0) &&
+                Object.keys(block).every(key => ['query', 'result', 'success', 'error', 'duration'].includes(key)));
+            if ((Array.isArray(output) && !textBlocks && !operationResults) || (object(output) && ['image', 'file', 'media', 'audio', 'video'].includes(output.type)))
+                throw new Error('Cline media or unsupported structured tool results require native context reconstruction.');
+        }
+    }
+    const canonical = readCline(raw);
+    toolNames(canonical.records.map(record => JSON.parse(record.record_json)));
+}

package/dist/readers/cursor.d.ts

@@ -0,0 +1,20 @@
+import { type CanonicalResult } from '@letta-ai/trajectory';
+export interface CursorNativeReadResult {
+    raw: string;
+    canonical: CanonicalResult;
+    nativeSessionId: string;
+    attachments: Array<{
+        name: string;
+        content: string;
+        sha256: string;
+    }>;
+}
+export declare function readCursor(raw: string): CanonicalResult;
+/** Guard used before treating a Cursor readout as resumable active context. */
+export declare function assertCursorPortable(raw: string): void;
+/**
+ * Read one Cursor CLI/ACP SQLite session without mutating it. `raw` is a
+ * deterministic, lossless row/blob readout rather than the SQLite container's
+ * page bytes; the original store remains untouched.
+ */
+export declare function readCursorNative(path: string, nativeSessionId?: string): Promise<CursorNativeReadResult>;

package/dist/readers/cursor.js

@@ -0,0 +1,374 @@
+import { createHash } from 'node:crypto';
+import { readFile, stat } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
+import { normalizeToCanonical } from '@letta-ai/trajectory';
+import { canonicalFromRecords } from './canonical.js';
+const FORMAT = 'cursor-agent-sqlite-readout-v1';
+export function readCursor(raw) {
+    let readout;
+    try {
+        readout = JSON.parse(raw);
+    }
+    catch {
+        return fail('readout JSON is invalid');
+    }
+    if (readout?.format !== FORMAT || readout.source?.runtime !== 'cursor-agent' || readout.source?.schema !== 1) {
+        fail('unsupported readout format');
+    }
+    if (typeof readout.sessionId !== 'string' || !readout.sessionId || typeof readout.metadataHex !== 'string' ||
+        !Array.isArray(readout.metaRows) || !Array.isArray(readout.blobs))
+        fail('readout shape is invalid');
+    const metadataRow = readout.metaRows.find(row => row.key === '0');
+    if (!metadataRow || metadataRow.value.toLowerCase() !== readout.metadataHex.toLowerCase())
+        fail('readout metadata rows conflict');
+    let metadata;
+    try {
+        metadata = JSON.parse(Buffer.from(readout.metadataHex, 'hex').toString('utf8'));
+    }
+    catch {
+        return fail('readout metadata JSON is invalid');
+    }
+    if (metadata.agentId !== readout.sessionId || typeof metadata.latestRootBlobId !== 'string' ||
+        metadata.latestRootBlobId.toLowerCase() !== readout.rootBlobId)
+        fail('readout identity conflicts with metadata');
+    const seen = new Set();
+    for (const blob of readout.blobs) {
+        if (seen.has(blob.id) || !/^[0-9a-f]{64}$/.test(blob.id) || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(blob.dataBase64) ||
+            createHash('sha256').update(Buffer.from(blob.dataBase64, 'base64')).digest('hex') !== blob.id) {
+            fail(`blob ${blob.id} is corrupt`);
+        }
+        seen.add(blob.id);
+    }
+    const transcript = decodeStore(readout);
+    const normalized = normalizeToCanonical({ source: 'cursor', transcript, sourceContext: { groupId: readout.sessionId },
+        bounds: { toolArguments: { maxCharacters: null }, toolResults: { maxCharacters: null } },
+        filters: { systemMessages: 'include', toolResults: 'include' } });
+    const decoded = normalized.records.map(record => JSON.parse(record.record_json)).filter(record => record.role !== 'meta');
+    return canonicalFromRecords('cursor', readout.sessionId, [
+        { record: { role: 'meta', source: 'cursor', ...(readout.provenance?.cwd ? { cwd: readout.provenance.cwd } : {}),
+                ...(typeof metadata.lastUsedModel === 'string' ? { model: metadata.lastUsedModel } : {}) }, sourceSequence: 0 },
+        ...decoded.map((record, index) => ({ record, sourceSequence: index + 1 })),
+    ], normalized.diagnostics);
+}
+/** Guard used before treating a Cursor readout as resumable active context. */
+export function assertCursorPortable(raw) { readCursor(raw); }
+function fail(message) { throw new Error(`Cursor native store: ${message}`); }
+function hex(bytes) { return Buffer.from(bytes).toString('hex'); }
+function fields(bytes) {
+    const output = [];
+    let offset = 0;
+    const varint = () => {
+        let value = 0n;
+        let shift = 0n;
+        while (offset < bytes.length && shift <= 63n) {
+            const byte = bytes[offset++];
+            value |= BigInt(byte & 0x7f) << shift;
+            if ((byte & 0x80) === 0)
+                return value;
+            shift += 7n;
+        }
+        return fail('invalid protobuf varint');
+    };
+    while (offset < bytes.length) {
+        const tag = varint();
+        const number = Number(tag >> 3n);
+        const wire = Number(tag & 7n);
+        if (!number)
+            fail('invalid protobuf field number');
+        if (wire === 0)
+            output.push({ number, wire, value: varint() });
+        else if (wire === 1) {
+            if (offset + 8 > bytes.length)
+                fail('truncated fixed64 field');
+            output.push({ number, wire, value: bytes.slice(offset, offset += 8) });
+        }
+        else if (wire === 2) {
+            const length = Number(varint());
+            if (!Number.isSafeInteger(length) || length < 0 || offset + length > bytes.length)
+                fail('truncated length-delimited field');
+            output.push({ number, wire, value: bytes.slice(offset, offset += length) });
+        }
+        else if (wire === 5) {
+            if (offset + 4 > bytes.length)
+                fail('truncated fixed32 field');
+            output.push({ number, wire, value: bytes.slice(offset, offset += 4) });
+        }
+        else
+            fail(`unsupported protobuf wire type ${wire}`);
+    }
+    return output;
+}
+function bytesOf(field, label) {
+    if (field.wire !== 2 || !(field.value instanceof Uint8Array))
+        fail(`${label} has the wrong protobuf type`);
+    return field.value;
+}
+function fixedBytesOf(field, wire, label) {
+    if (field.wire !== wire || !(field.value instanceof Uint8Array))
+        fail(`${label} has the wrong protobuf type`);
+    return field.value;
+}
+function stringOf(field, label) {
+    return new TextDecoder('utf-8', { fatal: true }).decode(bytesOf(field, label));
+}
+function boolOf(field, label) {
+    if (field.wire !== 0 || typeof field.value !== 'bigint')
+        fail(`${label} has the wrong protobuf type`);
+    return field.value !== 0n;
+}
+function one(values, number, label, required = false) {
+    const matches = values.filter(field => field.number === number);
+    if (matches.length > 1)
+        fail(`${label} is duplicated`);
+    if (required && matches.length !== 1)
+        fail(`${label} is missing`);
+    return matches[0];
+}
+function only(values, allowed, label) {
+    const unsupported = [...new Set(values.filter(field => !allowed.has(field.number)).map(field => field.number))];
+    if (unsupported.length)
+        fail(`${label} contains unsupported field(s) ${unsupported.join(', ')}`);
+}
+function decodeJsonValue(value) {
+    const valueFields = fields(value);
+    if (valueFields.length !== 1)
+        fail('MCP argument has an invalid protobuf Value');
+    const field = valueFields[0];
+    if (field.number === 1 && field.wire === 0)
+        return null;
+    if (field.number === 2 && field.wire === 1)
+        return Buffer.from(fixedBytesOf(field, 1, 'number')).readDoubleLE(0);
+    if (field.number === 3)
+        return stringOf(field, 'string');
+    if (field.number === 4)
+        return boolOf(field, 'boolean');
+    if (field.number === 5) {
+        const object = {};
+        for (const entry of fields(bytesOf(field, 'struct')).filter(item => item.number === 1)) {
+            const pair = fields(bytesOf(entry, 'struct entry'));
+            const key = stringOf(one(pair, 1, 'struct key', true), 'struct key');
+            object[key] = decodeJsonValue(bytesOf(one(pair, 2, 'struct value', true), 'struct value'));
+        }
+        return object;
+    }
+    if (field.number === 6)
+        return fields(bytesOf(field, 'list')).filter(item => item.number === 1)
+            .map(item => decodeJsonValue(bytesOf(item, 'list value')));
+    return fail(`unsupported protobuf Value field ${field.number}`);
+}
+function decodeMcpContent(item) {
+    const content = fields(item);
+    only(content, new Set([1]), 'MCP result content');
+    const text = one(content, 1, 'MCP text content', true);
+    const textFields = fields(bytesOf(text, 'MCP text content'));
+    only(textFields, new Set([1, 2]), 'MCP text');
+    return stringOf(one(textFields, 1, 'MCP text', true), 'MCP text');
+}
+function decodeMcpTool(value, outerId) {
+    const call = fields(value);
+    only(call, new Set([1, 2, 3]), 'MCP tool call');
+    const args = fields(bytesOf(one(call, 1, 'MCP args', true), 'MCP args'));
+    only(args, new Set([1, 2, 3, 4, 5]), 'MCP args');
+    const id = one(args, 3, 'MCP tool call ID') ? stringOf(one(args, 3, 'MCP tool call ID'), 'MCP tool call ID') : outerId;
+    if (!id || (outerId && id !== outerId))
+        fail('MCP tool call IDs conflict');
+    const nameField = one(args, 5, 'MCP tool name') ?? one(args, 1, 'MCP name');
+    if (!nameField)
+        fail('MCP tool name is missing');
+    const object = {};
+    for (const entry of args.filter(field => field.number === 2)) {
+        const pair = fields(bytesOf(entry, 'MCP argument'));
+        const key = stringOf(one(pair, 1, 'MCP argument key', true), 'MCP argument key');
+        object[key] = decodeJsonValue(bytesOf(one(pair, 2, 'MCP argument value', true), 'MCP argument value'));
+    }
+    const result = fields(bytesOf(one(call, 2, 'MCP result', true), 'MCP result'));
+    if (result.length !== 1)
+        fail('MCP result has no single terminal outcome');
+    const terminal = result[0];
+    if (terminal.number === 1) {
+        const success = fields(bytesOf(terminal, 'MCP success'));
+        only(success, new Set([1, 2, 3, 4]), 'MCP success');
+        const content = success.filter(field => field.number === 1).map(field => decodeMcpContent(bytesOf(field, 'MCP content'))).join('\n');
+        return { id, name: stringOf(nameField, 'MCP tool name'), args: JSON.stringify(object), result: content,
+            ok: !(one(success, 2, 'MCP is_error') && boolOf(one(success, 2, 'MCP is_error'), 'MCP is_error')) };
+    }
+    if ([2, 3, 4, 5, 6].includes(terminal.number)) {
+        const failure = fields(bytesOf(terminal, 'MCP failure'));
+        const reason = one(failure, 1, 'MCP failure reason');
+        return { id, name: stringOf(nameField, 'MCP tool name'), args: JSON.stringify(object),
+            result: reason ? stringOf(reason, 'MCP failure reason') : `Cursor MCP outcome ${terminal.number}`, ok: false };
+    }
+    return fail(`unsupported MCP result outcome ${terminal.number}`);
+}
+function decodeShellTool(encoded, outerId) {
+    const call = fields(encoded);
+    only(call, new Set([1, 2, 3]), 'shell tool call');
+    const args = fields(bytesOf(one(call, 1, 'shell args', true), 'shell args'));
+    only(args, new Set([1, 2, 3, 4, 5, 6, 7, 11, 12, 14, 15, 17, 21, 22, 23, 24]), 'shell args');
+    const nestedId = one(args, 4, 'shell tool call ID');
+    const id = nestedId ? stringOf(nestedId, 'shell tool call ID') : outerId;
+    if (!id || (outerId && id !== outerId))
+        fail('shell tool call IDs conflict');
+    const command = stringOf(one(args, 1, 'shell command', true), 'shell command');
+    const cwd = one(args, 2, 'shell cwd');
+    const result = fields(bytesOf(one(call, 2, 'shell result', true), 'shell result'));
+    if (result.length !== 1)
+        fail('shell result has no single terminal outcome');
+    const terminal = result[0];
+    const payload = fields(bytesOf(terminal, 'shell terminal result'));
+    const value = (number, label) => one(payload, number, label) ? stringOf(one(payload, number, label), label) : '';
+    const output = terminal.number === 1 || terminal.number === 2
+        ? JSON.stringify({ command: value(1, 'shell result command'), workingDirectory: value(2, 'shell result cwd'),
+            exitCode: one(payload, 3, 'shell exit code')?.value ? Number(one(payload, 3, 'shell exit code').value) : 0,
+            signal: value(4, 'shell signal'), stdout: value(5, 'shell stdout'), stderr: value(6, 'shell stderr') })
+        : value(3, 'shell failure reason') || value(1, 'shell failure command') || `Cursor shell outcome ${terminal.number}`;
+    return { id, name: 'shell', args: JSON.stringify({ command, ...(cwd ? { workingDirectory: stringOf(cwd, 'shell cwd') } : {}) }),
+        result: output, ok: terminal.number === 1 };
+}
+function decodeTool(value) {
+    const call = fields(value);
+    const outerId = one(call, 57, 'tool call ID');
+    const id = outerId ? stringOf(outerId, 'tool call ID') : undefined;
+    const tools = call.filter(field => field.number !== 54 && field.number !== 57 && field.number !== 59 && field.number !== 60);
+    if (tools.length !== 1)
+        fail('tool call has no single supported tool payload');
+    const tool = tools[0];
+    if (tool.number === 15)
+        return decodeMcpTool(bytesOf(tool, 'MCP tool'), id);
+    if (tool.number === 1)
+        return decodeShellTool(bytesOf(tool, 'shell tool'), id);
+    return fail(`unsupported Cursor tool kind field ${tool.number}`);
+}
+function decodeStore(readout) {
+    const blobs = new Map(readout.blobs.map(blob => [blob.id, Buffer.from(blob.dataBase64, 'base64')]));
+    const load = (id, label) => blobs.get(hex(id)) ?? fail(`missing ${label} blob ${hex(id)}`);
+    const root = fields(blobs.get(readout.rootBlobId) ?? fail('missing root blob'));
+    const compacted = root.some(field => [6, 11, 13, 37].includes(field.number));
+    const branched = root.some(field => [16, 19, 21, 24, 29, 30, 31].includes(field.number));
+    if (compacted)
+        fail('compacted conversations are not importable without loss');
+    if (branched)
+        fail('branched or subagent conversations require an explicit branch-aware reader');
+    only(root, new Set([8, 10, 26, 27, 33]), 'conversation root');
+    const rows = [];
+    let sequence = 0;
+    for (const turnRef of root.filter(field => field.number === 8)) {
+        const turn = fields(load(bytesOf(turnRef, 'turn reference'), 'turn'));
+        only(turn, new Set([1]), 'conversation turn');
+        const agent = fields(bytesOf(one(turn, 1, 'agent turn', true), 'agent turn'));
+        only(agent, new Set([1, 2, 3]), 'agent turn');
+        const user = fields(load(bytesOf(one(agent, 1, 'user reference', true), 'user reference'), 'user'));
+        only(user, new Set([1, 2, 10, 25, 26]), 'user message');
+        const userText = stringOf(one(user, 1, 'user text', true), 'user text');
+        rows.push({ id: `cursor-import-user-${++sequence}`, role: 'user', message: { content: [{ type: 'text', text: userText }] } });
+        for (const stepRef of agent.filter(field => field.number === 2)) {
+            const step = fields(load(bytesOf(stepRef, 'step reference'), 'conversation step'));
+            if (step.length !== 1)
+                fail('conversation step has no single message');
+            const message = step[0];
+            if (message.number === 1) {
+                const assistant = fields(bytesOf(message, 'assistant message'));
+                only(assistant, new Set([1, 2, 3]), 'assistant message');
+                rows.push({ id: `cursor-import-assistant-${++sequence}`, role: 'assistant',
+                    message: { content: [{ type: 'text', text: stringOf(one(assistant, 1, 'assistant text', true), 'assistant text') }] } });
+            }
+            else if (message.number === 3) {
+                const thought = fields(bytesOf(message, 'thinking message'));
+                only(thought, new Set([1, 2, 3, 4]), 'thinking message');
+                rows.push({ id: `cursor-import-thinking-${++sequence}`, role: 'assistant',
+                    message: { content: [{ type: 'thinking', thinking: stringOf(one(thought, 1, 'thinking text', true), 'thinking text') }] } });
+            }
+            else if (message.number === 2) {
+                const tool = decodeTool(bytesOf(message, 'tool call'));
+                rows.push({ id: `cursor-import-tool-${++sequence}`, role: 'assistant', message: { content: [
+                            { type: 'tool_use', id: tool.id, name: tool.name, input: JSON.parse(tool.args) },
+                            { type: 'tool_result', tool_use_id: tool.id, content: tool.result, is_error: !tool.ok },
+                        ] } });
+            }
+            else
+                fail(`unsupported conversation step field ${message.number}`);
+        }
+    }
+    return rows.map(row => JSON.stringify(row)).join('\n') + '\n';
+}
+async function storePath(path) {
+    const resolved = resolve(path);
+    const info = await stat(resolved);
+    if (info.isFile()) {
+        if (basename(resolved) !== 'store.db')
+            fail('file input must be a Cursor store.db');
+        return resolved;
+    }
+    if (!info.isDirectory())
+        fail('input is neither a store.db nor its session directory');
+    const candidate = join(resolved, 'store.db');
+    if (!(await stat(candidate).catch(() => null))?.isFile())
+        fail('directory has no direct store.db; select one native session directory');
+    return candidate;
+}
+/**
+ * Read one Cursor CLI/ACP SQLite session without mutating it. `raw` is a
+ * deterministic, lossless row/blob readout rather than the SQLite container's
+ * page bytes; the original store remains untouched.
+ */
+export async function readCursorNative(path, nativeSessionId) {
+    const { DatabaseSync } = await import('node:sqlite');
+    const dbPath = await storePath(path);
+    const db = new DatabaseSync(dbPath, { readOnly: true });
+    let metadataHex;
+    let metaRows;
+    let blobs;
+    try {
+        db.exec('PRAGMA query_only = ON');
+        const tables = db.prepare("SELECT name FROM sqlite_schema WHERE type='table' AND name IN ('blobs','meta') ORDER BY name").all();
+        if (tables.map(row => row.name).join(',') !== 'blobs,meta')
+            fail('unsupported SQLite schema');
+        const version = Number(db.prepare('PRAGMA user_version').get().user_version);
+        if (version !== 1)
+            fail(`unsupported SQLite user_version ${version}`);
+        metaRows = db.prepare('SELECT key, value FROM meta ORDER BY key').all().map(row => {
+            if (typeof row.key !== 'string' || typeof row.value !== 'string')
+                fail('invalid metadata row');
+            return { key: row.key, value: row.value };
+        });
+        const meta = metaRows.find(row => row.key === '0');
+        if (!meta || !/^(?:[0-9a-f]{2})+$/i.test(meta.value))
+            fail('metadata row is missing or invalid');
+        metadataHex = meta.value.toLowerCase();
+        blobs = db.prepare('SELECT id, data FROM blobs ORDER BY id').all().map(row => {
+            if (typeof row.id !== 'string' || !/^[0-9a-f]{64}$/i.test(row.id) || !(row.data instanceof Uint8Array))
+                fail('invalid blob row');
+            return { id: row.id.toLowerCase(), dataBase64: Buffer.from(row.data).toString('base64') };
+        });
+    }
+    finally {
+        db.close();
+    }
+    let metadata;
+    try {
+        metadata = JSON.parse(Buffer.from(metadataHex, 'hex').toString('utf8'));
+    }
+    catch {
+        return fail('metadata JSON is invalid');
+    }
+    if (typeof metadata.agentId !== 'string' || !metadata.agentId)
+        fail('metadata has no agentId');
+    if (nativeSessionId !== undefined && metadata.agentId !== nativeSessionId)
+        fail('selected session ID does not match store metadata');
+    if (typeof metadata.latestRootBlobId !== 'string' || !/^[0-9a-f]{64}$/i.test(metadata.latestRootBlobId))
+        fail('metadata has no valid root blob ID');
+    const readout = { format: FORMAT,
+        source: { runtime: 'cursor-agent', schema: 1, store: basename(dbPath) }, sessionId: metadata.agentId,
+        metadataHex, metaRows, rootBlobId: metadata.latestRootBlobId.toLowerCase(), blobs };
+    const sidecar = await readFile(join(dirname(dbPath), 'meta.json'), 'utf8').then(value => JSON.parse(value)).catch(() => null);
+    if (typeof sidecar?.cwd === 'string' && sidecar.cwd)
+        readout.provenance = { cwd: sidecar.cwd };
+    const raw = JSON.stringify(readout, null, 2) + '\n';
+    const transcript = decodeStore(readout);
+    const canonical = readCursor(raw);
+    if (canonical.diagnostics.some(diagnostic => diagnostic.code === 'invalid_json_line' || diagnostic.code === 'non_object_json_line')) {
+        fail('generated capture did not normalize cleanly');
+    }
+    return { raw, canonical, nativeSessionId: metadata.agentId, attachments: [{ name: 'cursor-capture.jsonl', content: transcript,
+                sha256: createHash('sha256').update(transcript).digest('hex') }] };
+}