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

1.9 KiB

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 for scope and verification.