agent-inspect 6.31.7 → 6.31.9

package/packages/core/dist/index.mjs

@@ -1,5 +1,5 @@
-import { getCurrentContext, getCurrentDepth, getParentStepId, getTraceSafetyFromContext, runWithStepContext, printStepStart, printStepComplete, printError, printFailedAt, inspectRun } from './chunk-VQUB3WRI.mjs';
-export { createInspector, getCurrentCorrelationMetadata, inspectRun, maybeInspectRun } from './chunk-VQUB3WRI.mjs';
+import { getCurrentContext, getCurrentDepth, getParentStepId, getTraceSafetyFromContext, runWithStepContext, printStepStart, printStepComplete, printError, printFailedAt, inspectRun } from './chunk-3SPBELJB.mjs';
+export { createInspector, getCurrentCorrelationMetadata, inspectRun, maybeInspectRun } from './chunk-3SPBELJB.mjs';
 import { normalizeObserveOutcomeInput, prepareOutcomeEventForDisk } from './chunk-N5PZAI6Q.mjs';
 import './chunk-BT7CATSD.mjs';
 import { prepareTraceEventForDisk, writeTraceEvent } from './chunk-DK3OW6UI.mjs';

package/packages/core/dist/persisted.cjs

@@ -1023,12 +1023,12 @@ function persistedInspectEventToTraceEvents(event) {
   if (!isPersistedInspectEvent(event)) {
     throw new Error("Invalid PersistedInspectEvent: failed isPersistedInspectEvent");
   }
-  const legacyEvent = event.attributes?.legacyEvent;
-  if (legacyEvent === "run_started") return [fromLegacyRunStarted(event)];
-  if (legacyEvent === "run_completed") return [fromLegacyRunCompleted(event)];
-  if (legacyEvent === "step_started") return [fromLegacyStepStarted(event)];
-  if (legacyEvent === "step_completed") return [fromLegacyStepCompleted(event)];
-  if (legacyEvent === "outcome_observed") return [fromLegacyOutcomeObserved(event)];
+  const legacyEvent2 = event.attributes?.legacyEvent;
+  if (legacyEvent2 === "run_started") return [fromLegacyRunStarted(event)];
+  if (legacyEvent2 === "run_completed") return [fromLegacyRunCompleted(event)];
+  if (legacyEvent2 === "step_started") return [fromLegacyStepStarted(event)];
+  if (legacyEvent2 === "step_completed") return [fromLegacyStepCompleted(event)];
+  if (legacyEvent2 === "outcome_observed") return [fromLegacyOutcomeObserved(event)];
   if (event.kind === "RUN") {
     return fromNativeRun(event);
   }
@@ -1049,6 +1049,336 @@ function persistedInspectEventsToTraceEvents(events, options) {
   return out;
 }
 
+// packages/core/src/diagnostics/programmatic.ts
+var PROGRAMMATIC_DIAGNOSTIC_SPECS = Object.freeze({
+  AI_TRACE_INPUT_INVALID: {
+    code: "AI_TRACE_INPUT_INVALID",
+    summary: 'Expected { type: "file", path }, { type: "directory", path }, { type: "string", content }, { type: "buffer", content }, or { type: "stdin" }.',
+    remediation: "For a file path, use openTraceFile(path).",
+    relatedCodes: ["invalid_input"]
+  },
+  AI_TRACE_FORMAT_UNSUPPORTED: {
+    code: "AI_TRACE_FORMAT_UNSUPPORTED",
+    summary: "No trace reader could detect the input format.",
+    remediation: "Pass an AgentInspect JSONL file via openTraceFile, or set options.format to a registered reader.",
+    relatedCodes: ["unsupported_format"]
+  },
+  AI_TRACE_FORMAT_AMBIGUOUS: {
+    code: "AI_TRACE_FORMAT_AMBIGUOUS",
+    summary: "Multiple trace readers matched the input with equal confidence.",
+    remediation: "Set options.format explicitly to disambiguate the reader.",
+    relatedCodes: ["ambiguous_format"]
+  },
+  AI_TRACE_FACTS_INPUT_NOT_NORMALIZED: {
+    code: "AI_TRACE_FACTS_INPUT_NOT_NORMALIZED",
+    summary: "TraceFacts requires TraceReadResult or PersistedInspectEvent[].",
+    remediation: "Use openTraceFile() to normalize a JSONL trace first."
+  },
+  AI_TRACE_CONTRACT_RUN_SELECTION_REQUIRED: {
+    code: "AI_TRACE_CONTRACT_RUN_SELECTION_REQUIRED",
+    summary: "Multiple runs are available; select a run before executing checks.",
+    remediation: "Pass options.runId or TraceCheckInput.selectedRun.",
+    relatedCodes: ["AI_CHECK_RUN_SELECTION_REQUIRED"]
+  },
+  AI_TRACE_RELATIONSHIP_SELF_PARENT: {
+    code: "AI_TRACE_RELATIONSHIP_SELF_PARENT",
+    summary: "A parentId equals its own event/step id.",
+    remediation: "Reject at capture (AI_LANGGRAPH_SELF_PARENT_REJECTED) or drop via logical projection; do not invent replacement parents.",
+    relatedCodes: [
+      "AI_LANGGRAPH_SELF_PARENT_REJECTED",
+      "AI_LOGICAL_SELF_PARENT_REMOVED"
+    ]
+  },
+  AI_TRACE_RELATIONSHIP_CYCLE: {
+    code: "AI_TRACE_RELATIONSHIP_CYCLE",
+    summary: "Trace contains a parentId cycle.",
+    remediation: "Use visibility-first tree linking for legacy fixtures; prefer acyclic capture for new adapter output.",
+    relatedCodes: ["structure.cycle"]
+  }
+});
+function formatProgrammaticDiagnostic(code, detail) {
+  const spec = PROGRAMMATIC_DIAGNOSTIC_SPECS[code];
+  const summary = detail?.trim() ? detail.trim() : spec.summary;
+  return `${code}: ${summary} Remediation: ${spec.remediation}`;
+}
+
+// packages/core/src/checks/logical-events.ts
+function isRecord3(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function legacyEvent(event) {
+  const value = event.attributes?.legacyEvent;
+  return typeof value === "string" ? value : void 0;
+}
+function stepIdOf(event) {
+  const value = event.attributes?.stepId;
+  if (typeof value === "string" && value.trim() !== "") return value;
+  return void 0;
+}
+function cloneEvent(event) {
+  return {
+    ...event,
+    ...event.attributes !== void 0 ? { attributes: { ...event.attributes } } : {},
+    ...event.error !== void 0 ? { error: { ...event.error } } : {},
+    ...event.tokenUsage !== void 0 ? { tokenUsage: { ...event.tokenUsage } } : {},
+    ...event.source !== void 0 ? { source: { ...event.source } } : {}
+  };
+}
+function mergeAttributes(start, complete) {
+  const merged = {
+    ...isRecord3(complete.attributes) ? complete.attributes : {},
+    ...isRecord3(start.attributes) ? start.attributes : {}
+  };
+  merged.legacyEvent = start.attributes?.legacyEvent ?? complete.attributes?.legacyEvent;
+  merged.legacyCompleteEvent = complete.attributes?.legacyEvent;
+  if (complete.attributes?.errorStack !== void 0) {
+    merged.errorStack = complete.attributes.errorStack;
+  }
+  return Object.keys(merged).length > 0 ? merged : void 0;
+}
+function pairStartComplete(start, complete) {
+  const attributes = mergeAttributes(start, complete);
+  const paired = {
+    ...cloneEvent(start),
+    status: complete.status,
+    timestamp: complete.timestamp ?? start.timestamp,
+    ...complete.endedAt !== void 0 ? { endedAt: complete.endedAt } : {},
+    ...complete.durationMs !== void 0 ? { durationMs: complete.durationMs } : {},
+    ...complete.error !== void 0 ? { error: { ...complete.error } } : {},
+    ...complete.tokenUsage !== void 0 && start.tokenUsage === void 0 ? { tokenUsage: { ...complete.tokenUsage } } : {},
+    ...attributes !== void 0 ? { attributes } : {}
+  };
+  return {
+    ...paired,
+    sourceEventIds: Object.freeze([start.eventId, complete.eventId]),
+    projection: {
+      paired: true,
+      absorbedEventIds: Object.freeze([complete.eventId]),
+      parentNormalized: false,
+      ...start.parentId !== void 0 ? { originalParentId: start.parentId } : {}
+    }
+  };
+}
+function asLogical(event, extras) {
+  return {
+    ...cloneEvent(event),
+    sourceEventIds: Object.freeze([event.eventId]),
+    projection: {
+      paired: false,
+      absorbedEventIds: Object.freeze([]),
+      parentNormalized: extras?.parentNormalized === true,
+      ...{}
+    }
+  };
+}
+function projectLogicalEvents(events) {
+  const diagnostics = [];
+  const byRun = /* @__PURE__ */ new Map();
+  for (const event of events) {
+    const list = byRun.get(event.runId) ?? [];
+    list.push(event);
+    byRun.set(event.runId, list);
+  }
+  const absorbedIds = /* @__PURE__ */ new Set();
+  const logicalByRawId = /* @__PURE__ */ new Map();
+  const stepIdToLogicalId = /* @__PURE__ */ new Map();
+  const logical = [];
+  const orderedRuns = [...byRun.keys()].sort((a, b) => a.localeCompare(b));
+  for (const runId of orderedRuns) {
+    const runEvents = byRun.get(runId) ?? [];
+    const starts = [];
+    const completes = [];
+    const others = [];
+    for (const event of runEvents) {
+      const legacy = legacyEvent(event);
+      if (legacy === "step_started" || legacy === "run_started" && event.status === "running") {
+        starts.push(event);
+      } else if (legacy === "step_completed" || legacy === "run_completed") {
+        completes.push(event);
+      } else {
+        others.push(event);
+      }
+    }
+    const usedCompletes = /* @__PURE__ */ new Set();
+    for (const start of starts) {
+      const stepId = stepIdOf(start);
+      let match;
+      if (legacyEvent(start) === "run_started") {
+        const candidates = completes.filter(
+          (c) => !usedCompletes.has(c.eventId) && legacyEvent(c) === "run_completed"
+        );
+        if (candidates.length > 1) {
+          diagnostics.push({
+            code: "AI_LOGICAL_PAIR_AMBIGUOUS",
+            message: `Multiple run_completed rows for run ${runId}; using first by eventId.`,
+            eventIds: candidates.map((c) => c.eventId)
+          });
+          candidates.sort((a, b) => a.eventId.localeCompare(b.eventId));
+        }
+        match = candidates[0];
+      } else if (stepId) {
+        const candidates = completes.filter(
+          (c) => !usedCompletes.has(c.eventId) && legacyEvent(c) === "step_completed" && stepIdOf(c) === stepId
+        );
+        if (candidates.length > 1) {
+          diagnostics.push({
+            code: "AI_LOGICAL_PAIR_AMBIGUOUS",
+            message: `Multiple step_completed rows for stepId ${stepId}; using first by eventId.`,
+            eventIds: candidates.map((c) => c.eventId)
+          });
+          candidates.sort((a, b) => a.eventId.localeCompare(b.eventId));
+        }
+        match = candidates[0];
+      }
+      if (match) {
+        usedCompletes.add(match.eventId);
+        absorbedIds.add(match.eventId);
+        const paired = pairStartComplete(start, match);
+        logical.push(paired);
+        logicalByRawId.set(start.eventId, paired);
+        logicalByRawId.set(match.eventId, paired);
+        if (stepId) stepIdToLogicalId.set(`${runId}:${stepId}`, paired.eventId);
+      } else {
+        diagnostics.push({
+          code: "AI_LOGICAL_PAIR_UNMATCHED_START",
+          message: `No matching complete for start ${start.eventId}.`,
+          eventIds: [start.eventId]
+        });
+        const alone = asLogical(start);
+        logical.push(alone);
+        logicalByRawId.set(start.eventId, alone);
+        if (stepId) stepIdToLogicalId.set(`${runId}:${stepId}`, alone.eventId);
+      }
+    }
+    for (const complete of completes) {
+      if (usedCompletes.has(complete.eventId)) continue;
+      diagnostics.push({
+        code: "AI_LOGICAL_PAIR_UNMATCHED_COMPLETE",
+        message: `No matching start for complete ${complete.eventId}.`,
+        eventIds: [complete.eventId]
+      });
+      const alone = asLogical(complete);
+      logical.push(alone);
+      logicalByRawId.set(complete.eventId, alone);
+      const stepId = stepIdOf(complete);
+      if (stepId && !stepIdToLogicalId.has(`${runId}:${stepId}`)) {
+        stepIdToLogicalId.set(`${runId}:${stepId}`, alone.eventId);
+      }
+    }
+    for (const event of others) {
+      const alone = asLogical(event);
+      logical.push(alone);
+      logicalByRawId.set(event.eventId, alone);
+      const stepId = stepIdOf(event);
+      if (stepId && !stepIdToLogicalId.has(`${runId}:${stepId}`)) {
+        stepIdToLogicalId.set(`${runId}:${stepId}`, alone.eventId);
+      }
+    }
+  }
+  const logicalById = new Map(logical.map((e) => [e.eventId, e]));
+  const normalized = [];
+  for (const event of logical) {
+    const originalParentId = event.parentId;
+    if (!originalParentId) {
+      normalized.push(event);
+      continue;
+    }
+    let nextParent = originalParentId;
+    let remapped = false;
+    const viaAbsorbed = logicalByRawId.get(originalParentId);
+    if (viaAbsorbed && viaAbsorbed.eventId !== originalParentId) {
+      nextParent = viaAbsorbed.eventId;
+      remapped = true;
+    } else if (!logicalById.has(originalParentId)) {
+      const viaStep = stepIdToLogicalId.get(`${event.runId}:${originalParentId}`);
+      if (viaStep) {
+        nextParent = viaStep;
+        remapped = true;
+      }
+    }
+    if (!remapped) {
+      if (originalParentId === event.eventId) {
+        diagnostics.push({
+          code: "AI_LOGICAL_SELF_PARENT_REMOVED",
+          message: formatProgrammaticDiagnostic(
+            "AI_TRACE_RELATIONSHIP_SELF_PARENT",
+            `Removed self-parent edge on ${event.eventId}.`
+          ),
+          eventIds: [event.eventId]
+        });
+        const { parentId: _drop, ...rest } = event;
+        normalized.push({
+          ...rest,
+          projection: {
+            ...event.projection,
+            parentNormalized: true,
+            originalParentId
+          }
+        });
+        continue;
+      }
+      if (!logicalById.has(originalParentId) && !logicalByRawId.has(originalParentId)) {
+        const mapping = event.attributes?.parentMapping;
+        const unresolved = mapping === "unresolved" || event.attributes?.parentUnresolved === true || event.attributes?.unresolvedParent === true || // LangGraph/framework scaffolding sentinel labels are not event ids.
+        /^LangGraph$/i.test(originalParentId) || originalParentId.startsWith("unresolved:");
+        if (!unresolved) {
+          diagnostics.push({
+            code: "AI_LOGICAL_PARENT_UNRESOLVED",
+            message: `Parent ${originalParentId} unresolved for ${event.eventId}.`,
+            eventIds: [event.eventId]
+          });
+        }
+      }
+      normalized.push(event);
+      continue;
+    }
+    if (nextParent === event.eventId) {
+      diagnostics.push({
+        code: "AI_LOGICAL_SELF_PARENT_REMOVED",
+        message: formatProgrammaticDiagnostic(
+          "AI_TRACE_RELATIONSHIP_SELF_PARENT",
+          `Removed self-parent edge on ${event.eventId} (was ${originalParentId}).`
+        ),
+        eventIds: [event.eventId]
+      });
+      const { parentId: _drop, ...rest } = event;
+      normalized.push({
+        ...rest,
+        projection: {
+          ...event.projection,
+          parentNormalized: true,
+          originalParentId
+        }
+      });
+      continue;
+    }
+    diagnostics.push({
+      code: "AI_LOGICAL_PARENT_REMAPPED",
+      message: `Remapped parent ${originalParentId} \u2192 ${nextParent} for ${event.eventId}.`,
+      eventIds: [event.eventId]
+    });
+    normalized.push({
+      ...event,
+      parentId: nextParent,
+      projection: {
+        ...event.projection,
+        parentNormalized: true,
+        originalParentId
+      }
+    });
+  }
+  const rawIndex = new Map(events.map((e, i) => [e.eventId, i]));
+  normalized.sort((a, b) => {
+    const ai = rawIndex.get(a.sourceEventIds[0]) ?? 0;
+    const bi = rawIndex.get(b.sourceEventIds[0]) ?? 0;
+    return ai - bi || a.eventId.localeCompare(b.eventId);
+  });
+  return {
+    logicalEvents: Object.freeze(normalized),
+    diagnostics: Object.freeze(diagnostics)
+  };
+}
+
 // packages/core/src/logs/tree-builder.ts
 function inc(map, key) {
   map[key] = (map[key] ?? 0) + 1;
@@ -1221,15 +1551,20 @@ var TreeBuilder = class {
 };
 
 // packages/core/src/persisted/tree-bridge.ts
+function logicalToPersisted(event) {
+  const { sourceEventIds: _sourceEventIds, projection: _projection, ...rest } = event;
+  return rest;
+}
 function persistedInspectEventsToRunTrees(events, options) {
-  const inspectEvents = persistedInspectEventsToInspectEvents(events, {
+  const sourceEvents = options?.coalesceLifecycle === true ? projectLogicalEvents(events).logicalEvents.map(logicalToPersisted) : events;
+  const inspectEvents = persistedInspectEventsToInspectEvents(sourceEvents, {
     skipInvalid: options?.skipInvalid
   });
   return new TreeBuilder().build(inspectEvents);
 }
-function traceEventsToPersistedRunTrees(events) {
+function traceEventsToPersistedRunTrees(events, options) {
   const persisted = traceEventsToPersistedInspectEvents(events);
-  return persistedInspectEventsToRunTrees(persisted);
+  return persistedInspectEventsToRunTrees(persisted, options);
 }
 
 exports.inspectEventToPersistedInspectEvent = inspectEventToPersistedInspectEvent;