@rahularya01/pi-cursor 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## [1.0.0] - 2026-07-23
+
+### Added
+
+- Initial stable release of `@rahularya01/pi-cursor` provider for Pi Coding Agent.
+- 4-tier authentication resolution cascade: automatically resolves tokens from `CURSOR_ACCESS_TOKEN` env var, macOS Keychain (Cursor CLI), Cursor IDE local state (`state.vscdb`), and Pi OAuth store (`~/.pi/agent/auth.json`).
+- Automatic WSL (Windows Subsystem for Linux) host Windows AppData credential auto-discovery.
+- Deep-link PKCE browser OAuth (`/login cursor`) with token refresh.
+- Native `streamSimple` transport over Connect/protobuf HTTP/2 via `h2-bridge.mjs`.
+- Live model discovery (`GetUsableModels` + parameterized metadata) with static fallback catalog.
+- Effort-suffix model collapse and Pi thinking-level routing.
+- Context-mode normalization: side-channel user messages (such as context-mode routing or post-compaction `<session_state>` blocks) are safely normalized into the system prompt so Cursor models stay focused on the user's task.
+- Visual TUI usage dashboard (`/cursor.usage`) with progress bars, plan breakdown (`Included`, `Auto`, `API`), reset dates, and dashboard link.
+- Sanitized provider diagnostics command (`/cursor.doctor`) and model catalog command (`/cursor.models`).
+- GitHub Actions CI/CD workflows targeting Node 22 and 24 for automated testing and npm publishing.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rahul Arya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,174 @@
+# @rahularya01/pi-cursor
+
+[![npm version](https://img.shields.io/npm/v/@rahularya01/pi-cursor?logo=npm)](https://www.npmjs.com/package/@rahularya01/pi-cursor)
+[![license](https://img.shields.io/npm/l/@rahularya01/pi-cursor)](LICENSE)
+
+A Pi Coding Agent provider for **Cursor** models. It adds provider `cursor`, multi-source authentication resolution (macOS Keychain, Cursor IDE, WSL host, environment variables, or PKCE browser OAuth), native Connect/protobuf streaming over HTTP/2, model discovery, thinking effort routing, and visual TUI usage diagnostics—without invoking the Cursor CLI for day-to-day chat.
+
+> **Unofficial integration.** This project is not affiliated with or endorsed by Cursor / Anysphere. It uses reverse-engineered Wire protocol details shared by community clients (see attributions). Use it only with an account you are authorized to access, and review its source before granting OAuth permissions. Cursor may change wire protocol endpoints or formats at any time.
+
+## Requirements
+
+- Pi Coding Agent and Pi AI version **0.80.0 or later**
+- A Cursor account with model access (or Cursor CLI / Cursor IDE logged in on your machine)
+- Node.js version **22.0.0 or later** (for native HTTP/2 Connect streaming and SQLite credential resolution)
+
+## Install
+
+Install from npm:
+
+```bash
+pi install npm:@rahularya01/pi-cursor
+```
+
+Or install the latest repository version:
+
+```bash
+pi install git:github.com/Rahularya01/pi-cursor
+```
+
+Restart Pi (or run `/reload`) after installation. To update the package later, run `pi update npm:@rahularya01/pi-cursor`.
+
+## Quick start
+
+1. If you are already logged in to Cursor CLI or the Cursor app on your machine, `pi-cursor` auto-detects your credentials. Otherwise, start Pi and run `/login cursor` to sign in via browser.
+2. Select a model, for example:
+
+   ```text
+   /model cursor/composer-2
+   ```
+
+3. Start working. Use `/cursor.doctor` to verify diagnostics and active authentication source.
+
+## Authentication and resolution cascade
+
+`pi-cursor` automatically resolves credentials using a 4-tier cascade:
+
+```text
+1. CURSOR_ACCESS_TOKEN environment variable
+2. Cursor CLI credentials in macOS Keychain (cursor-access-token / cursor-refresh-token)
+3. Cursor IDE local state DB (globalStorage/state.vscdb on macOS, Windows, Linux, or WSL)
+4. Pi OAuth credentials store (~/.pi/agent/auth.json via /login cursor)
+```
+
+### Automatic CLI & IDE login detection
+
+If you are logged into the Cursor desktop app or Cursor CLI (`cursor` / `agent`), `pi-cursor` automatically extracts your session credentials so you can start chatting immediately without manual browser login.
+
+On **WSL (Windows Subsystem for Linux)**, `pi-cursor` automatically scans Windows host user profiles (`/mnt/c/Users/*/AppData/...`) to detect and reuse your Windows Cursor app login.
+
+### Deep-link PKCE browser login
+
+When no local credentials exist, running `/login cursor` initiates browser sign-in:
+
+1. `/login cursor` opens `https://cursor.com/loginDeepControl?...`
+2. Pi polls `https://api2.cursor.sh/auth/poll` until authentication completes.
+3. Access and refresh tokens are stored in Pi's auth store (`~/.pi/agent/auth.json`).
+4. Tokens are automatically refreshed via `https://api2.cursor.sh/auth/exchange_user_api_key`.
+
+Use `/cursor.doctor` to inspect which source is active (`tokenSource=cli_keychain`, `tokenSource=ide_vscdb`, `tokenSource=pi_oauth`, `tokenSource=env`).
+
+## Commands
+
+| Command              | Description                                                                                      |
+| -------------------- | ------------------------------------------------------------------------------------------------ |
+| `/login cursor`      | Sign in to Cursor via browser PKCE and refresh the live model catalog.                           |
+| `/model cursor/<id>` | Choose a registered Cursor model.                                                                |
+| `/cursor.models`     | List active runtime models, context windows, and effort capabilities.                            |
+| `/cursor.models all` | Include tab/chat internal model variants normally hidden from the picker.                        |
+| `/cursor.usage`      | Display visual TUI usage dashboard (included/auto/API quota bars, reset dates, on-demand spend). |
+| `/cursor.doctor`     | Show sanitized provider diagnostics, active token source, endpoint, and last error.              |
+
+## Models and reasoning effort routing
+
+`pi-cursor` discovers live account models via `GetUsableModels` and parameterized metadata. Reasoning effort levels (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`) are mapped directly to Cursor's runtime model variants or reasoning parameters.
+
+| Public model ID          | Context | Thinking | Description / Routing                                      |
+| ------------------------ | ------- | -------- | ---------------------------------------------------------- |
+| `cursor/composer-2`      | 200,000 | Yes      | Cursor's agentic model with fast reasoning effort options. |
+| `cursor/composer-1.5`    | 200,000 | Yes      | Fast agent model optimized for code edit turns.            |
+| `cursor/claude-sonnet-5` | 200,000 | Yes      | Anthropic Claude Sonnet via Cursor infrastructure.         |
+| `cursor/gpt-5.5`         | 200,000 | Yes      | OpenAI flagship model with parameterized reasoning levels. |
+| `cursor/grok-4.5`        | 200,000 | Yes      | xAI Grok model via Cursor infrastructure.                  |
+
+To restrict which models Pi displays, configure `~/.pi/agent/settings.json`:
+
+```json
+{
+  "enabledModels": ["cursor/composer-2", "cursor/claude-sonnet-5", "cursor/gpt-5.5"]
+}
+```
+
+## Usage quota and visual TUI dashboard
+
+Running `/cursor.usage` displays a formatted terminal interface showing your current billing cycle, progress bars for included plan quota, auto/API usage, reset dates, and on-demand spend:
+
+```text
+Usage • Pro                                           Resets 5 Aug
+Monthly plan and on-demand usage
+
+Category        Current          Usage
+Included        13% used         ███░░░░░░░░░░░░░░░░░
+  Auto          12% used         ███░░░░░░░░░░░░░░░░░
+  API           14% used         ███░░░░░░░░░░░░░░░░░
+On-Demand       Disabled
+------------------------------------------------------------
+On-demand usage is off
+
+View in dashboard: cursor.com/dashboard?tab=usage
+```
+
+Usage statistics are fetched directly from Cursor's native Connect period usage endpoint (`POST https://api2.cursor.sh/aiserver.v1.DashboardService/GetCurrentPeriodUsage`) using your active access token, with optional fallback to `CURSOR_USAGE_SESSION_TOKEN`.
+
+## Architecture & Wire Protocol
+
+```text
+Pi Coding Agent  →  streamSimple (cursor-native)
+                      → h2-bridge.mjs (Node.js HTTP/2 child process)
+                      → agent.v1.AgentService/Run (Connect + Protobuf over HTTP/2)
+```
+
+- **Transport:** Native Connect/protobuf streaming over HTTP/2 via `h2-bridge.mjs`.
+- **Context-Mode Normalization:** Side-channel user messages (such as context-mode routing or post-compaction `<session_state>` blocks) are safely normalized into the system prompt so Cursor models stay focused on your primary task.
+- **Cross-Platform:** Tested and fully compatible with macOS, Linux, Windows, and WSL.
+
+## Configuration
+
+| Variable                                   | Purpose                                                                  |
+| ------------------------------------------ | ------------------------------------------------------------------------ |
+| `PI_CURSOR_AGENT_URL` / `CURSOR_AGENT_URL` | Override agent base URL (default: `https://agentn.us.api5.cursor.sh`).   |
+| `CURSOR_ACCESS_TOKEN`                      | Static access token override.                                            |
+| `PI_CURSOR_CLIENT_VERSION`                 | Pin `x-cursor-client-version` header sent by the HTTP/2 bridge.          |
+| `PI_CURSOR_RAW_MODELS`                     | Disable effort-suffix model collapse.                                    |
+| `PI_CURSOR_PROVIDER_DEBUG`                 | Enable JSONL debug logging (`/tmp/pi-cursor-debug.jsonl`).               |
+| `CURSOR_USAGE_SESSION_TOKEN`               | Optional `WorkosCursorSessionToken` fallback cookie for `/cursor.usage`. |
+| `PI_OFFLINE`                               | Skip live model discovery on startup.                                    |
+
+## Troubleshooting
+
+- **Not logged in / 401:** Ensure Cursor CLI or app is logged in, or run `/login cursor` again. Check `/cursor.doctor` to verify your `tokenSource`.
+- **Empty / hung stream:** Cursor may have updated wire headers; verify network connectivity or bump `PI_CURSOR_CLIENT_VERSION`.
+- **Tool continuation lost:** Retry the turn or start a new chat (the live upstream HTTP/2 stream was interrupted mid-tool).
+- **WSL credential detection:** Ensure your Windows user profile folder exists under `/mnt/c/Users/` and is readable from WSL.
+
+## Development
+
+```bash
+npm install
+npm run check
+```
+
+`npm run check` runs TypeScript typechecking, ESLint, Prettier format verification, security checks, and unit tests.
+
+## Attributions
+
+Wire protocol and authentication patterns adapted from MIT community client lineage:
+
+- [ephraimduncan/opencode-cursor](https://github.com/ephraimduncan/opencode-cursor)
+- [@pi-stef/cursor](https://www.npmjs.com/package/@pi-stef/cursor)
+
+Package structure mirrors [pi-antigravity](https://github.com/Rahularya01/pi-antigravity).
+
+## License
+
+[MIT](LICENSE)

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@rahularya01/pi-cursor",
+  "version": "1.0.0",
+  "description": "Native Cursor provider for Pi Coding Agent (OAuth + Connect/protobuf streamSimple)",
+  "author": "Rahul Arya",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Rahularya01/pi-cursor.git"
+  },
+  "homepage": "https://github.com/Rahularya01/pi-cursor#readme",
+  "bugs": {
+    "url": "https://github.com/Rahularya01/pi-cursor/issues"
+  },
+  "type": "module",
+  "main": "./src/index.ts",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "cursor",
+    "oauth",
+    "provider"
+  ],
+  "files": [
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md",
+    "src",
+    "tsconfig.json"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "security-check": "tsx scripts/security-check.ts",
+    "test": "tsx scripts/test-model-routing.ts && tsx scripts/test-thinking-levels.ts && tsx scripts/test-usage.ts && tsx scripts/test-context-mode-normalize.ts && tsx scripts/test-cli-auth.ts",
+    "smoke:auth": "node --import tsx scripts/smoke-auth.mjs",
+    "smoke:models": "node --import tsx scripts/smoke-models.mjs",
+    "smoke:stream": "node --import tsx scripts/smoke-stream.mjs",
+    "check": "npm run typecheck && npm run lint && npm run format:check && npm run security-check && npm test"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "dependencies": {
+    "@bufbuild/protobuf": "^2.0.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": ">=0.80.0",
+    "@earendil-works/pi-coding-agent": ">=0.80.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^26.1.1",
+    "eslint": "^10.7.0",
+    "eslint-config-prettier": "^10.1.8",
+    "globals": "^17.7.0",
+    "prettier": "^3.9.5",
+    "tsx": "^4.23.1",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.64.0"
+  }
+}

package/src/auth/cli-credentials.ts

@@ -0,0 +1,168 @@
+import { existsSync, readdirSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { homedir, platform } from "node:os";
+import { join } from "node:path";
+import { getCursorAccessTokenFromEnv, getTokenExpiry, refreshCursorToken } from "./oauth.js";
+
+export type CredentialSource =
+  | "env"
+  | "cli_keychain"
+  | "cli_keychain_refresh"
+  | "ide_vscdb"
+  | "ide_vscdb_refresh"
+  | "pi_oauth"
+  | "pi_oauth_refresh";
+
+export interface CursorTokenResult {
+  accessToken: string;
+  source: CredentialSource;
+}
+
+/**
+ * Reads token from macOS Keychain (security CLI).
+ */
+export async function getCursorKeychainToken(): Promise<CursorTokenResult | undefined> {
+  if (platform() !== "darwin") return undefined;
+
+  let accessToken: string | undefined;
+  let refreshToken: string | undefined;
+
+  try {
+    const rawAccess = execFileSync(
+      "security",
+      ["find-generic-password", "-s", "cursor-access-token", "-a", "cursor-user", "-w"],
+      { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 2000 },
+    ).trim();
+    if (rawAccess) accessToken = rawAccess;
+  } catch {
+    // Keychain item not found or error
+  }
+
+  try {
+    const rawRefresh = execFileSync(
+      "security",
+      ["find-generic-password", "-s", "cursor-refresh-token", "-a", "cursor-user", "-w"],
+      { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 2000 },
+    ).trim();
+    if (rawRefresh) refreshToken = rawRefresh;
+  } catch {
+    // Keychain item not found or error
+  }
+
+  if (accessToken && Date.now() < getTokenExpiry(accessToken)) {
+    return { accessToken, source: "cli_keychain" };
+  }
+
+  if (refreshToken) {
+    try {
+      const refreshed = await refreshCursorToken(refreshToken);
+      return { accessToken: refreshed.access, source: "cli_keychain_refresh" };
+    } catch {
+      // Refresh failed
+    }
+  }
+
+  return undefined;
+}
+
+async function getDatabaseSync() {
+  try {
+    const mod = await import("node:sqlite");
+    return mod.DatabaseSync;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Reads token from Cursor IDE state.vscdb.
+ */
+export async function getCursorVscdbToken(): Promise<CursorTokenResult | undefined> {
+  const DatabaseSyncClass = await getDatabaseSync();
+  if (!DatabaseSyncClass) return undefined;
+
+  const dbPaths: string[] = [];
+  const home = homedir();
+
+  if (platform() === "darwin") {
+    dbPaths.push(join(home, "Library/Application Support/Cursor/User/globalStorage/state.vscdb"));
+  } else if (platform() === "win32") {
+    if (process.env.APPDATA) {
+      dbPaths.push(join(process.env.APPDATA, "Cursor/User/globalStorage/state.vscdb"));
+    }
+  } else {
+    // Linux / WSL
+    dbPaths.push(join(home, ".config/Cursor/User/globalStorage/state.vscdb"));
+    // If running inside WSL, auto-detect Windows host Cursor credentials
+    if (process.env.WSL_DISTRO_NAME || process.env.WSL_INTEROP || existsSync("/mnt/c/Users")) {
+      try {
+        const usersDir = "/mnt/c/Users";
+        if (existsSync(usersDir)) {
+          for (const user of readdirSync(usersDir)) {
+            if (user === "Public" || user === "Default" || user.startsWith(".")) continue;
+            dbPaths.push(
+              join(usersDir, user, "AppData/Roaming/Cursor/User/globalStorage/state.vscdb"),
+            );
+          }
+        }
+      } catch {
+        // Ignore read permission errors on Windows user profiles
+      }
+    }
+  }
+
+  for (const dbPath of dbPaths) {
+    try {
+      const db = new DatabaseSyncClass(dbPath, { readOnly: true });
+
+      const accessRow = db
+        .prepare("SELECT value FROM ItemTable WHERE key = 'cursorAuth/accessToken'")
+        .get() as { value?: string } | undefined;
+      const refreshRow = db
+        .prepare("SELECT value FROM ItemTable WHERE key = 'cursorAuth/refreshToken'")
+        .get() as { value?: string } | undefined;
+
+      db.close();
+
+      const accessToken = typeof accessRow?.value === "string" ? accessRow.value.trim() : undefined;
+      const refreshToken =
+        typeof refreshRow?.value === "string" ? refreshRow.value.trim() : undefined;
+
+      if (accessToken && Date.now() < getTokenExpiry(accessToken)) {
+        return { accessToken, source: "ide_vscdb" };
+      }
+
+      if (refreshToken) {
+        try {
+          const refreshed = await refreshCursorToken(refreshToken);
+          return { accessToken: refreshed.access, source: "ide_vscdb_refresh" };
+        } catch {
+          // Refresh failed
+        }
+      }
+    } catch {
+      // Database missing or unreadable
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Full credential resolution cascade:
+ * 1. CURSOR_ACCESS_TOKEN env var
+ * 2. macOS Keychain (Cursor CLI)
+ * 3. Cursor IDE state.vscdb
+ */
+export async function resolveSystemCursorAccessToken(): Promise<CursorTokenResult | undefined> {
+  const envToken = getCursorAccessTokenFromEnv();
+  if (envToken) return { accessToken: envToken, source: "env" };
+
+  const keychainToken = await getCursorKeychainToken();
+  if (keychainToken) return keychainToken;
+
+  const vscdbToken = await getCursorVscdbToken();
+  if (vscdbToken) return vscdbToken;
+
+  return undefined;
+}

package/src/auth/index.ts

@@ -0,0 +1,10 @@
+export {
+  generateCursorAuthParams,
+  pollCursorAuth,
+  refreshCursorToken,
+  getTokenExpiry,
+  getCursorAccessTokenFromEnv,
+  createCursorAuthClient,
+  type CursorAuthParams,
+  type CursorCredentials,
+} from "./oauth.js";

package/src/auth/oauth.ts

@@ -0,0 +1,214 @@
+/**
+ * Cursor OAuth authentication via PKCE.
+ *
+ * Flow:
+ * 1. Generate PKCE verifier + challenge
+ * 2. Open browser to cursor.com/loginDeepControl
+ * 3. Poll api2.cursor.sh/auth/poll until tokens arrive
+ * 4. Refresh via api2.cursor.sh/auth/exchange_user_api_key
+ *
+ * Based on https://github.com/ephraimduncan/opencode-cursor by Ephraim Duncan.
+ */
+
+const CURSOR_LOGIN_URL = "https://cursor.com/loginDeepControl";
+const CURSOR_POLL_URL = "https://api2.cursor.sh/auth/poll";
+const CURSOR_REFRESH_URL = "https://api2.cursor.sh/auth/exchange_user_api_key";
+const POLL_MAX_ATTEMPTS = 150;
+const POLL_BASE_DELAY = 1000;
+const POLL_MAX_DELAY = 10_000;
+const POLL_BACKOFF_MULTIPLIER = 1.2;
+
+// ── PKCE ──
+
+async function generatePKCE(): Promise<{ verifier: string; challenge: string }> {
+  const verifierBytes = new Uint8Array(96);
+  crypto.getRandomValues(verifierBytes);
+  const verifier = Buffer.from(verifierBytes).toString("base64url");
+
+  const data = new TextEncoder().encode(verifier);
+  const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+  const challenge = Buffer.from(hashBuffer).toString("base64url");
+
+  return { verifier, challenge };
+}
+
+// ── Login params ──
+
+export interface CursorAuthParams {
+  verifier: string;
+  challenge: string;
+  uuid: string;
+  loginUrl: string;
+}
+
+export interface CursorAuthClientDependencies {
+  fetch?: typeof fetch;
+  generatePkce?: () => Promise<{ verifier: string; challenge: string; uuid?: string }>;
+  randomUUID?: () => string;
+  sleep?: (ms: number) => Promise<void>;
+}
+
+export interface CursorAuthLoginCallbacks {
+  onAuth(payload: { url: string }): void | Promise<void>;
+}
+
+export function createCursorAuthClient(deps: CursorAuthClientDependencies = {}) {
+  const fetchImpl = deps.fetch ?? fetch;
+  const sleepImpl =
+    deps.sleep ??
+    ((ms: number) =>
+      new Promise<void>((resolve) => {
+        setTimeout(resolve, ms);
+      }));
+  const generatePkceImpl: () => Promise<{ verifier: string; challenge: string; uuid?: string }> =
+    deps.generatePkce ?? generatePKCE;
+  const randomUUIDImpl = deps.randomUUID ?? (() => crypto.randomUUID());
+
+  async function generateParams(): Promise<CursorAuthParams> {
+    const { verifier, challenge, uuid: injectedUuid } = await generatePkceImpl();
+    const uuid = injectedUuid ?? randomUUIDImpl();
+
+    const params = new URLSearchParams({
+      challenge,
+      uuid,
+      mode: "login",
+      redirectTarget: "cli",
+    });
+
+    const loginUrl = `${CURSOR_LOGIN_URL}?${params.toString()}`;
+    return { verifier, challenge, uuid, loginUrl };
+  }
+
+  async function poll(
+    uuid: string,
+    verifier: string,
+  ): Promise<{ accessToken: string; refreshToken: string }> {
+    let delay = POLL_BASE_DELAY;
+    let consecutiveErrors = 0;
+
+    for (let attempt = 0; attempt < POLL_MAX_ATTEMPTS; attempt++) {
+      await sleepImpl(delay);
+
+      try {
+        const response = await fetchImpl(`${CURSOR_POLL_URL}?uuid=${uuid}&verifier=${verifier}`);
+
+        if (response.status === 404) {
+          consecutiveErrors = 0;
+          delay = Math.min(delay * POLL_BACKOFF_MULTIPLIER, POLL_MAX_DELAY);
+          continue;
+        }
+
+        if (response.ok) {
+          const data = (await response.json()) as {
+            accessToken: string;
+            refreshToken: string;
+          };
+          return {
+            accessToken: data.accessToken,
+            refreshToken: data.refreshToken,
+          };
+        }
+
+        throw new Error(`Poll failed: ${response.status}`);
+      } catch {
+        consecutiveErrors++;
+        if (consecutiveErrors >= 3) {
+          throw new Error("Too many consecutive errors during Cursor auth polling");
+        }
+      }
+    }
+
+    throw new Error("Cursor authentication polling timeout");
+  }
+
+  async function refreshToken(refreshToken: string): Promise<CursorCredentials> {
+    const response = await fetchImpl(CURSOR_REFRESH_URL, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${refreshToken}`,
+        "Content-Type": "application/json",
+      },
+      body: "{}",
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`Cursor token refresh failed: ${error}`);
+    }
+
+    const data = (await response.json()) as {
+      accessToken: string;
+      refreshToken: string;
+    };
+
+    return {
+      access: data.accessToken,
+      refresh: data.refreshToken || refreshToken,
+      expires: getTokenExpiry(data.accessToken),
+    };
+  }
+
+  async function login(callbacks: CursorAuthLoginCallbacks): Promise<CursorCredentials> {
+    const { verifier, uuid, loginUrl } = await generateParams();
+    await callbacks.onAuth({ url: loginUrl });
+    const { accessToken, refreshToken } = await poll(uuid, verifier);
+    return {
+      access: accessToken,
+      refresh: refreshToken,
+      expires: getTokenExpiry(accessToken),
+    };
+  }
+
+  return {
+    generateParams,
+    login,
+    poll,
+    refreshToken,
+  };
+}
+
+export async function generateCursorAuthParams(): Promise<CursorAuthParams> {
+  return createCursorAuthClient().generateParams();
+}
+
+// ── Poll for auth completion ──
+
+export async function pollCursorAuth(
+  uuid: string,
+  verifier: string,
+): Promise<{ accessToken: string; refreshToken: string }> {
+  return createCursorAuthClient().poll(uuid, verifier);
+}
+
+// ── Token refresh ──
+
+export interface CursorCredentials {
+  access: string;
+  refresh: string;
+  expires: number;
+}
+
+export async function refreshCursorToken(refreshToken: string): Promise<CursorCredentials> {
+  return createCursorAuthClient().refreshToken(refreshToken);
+}
+
+// ── JWT expiry extraction ──
+
+export function getCursorAccessTokenFromEnv(): string | undefined {
+  const token = process.env.CURSOR_ACCESS_TOKEN?.trim();
+  return token || undefined;
+}
+
+export function getTokenExpiry(token: string): number {
+  try {
+    const parts = token.split(".");
+    if (parts.length !== 3 || !parts[1]) {
+      return Date.now() + 3600 * 1000;
+    }
+    const decoded = JSON.parse(atob(parts[1].replace(/-/g, "+").replace(/_/g, "/")));
+    if (decoded && typeof decoded === "object" && typeof decoded.exp === "number") {
+      return decoded.exp * 1000 - 5 * 60 * 1000;
+    }
+  } catch {}
+  return Date.now() + 3600 * 1000;
+}