agentfootprint 6.43.0 → 6.45.0

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 {};

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

@@ -0,0 +1,231 @@
+/**
+ * RunStepRecorder — slider-ready ordered list of RunSteps, BUILT
+ * INCREMENTALLY during traversal. Real-time recorder, not a walker.
+ *
+ * Pattern: extends `SequenceStore<RunStep>` (shared storage shelf)
+ *          and implements `CombinedRecorder` (FlowRecorder hooks).
+ *          Subscribes to the agentfootprint typed-event dispatcher
+ *          for actor-arrow events. Each event handler decides whether
+ *          to emit a step; state lives on the instance and persists
+ *          across the run.
+ * Role:    The single source of truth for "what slider positions
+ *          exist in this run, and what transitions does each light
+ *          up." Lens consumers attach the recorder once and read
+ *          `getSteps()` — no per-render re-derivation.
+ *
+ * Why this matters: the older `buildRunSteps(events)` walker violated
+ * footprintjs's core principle ("collect during traversal, never
+ * post-process"). Each call walked the full event log multiple times;
+ * the playground triggered a full walk on every flowchart update,
+ * yielding O(N²) total work for a streaming run. The recorder pattern
+ * is O(N) — one handler call per event — and matches BoundaryRecorder /
+ * FlowchartRecorder / KeyedStore idioms throughout the library.
+ *
+ * The `buildRunSteps(...)` function is RETAINED as a thin compatibility
+ * shim that constructs a fresh recorder, replays events through it,
+ * and returns the resulting entries. Useful for snapshot-from-saved-
+ * events use cases (replay, testing, post-hoc analysis). Live consumers
+ * should attach the recorder directly via `runner.attach(rec)`.
+ */
+import type { CombinedRecorder, FlowDecisionEvent, FlowForkEvent, FlowLoopEvent, FlowSubflowEvent, TraversalContext } from 'footprintjs';
+interface FlowRunEvent {
+    readonly payload?: unknown;
+    readonly traversalContext?: TraversalContext;
+}
+import type { AgentfootprintEvent } from '../../events/registry.js';
+import type { EventDispatcher, Unsubscribe } from '../../events/dispatcher.js';
+import type { BoundaryRecorder, DomainEvent } from './BoundaryRecorder.js';
+/**
+ * One slider position. The smallest scrubable unit of the run.
+ *
+ * `transitions` is 1+ — fan-out / merge steps light up multiple
+ * transitions at once; sequential / decide / react steps light up
+ * exactly one. Renderers iterate `transitions` to highlight edges;
+ * details panels read `anchor.runtimeStageId`.
+ */
+export interface RunStep {
+    /** 0-based slider index (matches array position in `getSteps()`). */
+    readonly seq: number;
+    readonly kind: RunStepKind;
+    readonly transitions: readonly RunStepTransition[];
+    /**
+     * Per-step key — required by `SequenceStore<T>` for time-travel
+     * utilities (`getEntriesForStep`, `getEntryRanges`). Mirrors
+     * `anchor.runtimeStageId`; both fields point at the same value.
+     * Top-level placement satisfies the recorder's storage contract.
+     */
+    readonly runtimeStageId: string;
+    /** Anchor for commentary highlight + details pane lookup. */
+    readonly anchor: {
+        readonly runtimeStageId: string;
+        readonly subflowPath: readonly string[];
+    };
+    /** Human label — short, kind-specific. */
+    readonly label: string;
+    /** Wall-clock ms at which this step occurred. */
+    readonly tsMs: number;
+    /** Kind-specific decoration. Discriminate on `kind`. */
+    readonly meta?: RunStepMeta;
+}
+export type RunStepKind = 'sequential' | 'fork' | 'merge' | 'decide' | 'iteration' | 'iteration-exit' | 'react';
+export interface RunStepTransition {
+    readonly from: string;
+    readonly to: string;
+    readonly via: 'next' | 'fork-branch' | 'decision-branch' | 'loop-iteration' | 'actor-arrow';
+    readonly label?: string;
+}
+export type RunStepMeta = {
+    readonly kind: 'decide';
+    readonly chosen: string;
+    readonly rationale?: string;
+} | {
+    readonly kind: 'iteration';
+    readonly index: number;
+    readonly target: string;
+} | {
+    readonly kind: 'iteration-exit';
+    readonly index: number;
+    readonly reason?: string;
+} | {
+    readonly kind: 'fork';
+    readonly parentSubflowId: string;
+} | {
+    readonly kind: 'merge';
+    readonly mergedCount: number;
+} | {
+    readonly kind: 'react';
+    readonly actorArrow: 'user→llm' | 'tool→llm' | 'llm→tool' | 'llm→user';
+};
+export interface RunStepRecorderOptions {
+    readonly id?: string;
+}
+/** Factory — matches the `boundaryRecorder()` / `topologyRecorder()` style. */
+export declare function runStepRecorder(options?: RunStepRecorderOptions): RunStepRecorder;
+/**
+ * Real-time slider-step recorder. Emits a `RunStep` whenever an event
+ * marks a meaningful slider transition. State persists on the instance
+ * so successive events update bookkeeping in O(1).
+ *
+ * Attach via `runner.attach(rec)` for FlowRecorder events; call
+ * `rec.subscribe(runner.dispatcher)` for actor-arrow events. The
+ * `getSteps(drillPath?)` method returns the already-built list (no
+ * walking) with optional drill-scope filtering.
+ */
+export declare class RunStepRecorder implements CombinedRecorder {
+    readonly id: string;
+    /** Composition: storage shelf for the slider-step sequence. */
+    private readonly store;
+    /** Run-boundary observer — fires this.clear() when traversalContext.runId
+     *  changes between events. THIS IS THE FIX for the Parallel multi-run
+     *  aliasing bug — without it `forkKey = ${parent}@${rid}` collides
+     *  because rid resets to `seed#0` on each run. */
+    private readonly runIdGuard;
+    /** Stack of currently-open boundaries. The recorder owns this
+     *  directly because it's a simple stack and frames are recorder-
+     *  shaped. */
+    private boundaryStack;
+    /** Fork-emission coalescing + branch-exit tally. */
+    private readonly forks;
+    /** Tracks the most-recent leaf exit per depth → "forwards" handoff. */
+    private readonly siblings;
+    /** Buffers a "this MIGHT be the answer" leaf until onRunEnd. */
+    private readonly answerBuffer;
+    /** Run-root inference state machine (leaf vs composition). */
+    private readonly rootInferrer;
+    /** llm.start / llm.end actor-arrow classifier. */
+    private readonly actorArrows;
+    /** Has the first `asks` step fired? */
+    private asksEmitted;
+    constructor(options?: RunStepRecorderOptions);
+    /**
+     * Emit a RunStep, auto-mirroring `anchor.runtimeStageId` to the
+     * top-level `runtimeStageId` field that the keyed index uses. Single
+     * source of truth (the anchor) — never inconsistent with the storage
+     * key.
+     */
+    private push;
+    /** Internal seq-numbering helper — mirrors the store size so each
+     *  RunStep gets a unique 0-based index in emit order. */
+    private get entryCount();
+    clear(): void;
+    /** Internal — wipe all per-run state WITHOUT resetting the runIdGuard
+     *  itself. Called by `clear()` (which then resets the guard) AND by
+     *  the runIdGuard's onNewRun callback (where the guard is mid-update
+     *  and must NOT be reset, only the recorder's data should be).
+     *
+     *  Note: each sub-tracker owns its OWN clear; the orchestrator just
+     *  fans out. Adding new state to a sub-tracker requires no edit here. */
+    private resetForNewRun;
+    private observeRunId;
+    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
+     * `react` RunStep on every `llm.start` / `llm.end`. The recorder
+     * classifies `actorArrow` locally (mirrors BoundaryRecorder's
+     * pattern) so consumers don't have to depend on BoundaryRecorder's
+     * own subscription order.
+     */
+    subscribe(dispatcher: EventDispatcher): Unsubscribe;
+    /** Internal — also called by `ingestDomainEvent` for shim replay.
+     *
+     *  NOTE: deliberately does NOT call observeRunId(event.meta.runId).
+     *  The agentfootprint dispatcher's runId is a DIFFERENT generator
+     *  than footprintjs's traversalContext.runId — mixing them would
+     *  toggle lastRunId on every event and trigger a false reset.
+     *  Run-boundary detection happens reliably on the FlowRecorder side
+     *  (onRunStart fires FIRST in any new run before any typed event). */
+    protected ingestTypedEvent(event: AgentfootprintEvent): void;
+    /**
+     * Feed a single recorded `DomainEvent` (from BoundaryRecorder) into
+     * this recorder as if it had fired live. Used by `buildRunSteps`
+     * for snapshot replay; tests use it for fixture-driven projection.
+     *
+     * Live consumers should use `runner.attach(rec)` +
+     * `rec.subscribe(dispatcher)` instead — the recorder's hooks fire
+     * naturally during traversal.
+     */
+    ingestDomainEvent(e: DomainEvent): void;
+    /**
+     * Read-only query — returns the already-built step list filtered to
+     * `drillPath` scope. O(1) per call when scope is empty; O(N) filter
+     * otherwise. Composition-vs-leaf root filter is applied so the
+     * slider semantics match the user's mental model:
+     *
+     *   - **Leaf root** (single Agent / LLMCall): show `react` steps only.
+     *   - **Composition root** (Sequence / Parallel / Conditional / Loop):
+     *     show composition steps; hide intra-leaf `react` steps.
+     *
+     * Drill-down filters by `anchor.subflowPath` prefix and re-applies
+     * the leaf-vs-composition rule for the drilled scope.
+     */
+    getSteps(drillPath?: readonly string[]): readonly RunStep[];
+    /** Flush any deferred answer-candidate from the buffer. Called by
+     *  `onRunEnd` so a single `answers` step appears for runs that end
+     *  on a leaf exit (no further leaf entries followed). */
+    private flushCandidateAnswer;
+}
+export interface RunStepGraph {
+    readonly steps: readonly RunStep[];
+}
+export interface BuildRunStepsOptions {
+    readonly drillPath?: readonly string[];
+}
+/**
+ * Compatibility shim for snapshot-from-events use cases (replay,
+ * post-hoc analysis, tests). For LIVE use, prefer attaching a
+ * `RunStepRecorder` directly via `runner.attach(rec)` —
+ * `buildRunSteps(events)` constructs a fresh recorder, replays the
+ * events through its handlers, and returns the resulting entries.
+ *
+ * @deprecated Prefer `runStepRecorder()` + `runner.attach(rec)` for
+ *             live consumers. This shim remains for offline / testing
+ *             scenarios where only a recorded event list is available.
+ */
+export declare function buildRunSteps(source: BoundaryRecorder | readonly DomainEvent[], options?: BuildRunStepsOptions): RunStep[];
+export {};

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

@@ -0,0 +1,36 @@
+/**
+ * StatusRecorder — Claude Code-style live status line for Agent runs.
+ *
+ * Pattern: Facade over EventDispatcher's wildcard subscription.
+ * Role:    Tier 3 observability — the low-level helper behind
+ *          `attachStatus(dispatcher, { onStatus })` (exported from
+ *          `agentfootprint/observe`). For the high-level, uniform path use
+ *          `agent.enable.liveStatus({ strategy: chatBubbleLiveStatus({ onLine }) })`.
+ *          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 StatusOptions {
+    /**
+     * 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: StatusEvent) => string | null;
+}
+/**
+ * Subset of events the thinking renderer formats. Discriminated on `type`.
+ */
+export type StatusEvent = 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 attachStatus(dispatcher: EventDispatcher, options: StatusOptions): Unsubscribe;

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

@@ -0,0 +1,164 @@
+/**
+ * toolChoiceRecorder — runtime tool-choice margins (RFC-002 tier 2,
+ * blocks C4–C6).
+ *
+ * Per LLM call that OFFERED tools, this recorder captures the menu the
+ * model saw (`stream.llm_start.tools`), what it actually invoked
+ * (`stream.tool_start`), and the choice context — then, LAZILY on first
+ * read, ranks the offered candidates against that context via
+ * influence-core's `scoreMargin` (C4):
+ *
+ *   margin = score(best chosen) − score(best non-chosen)
+ *
+ * Small margin (`narrow`, < `marginThreshold`, default 0.05) = the
+ * choice was a close call under the proxy. Top-scored candidate not
+ * among the chosen (`proxyDisagreement`) is ALWAYS flagged — either a
+ * proxy miss or a genuinely surprising model choice; both are exactly
+ * what a debugger wants surfaced.
+ *
+ * ## The choice context (C4 — what is embedded, precisely)
+ *
+ * `buildChoiceContext` assembles the SAME two slots the model's
+ * tool-selection reasoning ran on:
+ *
+ *   INCLUDED
+ *   1. the user message of the current turn (`agent.turn_start.userPrompt`)
+ *      — the task the model is choosing a tool FOR (first
+ *      `maxSlotChars` chars: the head states the task);
+ *   2. the latest assistant reasoning text — the most recent
+ *      `stream.llm_end.content` of this turn, when present (last
+ *      `maxSlotChars` chars: the tail is where "what next" lives).
+ *      Iteration 1 has no assistant text; the slot is omitted.
+ *
+ *   EXCLUDED (deliberately)
+ *   - the system prompt: constant across every call of the run — zero
+ *     per-call discrimination, it only dilutes the embedding;
+ *   - older history turns: recency dominates tool choice, and the full
+ *     transcript grows the embedding cost linearly with run length;
+ *   - raw tool results: the model reads them, but their distilled
+ *     effect on the NEXT choice is the assistant's own reasoning text,
+ *     which IS included; raw payloads skew the embedding toward data
+ *     vocabulary (the honest-proxy discipline: mirror the
+ *     decision-relevant text, not every visible byte);
+ *   - tool schemas: those are the CANDIDATES being ranked, not context.
+ *
+ * Candidate text per offered tool = `confusabilityText` (tokenized name
+ * + description) — the SAME construction the catalog lint (C1) embeds,
+ * so build-time confusability and runtime margins measure one geometry.
+ *
+ * ## Laziness (C5)
+ *
+ * Event hooks only RECORD (string copies into a KeyedStore). The
+ * embedder runs on the first `getCalls()` / `getFlagged()` /
+ * `getSummary()` — embedding I/O NEVER rides the hot path, even when
+ * the recorder is attached inline. Scores memoize per entry. Attach
+ * with `{ delivery: 'deferred' }` (footprintjs RFC-001) to move the
+ * bookkeeping off the hot path too — it is a normal CombinedRecorder.
+ *
+ * Pattern: CombinedRecorder (Convention 1 — single purpose: tool-choice
+ *          margin evidence). Owns a `KeyedStore<ToolChoiceEntry>` keyed
+ *          by the LLM call's `runtimeStageId`. Convention 4: resets on a
+ *          new `runId` via `FlowRecorder.onRunStart`.
+ * Role:    Tier-3 /observe recorder. Attach via `Agent.create(...)
+ *          .recorder(handle)` or `executor.attachCombinedRecorder`.
+ *
+ * Honest claim (RFC-002 §2): margins are embedding geometry between the
+ * context and tool descriptions — a deterministic PROXY for the model's
+ * selection function, never "the model chose because". Tier 3
+ * (choice-entropy sampling) validates the proxy.
+ */
+import type { EmitEvent } from 'footprintjs';
+import { type Embedder, type MarginResult } from '../../lib/influence-core/index.js';
+/** Minimal structural slice of footprintjs's FlowRunEvent (runId is all
+ *  we read — Convention 4). */
+interface RunBoundaryEvent {
+    readonly traversalContext?: {
+        readonly runId?: string;
+    };
+}
+/** One offered tool, as the model saw it on `llm_start`. */
+export interface OfferedTool {
+    readonly name: string;
+    readonly description?: string;
+}
+/** Why an entry has no margin. */
+export type ToolChoiceSkipReason = 
+/** The model answered without invoking any tool — no choice to score. */
+'nothing-chosen'
+/** A chosen tool name was not in the offered catalog (wiring anomaly —
+ *  surfaced, not silently massaged). */
+ | 'chosen-not-offered';
+/** One LLM call that offered tools — the recorder's public row shape. */
+export interface ToolChoiceCall {
+    /** runtimeStageId of the LLM-call stage (the KeyedStore key). */
+    readonly runtimeStageId: string;
+    readonly iteration: number;
+    /** The catalog the model saw, in request order. */
+    readonly offered: readonly OfferedTool[];
+    /** Unique tool names actually invoked, in first-call order. */
+    readonly chosen: readonly string[];
+    /** Every invocation (parallel calls + repeat calls of one tool visible). */
+    readonly toolCallIds: readonly string[];
+    /** The choice context that was (or will be) embedded. */
+    readonly contextText: string;
+    /** Ranked scores + margin + flags. Undefined until scored, or when
+     *  `skipped` says why it never will be. */
+    readonly margin?: MarginResult;
+    readonly skipped?: ToolChoiceSkipReason;
+}
+/** Run-summary counts (C6). */
+export interface ToolChoiceSummary {
+    /** LLM calls that offered tools (= recorded entries). */
+    readonly llmCallsWithTools: number;
+    /** Entries where the model invoked at least one tool. */
+    readonly choices: number;
+    /** Entries with a computed `margin`. */
+    readonly scored: number;
+    /** narrow OR proxy-disagreement. */
+    readonly flagged: number;
+    readonly narrow: number;
+    readonly proxyDisagreement: number;
+    /** Entries that will never score (`skipped` set). */
+    readonly skipped: number;
+}
+export interface ToolChoiceRecorderOptions {
+    /**
+     * Injected embedder — runs ONLY on first read (lazy). Wrap in
+     * `embeddingCache(...)` (agentfootprint/observe) so repeated tool
+     * descriptions embed once across calls and runs.
+     */
+    readonly embedder: Embedder;
+    /** Margins below this flag `narrow`. Default 0.05 (RFC-002 §4). */
+    readonly marginThreshold?: number;
+    /** Per-slot cap for the choice context. Default 2000 chars. */
+    readonly maxSlotChars?: number;
+    /** Recorder id (default 'tool-choice'). */
+    readonly id?: string;
+}
+export interface ToolChoiceRecorderHandle {
+    readonly id: string;
+    /** All recorded LLM calls (scored on demand — first call runs the
+     *  embedder; results memoize). Entries still open mid-run stay
+     *  unscored until they close. */
+    getCalls(): Promise<readonly ToolChoiceCall[]>;
+    /** Calls whose choice was fragile: `narrow` margin OR
+     *  `proxyDisagreement` (always flagged) — C6. */
+    getFlagged(): Promise<readonly ToolChoiceCall[]>;
+    /** Run-summary counts (C6). Scores pending entries first. */
+    getSummary(): Promise<ToolChoiceSummary>;
+    clear(): void;
+    onEmit(event: EmitEvent): void;
+    onRunStart(event: RunBoundaryEvent): void;
+    onRunEnd(event: RunBoundaryEvent): void;
+    onRunFailed(event: RunBoundaryEvent): void;
+}
+/** C4: the precise choice-context construction (see module JSDoc for the
+ *  include/exclude rationale). Exported so consumers can reproduce it. */
+export declare function buildChoiceContext(args: {
+    readonly userPrompt: string;
+    readonly latestAssistantText?: string;
+    readonly maxSlotChars?: number;
+}): string;
+/** Build the tool-choice margin recorder (C5). */
+export declare function toolChoiceRecorder(options: ToolChoiceRecorderOptions): ToolChoiceRecorderHandle;
+export {};

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

@@ -0,0 +1,71 @@
+/**
+ * ToolLineageRecorder — derives the tool→tool DATA-FLOW graph of a run.
+ *
+ * Why this exists: in a ReAct agent a tool's output flows back to the LLM as
+ * text, and the LLM decides the NEXT tool's arguments — so the data dependency
+ * between tools (e.g. FLOGI's FCID reused as io_profile's `initiator_id`) never
+ * touches footprintjs's shared scope, and `causalChain` can't reconstruct it.
+ * This recorder rebuilds that graph from the tool emit stream by VALUE
+ * PROVENANCE: when a tool call's argument value equals a distinctive value
+ * produced by an EARLIER iteration's tool result, it records an edge
+ * (producer → consumer).
+ *
+ * It is a HEURISTIC, not ground truth — it matches by value, so it is accurate
+ * for distinctive identifiers (FCIDs, WWPNs, ids, NAAs, hostnames) and
+ * deliberately conservative:
+ *   - short / common values (below `minValueLength`) are ignored,
+ *   - numbers are ignored by default (coincidental matches are likely),
+ *   - same-iteration (parallel) tool calls never link to each other — the LLM
+ *     chose all their args from the same prior context, before any of them ran.
+ *
+ * No core changes: it consumes the existing `agentfootprint.stream.tool_start`
+ * (args) and `agentfootprint.stream.tool_end` (result) emits. Attach via
+ * `.recorder(toolLineageRecorder())` and read `getLineage()` after the run; the
+ * lens (or any consumer) can render the returned graph.
+ *
+ * Convention 1 — one purpose: it derives ONE artifact (the lineage graph) from
+ * the emit channel. Convention 4 — run-scoped: it resets when a new run starts
+ * (the `pipelineId` changes).
+ */
+import type { EmitRecorder } from 'footprintjs';
+/** A single tool invocation in the run. */
+export interface ToolCallRef {
+    /** The execution-step id this tool call ran under. */
+    readonly runtimeStageId: string;
+    /** The provider tool-call id (stable per call). */
+    readonly toolCallId: string;
+    /** The tool's name. */
+    readonly toolName: string;
+    /** The ReAct iteration the call belongs to (0-based). */
+    readonly iteration: number;
+}
+/** A value-derived data dependency: `from`'s result value reappeared in `to`'s args. */
+export interface ToolLineageEdge {
+    readonly from: ToolCallRef;
+    readonly to: ToolCallRef;
+    /** The distinctive value that links them. */
+    readonly value: string;
+}
+/** The tool→tool data-flow graph for one run. */
+export interface ToolLineageGraph {
+    readonly nodes: readonly ToolCallRef[];
+    readonly edges: readonly ToolLineageEdge[];
+}
+export interface ToolLineageOptions {
+    /** Recorder id (idempotent-by-id when attached). Default `'tool-lineage'`. */
+    readonly id?: string;
+    /** Minimum string length for a value to be matchable. Default 4. */
+    readonly minValueLength?: number;
+    /** Also match numeric values. Default false (coincidental matches likely). */
+    readonly matchNumbers?: boolean;
+    /** Max recursion depth when flattening args/results. Default 6. */
+    readonly maxDepth?: number;
+}
+/** An EmitRecorder that also exposes the derived lineage graph. */
+export interface ToolLineageRecorderHandle extends EmitRecorder {
+    /** The tool→tool data-flow graph derived so far. Safe to call during or after a run. */
+    getLineage(): ToolLineageGraph;
+    /** Reset all accumulated state. */
+    clear(): void;
+}
+export declare function toolLineageRecorder(options?: ToolLineageOptions): ToolLineageRecorderHandle;