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).
250 lines
12 KiB
Markdown
250 lines
12 KiB
Markdown
# `sys` — the deterministic Phoebus system interface
|
||
|
||
`sys` is the typed, validated execution boundary shared by the assistant and
|
||
the offline (no-model) administrator. Whatever the assistant can do, a human can
|
||
do by typing the same action; the assistant only makes it easier. The AI path
|
||
emits the same closed action schema, and the LLM never holds privilege: every
|
||
mutation is reviewed and authenticated by a human through the privileged broker.
|
||
|
||
```
|
||
sys <phrase> # deterministic parser (no model)
|
||
sys --action '<json>' # one typed action
|
||
sys --action-file plan.json # a typed action from a file
|
||
sys ask "<request>" # 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)
|
||
|
||
| Phrase | Typed action | Kind |
|
||
| --- | --- | --- |
|
||
| `inspect sshd` | `inspect_service` | read |
|
||
| `enable sshd` | `enable_service` | mutate |
|
||
| `disable sshd` | `disable_service` | mutate |
|
||
| `start sshd` | `start_service` | mutate |
|
||
| `stop sshd` | `stop_service` | mutate |
|
||
| `restart sshd` | `restart_service` | mutate |
|
||
|
||
### Packages (Portage)
|
||
|
||
| Phrase | Typed action | Kind |
|
||
| --- | --- | --- |
|
||
| `install vim` / `add vim` | `install_package` | mutate |
|
||
| `remove vim` / `uninstall vim` | `remove_package` | mutate |
|
||
| `search firefox` / `find firefox` | `search_packages` | read |
|
||
| `update` | `update_system` | mutate |
|
||
| `prepare updates` | `prepare_updates` | mutate |
|
||
| `what are you compiling` | `inspect_updates` | read |
|
||
| *(JSON only)* | `inspect_package` | read |
|
||
|
||
### Source selection (all lanes)
|
||
|
||
| Phrase | Typed action | Kind |
|
||
| --- | --- | --- |
|
||
| `choose firefox` | `choose_package` | read |
|
||
| `choose firefox via flatpak` | `choose_package` | read |
|
||
| `choose spotify as a gui sandboxed app` | `choose_package` | read |
|
||
| `prefer firefox via flatpak` | `set_package_preference` | mutate |
|
||
| `prefer firefox auto` | `set_package_preference` | mutate |
|
||
|
||
`choose` resolves real backend metadata, applies the shared policy
|
||
(ADR 0006), and prints the selected lane, version, provenance, integrity,
|
||
sandbox level, sizes, update behaviour and the rejected alternatives. It never
|
||
installs anything and never fabricates a candidate.
|
||
|
||
### Flatpak
|
||
|
||
| Phrase | Typed action | Kind |
|
||
| --- | --- | --- |
|
||
| `flatpak install org.chromium.Chromium` | `flatpak_install` | mutate |
|
||
| `flatpak remove org.chromium.Chromium` | `flatpak_remove` | mutate |
|
||
| `flatpak list` | `flatpak_list` | read |
|
||
|
||
### Nix (developer lane)
|
||
|
||
| Phrase | Typed action | Kind |
|
||
| --- | --- | --- |
|
||
| `nix prepare nodejs python312` | `nix_prepare` | mutate |
|
||
|
||
### Snap (opt-in; `app-containers/snapd` through Portage)
|
||
|
||
| Phrase | Typed action | Kind |
|
||
| --- | --- | --- |
|
||
| `snap find notes` | `snap_find` | read |
|
||
| `snap info thunderbird` | `snap_info` | read |
|
||
| `snap install thunderbird [channel]` | `snap_install` | mutate |
|
||
| `snap remove thunderbird` | `snap_remove` | mutate |
|
||
| `snap list` | `snap_list` | read |
|
||
| `snap refresh [name]` | `snap_refresh` | mutate |
|
||
| `snap connections thunderbird` | `snap_connections` | read |
|
||
|
||
Snap requires a ready `snapd` daemon. If it is absent, `snap_install` installs
|
||
`app-containers/snapd` through Portage and enables `snapd.socket` first.
|
||
Confinement is detected (`strict`/`partial`/`none`); `--classic` is only used
|
||
when the typed action sets `"classic": true` and is shown in the review. The
|
||
plan notes that snapd also refreshes automatically.
|
||
|
||
### AppImage (opt-in; managed, not sandboxed)
|
||
|
||
| Phrase | Typed action | Kind |
|
||
| --- | --- | --- |
|
||
| `appimage import /path/App.AppImage` | `appimage_import` | mutate |
|
||
| *(JSON only)* | `appimage_acquire` | mutate |
|
||
| *(JSON only)* | `appimage_update` | mutate |
|
||
| `appimage remove name` | `appimage_remove` | mutate |
|
||
| `appimage info name` | `appimage_info` | read |
|
||
| `appimage list` | `appimage_list` | read |
|
||
|
||
Acquisition requires a pinned SHA-256; a placeholder or mismatch is refused and
|
||
the download is discarded. Architecture is read from the ELF header without
|
||
executing the image. Desktop entries are installed, and user data is preserved
|
||
on removal unless `"purge_data": true`. AppImage provides **no application
|
||
sandbox** and is described as such.
|
||
|
||
### Custom ebuilds (Phoebus overlay)
|
||
|
||
| Phrase | Typed action | Kind |
|
||
| --- | --- | --- |
|
||
| `ebuilds` / `custom ebuilds` | `custom_ebuild_list` | read |
|
||
| *(JSON only)* | `custom_ebuild_prepare` | mutate |
|
||
| *(JSON only)* | `custom_ebuild_install` | mutate |
|
||
| *(JSON only)* | `custom_ebuild_remove` | mutate |
|
||
|
||
A custom ebuild is untrusted executable code. `custom_ebuild_prepare` writes it
|
||
to `/var/db/repos/phoebus` with a rationale and the SHA-256 of its exact
|
||
content; it does not build it. `custom_ebuild_install` requires that same
|
||
digest, regenerates the `Manifest` and builds through Portage with its sandbox
|
||
enabled. Editing the staged ebuild invalidates the approval.
|
||
|
||
### Snapshots and rollback
|
||
|
||
| Phrase | Typed action | Kind |
|
||
| --- | --- | --- |
|
||
| `snapshot before update` | `create_snapshot` | mutate |
|
||
| `undo` / `rollback` | `undo` | mutate |
|
||
| `undo status` | `rollback_status` | read |
|
||
| `history` | `history` | read |
|
||
|
||
## Acceptance matrix
|
||
|
||
The matrix below is the repeatable acceptance suite. `installer/tests/vm/
|
||
sys-acceptance.sh` runs the deterministic and JSON groups inside a booted,
|
||
installed, detached VM and prints a machine-readable summary; it is safe to run
|
||
with no network and no model.
|
||
|
||
| # | Case | Command | Expected |
|
||
| --- | --- | --- | --- |
|
||
| 1 | Identity | `sys --version` | prints the version, exit 0 |
|
||
| 2 | Read-only history | `sys history` | state, exit 0, no mutation |
|
||
| 3 | Invalid natural operand | `sys -- install --color=n` | rejected, nonzero |
|
||
| 4 | Unknown phrase | `sys frobnicate` | rejected, nonzero, examples shown |
|
||
| 5 | JSON unknown action | `--action '{"action":"run_shell"}'` | fail closed, nonzero |
|
||
| 6 | JSON unknown field | `--action '{"action":"history","x":1}'` | fail closed, nonzero |
|
||
| 7 | Option-like operand (JSON) | `install_package atom="-C"` | rejected before any command |
|
||
| 8 | Invalid Snap name | `snap_install name="Bad Name"` | rejected, nonzero |
|
||
| 9 | Invalid AppImage hash | `appimage_acquire sha256="00"` | rejected, nonzero |
|
||
| 10 | Ebuild path traversal | `custom_ebuild_prepare atom="../../x"` | rejected, nonzero |
|
||
| 11 | Choose with no lane | `sys choose unused-name` | selection or clear failure, never invented |
|
||
| 12 | Inventory (empty root) | `--root T appimage list` / `ebuilds` | "no managed …", exit 0 |
|
||
| 13 | Mutating as non-root | `set_package_preference` | refused: needs root |
|
||
| 14 | Snap daemon absent | `snap list` on a system without snapd | useful error, nonzero |
|
||
| 15 | Install a tiny package | `sys install app-misc/hello` (Portage) | installed; `emerge -p` confirms; recorded in `sys history` |
|
||
| 16 | Remove it | `sys remove app-misc/hello` | removed; recorded |
|
||
| 17 | Service lifecycle | `sys enable/start/stop sshd` | unit state matches `systemctl` |
|
||
| 18 | Update preparation | `sys prepare updates` then `what are you compiling` | state reported truthfully |
|
||
| 19 | Snapshot + undo | `sys snapshot`, mutate, `sys undo`, reboot | root/var/package state restored |
|
||
| 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 "<request>"` 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–31 are covered by host tests
|
||
(`crates/phoebus-core/src/selection.rs`, `.../action.rs`,
|
||
`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
|
||
|
||
- **No shell.** Every command is an argument vector through
|
||
`phoebus-executor::Exec`; there is no `sh -c` on any path.
|
||
- **Validated at the boundary.** Every action (manual, JSON, or AI) is
|
||
re-validated before a command is built; option-like operands are rejected.
|
||
- **Target-root isolation.** Alternate-root operations are chrooted; runtime
|
||
operations (services, Snap) refuse an alternate root.
|
||
- **Approval binding.** A resolved plan has a digest; a material change between
|
||
review and execution aborts. A custom ebuild binds approval to its content
|
||
digest.
|
||
- **Secrets** travel only through mode-0600 files/stdin and are redacted from
|
||
logs and history.
|