cursor-opencode-provider 0.7.6 → 0.8.1

package/dist/auth-renewal.js

@@ -0,0 +1,284 @@
+import { CURSOR_API_HOST, TOKEN_EXPIRY_THRESHOLD_S } from "./shared.js";
+import { AuthExchangeError, decodeJwtPayload, exchangeApiKey, isExchangeableApiKey, isExpiringSoon, refreshCursorSession, } from "./auth.js";
+// Failure details quote HTTP status text ("503 Service Unavailable"), and
+// OpenCode's SessionRetry keys off such words in provider error messages.
+import { CursorAuthError, CursorServerError, sanitizeHostTerminalMessage } from "./errors.js";
+import { errorMessage, trace } from "./debug.js";
+// Credential renewal policy. The two Cursor credential kinds are renewed by
+// independent paths and never stand in for each other:
+//
+// - Browser-login session (OAuth): `POST /oauth/token`, the way Cursor's IDE
+//   renews it, starting once less than 1272 h of its 60-day life remain.
+// - API key: re-exchange the raw `crsr_` key when the exchanged JWT nears
+//   expiry, the way Cursor CLI renews it. Its refresh token is never used.
+//
+// Renewal happens only on demand, when a request needs a token, as OpenCode's
+// own OAuth providers do (a per-request `fetch` that reads `getAuth()`); there
+// is no timer. Both keep the current token through a transient failure while
+// it is still valid, back off between attempts, and latch final failures so
+// they are not retried for the same credential.
+const API_BASE = `https://${CURSOR_API_HOST}`;
+/** Cursor IDE renews a session once less than this remains (`hir = 1272h`). */
+export const SESSION_RENEWAL_WINDOW_MS = 1272 * 3_600_000;
+/** Never renew a session token younger than this, whatever its lifetime. */
+export const SESSION_MIN_AGE_MS = 3_600_000;
+/** A token is still worth sending while it has at least this long left. */
+const USABLE_MARGIN_MS = 30_000;
+const BACKOFF_INITIAL_MS = 30_000;
+const BACKOFF_MAX_MS = 15 * 60_000;
+/** Remember at most this many in-process session renewals. */
+const MAX_SESSION_SUCCESSORS = 32;
+const SIGN_IN_AGAIN = "sign in to Cursor again";
+/**
+ * Issue and expiry times of a Cursor JWT. Cursor session tokens carry the
+ * issue time in a `time` claim (seconds, as a string); standard `iat` is used
+ * when present instead.
+ */
+export function tokenTimes(token) {
+    const payload = decodeJwtPayload(token);
+    if (!payload)
+        return {};
+    const seconds = (value) => {
+        const n = typeof value === "string" && value.trim() !== "" ? Number(value) : value;
+        return typeof n === "number" && Number.isFinite(n) ? n * 1000 : undefined;
+    };
+    const expiresAtMs = seconds(payload.exp);
+    const issuedAtMs = seconds(payload.iat) ?? seconds(payload.time);
+    return {
+        ...(issuedAtMs !== undefined ? { issuedAtMs } : {}),
+        ...(expiresAtMs !== undefined ? { expiresAtMs } : {}),
+    };
+}
+/**
+ * When a session token is due for renewal: 1272 h before expiry, but never
+ * within an hour of issue. Undefined when the token has no readable expiry.
+ */
+export function sessionRenewalDueAt(token) {
+    const { issuedAtMs, expiresAtMs } = tokenTimes(token);
+    if (expiresAtMs === undefined)
+        return undefined;
+    const due = expiresAtMs - SESSION_RENEWAL_WINDOW_MS;
+    return issuedAtMs === undefined ? due : Math.max(due, issuedAtMs + SESSION_MIN_AGE_MS);
+}
+function isUsable(token, now) {
+    const { expiresAtMs } = tokenTimes(token);
+    return expiresAtMs === undefined || expiresAtMs - now > USABLE_MARGIN_MS;
+}
+/** The token that stays valid longer (the first one on a tie or unknown expiry). */
+function longerLived(a, b) {
+    const aExp = tokenTimes(a).expiresAtMs;
+    const bExp = tokenTimes(b).expiresAtMs;
+    return bExp !== undefined && (aExp === undefined || bExp > aExp) ? b : a;
+}
+function isoTime(ms) {
+    return ms === undefined ? "unknown" : new Date(ms).toISOString();
+}
+function backoffMs(failures) {
+    return Math.min(BACKOFF_MAX_MS, BACKOFF_INITIAL_MS * 2 ** Math.max(0, failures - 1));
+}
+function stateFor(map, key) {
+    let state = map.get(key);
+    if (!state) {
+        state = { failures: 0 };
+        map.set(key, state);
+    }
+    return state;
+}
+function recordTransientFailure(state, message) {
+    state.failures++;
+    state.retryAt = Date.now() + backoffMs(state.failures);
+    state.lastFailure = message;
+}
+function recordSuccess(state) {
+    state.failures = 0;
+    state.retryAt = undefined;
+    state.lastFailure = undefined;
+}
+const sessionStates = new Map();
+/** Stored refresh token → newer session token this process obtained for it. */
+const sessionSuccessors = new Map();
+/**
+ * Follow renewals this process already made, so a caller still holding an
+ * older stored credential (persisting failed, or a host that persists only
+ * later) gets the newest token instead of renewing again.
+ */
+export function latestSessionTokens(tokens) {
+    let current = tokens;
+    for (let hops = 0; hops < MAX_SESSION_SUCCESSORS; hops++) {
+        const next = sessionSuccessors.get(current.refreshToken);
+        if (!next || next === current.refreshToken)
+            break;
+        current = { accessToken: next, refreshToken: next };
+    }
+    return longerLived(tokens.accessToken, current.accessToken) === current.accessToken ? current : tokens;
+}
+function rememberSuccessor(refreshToken, accessToken) {
+    sessionSuccessors.delete(refreshToken);
+    sessionSuccessors.set(refreshToken, accessToken);
+    while (sessionSuccessors.size > MAX_SESSION_SUCCESSORS) {
+        const oldest = sessionSuccessors.keys().next().value;
+        if (oldest === undefined)
+            break;
+        sessionSuccessors.delete(oldest);
+    }
+}
+export function isSessionRenewalDue(token, now = Date.now()) {
+    const due = sessionRenewalDueAt(token);
+    return due !== undefined && now >= due;
+}
+/**
+ * Return a usable session token, renewing it first when it is due (or when
+ * `force` is set after Cursor rejected it). Renewal failures that leave the
+ * current token valid keep it; a session Cursor ended, or one that expired
+ * and could not be renewed, raises `CursorAuthError`.
+ */
+export async function renewSessionIfDue(tokens, options = {}) {
+    const baseUrl = options.baseUrl ?? API_BASE;
+    const base = latestSessionTokens(tokens);
+    const fromMemory = base.accessToken !== tokens.accessToken;
+    if (!options.force && !isSessionRenewalDue(base.accessToken)) {
+        return { accessToken: base.accessToken, renewed: fromMemory };
+    }
+    const state = stateFor(sessionStates, `${baseUrl}\0${base.refreshToken}`);
+    if (!state.terminal && (options.force || state.retryAt === undefined || Date.now() >= state.retryAt)) {
+        state.inflight ??= (async () => {
+            const result = await refreshCursorSession(base.refreshToken, baseUrl);
+            if (result.ok) {
+                const { expiresAtMs } = tokenTimes(result.accessToken);
+                if (expiresAtMs === undefined) {
+                    recordTransientFailure(state, "session refresh returned a token without expiry");
+                }
+                else {
+                    rememberSuccessor(base.refreshToken, result.accessToken);
+                    recordSuccess(state);
+                    trace(`auth: session renewed exp=${isoTime(expiresAtMs)}`);
+                    return;
+                }
+            }
+            else if (result.kind === "transient") {
+                recordTransientFailure(state, result.message);
+            }
+            else {
+                state.terminal = new CursorAuthError(result.kind === "policy"
+                    ? `Cursor sign-in policy blocks this login (sign_in_policy_violation); ${SIGN_IN_AGAIN} with an allowed account`
+                    : `Cursor ended this login session; ${SIGN_IN_AGAIN}`, { code: result.kind === "policy" ? "sign_in_policy_violation" : "session_logout", statusCode: result.status });
+                trace(`auth: session renewal final failure kind=${result.kind}`);
+                return;
+            }
+            trace(`auth: session renewal failed (${state.lastFailure}) attempt=${state.failures} ` +
+                `retryAt=${isoTime(state.retryAt)} currentExp=${isoTime(tokenTimes(base.accessToken).expiresAtMs)}`);
+        })().finally(() => {
+            state.inflight = undefined;
+        });
+        await state.inflight;
+    }
+    const renewed = latestSessionTokens(base);
+    if (renewed.accessToken !== base.accessToken) {
+        return { accessToken: renewed.accessToken, renewed: true };
+    }
+    if (state.terminal)
+        throw state.terminal;
+    if (!isUsable(base.accessToken, Date.now())) {
+        throw new CursorAuthError(`Cursor login expired and could not be renewed (${sanitizeHostTerminalMessage(state.lastFailure ?? "no renewal attempt allowed yet")}); ${SIGN_IN_AGAIN}`, { code: "session_expired" });
+    }
+    return {
+        accessToken: base.accessToken,
+        renewed: fromMemory,
+        ...(state.retryAt !== undefined ? { retryAt: state.retryAt } : {}),
+    };
+}
+// ── API key ──
+const apiKeyStates = new Map();
+/**
+ * JWT for a raw `crsr_` API key: the cached or `seed` JWT while it is not
+ * within five minutes of expiry, otherwise a fresh exchange. Cached per API
+ * base URL and key. Never returns the raw key itself.
+ */
+export async function resolveApiKeyToken(apiKey, options = {}) {
+    if (!isExchangeableApiKey(apiKey)) {
+        throw new CursorAuthError("Cursor API key must start with crsr_");
+    }
+    const baseUrl = options.baseUrl ?? API_BASE;
+    const state = stateFor(apiKeyStates, `${baseUrl}\0${apiKey}`);
+    const seed = options.seed && !isExchangeableApiKey(options.seed) && tokenTimes(options.seed).expiresAtMs !== undefined
+        ? options.seed
+        : undefined;
+    if (seed)
+        state.token = state.token ? longerLived(state.token, seed) : seed;
+    const result = (token) => ({ accessToken: token, renewed: token !== seed });
+    if (state.token && !options.force && !isExpiringSoon(state.token, TOKEN_EXPIRY_THRESHOLD_S)) {
+        return result(state.token);
+    }
+    if (!state.terminal && (options.force || state.retryAt === undefined || Date.now() >= state.retryAt)) {
+        state.inflight ??= (async () => {
+            try {
+                const pair = await exchangeApiKey(apiKey, baseUrl);
+                state.token = state.token ? longerLived(state.token, pair.accessToken) : pair.accessToken;
+                recordSuccess(state);
+                trace(`auth: API key exchanged exp=${isoTime(tokenTimes(pair.accessToken).expiresAtMs)}`);
+            }
+            catch (error) {
+                const kind = error instanceof AuthExchangeError ? error.kind : "transient";
+                if (kind === "transient") {
+                    recordTransientFailure(state, errorMessage(error));
+                    trace(`auth: API key exchange failed (${state.lastFailure}) attempt=${state.failures} retryAt=${isoTime(state.retryAt)}`);
+                }
+                else {
+                    const status = error instanceof AuthExchangeError ? error.status : undefined;
+                    state.terminal = new CursorAuthError(kind === "policy"
+                        ? "Cursor sign-in policy blocks this API key (sign_in_policy_violation); use an allowed account"
+                        : `Cursor rejected the API key${status ? ` (HTTP ${status})` : ""}; create a new key and sign in with it`, { code: kind === "policy" ? "sign_in_policy_violation" : "api_key_rejected", ...(status ? { statusCode: status } : {}) });
+                    trace(`auth: API key exchange final failure kind=${kind} status=${status ?? "none"}`);
+                }
+            }
+        })().finally(() => {
+            state.inflight = undefined;
+        });
+        await state.inflight;
+    }
+    // A fresh exchange is always usable; an older token only until it expires.
+    if (state.token && isUsable(state.token, Date.now()))
+        return result(state.token);
+    if (state.terminal)
+        throw state.terminal;
+    throw new CursorServerError(`Cursor API key exchange failed (${sanitizeHostTerminalMessage(state.lastFailure ?? "waiting before the next attempt")}); it is retried automatically`, { transient: true, replaySafe: true });
+}
+/**
+ * Bearer token for a Cursor request. One credential source is used, in this
+ * order, and none of them falls back to another:
+ *
+ * 1. `getAccessToken` — the host resolves (and renews) the token per request.
+ * 2. `accessToken` — sent as-is.
+ * 3. `apiKey` — a raw `crsr_` key is exchanged and renewed; any other value is
+ *    a token a host forwarded through the generic API-key slot, sent as-is.
+ */
+export async function resolveBearerToken(input) {
+    let token;
+    if (input.getAccessToken) {
+        token = await input.getAccessToken(input.forceRefresh ? { forceRefresh: true } : undefined);
+    }
+    else if (input.accessToken) {
+        token = input.accessToken;
+    }
+    else if (input.apiKey) {
+        token = isExchangeableApiKey(input.apiKey)
+            ? (await resolveApiKeyToken(input.apiKey, { baseUrl: input.baseUrl, force: input.forceRefresh })).accessToken
+            : input.apiKey;
+    }
+    else {
+        throw new CursorAuthError("Cursor provider: no access token or API key provided");
+    }
+    if (!token)
+        throw new CursorAuthError(`Cursor provider: no access token available; ${SIGN_IN_AGAIN}`);
+    if (isExchangeableApiKey(token)) {
+        // A raw key is never a valid Bearer token; Cursor answers 401.
+        throw new CursorAuthError("Cursor provider: a raw crsr_ API key was supplied as an access token; pass it as apiKey");
+    }
+    return token;
+}
+/** Reset all renewal state (tests). */
+export function resetAuthRenewalState() {
+    sessionStates.clear();
+    sessionSuccessors.clear();
+    apiKeyStates.clear();
+}

package/dist/auth.d.ts

@@ -1,10 +1,15 @@
+/**
+ * How an API key exchange failed. A policy block (403
+ * `sign_in_policy_violation`, as Cursor CLI's `loginWithApiKey` reports it) and
+ * an authentication refusal (401/403) are final for that key; anything else —
+ * rate limit, timeout, server or network failure — is worth retrying later.
+ */
+export type AuthExchangeFailureKind = "policy" | "rejected" | "transient";
 export declare class AuthExchangeError extends Error {
     cause?: unknown | undefined;
-    constructor(message: string, cause?: unknown | undefined);
-}
-export declare class AuthRefreshError extends Error {
-    cause?: unknown | undefined;
-    constructor(message: string, cause?: unknown | undefined);
+    readonly kind: AuthExchangeFailureKind;
+    readonly status?: number | undefined;
+    constructor(message: string, cause?: unknown | undefined, kind?: AuthExchangeFailureKind, status?: number | undefined);
 }
 export declare class AuthPollError extends Error {
     cause?: unknown | undefined;
@@ -17,6 +22,8 @@ export declare function isExpiringSoon(jwt: string, thresholdS?: number): boolea
 export declare function decodeJwtPayload(jwt: string): Record<string, unknown> | null;
 /** JWT `exp` claim as epoch milliseconds, or null if missing/malformed. */
 export declare function decodeJwtExpiryMs(jwt: string): number | null;
+/** A raw Cursor API key (as opposed to a JWT already exchanged from one). */
+export declare function isExchangeableApiKey(value: string): boolean;
 export declare function useAuthToken(token: string): {
     accessToken: string;
 };
@@ -24,27 +31,36 @@ export type TokenPair = {
     accessToken: string;
     refreshToken: string;
 };
+/**
+ * Exchange a raw `crsr_` API key for a short-lived JWT. This is also how an
+ * API-key login is renewed: Cursor CLI re-runs the exchange and never uses the
+ * returned refresh token (`auth-refresh.ts` → `loginWithApiKey`).
+ */
 export declare function exchangeApiKey(apiKey: string, baseUrl?: string): Promise<TokenPair>;
-export declare function refreshAccessToken(refreshToken: string, baseUrl?: string): Promise<TokenPair>;
-/** Clear the apiKey→JWT cache (tests). */
-export declare function clearBearerTokenCache(): void;
+export type SessionRefreshResult = {
+    ok: true;
+    accessToken: string;
+} | {
+    ok: false;
+    /**
+     * `logout`: Cursor ended the session. `policy`: a sign-in policy blocks
+     * it. Both are final for this token. `transient`: try again later.
+     */
+    kind: "logout" | "policy" | "transient";
+    status?: number;
+    message: string;
+};
 /**
- * Resolve a Bearer JWT for Cursor API calls. Prefer an already-exchanged
- * `accessToken`; otherwise exchange (and cache) from `apiKey`, refreshing
- * when the cached JWT is near expiry.
+ * Renew a browser-login session token, exactly as Cursor's IDE does
+ * (`_performAccessTokenRefresh`): `POST /oauth/token` with a refresh_token
+ * grant and the IDE's client id. The response carries no new refresh token;
+ * the IDE stores the new access token as both, and so must callers.
  *
- * `apiKey` is only ever a raw exchangeable secret when it has Cursor's
- * `crsr_` prefix. Callers that generically forward whatever credential value
- * they hold — e.g. a host's package-agnostic "aisdk:" SDK loader, which
- * doesn't distinguish our OAuth vs. API-key connection methods and may pass
- * an already-issued JWT through the `apiKey` field — hand us a token that's
- * already good to use as-is; POSTing it to the exchange endpoint 401s.
+ * A rejected token is not an HTTP error: Cursor answers 200 with
+ * `{"access_token":"","shouldLogout":true}`, so the body decides the outcome.
+ * Never throws; every failure is a classified result.
  */
-export declare function resolveBearerToken(input: {
-    accessToken?: string;
-    apiKey?: string;
-    baseUrl?: string;
-}): Promise<string>;
+export declare function refreshCursorSession(refreshToken: string, baseUrl?: string): Promise<SessionRefreshResult>;
 export type PkceParams = {
     verifier: string;
     challenge: string;

package/dist/auth.js

@@ -1,23 +1,24 @@
-import { CURSOR_API_HOST, CURSOR_WEBSITE_HOST } from "./shared.js";
+import { CURSOR_API_HOST, CURSOR_OAUTH_CLIENT_ID, CURSOR_WEBSITE_HOST } from "./shared.js";
 import { withAbortDeadline } from "./deadline.js";
+import { errorMessage } from "./debug.js";
 const API_BASE = `https://${CURSOR_API_HOST}`;
 const AUTH_REQUEST_TIMEOUT_MS = 5_000;
+/** Cursor IDE aborts its session refresh after 20 s (`_performAccessTokenRefresh`). */
+const SESSION_REFRESH_TIMEOUT_MS = 20_000;
+/** Server error code Cursor's IDE and CLI both surface as a sign-in policy block. */
+const SIGN_IN_POLICY_VIOLATION = "sign_in_policy_violation";
 export class AuthExchangeError extends Error {
     cause;
-    constructor(message, cause) {
+    kind;
+    status;
+    constructor(message, cause, kind = "transient", status) {
         super(message);
         this.cause = cause;
+        this.kind = kind;
+        this.status = status;
         this.name = "AuthExchangeError";
     }
 }
-export class AuthRefreshError extends Error {
-    cause;
-    constructor(message, cause) {
-        super(message);
-        this.cause = cause;
-        this.name = "AuthRefreshError";
-    }
-}
 export class AuthPollError extends Error {
     cause;
     constructor(message, cause) {
@@ -69,10 +70,19 @@ function base64url(bytes) {
         .replace(/\//g, "_")
         .replace(/=+$/, "");
 }
+/** A raw Cursor API key (as opposed to a JWT already exchanged from one). */
+export function isExchangeableApiKey(value) {
+    return value.startsWith("crsr_");
+}
 // ── Mode A: pass-through auth token ──
 export function useAuthToken(token) {
     return { accessToken: token };
 }
+/**
+ * Exchange a raw `crsr_` API key for a short-lived JWT. This is also how an
+ * API-key login is renewed: Cursor CLI re-runs the exchange and never uses the
+ * returned refresh token (`auth-refresh.ts` → `loginWithApiKey`).
+ */
 export async function exchangeApiKey(apiKey, baseUrl = API_BASE) {
     return withAbortDeadline(AUTH_REQUEST_TIMEOUT_MS, () => new AuthExchangeError("API key exchange timed out"), async (signal) => {
         let res;
@@ -91,7 +101,18 @@ export async function exchangeApiKey(apiKey, baseUrl = API_BASE) {
             throw new AuthExchangeError("API key exchange request failed", cause);
         }
         if (!res.ok) {
-            throw new AuthExchangeError(`API key exchange failed: ${res.status} ${res.statusText}`);
+            let errorCode;
+            if (res.status === 403) {
+                errorCode = (await res.json().catch(() => undefined))?.error;
+            }
+            // Only an authentication refusal says the key itself is bad; rate
+            // limits, timeouts, and server errors are worth another attempt.
+            const kind = errorCode === SIGN_IN_POLICY_VIOLATION
+                ? "policy"
+                : res.status === 401 || res.status === 403 ? "rejected" : "transient";
+            throw new AuthExchangeError(kind === "policy"
+                ? `API key exchange blocked by Cursor sign-in policy (${SIGN_IN_POLICY_VIOLATION})`
+                : `API key exchange failed: ${res.status} ${res.statusText}`, undefined, kind, res.status);
         }
         let body;
         try {
@@ -106,97 +127,59 @@ export async function exchangeApiKey(apiKey, baseUrl = API_BASE) {
         return { accessToken: body.accessToken, refreshToken: body.refreshToken };
     });
 }
-export async function refreshAccessToken(refreshToken, baseUrl = API_BASE) {
-    return withAbortDeadline(AUTH_REQUEST_TIMEOUT_MS, () => new AuthRefreshError("Token refresh timed out"), async (signal) => {
-        let res;
-        try {
-            res = await fetch(`${baseUrl}/auth/token`, {
-                method: "POST",
-                headers: { "Content-Type": "application/json" },
-                body: JSON.stringify({ refreshToken }),
-                signal,
-            });
-        }
-        catch (cause) {
-            throw new AuthRefreshError("Token refresh request failed", cause);
-        }
-        if (!res.ok) {
-            throw new AuthRefreshError(`Token refresh failed: ${res.status} ${res.statusText}`);
-        }
-        let body;
-        try {
-            body = await res.json();
-        }
-        catch (cause) {
-            throw new AuthRefreshError("Token refresh returned malformed JSON", cause);
-        }
-        if (typeof body.accessToken !== "string" || typeof body.refreshToken !== "string") {
-            throw new AuthRefreshError("Refresh response missing tokens");
-        }
-        return { accessToken: body.accessToken, refreshToken: body.refreshToken };
-    });
-}
-// Cache JWTs obtained via API-key exchange so doStream doesn't re-exchange
-// on every turn when the caller only supplied `apiKey`.
-const _apiKeyTokenCache = new Map();
-const inflightBearer = new Map();
-/** Clear the apiKey→JWT cache (tests). */
-export function clearBearerTokenCache() {
-    _apiKeyTokenCache.clear();
-    inflightBearer.clear();
-}
 /**
- * Resolve a Bearer JWT for Cursor API calls. Prefer an already-exchanged
- * `accessToken`; otherwise exchange (and cache) from `apiKey`, refreshing
- * when the cached JWT is near expiry.
+ * Renew a browser-login session token, exactly as Cursor's IDE does
+ * (`_performAccessTokenRefresh`): `POST /oauth/token` with a refresh_token
+ * grant and the IDE's client id. The response carries no new refresh token;
+ * the IDE stores the new access token as both, and so must callers.
  *
- * `apiKey` is only ever a raw exchangeable secret when it has Cursor's
- * `crsr_` prefix. Callers that generically forward whatever credential value
- * they hold — e.g. a host's package-agnostic "aisdk:" SDK loader, which
- * doesn't distinguish our OAuth vs. API-key connection methods and may pass
- * an already-issued JWT through the `apiKey` field — hand us a token that's
- * already good to use as-is; POSTing it to the exchange endpoint 401s.
+ * A rejected token is not an HTTP error: Cursor answers 200 with
+ * `{"access_token":"","shouldLogout":true}`, so the body decides the outcome.
+ * Never throws; every failure is a classified result.
  */
-export async function resolveBearerToken(input) {
-    if (input.accessToken)
-        return input.accessToken;
-    if (!input.apiKey) {
-        throw new Error("Cursor provider: no access token or API key provided");
-    }
-    if (!input.apiKey.startsWith("crsr_"))
-        return input.apiKey;
-    const baseUrl = input.baseUrl ?? API_BASE;
-    const cached = _apiKeyTokenCache.get(input.apiKey);
-    if (cached && !isExpiringSoon(cached.accessToken)) {
-        return cached.accessToken;
-    }
-    const inflightKey = `${baseUrl}\0${input.apiKey}`;
-    const existing = inflightBearer.get(inflightKey);
-    if (existing)
-        return existing;
-    async function refreshOrExchange() {
-        if (cached) {
-            try {
-                const refreshed = await refreshAccessToken(cached.refreshToken, baseUrl);
-                _apiKeyTokenCache.set(input.apiKey, refreshed);
-                return refreshed.accessToken;
+export async function refreshCursorSession(refreshToken, baseUrl = API_BASE) {
+    try {
+        return await withAbortDeadline(SESSION_REFRESH_TIMEOUT_MS, () => new Error("session refresh timed out"), async (signal) => {
+            const res = await fetch(`${baseUrl}/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,
+            });
+            if (!res.ok) {
+                return {
+                    ok: false,
+                    kind: "transient",
+                    status: res.status,
+                    message: `session refresh failed: ${res.status} ${res.statusText}`,
+                };
             }
-            catch {
-                // Fall through to a fresh exchange.
+            const body = await res.json().catch(() => undefined);
+            if (body?.shouldLogout === true) {
+                return body.error === SIGN_IN_POLICY_VIOLATION
+                    ? { ok: false, kind: "policy", status: res.status, message: `session blocked by Cursor sign-in policy (${SIGN_IN_POLICY_VIOLATION})` }
+                    : { ok: false, kind: "logout", status: res.status, message: "Cursor ended the session (shouldLogout)" };
             }
-        }
-        const pair = await exchangeApiKey(input.apiKey, baseUrl);
-        _apiKeyTokenCache.set(input.apiKey, pair);
-        return pair.accessToken;
-    }
-    const pending = refreshOrExchange();
-    inflightBearer.set(inflightKey, pending);
-    try {
-        return await pending;
+            // The IDE would store an empty token here; treat it as a failed attempt.
+            if (typeof body?.access_token !== "string" || body.access_token === "") {
+                return { ok: false, kind: "transient", status: res.status, message: "session refresh returned no access token" };
+            }
+            return { ok: true, accessToken: body.access_token };
+        });
     }
-    finally {
-        if (inflightBearer.get(inflightKey) === pending)
-            inflightBearer.delete(inflightKey);
+    catch (cause) {
+        return {
+            ok: false,
+            kind: "transient",
+            message: `session refresh request failed: ${errorMessage(cause)}`,
+        };
     }
 }
 // ── Mode C: PKCE browser login ──

package/dist/classic-tools.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Classic plugin tools built with the host's own `tool()` helper when it can
+ * be found. Lives outside `plugin.ts` because OpenCode 1.x calls every export
+ * of a plugin module as a plugin (`getLegacyPlugins`), so that module may
+ * export `CursorPlugin` only.
+ */
+export declare function loadClassicTools(options?: {
+    importModule?: (specifier: string) => Promise<{
+        tool?: any;
+    }>;
+    configDirs?: string[];
+}): Promise<{
+    webSearch: any;
+    imageSave: any;
+}>;

package/dist/classic-tools.js

@@ -0,0 +1,45 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { opencodeGlobalConfigDirs } from "./context/paths.js";
+import { createOpenCodeWebSearchTool, openCodeWebSearchTool } from "./web-search-tool.js";
+import { createCursorImageSaveTool, cursorImageSaveTool } from "./image-save-tool.js";
+/**
+ * Classic plugin tools built with the host's own `tool()` helper when it can
+ * be found. Lives outside `plugin.ts` because OpenCode 1.x calls every export
+ * of a plugin module as a plugin (`getLegacyPlugins`), so that module may
+ * export `CursorPlugin` only.
+ */
+export async function loadClassicTools(options = {}) {
+    const configDir = options.configDirs?.[0] ?? opencodeGlobalConfigDirs()[0];
+    const candidates = [
+        ...(configDir
+            ? [path.join(configDir, "node_modules", "@opencode-ai", "plugin", "dist", "index.js")]
+            : []),
+        "@opencode-ai/plugin",
+    ];
+    const importModule = options.importModule ?? ((specifier) => import(specifier));
+    // The global config copy is the host-owned installation; bare import is a fallback.
+    for (const candidate of candidates) {
+        try {
+            const specifier = path.win32.isAbsolute(candidate) && !path.isAbsolute(candidate)
+                ? new URL(`file:///${candidate.replaceAll("\\", "/")}`).href
+                : path.isAbsolute(candidate)
+                    ? pathToFileURL(candidate).href
+                    : candidate;
+            const module = await importModule(specifier);
+            if (typeof module.tool === "function" && module.tool.schema) {
+                const factory = { tool: module.tool, schema: module.tool.schema };
+                return {
+                    webSearch: createOpenCodeWebSearchTool(factory),
+                    imageSave: createCursorImageSaveTool(factory),
+                };
+            }
+        }
+        catch {
+            // Try the next host-owned/normal resolution location.
+        }
+    }
+    // `tool()` is an identity helper; the fallback definitions use plain JSON
+    // Schema accepted by OpenCode's legacy registry when no Zod helper is present.
+    return { webSearch: openCodeWebSearchTool, imageSave: cursorImageSaveTool };
+}