agentfootprint 1.22.0 → 2.0.1

package/dist/types/recorders/observability/FlowchartRecorder.d.ts

@@ -0,0 +1,205 @@
+/**
+ * FlowchartRecorder — StepGraph projection over `BoundaryRecorder`.
+ *
+ * Pattern: Pure projection. `attachFlowchart` wires a `BoundaryRecorder`
+ *          to the executor + dispatcher; `buildStepGraph` is a fold over
+ *          `boundary.getEvents()` that produces the renderer-friendly
+ *          `StepGraph` shape Lens (and any other consumer) renders.
+ *
+ *          ZERO state machine in this file. ZERO event subscription.
+ *          ZERO name-based filters. Everything that decides "what's a
+ *          step" lives in BoundaryRecorder via capture-time tags
+ *          (`actorArrow`, `slotKind`, `primitiveKind`, `isAgentInternal`).
+ *
+ * Role:    Tier 3 observability. Enabled via
+ *          `runner.enable.flowchart({ onUpdate })`. The handle exposes:
+ *
+ *            handle.getSnapshot()  → derived StepGraph (back-compat)
+ *            handle.boundary       → the underlying BoundaryRecorder
+ *                                     (Lens reads it directly for richer
+ *                                     queries: getSlotBoundaries(),
+ *                                     getEventsByType, etc.)
+ *
+ * Event → StepNode mapping (the entire policy):
+ *
+ *   run.entry            → StepNode kind='subflow', primitiveKind='Run'
+ *   subflow.entry        → StepNode kind='subflow' (skipped if isAgentInternal
+ *                                                    or slotKind set —
+ *                                                    those are sub-components
+ *                                                    of the actor arrows)
+ *   fork.branch          → StepNode kind='fork-branch'
+ *   decision.branch      → StepNode kind='decision-branch'
+ *   llm.start            → StepNode kind=actorArrow ('user→llm' | 'tool→llm')
+ *   tool.start           → StepNode kind='llm->tool'
+ *   llm.end terminal     → StepNode kind='llm->user' (delivery marker)
+ *   loop.iteration       → loop-iteration StepEdge
+ *   context.injected     → attached to NEXT user→llm / tool→llm StepNode
+ *
+ * Result: a one-to-one correspondence between visible scrubbable steps
+ * and DomainEvents. Adding a new event type adds one mapping line here
+ * (or in the pure projection); no state machine, no merging.
+ */
+import type { CombinedRecorder } from 'footprintjs';
+import type { EventDispatcher } from '../../events/dispatcher.js';
+import { BoundaryRecorder } from './BoundaryRecorder.js';
+/**
+ * One node in the step-level flowchart. Node kind drives rendering
+ * (actor icon, color). ReAct steps carry token + tool details; topology
+ * nodes (subflow / fork-branch / decision-branch) mirror the footprintjs
+ * composition events and exist so composition structure (Loop, Parallel,
+ * Conditional, Swarm) stays visible in the graph.
+ */
+export interface StepNode {
+    readonly id: string;
+    readonly kind: 'user->llm' | 'llm->tool' | 'tool->llm' | 'llm->user' | 'subflow' | 'fork-branch' | 'decision-branch';
+    readonly label: string;
+    readonly startOffsetMs: number;
+    readonly endOffsetMs?: number;
+    /** LLM step: token usage of the call that bounded this step. */
+    readonly tokens?: {
+        readonly in: number;
+        readonly out: number;
+    };
+    /** llm->tool / tool->llm: the tool name. */
+    readonly toolName?: string;
+    /** user->llm / tool->llm: the model that was invoked. */
+    readonly llmModel?: string;
+    /** Decomposition of the underlying subflowId (rooted under '__root__'). */
+    readonly subflowPath: readonly string[];
+    /** Context injections attributed to this step (LLM steps only). */
+    readonly injections?: readonly ContextInjection[];
+    /** 1-based ReAct iteration this step belongs to. Undefined for
+     *  topology / composition nodes. */
+    readonly iterationIndex?: number;
+    /** Which slot the step's input updated. ReAct steps only. */
+    readonly slotUpdated?: 'system-prompt' | 'messages' | 'tools';
+    /** True ONLY for `subflow` StepNodes whose primitiveKind is `'Agent'`.
+     *  Narrow flag for callers that distinguish ReAct agents from other
+     *  composition primitives (cost / iteration / token attribution). */
+    readonly isAgentBoundary?: boolean;
+    /** Primitive kind from the subflow root description prefix
+     *  (`'Agent'` / `'LLMCall'` / `'Sequence'` / etc.). */
+    readonly primitiveKind?: string;
+    /** True for `subflow` StepNodes representing any KNOWN primitive
+     *  (Agent / LLMCall / Sequence / Parallel / Conditional / Loop) —
+     *  drives Lens's drill-in container treatment. */
+    readonly isPrimitiveBoundary?: boolean;
+    /** `inputMapper` payload at the subflow's entry. Subflow nodes only. */
+    readonly entryPayload?: unknown;
+    /** Subflow shared state at exit. Subflow nodes only.
+     *  Undefined for in-progress / paused subflows. */
+    readonly exitPayload?: unknown;
+    /** Stable per-execution key — same `runtimeStageId` Trace view uses. */
+    readonly runtimeStageId?: string;
+    /**
+     * Slot boundary payloads composed for THIS LLM step.
+     *
+     * Set ONLY for `kind === 'user->llm'` and `kind === 'tool->llm'`
+     * StepNodes — the moments where context flows INTO the LLM. Each
+     * entry carries the slot subflow's `inputMapper` result (entryPayload)
+     * and rendered slot output (exitPayload).
+     *
+     * Attribution: any slot subflow that fired BETWEEN the previous LLM
+     * end (or run start) and THIS LLM start is attributed to this call.
+     * Done at projection time over `boundary.getEvents()`; no consumer-
+     * side correlation required.
+     *
+     * Lens uses this to make the 3 slot rows inside the LLM card
+     * clickable — clicking a slot reveals its entry/exit payloads in
+     * the right-pane detail panel without needing direct BoundaryRecorder
+     * access.
+     */
+    readonly slotBoundaries?: {
+        readonly systemPrompt?: SlotBoundary;
+        readonly messages?: SlotBoundary;
+        readonly tools?: SlotBoundary;
+    };
+}
+/** One slot's boundary pair attributed to a specific LLM step. */
+export interface SlotBoundary {
+    /** runtimeStageId of the slot subflow execution. */
+    readonly runtimeStageId: string;
+    /** `inputMapper` payload — the data the slot was COMPOSED FROM
+     *  (RAG hits, skill content, user message, tool result, etc). */
+    readonly entryPayload?: unknown;
+    /** Subflow shared state at exit — the rendered slot content
+     *  (system prompt string, messages array, tools array). */
+    readonly exitPayload?: unknown;
+}
+/** Consumer-facing context injection (5 axes of context engineering). */
+export interface ContextInjection {
+    readonly slot: 'system-prompt' | 'messages' | 'tools';
+    readonly asRole?: 'system' | 'user' | 'assistant' | 'tool';
+    readonly source: string;
+    readonly sourceId?: string;
+    readonly contentSummary?: string;
+    readonly reason?: string;
+    readonly sectionTag?: string;
+    readonly upstreamRef?: string;
+    readonly retrievalScore?: number;
+    readonly rankPosition?: number;
+    readonly budgetTokens?: number;
+    readonly budgetFraction?: number;
+}
+export interface StepEdge {
+    readonly id: string;
+    readonly from: string;
+    readonly to: string;
+    readonly kind: 'next' | 'loop-iteration' | 'fork-branch' | 'decision-branch';
+    readonly iteration?: number;
+}
+export interface StepGraph {
+    readonly nodes: readonly StepNode[];
+    readonly edges: readonly StepEdge[];
+    readonly activeNodeId?: string;
+}
+export interface FlowchartOptions {
+    /** Called each time the graph changes; fires synchronously on the
+     *  driving event so the UI updates the moment the structure changes. */
+    readonly onUpdate?: (graph: StepGraph) => void;
+}
+export interface FlowchartHandle {
+    /** Current step graph (derived from boundary events). Safe during or
+     *  after a run. */
+    readonly getSnapshot: () => StepGraph;
+    /** Underlying BoundaryRecorder. Use for richer queries — slot data,
+     *  full event log, type-narrowed lookups. The single source of truth
+     *  Lens reads. */
+    readonly boundary: BoundaryRecorder;
+    /** Detach from executor + dispatcher. Subsequent events ignored. */
+    readonly unsubscribe: () => void;
+}
+/**
+ * Attach a live FlowchartRecorder to a runner.
+ *
+ *   1. Creates a `BoundaryRecorder` (the unified domain event log).
+ *   2. Attaches it to the executor's FlowRecorder channel via
+ *      `runnerAttach` — captures run / subflow / fork / decision / loop.
+ *   3. Subscribes it to the dispatcher — captures llm.* / tool.* /
+ *      context.injected.
+ *   4. Wires `onUpdate` so the consumer sees a fresh derived StepGraph
+ *      on every event.
+ *
+ * @internal Called from `RunnerBase.enable.flowchart`.
+ */
+export declare function attachFlowchart(runnerAttach: (recorder: CombinedRecorder) => () => void, dispatcher: EventDispatcher, options?: FlowchartOptions): FlowchartHandle;
+/**
+ * Project a `BoundaryRecorder`'s event stream into a `StepGraph`.
+ *
+ * Pure function — no side effects, no recorder mutation, deterministic.
+ * Called on every snapshot request and on every `onUpdate` fire. O(N)
+ * over the event stream; consumer-side memoization (e.g., React's
+ * `useMemo`) is straightforward when needed.
+ *
+ * The mapping is local to each event type: see the mapping table in
+ * the file header. State carried across the fold:
+ *   - `iter`: 1-based ReAct iteration counter, incremented on each
+ *     `llm.start`. ReAct nodes inherit the current value.
+ *   - `pendingInjections`: context.injected events buffered between
+ *     LLM calls; flushed onto the next user→llm or tool→llm StepNode.
+ *   - `prevReActId`: id of the previous ReAct StepNode for `next`-edge
+ *     wiring within an iteration.
+ *   - `runStartTs`: wall-clock at run start, for relative offsets.
+ */
+export declare function buildStepGraph(boundary: BoundaryRecorder): StepGraph;
+//# sourceMappingURL=FlowchartRecorder.d.ts.map

package/dist/types/recorders/observability/FlowchartRecorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FlowchartRecorder.d.ts","sourceRoot":"","sources":["../../../../src/recorders/observability/FlowchartRecorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,EAAE,gBAAgB,EAA6C,MAAM,uBAAuB,CAAC;AAIpG;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EACT,WAAW,GACX,WAAW,GACX,WAAW,GACX,WAAW,GACX,SAAS,GACT,aAAa,GACb,iBAAiB,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,gEAAgE;IAChE,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAChE,4CAA4C;IAC5C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,mEAAmE;IACnE,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAClD;wCACoC;IACpC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,6DAA6D;IAC7D,QAAQ,CAAC,WAAW,CAAC,EAAE,eAAe,GAAG,UAAU,GAAG,OAAO,CAAC;IAC9D;;yEAEqE;IACrE,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC;2DACuD;IACvD,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;sDAEkD;IAClD,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IACvC,wEAAwE;IACxE,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAChC;uDACmD;IACnD,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,wEAAwE;IACxE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE;QACxB,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC;QACrC,QAAQ,CAAC,QAAQ,CAAC,EAAE,YAAY,CAAC;QACjC,QAAQ,CAAC,KAAK,CAAC,EAAE,YAAY,CAAC;KAC/B,CAAC;CACH;AAED,kEAAkE;AAClE,MAAM,WAAW,YAAY;IAC3B,oDAAoD;IACpD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC;qEACiE;IACjE,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAChC;+DAC2D;IAC3D,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,yEAAyE;AACzE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,eAAe,GAAG,UAAU,GAAG,OAAO,CAAC;IACtD,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC;IAC3D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,aAAa,GAAG,iBAAiB,CAAC;IAC7E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAC;IACpC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,gBAAgB;IAC/B;4EACwE;IACxE,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;CAChD;AAED,MAAM,WAAW,eAAe;IAC9B;uBACmB;IACnB,QAAQ,CAAC,WAAW,EAAE,MAAM,SAAS,CAAC;IACtC;;sBAEkB;IAClB,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,oEAAoE;IACpE,QAAQ,CAAC,WAAW,EAAE,MAAM,IAAI,CAAC;CAClC;AAID;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC7B,YAAY,EAAE,CAAC,QAAQ,EAAE,gBAAgB,KAAK,MAAM,IAAI,EACxD,UAAU,EAAE,eAAe,EAC3B,OAAO,GAAE,gBAAqB,GAC7B,eAAe,CAmCjB;AA0DD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,gBAAgB,GAAG,SAAS,CA+RpE"}

package/dist/types/recorders/observability/LoggingRecorder.d.ts

@@ -0,0 +1,89 @@
+/**
+ * LoggingRecorder — firehose-style structured logging of every event.
+ *
+ * Pattern: Facade over EventDispatcher's wildcard subscription.
+ * Role:    Tier 3 observability — enabled via `agent.enable.logging({...})`.
+ *          Developer debugging tool; production typically uses an OTEL
+ *          recorder instead.
+ * Emits:   Does NOT emit; READS the dispatcher and writes to the logger.
+ *
+ * Filtering: consumer picks DOMAINS by name — the same domain segment that
+ * appears in event types (`agentfootprint.<domain>.<action>`). No internal
+ * tier jargon leaks into the public API.
+ */
+import type { EventDispatcher, Unsubscribe } from '../../events/dispatcher.js';
+import type { AgentfootprintEvent } from '../../events/registry.js';
+/**
+ * Minimal logger shape — structurally compatible with console, winston,
+ * pino, etc. Consumers pass their existing logger.
+ */
+export interface LoggingLogger {
+    log(message: string, data?: unknown): void;
+}
+/**
+ * Domain constants — one per event-registry domain. Use these instead of
+ * raw strings for autocomplete, typo protection, and rename safety.
+ *
+ * Raw strings still work (backed by the same literal union type below).
+ *
+ * @example
+ *   agent.enable.logging({ domains: [LoggingDomains.CONTEXT, LoggingDomains.STREAM] });
+ *   agent.enable.logging({ domains: ['context', 'stream'] }); // equivalent
+ */
+export declare const LoggingDomains: {
+    /** Context-engineering events (the 3-slot model). THE DEBUG CORE. */
+    readonly CONTEXT: "context";
+    /** LLM + tool request/response stream. */
+    readonly STREAM: "stream";
+    /** Composition control flow (Sequence / Parallel / Conditional / Loop). */
+    readonly COMPOSITION: "composition";
+    /** Agent lifecycle (turn · iteration · route_decided · handoff). */
+    readonly AGENT: "agent";
+    /** Memory strategy + store operations. */
+    readonly MEMORY: "memory";
+    /** Tool offered / activated / deactivated. */
+    readonly TOOLS: "tools";
+    /** Skill activation + deactivation. */
+    readonly SKILL: "skill";
+    /** Permission checks + gates. */
+    readonly PERMISSION: "permission";
+    /** Risk / guardrail detections. */
+    readonly RISK: "risk";
+    /** Provider / tool / skill fallback triggers. */
+    readonly FALLBACK: "fallback";
+    /** Cost + budget tracking. */
+    readonly COST: "cost";
+    /** Eval scores + threshold crossings. */
+    readonly EVAL: "eval";
+    /** Error retries + recoveries. */
+    readonly ERROR: "error";
+    /** Pause / resume requests. */
+    readonly PAUSE: "pause";
+    /** Embedding generation. */
+    readonly EMBEDDING: "embedding";
+};
+/**
+ * Domain name — the middle segment of event types
+ * (`agentfootprint.<domain>.<action>`). Consumers already see these in
+ * the events they subscribe to; reusing them here avoids teaching a
+ * new taxonomy.
+ */
+export type LoggingDomain = (typeof LoggingDomains)[keyof typeof LoggingDomains];
+export interface LoggingOptions {
+    /** Logger sink. Defaults to console. */
+    readonly logger?: LoggingLogger;
+    /**
+     * Domains to log. Pass `'all'` for firehose (including consumer custom
+     * events). Default: `['context', 'stream']` — the core debugging lens
+     * (what went into the LLM, what came out).
+     */
+    readonly domains?: readonly LoggingDomain[] | 'all';
+    /** Custom formatter. Default: `[domain.action]`. */
+    readonly format?: (event: AgentfootprintEvent) => string;
+}
+/**
+ * Attach a logging subscription to the event dispatcher.
+ * Returns an Unsubscribe — call to detach.
+ */
+export declare function attachLogging(dispatcher: EventDispatcher, options?: LoggingOptions): Unsubscribe;
+//# sourceMappingURL=LoggingRecorder.d.ts.map

package/dist/types/recorders/observability/LoggingRecorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LoggingRecorder.d.ts","sourceRoot":"","sources":["../../../../src/recorders/observability/LoggingRecorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAC/E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEpE;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CAC5C;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc;IACzB,qEAAqE;;IAErE,0CAA0C;;IAE1C,2EAA2E;;IAE3E,oEAAoE;;IAEpE,0CAA0C;;IAE1C,8CAA8C;;IAE9C,uCAAuC;;IAEvC,iCAAiC;;IAEjC,mCAAmC;;IAEnC,iDAAiD;;IAEjD,8BAA8B;;IAE9B,yCAAyC;;IAEzC,kCAAkC;;IAElC,+BAA+B;;IAE/B,4BAA4B;;CAEpB,CAAC;AAEX;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,OAAO,cAAc,CAAC,CAAC;AAEjF,MAAM,WAAW,cAAc;IAC7B,wCAAwC;IACxC,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,aAAa,EAAE,GAAG,KAAK,CAAC;IACpD,oDAAoD;IACpD,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,MAAM,CAAC;CAC1D;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,eAAe,EAC3B,OAAO,GAAE,cAAmB,GAC3B,WAAW,CAab"}

package/dist/types/recorders/observability/ThinkingRecorder.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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`.
+ */
+import type { EventDispatcher, Unsubscribe } from '../../events/dispatcher.js';
+import type { AgentfootprintEventMap } from '../../events/registry.js';
+export interface ThinkingOptions {
+    /**
+     * Called with a human-readable status string at each meaningful moment
+     * (iteration start, tool start/end, route decision, turn end).
+     */
+    readonly onStatus: (status: string) => void;
+    /**
+     * Custom formatter. Return `null` to skip an event; return a string
+     * to emit that status. Omit for the built-in renderer.
+     */
+    readonly format?: (event: ThinkingEvent) => string | null;
+}
+/**
+ * Subset of events the thinking renderer formats. Discriminated on `type`.
+ */
+export type ThinkingEvent = AgentfootprintEventMap['agentfootprint.agent.turn_start'] | AgentfootprintEventMap['agentfootprint.agent.turn_end'] | AgentfootprintEventMap['agentfootprint.agent.iteration_start'] | AgentfootprintEventMap['agentfootprint.agent.route_decided'] | AgentfootprintEventMap['agentfootprint.stream.tool_start'] | AgentfootprintEventMap['agentfootprint.stream.tool_end'];
+/**
+ * Attach a thinking-status subscription to the event dispatcher.
+ * Returns an Unsubscribe — call to detach.
+ */
+export declare function attachThinking(dispatcher: EventDispatcher, options: ThinkingOptions): Unsubscribe;
+//# sourceMappingURL=ThinkingRecorder.d.ts.map

package/dist/types/recorders/observability/ThinkingRecorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ThinkingRecorder.d.ts","sourceRoot":"","sources":["../../../../src/recorders/observability/ThinkingRecorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAC/E,OAAO,KAAK,EAEV,sBAAsB,EAEvB,MAAM,0BAA0B,CAAC;AAElC,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5C;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,MAAM,GAAG,IAAI,CAAC;CAC3D;AAED;;GAEG;AACH,MAAM,MAAM,aAAa,GACrB,sBAAsB,CAAC,iCAAiC,CAAC,GACzD,sBAAsB,CAAC,+BAA+B,CAAC,GACvD,sBAAsB,CAAC,sCAAsC,CAAC,GAC9D,sBAAsB,CAAC,oCAAoC,CAAC,GAC5D,sBAAsB,CAAC,kCAAkC,CAAC,GAC1D,sBAAsB,CAAC,gCAAgC,CAAC,CAAC;AAW7D;;;GAGG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,eAAe,EAAE,OAAO,EAAE,eAAe,GAAG,WAAW,CAOjG"}

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"}