agentfootprint 6.44.0 → 7.0.0

package/dist/esm/patterns/Reflection.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Reflection — iterative self-refinement via critic + revise.
+ *
+ * Paper: "Self-Refine: Iterative Refinement with Self-Feedback" —
+ *        Madaan et al., 2023 (https://arxiv.org/abs/2303.17651).
+ *
+ * Pattern: Factory (GoF) → produces a `Runner` built from a `Loop`
+ *          whose body is `Sequence(Propose → Critique → Revise)`.
+ * Role:    patterns/ layer. Pure composition — no new abstractions.
+ * Emits:   Loop's composition.iteration_start / iteration_exit plus
+ *          every inner LLMCall's stream.llm_start/end.
+ */
+import type { LLMProvider } from '../adapters/types.js';
+import type { Runner } from '../core/runner.js';
+export interface ReflectionOptions {
+    readonly provider: LLMProvider;
+    readonly model: string;
+    /** System prompt for the initial / revision proposer. */
+    readonly proposerPrompt: string;
+    /**
+     * System prompt for the critic. Should instruct the critic to return
+     * "DONE" (or a consumer-chosen sentinel) when the proposal is good
+     * enough — that string is checked by `untilCritiqueContains` to stop
+     * the refinement loop.
+     */
+    readonly criticPrompt: string;
+    /**
+     * Stop string the critic should emit when satisfied. When the critic's
+     * response contains this substring, the loop exits and the last
+     * proposal is returned. Default: 'DONE'.
+     */
+    readonly untilCritiqueContains?: string;
+    /** Max refinement iterations. Default 3. */
+    readonly maxIterations?: number;
+    readonly temperature?: number;
+    readonly maxTokens?: number;
+    readonly name?: string;
+    readonly id?: string;
+}
+/**
+ * Build a Reflection Runner. Each iteration:
+ *   1. Propose — LLMCall writes a candidate answer based on the input
+ *   2. Critique — LLMCall judges the candidate; exit marker stops loop
+ *   3. Revise — next iteration's propose sees the previous critique
+ *
+ * Each iteration's output (the candidate proposal) becomes the next
+ * iteration's input. The final iteration's proposal is returned.
+ */
+export declare function reflection(opts: ReflectionOptions): Runner<{
+    message: string;
+}, string>;

package/dist/esm/patterns/SelfConsistency.d.ts

@@ -0,0 +1,43 @@
+/**
+ * SelfConsistency — sample N answers, pick the majority.
+ *
+ * Paper: "Self-Consistency Improves Chain of Thought Reasoning in
+ * Language Models" — Wang et al., 2022 (https://arxiv.org/abs/2203.11171).
+ *
+ * Pattern: Factory (GoF) → produces a `Runner` that composes `Parallel`
+ *          of N `LLMCall` branches with a majority-vote merge function.
+ * Role:    patterns/ layer. Pure composition of core primitives +
+ *          core-flow compositions — no new abstractions.
+ * Emits:   Everything `Parallel` + `LLMCall` emit (stream / composition /
+ *          context). No pattern-specific event domain needed; consumers
+ *          observe via the standard typed listeners.
+ */
+import type { LLMProvider } from '../adapters/types.js';
+import type { Runner } from '../core/runner.js';
+export interface SelfConsistencyOptions {
+    readonly provider: LLMProvider;
+    readonly model: string;
+    readonly systemPrompt: string;
+    /** Number of parallel samples. 3 / 5 are typical; paper uses up to 40. */
+    readonly samples: number;
+    /** Sampling temperature. Defaults to a higher value (0.7) to get diverse samples. */
+    readonly temperature?: number;
+    readonly maxTokens?: number;
+    /**
+     * Consumer-provided extractor: given a full LLM response, return the
+     * "vote token" (e.g., the final answer stripped of the chain-of-thought
+     * preamble). Defaults to returning the trimmed string.
+     */
+    readonly extract?: (response: string) => string;
+    readonly name?: string;
+    readonly id?: string;
+}
+/**
+ * Build a SelfConsistency Runner. Given a system prompt, the Runner
+ * runs `samples` parallel LLMCalls with the same input, extracts each
+ * response's vote token, then returns the most-frequent token. Ties
+ * are broken by the first response's extract.
+ */
+export declare function selfConsistency(opts: SelfConsistencyOptions): Runner<{
+    message: string;
+}, string>;

package/dist/esm/patterns/Swarm.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Swarm — multi-agent handoff. At each step, an LLM-driven routing
+ * decision picks which agent handles the next turn.
+ *
+ * Origin: OpenAI Swarm experiment (2024). Useful for specialist
+ *         routing — each agent has a narrow role + its own tools.
+ *
+ * Pattern: Factory → produces a `Runner` built from
+ *          `Loop(Conditional(route-to-agent))`.
+ * Role:    patterns/ layer. Pure composition over existing primitives.
+ *          Agent roster is FIXED at build time; the routing decision
+ *          is made at runtime by a consumer-supplied `route(input)`
+ *          function (sync — pure over `{ message }`).
+ *
+ * For LLM-driven routing (the classic Swarm style), the consumer
+ * composes a "router" LLMCall as the first step of each iteration and
+ * parses its response in their `route()` function.
+ */
+import type { Runner } from '../core/runner.js';
+export interface SwarmAgent {
+    /** Stable id used in events + routing decisions. */
+    readonly id: string;
+    /** Display name for topology / narrative. */
+    readonly name?: string;
+    /** The runner that handles a turn when selected. */
+    readonly runner: Runner<{
+        message: string;
+    }, string>;
+}
+export interface SwarmOptions {
+    /**
+     * The fixed agent roster. Must contain >= 2 agents. The order doesn't
+     * matter — the `route` function selects by id.
+     */
+    readonly agents: readonly SwarmAgent[];
+    /**
+     * Routing function — receives the current message and returns the
+     * selected agent's id. Pure sync; evaluated before each iteration's
+     * chosen agent runs. Return `undefined` or an unknown id to halt
+     * the swarm (the loop's `until` guard fires).
+     */
+    readonly route: (input: {
+        readonly message: string;
+    }) => string | undefined;
+    /** Max hand-offs before the loop halts. Default 10. */
+    readonly maxHandoffs?: number;
+    readonly name?: string;
+    readonly id?: string;
+}
+/**
+ * Build a Swarm Runner. Each iteration:
+ *   1. Router evaluates `route(input)` to pick an agent id.
+ *   2. Conditional dispatches to that agent's runner.
+ *   3. Agent's output becomes the next iteration's input.
+ * Loop halts when `route` returns a halt-sentinel id (or unknown id
+ * falling to the `done` branch) OR when `maxHandoffs` is reached.
+ */
+export declare function swarm(opts: SwarmOptions): Runner<{
+    message: string;
+}, string>;

package/dist/esm/patterns/ToT.d.ts

@@ -0,0 +1,53 @@
+/**
+ * ToT — Tree of Thoughts: breadth-first iterative expansion + pruning.
+ *
+ * Paper: "Tree of Thoughts: Deliberate Problem Solving with Large
+ *        Language Models" — Yao et al., 2023
+ *        (https://arxiv.org/abs/2305.10601).
+ *
+ * Pattern: Factory → produces a `Runner` built from `Loop(depth times,
+ *          Parallel(K thought branches) + prune-to-top-M)`.
+ * Role:    patterns/ layer. Pure composition over existing primitives.
+ *          Build-time-fixed depth + branching factor; runtime frontier
+ *          is pruned to `beamWidth` per level via a consumer-supplied
+ *          scorer.
+ *
+ * Tradeoff vs. full DFS: this shipped variant is BFS with constant
+ * width. True DFS with backtracking or adaptive branching factor would
+ * need runtime-variable Parallel (DynamicParallel) or recursion.
+ */
+import type { LLMProvider } from '../adapters/types.js';
+import type { Runner } from '../core/runner.js';
+export interface ToTOptions {
+    readonly provider: LLMProvider;
+    readonly model: string;
+    /** System prompt for the thought-generation LLMCall. */
+    readonly thoughtPrompt: string;
+    /** Depth of the tree (number of expansion iterations). */
+    readonly depth: number;
+    /** Branching factor — K thoughts generated per frontier node per iteration. */
+    readonly branchingFactor: number;
+    /**
+     * Scorer: given a thought, return a numeric score. Higher is better.
+     * The top `beamWidth` thoughts survive each level; the rest are pruned.
+     * Synchronous so pruning is deterministic.
+     */
+    readonly score: (thought: string) => number;
+    /** Beam width — how many thoughts survive after each level. Default 1 (greedy). */
+    readonly beamWidth?: number;
+    readonly temperature?: number;
+    readonly maxTokens?: number;
+    readonly name?: string;
+    readonly id?: string;
+}
+/**
+ * Build a ToT Runner. At run time:
+ *   1. Seed — treat the input message as the initial frontier of 1 thought.
+ *   2. For each of `depth` iterations:
+ *      a. Parallel fan-out: generate `branchingFactor` new thoughts.
+ *      b. Score all new thoughts, keep top `beamWidth`, pass to next iteration.
+ *   3. Return the single best-scoring thought from the final frontier.
+ */
+export declare function tot(opts: ToTOptions): Runner<{
+    message: string;
+}, string>;

package/dist/esm/patterns/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * patterns/ — factory functions that compose primitives + core-flow
+ * into well-known agent patterns from the research literature.
+ *
+ * Each pattern is:
+ *   - A factory function returning a `Runner` — drops into any
+ *     `Sequence.step()`, `Parallel.branch()`, etc.
+ *   - Purely composed — no new primitives, no state machinery beyond
+ *     what the underlying compositions provide.
+ *   - Documented with the canonical paper reference.
+ *
+ * Build-time-fixed cardinality: all patterns take a FIXED
+ * shard/branch/agent count at build time. Run-time-variable branching
+ * is a separate (not-yet-shipped) feature and would need a
+ * `DynamicParallel` primitive.
+ */
+export { selfConsistency, type SelfConsistencyOptions } from './SelfConsistency.js';
+export { reflection, type ReflectionOptions } from './Reflection.js';
+export { debate, type DebateOptions } from './Debate.js';
+export { mapReduce, type MapReduceOptions } from './MapReduce.js';
+export { tot, type ToTOptions } from './ToT.js';
+export { swarm, type SwarmOptions, type SwarmAgent } from './Swarm.js';

package/dist/esm/providers.d.ts

@@ -0,0 +1,33 @@
+/**
+ * LLM provider adapters — implementation behind the `agentfootprint/llm-providers`
+ * subpath (which re-exports this file).
+ *
+ * The standalone `agentfootprint/providers` subpath alias was removed in 4.0.0.
+ * Import from the canonical subpath:
+ *
+ *   import { mock, anthropic, openai } from 'agentfootprint/llm-providers';
+ *
+ * Pattern: Adapter (GoF) — concrete `LLMProvider` implementations that
+ *          translate the agentfootprint port to a specific vendor SDK.
+ * Role:    Outer ring (Hexagonal). Swappable at runtime; the Agent
+ *          knows nothing about vendor specifics.
+ *
+ * What's here today:
+ *   • `mock` / `MockProvider` — deterministic + realistic-mode mock
+ *   • `anthropic` / `AnthropicProvider` — real provider (Claude)
+ *   • `openai` / `OpenAIProvider` — real provider (GPT)
+ *
+ * Bring your own (BYO):
+ *   For Bedrock / Ollama / Cohere / on-prem / fine-tuned models,
+ *   implement the `LLMProvider` interface (see `LLMProvider` exported
+ *   from the main barrel) — `complete()` is required, `stream()` is
+ *   optional. The `MockProvider` source is the canonical reference.
+ */
+export { MockProvider, mock, type MockProviderOptions, type MockReply, type LatencyMs, } from './adapters/llm/MockProvider.js';
+export { anthropic, AnthropicProvider, type AnthropicProviderOptions, } from './adapters/llm/AnthropicProvider.js';
+export { openai, OpenAIProvider, ollama, azureOpenai, type OpenAIProviderOptions, type AzureOpenAIProviderOptions, } from './adapters/llm/OpenAIProvider.js';
+export { bedrock, BedrockProvider, type BedrockProviderOptions, } from './adapters/llm/BedrockProvider.js';
+export { browserAnthropic, BrowserAnthropicProvider, type BrowserAnthropicProviderOptions, } from './adapters/llm/BrowserAnthropicProvider.js';
+export { browserOpenai, BrowserOpenAIProvider, type BrowserOpenAIProviderOptions, browserAzureOpenai, BrowserAzureOpenAIProvider, type BrowserAzureOpenAIProviderOptions, } from './adapters/llm/BrowserOpenAIProvider.js';
+export { createProvider, type ProviderKind, type CreateProviderOptions, } from './adapters/llm/createProvider.js';
+export type { LLMProvider, LLMRequest, LLMResponse, LLMChunk, LLMMessage, LLMToolSchema, } from './adapters/types.js';

package/dist/esm/providers.js

@@ -28,6 +28,6 @@ export { anthropic, AnthropicProvider, } from './adapters/llm/AnthropicProvider.
 export { openai, OpenAIProvider, ollama, azureOpenai, } from './adapters/llm/OpenAIProvider.js';
 export { bedrock, BedrockProvider, } from './adapters/llm/BedrockProvider.js';
 export { browserAnthropic, BrowserAnthropicProvider, } from './adapters/llm/BrowserAnthropicProvider.js';
-export { browserOpenai, BrowserOpenAIProvider, } from './adapters/llm/BrowserOpenAIProvider.js';
+export { browserOpenai, BrowserOpenAIProvider, browserAzureOpenai, BrowserAzureOpenAIProvider, } from './adapters/llm/BrowserOpenAIProvider.js';
 export { createProvider, } from './adapters/llm/createProvider.js';
 //# sourceMappingURL=providers.js.map

package/dist/esm/providers.js.map

@@ -1 +1 @@
-{"version":3,"file":"providers.js","sourceRoot":"","sources":["../../src/providers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EACL,YAAY,EACZ,IAAI,GAGL,MAAM,gCAAgC,CAAC;AAExC,OAAO,EACL,SAAS,EACT,iBAAiB,GAElB,MAAM,qCAAqC,CAAC;AAE7C,OAAO,EACL,MAAM,EACN,cAAc,EACd,MAAM,EACN,WAAW,GAGZ,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EACL,OAAO,EACP,eAAe,GAEhB,MAAM,mCAAmC,CAAC;AAE3C,OAAO,EACL,gBAAgB,EAChB,wBAAwB,GAEzB,MAAM,4CAA4C,CAAC;AAEpD,OAAO,EACL,aAAa,EACb,qBAAqB,GAEtB,MAAM,yCAAyC,CAAC;AAEjD,OAAO,EACL,cAAc,GAGf,MAAM,kCAAkC,CAAC"}
+{"version":3,"file":"providers.js","sourceRoot":"","sources":["../../src/providers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EACL,YAAY,EACZ,IAAI,GAIL,MAAM,gCAAgC,CAAC;AAExC,OAAO,EACL,SAAS,EACT,iBAAiB,GAElB,MAAM,qCAAqC,CAAC;AAE7C,OAAO,EACL,MAAM,EACN,cAAc,EACd,MAAM,EACN,WAAW,GAGZ,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EACL,OAAO,EACP,eAAe,GAEhB,MAAM,mCAAmC,CAAC;AAE3C,OAAO,EACL,gBAAgB,EAChB,wBAAwB,GAEzB,MAAM,4CAA4C,CAAC;AAEpD,OAAO,EACL,aAAa,EACb,qBAAqB,EAErB,kBAAkB,EAClB,0BAA0B,GAE3B,MAAM,yCAAyC,CAAC;AAEjD,OAAO,EACL,cAAc,GAGf,MAAM,kCAAkC,CAAC"}

package/dist/esm/recorders/core/AgentRecorder.d.ts

@@ -0,0 +1,15 @@
+/**
+ * AgentRecorder — forwards `agentfootprint.agent.*` emits to the dispatcher.
+ *
+ * Pattern: Factory (GoF) returning an EmitBridge instance.
+ * Role:    Convenience constructor for the agent-lifecycle bridge recorder.
+ *          Same mechanics as StreamRecorder, scoped to agent.* events
+ *          (turns + iterations + route decisions + handoffs).
+ * Emits:   agentfootprint.agent.turn_start / turn_end / iteration_start /
+ *          iteration_end / route_decided / handoff
+ */
+import { EmitBridge, type EmitBridgeOptions } from './EmitBridge.js';
+export type AgentRecorderOptions = Omit<EmitBridgeOptions, 'id' | 'prefix'> & {
+    readonly id?: string;
+};
+export declare function agentRecorder(options: AgentRecorderOptions): EmitBridge;

package/dist/esm/recorders/core/CompositionRecorder.d.ts

@@ -0,0 +1,17 @@
+/**
+ * CompositionRecorder — forwards `agentfootprint.composition.*` emits to the dispatcher.
+ *
+ * Pattern: Factory (GoF) returning an EmitBridge instance.
+ * Role:    Convenience constructor for the composition-domain bridge recorder.
+ *          Compositions (Sequence, Parallel, Conditional, Loop) typedEmit
+ *          composition.enter/exit/fork_start/branch_complete/merge_end/
+ *          route_decided/iteration_start/iteration_exit from their internal
+ *          stages; this recorder observes via footprintjs's EmitRecorder
+ *          channel and re-dispatches with typed payloads + meta.
+ * Emits:   agentfootprint.composition.*
+ */
+import { EmitBridge, type EmitBridgeOptions } from './EmitBridge.js';
+export type CompositionRecorderOptions = Omit<EmitBridgeOptions, 'id' | 'prefix'> & {
+    readonly id?: string;
+};
+export declare function compositionRecorder(options: CompositionRecorderOptions): EmitBridge;

package/dist/esm/recorders/core/ContextEvaluatedRecorder.d.ts

@@ -0,0 +1,23 @@
+/**
+ * ContextEvaluatedRecorder — forwards the `agentfootprint.context.evaluated`
+ * emit to the dispatcher.
+ *
+ * Pattern: Factory (GoF) returning an EmitBridge instance.
+ * Role:    The InjectionEngine `typedEmit`s `context.evaluated` (the
+ *          "what was considered / active / skipped + why" summary). Unlike the
+ *          other `context.*` events — which `ContextRecorder` DISPATCHES by
+ *          observing scope writes — this one is emitted complete by the stage,
+ *          so it just needs forwarding (the EmitBridge pass-through pattern,
+ *          same as StreamRecorder / AgentRecorder).
+ * Why a full-name prefix: scoped to EXACTLY `agentfootprint.context.evaluated`
+ *          (not the whole `context.*` domain) so it never double-dispatches
+ *          `context.slot_composed`, which IS `typedEmit`'d in the viz chart
+ *          (`buildMessageApiChart`) while ALSO being dispatched by
+ *          `ContextRecorder` from writes in the runtime charts.
+ * Emits:   agentfootprint.context.evaluated
+ */
+import { EmitBridge, type EmitBridgeOptions } from './EmitBridge.js';
+export type ContextEvaluatedRecorderOptions = Omit<EmitBridgeOptions, 'id' | 'prefix'> & {
+    readonly id?: string;
+};
+export declare function contextEvaluatedRecorder(options: ContextEvaluatedRecorderOptions): EmitBridge;

package/dist/esm/recorders/core/ContextRecorder.d.ts

@@ -0,0 +1,47 @@
+/**
+ * ContextRecorder — observes footprintjs subflow + scope events, emits
+ * grouped `context.*` domain events via the EventDispatcher.
+ *
+ * Pattern: Observer (GoF) + Pipes & Filters (Hohpe & Woolf, 2003).
+ * Role:    Core semantic grouping layer for the 3-slot model. Watches
+ *          slot subflows (sf-system-prompt / sf-messages / sf-tools) and
+ *          translates raw writes into context.injected / evicted /
+ *          slot_composed / budget_pressure events.
+ * Emits:   agentfootprint.context.injected
+ *          agentfootprint.context.evicted
+ *          agentfootprint.context.slot_composed
+ *          agentfootprint.context.budget_pressure
+ */
+import type { CombinedRecorder, FlowSubflowEvent, WriteEvent } from 'footprintjs';
+import type { EventDispatcher } from '../../events/dispatcher.js';
+import { type RunContext } from '../../bridge/eventMeta.js';
+/**
+ * Supplies the recorder with run-level context. Passed at construction
+ * time (static fields) OR updated via `updateRunContext` between runs
+ * when reusing one recorder across multiple executor runs.
+ */
+export interface ContextRecorderOptions {
+    readonly dispatcher: EventDispatcher;
+    readonly id?: string;
+    readonly getRunContext: () => RunContext;
+}
+export declare class ContextRecorder implements CombinedRecorder {
+    readonly id: string;
+    private readonly dispatcher;
+    private readonly getRunContext;
+    private readonly seenInjections;
+    constructor(options: ContextRecorderOptions);
+    onSubflowEntry(event: FlowSubflowEvent): void;
+    onSubflowExit(event: FlowSubflowEvent): void;
+    onWrite(event: WriteEvent): void;
+    private handleInjectionsWrite;
+    private handleSlotComposedWrite;
+    private handleEvictionsWrite;
+    private handleBudgetPressureWrite;
+    private emitInjected;
+    private dispatch;
+    private asInjectionArray;
+    private asSlotComposition;
+    private asEvictionArray;
+    private asPressureArray;
+}

package/dist/esm/recorders/core/CostRecorder.d.ts

@@ -0,0 +1,14 @@
+/**
+ * CostRecorder — forwards `agentfootprint.cost.*` emits to the dispatcher.
+ *
+ * Pattern: Factory (GoF) returning an EmitBridge instance.
+ * Role:    Bridges `cost.tick` + `cost.limit_hit` emits from LLMCall / Agent
+ *          stages (via `emitCostTick`) to the EventDispatcher so typed
+ *          consumer listeners fire.
+ * Emits:   agentfootprint.cost.tick / cost.limit_hit
+ */
+import { EmitBridge, type EmitBridgeOptions } from './EmitBridge.js';
+export type CostRecorderOptions = Omit<EmitBridgeOptions, 'id' | 'prefix'> & {
+    readonly id?: string;
+};
+export declare function costRecorder(options: CostRecorderOptions): EmitBridge;

package/dist/esm/recorders/core/EmitBridge.d.ts

@@ -0,0 +1,30 @@
+/**
+ * EmitBridge — forwards footprintjs emits whose name starts with a given
+ * prefix to the EventDispatcher, enriched with EventMeta.
+ *
+ * Pattern: Adapter (GoF) + Pipes & Filters (Hohpe & Woolf, 2003).
+ * Role:    Single reusable translation layer for every "pass-through"
+ *          prefix recorder (StreamRecorder, AgentRecorder, and any
+ *          future domain whose events are emitted via typedEmit()).
+ * Emits:   Any event whose name matches `prefix` — type derived from the
+ *          emit name and validated by the consumer's EventMap subscription.
+ */
+import type { CombinedRecorder, EmitEvent } from 'footprintjs';
+import type { EventDispatcher } from '../../events/dispatcher.js';
+import { type RunContext } from '../../bridge/eventMeta.js';
+export interface EmitBridgeOptions {
+    readonly dispatcher: EventDispatcher;
+    /** Recorder id — must be unique among attached recorders. */
+    readonly id: string;
+    /** Event-name prefix this bridge forwards (e.g. 'agentfootprint.stream.'). */
+    readonly prefix: string;
+    readonly getRunContext: () => RunContext;
+}
+export declare class EmitBridge implements CombinedRecorder {
+    readonly id: string;
+    private readonly dispatcher;
+    private readonly prefix;
+    private readonly getRunContext;
+    constructor(options: EmitBridgeOptions);
+    onEmit(event: EmitEvent): void;
+}

package/dist/esm/recorders/core/ErrorBridge.d.ts

@@ -0,0 +1,38 @@
+/**
+ * ErrorBridge — translates footprintjs's STRUCTURAL `onRunFailed` (the
+ * terminal run-boundary event fired when a run throws a non-pause error)
+ * into agentfootprint's TYPED `agentfootprint.error.fatal` domain event.
+ *
+ * Pattern: Adapter (GoF) — same role as EmitBridge, different channel.
+ * Role:    Close the "failed run is invisible" gap. footprintjs fires
+ *          `onError` (stage-level) + `onRunFailed` (run-level) on the
+ *          FlowRecorder channel, but agentfootprint's typed consumers
+ *          (LiveStateRecorder clearing in-flight, monitors setting
+ *          status) listen on the DISPATCHER. Without a bridge, a thrown
+ *          LLM call left `isLLMInFlight()` stuck true ("Chatbot is
+ *          thinking…" forever) and downstream STATUS showed "ok". This
+ *          re-dispatches one terminal typed event so every consumer
+ *          reacts uniformly.
+ * Emits:   agentfootprint.error.fatal (once per failed top-level run).
+ *
+ * Fires at the TOP LEVEL only — footprintjs `onRunFailed` is a run
+ * boundary, not a per-stage event. Subflow errors propagate up and
+ * surface here once.
+ */
+import type { CombinedRecorder, FlowRunFailedEvent } from 'footprintjs';
+import type { EventDispatcher } from '../../events/dispatcher.js';
+import { type RunContext } from '../../bridge/eventMeta.js';
+export interface ErrorBridgeOptions {
+    readonly dispatcher: EventDispatcher;
+    /** Recorder id — must be unique among attached recorders. */
+    readonly id?: string;
+    readonly getRunContext: () => RunContext;
+}
+export declare class ErrorBridge implements CombinedRecorder {
+    readonly id: string;
+    private readonly dispatcher;
+    private readonly getRunContext;
+    constructor(options: ErrorBridgeOptions);
+    onRunFailed(event: FlowRunFailedEvent): void;
+}
+export declare function errorBridge(options: ErrorBridgeOptions): ErrorBridge;

package/dist/esm/recorders/core/EvalRecorder.d.ts

@@ -0,0 +1,16 @@
+/**
+ * EvalRecorder — forwards `agentfootprint.eval.*` emits to the dispatcher.
+ *
+ * Pattern: Factory over EmitBridge.
+ * Role:    Bridges consumer-emitted `eval.score` + `eval.threshold_crossed`
+ *          events to typed listeners. Evaluation is a consumer concern
+ *          (LLM-based grading, heuristic checks, reference-output diffs),
+ *          so the library only provides transport — not any built-in
+ *          evaluators.
+ * Emits:   agentfootprint.eval.score / eval.threshold_crossed
+ */
+import { EmitBridge, type EmitBridgeOptions } from './EmitBridge.js';
+export type EvalRecorderOptions = Omit<EmitBridgeOptions, 'id' | 'prefix'> & {
+    readonly id?: string;
+};
+export declare function evalRecorder(options: EvalRecorderOptions): EmitBridge;

package/dist/esm/recorders/core/MemoryRecorder.d.ts

@@ -0,0 +1,17 @@
+/**
+ * MemoryRecorder — forwards `agentfootprint.memory.*` emits to the dispatcher.
+ *
+ * Pattern: Factory over EmitBridge.
+ * Role:    Bridges memory-layer events (strategy_applied, attached,
+ *          detached, written) emitted by consumer memory adapters.
+ *          The library does not ship a memory implementation; consumers
+ *          plug in their own store and emit these events where relevant
+ *          (e.g., before/after sliding-window summarization).
+ * Emits:   agentfootprint.memory.strategy_applied / attached /
+ *          detached / written
+ */
+import { EmitBridge, type EmitBridgeOptions } from './EmitBridge.js';
+export type MemoryRecorderOptions = Omit<EmitBridgeOptions, 'id' | 'prefix'> & {
+    readonly id?: string;
+};
+export declare function memoryRecorder(options: MemoryRecorderOptions): EmitBridge;

package/dist/esm/recorders/core/PermissionRecorder.d.ts

@@ -0,0 +1,16 @@
+/**
+ * PermissionRecorder — forwards `agentfootprint.permission.*` emits
+ * to the dispatcher.
+ *
+ * Pattern: Factory over EmitBridge.
+ * Role:    Bridges permission.check, permission.gate_opened, and
+ *          permission.gate_closed emits into the typed dispatcher so
+ *          consumer `.on('agentfootprint.permission.check', ...)`
+ *          listeners fire.
+ * Emits:   agentfootprint.permission.check / gate_opened / gate_closed
+ */
+import { EmitBridge, type EmitBridgeOptions } from './EmitBridge.js';
+export type PermissionRecorderOptions = Omit<EmitBridgeOptions, 'id' | 'prefix'> & {
+    readonly id?: string;
+};
+export declare function permissionRecorder(options: PermissionRecorderOptions): EmitBridge;

package/dist/esm/recorders/core/ReliabilityRecorder.d.ts

@@ -0,0 +1,24 @@
+/**
+ * ReliabilityRecorder — forwards `agentfootprint.reliability.*` emits to
+ * the dispatcher.
+ *
+ * Pattern: Factory (GoF) returning an EmitBridge instance.
+ * Role:    Bridges the rules-based reliability loop's telemetry
+ *          (`reliability.fail_fast` / `reliability.retried` /
+ *          `reliability.recovered`, emitted from `executeWithReliability`
+ *          via `typedEmit`) to the EventDispatcher so typed consumer
+ *          listeners (`agent.on('agentfootprint.reliability.retried', …)`)
+ *          fire. Without this bridge those emits hit the footprintjs emit
+ *          channel but never reach the dispatcher.
+ * Emits:   agentfootprint.reliability.fail_fast / retried / recovered
+ *
+ * NOTE: this is the RULES-LOOP family. The generic `error.retried` /
+ * `error.recovered` events are reserved for the standalone provider
+ * decorators (withRetry/withFallback) and are NOT bridged here — see
+ * docs/MENTAL_MODEL.md §14.
+ */
+import { EmitBridge, type EmitBridgeOptions } from './EmitBridge.js';
+export type ReliabilityRecorderOptions = Omit<EmitBridgeOptions, 'id' | 'prefix'> & {
+    readonly id?: string;
+};
+export declare function reliabilityRecorder(options: ReliabilityRecorderOptions): EmitBridge;

package/dist/esm/recorders/core/SkillRecorder.d.ts

@@ -0,0 +1,14 @@
+/**
+ * SkillRecorder — forwards `agentfootprint.skill.*` emits to the dispatcher.
+ *
+ * Pattern: Factory over EmitBridge.
+ * Role:    Bridges skill lifecycle events (activated, deactivated) emitted
+ *          by consumer skill-management code. Skills are a consumer-owned
+ *          context-engineering concern; the library only provides transport.
+ * Emits:   agentfootprint.skill.activated / skill.deactivated
+ */
+import { EmitBridge, type EmitBridgeOptions } from './EmitBridge.js';
+export type SkillRecorderOptions = Omit<EmitBridgeOptions, 'id' | 'prefix'> & {
+    readonly id?: string;
+};
+export declare function skillRecorder(options: SkillRecorderOptions): EmitBridge;

package/dist/esm/recorders/core/StreamRecorder.d.ts

@@ -0,0 +1,15 @@
+/**
+ * StreamRecorder — forwards `agentfootprint.stream.*` emits to the dispatcher.
+ *
+ * Pattern: Factory (GoF) returning an EmitBridge instance.
+ * Role:    Convenience constructor for the stream-domain bridge recorder.
+ *          Stage code in LLMCall/Agent calls `typedEmit(scope, 'agentfootprint.stream.llm_start', {...})`;
+ *          this recorder observes via footprintjs's EmitRecorder channel
+ *          and re-dispatches with typed payloads + enriched meta.
+ * Emits:   agentfootprint.stream.llm_start / llm_end / token / tool_start / tool_end
+ */
+import { EmitBridge, type EmitBridgeOptions } from './EmitBridge.js';
+export type StreamRecorderOptions = Omit<EmitBridgeOptions, 'id' | 'prefix'> & {
+    readonly id?: string;
+};
+export declare function streamRecorder(options: StreamRecorderOptions): EmitBridge;

package/dist/esm/recorders/core/ToolsRecorder.d.ts

@@ -0,0 +1,18 @@
+/**
+ * ToolsRecorder — forwards `agentfootprint.tools.*` emits to the dispatcher.
+ *
+ * Pattern: Factory over EmitBridge.
+ * Role:    Bridges tool-domain events. Today: discovery_failed (emitted by
+ *          buildToolsSlot when an external `ToolProvider.list(ctx)` throws
+ *          or rejects). The other tools.* events (offered/activated/
+ *          deactivated) are declared in the registry for consumer code
+ *          that wants to emit them; the same prefix bridge forwards all
+ *          of them.
+ * Emits:   agentfootprint.tools.offered / tools.activated / tools.deactivated
+ *          / tools.discovery_failed
+ */
+import { EmitBridge, type EmitBridgeOptions } from './EmitBridge.js';
+export type ToolsRecorderOptions = Omit<EmitBridgeOptions, 'id' | 'prefix'> & {
+    readonly id?: string;
+};
+export declare function toolsRecorder(options: ToolsRecorderOptions): EmitBridge;

package/dist/esm/recorders/core/ValidationRecorder.d.ts

@@ -0,0 +1,16 @@
+/**
+ * ValidationRecorder — forwards `agentfootprint.validation.*` emits to the
+ * dispatcher.
+ *
+ * Pattern: Factory over EmitBridge.
+ * Role:    Bridges tool-args validation events (#9) emitted by the
+ *          toolCalls stage when LLM-produced args fail the tool's declared
+ *          `inputSchema` — so consumers observe rejected/warned calls via
+ *          `agent.on('agentfootprint.validation.args_invalid', ...)`.
+ * Emits:   agentfootprint.validation.args_invalid
+ */
+import { EmitBridge, type EmitBridgeOptions } from './EmitBridge.js';
+export type ValidationRecorderOptions = Omit<EmitBridgeOptions, 'id' | 'prefix'> & {
+    readonly id?: string;
+};
+export declare function validationRecorder(options: ValidationRecorderOptions): EmitBridge;