agent-inspect 3.0.0 → 3.2.0

package/packages/cli/dist/index.mjs

@@ -5,15 +5,16 @@ import { fileURLToPath, pathToFileURL } from 'url';
 import { Command, Option } from 'commander';
 import { AsyncLocalStorage } from 'async_hooks';
 import crypto, { webcrypto, createHash } from 'crypto';
-import { unlink, stat, mkdir, writeFile, appendFile, readdir, readFile, access, open } from 'fs/promises';
+import { unlink, stat, mkdir, writeFile, appendFile, readdir, readFile, access, open, constants } from 'fs/promises';
 import os from 'os';
-import process2, { stdin, stdout } from 'process';
+import process3, { stdin, stdout } from 'process';
 import tty from 'tty';
 import { createInterface } from 'readline';
 import { createServer } from 'http';
+import { createRequire } from 'module';
 
 // package.json
-var version = "3.0.0";
+var version = "3.2.0";
 
 // packages/core/src/correlation-metadata.ts
 var TRACE_CORRELATION_KEYS = [
@@ -1177,13 +1178,13 @@ function assembleStyles() {
 }
 var ansiStyles = assembleStyles();
 var ansi_styles_default = ansiStyles;
-function hasFlag(flag, argv = globalThis.Deno ? globalThis.Deno.args : process2.argv) {
+function hasFlag(flag, argv = globalThis.Deno ? globalThis.Deno.args : process3.argv) {
   const prefix = flag.startsWith("-") ? "" : flag.length === 1 ? "-" : "--";
   const position = argv.indexOf(prefix + flag);
   const terminatorPosition = argv.indexOf("--");
   return position !== -1 && (terminatorPosition === -1 || position < terminatorPosition);
 }
-var { env } = process2;
+var { env } = process3;
 var flagForceColor;
 if (hasFlag("no-color") || hasFlag("no-colors") || hasFlag("color=false") || hasFlag("color=never")) {
   flagForceColor = 0;
@@ -1239,7 +1240,7 @@ function _supportsColor(haveStream, { streamIsTTY, sniffFlags = true } = {}) {
   if (env.TERM === "dumb") {
     return min;
   }
-  if (process2.platform === "win32") {
+  if (process3.platform === "win32") {
     const osRelease = os.release().split(".");
     if (Number(osRelease[0]) >= 10 && Number(osRelease[2]) >= 10586) {
       return Number(osRelease[2]) >= 14931 ? 3 : 2;
@@ -3059,12 +3060,12 @@ function buildCriticalPath(runs, handoffs) {
     handoffs.filter((edge) => edge.confidence === "explicit").map((edge) => edge.from)
   );
   const ordered = [...runs].sort(compareRuns);
-  const path16 = [];
+  const path18 = [];
   const visited = /* @__PURE__ */ new Set();
   const pushRun = (run, confidence, source) => {
     if (visited.has(run.runId)) return;
     visited.add(run.runId);
-    path16.push({
+    path18.push({
       runId: run.runId,
       name: run.name,
       startedAt: run.startedAt,
@@ -3089,7 +3090,7 @@ function buildCriticalPath(runs, handoffs) {
     const confidence = explicitTargets.has(run.runId) || explicitSources.has(run.runId) ? "explicit" : "correlated";
     pushRun(run, confidence, confidence === "explicit" ? "manual" : "inferred");
   }
-  return path16;
+  return path18;
 }
 function metaRunIdMatches(run, token, runById) {
   const meta = extractSessionWorkflowMetadata(run.metadata);
@@ -8332,13 +8333,13 @@ function pairSteps(left, right) {
   return pairs;
 }
 function compareLeafSteps(L, R, segments, opts, out) {
-  const path16 = buildPath(segments);
+  const path18 = buildPath(segments);
   if (L.name !== R.name) {
     out.push({
       kind: "structure",
       severity: "warning",
       message: "Step name differs",
-      path: path16,
+      path: path18,
       left: L.name,
       right: R.name
     });
@@ -8348,7 +8349,7 @@ function compareLeafSteps(L, R, segments, opts, out) {
       kind: "step-type",
       severity: "warning",
       message: "Step type differs",
-      path: path16,
+      path: path18,
       left: L.type,
       right: R.type
     });
@@ -8358,7 +8359,7 @@ function compareLeafSteps(L, R, segments, opts, out) {
       kind: "step-status",
       severity: "warning",
       message: "Step status differs",
-      path: path16,
+      path: path18,
       left: L.status,
       right: R.status
     });
@@ -8370,7 +8371,7 @@ function compareLeafSteps(L, R, segments, opts, out) {
       kind: "error",
       severity: "error",
       message: "Step error message differs",
-      path: path16,
+      path: path18,
       left: le || void 0,
       right: re || void 0
     });
@@ -8388,7 +8389,7 @@ function compareLeafSteps(L, R, segments, opts, out) {
         kind: "duration",
         severity: "info",
         message: "Step duration differs",
-        path: path16,
+        path: path18,
         left: ld,
         right: rd
       });
@@ -8401,7 +8402,7 @@ function compareLeafSteps(L, R, segments, opts, out) {
       kind: "metadata",
       severity: "info",
       message: "Step metadata differs",
-      path: path16,
+      path: path18,
       left: L.metadata,
       right: R.metadata
     });
@@ -8413,7 +8414,7 @@ function compareLeafSteps(L, R, segments, opts, out) {
       kind: "output",
       severity: "info",
       message: "Output preview differs",
-      path: path16,
+      path: path18,
       left: L.outputPreview,
       right: R.outputPreview
     });
@@ -8573,11 +8574,11 @@ function diffRuns(left, right, options) {
 }
 
 // packages/core/src/diff/renderer.ts
-function formatPath(path16) {
-  if (path16 === void 0 || path16.path.length === 0) {
+function formatPath(path18) {
+  if (path18 === void 0 || path18.path.length === 0) {
     return "(run)";
   }
-  return path16.path.map((s) => s.name).join(" > ");
+  return path18.path.map((s) => s.name).join(" > ");
 }
 function formatValue(v, verbose) {
   if (v === void 0) return "(undefined)";
@@ -9455,17 +9456,17 @@ function applyRule(rule, value, replacement) {
   }
   return value;
 }
-function childPath(path16, key) {
+function childPath(path18, key) {
   if (/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key)) {
-    return path16 ? `${path16}.${key}` : key;
+    return path18 ? `${path18}.${key}` : key;
   }
-  return `${path16 || "$"}[${JSON.stringify(key)}]`;
+  return `${path18 || "$"}[${JSON.stringify(key)}]`;
 }
-function indexPath(path16, index) {
-  return `${path16 || "$"}[${index}]`;
+function indexPath(path18, index) {
+  return `${path18 || "$"}[${index}]`;
 }
-function makeFinding(path16, detector, action, matchKind, severity = "warning", preview) {
-  return preview === void 0 ? { path: path16, detector, action, severity, matchKind } : { path: path16, detector, action, severity, matchKind, preview };
+function makeFinding(path18, detector, action, matchKind, severity = "warning", preview) {
+  return preview === void 0 ? { path: path18, detector, action, severity, matchKind } : { path: path18, detector, action, severity, matchKind, preview };
 }
 function createRedactionProfile(profile = "local") {
   switch (profile) {
@@ -9534,11 +9535,11 @@ var Redactor2 = class {
   #recordFinding(state, finding) {
     if (this.#collectFindings) state.findings.push(finding);
   }
-  #redactValue(value, key, path16, depth, state) {
+  #redactValue(value, key, path18, depth, state) {
     if (depth > this.#maxDepth) {
       this.#recordFinding(
         state,
-        makeFinding(path16, "structure.maxDepth", "truncate", "value", "warning")
+        makeFinding(path18, "structure.maxDepth", "truncate", "value", "warning")
       );
       return "[Truncated]";
     }
@@ -9547,19 +9548,19 @@ var Redactor2 = class {
       if (rule) {
         this.#recordFinding(
           state,
-          makeFinding(path16, `key.${rule.key}`, actionForRule(rule), "key", "warning")
+          makeFinding(path18, `key.${rule.key}`, actionForRule(rule), "key", "warning")
         );
         return applyRule(rule, value, this.#replacement);
       }
     }
     for (const detector of this.#detectors) {
-      const detections = detector.detect({ path: path16, key, value });
+      const detections = detector.detect({ path: path18, key, value });
       for (const detection of detections) {
         const action = detection.action ?? "replace";
         this.#recordFinding(
           state,
           makeFinding(
-            path16,
+            path18,
             detector.id,
             action,
             detection.matchKind ?? detector.matchKind ?? "custom",
@@ -9577,7 +9578,7 @@ var Redactor2 = class {
       const out = [];
       state.seen.set(value, out);
       value.forEach((item, index) => {
-        out[index] = this.#redactValue(item, void 0, indexPath(path16, index), depth + 1, state);
+        out[index] = this.#redactValue(item, void 0, indexPath(path18, index), depth + 1, state);
       });
       return out;
     }
@@ -9589,7 +9590,7 @@ var Redactor2 = class {
         out[entryKey] = this.#redactValue(
           entryValue,
           entryKey,
-          childPath(path16 === "$" ? "" : path16, entryKey),
+          childPath(path18 === "$" ? "" : path18, entryKey),
           depth + 1,
           state
         );
@@ -10461,7 +10462,7 @@ function stripPrefix(name, prefixes) {
   }
   return name;
 }
-function eventEvidence(event, path16) {
+function eventEvidence(event, path18) {
   return {
     runId: event.runId,
     eventId: event.eventId,
@@ -10471,7 +10472,7 @@ function eventEvidence(event, path16) {
     kind: event.kind,
     name: event.name,
     status: event.status,
-    ...path16 ? { path: path16 } : {}
+    ...path18 ? { path: path18 } : {}
   };
 }
 function runEvidence(run) {
@@ -10534,9 +10535,9 @@ function eventEndMs(event) {
 function normalizedKey(value) {
   return value.toLowerCase().replace(/[^a-z0-9_]/g, "");
 }
-function lastPathSegment(path16) {
-  const parts = path16.split(".");
-  return parts[parts.length - 1] ?? path16;
+function lastPathSegment(path18) {
+  const parts = path18.split(".");
+  return parts[parts.length - 1] ?? path18;
 }
 function valueType(value) {
   if (Array.isArray(value)) return "array";
@@ -10550,12 +10551,12 @@ function serializedByteLength(value) {
     return void 0;
   }
 }
-function pushValueEntries(entries, event, value, path16, key, depth = 0) {
-  entries.push({ event, path: path16, key, value });
+function pushValueEntries(entries, event, value, path18, key, depth = 0) {
+  entries.push({ event, path: path18, key, value });
   if (depth >= 8) return;
   if (Array.isArray(value)) {
     for (const [index, item] of value.entries()) {
-      pushValueEntries(entries, event, item, `${path16}.${index}`, String(index), depth + 1);
+      pushValueEntries(entries, event, item, `${path18}.${index}`, String(index), depth + 1);
     }
     return;
   }
@@ -10565,7 +10566,7 @@ function pushValueEntries(entries, event, value, path16, key, depth = 0) {
       entries,
       event,
       value[nestedKey],
-      `${path16}.${nestedKey}`,
+      `${path18}.${nestedKey}`,
       nestedKey,
       depth + 1
     );
@@ -10646,9 +10647,9 @@ function eventDurationMs(event) {
 }
 function treeShape(nodes) {
   const lines = [];
-  const visit = (node, path16) => {
-    lines.push(`${path16}:${node.event.kind}:${node.event.name}:${node.event.status ?? "unknown"}`);
-    node.children.forEach((child, index) => visit(child, `${path16}.${index}`));
+  const visit = (node, path18) => {
+    lines.push(`${path18}:${node.event.kind}:${node.event.name}:${node.event.status ?? "unknown"}`);
+    node.children.forEach((child, index) => visit(child, `${path18}.${index}`));
   };
   nodes.forEach((node, index) => visit(node, String(index)));
   return lines;
@@ -10697,9 +10698,9 @@ function retrievalShape(context) {
 function guardrailShape(context) {
   return guardrailEvents(context).map((event) => signalName(event, ["guardrailName", "guardrail", "guardrailId"], ["guardrail:"])).sort((a, b) => a.localeCompare(b));
 }
-function firstEvidenceForKind(context, kind, path16) {
+function firstEvidenceForKind(context, kind, path18) {
   const event = context.events.find((candidate) => candidate.kind === kind);
-  return event ? [eventEvidence(event, path16)] : runEvidence(context.selectedRun);
+  return event ? [eventEvidence(event, path18)] : runEvidence(context.selectedRun);
 }
 function baselineDiffFinding(message, evidence, expected, actual) {
   return failFinding("baseline.regression", message, evidence, expected, actual);
@@ -10947,13 +10948,13 @@ function createStructureCycleRule() {
       const seenCycles = /* @__PURE__ */ new Set();
       const findings = [];
       for (const event of [...context.events].sort((a, b) => a.eventId.localeCompare(b.eventId))) {
-        const path16 = [];
+        const path18 = [];
         const seenAt = /* @__PURE__ */ new Map();
         let current = event;
         while (current) {
           const existing = seenAt.get(current.eventId);
           if (existing !== void 0) {
-            const cycle = path16.slice(existing);
+            const cycle = path18.slice(existing);
             const key = cycle.map((item) => item.eventId).sort().join("\0");
             if (!seenCycles.has(key)) {
               seenCycles.add(key);
@@ -10969,8 +10970,8 @@ function createStructureCycleRule() {
             }
             break;
           }
-          seenAt.set(current.eventId, path16.length);
-          path16.push(current);
+          seenAt.set(current.eventId, path18.length);
+          path18.push(current);
           current = current.parentId ? byId.get(current.parentId) : void 0;
         }
       }
@@ -11767,23 +11768,23 @@ function evaluatePromptInjection(text, options = {}) {
   }
   return fail(ruleId, `Matched ${evidence.length} injection pattern(s).`, evidence, "warning");
 }
-function validateSchemaField(value, field, path16, evidence) {
+function validateSchemaField(value, field, path18, evidence) {
   const ruleId = "guardrail.structured-output";
   if (field.type) {
     const actual = value === null ? "null" : Array.isArray(value) ? "array" : typeof value;
     if (actual !== field.type) {
-      evidence.push({ ruleId, path: path16, preview: `expected ${field.type}, got ${actual}` });
+      evidence.push({ ruleId, path: path18, preview: `expected ${field.type}, got ${actual}` });
       return;
     }
   }
   if (field.enum && !field.enum.some((item) => Object.is(item, value))) {
-    evidence.push({ ruleId, path: path16, preview: "value not in enum" });
+    evidence.push({ ruleId, path: path18, preview: "value not in enum" });
   }
   if (field.type === "object" && field.required && value && typeof value === "object" && !Array.isArray(value)) {
     const record = value;
     for (const key of field.required) {
       if (!(key in record)) {
-        evidence.push({ ruleId, path: `${path16}.${key}`, preview: "missing required key" });
+        evidence.push({ ruleId, path: `${path18}.${key}`, preview: "missing required key" });
       }
     }
   }
@@ -12248,10 +12249,10 @@ function printHuman(result) {
     console.log(`- ${diagnostic4.code}: ${diagnostic4.message}`);
   }
   for (const finding of result.findings) {
-    const path16 = finding.evidence[0]?.path;
+    const path18 = finding.evidence[0]?.path;
     const run = finding.evidence[0]?.runId;
     const runPrefix = run ? `[${run}] ` : "";
-    console.log(`- ${runPrefix}${finding.ruleId}: ${finding.message}${path16 ? ` (${path16})` : ""}`);
+    console.log(`- ${runPrefix}${finding.ruleId}: ${finding.message}${path18 ? ` (${path18})` : ""}`);
   }
 }
 function readErrorResult(error) {
@@ -12789,10 +12790,10 @@ async function evalRun(input3, options = {}) {
     diagnostics: []
   };
 }
-function evidenceForRun(run, path16) {
-  return [{ runId: run.runId, ...path16 !== void 0 ? { path: path16 } : {} }];
+function evidenceForRun(run, path18) {
+  return [{ runId: run.runId, ...path18 !== void 0 ? { path: path18 } : {} }];
 }
-function evidenceForEvent(event, path16) {
+function evidenceForEvent(event, path18) {
   return [
     {
       runId: event.runId,
@@ -12800,7 +12801,7 @@ function evidenceForEvent(event, path16) {
       ...event.parentId !== void 0 ? { parentId: event.parentId } : {},
       kind: event.kind,
       name: event.name,
-      ...path16 !== void 0 ? { path: path16 } : {}
+      ...path18 !== void 0 ? { path: path18 } : {}
     }
   ];
 }
@@ -12958,9 +12959,9 @@ function collectTextFields(nodes, keys, preferredKinds = []) {
 function tokenize(text) {
   return [...text.toLowerCase().matchAll(/[a-z0-9][a-z0-9'-]{2,}/g)].map((match) => match[0].replace(/^['-]+|['-]+$/g, "")).filter((token) => token.length > 2 && !STOP_WORDS.has(token));
 }
-function firstEvidence(fields, run, path16) {
+function firstEvidence(fields, run, path18) {
   const first = fields[0];
-  return first === void 0 ? evidenceForRun(run, path16) : evidenceForEvent(first.node.event, first.path);
+  return first === void 0 ? evidenceForRun(run, path18) : evidenceForEvent(first.node.event, first.path);
 }
 function collectSourceIds(nodes, keys) {
   const wanted = keySet(keys);
@@ -13337,8 +13338,8 @@ function renderEvalMarkdown(result) {
   if (result.findings.length > 0) {
     lines.push("", "## Findings");
     for (const finding of result.findings) {
-      const path16 = finding.evidence[0]?.path;
-      lines.push(`- ${finding.ruleId}: ${finding.message}${path16 ? ` (${path16})` : ""}`);
+      const path18 = finding.evidence[0]?.path;
+      lines.push(`- ${finding.ruleId}: ${finding.message}${path18 ? ` (${path18})` : ""}`);
     }
   }
   return `${lines.join("\n")}
@@ -13531,8 +13532,8 @@ function printHuman2(result) {
     console.log(`- ${diagnostic4.code}: ${diagnostic4.message}`);
   }
   for (const finding of result.findings) {
-    const path16 = finding.evidence[0]?.path;
-    console.log(`- ${finding.ruleId}: ${finding.message}${path16 ? ` (${path16})` : ""}`);
+    const path18 = finding.evidence[0]?.path;
+    console.log(`- ${finding.ruleId}: ${finding.message}${path18 ? ` (${path18})` : ""}`);
   }
 }
 function readErrorResult2(error) {
@@ -13770,8 +13771,8 @@ function printHuman3(result) {
     console.log(`- ${diagnostic4.code}: ${diagnostic4.message}`);
   }
   for (const finding of result.findings) {
-    const path16 = finding.evidence[0]?.path;
-    console.log(`- ${finding.ruleId}: ${finding.message}${path16 ? ` (${path16})` : ""}`);
+    const path18 = finding.evidence[0]?.path;
+    console.log(`- ${finding.ruleId}: ${finding.message}${path18 ? ` (${path18})` : ""}`);
   }
   console.log(`Note: ${result.note}`);
 }
@@ -13890,8 +13891,8 @@ function renderCheckSection(result) {
     `Diagnostics: ${result.diagnostics.length}`
   ];
   for (const finding of result.findings.slice(0, 10)) {
-    const path16 = finding.evidence[0]?.path ?? "(run)";
-    lines.push(`- ${finding.ruleId}: ${finding.message} (${path16})`);
+    const path18 = finding.evidence[0]?.path ?? "(run)";
+    lines.push(`- ${finding.ruleId}: ${finding.message} (${path18})`);
   }
   for (const diagnostic4 of result.diagnostics.slice(0, 10)) {
     lines.push(`- ${diagnostic4.code}: ${diagnostic4.message}`);
@@ -14451,6 +14452,447 @@ ${markdown}`, "utf-8");
     console.log(markdown.trimEnd());
   }
 }
+var CONFIG_FILE = "agent-inspect.config.ts";
+var TRACE_DIR = ".agent-inspect";
+var GITKEEP = ".agent-inspect/.gitkeep";
+function normalizeFramework(value) {
+  const raw = (value ?? "custom").trim();
+  if (raw === "ai-sdk" || raw === "openai-agents" || raw === "langchain" || raw === "custom") {
+    return raw;
+  }
+  throw new Error(
+    "Unsupported --framework value. Use ai-sdk, openai-agents, langchain, or custom."
+  );
+}
+function configTemplate(framework) {
+  const base = `/**
+ * AgentInspect local config (metadata-only capture by default).
+ * See https://github.com/rajudandigam/agent-inspect/blob/main/docs/SAFE-TRACE-SHARING.md
+ */
+export const agentInspectConfig = {
+  traceDir: ".agent-inspect",
+  enabled: process.env.AGENT_INSPECT !== "0",
+  redactionProfile: "local" as const,
+};
+`;
+  if (framework === "custom") return base;
+  return `${base}
+export const framework = "${framework}" as const;
+`;
+}
+function demoTemplate(framework) {
+  switch (framework) {
+    case "ai-sdk":
+      return `/**
+ * AI SDK starter \u2014 metadata-only telemetry (no real model calls in this demo).
+ * Install: npm install agent-inspect @agent-inspect/ai-sdk ai
+ */
+import { inspectRun, step } from "agent-inspect";
+
+async function main() {
+  await inspectRun("ai-sdk-demo", async () => {
+    await step.tool("mock-generate", async () => ({ text: "ok" }));
+  }, { traceDir: ".agent-inspect", silent: true });
+  console.log("Trace written to .agent-inspect/");
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exitCode = 1;
+});
+`;
+    case "openai-agents":
+      return `/**
+ * OpenAI Agents starter \u2014 use @agent-inspect/openai-agents for local-only processors.
+ * This demo uses manual steps (no API keys).
+ */
+import { inspectRun, step } from "agent-inspect";
+
+async function main() {
+  await inspectRun("openai-agents-demo", async () => {
+    await step.tool("mock-agent-run", async () => "ok");
+  }, { traceDir: ".agent-inspect", silent: true });
+  console.log("Trace written to .agent-inspect/");
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exitCode = 1;
+});
+`;
+    case "langchain":
+      return `/**
+ * LangChain starter \u2014 wire @agent-inspect/langchain callbacks in your app.
+ * This demo uses manual steps (no API keys).
+ */
+import { inspectRun, step } from "agent-inspect";
+
+async function main() {
+  await inspectRun("langchain-demo", async () => {
+    await step.tool("mock-chain", async () => "ok");
+  }, { traceDir: ".agent-inspect", silent: true });
+  console.log("Trace written to .agent-inspect/");
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exitCode = 1;
+});
+`;
+    default:
+      return `import { observe } from "agent-inspect";
+
+class DemoAgent {
+  async run(input: { question: string }) {
+    return { answer: \`Echo: \${input.question}\` };
+  }
+}
+
+const agent = observe(new DemoAgent(), {
+  traceDir: ".agent-inspect",
+  silent: true,
+});
+
+await agent.run({ question: "hello" });
+console.log("Trace written to .agent-inspect/");
+`;
+  }
+}
+function githubWorkflowTemplate() {
+  return `name: AgentInspect artifacts
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+
+jobs:
+  trace-artifacts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+      - run: npm ci
+      - run: npm test
+      - name: Upload AgentInspect traces
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: agent-inspect-traces
+          path: .agent-inspect/**/*.jsonl
+          if-no-files-found: ignore
+`;
+}
+async function planInit(options = {}) {
+  const framework = normalizeFramework(options.framework);
+  const cwd = path14.resolve(options.cwd ?? process.cwd());
+  const demoPath = framework === "custom" ? path14.join("examples", "agent-inspect-demo.mjs") : path14.join("examples", `agent-inspect-${framework}-demo.mjs`);
+  const candidates = [
+    { rel: CONFIG_FILE, content: configTemplate(framework) },
+    { rel: GITKEEP, content: "" },
+    { rel: demoPath, content: demoTemplate(framework) }
+  ];
+  if (options.ci === "github") {
+    candidates.push({
+      rel: ".github/workflows/agent-inspect-artifacts.yml",
+      content: githubWorkflowTemplate()
+    });
+  }
+  const files = [];
+  for (const candidate of candidates) {
+    const abs = path14.join(cwd, candidate.rel);
+    try {
+      await access(abs);
+      files.push({
+        path: candidate.rel,
+        action: "skip",
+        reason: "file already exists"
+      });
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+      files.push({ path: candidate.rel, action: "create" });
+    }
+  }
+  return { framework, ...options.ci ? { ci: options.ci } : {}, files };
+}
+async function writePlannedFiles(plan, cwd, options) {
+  const written = [];
+  for (const entry of plan.files) {
+    if (entry.action === "skip") {
+      continue;
+    }
+    const abs = path14.join(cwd, entry.path);
+    if (options.dryRun) {
+      written.push(entry.path);
+      continue;
+    }
+    await mkdir(path14.dirname(abs), { recursive: true });
+    const content = entry.path === CONFIG_FILE ? configTemplate(plan.framework) : entry.path === GITKEEP ? "" : entry.path.endsWith(".yml") ? githubWorkflowTemplate() : demoTemplate(plan.framework);
+    await writeFile(abs, content, "utf-8");
+    written.push(entry.path);
+  }
+  return written;
+}
+async function initCommand(options = {}) {
+  const cwd = path14.resolve(options.cwd ?? process.cwd());
+  try {
+    const plan = await planInit({ ...options, cwd });
+    const toWrite = plan.files.filter((file) => file.action === "create").map((f) => f.path);
+    const skipped = plan.files.filter((file) => file.action === "skip");
+    if (options.json) {
+      const payload = {
+        ok: true,
+        version,
+        framework: plan.framework,
+        ci: plan.ci ?? null,
+        dryRun: options.dryRun === true,
+        planned: plan.files,
+        wouldWrite: options.dryRun ? toWrite : void 0
+      };
+      console.log(JSON.stringify(payload, null, 2));
+      if (options.dryRun) return;
+    }
+    const written = await writePlannedFiles(plan, cwd, options);
+    if (!options.json) {
+      console.log("AgentInspect init");
+      console.log(`Framework: ${plan.framework}`);
+      console.log(`Trace directory: ${TRACE_DIR}/`);
+      if (options.dryRun) {
+        console.log("Dry run \u2014 would create:");
+        for (const file of toWrite) console.log(`- ${file}`);
+        for (const file of skipped) {
+          console.log(`- ${file.path} (skip: ${file.reason ?? "exists"})`);
+        }
+        return;
+      }
+      console.log("Created:");
+      for (const file of written) console.log(`- ${file}`);
+      for (const file of skipped) {
+        console.log(`- ${file.path} (skipped: ${file.reason ?? "exists"})`);
+      }
+      console.log("\nNext: run your demo, then `npx agent-inspect list --dir .agent-inspect`");
+      console.log("No dependencies were installed. Add packages manually when ready.");
+    }
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    if (options.json) {
+      console.log(JSON.stringify({ ok: false, error: msg }, null, 2));
+    } else {
+      console.error(`[AgentInspect] init failed: ${msg}`);
+    }
+    process.exitCode = 1;
+  }
+}
+var OPTIONAL_PACKAGES = {
+  custom: [],
+  "ai-sdk": ["@agent-inspect/ai-sdk"],
+  "openai-agents": ["@agent-inspect/openai-agents"],
+  langchain: ["@agent-inspect/langchain"]
+};
+function nodeVersionCheck() {
+  const major = Number(process3.versions.node.split(".")[0]);
+  if (Number.isNaN(major) || major < 20) {
+    return {
+      id: "node-version",
+      status: "fail",
+      message: `Node ${process3.versions.node} is below the supported minimum (20).`,
+      remediation: "Upgrade to Node 20 LTS or newer.",
+      evidence: process3.versions.node
+    };
+  }
+  return {
+    id: "node-version",
+    status: "pass",
+    message: `Node ${process3.versions.node} meets the minimum (>=20).`,
+    evidence: process3.versions.node
+  };
+}
+function envCheck(name, optional = true) {
+  const value = process3.env[name];
+  if (value === void 0 || value.trim() === "") {
+    return {
+      id: `env-${name.toLowerCase()}`,
+      status: optional ? "skipped" : "warn",
+      message: `${name} is not set.`,
+      remediation: optional ? void 0 : `Set ${name}=1 to enable tracing.`
+    };
+  }
+  return {
+    id: `env-${name.toLowerCase()}`,
+    status: "pass",
+    message: `${name} is set.`,
+    evidence: value
+  };
+}
+async function traceDirWritable(traceDir) {
+  const resolved = path14.resolve(traceDir);
+  try {
+    await mkdir(resolved, { recursive: true });
+    await access(resolved, constants.W_OK);
+    return {
+      id: "trace-dir-writable",
+      status: "pass",
+      message: `Trace directory is writable: ${resolved}`,
+      evidence: resolved
+    };
+  } catch (error) {
+    return {
+      id: "trace-dir-writable",
+      status: "fail",
+      message: `Trace directory is not writable: ${resolved}`,
+      remediation: "Create the directory or set AGENT_INSPECT_TRACE_DIR to a writable path.",
+      evidence: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+function resolvePackage(cwd, name) {
+  const require2 = createRequire(path14.join(cwd, "package.json"));
+  try {
+    const pkgPath = require2.resolve(`${name}/package.json`);
+    const pkg = require2(pkgPath);
+    return { ok: true, version: pkg.version };
+  } catch {
+    return { ok: false };
+  }
+}
+function importSmoke(cwd) {
+  const results = [];
+  const require2 = createRequire(path14.join(cwd, "package.json"));
+  try {
+    require2.resolve("agent-inspect");
+    results.push({
+      id: "import-agent-inspect",
+      status: "pass",
+      message: "agent-inspect resolves from the current project."
+    });
+  } catch {
+    results.push({
+      id: "import-agent-inspect",
+      status: "warn",
+      message: "agent-inspect is not installed in the current project.",
+      remediation: "Run npm install agent-inspect (or pnpm add agent-inspect)."
+    });
+  }
+  try {
+    require2.resolve("agent-inspect/package.json");
+    results.push({
+      id: "import-agent-inspect-cjs",
+      status: "pass",
+      message: "CJS resolution for agent-inspect succeeded."
+    });
+  } catch {
+    results.push({
+      id: "import-agent-inspect-cjs",
+      status: "skipped",
+      message: "CJS resolution check skipped (package not installed locally)."
+    });
+  }
+  return results;
+}
+function optionalPackageChecks(cwd, framework) {
+  const packages = framework !== void 0 ? OPTIONAL_PACKAGES[framework] : [
+    "@agent-inspect/ai-sdk",
+    "@agent-inspect/openai-agents",
+    "@agent-inspect/langchain",
+    "@agent-inspect/redact",
+    "@agent-inspect/eval"
+  ];
+  return packages.map((name) => {
+    const resolved = resolvePackage(cwd, name);
+    if (!resolved.ok) {
+      return {
+        id: `optional-package-${name}`,
+        status: framework !== void 0 ? "warn" : "skipped",
+        message: `${name} is not installed.`,
+        remediation: framework !== void 0 ? `npm install ${name}` : void 0
+      };
+    }
+    return {
+      id: `optional-package-${name}`,
+      status: "pass",
+      message: `${name} is available.`,
+      evidence: resolved.version
+    };
+  });
+}
+function versionMismatchCheck(cwd) {
+  const root = resolvePackage(cwd, "agent-inspect");
+  if (!root.ok || root.version === void 0) {
+    return {
+      id: "version-alignment",
+      status: "skipped",
+      message: "Skipped version alignment \u2014 agent-inspect not installed locally."
+    };
+  }
+  if (root.version !== version) {
+    return {
+      id: "version-alignment",
+      status: "warn",
+      message: `CLI version ${version} differs from local agent-inspect@${root.version}.`,
+      remediation: "Align versions with npm install agent-inspect@latest",
+      evidence: `cli=${version};local=${root.version}`
+    };
+  }
+  return {
+    id: "version-alignment",
+    status: "pass",
+    message: `CLI and local agent-inspect are aligned at ${version}.`
+  };
+}
+async function runDoctorChecks(options = {}) {
+  const cwd = path14.resolve(options.cwd ?? process3.cwd());
+  const traceDir = options.traceDir?.trim() || process3.env.AGENT_INSPECT_TRACE_DIR?.trim() || ".agent-inspect";
+  const checks2 = [
+    nodeVersionCheck(),
+    {
+      id: "cli-version",
+      status: "pass",
+      message: `agent-inspect CLI ${version}`,
+      evidence: version
+    },
+    await traceDirWritable(traceDir),
+    envCheck("AGENT_INSPECT"),
+    envCheck("AGENT_INSPECT_TRACE_DIR"),
+    versionMismatchCheck(cwd)
+  ];
+  if (options.checkImports !== false) {
+    checks2.push(...importSmoke(cwd));
+  }
+  checks2.push(...optionalPackageChecks(cwd, options.framework));
+  return checks2.sort((a, b) => a.id.localeCompare(b.id));
+}
+async function doctorCommand(options = {}) {
+  const checks2 = await runDoctorChecks(options);
+  const failed = checks2.filter((check) => check.status === "fail").length;
+  const warned = checks2.filter((check) => check.status === "warn").length;
+  if (options.json) {
+    console.log(
+      JSON.stringify(
+        {
+          ok: failed === 0,
+          version,
+          summary: { pass: checks2.filter((c) => c.status === "pass").length, warn: warned, fail: failed },
+          checks: checks2
+        },
+        null,
+        2
+      )
+    );
+    if (failed > 0) process3.exitCode = 1;
+    return;
+  }
+  console.log("AgentInspect doctor");
+  for (const check of checks2) {
+    const tag = check.status.toUpperCase();
+    console.log(`[${tag}] ${check.id}: ${check.message}`);
+    if (check.remediation) console.log(`  \u2192 ${check.remediation}`);
+  }
+  console.log(`
+Summary: ${failed} failed, ${warned} warnings`);
+  if (failed > 0) process3.exitCode = 1;
+}
 
 // packages/cli/src/index.ts
 function runCommand(action) {
@@ -14750,6 +15192,26 @@ function createCliProgram() {
   ).action((target, opts) => {
     runCommand(() => explainCommand(target, opts));
   });
+  program.command("init").description("Initialize a minimal local AgentInspect setup (no dependency install)").addOption(
+    new Option("--framework <framework>", "starter framework path").choices([
+      "ai-sdk",
+      "openai-agents",
+      "langchain",
+      "custom"
+    ])
+  ).addOption(new Option("--ci <provider>", "optional CI snippet").choices(["github"])).option("--dry-run", "print planned files without writing").option("--yes", "non-interactive; skip existing files").option("--json", "print deterministic JSON plan/result").action((opts) => {
+    runCommand(() => initCommand(opts));
+  });
+  program.command("doctor").description("Diagnose local AgentInspect setup (no network, no installs)").option("--json", "print deterministic JSON results").option("--trace-dir <path>", "trace directory to validate (default .agent-inspect)").option("--check-imports", "check local package resolution", true).option("--no-check-imports", "skip import resolution checks").addOption(
+    new Option("--framework <framework>", "check optional adapter packages").choices([
+      "ai-sdk",
+      "openai-agents",
+      "langchain",
+      "custom"
+    ])
+  ).action((opts) => {
+    runCommand(() => doctorCommand(opts));
+  });
   return program;
 }
 function isPrimaryModule() {