overmind-mcp 2.3.0 → 2.3.2

package/docs/ASYNC_AGENT_INTEGRATION.md

@@ -1,311 +0,0 @@
-# OverMind Async Agent Integration — Process Registry & PID Tracking
-
-> **Problème résolu** : Les agents IA sont invoked en async via MCP, mais le seul lien avec le processus fils est le `sessionId` (généré par le runner, opaque pour OverMind). Si le processus parent meurt, le `sessionId` est perdu et le child process devient orphelin.
->
-> **Solution** : Un **Process Registry** qui stocke le mapping `pid ↔ sessionId ↔ agentName`, persistant dans `sessions.json`, permettant de :
-> - Se rattacher à un agent en cours via son PID
-> - Vérifier si un agent est encore vivant
-> - Tuer un agent par son PID
-> - Streamer output en temps réel
-
----
-
-## 1. Architecture
-
-```
-┌──────────────────────────────────────────────────────────────┐
-│  MCP Tool: run_agent() (async, non-blocking)                  │
-│                                                              │
-│  1. Spawn child process (claude/kilo/gemini/etc.)           │
-│  2. Register { pid, sessionId, agentName, runner, ts }     │
-│  3. Return immediately with { sessionId, pid }             │
-│     → Client can poll / attach to PID                       │
-│                                                              │
-│  ┌──────────────────┐    ┌──────────────────────────────┐  │
-│  │  Process Registry │◄──│  child.on('data')             │  │
-│  │  (sessions.json)  │    │  → buffers output            │  │
-│  │                   │    │  → checks liveliness         │  │
-│  │  { pid, sessionId,│    └──────────────────────────────┘  │
-│  │    agentName,     │                                     │
-│  │    runner, status,│    ┌──────────────────────────────┐  │
-│  │    startedAt }    │    │  MCP Tool: get_agent_status() │  │
-│  └──────────────────┘    │  → returns live output        │  │
-│                          │  → pid / alive / output so far │  │
-│                          └──────────────────────────────┘  │
-└──────────────────────────────────────────────────────────────┘
-```
-
----
-
-## 2. Sessions JSON — Nouveau Format
-
-**Avant** (sessions.json) :
-```json
-{
-  "kilo:sniper_analyst": { "id": "sess_abc123", "ts": 1746892800000 }
-}
-```
-
-**Après** (sessions.json + process registry) :
-```json
-{
-  "kilo:sniper_analyst": {
-    "id": "sess_abc123",
-    "ts": 1746892800000,
-    "pid": 12345,
-    "status": "running",
-    "outputBuffer": ""
-  },
-  "claude:planner": {
-    "id": "sess_def456",
-    "ts": 1746892900000,
-    "pid": 67890,
-    "status": "running",
-    "outputBuffer": "Thinking...\n"
-  }
-}
-```
-
-Le champ `status` peut être :
-- `running` — processus actif, PID valide
-- `done` — terminé avec succès (garde le last output pour retrieval)
-- `failed` — terminé avec erreur
-- `orphaned` — le parent a crash mais le child tourne encore
-
----
-
-## 3. Runner Changes — Spawn & Register
-
-Chaque runner (Claude, Kilo, Gemini, Hermes, etc.) doit :
-
-1. **Stocker le PID** dès le `spawn()` :
-```typescript
-const child = spawn(command, args, options);
-// Immediately register
-await registerProcess(child.pid, {
-  sessionId: undefined,      // filled when runner gives us sessionId
-  agentName,
-  runner,
-  startedAt: Date.now(),
-  status: 'running',
-});
-```
-
-2. **Mettre à jour avec le sessionId** dès qu'il est reçu :
-```typescript
-child.stdout?.on('data', (d) => {
-  const chunk = d.toString();
-  outputBuffer += chunk;
-  // Si le sessionId arrive pour la première fois
-  if (sessionId && !currentSessionId) {
-    currentSessionId = sessionId;
-    await updateProcessSession(sessionId, child.pid);
-  }
-});
-```
-
-3. **Marquer `done/failed`** à `child.on('close')` :
-```typescript
-child.on('close', async (code) => {
-  await updateProcessStatus(child.pid, code === 0 ? 'done' : 'failed');
-});
-```
-
-4. **Cleanup à la terminaison** :
-```typescript
-// Supprimer après 1h ( TTL ) ou sur explicit delete
-await unregisterProcess(pid);
-```
-
----
-
-## 4. Nouvelles Fonctions Registry
-
-```typescript
-// ─── Register a new running process ───────────────────────────
-/**
- * Called immediately after spawn(). Records the PID before the sessionId
- * is known (sessionId arrives later from stdout).
- */
-export async function registerProcess(
-  pid: number,
-  meta: {
-    agentName: string;
-    runner: string;
-    startedAt: number;
-    configPath?: string;
-  },
-): Promise<void> { ... }
-
-/**
- * Called when the runner emits a sessionId for the first time.
- * Links sessionId ↔ pid in the registry.
- */
-export async function linkSessionToPid(
-  sessionId: string,
-  pid: number,
-  configPath?: string,
-): Promise<void> { ... }
-
-/**
- * Update output buffer for live streaming.
- */
-export async function appendOutput(
-  pid: number,
-  chunk: string,
-  configPath?: string,
-): Promise<void> { ... }
-
-/**
- * Get current status + output buffer for a process.
- */
-export async function getProcessStatus(
-  agentName: string,
-  runner?: string,
-  configPath?: string,
-): Promise<ProcessStatus | null> { ... }
-
-/**
- * Kill a running agent by PID (Windows: taskkill /F /T /PID; Unix: SIGKILL).
- */
-export async function killAgent(
-  agentName: string,
-  runner?: string,
-  configPath?: string,
-): Promise<boolean> { ... }
-
-/**
- * Unregister (cleanup) a process entry.
- */
-export async function unregisterProcess(
-  pid: number,
-  configPath?: string,
-): Promise<void> { ... }
-```
-
----
-
-## 5. TTL & Cleanup
-
-```typescript
-const PROCESS_TTL_MS = 60 * 60 * 1000; // 1 hour after 'done'/'failed'
-const ORPHAN_CHECK_INTERVAL = 5 * 60 * 1000; // 5 minutes
-
-// On startup, scan for:
-// 1. 'running' entries where the PID no longer exists → mark 'orphaned'
-// 2. 'done'/'failed' entries older than PROCESS_TTL_MS → unregister
-```
-
----
-
-## 6. Nouveaux Outils MCP
-
-### `get_agent_status`
-```typescript
-{
-  agentName: string;
-  runner?: string; // defaults to 'claude' if omitted
-}
-// Returns:
-// { status, pid, outputBuffer, startedAt, sessionId }
-```
-
-### `stream_agent_output`
-```typescript
-{
-  agentName: string;
-  runner?: string;
-  sinceTimestamp?: number; // only return output after this ts
-}
-// Returns:
-// { output: string, status, isComplete: boolean }
-```
-
-### `kill_agent`
-```typescript
-{
-  agentName: string;
-  runner?: string;
-}
-// Returns:
-// { killed: boolean, pid: number }
-```
-
-### `wait_agent`
-```typescript
-{
-  agentName: string;
-  runner?: string;
-  timeoutMs?: number; // default: 900000 (15 min)
-}
-// Polls until status !== 'running', returns final result
-// Returns:
-// { status, result, exitCode }
-```
-
----
-
-## 7. Flux Complet — Async Agent Lifecycle
-
-```
-Client                    OverMind MCP                   Runner
-  │                           │                            │
-  │  run_agent()              │                            │
-  │─────────────────────────►│                            │
-  │                           │  spawn(child)               │
-  │                           │───────────────────────────►│
-  │                           │  registerProcess(pid)      │
-  │                           │  Return { sessionId, pid } │
-  │  { sessionId, pid }       │                            │
-  │◄──────────────────────────│                            │
-  │                           │                            │
-  │  get_agent_status()        │                            │
-  │─────────────────────────►│                            │
-  │                           │  getProcessStatus()        │
-  │  { status, outputBuffer }│                            │
-  │◄──────────────────────────│                            │
-  │                           │  stdout.on('data')         │
-  │                           │◄──────────────────────────│
-  │                           │  appendOutput(pid, chunk) │
-  │                           │                            │
-  │  stream_agent_output()    │                            │
-  │─────────────────────────►│                            │
-  │  { output, status }       │                            │
-  │◄──────────────────────────│                            │
-  │                           │  child.on('close')        │
-  │                           │◄──────────────────────────│
-  │                           │  updateProcessStatus(done) │
-  │                           │                            │
-  │  wait_agent()              │                            │
-  │─────────────────────────►│                            │
-  │  Polls until done          │                            │
-  │  { status, result }       │                            │
-  │◄──────────────────────────│                            │
-```
-
----
-
-## 8. Backward Compatibility
-
-- Les champs existants (`id`, `ts`) dans `sessions.json` ne changent pas
-- `status`, `pid`, `outputBuffer` sont **ajoutés** (optionnels)
-- Le `sessionId` reste le même — les outils existants (`autoResume`) continuent de fonctionner
-- Si `pid` n'existe pas dans une entrée (sessions anciennes), le status est déduit de `ts` :
-  - `ts` < 30 jours + pas de `pid` → `done` (legacy)
-  - `ts` récent + pas de `pid` → `running` (legacy, mais incertain)
-
----
-
-## 9. Implémentation Minimale — Checklist
-
-- [ ] `src/lib/processRegistry.ts` — nouvelles fonctions (register, link, append, status, kill, unregister)
-- [ ] `src/lib/sessions.ts` — ajout champs `pid`, `status`, `outputBuffer`
-- [ ] Chaque runner (8 fichiers) — ajouter `registerProcess()` après `spawn()`
-- [ ] Chaque runner — ajouter `appendOutput()` dans `stdout.on('data')`
-- [ ] Chaque runner — ajouter `updateProcessStatus()` dans `child.on('close')`
-- [ ] `src/tools/get_agent_status.ts` — nouvel outil MCP
-- [ ] `src/tools/stream_agent_output.ts` — nouvel outil MCP
-- [ ] `src/tools/kill_agent.ts` — nouvel outil MCP
-- [ ] `src/tools/wait_agent.ts` — nouvel outil MCP
-- [ ] `server.ts` — register les 4 nouveaux outils
-- [ ] Tests dans `src/__tests__/processRegistry.test.ts`

package/docs/INDEX.md

@@ -1,144 +0,0 @@
-# Documentation OverMind-MCP
-
-Bienvenue dans la documentation centralisée d'OverMind-MCP.
-
-> **Note** : Le site web cyberpunk avec animations est disponible dans ce dossier. Ce fichier INDEX.md sert de table des matières pour la documentation technique.
-
-## 📑 Structure
-
-```
-Workflow/
-├── dock../docker/docker-compose.yml              # Stack principale (9 services)
-├── docker-compose.exporters.yml    # Exporters métriques
-├── scripts/                        # Scripts setup/gestion
-│   ├── setup.mjs
-│   ├── install-dependencies.mjs
-│   └── docker-manager.mjs
-│
-└── docs/                   # Documentation
-    ├── index.html          # Site web cyberpunk
-    ├── INDEX.md            # Ce fichier (table des matières)
-    ├── guides/             # Guides utilisateur
-    │   ├── README.md       # Guide principal
-    │   ├── DEPLOYMENT.md   # Guide déploiement
-    │   └── SWARM_USAGE.md  # Guide Swarm
-    ├── api/                # Documentation API
-    │   ├── prompt/         # Prompts système
-    │   └── tools.md        # Référence outils
-    └── changelog/          # Historique versions
-        ├── CHANGELOG.md
-        └── CHANGELOG.add.md
-```
-
-## 🚀 Par où commencer ?
-
-1. **Nouveau utilisateur ?** → Commencez par [`guides/README.md`](./guides/README.md)
-2. **Veut déployer en production ?** → Voir [`guides/DEPLOYMENT.md`](./guides/DEPLOYMENT.md)
-3. **Intéressé par le Swarm ?** → Lire [`guides/SWARM_USAGE.md`](./guides/SWARM_USAGE.md)
-4. **Besoin de la référence API ?** → Consulter [`api/tools.md`](./api/tools.md)
-
-## 📚 Guides Utilisateur
-
-### [`guides/README.md`](./guides/README.md)
-Guide principal d'utilisation :
-- Installation et setup
-- Configuration des agents
-- Utilisation des runners
-- Exemples pratiques
-
-### [`guides/DEPLOYMENT.md`](./guides/DEPLOYMENT.md)
-Guide complet de déploiement :
-- Prérequis système
-- Configuration Docker Compose
-- Setup infrastructure (PostgreSQL, RabbitMQ, Temporal)
-- Sécurité et maintenance
-- Monitoring avec Prometheus/Grafana
-
-### [`guides/SWARM_USAGE.md`](./guides/SWARM_USAGE.md)
-Guide d'orchestration Swarm :
-- Configuration du swarm
-- Allocation dynamique de tâches
-- Workflows long-running
-- Exemples concrets
-- Monitoring et debug
-
-## 🏗️ Infrastructure
-
-### Docker Compose
-- **[`../dock../docker/docker-compose.yml`](../dock../docker/docker-compose.yml)** - Stack principale (9 services)
-  - RabbitMQ (Message Broker)
-  - Temporal (Workflow Orchestrator)
-  - PostgreSQL + pgvector (Vector DB)
-  - Redis (Cache)
-  - Prometheus (Metrics)
-  - Grafana (Dashboards)
-  - Jaeger (Tracing)
-  - OpenTelemetry Collector
-  - Node Exporter
-
-- **[`../docker-compose.exporters.yml`](../docker-compose.exporters.yml)** - Exporters de métriques
-  - RabbitMQ Exporter
-  - PostgreSQL Exporter
-  - Redis Exporter
-
-### Scripts Setup
-Voir [`../scripts/`](../scripts/) :
-- `setup.mjs` - Setup interactif complet
-- `install-dependencies.mjs` - Installation Docker/PostgreSQL
-- `docker-manager.mjs` - Gestion infrastructure (up/down/logs/status)
-- `postinstall.mjs` - Post-installation NPM
-
-## 🔌 API & Référence
-
-### [`api/prompt/`](./api/prompt/)
-Documentation des prompts système pour chaque runner :
-- Claude Code
-- Kilo (code, architect, ask, debug)
-- Hermes
-- Minimax 4
-
-### [`api/tools.md`](./api/tools.md)
-Référence complète des outils MCP :
-- `run_agent` - Exécuter un agent
-- `create_agent` - Créer un nouvel agent
-- `list_agents` - Lister les agents
-- `memory_search` - Recherche mémoire
-- `run_agents_parallel` - Exécution parallèle
-
-## 📝 Changelog
-
-### [`changelog/CHANGELOG.md`](./changelog/CHANGELOG.md)
-Historique complet des versions :
-- Toutes les versions de 1.x à 2.0.0
-- Features, bug fixes, breaking changes
-- Notes de migration
-
-### [`changelog/CHANGELOG.add.md`](./changelog/CHANGELOG.add.md)
-Notes détaillées de la v2.0.0 :
-- Swarm Orchestration
-- Long-Running Workflows
-- Infrastructure Docker complète
-- Observabilité de niveau production
-
-## 🔍 Recherche Rapide
-
-### Je veux...
-
-- **Installer OverMind** → [`guides/README.md`](./guides/README.md)
-- **Déployer en production** → [`guides/DEPLOYMENT.md`](./guides/DEPLOYMENT.md)
-- **Créer un agent** → [`guides/README.md`](./guides/README.md)
-- **Utiliser le Swarm** → [`guides/SWARM_USAGE.md`](./guides/SWARM_USAGE.md)
-- **Voir la référence API** → [`tools.md`](./tools.md)
-- **Setup Docker** → [`../dock../docker/docker-compose.yml`](../dock../docker/docker-compose.yml)
-- **Voir les nouveautés** → [`changelog/CHANGELOG.md`](./changelog/CHANGELOG.md)
-- **Debug un problème** → [`guides/DEPLOYMENT.md`](./guides/DEPLOYMENT.md) (section Monitoring)
-
-## 📖 Ressources Externes
-
-- **GitHub** : https://github.com/DeamonDev888/overmind-mcp
-- **Discord** : https://discord.gg/4AR82phtBz
-- **Site Web** : https://deamondev888.github.io/overmind-mcp/
-
----
-
-**Retour au README principal** : [`../README.md`](../README.md)

package/docs/changelog/CHANGELOG.add.md

@@ -1,106 +0,0 @@
-# Changelog
-
-## [2.0.0] - 2026-05-09
-
-### 🚀 OverMind-MCP v2.0.0 - Swarm & Observabilité Unifiée
-
-Cette version majeure marque l'achèvement complet de l'infrastructure OverMind-MCP avec des fonctionnalités d'orchestration avancées et une observabilité de niveau production.
-
-#### 🎯 Nouvelles Fonctionnalités Majeures
-
-**Swarm Orchestration (NOUVEAU)**
-- Allocation dynamique de tâches aux agents spécialisés
-- Load Balancing automatique avec scoring intelligent
-- Support de capacités multiples par agent (code, analysis, scraping, etc.)
-- Gestion de priorités de tâches (1-10)
-- Statistiques en temps réel (completed, failed, running, pending)
-- `createSwarmOrchestrator()` avec API complète
-- Fichier: `src/lib/orchestration/swarm.ts`
-
-**Workflows Long-Running Temporal (NOUVEAU)**
-- `longRunningWorkflow` pour tâches stateful (OSINT, analyses complètes)
-- Support de workflows jusqu'à 7 jours
-- Signaux de contrôle: `cancel`, `pause`, `resume`
-- Query d'état temps réel du workflow
-- Survit aux crashes (persistance Temporal)
-- API enrichie: `startLongRunningWorkflow()`, `getLongRunningWorkflowHandle()`
-- Fichiers: `src/lib/workflow/temporal/workflows.ts`, `client.ts`
-
-**Infrastructure Docker Complète (NOUVEAU)**
-- `docker-compose.yml`: Stack principale (9 services)
-  - RabbitMQ (Message Broker) avec Management UI
-  - Temporal (Workflow Orchestrator) avec Web UI
-  - PostgreSQL + pgvector (Vector DB 4096D)
-  - Redis (Cache & Sessions)
-  - Prometheus (Metrics Collection)
-  - Grafana (Dashboards)
-  - Jaeger (Distributed Tracing)
-  - OpenTelemetry Collector (Traces Bridge)
-  - Node Exporter (Host metrics)
-- `docker-compose.exporters.yml`: Exporters de métriques
-  - RabbitMQ Exporter
-  - PostgreSQL Exporter
-  - Redis Exporter
-- `init-db.sql`: Script d'initialisation PostgreSQL
-- `config/prometheus.yml`: Configuration Prometheus
-- `config/otel-collector.yml`: Configuration OpenTelemetry Collector
-
-**Observabilité de Niveau Production (NOUVEAU)**
-- Traces distribuées via OpenTelemetry → Jaeger
-- Métriques temps réel via Prometheus
-- Dashboards Grafana prêts à l'emploi
-- Support complet de télémétrie sur tous les runners
-- Scripts NPM ajoutés: `deploy:infra`, `deploy:exporters`, `deploy:all`, `deploy:logs`, `deploy:status`
-
-#### 📚 Documentation
-
-**Nouveaux Guides**
-- `DEPLOYMENT.md` (600+ lignes): Guide déploiement complet
-  - Prérequis, configuration, Docker Compose setup
-  - Tests & validation, sécurité & maintenance
-  - Workflows avancés, monitoring
-- `SWARM_USAGE.md` (500+ lignes): Guide Swarm Orchestration
-  - Configuration du swarm, allocation de tâches
-  - Workflows long-running, exemples pratiques
-  - Monitoring & debug
-- Configuration .env étendue avec toutes les variables
-
-#### 🔧 Améliorations Techniques
-
-- **Correction TypeScript**: `swarm.ts` (possibly undefined values)
-- **Correction ESLint**: Suppression warnings (unused vars, any types)
-- **Correction Tests**: Mock `registerMemoryAlertCallback` dans tests
-- **Tests**: 69 passed, 3 skipped (100% succès)
-- **Build**: TypeScript compilation clean
-- **Linting**: ESLint clean (0 errors, 0 warnings)
-
-#### 🚨 Breaking Changes
-
-- **Version majeure** (1.x → 2.0) dû à l'ajout significatif de fonctionnalités
-- **Nouvelles APIs publiques**: Swarm, Long-Running Workflows
-- **Nouvelle structure de projet**: `docker/`, `config/`, scripts déploiement
-- **Configuration .env**: Variables étendues (rétro-compatible)
-
-#### 🔄 Migration
-
-- Aucune migration nécessaire pour les utilisateurs existants
-- Les nouvelles fonctionnalités sont opt-in
-- Configuration .env étendue (rétro-compatible)
-
-#### 📦 Dependencies
-
-Mises à jour mineures de dépendances
-
----
-
-**Déploiement 100% terminé !** 🎉
-
-OverMind-MCP est maintenant un orchestrateur d'agents IA complet avec:
-- ✅ Message Broker RabbitMQ
-- ✅ Vector DB pgvector (4096D)
-- ✅ Temporal Workflows long-running
-- ✅ Swarm Orchestration avec allocation dynamique
-- ✅ Observabilité complète (Prometheus, Grafana, Jaeger)
-- ✅ Documentation production-ready
-
-**Prêt pour la production** 🚀