phoebus_os/docs/OPENCODE.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

187 lines
8.2 KiB
Markdown

# OpenCode connection workflow
OpenCode is integrated as a **real agent-server connection**, not a renamed
OpenAI-compatible endpoint. The adapter speaks OpenCode's session/message API
and feeds the same strict proposal parser, evidence review and executor as the
direct providers.
Read [ADR 0011](adr/0011-opencode-connection-boundary.md) first.
## Four components, not one
| Component | What it is | Where it runs |
|-----------|------------|---------------|
| OpenCode client | `opencode` TUI/CLI, or `opencode attach <url>` | your machine |
| OpenCode server | `opencode serve` — an HTTP/JSON **agent** API, not a model API | same machine as the client or the model |
| Model inference service | DeepSeek/OpenAI, or a local OpenAI-compatible server | provider cloud or your LAN |
| Phoebus installer/broker | the typed, privileged, local executor | the target machine only |
**An OpenCode server URL does not go in the direct-provider endpoint field.**
Select the OpenCode backend instead; Phoebus speaks the agent protocol.
## Configuration
```toml
[ai]
enabled = true
backend = "opencode" # "direct" (default) or "opencode"
opencode_server = "http://127.0.0.1:4096"
opencode_provider = "deepseek"
opencode_model = "deepseek-chat"
# The server password is a secret: supply it at runtime, never here.
```
The server password is stored in protected runtime input (a 0600 file or the GUI
secret pipe) and is **separate** from a direct provider API key.
## Command line
```sh
# Read-only: classify the server. Exits nonzero unless a model catalog exists.
phoebus-installer --opencode-probe http://127.0.0.1:4096 \
--opencode-provider deepseek --opencode-model deepseek-chat
# Acceptance: obtain and validate a real model response. Exits nonzero on any
# failure. This is the inference check, not a reachability check.
phoebus-installer --opencode-test http://127.0.0.1:4096 \
--opencode-provider deepseek --opencode-model deepseek-chat \
--opencode-password-file /path/to/server.pw
# Installer guidance through OpenCode (a real proposal is reviewed and applied).
phoebus-installer --ai-backend opencode \
--opencode-server http://127.0.0.1:4096 \
--opencode-provider deepseek --opencode-model deepseek-chat \
--install --ai
# The installed assistant uses the same adapter.
sys ask --ai-backend opencode --opencode-server http://127.0.0.1:4096 \
--opencode-provider deepseek --opencode-model deepseek-chat \
"show the transaction history"
```
`--opencode-password-file` must be mode 0600, like the direct provider key file.
## Graphical installer
On the **AI model** step choose **OpenCode agent**, then fill in the server URL,
the server password (if the server has one), the provider and the model. Two
actions are available:
- **Test connection** obtains and validates a real model response
(`ai_test`); it does not change the installation plan.
- **Connect and validate** obtains a real proposal through OpenCode and runs the
strict review (`ai_check`). Only then does the wizard allow continuing, and
only then does the backend accept the AI prerequisite for installation.
Changing the server, provider, model or password — or editing the configuration
— invalidates the validated state.
## Connection states
`phoebus-installer --opencode-probe` prints one of:
| State | Meaning |
|-------|---------|
| `insecure_transport` | the destination failed the transport policy |
| `unreachable` | the server could not be reached |
| `authentication_required` | the server returned 401 and no credential was supplied |
| `authentication_rejected` | a credential was supplied and rejected |
| `incompatible` | a response arrived but was not the expected API/JSON |
| `reachable` | healthy server with no model catalog |
| `model_catalog` | healthy server with a model catalog |
| `selected_model_unavailable` | the chosen provider/model is not in the catalog |
| `ready` | reserved for a real, validated model response (not the probe) |
A model catalog is not readiness. The probe never returns `ready`; only a real
inference that validates the response does.
## Transport policy
- Plain `http://` is accepted **only** when the resolved destination is
loopback. The host is resolved and the connection is pinned to the checked
address, so a DNS answer that changes after the check cannot move the target.
- Remote access is `https://` (curl verifies the certificate; verification is
never disabled) **or** an authenticated encrypted tunnel terminating on
loopback (SSH `-L`, WireGuard, ...).
- Redirects are disabled, the protocol is restricted to `http,https`, and
connect time, total time, header/body sizes and response size are bounded.
- A URL with userinfo, a path or a control character is rejected.
## Security
- The server the assistant talks to should run unprivileged with a restricted
configuration. OpenCode permission settings are not an OS sandbox: run the
Phoebus-facing server with a dedicated directory, no plugins, and no
developer sessions, and keep the model credentials out of its reach where the
deployment allows.
- The adapter requests **no tools** per message (`"tools": {...false}`) as
defence in depth, but that is not a substitute for process isolation.
- Destructive product actions remain in the local typed broker with local human
approval. The agent never receives a shell, root, credentials or private-file
access, and disk/account passphrases are never sent to it.
- The adapter creates a transient session per request, accepts only the
completed assistant text parts (never user, tool or reasoning parts) and
deletes the session afterwards, so installation facts are not retained.
## A. OpenCode on the development/VM host
```sh
export DEEPSEEK_API_KEY="$(cat ~/.config/phoebus/deepseek.key)" # 0600 file
opencode serve --hostname 127.0.0.1 --port 4096
opencode attach http://127.0.0.1:4096 # interactive client
phoebus-installer --opencode-probe http://127.0.0.1:4096
```
Keep the server on `127.0.0.1`; do not enable `--mdns` or bind `0.0.0.0`
without authentication.
## B. OpenCode on a separate user-controlled computer
Run the server on that computer bound to **loopback** and reach it through an
authenticated encrypted tunnel:
```sh
# remote:
opencode serve --hostname 127.0.0.1 --port 4096
# local:
ssh -N -L 127.0.0.1:4096:127.0.0.1:4096 you@remote.example
phoebus-installer --opencode-probe http://127.0.0.1:4096
```
If a tunnel is impossible, set `OPENCODE_SERVER_PASSWORD` and terminate TLS in
front of the server; never expose an unauthenticated plaintext service.
### VM networking is not one thing
| Endpoint | Meaning |
|----------|---------|
| `guest 127.0.0.1` | the guest's own loopback |
| `host 127.0.0.1` | the host's loopback (invisible to the guest) |
| `10.0.2.2` | the QEMU user-net gateway to the host |
| `192.168.x.y` | a real LAN address, reachable by other machines |
A VM guest cannot name the host's loopback directly, and plain `http` to the
gateway is refused by policy. The supported pattern is a host-local relay bound
to the **guest's** loopback (the same shape as an SSH tunnel); the VM harness
uses a tiny TCP forwarder for exactly this.
## Verified evidence (2026-09-22)
- `opencode 1.18.32` (pinned manifest: `v1.18.31`; version mismatch noted).
- `--opencode-probe` → `model_catalog`, 223 providers / 7915 models, 26
connected; the selected `deepseek:deepseek-v4-flash` present.
- `--opencode-test` → `validated model response: {"phoebus":"ok"}` (real
inference), exit 0.
- The GUI bridge `ai_check` over OpenCode applied 8 reviewed changes from a real
`deepseek-v4-flash` proposal.
- `sys ask` over OpenCode proposed a read-only `history` action and executed it
deterministically.
- Authentication: no credential → `authentication_required`; wrong →
`authentication_rejected`; correct → `model_catalog` and a successful real
inference.
- Transport policy: plain `http` to a LAN/global address →
`insecure_transport`, exit 1, no request sent.
- Real-HTTP integration tests cover status preservation, chunked multibyte
bodies, oversized bodies, redirects, abrupt disconnects and authentication.
- A separate physical computer remains **unverified**; a second server bound to
the LAN address reached through a loopback tunnel is the remote-topology test.