agentfootprint 1.22.0 → 2.0.1

package/dist/types/recorders/core/MemoryRecorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MemoryRecorder.d.ts","sourceRoot":"","sources":["../../../../src/recorders/core/MemoryRecorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAErE,MAAM,MAAM,qBAAqB,GAAG,IAAI,CAAC,iBAAiB,EAAE,IAAI,GAAG,QAAQ,CAAC,GAAG;IAC7E,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,wBAAgB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,UAAU,CAOzE"}

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

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

package/dist/types/recorders/core/PermissionRecorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PermissionRecorder.d.ts","sourceRoot":"","sources":["../../../../src/recorders/core/PermissionRecorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAErE,MAAM,MAAM,yBAAyB,GAAG,IAAI,CAAC,iBAAiB,EAAE,IAAI,GAAG,QAAQ,CAAC,GAAG;IACjF,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,yBAAyB,GAAG,UAAU,CAOjF"}

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

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

package/dist/types/recorders/core/SkillRecorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SkillRecorder.d.ts","sourceRoot":"","sources":["../../../../src/recorders/core/SkillRecorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAErE,MAAM,MAAM,oBAAoB,GAAG,IAAI,CAAC,iBAAiB,EAAE,IAAI,GAAG,QAAQ,CAAC,GAAG;IAC5E,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,UAAU,CAOvE"}

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

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

package/dist/types/recorders/core/StreamRecorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StreamRecorder.d.ts","sourceRoot":"","sources":["../../../../src/recorders/core/StreamRecorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAErE,MAAM,MAAM,qBAAqB,GAAG,IAAI,CAAC,iBAAiB,EAAE,IAAI,GAAG,QAAQ,CAAC,GAAG;IAC7E,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,wBAAgB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,UAAU,CAOzE"}

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

@@ -0,0 +1,35 @@
+/**
+ * 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-7',
+ *     systemPromptChars: 800,
+ *     messagesCount: 2,
+ *     toolsCount: 0,
+ *   });
+ */
+export declare function typedEmit<K extends AgentfootprintEventType>(scope: EmitableScope, type: K, payload: AgentfootprintEventMap[K]['payload']): void;
+export {};
+//# sourceMappingURL=typedEmit.d.ts.map

package/dist/types/recorders/core/typedEmit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typedEmit.d.ts","sourceRoot":"","sources":["../../../../src/recorders/core/typedEmit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAEhG;;;;GAIG;AACH,UAAU,aAAa;IACrB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CAC9C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,uBAAuB,EACzD,KAAK,EAAE,aAAa,EACpB,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,sBAAsB,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,GAC5C,IAAI,CAEN"}

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

@@ -0,0 +1,98 @@
+/**
+ * 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];
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/recorders/core/types.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,301 @@
+/**
+ * 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 } from 'agentfootprint';
+ *
+ * const boundary = boundaryRecorder();
+ * executor.attachCombinedRecorder(boundary);   // wires FlowRecorder side
+ * boundary.subscribe(runner.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 { SequenceRecorder } from 'footprintjs/trace';
+import type { CombinedRecorder, FlowDecisionEvent, FlowForkEvent, FlowLoopEvent, FlowSubflowEvent, TraversalContext } from 'footprintjs';
+interface FlowRunEvent {
+    readonly payload?: unknown;
+    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;
+}
+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;
+}
+/**
+ * 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 | DomainForkBranchEvent | DomainDecisionBranchEvent | DomainLoopIterationEvent | DomainLLMStartEvent | DomainLLMEndEvent | DomainToolStartEvent | DomainToolEndEvent | DomainContextInjectedEvent;
+export interface BoundaryRecorderOptions {
+    readonly id?: 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.
+ *
+ * Internally stores events in a `SequenceRecorder<DomainEvent>` so the
+ * usual time-travel utilities (`getEntryRanges`, `accumulate`) work
+ * out of the box.
+ */
+export declare class BoundaryRecorder extends SequenceRecorder<DomainEvent> implements CombinedRecorder {
+    readonly id: string;
+    /**
+     * 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;
+    constructor(options?: BoundaryRecorderOptions);
+    clear(): void;
+    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 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[];
+    };
+    /** Snapshot bundle — included in `executor.getSnapshot()` if the
+     *  executor implements the snapshot extension protocol. */
+    toSnapshot(): {
+        name: string;
+        description: string;
+        preferredOperation: "translate";
+        data: DomainEvent[];
+    };
+}
+export {};
+//# sourceMappingURL=BoundaryRecorder.d.ts.map

package/dist/types/recorders/observability/BoundaryRecorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BoundaryRecorder.d.ts","sourceRoot":"","sources":["../../../../src/recorders/observability/BoundaryRecorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4EG;AAEH,OAAO,EAA0C,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC7F,OAAO,KAAK,EACV,gBAAgB,EAChB,iBAAiB,EACjB,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,gBAAgB,EACjB,MAAM,aAAa,CAAC;AAMrB,UAAU,YAAY;IACpB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CAC9C;AAED,OAAO,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAE/E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAIzD,yCAAyC;AACzC,UAAU,eAAe;IACvB;;wEAEoE;IACpE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,6EAA6E;IAC7E,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,qCAAqC;IACrC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,cAAe,SAAQ,eAAe;IACrD,QAAQ,CAAC,IAAI,EAAE,WAAW,GAAG,UAAU,CAAC;IACxC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC;CACvB;AAED,MAAM,WAAW,kBAAmB,SAAQ,eAAe;IACzD,QAAQ,CAAC,IAAI,EAAE,eAAe,GAAG,cAAc,CAAC;IAChD,sEAAsE;IACtE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,wEAAwE;IACxE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,6EAA6E;IAC7E,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,0FAA0F;IAC1F,QAAQ,CAAC,QAAQ,CAAC,EAAE,WAAW,CAAC;IAChC,+FAA+F;IAC/F,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,mEAAmE;IACnE,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,qBAAsB,SAAQ,eAAe;IAC5D,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,yBAA0B,SAAQ,eAAe;IAChE,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;;;;OASG;IACH,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;CACnC;AAED,MAAM,WAAW,wBAAyB,SAAQ,eAAe;IAC/D,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,UAAU,GAAG,UAAU,GAAG,UAAU,CAAC;AAE3E,MAAM,WAAW,mBAAoB,SAAQ,eAAe;IAC1D,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;gFAC4E;IAC5E,QAAQ,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU,CAAC;CAC9C;AAED,MAAM,WAAW,iBAAkB,SAAQ,eAAe;IACxD,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACpE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;2EACuE;IACvE,QAAQ,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU,CAAC;CAC9C;AAED,MAAM,WAAW,oBAAqB,SAAQ,eAAe;IAC3D,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,kBAAmB,SAAQ,eAAe;IACzD,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,0BAA2B,SAAQ,eAAe;IACjE,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC;IAC3D,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,qEAAqE;IACrE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,wEAAwE;IACxE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,qEAAqE;AACrE,MAAM,MAAM,WAAW,GACnB,cAAc,GACd,kBAAkB,GAClB,qBAAqB,GACrB,yBAAyB,GACzB,wBAAwB,GACxB,mBAAmB,GACnB,iBAAiB,GACjB,oBAAoB,GACpB,kBAAkB,GAClB,0BAA0B,CAAC;AAY/B,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;CACtB;AAID,4EAA4E;AAC5E,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,uBAA4B,GAAG,gBAAgB,CAExF;AAED;;;;;;;;GAQG;AACH,qBAAa,gBAAiB,SAAQ,gBAAgB,CAAC,WAAW,CAAE,YAAW,gBAAgB;IAC7F,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB,CAAS;gBAEvB,OAAO,GAAE,uBAA4B;IAKxC,KAAK,IAAI,IAAI;IAOtB,UAAU,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI;IAIrC,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI;IAInC,cAAc,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI;IAK7C,aAAa,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI;IAK5C,MAAM,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI;IAmBlC,UAAU,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI;IA2B1C,MAAM,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI;IAelC;;;;;;;OAOG;IACH,SAAS,CAAC,UAAU,EAAE,eAAe,GAAG,WAAW;IAMnD,OAAO,CAAC,gBAAgB;IAuHxB,8DAA8D;IAC9D,SAAS,IAAI,WAAW,EAAE;IAI1B,oDAAoD;IACpD,eAAe,CAAC,CAAC,SAAS,WAAW,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,WAAW,EAAE;QAAE,IAAI,EAAE,CAAC,CAAA;KAAE,CAAC,EAAE;IAU5F,qEAAqE;IACrE,aAAa,IAAI,CAAC,cAAc,GAAG,kBAAkB,CAAC,EAAE;IAexD,uEAAuE;IACvE,QAAQ,IAAI,CAAC,cAAc,GAAG,kBAAkB,CAAC,EAAE;IAInD,wEAAwE;IACxE,eAAe,IAAI,CAAC,cAAc,GAAG,kBAAkB,CAAC,EAAE;IAI1D,mEAAmE;IACnE,WAAW,CAAC,cAAc,EAAE,MAAM,GAAG;QACnC,KAAK,CAAC,EAAE,cAAc,GAAG,kBAAkB,CAAC;QAC5C,IAAI,CAAC,EAAE,cAAc,GAAG,kBAAkB,CAAC;KAC5C;IAcD,qDAAqD;IACrD,eAAe,IAAI;QACjB,KAAK,CAAC,EAAE,cAAc,CAAC;QACvB,IAAI,CAAC,EAAE,cAAc,CAAC;KACvB;IAQD,4EAA4E;IAC5E,iBAAiB,IAAI;QACnB,YAAY,EAAE,kBAAkB,EAAE,CAAC;QACnC,QAAQ,EAAE,kBAAkB,EAAE,CAAC;QAC/B,KAAK,EAAE,kBAAkB,EAAE,CAAC;KAC7B;IAaD;+DAC2D;IAC3D,UAAU;;;;;;CAQX"}