agentfootprint 1.23.0 → 2.1.0

package/dist/types/recorders/observability/commentary/commentaryTemplates.d.ts

@@ -0,0 +1,96 @@
+/**
+ * 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.
+ */
+import type { AgentfootprintEvent } from '../../../events/registry.js';
+/** Flat map of template keys to template strings. Keys use a dotted
+ *  hierarchy mirroring event types + payload branches
+ *  (`'stream.llm_start.iter1'`, `'context.injected.rag'`). Values may
+ *  contain `{{name}}` placeholders that `renderCommentary` substitutes. */
+export type CommentaryTemplates = Readonly<Record<string, string>>;
+/**
+ * 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 declare const defaultCommentaryTemplates: CommentaryTemplates;
+/** Context the var-extractor reads from. Anything that's NOT in the
+ *  event payload (consumer-supplied appName, tool registry lookup) goes
+ *  here. Pure data — no closures, no I/O. */
+export interface CommentaryContext {
+    /** The system that orchestrates the LLM. Substituted as the active
+     *  actor in every line ("Acme called the LLM"). Default: `'Chatbot'`. */
+    readonly appName: string;
+    /** Resolves a tool name to its registered description ("Get current
+     *  weather for a city"). Used to compose the optional `descClause`
+     *  for `stream.tool_start`. Sync — Lens-style consumers precompute
+     *  the lookup map from `context.injected source='registry'` events. */
+    readonly getToolDescription?: (toolName: string) => string | undefined;
+}
+/**
+ * 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 declare function selectCommentaryKey(event: AgentfootprintEvent): string | null | undefined;
+/**
+ * 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 declare function extractCommentaryVars(event: AgentfootprintEvent, ctx: CommentaryContext, templates?: CommentaryTemplates): Record<string, string>;
+/**
+ * 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 declare function renderCommentary(template: string, vars: Record<string, string>): string;
+//# sourceMappingURL=commentaryTemplates.d.ts.map

package/dist/types/recorders/observability/commentary/commentaryTemplates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commentaryTemplates.d.ts","sourceRoot":"","sources":["../../../../../src/recorders/observability/commentary/commentaryTemplates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAEvE;;;2EAG2E;AAC3E,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAEnE;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,EAAE,mBAmDxC,CAAC;AAEF;;6CAE6C;AAC7C,MAAM,WAAW,iBAAiB;IAChC;6EACyE;IACzE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;2EAGuE;IACvE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;CACxE;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,mBAAmB,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CA8EzF;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,mBAAmB,EAC1B,GAAG,EAAE,iBAAiB,EACtB,SAAS,GAAE,mBAAgD,GAC1D,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAwBxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAEvF"}

package/dist/types/recorders/observability/thinking/thinkingTemplates.d.ts

@@ -0,0 +1,107 @@
+/**
+ * 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.
+ */
+import type { AgentfootprintEvent } from '../../../events/registry.js';
+/** The four mid-call states a chat bubble might render. */
+export type ThinkingStateKind = 'idle' | 'tool' | 'streaming' | 'paused';
+/**
+ * What the selector returns. The chat-bubble consumer feeds this into
+ * the renderer to get the final string.
+ */
+export interface ThinkingState {
+    readonly state: ThinkingStateKind;
+    /** Vars for `{{name}}` substitution in the matched template. */
+    readonly vars: Readonly<Record<string, string>>;
+    /** When `state === 'tool'`, the resolving toolName. The renderer
+     *  uses this to look up `tool.<toolName>` before the generic `tool`. */
+    readonly toolName?: string;
+}
+/** Flat template map. Keys: state kinds + per-tool overrides. */
+export type ThinkingTemplates = Readonly<Record<string, string>>;
+/** Render context — what the consumer's app config injects. */
+export interface ThinkingContext {
+    /** Active actor's name. Substituted as `{{appName}}` in templates. */
+    readonly appName: string;
+}
+/**
+ * Bundled English defaults. Override in the agent config via
+ * `.thinkingTemplates({...})`. Per-tool overrides go via
+ * `tool.<toolName>` keys.
+ */
+export declare const defaultThinkingTemplates: ThinkingTemplates;
+/**
+ * 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 declare function selectThinkingState(events: readonly AgentfootprintEvent[]): ThinkingState | null;
+/**
+ * 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 declare function renderThinkingLine(state: ThinkingState | null, ctx: ThinkingContext, templates?: ThinkingTemplates): string | null;
+//# sourceMappingURL=thinkingTemplates.d.ts.map

package/dist/types/recorders/observability/thinking/thinkingTemplates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"thinkingTemplates.d.ts","sourceRoot":"","sources":["../../../../../src/recorders/observability/thinking/thinkingTemplates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAIvE,2DAA2D;AAC3D,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,MAAM,GAAG,WAAW,GAAG,QAAQ,CAAC;AAEzE;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;IAClC,gEAAgE;IAChE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAChD;4EACwE;IACxE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,iEAAiE;AACjE,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAEjE,+DAA+D;AAC/D,MAAM,WAAW,eAAe;IAC9B,sEAAsE;IACtE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAID;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,EAAE,iBAKtC,CAAC;AAIF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,mBAAmB,EAAE,GAAG,aAAa,GAAG,IAAI,CAkFhG;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,aAAa,GAAG,IAAI,EAC3B,GAAG,EAAE,eAAe,EACpB,SAAS,GAAE,iBAA4C,GACtD,MAAM,GAAG,IAAI,CAaf"}

package/dist/types/resilience/fallbackProvider.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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 type { LLMProvider } from '../adapters/types.js';
+import { type WithFallbackOptions } from './withFallback.js';
+export interface FallbackProviderOptions extends WithFallbackOptions {
+    /** Optional explicit name for the chained provider. */
+    readonly name?: string;
+}
+/**
+ * Compose N providers into a single fallback chain. At least one
+ * provider is required; throws synchronously on empty input.
+ */
+export declare function fallbackProvider(...providers: readonly LLMProvider[]): LLMProvider;
+export declare function fallbackProvider(options: FallbackProviderOptions, ...providers: readonly LLMProvider[]): LLMProvider;
+//# sourceMappingURL=fallbackProvider.d.ts.map

package/dist/types/resilience/fallbackProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fallbackProvider.d.ts","sourceRoot":"","sources":["../../../src/resilience/fallbackProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAAgB,KAAK,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAE3E,MAAM,WAAW,uBAAwB,SAAQ,mBAAmB;IAClE,uDAAuD;IACvD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,SAAS,EAAE,SAAS,WAAW,EAAE,GAAG,WAAW,CAAC;AACpF,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,uBAAuB,EAChC,GAAG,SAAS,EAAE,SAAS,WAAW,EAAE,GACnC,WAAW,CAAC"}

package/dist/types/resilience/index.d.ts

@@ -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, type WithRetryOptions } from './withRetry.js';
+export { withFallback, type WithFallbackOptions } from './withFallback.js';
+export { fallbackProvider, type FallbackProviderOptions } from './fallbackProvider.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/resilience/index.d.ts.map

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

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

@@ -0,0 +1,46 @@
+/**
+ * withFallback — provider decorator that falls back to a secondary
+ * on error.
+ *
+ * Pattern: Decorator (GoF) — composes two `LLMProvider`s into one.
+ * Role:    Outer ring (Hexagonal). Stacks with `withRetry`:
+ *          `withRetry(withFallback(primary, fallback))` first retries
+ *          the primary, then on exhaustion falls back to the secondary.
+ *
+ * Common pairings:
+ *   • Anthropic primary, OpenAI fallback (vendor outage tolerance)
+ *   • Real provider primary, Mock fallback (degrade gracefully in dev)
+ *   • Premium model primary, cheaper model fallback (cost ceiling)
+ *
+ * `stream()` falls back too — if the primary's stream errors before
+ * yielding any chunks, we restart on the fallback. Once the primary
+ * has yielded chunks the stream is committed — fallback would
+ * duplicate the partial output.
+ */
+import type { LLMProvider } from '../adapters/types.js';
+export interface WithFallbackOptions {
+    /**
+     * Predicate to decide whether an error from the primary should
+     * trigger fallback. Default: every error except AbortError.
+     * Override to gate on specific status codes or error types.
+     */
+    readonly shouldFallback?: (error: unknown) => boolean;
+    /**
+     * Hook invoked when the primary fails and we're about to call the
+     * fallback. Useful for emitting `agentfootprint.resilience.fallback`.
+     */
+    readonly onFallback?: (error: unknown) => void;
+}
+/**
+ * Wrap a primary provider with a fallback. Tries primary first; on
+ * error matching the policy, calls the fallback.
+ *
+ * @example
+ *   const provider = withFallback(
+ *     anthropic({ apiKey: A }),
+ *     openai({ apiKey: O }),
+ *     { onFallback: (err) => console.warn('primary failed, falling back:', err) },
+ *   );
+ */
+export declare function withFallback(primary: LLMProvider, fallback: LLMProvider, options?: WithFallbackOptions): LLMProvider;
+//# sourceMappingURL=withFallback.d.ts.map

package/dist/types/resilience/withFallback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"withFallback.d.ts","sourceRoot":"","sources":["../../../src/resilience/withFallback.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAY,WAAW,EAA2B,MAAM,sBAAsB,CAAC;AAE3F,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;IACtD;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAChD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,WAAW,EACpB,QAAQ,EAAE,WAAW,EACrB,OAAO,GAAE,mBAAwB,GAChC,WAAW,CA6Cb"}

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

@@ -0,0 +1,54 @@
+/**
+ * withRetry — provider decorator that retries failed calls.
+ *
+ * Pattern: Decorator (GoF) — wraps an `LLMProvider` and adds retry
+ *          policy without changing its interface.
+ * Role:    Outer ring (Hexagonal). Composable: `withRetry(withFallback(...))`.
+ *
+ * Retries `complete()` on transient failures with exponential backoff.
+ * `stream()` is delegated as-is — once tokens start flowing the
+ * pipeline is stateful and cannot safely be restarted. If you need
+ * retry semantics for streaming, fall back to `complete()` or
+ * implement custom resumability at the consumer.
+ *
+ * Default policy:
+ *   • maxAttempts: 3 (initial + 2 retries)
+ *   • backoff:     exponential — 200ms, 400ms, 800ms
+ *   • shouldRetry: rejects 4xx-class errors (client mistakes don't
+ *                  benefit from retry) and AbortError; retries 5xx,
+ *                  network errors, and unknown shapes.
+ */
+import type { LLMProvider } from '../adapters/types.js';
+export interface WithRetryOptions {
+    /** Total attempts including the first. Default 3. Must be >= 1. */
+    readonly maxAttempts?: number;
+    /** Initial delay in ms before the first retry. Default 200. */
+    readonly initialDelayMs?: number;
+    /** Multiplier between attempts. Default 2 (200ms → 400ms → 800ms). */
+    readonly backoffFactor?: number;
+    /** Maximum delay cap in ms. Default 10_000. */
+    readonly maxDelayMs?: number;
+    /**
+     * Predicate to decide whether an error is worth retrying. Default
+     * skips AbortError + HTTP 4xx; retries everything else. Override
+     * to add provider-specific signals (e.g., 429 with Retry-After).
+     */
+    readonly shouldRetry?: (error: unknown, attempt: number) => boolean;
+    /**
+     * Hook invoked before each retry. Useful for logging or
+     * `agentfootprint.resilience.retry` emit. Receives the attempt
+     * number that's about to start (so attempt 2 = first retry).
+     */
+    readonly onRetry?: (error: unknown, attempt: number, delayMs: number) => void;
+}
+/**
+ * Wrap a provider so its `complete()` retries transient failures.
+ *
+ * @example
+ *   const robust = withRetry(anthropic({ apiKey }), {
+ *     maxAttempts: 5,
+ *     onRetry: (err, attempt, ms) => console.warn(`retry ${attempt} in ${ms}ms`, err),
+ *   });
+ */
+export declare function withRetry(provider: LLMProvider, options?: WithRetryOptions): LLMProvider;
+//# sourceMappingURL=withRetry.d.ts.map

package/dist/types/resilience/withRetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"withRetry.d.ts","sourceRoot":"","sources":["../../../src/resilience/withRetry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAY,WAAW,EAA2B,MAAM,sBAAsB,CAAC;AAE3F,MAAM,WAAW,gBAAgB;IAC/B,mEAAmE;IACnE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,+DAA+D;IAC/D,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,sEAAsE;IACtE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,+CAA+C;IAC/C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;IACpE;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAC/E;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,WAAW,EAAE,OAAO,GAAE,gBAAqB,GAAG,WAAW,CAqC5F"}

package/dist/types/stream.d.ts

@@ -0,0 +1,112 @@
+/**
+ * agentfootprint/stream — agent events → Server-Sent Events helpers.
+ *
+ * Pattern: Adapter (event stream → SSE wire format).
+ * Role:    Outer ring. Subscribes to a `Runner`'s `EventDispatcher`
+ *          and yields SSE-formatted strings. Drop into any HTTP
+ *          framework that accepts an async iterable response body
+ *          (Fetch Response, Express res.write, Hono streaming, etc.).
+ * Emits:   N/A — observes only.
+ *
+ * ─── 7-panel design review (2026-04-28) ─────────────────────────────
+ *
+ *   LLM-AI system design   ✓ One-line-per-event SSE format. Each
+ *                            event = one observation; each chunk
+ *                            includes the `runtimeStageId` for
+ *                            cross-view binding.
+ *   Performance            ✓ AsyncIterable<string> — no buffering;
+ *                            yields each event as it arrives. Stops
+ *                            naturally when the run completes.
+ *   Scalability            ✓ Per-run instance. No shared state;
+ *                            many concurrent SSE streams safe.
+ *   Research alignment     ✓ Standard SSE wire format
+ *                            (text/event-stream). Browsers'
+ *                            native EventSource API consumes directly.
+ *   Flexibility            ✓ `format` option for full event payload
+ *                            vs slim text-only mode (chat UIs that
+ *                            only want token deltas). `filter`
+ *                            predicate gates events.
+ *   Abstraction-modular    ✓ One function (`toSSE`) + one class
+ *                            (`SSEFormatter`); class is sugar for
+ *                            consumers who prefer .pipeTo() shape.
+ *   Software engineering   ✓ Pure observer. No global state. Tests
+ *                            cover unit + scenario + property +
+ *                            security + performance.
+ *
+ * ─── 7-pattern test coverage ────────────────────────────────────────
+ *
+ *   See `test/stream/unit/SSEFormatter.test.ts`.
+ */
+import type { AgentfootprintEvent } from './events/registry.js';
+import type { RunnerBase } from './core/RunnerBase.js';
+/**
+ * Hand the runner this iterable's caller before calling `runner.run()`.
+ * Yields SSE-formatted strings until the run finishes (success, error,
+ * or pause). Each event becomes:
+ *
+ *   event: <event name>
+ *   data: <JSON payload>
+ *   <blank line>
+ *
+ * @example
+ *   // Express
+ *   app.post('/agent', async (req, res) => {
+ *     res.setHeader('content-type', 'text/event-stream');
+ *     for await (const chunk of toSSE(agent)) {
+ *       res.write(chunk);
+ *     }
+ *     res.end();
+ *     // (in parallel: await agent.run(req.body))
+ *   });
+ */
+export interface ToSSEOptions {
+    /**
+     * Filter predicate — return false to skip an event. Default: all events.
+     * Common: `event => event.type.startsWith('agentfootprint.stream.')`
+     * for a token-only feed.
+     */
+    readonly filter?: (event: AgentfootprintEvent) => boolean;
+    /**
+     * Output shape:
+     *   - 'full' (default) — each event is JSON-serialized verbatim.
+     *   - 'text' — only `agentfootprint.stream.token.content` is yielded,
+     *     in plain text form (no event/data prefix). Useful for piping
+     *     directly into a chat UI.
+     */
+    readonly format?: 'full' | 'text';
+    /**
+     * Custom event name extractor. By default `event.type` is used.
+     * Useful for SSE consumers that want their own naming.
+     */
+    readonly eventName?: (event: AgentfootprintEvent) => string;
+    /**
+     * Heartbeat interval in ms. SSE connections through proxies/load
+     * balancers often die after ~30s of silence; emit `: ping` comments
+     * at this interval. Default 0 (disabled).
+     */
+    readonly heartbeatMs?: number;
+}
+/**
+ * Subscribe to a runner's `EventDispatcher` and yield SSE-formatted
+ * strings until the run completes.
+ */
+export declare function toSSE<TIn, TOut>(runner: RunnerBase<TIn, TOut>, options?: ToSSEOptions): AsyncIterable<string>;
+/**
+ * Class form for consumers who prefer `new SSEFormatter(runner).stream()`.
+ * Identical behavior to `toSSE(runner)` — pick by preference.
+ */
+export declare class SSEFormatter<TIn = unknown, TOut = unknown> {
+    private readonly runner;
+    private readonly options;
+    constructor(runner: RunnerBase<TIn, TOut>, options?: ToSSEOptions);
+    /** Async iterable of SSE chunks. Consume with `for await`. */
+    stream(): AsyncIterable<string>;
+}
+/**
+ * Format any JSON-able payload as a single SSE event chunk.
+ *
+ * Useful for app-level events outside the runner's typed registry
+ * (auth/error frames, app-state echoes). Most consumers won't need this.
+ */
+export declare function encodeSSE(eventName: string, payload: unknown): string;
+//# sourceMappingURL=stream.d.ts.map

package/dist/types/stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../src/stream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAGvD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,OAAO,CAAC;IAC1D;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,MAAM,CAAC;IAC5D;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;;GAGG;AACH,wBAAuB,KAAK,CAAC,GAAG,EAAE,IAAI,EACpC,MAAM,EAAE,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,EAC7B,OAAO,GAAE,YAAiB,GACzB,aAAa,CAAC,MAAM,CAAC,CA0EvB;AAED;;;GAGG;AACH,qBAAa,YAAY,CAAC,GAAG,GAAG,OAAO,EAAE,IAAI,GAAG,OAAO;IAEnD,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBADP,MAAM,EAAE,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,EAC7B,OAAO,GAAE,YAAiB;IAG7C,8DAA8D;IAC9D,MAAM,IAAI,aAAa,CAAC,MAAM,CAAC;CAGhC;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAMrE"}