From 8faf2bf887947036f3b6efdf6c5447fbe6cd5b29 Mon Sep 17 00:00:00 2001 From: Justin Carper Date: Wed, 10 Jun 2026 16:02:58 -0500 Subject: [PATCH] docs: correct variants, plan mode, sqlite self-heal MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Align docs with rc.2: variants are per reasoning/effort level (boolean params collapse to one on-variant), no synthetic plan variant; document plan agent → Cursor plan mode; add sqlite binding self-heal and stale plugin-cache troubleshooting; add the rc.2 changelog entry. --- CHANGELOG.md | 31 ++++++++++++++++++++++++++++--- README.md | 28 ++++++++++++++++++++++++---- 2 files changed, 52 insertions(+), 7 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index aafb871..b48e7b9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,29 @@ All notable changes to this project will be documented in this file. ## [Unreleased] +- `0.1.0-rc.2` — pre-release on the npm `next` dist-tag. Fixes found while + validating rc.1 against opencode 1.16.2: + - **Plugin now loads when installed by package name.** Added the + `exports["./server"]` entry opencode uses to resolve a plugin's entrypoint; + rc.1 exposed the plugin only at `./plugin`, which opencode does not read, so + the package installed but registered no hooks (no provider, no models). + - **Self-heal the `sqlite3` native binding.** opencode installs plugins with + Bun, which skips sqlite3's install script, so `@cursor/sdk`'s + `require("sqlite3")` failed with "Could not locate the bindings file". The + plugin now runs sqlite3's `prebuild-install -r napi` under the system Node + before loading the SDK (once per process, never throws). + - **Stream ordering.** The final answer no longer renders above the reasoning + blocks that preceded it — the open text part is closed when reasoning + resumes and each resume opens a fresh text part. + - **Model variants reach the picker.** Variants are seeded on the + config-injected models (opencode discards the `provider.models()` hook for + providers outside its models.dev catalog). Variant naming reworked against + the real catalog: boolean params (e.g. `thinking`) collapse to one + param-named variant instead of literal `true`/`false`; enum params key by + value. The synthetic `plan` variant was removed. + - **Plan agent → Cursor plan mode.** opencode's plan agent (`Tab`) is mapped + to Cursor's plan mode via the `chat.params` hook; an explicit variant/option + mode still wins. - `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`. @@ -21,8 +44,9 @@ 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 @@ -56,7 +80,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 diff --git a/README.md b/README.md index 8a4cda5..fb71253 100644 --- a/README.md +++ b/README.md @@ -156,10 +156,19 @@ opencode delivers per-request, provider-specific settings to the model under - `params` → `{ : 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": { @@ -336,6 +345,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@`) 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.