cursor-opencode-provider 0.2.9 → 0.3.1

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
 {
@@ -47,7 +47,14 @@ 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"`.
+Pin a version if you want: `"cursor-opencode-provider@0.3.1"`.
+
+You can also install it yourself first:
+
+```bash
+npm install cursor-opencode-provider
+# or: bun add cursor-opencode-provider
+```
 
 ### From a local clone
 
@@ -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.3.1/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 |
@@ -234,10 +350,18 @@ OpenCode
 
 ### Injected system guidance
 
-The provider adds OpenCode-specific system guidance to normal tool-capable conversations, including tool availability, canonical workspace-path grounding, and preferring `edit` / `write` over shell-based file mutation when those tools are available. Compaction keeps its dedicated prompt unchanged.
+The provider adds OpenCode-specific system guidance to normal tool-capable conversations, including tool availability, canonical workspace-path grounding, and preferring `edit` / `write` (or `apply_patch`, when the host advertises that instead) over shell-based file mutation when those tools are available. Compaction keeps its dedicated prompt unchanged.
 
 If this guidance causes issues, update `buildOpenCodeInteractionGuidance` in [`src/language-model.ts`](src/language-model.ts) and its focused coverage in [`test/prompt-history.test.ts`](test/prompt-history.test.ts).
 
+### `apply_patch` models (GPT-5 and friends)
+
+OpenCode 1.x does not simply add `apply_patch` for GPT-series models — it **removes** `edit` and `write` from the tool catalog and advertises `apply_patch` in their place (`ToolRegistry.tools`; the model id must contain `gpt-` and neither `oss` nor `gpt-4`). Cursor keeps sending its native write/edit requests regardless, so without translation every file change on a `gpt-5*` model is refused as an unavailable tool.
+
+The provider translates transparently: a native write becomes an `*** Add File:` patch, and a Pi edit becomes a minimal `*** Update File:` chunk widened to whole lines. This is keyed purely off what the host advertises — it is inert whenever `edit`/`write` are offered normally, and inert again when the host offers neither those nor `apply_patch`. An edit that cannot be expressed faithfully (target unreadable, or the text to replace is absent or ambiguous) is refused with a specific message rather than applied to the wrong region.
+
+OpenCode 2.0 does not perform this substitution, so the path is 1.x-only in practice. See [`src/protocol/apply-patch.ts`](src/protocol/apply-patch.ts) for the upstream references.
+
 ### Native subagent routing
 
 The provider reads the permission-filtered subagent catalog from the current host `task` or `actor` definition and advertises those recipients to Cursor as custom subagents. Exact configured names are preserved; unknown future Cursor subtype strings fall back to `general`. If a complete catalog omits every compatible recipient, the request fails on Cursor's typed subagent channel instead of selecting an arbitrary specialist.
@@ -256,7 +380,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 +390,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 +400,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 +409,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.
@@ -292,6 +420,7 @@ Project `instructions` may reference absolute or `~/` paths (OpenCode parity). S
 - **Compaction resets Cursor conversation state** — the classic plugin marks OpenCode's `compaction` agent explicitly. On those turns the provider mints an isolated Cursor `conversation_id`, drops the prior checkpoint + KV blobs, preserves real tool outputs as OpenCode-host observations in the seed history, and re-advertises the session's last tool catalog while refusing execution during the summary itself. The first normal turn then rebases once more onto a fresh conversation seeded with OpenCode's compacted prompt and normal system instructions, so the summary-agent checkpoint cannot suppress later tool calls. Ordinary no-tool / `toolChoice:none` calls do not reset conversation state.
 - **Conversation bindings and compaction catalogs are bounded** — process-global per-session bindings, prior tool catalogs, and pending post-compaction rebases use a 256-session LRU bound. Evicting a conversation binding also drops its checkpoint and KV blobs.
 - **Interrupted Runs resume from checkpoints** — a remote EOF, Connect end-stream, or trailer error is never emitted as a successful `stop`. When the failed Run produced an eligible checkpoint, the provider opens a new RPC for the same conversation and sends that state with `ResumeAction`, so completed text and tool work are not replayed. Before any stateful output, an interruption without a checkpoint can still rebase from OpenCode history. Stateful interruptions without a checkpoint are surfaced because replay would be ambiguous; retry exhaustion remains explicit. A transport closure after `turn_ended` is treated as successful completion.
+- **Large reads are capped at 50 KB by OpenCode, and the cap is reported** — OpenCode's `read` tool stops at `MAX_BYTES = 50 * 1024`, cutting on a whole-line boundary, and appends `(Output capped at 50 KB. Showing lines X-Y. Use offset=N to continue.)`. The provider strips that envelope before returning content to Cursor so the model cannot echo wrappers into a later write, but it re-states the cap: a capped native read appends a `[Partial read: …]` marker after the content, a capped MCP read gets a separate notice content item, and a Pi read carries structured `PiReadExecSuccess.truncation`. The structured `truncated` flag alone is not enough — verified against live `gpt-5.4-mini` and `grok-4.5` sessions, both of which asserted "highly confident" that partial content was the whole file until the textual marker was added. Deliberately paged reads (explicit `offset`/`limit`) are not marked. Without that signal the model treats a capped read as the whole file and rewrites it truncated, discarding everything past the cap. The cap is hardcoded in OpenCode's read tool — it is not the configurable `tool_output.max_bytes`, which governs `Truncate.Service` and not read's line accumulation — so the only lever is paging with `offset`. Prefer `edit` over whole-file `write` on files above 50 KB.
 - **No fallback models** — if Cursor’s `AvailableModels` API is unreachable and there is no local cache, the provider exposes no models.
 
 ## License

package/dist/agent-url.js

@@ -21,6 +21,8 @@ function normalizeApiBaseURL(baseURL) {
     return new URL(baseURL).origin;
 }
 function resolveCacheKey(token, options) {
+    // codeql[js/insufficient-password-hash] -- The token is a high-entropy JWT/API key,
+    // and this digest is only an ephemeral memoization key, never a password verifier.
     const tokenHash = createHash("sha256").update(token).digest("hex").slice(0, 16);
     return `${tokenHash}|${normalizeApiBaseURL(options.apiBaseURL ?? options.baseURL)}|telem:${options.telemetryEnabled === true}`;
 }

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/context/paths.js

@@ -145,8 +145,9 @@ export function slugifyWorkspacePath(workspaceRoot) {
     const resolved = path.resolve(workspaceRoot);
     return resolved
         .replace(/[^a-zA-Z0-9]/g, "-")
-        .replace(/-+/g, "-")
-        .replace(/^-+|-+$/g, "");
+        .split("-")
+        .filter(Boolean)
+        .join("-");
 }
 /**
  * Cursor-style project metadata root for a workspace.

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;