agentfootprint 9.30.0 → 9.32.0

package/dist/esm/lib/mcp/gatewayTransport.d.ts

@@ -56,6 +56,58 @@ export interface GatewayTransportOptions {
      * life of the transport, which is what the vended ones exist to avoid.
      */
     readonly headers?: Readonly<Record<string, string>>;
+    /**
+     * Your own `fetch`, called UNDERNEATH the per-request vending (9.32.0).
+     *
+     * ── The gap this closes ──────────────────────────────────────────────────
+     * Some gateways do not authenticate with a bearer alone. A managed identity
+     * path may want a client certificate (mTLS) or a proof-of-possession
+     * signature over the request itself (DPoP) — things computed FROM the
+     * request, which no header fixed at construction can express. Until this
+     * existed the only workaround was to abandon this transport for the generic
+     * `http` one, which has a `fetch` seam and fixes its headers at connect
+     * time — so a caller traded away token rotation to get a client certificate.
+     * That is a bad trade, and it was the shape an independent field trial
+     * reported (2026-08-13): *"exposes bearer-credential, header and scope
+     * options, but no certificate, DPoP or custom-fetch seam."*
+     *
+     * ── The composition, and its order ───────────────────────────────────────
+     * The credential is vended FIRST and applied to the request; your function is
+     * then called with that request. So a signer sees the final headers and has
+     * the last word over the bytes, exactly as it does on the `http` transport —
+     * and the vending still happens on every request, so rotation is not lost.
+     *
+     * **Zero vendor code lives here.** This library ships no signer, no
+     * certificate loader and no DPoP implementation; a scheme this repo has never
+     * heard of works on the day you write it. Whatever you do inside is between
+     * you and the server.
+     *
+     * ── What the secrecy invariant still guarantees ──────────────────────────
+     * Your function sees the request it is asked to send, headers included —
+     * which is what makes signing possible and is the whole point of the seam.
+     * What is still true is everything this module controls: the vended value is
+     * never cached, never stored on the transport, and never enters an event, an
+     * error or a log. A `fetch` you inject that logs its own headers is
+     * publishing your credential, and that is your decision to make in your code
+     * rather than something this library can do behind you.
+     *
+     * @example  mTLS, through an agent you own
+     *   gatewayTransport({
+     *     url, credentials, service: 'gateway',
+     *     fetch: (input, init) => fetch(input, { ...init, dispatcher: mtlsAgent }),
+     *   })
+     *
+     * @example  Proof-of-possession over the request
+     *   gatewayTransport({
+     *     url, credentials,
+     *     fetch: async (input, init) => {
+     *       const headers = new Headers(init?.headers);
+     *       headers.set('dpop', await sign(init?.method ?? 'POST', String(input)));
+     *       return fetch(input, { ...init, headers });
+     *     },
+     *   })
+     */
+    readonly fetch?: FetchLike;
 }
 /**
  * Describe an MCP connection whose auth headers are vended per request.

package/dist/esm/lib/mcp/gatewayTransport.js

@@ -65,6 +65,7 @@ export function gatewayTransport(options) {
         ...(options.scopes !== undefined && { scopes: options.scopes }),
         ...(options.mode !== undefined && { mode: options.mode }),
         ...(options.headers !== undefined && { headers: options.headers }),
+        ...(options.fetch !== undefined && { fetch: options.fetch }),
     };
 }
 /**

package/dist/esm/lib/mcp/gatewayTransport.js.map

@@ -1 +1 @@
-{"version":3,"file":"gatewayTransport.js","sourceRoot":"","sources":["../../../../src/lib/mcp/gatewayTransport.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"gatewayTransport.js","sourceRoot":"","sources":["../../../../src/lib/mcp/gatewayTransport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAE,kBAAkB,EAA2B,MAAM,yBAAyB,CAAC;AA8EtF,MAAM,eAAe,GAAG,SAAS,CAAC;AAElC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAgC;IAC/D,IAAI,CAAC,OAAO,CAAC,GAAG;QAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;IACtE,IAAI,CAAC,OAAO,CAAC,WAAW;QAAE,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;IACtF,OAAO;QACL,SAAS,EAAE,SAAS;QACpB,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,eAAe;QAC3C,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;QAC/D,GAAG,CAAC,OAAO,CAAC,IAAI,KAAK,SAAS,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC;QACzD,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC;QAClE,GAAG,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;KAC7D,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,OAAO,iCAAkC,SAAQ,KAAK;IACjD,IAAI,GAAG,oCAA6C,CAAC;IAC9D,sCAAsC;IAC7B,gBAAgB,CAAS;IAElC,YAAY,OAAe,EAAE,gBAAwB;QACnD,KAAK,CACH,8DAA8D,OAAO,kBAAkB;YACrF,qFAAqF;YACrF,sFAAsF;YACtF,4BAA4B,CAC/B,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,mCAAmC,CAAC;QAChD,IAAI,CAAC,gBAAgB,GAAG,gBAAgB,CAAC;IAC3C,CAAC;CACF;AAKD;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAChC,SAA8B,EAC9B,YAAuB,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC;IAExD,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;QAC3B,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,WAAW,CAAC,aAAa,CAAC;YACvD,OAAO,EAAE,SAAS,CAAC,OAAO;YAC1B,GAAG,CAAC,SAAS,CAAC,MAAM,KAAK,SAAS,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,CAAC;YACnE,GAAG,CAAC,SAAS,CAAC,IAAI,KAAK,SAAS,IAAI,EAAE,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE,CAAC;SAC9D,CAAC,CAAC;QACH,IAAI,CAAC,kBAAkB,CAAC,MAAM,CAAC,EAAE,CAAC;YAChC,MAAM,IAAI,iCAAiC,CAAC,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC,gBAAgB,CAAC,CAAC;QAC1F,CAAC;QAED,4EAA4E;QAC5E,sEAAsE;QACtE,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,IAAI,EAAE,OAAO,IAAI,EAAE,CAAC,CAAC;QACjD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,OAAO,IAAI,EAAE,CAAC;YAAE,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC5F,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,SAAS,EAAE,CAAC,EAAE,CAAC;YACzE,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC1B,CAAC;QAED,yEAAyE;QACzE,kEAAkE;QAClE,OAAO,SAAS,CAAC,KAAK,EAAE,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;IAChD,CAAC,CAAC;AACJ,CAAC"}

package/dist/esm/lib/mcp/mcpClient.js

@@ -152,8 +152,15 @@ async function buildTransport(t, retryOnThrottle) {
     // transport with no custom fetch still passes none and behaves exactly as it
     // did before 8.11.0.
     if (t.transport === 'gateway') {
+        // The consumer's own `fetch` (9.32.0) goes UNDERNEATH the vending, not
+        // beside it: `createVendingFetch` resolves the credential, applies it to
+        // this one request, and then calls the base fetch — so an mTLS agent or a
+        // DPoP signer sees the final headers and has the last word, while the
+        // credential is still vended per request. Passing `undefined` is the
+        // default global `fetch`, which is byte-identical to every release before
+        // the seam existed.
         return new httpMod.StreamableHTTPClientTransport(new URL(t.url), {
-            fetch: retryingFetch(createVendingFetch(t), retryOnThrottle),
+            fetch: retryingFetch(createVendingFetch(t, t.fetch), retryOnThrottle),
         });
     }
     // Both options ride the SAME SDK transport, and both are forwarded when both

package/dist/esm/lib/mcp/mcpClient.js.map

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

package/dist/esm/lib/mcp/types.d.ts

@@ -23,6 +23,7 @@
 import type { Tool } from '../../core/tools.js';
 import type { CredentialProvider } from '../../identity/types.js';
 import type { RetryOnThrottle } from './throttleRetry.js';
+import type { FetchLike } from './gatewayTransport.js';
 /**
  * `stdio` transport — spawns a local subprocess and speaks MCP over
  * its stdin/stdout. Best for development, single-user scenarios, and
@@ -134,6 +135,15 @@ export interface McpGatewayTransport {
      * the property the vended ones exist to avoid.
      */
     readonly headers?: Readonly<Record<string, string>>;
+    /**
+     * A `fetch` of your own, called UNDERNEATH the per-request vending (9.32.0)
+     * — the seam an mTLS agent or a DPoP signer goes into, so a caller no longer
+     * has to abandon this transport (and its token rotation) to get one. The
+     * credential is vended and applied FIRST, so your function sees the final
+     * headers and has the last word over the bytes. Zero vendor code lives here.
+     * See {@link GatewayTransportOptions.fetch} for the full contract.
+     */
+    readonly fetch?: FetchLike;
 }
 export type McpTransport = McpStdioTransport | McpHttpTransport | McpGatewayTransport;
 export interface McpClientOptions {

package/dist/esm/observe.js

@@ -75,7 +75,8 @@ export { embeddingRecorder, } from './recorders/core/EmbeddingRecorder.js';
 export { permissionRecorder, } from './recorders/core/PermissionRecorder.js';
 export { skillRecorder } from './recorders/core/SkillRecorder.js';
 // Provider-decorator telemetry (fallback.triggered / error.retried /
-// error.recovered). Attached automatically by Agent / LLMCall / Parallel;
+// error.recovered / error.circuit_changed). Attached automatically by
+// Agent / LLMCall / Parallel;
 // exported so consumers running the public message-api charts on a bare
 // FlowChartExecutor can wire the bridge themselves.
 export { resilienceRecorder, } from './recorders/core/ResilienceRecorder.js';

package/dist/esm/observe.js.map

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

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

@@ -3,16 +3,17 @@
  * to the dispatcher.
  *
  * Pattern: Factory (GoF) returning an EmitBridge instance.
- * Role:    Bridges the three events the resilience decorators source
- *          (`fallback.triggered` / `error.retried` / `error.recovered`,
- *          emitted in-run by `resilienceHooks` via `typedEmit`) to the
- *          EventDispatcher so typed consumer listeners
- *          (`agent.on('agentfootprint.error.retried', …)`) fire. Without
- *          this bridge those emits hit the footprintjs emit channel but
- *          never reach the dispatcher.
+ * Role:    Bridges the four events the resilience decorators source
+ *          (`fallback.triggered` / `error.retried` / `error.recovered` /
+ *          `error.circuit_changed`, emitted in-run by `resilienceHooks`
+ *          via `typedEmit`) to the EventDispatcher so typed consumer
+ *          listeners (`agent.on('agentfootprint.error.retried', …)`)
+ *          fire. Without this bridge those emits hit the footprintjs emit
+ *          channel but never reach the dispatcher.
  * Emits:   agentfootprint.fallback.triggered
  *          agentfootprint.error.retried
  *          agentfootprint.error.recovered
+ *          agentfootprint.error.circuit_changed  (9.32.0)
  *
  * Matched on EXACT full event names rather than the broader
  * `agentfootprint.error.` prefix. `error.fatal` is dispatched directly by

package/dist/esm/recorders/core/ResilienceRecorder.js

@@ -3,16 +3,17 @@
  * to the dispatcher.
  *
  * Pattern: Factory (GoF) returning an EmitBridge instance.
- * Role:    Bridges the three events the resilience decorators source
- *          (`fallback.triggered` / `error.retried` / `error.recovered`,
- *          emitted in-run by `resilienceHooks` via `typedEmit`) to the
- *          EventDispatcher so typed consumer listeners
- *          (`agent.on('agentfootprint.error.retried', …)`) fire. Without
- *          this bridge those emits hit the footprintjs emit channel but
- *          never reach the dispatcher.
+ * Role:    Bridges the four events the resilience decorators source
+ *          (`fallback.triggered` / `error.retried` / `error.recovered` /
+ *          `error.circuit_changed`, emitted in-run by `resilienceHooks`
+ *          via `typedEmit`) to the EventDispatcher so typed consumer
+ *          listeners (`agent.on('agentfootprint.error.retried', …)`)
+ *          fire. Without this bridge those emits hit the footprintjs emit
+ *          channel but never reach the dispatcher.
  * Emits:   agentfootprint.fallback.triggered
  *          agentfootprint.error.retried
  *          agentfootprint.error.recovered
+ *          agentfootprint.error.circuit_changed  (9.32.0)
  *
  * Matched on EXACT full event names rather than the broader
  * `agentfootprint.error.` prefix. `error.fatal` is dispatched directly by
@@ -33,6 +34,7 @@ export function resilienceRecorder(options) {
             'agentfootprint.fallback.triggered',
             'agentfootprint.error.retried',
             'agentfootprint.error.recovered',
+            'agentfootprint.error.circuit_changed',
         ],
         dispatcher: options.dispatcher,
         getRunContext: options.getRunContext,

package/dist/esm/recorders/core/ResilienceRecorder.js.map

@@ -1 +1 @@
-{"version":3,"file":"ResilienceRecorder.js","sourceRoot":"","sources":["../../../../src/recorders/core/ResilienceRecorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,UAAU,EAA0B,MAAM,iBAAiB,CAAC;AAMrE,MAAM,UAAU,kBAAkB,CAAC,OAAkC;IACnE,OAAO,IAAI,UAAU,CAAC;QACpB,EAAE,EAAE,OAAO,CAAC,EAAE,IAAI,oCAAoC;QACtD,MAAM,EAAE;YACN,mCAAmC;YACnC,8BAA8B;YAC9B,gCAAgC;SACjC;QACD,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,aAAa,EAAE,OAAO,CAAC,aAAa;KACrC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"ResilienceRecorder.js","sourceRoot":"","sources":["../../../../src/recorders/core/ResilienceRecorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,UAAU,EAA0B,MAAM,iBAAiB,CAAC;AAMrE,MAAM,UAAU,kBAAkB,CAAC,OAAkC;IACnE,OAAO,IAAI,UAAU,CAAC;QACpB,EAAE,EAAE,OAAO,CAAC,EAAE,IAAI,oCAAoC;QACtD,MAAM,EAAE;YACN,mCAAmC;YACnC,8BAA8B;YAC9B,gCAAgC;YAChC,sCAAsC;SACvC;QACD,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,aAAa,EAAE,OAAO,CAAC,aAAa;KACrC,CAAC,CAAC;AACL,CAAC"}

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

@@ -11,6 +11,7 @@
  * Emits:   agentfootprint.fallback.triggered
  *          agentfootprint.error.retried
  *          agentfootprint.error.recovered
+ *          agentfootprint.error.circuit_changed  (9.32.0)
  *
  * Why here and not in the decorators: a decorator is constructed by the
  * consumer BEFORE any run exists, so it can never reach a scope. Passing

package/dist/esm/recorders/core/resilienceHooks.js

@@ -11,6 +11,7 @@
  * Emits:   agentfootprint.fallback.triggered
  *          agentfootprint.error.retried
  *          agentfootprint.error.recovered
+ *          agentfootprint.error.circuit_changed  (9.32.0)
  *
  * Why here and not in the decorators: a decorator is constructed by the
  * consumer BEFORE any run exists, so it can never reach a scope. Passing
@@ -63,6 +64,18 @@ export function resilienceHooks(scope) {
                             totalDurationMs: report.totalDurationMs,
                         });
                         return;
+                    case 'circuit-changed':
+                        // 9.32.0 — the transition happened INSIDE this call, so the ids
+                        // footprintjs stamped before the stage ran are the right ones and
+                        // nothing here is synthesized. That is the whole reason the report
+                        // rides the per-call hooks rather than the breaker's own
+                        // `onStateChange`, which fires wherever the breaker lives.
+                        typedEmit(scope, 'agentfootprint.error.circuit_changed', {
+                            state: report.state,
+                            reason: report.reason,
+                            providerName: report.providerName,
+                        });
+                        return;
                 }
             }
             catch {

package/dist/esm/recorders/core/resilienceHooks.js.map

@@ -1 +1 @@
-{"version":3,"file":"resilienceHooks.js","sourceRoot":"","sources":["../../../../src/recorders/core/resilienceHooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,EAAE,SAAS,EAAsB,MAAM,gBAAgB,CAAC;AAE/D;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,KAAoB;IAClD,OAAO;QACL,YAAY,CAAC,MAAM;YACjB,+DAA+D;YAC/D,gEAAgE;YAChE,kEAAkE;YAClE,+DAA+D;YAC/D,wDAAwD;YACxD,IAAI,CAAC;gBACH,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;oBACpB,KAAK,WAAW;wBACd,SAAS,CAAC,KAAK,EAAE,mCAAmC,EAAE;4BACpD,IAAI,EAAE,UAAU;4BAChB,OAAO,EAAE,MAAM,CAAC,OAAO;4BACvB,QAAQ,EAAE,MAAM,CAAC,QAAQ;4BACzB,MAAM,EAAE,MAAM,CAAC,MAAM;yBACtB,CAAC,CAAC;wBACH,OAAO;oBACT,KAAK,SAAS;wBACZ,SAAS,CAAC,KAAK,EAAE,8BAA8B,EAAE;4BAC/C,OAAO,EAAE,MAAM,CAAC,OAAO;4BACvB,WAAW,EAAE,MAAM,CAAC,WAAW;4BAC/B,SAAS,EAAE,MAAM,CAAC,SAAS;4BAC3B,SAAS,EAAE,MAAM,CAAC,SAAS;4BAC3B,MAAM,EAAE,MAAM,CAAC,MAAM;yBACtB,CAAC,CAAC;wBACH,OAAO;oBACT,KAAK,WAAW;wBACd,SAAS,CAAC,KAAK,EAAE,gCAAgC,EAAE;4BACjD,OAAO,EAAE,MAAM,CAAC,OAAO;4BACvB,eAAe,EAAE,MAAM,CAAC,eAAe;yBACxC,CAAC,CAAC;wBACH,OAAO;gBACX,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,+CAA+C;YACjD,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"resilienceHooks.js","sourceRoot":"","sources":["../../../../src/recorders/core/resilienceHooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,EAAE,SAAS,EAAsB,MAAM,gBAAgB,CAAC;AAE/D;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,KAAoB;IAClD,OAAO;QACL,YAAY,CAAC,MAAM;YACjB,+DAA+D;YAC/D,gEAAgE;YAChE,kEAAkE;YAClE,+DAA+D;YAC/D,wDAAwD;YACxD,IAAI,CAAC;gBACH,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;oBACpB,KAAK,WAAW;wBACd,SAAS,CAAC,KAAK,EAAE,mCAAmC,EAAE;4BACpD,IAAI,EAAE,UAAU;4BAChB,OAAO,EAAE,MAAM,CAAC,OAAO;4BACvB,QAAQ,EAAE,MAAM,CAAC,QAAQ;4BACzB,MAAM,EAAE,MAAM,CAAC,MAAM;yBACtB,CAAC,CAAC;wBACH,OAAO;oBACT,KAAK,SAAS;wBACZ,SAAS,CAAC,KAAK,EAAE,8BAA8B,EAAE;4BAC/C,OAAO,EAAE,MAAM,CAAC,OAAO;4BACvB,WAAW,EAAE,MAAM,CAAC,WAAW;4BAC/B,SAAS,EAAE,MAAM,CAAC,SAAS;4BAC3B,SAAS,EAAE,MAAM,CAAC,SAAS;4BAC3B,MAAM,EAAE,MAAM,CAAC,MAAM;yBACtB,CAAC,CAAC;wBACH,OAAO;oBACT,KAAK,WAAW;wBACd,SAAS,CAAC,KAAK,EAAE,gCAAgC,EAAE;4BACjD,OAAO,EAAE,MAAM,CAAC,OAAO;4BACvB,eAAe,EAAE,MAAM,CAAC,eAAe;yBACxC,CAAC,CAAC;wBACH,OAAO;oBACT,KAAK,iBAAiB;wBACpB,gEAAgE;wBAChE,kEAAkE;wBAClE,mEAAmE;wBACnE,yDAAyD;wBACzD,2DAA2D;wBAC3D,SAAS,CAAC,KAAK,EAAE,sCAAsC,EAAE;4BACvD,KAAK,EAAE,MAAM,CAAC,KAAK;4BACnB,MAAM,EAAE,MAAM,CAAC,MAAM;4BACrB,YAAY,EAAE,MAAM,CAAC,YAAY;yBAClC,CAAC,CAAC;wBACH,OAAO;gBACX,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,+CAA+C;YACjD,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

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

@@ -80,6 +80,21 @@
  * predicate (the visible-tool list is recomputed every iteration).
  * First-class per-tool breakers (state keyed by tool name; run-scoped
  * vs process-scoped TBD) are a possible future enhancement.
+ *
+ * **Status: contract-shaped and tested — independently reproduced against a
+ * local harness, 2026-08-13.** Somebody who is not this library's author drove
+ * this breaker through its whole walk: it opened after two failures, served the
+ * next request from a fallback WITHOUT calling the primary, half-opened after
+ * cooldown, and closed after two successful probes. The one gap that run named
+ * — *"breaker transitions have no typed AgentFootprint event"* — is what 9.32.0
+ * closes with the `'circuit-changed'` report below, and the per-process scope
+ * stated further down was restated there and is unchanged.
+ *
+ * The failures were SCRIPTED and the cooldown was a test clock: those tests
+ * *"were local and deterministic, so they consumed no GCP credit"*. **No live
+ * provider has tripped this breaker from this repository**, so this is not the
+ * field-validated rung — a real degradation, with a real vendor's error mix and
+ * a real recovery time, remains unexercised.
  */
 import type { LLMProvider } from '../adapters/types.js';
 export interface WithCircuitBreakerOptions {
@@ -97,13 +112,18 @@ export interface WithCircuitBreakerOptions {
      */
     readonly shouldCount?: (error: unknown) => boolean;
     /**
-     * Hook invoked on every state transition. This is the ONLY way to
-     * observe breaker state: there is no declared event for a breaker
-     * transition, so unlike `withFallback`/`withRetry` this decorator
-     * reports nothing through the in-run `LLMCallHooks` channel. A trip
-     * becomes visible in a trace only when composed under
-     * `withFallback`, whose `agentfootprint.fallback.triggered` carries
-     * the `CircuitOpenError` message as its `reason`.
+     * Hook invoked on every state transition — your own callback, fired
+     * whether or not a run is in flight, and therefore the right place
+     * for a Redis-backed counter or a cluster-wide coordinator.
+     *
+     * Since 9.32 it is no longer the ONLY way to see a trip. Every
+     * transition is ALSO reported through the per-call `LLMCallHooks`
+     * channel as a `'circuit-changed'` `ResilienceReport`, which the
+     * in-run call site turns into
+     * `agentfootprint.error.circuit_changed` with the run's real
+     * correlation ids — the same seam `withFallback` and `withRetry`
+     * have always used. The two are complements, not duplicates: this
+     * hook fires everywhere, the event fires inside a run.
      */
     readonly onStateChange?: (state: CircuitState, reason: string) => void;
 }

package/dist/esm/resilience/withCircuitBreaker.js

@@ -80,6 +80,21 @@
  * predicate (the visible-tool list is recomputed every iteration).
  * First-class per-tool breakers (state keyed by tool name; run-scoped
  * vs process-scoped TBD) are a possible future enhancement.
+ *
+ * **Status: contract-shaped and tested — independently reproduced against a
+ * local harness, 2026-08-13.** Somebody who is not this library's author drove
+ * this breaker through its whole walk: it opened after two failures, served the
+ * next request from a fallback WITHOUT calling the primary, half-opened after
+ * cooldown, and closed after two successful probes. The one gap that run named
+ * — *"breaker transitions have no typed AgentFootprint event"* — is what 9.32.0
+ * closes with the `'circuit-changed'` report below, and the per-process scope
+ * stated further down was restated there and is unchanged.
+ *
+ * The failures were SCRIPTED and the cooldown was a test clock: those tests
+ * *"were local and deterministic, so they consumed no GCP credit"*. **No live
+ * provider has tripped this breaker from this repository**, so this is not the
+ * field-validated rung — a real degradation, with a real vendor's error mix and
+ * a real recovery time, remains unexercised.
  */
 // ─── Public error type ───────────────────────────────────────────────
 /**
@@ -128,7 +143,20 @@ export function withCircuitBreaker(inner, options = {}) {
         openedAt: 0,
         lastError: undefined,
     };
-    function transition(next, reason) {
+    /**
+     * Move the breaker, and say so on both channels.
+     *
+     * A no-op re-entry returns before either fires, which is what makes the
+     * report stream a record of TRANSITIONS rather than of calls: a hundred
+     * requests rejected while the breaker is already open produce zero events.
+     *
+     * `hooks` is the per-CALL channel, so it is threaded down from whichever
+     * `complete`/`stream` invocation caused the move. Every transition happens
+     * inside one — including `'cooldown elapsed'`, which is discovered by the
+     * next admitted call rather than by a timer — so the event always lands
+     * with the run's real correlation ids and nothing is ever synthesized.
+     */
+    function transition(next, reason, hooks) {
         if (breaker.state === next)
             return;
         breaker.state = next;
@@ -144,26 +172,32 @@ export function withCircuitBreaker(inner, options = {}) {
             breaker.consecutiveSuccesses = 0;
             breaker.lastError = undefined;
         }
+        hooks?.onResilience?.({
+            kind: 'circuit-changed',
+            state: next,
+            reason,
+            providerName: inner.name,
+        });
         onStateChange?.(next, reason);
     }
     /** Decide whether to admit a call. Mutates state if cooldown
      *  elapsed (open → half-open). Returns true to admit, false to
      *  reject with CircuitOpenError. */
-    function admit() {
+    function admit(hooks) {
         if (breaker.state === 'closed' || breaker.state === 'half-open')
             return true;
         // OPEN — check cooldown.
         if (Date.now() - breaker.openedAt >= cooldownMs) {
-            transition('half-open', 'cooldown elapsed');
+            transition('half-open', 'cooldown elapsed', hooks);
             return true;
         }
         return false;
     }
-    function recordSuccess() {
+    function recordSuccess(hooks) {
         if (breaker.state === 'half-open') {
             breaker.consecutiveSuccesses += 1;
             if (breaker.consecutiveSuccesses >= halfOpenSuccessThreshold) {
-                transition('closed', `${halfOpenSuccessThreshold} probe successes`);
+                transition('closed', `${halfOpenSuccessThreshold} probe successes`, hooks);
             }
         }
         else if (breaker.state === 'closed') {
@@ -171,24 +205,24 @@ export function withCircuitBreaker(inner, options = {}) {
             breaker.consecutiveFailures = 0;
         }
     }
-    function recordFailure(err) {
+    function recordFailure(err, hooks) {
         if (!shouldCount(err))
             return;
         breaker.lastError = err;
         if (breaker.state === 'half-open') {
             // Probe failed — re-open the breaker.
-            transition('open', 'half-open probe failed');
+            transition('open', 'half-open probe failed', hooks);
             return;
         }
         if (breaker.state === 'closed') {
             breaker.consecutiveFailures += 1;
             if (breaker.consecutiveFailures >= failureThreshold) {
-                transition('open', `${breaker.consecutiveFailures} consecutive failures`);
+                transition('open', `${breaker.consecutiveFailures} consecutive failures`, hooks);
             }
         }
     }
-    function rejectFastIfOpen() {
-        if (!admit()) {
+    function rejectFastIfOpen(hooks) {
+        if (!admit(hooks)) {
             throw new CircuitOpenError(inner.name, breaker.lastError, breaker.openedAt + cooldownMs);
         }
     }
@@ -206,17 +240,17 @@ export function withCircuitBreaker(inner, options = {}) {
             carriesForcedToolChoice: inner.carriesForcedToolChoice,
         }),
         async complete(req, hooks) {
-            rejectFastIfOpen();
+            rejectFastIfOpen(hooks);
             try {
-                // Forward `hooks` — this decorator reports nothing of its own, but
-                // it rebuilds a fresh provider object, so an inner decorator's
-                // reports are silently swallowed unless they're passed through.
+                // Forward `hooks` inward as well as using them here: this decorator
+                // rebuilds a fresh provider object, so an inner decorator's reports
+                // are silently swallowed unless they're passed through.
                 const res = await inner.complete(req, hooks);
-                recordSuccess();
+                recordSuccess(hooks);
                 return res;
             }
             catch (err) {
-                recordFailure(err);
+                recordFailure(err, hooks);
                 throw err;
             }
         },
@@ -226,7 +260,7 @@ export function withCircuitBreaker(inner, options = {}) {
         // (`if (provider.stream)`) still works correctly.
         ...(inner.stream && {
             async *stream(req, hooks) {
-                rejectFastIfOpen();
+                rejectFastIfOpen(hooks);
                 let yieldedAnyChunk = false;
                 try {
                     // This stream() method is conditionally defined only when
@@ -238,7 +272,7 @@ export function withCircuitBreaker(inner, options = {}) {
                         yieldedAnyChunk = true;
                         yield chunk;
                     }
-                    recordSuccess();
+                    recordSuccess(hooks);
                 }
                 catch (err) {
                     // Only count as a breaker-tripping failure if the stream
@@ -246,7 +280,7 @@ export function withCircuitBreaker(inner, options = {}) {
                     // less indicative of vendor health (could be a content-filter
                     // trip on this specific request).
                     if (!yieldedAnyChunk)
-                        recordFailure(err);
+                        recordFailure(err, hooks);
                     throw err;
                 }
             },

package/dist/esm/resilience/withCircuitBreaker.js.map

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

package/dist/esm/resilience/withFallback.d.ts

@@ -16,6 +16,17 @@
  * yielding any chunks, we restart on the fallback. Once the primary
  * has yielded chunks the stream is committed — fallback would
  * duplicate the partial output.
+ *
+ * **Status: contract-shaped and tested — independently reproduced against a
+ * local harness, 2026-08-13.** Somebody who is not this library's author called
+ * a failed primary once and a healthy fallback once, with
+ * `agentfootprint.fallback.triggered` on the typed stream; a stream that failed
+ * BEFORE its first chunk moved to the fallback, and one that failed AFTER a
+ * chunk did not — the stream-pinning law, measured rather than asserted, and
+ * the reason no output was duplicated. Both providers were SCRIPTED doubles and
+ * the run was deterministic and local (the trial's own words: it *"consumed no
+ * GCP credit"*). **No failover between two live providers has been exercised
+ * from this repository**, so this is not the field-validated rung.
  */
 import type { LLMProvider } from '../adapters/types.js';
 export interface WithFallbackOptions {

package/dist/esm/resilience/withFallback.js

@@ -16,6 +16,17 @@
  * yielding any chunks, we restart on the fallback. Once the primary
  * has yielded chunks the stream is committed — fallback would
  * duplicate the partial output.
+ *
+ * **Status: contract-shaped and tested — independently reproduced against a
+ * local harness, 2026-08-13.** Somebody who is not this library's author called
+ * a failed primary once and a healthy fallback once, with
+ * `agentfootprint.fallback.triggered` on the typed stream; a stream that failed
+ * BEFORE its first chunk moved to the fallback, and one that failed AFTER a
+ * chunk did not — the stream-pinning law, measured rather than asserted, and
+ * the reason no output was duplicated. Both providers were SCRIPTED doubles and
+ * the run was deterministic and local (the trial's own words: it *"consumed no
+ * GCP credit"*). **No failover between two live providers has been exercised
+ * from this repository**, so this is not the field-validated rung.
  */
 import { DEFAULT_CARRIES_IN_MESSAGES } from '../adapters/types.js';
 /**

package/dist/esm/resilience/withFallback.js.map

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

package/dist/esm/resilience/withRetry.d.ts

@@ -17,6 +17,18 @@
  *   • shouldRetry: rejects 4xx-class errors (client mistakes don't
  *                  benefit from retry) and AbortError; retries 5xx,
  *                  network errors, and unknown shapes.
+ *
+ * **Status: contract-shaped and tested — independently reproduced against a
+ * local harness, 2026-08-13.** Somebody who is not this library's author ran
+ * the behaviour end to end and it held: this decorator absorbed two HTTP
+ * 503-shaped failures and recovered on call three, with both
+ * `agentfootprint.error.retried` and `agentfootprint.error.recovered` on the
+ * typed stream, and it made exactly ONE streaming attempt, the limit as
+ * designed. What was exercised was a SCRIPTED failing provider — the trial's
+ * own note is that those tests *"were local and deterministic, so they consumed
+ * no GCP credit"*. **No live provider outage has been retried from this
+ * repository**, so this is not the field-validated rung: a real 503 from a real
+ * vendor, with a real Retry-After and real latency, remains unexercised.
  */
 import type { LLMProvider } from '../adapters/types.js';
 export interface WithRetryOptions {