introduce maximum ttl via the RUN_ENGINE_DEFAULT_MAX_TTL optional env var, set at engine level

Author: ericallam

apps/webapp/app/env.server.ts

@@ -600,6 +600,10 @@ const EnvironmentSchema = z
     RUN_ENGINE_TTL_SYSTEM_POLL_INTERVAL_MS: z.coerce.number().int().default(1_000),
     RUN_ENGINE_TTL_SYSTEM_BATCH_SIZE: z.coerce.number().int().default(100),
 
+    /** Optional maximum TTL for all runs (e.g. "14d"). If set, runs without an explicit TTL
+     *  will use this as their TTL, and runs with a TTL larger than this will be clamped. */
+    RUN_ENGINE_DEFAULT_MAX_TTL: z.string().optional(),
+
     RUN_ENGINE_RUN_LOCK_DURATION: z.coerce.number().int().default(5000),
     RUN_ENGINE_RUN_LOCK_AUTOMATIC_EXTENSION_THRESHOLD: z.coerce.number().int().default(1000),
     RUN_ENGINE_RUN_LOCK_MAX_RETRIES: z.coerce.number().int().default(10),

apps/webapp/app/v3/runEngine.server.ts

@@ -110,6 +110,7 @@ function createRunEngine() {
     },
     tracer,
     meter,
+    defaultMaxTtl: env.RUN_ENGINE_DEFAULT_MAX_TTL,
     heartbeatTimeoutsMs: {
       PENDING_EXECUTING: env.RUN_ENGINE_TIMEOUT_PENDING_EXECUTING,
       PENDING_CANCEL: env.RUN_ENGINE_TIMEOUT_PENDING_CANCEL,

internal-packages/run-engine/src/engine/index.ts

@@ -15,7 +15,11 @@ import {
   TaskRunInternalError,
 } from "@trigger.dev/core/v3";
 import { TaskRunError } from "@trigger.dev/core/v3/schemas";
-import { RunId, WaitpointId } from "@trigger.dev/core/v3/isomorphic";
+import {
+  parseNaturalLanguageDurationInMs,
+  RunId,
+  WaitpointId,
+} from "@trigger.dev/core/v3/isomorphic";
 import {
   Prisma,
   PrismaClient,
@@ -552,6 +556,9 @@ export class RunEngine {
 
         const status = delayUntil ? "DELAYED" : "PENDING";
 
+        // Apply defaultMaxTtl: use as default when no TTL is provided, clamp when larger
+        const resolvedTtl = this.#resolveMaxTtl(ttl);
+
         //create run
         let taskRun: TaskRun & { associatedWaitpoint: Waitpoint | null };
         const taskRunId = RunId.fromFriendlyId(friendlyId);
@@ -595,7 +602,7 @@ export class RunEngine {
               taskEventStore,
               priorityMs,
               queueTimestamp: queueTimestamp ?? delayUntil ?? new Date(),
-              ttl,
+              ttl: resolvedTtl,
               tags:
                 tags.length === 0
                   ? undefined
@@ -2265,6 +2272,33 @@ export class RunEngine {
     }
   }
 
+  /**
+   * Applies `defaultMaxTtl` to a run's TTL:
+   * - No max configured → pass through as-is.
+   * - No TTL on the run → use the max as the default.
+   * - Both exist → clamp to the smaller value.
+   */
+  #resolveMaxTtl(ttl: string | undefined): string | undefined {
+    const maxTtl = this.options.defaultMaxTtl;
+
+    if (!maxTtl) {
+      return ttl;
+    }
+
+    if (!ttl) {
+      return maxTtl;
+    }
+
+    const ttlMs = parseNaturalLanguageDurationInMs(ttl);
+    const maxTtlMs = parseNaturalLanguageDurationInMs(maxTtl);
+
+    if (ttlMs === undefined || maxTtlMs === undefined) {
+      return ttl;
+    }
+
+    return ttlMs <= maxTtlMs ? ttl : maxTtl;
+  }
+
   async #concurrencySweeperCallback(
     runIds: string[],
     completedAtOffsetMs: number = 1000 * 60 * 10

internal-packages/run-engine/src/engine/types.ts

@@ -129,6 +129,9 @@ export type RunEngineOptions = {
     factor?: number;
   };
   queueRunsWaitingForWorkerBatchSize?: number;
+  /** Optional maximum TTL for all runs (e.g. "14d"). If set, runs without an explicit TTL
+   *  will use this as their TTL, and runs with a TTL larger than this will be clamped. */
+  defaultMaxTtl?: string;
   tracer: Tracer;
   meter?: Meter;
   logger?: Logger;