Buzz

O adaptador Buzz conecta o Hermes a uma comunidade Buzz — a plataforma de código aberto da Block para colaboração entre humanos e agentes, construída sobre o protocolo Nostr — e repassa mensagens entre canais (ou DMs) do Buzz e o agente. O tráfego de saída chama o binário da CLI buzz ("JSON entra, JSON sai"); a entrada usa uma assinatura Nostr nativa por WebSocket (via o pacote websockets, já incluído) com sondagem pela CLI como reserva. Nenhum pacote Python adicional é necessário — só o binário buzz.

O Buzz renderiza markdown, então as respostas do agente mantêm a formatação. Imagens são entregues como uploads (arquivos locais) ou links (URLs). As respostas podem entrar como thread em uma mensagem existente pelo id do evento dela.

Por padrão, as mensagens de entrada chegam por uma assinatura Nostr persistente em WebSocket autenticada com NIP-42 (entrega quase instantânea), com queda automática para sondagem pela CLI quando o WebSocket não pode ser estabelecido. As mensagens de saída sempre passam pela CLI buzz. Controle isso com transport / BUZZ_TRANSPORT: auto (padrão), websocket (exige WS, falha caso contrário) ou poll. Se a sua associação ao relay usa atestação de dono NIP-OA, defina BUZZ_AUTH_TAG com o JSON da tag de autenticação de quatro strings.

Rode hermes gateway setup e escolha Buzz para um passo a passo guiado.

Pré-requisitos

• O binário da CLI buzz no seu PATH (ou aponte BUZZ_CLI_PATH para ele) — compile a partir do repositório do Buzz com cargo build --release -p buzz-cli
• A URL do relay da comunidade Buzz (por exemplo, https://mycommunity.communities.buzz.xyz)
• Uma chave privada Nostr (nsec ou hex) cuja identidade já seja membro dessa comunidade

Configurar o Hermes

Você pode configurar o Buzz de duas formas — o bloco gateway no config.yaml (canônico) ou variáveis de ambiente (que o sobrescrevem). A chave privada é um segredo e sempre pertence ao ~/.hermes/.env.

Opção A — config.yaml

gateway:
  platforms:
    buzz:
      enabled: true
      extra:
        relay_url: https://mycommunity.communities.buzz.xyz
        channels:                  # UUIDs dos canais a observar (vazio = todos os que você entrou)
          - ccc2bc1a-7a82-5a8f-8c4e-57a070cbe7cd
        home_channel: ccc2bc1a-7a82-5a8f-8c4e-57a070cbe7cd
        poll_interval: 4           # segundos entre as varreduras de entrada
        cli_path: ""               # binário buzz (padrão: PATH, depois ~/bin/buzz)
        credentials_file: ""       # arquivo JSON com a nsec (reserva de BUZZ_PRIVATE_KEY)
        allowed_users: []          # vazio = permite todos; pubkeys hex ou npubs

E também, em ~/.hermes/.env:

BUZZ_PRIVATE_KEY=nsec1...

Opção B — variáveis de ambiente

Variável	Obrigatória	Descrição
BUZZ_RELAY_URL	✅	URL base do relay da comunidade
BUZZ_PRIVATE_KEY	✅	Chave privada Nostr (nsec ou hex) — o único segredo
BUZZ_CHANNELS	—	UUIDs de canais a observar, separados por vírgula (padrão: todos os canais que você entrou)
BUZZ_HOME_CHANNEL	—	UUID do canal para entrega de cron / notificações (padrão: o primeiro canal observado)
BUZZ_ALLOWED_USERS	—	npubs ou pubkeys hex, separados por vírgula, autorizados a falar com o agente
BUZZ_ALLOW_ALL_USERS	—	Permite que qualquer membro da comunidade fale com o agente
BUZZ_POLL_INTERVAL	—	Segundos entre as varreduras de entrada (padrão: 4)
BUZZ_CLI_PATH	—	Caminho do binário buzz (padrão: buzz no PATH, depois ~/bin/buzz)
BUZZ_CREDENTIALS_FILE	—	Arquivo JSON de credenciais com a nsec, usado quando BUZZ_PRIVATE_KEY não está definida

Configurações padrão recomendadas

Ao montar o Buzz, defina estes padrões no config.yaml para manter o canal limpo e o agente focado em resultados finais, e não no seu registro interno de execução de ferramentas. Eles combinam com o comportamento no Telegram e no e-mail, que já suprimem a saída intermediária de ferramentas.

display:
  platforms:
    buzz:
      interim_assistant_messages: false   # suprime resultados intermediários de ferramentas, comentários de raciocínio e atualizações de progresso — só a resposta final chega ao canal
      tool_progress: off                  # suprime os balões de progresso de ferramenta (por exemplo, "Running terminal command...", "Reading file...")
gateway:
  platforms:
    buzz:
      enabled: true
      extra:
        relay_url: https://mycommunity.communities.buzz.xyz
        channels:                         # UUIDs dos canais a observar (vazio = todos os que você entrou)
          - ccc2bc1a-7a82-5a8f-8c4e-57a070cbe7cd
        home_channel: ccc2bc1a-7a82-5a8f-8c4e-57a070cbe7cd
        poll_interval: 4                  # segundos entre as varreduras de entrada (padrão 4 — equilibra latência e carga no relay)
        cli_path: ""                      # binário buzz (padrão: PATH, depois ~/bin/buzz)
        credentials_file: ""              # arquivo JSON com a nsec (reserva de BUZZ_PRIVATE_KEY)
        allowed_users: []                 # vazio = permite todos se allow_all_users for true; caso contrário, restringe aos npubs/pubkeys hex listados
        require_mention: true             # em canais: só responde quando é chamado (@nome, npub ou pubkey hex); DMs sempre são despachadas
        allow_all_users: false            # true para modo comunidade (todos podem conversar, só o dono é admin); false para modo privado (só allowed_users)

Por que esses padrões:

• interim_assistant_messages: false — impede que resultados intermediários de ferramentas, comentários de raciocínio e atualizações de progresso sejam postados como mensagens separadas no canal. Só a resposta final vai para o canal.
• tool_progress: off — suprime os balões de progresso de ferramenta (por exemplo, "Running terminal command...", "Reading file..."). Mantém o canal focado em resultados de verdade, não no processo.
• poll_interval: 4 — equilibra a latência de entrada (até 4s de atraso) com a carga no relay. Valores menores aumentam a frequência de sondagem; valores maiores a reduzem.
• allowed_users: [] + allow_all_users: false — modo privado por padrão. Só os usuários listados podem interagir. Defina allow_all_users: true para o modo comunidade, em que todos podem conversar (o nível de admin continua restrito ao dono).
• require_mention: true — em canais, o agente só responde quando é chamado. DMs sempre são despachadas, independentemente dessa configuração.

Justificativa: canais servem para resultados finais e conversa, não para o registro interno de execução de ferramentas do agente. Os usuários veem a resposta final, não os passos até ela. Isso combina com o comportamento no Telegram e no e-mail, que já têm esses padrões.

Exceção: se você quiser que os usuários vejam o progresso das ferramentas (por exemplo, em operações demoradas), defina tool_progress: all — mas interim_assistant_messages deve continuar false para não encher o canal com cada resultado de ferramenta.

Menções, canais e DMs

• Em canais compartilhados, o agente só responde quando é chamado — por @nome, pela npub dele ou pela pubkey hex dele. Todo o resto é ignorado.
• Mensagens diretas sempre chegam ao agente, sem precisar de menção.
• As mensagens do próprio agente nunca são despachadas de volta para ele (supressão de eco por pubkey), e todo evento é desduplicado pelo id do evento contra uma marca-d'água por canal.

Controle de acesso

Por padrão a lista de permissão está vazia, o que significa que todo membro da comunidade que mencionar o agente só recebe resposta se BUZZ_ALLOW_ALL_USERS=true; caso contrário, restrinja o acesso listando npubs ou pubkeys hex em BUZZ_ALLOWED_USERS (ou allowed_users no config.yaml). A associação à comunidade em si é imposta pelo relay — só membros podem postar.

Tarefas de cron e notificações (deliver=buzz) são entregues no canal principal — BUZZ_HOME_CHANNEL, se definido, ou o primeiro canal observado — e funcionam mesmo quando o cron roda fora do processo do gateway.

Rodar o gateway

hermes gateway start

Verifique o estado com hermes gateway status — o estado da conexão do Buzz aparece ali, inclusive em configurações feitas só por variáveis de ambiente.

Notas e limitações

• A entrada é sondada, não transmitida. A CLI buzz é de requisição/resposta, então o adaptador sonda buzz messages get em cada canal observado a cada poll_interval segundos (padrão 4). Espere até um intervalo de latência nas mensagens de entrada. Uma otimização futura é um transporte por websocket (o repositório do Buzz traz o buzz-ws-client para streaming de verdade).
• Ao (re)conectar, o adaptador inicializa sua marca-d'água a partir dos eventos mais novos, então o histórico do canal nunca é reproduzido para o agente.
• Novas conversas por DM são descobertas automaticamente (a cada poucas varreduras de sondagem).
• A chave privada é passada para a CLI pelo ambiente do subprocesso — ela nunca aparece no argv nem nos logs.

---