feat(sdk): expose user-provided idempotency key and scope in task context (#2903)

## Summary
- Store the original user-provided idempotency key and scope alongside
the hash
- Expose `ctx.run.idempotencyKey` as the user-provided key (not the
hash)
- Add `ctx.run.idempotencyKeyScope` to show the scope ("run", "attempt",
or "global")

<img width="539" height="450" alt="CleanShot 2026-01-19 at 11 40 46"
src="https://github.com/user-attachments/assets/b6f42991-697e-4314-a164-aef77b8fd25c"
/>

  ## Problem
Idempotency keys were hashed (SHA-256) before storage, making debugging
difficult since users couldn't see the value they originally set or
search for runs by idempotency key.

  ## Solution
Attach metadata to the `String` object returned by
`idempotencyKeys.create()` using a Symbol, extract it in the SDK before
the API call, and store it in the database alongside the hash.

  ```typescript
const key = await idempotencyKeys.create("my-key", { scope: "global" });
  await childTask.triggerAndWait(payload, { idempotencyKey: key });

  // In child task:
  ctx.run.idempotencyKey      // "my-key" (previously showed the hash)
  ctx.run.idempotencyKeyScope // "global"
```

  Test plan

  - Trigger task with idempotencyKeys.create() using different scopes (run, attempt, global)
  - Verify ctx.run.idempotencyKey returns user-provided key
  - Verify ctx.run.idempotencyKeyScope returns correct scope
  - Verify PostgreSQL stores idempotencyKeyOptions JSON
  - Verify ClickHouse receives idempotency_key_user and idempotency_key_scope via replication

---------

Co-authored-by: James Ritchie <james@trigger.dev>

Author: ericallam

.changeset/bright-keys-shine.md

@@ -0,0 +1,6 @@
+---
+"@trigger.dev/sdk": patch
+"@trigger.dev/core": patch
+---
+
+Expose user-provided idempotency key and scope in task context. `ctx.run.idempotencyKey` now returns the original key passed to `idempotencyKeys.create()` instead of the hash, and `ctx.run.idempotencyKeyScope` shows the scope ("run", "attempt", or "global").

apps/webapp/app/presenters/v3/ApiRetrieveRunPresenter.server.ts

@@ -9,6 +9,7 @@ import {
   logger,
 } from "@trigger.dev/core/v3";
 import { parsePacketAsJson } from "@trigger.dev/core/v3/utils/ioSerialization";
+import { getUserProvidedIdempotencyKey } from "@trigger.dev/core/v3/serverOnly";
 import { Prisma, TaskRunAttemptStatus, TaskRunStatus } from "@trigger.dev/database";
 import assertNever from "assert-never";
 import { API_VERSIONS, CURRENT_API_VERSION, RunStatusUnspecifiedApiVersion } from "~/api/versions";
@@ -38,6 +39,7 @@ const commonRunSelect = {
   baseCostInCents: true,
   usageDurationMs: true,
   idempotencyKey: true,
+  idempotencyKeyOptions: true,
   isTest: true,
   depth: true,
   scheduleId: true,
@@ -442,7 +444,7 @@ async function createCommonRunStructure(run: CommonRelatedRun, apiVersion: API_V
   return {
     id: run.friendlyId,
     taskIdentifier: run.taskIdentifier,
-    idempotencyKey: run.idempotencyKey ?? undefined,
+    idempotencyKey: getUserProvidedIdempotencyKey(run),
     version: run.lockedToVersion?.version,
     status: ApiRetrieveRunPresenter.apiStatusFromRunStatus(run.status, apiVersion),
     createdAt: run.createdAt,

apps/webapp/app/presenters/v3/SpanPresenter.server.ts

@@ -8,6 +8,10 @@ import {
   type V3TaskRunContext,
 } from "@trigger.dev/core/v3";
 import { AttemptId, getMaxDuration, parseTraceparent } from "@trigger.dev/core/v3/isomorphic";
+import {
+  extractIdempotencyKeyScope,
+  getUserProvidedIdempotencyKey,
+} from "@trigger.dev/core/v3/serverOnly";
 import { RUNNING_STATUSES } from "~/components/runs/v3/TaskRunStatus";
 import { logger } from "~/services/logger.server";
 import { rehydrateAttribute } from "~/v3/eventRepository/eventRepository.server";
@@ -229,8 +233,10 @@ export class SpanPresenter extends BasePresenter {
       isTest: run.isTest,
       replayedFromTaskRunFriendlyId: run.replayedFromTaskRunFriendlyId,
       environmentId: run.runtimeEnvironment.id,
-      idempotencyKey: run.idempotencyKey,
+      idempotencyKey: getUserProvidedIdempotencyKey(run),
       idempotencyKeyExpiresAt: run.idempotencyKeyExpiresAt,
+      idempotencyKeyScope: extractIdempotencyKeyScope(run),
+      idempotencyKeyStatus: this.getIdempotencyKeyStatus(run),
       debounce: run.debounce as { key: string; delay: string; createdAt: Date } | null,
       schedule: await this.resolveSchedule(run.scheduleId ?? undefined),
       queue: {
@@ -276,6 +282,30 @@ export class SpanPresenter extends BasePresenter {
     };
   }
 
+  private getIdempotencyKeyStatus(run: {
+    idempotencyKey: string | null;
+    idempotencyKeyExpiresAt: Date | null;
+    idempotencyKeyOptions: unknown;
+  }): "active" | "inactive" | "expired" | undefined {
+    // No idempotency configured if no scope exists
+    const scope = extractIdempotencyKeyScope(run);
+    if (!scope) {
+      return undefined;
+    }
+
+    // Check if expired first (takes precedence)
+    if (run.idempotencyKeyExpiresAt && run.idempotencyKeyExpiresAt < new Date()) {
+      return "expired";
+    }
+
+    // Check if reset (hash is null but options exist)
+    if (run.idempotencyKey === null) {
+      return "inactive";
+    }
+
+    return "active";
+  }
+
   async resolveSchedule(scheduleId?: string) {
     if (!scheduleId) {
       return;
@@ -355,6 +385,7 @@ export class SpanPresenter extends BasePresenter {
         //idempotency
         idempotencyKey: true,
         idempotencyKeyExpiresAt: true,
+        idempotencyKeyOptions: true,
         //debounce
         debounce: true,
         //delayed
@@ -644,7 +675,7 @@ export class SpanPresenter extends BasePresenter {
         createdAt: run.createdAt,
         tags: run.runTags,
         isTest: run.isTest,
-        idempotencyKey: run.idempotencyKey ?? undefined,
+        idempotencyKey: getUserProvidedIdempotencyKey(run) ?? undefined,
         startedAt: run.startedAt ?? run.createdAt,
         durationMs: run.usageDurationMs,
         costInCents: run.costInCents,

apps/webapp/app/routes/resources.orgs.$organizationSlug.projects.$projectParam.env.$envParam.runs.$runParam.idempotencyKey.reset.tsx

@@ -1,32 +1,16 @@
-import { parse } from "@conform-to/zod";
 import { type ActionFunction, json } from "@remix-run/node";
-import { z } from "zod";
 import { prisma } from "~/db.server";
-import { jsonWithErrorMessage } from "~/models/message.server";
+import { jsonWithErrorMessage, jsonWithSuccessMessage } from "~/models/message.server";
 import { logger } from "~/services/logger.server";
 import { requireUserId } from "~/services/session.server";
 import { ResetIdempotencyKeyService } from "~/v3/services/resetIdempotencyKey.server";
 import { v3RunParamsSchema } from "~/utils/pathBuilder";
 
-export const resetIdempotencyKeySchema = z.object({
-  taskIdentifier: z.string().min(1, "Task identifier is required"),
-});
-
 export const action: ActionFunction = async ({ request, params }) => {
   const userId = await requireUserId(request);
-  const { projectParam, organizationSlug, envParam, runParam } =
-    v3RunParamsSchema.parse(params);
-
-  const formData = await request.formData();
-  const submission = parse(formData, { schema: resetIdempotencyKeySchema });
-
-  if (!submission.value) {
-    return json(submission);
-  }
+  const { projectParam, organizationSlug, envParam, runParam } = v3RunParamsSchema.parse(params);
 
   try {
-    const { taskIdentifier } = submission.value;
-
     const taskRun = await prisma.taskRun.findFirst({
       where: {
         friendlyId: runParam,
@@ -54,21 +38,11 @@ export const action: ActionFunction = async ({ request, params }) => {
     });
 
     if (!taskRun) {
-      submission.error = { runParam: ["Run not found"] };
-      return json(submission);
+      return jsonWithErrorMessage({}, request, "Run not found");
     }
 
     if (!taskRun.idempotencyKey) {
-      return jsonWithErrorMessage(
-        submission,
-        request,
-        "This run does not have an idempotency key"
-      );
-    }
-
-    if (taskRun.taskIdentifier !== taskIdentifier) {
-      submission.error = { taskIdentifier: ["Task identifier does not match this run"] };
-      return json(submission);
+      return jsonWithErrorMessage({}, request, "This run does not have an idempotency key");
     }
 
     const environment = await prisma.runtimeEnvironment.findUnique({
@@ -85,22 +59,18 @@ export const action: ActionFunction = async ({ request, params }) => {
     });
 
     if (!environment) {
-      return jsonWithErrorMessage(
-        submission,
-        request,
-        "Environment not found"
-      );
+      return jsonWithErrorMessage({}, request, "Environment not found");
     }
 
     const service = new ResetIdempotencyKeyService();
 
-    await service.call(taskRun.idempotencyKey, taskIdentifier, {
+    await service.call(taskRun.idempotencyKey, taskRun.taskIdentifier, {
       ...environment,
       organizationId: environment.project.organizationId,
       organization: environment.project.organization,
     });
 
-    return json({ success: true });
+    return jsonWithSuccessMessage({}, request, "Idempotency key reset successfully");
   } catch (error) {
     if (error instanceof Error) {
       logger.error("Failed to reset idempotency key", {
@@ -110,15 +80,11 @@ export const action: ActionFunction = async ({ request, params }) => {
           stack: error.stack,
         },
       });
-      return jsonWithErrorMessage(
-        submission,
-        request,
-        `Failed to reset idempotency key: ${error.message}`
-      );
+      return jsonWithErrorMessage({}, request, `Failed to reset idempotency key: ${error.message}`);
     } else {
       logger.error("Failed to reset idempotency key", { error });
       return jsonWithErrorMessage(
-        submission,
+        {},
         request,
         `Failed to reset idempotency key: ${JSON.stringify(error)}`
       );