¿Importas un interno de Hermes? Ya hay una lista publicada de lo que un plugin puede importar

Tu plugin lleva tres meses en uso sin una sola queja. Luego sale una release nueva de Hermes, un usuario actualiza y el plugin falla al cargarse con un ImportError. Repasas el changelog y nada menciona tu plugin. Repasas tu código y el culpable es una línea que escribiste hace medio año — from hermes_cli.cli_config_load import _parse_service_tier_config — apuntando a una función interna que desde entonces se ha movido.
Lo que hace tan desagradable este tipo de accidente es que no falla nada en el momento en que lo escribes. El plugin se instala, funciona y pasa sus tests. Es una carga diferida, y el cambio que sigue va de enseñarla por adelantado.
Por qué un import privado siempre es una rotura futura
Hermes ya tiene una comprobación en runtime, la regla de core-override: un plugin no puede reasignar una función dentro de un módulo del core en tiempo de ejecución. Pero esa comprobación gobierna sustituir, no referenciar. Importar un interno la pasa sin problema, y a partir de ahí quedas atado a la implementación privada de otra persona, que no lleva ninguna promesa de compatibilidad: puede renombrarse, moverse o desaparecer en un refactor del que nunca te enterarás.
Para quien escribe plugins el coste llega tarde; para quien revisa es casi invisible entre unos cientos de líneas. Lo que el problema necesita de verdad es una frontera estática y decidible mecánicamente: ¿está en la lista publicada lo que has importado?
La lista salió del código
Antes era un frozenset escrito a mano en hermes_cli/plugin_validate_private_imports.py. Servía, pero era invisible para quien escribe plugins: te enterabas de lo que había en ella cuando la CI te señalaba tu línea.
El cambio del 5 de noviembre movió la lista, sin tocarla, a hermes_cli/data/plugin_api.json (que ya se distribuía como package data), y el validador la lee de ahí. Un script generador produce la página de docs developer-guide/plugins/public-api.md a partir del mismo archivo y, lo importante, un test falla cuando la página se queda desfasada. La lista no puede desviarse en silencio: cambiarla obliga a cambiar la documentación con ella.
Un día después la lista estrenó su primera entrada que es exactamente «lo que un plugin debería llamar»: agent.redact.redact_sensitive_text, que vemos más abajo.
Tres veredictos
La regla es corta:
- Una fila de módulo completo (por ejemplo
agent.memory_provider) permite ese módulo y todos los nombres que contiene que no empiecen por guion bajo. - Una fila de nombre único (por ejemplo
hermes_cli.auth_model_picker:prompt_model_selection) permite solo ese nombre. - Un módulo de Hermes fuera de la lista: un warning, nunca un bloqueo.
Que no bloquee es intencionado. Esto es la pista de la compuerta de admisión (regla 9 del catálogo, solo superficies públicas), no un compilador: el plugin se sigue instalando y se sigue ejecutando, y tanto el autor como el revisor pueden ver «esto probablemente se rompa algún día».
Cuatro categorías nunca se señalan: la biblioteca estándar, los paquetes de terceros, los módulos del propio plugin y los imports dentro de if TYPE_CHECKING:. Lo último es realmente útil: cuando una anotación de tipo necesita un tipo interno, envolver el import en TYPE_CHECKING es la salida limpia. Los imports en cadena mediante importlib.import_module("hermes_cli.…") también se resuelven, así que otra forma de escribirlo no es una escapatoria.
Cómo se ve el warning
Los hallazgos se imprimen como relative/path.py:line module[.name]:
myplugin/tools.py:41 hermes_cli.cli_config_load._parse_service_tier_config
Un detalle que conviene saber: el informe lista el primer sitio de cada módulo distinto antes que los demás sitios. Cuando la lista se trunca sigues viendo la amplitud —cuántos módulos internos tocas— en lugar de diez líneas del mismo. En CI, --json te da un informe legible por máquina; --install-deps instala las dependencias declaradas antes del sondeo de capacidades, que es como lo ejecuta la compuerta del catálogo.
La entrada nueva: redact_sensitive_text
Esta merece su propia sección, porque responde a una pregunta que los autores de plugins se encuentran constantemente: quiero enviar texto del usuario a un modelo. ¿Cómo enmascaro antes los secretos?
La respuesta antigua era from agent.redact import redact_sensitive_text: funcionaba, pero el validador te avisaba porque era privada. Ahora es API pública:
from agent.redact import redact_sensitive_text
text = redact_sensitive_text(user_text, force=True)
¿Por qué una función y no un parámetro redact= en ctx.llm? Porque un plugin puede manejar el mismo texto varias veces —trocearlo, concatenarlo, pegarlo en un prompt— y redactar solo en la llamada final no basta. Con la función en la mano puedes limpiarlo donde haga falta.
La semántica de force=True es lo que hay que recordar: es el interruptor que no te deja ninguna salida. Por defecto la redacción sigue el ajuste security.redact_secrets del operador, así que con ese ajuste desactivado la función devuelve el texto sin cambios. El texto destinado a un modelo es una frontera de seguridad, y ahí el ajuste no debería decidir; de ahí force=True. La formulación oficial es que lo uses donde los secretos no deben salir nunca de la máquina.
Otros dos parámetros importan. code_file=True se salta las pasadas de asignación ENV/JSON para código fuente conocido, así que un fixture como MAX_TOKENS=*** sobrevive. file_read=True es para contenido de archivo devuelto al agent: las credenciales con prefijo conocido como ghp_… pasan a ser un centinela no reutilizable en lugar de una máscara de cabeza y cola, porque esa máscara parece una clave real pero truncada, y un agent bien podría reescribirla en config.yaml.
Revisar tu propio plugin
hermes plugins validate ./my-plugin
hermes plugins validate ./my-plugin --json
Busca imports que empiecen por los paquetes del core: hermes_cli., agent., gateway., tools.. Si encuentras uno, hay tres salidas: cambiar a una entrada pública de la lista; si existe solo para una anotación de tipo, ponerlo bajo TYPE_CHECKING; o aceptar que necesitas un interno y planificar moverte con el core. Al menos ahora sabes dónde estás pisando.
Para una visión más amplia de cómo se admiten, instalan y organizan los plugins, la guía del catálogo de plugins lo cubre. Si te interesa cómo se manejan los secretos por el camino, los tres carriles de redacción miran la misma maquinaria desde el otro extremo.
¿Puedes usarlo hoy?
El traslado de la lista y la entrada nueva están en main (5 y 6 de noviembre) y no están en la etiqueta v0.23.0. En un build estable, hermes plugins validate sigue leyendo la lista escrita a mano en el código, y redact_sensitive_text sigue siendo un import privado.
Actualización (10/11/2026): estos cambios ya salieron en la v0.23.1 (9 de noviembre): basta con
hermes update. Lo de «no está en v0.23.0» sigue siendo cierto; la v0.23.1 cierra la brecha.
El valor de esto no depende de la versión, eso sí: escribe contra la página publicada desde ya. Lo que está en la lista es estable; lo que queda fuera, prestado. Esa regla no cambia con una release.
La conclusión
Aquí no se añadió ninguna función. Se añadió visibilidad. Una regla que siempre existió y que solo los revisores llevaban en la cabeza es ahora un archivo que puedes leer, una página que puedes buscar y una comprobación que tu CI puede ejecutar, con un test que mantiene la página honesta. No hará tu plugin más rápido, pero es el tipo de cimientos que lo mantienen instalable dentro de diez releases más.