@cleocode/playbooks 2026.4.93 → 2026.4.95

package/dist/runtime.d.ts

@@ -0,0 +1,206 @@
+/**
+ * Playbook runtime — deterministic state machine executor for `.cantbook` flows.
+ *
+ * This module is the executable heart of CLEO's T910 "Orchestration Coherence v4"
+ * pipeline. It walks a validated {@link PlaybookDefinition} one node at a time,
+ * merging node outputs into a shared `context`, enforcing per-node iteration
+ * caps, and pausing for HITL approval gates via the signed resume-token
+ * protocol (see `approval.ts`).
+ *
+ * Design constraints (non-negotiable):
+ *
+ * 1. Pure dependency injection — the runtime never imports or instantiates
+ *    subprocess code. Callers pass an {@link AgentDispatcher} for `agentic`
+ *    nodes and an optional {@link DeterministicRunner} for `deterministic`
+ *    nodes. Tests can therefore exercise every branch without mocking any
+ *    `@cleocode/*` module.
+ * 2. Deterministic ordering — a topological traversal is computed up front
+ *    from the {@link PlaybookDefinition.edges} graph (with `depends[]`
+ *    treated as reverse edges, exactly as the parser's cycle check does).
+ *    Execution order is stable across runs for the same definition.
+ * 3. Fail-closed policy — unknown node kinds, missing successors, unresolved
+ *    `inject_into` targets, or dispatcher errors all terminate the run with
+ *    a typed `terminalStatus`. The runtime never silently swallows failures.
+ * 4. HITL gates persist — when an `approval` node executes, the run is
+ *    marked `paused` in `playbook_runs`, a {@link PlaybookApproval} row is
+ *    written with the HMAC-signed resume token, and the returned
+ *    {@link ExecutePlaybookResult.approvalToken} is what the human reviewer
+ *    must present via `resumePlaybook` to continue.
+ *
+ * @task T930 — Playbook Runtime State Machine
+ */
+import type { DatabaseSync } from 'node:sqlite';
+import type { PlaybookDefinition } from '@cleocode/contracts';
+/**
+ * Input payload handed to {@link AgentDispatcher.dispatch} on every
+ * `agentic` node execution. All fields are read-only from the dispatcher's
+ * perspective — the runtime owns the lifecycle.
+ */
+export interface AgentDispatchInput {
+    /** Playbook run identifier (FK into `playbook_runs.run_id`). */
+    runId: string;
+    /** Node identifier within the run graph. */
+    nodeId: string;
+    /** Agent identity resolved from `node.agent` (falls back to `node.skill`). */
+    agentId: string;
+    /** Task identifier lifted from `context.taskId` if present, otherwise `runId`. */
+    taskId: string;
+    /** Snapshot of the accumulated bindings at dispatch time. */
+    context: Record<string, unknown>;
+    /** 1-based iteration counter for this specific node (retry-aware). */
+    iteration: number;
+}
+/**
+ * Terminal output returned by {@link AgentDispatcher.dispatch}. The runtime
+ * merges {@link output} into the run context on `status === 'success'` and
+ * triggers iteration-cap / escalation logic on `'failure'`.
+ */
+export interface AgentDispatchResult {
+    status: 'success' | 'failure';
+    /** Key-value pairs merged into the run context on success. */
+    output: Record<string, unknown>;
+    /** Human-readable failure reason. Persisted to `playbook_runs.error_context`. */
+    error?: string;
+}
+/**
+ * Injected contract for spawning subagents. Implementations MUST NOT depend
+ * on any `@cleocode/*` module — the runtime passes all state through
+ * {@link AgentDispatchInput} so tests can provide deterministic stubs.
+ */
+export interface AgentDispatcher {
+    /** Execute a single `agentic` node; return a success/failure envelope. */
+    dispatch(input: AgentDispatchInput): Promise<AgentDispatchResult>;
+}
+/**
+ * Input payload handed to {@link DeterministicRunner.run} on every
+ * `deterministic` node execution.
+ */
+export interface DeterministicRunInput {
+    runId: string;
+    nodeId: string;
+    command: string;
+    args: readonly string[];
+    cwd?: string;
+    env?: Readonly<Record<string, string>>;
+    /** Timeout in milliseconds; `undefined` means the runner picks a default. */
+    timeout_ms?: number;
+    context: Record<string, unknown>;
+    iteration: number;
+}
+/**
+ * Terminal output returned by {@link DeterministicRunner.run}. Shape mirrors
+ * {@link AgentDispatchResult} for runtime uniformity.
+ */
+export interface DeterministicRunResult {
+    status: 'success' | 'failure';
+    output: Record<string, unknown>;
+    error?: string;
+}
+/**
+ * Injected contract for running `deterministic` nodes (CLI tools, validators,
+ * decide scripts). If not supplied, the runtime delegates to
+ * {@link AgentDispatcher.dispatch} with `agentId = "deterministic:<command>"`
+ * so a single stub can cover both node kinds during unit testing.
+ */
+export interface DeterministicRunner {
+    run(input: DeterministicRunInput): Promise<DeterministicRunResult>;
+}
+/**
+ * Options accepted by {@link executePlaybook}.
+ */
+export interface ExecutePlaybookOptions {
+    /** Open `node:sqlite` handle with the T889 migration applied. */
+    db: DatabaseSync;
+    /** Validated playbook definition (output of {@link parsePlaybook}). */
+    playbook: PlaybookDefinition;
+    /** SHA-256 hex of the playbook source (output of {@link parsePlaybook}). */
+    playbookHash: string;
+    /** Starting bindings seeded into the run context (e.g. `{ taskId }`). */
+    initialContext: Record<string, unknown>;
+    /** Required dispatcher for `agentic` nodes. */
+    dispatcher: AgentDispatcher;
+    /** Optional runner for `deterministic` nodes. Defaults to `dispatcher`. */
+    deterministicRunner?: DeterministicRunner;
+    /** Override secret for HMAC resume-token signing. */
+    approvalSecret?: string;
+    /** Fallback per-node iteration cap when `on_failure.max_iterations` is unset. */
+    maxIterationsDefault?: number;
+    /** Epic id persisted to `playbook_runs.epic_id` for dashboard filtering. */
+    epicId?: string;
+    /** Session id persisted to `playbook_runs.session_id`. */
+    sessionId?: string;
+    /** Injectable clock for deterministic tests (defaults to `() => new Date()`). */
+    now?: () => Date;
+}
+/**
+ * Options accepted by {@link resumePlaybook}. The runtime validates that the
+ * supplied approval token resolves to an `approved` {@link PlaybookApproval}
+ * row before continuing execution.
+ */
+export interface ResumePlaybookOptions {
+    db: DatabaseSync;
+    playbook: PlaybookDefinition;
+    /** The token previously returned in {@link ExecutePlaybookResult.approvalToken}. */
+    approvalToken: string;
+    dispatcher: AgentDispatcher;
+    deterministicRunner?: DeterministicRunner;
+    approvalSecret?: string;
+    maxIterationsDefault?: number;
+    now?: () => Date;
+}
+/**
+ * Terminal status values reported by the runtime.
+ */
+export type PlaybookTerminalStatus = 'completed' | 'failed' | 'pending_approval' | 'exceeded_iteration_cap';
+/**
+ * Final envelope returned by both {@link executePlaybook} and
+ * {@link resumePlaybook}.
+ */
+export interface ExecutePlaybookResult {
+    runId: string;
+    terminalStatus: PlaybookTerminalStatus;
+    /** Fully-merged bindings at the point the runtime stopped. */
+    finalContext: Record<string, unknown>;
+    /** Set when `terminalStatus === 'pending_approval'`. */
+    approvalToken?: string;
+    /** Set when the run stopped because a specific node failed. */
+    failedNodeId?: string;
+    /** Set when the run stopped because a node hit its iteration cap. */
+    exceededNodeId?: string;
+    /** Human-readable error reason mirrored from the last failing node. */
+    errorContext?: string;
+}
+/**
+ * Error code stamped onto errors thrown by the runtime for invalid inputs.
+ * Exported for parity with the rest of the `@cleocode/playbooks` error codes.
+ */
+export declare const E_PLAYBOOK_RUNTIME_INVALID: "E_PLAYBOOK_RUNTIME_INVALID";
+/**
+ * Error code thrown when {@link resumePlaybook} is called with a token that
+ * does not resolve to an `approved` gate.
+ */
+export declare const E_PLAYBOOK_RESUME_BLOCKED: "E_PLAYBOOK_RESUME_BLOCKED";
+/**
+ * Execute a playbook from its entry node until a terminal state is reached
+ * (`completed`, `failed`, `exceeded_iteration_cap`, or `pending_approval`).
+ *
+ * Every execution is persisted to `playbook_runs` so that crashes or HITL
+ * pauses can resume via {@link resumePlaybook}. Returned
+ * {@link ExecutePlaybookResult.finalContext} is a fully-merged snapshot at
+ * the moment the runtime stopped.
+ *
+ * @param options - Runtime configuration, including the injected dispatcher.
+ * @returns Terminal envelope describing where the run stopped.
+ */
+export declare function executePlaybook(options: ExecutePlaybookOptions): Promise<ExecutePlaybookResult>;
+/**
+ * Resume a paused playbook run using a HITL approval token. The runtime
+ * validates that the token maps to an `approved` {@link PlaybookApproval}
+ * row and that the associated run is in `paused` state, then continues from
+ * the approval node's single successor.
+ *
+ * @throws Error stamped with {@link E_PLAYBOOK_RESUME_BLOCKED} if the token
+ *   is unknown, the gate is still `pending`, the gate was `rejected`, the
+ *   run is not `paused`, or the approval node has no successor.
+ */
+export declare function resumePlaybook(options: ResumePlaybookOptions): Promise<ExecutePlaybookResult>;