fix(ai): replay OpenAI reasoning items on tool follow-up

.changeset/openai-reasoning-replay.md

@@ -0,0 +1,7 @@
+---
+'@tanstack/ai': patch
+'@tanstack/openai-base': patch
+'@tanstack/ai-openai': patch
+---
+
+Replay OpenAI Responses reasoning items with function_call on the next tool turn. Default `include: ['reasoning.encrypted_content']` only on reasoning models.

packages/ai-client/vite.config.ts

@@ -10,6 +10,10 @@ const config = defineConfig({
     globals: true,
     environment: 'node',
     include: ['tests/**/*.test.ts'],
+    // Resume-join tests wait REJOIN_CONNECT_DEADLINE_MS (2s) inside
+    // waitFor({ timeout: 5_000 }). Default 5s testTimeout loses that race
+    // when nx runs this suite in parallel with the rest of test:pr.
+    testTimeout: 15_000,
     // Re-route the no-op devtools factories to the real implementations
     // for the whole test suite. The shipping default is no-op (so the
     // heavy bridge classes stay out of `@tanstack/ai-client`'s main

packages/ai-openai/src/adapters/text.ts

@@ -148,6 +148,17 @@ export class OpenAITextAdapter<
       delete request.top_p
     }
 
+    // Reasoning models pair each function_call with a reasoning item. Request
+    // the encrypted blob so convertMessagesToInput can replay it. Pre-5 chat
+    // models do not emit those items, so leave include unset for them.
+    // Callers can still set include in modelOptions.
+    if (
+      request.include === undefined &&
+      openAIModelRejectsSamplingParams(options.model)
+    ) {
+      request.include = ['reasoning.encrypted_content']
+    }
+
     return request
   }
 }

packages/ai-openai/tests/openai-adapter.test.ts

@@ -131,6 +131,88 @@ describe('OpenAI adapter option mapping', () => {
     expect(payload.tools).toBeDefined()
     expect(Array.isArray(payload.tools)).toBe(true)
     expect(payload.tools.length).toBeGreaterThan(0)
+    expect(payload.include).toBeUndefined()
+  })
+
+  it('requests encrypted reasoning only on reasoning models', async () => {
+    const mockStream = createMockChatCompletionsStream([
+      {
+        type: 'response.created',
+        response: {
+          id: 'resp-reasoning-include',
+          model: 'gpt-5.6',
+          status: 'in_progress',
+          created_at: 1234567890,
+        },
+      },
+      {
+        type: 'response.completed',
+        response: {
+          id: 'resp-reasoning-include',
+          status: 'completed',
+          usage: { input_tokens: 1, output_tokens: 0 },
+        },
+      },
+    ])
+
+    const responsesCreate = vi.fn().mockResolvedValueOnce(mockStream)
+    const adapter = new OpenAITextAdapter({ apiKey: 'test-key' }, 'gpt-5.6')
+    ;(adapter as any).client = {
+      responses: {
+        create: responsesCreate,
+      },
+    }
+
+    for await (const _chunk of chat({
+      adapter,
+      messages: [{ role: 'user', content: 'Hi' }],
+    })) {
+      // consume
+    }
+
+    const [payload] = responsesCreate.mock.calls[0]!
+    expect(payload.include).toEqual(['reasoning.encrypted_content'])
+  })
+
+  it('lets callers override the default reasoning include list', async () => {
+    const mockStream = createMockChatCompletionsStream([
+      {
+        type: 'response.created',
+        response: {
+          id: 'resp-include',
+          model: 'gpt-5.6',
+          status: 'in_progress',
+          created_at: 1234567890,
+        },
+      },
+      {
+        type: 'response.completed',
+        response: {
+          id: 'resp-include',
+          status: 'completed',
+          usage: { input_tokens: 1, output_tokens: 0 },
+        },
+      },
+    ])
+
+    const responsesCreate = vi.fn().mockResolvedValueOnce(mockStream)
+    const adapter = new OpenAITextAdapter({ apiKey: 'test-key' }, 'gpt-5.6')
+    ;(adapter as any).client = {
+      responses: {
+        create: responsesCreate,
+      },
+    }
+
+    for await (const _chunk of chat({
+      adapter,
+      messages: [{ role: 'user', content: 'Hi' }],
+      modelOptions: { include: [] },
+    })) {
+      // consume
+    }
+
+    const [payload] = responsesCreate.mock.calls[0]!
+    expect(payload.include).toEqual([])
   })
 
   it('accepts mixed string + object-form systemPrompts and joins .content into instructions', async () => {

packages/ai/skills/ai-core/adapter-configuration/references/openai-adapter.md

@@ -95,3 +95,8 @@ OPENAI_API_KEY
   `effort: 'low'` or higher to enable reasoning.
 - `o3-pro` only supports `high` reasoning effort.
 - `conversation` and `previous_response_id` cannot be used together.
+- Reasoning models (`o*`, `gpt-5*` except `*-chat-latest`, `codex-mini-latest`)
+  pair each `function_call` with a `reasoning` item. The adapter requests
+  `include: ['reasoning.encrypted_content']` for those models and replays that
+  item on the next turn. Pre-5 chat models are left unchanged. If you persist
+  history by hand, keep `thinking[].signature`.

packages/ai/src/activities/chat/index.ts

@@ -1870,7 +1870,7 @@ class TextEngine<
   }
 
   private finalizeCurrentThinkingStep(): void {
-    if (this.currentThinkingContent) {
+    if (this.currentThinkingContent || this.currentThinkingSignature) {
       this.accumulatedThinking.push({
         content: this.currentThinkingContent,
         ...(this.currentThinkingSignature && {

packages/ai/src/activities/chat/messages.ts

@@ -173,10 +173,10 @@ export function convertMessagesToModelMessages(
 
     if (role === 'reasoning') {
       const content = (msg as { content?: string }).content
-      if (content) {
-        const signature = encryptedValueFrom(msg)
+      const signature = encryptedValueFrom(msg)
+      if (content || signature !== undefined) {
         pendingThinking.push({
-          content,
+          content: typeof content === 'string' ? content : '',
           ...(signature !== undefined ? { signature } : {}),
         })
       }
@@ -593,7 +593,7 @@ function buildAssistantMessages(uiMessage: UIMessage): Array<ModelMessage> {
         break
 
       case 'thinking':
-        if (part.content) {
+        if (part.content || part.signature) {
           // Provider-executed tools have no tool-result part, so thinking
           // after them has to start the next segment or it replays first.
           if (current.toolCalls.some(isProviderExecutedToolCall)) {
@@ -712,7 +712,7 @@ export function modelMessageToUIMessage(
 
   if (modelMessage.role === 'assistant' && modelMessage.thinking?.length) {
     for (const thinking of modelMessage.thinking) {
-      if (!thinking.content) continue
+      if (!thinking.content && !thinking.signature) continue
       parts.push({
         type: 'thinking',
         content: thinking.content,
@@ -917,18 +917,20 @@ export function aguiSnapshotMessageToUIMessage(
       })
     case 'reasoning': {
       const signature = encryptedValueFrom(message)
+      const content = typeof message.content === 'string' ? message.content : ''
       return applySnapshotMetadata(message, {
         id,
         role: 'assistant',
-        parts: message.content
-          ? [
-              {
-                type: 'thinking' as const,
-                content: message.content,
-                ...(signature !== undefined ? { signature } : {}),
-              },
-            ]
-          : [],
+        parts:
+          content || signature !== undefined
+            ? [
+                {
+                  type: 'thinking' as const,
+                  content,
+                  ...(signature !== undefined ? { signature } : {}),
+                },
+              ]
+            : [],
       })
     }
     case 'activity':

packages/ai/tests/ag-ui-wire.test.ts

@@ -596,6 +596,39 @@ describe('uiMessagesToWire', () => {
     })
   })
 
+  it('round-trips empty thinking content when signature is present', () => {
+    const messages: Array<UIMessage> = [
+      {
+        id: 'a1',
+        role: 'assistant',
+        parts: [
+          {
+            type: 'thinking',
+            content: '',
+            signature: '{"id":"rs_1","encrypted_content":"enc"}',
+          },
+          {
+            type: 'tool-call',
+            id: 'call_1',
+            name: 'lookup_weather',
+            arguments: '{"location":"Berlin"}',
+            state: 'input-complete',
+          },
+        ],
+      },
+    ]
+    const wire = uiMessagesToWire(messages)
+    const model = convertMessagesToModelMessages(
+      wire as Array<UIMessage | ModelMessage>,
+    )
+    expect(model[0]?.thinking).toEqual([
+      {
+        content: '',
+        signature: '{"id":"rs_1","encrypted_content":"enc"}',
+      },
+    ])
+  })
+
   it('round-trips ThinkingPart.signature on spec encryptedValue', () => {
     const messages: Array<UIMessage> = [
       {

packages/ai/tests/messages.test.ts

@@ -73,6 +73,30 @@ describe('convertMessagesToModelMessages — AG-UI dedup pre-pass', () => {
     expect(result[0]?.role).toBe('user')
   })
 
+  it('keeps reasoning encryptedValue when content is empty', () => {
+    const result = convertMessagesToModelMessages([
+      {
+        role: 'reasoning',
+        content: '',
+        encryptedValue: 'sig-empty',
+      } as unknown as ModelMessage,
+      {
+        role: 'assistant',
+        content: null,
+        toolCalls: [
+          {
+            id: 'call_1',
+            type: 'function',
+            function: { name: 'lookup', arguments: '{}' },
+          },
+        ],
+      },
+    ])
+    expect(result[0]?.thinking).toEqual([
+      { content: '', signature: 'sig-empty' },
+    ])
+  })
+
   it('attaches reasoning encryptedValue as thinking signature on the next assistant', () => {
     const result = convertMessagesToModelMessages([
       {