agent-inspect 1.8.0 → 1.9.0

package/packages/cli/dist/index.mjs

@@ -12,7 +12,7 @@ import process2, { stdin, stdout } from 'process';
 import tty from 'tty';
 
 // package.json
-var version = "1.8.0";
+var version = "1.9.0";
 
 // packages/core/src/types.ts
 var STEP_TYPES = [
@@ -4058,6 +4058,151 @@ ${attrsSection}
   };
 }
 
+// packages/core/src/explain.ts
+function flatten(nodes, out = []) {
+  for (const node of nodes) {
+    out.push({ node, index: out.length + 1 });
+    flatten(node.children, out);
+  }
+  return out;
+}
+function redactValue(redactor, key, value) {
+  return redactor.redactValue(key, value);
+}
+function fact(id, label, value, redactor) {
+  return {
+    id,
+    label,
+    value: redactValue(redactor, id.split(".").at(-1) ?? id, value),
+    source: "trace",
+    confidence: "observed"
+  };
+}
+function topKinds(run) {
+  return Object.entries(run.metadata.kinds).filter(([, count]) => count > 0).sort((a, b) => {
+    if (b[1] !== a[1]) return b[1] - a[1];
+    return a[0].localeCompare(b[0]);
+  }).slice(0, 5).map(([kind, count]) => `${kind}:${count}`);
+}
+function countErrorNodes(nodes) {
+  return nodes.filter((entry) => entry.node.event.status === "error").length;
+}
+function slowestNode(nodes) {
+  return nodes.filter((entry) => entry.node.event.durationMs !== void 0).sort((a, b) => {
+    const delta = (b.node.event.durationMs ?? 0) - (a.node.event.durationMs ?? 0);
+    return delta !== 0 ? delta : a.index - b.index;
+  })[0];
+}
+function attributeFacts(nodes, redactor) {
+  const facts = [];
+  for (const entry of nodes) {
+    const attrs = entry.node.event.attributes;
+    if (attrs === void 0) continue;
+    for (const key of Object.keys(attrs).sort()) {
+      facts.push({
+        id: `node.${entry.index}.attributes.${key}`,
+        label: `${entry.node.event.name} attribute ${key}`,
+        value: redactValue(redactor, key, attrs[key]),
+        source: "trace",
+        confidence: "observed"
+      });
+      if (facts.length >= 8) return facts;
+    }
+  }
+  return facts;
+}
+function buildFacts(run, redactor) {
+  const nodes = flatten(run.children);
+  const facts = [
+    fact("run.id", "Run id", run.runId, redactor),
+    fact("run.name", "Run name", run.name ?? run.runId, redactor),
+    fact("run.status", "Run status", run.status ?? "unknown", redactor),
+    fact("run.totalEvents", "Total events", run.metadata.totalEvents, redactor),
+    fact("run.stepCount", "Top-level step count", run.children.length, redactor),
+    fact("run.nodeCount", "Total node count", nodes.length, redactor),
+    fact("run.errorNodeCount", "Error node count", countErrorNodes(nodes), redactor),
+    fact("run.kinds", "Observed kind mix", topKinds(run), redactor)
+  ];
+  if (run.durationMs !== void 0) {
+    facts.push(fact("run.durationMs", "Run duration milliseconds", run.durationMs, redactor));
+  }
+  const slowest = slowestNode(nodes);
+  if (slowest !== void 0) {
+    facts.push(
+      fact("run.slowestNode", "Slowest observed node", {
+        name: slowest.node.event.name,
+        kind: slowest.node.event.kind,
+        durationMs: slowest.node.event.durationMs
+      }, redactor)
+    );
+  }
+  facts.push(...attributeFacts(nodes, redactor));
+  return facts;
+}
+function buildInferences(run, facts) {
+  const inferences = [];
+  const errorFact = facts.find((item) => item.id === "run.errorNodeCount");
+  const kindFact = facts.find((item) => item.id === "run.kinds");
+  const durationFact = facts.find((item) => item.id === "run.durationMs");
+  const errorNodeCount = typeof errorFact?.value === "number" ? errorFact.value : 0;
+  if (run.status === "error" || errorNodeCount > 0) {
+    inferences.push({
+      id: "outcome.error",
+      label: "Outcome",
+      text: "The run recorded an error status or at least one error node.",
+      evidence: ["run.status", "run.errorNodeCount"],
+      confidence: "deterministic"
+    });
+  } else if (run.status === "ok") {
+    inferences.push({
+      id: "outcome.success",
+      label: "Outcome",
+      text: "The run completed without observed error nodes.",
+      evidence: ["run.status", "run.errorNodeCount"],
+      confidence: "deterministic"
+    });
+  }
+  if (kindFact !== void 0) {
+    inferences.push({
+      id: "shape.kind-mix",
+      label: "Trace shape",
+      text: "The explanation is based on the observed event kind mix, not generated content.",
+      evidence: [kindFact.id],
+      confidence: "deterministic"
+    });
+  }
+  if (durationFact !== void 0) {
+    inferences.push({
+      id: "timing.duration",
+      label: "Timing",
+      text: "Timing claims are limited to persisted duration fields in the trace.",
+      evidence: [durationFact.id],
+      confidence: "deterministic"
+    });
+  }
+  return inferences;
+}
+function buildLocalExplanation(run, options = {}) {
+  const redactionProfile = options.redactionProfile ?? "local";
+  const resolved = resolveRedactionProfile(redactionProfile);
+  const redactor = new Redactor({ extraKeys: resolved.extraKeys });
+  const mode = options.mode ?? "local";
+  const facts = buildFacts(run, redactor);
+  return {
+    mode,
+    runId: String(redactValue(redactor, "runId", run.runId)),
+    ...run.name !== void 0 ? { name: String(redactValue(redactor, "name", run.name)) } : {},
+    ...run.status !== void 0 ? { status: run.status } : {},
+    redactionProfile,
+    facts,
+    inferences: mode === "dry-run" ? [] : buildInferences(run, facts),
+    notes: [
+      "Generated locally without provider or network calls.",
+      "Facts are observed from normalized trace data; inferences are deterministic labels."
+    ]
+  };
+}
+
 // packages/core/src/stats.ts
 function percentile(sorted, p) {
   if (sorted.length === 0) return void 0;
@@ -8947,9 +9092,164 @@ async function readStdin(stdin) {
   }
   return content;
 }
+function isMissingFileError2(error) {
+  return error !== null && typeof error === "object" && "code" in error && error.code === "ENOENT";
+}
+async function inputFromTarget(target, options, stdin) {
+  if (target === "-") {
+    return { type: "string", content: await readStdin(stdin) };
+  }
+  try {
+    const stats2 = await stat(target);
+    if (stats2.isDirectory()) return { type: "directory", path: target };
+    return { type: "file", path: target };
+  } catch (error) {
+    if (!isMissingFileError2(error)) throw error;
+  }
+  const runPath = getTraceFilePath(target, resolveTraceDir({ dir: options.dir }));
+  const stats = await stat(runPath);
+  if (stats.isDirectory()) return { type: "directory", path: runPath };
+  return { type: "file", path: runPath };
+}
+
+// packages/cli/src/explain.ts
+function parseRedactionProfile3(value) {
+  const profile = (value ?? "local").trim().toLowerCase();
+  if (profile === "local" || profile === "share" || profile === "strict") {
+    return profile;
+  }
+  throw new Error(
+    `Unsupported --redaction-profile "${value ?? ""}". Use local, share, or strict.`
+  );
+}
+function selectRun(result, runId) {
+  if (runId !== void 0) {
+    return result.runs.find((run) => run.runId === runId);
+  }
+  return result.runs.length === 1 ? result.runs[0] : void 0;
+}
+function printMultipleRuns(result) {
+  console.error(
+    `Trace contains ${result.runs.length} runs. Re-run with --run <run-id>.`
+  );
+  for (const run of result.runs) {
+    console.error(`- ${run.runId}${run.name !== void 0 ? ` name=${run.name}` : ""}`);
+  }
+}
+function renderHuman(result) {
+  const lines = [
+    `Explain: ${result.name ?? result.runId}`,
+    `Mode: ${result.mode}`,
+    `Status: ${result.status ?? "unknown"}`,
+    `Redaction: ${result.redactionProfile}`,
+    "",
+    "Facts:"
+  ];
+  for (const fact2 of result.facts) {
+    lines.push(`- ${fact2.id}: ${JSON.stringify(fact2.value)}`);
+  }
+  lines.push("", "Inferences:");
+  if (result.inferences.length === 0) {
+    lines.push("- none");
+  } else {
+    for (const inference of result.inferences) {
+      lines.push(`- ${inference.label}: ${inference.text}`);
+    }
+  }
+  lines.push("", "Notes:");
+  for (const note of result.notes) {
+    lines.push(`- ${note}`);
+  }
+  return lines.join("\n");
+}
+function writeJson(result) {
+  console.log(JSON.stringify(result, null, 2));
+}
+function rejectProvider(provider, json) {
+  process.exitCode = 1;
+  const message = `Provider explain is not implemented in this build: ${provider}. Use --dry-run to inspect the redacted local payload.`;
+  if (json) {
+    writeJson({
+      ok: false,
+      error: { code: "PROVIDER_NOT_IMPLEMENTED", message }
+    });
+    return;
+  }
+  console.error(message);
+}
+async function explainCommand(target, options = {}, stdin = process.stdin) {
+  if (options.provider !== void 0) {
+    rejectProvider(options.provider, options.json);
+    return;
+  }
+  let redactionProfile;
+  try {
+    redactionProfile = parseRedactionProfile3(options.redactionProfile);
+  } catch (error) {
+    process.exitCode = 1;
+    console.error(error instanceof Error ? error.message : String(error));
+    return;
+  }
+  try {
+    const input3 = await inputFromTarget(target, options, stdin);
+    const read = await openTrace(input3, {
+      ...options.format !== void 0 ? { format: options.format } : {}
+    });
+    const selected = selectRun(read, options.run);
+    if (selected === void 0) {
+      process.exitCode = 1;
+      const message = options.run !== void 0 ? `Run not found: ${options.run}` : `Trace contains ${read.runs.length} runs. Specify --run <run-id>.`;
+      if (options.json) {
+        writeJson({ ok: false, error: { message }, runs: read.runs });
+      } else if (options.run !== void 0) {
+        console.error(message);
+      } else {
+        printMultipleRuns(read);
+      }
+      return;
+    }
+    const mode = options.dryRun ? "dry-run" : "local";
+    const explanation = buildLocalExplanation(selected, {
+      mode,
+      redactionProfile
+    });
+    if (options.json) {
+      writeJson({
+        ok: true,
+        format: read.format,
+        sourceFiles: read.sourceFiles,
+        warnings: read.warnings,
+        unsupportedFields: read.unsupportedFields,
+        explanation
+      });
+      return;
+    }
+    console.log(renderHuman(explanation));
+  } catch (error) {
+    process.exitCode = 1;
+    const message = error instanceof Error ? error.message : String(error);
+    const code = error instanceof TraceReadError ? error.code : void 0;
+    if (options.json) {
+      writeJson({
+        ok: false,
+        error: { ...code !== void 0 ? { code } : {}, message }
+      });
+      return;
+    }
+    console.error(message);
+  }
+}
+async function readStdin2(stdin) {
+  stdin.setEncoding("utf8");
+  let content = "";
+  for await (const chunk of stdin) {
+    content += typeof chunk === "string" ? chunk : String(chunk);
+  }
+  return content;
+}
 async function inputFromPathOrStdin(input3, stdin) {
   if (input3 === void 0 || input3 === "-") {
-    return { type: "string", content: await readStdin(stdin) };
+    return { type: "string", content: await readStdin2(stdin) };
   }
   const stats = await stat(input3);
   if (stats.isDirectory()) return { type: "directory", path: input3 };
@@ -9000,13 +9300,13 @@ function printRun(result, run) {
     printNode(node, 0);
   }
 }
-function selectRun(result, runId) {
+function selectRun2(result, runId) {
   if (runId !== void 0) {
     return result.runs.find((run) => run.runId === runId);
   }
   return result.runs.length === 1 ? result.runs[0] : void 0;
 }
-function printMultipleRuns(result) {
+function printMultipleRuns2(result) {
   console.error(
     `Trace contains ${result.runs.length} runs. Re-run with --run <run-id>.`
   );
@@ -9020,7 +9320,7 @@ function printMultipleRuns(result) {
     console.error(`- ${bits.join(" ")}`);
   }
 }
-function writeJson(output2) {
+function writeJson2(output2) {
   console.log(JSON.stringify(output2, null, 2));
 }
 async function openCommand(input3, options = {}, stdin = process.stdin) {
@@ -9029,12 +9329,12 @@ async function openCommand(input3, options = {}, stdin = process.stdin) {
     const result = await openTrace(traceInput, {
       ...options.format !== void 0 ? { format: options.format } : {}
     });
-    const selected = selectRun(result, options.run);
+    const selected = selectRun2(result, options.run);
     if (selected === void 0) {
       process.exitCode = 1;
       const message = options.run !== void 0 ? `Run not found: ${options.run}` : `Trace contains ${result.runs.length} runs. Specify --run <run-id>.`;
       if (options.json) {
-        writeJson({
+        writeJson2({
           format: result.format,
           sourceFiles: result.sourceFiles,
           warnings: result.warnings,
@@ -9045,12 +9345,12 @@ async function openCommand(input3, options = {}, stdin = process.stdin) {
       } else if (options.run !== void 0) {
         console.error(message);
       } else {
-        printMultipleRuns(result);
+        printMultipleRuns2(result);
       }
       return;
     }
     if (options.json) {
-      writeJson({
+      writeJson2({
         format: result.format,
         sourceFiles: result.sourceFiles,
         warnings: result.warnings,
@@ -9070,7 +9370,7 @@ async function openCommand(input3, options = {}, stdin = process.stdin) {
     const code = error instanceof TraceReadError ? error.code : void 0;
     const warnings = error instanceof TraceReadError ? error.warnings : [];
     if (options.json) {
-      writeJson({
+      writeJson2({
         warnings,
         error: { ...code !== void 0 ? { code } : {}, message }
       });
@@ -9174,7 +9474,7 @@ function errorResult(input3, diagnostics, selectedRun) {
 function flattenNodes(nodes) {
   return nodes.flatMap((node) => [node, ...flattenNodes(node.children)]);
 }
-function buildFacts(input3, selectedRun) {
+function buildFacts2(input3, selectedRun) {
   const scopedRuns = selectedRun ? [selectedRun] : input3.read.runs;
   const scopedRunIds = new Set(scopedRuns.map((run) => run.runId));
   const scopedEvents = selectedRun === void 0 ? input3.read.events : input3.read.events.filter((event) => scopedRunIds.has(event.runId));
@@ -10182,7 +10482,7 @@ function createBaselineRegressionRule(options) {
           )
         ];
       }
-      const baselineFacts = buildFacts(options.baseline, baselineSelection.run);
+      const baselineFacts = buildFacts2(options.baseline, baselineSelection.run);
       const baselineContext = {
         ...baselineFacts,
         selectedRun: baselineSelection.run,
@@ -10301,7 +10601,7 @@ function runTraceChecks(input3, options = {}) {
   if (rules.diagnostics.length > 0) {
     return errorResult(input3, rules.diagnostics, selected.run);
   }
-  const facts = buildFacts(input3, selected.run);
+  const facts = buildFacts2(input3, selected.run);
   const context = {
     ...facts,
     ...selected.run ? { selectedRun: selected.run } : {},
@@ -10336,33 +10636,6 @@ function runTraceChecks(input3, options = {}) {
     diagnostics
   };
 }
-async function readStdin2(stdin) {
-  stdin.setEncoding("utf8");
-  let content = "";
-  for await (const chunk of stdin) {
-    content += typeof chunk === "string" ? chunk : String(chunk);
-  }
-  return content;
-}
-function isMissingFileError2(error) {
-  return error !== null && typeof error === "object" && "code" in error && error.code === "ENOENT";
-}
-async function inputFromTarget(target, options, stdin) {
-  if (target === "-") {
-    return { type: "string", content: await readStdin2(stdin) };
-  }
-  try {
-    const stats2 = await stat(target);
-    if (stats2.isDirectory()) return { type: "directory", path: target };
-    return { type: "file", path: target };
-  } catch (error) {
-    if (!isMissingFileError2(error)) throw error;
-  }
-  const runPath = getTraceFilePath(target, resolveTraceDir({ dir: options.dir }));
-  const stats = await stat(runPath);
-  if (stats.isDirectory()) return { type: "directory", path: runPath };
-  return { type: "file", path: runPath };
-}
 
 // packages/cli/src/check.ts
 var DEFAULT_SELECT = ["run.status"];
@@ -10809,7 +11082,7 @@ function stable3(value) {
     Object.keys(record).sort((a, b) => a.localeCompare(b)).map((key) => [key, stable3(record[key])])
   );
 }
-function writeJson2(value) {
+function writeJson3(value) {
   return `${JSON.stringify(stable3(value), null, 2)}
 `;
 }
@@ -10827,7 +11100,7 @@ function increment(record, key) {
   const label = key && key.trim() !== "" ? key : "unknown";
   record[label] = (record[label] ?? 0) + 1;
 }
-function selectRun2(read, runId) {
+function selectRun3(read, runId) {
   if (runId !== void 0) {
     return read.runs.find((run) => run.runId === runId);
   }
@@ -10975,7 +11248,7 @@ async function artifactsCommand(target, options = {}, stdin = process.stdin) {
     process.exitCode = 1;
     return;
   }
-  const selectedRun = selectRun2(read, options.run);
+  const selectedRun = selectRun3(read, options.run);
   const check = runTraceChecks(
     { read },
     {
@@ -11012,12 +11285,12 @@ async function artifactsCommand(target, options = {}, stdin = process.stdin) {
   }
   const files = [];
   await mkdir(outputDir, { recursive: true });
-  await writeArtifact(outputDir, "trace.json", writeJson2(trace), files);
-  await writeArtifact(outputDir, "check.json", writeJson2(check), files);
+  await writeArtifact(outputDir, "trace.json", writeJson3(trace), files);
+  await writeArtifact(outputDir, "check.json", writeJson3(check), files);
   await writeArtifact(
     outputDir,
     "diff.json",
-    writeJson2(diff ?? { status: "not_requested", findings: [], diagnostics: [] }),
+    writeJson3(diff ?? { status: "not_requested", findings: [], diagnostics: [] }),
     files
   );
   await writeArtifact(outputDir, "summary.md", renderMarkdown(trace, check, diff), files);
@@ -11047,9 +11320,9 @@ ${renderMarkdown(trace, check, diff)}`, "utf-8");
     ...summaryTarget !== void 0 && summaryTarget.trim() !== "" ? { githubSummary: path10.resolve(summaryTarget) } : {},
     note: NOTE
   };
-  await writeFile(path10.join(outputDir, "manifest.json"), writeJson2(manifest), "utf-8");
+  await writeFile(path10.join(outputDir, "manifest.json"), writeJson3(manifest), "utf-8");
   if (options.json === true) {
-    console.log(writeJson2(manifest).trimEnd());
+    console.log(writeJson3(manifest).trimEnd());
   } else {
     console.log(`Wrote AgentInspect artifacts to ${outputDir}`);
     console.log(`Status: ${manifest.status}`);
@@ -11268,6 +11541,23 @@ function createCliProgram() {
   ).action((runId, opts) => {
     runCommand(() => reportCommand(runId, opts));
   });
+  program.command("explain").description("Explain a local trace with deterministic facts (no provider calls)").argument("<trace-path-or-run-id>", "trace file, directory, stdin -, or run id").option("--dir <path>", "trace directory for run-id lookup").addOption(
+    new Option("--format <format>", "trace input format").choices([
+      "agent-inspect-jsonl",
+      "openinference-json",
+      "otlp-json"
+    ])
+  ).option("--run <run-id>", "select a run when the trace contains multiple runs").option("--dry-run", "emit only the local facts payload that a provider could receive").option(
+    "--provider <provider>",
+    "reserved for explicit provider explain; currently rejected without network calls"
+  ).option("--json", "print deterministic JSON explanation result").addOption(
+    new Option(
+      "--redaction-profile <profile>",
+      "redaction profile for explanation payload: local, share, strict (default: local)"
+    ).choices(["local", "share", "strict"])
+  ).action((target, opts) => {
+    runCommand(() => explainCommand(target, opts));
+  });
   return program;
 }
 function isPrimaryModule() {