agentfootprint 2.11.0 → 2.11.1

package/dist/reliability/index.js

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * 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);
+ *   }
+ * }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initialBreakerState = exports.CircuitOpenError = exports.ReliabilityFailFastError = void 0;
+var types_js_1 = require("./types.js");
+Object.defineProperty(exports, "ReliabilityFailFastError", { enumerable: true, get: function () { return types_js_1.ReliabilityFailFastError; } });
+// CircuitBreaker pure-state-machine surface — exposed so consumers can
+// hydrate breaker state from a persistence store (Redis/DynamoDB) or
+// inspect projected state in their own observability adapters.
+var CircuitBreaker_js_1 = require("./CircuitBreaker.js");
+Object.defineProperty(exports, "CircuitOpenError", { enumerable: true, get: function () { return CircuitBreaker_js_1.CircuitOpenError; } });
+Object.defineProperty(exports, "initialBreakerState", { enumerable: true, get: function () { return CircuitBreaker_js_1.initialBreakerState; } });
+//# sourceMappingURL=index.js.map

package/dist/reliability/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/reliability/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;;;AAYH,uCAAsD;AAA7C,oHAAA,wBAAwB,OAAA;AAEjC,uEAAuE;AACvE,qEAAqE;AACrE,+DAA+D;AAC/D,yDAK6B;AAJ3B,qHAAA,gBAAgB,OAAA;AAChB,wHAAA,mBAAmB,OAAA"}

package/dist/reliability/types.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReliabilityFailFastError = void 0;
+// ─── Public typed error ──────────────────────────────────────────────
+/**
+ * Thrown by `Agent.run()` when a reliability rule routes to `'fail-fast'`
+ * and the gate $breaks with a reason. Carries:
+ *
+ *   • `kind`     — machine-readable identifier from the matched rule's
+ *                  `kind` field. Stable across versions; consumers
+ *                  branch on this.
+ *   • `reason`   — human-readable narrative string from `$break(reason)`.
+ *                  Format: `'reliability-{phase}: {label}'` (e.g.,
+ *                  `'reliability-post-decide: cost-cap-exceeded'`).
+ *   • `cause`    — the originating error from the LLM call, when one
+ *                  drove the fail-fast decision (e.g., the underlying
+ *                  HTTP error that tripped a circuit breaker).
+ *   • `snapshot` — the full `executor.getSnapshot()` at fail-fast time
+ *                  for forensics. Consumers persist this for postmortem
+ *                  analysis (commitLog, narrative, scope state, etc.).
+ *
+ * Three-channel discipline: `kind`/`payload` came from scope state,
+ * `reason` came from $break, `snapshot` is the engine's own audit trail.
+ * Emit events flowed independently to any attached observability adapter
+ * (this error is the RUNTIME signal; emit is the OBSERVABILITY signal).
+ */
+class ReliabilityFailFastError extends Error {
+    code = 'ERR_RELIABILITY_FAIL_FAST';
+    kind;
+    reason;
+    cause;
+    snapshot;
+    payload;
+    constructor(opts) {
+        super(`[reliability] ${opts.kind}: ${opts.reason}`);
+        this.name = 'ReliabilityFailFastError';
+        this.kind = opts.kind;
+        this.reason = opts.reason;
+        if (opts.cause !== undefined)
+            this.cause = opts.cause;
+        if (opts.snapshot !== undefined)
+            this.snapshot = opts.snapshot;
+        if (opts.payload !== undefined)
+            this.payload = opts.payload;
+    }
+}
+exports.ReliabilityFailFastError = ReliabilityFailFastError;
+//# sourceMappingURL=types.js.map

package/dist/reliability/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/reliability/types.ts"],"names":[],"mappings":";;;AA2QA,wEAAwE;AAExE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAa,wBAAyB,SAAQ,KAAK;IACxC,IAAI,GAAG,2BAAoC,CAAC;IAC5C,IAAI,CAAS;IACb,MAAM,CAAS;IACf,KAAK,CAAS;IACd,QAAQ,CAAW;IACnB,OAAO,CAAmC;IAEnD,YAAY,IAMX;QACC,KAAK,CAAC,iBAAiB,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;QACpD,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;QACvC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS;YAAE,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACtD,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS;YAAE,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC/D,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS;YAAE,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;IAC9D,CAAC;CACF;AAvBD,4DAuBC"}

package/dist/types/core/Agent.d.ts

@@ -16,8 +16,6 @@
 import { type CombinedNarrativeEntry, type FlowChart, type FlowchartCheckpoint, type RunOptions, type RuntimeSnapshot } from 'footprintjs';
 import type { CachePolicy, CacheStrategy } from '../cache/types.js';
 import { type RunnerPauseOutcome } from './pause.js';
-import type { LLMProvider, PermissionChecker, PricingTable } from '../adapters/types.js';
-import type { MemoryIdentity } from '../memory/identity/index.js';
 import type { MemoryDefinition } from '../memory/define.types.js';
 import type { Injection } from '../lib/injection-engine/types.js';
 import { type OutputFallbackOptions, type ResolvedOutputFallback } from './outputFallback.js';
@@ -26,71 +24,8 @@ import { type OutputSchemaOptions, type OutputSchemaParser } from './outputSchem
 import { RunnerBase } from './RunnerBase.js';
 import type { Tool, ToolRegistryEntry } from './tools.js';
 import type { ToolProvider } from '../tool-providers/types.js';
-export interface AgentOptions {
-    readonly provider: LLMProvider;
-    /** Human-friendly name shown in events/metrics. Default: 'Agent'. */
-    readonly name?: string;
-    /** Stable id used for topology + events. Default: 'agent'. */
-    readonly id?: string;
-    readonly model: string;
-    readonly temperature?: number;
-    readonly maxTokens?: number;
-    /** Hard budget on ReAct iterations. Default: 10. Hard cap: 50. */
-    readonly maxIterations?: number;
-    /**
-     * Pricing adapter. When set, Agent emits `agentfootprint.cost.tick`
-     * after every LLM response (once per ReAct iteration) with per-call
-     * and cumulative USD. Run-scoped — the cumulative resets each `.run()`.
-     */
-    readonly pricingTable?: PricingTable;
-    /**
-     * Cumulative USD budget per run. With `pricingTable`, Agent emits a
-     * one-shot `agentfootprint.cost.limit_hit` (`action: 'warn'`) when
-     * cumulative USD crosses this budget. Execution continues — consumers
-     * choose whether to abort by listening to the event.
-     */
-    readonly costBudget?: number;
-    /**
-     * Permission adapter. When set, the Agent calls
-     * `permissionChecker.check({capability: 'tool_call', ...})` BEFORE every
-     * `tool.execute()`. Emits `agentfootprint.permission.check` with the
-     * decision. On `deny`, the tool is skipped and its result is a
-     * synthetic denial string; on `allow` / `gate_open`, execution proceeds
-     * normally.
-     */
-    readonly permissionChecker?: PermissionChecker;
-    /**
-     * Global cache kill switch (v2.6+). `'off'` disables the cache
-     * layer entirely — the CacheGate decider routes to `'no-markers'`
-     * every iteration regardless of other rules. Default: caching
-     * enabled (auto-resolved per provider via the strategy registry).
-     *
-     * Use `'off'` for low-frequency agents (cron jobs running once per
-     * hour) where the cache TTL guarantees zero cache hits and the
-     * cache-write penalty isn't worth paying.
-     */
-    readonly caching?: 'off';
-    /**
-     * Optional explicit CacheStrategy override (v2.6+). Defaults to
-     * `getDefaultCacheStrategy(provider.name)` — so Anthropic/OpenAI/
-     * Bedrock/Mock providers auto-resolve to their respective strategies
-     * once those land in Phase 7+.
-     */
-    readonly cacheStrategy?: CacheStrategy;
-}
-export interface AgentInput {
-    readonly message: string;
-    /**
-     * Multi-tenant memory scope. Populated to `scope.identity` so memory
-     * subflows registered via `.memory()` can isolate reads/writes per
-     * tenant + principal + conversation.
-     *
-     * Defaults to `{ conversationId: '<runId>' }` when omitted, so agents
-     * without memory work unchanged.
-     */
-    readonly identity?: MemoryIdentity;
-}
-export type AgentOutput = string;
+import type { AgentInput, AgentOptions, AgentOutput } from './agent/types.js';
+export type { AgentInput, AgentOptions, AgentOutput };
 export declare class Agent extends RunnerBase<AgentInput, AgentOutput> {
     readonly name: string;
     readonly id: string;

package/dist/types/core/Agent.d.ts.map

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

package/dist/types/core/agent/types.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Agent type definitions — both PUBLIC types (AgentOptions, AgentInput,
+ * AgentOutput) consumed by `Agent.create({...}).run({...})` callers AND
+ * the INTERNAL `AgentState` shape used by stage functions.
+ *
+ * These were originally inline in `core/Agent.ts`; extracted here as
+ * part of the v2.11.1 decomposition. `core/Agent.ts` re-exports them
+ * for back-compat (the 28+ existing import sites continue to work).
+ */
+import type { LLMMessage, LLMProvider, LLMToolSchema, PermissionChecker, PricingTable } from '../../adapters/types.js';
+import type { CacheMarker, CacheStrategy } from '../../cache/types.js';
+import type { ActiveInjection } from '../../lib/injection-engine/types.js';
+import type { InjectionRecord } from '../../recorders/core/types.js';
+import type { MemoryIdentity } from '../../memory/identity/types.js';
+export interface AgentOptions {
+    readonly provider: LLMProvider;
+    /** Human-friendly name shown in events/metrics. Default: 'Agent'. */
+    readonly name?: string;
+    /** Stable id used for topology + events. Default: 'agent'. */
+    readonly id?: string;
+    readonly model: string;
+    readonly temperature?: number;
+    readonly maxTokens?: number;
+    /** Hard budget on ReAct iterations. Default: 10. Hard cap: 50. */
+    readonly maxIterations?: number;
+    /**
+     * Pricing adapter. When set, Agent emits `agentfootprint.cost.tick`
+     * after every LLM response (once per ReAct iteration) with per-call
+     * and cumulative USD. Run-scoped — the cumulative resets each `.run()`.
+     */
+    readonly pricingTable?: PricingTable;
+    /**
+     * Cumulative USD budget per run. With `pricingTable`, Agent emits a
+     * one-shot `agentfootprint.cost.limit_hit` (`action: 'warn'`) when
+     * cumulative USD crosses this budget. Execution continues — consumers
+     * choose whether to abort by listening to the event.
+     */
+    readonly costBudget?: number;
+    /**
+     * Permission adapter. When set, the Agent calls
+     * `permissionChecker.check({capability: 'tool_call', ...})` BEFORE every
+     * `tool.execute()`. Emits `agentfootprint.permission.check` with the
+     * decision. On `deny`, the tool is skipped and its result is a
+     * synthetic denial string; on `allow` / `gate_open`, execution proceeds
+     * normally.
+     */
+    readonly permissionChecker?: PermissionChecker;
+    /**
+     * Global cache kill switch (v2.6+). `'off'` disables the cache
+     * layer entirely — the CacheGate decider routes to `'no-markers'`
+     * every iteration regardless of other rules. Default: caching
+     * enabled (auto-resolved per provider via the strategy registry).
+     *
+     * Use `'off'` for low-frequency agents (cron jobs running once per
+     * hour) where the cache TTL guarantees zero cache hits and the
+     * cache-write penalty isn't worth paying.
+     */
+    readonly caching?: 'off';
+    /**
+     * Optional explicit CacheStrategy override (v2.6+). Defaults to
+     * `getDefaultCacheStrategy(provider.name)` — so Anthropic/OpenAI/
+     * Bedrock/Mock providers auto-resolve to their respective strategies
+     * once those land in Phase 7+.
+     */
+    readonly cacheStrategy?: CacheStrategy;
+}
+export interface AgentInput {
+    readonly message: string;
+    /**
+     * Multi-tenant memory scope. Populated to `scope.identity` so memory
+     * subflows registered via `.memory()` can isolate reads/writes per
+     * tenant + principal + conversation.
+     *
+     * Defaults to `{ conversationId: '<runId>' }` when omitted, so agents
+     * without memory work unchanged.
+     */
+    readonly identity?: MemoryIdentity;
+}
+export type AgentOutput = string;
+/**
+ * Internal scope state for the Agent's flowchart. Recorders never read
+ * this directly — they read the InjectionRecord convention keys + emit
+ * events. Each stage function under `./stages/` receives a TypedScope
+ * over this shape and reads/writes via typed properties.
+ *
+ * Mutability conventions (followed by every Agent stage):
+ *   • Per-iteration scalars (iteration, finalContent, llmLatestContent,
+ *     etc.) are OVERWRITTEN each pass; commitLog preserves history.
+ *   • Cumulative scalars (cumTokensInput, totalInputTokens, turnNumber)
+ *     accumulate monotonically across the run.
+ *   • Arrays from slot subflows (systemPromptInjections,
+ *     messagesInjections, toolsInjections, dynamicToolSchemas,
+ *     cacheMarkers) use `arrayMerge: ArrayMergeMode.Replace` semantics —
+ *     each iteration's value REPLACES the prior iteration's, not
+ *     appends.
+ */
+export interface AgentState {
+    userMessage: string;
+    history: readonly LLMMessage[];
+    iteration: number;
+    maxIterations: number;
+    finalContent: string;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    turnStartMs: number;
+    runIdentity: MemoryIdentity;
+    newMessages: readonly LLMMessage[];
+    turnNumber: number;
+    contextTokensRemaining: number;
+    systemPromptInjections: readonly InjectionRecord[];
+    messagesInjections: readonly InjectionRecord[];
+    toolsInjections: readonly InjectionRecord[];
+    llmLatestContent: string;
+    llmLatestToolCalls: readonly {
+        readonly id: string;
+        readonly name: string;
+        readonly args: Readonly<Record<string, unknown>>;
+    }[];
+    pausedToolCallId: string;
+    pausedToolName: string;
+    pausedToolStartMs: number;
+    cumTokensInput: number;
+    cumTokensOutput: number;
+    cumEstimatedUsd: number;
+    costBudgetHit: boolean;
+    /** Active set output by InjectionEngine subflow each iteration —
+     *  POJO projections (no functions) suitable for scope round-trip. */
+    activeInjections: readonly ActiveInjection[];
+    /** IDs of LLM-activated Skills the LLM has activated this turn
+     *  (via the `read_skill` tool). InjectionEngine matches by id. */
+    activatedInjectionIds: readonly string[];
+    /** Most recent tool result — drives `on-tool-return` triggers. */
+    lastToolResult?: {
+        toolName: string;
+        result: string;
+    };
+    /** Tool schemas resolved by the tools slot subflow each iteration
+     *  (registry + injection-supplied). Used by callLLM. */
+    dynamicToolSchemas: readonly LLMToolSchema[];
+    /** Provider-agnostic cache markers emitted by CacheDecision subflow.
+     *  Cleared each iteration by the SkipCaching branch when the
+     *  CacheGate decides to skip (kill switch / hit-rate / churn). */
+    cacheMarkers: readonly CacheMarker[];
+    /** Global cache kill switch from `Agent.create({ caching: 'off' })`. */
+    cachingDisabled: boolean;
+    /** Running cache hit rate from recent iterations (0..1). Computed
+     *  by cacheRecorder (Phase 9); `undefined` until first metrics. */
+    recentHitRate: number | undefined;
+    /** Rolling window of active-skill IDs across recent iterations.
+     *  Maintained by the UpdateSkillHistory function stage; consumed
+     *  by CacheGate's skill-churn rule. */
+    skillHistory: readonly (string | undefined)[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types/core/agent/types.d.ts.map

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

package/dist/types/core/agent/validators.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Agent validators — pure helper functions extracted from Agent.ts.
+ *
+ * These run at Agent construction time (eagerly, so misconfiguration
+ * fails fast at `.build()`) and during stage execution (safeStringify
+ * for tool-result formatting).
+ *
+ * Pure functions, no class state — extracted for readability and
+ * isolated testability. The Agent class imports + invokes these in
+ * its constructor and stage handlers.
+ */
+import type { MemoryDefinition } from '../../memory/define.types.js';
+import type { Injection } from '../../lib/injection-engine/types.js';
+import type { ToolRegistryEntry } from '../tools.js';
+/**
+ * Validate that every memory definition has a unique id. Each memory
+ * writes to its own scope key (`memoryInjection_${id}`); duplicates
+ * silently overwrite, leading to data loss that's hard to debug.
+ *
+ * Throws on collision so `Agent.build()` fails fast at construction.
+ */
+export declare function validateMemoryIdUniqueness(memories: readonly MemoryDefinition[]): void;
+/**
+ * Clamp `maxIterations` to a safe range. The lower bound (1) prevents
+ * a 0-iteration agent (no LLM calls = no work); the upper bound (50)
+ * prevents runaway loops in misconfigured agents.
+ */
+export declare function clampIterations(n: number): number;
+/**
+ * Validate tool-name uniqueness across `.tool()`-registered tools +
+ * every Skill's `inject.tools[]`. The LLM dispatches by `tool.schema.name`
+ * (the wire format), so any collision silently shadows execution.
+ *
+ * Called eagerly in the Agent constructor so `Agent.build()` throws
+ * immediately, not on first `run()`.
+ *
+ * `read_skill` is reserved when ≥1 Skill is registered — collisions
+ * with consumer tools throw.
+ */
+export declare function validateToolNameUniqueness(registry: readonly ToolRegistryEntry[], injections: readonly Injection[]): void;
+/**
+ * JSON.stringify with circular-ref protection. Tool results are untrusted —
+ * a hostile/buggy tool returning a cyclic object must not crash the run.
+ * Falls back to '[unstringifiable: <reason>]' so the LLM still sees that
+ * the tool ran and produced something unusable.
+ */
+export declare function safeStringify(value: unknown): string;
+//# sourceMappingURL=validators.d.ts.map

package/dist/types/core/agent/validators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../../../../src/core/agent/validators.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qCAAqC,CAAC;AACrE,OAAO,KAAK,EAAQ,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAE3D;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,GAAG,IAAI,CAWtF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAIjD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,EACtC,UAAU,EAAE,SAAS,SAAS,EAAE,GAC/B,IAAI,CAoEN;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAOpD"}

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

@@ -0,0 +1,76 @@
+/**
+ * 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;
+//# sourceMappingURL=CircuitBreaker.d.ts.map

package/dist/types/reliability/CircuitBreaker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CircuitBreaker.d.ts","sourceRoot":"","sources":["../../../src/reliability/CircuitBreaker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEvD,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAE3D,kEAAkE;AAClE,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,YAAY,CAAC;IACpB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,oBAAoB,EAAE,MAAM,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;GAKG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,IAAI,qBAA+B;IAC5C,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAChB,YAAY,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,SAAS,EAAE,UAAU,EAAE,MAAM;CAU3F;AAkBD,kDAAkD;AAClD,wBAAgB,mBAAmB,IAAI,YAAY,CAOlD;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,YAAY,EACnB,MAAM,EAAE,oBAAoB,GAAG,SAAS,GACvC;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,YAAY,CAAA;CAAE,CAchD;AAED,sEAAsE;AACtE,wBAAgB,aAAa,CAC3B,KAAK,EAAE,YAAY,EACnB,MAAM,EAAE,oBAAoB,GAAG,SAAS,GACvC,YAAY,CAsBd;AAED,kEAAkE;AAClE,wBAAgB,aAAa,CAC3B,KAAK,EAAE,YAAY,EACnB,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,oBAAoB,GAAG,SAAS,GACvC,YAAY,CAgCd;AAED,0DAA0D;AAC1D,wBAAgB,aAAa,CAC3B,KAAK,EAAE,YAAY,EACnB,MAAM,EAAE,oBAAoB,GAAG,SAAS,GACvC,MAAM,CAER"}

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

@@ -0,0 +1,54 @@
+/**
+ * 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;
+//# sourceMappingURL=buildReliabilityGateChart.d.ts.map

package/dist/types/reliability/buildReliabilityGateChart.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildReliabilityGateChart.d.ts","sourceRoot":"","sources":["../../../src/reliability/buildReliabilityGateChart.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,aAAa,CAAC;AAWzD,OAAO,KAAK,EAAE,iBAAiB,EAAqC,MAAM,YAAY,CAAC;AAkFvF;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,iBAAiB,GAAG,SAAS,CA4S9E"}

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

@@ -0,0 +1,29 @@
+/**
+ * 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 {};
+//# sourceMappingURL=classifyError.d.ts.map

package/dist/types/reliability/classifyError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"classifyError.d.ts","sourceRoot":"","sources":["../../../src/reliability/classifyError.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD,KAAK,SAAS,GAAG,gBAAgB,CAAC,WAAW,CAAC,CAAC;AAU/C;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,SAAS,CA8BrD"}

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

@@ -0,0 +1,34 @@
+/**
+ * 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';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/reliability/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/reliability/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,YAAY,EACV,oBAAoB,EACpB,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,EACrB,mBAAmB,EACnB,eAAe,EACf,gBAAgB,GACjB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAKtD,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,KAAK,YAAY,EACjB,KAAK,YAAY,GAClB,MAAM,qBAAqB,CAAC"}