expose concurrencyKey in task context

- Schemas: add optional concurrencyKey to TaskRunExecution and TaskRunContext types
- Engine: include concurrencyKey in execution/context building
- Services: pass concurrencyKey in execution payload
- Presenters/Routes: include concurrencyKey in context returned to UI
- Tests: verify execution.concurrencyKey is exposed as ctx.concurrencyKey
- Docs: document in docs/context.mdx
- Add changeset
- No concurrency behavior changes

Author: omkardongre

.changeset/eight-keys-impress.md

@@ -0,0 +1,5 @@
+---
+"@trigger.dev/core": patch
+---
+
+Expose concurrencyKey on task run context (ctx.concurrencyKey)

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

@@ -571,6 +571,7 @@ export class SpanPresenter extends BasePresenter {
         name: run.queue,
         id: run.queue,
       },
+      concurrencyKey: run.concurrencyKey ?? undefined,
       environment: {
         id: run.runtimeEnvironment.id,
         slug: run.runtimeEnvironment.slug,

apps/webapp/app/routes/resources.runs.$runParam.ts

@@ -193,6 +193,7 @@ export const loader = async ({ request, params }: LoaderFunctionArgs) => {
     queue: {
       name: run.queue,
     },
+    concurrencyKey: run.concurrencyKey,
     environment: {
       id: run.runtimeEnvironment.id,
       slug: run.runtimeEnvironment.slug,

apps/webapp/app/v3/marqs/sharedQueueConsumer.server.ts

@@ -1639,6 +1639,7 @@ export const AttemptForExecutionGetPayload = {
         baseCostInCents: true,
         maxDurationInSeconds: true,
         tags: true,
+        concurrencyKey: true,
       },
     },
     queue: {
@@ -1727,6 +1728,7 @@ class SharedQueueTasks {
         id: queue.friendlyId,
         name: queue.name,
       },
+      concurrencyKey: taskRun.concurrencyKey ?? undefined,
       environment: {
         id: attempt.runtimeEnvironment.id,
         slug: attempt.runtimeEnvironment.slug,

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

@@ -225,6 +225,7 @@ export class CreateTaskRunAttemptService extends BaseService {
           id: queue.friendlyId,
           name: queue.name,
         },
+        concurrencyKey: taskRun.concurrencyKey ?? undefined,
         environment: {
           id: environment.id,
           slug: environment.slug,

docs/context.mdx

@@ -125,6 +125,11 @@ export const parentTask = task({
   </Expandable>
 </ResponseField>
 
+<ResponseField name="concurrencyKey" type="string" optional>
+  If set, the run is queued under this key. Runs with the same key execute sequentially.
+  See <a href="/queue-concurrency">Queue concurrency</a> and <a href="/triggering#concurrencykey">Triggering: concurrencyKey</a>.
+</ResponseField>
+
 <ResponseField name="environment" type="object">
   <Expandable title="properties">
     <ResponseField name="id" type="string">

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

@@ -186,6 +186,7 @@ export class RunAttemptSystem {
         lockedById: true,
         lockedQueueId: true,
         queue: true,
+        concurrencyKey: true,
         attemptNumber: true,
         status: true,
         ttl: true,
@@ -275,6 +276,7 @@ export class RunAttemptSystem {
       },
       task,
       queue,
+      concurrencyKey: run.concurrencyKey ?? undefined,
       organization,
       project,
       machine: machinePreset,
@@ -410,6 +412,7 @@ export class RunAttemptSystem {
                   lockedById: true,
                   lockedQueueId: true,
                   queue: true,
+                  concurrencyKey: true,
                   attemptNumber: true,
                   status: true,
                   ttl: true,
@@ -596,6 +599,7 @@ export class RunAttemptSystem {
             },
             task,
             queue,
+            concurrencyKey: updatedRun.concurrencyKey ?? undefined,
             environment: {
               id: updatedRun.runtimeEnvironment.id,
               slug: updatedRun.runtimeEnvironment.slug,

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

@@ -336,6 +336,7 @@ export const TaskRunExecution = z.object({
       traceContext: z.record(z.unknown()).optional(),
     })
   ),
+  concurrencyKey: z.string().optional(),
   ...StaticTaskRunExecutionShape,
 });
 
@@ -390,6 +391,7 @@ export const V3TaskRunExecution = z.object({
     })
   ),
   queue: TaskRunExecutionQueue,
+  concurrencyKey: z.string().optional(),
   environment: TaskRunExecutionEnvironment,
   organization: TaskRunExecutionOrganization,
   project: TaskRunExecutionProject,
@@ -408,6 +410,7 @@ export const TaskRunContext = z.object({
     durationMs: true,
     costInCents: true,
   }),
+  concurrencyKey: z.string().optional(),
   ...StaticTaskRunExecutionShape,
 });
 
@@ -433,6 +436,7 @@ export const V3TaskRunContext = z.object({
   }),
   task: V3TaskRunExecutionTask,
   queue: TaskRunExecutionQueue,
+  concurrencyKey: z.string().optional(),
   environment: V3TaskRunExecutionEnvironment,
   organization: TaskRunExecutionOrganization,
   project: TaskRunExecutionProject,

packages/core/test/taskExecutor.test.ts

@@ -1840,6 +1840,26 @@ describe("TaskExecutor", () => {
       },
     });
   });
+
+  test("should pass concurrencyKey through to task context", async () => {
+    let receivedConcurrencyKey: string | undefined;
+    
+    const task = {
+      id: "test-task",
+      fns: {
+        run: async (payload: any, params: RunFnParams<any>) => {
+          receivedConcurrencyKey = params.ctx.concurrencyKey;
+          return { success: true };
+        },
+      },
+    };
+  
+    const result = await executeTask(task, { test: "data" }, undefined, undefined);
+
+    // Verify that concurrencyKey is passed through to task context
+    expect(receivedConcurrencyKey).toBe("user-123");
+    expect(result.result.ok).toBe(true);
+  });
 });
 
 function executeTask(
@@ -1915,6 +1935,7 @@ function executeTask(
       name: "test-queue",
       id: "test-queue-id",
     },
+    concurrencyKey: "user-123",
     environment: {
       type: "PRODUCTION",
       id: "test-environment-id",