agentfootprint 1.22.0 → 2.0.1

package/dist/esm/recorders/observability/ThinkingRecorder.js

@@ -0,0 +1,59 @@
+/**
+ * ThinkingRecorder — Claude Code-style live status line for Agent runs.
+ *
+ * Pattern: Facade over EventDispatcher's wildcard subscription.
+ * Role:    Tier 3 observability — consumers enable via
+ *          `agent.enable.thinking({ onStatus })`. Zero subscriptions
+ *          written by the consumer; one callback receives a human-
+ *          readable status string at every meaningful moment.
+ * Emits:   Does NOT emit; READS core events via the dispatcher and calls
+ *          `onStatus`.
+ */
+const RELEVANT = new Set([
+    'agentfootprint.agent.turn_start',
+    'agentfootprint.agent.turn_end',
+    'agentfootprint.agent.iteration_start',
+    'agentfootprint.agent.route_decided',
+    'agentfootprint.stream.tool_start',
+    'agentfootprint.stream.tool_end',
+]);
+/**
+ * Attach a thinking-status subscription to the event dispatcher.
+ * Returns an Unsubscribe — call to detach.
+ */
+export function attachThinking(dispatcher, options) {
+    const format = options.format ?? defaultFormatter;
+    return dispatcher.on('*', (event) => {
+        if (!RELEVANT.has(event.type))
+            return;
+        const status = format(event);
+        if (status !== null)
+            options.onStatus(status);
+    });
+}
+/**
+ * Default renderer. Humanizes each supported event into a short status line.
+ */
+function defaultFormatter(event) {
+    switch (event.type) {
+        case 'agentfootprint.agent.turn_start':
+            return 'Thinking...';
+        case 'agentfootprint.agent.iteration_start':
+            return `Iteration ${event.payload.iterIndex}`;
+        case 'agentfootprint.stream.tool_start':
+            return `Calling ${event.payload.toolName}(…)`;
+        case 'agentfootprint.stream.tool_end':
+            return event.payload.error
+                ? `Tool ${event.payload.toolCallId} failed`
+                : `Got result from ${event.payload.toolCallId}`;
+        case 'agentfootprint.agent.route_decided':
+            return event.payload.chosen === 'final'
+                ? 'Composing answer...'
+                : 'Continuing with tool calls...';
+        case 'agentfootprint.agent.turn_end':
+            return 'Done';
+        default:
+            return null;
+    }
+}
+//# sourceMappingURL=ThinkingRecorder.js.map

package/dist/esm/recorders/observability/ThinkingRecorder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ThinkingRecorder.js","sourceRoot":"","sources":["../../../../src/recorders/observability/ThinkingRecorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAiCH,MAAM,QAAQ,GAAyC,IAAI,GAAG,CAA0B;IACtF,iCAAiC;IACjC,+BAA+B;IAC/B,sCAAsC;IACtC,oCAAoC;IACpC,kCAAkC;IAClC,gCAAgC;CACjC,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,UAA2B,EAAE,OAAwB;IAClF,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,gBAAgB,CAAC;IAClD,OAAO,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,KAA0B,EAAE,EAAE;QACvD,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC;YAAE,OAAO;QACtC,MAAM,MAAM,GAAG,MAAM,CAAC,KAAsB,CAAC,CAAC;QAC9C,IAAI,MAAM,KAAK,IAAI;YAAE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAChD,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;GAEG;AACH,SAAS,gBAAgB,CAAC,KAAoB;IAC5C,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;QACnB,KAAK,iCAAiC;YACpC,OAAO,aAAa,CAAC;QACvB,KAAK,sCAAsC;YACzC,OAAO,aAAa,KAAK,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;QAChD,KAAK,kCAAkC;YACrC,OAAO,WAAW,KAAK,CAAC,OAAO,CAAC,QAAQ,KAAK,CAAC;QAChD,KAAK,gCAAgC;YACnC,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK;gBACxB,CAAC,CAAC,QAAQ,KAAK,CAAC,OAAO,CAAC,UAAU,SAAS;gBAC3C,CAAC,CAAC,mBAAmB,KAAK,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC;QACpD,KAAK,oCAAoC;YACvC,OAAO,KAAK,CAAC,OAAO,CAAC,MAAM,KAAK,OAAO;gBACrC,CAAC,CAAC,qBAAqB;gBACvB,CAAC,CAAC,+BAA+B,CAAC;QACtC,KAAK,+BAA+B;YAClC,OAAO,MAAM,CAAC;QAChB;YACE,OAAO,IAAI,CAAC;IAChB,CAAC;AACH,CAAC"}

package/dist/esm/recorders/observability/commentary/commentaryTemplates.js

@@ -0,0 +1,202 @@
+/**
+ * Commentary templates — bundled English prose for narrating an
+ * agentfootprint run, plus the small engine that picks the right
+ * template per event and substitutes payload values.
+ *
+ * Audience split (load-bearing):
+ *   • COMMENTARY  — pure prose for the bottom panel of any viewer
+ *                   (Lens, CLI tail, log file). NO technical numbers,
+ *                   NO field dumps, NO library terms.
+ *   • DETAILS      — token counts, durations, args, IDs. The right
+ *                   panel / DevTools / structured-log territory.
+ *
+ * Architecture (3 pieces):
+ *   1. `defaultCommentaryTemplates` — flat `key → string` map.
+ *      i18n-ready: ship a Spanish/Japanese/etc. version with the same
+ *      keys, pass via `commentaryTemplates` on the renderer.
+ *   2. `selectCommentaryKey(event)` — per-event-type routing fn.
+ *      Returns `string` (render this key), `null` (skip — too
+ *      low-signal for prose), or `undefined` (fall through to a
+ *      caller-supplied default humanizer).
+ *   3. `extractCommentaryVars(event, ctx)` — builds the
+ *      `{ appName, userPrompt, toolName, descClause, ... }` bag the
+ *      template will be rendered with.
+ *
+ * Plus a tiny non-recursive `renderCommentary(template, vars)`.
+ *
+ * Why this lives in agentfootprint (not Lens):
+ *   The keys ARE agentfootprint event types. The prose teaches
+ *   agentfootprint concepts (slot composition, ReAct, tool-calling).
+ *   Consumers building agentfootprint Agents ship their voice / locale
+ *   alongside their system prompt and tool registry. Lens (or any
+ *   other viewer) is just a renderer that consumes this surface.
+ *
+ * Verb discipline (encoded in the prose):
+ *   • `{{appName}}` (active actor)  — called, dispatched, returned,
+ *                                      decided, read, built
+ *   • LLM (passive actor)            — suggested, responded, produced,
+ *                                      asked for, gave
+ *   The split reflects the architectural truth: LLMs don't act, the
+ *   orchestrating system does.
+ */
+/**
+ * The bundled English templates. Override per-key via the renderer's
+ * `templates` option — partial overrides are spread on top of these
+ * defaults so consumers only ship what they want to change.
+ */
+export const defaultCommentaryTemplates = {
+    'agent.turn_start': 'User asked {{appName}}: "{{userPrompt}}".',
+    'stream.llm_start.iter1': '{{appName}} sent the question to the LLM.',
+    'stream.llm_start.iterN': "{{appName}} sent the tool's result to the LLM for reasoning.",
+    'stream.llm_end.tools': 'The LLM said it needs to use a tool. {{appName}} will do that next.',
+    'stream.llm_end.terminal': 'The LLM gave the final answer. {{appName}} returned it to the user.',
+    // Streaming. Token chunks are NOT rendered as one line each — that
+    // would flood the commentary. Consumers (Lens) accumulate tokens
+    // into a single "live" entry that updates in place until llm_end
+    // arrives, then replace it with the terminal narration above.
+    // The two templates here are for that consumer:
+    //   • `stream.thinking` — shown the moment llm_start fires, BEFORE
+    //     any tokens arrive ("Chatbot is thinking…")
+    //   • `stream.token.partial` — shown while tokens accumulate
+    //     ("Chatbot is responding: {{partial}}")
+    // Selecting these is a viewer concern; the engine emits the keys
+    // and the renderer decides whether to mount a live line or skip.
+    'stream.thinking': '{{appName}} is thinking…',
+    'stream.token.partial': '{{appName}} is responding: {{partial}}',
+    'stream.tool_start': '{{appName}} called the `{{toolName}}` tool{{descClause}}. The LLM asked for it, and {{appName}} figured out the inputs from the conversation.',
+    'stream.tool_start.desc': ' — registered as "{{desc}}"',
+    'stream.tool_start.noDesc': '',
+    'stream.tool_end': 'The tool returned its result. {{appName}} will share it with the LLM next.',
+    'context.injected.rag': '{{appName}} retrieved relevant content and added it to the conversation.',
+    'context.injected.skill': '{{appName}} activated a skill — its body went into the system prompt, and its tools became available to the LLM.',
+    'context.injected.memory': '{{appName}} pulled prior content from memory and added it to the conversation.',
+    'context.injected.instructions': '{{appName}} added a tool-specific instruction to the system prompt after that tool returned.',
+    'context.injected.custom': '{{appName}} injected a custom piece of context.',
+    'skill.activated': '{{appName}} turned on a skill — its tools and instructions are now available.',
+    'skill.deactivated': '{{appName}} turned off a skill.',
+    'composition.fork_start': '{{appName}} fanned out into parallel branches.',
+    'composition.merge_end': '{{appName}} merged the parallel branches back into one.',
+    'pause.request': '{{appName}} paused — waiting for input from a human or external system.',
+    'pause.resume': '{{appName}} resumed.',
+    'cost.limit_hit': '{{appName}} hit a cost limit and stopped.',
+};
+/**
+ * Pick the template key for an event. Branches encoded in the key
+ * suffix (no conditional logic in the templates themselves).
+ *
+ *   `null`      → explicit skip (baseline injections, low-signal events)
+ *   `undefined` → fall through to caller's default humanizer
+ *   `string`    → render `templates[key]` with `extractCommentaryVars`
+ */
+export function selectCommentaryKey(event) {
+    switch (event.type) {
+        case 'agentfootprint.agent.turn_start':
+            return 'agent.turn_start';
+        case 'agentfootprint.agent.turn_end':
+            return null;
+        case 'agentfootprint.stream.llm_start':
+            return event.payload.iteration === 1 ? 'stream.llm_start.iter1' : 'stream.llm_start.iterN';
+        case 'agentfootprint.stream.llm_end':
+            return event.payload.toolCallCount > 0 ? 'stream.llm_end.tools' : 'stream.llm_end.terminal';
+        case 'agentfootprint.stream.tool_start':
+            return 'stream.tool_start';
+        case 'agentfootprint.stream.tool_end':
+            return 'stream.tool_end';
+        case 'agentfootprint.context.injected':
+            switch (event.payload.source) {
+                case 'rag':
+                    return 'context.injected.rag';
+                case 'skill':
+                    return 'context.injected.skill';
+                case 'memory':
+                    return 'context.injected.memory';
+                case 'instructions':
+                    return 'context.injected.instructions';
+                case 'custom':
+                    return 'context.injected.custom';
+                // Baseline injections (LLM API natives, not engineering
+                // decisions): drop from prose.
+                case 'user':
+                case 'tool-result':
+                case 'assistant':
+                case 'base':
+                case 'registry':
+                    return null;
+                default:
+                    return 'context.injected.custom';
+            }
+        case 'agentfootprint.skill.activated':
+            return 'skill.activated';
+        case 'agentfootprint.skill.deactivated':
+            return 'skill.deactivated';
+        case 'agentfootprint.agent.iteration_start':
+        case 'agentfootprint.agent.iteration_end':
+        case 'agentfootprint.agent.route_decided':
+            return null; // implicit in surrounding llm.start/end narrative
+        case 'agentfootprint.composition.fork_start':
+            return 'composition.fork_start';
+        case 'agentfootprint.composition.merge_end':
+            return 'composition.merge_end';
+        case 'agentfootprint.pause.request':
+            return 'pause.request';
+        case 'agentfootprint.pause.resume':
+            return 'pause.resume';
+        case 'agentfootprint.cost.limit_hit':
+            return 'cost.limit_hit';
+        // Slot mechanics — plumbing, not pedagogy. The engineered
+        // injections above already narrate WHAT was added; the surrounding
+        // llm.start line narrates WHY. Mechanical "system-prompt composed
+        // (iter 1, 54/4000 tokens)" leaks technical numbers and adds no
+        // pedagogy.
+        case 'agentfootprint.context.slot_composed':
+        case 'agentfootprint.context.evicted':
+        case 'agentfootprint.context.budget_pressure':
+            return null;
+        default:
+            return undefined; // fall through
+    }
+}
+/**
+ * Build the variable bag for a given event. Flat `name → string` map;
+ * `renderCommentary` substitutes by name. Templates use whatever names
+ * this function produces.
+ *
+ * Two-step composition for `stream.tool_start`: the optional
+ * `descClause` is a rendered sub-template. We pre-render it here so
+ * the outer template stays a single non-recursive substitution pass.
+ */
+export function extractCommentaryVars(event, ctx, templates = defaultCommentaryTemplates) {
+    const base = { appName: ctx.appName };
+    switch (event.type) {
+        case 'agentfootprint.agent.turn_start':
+            return { ...base, userPrompt: event.payload.userPrompt };
+        case 'agentfootprint.stream.tool_start': {
+            const toolName = event.payload.toolName;
+            const desc = ctx.getToolDescription?.(toolName);
+            const hasDesc = typeof desc === 'string' && desc.trim().length > 0;
+            // Pre-render the descClause sub-template so the outer template
+            // sees a literal string. Keeps the engine flat (non-recursive).
+            const descClause = hasDesc
+                ? renderCommentary(templates['stream.tool_start.desc'] ?? '', { desc: desc })
+                : templates['stream.tool_start.noDesc'] ?? '';
+            return { ...base, toolName, descClause };
+        }
+        // Most templates only need {{appName}} — no token counts, no IDs,
+        // no durations make it into prose. Those live in DETAILS.
+        default:
+            return base;
+    }
+}
+/**
+ * Render a template by substituting `{{name}}` placeholders from the
+ * vars bag. Missing keys render as empty string — keeps prose
+ * forgiving when an optional field isn't present.
+ *
+ * Non-recursive: a substituted value is NOT itself processed for
+ * placeholders. Compose sub-templates upstream (see
+ * `extractCommentaryVars`).
+ */
+export function renderCommentary(template, vars) {
+    return template.replace(/\{\{(\w+)\}\}/g, (_, name) => vars[name] ?? '');
+}
+//# sourceMappingURL=commentaryTemplates.js.map

package/dist/esm/recorders/observability/commentary/commentaryTemplates.js.map

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

package/dist/esm/recorders/observability/thinking/thinkingTemplates.js

@@ -0,0 +1,185 @@
+/**
+ * Thinking templates — chat-bubble surface (separate from commentary).
+ *
+ * Audience split:
+ *   • COMMENTARY (`commentaryTemplates`)  — third-person, every moment,
+ *                                            shown in Lens panel. Audience:
+ *                                            developer / observer.
+ *   • THINKING (this file)                — first-person, mid-call only,
+ *                                            shown in chat bubble. Audience:
+ *                                            end user chatting with the agent.
+ *
+ * The thinking surface is a tiny finite state machine driven purely by
+ * the event log:
+ *
+ *      ┌──────────┐  llm.start, no tools yet
+ *  ────┤  idle    ├────────────────────────────► "Thinking…"
+ *      └──────────┘
+ *
+ *      ┌──────────┐  stream.token chunks accumulate
+ *  ────┤streaming ├────────────────────────────► "{{partial}}"
+ *      └──────────┘
+ *
+ *      ┌──────────┐  tool.start, no tool.end yet
+ *  ────┤   tool   ├────────────────────────────► "Working on `weather`…"
+ *      └──────────┘                               (or per-tool override)
+ *
+ *      ┌──────────┐  pause.request, no resume yet
+ *  ────┤  paused  ├────────────────────────────► "Waiting on you: …"
+ *      └──────────┘
+ *
+ *      (null)        run done / between calls   → bubble hidden
+ *
+ * The selector returns the CURRENT state by walking the event log;
+ * the renderer maps state → final string by looking up the template.
+ *
+ * Per-tool templates: consumers can ship `tool.<toolName>` keys
+ * (e.g. `tool.weather: 'Looking up the weather…'`) which the renderer
+ * prefers over the generic `tool` template. Lets each tool have its
+ * own first-person status without per-tool plumbing.
+ */
+// ── Defaults ───────────────────────────────────────────────────────
+/**
+ * Bundled English defaults. Override in the agent config via
+ * `.thinkingTemplates({...})`. Per-tool overrides go via
+ * `tool.<toolName>` keys.
+ */
+export const defaultThinkingTemplates = {
+    idle: 'Thinking…',
+    streaming: '{{partial}}',
+    tool: 'Working on `{{toolName}}`…',
+    paused: 'Waiting on you: {{question}}',
+};
+// ── Selector ───────────────────────────────────────────────────────
+/**
+ * Derive the current thinking state from the event log.
+ *
+ * Single forward walk that tracks "active" state for each domain:
+ *   • pause       — set on pause.request, cleared on pause.resume
+ *   • tool        — set on tool.start, cleared on matching tool.end
+ *                   (matched by `toolCallId` for parallel-tool safety)
+ *   • llm         — set on llm.start, cleared on llm.end
+ *
+ * Priority order (highest first):
+ *
+ *   1. ACTIVE PAUSE wins. When the agent is waiting on the human,
+ *      that's what the chat should show — not the underlying tool
+ *      that triggered the pause.
+ *   2. ACTIVE TOOL — the LLM said "use a tool" and the tool is
+ *      running. Show "Working on `<toolName>`…".
+ *   3. ACTIVE LLM — call in flight. Show streaming tokens if any
+ *      arrived, otherwise "Thinking…".
+ *   4. Otherwise null (bubble hidden).
+ *
+ * Pure projection. Forward walk is O(n); a closing event correctly
+ * cancels its matching opener so a completed tool.start/tool.end
+ * pair leaves the state quiescent.
+ */
+export function selectThinkingState(events) {
+    let activePause = null;
+    let activeTool = null;
+    let activeLlmStartIdx = -1; // -1 = no active LLM call
+    for (let i = 0; i < events.length; i++) {
+        const e = events[i];
+        switch (e.type) {
+            case 'agentfootprint.pause.request': {
+                const p = e.payload;
+                activePause = {
+                    question: p.reason ?? 'input required',
+                    ...(p.toolCallId ? { toolCallId: p.toolCallId } : {}),
+                };
+                break;
+            }
+            case 'agentfootprint.pause.resume':
+                activePause = null;
+                break;
+            case 'agentfootprint.stream.tool_start': {
+                const p = e.payload;
+                activeTool = {
+                    toolName: p.toolName,
+                    ...(p.toolCallId ? { toolCallId: p.toolCallId } : {}),
+                };
+                break;
+            }
+            case 'agentfootprint.stream.tool_end': {
+                // Match by toolCallId so parallel tools don't clobber each
+                // other. If no toolCallId is present (older event), clear
+                // unconditionally — backward-compat with simpler emitters.
+                const p = e.payload;
+                if (!p.toolCallId || activeTool?.toolCallId === p.toolCallId) {
+                    activeTool = null;
+                }
+                break;
+            }
+            case 'agentfootprint.stream.llm_start':
+                activeLlmStartIdx = i;
+                break;
+            case 'agentfootprint.stream.llm_end':
+                activeLlmStartIdx = -1;
+                break;
+        }
+    }
+    // Priority resolution.
+    if (activePause) {
+        return {
+            state: 'paused',
+            vars: {
+                question: activePause.question,
+                ...(activePause.toolCallId ? { toolCallId: activePause.toolCallId } : {}),
+            },
+        };
+    }
+    if (activeTool) {
+        return {
+            state: 'tool',
+            toolName: activeTool.toolName,
+            vars: {
+                toolName: activeTool.toolName,
+                ...(activeTool.toolCallId ? { toolCallId: activeTool.toolCallId } : {}),
+            },
+        };
+    }
+    if (activeLlmStartIdx >= 0) {
+        // Concatenate any tokens emitted after the active llm.start.
+        let partial = '';
+        for (let j = activeLlmStartIdx + 1; j < events.length; j++) {
+            if (events[j].type === 'agentfootprint.stream.token') {
+                const tok = events[j].payload;
+                partial += tok.content;
+            }
+        }
+        return partial.length > 0
+            ? { state: 'streaming', vars: { partial } }
+            : { state: 'idle', vars: {} };
+    }
+    return null;
+}
+// ── Renderer ───────────────────────────────────────────────────────
+/**
+ * Resolve the matched template + substitute vars.
+ *
+ *   • `state === null`           → null (chat bubble renders nothing)
+ *   • `state === 'tool'`         → tries `tool.<toolName>` first, then
+ *                                   generic `tool`
+ *   • Other states               → looks up the state's name as the key
+ *
+ * Missing template keys return null rather than the empty string —
+ * keeps the contract honest (consumer can detect "no template" and
+ * fall back to its own default).
+ */
+export function renderThinkingLine(state, ctx, templates = defaultThinkingTemplates) {
+    if (!state)
+        return null;
+    let key = state.state;
+    if (state.state === 'tool' && state.toolName) {
+        const specific = `tool.${state.toolName}`;
+        if (templates[specific] !== undefined)
+            key = specific;
+    }
+    const template = templates[key];
+    if (template === undefined)
+        return null;
+    const vars = { appName: ctx.appName, ...state.vars };
+    return template.replace(/\{\{(\w+)\}\}/g, (_, name) => vars[name] ?? '');
+}
+//# sourceMappingURL=thinkingTemplates.js.map

package/dist/esm/recorders/observability/thinking/thinkingTemplates.js.map

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

package/dist/esm/resilience/fallbackProvider.js

@@ -0,0 +1,53 @@
+/**
+ * fallbackProvider — convenience for chained fallbacks across N providers.
+ *
+ * Pattern: Chain of Responsibility (GoF) over `LLMProvider` instances.
+ * Role:    Outer ring (Hexagonal). Sugar over repeated `withFallback`.
+ *
+ * `fallbackProvider(p1, p2, p3)` is equivalent to
+ * `withFallback(p1, withFallback(p2, p3))` — tries each provider in
+ * order, advancing on errors that match the (optional) shouldFallback
+ * predicate. The first success wins; if all fail, the last error throws.
+ *
+ * @example
+ *   import { anthropic, openai, mock } from 'agentfootprint/providers';
+ *   import { fallbackProvider } from 'agentfootprint/resilience';
+ *
+ *   const provider = fallbackProvider(
+ *     anthropic({ apiKey: A }),
+ *     openai({ apiKey: O }),
+ *     mock({ reply: '[degraded] all upstream providers failed' }),
+ *   );
+ */
+import { withFallback } from './withFallback.js';
+export function fallbackProvider(first, ...rest) {
+    // Distinguish overload: an options object has no `name` of type "function".
+    // LLMProvider has `complete: function`; options doesn't.
+    const hasComplete = (x) => typeof x === 'object' && x !== null && typeof x.complete === 'function';
+    let providers;
+    let options = {};
+    if (hasComplete(first)) {
+        providers = [first, ...rest];
+    }
+    else {
+        providers = rest;
+        options = first;
+    }
+    if (providers.length === 0) {
+        throw new Error('fallbackProvider() requires at least one provider');
+    }
+    if (providers.length === 1) {
+        return providers[0];
+    }
+    // Right-fold: withFallback(p0, withFallback(p1, withFallback(p2, p3)))
+    let chained = providers[providers.length - 1];
+    for (let i = providers.length - 2; i >= 0; i--) {
+        chained = withFallback(providers[i], chained, options);
+    }
+    // Optionally override the auto-generated name.
+    if (options.name) {
+        return { ...chained, name: options.name };
+    }
+    return chained;
+}
+//# sourceMappingURL=fallbackProvider.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fallbackProvider.js","sourceRoot":"","sources":["../../../src/resilience/fallbackProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,EAAE,YAAY,EAA4B,MAAM,mBAAmB,CAAC;AAgB3E,MAAM,UAAU,gBAAgB,CAC9B,KAA4C,EAC5C,GAAG,IAA4B;IAE/B,4EAA4E;IAC5E,yDAAyD;IACzD,MAAM,WAAW,GAAG,CAAC,CAAU,EAAoB,EAAE,CACnD,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,OAAQ,CAAiB,CAAC,QAAQ,KAAK,UAAU,CAAC;IAE3F,IAAI,SAAiC,CAAC;IACtC,IAAI,OAAO,GAA4B,EAAE,CAAC;IAC1C,IAAI,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;QACvB,SAAS,GAAG,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,CAAC;IAC/B,CAAC;SAAM,CAAC;QACN,SAAS,GAAG,IAAI,CAAC;QACjB,OAAO,GAAG,KAAK,CAAC;IAClB,CAAC;IAED,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;IACvE,CAAC;IACD,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3B,OAAO,SAAS,CAAC,CAAC,CAAE,CAAC;IACvB,CAAC;IAED,uEAAuE;IACvE,IAAI,OAAO,GAAG,SAAS,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC;IAC/C,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC/C,OAAO,GAAG,YAAY,CAAC,SAAS,CAAC,CAAC,CAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAC1D,CAAC;IAED,+CAA+C;IAC/C,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;QACjB,OAAO,EAAE,GAAG,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC;IAC5C,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/esm/resilience/index.js

@@ -0,0 +1,65 @@
+/**
+ * agentfootprint/resilience — provider decorators for production reliability.
+ *
+ * Three composable wrappers around `LLMProvider`. Each preserves the
+ * `LLMProvider` interface (drop-in replacement) and stacks freely:
+ *
+ *   const provider = withRetry(
+ *     fallbackProvider(
+ *       anthropic({ apiKey }),
+ *       openai({ apiKey }),
+ *     ),
+ *     { maxAttempts: 5 },
+ *   );
+ *
+ * Reads as: try anthropic; on failure fall back to openai; the whole
+ * chain is wrapped in retry with 5 attempts.
+ *
+ * ─── 7-panel design review (2026-04-28) ────────────────────────────
+ *
+ *   LLM-AI system design   ✓ Decorator pattern around the existing
+ *                            `LLMProvider` port — no new contract.
+ *                            Stacks naturally; observation hooks
+ *                            (`onRetry`, `onFallback`) keep the
+ *                            recorder ecosystem informed.
+ *   Performance            ✓ Zero overhead on success path (one
+ *                            `try/await` per call). Backoff delays
+ *                            use AbortSignal-aware sleep — no busy
+ *                            wait, no leaked timers.
+ *   Scalability            ✓ Per-call state only. Composition is
+ *                            constant-time per attempt; chain depth
+ *                            doesn't grow runtime cost.
+ *   Research alignment     ✓ Right-fold of `withFallback` matches
+ *                            the standard chain-of-responsibility
+ *                            shape. No exotic resumption — once a
+ *                            stream yields, it commits.
+ *   Flexibility            ✓ Predicates (`shouldRetry`,
+ *                            `shouldFallback`) and hooks
+ *                            (`onRetry`, `onFallback`) make every
+ *                            policy decision overridable. Default
+ *                            policies match common real-world signals
+ *                            (4xx skip, 429 retry, AbortError pass).
+ *   Abstraction-modular    ✓ Three primitives, one purpose each.
+ *                            `fallbackProvider` is sugar over chained
+ *                            `withFallback`. No surprises.
+ *   Software engineering   ✓ Pure decorators — no shared state.
+ *                            Every option has a documented default.
+ *                            Tests cover unit + scenario + integration
+ *                            + property + security + performance + ROI.
+ *
+ * ─── 7-pattern test coverage ───────────────────────────────────────
+ *
+ *   Unit         test/resilience/unit/withRetry.test.ts
+ *                test/resilience/unit/withFallback.test.ts
+ *                test/resilience/unit/fallbackProvider.test.ts
+ *   Scenario     resilience-patterns.test.ts → "production recipes"
+ *   Integration  resilience-patterns.test.ts → "Agent + resilient provider"
+ *   Property     resilience-patterns.test.ts → "invariants"
+ *   Security     resilience-patterns.test.ts → "hostile inputs"
+ *   Performance  resilience-patterns.test.ts → "performance"
+ *   ROI          resilience-patterns.test.ts → "realistic SLO budgets"
+ */
+export { withRetry } from './withRetry.js';
+export { withFallback } from './withFallback.js';
+export { fallbackProvider } from './fallbackProvider.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/resilience/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAEH,OAAO,EAAE,SAAS,EAAyB,MAAM,gBAAgB,CAAC;AAClE,OAAO,EAAE,YAAY,EAA4B,MAAM,mBAAmB,CAAC;AAC3E,OAAO,EAAE,gBAAgB,EAAgC,MAAM,uBAAuB,CAAC"}