[AlaeddineMessadi]

OpenCode V2 changes session, input, permission and lifecycle contracts, so existing V1 routes cannot preserve their behavior directly. This adds typed V1/V2 adapters, detection, read-only diagnostics, normalized operations, durable V2 jobs and native MCP Tasks while preserving V1 support.

Prerelease scope

Prepare 3.1.0-rc.2 with experimental V2 support. V2 maps 64 tools, retains 22 intentional V1-only exceptions, and disables opencode_command_execute before submission. V1 commands remain available. The manifest also covers resources, templates and prompts, and generates the compatibility reference.

The user approved this reduced prerelease scope. The original 65-tool milestone remains incomplete, but upstream command correlation #49690 does not block this experimental candidate. Nothing has been merged or published. Future publication must use the tested archive with --tag next, preserving stable npm latest at 3.0.0.

Compatibility and issue #31

• Integrate the applicable local OPENCODE_AUTO_SERVE silently times out (30s) against OpenCode v2: serve no longer prints "opencode server listening on ..." #31 fix from the other agent: reject recognized V2/newer executables before V1 SDK auto-start, charge the version probe against the startup deadline, and provide V2 connection instructions. Unknown launcher versions retain bounded SDK startup. Invalid V1 health JSON cannot trigger replacement startup; failed owned children close exactly once.
• Preserve authentication failures, external/shared process ownership, and successful detection of an existing V2 server after a V1 HTML response. V2 auto-start remains intentionally unsupported.
• Pin the V2 client/isolated CLI to 2.0.32, retaining V1 SDK support and native 1.18.31 tests. Adapt project listing and URL-prefix handling, including event streams.
• Include bounded macOS cleanup retries for transient Darwin EPERM and ESRCH races; persistent failures remain errors. Refresh vulnerable lockfile dependencies within existing ranges.
• Keep parent-session creation conservatively guarded pending semantic validation. Keep staged reverts reversible and reject operations that implicitly commit them upstream.

Validation

• Clean installation, Node 22.23.3 full suite and coverage: 774 passed, 3 skipped on macOS arm64. Coverage: 72.09% statements, 70.85% branches, 72.74% functions, 75.28% lines.
• Node 24.20.0 full suite: 774 passed, 3 skipped before the final SyntaxError-only parser refinement; the pushed revision is checked on both runtimes by CI.
• Generated docs, whitespace checks and npm audit pass; zero advisories.
• The exact retained archive passed a production-only installation, executable help/version, initialization, discovery, fixture-backed calls and shutdown on Node 22.
• The same archive passed isolated native V1 1.18.31 and V2 2.0.32 checks on both Node 22.23.3 and 24.20.0: runtime identity, doctor read-only/no startup/redaction behavior, project/file/config reads, session CRUD/list, disconnect survival and cleanup. V2 doctor correctly reported no configured provider in the isolated environment; this is not inference-readiness evidence.
• All six hosted Ubuntu/macOS/Windows × Node 22/24 jobs passed on d173d13d38961d350ad07f9644ddd5bd2b21ffd9, including full tests, generated docs, installed-package and isolated native compatibility checks. Ubuntu Node 22 also passed coverage and audit. CI run 39155772654. Exact-archive Node 24 native checks also passed locally.

Archive: opencode-mcp-3.1.0-rc.2.tgz, 196116 bytes, 134 entries. Integrity: sha512-coxSRIxFzipefaddTrZNs0iQ4Z0y8U1Bciu5FSKoWyk2FWLcfARV0w3BMBUVRJG5+CMUMgEjv7BToAeMoj46hw==.

An initial coverage run overlapped another build writing shared dist and produced a CLI exit mismatch; a standalone rerun and clean-install suite passed. The failure log is retained, and subsequent builds/tests ran sequentially.

Evidence boundaries

Live inference, durable execution/restart recovery, cancellation against a provider, interactive forms/permissions, OAuth completion and GUI clients remain unverified. Fixture/contract tests do not establish those behaviors. Keep V2 experimental until the documented live acceptance checks pass. Windows Node 26 from #31 is outside the Node 22/24 matrix.

Addresses #31; contributor PR #34's OpenChamber authentication work remains separate. The other agent's uncommitted worktree and the earlier rc.1 archive remain intact.

See plans/008-experimental-prerelease.md for acceptance and archive evidence, plans/007-ci-and-opencode-2.0.32.md for the preceding upgrade, plans/004-v2-writes-input.md for the command unblock checklist, and MIGRATION.md for lifecycle/option limitations.

[brocasm]

Interressing about this PR, wainting merge to test this MCP

[AlaeddineMessadi]

Thanks for your interest, @brocasm! This PR adds OpenCode V1/V2 compatibility and better setup diagnostics. It’s still a draft while we finish validation and work through an upstream V2 API limitation.

If you’d like to test it before the merge, I’d be happy to share setup instructions. Feedback on your MCP client and workflow would be really helpful!

[bonsai]

Context that may be useful for the V2 detection/readiness work in this branch.

Testing 3.0.0 against OpenCode v2 (@opencode/cli 2.0.28, Windows 11 / Node 26) surfaced a silent 30s hang on the auto-serve path, reported in #31. The two detection points that differ from v1:

• Readiness handshake. @opencode-ai/sdk's createOpencodeServer waits for a stdout line starting with opencode server listening. On v2 that prefix is gone — opencode serve prints server listening on http://127.0.0.1:<port> followed by server password <generated>. So the promise never resolves and only the timeout fires.
• Health probe. isServerRunning() requires JSON {healthy:true} from /global/health. On v2 that path returns the web app shell (200 text/html), so a running v2 server is still reported unhealthy — which also means OPENCODE_BASE_URL + a manually started server does not work around the handshake issue, and OPENCODE_AUTO_SERVE=false just converts the hang into "server is not running".
• Auth. v2 rejects unauthenticated API calls (/api/* → 401) and generates the password at startup, so credential plumbing differs from the Basic-auth support in 3.0.0.

No action requested — flagging the readiness/handshake expectations in case they're relevant here. I can re-test against @opencode/cli 2.0.x on Windows/Node 26 if that's useful.

[AlaeddineMessadi]

Status update and new plan for this PR.

Upstream: anomalyco/opencode#49690 is still open. In 2.2.0 the session.command contract is byte-identical to 2.0.32: it returns 204 with no invocation id and no receipt. So opencode_command_execute stays disabled on V2. Bumping this branch to @opencode/client@2.2.0 builds and passes the fixture suite (771 passed, 6 skipped). That was not a live run.

Plan: #35 (thanks @norandom!) ports the server to the 2.x /api surface. It lands first as the base for 4.0.0. 1.x users stay on a 3.x maintenance line. I'm converting this PR to a draft. Once #35 merges, I'll bring the useful pieces over to 4.x as small follow-up PRs, without rebasing all of this:

• the doctor command and backend detection
• the live compatibility harnesses (test-compat, test-package)
• the Windows spawn fix and the macOS cleanup retries
• delivery: "queue" and the staged-revert guard, if Port to the OpenCode 2.x server API (4.0.0) #35 doesn't already cover them

@brocasm, thanks for your patience. If you're on OpenCode 2.x, #35 is the one to watch and test.