hex/docs/opencode-compatibility.md
Dax de7b012035
prefer a wsl opencode service when the lab is on (#2112)
* prefer a wsl opencode service with the lab on

* fix labs wsl diagram wording

* address review: wsl budget test and doc accuracy
2026-11-20 19:14:28 -05:00

114 lines
7 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# OpenCode V2 Compatibility
## Validation Baseline
The 2026-08-26 compatibility baseline is OpenCode V2 commit
[`6c392355dd6c4f15889d28273c6e3dbf69c4548c`](https://github.com/anomalyco/opencode/tree/6c392355dd6c4f15889d28273c6e3dbf69c4548c)
and the [official V2 API reference](https://opencode.ai/v2/docs/api/).
The newest published V2-branch CLI verified in the npm registry was
[`@opencode-ai/cli@0.0.0-dev-18334`](https://www.npmjs.com/package/@opencode-ai/cli/v/0.0.0-dev-18334),
published from that same commit by
[release run 18334](https://github.com/anomalyco/opencode/actions/runs/33009417492).
Its catalog, generation, and service-discovery contracts are unchanged from the
initial audit at `009eca8b5baa01b690753992725b450d045dd623`.
This records source review and local regression tests, including authenticated
loopback generation with a 1 MB JSON body, cancellation, and deadline expiry.
A provider-backed generation test also passed using CLI `0.0.0-dev-18334` and
the already-running server `0.0.0-dev-18329`, without creating a session or
restarting the service.
This is a dated validation snapshot, not a claim about the newest CLI available
today. The integration contract below describes Hex's current implementation;
new provider-backed validation must record its own CLI and server versions.
## Integration Contract
Hex never runs an OpenCode executable, never starts or restarts the service,
and never searches for or probes an installed CLI. It only talks to an already
running service (`src/desktop/opencode_service.rs`):
- It reads the bounded registration `service.json` (the stable, beta and dev
channels), then other channels' `service-<channel>.json`, in
`$XDG_STATE_HOME/opencode`, else `~/.local/state/opencode`; OpenCode uses the
same path on Windows. On macOS and Linux the file must be a regular file the
user owns with no group or other permissions.
- On Windows, with Labs › OpenCode in WSL on, it also reads the default WSL
distribution's registration at `<home>/.local/state/opencode` through
`\\wsl.localhost\`, or `\\wsl$\` on an older Windows 10; a WSL service that
answers `/api/info` is used ahead of a Windows one, and the Windows service
is used when WSL answers nothing. `HKCU\Software\Microsoft\Windows\CurrentVersion\Lxss`
is read on every lookup; a remembered home is reused only while its
`DistributionName` and `DefaultUid` still match, otherwise the home is
rebuilt from that distribution's `/etc/passwd` (at most 1 MiB, and only the
default distribution). With the lab on, every lookup also looks in WSL even
when a Windows service is healthy, waiting up to 3 s for it, and that read
can start the WSL VM. One lookup runs at a time on a shared helper thread
with a fixed 3 s discover budget; when Windows already confirmed a service,
the WSL lookup is capped at that 3 s (or the caller's smaller remaining
budget), so a cold distribution can't hold a rewrite or Annotate's send. Its
starter waits for its own remaining deadline or Escape; a joiner waits at
most the smaller of its own budget and the cap minus the lookup's age, and
returns "OpenCode isn't running" at once once that lookup is older than the
cap. A timeout or cancel never aborts the
shared lookup. A lookup that used its full cap without finding a service
pauses new lookups for 10 s. The cached home is dropped when its state
directory can't be read, when the default distribution or uid changes, and
on the next search that runs with the lab off. A scoped request to a WSL
service that fails (a transport error or 404) forgets the workspace so the
next one retries creating it. WSL2 forwards loopback, so the registered URL
is dialed as registered. No `wsl.exe` runs, and passwd contents and passwords
are never logged. `XDG_STATE_HOME` inside WSL is not read, and a home absent
from `/etc/passwd` (LDAP/SSSD) is not found.
- Annotate's capture router (`crates/router`) reaches OpenCode through the
same Windows discovery. With the lab on and a WSL service, its local
requests and session reads go through that service. The prompt's recorded-at
line names the capture folder as the Linux server sees it (`X:\a\b` →
`/mnt/x/a/b`, following `/etc/wsl.conf`'s `[automount]` root and its
`enabled = false`), while the summary header keeps the Windows path. When
WSL answers nothing, a native Windows service or a discovery that found none
leaves the router's own `service.json` and loopback path unchanged, and with
the lab off nothing changes.
- The registration's `url` must be loopback `http://` (`localhost`, `0.0.0.0`
and `::` are reached through loopback); anything else is refused.
- `GET /api/info` with the registration's password (HTTP Basic, user
`opencode`) must answer with the registered `pid` (and `version`, when
registered). Otherwise the registration is stale and OpenCode isn't running.
- Requests are HTTP/1.1 over `TcpStream`; content-length and chunked answers are
decoded, bounded to 16 MiB, and every wait observes the caller's deadline and
cancellation. Credentials never reach diagnostics.
When no service answers, features report "OpenCode isn't running" and link to
the OpenCode docs; Hex starts nothing.
Hex reads `/api/model` and `/api/model/default` through authenticated HTTP, avoiding
large piped CLI responses. It supplies `x-opencode-directory` for its Application
Support workspace; a service found in WSL gets a Linux workspace instead
(`<home>/.local/share/hex/opencode`), because a Windows path is relative to a
Linux server. Model selections use the catalog's `id`, not the upstream
provider's `modelID`. Available text-output models remain selectable regardless
of release status, including alpha and beta. Selecting a thinking variant for the
floating default saves the resolved catalog model alongside it; existing explicit
model selections are preserved.
One-shot generation accepts a prompt and optional model reference and returns
`data.text`. Current OpenCode serves it at `/api/experimental/generate`; Hex
falls back to the older `/api/generate` only when the server answers the new
route with HTTP 404, within the same generation deadline. It is stateless and uses the server's base configuration, not the
catalog request's directory header. Existing saved selections whose catalog and
upstream IDs match need no migration. Previously broken alias selections can be
fixed by reselecting the model; Hex does not guess an ID migration.
## Updating The Baseline
Pin an exact CLI version and source commit for isolated release-validation runs,
then deliberately update this baseline after testing the contracts above,
deadlines, and cancellation. At the 2026-08-26 audit, the `v2` source branch
published to npm's `dev` tag; `next` was an older beta, not the newest V2 build.
Resolve the published version rather than assuming a moving tag identifies the
desired source commit.
Record the connected server's `/api/info` version. Do not replace a user's
running service to perform compatibility validation.
Keep regression coverage for registration privacy, stale registrations,
loopback-only admission, chunked answers, deadlines, and cancellation.