@spacefast/common 0.0.26 → 0.2.2

package/dist/agents/connect-targets.d.ts

@@ -1,141 +1,10 @@
-import { type ConnectTargetId } from "./client-registry.js";
-export { CONNECT_TARGET_IDS } from "./client-registry.js";
-export type { ConnectTargetId } from "./client-registry.js";
+import { type AgentId } from "./registry/core.js";
+export declare const CONNECT_TARGET_IDS: readonly ["claude-code", "claude-app", "claude-desktop", "cursor", "codex", "chatgpt", "vscode", "github-copilot", "devin-desktop", "devin-cloud", "zed", "gemini-cli", "opencode", "amp", "warp", "factory-droid", "cline", "continue", "raycast", "poke", "pi", "indent", "hermes", "openclaw"];
+export type ConnectTargetId = AgentId;
 export declare const LOCAL_MCP_PACKAGE = "spacefast";
 export declare const LOCAL_MCP_COMMAND = "npx";
 export declare const LOCAL_MCP_ARGS: readonly ["-y", "spacefast", "mcp"];
-/** The copy-paste one-liner for the fixed On-Device product surface. */
 export declare const LOCAL_MCP_COMMAND_LINE: string;
-/**
- * base64 of a UTF-8 string, without Buffer. Byte-identical to
- * `Buffer.from(value, "utf8").toString("base64")`, so deeplinks stay stable
- * whether they are built at the Astro build (Node) or in the dashboard (browser).
- */
-export declare function base64Utf8(value: string): string;
-/** The on-device MCP server entry, byte-identical to the committed plugin `.mcp.json`. */
-export declare function localMcpServersJson(): {
-    mcpServers: {
-        spacefast: {
-            command: string;
-            args: ("mcp" | "spacefast" | "-y")[];
-            env: {};
-        };
-    };
-};
-/**
- * VS Code's `.vscode/mcp.json` uses a top-level `servers` key (not the
- * `mcpServers` key Cursor/Claude Code use), so it gets its own generator —
- * single-sourced from the same command/args/package so it can never drift.
- * See https://code.visualstudio.com/docs/agent-customization/mcp-servers.
- */
-export declare function vscodeMcpServersJson(): {
-    servers: {
-        spacefast: {
-            type: string;
-            command: string;
-            args: ("mcp" | "spacefast" | "-y")[];
-        };
-    };
-};
-export declare function cursorHostedMcpDeeplink(mcpEndpoint: string): string;
-export declare function vscodeHostedMcpDeeplink(mcpEndpoint: string): string;
-export declare function pokeHostedMcpDeeplink(mcpEndpoint: string): string;
-/**
- * The hosted server entry for the Pi coding agent's `pi-mcp-extension`
- * (`~/.pi/agent/mcp.json` or a project `.pi/mcp.json`). Pi has no built-in
- * MCP; the extension (`pi install npm:pi-mcp-extension`) adds it with a
- * `transport: "streamable-http"` entry — its own key names, not the
- * `type: "http"` shape Claude Code and VS Code use.
- */
-export declare function piHostedMcpConfig(mcpEndpoint: string): {
-    mcpServers: {
-        spacefast: {
-            transport: string;
-            url: string;
-        };
-    };
-};
-export declare function claudeHostedConnectorInstallUrl(mcpEndpoint: string): string;
-export declare function claudeOrgConnectorInstallUrl(mcpEndpoint: string): string;
-/**
- * The hosted server entry for Claude Code's `.mcp.json`. Claude Code rejects a
- * bare `{ url }` as invalid, so the entry carries `type: "http"` — byte-identical
- * to the committed `plugins/claude-code/.mcp.json`.
- */
-export declare function hostedMcpServersJson(mcpEndpoint: string): {
-    mcpServers: {
-        spacefast: {
-            type: string;
-            url: string;
-        };
-    };
-};
-/**
- * The hosted server entry for Cursor's `~/.cursor/mcp.json`. Cursor's known-good
- * shape is a bare `{ url }` (no `type`) — matching the committed
- * `plugins/cursor/.mcp.json`. Kept separate from the Claude Code generator
- * rather than adding `type` everywhere, since `type: "http"` in Cursor's file is
- * untested territory.
- */
-export declare function cursorHostedMcpServersJson(mcpEndpoint: string): {
-    mcpServers: {
-        spacefast: {
-            url: string;
-        };
-    };
-};
-/** The hosted server entry for VS Code's `.vscode/mcp.json` (`servers` + `type: http`). */
-export declare function vscodeHostedMcpServersJson(mcpEndpoint: string): {
-    servers: {
-        spacefast: {
-            type: string;
-            url: string;
-        };
-    };
-};
-/**
- * A complete, schema-pinned OpenCode V2 config for the hosted MCP server.
- * OpenCode's `mcp` key is a flat map keyed by server name (no `servers` level) —
- * the same shape `sf mcp install` writes (packages/cli/src/agent-setup.ts).
- */
-export declare function opencodeHostedMcpConfig(mcpEndpoint: string): {
-    $schema: string;
-    mcp: {
-        spacefast: {
-            type: string;
-            url: string;
-            enabled: boolean;
-        };
-    };
-};
-export declare function codexHostedMcpToml(mcpEndpoint: string): string;
-export declare const CODEX_MCP_TOML: string;
-/**
- * Claude Code's one-command hosted-MCP connect (`claude mcp add`). Parameterized
- * by the hosted endpoint so the dashboard can point it at the runtime-derived
- * endpoint while the marketing site passes the prod constant.
- */
-export declare function buildClaudeMcpAddCommand(mcpEndpoint: string): string;
-/**
- * Codex's hosted-MCP connect. `codex mcp add` registers the server; OAuth is a
- * separate `codex mcp login` step, so both are chained — a bare `add` leaves the
- * connection unauthenticated and the tools 401.
- */
-export declare function buildCodexMcpAddCommand(mcpEndpoint: string): string;
-/**
- * Hermes's hosted-MCP connect (`hermes mcp add --url`), the form NousResearch's
- * hermes-agent MCP guide documents. `--auth oauth` opts the hosted server into
- * the browser sign-in flow; unlike Codex there is no separate login command.
- */
-export declare function buildHermesMcpAddCommand(mcpEndpoint: string): string;
-/**
- * OpenClaw's hosted-MCP connect (`openclaw mcp add`), the form
- * docs.openclaw.ai/cli/mcp documents: `--transport streamable-http` is required
- * (no auto-detection), `--auth oauth` opts into OAuth. Sign-in is a separate
- * two-step `openclaw mcp login <name>` (prints an auth URL, then `--code`), so
- * setup copy must not promise a single-command flow.
- */
-export declare function buildOpenclawMcpAddCommand(mcpEndpoint: string): string;
 export type ConnectCopyLanguage = "bash" | "json" | "toml" | "text";
 export type ConnectCopy = Readonly<{
     /** Short label for the affordance and the copied-value toast. */
@@ -153,11 +22,7 @@ export type ConnectDownload = Readonly<{
     href: string;
     label: string;
 }>;
-/**
- * A single connect card: one agent, one primary action (a one-click deeplink or
- * a copy of the command/endpoint that wires it), plus an optional secondary
- * "copy the client config file" affordance.
- */
+/** A single connect card: one agent, one primary action, optional extras. */
 export type ConnectTarget = Readonly<{
     id: ConnectTargetId;
     name: string;
@@ -172,15 +37,10 @@ export type ConnectTarget = Readonly<{
     /** A downloadable installer for clients that ship one (Claude Desktop). */
     download?: ConnectDownload;
 }>;
-/**
- * The per-agent connect catalog, parameterized by the hosted MCP endpoint.
- * Every one-click and copy-config path carries the hosted endpoint (OAuth,
- * nothing to install); on-device stdio is the CLI users' alternative and
- * lives in the docs/marketing setup lanes, not here.
- */
+/** The per-agent connect catalog, parameterized by the hosted MCP endpoint. */
 export declare function buildConnectTargets({ mcpEndpoint }: {
     mcpEndpoint: string;
 }): ConnectTarget[];
-export declare function getConnectTarget(id: ConnectTargetId, options: {
+export declare function getConnectTarget(id: string, options: {
     mcpEndpoint: string;
 }): ConnectTarget;

package/dist/agents/connect-targets.js

@@ -1,307 +1,75 @@
 /*
- * Shared, browser-safe agent connect catalog.
+ * The connect-card projection of the agent registry.
  *
- * One source of truth for "add Spacefast to your agent": the MCP launch config,
- * the one-click deeplinks, and the per-agent connect entries. Both the marketing
- * standalone website (with the hardcoded prod
- * endpoint) and the Team Developer dashboard (with the runtime-derived
- * hosted endpoint) consume these, so every "connect an agent" surface advertises
- * the identical command, package, and config — they can never drift apart.
+ * This file used to hand-maintain a second copy of every deeplink, MCP config
+ * shape, and `mcp add` command. Those builders are gone: the registry
+ * (./registry/core.ts) owns the data, and this module is only the card shape the
+ * handoff document and the dashboard's connect surfaces render. A builder that
+ * lives here again is a fork waiting to happen.
  *
- * ISOMORPHIC ON PURPOSE: no Buffer, no process, no Node-only APIs. The dashboard
- * renders this in the browser, so base64 goes through TextEncoder + btoa (both
- * standard in browsers, Node 16+, and Bun) rather than Buffer.
+ * Isomorphic on purpose: no Buffer, no process, no Node-only APIs.
  */
-import { spacefastClaudePluginAddCommand, spacefastClaudePluginInstallCommand, spacefastCodexPluginAddCommand, spacefastCodexPluginInstallCommand, } from "../docs/skill-distribution.js";
-import { agentProductName } from "./client-registry.js";
-export { CONNECT_TARGET_IDS } from "./client-registry.js";
+import { AGENT_IDS, AGENT_REGISTRY, presentAgentEntry, } from "./registry/core.js";
+export const CONNECT_TARGET_IDS = AGENT_IDS;
 export const LOCAL_MCP_PACKAGE = "spacefast";
 export const LOCAL_MCP_COMMAND = "npx";
 export const LOCAL_MCP_ARGS = ["-y", LOCAL_MCP_PACKAGE, "mcp"];
-/** The copy-paste one-liner for the fixed On-Device product surface. */
 export const LOCAL_MCP_COMMAND_LINE = `${LOCAL_MCP_COMMAND} ${LOCAL_MCP_ARGS.join(" ")}`;
-/**
- * base64 of a UTF-8 string, without Buffer. Byte-identical to
- * `Buffer.from(value, "utf8").toString("base64")`, so deeplinks stay stable
- * whether they are built at the Astro build (Node) or in the dashboard (browser).
- */
-export function base64Utf8(value) {
-    const bytes = new TextEncoder().encode(value);
-    let binary = "";
-    for (const byte of bytes) {
-        binary += String.fromCharCode(byte);
-    }
-    return btoa(binary);
-}
-/** The on-device MCP server entry, byte-identical to the committed plugin `.mcp.json`. */
-export function localMcpServersJson() {
-    return {
-        mcpServers: {
-            [LOCAL_MCP_PACKAGE]: {
-                command: LOCAL_MCP_COMMAND,
-                args: [...LOCAL_MCP_ARGS],
-                env: {},
-            },
-        },
-    };
-}
-/**
- * VS Code's `.vscode/mcp.json` uses a top-level `servers` key (not the
- * `mcpServers` key Cursor/Claude Code use), so it gets its own generator —
- * single-sourced from the same command/args/package so it can never drift.
- * See https://code.visualstudio.com/docs/agent-customization/mcp-servers.
- */
-export function vscodeMcpServersJson() {
-    return {
-        servers: {
-            [LOCAL_MCP_PACKAGE]: {
-                type: "stdio",
-                command: LOCAL_MCP_COMMAND,
-                args: [...LOCAL_MCP_ARGS],
-            },
-        },
-    };
-}
-/*
- * ONE-CLICK PATHS ARE ALWAYS HOSTED. Policy: hosted MCP for cloud agents,
- * on-device for local ones — but a one-click install must never depend on the
- * user having npm/npx. The hosted URL server needs no runtime at all (the
- * client speaks HTTP + OAuth), so every deeplink and every primary action
- * carries the hosted endpoint. On-device stdio (`npx -y spacefast mcp`) stays
- * available as the explicitly-labeled alternative for people who run the CLI —
- * their environment already provides npx.
- */
-// Cursor one-click MCP install link — the canonical form Cursor's own directory
-// badges emit is the HTTPS web link (`https://cursor.com/install-mcp`), which
-// renders as a normal anchor everywhere; the `cursor://` scheme still works but
-// isn't what Cursor advertises. The inner config is the hosted URL entry
-// (base64-encoded); Cursor handles the OAuth dance itself.
-export function cursorHostedMcpDeeplink(mcpEndpoint) {
-    return `https://cursor.com/install-mcp?name=${LOCAL_MCP_PACKAGE}&config=${encodeURIComponent(base64Utf8(JSON.stringify({ url: mcpEndpoint })))}`;
-}
-// VS Code one-click MCP install link — the HTTPS redirect service, which 302s
-// into the documented `vscode:mcp/install?<uriencoded JSON>` URL handler. Host
-// is `vscode.dev` (NOT the badge-era `insiders.vscode.dev`, which emits the
-// same stable-VS-Code Location header today but reads as "insiders" to users
-// and breaks if the redirect ever honors its host). The config is the server
-// object WITHOUT the name (the service merges the `name` param into the JSON),
-// plain URI-encoded — base64 is Cursor's rule, not VS Code's. `type: "http"`
-// is mandatory: VS Code treats a bare `url` as a stdio command and fails
-// confusingly.
-export function vscodeHostedMcpDeeplink(mcpEndpoint) {
-    return `https://vscode.dev/redirect/mcp/install?name=${LOCAL_MCP_PACKAGE}&config=${encodeURIComponent(JSON.stringify({ type: "http", url: mcpEndpoint }))}`;
-}
-// Poke one-click MCP install link — a plain HTTPS page that prefills the
-// new-integration form (https://poke.com/docs/mcp-servers): ordinary
-// URI-encoded query params, no JSON blob, no base64. All params stay
-// user-editable in the form; the user reviews and hits Create. `apiKey` is
-// also accepted but must NEVER appear in a public link — our hosted server
-// authenticates via OAuth.
-export function pokeHostedMcpDeeplink(mcpEndpoint) {
-    return `https://poke.com/integrations/new?name=Spacefast&url=${encodeURIComponent(mcpEndpoint)}`;
-}
-/**
- * The hosted server entry for the Pi coding agent's `pi-mcp-extension`
- * (`~/.pi/agent/mcp.json` or a project `.pi/mcp.json`). Pi has no built-in
- * MCP; the extension (`pi install npm:pi-mcp-extension`) adds it with a
- * `transport: "streamable-http"` entry — its own key names, not the
- * `type: "http"` shape Claude Code and VS Code use.
- */
-export function piHostedMcpConfig(mcpEndpoint) {
-    return {
-        mcpServers: {
-            [LOCAL_MCP_PACKAGE]: { transport: "streamable-http", url: mcpEndpoint },
-        },
-    };
-}
-// Claude custom-connector install link — opens claude.ai's "Add custom
-// connector" dialog with name and URL prefilled (documented under "Share an
-// install link", claude.com/docs/connectors/building/directory-vs-custom).
-// Plain percent-encoded params, no JSON blob; the dialog shows the values came
-// from an external link and the user confirms before anything is added. The
-// connector then syncs to every Claude client (web, Desktop, mobile). Signed-out
-// users get the sign-in first, then land on the prefilled dialog.
-export function claudeHostedConnectorInstallUrl(mcpEndpoint) {
-    return `https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Spacefast&connectorUrl=${encodeURIComponent(mcpEndpoint)}`;
-}
-// The same documented params on the admin path: prefills the ORG-WIDE custom
-// connector dialog for Team/Enterprise Owners. Adding it org-wide connects
-// nobody by itself — each member still clicks Connect on the rolled-out
-// connector — so copy around this link must address the admin, not the member.
-export function claudeOrgConnectorInstallUrl(mcpEndpoint) {
-    return `https://claude.ai/admin-settings/connectors?modal=add-custom-connector&connectorName=Spacefast&connectorUrl=${encodeURIComponent(mcpEndpoint)}`;
-}
-/**
- * The hosted server entry for Claude Code's `.mcp.json`. Claude Code rejects a
- * bare `{ url }` as invalid, so the entry carries `type: "http"` — byte-identical
- * to the committed `plugins/claude-code/.mcp.json`.
- */
-export function hostedMcpServersJson(mcpEndpoint) {
-    return {
-        mcpServers: {
-            [LOCAL_MCP_PACKAGE]: { type: "http", url: mcpEndpoint },
-        },
-    };
-}
-/**
- * The hosted server entry for Cursor's `~/.cursor/mcp.json`. Cursor's known-good
- * shape is a bare `{ url }` (no `type`) — matching the committed
- * `plugins/cursor/.mcp.json`. Kept separate from the Claude Code generator
- * rather than adding `type` everywhere, since `type: "http"` in Cursor's file is
- * untested territory.
- */
-export function cursorHostedMcpServersJson(mcpEndpoint) {
-    return {
-        mcpServers: {
-            [LOCAL_MCP_PACKAGE]: { url: mcpEndpoint },
-        },
-    };
-}
-/** The hosted server entry for VS Code's `.vscode/mcp.json` (`servers` + `type: http`). */
-export function vscodeHostedMcpServersJson(mcpEndpoint) {
-    return {
-        servers: {
-            [LOCAL_MCP_PACKAGE]: { type: "http", url: mcpEndpoint },
-        },
-    };
-}
-/**
- * A complete, schema-pinned OpenCode V2 config for the hosted MCP server.
- * OpenCode's `mcp` key is a flat map keyed by server name (no `servers` level) —
- * the same shape `sf mcp install` writes (packages/cli/src/agent-setup.ts).
- */
-export function opencodeHostedMcpConfig(mcpEndpoint) {
-    return {
-        $schema: "https://opencode.ai/config.json",
-        mcp: {
-            [LOCAL_MCP_PACKAGE]: {
-                type: "remote",
-                url: mcpEndpoint,
-                enabled: true,
-            },
-        },
-    };
-}
-// Codex reads MCP servers from `~/.codex/config.toml`; the hosted entry is a
-// bare streamable-HTTP url (same lane the committed codex plugin ships).
-export function codexHostedMcpToml(mcpEndpoint) {
-    return [`[mcp_servers.${LOCAL_MCP_PACKAGE}]`, `url = ${JSON.stringify(mcpEndpoint)}`].join("\n");
-}
-// The on-device stdio TOML, for CLI users whose environment provides npx.
-export const CODEX_MCP_TOML = [
-    `[mcp_servers.${LOCAL_MCP_PACKAGE}]`,
-    `command = ${JSON.stringify(LOCAL_MCP_COMMAND)}`,
-    `args = [${LOCAL_MCP_ARGS.map((arg) => JSON.stringify(arg)).join(", ")}]`,
-].join("\n");
-/**
- * Claude Code's one-command hosted-MCP connect (`claude mcp add`). Parameterized
- * by the hosted endpoint so the dashboard can point it at the runtime-derived
- * endpoint while the marketing site passes the prod constant.
- */
-export function buildClaudeMcpAddCommand(mcpEndpoint) {
-    return `claude mcp add --transport http ${LOCAL_MCP_PACKAGE} ${mcpEndpoint}`;
-}
-/**
- * Codex's hosted-MCP connect. `codex mcp add` registers the server; OAuth is a
- * separate `codex mcp login` step, so both are chained — a bare `add` leaves the
- * connection unauthenticated and the tools 401.
- */
-export function buildCodexMcpAddCommand(mcpEndpoint) {
-    return `codex mcp add ${LOCAL_MCP_PACKAGE} --url ${mcpEndpoint} && codex mcp login ${LOCAL_MCP_PACKAGE}`;
-}
-/**
- * Hermes's hosted-MCP connect (`hermes mcp add --url`), the form NousResearch's
- * hermes-agent MCP guide documents. `--auth oauth` opts the hosted server into
- * the browser sign-in flow; unlike Codex there is no separate login command.
- */
-export function buildHermesMcpAddCommand(mcpEndpoint) {
-    return `hermes mcp add ${LOCAL_MCP_PACKAGE} --url ${mcpEndpoint} --auth oauth`;
-}
-/**
- * OpenClaw's hosted-MCP connect (`openclaw mcp add`), the form
- * docs.openclaw.ai/cli/mcp documents: `--transport streamable-http` is required
- * (no auto-detection), `--auth oauth` opts into OAuth. Sign-in is a separate
- * two-step `openclaw mcp login <name>` (prints an auth URL, then `--code`), so
- * setup copy must not promise a single-command flow.
- */
-export function buildOpenclawMcpAddCommand(mcpEndpoint) {
-    return `openclaw mcp add ${LOCAL_MCP_PACKAGE} --url ${mcpEndpoint} --transport streamable-http --auth oauth`;
-}
-/**
- * The per-agent connect catalog, parameterized by the hosted MCP endpoint.
- * Every one-click and copy-config path carries the hosted endpoint (OAuth,
- * nothing to install); on-device stdio is the CLI users' alternative and
- * lives in the docs/marketing setup lanes, not here.
- */
+/** The per-agent connect catalog, parameterized by the hosted MCP endpoint. */
 export function buildConnectTargets({ mcpEndpoint }) {
-    const cursorConfigJson = JSON.stringify(cursorHostedMcpServersJson(mcpEndpoint), null, 2);
-    const vscodeHostedConfigJson = JSON.stringify(vscodeHostedMcpServersJson(mcpEndpoint), null, 2);
-    return [
-        {
-            // The plugin is the recommended lane for CLI agents that support one:
-            // one paste ships the publish skill AND the MCP servers (hosted primary)
-            // and stays updated through the marketplace. `claude mcp add` remains
-            // the minimal MCP-only path in the config slot and on /agents.
-            id: "claude-code",
-            name: agentProductName("claude-code"),
-            blurb: "One paste installs the plugin: publish skill plus MCP, updated from the marketplace.",
-            primary: {
-                label: "Install plugin",
-                value: `${spacefastClaudePluginAddCommand} && ${spacefastClaudePluginInstallCommand}`,
-                language: "bash",
-            },
-            config: {
-                label: "MCP only: claude mcp add",
-                value: buildClaudeMcpAddCommand(mcpEndpoint),
-                language: "bash",
-            },
-        },
-        {
-            id: "cursor",
-            name: agentProductName("cursor"),
-            blurb: "One click adds hosted MCP. Approve once in the browser, nothing to install.",
-            deeplink: { href: cursorHostedMcpDeeplink(mcpEndpoint), label: "Add to Cursor" },
-            config: { label: "~/.cursor/mcp.json", value: cursorConfigJson, language: "json" },
-        },
-        {
-            id: "vscode",
-            name: agentProductName("vscode"),
-            blurb: "One click adds hosted MCP for Copilot agent mode.",
-            deeplink: { href: vscodeHostedMcpDeeplink(mcpEndpoint), label: "Add to VS Code" },
-            config: { label: ".vscode/mcp.json", value: vscodeHostedConfigJson, language: "json" },
-        },
-        {
-            id: "codex",
-            name: agentProductName("codex"),
-            blurb: "One paste installs the plugin: publish skill plus MCP, updated from the marketplace.",
-            primary: {
-                label: "Install plugin",
-                value: `${spacefastCodexPluginAddCommand} && ${spacefastCodexPluginInstallCommand}`,
-                language: "bash",
-            },
-            config: {
-                label: "MCP only: codex mcp add",
-                value: buildCodexMcpAddCommand(mcpEndpoint),
-                language: "bash",
-            },
-        },
-        {
-            id: "claude",
-            name: agentProductName("claude"),
-            blurb: "Settings → Connectors → Add custom connector, paste this endpoint. Or grab the desktop extension.",
-            primary: { label: "MCP endpoint", value: mcpEndpoint, language: "text" },
-            download: {
-                href: "https://github.com/spacefast/plugins/releases/latest/download/claude-desktop.mcpb",
-                label: "Download desktop extension",
-            },
-        },
-        {
-            id: "chatgpt",
-            name: agentProductName("chatgpt"),
-            blurb: "Turn on Developer mode (Settings → Apps & Connectors → Advanced), then Connectors → Create with this endpoint.",
-            primary: { label: "MCP endpoint", value: mcpEndpoint, language: "text" },
-        },
-    ];
+    const context = {
+        apiOrigin: "https://api.spacefast.com",
+        dashboardOrigin: "https://my.spacefast.com",
+        mcpEndpoint,
+        wwwOrigin: "https://spacefast.com",
+    };
+    return AGENT_REGISTRY.map((agent) => {
+        const presented = presentAgentEntry(agent.id, context);
+        // The registry already ranks the interactive lane, and it never leads with a
+        // listing that has nothing to run, so the first method is the card's action.
+        const primaryMethod = presented.methods[0];
+        const action = primaryMethod?.action;
+        const configMethod = agent.methods.find((method) => method.kind === "config");
+        const downloadMethod = agent.methods.find((method) => method.kind === "download");
+        const target = {
+            id: agent.id,
+            name: agent.name,
+            blurb: agent.description,
+        };
+        if (action?.kind === "link") {
+            target.deeplink = { href: action.value, label: action.label };
+        }
+        else if (action?.kind === "copy") {
+            target.primary = {
+                label: action.label,
+                value: action.value,
+                language: connectCopyLanguage(primaryMethod?.language),
+            };
+        }
+        if (configMethod?.kind === "config") {
+            target.config = {
+                label: configMethod.label,
+                value: configMethod.build(context),
+                language: connectCopyLanguage(configMethod.language),
+            };
+        }
+        if (downloadMethod?.kind === "download") {
+            target.download = {
+                href: downloadMethod.url(context),
+                label: downloadMethod.label,
+            };
+        }
+        return target;
+    });
+}
+function connectCopyLanguage(language) {
+    if (language === "json" || language === "jsonc")
+        return "json";
+    if (language === "toml")
+        return "toml";
+    if (language === "bash")
+        return "bash";
+    return "text";
 }
 export function getConnectTarget(id, options) {
     const target = buildConnectTargets(options).find((entry) => entry.id === id);

package/dist/agents/private-key-oauth.d.ts

@@ -19,7 +19,7 @@ export type AgentTokenExchangeResult = {
     accessToken: string;
     expiresIn: number;
 };
-/** Parse private-key agent credentials using the established bundled-over-split env precedence. */
+/** Parse private-key agent credentials using the bundled-over-split env precedence. */
 export declare function readAgentAuthConfig(env: AgentAuthEnvironment, apiUrl: string): AgentAuthConfig | null;
 export declare function resolveAgentApiAuthorization(config: AgentAuthConfig, apiUrl: string): {
     resources: string[];
@@ -34,3 +34,33 @@ export declare function exchangeAgentAccessToken(input: {
     createInvalidConfigError?: ((message: string) => Error) | undefined;
     fetch?: typeof globalThis.fetch | undefined;
 }): Promise<AgentTokenExchangeResult>;
+export type CachedAgentTokenRequest = {
+    apiUrl: string;
+    /** `x-spacefast-client` attribution for the exchange. Not part of the cache key. */
+    client: string;
+    config: AgentAuthConfig;
+    signal: AbortSignal;
+};
+export type CachedAgentTokenProvider = {
+    /** The cached access token for this authorization, exchanging one when needed. */
+    accessToken: (request: CachedAgentTokenRequest) => Promise<string>;
+    /** Drop the cached token so the next call re-exchanges. Call this on a 401. */
+    invalidate: () => void;
+};
+/**
+ * One agent access token held across calls instead of re-exchanged per request.
+ *
+ * The client-credentials grant is a signed round trip to the token endpoint, and
+ * an agent identity issues the same token for the same authorization until it
+ * expires: paying for it on every command (the CLI) or every tool call (the MCP
+ * server) buys nothing. The cache key is the authorization itself — client,
+ * endpoint, and the scope/resources {@link resolveAgentApiAuthorization} settled
+ * on — so pointing a process at a second API never replays the first one's
+ * bearer.
+ */
+export declare function createCachedAgentTokenProvider(options: {
+    createError: (input: AgentTokenExchangeErrorInput) => Error;
+    createInvalidConfigError?: ((message: string) => Error) | undefined;
+    fetch?: typeof globalThis.fetch | undefined;
+    now?: (() => number) | undefined;
+}): CachedAgentTokenProvider;