@tonyclaw/agent-inspector 3.0.45 → 3.0.47

package/src/cli/instanceApi.ts

@@ -0,0 +1,213 @@
+import { type z } from "zod";
+import {
+  getNamedInstance,
+  getNamedInstanceConnection,
+  type InstanceLifecycleError,
+  type InstanceLifecycleResult,
+  listNamedInstances,
+  restartNamedInstance,
+  startNamedInstance,
+  stopNamedInstance,
+} from "./instance";
+import {
+  type InstancePublicErrorCode,
+  INSTANCE_API_SCHEMA_VERSION,
+  InstanceEmptyRequestSchema,
+  InstanceStartRequestSchema,
+  instanceErrorOutput,
+} from "../lib/instanceContract";
+import { readManagedInstanceLaunch } from "../lib/managedInstance";
+
+const NO_STORE_HEADERS = { "cache-control": "no-store" };
+
+type ParsedBody<T> = { ok: true; value: T } | { ok: false; response: Response };
+
+function errorStatus(code: InstancePublicErrorCode): number {
+  switch (code) {
+    case "argument_invalid":
+    case "data_dir_invalid":
+    case "name_invalid":
+    case "port_invalid":
+    case "record_invalid":
+      return 400;
+    case "instance_not_found":
+      return 404;
+    case "config_mismatch":
+    case "data_dir_conflict":
+    case "identity_mismatch":
+    case "port_conflict":
+    case "self_lifecycle_unsupported":
+      return 409;
+    case "lock_not_owned":
+    case "lock_timeout":
+      return 423;
+    case "launch_failed":
+    case "launch_unavailable":
+    case "port_exhausted":
+    case "registry_io":
+    case "restart_failed_degraded":
+    case "restart_failed_rolled_back":
+    case "shutdown_failed":
+      return 503;
+  }
+}
+
+export function instanceErrorResponse(error: InstanceLifecycleError): Response {
+  return Response.json(instanceErrorOutput(error), {
+    status: errorStatus(error.code),
+    headers: NO_STORE_HEADERS,
+  });
+}
+
+export function instanceResultResponse<T>(
+  result: InstanceLifecycleResult<T>,
+  successStatus = 200,
+): Response {
+  return result.kind === "error"
+    ? instanceErrorResponse(result.error)
+    : Response.json(result.value, { status: successStatus, headers: NO_STORE_HEADERS });
+}
+
+export async function parseInstanceBody<T extends z.ZodType>(
+  request: Request,
+  schema: T,
+): Promise<ParsedBody<z.output<T>>> {
+  let value: unknown;
+  try {
+    const text = await request.text();
+    value = text.trim().length === 0 ? {} : JSON.parse(text);
+  } catch {
+    return {
+      ok: false,
+      response: instanceErrorResponse({
+        code: "argument_invalid",
+        message: "Request body must be valid JSON.",
+        retryable: false,
+      }),
+    };
+  }
+  const parsed = schema.safeParse(value);
+  if (!parsed.success) {
+    return {
+      ok: false,
+      response: instanceErrorResponse({
+        code: "argument_invalid",
+        message: `Invalid instance request: ${parsed.error.issues[0]?.message ?? "invalid body"}`,
+        retryable: false,
+      }),
+    };
+  }
+  return { ok: true, value: parsed.data };
+}
+
+export function selfLifecycleError(rawName: string): InstanceLifecycleError | null {
+  const current = readManagedInstanceLaunch(process.env);
+  return current.kind === "managed" && current.launch.name.toLowerCase() === rawName.toLowerCase()
+    ? {
+        code: "self_lifecycle_unsupported",
+        message:
+          "A managed runtime cannot stop or restart itself through its own REST/MCP transport; use the CLI or a different controller instance.",
+        retryable: false,
+      }
+    : null;
+}
+
+export function instanceListResponse(instances: readonly unknown[]): Response {
+  return Response.json(
+    { schemaVersion: INSTANCE_API_SCHEMA_VERSION, instances },
+    { headers: NO_STORE_HEADERS },
+  );
+}
+
+function methodNotAllowed(allow: string): Response {
+  return Response.json(
+    { error: "Method not allowed" },
+    { status: 405, headers: { ...NO_STORE_HEADERS, allow } },
+  );
+}
+
+function endpointNotFound(): Response {
+  return Response.json(
+    { error: "Instance endpoint not found" },
+    { status: 404, headers: NO_STORE_HEADERS },
+  );
+}
+
+function decodedName(value: string): string | null {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Framework-neutral named-instance API owned by the Node supervisor plane.
+ *
+ * The protected ingress uses this when a Rust backend is selected, keeping process lifecycle and
+ * OS-specific background behavior in the existing CLI instead of reimplementing it in Rust.
+ */
+export async function handleNamedInstanceApi(request: Request): Promise<Response> {
+  const url = new URL(request.url);
+  const segments = url.pathname.split("/").filter((segment) => segment.length > 0);
+  if (segments.length === 2 && segments[0] === "api" && segments[1] === "instances") {
+    if (request.method !== "GET") return methodNotAllowed("GET");
+    const result = await listNamedInstances();
+    return result.kind === "error"
+      ? instanceResultResponse(result)
+      : instanceListResponse(result.value);
+  }
+  if (segments.length < 3 || segments[0] !== "api" || segments[1] !== "instances") {
+    return endpointNotFound();
+  }
+  const name = decodedName(segments[2] ?? "");
+  if (name === null) {
+    return instanceErrorResponse({
+      code: "name_invalid",
+      message: "Instance name is not valid URL encoding.",
+      retryable: false,
+    });
+  }
+  if (segments.length === 3) {
+    return request.method === "GET"
+      ? instanceResultResponse(await getNamedInstance(name))
+      : methodNotAllowed("GET");
+  }
+  if (segments.length !== 4) return endpointNotFound();
+  const action = segments[3];
+  if (action === undefined) return endpointNotFound();
+  switch (action) {
+    case "connection":
+      return request.method === "GET"
+        ? instanceResultResponse(await getNamedInstanceConnection(name))
+        : methodNotAllowed("GET");
+    case "start": {
+      if (request.method !== "POST") return methodNotAllowed("POST");
+      const body = await parseInstanceBody(request, InstanceStartRequestSchema);
+      if (!body.ok) return body.response;
+      const result = await startNamedInstance(name, body.value);
+      const status = result.kind === "success" && result.value.outcome === "created" ? 201 : 200;
+      return instanceResultResponse(result, status);
+    }
+    case "stop": {
+      if (request.method !== "POST") return methodNotAllowed("POST");
+      const body = await parseInstanceBody(request, InstanceEmptyRequestSchema);
+      if (!body.ok) return body.response;
+      const selfError = selfLifecycleError(name);
+      return selfError === null
+        ? instanceResultResponse(await stopNamedInstance(name))
+        : instanceErrorResponse(selfError);
+    }
+    case "restart": {
+      if (request.method !== "POST") return methodNotAllowed("POST");
+      const body = await parseInstanceBody(request, InstanceStartRequestSchema);
+      if (!body.ok) return body.response;
+      const selfError = selfLifecycleError(name);
+      return selfError === null
+        ? instanceResultResponse(await restartNamedInstance(name, body.value))
+        : instanceErrorResponse(selfError);
+    }
+    default:
+      return endpointNotFound();
+  }
+}

package/src/cli/instanceArgs.ts

@@ -1,14 +1,20 @@
-import { normalizeBasePath } from "../lib/basePath";
+import { normalizePublicBasePath } from "../lib/basePath";
+import {
+  BackendImplementationSchema,
+  type BackendImplementation,
+} from "../lib/backendImplementation";
 import { isValidBindHost } from "./networkHints";
 
 export type InstanceCaptureMode = "simple" | "full";
 
 export type InstanceStartOverrides = {
+  backend: BackendImplementation | null;
   port: number | null;
   basePath: string | null;
   host: string | null;
   captureMode: InstanceCaptureMode | null;
   dataDir: string | null;
+  uiEnabled: boolean | null;
   open: boolean;
 };
 
@@ -36,16 +42,8 @@ function parseMode(value: string | undefined): InstanceCaptureMode | null {
 }
 
 function parseBasePath(value: string | undefined): string | null {
-  if (
-    value === undefined ||
-    !value.startsWith("/") ||
-    value.includes("?") ||
-    value.includes("#") ||
-    value.includes("\\")
-  ) {
-    return null;
-  }
-  return normalizeBasePath(value);
+  if (value === undefined) return null;
+  return normalizePublicBasePath(value);
 }
 
 function optionWithEquals(arg: string): { name: string; value: string } | null {
@@ -56,11 +54,13 @@ function optionWithEquals(arg: string): { name: string; value: string } | null {
 
 function emptyOverrides(): InstanceStartOverrides {
   return {
+    backend: null,
     port: null,
     basePath: null,
     host: null,
     captureMode: null,
     dataDir: null,
+    uiEnabled: null,
     open: false,
   };
 }
@@ -78,6 +78,12 @@ function setValueOption(
   value: string | undefined,
 ): string | null {
   switch (name) {
+    case "--backend": {
+      const backend = BackendImplementationSchema.safeParse(value?.trim().toLowerCase());
+      if (!backend.success) return "instance: --backend must be typescript or rust";
+      options.overrides.backend = backend.data;
+      return null;
+    }
     case "--port":
     case "-p": {
       const port = parsePort(value);
@@ -148,8 +154,27 @@ export function parseInstanceArgs(argv: readonly string[]): InstanceArgsResult {
       case "--open":
         options.overrides.open = true;
         break;
+      case "--backend-only":
+        if (options.overrides.uiEnabled === true) {
+          return {
+            kind: "error",
+            message: "instance: --backend-only and --with-ui are mutually exclusive",
+          };
+        }
+        options.overrides.uiEnabled = false;
+        break;
+      case "--with-ui":
+        if (options.overrides.uiEnabled === false) {
+          return {
+            kind: "error",
+            message: "instance: --backend-only and --with-ui are mutually exclusive",
+          };
+        }
+        options.overrides.uiEnabled = true;
+        break;
       case "--port":
       case "-p":
+      case "--backend":
       case "--base-path":
       case "--host":
       case "-H":
@@ -176,11 +201,13 @@ export function parseInstanceArgs(argv: readonly string[]): InstanceArgsResult {
       return { kind: "error", message: "instance: list does not accept an instance name" };
     }
     if (
+      options.overrides.backend !== null ||
       options.overrides.port !== null ||
       options.overrides.basePath !== null ||
       options.overrides.host !== null ||
       options.overrides.captureMode !== null ||
       options.overrides.dataDir !== null ||
+      options.overrides.uiEnabled !== null ||
       options.overrides.open
     ) {
       return { kind: "error", message: "instance: list accepts only --json" };
@@ -198,11 +225,13 @@ export function parseInstanceArgs(argv: readonly string[]): InstanceArgsResult {
       return { kind: "error", message: `instance: ${command} requires exactly one instance name` };
     }
     if (
+      options.overrides.backend !== null ||
       options.overrides.port !== null ||
       options.overrides.basePath !== null ||
       options.overrides.host !== null ||
       options.overrides.captureMode !== null ||
       options.overrides.dataDir !== null ||
+      options.overrides.uiEnabled !== null ||
       options.overrides.open
     ) {
       return {
@@ -220,6 +249,9 @@ export function parseInstanceArgs(argv: readonly string[]): InstanceArgsResult {
     if (name === undefined || options.positional.length !== 2) {
       return { kind: "error", message: `instance: ${command} requires exactly one instance name` };
     }
+    if (options.overrides.uiEnabled === false && options.overrides.open) {
+      return { kind: "error", message: "instance: --open cannot be used with --backend-only" };
+    }
     return {
       kind: "ok",
       action: { kind: command, name, overrides: options.overrides, json: options.json },
@@ -246,11 +278,14 @@ Usage:
   agent-inspector instance restart <name> [options]
 
 Start/restart options:
+  --backend <typescript|rust> Persist the backend implementation (default: typescript)
   --port, -p <port>       Public ingress port (auto-allocated on first start)
   --base-path <path>      Public Base Path (default: /inspector; use / for root)
   --host, -H <host>       Bind host (default: 127.0.0.1)
   --mode <simple|full>    Capture mode (default: simple)
   --data-dir <path>       Isolated data/config directory
+  --backend-only          Persist a headless backend without serving the UI
+  --with-ui               Persist composed UI serving (the default for new instances)
   --open                  Open the UI after readiness
   --json                  Emit machine-readable output
   --help, -h              Show this help

package/src/cli/instanceControl.ts

@@ -3,12 +3,17 @@ import {
   MANAGED_INSTANCE_SHUTDOWN_PATH,
   MANAGED_INSTANCE_TOKEN_HEADER,
 } from "../lib/managedInstance";
+import {
+  BackendImplementationSchema,
+  type BackendImplementation,
+} from "../lib/backendImplementation";
 
 const DEFAULT_CONTROL_TIMEOUT_MS = 2_000;
 
 export type InstanceControlFetch = (input: string, init?: RequestInit) => Promise<Response>;
 
 export type ExpectedInstanceControlIdentity = {
+  backend?: BackendImplementation;
   instanceId: string;
   launchId: string;
   controlToken: string;
@@ -18,6 +23,7 @@ export type ExpectedInstanceControlIdentity = {
 
 export type InstanceControlIdentity = {
   schemaVersion: 1;
+  backend: BackendImplementation;
   instanceId: string;
   launchId: string;
   supervisorPid: number;
@@ -45,6 +51,7 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 function parseIdentity(value: unknown): InstanceControlIdentity | null {
   if (!isRecord(value)) return null;
   const schemaVersion = value["schemaVersion"];
+  const backend = BackendImplementationSchema.safeParse(value["backend"] ?? "typescript");
   const instanceId = value["instanceId"];
   const launchId = value["launchId"];
   const supervisorPid = value["supervisorPid"];
@@ -53,6 +60,7 @@ function parseIdentity(value: unknown): InstanceControlIdentity | null {
   const upstreamPort = value["upstreamPort"];
   if (
     schemaVersion !== 1 ||
+    !backend.success ||
     typeof instanceId !== "string" ||
     instanceId.length === 0 ||
     typeof launchId !== "string" ||
@@ -75,6 +83,7 @@ function parseIdentity(value: unknown): InstanceControlIdentity | null {
   }
   return {
     schemaVersion: 1,
+    backend: backend.data,
     instanceId,
     launchId,
     supervisorPid,
@@ -136,6 +145,7 @@ export async function probeInstanceControl(
     if (
       identity.instanceId !== expected.instanceId ||
       identity.launchId !== expected.launchId ||
+      identity.backend !== (expected.backend ?? "typescript") ||
       identity.publicPort !== expected.publicPort
     ) {
       return { kind: "identity-mismatch" };
@@ -179,5 +189,3 @@ export async function requestInstanceShutdown(
     clearTimeout(timeout);
   }
 }
-
-export const instanceControlForTests = { parseIdentity };

package/src/cli/instanceModel.ts

@@ -1,7 +1,11 @@
 import { randomBytes, randomUUID } from "node:crypto";
 import { isAbsolute } from "node:path";
 import { z } from "zod";
-import { normalizeBasePath } from "../lib/basePath";
+import {
+  BackendImplementationSchema,
+  type BackendImplementation,
+} from "../lib/backendImplementation";
+import { normalizePublicBasePath } from "../lib/basePath";
 import { MANAGED_INSTANCE_CONTROL_PATH } from "../lib/managedInstance";
 import { CaptureModeSchema, type CaptureMode } from "../lib/runtimeConfig";
 
@@ -73,26 +77,13 @@ export function validateInstanceName(rawName: string): InstanceRegistryResult<st
 export function normalizeInstanceBasePath(
   rawBasePath: string | undefined,
 ): InstanceRegistryResult<string> {
-  const value = rawBasePath ?? "";
-  const trimmed = value.trim();
-  const hasControlCharacter = [...trimmed].some((character) => {
-    const codePoint = character.codePointAt(0) ?? 0;
-    return codePoint < 32 || codePoint === 127;
-  });
-  if (
-    trimmed.length > 0 &&
-    (!trimmed.startsWith("/") ||
-      trimmed.includes("?") ||
-      trimmed.includes("#") ||
-      trimmed.includes("\\") ||
-      hasControlCharacter)
-  ) {
+  const normalized = normalizePublicBasePath(rawBasePath);
+  if (normalized === null) {
     return instanceRegistryError(
       "record_invalid",
-      "Instance Base Path must be an absolute URL path without a query, hash, backslash, or control character.",
+      "Instance Base Path must use URL-safe path segments without traversal, encoded separators, or markup characters.",
     );
   }
-  const normalized = normalizeBasePath(trimmed);
   const reservedControlRoot = MANAGED_INSTANCE_CONTROL_PATH.replace(/\/instance$/u, "");
   if (normalized === reservedControlRoot || normalized.startsWith(`${reservedControlRoot}/`)) {
     return instanceRegistryError(
@@ -137,6 +128,8 @@ export const InstanceRecordSchema = z
     upstreamPort: PortSchema,
     basePath: NormalizedBasePathSchema,
     captureMode: CaptureModeSchema,
+    backend: BackendImplementationSchema.default("typescript"),
+    uiEnabled: z.boolean().default(true),
     dataDir: z
       .string()
       .min(1)
@@ -168,6 +161,8 @@ export type InstanceRecordOutput = {
   upstreamPort: number;
   basePath: string;
   captureMode: CaptureMode;
+  backend: BackendImplementation;
+  uiEnabled: boolean;
   dataDir: string;
   launch: {
     launchId: string;
@@ -182,6 +177,8 @@ export type CreateInstanceRecordInput = {
   upstreamPort: number;
   basePath?: string;
   captureMode: CaptureMode;
+  backend?: BackendImplementation;
+  uiEnabled?: boolean;
   dataDir: string;
 };
 
@@ -222,6 +219,8 @@ export function createInstanceRecord(
     upstreamPort: input.upstreamPort,
     basePath: basePath.value,
     captureMode: input.captureMode,
+    backend: input.backend ?? "typescript",
+    uiEnabled: input.uiEnabled ?? true,
     dataDir: input.dataDir,
     launch: createLaunch(factory, now),
   };
@@ -266,6 +265,8 @@ export function toInstanceRecordOutput(record: InstanceRecord): InstanceRecordOu
     upstreamPort: record.upstreamPort,
     basePath: record.basePath,
     captureMode: record.captureMode,
+    backend: record.backend,
+    uiEnabled: record.uiEnabled,
     dataDir: record.dataDir,
     launch: {
       launchId: record.launch.launchId,

package/src/cli/instanceRegistry.ts

@@ -500,15 +500,6 @@ export function withRegistryLock<T>(
   return runWithLock(acquireRegistryLock(root, options), operation);
 }
 
-export function withInstanceLock<T>(
-  root: string,
-  rawName: string,
-  operation: LockedOperation<T>,
-  options: InstanceLockOptions = {},
-): Promise<InstanceRegistryResult<T>> {
-  return runWithLock(acquireInstanceLock(root, rawName, options), operation);
-}
-
 type PathApi = typeof win32;
 
 export type CanonicalDataDirectory = {

package/src/cli/networkHints.ts

@@ -1,4 +1,5 @@
 import { networkInterfaces } from "node:os";
+import { isIP } from "node:net";
 import { appendBasePathToOrigin, normalizeBasePath } from "../lib/basePath";
 
 export type NetworkInterfaceMap = ReturnType<typeof networkInterfaces>;
@@ -22,12 +23,12 @@ export function isWildcardHost(host: BindHost): boolean {
 export function isLoopbackHost(host: BindHost): boolean {
   const trimmed = trimHost(host);
   if (trimmed === undefined) return false;
-  return (
-    trimmed === "localhost" ||
-    trimmed === "::1" ||
-    trimmed === "[::1]" ||
-    trimmed.startsWith("127.")
-  );
+  const normalized =
+    trimmed.startsWith("[") && trimmed.endsWith("]")
+      ? trimmed.slice(1, -1).toLowerCase()
+      : trimmed.toLowerCase();
+  if (normalized === "localhost" || normalized === "::1") return true;
+  return isIP(normalized) === 4 && normalized.split(".", 1)[0] === "127";
 }
 
 function bracketIpv6(host: string): string {
@@ -112,11 +113,28 @@ function accessUrl(origin: string, path: string, basePath: string): string {
   return appendBasePathToOrigin(origin, path, basePath);
 }
 
+function appendSurfaceLines(
+  lines: string[],
+  label: "Local" | "Bound" | "Network",
+  origin: string,
+  basePath: string,
+  uiEnabled: boolean,
+): void {
+  const baseUrl = accessUrl(origin, "/", basePath);
+  if (uiEnabled) lines.push(`   ${label} UI:       ${baseUrl}`);
+  lines.push(`   ${label} control Base: ${baseUrl}`);
+  lines.push(`   ${label} agent Base:   ${baseUrl}`);
+  lines.push(`   ${label} REST API:     ${accessUrl(origin, "/api", basePath)}`);
+  lines.push(`   ${label} proxy:        ${accessUrl(origin, "/proxy", basePath)}`);
+  lines.push(`   ${label} MCP:          ${accessUrl(origin, "/api/mcp", basePath)}`);
+}
+
 export function formatAccessHintLines(
   port: number,
   networkUrls: readonly string[],
   host: BindHost = undefined,
   basePath = "",
+  uiEnabled = true,
 ): string[] {
   const normalizedBasePath = normalizeBasePath(basePath);
   const localUrl = localUrlForPort(port);
@@ -124,14 +142,10 @@ export function formatAccessHintLines(
   const lines = ["Access URLs:", `   Bind host:      ${hostLabel}`];
 
   if (isLoopbackHost(host) || isWildcardHost(host)) {
-    lines.push(`   Local UI:       ${accessUrl(localUrl, "/", normalizedBasePath)}`);
-    lines.push(`   Local proxy:    ${accessUrl(localUrl, "/proxy", normalizedBasePath)}`);
-    lines.push(`   Local MCP:      ${accessUrl(localUrl, "/api/mcp", normalizedBasePath)}`);
+    appendSurfaceLines(lines, "Local", localUrl, normalizedBasePath, uiEnabled);
   } else {
     const boundUrl = urlForHost(port, host);
-    lines.push(`   Bound UI:       ${accessUrl(boundUrl, "/", normalizedBasePath)}`);
-    lines.push(`   Bound proxy:    ${accessUrl(boundUrl, "/proxy", normalizedBasePath)}`);
-    lines.push(`   Bound MCP:      ${accessUrl(boundUrl, "/api/mcp", normalizedBasePath)}`);
+    appendSurfaceLines(lines, "Bound", boundUrl, normalizedBasePath, uiEnabled);
     lines.push("   Localhost:      may not work because the server is bound to a specific host");
   }
 
@@ -141,8 +155,7 @@ export function formatAccessHintLines(
   } else if (firstNetworkUrl === undefined) {
     lines.push("   Network:        no non-loopback IPv4 address detected");
   } else {
-    lines.push(`   Network UI:     ${accessUrl(firstNetworkUrl, "/", normalizedBasePath)}`);
-    lines.push(`   Network proxy:  ${accessUrl(firstNetworkUrl, "/proxy", normalizedBasePath)}`);
+    appendSurfaceLines(lines, "Network", firstNetworkUrl, normalizedBasePath, uiEnabled);
     const moreUrls = networkUrls.slice(1);
     if (moreUrls.length > 0) {
       lines.push(`   Other IPs:      ${moreUrls.join(", ")}`);