@tonyclaw/agent-inspector 3.0.44 → 3.0.46

package/src/cli/onboardTarget.ts

@@ -0,0 +1,228 @@
+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>>;
+
+export type OnboardTargetKind = "default" | "instance" | "base-url";
+
+export type OnboardTarget = {
+  kind: OnboardTargetKind;
+  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;
+  anthropicProxyUrl: string;
+  openAiProxyUrl: string;
+  mcpUrl: string;
+};
+
+export type OnboardTargetOptions = {
+  instanceName: string | null;
+  baseUrl: string | null;
+  controlBaseUrl?: string | null;
+  agentBaseUrl?: string | null;
+  uiUrl?: string | null;
+  mcpName: string | null;
+};
+
+export type OnboardTargetResult =
+  | { ok: true; target: OnboardTarget }
+  | { ok: false; message: string };
+
+function targetFromSurfaces(
+  kind: OnboardTargetKind,
+  instanceName: string | null,
+  mcpName: string,
+  port: number,
+  controlBaseUrl: string,
+  agentBaseUrl: string,
+  uiUrl: string | null,
+): OnboardTarget {
+  return {
+    kind,
+    instanceName,
+    mcpName,
+    port,
+    uiUrl,
+    controlBaseUrl,
+    agentBaseUrl,
+    baseUrl: controlBaseUrl,
+    apiUrl: `${controlBaseUrl}/api`,
+    healthUrl: `${controlBaseUrl}/api/health`,
+    anthropicProxyUrl: `${agentBaseUrl}/proxy`,
+    openAiProxyUrl: `${agentBaseUrl}/proxy/v1`,
+    mcpUrl: `${agentBaseUrl}/api/mcp`,
+  };
+}
+
+function validateMcpName(rawName: string): string | null {
+  const name = rawName.trim();
+  return name === rawName && MCP_NAME_PATTERN.test(name) ? name : null;
+}
+
+function normalizeExplicitBaseUrl(rawBaseUrl: string): { baseUrl: string; port: number } | null {
+  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(rawOrigin);
+    if (
+      (parsed.protocol !== "http:" && parsed.protocol !== "https:") ||
+      parsed.username.length > 0 ||
+      parsed.password.length > 0 ||
+      parsed.pathname !== "/" ||
+      parsed.search.length > 0 ||
+      parsed.hash.length > 0
+    ) {
+      return null;
+    }
+    return parsed.origin;
+  } catch {
+    return null;
+  }
+}
+
+export function resolveOnboardTarget(
+  options: OnboardTargetOptions,
+  env: OnboardTargetEnv = process.env,
+): OnboardTargetResult {
+  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 explicit --base-url/--control-base-url/--agent-base-url/--ui-url options are mutually exclusive",
+    };
+  }
+
+  const explicitMcpName = options.mcpName === null ? null : validateMcpName(options.mcpName);
+  if (options.mcpName !== null && explicitMcpName === null) {
+    return {
+      ok: false,
+      message:
+        "--mcp-name must be 1-128 letters, digits, dots, hyphens, or underscores and start with a letter or digit",
+    };
+  }
+
+  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:
+          "Explicit UI, control, and agent Base URLs must be credential-free HTTP(S) URLs without a query or fragment",
+      };
+    }
+    return {
+      ok: true,
+      target: targetFromSurfaces(
+        "base-url",
+        null,
+        explicitMcpName ?? "agent-inspector",
+        control.port,
+        control.baseUrl,
+        agent.baseUrl,
+        ui?.baseUrl ?? null,
+      ),
+    };
+  }
+
+  if (options.instanceName !== null) {
+    const validatedName = validateInstanceName(options.instanceName);
+    if (validatedName.kind === "error") {
+      return { ok: false, message: validatedName.error.message };
+    }
+    const record = readInstanceRecord(getInstancesRoot(env), validatedName.value);
+    if (record.kind === "error") {
+      return { ok: false, message: record.error.message };
+    }
+    if (record.value === null) {
+      return {
+        ok: false,
+        message: `Named instance ${validatedName.value} does not exist`,
+      };
+    }
+    const origin = urlForHost(record.value.publicPort, record.value.host);
+    const baseUrl = appendBasePathToOrigin(origin, "/", record.value.basePath);
+    return {
+      ok: true,
+      target: targetFromSurfaces(
+        "instance",
+        record.value.name,
+        explicitMcpName ?? `agent-inspector-${record.value.name}`,
+        record.value.publicPort,
+        baseUrl,
+        baseUrl,
+        record.value.uiEnabled ? baseUrl : null,
+      ),
+    };
+  }
+
+  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: targetFromSurfaces(
+      "default",
+      null,
+      explicitMcpName ?? "agent-inspector",
+      DEFAULT_PORT,
+      baseUrl,
+      baseUrl,
+      env["AGENT_INSPECTOR_BACKEND_ONLY"] === "1" ? null : baseUrl,
+    ),
+  };
+}

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

@@ -11,6 +11,22 @@ export type CodexSkillOnboardContext = {
   readonly version: string;
   /** The default proxy port (mirrors `DEFAULT_PORT` in `src/cli.ts`). */
   readonly port: number;
+  /** 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. */
+  readonly targetKind?: "default" | "instance" | "base-url";
+  /** Normalized registry name for a named target. */
+  readonly instanceName?: string | null;
+  /** CLI arguments that reproduce the selected target. */
+  readonly onboardTargetArguments?: string;
 };
 
 export const REQUIRED_CODEX_PHASE_HEADINGS = [
@@ -23,7 +39,45 @@ export const REQUIRED_CODEX_PHASE_HEADINGS = [
 ] as const;
 
 export function renderCodexSkillOnboard(ctx: CodexSkillOnboardContext): string {
-  const { version, port } = 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 = `${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}`;
+  const startCommand =
+    targetKind === "instance" && instanceName !== null
+      ? `agent-inspector instance start ${instanceName}`
+      : targetKind === "base-url"
+        ? `# Explicit control target ${controlBaseUrl}: do not start a replacement local runtime.`
+        : "agent-inspector --mode simple --background --no-open";
+  const fullModeCommand =
+    targetKind === "instance" && instanceName !== null
+      ? `agent-inspector instance restart ${instanceName} --mode full`
+      : targetKind === "base-url"
+        ? "ask the target operator to enable Full capture mode"
+        : "agent-inspector --mode full --force-restart";
+  const startExplanation =
+    targetKind === "base-url"
+      ? `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.
@@ -36,10 +90,16 @@ 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
-http://localhost:${port}/api/mcp
+${mcpUrl}
 \`\`\`
 
 This skill is installed at \`~/.codex/skills/agent-inspector-onboard/SKILL.md\`.
@@ -47,13 +107,15 @@ Codex user-level configuration lives in \`~/.codex/config.toml\`. Codex supports
 
 Use exactly one MCP transport for the same Inspector instance:
 
-- Streamable HTTP MCP: configure \`url = "http://localhost:${port}/api/mcp"\`.
-- Stdio-only MCP clients: configure \`agent-inspector-mcp stdio --url http://localhost:${port}/api/mcp\`.
+- Streamable HTTP MCP: configure \`url = "${mcpUrl}"\`.
+- Stdio-only MCP clients: configure \`agent-inspector-mcp stdio --url ${mcpUrl}\`.
 
 Do not configure both transports in the same MCP client, or the client may show duplicate Inspector tools.
 
 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.
 
 ---
@@ -64,14 +126,14 @@ Check that the package and Codex home exist without printing secrets.
 
 \`\`\`powershell
 Get-Command agent-inspector -ErrorAction SilentlyContinue | Select-Object -ExpandProperty Source
-agent-inspector onboard --status
+${statusCommand}
 Test-Path (Join-Path $env:USERPROFILE ".codex")
 Test-Path (Join-Path $env:USERPROFILE ".codex\\config.toml")
 \`\`\`
 
 \`\`\`bash
 node -e "const fs=require('node:fs'),p=require('node:path');const names=process.platform==='win32'?['agent-inspector.cmd','agent-inspector.exe','agent-inspector']:['agent-inspector'];const found=(process.env.PATH||'').split(p.delimiter).some(d=>names.some(n=>fs.existsSync(p.join(d,n))));console.log(found?'agent-inspector: present':'agent-inspector: missing')"
-agent-inspector onboard --status
+${statusCommand}
 test -d "$HOME/.codex" && echo "codex home: present" || echo "codex home: missing"
 test -f "$HOME/.codex/config.toml" && echo "config: present" || echo "config: missing"
 \`\`\`
@@ -82,8 +144,8 @@ If \`agent-inspector\` is missing, ask the user to install it first:
 npm install -g @tonyclaw/agent-inspector
 \`\`\`
 
-If \`agent-inspector onboard --status\` reports \`outdated\` or \`missing\`, ask the user to run
-\`agent-inspector onboard --force\` and restart this skill before continuing.
+If \`${statusCommand}\` reports \`outdated\` or \`missing\`, ask the user to run
+\`${refreshCommand}\` and restart this skill before continuing.
 
 Do not read \`~/.codex/auth.json\`, token files, or unrelated Codex state files.
 
@@ -91,33 +153,35 @@ Do not read \`~/.codex/auth.json\`, token files, or unrelated Codex state files.
 
 ## Phase 1: Start Agent Inspector
 
-Start or reuse Agent Inspector before wiring MCP. Prefer the installed binary so Windows users get the branded runtime in Task Manager. Start onboarding in Simple mode; if the user needs raw headers, raw response, or SSE chunks later, restart with \`agent-inspector --mode full\`.
+${startExplanation}
 
 \`\`\`powershell
-agent-inspector --mode simple --background --no-open
-Invoke-RestMethod -Uri "http://localhost:${port}/api/health" -TimeoutSec 3
-Invoke-RestMethod -Uri "http://localhost:${port}/api/config" -TimeoutSec 3 | Select-Object captureMode
+${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
-agent-inspector --mode simple --background --no-open
-curl -fsS "http://localhost:${port}/api/health"
-curl -fsS "http://localhost:${port}/api/config" | grep -o '"captureMode":"[^"]*"'
+${startCommand}
+curl -fsS "${healthUrl}"
+curl -fsS "${runtimeUrl}"
+curl -fsS "${configUrl}" | grep -o '"captureMode":"[^"]*"'
 \`\`\`
 
-If the health check fails, show only the relevant error and ask whether to diagnose startup before editing Codex config. If the active capture mode is not \`simple\`, explain that an existing process is already running and offer to restart with \`agent-inspector --mode simple --force-restart\`.
+If the health check fails, show only the relevant error and ask whether to diagnose the selected target before editing Codex config. If deeper capture is required, offer \`${fullModeCommand}\`.
 
 ---
 
 ## Phase 2: Wire Codex MCP
 
-Add an \`agent-inspector\` MCP server to \`~/.codex/config.toml\`. Preserve the user's existing config and merge the table instead of replacing the file.
+Add the \`${mcpName}\` MCP server to \`~/.codex/config.toml\`. Preserve the user's existing config and merge the table instead of replacing the file.
 
 Recommended user-level config for Codex builds that support Streamable HTTP MCP:
 
 \`\`\`toml
-[mcp_servers.agent-inspector]
-url = "http://localhost:${port}/api/mcp"
+[mcp_servers.${mcpTomlKey}]
+url = "${mcpUrl}"
 startup_timeout_sec = 30
 tool_timeout_sec = 60
 \`\`\`
@@ -125,9 +189,9 @@ tool_timeout_sec = 60
 Fallback config for a stdio-only MCP client:
 
 \`\`\`toml
-[mcp_servers.agent-inspector]
+[mcp_servers.${mcpTomlKey}]
 command = "agent-inspector-mcp"
-args = ["stdio", "--url", "http://localhost:${port}/api/mcp"]
+args = ["stdio", "--url", "${mcpUrl}"]
 \`\`\`
 
 The stdio command is only a bridge to the same HTTP MCP endpoint. It does not start a second Inspector server.
@@ -135,8 +199,8 @@ The stdio command is only a bridge to the same HTTP MCP endpoint. It does not st
 If the user's Codex environment is managed by an admin allowlist, they may also need a matching identity rule in the managed requirements layer:
 
 \`\`\`toml
-[mcp_servers.agent-inspector.identity]
-url = "http://localhost:${port}/api/mcp"
+[mcp_servers.${mcpTomlKey}.identity]
+url = "${mcpUrl}"
 \`\`\`
 
 When editing:
@@ -145,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.
 
 ---
 
@@ -156,7 +220,7 @@ Tell the user that Codex loads MCP servers at session startup. After saving \`co
 Before restart, verify the HTTP endpoint itself:
 
 \`\`\`bash
-curl -sS -X POST "http://localhost:${port}/api/mcp" \\
+curl -sS -X POST "${mcpUrl}" \\
   -H "Content-Type: application/json" \\
   -H "Accept: application/json, text/event-stream" \\
   -d '{
@@ -203,27 +267,41 @@ Provider mutation tools expose and modify local provider configuration. Ask for
 
 ## Phase 5: Capture and memory review
 
-To capture Codex traffic through Agent Inspector, route a model client through:
+To capture traffic through Agent Inspector, use the protocol-correct base URL:
 
 \`\`\`text
-http://localhost:${port}/proxy
+Anthropic: ${anthropicProxyUrl}
+OpenAI Responses / Codex: ${openAiProxyUrl}
 \`\`\`
 
-For Anthropic-compatible tools, set \`ANTHROPIC_BASE_URL=http://localhost:${port}/proxy\`. For OpenAI-compatible tools, set \`OPENAI_BASE_URL=http://localhost:${port}/proxy\`.
+For Anthropic-compatible tools, set \`ANTHROPIC_BASE_URL=${anthropicProxyUrl}\`. For OpenAI-compatible tools and Codex Responses providers, set \`OPENAI_BASE_URL=${openAiProxyUrl}\`.
+
+Example Codex Responses provider snippet:
+
+\`\`\`toml
+[model_providers.agent-inspector]
+name = "Agent Inspector"
+base_url = "${openAiProxyUrl}"
+wire_api = "responses"
+\`\`\`
 
 If Codex or another AI tool runs in a different container, VM, WSL distro, or host than Agent
 Inspector, \`localhost\` points at the tool's own environment. Replace \`localhost\` with an Inspector
 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 \`http://localhost:${port}\`.
+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