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).
15 KiB
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.
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
--legacyis the administrative flag forsysdeterministic operations.--no-aiis 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:
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:
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
--legacyconstrain 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
--legacybypass 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
--legacycommands 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:
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 --portageinstalls and verifies viaemerge -p.mutate-remove:sys -y remove app-misc/hello --legacyuninstalls cleanly.mutate-history:sys history --legacyconfirms 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 nosh -con 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.