@vidit19sharma/opencode-cursor-auth 0.3.1 → 0.3.3

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## 0.3.3 — 2026-10-16
+
+### Added
+
+- `npx @vidit19sharma/opencode-cursor-auth update` — removes opencode's cached copy of the plugin so the next opencode start installs the current release. opencode resolves `@latest` once at first install and never re-checks, so users were silently stuck on the version they first installed (`--dry-run` supported).
+- Mocked plugin unit tests (`bun run test:plugin`) covering key handling, expiry, headless login URL passthrough and auth-entry seeding.
+
+### Fixed
+
+- Pressing Esc before the first byte (during agent setup) returned HTTP 502 "aborted"; it now propagates as a proper abort.
+- `@cursor/sdk` INFO/WARN log lines leaked into the opencode TUI: the lines are ANSI-coloured when stdout is a TTY, so the filter never matched there. Colours are stripped before matching and the filter is re-asserted per request.
+- An empty or whitespace API key stored via the paste method silently fell back to the SDK key store; it now returns 401 `invalid_api_key`.
+- A failure after content has already streamed emits a single SSE `error` frame and closes without `[DONE]` (covered by a test).
+
+## 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

package/README.md

@@ -23,18 +23,22 @@ 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
 
-For AI agents — paste this into any LLM agent:
+All three methods end with `opencode auth login` (next section).
 
-```
-Install the @vidit19sharma/opencode-cursor-auth plugin and configure it by following: https://raw.githubusercontent.com/vidit19sharma/opencode-cursor-auth/main/installation.md
+### 1. One command (npx)
+
+```sh
+npx @vidit19sharma/opencode-cursor-auth setup
 ```
 
-See [installation.md](installation.md) for the step-by-step agent instructions.
+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`:
 
@@ -44,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
 
@@ -71,6 +85,18 @@ opencode run -m cursor/auto "hello"
 
 Or pick any `cursor/*` model from the opencode model selector.
 
+## Upgrading
+
+```sh
+npx @vidit19sharma/opencode-cursor-auth update
+```
+
+Then restart opencode. opencode pins `@latest` to the version it first installed and never re-checks npm, so this deletes that cached copy and opencode installs the current release on next start. Tell-tale sign you need it: Ctrl+T shows no variants, or features from the changelog are missing. Manual equivalent:
+
+```sh
+rm -rf ~/.cache/opencode/packages/@vidit19sharma/opencode-cursor-auth@latest
+```
+
 ## Models
 
 ```sh
@@ -115,7 +141,7 @@ The models cache is refetched once on upgrade.
 ## 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)
 ```
 
@@ -147,6 +173,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.
@@ -154,7 +182,6 @@ 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).
 - 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.

package/dist/bridge.d.ts

@@ -1,3 +1,4 @@
+export declare function ensureQuietConsole(): void;
 type ContentPart = {
     type: string;
     text?: string;
@@ -34,6 +35,7 @@ export declare function withRetry<T>(fn: () => Promise<T>, signal?: AbortSignal,
 export declare function _setMaxActive(n: number): void;
 export declare function errorResponse(err: unknown, status?: number): Response;
 export declare function _resetForTest(): void;
+export declare function _failAfterFirstDelta(message: string | null): void;
 export declare function _stats(): {
     held: number;
     sessions: number;

package/dist/bridge.js

@@ -15,16 +15,28 @@ import { mkdtemp, readFile, writeFile } from "node:fs/promises";
 import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
 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.
-const SDK_LOG_LINE = /^\d{2}:\d{2}:\d{2}\.\d{3} (TRACE|DEBUG|INFO|WARN|ERROR)\s/;
-const originalConsoleLog = console.log.bind(console);
-console.log = (...args) => {
-    if (typeof args[0] === "string" && SDK_LOG_LINE.test(args[0]))
-        return;
-    originalConsoleLog(...args);
-};
+// @cursor/sdk has no log-level switch: it prints "HH:MM:SS.mmm INFO ..." through
+// whatever console.* is installed at call time, ANSI-coloured when stdout is a
+// TTY (the opencode TUI). Match after stripping colours; re-wrap per request so
+// a host that replaces console.* after plugin load cannot bypass the filter.
+const SDK_LOG_LINE = /^\d{2}:\d{2}:\d{2}\.\d{3} (TRACE|DEBUG|INFO|WARN)\s/;
+const ANSI = /\x1b\[[0-9;]*m/g;
+const QUIET = Symbol.for("opencode-cursor-auth.quiet");
+export function ensureQuietConsole() {
+    for (const m of ["log", "info", "warn", "debug"]) {
+        const current = console[m];
+        if (current[QUIET])
+            continue;
+        const wrapped = (...args) => {
+            if (typeof args[0] === "string" && SDK_LOG_LINE.test(args[0].replace(ANSI, "")))
+                return;
+            current(...args);
+        };
+        wrapped[QUIET] = true;
+        console[m] = wrapped;
+    }
+}
+ensureQuietConsole();
 function textOf(content) {
     if (typeof content === "string")
         return content;
@@ -63,6 +75,7 @@ function errorBody(err, status = statusFor(err)) {
     };
 }
 const abortError = () => new DOMException("aborted", "AbortError");
+const isAbort = (err) => err?.name === "AbortError";
 export function isTransient(err) {
     const e = (typeof err === "object" && err !== null ? err : {});
     if (e.name === "AbortError")
@@ -84,7 +97,9 @@ export async function withRetry(fn, signal, baseDelayMs = 1000, retryable = isTr
             return await fn();
         }
         catch (err) {
-            if (attempt >= 2 || signal?.aborted || !retryable(err))
+            if (signal?.aborted || isAbort(err))
+                throw abortError();
+            if (attempt >= 2 || !retryable(err))
                 throw err;
             const delay = Math.min(baseDelayMs * 2 ** attempt * (0.75 + Math.random() * 0.5), 30_000);
             await new Promise((r) => {
@@ -438,6 +453,9 @@ function attachSignal(held, signal) {
     held.detachSignal = null;
     if (!signal)
         return;
+    // listeners never fire on an already-aborted signal (abort during Agent.create/resume)
+    if (signal.aborted)
+        return abortHeld(held);
     const onAbort = () => abortHeld(held);
     signal.addEventListener("abort", onAbort, { once: true });
     held.detachSignal = () => signal.removeEventListener("abort", onAbort);
@@ -465,7 +483,10 @@ function teardownHeld(held) {
     heldByAgent.delete(held.agent.agentId);
 }
 function failHeld(held, err) {
+    if (isAbort(err))
+        return abortHeld(held);
     teardownHeld(held);
+    held.run?.cancel().catch(() => { });
     if (statusFor(err) === 403)
         markBlocked(held.model);
     if (held.response && !held.opened) {
@@ -544,6 +565,10 @@ export function _resetForTest() {
     agentByToolCallId.clear();
     sessionsLoaded = false;
 }
+let failAfterFirstDelta = null;
+export function _failAfterFirstDelta(message) {
+    failAfterFirstDelta = message;
+}
 export function _stats() {
     return {
         held: heldByAgent.size,
@@ -557,6 +582,7 @@ export function _stats() {
 export async function handleChatCompletion(body, apiKey, signal, scope) {
     if (signal?.aborted)
         throw new DOMException("aborted", "AbortError");
+    ensureQuietConsole();
     await loadSessions();
     const streaming = body.stream !== false;
     const reply = deferred();
@@ -579,6 +605,8 @@ export async function handleChatCompletion(body, apiKey, signal, scope) {
         held.response = sse?.response ?? null;
         held.opened = false;
         attachSignal(held, signal);
+        if (held.done)
+            return reply.promise;
         attachSink(held, sink);
         for (const m of body.messages) {
             if (m.role !== "tool" || !m.tool_call_id)
@@ -630,7 +658,7 @@ export async function handleChatCompletion(body, apiKey, signal, scope) {
         catch (err) {
             releaseSlot();
             releaseCwd(cwd);
-            if (signal?.aborted)
+            if (signal?.aborted || isAbort(err))
                 throw abortError();
             return errorResponse(err);
         }
@@ -660,6 +688,8 @@ export async function handleChatCompletion(body, apiKey, signal, scope) {
     const self = held;
     heldByAgent.set(agent.agentId, held);
     attachSignal(held, signal);
+    if (held.done)
+        return reply.promise;
     attachSink(held, sink);
     const customTools = {};
     for (const t of body.tools ?? []) {
@@ -676,7 +706,12 @@ export async function handleChatCompletion(body, apiKey, signal, scope) {
             },
         };
     }
-    await syncAgentsMd(cwd, body.messages);
+    await syncAgentsMd(cwd, body.messages).catch((err) => {
+        if (!self.done)
+            throw err;
+    });
+    if (self.done)
+        return reply.promise;
     const prompt = newSuffix
         .filter((m) => m.role !== "system")
         .map((m) => (m.role === "user" ? textOf(m.content) : `${m.role.toUpperCase()}: ${textOf(m.content)}`))
@@ -692,6 +727,11 @@ export async function handleChatCompletion(body, apiKey, signal, scope) {
                     openReply(self);
                     self.textAcc += update.text;
                     emit(self, "text", update.text);
+                    if (failAfterFirstDelta !== null) {
+                        const message = failAfterFirstDelta;
+                        failAfterFirstDelta = null;
+                        failHeld(self, new Error(message));
+                    }
                 }
                 else if (update.type === "thinking-delta" && update.text) {
                     openReply(self);

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, 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>]
+       npx ${PKG} update [--dry-run]
+
+setup (default): adds "${ENTRY}" to the "plugin" array of your opencode config.
+Idempotent: does nothing if any ${PKG} entry is already present.
+
+update: deletes opencode's cached copy of ${PKG} (opencode never re-resolves
+"@latest" once installed), so the next opencode start installs the latest version.
+Cache: $XDG_CACHE_HOME/opencode or ~/.cache/opencode.
+
+  --dry-run        print what would change, write/delete 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;
+    }
+}
+// opencode caches npm plugins in <cache>/packages/<name>@<spec>/ (older: <cache>/npm/) and never re-resolves @latest.
+function update(dryRun) {
+    const cache = join(process.env.XDG_CACHE_HOME || join(homedir(), ".cache"), "opencode");
+    const [scope, name] = PKG.split("/");
+    const dirs = ["packages", "npm"].flatMap((p) => {
+        const parent = join(cache, p, scope);
+        if (!existsSync(parent))
+            return [];
+        return readdirSync(parent)
+            .filter((d) => d.startsWith(`${name}@`))
+            .map((d) => join(parent, d));
+    });
+    if (!dirs.length) {
+        console.log(`nothing to update: opencode has no cached copy of ${PKG} (it will install the latest version on next start)`);
+        return 0;
+    }
+    for (const d of dirs) {
+        const pkg = tryParse(readFileSafe(join(d, "node_modules", PKG, "package.json")));
+        const version = typeof pkg?.version === "string" ? pkg.version : "unknown version";
+        if (!dryRun)
+            rmSync(d, { recursive: true, force: true });
+        console.log(`${dryRun ? "would remove" : "removed"} cached ${version} at ${d}`);
+    }
+    if (!dryRun)
+        console.log(`restart opencode — it will install the latest ${PKG} from npm on start`);
+    return 0;
+}
+function readFileSafe(f) {
+    try {
+        return readFileSync(f, "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+function main(argv) {
+    let dryRun = false;
+    let explicit;
+    let cmd = "setup";
+    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" || a === "update")
+            cmd = a;
+        else
+            return console.error(`Unknown argument: ${a}\n\n${HELP}`), 1;
+    }
+    if (argv.includes("--config") && !explicit)
+        return console.error("--config needs a path"), 1;
+    if (cmd === "update")
+        return update(dryRun);
+    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/plugin.d.ts

@@ -2,4 +2,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 function _resetKeyCache(): void;
 export declare const CursorAuthPlugin: Plugin;

package/dist/plugin.js

@@ -1,6 +1,9 @@
 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.
@@ -45,10 +48,17 @@ async function bodyText(input, init) {
         return input.text();
     return "";
 }
+export function _resetKeyCache() {
+    keyStatus = undefined;
+    warnedExpiry = false;
+}
 let pastedApiKey;
+const EMPTY_KEY = "Cursor API key is empty — run `opencode auth login` and pick Cursor, or paste a key from cursor.com/dashboard";
 async function cursorFetch(input, init) {
     const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
     if (url.includes("/chat/completions")) {
+        if (pastedApiKey === "")
+            return errorResponse({ message: EMPTY_KEY, code: "invalid_api_key" }, 401);
         const problem = await checkKey();
         if (problem)
             return errorResponse(problem, 401);
@@ -67,7 +77,17 @@ async function cursorFetch(input, init) {
     }
     return Response.json({ error: { message: `unsupported endpoint: ${url}` } }, { status: 404 });
 }
-export const CursorAuthPlugin = async () => {
+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 ??= {});
@@ -93,8 +113,7 @@ export const CursorAuthPlugin = async () => {
             provider: "cursor",
             loader: async (getAuth) => {
                 const auth = await getAuth().catch(() => undefined);
-                if (auth && auth.type === "api" && auth.key !== "cursor-sdk-store")
-                    pastedApiKey = auth.key;
+                pastedApiKey = auth?.type === "api" && auth.key !== "cursor-sdk-store" ? (auth.key ?? "").trim() : undefined;
                 return {
                     apiKey: "cursor-managed",
                     baseURL: BASE_URL,

package/installation.md

@@ -20,23 +20,9 @@ You should see `1.19` or newer. If older or missing, ask the user to install or
 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.
+You should see `v22.13` or newer. `@cursor/sdk` 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.
+A Cursor subscription (Pro, Business, or team) is required.
 
 ## Installation
 
@@ -52,7 +38,15 @@ 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.
+**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`:
 
@@ -107,7 +101,13 @@ Optional: to see which models the account is actually allowed to use, clone the
 
 ## 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:
+opencode resolves `@latest` once, at first install, and keeps that cached version forever; restarting does not upgrade it. To upgrade, run:
+
+```bash
+npx @vidit19sharma/opencode-cursor-auth update
+```
+
+Then tell the user to restart opencode; it installs the current release from npm on start. `update --dry-run` shows what would be removed. Manual equivalent (also delete any other `@vidit19sharma/opencode-cursor-auth@*` dir there, and under `~/.cache/opencode/npm/` on older opencode):
 
 ```bash
 rm -rf ~/.cache/opencode/packages/@vidit19sharma/opencode-cursor-auth@latest
@@ -123,9 +123,9 @@ The plugin is installed. Every model the user's Cursor plan includes is availabl
 - **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.
+- **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).
+- **Features missing / variants not showing on Ctrl+T**: opencode is running a stale cached version. Run `npx @vidit19sharma/opencode-cursor-auth update`, then restart 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
 

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@vidit19sharma/opencode-cursor-auth",
-  "version": "0.3.1",
-  "description": "OpenCode plugin that uses your Cursor subscription via the official @cursor/sdk \u2014 no proxy server, no separate login.",
+  "version": "0.3.3",
+  "description": "OpenCode plugin that uses your Cursor subscription via the official @cursor/sdk — 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",
@@ -31,10 +34,13 @@
     "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",
+    "test:plugin": "bun test spike/plugin.test.ts"
   },
   "dependencies": {
     "@cursor/sdk": "^1.0.36"