@cursor/bdk 0.2.3 → 0.2.4

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

@@ -1,984 +0,0 @@
-/**
- * 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 (status === 429) {
-    const cleaned =
-      detail === undefined ? undefined : detail.replace(/\[?resource_exhausted\]?/gi, "").trim();
-    const suffix = cleaned === undefined || cleaned === "" ? "" : `: ${cleaned}`;
-    return `${label} API rate limit (429)${suffix}. Retry after the rate-limit window.`;
-  }
-  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.
-  }
-}