@tonyclaw/agent-inspector 3.0.46 → 3.0.48

package/src/cli/instance.ts

@@ -1,11 +1,13 @@
 import { spawn, type ChildProcess } from "node:child_process";
 import { resolve as resolvePath } from "node:path";
+import packageJson from "../../package.json";
 import {
   AGENT_INSPECTOR_BASE_PATH_ENV,
   appendBasePathToOrigin,
   getConfiguredBasePath,
   normalizePublicBasePath,
 } from "../lib/basePath";
+import type { BackendImplementation } from "../lib/backendImplementation";
 import {
   type InstanceConnectionOutput,
   type InstanceOperationOutcome,
@@ -50,6 +52,7 @@ import {
   type PortAvailabilityCheck,
 } from "./instanceRegistry";
 import { probeHostForBindHost, urlForHost } from "./networkHints";
+import { resolvePreferredBackendImplementation } from "./rustBackendPackage";
 
 const DEFAULT_INSTANCE_HOST = "127.0.0.1";
 const DEFAULT_INSTANCE_CAPTURE_MODE = "simple";
@@ -101,6 +104,7 @@ export type InstanceLifecycleDependencies = {
   isPortAvailable?: PortAvailabilityCheck;
   launch?: (record: InstanceRecord, open: boolean) => Promise<boolean>;
   openUrl?: (url: string) => void;
+  resolveDefaultBackend?: () => BackendImplementation;
   sleep?: (milliseconds: number) => Promise<void>;
   readyTimeoutMs?: number;
   stopTimeoutMs?: number;
@@ -171,6 +175,7 @@ function statusOutput(
     upstreamPort: record.upstreamPort,
     basePath: displayBasePath(record.basePath),
     captureMode: record.captureMode,
+    backend: record.backend,
     uiEnabled: record.uiEnabled,
     dataDir: record.dataDir,
     supervisorPid: live.supervisorPid,
@@ -228,6 +233,7 @@ function connectionOutput(instance: InstanceStatusOutput): InstanceConnectionOut
 
 function expectedIdentity(record: InstanceRecord): ExpectedInstanceControlIdentity {
   return {
+    backend: record.backend,
     instanceId: record.instanceId,
     launchId: record.launch.launchId,
     controlToken: record.launch.controlToken,
@@ -285,6 +291,8 @@ export function buildInstanceLaunchArgs(record: InstanceRecord, open: boolean):
   const args = [
     "--background",
     "--no-open",
+    "--backend",
+    record.backend,
     "--port",
     String(record.publicPort),
     "--host",
@@ -310,6 +318,7 @@ async function defaultLaunch(
       [AGENT_INSPECTOR_CLI_ENTRY_ENV]: cliEntry,
       AGENT_INSPECTOR_DATA_DIR: record.dataDir,
       [AGENT_INSPECTOR_BASE_PATH_ENV]: displayBasePath(record.basePath),
+      [MANAGED_INSTANCE_ENV.backend]: record.backend,
       [MANAGED_INSTANCE_ENV.name]: record.name,
       [MANAGED_INSTANCE_ENV.instanceId]: record.instanceId,
       [MANAGED_INSTANCE_ENV.launchId]: record.launch.launchId,
@@ -475,6 +484,7 @@ function overridesDiffer(
   action: Extract<InstanceAction, { kind: "start" | "restart" }>,
 ): boolean {
   const { overrides } = action;
+  if (overrides.backend !== null && overrides.backend !== record.backend) return true;
   if (overrides.port !== null && overrides.port !== record.publicPort) return true;
   if (overrides.basePath !== null && overrides.basePath !== record.basePath) return true;
   if (overrides.host !== null && overrides.host !== record.host) return true;
@@ -507,6 +517,7 @@ function updatedRecord(
     upstreamPort: pair.upstreamPort,
     basePath: action.overrides.basePath ?? record.basePath,
     captureMode: action.overrides.captureMode ?? record.captureMode,
+    backend: action.overrides.backend ?? record.backend,
     uiEnabled: action.overrides.uiEnabled ?? record.uiEnabled,
     dataDir,
   };
@@ -542,6 +553,13 @@ function validateInstanceDataDirectory(
   return success(assigned.value.path);
 }
 
+function resolveDefaultInstanceBackend(deps: InstanceLifecycleDependencies): BackendImplementation {
+  return (
+    deps.resolveDefaultBackend?.() ??
+    resolvePreferredBackendImplementation({ rootVersion: packageJson.version })
+  );
+}
+
 async function createNewRecord(
   root: string,
   action: Extract<InstanceAction, { kind: "start" }>,
@@ -569,6 +587,7 @@ async function createNewRecord(
     upstreamPort: pairResult.value.upstreamPort,
     basePath: action.overrides.basePath ?? getConfiguredBasePath(process.env),
     captureMode: action.overrides.captureMode ?? DEFAULT_INSTANCE_CAPTURE_MODE,
+    backend: action.overrides.backend ?? resolveDefaultInstanceBackend(deps),
     uiEnabled: action.overrides.uiEnabled ?? true,
     dataDir: dataDirResult.value,
   });
@@ -808,6 +827,7 @@ function requestActionOverrides(
   input: InstanceStartRequest,
 ): Extract<InstanceAction, { kind: "start" }>["overrides"] {
   return {
+    backend: input.backend ?? null,
     port: input.port ?? null,
     basePath: input.basePath === undefined ? null : normalizePublicBasePath(input.basePath),
     host: input.host ?? null,
@@ -901,6 +921,7 @@ function formatStatus(output: InstanceStatusOutput): string {
   Port pair:      ${String(output.publicPort)} / ${String(output.upstreamPort)} (private)
   Base Path:      ${output.basePath}
   Capture mode:   ${output.captureMode}
+  Backend:        ${output.backend}
   Data directory: ${output.dataDir}
   Supervisor PID: ${pid}
   State reason:   ${reason}

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,9 +1,14 @@
 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;
@@ -49,6 +54,7 @@ function optionWithEquals(arg: string): { name: string; value: string } | null {
 
 function emptyOverrides(): InstanceStartOverrides {
   return {
+    backend: null,
     port: null,
     basePath: null,
     host: null,
@@ -72,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);
@@ -162,6 +174,7 @@ export function parseInstanceArgs(argv: readonly string[]): InstanceArgsResult {
         break;
       case "--port":
       case "-p":
+      case "--backend":
       case "--base-path":
       case "--host":
       case "-H":
@@ -188,6 +201,7 @@ 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 ||
@@ -211,6 +225,7 @@ 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 ||
@@ -263,6 +278,7 @@ Usage:
   agent-inspector instance restart <name> [options]
 
 Start/restart options:
+  --backend <typescript|rust> Persist the backend implementation (default: rust when native package is available)
   --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)

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" };

package/src/cli/instanceModel.ts

@@ -1,6 +1,10 @@
 import { randomBytes, randomUUID } from "node:crypto";
 import { isAbsolute } from "node:path";
 import { z } from "zod";
+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";
@@ -124,6 +128,7 @@ export const InstanceRecordSchema = z
     upstreamPort: PortSchema,
     basePath: NormalizedBasePathSchema,
     captureMode: CaptureModeSchema,
+    backend: BackendImplementationSchema.default("typescript"),
     uiEnabled: z.boolean().default(true),
     dataDir: z
       .string()
@@ -156,6 +161,7 @@ export type InstanceRecordOutput = {
   upstreamPort: number;
   basePath: string;
   captureMode: CaptureMode;
+  backend: BackendImplementation;
   uiEnabled: boolean;
   dataDir: string;
   launch: {
@@ -171,6 +177,7 @@ export type CreateInstanceRecordInput = {
   upstreamPort: number;
   basePath?: string;
   captureMode: CaptureMode;
+  backend?: BackendImplementation;
   uiEnabled?: boolean;
   dataDir: string;
 };
@@ -212,6 +219,7 @@ 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),
@@ -257,6 +265,7 @@ 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: {