agentfootprint 6.43.0 → 6.45.0

package/dist/esm/core/humanizeLLMError.d.ts

@@ -0,0 +1,23 @@
+/**
+ * humanizeLLMError — turn a raw provider/SDK error into a plain-language
+ * sentence a NON-developer can act on.
+ *
+ * agentfootprint targets vibe-coding / non-developer builders. A raw
+ * "[browser-anthropic] Failed to fetch" or "401 Unauthorized" means
+ * nothing to them. This maps the common failure shapes to a friendly,
+ * actionable message. The raw error is preserved on `.cause` (and via
+ * `wrapLLMError`) so developers can still dig in.
+ *
+ * Pure + dependency-light: string/shape matching only. Extend the cases
+ * as new provider failure modes surface — keep each message short and
+ * tell the user what to DO.
+ */
+/** Map a thrown provider/SDK error to a friendly, actionable sentence. */
+export declare function humanizeLLMError(err: unknown): string;
+/**
+ * Wrap a raw provider error in a fresh Error whose `.message` is the
+ * humanized sentence, preserving the original on `.cause` for developers
+ * (and "Copy for LLM"). Re-throw this from the LLM call site so the
+ * friendly message flows through onError → onRunFailed → the monitor.
+ */
+export declare function wrapLLMError(err: unknown): Error;

package/dist/esm/core/outputFallback.d.ts

@@ -0,0 +1,139 @@
+/**
+ * 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)
+ */
+import type { OutputSchemaError, OutputSchemaParser } from './outputSchema.js';
+/**
+ * Tier-2 fallback function. Receives the original validation error +
+ * the raw LLM output; returns a value that the agent will then try
+ * to validate against the same schema.
+ *
+ * If this function throws, OR its return value fails schema, the
+ * agent falls through to the `canned` value (tier 3).
+ */
+export type OutputFallbackFn<T> = (error: OutputSchemaError, rawOutput: string) => Promise<T> | T;
+export interface OutputFallbackOptions<T> {
+    /** Tier 2 — async function that produces a candidate value. May
+     *  throw or return invalid data; the agent will fall through to
+     *  `canned` if so. */
+    readonly fallback: OutputFallbackFn<T>;
+    /** Tier 3 — guaranteed-valid safety net. Validated against the
+     *  schema at builder time (throws on mismatch — fail-fast on
+     *  misconfig). When set, the agent NEVER throws on output-schema
+     *  failure.
+     *
+     *  When omitted, `fallback`-thrown errors propagate to the caller
+     *  (consumer chooses fail-open vs fail-closed). */
+    readonly canned?: T;
+}
+/**
+ * Internal — the resolved fallback config stored on the Agent.
+ * Identical to public `OutputFallbackOptions` but with the parser
+ * + canned-validation results pre-computed.
+ *
+ * @internal
+ */
+export interface ResolvedOutputFallback<T> {
+    readonly fallback: OutputFallbackFn<T>;
+    readonly canned?: T;
+    /** True when `canned` was provided. Used by `apply…` to decide
+     *  whether tier 3 exists at all. */
+    readonly hasCanned: boolean;
+}
+/**
+ * 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.
+ */
+export declare function validateCannedAgainstSchema<T>(canned: T, parser: OutputSchemaParser<T>): void;
+/**
+ * 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).
+ */
+export declare function applyOutputFallback<T>(raw: string, parser: OutputSchemaParser<T>, fallbackCfg: ResolvedOutputFallback<T>, emit: (eventType: string, payload: Record<string, unknown>) => void, primaryError: OutputSchemaError): Promise<T>;

package/dist/esm/core/outputSchema.d.ts

@@ -0,0 +1,127 @@
+/**
+ * outputSchema — declarative terminal contract for an Agent's final answer.
+ *
+ * The Block A6 piece. Lets a consumer say:
+ *
+ *   "Whatever this agent says at the end of a run, it MUST be JSON
+ *    matching this Zod (or Zod-like) schema. Auto-instruct the LLM,
+ *    parse + validate the final answer for me."
+ *
+ * Why a typed contract matters: agentic code that calls an LLM and
+ * then JSON.parses the string answer is brittle. The schema serves
+ * three jobs at once:
+ *
+ *   1. **Instruction**: a system-prompt sentence telling the LLM the
+ *      output shape (auto-generated from `schema.description` /
+ *      JSON-schema introspection where available, or from a consumer-
+ *      supplied `instruction` override).
+ *
+ *   2. **Validation**: a `parser.parse(rawString)` step on the run's
+ *      final answer, throwing `OutputSchemaError` on parse / shape
+ *      failure rather than returning malformed data.
+ *
+ *   3. **Type narrowing**: `agent.runTyped({...})` returns the inferred
+ *      shape `T` instead of `string`, so callers stop reaching for
+ *      `as MyType` casts.
+ *
+ * Pattern: Strategy (GoF) over the parser interface; structural
+ *          duck-typing (Zod / Valibot / ArkType / hand-written —
+ *          anything with a `parse(unknown): T` method satisfies it).
+ *
+ * Role:    Layer-6 (Agent) — terminal contract on the run output.
+ *          NOT a context-engineering Injection per se, but composes
+ *          with the InjectionEngine (auto-injects an Instruction).
+ *
+ * @example  zod schema
+ *   import { z } from 'zod';
+ *   const Output = z.object({ status: z.enum(['ok', 'err']), items: z.array(z.string()) });
+ *
+ *   const agent = Agent.create({ ... })
+ *     .system('You answer support tickets.')
+ *     .outputSchema(Output)
+ *     .build();
+ *
+ *   const typed = await agent.runTyped({ message: 'list pending tickets' });
+ *   typed.status; // narrowed to 'ok' | 'err'
+ *
+ * @example  valibot / arktype / hand-written parser
+ *   const Output = { parse(v: unknown): MyType { ... } };
+ *   const agent = Agent.create({...}).outputSchema(Output, { instruction: '...' }).build();
+ */
+/**
+ * Minimum shape any validation library must expose to satisfy
+ * `outputSchema`. Covers Zod (`schema.parse`), Valibot
+ * (`v.parse(schema, value)` — pass `{ parse: v => v.parse(schema, v) }`),
+ * ArkType (`type.assert`), and hand-written parsers.
+ *
+ * Implementations MUST throw on validation failure (the runtime
+ * catches the throw, wraps it in `OutputSchemaError`, and emits the
+ * diagnostic event).
+ */
+export interface OutputSchemaParser<T> {
+    parse(value: unknown): T;
+    /**
+     * Human-readable description of the output shape. Used by
+     * `outputSchema` to auto-build the system-prompt instruction when
+     * `opts.instruction` is not provided. Zod schemas expose this via
+     * `.describe('...')`; consumers can attach the field directly on
+     * hand-written parsers.
+     */
+    readonly description?: string;
+}
+/**
+ * Optional configuration for `outputSchema`.
+ */
+export interface OutputSchemaOptions {
+    /**
+     * Injection id for the auto-generated "respond with this shape"
+     * instruction. Defaults to `'output-schema'`. Override when you
+     * have multiple agents with different schemas in one process and
+     * want the diagnostic events to disambiguate.
+     */
+    readonly name?: string;
+    /**
+     * Custom system-prompt instruction text. Defaults to a generic
+     * "Respond with valid JSON matching the output schema. Do not
+     * include prose." sentence (extended with `parser.description`
+     * when present). Override when the LLM benefits from a
+     * domain-specific framing.
+     */
+    readonly instruction?: string;
+}
+/**
+ * Thrown by `agent.parseOutput(...)` / `agent.runTyped(...)` when the
+ * agent's final answer fails JSON parsing OR schema validation.
+ *
+ * `cause` carries the underlying parse error (Zod's ZodError, etc.).
+ * `rawOutput` carries the agent's untyped string output so callers
+ * can log / persist the failed response for triage.
+ */
+export declare class OutputSchemaError extends Error {
+    readonly rawOutput: string;
+    readonly stage: 'json-parse' | 'schema-validate';
+    readonly cause?: unknown;
+    constructor(message: string, opts: {
+        rawOutput: string;
+        stage: 'json-parse' | 'schema-validate';
+        cause?: unknown;
+    });
+}
+/**
+ * Default instruction template — used when `opts.instruction` is not
+ * provided. Concatenates the parser's `.description` (if present) so
+ * Zod schemas authored with `.describe('...')` propagate naturally.
+ */
+export declare function buildDefaultInstruction(parser: OutputSchemaParser<unknown>): string;
+/**
+ * Parse + validate a raw string answer against a parser. Used by
+ * `agent.parseOutput()` / `agent.runTyped()`. Centralized here so
+ * both call sites share identical error-mapping behavior.
+ *
+ * Two-stage error reporting:
+ *   - JSON parse failure → `stage: 'json-parse'` (LLM emitted prose
+ *     or malformed JSON)
+ *   - Schema validation failure → `stage: 'schema-validate'` (JSON
+ *     was valid but didn't match the contracted shape)
+ */
+export declare function applyOutputSchema<T>(raw: string, parser: OutputSchemaParser<T>): T;

package/dist/esm/core/pause.d.ts

@@ -0,0 +1,74 @@
+/**
+ * pause — runner-level pause/resume primitives.
+ *
+ * Pattern: Control-flow exception (PauseRequest) + typed outcome (RunnerPauseOutcome).
+ * Role:    core/ layer. Bridges footprintjs.s pause signal into the agentfootprint
+ *          Runner contract: tools call `pauseHere(data)` to raise a pause
+ *          intent; runners detect the paused executor result and return a
+ *          `RunnerPauseOutcome` instead of `TOut`. Consumers call
+ *          `runner.resume(checkpoint, input)` to continue.
+ * Emits:   N/A (types + helpers only). Event emission happens in RunnerBase.
+ *
+ * Why a control-flow "throw": tool.execute(args, ctx) doesn't receive the
+ * typed scope, so it cannot call `scope.$pause()` directly. A thrown
+ * `PauseRequest` is caught inside the Agent's tool-call stage, which then
+ * forwards the pause into the flowchart via `scope.$pause()`. This keeps
+ * the tool API clean (tools are pure-ish) while still supporting pause.
+ */
+import type { FlowchartCheckpoint } from 'footprintjs';
+/**
+ * Outcome returned by `runner.run()` / `runner.resume()` when execution
+ * has paused mid-flow. The shape mirrors footprintjs's `PausedResult` but
+ * surfaces `pauseData` as a first-class field for consumers who don't
+ * want to reach into the checkpoint.
+ */
+export interface RunnerPauseOutcome {
+    readonly paused: true;
+    /** Serializable checkpoint — store anywhere (Redis, Postgres, localStorage). */
+    readonly checkpoint: FlowchartCheckpoint;
+    /** Data passed to `scope.$pause()` / `pauseHere()`. Consumer-typed. */
+    readonly pauseData: unknown;
+}
+/** Type guard — discriminates `RunnerPauseOutcome` from a normal `TOut`. */
+export declare function isPaused<T>(result: T | RunnerPauseOutcome): result is RunnerPauseOutcome;
+/**
+ * Control-flow error raised by `pauseHere()` inside a tool's `execute()`.
+ * Caught by the Agent's tool-call stage, which forwards to `scope.$pause()`.
+ * Never propagates to the consumer.
+ */
+export declare class PauseRequest extends Error {
+    readonly data: unknown;
+    constructor(data: unknown);
+}
+/**
+ * Called from inside a tool's `execute()` to request a pause. Throws a
+ * `PauseRequest` that the Agent catches and forwards to the flowchart.
+ *
+ * @example
+ *   const approveTool: Tool<{ action: string }, string> = {
+ *     schema: { name: 'approve', description: 'Ask human', inputSchema: {...} },
+ *     execute: async (args) => {
+ *       pauseHere({ question: `Approve ${args.action}?`, risk: 'high' });
+ *       return ''; // unreachable — pauseHere always throws
+ *     },
+ *   };
+ */
+export declare function pauseHere(data: unknown): never;
+/** Type guard for a thrown `PauseRequest`. */
+export declare function isPauseRequest(err: unknown): err is PauseRequest;
+/**
+ * Ergonomic alias for `pauseHere(data)` — the human-in-the-loop name.
+ *
+ * `pauseHere` describes the mechanism (control-flow throw); `askHuman`
+ * describes the intent (ask a person to decide). Both work identically.
+ *
+ * @example
+ *   const approveRefund: Tool<{ amount: number }, string> = {
+ *     schema: { name: 'approve_refund', description: '...', inputSchema: {...} },
+ *     execute: async ({ amount }) => {
+ *       if (amount > 1000) askHuman({ question: `Approve $${amount}?` });
+ *       return 'auto-approved';
+ *     },
+ *   };
+ */
+export declare const askHuman: typeof pauseHere;

package/dist/esm/core/runCheckpoint.d.ts

@@ -0,0 +1,179 @@
+/**
+ * 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 RE-EXECUTION (idempotency requirement): anything the
+ *       failed iteration did after the last completed boundary —
+ *       including tool side effects — is NOT in the checkpoint. On
+ *       resume the model re-decides from the restored history and may
+ *       re-issue those tool calls; they WILL execute again. There is
+ *       NO built-in toolCallId-based dedup. Mutating tools (payments,
+ *       emails, DB writes) must be idempotent — derive an idempotency
+ *       key from stable call content, not from `ctx.toolCallId` (fresh
+ *       per issued call, so a re-issued call gets a NEW id). Note the
+ *       same requirement exists WITHOUT resume: a tool that performs
+ *       its side effect and then throws reports the error message back
+ *       to the model as the tool result, and the model typically
+ *       retries the call on the next iteration.
+ *
+ * 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).
+ */
+import type { LLMMessage } from '../adapters/types.js';
+/**
+ * JSON-serializable checkpoint of an in-progress agent run. Persist
+ * to ANY durable store (Redis / Postgres / S3 / disk / queue) and
+ * resume hours / days / deploys later via `agent.resumeOnError(...)`.
+ *
+ * **Stable shape** — the `version` field guards forward compat. v1
+ * → v2 transitions will be supported via a migration helper.
+ */
+export interface AgentRunCheckpoint {
+    /** Schema version. v1 = conversation-history-based. */
+    readonly version: 1;
+    /** `runId` of the FAILING run — lets the consumer correlate a
+     *  persisted checkpoint back to the original run's observability.
+     *  NOT reused on resume: `resumeOnError` starts a fresh run with a
+     *  fresh `runId` (only the conversation history is restored). */
+    readonly runId: string;
+    /** Conversation history at the LAST completed iteration boundary
+     *  (LLM messages). The next iteration retries from here. */
+    readonly history: readonly LLMMessage[];
+    /** Index of the last completed iteration in the FAILING run
+     *  (diagnostic — not consumed on resume). The resumed run restores
+     *  this history but re-seeds its own iteration counter at 1 with a
+     *  full `maxIterations` budget. */
+    readonly lastCompletedIteration: number;
+    /** Original input message. Surfaces in observability + lets the
+     *  consumer correlate checkpoint to the user's request. */
+    readonly originalInput: {
+        readonly message: string;
+    };
+    /** Wall-clock when the checkpoint was captured. Diagnostic only. */
+    readonly checkpointedAt: number;
+    /** Where the failure happened. Diagnostic — surfaces in oncall
+     *  triage so you can tell "LLM 500 mid-iteration" from "tool
+     *  threw" from "validation kept failing". */
+    readonly failurePoint?: {
+        readonly iteration: number;
+        readonly phase: 'iteration' | 'tool' | 'llm' | 'unknown';
+    };
+}
+/**
+ * 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
+ *   }
+ * }
+ * ```
+ */
+export declare class RunCheckpointError extends Error {
+    readonly code: "ERR_RUN_CHECKPOINT";
+    /** The error that triggered the checkpoint. Inspect for retry
+     *  decisions ("if cause is CircuitOpenError, wait for cooldown
+     *  before resuming"). */
+    readonly cause: Error;
+    /** The last-known-good checkpoint. Persist + pass back to
+     *  `agent.resumeOnError(checkpoint)` to continue from here. */
+    readonly checkpoint: AgentRunCheckpoint;
+    constructor(cause: Error, checkpoint: AgentRunCheckpoint);
+}
+/**
+ * Mutable state the Agent maintains during a run for checkpoint
+ * capture. Keyed by `runId` so multiple in-flight runs don't
+ * collide. Cleared on `turn_end` (success path).
+ *
+ * @internal
+ */
+export interface RunCheckpointTracker {
+    readonly runId: string;
+    readonly originalInput: {
+        readonly message: string;
+    };
+    /** Updated on every `agentfootprint.agent.iteration_end`. */
+    history: readonly LLMMessage[];
+    /** Updated on every `agentfootprint.agent.iteration_end`. */
+    lastCompletedIteration: number;
+    /** Set when an iteration begins (used to attribute the failure
+     *  phase if we throw before the next iteration_end). */
+    inFlightIteration?: number;
+}
+/**
+ * Build a JSON-serializable checkpoint from a tracker + failure
+ * info. Pure function — no side effects.
+ *
+ * @internal
+ */
+export declare function buildCheckpoint(tracker: RunCheckpointTracker, failurePoint?: {
+    iteration: number;
+    phase: AgentRunCheckpoint['failurePoint'] extends infer F ? F extends {
+        phase: infer P;
+    } ? P : never : never;
+}): AgentRunCheckpoint;
+/**
+ * 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.
+ */
+export declare function validateCheckpoint(value: unknown): AgentRunCheckpoint;
+/**
+ * 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`).
+ */
+export declare function classifyFailurePhase(err: Error): 'iteration' | 'tool' | 'llm' | 'unknown';