# Architecture système — IDE, agents, runtime, mémoire

## Répartition physique (première cible)

Pour le **premier déploiement**, un **poste Linux** (client) établit des sessions **SSH** vers un **serveur** qui concentre :

- Ollama, AnythingLLM (et extensions du socle IA) ;
- les **dépôts** et l’exécution des **agents** / OpenShell sur chemins autorisés.

L’**éditeur** et une partie de l’UX peuvent rester sur le client ; le **gateway**, le **policy-runtime** et les **knowledge-services** (fichiers RAG, workspaces AnythingLLM) sont cohérents **côté serveur**, sauf architecture hybride explicitement documentée. Voir [deployment-target.md](./deployment-target.md).

## Couches fonctionnelles (vue cible)

| Couche | Rôle |
|--------|------|
| **Agents `ia_dev`** | Noyau **métier et opératoire** (existant) ; sous-agents, recettes, tools |
| **OpenShell** | **Sécurité et exécution** : sandboxes, politiques, résolution contrôlée |
| **Éditeur (ex. Lapce)** | **Interaction** : texte léger, terminal, palette, timeline, UX intentionnelle |
| **Orchestrateur maison** | **Routage** : pas « d’intelligence » au sens LLM, mais décision de flux |
| **Ollama** | Backend d’**inférence** locale |
| **AnythingLLM** | **Mémoire documentaire** et RAG ; **un workspace par projet** ([anythingllm-workspaces.md](./anythingllm-workspaces.md)) |
| **ONLYOFFICE** | Backend **documentaire métier** (documents, feuilles, présentations) |

Flux type : demande utilisateur → orchestrateur → préparation (scripts / tools génériques) → agents → besoin LLM → Ollama ; besoin doc / RAG → AnythingLLM ; besoin bureautique → ONLYOFFICE.

## Orchestrateur — décisions de routage

Décider notamment :

- quelle **commande** utilisateur appelle quel **agent principal** ;
- quel agent appelle quel **sous-agent** ;
- quand privilégier un **script** vs un **tool générique** vs `ia_dev` ;
- quand `ia_dev` peut **escalader** vers Ollama ;
- quand interroger **AnythingLLM** ;
- quand passer par **ONLYOFFICE** ;
- quand **refuser**.

## Descripteur stable par agent

Chaque agent devrait exposer au minimum : **nom**, **rôle**, **entrées**, **sorties**, **droits**, **dépendances**, **scripts** appelés, **modèles** éventuels, **préconditions**, **postconditions**, **timeouts**, **coût**, **niveau de risque**.

Un **protocole unique** couvre les implémentations hétérogènes (script, workflow, wrapper d’outil, appel IA).

Hiérarchie agent → sous-agent : à **formaliser** explicitement pour éviter un graphe implicite ingouvernable.

## Événements normalisés (exemples)

`started`, `tool_selected`, `script_started`, `model_called`, `waiting_validation`, `completed`, `failed`, `rolled_back`, `artifact_created`.

Sortie **événementielle uniforme** vers l’éditeur ; **journalisation** ; possibilité de **rejouer**, diagnostiquer, **convertir en recette** stable.

## Sécurité — OpenShell central

- Chaque nouvelle résolution devrait pouvoir devenir **recipe**, **tool** ou **sous-agent** stable (travail des commandes UX de haut niveau).
- Les agents ne devraient **pas** exécuter directement sur l’hôte sans contrôle : **sandboxes** avec droits dérivés du **type d’agent** et du **projet**.

Exemples de **profils de policy** : lecture seule ; lecture + scripts locaux ; écriture bornée ; déploiement pprod / prod ; génération documentaire ; accès tickets ; accès base ; accès ONLYOFFICE.

**Pas de fallback implicite** non spécifié : refus ou erreur explicite selon les règles du projet.

## Couche de normalisation (registre agents)

Registre unifié des agents `ia_dev`, chacun exposé comme **objet standardisé** :

- identité, catégorie, **commandes déclenchantes**, permissions, environnements compatibles, mode d’exécution, outils requis, **politiques OpenShell**, formats d’entrée/sortie, stratégies de rejet (pas de fallback silencieux), journalisation, possibilité d’appeler d’autres agents.

Sans cette couche, l’IDE reste dépendant de **conventions implicites** du dépôt.

## Agent gateway (adaptateur)

Ne pas brancher le dépôt `ia_dev` directement dans l’éditeur : passer par une **agent gateway** qui :

1. Charge le **registre**  
2. **Valide** les permissions  
3. **Résout** les dépendances  
4. Ouvre la **sandbox OpenShell** adaptée  
5. **Injecte** le contexte autorisé  
6. **Lance** l’agent  
7. **Capture** les événements  
8. **Uniformise** les sorties  
9. **Publie** le flux vers l’éditeur  
10. **Journalise**  
11. Gère **rollbacks** et statuts  

## Modules logiciels (découpage)

| Module | Responsabilité |
|--------|----------------|
| **editor-shell** | Éditeur texte léger, terminal, explorer **mode expert**, onglets, palette de commandes, timeline, UX |
| **agent-gateway** | Adaptateur uniforme UX ↔ `ia_dev` |
| **policy-runtime** | OpenShell, profils de policy, providers, sandboxes, journaux |
| **knowledge-services** | AnythingLLM, mémoire projet, index documentaire, routage RAG |
| **doc-services** | ONLYOFFICE, flux `present`, `write`, `sheet` |

Les **agents** restent le noyau opératoire ; les modules encadrent et exposent.

## UX — masquage des agents

L’utilisateur ne « choisit pas un agent » dans le flux nominal : il exprime une **intention** (`ask`, `fix`, …). Le **routeur** sélectionne l’agent ou la chaîne d’agents.

## Socle éditeur : Lapce

**Lapce** (open source, Rust, rendu natif / GPU) est le candidat retenu pour un **éditeur rapide et léger** avec agents, au lieu d’un IDE historique très chargé. Positionnement aligné avec le rôle « coquille + orchestration + transparence contextuelle » décrit dans [ux-navigation-model.md](./ux-navigation-model.md).

## Taxonomie des droits

Les droits doivent être **nommés**, **vérifiables** et **traçables** (lien avec OpenShell et le registre d’agents). Pas de contournement par défaut.

## Mémoire d’exécution

Conserver une mémoire d’exécution **exploitable** : rejouer, auditer, promouvoir une exécution réussie en **recette** versionnée.