@tonyclaw/agent-inspector 3.1.32 → 4.0.2

package/src/cli/instanceApi.ts

@@ -1,213 +0,0 @@
-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,301 +0,0 @@
-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;
-};
-
-export type InstanceAction =
-  | { kind: "start"; name: string; overrides: InstanceStartOverrides; json: boolean }
-  | { kind: "list"; json: boolean }
-  | { kind: "status"; name: string; json: boolean }
-  | { kind: "connect"; name: string; json: boolean }
-  | { kind: "stop"; name: string; json: boolean }
-  | { kind: "restart"; name: string; overrides: InstanceStartOverrides; json: boolean };
-
-export type InstanceArgsResult =
-  | { kind: "help" }
-  | { kind: "error"; message: string }
-  | { kind: "ok"; action: InstanceAction };
-
-function parsePort(value: string | undefined): number | null {
-  if (value === undefined || value.trim().length === 0) return null;
-  const parsed = Number(value);
-  return Number.isInteger(parsed) && parsed >= 1 && parsed <= 65_535 ? parsed : null;
-}
-
-function parseMode(value: string | undefined): InstanceCaptureMode | null {
-  return value === "simple" || value === "full" ? value : null;
-}
-
-function parseBasePath(value: string | undefined): string | null {
-  if (value === undefined) return null;
-  return normalizePublicBasePath(value);
-}
-
-function optionWithEquals(arg: string): { name: string; value: string } | null {
-  if (!arg.startsWith("--") || !arg.includes("=")) return null;
-  const separator = arg.indexOf("=");
-  return { name: arg.slice(0, separator), value: arg.slice(separator + 1) };
-}
-
-function emptyOverrides(): InstanceStartOverrides {
-  return {
-    backend: null,
-    port: null,
-    basePath: null,
-    host: null,
-    captureMode: null,
-    dataDir: null,
-    uiEnabled: null,
-    open: false,
-  };
-}
-
-type MutableOptions = {
-  json: boolean;
-  help: boolean;
-  overrides: InstanceStartOverrides;
-  positional: string[];
-};
-
-function setValueOption(
-  options: MutableOptions,
-  name: string,
-  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);
-      if (port === null) return "instance: --port must be an integer from 1 to 65535";
-      options.overrides.port = port;
-      return null;
-    }
-    case "--base-path": {
-      const basePath = parseBasePath(value);
-      if (basePath === null) {
-        return "instance: --base-path must be an absolute URL path without a query or hash";
-      }
-      options.overrides.basePath = basePath;
-      return null;
-    }
-    case "--host":
-    case "-H": {
-      const host = value?.trim() ?? "";
-      if (!isValidBindHost(host)) {
-        return "instance: --host requires a hostname or IP address without a protocol or path";
-      }
-      options.overrides.host = host;
-      return null;
-    }
-    case "--mode":
-    case "--capture-mode": {
-      const captureMode = parseMode(value);
-      if (captureMode === null) return "instance: --mode must be simple or full";
-      options.overrides.captureMode = captureMode;
-      return null;
-    }
-    case "--data-dir": {
-      const dataDir = value?.trim() ?? "";
-      if (dataDir.length === 0) return "instance: --data-dir requires a directory path";
-      options.overrides.dataDir = dataDir;
-      return null;
-    }
-    default:
-      return `instance: unknown option ${name}`;
-  }
-}
-
-export function parseInstanceArgs(argv: readonly string[]): InstanceArgsResult {
-  const options: MutableOptions = {
-    json: false,
-    help: false,
-    overrides: emptyOverrides(),
-    positional: [],
-  };
-
-  for (let index = 0; index < argv.length; index++) {
-    const arg = argv[index];
-    if (arg === undefined) continue;
-    const equalsOption = optionWithEquals(arg);
-    if (equalsOption !== null) {
-      const error = setValueOption(options, equalsOption.name, equalsOption.value);
-      if (error !== null) return { kind: "error", message: error };
-      continue;
-    }
-    switch (arg) {
-      case "--help":
-      case "-h":
-        options.help = true;
-        break;
-      case "--json":
-        options.json = true;
-        break;
-      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":
-      case "--mode":
-      case "--capture-mode":
-      case "--data-dir": {
-        const error = setValueOption(options, arg, argv[index + 1]);
-        if (error !== null) return { kind: "error", message: error };
-        index++;
-        break;
-      }
-      default:
-        if (arg.startsWith("-")) {
-          return { kind: "error", message: `instance: unknown option ${arg}` };
-        }
-        options.positional.push(arg);
-    }
-  }
-
-  if (options.help) return { kind: "help" };
-  const command = options.positional[0];
-  if (command === "list") {
-    if (options.positional.length !== 1) {
-      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" };
-    }
-    return { kind: "ok", action: { kind: "list", json: options.json } };
-  }
-  if (
-    command === "status" ||
-    command === "stop" ||
-    command === "connect" ||
-    command === "connection"
-  ) {
-    const name = options.positional[1];
-    if (name === undefined || options.positional.length !== 2) {
-      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 {
-        kind: "error",
-        message: `instance: ${command} accepts only an instance name and --json`,
-      };
-    }
-    return {
-      kind: "ok",
-      action: { kind: command === "connection" ? "connect" : command, name, json: options.json },
-    };
-  }
-  if (command === "start" || command === "restart") {
-    const name = options.positional[1];
-    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 },
-    };
-  }
-  if (command === undefined) {
-    return {
-      kind: "error",
-      message: "instance: expected start, list, status, connect, stop, or restart",
-    };
-  }
-  return { kind: "error", message: `instance: unknown command ${command}` };
-}
-
-export function instanceHelp(): string {
-  return `agent-inspector instance - manage isolated named runtimes
-
-Usage:
-  agent-inspector instance start <name> [options]
-  agent-inspector instance list [--json]
-  agent-inspector instance status <name> [--json]
-  agent-inspector instance connect <name> [--json]
-  agent-inspector instance stop <name> [--json]
-  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)
-  --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
-
-Named instances run as hidden background supervisors and persist their configuration. Each one
-uses separate Provider, config, capture, and index storage. The existing \`agent-inspector\` command
-remains the unmanaged default instance. Base Path aliases mount another URL on one runtime; named
-instances start separate runtimes.
-
-The connect command prints protocol-correct Anthropic, OpenAI /v1, MCP, health, and UI settings
-without exposing lifecycle or Provider credentials. \`connection\` is accepted as an alias.
-`;
-}

package/src/cli/instanceControl.ts

@@ -1,191 +0,0 @@
-import {
-  MANAGED_INSTANCE_CONTROL_PATH,
-  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;
-  host: string;
-  publicPort: number;
-};
-
-export type InstanceControlIdentity = {
-  schemaVersion: 1;
-  backend: BackendImplementation;
-  instanceId: string;
-  launchId: string;
-  supervisorPid: number;
-  startedAt: string;
-  publicPort: number;
-  upstreamPort: number;
-};
-
-export type InstanceControlProbe =
-  | { kind: "running"; identity: InstanceControlIdentity }
-  | { kind: "unreachable"; timedOut: boolean }
-  | { kind: "identity-mismatch" }
-  | { kind: "invalid-response" };
-
-export type InstanceShutdownResult =
-  | { kind: "accepted" }
-  | { kind: "unreachable"; timedOut: boolean }
-  | { kind: "identity-mismatch" }
-  | { kind: "rejected" };
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-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"];
-  const startedAt = value["startedAt"];
-  const publicPort = value["publicPort"];
-  const upstreamPort = value["upstreamPort"];
-  if (
-    schemaVersion !== 1 ||
-    !backend.success ||
-    typeof instanceId !== "string" ||
-    instanceId.length === 0 ||
-    typeof launchId !== "string" ||
-    launchId.length === 0 ||
-    typeof supervisorPid !== "number" ||
-    !Number.isInteger(supervisorPid) ||
-    supervisorPid < 1 ||
-    typeof startedAt !== "string" ||
-    !Number.isFinite(Date.parse(startedAt)) ||
-    typeof publicPort !== "number" ||
-    !Number.isInteger(publicPort) ||
-    publicPort < 1 ||
-    publicPort > 65_535 ||
-    typeof upstreamPort !== "number" ||
-    !Number.isInteger(upstreamPort) ||
-    upstreamPort < 1 ||
-    upstreamPort > 65_535
-  ) {
-    return null;
-  }
-  return {
-    schemaVersion: 1,
-    backend: backend.data,
-    instanceId,
-    launchId,
-    supervisorPid,
-    startedAt,
-    publicPort,
-    upstreamPort,
-  };
-}
-
-function hostForUrl(host: string): string {
-  if (host.startsWith("[") && host.endsWith("]")) return host;
-  return host.includes(":") ? `[${host}]` : host;
-}
-
-function endpoint(identity: ExpectedInstanceControlIdentity, path: string): string {
-  return `http://${hostForUrl(identity.host)}:${String(identity.publicPort)}${path}`;
-}
-
-function requestInit(
-  identity: ExpectedInstanceControlIdentity,
-  controller: AbortController,
-  method: "GET" | "POST",
-): RequestInit {
-  return {
-    method,
-    headers: {
-      accept: "application/json",
-      [MANAGED_INSTANCE_TOKEN_HEADER]: identity.controlToken,
-    },
-    cache: "no-store",
-    signal: controller.signal,
-  };
-}
-
-async function responseJson(response: Response): Promise<unknown | null> {
-  try {
-    const value: unknown = await response.json();
-    return value;
-  } catch {
-    return null;
-  }
-}
-
-export async function probeInstanceControl(
-  expected: ExpectedInstanceControlIdentity,
-  fetchImpl: InstanceControlFetch = fetch,
-  timeoutMs = DEFAULT_CONTROL_TIMEOUT_MS,
-): Promise<InstanceControlProbe> {
-  const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), timeoutMs);
-  try {
-    const response = await fetchImpl(
-      endpoint(expected, MANAGED_INSTANCE_CONTROL_PATH),
-      requestInit(expected, controller, "GET"),
-    );
-    if (!response.ok) return { kind: "identity-mismatch" };
-    const identity = parseIdentity(await responseJson(response));
-    if (identity === null) return { kind: "invalid-response" };
-    if (
-      identity.instanceId !== expected.instanceId ||
-      identity.launchId !== expected.launchId ||
-      identity.backend !== (expected.backend ?? "typescript") ||
-      identity.publicPort !== expected.publicPort
-    ) {
-      return { kind: "identity-mismatch" };
-    }
-    return { kind: "running", identity };
-  } catch (error) {
-    return {
-      kind: "unreachable",
-      timedOut:
-        controller.signal.aborted || (error instanceof Error && error.name === "AbortError"),
-    };
-  } finally {
-    clearTimeout(timeout);
-  }
-}
-
-export async function requestInstanceShutdown(
-  expected: ExpectedInstanceControlIdentity,
-  fetchImpl: InstanceControlFetch = fetch,
-  timeoutMs = DEFAULT_CONTROL_TIMEOUT_MS,
-): Promise<InstanceShutdownResult> {
-  const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), timeoutMs);
-  try {
-    const response = await fetchImpl(
-      endpoint(expected, MANAGED_INSTANCE_SHUTDOWN_PATH),
-      requestInit(expected, controller, "POST"),
-    );
-    if (response.status === 202) return { kind: "accepted" };
-    if (response.status === 401 || response.status === 403 || response.status === 404) {
-      return { kind: "identity-mismatch" };
-    }
-    return { kind: "rejected" };
-  } catch (error) {
-    return {
-      kind: "unreachable",
-      timedOut:
-        controller.signal.aborted || (error instanceof Error && error.name === "AbortError"),
-    };
-  } finally {
-    clearTimeout(timeout);
-  }
-}