cursor-opencode-provider 0.7.5 → 0.8.0

package/dist/opencode2/integration.d.ts

@@ -1,4 +1,5 @@
-import type { CredentialValue, IntegrationDomain, IntegrationDraft } from "./types.js";
+import { type AccessTokenRequest } from "../auth-renewal.js";
+import type { CredentialOAuth, CredentialValue, IntegrationDomain, IntegrationDraft } from "./types.js";
 /**
  * Integration registration for the OpenCode 2.0 plugin — the replacement for the
  * classic plugin's `auth` hook (`methods` + `loader`).
@@ -9,15 +10,37 @@ import type { CredentialValue, IntegrationDomain, IntegrationDraft } from "./typ
 export declare const CURSOR_OAUTH_METHOD_ID = "oauth";
 /** Env vars that can supply a Cursor API key without running /connect. */
 export declare const CURSOR_ENV_NAMES: string[];
+/**
+ * Host-driven session renewal (`POST /oauth/token`, as Cursor's IDE does).
+ * OpenCode 2.0 calls this when the stored `expires` is within five minutes
+ * (`packages/core/src/integration.ts`, `connection.resolve`) and persists the
+ * result. A session this process already renewed in memory is handed over
+ * instead of renewed again. A transient failure returns the unchanged session
+ * with `expires` moved to the next allowed attempt, so the host keeps working
+ * and asks again later; only a session Cursor ended, or one that expired
+ * unrenewed, throws.
+ */
+export declare function refreshOAuth(credential: CredentialOAuth): Promise<CredentialOAuth>;
 /** Register the Cursor integration and its three connection methods. */
 export declare function applyCursorIntegration(draft: IntegrationDraft): void;
 /**
- * Turn a stored credential into a Cursor access token.
+ * Turn a stored credential into a Cursor access token. The two credential
+ * kinds are handled separately and never substitute for each other.
+ *
+ * - `oauth`: the session token, renewed in memory once it is due by Cursor's
+ *   IDE window (the host itself refreshes only in the last five minutes; it
+ *   then persists the renewal through `refreshOAuth`).
+ * - `key`: a raw `crsr_…` API key (from /connect or `CURSOR_API_KEY`),
+ *   exchanged for a short-lived JWT and re-exchanged near its expiry. Any
+ *   other value is an already-issued token and is used as-is.
  *
- * OAuth credentials already hold a JWT (the host refreshes them via `refresh`
- * above). A `key` credential is the raw `crsr_…` API key, which Cursor requires us
- * to exchange for a short-lived JWT — mirroring the classic plugin's behavior.
+ * Throws `CursorAuthError` when no usable token can be produced.
+ */
+export declare function accessTokenFromCredential(credential: CredentialValue | undefined, request?: AccessTokenRequest): Promise<string>;
+/**
+ * Current access token of the active Cursor connection, for a Run. Throws a
+ * `CursorAuthError` that says why when there is none.
  */
-export declare function accessTokenFromCredential(credential: CredentialValue | undefined): Promise<string | undefined>;
-/** Resolve the active Cursor connection into an access token, if any. */
+export declare function requireCursorAccessToken(integration: IntegrationDomain, request?: AccessTokenRequest): Promise<string>;
+/** Access token of the active Cursor connection, or undefined (model discovery). */
 export declare function resolveCursorAccessToken(integration: IntegrationDomain): Promise<string | undefined>;

package/dist/opencode2/integration.js

@@ -1,6 +1,9 @@
 import { CURSOR_WEBSITE_HOST } from "../shared.js";
 import { cursorApiBaseURL } from "../plugin-core.js";
-import { buildLoginUrl, decodeJwtExpiryMs, exchangeApiKey, generatePkceChallenge, generatePkceParams, isExpiringSoon, pollForTokens, refreshAccessToken, } from "../auth.js";
+import { buildLoginUrl, decodeJwtExpiryMs, generatePkceChallenge, generatePkceParams, isExchangeableApiKey, pollForTokens, } from "../auth.js";
+import { renewSessionIfDue, resolveApiKeyToken, } from "../auth-renewal.js";
+import { CursorAuthError, CursorProviderError } from "../errors.js";
+import { errorMessage } from "../debug.js";
 import { CURSOR_INTEGRATION_ID } from "./catalog.js";
 /**
  * Integration registration for the OpenCode 2.0 plugin — the replacement for the
@@ -15,6 +18,13 @@ export const CURSOR_ENV_NAMES = ["CURSOR_API_KEY"];
 function websiteURL() {
     return process.env.CURSOR_WEBSITE_URL ?? `https://${CURSOR_WEBSITE_HOST}`;
 }
+/** `expires` of a session credential: the JWT's own expiry, as OpenCode's built-in OAuth integrations store it. */
+function sessionExpires(token) {
+    return decodeJwtExpiryMs(token) ?? Date.now();
+}
+function sessionTokensOf(credential) {
+    return { accessToken: credential.access, refreshToken: credential.refresh || credential.access };
+}
 /** Browser (PKCE) login: open URL, then poll until Cursor hands back tokens. */
 async function authorizeOAuth() {
     const params = generatePkceParams();
@@ -30,23 +40,38 @@ async function authorizeOAuth() {
             methodID: CURSOR_OAUTH_METHOD_ID,
             access: result.accessToken,
             refresh: result.refreshToken,
-            expires: decodeJwtExpiryMs(result.accessToken) ?? Date.now(),
+            expires: sessionExpires(result.accessToken),
         })),
     };
 }
 /**
- * Renew an expiring Cursor JWT. The host calls this lazily when the stored
- * credential is close to expiry, so it must not assume it runs on every request.
+ * Host-driven session renewal (`POST /oauth/token`, as Cursor's IDE does).
+ * OpenCode 2.0 calls this when the stored `expires` is within five minutes
+ * (`packages/core/src/integration.ts`, `connection.resolve`) and persists the
+ * result. A session this process already renewed in memory is handed over
+ * instead of renewed again. A transient failure returns the unchanged session
+ * with `expires` moved to the next allowed attempt, so the host keeps working
+ * and asks again later; only a session Cursor ended, or one that expired
+ * unrenewed, throws.
  */
-async function refreshOAuth(credential) {
-    const tokens = await refreshAccessToken(credential.refresh, cursorApiBaseURL());
+export async function refreshOAuth(credential) {
+    const renewal = await renewSessionIfDue(sessionTokensOf(credential), { baseUrl: cursorApiBaseURL() });
+    const methodID = credential.methodID || CURSOR_OAUTH_METHOD_ID;
+    const metadata = credential.metadata === undefined ? {} : { metadata: credential.metadata };
+    if (renewal.renewed) {
+        return {
+            type: "oauth",
+            methodID,
+            access: renewal.accessToken,
+            refresh: renewal.accessToken,
+            expires: sessionExpires(renewal.accessToken),
+            ...metadata,
+        };
+    }
     return {
-        type: "oauth",
-        methodID: credential.methodID || CURSOR_OAUTH_METHOD_ID,
-        access: tokens.accessToken,
-        refresh: tokens.refreshToken,
-        expires: decodeJwtExpiryMs(tokens.accessToken) ?? Date.now(),
-        ...(credential.metadata === undefined ? {} : { metadata: credential.metadata }),
+        ...credential,
+        methodID,
+        expires: renewal.retryAt ?? sessionExpires(credential.access),
     };
 }
 /** Register the Cursor integration and its three connection methods. */
@@ -75,48 +100,52 @@ export function applyCursorIntegration(draft) {
     });
 }
 /**
- * Turn a stored credential into a Cursor access token.
+ * Turn a stored credential into a Cursor access token. The two credential
+ * kinds are handled separately and never substitute for each other.
  *
- * OAuth credentials already hold a JWT (the host refreshes them via `refresh`
- * above). A `key` credential is the raw `crsr_…` API key, which Cursor requires us
- * to exchange for a short-lived JWT — mirroring the classic plugin's behavior.
+ * - `oauth`: the session token, renewed in memory once it is due by Cursor's
+ *   IDE window (the host itself refreshes only in the last five minutes; it
+ *   then persists the renewal through `refreshOAuth`).
+ * - `key`: a raw `crsr_…` API key (from /connect or `CURSOR_API_KEY`),
+ *   exchanged for a short-lived JWT and re-exchanged near its expiry. Any
+ *   other value is an already-issued token and is used as-is.
+ *
+ * Throws `CursorAuthError` when no usable token can be produced.
  */
-export async function accessTokenFromCredential(credential) {
-    if (!credential)
-        return undefined;
-    if (credential.type === "oauth") {
-        if (credential.access && !isExpiringSoon(credential.access))
-            return credential.access;
-        if (!credential.refresh)
-            return credential.access || undefined;
-        try {
-            return (await refreshOAuth(credential)).access;
-        }
-        catch {
-            // Fall back to the existing token; the call may still succeed.
-            return credential.access || undefined;
-        }
+export async function accessTokenFromCredential(credential, request = {}) {
+    const force = request.forceRefresh === true;
+    if (credential?.type === "oauth") {
+        return (await renewSessionIfDue(sessionTokensOf(credential), { baseUrl: cursorApiBaseURL(), force })).accessToken;
     }
-    if (credential.type === "key") {
-        // Already a JWT (e.g. exchanged by an earlier run) — use it directly.
-        if (!credential.key.startsWith("crsr_"))
+    if (credential?.type === "key") {
+        if (!isExchangeableApiKey(credential.key))
             return credential.key;
-        try {
-            return (await exchangeApiKey(credential.key, cursorApiBaseURL())).accessToken;
-        }
-        catch {
-            return undefined;
-        }
+        return (await resolveApiKeyToken(credential.key, { baseUrl: cursorApiBaseURL(), force })).accessToken;
     }
-    return undefined;
+    throw new CursorAuthError("No Cursor login found; connect Cursor first", { code: "no_credential" });
 }
-/** Resolve the active Cursor connection into an access token, if any. */
-export async function resolveCursorAccessToken(integration) {
+/**
+ * Current access token of the active Cursor connection, for a Run. Throws a
+ * `CursorAuthError` that says why when there is none.
+ */
+export async function requireCursorAccessToken(integration, request = {}) {
+    let credential;
     try {
         const connection = await integration.connection.active(CURSOR_INTEGRATION_ID);
-        if (!connection)
-            return undefined;
-        return await accessTokenFromCredential(await integration.connection.resolve(connection));
+        credential = connection ? await integration.connection.resolve(connection) : undefined;
+    }
+    catch (error) {
+        // The host's resolve runs our refreshOAuth; keep its classified error.
+        if (error instanceof CursorProviderError)
+            throw error;
+        throw new CursorAuthError(`Cursor login could not be loaded (${errorMessage(error)})`, { cause: error });
+    }
+    return accessTokenFromCredential(credential, request);
+}
+/** Access token of the active Cursor connection, or undefined (model discovery). */
+export async function resolveCursorAccessToken(integration) {
+    try {
+        return await requireCursorAccessToken(integration);
     }
     catch {
         return undefined;

package/dist/plan-execution-kickoff.js

@@ -11,7 +11,7 @@
  */
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { trace } from "./debug.js";
+import { errorMessage, trace } from "./debug.js";
 /** Upstream `PlanExitTool` wording — keep verbatim so behaviour matches OpenCode. */
 export function createPlanExecutionKickoffText(planPath) {
     const where = planPath.trim() || "the plan";
@@ -149,7 +149,7 @@ export async function flushPlanExecutionKickoff(sessionID, options = {}) {
         return true;
     }
     catch (error) {
-        const detail = error instanceof Error ? error.message : String(error);
+        const detail = errorMessage(error);
         const message = `The approved plan could not start execution: ${detail}. ` +
             "The plan remains active and can be retried.";
         state.status = "failed";

package/dist/plugin-opencode2.js

@@ -7,7 +7,7 @@ import { sessionActivity } from "./activity.js";
 import { fetchOpenCodeWebSearchText, parseExaWebSearchResults, } from "./web-tools.js";
 import { captureCursorShellResult, cursorShellEnvForCommand, prepareCursorShellArgs, releaseCursorShellEnv, sanitizeRegisteredCursorShellOutput, } from "./shell-timeout.js";
 import { applyCursorProviderInventory, CURSOR_INTEGRATION_ID } from "./opencode2/catalog.js";
-import { applyCursorIntegration, resolveCursorAccessToken } from "./opencode2/integration.js";
+import { applyCursorIntegration, requireCursorAccessToken, resolveCursorAccessToken, } from "./opencode2/integration.js";
 import { exposeDirectMcpTools, rememberDirectMcpNamespaces } from "./opencode2/mcp-direct.js";
 import { registerTodoTools } from "./opencode2/todo-tools.js";
 import { OPENCODE_2_TOOL_DIALECT } from "./protocol/tools.js";
@@ -140,26 +140,20 @@ const plugin = {
         let sourceConnection;
         // ── Credentials ─────────────────────────────────────────
         await track(ctx.integration.transform(applyCursorIntegration));
-        let cachedToken;
         let tokenInflight;
         /**
-         * Cache only a *successful* resolution.
+         * Current token for model discovery and endpoint warmup, or undefined.
          *
-         * On a fresh install `setup()` runs before the user has connected, so the
-         * first attempt necessarily returns nothing. Memoizing that would pin the
-         * plugin to "no credentials" for the whole process and models would never
-         * load, even after a successful /connect.
+         * Resolved every time (concurrent callers share one attempt) and never
+         * memoized: on a fresh install `setup()` runs before the user has
+         * connected, and a long-running daemon outlives any single token. Both
+         * the host resolve and the renewal layer are cheap until a renewal is due.
          */
         const accessToken = async () => {
-            if (cachedToken)
-                return cachedToken;
             tokenInflight ??= resolveCursorAccessToken(ctx.integration).finally(() => {
                 tokenInflight = undefined;
             });
-            const token = await tokenInflight;
-            if (token)
-                cachedToken = token;
-            return token;
+            return tokenInflight;
         };
         const refreshSourceConnection = async () => {
             try {
@@ -210,10 +204,11 @@ const plugin = {
                 return;
             if (!isCursorPackage(event.package, event.model.providerID))
                 return;
-            const token = await accessToken();
             event.sdk = createSdk({
                 name: event.model.providerID || CURSOR_PROVIDER_ID,
-                ...(token ? { accessToken: token } : {}),
+                // Resolved per Run open: this SDK lives as long as the daemon, so
+                // a token captured here would outlive its expiry.
+                getAccessToken: (request) => requireCursorAccessToken(ctx.integration, request),
                 // Static fallback only. This hook fires once per model/package, not
                 // per session, and 2.0 runs one daemon across many projects — the
                 // real per-request directory comes from `x-opencode-directory`
@@ -467,7 +462,6 @@ const plugin = {
         retry.unref?.();
         void ensureModels().catch(() => { });
         const onCredentialSwitch = () => {
-            cachedToken = undefined;
             modelsLoaded = false;
             credentialGeneration++;
         };

package/dist/plugin.d.ts

@@ -1,12 +1,2 @@
 import type { Hooks, PluginInput } from "@opencode-ai/plugin";
-export { modelInfoToConfig, modelsToConfig, thinkingSuffixBaseNames } from "./model-config.js";
-export declare function loadClassicTools(options?: {
-    importModule?: (specifier: string) => Promise<{
-        tool?: any;
-    }>;
-    configDirs?: string[];
-}): Promise<{
-    webSearch: any;
-    imageSave: any;
-}>;
 export declare function CursorPlugin(input: PluginInput): Promise<Hooks>;

package/dist/plugin.js

@@ -1,57 +1,45 @@
-import path from "node:path";
-import { pathToFileURL } from "node:url";
 import { CURSOR_API_HOST, CURSOR_COMPACTION_OPTION, CURSOR_HOST_AGENT_OPTION, CURSOR_PROVIDER_ID, CURSOR_WEBSITE_HOST, } from "./shared.js";
 import { cursorApiBaseURL, cursorGetServerConfigTelemetryEnabled } from "./plugin-core.js";
-import { pollForTokens, exchangeApiKey, refreshAccessToken, isExpiringSoon, generatePkceParams, generatePkceChallenge, buildLoginUrl, decodeJwtExpiryMs } from "./auth.js";
+import { pollForTokens, exchangeApiKey, isExpiringSoon, generatePkceParams, generatePkceChallenge, buildLoginUrl, decodeJwtExpiryMs, isExchangeableApiKey } from "./auth.js";
+import { renewSessionIfDue, resolveApiKeyToken, } from "./auth-renewal.js";
+import { CursorAuthError } from "./errors.js";
+import { errorMessage, trace } from "./debug.js";
 import { readCache, discoverModels, isCacheFresh } from "./models.js";
-// Re-exported for API compatibility: tests and downstream code import these
-// from "./plugin.js". Canonical home is ./model-config.ts, which stays free of
-// host plugin imports so the OpenCode 2.0 entrypoint can share it.
 import { modelsToConfig } from "./model-config.js";
-export { modelInfoToConfig, modelsToConfig, thinkingSuffixBaseNames } from "./model-config.js";
-import { opencodeGlobalCacheDir, opencodeGlobalConfigDirs } from "./context/paths.js";
+import { loadClassicTools } from "./classic-tools.js";
+import { opencodeGlobalCacheDir } from "./context/paths.js";
 import { readStoredAuth } from "./context/auth-store.js";
 import { resolveAgentUrl } from "./agent-url.js";
 import { captureCursorShellResult, cursorShellEnvForCall, cursorShellOriginalCommand, prepareCursorShellArgs, releaseCursorShellEnv, sanitizeRegisteredCursorShellOutput, setCursorShellPath, } from "./shell-timeout.js";
 import { sessionActivity } from "./activity.js";
-import { createOpenCodeWebSearchTool, openCodeWebSearchTool } from "./web-search-tool.js";
-import { createCursorImageSaveTool, cursorImageSaveTool } from "./image-save-tool.js";
 import { createPlanExecutionKickoffText, setPlanExecutionKickoff, } from "./plan-execution-kickoff.js";
 import { dispatchHostEventBridge } from "./host-event-bridge.js";
 const MODULE_URL = new URL("./index.js", import.meta.url).href;
-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.
-        }
+/**
+ * Raw `crsr_` key behind an API-key login: under `metadata.apiKey` (saved at
+ * login, and merged there from the prompt inputs by OpenCode's CLI), or as
+ * `key` itself when OpenCode stored the typed key without our exchange.
+ */
+function storedApiKey(auth) {
+    const fromMetadata = auth.metadata?.apiKey;
+    if (typeof fromMetadata === "string" && isExchangeableApiKey(fromMetadata))
+        return fromMetadata;
+    return isExchangeableApiKey(auth.key) ? auth.key : undefined;
+}
+function sessionTokens(auth) {
+    // Cursor's IDE refreshes with the stored refresh token and then stores the
+    // new access token as both; an empty refresh field means the same.
+    return { accessToken: auth.access, refreshToken: auth.refresh || auth.access };
+}
+/** Whether `latest` is still the credential a renewal started from. */
+function isSameCredential(latest, started) {
+    if (latest.type === "oauth" && started.type === "oauth") {
+        return latest.access === started.access && latest.refresh === started.refresh;
     }
-    // `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 };
+    if (latest.type === "api" && started.type === "api") {
+        return latest.key === started.key && storedApiKey(latest) === storedApiKey(started);
+    }
+    return false;
 }
 export async function CursorPlugin(input) {
     const cacheDir = opencodeGlobalCacheDir();
@@ -76,13 +64,7 @@ export async function CursorPlugin(input) {
             });
         }
         : undefined);
-    // Last access token successfully resolved in this plugin instance. Config's
-    // loadModels can only read OpenCode's durable store (auth.json /
-    // OPENCODE_AUTH_CONTENT); auth.loader gets live credentials via getAuth().
-    // Those usually match, but after a refresh where persistAuthBestEffort fails,
-    // getAuth() may still see the old credentials while we already hold a usable
-    // token here — keep it so the loader can still discover models.
-    let sessionAccessToken;
+    let lastPersistAttempt;
     async function persistAuth(body) {
         await input.client.auth.set({
             path: { id: CURSOR_PROVIDER_ID },
@@ -110,64 +92,93 @@ export async function CursorPlugin(input) {
      * and config share the same underlying credentials when possible.
      */
     async function authForLoader(getAuth) {
-        return (await getAuth()) ?? (await authFromStore());
+        // getAuth is also called long after the loader returned (per-Run token
+        // resolution); never let a host-side failure there hide the durable store.
+        return (await getAuth().catch(() => undefined)) ?? (await authFromStore());
     }
-    async function resolveAccessToken(auth) {
-        if (auth.type === "api") {
-            let accessToken = auth.key;
-            const refreshToken = auth.metadata?.refreshToken;
-            // API-key exchange returns a short-lived JWT stored as `key`. Refresh
-            // it the same way as OAuth when it is expiring / already expired.
-            if (refreshToken && isExpiringSoon(auth.key)) {
-                try {
-                    const newTokens = await refreshAccessToken(refreshToken, apiBaseURL);
-                    accessToken = newTokens.accessToken;
-                    await persistAuthBestEffort({
-                        type: "api",
-                        key: newTokens.accessToken,
-                        metadata: {
-                            ...auth.metadata,
-                            refreshToken: newTokens.refreshToken,
-                        },
-                    });
-                }
-                catch {
-                    // refresh failed — keep the existing key; the next call may still work
-                }
-            }
-            if (accessToken)
-                sessionAccessToken = accessToken;
-            return accessToken;
+    /**
+     * Persist a renewed credential unless the stored one changed meanwhile (a
+     * re-login, or another process's renewal): never overwrite newer state.
+     */
+    async function persistRenewal(started, next, readCurrent) {
+        // One attempt per renewed token: when the write fails (read-only store,
+        // injected OPENCODE_AUTH_CONTENT) later Runs keep the in-memory token
+        // instead of re-reading and re-writing the store on every turn.
+        const token = next.type === "oauth" ? next.access : next.type === "api" ? next.key : undefined;
+        if (token === undefined || token === lastPersistAttempt)
+            return;
+        lastPersistAttempt = token;
+        const latest = await readCurrent().catch(() => undefined);
+        if (!latest || !isSameCredential(latest, started)) {
+            trace("auth: stored Cursor credential changed during renewal; keeping the stored one");
+            return;
         }
-        if (auth.type === "oauth") {
-            if (!isExpiringSoon(auth.access)) {
-                sessionAccessToken = auth.access;
-                return auth.access;
-            }
-            if (!auth.refresh)
-                return undefined;
-            try {
-                const newTokens = await refreshAccessToken(auth.refresh, apiBaseURL);
-                // Preserve optional OAuth fields (v2 Auth / plugin may carry these).
-                const extras = auth;
-                // Use the new token even if persisting back to OpenCode fails.
-                await persistAuthBestEffort({
-                    type: "oauth",
-                    access: newTokens.accessToken,
-                    refresh: newTokens.refreshToken,
-                    expires: decodeJwtExpiryMs(newTokens.accessToken) ?? Date.now(),
-                    ...(extras.accountId !== undefined ? { accountId: extras.accountId } : {}),
-                    ...(extras.enterpriseUrl !== undefined ? { enterpriseUrl: extras.enterpriseUrl } : {}),
-                });
-                sessionAccessToken = newTokens.accessToken;
-                return newTokens.accessToken;
-            }
-            catch {
-                return undefined;
-            }
+        await persistAuthBestEffort(next);
+    }
+    /** Browser-login session: renew when due (or forced) and persist the result. */
+    async function resolveSession(auth, readCurrent, force = false) {
+        const renewal = await renewSessionIfDue(sessionTokens(auth), { baseUrl: apiBaseURL, force });
+        if (renewal.renewed) {
+            // Preserve optional OAuth fields (v2 Auth / plugin may carry these).
+            const extras = auth;
+            await persistRenewal(auth, {
+                type: "oauth",
+                access: renewal.accessToken,
+                refresh: renewal.accessToken,
+                expires: decodeJwtExpiryMs(renewal.accessToken) ?? Date.now(),
+                ...(extras.accountId !== undefined ? { accountId: extras.accountId } : {}),
+                ...(extras.enterpriseUrl !== undefined ? { enterpriseUrl: extras.enterpriseUrl } : {}),
+            }, readCurrent);
+        }
+        return renewal;
+    }
+    /** API-key login: re-exchange the stored raw key when the JWT nears expiry. */
+    async function resolveApiKeyLogin(auth, readCurrent, force = false) {
+        const apiKey = storedApiKey(auth);
+        if (!apiKey) {
+            // Saved by an older version that kept only the exchanged JWT and its
+            // refresh token. Cursor renews API-key logins only by exchanging the key.
+            if (!isExpiringSoon(auth.key, 30))
+                return auth.key;
+            throw new CursorAuthError("This Cursor API-key login was saved without the key, so it cannot be renewed; sign in again with the API key", { code: "api_key_missing" });
+        }
+        const token = await resolveApiKeyToken(apiKey, {
+            baseUrl: apiBaseURL,
+            ...(isExchangeableApiKey(auth.key) ? {} : { seed: auth.key }),
+            force,
+        });
+        if (token.renewed) {
+            const { refreshToken: _unused, ...metadata } = auth.metadata ?? {};
+            await persistRenewal(auth, {
+                type: "api",
+                key: token.accessToken,
+                metadata: { ...metadata, apiKey },
+            }, readCurrent);
         }
+        return token.accessToken;
+    }
+    /**
+     * Current access token for the stored credential. The two credential kinds
+     * are handled by separate paths and never substitute for each other.
+     */
+    async function resolveAccessToken(auth, readCurrent, force = false) {
+        if (auth.type === "oauth")
+            return (await resolveSession(auth, readCurrent, force)).accessToken;
+        if (auth.type === "api")
+            return resolveApiKeyLogin(auth, readCurrent, force);
         return undefined;
     }
+    /** Best-effort token for startup work (model discovery, endpoint warmup). */
+    async function startupAccessToken(auth, readCurrent) {
+        try {
+            return await resolveAccessToken(auth, readCurrent);
+        }
+        catch (error) {
+            // Surfaced again, with the same message, when a Run asks for a token.
+            trace(`auth: no usable Cursor token at startup (${errorMessage(error)})`);
+            return undefined;
+        }
+    }
     async function loadModels() {
         const cached = await readCache(cacheDir);
         if (cached?.models.length && isCacheFresh(cached)) {
@@ -178,7 +189,7 @@ export async function CursorPlugin(input) {
         // or old-schema caches here so this process materializes the new model set.
         const auth = await authFromStore();
         if (auth) {
-            const accessToken = await resolveAccessToken(auth);
+            const accessToken = await startupAccessToken(auth, authFromStore);
             if (accessToken) {
                 try {
                     const models = await discoverModels(accessToken, cacheDir, { baseURL: apiBaseURL });
@@ -352,7 +363,9 @@ export async function CursorPlugin(input) {
                                 type: "success",
                                 key: result.accessToken,
                                 provider: CURSOR_PROVIDER_ID,
-                                metadata: { refreshToken: result.refreshToken },
+                                // Keep the raw key: Cursor renews an API-key login only by
+                                // exchanging the key again (its refresh token is never used).
+                                metadata: { apiKey },
                             };
                         }
                         catch {
@@ -362,10 +375,11 @@ export async function CursorPlugin(input) {
                 },
             ],
             async loader(getAuth) {
-                const auth = await authForLoader(getAuth);
-                // Prefer credentials from getAuth/store; if refresh already succeeded in
-                // loadModels but persist failed, fall back to the in-memory session token.
-                const accessToken = (auth ? await resolveAccessToken(auth) : undefined) ?? sessionAccessToken;
+                const readCurrent = () => authForLoader(getAuth);
+                const auth = await readCurrent();
+                // Model discovery and endpoint warmup need a token: like any request,
+                // that renews a due session (or expiring API-key JWT) first.
+                const accessToken = auth ? await startupAccessToken(auth, readCurrent) : undefined;
                 if (accessToken) {
                     // Skip when config already filled a fresh cache (avoids a second
                     // AvailableModels round-trip + background refresh on cold start).
@@ -384,8 +398,23 @@ export async function CursorPlugin(input) {
                         telemetryEnabled: cursorGetServerConfigTelemetryEnabled(),
                     }).catch(() => { });
                 }
+                // Asked for on every Run open: reads the live credential (so a
+                // re-login applies without a restart), renews it when due, persists the
+                // renewal. This is how OpenCode's own OAuth providers hand over
+                // credentials (codex, xai, copilot: a `fetch` that calls getAuth() per
+                // request): no token is placed in the options, which OpenCode serves
+                // unredacted from /provider; a function is dropped there.
+                const getAccessToken = async (request) => {
+                    const current = await readCurrent();
+                    const token = current
+                        ? await resolveAccessToken(current, readCurrent, request?.forceRefresh === true)
+                        : undefined;
+                    if (!token)
+                        throw new CursorAuthError("No Cursor login found; sign in to Cursor", { code: "no_credential" });
+                    return token;
+                };
                 return {
-                    ...(accessToken ? { accessToken } : {}),
+                    getAccessToken,
                     workspaceRoot: input.directory,
                     cacheDir,
                 };