praxis-agent 0.55.0 → 0.55.2

package/dist/application/turn-lifecycle.js

@@ -1,36 +1,150 @@
 import { AgentRunCancelledError, ModelProviderError, } from '../core/runtime.js';
-export class TurnTerminalController {
-    sink;
-    terminal = false;
-    constructor(sink) {
-        this.sink = sink;
-    }
-    emit = (event) => {
-        if (event.type === 'state' &&
-            (event.state === 'completed' ||
-                event.state === 'cancelled' ||
-                event.state === 'failed')) {
-            return;
+import { ActiveTurnInputMailbox, } from '../core/active-turn-input.js';
+/** Owns the lifecycle and active-turn coordination for one session service. */
+export class TurnCoordinator {
+    options;
+    activeTurns = new Map();
+    constructor(options) {
+        this.options = options;
+    }
+    async run(request, work) {
+        const { sessionId } = request.activation;
+        const mailbox = request.submission.kind === 'shell'
+            ? undefined
+            : new ActiveTurnInputMailbox(this.options.createSteeringId);
+        const record = {
+            ...(mailbox ? { mailbox } : {}),
+            terminal: false,
+        };
+        let terminalState = 'failed';
+        let pendingFailure;
+        const scope = {
+            emit: (event) => {
+                if (event.type === 'state' &&
+                    (event.state === 'completed' ||
+                        event.state === 'failed' ||
+                        event.state === 'cancelled')) {
+                    return;
+                }
+                this.options.eventSink(event);
+            },
+            ...(mailbox ? { steering: mailbox } : {}),
+        };
+        try {
+            this.validateRequest(request);
+            if (this.activeTurns.has(sessionId)) {
+                throw new Error(`conflict: locked (session ${sessionId} already has an active turn)`);
+            }
+            this.activeTurns.set(sessionId, record);
+            const result = await work(scope);
+            terminalState = 'completed';
+            this.transition(record, 'completed');
+            return result;
+        }
+        catch (error) {
+            if (!record.terminal) {
+                terminalState = this.terminalState(error, request.signal);
+                this.transition(record, terminalState);
+            }
+            throw error;
+        }
+        finally {
+            try {
+                if (mailbox) {
+                    pendingFailure = this.rejectPending(mailbox.close(), terminalState === 'cancelled' ? 'cancelled' : 'failed');
+                }
+            }
+            finally {
+                if (this.activeTurns.get(sessionId) === record) {
+                    this.activeTurns.delete(sessionId);
+                }
+            }
+            if (pendingFailure) {
+                // A rejected-input sink failure intentionally retains its prior precedence.
+                // eslint-disable-next-line no-unsafe-finally -- compatibility is covered by the sink-error regression
+                throw pendingFailure.error;
+            }
         }
-        this.sink(event);
-    };
-    complete() {
-        this.transition('completed');
     }
-    fail(error, signal) {
-        if (this.terminal)
-            return;
-        const cancelled = signal?.aborted === true ||
+    steer(sessionId, content) {
+        const active = this.activeTurns.get(sessionId);
+        if (!active)
+            return { kind: 'no-active-turn' };
+        if (!active.mailbox)
+            return { kind: 'not-steerable' };
+        const result = active.mailbox.enqueue(content);
+        if (result.kind === 'accepted' || result.kind === 'empty')
+            return result;
+        return { kind: 'turn-completing' };
+    }
+    withdrawSteering(sessionId, id) {
+        const active = this.activeTurns.get(sessionId);
+        if (!active)
+            return { kind: 'no-active-turn' };
+        if (!active.mailbox)
+            return { kind: 'not-steerable' };
+        const result = active.mailbox.withdraw(id);
+        return result.kind === 'withdrawn' ? result : { kind: 'not-pending' };
+    }
+    close() {
+        let firstFailure;
+        for (const active of this.activeTurns.values()) {
+            if (!active.mailbox)
+                continue;
+            const failure = this.rejectPending(active.mailbox.close(), 'closed');
+            firstFailure ??= failure;
+        }
+        if (firstFailure)
+            throw firstFailure.error;
+    }
+    validateRequest(request) {
+        const { activation, submission } = request;
+        const prompt = submission.kind === 'shell'
+            ? `! ${submission.command}`
+            : submission.kind === 'retry'
+                ? submission.prompt
+                : submission.text;
+        const images = submission.kind === 'prompt' ? (submission.images ?? []) : [];
+        const documents = submission.kind === 'prompt' ? (submission.documents ?? []) : [];
+        if (prompt.length === 0 && images.length === 0 && documents.length === 0) {
+            throw new Error('Prompt must not be empty');
+        }
+        if (activation.name !== undefined && activation.name.length === 0) {
+            throw new Error('Session name must not be empty');
+        }
+        if (submission.kind === 'shell' && submission.command.trim().length === 0) {
+            throw new Error('Shell command must not be empty');
+        }
+    }
+    terminalState(error, signal) {
+        return signal?.aborted === true ||
             error instanceof AgentRunCancelledError ||
-            (error instanceof ModelProviderError && error.kind === 'cancelled');
-        this.transition(cancelled ? 'cancelled' : 'failed');
+            (error instanceof ModelProviderError && error.kind === 'cancelled')
+            ? 'cancelled'
+            : 'failed';
+    }
+    transition(record, state) {
+        if (record.terminal)
+            return;
+        record.terminal = true;
+        this.options.eventSink({ type: 'state', state });
     }
-    transition(state) {
-        if (this.terminal) {
-            throw new Error('Turn terminal transition already emitted');
+    rejectPending(items, reason) {
+        let firstFailure;
+        for (const item of items) {
+            try {
+                this.options.eventSink({
+                    type: 'user-input-rejected',
+                    id: item.id,
+                    content: item.content,
+                    reason,
+                });
+            }
+            catch (error) {
+                firstFailure ??= { error };
+            }
         }
-        this.terminal = true;
-        this.sink({ type: 'state', state });
+        return firstFailure;
     }
 }
 //# sourceMappingURL=turn-lifecycle.js.map

package/dist/application/turn-persistence.d.ts

@@ -0,0 +1,62 @@
+import type { ModelMessage } from '../core/runtime.js';
+import type { TranscriptEvent } from '../core/transcript-event.js';
+import type { NativeTranscriptEntry } from '../native/schema.js';
+import type { NativeCompactionAppend, NativeInterruption, NativeMessageAppend, NativeSessionTranscriptLease } from './native-session-transcript.js';
+import type { NativeTranscriptTail } from '../persistence/native-transcript-store.js';
+export interface TurnPersistenceView {
+    readonly projectionEntries: readonly NativeTranscriptEntry[];
+    readonly projectionTail: NativeTranscriptTail;
+    readonly activeEvents: readonly TranscriptEvent[];
+    readonly activeMessages: readonly ModelMessage[];
+    readonly interruption: NativeInterruption;
+}
+export type TurnPersistenceCommand = {
+    readonly kind: 'projection';
+    readonly entries: readonly NativeTranscriptEntry[];
+} | {
+    readonly kind: 'messages';
+    readonly input: NativeMessageAppend;
+    readonly projectionEntries?: readonly NativeTranscriptEntry[];
+} | {
+    readonly kind: 'tool-execution-started';
+    readonly callId: string;
+} | {
+    readonly kind: 'tool-completion';
+    readonly input: Parameters<NativeSessionTranscriptLease['appendToolCompletion']>[0];
+} | {
+    readonly kind: 'compaction';
+    readonly input: NativeCompactionAppend;
+};
+export type TurnPersistenceReceipt = {
+    readonly kind: 'projection';
+    readonly lastProjectionId: string | null;
+} | {
+    readonly kind: 'messages';
+    readonly eventId: string;
+} | {
+    readonly kind: 'tool-execution-started';
+    readonly callId: string;
+} | {
+    readonly kind: 'tool-completion';
+    readonly callId: string;
+} | {
+    readonly kind: 'compaction';
+    readonly boundaryId: string;
+    readonly summaryId: string;
+};
+export declare class TurnPersistence {
+    private readonly input;
+    private projectionEntries;
+    private projectionTail;
+    private commitQueue;
+    constructor(input: {
+        readonly native: NativeSessionTranscriptLease;
+        readonly initialProjectionEntries?: readonly NativeTranscriptEntry[];
+    });
+    view(): TurnPersistenceView;
+    refresh(): TurnPersistenceView;
+    commit(command: TurnPersistenceCommand): Promise<TurnPersistenceReceipt>;
+    private commitCommand;
+    private stageProjection;
+}
+//# sourceMappingURL=turn-persistence.d.ts.map

package/dist/application/turn-persistence.js

@@ -0,0 +1,114 @@
+import { projectNativeSessionEntries } from './native-session-projection.js';
+const emptyProjectionTail = () => ({
+    byteLength: 0,
+    lastLineHash: null,
+    lastEventId: null,
+    newlineTerminated: true,
+});
+export class TurnPersistence {
+    input;
+    projectionEntries;
+    projectionTail = emptyProjectionTail();
+    commitQueue = Promise.resolve();
+    constructor(input) {
+        this.input = input;
+        this.projectionEntries = structuredClone(input.initialProjectionEntries
+            ? [...input.initialProjectionEntries]
+            : projectNativeSessionEntries(input.native.activeEvents()));
+    }
+    view() {
+        return {
+            projectionEntries: structuredClone(this.projectionEntries),
+            projectionTail: structuredClone(this.projectionTail),
+            activeEvents: structuredClone(this.input.native.activeEvents()),
+            activeMessages: structuredClone(this.input.native.activeMessages()),
+            interruption: structuredClone(this.input.native.interruption()),
+        };
+    }
+    refresh() {
+        this.projectionEntries = structuredClone(projectNativeSessionEntries(this.input.native.activeEvents()));
+        return this.view();
+    }
+    commit(command) {
+        let ownership;
+        try {
+            ownership = { ok: true, command: structuredClone(command) };
+        }
+        catch (error) {
+            ownership = { ok: false, error };
+        }
+        const operation = this.commitQueue.then(() => {
+            if (!ownership.ok)
+                throw ownership.error;
+            return this.commitCommand(ownership.command);
+        });
+        this.commitQueue = operation.then(() => undefined, () => undefined);
+        return operation;
+    }
+    async commitCommand(command) {
+        switch (command.kind) {
+            case 'projection': {
+                const staged = this.stageProjection(command.entries);
+                this.projectionEntries = staged.entries;
+                this.projectionTail = staged.tail;
+                const lastProjectionId = [...command.entries]
+                    .reverse()
+                    .find((entry) => typeof entry.uuid === 'string')?.uuid;
+                return {
+                    kind: 'projection',
+                    lastProjectionId: typeof lastProjectionId === 'string' ? lastProjectionId : null,
+                };
+            }
+            case 'messages': {
+                if (command.input.messages.length === 0)
+                    throw new Error('native transcript cannot append empty messages');
+                const staged = command.projectionEntries === undefined
+                    ? undefined
+                    : this.stageProjection(command.projectionEntries);
+                const eventId = await this.input.native.appendMessages(command.input);
+                if (staged) {
+                    this.projectionEntries = staged.entries;
+                    this.projectionTail = staged.tail;
+                }
+                return { kind: 'messages', eventId };
+            }
+            case 'tool-execution-started':
+                await this.input.native.beginToolExecution(command.callId);
+                return { kind: 'tool-execution-started', callId: command.callId };
+            case 'tool-completion':
+                await this.input.native.appendToolCompletion(command.input);
+                return { kind: 'tool-completion', callId: command.input.callId };
+            case 'compaction': {
+                const result = await this.input.native.appendCompaction(command.input);
+                return { kind: 'compaction', ...result };
+            }
+            default:
+                throw new Error('Unknown turn persistence command');
+        }
+    }
+    stageProjection(entries) {
+        if (entries.length === 0)
+            throw new Error('Cannot append an empty projection');
+        const stagedEntries = [...this.projectionEntries, ...entries];
+        const lastUuidValue = [...entries]
+            .reverse()
+            .find((entry) => typeof entry.uuid === 'string')?.uuid;
+        const lastUuid = typeof lastUuidValue === 'string' ? lastUuidValue : undefined;
+        const byteLength = this.projectionTail.byteLength + entries.length;
+        return {
+            entries: stagedEntries,
+            tail: {
+                ...this.projectionTail,
+                byteLength,
+                lastLineHash: `projection:${byteLength}`,
+                lastEventId: typeof lastUuid === 'string'
+                    ? lastUuid
+                    : this.projectionTail.lastEventId,
+                ...(this.projectionTail.branchParentId === undefined
+                    ? {}
+                    : { branchParentId: null }),
+            },
+        };
+    }
+}
+//# sourceMappingURL=turn-persistence.js.map

package/dist/cli/protocol.d.ts

@@ -243,11 +243,9 @@ export declare function parseCliInvocation(argv: readonly string[]): CliInvocati
 export declare function readStreamJsonMessages(input: AsyncIterable<string | Uint8Array>): AsyncGenerator<StreamJsonMessage>;
 export declare function readStreamUserMessages(input: AsyncIterable<string | Uint8Array>): AsyncGenerator<StreamUserMessage>;
 export declare class StreamJsonOutput {
-    private readonly write;
+    private readonly emitRaw;
     private readonly info;
     private readonly sessionId;
-    private readonly includePartialMessages;
-    private readonly includeHookEvents;
     private turnId;
     private turnText;
     private turnThinking;
@@ -263,7 +261,17 @@ export declare class StreamJsonOutput {
     private modelTurns;
     private compacting;
     private sessionState;
-    constructor(write: (value: unknown) => void, info: CliRuntimeInfo, sessionId: string, includePartialMessages: boolean, includeHookEvents?: boolean);
+    private readonly emitSessionStateEvents;
+    private partialEvents;
+    private pendingPartialStop;
+    constructor(emitRaw: (value: unknown) => void, info: CliRuntimeInfo, sessionId: string, options: {
+        includePartialMessages: boolean;
+        includeHookEvents?: boolean;
+        emitSessionStateEvents?: boolean;
+    });
+    private readonly includePartialMessages;
+    private readonly includeHookEvents;
+    private write;
     init(): void;
     replayUser(message: StreamUserMessage['message']): void;
     /**
@@ -282,11 +290,15 @@ export declare class StreamJsonOutput {
     error(message: string, startedAt: number): void;
     private onEvent;
     private writeSessionState;
+    private writeTerminalIdle;
     private ensureTurn;
     private discardTurn;
     private startTurn;
+    private writePartialMessageStart;
     private partialText;
+    private beginPartialBlock;
     private finishPartial;
+    private finishPartialTail;
     private flushAssistant;
     private finishTurn;
 }