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.tsas the single source for the tested OpenCode CLI set (2.2.6,2.2.7), the@opencode/pluginpeer range (2.2.6 || 2.2.7), and the CLI-to-API mapping. - Widened the optional
@opencode/pluginpeer from2.2.1to the tested API range.@opentui/core,@opentui/solid, andsolid-jsstay optional. EnsembleV2Service.start()warns once per realm on an unsupportedctx.app.version(console.warnplus ahost.unsupportedlog 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
| Item | Value |
|---|---|
| OS | Linux (Debian GNU/Linux 13) |
| Terminal host | tmux 3.5a |
| Node | 26.12.1 |
| OpenCode | opencode v2.2.7 |
| Provider | local OpenAI-compatible fake provider; no model, credentials, or external network |
Commands and results
| Command | Result |
|---|---|
npm run verify | Pass — strict type check; 1955 tests passed, 0 failed, 0 skipped, 0 todo (54.8 s). |
npm run test:live:probe | Pass — isolated OpenCode 2.2.7 + fake provider; 14/14 contract tests pass against the fresh record. |
npm run test:live:fake:all | Pass — fake 459 s, fake-empty 8 s; 2 passed, 0 failed, 0 skipped, 0 not run. |
git diff --check | Pass — 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:
[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.