@tonyclaw/agent-inspector 2.0.0

package/src/cli.ts

@@ -0,0 +1,345 @@
+#!/usr/bin/env node
+import { spawn, execSync, type ChildProcess } from "node:child_process";
+import { createConnection } from "node:net";
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve as resolvePath } from "node:path";
+import { existsSync } from "node:fs";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const DEFAULT_PORT = 25947;
+const LOCAL_PROBE_TIMEOUT_MS = 2000;
+
+/**
+ * Subcommand router. The legacy one-liner UX (`agent-inspector` with no args,
+ * or `agent-inspector start`) starts the proxy. `agent-inspector onboard` runs
+ * the guided skill install. Unknown subcommands fall back to the legacy
+ * behavior so a stray positional arg doesn't break an old invocation.
+ */
+const subcommand = process.argv[2];
+
+if (subcommand === "onboard") {
+  const { runOnboard } = await import("./cli/onboard.js");
+  const code = await runOnboard(process.argv.slice(3));
+  process.exit(code);
+}
+
+if (subcommand === "doctor") {
+  const { runDoctor } = await import("./cli/doctor.js");
+  const code = await runDoctor(process.argv.slice(3));
+  process.exit(code);
+}
+
+await runStart(process.argv.slice(2));
+
+// -----------------------------------------------------------------------------
+// Legacy `start` behavior — start the proxy on the configured port. Extracted
+// into a function so the router above can keep the top-level flow readable.
+// -----------------------------------------------------------------------------
+async function isInspectorHealthy(port: number): Promise<boolean> {
+  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: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const socket = createConnection({ host: "127.0.0.1", port });
+    const finish = (value: boolean): void => {
+      socket.removeAllListeners();
+      socket.destroy();
+      resolve(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: number): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+async function waitForInspectorHealthy(port: number, timeoutMs: number): Promise<boolean> {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (await isInspectorHealthy(port)) return true;
+    await sleep(250);
+  }
+  return false;
+}
+
+function openBrowser(targetUrl: string): void {
+  let command: string[] | undefined;
+  // eslint-disable-next-line @typescript-eslint/switch-exhaustiveness-check
+  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:
+      // Unsupported platform - do nothing
+      break;
+  }
+  if (command === undefined) return;
+  const [bin, ...cmdArgs] = command;
+  if (bin === undefined) return;
+  const browserProcess = spawn(bin, cmdArgs, {
+    stdio: "ignore",
+    detached: true,
+    windowsHide: true,
+  });
+  browserProcess.unref();
+}
+
+function waitForProcessExit(child: ChildProcess): Promise<number> {
+  return new Promise((resolve) => {
+    child.once("exit", (code) => {
+      resolve(code ?? 1);
+    });
+    child.once("error", () => {
+      resolve(1);
+    });
+  });
+}
+
+async function runStart(args: string[]): Promise<void> {
+  const envPort = process.env["PORT"];
+  const portDefault = envPort !== undefined ? Number(envPort) : DEFAULT_PORT;
+
+  let port = portDefault;
+  let open = true;
+  let openWasSpecified = false;
+  let background = false;
+  let forceRestart = false;
+  let configDir: string | undefined;
+  let providersJson: string | undefined;
+
+  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;
+  }
+
+  /**
+   * Check if a port is in use and kill the process using it
+   */
+  function killProcessOnPort(targetPort: number): void {
+    const platform = process.platform;
+
+    try {
+      let pids: number[] = [];
+
+      if (platform === "win32") {
+        // Windows: use netstat to find PID, then taskkill
+        const output = execSync(`netstat -ano | findstr :${targetPort}`, {
+          encoding: "utf8",
+          timeout: 5000,
+          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);
+              }
+            }
+          }
+        }
+        // Remove duplicates
+        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: 5000,
+              windowsHide: true,
+            });
+          } catch {
+            // Process may have already exited
+          }
+        }
+      } else {
+        // Unix-like: use lsof
+        const output = execSync(`lsof -ti:${targetPort}`, { encoding: "utf8", timeout: 5000 });
+        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);
+          }
+        }
+        // Remove duplicates
+        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: 5000 });
+          } catch {
+            // Process may have already exited
+          }
+        }
+      }
+    } catch {
+      // No process found on port, which is fine
+    }
+  }
+
+  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);
+  }
+
+  // Compute server path
+  const outputDir = __dirname;
+  const serverPath = join(outputDir, "../.output/server/index.mjs");
+
+  // Start server with node
+  const serverEnv = { ...process.env };
+  if (configDir !== undefined) {
+    // Normalize MSYS / Git Bash paths to Windows native form.
+    // On Windows, `path.join('/c/Users/foo')` becomes `\c\Users\foo`
+    // (leading slash converted to backslash).
+    // Child processes spawned by `spawn()` won't follow that style, so
+    // rewrite `\c\...` (or any `\x\...` drive) to `C:\...` before
+    // handing the path to the proxy server. No-op on already-native
+    // Windows paths and on non-Windows platforms.
+    let resolvedPath = join(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 !== undefined) {
+    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, 5000)) {
+      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);
+}

package/src/components/OnboardingBanner.tsx

@@ -0,0 +1,67 @@
+import { Check, X } from "lucide-react";
+import type { JSX } from "react";
+import { useOnboarding } from "../lib/useOnboarding";
+
+/**
+ * First-launch onboarding banner. Shows once on a fresh install (or
+ * any user who hasn't yet dismissed it), explains the per-tab data
+ * shapes the proxy captures, and disappears forever on dismissal.
+ *
+ * The "seen" state lives in the server's runtime config — see
+ * `useOnboarding` — so the dismissal persists across browser sessions
+ * and devices for the same install.
+ */
+export function OnboardingBanner(): JSX.Element | null {
+  const { hasSeenOnboarding, isLoading, markSeen } = useOnboarding();
+
+  if (isLoading || hasSeenOnboarding) return null;
+
+  return (
+    <div
+      role="note"
+      aria-label="Onboarding tip"
+      className="mx-4 mt-2 mb-1 flex items-start gap-3 rounded-md border border-amber-500/30 bg-amber-500/5 px-4 py-3 text-sm"
+    >
+      <div className="flex-1 min-w-0">
+        <div className="font-medium text-amber-600 dark:text-amber-400 mb-1">
+          Quick tour of the log tabs
+        </div>
+        <ul className="space-y-0.5 text-muted-foreground text-xs leading-relaxed">
+          <li>
+            <strong>Request</strong> / <strong>Response</strong> — structured views of what the
+            proxy sent and received.
+          </li>
+          <li>
+            <strong>Headers</strong> — request and response headers after proxy processing.
+          </li>
+          <li>
+            <strong>Raw Headers</strong> / <strong>Raw Request</strong> /{" "}
+            <strong>Raw Response</strong> — exact bytes from the upstream provider (visible in Full
+            mode).
+          </li>
+        </ul>
+      </div>
+      <button
+        type="button"
+        onClick={() => {
+          void markSeen();
+        }}
+        className="inline-flex items-center gap-1.5 text-xs h-8 px-3 rounded-md border border-amber-500/40 text-amber-700 dark:text-amber-300 hover:bg-amber-500/10 transition-colors shrink-0"
+        aria-label="Dismiss onboarding tip"
+      >
+        <Check className="size-3.5" />
+        Got it
+      </button>
+      <button
+        type="button"
+        onClick={() => {
+          void markSeen();
+        }}
+        className="text-muted-foreground hover:text-foreground transition-colors shrink-0 p-1 -m-1"
+        aria-label="Dismiss"
+      >
+        <X className="size-3.5" />
+      </button>
+    </div>
+  );
+}