agent-inspect 6.14.2 → 6.16.0

package/packages/cli/dist/index.cjs

@@ -6354,6 +6354,64 @@ var init_resolve2 = __esm({
   }
 });
 
+// packages/core/src/diagnostics/programmatic.ts
+function formatProgrammaticDiagnostic(code, detail) {
+  const spec = PROGRAMMATIC_DIAGNOSTIC_SPECS[code];
+  const summary = detail?.trim() ? detail.trim() : spec.summary;
+  return `${code}: ${summary} Remediation: ${spec.remediation}`;
+}
+var PROGRAMMATIC_DIAGNOSTIC_SPECS;
+var init_programmatic = __esm({
+  "packages/core/src/diagnostics/programmatic.ts"() {
+    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"]
+      }
+    });
+  }
+});
+
 // packages/core/src/safety/sensitive-key.ts
 function normalizeSensitiveKey(value) {
   return value.toLowerCase().replace(/[^a-z0-9_]/g, "");
@@ -6624,7 +6682,10 @@ function projectLogicalEvents(events) {
       if (originalParentId === event.eventId) {
         diagnostics.push({
           code: "AI_LOGICAL_SELF_PARENT_REMOVED",
-          message: `Removed self-parent edge on ${event.eventId}.`,
+          message: formatProgrammaticDiagnostic(
+            "AI_TRACE_RELATIONSHIP_SELF_PARENT",
+            `Removed self-parent edge on ${event.eventId}.`
+          ),
           eventIds: [event.eventId]
         });
         const { parentId: _drop, ...rest } = event;
@@ -6656,7 +6717,10 @@ function projectLogicalEvents(events) {
     if (nextParent === event.eventId) {
       diagnostics.push({
         code: "AI_LOGICAL_SELF_PARENT_REMOVED",
-        message: `Removed self-parent edge on ${event.eventId} (was ${originalParentId}).`,
+        message: formatProgrammaticDiagnostic(
+          "AI_TRACE_RELATIONSHIP_SELF_PARENT",
+          `Removed self-parent edge on ${event.eventId} (was ${originalParentId}).`
+        ),
         eventIds: [event.eventId]
       });
       const { parentId: _drop, ...rest } = event;
@@ -6720,6 +6784,7 @@ function pickString(record, keys) {
 }
 var init_logical_events = __esm({
   "packages/core/src/checks/logical-events.ts"() {
+    init_programmatic();
   }
 });
 
@@ -6748,7 +6813,11 @@ function summarizeSemanticParity(events) {
 }
 var init_trace_facts = __esm({
   "packages/core/src/checks/trace-facts.ts"() {
+    init_programmatic();
     init_logical_events();
+    formatProgrammaticDiagnostic(
+      "AI_TRACE_FACTS_INPUT_NOT_NORMALIZED"
+    );
   }
 });
 
@@ -6859,7 +6928,13 @@ function resolveSelectedRun(input3, runId) {
   if (input3.read.runs.length === 0) {
     return {
       diagnostics: [
-        diagnostic3("AI_CHECK_RUN_SELECTION_REQUIRED", "No runs are available for checks.")
+        diagnostic3(
+          "AI_CHECK_RUN_SELECTION_REQUIRED",
+          formatProgrammaticDiagnostic(
+            "AI_TRACE_CONTRACT_RUN_SELECTION_REQUIRED",
+            "No runs are available for checks."
+          )
+        )
       ]
     };
   }
@@ -6867,7 +6942,7 @@ function resolveSelectedRun(input3, runId) {
     diagnostics: [
       diagnostic3(
         "AI_CHECK_RUN_SELECTION_REQUIRED",
-        "Multiple runs are available; select a run before executing checks."
+        formatProgrammaticDiagnostic("AI_TRACE_CONTRACT_RUN_SELECTION_REQUIRED")
       )
     ]
   };
@@ -7596,7 +7671,7 @@ function createStructureCycleRule() {
               findings.push(
                 failFinding(
                   "structure.cycle",
-                  "Trace contains a parentId cycle.",
+                  formatProgrammaticDiagnostic("AI_TRACE_RELATIONSHIP_CYCLE"),
                   cycle.map((item) => eventEvidence(item, "parentId")),
                   "acyclic parentId graph",
                   cycle.map((item) => item.eventId).sort()
@@ -8163,11 +8238,13 @@ function runTraceChecks(input3, options = {}) {
 var SEVERITY_RANK, STATUS_RANK, CONFIDENCE_RANK, DEFAULT_SENSITIVE_KEYS, DEFAULT_RAW_CONTENT_KEYS, DEFAULT_SAFE_RAW_CONTENT_PATH_PREFIXES, SAFE_USAGE_LEAF_KEYS, DEFAULT_SECRET_PATTERNS;
 var init_checks2 = __esm({
   "packages/core/src/checks/index.ts"() {
+    init_programmatic();
     init_outcomes();
     init_sensitive_key();
     init_logical_events();
     init_logical_events();
     init_trace_facts();
+    init_programmatic();
     init_sensitive_key();
     init_contract();
     SEVERITY_RANK = {
@@ -8860,6 +8937,35 @@ var init_tree_bridge = __esm({
     init_to_inspect_event();
   }
 });
+function isTraceInput(input3) {
+  if (typeof input3 !== "object" || input3 === null || Array.isArray(input3)) {
+    return false;
+  }
+  const record = input3;
+  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(input3) {
+  if (isTraceInput(input3)) 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 {
@@ -10006,6 +10112,7 @@ function mapOtlpEventsToPersisted(document) {
   };
 }
 async function detectTraceFormat(input3, options = {}) {
+  assertTraceInput(input3);
   const readers = options.readers ?? DEFAULT_TRACE_READERS;
   if (options.format !== void 0) {
     const reader = findReaderByFormat(options.format, readers);
@@ -10102,19 +10209,20 @@ async function detectTraceFormat(input3, options = {}) {
   };
 }
 async function readTrace(input3, options = {}) {
+  assertTraceInput(input3);
   const readers = options.readers ?? DEFAULT_TRACE_READERS;
   const detection = await detectTraceFormat(input3, 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
     );
   }
@@ -10122,7 +10230,10 @@ async function readTrace(input3, 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
     );
   }
@@ -10151,12 +10262,13 @@ async function readTrace(input3, options = {}) {
 function openTrace(input3, options = {}) {
   return readTrace(input3, options);
 }
-var DEFAULT_MAX_TRACE_INPUT_BYTES, MIN_DETECTION_CONFIDENCE, AMBIGUOUS_CONFIDENCE_DELTA, resolvedInputCache, OPENINFERENCE_READER_FORMAT, OTLP_READER_FORMAT, OPENINFERENCE_SPAN_KEYS, OPENINFERENCE_SENSITIVE_ATTRIBUTE_KEYS, OTLP_SPAN_KEYS, TraceReadError, openInferenceJsonReader, otlpJsonReader, agentInspectJsonlReader, DEFAULT_TRACE_READERS;
+var DEFAULT_MAX_TRACE_INPUT_BYTES, MIN_DETECTION_CONFIDENCE, AMBIGUOUS_CONFIDENCE_DELTA, resolvedInputCache, OPENINFERENCE_READER_FORMAT, OTLP_READER_FORMAT, OPENINFERENCE_SPAN_KEYS, OPENINFERENCE_SENSITIVE_ATTRIBUTE_KEYS, OTLP_SPAN_KEYS, TraceReadError, TRACE_INPUT_INVALID_MESSAGE, openInferenceJsonReader, otlpJsonReader, agentInspectJsonlReader, DEFAULT_TRACE_READERS;
 var init_readers = __esm({
   "packages/core/src/readers/index.ts"() {
     init_read_trace();
     init_from_trace_event();
     init_tree_bridge();
+    init_programmatic();
     DEFAULT_MAX_TRACE_INPUT_BYTES = 10 * 1024 * 1024;
     MIN_DETECTION_CONFIDENCE = 0.5;
     AMBIGUOUS_CONFIDENCE_DELTA = 0.05;
@@ -10230,6 +10342,9 @@ var init_readers = __esm({
         this.warnings = warnings;
       }
     };
+    TRACE_INPUT_INVALID_MESSAGE = formatProgrammaticDiagnostic(
+      "AI_TRACE_INPUT_INVALID"
+    );
     openInferenceJsonReader = {
       format: OPENINFERENCE_READER_FORMAT,
       name: "OpenInference JSON",
@@ -12370,7 +12485,7 @@ var init_src = __esm({
 });
 
 // package.json
-var version = "6.14.2";
+var version = "6.16.0";
 
 // packages/cli/src/list.ts
 init_advanced();
@@ -12700,6 +12815,7 @@ init_tree_bridge();
 
 // packages/core/src/entries/readers.ts
 init_readers();
+init_programmatic();
 
 // packages/cli/src/read-run.ts
 function mapReaderFormat(format) {