overmind-mcp 3.6.0 → 3.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/docs/overmind-bridge-guide.md +665 -0
  2. package/package.json +1 -1
  3. package/docs/agent-http-tutorial.md +0 -524
  4. package/docs/doc_guide_agent_hermes_permanent.md +0 -315
  5. package/docs/guide_agent_hermes_overmind.md +0 -403
  6. package/docs/overmind-bridge-commands-reference.md +0 -438
  7. package/docs/overmind-bridge-persistent-agents.md +0 -463
package/docs/overmind-bridge-commands-reference.md DELETED
@@ -1,438 +0,0 @@
1
- # 📋 Référence Complète — Commandes A2A & RPC Overmind Bridge
2
-
3
- > **Version**: Overmind v3.5.2 + NEXUS V17 (6 bridges isolés P2P)
4
- > **Date**: 2026-07-10
5
- > **Portée**: Code source Overmind + bridges NEXUS + discord_llm
6
-
7
- ---
8
-
9
- ## Table des Matières
10
-
11
- 1. [Architecture Corrigée](#architecture-corrigée)
12
- 2. [Services Partagés](#services-partagés)
13
- 3. [Commandes RPC par Bridge (NEXUS)](#commandes-rpc-par-bridge-nexus)
14
- 4. [Commandes RPC OverBridgeServer (Overmind)](#commandes-rpc-overbridgeserver-overmind)
15
- 5. [Commandes A2A Hub (MCP Tool)](#commandes-a2a-hub-mcp-tool)
16
- 6. [Commandes CLI overmind-bridge](#commandes-cli-overmind-bridge)
17
- 7. [Commandes Hermes Profile Management](#commandes-hermes-profile-management)
18
- 8. [Scripts Helper d'Installation](#scripts-helper-dinstallation)
19
- 9. [Bugs Source Corrigés](#bugs-source-corrigés)
20
-
21
- ---
22
-
23
- ## Architecture Corrigée
24
-
25
- ```
26
- ┌────────────────────────────────────────────────────────────────────┐
27
- │ 6 BRIDGES ISOLÉS — P2P │
28
- │ │
29
- │ :3101 nexus_master 4 RPC: status/broadcast/pipeline/fanout │
30
- │ :3102 nexus_trader 2 RPC: trade.request/trade.analysis │
31
- │ :3103 nexus_risk_manager 3 RPC: validate/drawdown/feedback │
32
- │ :3104 nexus_healer 3 RPC: fixed/failed/diagnose │
33
- │ :3105 nexus_researcher 2 RPC: query/summarize │
34
- │ :3106 nexus_publisher 3 RPC: trade-open/trade-close/signal │
35
- │ │
36
- │ TOTAL: 17 RPC methods │
37
- │ │
38
- │ A2A = HTTP POST inter-bridges (chaque bridge a ses propres clients)│
39
- │ │
40
- │ SERVICES PARTAGÉS: │
41
- │ :3099 Overmind MCP Server (routing central) │
42
- │ :8642 Hermes Gateway API (X-Hermes-Profile routing) │
43
- │ :5432 PostgreSQL (MessageLog + Memory) │
44
- └────────────────────────────────────────────────────────────────────┘
45
- ```
46
-
47
- ---
48
-
49
- ## Services Partagés
50
-
51
- | Service | Port | URL | Rôle |
52
- |---------|------|-----|------|
53
- | **Overmind MCP** | :3099 | `http://[::1]:3099/mcp` | 14 tools: run_agent, a2a_hub, agent_control, memory_*, create_agent, etc. |
54
- | **Hermes Gateway** | :8642 | `http://127.0.0.1:8642` | API Server HTTP+SSE (OpenAI-compatible) |
55
- | **PostgreSQL** | :5432 | `localhost` | MessageLog (bridge_messages) + Memory (pgvector) |
56
- | **Hyperliquid MCP** | :3150 | `http://localhost:3150` | Trading data (NEXUS-specific, roadmap) |
57
-
58
- ---
59
-
60
- ## Commandes RPC par Bridge (NEXUS)
61
-
62
- Chaque bridge expose `POST /rpc` (JSON-RPC 2.0) + `GET /health` + `POST /shutdown`.
63
-
64
- ### Format de Requête
65
-
66
- ```bash
67
- curl -X POST http://127.0.0.1:<PORT>/rpc \
68
- -H "Content-Type: application/json" \
69
- -d '{"jsonrpc":"2.0","id":"<id>","method":"<method>","params":{...}}'
70
- ```
71
-
72
- ### :3101 — nexus_master (Orchestrateur)
73
-
74
- | Méthode | Params | Description |
75
- |---------|--------|-------------|
76
- | `health.ping` | — | Ping local (toujours OK) |
77
- | `master.status` | — | Agrège la santé des 6 bridges en temps réel |
78
- | `master.broadcast` | `{ message: string }` | Fan-out un prompt aux 5 peer bridges |
79
- | `master.pipeline` | `{ steps: [{ peer, prompt }] }` | Chaîne séquentielle A→B→C entre bridges |
80
- | `master.fanout` | `{ peers: string[], prompt, merge? }` | Parallèle N bridges + merge (concat/best/first_success) |
81
-
82
- **Exemples:**
83
-
84
- ```bash
85
- # Status réseau complet
86
- curl -s -X POST http://127.0.0.1:3101/rpc \
87
- -H "Content-Type: application/json" \
88
- -d '{"jsonrpc":"2.0","id":"1","method":"master.status"}'
89
-
90
- # Broadcast à tous les peers
91
- curl -s -X POST http://127.0.0.1:3101/rpc \
92
- -H "Content-Type: application/json" \
93
- -d '{"jsonrpc":"2.0","id":"2","method":"master.broadcast","params":{"message":"Alerte marché"}}'
94
-
95
- # Pipeline: researcher → trader → publisher
96
- curl -s -X POST http://127.0.0.1:3101/rpc \
97
- -H "Content-Type: application/json" \
98
- -d '{"jsonrpc":"2.0","id":"3","method":"master.pipeline","params":{"steps":[{"peer":"researcher","prompt":"Analyse BTC"},{"peer":"trader","prompt":"Décide trade"},{"peer":"publisher","prompt":"Publie signal"}]}}'
99
-
100
- # Fanout parallèle + merge best
101
- curl -s -X POST http://127.0.0.1:3101/rpc \
102
- -H "Content-Type: application/json" \
103
- -d '{"jsonrpc":"2.0","id":"4","method":"master.fanout","params":{"peers":["researcher","trader"],"prompt":"BTC outlook","merge":"best"}}'
104
- ```
105
-
106
- ### :3102 — nexus_trader (Exécution + Analyse)
107
-
108
- | Méthode | Params | Description |
109
- |---------|--------|-------------|
110
- | `trade.request` | `{ symbol, side, quantity, entryPrice?, stopLoss?, takeProfit? }` | Valide via risk, notifie publisher |
111
- | `trade.analysis` | `{ symbol, timeframe? }` | Délègue au researcher |
112
-
113
- ```bash
114
- curl -s -X POST http://127.0.0.1:3102/rpc \
115
- -H "Content-Type: application/json" \
116
- -d '{"jsonrpc":"2.0","id":"1","method":"trade.request","params":{"symbol":"BTC","side":"BUY","quantity":0.1}}'
117
- ```
118
-
119
- ### :3103 — nexus_risk_manager (Validation + Drawdown)
120
-
121
- | Méthode | Params | Description |
122
- |---------|--------|-------------|
123
- | `risk.validate` | `{ symbol, side, quantity, entryPrice?, stopLoss?, takeProfit? }` | Valide un trade proposé |
124
- | `risk.drawdown` | — | Vérifie le drawdown actuel du portfolio |
125
- | `risk.feedback` | `{ message, type, suggestedParams? }` | Feedback au trader |
126
-
127
- ```bash
128
- curl -s -X POST http://127.0.0.1:3103/rpc \
129
- -H "Content-Type: application/json" \
130
- -d '{"jsonrpc":"2.0","id":"1","method":"risk.validate","params":{"symbol":"BTC","side":"BUY","quantity":0.1}}'
131
- ```
132
-
133
- ### :3104 — nexus_healer (Auto-réparation)
134
-
135
- | Méthode | Params | Description |
136
- |---------|--------|-------------|
137
- | `heal.fixed` | `{ module, resolution, durationMs? }` | Notifie qu'un module a été réparé |
138
- | `heal.failed` | `{ module, error, attempts }` | Notifie qu'une réparation a échoué |
139
- | `heal.diagnose` | `{ module }` | Diagnostique l'état d'un module |
140
-
141
- ```bash
142
- curl -s -X POST http://127.0.0.1:3104/rpc \
143
- -H "Content-Type: application/json" \
144
- -d '{"jsonrpc":"2.0","id":"1","method":"heal.diagnose","params":{"module":"brain"}}'
145
- ```
146
-
147
- ### :3105 — nexus_researcher (Recherche + Summarization)
148
-
149
- | Méthode | Params | Description |
150
- |---------|--------|-------------|
151
- | `research.query` | `{ topic, depth? }` | Lance une recherche sur un sujet |
152
- | `research.summarize` | `{ sourceIds: string[] }` | Résume des sources |
153
-
154
- ```bash
155
- curl -s -X POST http://127.0.0.1:3105/rpc \
156
- -H "Content-Type: application/json" \
157
- -d '{"jsonrpc":"2.0","id":"1","method":"research.query","params":{"topic":"BTC trends","depth":"deep"}}'
158
- ```
159
-
160
- ### :3106 — nexus_publisher (Notifications + Signaux)
161
-
162
- | Méthode | Params | Description |
163
- |---------|--------|-------------|
164
- | `publish.trade-open` | `{ symbol, side, quantity, entryPrice, timestamp }` | Notifie l'ouverture d'un trade |
165
- | `publish.trade-close` | `{ symbol, side, quantity, exitPrice, pnl?, reason? }` | Notifie la fermeture d'un trade |
166
- | `publish.signal` | `{ message, channel? }` | Publie un signal sur un canal |
167
-
168
- ```bash
169
- curl -s -X POST http://127.0.0.1:3106/rpc \
170
- -H "Content-Type: application/json" \
171
- -d '{"jsonrpc":"2.0","id":"1","method":"publish.signal","params":{"message":"BTC bullish signal","channel":"trading"}}'
172
- ```
173
-
174
- ### Endpoints Communs (tous les bridges)
175
-
176
- | Endpoint | Méthode HTTP | Description |
177
- |----------|-------------|-------------|
178
- | `/health` | GET | `{ agent, status, uptime, rpcMethods[], peerCount }` |
179
- | `/rpc` | POST | JSON-RPC 2.0 dispatcher |
180
- | `/shutdown` | POST | Arrêt propre du bridge |
181
-
182
- ### Routage RPC Interne
183
-
184
- ```
185
- POST /rpc → dispatchRpc(method)
186
- 1. health.ping → local (toujours)
187
- 2. Méthode locale (registerRpcMethod) → handler local
188
- 3. Sinon → forwardToMcp() → POST http://[::1]:3099/mcp
189
- ```
190
-
191
- ---
192
-
193
- ## Commandes RPC OverBridgeServer (Overmind)
194
-
195
- Le `OverBridgeServer` (port 3100 par défaut, ou via discord_llm :3001) expose **24 méthodes JSON-RPC** :
196
-
197
- ### Agents (10 méthodes)
198
-
199
- | Méthode | Params | Description |
200
- |---------|--------|-------------|
201
- | `agent.run` | `agentName, runner, prompt, sessionId?, model?, externalKey?` | Lance un agent |
202
- | `agent.a2a` | `fromAgent, toAgent, runner, prompt, model?` | A→B (Agent-to-Agent) |
203
- | `agent.broadcast` | `fromAgent, runner, prompt, targets[]?, race?` | 1→N fan-out global |
204
- | `agent.pipeline` | `initiator, runner, prompt, steps[], accumulateContext?` | Chaîne A→B→C |
205
- | `agent.fanout` | `fromAgent, runner, prompt, targets[], mergeStrategy?` | 1→N + merge |
206
- | `agent.delegate` | `fromAgent, toAgent, runner, prompt, async?, callbackUrl?` | Fire-and-forget |
207
- | `agent.query` | `fromAgent, runner, prompt, targets[], agentTimeoutMs?` | Multi-agent query |
208
- | `agent.status` | `agentName, action?, runner?` | Status live |
209
- | `agent.list` | `status?, runner?` | Liste des agents |
210
- | `agent.kill` | `agentName, runner?` | Kill un agent |
211
-
212
- ### Messages (4 méthodes)
213
-
214
- | Méthode | Params | Description |
215
- |---------|--------|-------------|
216
- | `message.history` | `toAgent?, fromAgent?, status?, limit?, offset?, sinceHours?` | Historique paginé |
217
- | `message.get` | `id` (UUID) | Récupère un message |
218
- | `message.replay` | `id` (UUID) | Rejoue un message |
219
- | `message.stats` | — | Stats globales |
220
-
221
- ### Sessions (4 méthodes)
222
-
223
- | Méthode | Params | Description |
224
- |---------|--------|-------------|
225
- | `session.get` | `externalKey, agentName` | Session d'un utilisateur |
226
- | `session.list` | — | Toutes les sessions |
227
- | `session.delete` | `externalKey, agentName` | Supprime une session |
228
- | `session.stats` | — | Stats des sessions |
229
-
230
- ### Autres (6 méthodes)
231
-
232
- | Méthode | Description |
233
- |---------|-------------|
234
- | `health.ping` | Liveness check |
235
- | `webhook.sms` | Adapt + auto-dispatch webhook SMS |
236
- | `GET /health` | Healthcheck enrichi |
237
- | `POST /webhook/:provider` | Webhook HTTP (voipms, twilio, discord) |
238
- | `GET /f/:filename` | Static file serve |
239
- | `OPTIONS *` | CORS preflight |
240
-
241
- ---
242
-
243
- ## Commandes A2A Hub (MCP Tool)
244
-
245
- Le tool MCP `a2a_hub` expose 8 actions pour la communication inter-agents :
246
-
247
- | Action | Params | Description |
248
- |--------|--------|-------------|
249
- | `discover` | — | Liste tous les agents avec statut temps réel |
250
- | `status` | `target` | État détaillé d'un agent |
251
- | `send` | `target, message` | Message synchrone A→B |
252
- | `delegate` | `target, message, callbackUrl?` | Tâche async (retourne taskId) |
253
- | `pipeline` | `message, steps[]` | Chaîne séquentielle A→B→C |
254
- | `fanout` | `targets[], message, mergeStrategy?` | 1→N parallèle + merge |
255
- | `query` | `targets[], message` | Question rapide multi-agents |
256
- | `broadcast` | `message, race?` | Message global à tous |
257
-
258
- ```python
259
- # Exemples
260
- a2a_hub(action="discover")
261
- a2a_hub(action="send", target="nexus_trader", message="Analyse BTC")
262
- a2a_hub(action="pipeline", message="Analyse le marché", steps=[{"agentName":"nexus_researcher"},{"agentName":"nexus_trader"}])
263
- a2a_hub(action="fanout", targets=["nexus_trader","nexus_risk_manager"], message="BTC?", mergeStrategy="best")
264
- a2a_hub(action="broadcast", message="Alerte!", race=true)
265
- ```
266
-
267
- ---
268
-
269
- ## Commandes CLI overmind-bridge
270
-
271
- ### Démarrer le serveur
272
-
273
- ```bash
274
- overmind-bridge server --port 3100
275
- ```
276
-
277
- ### Appels one-shot
278
-
279
- ```bash
280
- # Flag direct
281
- overmind-bridge call agent.run --agent nexus_master --runner hermes --prompt "Analyse BTC"
282
-
283
- # Stdin
284
- echo "Analyse BTC" | overmind-bridge call agent.run --agent nexus_master --runner hermes --prompt-stdin
285
-
286
- # Fichier + variables
287
- overmind-bridge call agent.run --agent nexus_master --runner hermes \
288
- --prompt-file ./brief.txt --var ticker=BTC
289
-
290
- # A2A
291
- overmind-bridge call agent.a2a --from nexus_master --to nexus_trader --runner hermes \
292
- --prompt "Valide mon analyse"
293
- ```
294
-
295
- ### Gestion
296
-
297
- ```bash
298
- overmind-bridge status # Status de tous les agents
299
- overmind-bridge health # Health du serveur
300
- overmind-bridge replay --id 7f3e8a1b-... # Replay un message
301
- overmind-bridge sessions list # Liste des sessions
302
- overmind-bridge sessions get --key "+141****7735" --agent pdf_bon_travail
303
- overmind-bridge sessions rm --key "+141****7735" --agent pdf_bon_travail
304
- ```
305
-
306
- ---
307
-
308
- ## Commandes Hermes Profile Management
309
-
310
- ### Créer un agent
311
-
312
- ```bash
313
- # Via MCP tool
314
- create_agent(name: "trader_btc", runner: "hermes", prompt: "...", model: "glm-5.2")
315
-
316
- # Via CLI
317
- hermes profile create trader_btc --no-alias --description "Trader BTC"
318
- hermes -p trader_btc config set model.provider z-ai
319
- hermes -p trader_btc config set model.model glm-5.2
320
- ```
321
-
322
- ### Gérer les profils
323
-
324
- ```bash
325
- hermes profile list # Lister
326
- hermes profile show nexus_master # Détails
327
- hermes profile delete nexus_master --yes # Supprimer
328
- hermes -p nexus_master config set model.model "MiniMax-M3" # Changer modèle
329
- ```
330
-
331
- ### Lancer un agent
332
-
333
- ```bash
334
- # Via Gateway HTTP (recommandé — zero subprocess)
335
- run_agent(runner: "hermes", agentName: "nexus_master", prompt: "...")
336
-
337
- # Via CLI
338
- hermes -p nexus_master chat -q "Analyse le BTC" -Q --yolo
339
-
340
- # Via curl direct sur le Gateway
341
- curl -X POST http://127.0.0.1:8642/v1/chat/completions \
342
- -H "Content-Type: application/json" \
343
- -H "Authorization: Bearer ${API_SERVER_KEY}" \
344
- -H "X-Hermes-Profile: nexus_master" \
345
- -d '{"model":"glm-5.2","messages":[{"role":"user","content":"..."}],"stream":true}'
346
- ```
347
-
348
- ---
349
-
350
- ## Scripts Helper d'Installation
351
-
352
- ### NEXUS — Démarrage et gestion
353
-
354
- | Script | Usage | Description |
355
- |--------|-------|-------------|
356
- | `scripts/start-all-bridges.cjs` | `node scripts/start-all-bridges.cjs` | Démarre les 6 bridges en parallèle |
357
- | `scripts/stop-all-bridges.cjs` | `node scripts/stop-all-bridges.cjs` | Arrête les 6 bridges |
358
- | `scripts/status-bridges.cjs` | `node scripts/status-bridges.cjs` | Status de chaque bridge |
359
- | `scripts/seed-bridges.cjs` | `node scripts/seed-bridges.cjs` | Crée la structure + .env pour les 6 |
360
- | `scripts/test-a2a.cjs` | `node scripts/test-a2a.cjs` | Test E2A inter-bridges |
361
- | `scripts/postbuild.cjs` | `node scripts/postbuild.cjs` | Copie config + .env vers dist |
362
-
363
- ### Overmind — Build et install
364
-
365
- ```bash
366
- # Build complet
367
- cd Workflow && npm run build
368
-
369
- # Lint
370
- npm run lint
371
-
372
- # Test
373
- npm run test
374
-
375
- # Vérification installation
376
- npm run verify-install
377
-
378
- # Setup complet (Docker + Postgres + MCP)
379
- npm run setup
380
- ```
381
-
382
- ### discord_llm — Build et démarrage
383
-
384
- ```bash
385
- cd discord_llm && npm run build && npm start
386
- ```
387
-
388
- ### Hermes Gateway — Activation
389
-
390
- ```bash
391
- # Config dans config.yaml
392
- gateway:
393
- platforms:
394
- api_server:
395
- enabled: true
396
-
397
- # .env
398
- API_SERVER_KEY=<key>
399
- API_SERVER_ENABLED=1
400
-
401
- # Redémarrer
402
- hermes gateway restart
403
- ```
404
-
405
- ---
406
-
407
- ## Bugs Source Corrigés
408
-
409
- ### Overmind (Workflow/src/bridge/)
410
-
411
- | Bug | Fichier | Fix |
412
- |-----|---------|-----|
413
- | `localhost` au lieu de `[::1]` (IPv4/IPv6 mismatch Windows) | `types.ts:159` | → `http://[::1]:3099/mcp` |
414
- | `ping()` sans SSE Accept header (FastMCP rejette) | `BridgeProxy.ts:181` | → Ajout `Accept: text/event-stream` + fallback `GET /health` |
415
- | `parseSseText` non importé dans `BridgeProxy` | `BridgeProxy.ts:25` | → Ajout import |
416
- | Commentaire doc `localhost:3099` | `BridgeProxy.ts:11` | → `[::1]:3099` |
417
-
418
- ### NEXUS (Nexus/common/ + bridges/)
419
-
420
- | Bug | Fichier | Fix |
421
- |-----|---------|-----|
422
- | MCP URL `/rpc` au lieu de `/mcp` (FastMCP 404) | `BaseBridge.ts:227` | → `${mcpBase}/mcp` avec SSE parsing |
423
- | Timeout MCP hardcodé 60s | `BaseBridge.ts:232` | → `config.mcpTimeoutMs` (120s défaut) |
424
- | `Date.now()` comme ID JSON-RPC (collision) | `BridgeClient.ts:36` | → `crypto.randomUUID()` |
425
- | `appendFileSync` (sync I/O dans hot path) | `logger.ts:71` | → `appendFile` async + rotation 50MB |
426
- | Méthodes RPC custom forwardées au MCP (404) | `BaseBridge.ts:174` | → `registerRpcMethod()` + dispatch local |
427
- | `.env` introuvable après build (dist vs src) | `config.ts:20` | → `candidatePaths[]` multi-niveaux |
428
- | `postbuild.cjs` ne copiait pas les `.env` | `postbuild.cjs` | → Ajout section 2: copy bridges/.env |
429
- | `*/` dans JSDoc cassait le parser CJS | `postbuild.cjs:5` | → Reworded comment |
430
- | Pas de graceful shutdown SIGINT/SIGTERM | `bridge.ts` (×6) | → Ajout handler `process.on('SIGINT')` |
431
- | Pas de keep-alive HTTP (TCP handshake chaque call) | `BridgeClient.ts` | → `HttpAgent({ keepAlive: true })` partagé |
432
-
433
- ### discord_llm
434
-
435
- | Bug | Fichier | Fix |
436
- |-----|---------|-----|
437
- | `localhost:3099` au lieu de `[::1]:3099` | `overmind-bridge.ts:63` | → `http://[::1]:3099/mcp` |
438
- | `no-useless-assignment` lint errors | `overmind-bridge.ts:255,278` | → `let mcpStatus: string` (sans init) |