* 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
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.