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

95 lines
5.2 KiB
Markdown

# 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 `TextPart`s (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.