# 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: // Date: YYYY-MM-DD // Purpose: ``` #### Modification de fichier ```text // Modified by: — YYYY-MM-DD — ``` 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: // Date: YYYY-MM-DD // Purpose: ``` **Modification** ```text // Modified by: — YYYY-MM-DD — ``` ### 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: // Date: YYYY-MM-DD // Purpose: ``` **Modification** ```text // Modified by: — YYYY-MM-DD — ``` ### 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/`.