feat(core,webapp): version-discriminated queue reads, combined never ships

Queue reads now report a version that discriminates the shape. V1 queues
keep today's fields exactly (their own concurrencyLimit and its override
state) so nothing existing breaks; V2 queues are only the line runs wait
in and carry no queue-level concurrency, since their limits are read and
overridden through concurrencyLimits (concurrencyLimit stays as null so
older clients keep parsing). The combined block is gone from the public
schema entirely. The public queue routes now serialize through the schema,
so dashboard-only extras can never leak onto the wire; the dashboard reads
configured bounds from a presenter-attached limits object instead of the
public fields.

Author: matt-aitken

.changeset/task-concurrency.md

@@ -21,3 +21,5 @@ export const generateSummary = task({
 `perKey` caps each `concurrencyKey` pool and `total` caps across everything, keys or not. The queue-level `concurrencyLimit` option keeps working unchanged and is deprecated in favor of `concurrency`. Enforcement happens server-side; servers without support accept the option but do not enforce it yet.
 
 Manage limits at runtime with the new `concurrencyLimits` namespace: `list()` and `retrieve(name)` report each limit's bounds plus its live `running` and `queued` counts, `override(name, { perKey, total })` changes only the given bounds (overriding `total` to `0` pauses the limit), and `reset(name)` restores the declared values.
+
+Queue reads (`queues.list()` and `queues.retrieve()`) now report a `version` that discriminates the shape: `V1` queues keep today's fields (their own `concurrencyLimit` and its override state), while `V2` queues (tasks declared with `concurrency`) carry no queue-level concurrency, since their limits are read and overridden through `concurrencyLimits`.

apps/webapp/app/components/queues/QueueControls.tsx

@@ -1,9 +1,9 @@
 import { AdjustmentsHorizontalIcon, PauseIcon, PlayIcon } from "@heroicons/react/20/solid";
 import { DialogClose } from "@radix-ui/react-dialog";
 import { Form, useNavigation } from "@remix-run/react";
-import type { QueueItem } from "@trigger.dev/core/v3/schemas";
 import { useEffect, useState } from "react";
 import { cn } from "~/utils/cn";
+import type { QueueLimits } from "~/components/queues/queue-limits";
 import { Button, type ButtonVariant } from "~/components/primitives/Buttons";
 import { Dialog, DialogContent, DialogHeader, DialogTrigger } from "~/components/primitives/Dialog";
 import { FormButtons } from "~/components/primitives/FormButtons";
@@ -159,7 +159,12 @@ export function QueueOverrideConcurrencyButton({
   environmentConcurrencyLimit,
   trigger,
 }: {
-  queue: QueueItem & { concurrencyLimitOverridePercent: number | null };
+  queue: {
+    id: string;
+    name: string;
+    limits: QueueLimits;
+    concurrencyLimitOverridePercent: number | null;
+  };
   environmentConcurrencyLimit: number;
   /** How to render the dialog trigger. "menu-item" (default) is a PopoverMenuItem for row menus;
    * "button" is a standalone labeled button; "icon" is an icon-only button with the label in a
@@ -172,14 +177,14 @@ export function QueueOverrideConcurrencyButton({
     queue.concurrencyLimitOverridePercent !== null ? "percent" : "absolute"
   );
   const [concurrencyLimit, setConcurrencyLimit] = useState<string>(
-    queue.concurrencyLimit?.toString() ?? environmentConcurrencyLimit.toString()
+    queue.limits.perKey.current?.toString() ?? environmentConcurrencyLimit.toString()
   );
   const [percent, setPercent] = useState<string>(
     queue.concurrencyLimitOverridePercent?.toString() ?? "100"
   );
 
-  const isOverridden = !!queue.concurrency?.overriddenAt;
-  const currentLimit = queue.concurrencyLimit ?? environmentConcurrencyLimit;
+  const isOverridden = !!queue.limits.perKey.overriddenAt;
+  const currentLimit = queue.limits.perKey.current ?? environmentConcurrencyLimit;
 
   useEffect(() => {
     if (navigation.state === "loading" || navigation.state === "idle") {
@@ -277,18 +282,18 @@ export function QueueOverrideConcurrencyButton({
           {isOverridden ? (
             <Paragraph variant="small">
               This queue's concurrency limit is currently overridden to {currentLimit}.
-              {typeof queue.concurrency?.base === "number" &&
-                ` The original limit set in code was ${queue.concurrency.base}.`}{" "}
+              {typeof queue.limits.perKey.base === "number" &&
+                ` The original limit set in code was ${queue.limits.perKey.base}.`}{" "}
               You can update the override or remove it to restore the{" "}
-              {typeof queue.concurrency?.base === "number"
+              {typeof queue.limits.perKey.base === "number"
                 ? "limit set in code"
                 : "environment concurrency limit"}
               .
             </Paragraph>
           ) : (
             <Paragraph variant="small">
               Override this queue's concurrency limit. The current limit is {currentLimit}, which is
-              set {queue.concurrencyLimit !== null ? "in code" : "by the environment"}.
+              set {queue.limits.perKey.current !== null ? "in code" : "by the environment"}.
             </Paragraph>
           )}
           <Form method="post" onSubmit={() => setIsOpen(false)} className="space-y-3">

apps/webapp/app/components/queues/queue-limits.ts

@@ -0,0 +1,32 @@
+/**
+ * Dashboard-only view of a queue row's configured bounds. The public QueueItem
+ * shape is version-discriminated (V2 queues carry no queue-level concurrency),
+ * but the dashboard shows configured limits for every row, so presenters attach
+ * this alongside the public fields.
+ */
+export type QueueLimitBound = {
+  /** The enforced value right now (declared, or the override when one is active) */
+  current: number | null;
+  /** The declared value an override reverts to */
+  base: number | null;
+  /** The overridden value, when an override is active */
+  override: number | null;
+  overriddenAt: Date | null;
+  /** Display name of who applied the override (null when via the API) */
+  overriddenBy: string | null;
+};
+
+export type QueueTotalBound = {
+  current: number;
+  base: number | null;
+  override: number | null;
+  overriddenAt: Date | null;
+  /** Runs in flight across every pool of the row (keyed and keyless) */
+  running: number | null;
+};
+
+export type QueueLimits = {
+  perKey: QueueLimitBound;
+  /** Null when the row declares no total bound */
+  total: QueueTotalBound | null;
+};

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

@@ -7,7 +7,8 @@ import { clickhouseFactory } from "~/services/clickhouse/clickhouseFactoryInstan
 import { logger } from "~/services/logger.server";
 import { engine } from "~/v3/runEngine.server";
 import { BasePresenter } from "./basePresenter.server";
-import { toQueueItem } from "./QueueRetrievePresenter.server";
+import { toQueueItem, toQueueLimits } from "./QueueRetrievePresenter.server";
+import type { QueueLimits } from "~/components/queues/queue-limits";
 
 type QueueListEngine = Pick<
   RunEngine,
@@ -59,6 +60,8 @@ type QueueListItem = ReturnType<typeof toQueueItem> & {
   kind: "queue" | "limit";
   /** V2 rows hold the new perKey/total vocabulary in their limit columns. */
   concurrencyVersion: "V1" | "V2";
+  /** The row's configured bounds, dashboard-only (the public shape hides them on V2). */
+  limits: QueueLimits;
 };
 
 type QueueListPagination =
@@ -427,39 +430,45 @@ export class QueueListPresenter extends BasePresenter {
 
     const overriddenByMap = new Map(overriddenByUsers.map((u) => [u.id, u]));
 
-    return queues.map((queue) => ({
-      ...toQueueItem({
-        friendlyId: queue.friendlyId,
-        name: queue.name,
-        type: queue.type,
-        running:
-          queue.role === "LIMIT"
-            ? (totalRunningByQueue[queue.name] ?? 0)
-            : (runningByQueue[queue.name] ?? 0),
-        queued:
-          queue.role === "LIMIT"
-            ? (gateQueuedByQueue[queue.name] ?? 0)
-            : (queuedByQueue[queue.name] ?? 0),
-        concurrencyLimit: queue.concurrencyLimit ?? null,
-        concurrencyLimitBase: queue.concurrencyLimitBase ?? null,
-        concurrencyLimitOverriddenAt: queue.concurrencyLimitOverriddenAt ?? null,
-        concurrencyLimitOverriddenBy: queue.concurrencyLimitOverriddenBy
-          ? (overriddenByMap.get(queue.concurrencyLimitOverriddenBy) ?? null)
-          : null,
-        paused: queue.paused,
-        totalConcurrencyLimit: queue.totalConcurrencyLimit,
-        totalConcurrencyLimitBase: queue.totalConcurrencyLimitBase,
-        totalConcurrencyLimitOverriddenAt: queue.totalConcurrencyLimitOverriddenAt,
-        totalRunning:
-          queue.totalConcurrencyLimit !== null ? (totalRunningByQueue[queue.name] ?? 0) : null,
-      }),
-      // Prisma returns Decimal; the client only needs a plain number (null for absolute overrides).
-      concurrencyLimitOverridePercent:
-        queue.concurrencyLimitOverridePercent !== null
-          ? Number(queue.concurrencyLimitOverridePercent)
-          : null,
-      kind: queue.role === "LIMIT" ? ("limit" as const) : ("queue" as const),
-      concurrencyVersion: queue.concurrencyVersion,
-    }));
+    return queues.map((queue) => {
+      const overriddenByUser = queue.concurrencyLimitOverriddenBy
+        ? (overriddenByMap.get(queue.concurrencyLimitOverriddenBy) ?? null)
+        : null;
+      return {
+        ...toQueueItem({
+          friendlyId: queue.friendlyId,
+          name: queue.name,
+          type: queue.type,
+          version: queue.concurrencyVersion,
+          running:
+            queue.role === "LIMIT"
+              ? (totalRunningByQueue[queue.name] ?? 0)
+              : (runningByQueue[queue.name] ?? 0),
+          queued:
+            queue.role === "LIMIT"
+              ? (gateQueuedByQueue[queue.name] ?? 0)
+              : (queuedByQueue[queue.name] ?? 0),
+          concurrencyLimit: queue.concurrencyLimit ?? null,
+          concurrencyLimitBase: queue.concurrencyLimitBase ?? null,
+          concurrencyLimitOverriddenAt: queue.concurrencyLimitOverriddenAt ?? null,
+          concurrencyLimitOverriddenBy: overriddenByUser,
+          paused: queue.paused,
+        }),
+        // Prisma returns Decimal; the client only needs a plain number (null for absolute overrides).
+        concurrencyLimitOverridePercent:
+          queue.concurrencyLimitOverridePercent !== null
+            ? Number(queue.concurrencyLimitOverridePercent)
+            : null,
+        kind: queue.role === "LIMIT" ? ("limit" as const) : ("queue" as const),
+        concurrencyVersion: queue.concurrencyVersion,
+        limits: toQueueLimits(queue, {
+          totalRunning:
+            queue.totalConcurrencyLimit !== null ? (totalRunningByQueue[queue.name] ?? 0) : null,
+          overriddenByName: overriddenByUser
+            ? (overriddenByUser.displayName ?? overriddenByUser.name ?? null)
+            : null,
+        }),
+      };
+    });
   }
 }

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

@@ -1,5 +1,11 @@
 import { assertExhaustive } from "@trigger.dev/core";
-import { type Prettify, type QueueItem, type RetrieveQueueParam } from "@trigger.dev/core/v3";
+import {
+  QueueItem as QueueItemSchema,
+  type Prettify,
+  type QueueItem,
+  type RetrieveQueueParam,
+} from "@trigger.dev/core/v3";
+import type { QueueLimits } from "~/components/queues/queue-limits";
 import {
   type PrismaClientOrTransaction,
   type TaskQueue,
@@ -99,40 +105,91 @@ export class QueueRetrievePresenter extends BasePresenter {
         : undefined,
     ]);
 
-    // Transform queues to include running and queued counts
+    /** The returned queue = the public QueueItem fields plus dashboard extras
+     * (percent override source, configured bounds); the public API routes strip
+     * the extras via `toPublicQueueItem`. Prisma returns Decimal for the
+     * percent; the client only needs a plain number (null for absolute). */
     return {
       success: true as const,
       queue: {
         ...toQueueItem({
           friendlyId: queue.friendlyId,
           name: queue.name,
           type: queue.type,
+          version: queue.concurrencyVersion,
           running: results[1]?.[queue.name] ?? 0,
           queued: results[0]?.[queue.name] ?? 0,
           concurrencyLimit: queue.concurrencyLimit ?? null,
           concurrencyLimitBase: queue.concurrencyLimitBase ?? null,
           concurrencyLimitOverriddenAt: queue.concurrencyLimitOverriddenAt ?? null,
           concurrencyLimitOverriddenBy: queue.concurrencyLimitOverriddenBy ?? null,
           paused: queue.paused,
-          totalConcurrencyLimit: queue.totalConcurrencyLimit ?? null,
-          totalConcurrencyLimitBase: queue.totalConcurrencyLimitBase ?? null,
-          totalConcurrencyLimitOverriddenAt: queue.totalConcurrencyLimitOverriddenAt ?? null,
-          totalRunning:
-            queue.totalConcurrencyLimit != null ? (results[2]?.[queue.name] ?? 0) : null,
         }),
-        // The percent source-of-truth for percent-based overrides isn't part of the shared
-        // `QueueItem` schema (that's a public contract), so we surface it as an extra field on
-        // the returned queue — mirroring QueueListPresenter. Prisma returns Decimal; the client
-        // only needs a plain number (null for absolute overrides).
         concurrencyLimitOverridePercent:
           queue.concurrencyLimitOverridePercent !== null
             ? Number(queue.concurrencyLimitOverridePercent)
             : null,
+        limits: toQueueLimits(queue, {
+          totalRunning:
+            queue.totalConcurrencyLimit != null ? (results[2]?.[queue.name] ?? 0) : null,
+          overriddenByName: toQueueConcurrencyOverriddenBy(
+            queue.concurrencyLimitOverriddenBy ?? null
+          ),
+        }),
       },
     };
   }
 }
 
+/**
+ * The dashboard-only configured bounds of a row, independent of the public
+ * shape's version discrimination (V2 queues expose no queue-level concurrency
+ * publicly, but the dashboard still shows what's configured).
+ */
+export function toQueueLimits(
+  row: {
+    concurrencyLimit: number | null;
+    concurrencyLimitBase: number | null;
+    concurrencyLimitOverriddenAt: Date | null;
+    totalConcurrencyLimit: number | null;
+    totalConcurrencyLimitBase: number | null;
+    totalConcurrencyLimitOverriddenAt: Date | null;
+  },
+  extras: { totalRunning: number | null; overriddenByName: string | null }
+): QueueLimits {
+  return {
+    perKey: {
+      current: row.concurrencyLimit,
+      base: row.concurrencyLimitOverriddenAt ? row.concurrencyLimitBase : row.concurrencyLimit,
+      override: row.concurrencyLimitOverriddenAt ? row.concurrencyLimit : null,
+      overriddenAt: row.concurrencyLimitOverriddenAt,
+      overriddenBy: extras.overriddenByName,
+    },
+    total:
+      row.totalConcurrencyLimit !== null
+        ? {
+            current: row.totalConcurrencyLimit,
+            base: row.totalConcurrencyLimitOverriddenAt
+              ? row.totalConcurrencyLimitBase
+              : row.totalConcurrencyLimit,
+            override: row.totalConcurrencyLimitOverriddenAt ? row.totalConcurrencyLimit : null,
+            overriddenAt: row.totalConcurrencyLimitOverriddenAt,
+            running: extras.totalRunning,
+          }
+        : null,
+  };
+}
+
+/**
+ * The public API wire shape: the `QueueItem` contract exactly (dashboard extras
+ * stripped by the schema parse) plus the legacy field older clients require.
+ */
+export function toPublicQueueItem(item: QueueItem): QueueItem & {
+  releaseConcurrencyOnWaitpoint: boolean;
+} {
+  return { ...QueueItemSchema.parse(item), releaseConcurrencyOnWaitpoint: true };
+}
+
 export function queueTypeFromType(type: TaskQueueType) {
   switch (type) {
     case "NAMED":
@@ -145,54 +202,56 @@ export function queueTypeFromType(type: TaskQueueType) {
 }
 
 /**
- * Converts raw queue data into a standardized QueueItem format
- * @param data Raw queue data containing required queue properties
- * @returns A validated QueueItem object
+ * Converts raw queue data into the public QueueItem shape. The queue's version
+ * discriminates it: V1 carries the queue's own limit and override state; V2
+ * carries neither (a V2 queue is only the line — concurrency lives on the task
+ * `concurrency` option and the `concurrencyLimits` surface), with
+ * `concurrencyLimit` kept as null so older clients keep parsing.
  */
 export function toQueueItem(data: {
   friendlyId: string;
   name: string;
   type: TaskQueueType;
+  version: "V1" | "V2";
   running: number;
   queued: number;
   concurrencyLimit: number | null;
   concurrencyLimitBase: number | null;
   concurrencyLimitOverriddenAt: Date | null;
   concurrencyLimitOverriddenBy: User | null;
   paused: boolean;
-  totalConcurrencyLimit?: number | null;
-  totalConcurrencyLimitBase?: number | null;
-  totalConcurrencyLimitOverriddenAt?: Date | null;
-  totalRunning?: number | null;
 }): QueueItem & { releaseConcurrencyOnWaitpoint: boolean } {
-  return {
+  const common = {
     id: data.friendlyId,
     //remove the task/ prefix if it exists
     name: data.name.replace(/^task\//, ""),
     type: queueTypeFromType(data.type),
     running: data.running,
     queued: data.queued,
     paused: data.paused,
+    // TODO: This needs to be removed but keeping this here for now to avoid breaking existing clients
+    releaseConcurrencyOnWaitpoint: true,
+  };
+
+  if (data.version === "V2") {
+    return {
+      ...common,
+      version: "V2" as const,
+      concurrencyLimit: null,
+    };
+  }
+
+  return {
+    ...common,
+    version: "V1" as const,
     concurrencyLimit: data.concurrencyLimit,
     concurrency: {
       current: data.concurrencyLimit,
       base: data.concurrencyLimitBase,
       override: data.concurrencyLimitOverriddenAt ? data.concurrencyLimit : null,
       overriddenBy: toQueueConcurrencyOverriddenBy(data.concurrencyLimitOverriddenBy),
       overriddenAt: data.concurrencyLimitOverriddenAt,
-      combined:
-        data.totalConcurrencyLimit !== undefined
-          ? {
-              current: data.totalConcurrencyLimit,
-              base: data.totalConcurrencyLimitBase ?? null,
-              override: data.totalConcurrencyLimitOverriddenAt ? data.totalConcurrencyLimit : null,
-              overriddenAt: data.totalConcurrencyLimitOverriddenAt ?? null,
-              running: data.totalRunning ?? null,
-            }
-          : undefined,
     },
-    // TODO: This needs to be removed but keeping this here for now to avoid breaking existing clients
-    releaseConcurrencyOnWaitpoint: true,
   };
 }