Trigger.dev

Trigger.dev ist die Hintergrund-Job-Engine, die alle langlaufenden Operationen von CodeCourier antreibt. Während das Convex-Backend Echtzeitdaten verarbeitet und das Next.js-Frontend das Dashboard rendert, übernimmt Trigger.dev die Orchestrierung der KI-Coding- Agent-Workflows -- Tasks, die Minuten oder sogar Stunden laufen können. Diese Seite erklärt, was Trigger.dev bietet, welche Tasks CodeCourier definiert, wie Sie sie überwachen und welche Konfigurationsdetails relevant sind.

Was Trigger.dev bietet

Trigger.dev ist eine TypeScript-first-Hintergrund-Job-Plattform und bietet:

• Dauerhafte Ausführung -- Tasks überstehen Server-Neustarts und können über längere Zeit laufen, ohne abzulaufen.
• Automatische Wiederholungen -- Fehlgeschlagene Tasks können mit konfigurierbaren Backoff-Strategien automatisch wiederholt werden.
• Subtask-Orchestrierung -- Tasks können weitere Tasks auslösen und auf deren Ergebnisse warten, was komplexe mehrstufige Workflows ermöglicht.
• Echtzeit-Monitoring -- Das Trigger.dev- Dashboard zeigt Task-Status, Logs und Ausführungshistorie an.
• Concurrency-Steuerung -- Tasks können mit Concurrency-Limits konfiguriert werden, um Ressourcen- erschöpfung zu vermeiden.

CodeCourier Task-Definitionen

CodeCourier definiert die folgenden Trigger.dev-Tasks im Verzeichnis trigger/:

workflowOrchestrator

Die zentrale Workflow-Ausführungs-Engine. Wenn ein Benutzer einen Workflow-Run startet, übernimmt dieser Task und verwaltet den gesamten Ausführungslebenszyklus:

1. Erstellt den Run-Datensatz in Convex
2. Provisioniert eine E2B-Sandbox
3. Führt Pipeline-Schritte (Designer, Checker, Optimizer) in der Reihenfolge aus
4. Verarbeitet die Iterationslogik für Designer-Checker-Schleifen
5. Meldet den Fortschritt nach jedem Schritt an Convex
6. Erstellt nach Abschluss Pull Requests
7. Stößt die Learning-Extraktion aus dem Session-Transkript an
8. Bereinigt Sandboxes nach Abschluss

workChainOrchestrator

Orchestriert die sequenzielle Ausführung von Issues einer Work Chain. Jedes Issue wird zu einem separaten Run innerhalb der Chain, die nacheinander ausgeführt werden. Die Chain verfolgt den Gesamtfortschritt und verarbeitet Fehler auf Issue-Ebene.

designerStep

Führt einen einzelnen Designer-Schritt innerhalb eines Workflow- Runs aus. Der Designer ist der primäre KI-Coding-Agent, der den Aufgaben-Prompt empfängt und die gewünschten Änderungen innerhalb der Sandbox umsetzt.

checkerStep

Führt einen Checker-Schritt aus, der die Arbeit des Designers überprüft. Der Checker analysiert die in der Sandbox vorgenommenen Änderungen und liefert ein Urteil (pass oder fail) mit detailliertem Feedback. Schlägt die Prüfung fehl, wird das Feedback für die nächste Iteration an den Designer zurückgegeben.

optimizerStep

Führt einen Optimierungsdurchlauf auf dem Code aus, der in vorherigen Schritten erzeugt wurde. Der Optimizer konzentriert sich auf Verbesserungen der Codequalität, Performance-Optimierung und die Einhaltung bewährter Praktiken.

prompterStep

Ein spezialisierter Schritt, der Prompts für nachfolgende Schritte erzeugt oder verfeinert. Wird in benutzerdefinierten Pipelines eingesetzt, in denen Prompt-Engineering Teil des Workflows ist.

deepDiveStep

Führt eine tiefgehende Untersuchung eines bestimmten Problembereichs durch. Wird für komplexes Debugging oder architektonische Analysen verwendet, die eine gründliche Exploration der Codebasis erfordern.

issueSession

Verwaltet die Issue-Discovery für ein Projekt. Dieser Task provisioniert eine Sandbox, lässt den KI-Agent die Codebasis analysieren und identifiziert Bugs, technische Schulden und Verbesserungspotenziale. Das Ergebnis ist eine strukturierte Issue-Liste.

sandboxMessage

Verarbeitet das Senden einer Benutzer-Nachricht an eine laufende Sandbox und die Verarbeitung der Agent-Antwort. Dieser Task wird ausgelöst, wenn ein Benutzer eine Nachricht über die Sandbox-Chat- Oberfläche sendet.

learningExtraction

Wird nach Abschluss einer Sandbox-Session ausgeführt. Dieser Task analysiert das Konversations-Transkript zwischen Benutzer und KI-Agent, um wiederverwendbare Learnings zu extrahieren -- Muster, Vorlieben, Stolperfallen und Best Practices, die zukünftige Sessions verbessern.

mergeAgent

Ein spezialisierter Task, der Branches aus abgeschlossenen Sprint- Runs in einen einzelnen Branch zusammenführt. Der Merge-Agent provisioniert seine eigene Sandbox, holt alle Branches, löst Konflikte auf und erstellt einen finalen Pull Request.

Callback-Kommunikation

Trigger.dev-Tasks kommunizieren mit Convex über den HTTP-Callback- Endpoint unter /trigger/callback. Dies ist nötig, weil Trigger.dev-Tasks in ihrer eigenen Laufzeitumgebung ausgeführt werden und Convex-Funktionen nicht direkt aufrufen können. Der Callback-Mechanismus funktioniert wie folgt:

1. Der Task sendet einen HTTP-POST-Request an die Convex-Deployment- URL mit dem Pfad /trigger/callback.
2. Der Request enthält ein Bearer-Token zur Authentifizierung sowie einen JSON-Body mit Operationsnamen und Argumenten.
3. Der Convex-HTTP-Handler leitet die Operation an die passende interne Funktion weiter.
4. Das Ergebnis wird als JSON zurückgegeben, und der Task fährt basierend auf der Antwort fort.

Dieses Muster hält das Convex-Backend als Single Source of Truth, während Trigger.dev-Tasks den Zustand zuverlässig aktualisieren können.

Einrichtung und Konfiguration

Umgebungsvariablen

• TRIGGER_SECRET_KEY -- Der projektbezogene Trigger.dev-Secret-Key. Wird vom SDK zur Authentifizierung gegen die Trigger.dev-API verwendet.
• TRIGGER_CALLBACK_SECRET -- Ein gemeinsames Secret, mit dem sich Trigger.dev-Tasks am Convex-Callback-Endpoint authentifizieren. Dieses muss sowohl in der Trigger.dev-Umgebung als auch im Convex-Deployment gesetzt sein.

Build-Konfiguration

Der Trigger.dev-Build wird in trigger.config.ts im Projekt-Root konfiguriert. Diese Datei legt fest:

• Die Projekt-ID für das Trigger.dev-Deployment
• Build-Plugins und -Abhängigkeiten
• Alle externen Pakete, die mit der Trigger.dev-Runtime gebündelt werden müssen

Tasks überwachen

Trigger.dev-Dashboard

Das Trigger.dev-Web-Dashboard bietet Echtzeit-Einblick in die Task-Ausführung:

• Runs-Liste -- Zeigt alle Task-Ausführungen mit Status, Dauer und Zeitstempeln.
• Run-Details -- Zeigt das vollständige Ausführungs-Log für einen bestimmten Task, einschließlich Subtask-Aufrufen und deren Ergebnissen.
• Fehler-Tracking -- Fehlgeschlagene Tasks zeigen die Fehlermeldung und den Stack Trace zur Fehlerbehebung.

CodeCourier-Dashboard

Das CodeCourier-Dashboard zeigt den Trigger.dev-Run-Status ebenfalls über die Komponente TriggerRunStatus an. Diese Komponente nutzt das Paket @trigger.dev/react-hooks, um Echtzeit-Task-Status-Updates zu abonnieren und sie inline mit Sandbox- und Run-Karten darzustellen.

Task-Ausführungsablauf

Hier ist der typische Ausführungsablauf für einen Designer-Checker- Workflow:

1. Der Benutzer klickt im Dashboard auf "Start Run".
2. Die Convex-Action runActions.startRun erstellt einen Run-Datensatz und löst den Trigger.dev-Task workflowOrchestrator aus.
3. Der Orchestrator ruft die Callback-API auf, um Workflow- Konfiguration und Projekteinstellungen zu lesen.
4. Der Orchestrator provisioniert eine E2B-Sandbox und löst den Subtask designerStep aus.
5. Der Designer-Schritt sendet den Prompt an den KI-Agent in der Sandbox und streamt die Antwort.
6. Nach Abschluss des Designers löst der Orchestrator den Subtask checkerStep aus.
7. Der Checker prüft die Arbeit und liefert ein Urteil. Bei Fehlschlag wird die Schleife ab Schritt 4 wiederholt.
8. Bei Erfolg oder Erreichen der maximalen Iterationen erstellt der Orchestrator einen PR und löst die Learning-Extraktion aus.
9. Die Sandbox wird beendet und der Run-Status auf "completed" gesetzt.

Fehlerbehebung

Tasks bleiben im Pending-Zustand hängen

• Prüfen Sie im Trigger.dev-Dashboard die Concurrency-Limits. Wenn zu viele Tasks laufen, werden neue eventuell in eine Warteschlange gestellt.
• Stellen Sie sicher, dass TRIGGER_SECRET_KEY korrekt ist und das Trigger.dev-Projekt aktiv ist.

Callback-Fehler

• Prüfen Sie, ob TRIGGER_CALLBACK_SECRET in der Trigger.dev-Umgebung und im Convex-Deployment übereinstimmt.
• Schauen Sie in die Convex-Funktions-Logs nach Fehlermeldungen des Callback-Handlers.

Tasks schlagen nach Sandbox-Erstellung fehl

• Dies deutet meist auf fehlende Provider-API-Keys hin (Anthropic, E2B, GitHub). Stellen Sie sicher, dass alle erforderlichen Keys in den Projekteinstellungen konfiguriert sind.