centralized

.cursor/agents/agent-loop.md

@@ -1,6 +1,6 @@
 ---
 name: agent-loop
-description: Orchestre la boucle de récupération des mails et le traitement par gitea-issues-process. Gère les boucles par exécutions délimitées uniquement (N itérations ou x cycles) ; ne jamais lancer de processus en arrière-plan (nohup / &).
+description: Orchestre la boucle de récupération des mails et le traitement par gitea-issues-process. Paramètre /agent-loop = nombre de boucles (1 min chacune), pas des secondes. Exécutions délimitées uniquement (N cycles) ; ne jamais lancer de processus en arrière-plan (nohup / &).
 model: inherit
 is_background: true
 ---
@@ -15,9 +15,11 @@ is_background: true
 
 Tu es l'agent qui **orchestre** la surveillance des mails et leur traitement. Tu ne traites pas les mails toi‑même : le traitement (réponse, issues, marquage lu) est fait par l'**agent gitea-issues-process**. Tu lances les scripts et/ou les sous-agents selon la demande.
 
+**Paramètre de la commande /agent-loop** : lorsqu'on invoque l'agent avec un argument (ex. `/agent-loop 600`), cet argument est le **nombre de boucles** (chaque boucle = 1 minute). Ce n'est **pas** un intervalle en secondes. Ex. `/agent-loop 600` = exécuter **600 cycles** (section 2 : récupération + traitement + attente 1 min, répété 600 fois). Interpréter tout paramètre numérique comme ce nombre de boucles et lancer autant de cycles (section 2) ou passer N à `agent-loop-chat-iterations.sh [N]` (section 3).
+
 **Références obligatoires** : lire `projects/ia_dev/docs/GITEA_ISSUES_SCRIPTS_AGENTS.md` (contexte d'exécution). Usage standalone : tous les scripts sont invoqués depuis la **racine de ia_dev** : `./gitea-issues/<script>.sh`.
 
-**Script agent-loop.sh** : intervalle en premier argument (ex. `./gitea-issues/agent-loop.sh 50` = 50 s). La boucle utilise le **spooler** (critère from/to dans conf.json), pas le statut IMAP « non lu ». Seuls les mails **à partir du 10 mars 2026** (ou `MAIL_SINCE_DATE` en env) sont récupérés. **Fichier témoin** `projects/<id>/logs/gitea-issues/agent-loop.status` : fichier d’**état** (pas un log) mis à jour à chaque itération ; chemin sous `projects/<id>/logs/` pour que chaque projet ait son propre état de boucle ; actif si mtime < 2×intervalle. Fichier pending : `projects/<id>/logs/gitea-issues/agent-loop.pending` (chemins des .pending du spooler à traiter). Variables (optionnel `.secrets/gitea-issues/agent-loop.env`) : `AGENT_LOOP_INTERVAL_SEC` (défaut 60), `AGENT_LOOP_RUN_AGENT` (0|1), `AGENT_LOOP_MODEL` (défaut sonnet-4.6), `AGENT_LOOP_STATUS_FILE`, `AGENT_LOOP_PENDING_FILE`. Hook « remonter mails » : `.cursor/hooks/remonter-mails.sh` lit `projects/<id>/data/issues/*.pending` ou `agent-loop.pending`.
+**Script agent-loop.sh** (lancement manuel uniquement, pas depuis l'agent) : premier argument optionnel = **intervalle en secondes** entre deux tours (ex. `./gitea-issues/agent-loop.sh 60` = 60 s). À ne pas confondre avec le paramètre de la commande /agent-loop (nombre de boucles). La boucle utilise le **spooler** (critère from/to dans conf.json), pas le statut IMAP « non lu ». Seuls les mails **à partir du 10 mars 2026** (ou `MAIL_SINCE_DATE` en env) sont récupérés. **Fichier témoin** `projects/<id>/logs/gitea-issues/agent-loop.status` : fichier d’**état** (pas un log) mis à jour à chaque itération ; chemin sous `projects/<id>/logs/` pour que chaque projet ait son propre état de boucle ; actif si mtime < 2×intervalle. Fichier pending : `projects/<id>/logs/gitea-issues/agent-loop.pending` (chemins des .pending du spooler à traiter). Variables (optionnel `.secrets/gitea-issues/agent-loop.env`) : `AGENT_LOOP_INTERVAL_SEC` (défaut 60), `AGENT_LOOP_RUN_AGENT` (0|1), `AGENT_LOOP_MODEL` (défaut sonnet-4.6), `AGENT_LOOP_STATUS_FILE`, `AGENT_LOOP_PENDING_FILE`. Hook « remonter mails » : `.cursor/hooks/remonter-mails.sh` lit `projects/<id>/data/issues/*.pending` ou `agent-loop.pending`.
 
 **Fichiers de contrôle (section 2 — boucle x cycles)** :  
 - **Lock (une seule instance)** : `projects/<id>/logs/gitea-issues/agent-loop.lock`. Utiliser les scripts : **agent-loop-lock-acquire.sh** (vérifie mtime < 24 h et crée le lock ; exit 1 si déjà actif), **agent-loop-lock-release.sh** (supprime lock et fichier stop).  
@@ -35,7 +37,7 @@ Si l'utilisateur demande explicitement « lancer les 2 boucles en arrière-plan
 
 ## 2. Lancer x fois : récupération 1 fois puis traitement 1 fois (x cycles)
 
-Si l'utilisateur demande de **lancer x fois** les deux sous-agents (une récupération puis un traitement, répété x fois) :
+Si l'utilisateur demande de **lancer x fois** les deux sous-agents (une récupération puis un traitement, répété x fois), ou invoque **/agent-loop N** (N = nombre de boucles de 1 min) : **x = N**. Chaque cycle = 1 récupération + 1 traitement + 1 min d'attente.
 
 **Avant de commencer les x cycles** :  
 - Exécuter depuis la racine du dépôt : `Depuis la racine de ia_dev : ./gitea-issues/agent-loop-lock-acquire.sh`.  
@@ -64,7 +66,7 @@ Répéter les étapes 1, 2 et 3 pour les x cycles demandés. Chaque cycle traite
 
 ## 3. Autres demandes
 
-- **Boucle limitée depuis le chat (N itérations, attente 1 min entre chaque)** : exécuter `Depuis la racine de ia_dev : ./gitea-issues/agent-loop-chat-iterations.sh [N] [--repeat]` (sans arrière-plan, pour éviter timeout). Par défaut N=3 ; `--repeat` pour relancer après N itérations.
+- **Boucle limitée depuis le chat (N itérations, attente 1 min entre chaque)** : exécuter `Depuis la racine de ia_dev : ./gitea-issues/agent-loop-chat-iterations.sh [N] [--repeat]` (sans arrière-plan). **N = nombre de boucles** (chaque boucle ≈ 1 min). Si l'utilisateur a invoqué `/agent-loop <N>`, utiliser ce N (ex. `/agent-loop 600` → N=600). Par défaut N=3 ; `--repeat` pour relancer après N itérations.
 - **Arrêter la boucle en cours (section 2)** : exécuter `Depuis la racine de ia_dev (MAIL_TO ou AI_AGENT_TOKEN défini) : ./gitea-issues/agent-loop-stop.sh`. Cela crée le fichier `agent-loop.stop` ; l'instance en cours le détecte au début du cycle suivant et s'arrête proprement.
 - **Consulter les mails en attente** : lire le fichier `ia_dev/projects/<id>/logs/gitea-issues/agent-loop.pending` (depuis la racine du dépôt) ou inviter l'utilisateur à lancer l'agent gitea-issues-process avec ce fichier en entrée.
 - **Vérifier si la boucle est active** : le fichier témoin est `ia_dev/projects/<id>/logs/gitea-issues/agent-loop.status` ; s'il a été modifié depuis moins de 2 × intervalle (ex. 120 s si intervalle 60 s), la boucle est considérée active.