@trigger.dev/sdk 0.0.0-prerelease-20251215135620 → 0.0.0-prerelease-20260120115202

package/dist/commonjs/v3/idempotencyKeys.d.ts

@@ -1,5 +1,6 @@
-import { createIdempotencyKey, type IdempotencyKey } from "@trigger.dev/core/v3";
+import { createIdempotencyKey, resetIdempotencyKey, type IdempotencyKey } from "@trigger.dev/core/v3";
 export declare const idempotencyKeys: {
     create: typeof createIdempotencyKey;
+    reset: typeof resetIdempotencyKey;
 };
 export type { IdempotencyKey };

package/dist/commonjs/v3/idempotencyKeys.js

@@ -4,5 +4,6 @@ exports.idempotencyKeys = void 0;
 const v3_1 = require("@trigger.dev/core/v3");
 exports.idempotencyKeys = {
     create: v3_1.createIdempotencyKey,
+    reset: v3_1.resetIdempotencyKey,
 };
 //# sourceMappingURL=idempotencyKeys.js.map

package/dist/commonjs/v3/idempotencyKeys.js.map

@@ -1 +1 @@
-{"version":3,"file":"idempotencyKeys.js","sourceRoot":"","sources":["../../../src/v3/idempotencyKeys.ts"],"names":[],"mappings":";;;AAAA,6CAAiF;AAEpE,QAAA,eAAe,GAAG;IAC7B,MAAM,EAAE,yBAAoB;CAC7B,CAAC"}
+{"version":3,"file":"idempotencyKeys.js","sourceRoot":"","sources":["../../../src/v3/idempotencyKeys.ts"],"names":[],"mappings":";;;AAAA,6CAAsG;AAEzF,QAAA,eAAe,GAAG;IAC7B,MAAM,EAAE,yBAAoB;IAC5B,KAAK,EAAE,wBAAmB;CAC3B,CAAC"}

package/dist/commonjs/v3/index.d.ts

@@ -1,7 +1,7 @@
 export * from "./cache.js";
 export * from "./config.js";
 export { retry, type RetryOptions } from "./retry.js";
-export { queue } from "./shared.js";
+export { queue, BatchTriggerError } from "./shared.js";
 export * from "./tasks.js";
 export * from "./batch.js";
 export * from "./wait.js";

package/dist/commonjs/v3/index.js

@@ -26,13 +26,14 @@ var __importStar = (this && this.__importStar) || function (mod) {
     return result;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.auth = exports.configure = exports.queues = exports.envvars = exports.schedules = exports.runs = exports.logger = exports.CompleteTaskWithOutput = exports.OutOfMemoryError = exports.AbortTaskRunError = exports.UnprocessableEntityError = exports.RateLimitError = exports.PermissionDeniedError = exports.NotFoundError = exports.InternalServerError = exports.ConflictError = exports.BadRequestError = exports.AuthenticationError = exports.ApiError = exports.queue = exports.retry = void 0;
+exports.auth = exports.configure = exports.queues = exports.envvars = exports.schedules = exports.runs = exports.logger = exports.CompleteTaskWithOutput = exports.OutOfMemoryError = exports.AbortTaskRunError = exports.UnprocessableEntityError = exports.RateLimitError = exports.PermissionDeniedError = exports.NotFoundError = exports.InternalServerError = exports.ConflictError = exports.BadRequestError = exports.AuthenticationError = exports.ApiError = exports.BatchTriggerError = exports.queue = exports.retry = void 0;
 __exportStar(require("./cache.js"), exports);
 __exportStar(require("./config.js"), exports);
 var retry_js_1 = require("./retry.js");
 Object.defineProperty(exports, "retry", { enumerable: true, get: function () { return retry_js_1.retry; } });
 var shared_js_1 = require("./shared.js");
 Object.defineProperty(exports, "queue", { enumerable: true, get: function () { return shared_js_1.queue; } });
+Object.defineProperty(exports, "BatchTriggerError", { enumerable: true, get: function () { return shared_js_1.BatchTriggerError; } });
 __exportStar(require("./tasks.js"), exports);
 __exportStar(require("./batch.js"), exports);
 __exportStar(require("./wait.js"), exports);

package/dist/commonjs/v3/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/v3/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,6CAA2B;AAC3B,8CAA4B;AAC5B,uCAAsD;AAA7C,iGAAA,KAAK,OAAA;AACd,yCAAoC;AAA3B,kGAAA,KAAK,OAAA;AACd,6CAA2B;AAC3B,6CAA2B;AAC3B,4CAA0B;AAC1B,iDAA+B;AAC/B,6CAA2B;AAC3B,uDAAqC;AACrC,4CAA0B;AAC1B,gDAA8B;AAC9B,+CAA6B;AAC7B,gDAA8B;AAC9B,8CAA4B;AAC5B,4CAA0B;AAC1B,+CAA6B;AAC7B,kDAAgC;AAChC,+CAA6B;AAS7B,2CAe8B;AAd5B,8FAAA,QAAQ,OAAA;AACR,yGAAA,mBAAmB,OAAA;AACnB,qGAAA,eAAe,OAAA;AACf,mGAAA,aAAa,OAAA;AACb,yGAAA,mBAAmB,OAAA;AACnB,mGAAA,aAAa,OAAA;AACb,2GAAA,qBAAqB,OAAA;AACrB,oGAAA,cAAc,OAAA;AACd,8GAAA,wBAAwB,OAAA;AACxB,uGAAA,iBAAiB,OAAA;AACjB,sGAAA,gBAAgB,OAAA;AAChB,4GAAA,sBAAsB,OAAA;AACtB,4FAAA,MAAM,OAAA;AAIR,qCASmB;AARjB,+FAAA,IAAI,OAAA;AASN,kEAAkD;AAClD,wDAAwC;AACxC,sDAAsC;AAGtC,qCAA4C;AAAnC,oGAAA,SAAS,OAAA;AAAE,+FAAA,IAAI,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/v3/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,6CAA2B;AAC3B,8CAA4B;AAC5B,uCAAsD;AAA7C,iGAAA,KAAK,OAAA;AACd,yCAAuD;AAA9C,kGAAA,KAAK,OAAA;AAAE,8GAAA,iBAAiB,OAAA;AACjC,6CAA2B;AAC3B,6CAA2B;AAC3B,4CAA0B;AAC1B,iDAA+B;AAC/B,6CAA2B;AAC3B,uDAAqC;AACrC,4CAA0B;AAC1B,gDAA8B;AAC9B,+CAA6B;AAC7B,gDAA8B;AAC9B,8CAA4B;AAC5B,4CAA0B;AAC1B,+CAA6B;AAC7B,kDAAgC;AAChC,+CAA6B;AAS7B,2CAe8B;AAd5B,8FAAA,QAAQ,OAAA;AACR,yGAAA,mBAAmB,OAAA;AACnB,qGAAA,eAAe,OAAA;AACf,mGAAA,aAAa,OAAA;AACb,yGAAA,mBAAmB,OAAA;AACnB,mGAAA,aAAa,OAAA;AACb,2GAAA,qBAAqB,OAAA;AACrB,oGAAA,cAAc,OAAA;AACd,8GAAA,wBAAwB,OAAA;AACxB,uGAAA,iBAAiB,OAAA;AACjB,sGAAA,gBAAgB,OAAA;AAChB,4GAAA,sBAAsB,OAAA;AACtB,4FAAA,MAAM,OAAA;AAIR,qCASmB;AARjB,+FAAA,IAAI,OAAA;AASN,kEAAkD;AAClD,wDAAwC;AACxC,sDAAsC;AAGtC,qCAA4C;AAAnC,oGAAA,SAAS,OAAA;AAAE,+FAAA,IAAI,OAAA"}

package/dist/commonjs/v3/shared.d.ts

@@ -1,10 +1,9 @@
 import { SerializableJson } from "@trigger.dev/core";
-import { ApiRequestOptions, InitOutput, Queue, QueueOptions, SubtaskUnwrapError, TaskFromIdentifier, TaskRunContext, TaskRunPromise } from "@trigger.dev/core/v3";
+import { ApiError, ApiRequestOptions, InitOutput, Queue, QueueOptions, SubtaskUnwrapError, TaskFromIdentifier, TaskRunContext, TaskRunPromise } from "@trigger.dev/core/v3";
 import type { AnyRunHandle, AnyTask, BatchByIdAndWaitItem, BatchByIdItem, BatchByIdResult, BatchByTaskAndWaitItem, BatchByTaskItem, BatchByTaskResult, BatchItem, BatchResult, BatchRunHandle, BatchRunHandleFromTypes, BatchTasksRunHandleFromTypes, BatchTriggerAndWaitOptions, BatchTriggerOptions, InferRunTypes, RunHandle, RunHandleFromTypes, RunHandleOutput, RunHandlePayload, Task, TaskBatchOutputHandle, TaskIdentifier, TaskOptions, TaskOptionsWithSchema, TaskOutput, TaskOutputHandle, TaskPayload, TaskRunResult, TaskSchema, TaskWithSchema, TaskWithSchemaOptions, TaskWithToolOptions, ToolTask, ToolTaskParameters, TriggerAndWaitOptions, TriggerApiRequestOptions, TriggerOptions } from "@trigger.dev/core/v3";
 export type { AnyRunHandle, AnyTask, BatchItem, BatchResult, BatchRunHandle, BatchTriggerOptions, Queue, RunHandle, RunHandleOutput, RunHandlePayload, SerializableJson, Task, TaskBatchOutputHandle, TaskFromIdentifier, TaskIdentifier, TaskOptions, TaskOutput, TaskOutputHandle, TaskPayload, TaskRunResult, TriggerOptions, TaskWithSchema, TaskWithSchemaOptions, TaskSchema, TaskOptionsWithSchema, };
 export { SubtaskUnwrapError, TaskRunPromise };
 export type Context = TaskRunContext;
-export { BatchTriggerError };
 export declare function queue(options: QueueOptions): Queue;
 export declare function createTask<TIdentifier extends string, TOutput = unknown, TInitOutput extends InitOutput = any>(params: TaskOptionsWithSchema<TIdentifier, TOutput, TInitOutput>): Task<TIdentifier, any, TOutput>;
 export declare function createTask<TIdentifier extends string, TInput = void, TOutput = unknown, TInitOutput extends InitOutput = any>(params: TaskOptions<TIdentifier, TInput, TOutput, TInitOutput>): Task<TIdentifier, TInput, TOutput>;
@@ -425,11 +424,23 @@ export declare function batchTriggerAndWaitTasks<TTasks extends readonly AnyTask
 /**
  * Error thrown when batch trigger operations fail.
  * Includes context about which phase failed and the batch details.
+ *
+ * When the underlying error is a rate limit (429), additional properties are exposed:
+ * - `isRateLimited`: true
+ * - `retryAfterMs`: milliseconds until the rate limit resets
  */
-declare class BatchTriggerError extends Error {
+export declare class BatchTriggerError extends Error {
     readonly phase: "create" | "stream";
     readonly batchId?: string;
     readonly itemCount: number;
+    /** True if the error was caused by rate limiting (HTTP 429) */
+    readonly isRateLimited: boolean;
+    /** Milliseconds until the rate limit resets. Only set when `isRateLimited` is true. */
+    readonly retryAfterMs?: number;
+    /** The underlying API error, if the cause was an ApiError */
+    readonly apiError?: ApiError;
+    /** The underlying cause of the error */
+    readonly cause?: unknown;
     constructor(message: string, options: {
         cause?: unknown;
         phase: "create" | "stream";

package/dist/commonjs/v3/shared.js

@@ -273,6 +273,7 @@ async function batchTriggerById(...args) {
                     priority: item.options?.priority,
                     region: item.options?.region,
                     lockToVersion: item.options?.version ?? (0, v3_1.getEnvVar)("TRIGGER_VERSION"),
+                    debounce: item.options?.debounce,
                 },
             };
         }));
@@ -366,6 +367,7 @@ async function batchTriggerByIdAndWait(...args) {
                     machine: item.options?.machine,
                     priority: item.options?.priority,
                     region: item.options?.region,
+                    debounce: item.options?.debounce,
                 },
             };
         }));
@@ -463,6 +465,7 @@ async function batchTriggerTasks(...args) {
                     priority: item.options?.priority,
                     region: item.options?.region,
                     lockToVersion: item.options?.version ?? (0, v3_1.getEnvVar)("TRIGGER_VERSION"),
+                    debounce: item.options?.debounce,
                 },
             };
         }));
@@ -557,6 +560,7 @@ async function batchTriggerAndWaitTasks(...args) {
                     machine: item.options?.machine,
                     priority: item.options?.priority,
                     region: item.options?.region,
+                    debounce: item.options?.debounce,
                 },
             };
         }));
@@ -642,6 +646,7 @@ async function executeBatchTwoPhase(apiClient, items, options, requestOptions) {
             parentRunId: options.parentRunId,
             resumeParentOnCompletion: options.resumeParentOnCompletion,
             idempotencyKey: options.idempotencyKey,
+            idempotencyKeyOptions: options.idempotencyKeyOptions,
         }, { spanParentAsLink: options.spanParentAsLink }, requestOptions);
     }
     catch (error) {
@@ -672,20 +677,74 @@ async function executeBatchTwoPhase(apiClient, items, options, requestOptions) {
 /**
  * Error thrown when batch trigger operations fail.
  * Includes context about which phase failed and the batch details.
+ *
+ * When the underlying error is a rate limit (429), additional properties are exposed:
+ * - `isRateLimited`: true
+ * - `retryAfterMs`: milliseconds until the rate limit resets
  */
 class BatchTriggerError extends Error {
     phase;
     batchId;
     itemCount;
+    /** True if the error was caused by rate limiting (HTTP 429) */
+    isRateLimited;
+    /** Milliseconds until the rate limit resets. Only set when `isRateLimited` is true. */
+    retryAfterMs;
+    /** The underlying API error, if the cause was an ApiError */
+    apiError;
+    /** The underlying cause of the error */
+    cause;
     constructor(message, options) {
-        super(message, { cause: options.cause });
+        // Build enhanced message that includes the cause's message
+        const fullMessage = buildBatchErrorMessage(message, options.cause);
+        super(fullMessage, { cause: options.cause });
         this.name = "BatchTriggerError";
+        this.cause = options.cause;
         this.phase = options.phase;
         this.batchId = options.batchId;
         this.itemCount = options.itemCount;
+        // Extract rate limit info from cause
+        if (options.cause instanceof v3_1.RateLimitError) {
+            this.isRateLimited = true;
+            this.retryAfterMs = options.cause.millisecondsUntilReset;
+            this.apiError = options.cause;
+        }
+        else if (options.cause instanceof v3_1.ApiError) {
+            this.isRateLimited = options.cause.status === 429;
+            this.apiError = options.cause;
+        }
+        else {
+            this.isRateLimited = false;
+        }
     }
 }
 exports.BatchTriggerError = BatchTriggerError;
+/**
+ * Build an enhanced error message that includes context from the cause.
+ */
+function buildBatchErrorMessage(baseMessage, cause) {
+    if (!cause) {
+        return baseMessage;
+    }
+    // Handle RateLimitError specifically for better messaging
+    if (cause instanceof v3_1.RateLimitError) {
+        const retryMs = cause.millisecondsUntilReset;
+        if (retryMs !== undefined) {
+            const retrySeconds = Math.ceil(retryMs / 1000);
+            return `${baseMessage}: Rate limit exceeded - retry after ${retrySeconds}s`;
+        }
+        return `${baseMessage}: Rate limit exceeded`;
+    }
+    // Handle other ApiErrors
+    if (cause instanceof v3_1.ApiError) {
+        return `${baseMessage}: ${cause.message}`;
+    }
+    // Handle generic errors
+    if (cause instanceof Error) {
+        return `${baseMessage}: ${cause.message}`;
+    }
+    return baseMessage;
+}
 /**
  * Execute a streaming 2-phase batch trigger where items are streamed from an AsyncIterable.
  * Unlike executeBatchTwoPhase, this doesn't know the count upfront.
@@ -801,6 +860,7 @@ async function* transformBatchItemsStream(items, options) {
                 priority: item.options?.priority,
                 region: item.options?.region,
                 lockToVersion: item.options?.version ?? (0, v3_1.getEnvVar)("TRIGGER_VERSION"),
+                debounce: item.options?.debounce,
             },
         };
     }
@@ -841,6 +901,7 @@ async function* transformBatchItemsStreamForWait(items, options) {
                 machine: item.options?.machine,
                 priority: item.options?.priority,
                 region: item.options?.region,
+                debounce: item.options?.debounce,
             },
         };
     }
@@ -880,6 +941,7 @@ async function* transformBatchByTaskItemsStream(items, options) {
                 priority: item.options?.priority,
                 region: item.options?.region,
                 lockToVersion: item.options?.version ?? (0, v3_1.getEnvVar)("TRIGGER_VERSION"),
+                debounce: item.options?.debounce,
             },
         };
     }
@@ -919,6 +981,7 @@ async function* transformBatchByTaskItemsStreamForWait(items, options) {
                 machine: item.options?.machine,
                 priority: item.options?.priority,
                 region: item.options?.region,
+                debounce: item.options?.debounce,
             },
         };
     }
@@ -959,6 +1022,7 @@ async function* transformSingleTaskBatchItemsStream(taskIdentifier, items, parse
                 priority: item.options?.priority,
                 region: item.options?.region,
                 lockToVersion: item.options?.version ?? (0, v3_1.getEnvVar)("TRIGGER_VERSION"),
+                debounce: item.options?.debounce,
             },
         };
     }
@@ -974,6 +1038,12 @@ async function* transformSingleTaskBatchItemsStreamForWait(taskIdentifier, items
         const parsedPayload = parsePayload ? await parsePayload(item.payload) : item.payload;
         const payloadPacket = await (0, v3_1.stringifyIO)(parsedPayload);
         const batchItemIdempotencyKey = await (0, v3_1.makeIdempotencyKey)((0, v3_1.flattenIdempotencyKey)([options?.idempotencyKey, `${index}`]));
+        // Process item-specific idempotency key and extract options
+        const itemIdempotencyKey = await (0, v3_1.makeIdempotencyKey)(item.options?.idempotencyKey);
+        const finalIdempotencyKey = itemIdempotencyKey ?? batchItemIdempotencyKey;
+        const idempotencyKeyOptions = itemIdempotencyKey
+            ? (0, v3_1.getIdempotencyKeyOptions)(itemIdempotencyKey)
+            : undefined;
         yield {
             index: index++,
             task: taskIdentifier,
@@ -994,11 +1064,13 @@ async function* transformSingleTaskBatchItemsStreamForWait(taskIdentifier, items
                 maxAttempts: item.options?.maxAttempts,
                 metadata: item.options?.metadata,
                 maxDuration: item.options?.maxDuration,
-                idempotencyKey: (await (0, v3_1.makeIdempotencyKey)(item.options?.idempotencyKey)) ?? batchItemIdempotencyKey,
+                idempotencyKey: finalIdempotencyKey?.toString(),
                 idempotencyKeyTTL: item.options?.idempotencyKeyTTL ?? options?.idempotencyKeyTTL,
+                idempotencyKeyOptions,
                 machine: item.options?.machine,
                 priority: item.options?.priority,
                 region: item.options?.region,
+                debounce: item.options?.debounce,
             },
         };
     }
@@ -1007,6 +1079,11 @@ async function trigger_internal(name, id, payload, parsePayload, options, reques
     const apiClient = v3_1.apiClientManager.clientOrThrow(requestOptions?.clientConfig);
     const parsedPayload = parsePayload ? await parsePayload(payload) : payload;
     const payloadPacket = await (0, v3_1.stringifyIO)(parsedPayload);
+    // Process idempotency key and extract options for storage
+    const processedIdempotencyKey = await (0, v3_1.makeIdempotencyKey)(options?.idempotencyKey);
+    const idempotencyKeyOptions = processedIdempotencyKey
+        ? (0, v3_1.getIdempotencyKeyOptions)(processedIdempotencyKey)
+        : undefined;
     const handle = await apiClient.triggerTask(id, {
         payload: payloadPacket.data,
         options: {
@@ -1014,8 +1091,9 @@ async function trigger_internal(name, id, payload, parsePayload, options, reques
             concurrencyKey: options?.concurrencyKey,
             test: v3_1.taskContext.ctx?.run.isTest,
             payloadType: payloadPacket.dataType,
-            idempotencyKey: await (0, v3_1.makeIdempotencyKey)(options?.idempotencyKey),
+            idempotencyKey: processedIdempotencyKey?.toString(),
             idempotencyKeyTTL: options?.idempotencyKeyTTL,
+            idempotencyKeyOptions,
             delay: options?.delay,
             ttl: options?.ttl,
             tags: options?.tags,
@@ -1027,6 +1105,7 @@ async function trigger_internal(name, id, payload, parsePayload, options, reques
             priority: options?.priority,
             region: options?.region,
             lockToVersion: options?.version ?? (0, v3_1.getEnvVar)("TRIGGER_VERSION"),
+            debounce: options?.debounce,
         },
     }, {
         spanParentAsLink: true,
@@ -1055,6 +1134,12 @@ async function batchTrigger_internal(name, taskIdentifier, items, options, parse
             const parsedPayload = parsePayload ? await parsePayload(item.payload) : item.payload;
             const payloadPacket = await (0, v3_1.stringifyIO)(parsedPayload);
             const batchItemIdempotencyKey = await (0, v3_1.makeIdempotencyKey)((0, v3_1.flattenIdempotencyKey)([options?.idempotencyKey, `${index}`]));
+            // Process item-specific idempotency key and extract options
+            const itemIdempotencyKey = await (0, v3_1.makeIdempotencyKey)(item.options?.idempotencyKey);
+            const finalIdempotencyKey = itemIdempotencyKey ?? batchItemIdempotencyKey;
+            const idempotencyKeyOptions = itemIdempotencyKey
+                ? (0, v3_1.getIdempotencyKeyOptions)(itemIdempotencyKey)
+                : undefined;
             return {
                 index,
                 task: taskIdentifier,
@@ -1074,8 +1159,9 @@ async function batchTrigger_internal(name, taskIdentifier, items, options, parse
                     maxAttempts: item.options?.maxAttempts,
                     metadata: item.options?.metadata,
                     maxDuration: item.options?.maxDuration,
-                    idempotencyKey: (await (0, v3_1.makeIdempotencyKey)(item.options?.idempotencyKey)) ?? batchItemIdempotencyKey,
+                    idempotencyKey: finalIdempotencyKey?.toString(),
                     idempotencyKeyTTL: item.options?.idempotencyKeyTTL ?? options?.idempotencyKeyTTL,
+                    idempotencyKeyOptions,
                     machine: item.options?.machine,
                     priority: item.options?.priority,
                     region: item.options?.region,
@@ -1084,10 +1170,16 @@ async function batchTrigger_internal(name, taskIdentifier, items, options, parse
             };
         }));
         // Execute 2-phase batch
+        // Process batch-level idempotency key
+        const batchIdempotencyKey = await (0, v3_1.makeIdempotencyKey)(options?.idempotencyKey);
+        const batchIdempotencyKeyOptions = batchIdempotencyKey
+            ? (0, v3_1.getIdempotencyKeyOptions)(batchIdempotencyKey)
+            : undefined;
         const response = await tracer_js_1.tracer.startActiveSpan(name, async (span) => {
             const result = await executeBatchTwoPhase(apiClient, ndJsonItems, {
                 parentRunId: ctx?.run.id,
-                idempotencyKey: await (0, v3_1.makeIdempotencyKey)(options?.idempotencyKey),
+                idempotencyKey: batchIdempotencyKey?.toString(),
+                idempotencyKeyOptions: batchIdempotencyKeyOptions,
                 spanParentAsLink: true, // Fire-and-forget: child runs get separate trace IDs
             }, requestOptions);
             span.setAttribute("batchId", result.id);
@@ -1120,10 +1212,16 @@ async function batchTrigger_internal(name, taskIdentifier, items, options, parse
         const asyncItems = normalizeToAsyncIterable(items);
         const transformedItems = transformSingleTaskBatchItemsStream(taskIdentifier, asyncItems, parsePayload, options, queue);
         // Execute streaming 2-phase batch
+        // Process batch-level idempotency key
+        const streamBatchIdempotencyKey = await (0, v3_1.makeIdempotencyKey)(options?.idempotencyKey);
+        const streamBatchIdempotencyKeyOptions = streamBatchIdempotencyKey
+            ? (0, v3_1.getIdempotencyKeyOptions)(streamBatchIdempotencyKey)
+            : undefined;
         const response = await tracer_js_1.tracer.startActiveSpan(name, async (span) => {
             const result = await executeBatchTwoPhaseStreaming(apiClient, transformedItems, {
                 parentRunId: ctx?.run.id,
-                idempotencyKey: await (0, v3_1.makeIdempotencyKey)(options?.idempotencyKey),
+                idempotencyKey: streamBatchIdempotencyKey?.toString(),
+                idempotencyKeyOptions: streamBatchIdempotencyKeyOptions,
                 spanParentAsLink: true, // Fire-and-forget: child runs get separate trace IDs
             }, requestOptions);
             span.setAttribute("batchId", result.id);
@@ -1160,6 +1258,11 @@ async function triggerAndWait_internal(name, id, payload, parsePayload, options,
     const apiClient = v3_1.apiClientManager.clientOrThrow(requestOptions?.clientConfig);
     const parsedPayload = parsePayload ? await parsePayload(payload) : payload;
     const payloadPacket = await (0, v3_1.stringifyIO)(parsedPayload);
+    // Process idempotency key and extract options for storage
+    const processedIdempotencyKey = await (0, v3_1.makeIdempotencyKey)(options?.idempotencyKey);
+    const idempotencyKeyOptions = processedIdempotencyKey
+        ? (0, v3_1.getIdempotencyKeyOptions)(processedIdempotencyKey)
+        : undefined;
     return await tracer_js_1.tracer.startActiveSpan(name, async (span) => {
         const response = await apiClient.triggerTask(id, {
             payload: payloadPacket.data,
@@ -1177,11 +1280,13 @@ async function triggerAndWait_internal(name, id, payload, parsePayload, options,
                 maxDuration: options?.maxDuration,
                 resumeParentOnCompletion: true,
                 parentRunId: ctx.run.id,
-                idempotencyKey: await (0, v3_1.makeIdempotencyKey)(options?.idempotencyKey),
+                idempotencyKey: processedIdempotencyKey?.toString(),
                 idempotencyKeyTTL: options?.idempotencyKeyTTL,
+                idempotencyKeyOptions,
                 machine: options?.machine,
                 priority: options?.priority,
                 region: options?.region,
+                debounce: options?.debounce,
             },
         }, {}, requestOptions);
         span.setAttribute("runId", response.id);
@@ -1219,6 +1324,12 @@ async function batchTriggerAndWait_internal(name, id, items, parsePayload, optio
             const parsedPayload = parsePayload ? await parsePayload(item.payload) : item.payload;
             const payloadPacket = await (0, v3_1.stringifyIO)(parsedPayload);
             const batchItemIdempotencyKey = await (0, v3_1.makeIdempotencyKey)((0, v3_1.flattenIdempotencyKey)([options?.idempotencyKey, `${index}`]));
+            // Process item-specific idempotency key and extract options
+            const itemIdempotencyKey = await (0, v3_1.makeIdempotencyKey)(item.options?.idempotencyKey);
+            const finalIdempotencyKey = itemIdempotencyKey ?? batchItemIdempotencyKey;
+            const idempotencyKeyOptions = itemIdempotencyKey
+                ? (0, v3_1.getIdempotencyKeyOptions)(itemIdempotencyKey)
+                : undefined;
             return {
                 index,
                 task: id,
@@ -1239,20 +1350,27 @@ async function batchTriggerAndWait_internal(name, id, items, parsePayload, optio
                     maxAttempts: item.options?.maxAttempts,
                     metadata: item.options?.metadata,
                     maxDuration: item.options?.maxDuration,
-                    idempotencyKey: (await (0, v3_1.makeIdempotencyKey)(item.options?.idempotencyKey)) ?? batchItemIdempotencyKey,
+                    idempotencyKey: finalIdempotencyKey?.toString(),
                     idempotencyKeyTTL: item.options?.idempotencyKeyTTL ?? options?.idempotencyKeyTTL,
+                    idempotencyKeyOptions,
                     machine: item.options?.machine,
                     priority: item.options?.priority,
                     region: item.options?.region,
                 },
             };
         }));
+        // Process batch-level idempotency key
+        const batchIdempotencyKey = await (0, v3_1.makeIdempotencyKey)(options?.idempotencyKey);
+        const batchIdempotencyKeyOptions = batchIdempotencyKey
+            ? (0, v3_1.getIdempotencyKeyOptions)(batchIdempotencyKey)
+            : undefined;
         return await tracer_js_1.tracer.startActiveSpan(name, async (span) => {
             // Execute 2-phase batch
             const response = await executeBatchTwoPhase(apiClient, ndJsonItems, {
                 parentRunId: ctx.run.id,
                 resumeParentOnCompletion: true,
-                idempotencyKey: await (0, v3_1.makeIdempotencyKey)(options?.idempotencyKey),
+                idempotencyKey: batchIdempotencyKey?.toString(),
+                idempotencyKeyOptions: batchIdempotencyKeyOptions,
                 spanParentAsLink: false, // Waiting: child runs share parent's trace ID
             }, requestOptions);
             span.setAttribute("batchId", response.id);
@@ -1287,12 +1405,18 @@ async function batchTriggerAndWait_internal(name, id, items, parsePayload, optio
         // Stream path: convert to AsyncIterable and transform
         const asyncItems = normalizeToAsyncIterable(items);
         const transformedItems = transformSingleTaskBatchItemsStreamForWait(id, asyncItems, parsePayload, options, queue);
+        // Process batch-level idempotency key for streaming path
+        const streamBatchIdempotencyKey = await (0, v3_1.makeIdempotencyKey)(options?.idempotencyKey);
+        const streamBatchIdempotencyKeyOptions = streamBatchIdempotencyKey
+            ? (0, v3_1.getIdempotencyKeyOptions)(streamBatchIdempotencyKey)
+            : undefined;
         return await tracer_js_1.tracer.startActiveSpan(name, async (span) => {
             // Execute streaming 2-phase batch
             const response = await executeBatchTwoPhaseStreaming(apiClient, transformedItems, {
                 parentRunId: ctx.run.id,
                 resumeParentOnCompletion: true,
-                idempotencyKey: await (0, v3_1.makeIdempotencyKey)(options?.idempotencyKey),
+                idempotencyKey: streamBatchIdempotencyKey?.toString(),
+                idempotencyKeyOptions: streamBatchIdempotencyKeyOptions,
                 spanParentAsLink: false, // Waiting: child runs share parent's trace ID
             }, requestOptions);
             span.setAttribute("batchId", response.id);