agentfootprint 2.9.0 → 2.10.1

package/dist/esm/resilience/withCircuitBreaker.js

@@ -0,0 +1,229 @@
+/**
+ * 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).
+ *
+ * **Scope: per-instance, NOT distributed.** Each `withCircuitBreaker(...)`
+ * call holds its own breaker state in process memory. If you run 100
+ * server replicas, each has its own independent breaker — one
+ * instance can be CLOSED while another is OPEN. This is intentional
+ * (no shared state means no Redis dependency, no SPOF, no
+ * partial-cluster-blast-radius surprises) and matches Hystrix's
+ * default behavior. For cluster-wide coordination, layer your own
+ * Redis-backed counter on top via the `onStateChange` hook +
+ * `shouldCount` predicate.
+ */
+// ─── Public error type ───────────────────────────────────────────────
+/**
+ * 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 class CircuitOpenError extends Error {
+    code = 'ERR_CIRCUIT_OPEN';
+    /** The error that tripped the breaker (or the most recent failure
+     *  during HALF-OPEN that re-opened it). */
+    cause;
+    /** Wall-clock timestamp at which the breaker may next probe. */
+    retryAfter;
+    constructor(providerName, cause, retryAfter) {
+        super(`[${providerName}] circuit breaker is OPEN — failing fast (next probe at ${new Date(retryAfter).toISOString()}). Underlying error: ${cause?.message ?? String(cause)}`);
+        this.name = 'CircuitOpenError';
+        this.cause = cause;
+        this.retryAfter = retryAfter;
+    }
+}
+/**
+ * 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 function withCircuitBreaker(inner, options = {}) {
+    const failureThreshold = options.failureThreshold ?? 5;
+    const cooldownMs = options.cooldownMs ?? 30_000;
+    const halfOpenSuccessThreshold = options.halfOpenSuccessThreshold ?? 2;
+    const shouldCount = options.shouldCount ?? defaultShouldCount;
+    const onStateChange = options.onStateChange;
+    const breaker = {
+        state: 'closed',
+        consecutiveFailures: 0,
+        consecutiveSuccesses: 0,
+        openedAt: 0,
+        lastError: undefined,
+    };
+    function transition(next, reason) {
+        if (breaker.state === next)
+            return;
+        breaker.state = next;
+        if (next === 'open') {
+            breaker.openedAt = Date.now();
+            breaker.consecutiveSuccesses = 0;
+        }
+        else if (next === 'half-open') {
+            breaker.consecutiveSuccesses = 0;
+        }
+        else if (next === 'closed') {
+            breaker.consecutiveFailures = 0;
+            breaker.consecutiveSuccesses = 0;
+            breaker.lastError = undefined;
+        }
+        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() {
+        if (breaker.state === 'closed' || breaker.state === 'half-open')
+            return true;
+        // OPEN — check cooldown.
+        if (Date.now() - breaker.openedAt >= cooldownMs) {
+            transition('half-open', 'cooldown elapsed');
+            return true;
+        }
+        return false;
+    }
+    function recordSuccess() {
+        if (breaker.state === 'half-open') {
+            breaker.consecutiveSuccesses += 1;
+            if (breaker.consecutiveSuccesses >= halfOpenSuccessThreshold) {
+                transition('closed', `${halfOpenSuccessThreshold} probe successes`);
+            }
+        }
+        else if (breaker.state === 'closed') {
+            // Successful call resets the failure counter.
+            breaker.consecutiveFailures = 0;
+        }
+    }
+    function recordFailure(err) {
+        if (!shouldCount(err))
+            return;
+        breaker.lastError = err;
+        if (breaker.state === 'half-open') {
+            // Probe failed — re-open the breaker.
+            transition('open', 'half-open probe failed');
+            return;
+        }
+        if (breaker.state === 'closed') {
+            breaker.consecutiveFailures += 1;
+            if (breaker.consecutiveFailures >= failureThreshold) {
+                transition('open', `${breaker.consecutiveFailures} consecutive failures`);
+            }
+        }
+    }
+    function rejectFastIfOpen() {
+        if (!admit()) {
+            throw new CircuitOpenError(inner.name, breaker.lastError, breaker.openedAt + cooldownMs);
+        }
+    }
+    const wrapped = {
+        name: inner.name,
+        async complete(req) {
+            rejectFastIfOpen();
+            try {
+                const res = await inner.complete(req);
+                recordSuccess();
+                return res;
+            }
+            catch (err) {
+                recordFailure(err);
+                throw err;
+            }
+        },
+        // `stream` is optional on `LLMProvider`. Only define our wrapper
+        // if the underlying provider supports streaming — otherwise leave
+        // it undefined so the consumer's existing capability check
+        // (`if (provider.stream)`) still works correctly.
+        ...(inner.stream && {
+            async *stream(req) {
+                rejectFastIfOpen();
+                let yieldedAnyChunk = false;
+                try {
+                    for await (const chunk of inner.stream(req)) {
+                        yieldedAnyChunk = true;
+                        yield chunk;
+                    }
+                    recordSuccess();
+                }
+                catch (err) {
+                    // Only count as a breaker-tripping failure if the stream
+                    // failed BEFORE yielding any tokens. Mid-stream errors are
+                    // less indicative of vendor health (could be a content-filter
+                    // trip on this specific request).
+                    if (!yieldedAnyChunk)
+                        recordFailure(err);
+                    throw err;
+                }
+            },
+        }),
+    };
+    return wrapped;
+}
+// ─── Default predicates ──────────────────────────────────────────────
+function defaultShouldCount(error) {
+    // Don't count user cancellations.
+    const e = error;
+    if (e?.name === 'AbortError')
+        return false;
+    if (e?.code === 'ABORT_ERR')
+        return false;
+    return true;
+}
+//# sourceMappingURL=withCircuitBreaker.js.map

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

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

package/dist/index.js.map

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

package/dist/resilience/index.js

@@ -17,11 +17,14 @@
  * chain is wrapped in retry with 5 attempts.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.fallbackProvider = exports.withFallback = exports.withRetry = void 0;
+exports.CircuitOpenError = exports.withCircuitBreaker = exports.fallbackProvider = exports.withFallback = exports.withRetry = void 0;
 var withRetry_js_1 = require("./withRetry.js");
 Object.defineProperty(exports, "withRetry", { enumerable: true, get: function () { return withRetry_js_1.withRetry; } });
 var withFallback_js_1 = require("./withFallback.js");
 Object.defineProperty(exports, "withFallback", { enumerable: true, get: function () { return withFallback_js_1.withFallback; } });
 var fallbackProvider_js_1 = require("./fallbackProvider.js");
 Object.defineProperty(exports, "fallbackProvider", { enumerable: true, get: function () { return fallbackProvider_js_1.fallbackProvider; } });
+var withCircuitBreaker_js_1 = require("./withCircuitBreaker.js");
+Object.defineProperty(exports, "withCircuitBreaker", { enumerable: true, get: function () { return withCircuitBreaker_js_1.withCircuitBreaker; } });
+Object.defineProperty(exports, "CircuitOpenError", { enumerable: true, get: function () { return withCircuitBreaker_js_1.CircuitOpenError; } });
 //# sourceMappingURL=index.js.map

package/dist/resilience/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/resilience/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;GAgBG;;;AAEH,+CAAkE;AAAzD,yGAAA,SAAS,OAAA;AAClB,qDAA2E;AAAlE,+GAAA,YAAY,OAAA;AACrB,6DAAuF;AAA9E,uHAAA,gBAAgB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/resilience/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;GAgBG;;;AAEH,+CAAkE;AAAzD,yGAAA,SAAS,OAAA;AAClB,qDAA2E;AAAlE,+GAAA,YAAY,OAAA;AACrB,6DAAuF;AAA9E,uHAAA,gBAAgB,OAAA;AACzB,iEAKiC;AAJ/B,2HAAA,kBAAkB,OAAA;AAClB,yHAAA,gBAAgB,OAAA"}

package/dist/resilience/withCircuitBreaker.js

@@ -0,0 +1,234 @@
+"use strict";
+/**
+ * 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).
+ *
+ * **Scope: per-instance, NOT distributed.** Each `withCircuitBreaker(...)`
+ * call holds its own breaker state in process memory. If you run 100
+ * server replicas, each has its own independent breaker — one
+ * instance can be CLOSED while another is OPEN. This is intentional
+ * (no shared state means no Redis dependency, no SPOF, no
+ * partial-cluster-blast-radius surprises) and matches Hystrix's
+ * default behavior. For cluster-wide coordination, layer your own
+ * Redis-backed counter on top via the `onStateChange` hook +
+ * `shouldCount` predicate.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withCircuitBreaker = exports.CircuitOpenError = void 0;
+// ─── Public error type ───────────────────────────────────────────────
+/**
+ * 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.
+ */
+class CircuitOpenError extends Error {
+    code = 'ERR_CIRCUIT_OPEN';
+    /** The error that tripped the breaker (or the most recent failure
+     *  during HALF-OPEN that re-opened it). */
+    cause;
+    /** Wall-clock timestamp at which the breaker may next probe. */
+    retryAfter;
+    constructor(providerName, cause, retryAfter) {
+        super(`[${providerName}] circuit breaker is OPEN — failing fast (next probe at ${new Date(retryAfter).toISOString()}). Underlying error: ${cause?.message ?? String(cause)}`);
+        this.name = 'CircuitOpenError';
+        this.cause = cause;
+        this.retryAfter = retryAfter;
+    }
+}
+exports.CircuitOpenError = CircuitOpenError;
+/**
+ * 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 })),
+ * );
+ * ```
+ */
+function withCircuitBreaker(inner, options = {}) {
+    const failureThreshold = options.failureThreshold ?? 5;
+    const cooldownMs = options.cooldownMs ?? 30_000;
+    const halfOpenSuccessThreshold = options.halfOpenSuccessThreshold ?? 2;
+    const shouldCount = options.shouldCount ?? defaultShouldCount;
+    const onStateChange = options.onStateChange;
+    const breaker = {
+        state: 'closed',
+        consecutiveFailures: 0,
+        consecutiveSuccesses: 0,
+        openedAt: 0,
+        lastError: undefined,
+    };
+    function transition(next, reason) {
+        if (breaker.state === next)
+            return;
+        breaker.state = next;
+        if (next === 'open') {
+            breaker.openedAt = Date.now();
+            breaker.consecutiveSuccesses = 0;
+        }
+        else if (next === 'half-open') {
+            breaker.consecutiveSuccesses = 0;
+        }
+        else if (next === 'closed') {
+            breaker.consecutiveFailures = 0;
+            breaker.consecutiveSuccesses = 0;
+            breaker.lastError = undefined;
+        }
+        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() {
+        if (breaker.state === 'closed' || breaker.state === 'half-open')
+            return true;
+        // OPEN — check cooldown.
+        if (Date.now() - breaker.openedAt >= cooldownMs) {
+            transition('half-open', 'cooldown elapsed');
+            return true;
+        }
+        return false;
+    }
+    function recordSuccess() {
+        if (breaker.state === 'half-open') {
+            breaker.consecutiveSuccesses += 1;
+            if (breaker.consecutiveSuccesses >= halfOpenSuccessThreshold) {
+                transition('closed', `${halfOpenSuccessThreshold} probe successes`);
+            }
+        }
+        else if (breaker.state === 'closed') {
+            // Successful call resets the failure counter.
+            breaker.consecutiveFailures = 0;
+        }
+    }
+    function recordFailure(err) {
+        if (!shouldCount(err))
+            return;
+        breaker.lastError = err;
+        if (breaker.state === 'half-open') {
+            // Probe failed — re-open the breaker.
+            transition('open', 'half-open probe failed');
+            return;
+        }
+        if (breaker.state === 'closed') {
+            breaker.consecutiveFailures += 1;
+            if (breaker.consecutiveFailures >= failureThreshold) {
+                transition('open', `${breaker.consecutiveFailures} consecutive failures`);
+            }
+        }
+    }
+    function rejectFastIfOpen() {
+        if (!admit()) {
+            throw new CircuitOpenError(inner.name, breaker.lastError, breaker.openedAt + cooldownMs);
+        }
+    }
+    const wrapped = {
+        name: inner.name,
+        async complete(req) {
+            rejectFastIfOpen();
+            try {
+                const res = await inner.complete(req);
+                recordSuccess();
+                return res;
+            }
+            catch (err) {
+                recordFailure(err);
+                throw err;
+            }
+        },
+        // `stream` is optional on `LLMProvider`. Only define our wrapper
+        // if the underlying provider supports streaming — otherwise leave
+        // it undefined so the consumer's existing capability check
+        // (`if (provider.stream)`) still works correctly.
+        ...(inner.stream && {
+            async *stream(req) {
+                rejectFastIfOpen();
+                let yieldedAnyChunk = false;
+                try {
+                    for await (const chunk of inner.stream(req)) {
+                        yieldedAnyChunk = true;
+                        yield chunk;
+                    }
+                    recordSuccess();
+                }
+                catch (err) {
+                    // Only count as a breaker-tripping failure if the stream
+                    // failed BEFORE yielding any tokens. Mid-stream errors are
+                    // less indicative of vendor health (could be a content-filter
+                    // trip on this specific request).
+                    if (!yieldedAnyChunk)
+                        recordFailure(err);
+                    throw err;
+                }
+            },
+        }),
+    };
+    return wrapped;
+}
+exports.withCircuitBreaker = withCircuitBreaker;
+// ─── Default predicates ──────────────────────────────────────────────
+function defaultShouldCount(error) {
+    // Don't count user cancellations.
+    const e = error;
+    if (e?.name === 'AbortError')
+        return false;
+    if (e?.code === 'ABORT_ERR')
+        return false;
+    return true;
+}
+//# sourceMappingURL=withCircuitBreaker.js.map

package/dist/resilience/withCircuitBreaker.js.map

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

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

@@ -20,6 +20,7 @@ import type { LLMProvider, PermissionChecker, PricingTable } from '../adapters/t
 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';
 import { type OutputSchemaOptions, type OutputSchemaParser } from './outputSchema.js';
 import { RunnerBase } from './RunnerBase.js';
 import type { Tool, ToolRegistryEntry } from './tools.js';
@@ -169,6 +170,13 @@ export declare class Agent extends RunnerBase<AgentInput, AgentOutput> {
      * raw string; consumers opt into typed mode explicitly.
      */
     private readonly outputSchemaParser?;
+    /**
+     * Optional 3-tier degradation for output-schema validation
+     * failures. Set via the builder's `.outputFallback({...})`. When
+     * present, `parseOutput()` and `runTyped()` fall through:
+     *   primary → fallback → canned (in order; canned guarantees no-throw).
+     */
+    private readonly outputFallbackCfg?;
     /**
      * Optional `ToolProvider` set via the builder's `.toolProvider()`.
      * When present, the Tools slot subflow consults it per iteration
@@ -183,7 +191,7 @@ export declare class Agent extends RunnerBase<AgentInput, AgentOutput> {
         readonly appName: string;
         readonly commentaryTemplates: Readonly<Record<string, string>>;
         readonly thinkingTemplates: Readonly<Record<string, string>>;
-    }, injections?: readonly Injection[], memories?: readonly MemoryDefinition[], outputSchemaParser?: OutputSchemaParser<unknown>, toolProvider?: ToolProvider, systemPromptCachePolicy?: CachePolicy, cachingDisabled?: boolean, cacheStrategy?: CacheStrategy);
+    }, injections?: readonly Injection[], memories?: readonly MemoryDefinition[], outputSchemaParser?: OutputSchemaParser<unknown>, toolProvider?: ToolProvider, systemPromptCachePolicy?: CachePolicy, cachingDisabled?: boolean, cacheStrategy?: CacheStrategy, outputFallbackCfg?: ResolvedOutputFallback<unknown>);
     static create(opts: AgentOptions): AgentBuilder;
     toFlowChart(): FlowChart;
     /**
@@ -232,11 +240,25 @@ export declare class Agent extends RunnerBase<AgentInput, AgentOutput> {
      * layer; otherwise prefer `agent.runTyped()`.
      */
     parseOutput<T = unknown>(raw: string): T;
+    /**
+     * Async sister of `parseOutput()`. When the agent is configured
+     * with `.outputFallback({...})`, this is the version that engages
+     * the 3-tier degradation chain on validation failure (the sync
+     * `parseOutput` always throws on failure for back-compat).
+     *
+     * Without `outputFallback`, behaves identically to `parseOutput`
+     * — returns sync-style on the happy path, throws OutputSchemaError
+     * on validation failure.
+     */
+    parseOutputAsync<T = unknown>(raw: string): Promise<T>;
     /**
      * Run the agent and return the schema-validated typed output.
-     * Convenience over `parseOutput(await agent.run({...}))`.
+     * Convenience over `parseOutputAsync(await agent.run({...}))`.
+     *
+     * Throws `OutputSchemaError` on parse / validation failure UNLESS
+     * `.outputFallback({...})` is configured, in which case the
+     * 3-tier degradation chain (primary → fallback → canned) engages.
      *
-     * Throws `OutputSchemaError` on parse / validation failure.
      * Throws if the agent has no outputSchema set or if the run
      * pauses (use `run()` directly when pauses are expected).
      */
@@ -282,6 +304,9 @@ export declare class AgentBuilder {
      * builder, propagated to the Agent at `.build()` time.
      */
     private outputSchemaParser?;
+    /** 3-tier output fallback chain — set via `.outputFallback({...})`.
+     *  Optional; absent = current throw-on-validation-failure behavior. */
+    private outputFallbackCfg?;
     /**
      * Optional `ToolProvider` set via `.toolProvider()`. Propagated to
      * the Agent's Tools slot subflow + tool-call dispatcher; consulted
@@ -537,6 +562,41 @@ export declare class AgentBuilder {
      *   typed.status; // narrowed to 'ok' | 'err'
      */
     outputSchema<T>(parser: OutputSchemaParser<T>, opts?: OutputSchemaOptions): this;
+    /**
+     * 3-tier degradation for output-schema validation failures. Pairs
+     * with `.outputSchema()` — calling `.outputFallback()` without an
+     * `outputSchema` first throws (the fallback has nothing to validate).
+     *
+     * Three tiers:
+     *
+     *   1. **Primary** — LLM emitted schema-valid JSON. Caller gets it.
+     *   2. **Fallback** — `OutputSchemaError` thrown. The async
+     *      `fallback(error, raw)` runs; its return is re-validated.
+     *   3. **Canned** — static safety-net value. NEVER throws when set.
+     *
+     * `canned` is validated against the schema at builder time —
+     * fail-fast on misconfig (a `canned` that doesn't validate would
+     * defeat the fail-open guarantee).
+     *
+     * Two typed events fire on tier transitions for observability:
+     *   - `agentfootprint.resilience.output_fallback_triggered`
+     *   - `agentfootprint.resilience.output_canned_used`
+     *
+     * @example
+     * ```ts
+     * import { z } from 'zod';
+     * const Refund = z.object({ amount: z.number(), reason: z.string() });
+     *
+     * const agent = Agent.create({...})
+     *   .outputSchema(Refund)
+     *   .outputFallback({
+     *     fallback: async (err, raw) => ({ amount: 0, reason: 'manual review' }),
+     *     canned:   { amount: 0, reason: 'unable to process' },
+     *   })
+     *   .build();
+     * ```
+     */
+    outputFallback<T>(options: OutputFallbackOptions<T>): this;
     build(): Agent;
 }
 //# sourceMappingURL=Agent.d.ts.map