# Brief Architecture — Orchestration v3 : invocation native d'agents (surface MCP + repli fichier)

> Demandé par **Main** à **Architect**. Cadrage attendu **avant tout code** (méthode §3).
> Ce brief ne prescrit pas l'implémentation : il pose le problème, les contraintes et les
> décisions à trancher. À toi de produire la cartographie (ports, adapters, modèles, lots).

## 1. Contexte & problème

Aujourd'hui, un agent apprend qu'il doit déléguer via IdeA **uniquement par une instruction
en prose** injectée en tête de son convention file (`compose_convention_file`,
`crates/application/src/agent/lifecycle.rs` → bloc « # Orchestration IdeA »). Il écrit alors
un JSON dans `.ideai/requests/<id>/*.json`, capté par l'`OrchestratorWatcher`
(`crates/infrastructure/src/orchestrator/mod.rs`) → validé par le modèle domaine pur
(`crates/domain/src/orchestrator.rs`) → exécuté par `OrchestratorService`.

**Trois faiblesses constatées dans le code :**

1. **Conscience = soft prompt.** Rien ne contraint l'agent ; rien ne l'empêche d'utiliser
   le subagent natif du fournisseur ; le schéma JSON n'est même pas fourni dans l'instruction
   (l'agent doit le deviner).
2. **Pas de discussion inter-agents.** `agent.message` est marqué « future ». Le champ `task`
   d'`agent.run` est replié dans `context`, mais `OrchestratorService` n'utilise `context`
   que pour un agent **neuf** (initial `.md`) : pour un agent **déjà existant**, le `task` est
   **silencieusement ignoré**. La réponse (`*.response.json`) ne porte qu'un ACK de cycle de
   vie (`detail: "launched agent X"`), jamais la sortie produite par la cible.
3. **Fire-and-forget.** Aucune corrélation requête↔réponse de contenu, aucun réveil du
   demandeur.

## 2. Objectif produit (vision Anthony)

Rendre l'invocation d'un agent par un autre **aussi native que l'invocation de subagents dans
Claude CLI** (l'outil `Task` : le modèle voit un outil typé, l'appelle, et **le résultat
revient inline** dans sa conversation) — mais de façon **model-agnostic** (Claude, Codex,
Gemini, custom) et **toujours médiée par IdeA** (qui garde identité, contexte, mémoire,
observabilité UI).

## 3. Direction pressentie (à valider/affiner par l'Architecte)

**Exposer l'orchestration IdeA comme un serveur MCP** que IdeA branche sur chaque CLI qui le
supporte (Claude Code, Codex, Gemini CLI supportent MCP). Outils pressentis :

| Outil MCP | Effet |
|---|---|
| `idea_ask_agent(target, task) → reply` | Lance/réveille la cible, transmet la tâche, **attend et renvoie sa réponse** inline |
| `idea_launch_agent(target, visibility)` | Lancement fire-and-forget (équiv. `agent.run` actuel) |
| `idea_list_agents() → […]` | Découverte des agents du projet |

Bénéfices : conscience native (l'outil apparaît dans la liste d'outils, plus de prose à
« se rappeler »), arguments typés/validés (fini le JSON deviné), et surtout `ask_agent`
**renvoie le contenu** → comble la messagerie inter-agents manquante.

## 4. Points durs à trancher (cœur du cadrage)

1. **Capacité par runtime.** Tous les profils ne supportent pas MCP/outils (custom CLI).
   → Modèle **en couches** : surface MCP quand le profil le déclare ; **repli sur le protocole
   fichier `.ideai/requests` + prose** sinon. Le port `AgentRuntime` gagne une capacité
   déclarative (`supportsMcp` ou descripteur de capacités). Comment exprimer ça dans le profil
   déclaratif (§9) sans casser l'existant ?
2. **Retour synchrone d'`ask_agent`.** C'est le vrai défi : « attendre que la cible ait fini
   son tour et capturer sa sortie » pour un fournisseur arbitraire = même problème que
   l'inspecteur de session (cf. mémoire `conversation-resume-architecture`). Piste : la cible
   écrit sa réponse dans un **outbox** `.ideai/`, l'outil MCP attend/poll avec corrélation
   requête↔réponse + timeout. Définir : modèle de corrélation, event `AgentReplied`, sémantique
   de timeout/erreur, et que faire si la cible tourne déjà (one-live-session-per-agent).
3. **MCP vs subagents natifs.** On garde l'interdiction des subagents natifs (sinon
   court-circuit d'IdeA = perte identité/mémoire/observabilité), mais on offre désormais une
   **vraie alternative native**, pas qu'une interdiction. Comment configurer/injecter le serveur
   MCP par CLI (chaque CLI a sa propre conf MCP) depuis le lancement IdeA ?
4. **Frontières hexagonales.** Où vit le serveur MCP (nouvel adapter d'infrastructure ?), quel
   port côté domaine/application, comment il réutilise `OrchestratorService` existant plutôt que
   de le dupliquer.

## 5. Chantiers adjacents (à seulement situer, pas à cadrer ici)

Garder en tête la cohérence avec deux autres chantiers du même fil « agent = entité » :
- **Hot-swap de l'AI profile** d'un agent existant (absent à toutes les couches aujourd'hui).
- **Reprise auto des sessions au redémarrage** (terrain T5/T7 + `conversation_id` prêt mais
  non câblé : rien ne relance les agents `agent_was_running` à l'ouverture du projet).

## 6. Livrable attendu

Une cartographie d'architecture pour l'**orchestration v3** : ports & adapters, modèle de
messages (requête/réponse corrélées), capacité runtime MCP, stratégie de repli, découpage en
**lots** testables (méthode §3), et la liste des décisions tranchées avec leur justification.
Mets à jour `ARCHITECTURE.md` (§14.3) en conséquence.