agentfootprint 7.10.0 → 7.11.0

package/dist/esm/core-flow/Graph.d.ts

@@ -0,0 +1,272 @@
+/**
+ * graph() — a FIXED DAG of runners, levelized at build time.
+ *
+ * WHY this exists: `Sequence` and `workflow()` run steps in a line, and
+ * `Parallel` fans out ONCE and merges. Real pipelines are neither: an
+ * intake step feeds two independent lookups, and a writer waits for both.
+ * Expressing that with the existing compositions means nesting a Parallel
+ * inside a Sequence and threading values through by hand — and on this
+ * codebase that hand-off silently loses structured data (see "The trap"
+ * below). `graph()` states the shape once, as nodes and edges, and lets
+ * the engine work out what can run at the same time.
+ *
+ * What it gives you:
+ *   - **Concurrency you did not have to schedule.** Kahn levelization at
+ *     BUILD time groups nodes with no dependency between them; every node
+ *     in a level runs at the same time.
+ *   - **A shape checked before it runs.** A cycle, an edge pointing at a
+ *     node that does not exist, or a duplicate id is refused at BUILD
+ *     time, naming the offender. You cannot construct a broken graph.
+ *   - **No silent merges.** A node with two or more parents MUST declare
+ *     a `join` — a silent merge is a wrong merge, so the build refuses
+ *     and names the node.
+ *   - **Values, not text.** An edge's payload is the producer's OUTPUT
+ *     handed to the consumer, unchanged. There is no shared mutable scope
+ *     between nodes: a node reads exactly what its parents produced.
+ *
+ * Pattern: Adapter over footprintjs's subflow mounts — a level with
+ *          several nodes becomes stacked `addSubFlowChart` calls (a fork,
+ *          run concurrently); a level with one node is mounted
+ *          sequentially (`addSubFlowChartNext`, which resumes cleanly
+ *          across a pause). One join stage between levels.
+ * Role:    core-flow/ layer, alongside Sequence/Parallel/Conditional/
+ *          Loop/Workflow. Pure control flow — no LLM dependency.
+ * Emits:   agentfootprint.composition.enter / exit, reported as kind
+ *          `'Sequence'`. See "Why kind 'Sequence'" below.
+ *
+ * ## The trap this was built around (verified against footprintjs, not docs)
+ *
+ * The obvious sketch — `graph = Sequence(Parallel(level0), Parallel(level1), …)`
+ * — does NOT work on this codebase, for two independent reasons:
+ *
+ *   1. `Sequence`'s step contract is `{ message: string } -> string`, and
+ *      its step `outputMapper` coerces a non-string step output to `''`.
+ *      `workflow()` (v7.10.0) exists precisely because of this.
+ *   2. `Parallel` has the SAME limit one layer down: its branch type is
+ *      `Runner<{ message: string }, string>` and its branch `outputMapper`
+ *      coerces a non-string branch output to `''` (`Parallel.ts`, the
+ *      `typeof sfOutput === 'string' ? sfOutput : ''` mapper). So a
+ *      Parallel level cannot carry a structured value either.
+ *
+ * So `graph()` is built on the pass-through model `workflow()` established
+ * — its own composition, its own mappers, the same recorder wiring and the
+ * same `composition.enter` / `exit` events — rather than on top of
+ * Sequence/Parallel.
+ *
+ * ## Why kind 'Sequence'
+ *
+ * `CompositionKind` is a CLOSED public union (`'Sequence' | 'Parallel' |
+ * 'Conditional' | 'Loop'`). Widening it would break exhaustive switches in
+ * consumer code for no behavioural gain — the same call v7.10.0 made for
+ * `workflow()`. A graph's LEVELS are a sequence (level 0, then level 1, …),
+ * so `'Sequence'` is the honest member of that union: this composition runs
+ * its levels in order. The fan-out WITHIN a level is visible in the chart
+ * itself (a fork node per level), which is where a renderer reads it from.
+ *
+ * ## Honest limits (all verified against the engine, pinned in tests)
+ *
+ *   1. Only PLAIN DATA crosses a node boundary — the same limit
+ *      `workflow()` documents. A value with a prototype (Date, Map, class
+ *      instance) arrives as `{}`; `undefined` fields are dropped.
+ *   2. A node must RETURN its output: the value handed to its children is
+ *      the node chart's traversal result.
+ *   3. A node that THROWS is always reported as
+ *      `graph '<id>': node '<node>' failed: <reason>`, but it reaches that
+ *      sentence by two different routes. In a CONCURRENT level footprintjs
+ *      runs children under `Promise.allSettled`, so a failed child is
+ *      simply ABSENT from the results and the level join turns that
+ *      absence into the error. In a SEQUENTIAL (single-node) level the
+ *      error rejects the run raw, and `rethrowWithNodeAttribution` renames
+ *      it. Consumers see one shape either way.
+ *   4. A node that PAUSES surfaces as a pause — the engine halts the
+ *      traversal before the level's join runs, so `run()` returns a
+ *      `RunnerPauseOutcome`. `resume()` then carries on through the REST
+ *      of the graph only when the paused node was ALONE in its level (a
+ *      sequential mount). Resuming into a fork child completes that child
+ *      and stops: the remaining levels do not run. Give a node that asks a
+ *      human a level of its own. Both halves are pinned in tests.
+ *
+ * @example  a diamond: A feeds B and C, D waits for both
+ * ```ts
+ * const pipeline = graph({
+ *   nodes: [
+ *     { id: 'intake', runner: intake },
+ *     { id: 'orders', runner: lookupOrders },
+ *     { id: 'billing', runner: lookupBilling },
+ *     {
+ *       id: 'reply',
+ *       runner: writeReply,
+ *       // Two parents ⇒ a join is REQUIRED. `upstream` is keyed by node id.
+ *       join: (upstream) => ({
+ *         orders: upstream.orders as OrderInfo,
+ *         billing: upstream.billing as BillingInfo,
+ *       }),
+ *     },
+ *   ],
+ *   edges: [
+ *     { from: 'intake', to: 'orders' },
+ *     { from: 'intake', to: 'billing' },
+ *     { from: 'orders', to: 'reply' },
+ *     { from: 'billing', to: 'reply' },
+ *   ],
+ * });
+ *
+ * const out = await pipeline.run({ message: 'where is my refund?' });
+ * // out = { intake: …, orders: …, billing: …, reply: … } — keyed by node id
+ * ```
+ */
+import { type FlowchartCheckpoint, type RunOptions, type StructureRecorder } from 'footprintjs';
+import type { RunnerPauseOutcome } from '../core/pause.js';
+import type { Runner } from '../core/runner.js';
+import { RunnerBase } from '../core/RunnerBase.js';
+/**
+ * One node of the graph: an id, the runner that does the work, and — when
+ * the node has more than one parent — how to merge what those parents
+ * produced into this node's input.
+ */
+export interface GraphNode<I = unknown, O = unknown> {
+    /** Unique within the graph. Used as the results key and the chart node id. */
+    readonly id: string;
+    /** The work. Any Runner: LLMCall, Agent, a Sequence, another graph. */
+    readonly runner: Runner<I, O>;
+    /**
+     * Merge upstream outputs into this node's input. `upstream` is keyed by
+     * PARENT NODE ID, and each value is that parent's output, unchanged.
+     *
+     * Optional for a node with 0 or 1 parents (a single parent's output is
+     * passed through). **REQUIRED when a node has 2+ parents** — a silent
+     * merge is a wrong merge, so the build refuses and names the node.
+     */
+    readonly join?: (upstream: Readonly<Record<string, unknown>>) => I;
+    /** Human-friendly label for events + topology. Default: the node id. */
+    readonly name?: string;
+}
+/** A directed dependency: `from` must finish before `to` starts. */
+export interface GraphEdge {
+    readonly from: string;
+    readonly to: string;
+}
+export interface GraphOptions {
+    /** The nodes. Ids must be unique; at least one is required. */
+    readonly nodes: readonly GraphNode<any, any>[];
+    /** The dependencies. Every endpoint must name a declared node. */
+    readonly edges: readonly GraphEdge[];
+    /** Human-friendly name for events + topology. Default `'Graph'`. */
+    readonly name?: string;
+    /** Stable id used for topology + events. Default `'graph'`. */
+    readonly id?: string;
+    /**
+     * Optional build-time recorders passed through to footprintjs's
+     * `flowChart()` factory — they observe this graph's OWN nodes (Seed +
+     * one mount per graph node + one join per level + Finalize). Not
+     * propagated into the mounted node charts; attach them to each node
+     * runner for full coverage.
+     */
+    readonly structureRecorders?: readonly StructureRecorder[];
+}
+/** The graph's own input — handed to every ROOT node (one with no parents). */
+export type GraphInput = Record<string, unknown>;
+/** Outputs keyed by node id. Every node that ran contributes one entry. */
+export type GraphOutput = Record<string, unknown>;
+/**
+ * Kahn levelization: group nodes so that everything in level N depends
+ * only on levels < N. Nodes within a level are independent BY
+ * CONSTRUCTION, which is exactly the licence to run them concurrently.
+ *
+ * Declaration order is preserved inside each level so a graph's chart —
+ * and therefore its trace — is deterministic.
+ *
+ * Throws (naming the offender) on: an unknown edge endpoint, a duplicate
+ * node id, a cycle, or a fan-in > 1 with no `join`.
+ */
+export declare function levelize(nodes: readonly GraphNode<any, any>[], edges: readonly GraphEdge[]): readonly (readonly GraphNode<any, any>[])[];
+/**
+ * A fixed DAG of runners. Build one with {@link graph}.
+ */
+export declare class Graph extends RunnerBase<GraphInput, GraphOutput> {
+    readonly name: string;
+    readonly id: string;
+    private readonly nodes;
+    private readonly levels;
+    private readonly parentsOf;
+    private readonly opts;
+    private currentRunContext;
+    /**
+     * Per-node first-error records for the current run. footprintjs's
+     * `SubflowExecutor` swallows a subflow error into the parent's debug
+     * bag and skips the `outputMapper`, so the message never reaches parent
+     * scope on its own. An internal recorder captures it here; the level
+     * join reads it to name what actually went wrong. Mirrors Parallel's
+     * `branchErrors`, epoch-guarded for the same reason.
+     */
+    private readonly nodeErrors;
+    /** Monotonic run token — see Parallel's `runEpoch`. */
+    private runEpoch;
+    constructor(opts: GraphOptions);
+    /** How the graph was levelized — level 0 first. Stable post-construction. */
+    getLevels(): readonly (readonly string[])[];
+    run(input: GraphInput, options?: RunOptions): Promise<GraphOutput | RunnerPauseOutcome>;
+    resume(checkpoint: FlowchartCheckpoint, input?: unknown, options?: RunOptions): Promise<GraphOutput | RunnerPauseOutcome>;
+    /**
+     * Give a RAW rejection the same node-naming shape the level join
+     * produces.
+     *
+     * A node in a SEQUENTIAL (single-node) level rejects the run with its
+     * own error — the level join never runs, so nothing has attributed it to
+     * a node yet. The error recorder did see it, so correlate (by identity
+     * first, then bare message) and rename. Anything that does not correlate
+     * — including the join's own already-attributed error — is rethrown
+     * untouched.
+     */
+    private rethrowWithNodeAttribution;
+    private createExecutor;
+    /**
+     * Capture the first error per node. The node id is the first segment of
+     * the engine-prefixed `stageId` (`orders/call-llm` → node `orders`) —
+     * the same correlation Parallel uses, and the only one that survives a
+     * node mounting subflows of its own.
+     */
+    private makeNodeErrorRecorder;
+    private finalizeResult;
+    private buildChart;
+    /**
+     * What one node receives. Roots get the graph's own input; a single
+     * parent is passed through; 2+ parents go through the node's `join`
+     * (which the build already guaranteed exists).
+     *
+     * `parent` here is the RAW parent state the engine hands an
+     * `inputMapper` — not a TypedScope — so structured upstream values read
+     * back intact.
+     */
+    private inputForNode;
+}
+/**
+ * Build a fixed DAG of runners. Independent nodes run concurrently; the
+ * result is every node's output, keyed by node id.
+ *
+ * The shape is checked at BUILD time — a cycle, an edge pointing at an
+ * unknown node, a duplicate id, or a 2+-parent node with no `join` throws
+ * here, naming the offender, rather than misbehaving mid-run.
+ *
+ * @example  a fan-out with a merge
+ * ```ts
+ * const pipeline = graph({
+ *   nodes: [
+ *     { id: 'plan', runner: planner },
+ *     { id: 'search', runner: searcher },
+ *     { id: 'recall', runner: memory },
+ *     { id: 'answer', runner: writer, join: (u) => ({ ...u }) },
+ *   ],
+ *   edges: [
+ *     { from: 'plan', to: 'search' },
+ *     { from: 'plan', to: 'recall' },
+ *     { from: 'search', to: 'answer' },
+ *     { from: 'recall', to: 'answer' },
+ *   ],
+ * });
+ *
+ * const out = await pipeline.run({ message: 'what changed last week?' });
+ * console.log(out.answer);
+ * ```
+ */
+export declare function graph(opts: GraphOptions): Graph;