Files

T

gilles 0fbca06d3d docs: roadmap tâches 1.9-8 (briefs, gates de validation, designs tâche 2) + plans d'implémentation

Cartographie complète (liste_taches/coherence_taches), briefs tacheN + gates
validation_tacheN, design tâche 2 (docs/design/tache2/), specs/plans jalon 1-2
et tâche 1.9/2 (Phase 1, Phase 2, SJ-0→3). Validations consignées (1.9 ✅, 2-8 🟡).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-06-05 19:50:25 +02:00

16 KiB

Raw Blame History

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 :

Depuis la webapp : le volet gauche permet de discuter avec Hermes, demander une analyse, un rapport, un plan, ou une action proposée.
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

┌──────────────────────────────┐
│ 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é :

Utilisateur écrit dans le volet gauche.
Frontend envoie le message au backend system_update.
Backend ajoute un contexte système court :
- rôle Hermes ;
- interdiction secrets ;
- appeler MCP/API pour données machine ;
- actions dangereuses = validation webapp.
Backend appelle Hermes API Server sur 10.0.0.80:8642.
Réponse streamée vers le volet gauche.
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 :

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 :

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 :

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 :

{
  "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 :

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 :

machine_state ;
profil OS/type machine, hardware et métriques simples ;
snapshots JSON réduits ;
messages importants ;
rapports Markdown ;
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 :

~/.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 :

Lister machines via MCP.
Récupérer snapshots récents.
Si snapshots trop anciens, demander run_refresh.
Dédupliquer updates APT/Docker.
Récupérer les messages importants non acquittés.
Classer risques, warnings futurs et notices sécurité.
Produire rapport.
Si action demandée, créer demande de validation via request_action.
Après exécution, analyser ExecutionResult, messages importants et extraits de logs utiles.

7. Rapports Hermes

Rapport global attendu :

# 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 :

{
  "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/ :

Architecture Hermes/webapp/MCP.
Spécification du proxy backend vers Hermes API Server.
Spécification MCP system_update.
Spec du skill system-update-ops.
Spec des rapports globaux.
Spec notifications/webhooks Hermes.
Sécurité et validations.
Plan de déploiement Hermes sur 10.0.0.80.
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.

16 KiB Raw Blame History

Consigne de dev — Hermes, volet gauche, MCP, skills et messagerie

0. Contexte

1. Outils Hermes pertinents à déployer

API Server Hermes

MCP HTTP côté system_update

Skills Hermes

Messaging Gateway

Webhooks Hermes

Cron Hermes

2. Architecture cible

3. Cas 1 — Volet gauche Hermes dans la webapp

4. Cas 2 — Hermes TUI ou messagerie contrôle system_update

5. Tools MCP system_update

Terminal SSH interactif

6. Skill Hermes system-update-ops

7. Rapports Hermes

8. Notifications et webhooks

9. Sécurité

10. Livrables attendus

11. Définition de terminé

12. Technos à utiliser — checklist

13. URLs utiles

14. Liens parent/enfant avec les autres tâches

16 KiB

Raw Blame History

6. Skill Hermes `system-update-ops`