agentfootprint 6.44.0 → 6.45.0

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

@@ -0,0 +1,546 @@
+/**
+ * BoundaryRecorder — unified domain event log for an agentfootprint run.
+ *
+ * The single source of truth Lens (and any other consumer) reads to
+ * render a run. Every observable moment in a run is captured as one
+ * `DomainEvent` in a single ordered stream:
+ *
+ *   - `run.entry` / `run.exit`              — top-level executor.run()
+ *   - `subflow.entry` / `subflow.exit`      — every subflow boundary
+ *   - `fork.branch`                         — one per parallel child
+ *   - `decision.branch`                     — chosen branch of a Conditional
+ *   - `loop.iteration`                      — one per back-edge traversal
+ *   - `llm.start` / `llm.end`               — LLM provider call lifecycle
+ *   - `tool.start` / `tool.end`             — tool execution lifecycle
+ *   - `context.injected`                    — anything injected into a slot
+ *
+ * All events carry `runtimeStageId` (binds with footprintjs Trace view +
+ * with each other), `subflowPath`, `depth`, and `ts` (wall-clock ms).
+ * Subflow events are domain-tagged (`slotKind` / `primitiveKind` /
+ * `isAgentInternal`) so consumers dispatch on tag without re-parsing.
+ *
+ * Architecture:
+ *
+ *   ┌──── footprintjs (domain-agnostic) ────┐
+ *   │  FlowRecorder events (run/subflow/    │  ──┐
+ *   │  fork/decision/loop)                  │    │
+ *   └───────────────────────────────────────┘    │
+ *                                                │
+ *   ┌──── agentfootprint dispatcher ─────────┐   │  consumed by
+ *   │  Typed events (llm/tool/context)       │  ──┤
+ *   └────────────────────────────────────────┘   │
+ *                                                ▼
+ *                                  ┌─── BoundaryRecorder ───┐
+ *                                  │  one tagged stream of  │
+ *                                  │  DomainEvent           │
+ *                                  └────────────────────────┘
+ *                                                │
+ *                                                ▼  consumed by
+ *                                  ┌────── Lens (UI) ──────┐
+ *                                  │  Slider / RunFlow /   │
+ *                                  │  NodeDetail / etc.    │
+ *                                  └───────────────────────┘
+ *
+ * Why ONE recorder: Lens scrub axis, run-flow graph, slot rows inside
+ * the LLM card, right-pane detail panel, commentary panel — every UI
+ * surface reads from the SAME stream. Adding a new domain event = one
+ * tagged emit + one render shape. No state machines spread across
+ * renderers, no merging of multiple sources, no name-based filter lists.
+ *
+ * Naming: `runtimeStageId` is footprintjs's primitive (path-prefixed +
+ * `#executionIndex`). `subflowPath` is rooted under the synthetic
+ * `'__root__'`. `slotKind` / `primitiveKind` are agent-domain. The
+ * design follows the React Fiber + OpenTelemetry pattern:
+ * **producers self-describe; consumers dispatch on type**.
+ *
+ * @example
+ * ```typescript
+ * import { boundaryRecorder, EventDispatcher } from 'agentfootprint';
+ *
+ * const boundary = boundaryRecorder();
+ * const dispatcher = new EventDispatcher();
+ * executor.attachCombinedRecorder(boundary);   // wires FlowRecorder side
+ * boundary.subscribe(dispatcher);              // wires typed-event side
+ *
+ * await executor.run({ input });
+ *
+ * for (const e of boundary.getEvents()) {
+ *   switch (e.type) {
+ *     case 'run.entry':       renderRoot(e); break;
+ *     case 'subflow.entry':   if (e.slotKind) renderSlotRow(e);
+ *                              else if (e.primitiveKind) renderPrimitive(e);
+ *                              break;
+ *     case 'llm.start':       renderLLMCall(e); break;
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+import { CommitRangeIndex } from 'footprintjs/trace';
+import type { CombinedRecorder, FlowDecisionEvent, FlowForkEvent, FlowLoopEvent, FlowSubflowEvent, TraversalContext } from 'footprintjs';
+interface FlowRunEvent {
+    readonly payload?: unknown;
+    readonly traversalContext?: TraversalContext;
+}
+interface FlowRunFailedEvent {
+    readonly structuredError: {
+        readonly message: string;
+    };
+    readonly traversalContext?: TraversalContext;
+}
+import type { EventDispatcher, Unsubscribe } from '../../events/dispatcher.js';
+import type { ContextSlot } from '../../events/types.js';
+/** Fields every domain event carries. */
+interface DomainEventBase {
+    /** Stable per-execution key (footprintjs primitive). For run events it
+     *  is `'__root__#0'`; subflow events use the parent stage's runtimeStageId
+     *  at mount; typed events use the firing stage's runtimeStageId. */
+    readonly runtimeStageId: string;
+    /** Decomposition of `subflowId` into segments, rooted under `'__root__'`. */
+    readonly subflowPath: readonly string[];
+    /** Depth in the run tree — root = 0, top-level subflow = 1, etc. */
+    readonly depth: number;
+    /** Wall-clock ms at capture time. */
+    readonly ts: number;
+    /** Commit count when this event fired. 0 if the recorder was
+     *  constructed without `getCommitCount` (legacy mode). The boundary
+     *  RANGE for an (entry, exit) pair is `[entry.commitIdxBefore,
+     *  exit.commitIdxBefore]`. Phase 5 Layer 2 — see
+     *  `docs/design/boundary-commit-ranges.md`. */
+    readonly commitIdxBefore: number;
+    /** RESERVED for future event types that trigger engine writes.
+     *  CURRENT BEHAVIOR: always equals `commitIdxBefore` for every event
+     *  emitted by today's BoundaryRecorder. Observer events don't write
+     *  to scope, so the executor's commit count doesn't change between
+     *  the moment the event is sampled and the moment it's recorded.
+     *  Consumers should currently treat this as identical to
+     *  `commitIdxBefore`; do NOT rely on it being strictly greater.
+     *  The field exists for forward compatibility — if a future
+     *  observer pattern triggers commits during its handler, this is
+     *  where the post-effect count will land. */
+    readonly commitIdxAfter: number;
+}
+export interface DomainRunEvent extends DomainEventBase {
+    readonly type: 'run.entry' | 'run.exit';
+    readonly payload?: unknown;
+    /** Always `true` for run events — convenience flag for filter callers. */
+    readonly isRoot: true;
+}
+export interface DomainSubflowEvent extends DomainEventBase {
+    readonly type: 'subflow.entry' | 'subflow.exit';
+    /** Path-prefixed engine id (matches `FlowSubflowEvent.subflowId`). */
+    readonly subflowId: string;
+    /** Last segment of `subflowId` — convenience for leaf-name grouping. */
+    readonly localSubflowId: string;
+    readonly subflowName: string;
+    /** Build-time description from the subflow root (`'<Kind>: <detail>'`). */
+    readonly description?: string;
+    /** Parsed `'<Kind>:'` prefix — `'Agent'`, `'LLMCall'`, `'Sequence'`, etc. */
+    readonly primitiveKind?: string;
+    /** Set ONLY for the 3 input-slot subflows (sf-system-prompt / sf-messages / sf-tools). */
+    readonly slotKind?: ContextSlot;
+    /** True for Agent state-machine routing/wrapper subflows (route, tool-calls, final, merge). */
+    readonly isAgentInternal: boolean;
+    /** `inputMapper` result on entry; subflow shared state on exit. */
+    readonly payload?: unknown;
+}
+export interface DomainForkBranchEvent extends DomainEventBase {
+    readonly type: 'fork.branch';
+    readonly parentSubflowId: string;
+    readonly childName: string;
+}
+export interface DomainDecisionBranchEvent extends DomainEventBase {
+    readonly type: 'decision.branch';
+    readonly decider: string;
+    readonly chosen: string;
+    readonly rationale?: string;
+    /**
+     * `true` when this decision comes from one of the Agent's internal
+     * routing stages (e.g., the ReAct `Route` decider that picks
+     * `tool-calls` vs `final`). Filtered out of the timeline by
+     * `buildStepGraph` — the actor arrows that follow already encode
+     * the routing observably (`llm→tool` vs `llm→user`).
+     *
+     * `false` when the decision comes from a consumer-defined
+     * `Conditional` primitive — those ARE meaningful timeline steps.
+     */
+    readonly isAgentInternal: boolean;
+}
+export interface DomainLoopIterationEvent extends DomainEventBase {
+    readonly type: 'loop.iteration';
+    readonly target: string;
+    readonly iteration: number;
+}
+/**
+ * Composition boundary event — fired for every composition primitive
+ * (Parallel / Sequence / Loop / Conditional). Mirrors `subflow.entry/exit`
+ * but for the COMPOSITION wrapper itself (the box that contains the
+ * branches / steps / iterations / chosen-branch).
+ *
+ * This pair OPENS and CLOSES a boundary range in `boundaryIndex`. Child
+ * subflows that fire between the pair nest naturally inside the
+ * composition's range.
+ *
+ * The `runtimeStageId` is the composition's own per-execution id —
+ * SAME format as any other runtimeStageId, with `#executionIndex`. The
+ * `kind` discriminates which composition primitive this is.
+ *
+ * For the Lens compound time axis, this group is what collapses
+ * parallel branches into ONE slider position at the parent's drill
+ * level. Drill into the composition to see its children as positions.
+ */
+export interface DomainCompositionEvent extends DomainEventBase {
+    readonly type: 'composition.start' | 'composition.end';
+    readonly kind: 'Parallel' | 'Sequence' | 'Loop' | 'Conditional';
+    readonly compositionId: string;
+    readonly name: string;
+    /** On `composition.end`, the exit status reported by the composition. */
+    readonly status?: 'ok' | 'err' | 'break' | 'budget_exhausted';
+    readonly durationMs?: number;
+}
+/**
+ * The 4 actor arrows of a ReAct cycle. Tagged on `llm.start` / `llm.end`
+ * at capture time so consumers (slider, run-flow renderer) dispatch by
+ * `event.actorArrow` instead of running their own state machine.
+ *
+ *   - `'user→llm'` — first LLM call, or any LLM call NOT preceded by a
+ *     tool result (assembled-context delivery to the model).
+ *   - `'tool→llm'` — LLM call that follows a tool's result (the next
+ *     iteration of a ReAct loop).
+ *   - `'llm→tool'` — `llm.end` whose `toolCallCount > 0` (the LLM is
+ *     requesting tool execution).
+ *   - `'llm→user'` — `llm.end` with `toolCallCount === 0` (terminal
+ *     response delivered to the user).
+ */
+export type ActorArrow = 'user→llm' | 'tool→llm' | 'llm→tool' | 'llm→user';
+export interface DomainLLMStartEvent extends DomainEventBase {
+    readonly type: 'llm.start';
+    readonly model: string;
+    readonly provider: string;
+    readonly systemPromptChars?: number;
+    readonly messagesCount?: number;
+    readonly toolsCount?: number;
+    /** Capture-time classification: `'user→llm'` for the first call or any
+     *  call not preceded by a tool result; `'tool→llm'` after a tool result. */
+    readonly actorArrow: 'user→llm' | 'tool→llm';
+}
+export interface DomainLLMEndEvent extends DomainEventBase {
+    readonly type: 'llm.end';
+    readonly content: string;
+    readonly toolCallCount: number;
+    readonly usage: {
+        readonly input: number;
+        readonly output: number;
+    };
+    readonly stopReason?: string;
+    /** Capture-time classification: `'llm→tool'` when the LLM requested
+     *  tools (`toolCallCount > 0`); `'llm→user'` for terminal delivery. */
+    readonly actorArrow: 'llm→tool' | 'llm→user';
+}
+export interface DomainToolStartEvent extends DomainEventBase {
+    readonly type: 'tool.start';
+    readonly toolName: string;
+    readonly toolCallId: string;
+    readonly args?: unknown;
+}
+export interface DomainToolEndEvent extends DomainEventBase {
+    readonly type: 'tool.end';
+    readonly toolCallId: string;
+    readonly result?: unknown;
+    readonly durationMs?: number;
+    readonly error?: boolean;
+}
+export interface DomainContextInjectedEvent extends DomainEventBase {
+    readonly type: 'context.injected';
+    readonly slot: ContextSlot;
+    readonly source: string;
+    readonly sourceId?: string;
+    readonly asRole?: 'system' | 'user' | 'assistant' | 'tool';
+    readonly contentSummary?: string;
+    readonly reason?: string;
+    readonly sectionTag?: string;
+    readonly upstreamRef?: string;
+    readonly retrievalScore?: number;
+    readonly rankPosition?: number;
+    /** Tokens consumed by this injection (from `budgetSpent.tokens`). */
+    readonly budgetTokens?: number;
+    /** Fraction of slot cap consumed (from `budgetSpent.fractionOfCap`). */
+    readonly budgetFraction?: number;
+}
+/** Discriminated union covering every observable moment in a run. */
+export type DomainEvent = DomainRunEvent | DomainSubflowEvent | DomainCompositionEvent | DomainForkBranchEvent | DomainDecisionBranchEvent | DomainLoopIterationEvent | DomainLLMStartEvent | DomainLLMEndEvent | DomainToolStartEvent | DomainToolEndEvent | DomainContextInjectedEvent;
+/**
+ * Per-boundary rollup returned by
+ * `BoundaryRecorder.aggregateForBoundary` and
+ * `BoundaryRecorder.aggregateAllBoundaries`. Same shape regardless of
+ * primitive kind — UIs render the same chip set for every Agent /
+ * LLMCall / Sequence / Parallel / Conditional / Loop.
+ *
+ * Events count toward this rollup when their `subflowPath` is a
+ * prefix-match of the boundary's `subflowPath`. Nested boundaries
+ * (e.g., LLMCall inside an Agent) contribute to BOTH rollups.
+ *
+ * In-flight boundaries (no `subflow.exit` yet) get partial values;
+ * `endedAtMs` and `durationMs` are undefined until close.
+ */
+export interface BoundaryAggregate {
+    readonly runtimeStageId: string;
+    readonly subflowId: string;
+    readonly subflowPath: readonly string[];
+    /** `'Agent'` / `'LLMCall'` / `'Sequence'` / `'Parallel'` /
+     *  `'Conditional'` / `'Loop'`. Always set on rollups returned by
+     *  `aggregateAllBoundaries` (which filters to primitive boundaries).
+     *  Optional on `aggregateForBoundary` results because the caller may
+     *  request rollup for a non-primitive subflow (rare). */
+    readonly primitiveKind?: string;
+    /** Subflow display name (e.g., 'Triage', 'Billing'). */
+    readonly label: string;
+    /** Token usage summed across every `llm.end` inside this boundary. */
+    readonly tokens: {
+        readonly input: number;
+        readonly output: number;
+    };
+    /** Count of `llm.start` events inside this boundary. */
+    readonly llmCalls: number;
+    /** Count of `tool.start` events inside this boundary. */
+    readonly toolCalls: number;
+    /** Count of `agent.iteration_start` events scoped to this boundary —
+     *  ReAct-loop iterations. Always `0` for non-Agent primitives. */
+    readonly iterations: number;
+    /** Wall-clock ms of `subflow.entry`. */
+    readonly startedAtMs: number;
+    /** Wall-clock ms of `subflow.exit`. Undefined while in flight. */
+    readonly endedAtMs?: number;
+    /** `endedAtMs - startedAtMs`. Undefined while in flight. */
+    readonly durationMs?: number;
+}
+export interface BoundaryRecorderOptions {
+    readonly id?: string;
+    /**
+     * Live commit-count accessor — typically `() => executor.getCommitCount()`
+     * from footprintjs 5.1+. Inject from your runner. When provided:
+     *   - Every DomainEvent gains `commitIdxBefore` / `commitIdxAfter`.
+     *   - `recorder.boundaryIndex` is populated with open/close ranges
+     *     keyed on each subflow's entry event.
+     * When omitted (legacy / pre-5.1 footprintjs): both fields are 0 on
+     * every event; `boundaryIndex` exists but is empty. Phase 5 Layer 2.
+     */
+    readonly getCommitCount?: () => number;
+}
+/**
+ * Stripped projection used as the LABEL for the commit-range index.
+ * Intentionally OMITS `payload` (security panel review YELLOW #1):
+ * `boundaryIndex.enclosing()` queries should not bypass redaction by
+ * exposing raw scope payloads through the range index. Consumers
+ * needing payload can join on `runtimeStageId` with the full event
+ * stream via `getEvents()` (which IS subject to redaction policy).
+ */
+export interface BoundaryRangeLabel {
+    readonly type: 'subflow.entry' | 'run.entry' | 'composition.start';
+    readonly runtimeStageId: string;
+    readonly subflowPath: readonly string[];
+    readonly depth: number;
+    readonly ts: number;
+    /** Set on subflow entries; undefined on the synthetic run-root entry. */
+    readonly subflowId?: string;
+    readonly localSubflowId?: string;
+    readonly subflowName?: string;
+    readonly description?: string;
+    readonly primitiveKind?: string;
+    readonly slotKind?: ContextSlot;
+    readonly isAgentInternal?: boolean;
+    /** Composition primitive (Parallel/Sequence/Loop/Conditional) when the
+     *  range was opened by a `composition.start` event. */
+    readonly compositionKind?: 'Parallel' | 'Sequence' | 'Loop' | 'Conditional';
+    readonly compositionName?: string;
+}
+/** Factory — matches the `inOutRecorder()` / `topologyRecorder()` style. */
+export declare function boundaryRecorder(options?: BoundaryRecorderOptions): BoundaryRecorder;
+/**
+ * Unified domain event recorder. Implements `CombinedRecorder` so it can
+ * attach to the executor's FlowRecorder channel; exposes `subscribe()`
+ * to wire to the agentfootprint typed-event dispatcher.
+ *
+ * v5: composes a `SequenceStore<DomainEvent>` (storage) instead of
+ * extending the deprecated `SequenceStore<T>` base. Time-travel
+ * utilities (`getEntryRanges`, `accumulate`) are accessed through the
+ * store via the public read API on this class.
+ */
+export declare class BoundaryRecorder implements CombinedRecorder {
+    readonly id: string;
+    /** Composition: storage shelf. */
+    private readonly store;
+    /**
+     * Phase 5 Layer 2 — interval index over commit indices, populated
+     * live as boundary entry/exit pairs fire. Consumers (Lens) read
+     * `enclosing(commitIdx)` for breadcrumbs and `overlapping(slice)`
+     * for time-range queries. Empty when `getCommitCount` is not
+     * injected. See `docs/design/boundary-commit-ranges.md`.
+     */
+    readonly boundaryIndex: CommitRangeIndex<BoundaryRangeLabel>;
+    /** Open-range tokens keyed by `runtimeStageId` so the matching exit
+     *  can close the correct range. Pure side-table; cleared on runId
+     *  reset. Not exposed externally. */
+    private readonly openTokens;
+    /** Live commit-count accessor injected by the runner. Sanitized
+     *  (NaN/Infinity/negative → 0) before use. */
+    private readonly getCommitCount;
+    /** True when `getCommitCount` was explicitly injected. In LEGACY
+     *  MODE (false), `boundaryIndex` is intentionally NOT populated —
+     *  zero-width [0,0] ranges would mislead consumers querying the
+     *  index. Multi-panel review flagged this footgun. */
+    private readonly hasCommitTracking;
+    /**
+     * Tracks whether the most recent `llm.end` had toolCalls. Used to
+     * classify the NEXT `llm.start` as `'tool→llm'` (vs `'user→llm'` if
+     * there's no pending tool result). Reset on `clear()` and on every
+     * `llm.start` event after the classification is applied.
+     */
+    private prevLLMEndHadTools;
+    /**
+     * Run-boundary observer — fires resetForNewRun() when
+     * traversalContext.runId changes between events AND no boundary is
+     * currently open. The "no open boundary" gate distinguishes:
+     *
+     *   - **Legitimate new run** — consumer reuses one recorder across
+     *     sequential `executor.run()` calls. All prior boundaries closed
+     *     before the second run began; openTokens is empty when the new
+     *     runId arrives → safe to wipe state so the second run doesn't
+     *     alias with the first.
+     *   - **Composition sub-run** — primitives like `LLMCall`, `Sequence`,
+     *     and `Parallel` internally spawn their own `FlowChartExecutor`
+     *     instances. Each sub-executor mints a NEW runId. When that
+     *     sub-executor fires events on the SHARED recorder, the recorder
+     *     is still inside the parent run — `openTokens` is non-empty.
+     *     Resetting here would wipe the parent's boundary index mid-run
+     *     (the bug Layer 4 surfaced in agentfootprint-lens fanout).
+     *
+     * The `openTokens.size === 0` check is the cleanest semantic signal:
+     * if nothing is in-flight, a runId change means "the consumer started
+     * fresh"; if something is open, the new runId is from a sub-executor
+     * nested inside the still-ongoing parent.
+     */
+    private readonly runIdGuard;
+    constructor(options?: BoundaryRecorderOptions);
+    /**
+     * Reset all transient state.
+     *
+     * **Composition-safe gate (Phase 5 Layer 4):** if `openTokens.size > 0`
+     * the call is a no-op. Rationale: `FlowChartExecutor.run()` calls
+     * `r.clear?.()` on every attached recorder during its pre-run loop.
+     * When agentfootprint composition primitives (LLMCall, Sequence,
+     * Parallel, etc.) propagate the parent's recorders to nested
+     * sub-executors, EACH sub-executor's pre-run clear loop calls
+     * `clear()` on the SHARED parent recorder mid-run — wiping live
+     * parent state. The `openTokens.size > 0` check distinguishes:
+     *
+     *   - **Legitimate reset** — consumer or executor calls `clear()`
+     *     when no boundary is in-flight (`openTokens` empty). Safe to
+     *     wipe; the recorder is idle.
+     *   - **Composition wipe** — sub-executor's pre-run clear fires
+     *     while the parent has open boundaries (`openTokens` non-empty).
+     *     Skip the wipe; the parent's state must be preserved.
+     *
+     * If a consumer needs to forcibly wipe state even with open tokens
+     * (e.g., manual recovery after a crashed run), pair `clear()` with
+     * an explicit `forceClear()` (TODO — add when the use case shows up;
+     * today the recorder lifecycle pattern is "one recorder per logical
+     * run" so leaked tokens shouldn't occur).
+     */
+    clear(): void;
+    private observeRunId;
+    onRunStart(event: FlowRunEvent): void;
+    onRunEnd(event: FlowRunEvent): void;
+    onRunFailed(event: FlowRunFailedEvent): 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 domain
+     * event for each `llm.*` / `tool.*` / `context.injected` event.
+     *
+     * Returns an unsubscribe function; safe to call multiple times (each
+     * call adds a new subscription). Most consumers call this once at
+     * recorder construction and dispose with the returned function.
+     */
+    subscribe(dispatcher: EventDispatcher): Unsubscribe;
+    private ingestTypedEvent;
+    /** All events in capture order (the canonical projection). */
+    getEvents(): DomainEvent[];
+    /** Type-narrowed lookup: all events of one kind. */
+    getEventsByType<T extends DomainEvent['type']>(type: T): Extract<DomainEvent, {
+        type: T;
+    }>[];
+    /** All boundary events (run + subflow, entry + exit interleaved). */
+    getBoundaries(): (DomainRunEvent | DomainSubflowEvent)[];
+    /** Just the entry-phase boundary events — the "step list" timeline. */
+    getSteps(): (DomainRunEvent | DomainSubflowEvent)[];
+    /** Subset of `getSteps()` excluding agent-internal routing subflows. */
+    getVisibleSteps(): (DomainRunEvent | DomainSubflowEvent)[];
+    /** Entry/exit pair for one chart execution by `runtimeStageId`. */
+    getBoundary(runtimeStageId: string): {
+        entry?: DomainRunEvent | DomainSubflowEvent;
+        exit?: DomainRunEvent | DomainSubflowEvent;
+    };
+    /** Convenience for the outermost `__root__` pair. */
+    getRootBoundary(): {
+        entry?: DomainRunEvent;
+        exit?: DomainRunEvent;
+    };
+    /** Subflow events grouped by the 3 input slots — for slot-row rendering. */
+    getSlotBoundaries(): {
+        systemPrompt: DomainSubflowEvent[];
+        messages: DomainSubflowEvent[];
+        tools: DomainSubflowEvent[];
+    };
+    /**
+     * Roll up the event stream for ONE primitive boundary (Agent /
+     * LLMCall / Sequence / Parallel / Conditional / Loop) into per-
+     * boundary totals — tokens, llm calls, tool calls, iterations,
+     * cache hits, duration.
+     *
+     * Pure projection over `getEvents()`. Events are attributed to a
+     * boundary when their `subflowPath` is a **prefix-match** of the
+     * boundary's path — so a nested `LLMCall` inside an `Agent` rolls
+     * up into BOTH (LLMCall total + Agent total).
+     *
+     * Works mid-run (the boundary's `subflow.exit` may not have fired
+     * yet — `endedAtMs` / `durationMs` are undefined in that case).
+     * Works post-run.
+     *
+     * Multi-consumer story: this is the single source of rollup truth
+     * for Lens, CLI live monitors, Sentry breadcrumbs, OTel exporters,
+     * dashboards. Domain math (what counts as an "iteration"? does
+     * cache hit count separately from llmCalls?) lives HERE — every
+     * consumer hooks up; nobody re-implements.
+     *
+     * @param runtimeStageId The boundary's runtimeStageId (the same id
+     *   carried by `StepNode.runtimeStageId` for primitive subflows).
+     * @returns The rollup, or `undefined` if no `subflow.entry` event
+     *   matches `runtimeStageId`.
+     */
+    aggregateForBoundary(runtimeStageId: string): BoundaryAggregate | undefined;
+    /**
+     * Roll up every primitive boundary in the run into one rollup each,
+     * in the order their `subflow.entry` events fired. Top-level multi-
+     * agent UIs call this once per render to populate per-agent chips.
+     *
+     * Filters to `primitiveKind`-tagged subflows ONLY (Agent / LLMCall /
+     * Sequence / Parallel / Conditional / Loop). Slot subflows
+     * (`sf-system-prompt` / `sf-messages` / `sf-tools`) are NOT
+     * boundaries in this sense — they're context-engineering machinery,
+     * not user-facing rollup units.
+     */
+    aggregateAllBoundaries(): readonly BoundaryAggregate[];
+    /** Snapshot bundle — included in `executor.getSnapshot()` if the
+     *  executor implements the snapshot extension protocol. */
+    toSnapshot(): {
+        name: string;
+        description: string;
+        preferredOperation: "translate";
+        data: DomainEvent[];
+    };
+}
+export {};