overmind-mcp 2.8.21 → 2.8.23

package/docs/doc_hermes_gateway.md

@@ -0,0 +1,775 @@
+# 📡 Documentation — Hermes Gateway
+
+> Gateway multi-plateforme de Hermes Agent par Nous Research
+> Version : 2.1+ | Dernière MAJ : 2026-05-30
+
+---
+
+## 1. Architecture Générale
+
+```
+┌──────────────────────────────────────────────────────────┐
+│                    HERMES GATEWAY                         │
+│                                                          │
+│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐    │
+│  │Telegram  │  │ Discord │  │ Slack   │  │WhatsApp │    │
+│  │ Adapter  │  │ Adapter │  │ Adapter │  │ Adapter │    │
+│  └────┬─────┘  └────┬────┘  └────┬────┘  └────┬────┘    │
+│       │              │            │              │         │
+│  ┌────▼──────────────▼────────────▼──────────────▼────┐  │
+│  │           SESSION ROUTER (state.db)                 │  │
+│  │  • Route messages to agent sessions                 │  │
+│  │  • Channel → Session mapping                        │  │
+│  │  • Topic/Thread support                             │  │
+│  └──────────────────────┬────────────────────────────┘  │
+│                         │                                │
+│  ┌──────────────────────▼────────────────────────────┐  │
+│  │           AGENT LOOP (run_agent.py)                 │  │
+│  │  • System prompt construction                      │  │
+│  │  • LLM API calls (OpenAI format)                   │  │
+│  │  • Tool dispatch (MCP + native)                     │  │
+│  │  • Context compression                             │  │
+│  └──────────────────────┬────────────────────────────┘  │
+│                         │                                │
+│  ┌──────────────────────▼────────────────────────────┐  │
+│  │           TOOL LAYER                                │  │
+│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐           │  │
+│  │  │ Terminal  │ │ File I/O │ │ Browser  │           │  │
+│  │  └──────────┘ └──────────┘ └──────────┘           │  │
+│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐           │  │
+│  │  │ Web/HTTP │ │ Cron     │ │ Delegat. │           │  │
+│  │  └──────────┘ └──────────┘ └──────────┘           │  │
+│  │  ┌──────────────────────────────────────┐         │  │
+│  │  │ MCP Servers (HTTP/stdio)              │         │  │
+│  │  │ memory, discord, postgres, x, etc.    │         │  │
+│  │  └──────────────────────────────────────┘         │  │
+│  └───────────────────────────────────────────────────┘  │
+│                                                          │
+│  ┌───────────────────────────────────────────────────┐  │
+│  │  SERVICES ANNEXES                                  │  │
+│  │  • Cron Scheduler (jobs.py + scheduler.py)         │  │
+│  │  • Curator (skill lifecycle)                       │  │
+│  │  • Kanban (multi-agent work queue)                 │  │
+│  │  • TTS / STT                                       │  │
+│  └───────────────────────────────────────────────────┘  │
+└──────────────────────────────────────────────────────────┘
+```
+
+### Composants clés
+
+| Composant | Fichier | Rôle |
+|-----------|---------|------|
+| Gateway runner | `gateway/run.py` | Boucle principale, dispatch messages |
+| Platform adapters | `gateway/platforms/*.py` | Un adapter par plateforme |
+| Session router | `hermes_state.py` | SQLite state.db, routing |
+| Agent loop | `run_agent.py` | Conversation LLM + tools |
+| Tool dispatch | `model_tools.py` | Appels outils natifs + MCP |
+| Cron scheduler | `cron/scheduler.py` | Jobs planifiés |
+| Curator | `skills/curator.py` | Maintenance skills |
+
+---
+
+## 2. Plateformes Supportées
+
+| Plateforme | Adapter | Auth requise | Features |
+|------------|---------|-------------|----------|
+| **Telegram** | `telegram.py` | Bot Token | Topics, DMs, groupes, inline |
+| **Discord** | `discord.py` | Bot Token | Embeds, threads, réactions, boutons |
+| **Slack** | `slack.py` | Bot Token + Signing Secret | Channels, DMs, threads |
+| **WhatsApp** | `whatsapp.py` | WhatsApp Business API | Messages, médias |
+| **Signal** | `signal.py` | signal-cli | Messages, groupes |
+| **Email** | `email.py` | IMAP/SMTP | Envoi/réception, pièces jointes |
+| **SMS** | `sms.py` | Twilio / Vonage | Envoi/réception SMS |
+| **Matrix** | `matrix.py` | Homeserver + Token | Rooms, DMs |
+| **Mattermost** | `mattermost.py` | Bot Token | Channels, DMs |
+| **Home Assistant** | `homeassistant.py` | HA Webhook | Intentions, contrôle |
+| **DingTalk** | `dingtalk.py` | App Key/Secret | Messages, groupes |
+| **Feishu (Lark)** | `feishu.py` | App ID/Secret | Messages, docs |
+| **WeCom** | `wecom.py` | Corp ID + Secret | Messages |
+| **BlueBubbles** | `bluebubbles.py` | BB Server URL | iMessage |
+| **Weixin (WeChat)** | `weixin.py` | App ID/Secret | Messages |
+| **API Server** | `api_server.py` | Clé API custom | REST endpoint |
+| **Webhooks** | `webhook.py` | Route config | POST entrants |
+| **Open WebUI** | via API Server | Clé API | Interface web |
+
+### Configuration plateforme
+
+```bash
+# Setup interactif
+hermes gateway setup
+
+# Ou édition manuelle
+hermes config edit
+```
+
+Exemple config Discord :
+```yaml
+discord:
+  bot_token: ${DISCORD_BOT_TOKEN}
+  enabled: true
+  prefix: "!"
+  allowed_channels: []  # vide = tous
+```
+
+---
+
+## 3. Commandes CLI Gateway
+
+```bash
+# Démarrer le gateway (foreground)
+hermes gateway run
+
+# Installer comme service système
+hermes gateway install
+
+# Contrôle du service
+hermes gateway start
+hermes gateway stop
+hermes gateway restart
+
+# État du gateway
+hermes gateway status
+
+# Configuration initiale
+hermes gateway setup
+```
+
+### Options avancées
+
+```bash
+# Lancer avec un profil spécifique
+hermes gateway run --profile sniper
+
+# Mode verbose (debug)
+hermes gateway run --verbose
+
+# Port custom pour API server
+hermes gateway run --port 8080
+```
+
+---
+
+## 4. Configuration (config.yaml)
+
+### Sections pertinentes pour le gateway
+
+```yaml
+# === MODÈLE ===
+model:
+  default: glm-5.1
+  provider: z-ai
+  context_length: 128000
+
+# === AGENT ===
+agent:
+  max_turns: 90
+  tool_use_enforcement: true  # Oblige à utiliser les outils
+
+# === TERMINAL ===
+terminal:
+  backend: local        # local, docker, ssh
+  timeout: 180
+
+# === COMPRESSION ===
+compression:
+  enabled: true
+  threshold: 0.50       # Déclenche à 50% du context
+  target_ratio: 0.20    # Cible 20% du context
+
+# === TTS ===
+tts:
+  provider: elevenlabs
+  voice: charlie
+  voice_id: IKne3meq5aSn9XLyUdCD
+  model: eleven_multilingual_v2
+
+# === STT ===
+stt:
+  enabled: true
+  provider: local       # local, groq, openai, mistral
+  local:
+    model: base
+
+# === MÉMOIRE ===
+memory:
+  memory_enabled: true
+  user_profile_enabled: true
+  provider: built-in    # built-in, honcho, mem0
+
+# === SÉCURITÉ ===
+security:
+  redact_secrets: false
+  tirith_enabled: true
+  website_blocklist: []
+
+# === APPROBATIONS ===
+approvals:
+  mode: manual          # manual, smart, off
+
+# === MCP ===
+mcp_servers:
+  memory-server:
+    url: "http://localhost:3099/mcp"
+  discord-server:
+    url: "http://localhost:3141/mcp"
+
+# === DÉLÉGATION ===
+delegation:
+  max_concurrent_children: 3
+  max_spawn_depth: 1
+
+# === CRON ===
+# Géré via l'outil cronjob, pas de config yaml directe
+
+# === CANVAS ===
+display:
+  skin: default
+  tool_progress: true
+  show_reasoning: false
+  show_cost: false
+```
+
+---
+
+## 5. Slash Commands (Mode Gateway)
+
+### Contrôle de session
+```
+/new (/reset)        Nouvelle session
+/clear               Effacer + nouvelle session
+/retry               Renvoyer dernier message
+/undo                Annuler dernier échange
+/title [name]        Nommer la session
+/compress            Compression manuelle du contexte
+/stop                Tuer processus en arrière-plan
+/rollback [N]        Restaurer checkpoint filesystem
+```
+
+### Configuration
+```
+/config              Afficher config
+/model [name]        Changer de modèle
+/personality [name]  Changer personnalité
+/reasoning [level]   Niveau de raisonnement (none→xhigh)
+/verbose             Cycle verbose
+/voice [on|off|tts]  Mode vocal
+/yolo                Bypass approbations
+/status              Info session
+```
+
+### Outils & Skills
+```
+/tools               Gérer outils (CLI)
+/skills              Installer skills
+/skill <name>        Charger un skill
+/reload              Recharger .env
+/reload-mcp          Recharger serveurs MCP
+/cron                Gérer cron jobs
+```
+
+### Gateway
+```
+/approve             Approuver commande en attente
+/deny                Refuser commande
+/restart             Redémarrer gateway
+/sethome             Définir canal home
+/update              MAJ Hermes
+/platforms           Statut plateformes
+```
+
+### Info
+```
+/help                Aide
+/commands            Lister toutes les commandes
+/usage               Utilisation tokens
+/insights [days]     Analytics
+/debug               Upload rapport debug
+/profile             Info profil actif
+```
+
+---
+
+## 6. Cron Jobs
+
+### Fonctionnement
+
+```
+┌──────────────────────────────────────────┐
+│  CRON SCHEDULER                          │
+│  ├── cron/jobs.py      → Stockage jobs   │
+│  ├── cron/scheduler.py → Tick loop       │
+│  └── .tick.lock        → Anti-doublon    │
+│                                          │
+│  CHAQUE TICK :                           │
+│  1. Vérifie .tick.lock                   │
+│  2. Charge jobs actifs                   │
+│  3. Pour chaque job éligible :           │
+│     → Nouvelle session fraîche           │
+│     → Injecte le prompt                  │
+│     → Exécute l'agent                    │
+│     → Délivre le résultat                │
+│     → Détruit la session                 │
+│  4. Libère .tick.lock                    │
+└──────────────────────────────────────────┘
+```
+
+### Syntaxe de planification
+
+| Format | Exemple | Signification |
+|--------|---------|---------------|
+| Durée | `30m` | Toutes les 30 minutes |
+| Every | `every 2h` | Toutes les 2 heures |
+| Every day | `every monday 9am` | Chaque lundi à 9h |
+| Cron | `0 9 * * *` | Tous les jours à 9h |
+| ISO timestamp | `2026-06-01T10:00:00` | Une seule fois |
+
+### Options par job
+
+```python
+cronjob(
+  action="create",
+  name="analyse_crypto",         # Nom unique
+  schedule="every 2h",           # Planification
+  prompt="Analyse BTC...",       # Prompt auto-suffisant
+  skills=["web", "terminal"],    # Skills à charger
+  deliver="origin",              # Livraison (origin, all, platform:chat:thread)
+  model={"model": "glm-5.1"},   # Override modèle
+  workdir="/path/to/project",   # Répertoire de travail
+  enabled_toolsets=["web", "terminal", "file"],  # Restreindre outils
+  context_from=["job_id_abc"],  # Chaîner avec sortie d'un autre job
+  script="collect_data.sh",     # Script pre-run (data collection)
+  no_agent=False,                # True = script seul, pas d'agent
+  repeat=None,                   # None = récurrent, int = nombre de runs
+)
+```
+
+### Invariants cron
+
+- **Timeout hard** : 3 minutes par run
+- **skip_memory=True** par défaut (pas de mémoire auto)
+- **Pas de cron en chaîne** : un cron ne peut pas créer d'autres cron
+- **Lock file** empêche doubles ticks
+- **Session fraîche** à chaque tick (pas d'injection dans session active)
+
+---
+
+## 7. Intégration MCP
+
+### Architecture MCP dans le gateway
+
+```
+┌──────────────────────────────────────────┐
+│  AGENT SESSION                           │
+│  │                                       │
+│  ├── Outils natifs (terminal, file...)   │
+│  │                                       │
+│  └── MCP Servers                         │
+│      ├── HTTP Stream                     │
+│      │   ├── memory-server :3099         │
+│      │   ├── discord-server :3141        │
+│      │   ├── x-mcp-server :3142          │
+│      │   └── postgresql-server :5433     │
+│      │                                   │
+│      └── stdio (si configuré)            │
+│          └── custom-command --mcp        │
+└──────────────────────────────────────────┘
+```
+
+### Configuration MCP
+
+**3 niveaux par agent :**
+
+1. **`.mcp.json`** — Déclare les serveurs disponibles
+```json
+{
+  "mcpServers": {
+    "memory-server": {
+      "type": "http",
+      "url": "http://localhost:3099/mcp"
+    }
+  }
+}
+```
+
+2. **`settings.json`** — Active/filtre les serveurs
+```json
+{
+  "enabledMcpjsonServers": ["memory-server", "discord-server"],
+  "enableAllProjectMcpServers": false
+}
+```
+
+3. **`config.yaml`** — Gateway runtime
+```yaml
+mcp_servers:
+  memory-server:
+    url: "http://localhost:3099/mcp"
+```
+
+### Rechargement MCP
+
+```
+/reload-mcp           # Recharger sans restart
+/restart              # Restart complet du gateway
+```
+
+---
+
+## 8. Sécurité
+
+### Redaction des secrets
+
+```bash
+# Masquer les API keys dans le context
+hermes config set security.redact_secrets true
+
+# Désactiver
+hermes config set security.redact_secrets false
+```
+
+⚠️ **Restart requis** — ne prend pas effet mid-session.
+
+### Redaction PII
+
+```bash
+# Hasher les user IDs, strip numéros de téléphone
+hermes config set privacy.redact_pii true
+```
+
+### Modes d'approbation
+
+| Mode | Comportement |
+|------|-------------|
+| `manual` | Prompt avant chaque commande risquée (défaut) |
+| `smart` | LLM auxiliaire auto-approuve les commandes safe |
+| `off` | Bypass total (équivalent `--yolo`) |
+
+```bash
+hermes config set approvals.mode smart
+```
+
+### Allowlist shell hooks
+
+Fichier : `~/.hermes/shell-hooks-allowlist.json`
+Première exécution d'un hook → prompt interactif.
+
+---
+
+## 9. Gestion des Sessions
+
+### Architecture
+
+```
+~/.hermes/
+├── state.db           # Session store (SQLite + FTS5)
+├── sessions/
+│   ├── routing.json   # Channel → Session mapping
+│   └── *.jsonl        # Transcripts (optionnel)
+└── logs/
+    └── gateway.log    # Logs gateway
+```
+
+### Cycle de vie
+
+```
+Message entrant
+    │
+    ├── Canal connu ? → Router vers session existante
+    │                     ├── Topic/Thread ? → Sous-session
+    │                     └── Canal principal → Session principale
+    │
+    └── Nouveau canal → Créer nouvelle session
+                         ├── Charger config agent
+                         ├── Initialiser outils + MCP
+                         └── Démarrer boucle agent
+```
+
+### Commandes session
+
+```bash
+hermes sessions list          # Lister sessions récentes
+hermes sessions browse        # Picker interactif
+hermes sessions export OUT    # Exporter en JSONL
+hermes sessions rename ID T   # Renommer
+hermes sessions delete ID     # Supprimer
+hermes sessions prune         # Nettoyer vieilles sessions
+hermes sessions stats         # Statistiques du store
+```
+
+---
+
+## 10. Webhooks
+
+### Configuration
+
+```bash
+# Créer une route webhook
+hermes webhook subscribe myhook
+# → Crée /webhooks/myhook
+
+# Lister
+hermes webhook list
+
+# Supprimer
+hermes webhook remove myhook
+
+# Test
+hermes webhook test myhook
+```
+
+### Payload entrant
+
+```json
+POST /webhooks/myhook
+{
+  "message": "Analyse le marché BTC",
+  "source": "external_app",
+  "metadata": {
+    "priority": "high"
+  }
+}
+```
+
+Le gateway traite le payload comme un message utilisateur normal.
+
+---
+
+## 11. Profils
+
+### Concept
+
+Les profils permettent de faire tourner plusieurs instances Hermes isolées :
+
+```
+~/.hermes/              # Profil default
+~/.hermes/profiles/
+├── sniper/             # Profil sniper
+│   ├── config.yaml
+│   ├── .env
+│   ├── skills/
+│   └── sessions/
+└── researcher/         # Profil researcher
+    ├── config.yaml
+    └── ...
+```
+
+### Commandes
+
+```bash
+hermes profile list              # Lister profils
+hermes profile create sniper     # Créer (--clone, --clone-all)
+hermes profile use sniper        # Définir comme défaut
+hermes profile show sniper       # Détails
+hermes profile delete sniper     # Supprimer
+hermes profile rename A B        # Renommer
+hermes profile export sniper     # Export tar.gz
+hermes profile import file.tar.gz # Importer
+```
+
+### Lancer avec un profil
+
+```bash
+hermes --profile sniper
+hermes gateway run --profile sniper
+```
+
+---
+
+## 12. Credential Pools
+
+Rotation automatique des clés API pour éviter les rate limits.
+
+```bash
+hermes auth add             # Ajouter credential (wizard)
+hermes auth list [PROVIDER] # Lister credentials
+hermes auth remove P INDEX  # Supprimer par provider + index
+hermes auth reset PROVIDER  # Reset exhaustion status
+```
+
+### Comportement
+
+- Hermes essaie KEY_1 → si 429/401 → KEY_2 → si 429 → KEY_3
+- Marque les clés épuisées, les réessaie après cooldown
+- Configuré dans `.env` avec clés numérotées
+
+---
+
+## 13. TTS / STT en Gateway
+
+### TTS (Text → Voice)
+
+| Provider | Variable | Coût |
+|----------|----------|------|
+| Edge TTS | Aucune | Gratuit (défaut) |
+| ElevenLabs | `ELEVENLABS_API_KEY` | Freemium |
+| OpenAI | `VOICE_TOOLS_OPENAI_KEY` | Payant |
+| MiniMax | `MINIMAX_API_KEY` | Payant |
+| Mistral | `MISTRAL_API_KEY` | Payant |
+
+Commandes :
+```
+/voice on       # Voice-to-voice
+/voice tts      # Toujours voice
+/voice off      # Désactiver
+```
+
+### STT (Voice → Text)
+
+Transcription automatique des messages vocaux entrants.
+
+| Provider | Variable | Coût |
+|----------|----------|------|
+| Local faster-whisper | Aucune | Gratuit |
+| Groq Whisper | `GROQ_API_KEY` | Freemium |
+| OpenAI Whisper | `VOICE_TOOLS_OPENAI_KEY` | Payant |
+| Mistral Voxtral | `MISTRAL_API_KEY` | Payant |
+
+---
+
+## 14. Troubleshooting
+
+### Gateway ne démarre pas
+
+```bash
+hermes doctor           # Diagnostic complet
+hermes gateway status   # État du service
+cat ~/.hermes/logs/gateway.log | tail -50
+```
+
+### Bot Discord silencieux
+
+1. Vérifier le **Message Content Intent** dans Discord Developer Portal
+2. Vérifier `discord.bot_token` dans config
+3. Tester : `hermes gateway status`
+
+### Bot Telegram silencieux
+
+1. Vérifier `telegram.bot_token`
+2. Tester : `curl https://api.telegram.org/bot<TOKEN>/getMe`
+
+### Gateway meurt après SSH logout
+
+```bash
+sudo loginctl enable-linger $USER
+```
+
+### Gateway crash loop (systemd)
+
+```bash
+systemctl --user reset-failed hermes-gateway
+hermes gateway restart
+```
+
+### Outils MCP non disponibles
+
+```bash
+hermes mcp list           # Voir serveurs configurés
+hermes mcp test NAME      # Tester connexion
+/reload-mcp               # Recharger en session
+```
+
+### Modèle auxiliaire (vision, compression) ne fonctionne pas
+
+```bash
+hermes config set auxiliary.vision.provider openrouter
+hermes config set auxiliary.vision.model anthropic/claude-sonnet-4
+```
+
+### Memory non persistante
+
+```bash
+hermes memory status      # État du provider mémoire
+hermes config set memory.memory_enabled true
+```
+
+---
+
+## 15. Variables d'Environnement (.env)
+
+Fichier : `~/.hermes/.env`
+
+```bash
+# === PROVIDERS ===
+OPENROUTER_API_KEY=sk-or-...
+ANTHROPIC_API_KEY=sk-ant-...
+GOOGLE_API_KEY=AIza...
+DEEPSEEK_API_KEY=sk-...
+XAI_API_KEY=xai-...
+GLM_API_KEY=xxx.zai...
+MINIMAX_API_KEY=xxx
+ELEVENLABS_API_KEY=sk_...
+
+# === CREDENTIAL POOL ===
+OPENROUTER_API_KEY_2=sk-or-...
+OPENROUTER_API_KEY_3=sk-or-...
+
+# === PLATEFORMES ===
+DISCORD_BOT_TOKEN=MTk...
+TELEGRAM_BOT_TOKEN=123456:ABC...
+SLACK_BOT_TOKEN=xoxb-...
+TWILIO_ACCOUNT_SID=AC...
+TWILIO_AUTH_TOKEN=...
+
+# === MCP ===
+POSTGRES_CONNECTION_STRING=postgresql://...
+```
+
+---
+
+## 16. Chemins Importants
+
+| Chemin | Contenu |
+|--------|---------|
+| `~/.hermes/config.yaml` | Configuration principale |
+| `~/.hermes/.env` | Secrets et clés API |
+| `~/.hermes/skills/` | Skills installés |
+| `~/.hermes/sessions/` | Routing + transcripts |
+| `~/.hermes/state.db` | Session store SQLite |
+| `~/.hermes/logs/` | Logs gateway |
+| `~/.hermes/auth.json` | OAuth + credential pools |
+| `~/.hermes/hermes-agent/` | Code source |
+| `~/.hermes/shell-hooks-allowlist.json` | Allowlist hooks |
+
+---
+
+## 17. Flux de Message Complet
+
+```
+1. Utilisateur envoie message sur Discord
+   │
+2. Discord Adapter reçoit via Gateway Intent
+   │
+3. Session Router lookup (channel_id → session_id)
+   │
+   ├── Session existe → Continue conversation
+   └── Nouvelle session → Crée session fraîche
+   │
+4. Construction du system prompt
+   ├── Config agent (model, tools, persona)
+   ├── Memory injectée (user profile + memory notes)
+   ├── Skills chargés
+   └── MCP tools découverts
+   │
+5. Appel LLM (OpenAI format)
+   │
+6. Si tool_calls → Dispatch via model_tools.py
+   ├── Outils natifs (terminal, file, web...)
+   └── MCP tools (HTTP request au serveur MCP)
+   │
+7. Résultat outil → Ajouté au context → Retour étape 5
+   │
+8. Réponse texte finale
+   │
+9. Gateway envoie via Platform Adapter
+   ├── Texte simple → Message texte
+   ├── Structuré → Embed Discord / HTML Telegram
+   ├── Média → Upload fichier
+   └── TTS → Audio + transcription
+   │
+10. Logs + métriques mis à jour
+```
+
+---
+
+*Documentation générée par SniperBot Analyst — Overmind Ecosystem*
+*Source : Hermes Agent v2.1+ by Nous Research*