From c16014ade81504932eeba0825b555fe5e5b63290 Mon Sep 17 00:00:00 2001 From: Phoebus Date: Tue, 22 Sep 2026 02:36:36 -0700 Subject: [PATCH] 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). --- Makefile | 13 +- docs/CHANGELOG.md | 50 ++++ docs/HANDOFF.md | 42 +-- docs/OPENCODE.md | 239 +++++++++++------- docs/STATUS.md | 5 +- docs/VERIFICATION.md | 26 ++ docs/adr/0011-opencode-connection-boundary.md | 41 ++- installer/live/desktop/common/Bridge.qml | 3 + .../live/desktop/phoebus-install/shell.qml | 165 ++++++++++-- installer/tests/vm/gui-driver.py | 54 +++- 10 files changed, 499 insertions(+), 139 deletions(-) diff --git a/Makefile b/Makefile index 61e8c14..b3a11d2 100644 --- a/Makefile +++ b/Makefile @@ -8,7 +8,7 @@ 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: @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-rust cargo test --workspace\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 check fmt-check + clippy + tests\n' @printf ' make build release Rust installer\n' @@ -44,6 +45,16 @@ test-rust: test-vm: 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: cd installer-rs && cargo fmt --all diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index ed249ad..10266cc 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -7,6 +7,56 @@ Format: Keep a Changelog. Dates are UTC. ## 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 - **OpenCode connection workflow and capability probe.** New ADR 0011 and `docs/OPENCODE.md` separate the four components (client, server, model diff --git a/docs/HANDOFF.md b/docs/HANDOFF.md index 853f900..2b9f673 100644 --- a/docs/HANDOFF.md +++ b/docs/HANDOFF.md @@ -3,27 +3,29 @@ 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. -- **Last updated:** this session (2026-09-22), harness + security + polish. -- **Current focus:** Hardened the VM harness (enforced qcow2/`/dev`/backing-chain - safety, structured PASS/FAIL results, per-run OVMF+QMP, no `os.system`), - fixed confirmed security defects (disk revalidation before partitioning, - bridge replay/concurrency + input bounds, provider transport URL/size - hardening, `TargetRoot` symlink escapes, and the `0 B` disk-size probe bug), - added an OpenCode server capability probe + docs/ADR 0011, and fixed the - welcome focus ring and the untruthful mid-install cancellation. +- **Last updated:** this session (2026-09-22), OpenCode adapter. +- **Current focus:** Implemented a real OpenCode agent-server adapter + (`phoebus-executor::opencode_client`) that speaks the session/message protocol + over curl and implements `ModelTransport`, wired into canonical config + (`ai.backend = "opencode"`), the GUI ("OpenCode agent" + Test connection), + the installer CLI (`--ai-backend opencode`, `--opencode-test`) and `sys ask`. + The mandatory-AI gate now requires a validated interaction with invalidated + 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):** - - `gui-driver.py gui` on the rebuilt ISO: **23/23 PASS**, exit 0. Welcome - autostarts; Return launches the installer (focus fixed); duplicate sessions - prevented; live medium protected; keyboard navigation reaches network + AI; - advancing without a model is refused and starts nothing. - - `make test` green (Rust + 16 harness unit tests); `cargo fmt --check`, - `cargo clippy --workspace --all-targets` (no errors), release + static - builds. - - OpenCode probe: `ready` against `opencode 1.18.32`; `authentication_required` - (exit 1) against an unauthenticated LAN bind. - - ISO: `installer/live/phoebus-installer-amd64.iso` 1.6 GiB, - `sha256 428dbd7547db8690596bf5c3a0d7a6fa8aee4c9f9eca1e926c216712dd050b36`; - static binary `sha256 2f9cd4b36a12e469d2b6187166acaf8b11f7f382cc19f7ad08bb2a809c855591`. + - 336 Rust tests + 16 harness tests green; fmt/clippy clean. + - Real inference through `opencode 1.18.32` with `deepseek-v4-flash`; + `--opencode-test` → `{"phoebus":"ok"}`; the GUI bridge `ai_check` applied 8 + reviewed changes; `sys ask` proposed and ran a read-only action. + - Auth: none → `authentication_required`, wrong → `authentication_rejected`, + correct → `model_catalog` + successful inference. Plain http to a LAN host + → `insecure_transport`, exit 1, no request sent. + - 7 real-HTTP integration tests (status, chunked multibyte, oversize, + redirect, disconnect, auth) and 2 env-gated live tests. +- **Not yet verified this session:** the full graphical install through + OpenCode in a VM, and a separate physical computer. The pinned manifest is + `v1.18.31` while the tested binary is `1.18.32`. - **Public repo:** (remote `origin`, SSH port 2222). diff --git a/docs/OPENCODE.md b/docs/OPENCODE.md index ba9c432..828ecf6 100644 --- a/docs/OPENCODE.md +++ b/docs/OPENCODE.md @@ -1,13 +1,9 @@ # OpenCode connection workflow -OpenCode is used in two clearly separated ways: - -1. **Developer workflow** — on this repository, inspecting sanitized evidence. - Full tool access (shell, files, plugins) is fine because it runs as *you*, - 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. +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. @@ -16,84 +12,147 @@ Read [ADR 0011](adr/0011-opencode-connection-boundary.md) first. | Component | What it is | Where it runs | |-----------|------------|---------------| | OpenCode client | `opencode` TUI/CLI, or `opencode attach ` | 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 | -| Model inference service | DeepSeek/OpenAI, or a local OpenAI-compatible server (Ollama, llama.cpp, ...) | provider cloud or your LAN | +| 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 Phoebus's local-model endpoint field.** -An OpenCode server is an agent application; it is not an OpenAI-compatible -`/v1/chat/completions` endpoint. Pointing Phoebus's `local` provider at it will -fail, and would be the wrong trust boundary even if it parsed. +**An OpenCode server URL does not go in the direct-provider endpoint field.** +Select the OpenCode backend instead; Phoebus speaks the agent protocol. -## Capability probe (never assume compatibility) +## Configuration -```sh -phoebus-installer --opencode-probe http://127.0.0.1:4096 +```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. ``` -It is read-only and prints a typed state, exiting nonzero unless a model is -available: +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 | |-------|---------| -| `disconnected` | TCP connect failed; the service is down | -| `authentication_required` | the server answered 401/403; supply the password/tunnel | -| `incompatible` | a health response arrived but the API shape is not the expected one | -| `reachable_no_model` | healthy server, no model configured | -| `ready` | reachable, healthy, API-compatible, and ≥1 model configured | +| `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) | -`ready` still does **not** prove the model can emit a valid Phoebus proposal; -that requires a real prompt round-trip and proposal parse. A health check or an -HTTP 200 is not that proof. +A model catalog is not readiness. The probe never returns `ready`; only a real +inference that validates the response does. -The probe reads `/global/health` and `/config/providers`, keeps only counts from -the latter, and never returns the provider credentials that upstream includes in -that response. +## 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 -# 1. Set a provider credential through the environment (never a file in git). 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 - -# 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 +opencode attach http://127.0.0.1:4096 # interactive client phoebus-installer --opencode-probe http://127.0.0.1:4096 ``` -The probe now sees a loopback endpoint and the tunnel supplies transport -authentication and encryption. If you cannot use a tunnel, set -`OPENCODE_SERVER_PASSWORD` and terminate TLS in front of the server; never -expose an unauthenticated plaintext service. +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 -Inside a VM these are different endpoints and must not be confused: - | Endpoint | Meaning | |----------|---------| | `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 | | `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. -- Disable tools you do not need. OpenCode permission settings are *not* an - operating-system security boundary; enforce isolation outside the prompt. -- Keep the destructive execution path in Phoebus's local broker with local human - approval. The agent is never given a shell, root, credentials or private-file - access. -- Keep credentials in protected runtime storage (0600, outside model context). - Never forward disk passphrases or account passwords to OpenCode. -- Changing the model or connection invalidates any approval whose meaning - depends on it; a reconnect must never replay an installation command. - -## Developer workflow note - -For work on this repository, the developer OpenCode session may use full tools, -but only against a checkout and against **sanitized** test evidence. Do not feed -it VM disks, serial transcripts with credentials, `*.pw` files, or the -`PHOEBUS_OPENCODE_*` runtime inputs. - -## 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. +- `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. diff --git a/docs/STATUS.md b/docs/STATUS.md index 05b417c..565f21e 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -99,7 +99,10 @@ still not VM-verified. | Bridge replay/concurrency + input bounds | 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 | -| 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 | | Release gates + atomic publish | yes | yes | no | n/a | | `sys` verbs | yes | yes | yes | no | diff --git a/docs/VERIFICATION.md b/docs/VERIFICATION.md index c20a51f..9b43528 100644 --- a/docs/VERIFICATION.md +++ b/docs/VERIFICATION.md @@ -4,6 +4,32 @@ Companion to `docs/STATUS.md`. The machine-readable per-run results live outside git under `/var/tmp/phoebus-vm//results.json`; this file is the 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) ```json diff --git a/docs/adr/0011-opencode-connection-boundary.md b/docs/adr/0011-opencode-connection-boundary.md index 7f7f4e9..256f73c 100644 --- a/docs/adr/0011-opencode-connection-boundary.md +++ b/docs/adr/0011-opencode-connection-boundary.md @@ -44,10 +44,35 @@ Two facts shape the decision: 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. +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 @@ -62,5 +87,9 @@ Two facts shape the decision: ## Status -Accepted. The probe and its tests are implemented; end-to-end installation does -not depend on OpenCode. +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. diff --git a/installer/live/desktop/common/Bridge.qml b/installer/live/desktop/common/Bridge.qml index 288ec76..c97d91b 100644 --- a/installer/live/desktop/common/Bridge.qml +++ b/installer/live/desktop/common/Bridge.qml @@ -128,6 +128,9 @@ Singleton { function aiCheck(cb) { call("ai_check", {}, cb); } + function aiTest(cb) { + call("ai_test", {}, cb); + } function approve(eraseText, finalConfirmed, cb) { call("approve", { erase: eraseText, final_confirm: finalConfirmed }, cb); } diff --git a/installer/live/desktop/phoebus-install/shell.qml b/installer/live/desktop/phoebus-install/shell.qml index 07e5426..de3a0e0 100644 --- a/installer/live/desktop/phoebus-install/shell.qml +++ b/installer/live/desktop/phoebus-install/shell.qml @@ -28,11 +28,19 @@ ShellRoot { property string luksPw: "" property string luksPw2: "" property string apiKey: "" + // OpenCode server password (basic auth), distinct from a provider API key. + property string opencodePassword: "" property bool aiConnected: false property bool aiChecking: false property string aiError: "" 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 stageOrder: [] @@ -69,6 +77,21 @@ ShellRoot { 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, // so bindings that read `cfg.*` would not update. Reassigning a clone // re-evaluates them. Used after a choice/toggle changes the configuration. @@ -92,6 +115,10 @@ ShellRoot { modelField.inputItem.text = shell.cfg.ai.model; endpointField.inputItem.text = shell.cfg.ai.endpoint; 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; pw2Field.inputItem.text = shell.userPw2; luksField.inputItem.text = shell.luksPw; @@ -230,7 +257,7 @@ ShellRoot { shell.status = ""; const s = shell.step; 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.enabled = true; if (!shell.cfg.ai.model) @@ -278,22 +305,65 @@ ShellRoot { } function configureProvider(value) { - shell.cfg.ai.provider = value; shell.cfg.ai.enabled = value !== "none"; shell.aiConnected = false; + shell.aiTested = false; + shell.aiTestMessage = ""; shell.aiError = ""; shell.aiApplied = []; - if (value === "deepseek") - shell.cfg.ai.model = "deepseek-chat"; - else if (value === "openai") - shell.cfg.ai.model = "gpt-4o-mini"; - else if (value === "local") - shell.cfg.ai.model = shell.cfg.ai.model || "llama3.1"; - modelField.inputItem.text = shell.cfg.ai.model; - endpointField.inputItem.text = shell.cfg.ai.endpoint; + 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") + shell.cfg.ai.model = "deepseek-chat"; + else if (value === "openai") + shell.cfg.ai.model = "gpt-4o-mini"; + else if (value === "local") + shell.cfg.ai.model = shell.cfg.ai.model || "llama3.1"; + modelField.inputItem.text = shell.cfg.ai.model; + endpointField.inputItem.text = shell.cfg.ai.endpoint; + } 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() { shell.aiChecking = true; shell.aiError = ""; @@ -302,6 +372,8 @@ ShellRoot { const secrets = {}; if (shell.apiKey.length > 0) secrets.ai_api_key = shell.apiKey; + if (shell.opencodePassword.length > 0) + secrets.opencode_password = shell.opencodePassword; Bridge.setSecrets(secrets, () => { applyConfig(() => { Bridge.aiCheck(reply => { @@ -709,17 +781,19 @@ ShellRoot { options: [ { value: "deepseek", label: "DeepSeek" }, { 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) } + // -- direct providers ---------------------------------- PhoebusField { id: keyField label: "API key" placeholder: "Paste your provider key" 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 } PhoebusField { @@ -727,6 +801,7 @@ ShellRoot { label: "Model" placeholder: "model name" error: "" + visible: shell.cfg && !shell.isOpenCode onEdited: value => shell.cfg.ai.model = value Component.onCompleted: inputItem.text = shell.cfg && shell.cfg.ai.model ? shell.cfg.ai.model : "" } @@ -734,21 +809,70 @@ ShellRoot { id: endpointField label: "Endpoint (local models)" 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 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 { spacing: 12 + PhoebusButton { + label: shell.aiTesting ? "Testing…" : "Test connection" + actionEnabled: !shell.aiTesting && !shell.aiChecking + onClicked: shell.testAi() + } PhoebusButton { label: shell.aiChecking ? "Checking…" : "Connect and validate" primary: true - actionEnabled: !shell.aiChecking + actionEnabled: !shell.aiChecking && !shell.aiTesting onClicked: shell.connectAi() } PhoebusChip { visible: shell.aiConnected - text: "Connected" + text: "Validated" + tone: Theme.success + } + PhoebusChip { + visible: shell.aiTested && !shell.aiConnected + text: "Model responded" tone: Theme.success } } @@ -761,6 +885,15 @@ ShellRoot { font.pixelSize: Theme.fontSmall 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 { width: parent.width diff --git a/installer/tests/vm/gui-driver.py b/installer/tests/vm/gui-driver.py index 0fb478f..4ba6e9a 100644 --- a/installer/tests/vm/gui-driver.py +++ b/installer/tests/vm/gui-driver.py @@ -474,8 +474,10 @@ class Driver: label="duplicate-launch", ) 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( - "duplicate-sessions-prevented", n1 == n2 and n1 >= 1, + "exactly-one-installer-session", n1 == 1 and n2 == 1, f"n1={n1} n2={n2}", ) @@ -501,8 +503,58 @@ class Driver: "ai-step-blocks-install", blocked, "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") + 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: assert self.child is not None self.child.sendline(