overmind-mcp 3.5.2 → 3.6.0

package/docs/overmind-bridge-persistent-agents.md

@@ -1,892 +1,463 @@
-# 🌉 Overmind Bridge — Agents Persistants & A2A
+# 🌉 Architecture 6 Bridges Isolés NEXUS — Peer-to-Peer
 
-> **Version**: Overmind v3.5.0 — `src/bridge/` (1928 lignes OverBridgeServer + 443 OverBridgeService + 259 AgentRegistry)
-> **Date**: 2026-07-09
-> **Source**: `src/bridge/OverBridgeServer.ts`, `src/bridge/OverBridgeService.ts`, `src/bridge/AgentRegistry.ts`, `src/bin/overmind-bridge.ts`, `discord_llm/src/overmind-bridge.ts`
+> **Version**: NEXUS V17 — Architecture corrigée 2026-07-09
+> **Pattern**: 6 processes `overmind-bridge` INDÉPENDANTS, communication HTTP A2A inter-bridges
+> **PAS de dispatcher central sur :3100** — chaque bridge a son port, son agent, son .env, ses logs
 
 ---
 
-## Table des Matières
-
-1. [Vue d'Ensemble](#vue-densemble)
-2. [Architecture du Bridge](#architecture-du-bridge)
-3. [Les 3 Couches de Persistance](#les-3-couches-de-persistance)
-4. [AgentRegistry — État Live en Mémoire](#agentregistry--état-live-en-mémoire)
-5. [SessionStore — Sessions Multi-Tenant](#sessionstore--sessions-multi-tenant)
-6. [MessageLog — Persistence Postgres](#messagelog--persistence-postgres)
-7. [JSON-RPC 2.0 — Toutes les Méthodes](#json-rpc-20--toutes-les-méthodes)
-8. [A2A — Agent-to-Agent](#a2a--agent-to-agent)
-9. [A2A Extended — Broadcast, Pipeline, Fanout, Delegate, Query](#a2a-extended--broadcast-pipeline-fanout-delegate-query)
-10. [Comment Construire un Agent Persistant (comme discord_llm)](#comment-construire-un-agent-persistant-comme-discord_llm)
-11. [CLI overmind-bridge](#cli-overmind-bridge)
-12. [Démarrer le Serveur Bridge](#démarrer-le-serveur-bridge)
+## ❌ Ce que ce n'est PAS
 
----
-
-## Vue d'Ensemble
-
-L'Overmind Bridge est un **serveur HTTP JSON-RPC 2.0** qui transforme les appels MCP one-shot en conversations persistantes et multi-tenant. C'est la couche qui rend les agents "always-on" — même entre deux requêtes Discord, l'état de l'agent (session, contexte, mémoire) est préservé.
+- ❌ Un seul `OverBridgeServer` partagé sur :3100 qui dispatche
+- ❌ Un `OvermindBridge` qui route les appels vers les 6 agents
+- ❌ Un bridge "central" qui connaît tous les agents
 
-### Le Problème Résolu
+## ✅ Ce que c'est
 
-```
-Sans Bridge:
-  Discord !sniper → spawn hermes CLI → répond → meurt
-  Discord !sniper → spawn hermes CLI → répond → meurt  (perte de contexte!)
+Chaque agent NEXUS = **un process `overmind-bridge server` autonome** avec :
+- Son propre port dédié
+- Son agent dédié (configuré via flag)
+- Son propre .env (clés API, peers)
+- Ses propres logs
+- Ses propres clients HTTP vers les autres bridges
 
-Avec Bridge:
-  Discord !sniper → POST /rpc agent.run → agent (session persistée)
-  Discord !sniper → POST /rpc agent.run → agent (MÊME session, contexte conservé!)
-```
+La communication A2A = **HTTP POST inter-bridges** : agent A veut parler à agent B → POST `http://localhost:<port_b>/rpc` avec `agent.run`.
 
 ---
 
-## Architecture du Bridge
+## Allocation des Ports
 
-```
-┌──────────────────────────────────────────────────────────────────┐
-│                     CLIENTS (Discord, curl, Python)               │
-│                                                                   │
-│  discord_llm/overmind-bridge.ts    overmind-bridge CLI            │
-│  (Express, port 3001)              (call, scenario, status)       │
-└──────────────────────┬───────────────────────┬───────────────────┘
-                       │ POST /rpc              │
-                       │ JSON-RPC 2.0           │
-                       ▼                        ▼
-┌──────────────────────────────────────────────────────────────────┐
-│               OverBridgeServer (port 3100)                        │
-│               src/bridge/OverBridgeServer.ts                      │
-│                                                                   │
-│  ┌─────────────────────────────────────────────────────────────┐ │
-│  │  dispatchRpc() — route les méthodes JSON-RPC                │ │
-│  │  agent.run | agent.a2a | agent.broadcast | agent.pipeline   │ │
-│  │  agent.fanout | agent.delegate | agent.query                │ │
-│  │  agent.status | agent.list | agent.kill                     │ │
-│  │  message.history | message.get | message.replay | stats     │ │
-│  │  session.get | session.list | session.delete | session.stats│ │
-│  │  webhook.sms | health.ping                                  │ │
-│  └─────────────────────────────────────────────────────────────┘ │
-│                                                                   │
-│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────────┐ │
-│  │ AgentRegistry│  │ SessionStore │  │ MessageLog (Postgres)    │ │
-│  │ (in-memory)  │  │ (JSON file)  │  │ (bridge_messages table)  │ │
-│  │ busy/idle    │  │ externalKey  │  │ from/to/prompt/response  │ │
-│  │ mutex/agent  │  │ → sessionId  │  │ status: pending→done     │ │
-│  └──────────────┘  └──────────────┘  └──────────────────────────┘ │
-│                                                                   │
-│  ┌─────────────────────────────────────────────────────────────┐ │
-│  │ OverBridgeService (SDK wrapper)                             │ │
-│  │ → BridgeProxy → HTTP POST http://[::1]:3099/mcp             │ │
-│  │ → Overmind MCP Server → HermesGatewayRunner → Gateway :8642 │ │
-│  └─────────────────────────────────────────────────────────────┘ │
-└──────────────────────────────────────────────────────────────────┘
-```
-
----
+| Bridge # | Port | Agent | Runner | Script |
+|----------|------|-------|--------|--------|
+| #1 | **:3101** | `nexus_master` | hermes | `start-bridge-master.ps1` |
+| #2 | **:3102** | `nexus_trader` | hermes | `start-bridge-trader.ps1` |
+| #3 | **:3103** | `nexus_risk_manager` | hermes | `start-bridge-risk.ps1` |
+| #4 | **:3104** | `nexus_healer` | hermes | `start-bridge-healer.ps1` |
+| #5 | **:3105** | `nexus_researcher` | hermes | `start-bridge-researcher.ps1` |
+| #6 | **:3106** | `nexus_publisher` | hermes | `start-bridge-publisher.ps1` |
 
-## Les 3 Couches de Persistance
+## Services PARTAGÉS (single instance, utilisés par les 6 bridges)
 
-| Couche | Stockage | TTL | Rôle |
-|--------|----------|-----|------|
-| **AgentRegistry** | In-memory (Map) | Session live | Mutex par agent (1 run à la fois), statut busy/idle/online |
-| **SessionStore** | JSON file (`~/.overmind/bridge/sessions.json`) | 4h | Map `externalKey` → `sessionId` (multi-tenant: 1 session par utilisateur Discord) |
-| **MessageLog** | PostgreSQL (`bridge_messages` table) | Permanent | Historique complet: from, to, prompt, response, status, timestamps |
+| Service | Port | Pourquoi single |
+|---------|------|------------------|
+| **Overmind MCP Server** | :3099 | Routing centralisé — tous les bridges passent par lui pour `run_agent` |
+| **Hermes Gateway API** | :8642 | `X-Hermes-Profile` header route vers le bon profil — 1 process Python = 6 profils |
+| **PostgreSQL** | :5432 | `MessageLog` partagé — tous les bridges écrivent leurs A2A messages dans la même table `bridge_messages` |
 
 ---
 
-## AgentRegistry — État Live en Mémoire
-
-**Source**: `src/bridge/AgentRegistry.ts`
-
-Tracke l'état live de chaque agent avec un **mutex par agent** pour sérialiser les appels concurrents :
+## Topologie Réseau
+
+```
+┌────────────────────────────────────────────────────────────────────────┐
+│                   6 BRIDGES ISOLÉS — P2P                                │
+│                                                                        │
+│  ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐    │
+│  │ :3101           │    │ :3102           │    │ :3103           │    │
+│  │ nexus_master    │◄──►│ nexus_trader    │◄──►│ nexus_risk_mgr  │    │
+│  │ bridge.ts       │    │ bridge.ts       │    │ bridge.ts       │    │
+│  └────────┬────────┘    └────────┬────────┘    └────────┬────────┘    │
+│           │ HTTP A2A            │ HTTP A2A            │ HTTP A2A      │
+│           │                     │                     │               │
+│  ┌────────▼────────┐    ┌───────▼─────────┐    ┌──────▼──────────┐    │
+│  │ :3104           │    │ :3105           │    │ :3106           │    │
+│  │ nexus_healer    │◄──►│ nexus_researcher│◄──►│ nexus_publisher │    │
+│  │ bridge.ts       │    │ bridge.ts       │    │ bridge.ts       │    │
+│  └─────────────────┘    └─────────────────┘    └─────────────────┘    │
+│                                                                        │
+│           │                     │                     │               │
+│           └─────────────────────┼─────────────────────┘               │
+│                                 │                                      │
+│                                 ▼                                      │
+│           ┌──────────────────────────────────────┐                   │
+│           │  SERVICES PARTAGÉS (single)           │                   │
+│           │  • :3099  Overmind MCP Server         │                   │
+│           │  • :8642  Hermes Gateway API          │                   │
+│           │  • :5432  PostgreSQL (MessageLog)     │                   │
+│           └──────────────────────────────────────┘                   │
+└────────────────────────────────────────────────────────────────────────┘
+```
+
+### Pattern de Communication
+
+Quand `nexus_master` veut demander à `nexus_trader` d'exécuter un trade :
 
 ```typescript
-interface AgentLiveState {
-  name: string;
-  runner: RunnerType;
-  status: 'online' | 'offline' | 'busy' | 'idle';
-  pid?: number;
-  currentSessionId?: string;      // Session en cours (si busy)
-  lastActivityAt: number;
-  totalRuns: number;
-  totalErrors: number;
-  a2aReceived: number;             // Compteur A2A reçu
-  a2aSent: number;                 // Compteur A2A envoyé
-}
-```
-
-### Mutex — 1 Run à la Fois par Agent
-
-```typescript
-// Si agent "trader_btc" est déjà en train de tourner,
-// le 2e appel attend que le 1er termine.
-await this.registry.withLock('trader_btc', async () => {
-  this.registry.markBusy('trader_btc', sessionId);
-  const result = await this.service.runAgent({ ... });
-  this.registry.markIdle('trader_btc', !result.isError);
-  return result;
-});
-```
-
-### Méthodes Disponibles
-
-| Méthode | Description |
-|---------|-------------|
-| `register(name, runner)` | Enregistre l'agent dans le registry |
-| `markBusy(name, sessionId)` | Marque comme occupé (run en cours) |
-| `markIdle(name, success)` | Marque comme libre + incrémente compteurs |
-| `markOnline(name)` | Marque comme en ligne |
-| `markOffline(name)` | Marque comme hors ligne |
-| `get(name)` | Retourne l'état live complet |
-| `list({ status, runner })` | Liste filtrée des agents |
-| `stats()` | Stats globales (total, busy, idle, online) |
-| `incrementA2aSent(name)` | Incrémente le compteur A2A envoyé |
-| `incrementA2aReceived(name)` | Incrémente le compteur A2A reçu |
-| `prune(maxAgeMs)` | Nettoie les agents offline > 24h (auto toutes les 6h) |
-
----
-
-## SessionStore — Sessions Multi-Tenant
-
-**Source**: `src/bridge/SessionStore.ts`
-
-Le **multi-tenant** : chaque utilisateur externe a sa propre session persistante avec l'agent.
-
-### Comment ça Marche
-
-```
-Utilisateur Discord A (!sniper analyse BTC)
-  → externalKey = "discord_user_123"
-  → SessionStore.get("discord_user_123", "sniperbot_analyst")
-  → sessionId = "abc-123"  (session restaurée!)
-  → runAgent avec sessionId="abc-123"
-  → SessionStore.set("discord_user_123", "sniperbot_analyst", "abc-123")
-
-Utilisateur Discord B (!sniper analyse ETH)
-  → externalKey = "discord_user_456"
-  → SessionStore.get("discord_user_456", "sniperbot_analyst")
-  → pas de session → nouvelle session
-  → sessionId = "def-456"
-```
-
-### Persistence
-
-```json
-// ~/.overmind/bridge/sessions.json
-{
-  "discord_user_123:sniperbot_analyst": {
-    "externalKey": "discord_user_123",
-    "agentName": "sniperbot_analyst",
-    "runner": "hermes",
-    "sessionId": "abc-123",
-    "context": { "lastTopic": "BTC", "language": "fr" },
-    "createdAt": "2026-07-09T18:00:00Z",
-    "updatedAt": "2026-07-09T18:05:00Z"
+// Dans bridges/nexus_master/src/clients/MasterToTrader.ts
+import { BridgeClient } from '@nexus/bridge-common';
+
+export class MasterToTrader {
+  private client = new BridgeClient('http://127.0.0.1:3102');
+
+  async requestTrade(symbol: string, action: 'buy' | 'sell', size: number) {
+    return this.client.call('agent.run', {
+      agentName: 'nexus_trader',
+      runner: 'hermes',
+      prompt: `Exécute trade: ${action} ${size} ${symbol}`,
+      externalKey: 'master_to_trader',
+    });
   }
 }
 ```
 
-### TTL et Cleanup
-
-- TTL par défaut: **4h** (`sessionTtlMs: 4 * 60 * 60 * 1000`)
-- Cleanup automatique toutes les **5min** (`cleanupIntervalMs`)
-- Sessions expirées → supprimées du fichier
-
-### Directives — L'Agent Peut Mettre à Jour Sa Session
-
-Quand `enableDirectives: true`, l'agent peut émettre des directives dans sa réponse :
-
-```
-SESSION_ID: new-session-xyz     → met à jour le sessionId
-CONTEXT_UPDATE: {"lastTopic": "ETH"}  → patch le contexte
-BRIDGE_HINT: "Analyse terminée"  → log seulement
-```
-
-Le `DirectiveParser` (`src/bridge/DirectiveParser.ts`) parse ces directives, les applique au SessionStore, et les retire du texte visible par l'utilisateur.
-
----
-
-## MessageLog — Persistence Postgres
-
-**Source**: `src/bridge/MessageLog.ts`
-
-Historique permanent de tous les messages A2A et agent.run dans PostgreSQL.
-
-### Schéma de Table
-
-```sql
-CREATE TABLE bridge_messages (
-  id          UUID PRIMARY KEY,
-  from_agent  VARCHAR(255),        -- NULL si client externe
-  to_agent    VARCHAR(255) NOT NULL,
-  runner      VARCHAR(50) NOT NULL,
-  prompt      TEXT NOT NULL,
-  response    TEXT,
-  session_id  VARCHAR(255),
-  status      VARCHAR(20) DEFAULT 'pending',  -- pending → running → done/failed/timeout
-  metadata    JSONB,
-  created_at  TIMESTAMPTZ DEFAULT NOW(),
-  updated_at  TIMESTAMPTZ DEFAULT NOW()
-);
-
-CREATE INDEX idx_bridge_messages_to_agent   ON bridge_messages(to_agent, created_at DESC);
-CREATE INDEX idx_bridge_messages_from_agent ON bridge_messages(from_agent, created_at DESC);
-CREATE INDEX idx_bridge_messages_status     ON bridge_messages(status);
-```
-
-### Cycle de Vie d'un Message
-
-```
-agent.run appelé
-  → messageLog.create()     → status: "pending"
-  → messageLog.markRunning() → status: "running"
-  → agent termine...
-     → succès: messageLog.markDone()    → status: "done", response sauvegardée
-     → erreur:  messageLog.markFailed()  → status: "failed", error sauvegardé
-     → timeout: messageLog.markTimeout() → status: "timeout"
-```
-
-### Replay
-
-```bash
-# Rejouer un message (re-run avec le même prompt)
-curl -X POST http://localhost:3100/rpc \
-  -d '{"jsonrpc":"2.0","id":1,"method":"message.replay","params":{"id":"7f3e8a1b-..."}}'
-```
+**Flow** :
+1. `nexus_master` (port 3101) reçoit une requête externe
+2. Il appelle `MasterToTrader.requestTrade()` 
+3. `BridgeClient` fait `POST http://127.0.0.1:3102/rpc`
+4. Le bridge `nexus_trader` (port 3102) reçoit, exécute via MCP
+5. Réponse remontée : `nexus_trader` → `nexus_master` → client externe
 
 ---
 
-## JSON-RPC 2.0 — Toutes les Méthodes
-
-### Endpoint
-
+## Arborescence des Bridges
+
+```
+C:\Users\Deamon\Nexus\
+│
+├── bridges/                            ← 6 WRAPPERS ISOLÉS (un par agent)
+│   │
+│   ├── nexus_master/                   ← Bridge #1 (:3101)
+│   │   ├── package.json                ← name: @nexus/bridge-master, dep: overmind-mcp
+│   │   ├── tsconfig.json
+│   │   ├── .env                        ← AGENT_NAME, BRIDGE_PORT=3101, peers URLs
+│   │   ├── README.md
+│   │   ├── src/
+│   │   │   ├── bridge.ts               ← Entry point — lance OverBridgeServer
+│   │   │   ├── config.ts               ← Lit .env + export config typée
+│   │   │   ├── logger.ts               ← Pino logger dédié
+│   │   │   ├── startup.ts              ← init MessageLog + SessionStore + connect MCP
+│   │   │   └── clients/
+│   │   │       ├── MasterToTrader.ts   ← POST :3102/rpc
+│   │   │       ├── MasterToRisk.ts     ← POST :3103/rpc
+│   │   │       ├── MasterToResearcher.ts ← POST :3105/rpc
+│   │   │       └── MasterToPublisher.ts  ← POST :3106/rpc
+│   │   ├── logs/
+│   │   │   └── bridge-master.log
+│   │   └── dist/                       ← Compilé
+│   │
+│   ├── nexus_trader/                   ← Bridge #2 (:3102)
+│   │   ├── package.json                ← name: @nexus/bridge-trader
+│   │   ├── .env                        ← BRIDGE_PORT=3102
+│   │   ├── src/
+│   │   │   ├── bridge.ts
+│   │   │   └── clients/
+│   │   │       ├── TraderToMaster.ts   ← POST :3101/rpc (comm au maître)
+│   │   │       ├── TraderToRisk.ts     ← POST :3103/rpc (check risk)
+│   │   │       └── TraderToPublisher.ts ← POST :3106/rpc (publier trade)
+│   │   └── ...
+│   │
+│   ├── nexus_risk_manager/             ← Bridge #3 (:3103)
+│   │   └── ...
+│   ├── nexus_healer/                   ← Bridge #4 (:3104)
+│   │   └── ...
+│   ├── nexus_researcher/               ← Bridge #5 (:3105)
+│   │   └── ...
+│   └── nexus_publisher/                ← Bridge #6 (:3106)
+│       └── ...
+│
+├── common/                             ← PARTAGÉ entre les 6 bridges
+│   ├── package.json                    ← name: @nexus/bridge-common
+│   ├── src/
+│   │   ├── BaseBridge.ts               ← Classe abstraite — factorise le boot
+│   │   ├── BridgeClient.ts             ← Client HTTP vers un autre bridge
+│   │   ├── types.ts                    ← Interfaces partagées
+│   │   └── logger.ts                   ← Pino config commune
+│   └── dist/
+│
+├── profiles/                           ← Profils Hermes (existants)
+│   ├── nexus_master/{config.yaml,SOUL.md,.env,memories/,sessions/}
+│   ├── nexus_trader/
+│   ├── nexus_risk_manager/
+│   ├── nexus_healer/
+│   ├── nexus_researcher/
+│   └── nexus_publisher/
+│
+├── shared-infra/                       ← SERVICES PARTAGÉS (déjà en prod)
+│   ├── mcp-server/                     ← Overmind MCP :3099
+│   ├── hermes-gateway/                 ← Gateway :8642
+│   └── postgres/                       ← :5432
+│
+├── scripts/                            ← SCRIPTS DE GESTION
+│   ├── start-all-bridges.ps1           ← Démarre les 6 en parallèle (Start-Job)
+│   ├── stop-all-bridges.ps1
+│   ├── status-bridges.ps1
+│   ├── seed-bridges.ps1                ← Crée dossiers + .env pour les 6
+│   └── test-a2a-network.ps1            ← Test E2E inter-bridges
+│
+└── logs/
+    ├── bridges/
+    │   ├── nexus_master.log
+    │   ├── nexus_trader.log
+    │   ├── nexus_risk_manager.log
+    │   ├── nexus_healer.log
+    │   ├── nexus_researcher.log
+    │   └── nexus_publisher.log
+    └── network/
+        └── a2a-traffic.log
 ```
-POST /rpc
-Content-Type: application/json
-Authorization: Bearer <token>   (optionnel si authToken configuré)
-
-# Single request
-{"jsonrpc":"2.0","id":1,"method":"agent.run","params":{...}}
-
-# Batch (parallèle)
-[
-  {"jsonrpc":"2.0","id":1,"method":"agent.run","params":{...}},
-  {"jsonrpc":"2.0","id":2,"method":"agent.list","params":{}}
-]
-```
-
-### Méthodes Disponibles (24 méthodes)
-
-#### Agents (10 méthodes)
-
-| Méthode | Params Requis | Params Optionnels | Description |
-|---------|---------------|-------------------|-------------|
-| `agent.run` | `agentName`, `runner`, `prompt` | `sessionId`, `path`, `model`, `mode`, `silent`, `externalKey`, `parseDirectives`, `metadata` | Lance un agent |
-| `agent.a2a` | `fromAgent`, `toAgent`, `runner`, `prompt` | `model`, `path`, `metadata` | Agent A parle à Agent B |
-| `agent.broadcast` | `fromAgent`, `runner`, `prompt` | `targets[]`, `race`, `agentTimeoutMs`, `model` | Fan-out global |
-| `agent.pipeline` | `initiator`, `runner`, `prompt`, `steps[]` | `accumulateContext`, `totalTimeoutMs` | Chaîne A→B→C |
-| `agent.fanout` | `fromAgent`, `runner`, `prompt`, `targets[]` | `mergeStrategy`, `agentTimeoutMs`, `model` | 1→N + merge |
-| `agent.delegate` | `fromAgent`, `toAgent`, `runner`, `prompt` | `async`, `callbackUrl`, `model` | Fire-and-forget |
-| `agent.query` | `fromAgent`, `runner`, `prompt`, `targets[]` | `agentTimeoutMs`, `model` | Query multi-agents |
-| `agent.status` | `agentName` | `runner`, `action`, `sinceTimestamp`, `timeoutMs` | Status live |
-| `agent.list` | — | `status`, `runner` | Liste des agents |
-| `agent.kill` | `agentName` | `runner` | Kill un agent |
-
-#### Messages (4 méthodes)
-
-| Méthode | Params | Description |
-|---------|--------|-------------|
-| `message.history` | `toAgent?`, `fromAgent?`, `status?`, `limit?`, `offset?`, `sinceHours?` | Historique paginé |
-| `message.get` | `id` (UUID) | Récupère un message |
-| `message.replay` | `id` (UUID) | Rejoue un message |
-| `message.stats` | — | Stats globales |
-
-#### Sessions (4 méthodes)
-
-| Méthode | Params | Description |
-|---------|--------|-------------|
-| `session.get` | `externalKey`, `agentName` | Session d'un utilisateur |
-| `session.list` | — | Toutes les sessions |
-| `session.delete` | `externalKey`, `agentName` | Supprime une session |
-| `session.stats` | — | Stats des sessions |
-
-#### Autres (6 méthodes)
-
-| Méthode | Description |
-|---------|-------------|
-| `health.ping` | Liveness check |
-| `webhook.sms` | Adapt + auto-dispatch webhook SMS |
-| `GET /health` | Healthcheck enrichi (hors RPC) |
-| `POST /webhook/:provider` | Webhook HTTP (voipms, twilio, discord) |
-| `GET /f/:filename` | Static file serve |
-| `OPTIONS *` | CORS preflight |
 
 ---
 
-## A2A — Agent-to-Agent
-
-### Principe
+## Fichiers Clés
 
-Agent A envoie un message à Agent B. Le bridge :
-1. Enrichit le prompt avec un header A2A standardisé
-2. Persiste le message dans MessageLog (from=A, to=B)
-3. Incrémente les compteurs A2A (sent pour A, received pour B)
-4. Exécute B sous mutex (sérialise les appels concurrents vers B)
-5. Retourne la réponse de B à A
-
-### Format du Prompt A2A
-
-```
-[A2A — Agent-to-Agent Message]
-FROM: trader_btc
-TO: analyst_eth
-TIMESTAMP: 2026-07-09T18:30:00.000Z
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Valide mon analyse : le BTC va casser les 100k dans 48h
-```
-
-### Exemple curl
+### 1. `bridges/nexus_master/.env`
 
 ```bash
-curl -X POST http://localhost:3100/rpc \
-  -H "Content-Type: application/json" \
-  -d '{
-    "jsonrpc": "2.0",
-    "id": 1,
-    "method": "agent.a2a",
-    "params": {
-      "fromAgent": "trader_btc",
-      "toAgent": "analyst_eth",
-      "runner": "hermes",
-      "prompt": "Valide mon analyse : le BTC va casser les 100k dans 48h"
-    }
-  }'
-```
+# === Bridge :3101 — nexus_master ===
+AGENT_NAME=nexus_master
+RUNNER=hermes
+BRIDGE_PORT=3101
+BRIDGE_HOST=127.0.0.1
+
+# Upstream (services partagés)
+MCP_URL=http://[::1]:3099/mcp
+HERMES_GATEWAY_URL=http://127.0.0.1:8642
+HERMES_GATEWAY_KEY=hIhOKpVn3AgfW_sQO8XShjMb8YRhaZngSSv6UsWY0dc
+POSTGRES_HOST=localhost
+POSTGRES_DB=overmind
+POSTGRES_USER=overmind
+POSTGRES_PASSWORD=***
+
+# Peers (autres bridges)
+PEER_TRADER_URL=http://127.0.0.1:3102
+PEER_RISK_URL=http://127.0.0.1:3103
+PEER_HEALER_URL=http://127.0.0.1:3104
+PEER_RESEARCHER_URL=http://127.0.0.1:3105
+PEER_PUBLISHER_URL=http://127.0.0.1:3106
+
+# Session config
+SESSION_TTL_MS=14400000
+MESSAGE_LOG_ENABLED=true
+DIRECTIVES_ENABLED=true
+```
+
+### 2. `common/src/BaseBridge.ts` (partagé)
 
-### Réponse
-
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 1,
-  "result": {
-    "messageId": "7f3e8a1b-...",
-    "from": "trader_btc",
-    "to": "analyst_eth",
-    "sessionId": "api-abc123",
-    "content": [{ "type": "text", "text": "Je valide avec conviction 75..." }],
-    "isError": false
-  }
+```typescript
+import {
+  OverBridgeServer,
+  OverBridgeService,
+  loadMessageLogConfigFromEnv,
+  createBridgeLogger,
+} from 'overmind-mcp/bridge';
+import { BridgeClient } from './BridgeClient.js';
+
+export interface BaseBridgeConfig {
+  agentName: string;
+  port: number;
+  host: string;
+  mcpUrl: string;
+  logger: any;
 }
-```
-
----
-
-## A2A Extended — Broadcast, Pipeline, Fanout, Delegate, Query
-
-### 1. Broadcast — 1 → Tous (Fan-out Global)
-
-Un agent envoie un message à tous les agents online (ou à une liste cible).
-
-```bash
-curl -X POST http://localhost:3100/rpc \
-  -d '{
-    "jsonrpc": "2.0", "id": 1,
-    "method": "agent.broadcast",
-    "params": {
-      "fromAgent": "commander",
-      "runner": "hermes",
-      "prompt": "Alerte marché : BTC drop 5%",
-      "race": false,
-      "agentTimeoutMs": 60000
-    }
-  }'
-```
-
-- `race: true` → retourne dès qu'un agent répond (premier qui gagne)
-- `race: false` → attend tous les agents
-- Si `targets` absent → tous les agents `online` (excluant l'émetteur)
-
-### 2. Pipeline — Chaîne Séquentielle A→B→C
-
-L'output de chaque step devient l'input du suivant.
-
-```bash
-curl -X POST http://localhost:3100/rpc \
-  -d '{
-    "jsonrpc": "2.0", "id": 1,
-    "method": "agent.pipeline",
-    "params": {
-      "initiator": "commander",
-      "runner": "hermes",
-      "prompt": "Analyse le marché BTC actuel",
-      "steps": [
-        { "agentName": "data_collector", "promptPrefix": "Récupère les données:" },
-        { "agentName": "analyst", "promptPrefix": "Analyse ces données:" },
-        { "agentName": "strategist", "promptPrefix": "Propose une stratégie:" }
-      ],
-      "accumulateContext": true,
-      "totalTimeoutMs": 3600000
-    }
-  }'
-```
-
-- `accumulateContext: true` → chaque step reçoit TOUS les outputs précédents
-- `accumulateContext: false` → chaque step ne reçoit que le dernier output
-- Timeout global avec deadline check à chaque step
-
-### 3. Fanout — 1 → N Parallèle + Merge
 
-Un agent demande à plusieurs agents en parallèle, puis merge les résultats.
-
-```bash
-curl -X POST http://localhost:3100/rpc \
-  -d '{
-    "jsonrpc": "2.0", "id": 1,
-    "method": "agent.fanout",
-    "params": {
-      "fromAgent": "commander",
-      "runner": "hermes",
-      "prompt": "Quelle stratégie pour le BTC?",
-      "targets": ["analyst_1", "analyst_2", "analyst_3"],
-      "mergeStrategy": "best"
-    }
-  }'
-```
-
-Stratégies de merge :
-
-| Stratégie | Description |
-|-----------|-------------|
-| `concat` | Concatène toutes les réponses (défaut) |
-| `best` | Sélectionne la plus longue réponse |
-| `vote` | Vote par bucket de taille (100 chars) |
-| `first_success` | Premier qui réussit |
-
-### 4. Delegate — Fire-and-Forget Async
-
-Délègue une tâche à un agent de façon asynchrone. Retourne immédiatement avec un `taskId`.
-
-```bash
-curl -X POST http://localhost:3100/rpc \
-  -d '{
-    "jsonrpc": "2.0", "id": 1,
-    "method": "agent.delegate",
-    "params": {
-      "fromAgent": "commander",
-      "toAgent": "researcher",
-      "runner": "hermes",
-      "prompt": "Recherche l'historique des crashes BTC 2024",
-      "async": true,
-      "callbackUrl": "https://myapp.com/webhook/agent-done"
-    }
-  }'
-```
-
-- `async: true` → retourne immédiatement avec `taskId`
-- `callbackUrl` → POST le résultat quand l'agent termine
-- L'agent peut être suivi via `agent.status(agentName: "researcher")`
-
-### 5. Query — Multi-Agent Read-Only
+export abstract class BaseBridge {
+  protected service: OverBridgeService;
+  protected server: OverBridgeServer;
+
+  constructor(protected config: BaseBridgeConfig) {
+    this.service = new OverBridgeService({
+      mcpUrl: config.mcpUrl,
+      defaultTimeoutMs: 60_000,
+      agentTimeoutMs: 2_700_000,
+      maxRetries: 2,
+    }, config.logger);
+
+    this.server = new OverBridgeServer(this.service, {
+      port: config.port,
+      host: config.host,
+      postgres: loadMessageLogConfigFromEnv(),
+      enableMessageLog: true,
+      enableSessionStore: true,
+      enableDirectives: true,
+      sessionTtlMs: 4 * 60 * 60 * 1000,
+      rateLimitMax: 200,
+      sanitizeJson: true,
+    }, config.logger);
+  }
 
-Comme fanout mais optimisé pour des réponses courtes et rapides.
+  abstract getClients(): BridgeClient[];
 
-```bash
-curl -X POST http://localhost:3100/rpc \
-  -d '{
-    "jsonrpc": "2.0", "id": 1,
-    "method": "agent.query",
-    "params": {
-      "fromAgent": "commander",
-      "runner": "hermes",
-      "prompt": "Prix actuel du BTC?",
-      "targets": ["price_bot_1", "price_bot_2"],
-      "agentTimeoutMs": 30000
+  async start(): Promise<void> {
+    await this.server.start();
+    this.config.logger.info(`🚀 Bridge ${this.config.agentName} ready on :${this.config.port}`);
+    for (const client of this.getClients()) {
+      await client.healthCheck();
     }
-  }'
-```
-
----
-
-## Comment Construire un Agent Persistant (comme discord_llm)
-
-`discord_llm` est l'exemple canonique d'un client persistant du bridge. Voici le pattern complet :
-
-### Architecture discord_llm
+  }
 
-```
-┌─────────────────────────────────────────────────────────┐
-│  discord_llm/ (package: discord-claude-bridge v3.5.0)   │
-│                                                          │
-│  startpipeline.ts  → PipelineManager                     │
-│    ├── spawn overmind-bridge.ts (Express :3001)          │
-│    │   ├── OverBridgeService (SDK wrapper)               │
-│    │   ├── BridgeProxy → HTTP [::1]:3099/mcp             │
-│    │   ├── SessionStore (multi-tenant, JSON file)        │
-│    │   └── WebhookAdapter (voipms, twilio, discord)      │
-│    │                                                      │
-│    └── spawn discord-bot.ts (Discord.js)                 │
-│        ├── reçoit !sniper <message>                      │
-│        └── POST localhost:3001/send                      │
-│             → OverBridgeService.runAgentForDiscord()     │
-│             → BridgeProxy → MCP :3099                    │
-│             → HermesGatewayRunner → Gateway :8642        │
-│             → réponse → Discord                          │
-└─────────────────────────────────────────────────────────┘
+  async stop(): Promise<void> {
+    await this.server.stop();
+  }
+}
 ```
 
-### Étape 1 : Importer le SDK Overmind
+### 3. `bridges/nexus_master/src/bridge.ts`
 
 ```typescript
-// Import depuis overmind-mcp (package npm ou file:../Workflow)
-import {
-  OverBridgeService,    // SDK haut niveau (runAgent, sessions, heartbeat)
-  SessionStore,         // Multi-tenant (externalKey → sessionId)
-  WebhookAdapter,       // Adaptation webhooks (SMS, Discord, Twilio)
-  BridgeProxy,          // Low-level MCP transport (HTTP JSON-RPC)
-} from 'overmind-mcp/bridge';
+import { BaseBridge } from '@nexus/bridge-common';
+import { config } from './config.js';
+import { MasterToTrader } from './clients/MasterToTrader.js';
+import { MasterToRisk } from './clients/MasterToRisk.js';
+import { MasterToResearcher } from './clients/MasterToResearcher.js';
+import { MasterToPublisher } from './clients/MasterToPublisher.js';
+import { logger } from './logger.js';
+
+class MasterBridge extends BaseBridge {
+  protected getClients() {
+    return [
+      new MasterToTrader(config.peerTraderUrl, logger),
+      new MasterToRisk(config.peerRiskUrl, logger),
+      new MasterToResearcher(config.peerResearcherUrl, logger),
+      new MasterToPublisher(config.peerPublisherUrl, logger),
+    ];
+  }
+}
+
+const bridge = new MasterBridge();
+await bridge.start();
 ```
 
-### Étape 2 : Configurer le Bridge
+### 4. `bridges/nexus_master/src/clients/MasterToTrader.ts`
 
 ```typescript
-const OVERMIND_MCP_URL = process.env.OVERMIND_MCP_URL || 'http://localhost:3099/mcp';
-const AGENT_NAME = process.env.BRIDGE_AGENT || 'sniperbot_analyst';
-const RUNNER = 'hermes';
-
-// Low-level proxy → parle au MCP server
-const proxy = new BridgeProxy({
-  mcpUrl: OVERMIND_MCP_URL,
-  defaultTimeoutMs: 60_000,
-  agentTimeoutMs: 2_700_000,  // 45 min
-  maxRetries: 2,
-  retryDelayMs: 2_000,
-}, undefined, logger);
-
-// High-level service → session continuity + retry + circuit breaker
-const service = new OverBridgeService({
-  mcpUrl: OVERMIND_MCP_URL,
-  defaultTimeoutMs: 60_000,
-  agentTimeoutMs: 2_700_000,
-  maxRetries: 2,
-  retryDelayMs: 2_000,
-}, logger);
-
-// Multi-tenant sessions
-const sessionStore = new SessionStore({
-  persistPath: '~/.overmind/bridge/sessions.json',
-  ttlMs: 4 * 60 * 60 * 1000,        // 4h
-  cleanupIntervalMs: 5 * 60 * 1000,  // 5min
-}, logger);
-
-await sessionStore.init();
-```
+import { BridgeClient } from '@nexus/bridge-common';
 
-### Étape 3 : Exposer les Endpoints HTTP
+export class MasterToTrader {
+  private client: BridgeClient;
 
-```typescript
-import express from 'express';
-const app = express();
-app.use(express.json({ limit: '10mb' }));
-
-// ─── Route legacy (Discord bot) ─────────────────────────
-app.post('/send', async (req, res) => {
-  const { message, userId, username, channelId } = req.body;
-
-  // Lance l'agent avec contexte Discord
-  const result = await service.runAgentForDiscord(
-    AGENT_NAME, RUNNER, message,
-    { channelId, userId, username }
-  );
-
-  if (result.isError) {
-    return res.status(500).json({ error: result.content.map(c => c.text).join('\n') });
+  constructor(traderUrl: string, logger: any) {
+    this.client = new BridgeClient(traderUrl, logger);
   }
 
-  res.json({
-    result: result.content.map(c => c.text).join('\n'),
-    session_id: result.sessionId || service.sessionId,
-  });
-});
-
-// ─── JSON-RPC 2.0 endpoint ──────────────────────────────
-app.post('/rpc', async (req, res) => {
-  const { method, params, id } = req.body;
-
-  switch (method) {
-    case 'agent.run':
-      // Résolution sessionId via SessionStore
-      let sessionId = params.sessionId;
-      if (!sessionId && params.externalKey) {
-        const stored = sessionStore.get(params.externalKey, params.agentName);
-        if (stored) sessionId = stored.sessionId;
-      }
-
-      const result = await service.runAgent({
-        agentName: params.agentName,
-        runner: params.runner,
-        prompt: params.prompt,
-        sessionId,
-        model: params.model,
-      });
-
-      // Sauvegarde sessionId pour cet utilisateur
-      if (params.externalKey && result.sessionId) {
-        sessionStore.set({
-          externalKey: params.externalKey,
-          agentName: params.agentName,
-          runner: params.runner,
-          sessionId: result.sessionId,
-        });
-      }
-
-      return res.json({ jsonrpc: '2.0', id, result: {
-        sessionId: result.sessionId,
-        content: result.content,
-        isError: result.isError,
-      }});
-
-    case 'agent.a2a':
-      const enrichedPrompt = [
-        `[A2A — Agent-to-Agent Message]`,
-        `FROM: ${params.fromAgent}`,
-        `TO: ${params.toAgent}`,
-        `TIMESTAMP: ${new Date().toISOString()}`,
-        `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`,
-        params.prompt,
-      ].join('\n');
-
-      const a2aResult = await service.runAgent({
-        agentName: params.toAgent,
-        runner: params.runner,
-        prompt: enrichedPrompt,
-        model: params.model,
-      });
-
-      return res.json({ jsonrpc: '2.0', id, result: {
-        from: params.fromAgent,
-        to: params.toAgent,
-        sessionId: a2aResult.sessionId,
-        content: a2aResult.content,
-        isError: a2aResult.isError,
-      }});
-
-    case 'agent.list':
-      const agents = await proxy.call('list_agents', { details: params.details });
-      return res.json({ jsonrpc: '2.0', id, result: agents.result });
-
-    case 'session.get':
-      return res.json({ jsonrpc: '2.0', id, result: {
-        session: sessionStore.get(params.externalKey, params.agentName) ?? null,
-      }});
-
-    case 'session.list':
-      return res.json({ jsonrpc: '2.0', id, result: {
-        sessions: sessionStore.list(),
-        stats: sessionStore.stats(),
-      }});
-
-    case 'health.ping':
-      return res.json({ jsonrpc: '2.0', id, result: { pong: true, ts: Date.now() }});
+  async requestTrade(symbol: string, action: 'buy' | 'sell', size: number): Promise<any> {
+    return this.client.call('agent.run', {
+      agentName: 'nexus_trader',
+      runner: 'hermes',
+      prompt: `Exécute trade: ${action} ${size} ${symbol}`,
+      externalKey: 'master_to_trader',
+    });
   }
-});
-
-// ─── Health ─────────────────────────────────────────────
-app.get('/health', async (_req, res) => {
-  let mcpStatus = 'unknown';
-  try {
-    const health = await proxy.healthCheck();
-    mcpStatus = health.status;
-  } catch { mcpStatus = 'offline'; }
-  res.json({
-    status: 'ok',
-    version: '5.1.0',
-    mcp: { url: OVERMIND_MCP_URL, status: mcpStatus },
-    sessions: sessionStore.stats(),
-  });
-});
-
-app.listen(3001, () => logger.info('Bridge on :3001'));
-```
-
-### Étape 4 : Démarrer le Pipeline
-
-```typescript
-// startpipeline.ts — orchestre bridge + bot
-class PipelineManager {
-  async start() {
-    // 1. Démarrer le bridge (HTTP server)
-    this.bridgeProcess = spawn('node', ['dist/overmind-bridge.js']);
-
-    // 2. Attendre qu'il soit prêt
-    await this.waitForBridge();  // GET /health jusqu'à 200
 
-    // 3. Démarrer le bot Discord
-    this.discordProcess = spawn('node', ['dist/discord-bot.js']);
-
-    // 4. Auto-restart du bot si crash (max 3 tentatives)
-    this.discordProcess.on('exit', (code) => {
-      if (!this.isShuttingDown) this.restartDiscordBot();
+  async askAnalysis(marketData: any): Promise<any> {
+    return this.client.call('agent.run', {
+      agentName: 'nexus_trader',
+      runner: 'hermes',
+      prompt: `Analyse ces données: ${JSON.stringify(marketData)}`,
     });
   }
 }
 ```
 
-### Étape 5 : Configurer le .env
-
-```bash
-# discord_llm/.env
-CLAUDE_SERVER_PORT=3001                        # Port du bridge
-RUNNER=hermes                                  # Runner Overmind
-BRIDGE_AGENT=sniperbot_analyst                 # Agent par défaut
-OVERMIND_MCP_URL=http://[::1]:3099/mcp         # MCP server
-DISCORD_BOT_TOKEN=***                          # Token Discord
-BOT_PREFIX=!sniper                             # Préfixe commandes
-```
-
 ---
 
-## CLI overmind-bridge
-
-Le CLI `overmind-bridge` (`src/bin/overmind-bridge.ts`) permet de piloter le bridge sans écrire de code.
-
-### Démarrer le serveur
-
-```bash
-overmind-bridge server --port 3100
-```
-
-### Appels one-shot (8 sources de prompt)
-
-```bash
-# 1. Flag direct
-overmind-bridge call agent.run --agent scout --runner hermes --prompt "Analyse BTC"
-
-# 2. Stdin
-echo "Analyse BTC" | overmind-bridge call agent.run --agent scout --runner hermes --prompt-stdin
-
-# 3. Fichier
-overmind-bridge call agent.run --agent scout --runner hermes --prompt-file ./brief.txt
-
-# 4. Fichier + variables
-overmind-bridge call agent.run --agent scout --runner hermes \
-  --prompt-file ./brief.txt --var ticker=BTC --var timeframe=4h
-
-# 5-8. env-var, scenario, pipe, multi-file (voir --help)
-```
-
-### A2A via CLI
-
-```bash
-overmind-bridge call agent.a2a \
-  --from scout --to analyst --runner hermes \
-  --prompt "Valide mon analyse"
-```
-
-### Scénarios multi-agents
-
-```bash
-# JSON scenario file
-overmind-bridge scenario ./workflow.json --var ticker=BTC
-```
-
-### Status et Health
-
-```bash
-# Status de tous les agents
-overmind-bridge status
-
-# Health du serveur
-overmind-bridge health
-
-# Replay un message
-overmind-bridge replay --id 7f3e8a1b-...
+## Scripts de Gestion
+
+### `scripts/start-all-bridges.ps1`
+
+```powershell
+# Démarre les 6 bridges en parallèle
+$bridges = @(
+    @{ Name="master"; Port=3101 },
+    @{ Name="trader"; Port=3102 },
+    @{ Name="risk_manager"; Port=3103 },
+    @{ Name="healer"; Port=3104 },
+    @{ Name="researcher"; Port=3105 },
+    @{ Name="publisher"; Port=3106 }
+)
+
+$jobs = @()
+foreach ($b in $bridges) {
+    $script = "cd '$PSScriptRoot\..\bridges\nexus_$($b.Name)' ; node dist/bridge.js"
+    $jobs += Start-Job -ScriptBlock { Invoke-Expression $args[0] } -ArgumentList $script
+    Write-Host "✅ Started nexus_$($b.Name) on :$($b.Port)"
+}
 
-# Sessions
-overmind-bridge sessions list
-overmind-bridge sessions get --key "+141****7735" --agent pdf_bon_travail
-overmind-bridge sessions rm --key "+141****7735" --agent pdf_bon_travail
+Write-Host "`n6 bridges running. Press Ctrl+C to stop."
+Wait-Job -Job $jobs
+```
+
+### `scripts/seed-bridges.ps1`
+
+```powershell
+# Crée la structure de dossiers + .env pour les 6 bridges
+$template = @'
+AGENT_NAME={AGENT}
+RUNNER=hermes
+BRIDGE_PORT={PORT}
+BRIDGE_HOST=127.0.0.1
+MCP_URL=http://[::1]:3099/mcp
+HERMES_GATEWAY_URL=http://127.0.0.1:8642
+HERMES_GATEWAY_KEY=<KEY>
+PEER_TRADER_URL=http://127.0.0.1:3102
+PEER_RISK_URL=http://127.0.0.1:3103
+PEER_HEALER_URL=http://127.0.0.1:3104
+PEER_RESEARCHER_URL=http://127.0.0.1:3105
+PEER_PUBLISHER_URL=http://127.0.0.1:3106
+'@
+
+$config = @(
+    @{ Name="master"; Port=3101 },
+    @{ Name="trader"; Port=3102 },
+    @{ Name="risk_manager"; Port=3103 },
+    @{ Name="healer"; Port=3104 },
+    @{ Name="researcher"; Port=3105 },
+    @{ Name="publisher"; Port=3106 }
+)
+
+foreach ($c in $config) {
+    $dir = "$PSScriptRoot\..\bridges\nexus_$($c.Name)"
+    New-Item -ItemType Directory -Force -Path "$dir/src/clients"
+    New-Item -ItemType Directory -Force -Path "$dir/logs"
+    $env = $template -replace '{AGENT}', "nexus_$($c.Name)" -replace '{PORT}', $c.Port
+    Set-Content -Path "$dir/.env" -Value $env
+    Write-Host "✅ Seeded nexus_$($c.Name) on :$($c.Port)"
+}
 ```
 
 ---
 
-## Démarrer le Serveur Bridge
-
-### Option A : OverBridgeServer natif (port 3100)
-
-```typescript
-import { OverBridgeServer, OverBridgeService, loadMessageLogConfigFromEnv } from 'overmind-mcp/bridge';
-
-const service = new OverBridgeService({
-  mcpUrl: 'http://[::1]:3099/mcp',
-  defaultTimeoutMs: 60_000,
-  agentTimeoutMs: 2_700_000,
-}, logger);
-
-const server = new OverBridgeServer(service, {
-  port: 3100,
-  host: '127.0.0.1',
-  postgres: loadMessageLogConfigFromEnv(),
-  enableMessageLog: true,       // Persistence Postgres
-  enableSessionStore: true,     // Multi-tenant sessions
-  enableDirectives: true,       // SESSION_ID, CONTEXT_UPDATE directives
-  enableWebhooks: true,         // /webhook/:provider
-  sessionTtlMs: 4 * 60 * 60 * 1000,  // 4h
-  rateLimitMax: 100,            // 100 req/min par IP
-  allowedOrigins: ['*'],
-  sanitizeJson: true,           // Windows path repair
-});
-
-await server.start();
-// POST http://127.0.0.1:3100/rpc  (JSON-RPC 2.0)
-// GET  http://127.0.0.1:3100/health
-// POST http://127.0.0.1:3100/webhook/:provider
-```
-
-### Option B : Bridge léger Express (comme discord_llm)
-
-Pour un client qui n'a pas besoin de Postgres MessageLog mais veut les sessions multi-tenant :
-
-```typescript
-import express from 'express';
-import { OverBridgeService, SessionStore, BridgeProxy } from 'overmind-mcp/bridge';
-
-const app = express();
-app.use(express.json());
-
-const service = new OverBridgeService({ mcpUrl: 'http://[::1]:3099/mcp' });
-const sessions = new SessionStore({ persistPath: './sessions.json' });
-await sessions.init();
-
-// POST /send, POST /rpc, GET /health...
-app.listen(3001);
-```
-
-### Option C : CLI direct
-
-```bash
-# Démarrer le serveur OverBridgeServer complet
-overmind-bridge server --port 3100 --enable-message-log --enable-sessions --enable-webhooks
+## Avantages de cette Architecture
+
+| Bénéfice | Explication |
+|----------|-------------|
+| **Isolation** | Chaque agent = son process, son port, ses logs. Crash d'un agent ≠ crash des autres. |
+| **Scaling indépendant** | Tu peux redémarrer `nexus_trader` sans toucher aux autres. |
+| **Monitoring clair** | `GET :3101/health`, `GET :3102/health`, etc. — chaque agent a sa métrique. |
+| **Déploiement granulaire** | Tu peux déployer un agent sur une autre machine en gardant le même code. |
+| **Logs séparés** | `logs/bridges/nexus_master.log` — debugging facile par agent. |
+| **Config par agent** | `.env` dédié — clés API différentes si besoin. |
+| **Pas de SPOF** | Si le bridge master crash, les 5 autres continuent à fonctionner entre eux. |
+
+## Flow Complet — Exemple Concret
+
+```
+Discord !sniper trade BTC
+  ↓
+discord_llm bridge (:3001)
+  ↓ HTTP POST /send
+  ↓
+nexus_master bridge (:3101)
+  ↓ BridgeClient.call('agent.run', agentName='nexus_trader')
+  ↓ HTTP POST http://localhost:3102/rpc
+  ↓
+nexus_trader bridge (:3102)
+  ↓ service.runAgent() → BridgeProxy → HTTP POST :3099/mcp
+  ↓
+Overmind MCP Server (:3099)
+  ↓ runHermesAgent() → HermesGatewayRunner
+  ↓ HTTP POST :8642/v1/chat/completions + X-Hermes-Profile: nexus_trader
+  ↓
+Hermes Gateway (:8642)
+  ↓ Route vers profil nexus_trader
+  ↓ Response: "BUY 0.1 BTC @ 67500"
+  ↑ retour en sens inverse ↑
 ```
 
 ---
 
-## Configurations du OverBridgeServer
-
-| Config | Default | Description |
-|--------|---------|-------------|
-| `port` | 3100 | Port HTTP |
-| `host` | 127.0.0.1 | Host d'écoute |
-| `postgres` | — | Config Postgres pour MessageLog |
-| `enableMessageLog` | false | Persistence des messages en DB |
-| `enableSessionStore` | false | Sessions multi-tenant |
-| `enableDirectives` | false | Parse SESSION_ID, CONTEXT_UPDATE |
-| `enableWebhooks` | false | Auto-mount /webhook/:provider |
-| `authToken` | — | Bearer token auth |
-| `healthCheckIntervalMs` | 30000 | Heartbeat vers MCP |
-| `sessionTtlMs` | 14400000 (4h) | TTL sessions |
-| `sessionStorePath` | ~/.overmind/bridge/sessions.json | Fichier persistence |
-| `jsonBodyLimit` | 10mb | Limite body |
-| `sanitizeJson` | false | Repair JSON Windows paths |
-| `allowedOrigins` | localhost:3000,5173 | CORS |
-| `rateLimitMax` | 100 | Max req/min par IP |
+## Références
+
+- `overmind-mcp/bridge` exports : `OverBridgeServer`, `OverBridgeService`, `BridgeProxy`, `SessionStore`, `MessageLog`
+- Doc source : `Workflow/src/bridge/OverBridgeServer.ts` (1928 lignes)
+- Profils Hermes existants : `~/.hermes/profiles/nexus_*` (7 profils créés)
+- Gateway API : `Workflow/src/services/HermesGatewayRunner.ts` (HTTP+SSE, port 8642)