phoebus_os/docs/SYS.md
Phoebus f30b99d272
Some checks are pending
ci / test (push) Waiting to run
feat(admin): implement AI-first administration across CLI and desktop GUI
- Default natural-language and conversational routing for sys install, sys please install, and sys ask through shared AI workflow
- Constrain AI candidate evaluation when source flags are supplied without bypassing the model
- Enforce explicit --legacy flag for deterministic administration; legacy install without a source flag refuses execution and offers choices
- Audit --action and --action-file entry points to require --legacy or --broker
- Provide truthful guidance on absent or failing AI models without silent mutation or unverified fallback
- Implement package correctness safeguards: Nix attribute evaluation probe, Portage binary check with source compile abort guard, cross-source installed application tracking, and data preservation on removal
- Provide Quickshell desktop assistant (phoebus-assistant) backed by stdio JSON-RPC bridge (sys --assistant-bridge) and desktop integration
- Implement unified multi-source update checking across all package lanes
- Implement quiet proactive assistance monitor with alert deduplication and snoozing
- Expand acceptance suite in installer/tests/vm/sys-acceptance.sh to 22 cases (22/22 PASS)
2026-09-24 16:38:38 -07:00

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

--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:

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 --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:

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 (legacy) sys undo --legacy requires root or executes cleanly
4 AppImage inventory (empty) sys --legacy appimage list "no managed AppImages", exit 0
5 Ebuild inventory (empty) sys --legacy ebuilds "no custom ebuilds", exit 0
6 Invalid natural operand sys --legacy -- install --color=n rejected, nonzero
7 Unknown phrase sys --legacy frobnicate rejected, nonzero, examples shown
8 Audited action without legacy/broker sys --action '{"action":"history"}' fail closed, requires --legacy or --broker
9 Legacy install without source sys install firefox --legacy refused: requires explicit source flag
10 JSON unknown action --legacy --action '{"action":"run_shell"}' fail closed, nonzero
11 JSON unknown field --legacy --action '{"action":"history","x":1}' fail closed, nonzero
12 Option-like operand (JSON) install_package atom="-C" rejected before any command
13 Invalid Snap name snap_install name="Bad Name" rejected, nonzero
14 Invalid AppImage hash appimage_acquire sha256="00" rejected, nonzero
15 Ebuild path traversal custom_ebuild_prepare atom="../../x" rejected, nonzero
16 Mutating as non-root set_package_preference refused: needs root
17 Offline sys ask sys ask "<request>" with no provider deterministic fallback, nonzero
18 Choose with no lane sys --root / choose unused-xyz --legacy selection or clear failure, never invented
19 Conflicting backend flags sys install x --flatpak --nix rejected by CLI
20 Source flag without install sys --flatpak history --legacy rejected by CLI
21 Unqualified with no model sys install firefox (no provider) deterministic offer printed, nothing installed
22 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 22 read-only and failure acceptance cases are verified in the test suite (installer/tests/vm/sys-acceptance.sh reports PASS=22 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, and lane policy.

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.