praxis-agent 0.35.0 → 0.37.0

package/dist/persistence/native-transcript-store.js

@@ -0,0 +1,321 @@
+import { createHash } from 'node:crypto';
+import { mkdir, open, readFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { ExclusiveFileLease } from '../platform/exclusive-file-lease.js';
+import { createNativeTranscriptCodec } from './native-transcript-codec.js';
+import { classifyTranscriptAppend } from './transcript-file-append.js';
+const hashLine = (line) => createHash('sha256').update(line).digest('hex');
+const emptyTail = () => ({
+    byteLength: 0,
+    lastLineHash: null,
+    lastEventId: null,
+    newlineTerminated: true,
+});
+function splitLines(source) {
+    const end = source.at(-1) === 0x0a ? source.length - 1 : source.length;
+    if (!end)
+        return [];
+    const result = [];
+    let start = 0;
+    for (let i = 0; i < end; i++) {
+        if (source[i] === 0x0a) {
+            result.push(source.subarray(start, i));
+            start = i + 1;
+        }
+    }
+    result.push(source.subarray(start, end));
+    return result;
+}
+function tailFrom(source, records) {
+    const lines = splitLines(source);
+    const line = lines.at(-1);
+    return {
+        byteLength: source.length,
+        lastLineHash: line ? hashLine(line) : null,
+        lastEventId: records.at(-1)?.event.id ?? null,
+        newlineTerminated: source.length === 0 || source.at(-1) === 0x0a,
+    };
+}
+function equalTail(a, b) {
+    return (a.byteLength === b.byteLength &&
+        a.lastLineHash === b.lastLineHash &&
+        a.lastEventId === b.lastEventId &&
+        a.newlineTerminated === b.newlineTerminated);
+}
+function logicalTail(tail) {
+    return tail.branchParentId === undefined
+        ? tail.lastEventId
+        : (tail.branchParentId ?? null);
+}
+function effectiveParentId(event) {
+    return event.kind === 'context-boundary'
+        ? event.logicalParentId
+        : event.parentId;
+}
+function validateHistory(events) {
+    const ids = new Set();
+    const sessions = new Set();
+    const calls = new Set();
+    const children = new Map();
+    for (const [index, event] of events.entries()) {
+        if (ids.has(event.id))
+            throw new Error('Invalid native transcript invariant: event IDs must be unique');
+        if (sessions.size && !sessions.has(event.sessionId))
+            throw new Error('Invalid native transcript invariant: sessionId must match history');
+        if (event.kind === 'context-boundary') {
+            if (event.parentId !== null || !ids.has(event.logicalParentId))
+                throw new Error('Invalid native transcript invariant: context boundary logicalParentId must reference history');
+        }
+        else if (event.parentId === null) {
+            if (index !== 0)
+                throw new Error('Invalid native transcript invariant: only the first logical root may have a null parentId');
+        }
+        else if (!ids.has(event.parentId)) {
+            throw new Error('Invalid native transcript invariant: event parentId must reference an earlier event');
+        }
+        const parentId = effectiveParentId(event);
+        if (parentId !== null) {
+            const siblings = children.get(parentId) ?? [];
+            siblings.push(event);
+            children.set(parentId, siblings);
+        }
+        ids.add(event.id);
+        sessions.add(event.sessionId);
+        if (event.kind !== 'messages')
+            continue;
+        for (const message of event.messages) {
+            if (message.role !== 'assistant')
+                continue;
+            for (const call of message.toolCalls ?? []) {
+                if (calls.has(call.id))
+                    throw new Error('Invalid native transcript invariant: assistant tool-call IDs must be unique');
+                calls.add(call.id);
+            }
+        }
+    }
+    const root = events[0];
+    if (!root)
+        return;
+    const activeCalls = new Set();
+    const activeResults = new Set();
+    const stack = [{ event: root, leaving: false }];
+    while (stack.length > 0) {
+        const frame = stack.pop();
+        if (!frame)
+            break;
+        if (frame.leaving) {
+            for (const id of frame.addedCalls)
+                activeCalls.delete(id);
+            for (const id of frame.addedResults)
+                activeResults.delete(id);
+            continue;
+        }
+        const addedCalls = [];
+        const addedResults = [];
+        if (frame.event.kind === 'messages') {
+            for (const message of frame.event.messages) {
+                if (message.role === 'assistant') {
+                    for (const call of message.toolCalls ?? []) {
+                        activeCalls.add(call.id);
+                        addedCalls.push(call.id);
+                    }
+                }
+                else if (message.role === 'tool') {
+                    if (!activeCalls.has(message.toolCallId))
+                        throw new Error('Invalid native transcript invariant: tool result references unknown tool call on active ancestry');
+                    if (activeResults.has(message.toolCallId))
+                        throw new Error('Invalid native transcript invariant: tool call has multiple results on active ancestry');
+                    activeResults.add(message.toolCallId);
+                    addedResults.push(message.toolCallId);
+                }
+            }
+        }
+        stack.push({
+            event: frame.event,
+            leaving: true,
+            addedCalls,
+            addedResults,
+        });
+        const descendants = children.get(frame.event.id) ?? [];
+        for (let index = descendants.length - 1; index >= 0; index -= 1) {
+            const descendant = descendants[index];
+            if (descendant)
+                stack.push({ event: descendant, leaving: false });
+        }
+    }
+}
+export class NativeTranscriptStore {
+    options;
+    lease;
+    constructor(options) {
+        this.options = options;
+        this.lease = new ExclusiveFileLease(options.lockFile);
+    }
+    async source() {
+        try {
+            return await readFile(this.options.transcriptFile);
+        }
+        catch (e) {
+            if (e.code === 'ENOENT')
+                return Buffer.alloc(0);
+            throw e;
+        }
+    }
+    decode(source, recover) {
+        if (!source.length)
+            return { records: [], tail: emptyTail(), issue: null };
+        const decoded = createNativeTranscriptCodec().decodeDocument(source);
+        if (decoded.issue && !recover)
+            throw new Error(`Invalid native transcript: ${decoded.issue.message}`);
+        if (!recover)
+            validateHistory(decoded.records.map((record) => record.event));
+        return {
+            records: decoded.records,
+            tail: tailFrom(source, decoded.records),
+            issue: decoded.issue,
+        };
+    }
+    async load() {
+        const { records, tail } = this.decode(await this.source(), false);
+        return { records, tail };
+    }
+    async loadReadOnly() {
+        return this.decode(await this.source(), true);
+    }
+    async exportReadOnly() {
+        return this.source();
+    }
+    prepare(history, events, expected) {
+        if (!events.length)
+            throw new Error('Cannot append an empty native transcript batch');
+        const all = history.map((r) => r.event);
+        const historicalIds = new Set(all.map((event) => event.id));
+        if (expected.branchParentId !== undefined &&
+            expected.branchParentId !== null &&
+            !historicalIds.has(expected.branchParentId))
+            throw new Error('Invalid native transcript invariant: branchParentId must reference an earlier event');
+        validateHistory([...history.map((record) => record.event), ...events]);
+        const ids = new Set();
+        const sessions = new Set();
+        for (const e of all) {
+            if (ids.has(e.id))
+                throw new Error('Invalid native transcript invariant: event IDs must be unique');
+            if (sessions.size && !sessions.has(e.sessionId))
+                throw new Error('Invalid native transcript invariant: sessionId must match history');
+            ids.add(e.id);
+            sessions.add(e.sessionId);
+        }
+        let parent = logicalTail(expected);
+        const lines = [];
+        for (const event of events) {
+            const codec = createNativeTranscriptCodec();
+            const encoded = codec.encodeLine(event);
+            if (!encoded.ok)
+                throw new Error(`Invalid native transcript event: ${encoded.issue.message}`);
+            if (ids.has(event.id))
+                throw new Error('Invalid native transcript invariant: event IDs must be unique');
+            if (sessions.size && !sessions.has(event.sessionId))
+                throw new Error('Invalid native transcript invariant: sessionId must match history');
+            sessions.add(event.sessionId);
+            if (event.kind === 'context-boundary') {
+                if (event.parentId !== null || !ids.has(event.logicalParentId))
+                    throw new Error('Invalid native transcript invariant: context boundary logicalParentId must reference history');
+                parent = event.id;
+            }
+            else if (event.parentId !== parent)
+                throw new Error('Invalid native transcript invariant: event parentId does not match logical tail');
+            lines.push(Buffer.from(`${encoded.line}\n`));
+            ids.add(event.id);
+            parent = event.id;
+        }
+        return Buffer.concat(lines);
+    }
+    async create(events) {
+        const bytes = this.prepare([], events, emptyTail());
+        await mkdir(dirname(this.options.transcriptFile), { recursive: true });
+        let handle;
+        try {
+            handle = await open(this.options.transcriptFile, 'wx', 0o600);
+        }
+        catch (e) {
+            if (e.code === 'EEXIST')
+                return { status: 'conflict', reason: 'already-exists' };
+            throw e;
+        }
+        try {
+            await handle.writeFile(bytes);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        return { status: 'created', tail: (await this.load()).tail };
+    }
+    async reserveUnderLease() {
+        await mkdir(dirname(this.options.transcriptFile), { recursive: true });
+        let handle;
+        try {
+            handle = await open(this.options.transcriptFile, 'wx', 0o600);
+        }
+        catch (e) {
+            if (e.code === 'EEXIST')
+                return { status: 'conflict', reason: 'already-exists' };
+            throw e;
+        }
+        try {
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        return { status: 'reserved' };
+    }
+    async withLease(operation) {
+        const lock = await this.lease.tryAcquire();
+        if (!lock)
+            return { status: 'conflict', reason: 'locked' };
+        try {
+            const value = await operation({
+                reserve: () => this.reserveUnderLease(),
+                load: () => this.load(),
+                append: (tail, event) => this.appendUnderLease(tail, [event]),
+                appendMany: (tail, events) => this.appendUnderLease(tail, events),
+            });
+            return { status: 'completed', value };
+        }
+        finally {
+            await lock.release();
+        }
+    }
+    async appendUnderLease(expected, events) {
+        const current = await this.load();
+        if (!equalTail(current.tail, expected))
+            return { status: 'conflict', reason: 'tail-changed' };
+        if (!current.tail.newlineTerminated)
+            throw new Error('Invalid native transcript: file is not newline-terminated');
+        const bytes = this.prepare(current.records, events, expected);
+        await mkdir(dirname(this.options.transcriptFile), { recursive: true });
+        const handle = await open(this.options.transcriptFile, 'a');
+        try {
+            const stat = await handle.stat();
+            if (stat.size !== expected.byteLength)
+                return { status: 'conflict', reason: 'tail-changed' };
+            await handle.writeFile(bytes);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        const written = await readFile(this.options.transcriptFile);
+        if (classifyTranscriptAppend(written, expected.byteLength, bytes) ===
+            'interleaved-write')
+            return { status: 'conflict', reason: 'interleaved-write' };
+        const tail = (await this.load()).tail;
+        return { status: 'appended', tail };
+    }
+    async append(expectedTail, event) {
+        const result = await this.withLease((lease) => lease.append(expectedTail, event));
+        return result.status === 'completed' ? result.value : result;
+    }
+}
+//# sourceMappingURL=native-transcript-store.js.map

package/dist/persistence/subagent-lifecycle-store.d.ts

@@ -1,3 +1,5 @@
+import { type AgentLifecycleSnapshot, type LifecycleState } from '../core/agent-orchestration.js';
+import { type ExclusiveFileLeaseHandle } from '../platform/exclusive-file-lease.js';
 export type PersistedSubagentStatus = 'running' | 'completed' | 'failed' | 'killed';
 export interface PersistedSubagentRunResult {
     text: string;
@@ -32,35 +34,66 @@ export interface PersistedSubagentNotification {
         delivered: boolean;
     };
 }
+/** `status` is a read-only compatibility projection and is never persisted. */
 export interface PersistedSubagentLifecycle {
-    version: 1;
+    version: 2;
     sessionId: string;
     agentId: string;
-    status: PersistedSubagentStatus;
+    lifecycle: AgentLifecycleSnapshot;
     updatedAt: string;
     transcriptBytes?: number;
     detail?: string;
     result?: PersistedSubagentRunResult;
     notifications?: PersistedSubagentNotification[];
+    readonly status?: PersistedSubagentStatus;
+}
+type StoredLifecycle = Omit<PersistedSubagentLifecycle, 'status'>;
+export declare class SubagentExecution {
+    private readonly store;
+    private readonly lease;
+    readonly token: string;
+    readonly generation: number;
+    private current;
+    private released;
+    constructor(store: SubagentLifecycleStore, lease: ExclusiveFileLeaseHandle, token: string, generation: number, current: AgentLifecycleSnapshot);
+    get snapshot(): AgentLifecycleSnapshot;
+    transition(state: LifecycleState): Promise<AgentLifecycleSnapshot>;
+    running(): Promise<AgentLifecycleSnapshot>;
+    beginCancellation(): Promise<AgentLifecycleSnapshot>;
+    finish(state: 'completed' | 'failed' | 'cancelled', result?: PersistedSubagentRunResult, detail?: string, notification?: Omit<PersistedSubagentNotification, 'result' | 'consumed'>): Promise<AgentLifecycleSnapshot>;
+    release(): Promise<void>;
+    private ensureActive;
 }
-/** Praxis-private state for a retained Claude-compatible sidechain. */
 export declare class SubagentLifecycleStore {
     private readonly sessionId;
     private readonly agentId;
     private readonly transcriptPath?;
     private readonly path;
+    private readonly ownerLock;
+    private readonly mutationLock;
     private mutation;
     constructor(praxisRoot: string, sessionId: string, agentId: string, transcriptPath?: string | undefined);
     read(): Promise<PersistedSubagentLifecycle | null>;
-    write(status: PersistedSubagentStatus, detail?: string, terminal?: {
-        result: PersistedSubagentRunResult;
-        notification?: Omit<PersistedSubagentNotification, 'result' | 'consumed'>;
-    }): Promise<void>;
+    acquire(mode?: 'start' | 'continue' | 'recover'): Promise<SubagentExecution>;
+    start(): Promise<SubagentExecution>;
+    continue(): Promise<SubagentExecution>;
+    recover(): Promise<SubagentExecution>;
+    reconcileOwnerLoss(): Promise<{
+        owned: boolean;
+        snapshot: AgentLifecycleSnapshot | null;
+    }>;
     acknowledgeNotification(id: string): Promise<void>;
     prepareNotificationDetached(id: string, model: string): Promise<void>;
     confirmNotificationDetached(id: string): Promise<void>;
     matchesTranscript(record: PersistedSubagentLifecycle): Promise<boolean>;
-    private record;
+    private baseRecord;
+    withLifecycle(current: StoredLifecycle, lifecycle: AgentLifecycleSnapshot, extra?: Partial<Pick<StoredLifecycle, 'detail' | 'result' | 'notifications'>>): StoredLifecycle;
+    mutateOwned(lease: ExclusiveFileLeaseHandle, generation: number, operation: (current: StoredLifecycle) => StoredLifecycle, refreshTranscript?: boolean): Promise<AgentLifecycleSnapshot>;
     private mutate;
+    private acquireMutationLock;
+    private readStored;
+    private normalizeLegacy;
+    private writeStored;
 }
+export {};
 //# sourceMappingURL=subagent-lifecycle-store.d.ts.map