95 lines
6.2 KiB
Markdown
95 lines
6.2 KiB
Markdown
# 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](AGENTIC-HARDENING.md) 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](https://github.com/AvengeMedia/DankMaterialShell/blob/master/quickshell/Common/SettingsData.qml),
|
|
[DMS session data](https://github.com/AvengeMedia/DankMaterialShell/blob/master/quickshell/Common/SessionData.qml)
|
|
and [Mango configuration](https://github.com/DreamMaoMao/mangowc/blob/main/config.conf).
|
|
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.
|