agentfootprint 6.43.0 → 6.45.0

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

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

@@ -0,0 +1,60 @@
+/**
+ * @internal — not part of the public agentfootprint API. Imported only
+ * by RunStepRecorder. Subject to change without notice; do not import
+ * via deep paths.
+ *
+ * ForkTracker — owns the bookkeeping for parallel-fork emission and
+ * merge-step detection. Extracted from RunStepRecorder per Convention 1
+ * (one purpose per recorder/state machine).
+ *
+ * Responsibilities (and ONLY these):
+ *   1. Coalesce repeated `onFork` events for the same parent (race-safe
+ *      via parent+runtimeStageId key).
+ *   2. Track which child branches belong to which parent fork.
+ *   3. Track which branches have exited; signal "merge ready" when ALL
+ *      branches of a fork have exited.
+ *
+ * What it does NOT own:
+ *   - Storage (the recorder writes RunSteps to its SequenceStore).
+ *   - Run-boundary detection (the recorder's runIdGuard wipes this
+ *     tracker via `clear()`).
+ *   - Any other state machine.
+ */
+export interface ForkRegistration {
+    /** True if this is a NEW fork; false if the same fork was already seen
+     *  (caller should suppress duplicate emission). */
+    readonly fresh: boolean;
+}
+export interface MergeReady {
+    /** All branch IDs of the now-fully-exited fork, in the order they
+     *  were originally registered. */
+    readonly branches: readonly string[];
+}
+export declare class ForkTracker {
+    /** Per-parent: the ordered list of child branch IDs registered. */
+    private readonly branches;
+    /** Per-parent: the set of child branch IDs that have exited so far. */
+    private readonly exited;
+    /** Reverse index: child branch ID → its parent fork. */
+    private readonly childToParent;
+    /** Set of `${parent}@${runtimeStageId}` keys already registered, to
+     *  coalesce repeated onFork events. */
+    private readonly emittedKeys;
+    /**
+     * Register a new fork. If the same fork (by parent+runtimeStageId)
+     * was already registered, returns `{ fresh: false }` and the caller
+     * should suppress emission. Otherwise registers all child branches
+     * and returns `{ fresh: true }`.
+     */
+    registerFork(parent: string, runtimeStageId: string, children: readonly string[]): ForkRegistration;
+    /** True if this child belongs to a tracked fork (used to suppress
+     *  sequential-emission for fork-branch entry events). */
+    isForkChild(childSubflowId: string): boolean;
+    /**
+     * Record a fork-branch exit. If this completes the fork (all branches
+     * have exited), returns `{ branches }` so the caller can emit a merge
+     * step. Returns `undefined` if not yet complete or not a fork branch.
+     */
+    recordChildExit(childSubflowId: string): MergeReady | undefined;
+    clear(): void;
+}

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

@@ -0,0 +1,51 @@
+/**
+ * @internal — not part of the public agentfootprint API. Imported only
+ * by RunStepRecorder. Subject to change without notice.
+ *
+ * RootInferrer — small state machine deciding whether a run's root is
+ * a single leaf primitive (Agent / LLMCall) or a composition (Sequence
+ * / Parallel / Conditional / Loop).
+ *
+ * Extracted from RunStepRecorder per Convention 1.
+ *
+ * Inputs: subflow entries (with their depth + parsed primitiveKind),
+ * fork events (depth 0 → Parallel root), decision events (depth 0 →
+ * Conditional root), loop events (depth 0 → Loop root).
+ *
+ * Output: query `kind()` for the inferred root. Returns `undefined`
+ * until a signal arrives.
+ *
+ * Inference rules:
+ *   - Decisive composition signals (fork / decide / loop AT DEPTH 0)
+ *     lock the root and are never overridden.
+ *   - Shallowest primitive boundary IS a composition kind → root is
+ *     that composition.
+ *   - Two+ leaf siblings at the shallowest depth → implicit Sequence
+ *     root (Sequence-as-runner case where the Sequence itself doesn't
+ *     fire its own subflow.entry).
+ *   - Single leaf at the shallowest depth → root is "leaf".
+ */
+export type InferredRoot = 'leaf' | 'sequence' | 'parallel' | 'conditional' | 'loop' | undefined;
+export declare class RootInferrer {
+    private inferred;
+    private shallowestDepth;
+    private shallowestSiblings;
+    /** Currently-inferred root kind, or undefined if no signal yet. */
+    kind(): InferredRoot;
+    /** True when the root is a single leaf primitive (or unknown,
+     *  which should be treated as leaf for kind-filter purposes). */
+    isLeafRoot(): boolean;
+    /** Observe a subflow entry. */
+    observeSubflowEntry(depth: number, primitiveKind: string | undefined): void;
+    /** Observe a fork event. Locks root to Parallel if at depth 0 and
+     *  no decisive root has been inferred yet. */
+    observeFork(depth: number): void;
+    /** Observe a decision event. Locks root to Conditional if at depth 0
+     *  and no decisive root has been inferred yet. */
+    observeDecision(depth: number): void;
+    /** Observe a loop event. Locks root to Loop if at depth 0 and no
+     *  decisive root has been inferred yet. */
+    observeLoop(depth: number): void;
+    clear(): void;
+    private tryInfer;
+}

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

@@ -0,0 +1,24 @@
+/**
+ * @internal — not part of the public agentfootprint API. Imported only
+ * by RunStepRecorder. Subject to change without notice.
+ *
+ * SequenceSiblingTracker — tracks the most-recent leaf exit at each
+ * depth so the recorder knows when a new leaf entry at the same depth
+ * should emit a "sequential handoff" step ("forwards" semantics).
+ *
+ * Extracted from RunStepRecorder per Convention 1.
+ *
+ * Use:
+ *   - On leaf EXIT: `recordExit(depth, subflowId)`.
+ *   - On leaf ENTRY: `peekPrevSibling(depth)` returns the previous
+ *     leaf's subflowId at this depth, or undefined for the first leaf.
+ */
+export declare class SequenceSiblingTracker {
+    private readonly prevExitedAtDepth;
+    /** Returns the subflow id of the most-recently-exited leaf at this
+     *  depth, or undefined if this is the first leaf entry at the depth. */
+    peekPrevSibling(depth: number): string | undefined;
+    /** Record that a leaf at this depth just exited. */
+    recordExit(depth: number, subflowId: string): void;
+    clear(): void;
+}

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

@@ -0,0 +1,48 @@
+/**
+ * localObservability — Tier-3 (Debug) observability: RETAIN a live run model,
+ * render it live, and snapshot it for offline replay.
+ *
+ * One handle, two outputs:
+ *   - LIVE   — `onUpdate(graph)` fires per event; pass the handle to
+ *              `<Lens recorder={handle} />` and it re-renders as the agent runs.
+ *   - OFFLINE— `getTrace()` (any time) and `onComplete(trace)` (auto, at run
+ *              exit) freeze the model into a JSON-lossless `Trace` for `<Replay>`.
+ *
+ * Contrast with `enable.observability({ strategy })` (Tier-4 / Monitor), which
+ * ships each event to a vendor and FORGETS. localObservability KEEPS the model
+ * so you can look at it — locally, with full content. See
+ * `docs/design/local-observability-and-pii.md`.
+ *
+ * It's a thin wrapper over `enable.flowchart` (the existing live StepGraph) +
+ * `serializeTrace` (the snapshot). UI-free: returns data, never React.
+ */
+import type { CombinedRecorder } from 'footprintjs';
+import type { EventDispatcher } from '../../events/dispatcher.js';
+import type { DomainEvent } from './BoundaryRecorder.js';
+import { type FlowchartHandle, type StepGraph } from './FlowchartRecorder.js';
+import { type SerializeTraceOptions, type Trace } from './trace.js';
+export interface LocalObservabilityOptions {
+    /** LIVE recording — called with a fresh StepGraph on every event (drives `<Lens>`). */
+    readonly onLive?: (graph: StepGraph) => void;
+    /** At run exit — called once with the finalized recording (a Trace, auto-serialized) to replay offline. */
+    readonly onRecorded?: (trace: Trace) => void;
+    /**
+     * Default serialize-time redaction, applied to BOTH `onRecorded` and
+     * `getTrace()` (overridable per `getTrace` call). Runs once per event so PII
+     * never enters the Trace — see the trust-boundary note in the design doc.
+     * Pass `redactContent` for a ready-made redactor.
+     */
+    readonly redact?: (event: DomainEvent) => DomainEvent;
+}
+/** A `FlowchartHandle` (live) plus `getTrace()` (offline snapshot). */
+export interface LocalObservabilityHandle extends FlowchartHandle {
+    /** Freeze the current model into a JSON-lossless Trace. Safe during or after a run. */
+    getTrace(options?: SerializeTraceOptions): Trace;
+}
+/**
+ * Attach a local-observability handle. `now` is injectable for tests (the
+ * library otherwise stamps `Date.now()` at serialize time).
+ *
+ * @internal Called from `RunnerBase.enable.localObservability`.
+ */
+export declare function attachLocalObservability(runnerAttach: (recorder: CombinedRecorder) => () => void, dispatcher: EventDispatcher, options?: LocalObservabilityOptions, now?: () => number, getStructure?: () => unknown): LocalObservabilityHandle;

package/dist/esm/recorders/observability/localObservability.js

@@ -0,0 +1,54 @@
+/**
+ * localObservability — Tier-3 (Debug) observability: RETAIN a live run model,
+ * render it live, and snapshot it for offline replay.
+ *
+ * One handle, two outputs:
+ *   - LIVE   — `onUpdate(graph)` fires per event; pass the handle to
+ *              `<Lens recorder={handle} />` and it re-renders as the agent runs.
+ *   - OFFLINE— `getTrace()` (any time) and `onComplete(trace)` (auto, at run
+ *              exit) freeze the model into a JSON-lossless `Trace` for `<Replay>`.
+ *
+ * Contrast with `enable.observability({ strategy })` (Tier-4 / Monitor), which
+ * ships each event to a vendor and FORGETS. localObservability KEEPS the model
+ * so you can look at it — locally, with full content. See
+ * `docs/design/local-observability-and-pii.md`.
+ *
+ * It's a thin wrapper over `enable.flowchart` (the existing live StepGraph) +
+ * `serializeTrace` (the snapshot). UI-free: returns data, never React.
+ */
+import { attachFlowchart } from './FlowchartRecorder.js';
+import { serializeTrace } from './trace.js';
+/**
+ * Attach a local-observability handle. `now` is injectable for tests (the
+ * library otherwise stamps `Date.now()` at serialize time).
+ *
+ * @internal Called from `RunnerBase.enable.localObservability`.
+ */
+export function attachLocalObservability(runnerAttach, dispatcher, options = {}, now = Date.now, getStructure) {
+    let completed = false;
+    // `let` (not const): `handle` is referenced by `buildTrace` and the onUpdate
+    // closure below, both defined before its assignment. The closures only run
+    // after `attachFlowchart` returns, so `handle` is always set by call time.
+    // eslint-disable-next-line prefer-const
+    let handle;
+    const buildTrace = (override) => serializeTrace(handle.boundary.getEvents(), {
+        capturedAtMs: now(),
+        ...(getStructure && { structure: getStructure() }),
+        ...(options.redact && { redact: options.redact }),
+        ...override,
+    });
+    handle = attachFlowchart(runnerAttach, dispatcher, {
+        onUpdate: (graph) => {
+            options.onLive?.(graph);
+            // Fire onRecorded once, when the root run boundary closes.
+            if (options.onRecorded &&
+                !completed &&
+                handle.boundary.getEvents().some((e) => e.type === 'run.exit')) {
+                completed = true;
+                options.onRecorded(buildTrace());
+            }
+        },
+    });
+    return { ...handle, getTrace: buildTrace };
+}
+//# sourceMappingURL=localObservability.js.map

package/dist/esm/recorders/observability/localObservability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"localObservability.js","sourceRoot":"","sources":["../../../../src/recorders/observability/localObservability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAMH,OAAO,EAAE,eAAe,EAAwC,MAAM,wBAAwB,CAAC;AAC/F,OAAO,EAAE,cAAc,EAA0C,MAAM,YAAY,CAAC;AAsBpF;;;;;GAKG;AACH,MAAM,UAAU,wBAAwB,CACtC,YAAwD,EACxD,UAA2B,EAC3B,UAAqC,EAAE,EACvC,MAAoB,IAAI,CAAC,GAAG,EAC5B,YAA4B;IAE5B,IAAI,SAAS,GAAG,KAAK,CAAC;IACtB,6EAA6E;IAC7E,2EAA2E;IAC3E,2EAA2E;IAC3E,wCAAwC;IACxC,IAAI,MAAuB,CAAC;IAE5B,MAAM,UAAU,GAAG,CAAC,QAAgC,EAAS,EAAE,CAC7D,cAAc,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,EAAE,EAAE;QAC1C,YAAY,EAAE,GAAG,EAAE;QACnB,GAAG,CAAC,YAAY,IAAI,EAAE,SAAS,EAAE,YAAY,EAAE,EAAE,CAAC;QAClD,GAAG,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;QACjD,GAAG,QAAQ;KACZ,CAAC,CAAC;IAEL,MAAM,GAAG,eAAe,CAAC,YAAY,EAAE,UAAU,EAAE;QACjD,QAAQ,EAAE,CAAC,KAAK,EAAE,EAAE;YAClB,OAAO,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC;YACxB,2DAA2D;YAC3D,IACE,OAAO,CAAC,UAAU;gBAClB,CAAC,SAAS;gBACV,MAAM,CAAC,QAAQ,CAAC,SAAS,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,UAAU,CAAC,EAC9D,CAAC;gBACD,SAAS,GAAG,IAAI,CAAC;gBACjB,OAAO,CAAC,UAAU,CAAC,UAAU,EAAE,CAAC,CAAC;YACnC,CAAC;QACH,CAAC;KACF,CAAC,CAAC;IAEH,OAAO,EAAE,GAAG,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC;AAC7C,CAAC"}

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

@@ -0,0 +1,36 @@
+/**
+ * observeRunId — shared run-boundary detection helper for recorders.
+ *
+ * Why this exists: 5 places in observability/* duplicated the same
+ * 10-line pattern (lastRunId field + 3-line check + reset). Extract
+ * once so the contract stays consistent under maintenance.
+ *
+ * The pattern: hold a `lastRunId | undefined`. On every observed event:
+ *   - If runId is missing/undefined → no-op (defensive, allows callers
+ *     to pass `event.meta?.runId` without checking).
+ *   - First observation (lastRunId === undefined) → record, no reset.
+ *   - Same runId → no-op (steady state).
+ *   - Different runId → call onNewRun() then record the new id.
+ *
+ * Returned helper is mutable closure state — callers store it as a
+ * private field and call `.observe(runId)` from event hooks.
+ *
+ * @example
+ * ```typescript
+ * class MyRecorder implements ScopeRecorder {
+ *   private readonly runIdGuard = createRunIdObserver(() => this.reset());
+ *   onWrite(e) {
+ *     this.runIdGuard.observe(e.traversalContext?.runId);
+ *     // ... handle event
+ *   }
+ *   private reset() { this.store.clear(); }
+ * }
+ * ```
+ */
+export interface RunIdObserver {
+    /** Process an event's runId; fires onNewRun callback when it changes. */
+    observe(runId: string | undefined): void;
+    /** Clear state so the next observation initializes fresh. */
+    reset(): void;
+}
+export declare function createRunIdObserver(onNewRun: () => void): RunIdObserver;

package/dist/esm/recorders/observability/status/statusTemplates.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Thinking templates — chat-bubble surface (separate from commentary).
+ *
+ * Audience split:
+ *   • COMMENTARY (`commentaryTemplates`)  — third-person, every moment,
+ *                                            shown in Lens panel. Audience:
+ *                                            developer / observer.
+ *   • THINKING (this file)                — first-person, mid-call only,
+ *                                            shown in chat bubble. Audience:
+ *                                            end user chatting with the agent.
+ *
+ * The thinking surface is a tiny finite state machine driven purely by
+ * the event log:
+ *
+ *      ┌──────────┐  llm.start, no tools yet
+ *  ────┤  idle    ├────────────────────────────► "Thinking…"
+ *      └──────────┘
+ *
+ *      ┌──────────┐  stream.token chunks accumulate
+ *  ────┤streaming ├────────────────────────────► "{{partial}}"
+ *      └──────────┘
+ *
+ *      ┌──────────┐  tool.start, no tool.end yet
+ *  ────┤   tool   ├────────────────────────────► "Working on `weather`…"
+ *      └──────────┘                               (or per-tool override)
+ *
+ *      ┌──────────┐  pause.request, no resume yet
+ *  ────┤  paused  ├────────────────────────────► "Waiting on you: …"
+ *      └──────────┘
+ *
+ *      (null)        run done / between calls   → bubble hidden
+ *
+ * The selector returns the CURRENT state by walking the event log;
+ * the renderer maps state → final string by looking up the template.
+ *
+ * Per-tool templates: consumers can ship `tool.<toolName>` keys
+ * (e.g. `tool.weather: 'Looking up the weather…'`) which the renderer
+ * prefers over the generic `tool` template. Lets each tool have its
+ * own first-person status without per-tool plumbing.
+ */
+import type { AgentfootprintEvent } from '../../../events/registry.js';
+/** The four mid-call states a chat bubble might render. */
+export type StatusKind = 'idle' | 'tool' | 'streaming' | 'paused';
+/**
+ * What the selector returns. The chat-bubble consumer feeds this into
+ * the renderer to get the final string.
+ */
+export interface StatusState {
+    readonly state: StatusKind;
+    /** Vars for `{{name}}` substitution in the matched template. */
+    readonly vars: Readonly<Record<string, string>>;
+    /** When `state === 'tool'`, the resolving toolName. The renderer
+     *  uses this to look up `tool.<toolName>` before the generic `tool`. */
+    readonly toolName?: string;
+}
+/** Flat template map. Keys: state kinds + per-tool overrides. */
+export type StatusTemplates = Readonly<Record<string, string>>;
+/** Render context — what the consumer's app config injects. */
+export interface StatusContext {
+    /** Active actor's name. Substituted as `{{appName}}` in templates. */
+    readonly appName: string;
+}
+/**
+ * Bundled English defaults. Override in the agent config via
+ * `.thinkingTemplates({...})`. Per-tool overrides go via
+ * `tool.<toolName>` keys.
+ */
+export declare const defaultStatusTemplates: StatusTemplates;
+/**
+ * Derive the current thinking state from the event log.
+ *
+ * Single forward walk that tracks "active" state for each domain:
+ *   • pause       — set on pause.request, cleared on pause.resume
+ *   • tool        — set on tool.start, cleared on matching tool.end
+ *                   (matched by `toolCallId` for parallel-tool safety)
+ *   • llm         — set on llm.start, cleared on llm.end
+ *
+ * Priority order (highest first):
+ *
+ *   1. ACTIVE PAUSE wins. When the agent is waiting on the human,
+ *      that's what the chat should show — not the underlying tool
+ *      that triggered the pause.
+ *   2. ACTIVE TOOL — the LLM said "use a tool" and the tool is
+ *      running. Show "Working on `<toolName>`…".
+ *   3. ACTIVE LLM — call in flight. Show streaming tokens if any
+ *      arrived, otherwise "Thinking…".
+ *   4. Otherwise null (bubble hidden).
+ *
+ * Pure projection. Forward walk is O(n); a closing event correctly
+ * cancels its matching opener so a completed tool.start/tool.end
+ * pair leaves the state quiescent.
+ */
+export declare function selectStatus(events: readonly AgentfootprintEvent[]): StatusState | null;
+/**
+ * Resolve the matched template + substitute vars.
+ *
+ *   • `state === null`           → null (chat bubble renders nothing)
+ *   • `state === 'tool'`         → tries `tool.<toolName>` first, then
+ *                                   generic `tool`
+ *   • Other states               → looks up the state's name as the key
+ *
+ * Missing template keys return null rather than the empty string —
+ * keeps the contract honest (consumer can detect "no template" and
+ * fall back to its own default).
+ */
+export declare function renderStatusLine(state: StatusState | null, ctx: StatusContext, templates?: StatusTemplates): string | null;