agentfootprint 6.44.0 → 6.45.0

package/dist/esm/recorders/observability/internal/ForkTracker.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @internal — not part of the public agentfootprint API. Imported only
+ * by RunStepRecorder. Subject to change without notice; do not import
+ * via deep paths.
+ *
+ * ForkTracker — owns the bookkeeping for parallel-fork emission and
+ * merge-step detection. Extracted from RunStepRecorder per Convention 1
+ * (one purpose per recorder/state machine).
+ *
+ * Responsibilities (and ONLY these):
+ *   1. Coalesce repeated `onFork` events for the same parent (race-safe
+ *      via parent+runtimeStageId key).
+ *   2. Track which child branches belong to which parent fork.
+ *   3. Track which branches have exited; signal "merge ready" when ALL
+ *      branches of a fork have exited.
+ *
+ * What it does NOT own:
+ *   - Storage (the recorder writes RunSteps to its SequenceStore).
+ *   - Run-boundary detection (the recorder's runIdGuard wipes this
+ *     tracker via `clear()`).
+ *   - Any other state machine.
+ */
+export interface ForkRegistration {
+    /** True if this is a NEW fork; false if the same fork was already seen
+     *  (caller should suppress duplicate emission). */
+    readonly fresh: boolean;
+}
+export interface MergeReady {
+    /** All branch IDs of the now-fully-exited fork, in the order they
+     *  were originally registered. */
+    readonly branches: readonly string[];
+}
+export declare class ForkTracker {
+    /** Per-parent: the ordered list of child branch IDs registered. */
+    private readonly branches;
+    /** Per-parent: the set of child branch IDs that have exited so far. */
+    private readonly exited;
+    /** Reverse index: child branch ID → its parent fork. */
+    private readonly childToParent;
+    /** Set of `${parent}@${runtimeStageId}` keys already registered, to
+     *  coalesce repeated onFork events. */
+    private readonly emittedKeys;
+    /**
+     * Register a new fork. If the same fork (by parent+runtimeStageId)
+     * was already registered, returns `{ fresh: false }` and the caller
+     * should suppress emission. Otherwise registers all child branches
+     * and returns `{ fresh: true }`.
+     */
+    registerFork(parent: string, runtimeStageId: string, children: readonly string[]): ForkRegistration;
+    /** True if this child belongs to a tracked fork (used to suppress
+     *  sequential-emission for fork-branch entry events). */
+    isForkChild(childSubflowId: string): boolean;
+    /**
+     * Record a fork-branch exit. If this completes the fork (all branches
+     * have exited), returns `{ branches }` so the caller can emit a merge
+     * step. Returns `undefined` if not yet complete or not a fork branch.
+     */
+    recordChildExit(childSubflowId: string): MergeReady | undefined;
+    clear(): void;
+}

package/dist/esm/recorders/observability/internal/RootInferrer.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @internal — not part of the public agentfootprint API. Imported only
+ * by RunStepRecorder. Subject to change without notice.
+ *
+ * RootInferrer — small state machine deciding whether a run's root is
+ * a single leaf primitive (Agent / LLMCall) or a composition (Sequence
+ * / Parallel / Conditional / Loop).
+ *
+ * Extracted from RunStepRecorder per Convention 1.
+ *
+ * Inputs: subflow entries (with their depth + parsed primitiveKind),
+ * fork events (depth 0 → Parallel root), decision events (depth 0 →
+ * Conditional root), loop events (depth 0 → Loop root).
+ *
+ * Output: query `kind()` for the inferred root. Returns `undefined`
+ * until a signal arrives.
+ *
+ * Inference rules:
+ *   - Decisive composition signals (fork / decide / loop AT DEPTH 0)
+ *     lock the root and are never overridden.
+ *   - Shallowest primitive boundary IS a composition kind → root is
+ *     that composition.
+ *   - Two+ leaf siblings at the shallowest depth → implicit Sequence
+ *     root (Sequence-as-runner case where the Sequence itself doesn't
+ *     fire its own subflow.entry).
+ *   - Single leaf at the shallowest depth → root is "leaf".
+ */
+export type InferredRoot = 'leaf' | 'sequence' | 'parallel' | 'conditional' | 'loop' | undefined;
+export declare class RootInferrer {
+    private inferred;
+    private shallowestDepth;
+    private shallowestSiblings;
+    /** Currently-inferred root kind, or undefined if no signal yet. */
+    kind(): InferredRoot;
+    /** True when the root is a single leaf primitive (or unknown,
+     *  which should be treated as leaf for kind-filter purposes). */
+    isLeafRoot(): boolean;
+    /** Observe a subflow entry. */
+    observeSubflowEntry(depth: number, primitiveKind: string | undefined): void;
+    /** Observe a fork event. Locks root to Parallel if at depth 0 and
+     *  no decisive root has been inferred yet. */
+    observeFork(depth: number): void;
+    /** Observe a decision event. Locks root to Conditional if at depth 0
+     *  and no decisive root has been inferred yet. */
+    observeDecision(depth: number): void;
+    /** Observe a loop event. Locks root to Loop if at depth 0 and no
+     *  decisive root has been inferred yet. */
+    observeLoop(depth: number): void;
+    clear(): void;
+    private tryInfer;
+}

package/dist/esm/recorders/observability/internal/SequenceSiblingTracker.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @internal — not part of the public agentfootprint API. Imported only
+ * by RunStepRecorder. Subject to change without notice.
+ *
+ * SequenceSiblingTracker — tracks the most-recent leaf exit at each
+ * depth so the recorder knows when a new leaf entry at the same depth
+ * should emit a "sequential handoff" step ("forwards" semantics).
+ *
+ * Extracted from RunStepRecorder per Convention 1.
+ *
+ * Use:
+ *   - On leaf EXIT: `recordExit(depth, subflowId)`.
+ *   - On leaf ENTRY: `peekPrevSibling(depth)` returns the previous
+ *     leaf's subflowId at this depth, or undefined for the first leaf.
+ */
+export declare class SequenceSiblingTracker {
+    private readonly prevExitedAtDepth;
+    /** Returns the subflow id of the most-recently-exited leaf at this
+     *  depth, or undefined if this is the first leaf entry at the depth. */
+    peekPrevSibling(depth: number): string | undefined;
+    /** Record that a leaf at this depth just exited. */
+    recordExit(depth: number, subflowId: string): void;
+    clear(): void;
+}

package/dist/esm/recorders/observability/localObservability.d.ts

@@ -0,0 +1,48 @@
+/**
+ * localObservability — Tier-3 (Debug) observability: RETAIN a live run model,
+ * render it live, and snapshot it for offline replay.
+ *
+ * One handle, two outputs:
+ *   - LIVE   — `onUpdate(graph)` fires per event; pass the handle to
+ *              `<Lens recorder={handle} />` and it re-renders as the agent runs.
+ *   - OFFLINE— `getTrace()` (any time) and `onComplete(trace)` (auto, at run
+ *              exit) freeze the model into a JSON-lossless `Trace` for `<Replay>`.
+ *
+ * Contrast with `enable.observability({ strategy })` (Tier-4 / Monitor), which
+ * ships each event to a vendor and FORGETS. localObservability KEEPS the model
+ * so you can look at it — locally, with full content. See
+ * `docs/design/local-observability-and-pii.md`.
+ *
+ * It's a thin wrapper over `enable.flowchart` (the existing live StepGraph) +
+ * `serializeTrace` (the snapshot). UI-free: returns data, never React.
+ */
+import type { CombinedRecorder } from 'footprintjs';
+import type { EventDispatcher } from '../../events/dispatcher.js';
+import type { DomainEvent } from './BoundaryRecorder.js';
+import { type FlowchartHandle, type StepGraph } from './FlowchartRecorder.js';
+import { type SerializeTraceOptions, type Trace } from './trace.js';
+export interface LocalObservabilityOptions {
+    /** LIVE recording — called with a fresh StepGraph on every event (drives `<Lens>`). */
+    readonly onLive?: (graph: StepGraph) => void;
+    /** At run exit — called once with the finalized recording (a Trace, auto-serialized) to replay offline. */
+    readonly onRecorded?: (trace: Trace) => void;
+    /**
+     * Default serialize-time redaction, applied to BOTH `onRecorded` and
+     * `getTrace()` (overridable per `getTrace` call). Runs once per event so PII
+     * never enters the Trace — see the trust-boundary note in the design doc.
+     * Pass `redactContent` for a ready-made redactor.
+     */
+    readonly redact?: (event: DomainEvent) => DomainEvent;
+}
+/** A `FlowchartHandle` (live) plus `getTrace()` (offline snapshot). */
+export interface LocalObservabilityHandle extends FlowchartHandle {
+    /** Freeze the current model into a JSON-lossless Trace. Safe during or after a run. */
+    getTrace(options?: SerializeTraceOptions): Trace;
+}
+/**
+ * Attach a local-observability handle. `now` is injectable for tests (the
+ * library otherwise stamps `Date.now()` at serialize time).
+ *
+ * @internal Called from `RunnerBase.enable.localObservability`.
+ */
+export declare function attachLocalObservability(runnerAttach: (recorder: CombinedRecorder) => () => void, dispatcher: EventDispatcher, options?: LocalObservabilityOptions, now?: () => number, getStructure?: () => unknown): LocalObservabilityHandle;

package/dist/esm/recorders/observability/observeRunId.d.ts

@@ -0,0 +1,36 @@
+/**
+ * observeRunId — shared run-boundary detection helper for recorders.
+ *
+ * Why this exists: 5 places in observability/* duplicated the same
+ * 10-line pattern (lastRunId field + 3-line check + reset). Extract
+ * once so the contract stays consistent under maintenance.
+ *
+ * The pattern: hold a `lastRunId | undefined`. On every observed event:
+ *   - If runId is missing/undefined → no-op (defensive, allows callers
+ *     to pass `event.meta?.runId` without checking).
+ *   - First observation (lastRunId === undefined) → record, no reset.
+ *   - Same runId → no-op (steady state).
+ *   - Different runId → call onNewRun() then record the new id.
+ *
+ * Returned helper is mutable closure state — callers store it as a
+ * private field and call `.observe(runId)` from event hooks.
+ *
+ * @example
+ * ```typescript
+ * class MyRecorder implements ScopeRecorder {
+ *   private readonly runIdGuard = createRunIdObserver(() => this.reset());
+ *   onWrite(e) {
+ *     this.runIdGuard.observe(e.traversalContext?.runId);
+ *     // ... handle event
+ *   }
+ *   private reset() { this.store.clear(); }
+ * }
+ * ```
+ */
+export interface RunIdObserver {
+    /** Process an event's runId; fires onNewRun callback when it changes. */
+    observe(runId: string | undefined): void;
+    /** Clear state so the next observation initializes fresh. */
+    reset(): void;
+}
+export declare function createRunIdObserver(onNewRun: () => void): RunIdObserver;

package/dist/esm/recorders/observability/status/statusTemplates.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Thinking templates — chat-bubble surface (separate from commentary).
+ *
+ * Audience split:
+ *   • COMMENTARY (`commentaryTemplates`)  — third-person, every moment,
+ *                                            shown in Lens panel. Audience:
+ *                                            developer / observer.
+ *   • THINKING (this file)                — first-person, mid-call only,
+ *                                            shown in chat bubble. Audience:
+ *                                            end user chatting with the agent.
+ *
+ * The thinking surface is a tiny finite state machine driven purely by
+ * the event log:
+ *
+ *      ┌──────────┐  llm.start, no tools yet
+ *  ────┤  idle    ├────────────────────────────► "Thinking…"
+ *      └──────────┘
+ *
+ *      ┌──────────┐  stream.token chunks accumulate
+ *  ────┤streaming ├────────────────────────────► "{{partial}}"
+ *      └──────────┘
+ *
+ *      ┌──────────┐  tool.start, no tool.end yet
+ *  ────┤   tool   ├────────────────────────────► "Working on `weather`…"
+ *      └──────────┘                               (or per-tool override)
+ *
+ *      ┌──────────┐  pause.request, no resume yet
+ *  ────┤  paused  ├────────────────────────────► "Waiting on you: …"
+ *      └──────────┘
+ *
+ *      (null)        run done / between calls   → bubble hidden
+ *
+ * The selector returns the CURRENT state by walking the event log;
+ * the renderer maps state → final string by looking up the template.
+ *
+ * Per-tool templates: consumers can ship `tool.<toolName>` keys
+ * (e.g. `tool.weather: 'Looking up the weather…'`) which the renderer
+ * prefers over the generic `tool` template. Lets each tool have its
+ * own first-person status without per-tool plumbing.
+ */
+import type { AgentfootprintEvent } from '../../../events/registry.js';
+/** The four mid-call states a chat bubble might render. */
+export type StatusKind = 'idle' | 'tool' | 'streaming' | 'paused';
+/**
+ * What the selector returns. The chat-bubble consumer feeds this into
+ * the renderer to get the final string.
+ */
+export interface StatusState {
+    readonly state: StatusKind;
+    /** Vars for `{{name}}` substitution in the matched template. */
+    readonly vars: Readonly<Record<string, string>>;
+    /** When `state === 'tool'`, the resolving toolName. The renderer
+     *  uses this to look up `tool.<toolName>` before the generic `tool`. */
+    readonly toolName?: string;
+}
+/** Flat template map. Keys: state kinds + per-tool overrides. */
+export type StatusTemplates = Readonly<Record<string, string>>;
+/** Render context — what the consumer's app config injects. */
+export interface StatusContext {
+    /** Active actor's name. Substituted as `{{appName}}` in templates. */
+    readonly appName: string;
+}
+/**
+ * Bundled English defaults. Override in the agent config via
+ * `.thinkingTemplates({...})`. Per-tool overrides go via
+ * `tool.<toolName>` keys.
+ */
+export declare const defaultStatusTemplates: StatusTemplates;
+/**
+ * Derive the current thinking state from the event log.
+ *
+ * Single forward walk that tracks "active" state for each domain:
+ *   • pause       — set on pause.request, cleared on pause.resume
+ *   • tool        — set on tool.start, cleared on matching tool.end
+ *                   (matched by `toolCallId` for parallel-tool safety)
+ *   • llm         — set on llm.start, cleared on llm.end
+ *
+ * Priority order (highest first):
+ *
+ *   1. ACTIVE PAUSE wins. When the agent is waiting on the human,
+ *      that's what the chat should show — not the underlying tool
+ *      that triggered the pause.
+ *   2. ACTIVE TOOL — the LLM said "use a tool" and the tool is
+ *      running. Show "Working on `<toolName>`…".
+ *   3. ACTIVE LLM — call in flight. Show streaming tokens if any
+ *      arrived, otherwise "Thinking…".
+ *   4. Otherwise null (bubble hidden).
+ *
+ * Pure projection. Forward walk is O(n); a closing event correctly
+ * cancels its matching opener so a completed tool.start/tool.end
+ * pair leaves the state quiescent.
+ */
+export declare function selectStatus(events: readonly AgentfootprintEvent[]): StatusState | null;
+/**
+ * Resolve the matched template + substitute vars.
+ *
+ *   • `state === null`           → null (chat bubble renders nothing)
+ *   • `state === 'tool'`         → tries `tool.<toolName>` first, then
+ *                                   generic `tool`
+ *   • Other states               → looks up the state's name as the key
+ *
+ * Missing template keys return null rather than the empty string —
+ * keeps the contract honest (consumer can detect "no template" and
+ * fall back to its own default).
+ */
+export declare function renderStatusLine(state: StatusState | null, ctx: StatusContext, templates?: StatusTemplates): string | null;

package/dist/esm/recorders/observability/trace.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Trace — a UI-free, JSON-lossless snapshot of a run for OFFLINE REPLAY.
+ *
+ * `localObservability()` (Tier-3 / Debug) retains a live model during a run.
+ * `serializeTrace()` freezes that model into a `Trace` — plain JSON you can
+ * persist (file, Redis, a bug report) and later rehydrate WITHOUT re-running
+ * the agent. `agentfootprint-lens`'s `<Replay trace={…} />` consumes it and
+ * rebuilds the flowchart via the existing translators.
+ *
+ * A `Trace` stores ONLY the domain-event log (the single source of truth the
+ * Lens already reads). The step graph is ALWAYS a derived projection of those
+ * events (footprint.js's "graph is derived, never post-processed" principle) —
+ * it is rebuilt at render time, never stored. Storing a derived graph would be
+ * redundant AND a redaction hazard: a second content surface a per-event
+ * `redact` could never reach.
+ *
+ * PII / trust boundary: the event log carries real content — `llm.end.content`,
+ * `tool.start.args`, `tool.end.result`, `context.injected.contentSummary`,
+ * `run`/`subflow` `payload`, `decision.branch.rationale`. A live, in-process
+ * model is fine, but **serializing is a trust-boundary crossing** (the trace
+ * can travel). So redaction is applied HERE, at serialize time, via a
+ * consumer `redact` function — PII never enters the `Trace`. `redactContent`
+ * is a ready-made redactor covering every content field. The result is
+ * self-describing: `trace.redaction`. See
+ * `docs/design/local-observability-and-pii.md`.
+ *
+ * Because `getEvents()` is FLAT (parent + every subflow), one `redact` pass
+ * covers the whole tree — no per-subflow inheritance needed here. (The engine's
+ * `RedactionPolicy` separately propagates to subflows for the OBSERVER mirror.)
+ */
+import type { DomainEvent } from './BoundaryRecorder.js';
+import { type StepGraph } from './FlowchartRecorder.js';
+/**
+ * How a `Trace` was redacted before serialization.
+ * - `'none'`   — raw content (no `redact`). A `<Replay>` UI may warn.
+ * - `'pii'`    — a consumer `redact` ran (the default label when one is given).
+ * - `'policy'` — produced from a declarative `RedactionPolicy` (future).
+ */
+export type TraceRedaction = 'none' | 'pii' | 'policy';
+/** Cheap headline rollup, so a consumer can show totals without folding `events`. */
+export interface TraceSummary {
+    readonly tokens: {
+        readonly input: number;
+        readonly output: number;
+    };
+    readonly llmCalls: number;
+    readonly toolCalls: number;
+    readonly durationMs?: number;
+}
+/**
+ * A JSON-lossless, UI-free snapshot of one run. Persist it, ship it, replay it.
+ * `events` ARE the run (the graph is a derived projection, rebuilt at render).
+ */
+export interface Trace {
+    /** Schema version. Bump on a breaking shape change. */
+    readonly version: 1;
+    /** The domain-event log — the whole timeline. Already redacted if `redact` ran. */
+    readonly events: readonly DomainEvent[];
+    /**
+     * The serialized STATIC chart structure (footprint.js `buildTimeStructure`).
+     * Design-time data (stage ids/names/types/edges) — UI-free. `<Replay>` rebuilds
+     * the flowchart from this and overlays `events`, so an offline replay matches
+     * the live `<Lens>` exactly. NOT runtime-redacted (it carries no user data; the
+     * `redact` function targets runtime events).
+     */
+    readonly structure?: unknown;
+    /** Optional headline totals. */
+    readonly summary?: TraceSummary;
+    /** Self-describing redaction state — travels with the trace. */
+    readonly redaction: TraceRedaction;
+    /** Wall-clock capture time, stamped by the caller (the engine has no clock here). */
+    readonly capturedAtMs?: number;
+}
+export interface SerializeTraceOptions {
+    /**
+     * Consumer redaction — runs once per domain event at the serialize boundary,
+     * so PII never enters the `Trace`. Return a scrubbed COPY (do not mutate the
+     * input — the live model still references it). Use `redactContent` for a
+     * ready-made redactor. When omitted, content is raw.
+     */
+    readonly redact?: (event: DomainEvent) => DomainEvent;
+    /** Override the `redaction` label. Defaults to `'pii'` when `redact` is given, else `'none'`. */
+    readonly redactionLabel?: TraceRedaction;
+    /** The serialized static chart (`getSpec().buildTimeStructure`) — for `<Replay>` to rebuild the flowchart. */
+    readonly structure?: unknown;
+    /** Optional precomputed headline rollup. */
+    readonly summary?: TraceSummary;
+    /** Wall-clock capture time. Pass `Date.now()` from the call site. */
+    readonly capturedAtMs?: number;
+}
+/**
+ * Ready-made redactor: replaces every content-bearing field with a marker,
+ * keeping structure/counts for a useful replay. Covers ALL `DomainEvent`
+ * content surfaces — pass it to `getTrace({ redact: redactContent })`.
+ *
+ * Returns a copy only when it changes something, so unaffected events stay
+ * referentially identical (cheap) and the caller's live model is never mutated.
+ */
+export declare function redactContent(event: DomainEvent): DomainEvent;
+/**
+ * Freeze a live run model into a `Trace`. Pure: pass the `BoundaryRecorder`'s
+ * `getEvents()` output.
+ *
+ *   const trace = serializeTrace(handle.boundary.getEvents(), {
+ *     redact: redactContent,         // PII stripped before it enters the trace
+ *     capturedAtMs: Date.now(),
+ *   });
+ *   fs.writeFileSync('run.trace.json', JSON.stringify(trace));
+ */
+export declare function serializeTrace(events: readonly DomainEvent[], options?: SerializeTraceOptions): Trace;
+/**
+ * Rebuild the step graph from a `Trace` — the offline half of replay. The graph
+ * is ALWAYS a derived projection of `trace.events`; because those events were
+ * already redacted at serialize time, the rebuilt graph is clean too (no extra
+ * redaction needed — that's exactly why the graph is never stored). UI-free:
+ * `agentfootprint-lens`'s `<Replay>` translates this `StepGraph` into its
+ * xyflow render model.
+ */
+export declare function traceToStepGraph(trace: Trace): StepGraph;

package/dist/esm/reliability/CircuitBreaker.d.ts

@@ -0,0 +1,75 @@
+/**
+ * CircuitBreaker — pure state-machine functions for the Nygard breaker
+ * pattern.
+ *
+ * Refactored from a class-with-instance-state to PURE FUNCTIONS that
+ * take a state record and return a new one. Reasons:
+ *
+ *   1. **No hidden runtime state.** Breaker state lives in scope where
+ *      it's visible to commitLog, narrative, and rules — the footprintjs
+ *      "everything in scope" principle. The closure used to be the
+ *      source of truth and scope held only a projection; now scope IS
+ *      the source of truth.
+ *
+ *   2. **Round-trippable across gate invocations.** Because state is a
+ *      plain record, gate's outputMapper writes it back to agent scope;
+ *      agent scope persists across the ReAct loop's many LLM-call gate
+ *      invocations; gate's inputMapper reads it back in for the next
+ *      call. Per-process persistence comes from the agent scope, not
+ *      from a closure that hides between runs.
+ *
+ *   3. **Distributable later.** A future v2.12 `BreakerStateStore`
+ *      adapter (Redis/DynamoDB) just needs to serialize/deserialize the
+ *      state record. No class instances to reconstruct.
+ *
+ *   4. **Testable in isolation.** Pure functions; no instance setup.
+ *
+ * Pattern: Nygard *Release It!* — three states (CLOSED → OPEN →
+ *          HALF-OPEN) with cooldown and probe-success thresholds.
+ */
+import type { CircuitBreakerConfig } from './types.js';
+export type CircuitState = 'closed' | 'open' | 'half-open';
+/** Plain serializable record holding one breaker's full state. */
+export interface BreakerState {
+    state: CircuitState;
+    consecutiveFailures: number;
+    consecutiveSuccesses: number;
+    openedAt: number;
+    lastErrorMessage?: string;
+}
+/**
+ * Thrown by `assertAdmit()` when the breaker is OPEN and the cooldown
+ * window has not elapsed. The reliability gate stage catches this,
+ * classifies via `classifyError` → `'circuit-open'`, and lets the
+ * post-decide rules route on it.
+ */
+export declare class CircuitOpenError extends Error {
+    readonly code: "ERR_CIRCUIT_OPEN";
+    readonly cause: unknown;
+    readonly retryAfter: number;
+    constructor(providerName: string, lastErrorMessage: string | undefined, retryAfter: number);
+}
+/** Initial state for a freshly-CLOSED breaker. */
+export declare function initialBreakerState(): BreakerState;
+/**
+ * Decide whether to admit a call. Returns the (possibly-updated) state
+ * AND whether to admit. If OPEN and cooldown elapsed, transitions to
+ * HALF-OPEN and admits. Pure: caller must use the returned state.
+ *
+ * Usage in the gate stage:
+ * ```ts
+ * const { admitted, nextState } = admitCall(scope.breakerStates[name], config);
+ * scope.breakerStates[name] = nextState;
+ * if (!admitted) throw new CircuitOpenError(name, nextState.lastErrorMessage, ...);
+ * ```
+ */
+export declare function admitCall(state: BreakerState, config: CircuitBreakerConfig | undefined): {
+    admitted: boolean;
+    nextState: BreakerState;
+};
+/** Record a successful call. Returns the (possibly-updated) state. */
+export declare function recordSuccess(state: BreakerState, config: CircuitBreakerConfig | undefined): BreakerState;
+/** Record a failed call. Returns the (possibly-updated) state. */
+export declare function recordFailure(state: BreakerState, err: unknown, config: CircuitBreakerConfig | undefined): BreakerState;
+/** Compute the next probe time given a state + config. */
+export declare function nextProbeTime(state: BreakerState, config: CircuitBreakerConfig | undefined): number;

package/dist/esm/reliability/buildReliabilityGateChart.d.ts

@@ -0,0 +1,53 @@
+/**
+ * buildReliabilityGateChart — produces a footprintjs FlowChart that wraps
+ * an LLM call with rules-based reliability semantics, using the native
+ * `decide()` DSL via `addDeciderFunction` decider stages.
+ *
+ * The returned chart is mounted as a subflow in the agent's chart at
+ * Agent.build() time (only when reliability is configured). Inside the
+ * subflow:
+ *
+ *   PreCheck (decider) → CallProvider (function) → PostDecide (decider)
+ *                                                       │
+ *                                       ┌───────────────┘
+ *                                       ▼ loopTo('pre-check')
+ *
+ * Branch outcomes (escape via $break() to stop the gate's loop;
+ * fall-through via no-$break to trigger loopTo back to PreCheck):
+ *
+ *   PreCheck:
+ *     'continue'   → no-op   → falls through to CallProvider
+ *     'fail-fast'  → set failKind, $emit, $break(reason)
+ *
+ *   PostDecide:
+ *     'ok'          → $break() (subflow exits normally; agent continues)
+ *     'retry'       → bump attempt; falls through to loopTo
+ *     'retry-other' → bump providerIdx; falls through to loopTo
+ *     'fallback'    → call config.fallback(); $break() on success
+ *     'fail-fast'   → set failKind, $emit, $break(reason)
+ *
+ * The subflow is mounted WITHOUT `propagateBreak: true`. Subflow $break is
+ * local — agent.ts adds a `TranslateFailFast` agent-level stage AFTER the
+ * subflow that reads scope.reliabilityFailKind and converts it into an
+ * agent-level `$break(reason)`. This split lets normal subflow exits
+ * (`ok`/`fallback`) leave the agent running while fail-fast stops it.
+ *
+ * Three-channel discipline preserved:
+ *   • SCOPE STATE  — failKind/failPayload/failReason mapped to parent via
+ *                    outputMapper; consumed by agent's TranslateFailFast.
+ *   • $emit        — passive observability for external consumers.
+ *   • $break(reason)— control flow + human reason for narrative.
+ */
+import type { FlowChart } from 'footprintjs';
+import type { ReliabilityConfig } from './types.js';
+/**
+ * Build the reliability gate FlowChart from a config. Mount via
+ * `addSubFlowChartNext` in the agent's chart — see `Agent.build()`.
+ *
+ * Closure state captured by stage functions:
+ *   • `breakers` — Map<providerName, CircuitBreaker>; per-instance state
+ *     persists across gate invocations within ONE agent process.
+ *   • `preRules` / `postRules` — frozen rule arrays.
+ *   • `fallbackFn` — consumer's fallback function, if configured.
+ */
+export declare function buildReliabilityGateChart(config: ReliabilityConfig): FlowChart;

package/dist/esm/reliability/classifyError.d.ts

@@ -0,0 +1,28 @@
+/**
+ * classifyError — pure function mapping a thrown error to one of the
+ * coarse `ReliabilityScope.errorKind` categories used by reliability rules.
+ *
+ * Centralized so rules read structured `errorKind` instead of doing
+ * regex on `error.message` themselves. Add new categories ONLY when a
+ * new rule needs to discriminate them — keep the taxonomy small.
+ *
+ * Categories:
+ *   • 'ok'             — no error (caller should pass `undefined` or omit)
+ *   • 'circuit-open'   — `CircuitOpenError` from the breaker layer
+ *   • 'rate-limit'     — HTTP 429 or vendor rate-limit signal
+ *   • '5xx-transient'  — HTTP 5xx, ETIMEDOUT, ECONNRESET, ECONNREFUSED
+ *   • 'schema-fail'    — `OutputSchemaError` from the schema validator
+ *   • 'unknown'        — anything else (default; still routable but
+ *                        consumers usually `'fail-fast'` on this)
+ */
+import type { ReliabilityScope } from './types.js';
+type ErrorKind = ReliabilityScope['errorKind'];
+/**
+ * Classify an error into a `ReliabilityScope['errorKind']` category.
+ *
+ * @param err - The thrown value. May be an Error, a vendor SDK error
+ *   shape with `.status`/`.code`, or anything else (`unknown` defaults).
+ * @returns the matching coarse category string.
+ */
+export declare function classifyError(err: unknown): ErrorKind;
+export {};

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

@@ -0,0 +1,35 @@
+/**
+ * Reliability — public surface for the v2.11.1 rules-based reliability
+ * subsystem. Internal-only helpers (CircuitBreaker class, classifyError,
+ * buildReliabilityGate) live in their own files; this barrel exports
+ * the consumer-facing types and the typed error.
+ *
+ * Consumer use:
+ * ```ts
+ * import { Agent } from 'agentfootprint';
+ * import type { ReliabilityRule, ReliabilityScope } from 'agentfootprint/reliability';
+ * import { ReliabilityFailFastError } from 'agentfootprint/reliability';
+ *
+ * const agent = Agent.create({...}).reliability({
+ *   postDecide: [
+ *     { when: (s) => s.errorKind === '5xx-transient' && s.attempt < 3,
+ *       then: 'retry', kind: 'transient-retry' },
+ *     { when: (s) => s.error !== undefined,
+ *       then: 'fail-fast', kind: 'unrecoverable' },
+ *   ],
+ * }).build();
+ *
+ * try {
+ *   await agent.run({ message: '...' });
+ * } catch (e) {
+ *   if (e instanceof ReliabilityFailFastError) {
+ *     console.log(e.kind, e.reason);
+ *   }
+ * }
+ * ```
+ */
+export type { CircuitBreakerConfig, ReliabilityConfig, ReliabilityDecision, ReliabilityFallbackFn, ReliabilityProvider, ReliabilityRule, ReliabilityScope, } from './types.js';
+export { ReliabilityFailFastError } from './types.js';
+export { CircuitOpenError, initialBreakerState, type BreakerState, type CircuitState, } from './CircuitBreaker.js';
+export { ValidationFailure, lastNValidationErrorsMatch, defaultStuckLoopRule, } from '../core/agent/stages/reliabilityExecution.js';
+export type { OutputSchemaValidator } from '../core/agent/stages/reliabilityExecution.js';