@mastra/observability 1.0.0 → 1.1.0-alpha.1

package/dist/index.cjs

@@ -5,8 +5,12 @@ var error = require('@mastra/core/error');
 var logger = require('@mastra/core/logger');
 var observability = require('@mastra/core/observability');
 var utils = require('@mastra/core/utils');
+var promises = require('fs/promises');
+var path = require('path');
+var url = require('url');
 var web = require('stream/web');
 
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 var __defProp = Object.defineProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -6065,6 +6069,822 @@ var TestExporter = class extends BaseExporter {
     this.logger.info("TestExporter shutdown");
   }
 };
+var __filename$1 = url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)));
+var __dirname$1 = path.dirname(__filename$1);
+var SNAPSHOTS_DIR = path.join(__dirname$1, "..", "__snapshots__");
+var JsonExporter = class extends BaseExporter {
+  name = "json-exporter";
+  /** All collected events */
+  #events = [];
+  /** Per-span state tracking */
+  #spanStates = /* @__PURE__ */ new Map();
+  /** Logs for debugging */
+  #logs = [];
+  /** Configuration */
+  #config;
+  constructor(config = {}) {
+    super(config);
+    this.#config = {
+      validateLifecycle: true,
+      storeLogs: true,
+      jsonIndent: 2,
+      ...config
+    };
+  }
+  /**
+   * Process incoming tracing events with lifecycle tracking
+   */
+  async _exportTracingEvent(event) {
+    const span = event.exportedSpan;
+    const spanId = span.id;
+    const logMessage = `[JsonExporter] ${event.type}: ${span.type} "${span.name}" (entity: ${span.entityName ?? span.entityId ?? "unknown"}, trace: ${span.traceId.slice(-8)}, span: ${spanId.slice(-8)})`;
+    if (this.#config.storeLogs) {
+      this.#logs.push(logMessage);
+    }
+    const state = this.#spanStates.get(spanId) || {
+      hasStart: false,
+      hasEnd: false,
+      hasUpdate: false,
+      events: []
+    };
+    if (this.#config.validateLifecycle) {
+      this.#validateLifecycle(event, state, spanId);
+    }
+    if (event.type === observability.TracingEventType.SPAN_STARTED) {
+      state.hasStart = true;
+    } else if (event.type === observability.TracingEventType.SPAN_ENDED) {
+      state.hasEnd = true;
+      if (span.isEvent) {
+        state.isEventSpan = true;
+      }
+    } else if (event.type === observability.TracingEventType.SPAN_UPDATED) {
+      state.hasUpdate = true;
+    }
+    state.events.push(event);
+    this.#spanStates.set(spanId, state);
+    this.#events.push(event);
+  }
+  /**
+   * Validate span lifecycle rules
+   */
+  #validateLifecycle(event, state, spanId) {
+    const span = event.exportedSpan;
+    if (event.type === observability.TracingEventType.SPAN_STARTED) {
+      if (state.hasStart) {
+        this.logger.warn(`Span ${spanId} (${span.type} "${span.name}") started twice`);
+      }
+    } else if (event.type === observability.TracingEventType.SPAN_ENDED) {
+      if (span.isEvent) {
+        if (state.hasStart) {
+          this.logger.warn(`Event span ${spanId} (${span.type} "${span.name}") incorrectly received SPAN_STARTED`);
+        }
+        if (state.hasUpdate) {
+          this.logger.warn(`Event span ${spanId} (${span.type} "${span.name}") incorrectly received SPAN_UPDATED`);
+        }
+      } else {
+        if (!state.hasStart) {
+          this.logger.warn(`Normal span ${spanId} (${span.type} "${span.name}") ended without starting`);
+        }
+      }
+    }
+  }
+  // ============================================================================
+  // Query Methods
+  // ============================================================================
+  /**
+   * Get all collected events
+   */
+  get events() {
+    return [...this.#events];
+  }
+  /**
+   * Get completed spans by SpanType (e.g., 'agent_run', 'tool_call')
+   *
+   * @param type - The SpanType to filter by
+   * @returns Array of completed exported spans of the specified type
+   */
+  getSpansByType(type) {
+    return Array.from(this.#spanStates.values()).filter((state) => {
+      if (!state.hasEnd) return false;
+      const endEvent = state.events.find((e) => e.type === observability.TracingEventType.SPAN_ENDED);
+      return endEvent?.exportedSpan.type === type;
+    }).map((state) => {
+      const endEvent = state.events.find((e) => e.type === observability.TracingEventType.SPAN_ENDED);
+      return endEvent?.exportedSpan;
+    }).filter((span) => span !== void 0);
+  }
+  /**
+   * Get events by TracingEventType (SPAN_STARTED, SPAN_UPDATED, SPAN_ENDED)
+   *
+   * @param type - The TracingEventType to filter by
+   * @returns Array of events of the specified type
+   */
+  getByEventType(type) {
+    return this.#events.filter((e) => e.type === type);
+  }
+  /**
+   * Get all events and spans for a specific trace
+   *
+   * @param traceId - The trace ID to filter by
+   * @returns Object containing events and final spans for the trace
+   */
+  getByTraceId(traceId) {
+    const events = this.#events.filter((e) => e.exportedSpan.traceId === traceId);
+    const spans = this.#getUniqueSpansFromEvents(events);
+    return { events, spans };
+  }
+  /**
+   * Get all events for a specific span
+   *
+   * @param spanId - The span ID to filter by
+   * @returns Object containing events and final span state
+   */
+  getBySpanId(spanId) {
+    const state = this.#spanStates.get(spanId);
+    if (!state) {
+      return { events: [], span: void 0, state: void 0 };
+    }
+    const endEvent = state.events.find((e) => e.type === observability.TracingEventType.SPAN_ENDED);
+    const span = endEvent?.exportedSpan ?? state.events[state.events.length - 1]?.exportedSpan;
+    return { events: state.events, span, state };
+  }
+  /**
+   * Get all unique spans (returns the final state of each span)
+   */
+  getAllSpans() {
+    return Array.from(this.#spanStates.values()).map((state) => {
+      const endEvent = state.events.find((e) => e.type === observability.TracingEventType.SPAN_ENDED);
+      return endEvent?.exportedSpan ?? state.events[state.events.length - 1]?.exportedSpan;
+    }).filter((span) => span !== void 0);
+  }
+  /**
+   * Get only completed spans (those that have received SPAN_ENDED)
+   */
+  getCompletedSpans() {
+    return Array.from(this.#spanStates.values()).filter((state) => state.hasEnd).map((state) => {
+      const endEvent = state.events.find((e) => e.type === observability.TracingEventType.SPAN_ENDED);
+      return endEvent.exportedSpan;
+    });
+  }
+  /**
+   * Get root spans only (spans with no parent)
+   */
+  getRootSpans() {
+    return this.getAllSpans().filter((span) => span.isRootSpan);
+  }
+  /**
+   * Get incomplete spans (started but not yet ended)
+   */
+  getIncompleteSpans() {
+    return Array.from(this.#spanStates.entries()).filter(([_, state]) => !state.hasEnd).map(([spanId, state]) => ({
+      spanId,
+      span: state.events[0]?.exportedSpan,
+      state: {
+        hasStart: state.hasStart,
+        hasUpdate: state.hasUpdate,
+        hasEnd: state.hasEnd
+      }
+    }));
+  }
+  /**
+   * Get unique trace IDs from all collected spans
+   */
+  getTraceIds() {
+    const traceIds = /* @__PURE__ */ new Set();
+    for (const event of this.#events) {
+      traceIds.add(event.exportedSpan.traceId);
+    }
+    return Array.from(traceIds);
+  }
+  // ============================================================================
+  // Statistics
+  // ============================================================================
+  /**
+   * Get comprehensive statistics about collected spans
+   */
+  getStatistics() {
+    const bySpanType = {};
+    let completedSpans = 0;
+    let incompleteSpans = 0;
+    for (const state of this.#spanStates.values()) {
+      if (state.hasEnd) {
+        completedSpans++;
+        const endEvent = state.events.find((e) => e.type === observability.TracingEventType.SPAN_ENDED);
+        const spanType = endEvent?.exportedSpan.type;
+        if (spanType) {
+          bySpanType[spanType] = (bySpanType[spanType] || 0) + 1;
+        }
+      } else {
+        incompleteSpans++;
+      }
+    }
+    return {
+      totalEvents: this.#events.length,
+      totalSpans: this.#spanStates.size,
+      totalTraces: this.getTraceIds().length,
+      completedSpans,
+      incompleteSpans,
+      byEventType: {
+        started: this.#events.filter((e) => e.type === observability.TracingEventType.SPAN_STARTED).length,
+        updated: this.#events.filter((e) => e.type === observability.TracingEventType.SPAN_UPDATED).length,
+        ended: this.#events.filter((e) => e.type === observability.TracingEventType.SPAN_ENDED).length
+      },
+      bySpanType
+    };
+  }
+  // ============================================================================
+  // JSON Output
+  // ============================================================================
+  /**
+   * Serialize all collected data to JSON string
+   *
+   * @param options - Serialization options
+   * @returns JSON string of all collected data
+   */
+  toJSON(options) {
+    const indent = options?.indent ?? this.#config.jsonIndent;
+    const includeEvents = options?.includeEvents ?? true;
+    const includeStats = options?.includeStats ?? true;
+    const data = {
+      spans: this.getAllSpans()
+    };
+    if (includeEvents) {
+      data.events = this.#events;
+    }
+    if (includeStats) {
+      data.statistics = this.getStatistics();
+    }
+    return JSON.stringify(data, this.#jsonReplacer, indent);
+  }
+  /**
+   * Build a tree structure from spans, nesting children under their parents
+   *
+   * @returns Array of root span tree nodes (spans with no parent)
+   */
+  buildSpanTree() {
+    const spans = this.getAllSpans();
+    const nodeMap = /* @__PURE__ */ new Map();
+    const roots = [];
+    for (const span of spans) {
+      nodeMap.set(span.id, { span, children: [] });
+    }
+    for (const span of spans) {
+      const node = nodeMap.get(span.id);
+      if (span.parentSpanId && nodeMap.has(span.parentSpanId)) {
+        nodeMap.get(span.parentSpanId).children.push(node);
+      } else {
+        roots.push(node);
+      }
+    }
+    const sortChildren = (node) => {
+      node.children.sort((a, b) => new Date(a.span.startTime).getTime() - new Date(b.span.startTime).getTime());
+      node.children.forEach(sortChildren);
+    };
+    roots.forEach(sortChildren);
+    return roots;
+  }
+  /**
+   * Serialize spans as a tree structure to JSON string
+   *
+   * @param options - Serialization options
+   * @returns JSON string with spans nested in tree format
+   */
+  toTreeJSON(options) {
+    const indent = options?.indent ?? this.#config.jsonIndent;
+    const includeStats = options?.includeStats ?? true;
+    const data = {
+      tree: this.buildSpanTree()
+    };
+    if (includeStats) {
+      data.statistics = this.getStatistics();
+    }
+    return JSON.stringify(data, this.#jsonReplacer, indent);
+  }
+  /**
+   * Build a normalized tree structure suitable for snapshot testing.
+   *
+   * Normalizations applied:
+   * - Span IDs replaced with stable placeholders (<span-1>, <span-2>, etc.)
+   * - Trace IDs replaced with stable placeholders (<trace-1>, <trace-2>, etc.)
+   * - parentSpanId replaced with normalized parent ID
+   * - Timestamps replaced with durationMs (or null if not ended)
+   * - Empty children arrays are omitted
+   *
+   * @returns Array of normalized root tree nodes
+   */
+  buildNormalizedTree() {
+    const tree = this.buildSpanTree();
+    const spanIdMap = /* @__PURE__ */ new Map();
+    const traceIdMap = /* @__PURE__ */ new Map();
+    const uuidMapsByKey = /* @__PURE__ */ new Map();
+    const uuidCountersByKey = /* @__PURE__ */ new Map();
+    let spanIdCounter = 1;
+    let traceIdCounter = 1;
+    const uuidRegex2 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+    const hexId32Regex = /^[0-9a-f]{32}$/i;
+    const prefixedUuidRegex = /^([a-z_]+)_([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/i;
+    const embeddedPrefixedUuidRegex = /([a-z_]+)_([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})/gi;
+    const normalizeUuid = (uuid, key) => {
+      if (!uuidMapsByKey.has(key)) {
+        uuidMapsByKey.set(key, /* @__PURE__ */ new Map());
+        uuidCountersByKey.set(key, 1);
+      }
+      const keyMap = uuidMapsByKey.get(key);
+      if (!keyMap.has(uuid)) {
+        const counter = uuidCountersByKey.get(key);
+        keyMap.set(uuid, `<${key}-${counter}>`);
+        uuidCountersByKey.set(key, counter + 1);
+      }
+      return keyMap.get(uuid);
+    };
+    const normalizeValue = (value, key) => {
+      if (value instanceof Date) {
+        return "<date>";
+      }
+      if (typeof value === "string") {
+        if (key === "traceId" && (uuidRegex2.test(value) || hexId32Regex.test(value))) {
+          if (!traceIdMap.has(value)) {
+            traceIdMap.set(value, `<trace-${traceIdCounter++}>`);
+          }
+          return traceIdMap.get(value);
+        }
+        if (uuidRegex2.test(value)) {
+          return normalizeUuid(value, key ?? "uuid");
+        }
+        const prefixMatch = prefixedUuidRegex.exec(value);
+        if (prefixMatch && prefixMatch[1] && prefixMatch[2]) {
+          const prefix = prefixMatch[1];
+          const uuid = prefixMatch[2];
+          return `${prefix}_${normalizeUuid(uuid, prefix)}`;
+        }
+        if (embeddedPrefixedUuidRegex.test(value)) {
+          embeddedPrefixedUuidRegex.lastIndex = 0;
+          return value.replace(embeddedPrefixedUuidRegex, (_match, prefix, uuid) => {
+            return `${prefix}_${normalizeUuid(uuid, prefix)}`;
+          });
+        }
+      }
+      if (Array.isArray(value)) {
+        return value.map((v) => normalizeValue(v, key));
+      }
+      if (value && typeof value === "object") {
+        const normalized = {};
+        for (const [k, v] of Object.entries(value)) {
+          normalized[k] = normalizeValue(v, k);
+        }
+        return normalized;
+      }
+      return value;
+    };
+    const assignIds = (nodes) => {
+      for (const node of nodes) {
+        spanIdMap.set(node.span.id, `<span-${spanIdCounter++}>`);
+        if (!traceIdMap.has(node.span.traceId)) {
+          traceIdMap.set(node.span.traceId, `<trace-${traceIdCounter++}>`);
+        }
+        assignIds(node.children);
+      }
+    };
+    assignIds(tree);
+    const normalizeNode = (node) => {
+      const span = node.span;
+      const completed = span.endTime !== void 0 && span.endTime !== null;
+      const normalizedSpan = {
+        id: spanIdMap.get(span.id),
+        traceId: traceIdMap.get(span.traceId),
+        name: normalizeValue(span.name, "name"),
+        type: span.type,
+        completed,
+        isEvent: span.isEvent,
+        isRootSpan: span.isRootSpan
+      };
+      if (span.parentSpanId && spanIdMap.has(span.parentSpanId)) {
+        normalizedSpan.parentId = spanIdMap.get(span.parentSpanId);
+      }
+      if (span.entityType) {
+        normalizedSpan.entityType = span.entityType;
+      }
+      if (span.entityId) {
+        normalizedSpan.entityId = normalizeValue(span.entityId, "entityId");
+      }
+      if (span.attributes && Object.keys(span.attributes).length > 0) {
+        normalizedSpan.attributes = normalizeValue(span.attributes);
+      }
+      if (span.metadata && Object.keys(span.metadata).length > 0) {
+        normalizedSpan.metadata = normalizeValue(span.metadata);
+      }
+      if (span.input !== void 0) {
+        normalizedSpan.input = normalizeValue(span.input);
+      }
+      if (span.output !== void 0) {
+        normalizedSpan.output = normalizeValue(span.output);
+      }
+      if (span.errorInfo) {
+        normalizedSpan.errorInfo = span.errorInfo;
+      }
+      if (span.tags && span.tags.length > 0) {
+        normalizedSpan.tags = span.tags;
+      }
+      const result = { span: normalizedSpan };
+      if (node.children.length > 0) {
+        result.children = node.children.map(normalizeNode);
+      }
+      return result;
+    };
+    return tree.map(normalizeNode);
+  }
+  /**
+   * Generate an ASCII tree structure graph for debugging.
+   * Shows span type and name in a hierarchical format.
+   *
+   * @param nodes - Normalized tree nodes (defaults to current normalized tree)
+   * @returns Array of strings representing the tree structure
+   *
+   * @example
+   * ```
+   * agent_run: "agent run: 'test-agent'"
+   * ├── processor_run: "input processor: validator"
+   * │   └── agent_run: "agent run: 'validator-agent'"
+   * └── model_generation: "llm: 'mock-model-id'"
+   * ```
+   */
+  generateStructureGraph(nodes) {
+    const tree = nodes ?? this.buildNormalizedTree();
+    const lines = [];
+    const buildLines = (node, prefix, isLast, isRoot) => {
+      const connector = isRoot ? "" : isLast ? "\u2514\u2500\u2500 " : "\u251C\u2500\u2500 ";
+      const line = `${prefix}${connector}${node.span.type}: "${node.span.name}"`;
+      lines.push(line);
+      const children = node.children ?? [];
+      const childPrefix = isRoot ? "" : prefix + (isLast ? "    " : "\u2502   ");
+      children.forEach((child, index) => {
+        const childIsLast = index === children.length - 1;
+        buildLines(child, childPrefix, childIsLast, false);
+      });
+    };
+    tree.forEach((rootNode, index) => {
+      if (index > 0) {
+        lines.push("");
+      }
+      buildLines(rootNode, "", true, true);
+    });
+    return lines;
+  }
+  /**
+   * Serialize spans as a normalized tree structure for snapshot testing.
+   * Includes a __structure__ field with an ASCII tree graph for readability.
+   *
+   * @param options - Serialization options
+   * @returns JSON string with normalized spans in tree format
+   */
+  toNormalizedTreeJSON(options) {
+    const indent = options?.indent ?? this.#config.jsonIndent;
+    const includeStructure = options?.includeStructure ?? true;
+    const normalizedTree = this.buildNormalizedTree();
+    if (includeStructure) {
+      const structureGraph = this.generateStructureGraph(normalizedTree);
+      const data = {
+        __structure__: structureGraph,
+        spans: normalizedTree
+      };
+      return JSON.stringify(data, null, indent);
+    }
+    return JSON.stringify(normalizedTree, null, indent);
+  }
+  /**
+   * Write collected data to a JSON file
+   *
+   * @param filePath - Path to write the JSON file
+   * @param options - Serialization options
+   */
+  async writeToFile(filePath, options) {
+    const format = options?.format ?? "flat";
+    let json;
+    if (format === "normalized") {
+      json = this.toNormalizedTreeJSON({ indent: options?.indent });
+    } else if (format === "tree") {
+      json = this.toTreeJSON({ indent: options?.indent, includeStats: options?.includeStats });
+    } else {
+      json = this.toJSON(options);
+    }
+    await promises.writeFile(filePath, json, "utf-8");
+    this.logger.info(`JsonExporter: wrote ${this.#events.length} events to ${filePath}`);
+  }
+  /**
+   * Assert that the current normalized tree matches a snapshot file.
+   * Throws an error with a diff if they don't match.
+   *
+   * The snapshot format includes:
+   * - `__structure__`: ASCII tree graph (compared first for quick validation)
+   * - `spans`: The normalized span tree (detailed comparison)
+   *
+   * Supports special markers in the snapshot:
+   * - `{"__or__": ["value1", "value2"]}` - matches if actual equals any listed value
+   * - `{"__any__": "string"}` - matches any string value
+   * - `{"__any__": "number"}` - matches any number value
+   * - `{"__any__": "boolean"}` - matches any boolean value
+   * - `{"__any__": "object"}` - matches any object value
+   * - `{"__any__": "array"}` - matches any array value
+   * - `{"__any__": true}` - matches any non-null/undefined value
+   *
+   * Environment variables:
+   * Use `{ updateSnapshot: true }` option to update the snapshot instead of comparing
+   *
+   * @param snapshotName - Name of the snapshot file (resolved relative to __snapshots__ directory)
+   * @param options - Options for snapshot comparison
+   * @param options.updateSnapshot - If true, update the snapshot file instead of comparing
+   * @throws Error if the snapshot doesn't match (and updateSnapshot is false)
+   */
+  async assertMatchesSnapshot(snapshotName, options) {
+    const snapshotPath = path.join(SNAPSHOTS_DIR, snapshotName);
+    const normalizedTree = this.buildNormalizedTree();
+    const structureGraph = this.generateStructureGraph(normalizedTree);
+    const currentData = {
+      __structure__: structureGraph,
+      spans: normalizedTree
+    };
+    const currentJson = JSON.stringify(currentData, null, this.#config.jsonIndent);
+    const shouldUpdate = options?.updateSnapshot;
+    if (shouldUpdate) {
+      await promises.writeFile(snapshotPath, currentJson, "utf-8");
+      this.logger.info(`JsonExporter: updated snapshot ${snapshotPath}`);
+      return;
+    }
+    let snapshotData;
+    try {
+      const snapshotContent = await promises.readFile(snapshotPath, "utf-8");
+      snapshotData = JSON.parse(snapshotContent);
+    } catch {
+      throw new Error(`Snapshot file not found: ${snapshotPath}
+Run with { updateSnapshot: true } to create it.`);
+    }
+    let expectedSpans;
+    let expectedStructure;
+    if (Array.isArray(snapshotData)) {
+      expectedSpans = snapshotData;
+    } else if (snapshotData && typeof snapshotData === "object" && "spans" in snapshotData) {
+      expectedSpans = snapshotData.spans;
+      expectedStructure = snapshotData.__structure__;
+    } else {
+      throw new Error(
+        `Invalid snapshot format in ${snapshotPath}.
+Expected an array or object with 'spans' property.`
+      );
+    }
+    if (expectedStructure) {
+      const structureMismatches = this.#compareStructure(structureGraph, expectedStructure);
+      if (structureMismatches.length > 0) {
+        throw new Error(
+          `Structure mismatch in snapshot:
+
+Expected:
+${expectedStructure.join("\n")}
+
+Actual:
+${structureGraph.join("\n")}
+
+Differences:
+${structureMismatches.join("\n")}
+
+Snapshot: ${snapshotPath}
+Run with { updateSnapshot: true } to update.`
+        );
+      }
+    }
+    const mismatches = [];
+    this.#deepCompareWithMarkers(normalizedTree, expectedSpans, "$.spans", mismatches);
+    if (mismatches.length > 0) {
+      const mismatchDetails = mismatches.map(
+        (m, i) => `${i + 1}. ${m.path}
+   Expected: ${JSON.stringify(m.expected)}
+   Actual:   ${JSON.stringify(m.actual)}`
+      ).join("\n\n");
+      throw new Error(
+        `Snapshot has ${mismatches.length} mismatch${mismatches.length > 1 ? "es" : ""}:
+
+${mismatchDetails}
+
+Snapshot: ${snapshotPath}
+Run with { updateSnapshot: true } to update.`
+      );
+    }
+  }
+  /**
+   * Compare two structure graphs and return differences
+   */
+  #compareStructure(actual, expected) {
+    const diffs = [];
+    const maxLen = Math.max(actual.length, expected.length);
+    for (let i = 0; i < maxLen; i++) {
+      const actualLine = actual[i];
+      const expectedLine = expected[i];
+      if (actualLine !== expectedLine) {
+        if (actualLine === void 0) {
+          diffs.push(`Line ${i + 1}: Missing in actual`);
+          diffs.push(`  Expected: ${expectedLine}`);
+        } else if (expectedLine === void 0) {
+          diffs.push(`Line ${i + 1}: Extra in actual`);
+          diffs.push(`  Actual: ${actualLine}`);
+        } else {
+          diffs.push(`Line ${i + 1}:`);
+          diffs.push(`  Expected: ${expectedLine}`);
+          diffs.push(`  Actual:   ${actualLine}`);
+        }
+      }
+    }
+    return diffs;
+  }
+  /**
+   * Deep compare two values, supporting special markers like __or__ and __any__.
+   * Collects all mismatches into the provided array.
+   */
+  #deepCompareWithMarkers(actual, expected, path, mismatches) {
+    if (this.#isOrMarker(expected)) {
+      const allowedValues = expected.__or__;
+      const matches = allowedValues.some((allowed) => {
+        const tempMismatches = [];
+        this.#deepCompareWithMarkers(actual, allowed, path, tempMismatches);
+        return tempMismatches.length === 0;
+      });
+      if (!matches) {
+        mismatches.push({ path, expected: { __or__: allowedValues }, actual });
+      }
+      return;
+    }
+    if (this.#isAnyMarker(expected)) {
+      const typeConstraint = expected.__any__;
+      if (actual === null || actual === void 0) {
+        mismatches.push({ path, expected: { __any__: typeConstraint }, actual });
+        return;
+      }
+      if (typeConstraint === true) {
+        return;
+      }
+      const actualType = Array.isArray(actual) ? "array" : typeof actual;
+      if (actualType !== typeConstraint) {
+        mismatches.push({
+          path,
+          expected: { __any__: typeConstraint },
+          actual: `(${actualType}) ${JSON.stringify(actual).slice(0, 50)}...`
+        });
+      }
+      return;
+    }
+    if (Array.isArray(expected)) {
+      if (!Array.isArray(actual)) {
+        mismatches.push({ path, expected, actual });
+        return;
+      }
+      if (actual.length !== expected.length) {
+        mismatches.push({ path: `${path}.length`, expected: expected.length, actual: actual.length });
+        return;
+      }
+      for (let i = 0; i < expected.length; i++) {
+        this.#deepCompareWithMarkers(actual[i], expected[i], `${path}[${i}]`, mismatches);
+      }
+      return;
+    }
+    if (expected !== null && typeof expected === "object") {
+      if (actual === null || typeof actual !== "object" || Array.isArray(actual)) {
+        mismatches.push({ path, expected, actual });
+        return;
+      }
+      const expectedObj = expected;
+      const actualObj = actual;
+      for (const key of Object.keys(expectedObj)) {
+        if (this.#isMetadataKey(key)) {
+          continue;
+        }
+        if (!(key in actualObj)) {
+          if (expectedObj[key] !== void 0) {
+            mismatches.push({ path: `${path}.${key}`, expected: expectedObj[key], actual: void 0 });
+          }
+          continue;
+        }
+        this.#deepCompareWithMarkers(actualObj[key], expectedObj[key], `${path}.${key}`, mismatches);
+      }
+      for (const key of Object.keys(actualObj)) {
+        if (this.#isMetadataKey(key)) {
+          continue;
+        }
+        if (!(key in expectedObj)) {
+          if (actualObj[key] !== void 0) {
+            mismatches.push({ path: `${path}.${key}`, expected: void 0, actual: actualObj[key] });
+          }
+        }
+      }
+      return;
+    }
+    if (actual !== expected) {
+      mismatches.push({ path, expected, actual });
+    }
+  }
+  /**
+   * Check if a value is an __or__ marker object
+   */
+  #isOrMarker(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value) && "__or__" in value && Array.isArray(value.__or__);
+  }
+  /**
+   * Check if a value is an __any__ marker object
+   */
+  #isAnyMarker(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+      return false;
+    }
+    if (!("__any__" in value)) {
+      return false;
+    }
+    const constraint = value.__any__;
+    return constraint === true || ["string", "number", "boolean", "object", "array"].includes(constraint);
+  }
+  /**
+   * Check if a key should be skipped during comparison (metadata keys like __structure__)
+   */
+  #isMetadataKey(key) {
+    return key.startsWith("__") && key.endsWith("__");
+  }
+  /**
+   * Custom JSON replacer to handle Date objects and other special types
+   */
+  #jsonReplacer = (_key, value) => {
+    if (value instanceof Date) {
+      return value.toISOString();
+    }
+    return value;
+  };
+  // ============================================================================
+  // Debugging Helpers
+  // ============================================================================
+  /**
+   * Get all stored logs
+   */
+  getLogs() {
+    return [...this.#logs];
+  }
+  /**
+   * Dump logs to console for debugging (uses console.error for visibility in test output)
+   */
+  dumpLogs() {
+    console.error("\n=== JsonExporter Logs ===");
+    this.#logs.forEach((log) => console.error(log));
+    console.error("=== End Logs ===\n");
+  }
+  /**
+   * Validate final state - useful for test assertions
+   *
+   * @returns Object with validation results
+   */
+  validateFinalState() {
+    const traceIds = this.getTraceIds();
+    const incompleteSpans = this.getIncompleteSpans();
+    const singleTraceId = traceIds.length === 1;
+    const allSpansComplete = incompleteSpans.length === 0;
+    return {
+      valid: singleTraceId && allSpansComplete,
+      singleTraceId,
+      allSpansComplete,
+      traceIds,
+      incompleteSpans
+    };
+  }
+  // ============================================================================
+  // Reset & Lifecycle
+  // ============================================================================
+  /**
+   * Clear all collected events and state
+   */
+  clearEvents() {
+    this.#events = [];
+    this.#spanStates.clear();
+    this.#logs = [];
+  }
+  /**
+   * Alias for clearEvents (compatibility with TestExporter)
+   */
+  reset() {
+    this.clearEvents();
+  }
+  async shutdown() {
+    this.logger.info("JsonExporter shutdown");
+  }
+  // ============================================================================
+  // Private Helpers
+  // ============================================================================
+  /**
+   * Extract unique spans from a list of events
+   */
+  #getUniqueSpansFromEvents(events) {
+    const spanMap = /* @__PURE__ */ new Map();
+    for (const event of events) {
+      const span = event.exportedSpan;
+      if (event.type === observability.TracingEventType.SPAN_ENDED || !spanMap.has(span.id)) {
+        spanMap.set(span.id, span);
+      }
+    }
+    return Array.from(spanMap.values());
+  }
+};
 
 // src/usage.ts
 function extractUsageMetrics(usage, providerMetadata) {
@@ -6121,14 +6941,11 @@ var ModelSpanTracker = class {
   #modelSpan;
   #currentStepSpan;
   #currentChunkSpan;
+  #currentChunkType;
   #accumulator = {};
   #stepIndex = 0;
   #chunkSequence = 0;
   #completionStartTime;
-  /** Tracks tool output accumulators by toolCallId for consolidating sub-agent streams */
-  #toolOutputAccumulators = /* @__PURE__ */ new Map();
-  /** Tracks toolCallIds that had streaming output (to skip redundant tool-result spans) */
-  #streamedToolCallIds = /* @__PURE__ */ new Set();
   constructor(modelSpan) {
     this.#modelSpan = modelSpan;
   }
@@ -6215,6 +7032,7 @@ var ModelSpanTracker = class {
    * End the current Model execution step with token usage, finish reason, output, and metadata
    */
   #endStepSpan(payload) {
+    this.#endChunkSpan();
     if (!this.#currentStepSpan) return;
     const output = payload.output;
     const { usage: rawUsage, ...otherOutput } = output;
@@ -6222,8 +7040,10 @@ var ModelSpanTracker = class {
     const metadata = payload.metadata;
     const usage = extractUsageMetrics(rawUsage, metadata?.providerMetadata);
     const cleanMetadata = metadata ? { ...metadata } : void 0;
-    if (cleanMetadata?.request) {
-      delete cleanMetadata.request;
+    if (cleanMetadata) {
+      for (const key of ["request", "id", "timestamp", "modelId", "modelVersion", "modelProvider"]) {
+        delete cleanMetadata[key];
+      }
     }
     this.#currentStepSpan.end({
       output: otherOutput,
@@ -6244,6 +7064,7 @@ var ModelSpanTracker = class {
    * Create a new chunk span (for multi-part chunks like text-start/delta/end)
    */
   #startChunkSpan(chunkType, initialData) {
+    this.#endChunkSpan();
     if (!this.#currentStepSpan) {
       this.startStep();
     }
@@ -6255,6 +7076,7 @@ var ModelSpanTracker = class {
         sequenceNumber: this.#chunkSequence
       }
     });
+    this.#currentChunkType = chunkType;
     this.#accumulator = initialData || {};
   }
   /**
@@ -6277,13 +7099,14 @@ var ModelSpanTracker = class {
       output: output !== void 0 ? output : this.#accumulator
     });
     this.#currentChunkSpan = void 0;
+    this.#currentChunkType = void 0;
     this.#accumulator = {};
     this.#chunkSequence++;
   }
   /**
    * Create an event span (for single chunks like tool-call)
    */
-  #createEventSpan(chunkType, output) {
+  #createEventSpan(chunkType, output, options) {
     if (!this.#currentStepSpan) {
       this.startStep();
     }
@@ -6292,8 +7115,10 @@ var ModelSpanTracker = class {
       type: observability.SpanType.MODEL_CHUNK,
       attributes: {
         chunkType,
-        sequenceNumber: this.#chunkSequence
+        sequenceNumber: this.#chunkSequence,
+        ...options?.attributes
       },
+      metadata: options?.metadata,
       output
     });
     if (span) {
@@ -6321,6 +7146,9 @@ var ModelSpanTracker = class {
         this.#startChunkSpan("text");
         break;
       case "text-delta":
+        if (this.#currentChunkType !== "text") {
+          this.#startChunkSpan("text");
+        }
         this.#appendToAccumulator("text", chunk.payload.text);
         break;
       case "text-end": {
@@ -6338,6 +7166,9 @@ var ModelSpanTracker = class {
         this.#startChunkSpan("reasoning");
         break;
       case "reasoning-delta":
+        if (this.#currentChunkType !== "reasoning") {
+          this.#startChunkSpan("reasoning");
+        }
         this.#appendToAccumulator("text", chunk.payload.text);
         break;
       case "reasoning-end": {
@@ -6384,7 +7215,7 @@ var ModelSpanTracker = class {
   #handleObjectChunk(chunk) {
     switch (chunk.type) {
       case "object":
-        if (!this.#hasActiveChunkSpan()) {
+        if (this.#currentChunkType !== "object") {
           this.#startChunkSpan("object");
         }
         break;
@@ -6394,75 +7225,27 @@ var ModelSpanTracker = class {
     }
   }
   /**
-   * Handle tool-output chunks from sub-agents.
-   * Consolidates streaming text/reasoning deltas into a single span per tool call.
+   * Handle tool-call-approval chunks.
+   * Creates a span for approval requests so they can be seen in traces for debugging.
    */
-  #handleToolOutputChunk(chunk) {
-    if (chunk.type !== "tool-output") return;
+  #handleToolApprovalChunk(chunk) {
+    if (chunk.type !== "tool-call-approval") return;
     const payload = chunk.payload;
-    const { output, toolCallId, toolName } = payload;
-    let acc = this.#toolOutputAccumulators.get(toolCallId);
-    if (!acc) {
-      if (!this.#currentStepSpan) {
-        this.startStep();
-      }
-      acc = {
-        toolName: toolName || "unknown",
-        toolCallId,
-        text: "",
-        reasoning: "",
-        sequenceNumber: this.#chunkSequence++,
-        // Name the span 'tool-result' for consistency (tool-call → tool-result)
-        span: this.#currentStepSpan?.createChildSpan({
-          name: `chunk: 'tool-result'`,
-          type: observability.SpanType.MODEL_CHUNK,
-          attributes: {
-            chunkType: "tool-result",
-            sequenceNumber: this.#chunkSequence - 1
-          }
-        })
-      };
-      this.#toolOutputAccumulators.set(toolCallId, acc);
-    }
-    if (output && typeof output === "object" && "type" in output) {
-      const innerType = output.type;
-      switch (innerType) {
-        case "text-delta":
-          if (output.payload?.text) {
-            acc.text += output.payload.text;
-          }
-          break;
-        case "reasoning-delta":
-          if (output.payload?.text) {
-            acc.reasoning += output.payload.text;
-          }
-          break;
-        case "finish":
-        case "workflow-finish":
-          this.#endToolOutputSpan(toolCallId);
-          break;
-      }
-    }
-  }
-  /**
-   * End a tool output span and clean up the accumulator
-   */
-  #endToolOutputSpan(toolCallId) {
-    const acc = this.#toolOutputAccumulators.get(toolCallId);
-    if (!acc) return;
-    const output = {
-      toolCallId: acc.toolCallId,
-      toolName: acc.toolName
-    };
-    if (acc.text) {
-      output.text = acc.text;
+    if (!this.#currentStepSpan) {
+      this.startStep();
     }
-    if (acc.reasoning) {
-      output.reasoning = acc.reasoning;
+    const span = this.#currentStepSpan?.createEventSpan({
+      name: `chunk: 'tool-call-approval'`,
+      type: observability.SpanType.MODEL_CHUNK,
+      attributes: {
+        chunkType: "tool-call-approval",
+        sequenceNumber: this.#chunkSequence
+      },
+      output: payload
+    });
+    if (span) {
+      this.#chunkSequence++;
     }
-    acc.span?.end({ output });
-    this.#toolOutputAccumulators.delete(toolCallId);
-    this.#streamedToolCallIds.add(toolCallId);
   }
   /**
    * Wraps a stream with model tracing transform to track MODEL_STEP and MODEL_CHUNK spans.
@@ -6537,8 +7320,6 @@ var ModelSpanTracker = class {
             // Internal watch event
             case "tool-error":
             // Tool error handling
-            case "tool-call-approval":
-            // Approval request (not content)
             case "tool-call-suspended":
             // Suspension (not content)
             case "reasoning-signature":
@@ -6547,17 +7328,28 @@ var ModelSpanTracker = class {
             // Redacted content metadata
             case "step-output":
               break;
+            case "tool-call-approval":
+              this.#handleToolApprovalChunk(chunk);
+              break;
             case "tool-output":
-              this.#handleToolOutputChunk(chunk);
               break;
             case "tool-result": {
-              const toolCallId = chunk.payload?.toolCallId;
-              if (toolCallId && this.#streamedToolCallIds.has(toolCallId)) {
-                this.#streamedToolCallIds.delete(toolCallId);
-                break;
-              }
-              const { args, ...cleanPayload } = chunk.payload || {};
-              this.#createEventSpan(chunk.type, cleanPayload);
+              const {
+                // Metadata - tool call context (unique to tool-result chunks)
+                toolCallId,
+                toolName,
+                isError,
+                dynamic,
+                providerExecuted,
+                providerMetadata,
+                // Output - the actual result
+                result} = chunk.payload || {};
+              const metadata = { toolCallId, toolName };
+              if (isError !== void 0) metadata.isError = isError;
+              if (dynamic !== void 0) metadata.dynamic = dynamic;
+              if (providerExecuted !== void 0) metadata.providerExecuted = providerExecuted;
+              if (providerMetadata !== void 0) metadata.providerMetadata = providerMetadata;
+              this.#createEventSpan(chunk.type, result, { metadata });
               break;
             }
           }
@@ -6573,7 +7365,11 @@ var DEFAULT_KEYS_TO_STRIP = /* @__PURE__ */ new Set([
   "experimental_providerMetadata",
   "providerMetadata",
   "steps",
-  "tracingContext"
+  "tracingContext",
+  "execute",
+  // Tool execute functions
+  "validate"
+  // Schema validate functions
 ]);
 var DEFAULT_DEEP_CLEAN_OPTIONS = Object.freeze({
   keysToStrip: DEFAULT_KEYS_TO_STRIP,
@@ -6600,6 +7396,50 @@ function truncateString(s, maxChars) {
   }
   return s.slice(0, maxChars) + "\u2026[truncated]";
 }
+function isJsonSchema(val) {
+  if (typeof val !== "object" || val === null) return false;
+  if (val.$schema && typeof val.$schema === "string" && val.$schema.includes("json-schema")) {
+    return true;
+  }
+  if (val.type === "object" && val.properties && typeof val.properties === "object") {
+    return true;
+  }
+  return false;
+}
+function compressJsonSchema(schema, depth = 0) {
+  if (depth > 3) {
+    return schema.type || "object";
+  }
+  if (schema.type !== "object" || !schema.properties) {
+    return schema.type || schema;
+  }
+  const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+  const compressed = {};
+  for (const [key, propSchema] of Object.entries(schema.properties)) {
+    const prop = propSchema;
+    let value = prop.type || "unknown";
+    if (prop.type === "object" && prop.properties) {
+      value = compressJsonSchema(prop, depth + 1);
+      if (required.has(key)) {
+        compressed[key + " (required)"] = value;
+        continue;
+      }
+    } else if (prop.type === "array" && prop.items) {
+      if (prop.items.type === "object" && prop.items.properties) {
+        value = [compressJsonSchema(prop.items, depth + 1)];
+      } else {
+        value = `${prop.items.type || "any"}[]`;
+      }
+    } else if (prop.enum) {
+      value = prop.enum.map((v) => JSON.stringify(v)).join(" | ");
+    }
+    if (required.has(key) && typeof value === "string") {
+      value += " (required)";
+    }
+    compressed[key] = value;
+  }
+  return compressed;
+}
 function deepClean(value, options = DEFAULT_DEEP_CLEAN_OPTIONS) {
   const { keysToStrip, maxDepth, maxStringLength, maxArrayLength, maxObjectKeys } = options;
   const seen = /* @__PURE__ */ new WeakSet();
@@ -6659,6 +7499,15 @@ function deepClean(value, options = DEFAULT_DEEP_CLEAN_OPTIONS) {
     if (val instanceof ArrayBuffer) {
       return `[ArrayBuffer byteLength=${val.byteLength}]`;
     }
+    if (typeof val.serializeForSpan === "function") {
+      try {
+        return helper(val.serializeForSpan(), depth);
+      } catch {
+      }
+    }
+    if (isJsonSchema(val)) {
+      return helper(compressJsonSchema(val), depth);
+    }
     const cleaned = {};
     const entries = Object.entries(val);
     let keyCount = 0;
@@ -6766,9 +7615,10 @@ var BaseSpan = class {
     this.isInternal = isSpanInternal(this.type, options.tracingPolicy?.internal);
     this.traceState = options.traceState;
     this.tags = !options.parent && options.tags?.length ? options.tags : void 0;
-    this.entityType = options.entityType ?? options.parent?.entityType;
-    this.entityId = options.entityId ?? options.parent?.entityId;
-    this.entityName = options.entityName ?? options.parent?.entityName;
+    const entityParent = this.getParentSpan(false);
+    this.entityType = options.entityType ?? entityParent?.entityType;
+    this.entityId = options.entityId ?? entityParent?.entityId;
+    this.entityName = options.entityName ?? entityParent?.entityName;
     if (this.isEvent) {
       this.output = deepClean(options.output, this.deepCleanOptions);
     } else {
@@ -6795,14 +7645,25 @@ var BaseSpan = class {
   get isRootSpan() {
     return !this.parent;
   }
+  /** Get the closest parent span, optionally skipping internal spans */
+  getParentSpan(includeInternalSpans) {
+    if (!this.parent) {
+      return void 0;
+    }
+    if (includeInternalSpans) return this.parent;
+    if (this.parent.isInternal) return this.parent.getParentSpan(includeInternalSpans);
+    return this.parent;
+  }
   /** Get the closest parent spanId that isn't an internal span */
   getParentSpanId(includeInternalSpans) {
     if (!this.parent) {
       return this.parentSpanId;
     }
-    if (includeInternalSpans) return this.parent.id;
-    if (this.parent.isInternal) return this.parent.getParentSpanId(includeInternalSpans);
-    return this.parent.id;
+    const parentSpan = this.getParentSpan(includeInternalSpans);
+    if (parentSpan) {
+      return parentSpan.id;
+    }
+    return this.parent.getParentSpanId(includeInternalSpans);
   }
   /** Find the closest parent span of a specific type by walking up the parent chain */
   findParent(spanType) {
@@ -7846,6 +8707,7 @@ exports.DEFAULT_KEYS_TO_STRIP = DEFAULT_KEYS_TO_STRIP;
 exports.DefaultExporter = DefaultExporter;
 exports.DefaultObservabilityInstance = DefaultObservabilityInstance;
 exports.DefaultSpan = DefaultSpan;
+exports.JsonExporter = JsonExporter;
 exports.ModelSpanTracker = ModelSpanTracker;
 exports.NoOpSpan = NoOpSpan;
 exports.Observability = Observability;