@tonyclaw/agent-inspector 3.0.46 → 3.0.48

package/src/cli.ts

@@ -7,6 +7,13 @@ import { dirname, join, resolve as resolvePath } from "node:path";
 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,
@@ -33,6 +40,11 @@ import {
   shouldSuppressServerOutputLine,
   type ServerOutputFilterContext,
 } from "./cli/startupOutput.js";
+import {
+  resolvePreferredBackendImplementation,
+  resolveRustBackendPackage,
+} from "./cli/rustBackendPackage.js";
+import { handleNamedInstanceApi } from "./cli/instanceApi.js";
 import {
   closeIdentityProxyGracefully,
   forceCloseIdentityProxy,
@@ -87,6 +99,7 @@ Global options:
   -v, --version   Print the package version
 
 Start options:
+  --backend <typescript|rust> Select the backend implementation (default: rust when native package is available)
   --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)
@@ -194,6 +207,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 });
@@ -293,11 +333,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 {
@@ -385,6 +449,7 @@ function normalizeExplicitPublicOrigin(value: string | undefined): string | null
 }
 
 type BackgroundSupervisorOptions = {
+  backend: BackendImplementation;
   port: number;
   host: string | undefined;
   configDir: string | undefined;
@@ -396,7 +461,15 @@ type BackgroundSupervisorOptions = {
 };
 
 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);
   }
@@ -449,6 +522,7 @@ async function tryStartIdentityProxy(
   allowedUiOrigins: readonly string[],
   uiDirectory: string | undefined,
   publicOrigin: string | undefined,
+  backend: BackendImplementation,
 ): Promise<import("node:http").Server | null> {
   try {
     const server = await startIdentityProxy({
@@ -456,6 +530,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"],
@@ -472,6 +547,7 @@ async function tryStartIdentityProxy(
       maxRequestBytes: readPositiveIntegerEnv("AGENT_INSPECTOR_MAX_REQUEST_BYTES"),
       requestTimeoutMs: readPositiveIntegerEnv("AGENT_INSPECTOR_REQUEST_TIMEOUT_MS"),
       managedInstance,
+      instanceApiHandler: backend === "rust" ? handleNamedInstanceApi : undefined,
     });
     return server;
   } catch (err) {
@@ -495,6 +571,16 @@ 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 rawEnvBackend = process.env[AGENT_INSPECTOR_BACKEND_ENV];
+  const envBackend =
+    rawEnvBackend === undefined ? undefined : parseBackendImplementation(rawEnvBackend);
+  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 =
@@ -510,6 +596,8 @@ async function runStart(args: string[]): Promise<void> {
   let enableIdentityProxy = true;
   let legacyAliasEnabled = false;
   let serveUi = process.env["AGENT_INSPECTOR_BACKEND_ONLY"] !== "1";
+  let backend: BackendImplementation = envBackend ?? "typescript";
+  let backendWasSpecified = envBackend !== undefined;
 
   if (envMode !== undefined && envMode !== "") {
     const parsedMode = parseCaptureMode(envMode);
@@ -556,6 +644,22 @@ 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;
+      backendWasSpecified = true;
+      continue;
+    }
     switch (arg) {
       case "--port":
       case "-p":
@@ -574,6 +678,20 @@ 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;
+        backendWasSpecified = true;
+        i++;
+        break;
+      }
       case "--no-open":
         open = false;
         openWasSpecified = true;
@@ -662,6 +780,20 @@ async function runStart(args: string[]): Promise<void> {
     return;
   }
 
+  if (!backendWasSpecified) {
+    backend =
+      managedLaunch?.backend ??
+      resolvePreferredBackendImplementation({ rootVersion: packageJson.version });
+  }
+
+  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.",
@@ -704,6 +836,16 @@ async function runStart(args: string[]): Promise<void> {
     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
    */
@@ -770,6 +912,16 @@ async function runStart(args: string[]): Promise<void> {
       : appendBasePathToOrigin(localUrlForPort(legacyAliasPort), "/api/mcp", basePath);
 
   if (!forceRestart && (await isInspectorHealthy(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}`,
     );
@@ -816,6 +968,7 @@ async function runStart(args: string[]): Promise<void> {
     }
 
     const supervisorArgs = buildBackgroundSupervisorArgs({
+      backend,
       port,
       host,
       configDir,
@@ -861,11 +1014,6 @@ async function runStart(args: string[]): Promise<void> {
     return;
   }
 
-  // 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];
@@ -902,6 +1050,7 @@ 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)) {
@@ -913,9 +1062,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,
@@ -947,7 +1100,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);
       });
@@ -994,6 +1147,7 @@ async function runStart(args: string[]): Promise<void> {
           controlToken: managedLaunch.controlToken,
           supervisorPid: process.pid,
           startedAt: managedLaunch.startedAt,
+          backend,
           publicPort: port,
           upstreamPort,
           requestShutdown: () => requestSupervisorShutdown("SIGTERM"),
@@ -1008,6 +1162,7 @@ async function runStart(args: string[]): Promise<void> {
       uiOriginAllowlist.origins,
       uiDirectory,
       publicOrigin,
+      backend,
     );
     if (primaryProxy === null) {
       console.error(
@@ -1032,6 +1187,7 @@ async function runStart(args: string[]): Promise<void> {
         uiOriginAllowlist.origins,
         uiDirectory,
         publicOrigin,
+        backend,
       );
       if (legacyProxy !== null) {
         identityProxies.push({ label: "legacy", port: legacyAliasPort, server: legacyProxy });
@@ -1104,6 +1260,7 @@ async function runStart(args: string[]): Promise<void> {
     `${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) {

package/src/components/ProxyViewer.tsx

@@ -61,6 +61,7 @@ import { useProviders } from "../lib/useProviders";
 import { groupLogsByConversation, type ConversationGroupData } from "./proxy-viewer";
 import {
   buildSessionSlateStats,
+  buildHomeConnectionCommands,
   COPYABLE_COMMAND_CONTAINER_CLASS_NAME,
   COPYABLE_COMMAND_TEXT_CLASS_NAME,
   exportRequiresConfirmation,
@@ -2148,19 +2149,9 @@ export function ProxyViewer({
                     {liveEmptyStateCopy.showConnectionCommands && connectionEndpoints !== null && (
                       <>
                         <div className="flex flex-col items-center gap-2">
-                          <CopyableCommand
-                            command={`ANTHROPIC_BASE_URL=${connectionEndpoints.proxy} <your-tool>`}
-                          />
-                          <CopyableCommand
-                            command={`LLM_BASE_URL=${connectionEndpoints.proxy} opencode`}
-                          />
-                          <CopyableCommand
-                            command={`OPENAI_BASE_URL=${connectionEndpoints.openAiV1} <your-tool>`}
-                          />
-                          <CopyableCommand
-                            command={`base_url = "${connectionEndpoints.openAiV1}"`}
-                          />
-                          <CopyableCommand command={`MCP_URL=${connectionEndpoints.mcp}`} />
+                          {buildHomeConnectionCommands(connectionEndpoints).map((command) => (
+                            <CopyableCommand key={command} command={command} />
+                          ))}
                         </div>
                         <p className="mx-auto max-w-xl text-xs leading-relaxed text-muted-foreground">
                           Container note: if your AI tool runs in a different container or host than

package/src/components/proxy-viewer/proxyViewerLogic.ts

@@ -24,11 +24,20 @@ export type ConversationLogs = {
   logs: CapturedLog[];
 };
 
+export type HomeConnectionEndpoints = {
+  proxy: string;
+  mcp: string;
+};
+
 export const COPYABLE_COMMAND_CONTAINER_CLASS_NAME =
   "flex w-full min-w-0 items-center gap-2 rounded-md border border-border/70 bg-muted/35 px-3 py-2 sm:w-auto sm:max-w-full";
 export const COPYABLE_COMMAND_TEXT_CLASS_NAME =
   "m-0 min-w-0 flex-1 overflow-x-auto font-mono text-xs text-foreground sm:text-sm";
 
+export function buildHomeConnectionCommands(endpoints: HomeConnectionEndpoints): readonly string[] {
+  return [`PROXY_BASE_URL=${endpoints.proxy}`, `MCP_URL=${endpoints.mcp}`];
+}
+
 export type SessionSlateStats = {
   status: SessionSlateStatus;
   statusLabel: string;

package/src/lib/backendImplementation.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+
+export const AGENT_INSPECTOR_BACKEND_ENV = "AGENT_INSPECTOR_BACKEND";
+export const AGENT_INSPECTOR_BACKEND_HEADER = "x-agent-inspector-backend";
+
+export const BackendImplementationSchema = z.enum(["typescript", "rust"]);
+
+export type BackendImplementation = z.infer<typeof BackendImplementationSchema>;
+
+export function parseBackendImplementation(
+  value: string | undefined,
+): BackendImplementation | null {
+  if (value === undefined) return "typescript";
+  const parsed = BackendImplementationSchema.safeParse(value.trim().toLowerCase());
+  return parsed.success ? parsed.data : null;
+}

package/src/lib/instanceContract.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { BackendImplementationSchema } from "./backendImplementation";
 import { normalizePublicBasePath } from "./basePath";
 
 export const INSTANCE_API_SCHEMA_VERSION = 1;
@@ -43,6 +44,7 @@ export const InstanceStatusOutputSchema = z
     upstreamPort: z.number().int().min(1).max(65_535),
     basePath: z.string().refine(isCanonicalPublicBasePath, "Invalid public Base Path"),
     captureMode: z.enum(["simple", "full"]),
+    backend: BackendImplementationSchema.default("typescript"),
     uiEnabled: z.boolean(),
     dataDir: z.string().min(1),
     supervisorPid: z.number().int().positive().nullable(),
@@ -124,6 +126,7 @@ export const InstanceStartRequestSchema = z
       )
       .optional(),
     captureMode: z.enum(["simple", "full"]).optional(),
+    backend: BackendImplementationSchema.optional(),
     uiEnabled: z.boolean().optional(),
     dataDir: z.string().trim().min(1).max(32_767).optional(),
   })

package/src/lib/managedInstance.ts

@@ -5,6 +5,7 @@ export const MANAGED_INSTANCE_SHUTDOWN_MESSAGE_TYPE = "agent-inspector:managed-s
 export const AGENT_INSPECTOR_CLI_ENTRY_ENV = "AGENT_INSPECTOR_CLI_ENTRY";
 
 export const MANAGED_INSTANCE_ENV = {
+  backend: "AGENT_INSPECTOR_INSTANCE_BACKEND",
   name: "AGENT_INSPECTOR_INSTANCE_NAME",
   instanceId: "AGENT_INSPECTOR_INSTANCE_ID",
   launchId: "AGENT_INSPECTOR_INSTANCE_LAUNCH_ID",
@@ -16,6 +17,7 @@ export const MANAGED_INSTANCE_ENV = {
 type ManagedInstanceEnv = Readonly<Record<string, string | undefined>>;
 
 export type ManagedInstanceLaunch = {
+  backend: BackendImplementation;
   name: string;
   instanceId: string;
   launchId: string;
@@ -47,6 +49,7 @@ export function readManagedInstanceLaunch(
   env: ManagedInstanceEnv = process.env,
 ): ManagedInstanceLaunchResult {
   const values = [
+    env[MANAGED_INSTANCE_ENV.backend],
     env[MANAGED_INSTANCE_ENV.name],
     env[MANAGED_INSTANCE_ENV.instanceId],
     env[MANAGED_INSTANCE_ENV.launchId],
@@ -59,6 +62,9 @@ export function readManagedInstanceLaunch(
   }
 
   const name = nonEmpty(env[MANAGED_INSTANCE_ENV.name]);
+  const backend = parseBackendImplementation(
+    nonEmpty(env[MANAGED_INSTANCE_ENV.backend]) ?? undefined,
+  );
   const instanceId = nonEmpty(env[MANAGED_INSTANCE_ENV.instanceId]);
   const launchId = nonEmpty(env[MANAGED_INSTANCE_ENV.launchId]);
   const controlToken = nonEmpty(env[MANAGED_INSTANCE_ENV.controlToken]);
@@ -66,6 +72,7 @@ export function readManagedInstanceLaunch(
   const upstreamPort = Number(env[MANAGED_INSTANCE_ENV.upstreamPort]);
   if (
     name === null ||
+    backend === null ||
     instanceId === null ||
     launchId === null ||
     controlToken === null ||
@@ -83,7 +90,7 @@ export function readManagedInstanceLaunch(
   }
   return {
     kind: "managed",
-    launch: { name, instanceId, launchId, controlToken, startedAt, upstreamPort },
+    launch: { backend, name, instanceId, launchId, controlToken, startedAt, upstreamPort },
   };
 }
 
@@ -102,3 +109,4 @@ export function parseManagedInstanceShutdownMessage(
     ? { type: MANAGED_INSTANCE_SHUTDOWN_MESSAGE_TYPE, controlToken: value["controlToken"] }
     : null;
 }
+import { parseBackendImplementation, type BackendImplementation } from "./backendImplementation";

package/src/mcp/instanceHandlers.ts

@@ -90,6 +90,7 @@ function lifecycleRequest(input: InstanceLifecycleToolInput): InstanceStartReque
     basePath: input.basePath,
     host: input.host,
     captureMode: input.captureMode,
+    backend: input.backend,
     uiEnabled: input.uiEnabled,
     dataDir: input.dataDir,
   };