agentfootprint 6.44.0 → 6.45.0

package/dist/esm/recorders/core/ContextRecorder.d.ts

@@ -0,0 +1,47 @@
+/**
+ * ContextRecorder — observes footprintjs subflow + scope events, emits
+ * grouped `context.*` domain events via the EventDispatcher.
+ *
+ * Pattern: Observer (GoF) + Pipes & Filters (Hohpe & Woolf, 2003).
+ * Role:    Core semantic grouping layer for the 3-slot model. Watches
+ *          slot subflows (sf-system-prompt / sf-messages / sf-tools) and
+ *          translates raw writes into context.injected / evicted /
+ *          slot_composed / budget_pressure events.
+ * Emits:   agentfootprint.context.injected
+ *          agentfootprint.context.evicted
+ *          agentfootprint.context.slot_composed
+ *          agentfootprint.context.budget_pressure
+ */
+import type { CombinedRecorder, FlowSubflowEvent, WriteEvent } from 'footprintjs';
+import type { EventDispatcher } from '../../events/dispatcher.js';
+import { type RunContext } from '../../bridge/eventMeta.js';
+/**
+ * Supplies the recorder with run-level context. Passed at construction
+ * time (static fields) OR updated via `updateRunContext` between runs
+ * when reusing one recorder across multiple executor runs.
+ */
+export interface ContextRecorderOptions {
+    readonly dispatcher: EventDispatcher;
+    readonly id?: string;
+    readonly getRunContext: () => RunContext;
+}
+export declare class ContextRecorder implements CombinedRecorder {
+    readonly id: string;
+    private readonly dispatcher;
+    private readonly getRunContext;
+    private readonly seenInjections;
+    constructor(options: ContextRecorderOptions);
+    onSubflowEntry(event: FlowSubflowEvent): void;
+    onSubflowExit(event: FlowSubflowEvent): void;
+    onWrite(event: WriteEvent): void;
+    private handleInjectionsWrite;
+    private handleSlotComposedWrite;
+    private handleEvictionsWrite;
+    private handleBudgetPressureWrite;
+    private emitInjected;
+    private dispatch;
+    private asInjectionArray;
+    private asSlotComposition;
+    private asEvictionArray;
+    private asPressureArray;
+}

package/dist/esm/recorders/core/CostRecorder.d.ts

@@ -0,0 +1,14 @@
+/**
+ * CostRecorder — forwards `agentfootprint.cost.*` emits to the dispatcher.
+ *
+ * Pattern: Factory (GoF) returning an EmitBridge instance.
+ * Role:    Bridges `cost.tick` + `cost.limit_hit` emits from LLMCall / Agent
+ *          stages (via `emitCostTick`) to the EventDispatcher so typed
+ *          consumer listeners fire.
+ * Emits:   agentfootprint.cost.tick / cost.limit_hit
+ */
+import { EmitBridge, type EmitBridgeOptions } from './EmitBridge.js';
+export type CostRecorderOptions = Omit<EmitBridgeOptions, 'id' | 'prefix'> & {
+    readonly id?: string;
+};
+export declare function costRecorder(options: CostRecorderOptions): EmitBridge;

package/dist/esm/recorders/core/EmitBridge.d.ts

@@ -0,0 +1,30 @@
+/**
+ * EmitBridge — forwards footprintjs emits whose name starts with a given
+ * prefix to the EventDispatcher, enriched with EventMeta.
+ *
+ * Pattern: Adapter (GoF) + Pipes & Filters (Hohpe & Woolf, 2003).
+ * Role:    Single reusable translation layer for every "pass-through"
+ *          prefix recorder (StreamRecorder, AgentRecorder, and any
+ *          future domain whose events are emitted via typedEmit()).
+ * Emits:   Any event whose name matches `prefix` — type derived from the
+ *          emit name and validated by the consumer's EventMap subscription.
+ */
+import type { CombinedRecorder, EmitEvent } from 'footprintjs';
+import type { EventDispatcher } from '../../events/dispatcher.js';
+import { type RunContext } from '../../bridge/eventMeta.js';
+export interface EmitBridgeOptions {
+    readonly dispatcher: EventDispatcher;
+    /** Recorder id — must be unique among attached recorders. */
+    readonly id: string;
+    /** Event-name prefix this bridge forwards (e.g. 'agentfootprint.stream.'). */
+    readonly prefix: string;
+    readonly getRunContext: () => RunContext;
+}
+export declare class EmitBridge implements CombinedRecorder {
+    readonly id: string;
+    private readonly dispatcher;
+    private readonly prefix;
+    private readonly getRunContext;
+    constructor(options: EmitBridgeOptions);
+    onEmit(event: EmitEvent): void;
+}

package/dist/esm/recorders/core/ErrorBridge.d.ts

@@ -0,0 +1,38 @@
+/**
+ * ErrorBridge — translates footprintjs's STRUCTURAL `onRunFailed` (the
+ * terminal run-boundary event fired when a run throws a non-pause error)
+ * into agentfootprint's TYPED `agentfootprint.error.fatal` domain event.
+ *
+ * Pattern: Adapter (GoF) — same role as EmitBridge, different channel.
+ * Role:    Close the "failed run is invisible" gap. footprintjs fires
+ *          `onError` (stage-level) + `onRunFailed` (run-level) on the
+ *          FlowRecorder channel, but agentfootprint's typed consumers
+ *          (LiveStateRecorder clearing in-flight, monitors setting
+ *          status) listen on the DISPATCHER. Without a bridge, a thrown
+ *          LLM call left `isLLMInFlight()` stuck true ("Chatbot is
+ *          thinking…" forever) and downstream STATUS showed "ok". This
+ *          re-dispatches one terminal typed event so every consumer
+ *          reacts uniformly.
+ * Emits:   agentfootprint.error.fatal (once per failed top-level run).
+ *
+ * Fires at the TOP LEVEL only — footprintjs `onRunFailed` is a run
+ * boundary, not a per-stage event. Subflow errors propagate up and
+ * surface here once.
+ */
+import type { CombinedRecorder, FlowRunFailedEvent } from 'footprintjs';
+import type { EventDispatcher } from '../../events/dispatcher.js';
+import { type RunContext } from '../../bridge/eventMeta.js';
+export interface ErrorBridgeOptions {
+    readonly dispatcher: EventDispatcher;
+    /** Recorder id — must be unique among attached recorders. */
+    readonly id?: string;
+    readonly getRunContext: () => RunContext;
+}
+export declare class ErrorBridge implements CombinedRecorder {
+    readonly id: string;
+    private readonly dispatcher;
+    private readonly getRunContext;
+    constructor(options: ErrorBridgeOptions);
+    onRunFailed(event: FlowRunFailedEvent): void;
+}
+export declare function errorBridge(options: ErrorBridgeOptions): ErrorBridge;

package/dist/esm/recorders/core/EvalRecorder.d.ts

@@ -0,0 +1,16 @@
+/**
+ * EvalRecorder — forwards `agentfootprint.eval.*` emits to the dispatcher.
+ *
+ * Pattern: Factory over EmitBridge.
+ * Role:    Bridges consumer-emitted `eval.score` + `eval.threshold_crossed`
+ *          events to typed listeners. Evaluation is a consumer concern
+ *          (LLM-based grading, heuristic checks, reference-output diffs),
+ *          so the library only provides transport — not any built-in
+ *          evaluators.
+ * Emits:   agentfootprint.eval.score / eval.threshold_crossed
+ */
+import { EmitBridge, type EmitBridgeOptions } from './EmitBridge.js';
+export type EvalRecorderOptions = Omit<EmitBridgeOptions, 'id' | 'prefix'> & {
+    readonly id?: string;
+};
+export declare function evalRecorder(options: EvalRecorderOptions): EmitBridge;

package/dist/esm/recorders/core/MemoryRecorder.d.ts

@@ -0,0 +1,17 @@
+/**
+ * MemoryRecorder — forwards `agentfootprint.memory.*` emits to the dispatcher.
+ *
+ * Pattern: Factory over EmitBridge.
+ * Role:    Bridges memory-layer events (strategy_applied, attached,
+ *          detached, written) emitted by consumer memory adapters.
+ *          The library does not ship a memory implementation; consumers
+ *          plug in their own store and emit these events where relevant
+ *          (e.g., before/after sliding-window summarization).
+ * Emits:   agentfootprint.memory.strategy_applied / attached /
+ *          detached / written
+ */
+import { EmitBridge, type EmitBridgeOptions } from './EmitBridge.js';
+export type MemoryRecorderOptions = Omit<EmitBridgeOptions, 'id' | 'prefix'> & {
+    readonly id?: string;
+};
+export declare function memoryRecorder(options: MemoryRecorderOptions): EmitBridge;

package/dist/esm/recorders/core/PermissionRecorder.d.ts

@@ -0,0 +1,16 @@
+/**
+ * PermissionRecorder — forwards `agentfootprint.permission.*` emits
+ * to the dispatcher.
+ *
+ * Pattern: Factory over EmitBridge.
+ * Role:    Bridges permission.check, permission.gate_opened, and
+ *          permission.gate_closed emits into the typed dispatcher so
+ *          consumer `.on('agentfootprint.permission.check', ...)`
+ *          listeners fire.
+ * Emits:   agentfootprint.permission.check / gate_opened / gate_closed
+ */
+import { EmitBridge, type EmitBridgeOptions } from './EmitBridge.js';
+export type PermissionRecorderOptions = Omit<EmitBridgeOptions, 'id' | 'prefix'> & {
+    readonly id?: string;
+};
+export declare function permissionRecorder(options: PermissionRecorderOptions): EmitBridge;

package/dist/esm/recorders/core/ReliabilityRecorder.d.ts

@@ -0,0 +1,24 @@
+/**
+ * ReliabilityRecorder — forwards `agentfootprint.reliability.*` emits to
+ * the dispatcher.
+ *
+ * Pattern: Factory (GoF) returning an EmitBridge instance.
+ * Role:    Bridges the rules-based reliability loop's telemetry
+ *          (`reliability.fail_fast` / `reliability.retried` /
+ *          `reliability.recovered`, emitted from `executeWithReliability`
+ *          via `typedEmit`) to the EventDispatcher so typed consumer
+ *          listeners (`agent.on('agentfootprint.reliability.retried', …)`)
+ *          fire. Without this bridge those emits hit the footprintjs emit
+ *          channel but never reach the dispatcher.
+ * Emits:   agentfootprint.reliability.fail_fast / retried / recovered
+ *
+ * NOTE: this is the RULES-LOOP family. The generic `error.retried` /
+ * `error.recovered` events are reserved for the standalone provider
+ * decorators (withRetry/withFallback) and are NOT bridged here — see
+ * docs/MENTAL_MODEL.md §14.
+ */
+import { EmitBridge, type EmitBridgeOptions } from './EmitBridge.js';
+export type ReliabilityRecorderOptions = Omit<EmitBridgeOptions, 'id' | 'prefix'> & {
+    readonly id?: string;
+};
+export declare function reliabilityRecorder(options: ReliabilityRecorderOptions): EmitBridge;

package/dist/esm/recorders/core/SkillRecorder.d.ts

@@ -0,0 +1,14 @@
+/**
+ * SkillRecorder — forwards `agentfootprint.skill.*` emits to the dispatcher.
+ *
+ * Pattern: Factory over EmitBridge.
+ * Role:    Bridges skill lifecycle events (activated, deactivated) emitted
+ *          by consumer skill-management code. Skills are a consumer-owned
+ *          context-engineering concern; the library only provides transport.
+ * Emits:   agentfootprint.skill.activated / skill.deactivated
+ */
+import { EmitBridge, type EmitBridgeOptions } from './EmitBridge.js';
+export type SkillRecorderOptions = Omit<EmitBridgeOptions, 'id' | 'prefix'> & {
+    readonly id?: string;
+};
+export declare function skillRecorder(options: SkillRecorderOptions): EmitBridge;

package/dist/esm/recorders/core/StreamRecorder.d.ts

@@ -0,0 +1,15 @@
+/**
+ * StreamRecorder — forwards `agentfootprint.stream.*` emits to the dispatcher.
+ *
+ * Pattern: Factory (GoF) returning an EmitBridge instance.
+ * Role:    Convenience constructor for the stream-domain bridge recorder.
+ *          Stage code in LLMCall/Agent calls `typedEmit(scope, 'agentfootprint.stream.llm_start', {...})`;
+ *          this recorder observes via footprintjs's EmitRecorder channel
+ *          and re-dispatches with typed payloads + enriched meta.
+ * Emits:   agentfootprint.stream.llm_start / llm_end / token / tool_start / tool_end
+ */
+import { EmitBridge, type EmitBridgeOptions } from './EmitBridge.js';
+export type StreamRecorderOptions = Omit<EmitBridgeOptions, 'id' | 'prefix'> & {
+    readonly id?: string;
+};
+export declare function streamRecorder(options: StreamRecorderOptions): EmitBridge;

package/dist/esm/recorders/core/ToolsRecorder.d.ts

@@ -0,0 +1,18 @@
+/**
+ * ToolsRecorder — forwards `agentfootprint.tools.*` emits to the dispatcher.
+ *
+ * Pattern: Factory over EmitBridge.
+ * Role:    Bridges tool-domain events. Today: discovery_failed (emitted by
+ *          buildToolsSlot when an external `ToolProvider.list(ctx)` throws
+ *          or rejects). The other tools.* events (offered/activated/
+ *          deactivated) are declared in the registry for consumer code
+ *          that wants to emit them; the same prefix bridge forwards all
+ *          of them.
+ * Emits:   agentfootprint.tools.offered / tools.activated / tools.deactivated
+ *          / tools.discovery_failed
+ */
+import { EmitBridge, type EmitBridgeOptions } from './EmitBridge.js';
+export type ToolsRecorderOptions = Omit<EmitBridgeOptions, 'id' | 'prefix'> & {
+    readonly id?: string;
+};
+export declare function toolsRecorder(options: ToolsRecorderOptions): EmitBridge;

package/dist/esm/recorders/core/ValidationRecorder.d.ts

@@ -0,0 +1,16 @@
+/**
+ * ValidationRecorder — forwards `agentfootprint.validation.*` emits to the
+ * dispatcher.
+ *
+ * Pattern: Factory over EmitBridge.
+ * Role:    Bridges tool-args validation events (#9) emitted by the
+ *          toolCalls stage when LLM-produced args fail the tool's declared
+ *          `inputSchema` — so consumers observe rejected/warned calls via
+ *          `agent.on('agentfootprint.validation.args_invalid', ...)`.
+ * Emits:   agentfootprint.validation.args_invalid
+ */
+import { EmitBridge, type EmitBridgeOptions } from './EmitBridge.js';
+export type ValidationRecorderOptions = Omit<EmitBridgeOptions, 'id' | 'prefix'> & {
+    readonly id?: string;
+};
+export declare function validationRecorder(options: ValidationRecorderOptions): EmitBridge;

package/dist/esm/recorders/core/contextEngineering.d.ts

@@ -0,0 +1,136 @@
+/**
+ * contextEngineering(agent) — first-class handle on the engineered
+ * subset of `context.injected` events.
+ *
+ * The Block A8 piece. agentfootprint already emits `context.injected`
+ * for EVERY piece of content that lands in a slot — including the
+ * baseline flow (the user message, every tool result, the static
+ * system prompt). For a developer who wants to inspect what their
+ * RAG / Skills / Memory / Instructions / Steering / Facts ARE
+ * INJECTING (the actual context-engineering work), the baseline flow
+ * is noise.
+ *
+ * `contextEngineering(agent)` filters the stream to ONLY the
+ * engineered injections and gives consumers two cleaner subscriptions:
+ *
+ *   - `onEngineered(cb)` — fires for `source` ∈ {rag, skill, memory,
+ *     instructions, steering, fact, custom}. The actual
+ *     context-engineering work.
+ *   - `onBaseline(cb)` — fires for `source` ∈ {user, tool-result,
+ *     assistant, base, registry}. The baseline message-history flow.
+ *
+ * Use cases:
+ *   - **Lens UI**: render only engineered injections in the "context
+ *     bin"; show the baseline flow as edges between iterations.
+ *   - **Eval pipelines**: count how many RAG chunks vs Memory entries
+ *     vs Skill bodies entered the prompt for an eval-set query.
+ *   - **Cost attribution**: sum tokens by `source` to know what
+ *     fraction of spend is RAG vs Skills vs baseline.
+ *   - **Debug logging**: tail just the engineered signals to spot
+ *     surprising activations during dev.
+ *
+ * Pattern: Strategy + Filter (GoF) — pure classifier function over
+ *          the existing `context.injected` event payload, paired with
+ *          a thin subscription helper.
+ *
+ * Role:    Layer-2 (event taxonomy) consumer-side helper. Doesn't
+ *          emit new events; doesn't change the agent's flowchart.
+ *          Pure observation.
+ *
+ * @example
+ *   import { contextEngineering } from 'agentfootprint';
+ *
+ *   const ce = contextEngineering(agent);
+ *   ce.onEngineered((e) => {
+ *     console.log(`[${e.payload.source}] ${e.payload.contentSummary}`);
+ *   });
+ *   ce.onBaseline((e) => {
+ *     console.log(`[baseline:${e.payload.source}]`);
+ *   });
+ *
+ *   await agent.run({ message: 'help me' });
+ *   // ... runs; engineered + baseline streams fire separately
+ *
+ *   ce.detach();   // stops both subscriptions; the agent itself is fine
+ */
+import type { AgentfootprintEventMap } from '../../events/registry.js';
+import type { ContextSource } from '../../events/types.js';
+/**
+ * Public set of "engineered" sources — the context-engineering
+ * primitives that consumers configure (RAG, Skills, Memory,
+ * Instructions, Steering, Facts) plus user-defined `custom`.
+ *
+ * Frozen so consumers can `.has(value)` directly without copy.
+ */
+export declare const ENGINEERED_SOURCES: ReadonlySet<ContextSource>;
+/**
+ * Public set of "baseline" sources — the message-history flow that
+ * exists regardless of context engineering: user input, tool results,
+ * assistant outputs, the always-on system prompt anchor (`base`), and
+ * the agent's static tool registry advertisement (`registry`).
+ */
+export declare const BASELINE_SOURCES: ReadonlySet<ContextSource>;
+/**
+ * Pure classifier: given a `ContextSource`, is it engineered?
+ *
+ * Useful for ad-hoc filtering on a raw `agent.on('agentfootprint.context.injected', ...)`
+ * subscription when you don't need the wrapper helper.
+ */
+export declare function isEngineeredSource(source: ContextSource): boolean;
+/**
+ * Pure classifier: given a `ContextSource`, is it baseline?
+ */
+export declare function isBaselineSource(source: ContextSource): boolean;
+/**
+ * The shape of the event passed to `onEngineered` / `onBaseline`
+ * callbacks. Same as `agentfootprint.context.injected`'s envelope —
+ * we don't transform it, just route by source.
+ */
+export type ContextInjectedEvent = AgentfootprintEventMap['agentfootprint.context.injected'];
+/** Listener signature for the wrapper helper. */
+export type ContextInjectedListener = (event: ContextInjectedEvent) => void;
+/** Unsubscribe handle. */
+export type ContextEngineeringUnsubscribe = () => void;
+/**
+ * Minimal subset of the agent surface this helper depends on.
+ * Lets us accept any runner (Agent, LLMCall, Sequence, etc.) that
+ * implements the typed `on(type, cb)` subscription API.
+ */
+interface RunnerWithEvents {
+    on(type: 'agentfootprint.context.injected', listener: ContextInjectedListener): ContextEngineeringUnsubscribe;
+}
+/**
+ * Handle returned by `contextEngineering(agent)`. Lets consumers
+ * subscribe to engineered / baseline streams and detach cleanly.
+ */
+export interface ContextEngineeringHandle {
+    /**
+     * Fires for `context.injected` events whose source is in
+     * `ENGINEERED_SOURCES`. Returns an unsubscribe function.
+     */
+    onEngineered(listener: ContextInjectedListener): ContextEngineeringUnsubscribe;
+    /**
+     * Fires for `context.injected` events whose source is in
+     * `BASELINE_SOURCES`. Returns an unsubscribe function.
+     */
+    onBaseline(listener: ContextInjectedListener): ContextEngineeringUnsubscribe;
+    /**
+     * Detach all subscriptions registered through this handle. After
+     * calling, no further callbacks will fire. Idempotent (safe to
+     * call multiple times).
+     */
+    detach(): void;
+}
+/**
+ * Wrap a runner's `agentfootprint.context.injected` stream into two
+ * filtered subscriptions: engineered + baseline. Multiple listeners
+ * per stream are allowed; `detach()` removes all of them.
+ *
+ * The classifier inspects `event.payload.source`. Unknown sources
+ * (forward-compat: `ContextSource` is open-extensible) are routed
+ * to NEITHER stream — preferring under-firing over miscategorizing.
+ * Use `agent.on('agentfootprint.context.injected', ...)` directly
+ * if you need to observe sources that aren't (yet) classified.
+ */
+export declare function contextEngineering(agent: RunnerWithEvents): ContextEngineeringHandle;
+export {};

package/dist/esm/recorders/core/typedEmit.d.ts

@@ -0,0 +1,34 @@
+/**
+ * typedEmit — typed facade over footprintjs's `scope.$emit(name, payload)`.
+ *
+ * Pattern: Facade (GoF) over an untyped API.
+ * Role:    Stage code inside LLMCall/Agent/slot subflows calls this helper
+ *          to emit events. The EventMap + TS generics reject typos and
+ *          payload drift at compile time; the runtime call is identical
+ *          to footprintjs's `$emit`.
+ * Emits:   Whatever `T` is — the consumer passes the type and payload.
+ */
+import type { AgentfootprintEventMap, AgentfootprintEventType } from '../../events/registry.js';
+/**
+ * Minimal scope surface we need to emit — structurally compatible with
+ * footprintjs's `TypedScope<T>`, whose `$emit(name, payload?: unknown)` is
+ * wider than this.
+ */
+interface EmitableScope {
+    $emit(name: string, payload?: unknown): void;
+}
+/**
+ * Emit a typed event from inside stage code.
+ *
+ * @example
+ *   typedEmit(scope, 'agentfootprint.stream.llm_start', {
+ *     iteration: 1,
+ *     provider: 'anthropic',
+ *     model: 'claude-opus-4-8',
+ *     systemPromptChars: 800,
+ *     messagesCount: 2,
+ *     toolsCount: 0,
+ *   });
+ */
+export declare function typedEmit<K extends AgentfootprintEventType>(scope: EmitableScope, type: K, payload: AgentfootprintEventMap[K]['payload']): void;
+export {};

package/dist/esm/recorders/core/types.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Recorder-layer types — shapes builders use to communicate with recorders.
+ *
+ * Pattern: Data Transfer Object (Fowler, PoEAA).
+ * Role:    Shared vocabulary between builders (which WRITE injections) and
+ *          recorders (which OBSERVE those writes and emit grouped events).
+ */
+import type { ContextLifetime, ContextRecency, ContextRole, ContextSlot, ContextSource } from '../../events/types.js';
+/**
+ * An injection record written by a slot subflow into `scope[INJECTION_KEYS[slot]]`.
+ * ContextRecorder reads this to construct the corresponding event payload.
+ *
+ * Builders write arrays of these; recorders diff old-vs-new to detect NEW
+ * injections.
+ */
+export interface InjectionRecord {
+    /** Short human-readable content summary. */
+    readonly contentSummary: string;
+    /** Full content (may be redacted downstream). Optional. */
+    readonly rawContent?: string;
+    /** Stable hash of the content — enables duplicate detection. */
+    readonly contentHash: string;
+    /** The 3-slot target (sanity-checked against the subflow ID). */
+    readonly slot: ContextSlot;
+    /** Where this content came from. */
+    readonly source: ContextSource;
+    /** Optional source-specific identifier (retriever id, skill id, ...). */
+    readonly sourceId?: string;
+    /** Upstream event reference (runtimeStageId that produced the content). */
+    readonly upstreamRef?: string;
+    /** Why this was injected. */
+    readonly reason: string;
+    /** Role, when injecting into messages slot. */
+    readonly asRole?: ContextRole;
+    /** Recency, when injecting into messages slot. */
+    readonly asRecency?: ContextRecency;
+    /** Position within the slot (messages index, system-prompt section order). */
+    readonly position?: number;
+    /** Section tag for structured system prompts (e.g. "<skill>", "<retrieved>"). */
+    readonly sectionTag?: string;
+    /** Retrieval / ranking evidence. */
+    readonly retrievalScore?: number;
+    readonly rankPosition?: number;
+    readonly threshold?: number;
+    readonly budgetSpent?: {
+        readonly tokens: number;
+        readonly fractionOfCap: number;
+    };
+    /** How long this injection is expected to persist. */
+    readonly expiresAfter?: ContextLifetime;
+}
+/**
+ * Slot composition summary — written by a slot subflow at the END of its
+ * composition pass. ContextRecorder emits one `context.slot_composed`
+ * event per slot exit, built from this record.
+ */
+export interface SlotComposition {
+    readonly slot: ContextSlot;
+    readonly iteration: number;
+    readonly budget: {
+        readonly cap: number;
+        readonly used: number;
+        readonly headroomChars: number;
+    };
+    readonly sourceBreakdown: Readonly<Partial<Record<ContextSource, {
+        readonly chars: number;
+        readonly count: number;
+    }>>>;
+    readonly orderingStrategy?: string;
+    readonly droppedCount: number;
+    readonly droppedSummaries: readonly string[];
+}
+/**
+ * Eviction record — a piece that was removed from a slot under pressure.
+ */
+export interface EvictionRecord {
+    readonly slot: ContextSlot;
+    readonly contentHash: string;
+    readonly reason: 'budget' | 'stale' | 'low_score' | 'policy' | 'user_revoked';
+    readonly survivalMs: number;
+}
+/**
+ * Budget-pressure warning — emitted before evictions fire.
+ */
+export interface BudgetPressureRecord {
+    readonly slot: ContextSlot;
+    readonly capTokens: number;
+    readonly projectedTokens: number;
+    readonly overflowBy: number;
+    readonly planAction: 'evict' | 'summarize' | 'abort';
+}
+export declare const COMPOSITION_KEYS: {
+    readonly SLOT_COMPOSED: "slotCompositions";
+    readonly EVICTED: "slotEvictions";
+    readonly BUDGET_PRESSURE: "slotBudgetPressures";
+};
+export type CompositionKey = (typeof COMPOSITION_KEYS)[keyof typeof COMPOSITION_KEYS];

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

@@ -0,0 +1,117 @@
+/**
+ * AgentThinkingTraceRecorder — produce an AgentThinkingUI `Trace` from a run.
+ *
+ * AgentThinkingUI (the "watch it think" player) consumes a framework-agnostic
+ * `Trace` — a list of beats: `prompt → ask → return → answer`, where a tool
+ * reply is `data` (reason) or an `instruction` (a skill that says how to act).
+ * This recorder builds that `Trace` from agentfootprint's emit stream AS THE RUN
+ * TRAVERSES (no post-processing) — so any agentfootprint agent gets the
+ * domain-expert view for free, and AgentThinkingUI stays vendor-agnostic (it
+ * just renders the `Trace` JSON, exactly as it renders the OTLP adapter's output).
+ *
+ * Mapping (from the events already on the stream):
+ *   stream.llm_end (toolCalls>0)  → the brain reasoned; content + usage become
+ *                                   the upcoming ask's `brain` + `cost`.
+ *   stream.llm_end (toolCalls==0) → the final `answer`.
+ *   stream.tool_start             → `ask`  (read_skill → reaching for a skill).
+ *   stream.tool_end               → `return` (read_skill → replyType:'instruction'
+ *                                   + skill; any other tool → replyType:'data').
+ *
+ * Commentary (each beat's `brain`): filled from agentfootprint's OWN commentary
+ * engine — the SAME `selectCommentaryKey`/`extractCommentaryVars`/`renderCommentary`
+ * the Lens uses — so AgentThinkingUI's Notepad / bottom caption read identically
+ * to the Lens commentary panel (one engine, consumer-overridable via
+ * `commentaryTemplates`). The LLM's own reasoning still wins on the first ask of
+ * an iteration; the engine fills every other beat so no line is ever blank.
+ *
+ * Convention 1 (one purpose) + Convention 4 (run-scoped — resets per run).
+ */
+import type { EmitRecorder } from 'footprintjs';
+import { type CommentaryTemplates } from './commentary/commentaryTemplates.js';
+export interface AttCost {
+    ms: number;
+    tokens: number;
+    tokensIn?: number;
+    tokensOut?: number;
+    tokensCached?: number;
+}
+export interface AttAnswer {
+    headline: string;
+    [key: string]: unknown;
+}
+/** One tool the model had at its disposal for an LLM call — what it "saw" when it
+ *  decided. Lets a domain expert expand and read the menu next to the model's
+ *  reasoning, to debug WHY it chose (or skipped) a tool. */
+export interface AttToolSeen {
+    readonly name: string;
+    readonly description?: string;
+}
+export type AttStep = {
+    kind: 'prompt';
+    brain: string;
+    cost: AttCost;
+} | {
+    kind: 'ask';
+    tool: string;
+    toolName?: string;
+    input: Record<string, unknown>;
+    brain: string;
+    cost: AttCost;
+    /** Model's extended-thinking chain-of-thought for this iteration (when the
+     *  provider emitted reasoning blocks). Rendered as the "thinking" callout. */
+    thinking?: string;
+    /** The tools the model saw (name + description) for this iteration's call —
+     *  the menu it chose from. On the iteration's first ask only. */
+    toolsSeen?: readonly AttToolSeen[];
+} | {
+    kind: 'return';
+    tool: string;
+    toolName?: string;
+    replyType: 'data' | 'instruction' | 'both';
+    output: Record<string, unknown>;
+    brain: string;
+    cost: AttCost;
+    brainMode?: 'reason' | 'act';
+    skill?: string;
+    error?: string;
+} | {
+    kind: 'answer';
+    to: string;
+    brain: string;
+    answer: AttAnswer;
+    cost: AttCost;
+    error?: string;
+    /** Model's extended-thinking chain-of-thought before the final answer. */
+    thinking?: string;
+    /** The tools the model saw (name + description) for the final call. */
+    toolsSeen?: readonly AttToolSeen[];
+};
+export interface AttTrace {
+    task: string;
+    title?: string;
+    agent: string;
+    model: string;
+    asker: string;
+    steps: AttStep[];
+}
+export interface AgentThinkingTraceOptions {
+    readonly id?: string;
+    readonly agent?: string;
+    readonly model?: string;
+    readonly asker?: string;
+    /**
+     * Override agentfootprint's bundled commentary templates — the SAME shape as
+     * the Lens's `commentaryTemplates` prop (partial; spread over the defaults).
+     * Drives each beat's `brain` narration, so AgentThinkingUI's Notepad / bottom
+     * caption read like the Lens commentary panel — one engine, one voice,
+     * consumer-overridable. Omit to use the bundled English defaults.
+     */
+    readonly commentaryTemplates?: Partial<CommentaryTemplates>;
+}
+export interface AgentThinkingTraceHandle extends EmitRecorder {
+    /** The AgentThinkingUI `Trace` for the run so far. `task` (the headline of the
+     *  replay pill) defaults to the captured user message; override any field. */
+    getTrace(overrides?: Partial<Pick<AttTrace, 'task' | 'title' | 'agent' | 'model' | 'asker'>>): AttTrace;
+    clear(): void;
+}
+export declare function agentThinkingTrace(options?: AgentThinkingTraceOptions): AgentThinkingTraceHandle;