Files
hex/docs/opencode-compatibility.md
T
Dax 3434eb5f35 Rename voice-control to hex everywhere, without migrations (#293)
* Rename voice-control to hex everywhere, without migrations

The Cargo package and binary are now hex, every OS keeps its data in a
hex folder, and VOICE_CONTROL_* variables are HEX_*. Hex is a fresh
app: the macOS voice-control rename, its symlink, and the Windows and
Linux beta settings imports are gone. The Windows installer gets a new
AppId so it never takes over an old voice-control install's entry.

* Format

* Drop the Windows paste-last default only the beta import used
2026-10-28 13:08:44 -04:00

4.9 KiB

OpenCode V2 Compatibility

Validation Baseline

The 2026-08-26 compatibility baseline is OpenCode V2 commit 6c392355dd6c4f15889d28273c6e3dbf69c4548c and the official V2 API reference. The newest published V2-branch CLI verified in the npm registry was @opencode-ai/cli@0.0.0-dev-18334, published from that same commit by release run 18334. 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 discovers a separately installed opencode2, optionally overridden by HEX_OPENCODE_CLI. It does not bundle or pin the runtime CLI, own the managed service, or restart or update it. opencode2 api discovers or starts the service through OpenCode's own lifecycle.

Catalog loading and generation use opencode2 api get /api/info to identify the authenticated active server, starting it through the CLI when needed. A CLI HTTP 404 Not Found as the last stderr line (earlier lines may be warnings, such as a client/server version mismatch) falls back to the older /api/status, then /api/health, names within the same deadline; any other failure is final. Hex reads endpoint and password together from the bounded, owner-only service registration matching that server's PID and version, in the state directory opencode2 debug paths reports and in OpenCode's default one ($XDG_STATE_HOME/opencode, else ~/.local/state/opencode). A wrapper that rejects debug paths or redirects the CLI's own state still finds the default service's registration. It never reads or regenerates the configured password, changes service settings, or includes credentials in diagnostics.

The system curl sends the authenticated request over loopback HTTP. Credentials and JSON travel in a curl configuration through stdin, never command arguments or temporary files. Curl configuration files, proxies, and redirects are not used. Wildcard bind addresses (0.0.0.0 and ::) and localhost are normalized to loopback; other non-loopback endpoints are rejected. Discovery, request writing, and response waiting share the generation deadline and cancellation signal.

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. 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. curl reports the status on a trailing line so a missing route is distinguished from a served error body. 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.

Check the connected server's /api/info version as well as the CLI version: the CLI's api command permits a server version mismatch. Do not replace a user's running service to perform compatibility validation.

Keep regression coverage for body/credential privacy, curl configuration escaping, large bodies, loopback-only admission, blocked input pipes, and cancellation.