agentfootprint 7.9.0 → 7.11.0

package/dist/core-flow/Workflow.js

@@ -0,0 +1,210 @@
+"use strict";
+/**
+ * workflow() — sequential steps whose hand-offs are checked by the compiler.
+ *
+ * WHY this exists: `Sequence` is the workhorse for "A, then B, then C",
+ * and every step it accepts has the same shape — takes `{ message }`,
+ * returns `string`. That is exactly right for chaining LLM calls, and
+ * exactly wrong the moment a step wants to hand the next one something
+ * structured: `Sequence` coerces any non-string step output to `''`
+ * (Sequence.ts, the step `outputMapper`), so a step that returns a parsed
+ * ticket silently hands the next step nothing at all. The mistake shows up
+ * as an empty prompt three steps later, at runtime, in production.
+ *
+ * `workflow()` closes that gap from both ends:
+ *
+ *   - **At compile time** — step N's OUTPUT type must be what step N+1
+ *     accepts. A `Runner<{ message: string }, Ticket>` followed by a
+ *     `Runner<{ orderId: string }, string>` does not compile. The chain is
+ *     proven before you run it, not debugged after.
+ *   - **At run time** — a step's value is handed to the next step
+ *     UNCHANGED. Objects stay objects. The one convenience is the house
+ *     convention: a step that returns a `string` feeds the next step's
+ *     `{ message }`, because that is what every LLM runner here wants.
+ *
+ * Pattern: Adapter over footprintjs's `addSubFlowChartNext`, with the
+ *          type-level handoff proof carried by overloads (1–8 steps).
+ * Role:    core-flow/ layer, alongside Sequence/Parallel/Conditional/Loop.
+ *          Pure control flow — no LLM dependency.
+ * Emits:   agentfootprint.composition.enter / exit, reported as kind
+ *          `'Sequence'` — a workflow IS a sequential composition, and
+ *          widening the public `CompositionKind` union would break
+ *          exhaustive switches in consumer code for no behavioural gain.
+ *
+ * THREE HONEST LIMITS, all inherited from the engine and all verified in
+ * `test/core-flow/scenario/Workflow.test.ts` — worth knowing before you
+ * put rich objects on the wire:
+ *
+ *   1. Only PLAIN DATA crosses a step boundary. A value with a prototype
+ *      (Date, Map, Set, a class instance) arrives as `{}`, and `undefined`
+ *      fields are dropped. Send strings, numbers, arrays and plain
+ *      objects; send a timestamp as an ISO string, not a `Date`.
+ *   2. A step must RETURN its output — the value handed forward is the
+ *      step chart's traversal result. A step whose last stage returns
+ *      nothing hands its whole scope forward instead.
+ *   3. The workflow's own input keys stay visible to LATER steps too
+ *      (footprintjs's `getArgs()` inherits the run's arguments). A key the
+ *      previous step actually produced always wins; a key it did NOT
+ *      produce can still be read from the original input rather than
+ *      coming back `undefined`.
+ *
+ * @example  a typed three-step chain
+ * ```ts
+ * interface Ticket { orderId: string; angry: boolean }
+ *
+ * const parse: Runner<{ message: string }, Ticket> = …;
+ * const lookup: Runner<Ticket, { refundUsd: number }> = …;
+ * const reply: Runner<{ refundUsd: number }, string> = …;
+ *
+ * const intake = workflow(parse, lookup, reply);
+ * const answer = await intake.run({ message: 'where is my refund?' });
+ * //    ^? string — the chain's last output type
+ *
+ * workflow(parse, reply); // ✗ compile error: Ticket is not { refundUsd }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.workflow = exports.Workflow = void 0;
+const footprintjs_1 = require("footprintjs");
+const RunnerBase_js_1 = require("../core/RunnerBase.js");
+const AgentRecorder_js_1 = require("../recorders/core/AgentRecorder.js");
+const CompositionRecorder_js_1 = require("../recorders/core/CompositionRecorder.js");
+const ContextRecorder_js_1 = require("../recorders/core/ContextRecorder.js");
+const StreamRecorder_js_1 = require("../recorders/core/StreamRecorder.js");
+const typedEmit_js_1 = require("../recorders/core/typedEmit.js");
+/**
+ * Hand the previous step's value to the next step as its input args.
+ *
+ * `string` → `{ message }` (the house convention). Plain object → itself.
+ * Anything else is a broken hand-off and says so loudly: the alternative
+ * is an empty input three steps downstream with nothing pointing back
+ * here.
+ */
+function toStepArgs(value, stepNumber) {
+    if (typeof value === 'string')
+        return { message: value };
+    if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+        return { ...value };
+    }
+    const got = value === null ? 'null' : Array.isArray(value) ? 'an array' : typeof value;
+    throw new Error(`workflow: step ${stepNumber - 1} handed forward ${got}, but step ${stepNumber} needs an ` +
+        'object (or a string, which arrives as { message }). Make each step return its output.');
+}
+/**
+ * A sequential composition that passes values through untouched. Build one
+ * with {@link workflow} — that factory carries the type-level chain proof.
+ */
+class Workflow extends RunnerBase_js_1.RunnerBase {
+    name;
+    id;
+    steps;
+    opts;
+    currentRunContext = {
+        runStartMs: 0,
+        runId: 'pending',
+        compositionPath: [],
+    };
+    constructor(steps, opts = {}) {
+        super();
+        if (steps.length === 0) {
+            throw new Error('Workflow: must have at least one step');
+        }
+        this.opts = opts;
+        this.name = opts.name ?? 'Workflow';
+        this.id = opts.id ?? 'workflow';
+        this.steps = steps;
+        // Eager chart construction — see `RunnerBase.initChart` JSDoc.
+        this.initChart(() => this.buildChart());
+    }
+    async run(input, options) {
+        const executor = this.createExecutor();
+        this.lastExecutor = executor;
+        const result = await executor.run({ input: { ...input }, ...(options ?? {}) });
+        return this.finalizeResult(executor, result);
+    }
+    async resume(checkpoint, input, options) {
+        this.emitPauseResume(checkpoint, input);
+        const executor = this.createExecutor();
+        this.lastExecutor = executor;
+        const result = await executor.resume(checkpoint, input, options);
+        return this.finalizeResult(executor, result);
+    }
+    createExecutor() {
+        this.currentRunContext = {
+            runStartMs: Date.now(),
+            runId: (0, RunnerBase_js_1.makeRunId)(),
+            compositionPath: [`Workflow:${this.id}`],
+        };
+        const executor = new footprintjs_1.FlowChartExecutor(this.getSpec());
+        const dispatcher = this.getDispatcher();
+        const getRunCtx = () => this.currentRunContext;
+        executor.attachCombinedRecorder(new ContextRecorder_js_1.ContextRecorder({ dispatcher, getRunContext: getRunCtx }));
+        executor.attachCombinedRecorder((0, StreamRecorder_js_1.streamRecorder)({ dispatcher, getRunContext: getRunCtx }));
+        executor.attachCombinedRecorder((0, AgentRecorder_js_1.agentRecorder)({ dispatcher, getRunContext: getRunCtx }));
+        executor.attachCombinedRecorder((0, CompositionRecorder_js_1.compositionRecorder)({ dispatcher, getRunContext: getRunCtx }));
+        for (const r of this.attachedRecorders)
+            executor.attachCombinedRecorder(r);
+        return executor;
+    }
+    finalizeResult(executor, result) {
+        const paused = this.detectPause(executor, result);
+        if (paused)
+            return paused;
+        if (result instanceof Error)
+            throw result;
+        return result;
+    }
+    buildChart() {
+        const steps = this.steps;
+        const compositionId = this.id;
+        const compositionName = this.name;
+        const seed = (scope) => {
+            // The workflow's own input IS step 1's input — no unwrapping, no
+            // re-wrapping; that is the whole point of the typed chain.
+            scope.current = scope.$getArgs();
+            (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.composition.enter', {
+                kind: 'Sequence',
+                id: compositionId,
+                name: compositionName,
+                childCount: steps.length,
+            });
+        };
+        // Root description prefix `Sequence:` is the taxonomy marker every
+        // consumer (Lens, FlowchartRecorder.mapTopologyToSteps) already reads.
+        let builder = (0, footprintjs_1.flowChart)('Seed', seed, 'seed', {
+            ...(this.opts.structureRecorders !== undefined && {
+                structureRecorders: [...this.opts.structureRecorders],
+            }),
+            description: `Sequence: ${steps.length}-step typed workflow`,
+        });
+        steps.forEach((step, index) => {
+            const stepNumber = index + 1;
+            builder = builder.addSubFlowChartNext(`step-${stepNumber}`, step.getSpec(), `Step ${stepNumber}`, {
+                inputMapper: (parent) => toStepArgs(parent.current, stepNumber),
+                // Untouched: whatever the step's chart returned is what the next
+                // step (or the caller) receives. No string coercion.
+                outputMapper: (sfOutput) => ({ current: sfOutput }),
+            });
+        });
+        builder = builder.addFunction('Finalize', (scope) => {
+            (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.composition.exit', {
+                kind: 'Sequence',
+                id: compositionId,
+                name: compositionName,
+                status: 'ok',
+                durationMs: Date.now() - this.currentRunContext.runStartMs,
+            });
+            return scope.current;
+        }, 'finalize', 'Workflow finalize');
+        return builder.build();
+    }
+}
+exports.Workflow = Workflow;
+function workflow(...steps) {
+    if (steps.length === 0) {
+        throw new Error('workflow(): needs at least one step');
+    }
+    return new Workflow(steps);
+}
+exports.workflow = workflow;
+//# sourceMappingURL=Workflow.js.map

package/dist/core-flow/Workflow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Workflow.js","sourceRoot":"","sources":["../../src/core-flow/Workflow.ts"],"names":[],"mappings":"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"}

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;