agent-inspect 6.31.9 → 6.31.11

package/packages/core/dist/exporters.mjs

@@ -1,4 +1,4 @@
-import { buildRunWhatSummary, renderRunWhat, renderTimeline, buildRunTimeline } from './chunk-7YYS742B.mjs';
+import { buildRunWhatSummary, renderRunWhat, renderTimeline, buildRunTimeline } from './chunk-M3RJD3BP.mjs';
 import { summarizeObservedOutcomes, extractOutcomesFromTraceEvents, renderObservedOutcomesMarkdown, renderObservedOutcomesHtml } from './chunk-N5PZAI6Q.mjs';
 import { escapeHtml, flattenTree, safeString, compactAttributes, stableJson, escapeMarkdown, zeroKinds } from './chunk-CAWPF22J.mjs';
 export { compactAttributes, escapeHtml, escapeMarkdown, flattenTree, safeString, stableJson, summarizeTree } from './chunk-CAWPF22J.mjs';

package/packages/core/dist/{index-EQihlEei.d.cts → index-DACU4Dy1.d.cts}

@@ -1260,11 +1260,23 @@ interface TraceCheckRuleExecution {
  * @experimental  Available through `agent-inspect/checks`. Additive changes may ship in minor releases; breaking changes require a future major.
  */
 interface TraceCheckSummary {
+    /** Finding count with status pass. */
     passed: number;
+    /** Finding count with status fail and severity error. */
     failed: number;
+    /** Finding count with warning status or severity. */
     warnings: number;
+    /** Diagnostic count with severity error. */
     errors: number;
     rulesEvaluated: number;
+    /**
+     * Rule-status totals from `ruleExecutions` (independent of finding counts).
+     * @experimental Additive; always populated by `runTraceChecks` / contract evaluation.
+     */
+    rulesPassed: number;
+    rulesWarning: number;
+    rulesFailed: number;
+    rulesError: number;
 }
 /**
  * Experimental trace-check result.

package/packages/core/dist/{index-CgOAGuM5.d.ts → index-b4tIGrzq.d.ts}

@@ -1260,11 +1260,23 @@ interface TraceCheckRuleExecution {
  * @experimental  Available through `agent-inspect/checks`. Additive changes may ship in minor releases; breaking changes require a future major.
  */
 interface TraceCheckSummary {
+    /** Finding count with status pass. */
     passed: number;
+    /** Finding count with status fail and severity error. */
     failed: number;
+    /** Finding count with warning status or severity. */
     warnings: number;
+    /** Diagnostic count with severity error. */
     errors: number;
     rulesEvaluated: number;
+    /**
+     * Rule-status totals from `ruleExecutions` (independent of finding counts).
+     * @experimental Additive; always populated by `runTraceChecks` / contract evaluation.
+     */
+    rulesPassed: number;
+    rulesWarning: number;
+    rulesFailed: number;
+    rulesError: number;
 }
 /**
  * Experimental trace-check result.

package/packages/core/dist/index.cjs

@@ -2072,6 +2072,70 @@ function runWithStepContext(stepId, fn) {
   });
 }
 
+// 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"]
+  },
+  AI_TRACE_CONTRACT_INPUT_INVALID: {
+    code: "AI_TRACE_CONTRACT_INPUT_INVALID",
+    summary: "evaluateTraceContract expects ({ read }, contract) or use evaluateTraceContractRead(read, contract).",
+    remediation: "Pass TraceCheckInput as the first argument: evaluateTraceContract({ read }, contract).",
+    relatedCodes: ["AI_CHECK_INVALID_ARGUMENTS"]
+  },
+  AI_INSPECT_RUN_UNSUPPORTED_OPTION: {
+    code: "AI_INSPECT_RUN_UNSUPPORTED_OPTION",
+    summary: 'inspectRun does not accept a "writer" option.',
+    remediation: "Use createInspector({ writer }) then inspector.run(...). inspectRun persists via the global JSONL path (schema 0.1)."
+  }
+});
+function formatProgrammaticDiagnostic(code, detail) {
+  const spec = PROGRAMMATIC_DIAGNOSTIC_SPECS[code];
+  const summary = spec.summary;
+  return `${code}: ${summary} Remediation: ${spec.remediation}`;
+}
+
 // node_modules/.pnpm/chalk@5.6.2/node_modules/chalk/source/vendor/ansi-styles/index.js
 var ANSI_BACKGROUND_OFFSET = 10;
 var wrapAnsi16 = (offset = 0) => (code) => `\x1B[${code + offset}m`;
@@ -2702,6 +2766,18 @@ function resolveTraceDir(options = {}) {
 }
 
 // packages/core/src/inspect-run.ts
+var INSPECT_RUN_UNSUPPORTED_OPTION_KEYS = ["writer"];
+function warnUnsupportedInspectRunOptions(options) {
+  if (typeof options !== "object" || options === null || Array.isArray(options)) {
+    return;
+  }
+  const record = options;
+  for (const key of INSPECT_RUN_UNSUPPORTED_OPTION_KEYS) {
+    if (Object.prototype.hasOwnProperty.call(record, key) && record[key] !== void 0) {
+      warn(formatProgrammaticDiagnostic("AI_INSPECT_RUN_UNSUPPORTED_OPTION"));
+    }
+  }
+}
 function normalizeRunName(name) {
   if (typeof name !== "string" || name.trim() === "") {
     return "unnamed-run";
@@ -2719,6 +2795,7 @@ async function inspectRun(name, fn, options) {
   if (typeof fn !== "function") {
     throw new TypeError("inspectRun requires `fn` to be a function");
   }
+  warnUnsupportedInspectRunOptions(options);
   if (options?.enabled === false) {
     return Promise.resolve(fn());
   }