@tonyclaw/agent-inspector 2.0.15 → 2.0.17

package/src/cli/onboard.ts

@@ -5,12 +5,21 @@
  * Claude Code gets a skill + slash command. Codex gets a skill under
  * ~/.codex/skills that guides the user through connecting /api/mcp.
  *
- * Idempotent by default: re-runs without `--force` only write missing files.
- * `--force` overwrites, `--dry-run` writes nothing. Designed as an explicit
- * setup step that can fail softly without blocking normal CLI use.
+ * Idempotent by default: re-runs without `--force` write missing files and
+ * refresh older generated files. `--force` overwrites, `--dry-run` writes
+ * nothing. Designed as an explicit setup step that can fail softly without
+ * blocking normal CLI use.
  */
 
-import { mkdirSync, writeFileSync, existsSync, readFileSync } from "node:fs";
+import {
+  mkdirSync,
+  writeFileSync,
+  existsSync,
+  readFileSync,
+  unlinkSync,
+  readdirSync,
+  rmdirSync,
+} from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -37,6 +46,10 @@ const SKILL_FILE_NAME = "SKILL.md";
 const COMMAND_FILE_NAME =
   process.platform === "win32" ? "agent-inspector-onboard.md" : "agent-inspector:onboard.md";
 
+const GENERATED_VERSION_PATTERN = /^\s*version:\s*([0-9]+\.[0-9]+\.[0-9]+(?:[-+][^\s]+)?)\s*$/m;
+const FRONTMATTER_PATTERN = /^---\r?\n([\s\S]*?)\r?\n---/;
+const SEMVER_PATTERN = /^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/;
+
 export type OnboardFlags = {
   force: boolean;
   dryRun: boolean;
@@ -44,6 +57,9 @@ export type OnboardFlags = {
   skipToolWire: boolean;
   codexOnly: boolean;
   skipCodexSkill: boolean;
+  uninstall: boolean;
+  status: boolean;
+  json: boolean;
   skillDir: string | null;
   codexSkillDir: string | null;
 };
@@ -61,6 +77,47 @@ type PlannedFile = {
   enabled: boolean;
 };
 
+type ParsedVersion = {
+  major: number;
+  minor: number;
+  patch: number;
+};
+
+type GeneratedFileState = "missing" | "current" | "outdated" | "newer" | "custom";
+
+type GeneratedFileStatus = {
+  label: string;
+  path: string;
+  state: GeneratedFileState;
+  version: string | null;
+  action: string;
+};
+
+function actionForStatus(label: string, state: GeneratedFileState): string {
+  switch (state) {
+    case "missing":
+      switch (label) {
+        case "Codex skill":
+          return "agent-inspector onboard --codex-only";
+        case "Claude skill":
+        case "Claude command":
+          return "agent-inspector onboard --skip-codex-skill";
+        default:
+          return "agent-inspector onboard";
+      }
+    case "outdated":
+      return "agent-inspector onboard --force";
+    case "custom":
+      return "preserved; use agent-inspector onboard --force to replace";
+    case "newer":
+      return "no action; installed file is newer than this package";
+    case "current":
+      return "no action";
+    default:
+      return "agent-inspector onboard";
+  }
+}
+
 function parseFlags(argv: readonly string[]): OnboardFlags {
   const flags: OnboardFlags = {
     force: false,
@@ -69,6 +126,9 @@ function parseFlags(argv: readonly string[]): OnboardFlags {
     skipToolWire: false,
     codexOnly: false,
     skipCodexSkill: false,
+    uninstall: false,
+    status: false,
+    json: false,
     skillDir: null,
     codexSkillDir: null,
   };
@@ -95,6 +155,15 @@ function parseFlags(argv: readonly string[]): OnboardFlags {
       case "--skip-codex-skill":
         flags.skipCodexSkill = true;
         break;
+      case "--uninstall":
+        flags.uninstall = true;
+        break;
+      case "--status":
+        flags.status = true;
+        break;
+      case "--json":
+        flags.json = true;
+        break;
       case "--skill-dir": {
         const next = argv[i + 1];
         if (next === undefined) {
@@ -143,6 +212,9 @@ Options:
   --skip-tool-wire         Skip the wire-tool phase in the Claude skill body
   --skip-codex-skill       Install only the Claude Code skill and slash command
   --codex-only             Install only the Codex skill
+  --uninstall              Remove generated files whose version matches this package
+  --status                 Show installed onboarding file versions and suggested action
+  --json                   Emit machine-readable JSON with --status
   --skill-dir <path>       Override the target Claude root directory (default: ~/.claude)
   --codex-skill-dir <path> Override the target Codex skills directory (default: ~/.codex/skills)
   -h, --help               Show this help
@@ -181,10 +253,19 @@ function buildDetectedSummary(): string {
 }
 
 function readPackageVersion(): string {
+  const packageJsonPaths = [
+    join(__dirname, "..", "package.json"),
+    join(__dirname, "..", "..", "package.json"),
+  ];
+
   try {
-    const raw: unknown = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf8"));
-    if (isObject(raw) && typeof raw["version"] === "string") {
-      return raw["version"];
+    for (const packageJsonPath of packageJsonPaths) {
+      if (existsSync(packageJsonPath)) {
+        const raw: unknown = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+        if (isObject(raw) && typeof raw["version"] === "string") {
+          return raw["version"];
+        }
+      }
     }
   } catch {
     // best-effort: leave version as the fallback
@@ -192,6 +273,176 @@ function readPackageVersion(): string {
   return "0.0.0";
 }
 
+function parseVersion(version: string): ParsedVersion | null {
+  const match = SEMVER_PATTERN.exec(version);
+  if (match === null) {
+    return null;
+  }
+
+  const majorText = match[1];
+  const minorText = match[2];
+  const patchText = match[3];
+  if (majorText === undefined || minorText === undefined || patchText === undefined) {
+    return null;
+  }
+
+  const major = Number(majorText);
+  const minor = Number(minorText);
+  const patch = Number(patchText);
+  if (!Number.isInteger(major) || !Number.isInteger(minor) || !Number.isInteger(patch)) {
+    return null;
+  }
+
+  return { major, minor, patch };
+}
+
+function compareVersions(left: string, right: string): number | null {
+  const leftVersion = parseVersion(left);
+  const rightVersion = parseVersion(right);
+  if (leftVersion === null || rightVersion === null) {
+    return null;
+  }
+
+  const leftParts = [leftVersion.major, leftVersion.minor, leftVersion.patch];
+  const rightParts = [rightVersion.major, rightVersion.minor, rightVersion.patch];
+  for (let index = 0; index < leftParts.length; index++) {
+    const leftPart = leftParts[index];
+    const rightPart = rightParts[index];
+    if (leftPart === undefined || rightPart === undefined) {
+      return null;
+    }
+    if (leftPart > rightPart) {
+      return 1;
+    }
+    if (leftPart < rightPart) {
+      return -1;
+    }
+  }
+
+  return 0;
+}
+
+function extractGeneratedVersion(body: string): string | null {
+  const frontmatterMatch = FRONTMATTER_PATTERN.exec(body);
+  if (frontmatterMatch === null) {
+    return null;
+  }
+
+  const frontmatter = frontmatterMatch[1];
+  if (frontmatter === undefined) {
+    return null;
+  }
+
+  const versionMatch = GENERATED_VERSION_PATTERN.exec(frontmatter);
+  if (versionMatch === null) {
+    return null;
+  }
+
+  return versionMatch[1] ?? null;
+}
+
+function hasAgentInspectorAuthor(body: string): boolean {
+  const frontmatterMatch = FRONTMATTER_PATTERN.exec(body);
+  if (frontmatterMatch === null) {
+    return false;
+  }
+
+  const frontmatter = frontmatterMatch[1];
+  if (frontmatter === undefined) {
+    return false;
+  }
+
+  return /^\s*author:\s*agent-inspector\s*$/m.test(frontmatter);
+}
+
+function readGeneratedVersion(path: string): string | null {
+  try {
+    return extractGeneratedVersion(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function isMatchingGeneratedFile(path: string, currentVersion: string): boolean {
+  try {
+    const body = readFileSync(path, "utf8");
+    return hasAgentInspectorAuthor(body) && extractGeneratedVersion(body) === currentVersion;
+  } catch {
+    return false;
+  }
+}
+
+function readGeneratedFileStatus(file: PlannedFile, currentVersion: string): GeneratedFileStatus {
+  if (!existsSync(file.path)) {
+    return {
+      label: file.label,
+      path: file.path,
+      state: "missing",
+      version: null,
+      action: actionForStatus(file.label, "missing"),
+    };
+  }
+
+  try {
+    const body = readFileSync(file.path, "utf8");
+    const version = extractGeneratedVersion(body);
+    if (!hasAgentInspectorAuthor(body) || version === null) {
+      return {
+        label: file.label,
+        path: file.path,
+        state: "custom",
+        version,
+        action: actionForStatus(file.label, "custom"),
+      };
+    }
+
+    const comparison = compareVersions(version, currentVersion);
+    if (comparison === null) {
+      return {
+        label: file.label,
+        path: file.path,
+        state: "custom",
+        version,
+        action: actionForStatus(file.label, "custom"),
+      };
+    }
+    if (comparison < 0) {
+      return {
+        label: file.label,
+        path: file.path,
+        state: "outdated",
+        version,
+        action: actionForStatus(file.label, "outdated"),
+      };
+    }
+    if (comparison > 0) {
+      return {
+        label: file.label,
+        path: file.path,
+        state: "newer",
+        version,
+        action: actionForStatus(file.label, "newer"),
+      };
+    }
+
+    return {
+      label: file.label,
+      path: file.path,
+      state: "current",
+      version,
+      action: actionForStatus(file.label, "current"),
+    };
+  } catch {
+    return {
+      label: file.label,
+      path: file.path,
+      state: "custom",
+      version: null,
+      action: actionForStatus(file.label, "custom"),
+    };
+  }
+}
+
 function buildPlannedFiles(
   flags: OnboardFlags,
   targets: OnboardTargets,
@@ -207,7 +458,7 @@ function buildPlannedFiles(
         detectedSummary,
       })
     : "";
-  const commandBody = installClaude ? renderCommandOnboard() : "";
+  const commandBody = installClaude ? renderCommandOnboard({ version }) : "";
   const codexSkillBody = installCodex
     ? renderCodexSkillOnboard({
         version,
@@ -237,8 +488,136 @@ function buildPlannedFiles(
   ];
 }
 
-function shouldWrite(file: PlannedFile, force: boolean): boolean {
-  return file.enabled && (force || !existsSync(file.path));
+function shouldWrite(file: PlannedFile, force: boolean, currentVersion: string): boolean {
+  if (!file.enabled) {
+    return false;
+  }
+  if (force || !existsSync(file.path)) {
+    return true;
+  }
+
+  const existingVersion = readGeneratedVersion(file.path);
+  if (existingVersion === null) {
+    return false;
+  }
+
+  const comparison = compareVersions(existingVersion, currentVersion);
+  return comparison !== null && comparison < 0;
+}
+
+function shouldUninstall(file: PlannedFile, currentVersion: string): boolean {
+  return (
+    file.enabled && existsSync(file.path) && isMatchingGeneratedFile(file.path, currentVersion)
+  );
+}
+
+function removeEmptyDirectory(path: string): void {
+  try {
+    if (readdirSync(path).length === 0) {
+      rmdirSync(path);
+    }
+  } catch {
+    // best-effort cleanup only
+  }
+}
+
+function runUninstall(
+  plannedFiles: readonly PlannedFile[],
+  currentVersion: string,
+  dryRun: boolean,
+): number {
+  const enabledFiles = plannedFiles.filter((file) => file.enabled);
+  const filesToRemove = enabledFiles.filter((file) => shouldUninstall(file, currentVersion));
+
+  if (dryRun) {
+    process.stdout.write(`agent-inspector onboard --uninstall --dry-run\n\n`);
+    for (const file of enabledFiles) {
+      const status = shouldUninstall(file, currentVersion) ? "matching" : "skipped";
+      process.stdout.write(`${file.label}: ${file.path} (${status})\n`);
+    }
+    process.stdout.write(`\nNo files were removed.\n`);
+    return 0;
+  }
+
+  if (filesToRemove.length === 0) {
+    process.stdout.write(
+      "agent-inspector onboard: no generated onboarding files match this package version\n",
+    );
+    return 0;
+  }
+
+  try {
+    for (const file of filesToRemove) {
+      unlinkSync(file.path);
+      removeEmptyDirectory(dirname(file.path));
+      process.stdout.write(`Removed ${file.label}: ${file.path}\n`);
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`agent-inspector onboard: failed to remove files: ${msg}\n`);
+    return 1;
+  }
+
+  return 0;
+}
+
+function formatStatusVersion(status: GeneratedFileStatus): string {
+  return status.version ?? "-";
+}
+
+function summarizeStatusAction(statuses: readonly GeneratedFileStatus[]): string {
+  const actionable = statuses.filter(
+    (status) => status.state === "missing" || status.state === "outdated",
+  );
+  if (actionable.length > 0) {
+    const actions = Array.from(new Set(actionable.map((status) => status.action)));
+    return `Run: ${actions.join(" && ")}`;
+  }
+  if (statuses.some((status) => status.state === "custom")) {
+    return "Custom files are preserved. Use --force only if you want to replace them.";
+  }
+  if (statuses.some((status) => status.state === "newer")) {
+    return "Installed files are newer than this package. No action needed.";
+  }
+  return "All selected onboarding files are current.";
+}
+
+function runStatus(
+  plannedFiles: readonly PlannedFile[],
+  currentVersion: string,
+  json: boolean,
+): number {
+  const enabledFiles = plannedFiles.filter((file) => file.enabled);
+  const statuses = enabledFiles.map((file) => readGeneratedFileStatus(file, currentVersion));
+  const summary = summarizeStatusAction(statuses);
+
+  if (json) {
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          packageVersion: currentVersion,
+          files: statuses,
+          suggestedAction: summary,
+        },
+        null,
+        2,
+      )}\n`,
+    );
+    return 0;
+  }
+
+  process.stdout.write(`agent-inspector onboard status\n`);
+  process.stdout.write(`Package version: ${currentVersion}\n\n`);
+
+  for (const status of statuses) {
+    process.stdout.write(`${status.label}: ${status.state}`);
+    process.stdout.write(`, version ${formatStatusVersion(status)}\n`);
+    process.stdout.write(`  ${status.path}\n`);
+    process.stdout.write(`  Action: ${status.action}\n`);
+  }
+
+  process.stdout.write(`\nSuggested action: ${summary}\n`);
+  return 0;
 }
 
 export function runOnboard(argv: readonly string[]): Promise<number> {
@@ -260,11 +639,24 @@ function runOnboardSync(argv: readonly string[]): number {
   const plannedFiles = buildPlannedFiles(flags, targets, version);
   const enabledFiles = plannedFiles.filter((file) => file.enabled);
 
+  if (flags.json && !flags.status) {
+    process.stderr.write("agent-inspector onboard: --json is only supported with --status\n");
+    return 2;
+  }
+
   if (enabledFiles.length === 0) {
     process.stderr.write("agent-inspector onboard: no onboarding target selected\n");
     return 2;
   }
 
+  if (flags.status) {
+    return runStatus(plannedFiles, version, flags.json);
+  }
+
+  if (flags.uninstall) {
+    return runUninstall(plannedFiles, version, flags.dryRun);
+  }
+
   if (flags.dryRun) {
     process.stdout.write(`agent-inspector onboard --dry-run\n\n`);
     for (const file of enabledFiles) {
@@ -294,9 +686,11 @@ function runOnboardSync(argv: readonly string[]): number {
     return 0;
   }
 
-  const filesToWrite = plannedFiles.filter((file) => shouldWrite(file, flags.force));
+  const filesToWrite = plannedFiles.filter((file) => shouldWrite(file, flags.force, version));
   if (filesToWrite.length === 0) {
-    process.stdout.write("agent-inspector onboard: all selected onboarding files already exist\n");
+    process.stdout.write(
+      "agent-inspector onboard: all selected onboarding files are already up to date\n",
+    );
     process.stdout.write("Re-run with --force to refresh.\n");
     return 0;
   }
@@ -316,7 +710,7 @@ function runOnboardSync(argv: readonly string[]): number {
   const toolHint = firstTool !== null ? firstTool.displayName : "no known tool detected";
 
   for (const file of filesToWrite) {
-    process.stdout.write(`Installed ${file.label} to: ${file.path}\n`);
+    process.stdout.write(`Installed/updated ${file.label} to: ${file.path}\n`);
   }
   process.stdout.write(`\nNext steps:\n`);
   if (!flags.codexOnly) {

package/src/cli/templates/codex-skill-onboard.ts

@@ -47,6 +47,8 @@ Codex user-level configuration lives in \`~/.codex/config.toml\`. Codex supports
 
 Keep this setup local and explicit. Agent Inspector MCP tools can read captured requests and provider configuration, so only wire it into trusted local Codex environments.
 
+Agent Inspector starts in **Simple mode** by default. Keep Simple mode for everyday capture: requests, responses, tools, timing, and token usage stay available without retaining heavier raw headers, raw response, or detailed SSE chunk artifacts. Use **Full mode** only when the user is debugging provider headers, raw response payloads, or SSE stream details.
+
 ---
 
 ## Phase 0: Preflight
@@ -55,12 +57,14 @@ Check that the package and Codex home exist without printing secrets.
 
 \`\`\`powershell
 Get-Command agent-inspector -ErrorAction SilentlyContinue | Select-Object -ExpandProperty Source
+agent-inspector onboard --status
 Test-Path (Join-Path $env:USERPROFILE ".codex")
 Test-Path (Join-Path $env:USERPROFILE ".codex\\config.toml")
 \`\`\`
 
 \`\`\`bash
 command -v agent-inspector || true
+agent-inspector onboard --status
 test -d "$HOME/.codex" && echo "codex home: present" || echo "codex home: missing"
 test -f "$HOME/.codex/config.toml" && echo "config: present" || echo "config: missing"
 \`\`\`
@@ -71,25 +75,30 @@ If \`agent-inspector\` is missing, ask the user to install it first:
 npm install -g @tonyclaw/agent-inspector
 \`\`\`
 
+If \`agent-inspector onboard --status\` reports \`outdated\` or \`missing\`, ask the user to run
+\`agent-inspector onboard --force\` and restart this skill before continuing.
+
 Do not read \`~/.codex/auth.json\`, token files, or unrelated Codex state files.
 
 ---
 
 ## Phase 1: Start Agent Inspector
 
-Start or reuse Agent Inspector before wiring MCP. Prefer the installed binary so Windows users get the branded runtime in Task Manager.
+Start or reuse Agent Inspector before wiring MCP. Prefer the installed binary so Windows users get the branded runtime in Task Manager. Start onboarding in Simple mode; if the user needs raw headers, raw response, or SSE chunks later, restart with \`agent-inspector --mode full\`.
 
 \`\`\`powershell
-agent-inspector --background --no-open
+agent-inspector --mode simple --background --no-open
 Invoke-RestMethod -Uri "http://localhost:${port}/api/health" -TimeoutSec 3
+Invoke-RestMethod -Uri "http://localhost:${port}/api/config" -TimeoutSec 3 | Select-Object captureMode
 \`\`\`
 
 \`\`\`bash
-agent-inspector --background --no-open
+agent-inspector --mode simple --background --no-open
 curl -fsS "http://localhost:${port}/api/health"
+curl -fsS "http://localhost:${port}/api/config" | grep -o '"captureMode":"[^"]*"'
 \`\`\`
 
-If the health check fails, show only the relevant error and ask whether to diagnose startup before editing Codex config.
+If the health check fails, show only the relevant error and ask whether to diagnose startup before editing Codex config. If the active capture mode is not \`simple\`, explain that an existing process is already running and offer to restart with \`agent-inspector --mode simple --force-restart\`.
 
 ---
 

package/src/cli/templates/command-onboard.ts

@@ -1,17 +1,25 @@
 /**
- * Renders `~/.claude/commands/agent-inspector:onboard.md` — a thin slash
+ * Renders `~/.claude/commands/agent-inspector:onboard.md` - a thin slash
  * command that loads the `agent-inspector-onboard` skill. Claude Code
  * auto-discovers both the skill and the command once they're written,
  * so the command body just references the skill by name.
  */
 
-export function renderCommandOnboard(): string {
+export type CommandOnboardContext = {
+  /** Package version (from `package.json`), stamped into the frontmatter. */
+  readonly version: string;
+};
+
+export function renderCommandOnboard(ctx: CommandOnboardContext): string {
   return `---
-description: Walk through agent-inspector setup — start the proxy, wire your AI tool, capture your first request.
+description: Walk through agent-inspector setup - start the proxy, wire your AI tool, capture your first request.
+metadata:
+  author: agent-inspector
+  version: ${ctx.version}
 ---
 
 Invoke the \`agent-inspector-onboard\` skill and follow its phases.
 
-The user wants to set up agent-inspector. If they have specific context (e.g. "I'm on Windows", "I already added my API key"), honor it — but otherwise just run the skill end-to-end and let the \`EXPLAIN / DO / PAUSE\` markers drive the conversation.
+The user wants to set up agent-inspector. If they have specific context (e.g. "I'm on Windows", "I already added my API key"), honor it - but otherwise just run the skill end-to-end and let the \`EXPLAIN / DO / PAUSE\` markers drive the conversation.
 `;
 }