v0.23.1: un techo de 2 MiB congeló en silencio tu catálogo de plugins en el pasado


Un compañero suelta el nombre de un plugin en el canal del equipo y dice «instala este, está buenísimo». Escribes el comando de instalación y Hermes te responde que no encuentra ese plugin. Das por hecho que lo escribiste mal, pruebas otra variante y recibes la misma respuesta. Abres la página del catálogo: ahí está, con su versión, su repositorio y su descripción.

No falla tu red ni tu ortografía. Desde el 9 de noviembre, el archivo del catálogo oficial publicado pesa más de lo que el cliente está dispuesto a aceptar; y cuando el cliente decide que un archivo es demasiado grande, no protesta: se queda, sin decir nada, con la copia que viene dentro de tu versión. Lo que puedes buscar es una foto del día en que se cortó esa release. La v0.23.1 eleva el techo para que vuelva a usarse el catálogo en vivo.

Hay tres cosas que conviene entender: cómo muerde el techo, por qué lo de «silencioso» es la parte que sale cara, y cómo comprobar tu propia instalación. Y, de propina, el resto de la ventana.

La versión corta: actualiza

hermes update

A partir de ahí, el cliente acepta hasta 16 MiB en lugar de 2 MiB. El catálogo en vivo carga, así que hermes plugins install puede ver los plugins recién listados, resolver los pins actuales en vez de los que traía tu release y respetar las entradas removed más recientes.

Una advertencia que importa: el arreglo está en el cliente. Las instalaciones que se queden en la v0.23.0 o anteriores seguirán cayendo al catálogo local hasta que se actualicen. Así que cuando alguien jure que un plugin no existe, pídele hermes version antes de depurar cualquier otra cosa.

Cómo muerde un techo

El catálogo de plugins es un documento JSON público que se descarga al navegar o al instalar y que luego se cachea en local durante seis horas. Dos fuentes, en orden estricto de prioridad:

  1. El catálogo en vivo (plugin-catalog.json), publicado por el sitio de documentación: las entradas más nuevas, los pins de versión más nuevos y las bajas más nuevas;
  2. El catálogo incluido en el árbol, que viene con tu instalación: nunca se actualiza y solo se usa cuando el catálogo en vivo no se puede descargar.

La ruta de descarga tiene una comprobación de tamaño. Por encima del techo, la respuesta se considera rota: se lanza un error, se registra en nivel debug y se devuelve «no hay catálogo en vivo». Cada llamador que hay más arriba ve «nada», cae al catálogo incluido y no te dice ni una palabra.

El 9 de noviembre el documento publicado medía 2.109.306 bytes en 1.268 entradas, unos 1,7 KB cada una, y cruzó la línea de los 2 MiB. Desde ese momento:

  • los plugins recién listados no existían en tu máquina;
  • los plugins que se habían vuelto a fijar a un commit más nuevo se instalaban en el pin que traía tu release;
  • las entradas nuevas de «retirado / sin mantenimiento» eran invisibles.

Esa tercera es la que hay que masticar despacio. Un plugin retirado formalmente ya no parece retirado en tu instalación: sigue pareciendo instalable.

Midiendo el documento en vivo ahora mismo: 1.380 entradas, 2.310.445 bytes. Ya está un 10% por encima del techo antiguo. Sin la subida, esto solo se volvería más común, no menos.

Por qué lo de «silencioso» era la parte que sale cara

Visto en frío, el bug es una constante que se quedó corta. Lo difícil es el modo de fallo: todos los errores se tragaban.

Ese diseño es correcto en sus propios términos. Que falte el catálogo no debería bloquear nunca una instalación: si la red está caída o el sitio de documentación tiene un mal día, todavía deberías poder instalar desde la copia que ya tienes. Caer al respaldo ante cualquier fallo es la política correcta.

El problema es que «el documento es demasiado grande» y «no tengo red» acabaron en el mismo cajón. Lo primero significa que tu catálogo está desfasado y debería importarte; lo segundo significa espera un minuto y reinténtalo. Para el usuario las dos cosas se veían idénticas, y las acciones necesarias eran opuestas. El bug sobrevivió a esa ambigüedad hasta que alguien notó plugins que faltaban y tiró del hilo hasta la constante.

Así son casi todos los bugs de infraestructura: nada se cae, nada despierta a nadie, ninguna línea del log se pone en rojo y el mundo simplemente se va quedando viejo en silencio. Haces todo bien y obtienes la respuesta equivocada.

Qué cambió

El arreglo es el cambio de una constante, pero el comentario que entró con él merece leerse, porque fija el límite:

  • el techo pasa de 2 * 1024 * 1024 a 16 * 1024 * 1024;
  • con los tamaños actuales por entrada, 16 MiB dan para unas 9.000 entradas;
  • el techo no desaparece. Sigue acotando una respuesta hostil o corrupta; lo que deja de hacer es castigar el crecimiento normal.

El mismo archivo lleva las reglas de respaldo que lo rodean, y conocerlas te dice en qué catálogo estás:

Regla Valor Qué significa
Caché normal 6 horas las llamadas repetidas dentro de la ventana se saltan la descarga
Caché obsoleta utilizable durante 24 horas las cachés más viejas descartan entradas y solo conservan la lista de bajas
Memoria de fallos 60 segundos tras un fallo, no se reintenta en 60 s
Timeout de petición 5 segundos timeout de red por intento

Cómo comprobar tu propia instalación

La prueba honesta es de comportamiento: intenta instalar un plugin listado hace poco y mira si se resuelve. La página de referencia de hermes plugins recoge el conjunto completo de subcomandos.

Dos hábitos que merece la pena mantener:

  • cuando un plugin «no existe», ejecuta hermes version primero y luego piensa en el catálogo;
  • cuando un plugin se comporta como una versión que no instalaste, comprueba el pin resuelto antes de culpar al plugin.

Si leíste nuestra pieza anterior sobre cómo funciona el catálogo de plugins, esto es una consecuencia directa de aquel diseño: el catálogo son datos, no código, y el crecimiento de los datos acaba presionando las suposiciones del cliente. El mismo razonamiento aparece en la superficie pública de la API de plugins: las interfaces estables son lo que permite que los datos crezcan, y los clientes tienen que dejar sitio para ese crecimiento.

Qué más hay en la ventana

La v0.23.1 es una etiqueta de parche: 618 PR fusionados desde la v0.23.0, empaquetados en una release estable para el release de GitHub (CLI e instaladores), la app de Microsoft Store, Docker y Hermes Cloud. Medido en el commit 3b421578588, la ventana contiene 2.578 commits no de merge sobre 2.781 archivos modificados (+151.690 / −62.595) y 409 issues cerrados.

Las notas de la release dicen sin rodeos que un conjunto de funciones de esta ventana está sin documentar a propósito, y que las notas curadas completas llegan junto con la v0.24.0. En esa lista aparecen:

  • Esc backtrack en la TUI y en la CLI clásica, en lugar del selector de la lista de rewind;
  • chats de grupo que corren en un gateway sin Desktop y que pueden sentar bots de otras computadoras;
  • conexiones de gateway guardadas compartidas entre Desktop y la Webapp;
  • el navegador integrado, que inicia sesión con tu perfil real de navegador y rellena los inicios de sesión guardados desde la barra de direcciones;
  • hermes gateway attach para clientes locales;
  • hermes clipboard image --json;
  • nueva superficie de API de plugins: valores de entorno por sesión, métodos y eventos JSON-RPC de plugins, tareas auxiliares llm.oneshot, un conversation_id estable frente a la compresión, un hook on_session_open en el gateway y un hook post_curator_run;
  • lecturas de transcript y de handoff más rápidas, además de un buen lote de entradas nuevas en el catálogo.

Casi todo esto lo hemos contado por separado: el flujo de Esc backtrack en rebobinar una conversación sin perderla, la limpieza del catálogo en cómo se barren las entradas del catálogo por lotes, y el panorama general en la página de la v0.23.0.

Actualizar

# CLI
hermes update

# o vuelve a lanzar el instalador de una línea
# Docker / Hermes Cloud: nousresearch/hermes-agent:stable

La app de Microsoft Store se actualiza desde la Store. Una app de Desktop instalada con el instalador .exe / .dmg no cambia en esta release; recogerá el arreglo con el siguiente paquete.

Algo que merece la pena hacer tras actualizar: instalar el plugin que «no existía» y confirmar que se resuelve. Si sigue sin resolverse, revisa hermes plugins list y la versión de tu cliente; en ese punto el problema está en la entrada del plugin o en el repositorio, no en la caché del catálogo.

Notas completas: la página de la v0.23.1.