@tonyclaw/agent-inspector 3.0.43 → 3.0.45

package/src/lib/managedInstance.ts

@@ -0,0 +1,104 @@
+export const MANAGED_INSTANCE_CONTROL_PATH = "/.agent-inspector/instance";
+export const MANAGED_INSTANCE_SHUTDOWN_PATH = `${MANAGED_INSTANCE_CONTROL_PATH}/shutdown`;
+export const MANAGED_INSTANCE_TOKEN_HEADER = "x-agent-inspector-instance-token";
+export const MANAGED_INSTANCE_SHUTDOWN_MESSAGE_TYPE = "agent-inspector:managed-shutdown";
+export const AGENT_INSPECTOR_CLI_ENTRY_ENV = "AGENT_INSPECTOR_CLI_ENTRY";
+
+export const MANAGED_INSTANCE_ENV = {
+  name: "AGENT_INSPECTOR_INSTANCE_NAME",
+  instanceId: "AGENT_INSPECTOR_INSTANCE_ID",
+  launchId: "AGENT_INSPECTOR_INSTANCE_LAUNCH_ID",
+  controlToken: "AGENT_INSPECTOR_INSTANCE_CONTROL_TOKEN",
+  startedAt: "AGENT_INSPECTOR_INSTANCE_STARTED_AT",
+  upstreamPort: "AGENT_INSPECTOR_UPSTREAM_PORT",
+} as const;
+
+type ManagedInstanceEnv = Readonly<Record<string, string | undefined>>;
+
+export type ManagedInstanceLaunch = {
+  name: string;
+  instanceId: string;
+  launchId: string;
+  controlToken: string;
+  startedAt: string;
+  upstreamPort: number;
+};
+
+export type ManagedInstanceLaunchResult =
+  | { kind: "unmanaged" }
+  | { kind: "invalid"; message: string }
+  | { kind: "managed"; launch: ManagedInstanceLaunch };
+
+export type ManagedInstanceShutdownMessage = {
+  type: typeof MANAGED_INSTANCE_SHUTDOWN_MESSAGE_TYPE;
+  controlToken: string;
+};
+
+function nonEmpty(value: string | undefined): string | null {
+  const trimmed = value?.trim();
+  return trimmed === undefined || trimmed.length === 0 ? null : trimmed;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function readManagedInstanceLaunch(
+  env: ManagedInstanceEnv = process.env,
+): ManagedInstanceLaunchResult {
+  const values = [
+    env[MANAGED_INSTANCE_ENV.name],
+    env[MANAGED_INSTANCE_ENV.instanceId],
+    env[MANAGED_INSTANCE_ENV.launchId],
+    env[MANAGED_INSTANCE_ENV.controlToken],
+    env[MANAGED_INSTANCE_ENV.startedAt],
+    env[MANAGED_INSTANCE_ENV.upstreamPort],
+  ];
+  if (values.every((value) => value === undefined || value.trim().length === 0)) {
+    return { kind: "unmanaged" };
+  }
+
+  const name = nonEmpty(env[MANAGED_INSTANCE_ENV.name]);
+  const instanceId = nonEmpty(env[MANAGED_INSTANCE_ENV.instanceId]);
+  const launchId = nonEmpty(env[MANAGED_INSTANCE_ENV.launchId]);
+  const controlToken = nonEmpty(env[MANAGED_INSTANCE_ENV.controlToken]);
+  const startedAt = nonEmpty(env[MANAGED_INSTANCE_ENV.startedAt]);
+  const upstreamPort = Number(env[MANAGED_INSTANCE_ENV.upstreamPort]);
+  if (
+    name === null ||
+    instanceId === null ||
+    launchId === null ||
+    controlToken === null ||
+    controlToken.length < 32 ||
+    startedAt === null ||
+    !Number.isFinite(Date.parse(startedAt)) ||
+    !Number.isInteger(upstreamPort) ||
+    upstreamPort < 1 ||
+    upstreamPort > 65_535
+  ) {
+    return {
+      kind: "invalid",
+      message: "Managed instance launch environment is incomplete or invalid.",
+    };
+  }
+  return {
+    kind: "managed",
+    launch: { name, instanceId, launchId, controlToken, startedAt, upstreamPort },
+  };
+}
+
+export function managedInstanceShutdownMessage(
+  controlToken: string,
+): ManagedInstanceShutdownMessage {
+  return { type: MANAGED_INSTANCE_SHUTDOWN_MESSAGE_TYPE, controlToken };
+}
+
+export function parseManagedInstanceShutdownMessage(
+  value: unknown,
+): ManagedInstanceShutdownMessage | null {
+  if (!isRecord(value)) return null;
+  return value["type"] === MANAGED_INSTANCE_SHUTDOWN_MESSAGE_TYPE &&
+    typeof value["controlToken"] === "string"
+    ? { type: MANAGED_INSTANCE_SHUTDOWN_MESSAGE_TYPE, controlToken: value["controlToken"] }
+    : null;
+}

package/src/lib/publicBasePathContext.ts

@@ -0,0 +1,107 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import {
+  AGENT_INSPECTOR_PUBLIC_BASE_PATH_HEADER,
+  AGENT_INSPECTOR_PUBLIC_PORT_HEADER,
+  getConfiguredBasePath,
+  normalizeBasePath,
+} from "./basePath";
+import { getCurrentPort } from "./serverPort";
+
+type BasePathEnv = Readonly<Record<string, string | undefined>>;
+
+type PublicRequestContext = {
+  basePath: string;
+  publicPort: number | null;
+};
+
+const publicRequestStorage = new AsyncLocalStorage<PublicRequestContext>();
+
+function isSafePublicBasePath(value: string): boolean {
+  if (value.length === 0) return true;
+  if (!/^\/[A-Za-z0-9._~-]+(?:\/[A-Za-z0-9._~-]+)*$/u.test(value)) return false;
+  return !value.split("/").some((segment) => segment === "." || segment === "..");
+}
+
+/**
+ * Resolve the public Base Path attached by the trusted ingress. Invalid or
+ * missing values fall back to the process's canonical Base Path.
+ */
+export function resolveRequestPublicBasePath(request: Request, env?: BasePathEnv): string {
+  const rawValue = request.headers.get(AGENT_INSPECTOR_PUBLIC_BASE_PATH_HEADER);
+  if (rawValue !== null) {
+    const normalized = normalizeBasePath(rawValue);
+    if (isSafePublicBasePath(normalized)) return normalized;
+  }
+  return getConfiguredBasePath(env ?? process.env);
+}
+
+/** Resolve the trusted ingress listener port without consulting request URL or Host. */
+export function resolveRequestPublicPort(request: Request): number | null {
+  const rawValue = request.headers.get(AGENT_INSPECTOR_PUBLIC_PORT_HEADER);
+  if (rawValue !== null && /^\d{1,5}$/u.test(rawValue)) {
+    const headerPort = Number(rawValue);
+    if (Number.isSafeInteger(headerPort) && headerPort > 0 && headerPort <= 65_535) {
+      return headerPort;
+    }
+  }
+  try {
+    return getCurrentPort();
+  } catch {
+    // Vite dev does not always publish its listener port through process env.
+  }
+  try {
+    const urlPort = new URL(request.url).port;
+    if (!/^\d{1,5}$/u.test(urlPort)) return null;
+    const port = Number(urlPort);
+    return Number.isSafeInteger(port) && port > 0 && port <= 65_535 ? port : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Return the originating request's public Base Path, or the canonical path outside a request. */
+export function getPublicBasePath(env?: BasePathEnv): string {
+  return publicRequestStorage.getStore()?.basePath ?? getConfiguredBasePath(env ?? process.env);
+}
+
+/** Return the trusted ingress listener port, or the canonical process port outside a request. */
+export function getPublicPort(): number {
+  return publicRequestStorage.getStore()?.publicPort ?? getCurrentPort();
+}
+
+/** Run work with an explicitly selected public Base Path. Primarily useful for internal calls. */
+export function runWithPublicBasePath<T>(basePath: string, callback: () => T): T {
+  const current = publicRequestStorage.getStore();
+  return publicRequestStorage.run(
+    {
+      basePath: normalizeBasePath(basePath),
+      publicPort: current?.publicPort ?? null,
+    },
+    callback,
+  );
+}
+
+/** Run work with an explicit trusted public listener port. */
+export function runWithPublicPort<T>(publicPort: number, callback: () => T): T {
+  const current = publicRequestStorage.getStore();
+  const normalizedPort =
+    Number.isSafeInteger(publicPort) && publicPort > 0 && publicPort <= 65_535 ? publicPort : null;
+  return publicRequestStorage.run(
+    {
+      basePath: current?.basePath ?? getConfiguredBasePath(process.env),
+      publicPort: normalizedPort,
+    },
+    callback,
+  );
+}
+
+/** Run the complete request chain with the ingress-selected public Base Path. */
+export function runWithRequestPublicBasePath<T>(request: Request, callback: () => T): T {
+  return publicRequestStorage.run(
+    {
+      basePath: resolveRequestPublicBasePath(request),
+      publicPort: resolveRequestPublicPort(request),
+    },
+    callback,
+  );
+}

package/src/mcp/instanceHandlers.ts

@@ -0,0 +1,149 @@
+import { z } from "zod";
+import {
+  InstanceConnectionOutputSchema,
+  InstanceEmptyRequestSchema,
+  InstanceErrorOutputSchema,
+  InstanceListOutputSchema,
+  InstanceOperationOutputSchema,
+  InstanceStartRequestSchema,
+  InstanceStatusOutputSchema,
+  type InstanceStartRequest,
+} from "../lib/instanceContract";
+import type { CallApiOptions } from "./loopback";
+import type { ToolResult } from "./toolHandlers";
+
+export const INSTANCE_LIFECYCLE_TIMEOUT_MS = 60_000;
+
+export const InstanceToolNameSchema = z.string().trim().min(1).max(64);
+
+export const InstanceLifecycleToolInputSchema = InstanceStartRequestSchema.extend({
+  name: InstanceToolNameSchema,
+});
+
+export const InstanceNameToolInputSchema = z
+  .object({
+    name: InstanceToolNameSchema,
+  })
+  .strict();
+
+export type InstanceCallApiFn = (path: string, options?: CallApiOptions) => Promise<Response>;
+
+export type InstanceLifecycleToolInput = InstanceStartRequest & { name: string };
+
+function textJson(data: unknown): ToolResult {
+  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}
+
+function toolError(message: string): ToolResult {
+  return { content: [{ type: "text", text: message }], isError: true };
+}
+
+async function responseJson(response: Response): Promise<unknown | null> {
+  try {
+    const value: unknown = await response.json();
+    return value;
+  } catch {
+    return null;
+  }
+}
+
+async function validatedInstanceResponse(
+  response: Response,
+  schema: z.ZodType,
+  operation: string,
+): Promise<ToolResult> {
+  const value = await responseJson(response);
+  if (!response.ok) {
+    const error = InstanceErrorOutputSchema.safeParse(value);
+    return error.success
+      ? { ...textJson(error.data), isError: true }
+      : toolError(
+          `${operation} returned HTTP ${String(response.status)} with an invalid error body`,
+        );
+  }
+
+  const parsed = schema.safeParse(value);
+  return parsed.success
+    ? textJson(parsed.data)
+    : toolError(`${operation} returned an invalid public instance document`);
+}
+
+function instancePath(name: string, suffix = ""): string {
+  return `/api/instances/${encodeURIComponent(name)}${suffix}`;
+}
+
+function jsonPost(body: unknown): CallApiOptions {
+  return {
+    method: "POST",
+    headers: {
+      accept: "application/json",
+      "content-type": "application/json",
+    },
+    body: JSON.stringify(body),
+    timeoutMs: INSTANCE_LIFECYCLE_TIMEOUT_MS,
+  };
+}
+
+function lifecycleRequest(input: InstanceLifecycleToolInput): InstanceStartRequest {
+  return {
+    port: input.port,
+    basePath: input.basePath,
+    host: input.host,
+    captureMode: input.captureMode,
+    dataDir: input.dataDir,
+  };
+}
+
+export async function listInstancesImpl(callApi: InstanceCallApiFn): Promise<ToolResult> {
+  const response = await callApi("/api/instances", {
+    headers: { accept: "application/json" },
+  });
+  return validatedInstanceResponse(response, InstanceListOutputSchema, "GET /api/instances");
+}
+
+export async function getInstanceImpl(
+  callApi: InstanceCallApiFn,
+  name: string,
+): Promise<ToolResult> {
+  const path = instancePath(name);
+  const response = await callApi(path, { headers: { accept: "application/json" } });
+  return validatedInstanceResponse(response, InstanceStatusOutputSchema, `GET ${path}`);
+}
+
+export async function getInstanceConnectionImpl(
+  callApi: InstanceCallApiFn,
+  name: string,
+): Promise<ToolResult> {
+  const path = instancePath(name, "/connection");
+  const response = await callApi(path, { headers: { accept: "application/json" } });
+  return validatedInstanceResponse(response, InstanceConnectionOutputSchema, `GET ${path}`);
+}
+
+export async function startInstanceImpl(
+  callApi: InstanceCallApiFn,
+  input: InstanceLifecycleToolInput,
+): Promise<ToolResult> {
+  const path = instancePath(input.name, "/start");
+  const request = lifecycleRequest(input);
+  const response = await callApi(path, jsonPost(InstanceStartRequestSchema.parse(request)));
+  return validatedInstanceResponse(response, InstanceOperationOutputSchema, `POST ${path}`);
+}
+
+export async function stopInstanceImpl(
+  callApi: InstanceCallApiFn,
+  name: string,
+): Promise<ToolResult> {
+  const path = instancePath(name, "/stop");
+  const response = await callApi(path, jsonPost(InstanceEmptyRequestSchema.parse({})));
+  return validatedInstanceResponse(response, InstanceOperationOutputSchema, `POST ${path}`);
+}
+
+export async function restartInstanceImpl(
+  callApi: InstanceCallApiFn,
+  input: InstanceLifecycleToolInput,
+): Promise<ToolResult> {
+  const path = instancePath(input.name, "/restart");
+  const request = lifecycleRequest(input);
+  const response = await callApi(path, jsonPost(InstanceStartRequestSchema.parse(request)));
+  return validatedInstanceResponse(response, InstanceOperationOutputSchema, `POST ${path}`);
+}

package/src/mcp/loopback.ts

@@ -16,8 +16,12 @@
  * — should stay identical so callers don't change.
  */
 
-import { getConfiguredBasePath, withBasePath } from "../lib/basePath";
-import { getCurrentPort } from "../lib/serverPort";
+import {
+  AGENT_INSPECTOR_PUBLIC_BASE_PATH_HEADER,
+  AGENT_INSPECTOR_PUBLIC_PORT_HEADER,
+  withBasePath,
+} from "../lib/basePath";
+import { getPublicBasePath, getPublicPort } from "../lib/publicBasePathContext";
 
 const DEFAULT_TIMEOUT_MS = 30_000;
 
@@ -47,10 +51,17 @@ export async function callApi(path: string, options: CallApiOptions = {}): Promi
   if (!path.startsWith("/")) {
     throw new Error(`callApi: path must start with '/', got: ${path}`);
   }
-  const port = getCurrentPort();
-  const url = `http://127.0.0.1:${port}${withBasePath(path, getConfiguredBasePath(process.env))}`;
+  const port = getPublicPort();
+  const publicBasePath = getPublicBasePath();
+  const url = `http://127.0.0.1:${port}${withBasePath(path, publicBasePath)}`;
 
   const { timeoutMs = DEFAULT_TIMEOUT_MS, signal: userSignal, ...rest } = options;
+  const headers = new Headers(rest.headers);
+  headers.set(
+    AGENT_INSPECTOR_PUBLIC_BASE_PATH_HEADER,
+    publicBasePath.length === 0 ? "/" : publicBasePath,
+  );
+  headers.set(AGENT_INSPECTOR_PUBLIC_PORT_HEADER, String(port));
 
   const controller = new AbortController();
   const timeoutHandle = setTimeout(() => controller.abort(), timeoutMs);
@@ -65,7 +76,7 @@ export async function callApi(path: string, options: CallApiOptions = {}): Promi
   }
 
   try {
-    return await fetch(url, { ...rest, signal: controller.signal });
+    return await fetch(url, { ...rest, headers, signal: controller.signal });
   } catch (err) {
     if (err instanceof Error && err.name === "AbortError") {
       throw new LoopbackTimeoutError(path, timeoutMs);

package/src/mcp/mode.ts

@@ -1,5 +1,7 @@
 export type McpWriteMode = "enabled" | "readonly";
 
+export const MCP_INSTANCE_WRITES_ENV = "AGENT_INSPECTOR_MCP_INSTANCE_WRITES";
+
 function parseFlag(value: string | undefined): boolean | null {
   if (value === undefined) return null;
   switch (value.trim().toLowerCase()) {
@@ -26,6 +28,29 @@ export function isMcpWriteEnabled(): boolean {
   return writesFlag === true;
 }
 
+export function isMcpInstanceWriteEnabled(): boolean {
+  return process.env[MCP_INSTANCE_WRITES_ENV] === "1";
+}
+
+export function getMcpInstanceModeInfo(): {
+  writeMode: McpWriteMode;
+  writesEnabled: boolean;
+  env: { AGENT_INSPECTOR_MCP_INSTANCE_WRITES: string | null };
+  note: string;
+} {
+  const writesEnabled = isMcpInstanceWriteEnabled();
+  return {
+    writeMode: writesEnabled ? "enabled" : "readonly",
+    writesEnabled,
+    env: {
+      AGENT_INSPECTOR_MCP_INSTANCE_WRITES: process.env[MCP_INSTANCE_WRITES_ENV] ?? null,
+    },
+    note: writesEnabled
+      ? "Named-instance lifecycle tools passed the instance-specific opt-in. General MCP writes must also be enabled."
+      : "Named-instance lifecycle tools require AGENT_INSPECTOR_MCP_INSTANCE_WRITES=1 in addition to general MCP writes.",
+  };
+}
+
 export function getMcpModeInfo(): {
   writeMode: McpWriteMode;
   writesEnabled: boolean;