# 📄 agent.md — Mesh Agent (Rust pragmatique)

## 1. Description
**Mesh Agent** est un agent desktop multi-OS (Linux / Windows / macOS) conçu pour compléter Mesh (app web) avec des capacités locales avancées.

Objectifs :
- **Flux lourds P2P** (faible charge serveur)
- **Binaires multi-OS** simples à déployer
- Terminal/SSH partagé robuste
- Partage fichiers/dossiers performant
- Notifications directes Gotify

L’agent communique :
- avec le **Mesh Server** (REST + WebSocket) pour auth/permissions/signalisation,
- avec les **autres clients/agents** en **P2P** pour les flux data,
- avec **Gotify** pour les notifications.

---

## 2. Architecture (control plane vs data plane)
- **Control plane** : Mesh Server
  - Auth
  - Rooms & ACL
  - Tokens de capacités (TTL court)
  - Signalisation (WS)
  - Événements + notifications Gotify
- **Data plane** : P2P
  - Audio/Vidéo/Écran : WebRTC (côté client web)
  - Fichiers/Dossiers/Terminal : P2P via **QUIC** (recommandé V1)
    - fallback possible : WebRTC DataChannel (V2) ou HTTP temporaire (exception)

Le serveur ne transporte pas de média ni de transferts lourds.

---

## 3. Fonctions principales
### 3.1 Partage fichiers & dossiers (P2P)
- Envoi fichier : chunks + reprise + checksum
- Envoi dossier :
  - mode simple : **zip à la volée**
  - mode sync (optionnel) : watcher + manifest + diff
- Débit contrôlé + backpressure

### 3.2 Terminal / SSH share (preview + contrôle)
- L’agent lance une session locale via **PTY** (bash/pwsh) et peut lancer `ssh user@host`.
- Diffuse la sortie terminal en P2P.
- Modes :
  - **preview (lecture seule)** par défaut
  - **take control** (un seul contrôleur à la fois)

### 3.3 Notifications
- Envoi direct vers Gotify (agent → Gotify)
- Notifications OS locales (optionnel V1)

### 3.4 Intégration OS
- Tray icon (optionnel)
- Auto-start (optionnel)
- Identité machine : `device_id`

---

## 4. Stack technique (Rust)
### Runtime / réseau
- **Rust stable**
- **tokio** (async)
- **reqwest** (HTTP)
- **tokio-tungstenite** (WebSocket)
- **quinn** (QUIC P2P) — recommandé pour data plane (fichiers/terminal)

### Terminal
- Unix : **portable-pty** (ou equivalent) pour PTY
- Windows : **ConPTY** (crate dédiée / wrapper)

### FS / sync
- notify (watcher cross-platform)
- hashing (blake3 recommandé)

### Config / logs
- serde + toml/yaml
- tracing + tracing-subscriber

### Packaging
- binaire unique par OS
- install : MSI (Windows), deb/rpm (Linux), dmg/pkg (macOS) — V1/V2

---

## 5. Structure recommandée
```
agent/
  Cargo.toml
  src/
    main.rs
    config/
      mod.rs
    mesh/
      rest.rs
      ws.rs
      types.rs
    p2p/
      mod.rs
      quic/
        endpoint.rs
        protocol.rs
      fallback_http/
        mod.rs
    share/
      file_send.rs
      folder_zip.rs
      folder_sync/
        manifest.rs
        diff.rs
        watcher.rs
    terminal/
      mod.rs
      pty_unix.rs
      conpty_windows.rs
      stream.rs
    notifications/
      gotify.rs
      router.rs
    os/
      autostart.rs
      tray.rs
  tests/
```

---

## 6. Protocole & permissions
- Toutes les actions P2P sont autorisées par **capability tokens** (TTL court), émis par le serveur :
  - `share:file`, `share:folder`, `terminal:view`, `terminal:control`
- Le P2P (QUIC) utilise un **handshake applicatif** :
  - échange d’un token de session (issu du serveur)
  - validation côté pair avant d’accepter un flux

---

## 7. Sécurité (résumé)
- Les secrets SSH ne sortent jamais de la machine partageuse.
- Terminal share : preview-only par défaut.
- Chiffrement transport : QUIC (TLS 1.3), WebSocket/TLS.
- Logs sans contenu sensible.

---

## 8. TODO
### MVP (priorité)
- [ ] Config + identité `device_id`
- [ ] Connexion WS au serveur (auth)
- [ ] Réception events (room, terminal, share)
- [ ] Notifications Gotify
- [ ] Terminal preview (PTY) + stream P2P (QUIC)

### V1
- [ ] Envoi fichier P2P (QUIC)
- [ ] Envoi dossier (zip) P2P
- [ ] Take control terminal (arbitrage via serveur)
- [ ] Diagnostics (mode P2P, erreurs, stats)

### V2
- [ ] Sync dossier (manifest/diff)
- [ ] Tray + autostart multi-OS
- [ ] Fallback HTTP serveur (temporaire) si P2P impossible
- [ ] WebRTC DataChannel agent (si besoin compat)

---

## 9. Améliorations futures
- `.meshignore`
- Diff binaire + dédup
- Chiffrement applicatif E2E optionnel
- Tunnel SSH (TCP-like) au-dessus de QUIC (avancé)

---

## 10. Changelog
```
0.1.0 – Rust agent skeleton (WS + Gotify)
0.2.0 – Terminal share preview (QUIC)
0.3.0 – File transfer (QUIC)
0.4.0 – Folder zip + take control
0.5.0 – Folder sync (beta)
```