Exécuter des workflows

Exécuter un workflow dans CodeCourier crée une instance d’exécution (un « run ») qui traite les étapes du pipeline séquentiellement. Chaque run a son propre prompt, ses surcharges de configuration et son état d’exécution. Ce guide couvre comment démarrer des runs, ce qui se passe pendant l’exécution, et comment les surveiller et les gérer.

Démarrer un run

Flux d’exécution du run

L’orchestrateur de workflow (une tâche de fond Trigger.dev) gère tout le cycle de vie du run :

1. Initialisation du run

L’orchestrateur lit le blueprint de workflow, résout les références de persona et construit le plan d’exécution. Il parse les étapes du pipeline en execution blocks (étapes uniques et boucles) et prépare la configuration de la sandbox.

2. Exécution des étapes

Pour chaque étape du pipeline, l’orchestrateur :

1. Crée un enregistrement de run step dans la table runSteps avec le rôle de l’étape, le numéro d’itération, la référence de persona et le statut.
2. Crée une sandbox E2B à partir du template configuré. La sandbox est configurée avec le repo Git du projet, les variables d’environnement, les skills et les learnings.
3. Envoie la tâche d’étape appropriée (designer-step, checker-step, optimizer-step, etc.) à Trigger.dev.
4. La tâche d’étape exécute l’agent IA à l’intérieur de la sandbox avec le prompt et les instructions de l’étape. La sortie est renvoyée en streaming vers la table des messages de sandbox.
5. Enregistre l’usage des tokens et les données de coût pour l’étape.
6. Met à jour le statut du run step vers completed ou failed.

3. Gestion des Iteration Blocks

Lorsque l’orchestrateur atteint un Iteration Block (un groupe d’étapes consécutives partageant un loopId), il exécute les étapes du block en séquence, puis vérifie le verdict :

• Si l’étape checker produit un verdict de passage, le block sort et l’exécution continue vers le block suivant.
• Si l’étape checker produit un verdict d’échec, le block se relance depuis sa première étape. Le feedback du checker est incorporé dans le prompt du designer à l’itération suivante.
• Si le loopMaxIterations du block est atteint sans verdict de passage, le block se termine et le run est marqué comme failed.

Les étapes en dehors d’un Iteration Block s’exécutent exactement une fois. Les checkers en dehors d’un block émettent quand même un verdict mais ne provoquent pas de retry automatique.

4. Achèvement du run

Lorsque tous les execution blocks ont été traités :

1. Le statut du run est mis à jour vers completed.
2. Le timestamp completedAt est défini.
3. Une pull request est créée si le run a produit des changements Git.
4. L’extraction des learnings est déclenchée pour les sandboxes du run.
5. Les compteurs du projet sont mis à jour.
6. Des notifications sont envoyées (si configurées).

États du run

Chaque run se trouve dans l’un des sept états :

• scheduled - Le run a été mis en file d’attente par le scheduler de tâches récurrentes et attend son heure de déclenchement planifiée. C’est un état de pré-exécution qui précède pending. Les runs planifiés portent un timestamp scheduledFor, un timezone, un recurrencePattern et un recurringTaskId qui renvoie à la tâche récurrente qui les a créés.
• pending - Le run a été créé mais l’orchestrateur n’a pas encore commencé le traitement.
• running - L’orchestrateur exécute activement les étapes. Le champ currentIteration suit la progression.
• paused - Le run a été temporairement suspendu. Cela peut arriver quand une intervention de l’utilisateur est nécessaire.
• completed - Toutes les étapes se sont terminées avec succès.
• failed - Une étape a rencontré une erreur irrécupérable. Le champ error contient le message d’échec.
• cancelled - Le run a été annulé manuellement par l’utilisateur.

Surveiller un run

Vue détaillée du run

La page de détail du run fournit une vue complète de l’exécution :

• Statut et progression - État actuel, nombre d’itérations et temps écoulé.
• Timeline des étapes - Une timeline visuelle montrant chaque run step, son rôle, son statut et sa durée. Vous pouvez cliquer sur une étape pour voir la sortie de sa sandbox.
• Messages de sandbox - La sortie de terminal en streaming de chaque sandbox, montrant le travail de l’agent IA en temps réel.
• Verdicts - Pour les étapes checker, le verdict pass/fail et le texte de feedback sont affichés.
• Statut de PR - Si une pull request a été créée, son URL et son statut sont affichés.

Vue liste des runs

La page Runs montre une liste paginée de tous les runs du projet. Chaque ligne affiche le nom du run, le statut, la source (workflow, sprint ou sandbox), l’heure de création et un aperçu du prompt. Vous pouvez filtrer et trier les runs et utiliser des actions groupées pour supprimer plusieurs runs à la fois.

Sources des runs

Les runs sont créés à partir de plusieurs sources, suivies par le champ source :

• workflow - Déclenché manuellement à partir d’un blueprint de workflow sur la page Workflows.
• issue - Créé par une work chain dans le cadre de l’exécution d’une session d’issue.
• sandbox - Créé à partir d’un lancement de sandbox autonome.
• merge_agent - Créé par le merge agent pour la gestion des PR.
• sprint - Créé par un orchestrateur de sprint chain dans le cadre d’une exécution de sprint par lot.
• scheduled - Créé par le scheduler de tâches récurrentes à une cadence configurée (quotidienne, hebdomadaire, etc.).

Gestion des erreurs

Échecs d’étape

Lorsqu’une étape individuelle échoue, l’erreur est enregistrée sur l’enregistrement du run step. Selon le type d’échec :

• Échec de création de sandbox - E2B n’a pas pu provisionner la VM. Cela signifie généralement que la clé API E2B est invalide ou que le template n’existe pas.
• Crash d’agent - Le processus CLI IA s’est arrêté de manière inattendue. La sortie d’erreur est capturée dans les messages de sandbox.
• Timeout - La sandbox a dépassé son timeout configuré. Le travail effectué avant le timeout est préservé s’il est commité.
• Erreur d’API - Le provider IA a renvoyé une erreur (rate limit, clé invalide, erreur serveur).

Récupération de run

CodeCourier ne prend pas actuellement en charge la reprise d’un run échoué à partir du point d’échec. Si un run échoue, vous pouvez démarrer un nouveau run avec le même prompt. Le nouveau run démarre à neuf, mais si le run précédent a poussé des commits sur la branche, le nouveau run reprend là où le code s’est arrêté.

S’arrêter après le tour actuel

En plus de l’annulation immédiate, vous pouvez définir le flag stopAfterCurrentTurn sur un workflow en cours d’exécution. C’est un arrêt gracieux qui permet au tour d’agent en cours d’exécution de se terminer avant d’arrêter le run. C’est utile lorsque vous voulez examiner une progression partielle sans perdre le travail déjà en cours.

Lorsque stopAfterCurrentTurn est défini :

1. L’orchestrateur termine le tour d’agent actuel (l’IA achève sa réponse actuelle, son utilisation d’outils et tout commit de fichier).
2. Plutôt que de passer à l’itération ou l’étape suivante, le run passe àpaused.
3. Les changements de code commités pendant le tour final sont préservés sur la branche.

Vous pouvez définir ce flag depuis la page de détail du run en utilisant le bouton « Stop after turn », disponible tant que le run est à l’état running. C’est préférable à une annulation brutale lorsque vous voulez un point d’arrêt propre plutôt qu’un arrêt abrupt.

Suivi des CI Checks

Après qu’un run crée une pull request, CodeCourier suit le statut des CI checks pour cette PR. L’objet ciChecks de l’enregistrement du run reflète le dernier statut de l’API de checks de GitHub :

ciChecks: {
  status: "passing" | "failing" | "pending",  // Aggregate CI status
  checks: Array<{
    name: string,       // Check name (e.g., "Build", "Tests", "Lint")
    status: string,     // Individual check status
    url: string,        // Link to the check run on GitHub
  }>,
  checkedAt: number,    // Unix timestamp of the last status poll
}

Lorsque les CI checks de la PR d’un run échouent, le statut de PR du run passe à blocked_on_ci. Ce statut est distinct des autres états de PR et indique que la PR existe et est ouverte, mais ne peut pas être mergée tant que la CI ne passe pas.

Valeurs du statut de PR

Le champ prStatus d’un run suit tout le cycle de vie de la pull request associée :

• creating - La requête de création de PR a été envoyée mais ne s’est pas encore terminée.
• created - La PR est ouverte et attend la revue. Les CI checks peuvent être en cours d’exécution.
• blocked_on_ci - La PR est ouverte mais les CI checks échouent. L’objet ciChecks contient des détails sur les checks qui ont échoué.
• merged - La PR a été mergée dans la branche cible.
• failed - La tentative de création de PR a échoué (par exemple, erreur d’API GitHub, échec d’authentification). Le champ prError contient le message d’erreur.
• skipped - Aucun changement de code n’a été produit par le run, donc aucune PR n’a été créée.

Scores de qualité

Si le workflow inclut une étape Evaluator, l’enregistrement du run suit unqualityScore global (le score composite de toutes les étapes evaluator). Les enregistrements de run step individuels portent la décomposition complète qualityScores :

// On the run record:
qualityScore: number,   // Composite score (0-100) from all evaluator steps

// On individual runStep records (type: "evaluator"):
qualityScores: {
  correctness: number,      // 0-100
  typeSafety: number,       // 0-100
  codeStyle: number,        // 0-100
  testCoverage: number,     // 0-100
  completeness: number,     // 0-100
  composite: number,        // Weighted average of all five dimensions
  thresholdResult: boolean, // Whether composite meets the configured threshold
}

Les scores de qualité sont visibles dans la timeline des étapes de la vue détaillée du run et dans le dashboard de Monitoring. Les runs avec des scores de qualité faibles ou un thresholdResult en échec sont signalés visuellement afin qu’ils ressortent dans la liste des runs.

Annuler un run

Vous pouvez annuler un workflow en cours d’exécution depuis la page de détail du run. L’annulation :

1. Définit le statut du run à cancelled.
2. Tente de tuer toutes les sandboxes actives associées au run.
3. Empêche l’orchestrateur de traiter d’autres étapes.

L’annulation est best-effort - si une étape est en cours d’exécution, la sandbox peut continuer jusqu’à ce que la commande de kill prenne effet. Si vous voulez un arrêt plus propre, utilisez plutôt le flag stopAfterCurrentTurn (voir ci-dessus).

Métadonnées du run

Chaque enregistrement de run contient des métadonnées utiles pour le suivi et l’analyse :

{
  status: "running",              // Current state (includes "scheduled")
  prompt: "...",                  // The task description
  source: "workflow",             // How the run was created (workflow|sprint|sandbox|scheduled|...)
  currentIteration: 2,           // Current iteration inside an Iteration Block (or 1 when no block is active)
  config: { ... },               // Sandbox configuration
  githubRepoUrl: "...",          // Git repository
  branchName: "feat/...",        // Working branch
  prUrl: "...",                  // Pull request URL (after completion)
  prStatus: "created",           // PR lifecycle state (includes "blocked_on_ci")
  startedAt: 1712345678,         // Execution start timestamp
  completedAt: null,             // Null until finished
  cliVersion: "1.2.3",          // CLI tool version used
  qualityScore: 87,              // Composite quality score from evaluator steps
  stopAfterCurrentTurn: false,   // Graceful stop flag
  ciChecks: {                    // CI check status for the run's PR
    status: "passing",
    checks: [...],
    checkedAt: 1712345900,
  },
  // Scheduled run fields (only when source = "scheduled"):
  scheduledFor: 1712340000,      // Intended fire time
  timezone: "America/New_York",  // Timezone from recurring task
  recurrencePattern: "daily",    // Frequency (daily|weekly|...)
  recurringTaskId: "...",        // Reference to the recurring task
}