4nk/ia_dev
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
ia_dev/.cursor/agents/agent-loop.md
Nicolas Cantu 2363c6e4b7 full exec
2026-03-17 14:37:53 +01:00

12 KiB
Raw Blame History

name description model is_background
agent-loop 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 / &). inherit false

Agent agent-loop

Règle d'exécution intégrale (obligatoire, non négociable)

  • Tout dérouler : exécuter toutes les étapes décrites dans cet agent dans l'ordre, sans en omettre aucune. Tout doit se dérouler effectivement.
  • Sans priorisation : aucune étape n'est optionnelle ou "secondaire" ; chacune est obligatoire.
  • Sans jugement d'intérêt : ne jamais juger de la pertinence d'une étape pour la sauter ; tout appliquer tel que décrit, sans exception.
  • Vérification en fin d'agent : avant clôture, cocher explicitement chaque étape (réalisée / non réalisée).

Contexte projet : La configuration et la documentation du projet sont dans projects/<id>/. L'identifiant <id> est résolu uniquement par MAIL_TO (adresse « to » des mails) ou AI_AGENT_TOKEN (token des requêtes) ; pas de fallback. Voir projects/README.md. Rappeler en début d'exécution : projet (id), branche et répertoire de travail du dépôt concerné (ia_dev ou dépôt du projet configuré).

Documentation : La doc des projets gérés est dans projects/<id>/docs ; la doc ia_dev est dans projects/ia_dev/docs.

Horodatage : au début et à la fin d'exécution, afficher date/heure, projet (id), branche, répertoire de travail du dépôt concerné.

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.

Récupération et filtrage : la récupération des mails et le filtrage (to, from, tickets.authorized_emails, date) sont assurés par le script tickets-fetch-inbox.sh (qui appelle le Python associé). L'agent ne fait que lancer ce script ; il ne récupère ni ne filtre lui‑même. Les adresses « to » des mails reçus déterminent le projet (routage par le script) ; les réponses sont envoyées à l'expéditeur (« from »). Aucune adresse n'est fixée en dur.

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 (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).
  • Arrêt à la demande : projects/<id>/logs/gitea-issues/agent-loop.stop. Au début de chaque cycle, exécuter agent-loop-stop-requested.sh (exit 0 si le fichier existe) ; si oui, lancer agent-loop-lock-release.sh et sortir. Pour demander l'arrêt : Depuis la racine de ia_dev (MAIL_TO ou AI_AGENT_TOKEN défini) : ./gitea-issues/agent-loop-stop.sh ou touch projects/<id>/logs/gitea-issues/agent-loop.stop.

1. Pas de lancement en arrière-plan

Règle impérative : ne jamais lancer agent-loop.sh ni agent-loop-treatment.sh en arrière-plan (pas de nohup, pas de &). Ces scripts tournent indéfiniment et continueraient après la fin de la session. C'est l'agent agent-loop qui gère les boucles, par exécutions délimitées uniquement (section 2 ou 3).

Si l'utilisateur demande explicitement « lancer les 2 boucles en arrière-plan » : lui proposer à la place une boucle limitée (section 3 : agent-loop-chat-iterations.sh [N] avec N choisi, ou section 2 : x cycles récupération + traitement). Ne pas lancer de processus persistants sans que l'utilisateur ait confirmé en connaissance de cause et exécuté lui‑même la commande s'il le souhaite.

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), ou invoque /agent-loop N (N = nombre de boucles de 1 min) : x = N. Chaque cycle = 1 récupération + 1 traitement (agent gitea-issues-process) + 1 min d'attente. Pour que les N cycles s'exécutent réellement (sans limite de session) : l'agent lance une seule commande ./gitea-issues/agent-loop-n-cycles.sh [N] avec un timeout ≥ N minutes ; le script fait N × (récupération + agent via Cursor Agent CLI + 1 min). Voir section 3 (prérequis CLI et AGENT_LOOP_RUN_AGENT=1).

Avant de commencer les x cycles :

  • Exécuter depuis la racine de ia_dev : ./gitea-issues/agent-loop-lock-acquire.sh.
  • Si le script sort avec un code non nul : ne pas lancer les cycles ; indiquer à l'utilisateur qu'une instance est déjà en cours (lock actif, mtime < 24 h).
  • Si le script sort 0 : le lock est acquis ; poursuivre.
  • À la fin (normale ou après arrêt) : exécuter Depuis la racine de ia_dev : ./gitea-issues/agent-loop-lock-release.sh (supprime le lock et le fichier stop s'il existe).

Pour chaque cycle i de 1 à x :

Au début du cycle (avant l'étape 1) : exécuter Depuis la racine de ia_dev : ./gitea-issues/agent-loop-stop-requested.sh. Si le script sort 0 (fichier stop présent) : exécuter agent-loop-lock-release.sh, puis sortir en indiquant que la boucle a été arrêtée à la demande.

  1. Récupération une fois : exécuter depuis la racine de ia_dev :

    Depuis la racine de ia_dev : ./gitea-issues/agent-loop-retrieval-once.sh

    Ce script exécute tickets-fetch-inbox.sh puis list-pending-spooler.sh et écrit les chemins des .pending dans projects/<id>/logs/gitea-issues/agent-loop.pending (et met à jour le fichier témoin). Pas d'arrière-plan : attendre la fin du script.

  2. Traitement une fois : lancer intégralement l'agent gitea-issues-process sur les mails reçus (contenu de projects/<id>/logs/gitea-issues/agent-loop.pending). Utiliser le sous-agent Cursor (mcp_task ou équivalent) avec le type gitea-issues-process et un prompt du type : « Traite les mails du spooler listés dans projects/<id>/logs/gitea-issues/agent-loop.pending (chemins des .pending) ou en exécutant list-pending-spooler.sh. Pour chaque fichier .pending : lire le JSON (from, to, subject, body, message_id, base). Envoyer la réponse à l'expéditeur (champ « from » du JSON), pas à une adresse fixe ; le « to » du mail reçu a déjà déterminé le projet. Rédiger une réponse pertinente (uniquement ton texte ; pas de citation — mail-send-reply.sh refuse si le body contient From:, Message-ID, wrote:, etc.). Appeler mail-send-reply.sh --to puis write-response-spooler.sh. Ne pas appeler mail-mark-read.sh (spooler). »

  3. Attente 1 minute entre cycles : après chaque cycle (après l’étape 2), si ce n’est pas le dernier cycle (i < x), attendre 1 minute (60 secondes) avant de commencer le cycle suivant — exécuter sleep 60 ou faire attendre l’orchestration 60 s. Pas d’attente après le dernier cycle.

Répéter les étapes 1, 2 et 3 pour les x cycles demandés. Chaque cycle traite une seule récupération (ce qui a été reçu lors de cette récupération).

3. Autres demandes

  • Boucle limitée depuis le chat (N itérations, attente 1 min entre chaque) : pour /agent-loop N (ex. 600), l'agent exécute une seule commande depuis la racine de ia_dev : ./gitea-issues/agent-loop-n-cycles.sh [N] (défaut N=600), avec un timeout d'au moins N minutes (ex. 39600000 ms pour N=600 ≈ 11 h). Le script effectue exactement N cycles (vérification arrêt → récupération → invocation de l'agent gitea-issues-process via Cursor Agent CLI si AGENT_LOOP_RUN_AGENT=1 → attente 1 min) puis lock-release. Aucun contournement : le traitement à chaque cycle est le même agent gitea-issues-process, invoqué par le script via la CLI. Prérequis : Cursor Agent CLI dans le PATH et AGENT_LOOP_RUN_AGENT=1 dans .secrets/gitea-issues/agent-loop.env pour que les mails soient traités à chaque cycle. Ne pas utiliser agent-loop-chat-iterations.sh pour /agent-loop N : ce script fait uniquement mail-list-unread (legacy) et ne traite pas le spooler. Pour une demande explicite « N itérations legacy (non lu uniquement) » sans réponse mail : ./gitea-issues/agent-loop-chat-iterations.sh [N]. 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 projects/<id>/logs/gitea-issues/agent-loop.pending 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.

Contraintes

  • Pas de processus en arrière-plan : ne jamais lancer agent-loop.sh ni agent-loop-treatment.sh avec nohup ou & ; les boucles sont gérées par l'agent via des exécutions délimitées (agent-loop-chat-iterations.sh N, ou cycles section 2).
  • Ne pas déclencher la CI, ne pas écrire en base, ne pas masquer les sorties des scripts.
  • Répertoire d'exécution des scripts : toujours racine de ia_dev (standalone).
  • Le traitement des mails (réponse réelle, workflow fil, marquage lu) est uniquement assuré par l'agent gitea-issues-process ; ne pas court-circuiter son workflow.

Clôture complète obligatoire (tous les cas, sans exception)

En fin d'exécution de cet agent, toujours appliquer intégralement .cursor/rules/cloture-evolution.mdc : points 1 à 19. Toutes les étapes (agent + clôture) doivent être réellement passées, sans jugement de pertinence ; tout doit se dérouler. (horodatage, 5 sub-agents par projet, questions 3-13, docupdate, reste à faire, push-by-script si pas déjà fait, affichage du texte du commit). Aucune exception : même si la boucle n'a pas traité d'éléments, la clôture complète est obligatoire. Lister les actions réalisées et non réalisées pour chaque point.