feat: rebuild the Cursor adapter for OpenCode V2

[CasualDeveloper]

Hey, @makeittech - was excited to try out Astra and I think it did a great job with our plugin!

Issue for this PR

Refs #31. Please keep it open through publication and release checks.

This PR supersedes #34 and includes its release-flow documentation and constants-test explanation. Please review and merge this PR directly.

Type of change

• New feature
• Refactor / code improvement

What does this PR do?

I rebuilt the Cursor adapter for OpenCode V2 and removed the old proxy and compatibility code. It keeps private models and exact variants while OpenCode manages history, tools, permissions, and compaction.

Each new Cursor Run is built from OpenCode's messages and tool results, including images and reasoning data. This lets the host recover after a lost connection or restart without a second conversation store.

Each step reports Cursor's checkpoint occupancy as its input and its streamed output tokens as its output, so OpenCode's context meter and compaction follow the real conversation size. Before, tool steps reported no usage, so one long session filled a 1M context without compacting, and single-step Runs reported Run totals larger than the window, so compaction ran too early. Exact Run totals, including cache reads and writes, stay in provider metadata. Cursor gives no per-call cache split, so OpenCode's cost estimate is an upper bound on long tool loops.

Cursor is offered only its MCP tool family: the same x-cursor-agent-allowed-tools list the official SDK sends for tools: ["mcp"]. Models see OpenCode's tool names and schemas instead of a second set of Cursor-native tools. The list includes get_mcp_tools_tool_call, so Cursor still starts normally; allowing only mcp_tool_call broke bootstrap. Native workspace requests that still arrive (shellStreamArgs, shellArgs, grepArgs, readArgs, writeArgs, lsArgs) map to OpenCode host tools, empty-pattern grep calls route to glob, and tool result JSON envelopes are unwrapped.

Every Cursor exec frame and interaction query now gets a reply:

• Native shell streams finish with shellResult and streamClose. Without them, Cursor kept the turn pending after every shell call, so each continuation stalled until the watchdog fired. This is why long sessions looked stuck.
• Frames the adapter can't serve fail in band with throw and streamClose instead of leaving Cursor waiting.
• Cursor-hosted web search, Exa, web fetch, question, and mode-switch prompts are declined so the model uses OpenCode's tools. Plan creation gets an error, and VM setup fails the Run.
• Native StrReplace is declined. Cursor applies it to the read result as raw bytes, so it would write OpenCode's formatted read output back into the file.

A resumed Run waits up to 180 seconds for first output, like a fresh one. A rebuilt Run tells the model that the preceding tool results answer its own calls, instead of an opener that read like an interruption. The host-contract rule names OpenCode's rules as the application's system prompt rather than the user's.

I updated the adapter after OpenCode removed context.catalog. It now uses context.provider.transform() and reload(), refreshes models on credential.switched, and preserves failed-tool outcomes in structured compaction requests. Dependencies and the test host are pinned to released @opencode/* 2.0.6. Older hosts with the catalog API are no longer supported.

Grok opaque-reasoning checkpoints no longer fail a completed turn when a root has no unique assistant anchor. Cursor usable-model IDs group into families: none is the non-thinking SKU, and thinking SKUs become low/medium/high/xhigh/max.

The OpenCode id stays the stable catalog name, such as grok-4.6. Each variant still sends Cursor's exact wire id, such as cursor-grok-4.6-xhigh. All non-duplicate models from AvailableModels are published so newly released and parameterized models (such as Grok 4.7 and Grok 4.7 500K) appear in OpenCode's picker. If OpenCode has loaded a models.dev Cursor row, I copy that row's limits and price. I do not copy lab caps, and I do not replace the live catalog with a static list.

I also fixed model grouping against Cursor's real parameter spellings: any effort parameter (including reasoning_effort and minimal) groups into variants on one model, and Claude's thinking flag stays on that same model (none is non-thinking, while effort variants keep thinking enabled) instead of creating separate models. Connect error message details are also preserved in the transport.

How did you verify your code works?

The current head is 8ea167b. I amended it onto the previous head because #35 had no review activity. npm run verify passes locally and in CI against the pinned 2.0.6 host. The host fixture now uses 2.0.6's permission and form APIs, which fixes the earlier Missing key ["decision"] failure.

Live checks for this head ran on WSL through OpenCode 2.0.14 with Composer 2.5, Grok 4.7, and Auto:

• A multi-step task (list files, read them, run a failing test, fix the bug, re-run) finished in 23 to 49 seconds with no stalls or retries. Before the shell-stream fix, the same Composer task stalled after every shell step and did not finish in 10 minutes.
• Per-step input followed checkpoint occupancy as the conversation grew, and ranged reads returned exactly the requested lines.
• With a project AGENTS.md requiring one reply and the user asking for another, the models followed the project instruction in 18 of 18 trials, up from 6 of 9 with the old host-contract wording.

Instruction priority on Opus and with images, opaque-reasoning replay, and continued work after automatic compaction still need live verification. The test report records the remaining limits.

Checklist

• I have tested my changes locally.
• I have not included unrelated changes in this PR.