phoebus_os/docs/adr/0016-user-agent-capabilities.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

41 lines
1.9 KiB
Markdown

# ADR 0016: Explicit user-agent capabilities and recoverable personal changes
- Status: accepted
- Date: 2026-10-12
## Context
Workspace agents and the desktop assistant are user-level clients, distinct from
the privileged broker. The existing MCP desktop files were not consumed by the
shipped desktop, system proposals were not durable plans, user-installed agents
could not be granted narrowly, and reconnects/history persistence lacked adequate
failure handling.
## Decision
Keep workspace write authority explicit, expose user-installed tools through
read-only directory grants, and isolate networking by default. Fixed Bubblewrap
and descriptor-pinned mounts are mandatory. Shared networking is an explicit
capability, including host loopback access.
Use native desktop formats behind closed schemas and a fixed action catalogue.
Journal before mutation, retain recovery records, and refuse undo over external
edits. Stage package proposals using the existing reviewed-plan service without
executing or authenticating from MCP.
Separate desktop and CLI follow-up context; use bounded private descriptor-based
storage and serialize appends/clears. Recover bridge availability with compatible
handshakes and bounded retries, without replaying pending work. Bundle both user
binaries with the installer/runtime and explicitly install Bubblewrap.
Serialize descriptor inheritance around all executor process spawns. Lock release
waits for in-flight fork/exec transitions; intentional worker leases retain the
mutation lock after broker death.
## Consequences
Remote agents need explicit network grants. Existing unused desktop settings and
checkpoints are not migrated. Native settings require reload; a safe live IPC and
host-held authenticated MCP transport need separate implementation and acceptance.
The jail never receives the host home or runtime as a connectivity shortcut.
See [USER-AGENTS.md](../USER-AGENTS.md) for scope and verification.