cursor-opencode-provider 0.2.8 → 0.3.0

package/README.md

@@ -18,7 +18,7 @@ OpenCode driving a Cursor-routed Grok model through this provider:
 - **Authentication** — browser OAuth (PKCE), or API key from [cursor.com/settings](https://cursor.com/settings)
 - **Model discovery** — fetches available models from Cursor's API and caches them locally
 - **Streaming** — bidirectional Connect-RPC Runs with stale-session rotation, health checks, semantic/read-idle deadlines, bounded replay-safe recovery, and activity-aware held tool continuations
-- **Tool calls** — maps Cursor exec-server messages to AI SDK / OpenCode tool-call parts, including native subagent/Task execution (Cursor's `generalPurpose` maps to OpenCode `general`; read-oriented `bugbot` reviews map to `explore`) and the Pi read/bash/edit/write/grep/find/ls request/result field range; enforces the exact current OpenCode agent catalog before emitting any tool call; mirrors finalized display-only todo/plan state into OpenCode; strips OpenCode's `read` XML envelope (`<path>`/`<content>` + `N:` prefixes) before returning content to Cursor so the model cannot echo the wrapper into writes
+- **Tool calls** — maps Cursor exec-server messages to AI SDK / OpenCode tool-call parts, including catalog-aware native subagent execution: exact advertised custom agents win, `unspecified` / `generalPurpose` select `general`, read-oriented `bugbot` / `security-review` select `explore`, and `cursor-guide` selects enabled Kilo `scout` before `explore`; MiMo `actor` is used instead of its work-item `task` tool when advertised. The bridge also covers the Pi read/bash/edit/write/grep/find/ls request/result range, enforces the exact current OpenCode tool catalog, mirrors finalized display-only todo/plan state, and strips OpenCode's `read` XML envelope before returning content to Cursor.
 - **Thinking / reasoning** — surfaces extended-thinking deltas where the model supports it
 
 ## Requirements
@@ -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.8"`.
+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
 
@@ -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 |
@@ -238,13 +354,26 @@ The provider adds OpenCode-specific system guidance to normal tool-capable conve
 
 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).
 
+### 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.
+
+| Host | Default recipients | Optional recipients |
+|------|--------------------|---------------------|
+| OpenCode | `general`, `explore` | Add `agent/*.md` or `agents/*.md` with `mode: subagent` or `all` |
+| Kilo | `general`, `explore` | Enable `scout` with `KILO_EXPERIMENTAL_SCOUT=true` (or `KILO_EXPERIMENTAL=true`); add `.kilo/agent/*.md` custom agents with `mode: subagent` or `all` |
+| MiMo | `general`, `explore` | Add `.mimocode/agent/*.md` with `mode: subagent` |
+
+Kilo `scout` is reserved for external documentation, dependency repositories, and upstream source. Local workspace discovery continues to use `explore`. Primary modes and hidden/internal agents are never selected unless the host explicitly exposes them as spawnable.
+
 ## Package exports
 
 | Import path | Export |
 |-------------|--------|
 | `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.
@@ -253,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. |
@@ -262,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
 
@@ -270,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.
@@ -284,4 +416,4 @@ Project `instructions` may reference absolute or `~/` paths (OpenCode parity). S
 
 ## License
 
-MIT
+MIT

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/agents.d.ts

@@ -4,5 +4,9 @@ export type CollectedAgent = {
     description: string;
     prompt: string;
 };
-/** Custom OpenCode agents from `.opencode/agents` and global config. */
+/**
+ * Custom agents from the active OpenCode-compatible config roots. OCP may
+ * install a host-neutral bridge before loading this module; without one this
+ * remains the direct OpenCode discovery path.
+ */
 export declare function collectAgents(workspaceRoot: string): Promise<CollectedAgent[]>;

package/dist/context/agents.js

@@ -1,6 +1,6 @@
-import { readdir, readFile, stat } from "node:fs/promises";
+import { readdir, readFile, realpath, stat } from "node:fs/promises";
 import path from "node:path";
-import { opencodeGlobalConfigDir } from "./paths.js";
+import { opencodeGlobalConfigDirs, opencodeProjectConfigDirs } from "./paths.js";
 async function exists(p) {
     try {
         await stat(p);
@@ -36,41 +36,101 @@ function parseAgentMarkdown(raw, fallbackName) {
     }
     return { name, description, prompt: body.slice(0, 20_000) };
 }
-async function scanAgentDir(dir, out) {
-    if (!(await exists(dir)))
-        return;
-    let entries;
-    try {
-        entries = await readdir(dir);
-    }
-    catch {
+function uniquePaths(paths) {
+    const seen = new Set();
+    return paths.filter((value) => {
+        const normalized = path.resolve(value);
+        if (seen.has(normalized))
+            return false;
+        seen.add(normalized);
+        return true;
+    });
+}
+/**
+ * Read one host config root's `agent/` and `agents/` trees. Host loaders use
+ * both spellings and recurse through nested markdown files. Directory symlinks
+ * are followed with realpath cycle detection, matching host behavior without
+ * allowing a symlink loop to hang context construction.
+ */
+async function scanAgentRoot(root, out) {
+    if (!(await exists(root)))
         return;
-    }
-    for (const name of entries) {
-        if (!name.endsWith(".md"))
-            continue;
-        const full = path.join(dir, name);
+    const visitedDirs = new Set();
+    const scanDir = async (dir, relativePrefix) => {
+        let canonical;
         try {
-            const raw = await readFile(full, "utf-8");
-            const parsed = parseAgentMarkdown(raw, name.replace(/\.md$/, ""));
-            if (!out.has(parsed.name)) {
-                out.set(parsed.name, {
-                    fullPath: path.resolve(full),
-                    name: parsed.name,
-                    description: parsed.description,
-                    prompt: parsed.prompt,
-                });
-            }
+            canonical = await realpath(dir);
         }
         catch {
-            /* skip */
+            return;
         }
-    }
+        if (visitedDirs.has(canonical))
+            return;
+        visitedDirs.add(canonical);
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+            entries.sort((a, b) => a.name.localeCompare(b.name));
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const full = path.join(dir, entry.name);
+            const relative = path.join(relativePrefix, entry.name);
+            let isDirectory = entry.isDirectory();
+            let isFile = entry.isFile();
+            if (entry.isSymbolicLink()) {
+                try {
+                    const target = await stat(full);
+                    isDirectory = target.isDirectory();
+                    isFile = target.isFile();
+                }
+                catch {
+                    continue;
+                }
+            }
+            if (isDirectory) {
+                await scanDir(full, relative);
+                continue;
+            }
+            if (!isFile || !entry.name.endsWith(".md"))
+                continue;
+            try {
+                const raw = await readFile(full, "utf-8");
+                const fallbackName = relative.replace(/\\/g, "/").replace(/\.md$/, "");
+                const parsed = parseAgentMarkdown(raw, fallbackName);
+                if (!out.has(parsed.name)) {
+                    out.set(parsed.name, {
+                        fullPath: path.resolve(full),
+                        name: parsed.name,
+                        description: parsed.description,
+                        prompt: parsed.prompt,
+                    });
+                }
+            }
+            catch {
+                /* skip unreadable or malformed files without failing context build */
+            }
+        }
+    };
+    // Scan singular before plural, then let root ordering establish host
+    // precedence. This is deterministic and mirrors the hosts' brace glob.
+    await scanDir(path.join(root, "agent"), "agent");
+    await scanDir(path.join(root, "agents"), "agents");
 }
-/** Custom OpenCode agents from `.opencode/agents` and global config. */
+/**
+ * Custom agents from the active OpenCode-compatible config roots. OCP may
+ * install a host-neutral bridge before loading this module; without one this
+ * remains the direct OpenCode discovery path.
+ */
 export async function collectAgents(workspaceRoot) {
     const out = new Map();
-    await scanAgentDir(path.join(workspaceRoot, ".opencode", "agents"), out);
-    await scanAgentDir(path.join(opencodeGlobalConfigDir(), "agents"), out);
+    const roots = uniquePaths([
+        ...opencodeProjectConfigDirs(workspaceRoot),
+        ...opencodeGlobalConfigDirs(),
+    ]);
+    for (const root of roots)
+        await scanAgentRoot(root, out);
     return [...out.values()];
 }

package/dist/context/build.js

@@ -1,5 +1,5 @@
 import path from "node:path";
-import { toolsToDescriptors, toolsToMcpDescriptors } from "../protocol/tools.js";
+import { extractHostSubagentCatalog, toolsToDescriptors, toolsToMcpDescriptors, } from "../protocol/tools.js";
 import { collectRules } from "./rules.js";
 import { collectSkills } from "./skills.js";
 import { collectAgents } from "./agents.js";
@@ -9,6 +9,40 @@ import { collectProjectLayout } from "./layout.js";
 import { buildEnv } from "./env.js";
 import { ensureOpencodeProjectDir } from "./paths.js";
 import { traceRequestContextPaths } from "../debug.js";
+const DEFAULT_HOST_SUBAGENTS = [
+    {
+        name: "general",
+        description: "General-purpose agent for complex research and multi-step tasks.",
+    },
+    {
+        name: "explore",
+        description: "Read-only agent for searching and understanding the local codebase.",
+    },
+];
+/**
+ * Convert the raw host executor catalog into the exact subagent list advertised
+ * to Cursor. `hostSubagents.complete` answers a narrow question: did the host's
+ * task/actor tool itself expose an exhaustive recipient list (schema enum or
+ * catalog marker)? OpenCode's task tool intentionally uses a plain string, so
+ * that raw flag is false even though we can still advertise a complete Cursor
+ * catalog by adding built-in defaults and discovered agent files.
+ *
+ * `custom_subagents_info_complete` must describe the final advertised list, not
+ * the raw extraction source. If there is no executor, the empty list is
+ * complete. If the host catalog is complete, use it verbatim. Otherwise we make
+ * the advertised set complete by augmenting with default host agents and all
+ * locally discovered agents.
+ */
+function buildAdvertisedSubagentCatalog(hostSubagents, discoveredAgents) {
+    if (!hostSubagents.executor)
+        return { agents: [], complete: true };
+    if (hostSubagents.complete)
+        return { agents: hostSubagents.agents, complete: true };
+    return {
+        agents: [...DEFAULT_HOST_SUBAGENTS, ...hostSubagents.agents, ...discoveredAgents],
+        complete: true,
+    };
+}
 /**
  * Full RequestContext payload for live UMA + exec #10 reply.
  * Sourced from OpenCode discovery (and .claude/.agents skill fallbacks).
@@ -30,6 +64,26 @@ export async function buildRequestContext(input) {
     const flat = toolsToDescriptors(tools, providerIdentifier, mcpServerNames);
     const nested = toolsToMcpDescriptors(tools, providerIdentifier, mcpServerNames);
     const projectDir = ensureOpencodeProjectDir(workspaceRoot);
+    const hostSubagents = extractHostSubagentCatalog(tools);
+    const advertisedSubagents = buildAdvertisedSubagentCatalog(hostSubagents, agents);
+    const discoveredByName = new Map(agents.map((agent) => [agent.name, agent]));
+    const advertisedByName = new Map();
+    for (const agent of advertisedSubagents.agents) {
+        if (!advertisedByName.has(agent.name))
+            advertisedByName.set(agent.name, agent);
+    }
+    const customSubagents = [...advertisedByName.values()].map((agent) => {
+        const discovered = discoveredByName.get(agent.name);
+        return {
+            full_path: discovered?.fullPath ?? "",
+            name: agent.name,
+            description: discovered?.description || agent.description || "Host-configured subagent.",
+            // The host applies the real configured prompt when Task/Actor executes.
+            // Cursor only needs enough context to select the recipient intentionally.
+            prompt: discovered?.prompt ||
+                `Delegate to the host-configured ${agent.name} subagent; its host instructions and tools apply.`,
+        };
+    });
     const ctx = {
         env: buildEnv(workspaceRoot),
         tools: flat,
@@ -45,12 +99,7 @@ export async function buildRequestContext(input) {
             content: s.content,
             description: s.description,
         })),
-        custom_subagents: agents.map((a) => ({
-            full_path: a.fullPath,
-            name: a.name,
-            description: a.description,
-            prompt: a.prompt,
-        })),
+        custom_subagents: customSubagents,
         mcp_file_system_options: {
             enabled: true,
             // Cursor metadata root (mcps / agent-tools), not the git workspace.
@@ -74,7 +123,7 @@ export async function buildRequestContext(input) {
         git_repo_info_complete: true,
         git_status_info_complete: true,
         agent_skills_info_complete: true,
-        custom_subagents_info_complete: true,
+        custom_subagents_info_complete: advertisedSubagents.complete,
         mcp_file_system_info_complete: true,
         mcp_info_complete: true,
     };

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.d.ts

@@ -1,4 +1,14 @@
 export type HostPathEnv = NodeJS.ProcessEnv;
+/** Host-neutral bridge installed by OCP before an unchanged provider is loaded. */
+export declare const OPENCODE_PATH_BRIDGE: unique symbol;
+export type OpenCodePathBridge = {
+    projectConfigDirs: (workspaceRoot: string) => string[];
+    globalConfigDirs: () => string[];
+    configFileNames?: string[];
+};
+export declare function opencodeProjectConfigDirs(workspaceRoot: string): string[];
+export declare function opencodeGlobalConfigDirs(): string[];
+export declare function opencodeConfigFileNames(): string[];
 type CompatDetectResult = {
     id: string;
     supported: boolean;