Importer un interne d'Hermes ? Il existe désormais une liste publiée de ce que les plugins peuvent importer

Votre plugin tourne depuis trois mois sans la moindre plainte. Puis une nouvelle release de Hermes sort, un utilisateur met à jour, et le plugin échoue au chargement avec un ImportError. Vous parcourez le changelog : rien ne mentionne votre plugin. Vous parcourez votre code, et le coupable est une ligne écrite il y a six mois — from hermes_cli.cli_config_load import _parse_service_tier_config — qui pointe vers une fonction interne déplacée depuis.
Ce qui rend cette classe d’accident si désagréable, c’est que rien ne va mal au moment où vous l’écrivez. Le plugin s’installe, tourne et passe ses tests. C’est une charge différée, et le changement ci-dessous consiste à l’exposer tôt.
Pourquoi un import privé est toujours une casse future
Hermes a déjà une vérification à l’exécution, la règle core-override : un plugin ne peut pas relier une fonction d’un module core au moment de l’exécution. Mais cette vérification régit le remplacement, pas la référence. Importer un interne la passe — et vous voilà attaché à l’implémentation privée de quelqu’un, qui ne porte aucune promesse de compatibilité : elle peut être renommée, déplacée ou supprimée dans un refactor dont vous n’entendrez jamais parler.
Pour un auteur de plugin, le coût arrive tard ; pour un relecteur, il est presque invisible dans quelques centaines de lignes. Ce dont le problème a réellement besoin, c’est d’une frontière statique, mécaniquement décidable : la chose que vous avez importée est-elle sur la liste publiée ?
La liste est sortie du code
C’était un frozenset codé en dur dans hermes_cli/plugin_validate_private_imports.py. Utilisable, mais invisible pour les auteurs de plugins — vous découvriez son contenu quand la CI pointait votre ligne.
Le changement du 5 novembre a déplacé la liste, inchangée, dans hermes_cli/data/plugin_api.json (déjà livré comme package data), et le validateur la lit là. Un script générateur produit la page de docs developer-guide/plugins/public-api.md à partir du même fichier, et — le point important — un test échoue quand la page est périmée. La liste ne peut pas dériver en silence : la modifier force les docs à changer avec elle.
Un jour plus tard, la liste a gagné sa première entrée qui relève franchement de « ce qu’un plugin devrait appeler » : agent.redact.redact_sensitive_text, traité plus bas.
Trois verdicts
La règle est courte :
- Une ligne de module entier (disons
agent.memory_provider) autorise ce module et tous les noms qu’il contient qui ne commencent pas par un underscore. - Une ligne de nom unique (disons
hermes_cli.auth_model_picker:prompt_model_selection) autorise ce seul nom. - Un module Hermes hors liste : un avertissement, jamais un blocage.
Ne pas bloquer est délibéré. C’est l’indice de la porte d’admission (règle 9 du catalogue, surfaces publiques uniquement), pas un compilateur : le plugin s’installe et tourne toujours, et l’auteur comme le relecteur voient « ça cassera probablement un jour ».
Quatre catégories ne sont jamais signalées : la bibliothèque standard, les paquets tiers, les modules du plugin lui-même, et les imports sous if TYPE_CHECKING:. Ce dernier est réellement utile — quand une annotation de type a besoin d’un type interne, envelopper l’import dans TYPE_CHECKING est le geste propre. Les imports par chaîne via importlib.import_module("hermes_cli.…") sont résolus aussi, donc une autre orthographe n’est pas une échappatoire.
À quoi ressemble l’avertissement
Les constats sont affichés sous la forme relative/path.py:line module[.name] :
myplugin/tools.py:41 hermes_cli.cli_config_load._parse_service_tier_config
Un détail vaut la peine d’être connu : le rapport liste le premier site de chaque module distinct avant les autres sites. Quand la liste est tronquée, vous voyez encore l’étendue — combien de modules internes vous touchez — plutôt que dix lignes du même. En CI, --json donne un rapport lisible par machine ; --install-deps installe les dépendances déclarées avant la sonde de capacité, et c’est ainsi que la porte du catalogue l’exécute.
La nouvelle entrée : redact_sensitive_text
Celle-ci mérite sa propre section, parce qu’elle répond à une question que les auteurs de plugins rencontrent sans cesse : je veux envoyer du texte utilisateur à un modèle. Comment masquer les secrets d’abord ?
L’ancienne réponse était from agent.redact import redact_sensitive_text — ça marchait, mais le validateur vous avertissait, parce que c’était privé. C’est de l’API publique maintenant :
from agent.redact import redact_sensitive_text
text = redact_sensitive_text(user_text, force=True)
Pourquoi une fonction plutôt qu’un paramètre redact= sur ctx.llm ? Parce qu’un plugin peut manipuler le même texte plusieurs fois — le découper, le concaténer, le coller dans un prompt — et ne rédiger qu’au dernier appel ne suffit pas. Avec la fonction en main, vous nettoyez là où il faut nettoyer.
La sémantique de force=True est la partie à retenir : c’est l’interrupteur qui ne vous laisse aucune porte de sortie. Par défaut la rédaction suit le réglage security.redact_secrets de l’opérateur, donc avec celui-ci désactivé la fonction renvoie le texte inchangé. Du texte destiné à un modèle est une frontière de sécurité, et là le réglage ne doit pas décider — d’où force=True. La formulation officielle est qu’on l’utilise là où les secrets ne doivent jamais quitter la machine.
Deux autres paramètres comptent. code_file=True saute les passes d’affectation ENV/JSON pour du code source connu, pour qu’une fixture comme MAX_TOKENS=*** survive. file_read=True est pour le contenu de fichier renvoyé à l’agent : les identifiants reconnus par préfixe comme ghp_… deviennent une sentinelle non réutilisable au lieu d’un masque tête/queue, parce qu’un masque tête/queue ressemble à une clé réelle mais tronquée — et un agent peut très bien la réécrire dans config.yaml.
Vérifier votre propre plugin
hermes plugins validate ./my-plugin
hermes plugins validate ./my-plugin --json
Cherchez les imports commençant par les paquets core — hermes_cli., agent., gateway., tools.. Si vous en trouvez un, il y a trois sorties : passer à une entrée publique de la liste ; si elle n’existe que pour une annotation de type, la mettre sous TYPE_CHECKING ; ou accepter d’avoir besoin d’un interne et prévoir de suivre le core — au moins, vous savez maintenant où vous vous tenez.
Pour la vue d’ensemble de la façon dont les plugins sont admis, installés et structurés, le guide du catalogue de plugins s’en charge. Si ce qui vous intéresse est la gestion des secrets en chemin, les trois voies de rédaction regarde la même mécanique par l’autre bout.
Peut-on l’utiliser aujourd’hui
Le déplacement de la liste et la nouvelle entrée sont sur main (5–6 novembre) et pas dans le tag v0.23.0. Sur un build stable, hermes plugins validate lit encore la liste codée en dur dans la source, et redact_sensitive_text est encore un import privé.
Mise à jour (10/11/2026) : ces changements sont sortis dans la v0.23.1 (9 novembre) : un
hermes updatesuffit. Le « pas dans la v0.23.0 » ci-dessus reste exact ; la v0.23.1 comble l’écart.
La valeur de tout ça ne dépend pas de la version, cependant : écrivez contre la page publiée dès maintenant. Ce qui est sur la liste est stable ; ce qui n’y est pas est emprunté. Cette règle ne change pas avec une release.
À retenir
Aucune fonctionnalité n’a été ajoutée ici. De la visibilité, oui. Une règle qui a toujours existé, et que seuls les relecteurs gardaient en tête, est maintenant un fichier que vous pouvez lire, une page que vous pouvez chercher et une vérification que votre CI peut lancer — avec un test qui garde la page honnête. Ça ne rendra pas un plugin plus rapide, mais c’est le genre de fondation qui le garde installable dans dix releases.