@tonyclaw/agent-inspector 3.0.45 → 3.0.46

package/src/cli/instanceRegistry.ts

@@ -500,15 +500,6 @@ export function withRegistryLock<T>(
   return runWithLock(acquireRegistryLock(root, options), operation);
 }
 
-export function withInstanceLock<T>(
-  root: string,
-  rawName: string,
-  operation: LockedOperation<T>,
-  options: InstanceLockOptions = {},
-): Promise<InstanceRegistryResult<T>> {
-  return runWithLock(acquireInstanceLock(root, rawName, options), operation);
-}
-
 type PathApi = typeof win32;
 
 export type CanonicalDataDirectory = {

package/src/cli/networkHints.ts

@@ -1,4 +1,5 @@
 import { networkInterfaces } from "node:os";
+import { isIP } from "node:net";
 import { appendBasePathToOrigin, normalizeBasePath } from "../lib/basePath";
 
 export type NetworkInterfaceMap = ReturnType<typeof networkInterfaces>;
@@ -22,12 +23,12 @@ export function isWildcardHost(host: BindHost): boolean {
 export function isLoopbackHost(host: BindHost): boolean {
   const trimmed = trimHost(host);
   if (trimmed === undefined) return false;
-  return (
-    trimmed === "localhost" ||
-    trimmed === "::1" ||
-    trimmed === "[::1]" ||
-    trimmed.startsWith("127.")
-  );
+  const normalized =
+    trimmed.startsWith("[") && trimmed.endsWith("]")
+      ? trimmed.slice(1, -1).toLowerCase()
+      : trimmed.toLowerCase();
+  if (normalized === "localhost" || normalized === "::1") return true;
+  return isIP(normalized) === 4 && normalized.split(".", 1)[0] === "127";
 }
 
 function bracketIpv6(host: string): string {
@@ -112,11 +113,28 @@ function accessUrl(origin: string, path: string, basePath: string): string {
   return appendBasePathToOrigin(origin, path, basePath);
 }
 
+function appendSurfaceLines(
+  lines: string[],
+  label: "Local" | "Bound" | "Network",
+  origin: string,
+  basePath: string,
+  uiEnabled: boolean,
+): void {
+  const baseUrl = accessUrl(origin, "/", basePath);
+  if (uiEnabled) lines.push(`   ${label} UI:       ${baseUrl}`);
+  lines.push(`   ${label} control Base: ${baseUrl}`);
+  lines.push(`   ${label} agent Base:   ${baseUrl}`);
+  lines.push(`   ${label} REST API:     ${accessUrl(origin, "/api", basePath)}`);
+  lines.push(`   ${label} proxy:        ${accessUrl(origin, "/proxy", basePath)}`);
+  lines.push(`   ${label} MCP:          ${accessUrl(origin, "/api/mcp", basePath)}`);
+}
+
 export function formatAccessHintLines(
   port: number,
   networkUrls: readonly string[],
   host: BindHost = undefined,
   basePath = "",
+  uiEnabled = true,
 ): string[] {
   const normalizedBasePath = normalizeBasePath(basePath);
   const localUrl = localUrlForPort(port);
@@ -124,14 +142,10 @@ export function formatAccessHintLines(
   const lines = ["Access URLs:", `   Bind host:      ${hostLabel}`];
 
   if (isLoopbackHost(host) || isWildcardHost(host)) {
-    lines.push(`   Local UI:       ${accessUrl(localUrl, "/", normalizedBasePath)}`);
-    lines.push(`   Local proxy:    ${accessUrl(localUrl, "/proxy", normalizedBasePath)}`);
-    lines.push(`   Local MCP:      ${accessUrl(localUrl, "/api/mcp", normalizedBasePath)}`);
+    appendSurfaceLines(lines, "Local", localUrl, normalizedBasePath, uiEnabled);
   } else {
     const boundUrl = urlForHost(port, host);
-    lines.push(`   Bound UI:       ${accessUrl(boundUrl, "/", normalizedBasePath)}`);
-    lines.push(`   Bound proxy:    ${accessUrl(boundUrl, "/proxy", normalizedBasePath)}`);
-    lines.push(`   Bound MCP:      ${accessUrl(boundUrl, "/api/mcp", normalizedBasePath)}`);
+    appendSurfaceLines(lines, "Bound", boundUrl, normalizedBasePath, uiEnabled);
     lines.push("   Localhost:      may not work because the server is bound to a specific host");
   }
 
@@ -141,8 +155,7 @@ export function formatAccessHintLines(
   } else if (firstNetworkUrl === undefined) {
     lines.push("   Network:        no non-loopback IPv4 address detected");
   } else {
-    lines.push(`   Network UI:     ${accessUrl(firstNetworkUrl, "/", normalizedBasePath)}`);
-    lines.push(`   Network proxy:  ${accessUrl(firstNetworkUrl, "/proxy", normalizedBasePath)}`);
+    appendSurfaceLines(lines, "Network", firstNetworkUrl, normalizedBasePath, uiEnabled);
     const moreUrls = networkUrls.slice(1);
     if (moreUrls.length > 0) {
       lines.push(`   Other IPs:      ${moreUrls.join(", ")}`);

package/src/cli/onboard.ts

@@ -78,6 +78,9 @@ export type OnboardFlags = {
   mimoMcpUrl: string | null;
   instanceName: string | null;
   baseUrl: string | null;
+  controlBaseUrl: string | null;
+  agentBaseUrl: string | null;
+  uiUrl: string | null | undefined;
   mcpName: string | null;
   uninstall: boolean;
   status: boolean;
@@ -212,6 +215,9 @@ function parseFlags(argv: readonly string[]): OnboardFlags {
     mimoMcpUrl: null,
     instanceName: null,
     baseUrl: null,
+    controlBaseUrl: null,
+    agentBaseUrl: null,
+    uiUrl: undefined,
     mcpName: null,
     uninstall: false,
     status: false,
@@ -360,6 +366,39 @@ function parseFlags(argv: readonly string[]): OnboardFlags {
         i++;
         break;
       }
+      case "--control-base-url": {
+        const next = argv[i + 1];
+        if (next === undefined || next.trim().length === 0) {
+          process.stderr.write("agent-inspector onboard: --control-base-url requires a URL\n");
+          process.exit(2);
+        }
+        flags.controlBaseUrl = next;
+        i++;
+        break;
+      }
+      case "--agent-base-url": {
+        const next = argv[i + 1];
+        if (next === undefined || next.trim().length === 0) {
+          process.stderr.write("agent-inspector onboard: --agent-base-url requires a URL\n");
+          process.exit(2);
+        }
+        flags.agentBaseUrl = next;
+        i++;
+        break;
+      }
+      case "--ui-url": {
+        const next = argv[i + 1];
+        if (next === undefined || next.trim().length === 0) {
+          process.stderr.write("agent-inspector onboard: --ui-url requires a URL\n");
+          process.exit(2);
+        }
+        flags.uiUrl = next;
+        i++;
+        break;
+      }
+      case "--no-ui":
+        flags.uiUrl = null;
+        break;
       case "--mcp-name": {
         const next = argv[i + 1];
         if (next === undefined || next.trim().length === 0) {
@@ -440,7 +479,11 @@ Options:
                            MiMo Code MCP transport to write (default: local)
   --mimo-mcp-url <url>     Agent Inspector MCP endpoint for MiMo Code
   --instance <name>        Target a registered named Inspector instance
-  --base-url <url>         Target an explicit credential-free Inspector Base URL
+  --base-url <url>         Target an explicit credential-free backend control/agent Base URL
+  --control-base-url <url> Control API Base URL for a separated deployment
+  --agent-base-url <url>   Proxy and MCP Base URL for Coding Agents
+  --ui-url <url>           Browser UI URL for a separated deployment
+  --no-ui                  Declare that the explicit target has no browser UI
   --mcp-name <name>        MCP config key (named default: agent-inspector-<instance>)
   --uninstall              Remove generated files whose version matches this package
   --status                 Show installed onboarding file versions and suggested action
@@ -533,7 +576,22 @@ function onboardSelectionArguments(flags: OnboardFlags, target: OnboardTarget):
   if (target.kind === "instance" && target.instanceName !== null) {
     args.push("--instance", target.instanceName);
   } else if (target.kind === "base-url") {
-    args.push("--base-url", target.baseUrl);
+    const usedSharedBaseUrl =
+      flags.baseUrl !== null &&
+      flags.controlBaseUrl === null &&
+      flags.agentBaseUrl === null &&
+      flags.uiUrl === undefined;
+    if (usedSharedBaseUrl) {
+      args.push("--base-url", target.baseUrl);
+    } else {
+      args.push("--control-base-url", target.controlBaseUrl);
+      args.push("--agent-base-url", target.agentBaseUrl);
+      if (target.uiUrl === null) {
+        args.push("--no-ui");
+      } else {
+        args.push("--ui-url", target.uiUrl);
+      }
+    }
   }
   if (flags.mcpName !== null) args.push("--mcp-name", target.mcpName);
   return args.length === 0 ? "" : ` ${args.join(" ")}`;
@@ -1202,6 +1260,9 @@ function buildPlannedFiles(
         version,
         port: onboardTarget.port,
         baseUrl: onboardTarget.baseUrl,
+        controlBaseUrl: onboardTarget.controlBaseUrl,
+        agentBaseUrl: onboardTarget.agentBaseUrl,
+        uiUrl: onboardTarget.uiUrl,
         mcpName: onboardTarget.mcpName,
         targetKind: onboardTarget.kind,
         instanceName: onboardTarget.instanceName,
@@ -1215,6 +1276,9 @@ function buildPlannedFiles(
         version,
         port: onboardTarget.port,
         baseUrl: onboardTarget.baseUrl,
+        controlBaseUrl: onboardTarget.controlBaseUrl,
+        agentBaseUrl: onboardTarget.agentBaseUrl,
+        uiUrl: onboardTarget.uiUrl,
         mcpName: onboardTarget.mcpName,
         targetKind: onboardTarget.kind,
         instanceName: onboardTarget.instanceName,
@@ -1449,6 +1513,9 @@ function runOnboardSync(argv: readonly string[]): number {
   const resolvedTarget = resolveOnboardTarget({
     instanceName: flags.instanceName,
     baseUrl: flags.baseUrl,
+    controlBaseUrl: flags.controlBaseUrl,
+    agentBaseUrl: flags.agentBaseUrl,
+    uiUrl: flags.uiUrl,
     mcpName: flags.mcpName,
   });
   if (!resolvedTarget.ok) {

package/src/cli/onboardTarget.ts

@@ -1,9 +1,11 @@
 import { appendBasePathToOrigin, getConfiguredBasePath } from "../lib/basePath.js";
+import { normalizeBrowserRuntimeBaseUrl } from "../lib/browserRuntimeContract.js";
 import { getInstancesRoot, readInstanceRecord, validateInstanceName } from "./instanceRegistry.js";
 import { urlForHost } from "./networkHints.js";
 
 const DEFAULT_PORT = 9527;
 const DEFAULT_ORIGIN = `http://localhost:${String(DEFAULT_PORT)}`;
+const AGENT_INSPECTOR_PUBLIC_ORIGIN_ENV = "AGENT_INSPECTOR_PUBLIC_ORIGIN";
 const MCP_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u;
 
 type OnboardTargetEnv = Readonly<Record<string, string | undefined>>;
@@ -15,6 +17,10 @@ export type OnboardTarget = {
   instanceName: string | null;
   mcpName: string;
   port: number;
+  uiUrl: string | null;
+  controlBaseUrl: string;
+  agentBaseUrl: string;
+  /** @deprecated Compatibility alias for controlBaseUrl. */
   baseUrl: string;
   apiUrl: string;
   healthUrl: string;
@@ -26,6 +32,9 @@ export type OnboardTarget = {
 export type OnboardTargetOptions = {
   instanceName: string | null;
   baseUrl: string | null;
+  controlBaseUrl?: string | null;
+  agentBaseUrl?: string | null;
+  uiUrl?: string | null;
   mcpName: string | null;
 };
 
@@ -33,24 +42,29 @@ export type OnboardTargetResult =
   | { ok: true; target: OnboardTarget }
   | { ok: false; message: string };
 
-function targetFromBase(
+function targetFromSurfaces(
   kind: OnboardTargetKind,
   instanceName: string | null,
   mcpName: string,
   port: number,
-  baseUrl: string,
+  controlBaseUrl: string,
+  agentBaseUrl: string,
+  uiUrl: string | null,
 ): OnboardTarget {
   return {
     kind,
     instanceName,
     mcpName,
     port,
-    baseUrl,
-    apiUrl: `${baseUrl}/api`,
-    healthUrl: `${baseUrl}/api/health`,
-    anthropicProxyUrl: `${baseUrl}/proxy`,
-    openAiProxyUrl: `${baseUrl}/proxy/v1`,
-    mcpUrl: `${baseUrl}/api/mcp`,
+    uiUrl,
+    controlBaseUrl,
+    agentBaseUrl,
+    baseUrl: controlBaseUrl,
+    apiUrl: `${controlBaseUrl}/api`,
+    healthUrl: `${controlBaseUrl}/api/health`,
+    anthropicProxyUrl: `${agentBaseUrl}/proxy`,
+    openAiProxyUrl: `${agentBaseUrl}/proxy/v1`,
+    mcpUrl: `${agentBaseUrl}/api/mcp`,
   };
 }
 
@@ -60,31 +74,33 @@ function validateMcpName(rawName: string): string | null {
 }
 
 function normalizeExplicitBaseUrl(rawBaseUrl: string): { baseUrl: string; port: number } | null {
-  const candidate = rawBaseUrl.trim();
-  if (
-    candidate.length === 0 ||
-    candidate !== rawBaseUrl ||
-    candidate.includes("?") ||
-    candidate.includes("#")
-  ) {
+  const baseUrl = normalizeBrowserRuntimeBaseUrl(rawBaseUrl);
+  if (baseUrl === null) return null;
+  try {
+    const parsed = new URL(baseUrl);
+    const defaultPort = parsed.protocol === "https:" ? 443 : 80;
+    const port = parsed.port === "" ? defaultPort : Number(parsed.port);
+    return Number.isInteger(port) && port >= 1 && port <= 65_535 ? { baseUrl, port } : null;
+  } catch {
     return null;
   }
+}
 
+function normalizePublicOrigin(rawOrigin: string): string | null {
+  if (rawOrigin.trim() !== rawOrigin) return null;
   try {
-    const parsed = new URL(candidate);
+    const parsed = new URL(rawOrigin);
     if (
       (parsed.protocol !== "http:" && parsed.protocol !== "https:") ||
-      parsed.hostname.length === 0 ||
       parsed.username.length > 0 ||
-      parsed.password.length > 0
+      parsed.password.length > 0 ||
+      parsed.pathname !== "/" ||
+      parsed.search.length > 0 ||
+      parsed.hash.length > 0
     ) {
       return null;
     }
-    const pathname = parsed.pathname.replace(/\/+$/u, "");
-    const baseUrl = `${parsed.origin}${pathname === "" ? "" : pathname}`;
-    const defaultPort = parsed.protocol === "https:" ? 443 : 80;
-    const port = parsed.port === "" ? defaultPort : Number(parsed.port);
-    return Number.isInteger(port) && port >= 1 && port <= 65_535 ? { baseUrl, port } : null;
+    return parsed.origin;
   } catch {
     return null;
   }
@@ -94,10 +110,16 @@ export function resolveOnboardTarget(
   options: OnboardTargetOptions,
   env: OnboardTargetEnv = process.env,
 ): OnboardTargetResult {
-  if (options.instanceName !== null && options.baseUrl !== null) {
+  const hasExplicitSurface =
+    options.baseUrl !== null ||
+    (options.controlBaseUrl !== null && options.controlBaseUrl !== undefined) ||
+    (options.agentBaseUrl !== null && options.agentBaseUrl !== undefined) ||
+    options.uiUrl !== undefined;
+  if (options.instanceName !== null && hasExplicitSurface) {
     return {
       ok: false,
-      message: "--instance and --base-url are mutually exclusive",
+      message:
+        "--instance and explicit --base-url/--control-base-url/--agent-base-url/--ui-url options are mutually exclusive",
     };
   }
 
@@ -110,23 +132,39 @@ export function resolveOnboardTarget(
     };
   }
 
-  if (options.baseUrl !== null) {
-    const explicit = normalizeExplicitBaseUrl(options.baseUrl);
-    if (explicit === null) {
+  if (hasExplicitSurface) {
+    const sharedRaw = options.baseUrl;
+    const controlRaw = options.controlBaseUrl ?? sharedRaw ?? options.agentBaseUrl;
+    const agentRaw = options.agentBaseUrl ?? sharedRaw ?? options.controlBaseUrl;
+    const control =
+      controlRaw === null || controlRaw === undefined ? null : normalizeExplicitBaseUrl(controlRaw);
+    const agent =
+      agentRaw === null || agentRaw === undefined ? null : normalizeExplicitBaseUrl(agentRaw);
+    const ui =
+      options.uiUrl === undefined || options.uiUrl === null
+        ? null
+        : normalizeExplicitBaseUrl(options.uiUrl);
+    if (
+      control === null ||
+      agent === null ||
+      (options.uiUrl !== undefined && options.uiUrl !== null && ui === null)
+    ) {
       return {
         ok: false,
         message:
-          "--base-url must be a credential-free HTTP or HTTPS URL without a query or fragment",
+          "Explicit UI, control, and agent Base URLs must be credential-free HTTP(S) URLs without a query or fragment",
       };
     }
     return {
       ok: true,
-      target: targetFromBase(
+      target: targetFromSurfaces(
         "base-url",
         null,
         explicitMcpName ?? "agent-inspector",
-        explicit.port,
-        explicit.baseUrl,
+        control.port,
+        control.baseUrl,
+        agent.baseUrl,
+        ui?.baseUrl ?? null,
       ),
     };
   }
@@ -150,30 +188,41 @@ export function resolveOnboardTarget(
     const baseUrl = appendBasePathToOrigin(origin, "/", record.value.basePath);
     return {
       ok: true,
-      target: targetFromBase(
+      target: targetFromSurfaces(
         "instance",
         record.value.name,
         explicitMcpName ?? `agent-inspector-${record.value.name}`,
         record.value.publicPort,
         baseUrl,
+        baseUrl,
+        record.value.uiEnabled ? baseUrl : null,
       ),
     };
   }
 
-  const baseUrl = appendBasePathToOrigin(DEFAULT_ORIGIN, "/", getConfiguredBasePath(env));
+  const configuredPublicOrigin = env[AGENT_INSPECTOR_PUBLIC_ORIGIN_ENV];
+  const publicOrigin =
+    configuredPublicOrigin === undefined
+      ? DEFAULT_ORIGIN
+      : normalizePublicOrigin(configuredPublicOrigin);
+  if (publicOrigin === null) {
+    return {
+      ok: false,
+      message:
+        "AGENT_INSPECTOR_PUBLIC_ORIGIN must be an exact credential-free HTTP(S) origin without a path, query, or fragment",
+    };
+  }
+  const baseUrl = appendBasePathToOrigin(publicOrigin, "/", getConfiguredBasePath(env));
   return {
     ok: true,
-    target: targetFromBase(
+    target: targetFromSurfaces(
       "default",
       null,
       explicitMcpName ?? "agent-inspector",
       DEFAULT_PORT,
       baseUrl,
+      baseUrl,
+      env["AGENT_INSPECTOR_BACKEND_ONLY"] === "1" ? null : baseUrl,
     ),
   };
 }
-
-export const onboardTargetForTests = {
-  normalizeExplicitBaseUrl,
-  validateMcpName,
-};

package/src/cli/templates/codex-skill-onboard.ts

@@ -11,8 +11,14 @@ export type CodexSkillOnboardContext = {
   readonly version: string;
   /** The default proxy port (mirrors `DEFAULT_PORT` in `src/cli.ts`). */
   readonly port: number;
-  /** Public UI base URL, including the configured base path. */
+  /** Public backend control/agent Base URL, including the configured Base Path. */
   readonly baseUrl: string;
+  /** Optional composed or standalone UI URL. Undefined preserves the legacy composed default. */
+  readonly uiUrl?: string | null;
+  /** REST/SSE Base URL. Falls back to baseUrl for compatibility. */
+  readonly controlBaseUrl?: string;
+  /** Proxy/MCP Base URL. Falls back to baseUrl for compatibility. */
+  readonly agentBaseUrl?: string;
   /** MCP config key selected by onboarding. */
   readonly mcpName?: string;
   /** Selected onboarding target type. */
@@ -33,16 +39,20 @@ export const REQUIRED_CODEX_PHASE_HEADINGS = [
 ] as const;
 
 export function renderCodexSkillOnboard(ctx: CodexSkillOnboardContext): string {
-  const { version, baseUrl } = ctx;
+  const { version } = ctx;
+  const controlBaseUrl = ctx.controlBaseUrl ?? ctx.baseUrl;
+  const agentBaseUrl = ctx.agentBaseUrl ?? ctx.baseUrl;
+  const uiUrl = ctx.uiUrl === undefined ? ctx.baseUrl : ctx.uiUrl;
   const mcpName = ctx.mcpName ?? "agent-inspector";
   const targetKind = ctx.targetKind ?? "default";
   const targetArguments = ctx.onboardTargetArguments ?? "";
   const instanceName = ctx.instanceName ?? null;
-  const healthUrl = `${baseUrl}/api/health`;
-  const configUrl = `${baseUrl}/api/config`;
-  const anthropicProxyUrl = `${baseUrl}/proxy`;
-  const openAiProxyUrl = `${baseUrl}/proxy/v1`;
-  const mcpUrl = `${baseUrl}/api/mcp`;
+  const healthUrl = `${controlBaseUrl}/api/health`;
+  const runtimeUrl = `${controlBaseUrl}/api/runtime`;
+  const configUrl = `${controlBaseUrl}/api/config`;
+  const anthropicProxyUrl = `${agentBaseUrl}/proxy`;
+  const openAiProxyUrl = `${agentBaseUrl}/proxy/v1`;
+  const mcpUrl = `${agentBaseUrl}/api/mcp`;
   const mcpTomlKey = /^[A-Za-z0-9_-]+$/u.test(mcpName) ? mcpName : JSON.stringify(mcpName);
   const statusCommand = `agent-inspector onboard --status${targetArguments}`;
   const refreshCommand = `agent-inspector onboard --force${targetArguments}`;
@@ -50,7 +60,7 @@ export function renderCodexSkillOnboard(ctx: CodexSkillOnboardContext): string {
     targetKind === "instance" && instanceName !== null
       ? `agent-inspector instance start ${instanceName}`
       : targetKind === "base-url"
-        ? `# Explicit target ${baseUrl}: do not start a replacement local runtime.`
+        ? `# Explicit control target ${controlBaseUrl}: do not start a replacement local runtime.`
         : "agent-inspector --mode simple --background --no-open";
   const fullModeCommand =
     targetKind === "instance" && instanceName !== null
@@ -60,8 +70,14 @@ export function renderCodexSkillOnboard(ctx: CodexSkillOnboardContext): string {
         : "agent-inspector --mode full --force-restart";
   const startExplanation =
     targetKind === "base-url"
-      ? `The selected Inspector target is the explicit Base URL \`${baseUrl}\`. Do not start the default local runtime as a substitute; verify the selected target and ask its operator for help if it is unavailable.`
-      : `Start or reuse the selected Agent Inspector runtime before wiring MCP. Prefer the installed binary so Windows users get the branded runtime in Task Manager. Use \`${fullModeCommand}\` only when the user needs raw headers, raw response, or SSE chunks.`;
+      ? `The selected Inspector target uses control Base URL \`${controlBaseUrl}\` and agent Base URL \`${agentBaseUrl}\`. Do not start the default local runtime as a substitute; verify the selected target and ask its operator for help if it is unavailable.`
+      : `Start or reuse the selected Agent Inspector backend before wiring MCP. The default command composes a UI, while backend-only named instances retain proxy, REST, health, and MCP without UI files. Prefer the installed binary so Windows users get the branded runtime in Task Manager. Use \`${fullModeCommand}\` only when the user needs raw headers, raw response, or SSE chunks.`;
+  const selectedUi =
+    uiUrl === null ? "not supplied (do not infer one from a backend URL)" : `\`${uiUrl}\``;
+  const providerTestUiGuidance =
+    uiUrl === null
+      ? `No UI URL was supplied. Do not open \`${controlBaseUrl}\` or \`${agentBaseUrl}\` as a page; use the MCP Provider Test tools and log/session resources, or ask the operator for a standalone UI URL.`
+      : `The operator supplied the explicit composed or standalone UI URL \`${uiUrl}\`. Use that URL for browser steps; do not substitute the control or agent Base URL.`;
   return `---
 name: agent-inspector-onboard
 description: Guide Codex users through connecting Agent Inspector v${version} as a local MCP server.
@@ -74,7 +90,13 @@ metadata:
 
 Use this skill when the user wants to set up Agent Inspector inside Codex, connect the Agent Inspector MCP server, inspect captured model traffic from Codex, or turn Inspector sessions into reviewable knowledge candidates.
 
-Agent Inspector runs a local web UI, proxy, REST API, and MCP endpoint on the same port. The default MCP endpoint is:
+The selected deployment has these explicit surfaces:
+
+- UI URL: ${selectedUi}
+- Control Base URL: \`${controlBaseUrl}\`
+- Agent Base URL: \`${agentBaseUrl}\`
+
+Composed mode may use one URL for all three, but backend-only mode and separately hosted UI deployments do not require UI and backend to share a process, origin, or port. The selected MCP endpoint is:
 
 \`\`\`text
 ${mcpUrl}
@@ -92,6 +114,8 @@ Do not configure both transports in the same MCP client, or the client may show
 
 Keep this setup local and explicit. Agent Inspector MCP tools can read captured requests and provider configuration, so only wire it into trusted local Codex environments.
 
+The backend publishes token-free runtime discovery at \`${runtimeUrl}\`. Treat \`backend-only\` as healthy when REST, proxy, and MCP capabilities are present.
+
 Agent Inspector starts in **Simple mode** by default. Keep Simple mode for everyday capture: requests, responses, tools, timing, and token usage stay available without retaining heavier raw headers, raw response, or detailed SSE chunk artifacts. Use **Full mode** only when the user is debugging provider headers, raw response payloads, or SSE stream details.
 
 ---
@@ -134,12 +158,14 @@ ${startExplanation}
 \`\`\`powershell
 ${startCommand}
 Invoke-RestMethod -Uri "${healthUrl}" -TimeoutSec 3
+Invoke-RestMethod -Uri "${runtimeUrl}" -TimeoutSec 3 | Select-Object deploymentMode, capabilities
 Invoke-RestMethod -Uri "${configUrl}" -TimeoutSec 3 | Select-Object captureMode
 \`\`\`
 
 \`\`\`bash
 ${startCommand}
 curl -fsS "${healthUrl}"
+curl -fsS "${runtimeUrl}"
 curl -fsS "${configUrl}" | grep -o '"captureMode":"[^"]*"'
 \`\`\`
 
@@ -183,7 +209,7 @@ When editing:
 - Keep existing \`mcp_servers.*\`, \`projects.*\`, profiles, sandbox, approval, and model settings intact.
 - Remove any duplicate Inspector MCP entry that points to the same \`/api/mcp\` endpoint or runs the same \`agent-inspector-mcp stdio\` bridge under another name.
 - Do not write provider API keys into Codex config.
-- Do not expose Agent Inspector MCP beyond localhost.
+- Do not expose a raw Inspector listener to untrusted networks. For remote use, require the operator's authenticated same-origin gateway and keep control credentials in environment variables rather than generated config.
 
 ---
 
@@ -264,14 +290,18 @@ Inspector, \`localhost\` points at the tool's own environment. Replace \`localho
 address reachable from that environment, then verify the network/firewall path before debugging
 provider credentials.
 
-For a Provider Test memory probe, run a provider test in the Agent Inspector UI:
+For a Provider Test memory probe, first read \`${runtimeUrl}\`. ${providerTestUiGuidance}
 
-1. Open \`${baseUrl}\`.
+When an explicit UI URL is available:
+
+1. Open the supplied UI URL.
 2. Go to Settings -> Providers.
 3. Add or edit a Provider.
 4. Run Test.
 5. Check the \`provider-test\` session.
 
+If discovery reports \`backend-only\`, do not fail onboarding. A separately hosted UI may still exist only when its URL was explicitly supplied; otherwise use the MCP Provider Test tools and log/session resources. Proxy, REST, health, and MCP remain fully usable without UI files.
+
 Then ask Codex:
 
 \`\`\`text