Skip to content

OpenCode peer compatibility matrix (#257) ​

Status: implemented and verified locally on OpenCode 2.2.7; the 2.2.6/2.2.7 CI matrix is committed and runs the same commands. Date: 2026-11-12 Issue: #257 Spec: #255 Branch: ticket/257-peer-matrix Base: integration/prod-partials at a1fe441; merged 26b32c3 (ticket #263)

What changed ​

  • Added src/v2/host-compatibility.ts as the single source for the tested OpenCode CLI set (2.2.6, 2.2.7), the @opencode/plugin peer range (2.2.6 || 2.2.7), and the CLI-to-API mapping.
  • Widened the optional @opencode/plugin peer from 2.2.1 to the tested API range. @opentui/core, @opentui/solid, and solid-js stay optional.
  • EnsembleV2Service.start() warns once per realm on an unsupported ctx.app.version (console.warn plus a host.unsupported log record). Missing required host APIs still reject during location attachment.
  • Added .github/workflows/compatibility.yml, a matrix for OpenCode 2.2.6 and 2.2.7 that runs the preflight, the native host contract probe, and the deterministic fake/empty smoke suites. It is separate from the Node matrix.
  • Documented the supported range and mapping in the host support range, the README, and the runtime guide.

Environment ​

ItemValue
OSLinux (Debian GNU/Linux 13)
Terminal hosttmux 3.5a
Node26.12.1
OpenCodeopencode v2.2.7
Providerlocal OpenAI-compatible fake provider; no model, credentials, or external network

Commands and results ​

CommandResult
npm run verifyPass — strict type check; 1955 tests passed, 0 failed, 0 skipped, 0 todo (54.8 s).
npm run test:live:probePass — isolated OpenCode 2.2.7 + fake provider; 14/14 contract tests pass against the fresh record.
npm run test:live:fake:allPass — fake 459 s, fake-empty 8 s; 2 passed, 0 failed, 0 skipped, 0 not run.
git diff --checkPass — no whitespace errors.

The 2.2.6 host contract was recorded by ticket #210; the compatibility workflow re-runs the same probe and deterministic fake smoke on 2.2.6. This ticket did not rewrite the committed fixture.

Runtime warning ​

An unsupported host reports, once per service realm:

text
[ensemble] OpenCode 2.2.5 is not supported by this Ensemble build; supported hosts are 2.2.6 and 2.2.7 (@opencode/plugin 2.2.6 || 2.2.7). Ensemble will continue, but behavior on this version is untested.

The warning is non-fatal. A missing ctx.rpc.register, tool transform, storage, or event subscription still fails the attachment, as before. The warning contains no paths, conversation content, or credentials.

Privacy ​

The warning carries only the normalized host version and the public supported set. The probe record is checked by the existing privacy gate before it is uploaded on failure. No message text, file bytes, credentials, or absolute paths were added to logs or fixtures.

Released under the MIT License.