Add an 'OpenCode agent' choice with server/password/provider/model fields, a Test connection action, and a secret-free frontend state line the harness asserts. Require exactly one installer session and assert the current step and AI state instead of inferring from a screenshot. Add a live-OpenCode acceptance make target and document the adapter, transport policy, states and workflows (ADR 0011 updated).
5.2 KiB
ADR 0011: OpenCode connection boundary
- Status: Accepted
- Date: 2026-09-22
Context
The assignment requires a working OpenCode connection on the development/VM host
and from a separate user-controlled computer, while keeping the model untrusted
and the destructive broker local. OpenCode is an agent application, not an
OpenAI-compatible inference endpoint. Upstream's opencode serve exposes an
HTTP/JSON API (/global/health, /session, /config/providers, ...) with
optional basic authentication; opencode attach and opencode run --attach
connect a client to it.
Two facts shape the decision:
- A successful TCP connect, a health check or an HTTP 200 does not prove that a usable model is configured, nor that the model can emit a valid Phoebus proposal. The skill set must distinguish those states explicitly.
- The installed server, with no
OPENCODE_SERVER_PASSWORD, binds loopback and warns that it is unsecured. Its/config/providersresponse includes the provider credentials in cleartext. Exposing that service to a LAN would leak those credentials and hand an agent's tool surface to the network.
Decision
- Four components are named separately and may live on different machines: the OpenCode client, the OpenCode server, the model inference service, and the Phoebus installer/broker. An OpenCode server URL is never placed in Phoebus's local-model endpoint field.
- Connection states are typed and honest.
phoebus-executor::opencode_serverprobes/global/healthand/config/providersand reports one ofDisconnected,AuthenticationRequired,ReachableNoModel,Incompatible, orReady.Readymeans reachable, healthy, API-compatible and holding at least one model; it still does not prove a valid proposal round-trip. The probe keeps only counts from/config/providers, never the credentials it may contain. - Remote access is loopback plus an authenticated encrypted tunnel (SSH
port-forward, WireGuard, or equivalent). The probe accepts plain
http://only, because a direct TLS-less LAN bind is not an approved transport. - The OpenCode agent never inherits Phoebus privilege. Its tools, shell, file and plugin access are outside Phoebus's execution path. Destructive product actions still go through the local typed broker and local human approval. The OpenCode configuration is written mode 0600 and carries no credentials.
- The installer's AI step uses a real OpenCode adapter (implemented after
this ADR was first written).
phoebus-executor::opencode_clientspeaks the OpenCode session/message API over the project's curl transport and implements the sameModelTransporttrait as the direct providers, so the strict proposal parser, evidence review, facts and executor are reused unchanged. The adapter creates a transient session per request, accepts only the completed assistantTextParts (never user/tool/reasoning parts), disables tools per message, and deletes the session on every path. The GUI, the installer CLI andsys askall select it through canonical configuration (ai.backend = "opencode"). - A provider name is not a validated interaction. Both the GUI bridge and
the installer CLI require a successful, validated model interaction bound to
the current configuration (and credential) before installation; changing the
model, endpoint, server or credential invalidates it.
Readyis reserved for a real, validated response.
Protocol notes (verified against the shipped opencode 1.18.32)
- Health:
GET /global/health. Catalog:GET /provider(metadata; upstream may include a credentialkey, so only ids and model names are kept). POST /sessionrejects amodelfield (BadRequest) despite the OpenAPI schema; the model is selected on the message.POST /session/{id}/messagereturns the assistant reply synchronously;format: json_schemais rejected by the DeepSeek models in use ("Thinking mode does not support this tool_choice"), so the prompt carries an explicit change-object shape instead.POST /session/{id}/abortandDELETE /session/{id}clean up.- Authentication is HTTP Basic with username
opencodeand theOPENCODE_SERVER_PASSWORDvalue; Bearer is not accepted.
Consequences
- Remote OpenCode is not a one-click feature: the operator runs a tunnel. This is deliberate; the alternative is an unauthenticated credential-leaking agent endpoint on the LAN.
- The capability probe is testable against fake HTTP servers and against a real
opencode serve(env-gatedPHOEBUS_OPENCODE_PROBE), so compatibility is verified rather than assumed. - Developer use (this repository) and assistant use (approved bounded facts and typed proposals) remain clearly separated by tools and permissions.
Status
Accepted and implemented. The probe, the adapter and the connection states are
implemented with unit, real-HTTP integration, live-model and bridge tests; the
graphical installer can select OpenCode and obtain a real validated proposal.
End-to-end installation still does not depend on OpenCode: a direct provider
or the deterministic sys path remains available, and an installed system works
without a model.