feat: add global and task-level TTL settings

Support TTL defaults at both the task definition level and globally in
trigger.config.ts, with per-trigger overrides still taking precedence.

Precedence order: per-trigger TTL > task-level TTL > dev default (10m)

https://claude.ai/code/session_01Swj2TA2crHC29m1ynWwEUN

Author: claude

.changeset/quiet-dogs-fly.md

@@ -0,0 +1,7 @@
+---
+"@trigger.dev/sdk": patch
+"@trigger.dev/core": patch
+"trigger.dev": patch
+---
+
+Add support for setting TTL (time-to-live) defaults at the task level and globally in trigger.config.ts, with per-trigger overrides still taking precedence

apps/webapp/app/runEngine/services/triggerTask.server.ts

@@ -190,10 +190,30 @@ export class RunEngineTriggerTaskService {
         }
       }
 
-      const ttl =
-        typeof body.options?.ttl === "number"
-          ? stringifyDuration(body.options?.ttl)
-          : body.options?.ttl ?? (environment.type === "DEVELOPMENT" ? "10m" : undefined);
+      // Resolve TTL with precedence: per-trigger > task-level > dev default
+      let ttl: string | undefined;
+
+      if (body.options?.ttl !== undefined) {
+        // Per-trigger TTL takes highest priority
+        ttl =
+          typeof body.options.ttl === "number"
+            ? stringifyDuration(body.options.ttl)
+            : body.options.ttl;
+      } else {
+        // Look up task-level TTL default from BackgroundWorkerTask
+        const taskDefaults = await this.prisma.backgroundWorkerTask.findFirst({
+          where: {
+            slug: taskId,
+            projectId: environment.projectId,
+            runtimeEnvironmentId: environment.id,
+          },
+          select: { ttl: true },
+          orderBy: { createdAt: "desc" },
+        });
+
+        ttl =
+          taskDefaults?.ttl ?? (environment.type === "DEVELOPMENT" ? "10m" : undefined);
+      }
 
       // Get parent run if specified
       const parentRun = body.options?.parentRunId

apps/webapp/app/v3/services/createBackgroundWorker.server.ts

@@ -5,7 +5,7 @@ import {
   QueueManifest,
   TaskResource,
 } from "@trigger.dev/core/v3";
-import { BackgroundWorkerId } from "@trigger.dev/core/v3/isomorphic";
+import { BackgroundWorkerId, stringifyDuration } from "@trigger.dev/core/v3/isomorphic";
 import type { BackgroundWorker, TaskQueue, TaskQueueType } from "@trigger.dev/database";
 import cronstrue from "cronstrue";
 import { Prisma, PrismaClientOrTransaction } from "~/db.server";
@@ -280,6 +280,8 @@ async function createWorkerTask(
         triggerSource: task.triggerSource === "schedule" ? "SCHEDULED" : "STANDARD",
         fileId: tasksToBackgroundFiles?.get(task.id) ?? null,
         maxDurationInSeconds: task.maxDuration ? clampMaxDuration(task.maxDuration) : null,
+        ttl:
+          typeof task.ttl === "number" ? stringifyDuration(task.ttl) ?? null : task.ttl ?? null,
         queueId: queue.id,
         payloadSchema: task.payloadSchema as any,
       },

internal-packages/database/prisma/migrations/20260309120000_add_ttl_to_background_worker_task/migration.sql

@@ -0,0 +1,2 @@
+-- AlterTable
+ALTER TABLE "public"."BackgroundWorkerTask" ADD COLUMN IF NOT EXISTS "ttl" TEXT;

internal-packages/database/prisma/schema.prisma

@@ -569,6 +569,8 @@ model BackgroundWorkerTask {
 
   maxDurationInSeconds Int?
 
+  ttl String?
+
   triggerSource TaskTriggerSource @default(STANDARD)
 
   payloadSchema Json?

packages/cli-v3/src/entryPoints/dev-index-worker.ts

@@ -131,6 +131,20 @@ if (typeof config.maxDuration === "number") {
   });
 }
 
+// If the config has a TTL, we need to apply it to all tasks that don't have a TTL
+if (config.ttl !== undefined) {
+  tasks = tasks.map((task) => {
+    if (task.ttl === undefined) {
+      return {
+        ...task,
+        ttl: config.ttl,
+      } satisfies TaskManifest;
+    }
+
+    return task;
+  });
+}
+
 // If the config has a machine preset, we need to apply it to all tasks that don't have a machine preset
 if (typeof config.machine === "string") {
   tasks = tasks.map((task) => {

packages/cli-v3/src/entryPoints/managed-index-worker.ts

@@ -131,6 +131,20 @@ if (typeof config.maxDuration === "number") {
   });
 }
 
+// If the config has a TTL, we need to apply it to all tasks that don't have a TTL
+if (config.ttl !== undefined) {
+  tasks = tasks.map((task) => {
+    if (task.ttl === undefined) {
+      return {
+        ...task,
+        ttl: config.ttl,
+      } satisfies TaskManifest;
+    }
+
+    return task;
+  });
+}
+
 // If the config has a machine preset, we need to apply it to all tasks that don't have a machine preset
 if (typeof config.machine === "string") {
   tasks = tasks.map((task) => {

packages/core/src/v3/config.ts

@@ -176,6 +176,25 @@ export type TriggerConfig = {
    */
   maxDuration: number;
 
+  /**
+   * Set a default time-to-live (TTL) for all task runs in the project. If a run is not executed within this time, it will be removed from the queue and never execute.
+   *
+   * This can be a string like "1h" (1 hour), "30m" (30 minutes), "1d" (1 day), or a number of seconds.
+   *
+   * You can override this on a per-task basis by setting the `ttl` option on the task definition, or per-trigger by setting the `ttl` option when triggering.
+   *
+   * @example
+   *
+   * ```ts
+   * export default defineConfig({
+   *   project: "my-project",
+   *   maxDuration: 3600,
+   *   ttl: "1h",
+   * });
+   * ```
+   */
+  ttl?: string | number;
+
   /**
    * Enable console logging while running the dev CLI. This will print out logs from console.log, console.warn, and console.error. By default all logs are sent to the trigger.dev backend, and not logged to the console.
    */

packages/core/src/v3/schemas/schemas.ts

@@ -189,6 +189,7 @@ const taskMetadata = {
   triggerSource: z.string().optional(),
   schedule: ScheduleMetadata.optional(),
   maxDuration: z.number().optional(),
+  ttl: z.string().or(z.number().nonnegative()).optional(),
   payloadSchema: z.unknown().optional(),
 };
 

packages/core/src/v3/types/tasks.ts

@@ -277,6 +277,29 @@ type CommonTaskOptions<
    */
   maxDuration?: number;
 
+  /**
+   * Set a default time-to-live for runs of this task. If the run is not executed within this time, it will be removed from the queue and never execute.
+   *
+   * This can be a string like "1h" (1 hour), "30m" (30 minutes), "1d" (1 day), or a number of seconds.
+   *
+   * If omitted it will use the value in your `trigger.config.ts` file, if set.
+   *
+   * You can override this on a per-trigger basis by setting the `ttl` option when triggering the task.
+   *
+   * @example
+   *
+   * ```ts
+   * export const myTask = task({
+   *   id: "my-task",
+   *   ttl: "10m",
+   *   run: async (payload) => {
+   *     //...
+   *   },
+   * });
+   * ```
+   */
+  ttl?: string | number;
+
   /** This gets called when a task is triggered. It's where you put the code you want to execute.
    *
    * @param payload - The payload that is passed to your task when it's triggered. This must be JSON serializable.