@stablekernel/opencode-cursor 0.1.0-rc.2 → 0.2.0

package/CHANGELOG.md

@@ -4,10 +4,30 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
-- `0.1.0-rc.1` — first pre-release of the 0.1.0 surface below, published to the
-  npm `next` dist-tag for validation ahead of the stable `0.1.0`.
+## [0.2.0] — 2026-06-11
 
-## [0.1.0] — unreleased
+- **More Cursor tools map onto opencode's native tool renderers (blocks mode).**
+  Following the `edit` → diff-viewer mapping, Cursor's `shell`, `read`, `write`,
+  `glob`, `grep`, `ls`, `updateTodos`, and `task` tool activity is now surfaced
+  under opencode's registered `bash`, `read`, `write`, `glob`, `grep`, `list`,
+  `todowrite`, and `task` tools, and Cursor's web search (which runs as an MCP
+  tool) maps onto opencode's `websearch` renderer — so opencode renders its
+  native UI (shell console, file viewer, todo checklist, subagent card, search
+  results, …) instead of generic `cursor_*` blocks. Cursor's arg shape is
+  translated to opencode's (e.g. `path` → `filePath`, `globPattern` → `pattern`,
+  `fileText` → `content`); calls stay provider-executed (display-only, never
+  re-run on disk).
+- **Cleaner fallback blocks for tools without an opencode counterpart.**
+  `readLints` and `delete` now render as formatted `cursor_*` blocks (a
+  diagnostics list / a one-line confirmation) instead of raw JSON, and every MCP
+  tool's `content` array is flattened to readable text. Anything else — or a
+  result with an unexpected shape — still falls back to a safe `cursor_*` block
+  with the raw payload.
+
+## [0.1.0] — 2026-06-10
+
+> Pre-releases: `0.1.0-rc.1` and `0.1.0-rc.2` were published to the npm `next`
+> dist-tag for validation ahead of this stable release.
 
 Initial public release. A complete opencode integration for Cursor built on the
 official `@cursor/sdk`: a streaming chat provider, an auth/config/model plugin,
@@ -21,17 +41,24 @@ and a permission-gated delegation tool surface.
   tool activity, usage). Implements both `doStream()` and `doGenerate()`.
 - **Per-request controls** via `providerOptions.cursor` — `mode` (agent/plan),
   `params`, and `thinking` level; works with opencode's model variant picker.
-- **Model variants** auto-generated from `Cursor.models.list` parameters: a
-  `plan` variant plus one per reasoning level a model advertises.
+- **Model variants** auto-generated from `Cursor.models.list` parameters: one
+  per reasoning/effort level a model advertises (boolean params collapse to a
+  single on-variant). opencode's plan agent maps to Cursor plan mode.
 - **Session reuse** (`session: true`) — keeps one Cursor agent per opencode
   session via `Agent.resume()` across turns, with automatic fallback to a fresh
   agent. A run wedged by a crashed/duplicate process is recovered by retrying
   the send once with the SDK's `local.force` escape hatch.
-- **`toolDisplay` provider option** (`"reasoning"` default | `"blocks"`):
-  - `"reasoning"` renders Cursor's internal tool activity (including the real
-    MCP tool name) as concise `[tool] …` reasoning lines. Always safe — tool
-    calls never cross opencode's tool-execution boundary.
-  - `"blocks"` emits structured, provider-executed **dynamic** `tool-call` /
+- **Native diff viewer for Cursor edits (blocks mode).** A Cursor `edit` tool
+  call is now surfaced under opencode's registered `edit` tool with its real
+  unified diff in `metadata.diff`, so opencode renders its built-in diff viewer
+  instead of a generic block. The required `oldString`/`newString` (which Cursor
+  does not expose) are reconstructed from the diff; the call is provider-executed
+  so they are never applied to disk. Any edit without a usable diff (errors,
+  unexpected shapes, or a host without a registered `edit` tool) falls back to a
+  safe `cursor_edit` block. Other Cursor tools (shell/read/mcp/…) remain
+  prefixed `cursor_*` blocks.
+- **`toolDisplay` provider option** (`"blocks"` default | `"reasoning"`):
+  - `"blocks"` (default) emits structured, provider-executed **dynamic** `tool-call` /
     `tool-result` parts so opencode renders native tool blocks. Names are
     `cursor_`-prefixed and sanitized (`shell` → `cursor_shell`,
     `serena/find_symbol` → `cursor_serena_find_symbol`) so they can't collide
@@ -42,6 +69,10 @@ and a permission-gated delegation tool surface.
     errored/cancelled mid-tool) is closed with a synthetic error result so the
     block never dangles as "Tool execution aborted", and a run that ends with
     status `error` surfaces the failure instead of finishing silently.
+  - `"reasoning"` renders Cursor's internal tool activity (including the real
+    MCP tool name) as concise `[tool] …` reasoning lines. Always safe — tool
+    calls never cross opencode's tool-execution boundary; the fallback for
+    older/non-V3 hosts (`provider.cursor.options.toolDisplay: "reasoning"`).
 
 ### Node sidecar (Bun compatibility)
 
@@ -56,7 +87,8 @@ and a permission-gated delegation tool surface.
 
 ### Plugin
 
-- **opencode plugin** (`@stablekernel/opencode-cursor/plugin`): auth hook (API-key login;
+- **opencode plugin** (`@stablekernel/opencode-cursor`, resolved via the package's
+  `./server` export): auth hook (API-key login;
   the key is validated on first use rather than at login), config hook
   (auto-injects `provider.cursor`),
   `provider.models()` (live catalog via `Cursor.models.list`), and the

package/README.md

@@ -12,7 +12,8 @@ It uses your Cursor API key to:
 - register a `cursor` provider in opencode,
 - **list the models available to your account** (live, via `Cursor.models.list()`), and
 - run chats through Cursor's local agent runtime (`Agent.create` / `agent.send`), streaming
-  text and reasoning back into opencode (Cursor's own tool activity is surfaced as reasoning).
+  text and reasoning back into opencode (Cursor's own tool activity is surfaced as structured tool
+  blocks by default; see [Tool display](#tool-display)).
 
 This plugin registers Cursor as a **native opencode provider**: its models appear in
 `opencode models` and the model picker, and you talk to a Cursor model *directly* — with live model
@@ -62,6 +63,25 @@ login. The `provider.models()` hook refreshes the catalog live once you're authe
 
 ## Install
 
+### Quick install (one line)
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/stablekernel/opencode-cursor/main/install.sh | bash
+```
+
+The script registers the plugin in your **global** `opencode.json`
+(`~/.config/opencode/opencode.json`), checks for Node.js 22+ on your `PATH`, and offers to set
+`CURSOR_API_KEY`. Flags:
+
+- `--project` — write `./opencode.json` in the current directory instead of the global config.
+- `--yes` / `-y` — non-interactive; skip all prompts.
+
+It backs up an existing config before editing, is safe to re-run (idempotent), and uses `jq` when
+available (falling back to Node). You can review it first:
+[`install.sh`](./install.sh).
+
+### Manual install
+
 ```bash
 npm install @stablekernel/opencode-cursor
 ```
@@ -135,7 +155,7 @@ This plugin also registers two **delegation tools** that complement the provider
 | `session` | `false` | Reuse one Cursor agent per opencode session (resume across turns; see below) |
 | `forwardMcp` | `true` | Forward opencode's configured MCP servers to the Cursor agent |
 | `mcpServers` | — | Extra MCP servers (Cursor `McpServerConfig` shape); merged with forwarded ones |
-| `toolDisplay` | `"reasoning"` | How Cursor's internal tool activity is shown: `"reasoning"` (compact lines, works everywhere) or `"blocks"` (structured provider-executed tool blocks; opt-in, see [Tool display](#tool-display)) |
+| `toolDisplay` | `"blocks"` | How Cursor's internal tool activity is shown: `"blocks"` (structured provider-executed tool blocks; default, requires opencode 1.16+) or `"reasoning"` (compact lines, the fallback for older/non-V3 hosts). See [Tool display](#tool-display) |
 
 ### Session reuse (`session`)
 
@@ -156,10 +176,19 @@ opencode delivers per-request, provider-specific settings to the model under
 - `params` → `{ <paramId>: value }` mapped to Cursor `ModelSelection.params`
 - `thinking` → convenience, mapped to the `thinking` param
 
-These are most naturally driven by opencode's **model variant picker**: the plugin auto-generates a
-`plan` variant plus one variant per reasoning/thinking value the model advertises
-(`Cursor.models.list()` parameters). Selecting a variant sends its settings through
-`providerOptions.cursor`. You can also set them statically per model:
+These are most naturally driven by opencode's **model variant picker**: the plugin auto-generates
+one variant per reasoning/effort level a model advertises (`Cursor.models.list()` parameters). A
+boolean parameter (e.g. `thinking: ["false","true"]`) collapses to a single variant named after the
+parameter that switches it on (the off state is the default — no variant selected); enum parameters
+(e.g. `effort`, `reasoning`) produce one variant per value. Selecting a variant sends its settings
+through `providerOptions.cursor`.
+
+> **Plan mode is not a variant.** opencode's **plan agent** (toggled with `Tab`) is mapped to
+> Cursor's plan mode automatically by the plugin's `chat.params` hook, so switching opencode into
+> plan mode puts the Cursor agent into plan mode too. An explicit `mode` from a selected variant or
+> model option still wins.
+
+You can also set controls statically per model:
 
 ```json
 { "provider": { "cursor": { "models": {
@@ -302,31 +331,46 @@ no sidecar is spawned.
 Cursor runs its own agent loop and executes its own tools. The `toolDisplay` option controls how
 that activity appears in opencode:
 
-- **`"reasoning"` (default)** — each tool call is shown as a compact reasoning line
-  (`[tool] write {"path":…}`; failures as `[tool] x failed`). Robust on every host: no tool-call
-  parts cross into opencode, so there's no dependency on how the host treats provider-executed
-  tools.
-- **`"blocks"` (opt-in)** — tool activity is emitted as structured, **provider-executed**
+- **`"blocks"` (default)** — tool activity is emitted as structured, **provider-executed**
   `tool-call`/`tool-result` parts so opencode renders proper, collapsible tool blocks with inputs
   and outputs. opencode skips execution for provider-executed calls (they're display-only), so
-  Cursor's tools (`shell`, `mcp`, …) don't trigger an "unavailable tool" error. This requires a
+  Cursor's tools (`shell`, `mcp`, …) don't trigger an "unavailable tool" error. Requires a
   V3-native opencode host (1.16+).
 
-Enable blocks mode in your opencode config:
+  Where a Cursor tool has a natural opencode counterpart, it's surfaced under opencode's
+  **registered** tool name so its native renderer is used instead of a generic block: `edit` →
+  opencode's diff viewer (via `metadata.diff`), `shell` → `bash` console, `task` → the subagent
+  card, web search (which Cursor runs as an MCP tool) → the `websearch` renderer, and
+  `read`/`write`/`glob`/`grep`/`ls`/`updateTodos` → opencode's
+  `read`/`write`/`glob`/`grep`/`list`/`todowrite` renderers. Cursor's arg shape is translated to
+  opencode's (e.g. `path` → `filePath`); the call stays provider-executed, so it's display-only and
+  never re-run on disk.
+
+  Tools with no opencode counterpart still get cleaned up: `readLints` and `delete` render as
+  formatted `cursor_*` blocks (a diagnostics list / a one-line confirmation) rather than raw JSON,
+  and any MCP tool's `content` is flattened to readable text. Anything else — or a result with an
+  unexpected shape — falls back to a prefixed `cursor_*` block with the raw payload.
+- **`"reasoning"` (fallback)** — each tool call is shown as a compact reasoning line
+  (`[tool] write {"path":…}`; failures as `[tool] x failed`). Robust on every host: no tool-call
+  parts cross into opencode, so there's no dependency on how the host treats provider-executed
+  tools. Use this on older/non-V3 opencode hosts.
+
+The default needs no configuration. To force the reasoning fallback (e.g. on a pre-1.16 host):
 
 ```jsonc
 {
   "provider": {
     "cursor": {
-      "options": { "toolDisplay": "blocks" }
+      "options": { "toolDisplay": "reasoning" }
     }
   }
 }
 ```
 
-> Why opt-in: `"blocks"` depends on V3-native, provider-executed dynamic tool parts and has been
-> verified against opencode 1.16+. `"reasoning"` requires nothing from the host and remains the
-> always-safe default. If `"blocks"` renders cleanly for you, it's the nicer experience.
+> Why blocks by default: structured tool blocks are the nicer experience and have been verified
+> against opencode 1.16+. `"blocks"` depends on V3-native, provider-executed dynamic tool parts; if
+> your host predates that (or renders them poorly), set `"toolDisplay": "reasoning"` — it requires
+> nothing from the host and works everywhere.
 
 ## Troubleshooting
 
@@ -336,6 +380,17 @@ Enable blocks mode in your opencode config:
   with `OPENCODE_CURSOR_SIDECAR=1`.
 - **"Running under Bun without a usable Node sidecar" warning.** Install Node.js 22+, or set
   `OPENCODE_CURSOR_SIDECAR=0` to accept in-process behavior and silence the warning.
+- **"Could not locate the bindings file" / `node_sqlite3.node` not found.** `@cursor/sdk` depends on
+  the native `sqlite3` addon, and opencode installs plugins with Bun, which skips sqlite3's install
+  script — so the prebuilt binary may be missing. The plugin detects this and self-heals on first SDK
+  load by running sqlite3's own `prebuild-install -r napi` under your system Node (requires Node on
+  `PATH`). If it can't (no Node, offline), it logs a one-line manual fix: `cd` into the printed
+  sqlite3 directory and run `npx prebuild-install -r napi` (or `npm rebuild sqlite3`). Set
+  `OPENCODE_CURSOR_DEBUG=1` to see the repair output.
+- **Plugin looks enabled but no `cursor` provider/models appear.** opencode caches a plugin by its
+  install spec under `~/.cache/opencode/packages/`; a stale cache from an older version can persist.
+  Pin an exact version (`@stablekernel/opencode-cursor@<version>`) or delete the cached dir and
+  restart so opencode reinstalls.
 - **Only the four fallback models appear in the picker.** The live catalog loads after the first
   authenticated use — restart opencode once after logging in, or run `cursor_refresh_models` to
   force a refresh.

package/dist/provider/index.d.ts

@@ -4,10 +4,9 @@ import { AgentModeOption, McpServerConfig, SettingSource, AgentDefinition } from
 /**
  * How Cursor's internal tool activity (shell/read/edit/mcp/…) is surfaced to
  * opencode:
- *  - `"reasoning"` (default): rendered as compact reasoning lines. Robust on
- *    every host — no tool-call parts cross the execution boundary.
- *  - `"blocks"`: emitted as provider-executed AI-SDK `tool-call`/`tool-result`
- *    parts so opencode renders structured tool blocks. The parts must carry
+ *  - `"blocks"` (default): emitted as provider-executed AI-SDK
+ *    `tool-call`/`tool-result` parts so opencode renders structured tool
+ *    blocks. Requires a V3-native opencode host (1.16+). The parts must carry
  *    BOTH `providerExecuted: true` AND `dynamic: true` — ai's `parseToolCall`
  *    (v6, `doParseToolCall`) only exempts that combination from registered-tool
  *    validation; without `dynamic` an unknown name raises `NoSuchToolError`,
@@ -58,9 +57,11 @@ interface CursorProviderOptions {
     session?: boolean;
     /**
      * How Cursor's internal tool activity (shell/read/edit/mcp/…) is surfaced:
-     *  - `"reasoning"` (default): compact reasoning lines (works on every host).
-     *  - `"blocks"`: structured provider-executed `tool-call`/`tool-result` parts
-     *    so opencode renders proper tool blocks. Opt-in; requires a V3-native host.
+     *  - `"blocks"` (default): structured provider-executed `tool-call`/
+     *    `tool-result` parts so opencode renders proper tool blocks. Requires a
+     *    V3-native opencode host (1.16+).
+     *  - `"reasoning"`: compact reasoning lines; the fallback for older/non-V3
+     *    hosts (works everywhere).
      */
     toolDisplay?: ToolDisplay;
 }