@tonyclaw/agent-inspector 2.0.0

package/.output/cli.js

@@ -0,0 +1,1611 @@
+#!/usr/bin/env node
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/cli/detect-tools.ts
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+function which(bin) {
+  try {
+    if (process.platform === "win32") {
+      const out2 = execFileSync("where", [bin], {
+        encoding: "utf8",
+        timeout: 3e3,
+        windowsHide: true,
+        stdio: ["ignore", "pipe", "ignore"]
+      });
+      const first = out2.split(/\r?\n/).find((line) => line.trim().length > 0);
+      return first?.trim() ?? null;
+    }
+    const out = execFileSync("sh", ["-c", `command -v ${bin}`], {
+      encoding: "utf8",
+      timeout: 3e3,
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+    return out.trim() || null;
+  } catch {
+    return null;
+  }
+}
+function tryDir(path) {
+  return existsSync(path) ? path : null;
+}
+function detectClaudeCode() {
+  const configDir = tryDir(join(homedir(), ".claude"));
+  const bin = which("claude");
+  if (configDir === null && bin === null) return { found: false };
+  return { found: true, path: configDir ?? bin ?? "" };
+}
+function detectOpenCode() {
+  const configDir = tryDir(join(homedir(), ".config", "opencode"));
+  const bin = which("opencode");
+  if (configDir === null && bin === null) return { found: false };
+  return { found: true, path: configDir ?? bin ?? "" };
+}
+function detectMiMo() {
+  const configDir = tryDir(join(homedir(), ".mimo"));
+  const bin = which("mimo");
+  if (configDir === null && bin === null) return { found: false };
+  return { found: true, path: configDir ?? bin ?? "" };
+}
+function detectCursor() {
+  const configDir = tryDir(join(homedir(), ".cursor"));
+  const bin = which("cursor");
+  if (configDir === null && bin === null) return { found: false };
+  return { found: true, path: configDir ?? bin ?? "" };
+}
+function detectCody() {
+  const configDir = tryDir(join(homedir(), ".config", "cody"));
+  const bin = which("cody");
+  if (configDir === null && bin === null) return { found: false };
+  return { found: true, path: configDir ?? bin ?? "" };
+}
+function detectAll() {
+  return DETECTORS.map(({ id, displayName, detect }) => ({
+    id,
+    displayName,
+    result: detect()
+  }));
+}
+function detectFirst() {
+  for (const entry of DETECTORS) {
+    const result = entry.detect();
+    if (result.found) return { id: entry.id, displayName: entry.displayName, result };
+  }
+  return null;
+}
+var DETECTORS;
+var init_detect_tools = __esm({
+  "src/cli/detect-tools.ts"() {
+    "use strict";
+    DETECTORS = [
+      { id: "claude-code", displayName: "Claude Code", detect: detectClaudeCode },
+      { id: "opencode", displayName: "OpenCode", detect: detectOpenCode },
+      { id: "mimo", displayName: "MiMo Code", detect: detectMiMo },
+      { id: "cursor", displayName: "Cursor", detect: detectCursor },
+      { id: "cody", displayName: "Cody", detect: detectCody }
+    ];
+  }
+});
+
+// src/cli/templates/command-onboard.ts
+function renderCommandOnboard() {
+  return `---
+description: Walk through agent-inspector setup \u2014 start the proxy, wire your AI tool, capture your first request.
+---
+
+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 \u2014 but otherwise just run the skill end-to-end and let the \`EXPLAIN / DO / PAUSE\` markers drive the conversation.
+`;
+}
+var init_command_onboard = __esm({
+  "src/cli/templates/command-onboard.ts"() {
+    "use strict";
+  }
+});
+
+// src/cli/templates/skill-onboard.ts
+function renderSkillOnboard(ctx) {
+  const { version, port, detectedSummary } = ctx;
+  return `---
+name: agent-inspector-onboard
+description: Guided setup for Agent Inspector v${version}: start the proxy, wire your AI coding tool, capture your first request, and learn the Web UI.
+metadata:
+  author: agent-inspector
+  version: ${version}
+---
+
+# Agent Inspector onboard
+
+Guide the user from "I just installed Agent Inspector" to "I can see my AI tool's traffic in the Web UI". This is a teaching experience: you'll do real work in their environment while explaining each step.
+
+Environment detected by the installer:
+${detectedSummary || "  (no known AI tool detected \u2014 the user can still use the generic curl example in Phase 4)"}
+
+Default proxy port: \`${port}\` (override with \`PORT=<n> agent-inspector\` or \`--port <n>\`).
+
+> **PAUSE protocol.** Every \`**PAUSE**\` marker in this skill is a real stop.
+> Use the \`AskUserQuestion\` tool to actually wait for the user before
+> continuing. Do not stream past a PAUSE based on context \u2014 the user has
+> not seen your output yet. Each PAUSE in the body below includes a sample
+> question you can adapt.
+
+---
+
+## Phase 0: Idempotency check
+
+**EXPLAIN:** "Before we do anything, let me see what's already set up. If some of the steps are already done, we can skip them."
+
+**DO:** Probe the three pieces of state this skill touches. Use targeted checks \u2014 do **not** read large JSON files into the conversation.
+
+\`\`\`bash
+# 1. Is the proxy already up?
+curl -fsS "http://localhost:${port}/api/health" 2>/dev/null && echo "PROXY: up" || echo "PROXY: down"
+
+# 2. Does the provider config have a real provider key?
+agent_inspector_data_dir() {
+  base="\${HOME:-/tmp}"
+  if [ -n "\${AGENT_INSPECTOR_DATA_DIR:-}" ]; then
+    case "$AGENT_INSPECTOR_DATA_DIR" in /*) printf '%s
+' "$AGENT_INSPECTOR_DATA_DIR" ;; *) printf '%s
+' "$base/$AGENT_INSPECTOR_DATA_DIR" ;; esac
+  elif [ -n "\${AGENT_INSPECTOR_CONFIG_DIR:-}" ]; then
+    case "$AGENT_INSPECTOR_CONFIG_DIR" in /*) printf '%s
+' "$AGENT_INSPECTOR_CONFIG_DIR" ;; *) printf '%s
+' "$base/$AGENT_INSPECTOR_CONFIG_DIR" ;; esac
+  elif { [ ! -e "$base/.agent-inspector/providers.json" ] && [ ! -e "$base/.agent-inspector/config.json" ] && [ ! -e "$base/.agent-inspector/logs" ] && [ ! -e "$base/.agent-inspector/chunks" ]; } && { [ -e "$base/.llm-inspector/providers.json" ] || [ -e "$base/.llm-inspector/config.json" ] || [ -e "$base/.llm-inspector/logs" ] || [ -e "$base/.llm-inspector/chunks" ]; }; then
+    printf '%s
+' "$base/.llm-inspector"
+  else
+    printf '%s
+' "$base/.agent-inspector"
+  fi
+}
+DATA_DIR="$(agent_inspector_data_dir)"
+PROVIDERS="$DATA_DIR/providers.json"
+LEGACY_CONFIG="$DATA_DIR/config.json"
+if [ -f "$PROVIDERS" ] || [ -f "$LEGACY_CONFIG" ]; then
+  if grep -qE '"apiKey"[[:space:]]*:[[:space:]]*"sk-[^"]+"' "$PROVIDERS" "$LEGACY_CONFIG" 2>/dev/null; then
+    echo "CONFIG: has key (no REPLACE placeholder)"
+  elif grep -qE '"apiKey"[[:space:]]*:[[:space:]]*"REPLACE' "$PROVIDERS" "$LEGACY_CONFIG" 2>/dev/null; then
+    echo "CONFIG: missing or has placeholder key"
+  else
+    echo "CONFIG: missing or has placeholder key"
+  fi
+else
+  echo "CONFIG: file does not exist"
+fi
+
+# 3. Is the MCP server already wired? (project .mcp.json wins)
+PROJ_MCP=".mcp.json"
+HOME_MCP="$HOME/.claude.json"
+if [ -f "$PROJ_MCP" ] && grep -q '"agent-inspector"' "$PROJ_MCP"; then
+  echo "MCP: wired in $PROJ_MCP"
+elif [ -f "$HOME_MCP" ] && grep -q '"agent-inspector"' "$HOME_MCP"; then
+  echo "MCP: wired in $HOME_MCP"
+else
+  echo "MCP: not wired"
+fi
+\`\`\`
+
+\`\`\`powershell
+# Windows PowerShell \u2014 single-quoted so $env: expands correctly
+$port = ${port}
+function Resolve-AgentInspectorDataDir {
+  $base = $env:USERPROFILE
+  if (-not $base) { $base = $env:APPDATA }
+  if (-not $base) { $base = 'C:\\' }
+  if ($env:AGENT_INSPECTOR_DATA_DIR) {
+    if ([System.IO.Path]::IsPathRooted($env:AGENT_INSPECTOR_DATA_DIR)) { return $env:AGENT_INSPECTOR_DATA_DIR }
+    return (Join-Path $base $env:AGENT_INSPECTOR_DATA_DIR)
+  }
+  if ($env:AGENT_INSPECTOR_CONFIG_DIR) {
+    if ([System.IO.Path]::IsPathRooted($env:AGENT_INSPECTOR_CONFIG_DIR)) { return $env:AGENT_INSPECTOR_CONFIG_DIR }
+    return (Join-Path $base $env:AGENT_INSPECTOR_CONFIG_DIR)
+  }
+  $current = Join-Path $base '.agent-inspector'
+  $legacy = Join-Path $base '.llm-inspector'
+  $currentHasState = (Test-Path (Join-Path $current 'providers.json')) -or (Test-Path (Join-Path $current 'config.json')) -or (Test-Path (Join-Path $current 'logs')) -or (Test-Path (Join-Path $current 'chunks'))
+  $legacyHasState = (Test-Path (Join-Path $legacy 'providers.json')) -or (Test-Path (Join-Path $legacy 'config.json')) -or (Test-Path (Join-Path $legacy 'logs')) -or (Test-Path (Join-Path $legacy 'chunks'))
+  if (-not $currentHasState -and $legacyHasState) {
+    return $legacy
+  }
+  return $current
+}
+$dataDir = Resolve-AgentInspectorDataDir
+$providers = Join-Path $dataDir 'providers.json'
+$legacyConfig = Join-Path $dataDir 'config.json'
+
+# 1. Is the proxy already up?
+try {
+  $null = Invoke-RestMethod -Uri "http://localhost:$port/api/health" -TimeoutSec 2 -ErrorAction Stop
+  Write-Host 'PROXY: up'
+} catch {
+  Write-Host 'PROXY: down'
+}
+
+# 2. Does the config have a real provider key?
+if ((Test-Path $providers) -or (Test-Path $legacyConfig)) {
+  $content = ''
+  if (Test-Path $providers) { $content += Get-Content $providers -Raw }
+  if (Test-Path $legacyConfig) { $content += Get-Content $legacyConfig -Raw }
+  if ($content -match '"apiKey"[[:space:]]*:[[:space:]]*"(sk-[^"]+)"') {
+    Write-Host 'CONFIG: has key'
+  } elseif ($content -match 'REPLACE') {
+    Write-Host 'CONFIG: has placeholder key'
+  } else {
+    Write-Host 'CONFIG: missing key'
+  }
+} else {
+  Write-Host 'CONFIG: file does not exist'
+}
+
+# 3. Is the MCP server already wired? (project .mcp.json wins)
+$projMcp = Join-Path (Get-Location) '.mcp.json'
+$homeMcp = Join-Path $env:USERPROFILE '.claude.json'
+if ((Test-Path $projMcp) -and (Select-String -Path $projMcp -Pattern 'agent-inspector' -Quiet)) {
+  Write-Host "MCP: wired in $projMcp"
+} elseif ((Test-Path $homeMcp) -and (Select-String -Path $homeMcp -Pattern 'agent-inspector' -Quiet)) {
+  Write-Host "MCP: wired in $homeMcp"
+} else {
+  Write-Host 'MCP: not wired'
+}
+\`\`\`
+
+**DO:** Summarize the three checks in one line, then use \`AskUserQuestion\` to ask whether to skip the corresponding phases.
+
+> **PAUSE** \u2014 call \`AskUserQuestion\` with:
+> - header: \`Skip done\`
+> - question: \`Proxy/CONFIG/MCP state: <summary>. Skip the phases that are already done?\`
+> - options: \`["Yes, skip what's done", "No, walk me through everything again"]\`
+> Wait for the answer before moving to Preflight.
+
+---
+
+## Preflight
+
+**EXPLAIN:** "Quick env sanity check \u2014 make sure Node and Claude Code are present."
+
+**DO:** Run the platform-appropriate commands below.
+
+\`\`\`bash
+# Unix / macOS / WSL
+node --version                                       # expect >= 18
+command -v claude >/dev/null && echo "claude-code: present" || echo "claude-code: not detected"
+\`\`\`
+
+\`\`\`powershell
+# Windows PowerShell \u2014 single-quoted so $env: expands correctly
+node --version                                       # expect >= 18
+$null = Get-Command claude -ErrorAction SilentlyContinue
+if ($null) { Write-Host 'claude-code: present' } else { Write-Host 'claude-code: not detected' }
+\`\`\`
+
+> **PAUSE** \u2014 if Node is older than 18, ask the user to install a newer version (https://nodejs.org) before continuing. Use \`AskUserQuestion\` with header \`Node version\`.
+
+---
+
+## Phase 1: Welcome
+
+**EXPLAIN:**
+
+\`\`\`
+## Welcome to Agent Inspector!
+
+Agent Inspector is an agent observability and knowledge-capture platform for AI coding tools. The \`agent-inspector\` CLI runs a transparent local proxy + Web UI, so you can see every model request and response: system prompts, tool definitions, message history, SSE streaming chunks, and token counts captured live in a browser tab.
+
+**What we'll do in the next ~10 minutes:**
+1. Add your first LLM provider (Anthropic or OpenAI key)
+2. Start the proxy
+3. Wire your AI tool to use it
+4. Capture a first request end-to-end
+5. Tour the key UI affordances
+
+Ready? Let's start with the provider.
+\`\`\`
+
+> **PAUSE** \u2014 use \`AskUserQuestion\` with header \`Ready?\` and options \`["Yes, let's go", "Wait, I have a question"]\`. Wait for the user before continuing.
+
+---
+
+## Phase 2: Provider setup
+
+**EXPLAIN:** "A 'provider' is an upstream LLM endpoint \u2014 Anthropic, OpenAI, MiniMax, etc. agent-inspector routes each request to the right upstream based on the model name. You need at least one provider configured for the proxy to forward traffic."
+
+**DO:** First, re-check whether \`<dataDir>/providers.json\` already has a real key (Phase 0 may have raced with a manual edit). Use the same data-dir resolution and \`grep -qE '"apiKey":"sk-'\` (bash) or \`Select-String\` (PowerShell) check from Phase 0. If a real key is present, skip the rest of this phase.
+
+**DO:** If no real key, ask the user for the provider type and API key via \`AskUserQuestion\`. The question should be a free-form text field (no fixed options) \u2014 the API key is a secret, so don't echo it back in the question UI.
+
+\`\`\`bash
+# After collecting the key, write the config
+agent_inspector_data_dir() {
+  base="\${HOME:-/tmp}"
+  if [ -n "\${AGENT_INSPECTOR_DATA_DIR:-}" ]; then
+    case "$AGENT_INSPECTOR_DATA_DIR" in /*) printf '%s
+' "$AGENT_INSPECTOR_DATA_DIR" ;; *) printf '%s
+' "$base/$AGENT_INSPECTOR_DATA_DIR" ;; esac
+  elif [ -n "\${AGENT_INSPECTOR_CONFIG_DIR:-}" ]; then
+    case "$AGENT_INSPECTOR_CONFIG_DIR" in /*) printf '%s
+' "$AGENT_INSPECTOR_CONFIG_DIR" ;; *) printf '%s
+' "$base/$AGENT_INSPECTOR_CONFIG_DIR" ;; esac
+  elif { [ ! -e "$base/.agent-inspector/providers.json" ] && [ ! -e "$base/.agent-inspector/config.json" ] && [ ! -e "$base/.agent-inspector/logs" ] && [ ! -e "$base/.agent-inspector/chunks" ]; } && { [ -e "$base/.llm-inspector/providers.json" ] || [ -e "$base/.llm-inspector/config.json" ] || [ -e "$base/.llm-inspector/logs" ] || [ -e "$base/.llm-inspector/chunks" ]; }; then
+    printf '%s
+' "$base/.llm-inspector"
+  else
+    printf '%s
+' "$base/.agent-inspector"
+  fi
+}
+DATA_DIR="$(agent_inspector_data_dir)"
+mkdir -p "$DATA_DIR"
+PROVIDERS="$DATA_DIR/providers.json"
+NOW="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+cat > "$PROVIDERS" <<JSON
+{
+  "providers": [
+    {
+      "id": "onboard-anthropic",
+      "name": "Anthropic",
+      "apiKey": "REPLACE_ME_BEFORE_WRITING",
+      "models": ["claude-sonnet-4-5-20250929"],
+      "format": "anthropic",
+      "anthropicBaseUrl": "https://api.anthropic.com",
+      "openaiBaseUrl": "",
+      "authHeader": "bearer",
+      "createdAt": "$NOW",
+      "updatedAt": "$NOW"
+    }
+  ]
+}
+JSON
+# Then patch the apiKey with the user-provided value (use jq if available)
+\`\`\`
+
+\`\`\`powershell
+# Windows PowerShell \u2014 single-quoted so $env: expands correctly
+function Resolve-AgentInspectorDataDir {
+  $base = $env:USERPROFILE
+  if (-not $base) { $base = $env:APPDATA }
+  if (-not $base) { $base = 'C:\\' }
+  if ($env:AGENT_INSPECTOR_DATA_DIR) {
+    if ([System.IO.Path]::IsPathRooted($env:AGENT_INSPECTOR_DATA_DIR)) { return $env:AGENT_INSPECTOR_DATA_DIR }
+    return (Join-Path $base $env:AGENT_INSPECTOR_DATA_DIR)
+  }
+  if ($env:AGENT_INSPECTOR_CONFIG_DIR) {
+    if ([System.IO.Path]::IsPathRooted($env:AGENT_INSPECTOR_CONFIG_DIR)) { return $env:AGENT_INSPECTOR_CONFIG_DIR }
+    return (Join-Path $base $env:AGENT_INSPECTOR_CONFIG_DIR)
+  }
+  $current = Join-Path $base '.agent-inspector'
+  $legacy = Join-Path $base '.llm-inspector'
+  $currentHasState = (Test-Path (Join-Path $current 'providers.json')) -or (Test-Path (Join-Path $current 'config.json')) -or (Test-Path (Join-Path $current 'logs')) -or (Test-Path (Join-Path $current 'chunks'))
+  $legacyHasState = (Test-Path (Join-Path $legacy 'providers.json')) -or (Test-Path (Join-Path $legacy 'config.json')) -or (Test-Path (Join-Path $legacy 'logs')) -or (Test-Path (Join-Path $legacy 'chunks'))
+  if (-not $currentHasState -and $legacyHasState) {
+    return $legacy
+  }
+  return $current
+}
+$dir  = Resolve-AgentInspectorDataDir
+$file = Join-Path $dir 'providers.json'
+New-Item -ItemType Directory -Force -Path $dir | Out-Null
+$now = (Get-Date).ToUniversalTime().ToString('o')
+$json = @{
+  providers = @(
+    @{
+      id = 'onboard-anthropic'
+      name = 'Anthropic'
+      apiKey = 'REPLACE_ME_BEFORE_WRITING'
+      models = @('claude-sonnet-4-5-20250929')
+      format = 'anthropic'
+      anthropicBaseUrl = 'https://api.anthropic.com'
+      openaiBaseUrl = ''
+      authHeader = 'bearer'
+      createdAt = $now
+      updatedAt = $now
+    }
+  )
+} | ConvertTo-Json -Depth 5
+$json | Set-Content -Path $file -Encoding UTF8
+# Then patch the apiKey with the user-provided value
+\`\`\`
+
+**DO:** Patch the placeholder with the actual key using \`jq\` (preferred) or a simple \`sed\`. Then read the file back to confirm the key is no longer \`REPLACE_ME_BEFORE_WRITING\`.
+
+**DO:** If the user declines to provide a key in the AskUserQuestion (selects "Skip for now"), do **not** write a placeholder config. Tell the user that Phase 5 (First capture) will be skipped, and that they can re-run the skill after adding a key.
+
+> **PAUSE** \u2014 use \`AskUserQuestion\` with header \`Provider key\` and options \`["Key is in, continue", "Skip for now, I'll add it later"]\`. Wait for the answer.
+
+---
+
+## Phase 3: Start proxy
+
+**EXPLAIN:** "Time to start the proxy. It binds to port ${port} by default, reuses an already-running healthy agent-inspector, and prints the URL. Use \`--force-restart\` only when you intentionally want to replace the existing process."
+
+**DO:** Skip this phase entirely if the Phase 0 health check already reported \`PROXY: up\` and the user opted to skip done phases.
+
+**DO:** Otherwise, start the proxy with the explicit \`--background --no-open\` flags. On Windows, resolve the npm shim first and launch it through \`Start-Process -WindowStyle Hidden\` so setup does not flash a command window.
+
+\`\`\`bash
+# Unix / macOS / WSL
+agent-inspector --background --no-open > /tmp/agent-inspector.log 2>&1
+\`\`\`
+
+\`\`\`powershell
+# Windows PowerShell \u2014 single-quoted so $env: expands correctly.
+# Locate the binary on PATH first (works for npm, pnpm, yarn, volta, fnm).
+# If not on PATH, fall back to the common npm global shim at $env:APPDATA.
+# As a last resort, let cmd /c resolve it through PATHEXT.
+$log = Join-Path $env:TEMP 'agent-inspector.log'
+$err = Join-Path $env:TEMP 'agent-inspector.err.log'
+$found = Get-Command agent-inspector -ErrorAction SilentlyContinue
+if ($found) {
+  $shim = $found.Source
+  $args = '--background','--no-open'
+} elseif (Test-Path (Join-Path $env:APPDATA 'npm/agent-inspector.cmd')) {
+  $shim = Join-Path $env:APPDATA 'npm/agent-inspector.cmd'
+  $args = '--background','--no-open'
+} else {
+  # bin not on PATH and not at the default npm prefix \u2014 let cmd resolve it
+  $shim = 'cmd.exe'
+  $args = '/c','agent-inspector','--background','--no-open'
+}
+Start-Process -FilePath $shim -ArgumentList $args -RedirectStandardOutput $log -RedirectStandardError $err -WindowStyle Hidden
+\`\`\`
+
+Then wait for the port to be ready:
+
+\`\`\`bash
+for i in $(seq 1 20); do
+  curl -fsS "http://localhost:${port}/api/health" >/dev/null 2>&1 && echo "ready" && break
+  sleep 0.5
+done
+\`\`\`
+
+**DO:** Hit the health endpoint to confirm the proxy is alive:
+
+\`\`\`bash
+curl -sS "http://localhost:${port}/api/health"
+\`\`\`
+
+> **PAUSE** \u2014 if the health check fails, show the user the log file (\`/tmp/agent-inspector.log\` or \`%TEMP%\\agent-inspector.log\`) and diagnose. Common issues: another process on the port, firewall, missing providers. Use \`AskUserQuestion\` with header \`Proxy up?\` and options \`["Yes, proxy is up", "No, I see an error in the log"]\`. Wait for the answer.
+
+---
+
+## Phase 4: Wire tool
+
+**EXPLAIN:** "Now we tell your AI tool to send traffic through the proxy instead of directly to the upstream API. The exact env var depends on which tool you have."
+
+**DO:** Based on the \`Environment detected\` block at the top of this skill, print the matching wiring command. Examples for each supported tool:
+
+\`\`\`bash
+# Claude Code
+export ANTHROPIC_BASE_URL=http://localhost:${port}/proxy
+claude
+
+# OpenCode
+export LLM_BASE_URL=http://localhost:${port}/proxy
+opencode
+
+# MiMo Code
+export OPENAI_BASE_URL=http://localhost:${port}/proxy
+mimo
+
+# Cursor / Cody \u2014 set the OpenAI base URL in each tool's settings panel to http://localhost:${port}/proxy
+\`\`\`
+
+For a tool that wasn't auto-detected, fall through to the generic curl test in the next phase \u2014 the user can wire their tool later.
+
+> **PAUSE** \u2014 use \`AskUserQuestion\` with header \`Tool wired?\` and options \`["Yes, env var is set, claude is running", "No, I'm going to use the curl test instead"]\`. Wait for the answer.
+
+---
+
+## Phase 4.5: Wire MCP server
+
+**EXPLAIN:** "The proxy also exposes an MCP server at \`http://localhost:${port}/api/mcp\`. Your AI agent can query logs, replay requests, and test providers through it \u2014 no need to leave the editor."
+
+**DO:** Skip this phase if Phase 0 reported \`MCP: wired in <path>\` and the user opted to skip done phases.
+
+**DO:** Otherwise, check the project-level \`.mcp.json\` first (preferred \u2014 modern Claude Code convention), then fall back to \`~/.claude.json\`. Use the \`Read\` tool to inspect; do **not** \`cat\` a 40 KB file into the conversation.
+
+If neither has an \`agent-inspector\` entry, add one. The simplest path is to write to project \`.mcp.json\` (create it if missing):
+
+\`\`\`json
+// .mcp.json  (project root)
+{
+  "mcpServers": {
+    "agent-inspector": {
+      "type": "http",
+      "url": "http://localhost:${port}/api/mcp"
+    }
+  }
+}
+\`\`\`
+
+If \`mcpServers\` already exists in \`.mcp.json\`, merge the \`agent-inspector\` key into it via the \`Edit\` tool \u2014 do not overwrite other entries. If you can't create a project \`.mcp.json\` (no project root, permission, etc.), fall back to merging into \`~/.claude.json\` using the same \`Read\`/\`Edit\` pattern.
+
+**DO:** Verify the handshake. The MCP \`initialize\` request should return 200 with a \`serverInfo\` payload \u2014 that proves the server is mounted and reachable:
+
+\`\`\`bash
+curl -sS -X POST "http://localhost:${port}/api/mcp" \\
+  -H "Content-Type: application/json" \\
+  -H "Accept: application/json, text/event-stream" \\
+  -d '{
+    "jsonrpc": "2.0",
+    "id": 1,
+    "method": "initialize",
+    "params": {
+      "protocolVersion": "2025-03-26",
+      "capabilities": {},
+      "clientInfo": { "name": "onboard-check", "version": "0" }
+    }
+  }' | grep -o '"name":"agent-inspector"' && echo "handshake OK"
+\`\`\`
+
+The \`grep -o '"name":"agent-inspector"'\` extracts only the serverInfo name \u2014 do not dump the full response. If the server returns session IDs, store the \`mcp-session-id\` header from the first response and use it for the follow-up \`tools/list\` call.
+
+> **PAUSE** \u2014 use \`AskUserQuestion\` with header \`MCP OK?\` and options \`["Yes, handshake returned 200", "No, the call failed"]\`. Wait for the answer.
+
+---
+
+## Phase 5: First capture
+
+**EXPLAIN:** "Let's prove the proxy works end-to-end. We'll send one real request through it and confirm the log shows up in the API."
+
+**DO:** First, re-check the config. If the \`apiKey\` is still a \`REPLACE_ME_BEFORE_WRITING\` placeholder (user opted out in Phase 2), **skip the capture test** and tell the user to fill in their key and re-run the skill. A 401 from the upstream is fine if they did provide a real key \u2014 the proxy will still log the request.
+
+Fire a minimal Anthropic-format request through the proxy:
+
+\`\`\`bash
+curl -sS -X POST "http://localhost:${port}/proxy/v1/messages" \\
+  -H "Content-Type: application/json" \\
+  -H "anthropic-version: 2023-06-01" \\
+  -H "x-api-key: \${AGENT_INSPECTOR_API_KEY:-sk-no-key-needed-for-routing}" \\
+  -d '{"model":"claude-3-5-sonnet-20241022","max_tokens":1,"messages":[{"role":"user","content":"ping"}]}' \\
+  -o /tmp/agent-inspector-capture.json -w 'STATUS:%{http_code}\\n'
+\`\`\`
+
+**DO:** Poll the logs API for up to 5 seconds. A 200 with at least one entry means the request reached the proxy:
+
+\`\`\`bash
+for i in $(seq 1 10); do
+  resp=$(curl -sS "http://localhost:${port}/api/logs?limit=1")
+  count=$(echo "$resp" | grep -o '"total":[0-9]*' | head -1 | grep -o '[0-9]*$')
+  if [ "\${count:-0}" -ge 1 ]; then
+    echo "captured"
+    echo "$resp" | head -c 400
+    break
+  fi
+  sleep 0.5
+done
+\`\`\`
+
+**DO:** Diagnose the response based on the actual status and body. **Do not** default to "auth failure" for every 4xx.
+
+| Status | Body hint | Meaning |
+|--------|-----------|---------|
+| 200 | normal | Real success \u2014 the upstream returned data |
+| 401 | \`"unauthorized"\` or similar | Upstream rejected the key (expected with a test key) |
+| 403 | \`"Request not allowed"\` | **Proxy's allowlist** \u2014 not an auth failure, the proxy rejected the model/config. Show the user the proxy log. |
+| 403 | other text | Could be upstream ACL \u2014 different problem |
+| 5xx | anything | Upstream network error |
+
+> **PAUSE** \u2014 use \`AskUserQuestion\` with header \`Captured?\` and options matching the diagnosis above. Wait for the answer.
+
+---
+
+## Phase 6: Tour & wrap
+
+**EXPLAIN:** "Everything's working. Here's the cheat sheet for the Web UI and the supporting surfaces:"
+
+- **Web UI**: \`http://localhost:${port}/\` \u2014 collapsible log rows, per-tab Copy/Expand in the log header, Diff with Raw (request body), Diff with Previous (compare adjacent requests), Replay (re-send a request), Export (JSON ZIP).
+- **MCP server**: \`http://localhost:${port}/api/mcp\` \u2014 connect from your coding agent to query logs, replay, and test providers without leaving the editor. Look for the "MCP Ready" badge in the Web UI header.
+- **REST API**: \`/api/logs\`, \`/api/sessions\`, \`/api/providers\` \u2014 for scripting and shell-based inspection.
+- **Stop the proxy**:
+
+  \`\`\`bash
+  # Unix / macOS
+  lsof -ti:${port} | xargs -r kill -9
+
+  # Windows PowerShell \u2014 single-quoted so $env: expands correctly
+  Get-NetTCPConnection -LocalPort $port | ForEach-Object { Stop-Process -Id $_.OwningProcess -Force }
+  \`\`\`
+
+- **Re-run onboard**: \`agent-inspector onboard --force\` refreshes this skill.
+- **Full docs**: see the project README (linked from the Web UI footer).
+
+> **PAUSE** \u2014 use \`AskUserQuestion\` with header \`All set?\` and options \`["All set, I'm done", "Wait, I want to revisit a phase"]\`. Wait for the answer.
+
+You're done. Happy inspecting.
+`;
+}
+var REQUIRED_PHASE_HEADINGS;
+var init_skill_onboard = __esm({
+  "src/cli/templates/skill-onboard.ts"() {
+    "use strict";
+    REQUIRED_PHASE_HEADINGS = [
+      "Phase 0: Idempotency check",
+      "Preflight",
+      "Phase 1: Welcome",
+      "Phase 2: Provider setup",
+      "Phase 3: Start proxy",
+      "Phase 4: Wire tool",
+      "Phase 4.5: Wire MCP server",
+      "Phase 5: First capture",
+      "Phase 6: Tour & wrap"
+    ];
+  }
+});
+
+// src/cli/onboard.ts
+var onboard_exports = {};
+__export(onboard_exports, {
+  runOnboard: () => runOnboard
+});
+import { mkdirSync, writeFileSync, existsSync as existsSync2, readFileSync } from "node:fs";
+import { homedir as homedir2 } from "node:os";
+import { dirname, join as join2 } from "node:path";
+import { fileURLToPath } from "node:url";
+function parseFlags(argv) {
+  const flags = {
+    force: false,
+    dryRun: false,
+    skipProvider: false,
+    skipToolWire: false,
+    skillDir: null
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    switch (arg) {
+      case void 0:
+        continue;
+      case "--force":
+        flags.force = true;
+        break;
+      case "--dry-run":
+        flags.dryRun = true;
+        break;
+      case "--skip-provider":
+        flags.skipProvider = true;
+        break;
+      case "--skip-tool-wire":
+        flags.skipToolWire = true;
+        break;
+      case "--skill-dir": {
+        const next = argv[i + 1];
+        if (next === void 0) {
+          process.stderr.write("agent-inspector onboard: --skill-dir requires a path argument\n");
+          process.exit(2);
+        }
+        flags.skillDir = next;
+        i++;
+        break;
+      }
+      case "--help":
+      case "-h":
+        printHelp();
+        process.exit(0);
+        break;
+      default:
+        process.stderr.write(`agent-inspector onboard: unknown flag: ${arg}
+`);
+        process.exit(2);
+    }
+  }
+  return flags;
+}
+function printHelp() {
+  process.stdout.write(`agent-inspector onboard \u2014 install the agent-inspector Claude Code skill
+
+Usage:
+  agent-inspector onboard [options]
+
+Options:
+  --force              Overwrite the existing skill and slash command if they exist
+  --dry-run            Print target paths and a template preview, write nothing
+  --skip-provider      Skip the provider-setup phase in the skill body
+  --skip-tool-wire     Skip the wire-tool phase in the skill body
+  --skill-dir <path>   Override the target skill directory (default: ~/.claude/skills)
+  -h, --help           Show this help
+
+Exit codes:
+  0  success (or already installed)
+  2  invalid arguments
+  1  write failed
+`);
+}
+function resolveTargets(flags) {
+  const claudeRoot = flags.skillDir ?? join2(homedir2(), ".claude");
+  const skillDir = join2(claudeRoot, "skills", SKILL_DIR_NAME);
+  const commandsDir = join2(claudeRoot, "commands");
+  return {
+    skillFile: join2(skillDir, SKILL_FILE_NAME),
+    commandFile: join2(commandsDir, COMMAND_FILE_NAME)
+  };
+}
+function isObject(value) {
+  return typeof value === "object" && value !== null;
+}
+function buildDetectedSummary() {
+  const entries = detectAll();
+  const present = entries.filter((e) => e.result.found);
+  const absent = entries.filter((e) => !e.result.found);
+  const presentList = present.map((e) => e.displayName).join(", ") || "(none)";
+  const absentList = absent.map((e) => e.displayName).join(", ") || "(none)";
+  return `  - Detected: ${presentList}
+  - Not detected: ${absentList}`;
+}
+function runOnboard(argv) {
+  try {
+    return Promise.resolve(runOnboardSync(argv));
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`agent-inspector onboard: ${msg}
+`);
+    process.stderr.write("(run `agent-inspector onboard` again after fixing the issue)\n");
+    return Promise.resolve(0);
+  }
+}
+function runOnboardSync(argv) {
+  const flags = parseFlags(argv);
+  const { skillFile, commandFile } = resolveTargets(flags);
+  if (!flags.force && existsSync2(skillFile)) {
+    process.stdout.write(`agent-inspector onboard: already installed at ${skillFile}
+`);
+    process.stdout.write("Re-run with --force to refresh.\n");
+    return 0;
+  }
+  let version = "0.0.0";
+  try {
+    const raw = JSON.parse(readFileSync(join2(__dirname, "..", "package.json"), "utf8"));
+    if (isObject(raw) && typeof raw["version"] === "string") {
+      version = raw["version"];
+    }
+  } catch {
+  }
+  const detectedSummary = buildDetectedSummary();
+  const skillBody = renderSkillOnboard({
+    version,
+    port: DEFAULT_PORT,
+    detectedSummary
+  });
+  const commandBody = renderCommandOnboard();
+  if (flags.dryRun) {
+    process.stdout.write(`agent-inspector onboard --dry-run
+
+`);
+    process.stdout.write(`Skill target:     ${skillFile}
+`);
+    process.stdout.write(`Command target:   ${commandFile}
+
+`);
+    process.stdout.write(`Skill preview (first 5 lines + headings):
+`);
+    const previewLines = skillBody.split("\n").slice(0, 5);
+    process.stdout.write(`${previewLines.join("\n")}
+`);
+    process.stdout.write(`...
+`);
+    for (const heading of REQUIRED_PHASE_HEADINGS) {
+      process.stdout.write(`  - ${heading}
+`);
+    }
+    process.stdout.write(`
+Detected tools:
+${detectedSummary}
+`);
+    process.stdout.write(`
+No files were written.
+`);
+    return 0;
+  }
+  mkdirSync(join2(skillFile, ".."), { recursive: true });
+  mkdirSync(join2(commandFile, ".."), { recursive: true });
+  try {
+    writeFileSync(skillFile, skillBody, "utf8");
+    writeFileSync(commandFile, commandBody, "utf8");
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`agent-inspector onboard: failed to write files: ${msg}
+`);
+    return 1;
+  }
+  const firstTool = detectFirst();
+  const toolHint = firstTool !== null ? firstTool.displayName : "no known tool detected";
+  process.stdout.write(`Installed skill to:   ${skillFile}
+`);
+  process.stdout.write(`Installed command to: ${commandFile}
+`);
+  process.stdout.write(`
+Next steps:
+`);
+  process.stdout.write(`  - Open Claude Code and run: /agent-inspector:onboard
+`);
+  process.stdout.write(`  - Or refresh later: agent-inspector onboard --force
+`);
+  process.stdout.write(`  - Detected primary tool: ${toolHint}
+`);
+  return 0;
+}
+var __filename, __dirname, DEFAULT_PORT, SKILL_DIR_NAME, SKILL_FILE_NAME, COMMAND_FILE_NAME;
+var init_onboard = __esm({
+  "src/cli/onboard.ts"() {
+    "use strict";
+    init_detect_tools();
+    init_command_onboard();
+    init_skill_onboard();
+    __filename = fileURLToPath(import.meta.url);
+    __dirname = dirname(__filename);
+    DEFAULT_PORT = 25947;
+    SKILL_DIR_NAME = "agent-inspector-onboard";
+    SKILL_FILE_NAME = "SKILL.md";
+    COMMAND_FILE_NAME = process.platform === "win32" ? "agent-inspector-onboard.md" : "agent-inspector:onboard.md";
+  }
+});
+
+// src/proxy/dataDir.ts
+import { isAbsolute, join as join3 } from "node:path";
+function hasDataDirState(pathExists, dir) {
+  return pathExists(join3(dir, "providers.json")) || pathExists(join3(dir, "config.json")) || pathExists(join3(dir, "logs")) || pathExists(join3(dir, "chunks"));
+}
+function resolveDataDir(pathExists, env = process.env, platform = process.platform) {
+  const isWindows = platform === "win32";
+  const base = isWindows ? env["USERPROFILE"] ?? env["APPDATA"] ?? "C:\\" : env["HOME"] ?? "/tmp";
+  const dirEnv = env["AGENT_INSPECTOR_DATA_DIR"];
+  if (dirEnv !== void 0 && dirEnv !== "") {
+    return isAbsolute(dirEnv) ? dirEnv : join3(base, dirEnv);
+  }
+  const legacyDirEnv = env["AGENT_INSPECTOR_CONFIG_DIR"];
+  if (legacyDirEnv !== void 0 && legacyDirEnv !== "") {
+    return isAbsolute(legacyDirEnv) ? legacyDirEnv : join3(base, legacyDirEnv);
+  }
+  const currentDir = join3(base, CURRENT_DATA_DIR_NAME);
+  const legacyDir = join3(base, LEGACY_DATA_DIR_NAME);
+  return !hasDataDirState(pathExists, currentDir) && hasDataDirState(pathExists, legacyDir) ? legacyDir : currentDir;
+}
+var CURRENT_DATA_DIR_NAME, LEGACY_DATA_DIR_NAME;
+var init_dataDir = __esm({
+  "src/proxy/dataDir.ts"() {
+    "use strict";
+    CURRENT_DATA_DIR_NAME = ".agent-inspector";
+    LEGACY_DATA_DIR_NAME = ".llm-inspector";
+  }
+});
+
+// src/cli/doctor.ts
+var doctor_exports = {};
+__export(doctor_exports, {
+  buildDoctorReport: () => buildDoctorReport,
+  createDoctorDeps: () => createDoctorDeps,
+  doctorHelp: () => doctorHelp,
+  formatDoctorReport: () => formatDoctorReport,
+  parseDoctorArgs: () => parseDoctorArgs,
+  runDoctor: () => runDoctor
+});
+import { existsSync as existsSync3, readFileSync as readFileSync2, readdirSync } from "node:fs";
+import { isAbsolute as isAbsolute2, join as join4, resolve } from "node:path";
+import { createConnection } from "node:net";
+function check(name, severity, message, hint = "") {
+  return {
+    name,
+    severity,
+    message,
+    hint: hint === "" ? null : hint
+  };
+}
+function parsePort(raw) {
+  if (raw === void 0 || raw.trim() === "") return null;
+  const port = Number(raw);
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) return null;
+  return port;
+}
+function parseDoctorArgs(argv, env = process.env) {
+  const envPort = parsePort(env["PORT"]);
+  const options = {
+    port: envPort ?? DEFAULT_PORT2,
+    configDir: null,
+    providersJson: null,
+    help: false
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    switch (arg) {
+      case void 0:
+        continue;
+      case "--help":
+      case "-h":
+        options.help = true;
+        break;
+      case "--port":
+      case "-p": {
+        const parsed = parsePort(argv[i + 1]);
+        if (parsed === null) {
+          return { kind: "error", message: "doctor: --port must be an integer from 1 to 65535" };
+        }
+        options.port = parsed;
+        i++;
+        break;
+      }
+      case "--config-dir": {
+        const next = argv[i + 1];
+        if (next === void 0 || next.trim() === "") {
+          return { kind: "error", message: "doctor: --config-dir requires a path argument" };
+        }
+        options.configDir = next;
+        i++;
+        break;
+      }
+      case "--providers": {
+        const next = argv[i + 1];
+        if (next === void 0 || next.trim() === "") {
+          return { kind: "error", message: "doctor: --providers requires a JSON argument" };
+        }
+        options.providersJson = next;
+        i++;
+        break;
+      }
+      default:
+        return { kind: "error", message: `doctor: unknown option ${arg}` };
+    }
+  }
+  return { kind: "ok", options };
+}
+function isObject2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function providerCountFromParsed(value) {
+  if (Array.isArray(value)) return value.length;
+  if (isObject2(value)) {
+    const providers = value["providers"];
+    if (Array.isArray(providers)) return providers.length;
+  }
+  return null;
+}
+function providerCountFromJson(raw) {
+  try {
+    const parsed = JSON.parse(raw);
+    return providerCountFromParsed(parsed);
+  } catch {
+    return "invalid";
+  }
+}
+function resolveMaybeRelative(base, value) {
+  return isAbsolute2(value) ? value : resolve(base, value);
+}
+function resolveDefaultDataDir(env, platform, exists) {
+  return resolveDataDir(exists, env, platform);
+}
+function providerConfigCandidates(options, deps) {
+  const explicitPath = deps.env["AGENT_INSPECTOR_CONFIG_PATH"];
+  if (explicitPath !== void 0 && explicitPath !== "") {
+    return [resolveMaybeRelative(deps.cwd, explicitPath)];
+  }
+  if (options.configDir !== null) {
+    const dir = resolveMaybeRelative(deps.cwd, options.configDir);
+    return [join4(dir, "providers.json"), join4(dir, "config.json")];
+  }
+  const dataDir = resolveDefaultDataDir(deps.env, deps.platform, deps.exists);
+  return [join4(dataDir, "providers.json"), join4(dataDir, "config.json")];
+}
+function checkProviderConfig(options, deps) {
+  const providersJson = options.providersJson ?? deps.env["AGENT_INSPECTOR_PROVIDERS_JSON"] ?? null;
+  if (providersJson !== null) {
+    const count = providerCountFromJson(providersJson);
+    if (count === "invalid") {
+      return check(
+        "Provider config",
+        "fail",
+        "Provider JSON override is not valid JSON.",
+        "Fix --providers or AGENT_INSPECTOR_PROVIDERS_JSON; doctor never prints the raw value."
+      );
+    }
+    if (count !== null) {
+      return check("Provider config", "pass", `${count} provider(s) found in JSON override.`);
+    }
+    return check(
+      "Provider config",
+      "fail",
+      "Provider JSON override does not look like a provider array or { providers } object.",
+      "Use an exported providers JSON payload or configure providers in the UI."
+    );
+  }
+  const candidates = providerConfigCandidates(options, deps);
+  for (const candidate of candidates) {
+    if (!deps.exists(candidate)) continue;
+    const text = deps.readText(candidate);
+    if (text === null) {
+      return check(
+        "Provider config",
+        "fail",
+        `Provider config exists but could not be read: ${candidate}`
+      );
+    }
+    const count = providerCountFromJson(text);
+    if (count === "invalid") {
+      return check("Provider config", "fail", `Provider config is invalid JSON: ${candidate}`);
+    }
+    if (count !== null && count > 0) {
+      return check("Provider config", "pass", `${count} provider(s) configured.`);
+    }
+    return check(
+      "Provider config",
+      "warn",
+      `Provider config exists but no providers were found: ${candidate}`,
+      "Add a provider in Settings or import provider settings."
+    );
+  }
+  return check(
+    "Provider config",
+    "warn",
+    "No provider config was found.",
+    "Add a provider in the web UI, import providers, or pass --providers for this check."
+  );
+}
+async function checkProxyHealth(port, deps) {
+  const health = await deps.fetchHealth(port);
+  const url = `http://localhost:${port}`;
+  if (health.ok) {
+    return check(
+      "Proxy health",
+      "pass",
+      `agent-inspector is healthy at ${url}.`,
+      `Proxy URL: ${url}/proxy`
+    );
+  }
+  if (await deps.isPortOpen(port)) {
+    const suffix = health.status === null ? "" : ` (HTTP ${health.status})`;
+    return check(
+      "Proxy health",
+      "fail",
+      `Port ${port} is accepting connections, but /api/health is not healthy${suffix}.`,
+      "Stop that process, choose --port <n>, or start agent-inspector with --force-restart."
+    );
+  }
+  return check(
+    "Proxy health",
+    "warn",
+    `No process is listening on port ${port}.`,
+    "Start with `agent-inspector`, `agent-inspector --background`, or `bun run dev`."
+  );
+}
+function findProjectRoot(startDir, deps) {
+  let current = resolve(startDir);
+  for (let i = 0; i < 6; i++) {
+    if (deps.exists(join4(current, "package.json"))) return current;
+    const next = resolve(current, "..");
+    if (next === current) return startDir;
+    current = next;
+  }
+  return startDir;
+}
+function checkPackage(rootDir, deps) {
+  const packagePath = join4(rootDir, "package.json");
+  const text = deps.readText(packagePath);
+  if (text === null) {
+    return check("Package metadata", "warn", "package.json was not found near the CLI bundle.");
+  }
+  try {
+    const parsed = JSON.parse(text);
+    if (!isObject2(parsed)) {
+      return check("Package metadata", "warn", "package.json is not an object.");
+    }
+    const name = parsed["name"];
+    const version = parsed["version"];
+    if (typeof name === "string" && typeof version === "string") {
+      return check("Package metadata", "pass", `${name}@${version}`);
+    }
+    return check("Package metadata", "warn", "package.json is missing name or version.");
+  } catch {
+    return check("Package metadata", "warn", "package.json is not valid JSON.");
+  }
+}
+function checkExtensionSource(rootDir, deps) {
+  const extensionDir = join4(rootDir, "extensions", "chrome");
+  const missing = EXTENSION_REQUIRED_FILES.filter((file) => !deps.exists(join4(extensionDir, file)));
+  if (missing.length === 0) {
+    return check(
+      "Chrome extension source",
+      "pass",
+      "Manifest, side panel, service worker, and icons are present."
+    );
+  }
+  return check(
+    "Chrome extension source",
+    "fail",
+    `Missing ${missing.length} Chrome extension file(s): ${missing.join(", ")}`,
+    "Restore the extension files before packaging or loading unpacked."
+  );
+}
+function extensionManifestVersion(rootDir, deps) {
+  const manifestText = deps.readText(join4(rootDir, "extensions", "chrome", "manifest.json"));
+  if (manifestText === null) return null;
+  try {
+    const manifest = JSON.parse(manifestText);
+    if (!isObject2(manifest)) return null;
+    const version = manifest["version"];
+    return typeof version === "string" && version !== "" ? version : null;
+  } catch {
+    return null;
+  }
+}
+function checkExtensionPackage(rootDir, deps) {
+  const distDir = join4(rootDir, "dist", "chrome-extension");
+  const files = deps.listDir(distDir);
+  if (files === null) {
+    return check(
+      "Chrome extension package",
+      "warn",
+      "No packaged Chrome extension artifact was found.",
+      "Run `npm run extension:zip` before Chrome Web Store upload."
+    );
+  }
+  const manifestVersion = extensionManifestVersion(rootDir, deps);
+  if (manifestVersion !== null) {
+    const zipName = `agent-inspector-companion-v${manifestVersion}.zip`;
+    const checksumName = `${zipName}.sha256`;
+    const hasZip = files.includes(zipName);
+    const hasChecksum = files.includes(checksumName);
+    if (hasZip && hasChecksum) {
+      return check("Chrome extension package", "pass", `${zipName} with checksum is present.`);
+    }
+    if (hasZip) {
+      return check(
+        "Chrome extension package",
+        "warn",
+        `${zipName} exists but no .sha256 checksum was found.`,
+        "Run `npm run extension:zip` to regenerate the zip and checksum."
+      );
+    }
+    return check(
+      "Chrome extension package",
+      "warn",
+      `Current Chrome extension package was not found: ${zipName}`,
+      "Run `npm run extension:zip` before Chrome Web Store upload."
+    );
+  }
+  const zip = files.find((file) => file.endsWith(".zip"));
+  const checksum = files.find((file) => file.endsWith(".zip.sha256"));
+  if (zip !== void 0 && checksum !== void 0) {
+    return check("Chrome extension package", "pass", `${zip} with checksum is present.`);
+  }
+  if (zip !== void 0) {
+    return check(
+      "Chrome extension package",
+      "warn",
+      `${zip} exists but no .sha256 checksum was found.`,
+      "Run `npm run extension:zip` to regenerate the zip and checksum."
+    );
+  }
+  return check(
+    "Chrome extension package",
+    "warn",
+    "No Chrome extension zip artifact was found.",
+    "Run `npm run extension:zip` before Chrome Web Store upload."
+  );
+}
+async function buildDoctorReport(options, deps = createDoctorDeps()) {
+  const rootDir = findProjectRoot(deps.cwd, deps);
+  const checks = [
+    await checkProxyHealth(options.port, deps),
+    checkProviderConfig(options, deps),
+    checkPackage(rootDir, deps),
+    checkExtensionSource(rootDir, deps),
+    checkExtensionPackage(rootDir, deps)
+  ];
+  const passCount = checks.filter((item) => item.severity === "pass").length;
+  const warnCount = checks.filter((item) => item.severity === "warn").length;
+  const failCount = checks.filter((item) => item.severity === "fail").length;
+  return {
+    checks,
+    passCount,
+    warnCount,
+    failCount,
+    exitCode: failCount > 0 ? 1 : 0
+  };
+}
+function formatDoctorReport(report) {
+  const lines = ["agent-inspector doctor", ""];
+  for (const item of report.checks) {
+    lines.push(`${item.severity.toUpperCase().padEnd(4)} ${item.name}: ${item.message}`);
+    if (item.hint !== null) {
+      lines.push(`     ${item.hint}`);
+    }
+  }
+  lines.push("");
+  lines.push(
+    `Summary: ${report.passCount} pass, ${report.warnCount} warn, ${report.failCount} fail`
+  );
+  return `${lines.join("\n")}
+`;
+}
+function doctorHelp() {
+  return [
+    "agent-inspector doctor",
+    "",
+    "Usage:",
+    "  agent-inspector doctor [--port <port>] [--config-dir <dir>] [--providers <json>]",
+    "",
+    "Checks local proxy health, provider config presence, package metadata, and Chrome companion readiness.",
+    ""
+  ].join("\n");
+}
+async function fetchHealth(port) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), PROBE_TIMEOUT_MS);
+  try {
+    const response = await fetch(`http://127.0.0.1:${port}/api/health`, {
+      cache: "no-store",
+      signal: controller.signal
+    });
+    return { ok: response.ok, status: response.status };
+  } catch {
+    return { ok: false, status: null };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+function isPortOpen(port) {
+  return new Promise((resolveOpen) => {
+    const socket = createConnection({ host: "127.0.0.1", port });
+    const finish = (value) => {
+      socket.removeAllListeners();
+      socket.destroy();
+      resolveOpen(value);
+    };
+    socket.setTimeout(PROBE_TIMEOUT_MS);
+    socket.once("connect", () => finish(true));
+    socket.once("timeout", () => finish(false));
+    socket.once("error", () => finish(false));
+  });
+}
+function readText(path) {
+  try {
+    return readFileSync2(path, "utf8");
+  } catch {
+    return null;
+  }
+}
+function listDir(path) {
+  try {
+    return readdirSync(path);
+  } catch {
+    return null;
+  }
+}
+function createDoctorDeps() {
+  return {
+    env: process.env,
+    platform: process.platform,
+    cwd: process.cwd(),
+    exists: existsSync3,
+    readText,
+    listDir,
+    fetchHealth,
+    isPortOpen
+  };
+}
+async function runDoctor(argv) {
+  const parsed = parseDoctorArgs(argv);
+  if (parsed.kind === "error") {
+    process.stderr.write(`${parsed.message}
+`);
+    return 2;
+  }
+  if (parsed.options.help) {
+    process.stdout.write(doctorHelp());
+    return 0;
+  }
+  const report = await buildDoctorReport(parsed.options);
+  process.stdout.write(formatDoctorReport(report));
+  return report.exitCode;
+}
+var DEFAULT_PORT2, PROBE_TIMEOUT_MS, EXTENSION_REQUIRED_FILES;
+var init_doctor = __esm({
+  "src/cli/doctor.ts"() {
+    "use strict";
+    init_dataDir();
+    DEFAULT_PORT2 = 25947;
+    PROBE_TIMEOUT_MS = 2e3;
+    EXTENSION_REQUIRED_FILES = [
+      "manifest.json",
+      "sidepanel.html",
+      "sidepanel.js",
+      "sidepanel.css",
+      "service-worker.js",
+      "icons/icon.svg",
+      "icons/icon-16.png",
+      "icons/icon-32.png",
+      "icons/icon-48.png",
+      "icons/icon-128.png"
+    ];
+  }
+});
+
+// src/cli.ts
+import { spawn, execSync } from "node:child_process";
+import { createConnection as createConnection2 } from "node:net";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+import { dirname as dirname2, join as join5, resolve as resolvePath } from "node:path";
+var __filename2 = fileURLToPath2(import.meta.url);
+var __dirname2 = dirname2(__filename2);
+var DEFAULT_PORT3 = 25947;
+var LOCAL_PROBE_TIMEOUT_MS = 2e3;
+var subcommand = process.argv[2];
+if (subcommand === "onboard") {
+  const { runOnboard: runOnboard2 } = await Promise.resolve().then(() => (init_onboard(), onboard_exports));
+  const code = await runOnboard2(process.argv.slice(3));
+  process.exit(code);
+}
+if (subcommand === "doctor") {
+  const { runDoctor: runDoctor2 } = await Promise.resolve().then(() => (init_doctor(), doctor_exports));
+  const code = await runDoctor2(process.argv.slice(3));
+  process.exit(code);
+}
+await runStart(process.argv.slice(2));
+async function isInspectorHealthy(port) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), LOCAL_PROBE_TIMEOUT_MS);
+  try {
+    const response = await fetch(`http://127.0.0.1:${port}/api/health`, {
+      cache: "no-store",
+      signal: controller.signal
+    });
+    return response.ok;
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+function isPortAcceptingConnections(port) {
+  return new Promise((resolve2) => {
+    const socket = createConnection2({ host: "127.0.0.1", port });
+    const finish = (value) => {
+      socket.removeAllListeners();
+      socket.destroy();
+      resolve2(value);
+    };
+    socket.setTimeout(LOCAL_PROBE_TIMEOUT_MS);
+    socket.once("connect", () => finish(true));
+    socket.once("timeout", () => finish(false));
+    socket.once("error", () => finish(false));
+  });
+}
+function sleep(ms) {
+  return new Promise((resolve2) => {
+    setTimeout(resolve2, ms);
+  });
+}
+async function waitForInspectorHealthy(port, timeoutMs) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (await isInspectorHealthy(port)) return true;
+    await sleep(250);
+  }
+  return false;
+}
+function openBrowser(targetUrl) {
+  let command;
+  switch (process.platform) {
+    case "darwin":
+      command = ["open", targetUrl];
+      break;
+    case "linux":
+      command = ["xdg-open", targetUrl];
+      break;
+    case "win32":
+      command = ["cmd", "/c", "start", "", targetUrl];
+      break;
+    default:
+      break;
+  }
+  if (command === void 0) return;
+  const [bin, ...cmdArgs] = command;
+  if (bin === void 0) return;
+  const browserProcess = spawn(bin, cmdArgs, {
+    stdio: "ignore",
+    detached: true,
+    windowsHide: true
+  });
+  browserProcess.unref();
+}
+function waitForProcessExit(child) {
+  return new Promise((resolve2) => {
+    child.once("exit", (code) => {
+      resolve2(code ?? 1);
+    });
+    child.once("error", () => {
+      resolve2(1);
+    });
+  });
+}
+async function runStart(args) {
+  const envPort = process.env["PORT"];
+  const portDefault = envPort !== void 0 ? Number(envPort) : DEFAULT_PORT3;
+  let port = portDefault;
+  let open = true;
+  let openWasSpecified = false;
+  let background = false;
+  let forceRestart = false;
+  let configDir;
+  let providersJson;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i] ?? "";
+    switch (arg) {
+      case "--port":
+      case "-p":
+        port = Number(args[i + 1]);
+        i++;
+        break;
+      case "--no-open":
+        open = false;
+        openWasSpecified = true;
+        break;
+      case "--open":
+        open = true;
+        openWasSpecified = true;
+        break;
+      case "--force-restart":
+      case "--restart":
+        forceRestart = true;
+        break;
+      case "--background":
+        background = true;
+        break;
+      case "--config-dir":
+        configDir = args[i + 1];
+        i++;
+        break;
+      case "--providers":
+        providersJson = args[i + 1];
+        i++;
+        break;
+      default:
+        break;
+    }
+  }
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+    console.error(`Invalid port: ${String(port)}. Use --port <1-65535>.`);
+    process.exitCode = 1;
+    return;
+  }
+  function killProcessOnPort(targetPort) {
+    const platform = process.platform;
+    try {
+      let pids = [];
+      if (platform === "win32") {
+        const output = execSync(`netstat -ano | findstr :${targetPort}`, {
+          encoding: "utf8",
+          timeout: 5e3,
+          windowsHide: true
+        });
+        const lines = output.trim().split("\n");
+        for (const line of lines) {
+          const parts = line.trim().split(/\s+/);
+          if (parts.length >= 5) {
+            const localAddress = parts[1] ?? "";
+            const pidStr = parts[4] ?? "";
+            if (localAddress !== "" && pidStr !== "" && localAddress.includes(`:${targetPort}`)) {
+              const pid = parseInt(pidStr, 10);
+              if (!isNaN(pid) && pid > 0) {
+                pids.push(pid);
+              }
+            }
+          }
+        }
+        pids = [...new Set(pids)];
+        for (const pid of pids) {
+          try {
+            console.log(`Killing process ${pid} on port ${targetPort}...`);
+            execSync(`taskkill /PID ${pid} /F`, {
+              encoding: "utf8",
+              timeout: 5e3,
+              windowsHide: true
+            });
+          } catch {
+          }
+        }
+      } else {
+        const output = execSync(`lsof -ti:${targetPort}`, { encoding: "utf8", timeout: 5e3 });
+        const lines = output.trim().split("\n");
+        for (const line of lines) {
+          const pid = parseInt(line.trim(), 10);
+          if (!isNaN(pid) && pid > 0) {
+            pids.push(pid);
+          }
+        }
+        pids = [...new Set(pids)];
+        for (const pid of pids) {
+          try {
+            console.log(`Killing process ${pid} on port ${targetPort}...`);
+            execSync(`kill -9 ${pid}`, { encoding: "utf8", timeout: 5e3 });
+          } catch {
+          }
+        }
+      }
+    } catch {
+    }
+  }
+  process.env["PORT"] = String(port);
+  const url = `http://localhost:${port}`;
+  if (!forceRestart && await isInspectorHealthy(port)) {
+    console.log(`agent-inspector is already running at ${url}`);
+    console.log(`Use --force-restart to restart the existing instance.`);
+    if (open && openWasSpecified) {
+      openBrowser(url);
+    }
+    return;
+  }
+  if (!forceRestart && await isPortAcceptingConnections(port)) {
+    console.error(`Port ${port} is already in use, but it is not a healthy agent-inspector.`);
+    console.error(`Stop that process, choose --port <n>, or re-run with --force-restart.`);
+    process.exitCode = 1;
+    return;
+  }
+  if (forceRestart) {
+    killProcessOnPort(port);
+  }
+  console.log(`Server running at ${url}`);
+  console.log(`   Proxy: ${url}/proxy`);
+  console.log(``);
+  console.log(`Route AI coding tools through the proxy:`);
+  console.log(`   Claude Code:  ANTHROPIC_BASE_URL=${url}/proxy claude`);
+  console.log(`   OpenCode:     LLM_BASE_URL=${url}/proxy opencode`);
+  console.log(`   MiMo Code:    OPENAI_BASE_URL=${url}/proxy mimo`);
+  console.log(
+    `   Direct HTTP:  curl ${url}/proxy/v1/messages -d '{"model":"...","messages":[...]}'`
+  );
+  console.log(``);
+  console.log(`Routing environment variables:`);
+  console.log(`   ROUTES            JSON map of model prefix -> upstream URL`);
+  console.log(`   DEFAULT_UPSTREAM  Fallback upstream for unmatched models`);
+  console.log(
+    `   Example: ROUTES='{"claude-":"https://api.anthropic.com","MiniMax":"https://api.minimaxi.com/anthropic"}'`
+  );
+  if (open) {
+    openBrowser(url);
+  }
+  const outputDir = __dirname2;
+  const serverPath = join5(outputDir, "../.output/server/index.mjs");
+  const serverEnv = { ...process.env };
+  if (configDir !== void 0) {
+    let resolvedPath = join5(configDir);
+    const msysMatch = /^\\([a-z])\\(.*)$/i.exec(resolvedPath);
+    if (msysMatch !== null) {
+      const drive = (msysMatch[1] ?? "").toUpperCase();
+      const rest = msysMatch[2] ?? "";
+      resolvedPath = `${drive}:\\${rest}`;
+    } else {
+      resolvedPath = resolvePath(resolvedPath);
+    }
+    serverEnv["AGENT_INSPECTOR_CONFIG_DIR"] = resolvedPath;
+  }
+  if (providersJson !== void 0) {
+    serverEnv["AGENT_INSPECTOR_PROVIDERS_JSON"] = providersJson;
+  }
+  const serverProcess = spawn(process.execPath, [serverPath], {
+    stdio: background ? ["ignore", "ignore", "ignore"] : "inherit",
+    detached: background,
+    env: serverEnv,
+    windowsHide: background
+  });
+  if (background) {
+    serverProcess.unref();
+    if (await waitForInspectorHealthy(port, 5e3)) {
+      console.log(`agent-inspector background server is ready at ${url}`);
+      return;
+    }
+    console.error(`agent-inspector background server did not become ready at ${url}.`);
+    process.exitCode = 1;
+    return;
+  }
+  process.exitCode = await waitForProcessExit(serverProcess);
+}