footprintjs 4.1.0 → 4.3.0

package/dist/types/lib/scope/ScopeFacade.d.ts

@@ -62,6 +62,10 @@ export declare class ScopeFacade {
     /** @internal */
     notifyStageEnd(duration?: number): void;
     /** @internal */
+    notifyPause(stageId: string, pauseData?: unknown): void;
+    /** @internal */
+    notifyResume(stageId: string, hasInput: boolean): void;
+    /** @internal */
     notifyCommit(mutations: CommitEvent['mutations']): void;
     /** Called by StageContext.commit() observer. Converts tracked writes to CommitEvent format.
      *  Errors are caught to prevent recorder issues from aborting the traversal. */

package/dist/types/lib/scope/recorders/DebugRecorder.d.ts

@@ -4,10 +4,10 @@
  * Captures errors (always), mutations and reads (in verbose mode),
  * and stage lifecycle events for troubleshooting.
  */
-import type { ErrorEvent, ReadEvent, Recorder, StageEvent, WriteEvent } from '../types.js';
+import type { ErrorEvent, PauseEvent, ReadEvent, Recorder, ResumeEvent, StageEvent, WriteEvent } from '../types.js';
 export type DebugVerbosity = 'minimal' | 'verbose';
 export interface DebugEntry {
-    type: 'read' | 'write' | 'error' | 'stageStart' | 'stageEnd';
+    type: 'read' | 'write' | 'error' | 'stageStart' | 'stageEnd' | 'pause' | 'resume';
     stageName: string;
     timestamp: number;
     data: unknown;
@@ -16,7 +16,23 @@ export interface DebugRecorderOptions {
     id?: string;
     verbosity?: DebugVerbosity;
 }
+/**
+ * Each instance gets a unique auto-increment ID (`debug-1`, `debug-2`, ...),
+ * so multiple recorders with different verbosity coexist.
+ *
+ * @example
+ * ```typescript
+ * // Verbose debug for development
+ * executor.attachRecorder(new DebugRecorder({ verbosity: 'verbose' }));
+ *
+ * // Minimal debug for production (errors only)
+ * executor.attachRecorder(new DebugRecorder({ verbosity: 'minimal' }));
+ *
+ * // Both coexist — different auto IDs
+ * ```
+ */
 export declare class DebugRecorder implements Recorder {
+    private static _counter;
     readonly id: string;
     private entries;
     private verbosity;
@@ -26,6 +42,8 @@ export declare class DebugRecorder implements Recorder {
     onError(event: ErrorEvent): void;
     onStageStart(event: StageEvent): void;
     onStageEnd(event: StageEvent): void;
+    onPause(event: PauseEvent): void;
+    onResume(event: ResumeEvent): void;
     getEntries(): DebugEntry[];
     getErrors(): DebugEntry[];
     getEntriesForStage(stageName: string): DebugEntry[];

package/dist/types/lib/scope/recorders/MetricRecorder.d.ts

@@ -1,14 +1,41 @@
 /**
- * MetricRecorder — Production-focused recorder for timing and execution counts
+ * MetricRecorder — Production-focused recorder for timing and execution counts.
  *
  * Tracks read/write/commit counts per stage and measures stage execution duration.
+ *
+ * Each instance gets a unique auto-increment ID (`metrics-1`, `metrics-2`, ...),
+ * so multiple recorders with different configs coexist. Pass an explicit ID to
+ * override a specific instance (e.g., a framework-attached recorder).
+ *
+ * @example
+ * ```typescript
+ * // Track all stages (default)
+ * executor.attachRecorder(new MetricRecorder());
+ *
+ * // Track only LLM-related stages
+ * executor.attachRecorder(new MetricRecorder({
+ *   stageFilter: (name) => ['CallLLM', 'ParseResponse'].includes(name),
+ * }));
+ *
+ * // Two recorders: one for LLM timing, one for everything else
+ * executor.attachRecorder(new MetricRecorder({
+ *   stageFilter: (name) => name === 'CallLLM',
+ * }));
+ * executor.attachRecorder(new MetricRecorder({
+ *   stageFilter: (name) => name !== 'CallLLM',
+ * }));
+ *
+ * // Override a framework-attached recorder by passing its well-known ID
+ * executor.attachRecorder(new MetricRecorder({ id: 'metrics' }));
+ * ```
  */
-import type { CommitEvent, ReadEvent, Recorder, StageEvent, WriteEvent } from '../types.js';
+import type { CommitEvent, PauseEvent, ReadEvent, Recorder, StageEvent, WriteEvent } from '../types.js';
 export interface StageMetrics {
     stageName: string;
     readCount: number;
     writeCount: number;
     commitCount: number;
+    pauseCount: number;
     totalDuration: number;
     invocationCount: number;
 }
@@ -17,16 +44,37 @@ export interface AggregatedMetrics {
     totalReads: number;
     totalWrites: number;
     totalCommits: number;
+    totalPauses: number;
     stageMetrics: Map<string, StageMetrics>;
 }
+/** Options for MetricRecorder. All fields are optional. */
+export interface MetricRecorderOptions {
+    /** Recorder ID. Defaults to auto-increment (`metrics-1`, `metrics-2`, ...). */
+    id?: string;
+    /**
+     * Filter which stages are recorded. Return `true` to record, `false` to skip.
+     * When omitted, all stages are recorded.
+     *
+     * @example
+     * ```typescript
+     * // Only track stages that start with "Call"
+     * stageFilter: (name) => name.startsWith('Call')
+     * ```
+     */
+    stageFilter?: (stageName: string) => boolean;
+}
 export declare class MetricRecorder implements Recorder {
+    private static _counter;
     readonly id: string;
     private metrics;
     private stageStartTimes;
-    constructor(id?: string);
+    private stageFilter?;
+    constructor(idOrOptions?: string | MetricRecorderOptions);
+    private shouldRecord;
     onRead(event: ReadEvent): void;
     onWrite(event: WriteEvent): void;
     onCommit(event: CommitEvent): void;
+    onPause(event: PauseEvent): void;
     onStageStart(event: StageEvent): void;
     onStageEnd(event: StageEvent): void;
     getMetrics(): AggregatedMetrics;

package/dist/types/lib/scope/types.d.ts

@@ -38,6 +38,14 @@ export interface ErrorEvent extends RecorderContext {
 export interface StageEvent extends RecorderContext {
     duration?: number;
 }
+export interface PauseEvent extends RecorderContext {
+    stageId: string;
+    pauseData?: unknown;
+}
+export interface ResumeEvent extends RecorderContext {
+    stageId: string;
+    hasInput: boolean;
+}
 /**
  * Declarative redaction configuration — define once, applied everywhere.
  *
@@ -86,6 +94,8 @@ export interface Recorder {
     onError?(event: ErrorEvent): void;
     onStageStart?(event: StageEvent): void;
     onStageEnd?(event: StageEvent): void;
+    onPause?(event: PauseEvent): void;
+    onResume?(event: ResumeEvent): void;
     /** Reset state before each executor.run() — prevents cross-run accumulation. */
     clear?(): void;
     /** Expose collected data for inclusion in executor.getSnapshot().recorders. */

package/dist/types/recorders.d.ts

@@ -33,7 +33,7 @@ import { MilestoneNarrativeFlowRecorder } from './lib/engine/narrative/recorders
 import { WindowedNarrativeFlowRecorder } from './lib/engine/narrative/recorders/WindowedNarrativeFlowRecorder.js';
 import type { DebugEntry, DebugRecorderOptions } from './lib/scope/recorders/DebugRecorder.js';
 import { DebugRecorder } from './lib/scope/recorders/DebugRecorder.js';
-import type { AggregatedMetrics, StageMetrics } from './lib/scope/recorders/MetricRecorder.js';
+import type { AggregatedMetrics, MetricRecorderOptions, StageMetrics } from './lib/scope/recorders/MetricRecorder.js';
 import { MetricRecorder } from './lib/scope/recorders/MetricRecorder.js';
 export type NarrativeInstance = CombinedNarrativeRecorder & {
     lines(): string[];
@@ -47,7 +47,7 @@ export type MetricsInstance = MetricRecorder & {
     stage(name: string): StageMetrics | undefined;
     all(): AggregatedMetrics;
 };
-export declare function metrics(): MetricsInstance;
+export declare function metrics(options?: MetricRecorderOptions): MetricsInstance;
 export type DebugInstance = DebugRecorder & {
     logs(): DebugEntry[];
 };
@@ -60,3 +60,6 @@ export declare function adaptive(): AdaptiveNarrativeFlowRecorder;
 export declare function milestone(): MilestoneNarrativeFlowRecorder;
 export declare function windowed(maxEntries?: number): WindowedNarrativeFlowRecorder;
 export type { BreakRenderContext, CombinedNarrativeRecorderOptions, DecisionRenderContext, ErrorRenderContext, ForkRenderContext, LoopRenderContext, NarrativeRenderer, OpRenderContext, SelectedRenderContext, StageRenderContext, SubflowRenderContext, };
+export type { AggregatedMetrics, MetricRecorderOptions, StageMetrics };
+export type { CompositeSnapshot } from './lib/recorder/index.js';
+export { CompositeRecorder } from './lib/recorder/index.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "footprintjs",
-  "version": "4.1.0",
+  "version": "4.3.0",
   "description": "Explainable backend flows — automatic causal traces, decision evidence, and MCP tool generation for AI agents",
   "license": "MIT",
   "author": "Sanjay Krishna Anbalagan",