praxis-agent 0.35.0 → 0.37.0

package/dist/persistence/claude-job-store.js

@@ -2,7 +2,8 @@ import { randomUUID } from 'node:crypto';
 import { mkdir, open, readFile, readdir, rm } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { writeFileAtomically } from '../platform/atomic-write.js';
-import { ExclusiveFileLease } from '../platform/exclusive-file-lease.js';
+import { ExclusiveFileLease, } from '../platform/exclusive-file-lease.js';
+import { createAgentLifecycle, isTerminalLifecycleState, markLifecycleOrphaned, parseAgentLifecycleSnapshot, recoverLifecycle, transitionLifecycle, transferLifecycleOwner, } from '../core/agent-orchestration.js';
 const JOB_ID_PATTERN = /^[0-9a-f]{8}$/u;
 const SESSION_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
 const LOCK_WAIT_MS = 5_000;
@@ -98,6 +99,170 @@ function parseDispatch(source, filePath) {
     }
     return value;
 }
+function ownerFromLease(lease) {
+    return { token: lease.token, pid: lease.pid, acquiredAt: lease.createdAt };
+}
+function legacyLifecycleState(state) {
+    if (state.state === 'stopped')
+        return 'cancelled';
+    if (state.state === 'failed')
+        return 'failed';
+    return state.tempo === 'active' ? 'running' : 'waiting';
+}
+function projectState(state, lifecycle) {
+    const next = {
+        ...state,
+        state: lifecycle.state === 'failed' || lifecycle.state === 'orphaned'
+            ? 'failed'
+            : lifecycle.state === 'cancelled' || lifecycle.state === 'completed'
+                ? 'stopped'
+                : 'working',
+        tempo: lifecycle.state === 'waiting'
+            ? state.needs !== undefined
+                ? 'blocked'
+                : 'idle'
+            : lifecycle.state === 'queued'
+                ? state.needs !== undefined
+                    ? 'blocked'
+                    : 'active'
+                : isTerminalLifecycleState(lifecycle.state)
+                    ? 'idle'
+                    : 'active',
+        firstTerminalAt: isTerminalLifecycleState(lifecycle.state)
+            ? lifecycle.terminalAt
+            : null,
+        updatedAt: new Date().toISOString(),
+    };
+    if (isTerminalLifecycleState(lifecycle.state)) {
+        delete next.pid;
+        delete next.socketPath;
+        delete next.controlToken;
+        delete next.inFlight;
+        delete next.needs;
+    }
+    return next;
+}
+function projectionMatches(state, projection) {
+    return (state.state === projection.state &&
+        state.tempo === projection.tempo &&
+        state.firstTerminalAt === projection.firstTerminalAt &&
+        state.pid === projection.pid &&
+        state.socketPath === projection.socketPath &&
+        state.controlToken === projection.controlToken &&
+        state.needs === projection.needs &&
+        JSON.stringify(state.inFlight) === JSON.stringify(projection.inFlight));
+}
+export class ClaudeJobExecution {
+    store;
+    lease;
+    token;
+    generation;
+    jobId;
+    current;
+    released = false;
+    constructor(store, lease, token, generation, jobId, current) {
+        this.store = store;
+        this.lease = lease;
+        this.token = token;
+        this.generation = generation;
+        this.jobId = jobId;
+        this.current = current;
+    }
+    get snapshot() {
+        return this.current;
+    }
+    async update(mutateState) {
+        this.ensureActive();
+        const result = await this.store.mutateExecution(this, (lifecycle, state) => ({ lifecycle, state: mutateState(state) }));
+        this.current = result.lifecycle;
+        return result.state;
+    }
+    async running(mutateState) {
+        return this.transition('running', mutateState);
+    }
+    async waiting(mutateState) {
+        return this.transition('waiting', mutateState);
+    }
+    async beginCancellation(mutateState) {
+        return this.transition('cancelling', mutateState);
+    }
+    async finish(state, mutateState) {
+        return this.transition(state, mutateState);
+    }
+    async handoff() {
+        if (this.released)
+            return;
+        if (this.current.state !== 'queued')
+            throw new Error('Lifecycle handoff is only allowed while queued');
+        let ownershipError;
+        try {
+            await this.store.assertExecutionOwner(this);
+        }
+        catch (error) {
+            ownershipError = error;
+        }
+        let releaseError;
+        try {
+            await this.lease.release();
+        }
+        catch (error) {
+            releaseError = error;
+        }
+        if (releaseError === undefined)
+            this.released = true;
+        if (ownershipError !== undefined && releaseError !== undefined) {
+            throw new AggregateError([ownershipError, releaseError], 'Lifecycle handoff failed while releasing execution lease');
+        }
+        if (ownershipError !== undefined)
+            throw ownershipError;
+        if (releaseError !== undefined)
+            throw releaseError;
+    }
+    async release() {
+        if (this.released)
+            return;
+        let orphanError;
+        if (!isTerminalLifecycleState(this.current.state)) {
+            try {
+                this.current = await this.store.orphanExecution(this);
+            }
+            catch (error) {
+                if (!(error instanceof Error) ||
+                    !/stale or missing/u.test(error.message))
+                    orphanError = error;
+            }
+        }
+        let releaseError;
+        try {
+            await this.lease.release();
+        }
+        catch (error) {
+            releaseError = error;
+        }
+        if (releaseError === undefined && orphanError === undefined)
+            this.released = true;
+        if (orphanError !== undefined && releaseError !== undefined) {
+            throw new AggregateError([orphanError, releaseError], 'Lifecycle orphaning and execution lease release both failed');
+        }
+        if (orphanError !== undefined)
+            throw orphanError;
+        if (releaseError !== undefined)
+            throw releaseError;
+    }
+    async transition(next, mutateState) {
+        this.ensureActive();
+        const result = await this.store.mutateExecution(this, (lifecycle, state) => ({
+            lifecycle: transitionLifecycle(lifecycle, next, this.token),
+            state: mutateState ? mutateState(state) : state,
+        }));
+        this.current = result.lifecycle;
+        return result.lifecycle;
+    }
+    ensureActive() {
+        if (this.released)
+            throw new Error('Lifecycle execution has been released or is stale');
+    }
+}
 export class ClaudeJobStore {
     configRoot;
     lockRoot;
@@ -127,6 +292,236 @@ export class ClaudeJobStore {
             throw error;
         }
     }
+    async createExecution(state, dispatch) {
+        assertJobId(state.daemonShort);
+        const id = state.daemonShort;
+        const ownerLease = await this.ownerLease(id).tryAcquire();
+        if (!ownerLease)
+            return null;
+        const directory = this.jobDirectory(id);
+        let createdDirectory = false;
+        let lifecycleMayExist = false;
+        const cleanup = async (primary) => {
+            const failures = [];
+            if (createdDirectory) {
+                try {
+                    await rm(directory, { recursive: true, force: true });
+                }
+                catch (error) {
+                    failures.push(error);
+                }
+            }
+            if (lifecycleMayExist) {
+                try {
+                    await rm(this.lifecyclePath(id), { force: true });
+                }
+                catch (error) {
+                    failures.push(error);
+                }
+            }
+            try {
+                await ownerLease.release();
+            }
+            catch (error) {
+                failures.push(error);
+            }
+            if (failures.length > 0) {
+                throw new AggregateError(primary === undefined ? failures : [primary, ...failures], 'Claude job execution setup and cleanup failed');
+            }
+            if (primary !== undefined)
+                throw primary;
+        };
+        try {
+            await mkdir(dirname(directory), { recursive: true });
+            try {
+                await mkdir(directory);
+                createdDirectory = true;
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST')
+                    throw error;
+                await cleanup();
+                return null;
+            }
+            const owner = ownerFromLease(ownerLease);
+            const lifecycle = createAgentLifecycle(owner);
+            const record = {
+                version: 1,
+                jobId: id,
+                lifecycle,
+                updatedAt: new Date().toISOString(),
+            };
+            lifecycleMayExist = true;
+            await this.writeLifecycle(record);
+            await writeFileAtomically(this.dispatchPath(id), `${JSON.stringify(dispatch)}\n`);
+            await writeFileAtomically(this.statePath(id), `${JSON.stringify(state)}\n`);
+            return new ClaudeJobExecution(this, ownerLease, owner.token, lifecycle.generation, id, lifecycle);
+        }
+        catch (error) {
+            await cleanup(error);
+            return null;
+        }
+    }
+    async readWithLifecycle(id) {
+        assertJobId(id);
+        const state = await this.read(id);
+        const lifecycle = await this.readLifecycle(id);
+        if (!lifecycle) {
+            const projected = legacyLifecycleState(state);
+            return {
+                state,
+                lifecycleState: projected,
+                lifecycle: null,
+                legacy: true,
+            };
+        }
+        const projected = projectState(state, lifecycle.lifecycle);
+        if (!projectionMatches(state, projected)) {
+            const repaired = await this.withLock(id, async () => {
+                const latestState = await this.read(id);
+                const latest = await this.readLifecycle(id);
+                if (!latest)
+                    return { state: latestState, lifecycle: null };
+                const latestProjection = projectState(latestState, latest.lifecycle);
+                if (!projectionMatches(latestState, latestProjection))
+                    await writeFileAtomically(this.statePath(id), `${JSON.stringify(latestProjection)}\n`);
+                return { state: latestProjection, lifecycle: latest.lifecycle };
+            });
+            if (!repaired.lifecycle)
+                return {
+                    state: repaired.state,
+                    lifecycleState: legacyLifecycleState(repaired.state),
+                    lifecycle: null,
+                    legacy: true,
+                };
+            return {
+                state: repaired.state,
+                lifecycleState: repaired.lifecycle.state,
+                lifecycle: repaired.lifecycle,
+                legacy: false,
+            };
+        }
+        return {
+            state,
+            lifecycleState: lifecycle.lifecycle.state,
+            lifecycle: lifecycle.lifecycle,
+            legacy: false,
+        };
+    }
+    async listWithLifecycle() {
+        const states = await this.list();
+        const views = await Promise.all(states.map(async (state) => {
+            try {
+                return await this.readWithLifecycle(state.daemonShort);
+            }
+            catch {
+                return null;
+            }
+        }));
+        return views.filter((view) => view !== null);
+    }
+    async claimExecution(id) {
+        assertJobId(id);
+        const lease = await this.ownerLease(id).tryAcquire();
+        if (!lease)
+            throw new Error(`Agent ${id} lifecycle execution is already owned`);
+        try {
+            const execution = await this.withLock(id, async () => {
+                const state = await this.read(id);
+                const existing = await this.readLifecycle(id);
+                const owner = ownerFromLease(lease);
+                let lifecycle;
+                if (!existing) {
+                    if (state.state !== 'working')
+                        throw new Error(`Cannot claim non-working legacy agent: ${id}`);
+                    if (state.pid !== undefined &&
+                        state.pid !== process.pid &&
+                        isProcessAlive(state.pid))
+                        throw new Error(`Agent ${id} is owned by a live process`);
+                    lifecycle = transitionLifecycle(createAgentLifecycle(owner), 'running', owner.token);
+                    if (state.tempo !== 'active')
+                        lifecycle = transitionLifecycle(lifecycle, 'waiting', owner.token);
+                }
+                else if (existing.lifecycle.state === 'orphaned') {
+                    lifecycle = recoverLifecycle(existing.lifecycle, owner);
+                }
+                else if (isTerminalLifecycleState(existing.lifecycle.state)) {
+                    throw new Error(`Cannot claim terminal agent lifecycle: ${id}`);
+                }
+                else if (existing.lifecycle.state === 'queued') {
+                    lifecycle = transferLifecycleOwner(existing.lifecycle, existing.lifecycle.owner?.token ?? '', owner);
+                }
+                else if (existing.lifecycle.owner) {
+                    const orphaned = markLifecycleOrphaned(existing.lifecycle, existing.lifecycle.owner.token);
+                    lifecycle = recoverLifecycle(orphaned, owner);
+                }
+                else {
+                    throw new Error(`Invalid claimable lifecycle: ${id}`);
+                }
+                const next = {
+                    version: 1,
+                    jobId: id,
+                    lifecycle,
+                    updatedAt: new Date().toISOString(),
+                };
+                await this.writeLifecycle(next);
+                const projected = projectState(state, lifecycle);
+                await writeFileAtomically(this.statePath(id), `${JSON.stringify(projected)}\n`);
+                return new ClaudeJobExecution(this, lease, owner.token, lifecycle.generation, id, lifecycle);
+            });
+            return execution;
+        }
+        catch (error) {
+            await lease.release();
+            throw error;
+        }
+    }
+    async reconcileOwnerLoss(id) {
+        assertJobId(id);
+        const initial = await this.readWithLifecycle(id);
+        if (!initial.lifecycle) {
+            const pid = initial.state.pid;
+            return {
+                owned: pid !== undefined && isProcessAlive(pid),
+                view: initial,
+            };
+        }
+        if (isTerminalLifecycleState(initial.lifecycle.state))
+            return { owned: false, view: initial };
+        const probe = await this.ownerLease(id).tryAcquire();
+        if (!probe) {
+            const reread = await this.readWithLifecycle(id);
+            if (!reread.lifecycle || isTerminalLifecycleState(reread.lifecycle.state))
+                return { owned: false, view: reread };
+            return { owned: true, view: reread };
+        }
+        try {
+            await this.withLock(id, async () => {
+                const latest = await this.readLifecycle(id);
+                if (!latest)
+                    return false;
+                if (isTerminalLifecycleState(latest.lifecycle.state))
+                    return false;
+                if (latest.lifecycle.generation !== initial.lifecycle?.generation ||
+                    latest.lifecycle.owner?.token !== initial.lifecycle?.owner?.token)
+                    return false;
+                const orphaned = markLifecycleOrphaned(latest.lifecycle, latest.lifecycle.owner?.token ?? '');
+                await this.writeLifecycle({
+                    version: 1,
+                    jobId: id,
+                    lifecycle: orphaned,
+                    updatedAt: new Date().toISOString(),
+                });
+                const state = await this.read(id);
+                await writeFileAtomically(this.statePath(id), `${JSON.stringify(projectState(state, orphaned))}\n`);
+                return true;
+            });
+            return { owned: false, view: await this.readWithLifecycle(id) };
+        }
+        finally {
+            await probe.release();
+        }
+    }
     async read(id) {
         assertJobId(id);
         try {
@@ -284,6 +679,87 @@ export class ClaudeJobStore {
         }
         await writeFileAtomically(this.outputPath(id), content.subarray(start).toString('utf8'));
     }
+    async mutateExecution(execution, operation) {
+        return this.withLock(this.jobIdFromExecution(execution), async () => {
+            const current = await this.readLifecycle(this.jobIdFromExecution(execution));
+            const state = await this.read(this.jobIdFromExecution(execution));
+            if (!current ||
+                current.lifecycle.generation !== execution.generation ||
+                current.lifecycle.owner?.token !== execution.token)
+                throw new Error('Lifecycle execution owner token is stale or missing');
+            const result = operation(current.lifecycle, state);
+            if (result.state.daemonShort !== this.jobIdFromExecution(execution))
+                throw new Error('Agent ID cannot change');
+            const record = {
+                version: 1,
+                jobId: this.jobIdFromExecution(execution),
+                lifecycle: result.lifecycle,
+                updatedAt: new Date().toISOString(),
+            };
+            await this.writeLifecycle(record);
+            const projected = projectState({ ...result.state, updatedAt: record.updatedAt }, result.lifecycle);
+            await writeFileAtomically(this.statePath(this.jobIdFromExecution(execution)), `${JSON.stringify(projected)}\n`);
+            return { lifecycle: result.lifecycle, state: projected };
+        });
+    }
+    async assertExecutionOwner(execution) {
+        await this.withLock(this.jobIdFromExecution(execution), async () => {
+            const current = await this.readLifecycle(this.jobIdFromExecution(execution));
+            if (!current ||
+                current.lifecycle.generation !== execution.generation ||
+                current.lifecycle.owner?.token !== execution.token)
+                throw new Error('Lifecycle execution owner token is stale or missing');
+        });
+    }
+    async orphanExecution(execution) {
+        const result = await this.mutateExecution(execution, (lifecycle, state) => {
+            const next = markLifecycleOrphaned(lifecycle, execution.token);
+            return { lifecycle: next, state };
+        });
+        return result.lifecycle;
+    }
+    jobIdFromExecution(execution) {
+        return execution.jobId;
+    }
+    async readLifecycle(id) {
+        let source;
+        try {
+            source = await readFile(this.lifecyclePath(id), 'utf8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return null;
+            throw error;
+        }
+        let value;
+        try {
+            value = JSON.parse(source);
+        }
+        catch (error) {
+            throw new Error(`Invalid Claude job lifecycle: ${this.lifecyclePath(id)}`, {
+                cause: error,
+            });
+        }
+        if (!isRecord(value))
+            throw new Error(`Invalid Claude job lifecycle: ${this.lifecyclePath(id)}`);
+        let lifecycle;
+        try {
+            lifecycle = parseAgentLifecycleSnapshot(value.lifecycle);
+        }
+        catch {
+            throw new Error(`Invalid Claude job lifecycle: ${this.lifecyclePath(id)}`);
+        }
+        if (!isRecord(value) ||
+            value.version !== 1 ||
+            value.jobId !== id ||
+            typeof value.updatedAt !== 'string' ||
+            Number.isNaN(Date.parse(value.updatedAt)))
+            throw new Error(`Invalid Claude job lifecycle: ${this.lifecyclePath(id)}`);
+        return { ...value, lifecycle };
+    }
+    async writeLifecycle(record) {
+        await writeFileAtomically(this.lifecyclePath(record.jobId), `${JSON.stringify(record)}\n`, { mode: 0o600 });
+    }
     async withLock(id, operation) {
         const lease = new ExclusiveFileLease(join(this.lockRoot, 'locks', `job-${id}.lock`));
         const deadline = Date.now() + LOCK_WAIT_MS;
@@ -317,6 +793,12 @@ export class ClaudeJobStore {
     outputPath(id) {
         return join(this.jobDirectory(id), 'output.log');
     }
+    lifecyclePath(id) {
+        return join(this.lockRoot, 'agent-lifecycle', `${id}.json`);
+    }
+    ownerLease(id) {
+        return new ExclusiveFileLease(join(this.lockRoot, 'locks', `job-${id}.owner.lock`));
+    }
 }
 export function newClaudeJobIdentity() {
     const sessionId = randomUUID();

package/dist/persistence/claude-transcript-store.d.ts

@@ -1,5 +1,7 @@
 import type { ClaudeSchemaAdapter, ClaudeTranscriptEntry } from '../compatibility/claude/schema.js';
 import { type ClaudeSessionIndex } from './claude-session-index.js';
+import { classifyTranscriptAppend } from './transcript-file-append.js';
+export { classifyTranscriptAppend };
 export interface TranscriptTail {
     byteLength: number;
     lastLineHash: string | null;
@@ -65,7 +67,6 @@ export interface ClaudeTranscriptStoreOptions {
     schema: ClaudeSchemaAdapter;
     writeProfile?: 'main' | 'sidechain';
 }
-export declare function classifyTranscriptAppend(written: Uint8Array, previousByteLength: number, encodedLine: Uint8Array): 'appended' | 'interleaved-write';
 export declare class ClaudeTranscriptStore {
     private readonly sessionFile;
     private readonly lease;

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

@@ -7,6 +7,8 @@ import { isClaudeDurableMetadataType } from '../compatibility/claude/session-met
 import { getClaudeContentBlocks, indexClaudeToolLinks, recoverClaudeToolResultLinks, } from '../compatibility/claude/tool-links.js';
 import { ExclusiveFileLease } from '../platform/exclusive-file-lease.js';
 import { readClaudeSessionIndex, } from './claude-session-index.js';
+import { classifyTranscriptAppend } from './transcript-file-append.js';
+export { classifyTranscriptAppend };
 export class ClaudeTranscriptParseError extends Error {
     lineNumber;
     byteOffset;
@@ -34,16 +36,6 @@ const NON_TAIL_ENTRY_TYPES = new Set([
     'tag',
     'worktree-state',
 ]);
-export function classifyTranscriptAppend(written, previousByteLength, encodedLine) {
-    const expectedEnd = previousByteLength + encodedLine.length;
-    if (written.length === expectedEnd &&
-        Buffer.from(written)
-            .subarray(previousByteLength, expectedEnd)
-            .equals(encodedLine)) {
-        return 'appended';
-    }
-    return 'interleaved-write';
-}
 function hashLine(line) {
     return createHash('sha256').update(line).digest('hex');
 }

package/dist/persistence/native-team-mailbox.d.ts

@@ -0,0 +1,68 @@
+import { type TeamMailboxMessage, type TeamMailboxPayload } from '../core/team-mailbox.js';
+export interface NativeTeamMailboxRetention {
+    readonly maxRecords?: number;
+    readonly maxBytes?: number;
+}
+export interface NativeTeamMailboxOptions {
+    readonly nativeRoot: string;
+    readonly projectIdentity: string;
+    readonly teamId: string;
+    readonly participants: readonly string[];
+    readonly retention?: NativeTeamMailboxRetention;
+}
+export interface NativeTeamMailboxAppendInput {
+    readonly messageId: string;
+    readonly sender: string;
+    readonly recipients: readonly string[];
+    readonly payload: TeamMailboxPayload;
+    readonly createdAt?: string;
+}
+export interface NativeTeamMailboxAppendResult {
+    readonly message: TeamMailboxMessage;
+    readonly inserted: boolean;
+}
+export interface NativeTeamMailboxReadProof {
+    readonly participant: string;
+    readonly expectedCursor: number;
+    readonly throughSequence: number;
+    readonly messageIds: readonly string[];
+}
+export interface NativeTeamMailboxReadResult {
+    readonly messages: readonly TeamMailboxMessage[];
+    readonly expectedCursor: number;
+    readonly throughSequence: number;
+    readonly messageIds: readonly string[];
+    readonly proof: NativeTeamMailboxReadProof;
+}
+export declare class NativeTeamMailbox {
+    private readonly options;
+    readonly messagesPath: string;
+    readonly statePath: string;
+    readonly mutationPath: string;
+    private readonly participants;
+    private readonly participantSet;
+    private readonly maxRecords;
+    private readonly maxBytes;
+    private mutation;
+    private constructor();
+    static open(options: NativeTeamMailboxOptions): NativeTeamMailbox;
+    append(input: NativeTeamMailboxAppendInput): Promise<NativeTeamMailboxAppendResult>;
+    read(participant: string, bounds?: {
+        maxMessages?: number;
+    }): Promise<NativeTeamMailboxReadResult>;
+    acknowledge(proof: NativeTeamMailboxReadProof): Promise<void>;
+    private enqueue;
+    private mutate;
+    private acquireMutation;
+    private load;
+    private truncateAndSync;
+    private rewriteRecords;
+    private ensureMode;
+    private loadState;
+    private initialState;
+    private writeState;
+    private compact;
+    private assertParticipant;
+    private assertParticipants;
+}
+//# sourceMappingURL=native-team-mailbox.d.ts.map