External (non-desktop-managed) agents: publishing kind:10100 makes them un-mentionable — `shouldHideAgentFromMentions`'s invocability logic is unreachable

[ilporyynanen-dev]

Component: desktop
Version: v0.4.26, source at 0096d710ed2e6abab19aaf7cdc14e3ee603d7ec8

Summary

We run two headless buzz-acp agents on a server (systemd, one per team member, each on its own subscription). They authenticate via NIP-42, are relay members, join open channels via kind:9021, and
respond correctly — the server side works great.

The problem is desktop UI eligibility: for an agent the desktop does not manage, publishing a kind:10100 agent profile makes the agent disappear from @-mention autocomplete (and from the
add-member search), even when the 10100 content explicitly declares the current user invocable via respond_to: "allowlist" + respond_to_allowlist. This forces an either/or choice for external
agents:

• No kind:10100 → agent is mentionable (appears as a plain member), but is absent from the Agents directory.
• kind:10100 published → agent appears in the Agents directory, but can no longer be @-mentioned from the composer at all — and since buzz-acp subscribes to mentions, the agent becomes
  effectively unusable in channels.

Root cause

useMentions.ts:249 runs the managed-list gate before the invocability logic:

if (!isAgentIdentityInManagedList(candidate, managedAgentPubkeys)) {
  return;                       // ← any isAgent=true candidate not managed by THIS desktop is dropped here
}
if (shouldHideAgentFromMentions({ ... })) { return; }

isAgentIdentityInManagedList (agentAutocompleteEligibility.ts:57) returns false for every isAgent === true candidate whose pubkey is not in the local managed list — so the candidate never reaches
shouldHideAgentFromMentions.

But shouldHideAgentFromMentions (same file, line 67) contains carefully-written logic for exactly this case ("Option B"): show a member agent unless the relay directory gives an explicit
not-invocable signal, backed by relayAgentIsSharedWithUser, which checks respond_to === "allowlist" && respond_to_allowlist.includes(currentPubkey). Because of the earlier gate, this branch is
unreachable for every non-managed agent — the only candidates that survive the gate are managed agents, which are already unconditionally mentionable via mentionableAgentPubkeys. The invocability
check appears to be dead code, which suggests the gate ordering broke an intended behavior rather than implementing one.

The same pattern exists in the channel members add-search (MembersSidebar.tsx:285), so a non-managed agent with a 10100 profile cannot be added to channels from the UI either.

Reproduction

1. Create a headless agent: relay member, NIP-42 auth, buzz-acp with --respond-to=allowlist including user A's pubkey; join an open channel (kind:9021).
2. No kind:10100 published: user A types @ in that channel → agent appears (as a regular member); mention works; agent responds. ✓
3. Publish kind:10100 for the agent, content:

   {"name":"Agent","agent_type":"agent","respond_to":"allowlist","respond_to_allowlist":["<user A pubkey hex>"]}

4. After the directory refetch (≤5 min or app restart): @ no longer offers the agent to user A. Deleting the 10100 (kind:5, e-tag) restores mentionability.

Verified the relay serves the correct, latest-only 10100 with the allowlist fields; the raw→camelCase mapping in fromRawRelayAgent is correct; the drop happens purely in the gate above.

Expected

A directory agent whose kind:10100 declares the current user invocable (respond_to: "anyone", or allowlist including the user) should be mentionable and addable, per the logic already present in
shouldHideAgentFromMentions / relayAgentIsSharedWithUser.

Suggested fix

Let candidates that pass relayAgentIsSharedWithUser through the managed-list gate, e.g.:

if (
  !isAgentIdentityInManagedList(candidate, managedAgentPubkeys) &&
  !mentionableAgentPubkeys.has(normalizePubkey(candidate.pubkey))
) {                                                                       
return;
} 

(and the analogous change in MembersSidebar.tsx), which makes the existing Option B logic reachable while preserving the current behavior for unmanaged agents with no invocability signal.

Side notes from the same investigation (happy to split into separate issues)

• kind:5 a-tag deletion silently no-ops for plain replaceable kinds (e.g. 10100:<pubkey>:): handle_a_tag_deletion only applies coordinates for parameterized-replaceable (30000-range) kinds. The
  deletion event is accepted and stored, but the target keeps being served — surprising combination. An e-tag deletion of the latest version works.
• buzz-acp never publishes kind:0 or kind:10100 for its identity, so headless agents show as bare npubs until profiles are published out-of-band (we used buzz users set-profile + a small NIP-42
  publishing script). A --publish-profile option on buzz-acp would make headless deployments much smoother.

[v0l]

Independent reproduction on a different setup, same conclusion — and one addition to the suggested fix.

Environment: three headless buzz-acp agents under a systemd template on one Linux host, managed relay (*.communities.buzz.xyz), Buzz Desktop v0.4.26 on macOS as the client. Agents are community members (invite claim), joined open channels via kind:9021, --respond-to=allowlist with the desktop user's pubkey.

Confirmed identical behaviour, and I verified the relay side is not at fault before reaching the same code path:

• Desktop's exact call — POST /query {"kinds":[10100]} — returns all three with respond_to: "allowlist" and the user's pubkey in respond_to_allowlist.
• Channel member records are plain {"pubkey":…,"role":"member"} (no is_agent), profiles resolve with correct display_name, presence is continuously online (30/30 samples over 3 min).
• With kind:10100 published: absent from @ autocomplete. After a kind:5 deletion of the 10100 and an app restart: mentionable again as a regular member. Nothing else changed.

So the either/or is exactly as described: directory entry or mentionable, never both.

Additional suggestion: gate on ownership, not on process lifecycle

managedAgentPubkeys encodes "spawned by this app instance", which is a lifecycle fact. The thing the gate actually wants is "is this agent mine", and that's already modelled — nostr_convert.rs derives it cryptographically from a NIP-OA auth tag on the agent's kind:0:

let owner_pubkey = profile_valid_oa_owner_pubkey(ev);
is_agent: owner_pubkey.is_some(),
owner_pubkey,

and MentionCandidate already carries ownerPubkey. So alongside the mentionableAgentPubkeys escape hatch, an agent whose verified owner is the current identity could pass the gate directly:

const isOwnAgent =
  candidate.ownerPubkey != null &&
  normalizePubkey(candidate.ownerPubkey) === normalizedCurrentPubkey;

if (
  !isAgentIdentityInManagedList(candidate, managedAgentPubkeys) &&
  !isOwnAgent &&
  !mentionableAgentPubkeys.has(normalizePubkey(candidate.pubkey))
) {
  return;
}

Two reasons this matters beyond the respond_to path:

1. It covers the worst-affected configuration. respond_to: "owner-only" is the natural setting for a personal agent, and it is the one case relayAgentIsSharedWithUser can never satisfy — owner-only returns false in both branches. An owner running their own agent on a server is therefore permanently locked out of mentioning it from any client, which is the likeliest way to hit this bug.
2. It is a stronger signal. respond_to/respond_to_allowlist is self-asserted content in an event the agent publishes about itself; a NIP-OA auth tag is a BIP-340 signature by the owner's key over the agent pubkey, already verified by verify_auth_tag.

Caveat for anyone hitting this meanwhile

Adding a NIP-OA attestation today makes things worse, not better: an auth tag on the agent's kind:0 sets profile.is_agent = true, which flips candidate.isAgent and re-triggers this same drop even with no kind:10100 published. The only currently-working configuration for an external agent is no attestation and no directory entry — i.e. deliberately not identifying as an agent at all. Worth keeping in mind if the fix lands as ownership-based, since attestation would then need to become safe to publish.

[surfingdev]

Third independent reproduction — with one divergence from the original report that seems worth recording: deleting the kind:10100 did not restore mentionability for us.

Environment: three headless buzz-acp agents under systemd on a Linux VM, managed relay (*.communities.buzz.xyz), Buzz Desktop v0.4.26 on macOS. All three are community members via invite claim, joined channels, and answer correctly in channels and DMs — server side behaves exactly as described here.

Confirmed

With kind:10100 published: absent from @ autocomplete and from the add-member search, including with respond_to: "anyone" + real channel_ids, and with respond_to: "allowlist" containing the desktop user's pubkey.

Divergence

After a kind:5 e-tag deletion of all three 10100 events (verified — {"kinds":[10100]} now returns empty) and an app restart, the agents are still absent from @ autocomplete. The "no 10100 → mentionable as a plain member" half of the either/or did not hold here.

State verified at that point:

• relay serves no kind:10100 for any of the three
• channel member records are role: "member" (not bot)
• one agent has no agent_owner_pubkey at all (its NIP-OA binding never took — see below), the other two do
• none of the three are in the desktop's local managed-agents.json

By our reading of useMentions.ts:295-325, the owner-less agent should evaluate isAgent === false on every disjunct and therefore pass isAgentIdentityInManagedList untouched. It still doesn't appear, and we couldn't account for that from source alone. If there's a further condition we're missing, we're happy to dig — or to supply relay dumps.

Additional data point: is_agent is derived from owner attribution

nostr_convert/user_search.rs:23 and nostr_convert.rs:345 both set:

is_agent: owner_pubkey.is_some(),

So an external agent carrying a NIP-OA owner attestation is flagged isAgent regardless of whether it publishes kind:10100. That makes the constraint broader than the original either/or: for agents with owner attribution, dropping the 10100 does not clear the agent flag, so there is no configuration that yields both "Managed by " and mentionability.

A workaround that makes things worse

For completeness, since it looks attractive and is a trap: registering the external agent directly in the desktop's local managed-agents.json does put it in managedAgentPubkeys, and it then shows up in the Agents grid and in @ autocomplete as "agent · managed by you".

But mentioning it fails with:

Could not start agent mention: <name>: agent <pubkey> has no private key available
— the OS keyring may be unreachable. Refusing to start without an identity;
retry once the keyring is reachable.

spawn_key_refusal (managed_agents/storage.rs:164) fails closed, and the mention is never delivered. The mention path attempts a local spawn rather than routing to an already-connected agent, and there is no record field marking an agent as externally hosted — backend: {type: "provider"} selects a different local binary rather than skipping the spawn. So local registration converts "not mentionable" into "mentionable but broken".

This suggests the fix may need a second half alongside the eligibility gate: mentioning an agent the desktop does not host should route rather than spawn.

Endorsing the rest

+1 to the suggested gate change, and to --publish-profile on buzz-acp — we hit the same thing and ended up with buzz users set-profile plus a hand-rolled NIP-42 publisher for kind:10100.

One trap for anyone writing such a publisher: the relay answers the NIP-42 AUTH with its own ["OK", <auth-event-id>, …]. A publisher that exits on the first OK never sends its event and still reports success. Match OK against the id you sent.

[DougButdorf]

Fourth independent reproduction — same root cause, still present in v0.5.0 (released 2026-07-28) and current main. A few new data points that may help the fix:

Environment: self-hosted relay (latest main, GHCR image) on a VPS; external agent is a Hermes Agent runtime (not buzz-acp) on the same host, bridged over WSS (NIP-42 auth as the agent key, per-channel REQ {kinds:[9], "#h":[ch]} subscriptions, mention/DM → remote runtime → kind:9 reply with NIP-OA auth tag). Desktop v0.5.0 on Windows 11 as the client. Agent onboarding: invite claim → agent_owner_pubkey set → kind:0 profile → self-authored kind:10100 (respond_to: "anyone") → kind:9021 self-join of open channels.

Same conclusion: isAgentIdentityInManagedList runs as a pre-emptive gate in addCandidate (useMentions.ts) and drops any isAgent=true candidate not in the local managed list, so relayAgentIsSharedWithUser / shouldHideAgentFromMentions are unreachable for external agents in the channel composer. The agent responds correctly when p-tagged via API — it's purely a desktop eligibility gap.

New data points:

1. channel_ids (snake_case) is the field the eligibility check actually reads. fromRawRelayAgent maps channelIds: agent.channel_ids ?? [], and relayAgentIsSharedWithUser checks channelIds ∩ sharedChannelIds. A 10100 card with only channels is silently treated as "shares no channels" — worth documenting (or aliasing) alongside any gate fix.
2. The DM recipient picker is NOT affected — useNewMessageRecipients.ts builds eligibleAgentPubkeys via getMentionableAgentPubkeys and includes invocable relay agents as DM candidates. So once the 10100 card has correct channel_ids, users can open DMs with external agents; only the channel composer @-mention is blocked. DMs with a DM-exempt bridge make this a usable partial workaround that keeps the agent identity intact.
3. Re @surfingdev's wrinkle (deleting the 10100 didn't restore mentionability): the member-candidate isAgent flag has multiple OR-ed sources (member.isAgent, profile?.isAgent, directory membership). If agent_owner_pubkey (NIP-AA classification) is still set relay-side, the identity stays isAgent=true and the managed-list gate keeps dropping it even after the 10100 is gone. The full masquerade requires deleting the 10100 and clearing the owner classification — at which point the agent loses its badge/directory presence everywhere, which defeats the purpose for those of us running external agents as agents.

Happy to test a patch against our setup. The bridge side is solid — p-tag delivery, DM fan-out, and NIP-OA provenance all verified end-to-end; the only missing piece is the composer letting a human type the mention.

[greenpeppers100]

Independent reproduction, plus a second trigger that the suggested fix wouldn't cover.

Setup: three headless buzz-acp agents (Claude Code via @agentclientprotocol/claude-agent-acp) under systemd on a server, relay built from 90e058ebf, Buzz Desktop v0.5.0 on macOS. Same symptom — DMs work, the agents appear in the channel member list, but they're absent from @ autocomplete.

Ours declared respond_to: "anyone" rather than allowlist, so the gate isn't specific to allowlist mode. An authenticated POST /query confirmed the relay served the correct latest-only kind:10100; the drop is entirely client-side, as you describe.

Second, independent trigger: a NIP-OA-tagged kind:0, with no kind:10100 at all

useMentions.ts:317 ORs five sources into isAgent:

isAgent:
  member.isAgent === true ||
  profile?.isAgent === true ||
  member.role === "bot" ||
  managedAgentNamesByPubkey.has(pubkey) ||
  relayAgentNamesByPubkey.has(pubkey),

Two of these fire for external agents:

• relayAgentNamesByPubkey.has(pubkey) — presence of a kind:10100 alone sets isAgent, regardless of its content.
• profile?.isAgent — derived from profile_valid_oa_owner_pubkey (nostr_convert.rs:64), i.e. a NIP-OA auth tag on the kind:0 event. This is client-side verification of the tag, not the relay's users.agent_owner_pubkey column.

The second matters operationally because buzz-cli injects BUZZ_AUTH_TAG into every signed event. An operator who sets BUZZ_AUTH_TAG (as the ACP harness does for managed agents) and then runs buzz users set-profile ends up with an auth-tagged kind:0 — and the agent becomes un-mentionable with no kind:10100 published anywhere. We hit both triggers in sequence and misattributed the second to the first for a while, because deleting the 10100 alone didn't restore mentions.

Why this affects the suggested fix

The proposed mentionableAgentPubkeys bypass keys on the relay directory, so it rescues agents that publish a kind:10100 declaring the current user invocable. But an agent with an auth-tagged kind:0 and no 10100 is isAgent: true while absent from mentionableAgentPubkeys, so the gate still drops it — even though shouldHideAgentFromMentions would show it under "member, not in directory ⇒ unknown invocability ⇒ show".

Removing the managed-list gate from the mention path entirely, and letting shouldHideAgentFromMentions be the single policy, covers both triggers. Comparing the two, the only candidates whose outcome changes are exactly the ones #1611 intended to change: directory-present-and-invocable (now shown, currently hidden) and member-but-not-in-directory (now shown, currently hidden). Non-member non-invocable agents stay hidden either way.

Workaround

For anyone else blocked on this: delete the kind:10100 with a kind:5 carrying an e tag (the a-tag no-op you noted in the side notes does bite here), republish kind:0 with BUZZ_AUTH_TAG unset, and keep the agents as direct relay members rather than NIP-OA delegates. Mentions then work normally. The cost is the agent badge and the owner control commands (!shutdown / !cancel / !rotate), since those need a registered owner.

+1 on a --publish-profile option for buzz-acp — with the caveat that until this is fixed, publishing a profile is precisely what breaks mentionability.