Raft

O Hermes se conecta ao Raft como agente externo, por uma ponte local de canal de aviso. O adaptador sobe um endpoint HTTP em loopback, que recebe avisos sem conteúdo vindos da ponte, e os injeta no fluxo de sessão do gateway. O agente lê e envia mensagens pela CLI do Raft — o adaptador nunca toca no corpo das mensagens nem nos marcadores de entrega.

Divisão de responsabilidades

• A ponte cuida de: consumir os avisos, remover duplicatas, espera crescente entre tentativas, reconexão, entrega ao menos uma vez e registro de prova.
• O adaptador do Hermes cuida de: um endpoint de aviso em localhost e da injeção de uma nota curta no contexto do agente.
• O agente cuida de: buscar mensagens (raft message check), responder (raft message send) e todas as outras interações, pela CLI.

O adaptador não guarda credencial nenhuma do Raft — só um token compartilhado por sessão, para a autenticação em localhost entre a ponte e o endpoint.

---

Pré-requisitos

• Um espaço de trabalho no Raft onde você possa criar um agente externo
• A CLI do Raft instalada e autenticada naquele perfil de agente externo
• aiohttp — pacote Python (incluído nos extras [all] do Hermes)

No Raft, abra o menu de agentes, crie um agente externo e siga o cartão de configuração para instalar a CLI e autenticar o perfil. Criado o agente, o Raft mostra um guia de configuração do Hermes, com as variáveis de ambiente e a configuração necessárias para subir o gateway.

---

Configuração

Acrescente em ~/.hermes/.env:

RAFT_PROFILE=seu-perfil-de-agente

É só isso — o adaptador se habilita sozinho quando o RAFT_PROFILE existe. Ele gera um token de ponte por sessão, escolhe uma porta efêmera e cria o processo filho da ponte automaticamente quando o gateway sobe.

---

Como funciona

Servidor Raft → Ponte (avisos por SSE) → POST /wake → Adaptador do Hermes → contexto do agente
Agente → raft message check → Servidor Raft (corpo das mensagens)
Agente → raft message send → Servidor Raft (respostas)

1. O servidor do Raft manda avisos para a ponte, via SSE.
2. A ponte repassa cada aviso como um POST /wake ao endpoint em loopback do adaptador.
3. O adaptador valida o token, confere que o conteúdo é mesmo vazio, e injeta uma nota de aviso na sessão do Hermes.
4. O agente vê o aviso e usa a CLI do Raft para ler as mensagens e responder.

Os avisos são sem conteúdo por contrato — carregam metadados (identificador do evento, da mensagem, carimbos de tempo), mas nunca corpo de mensagem, nome de canal ou identidade de quem enviou. O adaptador recusa qualquer conteúdo com campos que pareçam texto (text, body, content, messages etc.).

---

A ponte

O adaptador cria o raft agent bridge como processo filho automaticamente, passando a URL do endpoint e o token. A ponte se conecta ao servidor do Raft usando o perfil configurado e começa a repassar os avisos. Ela é encerrada quando o gateway desliga.

---

Variáveis de ambiente

Variável	Descrição	Padrão
RAFT_PROFILE	Identificador do perfil de agente no Raft — habilita o adaptador quando definido	(obrigatória)