cursor-opencode-provider 0.7.6 → 0.8.1

package/dist/plugin-opencode2.js

@@ -1,22 +1,23 @@
 import { CURSOR_PROVIDER_ID, CURSOR_COMPACTION_OPTION, CURSOR_HOST_AGENT_OPTION, } from "./shared.js";
 import { createSdk, cursorApiBaseURL, cursorGetServerConfigTelemetryEnabled, isCursorPackage } from "./plugin-core.js";
-import { opencodeGlobalCacheDir } from "./context/paths.js";
+import { opencode2PlanDir, opencodeGlobalCacheDir, setNativePlansDir } from "./context/paths.js";
 import { discoverModels, isCacheFresh, readCache } from "./models.js";
 import { resolveAgentUrl } from "./agent-url.js";
 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 { registerCursorImageSaveTool } from "./opencode2/image-save-tool.js";
 import { OPENCODE_2_TOOL_DIALECT } from "./protocol/tools.js";
 import { clearSessionTodos } from "./todo-store.js";
 import { markCompactionSession } from "./compaction-marker.js";
 import { getSessionDirectory, markSessionDirectory } from "./session-directory.js";
+import { rememberHostSkillFiles } from "./context/skills.js";
 import { trace } from "./debug.js";
-import { cancelPlanExecutionKickoff, createPlanExecutionKickoffText, setPlanExecutionKickoff, } from "./plan-execution-kickoff.js";
-import { cancelHostAgentModeSwitch, setHostAgentModeSwitch, } from "./host-agent-mode.js";
+import { cancelHostAgentModeSwitch, hostAgentSwitchPromptText, setHostAgentModeSwitch, } from "./host-agent-mode.js";
 import { clearActiveCursorMode, getActiveCursorMode, normalizeSwitchModeId, setActiveCursorMode, } from "./protocol/switch-mode.js";
 import { CursorPlugin } from "./plugin.js";
 /**
@@ -92,45 +93,36 @@ const plugin = {
     setup: async (ctx) => {
         const cacheDir = opencodeGlobalCacheDir();
         const workspaceRoot = ctx.location?.directory || process.cwd();
+        // CreatePlan writes where OpenCode 2.0's Plan agent keeps plan files.
+        // OpenCode 2.0 sets a plugin up once per location instance and again on a
+        // plugin reload, then disposes older setups: each cleanup removes only
+        // what its own setup installed.
+        const disposeNativePlansDir = setNativePlansDir(opencode2PlanDir());
+        let disposeHostAgentModeSwitch;
+        trace(`opencode2 plugin: setup directory=${workspaceRoot}`);
         const hasShellEnvHook = typeof ctx.shell?.hook === "function";
-        const admitPlanKickoff = typeof ctx.session.synthetic === "function"
-            ? ctx.session.synthetic
-            : ctx.session.prompt;
-        if (typeof ctx.session.switchAgent === "function" && typeof admitPlanKickoff === "function") {
+        if (typeof ctx.session.switchAgent === "function") {
             const switchAgent = ctx.session.switchAgent;
-            setPlanExecutionKickoff(async ({ sessionID, planPath }) => {
-                await switchAgent({ sessionID, agent: "build" });
-                try {
-                    await admitPlanKickoff({
+            const continueTurn = typeof ctx.session.synthetic === "function"
+                ? ctx.session.synthetic
+                : typeof ctx.session.prompt === "function"
+                    ? ctx.session.prompt
+                    : undefined;
+            disposeHostAgentModeSwitch = setHostAgentModeSwitch(async ({ sessionID, targetModeID }) => {
+                const agent = normalizeSwitchModeId(targetModeID) === "plan"
+                    || normalizeSwitchModeId(targetModeID) === "spec"
+                    ? "plan"
+                    : "build";
+                await switchAgent({ sessionID, agent });
+                // switchAgent only publishes AgentSelected and leaves the session idle.
+                // Continue under the new agent the same way OpenCode 1.x promptAsync does.
+                if (continueTurn) {
+                    await continueTurn({
                         sessionID,
-                        text: createPlanExecutionKickoffText(planPath),
+                        text: hostAgentSwitchPromptText(agent),
                     });
                 }
-                catch (error) {
-                    // Switching and admitting input are separate public APIs. Restore the
-                    // plan agent if admission fails so the shared retry state is honest:
-                    // the plan remains active rather than silently leaving the session in
-                    // build mode with no execution turn.
-                    await switchAgent({ sessionID, agent: "plan" }).catch(() => { });
-                    throw error;
-                }
-            });
-        }
-        else {
-            setPlanExecutionKickoff(undefined);
-        }
-        if (typeof ctx.session.switchAgent === "function") {
-            const switchAgent = ctx.session.switchAgent;
-            setHostAgentModeSwitch(async ({ sessionID, targetModeID }) => {
-                const mode = normalizeSwitchModeId(targetModeID);
-                await switchAgent({
-                    sessionID,
-                    agent: mode === "plan" || mode === "spec" ? "plan" : "build",
-                });
-            });
-        }
-        else {
-            setHostAgentModeSwitch(undefined);
+            }, continueTurn ? { resumesTurn: true } : {});
         }
         const registrations = [];
         const track = async (p) => {
@@ -140,26 +132,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 +196,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`
@@ -267,6 +254,7 @@ const plugin = {
             // them as direct catalog tools (`codemode: false` + output schema) if
             // the host does not already own those names. When off, register none.
             registerTodoTools(draft);
+            registerCursorImageSaveTool(draft, ctx);
             // MCP tools default into Code Mode. Move every server that did not
             // explicitly opt in onto the direct catalog so this provider can
             // advertise them to Cursor (issue #29 still routes via CallDynamicTool).
@@ -380,6 +368,20 @@ const plugin = {
         // last known session directory ahead of this Location's static root.
         // Scoped by the host to this provider: other providers' requests never
         // reach the callback, so the header cannot leak to their endpoints.
+        // Skill files for RequestContext path-desc `agent_skills` (see context/skills.ts).
+        const rememberSkillFiles = async () => {
+            if (!ctx.skill)
+                return;
+            try {
+                const listed = await ctx.skill.list();
+                // skill.list is bound to this plugin Location. A session may have
+                // moved; never relabel this catalog with the session's new directory.
+                rememberHostSkillFiles(listed.location.directory, listed.data);
+            }
+            catch (error) {
+                trace(`model.request: skill.list failed: ${String(error)}`);
+            }
+        };
         await track(ctx.session.hook("model.request", async (event) => {
             const current = await ctx.session
                 .get({ sessionID: event.sessionID })
@@ -392,6 +394,7 @@ const plugin = {
             const directory = current ?? getSessionDirectory(event.sessionID) ?? ctx.location?.directory;
             if (!directory)
                 return;
+            await rememberSkillFiles();
             event.headers = {
                 ...event.headers,
                 "x-opencode-directory": encodeURIComponent(directory),
@@ -467,7 +470,6 @@ const plugin = {
         retry.unref?.();
         void ensureModels().catch(() => { });
         const onCredentialSwitch = () => {
-            cachedToken = undefined;
             modelsLoaded = false;
             credentialGeneration++;
         };
@@ -475,8 +477,9 @@ const plugin = {
         return async () => {
             clearInterval(retry);
             unsubscribe?.();
-            setPlanExecutionKickoff(undefined);
-            setHostAgentModeSwitch(undefined);
+            disposeHostAgentModeSwitch?.();
+            disposeNativePlansDir();
+            trace(`opencode2 plugin: cleanup directory=${workspaceRoot}`);
             for (const registration of registrations.reverse()) {
                 await registration.dispose().catch(() => { });
             }
@@ -535,7 +538,6 @@ function applySessionActivity(event, onCredentialSwitch) {
                 sessionActivity.removeSession(id);
                 clearSessionTodos(id);
                 clearActiveCursorMode(id);
-                cancelPlanExecutionKickoff(id);
                 cancelHostAgentModeSwitch(id);
             }
             break;

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,88 +1,105 @@
-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";
+import { createPromptHostAgentModeSwitch, setHostAgentModeSwitch } from "./host-agent-mode.js";
+import { isHostPlanFileResolved, resolveHostPlanFile } from "./host-plan-file.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;
+    }
+    if (latest.type === "api" && started.type === "api") {
+        return latest.key === started.key && storedApiKey(latest) === storedApiKey(started);
+    }
+    return false;
+}
+/** Names of the host's own user-selectable primary agents, from `app.agents()`. */
+function primaryAgentNames(response) {
+    const list = Array.isArray(response)
+        ? response
+        : Array.isArray(response?.data)
+            ? response.data
+            : undefined;
+    if (!list)
+        return undefined;
+    const names = new Set();
+    for (const item of list) {
+        if (typeof item?.name !== "string" || item.mode === "subagent" || item.hidden === true)
+            continue;
+        names.add(item.name);
     }
-    // `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 };
+    return names;
+}
+/**
+ * Install the OpenCode 1.x host-agent switch. Returns the agent-list refresh,
+ * which the caller runs once the host serves requests: the list is read from
+ * the host's own API, and a failed read leaves SwitchMode provider-owned.
+ */
+function installPromptHostAgentModeSwitch(input, sessionClient, promptAsync) {
+    const app = input.client?.app;
+    const agents = app?.agents;
+    // Nothing to install; a switch another entrypoint installed stays in place.
+    if (typeof promptAsync !== "function" || typeof agents !== "function")
+        return undefined;
+    let primary;
+    const refresh = () => agents.call(app)
+        .then((response) => { primary = primaryAgentNames(response) ?? primary; })
+        .catch((error) => trace(`host-agent-mode: agent list unavailable: ${errorMessage(error)}`));
+    const { apply, accepts } = createPromptHostAgentModeSwitch(async ({ sessionID, agent, text }) => {
+        await promptAsync.call(sessionClient, {
+            path: { id: sessionID },
+            body: { agent, parts: [{ type: "text", text, synthetic: true }] },
+        });
+        void refresh();
+    }, () => primary);
+    setHostAgentModeSwitch(apply, { resumesTurn: true, accepts });
+    return refresh;
 }
 export async function CursorPlugin(input) {
     const cacheDir = opencodeGlobalCacheDir();
     const apiBaseURL = cursorApiBaseURL();
     const classicTools = await loadClassicTools();
-    // Install the OpenCode plan-exit-shaped kickoff only when the OpenCode client
-    // exposes that structural API. Without it, no synthetic kickoff is registered.
     const sessionClient = input.client?.session;
     const promptAsync = sessionClient?.promptAsync;
-    setPlanExecutionKickoff(typeof promptAsync === "function"
-        ? async ({ sessionID, planPath }) => {
-            await promptAsync.call(sessionClient, {
-                path: { id: sessionID },
-                body: {
-                    agent: "build",
-                    parts: [{
-                            type: "text",
-                            text: createPlanExecutionKickoffText(planPath),
-                            synthetic: true,
-                        }],
-                },
-            });
-        }
-        : 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;
+    // Cursor SwitchMode without an advertised plan_enter selects the host's
+    // primary agent the OpenCode 1.x way once its Run has ended. The OpenCode 2.0
+    // entrypoint replaces this with `session.switchAgent` in its own setup().
+    const refreshHostAgents = installPromptHostAgentModeSwitch(input, sessionClient, promptAsync);
+    let hostAgentsLoaded;
+    const sessionGet = sessionClient?.get;
+    const getSession = typeof sessionGet === "function"
+        ? (sessionID) => sessionGet.call(sessionClient, { path: { id: sessionID } })
+        : undefined;
+    let lastPersistAttempt;
     async function persistAuth(body) {
         await input.client.auth.set({
             path: { id: CURSOR_PROVIDER_ID },
@@ -110,64 +127,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 +224,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 });
@@ -269,6 +315,22 @@ export async function CursorPlugin(input) {
             // Carry the canonical OpenCode id so an incompatible Cursor checkpoint
             // is rotated instead of resuming the prior agent's prompt.
             output.options[CURSOR_HOST_AGENT_OPTION] = hookInput.agent;
+            // First Cursor request: the host now serves its API, so read its agents
+            // before any Run can raise SwitchMode. Concurrent first requests share
+            // the one read; later requests find it settled.
+            hostAgentsLoaded ??= refreshHostAgents?.();
+            await hostAgentsLoaded;
+            // Know the session's own plan file (OpenCode's `Session.plan`) before the
+            // Run starts, so CreatePlan records the plan where the plan agent and
+            // plan_exit read it. It is fixed per session, so resolve it once.
+            if (hookInput.agent !== "compaction" && getSession && !isHostPlanFileResolved(hookInput.sessionID)) {
+                await resolveHostPlanFile({
+                    sessionID: hookInput.sessionID,
+                    getSession,
+                    worktree: input.worktree || input.project?.worktree,
+                    vcs: !!input.project?.vcs,
+                });
+            }
             // OpenCode's compaction pipeline invokes the LLM with agent="compaction".
             // Carry that stable runtime fact into LanguageModelV3 providerOptions so
             // the provider never has to guess from an empty tool list.
@@ -352,7 +414,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 +426,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 +449,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,
                 };