738 lines
42 KiB
Markdown
738 lines
42 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.
|
|
|
|
### Terminal feedback
|
|
|
|
Interactive `sys` commands show the current phase on stderr: checking the
|
|
system, investigating with the connected model, validating real package
|
|
evidence, reviewing effects, applying each approved action, and verifying the
|
|
result. A command that takes more than a moment shows its operation label;
|
|
long steps repeat their current label and elapsed time every ten seconds.
|
|
Progress never includes command arguments, command output, or credentials.
|
|
Results remain on stdout. Broker JSON does not emit human progress. The
|
|
assistant's stdio protocol sends redacted progress JSON lines before the final
|
|
reply, keyed by request ID; its GUI displays these phases in the conversation
|
|
card. Informational model answers are wrapped as prose and
|
|
omit the approval digest when no action is proposed.
|
|
|
|
> [!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 chatgpt desktop through nix # AI workflow constrained to Nix; descriptive name
|
|
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
|
|
```
|
|
|
|
An install phrase ending in `through`, `via`, `using`, or `with` plus a package
|
|
lane is parsed as a lane choice, not as part of the application name. If the
|
|
model cannot produce a valid plan for a descriptive name, `sys` searches the
|
|
requested lane and suggests an exact package identifier when the catalogue
|
|
confirms one. It does not install a fallback without review.
|
|
|
|
Removal is also AI-first by default. The deterministic ownership discovery and
|
|
policy validation always run underneath; the connected model confirms the exact
|
|
discovered copy. An ambiguous multi-lane install still requires an explicit
|
|
source flag, and a model failure stops execution rather than silently removing
|
|
deterministically:
|
|
|
|
```sh
|
|
sys remove firefox # AI workflow: confirm target, then remove
|
|
sys remove firefox --flatpak # AI workflow constrained to Flatpak
|
|
sys remove firefox --legacy # deterministic removal, no model
|
|
sys remove firefox --legacy --flatpak # deterministic removal from Flatpak
|
|
```
|
|
|
|
### 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 remove firefox --legacy # deterministic removal, 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. `--legacy`
|
|
never contacts a model.
|
|
|
|
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
|
|
first receive a read-only search across the configured Portage, Flatpak,
|
|
Snap, AppImage, Nix and staged-ebuild catalogues. Each source reports actual
|
|
matches, no matches, an unavailable backend, or a failed lookup; catalog
|
|
results are leads rather than verified artifacts. For a multiword name, an
|
|
empty lane also searches the first term and labels those broader results.
|
|
The model compares these
|
|
findings before recommending a source. The desktop Assistant shows the
|
|
source results alongside the recommended plan. Selecting a different result
|
|
re-resolves the exact displayed package ID and prepares a new source-specific
|
|
plan for approval; it never executes directly. A changed ID is refused.
|
|
AppImage catalog leads have no direct install button because acquisition
|
|
requires a pinned artifact URL and SHA-256. Source-constrained requests only
|
|
investigate the selected lane. 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.
|
|
- **Package source review** requires the model to inspect the exact candidate
|
|
before recommending a package from any lane, including ordinary Portage
|
|
source and binary packages. A vendor binary ebuild can appear in the
|
|
Portage source lane. `inspect_candidate` returns a structured
|
|
health report: source, integrity evidence, reported version and freshness
|
|
limits, isolation, and a `hold` or `review_required` status. The model must
|
|
explain uncertainty rather than declare a package safe or current. For
|
|
Flatpak, `sys` checks that the resolved app comes from its configured
|
|
`flathub` install remote, that the remote uses HTTPS, and that GPG
|
|
verification is enabled. It refuses an unverified remote and repeats the
|
|
check before execution; a changed version, remote, or verification state
|
|
invalidates approval. This Flatpak check also applies to direct typed
|
|
administrator actions. For all reviewed installs, the selected candidate
|
|
is inspected again and a changed version, source, or verification state
|
|
invalidates approval. Portage repository origin and Nix registry revision
|
|
are not currently established by this inspection and are labeled as such.
|
|
The plan shows these source health findings. A hash or
|
|
catalog entry alone does not authenticate an AppImage publisher, and this
|
|
review cannot prove that an upstream release is uncompromised.
|
|
- **General assistant plans** cannot use direct package install actions to
|
|
skip this source review. Package installs use the dedicated `sys install`
|
|
workflow. Typed administrator actions remain available through the audited
|
|
`--legacy` entry point.
|
|
- **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 |
|
|
| `build firefox from source` | `convert_to_source` | mutate (High risk, protective snapshot) |
|
|
| `build tuned kernel` | `build_tuned_kernel` | mutate (High risk, protective snapshot) |
|
|
| `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 (personal) |
|
|
| `prefer firefox auto` | `set_package_preference` | mutate (personal) |
|
|
| *(JSON only)* `system_wide: true` | `set_package_preference` | mutate (privileged) |
|
|
|
|
`prefer ...` saves the invoking user's own preference; it needs no elevation and
|
|
is stored under the user's config directory. The system-wide default is the same
|
|
action with `"system_wide": true`, which requires the authenticated broker. At
|
|
resolution time the personal choice wins and system defaults fill anything the
|
|
user has not set.
|
|
|
|
`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 |
|
|
| `nix install cmatrix` | `nix_install` | mutate |
|
|
|
|
`sys install cmatrix --legacy --nix` installs into the shared Phoebus Nix
|
|
profile; its commands are on the graphical session's `PATH`. The Nix client's
|
|
default profile remains separate. Direct `nix profile install nixpkgs#cmatrix`
|
|
as a normal user uses the user's own profile, which is also on `PATH`.
|
|
`nix prepare` only realises packages for temporary `nix shell` use.
|
|
|
|
### Snap (`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 |
|
|
|
|
New Phoebus desktop installs include `snapd` and enable `snapd.socket`; systemd
|
|
starts the socket on boot. Snap application installs still receive their own
|
|
review and approval. Systems installed before this change, and minimal
|
|
installations, need a separate reviewed setup step:
|
|
|
|
```sh
|
|
sys install app-containers/snapd --legacy --portage
|
|
sys enable snapd.socket --legacy
|
|
sys start snapd.socket --legacy
|
|
sys install <app> --legacy --snap
|
|
```
|
|
|
|
Run these on the installed system, not on the live installer. The resolver
|
|
prints the setup commands when the daemon is missing. AppArmor availability
|
|
determines the confinement reported by `snap debug confinement`; a running
|
|
daemon alone does not imply strict confinement.
|
|
New installs include the scoped `sys-fs/squashfs-tools lzma lzo` USE settings
|
|
required by Gentoo's snapd ebuild. An existing installation made before that
|
|
setting was added may need the same line in
|
|
`/etc/portage/package.use/phoebus-snap` before the Portage step.
|
|
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 and a public URL without credentials,
|
|
query or fragment; a placeholder or mismatch is refused and
|
|
the download is discarded. Architecture is read from the ELF header without
|
|
executing the image. Managed files live in `/opt/phoebus/appimages`, where a
|
|
normal desktop account can launch them and read their inventory. 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.
|
|
Images imported by older builds into the private
|
|
`/var/lib/phoebus/appimages` directory must be re-imported by an administrator
|
|
from that original file; the current import writes the accessible path and
|
|
replaces its desktop entry. The old file is left in place for explicit cleanup.
|
|
|
|
### 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.
|
|
|
|
### Package catalogue: search, inventory, information, updates, maintenance
|
|
|
|
These are AI-first like every other operation. Without `--legacy` the request
|
|
enters the connected model, which answers from **bounded, read-only evidence**
|
|
(search, inventory, information, update checks). A source flag
|
|
(`--portage`/`--flatpak`/`--nix`/`--snap`/`--appimage`/`--ebuild`) constrains the
|
|
AI workflow: lane-selectable queries are rewritten to that lane and an action
|
|
for any other lane is refused. `--legacy` runs the same typed action
|
|
deterministically with no model interaction.
|
|
|
|
Explicit AppImage **install** requests are a discovery-only exception: the
|
|
community catalog has no pinned artifact hash, so `sys` and the desktop
|
|
assistant show matching leads and the import/acquire requirements without
|
|
creating an install plan. A catalog match cannot be installed through
|
|
`sys install <name> --legacy --appimage` either.
|
|
|
|
Every result distinguishes three honest states per lane: **unavailable**
|
|
(tooling absent), **failed** (the tool ran and did not answer), and **empty**
|
|
(a successful query with no results). Package facts are never invented.
|
|
|
|
| Phrase | Typed action | Kind |
|
|
| --- | --- | --- |
|
|
| `search firefox` / `find firefox` | `search_packages` | read |
|
|
| `list` / `list installed` / `list vim` | `list_packages` | read |
|
|
| `info firefox` | `package_info` | read |
|
|
| `updates` / `check updates` | `check_updates` | read |
|
|
| `apply updates` / `upgrade` | `apply_updates` | mutate |
|
|
| `depclean` / `autoremove` | `depclean` | mutate |
|
|
| `clean cache` / `clean distfiles` | `clean_cache` | mutate |
|
|
| `who owns /usr/bin/vim` | `package_owners` | read |
|
|
| `deps vim` | `package_dependencies` (reverse=false) | read |
|
|
| `rdeps vim` | `package_dependencies` (reverse=true) | read |
|
|
|
|
Deterministic forms:
|
|
|
|
On the desktop, launch **Phoebus Updates** or press Super+U. The update view
|
|
checks sources without a model, and **Review & Apply** opens the same
|
|
interactive `sudo sys apply updates --legacy` flow in Kitty. Portage compiles
|
|
and other package progress stay visible through completion. DankMaterialShell
|
|
is updated as a normal Portage package; the default DMS bar does not use its
|
|
separate updater widget.
|
|
|
|
```sh
|
|
sys search firefox --legacy # every source
|
|
sys search firefox --legacy --flatpak # one source
|
|
sys search firefox --legacy --appimage # managed images + community catalog leads
|
|
sys search chatgpt --legacy --overlays --portage # configured Portage + external GPO leads
|
|
sys overlay review app-misc/chatgpt-desktop # inspect listed repos and current ebuilds
|
|
sys overlay enable app-misc/chatgpt-desktop gentoo-zh # stage, review, approve, register
|
|
sys list --legacy # installed inventory, all lanes
|
|
sys list vim --legacy --portage # inventory, source + text filter
|
|
sys info firefox --legacy # version/source/status/deps/size
|
|
sys updates --legacy # check only, no mutation
|
|
sys apply updates --legacy # apply, per-source outcome
|
|
sys depclean --legacy # Portage unused-dependency removal
|
|
sys clean cache --legacy --nix # Nix GC
|
|
sys who owns /usr/bin/vim --legacy # Portage file ownership
|
|
sys deps vim --legacy # forward dependencies
|
|
sys rdeps vim --legacy # reverse dependencies (equery)
|
|
```
|
|
|
|
Portage searches cover repositories configured on this machine. The optional
|
|
`--overlays` flag sends the search term to the unofficial GPO overlay index and
|
|
lists matching ebuild names as **external leads** below the local catalogue.
|
|
Those leads are not validated install candidates: review and sync a repository
|
|
first, and accept `~amd64` only for a specific package if needed. The external
|
|
lookup has an eight-second limit; a network failure leaves local results
|
|
available. `--overlays` is restricted to deterministic `search --legacy` and
|
|
cannot be combined with a non-Portage source flag.
|
|
`sys overlay review category/package` follows each GPO lead to Gentoo's
|
|
repository registry, then inspects the live Git repository name, commit, exact
|
|
ebuild SHA-256, `amd64` keywords, and package Manifest. It presents only options
|
|
that pass these checks. The registry explicitly calls many repositories
|
|
**unofficial** and **experimental**; listing and hashes do not prove publisher
|
|
trust. `sys overlay enable category/package repository` repeats discovery and
|
|
stages an exact revision-bound plan. After approval, the broker rechecks the
|
|
registry, commit and ebuild, clones the repository, masks every package in it
|
|
except the selected atom, adds a package-scoped `~amd64` allowance when needed,
|
|
and registers it with `auto-sync = yes`. A normal `emerge --sync` refreshes the
|
|
repository; `sys updates` still checks the last synced metadata. Installing or
|
|
updating the package itself requires a separate reviewed Portage plan. If the
|
|
source changes between review and execution, the broker refuses the stale plan.
|
|
Only the running system (`/`) supports this external review and registration.
|
|
|
|
In the desktop Assistant, pasting a `https://gpo.zugaina.org/category/package`
|
|
link checks that exact atom against configured Portage sources. If absent, it
|
|
shows eligible overlay options with their source, revision and ebuild digest.
|
|
Selecting one stages its registration plan; it never installs the package from
|
|
the GPO listing. The same broker handles the Assistant approval and CLI plan.
|
|
|
|
AppImage searches include Phoebus-managed images and read-only leads from the
|
|
AppImage project's community catalog when online. Leads show a catalog page
|
|
when supplied, but the catalog does not provide a pinned artifact and hash.
|
|
They are labeled `catalog lead` and cannot be installed from a search result;
|
|
`appimage_acquire` still needs an independently reviewed HTTPS artifact URL and
|
|
SHA-256. An unavailable catalog is reported as a lookup failure, while managed
|
|
images remain visible. Alternate-root searches inspect only managed images.
|
|
|
|
During a terminal mutation, `sys` shows the package manager's output as it
|
|
arrives: Portage build and merge logs, Flatpak transaction progress, Snap
|
|
operations, Nix realisation, custom ebuild builds, and AppImage downloads.
|
|
Carriage-return progress updates are displayed as well as complete lines.
|
|
The current phase and slow-step heartbeat remain visible. Read-only queries
|
|
return a composed report; the broker and assistant protocols keep their
|
|
structured output.
|
|
|
|
- **Search** covers Portage (`emerge --search`), Flatpak remote search, the Snap
|
|
Store, Phoebus-managed AppImages plus online community catalog leads, Nix (`nix search`, when online) and staged
|
|
custom ebuilds. Entries show source, identity, version, description and
|
|
installed status where the backend provides them.
|
|
- **Inventory** covers the Portage VDB, `flatpak list`, `snap list`,
|
|
Phoebus-managed AppImages and the **packages of the active Nix profiles**
|
|
(parsed from each profile's `manifest.json`; historical generations and
|
|
realised store paths are reported separately, never as installed programs).
|
|
Custom ebuilds install through Portage and are listed once, under Portage.
|
|
- **Information** combines installed copies (VDB metadata: version, size,
|
|
repository, `DEPEND`/`RDEPEND`/`BDEPEND`) with resolved candidates and policy
|
|
metadata. When more than one real package matches, the report is marked
|
|
**ambiguous** and lists every match instead of guessing.
|
|
- **Updates** check every supported lane. Applying a Flatpak or Snap update
|
|
**executes exactly the reviewed transaction**: the plan binds the full Flatpak
|
|
ref (`app/…/arch/branch`, from `remote-ls`) plus the installed and remote
|
|
**full commits** (from `flatpak info`, since Flatpak's `commit` column is
|
|
abbreviated), or the snap name plus its old/new revisions and tracking
|
|
channel. Execution is pinned (`flatpak update --commit=<commit>`) and the
|
|
source is revalidated immediately before its mutation — including after an
|
|
earlier source has run — so a commit republished under an unchanged human
|
|
version, a newly appearing update, or a change in the active installation
|
|
aborts as stale. A source whose resolution failed is never re-discovered and
|
|
executed later. `flatpak` and `snap` both require backend prerequisites and
|
|
are refused explicitly when they cannot run. AppImage (pinned URL+SHA) and Nix
|
|
(project/declarative) are refused as a system-level transaction rather than
|
|
reported as updated. A source that was attempted and failed fails the whole
|
|
action while the report still shows the sources that succeeded. Background
|
|
**preparation** (`prepare updates`, `what are you compiling`) remains distinct
|
|
from **activation**.
|
|
- **Maintenance**: `depclean` records its removal set as **structured package
|
|
effects** (not only prose) from `emerge --pretend --depclean` at review time,
|
|
so a changed removal set is caught before execution; it refuses when the
|
|
selection cannot be established, and preserves config files and user data.
|
|
`clean cache` reviews each cleaner's real **non-destructive preview**
|
|
(`eclean-dist`/`eclean-pkg` delete by default, so the preview passes
|
|
`--pretend` with the same `--deep` selection as the destructive run;
|
|
`nix-store --gc`'s documented preview is `--print-dead`) and binds the item
|
|
set to approval; a cleaner that ran and failed propagates as a failed action
|
|
while partial successes are preserved, and an unavailable cleaner is reported
|
|
distinctly from one that found nothing. `package_owners` and
|
|
`package_dependencies` use the installed VDB metadata (forward dependencies
|
|
include already-satisfied and conditional/versioned dependencies, never the
|
|
requested package itself; reverse dependencies exclude only a genuine
|
|
self-reference where the *dependent* is the queried package) with
|
|
`qdepends`/`equery` as the tree fallback, and report an explicit unsupported
|
|
error when the tool is absent.
|
|
- **Rooting**: every catalogue, update-check and maintenance command is built
|
|
for the *intended target* — directly for `/`, or inside the target chroot for
|
|
an alternate root. Snap acts on the running daemon and is therefore reported
|
|
unavailable (and refused for mutation) for an alternate root rather than ever
|
|
touching the host.
|
|
- `sys inspect <service> --legacy` is unchanged: `inspect` always means service
|
|
inspection (use `info` for packages).
|
|
|
|
Read-only catalogue actions (`search_packages`, `list_packages`,
|
|
`package_info`, `check_updates`, `package_owners`, `package_dependencies`) need
|
|
no root and write no transaction. `apply_updates`, `depclean` and `clean_cache`
|
|
are mutating, require root, take a protective snapshot where available, and are
|
|
recorded.
|
|
|
|
### 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 |
|
|
|
|
Portage, Flatpak, Snap, Nix profile, managed AppImage and custom ebuild package changes take
|
|
a protective coordinated root/var snapshot before mutation. `sys undo`
|
|
restores a chosen snapshot on the next boot; `/home` remains outside that
|
|
snapshot. Nix `prepare` only realises a development attribute and does not
|
|
install it into a persistent profile. Direct user-managed Nix profile changes and
|
|
snapd's automatic background refreshes are outside a `sys` transaction.
|
|
|
|
## 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:
|
|
|
|
For work that takes time, the bridge emits zero or more intermediate
|
|
`{"id":17,"event":"progress","progress":{"label":"...","state":"started"}}`
|
|
messages before the final response with the same ID. A matching `completed`
|
|
or `failed` event closes each phase. Labels pass through the shared secret
|
|
redactor; command arguments, output, model messages, and credentials are not
|
|
sent to QML. The assistant displays the activity under the relevant request
|
|
or approved plan and retains it after completion. Callers must wait for a
|
|
final response rather than treating a progress event as the reply.
|
|
Malformed model JSON or typed investigation steps receive up to two bounded
|
|
correction requests. A third malformed reply returns an error; no action is
|
|
executed from that reply. Installation investigation also accepts a typed
|
|
`unavailable` result after read-only candidate discovery. If it cannot build a
|
|
validated plan, the desktop shows a read-only information card with AppImage
|
|
catalog guidance and no approval control. A catalog lead is never treated as
|
|
an installable candidate without a reviewed artifact URL and SHA-256.
|
|
|
|
- `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 a reviewed plan card for install,
|
|
removal, general administration, or a follow-up confirmation. Every plan type
|
|
carries the same `plan_id`/`digest` review and approval state; information and
|
|
clarification replies carry no execution control. Removal is AI-first by
|
|
default.
|
|
- `execute`: executes exactly the referenced reviewed plan by plan ID and plan
|
|
digest. The privileged broker repeats the full validation.
|
|
- `legacy_install`: performs deterministic installation with an explicit backend.
|
|
- `legacy_execute`: executes typed actions deterministically.
|
|
- `clear_conversation`: deletes the persisted, minimized follow-up context.
|
|
- `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 the invoking user's
|
|
package source profiles, project environment tool mappings, and
|
|
keep-existing-source pins. Personal preferences are stored 0600/0700 under the
|
|
user's own config (`~/.config/phoebus/package-preferences.toml`) without
|
|
elevation; system defaults stay root-owned. When the write runs elevated the
|
|
created paths are chowned to the initiating user, a non-root process acting
|
|
for a different user is refused, and symlinked path components are rejected.
|
|
A failed write is reported as an error, never as "saved".
|
|
- `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.
|
|
|
|
## Privileged execution boundary
|
|
|
|
A mutating plan is stored as a `PreparedPlan` in per-user storage
|
|
(`/run/user/<uid>/phoebus/plans`, mode 0700; a 0600 plan file; atomic write; a
|
|
128-bit unpredictable identifier). The plan is sealed with an integrity digest
|
|
over the reviewed fields, the target root and the initiating uid. That seal is
|
|
only a self-consistency check: the owner of the plan file can recompute it, so
|
|
it is never treated as authentication.
|
|
|
|
`execute_plan` validates the plan before elevation and again — authoritatively —
|
|
inside the privileged broker (`sys --broker --execute-plan <id> --plan-uid <uid>
|
|
--approval-digest <sha256> --root <root>`). The broker:
|
|
|
|
- **independently recomputes the canonical approval digest** from the exact
|
|
executable actions, full candidate and reviewed material effects, plus the
|
|
versioned execution envelope (id, kind, creation/expiry, root, initiating uid,
|
|
privilege, source and application), and requires it
|
|
to equal both the digest stored in the plan and the independently supplied
|
|
`--approval-digest`. Retaining an approved digest while swapping an action and
|
|
resealing is therefore rejected for every plan kind (Install, LegacyInstall,
|
|
Removal, General, Undo) before any command runs;
|
|
- carries the digest the review card showed the user across authentication
|
|
independently of the plan file, so a replacement plan under the same
|
|
identifier is rejected even when it is resealed with a valid, self-consistent
|
|
checksum;
|
|
- rejects expired, modified, malformed, wrong-root or wrong-uid plans and
|
|
approval lifetimes longer than 900 seconds; old staged plans require review;
|
|
- holds a persistent kernel flock across authoritative revalidation, all
|
|
mutations, verification and terminal recording;
|
|
- derives the initiating identity from the authenticated caller context
|
|
(`PKEXEC_UID`), treating `--plan-uid` as untrusted input;
|
|
- revalidates the current package/removal state after authentication, and again
|
|
action-by-action at the execution boundary against the reviewed effects;
|
|
- anchors consumption in a **root-owned approval ledger**
|
|
(`/var/lib/phoebus/approvals`, 0700 / 0600, ADR 0014), keyed by a stable
|
|
approval identity (plan id, canonical digest, initiating uid, target root).
|
|
The key is claimed with `O_EXCL`, so at most one execution may run under
|
|
concurrent submissions; a retry is refused even after the user deletes every
|
|
file in their own plan directory; and editing only presentation fields
|
|
(summary, rationale, verification) and resealing cannot mint a fresh record.
|
|
A newly reviewed identical operation has a new plan id and is allowed. Each
|
|
claim records its owning process; terminal statuses are published atomically
|
|
once, are immutable, and recovery only marks an owner that is provably gone;
|
|
- treats the plan file and its contents as untrusted input, resolving storage
|
|
from the uid rather than an arbitrary path.
|
|
|
|
Authentication happens outside model context through Polkit (`pkexec`), never
|
|
passwordless sudo. Cancelling or refusing authentication performs no mutation
|
|
and consumes nothing: authentication precedes the ledger claim. A failed,
|
|
stale-plan, verification-failed or interrupted operation reaches a truthful
|
|
terminal status.
|
|
|
|
Each transaction records the outcome per action (`completed`, `failed`,
|
|
`unattempted`) plus the protective snapshot, so a partial execution is visible
|
|
and never reported as success.
|
|
|
|
## Transaction truthfulness
|
|
|
|
Every mutation is recorded as an in-progress transaction **before** it runs. On
|
|
action failure, verification failure, refusal or cancellation the same record is
|
|
finished with a truthful result (`failed: …` / `verify failed: …`); completed
|
|
steps and their protective snapshot are retained. A record that never reaches a
|
|
terminal result is an interrupted operation, and its consumed plan cannot be
|
|
replayed. A malformed broker reply is a protocol failure, never fabricated
|
|
success. History persistence failures are surfaced, not swallowed.
|
|
|
|
## Conversation privacy
|
|
|
|
Follow-up context is minimized before persistence: the raw request is never
|
|
stored, only structured context (kind, application, candidate, rationale), and
|
|
registered secrets are scrubbed with the active redactor. The history file is
|
|
0600 inside a 0700 directory, written atomically, bounded to ten turns, and can
|
|
be cleared (`clear_conversation`) so it no longer informs later follow-ups.
|
|
Redaction removes known secrets; it does not claim to detect arbitrary sensitive
|
|
text, which is why raw requests are not persisted.
|
|
|
|
## 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.
|
|
`sys-lane-operations.sh` exercises real Portage, Flatpak, AppImage and Nix
|
|
mutations; `sys-custom-ebuild-operations.sh` stages, builds and removes a
|
|
harmless package; `snap-guest.sh` covers Snap first use and refresh; and the
|
|
`appimage-rollback-*` fixtures verify a non-Portage change across a detached
|
|
rollback boot. All mutation fixtures require a validated disposable qcow2 VM.
|
|
|
|
| # | 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 | System-wide policy as non-root | `set_package_preference system_wide:true` | refused: needs root |
|
|
| 17b | Personal preference as non-root | `set_package_preference` | saved to user config, no `/etc` write |
|
|
| 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 |
|
|
| 24 | Legacy unified search | `sys search firefox --legacy` | "Package catalogue", exit 0 |
|
|
| 25 | Legacy inventory | `sys list --legacy` | "Package catalogue", exit 0 |
|
|
| 26 | Legacy package information | `sys info bash --legacy` | "Package information", exit 0 |
|
|
| 27 | Legacy update check | `sys updates --legacy` | "Unified Update Overview", exit 0 |
|
|
| 28 | Legacy JSON search | `--legacy --action '{"action":"search_packages","query":"firefox"}'` | catalogue, exit 0 |
|
|
| 29 | Search without a model | `sys search firefox` (no provider) | nonzero; exact `sys search firefox --legacy` offered; nothing searched |
|
|
| 30 | Source flag constrains the AI | `sys search firefox --flatpak` (no provider) | nonzero; `... --legacy --flatpak` offered; not bypassed |
|
|
| 31 | Non-root depclean | `sys depclean --legacy` (non-root) | requires root, nonzero |
|
|
| 32 | Non-root apply updates | `sys apply updates --legacy` (non-root) | requires root, nonzero |
|
|
| 33 | Non-root cache cleanup | `sys clean cache --legacy` (non-root) | requires root, nonzero |
|
|
| 34 | Non-root source build | `sys --legacy --action '{"action":"convert_to_source","app":"firefox"}'` (non-root) | requires root, nonzero |
|
|
| 35 | Non-root tuned kernel | `sys build tuned kernel --legacy` (non-root) | requires root, nonzero |
|
|
| 36 | Brave source refusal (root, no mutation) | `--legacy --action '{"action":"convert_to_source","app":"brave"}'` (root) | nonzero, "no trustworthy source route"; refused before approval/commands |
|
|
| 37 | Unknown source refusal (root, no mutation) | `--legacy --action '{"action":"convert_to_source","app":"definitely-not-an-app-xyz"}'` (root) | nonzero, "no supported source build" |
|
|
|
|
### 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.
|
|
|
|
The read-only and failure acceptance cases (37, including the
|
|
personal-preference case and the catalogue group) are exercised by the test
|
|
suite (`installer/tests/vm/sys-acceptance.sh`); the broker approval/replay
|
|
regression is covered by `phoebus-installer` unit tests. 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, cross-source removal, catalogue parsing, per-source
|
|
failures/ambiguity, the AI-default routing contract, and the source constraint.
|
|
|
|
## 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.
|
|
|
|
## User-level agents
|
|
|
|
`phoebus-agent-run --workspace /path/to/project --tool-dir /path/to/agent/bin agent`
|
|
confines a user agent with read-only tools and an isolated network. Add `--network`
|
|
only when granting access to remote providers or host loopback services.
|
|
`--offline` explicitly retains the default network isolation.
|
|
|
|
`phoebus-mcp` runs as the desktop user over initialized stdio MCP. Its closed
|
|
desktop operations save native configuration with undo; package proposals stage
|
|
real reviewable plans and never execute them. Desktop changes need reload/restart.
|
|
See [USER-AGENTS.md](USER-AGENTS.md) for capabilities, paths and limitations.
|