@tonyclaw/agent-inspector 3.0.44 → 3.0.46

package/src/cli/instanceArgs.ts

@@ -0,0 +1,285 @@
+import { normalizePublicBasePath } from "../lib/basePath";
+import { isValidBindHost } from "./networkHints";
+
+export type InstanceCaptureMode = "simple" | "full";
+
+export type InstanceStartOverrides = {
+  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 {
+    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 "--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 "--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.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.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:
+  --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

@@ -0,0 +1,181 @@
+import {
+  MANAGED_INSTANCE_CONTROL_PATH,
+  MANAGED_INSTANCE_SHUTDOWN_PATH,
+  MANAGED_INSTANCE_TOKEN_HEADER,
+} from "../lib/managedInstance";
+
+const DEFAULT_CONTROL_TIMEOUT_MS = 2_000;
+
+export type InstanceControlFetch = (input: string, init?: RequestInit) => Promise<Response>;
+
+export type ExpectedInstanceControlIdentity = {
+  instanceId: string;
+  launchId: string;
+  controlToken: string;
+  host: string;
+  publicPort: number;
+};
+
+export type InstanceControlIdentity = {
+  schemaVersion: 1;
+  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 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 ||
+    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,
+    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.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);
+  }
+}