agentfootprint 1.22.0 → 2.0.1

package/dist/types/core-flow/Conditional.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Conditional — routing composition: evaluates branches in order, runs the first match.
+ *
+ * Pattern: Builder (GoF) + Adapter over footprintjs's `addDeciderFunction`.
+ * Role:    core-flow/ layer. Picks exactly ONE branch based on a predicate
+ *          (sync function of input) OR an LLM decision. Chosen branch
+ *          receives `{ message }` and returns a string.
+ * Emits:   agentfootprint.composition.enter / exit +
+ *          composition.route_decided (via compositionRecorder).
+ *
+ * v1 of this primitive supports `.when(id, predicate, runner)` + `.otherwise(id, runner)`.
+ * LLM-gated routing (`.whenLLM(id, prompt, runner)`) lands in Phase 5.
+ */
+import { type FlowChart, type FlowchartCheckpoint, type RunOptions } from 'footprintjs';
+import type { RunnerPauseOutcome } from '../core/pause.js';
+import type { Runner } from '../core/runner.js';
+import { RunnerBase } from '../core/RunnerBase.js';
+export interface ConditionalOptions {
+    readonly name?: string;
+    readonly id?: string;
+}
+export interface ConditionalInput {
+    readonly message: string;
+}
+export type ConditionalOutput = string;
+type BranchChild = Runner<{
+    message: string;
+}, string>;
+export type Predicate = (input: ConditionalInput) => boolean;
+interface BranchEntry {
+    readonly id: string;
+    readonly name: string;
+    readonly runner: BranchChild;
+    /** Undefined for the `otherwise` fallback. */
+    readonly predicate?: Predicate;
+}
+export declare class Conditional extends RunnerBase<ConditionalInput, ConditionalOutput> {
+    readonly name: string;
+    readonly id: string;
+    private readonly branches;
+    private readonly fallbackId;
+    private currentRunContext;
+    constructor(opts: ConditionalOptions, branches: readonly BranchEntry[], fallbackId: string);
+    static create(opts?: ConditionalOptions): ConditionalBuilder;
+    toFlowChart(): FlowChart;
+    run(input: ConditionalInput, options?: RunOptions): Promise<ConditionalOutput | RunnerPauseOutcome>;
+    resume(checkpoint: FlowchartCheckpoint, input?: unknown, options?: RunOptions): Promise<ConditionalOutput | RunnerPauseOutcome>;
+    private createExecutor;
+    private finalizeResult;
+    private buildChart;
+}
+/**
+ * Fluent builder. Branches evaluate in registration order; first matching
+ * predicate wins. `.otherwise()` is the mandatory fallback.
+ */
+export declare class ConditionalBuilder {
+    private readonly opts;
+    private readonly branches;
+    private fallbackRegistered;
+    private fallbackId;
+    private readonly seenIds;
+    constructor(opts: ConditionalOptions);
+    /**
+     * Register a predicate-gated branch. `predicate` is a pure sync function
+     * of the Conditional's input; if it returns true, the corresponding
+     * runner executes. Branches evaluate in registration order.
+     */
+    when(id: string, predicate: Predicate, runner: BranchChild, name?: string): this;
+    /**
+     * Register the fallback branch. Exactly ONE must be registered before build().
+     */
+    otherwise(id: string, runner: BranchChild, name?: string): this;
+    build(): Conditional;
+}
+export {};
+//# sourceMappingURL=Conditional.d.ts.map

package/dist/types/core-flow/Conditional.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Conditional.d.ts","sourceRoot":"","sources":["../../../src/core-flow/Conditional.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAGL,KAAK,SAAS,EACd,KAAK,mBAAmB,EACxB,KAAK,UAAU,EAEhB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAa,MAAM,uBAAuB,CAAC;AAQ9D,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC;AAEvC,KAAK,WAAW,GAAG,MAAM,CAAC;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,EAAE,MAAM,CAAC,CAAC;AAEvD,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,gBAAgB,KAAK,OAAO,CAAC;AAE7D,UAAU,WAAW;IACnB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;CAChC;AAMD,qBAAa,WAAY,SAAQ,UAAU,CAAC,gBAAgB,EAAE,iBAAiB,CAAC;IAC9E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyB;IAClD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC,OAAO,CAAC,iBAAiB,CAIvB;gBAEU,IAAI,EAAE,kBAAkB,EAAE,QAAQ,EAAE,SAAS,WAAW,EAAE,EAAE,UAAU,EAAE,MAAM;IAW1F,MAAM,CAAC,MAAM,CAAC,IAAI,GAAE,kBAAuB,GAAG,kBAAkB;IAIhE,WAAW,IAAI,SAAS;IAIlB,GAAG,CACP,KAAK,EAAE,gBAAgB,EACvB,OAAO,CAAC,EAAE,UAAU,GACnB,OAAO,CAAC,iBAAiB,GAAG,kBAAkB,CAAC;IAS5C,MAAM,CACV,UAAU,EAAE,mBAAmB,EAC/B,KAAK,CAAC,EAAE,OAAO,EACf,OAAO,CAAC,EAAE,UAAU,GACnB,OAAO,CAAC,iBAAiB,GAAG,kBAAkB,CAAC;IAOlD,OAAO,CAAC,cAAc;IAqBtB,OAAO,CAAC,cAAc;IAWtB,OAAO,CAAC,UAAU;CAoHnB;AAED;;;GAGG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAqB;IAC1C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAC9C,OAAO,CAAC,kBAAkB,CAAS;IACnC,OAAO,CAAC,UAAU,CAAM;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;gBAEjC,IAAI,EAAE,kBAAkB;IAIpC;;;;OAIG;IACH,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI;IAShF;;OAEG;IACH,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI;IAc/D,KAAK,IAAI,WAAW;CAQrB"}

package/dist/types/core-flow/Loop.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Loop — iteration composition: runs a body runner repeatedly until exit.
+ *
+ * Pattern: Builder (GoF) + Adapter over footprintjs's `loopTo` + `$break`.
+ * Role:    core-flow/ layer. Enables Reflection, Self-Refine, Debate,
+ *          Reflexion, Constitutional AI, and any pattern needing
+ *          iterative refinement of a composition output.
+ * Emits:   agentfootprint.composition.enter / exit +
+ *          composition.iteration_start / iteration_exit
+ *          (via compositionRecorder).
+ *
+ * Budget guard is MANDATORY. You must set at least one of:
+ *   - maxIterations (default 10 if only .body() is set)
+ *   - maxWallclockMs
+ * Hard ceiling of 500 iterations prevents runaway loops even if a guard
+ * misfires; exceeding it throws.
+ */
+import { type FlowChart, type FlowchartCheckpoint, type RunOptions } from 'footprintjs';
+import type { RunnerPauseOutcome } from '../core/pause.js';
+import type { Runner } from '../core/runner.js';
+import { RunnerBase } from '../core/RunnerBase.js';
+export interface LoopOptions {
+    readonly name?: string;
+    readonly id?: string;
+}
+export interface LoopInput {
+    readonly message: string;
+}
+export type LoopOutput = string;
+type BodyChild = Runner<{
+    message: string;
+}, string>;
+/** Predicate evaluated AFTER each body iteration. Return true to exit the loop. */
+export type UntilGuard = (ctx: {
+    readonly iteration: number;
+    readonly latestOutput: string;
+    readonly startMs: number;
+}) => boolean;
+export declare class Loop extends RunnerBase<LoopInput, LoopOutput> {
+    readonly name: string;
+    readonly id: string;
+    private readonly body;
+    private readonly maxIterations;
+    private readonly maxWallclockMs;
+    private readonly until;
+    private currentRunContext;
+    constructor(opts: LoopOptions, body: BodyChild, config: {
+        maxIterations: number;
+        maxWallclockMs?: number;
+        until?: UntilGuard;
+    });
+    static create(opts?: LoopOptions): LoopBuilder;
+    toFlowChart(): FlowChart;
+    run(input: LoopInput, options?: RunOptions): Promise<LoopOutput | RunnerPauseOutcome>;
+    resume(checkpoint: FlowchartCheckpoint, input?: unknown, options?: RunOptions): Promise<LoopOutput | RunnerPauseOutcome>;
+    private createExecutor;
+    private finalizeResult;
+    private buildChart;
+}
+/**
+ * Fluent builder. Reads as natural English:
+ *   Loop.create().repeat(runner).times(10).forAtMost(30_000).until(fn).build()
+ *   →  "Loop: repeat runner, up to 10 times, for at most 30 seconds, until fn."
+ *
+ * Enforces a body runner is supplied before .build(). Default budget is
+ * 10 iterations (hard ceiling 500). Any of .times / .forAtMost / .until
+ * can fire to exit the loop.
+ */
+export declare class LoopBuilder {
+    private readonly opts;
+    private _body;
+    private _maxIterations;
+    private _maxWallclockMs;
+    private _until;
+    constructor(opts: LoopOptions);
+    /**
+     * The runner that executes each iteration. Required.
+     * Each iteration's output string becomes the next iteration's input `{ message }`.
+     */
+    repeat(runner: BodyChild): this;
+    /**
+     * Maximum iteration count. Default 10 if only `.repeat()` is called.
+     * Hard ceiling 500 — larger values are clamped.
+     */
+    times(n: number): this;
+    /**
+     * Wall-clock time budget in milliseconds. The loop exits at the next
+     * guard check after this elapses.
+     */
+    forAtMost(ms: number): this;
+    /**
+     * Exit predicate evaluated after each iteration. Return `true` to exit.
+     * Receives `{ iteration, latestOutput, startMs }`.
+     */
+    until(guard: UntilGuard): this;
+    build(): Loop;
+}
+export {};
+//# sourceMappingURL=Loop.d.ts.map

package/dist/types/core-flow/Loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Loop.d.ts","sourceRoot":"","sources":["../../../src/core-flow/Loop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAGL,KAAK,SAAS,EACd,KAAK,mBAAmB,EACxB,KAAK,UAAU,EAEhB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAa,MAAM,uBAAuB,CAAC;AAQ9D,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC;AAEhC,KAAK,SAAS,GAAG,MAAM,CAAC;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,EAAE,MAAM,CAAC,CAAC;AAErD,mFAAmF;AACnF,MAAM,MAAM,UAAU,GAAG,CAAC,GAAG,EAAE;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B,KAAK,OAAO,CAAC;AAQd,qBAAa,IAAK,SAAQ,UAAU,CAAC,SAAS,EAAE,UAAU,CAAC;IACzD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAY;IACjC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqB;IACpD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAyB;IAE/C,OAAO,CAAC,iBAAiB,CAIvB;gBAGA,IAAI,EAAE,WAAW,EACjB,IAAI,EAAE,SAAS,EACf,MAAM,EAAE;QACN,aAAa,EAAE,MAAM,CAAC;QACtB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,KAAK,CAAC,EAAE,UAAU,CAAC;KACpB;IAWH,MAAM,CAAC,MAAM,CAAC,IAAI,GAAE,WAAgB,GAAG,WAAW;IAIlD,WAAW,IAAI,SAAS;IAIlB,GAAG,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,GAAG,kBAAkB,CAAC;IASrF,MAAM,CACV,UAAU,EAAE,mBAAmB,EAC/B,KAAK,CAAC,EAAE,OAAO,EACf,OAAO,CAAC,EAAE,UAAU,GACnB,OAAO,CAAC,UAAU,GAAG,kBAAkB,CAAC;IAO3C,OAAO,CAAC,cAAc;IAqBtB,OAAO,CAAC,cAAc;IAWtB,OAAO,CAAC,UAAU;CAgGnB;AAED;;;;;;;;GAQG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAc;IACnC,OAAO,CAAC,KAAK,CAAwB;IACrC,OAAO,CAAC,cAAc,CAAqB;IAC3C,OAAO,CAAC,eAAe,CAAqB;IAC5C,OAAO,CAAC,MAAM,CAAyB;gBAE3B,IAAI,EAAE,WAAW;IAI7B;;;OAGG;IACH,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI;IAQ/B;;;OAGG;IACH,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IAKtB;;;OAGG;IACH,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAK3B;;;OAGG;IACH,KAAK,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAK9B,KAAK,IAAI,IAAI;CAWd"}

package/dist/types/core-flow/Parallel.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Parallel — fan-out composition: N branches run concurrently, then merge.
+ *
+ * Pattern: Builder (GoF) + Adapter over footprintjs's `addSubFlowChart`
+ *          (fork children).
+ * Role:    core-flow/ layer. All branches receive the same input
+ *          `{ message }`. Each returns a string. A merge step combines
+ *          them: either a pure function OR an LLM.
+ * Emits:   agentfootprint.composition.enter / exit +
+ *          composition.fork_start / branch_complete / merge_end
+ *          (via compositionRecorder).
+ */
+import { type FlowChart, type FlowchartCheckpoint, type RunOptions } from 'footprintjs';
+import type { RunnerPauseOutcome } from '../core/pause.js';
+import type { LLMProvider } from '../adapters/types.js';
+import type { Runner } from '../core/runner.js';
+import { RunnerBase } from '../core/RunnerBase.js';
+export interface ParallelOptions {
+    readonly name?: string;
+    readonly id?: string;
+}
+export interface ParallelInput {
+    readonly message: string;
+}
+export type ParallelOutput = string;
+type BranchChild = Runner<{
+    message: string;
+}, string>;
+export type MergeFn = (branchResults: Readonly<Record<string, string>>) => string;
+/**
+ * Outcome per branch in tolerant mode. One of:
+ *   - `{ ok: true, value: string }` — branch succeeded; `value` is the returned string
+ *   - `{ ok: false, error: string }` — branch threw; `error` is the error message
+ *
+ * Consumers in tolerant mode receive `Record<branchId, BranchOutcome>` and
+ * decide how to handle partial failure (e.g., fall back to a default,
+ * log, retry, or surface a user-facing message).
+ */
+export type BranchOutcome = {
+    readonly ok: true;
+    readonly value: string;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+export type MergeOutcomesFn = (outcomes: Readonly<Record<string, BranchOutcome>>) => string;
+export interface MergeWithLLMOptions {
+    readonly provider: LLMProvider;
+    readonly model: string;
+    /** Prompt prepended to the branch results when feeding the merge LLM. */
+    readonly prompt: string;
+    readonly temperature?: number;
+    readonly maxTokens?: number;
+}
+interface BranchEntry {
+    readonly id: string;
+    readonly name: string;
+    readonly runner: BranchChild;
+}
+type MergeStrategy = {
+    readonly kind: 'fn';
+    readonly fn: MergeFn;
+} | {
+    readonly kind: 'llm';
+    readonly opts: MergeWithLLMOptions;
+} | {
+    readonly kind: 'outcomes-fn';
+    readonly fn: MergeOutcomesFn;
+};
+export declare class Parallel extends RunnerBase<ParallelInput, ParallelOutput> {
+    readonly name: string;
+    readonly id: string;
+    private readonly branches;
+    private readonly merge;
+    private currentRunContext;
+    constructor(opts: ParallelOptions, branches: readonly BranchEntry[], merge: MergeStrategy);
+    static create(opts?: ParallelOptions): ParallelBuilder;
+    toFlowChart(): FlowChart;
+    run(input: ParallelInput, options?: RunOptions): Promise<ParallelOutput | RunnerPauseOutcome>;
+    resume(checkpoint: FlowchartCheckpoint, input?: unknown, options?: RunOptions): Promise<ParallelOutput | RunnerPauseOutcome>;
+    private createExecutor;
+    private finalizeResult;
+    private buildChart;
+}
+/** Fluent builder. Requires at least 2 branches + one merge strategy. */
+export declare class ParallelBuilder {
+    private readonly opts;
+    private readonly branches;
+    private merge;
+    private readonly seenIds;
+    constructor(opts: ParallelOptions);
+    /** Add a branch. All branches run concurrently with the same input. */
+    branch(id: string, runner: BranchChild, name?: string): this;
+    /**
+     * Merge branch results via a pure function.
+     * `fn` receives `{ [branchId]: string }` and returns the merged string.
+     */
+    mergeWithFn(fn: MergeFn): this;
+    /** Merge branch results by feeding them to an LLM for synthesis. */
+    mergeWithLLM(opts: MergeWithLLMOptions): this;
+    /**
+     * Tolerant merge — receives `{ [branchId]: BranchOutcome }` including
+     * both successes (`{ ok: true, value }`) and failures (`{ ok: false, error }`).
+     * Parallel does NOT throw on partial failure when this merge variant is
+     * used; the consumer's `fn` decides how to handle it (fall back, surface
+     * a warning, retry at a higher level, etc.).
+     *
+     * Use the default `mergeWithFn` / `mergeWithLLM` variants when you want
+     * a single failing branch to abort the whole Parallel loudly.
+     */
+    mergeOutcomesWithFn(fn: MergeOutcomesFn): this;
+    build(): Parallel;
+}
+export {};
+//# sourceMappingURL=Parallel.d.ts.map

package/dist/types/core-flow/Parallel.d.ts.map

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

package/dist/types/core-flow/Sequence.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Sequence — sequential composition of runners (steps chained one after another).
+ *
+ * Pattern: Builder (GoF) + Adapter over footprintjs's `addSubFlowChartNext`.
+ * Role:    core-flow/ layer — pure control flow, no LLM deps.
+ *          Each step's output becomes the next step's input; default
+ *          mapping is string chaining (step N's return → step N+1's
+ *          `{ message }`). Custom mapping via `.mapBetween(fn)` between
+ *          any two steps.
+ * Emits:   agentfootprint.composition.enter / exit (via compositionRecorder).
+ */
+import { type FlowChart, type FlowchartCheckpoint, type RunOptions } from 'footprintjs';
+import type { RunnerPauseOutcome } from '../core/pause.js';
+import type { Runner } from '../core/runner.js';
+import { RunnerBase } from '../core/RunnerBase.js';
+export interface SequenceOptions {
+    /** Human-friendly name for events + topology. Default: 'Sequence'. */
+    readonly name?: string;
+    /** Stable id used for topology + events. Default: 'sequence'. */
+    readonly id?: string;
+}
+export interface SequenceInput {
+    readonly message: string;
+}
+export type SequenceOutput = string;
+type StepChild = Runner<{
+    message: string;
+}, string>;
+interface StepEntry {
+    readonly id: string;
+    readonly runner: StepChild;
+    /** Mapper applied BEFORE this step's run(). */
+    readonly mapFromPrev: (prev: string) => {
+        message: string;
+    };
+}
+export declare class Sequence extends RunnerBase<SequenceInput, SequenceOutput> {
+    readonly name: string;
+    readonly id: string;
+    private readonly steps;
+    private currentRunContext;
+    constructor(opts: SequenceOptions, steps: readonly StepEntry[]);
+    static create(opts?: SequenceOptions): SequenceBuilder;
+    toFlowChart(): FlowChart;
+    run(input: SequenceInput, options?: RunOptions): Promise<SequenceOutput | RunnerPauseOutcome>;
+    resume(checkpoint: FlowchartCheckpoint, input?: unknown, options?: RunOptions): Promise<SequenceOutput | RunnerPauseOutcome>;
+    private createExecutor;
+    private finalizeResult;
+    private buildChart;
+}
+/**
+ * Fluent builder. Reads as natural English:
+ *   Sequence.create().step('a', A).pipeVia(fn).step('b', B).build()
+ *   →  "Sequence: step A, pipe via fn, step B."
+ *
+ * `step(id, runner)` adds a sequential step. `pipeVia(fn)` customises
+ * the transformation of the previous step's output before it feeds the
+ * next step (otherwise the default string-chain mapper is used).
+ */
+export declare class SequenceBuilder {
+    private readonly opts;
+    private readonly steps;
+    /** Pending pipeVia transformer for the NEXT step (consumed on .step()). */
+    private pendingPipe?;
+    private readonly seenIds;
+    constructor(opts: SequenceOptions);
+    /**
+     * Add a step. Runner must accept `{ message: string }` and return `string`.
+     * First step receives the Sequence input; subsequent steps receive the
+     * previous step's output (via the default string-chain mapper, or via
+     * the transformer set by a preceding `.pipeVia(fn)` call).
+     */
+    step(id: string, runner: StepChild): this;
+    /**
+     * Transform the previous step's string output before it reaches the
+     * next step. Consumed once by the next `.step()` call. Default
+     * mapping is `(prev) => ({ message: prev })`.
+     *
+     * Reads as English: `.step('a', A).pipeVia(fn).step('b', B)`
+     * →  "step A, pipe via fn, step B"
+     */
+    pipeVia(fn: (prev: string) => {
+        message: string;
+    }): this;
+    build(): Sequence;
+}
+export {};
+//# sourceMappingURL=Sequence.d.ts.map

package/dist/types/core-flow/Sequence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Sequence.d.ts","sourceRoot":"","sources":["../../../src/core-flow/Sequence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAGL,KAAK,SAAS,EACd,KAAK,mBAAmB,EACxB,KAAK,UAAU,EAEhB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAa,MAAM,uBAAuB,CAAC;AAQ9D,MAAM,WAAW,eAAe;IAC9B,sEAAsE;IACtE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC;AAKpC,KAAK,SAAS,GAAG,MAAM,CAAC;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,EAAE,MAAM,CAAC,CAAC;AAErD,UAAU,SAAS;IACjB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,+CAA+C;IAC/C,QAAQ,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7D;AAMD,qBAAa,QAAS,SAAQ,UAAU,CAAC,aAAa,EAAE,cAAc,CAAC;IACrE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAuB;IAE7C,OAAO,CAAC,iBAAiB,CAIvB;gBAEU,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,SAAS,SAAS,EAAE;IAU9D,MAAM,CAAC,MAAM,CAAC,IAAI,GAAE,eAAoB,GAAG,eAAe;IAI1D,WAAW,IAAI,SAAS;IAIlB,GAAG,CACP,KAAK,EAAE,aAAa,EACpB,OAAO,CAAC,EAAE,UAAU,GACnB,OAAO,CAAC,cAAc,GAAG,kBAAkB,CAAC;IASzC,MAAM,CACV,UAAU,EAAE,mBAAmB,EAC/B,KAAK,CAAC,EAAE,OAAO,EACf,OAAO,CAAC,EAAE,UAAU,GACnB,OAAO,CAAC,cAAc,GAAG,kBAAkB,CAAC;IAO/C,OAAO,CAAC,cAAc;IAqBtB,OAAO,CAAC,cAAc;IAWtB,OAAO,CAAC,UAAU;CAgEnB;AAED;;;;;;;;GAQG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAkB;IACvC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAmB;IACzC,2EAA2E;IAC3E,OAAO,CAAC,WAAW,CAAC,CAAwC;IAC5D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;gBAEjC,IAAI,EAAE,eAAe;IAIjC;;;;;OAKG;IACH,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI;IAWzC;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAKxD,KAAK,IAAI,QAAQ;CAQlB"}

package/dist/types/events/dispatcher.d.ts

@@ -0,0 +1,82 @@
+/**
+ * EventDispatcher — the central event bus (one per runner).
+ *
+ * Pattern: Observer (GoF) + Pub/Sub over a typed discriminated union.
+ * Role:    Single flat dispatcher for every event emitted during a run.
+ *          Replaces DOM-style bubbling — we have a central bus by
+ *          construction, so tree propagation is unnecessary.
+ * Emits:   N/A — this IS the emitter. It ROUTES events to listeners.
+ *
+ * Semantics:
+ *   - Observers are ALWAYS fire-and-forget (inherited from footprintjs's
+ *     recorder contract). Promise returns are never awaited.
+ *   - Listener errors are caught; they become `agentfootprint.error.fatal`
+ *     events with stage:'observer'. The run continues.
+ *   - Dispatch is O(1) hash lookup by event type.
+ *   - Zero allocation when no listener for an event type AND no wildcard.
+ *   - Dev-mode wraps listeners to warn on async listener Promise return.
+ */
+import type { AgentfootprintEvent, AgentfootprintEventMap, AgentfootprintEventType } from './registry.js';
+export type EventListener<K extends AgentfootprintEventType> = (event: AgentfootprintEventMap[K]) => void;
+export type WildcardListener = (event: AgentfootprintEvent) => void;
+export interface ListenOptions {
+    readonly once?: boolean;
+    readonly signal?: AbortSignal;
+}
+export type Unsubscribe = () => void;
+export type DomainWildcard = 'agentfootprint.composition.*' | 'agentfootprint.agent.*' | 'agentfootprint.stream.*' | 'agentfootprint.context.*' | 'agentfootprint.memory.*' | 'agentfootprint.tools.*' | 'agentfootprint.skill.*' | 'agentfootprint.permission.*' | 'agentfootprint.risk.*' | 'agentfootprint.fallback.*' | 'agentfootprint.cost.*' | 'agentfootprint.eval.*' | 'agentfootprint.error.*' | 'agentfootprint.pause.*' | 'agentfootprint.embedding.*';
+export type AllWildcard = '*';
+export type WildcardSubscription = DomainWildcard | AllWildcard;
+/**
+ * Central event bus. One per executable runner.
+ *
+ * Zero-alloc fast path: if `hasListenersFor(type)` is false AND there are
+ * no wildcards, `dispatch` returns immediately without iteration.
+ */
+export declare class EventDispatcher {
+    private readonly byType;
+    private readonly domainWildcards;
+    private readonly allWildcards;
+    /**
+     * Fast-path check. Returns true when at least one listener would fire
+     * for this type. Used by emitters to skip event-object allocation.
+     */
+    hasListenersFor(type: AgentfootprintEventType): boolean;
+    /**
+     * Subscribe a typed listener for a specific event type.
+     *
+     * The listener signature is `(event) => void` by design — Promises are
+     * NOT awaited. See dispatch() for details.
+     */
+    on<K extends AgentfootprintEventType>(type: K, listener: EventListener<K>, options?: ListenOptions): Unsubscribe;
+    /** Subscribe to a domain wildcard ('agentfootprint.context.*') or '*'. */
+    on(type: WildcardSubscription, listener: WildcardListener, options?: ListenOptions): Unsubscribe;
+    /**
+     * Subscribe a one-shot listener. Fires at most once and then auto-removes.
+     * Equivalent to `on(type, listener, { once: true })`.
+     */
+    once<K extends AgentfootprintEventType>(type: K, listener: EventListener<K>): Unsubscribe;
+    once(type: WildcardSubscription, listener: WildcardListener): Unsubscribe;
+    /**
+     * Remove a specific listener for a type. Prefer AbortSignal for auto-cleanup.
+     *
+     * Because listeners are wrapped in dev mode, identity is preserved via a
+     * WeakMap in addListener — consumers pass the original function.
+     */
+    off<K extends AgentfootprintEventType>(type: K, listener: EventListener<K>): void;
+    off(type: WildcardSubscription, listener: WildcardListener): void;
+    /**
+     * Route an event to all matching listeners (typed + domain-wildcard + all).
+     *
+     * Fire-and-forget: any returned Promise is IGNORED. Listener exceptions
+     * are caught and re-dispatched as `error.fatal` events with scope='observer'.
+     * The run continues regardless.
+     */
+    dispatch(event: AgentfootprintEvent): void;
+    private addListener;
+    private ensureBucket;
+    private bucketFor;
+    private fireBucket;
+    private domainKey;
+}
+//# sourceMappingURL=dispatcher.d.ts.map

package/dist/types/events/dispatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../../src/events/dispatcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EACV,mBAAmB,EACnB,sBAAsB,EACtB,uBAAuB,EACxB,MAAM,eAAe,CAAC;AAQvB,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,uBAAuB,IAAI,CAC7D,KAAK,EAAE,sBAAsB,CAAC,CAAC,CAAC,KAC7B,IAAI,CAAC;AAEV,MAAM,MAAM,gBAAgB,GAAG,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,CAAC;AAEpE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,MAAM,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC;AAarC,MAAM,MAAM,cAAc,GACtB,8BAA8B,GAC9B,wBAAwB,GACxB,yBAAyB,GACzB,0BAA0B,GAC1B,yBAAyB,GACzB,wBAAwB,GACxB,wBAAwB,GACxB,6BAA6B,GAC7B,uBAAuB,GACvB,2BAA2B,GAC3B,uBAAuB,GACvB,uBAAuB,GACvB,wBAAwB,GACxB,wBAAwB,GACxB,4BAA4B,CAAC;AAEjC,MAAM,MAAM,WAAW,GAAG,GAAG,CAAC;AAE9B,MAAM,MAAM,oBAAoB,GAAG,cAAc,GAAG,WAAW,CAAC;AAWhE;;;;;GAKG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0C;IACjE,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA0C;IAC1E,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA6B;IAI1D;;;OAGG;IACH,eAAe,CAAC,IAAI,EAAE,uBAAuB,GAAG,OAAO;IAWvD;;;;;OAKG;IACH,EAAE,CAAC,CAAC,SAAS,uBAAuB,EAClC,IAAI,EAAE,CAAC,EACP,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,EAC1B,OAAO,CAAC,EAAE,aAAa,GACtB,WAAW;IACd,0EAA0E;IAC1E,EAAE,CAAC,IAAI,EAAE,oBAAoB,EAAE,QAAQ,EAAE,gBAAgB,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,WAAW;IAyBhG;;;OAGG;IACH,IAAI,CAAC,CAAC,SAAS,uBAAuB,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,WAAW;IACzF,IAAI,CAAC,IAAI,EAAE,oBAAoB,EAAE,QAAQ,EAAE,gBAAgB,GAAG,WAAW;IASzE;;;;;OAKG;IACH,GAAG,CAAC,CAAC,SAAS,uBAAuB,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,IAAI;IACjF,GAAG,CAAC,IAAI,EAAE,oBAAoB,EAAE,QAAQ,EAAE,gBAAgB,GAAG,IAAI;IAgBjE;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,EAAE,mBAAmB,GAAG,IAAI;IAQ1C,OAAO,CAAC,WAAW;IAQnB,OAAO,CAAC,YAAY;IAmBpB,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,UAAU;IAoBlB,OAAO,CAAC,SAAS;CAKlB"}