Add triggerOptions to the transport, auto-tag with the chat ID

Author: ericallam

.scratch/plan-graceful-oversized-batch-items.md

@@ -488,6 +488,10 @@ function ChatClient({ chatId, initialMessages, initialSessions }) {
   `resume: true` causes `useChat` to call `reconnectToStream` on the transport when the component mounts. The transport uses the session's `lastEventId` to skip past already-seen stream events, so the frontend only receives new data. Only enable `resume` when there are existing messages — for brand new chats, there's nothing to reconnect to.
 </Info>
 
+<Warning>
+  In React strict mode (enabled by default in Next.js dev), you may see a `TypeError: Cannot read properties of undefined (reading 'state')` in the console when using `resume`. This is a [known bug in the AI SDK](https://github.com/vercel/ai/issues/8477) caused by React strict mode double-firing the resume effect. The error is caught internally and **does not affect functionality** — streaming and message display work correctly. It only appears in development and will not occur in production builds.
+</Warning>
+
 ### Full example
 
 Putting it all together — a complete chat app with server-side persistence, session reconnection, and stream resumption:
@@ -762,6 +766,32 @@ run: async ({ messages, signal }) => {
 | `metadata` | `Record<string, unknown>` | — | Default metadata for every request |
 | `sessions` | `Record<string, {...}>` | — | Restore sessions from storage |
 | `onSessionChange` | `(chatId, session \| null) => void` | — | Fires when session state changes |
+| `triggerOptions` | `{...}` | — | Options for the initial task trigger (see below) |
+
+#### triggerOptions
+
+Options forwarded to the Trigger.dev API when starting a new run. Only applies to the first message — subsequent messages reuse the same run.
+
+A `chat:{chatId}` tag is automatically added to every run.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `tags` | `string[]` | Additional tags for the run (merged with auto-tags, max 5 total) |
+| `queue` | `string` | Queue name for the run |
+| `maxAttempts` | `number` | Maximum retry attempts |
+| `machine` | `"micro" \| "small-1x" \| ...` | Machine preset for the run |
+| `priority` | `number` | Priority (lower = higher priority) |
+
+```ts
+const transport = useTriggerChatTransport({
+  task: "my-chat",
+  accessToken: getChatToken,
+  triggerOptions: {
+    tags: ["user:123"],
+    queue: "chat-queue",
+  },
+});
+```
 
 ### useTriggerChatTransport
 

docs/guides/ai-chat.mdx

@@ -151,6 +151,37 @@ export type TriggerChatTransportOptions = {
     chatId: string,
     session: { runId: string; publicAccessToken: string; lastEventId?: string } | null
   ) => void;
+
+  /**
+   * Options forwarded to the Trigger.dev API when starting a new run.
+   * Only applies to the first message — subsequent messages reuse the same run.
+   *
+   * A `chat:{chatId}` tag is automatically added to every run.
+   *
+   * @example
+   * ```ts
+   * new TriggerChatTransport({
+   *   task: "my-chat",
+   *   accessToken,
+   *   triggerOptions: {
+   *     tags: ["user:123"],
+   *     queue: "chat-queue",
+   *   },
+   * });
+   * ```
+   */
+  triggerOptions?: {
+    /** Additional tags for the run. A `chat:{chatId}` tag is always added automatically. */
+    tags?: string[];
+    /** Queue name for the run. */
+    queue?: string;
+    /** Maximum retry attempts. */
+    maxAttempts?: number;
+    /** Machine preset for the run. */
+    machine?: "micro" | "small-1x" | "small-2x" | "medium-1x" | "medium-2x" | "large-1x" | "large-2x";
+    /** Priority (lower = higher priority). */
+    priority?: number;
+  };
 };
 
 /**
@@ -202,6 +233,7 @@ export class TriggerChatTransport implements ChatTransport<UIMessage> {
   private readonly extraHeaders: Record<string, string>;
   private readonly streamTimeoutSeconds: number;
   private readonly defaultMetadata: Record<string, unknown> | undefined;
+  private readonly triggerOptions: TriggerChatTransportOptions["triggerOptions"];
   private _onSessionChange:
     | ((
         chatId: string,
@@ -223,6 +255,7 @@ export class TriggerChatTransport implements ChatTransport<UIMessage> {
     this.extraHeaders = options.headers ?? {};
     this.streamTimeoutSeconds = options.streamTimeoutSeconds ?? DEFAULT_STREAM_TIMEOUT_SECONDS;
     this.defaultMetadata = options.metadata;
+    this.triggerOptions = options.triggerOptions;
     this._onSessionChange = options.onSessionChange;
 
     // Restore sessions from external storage
@@ -303,10 +336,20 @@ export class TriggerChatTransport implements ChatTransport<UIMessage> {
     const currentToken = await this.resolveAccessToken();
     const apiClient = new ApiClient(this.baseURL, currentToken);
 
+    // Auto-tag with chatId; merge with user-provided tags (API limit: 5 tags)
+    const autoTags = [`chat:${chatId}`];
+    const userTags = this.triggerOptions?.tags ?? [];
+    const tags = [...autoTags, ...userTags].slice(0, 5);
+
     const triggerResponse = await apiClient.triggerTask(this.taskId, {
       payload,
       options: {
         payloadType: "application/json",
+        tags,
+        queue: this.triggerOptions?.queue ? { name: this.triggerOptions.queue } : undefined,
+        maxAttempts: this.triggerOptions?.maxAttempts,
+        machine: this.triggerOptions?.machine,
+        priority: this.triggerOptions?.priority,
       },
     });
 

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

@@ -62,6 +62,9 @@ export function ChatApp({
     baseURL: process.env.NEXT_PUBLIC_TRIGGER_API_URL,
     sessions: initialSessions,
     onSessionChange: handleSessionChange,
+    triggerOptions: {
+      tags: ["user:user_123"],
+    },
   });
 
   // Load messages when active chat changes