# Consigne de dev — Hermes, volet gauche, MCP, skills et messagerie > **Type** : mission d'**investigation + design intégration agent** (PAS d'implémentation). > **Langue** : français. > **Livrable final attendu** : spec d'intégration Hermes prête à passer en plan d'implémentation. --- ## 0. Contexte L'utilisateur dispose d'un agent Hermes sur `10.0.0.80`. Deux usages sont visés : 1. **Depuis la webapp** : le volet gauche permet de discuter avec Hermes, demander une analyse, un rapport, un plan, ou une action proposée. 2. **Depuis Hermes TUI ou messagerie** : l'utilisateur parle à Hermes ailleurs, puis Hermes utilise un skill et/ou MCP pour analyser une ou plusieurs machines, générer un rapport global, demander/lancer des upgrades validés, analyser les retours et erreurs. Docs Hermes consultées : - Documentation générale : https://hermes-agent.nousresearch.com/docs/ - API Server : https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server/ - MCP : https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp/ - Use MCP with Hermes : https://hermes-agent.nousresearch.com/docs/guides/use-mcp-with-hermes - Skills System : https://hermes-agent.nousresearch.com/docs/user-guide/features/skills - Cron : https://hermes-agent.nousresearch.com/docs/user-guide/features/cron - Messaging Gateway : https://hermes-agent.nousresearch.com/docs/user-guide/messaging - Webhooks : https://hermes-agent.nousresearch.com/docs/user-guide/messaging/webhooks/ --- ## 1. Outils Hermes pertinents à déployer D'après la documentation Hermes, les briques pertinentes sont : ### API Server Hermes Hermes expose un serveur HTTP compatible OpenAI. La doc indique : - activer `API_SERVER_ENABLED=true` ; - définir `API_SERVER_KEY` ; - lancer `hermes gateway` ; - endpoint typique `http://host:8642/v1`. Usage dans ce projet : - le volet gauche de la webapp parle au backend `system_update` ; - le backend relaie vers Hermes API Server sur `10.0.0.80:8642` ; - l'API key Hermes reste côté backend, jamais dans le navigateur ; - streaming via `/v1/runs` ou Chat Completions selon support détecté. ### MCP HTTP côté system_update Hermes sait se connecter à des serveurs MCP HTTP (`url`, `headers`) et filtrer les tools exposés. Usage dans ce projet : - `system_update` expose un serveur MCP HTTP interne ; - Hermes sur `10.0.0.80` déclare ce MCP dans `~/.hermes/config.yaml` ; - seuls les tools sûrs/minimaux sont exposés ; - les actions dangereuses créent une demande de validation webapp au lieu de s'exécuter directement. ### Skills Hermes Hermes charge des skills depuis `~/.hermes/skills/`, avec `SKILL.md`, références, scripts et slash commands. Usage dans ce projet : - créer un skill `system-update-ops` ; - il apprend à lire les snapshots JSON ; - il produit rapports globaux ; - il sait demander des refresh ; - il sait créer une proposition d'upgrade ; - il sait analyser erreurs APT/Docker/post-install ; - il ne manipule jamais les secrets. ### Messaging Gateway Hermes peut être utilisé depuis Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Email, SMS, Home Assistant, Mattermost, Teams, etc. Usage dans ce projet : - permettre à l'utilisateur de demander depuis un messager : - "analyse toutes les machines" ; - "fais un rapport global" ; - "prépare les upgrades" ; - "analyse l'échec sur vm_mqtt". ### Webhooks Hermes Hermes expose un adaptateur webhook avec HMAC, routes et livraison. Il peut fonctionner en mode agent ou `deliver_only`. Usage dans ce projet : - envoyer à Hermes une notification quand un job backend termine ; - notifier un canal messagerie après schedule automatique ; - transmettre un résumé JSON réduit ; - utiliser `deliver_only` pour notifications simples sans LLM. ### Cron Hermes Hermes peut planifier des tâches avec `/cron` ou `hermes cron`, charger des skills et livrer des résultats. Usage dans ce projet : - optionnel : planifier côté Hermes des audits périodiques de haut niveau ; - recommandé : garder les refresh machine opérationnels côté backend `system_update` (tâche 5), et utiliser Hermes cron pour rapports/analyses/résumés, pas pour exécuter SSH. --- ## 2. Architecture cible ```text ┌──────────────────────────────┐ │ Webapp system_update │ │ ┌──────────┬───────────────┐ │ │ │ Hermes │ Dashboard │ │ │ │ chat │ tuiles │ │ │ └──────────┴───────────────┘ │ └───────────────┬──────────────┘ │ HTTP/SSE ┌───────────────▼──────────────┐ │ Backend system_update │ │ - API machines/actions │ │ - stockage JSON │ │ - MCP HTTP server │ │ - proxy Hermes API │ └───────┬─────────────────┬────┘ │ │ │ MCP HTTP │ OpenAI-compatible API │ │ ┌───────▼─────────────────▼────┐ │ Hermes Agent 10.0.0.80 │ │ - API Server : :8642 │ │ - Gateway messaging │ │ - Skills system-update-ops │ │ - MCP client system_update │ └───────────────────────────────┘ ``` Règle forte : > Hermes ne fait jamais de SSH directement vers les machines. Il passe par les tools MCP/API de `system_update`. --- ## 3. Cas 1 — Volet gauche Hermes dans la webapp Flux recommandé : 1. Utilisateur écrit dans le volet gauche. 2. Frontend envoie le message au backend `system_update`. 3. Backend ajoute un contexte système court : - rôle Hermes ; - interdiction secrets ; - appeler MCP/API pour données machine ; - actions dangereuses = validation webapp. 4. Backend appelle Hermes API Server sur `10.0.0.80:8642`. 5. Réponse streamée vers le volet gauche. 6. Si Hermes propose une action, la webapp l'affiche comme carte de validation, pas comme exécution directe. Exigences UX pour la discussion : - séparation claire entre messages utilisateur, messages Hermes et messages système ; - copier-coller natif du texte ; - bouton copier sur chaque message long ; - blocs de commande monospace avec bouton copier ; - références cliquables vers machine, snapshot, exécution, rapport ou extrait de log ; - action proposée rendue dans une carte validable séparée du texte ; - aucun secret dans l'historique envoyé à Hermes ou affiché au navigateur. Endpoints frontend/backend à concevoir : ```text POST /api/hermes/chat GET /api/hermes/runs/:runId/events POST /api/hermes/runs/:runId/stop GET /api/hermes/health GET /api/hermes/capabilities ``` Le backend doit vérifier `/v1/health` et `/v1/capabilities` Hermes. Configuration : ```text HERMES_BASE_URL=http://10.0.0.80:8642/v1 HERMES_API_KEY=... HERMES_SESSION_KEY=system-update-webapp ``` L'API key n'est jamais exposée au navigateur. --- ## 4. Cas 2 — Hermes TUI ou messagerie contrôle system_update Depuis Hermes TUI/messagerie, l'utilisateur peut demander : - analyser une machine ; - analyser toutes les machines ; - faire un rapport global ; - comparer les updates ; - proposer un ordre de mise à jour ; - demander un upgrade ; - analyser le résultat ; - expliquer une erreur. Hermes utilise alors : - skill `system-update-ops` ; - MCP HTTP `system_update`. Exemple `~/.hermes/config.yaml` : ```yaml mcp_servers: system_update: url: "http://10.0.0.X:8787/mcp" headers: Authorization: "Bearer ${SYSTEM_UPDATE_MCP_TOKEN}" tools: include: - list_machines - get_machine_state - get_machine_hardware - get_machine_metrics - get_machine_snapshot - get_all_snapshots - get_machine_execution - get_machine_messages - search_reports - get_report - search_log_artifacts - run_refresh - request_action - get_pending_actions - preview_template - list_templates resources: false prompts: false ``` Le tool `request_action` ne lance pas directement les actions dangereuses. Il crée une demande : ```json { "requestId": "req_x", "machineId": "vm_mqtt", "action": "apt_upgrade", "status": "pending_user_approval", "summary": "4 paquets seront mis à jour", "risk": "medium" } ``` La webapp affiche la demande et l'utilisateur valide. --- ## 5. Tools MCP system_update Surface minimale à concevoir : ```text list_machines get_machine_state get_machine_hardware get_machine_metrics get_machine_snapshot get_all_snapshots get_machine_execution get_machine_messages search_reports get_report search_log_artifacts run_refresh request_action get_pending_actions preview_template list_templates ``` À éviter au MVP : - accès log brut complet non filtré ; - accès secrets ; - actions SSH directes depuis Hermes ; - suppression destructive ; - modification template sans validation. Accès logs/rapports autorisé : - `search_reports` : recherche dans titres/résumés/rapports Markdown ; - `get_report` : lecture d'un rapport archivé, sans secret ; - `get_machine_messages` : warnings/erreurs/dépréciations extraits des logs ; - `search_log_artifacts` : recherche ciblée dans logs bruts avec limites, masquage et pagination ; - `get_log_excerpt` (futur, hors liste MVP) : extrait par `artifactId` et plage de lignes, jamais log complet par défaut. Hermes doit travailler d'abord sur : 1. `machine_state` ; 2. profil OS/type machine, hardware et métriques simples ; 3. snapshots JSON réduits ; 4. messages importants ; 5. rapports Markdown ; 6. extraits de logs ciblés seulement si nécessaire. ### Terminal SSH interactif La webapp peut prévoir un vrai terminal SSH interactif dans le volet droit, mais ce n'est pas un tool Hermes. Règles : - l'utilisateur ouvre lui-même une session SSH interactive ; - Hermes peut suggérer une commande copiable ; - Hermes ne peut pas injecter une commande dans le terminal interactif ; - une commande copiée/collée reste une action utilisateur ; - ouverture/fermeture de session auditée ; - désactivation globale possible ; - session non persistée dans Hermes ; - logs de session conservés uniquement selon paramètre explicite, avec masquage secrets. Actions dangereuses : - `apt_full_upgrade` - `apt_dist_upgrade` - `docker_prune` - `docker_down` - `post_install_identity_network` - `reboot_verified` Ces actions doivent passer par validation UI. --- ## 6. Skill Hermes `system-update-ops` Créer une spec de skill : ```text ~/.hermes/skills/devops/system-update-ops/ ├─ SKILL.md ├─ references/ │ ├─ json-contracts.md │ ├─ apt-error-taxonomy.md │ ├─ important-messages-taxonomy.md │ ├─ docker-compose-workflow.md │ ├─ log-access-policy.md │ └─ safety-rules.md └─ templates/ ├─ global-report.md ├─ machine-report.md └─ upgrade-plan.md ``` Déclencheurs : - "analyse mes machines" - "rapport global system_update" - "pourquoi l'upgrade a échoué" - "prépare les mises à jour" - "propose un ordre d'upgrade" Procédure du skill : 1. Lister machines via MCP. 2. Récupérer snapshots récents. 3. Si snapshots trop anciens, demander `run_refresh`. 4. Dédupliquer updates APT/Docker. 5. Récupérer les messages importants non acquittés. 6. Classer risques, warnings futurs et notices sécurité. 7. Produire rapport. 8. Si action demandée, créer demande de validation via `request_action`. 9. Après exécution, analyser `ExecutionResult`, messages importants et extraits de logs utiles. --- ## 7. Rapports Hermes Rapport global attendu : ```text # Rapport global system_update ## Résumé - Machines OK - Machines avec updates - Machines en erreur - Reboots requis ## APT - Paquets par machine - Doublons - Risques ## Docker - Stacks avec updates - Pull errors - Prune possible ## Post-install - Profils manquants - Actions recommandées ## Plan proposé 1. Machine A 2. Machine B ## Actions en attente de validation ``` Le rapport doit être archivable côté backend et consultable depuis la webapp. --- ## 8. Notifications et webhooks Le backend `system_update` peut appeler Hermes Webhooks : - job automatique terminé ; - updates détectées ; - erreur critique ; - machine non revenue après reboot ; - rapport global prêt. Webhook Hermes recommandé : - HMAC obligatoire ; - payload JSON réduit ; - mode `deliver_only` pour notifications simples ; - mode agent avec skill `system-update-ops` pour synthèse. Exemple payload : ```json { "event": "updates_available", "machineCount": 3, "aptUpdates": 12, "dockerUpdates": 2, "reportRef": "reports/global/..." } ``` --- ## 9. Sécurité Règles non négociables : - Hermes ne reçoit jamais de mot de passe SSH/sudo/token registry ; - Hermes ne fait jamais SSH directement ; - Hermes ne reçoit pas les logs bruts complets par défaut ; - MCP expose seulement les tools whitelistés ; - actions dangereuses = validation UI ; - API Hermes appelée par backend seulement ; - token MCP avec rotation possible ; - audit des demandes Hermes ; - prompt injection : les données machine/logs sont traitées comme non fiables. --- ## 10. Livrables attendus À produire sous `docs/` : 1. Architecture Hermes/webapp/MCP. 2. Spécification du proxy backend vers Hermes API Server. 3. Spécification MCP `system_update`. 4. Spec du skill `system-update-ops`. 5. Spec des rapports globaux. 6. Spec notifications/webhooks Hermes. 7. Sécurité et validations. 8. Plan de déploiement Hermes sur `10.0.0.80`. 9. Découpage en sous-jalons. --- ## 11. Définition de terminé - Les deux cas d'usage sont couverts : volet gauche et TUI/messagerie. - Les outils Hermes à déployer sont listés. - Le MCP minimal est défini. - Le skill Hermes est spécifié. - Les actions dangereuses ne peuvent pas être exécutées sans validation webapp. - Les secrets restent côté backend. - Aucun code de production n'est livré pendant cette mission de design. --- ## 12. Technos à utiliser — checklist - [ ] Hermes API Server côté agent. - [ ] Backend proxy vers Hermes, clé jamais dans navigateur. - [ ] MCP HTTP exposé par `system_update`. - [ ] Skill Hermes `system-update-ops`. - [ ] Webhooks Hermes pour notifications. - [ ] Messaging Gateway si canaux externes utilisés. - [ ] JSON réduit, références rehydratables. - [ ] Audit MCP/API. - [ ] Validation UI obligatoire pour actions dangereuses. - [ ] Aucun SSH direct depuis Hermes. ## 13. URLs utiles - Hermes docs : https://hermes-agent.nousresearch.com/docs/ - Hermes API Server : https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server/ - Hermes MCP : https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp/ - Use MCP with Hermes : https://hermes-agent.nousresearch.com/docs/guides/use-mcp-with-hermes - Hermes Skills : https://hermes-agent.nousresearch.com/docs/user-guide/features/skills - Hermes Messaging : https://hermes-agent.nousresearch.com/docs/user-guide/messaging - Hermes Webhooks : https://hermes-agent.nousresearch.com/docs/user-guide/messaging/webhooks/ - Model Context Protocol : https://modelcontextprotocol.io/ - JSON Schema : https://json-schema.org/ ## 14. Liens parent/enfant avec les autres tâches - Parents : - `tache5.md` pour API, stockage et action requests. - `tache1.9.md` pour tables Hermes/MCP/audit. - `tache2.md` pour contrats JSON. - `tache7.md` pour réduction tokens. - Enfants : - `tache3.md` intègre le volet Hermes web. - `tache8.md` peut exposer une vue Hermes native via backend. - Validation : `validation_tache6.md`.