footprintjs 4.0.5 → 4.2.0

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

@@ -1,7 +1,33 @@
 /**
- * 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';
 export interface StageMetrics {
@@ -19,11 +45,30 @@ export interface AggregatedMetrics {
     totalCommits: 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;

package/dist/types/recorders.d.ts

@@ -23,8 +23,9 @@
  * Each factory returns the raw recorder instance with added short convenience methods.
  * Pass directly to chart.recorder(). No wrapping, no proxying -- just the class + shortcuts.
  */
+import type { CombinedNarrativeRecorderOptions } from './lib/engine/narrative/CombinedNarrativeRecorder.js';
 import { CombinedNarrativeRecorder } from './lib/engine/narrative/CombinedNarrativeRecorder.js';
-import type { CombinedNarrativeEntry } from './lib/engine/narrative/narrativeTypes.js';
+import type { BreakRenderContext, CombinedNarrativeEntry, DecisionRenderContext, ErrorRenderContext, ForkRenderContext, LoopRenderContext, NarrativeRenderer, OpRenderContext, SelectedRenderContext, StageRenderContext, SubflowRenderContext } from './lib/engine/narrative/narrativeTypes.js';
 import { AdaptiveNarrativeFlowRecorder } from './lib/engine/narrative/recorders/AdaptiveNarrativeFlowRecorder.js';
 import type { ManifestEntry } from './lib/engine/narrative/recorders/ManifestFlowRecorder.js';
 import { ManifestFlowRecorder } from './lib/engine/narrative/recorders/ManifestFlowRecorder.js';
@@ -32,13 +33,13 @@ 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[];
     structured(): CombinedNarrativeEntry[];
 };
-export declare function narrative(): NarrativeInstance;
+export declare function narrative(options?: CombinedNarrativeRecorderOptions): NarrativeInstance;
 export type MetricsInstance = MetricRecorder & {
     reads(): number;
     writes(): number;
@@ -46,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[];
 };
@@ -58,3 +59,7 @@ export declare function manifest(): ManifestInstance;
 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.0.5",
+  "version": "4.2.0",
   "description": "Explainable backend flows — automatic causal traces, decision evidence, and MCP tool generation for AI agents",
   "license": "MIT",
   "author": "Sanjay Krishna Anbalagan",