agentfootprint-lens 0.20.0 → 0.21.0

package/dist/{chunk-N3YJKWK5.js → chunk-BTVAAE66.js}

@@ -306,6 +306,7 @@ function relTime(runStartMs) {
 }
 
 // src/core/LensRecorder.ts
+var DEFAULT_MAX_EVENTS = 5e4;
 var KNOWN_EVENT_TYPES = new Set(ALL_EVENT_TYPES);
 var LensRecorder = class {
   constructor(rootLabel = "Run", options = {}) {
@@ -387,7 +388,18 @@ var LensRecorder = class {
     /** Unknown types already warned about — warn ONCE per type, not per
      *  event, so a chatty unknown emitter can't flood the console. */
     this.warnedUnknownTypes = /* @__PURE__ */ new Set();
+    /** Entries evicted by the cap so far. Surfaced via `getDiagnostics()`. */
+    this.droppedEventCount = 0;
+    /** Eviction already warned about — warn ONCE per run, not per batch. */
+    this.warnedEviction = false;
     this.debug = options.debug;
+    const cap = options.maxEvents ?? DEFAULT_MAX_EVENTS;
+    if (cap !== Number.POSITIVE_INFINITY && (!Number.isInteger(cap) || cap < 1)) {
+      throw new RangeError(
+        `LensRecorder: maxEvents must be a positive integer or Infinity, got ${cap}`
+      );
+    }
+    this.maxEvents = cap;
     this.root = {
       id: "run-root",
       kind: "run",
@@ -417,6 +429,8 @@ var LensRecorder = class {
     this.unknownEventTypes.clear();
     this.bracketMismatchCount = 0;
     this.warnedUnknownTypes.clear();
+    this.droppedEventCount = 0;
+    this.warnedEviction = false;
     this.liveState.clear();
     this.boundary.clear();
     this.runtime.reset();
@@ -436,14 +450,18 @@ var LensRecorder = class {
    *     `composition.exit`, ...) whose kind didn't match the top of the
    *     build stack (malformed ordering). The close is skipped; the
    *     tree stays partially structured rather than crashing.
+   *   - `droppedEvents` — entries evicted by the `maxEvents` FIFO cap
+   *     (U3). When non-zero, log-derived views cover only the retained
+   *     tail of the run.
    *
-   * Both are `{}` / `0` on a well-formed run. Reset by `clear()`.
-   * Returns a fresh snapshot object on every call.
+   * All are `{}` / `0` on a well-formed run that stayed under the cap.
+   * Reset by `clear()`. Returns a fresh snapshot object on every call.
    */
   getDiagnostics() {
     return {
       unknownEventTypes: Object.fromEntries(this.unknownEventTypes),
-      bracketMismatches: this.bracketMismatchCount
+      bracketMismatches: this.bracketMismatchCount,
+      droppedEvents: this.droppedEventCount
     };
   }
   /** Whether diagnostic warnings go to the console: explicit option
@@ -604,8 +622,52 @@ var LensRecorder = class {
     this.top().events.push(entry);
     this.noteUnknownType(event.type);
     this.dispatch(event, runOffsetMs, entry);
+    this.enforceCap();
     this.bumpVersion();
   }
+  /**
+   * U3 — enforce the `maxEvents` FIFO cap. When the store exceeds the
+   * cap, evict the oldest entries down to ~90% of the cap in ONE batch
+   * (amortized O(1) per event: one O(retained) rebuild per ~10%-of-cap
+   * pushes), then prune the SAME evicted entries from every run-tree
+   * node's `events` list — entry objects are shared references, so
+   * skipping the tree would hide the memory, not release it.
+   *
+   * `SequenceStore` is append-only by design (no removal API), so the
+   * batch rebuild (clear + re-push retained) is the supported eviction
+   * path; the per-step key + range indices rebuild correctly during
+   * re-push.
+   */
+  enforceCap() {
+    if (this.store.size <= this.maxEvents) return;
+    const all = this.store.getAll();
+    const evictBatch = Math.max(1, Math.floor(this.maxEvents / 10));
+    const retainCount = Math.max(1, this.maxEvents - evictBatch);
+    const dropCount = all.length - retainCount;
+    const retained = all.slice(dropCount);
+    this.store.clear();
+    for (const e of retained) this.store.push(e);
+    this.droppedEventCount += dropCount;
+    this.pruneNodeEvents(this.root, retained[0].seq);
+    if (this.debugEnabled() && !this.warnedEviction) {
+      this.warnedEviction = true;
+      console.warn(
+        `[lens] LensRecorder: maxEvents cap (${this.maxEvents}) reached \u2014 evicting oldest events (FIFO, ~10% per batch). Log-derived views now cover only the retained tail; evicted total in getDiagnostics().droppedEvents. Raise the cap via lensRecorder('Run', { maxEvents }) or pass Infinity to disable. (Warned once.)`
+      );
+    }
+  }
+  /** Drop entries with `seq < minSeq` from a node's `events` list (and
+   *  its descendants'). Per-node lists are seq-ordered, so this is a
+   *  prefix splice — in place, preserving the node object identity the
+   *  build stack may still hold. */
+  pruneNodeEvents(node, minSeq) {
+    if (node.events.length > 0 && node.events[0].seq < minSeq) {
+      let keepFrom = 0;
+      while (keepFrom < node.events.length && node.events[keepFrom].seq < minSeq) keepFrom++;
+      node.events.splice(0, keepFrom);
+    }
+    for (const child of node.children) this.pruneNodeEvents(child, minSeq);
+  }
   /** Notify all subscribers + bump version. Delegated to ChangeNotifier. */
   bumpVersion() {
     this.notifier.notify();
@@ -904,7 +966,13 @@ var LensRecorder = class {
   }
   /** Summary stats — computed lazily via `store.aggregate()`.
    *  Single-pass fold; types derived from the AgentfootprintEvent
-   *  discriminated union. */
+   *  discriminated union.
+   *
+   *  U3 caveat: once the `maxEvents` cap has evicted entries
+   *  (`getDiagnostics().droppedEvents > 0`), the folded counts/tokens
+   *  reflect only RETAINED events. `startedAt` / `durationMs` stay
+   *  anchored to the true first event of the run (tracked outside the
+   *  store), so the time axis never shifts. */
   selectSummary() {
     const init = {
       llmCallCount: 0,
@@ -944,7 +1012,7 @@ var LensRecorder = class {
       }
     }, init);
     const entries = this.store.getAll();
-    const startedAt = entries[0]?.wallClockMs ?? 0;
+    const startedAt = this.runStartMs ?? entries[0]?.wallClockMs ?? 0;
     const endedAt = entries[entries.length - 1]?.wallClockMs;
     return {
       startedAt,
@@ -2348,6 +2416,7 @@ export {
   ChangeNotifier,
   lensSnapshotRecorder,
   LensSnapshotRecorder,
+  DEFAULT_MAX_EVENTS,
   LensRecorder,
   lensRecorder,
   buildStepGraphFromSnapshot,
@@ -2385,4 +2454,4 @@ export {
   defaultSize,
   layoutLensGraph
 };
-//# sourceMappingURL=chunk-N3YJKWK5.js.map
+//# sourceMappingURL=chunk-BTVAAE66.js.map