Eseguire workflow

Eseguire un workflow in CodeCourier crea un’istanza di esecuzione (un « run ») che elabora gli step della pipeline in sequenza. Ogni run ha il proprio prompt, i propri override di configurazione e il proprio stato di esecuzione. Questa guida copre come avviare run, cosa succede durante l’esecuzione e come monitorarli e gestirli.

Avviare un run

Flusso di esecuzione del run

L’orchestratore di workflow (un task in background di Trigger.dev) gestisce l’intero ciclo di vita del run:

1. Inizializzazione del run

L’orchestratore legge il blueprint del workflow, risolve i riferimenti a persona e costruisce il piano di esecuzione. Analizza gli step della pipeline in execution block (step singoli e loop) e prepara la configurazione della sandbox.

2. Esecuzione degli step

Per ogni step della pipeline, l’orchestratore:

1. Crea un record di run step nella tabella runSteps con il ruolo dello step, il numero di iterazione, il riferimento a persona e lo status.
2. Crea una sandbox E2B dal template configurato. La sandbox viene impostata con il repo Git del progetto, le variabili d’ambiente, gli skill e i learning.
3. Invia il task di step appropriato (designer-step, checker-step, optimizer-step, ecc.) a Trigger.dev.
4. Il task di step esegue l’agente IA dentro la sandbox con il prompt e le istruzioni dello step. L’output viene restituito in streaming alla tabella dei messaggi della sandbox.
5. Registra l’uso dei token e i dati di costo per lo step.
6. Aggiorna lo status del run step a completed o failed.

3. Gestione degli Iteration Block

Quando l’orchestratore raggiunge un Iteration Block (un gruppo di step consecutivi che condividono un loopId), esegue gli step del block in sequenza, poi controlla il verdetto:

• Se lo step checker produce un verdetto positivo, il block esce e l’esecuzione continua verso il block successivo.
• Se lo step checker produce un verdetto negativo, il block viene rieseguito dal suo primo step. Il feedback del checker viene incorporato nel prompt del designer alla iterazione successiva.
• Se il loopMaxIterations del block viene raggiunto senza un verdetto positivo, il block termina e il run viene marcato come failed.

Gli step fuori da un Iteration Block vengono eseguiti esattamente una volta. I checker fuori da un block emettono comunque un verdetto ma non causano un retry automatico.

4. Completamento del run

Quando tutti gli execution block sono stati elaborati:

1. Lo status del run viene aggiornato a completed.
2. Il timestamp completedAt viene impostato.
3. Una pull request viene creata se il run ha prodotto modifiche Git.
4. L’estrazione dei learning viene avviata per le sandbox del run.
5. I contatori del progetto vengono aggiornati.
6. Le notifiche vengono inviate (se configurate).

Stati del run

Ogni run si trova in uno di sette stati:

• scheduled - Il run è stato messo in coda dallo scheduler dei task ricorrenti e attende l’orario di avvio pianificato. È uno stato di pre-esecuzione che precede pending. I run pianificati portano un timestamp scheduledFor, un timezone, un recurrencePattern e un recurringTaskId che rimanda al task ricorrente che li ha creati.
• pending - Il run è stato creato ma l’orchestratore non ha ancora iniziato l’elaborazione.
• running - L’orchestratore esegue attivamente gli step. Il campo currentIteration traccia l’avanzamento.
• paused - Il run è stato temporaneamente sospeso. Può accadere quando serve un intervento dell’utente.
• completed - Tutti gli step si sono conclusi con successo.
• failed - Uno step ha incontrato un errore irrecuperabile. Il campo error contiene il messaggio di fallimento.
• cancelled - Il run è stato annullato manualmente dall’utente.

Monitorare un run

Vista di dettaglio del run

La pagina di dettaglio del run fornisce una vista completa dell’esecuzione:

• Status e avanzamento - Stato attuale, conteggio delle iterazioni e tempo trascorso.
• Timeline degli step - Una timeline visiva che mostra ogni run step, il suo ruolo, status e durata. Puoi cliccare su uno step per vedere l’output della sua sandbox.
• Messaggi della sandbox - L’output del terminale in streaming di ogni sandbox, che mostra il lavoro dell’agente IA in tempo reale.
• Verdetti - Per gli step checker, il verdetto pass/fail e il testo di feedback vengono mostrati.
• Status della PR - Se una pull request è stata creata, vengono mostrati il suo URL e status.

Vista lista dei run

La pagina Runs mostra una lista paginata di tutti i run del progetto. Ogni riga mostra il nome del run, lo status, la source (workflow, sprint o sandbox), l’ora di creazione e un’anteprima del prompt. Puoi filtrare e ordinare i run e usare azioni bulk per eliminare più run alla volta.

Source dei run

I run vengono creati da diverse source, tracciate dal campo source:

• workflow - Avviato manualmente da un blueprint di workflow sulla pagina Workflows.
• issue - Creato da una work chain come parte dell’esecuzione di una sessione di issue.
• sandbox - Creato dall’avvio di una sandbox autonoma.
• merge_agent - Creato dal merge agent per la gestione delle PR.
• sprint - Creato da un orchestratore di sprint chain come parte di un’esecuzione di sprint batch.
• scheduled - Creato dallo scheduler dei task ricorrenti a una cadenza configurata (giornaliera, settimanale, ecc.).

Gestione degli errori

Fallimenti di step

Quando un singolo step fallisce, l’errore viene registrato sul record del run step. A seconda del tipo di fallimento:

• Fallimento di creazione della sandbox - E2B non è riuscito a provisionare la VM. Di solito significa che la chiave API E2B non è valida o il template non esiste.
• Crash dell’agente - Il processo CLI IA è terminato in modo imprevisto. L’output di errore viene catturato nei messaggi della sandbox.
• Timeout - La sandbox ha superato il timeout configurato. Il lavoro svolto prima del timeout è preservato se commitato.
• Errore API - Il provider IA ha restituito un errore (rate limit, chiave non valida, errore del server).

Recupero del run

CodeCourier attualmente non supporta la ripresa di un run fallito dal punto di fallimento. Se un run fallisce, puoi avviare un nuovo run con lo stesso prompt. Il nuovo run parte da zero, ma se il run precedente ha pushato commit sulla branch, il nuovo run riprende da dove il codice si è interrotto.

Fermarsi dopo il turno attuale

Oltre all’annullamento immediato, puoi impostare il flag stopAfterCurrentTurn su un workflow in esecuzione. È un arresto graduale che consente al turno di agente in esecuzione di completarsi prima di fermare il run. È utile quando vuoi revisionare un avanzamento parziale senza perdere il lavoro già in corso.

Quando stopAfterCurrentTurn è impostato:

1. L’orchestratore completa il turno di agente attuale (l’IA termina la sua risposta attuale, l’uso degli strumenti ed eventuali commit di file).
2. Anziché procedere alla iterazione o allo step successivo, il run passa apaused.
3. Le modifiche di codice commitate durante il turno finale vengono preservate sulla branch.

Puoi impostare questo flag dalla pagina di dettaglio del run usando il pulsante « Stop after turn », disponibile mentre il run è nello stato running. È preferibile a un annullamento brusco quando vuoi un punto di arresto pulito anziché un’interruzione improvvisa.

Tracciamento dei CI Check

Dopo che un run crea una pull request, CodeCourier traccia lo status dei CI check per quella PR. L’oggetto ciChecks del record del run riflette l’ultimo status dall’API di check di 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
}

Quando i CI check della PR di un run falliscono, lo status della PR del run passa a blocked_on_ci. Questo status è distinto dagli altri stati della PR e indica che la PR esiste ed è aperta, ma non può essere mergiata finché la CI non passa.

Valori dello status della PR

Il campo prStatus di un run traccia l’intero ciclo di vita della pull request associata:

• creating - La richiesta di creazione della PR è stata inviata ma non si è ancora completata.
• created - La PR è aperta e in attesa di revisione. I CI check potrebbero essere in esecuzione.
• blocked_on_ci - La PR è aperta ma i CI check falliscono. L’oggetto ciChecks contiene dettagli su quali check sono falliti.
• merged - La PR è stata mergiata nella branch di destinazione.
• failed - Il tentativo di creazione della PR è fallito (ad esempio, errore dell’API GitHub, fallimento di autenticazione). Il campo prError contiene il messaggio di errore.
• skipped - Nessuna modifica di codice è stata prodotta dal run, quindi nessuna PR è stata creata.

Punteggi di qualità

Se il workflow include uno step Evaluator, il record del run traccia unqualityScore complessivo (il punteggio composite di tutti gli step evaluator). I singoli record di run step portano l’intera scomposizione 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
}

I punteggi di qualità sono visibili nella timeline degli step della vista di dettaglio del run e nel dashboard di Monitoring. I run con punteggi di qualità bassi o un thresholdResult fallito vengono evidenziati visivamente in modo da risaltare nella lista dei run.

Annullare un run

Puoi annullare un workflow in esecuzione dalla pagina di dettaglio del run. L’annullamento:

1. Imposta lo status del run a cancelled.
2. Tenta di terminare qualsiasi sandbox attiva associata al run.
3. Impedisce all’orchestratore di elaborare ulteriori step.

L’annullamento è best-effort - se uno step è a metà esecuzione, la sandbox può continuare finché il comando di kill non ha effetto. Se vuoi un arresto più pulito, usa invece il flag stopAfterCurrentTurn (vedi sopra).

Metadati del run

Ogni record di run contiene metadati utili per il tracciamento e l’analisi:

{
  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
}