Trigger.dev

Trigger.dev è il motore di elaborazione dei job in background che alimenta tutte le operazioni di lunga durata di CodeCourier. Mentre il backend Convex gestisce i dati in tempo reale e il frontend Next.js renderizza la dashboard, Trigger.dev gestisce l’orchestrazione dei workflow degli agenti di coding IA -- task che possono girare per minuti o persino ore. Questa pagina spiega cosa offre Trigger.dev, i task specifici che CodeCourier definisce, come monitorarli e i dettagli di configurazione.

Cosa offre Trigger.dev

Trigger.dev è una piattaforma di job in background orientata a TypeScript che offre:

• Esecuzione durevole -- I task sopravvivono ai riavvii del server e possono girare per periodi prolungati senza andare in timeout.
• Retry automatici -- I task falliti possono essere ritentati automaticamente con strategie di backoff configurabili.
• Orchestrazione dei subtask -- I task possono attivare altri task e attendere i loro risultati, abilitando workflow complessi in più fasi.
• Monitoraggio in tempo reale -- La dashboard Trigger.dev mostra lo stato dei task, i log e la cronologia di esecuzione.
• Controllo della concorrenza -- I task possono essere configurati con limiti di concorrenza per evitare l’esaurimento delle risorse.

Definizioni dei task CodeCourier

CodeCourier definisce i seguenti task Trigger.dev nella directory trigger/:

workflowOrchestrator

Il principale motore di esecuzione dei workflow. Quando un utente attiva un run di workflow, questo task subentra e gestisce l’intero ciclo di vita dell’esecuzione:

1. Crea il record del run in Convex
2. Fornisce una sandbox E2B
3. Esegue in sequenza i passaggi della pipeline (designer, checker, optimizer)
4. Gestisce la logica di iterazione dei cicli designer-checker
5. Riporta l’avanzamento a Convex dopo ogni passaggio
6. Crea le pull request al completamento
7. Attiva l’estrazione dei learning dalla trascrizione della sessione
8. Ripulisce le sandbox una volta terminato

workChainOrchestrator

Orchestra l’esecuzione sequenziale delle issue di una work chain. Ogni issue diventa un run separato all’interno della catena, eseguito uno dopo l’altro. La catena traccia l’avanzamento complessivo e gestisce i fallimenti a livello di issue.

designerStep

Esegue un singolo passaggio designer all’interno di un run di workflow. Il designer è l’agente di coding IA principale che riceve il prompt del task e implementa le modifiche richieste all’interno della sandbox.

checkerStep

Esegue un passaggio checker che esamina il lavoro del designer. Il checker ispeziona le modifiche apportate nella sandbox e fornisce un verdetto (superato o fallito) con feedback dettagliato. Se il controllo fallisce, il feedback viene rimandato al designer per l’iterazione successiva.

optimizerStep

Esegue una passata di ottimizzazione sul codice prodotto dai passaggi precedenti. L’optimizer si concentra sui miglioramenti della qualità del codice, sull’ottimizzazione delle prestazioni e sul rispetto delle best practice.

prompterStep

Un passaggio specializzato che genera o affina i prompt per i passaggi successivi. Usato nelle pipeline personalizzate in cui il prompt engineering fa parte del workflow.

deepDiveStep

Esegue un’indagine approfondita in una specifica area problematica. Usato per task complessi di debugging o di analisi architetturale che richiedono un’esplorazione approfondita del codebase.

issueSession

Gestisce la issue discovery per un progetto. Questo task fornisce una sandbox, esegue l’agente IA per analizzare il codebase e identifica bug, debito tecnico e opportunità di miglioramento, producendo un elenco strutturato di issue.

sandboxMessage

Gestisce l’invio di un messaggio utente a una sandbox in esecuzione e l’elaborazione della risposta dell’agente. Questo task viene inviato quando un utente invia un messaggio tramite l’interfaccia di chat della sandbox.

learningExtraction

Viene eseguito dopo che una sessione di sandbox è completata. Questo task analizza la trascrizione della conversazione tra l’utente e l’agente IA per estrarre learning riutilizzabili -- pattern, preferenze, insidie e best practice che possono migliorare le sessioni future.

mergeAgent

Un task specializzato che unisce i branch dei run di sprint completati in un unico branch. Il merge agent fornisce la propria sandbox, effettua il pull di tutti i branch, risolve i conflitti e crea una pull request finale.

Comunicazione tramite callback

I task Trigger.dev comunicano con Convex tramite l’endpoint di callback HTTP all’indirizzo /trigger/callback. Questo è necessario perché i task Trigger.dev vengono eseguiti nel proprio ambiente di runtime e non possono chiamare direttamente le funzioni Convex. Il meccanismo di callback funziona come segue:

1. Il task invia una richiesta HTTP POST all’URL di deployment di Convex con il percorso /trigger/callback.
2. La richiesta include un bearer token per l’autenticazione e un corpo JSON con il nome dell’operazione e gli argomenti.
3. Il gestore HTTP di Convex indirizza l’operazione alla funzione interna appropriata.
4. Il risultato viene restituito come JSON e il task prosegue in base alla risposta.

Questo pattern mantiene il backend Convex come unica fonte di verità, consentendo al contempo ai task Trigger.dev di aggiornare lo stato in modo affidabile.

Installazione e configurazione

Variabili d’ambiente

• TRIGGER_SECRET_KEY -- La chiave segreta del progetto Trigger.dev. Usata dall’SDK per autenticarsi con l’API Trigger.dev.
• TRIGGER_CALLBACK_SECRET -- Un segreto condiviso usato dai task Trigger.dev per autenticarsi con l’endpoint di callback Convex. Deve essere impostato sia nell’ambiente Trigger.dev che nel deployment Convex.

Configurazione del build

Il build Trigger.dev è configurato in trigger.config.ts nella radice del progetto. Questo file specifica:

• L’ID del progetto per il deployment Trigger.dev
• I plugin e le dipendenze di build
• Eventuali pacchetti esterni che devono essere impacchettati con il runtime Trigger.dev

Monitorare i task

Dashboard Trigger.dev

La dashboard web di Trigger.dev offre visibilità in tempo reale sull’esecuzione dei task:

• Elenco dei run -- Mostra tutte le esecuzioni dei task con il loro stato, la durata e i timestamp.
• Dettaglio del run -- Mostra il log completo di esecuzione di un task specifico, incluse le invocazioni dei subtask e i loro risultati.
• Tracciamento degli errori -- I task falliti mostrano il messaggio di errore e lo stack trace per il debugging.

Dashboard CodeCourier

La dashboard CodeCourier mostra anche lo stato dei run Trigger.dev tramite il componente TriggerRunStatus. Questo componente usa il pacchetto @trigger.dev/react-hooks per sottoscriversi agli aggiornamenti di stato dei task in tempo reale e li mostra in linea con le card di sandbox e run.

Flusso di esecuzione dei task

Ecco il flusso di esecuzione tipico per un workflow designer-checker:

1. L’utente clicca su « Avvia run » nella dashboard.
2. L’action Convex runActions.startRun crea un record di run e invia il task Trigger.dev workflowOrchestrator.
3. L’orchestratore chiama l’API di callback per leggere la configurazione del workflow e le impostazioni del progetto.
4. L’orchestratore fornisce una sandbox E2B e invia il subtask designerStep.
5. Il passaggio designer invia il prompt all’agente IA all’interno della sandbox e trasmette la risposta in streaming.
6. Dopo che il designer è completato, l’orchestratore invia il subtask checkerStep.
7. Il checker esamina il lavoro e restituisce un verdetto. Se fallisce, il ciclo si ripete dal passaggio 4.
8. In caso di successo o al raggiungimento del numero massimo di iterazioni, l’orchestratore crea una PR e attiva l’estrazione dei learning.
9. La sandbox viene terminata e lo stato del run viene impostato su « completed ».

Risoluzione dei problemi

Task bloccati in stato di attesa

• Controlla i limiti di concorrenza nella dashboard Trigger.dev. Se sono in esecuzione troppi task, quelli nuovi potrebbero essere messi in coda.
• Verifica che TRIGGER_SECRET_KEY sia corretta e che il progetto Trigger.dev sia attivo.

Errori di callback

• Controlla che TRIGGER_CALLBACK_SECRET corrisponda sia nell’ambiente Trigger.dev che nel deployment Convex.
• Guarda i log delle funzioni Convex per i messaggi di errore del gestore di callback.

Task che falliscono dopo la creazione della sandbox

• Di solito questo indica chiavi API di provider mancanti (Anthropic, E2B, GitHub). Assicurati che tutte le chiavi richieste siano configurate nelle impostazioni del progetto.