@tonyclaw/agent-inspector 3.0.45 → 3.0.47

package/src/cli.ts

@@ -8,9 +8,18 @@ import { existsSync } from "node:fs";
 import type { Readable, Writable } from "node:stream";
 import packageJson from "../package.json";
 import {
+  AGENT_INSPECTOR_BACKEND_ENV,
+  AGENT_INSPECTOR_BACKEND_HEADER,
+  BackendImplementationSchema,
+  parseBackendImplementation,
+  type BackendImplementation,
+} from "./lib/backendImplementation.js";
+import {
+  AGENT_INSPECTOR_BASE_PATH_ENV,
   AGENT_INSPECTOR_INTERNAL_STRIPPED_BASE_PATH_ENV,
   appendBasePathToOrigin,
   getConfiguredBasePath,
+  normalizePublicBasePath,
 } from "./lib/basePath.js";
 import {
   AGENT_INSPECTOR_CLI_ENTRY_ENV,
@@ -31,9 +40,12 @@ import {
   shouldSuppressServerOutputLine,
   type ServerOutputFilterContext,
 } from "./cli/startupOutput.js";
+import { resolveRustBackendPackage } from "./cli/rustBackendPackage.js";
+import { handleNamedInstanceApi } from "./cli/instanceApi.js";
 import {
   closeIdentityProxyGracefully,
   forceCloseIdentityProxy,
+  parseUiOriginAllowlist,
   startIdentityProxy,
   stopIdentityProxyAdmission,
   type ManagedInstanceControlOptions,
@@ -83,6 +95,15 @@ Global options:
   -h, --help      Show this help without starting a runtime
   -v, --version   Print the package version
 
+Start options:
+  --backend <typescript|rust> Select the backend implementation (default: typescript)
+  --backend-only, --headless  Start the API, proxy, and MCP runtime without serving the UI
+  --with-ui                  Serve the independently built UI through the protected ingress
+  --port, -p <port>          Public ingress port (default: 9527)
+  --host, -H <host>          Bind host (default: 127.0.0.1)
+  --background               Start a hidden supervisor and return after readiness
+  --no-open                  Do not open the UI after startup
+
 Run \`agent-inspector instance --help\`, \`agent-inspector onboard --help\`, or
 \`agent-inspector doctor --help\` for command-specific options.`);
 }
@@ -183,6 +204,33 @@ async function getRunningCaptureMode(
   }
 }
 
+async function getRunningBackend(
+  port: number,
+  host?: string,
+  basePath = "",
+): Promise<BackendImplementation | null> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), LOCAL_PROBE_TIMEOUT_MS);
+  try {
+    const response = await fetch(
+      appendBasePathToOrigin(urlForHost(port, probeHostForBindHost(host)), "/api/health", basePath),
+      {
+        cache: "no-store",
+        signal: controller.signal,
+      },
+    );
+    if (!response.ok) return null;
+    const header = response.headers.get(AGENT_INSPECTOR_BACKEND_HEADER);
+    if (header === null) return "typescript";
+    const parsed = BackendImplementationSchema.safeParse(header.trim().toLowerCase());
+    return parsed.success ? parsed.data : null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
 function isPortAcceptingConnections(port: number, host?: string): Promise<boolean> {
   return new Promise((resolve) => {
     const socket = createConnection({ host: probeHostForBindHost(host), port });
@@ -282,11 +330,35 @@ type ServerCommand = {
   args: string[];
 };
 
-function resolveServerCommand(outputDir: string, serverPath: string): ServerCommand {
+type ServerCommandResolution =
+  | { kind: "success"; command: ServerCommand }
+  | { kind: "error"; message: string };
+
+function resolveServerCommand(
+  outputDir: string,
+  serverPath: string,
+  backend: BackendImplementation,
+): ServerCommandResolution {
+  if (backend === "rust") {
+    const resolved = resolveRustBackendPackage({ rootVersion: packageJson.version });
+    return resolved.kind === "error"
+      ? {
+          kind: "error",
+          message: `Cannot start the Rust backend (${resolved.error.code}): ${resolved.error.message}`,
+        }
+      : {
+          kind: "success",
+          command: { command: resolved.value.command, args: [...resolved.value.args] },
+        };
+  }
   const brandedRuntime = join(outputDir, BRANDED_WINDOWS_RUNTIME_EXE);
-  return process.platform === "win32" && existsSync(brandedRuntime)
-    ? { command: brandedRuntime, args: [serverPath] }
-    : { command: process.execPath, args: [serverPath] };
+  return {
+    kind: "success",
+    command:
+      process.platform === "win32" && existsSync(brandedRuntime)
+        ? { command: brandedRuntime, args: [serverPath] }
+        : { command: process.execPath, args: [serverPath] },
+  };
 }
 
 function parseCaptureMode(value: string | undefined): CaptureMode | null {
@@ -309,11 +381,26 @@ function readCaptureMode(raw: unknown): CaptureMode | null {
   return typeof value === "string" ? parseCaptureMode(value) : null;
 }
 
-function printAccessHints(port: number, host?: string, basePath = ""): void {
+function printAccessHints(
+  port: number,
+  host: string | undefined,
+  basePath: string,
+  serveUi: boolean,
+  publicOrigin: string | undefined,
+): void {
   const networkUrls = networkUrlsForBindHost(port, host);
-  for (const line of formatAccessHintLines(port, networkUrls, host, basePath)) {
+  for (const line of formatAccessHintLines(port, networkUrls, host, basePath, serveUi)) {
     console.log(line);
   }
+  if (publicOrigin !== undefined) {
+    const publicBaseUrl = appendBasePathToOrigin(publicOrigin, "/", basePath);
+    if (serveUi) console.log(`   Public UI:      ${publicBaseUrl}`);
+    console.log(`   Public control Base: ${publicBaseUrl}`);
+    console.log(`   Public agent Base:   ${publicBaseUrl}`);
+    console.log(`   Public REST API: ${appendBasePathToOrigin(publicOrigin, "/api", basePath)}`);
+    console.log(`   Public proxy:    ${appendBasePathToOrigin(publicOrigin, "/proxy", basePath)}`);
+    console.log(`   Public MCP:     ${appendBasePathToOrigin(publicOrigin, "/api/mcp", basePath)}`);
+  }
   if (!isLoopbackHost(host)) {
     const proxyTokenConfigured = (process.env["AGENT_INSPECTOR_PROXY_TOKEN"] ?? "") !== "";
     const legacyProxyEnabled =
@@ -345,7 +432,21 @@ function readPositiveIntegerEnv(name: string): number | undefined {
   return undefined;
 }
 
+function normalizeExplicitPublicOrigin(value: string | undefined): string | null | undefined {
+  if (value === undefined || value.trim().length === 0) return undefined;
+  try {
+    const parsed = new URL(value.trim());
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return null;
+    if (parsed.username.length > 0 || parsed.password.length > 0) return null;
+    if (parsed.pathname !== "/" || parsed.search.length > 0 || parsed.hash.length > 0) return null;
+    return parsed.origin;
+  } catch {
+    return null;
+  }
+}
+
 type BackgroundSupervisorOptions = {
+  backend: BackendImplementation;
   port: number;
   host: string | undefined;
   configDir: string | undefined;
@@ -353,10 +454,19 @@ type BackgroundSupervisorOptions = {
   captureMode: CaptureMode;
   enableIdentityProxy: boolean;
   legacyAliasEnabled: boolean;
+  serveUi: boolean;
 };
 
 function buildBackgroundSupervisorArgs(options: BackgroundSupervisorOptions): string[] {
-  const args = ["--no-open", "--port", String(options.port), "--mode", options.captureMode];
+  const args = [
+    "--no-open",
+    "--backend",
+    options.backend,
+    "--port",
+    String(options.port),
+    "--mode",
+    options.captureMode,
+  ];
   if (options.host !== undefined) {
     args.push("--host", options.host);
   }
@@ -372,6 +482,9 @@ function buildBackgroundSupervisorArgs(options: BackgroundSupervisorOptions): st
   if (options.legacyAliasEnabled) {
     args.push("--legacy-port");
   }
+  if (!options.serveUi) {
+    args.push("--backend-only");
+  }
   return args;
 }
 
@@ -395,17 +508,18 @@ function pickUpstreamPort(publicPort: number, legacyAliasPort: number | null): n
   return DEFAULT_UPSTREAM_PORT;
 }
 
-/** Try to start the identity proxy. Returns `null` (and prints a warning)
- *  if the listen port is already in use by another process — e.g. when
- *  restarting a previous instance that didn't shut down cleanly. The
- *  TanStack Start server keeps running either way; clients just lose the
- *  per-PID attribution until they fall back to direct port `port` access. */
+/** Try to start an identity-proxy ingress. The primary caller treats a
+ *  `null` result as fatal; only an optional compatibility alias may degrade. */
 async function tryStartIdentityProxy(
   identityPort: number,
   upstreamPort: number,
   listenHost: string,
   upstreamHost: string,
   managedInstance: ManagedInstanceControlOptions | undefined,
+  allowedUiOrigins: readonly string[],
+  uiDirectory: string | undefined,
+  publicOrigin: string | undefined,
+  backend: BackendImplementation,
 ): Promise<import("node:http").Server | null> {
   try {
     const server = await startIdentityProxy({
@@ -413,6 +527,7 @@ async function tryStartIdentityProxy(
       listenHost,
       upstreamHost,
       upstreamPort,
+      backendImplementation: backend,
       restrictRemoteControl: !isLoopbackHost(listenHost),
       allowRemoteControl: process.env["AGENT_INSPECTOR_ALLOW_REMOTE_CONTROL"] === "1",
       controlToken: process.env["AGENT_INSPECTOR_CONTROL_TOKEN"],
@@ -423,18 +538,18 @@ async function tryStartIdentityProxy(
         .split(",")
         .map((host) => host.trim())
         .filter((host) => host.length > 0),
+      allowedUiOrigins,
+      uiDirectory,
+      publicOrigin,
       maxRequestBytes: readPositiveIntegerEnv("AGENT_INSPECTOR_MAX_REQUEST_BYTES"),
       requestTimeoutMs: readPositiveIntegerEnv("AGENT_INSPECTOR_REQUEST_TIMEOUT_MS"),
       managedInstance,
+      instanceApiHandler: backend === "rust" ? handleNamedInstanceApi : undefined,
     });
     return server;
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
-    console.warn(
-      `[identity-proxy] Could not listen on port ${identityPort}: ${message}. ` +
-        `Falling back to OS-scan heuristic on port ${upstreamPort}. ` +
-        `Pass --identity-proxy-port <n> to choose another port, or --no-identity-proxy to disable.`,
-    );
+    console.warn(`[identity-proxy] Could not listen on port ${identityPort}: ${message}.`);
     return null;
   }
 }
@@ -453,6 +568,14 @@ async function runStart(args: string[]): Promise<void> {
   const envHost = process.env["NITRO_HOST"] ?? process.env["HOST"];
   const envMode =
     process.env["AGENT_INSPECTOR_CAPTURE_MODE"] ?? process.env["AGENT_INSPECTOR_MODE"];
+  const envBackend = parseBackendImplementation(process.env[AGENT_INSPECTOR_BACKEND_ENV]);
+  if (envBackend === null) {
+    console.error(
+      `Invalid ${AGENT_INSPECTOR_BACKEND_ENV}. Use typescript or rust; no backend was started.`,
+    );
+    process.exitCode = 1;
+    return;
+  }
 
   let port = portDefault;
   let host =
@@ -467,6 +590,8 @@ async function runStart(args: string[]): Promise<void> {
   let captureModeWasSpecified = false;
   let enableIdentityProxy = true;
   let legacyAliasEnabled = false;
+  let serveUi = process.env["AGENT_INSPECTOR_BACKEND_ONLY"] !== "1";
+  let backend: BackendImplementation = envBackend;
 
   if (envMode !== undefined && envMode !== "") {
     const parsedMode = parseCaptureMode(envMode);
@@ -513,6 +638,21 @@ async function runStart(args: string[]): Promise<void> {
       captureModeWasSpecified = true;
       continue;
     }
+    if (arg.startsWith("--backend=")) {
+      const parsedBackend = BackendImplementationSchema.safeParse(
+        arg
+          .slice(arg.indexOf("=") + 1)
+          .trim()
+          .toLowerCase(),
+      );
+      if (!parsedBackend.success) {
+        console.error("Invalid backend implementation. Use typescript or rust.");
+        process.exitCode = 1;
+        return;
+      }
+      backend = parsedBackend.data;
+      continue;
+    }
     switch (arg) {
       case "--port":
       case "-p":
@@ -531,6 +671,19 @@ async function runStart(args: string[]): Promise<void> {
         i++;
         break;
       }
+      case "--backend": {
+        const parsedBackend = BackendImplementationSchema.safeParse(
+          args[i + 1]?.trim().toLowerCase(),
+        );
+        if (!parsedBackend.success) {
+          console.error("Invalid backend implementation. Use typescript or rust.");
+          process.exitCode = 1;
+          return;
+        }
+        backend = parsedBackend.data;
+        i++;
+        break;
+      }
       case "--no-open":
         open = false;
         openWasSpecified = true;
@@ -546,6 +699,14 @@ async function runStart(args: string[]): Promise<void> {
       case "--background":
         background = true;
         break;
+      case "--backend-only":
+      case "--headless":
+        serveUi = false;
+        open = false;
+        break;
+      case "--with-ui":
+        serveUi = true;
+        break;
       case "--config-dir":
         configDir = args[i + 1];
         i++;
@@ -611,6 +772,14 @@ async function runStart(args: string[]): Promise<void> {
     return;
   }
 
+  if (managedLaunch !== null && managedLaunch.backend !== backend) {
+    console.error(
+      `Managed instance backend mismatch: launch identity requires ${managedLaunch.backend}, but ${backend} was selected.`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+
   if (!enableIdentityProxy && process.env["AGENT_INSPECTOR_ALLOW_UNPROTECTED_INGRESS"] !== "1") {
     console.error(
       "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.",
@@ -618,6 +787,50 @@ async function runStart(args: string[]): Promise<void> {
     process.exitCode = 1;
     return;
   }
+  if (!serveUi) open = false;
+  if (!enableIdentityProxy && serveUi) {
+    console.error(
+      "The decoupled UI is composed only by the protected ingress. Use --backend-only with --no-identity-proxy, or keep the identity proxy enabled.",
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const uiOriginAllowlist = parseUiOriginAllowlist(process.env["AGENT_INSPECTOR_UI_ORIGINS"]);
+  if (uiOriginAllowlist.rejected.length > 0) {
+    console.error(
+      `Invalid AGENT_INSPECTOR_UI_ORIGINS entries: ${uiOriginAllowlist.rejected.join(", ")}. Only exact loopback http(s) origins are accepted; use a same-origin authenticated gateway for remote UI hosting.`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const publicOrigin = normalizeExplicitPublicOrigin(process.env["AGENT_INSPECTOR_PUBLIC_ORIGIN"]);
+  if (publicOrigin === null) {
+    console.error(
+      "Invalid AGENT_INSPECTOR_PUBLIC_ORIGIN. Use an exact http(s) origin without credentials, path, query, or fragment.",
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const uiDirectoryCandidate = join(__dirname, "../.output/ui");
+  const uiIndexPath = join(uiDirectoryCandidate, "index.html");
+  const uiDirectory = serveUi && existsSync(uiIndexPath) ? uiDirectoryCandidate : undefined;
+  if (serveUi && uiDirectory === undefined) {
+    console.error(
+      `Agent Inspector UI artifact is missing at ${uiIndexPath}. Run the composed build or use --backend-only.`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  const outputDir = __dirname;
+  const serverPath = join(outputDir, "../.output/server/index.mjs");
+  const serverCommandResolution = resolveServerCommand(outputDir, serverPath, backend);
+  if (serverCommandResolution.kind === "error") {
+    console.error(serverCommandResolution.message);
+    process.exitCode = 1;
+    return;
+  }
+  const serverCommand = serverCommandResolution.command;
 
   /**
    * Check if a port is in use and kill the process using it
@@ -655,11 +868,22 @@ async function runStart(args: string[]): Promise<void> {
   const upstreamHost = enableIdentityProxy ? DEFAULT_BIND_HOST : host;
   process.env["PORT"] = String(upstreamPort);
 
+  const configuredBasePath = process.env[AGENT_INSPECTOR_BASE_PATH_ENV];
+  if (configuredBasePath !== undefined && normalizePublicBasePath(configuredBasePath) === null) {
+    console.error(
+      `Invalid ${AGENT_INSPECTOR_BASE_PATH_ENV}. Use / for root or URL-safe path segments such as /inspector or /foo-bar/v1.`,
+    );
+    process.exitCode = 1;
+    return;
+  }
   const basePath = getConfiguredBasePath(process.env);
-  const url = urlForHost(port, host);
-  const uiUrl = appendBasePathToOrigin(url, "/", basePath);
-  const proxyUrl = appendBasePathToOrigin(url, "/proxy", basePath);
-  const proxyMessagesUrl = appendBasePathToOrigin(url, "/proxy/v1/messages", basePath);
+  const bindOrigin = urlForHost(port, host);
+  const outwardOrigin = publicOrigin ?? bindOrigin;
+  const surfaceBaseUrl = appendBasePathToOrigin(outwardOrigin, "/", basePath);
+  const uiUrl = serveUi ? surfaceBaseUrl : null;
+  const proxyUrl = appendBasePathToOrigin(outwardOrigin, "/proxy", basePath);
+  const openAiProxyUrl = appendBasePathToOrigin(outwardOrigin, "/proxy/v1", basePath);
+  const proxyMessagesUrl = appendBasePathToOrigin(outwardOrigin, "/proxy/v1/messages", basePath);
   const legacyUrl =
     legacyAliasPort === null
       ? null
@@ -674,8 +898,20 @@ async function runStart(args: string[]): Promise<void> {
       : appendBasePathToOrigin(localUrlForPort(legacyAliasPort), "/api/mcp", basePath);
 
   if (!forceRestart && (await isInspectorHealthy(port, host, basePath))) {
-    console.log(`agent-inspector is already running at ${uiUrl}`);
-    printAccessHints(port, host, basePath);
+    const runningBackend = await getRunningBackend(port, host, basePath);
+    if (runningBackend !== backend) {
+      console.error(
+        runningBackend === null
+          ? `A healthy Agent Inspector is already running at ${surfaceBaseUrl}, but its backend implementation cannot be verified. Use --force-restart to replace it safely.`
+          : `Agent Inspector at ${surfaceBaseUrl} uses ${runningBackend}, but ${backend} was requested. Use --force-restart to switch implementations.`,
+      );
+      process.exitCode = 1;
+      return;
+    }
+    console.log(
+      `agent-inspector ${serveUi ? "is already running" : "backend is already running"} at ${surfaceBaseUrl}`,
+    );
+    printAccessHints(port, host, basePath, serveUi, publicOrigin);
     if (captureModeWasSpecified) {
       const runningMode = await getRunningCaptureMode(port, host, basePath);
       if (runningMode !== null && runningMode !== captureMode) {
@@ -684,7 +920,7 @@ async function runStart(args: string[]): Promise<void> {
       }
     }
     console.log(`Use --force-restart to restart the existing instance.`);
-    if (open && openWasSpecified) {
+    if (open && openWasSpecified && uiUrl !== null) {
       openBrowser(uiUrl);
     }
     return;
@@ -718,6 +954,7 @@ async function runStart(args: string[]): Promise<void> {
     }
 
     const supervisorArgs = buildBackgroundSupervisorArgs({
+      backend,
       port,
       host,
       configDir,
@@ -725,6 +962,7 @@ async function runStart(args: string[]): Promise<void> {
       captureMode,
       enableIdentityProxy,
       legacyAliasEnabled,
+      serveUi,
     });
     const supervisorProcess = spawn(process.execPath, [cliEntry, ...supervisorArgs], {
       stdio: "ignore",
@@ -738,8 +976,10 @@ async function runStart(args: string[]): Promise<void> {
     supervisorProcess.unref();
 
     if (await waitForInspectorHealthy(port, 10000, host, basePath)) {
-      console.log(`agent-inspector background server is ready at ${uiUrl}`);
-      printAccessHints(port, host, basePath);
+      console.log(
+        `agent-inspector background ${serveUi ? "server" : "backend"} is ready at ${surfaceBaseUrl}`,
+      );
+      printAccessHints(port, host, basePath, serveUi, publicOrigin);
       if (legacyProxyUrl !== null && legacyMcpUrl !== null) {
         console.log(`   Legacy proxy:  ${legacyProxyUrl}`);
         console.log(`   Legacy MCP:    ${legacyMcpUrl}`);
@@ -748,53 +988,18 @@ async function runStart(args: string[]): Promise<void> {
       console.log(`Route AI coding tools through the identity proxy for accurate PID attribution:`);
       console.log(`   Claude Code:  ANTHROPIC_BASE_URL=${proxyUrl} claude`);
       console.log(`   OpenCode:     LLM_BASE_URL=${proxyUrl} opencode`);
-      console.log(`   MiMo Code:    OPENAI_BASE_URL=${proxyUrl} mimo`);
-      if (open && openWasSpecified) {
+      console.log(`   MiMo Code:    OPENAI_BASE_URL=${openAiProxyUrl} mimo`);
+      if (open && openWasSpecified && uiUrl !== null) {
         openBrowser(uiUrl);
       }
       return;
     }
 
-    console.error(`agent-inspector background server did not become ready at ${uiUrl}.`);
+    console.error(`agent-inspector background server did not become ready at ${surfaceBaseUrl}.`);
     process.exitCode = 1;
     return;
   }
 
-  console.log(`Server running at ${uiUrl}`);
-  console.log(`   Capture mode: ${captureMode}`);
-  console.log(`   Proxy: ${proxyUrl}`);
-  printAccessHints(port, host, basePath);
-  if (legacyUrl !== null && legacyProxyUrl !== null && legacyMcpUrl !== null) {
-    console.log(`   Legacy UI:      ${legacyUrl}`);
-    console.log(`   Legacy proxy:   ${legacyProxyUrl}`);
-    console.log(`   Legacy MCP:     ${legacyMcpUrl}`);
-  }
-  console.log(``);
-  console.log(`Route AI coding tools through the proxy:`);
-  console.log(`   Claude Code:  ANTHROPIC_BASE_URL=${proxyUrl} claude`);
-  console.log(`   OpenCode:     LLM_BASE_URL=${proxyUrl} opencode`);
-  console.log(`   MiMo Code:    OPENAI_BASE_URL=${proxyUrl} mimo`);
-  console.log(`   Direct HTTP:  curl ${proxyMessagesUrl} -d '{"model":"...","messages":[...]}'`);
-  console.log(
-    `   Remote/container tools: use the Network proxy URL above when shown; otherwise restart with --host 0.0.0.0 or a reachable IP.`,
-  );
-  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(uiUrl);
-  }
-
-  // Compute server path
-  const outputDir = __dirname;
-  const serverPath = join(outputDir, "../.output/server/index.mjs");
-  const serverCommand = resolveServerCommand(outputDir, serverPath);
-
   // Start the server with the branded Windows runtime when postinstall created it.
   const serverEnv = { ...process.env };
   const currentCliEntry = process.env[AGENT_INSPECTOR_CLI_ENTRY_ENV] ?? process.argv[1];
@@ -831,6 +1036,8 @@ 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;
+  serverEnv[AGENT_INSPECTOR_BACKEND_ENV] = backend;
+  serverEnv["AGENT_INSPECTOR_BACKEND_ONLY"] = serveUi ? "0" : "1";
   const workerDir = join(__dirname, "workers");
   if (existsSync(workerDir)) {
     serverEnv["AGENT_INSPECTOR_WORKER_DIR"] = workerDir;
@@ -841,9 +1048,13 @@ async function runStart(args: string[]): Promise<void> {
         ? background
           ? ["ignore", "ignore", "ignore"]
           : ["ignore", "pipe", "pipe"]
-        : background
-          ? ["ignore", "ignore", "ignore", "ipc"]
-          : ["ignore", "pipe", "pipe", "ipc"],
+        : backend === "typescript"
+          ? background
+            ? ["ignore", "ignore", "ignore", "ipc"]
+            : ["ignore", "pipe", "pipe", "ipc"]
+          : background
+            ? ["ignore", "ignore", "ignore"]
+            : ["ignore", "pipe", "pipe"],
     detached: background,
     env: serverEnv,
     windowsHide: background,
@@ -875,7 +1086,7 @@ async function runStart(args: string[]): Promise<void> {
   const requestSupervisorShutdown = (signal: "SIGINT" | "SIGTERM"): void => {
     if (supervisorShutdownPromise !== null) return;
     for (const proxy of identityProxies) stopIdentityProxyAdmission(proxy.server);
-    if (managedLaunch !== null && serverProcess.connected) {
+    if (managedLaunch !== null && backend === "typescript" && serverProcess.connected) {
       serverProcess.send(managedInstanceShutdownMessage(managedLaunch.controlToken), (error) => {
         if (error !== null && serverProcess.exitCode === null) serverProcess.kill(signal);
       });
@@ -922,6 +1133,7 @@ async function runStart(args: string[]): Promise<void> {
           controlToken: managedLaunch.controlToken,
           supervisorPid: process.pid,
           startedAt: managedLaunch.startedAt,
+          backend,
           publicPort: port,
           upstreamPort,
           requestShutdown: () => requestSupervisorShutdown("SIGTERM"),
@@ -933,10 +1145,24 @@ async function runStart(args: string[]): Promise<void> {
       host,
       upstreamHost,
       managedInstanceControl,
+      uiOriginAllowlist.origins,
+      uiDirectory,
+      publicOrigin,
+      backend,
     );
-    if (primaryProxy !== null) {
-      identityProxies.push({ label: "primary", port, server: primaryProxy });
+    if (primaryProxy === null) {
+      console.error(
+        `Agent Inspector could not bind its protected public ingress at ${bindOrigin}; stopping the private backend.`,
+      );
+      requestSupervisorShutdown("SIGTERM");
+      const failedStartupShutdown = currentSupervisorShutdown();
+      if (failedStartupShutdown !== null) await failedStartupShutdown;
+      process.off("SIGINT", handleSigint);
+      process.off("SIGTERM", handleSigterm);
+      process.exitCode = 1;
+      return;
     }
+    identityProxies.push({ label: "primary", port, server: primaryProxy });
     if (legacyAliasPort !== null) {
       const legacyProxy = await tryStartIdentityProxy(
         legacyAliasPort,
@@ -944,6 +1170,10 @@ async function runStart(args: string[]): Promise<void> {
         host,
         upstreamHost,
         managedInstanceControl,
+        uiOriginAllowlist.origins,
+        uiDirectory,
+        publicOrigin,
+        backend,
       );
       if (legacyProxy !== null) {
         identityProxies.push({ label: "legacy", port: legacyAliasPort, server: legacyProxy });
@@ -957,11 +1187,13 @@ async function runStart(args: string[]): Promise<void> {
     // not started yet so the public port is not yet accepting traffic.
     const upstreamProbeBasePath = enableIdentityProxy ? "" : basePath;
     if (await waitForInspectorHealthy(upstreamPort, 5000, host, upstreamProbeBasePath)) {
-      console.log(`agent-inspector background server is ready at ${uiUrl}`);
+      console.log(
+        `agent-inspector background ${serveUi ? "server" : "backend"} is ready at ${surfaceBaseUrl}`,
+      );
       if (identityProxies.length > 0) {
         console.log(`Identity proxy ready on port ${port} (PID-attributing proxy).`);
       }
-      printAccessHints(port, host, basePath);
+      printAccessHints(port, host, basePath, serveUi, publicOrigin);
       if (legacyProxyUrl !== null && legacyMcpUrl !== null) {
         console.log(`   Legacy proxy:  ${legacyProxyUrl}`);
         console.log(`   Legacy MCP:    ${legacyMcpUrl}`);
@@ -972,7 +1204,7 @@ async function runStart(args: string[]): Promise<void> {
           `Route AI coding tools through the identity proxy for accurate PID attribution:`,
           `   Claude Code:  ANTHROPIC_BASE_URL=${proxyUrl} claude`,
           `   OpenCode:     LLM_BASE_URL=${proxyUrl} opencode`,
-          `   MiMo Code:    OPENAI_BASE_URL=${proxyUrl} mimo`,
+          `   MiMo Code:    OPENAI_BASE_URL=${openAiProxyUrl} mimo`,
           legacyProxyUrl === null
             ? `   Override the port with --port <n> when needed.`
             : `   Legacy configs using ${legacyProxyUrl} still work.`,
@@ -980,14 +1212,25 @@ async function runStart(args: string[]): Promise<void> {
       }
       return;
     }
-    console.error(`agent-inspector background server did not become ready at ${uiUrl}.`);
+    console.error(`agent-inspector background server did not become ready at ${surfaceBaseUrl}.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!(await waitForInspectorHealthy(port, 10_000, host, basePath))) {
+    console.error(`Agent Inspector did not become ready at ${surfaceBaseUrl}; stopping startup.`);
+    requestSupervisorShutdown("SIGTERM");
+    const failedStartupShutdown = currentSupervisorShutdown();
+    if (failedStartupShutdown !== null) await failedStartupShutdown;
+    process.off("SIGINT", handleSigint);
+    process.off("SIGTERM", handleSigterm);
     process.exitCode = 1;
     return;
   }
 
   if (identityProxies.length > 0) {
     console.log(``);
-    console.log(`Identity proxy ready at ${url} (PID-attributing public entrypoint).`);
+    console.log(`Identity proxy ready at ${bindOrigin} (PID-attributing ingress).`);
     if (legacyAliasPort !== null) {
       const legacyReady = identityProxies.some((proxy) => proxy.label === "legacy");
       if (legacyReady) {
@@ -999,6 +1242,29 @@ async function runStart(args: string[]): Promise<void> {
     }
   }
 
+  console.log(
+    `${serveUi ? "UI and backend" : "Backend control and agent runtime"} running at ${surfaceBaseUrl}`,
+  );
+  console.log(`   Capture mode: ${captureMode}`);
+  console.log(`   Backend: ${backend}`);
+  console.log(`   Proxy: ${proxyUrl}`);
+  printAccessHints(port, host, basePath, serveUi, publicOrigin);
+  if (legacyUrl !== null && legacyProxyUrl !== null && legacyMcpUrl !== null) {
+    console.log(`   Legacy UI:      ${legacyUrl}`);
+    console.log(`   Legacy proxy:   ${legacyProxyUrl}`);
+    console.log(`   Legacy MCP:     ${legacyMcpUrl}`);
+  }
+  console.log(``);
+  console.log(`Route AI coding tools through the proxy:`);
+  console.log(`   Claude Code:  ANTHROPIC_BASE_URL=${proxyUrl} claude`);
+  console.log(`   OpenCode:     LLM_BASE_URL=${proxyUrl} opencode`);
+  console.log(`   MiMo Code:    OPENAI_BASE_URL=${openAiProxyUrl} mimo`);
+  console.log(`   Direct HTTP:  curl ${proxyMessagesUrl} -d '{"model":"...","messages":[...]}'`);
+  console.log(
+    `   Remote/container tools: use the Network proxy URL above when shown; otherwise restart with --host 0.0.0.0 or a reachable IP.`,
+  );
+  if (open && uiUrl !== null) openBrowser(uiUrl);
+
   process.exitCode = await serverExit;
 
   const activeSupervisorShutdown = currentSupervisorShutdown();