feat(debounce): add maxDelay option to limit total debounce time

Add a per-trigger maxDelay option that limits how long a debounced run
can be delayed. This ensures execution happens within a specified window
even with continuous triggers.

Use case: Summarizing AI conversation threads that need to stay relatively
up to date while still debouncing rapid message triggers.

refs TRI-7234

Author: ericallam

.changeset/add-debounce-maxdelay.md

@@ -0,0 +1,16 @@
+---
+"@trigger.dev/core": patch
+"@trigger.dev/sdk": patch
+---
+
+Add `maxDelay` option to debounce feature. This allows setting a maximum time limit for how long a debounced run can be delayed, ensuring execution happens within a specified window even with continuous triggers.
+
+```typescript
+await myTask.trigger(payload, {
+  debounce: {
+    key: "my-key",
+    delay: "5s",
+    maxDelay: "30m", // Execute within 30 minutes regardless of continuous triggers
+  },
+});
+```

internal-packages/run-engine/src/engine/systems/debounceSystem.ts

@@ -6,7 +6,10 @@ import {
   type Result,
 } from "@internal/redis";
 import { startSpan } from "@internal/tracing";
-import { parseNaturalLanguageDuration } from "@trigger.dev/core/v3/isomorphic";
+import {
+  parseNaturalLanguageDuration,
+  parseNaturalLanguageDurationInMs,
+} from "@trigger.dev/core/v3/isomorphic";
 import { PrismaClientOrTransaction, TaskRun, Waitpoint } from "@trigger.dev/database";
 import { nanoid } from "nanoid";
 import { SystemResources } from "./systems.js";
@@ -17,6 +20,12 @@ export type DebounceOptions = {
   key: string;
   delay: string;
   mode?: "leading" | "trailing";
+  /**
+   * Maximum total delay before the run must execute, regardless of subsequent triggers.
+   * This prevents indefinite delays when continuous triggers keep pushing the execution time.
+   * If not specified, falls back to the server's maxDebounceDurationMs config.
+   */
+  maxDelay?: string;
   /** When mode: "trailing", these fields will be used to update the existing run */
   updateData?: {
     payload: string;
@@ -521,8 +530,22 @@ return 0
       }
 
       // Check if max debounce duration would be exceeded
+      // Use per-trigger maxDelay if provided, otherwise use global config
+      let maxDurationMs = this.maxDebounceDurationMs;
+      if (debounce.maxDelay) {
+        const parsedMaxDelay = parseNaturalLanguageDurationInMs(debounce.maxDelay);
+        if (parsedMaxDelay !== undefined) {
+          maxDurationMs = parsedMaxDelay;
+        } else {
+          this.$.logger.warn("handleExistingRun: invalid maxDelay duration, using global config", {
+            maxDelay: debounce.maxDelay,
+            fallbackMs: this.maxDebounceDurationMs,
+          });
+        }
+      }
+
       const runCreatedAt = existingRun.createdAt;
-      const maxDelayUntil = new Date(runCreatedAt.getTime() + this.maxDebounceDurationMs);
+      const maxDelayUntil = new Date(runCreatedAt.getTime() + maxDurationMs);
 
       if (newDelayUntil > maxDelayUntil) {
         this.$.logger.debug("handleExistingRun: max debounce duration would be exceeded", {
@@ -531,7 +554,8 @@ return 0
           runCreatedAt,
           newDelayUntil,
           maxDelayUntil,
-          maxDebounceDurationMs: this.maxDebounceDurationMs,
+          maxDurationMs,
+          maxDelayProvided: debounce.maxDelay,
         });
         // Clean up Redis key since this debounce window is closed
         await this.redis.del(redisKey);