cursor-opencode-provider 0.2.9 → 0.3.0

package/README.md

@@ -29,9 +29,9 @@ OpenCode driving a Cursor-routed Grok model through this provider:
 
 ## Installation
 
-### From npm (after publish)
+### From npm
 
-Add the package name to OpenCode config. OpenCode installs npm plugins with Bun at startup (cached under `~/.cache/opencode/node_modules/`):
+Add the package to OpenCode config. OpenCode installs npm plugins with Bun at startup (cached under `~/.cache/opencode/node_modules/`):
 
 ```json
 {
@@ -49,6 +49,13 @@ Add the package name to OpenCode config. OpenCode installs npm plugins with Bun
 
 Pin a version if you want: `"cursor-opencode-provider@0.2.9"`.
 
+You can also install it yourself first:
+
+```bash
+npm install cursor-opencode-provider
+# or: bun add cursor-opencode-provider
+```
+
 ### From a local clone
 
 ```bash
@@ -58,7 +65,7 @@ bun install
 bun run build
 ```
 
-Point config at the built files with absolute `file://` URLs:
+Point classic OpenCode config at the built files with absolute `file://` URLs:
 
 ```json
 {
@@ -73,6 +80,8 @@ Point config at the built files with absolute `file://` URLs:
 }
 ```
 
+For **OpenCode 2.0** local development, prefer the plugin path plus `CURSOR_OPENCODE2_DEV_ENTRY` — see [OpenCode 2.0 beta](#opencode-20-beta-opencode2).
+
 ## OpenCode setup
 
 If the `cursor` provider block is omitted, the classic plugin auto-registers it on startup (as **Cursor Integration**) using this package's entry. Model entries come from the local cache, which is filled after auth and again on startup when the cache is empty but credentials remain.
@@ -89,6 +98,108 @@ Local clone equivalent: `"file:///absolute/path/to/cursor-opencode-provider/dist
 
 That entry registers the provider via `ctx.aisdk.sdk` / `ctx.aisdk.language`. Keep the classic `plugin` entry for auth.
 
+### OpenCode 2.0 beta (`opencode2`)
+
+OpenCode 2.0 uses a different plugin API from the 1.18 `/v2/promise` one above — they
+are source-incompatible, so this package ships a **separate** entrypoint for it.
+Everything is registered by that one plugin. You do **not** need a `providers` entry,
+and there is no `enabled` flag. Do not also load `./plugin/v2` or the classic `plugin`
+entry under `opencode2`; they target the older APIs.
+
+Authenticate with `/connect` inside `opencode2`, choose **Cursor**, then either
+browser login or an API key. `CURSOR_API_KEY` is also picked up automatically.
+
+#### From npm
+
+```json
+{
+  "plugins": ["cursor-opencode-provider/plugin/opencode2"]
+}
+```
+
+Pin a version if you want: `"cursor-opencode-provider@0.2.9/plugin/opencode2"`.
+
+OpenCode 2.0 installs the published package into its host cache and loads the AI SDK
+entry from there (`aisdk:cursor-opencode-provider`). No extra env vars are required.
+
+#### From a local clone (`CURSOR_OPENCODE2_DEV_ENTRY`)
+
+Loading only the local plugin file is not enough for end-to-end local testing: OpenCode
+2.0's catalog still resolves the AI SDK package through `npm install` into
+`<host-cache>/packages/…` unless you override it. Point
+`CURSOR_OPENCODE2_DEV_ENTRY` at the built provider entry (`dist/index.js`, which exports
+`createCursor`) so the host imports that file directly.
+
+```bash
+cd /absolute/path/to/cursor-opencode-provider
+bun install && bun run build
+
+export CURSOR_OPENCODE2_DEV_ENTRY=/absolute/path/to/cursor-opencode-provider/dist/index.js
+# optional while debugging:
+# export CURSOR_PROVIDER_DEBUG=1
+```
+
+Example OpenCode 2.0 config (for example `~/.config/opencode/opencode.json` or a
+project `opencode.json`) that loads the built local plugin:
+
+```json
+{
+  "plugins": [
+    "/absolute/path/to/cursor-opencode-provider/dist/plugin-opencode2.js"
+  ]
+}
+```
+
+Equivalent forms for the same plugin entry:
+
+- `"file:///absolute/path/to/cursor-opencode-provider/dist/plugin-opencode2.js"`
+- `"../cursor-opencode-provider/dist/plugin-opencode2.js"` (relative to the config file; must start with `./` or `../`)
+
+You can also drop a symlink into `.opencode/plugins/` (or `~/.config/opencode/plugins/`),
+which OpenCode scans automatically:
+
+```bash
+mkdir -p .opencode/plugins
+ln -s /absolute/path/to/cursor-opencode-provider/dist/plugin-opencode2.js \
+      .opencode/plugins/cursor.js
+```
+
+Important for local 2.0 development:
+
+- **Export the env var before starting the daemon.** `opencode2 serve --service` inherits
+  env only at start time. After changing `CURSOR_OPENCODE2_DEV_ENTRY` or rebuilding
+  `dist/`, restart the service:
+
+  ```bash
+  opencode2 service stop
+  export CURSOR_OPENCODE2_DEV_ENTRY=/absolute/path/to/cursor-opencode-provider/dist/index.js
+  opencode2 service start
+  ```
+
+  `opencode2 service set` does **not** accept arbitrary env var names.
+- **Unset `CURSOR_OPENCODE2_DEV_ENTRY` in production** so the catalog uses the published
+  `aisdk:cursor-opencode-provider` package again.
+- **OpenCode does not install dependencies for local plugin files.** Keep the clone's
+  `bun install` intact and load the plugin from inside the clone (a copied-out file will
+  not resolve `protobufjs`).
+- **Rebuild after every change** (`bun run build`). The daemon reads `dist/`, not `src/`.
+
+Feature parity with the classic plugin, and the two places 2.0 differs:
+
+| Classic plugin | OpenCode 2.0 plugin |
+|---|---|
+| `config` hook registers provider + models | `ctx.catalog.transform` |
+| `auth` hook (OAuth + API key) | `ctx.integration.transform` + `/connect` |
+| `tool` hook (`custom_websearch`) | `ctx.tool.transform` |
+| `event` hook (session activity) | `ctx.event.subscribe` |
+| `tool.execute.before` / `.after` | `ctx.tool.hook(...)` |
+| `shell.env` injects the timeout wrapper | **No `shell.env` in 2.0** — the bash command is rewritten to call the wrapper file instead (same behavior, different mechanism) |
+| `chat.params` flags compaction turns | **No `chat.params` in 2.0** — the compaction agent is detected in `ctx.session.hook("context")` and correlated by session id |
+
+> **Beta.** OpenCode 2.0 and its plugin API are both beta and still changing. This
+> entrypoint is built against `@opencode-ai/plugin@next` (`0.0.0-next-16281`) and is
+> guarded by a compile-time conformance check, but expect churn.
+
 ### Authenticate
 
 ```bash
@@ -100,7 +211,7 @@ Choose the **cursor** provider, then one of:
 | Method | Description |
 |--------|-------------|
 | **Cursor account (browser login)** | PKCE OAuth — opens cursor.com to sign in |
-| **API key** | Paste a key from [cursor.com/settings](https://cursor.com/settings) (`sk-...`) |
+| **API key** | Paste a key from [cursor.com/settings](https://cursor.com/settings) (`crsr_...`) |
 
 After login, the plugin fetches your available models and writes them to `<host-cache>/cursor-models.json` (default `~/.cache/opencode/`). On later startups, a missing, empty, expired, or old-schema cache is refreshed during config load when Cursor auth is available; an existing stale cache remains usable if refresh fails.
 
@@ -177,7 +288,7 @@ const model = cursor.languageModel("composer-2.5")
 // model implements AI SDK LanguageModelV3 (doStream / doGenerate)
 ```
 
-Pass either `accessToken` (JWT from OAuth or key exchange) or `apiKey` (raw `sk-...` key). Optional: `apiBaseURL`, `agentBaseURL`, `cacheDir`, `headers`, `telemetryEnabled`, `retry`, and `continuation`. `cacheDir` pins the host cache root for model/version caches and Cursor project metadata; when omitted, the provider uses OCP `@opencode-compat/profile` detect (if installed) or the local MiMo/Kilo/OpenCode heuristic described in [Paths](#paths-host-cache). Transient failures resume from the latest checkpoint produced by that Run, matching Cursor CLI; without an eligible checkpoint, retries remain limited to replay-safe attempts so completed text or tool work is not duplicated. Pending-tool inactivity is renewed by OpenCode activity from the session or its descendants. The older `baseURL` option is still accepted as a legacy alias for `agentBaseURL`.
+Pass either `accessToken` (JWT from OAuth or key exchange) or `apiKey` (raw `crsr_...` key). Optional: `apiBaseURL`, `agentBaseURL`, `cacheDir`, `headers`, `telemetryEnabled`, `retry`, and `continuation`. `cacheDir` pins the host cache root for model/version caches and Cursor project metadata; when omitted, the provider uses OCP `@opencode-compat/profile` detect (if installed) or the local MiMo/Kilo/OpenCode heuristic described in [Paths](#paths-host-cache). Transient failures resume from the latest checkpoint produced by that Run, matching Cursor CLI; without an eligible checkpoint, retries remain limited to replay-safe attempts so completed text or tool work is not duplicated. Pending-tool inactivity is renewed by OpenCode activity from the session or its descendants. The older `baseURL` option is still accepted as a legacy alias for `agentBaseURL`.
 
 ## Environment variables
 
@@ -188,6 +299,7 @@ Pass either `accessToken` (JWT from OAuth or key exchange) or `apiKey` (raw `sk-
 | `CURSOR_GET_SERVER_CONFIG_TELEMETRY` | Set to `1` or `true` to opt the `GetServerConfig` lookup into telemetry in OpenCode/plugin usage |
 | `CURSOR_PROVIDER_DEBUG` | Set to `1` or `true` to enable wire-level debug logging |
 | `CURSOR_PROVIDER_DEBUG_FILE` | Debug log path (default: `debug-<pid>.log` under `$TMPDIR/cursor-provider-logs-<uid>/`) |
+| `CURSOR_OPENCODE2_DEV_ENTRY` | **Local OpenCode 2.0 only.** Absolute path to a built entry file (usually `dist/index.js`). Rewrites the catalog's AI SDK package to `aisdk:file://…` so the daemon imports your local build instead of `npm install`-ing the published package. Export it **before** `opencode2 service start`, then restart after rebuilds. Unset in production. |
 | `XDG_CACHE_HOME` | Base for host cache dirs (`$XDG_CACHE_HOME/opencode/`, `…/mimocode/`, or `…/kilo/`) when no explicit `cacheDir` / OCP detect override |
 | `MIMOCODE_HOME` | When set, host cache is `$MIMOCODE_HOME/cache` (MiMo) |
 | `KILO_CONFIG_DIR` | When set, host cache is `$XDG_CACHE_HOME/kilo` |
@@ -220,7 +332,11 @@ OpenCode
 | Module | Role |
 |--------|------|
 | `src/plugin.ts` | Classic OpenCode hooks: provider registration, OAuth, API key exchange, token refresh |
-| `src/plugin-v2.ts` | OpenCode Effect/Promise v2 plugin (`ctx.aisdk.*`); load via `./plugin/v2` only |
+| `src/plugin-v2.ts` | OpenCode 1.18 Effect/Promise v2 plugin (`ctx.aisdk.*`); load via `./plugin/v2` only |
+| `src/plugin-opencode2.ts` | OpenCode 2.0 beta plugin (catalog, integration, tools, aisdk); load via `./plugin/opencode2` only |
+| `src/opencode2/` | 2.0-only catalog mapping, integration/auth, and local API types |
+| `src/plugin-core.ts` | Host-neutral SDK factory, package matching, API base/telemetry resolution |
+| `src/model-config.ts` | Cursor model → OpenCode model mapping shared by every plugin surface |
 | `src/index.ts` | `createCursor` factory; default export is `CursorPlugin` |
 | `src/language-model.ts` | AI SDK `LanguageModelV3` adapter (`doStream`, `doGenerate`) |
 | `src/session.ts` | Held-open agent Run session and pending exec correlation |
@@ -256,7 +372,8 @@ Kilo `scout` is reserved for external documentation, dependency repositories, an
 |-------------|--------|
 | `cursor-opencode-provider` | `createCursor`, `CursorPlugin` (named + default) |
 | `cursor-opencode-provider/plugin` | `CursorPlugin` (classic Hooks — auth) |
-| `cursor-opencode-provider/plugin/v2` | OpenCode Effect/Promise v2 plugin (`ctx.aisdk.*`) |
+| `cursor-opencode-provider/plugin/v2` | OpenCode 1.18 Effect/Promise v2 plugin (`ctx.aisdk.*`) |
+| `cursor-opencode-provider/plugin/opencode2` | OpenCode 2.0 beta plugin (self-registering: catalog + auth + tools) |
 | `cursor-opencode-provider/errors` | Structured provider error classes |
 
 The package root intentionally stays plugin-safe for OpenCode's classic loader. `CursorPluginV2` and non-plugin runtime APIs are **not** re-exported from the package root; load them through their dedicated subpaths.
@@ -265,8 +382,9 @@ The package root intentionally stays plugin-safe for OpenCode's classic loader.
 
 | Problem | What to try |
 |---------|-------------|
-| No Cursor models in the picker | Confirm Cursor auth (`opencode auth login` → **cursor**). Restart OpenCode — if auth is present and the cache is empty, models are fetched on startup. Confirm `provider.cursor.npm` is the package name (or a built `file://…/dist/index.js`). |
+| No Cursor models in the picker | Confirm Cursor auth (`opencode auth login` → **cursor**, or `/connect` in `opencode2`). Restart OpenCode — if auth is present and the cache is empty, models are fetched on startup. Confirm `provider.cursor.npm` is the package name (or a built `file://…/dist/index.js`). |
 | Auth / 401 errors mid-session | Re-login. OAuth and exchanged API-key JWTs refresh automatically when near expiry; a revoked refresh token needs a fresh login. |
+| Local OpenCode 2.0 still runs the published package | Set `CURSOR_OPENCODE2_DEV_ENTRY` to an absolute `…/dist/index.js` path **before** starting the daemon, rebuild (`bun run build`), then `opencode2 service stop && opencode2 service start`. Loading only `dist/plugin-opencode2.js` is not enough — without the env var, 2.0 still `npm install`s the published package into the host cache. |
 | “Too many connections from different devices” | Device IDs are derived from stable OS identifiers (same approach as the Cursor CLI). Avoid running multiple clients that invent different machine fingerprints for the same account. |
 | Empty or stale model list | Delete `<host-cache>/cursor-models.json` (default `~/.cache/opencode/`, or MiMo/Kilo host cache) and restart OpenCode. Existing Cursor auth is enough to refill the cache; re-login only if auth itself is broken. Cache TTL is 24h; a failed background refresh keeps serving the previous cache. |
 | Stream hangs or HTTP/2 errors | The provider keeps Cursor's Run open across OpenCode tool calls, rotates aged shared connections, resumes transient interruptions from the latest eligible Cursor checkpoint, and falls back to a fresh-history rebase only before stateful output when no checkpoint exists. Repeated interruption is surfaced as an error instead of a false successful stop; retry the turn after checking connectivity. With debug logging enabled, look for `Run interrupted`, `resuming … checkpoint`, or `rebasing fresh Run`. Restart OpenCode after rebuilding a local `file://` install. |
@@ -274,6 +392,7 @@ The package root intentionally stays plugin-safe for OpenCode's classic loader.
 | Visible `<shell_metadata>` timeout text | Rebuild and restart a local install. Cursor's shell timeout is carried on its exec request; the provider now removes OpenCode's internal timeout envelope before it is rendered or stored, then returns Cursor's typed timeout or background-handoff event instead of treating the text as successful stdout. |
 | `Unsupported Cursor exec variant …` | The error names the canonical Cursor CLI request field, its expected result field, and this provider's handling classification. `handling=unsupported` is a known Cursor-native capability without a safe OpenCode AI SDK bridge; `unknown request field` indicates new protocol drift; `handling=opencode-tool` or `provider-control` indicates a provider decoder/dispatch regression. Enable the debug log and report the full named error. |
 | Need wire-level logs | Set `CURSOR_PROVIDER_DEBUG=1` (optional `CURSOR_PROVIDER_DEBUG_FILE`; the default is `debug-<pid>.log` under `$TMPDIR/cursor-provider-logs-<uid>/`) and reproduce the issue. |
+| Cache **write** tokens always show as `0` | Not a mapping bug in this provider. Cursor's `TurnEnded` protobuf includes `cache_write` (field 4) and this package forwards it as AI SDK `inputTokens.cacheWrite` / OpenCode `cache.write`. Real agent sessions send field 4 as `0` even when `cache_read` is large on later turns. With debug logging, confirm `turn_ended raw wire fields: … f4:wt0=0` and `v3CacheWrite=0 source=turn_ended`. Cache **read** counts from the same message do populate correctly. |
 
 ## Security
 
@@ -282,6 +401,7 @@ Project `instructions` may reference absolute or `~/` paths (OpenCode parity). S
 ## Known limitations
 
 - **Personal use / ToS** — this provider speaks Cursor’s private agent protocol (CLI-shaped client identity). Use only with an account you own; Cursor may change or restrict the API without notice.
+- **`TurnEnded.cache_write` is unused by Cursor's agent** — usage comes from `interaction_update.turn_ended` (`input_tokens`, `output_tokens`, `cache_read`, `cache_write`, `reasoning_tokens`). The provider maps those 1:1 into AI SDK V3 nested usage. Captured live Runs consistently set `cache_write=0` on the wire while still reporting non-zero `cache_read` and `reasoning_tokens`; there is no alternate agent-stream field today that supplies write counts, so OpenCode/Kilo cannot show cache-write tokens for this provider until Cursor populates that counter.
 - **`request_context` from OpenCode** — each Run sends Cursor `RequestContext` built from OpenCode project context (workspace env, `AGENTS.md` / `instructions`, `.opencode` agents/skills/plugins, git, layout, plus `.claude`/`.agents` skill fallbacks). Its canonical root is also used by the [injected system guidance](#injected-system-guidance). Same discovery as OpenCode — including `.cursor/` paths only when listed in `instructions`. Cursor-only cloud/sandbox marketplace surfaces are omitted. `env.workspace_paths` / `process_working_directory` stay on the real git workspace; Cursor's metadata root (`project_folder`, MCP `workspace_project_dir`, terminals/transcripts) is advertised under `<host-cache>/projects/<slug>/` (default `~/.cache/opencode/projects/…`) so dumps like `agent-tools/` do not land in the repo. OpenCode remains the permission authority: its coarse allow/ask/deny configuration is not fabricated into Cursor's unrelated allow/block instruction-list messages.
 - **Configured MCP tools keep their upstream server id** — OpenCode builtins and plugin/custom tools are advertised under a synthetic `opencode` MCP server. Tools whose flattened name matches an MCP server in merged `opencode.json` configuration (`github_create_pull_request`, …) are grouped into that server's `mcp_descriptors` / `provider_identifier` (`github`, …). Unknown underscore-containing names stay under `opencode` rather than being guessed incorrectly. Cursor's MCP-state exec probe is answered from the same advertised descriptors before the actual tool request, using the full canonical tool-definition identity required by native `get_mcp_tools`; exec still reconstructs the full OpenCode tool id.
 - **Display completions are notifications, not execution requests** — Cursor `tool_call_*` frames use a typed `ToolCall` oneof. The provider decodes them for diagnostics but only mirrors finalized todo/plan state (`update_todos_tool_call` / `create_plan_tool_call`) into advertised OpenCode `todowrite`; the completed payload already contains the authoritative final list. Interactive, data-returning, and side-effecting completions are never replayed as new tools because their result could not be returned to Cursor. Exec-backed native subagent/Task and Pi read/bash/edit/write/grep/find/ls calls use their typed request/result fields instead. Unknown display variants are logged. All 37 Cursor CLI exec request/result pairs are inventoried by field and name; known-but-unsupported and future unknown exec variants fail explicitly rather than receiving a guessed response that could deadlock the Run.

package/dist/auth.d.ts

@@ -32,6 +32,13 @@ export declare function clearBearerTokenCache(): void;
  * Resolve a Bearer JWT for Cursor API calls. Prefer an already-exchanged
  * `accessToken`; otherwise exchange (and cache) from `apiKey`, refreshing
  * when the cached JWT is near expiry.
+ *
+ * `apiKey` is only ever a raw exchangeable secret when it has Cursor's
+ * `crsr_` prefix. Callers that generically forward whatever credential value
+ * they hold — e.g. a host's package-agnostic "aisdk:" SDK loader, which
+ * doesn't distinguish our OAuth vs. API-key connection methods and may pass
+ * an already-issued JWT through the `apiKey` field — hand us a token that's
+ * already good to use as-is; POSTing it to the exchange endpoint 401s.
  */
 export declare function resolveBearerToken(input: {
     accessToken?: string;

package/dist/auth.js

@@ -147,6 +147,13 @@ export function clearBearerTokenCache() {
  * Resolve a Bearer JWT for Cursor API calls. Prefer an already-exchanged
  * `accessToken`; otherwise exchange (and cache) from `apiKey`, refreshing
  * when the cached JWT is near expiry.
+ *
+ * `apiKey` is only ever a raw exchangeable secret when it has Cursor's
+ * `crsr_` prefix. Callers that generically forward whatever credential value
+ * they hold — e.g. a host's package-agnostic "aisdk:" SDK loader, which
+ * doesn't distinguish our OAuth vs. API-key connection methods and may pass
+ * an already-issued JWT through the `apiKey` field — hand us a token that's
+ * already good to use as-is; POSTing it to the exchange endpoint 401s.
  */
 export async function resolveBearerToken(input) {
     if (input.accessToken)
@@ -154,6 +161,8 @@ export async function resolveBearerToken(input) {
     if (!input.apiKey) {
         throw new Error("Cursor provider: no access token or API key provided");
     }
+    if (!input.apiKey.startsWith("crsr_"))
+        return input.apiKey;
     const baseUrl = input.baseUrl ?? API_BASE;
     const cached = _apiKeyTokenCache.get(input.apiKey);
     if (cached && !isExpiringSoon(cached.accessToken)) {

package/dist/compaction-marker.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Session-scoped compaction marker for the OpenCode 2.0 plugin.
+ *
+ * The classic plugin learns that a turn belongs to OpenCode's compaction agent
+ * via the `chat.params` hook and forwards it as a provider option. OpenCode 2.0
+ * removed `chat.params`; the only place the runtime names the owning agent is
+ * `session.hook("context")`, which fires before dispatch. We record the fact
+ * there and let the provider read it back by session id.
+ *
+ * Bounded so a long-lived server cannot accumulate ids for dead sessions.
+ */
+export declare function markCompactionSession(sessionID: string, isCompaction: boolean): void;
+export declare function isCompactionSession(sessionID: string | undefined): boolean;
+export declare function clearCompactionSessions(): void;

package/dist/compaction-marker.js

@@ -0,0 +1,36 @@
+/**
+ * Session-scoped compaction marker for the OpenCode 2.0 plugin.
+ *
+ * The classic plugin learns that a turn belongs to OpenCode's compaction agent
+ * via the `chat.params` hook and forwards it as a provider option. OpenCode 2.0
+ * removed `chat.params`; the only place the runtime names the owning agent is
+ * `session.hook("context")`, which fires before dispatch. We record the fact
+ * there and let the provider read it back by session id.
+ *
+ * Bounded so a long-lived server cannot accumulate ids for dead sessions.
+ */
+const MAX_TRACKED_SESSIONS = 256;
+const compactionSessions = new Set();
+export function markCompactionSession(sessionID, isCompaction) {
+    if (!sessionID)
+        return;
+    if (!isCompaction) {
+        compactionSessions.delete(sessionID);
+        return;
+    }
+    // Re-insert to keep insertion order meaningful for the eviction below.
+    compactionSessions.delete(sessionID);
+    compactionSessions.add(sessionID);
+    while (compactionSessions.size > MAX_TRACKED_SESSIONS) {
+        const oldest = compactionSessions.values().next().value;
+        if (oldest === undefined)
+            break;
+        compactionSessions.delete(oldest);
+    }
+}
+export function isCompactionSession(sessionID) {
+    return typeof sessionID === "string" && compactionSessions.has(sessionID);
+}
+export function clearCompactionSessions() {
+    compactionSessions.clear();
+}

package/dist/context/env.js

@@ -20,6 +20,10 @@ export function buildEnv(workspaceRoot) {
     // Cursor's project_folder is a metadata root (agent-tools, terminals, …),
     // not the git workspace. Keep dumps under OpenCode cache.
     const projectFolder = ensureOpencodeProjectDir(cwd);
+    // process_working_directory must match the workspace, not the host process
+    // cwd. OpenCode 2.0's daemon is long-lived and often started from $HOME, so
+    // process.cwd() would advertise the home folder to Cursor and the model would
+    // treat that as its shell cwd. workspace_paths already uses `cwd` above.
     const env = {
         os_version: osVersion,
         workspace_paths: [cwd],
@@ -30,8 +34,8 @@ export function buildEnv(workspaceRoot) {
         project_folder: projectFolder,
         terminals_folder: path.join(projectFolder, "terminals"),
         agent_transcripts_folder: path.join(projectFolder, "agent-transcripts"),
-        process_working_directory: process.cwd(),
-        is_working_dir_home_dir: path.resolve(process.cwd()) === path.resolve(home),
+        process_working_directory: cwd,
+        is_working_dir_home_dir: cwd === path.resolve(home),
     };
     trace(`buildEnv: workspace_paths=${JSON.stringify(env.workspace_paths)} ` +
         `project_folder=${env.project_folder} ` +

package/dist/index.d.ts

@@ -34,9 +34,7 @@ export type CreateCursorOptions = {
     /** Fresh-turn retry policy. Defaults: 3 attempts, 500ms base, 8000ms cap. */
     retry?: CursorRetryOptions;
 };
-export declare function createCursor(options: CreateCursorOptions): {
-    languageModel(modelId: string): import("@ai-sdk/provider").LanguageModelV3;
-};
+export declare function createCursor(options: CreateCursorOptions): import("./plugin-core.js").CursorSdk;
 export { CursorPlugin };
 export type { CursorContinuationOptions, CursorContinuationPolicy } from "./session.js";
 export default CursorPlugin;

package/dist/index.js

@@ -1,13 +1,7 @@
-import { CURSOR_PROVIDER_ID } from "./shared.js";
-import { createCursorLanguageModel } from "./language-model.js";
+import { createSdk } from "./plugin-core.js";
 import { CursorPlugin } from "./plugin.js";
 export function createCursor(options) {
-    const providerId = options.name || CURSOR_PROVIDER_ID;
-    return {
-        languageModel(modelId) {
-            return createCursorLanguageModel(modelId, providerId, options);
-        },
-    };
+    return createSdk(options);
 }
 export { CursorPlugin };
 export default CursorPlugin;

package/dist/language-model.js

@@ -5,7 +5,7 @@ import { bidiRunStream, CursorRunInterruptedError, normalizeAgentRunOrigin, } fr
 import { trace, traceRequestContextPaths } from "./debug.js";
 import { buildRunRequest, buildHeartbeat } from "./protocol/request.js";
 import { decodeFramePayload } from "./protocol/framing.js";
-import { decodeMessage } from "./protocol/messages.js";
+import { debugWalkTurnEnded, decodeMessage } from "./protocol/messages.js";
 import { parseExecServerMessage, buildToolCallPart, buildExecClientMessages, buildReadRejectionMessages, classifyMissingReadTarget, resolveReadTargetPath, parseExecIdFromToolCallId, detectExecVariantField, buildRequestContextResult, buildMcpStateResult, buildCustomWebToolAliases, extractHostSubagentCatalog, resolveCustomWebToolAlias, remapNativeSubagentForCatalog, CUSTOM_WEBFETCH_TOOL, CUSTOM_WEBSEARCH_TOOL, } from "./protocol/tools.js";
 import { describeCursorExecVariant } from "./protocol/exec-variants.js";
 import { advertisedToolNamesFromDescriptors, extractExecDisplayCallId, extractProtobufSubmessage, listProtobufFieldNumbers, parseDisplayToolCall, resolveBridgedOpenCodeToolCall, } from "./protocol/tool-call-bridge.js";
@@ -22,9 +22,12 @@ import { workspaceRootFromRequestContext } from "./context/env.js";
 import { opencodeGlobalCacheDir, setHostCacheDirOverride } from "./context/paths.js";
 import { resolveAgentUrl } from "./agent-url.js";
 import { CURSOR_API_HOST, CURSOR_COMPACTION_OPTION } from "./shared.js";
+import { isCompactionSession } from "./compaction-marker.js";
+import { getSessionDirectory } from "./session-directory.js";
 import { consumeCursorShellResult, registerCursorShellCall, } from "./shell-timeout.js";
 import { analyzeReplayFrame, AttemptReplaySafety } from "./replay-safety.js";
 import { readAllFieldsStrict } from "./protocol/struct.js";
+import { buildLanguageModelV3UsageFromEstimate, buildLanguageModelV3UsageFromTurnEnded, turnEndedCounter, } from "./usage.js";
 let _availableModels;
 // mtime of the cache file the last time we loaded it. Compared on each call
 // so discoverModels' background refresh is picked up without a process restart.
@@ -275,7 +278,7 @@ export function createCursorLanguageModel(modelId, providerId, options) {
     };
 }
 async function doStreamImpl(modelId, options, callOptions) {
-    // A raw `sk-...` API key must be exchanged for a JWT before it can be used
+    // A raw `crsr_...` API key must be exchanged for a JWT before it can be used
     // as a Bearer token (the plugin path does this in auth.ts). The accessToken
     // path is already a JWT from OAuth/key-exchange, so we use it as-is.
     // resolveBearerToken caches apiKey exchanges so we don't hit /auth/exchange
@@ -445,8 +448,10 @@ async function startSession(modelId, token, callOptions, options, startOptions)
     const sessionKey = opencodeSessionKey(callOptions);
     const providerOptions = callOptions.providerOptions?.cursor;
     // The classic plugin marks OpenCode's agent="compaction" through chat.params.
+    // OpenCode 2.0 removed that hook, so its plugin records the same fact against
+    // the session id from session.hook("context") instead; consult both.
     // Do not infer this from tools/toolChoice: standalone no-tool calls are valid.
-    const isCompaction = providerOptions?.[CURSOR_COMPACTION_OPTION] === true;
+    const isCompaction = providerOptions?.[CURSOR_COMPACTION_OPTION] === true || isCompactionSession(sessionKey);
     const toolState = resolveTurnToolState({
         sessionKey,
         incomingTools,
@@ -482,7 +487,12 @@ async function startSession(modelId, token, callOptions, options, startOptions)
     const userText = recovery?.kind === "rebase"
         ? "Continue the interrupted turn from the conversation history above. Do not repeat completed work."
         : (extractUserText([...prompt].reverse().find((m) => m.role === "user")) || ".");
-    const workspaceRoot = path.resolve(options.workspaceRoot || process.cwd());
+    // v1 sets `options.workspaceRoot` correctly per invocation (`input.directory`,
+    // one plugin instance per project). OpenCode 2.0 runs one daemon across many
+    // projects, so its static `options.workspaceRoot` is only a last-resort
+    // fallback; `getSessionDirectory` carries the real per-session directory
+    // recorded from `session.hook("context")` in `plugin-opencode2.ts`.
+    const workspaceRoot = path.resolve(getSessionDirectory(sessionKey) ?? (options.workspaceRoot || process.cwd()));
     const baseSystemPrompt = extractSystemPrompt(prompt);
     const interactionGuidance = buildOpenCodeInteractionGuidance(cursorTools, isCompaction, workspaceRoot);
     const systemPrompt = interactionGuidance
@@ -583,6 +593,7 @@ async function startSession(modelId, token, callOptions, options, startOptions)
         outputTokens: 0,
         cacheRead: 0,
         cacheWrite: 0,
+        reasoningTokens: 0,
     };
     trace(`outbound Run: model=${cursorModelId} opencodeModel=${modelId} conversationId=${conversationId} ` +
         `params=${JSON.stringify(parameterValues ?? [])} ` +
@@ -730,6 +741,7 @@ export function deliverContinuationResults(session, trailingToolResults) {
                     toolName: pending.toolName ?? r.toolName,
                     resultMetadata: pending.resultMetadata,
                     shellOutcome: shellResult?.outcome,
+                    workspaceRoot: workspaceRootFromRequestContext(session.requestContext),
                 });
             }
             catch (error) {
@@ -916,6 +928,7 @@ export async function pump(session, controller, ids, abortSignal) {
                 error: reason,
                 toolName: parsed.toolName,
                 resultMetadata: parsed.resultMetadata,
+                workspaceRoot: workspaceRootFromRequestContext(session.requestContext),
             })) {
                 session.stream.write(frame);
             }
@@ -965,6 +978,7 @@ export async function pump(session, controller, ids, abortSignal) {
                 output: "",
                 toolName: parsed.toolName,
                 resultMetadata: { path: requestedPath },
+                workspaceRoot,
             })) {
                 session.stream.write(frame);
             }
@@ -1067,32 +1081,27 @@ export async function pump(session, controller, ids, abortSignal) {
         if (te) {
             // Authoritative TurnEnded counts — replace the running estimate.
             session.usageEstimate = {
-                inputTokens: Number(te.input_tokens ?? 0) || 0,
-                outputTokens: Number(te.output_tokens ?? 0) || 0,
-                cacheRead: Number(te.cache_read ?? 0) || 0,
-                cacheWrite: Number(te.cache_write ?? 0) || 0,
+                inputTokens: turnEndedCounter(te, "input_tokens"),
+                outputTokens: turnEndedCounter(te, "output_tokens"),
+                cacheRead: turnEndedCounter(te, "cache_read"),
+                cacheWrite: turnEndedCounter(te, "cache_write"),
+                reasoningTokens: turnEndedCounter(te, "reasoning_tokens"),
             };
         }
         const est = session.usageEstimate;
-        const usage = {
-            inputTokens: {
-                total: promptTokens,
-                noCache: undefined,
-                cacheRead: 0,
-                cacheWrite: 0,
-            },
-            outputTokens: {
-                total: estimateTokens(requestUsage.outputChars),
-                text: undefined,
-                reasoning: undefined,
-            },
-        };
+        const usage = te
+            ? buildLanguageModelV3UsageFromTurnEnded(te)
+            : buildLanguageModelV3UsageFromEstimate(est, promptTokens, requestUsage.outputChars, estimateTokens);
         const providerMetadata = te ? cursorTurnEndedProviderMetadata(te) : undefined;
         const reasonLabel = typeof reason === "object" && reason && "unified" in reason
             ? String(reason.unified ?? "unknown")
             : String(reason);
+        const inTotal = usage.inputTokens?.total ?? 0;
+        const outTotal = usage.outputTokens?.total ?? 0;
         trace(`finish: reason=${reasonLabel} ` +
-            `requestIn=${usage.inputTokens.total} requestOut=${usage.outputTokens.total} ` +
+            `v3In=${inTotal} v3Out=${outTotal} ` +
+            `v3CacheRead=${usage.inputTokens?.cacheRead ?? 0} v3CacheWrite=${usage.inputTokens?.cacheWrite ?? 0} ` +
+            `v3Reasoning=${usage.outputTokens?.reasoning ?? 0} ` +
             `rawIn=${est.inputTokens} rawOut=${est.outputTokens} ` +
             `rawCacheRead=${est.cacheRead} rawCacheWrite=${est.cacheWrite} ` +
             `source=${te ? "turn_ended" : "estimate"}`);
@@ -1238,6 +1247,7 @@ export async function pump(session, controller, ids, abortSignal) {
                 emitReasoning(iu.thinking_delta.text ?? "");
             }
             else if (iu?.turn_ended) {
+                trace(`turn_ended raw wire fields: ${debugWalkTurnEnded(payload)}`);
                 emitFinish(iu.turn_ended, { unified: "stop", raw: undefined });
                 sessionManager.close(session);
                 return;
@@ -1683,20 +1693,14 @@ export function estimatePromptTokens(prompt) {
 }
 /** Preserve cumulative Cursor counters as diagnostics, never as AI SDK request usage. */
 export function cursorTurnEndedProviderMetadata(te) {
-    const counter = (key) => {
-        const value = te[key];
-        return typeof value === "number" && Number.isFinite(value) && value >= 0
-            ? Math.trunc(value)
-            : 0;
-    };
     return {
         cursor: {
             usageVersion: 2,
-            inputTokensRaw: counter("input_tokens"),
-            outputTokensRaw: counter("output_tokens"),
-            cacheReadRaw: counter("cache_read"),
-            cacheWriteRaw: counter("cache_write"),
-            reasoningTokensRaw: counter("reasoning_tokens"),
+            inputTokensRaw: turnEndedCounter(te, "input_tokens"),
+            outputTokensRaw: turnEndedCounter(te, "output_tokens"),
+            cacheReadRaw: turnEndedCounter(te, "cache_read"),
+            cacheWriteRaw: turnEndedCounter(te, "cache_write"),
+            reasoningTokensRaw: turnEndedCounter(te, "reasoning_tokens"),
         },
     };
 }

package/dist/model-config.d.ts

@@ -0,0 +1,15 @@
+import { type ModelInfo } from "./models.js";
+/**
+ * Display names shared by both a thinking and a non-thinking model. A thinking
+ * model with such a name needs a "Thinking" tag to disambiguate it from its
+ * non-thinking twin (Cursor's Claude/Fable/Sonnet families). Models whose names
+ * are already unique — including Cursor's GPT family, where the reasoning tier
+ * ("None"/"Low"/"High"…) is baked into the name — are excluded, so they aren't
+ * tagged redundantly.
+ */
+export declare function thinkingSuffixBaseNames(models: ModelInfo[]): Set<string>;
+export declare function modelInfoToConfig(mi: ModelInfo, options?: {
+    thinkingSuffix?: boolean;
+    contextTier?: "base" | "long";
+}): Record<string, any>;
+export declare function modelsToConfig(models: ModelInfo[]): Record<string, any>;