@tonyclaw/agent-inspector 3.0.44 → 3.0.46

package/src/mcp/instanceHandlers.ts

@@ -0,0 +1,150 @@
+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,
+    uiEnabled: input.uiEnabled,
+    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;

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 { JsonValueSchema } from "../contracts";
+import { withBasePath } from "../lib/basePath";
+import {
+  getPublicBasePath,
+  getPublicOrigin,
+  runWithRequestPublicBasePath,
+} from "../lib/publicBasePathContext";
+import { JsonValueSchema, LogIdSchema, parseLogId } 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."),
@@ -301,7 +335,15 @@ const UpdateProviderInputSchema = z.object({
 });
 
 const LogResourceListResponseSchema = z.object({
-  logs: z.array(z.object({ id: z.number().int().positive() })),
+  logs: z.array(z.object({ id: LogIdSchema })),
+});
+
+export const McpLogIdInputSchema = z.object({
+  id: LogIdSchema.describe("The log id."),
+});
+
+export const McpOptionalLogIdInputSchema = z.object({
+  id: LogIdSchema.optional().describe("Optional log id to inspect."),
 });
 
 const ProcessResourceListResponseSchema = z.object({
@@ -327,10 +369,7 @@ function jsonResource(uri: URL, data: unknown): ReadResourceResult {
 }
 
 function mcpEndpointUrl(): string {
-  return `http://localhost:${String(getCurrentPort())}${withBasePath(
-    "/api/mcp",
-    getConfiguredBasePath(process.env),
-  )}`;
+  return `${getPublicOrigin()}${withBasePath("/api/mcp", getPublicBasePath())}`;
 }
 
 function mcpHealth(): Record<string, unknown> {
@@ -342,7 +381,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 +394,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 +419,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 +531,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 +592,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 +830,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(
@@ -782,9 +973,7 @@ function registerTools(server: McpServer): void {
       title: "Get a single captured log by id",
       description:
         "Returns the full CapturedLog for the given id, including rawRequestBody and responseText with no truncation. SSE streaming chunks are NOT included — use inspector_get_log_chunks for those. Returns an error if the id does not exist.",
-      inputSchema: z.object({
-        id: z.number().int().positive().describe("The log id."),
-      }),
+      inputSchema: McpLogIdInputSchema,
     },
     ({ id }) => safeCall(() => getLogImpl(callApi, id)),
   );
@@ -795,9 +984,7 @@ function registerTools(server: McpServer): void {
       title: "Get SSE streaming chunks for a captured log",
       description:
         "Returns the SSE chunks array for a streaming log, in the order they were received. Returns an error if the log has no chunks (i.e. was non-streaming or the log id is unknown).",
-      inputSchema: z.object({
-        id: z.number().int().positive().describe("The log id."),
-      }),
+      inputSchema: McpLogIdInputSchema,
     },
     ({ id }) => safeCall(() => getLogChunksImpl(callApi, id)),
   );
@@ -808,9 +995,7 @@ function registerTools(server: McpServer): void {
       title: "Get captured log headers",
       description:
         "Returns header-focused evidence for one log without large request/response bodies: raw headers, upstream headers, user-agent, origin, client PID/port, session id, model, and API path.",
-      inputSchema: z.object({
-        id: z.number().int().positive().describe("The log id."),
-      }),
+      inputSchema: McpLogIdInputSchema,
     },
     ({ id }) => safeCall(() => getLogHeadersImpl(callApi, id)),
   );
@@ -988,9 +1173,7 @@ function registerTools(server: McpServer): void {
       title: "Diagnose capture detail availability",
       description:
         "Explains why headers or bodies may be missing for the current runtime or a specific log, including captureMode, compact body mode, rawHeaders presence, and next-step recommendations.",
-      inputSchema: z.object({
-        id: z.number().int().positive().optional().describe("Optional log id to inspect."),
-      }),
+      inputSchema: McpOptionalLogIdInputSchema,
     },
     (args) => safeCall(() => diagnoseCaptureImpl(callApi, args)),
   );
@@ -1318,9 +1501,7 @@ function registerTools(server: McpServer): void {
       title: "Replay a captured log against its provider",
       description:
         "Re-sends the captured request body to the upstream LLM and returns the response summary: success flag, status, responseText, input/output token counts, elapsedMs, and whether the response was streaming. Useful for re-running a request after a fix or a transient failure. Returns an error if the log id is unknown or the upstream call fails.",
-      inputSchema: z.object({
-        id: z.number().int().positive().describe("The log id to replay."),
-      }),
+      inputSchema: McpLogIdInputSchema,
     },
     (args) => safeWriteCall("inspector_replay_log", () => replayLogImpl(callApi, args)),
   );
@@ -1460,6 +1641,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",
@@ -1580,8 +1810,8 @@ function registerResources(server: McpServer): void {
     },
     async (uri, variables) => {
       const id = variableString(variables, "id");
-      const parsed = id === null ? Number.NaN : Number(id);
-      if (!Number.isInteger(parsed) || parsed <= 0) {
+      const parsed = id === null ? null : parseLogId(id);
+      if (parsed === null) {
         return textResource(uri, "text/plain", "Invalid log id");
       }
       const result = await getLogImpl(callApi, parsed);
@@ -1958,6 +2188,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 +2238,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",