trajectories 0.1.2 → 0.1.4

package/dist/shared-observed.js

@@ -0,0 +1,286 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { TrajectoriesError } from './log-types.js';
+import { validateTranscript } from '@letta-ai/trajectory';
+import { digest, getObject, safeId, stableJson, withSessionLock } from './log-io.js';
+export function sharedObservationId(machineId, sessionId) {
+    safeId(machineId);
+    if (typeof sessionId !== 'string' || !sessionId || sessionId.length > 4096)
+        throw new TrajectoriesError('INVALID_INPUT', 'An indexed session identity is required.');
+    return digest(stableJson([machineId, sessionId]));
+}
+const hash = (value) => {
+    if (typeof value !== 'string' || !/^[a-f0-9]{64}$/.test(value))
+        throw new TrajectoriesError('INVALID_INPUT', 'Invalid shared content identity.');
+    return value;
+};
+const observationPath = (store, id) => join(resolve(store), 'observations', `${hash(id)}.jsonl`);
+function assertSession(value) {
+    if (!value || typeof value !== 'object' || typeof value.id !== 'string' || !value.id
+        || typeof value.source !== 'string' || !value.source || typeof value.source_path !== 'string'
+        || typeof value.content_hash !== 'string' || !Number.isSafeInteger(value.record_count) || value.record_count < 0
+        || typeof value.created_at !== 'string' || typeof value.updated_at !== 'string')
+        throw new TrajectoriesError('INVALID_INPUT', 'Invalid canonical observed session metadata.');
+    for (const key of ['title', 'cwd', 'model', 'started_at', 'ended_at'])
+        if (value[key] !== null && typeof value[key] !== 'string')
+            throw new TrajectoriesError('INVALID_INPUT', `Invalid session ${key}.`);
+    for (const key of ['parent_session_id', 'parent_tool_use_id', 'agent_nickname', 'thread_role'])
+        if (value[key] !== undefined && value[key] !== null && typeof value[key] !== 'string')
+            throw new TrajectoriesError('INVALID_INPUT', `Invalid session ${key}.`);
+    if (value.content_hash_version !== undefined && ![1, 2].includes(value.content_hash_version))
+        throw new TrajectoriesError('INVALID_INPUT', 'Invalid observed hash version.');
+    if (value.diagnostics !== undefined) {
+        if (!Array.isArray(value.diagnostics))
+            throw new TrajectoriesError('INVALID_INPUT', 'Invalid observed diagnostics.');
+        const codes = new Set();
+        for (const item of value.diagnostics) {
+            if (!item || typeof item.code !== 'string' || !item.code || codes.has(item.code)
+                || !Number.isSafeInteger(item.occurrenceCount) || item.occurrenceCount < 0
+                || (item.sample !== null && typeof item.sample !== 'string')
+                || (item.firstSeenAt !== undefined && typeof item.firstSeenAt !== 'string'))
+                throw new TrajectoriesError('INVALID_INPUT', 'Invalid observed diagnostic aggregate.');
+            codes.add(item.code);
+        }
+    }
+}
+function assertRecord(value, sessionId) {
+    if (!value || typeof value !== 'object' || typeof value.id !== 'string' || !value.id
+        || value.session_id !== sessionId || typeof value.source_type !== 'string' || typeof value.record_type !== 'string'
+        || typeof value.source_order_id !== 'string' || !Number.isSafeInteger(value.component_index) || value.component_index < 0
+        || typeof value.record_hash !== 'string' || typeof value.content_hash !== 'string' || typeof value.record_json !== 'string')
+        throw new TrajectoriesError('INVALID_INPUT', 'Invalid canonical observed record or session identity.');
+    for (const key of ['content', 'tool_call_id', 'tool_name', 'tool_arguments_json', 'tool_result_json',
+        'record_timestamp', 'source_timestamp', 'stable_source_record_id', 'source_identity_kind'])
+        if (value[key] !== null && typeof value[key] !== 'string')
+            throw new TrajectoriesError('INVALID_INPUT', `Invalid record ${key}.`);
+    if (![null, 0, 1].includes(value.tool_result_ok))
+        throw new TrajectoriesError('INVALID_INPUT', 'Invalid tool outcome.');
+    if (value.source_identity_kind !== null && !['native', 'location', 'content', 'synthetic'].includes(value.source_identity_kind))
+        throw new TrajectoriesError('INVALID_INPUT', 'Invalid source identity kind.');
+    for (const key of ['native_session_id', 'binding_id'])
+        if (value[key] !== undefined && value[key] !== null && typeof value[key] !== 'string')
+            throw new TrajectoriesError('INVALID_INPUT', 'Invalid native lineage identity.');
+    let parsed;
+    try {
+        parsed = JSON.parse(value.record_json);
+    }
+    catch {
+        throw new TrajectoriesError('INVALID_INPUT', 'Malformed canonical record JSON.');
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        throw new TrajectoriesError('INVALID_INPUT', 'Canonical record JSON must be an object.');
+    try {
+        validateTranscript([parsed], { partial: true });
+    }
+    catch {
+        throw new TrajectoriesError('INVALID_INPUT', 'Invalid normalized canonical record.');
+    }
+    const record = parsed;
+    if (value.record_type !== (record.role === 'assistant' && record.tool_calls ? 'assistant-tool-call' : record.role)
+        || digest(value.record_json) !== value.record_hash)
+        throw new TrajectoriesError('INTEGRITY_ERROR', 'Canonical record type or digest disagrees with its payload.');
+}
+export function assertObservedSummary(value, id) {
+    if (!value || typeof value !== 'object')
+        throw new TrajectoriesError('INVALID_INPUT', 'Invalid shared observation.');
+    assertSession(value.session);
+    hash(value.head);
+    if ((id !== undefined && value.id !== id) || value.id !== sharedObservationId(value.machineId, value.session.id))
+        throw new TrajectoriesError('INTEGRITY_ERROR', 'Shared observation identity mismatch.');
+}
+export function assertObservedManifest(value, id) {
+    assertObservedSummary(value, id);
+    if (!Array.isArray(value.recordObjects))
+        throw new TrajectoriesError('INVALID_INPUT', 'Invalid shared record manifest.');
+    const ids = new Set();
+    for (const ref of value.recordObjects) {
+        if (!ref || typeof ref.id !== 'string' || !ref.id || ids.has(ref.id))
+            throw new TrajectoriesError('INVALID_INPUT', 'Invalid shared record identities.');
+        ids.add(ref.id);
+        hash(ref.object);
+    }
+    if (ids.size !== value.session.record_count)
+        throw new TrajectoriesError('INTEGRITY_ERROR', 'Shared manifest count mismatch.');
+}
+export function assertObservedState(value, id) {
+    assertObservedSummary(value, id);
+    if (!Array.isArray(value.records))
+        throw new TrajectoriesError('INVALID_INPUT', 'Invalid shared canonical records.');
+    const ids = new Set();
+    for (const record of value.records) {
+        assertRecord(record, value.session.id);
+        if (ids.has(record.id))
+            throw new TrajectoriesError('INVALID_INPUT', 'Duplicate shared canonical record.');
+        ids.add(record.id);
+    }
+    if (ids.size !== value.session.record_count)
+        throw new TrajectoriesError('INTEGRITY_ERROR', 'Shared record count mismatch.');
+}
+async function frames(store, id) {
+    let text;
+    try {
+        text = await readFile(observationPath(store, id), 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    if (!text.endsWith('\n'))
+        throw new TrajectoriesError('INTEGRITY_ERROR', 'Partial observed-history log.');
+    const output = [];
+    for (const line of text.trimEnd().split('\n')) {
+        let frame;
+        try {
+            frame = JSON.parse(line);
+        }
+        catch {
+            throw new TrajectoriesError('INTEGRITY_ERROR', 'Invalid observed-history JSON.');
+        }
+        const body = frame?.body;
+        if (!body || body.version !== 1 || body.id !== id || sharedObservationId(body.machineId, body.sessionId) !== id
+            || body.parent !== (output.at(-1)?.head ?? null) || digest(stableJson(body)) !== frame.head
+            || !Array.isArray(body.set) || !Array.isArray(body.remove))
+            throw new TrajectoriesError('INTEGRITY_ERROR', 'Invalid observed-history chain.');
+        output.push(frame);
+    }
+    return output;
+}
+async function materialize(store, id, history) {
+    const current = history.at(-1);
+    if (!current)
+        throw new TrajectoriesError('NOT_FOUND', 'Shared observed session not found.');
+    const refs = new Map();
+    for (const { body } of history) {
+        for (const key of body.remove)
+            refs.delete(key);
+        for (const item of body.set)
+            refs.set(item.id, hash(item.object));
+    }
+    const session = JSON.parse((await getObject(store, hash(current.body.sessionObject))).toString());
+    assertSession(session);
+    if (session.id !== current.body.sessionId || session.record_count !== refs.size)
+        throw new TrajectoriesError('INTEGRITY_ERROR', 'Observed session metadata disagrees with its record view.');
+    return { id, head: current.head, machineId: current.body.machineId, session,
+        recordObjects: [...refs].map(([recordId, object]) => ({ id: recordId, object })) };
+}
+export async function getObservedManifest(store, id) {
+    return materialize(store, id, await frames(store, id));
+}
+export async function readObservedHistory(store, id) {
+    const { recordObjects, ...summary } = await getObservedManifest(store, id);
+    const records = [];
+    for (const ref of recordObjects) {
+        const record = JSON.parse((await getObject(store, ref.object)).toString());
+        assertRecord(record, summary.session.id);
+        if (record.id !== ref.id)
+            throw new TrajectoriesError('INTEGRITY_ERROR', 'Observed record identity changed.');
+        records.push(record);
+    }
+    records.sort((a, b) => a.source_order_id < b.source_order_id ? -1 : a.source_order_id > b.source_order_id ? 1
+        : a.component_index - b.component_index || a.id.localeCompare(b.id));
+    return { ...summary, records };
+}
+export async function listObservedHistories(store) {
+    let names;
+    try {
+        names = await readdir(join(resolve(store), 'observations'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    const output = [];
+    for (const name of names.sort()) {
+        if (!/^[a-f0-9]{64}\.jsonl$/.test(name))
+            continue;
+        const { recordObjects, ...summary } = await getObservedManifest(store, name.slice(0, -6));
+        output.push(summary);
+    }
+    return output;
+}
+export async function commitObservedDelta(store, delta) {
+    if (!delta || delta.version !== 1 || delta.id !== sharedObservationId(delta.machineId, delta.sessionId)
+        || (delta.parent !== null && hash(delta.parent) !== delta.parent) || !Array.isArray(delta.set) || !Array.isArray(delta.remove))
+        throw new TrajectoriesError('INVALID_INPUT', 'Invalid observed-history delta.');
+    hash(delta.sessionObject);
+    const keys = new Set();
+    for (const item of delta.set) {
+        if (!item || typeof item.id !== 'string' || !item.id || keys.has(item.id))
+            throw new TrajectoriesError('INVALID_INPUT', 'Duplicate or invalid record identity.');
+        keys.add(item.id);
+        hash(item.object);
+    }
+    for (const key of delta.remove) {
+        if (typeof key !== 'string' || !key || keys.has(key))
+            throw new TrajectoriesError('INVALID_INPUT', 'Duplicate or contradictory record changes.');
+        keys.add(key);
+    }
+    return withSessionLock(store, delta.id, async () => {
+        const history = await frames(store, delta.id);
+        const head = digest(stableJson(delta));
+        if (history.at(-1)?.head === head) {
+            const { recordObjects, ...summary } = await materialize(store, delta.id, history);
+            return summary;
+        }
+        if ((history.at(-1)?.head ?? null) !== delta.parent)
+            throw new TrajectoriesError('STALE_HEAD', 'Shared observed history advanced; refresh before publishing.');
+        for (const item of delta.set) {
+            const record = JSON.parse((await getObject(store, item.object)).toString());
+            assertRecord(record, delta.sessionId);
+            if (record.id !== item.id)
+                throw new TrajectoriesError('INTEGRITY_ERROR', 'Observed record reference has a different identity.');
+        }
+        const prospective = [...history, { head, body: delta }];
+        const manifest = await materialize(store, delta.id, prospective);
+        // This publishes delta events only, not a whole observation snapshot.
+        const { open } = await import('node:fs/promises');
+        const { ensureDirectory, syncDirectory } = await import('./log-io.js');
+        const path = observationPath(store, delta.id);
+        await ensureDirectory(join(resolve(store), 'observations'));
+        const file = await open(path, 'a', 0o600);
+        try {
+            await file.writeFile(stableJson({ head, body: delta }) + '\n');
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+        await syncDirectory(join(resolve(store), 'observations'));
+        const { recordObjects, ...summary } = manifest;
+        return summary;
+    });
+}
+export async function prepareObservedHistory(input, previous) {
+    assertSession(input.session);
+    const id = sharedObservationId(input.machineId, input.session.id);
+    if (previous)
+        assertObservedManifest(previous, id);
+    if (previous && (previous.id !== id || previous.machineId !== input.machineId || previous.session.id !== input.session.id))
+        throw new TrajectoriesError('INTEGRITY_ERROR', 'Remote observation identity mismatch.');
+    const prior = new Map(previous?.recordObjects.map(item => [item.id, item.object]) ?? []);
+    const objects = new Map();
+    const add = (value) => { const bytes = Buffer.from(stableJson(value)); const key = digest(bytes); objects.set(key, bytes); return key; };
+    const sessionObject = add(input.session);
+    const seen = new Set();
+    const set = [];
+    for (const record of input.records) {
+        assertRecord(record, input.session.id);
+        if (seen.has(record.id))
+            throw new TrajectoriesError('INVALID_INPUT', 'Duplicate canonical record ID.');
+        seen.add(record.id);
+        const key = digest(stableJson(record));
+        if (prior.get(record.id) !== key) {
+            add(record);
+            set.push({ id: record.id, object: key });
+        }
+    }
+    if (input.session.record_count !== seen.size)
+        throw new TrajectoriesError('INVALID_INPUT', 'Session record count disagrees with canonical records.');
+    const remove = [...prior.keys()].filter(key => !seen.has(key));
+    if (previous && !set.length && !remove.length && stableJson(previous.session) === stableJson(input.session))
+        return { delta: null, objects: new Map(), changedRecords: 0, removedRecords: 0 };
+    return { delta: { version: 1, id, parent: previous?.head ?? null, machineId: input.machineId,
+            sessionId: input.session.id, sessionObject, set, remove }, objects, changedRecords: set.length, removedRecords: remove.length };
+}

package/dist/shared.d.ts

@@ -0,0 +1,40 @@
+import { type ManagedSession } from './log-types.js';
+import { type ObservedRecord, type ObservedSession, type ObservedState, type ObservedSummary } from './shared-observed.js';
+export { sharedObservationId } from './shared-observed.js';
+export type { ObservedRecord, ObservedSession, ObservedState, ObservedSummary } from './shared-observed.js';
+export type { ManagedDelta } from './shared-managed.js';
+export interface SharedTransfer {
+    id: string;
+    head: string;
+    objectsTransferred: number;
+    bytesTransferred: number;
+}
+export interface ObservedSyncReceipt extends SharedTransfer {
+    changedRecords: number;
+    removedRecords: number;
+}
+export interface ManagedSyncReceipt extends SharedTransfer {
+    framesTransferred: number;
+}
+/** Node-compatible fetch handler; the host owns sockets, TLS, credentials and process lifetime. */
+export declare function createSharedHandler(options: {
+    store: string;
+    token: string;
+    maxBytes?: number;
+}): (request: Request) => Promise<Response>;
+export declare function createSharedClient(options: {
+    url: string;
+    token: string;
+    signal?: AbortSignal;
+}): {
+    listObserved(): Promise<ObservedSummary[]>;
+    getObserved(id: string): Promise<ObservedState>;
+    listManaged(): Promise<ManagedSession[]>;
+    pushObserved(input: {
+        machineId: string;
+        session: ObservedSession;
+        records: ObservedRecord[];
+    }): Promise<ObservedSyncReceipt>;
+    pushManaged(store: string, id: string): Promise<ManagedSyncReceipt>;
+    pullManaged(store: string, id: string): Promise<ManagedSyncReceipt>;
+};