@cursor/bdk 0.2.1

package/src/internal/cursor/backend-client.ts

@@ -0,0 +1,978 @@
+/**
+ * Minimal Connect-JSON client for the handful of `aiserver.v1.DashboardService`
+ * RPCs agent-serve needs — `GetMe`, `ListSandMcpTools`, `ExecuteSandMcpTool`,
+ * and the login-time key lifecycle (`CreateUserApiKey`, `ListUserApiKeys`,
+ * `RevokeUserApiKey`) — plus {@link CursorBackendClient.serviceRpc} for the
+ * odd unary call on another `aiserver.v1` service under the same token.
+ *
+ * Plain `fetch` POSTs with proto-JSON bodies and zod-validated responses:
+ * agent-serve is a published package and should not pull the generated
+ * proto tree in for a few unary calls.
+ *
+ * Auth: the client holds the account API key and exchanges it on demand for
+ * a short-lived access token (`POST /auth/exchange_user_api_key`, ~1h),
+ * cached until shortly before expiry and re-exchanged once on a 401.
+ */
+
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import type { McpToolAnnotations } from "../../types.js";
+import { describeError } from "../describe-error.js";
+import { CLI_COMMAND_NAME as CLI } from "../distribution.js";
+import { boundedToolAnnotations } from "../mcp-host.js";
+import {
+  CURSOR_SESSION_EXCHANGE_PATH,
+  CursorSessionExchangeError,
+  exchangeCursorApiKeyForSession,
+  SESSION_TOKEN_EXPIRY_LEEWAY_MS,
+} from "./session-token.js";
+
+const CLIENT_VERSION = "agent-serve-0.1.0";
+const DASHBOARD_SERVICE = "DashboardService";
+const LIST_TIMEOUT_MS = 60_000;
+/** Backend-executed tools call out to third-party servers; be generous. */
+const EXECUTE_TIMEOUT_MS = 120_000;
+
+export class CursorBackendError extends Error {
+  constructor(
+    message: string,
+    readonly status?: number,
+    readonly retryAfterMs?: number,
+  ) {
+    super(message);
+    this.name = "CursorBackendError";
+  }
+}
+
+// ============================================================================
+// Response schemas (proto-JSON, camelCase; default-valued fields are omitted)
+// ============================================================================
+
+const getMeResponseSchema: z.ZodObject<
+  {
+    authId: z.ZodOptional<z.ZodString>;
+    email: z.ZodOptional<z.ZodString>;
+    firstName: z.ZodOptional<z.ZodString>;
+    lastName: z.ZodOptional<z.ZodString>;
+    teamId: z.ZodOptional<z.ZodNumber>;
+    teamName: z.ZodOptional<z.ZodString>;
+  },
+  "strip"
+> = z.object({
+  authId: z.string().optional(),
+  email: z.string().optional(),
+  firstName: z.string().optional(),
+  lastName: z.string().optional(),
+  teamId: z.number().optional(),
+  teamName: z.string().optional(),
+});
+export type CursorIdentity = z.infer<typeof getMeResponseSchema>;
+
+const createUserApiKeyResponseSchema = z.object({
+  apiKey: z.string().min(1),
+});
+
+export interface CursorGithubToken {
+  token: string;
+  expiresAt: string;
+}
+
+const githubTokenResponseSchema: z.ZodType<CursorGithubToken> = z.object({
+  token: z.string().min(1),
+  expiresAt: z.string().datetime(),
+});
+
+/**
+ * SCMs whose git fetches ride the backend's `/v0/scm-events/<provider>-git-proxy`
+ * routes. `github` is for GitHub Enterprise Server hosts an engine's egress
+ * cannot reach; github.com clones mint a token and go direct.
+ */
+export type CursorScmCloneProvider = "github" | "gitlab" | "bitbucket";
+
+const SCM_CLONE_PROVIDER_LABELS: Record<CursorScmCloneProvider, string> = {
+  github: "GitHub",
+  gitlab: "GitLab",
+  bitbucket: "Bitbucket",
+};
+
+/**
+ * Proxied clone target for a GitHub (GHES) / GitLab / Bitbucket repository.
+ * The backend never hands out the provider credential: git fetches go to
+ * `remoteUrl` on the backend with the caller's own Cursor API key as a
+ * bearer token, and the backend adds the tenant credential per request.
+ */
+export interface CursorScmCloneTarget {
+  /** Absolute `<backend>/v0/scm-events/<provider>-git-proxy/<repo>.git`. */
+  remoteUrl: string;
+  /** Bearer credential git presents to the backend (the caller's API key). */
+  token: string;
+  /** ISO timestamp after which the caller re-resolves the target. */
+  expiresAt: string;
+  username: string;
+  authMode: "bearer";
+}
+
+const scmCloneTargetResponseSchema = z.object({
+  expiresAt: z.string().datetime(),
+  clone: z.object({
+    remotePath: z.string().regex(/^\/v0\/scm-events\/[a-z]+-git-proxy\/.+\.git$/),
+    username: z.string().min(1),
+    authMode: z.literal("bearer"),
+  }),
+});
+
+const mcpToolSchema = z.object({
+  name: z.string(),
+  providerIdentifier: z.string().optional(),
+  toolName: z.string().optional(),
+  description: z.string().optional(),
+  /** `google.protobuf.Value` — an arbitrary JSON Schema object. */
+  inputSchema: z.unknown().optional(),
+  /** Flat JSON-string output schema (`output_schema_json` on the proto). */
+  outputSchemaJson: z.string().optional(),
+  /** Flat JSON-string MCP annotations (`annotations_json` on the proto). */
+  annotationsJson: z.string().optional(),
+});
+
+const getAvailableMcpServersResponseSchema = z.object({
+  servers: z
+    .array(
+      z.object({
+        id: z.number().optional(),
+        name: z.string().optional(),
+        isTeamServer: z.boolean().optional(),
+        serverIdentifier: z.string().optional(),
+      }),
+    )
+    .optional(),
+});
+
+/** One connector row from the account's dashboard MCP listing. */
+export interface AvailableMcpServer {
+  id: number;
+  name: string;
+  isTeamServer: boolean;
+  serverIdentifier?: string;
+}
+
+const checkHttpMcpStatusResponseSchema = z.object({
+  statuses: z
+    .array(
+      z.object({
+        id: z.number().optional(),
+        requiresAuth: z.boolean().optional(),
+        authUrl: z.string().optional(),
+        error: z.string().optional(),
+      }),
+    )
+    .optional(),
+});
+
+/** Per-connector OAuth status (SA-scoped when `serviceAccountId` was sent). */
+export interface McpConnectorStatus {
+  id: number;
+  requiresAuth: boolean;
+  authUrl?: string;
+  error?: string;
+}
+
+const listSandMcpToolsResponseSchema = z.object({
+  servers: z
+    .array(
+      z.object({
+        serverIdentifier: z.string(),
+        /** "connected" | "needsAuth" | "error" | "loading" */
+        status: z.string(),
+        tools: z.array(mcpToolSchema).optional(),
+      }),
+    )
+    .optional(),
+});
+
+export interface AccountMcpTool {
+  /** Fully-qualified tool name (`<server>-<tool>`), the execution key. */
+  name: string;
+  description: string;
+  /** JSON Schema for the tool input (defaulted when the server omits it). */
+  inputSchema: Record<string, unknown>;
+  /**
+   * JSON Schema for the tool's structured output. Present only when the
+   * connector's server declares one — absent stays absent (never defaulted),
+   * matching the optional MCP `Tool.outputSchema` field.
+   */
+  outputSchema?: Record<string, unknown>;
+  /**
+   * MCP spec tool annotations as the connector's server reported them,
+   * bounded to the spec fields at parse time. Absent stays absent —
+   * untrusted hints, and the fail-closed signal for consumers that classify
+   * on them (dry-run effect resolution).
+   */
+  annotations?: McpToolAnnotations;
+}
+
+export interface AccountMcpServer {
+  serverIdentifier: string;
+  status: string;
+  tools: AccountMcpTool[];
+}
+
+/**
+ * Proto-JSON of `agent.v1.McpResult` (oneof → exactly one field set).
+ * Inner strings default to `""` because proto-JSON omits default-valued
+ * fields — `McpTextContent{text: ""}` arrives as `{"text": {}}`.
+ */
+const mcpResultSchema = z.object({
+  success: z
+    .object({
+      content: z
+        .array(
+          z.object({
+            text: z.object({ text: z.string().default("") }).optional(),
+            image: z
+              .object({
+                data: z.string().default(""),
+                mimeType: z.string().optional(),
+              })
+              .optional(),
+          }),
+        )
+        .optional(),
+      isError: z.boolean().optional(),
+      structuredContent: z.record(z.unknown()).optional(),
+    })
+    .optional(),
+  error: z.object({ error: z.string().optional() }).optional(),
+  rejected: z.object({ reason: z.string().optional() }).optional(),
+  permissionDenied: z.object({ error: z.string().optional() }).optional(),
+  toolNotFound: z
+    .object({
+      name: z.string().optional(),
+      availableTools: z.array(z.string()).optional(),
+    })
+    .optional(),
+  serverNotFound: z
+    .object({
+      name: z.string().optional(),
+      availableServers: z.array(z.string()).optional(),
+    })
+    .optional(),
+});
+
+const executeResponseSchema = z.object({
+  result: mcpResultSchema.optional(),
+});
+
+/** Normalized tool-call outcome, shaped like an MCP `CallToolResult`. */
+export interface AccountMcpCallResult {
+  content: Array<
+    { type: "text"; text: string } | { type: "image"; data: string; mimeType?: string }
+  >;
+  isError: boolean;
+  structuredContent?: Record<string, unknown>;
+}
+
+// ============================================================================
+// Shared request machinery (used by the client and the login-time mint)
+// ============================================================================
+
+/** One DashboardService Connect-JSON POST; auth is the caller's bearer. */
+async function connectRpc(args: {
+  fetchImpl: typeof fetch;
+  backendUrl: string;
+  service: string;
+  method: string;
+  bearer: string;
+  body: unknown;
+  timeoutMs: number;
+  extraHeaders?: Record<string, string>;
+}): Promise<Response> {
+  try {
+    return await args.fetchImpl(`${args.backendUrl}/aiserver.v1.${args.service}/${args.method}`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${args.bearer}`,
+        "x-ghost-mode": "true",
+        "x-cursor-client-version": CLIENT_VERSION,
+        "x-cursor-client-type": "agent-serve",
+        "x-request-id": randomUUID(),
+        ...args.extraHeaders,
+      },
+      body: JSON.stringify(args.body ?? {}),
+      signal: AbortSignal.timeout(args.timeoutMs),
+    });
+  } catch (error) {
+    throw new CursorBackendError(
+      `Cursor backend request ${args.method} failed: ${describeError(error)}`,
+    );
+  }
+}
+
+/** Drain and parse an RPC response; maps non-2xx to a CursorBackendError. */
+async function parseRpcResponse(method: string, response: Response): Promise<unknown> {
+  const text = await response.text();
+  if (!response.ok) {
+    throw new CursorBackendError(
+      `Cursor backend ${method} failed (${response.status}): ${connectErrorMessage(text)}`,
+      response.status,
+    );
+  }
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    throw new CursorBackendError(`Cursor backend ${method} returned a non-JSON response.`);
+  }
+}
+
+// ============================================================================
+// Client
+// ============================================================================
+
+export interface CursorBackendClientOptions {
+  backendUrl: string;
+  apiKey: string;
+  /**
+   * Re-resolve the key on each authenticated call. Hosted freeze listens
+   * unsigned and only gains a credential at task time (hosted deliveries
+   * consume the bind file into `CURSOR_API_KEY` before authored work); a
+   * constructor-frozen key would miss that bind.
+   */
+  getApiKey?: () => string;
+  logger?: (line: string) => void;
+  /** Test seam; defaults to global fetch. */
+  fetchImpl?: typeof fetch;
+}
+
+export class CursorBackendClient {
+  private readonly backendUrl: string;
+  private readonly resolveApiKey: () => string;
+  private readonly logger: (line: string) => void;
+  private readonly fetchImpl: typeof fetch;
+  private token: { value: string; expiresAtMs: number } | undefined;
+  private tokenExchange: Promise<string> | undefined;
+  private lastExchangedApiKey: string | undefined;
+
+  constructor(options: CursorBackendClientOptions) {
+    this.backendUrl = options.backendUrl.endsWith("/")
+      ? options.backendUrl.slice(0, -1)
+      : options.backendUrl;
+    this.resolveApiKey = options.getApiKey ?? (() => options.apiKey);
+    this.logger = options.logger ?? (() => {});
+    this.fetchImpl = options.fetchImpl ?? fetch;
+  }
+
+  private currentApiKey(): string {
+    return this.resolveApiKey().trim();
+  }
+
+  /** Who this API key acts as. */
+  async getMe(): Promise<CursorIdentity> {
+    return getMeResponseSchema.parse(await this.rpc("GetMe", {}));
+  }
+
+  /**
+   * The account's MCP connectors with live status and backend-prefixed tool
+   * definitions. `serverIdentifiers` restricts discovery (empty = all
+   * HTTP/SSE servers on the account).
+   */
+  async listAccountMcpTools(serverIdentifiers: readonly string[]): Promise<AccountMcpServer[]> {
+    const raw = await this.rpc(
+      "ListSandMcpTools",
+      { serverIdentifiers: [...serverIdentifiers] },
+      LIST_TIMEOUT_MS,
+    );
+    const parsed = listSandMcpToolsResponseSchema.parse(raw);
+    return (parsed.servers ?? []).map(server => ({
+      serverIdentifier: server.serverIdentifier,
+      status: server.status,
+      tools: (server.tools ?? []).map(tool => {
+        const outputSchema = parseOutputSchemaJson(tool.outputSchemaJson);
+        const annotations = parseAnnotationsJson(tool.annotationsJson);
+        return {
+          name: tool.name,
+          description: tool.description ?? "",
+          inputSchema: normalizeInputSchema(tool.inputSchema),
+          ...(outputSchema === undefined ? {} : { outputSchema }),
+          ...(annotations === undefined ? {} : { annotations }),
+        };
+      }),
+    }));
+  }
+
+  /**
+   * Execute one connector tool **on the Cursor backend** with the account's
+   * stored OAuth credentials. `toolName` is the fully-qualified name from
+   * {@link listAccountMcpTools}.
+   */
+  async executeAccountMcpTool(args: {
+    serverIdentifier: string;
+    toolName: string;
+    args: Record<string, unknown>;
+  }): Promise<AccountMcpCallResult> {
+    const raw = await this.rpc(
+      "ExecuteSandMcpTool",
+      {
+        serverIdentifier: args.serverIdentifier,
+        toolName: args.toolName,
+        args: args.args,
+        toolCallId: randomUUID(),
+      },
+      EXECUTE_TIMEOUT_MS,
+    );
+    const parsed = executeResponseSchema.parse(raw);
+    return toCallResult(parsed.result ?? {});
+  }
+
+  /**
+   * The account's dashboard MCP connector listing (id + name per server).
+   * `teamId` pins the ambient team so team-scoped connectors resolve for
+   * multi-team accounts.
+   */
+  async getAvailableMcpServers(options?: { teamId?: number }): Promise<AvailableMcpServer[]> {
+    const raw = await this.rpc("GetAvailableMcpServers", {}, LIST_TIMEOUT_MS, {
+      teamId: options?.teamId,
+    });
+    const parsed = getAvailableMcpServersResponseSchema.parse(raw);
+    return (parsed.servers ?? [])
+      .filter(server => server.id !== undefined && server.id > 0)
+      .map(server => ({
+        id: server.id!,
+        name: server.name ?? "",
+        isTeamServer: server.isTeamServer === true,
+        serverIdentifier: server.serverIdentifier,
+      }));
+  }
+
+  /**
+   * Probe connectors and mint OAuth `authUrl`s where authorization is
+   * needed. With `serviceAccountId`, this is the dashboard Authenticate
+   * flow for a hosted deployment's service account. Omit it to probe the
+   * signed-in user (local `serve` preflight).
+   */
+  async checkHttpMcpStatus(args: {
+    serverIds: number[];
+    oauthRedirectUri: string;
+    serviceAccountId?: string;
+  }): Promise<McpConnectorStatus[]> {
+    const raw = await this.rpc(
+      "CheckHttpMcpStatus",
+      {
+        serverIds: args.serverIds,
+        oauthRedirectUri: args.oauthRedirectUri,
+        serviceAccountId: args.serviceAccountId,
+      },
+      LIST_TIMEOUT_MS,
+    );
+    const parsed = checkHttpMcpStatusResponseSchema.parse(raw);
+    return (parsed.statuses ?? []).map(status => ({
+      id: status.id ?? 0,
+      requiresAuth: status.requiresAuth === true,
+      authUrl: status.authUrl,
+      error: status.error,
+    }));
+  }
+
+  /** Mint a short-lived GitHub token scoped to the requested repositories. */
+  async getGithubToken(
+    repos: readonly string[],
+    options?: { permissions?: "read" | "pr-write" | "contents-write" },
+  ): Promise<CursorGithubToken> {
+    const permissions = options?.permissions ?? "pr-write";
+    let response: Response;
+    try {
+      response = await this.fetchImpl(`${this.backendUrl}/v0/scm-events/github-token`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${this.currentApiKey()}`,
+        },
+        body: JSON.stringify({ repos: [...repos], permissions }),
+        signal: AbortSignal.timeout(30_000),
+      });
+    } catch (error) {
+      throw new CursorBackendError(
+        `Cursor GitHub credential request failed: ${describeError(error)}`,
+      );
+    }
+    const text = await response.text();
+    if (!response.ok) {
+      throw new CursorBackendError(
+        describeGithubTokenHttpFailure(response.status, text),
+        response.status,
+        retryAfterMsFromResponse(response),
+      );
+    }
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(text) as unknown;
+    } catch {
+      throw new CursorBackendError(
+        "Cursor backend returned a non-JSON GitHub credential response.",
+      );
+    }
+    return githubTokenResponseSchema.parse(parsed);
+  }
+
+  /**
+   * Resolve the proxied clone target for a GitHub (GHES) / GitLab /
+   * Bitbucket repository (`owner/name`; GitLab `path_with_namespace`). Same
+   * authorization as the provider proxy this host already calls; the
+   * returned remote lives on the backend and takes this client's API key,
+   * never a provider token.
+   */
+  async getScmCloneTarget(
+    provider: CursorScmCloneProvider,
+    repo: string,
+  ): Promise<CursorScmCloneTarget> {
+    const label = SCM_CLONE_PROVIDER_LABELS[provider];
+    let response: Response;
+    try {
+      response = await this.fetchImpl(`${this.backendUrl}/v0/scm-events/${provider}-clone-target`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${this.currentApiKey()}`,
+        },
+        body: JSON.stringify({ repo }),
+        signal: AbortSignal.timeout(30_000),
+      });
+    } catch (error) {
+      throw new CursorBackendError(
+        `Cursor ${label} clone target request failed: ${describeError(error)}`,
+      );
+    }
+    const text = await response.text();
+    if (!response.ok) {
+      throw new CursorBackendError(
+        describeGithubTokenHttpFailure(response.status, text, label),
+        response.status,
+        retryAfterMsFromResponse(response),
+      );
+    }
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(text) as unknown;
+    } catch {
+      throw new CursorBackendError(
+        `Cursor backend returned a non-JSON ${label} clone target response.`,
+      );
+    }
+    const body = scmCloneTargetResponseSchema.parse(parsed);
+    return {
+      remoteUrl: `${this.backendUrl}${body.clone.remotePath}`,
+      token: this.currentApiKey(),
+      expiresAt: body.expiresAt,
+      username: body.clone.username,
+      authMode: body.clone.authMode,
+    };
+  }
+
+  /**
+   * One unary Connect-JSON call on `aiserver.v1.<service>` with the same
+   * token exchange and 401 retry as the dashboard RPCs. Callers parse the
+   * proto-JSON response themselves.
+   */
+  serviceRpc(
+    service: string,
+    method: string,
+    body: unknown,
+    timeoutMs: number = LIST_TIMEOUT_MS,
+  ): Promise<unknown> {
+    return this.rpc(method, body, timeoutMs, { service });
+  }
+
+  private async rpc(
+    method: string,
+    body: unknown,
+    timeoutMs = LIST_TIMEOUT_MS,
+    options?: { teamId?: number; service?: string },
+  ): Promise<unknown> {
+    const service = options?.service ?? DASHBOARD_SERVICE;
+    const extraHeaders =
+      options?.teamId === undefined ? undefined : { "x-cursor-team-id": String(options.teamId) };
+    const bearer = await this.getAccessToken();
+    const first = await connectRpc({
+      fetchImpl: this.fetchImpl,
+      backendUrl: this.backendUrl,
+      service,
+      method,
+      bearer,
+      body,
+      timeoutMs,
+      extraHeaders,
+    });
+    if (first.status !== 401) {
+      return parseRpcResponse(method, first);
+    }
+    // The token aged out server-side. Drain the rejected body (keeps the
+    // connection reusable), drop the token — unless a concurrent retry
+    // already minted a newer one — and retry once.
+    await drainResponseBody(first);
+    if (this.token?.value === bearer) {
+      this.token = undefined;
+    }
+    const retryBearer = await this.getAccessToken();
+    const second = await connectRpc({
+      fetchImpl: this.fetchImpl,
+      backendUrl: this.backendUrl,
+      service,
+      method,
+      bearer: retryBearer,
+      body,
+      timeoutMs,
+      extraHeaders,
+    });
+    if (second.status === 401 && this.token?.value === retryBearer) {
+      // The freshly minted token was rejected too; do not keep serving it.
+      this.token = undefined;
+    }
+    return parseRpcResponse(method, second);
+  }
+
+  /**
+   * Serve a cached access token for the account, exchanging the API key
+   * when none is cached or it is near expiry.
+   */
+  private getAccessToken(): Promise<string> {
+    const apiKey = this.currentApiKey();
+    if (apiKey === "") {
+      return Promise.reject(
+        new CursorBackendError(
+          "The Cursor backend client has no API key yet. Bind CURSOR_API_KEY or CURSOR_API_KEY_FILE before authenticated calls.",
+        ),
+      );
+    }
+    if (this.lastExchangedApiKey !== apiKey) {
+      this.token = undefined;
+      this.tokenExchange = undefined;
+    }
+    if (
+      this.token !== undefined &&
+      Date.now() < this.token.expiresAtMs - SESSION_TOKEN_EXPIRY_LEEWAY_MS
+    ) {
+      return Promise.resolve(this.token.value);
+    }
+    // Single-flight: concurrent tool calls share one exchange.
+    if (this.tokenExchange === undefined) {
+      this.tokenExchange = this.exchangeApiKey().finally(() => {
+        this.tokenExchange = undefined;
+      });
+    }
+    return this.tokenExchange;
+  }
+
+  private async exchangeApiKey(): Promise<string> {
+    const apiKey = this.currentApiKey();
+    let session: { token: string; expiresAtMs: number };
+    try {
+      session = await exchangeCursorApiKeyForSession({
+        exchangeUrl: `${this.backendUrl}${CURSOR_SESSION_EXCHANGE_PATH}`,
+        apiKey,
+        fetchImpl: this.fetchImpl,
+      });
+    } catch (error) {
+      if (error instanceof CursorSessionExchangeError) {
+        if (error.status === undefined) {
+          throw new CursorBackendError(
+            `Could not reach the Cursor backend at ${this.backendUrl}: ${error.message}`,
+          );
+        }
+        if (error.status >= 200 && error.status < 300) {
+          // 2xx without a token in the body.
+          throw new CursorBackendError("Cursor API key exchange returned no access token.");
+        }
+        throw new CursorBackendError(
+          error.status === 401
+            ? `The Cursor API key was rejected. Run \`${CLI} login\` again or update CURSOR_API_KEY.`
+            : `Cursor API key exchange failed (${error.status}).`,
+          error.status,
+        );
+      }
+      throw error;
+    }
+    this.token = { value: session.token, expiresAtMs: session.expiresAtMs };
+    this.lastExchangedApiKey = apiKey;
+    this.logger("[agent-sdk] cursor account: minted a fresh access token");
+    return session.token;
+  }
+}
+
+/**
+ * Mint a named user API key from a short-lived login session token. Used
+ * exactly once per `agent-sdk login`; the session token is then discarded.
+ */
+export async function createUserApiKeyWithSessionToken(args: {
+  backendUrl: string;
+  sessionToken: string;
+  keyName: string;
+  fetchImpl?: typeof fetch;
+}): Promise<string> {
+  const response = await connectRpc({
+    fetchImpl: args.fetchImpl ?? fetch,
+    backendUrl: args.backendUrl.endsWith("/") ? args.backendUrl.slice(0, -1) : args.backendUrl,
+    service: DASHBOARD_SERVICE,
+    method: "CreateUserApiKey",
+    bearer: args.sessionToken,
+    body: { name: args.keyName },
+    timeoutMs: 30_000,
+  });
+  const raw = await parseRpcResponse("CreateUserApiKey", response);
+  return createUserApiKeyResponseSchema.parse(raw).apiKey;
+}
+
+const API_KEY_PREFIX = "crsr_";
+
+/** Matches dashboard `maskApiKey` (`crsr_...abcd`). */
+function maskApiKey(apiKey: string): string {
+  return `${API_KEY_PREFIX}...${apiKey.slice(-4)}`;
+}
+
+const listUserApiKeysResponseSchema = z.object({
+  apiKeys: z
+    .array(
+      z.object({
+        id: z.number(),
+        name: z.string(),
+        maskedKey: z.string().optional(),
+      }),
+    )
+    .optional(),
+});
+
+/**
+ * Best-effort cleanup when `login` mints a key but fails before storing it,
+ * authenticated with the browser session token that minted it. The key is
+ * identified by its masked suffix in `ListUserApiKeys` — never by name alone,
+ * so replica lag after `CreateUserApiKey` can only skip the cleanup, not
+ * revoke an older same-named key.
+ */
+export async function revokeMintedUserApiKey(args: {
+  backendUrl: string;
+  keyName: string;
+  /** The raw minted key; selects the exact list row via `maskedKey`. */
+  apiKey: string;
+  /** Session token from the PKCE login; the bearer for list + revoke. */
+  sessionToken: string;
+  fetchImpl?: typeof fetch;
+}): Promise<void> {
+  const fetchImpl = args.fetchImpl ?? fetch;
+  const backendUrl = args.backendUrl.endsWith("/") ? args.backendUrl.slice(0, -1) : args.backendUrl;
+
+  const listResponse = await connectRpc({
+    fetchImpl,
+    backendUrl,
+    service: DASHBOARD_SERVICE,
+    method: "ListUserApiKeys",
+    bearer: args.sessionToken,
+    body: {},
+    timeoutMs: 30_000,
+  });
+  const listed = listUserApiKeysResponseSchema.parse(
+    await parseRpcResponse("ListUserApiKeys", listResponse),
+  );
+  const masked = maskApiKey(args.apiKey);
+  const match = (listed.apiKeys ?? []).find(
+    key => key.name === args.keyName && key.maskedKey === masked,
+  );
+  if (match === undefined) {
+    // CreateUserApiKey writes the primary while ListUserApiKeys may read a
+    // lagging replica — skip rather than touch any other key.
+    return;
+  }
+  const revokeResponse = await connectRpc({
+    fetchImpl,
+    backendUrl,
+    service: DASHBOARD_SERVICE,
+    method: "RevokeUserApiKey",
+    bearer: args.sessionToken,
+    body: { id: match.id },
+    timeoutMs: 30_000,
+  });
+  await drainResponseBody(revokeResponse);
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+function safeJsonParse(text: string): unknown {
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    return undefined;
+  }
+}
+
+function normalizeInputSchema(schema: unknown): Record<string, unknown> {
+  if (typeof schema === "object" && schema !== null && !Array.isArray(schema)) {
+    return schema as Record<string, unknown>;
+  }
+  return { type: "object", properties: {} };
+}
+
+/**
+ * Parse the proto's flat-JSON-string output schema. Unlike
+ * {@link normalizeInputSchema} there is no fallback: outputSchema is optional
+ * on the MCP wire, so absence (or malformed JSON crossing the backend
+ * boundary) means omitted.
+ */
+function parseOutputSchemaJson(
+  outputSchemaJson: string | undefined,
+): Record<string, unknown> | undefined {
+  if (outputSchemaJson === undefined) {
+    return undefined;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(outputSchemaJson);
+  } catch {
+    return undefined;
+  }
+  return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
+    ? (parsed as Record<string, unknown>)
+    : undefined;
+}
+
+/**
+ * Parse the flat JSON-string annotations off the wire and bound them to the
+ * MCP-spec fields. Malformed or non-object payloads behave like absent ones,
+ * so readers fail closed.
+ */
+function parseAnnotationsJson(annotationsJson: string | undefined): McpToolAnnotations | undefined {
+  if (annotationsJson === undefined) {
+    return undefined;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(annotationsJson);
+  } catch {
+    return undefined;
+  }
+  return boundedToolAnnotations(parsed);
+}
+
+type McpResultJson = z.infer<typeof mcpResultSchema>;
+
+function toCallResult(result: McpResultJson): AccountMcpCallResult {
+  if (result.success !== undefined) {
+    const content: AccountMcpCallResult["content"] = [];
+    for (const item of result.success.content ?? []) {
+      if (item.text !== undefined) {
+        content.push({ type: "text", text: item.text.text });
+      } else if (item.image !== undefined) {
+        content.push({
+          type: "image",
+          data: item.image.data,
+          ...(item.image.mimeType === undefined ? {} : { mimeType: item.image.mimeType }),
+        });
+      }
+    }
+    return {
+      content,
+      isError: result.success.isError === true,
+      ...(result.success.structuredContent === undefined
+        ? {}
+        : { structuredContent: result.success.structuredContent }),
+    };
+  }
+  return {
+    content: [{ type: "text", text: describeFailure(result) }],
+    isError: true,
+  };
+}
+
+function describeFailure(result: McpResultJson): string {
+  if (result.error !== undefined) {
+    return result.error.error ?? "The tool call failed.";
+  }
+  if (result.permissionDenied !== undefined) {
+    return result.permissionDenied.error ?? "Permission denied.";
+  }
+  if (result.rejected !== undefined) {
+    return `The tool call was rejected${
+      result.rejected.reason === undefined ? "" : `: ${result.rejected.reason}`
+    }.`;
+  }
+  if (result.toolNotFound !== undefined) {
+    return `Unknown tool "${result.toolNotFound.name ?? ""}". Available: ${
+      (result.toolNotFound.availableTools ?? []).join(", ") || "(none)"
+    }.`;
+  }
+  if (result.serverNotFound !== undefined) {
+    return `Unknown MCP server "${result.serverNotFound.name ?? ""}". Available: ${
+      (result.serverNotFound.availableServers ?? []).join(", ") || "(none)"
+    }.`;
+  }
+  return "The tool call returned no result.";
+}
+
+/** Best-effort human-readable message from a Connect error JSON body. */
+function connectErrorMessage(bodyText: string): string {
+  const parsed = safeJsonParse(bodyText);
+  if (
+    typeof parsed === "object" &&
+    parsed !== null &&
+    typeof (parsed as { message?: unknown }).message === "string" &&
+    (parsed as { message: string }).message !== ""
+  ) {
+    return (parsed as { message: string }).message;
+  }
+  return bodyText.slice(0, 300) || "(empty response body)";
+}
+
+const MAX_GITHUB_TOKEN_RETRY_AFTER_MS = 60 * 60_000;
+
+/**
+ * Prefer the backend's actionable denial message. Only a true 401 on this
+ * route means the Cursor API key itself was rejected — GitHub-connection
+ * problems arrive as 403 with a server `error` string.
+ */
+function describeGithubTokenHttpFailure(
+  status: number,
+  bodyText: string,
+  label = "GitHub",
+): string {
+  const detail = githubTokenErrorFromBody(bodyText);
+  if (status === 401) {
+    return `The Cursor API key was rejected${
+      detail === undefined ? "" : `: ${detail}`
+    }. Run \`${CLI} login\` again or update CURSOR_API_KEY.`;
+  }
+  if (detail !== undefined) {
+    return detail;
+  }
+  return `Cursor ${label} credential request failed (${status}).`;
+}
+
+function githubTokenErrorFromBody(bodyText: string): string | undefined {
+  const parsed = safeJsonParse(bodyText);
+  if (typeof parsed !== "object" || parsed === null) {
+    return undefined;
+  }
+  const error = (parsed as { error?: unknown }).error;
+  if (typeof error === "string" && error !== "") {
+    return error;
+  }
+  const message = (parsed as { message?: unknown }).message;
+  if (typeof message === "string" && message !== "") {
+    return message;
+  }
+  return undefined;
+}
+
+function retryAfterMsFromResponse(response: Response): number | undefined {
+  const retryAfter = Number(response.headers.get("retry-after") ?? "");
+  if (!Number.isFinite(retryAfter) || retryAfter <= 0) {
+    return undefined;
+  }
+  return Math.min(retryAfter * 1000, MAX_GITHUB_TOKEN_RETRY_AFTER_MS);
+}
+
+/** Release undici/fetch connection slots on responses we will not parse. */
+async function drainResponseBody(response: Response): Promise<void> {
+  try {
+    await response.arrayBuffer();
+  } catch {
+    // Best-effort; the socket may already be closed.
+  }
+}