feat(sdk,core,cli): the concurrency option and named concurrency limits

Tasks declare concurrency directly: an inline { perKey, total } shape
caps the task, and concurrencyLimit() declares a named, shareable limit
that tasks hold via the same option (at most one inline plus two named).
Trigger calls switch a run's named limits with their own concurrency
option, strings only like queue. The queue tuple syntax and
combinedConcurrencyLimit never ship: queue() is a line again, its
concurrencyLimit deprecated in place, and the manifest carries the new
declarations for the server to compile.

Author: matt-aitken

.changeset/queue-combined-concurrency-limit.md

@@ -0,0 +1,20 @@
+---
+"@trigger.dev/sdk": patch
+"@trigger.dev/core": patch
+---
+
+Control a task's concurrency with the new `concurrency` option, and share limits across tasks with named concurrency limits. An inline shape caps the task itself; `concurrencyLimit()` declares a limit any task can hold (up to two named limits per task), and a trigger call can switch a run's named limits with its own `concurrency` option.
+
+```ts
+import { concurrencyLimit, task } from "@trigger.dev/sdk";
+
+export const openaiLimit = concurrencyLimit({ name: "openai", total: 25 });
+
+export const generateSummary = task({
+  id: "generate-summary",
+  concurrency: [{ perKey: 1, total: 5 }, openaiLimit],
+  run: async (payload) => {},
+});
+```
+
+`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.

.changeset/queue-gates.md

@@ -196,6 +196,7 @@ await sendMessageInCatalog(
       prompts: convertPromptSchemasToJsonSchemas(resourceCatalog.listPromptManifests()),
       skills: resourceCatalog.listSkillManifests(),
       queues: resourceCatalog.listQueueManifests(),
+      concurrencyLimits: resourceCatalog.listConcurrencyLimitManifests(),
       configPath: buildManifest.configPath,
       runtime: buildManifest.runtime,
       runtimeVersion: detectRuntimeVersion(),

.changeset/task-concurrency.md

@@ -192,6 +192,7 @@ await sendMessageInCatalog(
       prompts: convertPromptSchemasToJsonSchemas(resourceCatalog.listPromptManifests()),
       skills: resourceCatalog.listSkillManifests(),
       queues: resourceCatalog.listQueueManifests(),
+      concurrencyLimits: resourceCatalog.listConcurrencyLimitManifests(),
       configPath: buildManifest.configPath,
       runtime: buildManifest.runtime,
       runtimeVersion: detectRuntimeVersion(),

packages/cli-v3/src/entryPoints/dev-index-worker.ts

@@ -7,6 +7,7 @@ import type {
   WebhookManifest,
   WebhookMetadata,
   WorkerManifest,
+  ConcurrencyLimitManifest,
 } from "../schemas/index.js";
 import type {
   PromptMetadataWithFunctions,
@@ -27,6 +28,8 @@ export interface ResourceCatalog {
   registerWorkerManifest(workerManifest: WorkerManifest): void;
   registerQueueMetadata(queue: QueueManifest): void;
   listQueueManifests(): Array<QueueManifest>;
+  registerConcurrencyLimitMetadata(limit: ConcurrencyLimitManifest): void;
+  listConcurrencyLimitManifests(): Array<ConcurrencyLimitManifest>;
   getTaskSchema(id: string): TaskSchema | undefined;
   registerPromptMetadata(prompt: PromptMetadataWithFunctions): void;
   listPromptManifests(): Array<PromptManifest>;

packages/cli-v3/src/entryPoints/managed-index-worker.ts

@@ -9,6 +9,7 @@ import type {
   WebhookManifest,
   WebhookMetadata,
   WorkerManifest,
+  ConcurrencyLimitManifest,
 } from "../schemas/index.js";
 import type {
   PromptMetadataWithFunctions,
@@ -94,6 +95,14 @@ export class ResourceCatalogAPI {
     return this.#getCatalog().listQueueManifests();
   }
 
+  public registerConcurrencyLimitMetadata(limit: ConcurrencyLimitManifest): void {
+    this.#getCatalog().registerConcurrencyLimitMetadata(limit);
+  }
+
+  public listConcurrencyLimitManifests(): Array<ConcurrencyLimitManifest> {
+    return this.#getCatalog().listConcurrencyLimitManifests();
+  }
+
   public registerPromptMetadata(prompt: PromptMetadataWithFunctions): void {
     this.#getCatalog().registerPromptMetadata(prompt);
   }

packages/core/src/v3/resource-catalog/catalog.ts

@@ -7,6 +7,7 @@ import type {
   WebhookManifest,
   WebhookMetadata,
   WorkerManifest,
+  ConcurrencyLimitManifest,
 } from "../schemas/index.js";
 import {
   type PromptMetadataWithFunctions,
@@ -72,6 +73,12 @@ export class NoopResourceCatalog implements ResourceCatalog {
     return [];
   }
 
+  registerConcurrencyLimitMetadata(limit: ConcurrencyLimitManifest): void {}
+
+  listConcurrencyLimitManifests(): Array<ConcurrencyLimitManifest> {
+    return [];
+  }
+
   registerPromptMetadata(prompt: PromptMetadataWithFunctions): void {
     // noop
   }

packages/core/src/v3/resource-catalog/index.ts

@@ -10,6 +10,7 @@ import type {
   WebhookMetadata,
   WorkerManifest,
   QueueManifest,
+  ConcurrencyLimitManifest,
 } from "../schemas/index.js";
 import type {
   PromptMetadataWithFunctions,
@@ -41,6 +42,7 @@ export class StandardResourceCatalog implements ResourceCatalog {
   private _promptSchemas: Map<string, TaskSchema> = new Map();
   private _currentFileContext?: Omit<TaskFileMetadata, "exportName">;
   private _queueMetadata: Map<string, QueueManifest> = new Map();
+  private _concurrencyLimitMetadata: Map<string, ConcurrencyLimitManifest> = new Map();
   private _skillMetadata: Map<string, SkillMetadata> = new Map();
   private _skillFileMetadata: Map<string, TaskFileMetadata> = new Map();
   private _webhookMetadata: Map<string, WebhookMetadata> = new Map();
@@ -99,6 +101,25 @@ export class StandardResourceCatalog implements ResourceCatalog {
     this._queueMetadata.set(queue.name, queue);
   }
 
+  registerConcurrencyLimitMetadata(limit: ConcurrencyLimitManifest): void {
+    const existing = this._concurrencyLimitMetadata.get(limit.name);
+
+    //if it exists already with different settings, log a warning and keep the first definition
+    if (existing) {
+      if (existing.perKey !== limit.perKey || existing.total !== limit.total) {
+        console.warn(
+          `Concurrency limit "${limit.name}" is defined twice, with different settings.` +
+            `\n        - perKey: ${existing.perKey} vs ${limit.perKey}` +
+            `\n        - total: ${existing.total} vs ${limit.total}` +
+            `\n       Keeping the first definition.`
+        );
+        return;
+      }
+    }
+
+    this._concurrencyLimitMetadata.set(limit.name, limit);
+  }
+
   registerWorkerManifest(workerManifest: WorkerManifest): void {
     for (const task of workerManifest.tasks) {
       this._taskFileMetadata.set(task.id, {
@@ -222,6 +243,10 @@ export class StandardResourceCatalog implements ResourceCatalog {
     return Array.from(this._queueMetadata.values());
   }
 
+  listConcurrencyLimitManifests(): Array<ConcurrencyLimitManifest> {
+    return Array.from(this._concurrencyLimitMetadata.values());
+  }
+
   getTaskManifest(id: string): TaskManifest | undefined {
     const metadata = this._taskMetadata.get(id);
     const fileMetadata = this._taskFileMetadata.get(id);

packages/core/src/v3/resource-catalog/noopResourceCatalog.ts

@@ -336,6 +336,7 @@ export const TriggerTaskRequestBody = z
           )
           .max(2)
           .optional(),
+        concurrency: z.string().min(1).max(128).array().max(2).optional(),
         concurrencyKey: ConcurrencyKeySchema.optional(),
         delay: z.string().or(z.coerce.date()).optional(),
         idempotencyKey: z
@@ -451,6 +452,7 @@ export const BatchTriggerTaskItem = z.object({
         )
         .max(2)
         .optional(),
+      concurrency: z.string().min(1).max(128).array().max(2).optional(),
       tags: RunTags.optional(),
       test: z.boolean().optional(),
       ttl: z.string().or(z.number().nonnegative().int()).optional(),