aissia/docs/SUCCESSION.md

# Document de Succession - AISSIA

## Contexte

AISSIA = Assistant vocal agentique basé sur GroveEngine (C++17 hot-reload). Architecture "Claude Code en vocal" avec tools internes + FileSystem + MCP.

**Dernier commit** : `37b62b5`

## État Actuel

### Ce qui fonctionne

✅ **Build complet** - `cmake -B build && cmake --build build -j4`
✅ **6 modules hot-reload** - Scheduler, Notification, Monitoring, AI, Voice, Storage
✅ **4 services** - LLMService, StorageService, PlatformService, VoiceService
✅ **17 tools pour l'agent** :
  - 11 tools internes (via IIO pub/sub)
  - 6 FileSystem tools (read/write/edit/list/glob/grep)
  - MCP tools (désactivés par défaut)
✅ **Tests** - 67/75 tests modules+types passent

### Lancement

```bash
# Build
cmake -B build && cmake --build build -j4

# Run (depuis racine ou build/)
./build/aissia

# Mode MCP Server (expose les tools via JSON-RPC stdio)
./build/aissia --mcp-server

# Tests
cmake -B build -DBUILD_TESTING=ON
./build/tests/aissia_tests "[scheduler],[notification]"  # Modules
./build/tests/aissia_tests "[types]"                      # MCP types
```

### Variables d'Environnement

```bash
export ANTHROPIC_API_KEY="sk-ant-..."   # Requis pour Claude API
```

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                     LLMService                               │
│                   (Agentic Loop)                             │
├─────────────────────────────────────────────────────────────┤
│  ToolRegistry                                                │
│  ├── InternalTools (11) ─────► IIO pub/sub                  │
│  ├── FileSystemTools (6) ────► Direct C++ (read/write/edit) │
│  └── MCPClient (optionnel) ──► stdio JSON-RPC               │
└─────────────────────────────────────────────────────────────┘
                              │
         ┌──────────────┬─────┴──────┬──────────────┐
    Scheduler      Monitoring    Storage        Voice
     Module          Module       Module        Module
```

### Tools Disponibles

| Catégorie | Tools | Communication |
|-----------|-------|---------------|
| Scheduler | get_current_task, list_tasks, start_task, complete_task, start_break | IIO |
| Monitoring | get_focus_stats, get_current_app | IIO |
| Storage | save_note, query_notes, get_session_history | IIO |
| Voice | speak | IIO |
| FileSystem | read_file, write_file, edit_file, list_directory, glob_files, grep_files | Direct C++ |

### FileSystem Tools (Nouveau)

Implémentés dans `src/shared/tools/FileSystemTools.*` :

```cpp
// Lecture avec numéros de ligne
FileSystemTools::execute("read_file", {{"path", "/path/to/file"}, {"limit", 10}});

// Édition style Claude Code
FileSystemTools::execute("edit_file", {
    {"path", "/path/to/file"},
    {"old_string", "foo"},
    {"new_string", "bar"}
});

// Recherche
FileSystemTools::execute("glob_files", {{"pattern", "**/*.cpp"}});
FileSystemTools::execute("grep_files", {{"pattern", "TODO"}, {"path", "./src"}});
```

**Sécurité** :
- Chemins autorisés configurables
- Patterns bloqués : `*.env`, `*.key`, `*credentials*`
- Limites : 1MB lecture, 10MB écriture

## Fichiers Clés

### Nouveaux (Session actuelle)
```
src/shared/tools/FileSystemTools.hpp
src/shared/tools/FileSystemTools.cpp
PLAN_FILESYSTEM_TOOLS.md
```

### Services
```
src/services/LLMService.*      # Agentic loop, tools registry
src/services/StorageService.*  # SQLite persistence
src/services/PlatformService.* # Window tracking
src/services/VoiceService.*    # TTS/STT
```

### Modules (Hot-Reload)
```
src/modules/SchedulerModule.*
src/modules/NotificationModule.*
src/modules/MonitoringModule.*
src/modules/AIModule.*
src/modules/VoiceModule.*
src/modules/StorageModule.*
```

### MCP
```
src/shared/mcp/MCPTypes.hpp
src/shared/mcp/MCPClient.*      # Client MCP (consomme des serveurs externes)
src/shared/mcp/MCPServer.*      # Serveur MCP (expose AISSIA comme serveur)
src/shared/mcp/StdioTransport.*
config/mcp.json
```

## Tests

```bash
# Build avec tests
cmake -B build -DBUILD_TESTING=ON && cmake --build build -j4

# Par catégorie
./build/tests/aissia_tests "[scheduler]"      # 10 tests
./build/tests/aissia_tests "[notification]"   # 10 tests
./build/tests/aissia_tests "[types]"          # 15 tests MCP

# Tous les modules
./build/tests/aissia_tests "[scheduler],[notification],[monitoring],[ai],[voice],[storage]"
```

**Résultats actuels** :
- Modules : 52/60 (87%)
- MCP Types : 15/15 (100%)
- MCP Transport/Client : Nécessite fix serveurs Python

## Prochaines Étapes

### Priorité Haute
1. **Tester avec API key** - Vérifier la boucle agentique complète
2. **Activer MCP filesystem** - Pour tests end-to-end avec tools externes

### Priorité Moyenne
3. **Fixer tests MCP Transport** - Les serveurs Python reçoivent EOF
4. **Ajouter plus de tools** - add_task, set_reminder, etc.
5. **Streaming responses** - Feedback temps réel pendant génération

### Priorité Basse
6. **Tests end-to-end** - Flux complet inter-modules
7. **CI/CD** - GitHub Actions
8. **Documentation API** - Doxygen

## MCP Server Mode

AISSIA peut fonctionner comme **serveur MCP**, exposant ses tools à des clients externes via JSON-RPC sur stdio.

```bash
./build/aissia --mcp-server
```

### Protocole

Communication JSON-RPC 2.0 sur stdin/stdout :

```json
// Client → AISSIA
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"clientInfo":{"name":"client","version":"1.0"}}}

// AISSIA → Client
{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","serverInfo":{"name":"aissia","version":"0.2.0"},...}}

// Lister les tools
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

// Appeler un tool
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_directory","arguments":{"path":"."}}}
```

### Utilisation avec Claude Code

Ajouter dans la config MCP :
```json
{
  "servers": {
    "aissia": {
      "command": "/chemin/vers/build/aissia",
      "args": ["--mcp-server"]
    }
  }
}
```

### Tools Exposés (actuellement)

6 FileSystem tools. TODO: exposer les tools internes (scheduler, voice, etc.).

## Notes Techniques

### WSL
- Window tracker non disponible (stub utilisé)
- espeak non installé (TTS stub)
- Tout le reste fonctionne

### Hot-Reload
Les modules sont des `.so` chargés dynamiquement. Pour recompiler un module :
```bash
cmake --build build --target SchedulerModule
# Le module sera rechargé au prochain cycle si modifié
```