diff --git a/_INDEX.md b/_INDEX.md index cfc660f..19728da 100644 --- a/_INDEX.md +++ b/_INDEX.md @@ -10,6 +10,7 @@ | Runbook | Date | Tags | |---------|------|------| +| [Déploiement Superpowers — Flotte Hermes Agent, Claude Code & Antigravity (procédure, piège TLS 1.3, piège SSH PATH Synology)](common/superpowers-hermes-installation.md) | 2026-08-18 | hermes, superpowers, plugins, skills, tls, ssh, synology, claude-code, antigravity | | [baserow-schema-mcp — 4 outils de gestion de schema (create/delete table/field), companion service au MCP natif Baserow](common/baserow-schema-mcp.md) | 2026-08-17 | baserow, mcp, schema, jwt | | [Rotation des secrets — inventaire, portée réelle par empreinte, anomalies inter-sphères](common/rotation-secrets-inventaire.md) | 2026-07-18 | securite, secrets, rotation | | [Bifrost — routage texte par coût : état de la mesure, logs.db, clés virtuelles, incident 401](common/bifrost-routage-par-cout.md) | 2026-07-18 | bifrost, llm, cout, routage | diff --git a/common/superpowers-hermes-installation.md b/common/superpowers-hermes-installation.md new file mode 100644 index 0000000..53b52f9 --- /dev/null +++ b/common/superpowers-hermes-installation.md @@ -0,0 +1,141 @@ +# Déploiement Superpowers (obra/superpowers) — Flotte Hermes Agent, Claude Code & Antigravity + +**Instance auteur** : hermes-perso +**Date** : 2026-08-18 +**Tags** : [hermes, superpowers, plugins, skills, tls, ssh, synology, claude-code, antigravity] +**Statut** : valide + +--- + +## Probleme + +Déployer le framework de compétences et de méthodologie agentique **Superpowers** (`obra/superpowers`) de manière unifiée et sécurisée sur : +1. Les trois instances Hermes Agent NAS (`hermes-agent-nyora`, `hermes-agent-tt`, `hermes-agent-perso`) sous Docker. +2. Claude Code (extension VS Code / CLI). +3. Antigravity (`agy`). + +Le déploiement sur le NAS a rencontré plusieurs blocages d'infrastructure critiques : +- Blocage réseau lors des requêtes/clones HTTPS vers `github.com` (handshake TLS 1.3 bloqué/timeout). +- Commandes `docker` introuvables lors des accès SSH non-interactifs. +- Présence d'un clone dormant précoce sur `hermes-agent-perso` sans support natif `.hermes-plugin`. + +--- + +## Contexte et contraintes + +- **Hôte** : Synology NAS DS920+ (DSM 7.x, Linux 4.4 kernel). +- **Conteneurs** : `nousresearch/hermes-agent:v2026.8.3` (UID 1026, GID 100, utilisateur `hermes`). +- **Gestionnaire de processus interne** : s6-overlay (`s6-rc`, `s6-supervise`). +- **Canari strict** : déploiement ordonné (`nyora` -> `tt` -> `perso`) avec tests Telegram bloquants (`@HermesNyoraBot`, `@HermesTTBot`, `@HermesPersoBot`). Tolérance zéro pour les régressions sur TT. + +--- + +## Ce qui NE fonctionne PAS + +| Tentative | Erreur obtenue | Raison de l'echec | +|-----------|----------------|-------------------| +| `hermes plugins install obra/superpowers` direct | `fatal: unable to access 'https://github.com/...': Failed to connect... Connection timed out` | Le handshake TLS 1.3 sortant vers `github.com` est intercepté/droppé sur le réseau NAS/Docker (CrowdSec / firewall Synology). Seul TLS 1.2 passe. | +| `docker exec ...` via SSH non-interactif | `sh: docker: command not found` (exit code 127) | Les sous-shells non-interactifs sur Synology DSM démarrent avec un `$PATH` minimal (`/usr/bin:/bin`) qui n'inclut pas `/usr/local/bin`. | +| Utilisation du clone existant `/opt/data/skills/superpowers` (du 17/06) | Inactif, non chargé par le plugin manager | Clone créé avant le support officiel Hermes Plugin (dossier `.hermes-plugin` absent). | +| `hermes skills update ` pour découvrir de nouveaux skills | `No updates available` | La commande `skills update` ne découvre que les mises à jour de skills déjà installés, pas les nouveaux skills ajoutés à un tap distant. | + +--- + +## Solution validee + +### 1. Piège SSH PATH Synology + +Toujours exporter explicitement le chemin `/usr/local/bin` dans toute commande SSH non-interactive : + +```bash +ssh -p 22222 Best0f@192.168.100.33 "export PATH=/usr/local/bin:\$PATH; " +``` + +### 2. Contournement réseau TLS 1.2 (Système + Utilisateur) + +Forcer Git en TLS 1.2 au niveau système (`/etc/gitconfig`) ET utilisateur (`/opt/data/home/.gitconfig`) dans chaque conteneur : + +```bash +for c in hermes-agent-nyora hermes-agent-tt hermes-agent-perso; do + docker exec $c git config --system http.sslVersion tlsv1.2 + docker exec -u hermes $c git config --global http.sslVersion tlsv1.2 +done +``` + +### 3. Nettoyage du clone dormant sur hermes-agent-perso + +Renommer le clone obsolète sans le supprimer : + +```bash +docker exec hermes-agent-perso mv /opt/data/skills/superpowers /opt/data/skills/superpowers.STALE-pre-hermes-plugin-support-20260818 +``` + +### 4. Déploiement canari séquentiel sur Hermes Agent + +Pour chaque instance (`nyora`, puis `tt`, puis `perso`) : + +```bash +# 1. Installation du plugin +docker exec -u hermes hermes-agent- hermes plugins install obra/superpowers --enable + +# 2. Redémarrage du conteneur (chargement s6 propre) +docker restart hermes-agent- + +# 3. Vérification locale +docker exec -u hermes hermes-agent- hermes plugins list --plain --no-bundled +docker logs --tail 40 hermes-agent- + +# 4. Gate Bloquant Telegram : tester le bot correspondant avec une intention de création ("on va construire X") +# Confirmer le réflexe brainstorming avant de passer à l'instance suivante. +``` + +### 5. Claude Code (Extension VS Code & CLI) + +Puisque le binaire `claude` est présent (`~/.local/bin/claude` — Cas A) : + +```bash +claude plugin install superpowers@claude-plugins-official +``` +*Note : Recharger la fenêtre VS Code (`Developer: Reload Window`) pour que l'extension prenne en compte le plugin partagé.* + +### 6. Antigravity + +Installation directe via le gestionnaire de plugins d'Antigravity : + +```bash +agy plugin install https://github.com/obra/superpowers +``` + +--- + +## Verification + +```bash +# 1. Hermes Agent +docker exec -u hermes hermes-agent-nyora hermes plugins list --plain --no-bundled +# Attendu: enabled user 6.3.0 superpowers + +# 2. Claude Code +claude plugin list --json +# Attendu: "id": "superpowers@claude-plugins-official", "enabled": true + +# 3. Antigravity +agy plugin list +# Attendu: "name": "superpowers", "components": ["skills", "hooks"] +``` + +--- + +## Pieges specifiques DSM / NAS + +1. **TLS 1.3 dropping** : Tout outil effectuant des requêtes HTTPS directes vers GitHub (pip, npm, git) doit être configuré pour forcer TLS 1.2 si un timeout survient lors du handshake. +2. **Utilisateur hermes vs root** : `docker exec` exécute par défaut sous `root`. Les commandes `hermes plugins` et les fichiers de config utilisateur doivent impérativement être exécutés sous `-u hermes` (UID 1026) pour éviter des corruptions de permissions dans `/opt/data/`. +3. **Absence de hook post-compaction Hermes** : En cas de très longue session Telegram compactée dès son premier tour, le bootstrap Superpowers peut se désactiver. Ouvrir une session fraîche restaure l'amorçage. + +--- + +## References + +- [Repo upstream obra/superpowers](https://github.com/obra/superpowers) +- [Documentation Nous Research Hermes Agent](https://github.com/NousResearch/Hermes-Agent) +- [PROTOCOL-INFRA NAS DS920+](common/PROTOCOL-INFRA.md)