# 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 <ID_IMAGE_0.17> 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-<inst>   # une fois suffit (tag partage)
/usr/local/bin/docker compose up -d hermes-agent-<inst>
```

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-<inst>          # healthy
$D exec hermes-agent-<inst> hermes --version                          # v0.19.0 (2026.7.20) upstream 3ef6bbd2
$D exec hermes-agent-<inst> ls /opt/hermes/plugins/platforms/telegram/adapter.py  # present
$D exec hermes-agent-<inst> sh -lc 'test -e /opt/hermes/gateway/platforms/telegram.py && echo PROBLEME || echo ABSENT_ok'
$D exec hermes-agent-<inst> 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-<inst> 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-<inst>`. `/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.