@tanstack/openai-base 0.10.1 → 0.10.3

package/src/adapters/responses-text.ts

@@ -6,7 +6,9 @@ import {
 } from '@tanstack/ai/adapter-internals'
 import { generateId } from '@tanstack/ai-utils'
 import { extractRequestOptions } from '../utils/request-options'
-import { makeStructuredOutputCompatible } from '../utils/schema-converter'
+import { makeStructuredOutputCompatibleWithMap } from '../utils/schema-converter'
+import { createToolInputNormalizer } from '../utils/tool-input-normalizer'
+import type { StructuredOutputCompatibility } from '../utils/schema-converter'
 import { buildResponsesUsage } from '../usage'
 import { convertToolsToResponsesFormat } from './responses-tool-converter'
 import type OpenAI from 'openai'
@@ -27,7 +29,7 @@ import type {
   DefaultMessageMetadataByModality,
   Modality,
   ModelMessage,
-  StreamChunk,
+  AdapterYieldChunk,
   TextOptions,
 } from '@tanstack/ai'
 
@@ -89,7 +91,7 @@ export abstract class OpenAIBaseResponsesTextAdapter<
 
   async *chatStream(
     options: TextOptions<TProviderOptions>,
-  ): AsyncIterable<StreamChunk> {
+  ): AsyncIterable<AdapterYieldChunk> {
     // Key streamed state by output item ID because argument deltas reference
     // `item_id`. The state separately retains `call_id`, which is the public
     // tool-call ID and the correlation key for function_call_output.
@@ -298,7 +300,7 @@ export abstract class OpenAIBaseResponsesTextAdapter<
    */
   async *structuredOutputStream(
     options: StructuredOutputOptions<TProviderOptions>,
-  ): AsyncIterable<StreamChunk> {
+  ): AsyncIterable<AdapterYieldChunk> {
     const { chatOptions, outputSchema } = options
     const requestParams = this.mapOptionsToRequest(chatOptions)
 
@@ -325,7 +327,7 @@ export abstract class OpenAIBaseResponsesTextAdapter<
 
     const closeReasoning = function* (this: {
       name: string
-    }): Generator<StreamChunk> {
+    }): Generator<AdapterYieldChunk> {
       if (reasoningMessageId && !hasClosedReasoning) {
         hasClosedReasoning = true
         yield {
@@ -350,12 +352,15 @@ export abstract class OpenAIBaseResponsesTextAdapter<
             content: accumulatedReasoning,
           }
         }
+        reasoningMessageId = undefined
+        stepId = undefined
+        hasClosedReasoning = false
       }
     }.bind(this)
 
     const openReasoning = function* (this: {
       name: string
-    }): Generator<StreamChunk> {
+    }): Generator<AdapterYieldChunk> {
       if (reasoningMessageId) return
       reasoningMessageId = generateId(this.name)
       stepId = generateId(this.name)
@@ -674,15 +679,29 @@ export abstract class OpenAIBaseResponsesTextAdapter<
     )
   }
 
+  /**
+   * Strict conversion plus the inverse null-widening map for this request.
+   * Override this when schema conversion changes, so tool-input undo matches
+   * the wire schema.
+   */
+  protected makeStructuredOutputCompatibleWithMap(
+    schema: Record<string, any>,
+    originalRequired?: Array<string>,
+  ): StructuredOutputCompatibility {
+    return makeStructuredOutputCompatibleWithMap(schema, originalRequired)
+  }
+
   /**
    * Applies provider-specific transformations for structured output compatibility.
-   * Override this in subclasses to handle provider-specific quirks.
+   * Override `makeStructuredOutputCompatibleWithMap` when you need the inverse map
+   * to match the wire schema.
    */
   protected makeStructuredOutputCompatible(
     schema: Record<string, any>,
     originalRequired?: Array<string>,
   ): Record<string, any> {
-    return makeStructuredOutputCompatible(schema, originalRequired)
+    return this.makeStructuredOutputCompatibleWithMap(schema, originalRequired)
+      .schema
   }
 
   /**
@@ -782,7 +801,12 @@ export abstract class OpenAIBaseResponsesTextAdapter<
       messageId: string
       hasEmittedRunStarted: boolean
     },
-  ): AsyncIterable<StreamChunk> {
+  ): AsyncIterable<AdapterYieldChunk> {
+    const normalizeToolInput = createToolInputNormalizer(
+      options.tools,
+      (schema, required) =>
+        this.makeStructuredOutputCompatibleWithMap(schema, required),
+    )
     let accumulatedContent = ''
     let accumulatedReasoning = ''
 
@@ -796,12 +820,95 @@ export abstract class OpenAIBaseResponsesTextAdapter<
     // AG-UI lifecycle tracking
     let stepId: string | null = null
     let hasEmittedTextMessageStart = false
-    let hasEmittedStepStarted = false
+    let reasoningMessageId: string | undefined
+    let hasClosedReasoning = false
     // Track whether we've emitted a terminal RUN_FINISHED so the
     // end-of-stream fallback below knows to synthesise one when the upstream
     // cuts off without a response.completed event.
     let runFinishedEmitted = false
 
+    const adapterName = this.name
+    const emitModel = () => model || options.model
+
+    const openReasoning = function* (): Generator<AdapterYieldChunk> {
+      if (reasoningMessageId) return
+      reasoningMessageId = generateId(adapterName)
+      stepId = generateId(adapterName)
+      const timestamp = Date.now()
+      const currentModel = emitModel()
+      yield {
+        type: EventType.REASONING_START,
+        messageId: reasoningMessageId,
+        model: currentModel,
+        timestamp,
+      }
+      yield {
+        type: EventType.REASONING_MESSAGE_START,
+        messageId: reasoningMessageId,
+        role: 'reasoning' as const,
+        model: currentModel,
+        timestamp,
+      }
+      yield {
+        type: EventType.STEP_STARTED,
+        stepName: stepId,
+        stepId,
+        model: currentModel,
+        timestamp,
+        stepType: 'thinking',
+      }
+    }
+
+    const closeReasoning = function* (): Generator<AdapterYieldChunk> {
+      if (!reasoningMessageId || hasClosedReasoning) return
+      hasClosedReasoning = true
+      const timestamp = Date.now()
+      const currentModel = emitModel()
+      yield {
+        type: EventType.REASONING_MESSAGE_END,
+        messageId: reasoningMessageId,
+        model: currentModel,
+        timestamp,
+      }
+      yield {
+        type: EventType.REASONING_END,
+        messageId: reasoningMessageId,
+        model: currentModel,
+        timestamp,
+      }
+      if (stepId) {
+        yield {
+          type: EventType.STEP_FINISHED,
+          stepName: stepId,
+          stepId,
+          model: currentModel,
+          timestamp,
+          content: accumulatedReasoning,
+        }
+      }
+      reasoningMessageId = undefined
+      stepId = null
+      hasClosedReasoning = false
+      accumulatedReasoning = ''
+    }
+
+    const emitReasoningDelta = function* (
+      text: string,
+    ): Generator<AdapterYieldChunk> {
+      if (!text) return
+      yield* openReasoning()
+      if (!reasoningMessageId) return
+      accumulatedReasoning += text
+      hasStreamedReasoningDeltas = true
+      yield {
+        type: EventType.REASONING_MESSAGE_CONTENT,
+        messageId: reasoningMessageId,
+        delta: text,
+        model: emitModel(),
+        timestamp: Date.now(),
+      }
+    }
+
     try {
       for await (const chunk of stream) {
         options.logger.provider(`provider=${this.name} type=${chunk.type}`, {
@@ -826,7 +933,7 @@ export abstract class OpenAIBaseResponsesTextAdapter<
           type: string
           text?: string
           refusal?: string
-        }): StreamChunk => {
+        }): AdapterYieldChunk => {
           if (contentPart.type === 'output_text') {
             accumulatedContent += contentPart.text || ''
             return {
@@ -839,25 +946,6 @@ export abstract class OpenAIBaseResponsesTextAdapter<
             }
           }
 
-          if (contentPart.type === 'reasoning_text') {
-            accumulatedReasoning += contentPart.text || ''
-            // Cache the fallback stepId rather than generating a fresh one
-            // on every call — otherwise multiple reasoning chunks arriving
-            // before STEP_STARTED was emitted (e.g. via response.content_part.done
-            // alone) would each get a different stepId and break correlation.
-            if (!stepId) {
-              stepId = generateId(this.name)
-            }
-            return {
-              type: EventType.STEP_FINISHED,
-              stepName: stepId,
-              stepId,
-              model: model || options.model,
-              timestamp: Date.now(),
-              delta: contentPart.text || '',
-              content: accumulatedReasoning,
-            }
-          }
           // Either a real refusal or an unknown content_part type. Surface
           // the part type in the error so unknown parts are debuggable
           // instead of being misreported as "Unknown refusal".
@@ -892,7 +980,9 @@ export abstract class OpenAIBaseResponsesTextAdapter<
           hasStreamedContentDeltas = false
           hasStreamedReasoningDeltas = false
           hasEmittedTextMessageStart = false
-          hasEmittedStepStarted = false
+          reasoningMessageId = undefined
+          hasClosedReasoning = false
+          stepId = null
           accumulatedContent = ''
           accumulatedReasoning = ''
         }
@@ -907,6 +997,7 @@ export abstract class OpenAIBaseResponsesTextAdapter<
           chunk.type === 'response.failed' ||
           chunk.type === 'response.incomplete'
         ) {
+          yield* closeReasoning()
           if (hasEmittedTextMessageStart) {
             yield {
               type: EventType.TEXT_MESSAGE_END,
@@ -962,6 +1053,7 @@ export abstract class OpenAIBaseResponsesTextAdapter<
               : ''
 
           if (textDelta) {
+            yield* closeReasoning()
             // Emit TEXT_MESSAGE_START on first text content
             if (!hasEmittedTextMessageStart) {
               hasEmittedTextMessageStart = true
@@ -990,90 +1082,47 @@ export abstract class OpenAIBaseResponsesTextAdapter<
         // Handle reasoning deltas (token-by-token thinking/reasoning streaming)
         // response.reasoning_text.delta provides incremental reasoning updates
         if (chunk.type === 'response.reasoning_text.delta' && chunk.delta) {
-          // Delta can be an array of strings or a single string
           const reasoningDelta = Array.isArray(chunk.delta)
             ? chunk.delta.join('')
             : typeof chunk.delta === 'string'
               ? chunk.delta
               : ''
-
-          if (reasoningDelta) {
-            // Emit STEP_STARTED on first reasoning content
-            if (!hasEmittedStepStarted) {
-              hasEmittedStepStarted = true
-              stepId = generateId(this.name)
-              yield {
-                type: EventType.STEP_STARTED,
-                stepName: stepId,
-                stepId,
-                model: model || options.model,
-                timestamp: Date.now(),
-                stepType: 'thinking',
-              }
-            }
-
-            accumulatedReasoning += reasoningDelta
-            hasStreamedReasoningDeltas = true
-            const fallbackStepId = stepId || generateId(this.name)
-            yield {
-              type: EventType.STEP_FINISHED,
-              stepName: fallbackStepId,
-              stepId: fallbackStepId,
-              model: model || options.model,
-              timestamp: Date.now(),
-              delta: reasoningDelta,
-              content: accumulatedReasoning,
-            }
-          }
+          yield* emitReasoningDelta(reasoningDelta)
         }
 
         // Handle reasoning summary deltas (when using reasoning.summary option)
-        // response.reasoning_summary_text.delta provides incremental summary updates
         if (
           chunk.type === 'response.reasoning_summary_text.delta' &&
           chunk.delta
         ) {
           const summaryDelta =
             typeof chunk.delta === 'string' ? chunk.delta : ''
-
-          if (summaryDelta) {
-            // Emit STEP_STARTED on first reasoning content
-            if (!hasEmittedStepStarted) {
-              hasEmittedStepStarted = true
-              stepId = generateId(this.name)
-              yield {
-                type: EventType.STEP_STARTED,
-                stepName: stepId,
-                stepId,
-                model: model || options.model,
-                timestamp: Date.now(),
-                stepType: 'thinking',
-              }
-            }
-
-            accumulatedReasoning += summaryDelta
-            hasStreamedReasoningDeltas = true
-            const fallbackStepId = stepId || generateId(this.name)
-            yield {
-              type: EventType.STEP_FINISHED,
-              stepName: fallbackStepId,
-              stepId: fallbackStepId,
-              model: model || options.model,
-              timestamp: Date.now(),
-              delta: summaryDelta,
-              content: accumulatedReasoning,
-            }
-          }
+          yield* emitReasoningDelta(summaryDelta)
         }
 
         // handle content_part added events for text, reasoning and refusals
         if (chunk.type === 'response.content_part.added') {
           const contentPart = chunk.part
-          // Emit TEXT_MESSAGE_START if this is text content
+          // The Responses API can announce a text part with an empty
+          // placeholder before putting the actual text only on the completed
+          // response. An empty placeholder is not streamed content and must
+          // not suppress the completion backstop below.
+          if (
+            (contentPart.type === 'output_text' ||
+              contentPart.type === 'reasoning_text') &&
+            !contentPart.text
+          ) {
+            continue
+          }
+          if (contentPart.type === 'reasoning_text') {
+            yield* emitReasoningDelta(contentPart.text || '')
+            continue
+          }
           if (
             contentPart.type === 'output_text' &&
             !hasEmittedTextMessageStart
           ) {
+            yield* closeReasoning()
             hasEmittedTextMessageStart = true
             yield {
               type: EventType.TEXT_MESSAGE_START,
@@ -1083,27 +1132,12 @@ export abstract class OpenAIBaseResponsesTextAdapter<
               role: 'assistant',
             }
           }
-          // Emit STEP_STARTED if this is reasoning content
-          if (contentPart.type === 'reasoning_text' && !hasEmittedStepStarted) {
-            hasEmittedStepStarted = true
-            stepId = generateId(this.name)
-            yield {
-              type: EventType.STEP_STARTED,
-              stepName: stepId,
-              stepId,
-              model: model || options.model,
-              timestamp: Date.now(),
-              stepType: 'thinking',
-            }
-          }
           // Mark whichever stream we just emitted into so a subsequent
           // `content_part.done` doesn't duplicate the same text. Without
           // this flag, an `added` event carrying the full text followed by
           // a matching `done` event would emit TEXT_MESSAGE_CONTENT twice.
           if (contentPart.type === 'output_text') {
             hasStreamedContentDeltas = true
-          } else if (contentPart.type === 'reasoning_text') {
-            hasStreamedReasoningDeltas = true
           }
           const partChunk = handleContentPart(contentPart)
           yield partChunk
@@ -1140,10 +1174,15 @@ export abstract class OpenAIBaseResponsesTextAdapter<
           // without a start and never see an end. Emit the lifecycle opener
           // for whichever stream this content_part belongs to before yielding
           // the CONTENT chunk; the post-loop block emits the matching END.
+          if (contentPart.type === 'reasoning_text') {
+            yield* emitReasoningDelta(contentPart.text || '')
+            continue
+          }
           if (
             contentPart.type === 'output_text' &&
             !hasEmittedTextMessageStart
           ) {
+            yield* closeReasoning()
             hasEmittedTextMessageStart = true
             yield {
               type: EventType.TEXT_MESSAGE_START,
@@ -1152,20 +1191,6 @@ export abstract class OpenAIBaseResponsesTextAdapter<
               timestamp: Date.now(),
               role: 'assistant',
             }
-          } else if (
-            contentPart.type === 'reasoning_text' &&
-            !hasEmittedStepStarted
-          ) {
-            hasEmittedStepStarted = true
-            stepId = generateId(this.name)
-            yield {
-              type: EventType.STEP_STARTED,
-              stepName: stepId,
-              stepId,
-              model: model || options.model,
-              timestamp: Date.now(),
-              stepType: 'thinking',
-            }
           }
 
           // Only emit if we haven't been streaming deltas (e.g., for non-streaming responses)
@@ -1303,7 +1328,10 @@ export abstract class OpenAIBaseResponsesTextAdapter<
           if (chunk.arguments) {
             try {
               const parsed = JSON.parse(chunk.arguments)
-              parsedInput = parsed && typeof parsed === 'object' ? parsed : {}
+              parsedInput = normalizeToolInput(
+                name,
+                parsed && typeof parsed === 'object' ? parsed : {},
+              )
             } catch (parseError) {
               options.logger.errors(
                 `${this.name}.processStreamChunks tool-args JSON parse failed`,
@@ -1383,8 +1411,10 @@ export abstract class OpenAIBaseResponsesTextAdapter<
               if (rawArgs) {
                 try {
                   const parsed = JSON.parse(rawArgs)
-                  parsedInput =
-                    parsed && typeof parsed === 'object' ? parsed : {}
+                  parsedInput = normalizeToolInput(
+                    name,
+                    parsed && typeof parsed === 'object' ? parsed : {},
+                  )
                 } catch (parseError) {
                   options.logger.errors(
                     `${this.name}.processStreamChunks tool-args JSON parse failed (output_item.done backfill)`,
@@ -1419,6 +1449,40 @@ export abstract class OpenAIBaseResponsesTextAdapter<
         }
 
         if (chunk.type === 'response.completed') {
+          // Some Responses API streams, notably reasoning-model responses,
+          // can omit text deltas and carry the successful final text only in
+          // response.completed.output. Recover that text so consumers never
+          // observe an empty result for a successful response.
+          const completedText = chunk.response.output
+            .flatMap((item) => (item.type === 'message' ? item.content : []))
+            .filter((part) => part.type === 'output_text')
+            .map((part) => part.text)
+            .join('')
+
+          if (accumulatedContent.length === 0 && completedText.length > 0) {
+            if (!hasEmittedTextMessageStart) {
+              hasEmittedTextMessageStart = true
+              yield {
+                type: EventType.TEXT_MESSAGE_START,
+                messageId: aguiState.messageId,
+                model: model || options.model,
+                timestamp: Date.now(),
+                role: 'assistant',
+              }
+            }
+
+            accumulatedContent = completedText
+            hasStreamedContentDeltas = true
+            yield {
+              type: EventType.TEXT_MESSAGE_CONTENT,
+              messageId: aguiState.messageId,
+              model: model || options.model,
+              timestamp: Date.now(),
+              delta: completedText,
+              content: accumulatedContent,
+            }
+          }
+
           // Final backstop for function_call lifecycle: if a function_call
           // appears in `response.output[]` but was never matched by an
           // output_item.added/done with a name, recover the missing START
@@ -1466,8 +1530,10 @@ export abstract class OpenAIBaseResponsesTextAdapter<
               if (rawArgs) {
                 try {
                   const parsed = JSON.parse(rawArgs)
-                  parsedInput =
-                    parsed && typeof parsed === 'object' ? parsed : {}
+                  parsedInput = normalizeToolInput(
+                    name,
+                    parsed && typeof parsed === 'object' ? parsed : {},
+                  )
                 } catch (parseError) {
                   options.logger.errors(
                     `${this.name}.processStreamChunks tool-args JSON parse failed (response.completed backfill)`,
@@ -1500,6 +1566,7 @@ export abstract class OpenAIBaseResponsesTextAdapter<
             }
           }
 
+          yield* closeReasoning()
           // Emit TEXT_MESSAGE_END if we had text content
           if (hasEmittedTextMessageStart) {
             yield {
@@ -1582,6 +1649,7 @@ export abstract class OpenAIBaseResponsesTextAdapter<
       // mirrors the chat-completions adapter's behavior so consumers always
       // see a terminal event for every started run.
       if (!runFinishedEmitted && aguiState.hasEmittedRunStarted) {
+        yield* closeReasoning()
         if (hasEmittedTextMessageStart) {
           yield {
             type: EventType.TEXT_MESSAGE_END,
@@ -1962,9 +2030,9 @@ export abstract class OpenAIBaseResponsesTextAdapter<
    * Handles backward compatibility with string content.
    */
   protected normalizeContent(
-    content: string | null | Array<ContentPart>,
+    content: string | null | undefined | Array<ContentPart>,
   ): Array<ContentPart> {
-    if (content === null) {
+    if (content === null || content === undefined) {
       return []
     }
     if (typeof content === 'string') {
@@ -1977,9 +2045,9 @@ export abstract class OpenAIBaseResponsesTextAdapter<
    * Extracts text content from a content value that may be string, null, or ContentPart array.
    */
   protected extractTextContent(
-    content: string | null | Array<ContentPart>,
+    content: string | null | undefined | Array<ContentPart>,
   ): string {
-    if (content === null) {
+    if (content === null || content === undefined) {
       return ''
     }
     if (typeof content === 'string') {

package/src/adapters/responses-tool-converter.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'vitest'
+import { convertFunctionToolToResponsesFormat } from './responses-tool-converter'
+import type { Tool } from '@tanstack/ai'
+
+describe('responses tool converter', () => {
+  it('falls back from strict mode when an anyOf variant needs null widening', () => {
+    const out = convertFunctionToolToResponsesFormat(anyOfOptionalVariantTool)
+
+    expect(out.strict).toBe(false)
+    expect(out.parameters).toMatchObject({
+      properties: {
+        value: {
+          anyOf: [{ required: ['kind'] }, { required: ['kind', 'note'] }],
+        },
+      },
+    })
+  })
+
+  it('falls back from strict mode for boolean schema nodes', () => {
+    const out = convertFunctionToolToResponsesFormat(booleanSchemaTool)
+
+    expect(out.strict).toBe(false)
+    expect(out.parameters).toEqual(booleanSchemaTool.inputSchema)
+  })
+})
+
+const booleanSchemaInput = {
+  type: 'object',
+  properties: {},
+  required: [],
+}
+Reflect.set(booleanSchemaInput.properties, 'acceptAnything', true)
+
+const booleanSchemaTool = {
+  name: 'accept_anything',
+  description: 'Accept any value',
+  inputSchema: booleanSchemaInput,
+} satisfies Tool
+
+const anyOfOptionalVariantTool: Tool = {
+  name: 'store_variant',
+  description: 'Store a union variant',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      value: {
+        anyOf: [
+          {
+            type: 'object',
+            properties: {
+              kind: { const: 'optional' },
+              note: { type: 'string' },
+            },
+            required: ['kind'],
+          },
+          {
+            type: 'object',
+            properties: {
+              kind: { const: 'nullable' },
+              note: { type: ['string', 'null'] },
+            },
+            required: ['kind', 'note'],
+          },
+        ],
+      },
+    },
+    required: ['value'],
+  },
+}

package/src/index.ts

@@ -1,4 +1,7 @@
-export { makeStructuredOutputCompatible } from './utils/schema-converter'
+export {
+  makeStructuredOutputCompatible,
+  makeStructuredOutputCompatibleWithMap,
+} from './utils/schema-converter'
 export {
   buildChatCompletionsUsage,
   buildResponsesUsage,

package/src/tools/function-tool.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it } from 'vitest'
+import { convertFunctionToolToAdapterFormat } from './function-tool'
+import type { Tool } from '@tanstack/ai'
+
+describe('function-tool adapter converter', () => {
+  it('falls back from strict mode when an anyOf variant needs null widening', () => {
+    const out = convertFunctionToolToAdapterFormat(anyOfOptionalVariantTool)
+
+    expect(out.strict).toBe(false)
+  })
+
+  it('falls back from strict mode for boolean schema nodes', () => {
+    const out = convertFunctionToolToAdapterFormat(booleanSchemaTool)
+
+    expect(out.strict).toBe(false)
+    expect(out.parameters).toEqual(booleanSchemaTool.inputSchema)
+  })
+})
+
+const booleanSchemaInput = {
+  type: 'object',
+  properties: {},
+  required: [],
+}
+Reflect.set(booleanSchemaInput.properties, 'acceptAnything', true)
+
+const booleanSchemaTool = {
+  name: 'accept_anything',
+  description: 'Accept any value',
+  inputSchema: booleanSchemaInput,
+} satisfies Tool
+
+const anyOfOptionalVariantTool: Tool = {
+  name: 'store_variant',
+  description: 'Store a union variant',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      value: {
+        anyOf: [
+          {
+            type: 'object',
+            properties: {
+              kind: { const: 'optional' },
+              note: { type: 'string' },
+            },
+            required: ['kind'],
+          },
+          {
+            type: 'object',
+            properties: {
+              kind: { const: 'nullable' },
+              note: { type: ['string', 'null'] },
+            },
+            required: ['kind', 'note'],
+          },
+        ],
+      },
+    },
+    required: ['value'],
+  },
+}