fix(chat): merge an action's metadata over the transport's clientData

sendAction with per-action metadata replaced the transport defaults instead
of merging them, so required default fields vanished for direct callers.
sendMessages already merged before routing; sendAction now merges itself, and
its docstring describes the chat.turn() model.

Author: ericallam

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

@@ -1021,6 +1021,35 @@ describe("TriggerChatTransport", () => {
       expect(actionBody.payload.metadata).toEqual({ tenant: "t-1" });
     });
 
+    it("merges per-action metadata over the transport's clientData", async () => {
+      let actionBody: any;
+      global.fetch = vi.fn().mockImplementation(async (url: string | URL, init?: RequestInit) => {
+        const urlStr = typeof url === "string" ? url : url.toString();
+        if (isSessionStreamAppendUrl(urlStr)) {
+          actionBody = JSON.parse(init!.body as string);
+          return defaultAppendResponse();
+        }
+        if (isSessionOutSubscribeUrl(urlStr)) return defaultSseResponse();
+        throw new Error(`Unexpected URL: ${urlStr}`);
+      });
+
+      const transport = new TriggerChatTransport({
+        task: "my-chat-task",
+        accessToken: () => "pat",
+        sessions: { "chat-act-meta": { publicAccessToken: "p" } },
+        clientData: { userId: "u1", scope: "default" } as Record<string, unknown>,
+      });
+
+      const stream = await transport.sendAction(
+        "chat-act-meta",
+        { type: "undo" },
+        { metadata: { scope: "action" } }
+      );
+      await drainChunks(stream);
+
+      expect(actionBody.payload.metadata).toEqual({ userId: "u1", scope: "action" });
+    });
+
     it("marks the session streaming and notifies before subscribing", async () => {
       global.fetch = vi.fn().mockImplementation(async (url: string | URL) => {
         const urlStr = typeof url === "string" ? url : url.toString();

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

@@ -1260,11 +1260,11 @@ export class TriggerChatTransport implements ChatTransport<UIMessage> {
 
   /**
    * Send a custom action chunk (for `chat.agent`'s `actionSchema` /
-   * `onAction` hook). Actions are not turns — only `hydrateMessages`
-   * and `onAction` fire on the agent side. The returned stream
-   * carries any model response `onAction` produced (when it returns a
-   * `StreamTextResult`); for `void`-returning side-effect-only actions
-   * the stream completes immediately with `trigger:turn-complete`.
+   * `onAction` hook). An action is an edit: only `hydrateMessages` and
+   * `onAction` fire on the agent side, and the returned stream completes
+   * with `trigger:turn-complete` once the edit is persisted. When `onAction`
+   * returns `chat.turn()` the turn's response follows on the same stream.
+   * Per-action `metadata` is merged over the transport's `clientData`.
    */
   sendAction = async (
     chatId: string,
@@ -1284,7 +1284,10 @@ export class TriggerChatTransport implements ChatTransport<UIMessage> {
       chatId,
       trigger: "action" as const,
       action,
-      metadata: options?.metadata ?? this.defaultMetadata ?? undefined,
+      metadata:
+        this.defaultMetadata || options?.metadata
+          ? { ...(this.defaultMetadata ?? {}), ...(options?.metadata ?? {}) }
+          : undefined,
     };
 
     const body = this.serializeInputChunk({ kind: "message", payload: wirePayload });