agentfootprint 6.44.0 → 7.0.0

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;