Três bugs silenciosos no gateway: um erro de digitação que matou as respostas, uma máscara que engoliu job keys e uma mexida no sys.path

Seu roteador de alertas te chama porque um job caiu na fila errada. Você abre o log para achar a chave e lê ITEM-000042:***. Então foi a redaction. Você revisa security.redact_secrets, seus prefixos de fornecedor, as regras de bearer token, e tudo parece certo. É preciso uma segunda passada para enxergar: nenhum segredo foi encontrado. O padrão começou no meio de um identificador comum, tratou os dígitos do final como credencial e mascarou a chave inteira com eles.
Três bugs, uma camada
O gateway é o processo por trás do Desktop e por trás de toda integração com plataformas de chat. Os adaptadores de plataforma — Telegram, WhatsApp, Discord, Slack, Raft — são tradutores finos entre esse processo e uma API de rede específica. Eles leem configuração do ambiente, escrevem linhas de log que passam pelo filtro de redaction e importam módulos irmãos do repositório. Três tarefas comuns, três bugs.
Os três foram corrigidos no mesmo pull request da camada do gateway (#151738, mesclado em 2026-11-09). Parecem sem relação e, de certo modo, são. Mas compartilham uma camada e um temperamento: cada um falha em outro lugar que não o do defeito, então nenhum deles jamais aparece como um erro que você possa buscar.
Essa é a primeira razão pela qual essa classe de defeito é tão difícil de achar. Uma regressão de adaptador não parece problema de adaptador: parece uma job key quebrada, um bot que parou de responder ou uma biblioteca relatando a versão errada. Você gasta a primeira hora no arquivo errado.
Caso um: um caractere errado no .env matou a resposta
O caminho de «follow-up enquanto ocupado» do Telegram precisa saber quanto esperar antes de decidir que uma mensagem é um follow-up de verdade e não parte do run que já está em andamento. Esse valor vem de HERMES_TELEGRAM_FOLLOWUP_GRACE_SECONDS, e o código o convertia com uma chamada float crua.
Então um valor como abc — um erro de digitação, um placeholder esquecido ou um 3s que alguém escreveu porque lê melhor — levantava ValueError: could not convert string to float: 'abc' em run_inbound.py:697. Essa exceção não era capturada na fronteira. Ela desenrolava o inbound handler inteiro, o que significa que a mensagem do usuário não recebia resposta alguma. Não um follow-up atrasado. Um turno morto.
O conserto faz essa leitura passar por gateway.run._float_env, o mesmo helper que os outros ajustes de timeout daquele módulo já usam. Entrada ruim não levanta mais: cai para 3 segundos, o follow-up entra na fila e o agente continua trabalhando.
# Errado — os três são strings, não números
HERMES_TELEGRAM_FOLLOWUP_GRACE_SECONDS=abc
HERMES_TELEGRAM_FOLLOWUP_GRACE_SECONDS=3s
HERMES_TELEGRAM_FOLLOWUP_GRACE_SECONDS=
# Certo — um número limpo, em segundos
HERMES_TELEGRAM_FOLLOWUP_GRACE_SECONDS=3
Por que ficava escondido: o caminho só roda quando uma segunda mensagem chega com um run em execução, então quase nenhum teste o toca. E quando dispara, o erro se manifesta como «o bot me ignorou», o que manda a pessoa para o token, depois para o webhook, depois para a rede — não para um valor de configuração digitado semanas atrás. Env vars não têm sistema de tipos, e nada as valida até a linha que as parseia rodar.
Caso dois: a redaction passou a casar no meio da palavra
Redaction é pattern matching com uma promessa anexada: encontre os segredos, deixe o resto em paz. A segunda metade é a parte que quebra em silêncio.
Um regex não sabe o que é uma palavra. A menos que você mande começar só numa fronteira, ele vai começar alegremente em qualquer caractere que satisfaça o padrão. O padrão antigo do Telegram _TELEGRAM_RE topava começar no meio de um identificador ASCII, na sequência de dígitos colada ao final. Então uma job key comum — algo no formato ITEM-000042:job-a12345678:q- seguido de uma longa sequência de a — casava a partir do meio e era substituída, inteira, por ***.
Nada levantou. Nada avisou. A linha de log perdeu a chave e o engenheiro de plantão perdeu vinte minutos.
O conserto restringe onde uma correspondência pode começar: numa fronteira de identificador, ou depois de um dos separadores de escape de largura fixa que o adaptador realmente emite (\n, \uXXXX, %XX e companhia). O lookbehind de sequência de dígitos que impede o scanner de repassar pelos mesmos dígitos continua lá — removê-lo é como uma passada de redaction vira quadrática numa string numérica longa.
Uma asserção de teste precisou ser afrouxada, e a razão vale conhecer: o tratamento de nomes de chave JSON no main agora mascara os valores de credencial antes de processar os nomes de chave, então uma asserção que esperava ver um nome de chave intacto não descreve mais o que o código faz. Isso é um teste alcançando uma mudança deliberada, não um buraco sendo tapado.
A lição se generaliza: se suas regras de redaction são uma lista de regexes e nenhuma ancora numa fronteira, você tem um bug esperando o primeiro identificador que termina em oito dígitos.
Caso três: importar um adaptador embaralhava o caminho de import
sys.path numa frase: a lista ordenada de diretórios que o Python percorre, da frente para trás, quando você escreve import something, em que o primeiro diretório que contém uma correspondência vence. A posição zero ganha de tudo, inclusive de pacotes instalados corretamente no ambiente.
Instalar qualquer adaptador de plataforma — telegram, whatsapp, discord, slack, raft, além de gateway.platforms.base, cron.scheduler e tools.cronjob_tools — costumava inserir o diretório do repositório em sys.path[0]. A partir daquele instante, qualquer nome de módulo que existisse tanto no repositório quanto no ambiente instalado resolvia para a cópia do repositório.
A reprodução é incomumente limpa. Importe o pacote real evals, depois um adaptador, depois import evals de novo: agora ele se liga ao diretório evals do próprio repositório em vez da distribuição instalada. Dez de dez vermelho antes do conserto, dez de dez verde depois, e os adaptadores não mexem mais na ordem do sys.path de forma alguma.
Esse é o mais silencioso dos três. Sem exceção, sem aviso, sem nota de depreciação. O import dá certo e devolve um objeto — só que um objeto diferente do que todos os outros caminhos de código do processo esperam. Qualquer coisa que dependa da identidade da distribuição instalada (metadados de versão, entry points, descoberta de plugins) começa a devolver respostas que pertencem a outro pacote, e o sintoma aparece no subsistema que consultou aquele módulo, muito longe do adaptador que moveu o caminho.
Antes e depois, em termos simples
Sem o harness de teste, foi isso que mudou:
| Sonda | Antes | Depois |
|---|---|---|
HERMES_TELEGRAM_FOLLOWUP_GRACE_SECONDS=abc, mensagem chegando no meio do run |
ValueError mata a resposta |
O valor ruim cai para 3 segundos; o follow-up entra na fila do mesmo jeito |
Uma job key comum como ITEM-000042:job-a12345678:q- mais uma longa sequência de a |
A chave inteira vira *** |
A chave sobrevive intacta |
| Uma credencial real no mesmo fluxo de log | Mascarada | Continua mascarada |
import evals depois de importar um adaptador, com evals instalado do PyPI |
Liga na cópia do repo, 10 de 10 | Liga no pacote instalado, 10 de 10 |
Leia a terceira linha antes de confiar em qualquer mudança de redaction: apertar um padrão é fácil; apertar sem largar o que ele protegia é o trabalho.
Confira sua própria instalação
Duas checagens rápidas, porque os dois bugs ficam invisíveis até morderem.
# Para qual `evals` este interpretador resolve?
python3 -c "import evals; print(evals.__file__)"
# Confirme que o valor de carência é um número limpo
grep -n FOLLOWUP_GRACE .env
Se a primeira imprimir um caminho dentro do seu checkout em vez de dentro de site-packages, você está olhando exatamente para a falha acima. Na segunda, um valor não numérico agora degrada para o padrão de 3 segundos em vez de levantar — mas um fallback silencioso continua sendo configuração errada, então corrija o valor em vez de contar com o fallback.
Para a metade da redaction, dê grep por *** nos seus próprios logs e leia as linhas em volta. Um cabeçalho Authorization mascarado é o sistema funcionando. Uma job key, request id ou trace id mascarado é o sistema trabalhando demais, e nenhuma revisão de configuração vai revelar isso.
Quem consertou o quê
Três consertos, três origens, mesclados juntos:
- O conserto da fronteira da redaction (#145664) foi cherry-pick de @liuhao1024, com um patch de @yuzilongleif-collab.
- O conserto da carência de follow-up (#50120) foi cherry-pick do #51324 do @Bartok9.
- O conserto do
sys.path(#117698) se apoia no #117699 do @beardthelion.
A versão curta
Um bug é difícil de achar na proporção da distância entre o sintoma e a causa. Um float mal digitado numa env var parece um bot quebrado. Um regex que começa no meio da palavra parece uma máscara funcionando. Um caminho de import reordenado parece um import funcionando.
Leve os hábitos de checagem, não os três patches. Imprima __file__ dos módulos de que você depende. Nunca deixe um valor de configuração chegar a um parser sem fallback. Ancore todo regex de redaction numa fronteira e releia o que ele casou na última vez que disparou. Qualquer um desses hábitos teria pego os três em minutos.
Leitura relacionada: por que um cookie numa linha de log é um login, quanto custava um 409 do Telegram, como chamadas bloqueantes congelaram o event loop do gateway, e a referência de configuração.