agentfootprint 2.8.3 → 2.10.0

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

@@ -18,4 +18,5 @@
 export { withRetry, type WithRetryOptions } from './withRetry.js';
 export { withFallback, type WithFallbackOptions } from './withFallback.js';
 export { fallbackProvider, type FallbackProviderOptions } from './fallbackProvider.js';
+export { withCircuitBreaker, CircuitOpenError, type WithCircuitBreakerOptions, type CircuitState, } from './withCircuitBreaker.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/resilience/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAC3E,OAAO,EAAE,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/resilience/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAC3E,OAAO,EAAE,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AACvF,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,KAAK,yBAAyB,EAC9B,KAAK,YAAY,GAClB,MAAM,yBAAyB,CAAC"}

package/dist/types/resilience/withCircuitBreaker.d.ts

@@ -0,0 +1,104 @@
+/**
+ * withCircuitBreaker — provider decorator that fails fast after N
+ * consecutive failures.
+ *
+ * Pattern: Circuit Breaker (Nygard, *Release It!*) — wraps an
+ *          `LLMProvider` and tracks consecutive failures. After
+ *          `failureThreshold` failures, the breaker OPENS and
+ *          rejects all calls without invoking the wrapped provider.
+ *          After `cooldownMs`, the breaker enters HALF-OPEN and
+ *          allows probe calls; success closes the breaker, failure
+ *          re-opens it.
+ *
+ * Role:    Outer ring (Hexagonal). Composes with `withRetry` and
+ *          `withFallback`:
+ *
+ *          ```
+ *          withFallback(
+ *            withCircuitBreaker(anthropic(...)),  // ← stop hammering on outage
+ *            withCircuitBreaker(openai(...)),
+ *          )
+ *          ```
+ *
+ *          When Anthropic 503s for the 5th time, the breaker opens
+ *          and `complete()` throws `CircuitOpenError` immediately —
+ *          no network round-trip — which `withFallback` then
+ *          catches and routes to OpenAI. After 30 seconds the
+ *          breaker probes Anthropic with a single call; if it
+ *          succeeds, normal operation resumes.
+ *
+ * Why a circuit breaker on top of `withRetry`?
+ *   - `withRetry` keeps hammering one provider with exponential
+ *     backoff — it doesn't know the vendor is down.
+ *   - During a multi-minute Anthropic outage, every request still
+ *     burns 3 retries + backoff = ~3 sec of latency before failing
+ *     to the fallback. Multiplied by your QPS, that's a lot of
+ *     wasted time + tokens (some retries DO get billed).
+ *   - The breaker says: "we just saw 5 failures in a row; stop
+ *     calling for 30 seconds." Subsequent requests fail in <1ms,
+ *     `withFallback` routes immediately to OpenAI.
+ *
+ * Three states:
+ *
+ *     CLOSED ──[ N consecutive failures ]──► OPEN
+ *        ▲                                    │
+ *        │                                    │ [cooldownMs elapsed]
+ *        │                                    ▼
+ *        └──[ M probe successes ]──── HALF-OPEN
+ *
+ *     HALF-OPEN ──[ probe failure ]──► OPEN (cooldown restarts)
+ *
+ * `stream()` is decorated identically. `name`/`flush`/`stop` pass
+ * through unchanged (the consumer's existing observability hooks
+ * still see the underlying provider's identity).
+ */
+import type { LLMProvider } from '../adapters/types.js';
+export interface WithCircuitBreakerOptions {
+    /** Consecutive failures before the breaker OPENS. Default 5. */
+    readonly failureThreshold?: number;
+    /** How long the breaker stays OPEN before probing. Default 30s. */
+    readonly cooldownMs?: number;
+    /** Successes required in HALF-OPEN to fully CLOSE. Default 2. */
+    readonly halfOpenSuccessThreshold?: number;
+    /**
+     * Predicate — does this error count toward the threshold? Default:
+     * everything except AbortError counts. Override to ignore client
+     * errors (e.g., 4xx) so a malformed request doesn't trip the
+     * breaker for everyone.
+     */
+    readonly shouldCount?: (error: unknown) => boolean;
+    /** Hook invoked on every state transition. Useful for emitting
+     *  `agentfootprint.resilience.circuit_state_changed`. */
+    readonly onStateChange?: (state: CircuitState, reason: string) => void;
+}
+export type CircuitState = 'closed' | 'open' | 'half-open';
+/**
+ * Thrown by the wrapped provider when the breaker is OPEN. Carries
+ * the underlying root-cause error from the most recent failure so
+ * consumers can observe what tripped the breaker.
+ */
+export declare class CircuitOpenError extends Error {
+    readonly code: "ERR_CIRCUIT_OPEN";
+    /** The error that tripped the breaker (or the most recent failure
+     *  during HALF-OPEN that re-opened it). */
+    readonly cause: unknown;
+    /** Wall-clock timestamp at which the breaker may next probe. */
+    readonly retryAfter: number;
+    constructor(providerName: string, cause: unknown, retryAfter: number);
+}
+/**
+ * Wrap a provider with a circuit breaker.
+ *
+ * @example
+ * ```ts
+ * import { anthropic, openai } from 'agentfootprint/llm-providers';
+ * import { withCircuitBreaker, withFallback } from 'agentfootprint/resilience';
+ *
+ * const provider = withFallback(
+ *   withCircuitBreaker(anthropic({ apiKey }), { failureThreshold: 5, cooldownMs: 30_000 }),
+ *   withCircuitBreaker(openai({ apiKey })),
+ * );
+ * ```
+ */
+export declare function withCircuitBreaker(inner: LLMProvider, options?: WithCircuitBreakerOptions): LLMProvider;
+//# sourceMappingURL=withCircuitBreaker.d.ts.map

package/dist/types/resilience/withCircuitBreaker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"withCircuitBreaker.d.ts","sourceRoot":"","sources":["../../../src/resilience/withCircuitBreaker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH,OAAO,KAAK,EAAY,WAAW,EAA2B,MAAM,sBAAsB,CAAC;AAI3F,MAAM,WAAW,yBAAyB;IACxC,gEAAgE;IAChE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,mEAAmE;IACnE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,iEAAiE;IACjE,QAAQ,CAAC,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAC3C;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;IACnD;6DACyD;IACzD,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CACxE;AAED,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAI3D;;;;GAIG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,IAAI,qBAA+B;IAC5C;+CAC2C;IAC3C,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,gEAAgE;IAChE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAChB,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM;CAYrE;AAYD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,WAAW,EAClB,OAAO,GAAE,yBAA8B,GACtC,WAAW,CAsHb"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentfootprint",
-  "version": "2.8.3",
+  "version": "2.10.0",
   "description": "The explainable agent framework — build AI agents you can explain, audit, and trust. Built on footprintjs.",
   "license": "MIT",
   "author": "Sanjay Krishna Anbalagan",
@@ -173,6 +173,7 @@
     "@aws-sdk/client-cloudwatch-logs": "*",
     "@aws-sdk/client-xray": "*",
     "@modelcontextprotocol/sdk": "*",
+    "@opentelemetry/api": "*",
     "footprintjs": ">=4.17.1",
     "ioredis": "*",
     "openai": "*",
@@ -200,6 +201,9 @@
     "@modelcontextprotocol/sdk": {
       "optional": true
     },
+    "@opentelemetry/api": {
+      "optional": true
+    },
     "ioredis": {
       "optional": true
     },