mirror of
https://github.com/anomalyco/hex.git
synced 2026-11-21 02:09:25 +08:00
* annotate: send through OpenCode in WSL when the lab is on * annotate: address review * annotate: dropped wsl replies read as no answer
110 lines
6.6 KiB
Markdown
110 lines
6.6 KiB
Markdown
# 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, when no Windows registration answers and Labs › OpenCode in WSL
|
||
is on, it reads the default WSL distribution's registration at
|
||
`<home>/.local/state/opencode` through `\\wsl.localhost\`, or `\\wsl$\` on
|
||
an older Windows 10. `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; opening it can start the WSL VM too). One lookup
|
||
runs at a time on a shared helper thread with a fixed 3 s discover budget.
|
||
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. 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.
|