phoebus_os/docs/USER-AGENTS.md
Phoebus 3b219fc851
Some checks failed
ci / test (push) Has been cancelled
fix(agents): harden both user-level agent paths
2026-10-12 07:15:31 -07:00

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.