agent-inspect 6.31.6 → 6.31.7

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 6.31.7
+
+### Patch Changes
+
+- 3f7abb5: Make timeline depth resolution cycle-safe and stack-safe for cyclic or very deep parent chains (GitHub #453 / #454).
+- 3f7abb5: Preserve framework source attribution on CLI export via the persisted tree bridge, emit numeric OTLP StatusCode/SpanKind enums, map numeric status 0/1/2 on import, and harden OTLP nested validation with field-path diagnostics.
+
 ## 6.31.6
 
 ### Patch Changes

package/README.md

@@ -213,7 +213,7 @@ The root package is enough for custom capture, the CLI, checks, and Evidence wor
 
 ## Status and documentation
 
-**Current published baseline:** **6.31.6** · persisted schema `1.0` · Node.js `>=20` · MIT.
+**Current published baseline:** **6.31.7** · persisted schema `1.0` · Node.js `>=20` · MIT.
 
 Legacy v0.1 and v0.2 traces remain readable. Check the npm badge and [changelog](CHANGELOG.md) for the current published version.
 

package/docs/AI-SDK-ADOPTION.md

@@ -2,10 +2,12 @@
 
 Blessed path for **Vercel AI SDK** + AgentInspect — local traces only, metadata-first by default.
 
+**Peer:** `ai@^6.0.0` — tested with **`ai@6.0.210`**. This guide does not claim AI SDK 7 support.
+
 ## Install
 
 ```bash
-npm install agent-inspect @agent-inspect/ai-sdk ai
+npm install agent-inspect @agent-inspect/ai-sdk ai@6.0.210
 ```
 
 Or bootstrap a project:
@@ -20,54 +22,79 @@ npx agent-inspect init --framework ai-sdk
 import { generateText } from "ai";
 import { agentInspect } from "@agent-inspect/ai-sdk";
 
-await generateText({
-  model: yourModel,
-  prompt: "Hello",
-  experimental_telemetry: {
-    isEnabled: true,
-    recordInputs: false,
-    recordOutputs: false,
-    integrations: [
-      agentInspect({
-        traceDir: ".agent-inspect",
-        runName: "support-agent",
-        capture: "metadata-only",
-      }),
-    ],
-  },
+const integration = agentInspect({
+  traceDir: ".agent-inspect",
+  runName: "support-agent",
+  capture: "metadata-only",
 });
+
+try {
+  await generateText({
+    model: yourModel,
+    prompt: "Hello",
+    experimental_telemetry: {
+      isEnabled: true,
+      recordInputs: false,
+      recordOutputs: false,
+      integrations: [integration],
+    },
+  });
+} finally {
+  await integration.flush();
+  await integration.close();
+}
 ```
 
+Pass the integration only through `experimental_telemetry.integrations`. AgentInspect does **not** expose `getTelemetryMetadata()` or `getTelemetryHandlers()`.
+
 ## `streamText` (metadata-only)
 
 ```ts
 import { streamText } from "ai";
 import { agentInspect } from "@agent-inspect/ai-sdk";
 
-const result = streamText({
-  model: yourModel,
-  prompt: "Hello",
-  experimental_telemetry: {
-    isEnabled: true,
-    recordInputs: false,
-    recordOutputs: false,
-    integrations: [
-      agentInspect({
-        traceDir: ".agent-inspect",
-        runName: "stream-demo",
-        capture: "metadata-only",
-      }),
-    ],
-  },
+const integration = agentInspect({
+  traceDir: ".agent-inspect",
+  runName: "stream-demo",
+  capture: "metadata-only",
 });
 
-for await (const _chunk of result.textStream) {
-  // consume stream
+try {
+  const result = streamText({
+    model: yourModel,
+    prompt: "Hello",
+    experimental_telemetry: {
+      isEnabled: true,
+      recordInputs: false,
+      recordOutputs: false,
+      integrations: [integration],
+    },
+  });
+
+  for await (const _chunk of result.textStream) {
+    // consume stream
+  }
+} finally {
+  await integration.flush();
+  await integration.close();
 }
 ```
 
 Streaming lifecycle metadata is captured; raw token streams are not persisted by default.
 
+## Concurrent generations
+
+Create a **new** `agentInspect()` instance for each concurrent generation. Do not share one integration across overlapping `generateText` / `streamText` calls.
+
+## Diagnostics
+
+```ts
+const d = integration.getDiagnostics();
+console.log(d.writeFailures, d.lifecycleWarnings, d.lastWarning, d.capture);
+```
+
+Use `onDiagnostic` in options for live callbacks. Failures degrade locally; they do not throw into your agent return path.
+
 ## Tool calls
 
 Tool spans appear when the model invokes tools. Keep `recordInputs` / `recordOutputs` false unless you explicitly accept content capture risk.
@@ -110,10 +137,11 @@ Use `--fail-on-observation` only when the run records explicit OUTCOME events.
 
 | Symptom | Fix |
 | ------- | --- |
-| No trace file | Ensure `experimental_telemetry.isEnabled: true` and integrations include `agentInspect()` |
+| No trace file | Ensure `experimental_telemetry.isEnabled: true` and `integrations: [integration]` |
 | Empty trace | Confirm `AGENT_INSPECT` is not `0` |
 | Prompts in trace | Set `recordInputs: false` and `recordOutputs: false` on the AI SDK call |
 | Wrong directory | Pass `traceDir` to `agentInspect()` or set `AGENT_INSPECT_TRACE_DIR` |
+| Mixed concurrent runs | Use a separate `agentInspect()` instance per overlapping generation |
 
 ## Recipes (no network)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-inspect",
-  "version": "6.31.6",
+  "version": "6.31.7",
   "license": "MIT",
   "type": "module",
   "description": "Local evidence debugger and trajectory-test toolkit for TypeScript AI agents — execution trees, TraceContract checks, Evidence v2, and read-only MCP",

package/packages/cli/dist/{chunk-YXDNWHNJ.mjs → chunk-QV73NM25.mjs}

@@ -2243,6 +2243,8 @@ function renderTraceStats(stats) {
 }
 
 // packages/core/src/timeline.ts
+var ROOT_TIMELINE_DEPTH = 0;
+var MAX_TIMELINE_DEPTH = 1e3;
 function finite(n) {
   return typeof n === "number" && Number.isFinite(n);
 }
@@ -2313,16 +2315,51 @@ function buildRunTimeline(events, options = {}) {
   const computeDepth = (stepId) => {
     const cached = depthCache.get(stepId);
     if (cached !== void 0) return cached;
-    const node = steps.get(stepId);
-    if (!node) return 0;
-    const parent = node.parentId;
-    if (typeof parent !== "string" || parent.trim() === "" || !steps.has(parent)) {
-      depthCache.set(stepId, 0);
-      return 0;
+    const ancestry = [];
+    const ancestryIndexes = /* @__PURE__ */ new Map();
+    let currentStepId = stepId;
+    let resolvedDepth;
+    while (resolvedDepth === void 0) {
+      const cachedDepth = depthCache.get(currentStepId);
+      if (cachedDepth !== void 0) {
+        resolvedDepth = cachedDepth;
+        continue;
+      }
+      const cycleStart = ancestryIndexes.get(currentStepId);
+      if (cycleStart !== void 0) {
+        const cycleStepIds = ancestry.splice(cycleStart);
+        for (const cycleStepId of cycleStepIds) {
+          depthCache.set(cycleStepId, ROOT_TIMELINE_DEPTH);
+        }
+        resolvedDepth = ROOT_TIMELINE_DEPTH;
+        continue;
+      }
+      const currentStep = steps.get(currentStepId);
+      if (!currentStep) {
+        resolvedDepth = ROOT_TIMELINE_DEPTH;
+        continue;
+      }
+      ancestryIndexes.set(currentStepId, ancestry.length);
+      ancestry.push(currentStepId);
+      const parentId = currentStep.parentId;
+      if (typeof parentId !== "string" || parentId.trim() === "" || !steps.has(parentId)) {
+        ancestry.pop();
+        depthCache.set(currentStepId, ROOT_TIMELINE_DEPTH);
+        resolvedDepth = ROOT_TIMELINE_DEPTH;
+        continue;
+      }
+      currentStepId = parentId;
+    }
+    ancestry.reverse();
+    for (const ancestorStepId of ancestry) {
+      resolvedDepth = Math.min(MAX_TIMELINE_DEPTH, resolvedDepth + 1);
+      depthCache.set(ancestorStepId, resolvedDepth);
+    }
+    const resolvedStepDepth = depthCache.get(stepId);
+    if (resolvedStepDepth === void 0) {
+      throw new Error(`Failed to resolve timeline depth for step "${stepId}"`);
     }
-    const d = Math.min(1e3, computeDepth(parent) + 1);
-    depthCache.set(stepId, d);
-    return d;
+    return resolvedStepDepth;
   };
   const entries = [];
   for (const [stepId, s] of steps.entries()) {
@@ -11882,6 +11919,23 @@ function persistedInspectEventToInspectEvent(event) {
   if (event.durationMs !== void 0 && Number.isFinite(event.durationMs) && event.durationMs >= 0) {
     out.durationMs = event.durationMs;
   }
+  if (event.startedAt !== void 0) {
+    const started = parseIsoToMs3(event.startedAt);
+    if (!started.invalidTimestamp) {
+      attrs.startedAtMs = started.ms;
+      out.timestamp = started.ms;
+    }
+  }
+  if (event.endedAt !== void 0) {
+    const ended = parseIsoToMs3(event.endedAt);
+    if (!ended.invalidTimestamp) {
+      attrs.endedAtMs = ended.ms;
+      if (out.durationMs === void 0 && typeof attrs.startedAtMs === "number" && ended.ms >= attrs.startedAtMs) {
+        out.durationMs = ended.ms - attrs.startedAtMs;
+      }
+    }
+  }
+  out.attributes = compactAttributes3(attrs);
   return out;
 }
 function persistedInspectEventsToInspectEvents(events, options) {
@@ -12943,20 +12997,38 @@ function extractOtlpDocument(root) {
 function mapOtlpStatus(status) {
   if (!isRecord11(status)) return void 0;
   const rawCode = status.code;
-  if (typeof rawCode !== "string") return void 0;
-  switch (rawCode.toUpperCase()) {
-    case "STATUS_CODE_OK":
-    case "OK":
-      return "ok";
-    case "STATUS_CODE_ERROR":
-    case "ERROR":
-      return "error";
-    case "STATUS_CODE_UNSET":
-    case "UNSET":
-      return "unknown";
-    default:
-      return "unknown";
+  if (typeof rawCode === "number" && Number.isFinite(rawCode)) {
+    switch (rawCode) {
+      case 0:
+        return "unknown";
+      case 1:
+        return "ok";
+      case 2:
+        return "error";
+      default:
+        return "unknown";
+    }
+  }
+  if (typeof rawCode === "string") {
+    const trimmed = rawCode.trim();
+    if (/^\d+$/.test(trimmed)) {
+      return mapOtlpStatus({ code: Number(trimmed) });
+    }
+    switch (trimmed.toUpperCase()) {
+      case "STATUS_CODE_OK":
+      case "OK":
+        return "ok";
+      case "STATUS_CODE_ERROR":
+      case "ERROR":
+        return "error";
+      case "STATUS_CODE_UNSET":
+      case "UNSET":
+        return "unknown";
+      default:
+        return "unknown";
+    }
   }
+  return void 0;
 }
 function readOtlpKind(attributes, pathPrefix) {
   const warnings = [];
@@ -14887,6 +14959,6 @@ function renderGateReport(result, options = {}) {
   return renderGateSummaryMarkdown(result);
 }
 
-export { ATTRIBUTION_CONFIDENCES, COHORT_METRIC_IDS, DEFAULT_REDACT_KEYS, DEFAULT_SUITE_ARTIFACTS_DIR, EVIDENCE_FORMAT_VERSION, EVIDENCE_HTML_FILENAME, EVIDENCE_MANIFEST_FILENAME, Redactor, TraceDirectory, TraceReadError, TreeBuilder, aggregateBundleSafeStatus, aggregateSessionCheckResults, analyzeCohort, applyProfileMetadataCaps, assertBundlePathContained, assertEvidenceRelativePath, buildActivitySummary, buildBundleMetadata, buildBundleSummaryMarkdown, buildEvidenceCausalFailureViewHtml, buildEvidenceCiPackage, buildEvidenceCircuitViewHtml, buildEvidenceContractsViewHtml, buildEvidenceDiffViewHtml, buildEvidenceHtmlShell, buildEvidenceManifest, buildEvidenceOutcomesViewHtml, buildEvidenceProvenanceViewHtml, buildEvidenceSafetyViewHtml, buildEvidenceTimelineViewHtml, buildEvidenceToolsLlmViewHtml, buildEvidenceTreeViewHtml, buildLocalExplanation, buildPlaceholderArtifact, buildRunSummary, buildRunTimeline, buildRunWhatSummary, buildSessionIndex, buildTraceStats, buildZipArchive, bundleFailsOnSafety, bundleRunAssetRelativePath, collectTraceSchemaVersions, compactAttributes, createBaselineRegressionRule, createLlmUsageRule, createMaxStepDurationRule, createObservedOutcomeRule, createRequireCompletedRule, createRunDepthRule, createRunDurationRule, createRunStatusRule, createSafetyOversizedAttributeRule, createSafetyRawContentRule, createSafetyRedactionRule, createSafetySecretPatternRule, createStallDetectionRule, createStructureCycleRule, createStructureOrphanRule, createStructureParallelWidthRule, createStructureRelationshipRule, createToolUsageRule, defaultBundleOutputPath, defaultSuiteConfigTemplate, defineTraceContract, diffRuns, diffTraceEvents, enrichSessionRunRecord, escapeHtml, escapeMarkdown, evaluateTraceContract, extractMetadata, extractOutcomesFromTraceEvents, filterMetasBySessionScope, filterTraces, flattenTree, formatDuration2 as formatDuration, formatStepLabel, formatTimestamp, gateHasThresholds, getIndent, getTraceFilePath, inferEvidenceFileRole, isAgentInspectTrace, isAttributionConfidence, isCredentialSensitiveKey, isPersistedInspectEvent, loadSessionRunRecords, loadSuiteConfig, loadTraceMetadataList, manualTraceEventsToComparableRun, nanoid, normalizeBundleOutputPath, openTrace, parseCohortMetricList, parseDuration, parseDurationFilter, parseGateList, parseTraceJsonl, persistedInspectEventsToTraceEvents, projectLogicalEvents, renderActivitySummaryHuman, renderCohortReport, renderErrorLine, renderGateReport, renderObservedOutcomesHtml, renderObservedOutcomesMarkdown, renderRunDiff, renderRunWhat, renderStepLine, renderSuiteReport, renderTimeline, renderTraceStats, resolveBundleRunIds, resolveRedactionProfile, resolveSuiteTemplate, resolveTraceDir, runGate, runSuite, runTraceChecks, safeString, sanitizeBundleRunId, searchTraces, serializeEvidenceManifest, sha256Hex, stableJson, stringContainsHighConfidenceCredential, summarizeObservedOutcomes, summarizeSemanticParity, traceEventToPersistedInspectEvent, truncateName, truncateStringForProfile, validateEvent, validateSuiteConfig, verifyEvidenceDirectory, zeroKinds };
-//# sourceMappingURL=chunk-YXDNWHNJ.mjs.map
-//# sourceMappingURL=chunk-YXDNWHNJ.mjs.map
+export { ATTRIBUTION_CONFIDENCES, COHORT_METRIC_IDS, DEFAULT_REDACT_KEYS, DEFAULT_SUITE_ARTIFACTS_DIR, EVIDENCE_FORMAT_VERSION, EVIDENCE_HTML_FILENAME, EVIDENCE_MANIFEST_FILENAME, Redactor, TraceDirectory, TraceReadError, TreeBuilder, aggregateBundleSafeStatus, aggregateSessionCheckResults, analyzeCohort, applyProfileMetadataCaps, assertBundlePathContained, assertEvidenceRelativePath, buildActivitySummary, buildBundleMetadata, buildBundleSummaryMarkdown, buildEvidenceCausalFailureViewHtml, buildEvidenceCiPackage, buildEvidenceCircuitViewHtml, buildEvidenceContractsViewHtml, buildEvidenceDiffViewHtml, buildEvidenceHtmlShell, buildEvidenceManifest, buildEvidenceOutcomesViewHtml, buildEvidenceProvenanceViewHtml, buildEvidenceSafetyViewHtml, buildEvidenceTimelineViewHtml, buildEvidenceToolsLlmViewHtml, buildEvidenceTreeViewHtml, buildLocalExplanation, buildPlaceholderArtifact, buildRunSummary, buildRunTimeline, buildRunWhatSummary, buildSessionIndex, buildTraceStats, buildZipArchive, bundleFailsOnSafety, bundleRunAssetRelativePath, collectTraceSchemaVersions, compactAttributes, createBaselineRegressionRule, createLlmUsageRule, createMaxStepDurationRule, createObservedOutcomeRule, createRequireCompletedRule, createRunDepthRule, createRunDurationRule, createRunStatusRule, createSafetyOversizedAttributeRule, createSafetyRawContentRule, createSafetyRedactionRule, createSafetySecretPatternRule, createStallDetectionRule, createStructureCycleRule, createStructureOrphanRule, createStructureParallelWidthRule, createStructureRelationshipRule, createToolUsageRule, defaultBundleOutputPath, defaultSuiteConfigTemplate, defineTraceContract, diffRuns, diffTraceEvents, enrichSessionRunRecord, escapeHtml, escapeMarkdown, evaluateTraceContract, extractMetadata, extractOutcomesFromTraceEvents, filterMetasBySessionScope, filterTraces, flattenTree, formatDuration2 as formatDuration, formatStepLabel, formatTimestamp, gateHasThresholds, getIndent, getTraceFilePath, inferEvidenceFileRole, isAgentInspectTrace, isAttributionConfidence, isCredentialSensitiveKey, isPersistedInspectEvent, loadSessionRunRecords, loadSuiteConfig, loadTraceMetadataList, manualTraceEventsToComparableRun, nanoid, normalizeBundleOutputPath, openTrace, parseCohortMetricList, parseDuration, parseDurationFilter, parseGateList, parseTraceJsonl, persistedInspectEventsToRunTrees, persistedInspectEventsToTraceEvents, projectLogicalEvents, renderActivitySummaryHuman, renderCohortReport, renderErrorLine, renderGateReport, renderObservedOutcomesHtml, renderObservedOutcomesMarkdown, renderRunDiff, renderRunWhat, renderStepLine, renderSuiteReport, renderTimeline, renderTraceStats, resolveBundleRunIds, resolveRedactionProfile, resolveSuiteTemplate, resolveTraceDir, runGate, runSuite, runTraceChecks, safeString, sanitizeBundleRunId, searchTraces, serializeEvidenceManifest, sha256Hex, stableJson, stringContainsHighConfidenceCredential, summarizeObservedOutcomes, summarizeSemanticParity, traceEventToPersistedInspectEvent, truncateName, truncateStringForProfile, validateEvent, validateSuiteConfig, verifyEvidenceDirectory, zeroKinds };
+//# sourceMappingURL=chunk-QV73NM25.mjs.map
+//# sourceMappingURL=chunk-QV73NM25.mjs.map