cartethyia 2.4.6 → 2.5.0

package/src/providers/integrations/commandcode/discovery.ts

@@ -0,0 +1,116 @@
+/**
+ * Command Code model discovery, read from the Provider API.
+ *
+ * The adapter used to carry a hand-copied list of 36 ids with no limits and one
+ * wire for all of them. The Provider API publishes the real roster — 95 rows,
+ * each stating `context_length` and `supported_endpoints` — so this replaces
+ * that snapshot with what the provider actually serves.
+ *
+ * Two facts the snapshot could not express, and both change what is routable:
+ *
+ *   * Every `claude-*` id is served on `/messages` only. A catalog that filed
+ *     them as chat posted to an endpoint that does not answer them, so all nine
+ *     were unusable.
+ *
+ *   * Many ids also serve `/responses`. The wire is chosen per model from
+ *     `supported_endpoints`, which is the provider's own advertisement, rather
+ *     than guessed from the id.
+ *
+ * `:free` is deliberately NOT read as a free tier here. Verified against the
+ * live API: `minimax/minimax-m3.1-flash-preview:free`, `stealth/cat-jam:free`,
+ * `stealth/glyph-cluster:free` and `reflection/beam:free` all answer 400
+ * "insufficient credits" on an account whose `freeCredits` is 0. The suffix is
+ * part of the upstream id, not a pricing statement — the opposite of
+ * OpenRouter, Kilo and Cline, where `:free` is the tier. Marking it here would
+ * publish paid models as free, which is the defect fixed on Cline.
+ */
+import type { ModelDefinition } from "../../provider-model-definition";
+import { isRecord } from "../../../protocol/codecs";
+import { boundedUpstreamNumber, sanitizeUpstreamLabel } from "../../provider-sanitize";
+import type { ProviderModelDiscovery } from "../../discovery/discovery-types";
+import { defineModel } from "../../provider-model-definition";
+import { COMMANDCODE_PROVIDER_ID } from "./commandcode";
+
+/** The Provider API's OpenAI-shaped model listing. */
+export const COMMANDCODE_MODELS_PATH = "/models" as const;
+
+/** The route that selects the OpenAI Responses wire when a model lists it. */
+const RESPONSES_ENDPOINT = "/responses" as const;
+const ANTHROPIC_MESSAGES_ENDPOINT = "/messages" as const;
+
+const MAX_CONTEXT = 1_000_000_000;
+
+/**
+ * The wire a model is served on.
+ *
+ * `claude-*` answers `/messages` only. Everything else answers
+ * `/chat/completions`, and adds `/responses` when the listing advertises it.
+ * Without endpoint metadata a model keeps chat, which every non-Claude model
+ * serves, so a listing that omits the field never breaks.
+ */
+export function commandCodeWireFor(
+  modelId: string,
+  supportedEndpoints?: readonly string[],
+): { readonly wireFamily: "messages" | "responses" | "chat"; readonly endpointPath: string } {
+  if (modelId.startsWith("claude-")) {
+    return { wireFamily: "messages", endpointPath: ANTHROPIC_MESSAGES_ENDPOINT };
+  }
+  if (supportedEndpoints?.includes(RESPONSES_ENDPOINT)) {
+    return { wireFamily: "responses", endpointPath: RESPONSES_ENDPOINT };
+  }
+  return { wireFamily: "chat", endpointPath: "/chat/completions" };
+}
+
+/** Reads `supported_endpoints` tolerantly — unknown rows keep the chat wire. */
+function endpointList(value: unknown): readonly string[] {
+  if (!Array.isArray(value)) return [];
+  return value.filter((entry): entry is string => typeof entry === "string");
+}
+
+export const discoverCommandCodeModels: ProviderModelDiscovery = async (
+  input,
+): Promise<readonly ModelDefinition[] | null> => {
+  const fetcher = input.fetcher ?? fetch;
+  const signal = AbortSignal.timeout(10_000);
+  try {
+    const base = input.baseUrl.replace(/\/+$/, "");
+    const response = await fetcher(`${base}${COMMANDCODE_MODELS_PATH}`, {
+      headers: { accept: "application/json", authorization: `Bearer ${input.credential}` },
+      signal,
+    });
+    if (!response.ok) return null;
+    const body: unknown = await response.json();
+    if (!isRecord(body)) return null;
+    const rows = Array.isArray(body["data"]) ? body["data"] : [];
+    const byId = new Map<string, ModelDefinition>();
+    for (const row of rows) {
+      if (!isRecord(row)) continue;
+      const id = sanitizeUpstreamLabel(row["id"]);
+      if (id === undefined) continue;
+      const contextLimit = boundedUpstreamNumber(row["context_length"], { min: 1, max: MAX_CONTEXT });
+      const { wireFamily, endpointPath } = commandCodeWireFor(
+        id,
+        endpointList(row["supported_endpoints"]),
+      );
+      byId.set(
+        id,
+        defineModel({
+          id,
+          providerId: COMMANDCODE_PROVIDER_ID,
+          wireFamily,
+          endpoint: endpointPath,
+          // `null` when the row states no limit, which is not a guess: the
+          // routing ladder keeps its own fallback.
+          ctx: contextLimit ?? null,
+          reasoning: true,
+          toolCall: true,
+          vision: true,
+        }),
+      );
+    }
+    if (byId.size === 0) return null;
+    return [...byId.values()].sort((a, b) => a.modelId.localeCompare(b.modelId));
+  } catch {
+    return null;
+  }
+};

package/src/providers/integrations/commandcode/quota.ts

@@ -0,0 +1,160 @@
+/**
+ * Command Code quota, read from the four billing endpoints its client reads.
+ *
+ * Command Code bills in credits, not in rate-limit windows, so a quota row here
+ * is a credit balance rather than a 5-hour/weekly pair. The shape the console
+ * renders still expects windows, so the balance is reported as one independent
+ * window — the honest reading, since credits are the only thing consumed.
+ *
+ * The endpoints, all on `https://api.commandcode.ai` (not the Provider API
+ * origin the model catalog lives on):
+ *
+ *   `/alpha/whoami`                  identity, and the `orgId` when one exists
+ *   `/alpha/billing/credits`         the balance and any window limits
+ *   `/alpha/billing/subscriptions`   the plan, when there is one
+ *   `/alpha/usage/summary`           spend in the period, for context
+ *
+ * Every call is optional to the result: a failure reports what is still known
+ * rather than failing the whole read, because an operator who can see a zero
+ * balance has already got the answer even if the usage summary never came back.
+ */
+import type { FetchLike, ProviderQuotaResult, ProviderQuotaWindow } from "../../quota/quota-contracts";
+
+const COMMANDCODE_API_BASE = "https://api.commandcode.ai" as const;
+const REQUEST_TIMEOUT_MS = 15_000;
+
+interface RequestOk {
+  readonly ok: true;
+  readonly value: unknown;
+}
+interface RequestFailed {
+  readonly ok: false;
+}
+type RequestResult = RequestOk | RequestFailed;
+
+async function readJson(
+  path: string,
+  credential: string,
+  fetcher: FetchLike,
+): Promise<RequestResult> {
+  try {
+    const response = await fetcher(`${COMMANDCODE_API_BASE}${path}`, {
+      method: "GET",
+      headers: { accept: "application/json", authorization: `Bearer ${credential}` },
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    if (!response.ok) return { ok: false };
+    return { ok: true, value: await response.json() };
+  } catch {
+    return { ok: false };
+  }
+}
+
+function recordValue(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+function numberOrNull(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+/** The credit block: three balances that are summed, plus any window limits. */
+function creditWindow(credits: Record<string, unknown>): ProviderQuotaWindow | null {
+  const monthly = numberOrNull(credits["monthlyCredits"]) ?? 0;
+  const purchased = numberOrNull(credits["purchasedCredits"]) ?? 0;
+  const free = numberOrNull(credits["freeCredits"]) ?? 0;
+  const remaining = monthly + purchased + free;
+  // Command Code reports no ceiling for a credit balance, so there is no
+  // percentage to compute — unlike a rate-limit window, where the upstream
+  // states both sides. Reporting null is the truthful answer.
+  return {
+    kind: "credits",
+    label: "Credits",
+    accounting: "independent",
+    usedPercent: null,
+    remainingPercent: null,
+    resetsAt: null,
+    remaining,
+  };
+}
+
+function windowLimits(
+  limits: Record<string, unknown>,
+): readonly ProviderQuotaWindow[] {
+  const out: ProviderQuotaWindow[] = [];
+  const fiveHour = recordValue(limits["fiveHour"]);
+  const weekly = recordValue(limits["weekly"]);
+  const push = (source: Record<string, unknown> | undefined, kind: string, label: string) => {
+    if (source === undefined) return;
+    out.push({
+      kind,
+      label,
+      accounting: "independent",
+      usedPercent: numberOrNull(source["usedPercent"]),
+      remainingPercent: numberOrNull(source["remainingPercent"]),
+      resetsAt: typeof source["resetsAt"] === "string" ? source["resetsAt"] : null,
+      remaining: numberOrNull(source["remaining"]),
+    });
+  };
+  push(fiveHour, "five_hour", "5 Hour");
+  push(weekly, "weekly", "Weekly");
+  return out;
+}
+
+export async function fetchCommandCodeQuota(
+  credential: string,
+  fetcher: FetchLike,
+): Promise<ProviderQuotaResult> {
+  const source = "commandcode";
+  const [whoami, creditsRaw, subscriptionRaw] = await Promise.all([
+    readJson("/alpha/whoami", credential, fetcher),
+    readJson("/alpha/billing/credits", credential, fetcher),
+    readJson("/alpha/billing/subscriptions", credential, fetcher),
+  ]);
+  if (!whoami.ok && !creditsRaw.ok) {
+    return {
+      source,
+      plan: null,
+      windows: [],
+      error: "Command Code did not answer its billing endpoints",
+    };
+  }
+
+  const whoamiBody = whoami.ok ? recordValue(whoami.value) : undefined;
+  const user = recordValue(whoamiBody?.["user"]);
+  const accountLabel =
+    (typeof user?.["email"] === "string" && user["email"]) ||
+    (typeof user?.["userName"] === "string" && user["userName"]) ||
+    undefined;
+
+  const creditsBody = creditsRaw.ok ? recordValue(creditsRaw.value) : undefined;
+  const windows: ProviderQuotaWindow[] = [];
+  if (creditsBody !== undefined) {
+    const credits = recordValue(creditsBody["credits"]);
+    if (credits !== undefined) {
+      const window = creditWindow(credits);
+      if (window !== null) windows.push(window);
+    }
+    const limits = recordValue(creditsBody["windowLimits"]);
+    if (limits !== undefined) windows.push(...windowLimits(limits));
+  }
+
+  const subscriptionBody = subscriptionRaw.ok ? recordValue(subscriptionRaw.value) : undefined;
+  const planRecord = recordValue(subscriptionBody?.["data"]);
+  const plan =
+    typeof planRecord?.["name"] === "string"
+      ? planRecord["name"]
+      : creditsRaw.ok
+        ? "Credits"
+        : null;
+
+  return {
+    source,
+    plan,
+    windows,
+    error: null,
+    ...(accountLabel === undefined ? {} : { accountLabel }),
+  };
+}

package/src/providers/integrations/cursor/cursor-auth.ts

@@ -0,0 +1,418 @@
+/**
+ * Cursor OAuth client and token refresher.
+ *
+ * Cursor's login is its own PKCE device flow, not RFC 8628: the verifier and a
+ * UUID are generated locally, the operator opens a `loginDeepControl` URL in a
+ * browser, and the gateway polls `/auth/poll` until the tokens land. There is no
+ * user code — approval is bound to the browser session — so `userCode` is empty
+ * and the private verifier rides in `providerState`, which the console persists
+ * server-side and never returns to the browser.
+ *
+ * Two credential families reach dispatch:
+ *
+ * - **Browser session** (`/oauth/token` refresh grant, as Cursor's IDE performs
+ *   it). A rejected token is not an HTTP error: Cursor answers 200 with
+ *   `{"access_token":"","shouldLogout":true}`, so the body decides the outcome.
+ * - **Raw API key** (`crsr_`, exchanged at `/auth/exchange_user_api_key`). The
+ *   exchanged JWT is the dispatch secret; the raw key is kept in the encrypted
+ *   refresh field so the refresher can re-exchange it, which is how Cursor CLI
+ *   renews an API-key login.
+ *
+ * A raw key never reaches `auth_state` and is never logged: `auth_state` is
+ * operator-visible in the console.
+ */
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import { OAuthDeviceFlow } from "../../authentication/oauth-device-flow";
+import type {
+  OAuthDeviceFlowContext,
+  OAuthDevicePollResult,
+  OAuthDeviceStartResult,
+  OAuthExchangeResult,
+  OAuthImportInput,
+  OAuthLoginField,
+} from "../../authentication/oauth-flow-store";
+import { base64UrlEncode, nonEmptyTrimmedString, record } from "../../authentication/oauth-flow-store";
+import type { FetchLike } from "../../authentication/oauth-client";
+import type { OAuthRefreshContext, OAuthTokenRefreshResult } from "../../authentication/oauth-refresh-service";
+import {
+  AUTH_REQUEST_TIMEOUT_MS,
+  CURSOR_API_BASE_URL,
+  CURSOR_OAUTH_CLIENT_ID,
+  CURSOR_WEBSITE_URL,
+  SESSION_REFRESH_TIMEOUT_MS,
+  SIGN_IN_POLICY_VIOLATION,
+  TOKEN_EXPIRY_THRESHOLD_S,
+  isExchangeableApiKey,
+} from "./cursor-shared";
+
+/** Device authorizations live 5 minutes before the flow is abandoned. */
+const DEVICE_EXPIRY_SECONDS = 300;
+/** Dashboard poll cadence for the device authorization. */
+const DEVICE_INTERVAL_SECONDS = 5;
+/** Token lifetime assumed when the upstream omits every expiry hint. */
+const EXPIRY_FALLBACK_MS = 30 * 24 * 60 * 60 * 1000;
+
+/** Fields the import flow collects: one raw Cursor API key. */
+const IMPORT_FIELDS: readonly OAuthLoginField[] = [
+  {
+    key: "credential",
+    label: "Cursor API key",
+    placeholder: "crsr_…",
+    secret: true,
+    required: true,
+  },
+];
+
+function base64urlDecode(segment: string): string | undefined {
+  try {
+    return Buffer.from(segment, "base64url").toString("utf8");
+  } catch {
+    return undefined;
+  }
+}
+
+/** Decodes a JWT payload without verifying; the trust boundary stays at TLS. */
+export function decodeJwtPayload(token: string): Record<string, unknown> | undefined {
+  const segment = token.split(".")[1];
+  if (segment === undefined) return undefined;
+  const json = base64urlDecode(segment);
+  if (json === undefined) return undefined;
+  try {
+    return record(JSON.parse(json) as unknown);
+  } catch {
+    return undefined;
+  }
+}
+
+/** JWT `exp` claim as epoch milliseconds, or `undefined` when absent/malformed. */
+export function decodeJwtExpiryMs(token: string): number | undefined {
+  const payload = decodeJwtPayload(token);
+  const exp = payload?.["exp"];
+  if (typeof exp !== "number" || !Number.isFinite(exp)) return undefined;
+  return exp * 1000;
+}
+
+/** True when a JWT expires within the refresh threshold. */
+export function isExpiringSoon(token: string, thresholdSeconds = TOKEN_EXPIRY_THRESHOLD_S): boolean {
+  const expiry = decodeJwtExpiryMs(token);
+  if (expiry === undefined) return false;
+  return expiry - Date.now() < thresholdSeconds * 1000;
+}
+
+/**
+ * The account identity Cursor itself asserts, from the access token's `sub`.
+ *
+ * Cursor publishes no email on this grant, so the login used to fall back to the
+ * provider id — every account of the provider then looked identical, and adding
+ * a second one replaced the first. `sub` (`auth0|user_01…`) is stable across
+ * every login of one account and differs between accounts, which is exactly
+ * what an account identity has to do.
+ */
+export function cursorAccountIdentity(token: string): string | undefined {
+  const payload = decodeJwtPayload(token);
+  const subject = payload?.["sub"];
+  return typeof subject === "string" && subject.trim().length > 0 ? subject.trim() : undefined;
+}
+
+/** Private device-flow state. Never returned to the browser. */
+interface CursorDeviceState {
+  readonly verifier: string;
+}
+
+function parseDeviceState(value: string | undefined): CursorDeviceState | undefined {
+  if (value === undefined || value.length === 0) return undefined;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(value) as unknown;
+  } catch {
+    return undefined;
+  }
+  const root = record(parsed);
+  const verifier = root === undefined ? undefined : nonEmptyTrimmedString(root["verifier"]);
+  return verifier === undefined ? undefined : { verifier };
+}
+
+/** Minimal fetch surface accepted by the token request helpers. */
+type FetchFn = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+
+/** The base OAuth client's fetch surface; widened to `FetchFn` at each call. */
+function asFetchFn(fetchFn: FetchLike): FetchFn {
+  // Structural identity: the base class's `FetchLike` is the same signature as
+  // `FetchFn`, so this only reconciles the two declarations.
+  return fetchFn as FetchFn;
+}
+
+type JsonOutcome =
+  | { ok: true; body: Record<string, unknown>; status: number }
+  | { ok: false; status?: number; message: string };
+
+async function fetchJson(
+  fetchFn: FetchFn,
+  url: string,
+  init: RequestInit,
+  timeoutMs: number,
+  label: string,
+): Promise<JsonOutcome> {
+  let response: Response;
+  try {
+    response = await fetchFn(url, {
+      ...init,
+      signal: signalOrTimeout(init.signal, timeoutMs),
+    });
+  } catch (error) {
+    return {
+      ok: false,
+      message: `${label} request failed: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+  const text = await response.text().catch(() => "");
+  let body: Record<string, unknown> | undefined;
+  try {
+    body = record(JSON.parse(text) as unknown) ?? undefined;
+  } catch {
+    body = undefined;
+  }
+  if (!response.ok) {
+    return {
+      ok: false,
+      status: response.status,
+      message: `${label} failed (${response.status}): ${text.slice(0, 200)}`,
+    };
+  }
+  if (body === undefined) {
+    return { ok: false, status: response.status, message: `${label} returned malformed JSON` };
+  }
+  return { ok: true, body, status: response.status };
+}
+
+/** Composes an outer signal with a bounded timeout; absent signal → timeout alone. */
+function signalOrTimeout(signal: AbortSignal | null | undefined, timeoutMs: number): AbortSignal {
+  const timeout = AbortSignal.timeout(timeoutMs);
+  return signal === null || signal === undefined ? timeout : AbortSignal.any([signal, timeout]);
+}
+
+/**
+ * Exchanges a raw `crsr_` key for a short-lived JWT.
+ *
+ * Also how an API-key login is renewed: Cursor CLI re-runs the exchange and
+ * never uses the refresh token the response carries.
+ */
+async function exchangeApiKey(
+  fetchFn: FetchFn,
+  apiKey: string,
+): Promise<{ accessToken: string; refreshToken: string; expiresAt: Date }> {
+  const outcome = await fetchJson(
+    fetchFn,
+    `${CURSOR_API_BASE_URL}/auth/exchange_user_api_key`,
+    {
+      method: "POST",
+      headers: { "content-type": "application/json", authorization: `Bearer ${apiKey}` },
+      body: "{}",
+    },
+    AUTH_REQUEST_TIMEOUT_MS,
+    "Cursor API key exchange",
+  );
+  if (!outcome.ok) throw new Error(outcome.message);
+  const accessToken = nonEmptyTrimmedString(outcome.body["accessToken"]);
+  if (accessToken === undefined) throw new Error("Cursor API key exchange returned no access token");
+  const refreshToken = nonEmptyTrimmedString(outcome.body["refreshToken"]) ?? apiKey;
+  const expiry = decodeJwtExpiryMs(accessToken);
+  return {
+    accessToken,
+    refreshToken,
+    expiresAt: new Date(expiry ?? Date.now() + EXPIRY_FALLBACK_MS),
+  };
+}
+
+export class CursorOAuthClient extends OAuthDeviceFlow {
+  override readonly supportsDeviceCode = true;
+  override readonly supportsBrowserCode = false;
+  readonly importFields = IMPORT_FIELDS;
+
+  protected override readonly providerLabel = "Cursor";
+  // Cursor's poll endpoint takes no client id; the abstract field stays empty
+  // rather than inventing one, and the poll request omits it.
+  protected override readonly clientId = "";
+  protected override readonly tokenUrl = `${CURSOR_API_BASE_URL}/oauth/token`;
+  protected override readonly scopes = "";
+
+  /**
+   * Starts the browser login.
+   *
+   * The PKCE verifier is the flow's private half and is returned only as
+   * `providerState` — the console persists it in Redis, and the browser sees the
+   * URL and the UUID alone. Publishing it would let anyone who can read the
+   * start response mint the tokens the operator is about to authorize.
+   */
+  override async startDeviceAuth(
+    _context?: OAuthDeviceFlowContext,
+  ): Promise<OAuthDeviceStartResult> {
+    const verifier = base64UrlEncode(randomBytes(32));
+    const challenge = base64UrlEncode(createHash("sha256").update(verifier).digest());
+    const uuid = randomUUID();
+    const params = new URLSearchParams({
+      challenge,
+      uuid,
+      mode: "login",
+      redirectTarget: "cli",
+    });
+    return {
+      verificationUri: `${CURSOR_WEBSITE_URL}/loginDeepControl?${params.toString()}`,
+      // No user code: approval happens against the browser session.
+      userCode: "",
+      deviceAuthId: uuid,
+      intervalSeconds: DEVICE_INTERVAL_SECONDS,
+      expiresInSeconds: DEVICE_EXPIRY_SECONDS,
+      providerState: JSON.stringify({ verifier } satisfies CursorDeviceState),
+    };
+  }
+
+  /**
+   * Polls `/auth/poll` with the private verifier.
+   *
+   * 404 is Cursor's "not approved yet" answer, not a failure. A 429 is a
+   * backoff request rather than a dead credential, so the dashboard widens its
+   * cadence and keeps waiting. A 200 without tokens is still pending: the
+   * operator may not have finished approving, and ending the flow there would
+   * abandon a login in progress (a genuinely changed shape surfaces as the
+   * flow's own expiry).
+   */
+  override async pollDeviceAuth(
+    deviceAuthId: string,
+    context?: OAuthDeviceFlowContext,
+  ): Promise<OAuthDevicePollResult> {
+    const state = parseDeviceState(context?.providerState);
+    if (state === undefined) return { status: "failed", reason: "unknown Cursor device authorization" };
+    const url =
+      `${CURSOR_API_BASE_URL}/auth/poll?uuid=${encodeURIComponent(deviceAuthId)}` +
+      `&verifier=${encodeURIComponent(state.verifier)}`;
+    const outcome = await fetchJson(
+      asFetchFn(this.fetchFn),
+      url,
+      { method: "GET", headers: { accept: "application/json" } },
+      AUTH_REQUEST_TIMEOUT_MS,
+      "Cursor device polling",
+    );
+    if (!outcome.ok) {
+      if (outcome.status === 404) return { status: "pending" };
+      if (outcome.status === 429) {
+        return { status: "slow_down", retryAfterSeconds: DEVICE_INTERVAL_SECONDS * 2 };
+      }
+      return { status: "failed", reason: outcome.message };
+    }
+    const accessToken = nonEmptyTrimmedString(outcome.body["accessToken"]);
+    if (accessToken === undefined) return { status: "pending" };
+    const refreshToken = nonEmptyTrimmedString(outcome.body["refreshToken"]) ?? accessToken;
+    const expiry = decodeJwtExpiryMs(accessToken);
+    const identity = cursorAccountIdentity(accessToken);
+    return {
+      status: "complete",
+      result: {
+        access: accessToken,
+        refresh: refreshToken,
+        expiresAt: new Date(expiry ?? Date.now() + EXPIRY_FALLBACK_MS),
+        ...(identity === undefined ? {} : { accountLabel: identity }),
+        // `method` distinguishes a browser session (renewed by grant) from an
+        // imported key (renewed by re-exchange). It carries no secret.
+        auth_state: { method: "login", ...(identity === undefined ? {} : { subject: identity }) },
+      },
+    };
+  }
+
+  /**
+   * Imports a raw Cursor API key.
+   *
+   * The key is exchanged before it is returned, so an import cannot persist
+   * material that never worked. The exchanged JWT becomes the account secret and
+   * the raw key rides in the encrypted refresh field: the refresher needs it to
+   * renew the login, and that field is the only place it is stored.
+   */
+  async importCredential(input: OAuthImportInput): Promise<OAuthExchangeResult> {
+    const credential = input.credential.trim();
+    if (credential.length === 0) throw new Error("Cursor credential material is required");
+    if (!isExchangeableApiKey(credential)) {
+      throw new Error(
+        "Cursor API keys start with 'crsr_'; sign in with Cursor for a browser session instead.",
+      );
+    }
+    const exchanged = await exchangeApiKey(asFetchFn(this.fetchFn), credential);
+    const identity = cursorAccountIdentity(exchanged.accessToken);
+    return {
+      access: exchanged.accessToken,
+      refresh: credential,
+      expiresAt: exchanged.expiresAt,
+      ...(identity === undefined ? {} : { accountLabel: identity }),
+      auth_state: { method: "api_key", ...(identity === undefined ? {} : { subject: identity }) },
+    };
+  }
+
+  /**
+   * Renews one Cursor account credential.
+   *
+   * An API-key account re-exchanges its raw key (the refresh field holds it); a
+   * browser session posts the IDE's refresh grant. A sign-in policy block and a
+   * `shouldLogout` answer are terminal for this credential, while a network or
+   * 5xx failure is transient and worth retrying.
+   */
+  override async refresh(
+    refreshToken: string,
+    signal?: AbortSignal,
+    context?: OAuthRefreshContext,
+  ): Promise<OAuthTokenRefreshResult> {
+    const method = nonEmptyTrimmedString(context?.auth_state?.["method"]);
+    if (isExchangeableApiKey(refreshToken)) {
+      const exchanged = await exchangeApiKey(asFetchFn(this.fetchFn), refreshToken);
+      return {
+        access: exchanged.accessToken,
+        refresh: refreshToken,
+        expiresAt: exchanged.expiresAt,
+        auth_state: { method: method ?? "api_key" },
+      };
+    }
+    if (refreshToken.length === 0) throw new Error("Cursor refresh token is missing");
+    const outcome = await fetchJson(
+      asFetchFn(this.fetchFn),
+      `${CURSOR_API_BASE_URL}/oauth/token`,
+      {
+        method: "POST",
+        headers: { "content-type": "application/json", "x-cursor-client-type": "cli" },
+        body: JSON.stringify({
+          grant_type: "refresh_token",
+          client_id: CURSOR_OAUTH_CLIENT_ID,
+          refresh_token: refreshToken,
+        }),
+        ...(signal === undefined ? {} : { signal }),
+      },
+      SESSION_REFRESH_TIMEOUT_MS,
+      "Cursor session refresh",
+    );
+    if (!outcome.ok) {
+      // A bare transport failure is transient; a refusal is not.
+      if (outcome.status === 401 || outcome.status === 403) {
+        throw new Error(`Cursor session refresh was rejected (${outcome.status})`);
+      }
+      throw new Error(outcome.message);
+    }
+    if (outcome.body["shouldLogout"] === true) {
+      const code = outcome.body["error"];
+      throw new Error(
+        code === SIGN_IN_POLICY_VIOLATION
+          ? `Cursor session blocked by sign-in policy (${SIGN_IN_POLICY_VIOLATION})`
+          : "Cursor ended the session (shouldLogout) — sign in again",
+      );
+    }
+    const access = nonEmptyTrimmedString(outcome.body["access_token"]);
+    if (access === undefined) throw new Error("Cursor session refresh returned no access token");
+    const expiry = decodeJwtExpiryMs(access);
+    return {
+      access,
+      // The grant issues no new refresh token: the IDE stores the access token
+      // as both, and so does this refresher.
+      refresh: refreshToken,
+      expiresAt: new Date(expiry ?? Date.now() + EXPIRY_FALLBACK_MS),
+      auth_state: { method: method ?? "login" },
+    };
+  }
+}
+
+export const cursorOAuthClient = new CursorOAuthClient();