agentfootprint 2.14.0 → 2.14.2

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

@@ -0,0 +1,215 @@
+/**
+ * LiveStateRecorder — domain trackers built on the footprintjs
+ * `BoundaryStateTracker<TState>` storage primitive (v4.17.2+).
+ *
+ * **What this answers:** "Right now, mid-run, what's happening?"
+ *
+ *   - Is an LLM call in flight? What's the partial answer so far?
+ *   - Is a tool executing? Which tool? What args?
+ *   - Is the agent in a turn? Which turn index?
+ *
+ * All reads are O(1) — the trackers maintain incremental state via
+ * the framework's bracket-scoped storage primitive. No event-log fold,
+ * no walking arrays per render.
+ *
+ * **Mental model — observers vs. bookkeepers:**
+ *
+ *   `BoundaryStateTracker<TState>` (footprintjs) = STORAGE shelf.
+ *   `EventDispatcher.on(...)` (agentfootprint)  = OBSERVER source.
+ *
+ *   Each domain tracker (`LiveLLMTracker`, `LiveToolTracker`,
+ *   `LiveAgentTurnTracker`) extends the storage shelf AND subscribes
+ *   to the dispatcher. The composition `LiveStateRecorder` bundles
+ *   all three so a consumer only attaches once.
+ *
+ * **Tier 1 (live) only.** Past states are not stored — when a boundary
+ * closes, its transient state clears. For time-travel queries, snapshot
+ * to a `SequenceRecorder<TState>` instead. See the BoundaryStateTracker
+ * JSDoc for the rationale.
+ *
+ * @example Use the bundled façade — one attach, three live views:
+ *
+ * ```typescript
+ * import { LiveStateRecorder } from 'agentfootprint';
+ *
+ * const liveState = new LiveStateRecorder();
+ * liveState.subscribe(runner);
+ *
+ * await runner.run({ input });
+ *
+ * // Read at any moment during the run (e.g., from another async task):
+ * liveState.isLLMInFlight();          // true between llm_start ↔ llm_end
+ * liveState.getPartialLLM();          // accumulated tokens so far
+ * liveState.isToolExecuting();        // true between tool_start ↔ tool_end
+ * liveState.isAgentInTurn();          // true between turn_start ↔ turn_end
+ *
+ * liveState.unsubscribe();
+ * ```
+ *
+ * @example Use a single tracker directly when you only need one slice:
+ *
+ * ```typescript
+ * import { LiveLLMTracker } from 'agentfootprint';
+ *
+ * const llm = new LiveLLMTracker();
+ * llm.subscribe(runner);
+ * await runner.run({ input });
+ *
+ * llm.isInFlight();                   // O(1)
+ * llm.getLatestPartial();             // most recent active call's partial
+ * llm.getActive(rid)?.tokens;         // tokens accumulated for one call
+ * ```
+ */
+import { BoundaryStateTracker } from 'footprintjs/trace';
+import type { Unsubscribe } from '../../events/dispatcher.js';
+import type { AgentfootprintEvent, AgentfootprintEventType } from '../../events/registry.js';
+/** Minimal Runner shape this recorder needs — only the public `on(...)`
+ *  subscription method, so the same trackers can attach to a real Runner
+ *  (Agent, etc.) OR to a test mock without exposing the protected
+ *  internal dispatcher. */
+export interface LiveStateRunnerLike {
+    on<K extends AgentfootprintEventType>(type: K, listener: (event: Extract<AgentfootprintEvent, {
+        type: K;
+    }>) => void): Unsubscribe;
+}
+/** Live transient state of one in-flight LLM call. */
+export interface LLMLiveState {
+    /** Accumulated content from `stream.token` events since `llm_start`. */
+    readonly partial: string;
+    /** Number of tokens received so far. */
+    readonly tokens: number;
+    /** Iteration index (from the LLMStartPayload). */
+    readonly iteration: number;
+    /** Provider name (e.g., 'anthropic', 'openai'). */
+    readonly provider: string;
+    /** Model id. */
+    readonly model: string;
+    /** Wall-clock ms when llm_start fired. */
+    readonly startedAtMs: number;
+}
+/** Live transient state of one in-flight tool call. */
+export interface ToolLiveState {
+    readonly toolName: string;
+    readonly args: Readonly<Record<string, unknown>>;
+    readonly toolCallId: string;
+    readonly startedAtMs: number;
+}
+/** Live transient state of one in-flight agent turn. */
+export interface AgentTurnLiveState {
+    readonly turnIndex: number;
+    readonly userPrompt: string;
+    readonly startedAtMs: number;
+}
+/**
+ * Tracks the in-flight state of LLM calls. Subscribes to:
+ *   - `agentfootprint.stream.llm_start`  → opens a boundary
+ *   - `agentfootprint.stream.token`      → appends to partial
+ *   - `agentfootprint.stream.llm_end`    → closes the boundary
+ *
+ * Boundary key: `runtimeStageId` of the call-llm stage. Parallel LLM
+ * calls (Parallel composition with multiple branches) get distinct
+ * keys and are tracked independently.
+ */
+export declare class LiveLLMTracker extends BoundaryStateTracker<LLMLiveState> {
+    readonly id = "live-llm";
+    /** Subscribe to a runner's dispatcher. Returns an Unsubscribe. */
+    subscribe(runner: LiveStateRunnerLike): Unsubscribe;
+    /** True if any LLM call is currently in flight. Same as `hasActive`. */
+    isInFlight(): boolean;
+    /** Accumulated partial content of the MOST RECENTLY started active
+     *  LLM call. Empty string when no call is active. Useful for the
+     *  classic "Chatbot is responding: …" live commentary line. */
+    getLatestPartial(): string;
+}
+/**
+ * Tracks in-flight tool calls. Subscribes to:
+ *   - `agentfootprint.stream.tool_start` → opens a boundary
+ *   - `agentfootprint.stream.tool_end`   → closes the boundary
+ *
+ * Boundary key: `toolCallId` (more granular than `runtimeStageId` —
+ * parallel tools share one calling stage but have distinct toolCallIds).
+ */
+export declare class LiveToolTracker extends BoundaryStateTracker<ToolLiveState> {
+    readonly id = "live-tool";
+    subscribe(runner: LiveStateRunnerLike): Unsubscribe;
+    /** True if any tool is currently executing. */
+    isExecuting(): boolean;
+    /** Names of tools currently executing. Empty when none. */
+    getExecutingToolNames(): readonly string[];
+}
+/**
+ * Tracks in-flight agent turns. Subscribes to:
+ *   - `agentfootprint.agent.turn_start` → opens a boundary
+ *   - `agentfootprint.agent.turn_end`   → closes the boundary
+ *
+ * Boundary key: stringified `turnIndex` from the payload — survives
+ * across runner instances because turnIndex resets per-session.
+ */
+export declare class LiveAgentTurnTracker extends BoundaryStateTracker<AgentTurnLiveState> {
+    readonly id = "live-agent-turn";
+    subscribe(runner: LiveStateRunnerLike): Unsubscribe;
+    /** True if the agent is currently inside a turn. */
+    isInTurn(): boolean;
+    /** Index of the most-recently started active turn (-1 if none). */
+    getCurrentTurnIndex(): number;
+}
+/**
+ * One-stop façade bundling `LiveLLMTracker` + `LiveToolTracker` +
+ * `LiveAgentTurnTracker`. Consumers attach this once and get O(1)
+ * reads across all three live-state slices.
+ *
+ * Use the bundled façade unless you ONLY need one slice — using a
+ * single tracker directly avoids subscribing to events you don't read.
+ *
+ * **Lifecycle**: call `subscribe(runner)` to wire all three trackers,
+ * then `unsubscribe()` to detach. `clear()` resets all transient state
+ * across the three (called automatically by consumers like Lens between
+ * runs).
+ *
+ * **What this is NOT for:**
+ *   - Time-travel queries (Tier 1 only — live state)
+ *   - Aggregations (use SequenceRecorder.aggregate)
+ *   - Stage-level observation (use Recorder.onStageStart/End)
+ *
+ * **Composition over inheritance:** the façade does NOT extend
+ * `BoundaryStateTracker` itself — different boundary kinds need
+ * separate active maps to avoid key collisions between LLM and tool
+ * boundaries. Each sub-tracker keeps its own state.
+ */
+export declare class LiveStateRecorder {
+    readonly id = "live-state";
+    /** LLM call live state. */
+    readonly llm: LiveLLMTracker;
+    /** Tool execution live state. */
+    readonly tool: LiveToolTracker;
+    /** Agent turn live state. */
+    readonly turn: LiveAgentTurnTracker;
+    /** Active subscription disposer, if `subscribe()` is called. */
+    private active;
+    constructor();
+    /** Subscribe all three trackers to one runner. Idempotent — calling
+     *  twice on the same recorder unsubscribes the prior subscription
+     *  first to avoid double-counting. */
+    subscribe(runner: LiveStateRunnerLike): Unsubscribe;
+    /** Detach all three trackers from the current runner. Idempotent. */
+    unsubscribe(): void;
+    /** Reset transient state across all three trackers. Called by the
+     *  executor / consumer between runs. */
+    clear(): void;
+    /** True if any LLM call is currently in flight. */
+    isLLMInFlight(): boolean;
+    /** Accumulated partial content of the most-recently started LLM call. */
+    getPartialLLM(): string;
+    /** True if any tool is currently executing. */
+    isToolExecuting(): boolean;
+    /** Names of tools currently executing. */
+    getExecutingToolNames(): readonly string[];
+    /** True if the agent is currently inside a turn. */
+    isAgentInTurn(): boolean;
+    /** Current turn index (-1 if not in a turn). */
+    getCurrentTurnIndex(): number;
+}
+/** Convenience factory — same shape as `boundaryRecorder()` /
+ *  `topologyRecorder()` / `inOutRecorder()` in footprintjs. */
+export declare function liveStateRecorder(): LiveStateRecorder;
+//# sourceMappingURL=LiveStateRecorder.d.ts.map

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentfootprint",
-  "version": "2.14.0",
+  "version": "2.14.2",
   "description": "The explainable agent framework — build AI agents you can explain, audit, and trust. Built on footprintjs.",
   "license": "MIT",
   "author": "Sanjay Krishna Anbalagan",
@@ -184,7 +184,7 @@
     "@aws-sdk/client-xray": "*",
     "@modelcontextprotocol/sdk": "*",
     "@opentelemetry/api": "*",
-    "footprintjs": ">=4.17.1",
+    "footprintjs": ">=4.17.2",
     "ioredis": "*",
     "openai": "*",
     "zod": "*"
@@ -228,7 +228,7 @@
     "@vitest/coverage-v8": "^4.1.5",
     "eslint": "^8.44.0",
     "eslint-config-prettier": "^6.15.0",
-    "footprintjs": "^4.17.1",
+    "footprintjs": "^4.17.2",
     "prettier": "^2.8.1",
     "typedoc": "^0.28.19",
     "typedoc-plugin-markdown": "^4.11.0",