RFC: App-integration agents — install a Buzz-managed agent that carries an app's own tools + scoped credentials (headless, owner-approved)

[adamazad]

Summary

A stable, scriptable way for a third-party app to install a Buzz-managed
agent that carries the app's own tools + a scoped credential — so the agent
does real domain work (not just chat) while Buzz hosts + supervises it. Today a
managed agent (Fizz/Bumble/Honey) is a general assistant with no app tooling, and
the only way to give one app-specific tools + secrets headlessly is blocked.

Concrete use case (what drove this)

Figura is a design tool. We wanted a Buzz-native Figura agent: mention it in a
channel → it builds an on-brand UI mock ("fig") and replies with a link, answers
"what figs do we have?" via our CLI, iterates on a fig in-thread. That needs the
agent's harness to carry:

• the figura CLI + /fig skill (its tools),
• a scoped team token (which team's brand + where figs land),
• a persona/system prompt.

A builtin:fizz-style managed agent can't do this — it has no Figura tooling or
credential. So we ended up shipping a self-hosted daemon (own Nostr key,
channels add-member, launchd) as a workaround. That works, but:

• It doesn't scale to co-hosts. If two teammates each run the daemon in the
  same channels, both fire on @figura → duplicate replies, duplicate figs, each
  burning its own model subscription. There's no cross-daemon dedup. A single
  Buzz-managed agent per community would solve this by construction.

Why the managed path is blocked today

1. Managed agents can't carry app tools + secrets headlessly. Desktop's
   Create-agent → Advanced sets runtime.mcpCommand + env_vars, but the CLI
   agents draft-create path is a deliberately no-secret owner-review contract
   (parseAgentManagementRequest drops any secret-shaped/unknown key). So an app
   installer can't hand over a token/tool via the draft. (CLI: expose --mcp-command and --env on buzz agents draft-create/draft-update (GUI Advanced parity) #3115 tried the CLI flag
   and ran into exactly this.)
2. Headless provisioning needs a Desktop-minted attestation. draft-create
   requires BUZZ_AUTH_TAG (NIP-OA owner attestation), which only Desktop mints —
   there's no CLI to produce it. So the flow can't run from an app's setup.
3. The deep-link prefill (feat(deep-link): add buzz://install-agent prefill arm #2911) still routes to the owner's Desktop form and
   isn't in released builds.

Net: there's no path for "app X installs its working agent into my community" that
carries X's tools + a scoped secret, with owner approval but without hand-walking
the GUI.

Ask

A stable extension point to register/install a managed-agent bundle:

{ personaId, displayName, systemPrompt,
  harness,                       // e.g. claude-code
  tools: { mcpCommand | mcpServers },
  credentials: [ vaultRef ],     // scoped secret, egress-substituted, never in the
                                 // owner-review draft or the sandbox
  defaultChannels }

• Owner-approved, not owner-hand-authored. The owner still consents (one
  approval), but an app can prefill the whole bundle headlessly.
• Secrets handled safely — a vault/secret-ref the harness resolves at egress,
  distinct from the no-secret draft contract (so CLI: expose --mcp-command and --env on buzz agents draft-create/draft-update (GUI Advanced parity) #3115's boundary stays intact).
• This is the layer beneath the marketplace (RFC: Cross-community agent marketplace (discovery + install) built on the shared-persona catalog and buzz://install-agent #2958): the marketplace discovers/
  installs; this defines what a working, tool-carrying installed agent IS.

Relates to

• RFC: Cross-community agent marketplace (discovery + install) built on the shared-persona catalog and buzz://install-agent #2958 — Cross-community agent marketplace (discovery/install)
• RFC: Stable extension points for downstream integrations and distributions #2754 — Stable extension points for downstream integrations (MCP tools + agent lifecycle is one bullet; this is the concrete agent-bundle case)
• CLI: expose --mcp-command and --env on buzz agents draft-create/draft-update (GUI Advanced parity) #3115 — CLI --mcp-command/--env (blocked by the no-secret draft contract)
• feat(deep-link): add buzz://install-agent prefill arm #2911 — buzz://install-agent deep-link prefill

Happy to share the Figura self-hosted-daemon design as a reference for what a
managed equivalent would need to replace.

[asymetryk]

Thanks for opening this RFC. I’m implementing a self-hosted Agent Workforce where Buzz is the human collaboration, approval, and provenance surface, while an external AgentInfra control plane owns credential and token lifecycle.

A separation that looks important in practice is:

• Connection — how Buzz/agents can reach a provider (Google OAuth, Microsoft OAuth, SMB credentials, S3 keys, etc.). Buzz should retain only a logical vaultRef/secret handle, never the credential itself.
• Data source — the bounded thing being made available (a mailbox, calendar, Drive folder, network share, bucket, database, and so on).
• Grant — which agent or workflow may use that data source, for which verbs/risk classes, under which approval policy, and until when.
• Agent/app — consumes an approved grant and receives a scoped capability, not a reusable raw token.

The corresponding human loop belongs naturally in Buzz: connection readiness, re-auth requests, permission approvals, failures, and receipts in the Inbox; capability/readiness visibility on the agent before delegation.

This seems closely related to #2282, #2754, #2931, and draft #3275. Would maintainers prefer the Connection / Data Source / Grant contract to be developed inside this RFC, or as a separate focused RFC that this issue can depend on?

I’m going to prove a private metadata-and-policy MVP first without migrating existing provider tokens, and I’d be glad to bring back the schema and implementation lessons before proposing small upstream PRs.

[asymetryk]

Update after proving the private metadata-and-policy MVP end to end:

We now have a working pilot where a native Buzz mention routes to an external agent runtime, the runtime discovers only its assigned connection alias, and a separate connection plane authorizes access to one bounded data source. In the pilot, the agent could list its connection, search one Gmail mailbox, and read one result. The same identity was denied create, update, delete, and send; unsigned calls and unassigned aliases also failed closed. The decision audit recorded search/read and zero mailbox mutations.

What held up well in practice:

• Connection is a specific authenticated account, not a provider singleton. Multiple Google accounts and Microsoft consumer/Microsoft 365 accounts remain independent.
• Data source is the bounded resource behind it: mailbox, calendar, folder, share, bucket, database, or API.
• Grant binds an agent or workflow to that data source, an operation set, an approval mode, and optionally an expiry.
• The agent receives an alias plus effective operations, never the OAuth token or broker handle.
• Readiness requires fresh provider readback bound to the verified principal (and tenant for Microsoft 365), not merely the presence of a credential.

A minimal Buzz-facing management surface could therefore be three views:

1. Connections — connect/reconnect accounts, show provider identity, readiness, last verification, and exposed data sources.
2. Agent access — an agent × data-source matrix with per-operation policy: standing access, ask every time, or blocked.
3. Activity — privacy-safe allow/deny decisions, re-auth requests, approvals, and signed execution receipts.

The smallest upstream boundary does not need Buzz to become the vault. It could be:

• a typed, non-secret Connection/Data Source/Grant manifest;
• stable owner approval and re-auth events with idempotency identifiers;
• signed readiness/execution receipts;
• an extension surface that can render the management UI, potentially building on the MCP Apps/channel-tab work in feat(desktop): host MCP Apps as channel tabs #3275 and the custom-harness MCP sidecar work in feat(desktop): support MCP sidecars for custom harnesses #4078.

The attached concept is intentionally operational rather than a decorative dashboard. It shows multiple accounts, data-source readiness, and explicit per-agent verbs without exposing credential values.

Would maintainers prefer this as a focused RFC that #3227 depends on, or should the contract continue to develop directly in this thread? I can share a reduced schema, decision examples, and tests from the private pilot without including provider credentials or deployment-specific internals.