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).
95 lines
5.2 KiB
Markdown
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.
|