agent-inspect 6.14.1 → 6.15.0

package/packages/core/dist/readers.cjs

@@ -868,6 +868,20 @@ function traceEventsToPersistedInspectEvents(events, options) {
 function inc(map, key) {
   map[key] = (map[key] ?? 0) + 1;
 }
+function confidenceRank(confidence) {
+  switch (confidence) {
+    case "unknown":
+      return 0;
+    case "heuristic":
+      return 1;
+    case "correlated":
+      return 2;
+    case "explicit":
+      return 3;
+    default:
+      return 0;
+  }
+}
 function computeRunStatus(events) {
   let runTerminal;
   let sawRunEvent = false;
@@ -888,6 +902,84 @@ function computeRunStatus(events) {
   }
   return hasRunning ? "running" : "ok";
 }
+function linkNodesVisibilityFirst(nodes) {
+  let selfParentCount = 0;
+  let unresolvedParentCount = 0;
+  let normalizedEdgeCount = 0;
+  let cycleCount = 0;
+  const pending = [];
+  for (const node of nodes.values()) {
+    const parentId = node.event.parentId;
+    if (!parentId) continue;
+    if (parentId === node.event.eventId) {
+      selfParentCount += 1;
+      normalizedEdgeCount += 1;
+      continue;
+    }
+    if (!nodes.has(parentId)) {
+      unresolvedParentCount += 1;
+      continue;
+    }
+    pending.push({
+      childId: node.event.eventId,
+      parentId,
+      childTimestamp: node.event.timestamp,
+      childConfidence: node.event.confidence
+    });
+  }
+  pending.sort((a, b) => {
+    const conf = confidenceRank(b.childConfidence) - confidenceRank(a.childConfidence);
+    if (conf !== 0) return conf;
+    return a.childTimestamp - b.childTimestamp;
+  });
+  const parentOf = /* @__PURE__ */ new Map();
+  for (const edge of pending) {
+    parentOf.set(edge.childId, edge.parentId);
+    let cursor = edge.parentId;
+    const seen = /* @__PURE__ */ new Set([edge.childId]);
+    let cyclic = false;
+    while (cursor) {
+      if (seen.has(cursor)) {
+        cyclic = true;
+        break;
+      }
+      seen.add(cursor);
+      cursor = parentOf.get(cursor);
+    }
+    if (cyclic) {
+      parentOf.delete(edge.childId);
+      cycleCount += 1;
+      normalizedEdgeCount += 1;
+    }
+  }
+  for (const [childId, parentId] of parentOf) {
+    nodes.get(parentId).children.push(nodes.get(childId));
+  }
+  const roots = [];
+  for (const node of nodes.values()) {
+    if (!parentOf.has(node.event.eventId)) {
+      roots.push(node);
+    }
+  }
+  const assignDepth = (n, depth, stack) => {
+    if (stack.has(n.event.eventId)) return;
+    n.depth = depth;
+    stack.add(n.event.eventId);
+    for (const c of n.children) assignDepth(c, depth + 1, stack);
+    stack.delete(n.event.eventId);
+  };
+  for (const r of roots) assignDepth(r, 0, /* @__PURE__ */ new Set());
+  return {
+    roots,
+    summary: {
+      rootCount: roots.length,
+      selfParentCount,
+      cycleCount,
+      unresolvedParentCount,
+      normalizedEdgeCount
+    }
+  };
+}
 var TreeBuilder = class {
   constructor(options) {
     void options?.config;
@@ -905,20 +997,7 @@ var TreeBuilder = class {
       for (const e of sorted) {
         nodes.set(e.eventId, { event: e, children: [], depth: 0 });
       }
-      const roots = [];
-      for (const node of nodes.values()) {
-        const parentId = node.event.parentId;
-        if (parentId && nodes.has(parentId)) {
-          nodes.get(parentId).children.push(node);
-        } else {
-          roots.push(node);
-        }
-      }
-      const assignDepth = (n, depth) => {
-        n.depth = depth;
-        for (const c of n.children) assignDepth(c, depth + 1);
-      };
-      for (const r of roots) assignDepth(r, 0);
+      const { roots, summary } = linkNodesVisibilityFirst(nodes);
       const confidenceBreakdown = {
         explicit: 0,
         correlated: 0,
@@ -946,7 +1025,8 @@ var TreeBuilder = class {
         metadata: {
           totalEvents: sorted.length,
           confidenceBreakdown,
-          kinds
+          kinds,
+          relationshipSummary: summary
         }
       });
     }
@@ -1101,6 +1181,59 @@ function persistedInspectEventsToRunTrees(events, options) {
   return new TreeBuilder().build(inspectEvents);
 }
 
+// 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/readers/index.ts
 var DEFAULT_MAX_TRACE_INPUT_BYTES = 10 * 1024 * 1024;
 var MIN_DETECTION_CONFIDENCE = 0.5;
@@ -1175,6 +1308,38 @@ var TraceReadError = class extends Error {
     this.warnings = warnings;
   }
 };
+var TRACE_INPUT_INVALID_MESSAGE = formatProgrammaticDiagnostic(
+  "AI_TRACE_INPUT_INVALID"
+);
+function isTraceInput(input) {
+  if (typeof input !== "object" || input === null || Array.isArray(input)) {
+    return false;
+  }
+  const record = input;
+  switch (record.type) {
+    case "file":
+    case "directory":
+      return typeof record.path === "string";
+    case "string":
+      return typeof record.content === "string";
+    case "buffer":
+      return Buffer.isBuffer(record.content);
+    case "stdin":
+      return true;
+    default:
+      return false;
+  }
+}
+function assertTraceInput(input) {
+  if (isTraceInput(input)) return;
+  throw new TraceReadError("invalid_input", TRACE_INPUT_INVALID_MESSAGE, [
+    {
+      code: "AI_TRACE_INPUT_INVALID",
+      message: TRACE_INPUT_INVALID_MESSAGE,
+      severity: "error"
+    }
+  ]);
+}
 function normalizeCandidate(reader, candidate) {
   const confidence = Number.isFinite(candidate.confidence) ? Math.max(0, Math.min(1, candidate.confidence)) : 0;
   return {
@@ -2529,6 +2694,7 @@ var DEFAULT_TRACE_READERS = [
   otlpJsonReader
 ];
 async function detectTraceFormat(input, options = {}) {
+  assertTraceInput(input);
   const readers = options.readers ?? DEFAULT_TRACE_READERS;
   if (options.format !== void 0) {
     const reader = findReaderByFormat(options.format, readers);
@@ -2625,19 +2791,20 @@ async function detectTraceFormat(input, options = {}) {
   };
 }
 async function readTrace(input, options = {}) {
+  assertTraceInput(input);
   const readers = options.readers ?? DEFAULT_TRACE_READERS;
   const detection = await detectTraceFormat(input, options);
   if (detection.status === "unsupported" || detection.format === void 0) {
     throw new TraceReadError(
       "unsupported_format",
-      "No trace reader could detect the input format.",
+      formatProgrammaticDiagnostic("AI_TRACE_FORMAT_UNSUPPORTED"),
       detection.warnings
     );
   }
   if (detection.status === "ambiguous") {
     throw new TraceReadError(
       "ambiguous_format",
-      "Multiple trace readers matched the input with equal confidence.",
+      formatProgrammaticDiagnostic("AI_TRACE_FORMAT_AMBIGUOUS"),
       detection.warnings
     );
   }
@@ -2645,7 +2812,10 @@ async function readTrace(input, options = {}) {
   if (!reader) {
     throw new TraceReadError(
       "unsupported_format",
-      `No trace reader is registered for format "${detection.format}".`,
+      formatProgrammaticDiagnostic(
+        "AI_TRACE_FORMAT_UNSUPPORTED",
+        `No trace reader is registered for format "${detection.format}".`
+      ),
       detection.warnings
     );
   }
@@ -2674,13 +2844,28 @@ async function readTrace(input, options = {}) {
 function openTrace(input, options = {}) {
   return readTrace(input, options);
 }
+function openTraceFile(filePath, options = {}) {
+  return openTrace({ type: "file", path: filePath }, options);
+}
+function openTraceDirectory(dirPath, options = {}) {
+  return openTrace({ type: "directory", path: dirPath }, options);
+}
+function openTraceText(content, options = {}) {
+  return openTrace({ type: "string", content }, options);
+}
 
 exports.DEFAULT_TRACE_READERS = DEFAULT_TRACE_READERS;
+exports.PROGRAMMATIC_DIAGNOSTIC_SPECS = PROGRAMMATIC_DIAGNOSTIC_SPECS;
 exports.TraceReadError = TraceReadError;
 exports.agentInspectJsonlReader = agentInspectJsonlReader;
+exports.assertTraceInput = assertTraceInput;
 exports.detectTraceFormat = detectTraceFormat;
+exports.formatProgrammaticDiagnostic = formatProgrammaticDiagnostic;
 exports.openInferenceJsonReader = openInferenceJsonReader;
 exports.openTrace = openTrace;
+exports.openTraceDirectory = openTraceDirectory;
+exports.openTraceFile = openTraceFile;
+exports.openTraceText = openTraceText;
 exports.otlpJsonReader = otlpJsonReader;
 exports.readTrace = readTrace;
 //# sourceMappingURL=readers.cjs.map