phoebus_os/docs/adr/0011-opencode-connection-boundary.md
Phoebus c16014ade8 feat(gui): select and validate OpenCode from the installer
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).
2026-09-22 02:36:36 -07:00

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:

  1. 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.
  2. The installed server, with no OPENCODE_SERVER_PASSWORD, binds loopback and warns that it is unsecured. Its /config/providers response 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

  1. 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.
  2. Connection states are typed and honest. phoebus-executor::opencode_server probes /global/health and /config/providers and reports one of Disconnected, AuthenticationRequired, ReachableNoModel, Incompatible, or Ready. Ready means 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.
  3. 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.
  4. 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.
  5. The installer's AI step uses a real OpenCode adapter (implemented after this ADR was first written). phoebus-executor::opencode_client speaks the OpenCode session/message API over the project's curl transport and implements the same ModelTransport trait 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 assistant TextParts (never user/tool/reasoning parts), disables tools per message, and deletes the session on every path. The GUI, the installer CLI and sys ask all select it through canonical configuration (ai.backend = "opencode").
  6. 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. Ready is 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 credential key, so only ids and model names are kept).
  • POST /session rejects a model field (BadRequest) despite the OpenAPI schema; the model is selected on the message.
  • POST /session/{id}/message returns the assistant reply synchronously; format: json_schema is 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}/abort and DELETE /session/{id} clean up.
  • Authentication is HTTP Basic with username opencode and the OPENCODE_SERVER_PASSWORD value; 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-gated PHOEBUS_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.