CortexLM
diff --git a/‎ORCHESTRATE/AGENT_10_BACKEND.md‎
Lines changed: 873 additions & 0 deletions b/‎ORCHESTRATE/AGENT_10_BACKEND.md‎
Lines changed: 873 additions & 0 deletions
diff --git a/‎ORCHESTRATE/AGENT_1_MULTIAGENT.md‎
Lines changed: 302 additions & 0 deletions b/‎ORCHESTRATE/AGENT_1_MULTIAGENT.md‎
Lines changed: 302 additions & 0 deletions
@@ -0,0 +1,302 @@
+# AGENT_1: Multi-Agent System & Subagents
+
+## Mission
+
+Implémenter un système complet de multi-agents permettant l'orchestration de subagents parallèles avec communication inter-agents, inspiré de Claude Code et OpenAI Codex.
+
+## Contexte
+
+**Source de référence:** AMELIORATIONS.md Sections 2.1, 5.5, 16.1.1, 21.1.10  
+**Priorité:** 🔴 Critique  
+**Effort estimé:** 6-8 jours développeur  
+**Dépendances internes:** cortex-agents/ (existant mais incomplet)
+
+## État Actuel dans cortex-cli
+
+Le crate `cortex-agents/` existe avec:
+- `AgentControl` - Contrôle basique des threads agents
+- `AgentThread` - Représentation d'un thread agent
+- `AgentInfo` - Configuration d'un agent
+- `@mention` support pour invoquer des subagents
+
+**Manquant:**
+- Outils de collaboration (spawn_agent, send_input, wait, close_agent)
+- DAG de dépendances entre tâches
+- Communication asynchrone entre agents
+- Gestion des limites de profondeur
+- Swarms multi-agents
+
+## Objectifs Spécifiques
+
+### 1. Outils de Collaboration Multi-Agent
+
+Créer `cortex-agents/src/collab/` avec:
+
+```rust
+// collab/mod.rs
+pub mod spawn;
+pub mod send_input;
+pub mod wait;
+pub mod close;
+
+// Constantes
+pub const MAX_THREAD_SPAWN_DEPTH: i32 = 1;
+pub const MIN_WAIT_TIMEOUT_MS: i64 = 10_000;
+pub const DEFAULT_WAIT_TIMEOUT_MS: i64 = 30_000;
+pub const MAX_WAIT_TIMEOUT_MS: i64 = 300_000;
+```
+
+### 2. spawn_agent Tool
+
+```rust
+// collab/spawn.rs
+#[derive(Debug, Deserialize)]
+pub struct SpawnAgentArgs {
+    pub message: String,
+    pub agent_type: Option<AgentRole>,
+}
+
+#[derive(Debug, Serialize)]
+pub struct SpawnAgentResult {
+    pub agent_id: String,
+}
+
+pub async fn handle(
+    session: &Session,
+    args: SpawnAgentArgs,
+) -> Result<SpawnAgentResult, CollabError> {
+    // 1. Valider le message non-vide
+    // 2. Vérifier la profondeur d'imbrication
+    // 3. Créer config pour le nouvel agent
+    // 4. Spawn via AgentControl
+    // 5. Retourner l'ID du nouvel agent
+}
+```
+
+### 3. send_input Tool
+
+```rust
+// collab/send_input.rs
+#[derive(Debug, Deserialize)]
+pub struct SendInputArgs {
+    pub id: String,
+    pub message: String,
+    #[serde(default)]
+    pub interrupt: bool,
+}
+
+pub async fn handle(
+    control: &AgentControl,
+    args: SendInputArgs,
+) -> Result<SendInputResult, CollabError> {
+    // 1. Parser l'ID de l'agent
+    // 2. Optionnellement interrompre avant envoi
+    // 3. Envoyer le prompt
+    // 4. Retourner le submission_id
+}
+```
+
+### 4. wait Tool
+
+```rust
+// collab/wait.rs
+#[derive(Debug, Deserialize)]
+pub struct WaitArgs {
+    pub ids: Vec<String>,
+    pub timeout_ms: Option<i64>,
+}
+
+#[derive(Debug, Serialize)]
+pub struct WaitResult {
+    pub status: HashMap<String, AgentThreadStatus>,
+    pub timed_out: bool,
+}
+
+pub async fn handle(
+    control: &AgentControl,
+    args: WaitArgs,
+) -> Result<WaitResult, CollabError> {
+    // 1. Valider les IDs non-vides
+    // 2. Clamper le timeout entre MIN et MAX
+    // 3. S'abonner aux status
+    // 4. Attendre avec FuturesUnordered + timeout
+    // 5. Retourner les status finaux
+}
+```
+
+### 5. close_agent Tool
+
+```rust
+// collab/close.rs
+pub async fn handle(
+    control: &AgentControl,
+    agent_id: &str,
+) -> Result<CloseAgentResult, CollabError> {
+    // 1. Parser l'ID
+    // 2. Récupérer le status actuel
+    // 3. Shutdown si pas déjà fermé
+    // 4. Retourner le status final
+}
+```
+
+### 6. Système de DAG pour Tâches
+
+Créer `cortex-agents/src/task/`:
+
+```rust
+// task/mod.rs
+pub mod dag;
+pub mod persistence;
+pub mod hydration;
+
+// task/dag.rs
+pub struct TaskDag {
+    tasks: HashMap<TaskId, Task>,
+    dependencies: HashMap<TaskId, HashSet<TaskId>>,
+}
+
+impl TaskDag {
+    pub fn new() -> Self;
+    pub fn add_task(&mut self, task: Task) -> TaskId;
+    pub fn add_dependency(&mut self, task: TaskId, depends_on: TaskId);
+    pub fn get_ready_tasks(&self) -> Vec<&Task>;
+    pub fn mark_completed(&mut self, task_id: TaskId);
+    pub fn topological_sort(&self) -> Result<Vec<TaskId>>;
+}
+```
+
+### 7. Routing Decision Framework
+
+```rust
+// routing.rs
+pub enum DispatchMode {
+    Parallel,   // 3+ tâches non-liées, pas d'état partagé
+    Sequential, // Dépendances entre tâches, fichiers partagés
+    Background, // Recherche/analyse, pas de modifications
+}
+
+pub struct RoutingDecision {
+    pub mode: DispatchMode,
+    pub reason: String,
+    pub affected_files: Vec<PathBuf>,
+}
+
+pub fn decide_routing(tasks: &[Task]) -> RoutingDecision {
+    // Analyser les fichiers modifiés
+    // Détecter les dépendances implicites
+    // Recommander le mode de dispatch
+}
+```
+
+## Fichiers à Créer
+
+```
+cortex-agents/src/
+├── collab/
+│   ├── mod.rs
+│   ├── spawn.rs
+│   ├── send_input.rs
+│   ├── wait.rs
+│   ├── close.rs
+│   └── error.rs
+├── task/
+│   ├── mod.rs
+│   ├── dag.rs
+│   ├── persistence.rs
+│   └── hydration.rs
+├── routing.rs
+└── swarm.rs (optionnel phase 2)
+```
+
+## Fichiers à Modifier
+
+1. `cortex-agents/src/lib.rs` - Ajouter exports des nouveaux modules
+2. `cortex-agents/src/control.rs` - Étendre AgentControl
+3. `cortex-agents/Cargo.toml` - Ajouter dépendances (futures, uuid, tokio)
+
+## Tests Requis
+
+```rust
+#[cfg(test)]
+mod tests {
+    // Test spawn avec validation de profondeur
+    #[tokio::test]
+    async fn test_spawn_depth_limit() { ... }
+    
+    // Test communication inter-agents
+    #[tokio::test]
+    async fn test_send_input_to_agent() { ... }
+    
+    // Test wait avec timeout
+    #[tokio::test]
+    async fn test_wait_with_timeout() { ... }
+    
+    // Test DAG topological sort
+    #[test]
+    fn test_dag_topological_sort() { ... }
+    
+    // Test routing decision
+    #[test]
+    fn test_routing_decision_parallel() { ... }
+}
+```
+
+## Sécurité
+
+### À Implémenter
+
+1. **Limite de profondeur** - MAX_THREAD_SPAWN_DEPTH = 1 (pas de récursion infinie)
+2. **Limite de threads** - Max concurrent agents par session
+3. **Timeout obligatoire** - MIN_WAIT_TIMEOUT_MS pour éviter le polling
+4. **Isolation de contexte** - Chaque agent a son propre contexte
+5. **RAII Guards** - Cleanup automatique des resources
+
+### Vérifications de Sécurité
+
+```rust
+// Avant chaque spawn
+fn validate_spawn(session: &Session) -> Result<()> {
+    let depth = get_current_depth(session);
+    if depth > MAX_THREAD_SPAWN_DEPTH {
+        bail!("Agent depth limit reached");
+    }
+    let active = session.agent_control.active_count();
+    if active >= MAX_CONCURRENT_AGENTS {
+        bail!("Maximum concurrent agents reached");
+    }
+    Ok(())
+}
+```
+
+## Ce Qu'il Ne Faut PAS Faire
+
+1. ❌ Permettre la récursion infinie d'agents
+2. ❌ Ignorer les timeouts
+3. ❌ Partager l'état mutable entre agents sans synchronisation
+4. ❌ Laisser des agents orphelins sans cleanup
+5. ❌ Logger les prompts utilisateur (peuvent contenir des secrets)
+
+## Critères de Succès
+
+- [ ] `spawn_agent` fonctionne avec limite de profondeur
+- [ ] `send_input` permet la communication bidirectionnelle
+- [ ] `wait` respecte les timeouts avec clamping
+- [ ] `close_agent` fait un cleanup propre
+- [ ] DAG gère correctement les dépendances
+- [ ] Tests unitaires passent
+- [ ] Pas de memory leaks (agents cleanup)
+- [ ] Documentation Rustdoc complète
+
+## Estimation
+
+| Tâche | Durée |
+|-------|-------|
+| Outils collab (spawn, send, wait, close) | 3 jours |
+| DAG de tâches | 2 jours |
+| Routing framework | 1 jour |
+| Tests et documentation | 2 jours |
+| **Total** | **8 jours** |
+
+---
+
+*Agent autonome - Pas de dépendance externe*