fix(desktop): make remotely hosted agents mentionable from other machines

[TanskiSzymon]

Related work

Reported in #3277, #2950, #2987 and #2603. Client-side fixes for the same
symptom are proposed in #2605, #2893, #3292, #3472 and #3676 — this PR differs
in also publishing kind:10100, without which the directory those fixes read
from stays empty (see #3277 for relay-layer confirmation). The Rust half here
is separable and can be rebased on top of whichever client-side fix maintainers
prefer.

Problem

An agent hosted on one machine cannot be @-mentioned from another. This makes the
"run an agent on a always-on box, talk to it from your laptop" setup impossible,
and the failure is silent: the agent shows up in the member list with a presence
dot, but never appears in mention autocomplete and never answers.

Three independent causes, each sufficient on its own.

1. Remote agents were filtered out before the directory rules ran.

useMentions adds relay-directory agents as candidates with isAgent: true, and
the very next filter — isAgentIdentityInManagedList — dropped every agent not in
managedAgentPubkeys, i.e. not running locally. shouldHideAgentFromMentions,
which implements the actual directory rules, could never be reached for a remote
agent. The two are contradictory: one path adds them, the next removes them.

2. Nothing published kind:10100.

list_relay_agents queries kind:10100 and getMentionableAgentPubkeys derives
mentionability from it, but no code path in the desktop or the harness ever wrote
that kind. The directory is empty in every deployment, so the discovery path it
backs is dead code in practice.

3. respond_to: anyone was decided from a source only the agent's host can write.

anyone means "any member of a channel I am in". The check asked the agent's own
directory entry whether it shares a channel with the reader — but only the machine
holding the agent's key can update that entry. It is empty for an agent that has
not republished since starting, and stale whenever someone else changes the agent's
channels. Visibility therefore depended on whether a third party's laptop happened
to refresh in time.

Changes

• Pass the already-computed mentionableAgentPubkeys into
  isAgentIdentityInManagedList so directory-advertised agents survive the gate.
  The parameter is optional; MembersSidebar, where restricting to locally managed
  agents is intended, is unchanged.
• Publish the agent's kind:10100 entry from probe_agent_relay_access, which
  already runs per (agent, community) on start and already queries the agent's
  kind:39002 memberships — no extra round trip, and it is signed with the agent's
  own keys as consumers expect.
• Refresh that entry when the agent joins a channel, and on directory reads
  (throttled per agent), so it does not stay channel-less after creation.
• Accept the open channel's membership as an equally valid signal for anyone.
  The client already holds it and it is correct the moment the agent joins;
  the directory entry remains as the second source. owner-only and allowlist
  are unaffected — presence in a channel never widens who may instruct an agent.
• Document the behavior where users choose it, under "Who can send instructions".

kind:10100 carries two contracts

Worth flagging for review. The client reads name, respond_to and channel_ids
from this kind, while the relay's handle_agent_profile requires
channel_add_policy and fails the whole side effect without it:

ERROR Side effect failed: kind:10100 missing channel_add_policy field

So an entry written for the client is rejected by the relay, and vice versa. This
is likely why the directory was never populated. The entry here satisfies both,
publishing owner_only — the relay's own default, so behavior is unchanged. A
cleaner fix is to split the concerns, but that is a protocol change and out of
scope here.

Testing

• desktop: 3889 unit tests pass, including new cases for the eligibility gate,
  membership-beats-stale-directory, and that presence never overrides owner-only.
• desktop/src-tauri: agent_events 11/11, covering the entry shape,
  channel_add_policy, snake_case wire format, and channel-id extraction.
• cargo clippy --all-targets -- -D warnings clean; biome check clean.
• Verified end to end on a self-hosted relay across two machines: an agent running
  on a Mac mini is mentionable and answers from a second laptop, under both
  anyone and allowlist, while owner-only stays private.

Note on kind:39002

channel_ids are read from the d tag. AGENTS.md says channels use h tags,
which holds for message events but not for membership events — kind:39002 is
addressable and carries the channel in d, the same shape get_channels relies
on. Calling it out because the guidance reads as universal and cost me a debugging
cycle.

[lolamathematician]

I can offer windows testing of this fix. See: #3277 (comment)

[wrdodd]

Independently traced this on main and can confirm all three causes — in particular #2, which is what makes the gate-only fixes inert.

The only production writer of kind:10100 on main is cmd_set_add_policy (crates/buzz-cli/src/commands/channels.rs:1005), and it publishes {"channel_add_policy": policy} — nothing else. No respond_to, no channel_ids, no name. Everything downstream then degrades to a non-signal:

• agents_from_events defaults a missing channel_ids to [] (desktop/src-tauri/src/nostr_convert.rs:473)
• fromRawRelayAgent maps a missing respond_to to null (desktop/src/shared/api/tauri.ts:684)

So relayAgentIsSharedWithUser returns false on both of its branches for every entry the directory can currently contain, getMentionableAgentPubkeys collapses to the managedAgentPubkeys it was seeded from, and a patch that only widens the addCandidate gate to consult mentionableAgentPubkeys admits exactly the set the old gate already admitted.

Searched all of main for 10100 and KIND_AGENT_PROFILE: 13 files, and the only writers are the CLI policy command above and crates/buzz-test-client/tests/e2e_relay.rs. The agent harness crates have no hits at all — nothing publishes an agent's own profile.

For triage, the open queue splits along exactly that line. Most of the PRs address the gate half; I read #4058 closely and it is inert on its own for the reason above, and the same argument applies to any gate-only change. #3708 is deliberately scoped to the publisher half and states the same finding ("nothing has ever written to it... a no-op in practice"). This PR is the only open one I found that closes both halves in a single change.

So the shortest path to a user-visible fix is either this PR, or #3708 plus one gate PR. Either way the publisher half cannot be skipped. Six open issues describe the resulting symptom: #2508, #3125, #3277, #3671, #3809, #3971.

Reported by a user hitting this in a multi-machine setup: agents show in the member list with presence, but never appear in autocomplete from any machine other than the host.

[TanskiSzymon]

Thanks — Windows testing would be genuinely useful. I only verified this on macOS (Apple Silicon and Intel), across two machines against a self-hosted relay, so a third platform closes a real gap.

Coming back to this with the context I should have gathered before opening: there are already several PRs against the same symptom — #2605, #2893, #3292, #3472, #3676 — plus #2603, #2950, #2987 and #3277 describing it. I didn't check first, which was my mistake.

Having read through them, one difference is worth flagging, and it's the reason this one is larger:

Every other PR fixes only the client side. They correct the gate ordering in useMentions / agentAutocompleteEligibility so a directory agent survives eligibility. None of them touch the Rust side, so nothing publishes kind:10100 — which matches what @surfingdev noted in #3277 ("the client change alone is a no-op without the 10100 publish") and what @rrickels confirmed at the relay layer.

This PR does both halves:

• publishes the agent's kind:10100 entry from probe_agent_relay_access, reusing the kind:39002 query it already makes;
• satisfies both contracts that kind currently carries — the client reads respond_to/channel_ids, while the relay's handle_agent_profile requires channel_add_policy and logs Side effect failed without it. That conflict is likely why the directory stayed empty everywhere;
• treats channel membership as an independent proof of reachability for respond_to: anyone, so eligibility no longer depends on whether the agent's host refreshed its entry in time. That last part also removes the failure mode the client-only PRs still have: an agent whose directory entry is empty or stale is hidden rather than shown, because directory presence without invocability reads as an explicit exclusion.

Verified end to end on a self-hosted relay: an agent running on one machine is mentionable and answers from a second, under anyone and allowlist, while owner-only stays private.

I'm not attached to this being the PR that lands. If maintainers prefer #3676's client-side shape, the Rust half here is separable and I'm happy to rebase it as a follow-up on top of whichever client fix is chosen — the two are complementary, not competing. @Shipitrealgood, happy to coordinate if that's useful.

One thing I'd flag for whoever picks this up: AGENTS.md says channels use h tags. That holds for message events but not for kind:39002, which is addressable and carries the channel in d — the shape get_channels already relies on. I read it as universal and it cost me a debugging cycle.

[wrdodd]

Two additions, both verified against main.

The channel_add_policy conflict checks out, and #3708 hit it independently. handle_agent_profile (crates/buzz-relay/src/handlers/side_effects.rs) bails with kind:10100 missing channel_add_policy field when the field is absent, so any publisher omitting it gets its side effect rejected while the event itself is still stored — exactly the "stored but never applied" shape you describe.

#3708 is the other open PR on the publisher half; it is not in the duplicate list above, and it solves this by reading the agent's prior record back rather than sending a fixed default:

pub(super) fn existing_channel_add_policy(events: &[nostr::Event]) -> String

with the stated reason that a fixed value would "rewrite an operator's deliberate owner_only or nobody choice every time the agent starts." Two authors converging on the same constraint from different directions is decent evidence the diagnosis is right, and if you do split the Rust half here, that read-back is worth carrying over.

The AGENTS.md issue is a real doc bug. Verbatim on main:

146: **Channel scoping**: Channels use `h` tags (NIP-29 group tag), not `e` tags.
147: Filters and queries must scope to `h` tags when operating within a channel.

No carve-out for addressable kinds, so reading it as universal is the natural reading. Worth a one-line PR so the next person does not lose the same cycle.

[TanskiSzymon]

You are right on both counts, and #3708 changes what I think should happen with this PR.

I missed #3708 when I looked for prior work. It solves the publisher half properly, and the read back of the prior channel_add_policy is the part I got wrong. My DEFAULT_CHANNEL_ADD_POLICY = "owner_only" silently rewrites an operator's deliberate nobody or owner_only choice on every agent start. That is a real bug in my code, not a stylistic difference, and it would have shipped quietly because the relay accepts the write and logs nothing. Publishing an offline record on stop is also something I did not handle at all.

So I am not going to argue for my Rust half. #3708 does it better, it came first, and it comes from the person who reported the issue. If maintainers want the publisher, that is the one to take.

What I would like to check before deciding what is left here: does any open PR treat channel membership as an independent proof of reachability for respond_to: anyone?

The reason I ask is that publishing the directory record is necessary but not sufficient. A record published at agent start is always channel less, because kind:39002 memberships do not exist until the harness first connects. That empty record then reads as an explicit not invocable signal in shouldHideAgentFromMentions, so the agent ends up hidden rather than shown, which is worse than having no record at all. I hit this during testing and it looked exactly like the original bug.

My last commit sidesteps it by accepting the open channel's membership as sufficient for anyone, since the client already holds that data and it is correct the moment the agent joins. The directory record stays as a second source. owner-only and allowlist are untouched, with a test pinning that presence in a channel never widens who may instruct an agent.

If that idea is already covered somewhere in the queue, I will close this and there is nothing lost. If it is not, I would rather strip this PR down to just that piece on top of #3708 than keep a competing publisher around.

On the doc bug, I will open a separate one line PR for AGENTS.md. It is uncontested and it does not need to wait for any of this to be resolved.

[Shipitrealgood]

@TanskiSzymon "What I would like to check before deciding what is left here: does any open PR treat channel membership as an independent proof of reachability for respond_to: anyone?"

Yes — open PR #3676 treats channel membership as independent reachability for respond_to: anyone.

How it is handled there

#3676 rewrites Desktop shouldHideAgentFromMentions (and drops the managed-list pre-gate on the @ path in useMentions). For external (non-managed) agent-classified candidates the rule is:

• Not a channel member → hide (add-via-mention left out of scope).
• Member, then consult the kind:10100 policy map:
  • anyone → offer — no check of directory channelIds / "shared channel" geometry. Membership is the reachability proof.
  • allowlist → offer only if the viewer is on the list (membership does not widen this).
  • owner-only → offer only if the viewer is the NIP-OA-verified owner (membership does not widen this).
  • No directory declaration → offer only to that verified owner (not "show everyone").

Local managed agents stay always offerable (native path), membership not required.

So the race you hit — a start-time record with empty channelIds reading as explicit not-invocable — does not apply under #3676: member + anyone shows, even when the 10100 has no channelIds yet. The field isn't an input on the mention path.

This also satisfies the four-row fixture table in #3277 (mira hidden, quinn hidden, remote anyone member shown, managed shown) — while replacing the one signal in that issue's sketched rules that would still race, since both derive "shared channel" from the directory's channelIds.

Before closing, worth a pass with @4dlt against #3708 on three things here:

1. The membership-change refresh triggers — the add_channel_members hook and the throttled refresh_agent_directory_entries before directory reads — aren't in fix(desktop): publish kind:10100 agent profile directory records #3708 or anywhere else in the queue. fix(desktop): publish kind:10100 agent profile directory records #3708 publishes on create/start/stop, so a membership change after start isn't reflected until restart, and one made from another device is something the hosting machine can't observe locally at all. Still relevant under any eligibility PR: surfaces with no member list in hand (new-message recipients, the projects agent prompt — and mentions on main today) decide from the record's channel overlap.

2. If the triggers are kept, two things in this refresh path to look at when rebasing: it rebuilds the record with the fixed owner_only default (the clobber you called out above), and it hardcodes status: "online" with no is-running filter — which would flip fix(desktop): publish kind:10100 agent profile directory records #3708's offline record back on the next directory read. (fix(desktop): publish kind:10100 agent profile directory records #3708's publish_agent_directory takes status as a parameter and does the channel_add_policy read-back.)

3. The RespondToField copy is orthogonal to the eligibility question — same category as your AGENTS.md one-liner.