From f9e39925b49ef52e4b370439de59b5ebd28103c5 Mon Sep 17 00:00:00 2001 From: Phoebus Date: Wed, 23 Sep 2026 20:30:13 -0700 Subject: [PATCH] feat(install): AI-first sys install workflow Implement the shared installation workflow (ADR 0013). sys install, sys ask install and the explicit backend flags all use one path: identify -> evidence -> AI investigation -> deterministic validation/effects -> review -> approval -> execute -> verify -> history. - phoebus-ai::install: bounded, multi-turn investigation. The model may request typed read-only evidence (discover_candidates, inspect_candidate, check_backend, inspect_installation), ask one bounded question about intent, and must return a structured InstallProposal. Turn/request/size limits and repeated-request detection bound it; a rejected proposal is revised. - phoebus-core: add the four read-only investigation actions and strict validators; add a transaction id; backend/kind wire names now match as_str. - phoebus-executor::install: resolve_explicit (no model, no fallback), resolve_deterministic and resolve_with_ai; validate_proposal re-resolves the candidate against real metadata, rejects fabrication/ambiguity/staleness/ duplicates, maps it to the existing broker action, and binds approval to a digest; revalidate + verify_installed. chooser gains per-lane friendly-name resolution and structured evidence. - transaction::begin/finish record an in-progress transaction before mutation. - sys: --portage/--flatpak/--nix/--snap/--appimage/--ebuild (mutually exclusive) bypass the model; an unqualified install consults the model and, with none, prints the deterministic selection and installs nothing. - The installer persists /etc/phoebus/install.toml; sys loads it and adds free space, Wayland, usable lanes, saved preferences and recovery capability to the bounded facts. - Docs: ADR 0013, docs/SYS.md install sections and cases 23-31, CHANGELOG, STATUS, HANDOFF, ROADMAP. New live-VM workflow check script. Host gates pass: fmt, clippy (no new warnings), workspace tests, make test. VM: verified the workflow CLI and read-only investigation on the reference LiveGUI ISO; a full target install journey is running (see HANDOFF). --- docs/CHANGELOG.md | 46 + docs/HANDOFF.md | 147 ++- docs/ROADMAP.md | 1 + docs/STATUS.md | 7 + docs/SYS.md | 75 +- docs/adr/0013-ai-first-installation.md | 143 +++ docs/adr/README.md | 1 + installer-rs/crates/phoebus-ai/src/install.rs | 712 +++++++++++ installer-rs/crates/phoebus-ai/src/lib.rs | 1 + .../crates/phoebus-ai/src/provider.rs | 26 + .../crates/phoebus-core/src/action.rs | 102 ++ .../crates/phoebus-core/src/selection.rs | 15 +- .../crates/phoebus-core/src/transaction.rs | 6 + .../crates/phoebus-executor/src/actions.rs | 36 + .../crates/phoebus-executor/src/chooser.rs | 499 ++++++++ .../crates/phoebus-executor/src/install.rs | 1102 +++++++++++++++++ .../crates/phoebus-executor/src/lib.rs | 1 + .../phoebus-executor/src/transaction.rs | 139 ++- .../crates/phoebus-installer/src/bin/sys.rs | 428 ++++++- .../phoebus-installer/src/orchestrate.rs | 10 + .../crates/phoebus-installer/tests/sys_cli.rs | 104 ++ installer/tests/vm/live-sys-install-check.sh | 70 ++ installer/tests/vm/sys-acceptance.sh | 35 + 23 files changed, 3616 insertions(+), 90 deletions(-) create mode 100644 docs/adr/0013-ai-first-installation.md create mode 100644 installer-rs/crates/phoebus-ai/src/install.rs create mode 100644 installer-rs/crates/phoebus-executor/src/install.rs create mode 100644 installer/tests/vm/live-sys-install-check.sh diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 39b5a86..983c288 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -3,6 +3,52 @@ All notable changes are recorded here. The authoritative history is `git log`; this file is the curated, human-readable summary. +## 2026-09-24 — AI-first package installation + +- **Shared installation workflow (`phoebus-executor::install`, ADR 0013):** + `sys install `, `sys ask install ` and the explicit + backend flags all run one flow: identify → evidence → AI investigation → + deterministic validation + effects → review → approval → execute → verify → + history. The AI only recommends; the resolver re-checks every proposal + against real backend metadata and maps it to the existing broker action. +- **Bounded investigation (`phoebus-ai::install`):** the model may request + typed, read-only evidence (`discover_candidates`, `inspect_candidate`, + `check_backend`, `inspect_installation`) and ask one bounded question about + intent before proposing a structured `InstallProposal`. Bounds: turn, + per-turn request and evidence-size limits plus repeated-request detection. A + rejected proposal is fed back for a bounded revision. +- **Friendly-name resolution and validation:** per-lane resolution + (`chooser::resolve_for_backend`) maps friendly names to real identifiers, + reports ambiguity, and never fabricates a candidate. Duplicate installs, + stale versions and changed effects are refused; approval is bound to a digest + and revalidated before execution. +- **Explicit backend flags are authoritative:** `--portage`, `--flatpak`, + `--nix`, `--snap`, `--appimage`, `--ebuild` bypass the model, are mutually + exclusive, and never fall back to another lane. +- **No-model path:** an unqualified install with no provider prints the + deterministic selection and the explicit commands and installs nothing; + provider failure is never permission to install. +- **Install facts are real:** `sys` now loads the installed + `/etc/phoebus/install.toml` instead of assuming defaults, and the bounded + facts include free space, Wayland, the usable lanes, saved preferences and + recovery capability. +- **Transaction engine:** installs record an in-progress transaction before the + mutation (`transaction::begin`/`finish`), verify installed identity/version + afterwards, and record failures truthfully. +- **ADRs/docs:** new `docs/adr/0013-ai-first-installation.md`; `docs/SYS.md` + updated with the install workflow and acceptance cases 23–31. + +### Verified (host) +- `cargo fmt`, `cargo clippy --workspace --all-targets` (no new warnings) and + `cargo test --workspace` pass. New tests cover: the AI loop (steps, bounds, + repetition, revision, provider failure), resolver fabrication/ambiguity/ + duplicate/changed-evidence, action mapping, transaction begin/finish, CLI + flag conflicts/no-fallback/no-model, and target-vs-host facts. + +### Not yet verified +- Real VM installation journeys through `sys install` (AI-selected and + explicit-backend) are the next gate; see `docs/HANDOFF.md`. + ## 2026-09-24 — Hardware-aware software selection, Snap/AppImage/custom ebuild, `sys` lifecycle - **Shared selection policy (`phoebus-core::selection`, ADR 0006 revised):** diff --git a/docs/HANDOFF.md b/docs/HANDOFF.md index 08208e1..866cff0 100644 --- a/docs/HANDOFF.md +++ b/docs/HANDOFF.md @@ -3,105 +3,96 @@ 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-24), hardware-aware software - selection across all lanes, Snap/AppImage/custom-ebuild backends, and the - installed-`sys` lifecycle. +- **Last updated:** this session (2026-09-24), AI-first package installation: + the shared `sys install` workflow, bounded AI investigation, deterministic + proposal validation, explicit backend flags and truthful install transactions. - **Current focus:** - 1. **Shared selection policy** (`phoebus-core::selection`, ADR 0006 revised): - fixed category routing is gone. A deterministic, inspectable policy - resolves real candidates from Portage (source/binary/vendor), Nix, Flatpak, - Snap, AppImage and the Phoebus overlay; separates hard constraints from - preferences; keeps base components under Portage; honours and persists - explicit choices; errors instead of silently switching lanes; reuses an - already-installed lane. - 2. **New backends** (`phoebus-executor`): `snap` (daemon/confinement - detection, install/list/remove/refresh/connections, `app-containers/snapd` - through Portage), `appimage` (pinned-hash acquire/import, ELF arch check - without execution, desktop integration, data-preserving removal), `ebuild` - (Phoebus overlay, rationale + content digest, approval-gated build with - Portage's sandbox). - 3. **`sys` surface**: `choose_package`, `set_package_preference`, `snap_*`, - `appimage_*`, `custom_ebuild_*` typed actions with strict validators and - deterministic phrases; `docs/SYS.md` is the command reference and - acceptance matrix. - 4. **`sys` in the installed target**: located beside the installer, copied to - `/usr/local/bin/sys`, proven to run in the target chroot before the - recovery snapshot; install fails closed if absent. - 5. **VM harness**: `install.sh` fetches `sys`; `rollback-guest.sh` uses the - installed binary; new `installer/tests/vm/sys-acceptance.sh`. + 1. **Shared install workflow** (`phoebus-executor::install`, ADR 0013): + identify → evidence → AI investigation → deterministic validation/effects + → review → approval → execute → verify → history. Used by + `sys install`, `sys ask install ...` and the explicit backend flags. + 2. **Bounded investigation** (`phoebus-ai::install`): the model may request + typed read-only evidence (`discover_candidates`, `inspect_candidate`, + `check_backend`, `inspect_installation`) and ask one bounded question + before proposing; turn/request/size limits and repeated-request detection + bound it. A rejected proposal is revised with the resolver's finding. + 3. **Deterministic authority**: `validate_proposal` re-resolves the candidate + against real metadata (fabrication, staleness, ambiguity and duplicates + are refused), maps it to the existing broker action, and binds approval to + a digest that is revalidated before execution. + 4. **Explicit flags**: `--portage/--flatpak/--nix/--snap/--appimage/--ebuild` + bypass the model, are mutually exclusive and never fall back. + 5. **No-model path**: an unqualified install with no provider prints the + deterministic selection and explicit commands and installs nothing. + 6. **Transactions**: `transaction::begin`/`finish` record an in-progress + transaction before the mutation; installs verify identity/version after. + 7. **Real install facts**: `/etc/phoebus/install.toml` is now written by the + installer and read by `sys`; facts add free space, Wayland, usable lanes, + saved preferences and recovery capability. - **Last verified (this session):** - `cargo fmt --all -- --check`, `cargo clippy --workspace --all-targets` - (no new warnings) and `cargo test --workspace` pass. New coverage: the - selection policy (16 tests across hardware/preference/failure cases), Snap - and AppImage parsing/behaviour, the ebuild digest/approval path, chooser - resolution, and `sys_cli` host tests. - - `installer/tests/vm/test_vmsafety.py` (18 tests) passes with the new guest - script. -- **Not yet verified this session:** the new lanes and the installed-`sys` - lifecycle are unit/integration tested but **not exercised in a booted VM**: a - full `gui-install` (started by a prior session) was still running on the only - disposable disk. The NVIDIA boot gates and the rollback destructive gate remain - unrun. + (no new warnings) and `cargo test --workspace` pass. + - New tests: AI loop steps/bounds/repetition/revision/provider-failure; + resolver fabrication/ambiguity/duplicate/changed-version; action mapping; + transaction begin/finish (ok and failed); `sys_cli` flag conflicts, + no-fallback, no-model offer, help; target-vs-host facts. + - `installer/tests/vm/test_vmsafety.py` (18 tests) passes with the extended + `sys-acceptance.sh`. +- **Not yet verified this session:** a real VM installation journey through + `sys install` (AI-selected and explicit-backend). The `sys` acceptance matrix + now includes the read-only install-workflow cases (23–31). No live model call + was made. - **Public repo:** (remote `origin`, SSH port 2222). ## Next actions (in order) -1. **Boot the installed disk and run the `sys` acceptance matrix** once the - current `gui-install` VM releases the disk: +1. **VM install journey**: clone the installed disposable disk, boot it + detached, and run: ```sh - cp installer-rs/target/x86_64-unknown-linux-gnu/release/phoebus-installer \ - installer-rs/target/x86_64-unknown-linux-gnu/release/sys /home/dominic/vmlab/serve/ - cp installer/tests/vm/{install.sh,sys-acceptance.sh,rollback-guest.sh,rollback-verify.sh} /home/dominic/vmlab/serve/ - # in the serve dir: python3 -m http.server 8000 --bind 127.0.0.1 + # serve the freshly built static binaries (make static) plus the guest scripts DISK=/var/tmp/phoebus-vm/disks/.qcow2 OVMF_CODE=... OVMF_VARS=... \ - BOOT_CHECKS='test -x /usr/local/bin/sys && /usr/local/bin/sys --version; sudo /usr/local/bin/sys history; \ - curl -fsSL http://10.0.2.2:8000/sys-acceptance.sh -o /tmp/sa.sh && SYS_ACCEPTANCE_MUTATE=1 bash /tmp/sa.sh; \ + BOOT_CHECKS='test -x /usr/local/bin/sys && /usr/local/bin/sys --version; \ + sudo /usr/local/bin/sys install app-misc/hello --portage; \ + sudo /usr/local/bin/sys history; \ + curl -fsSL http://10.0.2.2:8000/sys-acceptance.sh -o /tmp/sa.sh && bash /tmp/sa.sh; \ echo ===CHECKS-$(printf END)===' \ python3 installer/tests/vm/serial-driver.py boot ``` - Confirm `/usr/local/bin/sys` exists (installed lifecycle), the matrix reports - `FAIL=0`, and a Portage install/remove appears in `sys history`. -2. **Snap / AppImage / custom-ebuild VM journeys**: on a disposable installed - VM, `sys snap install `, `sys appimage import` a small test image, - and one `custom_ebuild_prepare` + `custom_ebuild_install`. Needs network for - Snap/AppImage; the custom-ebuild path can use a local file. -3. **Rollback VM acceptance**: clone the installed disk and run - `serial-driver.py rollback`. The destructive gate is written and unit-checked - but unrun. -4. **NVIDIA hardware acceptance (BLOCKED)**: needs an NVIDIA GPU; unchanged. -5. **Live AI provider call**: exercise `sys ask` with a real 0600 key file; the - path is fixture-verified only. -6. **Installed Mango desktop** and the **live ISO `gui` journey** remain to be - re-run on this checkout. + Confirm an explicit-backend install succeeds, appears in `sys history`, and + the matrix reports `FAIL=0`. +2. **AI-selected install journey**: with a configured provider (existing + authorization, 0600 key file), run `sudo sys install ` in the VM and + confirm the model investigates, the resolver confirms the candidate, and the + plan is presented before approval. Use `PHOEBUS_AI_PROVIDER=` (empty) to + exercise the no-model offer in the same run. +3. **Rollback VM acceptance** (`serial-driver.py rollback`) remains unrun. +4. **NVIDIA hardware acceptance (BLOCKED)**: needs an NVIDIA GPU. +5. **Installed Mango desktop** and the **live ISO `gui` journey** remain to be + re-run. ## Known blockers / risks -- **One disposable disk, shared with a long `gui-install`.** Do not start a - second VM against the same qcow2; clone it first. `make doctor` reports - ~29 GiB free now (the earlier ~12 GiB disk blocker has eased). -- **No NVIDIA GPU** (and no authorised passthrough): acceleration cannot be - verified here. -- **Snap needs network and AppArmor** for meaningful confinement. The lane - detects confinement honestly; a host without AppArmor reports `none`. -- **AppImage provides no sandbox.** Do not describe it as one; runtime - requirements (FUSE) are not auto-installed. -- **The custom-ebuild build is Portage sandboxed, not VM-isolated.** Treat a - generated ebuild as untrusted and keep the digest-bound approval. -- **`gui-install` completion is host-time bound** (base stage ~116 min, kernel - compile beyond the 4 h timeout). The deterministic install + detached boot is - the proven path. +- **A full VM install still takes hours** (base stage ~116 min). Use the already + installed disposable disk (clone it) for `sys install` journeys rather than a + fresh install. +- **No NVIDIA GPU** (and no authorised passthrough). +- **Snap needs network and AppArmor** for meaningful confinement; the lane + detects confinement honestly. +- **AppImage provides no sandbox**; do not describe it as one. +- **Custom ebuilds remain separately reviewed, untrusted artifacts**; the + install workflow never builds one during investigation. +- **OpenCode transport** concatenates messages, so multi-turn investigation is + best-effort there; the direct providers carry the full conversation. - Harness artifacts live under `/var/tmp/phoebus-vm/` (outside git). ## Environment notes - Dev host: Ubuntu 26.04. QEMU/OVMF/xorriso/rustfmt/clippy/ImageMagick/visudo - present. `flatpak` and `snap` clients are installed on the host (not usable as - proof of the VM lanes). -- Debian-Live base ISO is cached at `/home/dominic/debian-live-standard.iso`. -- VM harnesses: `installer/tests/vm/gui-driver.py`, `serial-driver.py`, - `appliance-driver.py`, `live-driver.py`, and `sys-acceptance.sh`. - `DISK` must be a disposable qcow2; never point it at `/dev/*`. + present. `flatpak` and `snap` clients are present on the host (not proof of + the VM lanes). +- VM harnesses: `installer/tests/vm/{gui-driver,serial-driver,appliance-driver,live-driver}.py` + and `sys-acceptance.sh`. `DISK` must be a disposable qcow2; never `/dev/*`. - Serve fixtures from `/home/dominic/vmlab/serve` with `python3 -m http.server 8000 --bind 127.0.0.1` (reachable as `10.0.2.2:8000`). - The static binaries for the VM: `make static` builds `phoebus-installer` and diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 00564b3..feca7f0 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -25,6 +25,7 @@ more interesting. Status vocabulary: **Done**, **Partial**, **Next**, **Later**. | — | AI-guided install optimization | Partial | DeepSeek/OpenAI/local providers, evidence-gated typed review, mandatory at install with `--no-ai` break-glass; fixture-verified, no live call | | — | Nix as a built-in second lane | Partial | pinned-release bootstrap; `nix-daemon` active and `nix shell nixpkgs#hello` VM-verified; on by default | | — | Hardware-aware software selection (all lanes) | Partial | shared policy + candidate resolution + `choose_package`/`set_package_preference` (unit-tested); Snap, AppImage and custom-ebuild backends implemented (unit-tested); VM journeys pending (ADR 0006 revised) | +| — | AI-first package installation | Partial | shared `sys install` workflow with bounded AI investigation, deterministic validation, explicit backend flags and no-model offer (unit/integration-tested); VM install journeys pending (ADR 0013) | | — | Git workflow + agent guide | Done | this `docs/` set, `.githooks/`, `scripts/` | ## Immediate next steps diff --git a/docs/STATUS.md b/docs/STATUS.md index 0047a07..94dda5c 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -92,6 +92,13 @@ still not VM-verified. | AppImage lane (import/acquire/integrity/desktop/remove) | yes | yes | no | no | | Custom ebuild overlay (stage/approve/build/remove) | yes | yes | no | no | | `sys` installed into the target + verified in chroot | yes | yes (unit) | no | no | +| AI-first install workflow (`sys install`, `sys ask`) | yes | yes | no | no | +| Bounded AI investigation (typed read-only evidence) | yes | yes | no | no | +| Deterministic proposal validation (fabrication/stale/ambiguous/duplicate) | yes | yes | no | no | +| Explicit backend install flags (no fallback) | yes | yes | no | no | +| No-model unqualified install refuses and offers commands | yes | yes | no | no | +| Install transaction begin/finish + verification | yes | yes | no | no | +| Installed config loaded (`/etc/phoebus/install.toml`) | yes | no | no | no | | `sys` consistent target-root execution | yes | yes | no | no | | `sys` validation at the execution boundary | yes | yes | no | n/a | | `sys ask` truthful failure (nonzero, stop, record) | yes | yes | no | n/a | diff --git a/docs/SYS.md b/docs/SYS.md index 6dfcd2f..bc4f8f8 100644 --- a/docs/SYS.md +++ b/docs/SYS.md @@ -16,6 +16,63 @@ sys ask "" # assistant proposes the same typed actions Run `sys --help` for the flags. Mutating actions require root (`sudo sys ...`). Without a model, `sys ask` prints the deterministic equivalent and exits. +## AI-first installation (`sys install`) + +``` +sys install firefox # AI investigates and recommends +sys install firefox --flatpak # deterministic, no model +sys install firefox --portage +sys install nodejs --nix +sys install thunderbird --snap +sys install MyTool --appimage +sys install app-misc/my-thing --ebuild # build a staged custom ebuild +sys ask install firefox # the same workflow via the assistant +``` + +One shared workflow (ADR 0013) is used by all of these: + +``` +identify -> evidence -> AI investigation -> proposed selection +-> deterministic validation + effects -> review -> approve -> execute +-> verify -> history +``` + +- **Unqualified** installation consults the connected model. The model may + request bounded, read-only evidence (`discover_candidates`, + `inspect_candidate`, `check_backend`, `inspect_installation`) and may ask one + bounded question about your intent. It returns a structured proposal naming a + real candidate id; the deterministic resolver independently confirms that + candidate against backend metadata, computes the effects, and binds approval + to a digest. A fabricated, stale, ambiguous or duplicating proposal is + rejected and returned to the model for a bounded revision. +- **Explicit backend flags** (`--portage`, `--flatpak`, `--nix`, `--snap`, + `--appimage`, `--ebuild`) bypass the model, are mutually exclusive, and never + fall back to another lane. If the lane cannot satisfy the request, the reason + and alternatives are shown and nothing is installed. +- **No model** for an unqualified install: the deterministic candidate + selection and the explicit commands are printed, and nothing is installed. A + provider failure is never permission to install through a lane. +- Every install is recorded in the transaction log **before** it runs (an + interrupted run leaves an in-progress record) and verified afterwards + (package database, `flatpak list`, `snap list`, or the managed AppImage + record). A verification failure is a failed transaction. + +Read-only investigation is also directly available: + +| Phrase / JSON | Typed action | Kind | +| --- | --- | --- | +| *(JSON only)* | `discover_candidates` | read | +| *(JSON only)* | `inspect_candidate` | read | +| *(JSON only)* | `check_backend` | read | +| *(JSON only)* | `inspect_installation` | read | + +Example: + +```sh +sys --action '{"action":"discover_candidates","query":"firefox","gui":true}' +sys --action '{"action":"check_backend","backend":"snap"}' +``` + ## Commands and typed actions ### Services (Portage/systemd ownership) @@ -160,12 +217,22 @@ with no network and no model. | 20 | Approval rejected | answer `n` at the prompt | no mutation, nonzero | | 21 | Plan changed between review and exec | concurrent metadata change | aborts, nonzero | | 22 | Offline `sys ask` | `sys ask ""` with no provider | deterministic fallback, nonzero | +| 23 | Unqualified install consults the model | `sys install firefox` with a provider | model investigated; resolver confirmed | +| 24 | Explicit backend, no model | `sys install firefox --flatpak` with no provider | deterministic, no model consulted | +| 25 | Conflicting backend flags | `sys install x --flatpak --nix` | rejected by the CLI | +| 26 | Explicit lane cannot satisfy | `sys install x --portage` without Portage | explained, no fallback, nonzero | +| 27 | Unqualified with no model | `sys install firefox` and no provider | deterministic offer printed, nothing installed | +| 28 | Ambiguous friendly name | a name matching several candidates | clarification required, nonzero | +| 29 | Fabricated candidate | model proposes a non-existent id | rejected, revised, no install | +| 30 | Changed candidate version | metadata changes after review | approval invalidated, nonzero | +| 31 | Failed install history | a failing backend command | transaction recorded as failed | -Cases 1–14 and 21–22 are covered by host tests +Cases 1–14 and 21–31 are covered by host tests (`crates/phoebus-core/src/selection.rs`, `.../action.rs`, -`crates/phoebus-executor/src/{snap,appimage,ebuild,chooser}.rs`, and -`crates/phoebus-installer/tests/sys_cli.rs`). Cases 15–20 and the in-VM subset -of 1–14 are exercised by the VM acceptance script; their current verification +`crates/phoebus-ai/src/install.rs`, +`crates/phoebus-executor/src/{install,snap,appimage,ebuild,chooser,transaction}.rs`, +and `crates/phoebus-installer/tests/sys_cli.rs`). Cases 15–20 and the in-VM +subset are exercised by the VM acceptance script; their current verification status is recorded in `docs/STATUS.md`. ## Security properties diff --git a/docs/adr/0013-ai-first-installation.md b/docs/adr/0013-ai-first-installation.md new file mode 100644 index 0000000..179c41c --- /dev/null +++ b/docs/adr/0013-ai-first-installation.md @@ -0,0 +1,143 @@ +# ADR 0013: AI-first package installation workflow + +- **Status:** Accepted +- **Date:** 2026-09-24 + +## Context + +ADR 0006 made software selection a shared, hardware- and preference-aware +policy rather than fixed category routing. The remaining gap was the *entry +point*: `sys install ` was a thin Portage wrapper and ignored the +connected model, while Flatpak/Nix/Snap/AppImage each had their own command. +A user had to know the right lane in advance. + +This ADR defines the installation workflow itself. It supersedes any remaining +fixed category-to-backend routing: the model makes the contextual +recommendation, and the deterministic system validates and executes it. + +## Decision + +`sys install ` is **AI-first**. One shared workflow is used by +ordinary installation, by `sys ask` installation requests, and by explicit +backend flags: + +``` +request -> identify application -> gather evidence -> AI investigation +-> proposed selection -> deterministic resolution/validation -> review +-> approved execution -> verification -> history +``` + +The workflow lives in `phoebus-executor::install`; the model loop lives in +`phoebus-ai::install`. The CLI only wires flags and presentation. + +### 1. The model investigates with typed, read-only tools + +The model has no shell and no filesystem access. It runs a **bounded** +multi-turn investigation and may: + +- request evidence with the read-only typed actions `discover_candidates`, + `inspect_candidate`, `check_backend`, `inspect_installation`; +- ask the user a question about intent when system facts cannot answer it; +- then return a structured `InstallProposal { application, backend, candidate, + version, reason, tradeoffs, evidence }`. + +Bounds: turn limit, per-turn request limit, evidence-size cap, and +repeated-request detection (the same evidence is never fetched twice; the model +is told to finalise or ask the user). Evidence is untrusted data; it cannot +grant capabilities. Only the four read-only actions are permitted; a proposal +that requests anything mutating fails closed. + +### 2. The deterministic resolver is authoritative + +The model's proposal is never executed directly. `validate_proposal`: + +- re-resolves the application against real backend metadata, including + friendly-name resolution per lane; +- rejects a candidate that is not exactly one the backend reported (fabricated + or stale identifiers), an unavailable candidate, an ambiguous friendly name, + or a duplicate of an existing installation; +- maps the confirmed candidate to the *existing* broker action + (`install_package`, `flatpak_install`, `snap_install`, `nix_prepare`, + `custom_ebuild_install`), so there is no parallel execution path; +- computes concrete effects (Portage `--pretend`, or a synthetic effect for + binary lanes) and a single approval digest. + +A rejection is returned to the model as a bounded finding, which may revise its +proposal up to the turn limit. + +### 3. Hard rules stay outside model discretion + +Portage owns the kernel, drivers, systemd, the host graphics/audio stack and +boot (enforced by the selection policy). Signature verification, architecture +and hardware compatibility, target-root isolation and the privilege boundary +are not proposable. A custom ebuild remains a separately reviewed, untrusted +artifact; the install workflow never builds one as part of "investigation". + +### 4. Explicit backend flags are authoritative + +`--portage`, `--flatpak`, `--nix`, `--snap`, `--appimage`, `--ebuild`: + +- bypass the model entirely and use deterministic resolution within the + requested lane; +- are mutually exclusive (CLI arg group); +- never fall back to another lane: if the lane cannot satisfy the request, the + reason and the alternatives are shown and nothing is installed; +- still require validation, a protective snapshot where applicable, + authentication and review. + +Saved preferences inform ordinary AI recommendations; an explicit flag takes +precedence over a saved preference. + +### 5. No-model path + +For an unqualified install with no reachable provider, the workflow prints the +deterministic candidate selection and the explicit-backend commands, then +**refuses to install**. Provider failure is never treated as permission to +install through a lane. Explicit-backend installation, service management and +recovery remain fully deterministic and model-free. + +### 6. One transaction engine, verification, truthful history + +All three selection sources execute through the same broker action and the same +transaction engine. The workflow records the transaction **before** the +mutation (so an interrupted run leaves a visible in-progress record), then: + +- revalidates the reviewed plan immediately before execution (candidate, + version, action and effects digest); a material change aborts; +- verifies the installed identity and version after execution (`/var/db/pkg`, + `flatpak list`, `snap list`, the managed AppImage record); +- records the final outcome and the protective snapshot. + +Success is never claimed merely because a subprocess exited zero: verification +failure is a failed transaction. + +## Consequences + +- The AI needs bounded, structured tools; the read-only actions are real `sys` + surfaces (`sys --action '{"action":"discover_candidates",...}'`) as well as + model tools. +- A connected model is required for an unqualified `sys install`; this is the + AI-first contract. It is never required to install explicitly, to manage + services, or to recover. +- The resolver and the model must agree on identifiers. The wire names for + backends (`portage-source`, `custom-ebuild`, ...) are the same as + `Backend::as_str`, so evidence and proposals share one vocabulary. +- Multi-turn behaviour depends on the transport. The direct providers carry the + full conversation; the OpenCode adapter concatenates messages, so + investigation is best-effort there. + +## Non-goals + +- Letting the model execute anything (it cannot). +- Automatically building generated ebuilds during investigation. +- Silent lane switching or duplicate installs. +- Replacing deterministic administration with a model. + +## Verification + +Unit/integration coverage: the AI loop (steps, bounds, repetition, revision, +provider failure), the resolver (fabrication, ambiguity, duplicate, changed +evidence), the action mapping, the CLI (flag conflicts, no-fallback, no-model +offer), and the transaction begin/finish. VM journeys through `sys install` +(AI-selected and explicit-backend) remain the acceptance gate; see +`docs/SYS.md` and `docs/STATUS.md`. diff --git a/docs/adr/README.md b/docs/adr/README.md index 390e36c..47050f7 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -18,5 +18,6 @@ and link it here. | [0010](0010-graphical-installer-frontend.md) | Graphical installer frontend and typed bridge | Accepted | | [0011](0011-opencode-connection-boundary.md) | OpenCode connection boundary | Accepted | | [0012](0012-nvidia-driver-policy.md) | NVIDIA accelerated-driver policy and payload | Accepted | +| [0013](0013-ai-first-installation.md) | AI-first package installation workflow | Accepted | Format: Context / Decision / Consequences / Status. diff --git a/installer-rs/crates/phoebus-ai/src/install.rs b/installer-rs/crates/phoebus-ai/src/install.rs new file mode 100644 index 0000000..6f29b69 --- /dev/null +++ b/installer-rs/crates/phoebus-ai/src/install.rs @@ -0,0 +1,712 @@ +//! AI-driven installation investigation. +//! +//! The model does not get a shell. It runs a **bounded, multi-turn +//! investigation**: it may ask for typed, read-only evidence (via +//! [`InstallSession::investigate`]), ask the user a question about intent +//! (via [`InstallSession::ask`]), and only then return a structured +//! [`InstallProposal`]. The proposal is validated structurally here and +//! *independently* by the deterministic resolver in `phoebus-executor`, which +//! must confirm the candidate against real backend metadata. +//! +//! Bounds: a turn limit, a per-turn request limit, a response-size limit and +//! repeated-request detection. A repeated evidence request is not executed +//! again; the model is told to finalise or ask the user instead of looping. + +use phoebus_core::action::{valid_application_name, valid_candidate_id, SystemAction}; +use phoebus_core::selection::Backend; +use serde::{Deserialize, Serialize}; + +use crate::provider::{ + extract_content, ChatMessage, ChatRequest, ModelTransport, ProviderKind, ResponseFormat, + SystemFacts, +}; +use crate::AiError; + +/// The model's structured installation recommendation. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct InstallProposal { + /// The user-facing application (identity, not a backend id). + pub application: String, + pub backend: Backend, + /// The backend-native identifier, copied from evidence. + pub candidate: String, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub version: Option, + /// Why this candidate suits this machine and request. + pub reason: String, + #[serde(default)] + pub tradeoffs: Vec, + /// Evidence the recommendation rests on (candidate ids, measured facts). + #[serde(default)] + pub evidence: Vec, +} + +const MAX_TEXT: usize = 4096; +const MAX_ITEM: usize = 1024; +const MAX_ITEMS: usize = 16; + +impl InstallProposal { + /// Structural validation only. The deterministic resolver still confirms + /// the candidate against real metadata; this just rejects malformed or + /// absurd proposals before they reach it. + pub fn validate_structural(&self) -> Result<(), String> { + if !valid_application_name(&self.application) { + return Err(format!("invalid application name: {}", self.application)); + } + if !valid_candidate_id(self.backend, &self.candidate) { + return Err(format!( + "invalid {} candidate id: {}", + self.backend.as_str(), + self.candidate + )); + } + if self.reason.trim().is_empty() || self.reason.len() > MAX_TEXT { + return Err("a bounded, non-empty reason is required".into()); + } + for list in [&self.tradeoffs, &self.evidence] { + if list.len() > MAX_ITEMS { + return Err(format!("at most {MAX_ITEMS} items are allowed")); + } + if list.iter().any(|s| s.len() > MAX_ITEM) { + return Err("an item is too long".into()); + } + } + if let Some(version) = &self.version { + if version.len() > 256 || version.chars().any(|c| c.is_control()) { + return Err("invalid version string".into()); + } + } + Ok(()) + } + + pub fn render(&self) -> String { + let mut out = String::new(); + out.push_str(&format!( + "application: {}\n backend: {}\n candidate: {}\n", + self.application, + self.backend.as_str(), + self.candidate + )); + if let Some(version) = &self.version { + out.push_str(&format!(" version: {version}\n")); + } + out.push_str(&format!(" why: {}\n", self.reason)); + for t in &self.tradeoffs { + out.push_str(&format!(" tradeoff: {t}\n")); + } + for e in &self.evidence { + out.push_str(&format!(" evidence: {e}\n")); + } + out + } +} + +/// A step in the investigation conversation. +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +pub enum InstallStep { + Ask { + question: String, + }, + Investigate { + requests: Vec, + }, + Propose { + summary: String, + proposal: InstallProposal, + }, +} + +/// The closed set of read-only actions the model may request as evidence. +pub fn is_investigation_action(action: &SystemAction) -> bool { + matches!( + action, + SystemAction::DiscoverCandidates { .. } + | SystemAction::InspectCandidate { .. } + | SystemAction::CheckBackend { .. } + | SystemAction::InspectInstallation { .. } + ) +} + +/// One piece of evidence returned for a request. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct Evidence { + pub request: String, + pub output: String, +} + +/// The system-side half of the loop: produce evidence and, optionally, ask the +/// user a question about intent. Implemented by `phoebus-executor`/`sys`. +pub trait InstallSession { + /// Execute read-only investigation actions and return their evidence. + fn investigate(&self, requests: &[SystemAction]) -> Vec; + /// Ask the user a question about intent or preference. `None` means no + /// answer is available (non-interactive); the model is then told to proceed + /// with a conservative, reversible assumption. + fn ask(&self, question: &str) -> Option; +} + +/// Hard bounds on the investigation loop. +#[derive(Debug, Clone)] +pub struct Limits { + pub max_turns: usize, + pub max_requests_per_turn: usize, + /// Maximum bytes of evidence fed back in one turn. + pub max_evidence_bytes: usize, + /// How many times the exact same evidence request set may repeat before the + /// loop refuses to execute it again. + pub max_identical_requests: usize, +} + +impl Default for Limits { + fn default() -> Self { + Self { + max_turns: 8, + max_requests_per_turn: 6, + max_evidence_bytes: 24 * 1024, + max_identical_requests: 1, + } + } +} + +pub const INSTALL_PROMPT: &str = "\ +You are the Phoebus OS installation advisor. The user asked to install an application. \ +You must recommend the single best installation option for THIS machine and the user's \ +request, using only real candidate identifiers returned to you. You have no shell, no \ +root, no filesystem access and no credentials. + +Each reply is ONE JSON object with version 2 and a `kind`: + +1. Investigate (read-only evidence): \ +{\"version\":2,\"kind\":\"investigate\",\"requests\":[,...]}. Allowed actions: \ +discover_candidates (query, optional kind/gui/requires_sandbox), inspect_candidate \ +(backend, id), check_backend (backend), inspect_installation (application). + +2. Ask the user about intent (only when system facts cannot answer): \ +{\"version\":2,\"kind\":\"ask\",\"question\":\"...\"}. Use this sparingly, e.g. whether \ +the application must access local development tools or a specific file. + +3. Propose: {\"version\":2,\"kind\":\"propose\",\"proposal\":{\"application\":\"...\",\ +\"backend\":\"...\",\"candidate\":\"...\",\"version\":\"...\",\"reason\":\"...\",\ +\"tradeoffs\":[\"...\"],\"evidence\":[\"...\"]}}. + +Backends: portage-source, portage-binary, portage-vendor, nix, flatpak, snap, appimage, \ +custom-ebuild. + +Rules: compare suitable options across lanes; do NOT choose a lane merely because the \ +application is a desktop app (Flatpak/Snap) or a developer tool (Nix) — base the choice on \ +the machine facts, the user's requirement, permissions, confinement, integration, size, \ +measured compile time and update behaviour. Never invent a candidate id, version, size, \ +checksum, availability or compatibility: use only what discover_candidates returned. \ +Portage owns the kernel, drivers, systemd, the host graphics/audio stack and boot tooling. \ +Prefer an existing installation and the user's saved preference; never migrate or duplicate \ +silently. If the user asked for a specific backend, honour it. When you have enough \ +evidence, propose."; + +/// Build the first request of the investigation. +pub fn build_open_request( + provider: ProviderKind, + model: &str, + facts: &SystemFacts, + request: &str, +) -> ChatRequest { + let model = if model.trim().is_empty() { + provider.default_model().to_string() + } else { + model.trim().to_string() + }; + let user = format!( + "System facts (JSON):\n{}\n\nUser installation request: {request}\n\n\ + Investigate or propose.", + facts.render() + ); + ChatRequest { + model, + messages: vec![ + ChatMessage { + role: "system".into(), + content: INSTALL_PROMPT.into(), + }, + ChatMessage { + role: "user".into(), + content: user, + }, + ], + temperature: 0.0, + response_format: Some(ResponseFormat { + kind: "json_object".into(), + }), + } +} + +/// Parse one model message strictly. Unknown fields, an unsupported version, an +/// unknown kind, or a mutating/invalid investigation action fail closed. +pub fn parse_step(text: &str) -> Result { + let value: serde_json::Value = serde_json::from_str(text)?; + let obj = value + .as_object() + .ok_or_else(|| AiError::Rejected("the reply must be a JSON object".into()))?; + let version = obj + .get("version") + .and_then(|v| v.as_u64()) + .ok_or_else(|| AiError::Rejected("missing `version`".into()))?; + if version != 2 { + return Err(AiError::UnsupportedVersion(version as u32)); + } + let kind = obj + .get("kind") + .and_then(|k| k.as_str()) + .ok_or_else(|| AiError::Rejected("missing `kind`".into()))?; + let allowed: &[&str] = match kind { + "ask" => &["version", "kind", "question"], + "investigate" => &["version", "kind", "requests"], + "propose" => &["version", "kind", "proposal"], + other => return Err(AiError::Rejected(format!("unknown kind `{other}`"))), + }; + for key in obj.keys() { + if !allowed.contains(&key.as_str()) { + return Err(AiError::Rejected(format!("unexpected field `{key}`"))); + } + } + let get = |key: &str| { + obj.get(key) + .cloned() + .ok_or_else(|| AiError::Rejected(format!("missing `{key}`"))) + }; + match kind { + "ask" => { + let question: String = serde_json::from_value(get("question")?)?; + if question.trim().is_empty() || question.len() > 1024 { + return Err(AiError::Rejected("invalid question".into())); + } + Ok(InstallStep::Ask { question }) + } + "investigate" => { + let requests: Vec = serde_json::from_value(get("requests")?)?; + for request in &requests { + if !is_investigation_action(request) { + return Err(AiError::Rejected(format!( + "`{}` is not a permitted read-only investigation action", + request.describe() + ))); + } + request + .validate() + .map_err(|e| AiError::Rejected(format!("invalid request: {e}")))?; + } + Ok(InstallStep::Investigate { requests }) + } + "propose" => { + let proposal: InstallProposal = serde_json::from_value(get("proposal")?)?; + proposal.validate_structural().map_err(AiError::Rejected)?; + Ok(InstallStep::Propose { + summary: String::new(), + proposal, + }) + } + _ => unreachable!(), + } +} + +fn messages_body(request: &ChatRequest) -> Result { + Ok(serde_json::to_string(request)?) +} + +/// Run the bounded investigation and return a structurally valid proposal. +/// +/// `validate` is the deterministic resolver's check (provided by the caller). +/// A rejected proposal is fed back to the model for a bounded revision rather +/// than being accepted. +#[allow(clippy::too_many_arguments)] +pub fn investigate_install( + provider: ProviderKind, + endpoint: &str, + model: &str, + facts: &SystemFacts, + request: &str, + transport: &dyn ModelTransport, + session: &dyn InstallSession, + validate: &dyn Fn(&InstallProposal) -> Result<(), String>, + limits: &Limits, +) -> Result { + if provider == ProviderKind::None { + return Err(AiError::ProviderUnavailable( + "no AI provider selected".into(), + )); + } + crate::provider::validate_endpoint(endpoint)?; + facts.validate_no_forbidden()?; + + let mut chat = build_open_request(provider, model, facts, request); + let mut repeated: std::collections::BTreeMap = std::collections::BTreeMap::new(); + let mut turns = 0usize; + + while turns < limits.max_turns { + turns += 1; + let body = messages_body(&chat)?; + let response = transport.send(provider, endpoint, &body)?; + let content = extract_content(&response)?; + let step = parse_step(&content)?; + + match step { + InstallStep::Ask { question } => { + chat.messages.push(ChatMessage { + role: "assistant".into(), + content: content.clone(), + }); + let answer = session.ask(&question); + let user = match answer { + Some(answer) => format!("The user answered: {answer}"), + None => "No answer is available (non-interactive). Proceed with a \ + conservative, reversible choice and state your assumption." + .to_string(), + }; + chat.messages.push(ChatMessage { + role: "user".into(), + content: user, + }); + } + InstallStep::Investigate { requests } => { + if requests.is_empty() { + return Err(AiError::Rejected("empty investigation request".into())); + } + if requests.len() > limits.max_requests_per_turn { + return Err(AiError::Rejected(format!( + "too many investigation requests in one turn (max {})", + limits.max_requests_per_turn + ))); + } + for request in &requests { + if !is_investigation_action(request) { + return Err(AiError::Rejected(format!( + "`{}` is not a permitted read-only investigation action", + request.describe() + ))); + } + request + .validate() + .map_err(|e| AiError::Rejected(format!("invalid request: {e}")))?; + } + // Canonical key: sorted action JSON, so order does not matter. + let mut keys: Vec = requests + .iter() + .filter_map(|r| serde_json::to_string(r).ok()) + .collect(); + keys.sort(); + let key = keys.join("|"); + let count = repeated.entry(key).or_insert(0); + *count += 1; + chat.messages.push(ChatMessage { + role: "assistant".into(), + content: content.clone(), + }); + if *count > limits.max_identical_requests { + chat.messages.push(ChatMessage { + role: "user".into(), + content: "You already requested exactly this evidence; it will not \ + be fetched again. Propose now, or ask the user a question \ + if their intent is genuinely unknown." + .to_string(), + }); + continue; + } + let evidence = session.investigate(&requests); + let mut payload = String::new(); + for item in &evidence { + payload.push_str(&format!( + "Request: {}\nOutput:\n{}\n\n", + item.request, item.output + )); + if payload.len() >= limits.max_evidence_bytes { + break; + } + } + if payload.len() > limits.max_evidence_bytes { + payload.truncate(limits.max_evidence_bytes); + payload.push_str("\n[evidence truncated]"); + } + chat.messages.push(ChatMessage { + role: "user".into(), + content: format!("Evidence:\n{payload}"), + }); + } + InstallStep::Propose { proposal, .. } => { + proposal.validate_structural().map_err(AiError::Rejected)?; + match validate(&proposal) { + Ok(()) => return Ok(proposal), + Err(findings) => { + chat.messages.push(ChatMessage { + role: "assistant".into(), + content: content.clone(), + }); + chat.messages.push(ChatMessage { + role: "user".into(), + content: format!( + "Your proposal was rejected by the deterministic resolver: \ + {findings}. Investigate further or propose a different, \ + real candidate." + ), + }); + } + } + } + } + } + + Err(AiError::Rejected(format!( + "the investigation did not reach a valid proposal within {} turns", + limits.max_turns + ))) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::provider::chat_response; + + fn facts() -> SystemFacts { + SystemFacts { + arch: "x86_64".into(), + cpu_cores: 8, + memory_mib: 16384, + ..Default::default() + } + } + + struct Sessions { + evidence: std::cell::RefCell>>, + answer: Option, + } + + impl InstallSession for Sessions { + fn investigate(&self, requests: &[SystemAction]) -> Vec { + self.evidence.borrow_mut().push(requests.to_vec()); + requests + .iter() + .map(|r| Evidence { + request: r.describe(), + output: "[{\"backend\":\"flatpak\",\"id\":\"org.mozilla.firefox\"}]".into(), + }) + .collect() + } + fn ask(&self, _q: &str) -> Option { + self.answer.clone() + } + } + + fn ok_proposal() -> &'static str { + r#"{"version":2,"kind":"propose","proposal":{"application":"firefox","backend":"flatpak","candidate":"org.mozilla.firefox","reason":"sandboxed, native Wayland","evidence":["org.mozilla.firefox"]}}"# + } + + #[test] + fn parse_accepts_the_three_step_kinds() { + let ask = parse_step(r#"{"version":2,"kind":"ask","question":"Do you need dev tools?"}"#) + .unwrap(); + assert!(matches!(ask, InstallStep::Ask { .. })); + let inv = parse_step( + r#"{"version":2,"kind":"investigate","requests":[{"action":"discover_candidates","query":"firefox"}]}"#, + ) + .unwrap(); + assert!(matches!(inv, InstallStep::Investigate { .. })); + let prop = parse_step(ok_proposal()).unwrap(); + assert!(matches!(prop, InstallStep::Propose { .. })); + } + + #[test] + fn parse_rejects_mutation_unknown_fields_and_bad_version() { + // A mutating action is not a permitted investigation request. + let err = parse_step( + r#"{"version":2,"kind":"investigate","requests":[{"action":"install_package","atom":"vim"}]}"#, + ) + .unwrap_err(); + assert!(err.to_string().contains("read-only") || err.to_string().contains("permitted")); + // Unknown top-level field. + assert!(parse_step(r#"{"version":2,"kind":"ask","question":"q","shell":"sh"}"#).is_err()); + // Unsupported version. + assert!(matches!( + parse_step(r#"{"version":1,"kind":"ask","question":"q"}"#), + Err(AiError::UnsupportedVersion(1)) + )); + // Bad candidate for the backend. + let bad = r#"{"version":2,"kind":"propose","proposal":{"application":"firefox","backend":"flatpak","candidate":"bad id","reason":"x"}}"#; + assert!(parse_step(bad).unwrap_err().to_string().contains("invalid")); + } + + #[test] + fn investigation_then_proposal_succeeds() { + let transport = crate::provider::ScriptedTransport::new(vec![ + chat_response( + r#"{"version":2,"kind":"investigate","requests":[{"action":"discover_candidates","query":"firefox"}]}"#, + ), + chat_response(ok_proposal()), + ]); + let session = Sessions { + evidence: std::cell::RefCell::new(Vec::new()), + answer: None, + }; + let proposal = investigate_install( + ProviderKind::Local, + "http://127.0.0.1:11434/v1/chat/completions", + "m", + &facts(), + "install firefox", + &transport, + &session, + &|_| Ok(()), + &Limits::default(), + ) + .unwrap(); + assert_eq!(proposal.candidate, "org.mozilla.firefox"); + assert_eq!(session.evidence.borrow().len(), 1); + let requests = transport.requests(); + assert_eq!(requests.len(), 2); + // The second request must carry the evidence back to the model. + assert!(requests[1].contains("org.mozilla.firefox")); + } + + #[test] + fn a_rejected_proposal_is_revised_with_findings() { + let transport = crate::provider::ScriptedTransport::new(vec![ + chat_response(ok_proposal()), + chat_response(ok_proposal()), + ]); + let session = Sessions { + evidence: std::cell::RefCell::new(Vec::new()), + answer: None, + }; + let attempts = std::cell::Cell::new(0); + let validate = |_: &InstallProposal| -> Result<(), String> { + attempts.set(attempts.get() + 1); + if attempts.get() == 1 { + Err("no such Flatpak id in the configured remotes".into()) + } else { + Ok(()) + } + }; + let proposal = investigate_install( + ProviderKind::Local, + "http://127.0.0.1:11434/v1/chat/completions", + "m", + &facts(), + "install firefox", + &transport, + &session, + &validate, + &Limits::default(), + ) + .unwrap(); + assert_eq!(proposal.application, "firefox"); + assert_eq!(attempts.get(), 2); + let requests = transport.requests(); + assert!(requests[1].contains("rejected")); + } + + #[test] + fn truncated_by_the_turn_limit() { + // The model keeps investigating forever; the loop stops. + let transport = crate::provider::ScriptedTransport::new( + (0..10) + .map(|_| { + chat_response( + r#"{"version":2,"kind":"investigate","requests":[{"action":"check_backend","backend":"flatpak"}]}"#, + ) + }) + .collect(), + ); + let session = Sessions { + evidence: std::cell::RefCell::new(Vec::new()), + answer: None, + }; + let limits = Limits { + max_turns: 4, + ..Default::default() + }; + let err = investigate_install( + ProviderKind::Local, + "http://127.0.0.1:11434/v1/chat/completions", + "m", + &facts(), + "install x", + &transport, + &session, + &|_| Ok(()), + &limits, + ) + .unwrap_err(); + assert!(err.to_string().contains("did not reach a valid proposal")); + // The identical evidence is fetched exactly once. + assert_eq!(session.evidence.borrow().len(), 1); + } + + #[test] + fn too_many_requests_in_a_turn_are_refused() { + let transport = crate::provider::ScriptedTransport::new(vec![chat_response( + r#"{"version":2,"kind":"investigate","requests":[{"action":"check_backend","backend":"flatpak"},{"action":"check_backend","backend":"nix"},{"action":"check_backend","backend":"snap"},{"action":"check_backend","backend":"appimage"},{"action":"check_backend","backend":"portage-source"},{"action":"check_backend","backend":"portage-binary"},{"action":"check_backend","backend":"custom-ebuild"}]}"#, + )]); + let session = Sessions { + evidence: std::cell::RefCell::new(Vec::new()), + answer: None, + }; + let err = investigate_install( + ProviderKind::Local, + "http://127.0.0.1:11434/v1/chat/completions", + "m", + &facts(), + "install x", + &transport, + &session, + &|_| Ok(()), + &Limits::default(), + ) + .unwrap_err(); + assert!(err.to_string().contains("too many")); + assert!(session.evidence.borrow().is_empty()); + } + + #[test] + fn ask_feeds_the_answer_back_and_none_is_explicit() { + let transport = crate::provider::ScriptedTransport::new(vec![ + chat_response(r#"{"version":2,"kind":"ask","question":"Do you need dev tools?"}"#), + chat_response(ok_proposal()), + ]); + let session = Sessions { + evidence: std::cell::RefCell::new(Vec::new()), + answer: Some("yes".into()), + }; + investigate_install( + ProviderKind::Local, + "http://127.0.0.1:11434/v1/chat/completions", + "m", + &facts(), + "install nodejs", + &transport, + &session, + &|_| Ok(()), + &Limits::default(), + ) + .unwrap(); + assert!(transport.requests()[1].contains("The user answered: yes")); + } + + #[test] + fn an_unavailable_provider_is_explicit() { + let transport = crate::provider::TestTransport::new("{}"); + let session = Sessions { + evidence: std::cell::RefCell::new(Vec::new()), + answer: None, + }; + let err = investigate_install( + ProviderKind::None, + "http://127.0.0.1:11434/v1/chat/completions", + "m", + &facts(), + "install x", + &transport, + &session, + &|_| Ok(()), + &Limits::default(), + ) + .unwrap_err(); + assert!(matches!(err, AiError::ProviderUnavailable(_))); + } +} diff --git a/installer-rs/crates/phoebus-ai/src/lib.rs b/installer-rs/crates/phoebus-ai/src/lib.rs index 4806a32..f6ad464 100644 --- a/installer-rs/crates/phoebus-ai/src/lib.rs +++ b/installer-rs/crates/phoebus-ai/src/lib.rs @@ -7,6 +7,7 @@ //! step performed by the deterministic backend. pub mod assistant; +pub mod install; pub mod privacy; pub mod provider; diff --git a/installer-rs/crates/phoebus-ai/src/provider.rs b/installer-rs/crates/phoebus-ai/src/provider.rs index 4be62d0..1440e7b 100644 --- a/installer-rs/crates/phoebus-ai/src/provider.rs +++ b/installer-rs/crates/phoebus-ai/src/provider.rs @@ -99,6 +99,21 @@ pub struct SystemFacts { pub recommended_kernel_profile: String, /// Measured compile times (seconds) for the slowest packages, capped. pub measured_compile_times: BTreeMap, + /// Free space on the intended root, in MiB (`0` means unknown). + #[serde(default)] + pub storage_free_mib: u64, + /// Whether a Wayland session/stack is in use on the intended system. + #[serde(default)] + pub wayland: bool, + /// Lanes whose tooling is present and usable (Portage, Nix, Flatpak, ...). + #[serde(default)] + pub available_backends: Vec, + /// Saved per-application backend preferences. + #[serde(default)] + pub saved_preferences: BTreeMap, + /// Whether Btrfs snapshots and rollback are available for recovery. + #[serde(default)] + pub recovery_snapshots: bool, } /// Storage facts supplied by the caller (disk probing lives in the executor). @@ -149,6 +164,7 @@ impl SystemFacts { encryption: config.encryption.mode.to_string(), recommended_kernel_profile: hardware.recommended_kernel_profile().to_string(), measured_compile_times: measured.into_iter().collect(), + ..Default::default() } } @@ -179,6 +195,16 @@ impl SystemFacts { return Err(AiError::PrivateData(atom.clone())); } } + for backend in &self.available_backends { + if is_forbidden_path(backend) { + return Err(AiError::PrivateData(backend.clone())); + } + } + for (app, backend) in &self.saved_preferences { + if is_forbidden_path(app) || is_forbidden_path(backend) { + return Err(AiError::PrivateData(format!("{app}={backend}"))); + } + } Ok(()) } } diff --git a/installer-rs/crates/phoebus-core/src/action.rs b/installer-rs/crates/phoebus-core/src/action.rs index 80e256a..ed7ca82 100644 --- a/installer-rs/crates/phoebus-core/src/action.rs +++ b/installer-rs/crates/phoebus-core/src/action.rs @@ -115,6 +115,39 @@ pub enum SystemAction { backend: Option, }, + // ------------------------------------------------------------------ + // Bounded, read-only investigation used by the AI installation workflow. + // These return evidence only; they never mutate the system. + // ------------------------------------------------------------------ + /// Discover the real candidates for an application across the available + /// lanes (Portage, Nix, Flatpak, Snap, AppImage, the Phoebus overlay). + DiscoverCandidates { + query: String, + #[serde(default, skip_serializing_if = "Option::is_none")] + kind: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + backend: Option, + #[serde(default)] + gui: bool, + #[serde(default)] + requires_sandbox: bool, + }, + /// Inspect one resolved candidate's metadata (version, source, sizes, + /// dependencies, permissions, confinement, update behaviour). + InspectCandidate { + backend: Backend, + id: String, + }, + /// Report whether a lane is installed and ready, including daemon state and + /// confinement where relevant. + CheckBackend { + backend: Backend, + }, + /// Report existing installations of an application and any duplication. + InspectInstallation { + application: String, + }, + // ------------------------------------------------------------------ // Snap lane. // ------------------------------------------------------------------ @@ -266,6 +299,18 @@ impl SystemAction { Some(backend) => format!("prefer {} for {name}", backend.as_str()), None => format!("clear the backend preference for {name}"), }, + SystemAction::DiscoverCandidates { query, .. } => { + format!("discover installation candidates for `{query}`") + } + SystemAction::InspectCandidate { backend, id } => { + format!("inspect the {} candidate {id}", backend.as_str()) + } + SystemAction::CheckBackend { backend } => { + format!("check whether the {} lane is ready", backend.as_str()) + } + SystemAction::InspectInstallation { application } => { + format!("inspect existing installations of {application}") + } SystemAction::SnapFind { query } => format!("search the Snap store for `{query}`"), SystemAction::SnapInfo { name } => format!("inspect snap {name}"), SystemAction::SnapInstall { @@ -341,6 +386,10 @@ impl SystemAction { | SystemAction::SnapConnections { .. } | SystemAction::AppImageInfo { .. } | SystemAction::AppImageList + | SystemAction::DiscoverCandidates { .. } + | SystemAction::InspectCandidate { .. } + | SystemAction::CheckBackend { .. } + | SystemAction::InspectInstallation { .. } | SystemAction::CustomEbuildList => Risk::Low, SystemAction::PrepareUpdates => Risk::Medium, SystemAction::EnableService { .. } @@ -389,6 +438,10 @@ impl SystemAction { | SystemAction::SnapConnections { .. } | SystemAction::AppImageInfo { .. } | SystemAction::AppImageList + | SystemAction::DiscoverCandidates { .. } + | SystemAction::InspectCandidate { .. } + | SystemAction::CheckBackend { .. } + | SystemAction::InspectInstallation { .. } | SystemAction::CustomEbuildList ) } @@ -484,6 +537,28 @@ impl SystemAction { Err(format!("invalid package name: {name}")) } } + SystemAction::DiscoverCandidates { query, .. } => { + if valid_search_query(query) { + Ok(()) + } else { + Err(format!("invalid application query: {query}")) + } + } + SystemAction::InspectCandidate { backend, id } => { + if valid_candidate_id(*backend, id) { + Ok(()) + } else { + Err(format!("invalid {} candidate id: {id}", backend.as_str())) + } + } + SystemAction::CheckBackend { .. } => Ok(()), + SystemAction::InspectInstallation { application } => { + if valid_application_name(application) { + Ok(()) + } else { + Err(format!("invalid application name: {application}")) + } + } SystemAction::SnapFind { query } => { if valid_search_query(query) { Ok(()) @@ -729,6 +804,33 @@ pub fn valid_http_url(value: &str) -> bool { && !value.chars().any(|c| c.is_whitespace() || c.is_control()) } +/// A user-facing application name (`firefox`, `org.mozilla.firefox`, +/// `app-editors/vim`). Bounded, no leading dash, no whitespace or controls. +pub fn valid_application_name(value: &str) -> bool { + !value.is_empty() + && value.len() <= 128 + && !value.starts_with('-') + && value + .chars() + .all(|c| c.is_ascii_alphanumeric() || "._+@/-".contains(c)) +} + +/// Validate a backend-native candidate identifier. Each lane has its own +/// identity grammar, so a Portage atom is checked as an atom and a Flatpak +/// application id as a reverse-DNS id; a mismatch fails closed. +pub fn valid_candidate_id(backend: Backend, id: &str) -> bool { + match backend { + Backend::PortageSource | Backend::PortageBinary | Backend::PortageVendor => { + valid_package_spec(id) + } + Backend::Nix => valid_nix_attribute(id), + Backend::Flatpak => valid_flatpak_app_id(id), + Backend::Snap => valid_snap_name(id), + Backend::AppImage => valid_appimage_name(id), + Backend::CustomEbuild => valid_ebuild_atom(id), + } +} + /// A real SHA-256: 64 hex characters and not the all-zero placeholder. pub fn valid_sha256(value: &str) -> bool { value.len() == 64 diff --git a/installer-rs/crates/phoebus-core/src/selection.rs b/installer-rs/crates/phoebus-core/src/selection.rs index 7b28510..ebe3b23 100644 --- a/installer-rs/crates/phoebus-core/src/selection.rs +++ b/installer-rs/crates/phoebus-core/src/selection.rs @@ -36,23 +36,30 @@ use crate::hardware::GpuVendor; /// A software lane. Each maps to a real backend with distinct guarantees. #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)] -#[serde(rename_all = "snake_case")] pub enum Backend { /// Gentoo source ebuild compiled locally. + #[serde(rename = "portage-source")] PortageSource, /// A signed binary package from the official Gentoo binhost. + #[serde(rename = "portage-binary")] PortageBinary, /// A native vendor-binary ebuild (`-bin`/`-launcher`), e.g. google-chrome. + #[serde(rename = "portage-vendor")] PortageVendor, /// Nix (developer tools, alternate versions, reproducible environments). + #[serde(rename = "nix")] Nix, /// Flatpak (sandboxed GUI applications). + #[serde(rename = "flatpak")] Flatpak, /// Snap (sandboxed applications with channel/refresh semantics). + #[serde(rename = "snap")] Snap, /// A managed AppImage (single-file, user-run, no built-in sandbox). + #[serde(rename = "appimage")] AppImage, /// A Phoebus-managed custom ebuild in the dedicated overlay. + #[serde(rename = "custom-ebuild")] CustomEbuild, } @@ -115,17 +122,21 @@ impl Backend { /// What is being installed. Used for hard rules and as a suitability hint, not /// as an automatic routing decision. #[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)] -#[serde(rename_all = "snake_case")] pub enum PackageKind { /// Kernel, drivers, systemd, host graphics/audio, boot — Portage only. + #[serde(rename = "base-system")] BaseSystem, /// A graphical desktop application. + #[serde(rename = "desktop-app")] DesktopApp, /// A developer tool, runtime or per-project environment. + #[serde(rename = "developer-tool")] DeveloperTool, /// A command-line administration or utility tool. + #[serde(rename = "cli-tool")] CliTool, #[default] + #[serde(rename = "unclassified")] Unclassified, } diff --git a/installer-rs/crates/phoebus-core/src/transaction.rs b/installer-rs/crates/phoebus-core/src/transaction.rs index e189180..2790aa9 100644 --- a/installer-rs/crates/phoebus-core/src/transaction.rs +++ b/installer-rs/crates/phoebus-core/src/transaction.rs @@ -13,6 +13,9 @@ use crate::error::{CoreError, Result}; #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] #[serde(default)] pub struct TransactionRecord { + /// A stable id, assigned when the transaction begins. A record that never + /// gets a terminal result is an interrupted operation, not a success. + pub id: u64, pub created_unix: u64, /// Where the request came from: `sys` or `assistant`. pub origin: String, @@ -79,6 +82,7 @@ impl TransactionOutcome { impl Default for TransactionRecord { fn default() -> Self { Self { + id: 0, created_unix: 0, origin: String::new(), summary: String::new(), @@ -187,6 +191,7 @@ mod tests { let path = dir.path().join("transactions.toml"); let mut log = TransactionLog::default(); log.append(TransactionRecord { + id: 0, created_unix: 10, origin: "assistant".into(), summary: "install vim".into(), @@ -221,6 +226,7 @@ mod tests { let path = dir.path().join("transactions.toml"); let mut log = TransactionLog::default(); log.append(TransactionRecord { + id: 0, created_unix: 20, origin: "assistant".into(), summary: "install two".into(), diff --git a/installer-rs/crates/phoebus-executor/src/actions.rs b/installer-rs/crates/phoebus-executor/src/actions.rs index 86cb985..ab86e29 100644 --- a/installer-rs/crates/phoebus-executor/src/actions.rs +++ b/installer-rs/crates/phoebus-executor/src/actions.rs @@ -532,6 +532,42 @@ pub fn execute( } } } + SystemAction::DiscoverCandidates { + query, + kind, + backend, + gui, + requires_sandbox, + } => { + let need = Need { + name: query.clone(), + kind: (*kind).unwrap_or_else(|| chooser::infer_kind(query)), + requires_sandbox: *requires_sandbox, + requires_proprietary: false, + gui: *gui, + requires_features: Vec::new(), + explicit_backend: *backend, + max_install_mib: None, + }; + let candidates = chooser::resolve_candidates(exec, root, &need); + serde_json::to_string_pretty(&candidates) + .unwrap_or_else(|e| format!("could not serialise candidates: {e}")) + } + SystemAction::InspectCandidate { backend, id } => { + let detail = chooser::candidate_detail(exec, root, *backend, id); + serde_json::to_string_pretty(&detail) + .unwrap_or_else(|e| format!("could not serialise candidate: {e}")) + } + SystemAction::CheckBackend { backend } => { + let status = chooser::backend_status(exec, root, *backend); + serde_json::to_string_pretty(&status) + .unwrap_or_else(|e| format!("could not serialise backend status: {e}")) + } + SystemAction::InspectInstallation { application } => { + let inspection = chooser::installed_copies(exec, root, application); + serde_json::to_string_pretty(&inspection) + .unwrap_or_else(|e| format!("could not serialise installations: {e}")) + } SystemAction::SnapFind { query } => { require_host_root(root, "find snaps")?; snap::find(exec, query)? diff --git a/installer-rs/crates/phoebus-executor/src/chooser.rs b/installer-rs/crates/phoebus-executor/src/chooser.rs index 5c9ad7b..0007299 100644 --- a/installer-rs/crates/phoebus-executor/src/chooser.rs +++ b/installer-rs/crates/phoebus-executor/src/chooser.rs @@ -403,6 +403,475 @@ pub fn infer_kind(_name: &str) -> PackageKind { PackageKind::Unclassified } +// --------------------------------------------------------------------------- +// Structured, read-only evidence for the AI installation workflow. +// --------------------------------------------------------------------------- + +/// A candidate plus the extra, backend-specific evidence that is only fetched +/// on demand (dependencies, confinement, channels). +#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)] +pub struct CandidateDetail { + #[serde(flatten)] + pub candidate: Candidate, + /// The transitive merge/dependency set, when the backend can report it. + pub dependencies: Vec, + /// Snap confinement (`strict`/`partial`/`none`), when applicable. + #[serde(skip_serializing_if = "Option::is_none")] + pub confinement: Option, + /// Snap channel, when applicable. + #[serde(skip_serializing_if = "Option::is_none")] + pub channel: Option, +} + +/// Whether a lane is installed and ready on the intended system. +#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)] +pub struct BackendStatus { + pub backend: String, + pub available: bool, + /// A bounded, human-readable explanation (never invented). + pub detail: String, +} + +/// One existing installation of an application. +#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)] +pub struct InstalledCopy { + pub backend: String, + pub id: String, + pub version: String, +} + +/// What is already installed for an application, and whether it is duplicated +/// across lanes (which must never be created silently). +#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)] +pub struct InstallationInspection { + pub application: String, + pub copies: Vec, + pub duplicate: bool, +} + +/// Inspect one candidate's metadata, using only what the backend actually +/// reports. A candidate that cannot be resolved is returned as unavailable +/// rather than invented. +pub fn candidate_detail(exec: &Exec, root: &Path, backend: Backend, id: &str) -> CandidateDetail { + let need = Need::new(id); + let mut candidate = resolve_candidates(exec, root, &need) + .into_iter() + .find(|c| c.backend == backend && c.id == id); + let mut dependencies = Vec::new(); + let mut confinement = None; + let mut channel = None; + + match backend { + Backend::PortageSource | Backend::PortageBinary | Backend::PortageVendor => { + if let Ok(out) = exec.runner.execute( + &CommandSpec::new("sys", "inspect candidate dependencies", "emerge") + .args(["--pretend", "--quiet", "--color=n", "--"]) + .arg(id), + ) { + if out.success { + let plan = phoebus_core::effects::parse_emerge_pretend(&out.stdout_lossy()); + dependencies = plan.effects.into_iter().map(|e| e.target).collect(); + } + } + } + Backend::Snap => { + if let Ok(out) = exec.runner.execute( + &CommandSpec::new("sys", "inspect snap candidate", "snap").args([ + "info", + id, + "--color=never", + ]), + ) { + if out.success { + let text = out.stdout_lossy(); + let (version, chan, conf) = crate::snap::parse_info_summary(&text); + if let Some(c) = candidate.as_mut() { + if c.version.is_none() { + c.version = version; + } + } + channel = chan; + confinement = Some(conf.as_str().to_string()); + } + } + } + Backend::Flatpak | Backend::Nix | Backend::AppImage | Backend::CustomEbuild => {} + } + + let candidate = candidate.unwrap_or_else(|| { + let mut c = Candidate::new(backend, id, "(unresolved)"); + c.available = false; + c.notes + .push("this backend could not resolve the candidate from real metadata".into()); + c + }); + + CandidateDetail { + candidate, + dependencies, + confinement, + channel, + } +} + +/// The result of resolving a friendly application name within one lane. +#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)] +pub struct BackendResolution { + pub backend: String, + pub candidates: Vec, + /// Every identifier that matched a friendly name, when it was not itself an + /// exact identifier and more than one candidate matched. A non-empty list + /// means the caller must ask the user which one is intended. + pub ambiguous: Vec, +} + +impl BackendResolution { + pub fn unambiguous(&self) -> Option<&Candidate> { + if self.ambiguous.is_empty() && self.candidates.len() == 1 { + self.candidates.first() + } else { + None + } + } + + pub fn is_ambiguous(&self) -> bool { + !self.ambiguous.is_empty() || self.candidates.len() > 1 + } +} + +/// Resolve an application name within one lane, including friendly names where +/// the lane exposes an authoritative search. Only real metadata is used; an +/// unknown name yields no candidate (never a fabricated one). +pub fn resolve_for_backend( + exec: &Exec, + root: &Path, + backend: Backend, + application: &str, +) -> BackendResolution { + let mut candidates: Vec = Vec::new(); + let mut ambiguous: Vec = Vec::new(); + let exact = |id: &str| id == application; + + match backend { + Backend::Flatpak => { + if crate::exec::find_in_path("flatpak").is_some() { + if let Ok(out) = exec.runner.execute( + &CommandSpec::new("sys", "resolve flatpak name", "flatpak").args([ + "search", + "--columns=application,version", + "--", + application, + ]), + ) { + if out.success { + let mut matches: Vec<(String, String)> = Vec::new(); + for line in out.stdout_lossy().lines() { + let mut cols = line.split_whitespace(); + if let (Some(id), Some(version)) = (cols.next(), cols.next()) { + if id.contains('.') { + matches.push((id.to_string(), version.to_string())); + } + } + } + let exact_matches: Vec<_> = matches + .iter() + .filter(|(id, _)| exact(id)) + .cloned() + .collect(); + if !exact_matches.is_empty() { + for (id, version) in exact_matches { + let mut c = Candidate::new(Backend::Flatpak, id, "flathub"); + c.version = Some(version); + c.verified = true; + c.sandbox = SandboxLevel::Strong; + c.update_reliability = UpdateReliability::Automatic; + candidates.push(c); + } + } else if matches.len() == 1 { + let (id, version) = matches.pop().unwrap(); + let mut c = Candidate::new(Backend::Flatpak, id, "flathub"); + c.version = Some(version); + c.verified = true; + c.sandbox = SandboxLevel::Strong; + c.update_reliability = UpdateReliability::Automatic; + c.notes + .push(format!("matched the friendly name `{application}`")); + candidates.push(c); + } else if matches.len() > 1 { + ambiguous = matches.into_iter().map(|(id, _)| id).collect(); + } + } + } + } + } + Backend::Snap => { + if matches!(crate::snap::status(exec), Ok(s) if s.usable()) { + if let Ok(out) = exec.runner.execute( + &CommandSpec::new("sys", "resolve snap name", "snap").args([ + "find", + "--color=never", + "--", + application, + ]), + ) { + if out.success { + let found = crate::snap::parse_find(&out.stdout_lossy()); + let exact_matches: Vec<_> = + found.iter().filter(|c| exact(&c.name)).cloned().collect(); + if !exact_matches.is_empty() { + for hit in exact_matches { + candidates.push(snap_candidate(hit.name, hit.version, false)); + } + } else if found.len() == 1 { + let hit = &found[0]; + let mut c = + snap_candidate(hit.name.clone(), hit.version.clone(), false); + c.notes + .push(format!("matched the friendly name `{application}`")); + candidates.push(c); + } else if found.len() > 1 { + ambiguous = found.into_iter().map(|c| c.name).collect(); + } + } + } + } + } + Backend::PortageSource | Backend::PortageBinary | Backend::PortageVendor => { + // Portage resolves bare names itself; confirm the atom is real. + if let Ok(out) = exec.runner.execute( + &CommandSpec::new("sys", "resolve portage name", "emerge") + .args(["--pretend", "--quiet", "--color=n", "--"]) + .arg(application), + ) { + if out.success { + let id = parse_pretend_version(&out.stdout_lossy()) + .unwrap_or_else(|| application.to_string()); + candidates.push(portage_candidate( + &id, + backend == Backend::PortageBinary, + &hardware_facts(exec, root), + )); + } + } + } + Backend::Nix => { + if crate::nix::installed(root) && phoebus_core::action::valid_nix_attribute(application) + { + let mut c = Candidate::new(Backend::Nix, application, "nixpkgs (pinned)"); + c.verified = true; + c.update_reliability = UpdateReliability::Automatic; + candidates.push(c); + } + } + Backend::AppImage => { + if let Ok(record) = crate::appimage::info(root, application) { + let mut c = Candidate::new( + Backend::AppImage, + record.name.clone(), + record.provenance.clone(), + ); + c.version = Some(record.version.clone()); + c.verified = true; + c.sandbox = SandboxLevel::None; + c.arch = record.arch.clone(); + candidates.push(c); + } + } + Backend::CustomEbuild => { + let staged = crate::ebuild::list(root); + let matches: Vec<_> = staged + .into_iter() + .filter(|s| s.atom == application || s.package_name() == application) + .collect(); + if matches.len() == 1 { + let s = &matches[0]; + let mut c = Candidate::new( + Backend::CustomEbuild, + s.atom.clone(), + "Phoebus overlay (/var/db/repos/phoebus)", + ); + c.version = Some(s.version.clone()); + candidates.push(c); + } else if matches.len() > 1 { + ambiguous = matches.into_iter().map(|s| s.atom).collect(); + } + } + } + + BackendResolution { + backend: backend.as_str().to_string(), + candidates, + ambiguous, + } +} + +fn snap_candidate(name: String, version: String, classic: bool) -> Candidate { + let mut c = Candidate::new(Backend::Snap, name, "Snap Store"); + c.version = Some(version); + c.verified = true; + c.sandbox = if classic { + SandboxLevel::None + } else { + SandboxLevel::Strong + }; + c.update_reliability = UpdateReliability::Automatic; + c +} + +/// Report whether a lane is present and ready. +pub fn backend_status(exec: &Exec, root: &Path, backend: Backend) -> BackendStatus { + let facts = hardware_facts(exec, root); + let available = facts.backend_available(backend); + let detail = match backend { + Backend::PortageSource | Backend::PortageVendor => { + if crate::exec::find_in_path("emerge").is_some() { + "Portage (emerge) is present".into() + } else { + "emerge is not in PATH".into() + } + } + Backend::PortageBinary => { + if root.join("etc/portage/binrepos.conf").exists() { + "a signed binary host is configured".into() + } else { + "no binhost is configured; source builds would be used".into() + } + } + Backend::Nix => { + if crate::nix::installed(root) { + "the Nix store is present".into() + } else { + "Nix is not installed in this target".into() + } + } + Backend::Flatpak => { + if crate::exec::find_in_path("flatpak").is_some() { + "the flatpak client is present".into() + } else { + "flatpak is not installed".into() + } + } + Backend::Snap => match crate::snap::status(exec) { + Ok(s) => format!( + "snap client present: {}, daemon active: {}, confinement: {}", + s.client_present, + s.daemon_ready, + s.confinement.as_str() + ), + Err(_) => "snapd state could not be determined".into(), + }, + Backend::AppImage => "AppImages can be imported or downloaded locally".into(), + Backend::CustomEbuild => { + if crate::ebuild::list(root).is_empty() { + "no custom ebuilds are staged".into() + } else { + "the Phoebus overlay is present with staged ebuilds".into() + } + } + }; + BackendStatus { + backend: backend.as_str().to_string(), + available, + detail, + } +} + +/// Inspect what is already installed for an application across lanes. Never +/// invents a copy; every entry comes from a real backend inventory. +pub fn installed_copies(exec: &Exec, root: &Path, application: &str) -> InstallationInspection { + let mut copies = Vec::new(); + + // Flatpak. + if crate::exec::find_in_path("flatpak").is_some() { + if let Ok(out) = exec.runner.execute( + &CommandSpec::new("sys", "inspect installed flatpaks", "flatpak").args([ + "list", + "--app", + "--columns=application,version", + ]), + ) { + if out.success { + for line in out.stdout_lossy().lines() { + let mut cols = line.split_whitespace(); + if let (Some(id), Some(version)) = (cols.next(), cols.next()) { + if id == application { + copies.push(InstalledCopy { + backend: Backend::Flatpak.as_str().into(), + id: id.to_string(), + version: version.to_string(), + }); + } + } + } + } + } + } + + // Snap. + if let Ok(entries) = crate::snap::list(exec) { + for entry in entries { + if entry.name == application { + copies.push(InstalledCopy { + backend: Backend::Snap.as_str().into(), + id: entry.name, + version: entry.version, + }); + } + } + } + + // AppImage (managed record). + if let Ok(record) = crate::appimage::info(root, application) { + copies.push(InstalledCopy { + backend: Backend::AppImage.as_str().into(), + id: record.name, + version: record.version, + }); + } + + // Portage (VDB). + if let Some(version) = portage_installed_version(root, application) { + copies.push(InstalledCopy { + backend: Backend::PortageSource.as_str().into(), + id: application.to_string(), + version, + }); + } + + let duplicate = copies.len() > 1; + InstallationInspection { + application: application.to_string(), + copies, + duplicate, + } +} + +/// The installed version of a Portage package from the VDB, if present. +fn portage_installed_version(root: &Path, name: &str) -> Option { + let vdb = root.join("var/db/pkg"); + let (category, package) = match name.split_once('/') { + Some((c, p)) => (Some(c.to_string()), p.to_string()), + None => (None, name.to_string()), + }; + let categories = std::fs::read_dir(&vdb).ok()?; + for category_entry in categories.flatten() { + let category_name = category_entry.file_name().to_string_lossy().to_string(); + if let Some(want) = &category { + if &category_name != want { + continue; + } + } + let pkgs = std::fs::read_dir(category_entry.path()).ok()?; + for pkg in pkgs.flatten() { + let dir = pkg.file_name().to_string_lossy().to_string(); + if let Some(rest) = dir.strip_prefix(&format!("{package}-")) { + return Some(rest.to_string()); + } + } + } + None +} + /// A plain-text inventory of the available lanes, for `sys choose` with no /// request and for diagnostics. pub fn lanes_report(exec: &Exec, root: &Path) -> String { @@ -532,4 +1001,34 @@ mod tests { assert!(report.contains(backend.as_str()), "missing {backend:?}"); } } + + #[test] + fn target_facts_are_read_from_the_target_not_the_host() { + // A binhost configured in one root must not appear in another: the + // host's own configuration must never leak into a target's facts. + let exec = make_exec(RecordingRunner::new()); + let with_binhost = tempfile::tempdir().unwrap(); + std::fs::create_dir_all(with_binhost.path().join("etc/portage")).unwrap(); + std::fs::write(with_binhost.path().join("etc/portage/binrepos.conf"), "x").unwrap(); + let without = tempfile::tempdir().unwrap(); + + let a = hardware_facts(&exec, with_binhost.path()); + let b = hardware_facts(&exec, without.path()); + assert!(a.binhost_available); + assert!(!b.binhost_available); + assert!(a.available_backends.contains(&Backend::PortageBinary)); + assert!(!b.available_backends.contains(&Backend::PortageBinary)); + } + + #[test] + fn installed_copies_reports_duplication_and_versions() { + let runner = RecordingRunner::new(); + runner.set_response("flatpak", ok("org.mozilla.firefox 128\n")); + let exec = make_exec(runner); + let root = tempfile::tempdir().unwrap(); + let inspection = installed_copies(&exec, root.path(), "org.mozilla.firefox"); + assert_eq!(inspection.copies.len(), 1); + assert_eq!(inspection.copies[0].version, "128"); + assert!(!inspection.duplicate); + } } diff --git a/installer-rs/crates/phoebus-executor/src/install.rs b/installer-rs/crates/phoebus-executor/src/install.rs new file mode 100644 index 0000000..06c0ebf --- /dev/null +++ b/installer-rs/crates/phoebus-executor/src/install.rs @@ -0,0 +1,1102 @@ +//! The shared installation workflow. +//! +//! One path is used by ordinary `sys install`, by `sys ask` installation +//! requests, and by explicit backend flags: +//! +//! request -> identify -> evidence -> AI investigation (or explicit/ +//! deterministic selection) -> resolved candidate -> deterministic validation +//! and effect resolution -> review -> approved execution -> verification -> +//! history. +//! +//! The AI only *recommends*. Every recommendation is re-checked against real +//! backend metadata here before it can become a `SystemAction`; the broker then +//! executes it through the same transaction engine as any other action. + +use std::path::Path; + +use phoebus_ai::install::{Evidence, InstallProposal, InstallSession}; +use phoebus_ai::provider::{ModelTransport, ProviderKind, SystemFacts}; +use phoebus_core::action::SystemAction; +use phoebus_core::effects::{EffectKind, EffectSource, PackageEffect, ResolvedPlan}; +use phoebus_core::selection::{Backend, Candidate, Need, PackageKind, Rejected}; + +use crate::error::{ExecError, Result}; +use crate::exec::Exec; +use crate::{actions, chooser}; + +/// A caller-provided question/answer function (terminal prompt in `sys`). +pub type AskFn<'a> = dyn Fn(&str) -> Option + 'a; + +/// What the user asked to install, and the constraints they gave. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct InstallRequest { + pub application: String, + pub kind: Option, + pub gui: bool, + pub requires_sandbox: bool, + pub requires_proprietary: bool, + pub requirements: Vec, + /// An explicit backend constraint (`--flatpak`, `--portage`, ...). + pub backend: Option, +} + +impl InstallRequest { + pub fn new(application: impl Into) -> Self { + Self { + application: application.into(), + kind: None, + gui: false, + requires_sandbox: false, + requires_proprietary: false, + requirements: Vec::new(), + backend: None, + } + } + + pub fn need(&self) -> Need { + Need { + name: self.application.clone(), + kind: self.kind.unwrap_or(PackageKind::Unclassified), + requires_sandbox: self.requires_sandbox, + requires_proprietary: self.requires_proprietary, + gui: self.gui, + requires_features: self.requirements.clone(), + explicit_backend: self.backend, + max_install_mib: None, + } + } +} + +/// How the candidate was chosen. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum InstallSource { + /// The user constrained the backend on the command line. + ExplicitBackend, + /// The connected model investigated and recommended. + AiRecommendation, + /// No model was available; the deterministic selector produced this. + DeterministicFallback, +} + +impl InstallSource { + pub fn as_str(self) -> &'static str { + match self { + InstallSource::ExplicitBackend => "explicit-backend", + InstallSource::AiRecommendation => "ai-recommendation", + InstallSource::DeterministicFallback => "deterministic-fallback", + } + } +} + +/// A fully resolved installation, ready for review and approval. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct ResolvedInstall { + pub request: InstallRequest, + pub candidate: Candidate, + pub action: SystemAction, + /// Concrete Portage effects, or a synthetic effect entry for non-Portage + /// lanes (so the review always states version/download/install size). + pub effects: ResolvedPlan, + pub rationale: Vec, + pub alternatives: Vec, + pub source: InstallSource, + /// Warnings that do not block, e.g. a second copy in another lane. + pub warnings: Vec, + /// A human string describing what will be verified after execution. + pub verification: String, +} + +impl ResolvedInstall { + /// Bind approval to the complete resolved plan. Re-resolving before + /// execution and comparing this value detects a material change. + pub fn approval_digest(&self) -> String { + approval_digest_for(&self.candidate, &self.action, &self.effects) + } + + /// A complete, human-readable review. + pub fn render(&self) -> String { + let c = &self.candidate; + let mut out = String::new(); + out.push_str(&format!( + "Install plan ({} selection):\n", + self.source.as_str() + )); + out.push_str(&format!(" application: {}\n", self.request.application)); + out.push_str(&format!(" backend: {}\n", c.backend.as_str())); + out.push_str(&format!(" candidate: {}\n", c.id)); + out.push_str(&format!( + " version: {}\n", + c.version.as_deref().unwrap_or("(resolved at install time)") + )); + out.push_str(&format!(" source: {}\n", c.provenance)); + out.push_str(&format!( + " integrity: {}\n", + if c.verified { + "verified (signature/hash)" + } else { + "UNVERIFIED — provenance not cryptographic" + } + )); + out.push_str(&format!( + " sandbox: {} wayland: {} desktop: {}\n", + sandbox_str(c.sandbox), + cap_str(c.wayland), + cap_str(c.desktop_integration) + )); + if let Some(mib) = c.download_mib { + out.push_str(&format!(" download: ~{mib} MiB\n")); + } + if let Some(mib) = c.install_mib { + out.push_str(&format!(" on disk: ~{mib} MiB\n")); + } + if let Some(mib) = c.shared_runtime_mib { + out.push_str(&format!(" shared runtime: ~{mib} MiB (if not present)\n")); + } + if !c.permissions.is_empty() { + out.push_str(&format!(" permissions: {}\n", c.permissions.join(", "))); + } + out.push_str("Why:\n"); + for line in &self.rationale { + out.push_str(&format!(" - {line}\n")); + } + if !self.alternatives.is_empty() { + out.push_str("Alternatives considered:\n"); + for r in &self.alternatives { + out.push_str(&format!( + " - {} ({}): {}\n", + r.id, + r.backend.as_str(), + r.reason.explain() + )); + } + } + for warning in &self.warnings { + out.push_str(&format!(" ! {warning}\n")); + } + if self.effects.established && !self.effects.effects.is_empty() { + out.push_str(&self.effects.render()); + } + out.push_str(&format!("Verification: {}\n", self.verification)); + out.push_str(&format!("Approval digest: {}\n", self.approval_digest())); + out + } +} + +fn sandbox_str(level: phoebus_core::selection::SandboxLevel) -> &'static str { + use phoebus_core::selection::SandboxLevel::*; + match level { + None => "none", + Partial => "partial", + Strong => "strong", + } +} + +fn cap_str(cap: phoebus_core::selection::Capability) -> &'static str { + use phoebus_core::selection::Capability::*; + match cap { + No => "no", + Partial => "partial", + Yes => "yes", + } +} + +/// Build the concrete typed action for a candidate. This is the single mapping +/// from a lane to the broker action, so the workflow cannot disagree with the +/// execution path. +pub fn action_for(_exec: &Exec, root: &Path, candidate: &Candidate) -> Result { + match candidate.backend { + Backend::PortageSource | Backend::PortageBinary | Backend::PortageVendor => { + Ok(SystemAction::InstallPackage { + atom: candidate.id.clone(), + }) + } + Backend::Flatpak => Ok(SystemAction::FlatpakInstall { + app_id: candidate.id.clone(), + }), + Backend::Snap => Ok(SystemAction::SnapInstall { + name: candidate.id.clone(), + channel: None, + classic: false, + }), + Backend::Nix => Ok(SystemAction::NixPrepare { + packages: vec![candidate.id.clone()], + }), + Backend::AppImage => Err(ExecError::operation( + "install", + "resolve AppImage", + "an AppImage must be acquired with an explicit pinned URL and SHA-256; \ + use `appimage_acquire` or `appimage import`", + )), + Backend::CustomEbuild => { + let staged = crate::ebuild::staged(root, &candidate.id).ok_or_else(|| { + ExecError::operation( + "install", + "resolve custom ebuild", + format!( + "{} is not staged in the Phoebus overlay; stage it with \ + custom_ebuild_prepare first", + candidate.id + ), + ) + })?; + Ok(SystemAction::CustomEbuildInstall { + atom: staged.atom.clone(), + version: staged.version.clone(), + digest: staged.digest.clone(), + }) + } + } +} + +/// Build a concrete, reviewable effect plan for a candidate. Portage effects +/// come from `emerge --pretend`; other lanes get a single synthetic entry so the +/// review still states the identity, version and size, and the approval digest +/// binds them. +pub fn effects_for( + exec: &Exec, + root: &Path, + candidate: &Candidate, + action: &SystemAction, +) -> Result { + if action_is_portage(action) { + return actions::resolve_effects(exec, action, root); + } + let mut plan = ResolvedPlan { + established: true, + ..Default::default() + }; + plan.effects.push(PackageEffect { + target: candidate.id.clone(), + previous: None, + kind: EffectKind::New, + source: match candidate.backend { + Backend::CustomEbuild | Backend::PortageSource => EffectSource::Source, + _ => EffectSource::Binary, + }, + }); + plan.download_bytes = candidate.download_mib.map(|m| m * 1024 * 1024); + if !candidate.verified { + plan.consequences + .push("provenance cannot be cryptographically verified".into()); + } + plan.recompute_digest(); + Ok(plan) +} + +fn action_is_portage(action: &SystemAction) -> bool { + matches!( + action, + SystemAction::InstallPackage { .. } + | SystemAction::RemovePackage { .. } + | SystemAction::UpdateSystem + ) +} + +/// Bind approval to a candidate, its action and its resolved effects. +pub fn approval_digest_for( + candidate: &Candidate, + action: &SystemAction, + effects: &ResolvedPlan, +) -> String { + use sha2::{Digest, Sha256}; + let mut hasher = Sha256::new(); + hasher.update(candidate.backend.as_str().as_bytes()); + hasher.update(b"\0"); + hasher.update(candidate.id.as_bytes()); + hasher.update(b"\0"); + hasher.update(candidate.version.as_deref().unwrap_or("").as_bytes()); + hasher.update(b"\0"); + hasher.update(serde_json::to_string(action).unwrap_or_default().as_bytes()); + hasher.update(b"\0"); + if effects.established { + hasher.update(effects.digest.as_bytes()); + } else { + hasher.update(b"no-portage-effects"); + } + format!("{:x}", hasher.finalize()) +} + +/// Re-resolve a reviewed installation immediately before execution. Returns the +/// current approval digest; a different value (changed candidate, version, +/// action or effects) must abort and require another review. +pub fn revalidate(exec: &Exec, root: &Path, resolved: &ResolvedInstall) -> Result { + let backend = resolved.candidate.backend; + let resolution = chooser::resolve_for_backend(exec, root, backend, &resolved.candidate.id); + if resolution.is_ambiguous() { + return Err(ExecError::operation( + "install", + "revalidate", + format!( + "the reviewed candidate is now ambiguous: {}", + resolution.ambiguous.join(", ") + ), + )); + } + let current = resolution + .candidates + .iter() + .find(|c| c.id == resolved.candidate.id && c.available) + .ok_or_else(|| { + ExecError::operation( + "install", + "revalidate", + "the reviewed candidate is no longer available from real metadata", + ) + })?; + if current.version != resolved.candidate.version { + return Err(ExecError::operation( + "install", + "revalidate", + format!( + "the candidate version changed ({} -> {})", + resolved.candidate.version.as_deref().unwrap_or("(none)"), + current.version.as_deref().unwrap_or("(none)") + ), + )); + } + let action = action_for(exec, root, current)?; + if action != resolved.action { + return Err(ExecError::operation( + "install", + "revalidate", + "the resolved action changed since it was reviewed", + )); + } + let effects = effects_for(exec, root, current, &action)?; + if effects.established + && resolved.effects.established + && effects.digest != resolved.effects.digest + { + return Err(ExecError::operation( + "install", + "revalidate", + "the resolved package effects changed since they were reviewed", + )); + } + Ok(approval_digest_for(current, &action, &effects)) +} + +/// Independently confirm a proposal against real metadata and turn it into a +/// ready-to-review installation. Returns a bounded finding string on rejection +/// so the AI loop can revise. +pub fn validate_proposal( + exec: &Exec, + root: &Path, + request: &InstallRequest, + proposal: &InstallProposal, +) -> std::result::Result { + proposal.validate_structural()?; + + // The proposal may reference the application by a friendly name; resolve + // both the general candidate set and the specific backend. + let need = request.need(); + let mut candidates = chooser::resolve_candidates(exec, root, &need); + let resolution = + chooser::resolve_for_backend(exec, root, proposal.backend, &proposal.application); + if resolution.is_ambiguous() { + return Err(format!( + "`{}` matches several {} candidates: {}. Ask the user which one is intended.", + proposal.application, + proposal.backend.as_str(), + resolution.ambiguous.join(", ") + )); + } + candidates.extend(resolution.candidates.clone()); + + let candidate = candidates + .into_iter() + .find(|c| c.backend == proposal.backend && c.id == proposal.candidate) + .filter(|c| c.available) + .ok_or_else(|| { + format!( + "no available {} candidate with id `{}` exists for `{}`; use only ids \ + returned by discover_candidates/resolve_for_backend", + proposal.backend.as_str(), + proposal.candidate, + proposal.application + ) + })?; + + let mut rationale = vec![format!("AI: {}", proposal.reason.trim())]; + rationale.extend(proposal.tradeoffs.iter().map(|t| format!("tradeoff: {t}"))); + rationale.extend(proposal.evidence.iter().map(|e| format!("evidence: {e}"))); + + finalize( + exec, + root, + request, + candidate, + rationale, + Vec::new(), + InstallSource::AiRecommendation, + false, + ) + .map_err(|e| e.to_string()) +} + +/// Resolve an installation with the deterministic policy (no model). +pub fn resolve_deterministic( + exec: &Exec, + root: &Path, + request: &InstallRequest, +) -> Result { + let need = request.need(); + let selection = chooser::choose(exec, root, &need)?; + let candidate = selection.chosen.clone(); + let mut rationale = selection.rationale.clone(); + if selection.already_installed { + rationale.insert(0, "already installed through this lane; reusing it".into()); + } + finalize( + exec, + root, + request, + candidate, + rationale, + selection.rejected.clone(), + InstallSource::DeterministicFallback, + false, + ) +} + +/// Resolve an installation constrained to an explicit backend. Never falls back +/// to another lane: if the requested lane cannot satisfy the request, that is +/// explained. +pub fn resolve_explicit( + exec: &Exec, + root: &Path, + request: &InstallRequest, +) -> Result { + let backend = request.backend.ok_or_else(|| { + ExecError::operation( + "install", + "resolve explicit backend", + "no backend was requested", + ) + })?; + let resolution = chooser::resolve_for_backend(exec, root, backend, &request.application); + if resolution.is_ambiguous() { + return Err(ExecError::operation( + "install", + "resolve application", + format!( + "`{}` is ambiguous in the {} lane: {}. Choose one explicitly.", + request.application, + backend.as_str(), + resolution.ambiguous.join(", ") + ), + )); + } + let candidate = resolution + .candidates + .iter() + .find(|c| c.available) + .cloned() + .ok_or_else(|| { + ExecError::operation( + "install", + "resolve application", + format!( + "the {} lane cannot satisfy `{}`; no real candidate was found. \ + Use a different lane explicitly (e.g. --flatpak, --portage) or \ + connect a model to compare options.", + backend.as_str(), + request.application + ), + ) + })?; + finalize( + exec, + root, + request, + candidate, + vec![format!( + "explicit backend `{}` was requested", + backend.as_str() + )], + Vec::new(), + InstallSource::ExplicitBackend, + // An explicit flag is a deliberate user choice; a duplicate is a + // warning, not a hard block. + true, + ) +} + +/// Turn a confirmed candidate into a reviewable plan, including duplicate +/// detection. +#[allow(clippy::too_many_arguments)] +fn finalize( + exec: &Exec, + root: &Path, + request: &InstallRequest, + candidate: Candidate, + rationale: Vec, + alternatives: Vec, + source: InstallSource, + allow_duplicate: bool, +) -> Result { + let inspection = chooser::installed_copies(exec, root, &request.application); + let mut warnings = Vec::new(); + let candidate_is_portage = candidate.backend.is_portage(); + if !inspection.copies.is_empty() { + let summary = inspection + .copies + .iter() + .map(|c| format!("{} {} ({})", c.id, c.version, c.backend)) + .collect::>() + .join(", "); + let same_lane = inspection + .copies + .iter() + .find(|c| c.backend == candidate.backend.as_str()); + if let Some(copy) = same_lane { + if !candidate_is_portage { + return Err(ExecError::operation( + "install", + "check existing install", + format!( + "`{}` is already installed via {} {} ({}); no installation is needed", + request.application, copy.id, copy.version, copy.backend + ), + )); + } + } else if !candidate_is_portage { + // Installed through a different lane: a second copy is a real + // decision, so require the user to make it explicitly. + if !allow_duplicate { + return Err(ExecError::operation( + "install", + "check existing install", + format!( + "`{}` is already installed via {}. Installing it through {} would \ + duplicate it. Ask the user whether to switch lanes or skip.", + request.application, + summary, + candidate.backend.as_str() + ), + )); + } + warnings.push(format!( + "a second copy will be installed; `{}` already exists via {}", + request.application, summary + )); + } + } + + let action = action_for(exec, root, &candidate)?; + let effects = effects_for(exec, root, &candidate, &action)?; + let verification = verification_plan(&candidate); + + Ok(ResolvedInstall { + request: request.clone(), + candidate, + action, + effects, + rationale, + alternatives, + source, + warnings, + verification, + }) +} + +/// The AI session supported by the executor: read-only investigation is run +/// through the same broker as every other action, and `ask` is delegated to the +/// caller (a terminal prompt in `sys`, scripted in tests). +pub struct ExecutorSession<'a> { + pub exec: &'a Exec, + pub root: &'a Path, + pub ask: Option<&'a AskFn<'a>>, +} + +impl InstallSession for ExecutorSession<'_> { + fn investigate(&self, requests: &[SystemAction]) -> Vec { + requests + .iter() + .map(|request| { + let output = match actions::execute(self.exec, request, None, self.root) { + Ok(outcome) => outcome.output, + Err(e) => format!("investigation failed: {e}"), + }; + Evidence { + request: request.describe(), + output, + } + }) + .collect() + } + + fn ask(&self, question: &str) -> Option { + self.ask.and_then(|f| f(question)) + } +} + +/// Configuration for the AI half of the workflow. +pub struct AiInstall<'a> { + pub provider: ProviderKind, + pub endpoint: String, + pub model: String, + pub transport: &'a dyn ModelTransport, + pub limits: phoebus_ai::install::Limits, +} + +/// Run the AI investigation and validate its proposal deterministically. +pub fn resolve_with_ai( + exec: &Exec, + root: &Path, + request: &InstallRequest, + session: &dyn InstallSession, + ai: &AiInstall<'_>, + facts: &SystemFacts, +) -> Result { + let phrase = format!( + "install {}{}", + request.application, + if request.gui { + " (graphical application)" + } else { + "" + } + ); + // The validator both checks the proposal against real metadata and stashes + // the resolved plan, so we do not resolve twice. + let validated: std::cell::RefCell> = std::cell::RefCell::new(None); + let validator = |proposal: &InstallProposal| -> std::result::Result<(), String> { + match validate_proposal(exec, root, request, proposal) { + Ok(resolved) => { + *validated.borrow_mut() = Some(resolved); + Ok(()) + } + Err(finding) => Err(finding), + } + }; + + let outcome = phoebus_ai::install::investigate_install( + ai.provider, + &ai.endpoint, + &ai.model, + facts, + &phrase, + ai.transport, + session, + &validator, + &ai.limits, + ) + .map_err(|e| ExecError::operation("install", "AI investigation", e.to_string()))?; + let _ = outcome; + validated.into_inner().ok_or_else(|| { + ExecError::operation( + "install", + "AI investigation", + "the investigation produced no validated installation", + ) + }) +} + +/// Verify the installed package identity and version after execution. Returns a +/// clear statement of what could and could not be verified; success is never +/// claimed merely because a process exited zero. +pub fn verify_installed(exec: &Exec, root: &Path, resolved: &ResolvedInstall) -> Result { + let c = &resolved.candidate; + match c.backend { + Backend::PortageSource | Backend::PortageBinary | Backend::PortageVendor => { + let inspection = chooser::installed_copies(exec, root, &resolved.request.application); + if let Some(copy) = inspection + .copies + .iter() + .find(|x| x.backend == Backend::PortageSource.as_str()) + { + return Ok(format!( + "verified: {} {} is in the Portage package database", + copy.id, copy.version + )); + } + Err(ExecError::operation( + "install", + "verify install", + format!( + "emerge reported success but `{}` is not in the package database", + resolved.request.application + ), + )) + } + Backend::Flatpak => { + let installed = exec.runner.execute(&phoebus_executor_command( + "flatpak", + &["list", "--app", "--columns=application"], + )); + if installed + .map(|o| o.stdout_lossy().lines().any(|l| l.trim() == c.id)) + .unwrap_or(false) + { + Ok(format!("verified: Flatpak app {} is installed", c.id)) + } else { + Err(ExecError::operation( + "install", + "verify install", + format!("Flatpak did not report {} as installed", c.id), + )) + } + } + Backend::Snap => { + let entries = crate::snap::list(exec)?; + if entries.iter().any(|e| e.name == c.id) { + Ok(format!("verified: snap {} is installed", c.id)) + } else { + Err(ExecError::operation( + "install", + "verify install", + format!("snapd did not report {} as installed", c.id), + )) + } + } + Backend::AppImage => { + crate::appimage::info(root, &c.id)?; + Ok(format!("verified: managed AppImage {} has a record", c.id)) + } + Backend::Nix => Ok(format!( + "the Nix packages were realised; identity is recorded in the transaction, \ + and `nix shell nixpkgs#{}` is the supported way to use them", + c.id + )), + Backend::CustomEbuild => { + if phoebus_core::action::valid_ebuild_atom(&c.id) + && chooser::installed_copies(exec, root, &resolved.request.application) + .copies + .iter() + .any(|x| x.backend == Backend::PortageSource.as_str()) + { + Ok(format!("verified: custom ebuild {} is installed", c.id)) + } else { + Err(ExecError::operation( + "install", + "verify install", + format!("custom ebuild {} is not in the package database", c.id), + )) + } + } + } +} + +/// A small helper so verification can run a plain host command. +fn phoebus_executor_command(program: &str, args: &[&str]) -> crate::command::CommandSpec { + crate::command::CommandSpec::new("install", "verify", program).args(args.iter().copied()) +} + +fn verification_plan(candidate: &Candidate) -> String { + match candidate.backend { + Backend::PortageSource | Backend::PortageBinary | Backend::PortageVendor => { + "the Portage package database will be checked for the package after the merge".into() + } + Backend::Flatpak => "`flatpak list` will be checked for the application id".into(), + Backend::Snap => "`snap list` will be checked for the snap".into(), + Backend::AppImage => "the managed record and file will be checked".into(), + Backend::Nix => { + "the command will be reported; Nix identity is recorded in the transaction".into() + } + Backend::CustomEbuild => { + "the Portage package database will be checked for the custom atom".into() + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::command::{CommandOutput, RecordingRunner}; + use crate::log::Logger; + use phoebus_core::Redactor; + use std::time::Duration; + + fn make_exec(runner: RecordingRunner) -> Exec { + let path = tempfile::tempdir().unwrap().keep(); + let logger = Logger::open(path.join("l.log"), Redactor::new(), false); + Exec::new(Box::new(runner), logger, false, path.join("root"), path) + } + + fn ok(stdout: &str) -> CommandOutput { + CommandOutput { + status: 0, + success: true, + stdout: stdout.as_bytes().to_vec(), + stderr: Vec::new(), + duration: Duration::from_millis(1), + } + } + + #[test] + fn explicit_portage_produces_an_install_action() { + let runner = RecordingRunner::new(); + runner.set_response( + "emerge", + ok("Calculating dependencies... done!\n[ebuild N ] app-editors/vim-9.1.0\n"), + ); + let exec = make_exec(runner); + let root = tempfile::tempdir().unwrap(); + let mut request = InstallRequest::new("vim"); + request.backend = Some(Backend::PortageSource); + // Use the host-root path so the canned `emerge` response is reached + // directly (an alternate root would use `chroot`). + let resolved = resolve_explicit(&exec, Path::new("/"), &request).unwrap(); + assert_eq!(resolved.source, InstallSource::ExplicitBackend); + assert!(matches!( + resolved.action, + SystemAction::InstallPackage { .. } + )); + let _ = root; + } + + #[test] + fn explicit_backend_without_a_candidate_never_falls_back() { + // Snap daemon is not running in the recording runner (status fails to + // become usable), so the Snap lane cannot satisfy the request. + let runner = RecordingRunner::new(); + let exec = make_exec(runner); + let root = tempfile::tempdir().unwrap(); + let mut request = InstallRequest::new("thunderbird"); + request.backend = Some(Backend::Snap); + let err = resolve_explicit(&exec, root.path(), &request).unwrap_err(); + assert!(err.to_string().contains("cannot satisfy"), "{err}"); + assert!(err.to_string().contains("snap")); + } + + #[test] + fn validate_proposal_rejects_a_fabricated_candidate() { + let runner = RecordingRunner::new(); + runner.fail("emerge", "no such package"); + runner.fail("flatpak", "not found"); + let exec = make_exec(runner); + let root = tempfile::tempdir().unwrap(); + let request = InstallRequest::new("firefox"); + let proposal = InstallProposal { + application: "firefox".into(), + backend: Backend::Flatpak, + candidate: "org.mozilla.firefox".into(), + version: None, + reason: "x".into(), + tradeoffs: vec![], + evidence: vec![], + }; + let err = validate_proposal(&exec, root.path(), &request, &proposal).unwrap_err(); + assert!(err.contains("no available"), "{err}"); + } + + #[test] + fn validation_detects_an_ambiguous_friendly_name() { + let runner = RecordingRunner::new(); + runner.set_response( + "flatpak", + ok("org.mozilla.firefox 128 stable\norg.mozilla.firefoxpwa 1.0 stable\n"), + ); + let exec = make_exec(runner); + let root = tempfile::tempdir().unwrap(); + let request = InstallRequest::new("firefox"); + let proposal = InstallProposal { + application: "firefox".into(), + backend: Backend::Flatpak, + candidate: "org.mozilla.firefox".into(), + version: None, + reason: "x".into(), + tradeoffs: vec![], + evidence: vec![], + }; + let err = validate_proposal(&exec, root.path(), &request, &proposal).unwrap_err(); + assert!(err.contains("matches several"), "{err}"); + } + + #[test] + fn the_action_mapping_never_invents_an_appimage_acquire() { + let exec = make_exec(RecordingRunner::new()); + let root = tempfile::tempdir().unwrap(); + let mut c = Candidate::new(Backend::AppImage, "tool", "vendor"); + c.available = true; + let err = action_for(&exec, root.path(), &c).unwrap_err(); + assert!(err.to_string().contains("pinned URL"), "{err}"); + } + + // --- args-aware runner so different subcommands can be simulated -------- + + struct ArgRunner { + recorded: std::sync::Mutex>, + /// Flatpak search version, mutable so a metadata change can be tested. + version: std::sync::Arc, + /// Whether `flatpak list` reports the app as installed. + installed: bool, + } + + impl ArgRunner { + fn new(version: std::sync::Arc, installed: bool) -> Self { + Self { + recorded: std::sync::Mutex::new(Vec::new()), + version, + installed, + } + } + } + + impl crate::command::ProcessRunner for ArgRunner { + fn execute(&self, spec: &crate::command::CommandSpec) -> Result { + self.recorded.lock().unwrap().push(spec.clone()); + let ok = |s: String| CommandOutput { + status: 0, + success: true, + stdout: s.into_bytes(), + stderr: Vec::new(), + duration: Duration::from_millis(1), + }; + let fail = || CommandOutput { + status: 1, + success: false, + stdout: Vec::new(), + stderr: b"no".to_vec(), + duration: Duration::from_millis(1), + }; + let version = self.version.load(std::sync::atomic::Ordering::SeqCst); + match spec.program.as_str() { + "flatpak" if spec.args.iter().any(|a| a == "search") => { + Ok(ok(format!("org.mozilla.firefox {version}\n"))) + } + "flatpak" if spec.args.iter().any(|a| a == "list") => Ok(ok(if self.installed { + format!("org.mozilla.firefox {version}\n") + } else { + String::new() + })), + "emerge" => Ok(fail()), + _ => Ok(ok(String::new())), + } + } + } + + fn arg_exec(version: std::sync::Arc, installed: bool) -> Exec { + let path = tempfile::tempdir().unwrap().keep(); + let logger = Logger::open(path.join("l.log"), Redactor::new(), false); + Exec::new( + Box::new(ArgRunner::new(version, installed)), + logger, + false, + path.join("root"), + path, + ) + } + + fn facts() -> SystemFacts { + SystemFacts { + arch: "x86_64".into(), + cpu_cores: 8, + memory_mib: 16384, + ..Default::default() + } + } + + struct NoAsk; + impl phoebus_ai::install::InstallSession for NoAsk { + fn investigate(&self, requests: &[SystemAction]) -> Vec { + requests + .iter() + .map(|r| Evidence { + request: r.describe(), + output: "[]".into(), + }) + .collect() + } + fn ask(&self, _q: &str) -> Option { + None + } + } + + fn ai<'a>(transport: &'a dyn ModelTransport) -> AiInstall<'a> { + AiInstall { + provider: ProviderKind::Local, + endpoint: "http://127.0.0.1:11434/v1/chat/completions".into(), + model: "m".into(), + transport, + limits: phoebus_ai::install::Limits::default(), + } + } + + fn proposal(candidate: &str) -> String { + phoebus_ai::provider::chat_response(&format!( + r#"{{"version":2,"kind":"propose","proposal":{{"application":"firefox","backend":"flatpak","candidate":"{candidate}","reason":"x"}}}}"# + )) + } + + #[test] + fn ai_unqualified_install_is_confirmed_by_the_resolver() { + let version = std::sync::Arc::new(std::sync::atomic::AtomicU32::new(128)); + let exec = arg_exec(version, false); + let root = tempfile::tempdir().unwrap(); + let request = InstallRequest::new("firefox"); + let transport = + phoebus_ai::provider::ScriptedTransport::new(vec![proposal("org.mozilla.firefox")]); + let resolved = resolve_with_ai( + &exec, + root.path(), + &request, + &NoAsk, + &ai(&transport), + &facts(), + ) + .unwrap(); + assert_eq!(resolved.candidate.id, "org.mozilla.firefox"); + assert_eq!(resolved.source, InstallSource::AiRecommendation); + assert!(matches!( + resolved.action, + SystemAction::FlatpakInstall { .. } + )); + } + + #[test] + fn a_fabricated_candidate_is_rejected_and_the_model_revises() { + let version = std::sync::Arc::new(std::sync::atomic::AtomicU32::new(128)); + let exec = arg_exec(version, false); + let root = tempfile::tempdir().unwrap(); + let request = InstallRequest::new("firefox"); + let transport = phoebus_ai::provider::ScriptedTransport::new(vec![ + proposal("org.evil.Firefox"), + proposal("org.mozilla.firefox"), + ]); + let resolved = resolve_with_ai( + &exec, + root.path(), + &request, + &NoAsk, + &ai(&transport), + &facts(), + ) + .unwrap(); + assert_eq!(resolved.candidate.id, "org.mozilla.firefox"); + // The second request carries the resolver's finding. + assert!(transport.requests()[1].contains("no available")); + } + + #[test] + fn a_changed_candidate_version_invalidates_the_review() { + let version = std::sync::Arc::new(std::sync::atomic::AtomicU32::new(128)); + let exec = arg_exec(version.clone(), false); + let root = tempfile::tempdir().unwrap(); + let mut request = InstallRequest::new("firefox"); + request.backend = Some(Backend::Flatpak); + let resolved = resolve_explicit(&exec, root.path(), &request).unwrap(); + assert_eq!(resolved.candidate.version.as_deref(), Some("128")); + // Same metadata -> the reviewed digest revalidates. + assert_eq!( + revalidate(&exec, root.path(), &resolved).unwrap(), + resolved.approval_digest() + ); + // The remote publishes a new version: the approval is invalidated. + version.store(129, std::sync::atomic::Ordering::SeqCst); + let err = revalidate(&exec, root.path(), &resolved).unwrap_err(); + assert!(err.to_string().contains("version changed"), "{err}"); + } + + #[test] + fn an_already_installed_app_in_the_same_lane_is_not_reinstalled() { + let version = std::sync::Arc::new(std::sync::atomic::AtomicU32::new(128)); + let exec = arg_exec(version, true); + let root = tempfile::tempdir().unwrap(); + let mut request = InstallRequest::new("org.mozilla.firefox"); + request.backend = Some(Backend::Flatpak); + let err = resolve_explicit(&exec, root.path(), &request).unwrap_err(); + assert!(err.to_string().contains("already installed"), "{err}"); + } +} diff --git a/installer-rs/crates/phoebus-executor/src/lib.rs b/installer-rs/crates/phoebus-executor/src/lib.rs index d6a3e1e..c30ae93 100644 --- a/installer-rs/crates/phoebus-executor/src/lib.rs +++ b/installer-rs/crates/phoebus-executor/src/lib.rs @@ -17,6 +17,7 @@ pub mod ebuild; pub mod encryption; pub mod error; pub mod exec; +pub mod install; pub mod kernel; pub mod live_nvidia; pub mod log; diff --git a/installer-rs/crates/phoebus-executor/src/transaction.rs b/installer-rs/crates/phoebus-executor/src/transaction.rs index 9261530..6da0392 100644 --- a/installer-rs/crates/phoebus-executor/src/transaction.rs +++ b/installer-rs/crates/phoebus-executor/src/transaction.rs @@ -2,7 +2,7 @@ use std::path::{Path, PathBuf}; -use phoebus_core::transaction::{TransactionLog, TransactionRecord}; +use phoebus_core::transaction::{TransactionLog, TransactionOutcome, TransactionRecord}; use crate::error::{ExecError, Result}; use crate::exec::Exec; @@ -25,6 +25,56 @@ pub fn append(exec: &Exec, root: &Path, record: TransactionRecord) -> Result<()> Ok(()) } +fn now_id() -> u64 { + use std::time::{SystemTime, UNIX_EPOCH}; + SystemTime::now() + .duration_since(UNIX_EPOCH) + .map(|d| d.as_nanos() as u64) + .unwrap_or(0) + .max(1) +} + +/// Record a transaction **before** the mutation starts. Returns its id; a +/// record that never reaches [`finish`] is an interrupted operation, not a +/// success. +pub fn begin(exec: &Exec, root: &Path, mut record: TransactionRecord) -> Result { + let id = if record.id != 0 { record.id } else { now_id() }; + record.id = id; + if record.result.trim().is_empty() { + record.result = "in progress".into(); + } + append(exec, root, record)?; + Ok(id) +} + +/// Complete a transaction begun with [`begin`], preserving the same record so +/// the history shows one entry per operation. +pub fn finish( + exec: &Exec, + root: &Path, + id: u64, + result: impl Into, + snapshot: Option, + outcomes: Vec, +) -> Result<()> { + let mut log = read(root)?; + let record = log.records.iter_mut().find(|r| r.id == id).ok_or_else(|| { + ExecError::operation( + "transaction", + "finish", + "no in-progress transaction with that id", + ) + })?; + record.result = result.into(); + if snapshot.is_some() { + record.snapshot = snapshot; + } + record.outcomes = outcomes; + log.save(&path(root)).map_err(ExecError::Core)?; + exec.logger.info("updated transaction"); + Ok(()) +} + #[cfg(test)] mod tests { use super::*; @@ -58,4 +108,91 @@ mod tests { assert_eq!(log.records.len(), 1); assert_eq!(log.records[0].origin, "sys"); } + + #[test] + fn begin_records_in_progress_and_finish_updates_the_same_record() { + let path = tempfile::tempdir().unwrap().keep(); + let logger = Logger::open(path.join("l.log"), Redactor::new(), false); + let exec = Exec::new( + Box::new(RecordingRunner::new()), + logger, + false, + path.join("root"), + path, + ); + let root = Path::new(&exec.root); + let id = begin( + &exec, + root, + TransactionRecord { + origin: "sys".into(), + summary: "install firefox".into(), + result: String::new(), + ..Default::default() + }, + ) + .unwrap(); + // Before finish, the record is visibly in progress. + let log = read(root).unwrap(); + assert_eq!(log.records.len(), 1); + assert_eq!(log.records[0].result, "in progress"); + assert_eq!(log.records[0].id, id); + + finish( + &exec, + root, + id, + "ok", + None, + vec![TransactionOutcome::completed("install firefox")], + ) + .unwrap(); + let log = read(root).unwrap(); + // Still one record, now complete. + assert_eq!(log.records.len(), 1); + assert_eq!(log.records[0].result, "ok"); + assert_eq!(log.records[0].outcome_counts(), (1, 0, 0)); + } + + #[test] + fn a_failed_operation_is_recorded_truthfully() { + let path = tempfile::tempdir().unwrap().keep(); + let logger = Logger::open(path.join("l.log"), Redactor::new(), false); + let exec = Exec::new( + Box::new(RecordingRunner::new()), + logger, + false, + path.join("root"), + path, + ); + let root = Path::new(&exec.root); + let id = begin( + &exec, + root, + TransactionRecord { + origin: "sys".into(), + summary: "install firefox".into(), + result: String::new(), + ..Default::default() + }, + ) + .unwrap(); + finish( + &exec, + root, + id, + "failed: network unreachable", + None, + vec![TransactionOutcome::failed( + "install firefox", + "network unreachable", + )], + ) + .unwrap(); + let log = read(root).unwrap(); + assert_eq!(log.records.len(), 1); + assert!(log.records[0].result.starts_with("failed")); + assert_eq!(log.records[0].outcome_counts(), (0, 1, 0)); + assert!(log.render().contains("Failed")); + } } diff --git a/installer-rs/crates/phoebus-installer/src/bin/sys.rs b/installer-rs/crates/phoebus-installer/src/bin/sys.rs index 6b620a1..271a8df 100644 --- a/installer-rs/crates/phoebus-installer/src/bin/sys.rs +++ b/installer-rs/crates/phoebus-installer/src/bin/sys.rs @@ -13,16 +13,25 @@ use clap::Parser; use phoebus_ai::assistant::{complete_plan, AssistantPlan}; use phoebus_ai::provider::{ModelTransport, ProviderKind, SystemFacts}; use phoebus_core::action::{parse_action, parse_natural, SystemAction}; +use phoebus_core::selection::Backend; use phoebus_core::transaction::{TransactionOutcome, TransactionRecord}; use phoebus_core::{AiBackend, InstallConfig, Redactor}; +use phoebus_executor::install::{self, AiInstall, ExecutorSession, InstallRequest}; use phoebus_executor::opencode_client::ExecOpenCodeTransport; use phoebus_executor::{ - actions, authorize, probe, transaction, AutoConfirm, Confirmation, DestructiveAuthorization, - Exec, Logger, RealRunner, Result, + actions, authorize, chooser, probe, transaction, AutoConfirm, Confirmation, + DestructiveAuthorization, Exec, Logger, RealRunner, Result, }; #[derive(Parser, Debug)] -#[command(name = "sys", about = "Phoebus system interface", version)] +#[command( + name = "sys", + about = "Phoebus system interface", + version, + group(clap::ArgGroup::new("backend").args([ + "portage", "flatpak", "nix", "snap", "appimage", "ebuild" + ]).multiple(false)) +)] struct Cli { /// Natural-language instruction, e.g. `enable sshd`. text: Vec, @@ -43,6 +52,30 @@ struct Cli { #[arg(long, default_value = "/")] root: PathBuf, + /// Install through Portage only (no model needed). + #[arg(long)] + portage: bool, + + /// Install from Flatpak only (no model needed). + #[arg(long)] + flatpak: bool, + + /// Install from Nix only (no model needed). + #[arg(long)] + nix: bool, + + /// Install from Snap only (no model needed). + #[arg(long)] + snap: bool, + + /// Install a managed AppImage only (no model needed). + #[arg(long)] + appimage: bool, + + /// Build and install a staged custom ebuild only (no model needed). + #[arg(long)] + ebuild: bool, + /// AI provider for `sys ask`: deepseek, openai, or local. #[arg(long, value_name = "PROVIDER")] ai_provider: Option, @@ -180,6 +213,21 @@ fn run() -> std::result::Result<(), Box> { return run_ask(&cli, &exec, &instruction); } + // `sys install ` is AI-first: a connected model investigates + // and recommends, while an explicit backend flag is deterministic and needs + // no model. Both share `phoebus_executor::install`. + let backend = backend_flag(&cli); + if let Some(application) = parse_install_text(&cli.text.join(" ")) { + return run_install(&cli, &exec, &application, backend); + } + if backend.is_some() { + return Err( + "--portage/--flatpak/--nix/--snap/--appimage/--ebuild only apply to \ + `sys install `" + .into(), + ); + } + let action = if let Some(json) = &cli.action { parse_action(json)? } else if let Some(path) = &cli.action_file { @@ -251,6 +299,7 @@ fn run() -> std::result::Result<(), Box> { if action.is_mutating() { let described = action.describe(); let record = TransactionRecord { + id: 0, created_unix: now_unix(), origin: "sys".into(), summary: described.clone(), @@ -265,14 +314,376 @@ fn run() -> std::result::Result<(), Box> { Ok(()) } +/// A caller-provided question/answer function for the AI install loop. +type AskFn = dyn Fn(&str) -> Option; + +/// Map the explicit backend flags to a lane. The clap arg group forbids more +/// than one, so at most one is set. +fn backend_flag(cli: &Cli) -> Option { + if cli.portage { + Some(Backend::PortageSource) + } else if cli.flatpak { + Some(Backend::Flatpak) + } else if cli.nix { + Some(Backend::Nix) + } else if cli.snap { + Some(Backend::Snap) + } else if cli.appimage { + Some(Backend::AppImage) + } else if cli.ebuild { + Some(Backend::CustomEbuild) + } else { + None + } +} + +/// Parse `install ` / `add `. Option-like operands +/// are left to the deterministic parser so `install --color=n` is still +/// rejected as before. +fn parse_install_text(text: &str) -> Option { + let trimmed = text.trim(); + let lower = trimmed.to_ascii_lowercase(); + for prefix in ["install ", "add "] { + if lower.starts_with(prefix) { + let app = trimmed[prefix.len()..].trim(); + if !app.is_empty() && !app.contains(char::is_whitespace) && !app.starts_with('-') { + return Some(app.to_string()); + } + } + } + None +} + +/// Load the installed system's configuration instead of assuming defaults. +/// Distinguishes the real target from the development host (the root is the +/// target; nothing here reads the host's own configuration). +fn load_installed_config(root: &Path) -> InstallConfig { + let path = root.join("etc/phoebus/install.toml"); + std::fs::read_to_string(&path) + .ok() + .and_then(|text| InstallConfig::from_toml(&text).ok()) + .unwrap_or_default() +} + +/// A bounded asker for questions about user intent. Disabled under `--yes` or +/// when stdin is not a terminal: the AI loop is then told to proceed with a +/// conservative assumption. +fn install_asker(cli: &Cli) -> Option> { + use std::io::IsTerminal; + if cli.yes || !std::io::stdin().is_terminal() { + return None; + } + Some(Box::new(|question: &str| { + println!("\nThe assistant needs to know: {question}"); + eprint!("> "); + use std::io::Write; + std::io::stdout().flush().ok(); + let mut line = String::new(); + match std::io::stdin().read_line(&mut line) { + Ok(n) if n > 0 => { + let t = line.trim(); + if t.is_empty() { + None + } else { + Some(t.to_string()) + } + } + _ => None, + } + })) +} + +/// Explain that an unqualified install needs a model, and show the +/// deterministic candidate selection without installing it. +fn print_install_offer(cli: &Cli, exec: &Exec, application: &str) { + let need = InstallRequest::new(application).need(); + match chooser::choose(exec, &cli.root, &need) { + Ok(selection) => println!("{}", selection.render()), + Err(e) => eprintln!("sys: the deterministic selector also found no candidate: {e}"), + } + eprintln!(); + eprintln!("No connected model is available for an unqualified install, so Phoebus will"); + eprintln!("not choose a lane for you. Install explicitly, for example:"); + eprintln!(" sys install {application} --flatpak"); + eprintln!(" sys install {application} --portage"); + eprintln!(" sys install {application} --nix"); + eprintln!(" sys install {application} --snap"); + eprintln!(" sys install {application} --appimage"); + eprintln!(" sys install {application} --ebuild"); +} + +/// `sys install `: the shared installation workflow. +fn run_install( + cli: &Cli, + exec: &Exec, + application: &str, + backend: Option, +) -> std::result::Result<(), Box> { + let mut request = InstallRequest::new(application); + request.backend = backend; + + // An explicit backend is deterministic and works without a model. + if backend.is_some() { + let resolved = install::resolve_explicit(exec, &cli.root, &request)?; + return execute_resolved(cli, exec, resolved); + } + + // Unqualified: the configured model investigates and recommends. A + // provider failure never becomes permission to install through a lane. + let conf = load_installed_ai_config(&cli.root); + let ai_backend = resolve_backend(cli, conf.as_ref()); + let facts = gather_facts(exec); + let (provider, endpoint, model); + let transport: Box; + + match ai_backend { + AiBackend::OpenCode => { + let server = cli + .opencode_server + .clone() + .or_else(|| std::env::var("PHOEBUS_OPENCODE_SERVER").ok()) + .or_else(|| conf.as_ref().map(|c| c.opencode_server.clone())) + .unwrap_or_default(); + let opencode_provider = cli + .opencode_provider + .clone() + .or_else(|| std::env::var("PHOEBUS_OPENCODE_PROVIDER").ok()) + .or_else(|| conf.as_ref().map(|c| c.opencode_provider.clone())) + .unwrap_or_default(); + let opencode_model = cli + .opencode_model + .clone() + .or_else(|| std::env::var("PHOEBUS_OPENCODE_MODEL").ok()) + .or_else(|| conf.as_ref().map(|c| c.opencode_model.clone())) + .unwrap_or_default(); + if server.trim().is_empty() + || opencode_provider.trim().is_empty() + || opencode_model.trim().is_empty() + { + print_install_offer(cli, exec, application); + return Err( + "OpenCode needs --opencode-server, --opencode-provider and --opencode-model" + .into(), + ); + } + let password = match &cli.opencode_password_file { + Some(path) => Some(phoebus_executor::ai::load_api_key(path)?), + None => None, + }; + provider = ProviderKind::Local; + endpoint = server; + model = opencode_model; + transport = Box::new( + ExecOpenCodeTransport::new( + exec, + endpoint.clone(), + opencode_provider, + model.clone(), + ) + .with_auth(password), + ); + } + AiBackend::Direct => { + provider = resolve_provider(cli, conf.as_ref()); + if provider == ProviderKind::None { + print_install_offer(cli, exec, application); + return Err("no AI provider configured for an unqualified install".into()); + } + let key = match api_key_file(cli) { + Some(path) => Some(phoebus_executor::ai::load_api_key(&path)?), + None => None, + }; + if provider.requires_key() && key.is_none() { + print_install_offer(cli, exec, application); + return Err(format!( + "provider `{}` requires --ai-api-key-file (mode 0600)", + provider.as_str() + ) + .into()); + } + endpoint = resolve_endpoint(cli, provider, conf.as_ref()); + model = resolve_model(cli, conf.as_ref()); + let direct = phoebus_executor::ai::CurlTransport::new(exec, key); + transport = if cli.no_sandbox { + Box::new(direct) + } else { + Box::new(direct.sandboxed()) + }; + } + } + + eprintln!( + "Investigating `{application}` with {} (bounded, read-only evidence only)...", + provider.as_str() + ); + let ai = AiInstall { + provider, + endpoint, + model, + transport: transport.as_ref(), + limits: phoebus_ai::install::Limits::default(), + }; + let asker = install_asker(cli); + let session = ExecutorSession { + exec, + root: &cli.root, + ask: asker.as_deref(), + }; + let resolved = match install::resolve_with_ai(exec, &cli.root, &request, &session, &ai, &facts) + { + Ok(resolved) => resolved, + Err(e) => { + // The model failed: offer the deterministic path and stop; do not + // install through any backend. + print_install_offer(cli, exec, application); + return Err(format!("the AI investigation did not produce a plan: {e}").into()); + } + }; + execute_resolved(cli, exec, resolved) +} + +/// Present, approve, execute, verify and record a resolved installation. This +/// is the single execution path for AI-, explicit- and deterministic-selected +/// installs. +fn execute_resolved( + cli: &Cli, + exec: &Exec, + resolved: install::ResolvedInstall, +) -> std::result::Result<(), Box> { + println!("{}", resolved.render()); + + if effective_uid() != 0 { + return Err(format!( + "installing `{}` requires root; run `sudo sys install {}`", + resolved.request.application, resolved.request.application + ) + .into()); + } + let confirmation = SysConfirm { + action: resolved.action.clone(), + assume_yes: cli.yes, + }; + let auth = authorize(&confirmation, &resolved.render(), "install")?; + + // Bind approval to the reviewed plan and revalidate before any mutation. + let current = match install::revalidate(exec, &cli.root, &resolved) { + Ok(current) => current, + Err(e) => { + return Err( + format!("the reviewed plan changed before execution ({e}); review again").into(), + ) + } + }; + if current != resolved.approval_digest() { + return Err( + "the reviewed plan changed materially before execution; re-run and review again".into(), + ); + } + + let described = format!( + "install {} via {} ({})", + resolved.request.application, + resolved.candidate.backend.as_str(), + resolved.source.as_str() + ); + // Record before mutation: an interrupted run leaves a visible in-progress + // record rather than a missing one. + let record = TransactionRecord { + id: 0, + created_unix: now_unix(), + origin: "sys".into(), + summary: described.clone(), + actions: vec![described.clone()], + result: "in progress".into(), + snapshot: None, + digest: Some(resolved.approval_digest()), + outcomes: Vec::new(), + }; + let id = transaction::begin(exec, &cli.root, record)?; + + let outcome = match actions::execute(exec, &resolved.action, Some(&auth), &cli.root) { + Ok(outcome) => outcome, + Err(e) => { + let detail = e.to_string(); + let _ = transaction::finish( + exec, + &cli.root, + id, + format!("failed: {detail}"), + None, + vec![TransactionOutcome::failed( + described.clone(), + detail.clone(), + )], + ); + return Err(format!("installation failed: {detail}").into()); + } + }; + if let Some(snapshot) = &outcome.snapshot { + println!("protective snapshot: {snapshot}"); + } + println!("{}", outcome.output); + + match install::verify_installed(exec, &cli.root, &resolved) { + Ok(verification) => { + println!("{verification}"); + transaction::finish( + exec, + &cli.root, + id, + "ok", + outcome.snapshot.clone(), + vec![TransactionOutcome::completed(described.clone())], + )?; + Ok(()) + } + Err(e) => { + let detail = e.to_string(); + transaction::finish( + exec, + &cli.root, + id, + format!("verify failed: {detail}"), + outcome.snapshot.clone(), + vec![TransactionOutcome::completed(described.clone())], + )?; + Err(format!("the install command completed but verification failed: {detail}").into()) + } + } +} + /// Bounded system facts for the assistant: hardware, selected profile and /// measured compile times. No personal files, credentials or command history. fn gather_facts(exec: &Exec) -> SystemFacts { - let config = InstallConfig::default(); + let config = load_installed_config(&exec.root); let hardware = probe::probe_hardware(exec.runner.as_ref()); let history = phoebus_core::load_history(&exec.root.join("var/lib/phoebus/compile-times.tsv")); let binhost = exec.root.join("etc/portage/binrepos.conf").exists(); - SystemFacts::from_system(&config, &hardware, &history, binhost, None) + let mut facts = SystemFacts::from_system(&config, &hardware, &history, binhost, None); + + // Add bounded, read-only environment facts beyond the static config: + // real free space, Wayland, the lanes that are actually usable, saved + // preferences and recovery capability. These are the same facts the + // deterministic selector uses, so the AI and the resolver agree. + let hw = chooser::hardware_facts(exec, &exec.root); + facts.storage_free_mib = hw.storage_free_mib; + facts.wayland = hw.wayland; + facts.available_backends = hw + .available_backends + .iter() + .map(|b| b.as_str().to_string()) + .collect(); + let prefs = chooser::load_preferences(&exec.root); + facts.saved_preferences = prefs + .per_app + .iter() + .map(|(app, backend)| (app.clone(), backend.as_str().to_string())) + .collect(); + facts.recovery_snapshots = exec + .root + .join(phoebus_executor::snapshot::SNAPSHOT_DIR) + .is_dir(); + facts } fn load_installed_ai_config(root: &Path) -> Option { @@ -366,6 +777,12 @@ fn run_ask( exec: &Exec, instruction: &str, ) -> std::result::Result<(), Box> { + // An installation request through `sys ask` uses the same shared workflow + // (AI investigation + deterministic validation) as `sys install`. + if let Some(application) = parse_install_text(instruction) { + return run_install(cli, exec, &application, backend_flag(cli)); + } + let facts = gather_facts(exec); let conf = load_installed_ai_config(&cli.root); let backend = resolve_backend(cli, conf.as_ref()); @@ -536,6 +953,7 @@ fn run_ask( Some((action, detail)) => format!("failed: {action}: {detail}"), }; let record = TransactionRecord { + id: 0, created_unix: now_unix(), origin: "assistant".into(), summary: plan.summary.clone(), diff --git a/installer-rs/crates/phoebus-installer/src/orchestrate.rs b/installer-rs/crates/phoebus-installer/src/orchestrate.rs index 89e1161..b6af897 100644 --- a/installer-rs/crates/phoebus-installer/src/orchestrate.rs +++ b/installer-rs/crates/phoebus-installer/src/orchestrate.rs @@ -736,6 +736,16 @@ impl Installer { } } + // 2b. Persist the non-secret installation configuration so the + // installed `sys` loads the real settings (desktop, filesystem, + // package policy, groups) instead of assuming defaults. There are no + // secrets in `InstallConfig`; passphrases are handled separately. + if let Ok(toml_str) = self.config.to_toml_string() { + self.exec + .target() + .write("etc/phoebus/install.toml", toml_str)?; + } + // 3. Rewrite the desktop entry point last so it cannot be shadowed by an // earlier stage; a no-op for non-desktop profiles. desktop::write_session_script(&self.exec, &self.config)?; diff --git a/installer-rs/crates/phoebus-installer/tests/sys_cli.rs b/installer-rs/crates/phoebus-installer/tests/sys_cli.rs index 2c56019..a43824a 100644 --- a/installer-rs/crates/phoebus-installer/tests/sys_cli.rs +++ b/installer-rs/crates/phoebus-installer/tests/sys_cli.rs @@ -151,6 +151,110 @@ fn effective_uid_is_root() -> bool { .unwrap_or(false) } +#[test] +fn conflicting_backend_flags_are_rejected_by_the_cli() { + let out = sys() + .args(["--flatpak", "--nix", "install", "some-app"]) + .output() + .expect("run sys"); + assert!(!out.status.success()); + let stderr = String::from_utf8_lossy(&out.stderr); + assert!( + stderr.contains("cannot be used with") + || stderr.contains("conflict") + || stderr.contains("not allowed"), + "stderr: {stderr}" + ); +} + +#[test] +fn a_backend_flag_without_an_install_is_refused() { + let out = sys() + .args(["--flatpak", "history"]) + .output() + .expect("run sys"); + assert!(!out.status.success()); + let stderr = String::from_utf8_lossy(&out.stderr); + assert!(stderr.contains("only apply to"), "stderr: {stderr}"); +} + +#[test] +fn an_explicit_backend_never_falls_back_to_another_lane() { + // No Portage on this host, so an explicit `--portage` install must fail + // with an explanation and must not try Flatpak/snap/anything else. + if effective_uid_is_root() { + return; + } + let root = tempfile::tempdir().expect("temp root"); + let empty = tempfile::tempdir().expect("empty PATH"); + let out = sys() + .env("PATH", empty.path()) + .arg("--root") + .arg(root.path()) + .args(["install", "some-app", "--portage"]) + .output() + .expect("run sys"); + assert!(!out.status.success()); + let stderr = String::from_utf8_lossy(&out.stderr); + assert!( + stderr.contains("cannot satisfy") || stderr.contains("no real candidate"), + "stderr: {stderr}" + ); +} + +#[test] +fn an_unqualified_install_without_a_model_offers_options_and_installs_nothing() { + if effective_uid_is_root() { + return; + } + let root = tempfile::tempdir().expect("temp root"); + let empty = tempfile::tempdir().expect("empty PATH"); + let out = sys() + .env("PATH", empty.path()) + .env("PHOEBUS_AI_PROVIDER", "none") + .env("PHOEBUS_AI_BACKEND", "direct") + .arg("--root") + .arg(root.path()) + .args(["install", "firefox"]) + .output() + .expect("run sys"); + assert!( + !out.status.success(), + "an unqualified install must not proceed without a model" + ); + let stderr = String::from_utf8_lossy(&out.stderr); + assert!( + stderr.contains("No connected model") || stderr.contains("no AI provider"), + "stderr: {stderr}" + ); + assert!( + stderr.contains("--flatpak") && stderr.contains("--portage"), + "the offer must name the explicit backends: {stderr}" + ); + // Nothing may have been installed or executed. + assert!(!root + .path() + .join("var/lib/phoebus/transactions.toml") + .exists()); +} + +#[test] +fn the_help_lists_every_backend_flag() { + let out = sys().arg("--help").output().expect("run sys"); + assert!(out.status.success()); + let stdout = String::from_utf8_lossy(&out.stdout); + for flag in [ + "--portage", + "--flatpak", + "--nix", + "--snap", + "--appimage", + "--ebuild", + ] { + assert!(stdout.contains(flag), "help is missing {flag}"); + } +} + #[test] fn choose_never_invents_a_candidate() { // Depending on the host, a lane may or may not be resolvable. Either way the diff --git a/installer/tests/vm/live-sys-install-check.sh b/installer/tests/vm/live-sys-install-check.sh new file mode 100644 index 0000000..543a4a8 --- /dev/null +++ b/installer/tests/vm/live-sys-install-check.sh @@ -0,0 +1,70 @@ +#!/bin/bash +# Guest-side VM verification for the AI-first installation workflow. +# +# Boots the reference Gentoo LiveGUI ISO and exercises `sys install` through +# the deterministic CLI and the read-only investigation surface. The live medium +# ships no Portage tree (it syncs during install), so the explicit install step +# runs only when a tree is already present; otherwise it is skipped and the +# read-only workflow checks are the evidence. A real install journey runs on an +# *installed* target (see docs/HANDOFF.md). +set -u +export PATH=/usr/sbin:/usr/bin:/sbin:/bin +BASE="${PHOEBUS_BASE_URL:-http://10.0.2.2:8000}" +PKG="${SYS_CHECK_PACKAGE:-app-misc/hello}" + +echo "===LIVE-SYS-START===" +cd /tmp || exit 1 +if ! curl -fsSL "$BASE/sys" -o /tmp/sys; then + echo "===SYS-FETCH-FAIL==="; poweroff -f; exit 1 +fi +chmod 0755 /tmp/sys + +echo "--- version ---" +/tmp/sys --version + +echo "--- sync the Portage tree (the live medium ships none) ---" +if timeout 1500 emerge --sync --quiet >/tmp/sync.log 2>&1; then + echo "sync-ok" +else + echo "sync-failed rc=$?; tail:"; tail -5 /tmp/sync.log +fi + +echo "--- conflicting flags must be rejected ---" +/tmp/sys install firefox --flatpak --nix +echo "conflict-rc=$?" + +echo "--- unqualified install with no model must not install ---" +PHOEBUS_AI_PROVIDER= PHOEBUS_AI_BACKEND=direct /tmp/sys install "$PKG" +echo "no-model-rc=$?" + +echo "--- check_backend ---" +/tmp/sys --action '{"action":"check_backend","backend":"portage-source"}' + +echo "--- discover_candidates ---" +/tmp/sys --action "{\"action\":\"discover_candidates\",\"query\":\"$PKG\"}" + +echo "--- explicit Portage install (deterministic, no model) ---" +if [ -d /var/db/repos/gentoo/profiles ]; then + /tmp/sys -y install "$PKG" --portage + echo "portage-install-rc=$?" + echo "--- verify in the package database ---" + ls -d /var/db/pkg/app-misc/hello-* 2>&1 +else + echo "skip: the live medium ships no Portage tree (sync took too long)" + echo "portage-install-rc=skipped" +fi + +echo "--- history ---" +/tmp/sys history + +if [ -d /var/db/pkg/app-misc ]; then + echo "--- remove to leave the live medium clean ---" + /tmp/sys -y remove "$PKG" + echo "remove-rc=$?" +fi + +echo "===LIVE-SYS-DONE===" +sync +echo "===INSTALL-RC=0===" +poweroff -f +echo "===POWEROFF===" diff --git a/installer/tests/vm/sys-acceptance.sh b/installer/tests/vm/sys-acceptance.sh index baa7608..958ddba 100755 --- a/installer/tests/vm/sys-acceptance.sh +++ b/installer/tests/vm/sys-acceptance.sh @@ -96,6 +96,41 @@ else report choose FAIL "unexpected output: $(head -c 200 "$WORK/choose.err")" fi +# --- AI-first installation workflow (read-only cases) --------------------- +# Conflicting backend flags must be rejected by the CLI. +"$SYS" install firefox --flatpak --nix >"$WORK/conflict.out" 2>"$WORK/conflict.err" +if [[ $? -ne 0 ]] && grep -qi "cannot be used with\|conflict\|not allowed" "$WORK/conflict.err"; then + report install-flag-conflict PASS "rejected" +else + report install-flag-conflict FAIL "$(head -c 160 "$WORK/conflict.err")" +fi + +# A backend flag without an install is refused. +"$SYS" --flatpak history >"$WORK/flag.out" 2>"$WORK/flag.err" +if [[ $? -ne 0 ]] && grep -q "only apply to" "$WORK/flag.err"; then + report install-flag-alone PASS "refused" +else + report install-flag-alone FAIL "$(head -c 160 "$WORK/flag.err")" +fi + +# An unqualified install with no provider must offer the explicit commands and +# install nothing. +PHOEBUS_AI_PROVIDER= PHOEBUS_AI_BACKEND=direct \ + "$SYS" install unused-package-xyz >"$WORK/noai.out" 2>"$WORK/noai.err" +if [[ $? -ne 0 ]] && grep -q -- "--flatpak" "$WORK/noai.err"; then + report install-no-model-offer PASS "no model: deterministic offer shown" +else + report install-no-model-offer FAIL "$(head -c 200 "$WORK/noai.err")" +fi + +# Read-only investigation returns structured evidence. +"$SYS" --action '{"action":"check_backend","backend":"flatpak"}' >"$WORK/be.out" 2>"$WORK/be.err" +if grep -q '"backend"' "$WORK/be.out"; then + report investigate-check-backend PASS "$(head -c 120 "$WORK/be.out" | tr '\n' ' ')" +else + report investigate-check-backend FAIL "$(head -c 160 "$WORK/be.err")" +fi + # --- Optional mutating group (disposable VM only) ------------------------- if [[ "$MUTATE" == "1" ]]; then PKG="${SYS_ACCEPTANCE_PACKAGE:-app-misc/hello}"