feat(core): make run queue a public API field

Add queue to CommonRunFields so RetrieveRunResponse/ListRunResponseItem
carry it, document it in the OpenAPI schema, and omit it (rather than
sending an empty string) on a buffered run that doesn't have one yet.

Author: kathiekiwi

.changeset/run-object-queue-field.md

@@ -0,0 +1,6 @@
+---
+"@trigger.dev/core": patch
+"@trigger.dev/sdk": patch
+---
+
+Run objects returned by `runs.retrieve()` and `runs.list()` now include the run's `queue` name.

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

@@ -86,7 +86,10 @@ type CommonRelatedRunWithVersion = CommonRelatedRun & {
 // ReturnType<typeof findRun>) so findRun can return a synthesised buffered
 // run without the type becoming self-referential. Exported so the
 // buffer-synthesis helper below can match this shape under unit test.
-export type FoundRun = CommonRelatedRunWithVersion & {
+export type FoundRun = Omit<CommonRelatedRunWithVersion, "queue"> & {
+  // Optional here only because a buffered (mollified) run may not carry it yet;
+  // a Postgres-resident run always has one (see commonRunSelect).
+  queue?: string;
   traceId: string;
   payload: string;
   payloadType: string;
@@ -523,7 +526,7 @@ export class ApiRetrieveRunPresenter {
   }
 }
 
-async function resolveSchedule(run: CommonRelatedRun) {
+async function resolveSchedule(run: Pick<CommonRelatedRun, "scheduleId">) {
   if (!run.scheduleId) {
     return undefined;
   }
@@ -551,7 +554,9 @@ async function resolveSchedule(run: CommonRelatedRun) {
 }
 
 async function createCommonRunStructure(
-  run: CommonRelatedRunWithVersion,
+  // `queue` is widened to optional: a Postgres-resident run always has one, but a
+  // buffered (mollified) run synthesised into `FoundRun` may not yet.
+  run: Omit<CommonRelatedRunWithVersion, "queue"> & { queue?: string },
   apiVersion: API_VERSIONS
 ) {
   const metadata = await parsePacketAsJson({
@@ -591,7 +596,9 @@ async function createCommonRunStructure(
   };
 }
 
-function resolveTriggerFunction(run: CommonRelatedRun): TriggerFunction {
+function resolveTriggerFunction(
+  run: Pick<CommonRelatedRun, "batch" | "resumeParentOnCompletion">
+): TriggerFunction {
   if (run.batch) {
     return run.resumeParentOnCompletion ? "batchTriggerAndWait" : "batchTrigger";
   } else {
@@ -698,7 +705,7 @@ export function synthesiseFoundRunFromBuffer(buffered: SyntheticRun): FoundRun {
     startedAt: null,
     // Buffered runs live in Redis until the drainer replays them into Postgres — never queued there yet.
     queuedAt: null,
-    queue: buffered.queue ?? "",
+    queue: buffered.queue,
     updatedAt: buffered.cancelledAt ?? buffered.createdAt,
     // PG-resident SYSTEM_FAILURE rows always have `completedAt` set by
     // the engine; the buffer-synth path must match so SDK consumers

docs/v3-openapi.yaml

@@ -5549,6 +5549,10 @@ components:
           type: string
           example: 20240523.1
           description: The version of the worker that executed the run
+        queue:
+          type: string
+          description: The name of the queue the run was placed in
+          example: task/my-task
         idempotencyKey:
           type: string
           description: The idempotency key used to prevent creating duplicate runs, if provided

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

@@ -1359,6 +1359,7 @@ const CommonRunFields = {
   metadata: z.record(z.any()).optional(),
   taskKind: z.string().optional(),
   region: z.string().optional(),
+  queue: z.string().optional(),
 };
 
 const RetrieveRunCommandFields = {