@tonyclaw/agent-inspector 3.0.45 → 3.0.47

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,
-};