@wjarka/cezarion 0.16.0 → 0.17.0

package/dist/workflows/question-routing.js

@@ -0,0 +1,18 @@
+import { openQuestions } from '../delegation/questions.js';
+/** The first fallback reason, or the conversation that admitted the worker question. */
+export function workerQuestionFallback(worker, root, parentCanReceive) {
+    // Recovery can find a question that never left a worker which has since stopped.
+    if (!['queued', 'running', 'waiting'].includes(worker.status))
+        return { reason: 'worker-stopped' };
+    if (root?.delegation?.role !== 'root' || !parentCanReceive(root))
+        return { reason: 'the parent can no longer receive messages' };
+    const state = root.delegation.conversation ?? { messages: [], outcomes: [] };
+    // Room in the ledger for the question AND its reply, beside the replies other open questions
+    // reserve. The reply itself is always admitted to this worker's inbox (service.send).
+    if (state.messages.length + openQuestions(state).length + 2 > 1024 || (root.agentInputs ?? []).filter(input => !input.deliveredAt).length >= 32 ||
+        state.messages.filter(m => m.kind === 'request' && m.state === 'accepted' && !state.outcomes.some(o => o.requestId === m.id)).length >= 32) {
+        return { reason: 'the parent conversation is at capacity' };
+    }
+    return { state };
+}
+//# sourceMappingURL=question-routing.js.map

package/dist/workflows/question-routing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"question-routing.js","sourceRoot":"","sources":["../../src/workflows/question-routing.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAE3D,wFAAwF;AACxF,MAAM,UAAU,sBAAsB,CAAC,MAAiB,EAAE,IAA2B,EAAE,gBAA8C;IACnI,iFAAiF;IACjF,IAAI,CAAC,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC;QAAE,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC;IACnG,IAAI,IAAI,EAAE,UAAU,EAAE,IAAI,KAAK,MAAM,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,MAAM,EAAE,2CAA2C,EAAE,CAAC;IACjI,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,CAAC,YAAY,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;IAC7E,6FAA6F;IAC7F,sFAAsF;IACtF,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,MAAM,IAAI,EAAE;QAC7I,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,CAAC,KAAK,KAAK,UAAU,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,IAAI,EAAE,EAAE,CAAC;QAC7I,OAAO,EAAE,MAAM,EAAE,wCAAwC,EAAE,CAAC;IAC9D,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,CAAC;AACnB,CAAC"}

package/dist/workflows/run-scheduling.d.ts

@@ -0,0 +1,35 @@
+import type { RunnerId } from '../core/agent-runner.ts';
+import type { RunRecord } from '../runs/store.ts';
+import type { AccountHolds } from '../workspace/semaphore.ts';
+import type { StartRunInput } from './run.ts';
+import type { WorkflowDef } from './types.ts';
+import type { resolvedWaits } from './waits.ts';
+/**
+ * A deadline hold blocks all work on its account. An in-flight resume holds fresh work only;
+ * other resumes must remain eligible.
+ */
+export declare function accountHeldFor(run: Pick<RunRecord, 'runner' | 'agentProfile' | 'status' | 'autoResumeAttempts'>, holds: AccountHolds, fallbackRunner: RunnerId): boolean;
+/**
+ * Key usage-limit holds by resolved runner and account. fallbackRunner applies before a run
+ * records its runner.
+ */
+export declare function runAccountKey(run: Pick<RunRecord, 'runner' | 'agentProfile'>, fallbackRunner: RunnerId): string;
+/**
+ * Whether an automatic resume has not completed its first turn. Such resumes bypass in-flight
+ * holds, but not a future deadline hold.
+ */
+export declare function resumeInFlight(run: Pick<RunRecord, 'status' | 'autoResumeAttempts'>): boolean;
+/** Fixed opening turn; the queued results themselves are delivered after its turn end. */
+export declare function sessionlessWakePrompt(resolved: ReturnType<typeof resolvedWaits>): string;
+/** Resume the persisted pending tail instead of replaying completed agents. */
+export declare function queuedStartAt(run: RunRecord, workflow: WorkflowDef): number;
+/** Input before hydration, preserving autonomy and an explicit worktree opt-out on restart. */
+export declare function queuedRecoveryInput(run: RunRecord): StartRunInput;
+/**
+ * The wake instant as a human reads it — local, to the SECOND, with the zone named. The
+ * transcript line is what someone scanning a stalled task actually reads, and "18:41" is not
+ * enough to tell a wait that is nearly over from one that just started; the machine-readable ISO
+ * copy lives on `RunRecord.autoResumeAt`. Server-side formatting is honest here because cezar is
+ * local-first: the process and the browser reading it are the same machine.
+ */
+export declare function formatWakeInstant(at: Date): string;

package/dist/workflows/run-scheduling.js

@@ -0,0 +1,61 @@
+/**
+ * A deadline hold blocks all work on its account. An in-flight resume holds fresh work only;
+ * other resumes must remain eligible.
+ */
+export function accountHeldFor(run, holds, fallbackRunner) {
+    const key = runAccountKey(run, fallbackRunner);
+    if (holds.deadline.has(key))
+        return true;
+    return holds.inFlight.has(key) && !resumeInFlight(run);
+}
+/**
+ * Key usage-limit holds by resolved runner and account. fallbackRunner applies before a run
+ * records its runner.
+ */
+export function runAccountKey(run, fallbackRunner) {
+    return `${run.runner ?? fallbackRunner}:${run.agentProfile ?? 'default'}`;
+}
+/**
+ * Whether an automatic resume has not completed its first turn. Such resumes bypass in-flight
+ * holds, but not a future deadline hold.
+ */
+export function resumeInFlight(run) {
+    return (run.autoResumeAttempts !== undefined && (run.status === 'queued' || run.status === 'running'));
+}
+/** Fixed opening turn; the queued results themselves are delivered after its turn end. */
+export function sessionlessWakePrompt(resolved) {
+    return resolved.some(wait => wait.kind === 'pr')
+        ? 'Resume to receive the queued CI observation. End this opening turn so Cezar can deliver it; do not poll CI.'
+        : resolved.some(wait => wait.kind === 'worker')
+            ? 'Resume to receive the queued worker wait result. End this opening turn so Cezar can deliver it.'
+            : resolved.length ? 'Resume to receive the queued timer result. End this opening turn so Cezar can deliver it.'
+                : 'Resume to receive queued messages. End this opening turn so Cezar can deliver them.';
+}
+/** Resume the persisted pending tail instead of replaying completed agents. */
+export function queuedStartAt(run, workflow) {
+    return Math.max(0, workflow.steps.findIndex(definition => run.steps.find(step => step.id === definition.id)?.status === 'pending'));
+}
+/** Input before hydration, preserving autonomy and an explicit worktree opt-out on restart. */
+export function queuedRecoveryInput(run) {
+    return {
+        task: run.task,
+        agentProfile: run.agentProfile,
+        systemPrompt: run.systemPrompt,
+        model: run.model,
+        effort: run.effort,
+        runner: run.runner,
+        autonomous: run.autonomous,
+        worktree: run.worktree,
+    };
+}
+/**
+ * The wake instant as a human reads it — local, to the SECOND, with the zone named. The
+ * transcript line is what someone scanning a stalled task actually reads, and "18:41" is not
+ * enough to tell a wait that is nearly over from one that just started; the machine-readable ISO
+ * copy lives on `RunRecord.autoResumeAt`. Server-side formatting is honest here because cezar is
+ * local-first: the process and the browser reading it are the same machine.
+ */
+export function formatWakeInstant(at) {
+    return new Intl.DateTimeFormat(undefined, { dateStyle: 'medium', timeStyle: 'long' }).format(at);
+}
+//# sourceMappingURL=run-scheduling.js.map

package/dist/workflows/run-scheduling.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-scheduling.js","sourceRoot":"","sources":["../../src/workflows/run-scheduling.ts"],"names":[],"mappings":"AAOA;;;GAGG;AACH,MAAM,UAAU,cAAc,CAC5B,GAAiF,EACjF,KAAmB,EACnB,cAAwB;IAExB,MAAM,GAAG,GAAG,aAAa,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;IAC/C,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACzC,OAAO,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC;AACzD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAC3B,GAA+C,EAC/C,cAAwB;IAExB,OAAO,GAAG,GAAG,CAAC,MAAM,IAAI,cAAc,IAAI,GAAG,CAAC,YAAY,IAAI,SAAS,EAAE,CAAC;AAC5E,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,GAAqD;IAClF,OAAO,CACL,GAAG,CAAC,kBAAkB,KAAK,SAAS,IAAI,CAAC,GAAG,CAAC,MAAM,KAAK,QAAQ,IAAI,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAC9F,CAAC;AACJ,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,qBAAqB,CAAC,QAA0C;IAC9E,OAAO,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC;QAC9C,CAAC,CAAC,6GAA6G;QAC/G,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC;YAC7C,CAAC,CAAC,iGAAiG;YACnG,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,2FAA2F;gBAC7G,CAAC,CAAC,qFAAqF,CAAC;AAChG,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,aAAa,CAAC,GAAc,EAAE,QAAqB;IACjE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC,KAAK,CAAC,SAAS,CAAC,UAAU,CAAC,EAAE,CACvD,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,KAAK,UAAU,CAAC,EAAE,CAAC,EAAE,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC;AAC9E,CAAC;AAED,+FAA+F;AAC/F,MAAM,UAAU,mBAAmB,CAAC,GAAc;IAChD,OAAO;QACL,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,YAAY,EAAE,GAAG,CAAC,YAAY;QAC9B,YAAY,EAAE,GAAG,CAAC,YAAY;QAC9B,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,QAAQ,EAAE,GAAG,CAAC,QAAQ;KACvB,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,EAAQ;IACxC,OAAO,IAAI,IAAI,CAAC,cAAc,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AACnG,CAAC"}

package/dist/workflows/run-states.d.ts

@@ -0,0 +1,190 @@
+/**
+ * Every run state, every exit out of it and every wait kind, as data (hearsay-tools/cezarion#1804).
+ * This file is the Transitions out table of AGENTS.md § Case tables: a change that adds or changes
+ * a run state declares its exits here first.
+ *
+ * Two levels. An exit (`RUN_EXITS`) is one kind of status write, with the statuses it may leave
+ * from. A trigger row (`RUN_TRIGGERS`) is one event out of one state: who or what fires it, what
+ * happens at shipped defaults, the exit it writes and the `run.ts` functions on its path. Many rows
+ * end in one exit (`settleSuccess` serves `cezar_done`, Finish and an idle-closed worker).
+ *
+ * `run.ts` takes every run status it writes from `transition` or `transitionVia`. Outside strict
+ * mode both return the declared status and do nothing else: no read, no log, no throw, so a
+ * production write is the write it was. `vitest.setup.ts` turns strict mode on, so a test fails on
+ * a write whose stored status the exit does not leave from.
+ */
+import type { RunRecord, RunStatus, Wait, WaitPhase } from '../contract/index.js';
+/** Who or what fires a trigger. */
+export type FiredBy = 'human' | 'parent' | 'agent' | 'runner' | 'timer' | 'scheduler' | 'watcher' | 'worker' | 'recovery' | 'engine';
+/** The actors that fire with no person and no restart behind them. */
+export declare const AUTOMATIC: ReadonlySet<FiredBy>;
+/** What a `waiting` run waits on: `computeWaitingOn`'s kinds, plus three cases it leaves out. */
+export type Park = 'permission' | 'human' | 'usage-limit' | 'workers' | 'pr' | 'process' | 'timer' | 'capacity' | 'plain';
+export type RunState = Exclude<RunStatus, 'waiting'> | `waiting:${Park}`;
+export type RunStateSpec = {
+    final: boolean;
+    /** Why the state's only unconditional default exits are a person's. */
+    humanOnly?: string;
+    note?: string;
+};
+export declare const RUN_STATES: {
+    readonly [S in RunState]: RunStateSpec;
+};
+/** The status of a state. */
+export declare function statusOf(state: RunState): RunStatus;
+/** One kind of status write: the statuses it may leave from and the one it writes. */
+export declare const RUN_EXITS: {
+    readonly start: {
+        readonly from: readonly ["queued", "running", "waiting"];
+        readonly to: 'running';
+    };
+    readonly 'start-held': {
+        readonly from: readonly ["queued"];
+        readonly to: 'queued';
+    };
+    readonly requeue: {
+        readonly from: readonly ["queued", "running", "failed"];
+        readonly to: 'queued';
+    };
+    readonly 'continue-line': {
+        readonly from: readonly ["waiting", "review", "done", "failed", "cancelled"];
+        readonly to: 'queued';
+    };
+    readonly 'continue-now': {
+        readonly from: readonly ["waiting", "review", "done", "failed", "cancelled"];
+        readonly to: 'running';
+    };
+    readonly park: {
+        readonly from: readonly ["running", "queued", "waiting"];
+        readonly to: 'waiting';
+    };
+    readonly 'park-for-wake': {
+        readonly from: readonly ["queued", "waiting"];
+        readonly to: 'waiting';
+    };
+    readonly hold: {
+        readonly from: readonly ["failed", "waiting"];
+        readonly to: 'waiting';
+    };
+    readonly resume: {
+        readonly from: readonly ["waiting"];
+        readonly to: 'running';
+    };
+    readonly succeed: {
+        readonly from: readonly ["running", "waiting"];
+        readonly to: 'done';
+    };
+    readonly 'succeed-review': {
+        readonly from: readonly ["running", "waiting"];
+        readonly to: 'review';
+    };
+    readonly 'accept-review': {
+        readonly from: readonly ["review"];
+        readonly to: 'done';
+    };
+    readonly 'fail-start': {
+        readonly from: readonly ["queued", "running"];
+        readonly to: 'failed';
+    };
+    readonly fail: {
+        readonly from: readonly ["running", "waiting"];
+        readonly to: 'failed';
+    };
+    readonly 'fail-continue': {
+        readonly from: readonly ["running", "waiting", "cancelled"];
+        readonly to: 'failed';
+    };
+    readonly 'fail-interrupted': {
+        readonly from: readonly ["queued", "running", "waiting"];
+        readonly to: 'failed';
+    };
+    readonly 'fail-crash': {
+        readonly from: readonly ["queued", "running", "waiting"];
+        readonly to: 'failed';
+    };
+    readonly 'withdraw-hold': {
+        readonly from: readonly ["waiting"];
+        readonly to: 'failed';
+    };
+    readonly cancel: {
+        readonly from: readonly ["queued", "running", "waiting"];
+        readonly to: 'cancelled';
+    };
+    readonly 'stop-worker': {
+        readonly from: readonly ["queued", "running", "waiting", "review", "done", "failed"];
+        readonly to: 'cancelled';
+    };
+    readonly 'cancel-late': {
+        readonly from: readonly ["queued", "running", "waiting", "done", "review", "failed"];
+        readonly to: 'cancelled';
+    };
+};
+export type RunExitId = keyof typeof RUN_EXITS;
+export type TriggerRow = {
+    /** `<state group>.<event>`, unique. */
+    id: string;
+    states: readonly RunState[];
+    trigger: string;
+    firedBy: FiredBy;
+    /** A condition on the run. A row with one never counts as the state's automatic exit. */
+    when?: string;
+    /** Behavior at shipped defaults. */
+    behavior: string;
+    /** Null: no status write (a nudge is sent, the session closes). */
+    exit: RunExitId | null;
+    /** The states it reaches, or `same`: it does not leave the state. */
+    to: readonly RunState[] | 'same';
+    /** The `run.ts` functions on its path; `store:` and `server:` name a writer outside `run.ts`. */
+    via: readonly string[];
+    /** The existing test that drives the row. */
+    pinnedBy?: {
+        file: string;
+        test: string;
+    };
+};
+export declare const RUN_TRIGGERS: readonly TriggerRow[];
+/** Each wait kind: its deadline, whether it keeps a slot while it is the top wait, who resolves it. */
+export type WaitKindSpec = {
+    deadline: 'required' | 'agent-only' | 'none';
+    keepsSlot: boolean;
+    resolves: readonly {
+        trigger: string;
+        firedBy: FiredBy;
+    }[];
+    cancels: readonly string[];
+    humanOnly?: string;
+};
+export declare const WAIT_KINDS: {
+    readonly [K in Wait['kind']]: WaitKindSpec;
+};
+/** The phases a wait entry moves through. Their writes go through RunStore.commitOutcome (hearsay-tools/cezarion#1805). */
+export declare const WAIT_PHASES: {
+    readonly [P in WaitPhase]: readonly {
+        to: WaitPhase;
+        firedBy: readonly FiredBy[];
+    }[];
+};
+export type StateInput = Partial<Pick<RunRecord, 'status' | 'waits' | 'autoResumeAt' | 'hasPendingPermission' | 'agentInputs' | 'delegation'>> & Pick<RunRecord, 'status'>;
+/** The state of a stored record. Pure. */
+export declare function stateOf(run: StateInput): RunState;
+/** Tests only: `vitest.setup.ts` calls it, so a violation throws and is recorded. Returns the
+ *  previous mode, so a test that changes it can put it back. */
+export declare function strictRunExits(on?: boolean): boolean;
+/** The violations recorded since the last call, so a test fails even when `run.ts` swallowed the throw. */
+export declare function takeRunExitViolations(): string[];
+/** Throws the violations recorded since the last call: the test setup runs it after each test. */
+export declare function throwRunExitViolations(): void;
+/**
+ * THE entry point for a run status write in `run.ts`: the status `exit` writes. In strict mode it
+ * reads the stored record and refuses an exit that does not leave from its status. A run the store
+ * does not hold passes, because the write then writes nothing.
+ */
+export declare function transition<E extends RunExitId>(exit: E, read: () => Pick<StateInput, 'status'> | undefined): (typeof RUN_EXITS)[E]['to'];
+/**
+ * For a store commit that writes a status it holds itself. In strict mode it reads the stored
+ * status before and after the commit. When the status changed, the old one must be in the exit's
+ * `from` and the new one must be the exit's `to`, so the commit and its exit cannot drift apart. A
+ * commit that wrote no status (it refused, or only cleared fields) passes. Both checks run after
+ * the commit, so strict mode never keeps a commit from running.
+ */
+export declare function transitionVia<T>(exit: RunExitId, read: () => Pick<StateInput, 'status'> | undefined, commit: () => T): T;