agent-inspect 6.14.2 → 6.16.0

package/packages/core/dist/index-B9ZGvUVL.d.ts

@@ -0,0 +1,102 @@
+import { a as InspectRunTree } from './inspect-event-DRthdZlf.js';
+import { P as PersistedInspectEvent } from './persisted-inspect-event-BVucFVrP.js';
+
+type TraceInput = {
+    type: "file";
+    path: string;
+} | {
+    type: "directory";
+    path: string;
+} | {
+    type: "string";
+    content: string;
+} | {
+    type: "buffer";
+    content: Buffer;
+} | {
+    type: "stdin";
+};
+type TraceReadWarningSeverity = "info" | "warning" | "error";
+interface TraceReadWarning {
+    code: string;
+    message: string;
+    severity?: TraceReadWarningSeverity;
+    sourceFile?: string;
+    line?: number;
+    field?: string;
+}
+interface TraceReadResult {
+    format: string;
+    events: PersistedInspectEvent[];
+    runs: InspectRunTree[];
+    warnings: TraceReadWarning[];
+    unsupportedFields: string[];
+    sourceFiles: string[];
+}
+interface TraceFormatCandidate {
+    format: string;
+    confidence: number;
+    readerName?: string;
+    description?: string;
+    warnings?: TraceReadWarning[];
+}
+type TraceFormatDetectionStatus = "detected" | "ambiguous" | "unsupported";
+interface TraceFormatDetectionResult {
+    status: TraceFormatDetectionStatus;
+    format?: string;
+    candidates: TraceFormatCandidate[];
+    warnings: TraceReadWarning[];
+}
+interface TraceReaderDetectOptions {
+    format?: string;
+}
+interface TraceReaderReadOptions {
+    format?: string;
+}
+interface TraceReader {
+    readonly format: string;
+    readonly name?: string;
+    detect(input: TraceInput, options?: TraceReaderDetectOptions): TraceFormatCandidate | undefined | Promise<TraceFormatCandidate | undefined>;
+    read(input: TraceInput, options?: TraceReaderReadOptions): TraceReadResult | Promise<TraceReadResult>;
+}
+interface TraceReadOptions {
+    format?: string;
+    readers?: readonly TraceReader[];
+}
+type TraceReadErrorCode = "unsupported_format" | "ambiguous_format" | "reader_failed" | "invalid_input";
+declare class TraceReadError extends Error {
+    readonly code: TraceReadErrorCode;
+    readonly warnings: TraceReadWarning[];
+    constructor(code: TraceReadErrorCode, message: string, warnings?: TraceReadWarning[]);
+}
+/**
+ * Runtime guard for structured TraceInput. Never throws WeakMap key errors for bare strings.
+ */
+declare function assertTraceInput(input: unknown): asserts input is TraceInput;
+declare const openInferenceJsonReader: TraceReader;
+declare const otlpJsonReader: TraceReader;
+declare const agentInspectJsonlReader: TraceReader;
+declare const DEFAULT_TRACE_READERS: readonly TraceReader[];
+declare function detectTraceFormat(input: TraceInput, options?: TraceReadOptions): Promise<TraceFormatDetectionResult>;
+declare function readTrace(input: TraceInput, options?: TraceReadOptions): Promise<TraceReadResult>;
+declare function openTrace(input: TraceInput, options?: TraceReadOptions): Promise<TraceReadResult>;
+/**
+ * Open a single local trace file. Prefer this over passing a bare path string to `openTrace`.
+ *
+ * @experimental Additive convenience over `openTrace({ type: "file", path })`.
+ */
+declare function openTraceFile(filePath: string, options?: TraceReadOptions): Promise<TraceReadResult>;
+/**
+ * Open all `*.jsonl` files in a local directory (sorted, concatenated).
+ *
+ * @experimental Additive convenience over `openTrace({ type: "directory", path })`.
+ */
+declare function openTraceDirectory(dirPath: string, options?: TraceReadOptions): Promise<TraceReadResult>;
+/**
+ * Open an in-memory JSONL / supported text payload.
+ *
+ * @experimental Additive convenience over `openTrace({ type: "string", content })`.
+ */
+declare function openTraceText(content: string, options?: TraceReadOptions): Promise<TraceReadResult>;
+
+export { DEFAULT_TRACE_READERS as D, type TraceReadResult as T, type TraceReadWarning as a, type TraceFormatCandidate as b, type TraceFormatDetectionResult as c, type TraceFormatDetectionStatus as d, type TraceInput as e, TraceReadError as f, type TraceReadErrorCode as g, type TraceReadOptions as h, type TraceReadWarningSeverity as i, type TraceReader as j, type TraceReaderDetectOptions as k, type TraceReaderReadOptions as l, agentInspectJsonlReader as m, assertTraceInput as n, detectTraceFormat as o, openInferenceJsonReader as p, openTrace as q, openTraceDirectory as r, openTraceFile as s, openTraceText as t, otlpJsonReader as u, readTrace as v };

package/packages/core/dist/{index-D9HBequ_.d.ts → index-BsCcOKxy.d.ts}

@@ -1,4 +1,4 @@
-import { TraceReadResult, TraceReadWarning } from './readers.js';
+import { T as TraceReadResult, a as TraceReadWarning } from './index-B9ZGvUVL.js';
 import { a as InspectRunTree, b as InspectNode, A as AttributionConfidence } from './inspect-event-DRthdZlf.js';
 import { P as PersistedInspectEvent } from './persisted-inspect-event-BVucFVrP.js';
 import { O as ObservedOutcomeStatus } from './types-B562HgN_.js';

package/packages/core/dist/{index-BY6XZ5aG.d.cts → index-Xk9X-yjY.d.cts}

@@ -1,4 +1,4 @@
-import { TraceReadResult, TraceReadWarning } from './readers.cjs';
+import { T as TraceReadResult, a as TraceReadWarning } from './index-B259NKkH.cjs';
 import { a as InspectRunTree, b as InspectNode, A as AttributionConfidence } from './inspect-event-DRthdZlf.cjs';
 import { P as PersistedInspectEvent } from './persisted-inspect-event-CVZWZldL.cjs';
 import { O as ObservedOutcomeStatus } from './types-B562HgN_.cjs';

package/packages/core/dist/readers.cjs

@@ -1181,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;
@@ -1255,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 {
@@ -2609,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);
@@ -2705,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
     );
   }
@@ -2725,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
     );
   }
@@ -2754,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