agentfootprint-lens 0.19.0 → 0.20.0

package/dist/{chunk-A2ELAEZX.js → chunk-N3YJKWK5.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,9 @@ function relTime(runStartMs) {
 }
 
 // src/core/LensRecorder.ts
+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 +379,15 @@ 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();
+    this.debug = options.debug;
     this.root = {
       id: "run-root",
       kind: "run",
@@ -400,11 +414,44 @@ var LensRecorder = class {
     this.finalStatus = "running";
     this.runError = void 0;
     this.lastRunId = void 0;
+    this.unknownEventTypes.clear();
+    this.bracketMismatchCount = 0;
+    this.warnedUnknownTypes.clear();
     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.
+   *
+   * Both are `{}` / `0` on a well-formed run. Reset by `clear()`.
+   * Returns a fresh snapshot object on every call.
+   */
+  getDiagnostics() {
+    return {
+      unknownEventTypes: Object.fromEntries(this.unknownEventTypes),
+      bracketMismatches: this.bracketMismatchCount
+    };
+  }
+  /** 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,6 +602,7 @@ var LensRecorder = class {
     };
     this.store.push(entry);
     this.top().events.push(entry);
+    this.noteUnknownType(event.type);
     this.dispatch(event, runOffsetMs, entry);
     this.bumpVersion();
   }
@@ -562,6 +610,21 @@ var LensRecorder = class {
   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 +649,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 +675,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 +700,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 +718,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 +745,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 +783,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 +827,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;
@@ -909,8 +999,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 +1708,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 +1716,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) {
@@ -2295,4 +2385,4 @@ export {
   defaultSize,
   layoutLensGraph
 };
-//# sourceMappingURL=chunk-A2ELAEZX.js.map
+//# sourceMappingURL=chunk-N3YJKWK5.js.map