6.2 KiB
User-level agents
Phoebus has two user-level agent paths as well as the privileged administration broker. This review and implementation cover both user paths. The earlier system boundary review covers the broker separately.
Implemented boundaries
| Path | Capabilities | State and failure behavior |
|---|---|---|
Workspace agent (phoebus-agent-run) |
Selected workspace writable; explicit --tool-dir directories read-only; fixed /usr/bin/bwrap; no root; isolated network by default |
Synthetic home and cleared environment; directories pinned by descriptors; launch refuses invalid grants or unavailable isolation |
Desktop MCP (phoebus-mcp) |
Closed native theme/keybinding operations; bounded theme read; checkpoint undo; inspected package-install proposals | Actual desktop uid and owned home; strict schemas and initialized protocol session; no elevation or package execution |
| Desktop assistant bridge | Existing typed review/execution flow and personal preferences | Compatible handshake before readiness; bounded reconnects; pending requests fail without replay; CLI and desktop conversation files separate |
| Personal persistence | Preferences, alerts and bounded conversation context | Descriptor-based private atomic writes; kernel uid for unprivileged callers; no shared temporary-home fallback; concurrent conversation writes serialized |
Networking is a capability grant: --network shares the host network namespace,
including loopback services. It is required for remote providers and host local
model services; it is not an endpoint allowlist. Authentication and a narrow
host-held agent transport remain separate work. Do not grant the whole home,
host runtime directory or system bus to make a jailed client connect.
Native desktop changes
The old MCP implementation wrote unused DMS/Mango files and returned a fictitious
system proposal. Theme patches now update .config/DankMaterialShell/settings.json
(matugenSeedColor and dynamic theme selection), and
.local/state/DankMaterialShell/session.json (isLightMode, wallpaperPath).
They preserve unrelated JSON fields. Keybindings update Mango's native
.config/mango/config.conf, preserving the default configuration when creating
an initial personal file. Allowed actions are a fixed desktop catalogue;
arbitrary shell commands are refused.
The formats follow the shipped defaults and upstream DMS settings, DMS session data and Mango configuration. Saving requires a desktop reload/restart to consume changes. Live IPC reload and visual appearance have not been verified by this work.
Private undo journals live in .local/state/phoebus/desktop-checkpoints, bounded
to 64 completed checkpoints. The journal is durable before any configuration
write. Undo restores exact previous bytes or absence, checks every affected file
before restoring anything, and refuses external edits. Interrupted writes keep
recovery evidence; a full journal refuses another change until undo makes room; successful undo removes its journal. Old checkpoints for the
previous unused formats are not migrated.
system_propose_action resolves and stages actual package-install plans through
the shared planning service and per-user plan store. It returns the rendered
review, identifier, approval digest and authorization argument vector. The MCP
server never executes that vector. Service-management and other unsupported
verbs are refused explicitly.
Conversation and bridge recovery
Desktop context uses desktop-conversation.json; CLI context uses
conversation.json. Each retains ten minimized turns, reads at most 1 MiB,
redacts registered secrets from nested candidate/alternative fields and publishes
atomically with mode 0600 under a private directory. A persistent lock serializes
append and clear. Elevated processes refuse to mutate another user's conversation
state, avoiding root-owned history and lock files. Future timestamps and ambiguous negative/backend-comparison
phrases do not become implicit backend switches. The existing plan/digest approval
requirements still apply to contextual confirmation.
The QML bridge becomes ready only after protocol version 1 handshake. Process exit fails pending work once, attempts at most three reconnects, and does not replay a possibly executing operation. Stable operation resets that retry budget; manual reconnect remains available. Conversation clearing preserves the visible messages if backend clearing fails. Raw malformed stdout/stderr is not printed into the application console.
Delivery and verification
Build/static targets include installer, sys, phoebus-agent-run and
phoebus-mcp. Live media and installed runtime stage all four together;
installation refuses missing companion binaries before copying sys.
Bubblewrap is an explicit base package dependency.
The complete gate passes 991 Rust tests and 22 harness safety tests. Three Node checks evaluate the shipped QML JavaScript handlers. Real host developer and user-model denied-operation checks pass. Dynamic/static release builds and strict Clippy pass; final verification is recorded in STATUS and HANDOFF.
Gentoo disposable-overlay run serial-boot-20261012T141203Z-b2ac2870 passed
11/11 driver checks: protocol lifecycle, native settings/exact undo, external-edit
refusal, workspace/read-only tools/private-home isolation, default and explicit
network grants, root refusal and desktop/CLI context separation with elevated-write refusal,
plus boot/login/poweroff. The tracked fixture
is installer/tests/vm/user-agent-guest.py. No model or account credentials were
used; the preserved base image and existing ISO were unchanged.
Remaining acceptance: a fresh installation with the new companion bundle; visual theme reload and real-seat QML behavior; actual-provider agent workflows; and a narrow host-held MCP/credential transport. A MCP server launched inside the workspace jail operates on its synthetic home, not the host desktop. No generic user-agent scheduler or unrestricted host automation is introduced.