agentfootprint 2.10.0 → 2.10.2

package/dist/core/outputFallback.js

@@ -0,0 +1,156 @@
+"use strict";
+/**
+ * outputFallback — 3-tier degradation for structured-output validation
+ * failures.
+ *
+ * Pairs with `outputSchema(parser)`. When the LLM's final answer
+ * fails schema validation (after the agent loop has done what it
+ * could), instead of throwing `OutputSchemaError` to the caller,
+ * the agent falls through:
+ *
+ *   1. **Primary** — LLM emitted schema-valid JSON. Caller gets the
+ *      parsed value.
+ *   2. **Fallback** — `OutputSchemaError` thrown by the parser. The
+ *      consumer-supplied async `fallback(error, raw)` runs; its
+ *      return value is parsed against the same schema. If valid →
+ *      caller gets it. If `fallback` itself throws OR its return
+ *      value fails schema → tier 3.
+ *   3. **Canned** — static `canned` value (validated against the
+ *      schema at builder time so it's guaranteed to satisfy). The
+ *      agent NEVER throws when `canned` is set.
+ *
+ * Pattern: chain-of-responsibility (GoF) over typed degradation tiers.
+ *          Same shape as `withRetry` / `withFallback` for LLM
+ *          providers, but at the SCHEMA layer instead of the network
+ *          layer.
+ *
+ * Role:    Layer-6 (Agent) — terminal contract failure handler.
+ *          Composable with `outputSchema` (which it supplements;
+ *          one without the other is incoherent).
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod';
+ *
+ * const Refund = z.object({
+ *   amount: z.number().nonnegative(),
+ *   reason: z.string().min(1),
+ * });
+ *
+ * const agent = Agent.create({...})
+ *   .system('You decide refund amounts.')
+ *   .outputSchema(Refund)
+ *   .outputFallback({
+ *     // Tier 2: try a more permissive prompt; if it also fails,
+ *     //         escalate to a human.
+ *     fallback: async (err, raw) => ({
+ *       amount: 0,
+ *       reason: `manual review required (LLM output: ${raw.slice(0, 200)})`,
+ *     }),
+ *     // Tier 3: guaranteed-valid safety net.
+ *     canned: { amount: 0, reason: 'unable to process — please retry' },
+ *   })
+ *   .build();
+ *
+ * // Caller never sees OutputSchemaError; gets a typed Refund either way.
+ * const refund = await agent.runTyped({ message: '...' });
+ * ```
+ *
+ * Why this matters in production:
+ *   - LLMs occasionally emit prose despite the system prompt asking
+ *     for JSON ("Sure! Here's your refund: {...}").
+ *   - Schema-violating outputs are bursty under model load (vendor
+ *     A/B tests, model rollouts, content-filter trips).
+ *   - A B2C agent that THROWS on every malformed output cascades
+ *     into 5xx for the end user; the FAIL-OPEN pattern degrades
+ *     gracefully and lets you triage offline.
+ *
+ * Two typed events fire so observability backends can alert on
+ * degradation:
+ *   - `agentfootprint.resilience.output_fallback_triggered`
+ *     (tier 2 fired)
+ *   - `agentfootprint.resilience.output_canned_used`
+ *     (tier 3 fired — fallback also failed; safety net engaged)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyOutputFallback = exports.validateCannedAgainstSchema = void 0;
+// ─── Builder-time validation ─────────────────────────────────────────
+/**
+ * Validate the consumer-supplied `canned` value against the schema
+ * at builder time. Fail-fast on misconfig — a `canned` value that
+ * doesn't satisfy the schema would cascade into runtime errors
+ * AFTER the agent loop has already failed, which defeats the
+ * fail-open guarantee.
+ *
+ * Throws `TypeError` with a hint if validation fails.
+ */
+function validateCannedAgainstSchema(canned, parser) {
+    try {
+        parser.parse(canned);
+    }
+    catch (cause) {
+        throw new TypeError(`[outputFallback] canned value does not satisfy outputSchema. ` +
+            `The canned value is the safety net — it must always validate. ` +
+            `Underlying error: ${cause?.message ?? String(cause)}`);
+    }
+}
+exports.validateCannedAgainstSchema = validateCannedAgainstSchema;
+// ─── Runtime application ─────────────────────────────────────────────
+/**
+ * The 3-tier resolver. Called by `agent.parseOutput()` /
+ * `agent.runTyped()` when an `outputFallback` is configured. Replaces
+ * the bare-throw behavior of `applyOutputSchema()`.
+ *
+ * Returns the typed value from whichever tier wins. Emits typed
+ * events at every tier transition so observability backends can
+ * alert on degradation.
+ *
+ * @param raw          — the LLM's original final-answer string
+ * @param parser       — the outputSchema parser
+ * @param fallbackCfg  — the resolved fallback configuration
+ * @param emit         — agentfootprint dispatcher's `dispatch()` entry
+ *                       (typed via the runner; we accept a thin
+ *                       function so this module stays import-free of
+ *                       the dispatcher).
+ */
+async function applyOutputFallback(raw, parser, fallbackCfg, emit, primaryError) {
+    // Tier 2 — fallback function.
+    emit('agentfootprint.resilience.output_fallback_triggered', {
+        stage: primaryError.stage,
+        rawOutputPreview: raw.slice(0, 200),
+        primaryErrorMessage: primaryError.message,
+    });
+    let tier2Value;
+    try {
+        tier2Value = await fallbackCfg.fallback(primaryError, raw);
+    }
+    catch (fallbackError) {
+        return cannedOrRethrow(parser, fallbackCfg, emit, fallbackError, raw);
+    }
+    // Validate tier 2's output against the schema.
+    try {
+        return parser.parse(tier2Value);
+    }
+    catch (validationError) {
+        return cannedOrRethrow(parser, fallbackCfg, emit, validationError, raw);
+    }
+}
+exports.applyOutputFallback = applyOutputFallback;
+function cannedOrRethrow(parser, fallbackCfg, emit, failureCause, raw) {
+    if (!fallbackCfg.hasCanned) {
+        // No safety net — propagate. Consumer chose fail-closed by
+        // omitting `canned`.
+        if (failureCause instanceof Error)
+            throw failureCause;
+        throw new Error(String(failureCause));
+    }
+    emit('agentfootprint.resilience.output_canned_used', {
+        rawOutputPreview: raw.slice(0, 200),
+        fallbackErrorMessage: failureCause instanceof Error ? failureCause.message : String(failureCause),
+    });
+    // Re-validate canned defensively. Builder-time validation already
+    // ran, but if a consumer mutates the canned object after build,
+    // we'd rather throw than corrupt the contract.
+    return parser.parse(fallbackCfg.canned);
+}
+//# sourceMappingURL=outputFallback.js.map

package/dist/core/outputFallback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outputFallback.js","sourceRoot":"","sources":["../../src/core/outputFallback.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;;;AA8CH,wEAAwE;AAExE;;;;;;;;GAQG;AACH,SAAgB,2BAA2B,CAAI,MAAS,EAAE,MAA6B;IACrF,IAAI,CAAC;QACH,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACvB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,SAAS,CACjB,+DAA+D;YAC7D,gEAAgE;YAChE,qBAAsB,KAA8B,EAAE,OAAO,IAAI,MAAM,CAAC,KAAK,CAAC,EAAE,CACnF,CAAC;IACJ,CAAC;AACH,CAAC;AAVD,kEAUC;AAED,wEAAwE;AAExE;;;;;;;;;;;;;;;;GAgBG;AACI,KAAK,UAAU,mBAAmB,CACvC,GAAW,EACX,MAA6B,EAC7B,WAAsC,EACtC,IAAmE,EACnE,YAA+B;IAE/B,8BAA8B;IAC9B,IAAI,CAAC,qDAAqD,EAAE;QAC1D,KAAK,EAAE,YAAY,CAAC,KAAK;QACzB,gBAAgB,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC;QACnC,mBAAmB,EAAE,YAAY,CAAC,OAAO;KAC1C,CAAC,CAAC;IAEH,IAAI,UAAmB,CAAC;IACxB,IAAI,CAAC;QACH,UAAU,GAAG,MAAM,WAAW,CAAC,QAAQ,CAAC,YAAY,EAAE,GAAG,CAAC,CAAC;IAC7D,CAAC;IAAC,OAAO,aAAa,EAAE,CAAC;QACvB,OAAO,eAAe,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,aAAa,EAAE,GAAG,CAAC,CAAC;IACxE,CAAC;IAED,+CAA+C;IAC/C,IAAI,CAAC;QACH,OAAO,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IAClC,CAAC;IAAC,OAAO,eAAe,EAAE,CAAC;QACzB,OAAO,eAAe,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,eAAe,EAAE,GAAG,CAAC,CAAC;IAC1E,CAAC;AACH,CAAC;AA3BD,kDA2BC;AAED,SAAS,eAAe,CACtB,MAA6B,EAC7B,WAAsC,EACtC,IAAmE,EACnE,YAAqB,EACrB,GAAW;IAEX,IAAI,CAAC,WAAW,CAAC,SAAS,EAAE,CAAC;QAC3B,2DAA2D;QAC3D,qBAAqB;QACrB,IAAI,YAAY,YAAY,KAAK;YAAE,MAAM,YAAY,CAAC;QACtD,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC;IACxC,CAAC;IACD,IAAI,CAAC,8CAA8C,EAAE;QACnD,gBAAgB,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC;QACnC,oBAAoB,EAClB,YAAY,YAAY,KAAK,CAAC,CAAC,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC;KAC9E,CAAC,CAAC;IACH,kEAAkE;IAClE,gEAAgE;IAChE,+CAA+C;IAC/C,OAAO,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;AAC1C,CAAC"}

package/dist/core/runCheckpoint.js

@@ -0,0 +1,169 @@
+"use strict";
+/**
+ * runCheckpoint — fault-tolerant resume primitives.
+ *
+ * Today's pause/resume only handles INTENTIONAL pauses (`askHuman`).
+ * Errors mid-run (LLM 500s, vendor outages, tool throws, container
+ * restarts) propagate all the way up and the consumer must restart
+ * from scratch — losing the prior iterations' work.
+ *
+ * This module adds the third piece of the Reliability subsystem:
+ *
+ *   1. **`AgentRunCheckpoint`** — JSON-serializable snapshot of an
+ *      agent run's progress. Captured automatically at each
+ *      iteration boundary (the natural commit points). Survives
+ *      process restart — persist to Redis / Postgres / S3 / queue.
+ *
+ *   2. **`RunCheckpointError`** — wraps the underlying error with
+ *      the last-known-good checkpoint. Throwing this instead of the
+ *      raw error lets consumers catch + persist + resume later
+ *      without losing context.
+ *
+ *   3. **`agent.resumeOnError(checkpoint)`** — replays the agent run
+ *      with the checkpointed conversation history restored. The
+ *      next iteration retries the call that originally failed (with
+ *      the latest provider state — circuit breaker may have closed,
+ *      vendor may have recovered, etc.).
+ *
+ * Design tradeoff: we use a CONVERSATION-HISTORY checkpoint shape
+ * rather than a full executor-state checkpoint (which would require
+ * footprintjs API surface changes for mid-run snapshotting). The
+ * tradeoff:
+ *
+ *   ✅ Survives process restart (JSON-serializable, tiny payload)
+ *   ✅ Works with any LLM provider — replay starts from history
+ *   ✅ No footprintjs core changes
+ *   ⚠️  Loses mid-iteration partial state (acceptable — iterations
+ *       are atomic; we resume from the last completed boundary)
+ *   ⚠️  Tool calls inside the failed iteration re-execute (consumer
+ *       must idempotency-key their tool implementations OR use
+ *       v2.10.3+ tool-result dedup via toolCallId).
+ *
+ * Pattern: Memento (GoF) — snapshot of an object's internal state
+ *          for later restoration. Same shape as `FlowchartCheckpoint`
+ *          but at the agent layer (one logical iteration vs. one
+ *          DFS stage).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyFailurePhase = exports.validateCheckpoint = exports.buildCheckpoint = exports.RunCheckpointError = void 0;
+/**
+ * Thrown by `agent.run()` when a fault occurs mid-run. Carries the
+ * underlying error AND the last-known-good checkpoint. Catch this
+ * specifically to engage the resume-on-error path; let other errors
+ * propagate normally.
+ *
+ * @example
+ * ```ts
+ * import { Agent, RunCheckpointError } from 'agentfootprint';
+ *
+ * try {
+ *   const result = await agent.run({ message: 'long task' });
+ * } catch (err) {
+ *   if (err instanceof RunCheckpointError) {
+ *     await checkpointStore.put(sessionId, err.checkpoint);
+ *     // hours / restart later:
+ *     const checkpoint = await checkpointStore.get(sessionId);
+ *     const result = await agent.resumeOnError(checkpoint);
+ *   } else {
+ *     throw err; // not a recoverable error — propagate
+ *   }
+ * }
+ * ```
+ */
+class RunCheckpointError extends Error {
+    code = 'ERR_RUN_CHECKPOINT';
+    /** The error that triggered the checkpoint. Inspect for retry
+     *  decisions ("if cause is CircuitOpenError, wait for cooldown
+     *  before resuming"). */
+    cause;
+    /** The last-known-good checkpoint. Persist + pass back to
+     *  `agent.resumeOnError(checkpoint)` to continue from here. */
+    checkpoint;
+    constructor(cause, checkpoint) {
+        const phase = checkpoint.failurePoint?.phase ?? 'unknown';
+        super(`[agent run] failed at iteration ${checkpoint.failurePoint?.iteration ?? '?'} (${phase}). ` +
+            `Last-good checkpoint captured at iteration ${checkpoint.lastCompletedIteration}. ` +
+            `Pass to agent.resumeOnError(checkpoint) to continue. ` +
+            `Underlying error: ${cause.message}`);
+        this.name = 'RunCheckpointError';
+        this.cause = cause;
+        this.checkpoint = checkpoint;
+    }
+}
+exports.RunCheckpointError = RunCheckpointError;
+/**
+ * Build a JSON-serializable checkpoint from a tracker + failure
+ * info. Pure function — no side effects.
+ *
+ * @internal
+ */
+function buildCheckpoint(tracker, failurePoint) {
+    return {
+        version: 1,
+        runId: tracker.runId,
+        history: tracker.history,
+        lastCompletedIteration: tracker.lastCompletedIteration,
+        originalInput: tracker.originalInput,
+        checkpointedAt: Date.now(),
+        ...(failurePoint && { failurePoint }),
+    };
+}
+exports.buildCheckpoint = buildCheckpoint;
+/**
+ * Validate a checkpoint at deserialization time. Catches forward-
+ * incompatible payloads (someone tries to resume a v3 checkpoint on
+ * a v1 runtime, or a corrupted JSON blob).
+ *
+ * Returns the checkpoint typed-narrowed; throws TypeError on
+ * unknown shape.
+ */
+function validateCheckpoint(value) {
+    if (!value || typeof value !== 'object') {
+        throw new TypeError('[resumeOnError] checkpoint is not an object.');
+    }
+    const c = value;
+    if (c.version !== 1) {
+        throw new TypeError(`[resumeOnError] unsupported checkpoint version: ${c.version}. ` +
+            `This runtime supports version 1; persisted checkpoints from a future ` +
+            `agentfootprint version need a matching runtime to resume.`);
+    }
+    if (typeof c.runId !== 'string' || !Array.isArray(c.history)) {
+        throw new TypeError('[resumeOnError] checkpoint missing required fields (runId, history).');
+    }
+    if (typeof c.lastCompletedIteration !== 'number') {
+        throw new TypeError('[resumeOnError] checkpoint missing required field: lastCompletedIteration.');
+    }
+    if (!c.originalInput || typeof c.originalInput.message !== 'string') {
+        throw new TypeError('[resumeOnError] checkpoint missing required field: originalInput.message.');
+    }
+    return c;
+}
+exports.validateCheckpoint = validateCheckpoint;
+/**
+ * Classify a thrown error into one of the failure-point phase
+ * buckets. Heuristic — uses error name / code / message inspection.
+ * Fast path returns 'unknown' so unrecognized errors still produce
+ * a checkpoint (the cause itself is preserved in
+ * `RunCheckpointError.cause`).
+ */
+function classifyFailurePhase(err) {
+    const name = err.name;
+    const code = err.code ?? '';
+    const msg = err.message ?? '';
+    // LLM provider failures: known codes + name patterns.
+    if (code === 'ERR_CIRCUIT_OPEN' || // our own circuit breaker
+        name === 'AnthropicError' ||
+        name === 'OpenAIError' ||
+        name === 'BedrockError' ||
+        /\b(LLM|provider|anthropic|openai|bedrock)\b/i.test(msg)) {
+        return 'llm';
+    }
+    if (/\b(tool|tool_call)\b/i.test(name) || /\bTool\b/.test(msg)) {
+        return 'tool';
+    }
+    if (/iteration/i.test(msg))
+        return 'iteration';
+    return 'unknown';
+}
+exports.classifyFailurePhase = classifyFailurePhase;
+//# sourceMappingURL=runCheckpoint.js.map

package/dist/core/runCheckpoint.js.map

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

package/dist/esm/core/Agent.js

@@ -47,7 +47,9 @@ import { buildToolsSlot } from './slots/buildToolsSlot.js';
 import { buildInjectionEngineSubflow } from '../lib/injection-engine/buildInjectionEngineSubflow.js';
 import { buildReadSkillTool } from '../lib/injection-engine/skillTools.js';
 import { defineInstruction } from '../lib/injection-engine/factories/defineInstruction.js';
-import { applyOutputSchema, buildDefaultInstruction, } from './outputSchema.js';
+import { applyOutputFallback, validateCannedAgainstSchema, } from './outputFallback.js';
+import { buildCheckpoint, classifyFailurePhase, RunCheckpointError, validateCheckpoint, } from './runCheckpoint.js';
+import { applyOutputSchema, buildDefaultInstruction, OutputSchemaError, } from './outputSchema.js';
 import { RunnerBase, makeRunId } from './RunnerBase.js';
 export class Agent extends RunnerBase {
     name;
@@ -133,6 +135,17 @@ export class Agent extends RunnerBase {
      * raw string; consumers opt into typed mode explicitly.
      */
     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).
+     */
+    outputFallbackCfg;
+    /** Side-channel for `resumeOnError(...)` — when set, the seed
+     *  function restores `scope.history` from this instead of starting
+     *  fresh. Cleared on first read so subsequent runs start clean. */
+    pendingResumeHistory;
     /**
      * Optional `ToolProvider` set via the builder's `.toolProvider()`.
      * When present, the Tools slot subflow consults it per iteration
@@ -143,7 +156,7 @@ export class Agent extends RunnerBase {
      * dispatch correctly when their visible-set changes mid-turn.
      */
     externalToolProvider;
-    constructor(opts, systemPromptValue, registry, voice, injections = [], memories = [], outputSchemaParser, toolProvider, systemPromptCachePolicy = 'always', cachingDisabled = false, cacheStrategy) {
+    constructor(opts, systemPromptValue, registry, voice, injections = [], memories = [], outputSchemaParser, toolProvider, systemPromptCachePolicy = 'always', cachingDisabled = false, cacheStrategy, outputFallbackCfg) {
         super();
         this.provider = opts.provider;
         this.name = opts.name ?? 'Agent';
@@ -162,6 +175,7 @@ export class Agent extends RunnerBase {
         this.injections = injections;
         this.memories = memories;
         this.outputSchemaParser = outputSchemaParser;
+        this.outputFallbackCfg = outputFallbackCfg;
         this.externalToolProvider = toolProvider;
         // Eager validation: tool names must be unique across .tool() +
         // every Skill.inject.tools — the LLM dispatches by name. Runs in
@@ -247,11 +261,54 @@ export class Agent extends RunnerBase {
         }
         return applyOutputSchema(raw, this.outputSchemaParser);
     }
+    /**
+     * 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.
+     */
+    async parseOutputAsync(raw) {
+        if (!this.outputSchemaParser) {
+            throw new Error(`Agent.parseOutputAsync: this agent has no outputSchema. Use ` +
+                `Agent.create({...}).outputSchema(parser).build() to enable typed output.`);
+        }
+        const parser = this.outputSchemaParser;
+        try {
+            return applyOutputSchema(raw, parser);
+        }
+        catch (err) {
+            if (!this.outputFallbackCfg || !(err instanceof OutputSchemaError))
+                throw err;
+            // Engage the 3-tier fallback. The dispatcher gives us the
+            // typed-event entry; we synthesize a minimal event shape since
+            // these events have no per-stage anchor.
+            const emit = (eventType, payload) => {
+                try {
+                    this.dispatcher.dispatch({
+                        type: eventType,
+                        timestamp: Date.now(),
+                        payload,
+                    });
+                }
+                catch {
+                    /* observability errors must not poison the fallback path */
+                }
+            };
+            return applyOutputFallback(raw, parser, this.outputFallbackCfg, emit, err);
+        }
+    }
     /**
      * 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).
      */
@@ -265,18 +322,109 @@ export class Agent extends RunnerBase {
             throw new Error('Agent.runTyped: run paused — typed mode does not support pauses. ' +
                 'Use agent.run() + agent.parseOutput(...) after resume.');
         }
-        return this.parseOutput(out);
+        return this.parseOutputAsync(out);
     }
     async run(input, options) {
+        // (helper used in the catch block below — module-private function
+        // declared at file end via hoisting)
         const executor = this.createExecutor();
-        const result = await executor.run({
-            input: {
-                message: input.message,
-                ...(input.identity !== undefined && { identity: input.identity }),
-            },
-            ...(options ?? {}),
-        });
-        return this.finalizeResult(executor, result);
+        // Auto-checkpoint at iteration boundaries — captures the latest
+        // conversation history into a per-run tracker. On error, we
+        // wrap the underlying error in `RunCheckpointError` carrying
+        // this checkpoint so `agent.resumeOnError(checkpoint)` can
+        // continue from the last good iteration.
+        const tracker = {
+            runId: this.currentRunContext?.runId ?? 'unknown',
+            originalInput: { message: input.message },
+            history: [],
+            lastCompletedIteration: 0,
+        };
+        const stopTracking = this.installCheckpointTracker(tracker);
+        try {
+            const result = await executor.run({
+                input: {
+                    message: input.message,
+                    ...(input.identity !== undefined && { identity: input.identity }),
+                },
+                ...(options ?? {}),
+            });
+            return this.finalizeResult(executor, result);
+        }
+        catch (cause) {
+            // Wrap recoverable errors with the last-known-good checkpoint.
+            // Pause-signal exceptions are not recoverable in this sense
+            // (they're intentional askHuman pauses) — let those propagate.
+            if (cause instanceof Error && cause.name !== 'PauseSignal' && tracker.history.length > 0) {
+                const checkpoint = buildCheckpoint(tracker, {
+                    iteration: tracker.inFlightIteration ?? tracker.lastCompletedIteration + 1,
+                    phase: classifyFailurePhase(cause),
+                });
+                throw new RunCheckpointError(cause, checkpoint);
+            }
+            throw cause;
+        }
+        finally {
+            stopTracking();
+        }
+    }
+    /**
+     * Resume an agent run from a checkpoint produced by a prior
+     * `RunCheckpointError`. Unlike `agent.resume()` (which takes a
+     * `FlowchartCheckpoint` from an intentional pause), this takes
+     * an `AgentRunCheckpoint` (conversation-history snapshot) and
+     * replays the agent run with that history restored.
+     *
+     * The next iteration retries the call that originally failed —
+     * with the latest provider state (circuit breaker may have
+     * closed, vendor may have recovered, etc.).
+     *
+     * @example
+     * ```ts
+     * try {
+     *   const result = await agent.run({ message: 'long task' });
+     * } catch (err) {
+     *   if (err instanceof RunCheckpointError) {
+     *     await checkpointStore.put(sessionId, err.checkpoint);
+     *     // hours / restart later:
+     *     const checkpoint = await checkpointStore.get(sessionId);
+     *     const result = await agent.resumeOnError(checkpoint);
+     *   }
+     * }
+     * ```
+     */
+    async resumeOnError(checkpoint, options) {
+        const cp = validateCheckpoint(checkpoint);
+        // Stash the checkpointed history on the side channel; the seed
+        // function reads + clears it before scope.history initializes.
+        this.pendingResumeHistory = cp.history;
+        return this.run({ message: cp.originalInput.message }, options);
+    }
+    /**
+     * Install a per-run checkpoint tracker. Listens for the agent's
+     * own iteration_end events on `this.dispatcher` and snapshots the
+     * conversation history into the tracker. Returns a stop function.
+     *
+     * @internal
+     */
+    installCheckpointTracker(tracker) {
+        const offIterStart = this.dispatcher.on('agentfootprint.agent.iteration_start', ((event) => {
+            const p = event.payload;
+            if (typeof p?.iterIndex === 'number')
+                tracker.inFlightIteration = p.iterIndex;
+        }));
+        const offIterEnd = this.dispatcher.on('agentfootprint.agent.iteration_end', ((event) => {
+            const p = event.payload;
+            if (typeof p?.iterIndex === 'number')
+                tracker.lastCompletedIteration = p.iterIndex;
+            if (Array.isArray(p?.history)) {
+                tracker.history = p.history;
+            }
+            tracker.inFlightIteration = undefined;
+        }));
+        return () => {
+            offIterStart();
+            offIterEnd();
+        };
     }
     async resume(checkpoint, input, options) {
         this.emitPauseResume(checkpoint, input);
@@ -360,7 +508,18 @@ export class Agent extends RunnerBase {
         const seed = (scope) => {
             const args = scope.$getArgs();
             scope.userMessage = args.message;
-            scope.history = [{ role: 'user', content: args.message }];
+            // If `resumeOnError(...)` set the side channel, restore the
+            // checkpointed conversation history. The next iteration sees
+            // the prior messages and continues from the failure point.
+            // We always clear the field after reading so subsequent runs
+            // (without resumeOnError) start fresh.
+            if (this.pendingResumeHistory && this.pendingResumeHistory.length > 0) {
+                scope.history = [...this.pendingResumeHistory];
+                this.pendingResumeHistory = undefined;
+            }
+            else {
+                scope.history = [{ role: 'user', content: args.message }];
+            }
             // Default identity uses the runId so multi-run isolation works
             // without consumer changes; explicit identity (multi-tenant)
             // overrides via `agent.run({ identity })`.
@@ -823,6 +982,7 @@ export class Agent extends RunnerBase {
                     turnIndex: 0,
                     iterIndex: iteration,
                     toolCallCount: toolCalls.length,
+                    history: scope.history,
                 });
                 scope.iteration = iteration + 1;
                 return undefined; // explicit: no pause, flow continues to loopTo
@@ -857,6 +1017,7 @@ export class Agent extends RunnerBase {
                     turnIndex: 0,
                     iterIndex: iteration,
                     toolCallCount: 1,
+                    history: scope.history,
                 });
                 scope.iteration = iteration + 1;
                 // Clear pause checkpoint fields.
@@ -1142,6 +1303,9 @@ export class AgentBuilder {
      * builder, propagated to the Agent at `.build()` time.
      */
     outputSchemaParser;
+    /** 3-tier output fallback chain — set via `.outputFallback({...})`.
+     *  Optional; absent = current throw-on-validation-failure behavior. */
+    outputFallbackCfg;
     /**
      * Optional `ToolProvider` set via `.toolProvider()`. Propagated to
      * the Agent's Tools slot subflow + tool-call dispatcher; consulted
@@ -1499,6 +1663,59 @@ export class AgentBuilder {
         }));
         return 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(options) {
+        if (!this.outputSchemaParser) {
+            throw new Error('AgentBuilder.outputFallback: call .outputSchema(parser) FIRST. ' +
+                'outputFallback supplements outputSchema; one without the other is incoherent.');
+        }
+        if (this.outputFallbackCfg) {
+            throw new Error('AgentBuilder.outputFallback: already set. Each agent has at most one fallback chain.');
+        }
+        // Build-time validation — canned MUST satisfy the schema.
+        if (options.canned !== undefined) {
+            validateCannedAgainstSchema(options.canned, this.outputSchemaParser);
+        }
+        this.outputFallbackCfg = {
+            fallback: options.fallback,
+            ...(options.canned !== undefined && { canned: options.canned }),
+            hasCanned: options.canned !== undefined,
+        };
+        return this;
+    }
     build() {
         // Resolve the voice config: bundled defaults + consumer overrides.
         // Templates flow through the same barrel exports the rest of the
@@ -1511,7 +1728,7 @@ export class AgentBuilder {
         const opts = this.maxIterationsOverride !== undefined
             ? { ...this.opts, maxIterations: this.maxIterationsOverride }
             : this.opts;
-        const agent = new Agent(opts, this.systemPromptValue, this.registry, voice, this.injectionList, this.memoryList, this.outputSchemaParser, this.toolProviderRef, this.systemPromptCachePolicy, this.cachingDisabledValue, this.cacheStrategyOverride);
+        const agent = new Agent(opts, this.systemPromptValue, this.registry, voice, this.injectionList, this.memoryList, this.outputSchemaParser, this.toolProviderRef, this.systemPromptCachePolicy, this.cachingDisabledValue, this.cacheStrategyOverride, this.outputFallbackCfg);
         // Attach builder-collected recorders so they receive events from
         // the very first run. Mirrors what consumers would do post-build
         // via `agent.attach(rec)`; the builder method is purely sugar.