@tonyclaw/agent-inspector 3.0.44 → 3.0.45

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,15 @@ 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;
+  mcpName: string | null;
   uninstall: boolean;
   status: boolean;
   json: boolean;
@@ -88,6 +96,7 @@ type AgentMcpConfigTarget = {
   configPath: string;
   transport: AgentMcpTransport;
   endpoint: string;
+  mcpName: string;
   setupAction: string;
   forceAction: string;
   verifyCommand: string;
@@ -102,6 +111,7 @@ type AgentMcpConfigStatus = {
   state: AgentMcpConfigState;
   transport: AgentMcpStatusTransport;
   endpoint: string;
+  mcpName: string;
   action: string;
   forceAction: string;
   verifyCommand: string;
@@ -183,11 +193,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 +204,15 @@ 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,
+    mcpName: null,
     uninstall: false,
     status: false,
     json: false,
@@ -332,6 +340,36 @@ 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 "--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 +439,9 @@ 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 Inspector Base URL
+  --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 +528,49 @@ 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") {
+    args.push("--base-url", target.baseUrl);
+  }
+  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 +787,7 @@ function makeAgentStatus(
     state,
     transport,
     endpoint: target.endpoint,
+    mcpName: target.mcpName,
     action: target.setupAction,
     forceAction: target.forceAction,
     verifyCommand: target.verifyCommand,
@@ -743,12 +800,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 +825,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 +834,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 +852,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 +869,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 +921,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 +1191,21 @@ 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,
+        mcpName: onboardTarget.mcpName,
+        targetKind: onboardTarget.kind,
+        instanceName: onboardTarget.instanceName,
+        onboardTargetArguments: targetArguments,
         detectedSummary,
       })
     : "";
@@ -1144,7 +1213,12 @@ function buildPlannedFiles(
   const codexSkillBody = installCodex
     ? renderCodexSkillOnboard({
         version,
-        port: DEFAULT_PORT,
+        port: onboardTarget.port,
+        baseUrl: onboardTarget.baseUrl,
+        mcpName: onboardTarget.mcpName,
+        targetKind: onboardTarget.kind,
+        instanceName: onboardTarget.instanceName,
+        onboardTargetArguments: targetArguments,
       })
     : "";
 
@@ -1348,6 +1422,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 +1446,28 @@ 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,
+    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 +1498,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) {

package/src/cli/onboardTarget.ts

@@ -0,0 +1,179 @@
+import { appendBasePathToOrigin, getConfiguredBasePath } from "../lib/basePath.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 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;
+  baseUrl: string;
+  apiUrl: string;
+  healthUrl: string;
+  anthropicProxyUrl: string;
+  openAiProxyUrl: string;
+  mcpUrl: string;
+};
+
+export type OnboardTargetOptions = {
+  instanceName: string | null;
+  baseUrl: string | null;
+  mcpName: string | null;
+};
+
+export type OnboardTargetResult =
+  | { ok: true; target: OnboardTarget }
+  | { ok: false; message: string };
+
+function targetFromBase(
+  kind: OnboardTargetKind,
+  instanceName: string | null,
+  mcpName: string,
+  port: number,
+  baseUrl: string,
+): 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`,
+  };
+}
+
+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 candidate = rawBaseUrl.trim();
+  if (
+    candidate.length === 0 ||
+    candidate !== rawBaseUrl ||
+    candidate.includes("?") ||
+    candidate.includes("#")
+  ) {
+    return null;
+  }
+
+  try {
+    const parsed = new URL(candidate);
+    if (
+      (parsed.protocol !== "http:" && parsed.protocol !== "https:") ||
+      parsed.hostname.length === 0 ||
+      parsed.username.length > 0 ||
+      parsed.password.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;
+  } catch {
+    return null;
+  }
+}
+
+export function resolveOnboardTarget(
+  options: OnboardTargetOptions,
+  env: OnboardTargetEnv = process.env,
+): OnboardTargetResult {
+  if (options.instanceName !== null && options.baseUrl !== null) {
+    return {
+      ok: false,
+      message: "--instance and --base-url 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 (options.baseUrl !== null) {
+    const explicit = normalizeExplicitBaseUrl(options.baseUrl);
+    if (explicit === null) {
+      return {
+        ok: false,
+        message:
+          "--base-url must be a credential-free HTTP or HTTPS URL without a query or fragment",
+      };
+    }
+    return {
+      ok: true,
+      target: targetFromBase(
+        "base-url",
+        null,
+        explicitMcpName ?? "agent-inspector",
+        explicit.port,
+        explicit.baseUrl,
+      ),
+    };
+  }
+
+  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: targetFromBase(
+        "instance",
+        record.value.name,
+        explicitMcpName ?? `agent-inspector-${record.value.name}`,
+        record.value.publicPort,
+        baseUrl,
+      ),
+    };
+  }
+
+  const baseUrl = appendBasePathToOrigin(DEFAULT_ORIGIN, "/", getConfiguredBasePath(env));
+  return {
+    ok: true,
+    target: targetFromBase(
+      "default",
+      null,
+      explicitMcpName ?? "agent-inspector",
+      DEFAULT_PORT,
+      baseUrl,
+    ),
+  };
+}
+
+export const onboardTargetForTests = {
+  normalizeExplicitBaseUrl,
+  validateMcpName,
+};