Add clientData support

Author: ericallam

.claude/rules/package-installation.md

@@ -0,0 +1,22 @@
+---
+paths:
+  - "**/package.json"
+---
+
+# Installing Packages
+
+When adding a new dependency to any package.json in the monorepo:
+
+1. **Look up the latest version** on npm before adding:
+   ```bash
+   pnpm view <package-name> version
+   ```
+   If unsure which version to use (e.g. major version compatibility), confirm with the user.
+
+2. **Edit the package.json directly** — do NOT use `pnpm add` as it can cause issues in the monorepo. Add the dependency with the correct version range (typically `^x.y.z`).
+
+3. **Run `pnpm i` from the repo root** after editing to install and update the lockfile:
+   ```bash
+   pnpm i
+   ```
+   Always run from the repo root, not from the package directory.

CLAUDE.md

@@ -6,6 +6,8 @@ This file provides guidance to Claude Code when working with this repository. Su
 
 This is a pnpm 10.23.0 monorepo using Turborepo. Run commands from root with `pnpm run`.
 
+**Adding dependencies:** Edit `package.json` directly instead of using `pnpm add`, then run `pnpm i` from the repo root. See `.claude/rules/package-installation.md` for the full process.
+
 ```bash
 pnpm run docker              # Start Docker services (PostgreSQL, Redis, Electric)
 pnpm run db:migrate           # Run database migrations

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

@@ -167,11 +167,23 @@ export const CHAT_STREAM_KEY = _CHAT_STREAM_KEY;
 export { CHAT_MESSAGES_STREAM_ID, CHAT_STOP_STREAM_ID };
 
 /**
- * The payload shape that the chat transport sends to the triggered task.
+ * The wire payload shape sent by `TriggerChatTransport`.
+ * Uses `metadata` to match the AI SDK's `ChatRequestOptions` field name.
+ * @internal
+ */
+type ChatTaskWirePayload<TMessage extends UIMessage = UIMessage> = {
+  messages: TMessage[];
+  chatId: string;
+  trigger: "submit-message" | "regenerate-message";
+  messageId?: string;
+  metadata?: unknown;
+};
+
+/**
+ * The payload shape passed to the `chatTask` run function.
  *
- * When using `chatTask()`, the payload is automatically typed — you don't need
- * to import this type. Use this type only if you're using `task()` directly
- * with `pipeChat()`.
+ * The `metadata` field from the AI SDK transport is exposed as `clientData`
+ * to avoid confusion with Trigger.dev's run metadata.
  */
 export type ChatTaskPayload<TMessage extends UIMessage = UIMessage> = {
   /** The conversation messages */
@@ -190,8 +202,8 @@ export type ChatTaskPayload<TMessage extends UIMessage = UIMessage> = {
   /** The ID of the message to regenerate (only for `"regenerate-message"`) */
   messageId?: string;
 
-  /** Custom metadata from the frontend */
-  metadata?: unknown;
+  /** Custom data from the frontend (passed via `metadata` on `sendMessage()` or the transport). */
+  clientData?: unknown;
 };
 
 /**
@@ -213,7 +225,7 @@ export type ChatTaskSignals = {
 export type ChatTaskRunPayload = ChatTaskPayload & ChatTaskSignals;
 
 // Input streams for bidirectional chat communication
-const messagesInput = streams.input<ChatTaskPayload>({ id: CHAT_MESSAGES_STREAM_ID });
+const messagesInput = streams.input<ChatTaskWirePayload>({ id: CHAT_MESSAGES_STREAM_ID });
 const stopInput = streams.input<{ stop: true; message?: string }>({ id: CHAT_STOP_STREAM_ID });
 
 /**
@@ -449,7 +461,7 @@ export type ChatTaskOptions<TIdentifier extends string> = Omit<
  */
 function chatTask<TIdentifier extends string>(
   options: ChatTaskOptions<TIdentifier>
-): Task<TIdentifier, ChatTaskPayload, unknown> {
+): Task<TIdentifier, ChatTaskWirePayload, unknown> {
   const {
     run: userRun,
     maxTurns = 100,
@@ -458,10 +470,10 @@ function chatTask<TIdentifier extends string>(
     ...restOptions
   } = options;
 
-  return createTask<TIdentifier, ChatTaskPayload, unknown>({
+  return createTask<TIdentifier, ChatTaskWirePayload, unknown>({
     ...restOptions,
-    run: async (payload: ChatTaskPayload, { signal: runSignal }) => {
-      let currentPayload = payload;
+    run: async (payload: ChatTaskWirePayload, { signal: runSignal }) => {
+      let currentWirePayload = payload;
 
       // Mutable reference to the current turn's stop controller so the
       // stop input stream listener (registered once) can abort the right turn.
@@ -486,15 +498,19 @@ function chatTask<TIdentifier extends string>(
           const combinedSignal = AbortSignal.any([runSignal, stopController.signal]);
 
           // Buffer messages that arrive during streaming
-          const pendingMessages: ChatTaskPayload[] = [];
+          const pendingMessages: ChatTaskWirePayload[] = [];
           const msgSub = messagesInput.on((msg) => {
-            pendingMessages.push(msg as ChatTaskPayload);
+            pendingMessages.push(msg);
           });
 
+          // Remap wire payload to user-facing payload (metadata -> clientData)
+          const { metadata: wireMetadata, ...restWire } = currentWirePayload;
+
           try {
             const result = await userRun({
-              ...currentPayload,
-              messages: sanitizeMessages(currentPayload.messages),
+              ...restWire,
+              clientData: wireMetadata,
+              messages: sanitizeMessages(currentWirePayload.messages),
               signal: combinedSignal,
               cancelSignal,
               stopSignal,
@@ -526,7 +542,7 @@ function chatTask<TIdentifier extends string>(
 
           // If messages arrived during streaming, use the first one immediately
           if (pendingMessages.length > 0) {
-            currentPayload = pendingMessages[0]!;
+            currentWirePayload = pendingMessages[0]!;
             continue;
           }
 
@@ -539,7 +555,7 @@ function chatTask<TIdentifier extends string>(
 
             if (warm.ok) {
               // Message arrived while warm — respond instantly
-              currentPayload = warm.output;
+              currentWirePayload = warm.output;
               continue;
             }
           }
@@ -552,7 +568,7 @@ function chatTask<TIdentifier extends string>(
             return;
           }
 
-          currentPayload = next.output;
+          currentWirePayload = next.output;
         }
       } finally {
         stopSub.off();

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

@@ -82,6 +82,24 @@ export type TriggerChatTransportOptions = {
    * @default 120
    */
   streamTimeoutSeconds?: number;
+
+  /**
+   * Default metadata included in every request payload.
+   * Merged with per-call `metadata` from `sendMessage()` — per-call values
+   * take precedence over transport-level defaults.
+   *
+   * Useful for data that should accompany every message, like a user ID.
+   *
+   * @example
+   * ```ts
+   * new TriggerChatTransport({
+   *   task: "my-chat",
+   *   accessToken,
+   *   metadata: { userId: currentUser.id },
+   * });
+   * ```
+   */
+  metadata?: Record<string, unknown>;
 };
 
 /**
@@ -132,6 +150,7 @@ export class TriggerChatTransport implements ChatTransport<UIMessage> {
   private readonly streamKey: string;
   private readonly extraHeaders: Record<string, string>;
   private readonly streamTimeoutSeconds: number;
+  private readonly defaultMetadata: Record<string, unknown> | undefined;
 
   private sessions: Map<string, ChatSessionState> = new Map();
 
@@ -145,6 +164,7 @@ export class TriggerChatTransport implements ChatTransport<UIMessage> {
     this.streamKey = options.streamKey ?? DEFAULT_STREAM_KEY;
     this.extraHeaders = options.headers ?? {};
     this.streamTimeoutSeconds = options.streamTimeoutSeconds ?? DEFAULT_STREAM_TIMEOUT_SECONDS;
+    this.defaultMetadata = options.metadata;
   }
 
   sendMessages = async (
@@ -158,13 +178,18 @@ export class TriggerChatTransport implements ChatTransport<UIMessage> {
   ): Promise<ReadableStream<UIMessageChunk>> => {
     const { trigger, chatId, messageId, messages, abortSignal, body, metadata } = options;
 
+    const mergedMetadata =
+      this.defaultMetadata || metadata
+        ? { ...(this.defaultMetadata ?? {}), ...((metadata as Record<string, unknown>) ?? {}) }
+        : undefined;
+
     const payload = {
       ...(body ?? {}),
       messages,
       chatId,
       trigger,
       messageId,
-      metadata,
+      metadata: mergedMetadata,
     };
 
     const session = this.sessions.get(chatId);