melchizedek-agents 0.18.0 → 0.20.0

package/dist/lib/workflow/scheduler.d.ts

@@ -0,0 +1,418 @@
+/**
+ * lib/workflow/scheduler.ts — the engine's own walk of a workflow graph.
+ *
+ * `runWorkflowGraph(graph, options)` runs the `WorkflowGraph` that
+ * `buildWorkflowGraph` (lib/workflow/graph.ts) builds: a node runs when a
+ * predecessor's completion triggers it, a node with several successors fans
+ * out, a `join` waits until every predecessor has completed, a `map` runs its
+ * agent once per item under `maxParallel`, and each node's output is the
+ * input its successors receive. It imports nothing from ADK.
+ *
+ * What a node DOES is not this module's business. Agent, tool and ask_user
+ * nodes, and each item of a map, are run by the `runNode` function the caller
+ * passes in (WS4-3, WS4-5 and WS4-4a supply them). The scheduler runs the
+ * kinds that are pure graph mechanics itself: the start node seeds the walk,
+ * a `join` outputs `{ <predecessor>: <output> }`, a `route` step re-emits its
+ * input with the route `routeOf` reads from it, and a `map` is the worker
+ * pool around its items.
+ *
+ * ── The same walk as ADK's Workflow ──────────────────────────────────────
+ * The loop is ADK 2.2's (`Workflow.runLoop`, workflow/workflow.js), step for
+ * step, so a graph completes in the order ADK records for it
+ * (tests/workflowScheduler.test.ts runs both and compares):
+ *
+ *   - Triggers are buffered per node, in the order they were pushed. Each
+ *     pass starts every buffered node that is not already running, in the
+ *     buffer's order, until `maxConcurrency` nodes are pending.
+ *   - The loop then waits for the first pending node to settle, by
+ *     `Promise.race` over the pending runs in the order they started, so of
+ *     two runs already settled the one started first is handled first.
+ *   - A completed node pushes one trigger to each successor its route
+ *     selects (`always` edges, the edges keyed to its route compared as
+ *     strings in ADK's spelling of the key, else the `default` edge). A join
+ *     is triggered only once every predecessor has COMPLETED, with their
+ *     outputs keyed in edge order. A node triggered while it runs runs again
+ *     afterwards, once per trigger, as ADK does: only a join waits for all.
+ *   - Branches and node paths are ADK's (`Planner@1`, `Six.Fan.Agent@0`), so
+ *     the events a node runner writes can carry the values ADK writes.
+ *   - The workflow's output is the one terminal node's output; two terminal
+ *     outputs fail the run with ADK's message.
+ *
+ * ── The controls (ADK's node_runner.js, ADR 0089) ─────────────────────────
+ * Every node run goes through `executeNode`, and every attempt of it through
+ * `withControls`, which is ADK's `runChildNode` loop:
+ *
+ *   - **Timeout.** A node with `timeout` races each attempt against a timer;
+ *     the runner's signal aborts when it fires and the attempt fails with
+ *     `NodeTimeoutError`. Without a timeout the attempt is awaited, as ADK
+ *     awaits it: the runner gets the signal and must settle when it aborts.
+ *   - **Retry.** A failed attempt is retried while the node's `retry` allows
+ *     (`max_attempts`, default 5; an `exceptions` list of error names when
+ *     one is given), after ADK's backoff with its jitter. An abort and a map
+ *     item's failure are never retried; an abort cuts a backoff short.
+ *   - **Node errors.** A runner reports an error by returning `error`: the
+ *     walk emits it (`node_error`, source `node`) and, when the result has no
+ *     output and no route, the attempt fails with `NodeReportedError`. A node
+ *     that gives up fails the walk; the walk emits that error once (source
+ *     `workflow`) unless the node already reported it or the walk was
+ *     aborted, then aborts the other runs, lets them settle and rethrows the
+ *     error unchanged. Every `node_error` is collected in `nodeErrors`, in
+ *     the shape runSyndicateTurn's drain collects ADK's error events.
+ *   - **Abort and deadline.** The walk's signal is the caller's, else the
+ *     current turn's (lib/runtime/turnControl.ts), so a cancel or a deadline
+ *     reaches every run. Once it fires no node starts, and the walk rejects
+ *     with `InvocationAbortedError` when nothing is left running.
+ *   - **max_concurrency** counts every pending run, a retrying one included.
+ *
+ * A map item runs under its agent's own modifiers (`nodes.<agent>`), and an
+ * item that gives up fails the map with `DynamicNodeFailError`, as ADK's
+ * ParallelWorker does; the map entry's own `retry` and `timeout` are not
+ * applied, because ADK's compile does not apply them.
+ *
+ * ── Interrupts (ADK's handleCompletion and finalize, ADR 0092) ───────────
+ * A runner that pauses its node on a person returns `interruptIds` (the ids
+ * of the input requests its events carry; lib/workflow/pause.ts raises them
+ * for an ask_user node). The node then WAITS, as ADK's does: it is not
+ * completed, records no output, triggers no successor, and is not started
+ * again by a later trigger in the same walk. The rest of the graph runs on.
+ * A walk that ends with a node waiting resolves with every open id in
+ * `interruptIds`, in the order the nodes paused, and no output (ADK skips
+ * the terminal check). A reported error with an interrupt is not the node's
+ * failure. A map item's interrupts are not carried (an agent node's own
+ * pause does not run here yet).
+ *
+ * ── Resume (ADK's startNodeTask on rehydrated state, ADR 0094) ───────────
+ * A walk given `resume` (lib/workflow/resume.ts builds it from the stored
+ * events) starts from START as ADK's does, and each node's first activation
+ * takes that node's next prior run:
+ *
+ *   - a prior run with an output or a route and no open interrupt is done:
+ *     the node completes at once with that output, route and branch, emits
+ *     `node_resumed` (not `node_start` or `node_end`; ADK writes no event
+ *     for it) and triggers its successors as a completion does;
+ *   - a paused prior run of a node that does not rerun on resume
+ *     (`rerunsOnResume`) completes with its answers, the same way;
+ *   - any other node runs, a paused one on the input it recorded, with the
+ *     answers in `NodeRun.resumeInputs` (none on a repeat activation in the
+ *     same walk). Neither shortcut counts as a run of the node.
+ *
+ * A task-mode node that waits for its output (WS4-3) is a later ticket.
+ *
+ * ── Tracing (ADR 0095) ───────────────────────────────────────────────────
+ * The scheduler opens no span. A caller that passes `traceNode` has each
+ * node run (every attempt and backoff inside it) and each map item's run
+ * wrapped, as ADK's node runner opens `execute_node` around them; the
+ * native turn (lib/workflow/turn.ts) passes the engine's `node.execute`
+ * span, so an agent node's own spans nest under it.
+ */
+import type { TurnEvent } from '../runtime/events.ts';
+import type { AgentNode, AskUserNode, GraphNodeKind, MapNode, ToolNode, WorkflowGraph } from './graph.ts';
+import type { RetryYaml } from '../workflowConfig.ts';
+import type { ResumeState } from './resume.ts';
+/** ADK's ParallelWorker pool size when `max_parallel` is not set. */
+export declare const DEFAULT_MAX_PARALLEL = 8;
+/** A graph node the caller's runner executes. */
+export type RunnableNode = AgentNode | ToolNode | AskUserNode;
+/** One item of a map: the map's agent run on `items[index]`. */
+export interface MapItem {
+    kind: 'map_item';
+    /** The agent run on the item. */
+    agent: string;
+    /** The map node. */
+    map: MapNode;
+    index: number;
+}
+/** One run of a node, as the scheduler hands it to the runner. */
+export interface NodeRun {
+    target: RunnableNode | MapItem;
+    /** The predecessor's output; a join's `{ <predecessor>: <output> }`; the workflow input after START; a map's item. */
+    input: unknown;
+    /** The node's run counter as a string ("1", "2", ...); a map item's index. */
+    runId: string;
+    /** ADK's node path: `<workflow>.<node>`, or `<workflow>.<map>.<agent>@<index>` for a map item. */
+    path: string;
+    /** ADK's branch, undefined at the workflow's own branch. */
+    branch: string | undefined;
+    /**
+     * Aborted when this attempt must stop: the walk's signal fired (a cancel,
+     * the turn's deadline, another node failed) or the node's timeout did.
+     * A runner settles promptly once it aborts.
+     */
+    signal: AbortSignal;
+    /** Which attempt this is, from 1; above 1 only for a node with `retry`. */
+    attempt: number;
+    /**
+     * A resumed walk's answers, by interrupt id (ADK's ctx.resumeInputs):
+     * every answer, on a node's first activation; empty on a repeat one.
+     * Absent in a walk that is not a resume.
+     */
+    resumeInputs?: Readonly<Record<string, unknown>>;
+    /**
+     * The interrupts this node's prior run paused on, when this run resumes it
+     * (a resumed walk's first activation of a node that waited). An agent node
+     * resumes its own run on them instead of starting afresh (ADR 0098).
+     */
+    resumedInterruptIds?: readonly string[];
+}
+/** An error a node reports instead of throwing, as an ADK event's errorCode and errorMessage. */
+export interface ReportedNodeError {
+    code: string;
+    message: string;
+}
+/** What a node run produced. */
+export interface NodeResult {
+    /** The node's output, handed to its successors as their input. */
+    output?: unknown;
+    /** The route(s) the node emitted; only keyed edges read it. */
+    route?: unknown;
+    /**
+     * An error the node reported. It is emitted and collected; with no output,
+     * no route and no interrupt the attempt fails (`NodeReportedError`) and
+     * may be retried.
+     */
+    error?: ReportedNodeError;
+    /**
+     * The ids of the input requests the node paused on (ADK's
+     * `longRunningToolIds` on its events). Non-empty: the node waits, and its
+     * output and route are not acted on.
+     */
+    interruptIds?: string[];
+}
+export type NodeRunner = (run: NodeRun) => NodeResult | Promise<NodeResult>;
+/** One collected node error, in the shape runSyndicateTurn's `answer.nodeErrors` holds. */
+export interface CollectedNodeError {
+    node: string;
+    code: string;
+    message: string;
+}
+/** What the walk reports as it goes. */
+export type SchedulerEvent = {
+    type: 'node_start';
+    node: string;
+    kind: GraphNodeKind;
+    runId: string;
+    path: string;
+    branch: string | undefined;
+    input: unknown;
+} | {
+    type: 'node_end';
+    node: string;
+    kind: GraphNodeKind;
+    runId: string;
+    path: string;
+    branch: string | undefined;
+    output: unknown;
+    route?: unknown;
+} | {
+    type: 'node_waiting';
+    node: string;
+    kind: GraphNodeKind;
+    runId: string;
+    path: string;
+    branch: string | undefined;
+    interruptIds: string[];
+}
+/**
+ * A resumed walk completed the node from its stored run without running
+ * it: `stored` (its prior output), or `answers` (a node that does not
+ * rerun, completed with the answers to its interrupts). ADK writes no
+ * event for either.
+ */
+ | {
+    type: 'node_resumed';
+    node: string;
+    kind: GraphNodeKind;
+    path: string;
+    branch: string | undefined;
+    output: unknown;
+    route?: unknown;
+    from: 'stored' | 'answers';
+} | {
+    type: 'item_start';
+    node: string;
+    agent: string;
+    index: number;
+    path: string;
+    branch: string | undefined;
+    input: unknown;
+} | {
+    type: 'item_end';
+    node: string;
+    agent: string;
+    index: number;
+    path: string;
+    branch: string | undefined;
+    output: unknown;
+} | {
+    type: 'node_error';
+    /**
+     * `node`: the node reported it on an attempt (ADK: the node's own event
+     * carrying an errorCode). `workflow`: the node gave up and the walk
+     * reports why (ADK: the workflow's node-error event).
+     */
+    source: 'node' | 'workflow';
+    /** The node, or a map item's agent, as ADK's event author. */
+    node: string;
+    path: string;
+    /** The run's branch for `node`; the workflow's own branch for `workflow`, as ADK writes it. */
+    branch: string | undefined;
+    code: string;
+    message: string;
+    /** The error's class name (ADK's errorType); `workflow` only. */
+    errorType?: string;
+    /** The attempt it happened on; for `workflow`, the attempts made. */
+    attempt: number;
+};
+export interface RunWorkflowOptions {
+    /** The workflow's input: what the nodes after START receive. */
+    input: unknown;
+    /** Runs agent, tool and ask_user nodes and map items. */
+    runNode: NodeRunner;
+    /** Aborts every run in flight when it fires. Default: the current turn's signal (turnControl), if any. */
+    signal?: AbortSignal;
+    /** Called synchronously for every event, in order. */
+    onEvent?: (event: SchedulerEvent) => void;
+    /** The workflow's own node path; default the graph's name. */
+    nodePath?: string;
+    /** The workflow's own branch; default none. */
+    branch?: string;
+    /**
+     * Resume a paused walk: the prior runs and answers workflowResume
+     * (lib/workflow/resume.ts) rebuilt from the stored events. The scheduler
+     * consumes `priorRuns`.
+     */
+    resume?: ResumeState;
+    /**
+     * Wraps each node's run (every attempt of it, the backoffs included) and
+     * each map item's, as ADK's node runner opens its `execute_node` span
+     * around them. The turn runner passes the engine's span here
+     * (lib/runtime/native/telemetry.ts, ADR 0095); the scheduler itself
+     * knows nothing of tracing. A node completed from its stored run on a
+     * resume runs nothing and is not wrapped. Default: none.
+     */
+    traceNode?: NodeTracer;
+}
+/** What a node tracer learns about the run it wraps. */
+export interface TracedNode {
+    /** The node, or a map item's agent. */
+    name: string;
+    kind: GraphNodeKind | 'map_item';
+    path: string;
+    /** The run id (a map item's index). */
+    runId: string;
+    /** The run's attempt counter: read it once the run settles for the attempts made. */
+    attempts: {
+        readonly count: number;
+    };
+}
+/** Wraps one node run; must return what `run` returns, or rethrow what it throws. */
+export type NodeTracer = (node: TracedNode, run: () => Promise<NodeResult>) => Promise<NodeResult>;
+export interface WorkflowRun {
+    /** The terminal node's output, or undefined when no terminal node produced one. */
+    output: unknown;
+    /** Every completed node's latest output, by name (a node whose output was undefined is absent, as in ADK). */
+    outputs: Map<string, unknown>;
+    /** Node names in the order they completed (a node that ran twice appears twice; a resumed walk's `node_resumed` nodes included). */
+    order: string[];
+    /** Every node error the walk emitted, in order: the attempts that failed and were retried or survived. */
+    nodeErrors: CollectedNodeError[];
+    /**
+     * The input requests the walk ended waiting on, in the order their nodes
+     * paused. Non-empty: the walk is paused (input-required) and `output` is
+     * undefined.
+     */
+    interruptIds: string[];
+}
+/** A node ran past its `timeout`. */
+export declare class NodeTimeoutError extends Error {
+    readonly nodeName: string;
+    readonly timeout: number;
+    constructor(options: {
+        nodeName: string;
+        timeout: number;
+    });
+}
+/** A node reported an error and produced no output and no route. */
+export declare class NodeReportedError extends Error {
+    readonly code: string;
+    readonly nodeName: string;
+    constructor(options: {
+        nodeName: string;
+        errorCode?: string;
+        errorMessage?: string;
+    });
+}
+/** The walk, or one node's run, stopped because its signal fired. */
+export declare class InvocationAbortedError extends Error {
+    constructor(message?: string, options?: {
+        cause?: unknown;
+    });
+}
+/** A map item gave up; the map fails with this. */
+export declare class DynamicNodeFailError extends Error {
+    readonly error: Error;
+    readonly errorNodePath: string;
+    constructor(options: {
+        message: string;
+        error: Error;
+        errorNodePath: string;
+    });
+}
+/** ADK's defaults when a `retry` block leaves a field out. */
+export declare const RETRY_DEFAULTS: {
+    readonly maxAttempts: 5;
+    readonly initialDelay: 1;
+    readonly maxDelay: 60;
+    readonly backoffFactor: 2;
+    readonly jitter: 1;
+};
+/**
+ * A node's retry, as the YAML spells it: ADK's fields, `exceptions` (the
+ * error names that may be retried, all when absent) and `jitter` (the
+ * random spread, default 1) included.
+ */
+export type RetrySettings = RetryYaml;
+/** The names an error answers to: its class's and its `name`, as ADK matches `exceptions`. */
+export declare function errorNames(error: unknown): string[];
+/** ADK's errorType: the class name, or the assigned name of a plain Error. */
+export declare function errorName(error: unknown): string;
+/** Whether a node that has made `attempts` attempts and failed with `error` runs again. */
+export declare function shouldRetry(error: unknown, retry: RetrySettings, attempts: number): boolean;
+/** Seconds to wait before the attempt after `attempts`: exponential backoff, capped, with ADK's jitter. */
+export declare function retryDelaySeconds(retry: RetrySettings, attempts: number, random?: () => number): number;
+/**
+ * Run a workflow graph to its end. Resolves with the workflow's output, every
+ * node's output and the completion order; rejects with the first node error,
+ * after every run still pending has settled.
+ */
+export declare function runWorkflowGraph(graph: WorkflowGraph, options: RunWorkflowOptions): Promise<WorkflowRun>;
+/** The event ADK's workflow writes for a node that gave up (`createNodeErrorEvent`). */
+export type NodeErrorTurnEvent = TurnEvent & {
+    isNodeError: true;
+    errorType: string;
+    errorCode: string;
+    errorMessage: string;
+    attemptCount: number;
+};
+/**
+ * The event ADK stores for a `node_error` the walk reported (source
+ * `workflow`): ADK's `createNodeErrorEvent`, field for field and in its key
+ * order, so a turn runner can write it where ADK writes it. An error a node
+ * reported itself (source `node`) is already on the event its runner wrote.
+ */
+export declare function nodeErrorEvent(event: Extract<SchedulerEvent, {
+    type: 'node_error';
+}>, invocationId: string): NodeErrorTurnEvent;
+/**
+ * The walk as a stream: every event as it happens, then the run as the
+ * generator's return value. The walk does not wait for the consumer, so a
+ * slow reader never changes the order.
+ */
+export declare function streamWorkflowGraph(graph: WorkflowGraph, options: Omit<RunWorkflowOptions, 'onEvent'>): AsyncGenerator<SchedulerEvent, WorkflowRun>;
+/**
+ * The successors a completed node triggers, as ADK's `getNextPendingNodes`
+ * selects them: every `always` edge; every keyed edge whose key (in ADK's
+ * spelling) equals the emitted route, or one of them, compared as strings;
+ * and the `default` edge when no keyed edge matched.
+ */
+export declare function nextNodes(graph: WorkflowGraph, name: string, route: unknown): string[];