OpenCode is an agent application, not an OpenAI-compatible endpoint. Add a typed probe over /global/health and /config/providers that distinguishes disconnected, authentication required, incompatible, reachable-no-model and ready, and never returns provider credentials. Expose it as phoebus-installer --opencode-probe. Document the four components, host and tunnelled remote workflows, and the Phoebus assistant boundary (ADR 0011).
66 lines
3.4 KiB
Markdown
66 lines
3.4 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 keeps using its own bounded transport.** OpenCode
|
|
is an optional operator workflow, not a replacement for the typed proposal
|
|
transport; a future adapter must perform a real prompt round-trip and parse a
|
|
versioned proposal before it may claim compatibility.
|
|
|
|
## 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. The probe and its tests are implemented; end-to-end installation does
|
|
not depend on OpenCode.
|