Gilles Soulier
307 lines
7.9 KiB
Markdown
307 lines
7.9 KiB
Markdown
# Livrables — Agent Rust
|
||
|
||
Ce document contient :
|
||
|
||
1. le fichier `agent/CLAUDE.md`
|
||
2. un prompt Codex initial pour générer le squelette compilable de `agent/`
|
||
|
||
---
|
||
|
||
## 1) `agent/CLAUDE.md`
|
||
|
||
```markdown
|
||
# CLAUDE.md — Mesh Agent (Rust)
|
||
|
||
## Portée
|
||
Ce fichier s’applique **uniquement** au code situé dans `agent/`.
|
||
Il complète le `CLAUDE.md` racine (vision/architecture). En cas de conflit, le `CLAUDE.md` racine prime.
|
||
|
||
---
|
||
|
||
## Objectifs de l’agent
|
||
- Multi-OS (Linux, Windows, macOS)
|
||
- Faible charge serveur : le serveur ne transporte pas de flux lourds
|
||
- Data-plane performant :
|
||
- **QUIC (TLS 1.3)** pour fichiers/dossiers/terminal
|
||
- fallback HTTP temporaire (exceptionnel)
|
||
- Terminal share robuste via PTY (preview par défaut)
|
||
- Notifications directes Gotify
|
||
|
||
---
|
||
|
||
## Rappels d’architecture
|
||
- Control plane : Mesh Server (REST + WS)
|
||
- auth, rooms, ACL
|
||
- capability tokens TTL court
|
||
- orchestration des sessions P2P
|
||
- Data plane : agent ↔ agent
|
||
- QUIC via `quinn`
|
||
- handshake applicatif obligatoire `P2P_HELLO`
|
||
|
||
---
|
||
|
||
## Règles de sécurité (non négociables)
|
||
- Aucun contournement des capability tokens.
|
||
- Terminal : **preview-only** par défaut.
|
||
- Input distant uniquement si :
|
||
1) serveur a accordé `terminal:control`
|
||
2) l’agent propriétaire confirme/maintient le contrôleur actif
|
||
- Ne jamais exfiltrer : clés SSH, mots de passe, variables secrètes.
|
||
- Logs sans contenu sensible (pas de contenu de terminal en clair dans les logs).
|
||
|
||
---
|
||
|
||
## Contraintes de code Rust
|
||
- Rust stable
|
||
- Async : `tokio`
|
||
- HTTP : `reqwest`
|
||
- WebSocket : `tokio-tungstenite`
|
||
- QUIC : `quinn`
|
||
- Config : `serde` + `toml` (ou yaml)
|
||
- Logs : `tracing`
|
||
|
||
Qualité :
|
||
- Interdiction de `unwrap()` / `expect()` en code final
|
||
- Erreurs explicites (`Result`) + `thiserror` recommandé
|
||
- Tests stubs acceptés, mais structure prête
|
||
|
||
---
|
||
|
||
## Structure obligatoire du dossier
|
||
Ne pas renommer arbitrairement.
|
||
|
||
```
|
||
|
||
agent/ Cargo.toml src/ main.rs config/ mesh/ p2p/ quic/ share/ terminal/ notifications/ os/ tests/
|
||
|
||
```
|
||
|
||
---
|
||
|
||
## Développement : ordre recommandé
|
||
1) **Squelette compilable** + config + logs
|
||
2) Client Mesh (REST + WS)
|
||
3) Notifications Gotify (agent → gotify)
|
||
4) Terminal preview via PTY (local) + stream (transport abstrait)
|
||
5) QUIC : endpoint + handshake `P2P_HELLO`
|
||
6) Terminal preview sur QUIC
|
||
7) File transfer sur QUIC
|
||
8) Folder zip sur QUIC
|
||
9) Terminal take-control (arbitrage via serveur)
|
||
|
||
---
|
||
|
||
## Consigne de suivi d’avancement
|
||
À chaque jalon significatif **ou** vers ~80 % d’une session de travail, produire :
|
||
|
||
```
|
||
|
||
ÉTAT D’AVANCEMENT – Mesh Agent ✔ Terminé :
|
||
|
||
- ... ◻ En cours :
|
||
- ... ✖ À faire :
|
||
- ... Risques / points bloquants :
|
||
- ... Prochaine action recommandée :
|
||
- ...
|
||
|
||
```
|
||
|
||
---
|
||
|
||
## Gestion du contexte (pour Claude)
|
||
- Utiliser `/clear` entre tâches distinctes.
|
||
- Pour revue sécurité/perf : utiliser un sous-agent.
|
||
|
||
Le contexte durable doit rester dans :
|
||
- `CLAUDE.md` (racine)
|
||
- ce `agent/CLAUDE.md`
|
||
- `docs/`.
|
||
```
|
||
|
||
---
|
||
|
||
## 2) Prompt Codex initial — squelette compilable `agent/`
|
||
|
||
```markdown
|
||
# Codex Prompt — Mesh Agent (Rust) : Skeleton compilable (étape 1)
|
||
|
||
Contexte
|
||
- Projet Mesh : server Python (control plane), client web, agent Rust (data plane QUIC).
|
||
- Références : `CLAUDE.md` racine + `agent.md` + `agent/CLAUDE.md`.
|
||
|
||
Objectif
|
||
- Générer un squelette **compilable** du dossier `agent/` (Rust stable) avec la structure imposée.
|
||
- Aucun code “tout-en-un”. Travail en modules minimalistes.
|
||
|
||
Règles
|
||
- Rust stable, tokio, tracing.
|
||
- Pas de unwrap/expect dans le code final.
|
||
- Erreurs via Result + thiserror.
|
||
- Config via serde + toml.
|
||
|
||
Livrables attendus
|
||
1) `agent/Cargo.toml` avec dépendances minimales : tokio, tracing, tracing-subscriber, serde, toml, reqwest, tokio-tungstenite, thiserror.
|
||
2) Arborescence `src/` avec modules vides mais raccordés :
|
||
- config/
|
||
- mesh/ (rest.rs, ws.rs, types.rs)
|
||
- notifications/ (gotify.rs, router.rs)
|
||
- terminal/ (mod.rs, stream.rs)
|
||
- p2p/quic/ (endpoint.rs, protocol.rs)
|
||
- share/ (file_send.rs, folder_zip.rs)
|
||
- os/ (autostart.rs, tray.rs)
|
||
3) `src/main.rs` :
|
||
- charge config
|
||
- init tracing
|
||
- démarre runtime tokio
|
||
- affiche un log “agent started”
|
||
4) `agent/README.md` : commandes build/run
|
||
5) `agent/.env.example` (si utile) + `config.example.toml`
|
||
|
||
Ne pas implémenter la logique QUIC/WS complète maintenant : uniquement les stubs d’API et la compilation.
|
||
|
||
Stop
|
||
- Quand tout compile (`cargo build`), terminer et fournir un court résumé des fichiers créés.
|
||
- Si tu estimes être à ~80 % de l’objectif, produire un état d’avancement au format imposé avant d’aller plus loin.
|
||
```
|
||
|
||
|
||
|
||
---
|
||
|
||
## Traçabilité des modifications de code (obligatoire)
|
||
|
||
Chaque **agent (Claude principal, sous-agent, Codex, ou autre)** qui **crée ou modifie du code** doit **explicitement l’indiquer dans les fichiers concernés**.
|
||
|
||
### Règles de traçabilité
|
||
|
||
- **Tout fichier créé** doit contenir un commentaire en **début de fichier** indiquant :
|
||
|
||
- l’agent auteur,
|
||
- la date,
|
||
- l’objectif de la création.
|
||
|
||
- **Toute modification d’un fichier existant** doit être signalée :
|
||
|
||
- soit par un commentaire en **début de fichier** (si modification importante),
|
||
- soit par un commentaire **en fin de ligne** ou à proximité immédiate du changement (si modification ponctuelle).
|
||
|
||
### Format imposé des commentaires
|
||
|
||
#### Création de fichier
|
||
|
||
```text
|
||
// Created by: <agent_name>
|
||
// Date: YYYY-MM-DD
|
||
// Purpose: <short description>
|
||
```
|
||
|
||
#### Modification de fichier
|
||
|
||
```text
|
||
// Modified by: <agent_name> — YYYY-MM-DD — <reason>
|
||
```
|
||
|
||
Le format exact peut être adapté au langage (Rust, Python, TypeScript…), mais **les informations doivent toujours être présentes**.
|
||
|
||
### Agents concernés
|
||
|
||
Cette règle s’applique à :
|
||
|
||
- Claude (agent principal),
|
||
- tous les **sous-agents**,
|
||
- **Codex** ou tout autre générateur de code,
|
||
- toute automatisation produisant ou modifiant des fichiers.
|
||
|
||
### Objectif
|
||
|
||
- garantir une **traçabilité claire** des décisions et des changements,
|
||
- faciliter les revues (sécurité, performance, architecture),
|
||
- permettre de comprendre rapidement **qui a fait quoi et pourquoi**.
|
||
|
||
Cette consigne est **obligatoire et non optionnelle** pour le projet Mesh.
|
||
|
||
|
||
|
||
---
|
||
|
||
## Traçabilité des modifications de code (obligatoire)
|
||
|
||
Toute **création ou modification de code** réalisée pour l’agent Mesh doit indiquer **explicitement l’agent auteur**.
|
||
|
||
### Règles
|
||
|
||
- **Création de fichier** : commentaire en début de fichier.
|
||
- **Modification importante** : commentaire en début de fichier.
|
||
- **Modification ponctuelle** : commentaire en fin de ligne ou à proximité immédiate.
|
||
|
||
### Formats imposés (à adapter au langage)
|
||
|
||
**Création**
|
||
|
||
```text
|
||
// Created by: <agent_name>
|
||
// Date: YYYY-MM-DD
|
||
// Purpose: <short description>
|
||
```
|
||
|
||
**Modification**
|
||
|
||
```text
|
||
// Modified by: <agent_name> — YYYY-MM-DD — <reason>
|
||
```
|
||
|
||
### Agents concernés
|
||
|
||
- Claude (principal)
|
||
- Sous-agents
|
||
- Codex / générateurs de code
|
||
|
||
### Objectif
|
||
|
||
Garantir une **traçabilité claire** (qui / quand / pourquoi) pour les revues sécurité, performance et maintenance.
|
||
|
||
Cette règle est **non optionnelle** pour l’agent Mesh.
|
||
|
||
|
||
|
||
---
|
||
|
||
## Traçabilité des modifications de code (obligatoire — Agent)
|
||
|
||
Cette règle s’applique **spécifiquement au dossier **`` et est prioritaire pour Codex.
|
||
|
||
### Exigences
|
||
|
||
- Chaque agent (Claude, sous-agent, Codex) doit **signer ses créations et modifications**.
|
||
- Aucune PR ou génération de code n’est valide sans cette signature.
|
||
|
||
### Formats
|
||
|
||
**Création de fichier**
|
||
|
||
```text
|
||
// Created by: <agent_name>
|
||
// Date: YYYY-MM-DD
|
||
// Purpose: <short description>
|
||
```
|
||
|
||
**Modification**
|
||
|
||
```text
|
||
// Modified by: <agent_name> — YYYY-MM-DD — <reason>
|
||
```
|
||
|
||
### Placement
|
||
|
||
- Début de fichier : création ou refactor majeur.
|
||
- Fin de ligne / bloc : correction ponctuelle.
|
||
|
||
### Objectif
|
||
|
||
- Auditabilité
|
||
- Revue facilitée
|
||
- Historique lisible sans dépendre des commits
|
||
|
||
Cette consigne est **obligatoire** pour toute génération de code dans `agent/`.
|
||
|