@tonyclaw/agent-inspector 3.0.44 → 3.0.45

package/src/mcp/server.ts

@@ -33,9 +33,14 @@ import {
   UpdateInspectorGroupInputSchema,
 } from "../lib/groupContract";
 import { InspectorRunStatusSchema, UpdateInspectorRunInputSchema } from "../lib/runContract";
-import { getCurrentPort, setCurrentPort } from "../lib/serverPort";
-import { getConfiguredBasePath, withBasePath } from "../lib/basePath";
+import { withBasePath } from "../lib/basePath";
+import {
+  getPublicBasePath,
+  getPublicPort,
+  runWithRequestPublicBasePath,
+} from "../lib/publicBasePathContext";
 import { JsonValueSchema } from "../contracts";
+import { InstanceListOutputSchema } from "../lib/instanceContract";
 import {
   MAX_PROVIDER_MODEL_NAME_CHARS,
   MAX_PROVIDER_MODELS,
@@ -43,7 +48,22 @@ import {
   MAX_SEARCH_QUERY_CHARS,
 } from "../lib/resourceLimits";
 import { getCurrentContext } from "./currentContext";
-import { getMcpModeInfo, isMcpWriteEnabled } from "./mode";
+import {
+  getMcpInstanceModeInfo,
+  getMcpModeInfo,
+  isMcpInstanceWriteEnabled,
+  isMcpWriteEnabled,
+} from "./mode";
+import {
+  getInstanceConnectionImpl,
+  getInstanceImpl,
+  InstanceLifecycleToolInputSchema,
+  InstanceNameToolInputSchema,
+  listInstancesImpl,
+  restartInstanceImpl,
+  startInstanceImpl,
+  stopInstanceImpl,
+} from "./instanceHandlers";
 import {
   getInspectorGroup,
   listInspectorGroups,
@@ -178,17 +198,10 @@ export async function _resetForTests(): Promise<void> {
  * handler — accepts a Web `Request`, returns a `Promise<Response>`.
  */
 export async function handleMcpRequest(request: Request): Promise<Response> {
-  // Extract port from the incoming request URL so loopback calls work even
-  // when PORT env var is unset (e.g. MCP client connected before server init).
-  try {
-    const url = new URL(request.url);
-    const port = Number(url.port);
-    if (port > 0) setCurrentPort(port);
-  } catch {
-    // URL parse failure → fall through to PORT env var in getCurrentPort()
-  }
-  const { transport } = await getServer();
-  return transport.handleRequest(request);
+  return runWithRequestPublicBasePath(request, async () => {
+    const { transport } = await getServer();
+    return transport.handleRequest(request);
+  });
 }
 
 // ---------------------------------------------------------------------------
@@ -219,6 +232,27 @@ Either preview field is null when the body is unknown format, unparseable, or th
 const PROVIDER_WRITE_WARNING =
   "⚠ This tool mutates provider configuration. Confirm with the user before invoking.";
 
+const INSTANCE_LIFECYCLE_WRITE_WARNING =
+  "This tool changes a local Agent Inspector process. Obtain explicit user approval before invoking it.";
+
+const INSTANCE_READ_TOOL_NAMES = [
+  "inspector_list_instances",
+  "inspector_get_instance",
+  "inspector_get_instance_connection",
+] as const;
+
+const INSTANCE_WRITE_TOOL_NAMES = [
+  "inspector_start_instance",
+  "inspector_stop_instance",
+  "inspector_restart_instance",
+] as const;
+
+const INSTANCE_RESOURCE_URIS = [
+  "inspector://instances",
+  "inspector://instances/{name}",
+  "inspector://instances/{name}/connection",
+] as const;
+
 const AddProviderInputSchema = z
   .object({
     name: z.string().min(1).describe("Provider display name."),
@@ -327,9 +361,9 @@ function jsonResource(uri: URL, data: unknown): ReadResourceResult {
 }
 
 function mcpEndpointUrl(): string {
-  return `http://localhost:${String(getCurrentPort())}${withBasePath(
+  return `http://localhost:${String(getPublicPort())}${withBasePath(
     "/api/mcp",
-    getConfiguredBasePath(process.env),
+    getPublicBasePath(),
   )}`;
 }
 
@@ -342,7 +376,7 @@ function mcpHealth(): Record<string, unknown> {
     },
     transport: {
       primary: "streamable-http",
-      endpoint: withBasePath("/api/mcp", getConfiguredBasePath(process.env)),
+      endpoint: mcpEndpointUrl(),
       stateless: true,
     },
     mode: getMcpModeInfo(),
@@ -355,6 +389,7 @@ function mcpHealth(): Record<string, unknown> {
 }
 
 const WRITE_TOOL_NAMES = new Set<string>([
+  ...INSTANCE_WRITE_TOOL_NAMES,
   "inspector_create_run",
   "inspector_update_run",
   "inspector_export_evidence",
@@ -379,18 +414,36 @@ const WRITE_TOOL_NAMES = new Set<string>([
 function mcpCapabilities(): Record<string, unknown> {
   const readTools = TOOL_NAMES.filter((name) => !WRITE_TOOL_NAMES.has(name));
   const writeTools = TOOL_NAMES.filter((name) => WRITE_TOOL_NAMES.has(name));
+  const generalWriteMode = getMcpModeInfo();
+  const instanceWriteMode = getMcpInstanceModeInfo();
   return {
     serverInfo: {
       name: "agent-inspector",
       version: MCP_SERVER_VERSION,
     },
-    mode: getMcpModeInfo(),
+    mode: generalWriteMode,
     tools: {
       read: readTools,
       writeOrAction: writeTools,
     },
     resources: RESOURCE_NAMES,
     prompts: PROMPT_NAMES,
+    instanceControl: {
+      tools: {
+        read: INSTANCE_READ_TOOL_NAMES,
+        writeOrAction: INSTANCE_WRITE_TOOL_NAMES,
+      },
+      resources: INSTANCE_RESOURCE_URIS,
+      writeGates: {
+        general: generalWriteMode,
+        instance: instanceWriteMode,
+        lifecycleWritesEnabled: generalWriteMode.writesEnabled && instanceWriteMode.writesEnabled,
+      },
+      limitations: {
+        selfStopOrRestart:
+          "The serving managed instance cannot stop or restart itself over REST or MCP. Use the CLI or a sibling controller instance.",
+      },
+    },
   };
 }
 
@@ -473,6 +526,36 @@ function safeWriteCall(
   });
 }
 
+function disabledInstanceWriteTool(toolName: string): ToolResult {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(
+          {
+            error: "mcp-instance-write-disabled",
+            tool: toolName,
+            generalMode: getMcpModeInfo(),
+            instanceMode: getMcpInstanceModeInfo(),
+          },
+          null,
+          2,
+        ),
+      },
+    ],
+    isError: true,
+  };
+}
+
+function safeInstanceWriteCall(
+  toolName: string,
+  fn: () => ToolResult | Promise<ToolResult>,
+): Promise<ToolResult> {
+  return safeWriteCall(toolName, () =>
+    isMcpInstanceWriteEnabled() ? fn() : disabledInstanceWriteTool(toolName),
+  );
+}
+
 function variableString(variables: Variables, name: string): string | null {
   const value = variables[name];
   if (Array.isArray(value)) return value[0] ?? null;
@@ -504,6 +587,41 @@ function readServiceJsonResource<T>(
   return jsonResource(uri, result.value);
 }
 
+async function readInstanceToolResource(
+  uri: URL,
+  resultPromise: Promise<ToolResult>,
+): Promise<ReadResourceResult> {
+  const result = await resultPromise;
+  const text = result.content[0]?.text ?? "";
+  return textResource(uri, result.isError === true ? "text/plain" : "application/json", text);
+}
+
+async function listInstanceTemplateResources(connection: boolean): Promise<ListResourcesResult> {
+  try {
+    const response = await callApi("/api/instances", {
+      headers: { accept: "application/json" },
+    });
+    if (!response.ok) return listResult([]);
+    const parsed = InstanceListOutputSchema.safeParse(await response.json());
+    if (!parsed.success) return listResult([]);
+    return listResult(
+      parsed.data.instances.map((instance) => ({
+        uri: connection
+          ? `inspector://instances/${encodeURIComponent(instance.name)}/connection`
+          : `inspector://instances/${encodeURIComponent(instance.name)}`,
+        name: connection ? `instance-connection:${instance.name}` : `instance:${instance.name}`,
+        title: connection
+          ? `Agent Inspector connection for ${instance.name}`
+          : `Agent Inspector instance ${instance.name}`,
+        mimeType: "application/json",
+        description: `${instance.state} at ${instance.urls.ui}`,
+      })),
+    );
+  } catch {
+    return listResult([]);
+  }
+}
+
 async function listSessionResources(): Promise<ListResourcesResult> {
   try {
     const response = await callApi("/api/sessions");
@@ -707,6 +825,74 @@ function userPrompt(text: string): GetPromptResult {
 // ---------------------------------------------------------------------------
 
 function registerTools(server: McpServer): void {
+  // ----- Named instance discovery and lifecycle -----
+
+  server.registerTool(
+    "inspector_list_instances",
+    {
+      title: "List named Agent Inspector instances",
+      description:
+        "Returns the versioned, token-free REST instance list with live state, saved configuration, and public URLs. Available in readonly mode.",
+      inputSchema: z.object({}).strict(),
+    },
+    () => safeCall(() => listInstancesImpl(callApi)),
+  );
+
+  server.registerTool(
+    "inspector_get_instance",
+    {
+      title: "Get a named Agent Inspector instance",
+      description:
+        "Returns one versioned, token-free named-instance status document from the REST control plane. Available in readonly mode.",
+      inputSchema: InstanceNameToolInputSchema,
+    },
+    ({ name }) => safeCall(() => getInstanceImpl(callApi, name)),
+  );
+
+  server.registerTool(
+    "inspector_get_instance_connection",
+    {
+      title: "Get coding-agent connection settings for an instance",
+      description:
+        "Returns the REST connection descriptor for one named instance, including protocol-correct proxy, OpenAI /v1, MCP, health, environment, and Codex values. It never includes credentials.",
+      inputSchema: InstanceNameToolInputSchema,
+    },
+    ({ name }) => safeCall(() => getInstanceConnectionImpl(callApi, name)),
+  );
+
+  server.registerTool(
+    "inspector_start_instance",
+    {
+      title: "Start or create a named Agent Inspector instance",
+      description: `${INSTANCE_LIFECYCLE_WRITE_WARNING} Starts, creates, or idempotently reuses a named sibling instance through the REST lifecycle API. Requires both AGENT_INSPECTOR_MCP_WRITES=1 and AGENT_INSPECTOR_MCP_INSTANCE_WRITES=1.`,
+      inputSchema: InstanceLifecycleToolInputSchema,
+    },
+    (args) =>
+      safeInstanceWriteCall("inspector_start_instance", () => startInstanceImpl(callApi, args)),
+  );
+
+  server.registerTool(
+    "inspector_stop_instance",
+    {
+      title: "Stop a named Agent Inspector instance",
+      description: `${INSTANCE_LIFECYCLE_WRITE_WARNING} Gracefully stops a sibling instance after authenticated ownership checks. The instance serving this MCP connection cannot stop itself. Requires both MCP write gates.`,
+      inputSchema: InstanceNameToolInputSchema,
+    },
+    ({ name }) =>
+      safeInstanceWriteCall("inspector_stop_instance", () => stopInstanceImpl(callApi, name)),
+  );
+
+  server.registerTool(
+    "inspector_restart_instance",
+    {
+      title: "Restart a named Agent Inspector instance",
+      description: `${INSTANCE_LIFECYCLE_WRITE_WARNING} Validates and restarts a sibling instance through the bounded REST lifecycle path. The instance serving this MCP connection cannot restart itself. Requires both MCP write gates.`,
+      inputSchema: InstanceLifecycleToolInputSchema,
+    },
+    (args) =>
+      safeInstanceWriteCall("inspector_restart_instance", () => restartInstanceImpl(callApi, args)),
+  );
+
   // ----- Read tools -----
 
   server.registerTool(
@@ -1460,6 +1646,55 @@ PATCH-style update: only the fields you supply are changed. Use models to update
 }
 
 function registerResources(server: McpServer): void {
+  server.registerResource(
+    "inspector_instances",
+    "inspector://instances",
+    {
+      title: "Named Agent Inspector instances",
+      description: "Versioned, token-free named-instance list backed by GET /api/instances.",
+      mimeType: "application/json",
+    },
+    (uri) => readInstanceToolResource(uri, listInstancesImpl(callApi)),
+  );
+
+  server.registerResource(
+    "inspector_instance",
+    new ResourceTemplate("inspector://instances/{name}", {
+      list: async () => await listInstanceTemplateResources(false),
+    }),
+    {
+      title: "Named Agent Inspector instance",
+      description:
+        "Versioned, token-free status for one named instance backed by GET /api/instances/{name}.",
+      mimeType: "application/json",
+    },
+    (uri, variables) => {
+      const name = variableString(variables, "name");
+      return name === null
+        ? textResource(uri, "text/plain", "Missing instance name")
+        : readInstanceToolResource(uri, getInstanceImpl(callApi, name));
+    },
+  );
+
+  server.registerResource(
+    "inspector_instance_connection",
+    new ResourceTemplate("inspector://instances/{name}/connection", {
+      list: async () => await listInstanceTemplateResources(true),
+    }),
+    {
+      title: "Named instance coding-agent connection",
+      description:
+        "Token-free connection descriptor backed by GET /api/instances/{name}/connection.",
+      mimeType: "application/json",
+    },
+    (uri, variables) => {
+      const name = variableString(variables, "name");
+      return name === null
+        ? textResource(uri, "text/plain", "Missing instance name")
+        : readInstanceToolResource(uri, getInstanceConnectionImpl(callApi, name));
+    },
+  );
+
   server.registerResource(
     "inspector_mcp_health",
     "inspector://mcp/health",
@@ -1958,6 +2193,8 @@ Return:
 
 // Surface the tool catalog for tests that assert on the tool name set.
 export const TOOL_NAMES = [
+  ...INSTANCE_READ_TOOL_NAMES,
+  ...INSTANCE_WRITE_TOOL_NAMES,
   "inspector_list_logs",
   "inspector_search_logs",
   "inspector_get_log",
@@ -2006,6 +2243,9 @@ export const TOOL_NAMES = [
 ] as const;
 
 export const RESOURCE_NAMES = [
+  "inspector_instances",
+  "inspector_instance",
+  "inspector_instance_connection",
   "inspector_mcp_health",
   "inspector_mcp_capabilities",
   "inspector_mcp_config",

package/src/mcp/toolHandlers.ts

@@ -20,7 +20,7 @@ import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import JSZip from "jszip";
 import { z } from "zod";
-import { getCurrentPort } from "../lib/serverPort";
+import { getPublicPort } from "../lib/publicBasePathContext";
 import { LoopbackTimeoutError, type CallApiOptions } from "./loopback";
 import { extractLastUserMessagePreview, extractResponsePreview } from "./previewExtractor";
 import {
@@ -138,7 +138,7 @@ function redactedProvidersResult(value: unknown): ToolResult {
 }
 
 function inspectorBaseUrl(): string {
-  return `http://127.0.0.1:${String(getCurrentPort())}`;
+  return `http://127.0.0.1:${String(getPublicPort())}`;
 }
 
 function hasBodyText(value: string | null, byteLength: number | null | undefined): boolean {