Some checks are pending
ci / test (push) Waiting to run
Unifies AI-first administration across the CLI (sys) and desktop GUI
(phoebus-assistant) through a shared service layer, fixes installed
desktop QML asset provisioning, adds Polkit elevation, and introduces
contextual conversation continuity.
- Extract phoebus_installer::service shared by CLI and desktop assistant bridge:
- Reviewable plan staging (PreparedPlan) with SHA-256 cryptographic digests,
15-minute TTL expiration, and replay prevention (PlanStore).
- Pre-mutation system state revalidation binding execution strictly to the reviewed plan.
- Honest recommendations displaying genuine provenance and unmeasured compile times.
- Two-phase transaction logging (begin before mutation, finish with verification).
- Provision installed desktop assets and Polkit policy in phoebus-executor::desktop:
- Added gui-apps/quickshell to canonical Mango desktop packages.
- Embed 13 QML and policy files into target root under /usr/share/phoebus/assistant/.
- Installed Polkit policy (club.phoebus.sys.policy) allowing unprivileged users to
authenticate mutating plans via pkexec without blanket passwordless sudo.
- Eliminate startup freeze and polling in phoebus-assistant:
- Multi-source update queries moved to on-demand tab switching.
- Handshake timer reduced to one-shot 100ms with fast deterministic check.
- Add phoebus_installer::conversation:
- Bounded 10-turn history with credential redaction.
- Contextual follow-up resolution for comparisons, backend switching, and confirmation.
- Implement unified cross-source removal (plan_removal) preserving user data by default.
- Verified: all 486 workspace tests pass, release and crt-static builds succeed,
and 23/23 VM acceptance cases pass (PASS=23 FAIL=0).
312 lines
15 KiB
Markdown
312 lines
15 KiB
Markdown
# `sys` — the Phoebus system interface
|
|
|
|
`sys` is the typed, validated execution boundary shared by the desktop assistant
|
|
(`phoebus-assistant`) and the offline/deterministic 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.
|
|
|
|
```sh
|
|
sys <phrase> # natural language / AI workflow (default)
|
|
sys please <phrase> # natural conversational alias (same AI workflow)
|
|
sys ask "<request>" # assistant proposes the same typed actions
|
|
sys --legacy <phrase> # explicit deterministic mode (no model interaction)
|
|
sys --legacy --action '<json>' # one typed action in deterministic legacy mode
|
|
sys --broker --action '<json>' # internal broker invocation for shared UI / bridge
|
|
sys --assistant-bridge # stdio JSON-RPC bridge for the desktop assistant
|
|
```
|
|
|
|
Run `sys --help` for the full list of flags. Mutating actions require root
|
|
(`sudo sys ...`). Without a model, AI workflows stop and print the actionable
|
|
deterministic legacy alternative (`sys install <pkg> --legacy --<source>`)
|
|
instead of silently falling back or switching sources.
|
|
|
|
> [!NOTE]
|
|
> `--legacy` is the administrative flag for `sys` deterministic operations.
|
|
> `--no-ai` is an installer-only break-glass flag reserved exclusively for
|
|
> non-interactive ISO installations (`installer-rs/tests/ai_guidance.rs`).
|
|
|
|
## AI-first installation (`sys install`)
|
|
|
|
Natural language is the default interaction. Source flags alone constrain the
|
|
AI investigation to a specific package source without bypassing the model:
|
|
|
|
```sh
|
|
sys install firefox # AI investigates and recommends a package source
|
|
sys please install firefox # identical AI workflow
|
|
sys ask "install firefox" # identical AI workflow
|
|
sys install firefox --flatpak # AI workflow constrained to Flatpak
|
|
sys install firefox --portage # AI workflow constrained to Portage
|
|
sys install nodejs --nix # AI workflow constrained to Nix
|
|
sys install thunderbird --snap # AI workflow constrained to Snap
|
|
sys install MyTool --appimage # AI workflow constrained to AppImage
|
|
sys install app-misc/my-thing --ebuild # AI workflow constrained to custom ebuild
|
|
```
|
|
|
|
### Deterministic administration (`--legacy`)
|
|
|
|
Deterministic operation must be explicitly selected with `--legacy`:
|
|
|
|
```sh
|
|
sys install firefox --legacy --flatpak # deterministic Flatpak workflow; no model interaction
|
|
sys install firefox --legacy --portage # deterministic Portage workflow; no model interaction
|
|
sys history --legacy # deterministic history without model
|
|
sys undo --legacy # deterministic recovery without model
|
|
sys install firefox --legacy # REFUSED: requires an explicit package source flag
|
|
```
|
|
|
|
When `--legacy` is used with `install` but without an explicit source flag,
|
|
execution is refused and available package sources are displayed.
|
|
|
|
Direct JSON and action-file invocations (`--action` and `--action-file`) are
|
|
audited entry points: they fail closed unless invoked with `--legacy` (for
|
|
deterministic administrator usage) or `--broker` (for internal UI/bridge
|
|
calls).
|
|
|
|
One shared workflow (ADR 0013) is used by all installations:
|
|
|
|
```
|
|
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.
|
|
- **Source flags without `--legacy`** constrain the AI investigation to the
|
|
specified backend, ensuring the model evaluates and explains candidates for
|
|
that source while preserving the full investigation, explanation, and
|
|
approval cycle.
|
|
- **Explicit backend flags with `--legacy`** bypass the model entirely, 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 / Provider failure**: For an unqualified install without a model or
|
|
upon provider error, the operation halts cleanly. The deterministic candidate
|
|
selection and explicit `--legacy` commands are printed, and nothing is
|
|
installed. A provider failure is never permission to install through a lane
|
|
silently.
|
|
- 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. User data is
|
|
preserved by default on removal.
|
|
|
|
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 |
|
|
|
|
## Desktop assistant bridge (`sys --assistant-bridge`)
|
|
|
|
The desktop assistant GUI (`phoebus-assistant`) is a lightweight Quickshell QML
|
|
interface that delegates all logic to `sys --assistant-bridge`. The bridge runs
|
|
a stdio JSON-RPC server speaking newline-delimited JSON messages:
|
|
|
|
- `handshake`: validates client identity and checks active AI model connectivity.
|
|
- `ask`: submits a conversational request (`install firefox`, `why is audio broken?`)
|
|
into the shared AI workflow, returning assistant proposals and bounded evidence.
|
|
- `execute`: executes a reviewed, approved plan by plan ID and plan digest.
|
|
- `legacy_install`: performs deterministic installation with an explicit backend.
|
|
- `legacy_execute`: executes typed actions deterministically.
|
|
- `updates`: queries the unified multi-source update system across Portage,
|
|
Flatpak, Snap, AppImage, and Nix.
|
|
- `proactive_alerts`, `proactive_snooze`, `proactive_dismiss`: interacts with the
|
|
quiet proactive system monitor.
|
|
- `get_preferences`, `set_preferences`: inspects and edits user package source
|
|
profiles, project environment tool mappings, and keep-existing-source pins.
|
|
- `history`, `undo`: queries transaction logs and initiates recovery.
|
|
|
|
Zero business logic lives in the GUI: equivalent CLI and GUI requests produce
|
|
identical validated plans given the same facts and preferences.
|
|
|
|
## Acceptance matrix
|
|
|
|
The matrix below is the repeatable acceptance suite. `installer/tests/vm/sys-acceptance.sh`
|
|
runs the deterministic, legacy, and JSON acceptance cases 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 (legacy) | `sys history --legacy` | state, exit 0, no mutation |
|
|
| 3 | Undo status (legacy) | `sys undo status --legacy` | idle rollback state, exit 0 |
|
|
| 4 | Non-root undo | `sys undo --legacy` (non-root) | requires root, exit nonzero |
|
|
| 5 | AppImage inventory (empty) | `sys --legacy appimage list` | "no managed AppImages", exit 0 |
|
|
| 6 | Ebuild inventory (empty) | `sys --legacy ebuilds` | "no custom ebuilds", exit 0 |
|
|
| 7 | Invalid natural operand | `sys --legacy -- install --color=n` | rejected, nonzero |
|
|
| 8 | Unknown phrase | `sys --legacy frobnicate` | rejected, nonzero, examples shown |
|
|
| 9 | Audited action without legacy/broker | `sys --action '{"action":"history"}'` | fail closed, requires `--legacy` or `--broker` |
|
|
| 10 | Legacy install without source | `sys install firefox --legacy` | refused: requires explicit source flag |
|
|
| 11 | JSON unknown action | `--legacy --action '{"action":"run_shell"}'` | fail closed, nonzero |
|
|
| 12 | JSON unknown field | `--legacy --action '{"action":"history","x":1}'` | fail closed, nonzero |
|
|
| 13 | Option-like operand (JSON) | `install_package atom="-C"` | rejected before any command |
|
|
| 14 | Invalid Snap name | `snap_install name="Bad Name"` | rejected, nonzero |
|
|
| 15 | Invalid AppImage hash | `appimage_acquire sha256="00"` | rejected, nonzero |
|
|
| 16 | Ebuild path traversal | `custom_ebuild_prepare atom="../../x"` | rejected, nonzero |
|
|
| 17 | Mutating as non-root | `set_package_preference` | refused: needs root |
|
|
| 18 | Offline `sys ask` | `sys ask "<request>"` with no provider | deterministic fallback, nonzero |
|
|
| 19 | Choose with no lane | `sys --root / choose unused-xyz --legacy` | selection or clear failure, never invented |
|
|
| 20 | Conflicting backend flags | `sys install x --flatpak --nix` | rejected by CLI |
|
|
| 21 | Source flag without install | `sys --flatpak history --legacy` | rejected by CLI |
|
|
| 22 | Unqualified with no model | `sys install firefox` (no provider) | deterministic offer printed, nothing installed |
|
|
| 23 | Read-only investigation | `--legacy --action '{"action":"check_backend",...}'` | structured JSON evidence returned |
|
|
|
|
### Mutating acceptance cases (disposable VM only)
|
|
|
|
When `SYS_ACCEPTANCE_MUTATE=1` is set in the disposable VM:
|
|
- `mutate-install`: `sys -y install app-misc/hello --legacy --portage` installs and verifies via `emerge -p`.
|
|
- `mutate-remove`: `sys -y remove app-misc/hello --legacy` uninstalls cleanly.
|
|
- `mutate-history`: `sys history --legacy` confirms both install and remove are logged.
|
|
|
|
All 23 read-only and failure acceptance cases are verified in the test suite
|
|
(`installer/tests/vm/sys-acceptance.sh` reports `PASS=23 FAIL=0`). Host unit and
|
|
integration tests in `crates/phoebus-installer/tests/sys_cli.rs`,
|
|
`crates/phoebus-core/`, and `crates/phoebus-executor/` cover proposal validation,
|
|
digest matching, lane policy, and cross-source removal.
|
|
|
|
## 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.
|