# Phase 1 : squelette sécurisé, instance de test — plan d'implémentation > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal :** une conversation LibreDesk étiquetée `tri:diagnostic` reçoit, sur l'instance de test, une note privée « Brouillon IA » écrite par les agents support et analyste, avec ses étiquettes d'état, sans qu'aucun message sortant n'apparaisse. **Architecture :** un point d'entrée non interactif, `python -m support_diagnostic.run`, lit les conversations éligibles par l'API LibreDesk, passe chaque mail aux agents existants (copiés de `Support-Agent/API/`, sortie mail), et seul ce code déterministe écrit dans LibreDesk : une note privée et des étiquettes, par un client restreint. L'état vit dans les étiquettes. Un workflow Gitea le lance à la main. **Tech Stack :** Python ≥ 3.12, bibliothèque standard (urllib, http.server, unittest) ; `anthropic`, `langsmith`, `matplotlib` pour les agents copiés ; Docker Compose pour l'instance de test ; Gitea Actions. **Spec :** `docs/spec.md` (§1, §6.2, §7, §8 S1, §9) ; constats de la phase 0 : `docs/verifications.md`. ## Global Constraints - **Aucun message ne part au client** (spec §1). Le seul `POST …/messages` du dépôt est dans `LibreDesk.note_privee`, avec `"private": True` en dur, `"sender_type": "agent"`, jamais `to`, `cc`, `bcc`. - Les agents LLM n'écrivent jamais dans LibreDesk : ils reçoivent du texte, rendent du texte (spec §7.4). - `DRY_RUN` : seule la valeur exacte `false` permet d'écrire ; absente ou toute autre valeur, rien n'est écrit (spec §7.5). - Écrire exige aussi `ALLOWED_CONVERSATION_IDS` non vide : des uuid séparés par des virgules, ou `*` pour toutes (spec §7.6). - `MAX_CONVERSATIONS_PER_RUN` : défaut `3` (spec §7.7). - `KILL_SWITCH` non vide et différent de `false` et `0` : sortie immédiate, code 0, rien lu ni écrit (spec §7.8). - Le compte technique a le rôle « Agent IA » : `conversations:read`, `conversations:read_all`, `messages:read`, `messages:write_private`, `conversations:update_tags`, et rien d'autre (verifications.md, point 1). - Étiquettes, toujours avec `action` `add_tags` ou `remove_tags`, jamais `set_tags` ni sans `action` (sans, LibreDesk remplace toutes les étiquettes). - Contrat d'étiquettes (à confirmer par Maxime à la revue du plan) : `tri:diagnostic`, `diag:en-cours`, `diag:fait`, `diag:erreur`, `diag:ignore`, `diag:relancer`. Éligible : `tri:diagnostic` présent et (aucune `diag:*` ou `diag:relancer` présente). - En-tête de chaque note, mot pour mot : `🤖 BROUILLON IA — à relire, ne pas envoyer tel quel`. Pas de mention `@agent` (spec §7.11, §7.12). - Langue : code et documents en français, comme `Support-Agent`. - Le runner Gitea : son label est inconnu (verifications.md, Gitea) ; les workflows portent `runs-on: ubuntu-latest` jusqu'à ce que Maxime donne le label. ## Hors de ce plan - Phase 2 et au-delà : la planification (cron), la production. - **Les données des stations sur le runner** (verifications.md, point 6) : en phase 1, le diagnostic réel tourne sur le poste avec `AIMSIGHT_DATA=~/Support-Agent/data` ; le workflow ne fait qu'un passage à blanc. À décider avant la phase 2. De même : en phase 2, un cron en simulation, qui n'écrit pas d'étiquette, rediagnostiquerait les mêmes conversations à chaque passage. - Les verrous orphelins (`diag:en-cours` laissé par un runner tué, spec §9.3) : un humain retire l'étiquette ; marqué `ponytail:` dans le code. - `supprimer_note` (spec §7.2) : inutile tant que l'instance de test se remet à zéro par `docker compose down -v`. - Le nom du site → la station (Crissier = LENZSPITZE) : le support le déduit du mail, ou le demande, et sa question devient la note (`diag:ignore`). ## Review Focus 1. Une conversation porte déjà une étiquette d'un humain (`urgent`) : nos opérations ne la retirent jamais. → Tâche 2, `test_etiqueter_n_envoie_jamais_set`. 2. La réponse de LibreDesk à la note n'est pas une note privée (changement d'API, 200 sans `private: true`) : tout s'arrête, plus rien n'est écrit. → Tâches 2 et 4, `test_note_non_privee_leve_garde`, `test_garde_arrete_tout`. 3. Les agents échouent au milieu d'une conversation : `diag:en-cours` est retiré, `diag:erreur` posé, la suivante est traitée. → Tâche 4, `test_erreur_passe_a_la_suivante`. 4. Relance (`diag:relancer`) d'une conversation où figure déjà notre note : notre note n'entre ni dans le mail ni dans le contexte ; les notes privées des humains entrent dans le contexte. → Tâche 4, `test_relance_ecarte_nos_notes`. 5. Mail du client vide (image seule, HTML sans texte) : pas d'appel aux agents, `diag:ignore` et une note qui le dit. → Tâche 4, `test_mail_vide_ignore`. --- ## Structure ``` Support-AI/ agents/ copie de Support-Agent/API/ (prompts, knowledge, tools sans typst/, support/), PROVENANCE.md support_diagnostic/ __init__.py libredesk.py le client restreint (seul à parler à LibreDesk) diagnostic.py l'adaptateur vers agents/support/seance.py run.py la configuration, le cycle, la note tests/ faux_libredesk.py un faux LibreDesk (http.server) qui enregistre les requêtes test_libredesk.py test_garde_fou.py test_diagnostic.py test_run.py test_instance.py intégration, sautée sans LIBREDESK_TEST_URL instance-de-test/ docker-compose.yml, verifier.py (phase 0), preparer.py .gitea/workflows/tests.yml, diagnostic.yml requirements.txt, .gitignore, README.md ``` Tests : `python -m unittest discover -s tests -v` depuis la racine. --- ### Task 1 : la copie des agents **Files :** - Create : `agents/` (copie), `agents/PROVENANCE.md`, `requirements.txt`, `.gitignore` **Interfaces :** - Produces : `agents/support/seance.py` (`Seance`, `CASES`), `agents/support/agent.py`, inchangés ; `requirements.txt`. - [ ] **Step 1 : copier** `Support-Agent/API/` vers `agents/`, sans `cases/`, `docs/`, `.venv/`, `.env`, `__pycache__/`, `tools/typst/` (la sortie PDF n'est pas utilisée). `agents/PROVENANCE.md` : la provenance de `API/PROVENANCE.md`, plus une ligne « `Support-Agent/API/` → `agents/`, commit ``, 2026-11-09, sans `tools/typst/` ni `cases/` ». - [ ] **Step 2 : `requirements.txt`** = celui de `API/` (`anthropic`, `langsmith`, `matplotlib`). `.gitignore` : `.venv/`, `__pycache__/`, `.env`, `cases/`, `instance-de-test/config.toml`, `instance-de-test/uploads/`. - [ ] **Step 3 : vérifier que le prompt du support se construit sans la PDF** Run : `python3 -m venv .venv && .venv/bin/pip install -r requirements.txt && .venv/bin/python -c "import sys; sys.path.insert(0,'agents/support'); import seance; print(len(seance.systeme('support','mail')), len(seance.systeme('analyste')))"` Expected : deux nombres > 10000, pas d'exception. - [ ] **Step 4 : commit** `git add agents requirements.txt .gitignore && git commit -m "Copie des agents de Support-Agent/API (sortie mail)"` --- ### Task 2 : le client LibreDesk restreint **Files :** - Create : `support_diagnostic/__init__.py` (vide), `support_diagnostic/libredesk.py`, `tests/faux_libredesk.py`, `tests/test_libredesk.py`, `tests/test_garde_fou.py` **Interfaces :** - Produces : - `class Garde(Exception)` : anomalie du garde-fou d'envoi ; l'appelant arrête toute l'exécution. - `class LibreDesk(url: str, cle: str, secret: str, ecrire: bool)` ; en-tête `Authorization: token :` ; timeout 30 s. - `moi() -> int` : l'id du compte technique (`GET /api/v1/agents/me`). - `ids_etiquettes() -> dict[str, int]` (`GET /api/v1/tags`). - `conversations(avec: int) -> list[dict]` : toutes les pages de `GET /api/v1/conversations/all?page_size=50&filters=…` avec le filtre `{"model":"conversations","field":"tags","operator":"contains","value":"[]"}`. - `etiquettes(uuid: str) -> list[str]` (`GET /api/v1/conversations/{uuid}` → `tags`). - `messages(uuid: str) -> list[dict]` (`GET …/messages?page_size=500`). - `piece(url: str) -> bytes`. - `etiqueter(uuid: str, ajouter: list[str] = (), retirer: list[str] = ()) -> None` : un `POST …/tags` par action non vide ; si `ecrire` est faux, journalise et ne fait rien ; après un ajout, relit `etiquettes(uuid)` et lève `RuntimeError` s'il en manque une (LibreDesk ignore en silence une étiquette inconnue). - `note_privee(uuid: str, html: str) -> dict | None` : si `ecrire` est faux, journalise `[simulation] note pour ` puis le html, rend `None` ; sinon `POST …/messages` avec exactement `{"message": html, "private": True, "sender_type": "agent"}`, et lève `Garde` si la réponse n'a pas `private is True`. - Aucune autre méthode qui écrit ; pas de méthode de requête générique publique. - [ ] **Step 1 : le faux LibreDesk.** `tests/faux_libredesk.py` : `FauxLibreDesk()` démarre un `ThreadingHTTPServer` sur `127.0.0.1:0` ; `.url` ; `.requetes : list[tuple[str, str, dict | None]]` (méthode, chemin avec la requête, corps JSON) ; `.reponses : dict[tuple[str, str], object]` (méthode, chemin sans la requête → la valeur de `data`, ou un `int` pour un code d'erreur) ; `.arreter()`. - [ ] **Step 2 : les tests qui échouent**, dans `tests/test_libredesk.py` : ```python def test_note_privee_envoie_exactement_le_corps_fige(self): self.faux.reponses[("POST", "/api/v1/conversations/c1/messages")] = {"uuid": "m1", "private": True} LibreDesk(self.faux.url, "k", "s", ecrire=True).note_privee("c1", "

x

") m, chemin, corps = self.faux.requetes[-1] assert (m, chemin) == ("POST", "/api/v1/conversations/c1/messages") assert corps == {"message": "

x

", "private": True, "sender_type": "agent"} def test_note_non_privee_leve_garde(self): # réponse {"uuid": "m1", "private": False}, puis {} : Garde les deux fois def test_simulation_n_ecrit_rien(self): # ecrire=False : note_privee et etiqueter → aucune requête POST def test_etiqueter_n_envoie_jamais_set(self): # etiqueter("c1", ["diag:fait"], ["diag:en-cours"]) : deux POST, # actions add_tags puis remove_tags, aucun autre champ def test_etiquette_inconnue_leve(self): # après add_tags, GET rend tags sans "diag:fait" → RuntimeError def test_authentification(self): # en-tête Authorization == "token k:s" (le faux l'enregistre aussi) def test_conversations_pagine_et_filtre(self):# deux pages (total_pages=2) → résultats concaténés ; le filtre # décodé == [{"model":"conversations","field":"tags","operator":"contains","value":"[7]"}] ``` Et `tests/test_garde_fou.py` (spec §7.10), sur le texte de `support_diagnostic/*.py` : ```python def test_un_seul_post_de_messages(self): # "/messages" n'apparaît que dans libredesk.py, dans le corps de note_privee et de messages() (GET) def test_private_en_dur(self): # libredesk.py contient '"private": True' ; aucun fichier ne contient '"to"', '"cc"', '"bcc"', 'set_tags' ``` - [ ] **Step 3 : lancer, vérifier l'échec** — Run : `.venv/bin/python -m unittest tests.test_libredesk tests.test_garde_fou -v` — Expected : ImportError sur `support_diagnostic.libredesk`. - [ ] **Step 4 : écrire `support_diagnostic/libredesk.py`** (urllib, comme `Support-Agent/app/serveur/libredesk.py` ; `add_unredirected_header` pour l'authentification). - [ ] **Step 5 : lancer, vérifier le succès** — même commande — Expected : tout OK. - [ ] **Step 6 : commit** `git commit -m "Client LibreDesk restreint : notes privées et étiquettes seulement"` --- ### Task 3 : l'adaptateur vers les agents **Files :** - Create : `support_diagnostic/diagnostic.py`, `tests/test_diagnostic.py` **Interfaces :** - Consumes : `agents/support/seance.py` (`Seance(mail, images, contexte, donnees, journal, client=None, sortie="mail")`, `.demarrer()`, `.derniere_version()`, `.cout()`, `.support.messages`, `.dossier`, le module attribut `CASES`). - Produces : - `@dataclass Resultat: statut: str` (`"fait"` ou `"ignore"`) `, texte: str, pieces: list[Path], cout: float, dossier: Path | None` (`None` quand les agents n'ont pas tourné) - `MODELE = "claude-opus-5-5"` (celui de `agents/support/agent.py`, pour le pied de note) - `diagnostiquer(mail: str, images: list[tuple[str, bytes]], contexte: str, donnees: Path, cases: Path, client=None) -> Resultat` Approche : `sys.path` reçoit `agents/support` ; `seance.CASES = cases` avant de créer la séance ; `journal` écrit chaque événement en une ligne sur stdout (`[agent] type : texte`, tronqué à 300 caractères). Si `derniere_version()` existe : `fait`, `texte` et `pieces` (chemins dans `s.dossier`) lus du JSON. Sinon : `ignore`, `texte` = le texte du dernier message `assistant` du support (sa question ou son explication). Une exception des agents remonte telle quelle. - [ ] **Step 1 : les tests qui échouent**, avec un faux client Anthropic sur le modèle de `agents/support/check.py` (`FauxClient`, `reponse`, `Bloc` : les recopier dans le test, `check.py` n'est pas importable sans données) : ```python def test_mail_ecrit_donne_fait(self): # le support appelle ecrire_mail({"texte": "Bonjour, …", "pieces_jointes": []}) puis end_turn r = diagnostiquer("mail", [], "", Path(tmp), Path(tmp), client=faux) assert r.statut == "fait" and r.texte == "Bonjour, …" and r.pieces == [] def test_question_donne_ignore(self): # le support répond par du texte, end_turn, sans ecrire_mail assert r.statut == "ignore" and r.texte == "Quelle station ?" ``` - [ ] **Step 2 : lancer, vérifier l'échec** — Run : `.venv/bin/python -m unittest tests.test_diagnostic -v` — Expected : ImportError. - [ ] **Step 3 : écrire `support_diagnostic/diagnostic.py`**. - [ ] **Step 4 : lancer, vérifier le succès** — même commande — Expected : OK. - [ ] **Step 5 : commit** `git commit -m "Adaptateur non interactif vers le support et l'analyste"` --- ### Task 4 : le cycle **Files :** - Create : `support_diagnostic/run.py`, `tests/test_run.py` **Interfaces :** - Consumes : `LibreDesk`, `Garde` (tâche 2) ; `diagnostiquer`, `Resultat`, `MODELE` (tâche 3). - Produces : - `@dataclass Config: url, cle, secret: str; ecrire: bool; autorisees: set[str] | None` (`None` = `*`) `; plafond: int; conversation: str` (`""` = toutes) `; donnees: Path; cases: Path` - `Config.depuis_env(env: Mapping[str, str]) -> Config | None` : `None` si `KILL_SWITCH` est actif. Variables : `LIBREDESK_URL`, `LIBREDESK_API_KEY`, `LIBREDESK_API_SECRET`, `DRY_RUN`, `ALLOWED_CONVERSATION_IDS`, `MAX_CONVERSATIONS_PER_RUN`, `KILL_SWITCH`, `CONVERSATION`, `AIMSIGHT_DATA` (défaut `data`), `AIMSIGHT_CASES` (défaut un dossier temporaire). Lève `ValueError` si `ecrire` et `ALLOWED_CONVERSATION_IDS` vide. - `eligible(etiquettes: list[str]) -> bool` - `fil(messages: list[dict], moi: int) -> tuple[str, str]` : (le mail, le contexte). Le mail : messages `incoming` et `outgoing` non privés, le plus récent en tête, au format de `mail()` de `Support-Agent/app/serveur/libredesk.py` (le recopier). Le contexte : les notes privées dont l'auteur n'est pas `moi`, en texte. - `note(r: Resultat, execution: str) -> str` : le HTML de la note. - `traiter(ld: LibreDesk, cfg: Config, diag=diagnostiquer) -> dict[str, str]` : uuid → statut (`fait`, `ignore`, `erreur`). - `main() -> int` : `python -m support_diagnostic.run` ; code 1 sur `Garde`. Le cycle de `traiter` (spec §9.2) : 1. Candidates : `ld.conversations(ids["tri:diagnostic"])`, ou la seule `cfg.conversation` ; garder celles dont `eligible(ld.etiquettes(uuid))` et, si `cfg.autorisees`, l'uuid y est ; s'arrêter à `cfg.plafond`. 2. Pour chacune : `etiqueter(uuid, ["diag:en-cours"])` ; `fil(ld.messages(uuid), ld.moi())` ; images des messages entrants (types `image/png|jpeg|gif|webp`, ≥ 10 000 octets, comme `Support-Agent`) ; mail vide après `strip()` → `Resultat("ignore", "Le mail du client ne contient pas de texte.", …)` sans appeler `diag` ; sinon `diag(...)` ; `note_privee(uuid, note(r, execution))` ; `etiqueter(uuid, ["diag:" + r.statut], ["diag:en-cours", "diag:relancer"])`. 3. Exception d'une conversation (autre que `Garde`) : `note_privee(uuid, …)` courte (en-tête, « Diagnostic en échec », nom de l'exception, `execution`), `etiqueter(uuid, ["diag:erreur"], ["diag:en-cours"])`, chacun dans son propre `try` ; conversation suivante. 4. `Garde` : `etiqueter(uuid, ["diag:erreur"])` dans un `try`, puis la relancer : tout s'arrête. 5. Fin : une ligne par conversation (uuid, statut, coût), le total, la durée. `execution` : `${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}` si ces variables existent (Gitea les fournit), sinon `local` ; plus `GITHUB_SHA[:7]`. La note (spec §8, version de départ ; format à valider avec l'équipe support) : ```html

🤖 BROUILLON IA — à relire, ne pas envoyer tel quel

Proposition de réponse au client :

…texte échappé (html.escape), un

par paragraphe,
aux retours simples…

Figures préparées (non jointes) : figure-1.png, …


Exécution … · commit … · modèle claude-opus-5-5 · coût 1.23 $

``` - [ ] **Step 1 : les tests qui échouent**, `tests/test_run.py`, avec un faux `LibreDesk` en mémoire (mêmes méthodes, enregistre les appels ; `ecrire` comme le vrai) et un faux `diag` : ```python def test_dry_run_par_defaut(self): # depuis_env({...sans DRY_RUN}).ecrire is False ; "False", "0", "no" → False ; "false" → True def test_ecrire_exige_liste_blanche(self):# DRY_RUN=false sans ALLOWED_CONVERSATION_IDS → ValueError ; "*" → autorisees is None def test_kill_switch(self): # KILL_SWITCH="1" → None ; "false", "0", "" → Config def test_eligible(self): # ["tri:diagnostic"] True ; + "diag:fait" False ; + "diag:fait","diag:relancer" True ; [] False def test_plafond_et_liste_blanche(self): # 5 éligibles, plafond 3 → 3 traitées ; liste blanche {c2} → seule c2 def test_cycle_fait(self): # étiquettes : add en-cours, puis add diag:fait / remove en-cours, relancer ; # une note qui commence par l'en-tête exact et contient le texte du diag def test_mail_vide_ignore(self): # Review Focus 5 def test_erreur_passe_a_la_suivante(self):# Review Focus 3 : diag lève sur c1 → c1 "erreur" (en-cours retiré), c2 "fait" def test_garde_arrete_tout(self): # Review Focus 2 : note_privee lève Garde sur c1 → c2 jamais lue, Garde remonte def test_relance_ecarte_nos_notes(self): # Review Focus 4 : fil() avec une note privée de moi (exclue) et une d'un # humain (dans le contexte, pas dans le mail) def test_note_echappe_le_html(self): # texte "