@vidit19sharma/opencode-cursor-auth 0.2.0 → 0.3.2

package/CHANGELOG.md

@@ -2,6 +2,49 @@
 
 All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## 0.3.2 — 2026-10-16
+
+### Added
+
+- `npx @vidit19sharma/opencode-cursor-auth setup` — adds the plugin to opencode config idempotently (`--dry-run`, `--config`).
+
+### Fixed
+
+- The first request before `opencode auth login` hung in opencode's connect loop: without a `cursor` auth entry opencode skips the plugin's auth loader and dials the dummy `http://cursor.local/v1`. The plugin now seeds its auth entry (only when none exists), so the loader runs and returns a clear 401 telling you to run `opencode auth login`.
+
+### Changed
+
+- Docs no longer claim the Cursor CLI (`cursor-agent`) is required; `@cursor/sdk` talks to Cursor's backend directly.
+
+## 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
@@ -23,11 +23,23 @@ The plugin bridges opencode's OpenAI-style chat requests to the official [`@curs
 ## Requirements
 
 - Node >= 22.13 (opencode runs plugins on Bun, which also works)
-- [`cursor-agent` CLI](https://cursor.com/docs/cli) installed (`curl https://cursor.com/install -fsS | bash`) — the SDK's local executor uses it
 - A Cursor subscription
 
 ## Install
 
+All three methods end with `opencode auth login` (next section).
+
+### 1. One command (npx)
+
+```sh
+npx @vidit19sharma/opencode-cursor-auth setup
+```
+
+Adds the plugin to the `plugin` array of your opencode config (`~/.config/opencode/opencode.json[c]`, or creates `opencode.json`); running it again is a no-op.
+`--dry-run` shows the change without writing; `--config <path>` targets a specific file. A `.jsonc` file with comments is never rewritten — you get the one-line manual edit instead.
+
+### 2. Manual
+
 Add the plugin to `~/.config/opencode/opencode.json`:
 
 ```json
@@ -36,7 +48,17 @@ Add the plugin to `~/.config/opencode/opencode.json`:
 }
 ```
 
-The plugin auto-registers a `cursor` provider — no manual provider config needed.
+The plugin auto-registers the `cursor` provider — no manual provider config needed.
+
+### 3. Let an AI agent do it
+
+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.
 
 ## Authenticate
 
@@ -69,15 +91,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
 
@@ -95,7 +129,7 @@ The catalog is cached at `~/.cache/opencode-cursor-auth/models.json`; delete it
 ## How it works
 
 ```
-opencode ──(OpenAI chat JSON)──> plugin fetch() ──> @cursor/sdk Agent ──> cursor-agent ──> Cursor backend
+opencode ──(OpenAI chat JSON)──> plugin fetch() ──> @cursor/sdk Agent ──> Cursor backend
          <─(SSE stream)────────  bridge  <──(typed deltas: text / thinking / tool calls)
 ```
 
@@ -103,7 +137,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 +146,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 |
@@ -127,6 +161,8 @@ bun install
 bun run build        # tsc → dist/
 bun run test         # end-to-end bridge tests (requires Cursor login, uses real Cursor usage)
 bun run spike        # raw @cursor/sdk validation
+bun run test:cli     # exercises the npx setup command against temp config dirs (7 cases)
+bun run smoke        # packs the plugin and loads it in a pristine HOME (startup, auth login, first request before login)
 ```
 
 The test suite runs 13 scenarios: plain streaming, a full tool loop on one held run, in-memory and disk-persisted session resume, AGENTS.md system-prompt delivery, mid-stream abort, error statuses, session scoping, context limits and key checks, model variants, the concurrency cap, retry semantics, and blocked models.
@@ -134,8 +170,8 @@ The test suite runs 13 scenarios: plain streaming, a full tool loop on one held
 ## Known limitations
 
 - `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/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import process from "node:process";
+const PKG = "@vidit19sharma/opencode-cursor-auth";
+const ENTRY = `${PKG}@latest`;
+const HELP = `Usage: npx ${PKG} [setup] [--dry-run] [--config <path>]
+
+Adds "${ENTRY}" to the "plugin" array of your opencode config.
+Idempotent: does nothing if any ${PKG} entry is already present.
+
+  --dry-run        print what would change, write nothing
+  --config <path>  edit this file instead of the auto-detected one
+  --help           show this help
+
+Config lookup: --config, $OPENCODE_CONFIG, then opencode.jsonc / opencode.json in
+$OPENCODE_CONFIG_DIR, $XDG_CONFIG_HOME/opencode or ~/.config/opencode.
+
+Exit codes: 0 ok or already installed, 2 cannot edit safely (manual edit printed), 1 error.`;
+const NEXT = `Next steps:
+  1. Restart opencode
+  2. opencode auth login -> Cursor -> Log in with Cursor (browser)
+  3. opencode models | grep cursor/`;
+const MANUAL = `Add this to the top-level "plugin" array of your opencode config (create it if missing):
+  "plugin": ["${ENTRY}"]`;
+// Strips // and /* */ comments and trailing commas outside double-quoted strings; does not handle single-quoted strings or other JSON5 syntax.
+const stripJsonc = (s) => s
+    .replace(/("(?:\\.|[^"\\])*")|\/\/[^\n]*|\/\*[\s\S]*?\*\//g, (_m, str) => str ?? "")
+    .replace(/("(?:\\.|[^"\\])*")|,(\s*[}\]])/g, (_m, str, close) => str ?? close);
+function tryParse(s) {
+    try {
+        return JSON.parse(s);
+    }
+    catch {
+        return undefined;
+    }
+}
+function main(argv) {
+    let dryRun = false;
+    let explicit;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--help" || a === "-h")
+            return console.log(HELP), 0;
+        else if (a === "--dry-run")
+            dryRun = true;
+        else if (a === "--config")
+            explicit = argv[++i];
+        else if (a !== "setup")
+            return console.error(`Unknown argument: ${a}\n\n${HELP}`), 1;
+    }
+    if (argv.includes("--config") && !explicit)
+        return console.error("--config needs a path"), 1;
+    const env = process.env;
+    const dir = env.OPENCODE_CONFIG_DIR || join(env.XDG_CONFIG_HOME || join(homedir(), ".config"), "opencode");
+    const file = resolve(explicit ||
+        env.OPENCODE_CONFIG ||
+        ["opencode.jsonc", "opencode.json"].map((f) => join(dir, f)).find((f) => existsSync(f)) ||
+        join(dir, "opencode.json"));
+    const exists = existsSync(file);
+    const original = exists ? readFileSync(file, "utf8") : "";
+    const strict = exists ? tryParse(original) : { $schema: "https://opencode.ai/config.json" };
+    const config = (strict ?? tryParse(stripJsonc(original)));
+    console.log(`Config: ${file}${exists ? "" : " (will be created)"}`);
+    if (!config || typeof config !== "object" || Array.isArray(config)) {
+        console.error(`Cannot parse ${file}; not editing it.\n${MANUAL}`);
+        return 2;
+    }
+    const leftovers = [];
+    const provider = config.provider;
+    if (provider && typeof provider === "object" && "cursor-acp" in provider)
+        leftovers.push(`  - remove the "cursor-acp" block under "provider" in ${file}`);
+    const acp = join(dir, "plugin", "cursor-acp.js");
+    if (existsSync(acp))
+        leftovers.push(`  - rm ${JSON.stringify(acp)}`);
+    if (leftovers.length)
+        console.log(`Notice: old open-cursor setup found (nothing was deleted). To remove it:\n${leftovers.join("\n")}\n  - npm uninstall -g @rama_nigg/open-cursor`);
+    const plugins = config.plugin ?? [];
+    if (!Array.isArray(plugins)) {
+        console.error(`"plugin" in ${file} is not an array; not editing it.\n${MANUAL}`);
+        return 2;
+    }
+    if (plugins.some((p) => typeof p === "string" && p.startsWith(PKG))) {
+        console.log(`Already installed: ${PKG} is in "plugin". File left untouched.\n\n${NEXT}`);
+        return 0;
+    }
+    if (strict === undefined) {
+        console.error(`${file} has comments or trailing commas; not rewriting it (that would drop them).\n${MANUAL}`);
+        return 2;
+    }
+    config.plugin = [...plugins, ENTRY];
+    const next = JSON.stringify(config, null, 2) + "\n";
+    if (dryRun) {
+        console.log(`Dry run: would ${exists ? "update" : "create"} ${file} with:\n${next}`);
+        return 0;
+    }
+    mkdirSync(dirname(file), { recursive: true });
+    if (exists)
+        writeFileSync(`${file}.bak-cursor-auth`, original);
+    writeFileSync(`${file}.tmp`, next);
+    renameSync(`${file}.tmp`, file);
+    console.log(`Added "${ENTRY}" to "plugin"${exists ? ` (backup: ${file}.bak-cursor-auth)` : ""}.\n\n${NEXT}`);
+    return 0;
+}
+try {
+    process.exitCode = main(process.argv.slice(2));
+}
+catch (e) {
+    console.error(`Unexpected error: ${e instanceof Error ? e.message : e}`);
+    process.exitCode = 1;
+}

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,152 @@
+import { Cursor } from "@cursor/sdk";
+import { errorResponse, handleChatCompletion } from "./bridge.js";
+import { currentModels } from "./models.js";
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+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 });
+}
+async function seedAuthEntry(client) {
+    if (!client?.auth?.set)
+        return;
+    const file = join(process.env.XDG_DATA_HOME || join(homedir(), ".local", "share"), "opencode", "auth.json");
+    const entries = await readFile(file, "utf8").then(JSON.parse, (err) => (err.code === "ENOENT" ? {} : undefined));
+    if (!entries || typeof entries !== "object" || "cursor" in entries)
+        return;
+    await client.auth.set({ path: { id: "cursor" }, body: { type: "api", key: "cursor-sdk-store" } });
+}
+export const CursorAuthPlugin = async (input) => {
+    seedAuthEntry(input?.client).catch(() => { });
+    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,132 @@
+# 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. `@cursor/sdk` requires Node >= 22.13. If older, ask the user to upgrade Node.
+
+A Cursor subscription (Pro, Business, or team) is required.
+
+## 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
+
+**Preferred, if you can run shell commands:**
+
+```bash
+npx @vidit19sharma/opencode-cursor-auth setup
+```
+
+It adds the plugin idempotently (exit 0 = added or already present) and lists any open-cursor leftovers from Step 1 without deleting them. Exit 2 means it could not edit the file safely (e.g. a `.jsonc` with comments); it prints the exact edit, which you then make by hand as described below. Use `--dry-run` to preview.
+
+**Fallback: edit the file by hand.** 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.
+- **Request hangs with no error**: `opencode auth login` was never run for Cursor; run it (0.3.2+ seeds the entry automatically so you get a 401 message instead).
+- **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.
+
+### 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,13 +1,17 @@
 {
   "name": "@vidit19sharma/opencode-cursor-auth",
-  "version": "0.2.0",
+  "version": "0.3.2",
   "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",
   "types": "dist/index.d.ts",
+  "bin": {
+    "opencode-cursor-auth": "dist/cli.js"
+  },
   "files": [
     "dist",
     "README.md",
+    "installation.md",
     "CHANGELOG.md",
     "LICENSE"
   ],
@@ -30,10 +34,12 @@
     "auth"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && chmod +x dist/cli.js",
     "test": "bun spike/e2e-bridge.ts",
     "spike": "bun spike/validate-sdk.ts",
-    "prepublishOnly": "tsc"
+    "smoke": "bash scripts/fresh-home-smoke.sh",
+    "prepublishOnly": "npm run build",
+    "test:cli": "npm run build && bash spike/cli-setup.test.sh"
   },
   "dependencies": {
     "@cursor/sdk": "^1.0.36"