feat: Cursor provider plugin for opencode

opencode provider + plugin backed by @cursor/sdk, plus permission-gated
cursor_delegate / cursor_cloud_agent tools. Bun-safe via an automatic Node
sidecar for the SDK's streaming RPC. Prepared as v0.1.0-rc.1.

Author: justin-carper

.github/dependabot.yml

@@ -0,0 +1,15 @@
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+    groups:
+      dev-dependencies:
+        dependency-type: "development"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

.github/workflows/ci.yml

@@ -0,0 +1,60 @@
+name: CI
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: typecheck · test · build (node ${{ matrix.node-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        node-version: ["22.x", "24.x"]
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Node ${{ matrix.node-version }}
+        uses: actions/setup-node@v6
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Typecheck
+        run: npm run typecheck
+
+      - name: Test
+        run: npm test
+
+      - name: Build
+        run: npm run build
+
+  integration:
+    name: e2e · opencode loads plugin & lists models
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: "24.x"
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install opencode, load the plugin, and list Cursor models
+        run: bash scripts/integration-test.sh
+        env:
+          # Optional: when set, the script additionally verifies live auth and
+          # Cursor.models.list(). Without it, the fallback model path is tested.
+          CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }}

.github/workflows/release.yml

@@ -0,0 +1,69 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"
+      - "v[0-9]+.[0-9]+.[0-9]+-*"
+
+permissions:
+  contents: write   # create GitHub Release
+  id-token: write   # npm provenance attestation
+
+jobs:
+  release:
+    name: Publish to npm + create GitHub Release
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: "22.x"
+          registry-url: "https://registry.npmjs.org"
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Typecheck, test, and build
+        run: npm run prepublishOnly
+
+      # Run the full integration test (no CURSOR_API_KEY → fallback path).
+      # Skip with SKIP_INTEGRATION=true for patch releases that don't touch
+      # the plugin/provider entry-points.
+      - name: Integration smoke test
+        if: env.SKIP_INTEGRATION != 'true'
+        run: bash scripts/integration-test.sh
+        env:
+          CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }}
+
+      # A tag with a pre-release suffix (e.g. v0.1.0-rc.1) publishes to the
+      # `next` dist-tag and is flagged as a GitHub pre-release, so `npm install`
+      # and the repo's "Latest" release keep pointing at the last stable.
+      - name: Classify release from tag
+        id: version
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+          echo "VERSION=$VERSION" >> "$GITHUB_OUTPUT"
+          if [[ "$VERSION" == *-* ]]; then
+            echo "NPM_TAG=next" >> "$GITHUB_OUTPUT"
+            echo "PRERELEASE=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "NPM_TAG=latest" >> "$GITHUB_OUTPUT"
+            echo "PRERELEASE=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Publish to npm
+        run: npm publish --provenance --access public --tag "${{ steps.version.outputs.NPM_TAG }}"
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v3
+        with:
+          name: "v${{ steps.version.outputs.VERSION }}"
+          generate_release_notes: true
+          prerelease: ${{ steps.version.outputs.PRERELEASE }}
+          make_latest: ${{ steps.version.outputs.PRERELEASE == 'false' }}

.gitignore

@@ -0,0 +1,16 @@
+node_modules/
+dist/
+*.log
+.DS_Store
+coverage/
+
+# Packaging artifacts
+*.tgz
+
+# Local editor / agent tooling
+.serena/
+.opencode/
+.claude/
+
+# Local-only dev config (never commit)
+opencode.json

.npmrc

@@ -0,0 +1 @@
+registry=https://registry.npmjs.org/

CHANGELOG.md

@@ -0,0 +1,88 @@
+# Changelog
+
+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.1.0] — 2026-06-10
+
+Initial public release. A complete opencode integration for Cursor built on the
+official `@cursor/sdk`: a streaming chat provider, an auth/config/model plugin,
+and a permission-gated delegation tool surface.
+
+### Provider
+
+- **Cursor provider** backed by the official `@cursor/sdk` — drives a local
+  Cursor agent (`Agent.create` / `agent.send`) and translates its `onDelta`
+  callbacks into AI SDK `LanguageModelV3` stream parts (text, reasoning,
+  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.
+- **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` /
+    `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
+    with opencode-registered tools, and carry `providerExecuted: true` +
+    `dynamic: true` so ai v6's `parseToolCall` accepts them without
+    registered-tool validation. Tool-results use the V3-spec `result` +
+    `isError` fields. A tool call whose completion never arrives (run
+    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.
+
+### Node sidecar (Bun compatibility)
+
+- **Automatic Node sidecar** — opencode runs on Bun, whose `node:http2` client
+  is incompatible with the Cursor SDK's long-lived streaming RPC
+  (`NGHTTP2_FRAME_SIZE_ERROR`), causing native tool calls to execute but never
+  report completion. When Bun is detected and `node` is on `PATH`, the SDK
+  agent is hosted in a Node child process and driven over a JSON-lines stdio
+  protocol; the provider is otherwise unchanged. Under Node the SDK runs
+  in-process. Override with `OPENCODE_CURSOR_SIDECAR=1` (force on) or
+  `OPENCODE_CURSOR_SIDECAR=0` (force in-process / silence the Bun warning).
+
+### Plugin
+
+- **opencode plugin** (`@stablekernel/opencode-cursor/plugin`): 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
+  `cursor_refresh_models` tool. The auth loader warms a key-independent catalog
+  cache so the model picker is populated on first authed load (and restart)
+  rather than showing only the fallback snapshot.
+- **MCP server forwarding** — opencode's configured `config.mcp` entries are
+  translated to Cursor `McpServerConfig` and passed to the local agent so it can
+  use the same servers (e.g. Serena). Opt out with `provider.cursor.options.forwardMcp`.
+- **Model discovery** with a 24-hour cache (keyed by key fingerprint) and a
+  built-in fallback snapshot (composer-2.5, claude-opus-4-8, claude-sonnet-4-6,
+  gpt-5.5) for use without an API key.
+
+### Delegation tools
+
+- **`cursor_cloud_agent`** — launch a Cursor cloud (background) agent on a
+  remote repo via `Agent.create({ cloud: { repos, autoCreatePR } })`; returns
+  the agent id, terminal status, result, and PR url. Progress is collected from
+  `run.onDidChangeStatus`, `onStep`, and `onDelta`.
+- **`cursor_delegate`** — run a single local Cursor turn as a permission-gated,
+  auditable opencode tool call (reuses the provider's `acquireAgent` +
+  `streamAgentTurn` plumbing). Both tools honor opencode's `permission` config
+  via `ToolContext.ask` and are fail-closed when no permission gate is present.
+
+### Tooling
+
+- **Provider debug tracing** — opt-in via `OPENCODE_CURSOR_DEBUG=1`.
+- End-to-end CI: unit tests on two Node versions plus a full integration test
+  (opencode loads the plugin, lists models, optionally runs a live chat turn).

CONTRIBUTING.md

@@ -0,0 +1,73 @@
+# Contributing
+
+Thanks for your interest in improving `@stablekernel/opencode-cursor`! Issues and pull
+requests are welcome.
+
+## Reporting issues
+
+- **Bugs / features:** open an issue at
+  <https://github.com/stablekernel/opencode-cursor/issues>.
+- **Security vulnerabilities:** do **not** file a public issue — see
+  [SECURITY.md](./SECURITY.md).
+
+When reporting a runtime bug, please include:
+
+- your runtime (Bun vs. Node) and version, and your opencode version,
+- whether the Node sidecar is in use (Bun + `node` on `PATH`),
+- output from running with `OPENCODE_CURSOR_DEBUG=1`.
+
+## Development setup
+
+Requires **Node.js 22+**.
+
+```bash
+npm install
+npm run typecheck
+npm test
+npm run build
+
+# End-to-end: install the real opencode CLI, load this plugin, and assert
+# `opencode models` lists the Cursor provider (no API key required — uses the
+# fallback snapshot; set CURSOR_API_KEY to also verify live discovery).
+bash scripts/integration-test.sh
+```
+
+CI runs unit tests + build on Node 22 and 24 plus the end-to-end check on every
+push. Built with `@cursor/sdk`, `@opencode-ai/plugin`, and `@ai-sdk/provider`.
+
+## Pull requests
+
+- Add or update tests for behavior changes (this repo uses
+  [Vitest](https://vitest.dev); see `test/`).
+- Keep `npm run typecheck`, `npm test`, and `npm run build` green.
+- Update `CHANGELOG.md` under the appropriate version/`[Unreleased]` heading.
+
+## Releasing (maintainers)
+
+The `.github/workflows/release.yml` workflow publishes automatically when a
+version tag is pushed:
+
+```bash
+# 1. Bump the version in package.json (patch / minor / major)
+npm version patch          # or: minor, major, or e.g. --new-version 0.2.0
+
+# 2. Push the commit and the generated tag together
+git push origin main --follow-tags
+```
+
+The release job will:
+
+1. Run `prepublishOnly` (typecheck → test → build) to gate the publish.
+2. Run the integration smoke test (uses the `CURSOR_API_KEY` secret if set).
+3. Publish to npm with [provenance attestation](https://docs.npmjs.com/generating-provenance-statements).
+4. Create a GitHub Release with auto-generated release notes.
+
+**Required repository secrets** (Settings → Secrets → Actions):
+
+| Secret | Purpose |
+| --- | --- |
+| `NPM_TOKEN` | npm automation token with `publish` access |
+| `CURSOR_API_KEY` | (optional) live-path integration test during release |
+
+**Pre-publish checklist:** update `CHANGELOG.md`, confirm `version` in
+`package.json` matches the tag, and ensure the branch is merged to `main`.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 justin-carper
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.