agentfootprint 1.23.0 → 2.1.0

package/dist/compositions/withCircuitBreaker.js

@@ -1,84 +0,0 @@
-"use strict";
-/**
- * withCircuitBreaker — wraps a RunnerLike with circuit breaker protection.
- *
- * Tracks consecutive failures. After `threshold` failures, the circuit
- * opens and all subsequent calls fail immediately (fast-fail) until
- * `resetAfterMs` has elapsed, at which point a single probe call is
- * allowed through (half-open state).
- *
- * States:
- *   CLOSED  → normal operation, counting failures
- *   OPEN    → fast-fail, no calls to runner
- *   HALF_OPEN → one probe call allowed; success → CLOSED, failure → OPEN
- *
- * Usage:
- *   const protected = withCircuitBreaker(fragileAgent, {
- *     threshold: 5,
- *     resetAfterMs: 30_000,
- *   });
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.withCircuitBreaker = exports.CircuitBreaker = void 0;
-class CircuitBreaker {
-    state = 'closed';
-    failures = 0;
-    lastFailureTime = 0;
-    threshold;
-    resetAfterMs;
-    constructor(options = {}) {
-        this.threshold = options.threshold ?? 5;
-        this.resetAfterMs = options.resetAfterMs ?? 30_000;
-    }
-    getState() {
-        if (this.state === 'open') {
-            if (Date.now() - this.lastFailureTime >= this.resetAfterMs) {
-                this.state = 'half_open';
-            }
-        }
-        return this.state;
-    }
-    recordSuccess() {
-        this.failures = 0;
-        this.state = 'closed';
-    }
-    recordFailure() {
-        this.failures++;
-        this.lastFailureTime = Date.now();
-        if (this.failures >= this.threshold) {
-            this.state = 'open';
-        }
-    }
-    reset() {
-        this.state = 'closed';
-        this.failures = 0;
-        this.lastFailureTime = 0;
-    }
-}
-exports.CircuitBreaker = CircuitBreaker;
-function withCircuitBreaker(runner, options = {}) {
-    const breaker = new CircuitBreaker(options);
-    const wrapped = {
-        breaker,
-        run: async (message, runOptions) => {
-            const state = breaker.getState();
-            if (state === 'open') {
-                throw new Error('Circuit breaker is open');
-            }
-            try {
-                const result = await runner.run(message, runOptions);
-                breaker.recordSuccess();
-                return result;
-            }
-            catch (err) {
-                breaker.recordFailure();
-                throw err;
-            }
-        },
-        getNarrativeEntries: runner.getNarrativeEntries?.bind(runner),
-        getSnapshot: runner.getSnapshot?.bind(runner),
-    };
-    return wrapped;
-}
-exports.withCircuitBreaker = withCircuitBreaker;
-//# sourceMappingURL=withCircuitBreaker.js.map

package/dist/compositions/withCircuitBreaker.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"withCircuitBreaker.js","sourceRoot":"","sources":["../../src/compositions/withCircuitBreaker.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;GAkBG;;;AAaH,MAAa,cAAc;IACjB,KAAK,GAAiB,QAAQ,CAAC;IAC/B,QAAQ,GAAG,CAAC,CAAC;IACb,eAAe,GAAG,CAAC,CAAC;IACX,SAAS,CAAS;IAClB,YAAY,CAAS;IAEtC,YAAY,UAAiC,EAAE;QAC7C,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,CAAC,CAAC;QACxC,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,MAAM,CAAC;IACrD,CAAC;IAED,QAAQ;QACN,IAAI,IAAI,CAAC,KAAK,KAAK,MAAM,EAAE,CAAC;YAC1B,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,eAAe,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;gBAC3D,IAAI,CAAC,KAAK,GAAG,WAAW,CAAC;YAC3B,CAAC;QACH,CAAC;QACD,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,aAAa;QACX,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC;QAClB,IAAI,CAAC,KAAK,GAAG,QAAQ,CAAC;IACxB,CAAC;IAED,aAAa;QACX,IAAI,CAAC,QAAQ,EAAE,CAAC;QAChB,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAClC,IAAI,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACpC,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC;QACtB,CAAC;IACH,CAAC;IAED,KAAK;QACH,IAAI,CAAC,KAAK,GAAG,QAAQ,CAAC;QACtB,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC;QAClB,IAAI,CAAC,eAAe,GAAG,CAAC,CAAC;IAC3B,CAAC;CACF;AAvCD,wCAuCC;AAED,SAAgB,kBAAkB,CAChC,MAAkB,EAClB,UAAiC,EAAE;IAEnC,MAAM,OAAO,GAAG,IAAI,cAAc,CAAC,OAAO,CAAC,CAAC;IAE5C,MAAM,OAAO,GAA6C;QACxD,OAAO;QACP,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE;YACjC,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;YAEjC,IAAI,KAAK,KAAK,MAAM,EAAE,CAAC;gBACrB,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;YAC7C,CAAC;YAED,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;gBACrD,OAAO,CAAC,aAAa,EAAE,CAAC;gBACxB,OAAO,MAAM,CAAC;YAChB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,OAAO,CAAC,aAAa,EAAE,CAAC;gBACxB,MAAM,GAAG,CAAC;YACZ,CAAC;QACH,CAAC;QACD,mBAAmB,EAAE,MAAM,CAAC,mBAAmB,EAAE,IAAI,CAAC,MAAM,CAAC;QAC7D,WAAW,EAAE,MAAM,CAAC,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC;KAC9C,CAAC;IAEF,OAAO,OAAO,CAAC;AACjB,CAAC;AA7BD,gDA6BC"}

package/dist/compositions/withFallback.js

@@ -1,33 +0,0 @@
-"use strict";
-/**
- * withFallback — wraps a primary RunnerLike with a fallback.
- *
- * If the primary runner throws, the fallback runner is called instead.
- * Useful for degraded-mode patterns (e.g., expensive LLM → cheap LLM).
- *
- * Usage:
- *   const safe = withFallback(gpt4Agent, gpt35Agent);
- *   const result = await safe.run('Hello');
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.withFallback = void 0;
-function withFallback(primary, fallback, options = {}) {
-    const { shouldFallback = () => true } = options;
-    return {
-        run: async (message, runOptions) => {
-            try {
-                return await primary.run(message, runOptions);
-            }
-            catch (err) {
-                if (!shouldFallback(err))
-                    throw err;
-                return fallback.run(message, runOptions);
-            }
-        },
-        // Narrative/snapshot from whichever runner succeeded
-        getNarrativeEntries: () => primary.getNarrativeEntries?.() ?? fallback.getNarrativeEntries?.() ?? [],
-        getSnapshot: () => primary.getSnapshot?.() ?? fallback.getSnapshot?.(),
-    };
-}
-exports.withFallback = withFallback;
-//# sourceMappingURL=withFallback.js.map

package/dist/compositions/withFallback.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"withFallback.js","sourceRoot":"","sources":["../../src/compositions/withFallback.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;AASH,SAAgB,YAAY,CAC1B,OAAmB,EACnB,QAAoB,EACpB,UAA2B,EAAE;IAE7B,MAAM,EAAE,cAAc,GAAG,GAAG,EAAE,CAAC,IAAI,EAAE,GAAG,OAAO,CAAC;IAEhD,OAAO;QACL,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE;YACjC,IAAI,CAAC;gBACH,OAAO,MAAM,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;YAChD,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC;oBAAE,MAAM,GAAG,CAAC;gBACpC,OAAO,QAAQ,CAAC,GAAG,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;YAC3C,CAAC;QACH,CAAC;QACD,qDAAqD;QACrD,mBAAmB,EAAE,GAAG,EAAE,CACxB,OAAO,CAAC,mBAAmB,EAAE,EAAE,IAAI,QAAQ,CAAC,mBAAmB,EAAE,EAAE,IAAI,EAAE;QAC3E,WAAW,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,IAAI,QAAQ,CAAC,WAAW,EAAE,EAAE;KACvE,CAAC;AACJ,CAAC;AArBD,oCAqBC"}

package/dist/compositions/withRetry.js

@@ -1,59 +0,0 @@
-"use strict";
-/**
- * withRetry — wraps a RunnerLike with retry logic.
- *
- * On failure, retries up to maxRetries times with configurable backoff.
- * Respects AbortSignal for cancellation during wait periods.
- *
- * Usage:
- *   const reliable = withRetry(unreliableAgent, {
- *     maxRetries: 3,
- *     backoffMs: 1000,
- *     backoffMultiplier: 2,
- *   });
- *   const result = await reliable.run('Hello');
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.withRetry = void 0;
-function withRetry(runner, options = {}) {
-    const { maxRetries = 3, backoffMs = 0, backoffMultiplier = 1, shouldRetry = () => true, } = options;
-    return {
-        run: async (message, runOptions) => {
-            let lastError;
-            let delay = backoffMs;
-            for (let attempt = 0; attempt <= maxRetries; attempt++) {
-                try {
-                    return await runner.run(message, runOptions);
-                }
-                catch (err) {
-                    lastError = err;
-                    if (attempt >= maxRetries || !shouldRetry(err)) {
-                        break;
-                    }
-                    if (delay > 0) {
-                        await sleep(delay, runOptions?.signal);
-                        delay *= backoffMultiplier;
-                    }
-                }
-            }
-            throw lastError;
-        },
-        getNarrativeEntries: runner.getNarrativeEntries?.bind(runner),
-        getSnapshot: runner.getSnapshot?.bind(runner),
-    };
-}
-exports.withRetry = withRetry;
-function sleep(ms, signal) {
-    return new Promise((resolve, reject) => {
-        if (signal?.aborted) {
-            reject(signal.reason ?? new Error('Aborted'));
-            return;
-        }
-        const timer = setTimeout(resolve, ms);
-        signal?.addEventListener('abort', () => {
-            clearTimeout(timer);
-            reject(signal.reason ?? new Error('Aborted'));
-        }, { once: true });
-    });
-}
-//# sourceMappingURL=withRetry.js.map

package/dist/compositions/withRetry.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"withRetry.js","sourceRoot":"","sources":["../../src/compositions/withRetry.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;;AAeH,SAAgB,SAAS,CAAC,MAAkB,EAAE,UAAwB,EAAE;IACtE,MAAM,EACJ,UAAU,GAAG,CAAC,EACd,SAAS,GAAG,CAAC,EACb,iBAAiB,GAAG,CAAC,EACrB,WAAW,GAAG,GAAG,EAAE,CAAC,IAAI,GACzB,GAAG,OAAO,CAAC;IAEZ,OAAO;QACL,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE;YACjC,IAAI,SAAkB,CAAC;YACvB,IAAI,KAAK,GAAG,SAAS,CAAC;YAEtB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,UAAU,EAAE,OAAO,EAAE,EAAE,CAAC;gBACvD,IAAI,CAAC;oBACH,OAAO,MAAM,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;gBAC/C,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,SAAS,GAAG,GAAG,CAAC;oBAEhB,IAAI,OAAO,IAAI,UAAU,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC;wBAC/C,MAAM;oBACR,CAAC;oBAED,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;wBACd,MAAM,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;wBACvC,KAAK,IAAI,iBAAiB,CAAC;oBAC7B,CAAC;gBACH,CAAC;YACH,CAAC;YAED,MAAM,SAAS,CAAC;QAClB,CAAC;QACD,mBAAmB,EAAE,MAAM,CAAC,mBAAmB,EAAE,IAAI,CAAC,MAAM,CAAC;QAC7D,WAAW,EAAE,MAAM,CAAC,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC;KAC9C,CAAC;AACJ,CAAC;AAnCD,8BAmCC;AAED,SAAS,KAAK,CAAC,EAAU,EAAE,MAAoB;IAC7C,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;YACpB,MAAM,CAAC,MAAM,CAAC,MAAM,IAAI,IAAI,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;YAC9C,OAAO;QACT,CAAC;QACD,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QACtC,MAAM,EAAE,gBAAgB,CACtB,OAAO,EACP,GAAG,EAAE;YACH,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,MAAM,CAAC,MAAM,CAAC,MAAM,IAAI,IAAI,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;QAChD,CAAC,EACD,EAAE,IAAI,EAAE,IAAI,EAAE,CACf,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/concepts/Conditional.js

@@ -1,306 +0,0 @@
-"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");
-const streaming_1 = require("../streaming");
-const forwardEmitRecorders_1 = require("../recorders/forwardEmitRecorders");
-const attachRecorderHelper_1 = require("../recorders/attachRecorderHelper");
-/** True iff the runner exposes `toFlowChart()` for subflow composition. */
-function hasFlowChart(runner) {
-    return typeof runner.toFlowChart === 'function';
-}
-/** 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;
-    }
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    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)();
-    /** Persistent observer list — see AgentRunner.dispatcher. */
-    dispatcher = new streaming_1.EventDispatcher();
-    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;
-        const dispatcher = this.dispatcher;
-        const perRun = options?.onEvent;
-        const onStreamEvent = dispatcher.size > 0 || perRun
-            ? (e) => {
-                dispatcher.dispatch(e);
-                if (perRun) {
-                    try {
-                        perRun(e);
-                    }
-                    catch {
-                        /* swallow */
-                    }
-                }
-            }
-            : undefined;
-        onStreamEvent?.({ type: 'turn_start', userMessage: message });
-        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'));
-        (0, forwardEmitRecorders_1.forwardEmitRecorders)(executor, this.opts.recorders);
-        if (onStreamEvent) {
-            executor.attachEmitRecorder((0, streaming_1.createStreamEventRecorder)(onStreamEvent));
-        }
-        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);
-        onStreamEvent?.({ type: 'turn_end', content, iterations: 1 });
-        return {
-            content,
-            agents: [],
-            totalLatencyMs: Date.now() - startTime,
-        };
-    }
-    /** Subscribe to the runner's live stream of events. See AgentRunner.observe(). */
-    observe(handler) {
-        return this.dispatcher.observe(handler);
-    }
-    /**
-     * Attach a recorder POST-BUILD. See AgentRunner.attachRecorder.
-     * Conditional composition is discovered at runtime via the executor's
-     * onDecision events, routed through the recorder's TopologyRecorder.
-     */
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    attachRecorder(recorder) {
-        return (0, attachRecorderHelper_1.attachRecorderToList)(this.opts.recorders, recorder);
-    }
-    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. Returns the full DecisionResult
-        // (NOT `.branch`) — DeciderHandler recognizes the DECISION_RESULT symbol
-        // brand and extracts evidence onto FlowRecorder.onDecision. Returning a
-        // bare string would silently drop that evidence.
-        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,
-            });
-            return (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');
-        };
-        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 each branch: if the runner exposes `toFlowChart()`, mount
-        // as a subflow branch so narrative / explainable-UI consumers get
-        // drill-down into the chosen runner. Otherwise fall back to
-        // `runnerAsStage`. Matches the pattern used by FlowChart.ts and
-        // buildSwarmRouting — no concept should silently lose drill-down.
-        const mountRunnerBranch = (id, name, runner) => {
-            if (hasFlowChart(runner)) {
-                decider = decider.addSubFlowChartBranch(id, runner.toFlowChart(), name, {
-                    // The runner's seed stage reads `scope.message` when invoked
-                    // in subflow mode — pipe the pipeline input through.
-                    inputMapper: (parent) => ({
-                        message: parent.pipelineInput ?? '',
-                    }),
-                    outputMapper: (sfOutput) => ({
-                        result: String(sfOutput.result ?? sfOutput.content ?? ''),
-                    }),
-                });
-            }
-            else {
-                decider = decider.addFunctionBranch(id, name, (0, runnerAsStage_1.runnerAsStage)({ id, name, runner }));
-            }
-        };
-        for (const b of this.opts.branches) {
-            mountRunnerBranch(b.id, b.name, b.runner);
-        }
-        mountRunnerBranch('default', this.opts.defaultName, 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 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

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