opencode-raven 2.2.1 → 2.3.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 2.3.0
+
+### Added
+- OpenCode 2 support through a native `setup()` adapter, sharing Raven configuration and MCP runtime with OpenCode 1.
+- V2 agent/tool registration, shell routing, model discovery, guidance injection, child-session completion waiting, cancellation, continuation validation, and provider-error handling.
+- A v2 terminal companion and typed RPC contract for immediate `/raven` command output and notifications without a model turn.
+- Native-host smoke checks, including offline v2 routing and delegation, alongside v1/v2 regression tests.
+
+### Changed
+- Raised the OpenCode 1 minimum to 1.18.29 for the shared `server()`/`setup()` object entrypoint. The v2 adapter targets OpenCode 2.0.26 and newer 2.x releases.
+- OpenCode 2 installation uses `plugins`; OpenCode 1 continues to use `plugin`.
+- V2 update instructions delegate cache management to OpenCode instead of deleting v1 cache paths.
+
+## 2.2.2
+
+### Added
+- Fresh installs automatically select an available zero-cost, tool-capable model from OpenCode's connected provider catalog for Raven Search and Raven MCP.
+- `/raven seek model auto` and `/raven mcp model auto` retry free-model detection.
+
+### Changed
+- Removed the retired `opencode/deepseek-v4-flash-free` default. Raven now leaves routing inactive and shows first-time setup instructions when no suitable free model is available.
+- Auto-selected models are rechecked on startup, while manually configured models are never replaced.
+
 ## 2.2.1
 
 ### Fixed

package/README.md

@@ -1,6 +1,7 @@
 <div align="center">
   <h1>opencode-raven</h1>
   <p><strong>Keep noisy tool work out of your main OpenCode context.</strong></p>
+  <p><strong>Supports OpenCode V2 (2.0.26+) and OpenCode V1 (1.18.29+), in one package.</strong></p>
   <p>
     <a href="https://www.npmjs.com/package/opencode-raven"><img src="https://img.shields.io/npm/v/opencode-raven.svg" alt="npm version" /></a>
     <a href="https://www.npmjs.com/package/opencode-raven"><img src="https://img.shields.io/npm/dm/opencode-raven.svg" alt="npm downloads" /></a>
@@ -29,7 +30,21 @@
 
 ## Install
 
-Raven requires OpenCode 1.15.12 or newer. Add it to `opencode.jsonc`:
+**Raven 2.3 supports OpenCode V2 (2.0.26+).** OpenCode V1 (1.18.29+) remains supported in the same package—no separate plugin is needed.
+
+### OpenCode V2
+
+Use the v2 `plugins` key in `opencode.jsonc`:
+
+```jsonc
+{
+  "plugins": ["opencode-raven"]
+}
+```
+
+### OpenCode V1
+
+Use the v1 `plugin` key in `opencode.jsonc`:
 
 ```jsonc
 {
@@ -37,10 +52,35 @@ Raven requires OpenCode 1.15.12 or newer. Add it to `opencode.jsonc`:
 }
 ```
 
-Restart OpenCode, then run `/raven` to verify the loaded version, model, routing, MCP health, and estimated savings.
+Restart OpenCode, then run `/raven` to verify the loaded version, model, routing, MCP health, and estimated savings. A fresh install may ask for one additional restart after selecting its model.
 
 OpenCode resolves the package from npm and caches it automatically.
 
+### Upgrading From OpenCode 1 To 2
+
+Keep using `opencode-raven`; change its OpenCode config entry from `plugin` to `plugins`. Raven's existing `~/.config/opencode/opencode-raven/raven-config.json` is shared by both versions, including models, on-demand MCPs, routing settings, and stats. Quit and restart OpenCode after upgrading.
+
+OpenCode 1 uses Raven's `server()` entrypoint; OpenCode 2 uses `setup()` and automatically loads the terminal companion. The terminal companion displays `/raven` command results in a dialog and delivers startup/update warnings as toasts, without sending a prompt to the model. The v2 server also exposes the typed `opencode-raven/rpc` command contract for other clients.
+
+The v1 minimum is 1.18.29 because earlier versions cannot load the shared object entrypoint. See OpenCode's [plugin migration guide](https://opencode.ai/v2/docs/build/plugins/migrate-v1) for the upstream lifecycle and config changes.
+
+For local development, v1 can load `file:///path/to/opencode-raven/index.ts`; v2 requires the package directory, `file:///path/to/opencode-raven`.
+
+### First-Time Setup
+
+On first start, Raven checks OpenCode's connected provider catalog and automatically selects an available zero-cost, tool-capable model from the `opencode` provider for both Raven agents. Free-model availability is controlled by the provider and can change.
+
+If a free model is found, Raven writes it to the config and asks you to restart OpenCode once to load it. After restarting, `/raven` shows it with `(auto)`. Raven rechecks auto-selected models after startup and replaces one only when it is no longer available. A model you set manually is never replaced.
+
+If no suitable free model is available, Raven shows a setup warning and leaves search routing inactive rather than silently using a paid model. Open OpenCode's model picker to choose an available model, then run:
+
+```txt
+/raven seek model <provider/model>
+/raven mcp model <provider/model>
+```
+
+Restart OpenCode afterward. You can retry free-model detection at any time with `/raven seek model auto` and `/raven mcp model auto`.
+
 ## Example
 
 <p align="center">
@@ -95,7 +135,8 @@ Manual edits require an OpenCode restart. Route and timeout commands apply immed
 
 | Field | Fresh-install default | Description |
 |-------|-----------------------|-------------|
-| `raven_seek.model` | From `Raven.md` | Search-agent model override. |
+| `raven_seek.model` | Auto-detected free OpenCode model, otherwise unset | Search-agent model. Manual values are preserved. |
+| `raven_seek.autoSelectedModel` | Managed by Raven | Tracks whether the Search model can be safely refreshed automatically. |
 | `raven_seek.reasoning_effort` | `low` | Search-agent reasoning option. |
 | `raven_seek.instructions` | `""` | Extra search-agent instructions. |
 | `raven_seek.routeTools` | Search/fetch tools plus `bash` | Exact tools routed through Raven Search. |
@@ -103,7 +144,8 @@ Manual edits require an OpenCode restart. Route and timeout commands apply immed
 | `raven_seek.excludeAgents` | `[]` | Agents allowed to bypass search routing. |
 | `raven_seek.excludeTools` | `[]` | Exact tools never routed through Raven Search. |
 | `raven_seek.timeout` | `600` | Search delegation timeout in seconds. |
-| `raven_mcp.model` | From `RavenMcp.md` | MCP-agent model override. |
+| `raven_mcp.model` | Auto-detected free OpenCode model, otherwise unset | MCP-agent model. Manual values are preserved. |
+| `raven_mcp.autoSelectedModel` | Managed by Raven | Tracks whether the MCP model can be safely refreshed automatically. |
 | `raven_mcp.reasoning_effort` | `low` | MCP-agent reasoning option. |
 | `raven_mcp.instructions` | `""` | Extra MCP-agent instructions. |
 | `raven_mcp.timeout` | `600` | MCP delegation and fallback connection timeout in seconds. |
@@ -166,7 +208,7 @@ Generated MCP metadata and main-model guidance live beside `raven-config.json`.
 
 ## Routing
 
-Default routed tools are `grep`, `glob`, `webfetch`, `fetch`, `websearch`, and search-like `bash` commands.
+Default routed tools are `grep`, `glob`, `webfetch`, `fetch`, `websearch`, and search-like `bash` commands. On OpenCode 2, Raven also recognizes the native `shell` tool; `bash` and `shell` are routing aliases, so existing routing settings continue to work. Exact `excludeTools` entries use the host's actual tool name.
 
 Global MCPs are automatically routed when their OpenCode tool names use the normal `<server>_<tool>` prefix. Use a keyword for suffix-style names:
 
@@ -195,10 +237,10 @@ When `bash` is routed, Raven intercepts primary discovery commands such as `rg`,
 | `/raven mcp` | Show on-demand MCP health and generated metadata. |
 | `/raven mcp refresh [server]` | Recheck MCP health and regenerate metadata. |
 | `/raven mcp detail full|minimized` | Set generated guidance detail; restart afterward. |
-| `/raven seek model <provider/model>` | Change the search model; restart afterward. |
+| `/raven seek model <provider/model>\|auto` | Change or auto-detect the search model; restart afterward. |
 | `/raven seek effort <value>` | Change search reasoning effort; restart afterward. |
 | `/raven seek timeout <seconds>` | Change the search delegation timeout. |
-| `/raven mcp model <provider/model>` | Change the MCP model; restart afterward. |
+| `/raven mcp model <provider/model>\|auto` | Change or auto-detect the MCP model; restart afterward. |
 | `/raven mcp effort <value>` | Change MCP reasoning effort; restart afterward. |
 | `/raven mcp timeout <seconds>` | Change the MCP delegation timeout. |
 | `/raven stats` | Show estimated context avoided. |
@@ -223,12 +265,27 @@ Review `Raven.md` and your MCP commands before using Raven in sensitive environm
 
 ## Troubleshooting
 
+- First-time model warning: select a model in OpenCode's model picker, run `/raven seek model <provider/model>` and `/raven mcp model <provider/model>`, then restart. Use `auto` as the model value to retry free-model detection.
 - Search provider or quota failure: run `/raven seek model <provider/model>`, then restart OpenCode.
 - MCP-agent provider or quota failure: run `/raven mcp model <provider/model>`, then restart OpenCode.
 - MCP failure: run `/raven mcp`, then `/raven mcp refresh <server>` after correcting its URL, command, environment, or credentials.
 - Stale plugin version: run `/raven update`, restart OpenCode, and follow the cache-clearing instructions it prints if needed.
 - Remove Raven: delete `"opencode-raven"` from `plugin`, restart, then optionally remove `~/.config/opencode/opencode-raven/`.
 
+On OpenCode 2, remove it from `plugins` instead. `/raven update` uses v1 cache-clearing behavior only on OpenCode 1; on v2 it checks the version and provides restart/pinned-version instructions while leaving cache management to OpenCode.
+
+## Development Checks
+
+```sh
+bun install
+bun test
+bun run typecheck
+bun scripts/smoke-compat.ts v1 /path/to/opencode-v1
+bun scripts/smoke-compat.ts v2 /path/to/opencode-v2
+```
+
+The native smoke checks use isolated configuration and data directories. The v2 check uses a deterministic local model endpoint to exercise routed main-agent search, direct Raven child search, delegation completion, and command/RPC output without calling a paid model provider.
+
 See [CHANGELOG.md](CHANGELOG.md) for release history.
 
 ## Disclaimer

package/Raven.md

@@ -1,9 +1,8 @@
 ---
-description: Context firewall for OpenCode that routes noisy search, docs, web, GitHub, and MCP calls through a free focused agent before they hit your main model.
+description: Context firewall for OpenCode that routes noisy search, docs, web, GitHub, and MCP calls through a focused agent before they hit your main model.
 mode: subagent
 hidden: false
-model: opencode/deepseek-v4-flash-free
-reasoning_effort: low
+reasoning_effort: low
 permission:
   read: allow
   glob: allow

package/RavenMcp.md

@@ -2,7 +2,6 @@
 description: Focused on-demand MCP agent that retrieves compact information through Raven's internal MCP bridge.
 mode: subagent
 hidden: true
-model: opencode/deepseek-v4-flash-free
 reasoning_effort: low
 permission:
   "*": deny