feat(desktop): register existing external agent references

[camaragon]

feat(desktop): register existing external agent references

Summary

• add a keyless, device-local registry for existing external agent identities
• render registered identities in the Desktop Agents view as Externally managed cards
• support explicit registration, profile navigation, full-public-key copy, and reference-only removal
• fail closed when lifecycle/configuration commands target a registered reference

Related to #3054 and #3556.

Why

Desktop currently models locally managed agents and relay-discovered agents, but it has no explicit way to retain a display reference to an existing identity that is operated elsewhere and may not be discoverable through current relay ownership metadata.

This change adds a narrow local reference type instead of importing the identity as a managed agent. It complements the relay-discovery approach in #3556: relay discovery remains useful when verified ownership metadata exists, while an explicit local reference covers identities that must be selected directly by public key.

Safety boundary

A registered reference contains only:

• public key
• optional local label
• optional local role summary
• creation and update timestamps

It never contains or owns a private key, authorization credential, runtime, provider, model, environment, system prompt, process, or auto-start configuration.

Registered references are display/navigation metadata only. They are not added to the application-wide trusted-agent set and do not affect bot classification, mention eligibility, or configuration-message authorization. Their cards expose no Start, Stop, Restart, Deploy, model, runtime-error, auto-start, or secret controls.

Managed-agent lifecycle/configuration/delete commands validate ownership before side effects and return agent <pubkey> not found for registered references.

Storage and rollback

References are stored separately from managed agents in a restricted, atomically written JSON file. Invalid JSON is preserved and fails closed. Removing a reference deletes only the local display reference; it does not delete an identity or stop an external process.

Older builds ignore the separate reference file, so code rollback does not alter managed-agent state.

Verification

• cargo fmt --check
• cargo test registered_references --lib — 17 passed
• cargo test registered_agent_references --lib — 10 passed
• cargo test --lib — 2,608 passed, 17 ignored
• frontend unit tests — 5,104 passed
• pnpm typecheck
• pnpm check
• pnpm build:e2e
• node scripts/check-registered-agent-boundary.mjs
• focused registered-reference Playwright coverage — 4 passed

Independent implementation review found no unresolved blocking, high, or medium correctness findings.

[PabloReyes]

Hi Buzz team, @camaragon. This PR is close to a use case we have, so consider this a design question for a possible follow up, not a request to expand the current PR.

We operate agents through an external controller that governs their identity and credentials. The Nostr pubkey already gives each agent a stable identity in Buzz, but we're missing a structured, inspectable link from that pubkey to the controller's public per-agent record.

Free text such as the local roleSummary or profile about can contain a URL, but clients can't render it distinctly or tell it apart from an ordinary description. NIP-05 associates an identifier with the pubkey, but doesn't describe who governs the agent or where that governance record can be inspected.

Would you consider one optional structured field on the reference, for example { controller, uri }? It would be display-only, opened only through explicit user action, and carry no authorization or trust semantics. If absent or invalid, it would have no effect on the reference existing behavior.

This may belong on the device-local reference introduced here, or probably on the signed, relay-published side in #3556... I think that local storage can act as an operator bookmark, while a portable claim should probably be relay-published.

Happy to write up a short follow-up proposal if useful.

[camaragon]

Thanks, @PabloReyes. I think you've got the split right. A local reference can hold a bookmark, but a portable governance claim should be signed and published to the relay.

I went back through both implementations. The reference in #6321 is deliberately narrow: keyless, stored only on the current device, used for display and profile navigation. Registering one doesn't add the pubkey to the trusted-agent set, and it doesn't touch bot classification, mentions, config-message authorization, or lifecycle controls.

Given that boundary, I'd rather not add a controller field to the local reference. Even if we call it display-only, the name makes unsigned local metadata look like a governance claim, which is exactly what that type is meant to avoid.

#3556 is the better home for the portable version. It already discovers agents through signed kind:0 profiles with verified NIP-OA owner attestations. A follow-up could add controller identity and an inspectable governance URI as attested profile metadata, so clients could show a distinct "Governance record" link that opens only when the user clicks it. No permissions, no effect on trust or lifecycle.

I looked at the nearby NIPs and didn't find a clean fit. NIP-05 links an identifier to a pubkey, NIP-39 links to external-platform identities, and NIP-89 covers app handlers. NIP-46 is the closest in spirit, but it's about remote signing, not a public governance pointer. So there does seem to be a gap.

A minimal version could specify:

• the controller as a Nostr pubkey
• an absolute HTTPS URI for the public governance record
• a controller signature binding that URI to the agent pubkey, which is what makes it verifiable rather than free text
• no automatic fetching, no authorization semantics
• invalid or missing metadata simply ignored

I still think there's a real local use case here, the operator bookmark you mentioned. I'd just name it something like operatorBookmark rather than controller, so the private device-local note and the signed, portable claim never get confused for each other.

If you want to write it up, please do. I'd open a new issue and link both #3556 and this thread. #3556 is Ali's and still waiting on review, with an open pagination finding on the owner-tagged kind:0 scan, so keeping the proposal separate should make both easier to review.

[camaragon]

@block/buzz-oss-team This is ready for maintainer review. Scope is intentionally narrow: register keyless local references for existing external agents without changing trusted-agent membership, authorization, or lifecycle controls. DCO is green and the branch is mergeable.

[camaragon]

@block/buzz-oss-team This desktop agent-reference change is ready for maintainer review; all currently reported DCO checks pass. Please review when available.