
Construire hermes-ui : le harnais qui rend Hermes Agent visible
Hermes Agent est un assistant vocal et textuel qui tourne en local, avec un cerveau distant hébergé par un fournisseur LLM et des mains locales qui contrôlent la domotique, le NAS, les services. Mais un agent sans interface, c'est un terminal sans écran. hermes-ui est le harnais construit pour rendre cet agent visible, utilisable et agréable au quotidien par toute la famille.
Pourquoi un harnais
Le terme « harnais » n'est pas un hasard. Hermes Agent expose une API REST avec streaming SSE — il parle, il écoute, il exécute des outils, il délègue à des sous-agents. Mais il ne montre rien. Pas de bulles de chat, pas de rendu des widgets, pas de gestion des conversations, pas de profils utilisateurs. L'agent est une boîte noire qui répond en JSON.
Le harnais, c'est tout ce qui transforme ce flux brut en quelque chose d'humain : une interface qui affiche les réponses au fur et à mesure, qui sait interpréter les 16 formats de widgets embarqués — tableaux, graphiques, diagrammes, figures géométriques —, qui gère les profils de chaque membre de la famille, et qui persistent les conversations d'une session à l'autre. Ce n'est pas un client API générique. C'est un contrat implicite entre l'agent et ses utilisateurs.
L'architecture : React 19 côté client, Express côté serveur
hermes-ui est une application web mono-repo composée de deux parties :
- Le serveur Express — un proxy qui reçoit les requêtes du navigateur, les transforme en appels API vers Hermes Agent, et gère la persistance des conversations en JSON sur disque. C'est lui qui possède la clé API, qui injecte les consignes de mode (Étudier/Agir, todolist active), et qui stream les événements SSE au client.
- L'interface React — une SPA construite avec React 19, TypeScript, Vite et Tailwind CSS. Le store client utilise un pattern Map avec useSyncExternalStore et notification par version : chaque mutation d'un run bump un compteur, ce qui déclenche le re-rendu des composants abonnés sans comparaison profonde.
Les composants UI s'appuient sur Radix UI pour l'accessibilité — dialogs, menus, toggle — et lucide-react pour les icônes. Le tout est skinnable via 16 thèmes clair/sombre appliqués par un attribut data-theme sur la balise racine HTML.
Le runStore : le cœur reactif
Le défi principal d'un chat avec streaming est de gérer l'état des « runs » — ces sessions pendant lesquelles l'agent pense, utilise des outils, et produit une réponse. Un run peut durer quelques secondes ou plusieurs minutes. Pendant ce temps, le client reçoit un flux d'événements SSE : segments de texte, appels d'outils, resultats de sous-agents, raisonnement.
Le runStore est un store client implémenté comme un Map indexé par runId. Chaque run est un objet avec ses segments de texte, ses appels d'outils, son état — running, completed, failed, cancelled. La notification se fait par version : quand un run est mis a jour, on incremente un compteur atomique. Les composants React qui lisent le store via useSyncExternalStore se re-renderont uniquement si la version a change.
Ce pattern a été choisi apres avoir constaté que les solutions classiques — useState par composant, ou un store React Redux — créent des re-rendus en cascade lors du streaming. Avec un million de tokens de contexte possible, un agent qui utilise 5 outils en parallèle, et un frontend qui doit rester fluide, la performance du store est critique.
Les widgets : 16 formats pour rendre l'agent lisible
L'un des choix les plus structurants de hermes-ui est le système de widgets fenced. Quand l'agent produit du contenu structuré — un tableau de données, un graphique, un diagramme de flux, une figure de géométrie — il l'encadre dans un bloc de code avec un langage spécifique :
```table
{"columns":[{"header":"Nom","accessorKey":"name"}],"data":[{"name":"Alice"}]}
```Le front-end intercepte ces blocs via un pipeline remark/rehype — la chaîne de transformation Markdown de react-markdown — et les rend en composants React natifs. Le WidgetBlock dans MessageItem.tsx parse le JSON, vérifie le langage, et délègue au bon renderer : un tableau interactif pour table, un graphique ECharts pour echart, un diagramme Mermaid, une figure JXSGraph interactive, un quiz question, un itineraire route, et ainsi de suite.
Le pipeline est conçu pour etre extensible : ajouter un nouveau widget revient a ajouter un case dans le switch du WidgetBlock, creer le composant React correspondant, et documenter le format JSON dans le prompt système — MARKDOWN_INSTRUCTIONS. Ce prompt fait environ 10 000 caractères et decrit chaque widget avec un exemple complet — c'est lui qui apprend a l'agent comment produire le bon format.
Profils familiaux et authentification
hermes-ui n'est pas conçu pour un utilisateur seul. La famille — chacun a ses propres conversations, ses propres clés API, et ses propres restrictions. Le système de profils fonctionne sur le modele Netflix : un ecran de sélection au démarrage, un préfixe /p/membre/ sur chaque appel API, et un espace de conversations séparé par membre.
Les enfants ont un accès simplifié — header seul, pas de jeton signé — tandis que les parents doivent fournir un jeton HMAC pour les operations sensibles. La separation est stricte : les conversations d'un membre ne sont jamais visibles par un autre. Le serveur Express enforce cette separation au niveau de la route, pas du prompt.
Le mode Étudier/Agir et la boucle qualité
Une des fonctionnalités les plus complexes de hermes-ui est le « plan mode » — un segmenteur Étudier/Agir qui contrôle comment l'agent aborde une tâche. En mode Étudier, l'agent produit un plan détaillé avec une todolist, sans exécuter. L'utilisateur valide, puis bascule en mode Agir pour l'exécution.
Le serveur injecte des consignes statiques dans le flux d'entrée — le « delta » — selon le mode actif : PLAN_MODE_INSTRUCTION en mode Étudier, qui interdit l'exécution et autorise la creation de plan, TODO_ACTIVE_INSTRUCTION quand une todolist est active, qui force l'agent a suivre les étapes. Ces consignes sont dans le delta, jamais dans l'historique persistent — ce qui signifie que le switch entre modes ne casse pas le KV cache côté serveur.
La boucle qualité est un mecanisme qui vérifie, a la fin de chaque run, que l'agent a bien produit un plan exploitable avec des étapes concretes. Si ce n'est pas le cas, elle relance automatiquement un run avec une consigne corrective. Le tout est verrouillé : pas de boucle en mode Étudier, pas de boucle si la todolist n'est pas entamée.
Les défis rencontres
Construire un harnais pour un agent IA, c'est affronter une categorie de problèmes qu'on ne trouve dans aucun tutorial.
Le double agent. Quand un run est interrompu puis relance, l'ancien run peut continuer de tourner côté serveur pendant que le nouveau démarré. Résultat : deux boucles d'agent sur la même session, des éditions de fichiers concurrentes. Le correctif a nécessite un verrou par conversation — startLocks — qui rend la sequence check-supersession-creation atomique.
Le titrage en arrière-plan. Pour nommer automatiquement les conversations, hermes-ui lançait un second LLM en parallèle. Ce second run n'etait jamais stoppe côté serveur quand l'utilisateur naviguait ailleurs — il tournait des heures en silencieux. La solution : un titrage 100 % local basé sur des heuristiques, sans appel réseau.
La supersession incomplète. Quand l'utilisateur clique « Arrêter » pendant un run, hermes-ui coupait le flux SSE local mais n'envoyait jamais la requete d'arrêt au serveur. Le run continuait de tourner, consommant des tokens et utilisant des outils, pendant que l'utilisateur croyait avoir tout arrête. Ce bug a nécessite un stopUpstream() qui attend la confirmation côté gateway avant de couper le SSE.
Les collisions de worktree. Quand deux agents travaillent en parallèle sur hermes-ui via des worktrees Git dedies, les merges et les bumps de version peuvent se chevaucher. Un agent qui bumperait a une version alors qu'un autre vient de merger creerait un tag pointant sur un commit sans le travail du second. La regle dorée : toujours vérifier git log --oneline -3 avant de bumper, et ne jamais annoncer un tag sans avoir lu le SHA juste avant.
Le déploiement : CI/CD par Gitea Actions
hermes-ui est deploye sur le NAS familial via Docker, avec un pipeline CI/CD automatisé. Chaque push sur la branche feat/hermes-ui déclenche une pipeline Gitea Actions qui build l'image Docker, la publie sur le registry local, et redéploie la stack via Dockge. Le tout prend environ trois minutes.
Le conteneur de production sert l'application Express, qui a son tour sert le bundle React compile. Le tout est expose sur le port 3100, accèssible en local et via un reverse proxy Caddy pour l'accès externe. La health check pointe vers /api/version — une route qui renvoie simplement le numéro de version embarquée, ce qui permet de vérifier en un curl que le bon code est en production.
Ce que le harnais ne fait pas
hermes-ui est un harnais, pas un cerveau. Il ne raisonne pas, il n'interprète pas, il ne déc pas. Il transporte les messages entre l'humain et l'agent, il affiche le resultat, il gere les profils et la persistance. La ligne de démarcation est claire : tout ce qui nécessite de la comprehension est côté serveur Hermes ; tout ce qui nécessite de l'ergonomie est côté hermes-ui.
Cette separation a un coût : chaque nouvelle fonctionnalité de l'agent — un nouveau type de sous-agent, un nouvel outil, un nouveau format de widget — nécessite un travail des deux côtés. Le serveur doit produire le bon format, le front doit savoir l'afficher. Le prompt système fait le pont — c'est la que l'agent apprend comment produire du JSON valide pour chaque widget, avec des exemples et des contraintes.
Apres cinq mois de développement itératif, hermes-ui est passé de zéro a une application de plus de 450 tests, avec un store reactif, un pipeline de widgets éprouvé, et un système de profils familial. Le harnais tient. L'agent dedans aussi.
← Retour aux articles