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).
This commit is contained in:
Phoebus 2026-09-22 02:36:36 -07:00
parent 0d65d56eda
commit c16014ade8
10 changed files with 499 additions and 139 deletions

View file

@ -8,7 +8,7 @@
SHELL := /bin/bash SHELL := /bin/bash
.PHONY: help context doctor test test-rust test-vm fmt fmt-check clippy check build static vm hooks commit publish backup forgejo-init public private protect release clean .PHONY: help context doctor test test-rust test-vm opencode-acceptance fmt fmt-check clippy check build static vm hooks commit publish backup forgejo-init public private protect release clean
help: help:
@printf 'Phoebus OS targets:\n' @printf 'Phoebus OS targets:\n'
@ -17,6 +17,7 @@ help:
@printf ' make test run the Rust and VM-harness test suites\n' @printf ' make test run the Rust and VM-harness test suites\n'
@printf ' make test-rust cargo test --workspace\n' @printf ' make test-rust cargo test --workspace\n'
@printf ' make test-vm python3 installer/tests/vm/test_vmsafety.py\n' @printf ' make test-vm python3 installer/tests/vm/test_vmsafety.py\n'
@printf ' make opencode-acceptance live-model acceptance (needs PHOEBUS_OPENCODE_LIVE_*)\n'
@printf ' make fmt cargo fmt --all\n' @printf ' make fmt cargo fmt --all\n'
@printf ' make check fmt-check + clippy + tests\n' @printf ' make check fmt-check + clippy + tests\n'
@printf ' make build release Rust installer\n' @printf ' make build release Rust installer\n'
@ -44,6 +45,16 @@ test-rust:
test-vm: test-vm:
python3 installer/tests/vm/test_vmsafety.py python3 installer/tests/vm/test_vmsafety.py
# A real-model acceptance run. Fails (BLOCKED) when the live server is not
# configured, so it can never pass by silently not running.
opencode-acceptance:
@if [ -z "$$PHOEBUS_OPENCODE_LIVE_URL" ] || [ -z "$$PHOEBUS_OPENCODE_LIVE_PROVIDER" ] || [ -z "$$PHOEBUS_OPENCODE_LIVE_MODEL" ]; then \
echo "BLOCKED: set PHOEBUS_OPENCODE_LIVE_URL, PHOEBUS_OPENCODE_LIVE_PROVIDER and PHOEBUS_OPENCODE_LIVE_MODEL"; \
exit 2; \
fi
cd installer-rs && PHOEBUS_OPENCODE_REQUIRE_LIVE=1 \
cargo test -p phoebus-executor --test opencode_live -- --nocapture
fmt: fmt:
cd installer-rs && cargo fmt --all cd installer-rs && cargo fmt --all

View file

@ -7,6 +7,56 @@ Format: Keep a Changelog. Dates are UTC.
## Unreleased ## Unreleased
### Added
- **Real OpenCode agent-server adapter.** `phoebus-executor::opencode_client`
implements the OpenCode session/message protocol over the project's curl
transport and the `ModelTransport` trait, so the strict proposal parser,
evidence review, bounded facts and executor are reused unchanged. The GUI
("OpenCode agent"), the installer CLI (`--ai-backend opencode`,
`--opencode-server/-provider/-model/-password-file`) and `sys ask` all use it.
It creates a transient session per request, accepts only the completed
assistant text parts, disables tools per message, and deletes the session.
A JSON schema output mode is available in the protocol but is not used: the
shipped DeepSeek models reject it, and the prompt carries an explicit change
shape instead. The `opencode 1.18.32` contract was verified directly: session
creation rejects a `model` field, `/provider` metadata can contain a
credential and is reduced to ids/model names, and auth is HTTP Basic
(`opencode` / `OPENCODE_SERVER_PASSWORD`).
- **`--opencode-test`** obtains and validates a real model response (exit
nonzero on failure), distinct from the read-only `--opencode-probe`. A live
acceptance test (`make opencode-acceptance`) fails as BLOCKED when no server
is configured, so it cannot pass by not running.
- **Truthful OpenCode connection states** (`insecure_transport`, `unreachable`,
`authentication_required`, `authentication_rejected`, `incompatible`,
`reachable`, `model_catalog`, `selected_model_unavailable`); `ready` is
reserved for a validated response and is never returned by the probe.
- **GUI "Test connection"** and OpenCode connection controls, plus a backend
selection (`ai.backend`) in canonical configuration.
### Security
- **The mandatory-AI gate now requires a validated interaction.** Both the GUI
bridge and the installer CLI refuse to install when only a provider name is
configured; a successful, validated model interaction bound to the current
configuration (and credential) is required. Changing the model, endpoint,
server or a secret invalidates it. A direct provider or `--no-ai` remains the
fallback.
- **OpenCode transport policy is enforced.** Plain `http://` is accepted only
when the resolved destination is loopback and the connection is pinned to the
checked address; remote access is `https://` with certificate verification or
an authenticated tunnel to loopback. Redirects, unsafe schemes and oversized
or trickled bodies are bounded, and credentials travel only on curl's stdin.
- **Credentials never surface.** The catalog is reduced to ids/model names;
server responses that echo credentials are not retained, and tests feed
credential-bearing bodies and assert they do not appear in errors or state.
### Fixed
- **OpenCode client/probe defects found by testing:** the handwritten HTTP
reader (no total deadline, UTF-8-unsafe chunk fallback) was removed in favour
of the curl transport; the catalog is no longer parsed on a non-2xx status; a
provider-shaped 500 can no longer look like a catalog; the duplicate-session
harness check requires exactly one session; and GUI navigation is asserted
from secret-free frontend state lines rather than inferred from a screenshot.
### Added ### Added
- **OpenCode connection workflow and capability probe.** New ADR 0011 and - **OpenCode connection workflow and capability probe.** New ADR 0011 and
`docs/OPENCODE.md` separate the four components (client, server, model `docs/OPENCODE.md` separate the four components (client, server, model

View file

@ -3,27 +3,29 @@
Rolling note between work sessions. **Update this file before you finish**, then Rolling note between work sessions. **Update this file before you finish**, then
commit it. It should be short and current; use `git log` for detail. commit it. It should be short and current; use `git log` for detail.
- **Last updated:** this session (2026-09-22), harness + security + polish. - **Last updated:** this session (2026-09-22), OpenCode adapter.
- **Current focus:** Hardened the VM harness (enforced qcow2/`/dev`/backing-chain - **Current focus:** Implemented a real OpenCode agent-server adapter
safety, structured PASS/FAIL results, per-run OVMF+QMP, no `os.system`), (`phoebus-executor::opencode_client`) that speaks the session/message protocol
fixed confirmed security defects (disk revalidation before partitioning, over curl and implements `ModelTransport`, wired into canonical config
bridge replay/concurrency + input bounds, provider transport URL/size (`ai.backend = "opencode"`), the GUI ("OpenCode agent" + Test connection),
hardening, `TargetRoot` symlink escapes, and the `0 B` disk-size probe bug), the installer CLI (`--ai-backend opencode`, `--opencode-test`) and `sys ask`.
added an OpenCode server capability probe + docs/ADR 0011, and fixed the The mandatory-AI gate now requires a validated interaction with invalidated
welcome focus ring and the untruthful mid-install cancellation. state. The probe/transport were hardened (loopback/TLS policy, DNS pinning,
status checks, auth), and the GUI harness gained exact-session and
frontend-state assertions.
- **Last verified (this session):** - **Last verified (this session):**
- `gui-driver.py gui` on the rebuilt ISO: **23/23 PASS**, exit 0. Welcome - 336 Rust tests + 16 harness tests green; fmt/clippy clean.
autostarts; Return launches the installer (focus fixed); duplicate sessions - Real inference through `opencode 1.18.32` with `deepseek-v4-flash`;
prevented; live medium protected; keyboard navigation reaches network + AI; `--opencode-test` → `{"phoebus":"ok"}`; the GUI bridge `ai_check` applied 8
advancing without a model is refused and starts nothing. reviewed changes; `sys ask` proposed and ran a read-only action.
- `make test` green (Rust + 16 harness unit tests); `cargo fmt --check`, - Auth: none → `authentication_required`, wrong → `authentication_rejected`,
`cargo clippy --workspace --all-targets` (no errors), release + static correct → `model_catalog` + successful inference. Plain http to a LAN host
builds. → `insecure_transport`, exit 1, no request sent.
- OpenCode probe: `ready` against `opencode 1.18.32`; `authentication_required` - 7 real-HTTP integration tests (status, chunked multibyte, oversize,
(exit 1) against an unauthenticated LAN bind. redirect, disconnect, auth) and 2 env-gated live tests.
- ISO: `installer/live/phoebus-installer-amd64.iso` 1.6 GiB, - **Not yet verified this session:** the full graphical install through
`sha256 428dbd7547db8690596bf5c3a0d7a6fa8aee4c9f9eca1e926c216712dd050b36`; OpenCode in a VM, and a separate physical computer. The pinned manifest is
static binary `sha256 2f9cd4b36a12e469d2b6187166acaf8b11f7f382cc19f7ad08bb2a809c855591`. `v1.18.31` while the tested binary is `1.18.32`.
- **Public repo:** <https://git.phoebus.club/phoebus/phoebus_os> - **Public repo:** <https://git.phoebus.club/phoebus/phoebus_os>
(remote `origin`, SSH port 2222). (remote `origin`, SSH port 2222).

View file

@ -1,13 +1,9 @@
# OpenCode connection workflow # OpenCode connection workflow
OpenCode is used in two clearly separated ways: OpenCode is integrated as a **real agent-server connection**, not a renamed
OpenAI-compatible endpoint. The adapter speaks OpenCode's session/message API
1. **Developer workflow** — on this repository, inspecting sanitized evidence. and feeds the same strict proposal parser, evidence review and executor as the
Full tool access (shell, files, plugins) is fine because it runs as *you*, direct providers.
on *your* machine, against *your* checkout.
2. **Phoebus assistant connection** — approved, bounded system facts and
validated typed proposals. It must never inherit the developer tool
permissions and never receives secrets.
Read [ADR 0011](adr/0011-opencode-connection-boundary.md) first. Read [ADR 0011](adr/0011-opencode-connection-boundary.md) first.
@ -16,84 +12,147 @@ Read [ADR 0011](adr/0011-opencode-connection-boundary.md) first.
| Component | What it is | Where it runs | | Component | What it is | Where it runs |
|-----------|------------|---------------| |-----------|------------|---------------|
| OpenCode client | `opencode` TUI/CLI, or `opencode attach <url>` | your machine | | OpenCode client | `opencode` TUI/CLI, or `opencode attach <url>` | your machine |
| OpenCode server | `opencode serve` — an HTTP/JSON **agent** API, not a model API | usually the same machine as the client or the model | | 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 (Ollama, llama.cpp, ...) | provider cloud or your LAN | | 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 | | Phoebus installer/broker | the typed, privileged, local executor | the target machine only |
**An OpenCode server URL does not go in Phoebus's local-model endpoint field.** **An OpenCode server URL does not go in the direct-provider endpoint field.**
An OpenCode server is an agent application; it is not an OpenAI-compatible Select the OpenCode backend instead; Phoebus speaks the agent protocol.
`/v1/chat/completions` endpoint. Pointing Phoebus's `local` provider at it will
fail, and would be the wrong trust boundary even if it parsed.
## Capability probe (never assume compatibility) ## Configuration
```sh ```toml
phoebus-installer --opencode-probe http://127.0.0.1:4096 [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.
``` ```
It is read-only and prints a typed state, exiting nonzero unless a model is The server password is stored in protected runtime input (a 0600 file or the GUI
available: 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 | | State | Meaning |
|-------|---------| |-------|---------|
| `disconnected` | TCP connect failed; the service is down | | `insecure_transport` | the destination failed the transport policy |
| `authentication_required` | the server answered 401/403; supply the password/tunnel | | `unreachable` | the server could not be reached |
| `incompatible` | a health response arrived but the API shape is not the expected one | | `authentication_required` | the server returned 401 and no credential was supplied |
| `reachable_no_model` | healthy server, no model configured | | `authentication_rejected` | a credential was supplied and rejected |
| `ready` | reachable, healthy, API-compatible, and ≥1 model configured | | `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) |
`ready` still does **not** prove the model can emit a valid Phoebus proposal; A model catalog is not readiness. The probe never returns `ready`; only a real
that requires a real prompt round-trip and proposal parse. A health check or an inference that validates the response does.
HTTP 200 is not that proof.
The probe reads `/global/health` and `/config/providers`, keeps only counts from ## Transport policy
the latter, and never returns the provider credentials that upstream includes in
that response. - 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 ## A. OpenCode on the development/VM host
```sh ```sh
# 1. Set a provider credential through the environment (never a file in git).
export DEEPSEEK_API_KEY="$(cat ~/.config/phoebus/deepseek.key)" # 0600 file export DEEPSEEK_API_KEY="$(cat ~/.config/phoebus/deepseek.key)" # 0600 file
# 2. Start the server on loopback only. Upstream warns when it is unsecured.
opencode serve --hostname 127.0.0.1 --port 4096 opencode serve --hostname 127.0.0.1 --port 4096
opencode attach http://127.0.0.1:4096 # interactive client
# 3. In another terminal, attach a client to it.
opencode attach http://127.0.0.1:4096
```
Keep the server on `127.0.0.1`. Do not pass `--mdns` and do not bind `0.0.0.0`
without authentication: the server's configuration API can expose provider
credentials.
## 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. SSH port-forwarding is the simplest approved
transport:
```sh
# On the remote computer:
opencode serve --hostname 127.0.0.1 --port 4096
# From your machine (tunnel local 127.0.0.1:4096 -> remote loopback:4096):
ssh -N -L 127.0.0.1:4096:127.0.0.1:4096 you@remote.example
# Then, locally:
opencode attach http://127.0.0.1:4096
phoebus-installer --opencode-probe http://127.0.0.1:4096 phoebus-installer --opencode-probe http://127.0.0.1:4096
``` ```
The probe now sees a loopback endpoint and the tunnel supplies transport Keep the server on `127.0.0.1`; do not enable `--mdns` or bind `0.0.0.0`
authentication and encryption. If you cannot use a tunnel, set without authentication.
`OPENCODE_SERVER_PASSWORD` and terminate TLS in front of the server; never
expose an unauthenticated plaintext service. ## 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 ### VM networking is not one thing
Inside a VM these are different endpoints and must not be confused:
| Endpoint | Meaning | | Endpoint | Meaning |
|----------|---------| |----------|---------|
| `guest 127.0.0.1` | the guest's own loopback | | `guest 127.0.0.1` | the guest's own loopback |
@ -101,36 +160,28 @@ Inside a VM these are different endpoints and must not be confused:
| `10.0.2.2` | the QEMU user-net gateway to the host | | `10.0.2.2` | the QEMU user-net gateway to the host |
| `192.168.x.y` | a real LAN address, reachable by other machines | | `192.168.x.y` | a real LAN address, reachable by other machines |
## C. Phoebus assistant boundary 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.
When a Phoebus assistant uses OpenCode: ## Verified evidence (2026-09-22)
- Run the service unprivileged, with restricted filesystem access. - `opencode 1.18.32` (pinned manifest: `v1.18.31`; version mismatch noted).
- Disable tools you do not need. OpenCode permission settings are *not* an - `--opencode-probe` → `model_catalog`, 223 providers / 7915 models, 26
operating-system security boundary; enforce isolation outside the prompt. connected; the selected `deepseek:deepseek-v4-flash` present.
- Keep the destructive execution path in Phoebus's local broker with local human - `--opencode-test` → `validated model response: {"phoebus":"ok"}` (real
approval. The agent is never given a shell, root, credentials or private-file inference), exit 0.
access. - The GUI bridge `ai_check` over OpenCode applied 8 reviewed changes from a real
- Keep credentials in protected runtime storage (0600, outside model context). `deepseek-v4-flash` proposal.
Never forward disk passphrases or account passwords to OpenCode. - `sys ask` over OpenCode proposed a read-only `history` action and executed it
- Changing the model or connection invalidates any approval whose meaning deterministically.
depends on it; a reconnect must never replay an installation command. - Authentication: no credential → `authentication_required`; wrong →
`authentication_rejected`; correct → `model_catalog` and a successful real
## Developer workflow note inference.
- Transport policy: plain `http` to a LAN/global address →
For work on this repository, the developer OpenCode session may use full tools, `insecure_transport`, exit 1, no request sent.
but only against a checkout and against **sanitized** test evidence. Do not feed - Real-HTTP integration tests cover status preservation, chunked multibyte
it VM disks, serial transcripts with credentials, `*.pw` files, or the bodies, oversized bodies, redirects, abrupt disconnects and authentication.
`PHOEBUS_OPENCODE_*` runtime inputs. - A separate physical computer remains **unverified**; a second server bound to
the LAN address reached through a loopback tunnel is the remote-topology test.
## Verified evidence
- `phoebus-installer --opencode-probe http://127.0.0.1:41999` against the
installed `opencode 1.18.32` returned `ready` (3 providers, 27 models).
- The same probe through a forwarded second loopback endpoint returned `ready`.
- A server deliberately bound to a LAN address **without** authentication
returned `authentication_required` and exit status 1: the probe refuses to
treat an unauthenticated service as usable.
- Physical second-computer verification is **BLOCKED** in this environment (no
second machine / no passwordless SSH); the forwarded-hop test is labelled as a
host-local transport test, not a second computer.

View file

@ -99,7 +99,10 @@ still not VM-verified.
| Bridge replay/concurrency + input bounds | yes | yes | no | n/a | | Bridge replay/concurrency + input bounds | yes | yes | no | n/a |
| Provider transport endpoint/size hardening | yes | yes | no | n/a | | Provider transport endpoint/size hardening | yes | yes | no | n/a |
| `TargetRoot` symlink-escape guard | yes | yes | n/a | n/a | | `TargetRoot` symlink-escape guard | yes | yes | n/a | n/a |
| OpenCode server capability probe | yes | yes | real host probe (`ready`) | n/a | | OpenCode server capability probe | yes | yes | real host probe + auth + policy | n/a |
| OpenCode proposal adapter (real inference) | yes | yes | real model (`deepseek-v4-flash`) | n/a |
| OpenCode in GUI / CLI / `sys ask` | yes | yes | bridge + `sys ask` live | n/a |
| Mandatory AI requires a validated interaction | yes | yes | bridge + CLI | n/a |
| GURU packaging (scoped keywords) | yes | yes | no (build/install unverified) | no | | GURU packaging (scoped keywords) | yes | yes | no (build/install unverified) | no |
| Release gates + atomic publish | yes | yes | no | n/a | | Release gates + atomic publish | yes | yes | no | n/a |
| `sys` verbs | yes | yes | yes | no | | `sys` verbs | yes | yes | yes | no |

View file

@ -4,6 +4,32 @@ Companion to `docs/STATUS.md`. The machine-readable per-run results live outside
git under `/var/tmp/phoebus-vm/<run-id>/results.json`; this file is the git under `/var/tmp/phoebus-vm/<run-id>/results.json`; this file is the
human-readable register of what was found, fixed and still unverified. human-readable register of what was found, fixed and still unverified.
## OpenCode adapter (2026-09-22, second pass)
Implemented a real OpenCode adapter (not just a probe), integrated through
canonical configuration (`ai.backend = "opencode"`), the GUI bridge, the
installer CLI and `sys ask`. Defects found while implementing and testing:
| ID | Defect | Fix | Test |
|----|--------|-----|------|
| O1 | No OpenCode proposal adapter; the GUI used the OpenAI-compatible transport | `phoebus-executor::opencode_client` implements the real session/message protocol as a `ModelTransport` | live + bridge end-to-end |
| O2 | `POST /session` was sent a `model` field per the OpenAPI schema | the shipped 1.18.32 rejects it (BadRequest); the model is selected on the message | real-HTTP integration |
| O3 | The probe had no credential input | `ProbeRequest.auth` + basic-auth header via stdin | auth integration test |
| O4 | The probe did not enforce the connection destination | `Endpoint::checked_target` resolves and requires loopback for plain http; the connection is pinned | `transport_policy_enforces_loopback_for_plain_http`, insecure-destination test |
| O5 | Handwritten HTTP read had no total deadline and a UTF-8-unsafe chunk decoder that fell back on malformed input | removed the handwritten parser; the established curl transport is used and bounds time, protocol, redirects and size | real-HTTP chunked/oversize/redirect/disconnect tests |
| O6 | The catalog was parsed without checking the HTTP status; a providers-shaped 500 could look like a catalog | status is checked before parsing; non-2xx is `incompatible` | `a_misleading_success_shaped_500_does_not_produce_a_catalog` |
| O7 | Catalog presence counted as readiness | `ready` is reserved for a validated response; the probe returns `model_catalog`/`reachable` | `an_empty_catalog_is_reachable_not_ready` |
| O8 | `probe_live_server_when_configured` passed when its env var was absent and only asserted reachability | replaced by env-gated `opencode_live` tests that assert a real inference; `PHOEBUS_OPENCODE_REQUIRE_LIVE=1` fails when the live run cannot happen | `make opencode-acceptance` |
| O9 | The credential test built an already-sanitised struct | tests feed credential-bearing server bodies and assert errors/catalogs never contain them | `one_shot_rejects_a_non_assistant_or_errored_reply`, `catalog_never_reads_provider_keys` |
| O10 | A provider name satisfied the mandatory-AI gate | both the bridge and the CLI require a validated interaction bound to the current configuration; config/secret changes invalidate it | `a_provider_name_alone_does_not_satisfy_the_ai_requirement`, `an_unreachable_provider_does_not_satisfy_the_ai_gate` |
| O11 | The proposal prompt allowed the model to key the change by action name | prompt now requires exactly `action` + `value` with explicit examples | live bridge `ai_check` |
| O12 | The GUI duplicate-session assertion accepted two pre-existing sessions | requires exactly one session before and after | harness |
| O13 | GUI navigation was inferred from a surviving process/screenshot | the frontend emits secret-free `phoebus-state` lines; the harness asserts the current step and AI state | harness |
OpenCode protocol/transport tests: 26 executor unit tests + 7 real-HTTP
integration tests + 2 live tests (skipped offline, real inference when
configured). Bridge gate tests: 5. Full suite: 336 Rust tests.
## Run matrix (this session, 2026-09-22) ## Run matrix (this session, 2026-09-22)
```json ```json

View file

@ -44,10 +44,35 @@ Two facts shape the decision:
product actions still go through the local typed broker and local human product actions still go through the local typed broker and local human
approval. The OpenCode configuration is written mode 0600 and carries no approval. The OpenCode configuration is written mode 0600 and carries no
credentials. credentials.
5. **The installer's AI step keeps using its own bounded transport.** OpenCode 5. **The installer's AI step uses a real OpenCode adapter** (implemented after
is an optional operator workflow, not a replacement for the typed proposal this ADR was first written). `phoebus-executor::opencode_client` speaks the
transport; a future adapter must perform a real prompt round-trip and parse a OpenCode session/message API over the project's curl transport and implements
versioned proposal before it may claim compatibility. 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 ## Consequences
@ -62,5 +87,9 @@ Two facts shape the decision:
## Status ## Status
Accepted. The probe and its tests are implemented; end-to-end installation does Accepted and implemented. The probe, the adapter and the connection states are
not depend on OpenCode. 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.

View file

@ -128,6 +128,9 @@ Singleton {
function aiCheck(cb) { function aiCheck(cb) {
call("ai_check", {}, cb); call("ai_check", {}, cb);
} }
function aiTest(cb) {
call("ai_test", {}, cb);
}
function approve(eraseText, finalConfirmed, cb) { function approve(eraseText, finalConfirmed, cb) {
call("approve", { erase: eraseText, final_confirm: finalConfirmed }, cb); call("approve", { erase: eraseText, final_confirm: finalConfirmed }, cb);
} }

View file

@ -28,11 +28,19 @@ ShellRoot {
property string luksPw: "" property string luksPw: ""
property string luksPw2: "" property string luksPw2: ""
property string apiKey: "" property string apiKey: ""
// OpenCode server password (basic auth), distinct from a provider API key.
property string opencodePassword: ""
property bool aiConnected: false property bool aiConnected: false
property bool aiChecking: false property bool aiChecking: false
property string aiError: "" property string aiError: ""
property var aiApplied: [] property var aiApplied: []
// "Test connection" state: a real, validated model response was obtained.
property bool aiTesting: false
property bool aiTested: false
property string aiTestMessage: ""
readonly property bool isOpenCode: shell.cfg && shell.cfg.ai.backend === "opencode"
property var stageStatus: ({}) property var stageStatus: ({})
property var stageOrder: [] property var stageOrder: []
@ -69,6 +77,21 @@ ShellRoot {
return JSON.parse(JSON.stringify(o)); return JSON.parse(JSON.stringify(o));
} }
// A compact, secret-free state line for the harness. It lets a test assert
// the actual current step and AI connection state instead of inferring them
// from a screenshot or the mere survival of the process.
function logState(tag) {
console.log("phoebus-state " + tag
+ " step=" + shell.step
+ " phase=" + shell.phase
+ " aiConnected=" + shell.aiConnected
+ " aiError=" + shell.aiError.replace(/\n/g, " ").slice(0, 200));
}
onStepChanged: logState("step")
onPhaseChanged: logState("phase")
onAiConnectedChanged: logState("ai")
onAiErrorChanged: logState("error")
// QML `var` properties do not emit change signals for nested assignments, // QML `var` properties do not emit change signals for nested assignments,
// so bindings that read `cfg.*` would not update. Reassigning a clone // so bindings that read `cfg.*` would not update. Reassigning a clone
// re-evaluates them. Used after a choice/toggle changes the configuration. // re-evaluates them. Used after a choice/toggle changes the configuration.
@ -92,6 +115,10 @@ ShellRoot {
modelField.inputItem.text = shell.cfg.ai.model; modelField.inputItem.text = shell.cfg.ai.model;
endpointField.inputItem.text = shell.cfg.ai.endpoint; endpointField.inputItem.text = shell.cfg.ai.endpoint;
keyField.inputItem.text = shell.apiKey; keyField.inputItem.text = shell.apiKey;
opencodeServerField.inputItem.text = shell.cfg.ai.opencode_server;
opencodeProviderField.inputItem.text = shell.cfg.ai.opencode_provider;
opencodeModelField.inputItem.text = shell.cfg.ai.opencode_model;
opencodePasswordField.inputItem.text = shell.opencodePassword;
pwField.inputItem.text = shell.userPw; pwField.inputItem.text = shell.userPw;
pw2Field.inputItem.text = shell.userPw2; pw2Field.inputItem.text = shell.userPw2;
luksField.inputItem.text = shell.luksPw; luksField.inputItem.text = shell.luksPw;
@ -230,7 +257,7 @@ ShellRoot {
shell.status = ""; shell.status = "";
const s = shell.step; const s = shell.step;
if (s === 2) { if (s === 2) {
if (!shell.cfg.ai.provider || shell.cfg.ai.provider === "none") { if (!shell.isOpenCode && (!shell.cfg.ai.provider || shell.cfg.ai.provider === "none")) {
shell.cfg.ai.provider = "deepseek"; shell.cfg.ai.provider = "deepseek";
shell.cfg.ai.enabled = true; shell.cfg.ai.enabled = true;
if (!shell.cfg.ai.model) if (!shell.cfg.ai.model)
@ -278,11 +305,26 @@ ShellRoot {
} }
function configureProvider(value) { function configureProvider(value) {
shell.cfg.ai.provider = value;
shell.cfg.ai.enabled = value !== "none"; shell.cfg.ai.enabled = value !== "none";
shell.aiConnected = false; shell.aiConnected = false;
shell.aiTested = false;
shell.aiTestMessage = "";
shell.aiError = ""; shell.aiError = "";
shell.aiApplied = []; shell.aiApplied = [];
if (value === "opencode") {
// OpenCode is an agent server with its own protocol; it is not an
// OpenAI-compatible endpoint, so it has its own backend and fields.
shell.cfg.ai.backend = "opencode";
shell.cfg.ai.provider = "opencode";
shell.cfg.ai.opencode_server = shell.cfg.ai.opencode_server || "http://127.0.0.1:4096";
shell.cfg.ai.opencode_provider = shell.cfg.ai.opencode_provider || "deepseek";
shell.cfg.ai.opencode_model = shell.cfg.ai.opencode_model || "deepseek-chat";
opencodeServerField.inputItem.text = shell.cfg.ai.opencode_server;
opencodeProviderField.inputItem.text = shell.cfg.ai.opencode_provider;
opencodeModelField.inputItem.text = shell.cfg.ai.opencode_model;
} else {
shell.cfg.ai.backend = "direct";
shell.cfg.ai.provider = value;
if (value === "deepseek") if (value === "deepseek")
shell.cfg.ai.model = "deepseek-chat"; shell.cfg.ai.model = "deepseek-chat";
else if (value === "openai") else if (value === "openai")
@ -291,9 +333,37 @@ ShellRoot {
shell.cfg.ai.model = shell.cfg.ai.model || "llama3.1"; shell.cfg.ai.model = shell.cfg.ai.model || "llama3.1";
modelField.inputItem.text = shell.cfg.ai.model; modelField.inputItem.text = shell.cfg.ai.model;
endpointField.inputItem.text = shell.cfg.ai.endpoint; endpointField.inputItem.text = shell.cfg.ai.endpoint;
}
shell.touchConfig(); shell.touchConfig();
} }
// A lightweight real interaction used by "Test connection": it obtains and
// validates a model response without proposing installation changes.
function testAi() {
shell.aiTesting = true;
shell.aiTested = false;
shell.aiTestMessage = "";
shell.aiError = "";
const secrets = {};
if (shell.opencodePassword.length > 0)
secrets.opencode_password = shell.opencodePassword;
if (shell.apiKey.length > 0)
secrets.ai_api_key = shell.apiKey;
Bridge.setSecrets(secrets, () => {
applyConfig(() => {
Bridge.aiTest(reply => {
shell.aiTesting = false;
if (reply.ok) {
shell.aiTested = true;
shell.aiTestMessage = "Model responded";
} else {
shell.aiTestMessage = reply.error;
}
});
});
});
}
function connectAi() { function connectAi() {
shell.aiChecking = true; shell.aiChecking = true;
shell.aiError = ""; shell.aiError = "";
@ -302,6 +372,8 @@ ShellRoot {
const secrets = {}; const secrets = {};
if (shell.apiKey.length > 0) if (shell.apiKey.length > 0)
secrets.ai_api_key = shell.apiKey; secrets.ai_api_key = shell.apiKey;
if (shell.opencodePassword.length > 0)
secrets.opencode_password = shell.opencodePassword;
Bridge.setSecrets(secrets, () => { Bridge.setSecrets(secrets, () => {
applyConfig(() => { applyConfig(() => {
Bridge.aiCheck(reply => { Bridge.aiCheck(reply => {
@ -709,17 +781,19 @@ ShellRoot {
options: [ options: [
{ value: "deepseek", label: "DeepSeek" }, { value: "deepseek", label: "DeepSeek" },
{ value: "openai", label: "OpenAI" }, { value: "openai", label: "OpenAI" },
{ value: "local", label: "Local model" } { value: "local", label: "Local model" },
{ value: "opencode", label: "OpenCode agent" }
] ]
value: shell.cfg ? shell.cfg.ai.provider : "deepseek" value: shell.isOpenCode ? "opencode" : (shell.cfg ? shell.cfg.ai.provider : "deepseek")
onSelected: value => shell.configureProvider(value) onSelected: value => shell.configureProvider(value)
} }
// -- direct providers ----------------------------------
PhoebusField { PhoebusField {
id: keyField id: keyField
label: "API key" label: "API key"
placeholder: "Paste your provider key" placeholder: "Paste your provider key"
secret: true secret: true
visible: shell.cfg && (shell.cfg.ai.provider === "deepseek" || shell.cfg.ai.provider === "openai") visible: shell.cfg && !shell.isOpenCode && (shell.cfg.ai.provider === "deepseek" || shell.cfg.ai.provider === "openai")
onEdited: value => shell.apiKey = value onEdited: value => shell.apiKey = value
} }
PhoebusField { PhoebusField {
@ -727,6 +801,7 @@ ShellRoot {
label: "Model" label: "Model"
placeholder: "model name" placeholder: "model name"
error: "" error: ""
visible: shell.cfg && !shell.isOpenCode
onEdited: value => shell.cfg.ai.model = value onEdited: value => shell.cfg.ai.model = value
Component.onCompleted: inputItem.text = shell.cfg && shell.cfg.ai.model ? shell.cfg.ai.model : "" Component.onCompleted: inputItem.text = shell.cfg && shell.cfg.ai.model ? shell.cfg.ai.model : ""
} }
@ -734,21 +809,70 @@ ShellRoot {
id: endpointField id: endpointField
label: "Endpoint (local models)" label: "Endpoint (local models)"
placeholder: "http://127.0.0.1:11434/v1/chat/completions" placeholder: "http://127.0.0.1:11434/v1/chat/completions"
visible: shell.cfg && shell.cfg.ai.provider === "local" visible: shell.cfg && !shell.isOpenCode && shell.cfg.ai.provider === "local"
onEdited: value => shell.cfg.ai.endpoint = value onEdited: value => shell.cfg.ai.endpoint = value
Component.onCompleted: inputItem.text = shell.cfg && shell.cfg.ai.endpoint ? shell.cfg.ai.endpoint : "" Component.onCompleted: inputItem.text = shell.cfg && shell.cfg.ai.endpoint ? shell.cfg.ai.endpoint : ""
} }
// -- OpenCode agent server -----------------------------
Text {
width: parent.width
visible: shell.isOpenCode
text: "OpenCode is an agent server, not a model endpoint. Phoebus connects to it over its own protocol. Bind it to loopback and reach a remote server through an authenticated tunnel; plain http to a non-loopback address is refused."
color: Theme.muted
font.family: Theme.family
font.pixelSize: Theme.fontSmall
wrapMode: Text.WordWrap
}
PhoebusField {
id: opencodeServerField
label: "OpenCode server"
placeholder: "http://127.0.0.1:4096"
visible: shell.isOpenCode
onEdited: value => shell.cfg.ai.opencode_server = value
}
PhoebusField {
id: opencodePasswordField
label: "Server password (if set)"
placeholder: "OPENCODE_SERVER_PASSWORD"
secret: true
visible: shell.isOpenCode
onEdited: value => shell.opencodePassword = value
}
PhoebusField {
id: opencodeProviderField
label: "Provider"
placeholder: "deepseek"
visible: shell.isOpenCode
onEdited: value => shell.cfg.ai.opencode_provider = value
}
PhoebusField {
id: opencodeModelField
label: "Model"
placeholder: "deepseek-chat"
visible: shell.isOpenCode
onEdited: value => shell.cfg.ai.opencode_model = value
}
Row { Row {
spacing: 12 spacing: 12
PhoebusButton {
label: shell.aiTesting ? "Testing…" : "Test connection"
actionEnabled: !shell.aiTesting && !shell.aiChecking
onClicked: shell.testAi()
}
PhoebusButton { PhoebusButton {
label: shell.aiChecking ? "Checking…" : "Connect and validate" label: shell.aiChecking ? "Checking…" : "Connect and validate"
primary: true primary: true
actionEnabled: !shell.aiChecking actionEnabled: !shell.aiChecking && !shell.aiTesting
onClicked: shell.connectAi() onClicked: shell.connectAi()
} }
PhoebusChip { PhoebusChip {
visible: shell.aiConnected visible: shell.aiConnected
text: "Connected" text: "Validated"
tone: Theme.success
}
PhoebusChip {
visible: shell.aiTested && !shell.aiConnected
text: "Model responded"
tone: Theme.success tone: Theme.success
} }
} }
@ -761,6 +885,15 @@ ShellRoot {
font.pixelSize: Theme.fontSmall font.pixelSize: Theme.fontSmall
wrapMode: Text.WordWrap wrapMode: Text.WordWrap
} }
Text {
width: parent.width
visible: shell.aiTestMessage.length > 0 && shell.aiError.length === 0
text: shell.aiTestMessage
color: shell.aiTested ? Theme.success : Theme.danger
font.family: Theme.family
font.pixelSize: Theme.fontSmall
wrapMode: Text.WordWrap
}
} }
PhoebusCard { PhoebusCard {
width: parent.width width: parent.width

View file

@ -474,8 +474,10 @@ class Driver:
label="duplicate-launch", label="duplicate-launch",
) )
n1, n2 = int(self.last_group(1)), int(self.last_group(2)) n1, n2 = int(self.last_group(1)), int(self.last_group(2))
# Exactly one session before and after: two pre-existing sessions must
# not pass as "no duplicate".
self.results.assert_true( self.results.assert_true(
"duplicate-sessions-prevented", n1 == n2 and n1 >= 1, "exactly-one-installer-session", n1 == 1 and n2 == 1,
f"n1={n1} n2={n2}", f"n1={n1} n2={n2}",
) )
@ -501,8 +503,58 @@ class Driver:
"ai-step-blocks-install", blocked, "ai-step-blocks-install", blocked,
"the AI step allowed advancement without a connected model", "the AI step allowed advancement without a connected model",
) )
# Behavioral evidence from the frontend's own state lines: the wizard is
# still on the AI step (index 2) and has not reported a connection, and
# it shows an inline error. A surviving process or a screenshot would
# not prove any of this.
state = self._frontend_state()
if state is None:
self.results.fail("ai-page-remains", "no frontend state line found")
else:
self.results.assert_true(
"ai-page-remains", state["step"] == 2 and not state["aiConnected"],
f"last state: {state}",
)
self.results.assert_true(
"ai-error-shown", bool(state["aiError"]),
f"the AI step showed no inline error: {state}",
)
self.results.pass_("gui-walk-completed") self.results.pass_("gui-walk-completed")
def _frontend_state(self) -> dict | None:
"""Read the frontend's last secret-free state line.
The pattern is built from a variable so the shell echo of the command
cannot be mistaken for a real state line.
"""
assert self.child is not None
self.child.sendline(
'P=phoebus-; grep -ah "${P}state " '
"/run/user/1000/quickshell/by-id/*/log.qslog 2>/dev/null | tail -1; "
"echo STATE-$(printf END)"
)
try:
self.child.expect("STATE-END", timeout=30)
except (pexpect.TIMEOUT, pexpect.EOF):
return None
step = ai = None
err = ""
for line in (self.child.before or "").splitlines():
if "phoebus-state" not in line:
continue
match = re.search(r"step=(\d+)", line)
if match:
step = int(match.group(1))
match = re.search(r"aiConnected=(true|false)", line)
if match:
ai = match.group(1) == "true"
match = re.search(r"aiError=(.*)$", line)
if match:
err = match.group(1).strip()
if step is None:
return None
return {"step": step, "aiConnected": bool(ai), "aiError": err}
def _installer_alive(self) -> bool: def _installer_alive(self) -> bool:
assert self.child is not None assert self.child is not None
self.child.sendline( self.child.sendline(