@vidit19sharma/opencode-cursor-auth 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## 0.3.1 — 2026-10-16
+
+### Fixed
+
+- opencode crashed at startup on a fresh machine (`undefined is not an object (evaluating 'C.provider')`, and `C.auth` on `opencode auth login`) as soon as the plugin was enabled. opencode invokes **every named export** of a plugin module as a plugin; the entry module also exported `CursorAuthPlugin`, `keyProblem` and `parseContext`, so opencode called the helpers as plugins and tried to read hooks off their return values. The entry now exposes only `default`; helpers moved to `src/plugin.ts`. Affects 0.1.0–0.3.0. A test guards the export shape.
+
+## 0.3.0 — 2026-10-16
+
+### Breaking
+
+- The suffixed variant ids from 0.2.0 (`cursor/gpt-5.5-low`, `cursor/claude-opus-5-5-1m-max`, …) no longer exist; Cursor rejects them with 400 "Cannot use this model". Migrate `cursor/gpt-5.5-low` to model `cursor/gpt-5.5` + variant `low` (Ctrl+T in the TUI, or `variant:` in config).
+
+### Added
+
+- Cursor variants on opencode's native variant picker (Ctrl+T): the model list is the 47 base ids only, and every other Cursor variant is attached as an opencode model variant, named by the params that differ from Cursor's default (e.g. `low`, `272k-none`, `no-thinking`, `xhigh-fast`).
+- Variants are selectable in config with `variant: "<name>"` next to `model` in an agent entry.
+- `installation.md`: step-by-step install guide for AI coding agents (prerequisites, config edit, auth, verification, troubleshooting), shipped in the npm tarball; the README has a one-line prompt to hand to any LLM agent.
+- `spike/probe-models.ts`: probes every base model once and reports AVAILABLE / BLOCKED / OTHER for the logged-in account.
+
+### Changed
+
+- A base id now means Cursor's own default variant (`isDefault`), sends its params explicitly, and gets that variant's context limit; previously it implied the first-listed param values and under-reported context (`gpt-5.5`: 272k → 1M).
+- Models cache bumped to v4 `{name, context, params, variants, allowed}`; older cache files are refetched once.
+
+### Fixed
+
+- Blocked-model flags learned from 403s persist across the 24h catalog refresh (carried over by base id), so admin-blocked models stay hidden instead of reappearing; delete `models.json` to re-check.
+- An unknown variant param id or value (sent as `cursor_params`) returns 400 `invalid_request_error` before any Cursor agent is created or concurrency slot taken.
+
 ## 0.2.0 — 2026-10-16
 
 ### Added

package/README.md

@@ -12,8 +12,8 @@ The plugin bridges opencode's OpenAI-style chat requests to the official [`@curs
 - **Thinking blocks** — Cursor reasoning streams into opencode as proper thinking blocks (`reasoning_content`)
 - **Session resume** — conversations map to native Cursor agents (`Agent.resume`), in-memory and persisted to disk for 7 days, scoped per opencode session so parallel sub-agents never share an agent
 - **System prompts** — delivered via `AGENTS.md` in a per-session workspace (the `--system-prompt` flag is server-gated by Cursor)
-- **Dynamic model list with variants** — fetched live from `Cursor.models.list()`, cached 24h; every reasoning-effort / fast / 1M-context variant is its own model id
-- **Context limits** — each model publishes its Cursor context window, so opencode's auto-compaction and context indicator work
+- **Dynamic model list with variants** — fetched live from `Cursor.models.list()`, cached 24h; one id per model, with every reasoning-effort / thinking / fast / context variant on opencode's Ctrl+T variant picker
+- **Context limits** — each model publishes the context window of Cursor's default variant, so opencode's auto-compaction and context indicator work
 - **Real error statuses** — 400 / 401 / 403 / 429 / 502 instead of a 200 stream carrying an error
 - **Cancellation** — Esc or a sub-agent timeout cancels the Cursor run and closes the agent
 - **Concurrency cap and retry** — at most 4 Cursor runs at once (configurable); transient failures retried before the first byte
@@ -28,6 +28,14 @@ The plugin bridges opencode's OpenAI-style chat requests to the official [`@curs
 
 ## Install
 
+For AI agents — paste this into any LLM agent:
+
+```
+Install the @vidit19sharma/opencode-cursor-auth plugin and configure it by following: https://raw.githubusercontent.com/vidit19sharma/opencode-cursor-auth/main/installation.md
+```
+
+See [installation.md](installation.md) for the step-by-step agent instructions.
+
 Add the plugin to `~/.config/opencode/opencode.json`:
 
 ```json
@@ -69,15 +77,27 @@ Or pick any `cursor/*` model from the opencode model selector.
 opencode models | grep cursor/
 ```
 
-- **Base ids** (`cursor/gpt-5.5`) send no parameters, so Cursor applies its own defaults. Cursor's `default` model is exposed as `cursor/auto`.
-- **Variant ids** are the base id plus every non-default parameter value, in Cursor's parameter order. Boolean parameters use the parameter name. Examples: `cursor/gpt-5.5-low`, `cursor/gpt-5.5-high-fast`, `cursor/gpt-5.5-1m-extra-high`, `cursor/claude-opus-5-5-1m-max`.
-- The full catalog is currently about 485 ids from 47 models.
-- **Limits**: `limit.context` is the variant's context value, else the model's first listed context value, else 200k. `limit.output` is a fixed 32k accounting reserve (Cursor publishes no output cap and the bridge sends no `max_tokens`). Limits you set yourself in opencode config are kept.
-- **Unknown ids** are passed through to Cursor, which answers with its own 400.
+- **Base ids only** — one id per Cursor model (47 today: `cursor/auto`, `cursor/gpt-5.5`, `cursor/claude-opus-5-5`, …). A base id is Cursor's own default variant (`isDefault`) and sends its params explicitly. Cursor's `default` model is exposed as `cursor/auto`.
+- **Variants** — every other Cursor variant (reasoning effort, thinking, fast, context size) is an opencode model variant. In the TUI, select the model and press **Ctrl+T** to cycle them. Models with no variants (e.g. `gemini-3.1-pro`) show "No variants available".
+- **Variant names** are the params that differ from Cursor's default, joined by `-`: values as-is (`low`, `xhigh`, `272k`), a boolean switched on is the param name (`fast`, `thinking`), switched off is `no-<param>` (`no-fast`, `no-thinking`). Examples: gpt-5.5 → `low`, `extra-high`, `272k-high-fast`; claude-opus-5 → `no-thinking`, `max-fast`; grok-4.7 → `256k-low-no-fast`.
+- **In config**, set `variant` next to `model`:
+
+  ```json
+  { "agent": { "build": { "model": "cursor/gpt-5.5", "variant": "low" } } }
+  ```
+
+- **Limits**: `limit.context` is the default variant's context value, else the model's first listed context value, else 200k (gpt-5.5 and claude-opus-5-5 → 1M). `limit.output` is a fixed 32k accounting reserve (Cursor publishes no output cap and the bridge sends no `max_tokens`). Limits you set yourself in opencode config are kept.
+- **Unknown ids** are passed through to Cursor, which answers with its own 400. An unknown variant param returns 400 `invalid_request_error` before any Cursor agent is created.
 - **Blocked models**: Cursor's catalog has no per-account entitlement info. If Cursor rejects a model as "Model Blocked" (e.g. a team admin disabled it), the request fails with 403 `permission_error` carrying Cursor's message, and that model and all its variants are hidden from the list. Using a hidden id explicitly still sends it to Cursor. Blocked flags persist across catalog refreshes; delete `~/.cache/opencode-cursor-auth/models.json` to re-check.
 - **Offline / logged out**: the stale cache is used if present, otherwise only `cursor/auto`.
 
-The catalog is cached at `~/.cache/opencode-cursor-auth/models.json`; delete it to force a refresh.
+The catalog is cached for 24h at `~/.cache/opencode-cursor-auth/models.json`; delete it to force a refresh.
+
+### Migrating from 0.2.0
+
+The suffixed ids (`cursor/gpt-5.5-low`, `cursor/claude-opus-5-5-1m-max`, …) no longer exist; Cursor rejects them with 400 "Cannot use this model".
+Replace each with the base model plus a variant: `cursor/gpt-5.5-low` → `"model": "cursor/gpt-5.5", "variant": "low"`.
+The models cache is refetched once on upgrade.
 
 ## Configuration
 
@@ -103,7 +123,7 @@ opencode ──(OpenAI chat JSON)──> plugin fetch() ──> @cursor/sdk Agen
 - Each opencode tool is registered as a Cursor **custom tool** whose `execute()` parks a promise, emits an OpenAI `tool_calls` chunk, and resumes the *same* Cursor run when opencode sends the tool result back.
 - Conversation prefixes, plus the opencode session id (sent via the `chat.headers` hook), are hashed → mapped to Cursor agent IDs, so follow-up turns use `Agent.resume` instead of replaying history. The map persists at `~/.cache/opencode-cursor-auth/sessions.json`.
 - System messages are written to `AGENTS.md` in a per-session temp workspace and loaded via Cursor's project rules (`settingSources: ["project"]`). Workspaces are removed once no session references them.
-- Variant ids are mapped back to Cursor `ModelSelection` params (`{ id, params }`).
+- The selected variant reaches the plugin as `providerOptions.cursor`; `@ai-sdk/openai-compatible` puts it in the request body as top-level `cursor_params: [{ id, value }, …]`, which the bridge validates and maps to Cursor `ModelSelection.params`.
 - New turns take a slot from a FIFO semaphore (`OPENCODE_CURSOR_MAX_ACTIVE`); tool-result continuations reuse their run's slot. `Agent.create` / `Agent.resume` / `send` are attempted up to 3 times with jittered exponential backoff on 429, 5xx, and network errors, never after the first byte.
 - The HTTP reply opens on the first text or thinking delta, so failures before any content become real HTTP errors.
 - The request's abort signal and stream cancel cancel the Cursor run, close the agent, and release its slot.
@@ -112,7 +132,7 @@ opencode ──(OpenAI chat JSON)──> plugin fetch() ──> @cursor/sdk Agen
 
 | Status | When |
 | --- | --- |
-| 400 | Unknown model or bad argument (Cursor's message); also an expired tool-call continuation |
+| 400 | Unknown model or bad argument (Cursor's message), unknown variant param; also an expired tool-call continuation |
 | 401 | SDK key missing/expired, or Cursor rejects the key |
 | 403 | Model blocked for your account (`permission_error`) |
 | 429 | Cursor rate limit |
@@ -135,7 +155,8 @@ The test suite runs 13 scenarios: plain streaming, a full tool loop on one held
 
 - `systemPrompt` as a true harness replacement is feature-gated server-side by Cursor; system text is applied via `AGENTS.md` as a project rule (merged under Cursor's harness prompt).
 - The SDK spawns a `cursor-agent` worker per turn (~1–2 s startup on resume).
-- The model list is Cursor's full catalog (~485 ids). It has no entitlement info, so models your plan or team blocks only disappear after the first 403.
+- Cursor's catalog has no entitlement info, so models your plan or team blocks only disappear after the first 403.
+- `limit.context` is per model, not per variant: picking a smaller-context variant (e.g. gpt-5.5 `272k`) keeps the base model's 1M limit in opencode's context indicator and auto-compaction.
 - A run parked waiting for a tool result keeps its slot. Cursor-model sessions that spawn Cursor-model sub-agents nested deeper than `OPENCODE_CURSOR_MAX_ACTIVE` will stall; raise the limit if you fan out.
 - Usage/rate limits are whatever your Cursor plan enforces — the plugin adds none beyond the concurrency cap.
 

package/dist/bridge.d.ts

@@ -27,6 +27,7 @@ type OaBody = {
     messages: OaMessage[];
     tools?: OaTool[];
     stream?: boolean;
+    cursor_params?: unknown;
 };
 export declare function isTransient(err: unknown): boolean;
 export declare function withRetry<T>(fn: () => Promise<T>, signal?: AbortSignal, baseDelayMs?: number, retryable?: typeof isTransient): Promise<T>;

package/dist/bridge.js

@@ -14,7 +14,7 @@ import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { mkdtemp, readFile, writeFile } from "node:fs/promises";
 import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
-import { markBlocked, resolveModel } from "./models.js";
+import { markBlocked, resolveVariant } from "./models.js";
 // @cursor/sdk's internal logger writes "HH:MM:SS.mmm INFO ..." lines via
 // console.log unconditionally (no config/env to silence it, verified against
 // the esm bundle). Filter exactly those lines, pass everything else through.
@@ -592,6 +592,10 @@ export async function handleChatCompletion(body, apiKey, signal, scope) {
         }
         return reply.promise;
     }
+    // opencode wraps variant options as providerOptions.cursor; @ai-sdk/openai-compatible (name "cursor") spreads them into the body top level
+    const model = resolveVariant(body.model, body.cursor_params) ?? { id: body.model };
+    if (typeof model === "string")
+        return errorResponse(model, 400);
     // new turn: reuse the agent whose last-seen conversation matches our prefix
     const prefix = body.messages.slice(0, -1);
     const key = hashMessages(prefix, scope);
@@ -601,7 +605,7 @@ export async function handleChatCompletion(body, apiKey, signal, scope) {
     let cwd;
     let newSuffix = body.messages;
     const agentOptions = (cwd) => ({
-        model: resolveModel(body.model) ?? { id: body.model },
+        model,
         tools: ["mcp"],
         ...(apiKey ? { apiKey } : {}),
         local: { cwd, settingSources: ["project"], enableAgentRetries: true },

package/dist/index.d.ts

@@ -1,6 +1 @@
-import type { Plugin } from "@opencode-ai/plugin";
-import { type SdkAuthStatus } from "@cursor/sdk";
-export { parseContext } from "./models.js";
-export declare function keyProblem(status: SdkAuthStatus, nowMs: number): string | undefined;
-export declare const CursorAuthPlugin: Plugin;
-export default CursorAuthPlugin;
+export { CursorAuthPlugin as default } from "./plugin.js";

package/dist/index.js

@@ -1,138 +1,3 @@
-import { Cursor } from "@cursor/sdk";
-import { errorResponse, handleChatCompletion } from "./bridge.js";
-import { currentModels } from "./models.js";
-export { parseContext } from "./models.js";
-const BASE_URL = "http://cursor.local/v1";
-// Cursor publishes no output limit and the bridge never passes max_tokens to Cursor, so output is only an accounting reserve for opencode.
-const DEFAULT_CONTEXT = 200_000;
-const DEFAULT_OUTPUT = 32_000;
-export function keyProblem(status, nowMs) {
-    if (status.status !== "logged-in")
-        return "Cursor SDK key missing — run `opencode auth login` and pick Cursor";
-    if (typeof status.apiKeyExpiresAtMs === "number" && status.apiKeyExpiresAtMs <= nowMs)
-        return `Cursor SDK key expired on ${new Date(status.apiKeyExpiresAtMs).toISOString()} — run \`opencode auth login\` and pick Cursor`;
-    return undefined;
-}
-const KEY_CHECK_TTL_MS = 60_000;
-const EXPIRY_WARN_MS = 7 * 24 * 60 * 60 * 1000;
-let keyStatus;
-let warnedExpiry = false;
-async function checkKey() {
-    if (pastedApiKey || process.env.CURSOR_API_KEY)
-        return undefined;
-    const now = Date.now();
-    if (!keyStatus || now - keyStatus.at > KEY_CHECK_TTL_MS) {
-        keyStatus = { at: now, value: Cursor.auth.status().catch(() => undefined) };
-    }
-    const status = await keyStatus.value;
-    if (!status)
-        return undefined;
-    const exp = status.status === "logged-in" ? status.apiKeyExpiresAtMs : undefined;
-    if (!warnedExpiry && typeof exp === "number" && exp > now && exp - now <= EXPIRY_WARN_MS) {
-        warnedExpiry = true;
-        const days = Math.ceil((exp - now) / (24 * 60 * 60 * 1000));
-        console.error(`[opencode-cursor-auth] Cursor SDK key expires in ${days} days — run \`opencode auth login\` to renew`);
-    }
-    return keyProblem(status, now);
-}
-async function bodyText(input, init) {
-    const b = init?.body;
-    if (typeof b === "string")
-        return b;
-    if (b instanceof Uint8Array)
-        return new TextDecoder().decode(b);
-    if (input instanceof Request)
-        return input.text();
-    return "";
-}
-let pastedApiKey;
-async function cursorFetch(input, init) {
-    const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
-    if (url.includes("/chat/completions")) {
-        const problem = await checkKey();
-        if (problem)
-            return errorResponse(problem, 401);
-        const body = JSON.parse(await bodyText(input, init));
-        const signal = init?.signal ?? (input instanceof Request ? input.signal : undefined);
-        const scope = new Headers(init?.headers).get("x-opencode-session") ??
-            (input instanceof Request ? input.headers.get("x-opencode-session") : null) ??
-            undefined;
-        return handleChatCompletion(body, pastedApiKey, signal, scope);
-    }
-    if (url.includes("/models")) {
-        return Response.json({
-            object: "list",
-            data: Object.keys(await currentModels()).map((id) => ({ id, object: "model" })),
-        });
-    }
-    return Response.json({ error: { message: `unsupported endpoint: ${url}` } }, { status: 404 });
-}
-export const CursorAuthPlugin = async () => {
-    return {
-        config: async (config) => {
-            const providers = (config.provider ??= {});
-            const cursor = (providers["cursor"] ??= { models: {} });
-            cursor.npm ??= "@ai-sdk/openai-compatible";
-            cursor.name ??= "Cursor";
-            cursor.options = { ...cursor.options, baseURL: BASE_URL };
-            cursor.models ??= {};
-            for (const [id, { name, context }] of Object.entries(await currentModels())) {
-                cursor.models[id] ??= { name };
-                const model = cursor.models[id];
-                model.cost = { input: 0, output: 0, cache_read: 0, cache_write: 0 };
-                model.limit ??= { context: context ?? DEFAULT_CONTEXT, output: DEFAULT_OUTPUT };
-            }
-        },
-        "chat.headers": async (input, output) => {
-            if (input.model.providerID === "cursor")
-                output.headers["x-opencode-session"] = input.sessionID;
-        },
-        auth: {
-            provider: "cursor",
-            loader: async (getAuth) => {
-                const auth = await getAuth().catch(() => undefined);
-                if (auth && auth.type === "api" && auth.key !== "cursor-sdk-store")
-                    pastedApiKey = auth.key;
-                return {
-                    apiKey: "cursor-managed",
-                    baseURL: BASE_URL,
-                    fetch: cursorFetch,
-                };
-            },
-            methods: [
-                {
-                    type: "oauth",
-                    label: "Log in with Cursor (browser)",
-                    authorize: async () => {
-                        let resolveUrl;
-                        const urlReady = new Promise((r) => (resolveUrl = r));
-                        const login = Cursor.auth
-                            .login({
-                            apiKeyName: "opencode-cursor-auth",
-                            openBrowser: false,
-                            onLoginUrl: (url) => resolveUrl(url),
-                        })
-                            .catch((err) => err);
-                        const url = await Promise.race([urlReady, login.then(() => "")]);
-                        return {
-                            url: typeof url === "string" && url ? url : "https://cursor.com/dashboard",
-                            instructions: "Complete the login in your browser. The key is stored in ~/.cursor/sdk/auth.json.",
-                            method: "auto",
-                            callback: async () => {
-                                const result = await login;
-                                if (result instanceof Error)
-                                    return { type: "failed" };
-                                return { type: "success", key: "cursor-sdk-store" };
-                            },
-                        };
-                    },
-                },
-                {
-                    type: "api",
-                    label: "Paste a Cursor API key (cursor.com/dashboard)",
-                },
-            ],
-        },
-    };
-};
-export default CursorAuthPlugin;
+// opencode calls EVERY named export of a plugin module as a plugin, so this
+// entry must expose exactly one export; helpers live in plugin.ts.
+export { CursorAuthPlugin as default } from "./plugin.js";

package/dist/models.d.ts

@@ -1,13 +1,20 @@
 import { type ModelListItem, type ModelParameterValue, type ModelSelection } from "@cursor/sdk";
+type Variant = {
+    params: ModelParameterValue[];
+    context?: number;
+};
 export type ModelInfo = {
     name: string;
     context?: number;
-    base?: string;
     params?: ModelParameterValue[];
+    variants?: Record<string, Variant>;
+    allowed?: Record<string, string[]>;
     blocked?: true;
 };
 export declare function parseContext(m: ModelListItem): number | undefined;
 export declare function buildCatalog(list: ModelListItem[]): Record<string, ModelInfo>;
 export declare function currentModels(): Promise<Record<string, ModelInfo>>;
 export declare function resolveModel(opencodeId: string): ModelSelection | undefined;
+export declare function resolveVariant(opencodeId: string, params?: unknown): ModelSelection | string | undefined;
 export declare function markBlocked(opencodeId: string): void;
+export {};

package/dist/models.js

@@ -9,7 +9,7 @@ let catalog = {};
 let fetchedAt = 0;
 function saveCatalog() {
     mkdirSync(CACHE_DIR, { recursive: true });
-    writeFileSync(MODELS_CACHE_PATH, JSON.stringify({ version: 3, fetchedAt, models: catalog }));
+    writeFileSync(MODELS_CACHE_PATH, JSON.stringify({ version: 4, fetchedAt, models: catalog }));
 }
 function contextValue(raw) {
     const match = raw?.trim().match(/^(\d+)([km]?)$/i);
@@ -23,32 +23,44 @@ export function parseContext(m) {
 }
 export function buildCatalog(list) {
     const models = {};
-    const rename = (id) => (id === "default" ? "auto" : id);
     for (const m of list) {
-        const context = parseContext(m);
-        models[rename(m.id)] = { name: m.displayName ?? m.id, ...(context ? { context } : {}) };
-    }
-    for (const m of list) {
-        const base = rename(m.id);
+        const def = m.variants?.find((v) => v.isDefault) ?? m.variants?.[0];
+        const ctxOf = (ps) => contextValue(ps?.find((p) => p.id === "context")?.value);
+        const context = ctxOf(def?.params) ?? parseContext(m);
+        const allowed = {};
+        const allow = (id, value) => {
+            if (!(allowed[id] ??= []).includes(value))
+                allowed[id].push(value);
+        };
+        for (const p of m.parameters ?? [])
+            for (const v of p.values)
+                allow(p.id, v.value);
+        const variants = {};
         for (const v of m.variants ?? []) {
-            // id = base + non-default param values (first listed value is the default); "true" flags use the param id, e.g. gpt-5.5-low-fast
-            const parts = v.params
-                .filter((p) => m.parameters?.find((d) => d.id === p.id)?.values[0]?.value !== p.value)
-                .map((p) => (p.value === "true" ? p.id : p.value));
-            const id = [base, ...parts].join("-");
-            if (models[id])
+            for (const p of v.params)
+                allow(p.id, p.value);
+            const name = v.params
+                .filter((p) => def?.params.find((d) => d.id === p.id)?.value !== p.value)
+                .map((p) => (p.value === "true" ? p.id : p.value === "false" ? `no-${p.id}` : p.value))
+                .join("-");
+            if (!name || variants[name])
                 continue;
-            const context = contextValue(v.params.find((p) => p.id === "context")?.value) ?? models[base].context;
-            const label = v.displayName && v.displayName !== m.displayName ? v.displayName : parts.join(" ");
-            models[id] = { name: `${models[base].name} (${label})`, ...(context ? { context } : {}), base, params: v.params };
+            const vctx = ctxOf(v.params) ?? context;
+            variants[name] = { params: v.params, ...(vctx ? { context: vctx } : {}) };
         }
+        models[m.id === "default" ? "auto" : m.id] = {
+            name: m.displayName ?? m.id,
+            ...(context ? { context } : {}),
+            ...(def ? { params: def.params, allowed } : {}),
+            ...(Object.keys(variants).length ? { variants } : {}),
+        };
     }
     return models;
 }
 function loadCachedModels() {
     try {
         const raw = JSON.parse(readFileSync(MODELS_CACHE_PATH, "utf8"));
-        if (raw?.version === 3 && raw.models && Object.keys(raw.models).length > 0)
+        if (raw?.version === 4 && raw.models && Object.keys(raw.models).length > 0)
             return raw;
     }
     catch {
@@ -94,22 +106,29 @@ export function resolveModel(opencodeId) {
     const m = catalog[opencodeId];
     if (!m)
         return undefined;
-    return m.base && m.params ? { id: m.base, params: m.params } : { id: opencodeId };
+    return m.params ? { id: opencodeId, params: m.params } : { id: opencodeId };
+}
+export function resolveVariant(opencodeId, params) {
+    if (!Array.isArray(params))
+        return resolveModel(opencodeId);
+    loadCatalog();
+    const allowed = catalog[opencodeId]?.allowed ?? {};
+    for (const p of params) {
+        if (!allowed[p?.id]?.includes(p?.value))
+            return `unknown variant param ${p?.id}=${p?.value} for model ${opencodeId}`;
+    }
+    return { id: opencodeId, params: params.map((p) => ({ id: p.id, value: p.value })) };
 }
 export function markBlocked(opencodeId) {
     loadCatalog();
-    const base = catalog[opencodeId]?.base ?? opencodeId;
-    let changed = false;
-    for (const [id, m] of Object.entries(catalog)) {
-        if ((id === base || m.base === base) && !m.blocked)
-            m.blocked = changed = true;
+    const m = catalog[opencodeId];
+    if (!m || m.blocked)
+        return;
+    m.blocked = true;
+    try {
+        saveCatalog();
     }
-    if (changed) {
-        try {
-            saveCatalog();
-        }
-        catch {
-            // cache dir unwritable — the in-memory flag still hides it for this process
-        }
+    catch {
+        // cache dir unwritable — the in-memory flag still hides it for this process
     }
 }

package/dist/plugin.d.ts

@@ -0,0 +1,5 @@
+import type { Plugin } from "@opencode-ai/plugin";
+import { type SdkAuthStatus } from "@cursor/sdk";
+export { parseContext } from "./models.js";
+export declare function keyProblem(status: SdkAuthStatus, nowMs: number): string | undefined;
+export declare const CursorAuthPlugin: Plugin;

package/dist/plugin.js

@@ -0,0 +1,139 @@
+import { Cursor } from "@cursor/sdk";
+import { errorResponse, handleChatCompletion } from "./bridge.js";
+import { currentModels } from "./models.js";
+export { parseContext } from "./models.js";
+const BASE_URL = "http://cursor.local/v1";
+// Cursor publishes no output limit and the bridge never passes max_tokens to Cursor, so output is only an accounting reserve for opencode.
+const DEFAULT_CONTEXT = 200_000;
+const DEFAULT_OUTPUT = 32_000;
+export function keyProblem(status, nowMs) {
+    if (status.status !== "logged-in")
+        return "Cursor SDK key missing — run `opencode auth login` and pick Cursor";
+    if (typeof status.apiKeyExpiresAtMs === "number" && status.apiKeyExpiresAtMs <= nowMs)
+        return `Cursor SDK key expired on ${new Date(status.apiKeyExpiresAtMs).toISOString()} — run \`opencode auth login\` and pick Cursor`;
+    return undefined;
+}
+const KEY_CHECK_TTL_MS = 60_000;
+const EXPIRY_WARN_MS = 7 * 24 * 60 * 60 * 1000;
+let keyStatus;
+let warnedExpiry = false;
+async function checkKey() {
+    if (pastedApiKey || process.env.CURSOR_API_KEY)
+        return undefined;
+    const now = Date.now();
+    if (!keyStatus || now - keyStatus.at > KEY_CHECK_TTL_MS) {
+        keyStatus = { at: now, value: Cursor.auth.status().catch(() => undefined) };
+    }
+    const status = await keyStatus.value;
+    if (!status)
+        return undefined;
+    const exp = status.status === "logged-in" ? status.apiKeyExpiresAtMs : undefined;
+    if (!warnedExpiry && typeof exp === "number" && exp > now && exp - now <= EXPIRY_WARN_MS) {
+        warnedExpiry = true;
+        const days = Math.ceil((exp - now) / (24 * 60 * 60 * 1000));
+        console.error(`[opencode-cursor-auth] Cursor SDK key expires in ${days} days — run \`opencode auth login\` to renew`);
+    }
+    return keyProblem(status, now);
+}
+async function bodyText(input, init) {
+    const b = init?.body;
+    if (typeof b === "string")
+        return b;
+    if (b instanceof Uint8Array)
+        return new TextDecoder().decode(b);
+    if (input instanceof Request)
+        return input.text();
+    return "";
+}
+let pastedApiKey;
+async function cursorFetch(input, init) {
+    const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+    if (url.includes("/chat/completions")) {
+        const problem = await checkKey();
+        if (problem)
+            return errorResponse(problem, 401);
+        const body = JSON.parse(await bodyText(input, init));
+        const signal = init?.signal ?? (input instanceof Request ? input.signal : undefined);
+        const scope = new Headers(init?.headers).get("x-opencode-session") ??
+            (input instanceof Request ? input.headers.get("x-opencode-session") : null) ??
+            undefined;
+        return handleChatCompletion(body, pastedApiKey, signal, scope);
+    }
+    if (url.includes("/models")) {
+        return Response.json({
+            object: "list",
+            data: Object.keys(await currentModels()).map((id) => ({ id, object: "model" })),
+        });
+    }
+    return Response.json({ error: { message: `unsupported endpoint: ${url}` } }, { status: 404 });
+}
+export const CursorAuthPlugin = async () => {
+    return {
+        config: async (config) => {
+            const providers = (config.provider ??= {});
+            const cursor = (providers["cursor"] ??= { models: {} });
+            cursor.npm ??= "@ai-sdk/openai-compatible";
+            cursor.name ??= "Cursor";
+            cursor.options = { ...cursor.options, baseURL: BASE_URL };
+            cursor.models ??= {};
+            for (const [id, { name, context, variants }] of Object.entries(await currentModels())) {
+                cursor.models[id] ??= { name };
+                const model = cursor.models[id];
+                model.cost = { input: 0, output: 0, cache_read: 0, cache_write: 0 };
+                model.limit ??= { context: context ?? DEFAULT_CONTEXT, output: DEFAULT_OUTPUT };
+                if (variants)
+                    model.variants ??= Object.fromEntries(Object.entries(variants).map(([n, v]) => [n, { cursor_params: v.params }]));
+            }
+        },
+        "chat.headers": async (input, output) => {
+            if (input.model.providerID === "cursor")
+                output.headers["x-opencode-session"] = input.sessionID;
+        },
+        auth: {
+            provider: "cursor",
+            loader: async (getAuth) => {
+                const auth = await getAuth().catch(() => undefined);
+                if (auth && auth.type === "api" && auth.key !== "cursor-sdk-store")
+                    pastedApiKey = auth.key;
+                return {
+                    apiKey: "cursor-managed",
+                    baseURL: BASE_URL,
+                    fetch: cursorFetch,
+                };
+            },
+            methods: [
+                {
+                    type: "oauth",
+                    label: "Log in with Cursor (browser)",
+                    authorize: async () => {
+                        let resolveUrl;
+                        const urlReady = new Promise((r) => (resolveUrl = r));
+                        const login = Cursor.auth
+                            .login({
+                            apiKeyName: "opencode-cursor-auth",
+                            openBrowser: false,
+                            onLoginUrl: (url) => resolveUrl(url),
+                        })
+                            .catch((err) => err);
+                        const url = await Promise.race([urlReady, login.then(() => "")]);
+                        return {
+                            url: typeof url === "string" && url ? url : "https://cursor.com/dashboard",
+                            instructions: "Complete the login in your browser. The key is stored in ~/.cursor/sdk/auth.json.",
+                            method: "auto",
+                            callback: async () => {
+                                const result = await login;
+                                if (result instanceof Error)
+                                    return { type: "failed" };
+                                return { type: "success", key: "cursor-sdk-store" };
+                            },
+                        };
+                    },
+                },
+                {
+                    type: "api",
+                    label: "Paste a Cursor API key (cursor.com/dashboard)",
+                },
+            ],
+        },
+    };
+};

package/installation.md

@@ -0,0 +1,139 @@
+# Install @vidit19sharma/opencode-cursor-auth
+
+These instructions are designed for AI coding agents.
+
+The plugin lets opencode use a Cursor subscription through the official `@cursor/sdk`, in-process. Supported on macOS/Linux; Windows untested.
+
+## Prerequisites
+
+### Check opencode version
+
+```bash
+opencode --version
+```
+
+You should see `1.19` or newer. If older or missing, ask the user to install or upgrade opencode before continuing.
+
+### Check Node version
+
+```bash
+node --version
+```
+
+You should see `v22.13` or newer. opencode installs plugins with Bun, but `@cursor/sdk` spawns the `cursor-agent` binary and requires Node >= 22.13. If older, ask the user to upgrade Node.
+
+### Check the Cursor CLI
+
+```bash
+cursor-agent --version
+```
+
+If this prints a version, continue. If it fails with `command not found`, install it:
+
+```bash
+curl https://cursor.com/install -fsS | bash
+```
+
+Then open a new shell, or add `~/.local/bin` to `PATH`, and re-run `cursor-agent --version`.
+
+A Cursor subscription (Pro, Business, or team) is required. `cursor-agent login` is not required (the plugin has its own login) but is harmless.
+
+## Installation
+
+### Step 1: Remove the old open-cursor setup (only if present)
+
+If `~/.config/opencode/plugin/cursor-acp.js` exists or the opencode config has a `cursor-acp` provider, the user has the old `@rama_nigg/open-cursor` proxy setup. Remove it:
+
+1. Delete the `cursor-acp` block under `provider` in the opencode config.
+2. Delete the file: `rm ~/.config/opencode/plugin/cursor-acp.js`
+3. Uninstall it: `npm uninstall -g @rama_nigg/open-cursor`
+
+Skip this step if none of these exist.
+
+### Step 2: Add the plugin to the opencode config
+
+The config file is `~/.config/opencode/opencode.json`. Some users have `~/.config/opencode/opencode.jsonc` instead; edit whichever exists.
+
+If neither exists, create `~/.config/opencode/opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["@vidit19sharma/opencode-cursor-auth@latest"]
+}
+```
+
+If the file exists and has no top-level `plugin` array, add one:
+
+```json
+"plugin": ["@vidit19sharma/opencode-cursor-auth@latest"]
+```
+
+If a `plugin` array already exists, append `"@vidit19sharma/opencode-cursor-auth@latest"` and keep every existing entry.
+
+Do not add a `provider.cursor` block by hand. On startup the plugin registers the `cursor` provider and its model list automatically. No `npm install` is needed; opencode installs the package at startup.
+
+### Step 3: Authenticate
+
+Pick one method.
+
+**Browser login.** This step needs the user. Ask them to run:
+
+```bash
+opencode auth login
+```
+
+and choose provider **Cursor**, then **Log in with Cursor (browser)**. A browser opens; they sign in to Cursor. This mints a 90-day SDK key stored at `~/.cursor/sdk/auth.json` (written by `@cursor/sdk`, not by the plugin). When the key expires, requests return a 401 telling the user to run `opencode auth login` again; a warning is printed to stderr during the last 7 days.
+
+**API key.** In `opencode auth login`, choose **Cursor**, then **Paste a Cursor API key**. Keys come from cursor.com/dashboard (Integrations / API keys). Alternatively, set `CURSOR_API_KEY` in the environment before starting opencode.
+
+## Verification
+
+```bash
+opencode models | grep cursor/
+```
+
+You should see `cursor/auto`, `cursor/gpt-5.5`, `cursor/claude-opus-5-5`, and more. The first run fetches the catalog from Cursor (about 3 s); it is cached for 24 h at `~/.cache/opencode-cursor-auth/models.json`.
+
+Variants are not separate ids. In the TUI, press Ctrl+T on a cursor model to pick its effort, thinking, fast, or context variant.
+
+```bash
+opencode run -m cursor/gpt-5.5 "Reply with exactly: CURSOR-AUTH-OK"
+```
+
+You should see `CURSOR-AUTH-OK`. In some setups `opencode run` does not exit on its own because of other plugins; Ctrl-C after the reply is fine.
+
+Optional: to see which models the account is actually allowed to use, clone the repo, run `bun install`, then `bun spike/probe-models.ts`. It sends one tiny request per model.
+
+## Upgrading
+
+With `@latest` in the `plugin` array, restarting opencode picks up new versions. If it stays on an old version, clear the cached package and restart opencode:
+
+```bash
+rm -rf ~/.cache/opencode/packages/@vidit19sharma/opencode-cursor-auth@latest
+```
+
+## Done
+
+The plugin is installed. Every model the user's Cursor plan includes is available as `cursor/*` in opencode.
+
+## Troubleshooting
+
+- **`Cannot connect to API`, or nothing happens on cursor models**: the auth entry is missing. Run `opencode auth login` and pick Cursor.
+- **401 `Cursor SDK key missing/expired`**: run `opencode auth login`.
+- **403 `permission_error` "Model Blocked"**: a team admin disabled that model for the account. It is hidden from `opencode models` from then on; delete `~/.cache/opencode-cursor-auth/models.json` to re-check.
+- **400 `Cannot use this model`**: the model id is not in Cursor's catalog for this account.
+- **`cursor-agent: command not found` at request time**: install the Cursor CLI (see Prerequisites) and make sure it is on `PATH` for the shell that launches opencode.
+- **Model list empty or only `cursor/auto`**: the catalog fetch failed (offline or not logged in). Fix auth, delete `~/.cache/opencode-cursor-auth/models.json`, restart opencode.
+- **Stray `cursor-agent` processes**: check with `pgrep -fl cursor-agent`. A single `worker-server` is the SDK's idle singleton and is normal.
+
+### Paths
+
+| Path | Contents |
+| --- | --- |
+| `~/.cursor/sdk/auth.json` | SDK key from browser login |
+| `~/.cache/opencode-cursor-auth/models.json` | Model catalog, 24 h |
+| `~/.cache/opencode-cursor-auth/sessions.json` | Conversation to Cursor agent map, 7 days |
+| `~/.local/share/opencode/auth.json` | opencode's auth registry; the Cursor entry is a sentinel, the real key lives in the SDK file |
+
+See the [README](README.md) for more detail.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vidit19sharma/opencode-cursor-auth",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "OpenCode plugin that uses your Cursor subscription via the official @cursor/sdk \u2014 no proxy server, no separate login.",
   "type": "module",
   "main": "dist/index.js",
@@ -8,6 +8,7 @@
   "files": [
     "dist",
     "README.md",
+    "installation.md",
     "CHANGELOG.md",
     "LICENSE"
   ],