@tonyclaw/agent-inspector 3.0.46 → 3.0.47

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,8 @@ import {
   shouldSuppressServerOutputLine,
   type ServerOutputFilterContext,
 } from "./cli/startupOutput.js";
+import { resolveRustBackendPackage } from "./cli/rustBackendPackage.js";
+import { handleNamedInstanceApi } from "./cli/instanceApi.js";
 import {
   closeIdentityProxyGracefully,
   forceCloseIdentityProxy,
@@ -87,6 +96,7 @@ Global options:
   -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)
@@ -194,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 });
@@ -293,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 {
@@ -385,6 +446,7 @@ function normalizeExplicitPublicOrigin(value: string | undefined): string | null
 }
 
 type BackgroundSupervisorOptions = {
+  backend: BackendImplementation;
   port: number;
   host: string | undefined;
   configDir: string | undefined;
@@ -396,7 +458,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 +519,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 +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"],
@@ -472,6 +544,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 +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 =
@@ -510,6 +591,7 @@ 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;
 
   if (envMode !== undefined && envMode !== "") {
     const parsedMode = parseCaptureMode(envMode);
@@ -556,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":
@@ -574,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;
@@ -662,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.",
@@ -704,6 +822,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 +898,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 +954,7 @@ async function runStart(args: string[]): Promise<void> {
     }
 
     const supervisorArgs = buildBackgroundSupervisorArgs({
+      backend,
       port,
       host,
       configDir,
@@ -861,11 +1000,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 +1036,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 +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,
@@ -947,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);
       });
@@ -994,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"),
@@ -1008,6 +1148,7 @@ async function runStart(args: string[]): Promise<void> {
       uiOriginAllowlist.origins,
       uiDirectory,
       publicOrigin,
+      backend,
     );
     if (primaryProxy === null) {
       console.error(
@@ -1032,6 +1173,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 +1246,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/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,
   };

package/src/proxy/identityProxy.ts

@@ -7,6 +7,10 @@ import {
   BROWSER_RUNTIME_SCHEMA_VERSION,
   type BrowserRuntimeDeployment,
 } from "../lib/browserRuntimeContract";
+import {
+  AGENT_INSPECTOR_BACKEND_HEADER,
+  type BackendImplementation,
+} from "../lib/backendImplementation";
 import {
   AGENT_INSPECTOR_BASE_PATH_META_NAME,
   AGENT_INSPECTOR_PUBLIC_BASE_PATH_HEADER,
@@ -39,6 +43,8 @@ const CSRF_HEADER = "x-agent-inspector-csrf";
 const DEFAULT_MAX_REQUEST_BYTES = 64 * 1024 * 1024;
 const DEFAULT_REQUEST_TIMEOUT_MS = 120_000;
 const ALIAS_CONTROL_MAX_REQUEST_BYTES = 8 * 1024;
+const INSTANCE_API_MAX_REQUEST_BYTES = 64 * 1024;
+const LOCAL_CONTROL_MAX_RESPONSE_BYTES = 1024 * 1024;
 
 export const IDENTITY_PROXY_CONTROL_NAMESPACE = "/.agent-inspector";
 export const IDENTITY_PROXY_ALIAS_CONTROL_PATH = `${IDENTITY_PROXY_CONTROL_NAMESPACE}/base-path-aliases`;
@@ -480,6 +486,8 @@ async function tryServeUiAsset(
 }
 
 export type IdentityProxyOptions = {
+  /** Backend child implementation supervised behind this protected ingress. */
+  backendImplementation?: BackendImplementation;
   /** Public port to listen on. Clients point at this. */
   listenPort: number;
   /** Interface exposed to clients. Defaults are chosen by the CLI. */
@@ -514,9 +522,12 @@ export type IdentityProxyOptions = {
   aliasRegistry?: BasePathAliasRegistry;
   /** Private lifecycle identity exposed only to the owning local instance manager. */
   managedInstance?: ManagedInstanceControlOptions;
+  /** Optional Node-supervisor instance API retained when the selected backend is Rust. */
+  instanceApiHandler?: (request: Request) => Promise<Response>;
 };
 
 export type ManagedInstanceControlOptions = {
+  backend?: BackendImplementation;
   name: string;
   instanceId: string;
   launchId: string;
@@ -900,6 +911,128 @@ function readAliasControlBody(req: http.IncomingMessage): Promise<AliasControlBo
   });
 }
 
+type LocalControlBodyResult =
+  | { ok: true; body: Buffer }
+  | { ok: false; status: number; error: string };
+
+function readLocalControlBody(
+  req: http.IncomingMessage,
+  maxBytes: number,
+  timeoutMs: number,
+): Promise<LocalControlBodyResult> {
+  return new Promise((resolve) => {
+    const chunks: Buffer[] = [];
+    let receivedBytes = 0;
+    let settled = false;
+    const timer = setTimeout(() => {
+      finish({ ok: false, status: 408, error: "Instance request body timed out" });
+      req.resume();
+    }, timeoutMs);
+    const finish = (result: LocalControlBodyResult): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(result);
+    };
+    req.on("data", (chunk: unknown) => {
+      if (settled) return;
+      const buffer = toBuffer(chunk);
+      receivedBytes += buffer.byteLength;
+      if (receivedBytes > maxBytes) {
+        finish({
+          ok: false,
+          status: 413,
+          error: `Instance request body exceeds ${String(maxBytes)} bytes`,
+        });
+        req.resume();
+        return;
+      }
+      chunks.push(buffer);
+    });
+    req.on("end", () => finish({ ok: true, body: Buffer.concat(chunks) }));
+    req.on("aborted", () =>
+      finish({ ok: false, status: 400, error: "Client aborted instance request body" }),
+    );
+    req.on("error", () =>
+      finish({ ok: false, status: 400, error: "Instance request body failed" }),
+    );
+  });
+}
+
+function writeLocalControlError(
+  res: http.ServerResponse,
+  status: number,
+  error: string,
+  allowedUiOrigin: string | null,
+): void {
+  res.writeHead(status, {
+    "content-type": "application/json; charset=utf-8",
+    "cache-control": "no-store",
+    ...uiCorsHeaders(allowedUiOrigin),
+  });
+  res.end(JSON.stringify({ error }));
+}
+
+async function handleLocalInstanceApi(
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+  handler: (request: Request) => Promise<Response>,
+  upstreamPath: string,
+  requestPublicOrigin: string,
+  allowedUiOrigin: string | null,
+  maxRequestBytes: number,
+  requestTimeoutMs: number,
+): Promise<void> {
+  const body = await readLocalControlBody(
+    req,
+    Math.min(maxRequestBytes, INSTANCE_API_MAX_REQUEST_BYTES),
+    requestTimeoutMs,
+  );
+  if (!body.ok) {
+    writeLocalControlError(res, body.status, body.error, allowedUiOrigin);
+    return;
+  }
+  const method = (req.method ?? "GET").toUpperCase();
+  const headers = new Headers();
+  const contentType = firstHeader(req.headers["content-type"]);
+  if (contentType !== undefined) headers.set("content-type", contentType);
+  const request = new Request(new URL(upstreamPath, requestPublicOrigin), {
+    method,
+    headers,
+    body: method === "GET" || method === "HEAD" ? undefined : body.body.toString("utf8"),
+  });
+  let response: Response;
+  try {
+    response = await handler(request);
+  } catch {
+    writeLocalControlError(res, 503, "Instance supervisor request failed", allowedUiOrigin);
+    return;
+  }
+  const responseBody = Buffer.from(await response.arrayBuffer());
+  if (responseBody.byteLength > LOCAL_CONTROL_MAX_RESPONSE_BYTES) {
+    writeLocalControlError(
+      res,
+      502,
+      "Instance supervisor response exceeded its resource limit",
+      allowedUiOrigin,
+    );
+    return;
+  }
+  const responseHeaders: Record<string, string> = {
+    ...uiCorsHeaders(allowedUiOrigin),
+    "content-length": String(responseBody.byteLength),
+  };
+  response.headers.forEach((value, name) => {
+    const lowerName = name.toLowerCase();
+    if (!REQUEST_HOP_BY_HOP.has(lowerName) && lowerName !== "content-length") {
+      responseHeaders[lowerName] = value;
+    }
+  });
+  responseHeaders["cache-control"] = "no-store";
+  res.writeHead(response.status, responseHeaders);
+  res.end(responseBody);
+}
+
 function isUnknownRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -1070,6 +1203,7 @@ function handleManagedInstanceControlRequest(
     }
     writeManagedInstanceControlResponse(res, 200, {
       schemaVersion: 1,
+      backend: managedInstance.backend ?? "typescript",
       name: managedInstance.name,
       instanceId: managedInstance.instanceId,
       launchId: managedInstance.launchId,
@@ -1483,6 +1617,19 @@ async function handleRequest(
     options.requestTimeoutMs,
     DEFAULT_REQUEST_TIMEOUT_MS,
   );
+  if (options.instanceApiHandler !== undefined && isInstanceManagementPath(upstreamPathname)) {
+    await handleLocalInstanceApi(
+      req,
+      res,
+      options.instanceApiHandler,
+      upstreamPath,
+      requestPublicOrigin,
+      allowedUiOrigin,
+      maxRequestBytes,
+      requestTimeoutMs,
+    );
+    return;
+  }
   const proxyReq = http.request(
     {
       hostname: options.upstreamHost,
@@ -1554,6 +1701,7 @@ async function handleRequest(
       for (const [name, value] of Object.entries(BASE_SECURITY_HEADERS)) {
         outHeaders[name] = value;
       }
+      outHeaders[AGENT_INSPECTOR_BACKEND_HEADER] = options.backendImplementation ?? "typescript";
       if (allowedUiOrigin !== null && isUiControlPath(upstreamPathname)) {
         outHeaders["access-control-allow-origin"] = allowedUiOrigin;
         outHeaders["access-control-expose-headers"] = "Content-Disposition";

package/src/proxy/sessionArchive.ts

@@ -278,10 +278,6 @@ export async function archiveSessionLogs(logs: readonly CapturedLog[]): Promise<
   return archivedCount;
 }
 
-export async function archiveSessionLog(log: CapturedLog): Promise<boolean> {
-  return (await archiveSessionLogs([log])) === 1;
-}
-
 function readString(row: unknown, name: string): string | null {
   const value = readProperty(row, name);
   return typeof value === "string" ? value : null;
@@ -481,7 +477,3 @@ export async function clearSessionArchives(): Promise<number> {
     return 0;
   }
 }
-
-export function _resetSessionArchiveCacheForTests(): void {
-  cachedArchiveMax = null;
-}