agentfootprint 6.44.0 → 6.45.0

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;

package/dist/esm/recorders/observability/commentary/commentaryTemplates.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Commentary templates — bundled English prose for narrating an
+ * agentfootprint run, plus the small engine that picks the right
+ * template per event and substitutes payload values.
+ *
+ * Audience split (load-bearing):
+ *   • COMMENTARY  — pure prose for the bottom panel of any viewer
+ *                   (Lens, CLI tail, log file). NO technical numbers,
+ *                   NO field dumps, NO library terms.
+ *   • DETAILS      — token counts, durations, args, IDs. The right
+ *                   panel / DevTools / structured-log territory.
+ *
+ * Architecture (3 pieces):
+ *   1. `defaultCommentaryTemplates` — flat `key → string` map.
+ *      i18n-ready: ship a Spanish/Japanese/etc. version with the same
+ *      keys, pass via `commentaryTemplates` on the renderer.
+ *   2. `selectCommentaryKey(event)` — per-event-type routing fn.
+ *      Returns `string` (render this key), `null` (skip — too
+ *      low-signal for prose), or `undefined` (fall through to a
+ *      caller-supplied default humanizer).
+ *   3. `extractCommentaryVars(event, ctx)` — builds the
+ *      `{ appName, userPrompt, toolName, descClause, ... }` bag the
+ *      template will be rendered with.
+ *
+ * Plus a tiny non-recursive `renderCommentary(template, vars)`.
+ *
+ * Why this lives in agentfootprint (not Lens):
+ *   The keys ARE agentfootprint event types. The prose teaches
+ *   agentfootprint concepts (slot composition, ReAct, tool-calling).
+ *   Consumers building agentfootprint Agents ship their voice / locale
+ *   alongside their system prompt and tool registry. Lens (or any
+ *   other viewer) is just a renderer that consumes this surface.
+ *
+ * Verb discipline (encoded in the prose):
+ *   • `{{appName}}` (active actor)  — called, dispatched, returned,
+ *                                      decided, read, built
+ *   • LLM (passive actor)            — suggested, responded, produced,
+ *                                      asked for, gave
+ *   The split reflects the architectural truth: LLMs don't act, the
+ *   orchestrating system does.
+ */
+import type { AgentfootprintEvent } from '../../../events/registry.js';
+/** Flat map of template keys to template strings. Keys use a dotted
+ *  hierarchy mirroring event types + payload branches
+ *  (`'stream.llm_start.iter1'`, `'context.injected.rag'`). Values may
+ *  contain `{{name}}` placeholders that `renderCommentary` substitutes. */
+export type CommentaryTemplates = Readonly<Record<string, string>>;
+/**
+ * The bundled English templates. Override per-key via the renderer's
+ * `templates` option — partial overrides are spread on top of these
+ * defaults so consumers only ship what they want to change.
+ */
+export declare const defaultCommentaryTemplates: CommentaryTemplates;
+/** Context the var-extractor reads from. Anything that's NOT in the
+ *  event payload (consumer-supplied appName, tool registry lookup) goes
+ *  here. Pure data — no closures, no I/O. */
+export interface CommentaryContext {
+    /** The system that orchestrates the LLM. Substituted as the active
+     *  actor in every line ("Acme called the LLM"). Default: `'Chatbot'`. */
+    readonly appName: string;
+    /** Resolves a tool name to its registered description ("Get current
+     *  weather for a city"). Used to compose the optional `descClause`
+     *  for `stream.tool_start`. Sync — Lens-style consumers precompute
+     *  the lookup map from `context.injected source='registry'` events. */
+    readonly getToolDescription?: (toolName: string) => string | undefined;
+}
+/**
+ * Pick the template key for an event. Branches encoded in the key
+ * suffix (no conditional logic in the templates themselves).
+ *
+ *   `null`      → explicit skip (baseline injections, low-signal events)
+ *   `undefined` → fall through to caller's default humanizer
+ *   `string`    → render `templates[key]` with `extractCommentaryVars`
+ */
+export declare function selectCommentaryKey(event: AgentfootprintEvent): string | null | undefined;
+/**
+ * Build the variable bag for a given event. Flat `name → string` map;
+ * `renderCommentary` substitutes by name. Templates use whatever names
+ * this function produces.
+ *
+ * Two-step composition for `stream.tool_start`: the optional
+ * `descClause` is a rendered sub-template. We pre-render it here so
+ * the outer template stays a single non-recursive substitution pass.
+ */
+export declare function extractCommentaryVars(event: AgentfootprintEvent, ctx: CommentaryContext, templates?: CommentaryTemplates): Record<string, string>;
+/**
+ * Resolve the agent name from an event's `meta.subflowPath`.
+ *
+ * Walks the path right-to-left, skipping library-internal segments
+ * (slot subflows, agent-routing subflows, thinking handlers), and
+ * returns the FIRST meaningful segment with the optional `step-`
+ * Sequence prefix stripped. For events with no meaningful path
+ * (single-Agent runners, top-level events), falls back to `appName`.
+ */
+export declare function extractAgentName(event: AgentfootprintEvent, ctx: CommentaryContext): string;
+/**
+ * Render a template by substituting `{{name}}` placeholders from the
+ * vars bag. Missing keys render as empty string — keeps prose
+ * forgiving when an optional field isn't present.
+ *
+ * Non-recursive: a substituted value is NOT itself processed for
+ * placeholders. Compose sub-templates upstream (see
+ * `extractCommentaryVars`).
+ */
+export declare function renderCommentary(template: string, vars: Record<string, string>): string;

package/dist/esm/recorders/observability/internal/ActorArrowClassifier.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @internal — not part of the public agentfootprint API. Imported only
+ * by RunStepRecorder. Subject to change without notice.
+ *
+ * ActorArrowClassifier — classifies the next `llm.start` as
+ * `'user→llm'` (no pending tool result) vs `'tool→llm'` (after a
+ * tool result), and the next `llm.end` as `'llm→tool'` vs `'llm→user'`
+ * based on the call's `toolCallCount`.
+ *
+ * Extracted from RunStepRecorder per Convention 1. Keeps a single
+ * boolean of state — `prevLLMEndHadTools` — and consumes-then-resets
+ * it on each `llm.start`.
+ */
+export type StartArrow = 'user→llm' | 'tool→llm';
+export type EndArrow = 'llm→tool' | 'llm→user';
+export declare class ActorArrowClassifier {
+    private prevLLMEndHadTools;
+    /** Classify the next `llm.start`. Consumes + resets the pending
+     *  flag after returning. */
+    classifyStart(): StartArrow;
+    /** Classify an `llm.end` based on its tool-call count, and update
+     *  the pending flag for the NEXT llm.start. */
+    classifyEnd(toolCallCount: number): EndArrow;
+    clear(): void;
+}

package/dist/esm/recorders/observability/internal/CandidateAnswerBuffer.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @internal — not part of the public agentfootprint API. Imported only
+ * by RunStepRecorder. Subject to change without notice.
+ *
+ * CandidateAnswerBuffer — buffers a "this leaf MIGHT be the run's
+ * answer" candidate that's only confirmed on `onRunEnd`. Replaced
+ * by every later leaf exit at run scope; the last one wins.
+ *
+ * Extracted from RunStepRecorder per Convention 1.
+ *
+ * Use:
+ *   - On leaf EXIT at run scope: `set(frame, ts, runtimeStageId)`.
+ *   - On `onRunEnd`: `flush()` returns the buffered candidate (or
+ *     undefined if none), and clears the buffer.
+ */
+export interface CandidateAnswer<TFrame> {
+    readonly frame: TFrame;
+    readonly tsMs: number;
+    readonly runtimeStageId: string;
+}
+export declare class CandidateAnswerBuffer<TFrame> {
+    private candidate;
+    /** Buffer a new candidate, replacing any prior one. */
+    set(frame: TFrame, tsMs: number, runtimeStageId: string): void;
+    /** Return + clear the buffered candidate (or undefined if empty). */
+    flush(): CandidateAnswer<TFrame> | undefined;
+    clear(): void;
+}