agent-manager/ARCHITECTURE.md

# 🏗️ Document d'architecture — agent-manager (`am`)

> Ce document décrit la conception, le fonctionnement et les fonctionnalités de **agent-manager** (binaire `am`), un CLI Rust multiplateforme pour gérer des agents IA de coding locaux.
>
> 📦 Version : `0.6.0` · 🦀 Rust 2021 · ✅ Windows · ✅ Linux · ✅ macOS

---

## 🎯 Vue d'ensemble

`am` est un gestionnaire d'agents IA de coding qui permet de :

- 📋 Découvrir et lister plus de **72 agents** via un catalogue YAML embarqué
- 📦 Les installer avec **9 méthodes** différentes (npm, pip, uv, cargo, go, bun, curl, binaire, git)
- 🚀 Les démarrer, arrêter, redémarrer en avant-plan ou en arrière-plan
- 🔍 Observer leur état, leurs logs, leurs statistiques d'utilisation
- 🛠️ Gérer dépendances, alias, groupes, profils, secrets, favoris et annotations
- ⚡ Exécuter des actions shell via langage naturel avec un agent léger (`am ai`)

Le tout sans toucher au système : chaque agent est installé dans un répertoire utilisateur isolé.

---

## 🧩 Architecture globale

```mermaid
flowchart TB
    subgraph UI["🖥️ Interfaces utilisateur"]
        CLI["Ligne de commande<br/>clap v4"]
        REPL["Shell interactif<br/>rustyline"]
        TUI["Dashboard TUI<br/>ratatui + crossterm"]
        WEB["Dashboard web<br/>tiny_http (127.0.0.1)"]
    end

    subgraph CORE["⚙️ Noyau applicatif"]
        APP["App<br/>contexte partagé"]
        CLI_DEF["cli.rs<br/>définition des commandes"]
        CMD["commands/<br/>dispatch"]
        SHELL_AI["shell_ai.rs<br/>agent shell léger"]
    end

    subgraph DATA["💾 Données persistantes"]
        CONFIG["Configuration YAML<br/>embarquée + utilisateur"]
        CATALOG["Catalog<br/>index agents/alias/groupes"]
        STATE["StateStore<br/>state.json"]
        EVENTS["Journal JSONL<br/>events-YYYYMM.jsonl"]
        CACHE["Probe cache<br/>probe-cache.json"]
    end

    subgraph EXEC["🔧 Exécution"]
        RUNNER["Runner trait<br/>système / mock"]
        INSTALLERS["installers/<br/>9 méthodes"]
        DEPS["deps.rs<br/>vérification dépendances"]
        PROCESS["process.rs<br/>PID / signaux"]
    end

    subgraph OBS["👁️ Observation"]
        PROBE["probe.rs<br/>détection agents externes"]
        DASH["dashboard.rs<br/>agrégation"]
        STATS["stats.rs<br/>statistiques"]
        SESSIONS["sessions.rs<br/>registre sessions"]
    end

    CLI --> APP
    REPL --> APP
    TUI --> APP
    WEB --> APP
    APP --> CLI_DEF
    APP --> SHELL_AI
    APP --> CONFIG
    APP --> CATALOG
    APP --> STATE
    APP --> EVENTS
    APP --> CACHE
    CMD --> RUNNER
    CMD --> INSTALLERS
    CMD --> DEPS
    CMD --> PROCESS
    CMD --> PROBE
    CMD --> DASH
    CMD --> STATS
    CMD --> SESSIONS
    SHELL_AI --> CMD
```

---

## 🚀 Flux d'exécution d'une commande

```mermaid
sequenceDiagram
    autonumber
    participant User
    participant main as main.rs
    participant lib as lib.rs
    participant help as help.rs
    participant cli as cli.rs
    participant app as app.rs
    participant cfg as config.rs
    participant state as state.rs
    participant cmd as commands/mod.rs
    participant impl as commands/xxx_cmd.rs

    User->>main: am install jcode
    main->>lib: main_entry()
    lib->>lib: spawn thread 8 Mo
    lib->>help: intercept(-h/--help) ?
    help-->>lib: None
    lib->>cli: Cli::parse()
    cli-->>lib: Cli { command: Install {...} }
    lib->>app: App::from_cli(cli)
    app->>cfg: load() config embarquée + user
    cfg-->>app: Config
    app->>state: StateStore::new()
    state-->>app: state.json chargé
    app-->>lib: App
    lib->>cmd: commands::execute(&app)
    cmd->>impl: install_cmd::run(...)
    impl->>impl: vérifier dépendances, installer
    impl->>state: persister
    impl->>app: emit(event install)
    impl-->>cmd: Ok(0)
    cmd-->>lib: 0
    lib-->>main: code sortie
```

---

## 📁 Structure du code source

```
src/
├── main.rs              🚪 Point d'entrée
├── lib.rs               🧭 main_entry(), doc du crate
├── cli.rs               📋 Définition clap de toutes les commandes
├── app.rs               🧰 Contexte App (config, state, paths, logger, theme)
├── config.rs            ⚙️ Schéma YAML, chargement, fusion, validation
├── catalog.rs           🔍 Index agents + recherche fuzzy + suggestions
├── catalog_remote.rs    🌐 Catalogues distants (fetch, cache, includes)
├── state.rs             💾 Base JSON des installations et annotations
├── events.rs            📝 Journal d'événements JSONL
├── runner.rs            🏃 Trait d'exécution système / mock
├── process.rs           ⚙️ Lancement, arrêt, signaux des processus
├── deps.rs              ✅ Vérification et auto-installation des dépendances
├── toolchain.rs         🖥️ Détection OS / gestionnaire de paquets
├── download.rs          ⬇️ Téléchargement, checksums, extraction
├── probe.rs             🔎 Détection des agents externes sur le PATH
├── dashboard.rs         📊 Données agrégées du dashboard
├── ps.rs                🧮 Table des processus
├── context.rs           📂 Contexte du projet courant
├── repl.rs              💬 Shell interactif
├── shell.rs             🐚 Gestion des shells supportés
├── help.rs              ❓ Aide Nushell-style
├── output.rs            🖨️ Logger et rendu
├── tables.rs            📋 Rendu tabulaire
├── theme.rs             🎨 Thèmes de couleur (REPL et tableaux)
├── web.rs               🌐 Serveur HTTP local (127.0.0.1) + API JSON + frontend embarqué
├── serve.rs             🚀 API HTTP + WebSocket authentifiée (pilotage à distance, issue #80)
├── frontend/            📄 index.html — dashboard web (HTML5 + CSS + JS vanilla, include_str!)
├── history.rs           ⏪ Historique des commandes
├── sessions.rs          📅 Registre des sessions
├── projects.rs          🗂️️ Agrégation par projet
├── hooks.rs             🪝 Hooks de cycle de vie
├── secrets.rs           🔒 Gestion des secrets (keyring OS)
├── providers.rs         🏷️ Registre de providers LLM (base_url, modèles, défaut, @secret)
├── registry.rs          📦 Registre communautaire de catalogues (manifeste + sha256)
├── ask.rs               💬 Langage naturel → commandes am (règles locales + LLM optionnel)
├── sandbox.rs           🛡️ Profils sandbox par agent (allowlist, périmètre, réseau)
├── telemetry.rs         📈 Télémétrie anonyme opt-in (compteurs agrégés)
├── lab.rs               🧪 Benchmark d'agents (tâches YAML versionnables)
├── playbook.rs          ▶️ Rejeu pas à pas d'une séquence d'historique
├── plugins.rs           🔌 Scripts d'extension sur les événements (contrat JSON)
├── models.rs            🤖 Inventaire des modèles locaux (ollama, llama.cpp, LM Studio)
├── shell_ai.rs          ⚡ Agent shell léger : langage naturel → action shell
├── sync.rs              🔄 Push git de l'état (journal, sessions, config)
├── agent_config.rs      ⚙️ Adaptateurs de configuration post-install (TOML/YAML/JSON/key=value)
├── costs.rs             💰 Coûts estimés par agent (tokens in/out, modèles de prix)
├── automation.rs        ⚙️ Services système + tâches planifiées (systemd/launchd/schtasks)
├── backup.rs            💾 Sauvegardes (update --rollback, migrate)
├── doctor.rs            🩺 Diagnostics environnement + --fix
├── nav.rs               🧭 Tables de navigation (ls/dir)
├── i18n.rs              🌍 Catalogue de traductions FR/EN (--lang, AM_LANG, LANG)
├── version.rs           🏷️ Informations de version
├── commands/            📦 51 modules, un par commande
└── installers/          📦 8 installateurs spécialisés
```

---

## ⚙️ Configuration : catalogue YAML extensible

### Hiérarchie de chargement

```mermaid
flowchart LR
    EMB["📦 config.yaml<br/>embarqué dans le binaire"] --> MERGE["🔀 Fusion"]
    USER["👤 ~/.config/agent-manager/config.yaml"] --> MERGE
    LOCAL["📂 ./agent-manager.yaml"] --> MERGE
    FLAG["⚡ --config <file>"] --> MERGE
    MERGE --> EFFECTIVE["✅ Configuration effective"]
```

Priorité (la plus prioritaire en dernier) :

1. `config.yaml` embarqué (catalogue par défaut, ~72 agents)
2. `~/.config/agent-manager/config.yaml`
3. `./agent-manager.yaml` (configuration locale par projet)
4. `--config <fichier>`

### Schéma de configuration

```yaml
version: "1.0"

settings:
  install_dir: null            # ~/.local/share/agent-manager/agents
  log_dir: null                # ~/.local/state/agent-manager/logs
  default_shell: null          # shell utilisateur par défaut
  auto_install_deps: true      # proposer d'installer les dépendances manquantes
  confirm_before_run: true     # confirmer avant les scripts d'installation
  stop_timeout_secs: 5         # délai SIGTERM → SIGKILL
  self_update_repo: Projets/agent-manager
  self_update_base_url: https://git.dracodev.net/api/v1
  theme: null
  hooks:
    on_install: []
    on_start: []
    on_stop: []
    on_update: []

aliases:
  cc: claude-code
  gemini: antigravity-cli

groups:
  dev: [claude-code, aider, codex]

include:
  - ./extra-agents.yaml

agents:
  - name: claude-code
    display_name: "Claude Code"
    description: "..."
    category: coding-agent
    website: https://github.com/anthropics/claude-code
    install:
      type: npm
      package: "@anthropic-ai/claude-code"
    dependencies:
      - { name: node, min_version: "18.0.0" }
    run: claude
    tags: [anthropic, assistant]

profiles:
  dev:
    agent: claude-code
    env: { API_ENV: dev }
    args: [--verbose]

projects:
  mon-projet:
    root: ~/projets/mon-projet
    default_agent: claude-code
    env: { KEY: value }
```

### Définition d'un agent (`AgentDef`)

| Champ | Description |
|-------|-------------|
| `name` | Identifiant unique (slug) |
| `display_name` | Nom lisible |
| `description` | Description longue |
| `category` | Catégorie (coding-agent, assistant, local-first...) |
| `website` | URL du projet |
| `install` | Spécification d'installation |
| `dependencies` | Outils requis (node, python, go...) avec version min |
| `run` | Commande de lancement |
| `args` | Arguments par défaut |
| `env` | Variables d'environnement par défaut |
| `tags` | Tags pour recherche/filtrage |
| `installable` | `false` pour les agents SaaS/Desktop |
| `platforms` | Restriction `linux`/`macos`/`windows` |

### Méthodes d'installation supportées

| Type | Fichier | Principe |
|------|---------|----------|
| `npm` | `installers/npm.rs` | `npm install -g --prefix <root>` |
| `bun` | `installers/npm.rs` | `bun install -g` |
| `pip` / `uv` | `installers/pipuv.rs` | virtualenv privé dans `install_dir` |
| `cargo` | `installers/cargo.rs` | `cargo install --root` |
| `go` | `installers/golang.rs` | `go install` avec `GOBIN` local |
| `curl` | `installers/script.rs` | Télécharge et exécute un script |
| `binary` | `installers/binary.rs` | Release GitHub/Gitea → extraction archive |
| `git` | `installers/git.rs` | Clone + build + `binary_path` |

---

## 💾 Gestion des états

### `state.json` — base d'installation locale

Format JSON version 3, atomique (écriture `.tmp` + `rename`).

```json
{
  "version": 3,
  "installed": {
    "jcode": {
      "name": "jcode",
      "version": "0.76.0",
      "method": "binary",
      "directory": ".../agents/jcode",
      "binaries": ["jcode"],
      "pid": null,
      "installed_at": "...",
      "updated_at": "..."
    }
  },
  "annotations": {
    "jcode": {
      "favorite": true,
      "note": "mon agent préféré",
      "tags": ["perso"]
    }
  }
}
```

### Journal d'événements JSONL

- Un fichier par mois : `events-YYYYMM.jsonl`
- Append-only, horodaté
- Types d'événements : `start`, `stop`, `run`, `install`, `update`, `uninstall`, `doctor`, `config`, `repl`, `shell`, `annotate`
- Les secrets ne sont jamais journalisés
- Source de vérité pour les statistiques, sessions, projets et timeline

### Cache de sondes

`probe-cache.json` évite de re-scanner le PATH à chaque commande pour détecter les agents externes et leurs versions.

---

## 🛡️ Gestion des dépendances

```mermaid
flowchart LR
    INSTALL["am install jcode"] --> CHECK["deps::check_dep"]
    CHECK --> MISSING{Manquant ?}
    MISSING -->|Oui| DETECT["toolchain::detect OS"]
    DETECT --> COMMANDS["toolchain::install_commands"]
    COMMANDS --> PROMPT["Proposer la commande"]
    PROMPT --> AUTO["Exécuter si --yes"]
    AUTO --> INSTALL2["installers::run_install"]
    MISSING -->|Non| INSTALL2
```

- `deps.rs` vérifie chaque dépendance via `<outil> --version`
- `toolchain.rs` détecte l'OS et le gestionnaire de paquets :
  - Windows : `scoop` → `winget`
  - Linux : `apt` / `dnf` / `pacman` / `apk`
  - macOS : `brew`
- Si `auto_install_deps: true`, `am` propose et peut exécuter la commande d'installation
- Les dépendances de l'agent (modules npm/pip) restent isolées dans le répertoire `install_dir`

---

## ⚡ Gestion des processus

```mermaid
flowchart TB
    START["am start <agent>"] --> MODE{Mode ?}
    MODE -->|Foreground| FG["Attache au terminal<br/>Ctrl-C pour quitter"]
    MODE -->|Background| BG["spawn_background()"]
    BG --> LOG["Redirection stdout/stderr<br/>vers log agent"]
    LOG --> PID["Enregistrement PID<br/>dans state.json"]
    PID --> EVENT["Émission événement start"]

    STOP["am stop <agent>"] --> SIGTERM["SIGTERM"]
    SIGTERM --> WAIT{"Processus terminé ?"}
    WAIT -->|Non| SIGKILL["SIGKILL après timeout"]
    WAIT -->|Oui| CLEAN["PID effacé"]
```

- Démarrage avant-plan (`-f`) ou arrière-plan (`-b`, `--background`)
- Variables d'environnement injectées via `--env KEY=VALUE`
- Secrets via `--env KEY=@secret` (résolu depuis le trousseau OS)
- Arrêt gracieux avec timeout configurable (défaut 5 s)
- Notifications desktop optionnelles (`--notify`)

---

## 📋 Commandes détaillées

### 🔍 Découvrir

| Commande | Description |
|----------|-------------|
| `am list` | Agents installés + détectés sur le PATH |
| `am list --all` | Tout le catalogue avec état |
| `am search <mot>` | Recherche fuzzy avec suggestions |
| `am info <agent>` | Fiche détaillée |
| `am status [agent]` | État, version, PID, logs |

### 📦 Cycle de vie

| Commande | Description |
|----------|-------------|
| `am install <agent>` | Installe un agent et ses dépendances |
| `am install <agent> --method pip` | Choisit la méthode |
| `am uninstall <agent> [--purge]` | Désinstalle et nettoie |
| `am update <agent>` / `--all` | Met à jour |
| `am start [agent]` | Lance en avant-plan |
| `am start <agent> -b` | Lance en arrière-plan |
| `am stop <agent>` | Arrêt gracieux |
| `am restart <agent>` | Redémarrage |
| `am run <agent> [args...]` | Exécution directe sans gestion de PID |

### 👁️ Observer

| Commande | Description |
|----------|-------------|
| `am logs <agent>` | Tail du log agent |
| `am log [agent]` | Journal des événements `am` |
| `am timeline` | Vue chronologique unifiée |
| `am sessions [agent]` | Registre des sessions |
| `am stats [agent] --period 7d` | Statistiques d'utilisation |
| `am top --period 30d` | Top 10 agents |
| `am report --last-week` | Rapport markdown |
| `am projects [nom]` | Agents par projet |
| `am dashboard` | Dashboard TUI temps réel |
| `am watch <agent> --restart` | Supervision et relance automatique |

### 🎯 Personnaliser

| Commande | Description |
|----------|-------------|
| `am favorite <agent>` | Marquer comme favori |
| `am note <agent> <texte>` | Ajouter une note |
| `am tag <agent> <tag>` | Taguer |
| `am tags [agent]` | Lister les tags |
| `am profile list/show <name>` | Profils d'environnement |
| `am alias add <nom> <cible>` | Créer un alias |
| `am secret set <nom> --agent <a> --value <v>` | Secret dans le trousseau |

### 🛠️ Système

| Commande | Description |
|----------|-------------|
| `am doctor [--fix]` | Diagnostic environnement |
| `am config show/path/edit/validate/set` | Gestion config |
| `am completion <shell>` | Script de complétion |
| `am man [commande]` | Page de manuel |
| `am open <agent>` | Ouvrir le répertoire d'installation |
| `am export/import` | Sauvegarde/restauration |
| `am self-update [--check]` | Mise à jour de `am` |
| `am self-uninstall` | Désinstallation complète |
| `am version` | Version et build |
| `am` (sans commande) | REPL interactif |

### 🤖 Copilote & plateforme (v0.7.0 / v1.0)

| Commande | Description |
|----------|-------------|
| `am ask "<demande>"` | Langage naturel → commande(s) am : règles locales FR/EN hors-ligne, raffinement LLM optionnel (`settings.ask`), confirmation avant exécution |
| `am providers list/add/remove/set-token` | Registre LLM centralisé (base_url, modèles, clé par provider au keyring, résolution `@secret`) |
| `am registry publish/search/install` | Registre communautaire de catalogues (Gitea, manifeste + checksum sha256 vérifié) |
| `am serve --token [--port]` | API HTTP + WebSocket authentifiée : stats, run, start, stop, ask — rate limiting par IP, TLS derrière reverse proxy |
| `am web [--port]` | Dashboard web local en lecture seule (127.0.0.1), contrats `--json` réutilisés |
| `am ai "<prompt>" [--exec] [--files <path>]` | **Shell AI** : langage naturel → commande/action shell via agent léger (AIChat) ; `--dry-run` par défaut, confirmation avant exécution |
| `am lab --agents a,b --task <f>` | Benchmark comparatif (durée, exit, coût) sur tâches YAML versionnables |
| `am sync [--message]` | Sauvegarde git de l'état (journal, sessions, config — secrets exclus) |
| `am migrate export/import` | Bundle de transfert machine A → B (config + état + historique) |
| `am schedule add/list/remove/run` | Planification de commandes am (cron / Task Scheduler, issue #56) |
| `am service install <agent>` | Service système (systemd / launchd / tâche Windows, autostart) |
| `am monitor [--json]` | TUI temps réel des processus gérés (CPU/RSS/uptime) + alertes de seuils |
| `am models [--prune]` | Inventaire des modèles locaux (ollama, llama.cpp, LM Studio) |
| `am audit` | Qui a modifié quoi, quand (checksums config + journal) |
| `am plugins [--test <nom>]` | Scripts d'extension sur les événements (contrat JSON stdin/stdout) |

---

## 🌐 Options globales

Disponibles avant ou après la sous-commande.

| Option | Effet |
|--------|-------|
| `-c, --config <FILE>` | Fichier de configuration alternatif |
| `-v, --verbose` | Affiche chaque commande exécutée |
| `-q, --quiet` | Seules les erreurs sont affichées |
| `-y, --yes` | Oui à toutes les confirmations |
| `--dry-run` | Simulation sans modification |
| `--json` | Sortie JSON structurée |
| `--no-color` | Désactive les couleurs |
| `--theme <THEME>` | Thème de couleur |

---

## 🎨 Fonctionnalités avancées

### Alias

```yaml
aliases:
  cc: claude-code
  gemini: antigravity-cli
```

`am start cc` démarre `claude-code`.

### Groupes

```yaml
groups:
  dev: [claude-code, aider, codex]
```

`am start group:dev` démarre tous les agents du groupe en arrière-plan.

### Profils d'environnement

```yaml
profiles:
  dev:
    agent: claude-code
    env: { API_ENV: dev }
    args: [--verbose]
```

`am start --profile dev` lance `claude-code` avec les variables et arguments du profil.

### Projets

```yaml
projects:
  mon-projet:
    root: ~/projets/mon-projet
    default_agent: claude-code
```

Dans le répertoire du projet, `am start` sans argument lance l'agent par défaut du projet.

### Secrets

Les secrets sont stockés dans le trousseau du système d'exploitation (via `keyring`), jamais en clair dans la config.

```bash
am secret set OPENAI_API_KEY --agent claude-code --value sk-...
am start claude-code --env OPENAI_API_KEY=@secret
```

### Hooks

Commandes exécutées automatiquement aux étapes clés du cycle de vie :

- `on_install`
- `on_start`
- `on_stop`
- `on_update`

Définissables globalement dans `settings.hooks` ou par projet.

### Shell interactif (REPL)

Lancé par `am` sans sous-commande :

- Complétion Tab personnalisée (commandes, agents, alias, groupes, flags, shells, thèmes)
- Historique des commandes
- Passerelle système : commandes inconnues exécutées dans le shell actif
- Commandes internes : `ls`, `dir`, `cd`, `ps`, `where`, `get`, `shell`, `theme`, `exit`, `/help`
- Bannière ASCII art

---

## 📊 Dashboard TUI

```mermaid
flowchart LR
    DASH["am dashboard"] --> OVER["Overview"]
    DASH --> ACT["Activité"]
    DASH --> STATS["Statistiques"]
    DASH --> SESS["Sessions"]
    DASH --> PROJ["Projets"]
```

- Navigation : `Tab` / `←` / `→` pour les onglets
- Défilement : `j` / `k` ou flèches
- Quitter : `q`
- Données agrégées depuis `state.json`, le journal d'événements, les sessions et les projets

---

## 🧪 Tests

### Organisation

- **Tests unitaires** : dans chaque module `src/*.rs` sous `#[cfg(test)]`
- **Tests d'intégration** : dans `tests/`

### Fichiers de tests notables

| Fichier | Couverture |
|---------|------------|
| `annotations_test.rs` | Favoris, notes, tags |
| `config_test.rs` | Chargement/validation/fusion |
| `dashboard_test.rs` | Dashboard |
| `doctor_test.rs` | `am doctor` |
| `dry_run_test.rs` | Mode `--dry-run` |
| `events_test.rs` | Journal d'événements |
| `history_test.rs` | Historique |
| `process_test.rs` | Processus |
| `profiles_test.rs` | Profils |
| `projects_test.rs` | Projets |
| `sessions_test.rs` | Sessions |
| `stats_test.rs` | Statistiques |

Lancer les tests :

```bash
cargo test
```

---

## 📦 Packaging et distribution

```
dist/                    Binaires précompilés
├── am-linux-x86_64
├── am-linux-aarch64
├── am-windows-x86_64.zip
├── am_0.4.3_amd64.deb
└── ...

packaging/              Scripts de packaging
├── deb/
├── rpm/
├── homebrew/
├── scoop/
└── winget/

completions/            Scripts de complétion
├── _am                 zsh
├── _am.ps1             PowerShell
├── am.bash             bash
├── am.elv              elvish
└── am.fish             fish

man/                    Pages de manuel générées
```

- `build.rs` enregistre le commit et la branche git pour `am version`
- `scripts/build-release.ps1` construit les releases multiplateformes
- `scripts/render-manifests.ps1` génère les manifests de packaging

---

## 🗂️️ Arborescence des données utilisateur

### Windows

```
%LOCALAPPDATA%\agent-manager\
├── agents\              installations
├── logs\                logs agents
└── state\               state.json, events-*.jsonl, probe-cache.json
```

### Linux

```
~/.local/share/agent-manager/   données
~/.local/state/agent-manager/   logs, state, events, cache
~/.config/agent-manager/        config.yaml
```

### macOS

```
~/Library/Application Support/agent-manager/   données
~/.local/state/agent-manager/                  logs, state, events, cache
~/.config/agent-manager/                       config.yaml
```

Variables d'environnement de débogage/test :

- `AGENT_MANAGER_DATA` : remplace le répertoire de données
- `AGENT_MANAGER_STATE` : remplace le répertoire d'état

---

## 🔐 Sécurité

- Mode `--dry-run` universel pour simuler sans modifier
- Checksums `sha256` pour les binaires téléchargés
- Confirmation avant exécution des scripts d'installation
- Secrets dans le trousseau OS, jamais dans les logs ni le journal
- Installation isolée : aucune modification système

---

## 🔁 Résumé du flux de données

```mermaid
flowchart LR
    CONFIG["📄 YAML config"] --> CATALOG["📚 Catalog"]
    CATALOG --> INSTALL["📦 Installateurs"]
    INSTALL --> STATE["💾 state.json"]
    STATE --> PROCESS["⚙️ Processus"]
    PROCESS --> EVENTS["📝 Journal JSONL"]
    EVENTS --> STATS["📊 Stats / Dashboard"]
    EVENTS --> SESSIONS["📅 Sessions"]
    EVENTS --> PROJECTS["🗂️️ Projets"]
```

---

## ⚡ Shell AI

`am ai` (alias `am shell`) est une commande dédiée aux **actions shell via langage naturel**. Elle repose sur un agent léger (par défaut **AIChat**, installé comme n'importe quel autre agent via le catalogue) et réutilise le registre de providers LLM (`providers.rs`) pour choisir le modèle le plus rapide/cheap.

### Flux d'exécution

```mermaid
sequenceDiagram
    autonumber
    participant User
    participant cli as cli.rs
    participant shell_ai as shell_ai.rs
    participant catalog as catalog.rs
    participant providers as providers.rs
    participant runner as runner.rs
    participant aichat as aichat (agent)

    User->>cli: am ai "traite les JSON"
    cli->>shell_ai: parse args (--exec, --files)
    shell_ai->>catalog: agent "aichat" installé ?
    catalog-->>shell_ai: Ok / install
    shell_ai->>providers: provider & modèle par défaut
    providers-->>shell_ai: config (ollama / cheap cloud)
    shell_ai->>shell_ai: injecte cwd + fichiers (--files)
    shell_ai->>runner: exec aichat -f . -e "..."
    runner->>aichat: lancement processus
    aichat-->>runner: commande générée / exécutée
    runner-->>shell_ai: output + exit code
    shell_ai->>shell_ai: journalise événement shell_ai
    shell_ai-->>User: résultat ou confirmation
```

### Sécurité

| Règle | Détail |
|---|---|
| `--dry-run` par défaut | Aucune commande modifiante n'est exécutée sans confirmation |
| Classification risk/certainty | Inspiré d'AI CLI : chaque commande est classée `safe` ou `risky` |
| Confirmation utilisateur | Les commandes `risky` demandent une validation explicite |
| Mode local possible | Support d'Ollama via `providers.rs` pour ne pas sortir les données |

### Dépendances

- `src/shell_ai.rs` : parsing du prompt, gestion des flags, appel à l'agent
- `src/providers.rs` : résolution du provider/modèle
- `src/runner.rs` : exécution du binaire `aichat`
- `src/events.rs` : journalisation `shell_ai` dans le journal JSONL
- `config.yaml` : définition de l'agent `aichat` + alias `ai`

---

## 📚 Références

- `src/lib.rs:4` : documentation d'architecture du crate
- `src/cli.rs:24` : options globales
- `src/cli.rs:61` : énumération des commandes
- `src/app.rs:16` : struct `App`
- `src/config.rs:25` : struct `Config`
- `src/config.rs:148` : struct `AgentDef`
- `src/config.rs:241` : enum `InstallType`
- `src/state.rs:12` : struct `StateFile`
- `src/events.rs:57` : struct `Event`
- `README.md` : documentation utilisateur complète

---

*Document généré pour agent-manager v0.4.3* 🚀