agentfootprint 1.23.0 → 2.1.0

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

@@ -0,0 +1,301 @@
+/**
+ * BoundaryRecorder — unified domain event log for an agentfootprint run.
+ *
+ * The single source of truth Lens (and any other consumer) reads to
+ * render a run. Every observable moment in a run is captured as one
+ * `DomainEvent` in a single ordered stream:
+ *
+ *   - `run.entry` / `run.exit`              — top-level executor.run()
+ *   - `subflow.entry` / `subflow.exit`      — every subflow boundary
+ *   - `fork.branch`                         — one per parallel child
+ *   - `decision.branch`                     — chosen branch of a Conditional
+ *   - `loop.iteration`                      — one per back-edge traversal
+ *   - `llm.start` / `llm.end`               — LLM provider call lifecycle
+ *   - `tool.start` / `tool.end`             — tool execution lifecycle
+ *   - `context.injected`                    — anything injected into a slot
+ *
+ * All events carry `runtimeStageId` (binds with footprintjs Trace view +
+ * with each other), `subflowPath`, `depth`, and `ts` (wall-clock ms).
+ * Subflow events are domain-tagged (`slotKind` / `primitiveKind` /
+ * `isAgentInternal`) so consumers dispatch on tag without re-parsing.
+ *
+ * Architecture:
+ *
+ *   ┌──── footprintjs (domain-agnostic) ────┐
+ *   │  FlowRecorder events (run/subflow/    │  ──┐
+ *   │  fork/decision/loop)                  │    │
+ *   └───────────────────────────────────────┘    │
+ *                                                │
+ *   ┌──── agentfootprint dispatcher ─────────┐   │  consumed by
+ *   │  Typed events (llm/tool/context)       │  ──┤
+ *   └────────────────────────────────────────┘   │
+ *                                                ▼
+ *                                  ┌─── BoundaryRecorder ───┐
+ *                                  │  one tagged stream of  │
+ *                                  │  DomainEvent           │
+ *                                  └────────────────────────┘
+ *                                                │
+ *                                                ▼  consumed by
+ *                                  ┌────── Lens (UI) ──────┐
+ *                                  │  Slider / RunFlow /   │
+ *                                  │  NodeDetail / etc.    │
+ *                                  └───────────────────────┘
+ *
+ * Why ONE recorder: Lens scrub axis, run-flow graph, slot rows inside
+ * the LLM card, right-pane detail panel, commentary panel — every UI
+ * surface reads from the SAME stream. Adding a new domain event = one
+ * tagged emit + one render shape. No state machines spread across
+ * renderers, no merging of multiple sources, no name-based filter lists.
+ *
+ * Naming: `runtimeStageId` is footprintjs's primitive (path-prefixed +
+ * `#executionIndex`). `subflowPath` is rooted under the synthetic
+ * `'__root__'`. `slotKind` / `primitiveKind` are agent-domain. The
+ * design follows the React Fiber + OpenTelemetry pattern:
+ * **producers self-describe; consumers dispatch on type**.
+ *
+ * @example
+ * ```typescript
+ * import { boundaryRecorder } from 'agentfootprint';
+ *
+ * const boundary = boundaryRecorder();
+ * executor.attachCombinedRecorder(boundary);   // wires FlowRecorder side
+ * boundary.subscribe(runner.dispatcher);        // wires typed-event side
+ *
+ * await executor.run({ input });
+ *
+ * for (const e of boundary.getEvents()) {
+ *   switch (e.type) {
+ *     case 'run.entry':       renderRoot(e); break;
+ *     case 'subflow.entry':   if (e.slotKind) renderSlotRow(e);
+ *                              else if (e.primitiveKind) renderPrimitive(e);
+ *                              break;
+ *     case 'llm.start':       renderLLMCall(e); break;
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+import { SequenceRecorder } from 'footprintjs/trace';
+import type { CombinedRecorder, FlowDecisionEvent, FlowForkEvent, FlowLoopEvent, FlowSubflowEvent, TraversalContext } from 'footprintjs';
+interface FlowRunEvent {
+    readonly payload?: unknown;
+    readonly traversalContext?: TraversalContext;
+}
+import type { EventDispatcher, Unsubscribe } from '../../events/dispatcher.js';
+import type { ContextSlot } from '../../events/types.js';
+/** Fields every domain event carries. */
+interface DomainEventBase {
+    /** Stable per-execution key (footprintjs primitive). For run events it
+     *  is `'__root__#0'`; subflow events use the parent stage's runtimeStageId
+     *  at mount; typed events use the firing stage's runtimeStageId. */
+    readonly runtimeStageId: string;
+    /** Decomposition of `subflowId` into segments, rooted under `'__root__'`. */
+    readonly subflowPath: readonly string[];
+    /** Depth in the run tree — root = 0, top-level subflow = 1, etc. */
+    readonly depth: number;
+    /** Wall-clock ms at capture time. */
+    readonly ts: number;
+}
+export interface DomainRunEvent extends DomainEventBase {
+    readonly type: 'run.entry' | 'run.exit';
+    readonly payload?: unknown;
+    /** Always `true` for run events — convenience flag for filter callers. */
+    readonly isRoot: true;
+}
+export interface DomainSubflowEvent extends DomainEventBase {
+    readonly type: 'subflow.entry' | 'subflow.exit';
+    /** Path-prefixed engine id (matches `FlowSubflowEvent.subflowId`). */
+    readonly subflowId: string;
+    /** Last segment of `subflowId` — convenience for leaf-name grouping. */
+    readonly localSubflowId: string;
+    readonly subflowName: string;
+    /** Build-time description from the subflow root (`'<Kind>: <detail>'`). */
+    readonly description?: string;
+    /** Parsed `'<Kind>:'` prefix — `'Agent'`, `'LLMCall'`, `'Sequence'`, etc. */
+    readonly primitiveKind?: string;
+    /** Set ONLY for the 3 input-slot subflows (sf-system-prompt / sf-messages / sf-tools). */
+    readonly slotKind?: ContextSlot;
+    /** True for Agent state-machine routing/wrapper subflows (route, tool-calls, final, merge). */
+    readonly isAgentInternal: boolean;
+    /** `inputMapper` result on entry; subflow shared state on exit. */
+    readonly payload?: unknown;
+}
+export interface DomainForkBranchEvent extends DomainEventBase {
+    readonly type: 'fork.branch';
+    readonly parentSubflowId: string;
+    readonly childName: string;
+}
+export interface DomainDecisionBranchEvent extends DomainEventBase {
+    readonly type: 'decision.branch';
+    readonly decider: string;
+    readonly chosen: string;
+    readonly rationale?: string;
+    /**
+     * `true` when this decision comes from one of the Agent's internal
+     * routing stages (e.g., the ReAct `Route` decider that picks
+     * `tool-calls` vs `final`). Filtered out of the timeline by
+     * `buildStepGraph` — the actor arrows that follow already encode
+     * the routing observably (`llm→tool` vs `llm→user`).
+     *
+     * `false` when the decision comes from a consumer-defined
+     * `Conditional` primitive — those ARE meaningful timeline steps.
+     */
+    readonly isAgentInternal: boolean;
+}
+export interface DomainLoopIterationEvent extends DomainEventBase {
+    readonly type: 'loop.iteration';
+    readonly target: string;
+    readonly iteration: number;
+}
+/**
+ * The 4 actor arrows of a ReAct cycle. Tagged on `llm.start` / `llm.end`
+ * at capture time so consumers (slider, run-flow renderer) dispatch by
+ * `event.actorArrow` instead of running their own state machine.
+ *
+ *   - `'user→llm'` — first LLM call, or any LLM call NOT preceded by a
+ *     tool result (assembled-context delivery to the model).
+ *   - `'tool→llm'` — LLM call that follows a tool's result (the next
+ *     iteration of a ReAct loop).
+ *   - `'llm→tool'` — `llm.end` whose `toolCallCount > 0` (the LLM is
+ *     requesting tool execution).
+ *   - `'llm→user'` — `llm.end` with `toolCallCount === 0` (terminal
+ *     response delivered to the user).
+ */
+export type ActorArrow = 'user→llm' | 'tool→llm' | 'llm→tool' | 'llm→user';
+export interface DomainLLMStartEvent extends DomainEventBase {
+    readonly type: 'llm.start';
+    readonly model: string;
+    readonly provider: string;
+    readonly systemPromptChars?: number;
+    readonly messagesCount?: number;
+    readonly toolsCount?: number;
+    /** Capture-time classification: `'user→llm'` for the first call or any
+     *  call not preceded by a tool result; `'tool→llm'` after a tool result. */
+    readonly actorArrow: 'user→llm' | 'tool→llm';
+}
+export interface DomainLLMEndEvent extends DomainEventBase {
+    readonly type: 'llm.end';
+    readonly content: string;
+    readonly toolCallCount: number;
+    readonly usage: {
+        readonly input: number;
+        readonly output: number;
+    };
+    readonly stopReason?: string;
+    /** Capture-time classification: `'llm→tool'` when the LLM requested
+     *  tools (`toolCallCount > 0`); `'llm→user'` for terminal delivery. */
+    readonly actorArrow: 'llm→tool' | 'llm→user';
+}
+export interface DomainToolStartEvent extends DomainEventBase {
+    readonly type: 'tool.start';
+    readonly toolName: string;
+    readonly toolCallId: string;
+    readonly args?: unknown;
+}
+export interface DomainToolEndEvent extends DomainEventBase {
+    readonly type: 'tool.end';
+    readonly toolCallId: string;
+    readonly result?: unknown;
+    readonly durationMs?: number;
+    readonly error?: boolean;
+}
+export interface DomainContextInjectedEvent extends DomainEventBase {
+    readonly type: 'context.injected';
+    readonly slot: ContextSlot;
+    readonly source: string;
+    readonly sourceId?: string;
+    readonly asRole?: 'system' | 'user' | 'assistant' | 'tool';
+    readonly contentSummary?: string;
+    readonly reason?: string;
+    readonly sectionTag?: string;
+    readonly upstreamRef?: string;
+    readonly retrievalScore?: number;
+    readonly rankPosition?: number;
+    /** Tokens consumed by this injection (from `budgetSpent.tokens`). */
+    readonly budgetTokens?: number;
+    /** Fraction of slot cap consumed (from `budgetSpent.fractionOfCap`). */
+    readonly budgetFraction?: number;
+}
+/** Discriminated union covering every observable moment in a run. */
+export type DomainEvent = DomainRunEvent | DomainSubflowEvent | DomainForkBranchEvent | DomainDecisionBranchEvent | DomainLoopIterationEvent | DomainLLMStartEvent | DomainLLMEndEvent | DomainToolStartEvent | DomainToolEndEvent | DomainContextInjectedEvent;
+export interface BoundaryRecorderOptions {
+    readonly id?: string;
+}
+/** Factory — matches the `inOutRecorder()` / `topologyRecorder()` style. */
+export declare function boundaryRecorder(options?: BoundaryRecorderOptions): BoundaryRecorder;
+/**
+ * Unified domain event recorder. Implements `CombinedRecorder` so it can
+ * attach to the executor's FlowRecorder channel; exposes `subscribe()`
+ * to wire to the agentfootprint typed-event dispatcher.
+ *
+ * Internally stores events in a `SequenceRecorder<DomainEvent>` so the
+ * usual time-travel utilities (`getEntryRanges`, `accumulate`) work
+ * out of the box.
+ */
+export declare class BoundaryRecorder extends SequenceRecorder<DomainEvent> implements CombinedRecorder {
+    readonly id: string;
+    /**
+     * Tracks whether the most recent `llm.end` had toolCalls. Used to
+     * classify the NEXT `llm.start` as `'tool→llm'` (vs `'user→llm'` if
+     * there's no pending tool result). Reset on `clear()` and on every
+     * `llm.start` event after the classification is applied.
+     */
+    private prevLLMEndHadTools;
+    constructor(options?: BoundaryRecorderOptions);
+    clear(): void;
+    onRunStart(event: FlowRunEvent): void;
+    onRunEnd(event: FlowRunEvent): void;
+    onSubflowEntry(event: FlowSubflowEvent): void;
+    onSubflowExit(event: FlowSubflowEvent): void;
+    onFork(event: FlowForkEvent): void;
+    onDecision(event: FlowDecisionEvent): void;
+    onLoop(event: FlowLoopEvent): void;
+    /**
+     * Subscribe to the runner's typed-event dispatcher and emit a domain
+     * event for each `llm.*` / `tool.*` / `context.injected` event.
+     *
+     * Returns an unsubscribe function; safe to call multiple times (each
+     * call adds a new subscription). Most consumers call this once at
+     * recorder construction and dispose with the returned function.
+     */
+    subscribe(dispatcher: EventDispatcher): Unsubscribe;
+    private ingestTypedEvent;
+    /** All events in capture order (the canonical projection). */
+    getEvents(): DomainEvent[];
+    /** Type-narrowed lookup: all events of one kind. */
+    getEventsByType<T extends DomainEvent['type']>(type: T): Extract<DomainEvent, {
+        type: T;
+    }>[];
+    /** All boundary events (run + subflow, entry + exit interleaved). */
+    getBoundaries(): (DomainRunEvent | DomainSubflowEvent)[];
+    /** Just the entry-phase boundary events — the "step list" timeline. */
+    getSteps(): (DomainRunEvent | DomainSubflowEvent)[];
+    /** Subset of `getSteps()` excluding agent-internal routing subflows. */
+    getVisibleSteps(): (DomainRunEvent | DomainSubflowEvent)[];
+    /** Entry/exit pair for one chart execution by `runtimeStageId`. */
+    getBoundary(runtimeStageId: string): {
+        entry?: DomainRunEvent | DomainSubflowEvent;
+        exit?: DomainRunEvent | DomainSubflowEvent;
+    };
+    /** Convenience for the outermost `__root__` pair. */
+    getRootBoundary(): {
+        entry?: DomainRunEvent;
+        exit?: DomainRunEvent;
+    };
+    /** Subflow events grouped by the 3 input slots — for slot-row rendering. */
+    getSlotBoundaries(): {
+        systemPrompt: DomainSubflowEvent[];
+        messages: DomainSubflowEvent[];
+        tools: DomainSubflowEvent[];
+    };
+    /** Snapshot bundle — included in `executor.getSnapshot()` if the
+     *  executor implements the snapshot extension protocol. */
+    toSnapshot(): {
+        name: string;
+        description: string;
+        preferredOperation: "translate";
+        data: DomainEvent[];
+    };
+}
+export {};
+//# sourceMappingURL=BoundaryRecorder.d.ts.map

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

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

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

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