Trigger.dev

Trigger.dev est le moteur de traitement des tâches de fond qui alimente toutes les opérations de longue durée de CodeCourier. Tandis que le backend Convex gère les données en temps réel et que le frontend Next.js affiche le tableau de bord, Trigger.dev gère l’orchestration des workflows d’agents de codage IA -- des tâches qui peuvent s’exécuter pendant des minutes, voire des heures. Cette page explique ce que fournit Trigger.dev, les tâches spécifiques que CodeCourier définit, comment les surveiller et les détails de configuration.

Ce que fournit Trigger.dev

Trigger.dev est une plateforme de tâches de fond axée sur TypeScript qui fournit :

• Exécution durable -- Les tâches survivent aux redémarrages du serveur et peuvent s’exécuter pendant de longues périodes sans expirer.
• Nouvelles tentatives automatiques -- Les tâches échouées peuvent être relancées automatiquement avec des stratégies de backoff configurables.
• Orchestration de sous-tâches -- Les tâches peuvent déclencher d’autres tâches et attendre leurs résultats, permettant des workflows complexes en plusieurs étapes.
• Surveillance en temps réel -- Le tableau de bord Trigger.dev affiche l’état des tâches, les logs et l’historique d’exécution.
• Contrôle de la concurrence -- Les tâches peuvent être configurées avec des limites de concurrence pour éviter l’épuisement des ressources.

Définitions de tâches CodeCourier

CodeCourier définit les tâches Trigger.dev suivantes dans le répertoire trigger/ :

workflowOrchestrator

Le principal moteur d’exécution de workflow. Lorsqu’un utilisateur déclenche un run de workflow, cette tâche prend le relais et gère l’ensemble du cycle de vie de l’exécution :

1. Crée l’enregistrement du run dans Convex
2. Provisionne une sandbox E2B
3. Exécute les étapes du pipeline (designer, checker, optimizer) en séquence
4. Gère la logique d’itération des boucles designer-checker
5. Rapporte la progression à Convex après chaque étape
6. Crée les pull requests à l’achèvement
7. Déclenche l’extraction des learnings depuis la transcription de session
8. Nettoie les sandboxes une fois terminé

workChainOrchestrator

Orchestre l’exécution séquentielle des issues d’une work chain. Chaque issue devient un run distinct au sein de la chaîne, exécuté l’un après l’autre. La chaîne suit la progression globale et gère les échecs au niveau de l’issue.

designerStep

Exécute une seule étape designer au sein d’un run de workflow. Le designer est l’agent de codage IA principal qui reçoit le prompt de la tâche et implémente les changements demandés à l’intérieur de la sandbox.

checkerStep

Exécute une étape checker qui examine le travail du designer. Le checker inspecte les changements effectués dans la sandbox et fournit un verdict (réussite ou échec) avec un retour détaillé. Si la vérification échoue, le retour est renvoyé au designer pour l’itération suivante.

optimizerStep

Effectue une passe d’optimisation sur le code produit par les étapes précédentes. L’optimizer se concentre sur les améliorations de la qualité du code, l’optimisation des performances et le respect des bonnes pratiques.

prompterStep

Une étape spécialisée qui génère ou affine les prompts pour les étapes suivantes. Utilisée dans les pipelines personnalisés où l’ingénierie de prompts fait partie du workflow.

deepDiveStep

Effectue une investigation approfondie dans un domaine problématique spécifique. Utilisée pour des tâches complexes de débogage ou d’analyse architecturale qui nécessitent une exploration approfondie de la base de code.

issueSession

Gère la découverte d’issues pour un projet. Cette tâche provisionne une sandbox, exécute l’agent IA pour analyser la base de code, et identifie les bugs, la dette technique et les opportunités d’amélioration, produisant une liste structurée d’issues.

sandboxMessage

Gère l’envoi d’un message utilisateur à une sandbox en cours d’exécution et le traitement de la réponse de l’agent. Cette tâche est déclenchée lorsqu’un utilisateur envoie un message via l’interface de chat de la sandbox.

learningExtraction

S’exécute après la fin d’une session de sandbox. Cette tâche analyse la transcription de la conversation entre l’utilisateur et l’agent IA pour extraire des learnings réutilisables -- patterns, préférences, pièges et bonnes pratiques qui peuvent améliorer les sessions futures.

mergeAgent

Une tâche spécialisée qui fusionne les branches de runs de sprint terminés en une seule branche. L’agent de merge provisionne sa propre sandbox, récupère toutes les branches, résout les conflits et crée une pull request finale.

Communication par callback

Les tâches Trigger.dev communiquent avec Convex via le point de terminaison de callback HTTP à /trigger/callback. Cela est nécessaire car les tâches Trigger.dev s’exécutent dans leur propre environnement d’exécution et ne peuvent pas appeler directement les fonctions Convex. Le mécanisme de callback fonctionne comme suit :

1. La tâche envoie une requête HTTP POST à l’URL de déploiement Convex avec le chemin /trigger/callback.
2. La requête inclut un bearer token pour l’authentification et un corps JSON avec le nom de l’opération et les arguments.
3. Le gestionnaire HTTP de Convex distribue l’opération à la fonction interne appropriée.
4. Le résultat est renvoyé au format JSON, et la tâche continue en fonction de la réponse.

Ce pattern maintient le backend Convex comme unique source de vérité tout en permettant aux tâches Trigger.dev de mettre à jour l’état de manière fiable.

Installation et configuration

Variables d’environnement

• TRIGGER_SECRET_KEY -- La clé secrète du projet Trigger.dev. Utilisée par le SDK pour s’authentifier auprès de l’API Trigger.dev.
• TRIGGER_CALLBACK_SECRET -- Un secret partagé utilisé par les tâches Trigger.dev pour s’authentifier auprès du point de terminaison de callback Convex. Il doit être défini à la fois dans l’environnement Trigger.dev et dans le déploiement Convex.

Configuration du build

Le build Trigger.dev est configuré dans trigger.config.ts à la racine du projet. Ce fichier spécifie :

• L’ID du projet pour le déploiement Trigger.dev
• Les plugins et dépendances de build
• Tout paquet externe qui doit être empaqueté avec le runtime Trigger.dev

Surveiller les tâches

Tableau de bord Trigger.dev

Le tableau de bord web Trigger.dev offre une visibilité en temps réel sur l’exécution des tâches :

• Liste des runs -- Affiche toutes les exécutions de tâches avec leur état, leur durée et leurs horodatages.
• Détail du run -- Affiche le journal complet d’exécution d’une tâche spécifique, y compris les invocations de sous-tâches et leurs résultats.
• Suivi des erreurs -- Les tâches échouées affichent le message d’erreur et la stack trace pour le débogage.

Tableau de bord CodeCourier

Le tableau de bord CodeCourier affiche également l’état des runs Trigger.dev via le composant TriggerRunStatus. Ce composant utilise le paquet @trigger.dev/react-hooks pour s’abonner aux mises à jour d’état des tâches en temps réel et les affiche en ligne avec les cartes de sandbox et de run.

Flux d’exécution des tâches

Voici le flux d’exécution typique pour un workflow designer-checker :

1. L’utilisateur clique sur « Démarrer le run » dans le tableau de bord.
2. L’action Convex runActions.startRun crée un enregistrement de run et déclenche la tâche Trigger.dev workflowOrchestrator.
3. L’orchestrateur appelle l’API de callback pour lire la configuration du workflow et les paramètres du projet.
4. L’orchestrateur provisionne une sandbox E2B et déclenche la sous-tâche designerStep.
5. L’étape designer envoie le prompt à l’agent IA à l’intérieur de la sandbox et diffuse la réponse.
6. Une fois le designer terminé, l’orchestrateur déclenche la sous-tâche checkerStep.
7. Le checker examine le travail et renvoie un verdict. En cas d’échec, la boucle recommence à l’étape 4.
8. En cas de succès ou lorsque le nombre maximal d’itérations est atteint, l’orchestrateur crée une PR et déclenche l’extraction des learnings.
9. La sandbox est arrêtée et l’état du run passe à « completed ».

Dépannage

Tâches bloquées en état d’attente

• Vérifiez les limites de concurrence dans le tableau de bord Trigger.dev. Si trop de tâches sont en cours d’exécution, les nouvelles peuvent être mises en file d’attente.
• Vérifiez que TRIGGER_SECRET_KEY est correcte et que le projet Trigger.dev est actif.

Erreurs de callback

• Vérifiez que TRIGGER_CALLBACK_SECRET correspond à la fois dans l’environnement Trigger.dev et dans le déploiement Convex.
• Consultez les logs des fonctions Convex pour les messages d’erreur du gestionnaire de callback.

Tâches échouant après la création de la sandbox

• Cela indique généralement des clés API de fournisseur manquantes (Anthropic, E2B, GitHub). Assurez-vous que toutes les clés requises sont configurées dans les paramètres du projet.