docs(user-guide): add annotated recommended default settings for Buzz adapter - #72161
Closed
rob-coco wants to merge 6 commits into
Closed
docs(user-guide): add annotated recommended default settings for Buzz adapter#72161rob-coco wants to merge 6 commits into
rob-coco wants to merge 6 commits into
Conversation
Plugin-path adapter (zero core changes) connecting Hermes to a Buzz community relay via the buzz CLI binary (JSON in/out, arg-list exec, key passed via env only). Inbound uses a poll loop with per-channel high-water marks seeded from newest (no history replay), event-id de-dupe, self-echo suppression by pubkey, and mention gating in channels (DMs always dispatch). Registers env_enablement, cron home-channel delivery, and an out-of-process standalone sender, mirroring the IRC plugin. Verified against a live relay: connect -> send -> poll -> MessageEvent round-trip, self-echo suppressed, clean disconnect. Known limitation: polled inbound (default 4s); a websocket transport (buzz-ws-client) is a future optimization. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The Buzz adapter's check_requirements() reads config from env only, so a config.yaml-only setup (relay URL in gateway.platforms.buzz.extra) failed the check_fn gate and was silently skipped at startup. Add an apply_yaml_config_fn hook that bridges buzz.extra -> BUZZ_* env vars, mirroring the Slack/Telegram pattern; BUZZ_PRIVATE_KEY stays a .env secret. Also fix send_reaction() to use buzz-cli's real flags (--event <id> --emoji), replacing the non-existent --channel/--message-id flags that would have failed on every message. Verified live against the hosted relay (accepted:true). Refs NousResearch#68871
Channel messages address the agent with a leading @mention (e.g. '@chip /whoami'). The adapter passed the raw content through, so the gateway's is_command() check (text.lstrip().startswith('/')) never matched and slash commands were routed as plain chat. Strip a leading mention (name, npub, or hex form) before dispatch in channels, mirroring the Discord adapter. Also cleans normal prompts ('@chip what's up?' -> 'what's up?'). DMs are untouched. Verified live: '@chip /whoami' -> '/whoami' after connect populates identity. Refs NousResearch#68871
Channel mention-gating was hardcoded on. Add a configurable require_mention (default True, preserving current behavior). When False, the agent responds to every message in a watched channel, not only when @mentioned; DMs always dispatch. Read from config.yaml gateway.platforms.buzz.extra.require_mention with BUZZ_REQUIRE_MENTION env override, bridged via apply_yaml_config_fn like the other settings. A leading mention is still stripped when present. Refs NousResearch#68871
On hosted relays `buzz dms list` reliably returns [] even when DM conversations exist, so DMs leaked in via `channels list` (as entries named "DM" with an empty description) and were seeded chat_type="group". That put them behind the channel mention gate: "@chip /whoami" worked but an un-mentioned DM was silently dropped. Classify from the Nostr tags of real traffic instead: a message another user sends in a DM carries a structural ["p", <own pubkey>] tag even when the text never mentions the agent, while in a real channel a p-tag-to-self only ever accompanies a visible @mention (typed mention or reply). A group conversation therefore latches to chat_type="dm" on the first kind-9 event that is p-tagged to self WITHOUT a visible mention in the content — guarded by channels-list metadata so a real community channel (real name / non-empty description) is never reclassified by a reply or mention that p-tags the agent. - latch during history seeding too, so a leaked DM bypasses the mention gate from the very first poll after connect - keep `dms list` as a best-effort source, and scan `channels list` as a fallback so DM conversations opened mid-run still get watched - strip a leading @mention in DMs as well, so "@chip /whoami" keeps firing as a slash command after the conversation reclassifies Refs NousResearch#68871 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
… adapter Expands the 'Recommended display settings' section into a comprehensive 'Recommended default settings' block covering display, access control, polling, and mention behavior. Each setting includes an inline annotation and rationale bullet. Matches Telegram/email default behavior (no intermediate tool output, mention-gated channels, private-by-default access). Refs NousResearch#68871
1 task
alt-glitch
added
type/feature
Collaborator
Related to #71610 and #71686, which are active Buzz adapter implementations for #68871. This PR's live diff includes the adapter implementation as well as the documentation named by its title; maintainer consolidation is needed rather than a duplicate closure. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Expands the 'Recommended display settings' section into a comprehensive
'Recommended default settings' block covering:
interim_assistant_messages: false,tool_progress: off— suppresses intermediate tool output, reasoning comments, and progress bubbles so only final responses reach the channel.allowed_users,allow_all_users— private-by-default mode with community mode option.poll_interval,require_mention: true— mention-gated channels, DMs always dispatch.Each setting includes an inline annotation and rationale bullet. Matches the behavior on Telegram and email, which already suppress intermediate tool output.
Context
This is a companion documentation update to the Buzz platform adapter
(
feat/buzz-platform-adapter). The adapter itself lives on this branch;this PR focuses solely on the user-guide docs so operators can copy-paste
a clean, non-spammy config on first setup.
Refs #68871