feat(desktop): expose a secured local control API/CLI for Desktop configuration and agent lifecycle

[skillz-xx]

Motivation

Buzz has a strong agent-facing relay CLI, but the installed Desktop remains a separate, UI-only control plane for important local state. The buzz CLI can operate messages, channels, repositories, workflows, and relay-side agent drafts, but it cannot directly and reliably manage the Desktop instance that owns:

• the authenticated human identity and OS-keyring material;
• the local managed-agent registry;
• ACP runtime/harness registrations and launch arguments;
• exact provider/model/thinking/run-target settings;
• agent start/stop/restart state;
• pending owner-review requests;
• live session/runtime diagnostics and effective tool capabilities.

This becomes a practical blocker when an owner explicitly asks an agent to configure Buzz itself. Today the agent must either hand the work back to the human, edit undocumented local files, or use accessibility/pixel automation against Desktop dialogs. UI automation is fragile, difficult to make idempotent, hard to audit, and risky around one-time identity/private-key screens.

A concrete workflow on Buzz Desktop 0.5.5 required UI automation to register custom ACP runtimes, create managed agents with exact model aliases, add them to a channel, start/stop them, and inspect live runtime state. The relay CLI could handle adjacent channel operations, but not the Desktop-local configuration. A live capability check also caught a runtime whose UI configuration looked restricted while its fresh session actually exposed a broad command catalog; a structured Desktop/runtime inspection surface would make this kind of fail-closed verification much safer.

This is not a request to export the owner's private key or let a remote agent silently impersonate the owner. It is a request for a supported, local, owner-authorized automation boundary.

Proposed solution

Expose a versioned local Desktop control API, with a matching CLI namespace such as buzz desktop .... A Unix-domain socket on macOS/Linux and named pipe on Windows would keep this separate from the relay API.

Possible initial surface:

buzz desktop status --json
buzz desktop runtimes list|get|add|update|remove|probe
buzz desktop agents list|get|create-draft|update-draft
buzz desktop agents start|stop|restart
buzz desktop agents runtime|sessions|capabilities
buzz desktop approvals list|show|approve|deny
buzz desktop settings get|set

The exact command shape is non-normative. The important properties are:

1. Desktop remains the authority. Commands are executed by the running Desktop process using its existing authenticated context and keyring; keys and secrets are never returned to the caller.
2. Scoped local authorization. The owner pairs a local automation client once and grants explicit scopes such as desktop.read, agents.configure, agents.lifecycle, or approvals.request. Capabilities should be revocable and optionally time-limited.
3. Owner review for sensitive mutations. Identity creation/rotation, secret changes, permission expansion, destructive actions, and owner-signed relay mutations should still produce an exact Desktop diff for human approval. Automation can prepare and submit the draft without bypassing consent.
4. Structured, idempotent operations. JSON input/output, stable object IDs, dry-run/diff support, idempotency keys, and clear conflict/error states. No success response merely because an ephemeral request was published; report whether Desktop received, queued, applied, or rejected it.
5. Runtime truth, not only desired config. Read operations should distinguish configured harness/model/tools from the effective fresh-session values observed over ACP. This is useful for detecting adapters that ignore launch flags or silently expose additional tools.
6. No undocumented file editing. The API should reuse Desktop's validation, persistence, restart/session-invalidation, keyring, and runtime-discovery code rather than making callers mutate managed-agents.json or custom-runtime files directly.
7. Safe defaults. Local clients begin read-only; secret values are redacted; private keys are never printed; destructive or privilege-expanding operations fail closed without an interactive owner grant.

A minimal first increment could be read-only status, runtimes list/get, agents list/get/runtime, and lifecycle start/stop/restart, followed by draft-based configuration mutations.

Alternatives considered

• Continue using Desktop accessibility/UI automation: works for experiments, but is brittle across layout changes, cannot provide reliable idempotency or structured errors, and may traverse sensitive dialogs.
• Expand only relay-side buzz agents draft-*: useful (CLI: expose --mcp-command and --env on buzz agents draft-create/draft-update (GUI Advanced parity) #3115), but it cannot inspect or control Desktop-local runtime state, and current ephemeral draft delivery/owner-review behavior has separate reliability gaps (fix(desktop): buzz agents draft-create succeeds on relay but fails to trigger Desktop draft review form #3791, buzz agents draft-update silently drops a draft when one is already pending #3559, Desktop does not surface accepted agent draft-update requests #4334).
• Edit local Desktop state files directly: bypasses validation/keyring logic, is unsupported, and risks corrupting or desynchronizing runtime state.
• Use a headless agent-host/spawner instead: valuable for always-on remote seats, but does not solve automation of the owner's existing Desktop-local agents, settings, and approval surfaces.
• Expose a general remote HTTP admin API: broader and riskier than needed. A local IPC boundary with explicit owner-granted scopes is preferable.

Additional context

Installed environment used for the concrete workflow:

• Buzz Desktop 0.5.5 (xyz.block.buzz.app)
• macOS, Apple Silicon
• bundled/local buzz CLI; the current CLI has no --version option

Closest related work, but not duplicates:

• Add a configurable ACP runtime registry (or document how to attach a 3rd-party runtime like omp acp) #3399 — configurable ACP runtime registry; this request would make that registry scriptably manageable and inspectable.
• CLI: expose --mcp-command and --env on buzz agents draft-create/draft-update (GUI Advanced parity) #3115 — CLI parity for --mcp-command and --env; useful for relay-side drafts, but not Desktop-local state, lifecycle, diagnostics, or durable receipt.
• fix(desktop): buzz agents draft-create succeeds on relay but fails to trigger Desktop draft review form #3791 / buzz agents draft-update silently drops a draft when one is already pending #3559 / Desktop does not surface accepted agent draft-update requests #4334 — relay-originated agent drafts can be lost, dropped, or not surfaced; a Desktop control endpoint should report durable receipt/queue/application state.
• An agent's runtime can die silently — no signal in the channel, no way to restart it #2453 — runtime liveness and restart control; this proposal includes a structured local lifecycle surface for that narrower need.
• Show what each agent can do and whether it is ready before delegation #2931 — owner-visible capability/readiness manifests; this proposal would expose the same runtime truth through a redacted, scriptable read surface.
• feat(cli): owner-authorized management of synced sidebar categories #3590 — CLI management for one Desktop-only preference surface (sidebar categories).
• RFC: Machine-level enrollment for headless/self-host — join once, then freely create many agents (Raft-like) #3554 / feat(spawner): first-party server-hosted agents via a buzz-spawner daemon #2859 — machine enrollment and headless multi-agent hosts; complementary, not a replacement for Desktop-local control.
• RFC: App-integration agents — install a Buzz-managed agent that carries an app's own tools + scoped credentials (headless, owner-approved) #3227 — owner-approved app-installed managed-agent bundles.

Duplicate searches performed for desktop CLI, headless, local API, runtime registry, managed agent, Desktop automation, and agent create/start/stop lifecycle. No issue found for a general secured local Desktop control API/CLI.

[skillz-xx]

This was filed prematurely during an active configuration/validation run. Withdrawing it until the full agent setup is complete so the eventual report can include consolidated, verified evidence and avoid piecemeal feedback.

[skillz-xx]

Configuration and field validation are now complete across four distinct managed ACP runtimes. I have replaced the withdrawn placeholder with the consolidated, sanitized report and reopened the feature request.