@tonyclaw/agent-inspector 3.0.29 → 3.0.31

package/README.md

@@ -33,11 +33,27 @@ agent-inspector-mcp doctor
 
 Agent Inspector requires Node.js 22 or newer. Node.js 24 LTS is recommended for production use.
 
-By default, Agent Inspector binds to `127.0.0.1`. With `--host 0.0.0.0`, remote coding tools may
-use `/proxy`, while the UI, REST API, and MCP control plane remain local-only. Set
-`AGENT_INSPECTOR_CONTROL_TOKEN` for authenticated remote API/MCP clients, or explicitly set
-`AGENT_INSPECTOR_ALLOW_REMOTE_CONTROL=1` only behind a trusted firewall or loopback-only port
-mapping.
+By default, Agent Inspector binds to `127.0.0.1` and local tools need no Inspector credential.
+With `--host 0.0.0.0`, non-loopback coding tools must authenticate `/proxy` with a dedicated
+`AGENT_INSPECTOR_PROXY_TOKEN`, supplied as `Proxy-Authorization: Bearer <token>` or
+`X-Agent-Inspector-Proxy-Token: <token>`. Provider `Authorization` remains separate and is never
+accepted as the Inspector proxy credential. The UI, REST API, and MCP control plane remain
+local-only unless `AGENT_INSPECTOR_CONTROL_TOKEN` is configured for authenticated remote API/MCP
+clients. `AGENT_INSPECTOR_ALLOW_UNAUTHENTICATED_REMOTE_PROXY=1` and
+`AGENT_INSPECTOR_ALLOW_REMOTE_CONTROL=1` are temporary compatibility overrides intended only for a
+trusted firewall or loopback-only port mapping.
+
+The packaged CLI keeps the protected identity ingress enabled even on loopback because it also owns
+Host validation, CSRF enforcement, credential scoping, and first-hop byte budgets. Disabling it with
+`--no-identity-proxy` requires the explicit diagnostic-only
+`AGENT_INSPECTOR_ALLOW_UNPROTECTED_INGRESS=1` override.
+
+When exposing Inspector through a named reverse proxy, add its public hostname to the comma-separated
+`AGENT_INSPECTOR_TRUSTED_HOSTS` allowlist. Browser mutations require same-origin CSRF proof; the
+built-in UI supplies it automatically. The public ingress streams request bodies with backpressure
+and defaults to a 64 MiB hard limit and a 120 second body deadline; override these with positive
+integer byte/millisecond values in `AGENT_INSPECTOR_MAX_REQUEST_BYTES` and
+`AGENT_INSPECTOR_REQUEST_TIMEOUT_MS` when a trusted workload requires different bounds.
 
 `@tonyclaw/agent-inspector` runs the local UI, proxy, REST API, storage, and built-in
 `/api/mcp` endpoint. `@tonyclaw/agent-inspector-mcp` is the enhancement package for

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tonyclaw/agent-inspector",
-  "version": "3.0.29",
+  "version": "3.0.31",
   "type": "module",
   "description": "Agent observability and knowledge capture layer for AI coding tools.",
   "license": "MIT",
@@ -54,7 +54,11 @@
   "scripts": {
     "dev": "vite dev",
     "start": "node .output/cli.js",
-    "build": "vite build && bun build:cli && bun build:mcp",
+    "build": "vite build && bun build:workers && bun build:cli && bun build:mcp && bun check:bundle",
+    "build:workers": "npx esbuild src/proxy/logFinalizer.worker.ts src/proxy/sessionWorkerEntry.ts --bundle --platform=node --target=node22 --format=esm --outdir=.output/workers --external:better-sqlite3",
+    "smoke:workers": "node scripts/smoke-production-workers.mjs",
+    "smoke:packed-workers": "node scripts/smoke-packed-workers.mjs",
+    "check:bundle": "node scripts/check-client-bundle.mjs",
     "build:cli": "npx esbuild src/cli.ts --bundle --platform=node --target=node22 --format=esm --outfile=.output/cli.js",
     "build:mcp": "npx esbuild packages/agent-inspector-mcp/src/cli.ts --bundle --platform=node --target=node22 --format=esm --outfile=packages/agent-inspector-mcp/dist/cli.js",
     "postinstall": "node scripts/setup-windows-runtime.mjs && node scripts/setup-agent-skills.mjs",

package/src/cli.ts

@@ -19,7 +19,12 @@ import {
   shouldSuppressServerOutputLine,
   type ServerOutputFilterContext,
 } from "./cli/startupOutput.js";
-import { startIdentityProxy } from "./proxy/identityProxy.js";
+import {
+  closeIdentityProxyGracefully,
+  forceCloseIdentityProxy,
+  startIdentityProxy,
+  stopIdentityProxyAdmission,
+} from "./proxy/identityProxy.js";
 import { findPidsByPort, killPid, openUrlCommand } from "./proxy/platformCommands.js";
 
 const __filename = fileURLToPath(import.meta.url);
@@ -36,6 +41,8 @@ const DEFAULT_BIND_HOST = "127.0.0.1";
 const LOCAL_PROBE_TIMEOUT_MS = 2000;
 const BRANDED_WINDOWS_RUNTIME_EXE = "agent-inspector.exe";
 const DEFAULT_CAPTURE_MODE = "simple";
+const DEFAULT_SHUTDOWN_DEADLINE_MS = 15_000;
+const SUPERVISOR_SHUTDOWN_GRACE_MS = 2_000;
 
 type CaptureMode = "simple" | "full";
 
@@ -232,10 +239,20 @@ function printAccessHints(port: number, host?: string): void {
     console.log(line);
   }
   if (!isLoopbackHost(host)) {
+    const proxyTokenConfigured = (process.env["AGENT_INSPECTOR_PROXY_TOKEN"] ?? "") !== "";
+    const legacyProxyEnabled =
+      process.env["AGENT_INSPECTOR_ALLOW_UNAUTHENTICATED_REMOTE_PROXY"] === "1";
+    if (proxyTokenConfigured) {
+      console.log("   Remote proxy:   dedicated token authentication enabled");
+    } else if (legacyProxyEnabled) {
+      console.warn("   Remote proxy:   UNAUTHENTICATED compatibility mode enabled");
+    } else {
+      console.warn("   Remote proxy:   blocked until AGENT_INSPECTOR_PROXY_TOKEN is configured");
+    }
     if (process.env["AGENT_INSPECTOR_ALLOW_REMOTE_CONTROL"] === "1") {
       console.warn("   Control plane:  REMOTE ACCESS ENABLED by administrator override");
     } else {
-      console.log("   Control plane:  local only; remote clients may use /proxy");
+      console.log("   Control plane:  local only by default");
       if ((process.env["AGENT_INSPECTOR_CONTROL_TOKEN"] ?? "") !== "") {
         console.log("   Remote API:     Bearer token authentication enabled");
       }
@@ -243,6 +260,15 @@ function printAccessHints(port: number, host?: string): void {
   }
 }
 
+function readPositiveIntegerEnv(name: string): number | undefined {
+  const raw = process.env[name];
+  if (raw === undefined || raw.trim().length === 0) return undefined;
+  const parsed = Number(raw);
+  if (Number.isSafeInteger(parsed) && parsed > 0) return parsed;
+  console.warn(`Ignoring invalid ${name}=${raw}; expected a positive integer.`);
+  return undefined;
+}
+
 type BackgroundSupervisorOptions = {
   port: number;
   host: string | undefined;
@@ -313,6 +339,15 @@ async function tryStartIdentityProxy(
       restrictRemoteControl: !isLoopbackHost(listenHost),
       allowRemoteControl: process.env["AGENT_INSPECTOR_ALLOW_REMOTE_CONTROL"] === "1",
       controlToken: process.env["AGENT_INSPECTOR_CONTROL_TOKEN"],
+      proxyToken: process.env["AGENT_INSPECTOR_PROXY_TOKEN"],
+      allowUnauthenticatedRemoteProxy:
+        process.env["AGENT_INSPECTOR_ALLOW_UNAUTHENTICATED_REMOTE_PROXY"] === "1",
+      trustedHosts: (process.env["AGENT_INSPECTOR_TRUSTED_HOSTS"] ?? "")
+        .split(",")
+        .map((host) => host.trim())
+        .filter((host) => host.length > 0),
+      maxRequestBytes: readPositiveIntegerEnv("AGENT_INSPECTOR_MAX_REQUEST_BYTES"),
+      requestTimeoutMs: readPositiveIntegerEnv("AGENT_INSPECTOR_REQUEST_TIMEOUT_MS"),
     });
     return server;
   } catch (err) {
@@ -475,13 +510,9 @@ async function runStart(args: string[]): Promise<void> {
     return;
   }
 
-  if (
-    !enableIdentityProxy &&
-    !isLoopbackHost(host) &&
-    process.env["AGENT_INSPECTOR_ALLOW_REMOTE_CONTROL"] !== "1"
-  ) {
+  if (!enableIdentityProxy && process.env["AGENT_INSPECTOR_ALLOW_UNPROTECTED_INGRESS"] !== "1") {
     console.error(
-      "Refusing an unprotected remote bind with --no-identity-proxy. Keep the identity proxy enabled or set AGENT_INSPECTOR_ALLOW_REMOTE_CONTROL=1 explicitly.",
+      "Refusing --no-identity-proxy because it also disables Host, CSRF, credential-scope, and first-hop budget enforcement. Keep the protected ingress enabled or set AGENT_INSPECTOR_ALLOW_UNPROTECTED_INGRESS=1 explicitly for temporary diagnostics.",
     );
     process.exitCode = 1;
     return;
@@ -663,6 +694,10 @@ async function runStart(args: string[]): Promise<void> {
   serverEnv["AGENT_INSPECTOR_PUBLIC_PORT"] = String(port);
   serverEnv["PROXY_PORT"] = String(port);
   serverEnv["AGENT_INSPECTOR_CAPTURE_MODE"] = captureMode;
+  const workerDir = join(__dirname, "workers");
+  if (existsSync(workerDir)) {
+    serverEnv["AGENT_INSPECTOR_WORKER_DIR"] = workerDir;
+  }
   const serverProcess = spawn(serverCommand.command, serverCommand.args, {
     stdio: background ? ["ignore", "ignore", "ignore"] : ["ignore", "pipe", "pipe"],
     detached: background,
@@ -692,6 +727,41 @@ async function runStart(args: string[]): Promise<void> {
     port: number;
     server: import("node:http").Server;
   }> = [];
+  let supervisorShutdownPromise: Promise<void> | null = null;
+  const requestSupervisorShutdown = (signal: "SIGINT" | "SIGTERM"): void => {
+    if (supervisorShutdownPromise !== null) return;
+    for (const proxy of identityProxies) stopIdentityProxyAdmission(proxy.server);
+    serverProcess.kill(signal);
+
+    const childDeadline =
+      readPositiveIntegerEnv("AGENT_INSPECTOR_SHUTDOWN_TIMEOUT_MS") ?? DEFAULT_SHUTDOWN_DEADLINE_MS;
+    let deadline: ReturnType<typeof setTimeout> | null = null;
+    let forced = false;
+    const graceful = Promise.all([
+      serverExit.then(() => undefined),
+      ...identityProxies.map(async (proxy) => await closeIdentityProxyGracefully(proxy.server)),
+    ]).then(() => undefined);
+    const timedOut = new Promise<void>((resolve) => {
+      deadline = setTimeout(() => {
+        forced = true;
+        for (const proxy of identityProxies) forceCloseIdentityProxy(proxy.server);
+        if (serverProcess.exitCode === null) serverProcess.kill("SIGKILL");
+        resolve();
+      }, childDeadline + SUPERVISOR_SHUTDOWN_GRACE_MS);
+    });
+    supervisorShutdownPromise = Promise.race([graceful, timedOut])
+      .finally(() => {
+        if (deadline !== null) clearTimeout(deadline);
+      })
+      .then(() => {
+        if (forced) process.exitCode = 1;
+      });
+  };
+  const handleSigint = (): void => requestSupervisorShutdown("SIGINT");
+  const handleSigterm = (): void => requestSupervisorShutdown("SIGTERM");
+  const currentSupervisorShutdown = (): Promise<void> | null => supervisorShutdownPromise;
+  process.on("SIGINT", handleSigint);
+  process.on("SIGTERM", handleSigterm);
   if (enableIdentityProxy) {
     const primaryProxy = await tryStartIdentityProxy(port, upstreamPort, host, upstreamHost);
     if (primaryProxy !== null) {
@@ -759,7 +829,12 @@ async function runStart(args: string[]): Promise<void> {
 
   process.exitCode = await serverExit;
 
-  for (const proxy of identityProxies) {
-    await new Promise<void>((resolve) => proxy.server.close(() => resolve()));
+  const activeSupervisorShutdown = currentSupervisorShutdown();
+  if (activeSupervisorShutdown !== null) {
+    await activeSupervisorShutdown;
+  } else {
+    await Promise.all(identityProxies.map((proxy) => closeIdentityProxyGracefully(proxy.server)));
   }
+  process.off("SIGINT", handleSigint);
+  process.off("SIGTERM", handleSigterm);
 }

package/src/components/OnboardingBanner.tsx

@@ -3,28 +3,31 @@ import { useState, type JSX } from "react";
 import { useOnboarding } from "../lib/useOnboarding";
 
 /**
- * First-launch onboarding banner. Shows once on a fresh install and persists
- * dismissal through the server runtime config.
+ * Presentational onboarding surface, exported so responsive and accessibility
+ * behavior can be verified without runtime configuration state.
  */
-export function OnboardingBanner(): JSX.Element | null {
-  const { hasSeenOnboarding, isLoading, markSeen } = useOnboarding();
-  const [expanded, setExpanded] = useState(false);
-
-  if (isLoading || hasSeenOnboarding) return null;
-
+export function OnboardingTip({
+  expanded,
+  onToggle,
+  onDismiss,
+}: {
+  expanded: boolean;
+  onToggle: () => void;
+  onDismiss: () => void;
+}): JSX.Element {
   const detailClass = expanded ? "grid" : "hidden sm:grid";
 
   return (
     <div
       role="note"
       aria-label="Onboarding tip"
-      className="mx-4 mt-2 mb-1 rounded-md border border-amber-500/30 bg-[#130d04] px-3 py-2 text-sm shadow-[0_12px_40px_rgba(0,0,0,0.16)]"
+      className="mx-3 mt-2 mb-1 rounded-md border border-warning/30 bg-warning/10 px-3 py-2 text-sm shadow-sm sm:mx-4"
     >
       <div className="flex items-start gap-3">
-        <Info className="mt-0.5 size-4 shrink-0 text-amber-300" aria-hidden="true" />
+        <Info className="mt-0.5 size-4 shrink-0 text-warning" aria-hidden="true" />
         <div className="min-w-0 flex-1">
           <div className="flex min-w-0 flex-wrap items-center gap-x-2 gap-y-1">
-            <span className="font-medium text-amber-200">Inspector ready</span>
+            <span className="font-medium text-foreground">Inspector ready</span>
             <span className="hidden truncate text-xs text-muted-foreground sm:inline">
               Request, response, tool, timing, token, replay, and memory signals are active.
             </span>
@@ -45,8 +48,8 @@ export function OnboardingBanner(): JSX.Element | null {
         </div>
         <button
           type="button"
-          onClick={() => setExpanded((value) => !value)}
-          className="inline-flex h-8 shrink-0 items-center gap-1 rounded-md border border-amber-500/30 px-2 text-xs text-amber-200 transition-colors hover:bg-amber-500/10 sm:hidden"
+          onClick={onToggle}
+          className="inline-flex h-8 shrink-0 items-center gap-1 rounded-md border border-warning/35 px-2 text-xs font-medium text-foreground transition-colors hover:bg-warning/15 focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none sm:hidden"
           aria-expanded={expanded}
           aria-label={expanded ? "Hide onboarding details" : "Show onboarding details"}
         >
@@ -56,10 +59,8 @@ export function OnboardingBanner(): JSX.Element | null {
         </button>
         <button
           type="button"
-          onClick={() => {
-            void markSeen();
-          }}
-          className="hidden h-8 shrink-0 items-center gap-1.5 rounded-md border border-amber-500/40 px-3 text-xs text-amber-200 transition-colors hover:bg-amber-500/10 sm:inline-flex"
+          onClick={onDismiss}
+          className="hidden h-8 shrink-0 items-center gap-1.5 rounded-md border border-warning/40 px-3 text-xs font-medium text-foreground transition-colors hover:bg-warning/15 focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none sm:inline-flex"
           aria-label="Dismiss onboarding tip"
         >
           <Check className="size-3.5" />
@@ -67,10 +68,8 @@ export function OnboardingBanner(): JSX.Element | null {
         </button>
         <button
           type="button"
-          onClick={() => {
-            void markSeen();
-          }}
-          className="-m-1 shrink-0 p-1 text-muted-foreground transition-colors hover:text-foreground"
+          onClick={onDismiss}
+          className="-m-1 shrink-0 rounded-sm p-1 text-muted-foreground transition-colors hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none"
           aria-label="Dismiss"
         >
           <X className="size-3.5" />
@@ -79,3 +78,24 @@ export function OnboardingBanner(): JSX.Element | null {
     </div>
   );
 }
+
+/**
+ * First-launch onboarding banner. Shows once on a fresh install and persists
+ * dismissal through the server runtime config.
+ */
+export function OnboardingBanner(): JSX.Element | null {
+  const { hasSeenOnboarding, isLoading, markSeen } = useOnboarding();
+  const [expanded, setExpanded] = useState(false);
+
+  if (isLoading || hasSeenOnboarding) return null;
+
+  return (
+    <OnboardingTip
+      expanded={expanded}
+      onToggle={() => setExpanded((value) => !value)}
+      onDismiss={() => {
+        void markSeen();
+      }}
+    />
+  );
+}