agentfootprint 1.7.1 → 1.9.0

package/CLAUDE.md

@@ -5,7 +5,7 @@ This is the agentfootprint library — the explainable agent framework. Build AI
 ## Core Principles
 
 - **Adapter-swap testing.** Every concept uses `LLMProvider` — swap `mock([...])` for `createProvider(anthropic(...))` with zero code changes. $0 test runs, deterministic assertions.
-- **Concept ladder.** Five concepts, each a flowchart: LLMCall < RAG < Agent < FlowChart < Swarm. Each adds exactly one capability.
+- **Concept ladder.** Seven concepts, each a flowchart: LLMCall (leaf), RAG (augmented leaf), Agent (ReAct cycle), Swarm (LLM dispatch), FlowChart (sequence), Parallel (fan-out), Conditional (branch). Each wraps a footprintjs primitive. DAG-complete: leaf + sequence + fan-out + branch + cycle covers every shape.
 - **Built-in recorders.** Observe tokens, cost, tool usage, quality, guardrails — all via `.recorder()` on the builder. Never shape behavior, only observe.
 - **Collect during traversal.** Inherited from footprintjs — all data collection happens as side effects of the single DFS traversal pass. Never post-process.
 
@@ -14,7 +14,7 @@ This is the agentfootprint library — the explainable agent framework. Build AI
 ```
 src/
 ├── core/        → AgentLoopConfig, AgentRecorder interface, PromptProvider/ToolProvider interfaces
-├── concepts/    → 5 builders + runners (LLMCall, Agent, RAG, FlowChart, Swarm)
+├── concepts/    → 7 builders + runners (LLMCall, Agent, RAG, FlowChart, Swarm, Parallel, Conditional)
 ├── adapters/    → LLMProvider implementations (mock, anthropic, openai, bedrock, mcp, a2a)
 ├── models/      → ModelConfig factories (anthropic(), openai(), ollama(), bedrock())
 ├── providers/   → Strategy implementations (prompt/, messages/, tools/)

package/dist/concepts/Conditional.js

@@ -0,0 +1,260 @@
+"use strict";
+/**
+ * Conditional — branch to a runner based on predicates (DAG "if/else").
+ *
+ * Thin wrapper over footprintjs `addDeciderFunction` + `addFunctionBranch`.
+ * A conditional is a top-level routing decision between runners — distinct
+ * from `Agent.route()`, which branches INSIDE a ReAct loop. Use Conditional
+ * when the shape is "pick one runner and return its result" (triage, content
+ * classification, policy routing).
+ *
+ * Predicates are evaluated in the order `.when()` was called; first match
+ * wins. If every predicate misses, the `otherwise` branch runs. A predicate
+ * that throws is treated as a miss (fail-open) and the next branch is tried.
+ *
+ * @example
+ * ```ts
+ * import { Conditional, Agent, RAG } from 'agentfootprint';
+ *
+ * const triage = Conditional.create({ name: 'triage' })
+ *   .when((input) => input.includes('refund'), refundAgent)
+ *   .when((input) => input.length > 500, ragRunner)
+ *   .otherwise(generalAgent)
+ *   .build();
+ *
+ * const result = await triage.run('I want a refund please');
+ * // Narrative: "[triage] Chose refundAgent — predicate 0 matched"
+ * ```
+ *
+ * Conditional is a runner itself — plug it into `FlowChart`, `Parallel`,
+ * `Agent.route()`, or another `Conditional`. Composes like any other concept.
+ *
+ * ## Why this exists alongside footprintjs primitives
+ *
+ * footprintjs gives you `addDeciderFunction` + `addFunctionBranch` + `decide()`
+ * at the stage level. Conditional wraps those so you can compose **runners**
+ * (Agent, RAG, Swarm, user-built) instead of stage functions. Same underlying
+ * engine, same narrative, same evidence capture from `decide()`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConditionalRunner = exports.Conditional = void 0;
+const footprintjs_1 = require("footprintjs");
+const runnerAsStage_1 = require("../stages/runnerAsStage");
+const RecorderBridge_1 = require("../recorders/RecorderBridge");
+const specIcons_1 = require("./specIcons");
+const narrative_1 = require("../lib/narrative");
+/** Valid characters for a branch ID that feeds into runtimeStageId. */
+const VALID_BRANCH_ID = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+function isRunnerLike(x) {
+    return x !== null && typeof x === 'object' && typeof x.run === 'function';
+}
+/**
+ * Builder for the Conditional concept. Each `.when()` adds a predicate →
+ * runner branch. `.otherwise()` sets the default (required). `.build()`
+ * returns a `ConditionalRunner`.
+ */
+class Conditional {
+    conditionalName;
+    branches = [];
+    defaultRunner;
+    defaultName = 'Default';
+    recorders = [];
+    constructor(options) {
+        this.conditionalName = options.name ?? 'conditional';
+    }
+    static create(options = {}) {
+        return new Conditional(options);
+    }
+    /**
+     * Add a predicate → runner branch. Predicates are evaluated in the order
+     * they were added; first match wins. A throwing predicate is treated as a
+     * miss (fail-open) so a faulty branch never blocks a valid one.
+     *
+     * The `id` + optional `name` appear in narrative / decision evidence.
+     */
+    when(predicate, runner, options) {
+        if (typeof predicate !== 'function') {
+            throw new TypeError('Conditional.when: predicate must be a function (input, state) => boolean.');
+        }
+        if (!isRunnerLike(runner)) {
+            throw new TypeError('Conditional.when: runner must expose a run() method. Pass a built runner (Agent, LLMCall, etc.).');
+        }
+        const id = options?.id ?? `branch-${this.branches.length}`;
+        if (id === 'default') {
+            throw new Error("Conditional.when: branch ID 'default' is reserved for .otherwise(). Pass a different id.");
+        }
+        if (!VALID_BRANCH_ID.test(id)) {
+            throw new Error(`Conditional.when: branch ID '${id}' is invalid. Use alphanumerics, hyphens, or underscores — IDs feed into runtimeStageId and cannot contain '/' or whitespace.`);
+        }
+        if (this.branches.some((b) => b.id === id)) {
+            throw new Error(`Conditional: duplicate branch ID '${id}'.`);
+        }
+        this.branches.push({
+            id,
+            name: options?.name ?? id,
+            predicate,
+            runner,
+        });
+        return this;
+    }
+    /** Set the default runner — runs when every `.when()` predicate misses. */
+    otherwise(runner, options) {
+        if (!isRunnerLike(runner)) {
+            throw new TypeError('Conditional.otherwise: runner must expose a run() method. Pass a built runner (Agent, LLMCall, etc.).');
+        }
+        this.defaultRunner = runner;
+        if (options?.name)
+            this.defaultName = options.name;
+        return this;
+    }
+    recorder(rec) {
+        this.recorders.push(rec);
+        return this;
+    }
+    build() {
+        if (this.branches.length === 0) {
+            throw new Error('Conditional requires at least one .when() branch. Use FlowChart for unconditional single-runner pipelines.');
+        }
+        if (!this.defaultRunner) {
+            throw new Error('Conditional requires .otherwise(runner) — a default branch. Without it, an input matching nothing has no runner to route to.');
+        }
+        return new ConditionalRunner({
+            name: this.conditionalName,
+            branches: [...this.branches],
+            defaultRunner: this.defaultRunner,
+            defaultName: this.defaultName,
+            recorders: [...this.recorders],
+        });
+    }
+}
+exports.Conditional = Conditional;
+/**
+ * Runner produced by `Conditional.build()`. Exposes the same surface as other
+ * runners: `run`, `getNarrative`, `getNarrativeEntries`, `getSnapshot`,
+ * `getSpec`, `toFlowChart`. Composes into FlowChart / Parallel / Agent.route
+ * like any other runner.
+ */
+class ConditionalRunner {
+    opts;
+    lastExecutor;
+    lastSpec;
+    narrativeRenderer = (0, narrative_1.createAgentRenderer)();
+    constructor(opts) {
+        this.opts = opts;
+    }
+    async run(message, options) {
+        const startTime = Date.now();
+        const bridge = this.opts.recorders.length > 0 ? new RecorderBridge_1.RecorderBridge([...this.opts.recorders]) : null;
+        bridge?.dispatchTurnStart(message);
+        const chart = this.buildChart();
+        const executor = new footprintjs_1.FlowChartExecutor(chart, { enrichSnapshots: true });
+        executor.enableNarrative({ renderer: this.narrativeRenderer });
+        executor.attachRecorder(new footprintjs_1.MetricRecorder('metrics'));
+        try {
+            await executor.run({
+                input: { message },
+                signal: options?.signal,
+                timeoutMs: options?.timeoutMs,
+            });
+        }
+        catch (err) {
+            bridge?.dispatchError('llm', err);
+            throw err;
+        }
+        this.lastExecutor = executor;
+        const snapshot = executor.getSnapshot();
+        const state = snapshot?.sharedState ?? {};
+        const content = state.result ?? '';
+        bridge?.dispatchTurnComplete(content, 0);
+        return {
+            content,
+            agents: [],
+            totalLatencyMs: Date.now() - startTime,
+        };
+    }
+    buildChart() {
+        // Seed stage: store pipeline input so runner stages can read it.
+        const seedStage = (scope) => {
+            const args = scope.$getArgs();
+            scope.pipelineInput = args?.message ?? '';
+        };
+        // Decider: evaluate predicates in order. Use decide() so the matched
+        // branch id appears in the narrative as decision evidence.
+        //
+        // `decide()` returns a `DecisionResult<T>` — we extract `.value` to
+        // satisfy footprintjs's `addDeciderFunction` signature (string branch id).
+        // The full DecisionResult is still captured internally by the engine so
+        // it appears in the narrative / FlowRecorder `onDecision` evidence field.
+        const branches = this.opts.branches;
+        const deciderFn = (scope) => {
+            const input = scope.pipelineInput ?? '';
+            // Frozen state snapshot so a predicate can't accidentally mutate scope.
+            // Only exposes well-known fields — predicates must not depend on
+            // arbitrary scope keys (that's what stages are for).
+            const state = Object.freeze({
+                pipelineInput: input,
+            });
+            // decide() returns a DecisionResult whose `.branch` is the chosen id.
+            // footprintjs's addDeciderFunction accepts DecisionResult directly, but
+            // we extract `.branch` for a clearer string-typed return.
+            const result = (0, footprintjs_1.decide)(scope, branches.map((b) => ({
+                when: () => {
+                    // Fail-open on throw so a broken predicate can't block other
+                    // matching branches. Coerce non-boolean truthy returns to true.
+                    try {
+                        return Boolean(b.predicate(input, state));
+                    }
+                    catch {
+                        return false;
+                    }
+                },
+                then: b.id,
+                label: b.name,
+            })), 'default');
+            return result.branch;
+        };
+        let builder = (0, footprintjs_1.flowChart)('Seed', seedStage, 'seed');
+        let decider = builder.addDeciderFunction('Route', deciderFn, `${this.opts.name}-decide`, 'Pick the branch whose predicate matches first.');
+        // Mount every branch as `runnerAsStage` — it calls `runner.run(input)`
+        // and writes the output to `scope.result` on the parent. This keeps
+        // propagation simple: whichever branch fires, its content ends up on
+        // `result` for the caller to read. Subflow-mount variants (for UI
+        // drill-down) can be added behind a flag if/when needed.
+        for (const b of this.opts.branches) {
+            decider = decider.addFunctionBranch(b.id, b.name, (0, runnerAsStage_1.runnerAsStage)({ id: b.id, name: b.name, runner: b.runner }));
+        }
+        decider = decider.addFunctionBranch('default', this.opts.defaultName, (0, runnerAsStage_1.runnerAsStage)({
+            id: 'default',
+            name: this.opts.defaultName,
+            runner: this.opts.defaultRunner,
+        }));
+        builder = decider.setDefault('default').end();
+        this.lastSpec = (0, specIcons_1.annotateSpecIcons)(builder.toSpec());
+        return builder.build();
+    }
+    /** Get the flowchart spec (stage graph metadata). */
+    getSpec() {
+        if (!this.lastSpec) {
+            this.buildChart();
+        }
+        return this.lastSpec;
+    }
+    /** Expose the flowchart definition so this runner can be mounted as a subflow. */
+    toFlowChart() {
+        return this.buildChart();
+    }
+    /** Get the narrative from the last run. */
+    getNarrative() {
+        return this.lastExecutor?.getNarrative() ?? [];
+    }
+    /** Get structured narrative entries from the last run. */
+    getNarrativeEntries() {
+        return this.lastExecutor?.getNarrativeEntries() ?? [];
+    }
+    /** Get the full execution snapshot from the last run. */
+    getSnapshot() {
+        return this.lastExecutor?.getSnapshot();
+    }
+}
+exports.ConditionalRunner = ConditionalRunner;
+//# sourceMappingURL=Conditional.js.map

package/dist/concepts/Conditional.js.map

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

package/dist/concepts/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ParallelRunner = exports.Parallel = exports.SwarmRunner = exports.Swarm = exports.FlowChartRunner = exports.FlowChart = exports.RAGRunner = exports.RAG = exports.LLMCallRunner = exports.LLMCall = exports.AgentRunner = exports.Agent = void 0;
+exports.ConditionalRunner = exports.Conditional = exports.ParallelRunner = exports.Parallel = exports.SwarmRunner = exports.Swarm = exports.FlowChartRunner = exports.FlowChart = exports.RAGRunner = exports.RAG = exports.LLMCallRunner = exports.LLMCall = exports.AgentRunner = exports.Agent = void 0;
 // Agent rebuilt on library-of-libraries architecture (src/lib/)
 var concepts_1 = require("../lib/concepts");
 Object.defineProperty(exports, "Agent", { enumerable: true, get: function () { return concepts_1.Agent; } });
@@ -20,4 +20,7 @@ Object.defineProperty(exports, "SwarmRunner", { enumerable: true, get: function
 var Parallel_1 = require("./Parallel");
 Object.defineProperty(exports, "Parallel", { enumerable: true, get: function () { return Parallel_1.Parallel; } });
 Object.defineProperty(exports, "ParallelRunner", { enumerable: true, get: function () { return Parallel_1.ParallelRunner; } });
+var Conditional_1 = require("./Conditional");
+Object.defineProperty(exports, "Conditional", { enumerable: true, get: function () { return Conditional_1.Conditional; } });
+Object.defineProperty(exports, "ConditionalRunner", { enumerable: true, get: function () { return Conditional_1.ConditionalRunner; } });
 //# sourceMappingURL=index.js.map

package/dist/concepts/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/concepts/index.ts"],"names":[],"mappings":";;;AAAA,gEAAgE;AAChE,4CAAqD;AAA5C,iGAAA,KAAK,OAAA;AAAE,uGAAA,WAAW,OAAA;AAE3B,qCAAmD;AAA1C,kGAAA,OAAO,OAAA;AAAE,wGAAA,aAAa,OAAA;AAE/B,6BAAuC;AAA9B,0FAAA,GAAG,OAAA;AAAE,gGAAA,SAAS,OAAA;AAEvB,yCAAyD;AAAhD,sGAAA,SAAS,OAAA;AAAE,4GAAA,eAAe,OAAA;AACnC,iCAA6C;AAApC,8FAAA,KAAK,OAAA;AAAE,oGAAA,WAAW,OAAA;AAE3B,uCAAsD;AAA7C,oGAAA,QAAQ,OAAA;AAAE,0GAAA,cAAc,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/concepts/index.ts"],"names":[],"mappings":";;;AAAA,gEAAgE;AAChE,4CAAqD;AAA5C,iGAAA,KAAK,OAAA;AAAE,uGAAA,WAAW,OAAA;AAE3B,qCAAmD;AAA1C,kGAAA,OAAO,OAAA;AAAE,wGAAA,aAAa,OAAA;AAE/B,6BAAuC;AAA9B,0FAAA,GAAG,OAAA;AAAE,gGAAA,SAAS,OAAA;AAEvB,yCAAyD;AAAhD,sGAAA,SAAS,OAAA;AAAE,4GAAA,eAAe,OAAA;AACnC,iCAA6C;AAApC,8FAAA,KAAK,OAAA;AAAE,oGAAA,WAAW,OAAA;AAE3B,uCAAsD;AAA7C,oGAAA,QAAQ,OAAA;AAAE,0GAAA,cAAc,OAAA;AAEjC,6CAA+D;AAAtD,0GAAA,WAAW,OAAA;AAAE,gHAAA,iBAAiB,OAAA"}

package/dist/esm/concepts/Conditional.js

@@ -0,0 +1,255 @@
+/**
+ * Conditional — branch to a runner based on predicates (DAG "if/else").
+ *
+ * Thin wrapper over footprintjs `addDeciderFunction` + `addFunctionBranch`.
+ * A conditional is a top-level routing decision between runners — distinct
+ * from `Agent.route()`, which branches INSIDE a ReAct loop. Use Conditional
+ * when the shape is "pick one runner and return its result" (triage, content
+ * classification, policy routing).
+ *
+ * Predicates are evaluated in the order `.when()` was called; first match
+ * wins. If every predicate misses, the `otherwise` branch runs. A predicate
+ * that throws is treated as a miss (fail-open) and the next branch is tried.
+ *
+ * @example
+ * ```ts
+ * import { Conditional, Agent, RAG } from 'agentfootprint';
+ *
+ * const triage = Conditional.create({ name: 'triage' })
+ *   .when((input) => input.includes('refund'), refundAgent)
+ *   .when((input) => input.length > 500, ragRunner)
+ *   .otherwise(generalAgent)
+ *   .build();
+ *
+ * const result = await triage.run('I want a refund please');
+ * // Narrative: "[triage] Chose refundAgent — predicate 0 matched"
+ * ```
+ *
+ * Conditional is a runner itself — plug it into `FlowChart`, `Parallel`,
+ * `Agent.route()`, or another `Conditional`. Composes like any other concept.
+ *
+ * ## Why this exists alongside footprintjs primitives
+ *
+ * footprintjs gives you `addDeciderFunction` + `addFunctionBranch` + `decide()`
+ * at the stage level. Conditional wraps those so you can compose **runners**
+ * (Agent, RAG, Swarm, user-built) instead of stage functions. Same underlying
+ * engine, same narrative, same evidence capture from `decide()`.
+ */
+import { flowChart as buildFlowChart, FlowChartExecutor, MetricRecorder, decide, } from 'footprintjs';
+import { runnerAsStage } from '../stages/runnerAsStage';
+import { RecorderBridge } from '../recorders/RecorderBridge';
+import { annotateSpecIcons } from './specIcons';
+import { createAgentRenderer } from '../lib/narrative';
+/** Valid characters for a branch ID that feeds into runtimeStageId. */
+const VALID_BRANCH_ID = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+function isRunnerLike(x) {
+    return x !== null && typeof x === 'object' && typeof x.run === 'function';
+}
+/**
+ * Builder for the Conditional concept. Each `.when()` adds a predicate →
+ * runner branch. `.otherwise()` sets the default (required). `.build()`
+ * returns a `ConditionalRunner`.
+ */
+export class Conditional {
+    conditionalName;
+    branches = [];
+    defaultRunner;
+    defaultName = 'Default';
+    recorders = [];
+    constructor(options) {
+        this.conditionalName = options.name ?? 'conditional';
+    }
+    static create(options = {}) {
+        return new Conditional(options);
+    }
+    /**
+     * Add a predicate → runner branch. Predicates are evaluated in the order
+     * they were added; first match wins. A throwing predicate is treated as a
+     * miss (fail-open) so a faulty branch never blocks a valid one.
+     *
+     * The `id` + optional `name` appear in narrative / decision evidence.
+     */
+    when(predicate, runner, options) {
+        if (typeof predicate !== 'function') {
+            throw new TypeError('Conditional.when: predicate must be a function (input, state) => boolean.');
+        }
+        if (!isRunnerLike(runner)) {
+            throw new TypeError('Conditional.when: runner must expose a run() method. Pass a built runner (Agent, LLMCall, etc.).');
+        }
+        const id = options?.id ?? `branch-${this.branches.length}`;
+        if (id === 'default') {
+            throw new Error("Conditional.when: branch ID 'default' is reserved for .otherwise(). Pass a different id.");
+        }
+        if (!VALID_BRANCH_ID.test(id)) {
+            throw new Error(`Conditional.when: branch ID '${id}' is invalid. Use alphanumerics, hyphens, or underscores — IDs feed into runtimeStageId and cannot contain '/' or whitespace.`);
+        }
+        if (this.branches.some((b) => b.id === id)) {
+            throw new Error(`Conditional: duplicate branch ID '${id}'.`);
+        }
+        this.branches.push({
+            id,
+            name: options?.name ?? id,
+            predicate,
+            runner,
+        });
+        return this;
+    }
+    /** Set the default runner — runs when every `.when()` predicate misses. */
+    otherwise(runner, options) {
+        if (!isRunnerLike(runner)) {
+            throw new TypeError('Conditional.otherwise: runner must expose a run() method. Pass a built runner (Agent, LLMCall, etc.).');
+        }
+        this.defaultRunner = runner;
+        if (options?.name)
+            this.defaultName = options.name;
+        return this;
+    }
+    recorder(rec) {
+        this.recorders.push(rec);
+        return this;
+    }
+    build() {
+        if (this.branches.length === 0) {
+            throw new Error('Conditional requires at least one .when() branch. Use FlowChart for unconditional single-runner pipelines.');
+        }
+        if (!this.defaultRunner) {
+            throw new Error('Conditional requires .otherwise(runner) — a default branch. Without it, an input matching nothing has no runner to route to.');
+        }
+        return new ConditionalRunner({
+            name: this.conditionalName,
+            branches: [...this.branches],
+            defaultRunner: this.defaultRunner,
+            defaultName: this.defaultName,
+            recorders: [...this.recorders],
+        });
+    }
+}
+/**
+ * Runner produced by `Conditional.build()`. Exposes the same surface as other
+ * runners: `run`, `getNarrative`, `getNarrativeEntries`, `getSnapshot`,
+ * `getSpec`, `toFlowChart`. Composes into FlowChart / Parallel / Agent.route
+ * like any other runner.
+ */
+export class ConditionalRunner {
+    opts;
+    lastExecutor;
+    lastSpec;
+    narrativeRenderer = createAgentRenderer();
+    constructor(opts) {
+        this.opts = opts;
+    }
+    async run(message, options) {
+        const startTime = Date.now();
+        const bridge = this.opts.recorders.length > 0 ? new RecorderBridge([...this.opts.recorders]) : null;
+        bridge?.dispatchTurnStart(message);
+        const chart = this.buildChart();
+        const executor = new FlowChartExecutor(chart, { enrichSnapshots: true });
+        executor.enableNarrative({ renderer: this.narrativeRenderer });
+        executor.attachRecorder(new MetricRecorder('metrics'));
+        try {
+            await executor.run({
+                input: { message },
+                signal: options?.signal,
+                timeoutMs: options?.timeoutMs,
+            });
+        }
+        catch (err) {
+            bridge?.dispatchError('llm', err);
+            throw err;
+        }
+        this.lastExecutor = executor;
+        const snapshot = executor.getSnapshot();
+        const state = snapshot?.sharedState ?? {};
+        const content = state.result ?? '';
+        bridge?.dispatchTurnComplete(content, 0);
+        return {
+            content,
+            agents: [],
+            totalLatencyMs: Date.now() - startTime,
+        };
+    }
+    buildChart() {
+        // Seed stage: store pipeline input so runner stages can read it.
+        const seedStage = (scope) => {
+            const args = scope.$getArgs();
+            scope.pipelineInput = args?.message ?? '';
+        };
+        // Decider: evaluate predicates in order. Use decide() so the matched
+        // branch id appears in the narrative as decision evidence.
+        //
+        // `decide()` returns a `DecisionResult<T>` — we extract `.value` to
+        // satisfy footprintjs's `addDeciderFunction` signature (string branch id).
+        // The full DecisionResult is still captured internally by the engine so
+        // it appears in the narrative / FlowRecorder `onDecision` evidence field.
+        const branches = this.opts.branches;
+        const deciderFn = (scope) => {
+            const input = scope.pipelineInput ?? '';
+            // Frozen state snapshot so a predicate can't accidentally mutate scope.
+            // Only exposes well-known fields — predicates must not depend on
+            // arbitrary scope keys (that's what stages are for).
+            const state = Object.freeze({
+                pipelineInput: input,
+            });
+            // decide() returns a DecisionResult whose `.branch` is the chosen id.
+            // footprintjs's addDeciderFunction accepts DecisionResult directly, but
+            // we extract `.branch` for a clearer string-typed return.
+            const result = decide(scope, branches.map((b) => ({
+                when: () => {
+                    // Fail-open on throw so a broken predicate can't block other
+                    // matching branches. Coerce non-boolean truthy returns to true.
+                    try {
+                        return Boolean(b.predicate(input, state));
+                    }
+                    catch {
+                        return false;
+                    }
+                },
+                then: b.id,
+                label: b.name,
+            })), 'default');
+            return result.branch;
+        };
+        let builder = buildFlowChart('Seed', seedStage, 'seed');
+        let decider = builder.addDeciderFunction('Route', deciderFn, `${this.opts.name}-decide`, 'Pick the branch whose predicate matches first.');
+        // Mount every branch as `runnerAsStage` — it calls `runner.run(input)`
+        // and writes the output to `scope.result` on the parent. This keeps
+        // propagation simple: whichever branch fires, its content ends up on
+        // `result` for the caller to read. Subflow-mount variants (for UI
+        // drill-down) can be added behind a flag if/when needed.
+        for (const b of this.opts.branches) {
+            decider = decider.addFunctionBranch(b.id, b.name, runnerAsStage({ id: b.id, name: b.name, runner: b.runner }));
+        }
+        decider = decider.addFunctionBranch('default', this.opts.defaultName, runnerAsStage({
+            id: 'default',
+            name: this.opts.defaultName,
+            runner: this.opts.defaultRunner,
+        }));
+        builder = decider.setDefault('default').end();
+        this.lastSpec = annotateSpecIcons(builder.toSpec());
+        return builder.build();
+    }
+    /** Get the flowchart spec (stage graph metadata). */
+    getSpec() {
+        if (!this.lastSpec) {
+            this.buildChart();
+        }
+        return this.lastSpec;
+    }
+    /** Expose the flowchart definition so this runner can be mounted as a subflow. */
+    toFlowChart() {
+        return this.buildChart();
+    }
+    /** Get the narrative from the last run. */
+    getNarrative() {
+        return this.lastExecutor?.getNarrative() ?? [];
+    }
+    /** Get structured narrative entries from the last run. */
+    getNarrativeEntries() {
+        return this.lastExecutor?.getNarrativeEntries() ?? [];
+    }
+    /** Get the full execution snapshot from the last run. */
+    getSnapshot() {
+        return this.lastExecutor?.getSnapshot();
+    }
+}
+//# sourceMappingURL=Conditional.js.map

package/dist/esm/concepts/Conditional.js.map

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

package/dist/esm/concepts/index.js

@@ -5,4 +5,5 @@ export { RAG, RAGRunner } from './RAG';
 export { FlowChart, FlowChartRunner } from './FlowChart';
 export { Swarm, SwarmRunner } from './Swarm';
 export { Parallel, ParallelRunner } from './Parallel';
+export { Conditional, ConditionalRunner } from './Conditional';
 //# sourceMappingURL=index.js.map

package/dist/esm/concepts/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/concepts/index.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAErD,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAEnD,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE7C,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/concepts/index.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAErD,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAEnD,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE7C,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEtD,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC"}

package/dist/esm/index.js

@@ -12,7 +12,7 @@
  *   agentfootprint/stream        → Real-time lifecycle events
  */
 // ── Concepts (Builders + Runners) ───────────────────────────
-export { Agent, AgentRunner, LLMCall, LLMCallRunner, RAG, RAGRunner, FlowChart, FlowChartRunner, Swarm, SwarmRunner, Parallel, ParallelRunner, } from './concepts';
+export { Agent, AgentRunner, LLMCall, LLMCallRunner, RAG, RAGRunner, FlowChart, FlowChartRunner, Swarm, SwarmRunner, Parallel, ParallelRunner, Conditional, ConditionalRunner, } from './concepts';
 // ── Tools ───────────────────────────────────────────────────
 export { defineTool, askHuman, ToolRegistry } from './tools';
 // ── Providers (core — you can't build an agent without these) ─

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,+DAA+D;AAC/D,OAAO,EACL,KAAK,EACL,WAAW,EACX,OAAO,EACP,aAAa,EACb,GAAG,EACH,SAAS,EACT,SAAS,EACT,eAAe,EACf,KAAK,EACL,WAAW,EACX,QAAQ,EACR,cAAc,GACf,MAAM,YAAY,CAAC;AAGpB,+DAA+D;AAC/D,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE7D,iEAAiE;AACjE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC7F,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC7E,OAAO,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAC3E,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAuBlF,+DAA+D;AAC/D,OAAO,EACL,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,SAAS,EACT,UAAU,EACV,WAAW,EACX,QAAQ,GACT,MAAM,SAAS,CAAC;AAEjB,+DAA+D;AAC/D,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AA0BnC,8DAA8D;AAC9D,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAGvC,uEAAuE;AACvE,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAGnF,+DAA+D;AAC/D,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,+DAA+D;AAC/D,OAAO,EACL,KAAK,EACL,WAAW,EACX,OAAO,EACP,aAAa,EACb,GAAG,EACH,SAAS,EACT,SAAS,EACT,eAAe,EACf,KAAK,EACL,WAAW,EACX,QAAQ,EACR,cAAc,EACd,WAAW,EACX,iBAAiB,GAClB,MAAM,YAAY,CAAC;AAQpB,+DAA+D;AAC/D,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE7D,iEAAiE;AACjE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC7F,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC7E,OAAO,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAC3E,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAuBlF,+DAA+D;AAC/D,OAAO,EACL,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,SAAS,EACT,UAAU,EACV,WAAW,EACX,QAAQ,GACT,MAAM,SAAS,CAAC;AAEjB,+DAA+D;AAC/D,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AA0BnC,8DAA8D;AAC9D,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAGvC,uEAAuE;AACvE,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAGnF,+DAA+D;AAC/D,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/esm/patterns/index.js

@@ -0,0 +1,18 @@
+/**
+ * agentfootprint/patterns — canonical agent composition patterns.
+ *
+ * Each pattern is a thin factory over the existing concepts (`FlowChart`,
+ * `Parallel`, `Conditional`, `Agent`, `LLMCall`, `RAG`, `Swarm`). No new
+ * primitives. The source of each file shows the composition — read it to
+ * learn how to build your own.
+ *
+ * @example
+ * ```ts
+ * import { treeOfThoughts, reflexion, planExecute, mapReduce } from 'agentfootprint/patterns';
+ * ```
+ */
+export { planExecute } from './planExecute';
+export { mapReduce } from './mapReduce';
+export { treeOfThoughts } from './treeOfThoughts';
+export { reflexion } from './reflexion';
+//# sourceMappingURL=index.js.map

package/dist/esm/patterns/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/patterns/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAG5C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGxC,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAGlD,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC"}