agentfootprint-lens 0.19.0 → 0.21.0

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

@@ -3,7 +3,11 @@ import {
 } from "./chunk-KQOLJKKM.js";
 
 // src/core/LensRecorder.ts
+import { isDevMode } from "footprintjs";
 import { SequenceStore } from "footprintjs/trace";
+import {
+  ALL_EVENT_TYPES
+} from "agentfootprint";
 import { LiveStateRecorder, BoundaryRecorder } from "agentfootprint/observe";
 import {
   createTraceRuntimeOverlay
@@ -302,8 +306,10 @@ 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") {
+  constructor(rootLabel = "Run", options = {}) {
     /** Stable id for idempotent attach. */
     this.id = "lens";
     /** Composition: ordered + keyed event-log storage. */
@@ -374,6 +380,26 @@ var LensRecorder = class {
      * notifier. See `ChangeNotifier` JSDoc for adapter examples.
      */
     this.notifier = new ChangeNotifier();
+    /** Per-type count of events outside the agentfootprint registry.
+     *  Always maintained (debug only gates console output). */
+    this.unknownEventTypes = /* @__PURE__ */ new Map();
+    /** Count of `popIfKind` bracket mismatches. Always maintained. */
+    this.bracketMismatchCount = 0;
+    /** 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",
@@ -400,11 +426,50 @@ var LensRecorder = class {
     this.finalStatus = "running";
     this.runError = void 0;
     this.lastRunId = void 0;
+    this.unknownEventTypes.clear();
+    this.bracketMismatchCount = 0;
+    this.warnedUnknownTypes.clear();
+    this.droppedEventCount = 0;
+    this.warnedEviction = false;
     this.liveState.clear();
     this.boundary.clear();
     this.runtime.reset();
     this.bumpVersion();
   }
+  /**
+   * Health counters for the observed event stream (backlog item U4).
+   * Always maintained — no debug flag needed — so UIs and tests can
+   * assert stream health without scraping the console:
+   *
+   *   - `unknownEventTypes` — per-type counts of events whose `type` is
+   *     not in agentfootprint's event registry (e.g. a newer
+   *     agentfootprint emitting types this lens doesn't know, or a
+   *     custom dispatcher leaking foreign events). These events are
+   *     still attached to the current top node — counted, not dropped.
+   *   - `bracketMismatches` — close events (`llm_end`, `tool_end`,
+   *     `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.
+   *
+   * 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,
+      droppedEvents: this.droppedEventCount
+    };
+  }
+  /** Whether diagnostic warnings go to the console: explicit option
+   *  wins; otherwise follow footprintjs's global dev-mode flag
+   *  (evaluated per event so `enableDevMode()` mid-run takes effect). */
+  debugEnabled() {
+    return this.debug ?? isDevMode();
+  }
   /**
    * The StepGraph the UI renders — agentfootprint's ReAct projection
    * (actor-arrow steps with `iterationIndex` + `slotUpdated`, plus
@@ -555,13 +620,73 @@ var LensRecorder = class {
     };
     this.store.push(entry);
     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();
   }
+  /**
+   * U4 diagnostics — count (and, in debug, warn ONCE per type about)
+   * event types outside agentfootprint's registry. One Set lookup per
+   * event on the happy path.
+   */
+  noteUnknownType(type) {
+    if (KNOWN_EVENT_TYPES.has(type)) return;
+    this.unknownEventTypes.set(type, (this.unknownEventTypes.get(type) ?? 0) + 1);
+    if (this.debugEnabled() && !this.warnedUnknownTypes.has(type)) {
+      this.warnedUnknownTypes.add(type);
+      console.warn(
+        `[lens] LensRecorder: unknown event type '${type}' \u2014 not in agentfootprint's event registry. Attached to the current node without structural handling. (Warned once per type; counts in getDiagnostics().unknownEventTypes.)`
+      );
+    }
+  }
   /**
    * Kind-specific handling. Keeps the switch exhaustive over every v2
    * event type we structurally care about; the default branch is the
@@ -586,10 +711,14 @@ var LensRecorder = class {
     }
     if (type === "agentfootprint.composition.exit") {
       const p = event.payload;
-      this.popIfKind("composition", {
-        endOffsetMs: runOffsetMs,
-        status: p.status === "ok" ? "ok" : p.status === "budget_exhausted" ? "budget_exhausted" : "err"
-      });
+      this.popIfKind(
+        "composition",
+        {
+          endOffsetMs: runOffsetMs,
+          status: p.status === "ok" ? "ok" : p.status === "budget_exhausted" ? "budget_exhausted" : "err"
+        },
+        entry.runtimeStageId
+      );
       return;
     }
     if (type === "agentfootprint.composition.iteration_start") {
@@ -608,11 +737,15 @@ var LensRecorder = class {
     }
     if (type === "agentfootprint.composition.iteration_exit") {
       const p = event.payload;
-      this.popIfKind("iteration", {
-        endOffsetMs: runOffsetMs,
-        status: p.reason === "budget" ? "budget_exhausted" : "ok",
-        iterationExit: p.reason
-      });
+      this.popIfKind(
+        "iteration",
+        {
+          endOffsetMs: runOffsetMs,
+          status: p.reason === "budget" ? "budget_exhausted" : "ok",
+          iterationExit: p.reason
+        },
+        entry.runtimeStageId
+      );
       return;
     }
     if (type === "agentfootprint.agent.turn_start") {
@@ -629,7 +762,7 @@ var LensRecorder = class {
       return;
     }
     if (type === "agentfootprint.agent.turn_end") {
-      this.popIfKind("iteration", { endOffsetMs: runOffsetMs, status: "ok" });
+      this.popIfKind("iteration", { endOffsetMs: runOffsetMs, status: "ok" }, entry.runtimeStageId);
       return;
     }
     if (type === "agentfootprint.agent.iteration_start") {
@@ -647,7 +780,7 @@ var LensRecorder = class {
       return;
     }
     if (type === "agentfootprint.agent.iteration_end") {
-      this.popIfKind("iteration", { endOffsetMs: runOffsetMs, status: "ok" });
+      this.popIfKind("iteration", { endOffsetMs: runOffsetMs, status: "ok" }, entry.runtimeStageId);
       return;
     }
     if (type === "agentfootprint.stream.llm_start") {
@@ -674,16 +807,20 @@ var LensRecorder = class {
     }
     if (type === "agentfootprint.stream.llm_end") {
       const p = event.payload;
-      this.popIfKind("llm-call", {
-        endOffsetMs: runOffsetMs,
-        status: "ok",
-        llmEnd: {
-          content: p.content,
-          toolCallCount: p.toolCallCount,
-          usage: p.usage,
-          stopReason: p.stopReason
-        }
-      });
+      this.popIfKind(
+        "llm-call",
+        {
+          endOffsetMs: runOffsetMs,
+          status: "ok",
+          llmEnd: {
+            content: p.content,
+            toolCallCount: p.toolCallCount,
+            usage: p.usage,
+            stopReason: p.stopReason
+          }
+        },
+        entry.runtimeStageId
+      );
       return;
     }
     if (type === "agentfootprint.stream.tool_start") {
@@ -708,11 +845,15 @@ var LensRecorder = class {
     }
     if (type === "agentfootprint.stream.tool_end") {
       const p = event.payload;
-      this.popIfKind("tool-call", {
-        endOffsetMs: runOffsetMs,
-        status: p.error === true ? "err" : "ok",
-        toolEnd: { result: p.result, error: p.error ?? false }
-      });
+      this.popIfKind(
+        "tool-call",
+        {
+          endOffsetMs: runOffsetMs,
+          status: p.error === true ? "err" : "ok",
+          toolEnd: { result: p.result, error: p.error ?? false }
+        },
+        entry.runtimeStageId
+      );
       return;
     }
     if (type === "agentfootprint.pause.request") {
@@ -748,12 +889,23 @@ var LensRecorder = class {
   }
   /**
    * Pop the top node IF its kind matches, applying finalization fields.
-   * Mismatched kinds (indicating malformed event ordering) are logged
-   * but don't throw — Lens prefers partial correctness to crashes.
+   * Mismatched kinds (indicating malformed event ordering) are SKIPPED,
+   * never thrown — Lens prefers partial correctness to crashes. Every
+   * mismatch increments `getDiagnostics().bracketMismatches` (U4), and
+   * when debug is on (`LensRecorderOptions.debug` or footprintjs
+   * `isDevMode()`) each mismatch logs a `console.warn` with the
+   * expected vs found kind plus the closing event's `runtimeStageId`.
+   * Well-formed runs stay console-silent either way.
    */
-  popIfKind(kind, finalize) {
+  popIfKind(kind, finalize, runtimeStageId) {
     const top = this.top();
     if (top.kind !== kind) {
+      this.bracketMismatchCount += 1;
+      if (this.debugEnabled()) {
+        console.warn(
+          `[lens] LensRecorder: bracket mismatch \u2014 tried to close a '${kind}' node but the top of the stack is '${top.kind}'` + (runtimeStageId !== void 0 ? ` (runtimeStageId: ${runtimeStageId})` : "") + `. Close event skipped; the tree stays partially structured.`
+        );
+      }
       return;
     }
     top.endOffsetMs = finalize.endOffsetMs;
@@ -814,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,
@@ -854,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,
@@ -909,8 +1067,8 @@ function buildDetails(n) {
   }
   return void 0;
 }
-function lensRecorder(rootLabel) {
-  return new LensRecorder(rootLabel);
+function lensRecorder(rootLabel, options) {
+  return new LensRecorder(rootLabel, options);
 }
 
 // src/core/buildStepGraphFromSnapshot.ts
@@ -1618,7 +1776,7 @@ function makeEdge(kind, source, target, options = {}) {
 }
 
 // src/core/translate/helpers/mergeOutputs.ts
-import { isDevMode } from "footprintjs";
+import { isDevMode as isDevMode2 } from "footprintjs";
 function mergeOutputs(outputs, rootNodeId) {
   const nodes = [];
   const edges = [];
@@ -1626,7 +1784,7 @@ function mergeOutputs(outputs, rootNodeId) {
     for (const n of o.nodes) nodes.push(n);
     for (const e of o.edges) edges.push(e);
   }
-  if (isDevMode()) assertNoCollisions(nodes, edges);
+  if (isDevMode2()) assertNoCollisions(nodes, edges);
   return { nodes, edges, rootNodeId };
 }
 function assertNoCollisions(nodes, edges) {
@@ -2258,6 +2416,7 @@ export {
   ChangeNotifier,
   lensSnapshotRecorder,
   LensSnapshotRecorder,
+  DEFAULT_MAX_EVENTS,
   LensRecorder,
   lensRecorder,
   buildStepGraphFromSnapshot,
@@ -2295,4 +2454,4 @@ export {
   defaultSize,
   layoutLensGraph
 };
-//# sourceMappingURL=chunk-A2ELAEZX.js.map
+//# sourceMappingURL=chunk-BTVAAE66.js.map