@tonyclaw/agent-inspector 3.0.44 → 3.0.46

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

@@ -26,6 +26,7 @@ import { fileURLToPath } from "node:url";
 
 import { appendBasePathToOrigin, getConfiguredBasePath } from "../lib/basePath.js";
 import { detectAll, detectFirst } from "./detect-tools.js";
+import { type OnboardTarget, resolveOnboardTarget } from "./onboardTarget.js";
 import { renderCommandOnboard } from "./templates/command-onboard.js";
 import {
   renderCodexSkillOnboard,
@@ -38,7 +39,11 @@ const __dirname = dirname(__filename);
 
 const DEFAULT_PORT = 9527;
 const DEFAULT_ORIGIN = `http://localhost:${DEFAULT_PORT}`;
-const DEFAULT_MCP_URL = `${DEFAULT_ORIGIN}/api/mcp`;
+const DEFAULT_MCP_URL = appendBasePathToOrigin(
+  DEFAULT_ORIGIN,
+  "/api/mcp",
+  getConfiguredBasePath({}),
+);
 const LEGACY_MCP_URL = "http://localhost:9527/api/mcp";
 const SKILL_DIR_NAME = "agent-inspector-onboard";
 const SKILL_FILE_NAME = "SKILL.md";
@@ -65,12 +70,18 @@ export type OnboardFlags = {
   opencodeOnly: boolean;
   opencodeConfig: string | null;
   opencodeTransport: AgentMcpTransport;
-  opencodeMcpUrl: string;
+  opencodeMcpUrl: string | null;
   mimo: boolean;
   mimoOnly: boolean;
   mimoConfig: string | null;
   mimoTransport: AgentMcpTransport;
-  mimoMcpUrl: string;
+  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;
   json: boolean;
@@ -88,6 +99,7 @@ type AgentMcpConfigTarget = {
   configPath: string;
   transport: AgentMcpTransport;
   endpoint: string;
+  mcpName: string;
   setupAction: string;
   forceAction: string;
   verifyCommand: string;
@@ -102,6 +114,7 @@ type AgentMcpConfigStatus = {
   state: AgentMcpConfigState;
   transport: AgentMcpStatusTransport;
   endpoint: string;
+  mcpName: string;
   action: string;
   forceAction: string;
   verifyCommand: string;
@@ -183,11 +196,6 @@ function actionForStatus(label: string, state: GeneratedFileState): string {
 }
 
 function parseFlags(argv: readonly string[]): OnboardFlags {
-  const defaultMcpUrl = appendBasePathToOrigin(
-    DEFAULT_ORIGIN,
-    "/api/mcp",
-    getConfiguredBasePath(process.env),
-  );
   const flags: OnboardFlags = {
     force: false,
     dryRun: false,
@@ -199,12 +207,18 @@ function parseFlags(argv: readonly string[]): OnboardFlags {
     opencodeOnly: false,
     opencodeConfig: null,
     opencodeTransport: "local",
-    opencodeMcpUrl: defaultMcpUrl,
+    opencodeMcpUrl: null,
     mimo: false,
     mimoOnly: false,
     mimoConfig: null,
     mimoTransport: "local",
-    mimoMcpUrl: defaultMcpUrl,
+    mimoMcpUrl: null,
+    instanceName: null,
+    baseUrl: null,
+    controlBaseUrl: null,
+    agentBaseUrl: null,
+    uiUrl: undefined,
+    mcpName: null,
     uninstall: false,
     status: false,
     json: false,
@@ -332,6 +346,69 @@ function parseFlags(argv: readonly string[]): OnboardFlags {
         i++;
         break;
       }
+      case "--instance": {
+        const next = argv[i + 1];
+        if (next === undefined || next.trim().length === 0) {
+          process.stderr.write("agent-inspector onboard: --instance requires a name\n");
+          process.exit(2);
+        }
+        flags.instanceName = next;
+        i++;
+        break;
+      }
+      case "--base-url": {
+        const next = argv[i + 1];
+        if (next === undefined || next.trim().length === 0) {
+          process.stderr.write("agent-inspector onboard: --base-url requires a URL\n");
+          process.exit(2);
+        }
+        flags.baseUrl = next;
+        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) {
+          process.stderr.write("agent-inspector onboard: --mcp-name requires a name\n");
+          process.exit(2);
+        }
+        flags.mcpName = next;
+        i++;
+        break;
+      }
       case "--uninstall":
         flags.uninstall = true;
         break;
@@ -401,6 +478,13 @@ Options:
   --mimo-transport <local|remote>
                            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 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
   --json                   Emit machine-readable JSON with --status
@@ -487,34 +571,64 @@ function resolveMiMoConfigPath(flags: OnboardFlags): string {
   return jsoncPath;
 }
 
-function openCodeTarget(flags: OnboardFlags): AgentMcpConfigTarget {
+function onboardSelectionArguments(flags: OnboardFlags, target: OnboardTarget): string {
+  const args: string[] = [];
+  if (target.kind === "instance" && target.instanceName !== null) {
+    args.push("--instance", target.instanceName);
+  } else if (target.kind === "base-url") {
+    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(" ")}`;
+}
+
+function openCodeTarget(flags: OnboardFlags, onboardTarget: OnboardTarget): AgentMcpConfigTarget {
+  const setupAction = `agent-inspector onboard --opencode-only${onboardSelectionArguments(flags, onboardTarget)}`;
   return {
     label: "OpenCode",
     configLabel: "OpenCode MCP config",
     configPath: resolveOpenCodeConfigPath(flags),
     transport: flags.opencodeTransport,
-    endpoint: flags.opencodeMcpUrl,
-    setupAction: "agent-inspector onboard --opencode-only",
-    forceAction: "agent-inspector onboard --opencode-only --force",
+    endpoint: flags.opencodeMcpUrl ?? onboardTarget.mcpUrl,
+    mcpName: onboardTarget.mcpName,
+    setupAction,
+    forceAction: `${setupAction} --force`,
     verifyCommand: "opencode mcp list",
-    invalidAction: "fix OpenCode JSON/JSONC, then rerun agent-inspector onboard --opencode-only",
-    configObjectName: "mcp.agent-inspector",
+    invalidAction: `fix OpenCode JSON/JSONC, then rerun ${setupAction}`,
+    configObjectName: `mcp.${onboardTarget.mcpName}`,
     defaultSchema: "https://opencode.ai/config.json",
   };
 }
 
-function miMoTarget(flags: OnboardFlags): AgentMcpConfigTarget {
+function miMoTarget(flags: OnboardFlags, onboardTarget: OnboardTarget): AgentMcpConfigTarget {
+  const setupAction = `agent-inspector onboard --mimo-only${onboardSelectionArguments(flags, onboardTarget)}`;
   return {
     label: "MiMo Code",
     configLabel: "MiMo Code MCP config",
     configPath: resolveMiMoConfigPath(flags),
     transport: flags.mimoTransport,
-    endpoint: flags.mimoMcpUrl,
-    setupAction: "agent-inspector onboard --mimo-only",
-    forceAction: "agent-inspector onboard --mimo-only --force",
+    endpoint: flags.mimoMcpUrl ?? onboardTarget.mcpUrl,
+    mcpName: onboardTarget.mcpName,
+    setupAction,
+    forceAction: `${setupAction} --force`,
     verifyCommand: "mimo mcp list",
-    invalidAction: "fix MiMo Code JSON/JSONC, then rerun agent-inspector onboard --mimo-only",
-    configObjectName: "mcp.agent-inspector",
+    invalidAction: `fix MiMo Code JSON/JSONC, then rerun ${setupAction}`,
+    configObjectName: `mcp.${onboardTarget.mcpName}`,
     defaultSchema: "https://mimo.xiaomi.com/mimocode/config.json",
   };
 }
@@ -731,6 +845,7 @@ function makeAgentStatus(
     state,
     transport,
     endpoint: target.endpoint,
+    mcpName: target.mcpName,
     action: target.setupAction,
     forceAction: target.forceAction,
     verifyCommand: target.verifyCommand,
@@ -743,12 +858,12 @@ function makeAgentStatus(
   };
 }
 
-function getAgentEntry(config: Record<string, unknown>): unknown {
+function getAgentEntry(config: Record<string, unknown>, mcpName: string): unknown {
   const mcp = config["mcp"];
   if (!isObject(mcp)) {
     return undefined;
   }
-  return mcp["agent-inspector"];
+  return mcp[mcpName];
 }
 
 function buildAgentConfig(
@@ -768,7 +883,7 @@ function buildAgentConfig(
 
   const currentMcp = config["mcp"];
   const nextMcp: Record<string, unknown> = isObject(currentMcp) ? { ...currentMcp } : {};
-  nextMcp["agent-inspector"] = buildAgentMcpEntry(target.transport, target.endpoint);
+  nextMcp[target.mcpName] = buildAgentMcpEntry(target.transport, target.endpoint);
   nextConfig["mcp"] = nextMcp;
   return nextConfig;
 }
@@ -777,7 +892,10 @@ function formatAgentConfig(config: Record<string, unknown>): string {
   return `${JSON.stringify(config, null, 2)}\n`;
 }
 
-function removeAgentEntry(config: Record<string, unknown>): Record<string, unknown> {
+function removeAgentEntry(
+  config: Record<string, unknown>,
+  mcpName: string,
+): Record<string, unknown> {
   const nextConfig: Record<string, unknown> = {};
   for (const [key, value] of Object.entries(config)) {
     if (key !== "mcp") {
@@ -792,7 +910,7 @@ function removeAgentEntry(config: Record<string, unknown>): Record<string, unkno
 
   const nextMcp: Record<string, unknown> = {};
   for (const [key, value] of Object.entries(currentMcp)) {
-    if (key !== "agent-inspector") {
+    if (key !== mcpName) {
       nextMcp[key] = value;
     }
   }
@@ -809,7 +927,7 @@ function readAgentStatus(target: AgentMcpConfigTarget): AgentMcpConfigStatus {
     return makeAgentStatus(target, "invalid", "unknown", read.message);
   }
 
-  const entry = getAgentEntry(read.config);
+  const entry = getAgentEntry(read.config, target.mcpName);
   if (entry === undefined) {
     const detail = read.exists
       ? `${target.label} config has no ${target.configObjectName}`
@@ -861,12 +979,14 @@ function buildAgentPlan(
   }
 
   const status = readAgentStatus(target);
-  const entry = getAgentEntry(read.config);
+  const entry = getAgentEntry(read.config, target.mcpName);
   const nextBody = formatAgentConfig(buildAgentConfig(read.config, target));
 
   if (uninstall) {
     const shouldRemove = entry !== undefined && isKnownAgentEntry(entry, target.endpoint, true);
-    const removeBody = shouldRemove ? formatAgentConfig(removeAgentEntry(read.config)) : null;
+    const removeBody = shouldRemove
+      ? formatAgentConfig(removeAgentEntry(read.config, target.mcpName))
+      : null;
     return {
       status,
       body: removeBody,
@@ -1129,14 +1249,24 @@ function buildPlannedFiles(
   flags: OnboardFlags,
   targets: OnboardTargets,
   version: string,
+  onboardTarget: OnboardTarget,
 ): PlannedFile[] {
   const installClaude = !flags.codexOnly && !hasOnlyAgentMcpTarget(flags);
   const installCodex = !flags.skipCodexSkill && !hasOnlyAgentMcpTarget(flags);
   const detectedSummary = installClaude ? buildDetectedSummary() : "";
+  const targetArguments = onboardSelectionArguments(flags, onboardTarget);
   const claudeSkillBody = installClaude
     ? renderSkillOnboard({
         version,
-        port: DEFAULT_PORT,
+        port: onboardTarget.port,
+        baseUrl: onboardTarget.baseUrl,
+        controlBaseUrl: onboardTarget.controlBaseUrl,
+        agentBaseUrl: onboardTarget.agentBaseUrl,
+        uiUrl: onboardTarget.uiUrl,
+        mcpName: onboardTarget.mcpName,
+        targetKind: onboardTarget.kind,
+        instanceName: onboardTarget.instanceName,
+        onboardTargetArguments: targetArguments,
         detectedSummary,
       })
     : "";
@@ -1144,7 +1274,15 @@ function buildPlannedFiles(
   const codexSkillBody = installCodex
     ? renderCodexSkillOnboard({
         version,
-        port: DEFAULT_PORT,
+        port: onboardTarget.port,
+        baseUrl: onboardTarget.baseUrl,
+        controlBaseUrl: onboardTarget.controlBaseUrl,
+        agentBaseUrl: onboardTarget.agentBaseUrl,
+        uiUrl: onboardTarget.uiUrl,
+        mcpName: onboardTarget.mcpName,
+        targetKind: onboardTarget.kind,
+        instanceName: onboardTarget.instanceName,
+        onboardTargetArguments: targetArguments,
       })
     : "";
 
@@ -1348,6 +1486,7 @@ function runStatus(
     process.stdout.write(`${agentStatus.label}: ${agentStatus.state}`);
     process.stdout.write(`, transport ${agentStatus.transport}\n`);
     process.stdout.write(`  ${agentStatus.path}\n`);
+    process.stdout.write(`  MCP key: ${agentStatus.mcpName}\n`);
     process.stdout.write(`  Endpoint: ${agentStatus.endpoint}\n`);
     process.stdout.write(`  Detail: ${agentStatus.detail}\n`);
     process.stdout.write(`  Action: ${agentStatus.action}\n`);
@@ -1371,16 +1510,31 @@ export function runOnboard(argv: readonly string[]): Promise<number> {
 
 function runOnboardSync(argv: readonly string[]): number {
   const flags = parseFlags(argv);
+  const resolvedTarget = resolveOnboardTarget({
+    instanceName: flags.instanceName,
+    baseUrl: flags.baseUrl,
+    controlBaseUrl: flags.controlBaseUrl,
+    agentBaseUrl: flags.agentBaseUrl,
+    uiUrl: flags.uiUrl,
+    mcpName: flags.mcpName,
+  });
+  if (!resolvedTarget.ok) {
+    process.stderr.write(`agent-inspector onboard: ${resolvedTarget.message}\n`);
+    return 2;
+  }
+  const onboardTarget = resolvedTarget.target;
   const targets = resolveTargets(flags);
   const version = readPackageVersion();
-  const plannedFiles = buildPlannedFiles(flags, targets, version);
+  const plannedFiles = buildPlannedFiles(flags, targets, version, onboardTarget);
   const enabledFiles = plannedFiles.filter((file) => file.enabled);
   const agentPlans: AgentMcpConfigPlan[] = [];
   if (isOpenCodeEnabled(flags)) {
-    agentPlans.push(buildAgentPlan(openCodeTarget(flags), flags.uninstall, flags.force));
+    agentPlans.push(
+      buildAgentPlan(openCodeTarget(flags, onboardTarget), flags.uninstall, flags.force),
+    );
   }
   if (isMiMoEnabled(flags)) {
-    agentPlans.push(buildAgentPlan(miMoTarget(flags), flags.uninstall, flags.force));
+    agentPlans.push(buildAgentPlan(miMoTarget(flags, onboardTarget), flags.uninstall, flags.force));
   }
   const agentStatuses = agentPlans.map((plan) => plan.status);
 
@@ -1411,6 +1565,7 @@ function runOnboardSync(argv: readonly string[]): number {
     for (const plan of agentPlans) {
       process.stdout.write(`${plan.status.label}: ${plan.status.path} (${plan.status.state})\n`);
       process.stdout.write(`  Transport: ${plan.status.transport}\n`);
+      process.stdout.write(`  MCP key: ${plan.status.mcpName}\n`);
       process.stdout.write(`  Endpoint: ${plan.status.endpoint}\n`);
       process.stdout.write(`  Action: ${plan.status.action}\n`);
       if (plan.blockedMessage !== null) {