@agent-native/core 0.51.15 → 0.53.0

package/dist/cli/connect.js

@@ -1,12 +1,13 @@
 /**
- * `agent-native connect <url>` — wire your local Claude Code / Codex / Cowork
+ * `agent-native connect <url>` — wire your local MCP-capable coding agent
  * to a DEPLOYED agent-native app. OAuth-capable clients receive a standard
  * remote MCP URL entry and authenticate in the host. Fallback clients use the
  * browser device-code flow: open the verification URL, approve in the browser,
  * and the minted HTTP MCP server entry is written idempotently.
  *
- *   agent-native connect <url> [--client all|claude-code|claude-code-cli|
- *                               codex|cowork] [--scope user|project]
+ *   agent-native connect <url> [--client all|claude-code|
+ *                               codex|cowork|cursor|opencode|github-copilot]
+ *                               [--scope user|project]
  *                               [--name <serverName>]
  *   agent-native reconnect [<url>] [--client ...] [--name <serverName>]
  *   agent-native connect <url> --token <token>   (no-browser fallback)
@@ -33,7 +34,7 @@ import os from "node:os";
 import { spawn } from "node:child_process";
 import path from "node:path";
 import { findWorkspaceRoot } from "../mcp/workspace-resolve.js";
-import { CLIENTS, configPathFor, removeSameUrlDuplicatesForClient, writeCodexBlock, writeHttpEntryForClient, writeJsonMcpEntry, } from "./mcp-config-writers.js";
+import { CLIENTS, configPathFor, jsonMcpConfigKeyForClient, removeSameUrlDuplicatesForClient, writeCodexBlock, writeHttpEntryForClient, writeJsonMcpEntryForClient, } from "./mcp-config-writers.js";
 import { isFirstPartyPlanHost, writePlanPublishAuth, } from "./plan-publish-store.js";
 import { TEMPLATES, visibleTemplates } from "./templates-meta.js";
 const DEVICE_START_PATH = "/_agent-native/mcp/connect/device/start";
@@ -66,16 +67,25 @@ const CLIENT_LABELS = {
     "claude-code-cli": "Claude Code CLI",
     codex: "Codex",
     cowork: "Claude Cowork",
+    cursor: "Cursor",
+    opencode: "OpenCode",
+    "github-copilot": "GitHub Copilot / VS Code",
 };
 const CLIENT_HINTS = {
     "claude-code": ".mcp.json or ~/.claude.json",
     "claude-code-cli": ".mcp.json or ~/.claude.json",
     codex: "$CODEX_HOME/config.toml or ~/.codex/config.toml",
     cowork: "~/.cowork/mcp.json",
+    cursor: ".cursor/mcp.json or ~/.cursor/mcp.json",
+    opencode: "opencode.json or ~/.config/opencode/opencode.json",
+    "github-copilot": ".vscode/mcp.json or VS Code user mcp.json",
 };
 const REMOTE_MCP_OAUTH_CLIENTS = new Set([
     "claude-code",
     "claude-code-cli",
+    "cursor",
+    "opencode",
+    "github-copilot",
 ]);
 let logOutImpl = (msg) => process.stdout.write(`${msg}\n`);
 let logErrImpl = (msg) => process.stderr.write(`${msg}\n`);
@@ -175,11 +185,15 @@ export function normalizeUrl(raw) {
     const base = `${parsed.origin}${parsed.pathname}`.replace(/\/+$/, "");
     return base;
 }
+// Clients offered in the interactive picker and expanded by "all". Excludes
+// the `claude-code-cli` alias so users only ever see a single "Claude Code"
+// option (it still works if passed explicitly via --client).
+const SELECTABLE_CLIENTS = CLIENTS.filter((c) => c !== "claude-code-cli");
 /** Resolve the requested clients list. "all" → every supported client. */
 export function resolveClients(client) {
-    const c = (client ?? "all").toLowerCase();
+    const c = normalizeClientAlias(client ?? "all");
     if (c === "all" || c === "")
-        return [...CLIENTS];
+        return [...SELECTABLE_CLIENTS];
     if (c.includes(",")) {
         const clients = normalizeClientIds(c.split(",").map((part) => part.trim()));
         if (clients.length > 0)
@@ -189,6 +203,20 @@ export function resolveClients(client) {
         return [c];
     throw new Error(`Unknown --client "${client}". Use: all, ${CLIENTS.join(", ")}`);
 }
+function normalizeClientAlias(value) {
+    const id = value.trim().toLowerCase();
+    // The Claude Code CLI and desktop share ~/.claude.json, so they are one
+    // client. `claude-code-cli` stays accepted for back-compat but collapses to
+    // the single "Claude Code" option everywhere it surfaces.
+    if (id === "claude" ||
+        id === "claude-code-desktop" ||
+        id === "claude-code-cli")
+        return "claude-code";
+    if (id === "copilot" || id === "vscode" || id === "vs-code") {
+        return "github-copilot";
+    }
+    return id;
+}
 export function connectPreferencesPath() {
     return path.join(os.homedir(), ".agent-native", "connect.json");
 }
@@ -200,7 +228,7 @@ function normalizeClientIds(values) {
     for (const value of values) {
         if (typeof value !== "string")
             continue;
-        const id = value.toLowerCase();
+        const id = normalizeClientAlias(value);
         if (!CLIENTS.includes(id))
             continue;
         const client = id;
@@ -233,7 +261,7 @@ export function writeConnectClientPreferences(clients, file = connectPreferences
     }, null, 2) + "\n", "utf-8");
 }
 function clientPromptOptions() {
-    return CLIENTS.map((client) => ({
+    return SELECTABLE_CLIENTS.map((client) => ({
         value: client,
         label: CLIENT_LABELS[client],
         hint: CLIENT_HINTS[client],
@@ -361,6 +389,22 @@ function sentenceClientLabelList(clients) {
         return `${labels[0]} and ${labels[1]}`;
     return `${labels.slice(0, -1).join(", ")}, and ${labels[labels.length - 1]}`;
 }
+function oauthNextStepsForClients(clients, serverName) {
+    const lines = [];
+    if (clients.includes("claude-code") || clients.includes("claude-code-cli")) {
+        lines.push("Claude Code: restart Claude Code, run /mcp, and choose Authenticate.");
+    }
+    if (clients.includes("cursor")) {
+        lines.push("Cursor: restart or reload Cursor, then authenticate the MCP server from Cursor MCP settings if prompted.");
+    }
+    if (clients.includes("opencode")) {
+        lines.push(`OpenCode: run opencode mcp auth ${serverName ?? "<server-name>"} or authenticate on first use.`);
+    }
+    if (clients.includes("github-copilot")) {
+        lines.push("GitHub Copilot / VS Code: reload VS Code, open the MCP config, and use the Auth action above the server if prompted.");
+    }
+    return lines;
+}
 function clientsNotIn(requestedClients, effectiveClients) {
     const effective = new Set(effectiveClients);
     return requestedClients.filter((client) => !effective.has(client));
@@ -379,7 +423,7 @@ async function showReconnectSuccessOutro({ serverName, clients, }) {
     }
     const oauthClients = clients.filter((client) => supportsRemoteMcpOAuth(client));
     if (oauthClients.length > 0) {
-        lines.push(`${sentenceClientLabelList(oauthClients)}: restart, run /mcp, then choose Authenticate/Reconnect.`);
+        lines.push(...oauthNextStepsForClients(oauthClients, serverName));
     }
     if (!clients.includes("codex") && oauthClients.length === 0) {
         lines.push(`Restart or reload ${sentenceClientLabelList(clients)} before using the MCP tools.`);
@@ -556,26 +600,43 @@ export async function runDeviceFlow(baseUrl, appSlug, clientArg, deps = {}, opti
     const sleep = deps.sleep ?? realSleep;
     const open = deps.openBrowser ?? openInBrowser;
     const now = deps.now ?? (() => Date.now());
-    let start;
-    try {
-        const { status, json } = await postJson(fetchImpl, `${baseUrl}${DEVICE_START_PATH}`, {
-            client: clientArg,
-            app: appSlug,
-            ...(options.fullCatalog ? { fullCatalog: true } : {}),
-        });
-        if (status < 200 || status >= 300 || !json?.device_code) {
+    let start = null;
+    // A cold/propagating Plan instance can briefly 404/5xx before its connect
+    // route is registered (async plugin init). Retry a few times so a recoverable
+    // blip doesn't kill the connect before polling even begins.
+    const START_ATTEMPTS = 4;
+    for (let attempt = 0; attempt < START_ATTEMPTS; attempt++) {
+        try {
+            const { status, json } = await postJson(fetchImpl, `${baseUrl}${DEVICE_START_PATH}`, {
+                client: clientArg,
+                app: appSlug,
+                ...(options.fullCatalog ? { fullCatalog: true } : {}),
+            });
+            if (status >= 200 && status < 300 && json?.device_code) {
+                start = json;
+                break;
+            }
+            if ((status === 404 || status >= 500) && attempt < START_ATTEMPTS - 1) {
+                await sleep(1000 * (attempt + 1));
+                continue;
+            }
             logErr(`  Could not start the connect flow on ${baseUrl} ` +
                 `(HTTP ${status}). Is this an agent-native app, and is it ` +
                 `deployed with the connect endpoint enabled?`);
             return null;
         }
-        start = json;
+        catch (err) {
+            if (attempt < START_ATTEMPTS - 1) {
+                await sleep(1000 * (attempt + 1));
+                continue;
+            }
+            logErr(`  Could not reach ${baseUrl} (${err?.message ?? err}). ` +
+                `Check the URL and your network.`);
+            return null;
+        }
     }
-    catch (err) {
-        logErr(`  Could not reach ${baseUrl} (${err?.message ?? err}). ` +
-            `Check the URL and your network.`);
+    if (!start)
         return null;
-    }
     const interval = Math.max(1, Number(start.interval) || 5);
     const expiresIn = Math.max(interval, Number(start.expires_in) || 600);
     const deadline = now() + expiresIn * 1000;
@@ -588,23 +649,59 @@ export async function runDeviceFlow(baseUrl, appSlug, clientArg, deps = {}, opti
     logOut("  Approve in the browser to finish. Opening it now…");
     open(start.verification_uri_complete);
     let spin = 0;
+    let transientStreak = 0;
+    // Ride out brief cold-instance blips, but don't poll a persistently-dead
+    // endpoint forever: give up after this many consecutive transient (404/5xx
+    // or network-error) polls. Reset as soon as one poll responds normally.
+    const MAX_TRANSIENT_POLLS = 20;
     const isTTY = !!process.stdout.isTTY;
     while (now() < deadline) {
         let poll;
+        let transient = false;
         try {
             const { status, json } = await postJson(fetchImpl, `${baseUrl}${DEVICE_POLL_PATH}`, { device_code: start.device_code });
             if (status < 200 || status >= 300) {
+                if (isTerminalPollBody(json)) {
+                    poll = json;
+                }
+                else if (status === 404 || status >= 500) {
+                    // Transient: a cold/propagating Plan instance can briefly serve a
+                    // bare 404 (the MCP route isn't registered until async plugin init
+                    // settles) or a 5xx before it's healthy. The next poll usually lands
+                    // on a warm instance, so keep polling until the deadline instead of
+                    // hard-failing the whole connect on a recoverable blip. (This is the
+                    // recurring "Cannot find any route matching [POST] .../mcp" case.)
+                    poll = { status: "pending" };
+                    transient = true;
+                }
+                else {
+                    if (isTTY)
+                        process.stdout.write("\r\x1b[K");
+                    logErr(`  Connect polling failed (HTTP ${status}): ` +
+                        responseMessage(json, "server returned an error."));
+                    return null;
+                }
+            }
+            else {
+                poll = (json ?? { status: "pending" });
+            }
+        }
+        catch {
+            // Transient network error — keep polling.
+            poll = { status: "pending" };
+            transient = true;
+        }
+        if (transient) {
+            if (++transientStreak > MAX_TRANSIENT_POLLS) {
                 if (isTTY)
                     process.stdout.write("\r\x1b[K");
-                logErr(`  Connect polling failed (HTTP ${status}): ` +
-                    responseMessage(json, "server returned an error."));
+                logErr("  Connect endpoint is not responding (repeated 404/5xx). It may be " +
+                    "mid-deploy — wait a minute and run the command again.");
                 return null;
             }
-            poll = (json ?? { status: "pending" });
         }
-        catch {
-            // Transient network error — keep polling until the deadline.
-            poll = { status: "pending" };
+        else {
+            transientStreak = 0;
         }
         if (poll.status === "approved") {
             if (isTTY)
@@ -652,6 +749,12 @@ export async function runDeviceFlow(baseUrl, appSlug, clientArg, deps = {}, opti
     logErr("  Timed out waiting for approval. Run the command again to retry.");
     return null;
 }
+function isTerminalPollBody(json) {
+    return (json?.status === "not_found" ||
+        json?.status === "error" ||
+        json?.status === "expired" ||
+        json?.status === "consumed");
+}
 // ---------------------------------------------------------------------------
 // Writing config(s)
 // ---------------------------------------------------------------------------
@@ -707,10 +810,10 @@ function setSavedProfileEntry(profiles, serverName, client, file, entry) {
     profiles.prodEntries[serverName][client] ??= {};
     profiles.prodEntries[serverName][client][file] = entry;
 }
-function readJsonMcpServerEntry(file, serverName) {
+function readJsonMcpServerEntry(client, file, serverName) {
     try {
         const parsed = JSON.parse(fs.readFileSync(file, "utf-8"));
-        const entry = parsed?.mcpServers?.[serverName];
+        const entry = parsed?.[jsonMcpConfigKeyForClient(client)]?.[serverName];
         return entry && typeof entry === "object" ? entry : undefined;
     }
     catch {
@@ -760,7 +863,7 @@ function readCurrentMcpEntry(client, serverName, baseDir, scope) {
                 : undefined,
         };
     }
-    const entry = readJsonMcpServerEntry(file, serverName);
+    const entry = readJsonMcpServerEntry(client, file, serverName);
     return {
         file,
         saved: entry
@@ -777,7 +880,7 @@ function writeSavedMcpEntry(client, file, serverName, saved) {
     }
     if (saved.kind !== "json")
         return;
-    writeJsonMcpEntry(file, serverName, saved.entry);
+    writeJsonMcpEntryForClient(client, file, serverName, saved.entry);
 }
 function unescapeTomlString(value) {
     return value.replace(/\\"/g, '"').replace(/\\\\/g, "\\");
@@ -808,10 +911,10 @@ function savedEntryUrl(saved) {
     const match = saved.block.match(/^\s*url\s*=\s*"((?:\\.|[^"])*)"/m);
     return match ? unescapeTomlString(match[1]) : undefined;
 }
-function readJsonMcpServerEntries(file) {
+function readJsonMcpServerEntries(client, file) {
     try {
         const parsed = JSON.parse(fs.readFileSync(file, "utf-8"));
-        const servers = parsed?.mcpServers;
+        const servers = parsed?.[jsonMcpConfigKeyForClient(client)];
         if (!servers || typeof servers !== "object" || Array.isArray(servers)) {
             return [];
         }
@@ -881,7 +984,7 @@ function readExistingMcpEntries(clients, baseDir, scope) {
         const file = configPathFor(client, baseDir, scope);
         const rawEntries = client === "codex"
             ? readCodexMcpServerEntries(file)
-            : readJsonMcpServerEntries(file);
+            : readJsonMcpServerEntries(client, file);
         for (const { serverName, saved } of rawEntries) {
             const url = savedEntryUrl(saved);
             if (!url)
@@ -912,7 +1015,12 @@ function savedEntryHeaders(saved) {
     if (!saved)
         return {};
     if (saved.kind === "json") {
-        const headers = saved.entry.headers;
+        const headers = saved.entry.headers ??
+            (saved.entry.requestInit &&
+                typeof saved.entry.requestInit === "object" &&
+                !Array.isArray(saved.entry.requestInit)
+                ? saved.entry.requestInit.headers
+                : undefined);
         return headers && typeof headers === "object"
             ? Object.fromEntries(Object.entries(headers)
                 .filter((entry) => {
@@ -1526,12 +1634,11 @@ async function connectOne(rawUrl, parsed, clients, deps) {
     // ADDITIONAL write alongside the per-client MCP config; Best-effort and
     // merge-not-clobber — never fails the connect.
     //
-    // OAuth clients (claude-code, claude-code-cli) authenticate in-host via
-    // standard MCP OAuth, so they never mint a local bearer token. To still
-    // populate the publish store for them, we run a supplemental device-flow
-    // mint using a non-OAuth client arg so the Plans server gets a usable token
-    // and `publish-visual-plan` doesn't send the user back to `agent-native
-    // connect` right after they just ran it.
+    // OAuth clients authenticate in-host via standard MCP OAuth, so they never
+    // mint a local bearer token. To still populate the publish store for them, we
+    // run a supplemental device-flow mint using a non-OAuth client arg so the
+    // Plans server gets a usable token and `publish-visual-plan` doesn't send the
+    // user back to `agent-native connect` right after they just ran it.
     let publishToken = token;
     if (!publishToken &&
         oauthClients.length > 0 &&
@@ -1579,7 +1686,9 @@ async function connectOne(rawUrl, parsed, clients, deps) {
             logOut(`  Replaced legacy bearer headers for ${clientLabelList(oauthMigrations)}; it will reconnect with standard MCP OAuth.`);
         }
         logOut(`  ${clientLabelList(oauthClients)}: wrote URL-only MCP config (no bearer headers).`);
-        logOut("  Next: restart Claude Code, run /mcp, and choose Authenticate.");
+        for (const line of oauthNextStepsForClients(oauthClients, serverName)) {
+            logOut(`  Next: ${line}`);
+        }
     }
     logOut("");
     logOut(`  Restart or reload ${sentenceClientLabelList(clients)} to pick up the new MCP server.`);
@@ -1762,16 +1871,16 @@ Usage:
 
   npx @agent-native/core@latest connect <url> [--client <c>] [--scope user|project] [--name <n>]
       Writes the HTTP MCP entry into your selected client config(s). Claude
-      Code / Claude Code CLI use standard remote MCP OAuth: restart Claude,
-      run /mcp, and choose Authenticate. Codex / Cowork use the browser
+      Code, Cursor, OpenCode, and GitHub Copilot / VS Code use standard remote
+      MCP OAuth and get URL-only config. Codex / Cowork use the browser
       device-code fallback: the command prints a code, opens the verification
       URL, polls until approved, then writes bearer headers. With no --client,
       opens a brief picker preselected from ~/.agent-native/connect.json, or
       all clients on first run. Idempotent — re-running replaces the same entry.
       Auth is stored per client config/session; restart or reload each selected
       client before expecting new tools to appear.
-      Re-running over an older Claude bearer entry upgrades it to URL-only
-      OAuth config and prompts you to authenticate with /mcp.
+      Re-running over an older OAuth-capable bearer entry upgrades it to
+      URL-only OAuth config and prompts you to authenticate in that host.
 
       For cross-app access, prefer the unified Dispatch gateway:
       npx @agent-native/core@latest connect https://dispatch.agent-native.com
@@ -1808,7 +1917,7 @@ Developer:
   npx @agent-native/core@latest connect prod [--apps mail,calendar] [--client <c>]
       Restore production MCP entries saved before the dev switch.
 
-Clients:  all (default), claude-code, claude-code-cli, codex, cowork
+Clients:  all (default), claude-code, codex, cowork, cursor, opencode, github-copilot
 Scope:    user (default, ~/.claude.json) or project (.mcp.json)`;
 /**
  * `agent-native connect` entry point. `deps` is injectable for tests; the