Tres bugs silenciosos del gateway: una errata que mató las respuestas, una máscara que se comió las job keys y un baile de sys.path

Tu enrutador de alertas te avisa de que un job ha caído en la cola equivocada. Abres el log para buscar la clave y lees ITEM-000042:***. Así que fue la redaction. Revisas security.redact_secrets, tus prefijos de proveedor, las reglas de bearer token, y todo parece correcto. Hace falta una segunda pasada para verlo: no coincidió ningún secreto. El patrón arrancó en mitad de un identificador corriente, tomó los dígitos de su cola como si fueran una credencial y enmascaró la clave entera con ellos.
Tres bugs, una sola capa
El gateway es el proceso que hay detrás de Desktop y detrás de cada integración con plataformas de chat. Los adaptadores de plataforma —Telegram, WhatsApp, Discord, Slack, Raft— son traductores finos entre ese proceso y una API de red concreta. Leen configuración del entorno, escriben líneas de log que pasan por el filtro de redaction e importan módulos hermanos del repositorio. Tres tareas corrientes, tres bugs.
Los tres se corrigieron en el mismo pull request de la capa gateway (#151738, fusionado el 2026-11-09). Parecen no tener relación y, en cierto sentido, no la tienen. Pero comparten capa y carácter: cada uno falla en un sitio distinto de donde vive el defecto, así que ninguno aparece nunca como un error que puedas buscar.
Esa es la primera razón por la que esta clase de defecto cuesta tanto de encontrar. Una regresión en un adaptador no parece un problema de adaptador: parece una job key corrupta, un bot que dejó de responder o una librería que informa de la versión equivocada. Te pasas la primera hora en el archivo equivocado.
Caso uno: un carácter mal puesto en .env mató la respuesta
La ruta de «seguimiento mientras está ocupado» de Telegram necesita saber cuánto esperar antes de decidir que un mensaje es un seguimiento real y no parte de la ejecución que ya está en curso. Ese valor viene de HERMES_TELEGRAM_FOLLOWUP_GRACE_SECONDS, y el código lo convertía con una llamada a float a pelo.
Así que un valor como abc —una errata, un placeholder olvidado o un 3s que alguien escribió porque se lee mejor— lanzaba ValueError: could not convert string to float: 'abc' en run_inbound.py:697. Esa excepción no se capturaba en el borde. Desenrollaba todo el inbound handler, lo que significa que el mensaje del usuario no recibía ninguna respuesta. No un seguimiento tardío. Un turno muerto.
El arreglo hace que esa lectura pase por gateway.run._float_env, el mismo helper que ya usan los demás parámetros de timeout de ese módulo. Una entrada mala ya no lanza: cae a 3 segundos, el seguimiento se encola y el agente sigue trabajando.
# Mal: los tres son cadenas, no números
HERMES_TELEGRAM_FOLLOWUP_GRACE_SECONDS=abc
HERMES_TELEGRAM_FOLLOWUP_GRACE_SECONDS=3s
HERMES_TELEGRAM_FOLLOWUP_GRACE_SECONDS=
# Bien: un número limpio, en segundos
HERMES_TELEGRAM_FOLLOWUP_GRACE_SECONDS=3
Por qué se escondía: la ruta solo se ejecuta cuando llega un segundo mensaje mientras hay una ejecución en vuelo, así que casi ninguna prueba la toca. Y cuando salta, el error se manifiesta como «el bot me ignoró», lo que manda a la gente al token, luego al webhook, luego a la red —y no a un valor de configuración que escribieron hace semanas. Las env vars no tienen sistema de tipos, y nada las valida hasta que se ejecuta la línea que las parsea.
Caso dos: la redaction empezó a coincidir a mitad de palabra
La redaction es coincidencia de patrones con una promesa adjunta: encuentra los secretos, deja el resto en paz. La segunda mitad es la que se rompe en silencio.
Un regex no sabe qué es una palabra. A menos que le digas que empiece solo en un límite, arrancará tan contento en cualquier carácter que satisfaga el patrón. El viejo patrón de Telegram _TELEGRAM_RE estaba dispuesto a empezar en mitad de un identificador ASCII, en la tirada de dígitos pegada a su cola. Así que una job key corriente —algo con la forma ITEM-000042:job-a12345678:q- seguido de una larga ristra de a— coincidía desde el medio y se sustituía, entera, por ***.
Nada lanzó. Nada avisó. La línea de log perdió su clave y el ingeniero de guardia perdió veinte minutos.
El arreglo restringe dónde puede empezar una coincidencia: en un límite de identificador, o después de uno de los separadores de escape de ancho fijo que el adaptador emite de verdad (\n, \uXXXX, %XX y compañía). El lookbehind de tirada de dígitos que evita que el escáner vuelva a recorrer los mismos dígitos sigue ahí: quitarlo es cómo una pasada de redaction se vuelve cuadrática sobre una cadena numérica larga.
Hubo que relajar una aserción de test, y la razón merece conocerse: el manejo de nombres de clave JSON en main ahora enmascara los valores de credencial antes de procesar los nombres de clave, así que una aserción que esperaba que un nombre de clave apareciera intacto ya no describe lo que hace el código. Eso es un test poniéndose al día con un cambio deliberado, no un agujero que se tapa.
La lección se generaliza: si tus reglas de redaction son una lista de regexes y ninguna ancla en un límite, tienes un bug esperando al primer identificador que termine en ocho dígitos.
Caso tres: importar un adaptador reordenaba la ruta de importación
sys.path en una frase: la lista ordenada de directorios que Python recorre, de delante hacia atrás, cuando escribes import something, donde gana el primer directorio que contiene una coincidencia. La posición cero le gana a todo, incluidos los paquetes instalados correctamente en el entorno.
Instalar cualquier adaptador de plataforma —telegram, whatsapp, discord, slack, raft, además de gateway.platforms.base, cron.scheduler y tools.cronjob_tools— solía insertar el directorio del repositorio en sys.path[0]. Desde ese momento, cualquier nombre de módulo que existiera tanto en el repositorio como en el entorno instalado se resolvía a la copia del repositorio.
La reproducción es inusualmente limpia. Importa el paquete real evals, luego un adaptador, luego import evals otra vez: ahora se enlaza con el directorio evals del propio repositorio en lugar de con la distribución instalada. Diez de diez en rojo antes del arreglo, diez de diez en verde después, y los adaptadores ya no tocan el orden de sys.path en absoluto.
Este es el más silencioso de los tres. Sin excepción, sin warning, sin aviso de deprecación. El import tiene éxito y devuelve un objeto, solo que uno distinto del que esperan los demás caminos de código del proceso. Todo lo que dependa de la identidad de la distribución instalada (metadatos de versión, entry points, descubrimiento de plugins) empieza a devolver respuestas que pertenecen a otro paquete, y el síntoma aparece en el subsistema que consultó ese módulo, en las antípodas del adaptador que movió la ruta.
Antes y después, en lenguaje llano
Despojado del harness de test, esto es lo que cambió:
| Sonda | Antes | Después |
|---|---|---|
HERMES_TELEGRAM_FOLLOWUP_GRACE_SECONDS=abc, mensaje que llega a mitad de ejecución |
ValueError mata la respuesta |
El valor malo cae a 3 segundos; el seguimiento se encola igual |
Una job key corriente como ITEM-000042:job-a12345678:q- más una larga ristra de a |
La clave entera se convierte en *** |
La clave sobrevive tal cual |
| Una credencial real en el mismo flujo de log | Enmascarada | Sigue enmascarada |
import evals tras importar un adaptador, con evals instalado desde PyPI |
Se enlaza a la copia del repo, 10 de 10 | Se enlaza al paquete instalado, 10 de 10 |
Lee la tercera fila antes de fiarte de cualquier cambio de redaction: apretar un patrón es fácil; apretarlo sin perder lo que protegía es el trabajo.
Revisa tu propia instalación
Dos comprobaciones rápidas, porque los dos bugs siguen invisibles hasta que muerden.
# ¿A qué `evals` resuelve este intérprete?
python3 -c "import evals; print(evals.__file__)"
# Confirma que el valor de gracia es un número limpio
grep -n FOLLOWUP_GRACE .env
Si la primera imprime una ruta dentro de tu checkout en lugar de dentro de site-packages, estás viendo exactamente el fallo de arriba. Para la segunda, un valor no numérico ahora degrada al valor por defecto de 3 segundos en lugar de lanzar, pero un fallback silencioso sigue siendo una configuración equivocada, así que corrige el valor en lugar de apoyarte en el fallback.
Para la mitad de redaction, busca *** en tus propios logs y lee las líneas de alrededor. Una cabecera Authorization enmascarada es el sistema funcionando. Una job key, request id o trace id enmascarado es el sistema trabajando de más, y ninguna cantidad de revisión de configuración lo va a revelar.
Quién arregló qué
Tres arreglos, tres orígenes, fusionados juntos:
- El arreglo del límite de redaction (#145664) se hizo cherry-pick desde @liuhao1024, con un parche de @yuzilongleif-collab.
- El arreglo de la gracia de seguimiento (#50120) se hizo cherry-pick del #51324 de @Bartok9.
- El arreglo de
sys.path(#117698) se apoya en el #117699 de @beardthelion.
La versión corta
Un bug cuesta de encontrar en proporción a lo lejos que queda su síntoma de su causa. Un float mal escrito en una env var parece un bot roto. Un regex que arranca a mitad de palabra parece una máscara que funciona. Una ruta de importación reordenada parece un import que funciona.
Quédate con los hábitos de comprobación antes que con los tres parches. Imprime __file__ de los módulos de los que dependes. No dejes que un valor de configuración llegue a un parser sin un fallback. Ancla cada regex de redaction en un límite y vuelve a leer qué coincidió la última vez que saltó. Cualquiera de esos hábitos habría cazado los tres en minutos.
Lectura relacionada: por qué una cookie en una línea de log es un inicio de sesión, lo que costaba un 409 de Telegram, cómo las llamadas bloqueantes congelaron el event loop del gateway, y la referencia de configuración.