phoebus_os/docs/adr/0011-opencode-connection-boundary.md
Phoebus 3d43f8c6c8 feat(executor): add an OpenCode server capability probe
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).
2026-09-21 20:01:44 -07:00

3.4 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 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.