feat(ai-client): accept a per-call body via SendMessageOptions

ChatClient.sendMessage already took a per-call body as its positional
second argument, but every framework hook (useChat, injectChat,
createChat, ...) exposes sendMessage(content, options) and forwards
undefined for it — leaving no race-free way to send per-message data
(e.g. attachment ids) through a hook: updating a reactive chat-level
body/forwardedProps option right before sending can flush after the
send.

SendMessageOptions gains an optional body that ChatClient resolves as a
fallback to the positional argument (positional wins), so every wrapper
inherits the capability with no wrapper code changes. Queued sends
preserve it exactly like the positional form.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: 2 people

.changeset/spotty-donuts-repeat.md

@@ -0,0 +1,9 @@
+---
+'@tanstack/ai-client': minor
+---
+
+Add `body` to `SendMessageOptions`: a per-call body shallow-merged into the request's `forwardedProps` with the highest priority.
+
+`ChatClient.sendMessage` already accepted a per-call body as its positional second argument, but the framework hooks (`useChat`, `injectChat`, `createChat`, …) expose `sendMessage(content, options)` and forwarded `undefined` for it — leaving no race-free way to send per-message data (e.g. attachment ids) through a hook. Updating a reactive chat-level `body`/`forwardedProps` option right before sending is racy because reactive option changes can flush after the send.
+
+`sendMessage(content, { body: { ... } })` now works through every framework hook and on `ChatClient` directly. The positional argument wins if both are provided. Queued sends preserve their per-call `body` exactly like the positional form.

docs/chat/connection-adapters.md

@@ -80,6 +80,24 @@ const { messages } = useChat({
 
 > **Tip:** `body` and `forwardedProps` populate the same wire field. Use `body` for static defaults, the `forwardedProps` constructor option (or per-`sendMessage` `data`) for dynamic values. Runtime values always win.
 
+**Per-call body.** For data that belongs to one specific message (attachment ids, a one-off flag), pass `body` in `sendMessage`'s options — it is shallow-merged into `forwardedProps` with the highest priority, for that request only:
+
+```typescript
+import { useChat, fetchServerSentEvents } from "@tanstack/ai-react";
+
+const { sendMessage } = useChat({
+  connection: fetchServerSentEvents("/api/chat"),
+  body: { provider: "openai" },
+});
+
+// forwardedProps for this request: { provider: "openai", attachmentIds: [...] }
+await sendMessage("Summarize the attached files", {
+  body: { attachmentIds: ["att_1", "att_2"] },
+});
+```
+
+This is race-free where updating a reactive chat-level `body`/`forwardedProps` option right before sending is not (reactive option changes can flush after the send). On `ChatClient` directly, the positional `body` argument does the same thing and wins if both are provided.
+
 ### Resumable SSE
 
 `fetchServerSentEvents` watches SSE `id:` values. If a connection drops after

packages/ai-angular/tests/inject-chat.test.ts

@@ -123,6 +123,29 @@ describe('injectChat — streaming', () => {
     expect(result.isLoading()).toBe(false)
   })
 
+  it('merges sendMessage options.body into the request', async () => {
+    let capturedData: Record<string, any> | undefined
+    const adapter = createMockConnectionAdapter({
+      chunks: createTextChunks('Hello there'),
+      onConnect: (_messages, data) => {
+        capturedData = data
+      },
+    })
+    const { result, flush } = renderInjectChat({
+      connection: adapter,
+      body: { provider: 'openai' },
+    })
+
+    // injectChat has no positional body arg — options.body is the per-call
+    // channel, merged over the chat-level `body` option.
+    await result.sendMessage('Hi', { body: { attachmentIds: ['a1', 'a2'] } })
+    await tick()
+    flush()
+
+    expect(capturedData?.['provider']).toBe('openai')
+    expect(capturedData?.['attachmentIds']).toEqual(['a1', 'a2'])
+  })
+
   it('initializes with provided messages', () => {
     const adapter = createMockConnectionAdapter()
     const initialMessages = [

packages/ai-client/src/chat-client.ts

@@ -1773,7 +1773,9 @@ export class ChatClient<
    * @param body - Optional body parameters to merge with the client's base body for this request.
    *               Uses shallow merge with per-message body taking priority.
    * @param sendOptions - Per-call overrides, e.g. `{ whenBusy: 'interrupt' }` to
-   *                      override the configured queue policy for this one send.
+   *                      override the configured queue policy for this one send,
+   *                      or `{ body }` as an alternative to the positional `body`
+   *                      argument (the positional argument wins if both are set).
    *
    * @example
    * ```ts
@@ -1783,9 +1785,13 @@ export class ChatClient<
    * // Text message with custom body params
    * await client.sendMessage('Hello!', { temperature: 0.7 })
    *
-   * // Per-call whenBusy override (body must still be the 2nd arg on ChatClient)
+   * // Per-call whenBusy override
    * await client.sendMessage('Urgent', undefined, { whenBusy: 'interrupt' })
    *
+   * // Per-call body via options — same effect as the positional arg. This is
+   * // the shape the framework hooks (`useChat`, `injectChat`, …) forward.
+   * await client.sendMessage('Hello!', undefined, { body: { temperature: 0.7 } })
+   *
    * // Multimodal message with image
    * await client.sendMessage({
    *   content: [
@@ -1823,13 +1829,17 @@ export class ChatClient<
       )
     }
 
+    // Positional `body` wins over `sendOptions.body` — the positional arg
+    // predates the option and existing callers may pass both.
+    const resolvedBody = body ?? sendOptions?.body
+
     if (this.isSendBusy()) {
       const { action, id } = this.decideWhenBusy(content, sendOptions)
       if (action === 'drop') {
         return
       }
       if (action === 'queue') {
-        this.enqueueMessage(content, body, id)
+        this.enqueueMessage(content, resolvedBody, id)
         return
       }
       // 'interrupt': abort the current stream, then send now.
@@ -1846,7 +1856,7 @@ export class ChatClient<
     }
 
     try {
-      await this.deliverMessage(content, body)
+      await this.deliverMessage(content, resolvedBody)
     } finally {
       this.sendInFlight = false
     }

packages/ai-client/src/types.ts

@@ -411,6 +411,20 @@ export type QueueOption = WhenBusy | QueueConfig | QueueStrategy
 export interface SendMessageOptions {
   /** Overrides the configured `whenBusy` for this one send. */
   whenBusy?: WhenBusy
+  /**
+   * Body parameters merged into this request's wire `forwardedProps`
+   * (shallow merge, highest priority — wins over the chat-level `body` and
+   * `forwardedProps` options on key collisions).
+   *
+   * Equivalent to the positional `body` argument of `ChatClient.sendMessage`;
+   * if both are provided, the positional argument wins. The framework hooks
+   * (`useChat`, `injectChat`, …) expose `sendMessage(content, options)`
+   * without the positional argument, so this option is the way to pass a
+   * per-call body through them — chat-level `forwardedProps` set via
+   * reactive options can flush asynchronously, which makes "set option,
+   * then send" racy for data that belongs to one specific message.
+   */
+  body?: Record<string, any>
 }
 
 /**

packages/ai-client/tests/chat-client-queue.test.ts

@@ -685,6 +685,42 @@ describe('ChatClient queue policy branches', () => {
     expect(seenBodies.map((b) => b?.tag)).toEqual(['seed', 'y'])
   })
 
+  it('preserves sendOptions.body for queued sends', async () => {
+    const seenBodies: Array<Record<string, unknown> | undefined> = []
+    const deferred = createDeferred<void>()
+    let call = 0
+    const connection: ConnectConnectionAdapter = {
+      async *connect(_messages, data) {
+        call += 1
+        seenBodies.push(
+          data && typeof data === 'object'
+            ? (data as Record<string, unknown>)
+            : undefined,
+        )
+        if (call === 1) {
+          await deferred.promise
+        }
+        yield* createTextChunks('done', `msg-${call}`)
+      },
+    }
+
+    // Hook-style calls: body rides in sendOptions, positional arg unused.
+    const client = new ChatClient({ connection })
+    const firstSend = client.sendMessage('first', undefined, {
+      body: { tag: 'seed' },
+    })
+    await vi.waitFor(() => {
+      expect(client.getIsLoading()).toBe(true)
+    })
+    await client.sendMessage('a', undefined, { body: { tag: 'a' } })
+    deferred.resolve()
+    await firstSend
+    await vi.waitFor(() => {
+      expect(client.getQueue()).toEqual([])
+    })
+    expect(seenBodies.map((b) => b?.tag)).toEqual(['seed', 'a'])
+  })
+
   it('batch drain does not strand messages enqueued during the batch stream', async () => {
     const deferred1 = createDeferred<void>()
     const deferred2 = createDeferred<void>()

packages/ai-client/tests/chat-client.test.ts

@@ -3397,6 +3397,55 @@ describe('ChatClient', () => {
       expect(capturedData?.['maxTokens']).toBe(100) // From per-message body
     })
 
+    it('should merge sendOptions.body into the request (hook-style per-call body)', async () => {
+      const chunks = createTextChunks('Response')
+      let capturedData: Record<string, any> | undefined
+      const adapter = createMockConnectionAdapter({
+        chunks,
+        onConnect: (_messages, data) => {
+          capturedData = data
+        },
+      })
+
+      const client = new ChatClient({
+        connection: adapter,
+        body: { model: 'gpt-5.5', temperature: 0.7 },
+      })
+
+      // The framework hooks call sendMessage(content, undefined, sendOptions),
+      // so `sendOptions.body` is their only per-call body channel.
+      await client.sendMessage('Hello', undefined, {
+        body: { model: 'gpt-6', maxTokens: 100 },
+      })
+
+      expect(capturedData?.['model']).toBe('gpt-6') // From sendOptions.body
+      expect(capturedData?.['temperature']).toBe(0.7) // From base body
+      expect(capturedData?.['maxTokens']).toBe(100) // From sendOptions.body
+    })
+
+    it('positional body wins over sendOptions.body', async () => {
+      const chunks = createTextChunks('Response')
+      let capturedData: Record<string, any> | undefined
+      const adapter = createMockConnectionAdapter({
+        chunks,
+        onConnect: (_messages, data) => {
+          capturedData = data
+        },
+      })
+
+      const client = new ChatClient({ connection: adapter })
+
+      await client.sendMessage(
+        'Hello',
+        { tag: 'positional' },
+        { body: { tag: 'options', extra: true } },
+      )
+
+      // The positional arg replaces (not merges with) sendOptions.body.
+      expect(capturedData?.['tag']).toBe('positional')
+      expect(capturedData?.['extra']).toBeUndefined()
+    })
+
     it('should accept forwardedProps option and merge into request body', async () => {
       const chunks = createTextChunks('Response')
       let capturedData: Record<string, any> | undefined

packages/ai-preact/src/use-mcp-app-bridge.ts

@@ -19,7 +19,7 @@ export type UseMcpAppBridgeOptions = CreateMcpAppBridgeOptions
  * const bridge = useMcpAppBridge({
  *   threadId,
  *   callEndpoint: '/api/mcp-apps-call',
- *   chat: { sendMessage: async (content) => void sendMessage(content) },
+ *   chat: { sendMessage: (content, body) => sendMessage(content, { body }) },
  *   onLink: (url) => window.open(url, '_blank', 'noopener,noreferrer'),
  * })
  * // pass `bridge` to <MCPAppResource bridge={bridge} … />

packages/ai-react/src/types.ts

@@ -164,7 +164,9 @@ interface BaseUseChatReturn<
    * Can be a simple string or multimodal content with images, audio, etc.
    * By default, sends while busy are queued until the run settles successfully
    * (`queue: 'drop'` restores the old drop-while-busy behavior).
-   * Pass `{ whenBusy }` to override the policy for a single send.
+   * Pass `{ whenBusy }` to override the policy for a single send, or
+   * `{ body }` to merge per-call body params into this request's
+   * `forwardedProps`.
    */
   sendMessage: (
     content: string | MultimodalContent,

packages/ai-react/src/use-mcp-app-bridge.ts

@@ -19,7 +19,7 @@ export type UseMcpAppBridgeOptions = CreateMcpAppBridgeOptions
  * const bridge = useMcpAppBridge({
  *   threadId,
  *   callEndpoint: '/api/mcp-apps-call',
- *   chat: { sendMessage: async (content) => void sendMessage(content) },
+ *   chat: { sendMessage: (content, body) => sendMessage(content, { body }) },
  *   onLink: (url) => window.open(url, '_blank', 'noopener,noreferrer'),
  * })
  * // pass `bridge` to <MCPAppResource bridge={bridge} … />