@enderfga/claw-orchestrator 5.0.0 → 6.0.0

package/dist/src/kernel/engine.d.ts

@@ -0,0 +1,319 @@
+/**
+ * The run kernel.
+ *
+ * A durable executor for workflow runs. It owns what the existing state machines
+ * each owned separately and differently: what is running, what to do when a step
+ * fails, when to give up, how to stop, and — the part none of them had — how to
+ * come back after the process dies.
+ *
+ * Every mode goes through it. `council_start`, `fanout_start`, `ultraplan_start`,
+ * `ultrareview_start` and `autoloop_start` each create a run here; the engines
+ * they wrap (`Council`, `Fanout`, the autoloop dispatcher) still do the work,
+ * but they no longer own a lifecycle. What that replaced: five result maps, four
+ * 30-minute eviction timers, a 5-second poller, two `Set`s fencing a start
+ * against a delete, and two incompatible ways of listing past runs across
+ * processes.
+ *
+ * Durability contract, stated precisely: every state transition is checkpointed
+ * (atomic `run.json`) and appended to `events.jsonl` before the next step
+ * begins, and `resume` restarts at the last node boundary. That makes node
+ * execution **at-least-once**, not exactly-once — there is no idempotency key,
+ * no attempt lease, and no side-effect commit marker, so a node that died after
+ * writing files but before its checkpoint runs again from the top. Workflows
+ * whose nodes are not safe to repeat need to make them safe.
+ *
+ * Ownership contract, equally precisely: this class never writes to a run
+ * directly. It holds a `RunGuard` from the store and every change — checkpoint,
+ * event, node artifact, terminal verdict — goes through `RunTxn`, which applies
+ * the change to a *copy*, commits it under the guard, and adopts the copy only
+ * if the disk accepted it. There is no code path from here to `run.json` that
+ * skips that, because the raw writers are no longer exported. An owner that has
+ * been superseded therefore cannot change the run in memory either: its record
+ * stops advancing at the last write the disk agreed to.
+ *
+ * Control flow is linear with an explicit `router` node for branches and loops.
+ * Parallelism is the `fanout` node rather than a general parallel/join construct:
+ * fan-out is the shape every existing mode actually needed, and a join barrier
+ * would add failure modes (partial joins, orphaned branches) that nothing here
+ * would exercise.
+ *
+ * What a node timeout can and cannot do: it stops the kernel waiting and marks
+ * the node failed, but an in-flight agent turn is owned by the session layer and
+ * finishes on its own schedule. The kernel does not pretend otherwise.
+ */
+import { EventEmitter } from 'node:events';
+import { type Logger } from '../logger.js';
+import { type AcceptanceContract } from '../verify/contract.js';
+import type { SessionManagerLike } from './agent-step.js';
+import { runDir, summarize, type ListRunsQuery, type RunSummary } from './store.js';
+import { type ConsensusVote, type KernelEvent, type NodeKind, type NodeSpec, type RunRecord, type WorkflowSpec } from './types.js';
+export declare const DEFAULT_NODE_TIMEOUT_MS: number;
+export declare const DEFAULT_MAX_NODE_VISITS = 50;
+/**
+ * How long a run about to claim `verified` waits for abandoned attempts to stop.
+ *
+ * Short on purpose. The wait exists to catch an attempt that is about to finish,
+ * not to hold a run hostage to one that never will — a node stuck forever must
+ * not stop the run from ending, only from being called verified.
+ */
+export declare const QUIESCE_GRACE_MS = 2000;
+/** Terminal verifier appended when the workflow declares a run-level contract. */
+export declare const IMPLICIT_VERIFIER_ID = "__verify";
+/** How much node text the checkpoint carries inline. The rest goes to disk. */
+export declare const OUTPUT_PREVIEW_CHARS = 4000;
+export interface NodeResult {
+    ok: boolean;
+    output?: string;
+    error?: string;
+    evidenceId?: string;
+    /** Verifier nodes only: whether the contract passed. */
+    passed?: boolean;
+    /** Verifier nodes only: the tree digest at the moment the checks finished. */
+    treeFingerprint?: string;
+    /** human_gate nodes: park the run until a human answers. */
+    awaitHuman?: boolean;
+    costUsd?: number;
+    artifacts?: string[];
+    /** Advisory. Recorded on the run; never consulted for completion. */
+    consensusVotes?: ConsensusVote[];
+    /** Router nodes: the node id control should move to. */
+    goto?: string;
+    /** Subflow nodes: the child run this node started. */
+    childRunId?: string;
+    /** Mode-specific payload to checkpoint on the node record. */
+    data?: unknown;
+}
+export interface NodeContext {
+    runId: string;
+    record: RunRecord;
+    cwd: string;
+    /**
+     * 1-based attempt number for this visit. Nodes that name external resources
+     * must include it: a timed-out attempt is abandoned, not killed, so it is
+     * still running — and still holds a `finally` that tears down whatever it
+     * named. Sharing a name with the retry means the dying attempt stops the live
+     * one's session.
+     */
+    attempt: number;
+    manager?: SessionManagerLike;
+    logger: Logger;
+    signal: {
+        aborted: boolean;
+    };
+    /** Text injected by `steer()` since this node last ran. Consumed by the node. */
+    takeSteer(): string[];
+    emit(event: KernelEvent): void;
+    /** The workflow-level contract, for a `contract: 'run'` verifier node. */
+    runContract?: AcceptanceContract;
+    /** In-memory values the spec deliberately does not carry. Never persisted. */
+    secrets: Record<string, unknown>;
+    /** `StartOptions.tag` for the start that launched this node, when one was given. */
+    tag?: string;
+    /**
+     * Publish the live engine object for this node (a `Council`, a `Fanout`, an
+     * autoloop dispatcher) so in-flight control — inject, abort, chat — can reach
+     * it. In-memory by necessity: you cannot inject into a turn in a process that
+     * is gone, and pretending otherwise would be the kind of claim this release
+     * exists to remove. After a restart a run resumes; it does not reconnect.
+     */
+    setHandle(handle: unknown): void;
+    /** Checkpoint mode payload as the node runs, not only when it finishes. */
+    publish(data: unknown): void;
+    /**
+     * Record a child run started by this node, immediately.
+     *
+     * It has to land before the child finishes, not with the node's result: the
+     * whole point is that cancelling the parent can find the child, and a parent
+     * cancelled mid-subflow is exactly when the id is not yet in the record.
+     */
+    setChild(childRunId: string): void;
+}
+export type NodeExecutor = (node: NodeSpec, ctx: NodeContext) => Promise<NodeResult>;
+export interface KernelOptions {
+    manager?: SessionManagerLike;
+    logger?: Logger;
+    executors?: Partial<Record<NodeKind, NodeExecutor>>;
+    /** Default per-node wall clock. */
+    nodeTimeoutMs?: number;
+}
+export interface StartOptions {
+    runId?: string;
+    cwd?: string;
+    /** Overrides `spec.contract`. Callers only — never sourced from agent output. */
+    contract?: unknown;
+    /**
+     * Opaque label for THIS start, handed to nodes as `ctx.tag`.
+     *
+     * A run id can be reused — a start that failed frees it for a retry — so
+     * anything the caller keys on the run id can be clobbered by the next start.
+     * The tag identifies one attempt at running it.
+     */
+    tag?: string;
+    /**
+     * Values a node needs but the spec must not carry — custom-engine configs,
+     * whose `env` holds credentials.
+     *
+     * These live only in this process's memory. They are never written to
+     * `spec.json` or `run.json`, and a resume in another process has to supply
+     * them again rather than reading them back, which is the point.
+     */
+    secrets?: Record<string, unknown>;
+}
+/**
+ * Append the implicit terminal verifier when a run-level contract exists and the
+ * author did not already place one. This is what makes `completed` mean "checked".
+ */
+/**
+ * Reject a spec that cannot execute correctly, before anything runs.
+ *
+ * These are all mistakes that used to surface much later and much worse: a
+ * duplicate node id silently overwrote a record so one of the two nodes had no
+ * state; a `next` or router target naming a node that does not exist failed the
+ * run halfway through with `unknown node`; a negative retry or visit bound was
+ * accepted and then behaved arbitrarily.
+ */
+export declare function validateSpec(spec: WorkflowSpec): void;
+export declare function prepareSpec(spec: WorkflowSpec): WorkflowSpec;
+export declare class RunKernel extends EventEmitter {
+    private readonly manager?;
+    private readonly logger;
+    private readonly executors;
+    private readonly nodeTimeoutMs;
+    private readonly live;
+    /**
+     * This kernel's identity as a run owner.
+     *
+     * Per instance, not per process: two `RunKernel`s in one process — two
+     * SessionManagers is not exotic — would otherwise share a pid and each treat
+     * the other's lease as its own, so both would execute the same run.
+     */
+    readonly ownerId: string;
+    /**
+     * Per-run secrets, in memory only. Keyed by run id so a resume in this
+     * process can re-use what the start supplied; a resume elsewhere must be
+     * given them again.
+     */
+    private readonly _secrets;
+    /** Caller label for the most recent start of each run. */
+    private readonly _tags;
+    constructor(opts?: KernelOptions);
+    /** Stop and await any live run holding this id, so a reuse cannot overlap it. */
+    private _retire;
+    /** Register (or replace) the executor for one node kind. */
+    setExecutor(kind: NodeKind, executor: NodeExecutor): void;
+    /**
+     * Open a transaction over a run this kernel has just claimed.
+     *
+     * The abort signal is created here rather than in `_launch` because the
+     * transaction has to be able to stop the run the moment a write is refused,
+     * and that can happen before the handle exists.
+     */
+    private _open;
+    /**
+     * Hand a claim back, retrying while the lock is merely busy.
+     *
+     * Best-effort with a bound: contention here is measured in microseconds, so a
+     * few backed-off attempts cover everything short of a wedged filesystem — and
+     * if it is wedged, saying so beats retrying forever.
+     */
+    private _scheduleRelease;
+    start(rawSpec: WorkflowSpec, opts?: StartOptions): Promise<RunRecord>;
+    /**
+     * Re-attach to a run whose process died. Nodes already marked succeeded are not
+     * re-run; the node that was in flight when the process ended is retried from
+     * the start, because a half-finished node left no result to trust.
+     */
+    resume(runId: string, opts?: {
+        restart?: boolean;
+        secrets?: Record<string, unknown>;
+        tag?: string;
+    }): Promise<RunRecord>;
+    cancel(runId: string): boolean;
+    /** Queue text for the current (or next) agent node. */
+    steer(runId: string, text: string): boolean;
+    /** Answer a parked `human_gate`. */
+    approve(runId: string, approved: boolean): boolean;
+    get(runId: string): RunRecord | undefined;
+    /**
+     * The live engine object a running node published, if the run is still going
+     * in this process. Undefined once the node finishes or the process restarts —
+     * which is the honest answer, not a gap.
+     */
+    handle<T>(runId: string, nodeId: string): T | undefined;
+    list(query?: ListRunsQuery): RunSummary[];
+    /**
+     * Remove a run.
+     *
+     * `expectTag` guards against deleting the wrong incarnation: a run id is
+     * reused when a failed start frees it, so a dying start's cleanup could
+     * otherwise delete the retry that had already taken the id. When the tag does
+     * not match, nothing is touched.
+     *
+     * Deleting takes the incarnation with it, which is what makes the id safe to
+     * reuse: any guard still held by an abandoned attempt of the deleted run names
+     * an incarnation that no longer exists, so it cannot write to whatever takes
+     * the id next.
+     */
+    delete(runId: string, opts?: {
+        expectTag?: string;
+    }): boolean;
+    /**
+     * Resolves when the run reaches a terminal state. A run that already finished
+     * (or belongs to another process) resolves from disk, so the caller does not
+     * have to race the completion.
+     */
+    wait(runId: string): Promise<RunRecord | undefined>;
+    shutdown(): Promise<void>;
+    private _launch;
+    private _setRunState;
+    private _setNodeState;
+    private _nodeSpec;
+    private _nextInOrder;
+    private _firstPending;
+    private _executeNode;
+    /**
+     * Wait for abandoned attempts to stop, so a terminal verdict describes a tree
+     * nobody is still writing to.
+     *
+     * A timed-out node is not killed — JS gives us no way to — so a run used to
+     * stamp `completed / verified`, then have the abandoned attempt write to the
+     * workspace afterwards. The evidence was accurate at the moment it was taken
+     * and wrong seconds later, with nothing recording that.
+     */
+    private _awaitQuiescence;
+    private _run;
+    private _runWithRetry;
+    private _park;
+    /** Node kinds that can change the workspace. Routers and gates cannot. */
+    private static readonly SIDE_EFFECT_KINDS;
+    /**
+     * Fold a node's result into the run — output, artifacts, cost, votes, verdict
+     * — as one committed change.
+     *
+     * Every one of these used to be assigned straight onto the live record, with
+     * only the events fenced. A superseded owner therefore returned a record
+     * carrying an output, a cost and a passing verdict that the disk had refused.
+     */
+    private _absorb;
+    /**
+     * Decide the terminal state. `completed` requires that nothing refuted the run;
+     * a run with no contract completes as `unverified`, which says we did not check
+     * rather than claiming success.
+     */
+    private _finish;
+    /**
+     * Why a passing verdict no longer stands, or undefined if it still does.
+     *
+     * `prepareSpec` cannot enforce this structurally: a router can send control
+     * anywhere, so which node runs last is not a property of the spec. And a
+     * "nothing after the verifier" rule would be the wrong rule anyway — what
+     * matters is not that a node ran, but that the tree moved. So this measures.
+     *
+     * The caller drops the outcome to `unverified`, not `refuted`: no check
+     * failed. We simply no longer know, and saying so is the whole point of having
+     * three outcomes.
+     */
+    private _verdictWentStale;
+}
+/** Run directory for a given run — re-exported so callers need not import the store. */
+export { runDir, summarize };