Trigger.dev

How CodeCourier uses Trigger.dev for background job processing, workflow orchestration, and long-running AI agent tasks.

9 min read
trigger.devbackground-jobsorchestration

Trigger.dev is the background job processing engine that powers all of CodeCourier's long-running operations. While the Convex backend handles real-time data and the Next.js frontend renders the dashboard, Trigger.dev manages the orchestration of AI coding agent workflows -- tasks that can run for minutes or even hours. This page explains what Trigger.dev provides, the specific tasks CodeCourier defines, how to monitor them, and configuration details.

What Trigger.dev Provides

Trigger.dev is a TypeScript-first background job platform that provides:

  • Durable execution -- Tasks survive server restarts and can run for extended periods without timing out.
  • Automatic retries -- Failed tasks can be automatically retried with configurable backoff strategies.
  • Subtask orchestration -- Tasks can trigger other tasks and wait for their results, enabling complex multi-step workflows.
  • Real-time monitoring -- The Trigger.dev dashboard shows task status, logs, and execution history.
  • Concurrency control -- Tasks can be configured with concurrency limits to prevent resource exhaustion.

CodeCourier Task Definitions

CodeCourier defines the following Trigger.dev tasks in the trigger/ directory:

workflowOrchestrator

The main workflow execution engine. When a user triggers a workflow run, this task takes over and manages the entire execution lifecycle:

  1. Creates the run record in Convex
  2. Provisions an E2B sandbox
  3. Executes pipeline steps (designer, checker, optimizer) in sequence
  4. Handles iteration logic for designer-checker loops
  5. Reports progress back to Convex after each step
  6. Creates pull requests on completion
  7. Triggers learning extraction from the session transcript
  8. Cleans up sandboxes when done

workChainOrchestrator

Orchestrates sequential execution of issues from a work chain. Each issue becomes a separate run within the chain, executed one after another. The chain tracks overall progress and handles failures at the issue level.

designerStep

Executes a single designer step within a workflow run. The designer is the primary AI coding agent that receives the task prompt and implements the requested changes inside the sandbox.

checkerStep

Executes a checker step that reviews the designer's work. The checker examines the changes made in the sandbox and provides a verdict (pass or fail) with detailed feedback. If the check fails, the feedback is passed back to the designer for the next iteration.

optimizerStep

Runs an optimization pass on the code produced by previous steps. The optimizer focuses on code quality improvements, performance optimization, and adherence to best practices.

prompterStep

A specialized step that generates or refines prompts for subsequent steps. Used in custom pipelines where prompt engineering is part of the workflow.

deepDiveStep

Performs deep investigation into a specific problem area. Used for complex debugging or architectural analysis tasks that require thorough exploration of the codebase.

issueSession

Manages issue discovery for a project. This task provisions a sandbox, runs the AI agent to analyze the codebase, and identifies bugs, technical debt, and improvement opportunities, producing a structured list of issues.

sandboxMessage

Handles sending a user message to a running sandbox and processing the agent's response. This task is dispatched when a user sends a message through the sandbox chat interface.

learningExtraction

Runs after a sandbox session completes. This task analyzes the conversation transcript between the user and the AI agent to extract reusable learnings -- patterns, preferences, gotchas, and best practices that can improve future sessions.

mergeAgent

A specialized task that merges branches from completed sprint runs into a single branch. The merge agent provisions its own sandbox, pulls all branches, resolves conflicts, and creates a final pull request.

Callback Communication

Trigger.dev tasks communicate with Convex through the HTTP callback endpoint at /trigger/callback. This is necessary because Trigger.dev tasks run in their own runtime environment and cannot directly call Convex functions. The callback mechanism works as follows:

  1. The task sends an HTTP POST request to the Convex deployment URL with the path /trigger/callback.
  2. The request includes a bearer token for authentication and a JSON body with the operation name and arguments.
  3. The Convex HTTP handler dispatches the operation to the appropriate internal function.
  4. The result is returned as JSON, and the task continues based on the response.

This pattern keeps the Convex backend as the single source of truth while allowing Trigger.dev tasks to update state reliably.

Setup and Configuration

Environment Variables

  • TRIGGER_SECRET_KEY -- The Trigger.dev project secret key. Used by the SDK to authenticate with the Trigger.dev API.
  • TRIGGER_CALLBACK_SECRET -- A shared secret used by Trigger.dev tasks to authenticate with the Convex callback endpoint. This must be set in both the Trigger.dev environment and the Convex deployment.

Build Configuration

The Trigger.dev build is configured in trigger.config.ts at the project root. This file specifies:

  • The project ID for the Trigger.dev deployment
  • Build plugins and dependencies
  • Any external packages that need to be bundled with the Trigger.dev runtime

Monitoring Tasks

Trigger.dev Dashboard

The Trigger.dev web dashboard provides real-time visibility into task execution:

  • Runs list -- Shows all task executions with their status, duration, and timestamps.
  • Run detail -- Shows the full execution log for a specific task, including subtask invocations and their results.
  • Error tracking -- Failed tasks show the error message and stack trace for debugging.

CodeCourier Dashboard

The CodeCourier dashboard also displays Trigger.dev run status through the TriggerRunStatus component. This component uses the @trigger.dev/react-hooks package to subscribe to real-time task status updates and displays them inline with sandbox and run cards.

Task Execution Flow

Here is the typical execution flow for a designer-checker workflow:

  1. User clicks "Start Run" in the dashboard.
  2. The runActions.startRun Convex action creates a run record and dispatches the workflowOrchestrator Trigger.dev task.
  3. The orchestrator calls the callback API to read the workflow configuration and project settings.
  4. The orchestrator provisions an E2B sandbox and dispatches the designerStep subtask.
  5. The designer step sends the prompt to the AI agent inside the sandbox and streams the response.
  6. After the designer completes, the orchestrator dispatches the checkerStep subtask.
  7. The checker reviews the work and returns a verdict. If it fails, the loop repeats from step 4.
  8. On success or max iterations reached, the orchestrator creates a PR and triggers learning extraction.
  9. The sandbox is killed and the run status is set to "completed".

Troubleshooting

Tasks stuck in pending state

  • Check the Trigger.dev dashboard for concurrency limits. If too many tasks are running, new ones may queue.
  • Verify the TRIGGER_SECRET_KEY is correct and the Trigger.dev project is active.

Callback errors

  • Check that TRIGGER_CALLBACK_SECRET matches in both the Trigger.dev environment and the Convex deployment.
  • Look at the Convex function logs for error messages from the callback handler.

Tasks failing after sandbox creation

  • This usually indicates missing provider API keys (Anthropic, E2B, GitHub). Ensure all required keys are configured in project settings.