@wjarka/cezarion 0.14.8 → 0.14.9-dev.842

package/dist/runs/store.d.ts

@@ -1,6 +1,6 @@
 import { EventEmitter } from 'node:events';
 import { z } from 'zod';
-import type { CiWait, ConversationState, AgentInput, DelegationState, WorkerCollectedResult } from '../contract/index.js';
+import type { CiWait, ConversationState, AgentInput, InboxClaim, DelegationState, WorkerCollectedResult } from '../contract/index.js';
 import { type WorkerExecutionIdentity } from '../delegation/execution-identity.ts';
 import { workflowDefSchema } from '../workflows/types.ts';
 import type { RunnerId } from '../core/agent-runner.ts';
@@ -125,6 +125,18 @@ export declare const runRecordSchema: z.ZodObject<{
                 }>;
                 resumed: z.ZodOptional<z.ZodLiteral<true>>;
                 instruction: z.ZodOptional<z.ZodString>;
+                question: z.ZodOptional<z.ZodObject<{
+                    questions: z.ZodArray<z.ZodObject<{
+                        id: z.ZodOptional<z.ZodString>;
+                        header: z.ZodString;
+                        question: z.ZodString;
+                        options: z.ZodArray<z.ZodObject<{
+                            label: z.ZodString;
+                            description: z.ZodOptional<z.ZodString>;
+                        }, z.core.$strict>>;
+                        multiSelect: z.ZodOptional<z.ZodBoolean>;
+                    }, z.core.$strict>>;
+                }, z.core.$strict>>;
             }, z.core.$strict>>;
             outcomes: z.ZodArray<z.ZodObject<{
                 requestId: z.ZodUUID;
@@ -133,6 +145,7 @@ export declare const runRecordSchema: z.ZodObject<{
                     "completed-without-reply": "completed-without-reply";
                     destroyed: "destroyed";
                     failed: "failed";
+                    "human-fallback": "human-fallback";
                     replied: "replied";
                     "sender-closed": "sender-closed";
                     "timed-out": "timed-out";
@@ -175,6 +188,7 @@ export declare const runRecordSchema: z.ZodObject<{
                     "completed-without-reply": "completed-without-reply";
                     destroyed: "destroyed";
                     failed: "failed";
+                    "human-fallback": "human-fallback";
                     replied: "replied";
                     "sender-closed": "sender-closed";
                     "timed-out": "timed-out";
@@ -228,6 +242,7 @@ export declare const runRecordSchema: z.ZodObject<{
                     "completed-without-reply": "completed-without-reply";
                     destroyed: "destroyed";
                     failed: "failed";
+                    "human-fallback": "human-fallback";
                     replied: "replied";
                     "sender-closed": "sender-closed";
                     "timed-out": "timed-out";
@@ -316,6 +331,7 @@ export declare const runRecordSchema: z.ZodObject<{
                     "completed-without-reply": "completed-without-reply";
                     destroyed: "destroyed";
                     failed: "failed";
+                    "human-fallback": "human-fallback";
                     replied: "replied";
                     "sender-closed": "sender-closed";
                     "timed-out": "timed-out";
@@ -369,6 +385,7 @@ export declare const runRecordSchema: z.ZodObject<{
                     "completed-without-reply": "completed-without-reply";
                     destroyed: "destroyed";
                     failed: "failed";
+                    "human-fallback": "human-fallback";
                     replied: "replied";
                     "sender-closed": "sender-closed";
                     "timed-out": "timed-out";
@@ -486,6 +503,15 @@ export declare const runRecordSchema: z.ZodObject<{
         text: z.ZodString;
         createdAt: z.ZodISODateTime;
         deliveredAt: z.ZodOptional<z.ZodISODateTime>;
+        consumedAt: z.ZodOptional<z.ZodISODateTime>;
+        awaitingRead: z.ZodOptional<z.ZodLiteral<true>>;
+        inboxClaim: z.ZodOptional<z.ZodObject<{
+            receiptId: z.ZodUUID;
+            generation: z.ZodUUID;
+            expiresAt: z.ZodISODateTime;
+            acknowledgedAt: z.ZodOptional<z.ZodISODateTime>;
+            memberIds: z.ZodOptional<z.ZodArray<z.ZodUUID>>;
+        }, z.core.$strict>>;
     }, z.core.$strict>>>;
     ciWait: z.ZodOptional<z.ZodObject<{
         prUrl: z.ZodString;
@@ -648,6 +674,8 @@ export declare const runRecordSchema: z.ZodObject<{
     worktreeReclaimedAt: z.ZodOptional<z.ZodString>;
     groupId: z.ZodOptional<z.ZodString>;
     variant: z.ZodOptional<z.ZodString>;
+    clientRequestId: z.ZodOptional<z.ZodString>;
+    clientRequestHash: z.ZodOptional<z.ZodString>;
     peakRssBytes: z.ZodOptional<z.ZodNumber>;
     peakProcCount: z.ZodOptional<z.ZodNumber>;
     archived: z.ZodDefault<z.ZodBoolean>;
@@ -777,10 +805,22 @@ export declare function parseRunRecords(raw: unknown): z.ZodSafeParseResult<{
                 state: "accepted" | "continuation-required" | "destroyed" | "late";
                 resumed?: true | undefined;
                 instruction?: string | undefined;
+                question?: {
+                    questions: {
+                        id?: string | undefined;
+                        header: string;
+                        question: string;
+                        options: {
+                            label: string;
+                            description?: string | undefined;
+                        }[];
+                        multiSelect?: boolean | undefined;
+                    }[];
+                } | undefined;
             }[];
             outcomes: {
                 requestId: string;
-                status: "cancelled" | "completed-without-reply" | "destroyed" | "failed" | "replied" | "sender-closed" | "timed-out";
+                status: "cancelled" | "completed-without-reply" | "destroyed" | "failed" | "human-fallback" | "replied" | "sender-closed" | "timed-out";
                 observedAt: string;
                 replyId?: string | undefined;
             }[];
@@ -803,7 +843,7 @@ export declare function parseRunRecords(raw: unknown): z.ZodSafeParseResult<{
             requestIds?: string[] | undefined;
             requestOutcomes?: {
                 requestId: string;
-                status: "cancelled" | "completed-without-reply" | "destroyed" | "failed" | "replied" | "sender-closed" | "timed-out";
+                status: "cancelled" | "completed-without-reply" | "destroyed" | "failed" | "human-fallback" | "replied" | "sender-closed" | "timed-out";
                 observedAt: string;
                 replyId?: string | undefined;
             }[] | undefined;
@@ -830,7 +870,7 @@ export declare function parseRunRecords(raw: unknown): z.ZodSafeParseResult<{
             requestIds?: string[] | undefined;
             requestOutcomes?: {
                 requestId: string;
-                status: "cancelled" | "completed-without-reply" | "destroyed" | "failed" | "replied" | "sender-closed" | "timed-out";
+                status: "cancelled" | "completed-without-reply" | "destroyed" | "failed" | "human-fallback" | "replied" | "sender-closed" | "timed-out";
                 observedAt: string;
                 replyId?: string | undefined;
             }[] | undefined;
@@ -877,7 +917,7 @@ export declare function parseRunRecords(raw: unknown): z.ZodSafeParseResult<{
             requestIds?: string[] | undefined;
             requestOutcomes?: {
                 requestId: string;
-                status: "cancelled" | "completed-without-reply" | "destroyed" | "failed" | "replied" | "sender-closed" | "timed-out";
+                status: "cancelled" | "completed-without-reply" | "destroyed" | "failed" | "human-fallback" | "replied" | "sender-closed" | "timed-out";
                 observedAt: string;
                 replyId?: string | undefined;
             }[] | undefined;
@@ -904,7 +944,7 @@ export declare function parseRunRecords(raw: unknown): z.ZodSafeParseResult<{
             requestIds?: string[] | undefined;
             requestOutcomes?: {
                 requestId: string;
-                status: "cancelled" | "completed-without-reply" | "destroyed" | "failed" | "replied" | "sender-closed" | "timed-out";
+                status: "cancelled" | "completed-without-reply" | "destroyed" | "failed" | "human-fallback" | "replied" | "sender-closed" | "timed-out";
                 observedAt: string;
                 replyId?: string | undefined;
             }[] | undefined;
@@ -974,6 +1014,15 @@ export declare function parseRunRecords(raw: unknown): z.ZodSafeParseResult<{
         text: string;
         createdAt: string;
         deliveredAt?: string | undefined;
+        consumedAt?: string | undefined;
+        awaitingRead?: true | undefined;
+        inboxClaim?: {
+            receiptId: string;
+            generation: string;
+            expiresAt: string;
+            acknowledgedAt?: string | undefined;
+            memberIds?: string[] | undefined;
+        } | undefined;
     }[] | undefined;
     ciWait?: {
         prUrl: string;
@@ -1085,6 +1134,8 @@ export declare function parseRunRecords(raw: unknown): z.ZodSafeParseResult<{
     worktreeReclaimedAt?: string | undefined;
     groupId?: string | undefined;
     variant?: string | undefined;
+    clientRequestId?: string | undefined;
+    clientRequestHash?: string | undefined;
     peakRssBytes?: number | undefined;
     peakProcCount?: number | undefined;
     archived: boolean;
@@ -1220,6 +1271,9 @@ export declare class RunStore extends EventEmitter {
     setRepoHandle(handle: RepoHandle | null): void;
     listRuns(): RunRecord[];
     getRun(id: string): RunRecord | undefined;
+    /** The run an idempotent start already created (#504), archived or not. A deleted run is gone
+     *  with its record, so a retry after deletion honestly creates a fresh one. */
+    findRunByClientRequestId(clientRequestId: string): RunRecord | undefined;
     createRun(input: {
         title: string;
         systemPrompt?: string;
@@ -1237,6 +1291,8 @@ export declare class RunStore extends EventEmitter {
         worktree?: false;
         groupId?: string;
         variant?: string;
+        clientRequestId?: string;
+        clientRequestHash?: string;
         steps: Array<Pick<StepState, 'id' | 'name' | 'kind'>>;
     }): RunRecord;
     /** Build without publishing: owned creation must commit its receipt and run together. */
@@ -1247,7 +1303,23 @@ export declare class RunStore extends EventEmitter {
         input: AgentInput;
     }): void;
     /** Observable atomic input checkpoint: a failed write publishes nothing. */
+    /** Accepted input the harness will never read returns to the queue (#505): only its
+     * delivery and consumption receipts are cleared; order and identity are kept. */
+    requeueUnconsumedAgentInputs(id: string, ids: readonly string[]): void;
+    /** Model consumption observed by the current session (#505). Never un-sets deliveredAt. */
+    commitAgentInputsConsumed(id: string, ids: readonly string[], at: string): void;
+    /** Delivered, but the harness never confirmed reading it (#505): stop awaiting a read. */
+    commitAgentInputsUnconfirmed(id: string, ids: readonly string[]): void;
+    /** Crash recovery (#505): input a harness accepted but was never seen reading goes
+     * back to the queue. Returns the requeued IDs. */
+    requeueAwaitingReadInputs(id: string): string[];
     commitAgentInputs(id: string, inputs: readonly AgentInput[], openingContinuationInputId?: string): void;
+    /** Reserve only unread conversation inputs in one durable index replacement. */
+    claimInboxInputs(runId: string, ids: readonly string[], claim: InboxClaim): void;
+    /** A receipt owns every matching input or none; exact ACK retries preserve the first timestamp. */
+    ackInboxInputs(runId: string, receiptId: string, generation: string, at: string): 'acknowledged' | 'already-acknowledged';
+    releaseInboxInputs(runId: string, receiptId: string, generation: string): 'released';
+    clearExpiredInboxClaims(runId: string, now: string): void;
     /** CI intent and its wake entry share one atomic index replacement. */
     commitCiWait(id: string, wait: CiWait, input?: AgentInput): void;
     /** Retire the wait and precisely its pending wake, optionally accepting human input. */

package/dist/runs/store.js

@@ -1,9 +1,11 @@
 import { EventEmitter } from 'node:events';
+import { removeArtifacts } from '../artifacts/lifecycle.js';
 import { randomUUID } from 'node:crypto';
+import { isDeepStrictEqual } from 'node:util';
 import { appendFileSync, closeSync, constants, fstatSync, fsyncSync, lstatSync, openSync, readSync, realpathSync, readdirSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { z } from 'zod';
-import { ciWaitSchema, agentInputSchema, delegationStateSchema, workerCreationReceiptSchema, workerCollectedResultSchema, workerResultFileSchema, continuationMessageSchema, runRecordSchema as contractRunRecordSchema, } from '../contract/index.js';
+import { ciWaitSchema, agentInputSchema, inboxClaimSchema, delegationStateSchema, workerCreationReceiptSchema, workerCollectedResultSchema, workerResultFileSchema, continuationMessageSchema, runRecordSchema as contractRunRecordSchema, } from '../contract/index.js';
 import { storedDelegationStateSchema } from './delegation-state.js';
 import { refreshHumanAskSummary } from './human-ask-summary.js';
 import { workerExecutionIdentitySchema } from '../delegation/execution-identity.js';
@@ -262,6 +264,10 @@ export const runRecordSchema = z.object({
     groupId: z.string().optional(),
     /** Variant letter within the group — 'A' | 'B' | 'C' (kept as a string). */
     variant: z.string().optional(),
+    /** Idempotent start (#504): the caller's request id and the hash of the start payload it
+     *  named (`src/runs/client-request.ts`). Absent on every run started without one. */
+    clientRequestId: z.string().optional(),
+    clientRequestHash: z.string().optional(),
     /** Peak resident memory (bytes) / process count observed across the run's
      *  agent process trees (#348) — written when a session's telemetry ends.
      *  Optional: old runs.json files and `ps`-less platforms have neither. */
@@ -776,6 +782,14 @@ export class RunStore extends EventEmitter {
     getRun(id) {
         return this.runs.get(id);
     }
+    /** The run an idempotent start already created (#504), archived or not. A deleted run is gone
+     *  with its record, so a retry after deletion honestly creates a fresh one. */
+    findRunByClientRequestId(clientRequestId) {
+        for (const run of this.runs.values())
+            if (run.clientRequestId === clientRequestId)
+                return run;
+        return undefined;
+    }
     createRun(input) {
         const run = this.buildRun(input, randomUUID());
         this.runs.set(run.id, run);
@@ -807,6 +821,7 @@ export class RunStore extends EventEmitter {
             worktree: input.worktree,
             groupId: input.groupId,
             variant: input.variant,
+            ...(input.clientRequestId === undefined ? {} : { clientRequestId: input.clientRequestId, clientRequestHash: input.clientRequestHash }),
             status: 'queued',
             createdAt: new Date().toISOString(),
             tokensUsed: 0,
@@ -846,11 +861,65 @@ export class RunStore extends EventEmitter {
         this.commitIndex(proposed, changed);
     }
     /** Observable atomic input checkpoint: a failed write publishes nothing. */
+    /** Accepted input the harness will never read returns to the queue (#505): only its
+     * delivery and consumption receipts are cleared; order and identity are kept. */
+    requeueUnconsumedAgentInputs(id, ids) {
+        const run = this.runs.get(id);
+        if (!run?.agentInputs || !ids.length)
+            return;
+        this.commitAgentInputs(id, run.agentInputs.map(input => {
+            if (!ids.includes(input.id))
+                return input;
+            const { deliveredAt: _delivered, consumedAt: _consumed, awaitingRead: _awaiting, ...queued } = input;
+            return queued;
+        }));
+    }
+    /** Model consumption observed by the current session (#505). Never un-sets deliveredAt. */
+    commitAgentInputsConsumed(id, ids, at) {
+        const run = this.runs.get(id);
+        if (!run?.agentInputs || !ids.length)
+            return;
+        this.commitAgentInputs(id, run.agentInputs.map(input => {
+            if (!ids.includes(input.id) || !input.deliveredAt || input.consumedAt)
+                return input;
+            const { awaitingRead: _awaiting, ...read } = input;
+            return { ...read, consumedAt: at };
+        }));
+    }
+    /** Delivered, but the harness never confirmed reading it (#505): stop awaiting a read. */
+    commitAgentInputsUnconfirmed(id, ids) {
+        const run = this.runs.get(id);
+        if (!run?.agentInputs || !ids.length)
+            return;
+        this.commitAgentInputs(id, run.agentInputs.map(input => {
+            if (!ids.includes(input.id) || !input.awaitingRead)
+                return input;
+            const { awaitingRead: _awaiting, ...unconfirmed } = input;
+            return unconfirmed;
+        }));
+    }
+    /** Crash recovery (#505): input a harness accepted but was never seen reading goes
+     * back to the queue. Returns the requeued IDs. */
+    requeueAwaitingReadInputs(id) {
+        const ids = (this.runs.get(id)?.agentInputs ?? []).filter(input => input.awaitingRead && input.deliveredAt && !input.consumedAt).map(input => input.id);
+        this.requeueUnconsumedAgentInputs(id, ids);
+        return ids;
+    }
     commitAgentInputs(id, inputs, openingContinuationInputId) {
         const run = this.runs.get(id);
         if (!run)
             throw new Error('missing agent input target');
         const agentInputs = inputs.map(input => agentInputSchema.parse(input));
+        const now = new Date().toISOString();
+        for (const input of run.agentInputs ?? []) {
+            const claim = input.inboxClaim;
+            if (!claim || claim.acknowledgedAt || claim.expiresAt <= now)
+                continue;
+            const matching = agentInputs.filter(next => next.id === input.id);
+            if (matching.length !== 1 || !isDeepStrictEqual(matching[0].inboxClaim, claim)) {
+                throw new Error('live inbox receipt changed');
+            }
+        }
         if (openingContinuationInputId && (run.continuationMessage?.agentInputId !== openingContinuationInputId ||
             !agentInputs.some(input => input.id === openingContinuationInputId && input.deliveredAt)))
             throw new Error('opening agent input checkpoint changed');
@@ -858,6 +927,96 @@ export class RunStore extends EventEmitter {
         proposed.set(id, { ...run, agentInputs, ...(openingContinuationInputId ? { continuationMessage: undefined } : {}) });
         this.commitIndex(proposed, new Set([id]));
     }
+    /** Reserve only unread conversation inputs in one durable index replacement. */
+    claimInboxInputs(runId, ids, claim) {
+        const run = this.runs.get(runId);
+        if (!run)
+            throw new Error('missing inbox recipient');
+        const selected = z.array(z.uuid()).min(1).max(32).refine(values => new Set(values).size === values.length).parse(ids);
+        const receipt = inboxClaimSchema.parse({ ...claim, memberIds: selected });
+        if (receipt.acknowledgedAt || receipt.expiresAt <= new Date().toISOString())
+            throw new Error('inbox claim is not live');
+        const inputs = run.agentInputs ?? [];
+        if (inputs.some(input => input.inboxClaim?.receiptId === receipt.receiptId))
+            throw new Error('inbox receipt already exists');
+        for (const id of selected) {
+            const matching = inputs.filter(input => input.id === id);
+            if (matching.length !== 1 || matching[0]?.source !== 'agent' || !matching[0].conversation ||
+                matching[0].deliveredAt || (matching[0].inboxClaim && matching[0].inboxClaim.expiresAt > new Date().toISOString())) {
+                throw new Error('inbox input is not available');
+            }
+        }
+        const selectedIds = new Set(selected);
+        const proposed = new Map(this.runs);
+        proposed.set(runId, { ...run, agentInputs: inputs.map(input => selectedIds.has(input.id)
+                ? agentInputSchema.parse({ ...input, inboxClaim: receipt }) : input) });
+        this.commitIndex(proposed, new Set([runId]));
+    }
+    /** A receipt owns every matching input or none; exact ACK retries preserve the first timestamp. */
+    ackInboxInputs(runId, receiptId, generation, at) {
+        const run = this.runs.get(runId);
+        if (!run)
+            throw new Error('missing inbox recipient');
+        inboxClaimSchema.shape.receiptId.parse(receiptId);
+        inboxClaimSchema.shape.generation.parse(generation);
+        inboxClaimSchema.shape.expiresAt.parse(at);
+        const matching = (run.agentInputs ?? []).filter(input => input.inboxClaim?.receiptId === receiptId);
+        const receipt = matching[0]?.inboxClaim;
+        const memberIds = receipt?.memberIds;
+        if (!memberIds || matching.length !== memberIds.length ||
+            !memberIds.every(id => matching.some(input => input.id === id)) ||
+            matching.some(input => !isDeepStrictEqual(input.inboxClaim, receipt)) ||
+            matching.some(input => input.inboxClaim?.generation !== generation ||
+                input.source !== 'agent' || !input.conversation))
+            throw new Error('inbox receipt changed');
+        if (matching.every(input => input.inboxClaim?.acknowledgedAt && input.deliveredAt === input.inboxClaim.acknowledgedAt)) {
+            return 'already-acknowledged';
+        }
+        if (matching.some(input => input.deliveredAt || input.inboxClaim?.acknowledgedAt || input.inboxClaim.expiresAt <= at)) {
+            throw new Error('inbox receipt expired or displaced');
+        }
+        const proposed = new Map(this.runs);
+        proposed.set(runId, { ...run, agentInputs: run.agentInputs.map(input => input.inboxClaim?.receiptId === receiptId
+                ? agentInputSchema.parse({ ...input, deliveredAt: at, inboxClaim: { ...input.inboxClaim, acknowledgedAt: at } }) : input) });
+        this.commitIndex(proposed, new Set([runId]));
+        return 'acknowledged';
+    }
+    releaseInboxInputs(runId, receiptId, generation) {
+        const run = this.runs.get(runId);
+        if (!run)
+            throw new Error('missing inbox recipient');
+        inboxClaimSchema.shape.receiptId.parse(receiptId);
+        inboxClaimSchema.shape.generation.parse(generation);
+        const matching = (run.agentInputs ?? []).filter(input => input.inboxClaim?.receiptId === receiptId);
+        if (!matching.length || matching.some(input => input.inboxClaim?.generation !== generation ||
+            input.inboxClaim?.acknowledgedAt || input.deliveredAt))
+            throw new Error('inbox receipt changed');
+        const proposed = new Map(this.runs);
+        proposed.set(runId, { ...run, agentInputs: run.agentInputs.map(input => {
+                if (input.inboxClaim?.receiptId !== receiptId)
+                    return input;
+                const { inboxClaim: _claim, ...unclaimed } = input;
+                return agentInputSchema.parse(unclaimed);
+            }) });
+        this.commitIndex(proposed, new Set([runId]));
+        return 'released';
+    }
+    clearExpiredInboxClaims(runId, now) {
+        const run = this.runs.get(runId);
+        if (!run)
+            throw new Error('missing inbox recipient');
+        inboxClaimSchema.shape.expiresAt.parse(now);
+        if (!run.agentInputs?.some(input => input.inboxClaim && !input.inboxClaim.acknowledgedAt && input.inboxClaim.expiresAt <= now))
+            return;
+        const proposed = new Map(this.runs);
+        proposed.set(runId, { ...run, agentInputs: run.agentInputs.map(input => {
+                if (!input.inboxClaim || input.inboxClaim.acknowledgedAt || input.inboxClaim.expiresAt > now)
+                    return input;
+                const { inboxClaim: _claim, ...unclaimed } = input;
+                return agentInputSchema.parse(unclaimed);
+            }) });
+        this.commitIndex(proposed, new Set([runId]));
+    }
     /** CI intent and its wake entry share one atomic index replacement. */
     commitCiWait(id, wait, input) {
         const run = this.runs.get(id);
@@ -1974,6 +2133,7 @@ export class RunStore extends EventEmitter {
         rmSync(this.eventsPath(id), { force: true });
         rmSync(this.handoffPath(id), { force: true });
         rmSync(this.imagesDir(id), { recursive: true, force: true });
+        removeArtifacts(this.dataDir, id);
     }
     deleteRun(id) {
         if (!this.canDeleteRun(id))
@@ -1987,6 +2147,7 @@ export class RunStore extends EventEmitter {
                 rmSync(this.eventsPath(id), { force: true });
                 rmSync(this.handoffPath(id), { force: true });
                 rmSync(this.imagesDir(id), { recursive: true, force: true });
+                removeArtifacts(this.dataDir, id);
             }
             catch { /* Ordinary run deletion preserves its existing best-effort behavior. */ }
             this.seqs.delete(id);
@@ -2054,6 +2215,7 @@ export class RunStore extends EventEmitter {
                 rmSync(this.eventsPath(stale.id), { force: true });
                 rmSync(this.handoffPath(stale.id), { force: true });
                 rmSync(this.imagesDir(stale.id), { recursive: true, force: true });
+                removeArtifacts(this.dataDir, stale.id);
             }
             catch {
                 // best effort