From d976a92857f6a0aeb6ee6b6d657d9e5a99076d33 Mon Sep 17 00:00:00 2001 From: bolbol Date: Thu, 23 Jul 2026 12:31:50 +0000 Subject: [PATCH] Runbook: migration hermes-agent 0.17->0.19 (3 instances, 2026-07-23) --- common/migration-hermes-0.19-20260723.md | 108 +++++++++++++++++++++++ 1 file changed, 108 insertions(+) create mode 100644 common/migration-hermes-0.19-20260723.md diff --git a/common/migration-hermes-0.19-20260723.md b/common/migration-hermes-0.19-20260723.md new file mode 100644 index 0000000..7a645aa --- /dev/null +++ b/common/migration-hermes-0.19-20260723.md @@ -0,0 +1,108 @@ +# Migration hermes-agent 0.17.0 -> 0.19.0 (v2026.7.20) sur les 3 agents NAS + +**Instance auteur** : Claude Code (session Nabil, token via hermes-nyora) +**Date** : 2026-07-23 +**Tags** : hermes, docker, migration, telegram, upgrade +**Statut** : valide + +--- + +## Probleme + +Faire passer les 3 agents NAS (hermes-tt, hermes-nyora, hermes-perso) de +hermes-agent 0.17.0 (2026.6.19, runtime ff50a886) a 0.19.0 (v2026.7.20), +sans perdre la personnalisation Telegram appliquee en prod. + +--- + +## Contexte et contraintes (decouvertes cles) + +- **La prod NE build PAS localement.** `docker-compose.yml` utilise + `image: nousresearch/hermes-agent:latest` (tire du Hub) — AUCUN `build:`. + Le dossier `hermes-nyora/hermes-agent-source/` est un arbre MORT, non utilise. + (Explique la contradiction source-27-mai / runtime-20-juin.) +- **La seule personnalisation prod = un bind-mount RO dans le compose** (x3) : + `patches/telegram.py:/opt/hermes/gateway/platforms/telegram.py:ro`. + Ce patch (fix overflow/continuation Telegram en streaming, ~94 lignes) est + **OBSOLETE en 0.19** : Telegram y est refactore en plugin + `plugins/platforms/telegram/adapter.py` qui contient deja le fix nativement. +- **En 0.19, `gateway/platforms/telegram.py` n'existe plus** : garder le + bind-mount reinjecterait un module mort -> il faut le RETIRER. +- ff50a886 = `v2026.6.19-44-g...` (44 commits apres le tag 0.17.0), ancetre de + v2026.7.20. Aucun breaking change config/SOUL/skills (0.17->0.19), seulement + additif ; les cles inconnues avertissent (ne cassent pas). +- config/SOUL/skills/jobs.json vivent dans le volume `/opt/data` par instance : + NON touches par le changement d'image (verifie bit-a-bit sur tt). + +--- + +## Ce qui NE fonctionne PAS + +| Tentative | Erreur / effet | Raison | +|-----------|----------------|--------| +| Garder le bind-mount telegram.py en 0.19 | fichier mort injecte dans gateway/platforms/ | cible refactoree en plugins/platforms/telegram/ | +| Chercher un `RUN patch` dans le Dockerfile | introuvable | le patch n'a jamais transite par un build, uniquement par le bind-mount compose | +| API Gitea via `gitea:3000` depuis conteneur hermes | HTTP 000 | Gitea sert son HTTP sur 3232 (pas 3000) ; utiliser host:3232 ou gitea:3232 | + +--- + +## Solution validee (par instance, ordre : nyora -> perso -> tt) + +```bash +cd /volume1/docker/hermes-platform +# 0. Pre-vol (une fois) : backups horodates + tag image rollback +TS=$(date +%Y%m%d-%H%M) +cp docker-compose.yml docker-compose.yml.bak-$TS +/usr/local/bin/docker tag nousresearch/hermes-agent:rollback-ff50a886 +# snapshots /opt/data des 3 instances (tar -I 'gzip -1') + +# 1. Editer le BLOC de l'instance (seulement) : +# image: ...:latest -> image: nousresearch/hermes-agent:v2026.7.20 +# supprimer la ligne - .../patches/telegram.py:...:ro +# ATTENTION : les numeros de ligne se decalent a chaque suppression, re-grep avant chaque edit. + +# 2. Recreer uniquement ce service +/usr/local/bin/docker compose pull hermes-agent- # une fois suffit (tag partage) +/usr/local/bin/docker compose up -d hermes-agent- +``` + +Faire valider chaque instance (dont test Telegram >4096 par l'utilisateur +autorise) AVANT de passer a la suivante. tt en dernier (critique, achats/AO). + +--- + +## Verification (par instance) + +```bash +D=/usr/local/bin/docker +$D inspect -f '{{.State.Health.Status}}' hermes-agent- # healthy +$D exec hermes-agent- hermes --version # v0.19.0 (2026.7.20) upstream 3ef6bbd2 +$D exec hermes-agent- ls /opt/hermes/plugins/platforms/telegram/adapter.py # present +$D exec hermes-agent- sh -lc 'test -e /opt/hermes/gateway/platforms/telegram.py && echo PROBLEME || echo ABSENT_ok' +$D exec hermes-agent- sh -lc 'curl -s -o /dev/null -w "%{http_code}\n" https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getMe' # 200 +$D exec hermes-agent- hermes config check # aucune erreur +# + test manuel Telegram >4096 caracteres (continuations propres) +``` +Specifique tt : `curl http://hermes-mail-browser:8000/health` (200) ; +skill `/opt/data/skills/mail-o365-tt.md` intact (md5) ; `PROTOCOL-INFRA.md` +sans valeur O365_PASS (seule la ligne d'audit de purge) ; `cron/jobs.json` +intact (Veille JORT, Brief RLA, Courriels TT). + +Observation non bloquante 0.19 : 3 skills perdent leur slash-command auto +(collision core) -> utiliser `/skill agents|kanban|handoff`. + +--- + +## Rollback (par instance) + +Rediter le bloc -> `image: nousresearch/hermes-agent:rollback-ff50a886` ++ reajouter la ligne bind-mount patches/telegram.py, puis +`docker compose up -d hermes-agent-`. `/opt/data` non modifie par +l'image ; snapshot dispo au besoin. + +--- + +## Resultat + +Migration reussie 3/3 le 2026-07-23 : nyora, perso, tt en v0.19.0, plugin +Telegram natif, 0 bind-mount restant, tests Telegram >4096 confirmes sur les 3.