feat(sdk,core,webapp): chat sessions accept concurrencyKey and trigger-time named limits

Chat agents already accept the task-level concurrency option, but the
session trigger path had no way to scope runs: SessionTriggerConfig now
carries concurrencyKey and up to two named limits, threaded through the
session run trigger (initial, continuation, and upgrade re-triggers) and
forwarded by all three session starters (createStartSessionAction, the
AgentChat client, and handover). Keys are never defaulted from the chat
ID; a session without one shares the task's keyless pool. Named limits
are validated client-side with the same rules as tasks.trigger.

Author: matt-aitken

.changeset/chat-session-concurrency.md

@@ -0,0 +1,12 @@
+---
+"@trigger.dev/sdk": patch
+"@trigger.dev/core": patch
+---
+
+Chat agents can now scope concurrency per session. Pass `concurrencyKey` (for example your chat or tenant ID) and trigger-time named limits via `triggerConfig.concurrency` when starting a chat session, from `chat.createStartSessionAction`, the `AgentChat` client, or a handover. Keys are never defaulted, so a session without one shares the task's keyless pool.
+
+```ts
+const start = chat.createStartSessionAction("support-chat", {
+  triggerConfig: { concurrencyKey: user.id },
+});
+```

apps/webapp/app/services/realtime/sessionRunManager.server.ts

@@ -318,6 +318,8 @@ async function triggerSessionRun(params: {
     options: {
       ...(config.machine ? { machine: config.machine as never } : {}),
       ...(config.queue ? { queue: { name: config.queue } } : {}),
+      ...(config.concurrency ? { concurrency: config.concurrency } : {}),
+      ...(config.concurrencyKey !== undefined ? { concurrencyKey: config.concurrencyKey } : {}),
       ...(config.tags ? { tags: config.tags } : {}),
       ...(config.maxAttempts !== undefined ? { maxAttempts: config.maxAttempts } : {}),
       ...(config.maxDuration !== undefined ? { maxDuration: config.maxDuration } : {}),

docs/ai-chat/client-protocol.mdx

@@ -206,6 +206,8 @@ Pick `"preload"` when the UI has rendered but the user hasn't typed (warms the a
 | `expiresAt` | `string` (ISO date) | Retention cap. |
 | `triggerConfig.machine` | `string` | Machine preset (`micro`, `small-1x`, …) for every run. |
 | `triggerConfig.queue` | `string` | Queue name. |
+| `triggerConfig.concurrency` | `string[]` | Up to two [named concurrency limits](/concurrency#sharing-a-limit-between-tasks) every run holds, replacing the task's declared named limits. |
+| `triggerConfig.concurrencyKey` | `string` | Scopes every run of this session to its own pool under each `perKey` bound it holds. Never defaulted — pass one (e.g. your chat or tenant ID) to isolate sessions from each other. |
 | `triggerConfig.tags` | `string[]` | Tags applied to every run (in addition to session-level `tags`). |
 | `triggerConfig.maxAttempts` | `number` | Per-run retry cap (1–10). |
 | `triggerConfig.maxDuration` | `number` | Per-run wall-clock cap, seconds. |

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

@@ -1890,6 +1890,10 @@ export const SessionTriggerConfig = z.object({
   basePayload: z.record(z.unknown()),
   machine: MachinePresetName.optional(),
   queue: z.string().max(128).optional(),
+  /** Named concurrency limits every run holds, replacing the task's declared named limits. */
+  concurrency: z.string().min(1).max(128).array().max(2).optional(),
+  /** Scopes every run to its own pool under each `perKey` bound it holds. Never defaulted — a session without one shares the keyless pool. */
+  concurrencyKey: ConcurrencyKeySchema.optional(),
   tags: z.array(z.string().max(128)).max(10).optional(),
   maxAttempts: z.number().int().positive().max(10).optional(),
   /** Per-run wall-clock cap (seconds). Forwarded to `TaskRunOptions.maxDuration`. */

packages/trigger-sdk/src/v3/ai.ts

@@ -118,7 +118,7 @@ import {
   sessions,
   type SessionSubscribeOptions,
 } from "./sessions.js";
-import { createTask } from "./shared.js";
+import { createTask, triggerConcurrencyBody } from "./shared.js";
 import { markChatAgentRunForStreamsWarning } from "./streams.js";
 import { tracer } from "./tracer.js";
 
@@ -11800,6 +11800,9 @@ function createChatStartSessionAction<TChat extends AnyTask = AnyTask>(
       params.clientData !== undefined ? { metadata: params.clientData } : {};
     const maxAttempts = params.triggerConfig?.maxAttempts ?? options?.triggerConfig?.maxAttempts;
     const maxDuration = params.triggerConfig?.maxDuration ?? options?.triggerConfig?.maxDuration;
+    const concurrency = params.triggerConfig?.concurrency ?? options?.triggerConfig?.concurrency;
+    const concurrencyKey =
+      params.triggerConfig?.concurrencyKey ?? options?.triggerConfig?.concurrencyKey;
     const idleTimeoutInSeconds =
       params.triggerConfig?.idleTimeoutInSeconds ?? options?.triggerConfig?.idleTimeoutInSeconds;
 
@@ -11818,6 +11821,8 @@ function createChatStartSessionAction<TChat extends AnyTask = AnyTask>(
       ...(options?.triggerConfig?.queue || params.triggerConfig?.queue
         ? { queue: params.triggerConfig?.queue ?? options?.triggerConfig?.queue }
         : {}),
+      ...(concurrency ? triggerConcurrencyBody(concurrency) : {}),
+      ...(concurrencyKey !== undefined ? { concurrencyKey } : {}),
       tags,
       ...(maxAttempts !== undefined ? { maxAttempts } : {}),
       ...(maxDuration !== undefined ? { maxDuration } : {}),

packages/trigger-sdk/src/v3/chat-client.ts

@@ -671,6 +671,12 @@ export class AgentChat<TAgent = unknown> {
       },
       ...(this.triggerConfigDefault?.machine ? { machine: this.triggerConfigDefault.machine } : {}),
       ...(this.triggerConfigDefault?.queue ? { queue: this.triggerConfigDefault.queue } : {}),
+      ...(this.triggerConfigDefault?.concurrency
+        ? { concurrency: this.triggerConfigDefault.concurrency }
+        : {}),
+      ...(this.triggerConfigDefault?.concurrencyKey !== undefined
+        ? { concurrencyKey: this.triggerConfigDefault.concurrencyKey }
+        : {}),
       tags: chatRunTags(this.chatId, this.triggerConfigDefault?.tags),
       ...(this.triggerConfigDefault?.maxAttempts !== undefined
         ? { maxAttempts: this.triggerConfigDefault.maxAttempts }

packages/trigger-sdk/src/v3/chat-server.ts

@@ -72,6 +72,7 @@ import {
 import type { FinishReason, ModelMessage, Tool, UIMessage, UIMessageChunk } from "ai";
 import type { ChatInputChunk, ChatTaskWirePayload } from "./ai-shared.js";
 import { chatRunTags } from "./ai-shared.js";
+import { triggerConcurrencyBody } from "./shared.js";
 
 // `StreamTextResult` is defined locally rather than imported from `ai`: its
 // generic arity diverged (v6 `StreamTextResult<TOOLS, OUTPUT>`, v7
@@ -543,6 +544,12 @@ async function openHandoverSession(opts: {
     },
     ...(opts.triggerConfig?.machine ? { machine: opts.triggerConfig.machine } : {}),
     ...(opts.triggerConfig?.queue ? { queue: opts.triggerConfig.queue } : {}),
+    ...(opts.triggerConfig?.concurrency
+      ? triggerConcurrencyBody(opts.triggerConfig.concurrency)
+      : {}),
+    ...(opts.triggerConfig?.concurrencyKey !== undefined
+      ? { concurrencyKey: opts.triggerConfig.concurrencyKey }
+      : {}),
     tags,
     ...(opts.triggerConfig?.maxAttempts !== undefined
       ? { maxAttempts: opts.triggerConfig.maxAttempts }

packages/trigger-sdk/src/v3/createStartSessionAction.test.ts

@@ -150,6 +150,47 @@ describe("chat.createStartSessionAction — runtime", () => {
     expect(lastStartBody?.triggerConfig.lockToVersion).toBe("20260101.1");
   });
 
+  it("forwards concurrency and concurrencyKey from triggerConfig, with per-call precedence", async () => {
+    installStartFixture();
+
+    const start = chat.createStartSessionAction("fake-chat", {
+      triggerConfig: {
+        concurrency: ["chats"],
+        concurrencyKey: "tenant-default",
+      },
+    });
+    await start({
+      chatId: "chat-conc",
+      triggerConfig: { concurrencyKey: "tenant-42" },
+    });
+
+    expect(lastStartBody?.triggerConfig.concurrency).toEqual(["chats"]);
+    expect(lastStartBody?.triggerConfig.concurrencyKey).toBe("tenant-42");
+  });
+
+  it("never defaults concurrencyKey from the chatId", async () => {
+    installStartFixture();
+
+    const start = chat.createStartSessionAction("fake-chat");
+    await start({ chatId: "chat-no-key" });
+
+    expect(lastStartBody?.triggerConfig.concurrencyKey).toBeUndefined();
+    expect(lastStartBody?.triggerConfig.concurrency).toBeUndefined();
+  });
+
+  it("rejects invalid trigger-time limit names before any network call", async () => {
+    installStartFixture();
+
+    const start = chat.createStartSessionAction("fake-chat", {
+      triggerConfig: { concurrency: ["not a valid name!"] },
+    });
+
+    await expect(start({ chatId: "chat-bad-limit" })).rejects.toThrow(
+      /letters, numbers, underscores and hyphens/
+    );
+    expect(lastStartBody).toBeUndefined();
+  });
+
   it("server-mints override tokens for additional API keys", async () => {
     const requests: Array<{ url: string; body: unknown }> = [];
     const start = chat.createStartSessionAction("fake-chat", {

packages/trigger-sdk/src/v3/shared.ts

@@ -217,7 +217,7 @@ function triggerQueueBody(
  * Trigger-time named limits: strings only, like `queue`. They replace the task's
  * declared named limits for this run; the server resolves names to the run's gates.
  */
-function triggerConcurrencyBody(concurrency: string | string[] | undefined): {
+export function triggerConcurrencyBody(concurrency: string | string[] | undefined): {
   concurrency?: string[];
 } {
   if (!concurrency) {