agentfootprint 6.44.0 → 6.45.0

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

@@ -0,0 +1,220 @@
+/**
+ * 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, type DomainEvent } 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;
+    /** LLM's text content. Set on `llm->tool` (the reasoning emitted with the
+     *  tool_use blocks) and on `llm->user` (the terminal answer). */
+    readonly assistantText?: string;
+    /** Tool input arguments the LLM produced. Set on `llm->tool` from the
+     *  matching `tool.start` event payload. */
+    readonly toolArgs?: unknown;
+    /** Tool result returned to the LLM. Set on `tool->llm` from the
+     *  preceding `tool.end` event payload. */
+    readonly toolResult?: 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;
+/**
+ * Pure events → StepGraph fold. Same projection as `buildStepGraph`, but from a
+ * flat `DomainEvent[]` rather than a live `BoundaryRecorder` — so an offline
+ * `Trace` (which stores only events) can be rebuilt into a graph for `<Replay>`
+ * without re-running the agent. The graph is always derived, never stored.
+ */
+export declare function buildStepGraphFromEvents(events: readonly DomainEvent[]): StepGraph;

package/dist/esm/recorders/observability/LiveStateRecorder.d.ts

@@ -0,0 +1,250 @@
+/**
+ * LiveStateRecorder — domain trackers built on the footprintjs
+ * `BoundaryStateStore<TState>` storage primitive (v4.17.2+).
+ *
+ * **What this answers:** "Right now, mid-run, what's happening?"
+ *
+ *   - Is an LLM call in flight? What's the partial answer so far?
+ *   - Is a tool executing? Which tool? What args?
+ *   - Is the agent in a turn? Which turn index?
+ *
+ * All reads are O(1) — the trackers maintain incremental state via
+ * the framework's bracket-scoped storage primitive. No event-log fold,
+ * no walking arrays per render.
+ *
+ * **Mental model — observers vs. bookkeepers:**
+ *
+ *   `BoundaryStateStore<TState>` (footprintjs) = STORAGE shelf.
+ *   `EventDispatcher.on(...)` (agentfootprint)  = OBSERVER source.
+ *
+ *   Each domain tracker (`LiveLLMTracker`, `LiveToolTracker`,
+ *   `LiveAgentTurnTracker`) extends the storage shelf AND subscribes
+ *   to the dispatcher. The composition `LiveStateRecorder` bundles
+ *   all three so a consumer only attaches once.
+ *
+ * **Tier 1 (live) only.** Past states are not stored — when a boundary
+ * closes, its transient state clears. For time-travel queries, snapshot
+ * to a `SequenceStore<TState>` instead. See the BoundaryStateStore
+ * JSDoc for the rationale.
+ *
+ * @example Use the bundled façade — one attach, three live views:
+ *
+ * ```typescript
+ * import { LiveStateRecorder } from 'agentfootprint';
+ *
+ * const liveState = new LiveStateRecorder();
+ * liveState.subscribe(runner);
+ *
+ * await runner.run({ input });
+ *
+ * // Read at any moment during the run (e.g., from another async task):
+ * liveState.isLLMInFlight();          // true between llm_start ↔ llm_end
+ * liveState.getPartialLLM();          // accumulated tokens so far
+ * liveState.isToolExecuting();        // true between tool_start ↔ tool_end
+ * liveState.isAgentInTurn();          // true between turn_start ↔ turn_end
+ *
+ * liveState.unsubscribe();
+ * ```
+ *
+ * @example Use a single tracker directly when you only need one slice:
+ *
+ * ```typescript
+ * import { LiveLLMTracker } from 'agentfootprint';
+ *
+ * const llm = new LiveLLMTracker();
+ * llm.subscribe(runner);
+ * await runner.run({ input });
+ *
+ * llm.isInFlight();                   // O(1)
+ * llm.getLatestPartial();             // most recent active call's partial
+ * llm.getActive(rid)?.tokens;         // tokens accumulated for one call
+ * ```
+ */
+import type { Unsubscribe } from '../../events/dispatcher.js';
+import type { AgentfootprintEvent, AgentfootprintEventType } from '../../events/registry.js';
+/** Minimal Runner shape this recorder needs — only the public `on(...)`
+ *  subscription method, so the same trackers can attach to a real Runner
+ *  (Agent, etc.) OR to a test mock without exposing the protected
+ *  internal dispatcher. */
+export interface LiveStateRunnerLike {
+    on<K extends AgentfootprintEventType>(type: K, listener: (event: Extract<AgentfootprintEvent, {
+        type: K;
+    }>) => void): Unsubscribe;
+}
+/** Live transient state of one in-flight LLM call. */
+export interface LLMLiveState {
+    /** Accumulated content from `stream.token` events since `llm_start`. */
+    readonly partial: string;
+    /** Number of tokens received so far. */
+    readonly tokens: number;
+    /** Iteration index (from the LLMStartPayload). */
+    readonly iteration: number;
+    /** Provider name (e.g., 'anthropic', 'openai'). */
+    readonly provider: string;
+    /** Model id. */
+    readonly model: string;
+    /** Wall-clock ms when llm_start fired. */
+    readonly startedAtMs: number;
+}
+/** Live transient state of one in-flight tool call. */
+export interface ToolLiveState {
+    readonly toolName: string;
+    readonly args: Readonly<Record<string, unknown>>;
+    readonly toolCallId: string;
+    readonly startedAtMs: number;
+}
+/** Live transient state of one in-flight agent turn. */
+export interface AgentTurnLiveState {
+    readonly turnIndex: number;
+    readonly userPrompt: string;
+    readonly startedAtMs: number;
+}
+/**
+ * Tracks the in-flight state of LLM calls. Subscribes to:
+ *   - `agentfootprint.stream.llm_start`  → opens a boundary
+ *   - `agentfootprint.stream.token`      → appends to partial
+ *   - `agentfootprint.stream.llm_end`    → closes the boundary
+ *
+ * Boundary key: `runtimeStageId` of the call-llm stage. Parallel LLM
+ * calls (Parallel composition with multiple branches) get distinct
+ * keys and are tracked independently.
+ */
+export declare class LiveLLMTracker {
+    readonly id = "live-llm";
+    /** Composition: bracket-scoped storage primitive. */
+    private readonly store;
+    /** Wipes the store when a fresh run reuses identical runtimeStageId keys. */
+    private readonly runIdGuard;
+    private observeRunId;
+    /** Subscribe to a runner's dispatcher. Returns an Unsubscribe. */
+    subscribe(runner: LiveStateRunnerLike): Unsubscribe;
+    /** Reset all transient state. Called by `LiveStateRecorder.clear()`. */
+    clear(): void;
+    /** True if any LLM call is currently in flight. */
+    isInFlight(): boolean;
+    /** Same as `store.hasActive` — exposed for parity with the v4 API. */
+    get hasActive(): boolean;
+    /** Number of currently-active boundaries. */
+    get activeCount(): number;
+    /** Currently-active boundary state for one runtimeStageId. */
+    getActive(runtimeStageId: string): LLMLiveState | undefined;
+    /** All currently-active boundaries. */
+    getAllActive(): ReadonlyMap<string, LLMLiveState>;
+    /** Accumulated partial content of the MOST RECENTLY started active
+     *  LLM call. Empty string when no call is active. Useful for the
+     *  classic "Chatbot is responding: …" live commentary line. */
+    getLatestPartial(): string;
+}
+/**
+ * Tracks in-flight tool calls. Subscribes to:
+ *   - `agentfootprint.stream.tool_start` → opens a boundary
+ *   - `agentfootprint.stream.tool_end`   → closes the boundary
+ *
+ * Boundary key: `toolCallId` (more granular than `runtimeStageId` —
+ * parallel tools share one calling stage but have distinct toolCallIds).
+ */
+export declare class LiveToolTracker {
+    readonly id = "live-tool";
+    private readonly store;
+    private readonly runIdGuard;
+    private observeRunId;
+    subscribe(runner: LiveStateRunnerLike): Unsubscribe;
+    clear(): void;
+    /** True if any tool is currently executing. */
+    isExecuting(): boolean;
+    get hasActive(): boolean;
+    get activeCount(): number;
+    getActive(toolCallId: string): ToolLiveState | undefined;
+    getAllActive(): ReadonlyMap<string, ToolLiveState>;
+    /** Names of tools currently executing. Empty when none. */
+    getExecutingToolNames(): readonly string[];
+}
+/**
+ * Tracks in-flight agent turns. Subscribes to:
+ *   - `agentfootprint.agent.turn_start` → opens a boundary
+ *   - `agentfootprint.agent.turn_end`   → closes the boundary
+ *
+ * Boundary key: stringified `turnIndex` from the payload — survives
+ * across runner instances because turnIndex resets per-session.
+ */
+export declare class LiveAgentTurnTracker {
+    readonly id = "live-agent-turn";
+    private readonly store;
+    private readonly runIdGuard;
+    private observeRunId;
+    subscribe(runner: LiveStateRunnerLike): Unsubscribe;
+    clear(): void;
+    /** True if the agent is currently inside a turn. */
+    isInTurn(): boolean;
+    get hasActive(): boolean;
+    get activeCount(): number;
+    getActive(turnIndex: string): AgentTurnLiveState | undefined;
+    getAllActive(): ReadonlyMap<string, AgentTurnLiveState>;
+    /** Index of the most-recently started active turn (-1 if none). */
+    getCurrentTurnIndex(): number;
+}
+/**
+ * One-stop façade bundling `LiveLLMTracker` + `LiveToolTracker` +
+ * `LiveAgentTurnTracker`. Consumers attach this once and get O(1)
+ * reads across all three live-state slices.
+ *
+ * Use the bundled façade unless you ONLY need one slice — using a
+ * single tracker directly avoids subscribing to events you don't read.
+ *
+ * **Lifecycle**: call `subscribe(runner)` to wire all three trackers,
+ * then `unsubscribe()` to detach. `clear()` resets all transient state
+ * across the three (called automatically by consumers like Lens between
+ * runs).
+ *
+ * **What this is NOT for:**
+ *   - Time-travel queries (Tier 1 only — live state)
+ *   - Aggregations (use SequenceStore.aggregate)
+ *   - Stage-level observation (use Recorder.onStageStart/End)
+ *
+ * **Composition over inheritance:** the façade does NOT extend
+ * `BoundaryStateStore` itself — different boundary kinds need
+ * separate active maps to avoid key collisions between LLM and tool
+ * boundaries. Each sub-tracker keeps its own state.
+ */
+export declare class LiveStateRecorder {
+    readonly id = "live-state";
+    /** LLM call live state. */
+    readonly llm: LiveLLMTracker;
+    /** Tool execution live state. */
+    readonly tool: LiveToolTracker;
+    /** Agent turn live state. */
+    readonly turn: LiveAgentTurnTracker;
+    /** Active subscription disposer, if `subscribe()` is called. */
+    private active;
+    constructor();
+    /** Subscribe all three trackers to one runner. Idempotent — calling
+     *  twice on the same recorder unsubscribes the prior subscription
+     *  first to avoid double-counting.
+     *
+     *  Adds a wildcard `*` listener that observes runId on EVERY event
+     *  (regardless of which tracker subscribes to it) and calls
+     *  `clear()` on all three trackers when the runId changes. This
+     *  closes the gap where a tracker that never saw events in run 1
+     *  would fail to reset in run 2. */
+    subscribe(runner: LiveStateRunnerLike): Unsubscribe;
+    /** Detach all three trackers from the current runner. Idempotent. */
+    unsubscribe(): void;
+    /** Reset transient state across all three trackers. Called by the
+     *  executor / consumer between runs. */
+    clear(): void;
+    /** True if any LLM call is currently in flight. */
+    isLLMInFlight(): boolean;
+    /** Accumulated partial content of the most-recently started LLM call. */
+    getPartialLLM(): string;
+    /** True if any tool is currently executing. */
+    isToolExecuting(): boolean;
+    /** Names of tools currently executing. */
+    getExecutingToolNames(): readonly string[];
+    /** True if the agent is currently inside a turn. */
+    isAgentInTurn(): boolean;
+    /** Current turn index (-1 if not in a turn). */
+    getCurrentTurnIndex(): number;
+}
+/** Convenience factory — same shape as `boundaryRecorder()` /
+ *  `topologyRecorder()` / `inOutRecorder()` in footprintjs. */
+export declare function liveStateRecorder(): LiveStateRecorder;

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

@@ -0,0 +1,91 @@
+/**
+ * LoggingRecorder — firehose-style structured logging of every event.
+ *
+ * Pattern: Facade over EventDispatcher's wildcard subscription.
+ * Role:    Tier 3 observability — the low-level helper behind
+ *          `attachLogging(dispatcher, {...})` (exported from
+ *          `agentfootprint/observe`). For the high-level, uniform path use
+ *          `agent.enable.observability({ strategy: consoleObservability() })`.
+ *          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
+ *   attachLogging(dispatcher, { domains: [LoggingDomains.CONTEXT, LoggingDomains.STREAM] });
+ *   attachLogging(dispatcher, { 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;

package/dist/esm/recorders/observability/RouteRecorder.d.ts

@@ -0,0 +1,83 @@
+/**
+ * routeRecorder — records the skill-graph route a run actually took.
+ *
+ * A passive observer that reconstructs, hop by hop, which skill the agent was in,
+ * where it went next, and WHY — by COMPOSING already-shipped events (no engine
+ * change): `agentfootprint.context.evaluated` (its `routing[]` carries via/from/
+ * label per active skill-graph injection) + `agentfootprint.skill.rejected` (an
+ * out-of-reach read_skill) + `stream.tool_start` (the tool that drove a hop).
+ *
+ * Also folds in the GREY-AREA GOVERNORS (observability tier): it detects
+ * oscillation (A→B→A→B within `pingPongWindow`) and a run of consecutive rejected
+ * `read_skill` jumps (`maxRejectedRetries`), reported via `getTrips()`. These LABEL
+ * the trace (`onTrip:'stay'` semantics) — the hard "always stops" guarantee remains
+ * the agent's iteration cap; a runtime force-stop is a deferred follow-on.
+ *
+ * Pattern: CombinedRecorder (Convention 1 — single purpose: route evidence). Owns a
+ *          `SequenceStore<RouteHop>`. Convention 4: resets on a new `runId`.
+ * Role:    Tier-3 /observe recorder — `Agent.create(...).recorder(routeRecorder())`.
+ *          Powers the lens, the "Why this skill?" panel, and paper route figures.
+ */
+import type { EmitEvent } from 'footprintjs';
+interface RunBoundaryEvent {
+    readonly traversalContext?: {
+        readonly runId?: string;
+    };
+}
+/** How the graph arrived at a skill on a hop. */
+export type RouteOutcome = 'entry' | 'route' | 'stay' | 'rejected';
+/** One hop of the route — the skill the graph was in at one iteration + how. */
+export interface RouteHop {
+    /** runtimeStageId of the iteration (the SequenceStore key). */
+    readonly runtimeStageId: string;
+    readonly iteration: number;
+    /** The skill before this hop (undefined at cold start). */
+    readonly fromSkill?: string;
+    /** The skill after this hop (undefined for a pure rejection). */
+    readonly toSkill?: string;
+    readonly outcome: RouteOutcome;
+    /** A human-readable reason for this hop (see `formatRouteHop`). */
+    readonly why: string;
+    /** The route edge's caption, when one drove the hop. */
+    readonly edgeLabel?: string;
+    /** The tool whose result drove the hop (most recent tool_start). */
+    readonly lastTool?: string;
+    /** Rejection only — the skill the model tried to jump to. */
+    readonly requestedSkill?: string;
+    /** Rejection only — the reachable set it was bounded to. */
+    readonly reachable?: readonly string[];
+}
+/** A governor trip — the route is misbehaving. */
+export type RouteTripKind = 'ping-pong' | 'rejected-cap';
+export interface RouteTrip {
+    readonly kind: RouteTripKind;
+    readonly iteration: number;
+    readonly skills: readonly string[];
+    readonly detail: string;
+}
+export interface RouteRecorderOptions {
+    readonly id?: string;
+    /** Window for oscillation detection (a [X,Y,X,Y] pattern trips). Default 4. */
+    readonly pingPongWindow?: number;
+    /** Consecutive rejected read_skill jumps before a `rejected-cap` trip. Default 3. */
+    readonly maxRejectedRetries?: number;
+}
+export interface RouteRecorderHandle {
+    readonly id: string;
+    /** The distinct skill sequence the run moved through (the "route"). */
+    getPath(): readonly string[];
+    /** Every hop, in order. */
+    getHops(): readonly RouteHop[];
+    /** The rejected read_skill attempts (out-of-reach jumps). */
+    getRejections(): readonly RouteHop[];
+    /** Governor trips (oscillation / rejected-retry cap). */
+    getTrips(): readonly RouteTrip[];
+    clear(): void;
+    onEmit(event: EmitEvent): void;
+    onRunStart(event: RunBoundaryEvent): void;
+}
+/** A human-readable one-line reason for a hop. Exported (pure). */
+export declare function formatRouteHop(hop: RouteHop): string;
+/** Build the route recorder. */
+export declare function routeRecorder(options?: RouteRecorderOptions): RouteRecorderHandle;
+export {};