@tanstack/openai-base 0.10.0 → 0.10.2

package/src/adapters/chat-completions-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 { buildChatCompletionsUsage } from '../usage'
 import { convertToolsToChatCompletionsFormat } from './chat-completions-tool-converter'
 import type OpenAI from 'openai'
@@ -30,6 +32,13 @@ import type {
   TextOptions,
 } from '@tanstack/ai'
 
+type ChatStreamState = {
+  runId: string
+  threadId: string
+  messageId: string
+  hasEmittedRunStarted: boolean
+}
+
 /**
  * Shared implementation of the OpenAI Chat Completions API. Holds the
  * stream-accumulator + AG-UI lifecycle logic and calls the OpenAI SDK
@@ -94,98 +103,99 @@ export abstract class OpenAIBaseChatCompletionsTextAdapter<
 
       yield* this.processStreamChunks(stream, options, aguiState)
     } catch (error: unknown) {
-      // Narrow before logging: raw SDK errors can carry request metadata
-      // (including auth headers) which we must never surface to user loggers.
-      const errorPayload = toRunErrorPayload(
-        error,
-        `${this.name}.chatStream failed`,
-      )
-      const rawEvent = toRunErrorRawEvent(error)
+      yield* this.handleChatStreamError(error, options, aguiState, 'chatStream')
+    }
+  }
 
-      // Emit RUN_STARTED if not yet emitted
-      if (!aguiState.hasEmittedRunStarted) {
-        aguiState.hasEmittedRunStarted = true
-        yield {
-          type: EventType.RUN_STARTED,
-          runId: aguiState.runId,
-          threadId: aguiState.threadId,
-          model: options.model,
-          timestamp: Date.now(),
-          parentRunId: options.parentRunId,
-        }
-      }
+  private async *handleChatStreamError(
+    error: unknown,
+    options: TextOptions,
+    aguiState: ChatStreamState,
+    source: 'chatStream' | 'processStreamChunks',
+  ): AsyncIterable<StreamChunk> {
+    // Narrow before logging: raw SDK errors can carry request metadata
+    // (including auth headers) which we must never surface to user loggers.
+    const errorPayload = toRunErrorPayload(
+      error,
+      `${this.name}.${source} failed`,
+    )
+    const rawEvent = toRunErrorRawEvent(error)
 
-      const rejectedToolCall = this.extractRejectedToolCall(
-        rawEvent,
-        errorPayload.message,
-      )
-      if (rejectedToolCall) {
-        const toolCallId = generateId(this.name)
-        yield {
-          type: EventType.TOOL_CALL_START,
-          toolCallId,
-          toolCallName: rejectedToolCall.toolName,
-          toolName: rejectedToolCall.toolName,
-          parentMessageId: aguiState.messageId,
-          model: options.model,
-          timestamp: Date.now(),
-        }
-        yield {
-          type: EventType.TOOL_CALL_ARGS,
-          toolCallId,
-          delta: rejectedToolCall.arguments,
-          args: rejectedToolCall.arguments,
-          model: options.model,
-          timestamp: Date.now(),
-        }
-        yield {
-          type: EventType.TOOL_CALL_END,
-          toolCallId,
-          toolCallName: rejectedToolCall.toolName,
-          toolName: rejectedToolCall.toolName,
-          ...(rejectedToolCall.input !== undefined && {
-            input: rejectedToolCall.input,
-          }),
-          result: JSON.stringify({ error: rejectedToolCall.error }),
-          state: 'output-error',
-          model: options.model,
-          timestamp: Date.now(),
-        }
-        yield {
-          type: EventType.RUN_FINISHED,
-          runId: aguiState.runId,
-          threadId: aguiState.threadId,
-          model: options.model,
-          timestamp: Date.now(),
-          finishReason: 'tool_calls',
-        }
-        return
+    if (!aguiState.hasEmittedRunStarted) {
+      aguiState.hasEmittedRunStarted = true
+      yield {
+        type: EventType.RUN_STARTED,
+        runId: aguiState.runId,
+        threadId: aguiState.threadId,
+        model: options.model,
+        timestamp: Date.now(),
+        parentRunId: options.parentRunId,
       }
+    }
 
-      // Emit AG-UI RUN_ERROR. Conditional `code` spread keeps the wire
-      // shape spec-compliant under `exactOptionalPropertyTypes`: AG-UI's
-      // `RunErrorEvent.code` is `string?` (absent vs explicit `undefined`
-      // matter), so we omit the key when there's no code.
+    const rejectedToolCall = this.extractRejectedToolCall(
+      rawEvent,
+      errorPayload.message,
+    )
+    if (rejectedToolCall) {
+      const toolCallId = generateId(this.name)
       yield {
-        type: EventType.RUN_ERROR,
+        type: EventType.TOOL_CALL_START,
+        toolCallId,
+        toolCallName: rejectedToolCall.toolName,
+        toolName: rejectedToolCall.toolName,
+        parentMessageId: aguiState.messageId,
         model: options.model,
         timestamp: Date.now(),
-        message: errorPayload.message,
-        code: errorPayload.code,
-        // Forward the provider's structured error body so consumers can recover
-        // the upstream detail the `{ message, code }` payload drops. Omitted
-        // when the error carried no provider body (see toRunErrorRawEvent).
-        ...(rawEvent !== undefined && { rawEvent }),
-        error: {
-          message: errorPayload.message,
-          code: errorPayload.code,
-        },
       }
+      yield {
+        type: EventType.TOOL_CALL_ARGS,
+        toolCallId,
+        delta: rejectedToolCall.arguments,
+        args: rejectedToolCall.arguments,
+        model: options.model,
+        timestamp: Date.now(),
+      }
+      yield {
+        type: EventType.TOOL_CALL_END,
+        toolCallId,
+        toolCallName: rejectedToolCall.toolName,
+        toolName: rejectedToolCall.toolName,
+        ...(rejectedToolCall.input !== undefined && {
+          input: rejectedToolCall.input,
+        }),
+        result: JSON.stringify({ error: rejectedToolCall.error }),
+        state: 'output-error',
+        model: options.model,
+        timestamp: Date.now(),
+      }
+      yield {
+        type: EventType.RUN_FINISHED,
+        runId: aguiState.runId,
+        threadId: aguiState.threadId,
+        model: options.model,
+        timestamp: Date.now(),
+        finishReason: 'tool_calls',
+      }
+      return
+    }
 
-      options.logger.errors(`${this.name}.chatStream fatal`, {
-        error: errorPayload,
-        source: `${this.name}.chatStream`,
-      })
+    options.logger.errors(`${this.name}.${source} fatal`, {
+      error: errorPayload,
+      source: `${this.name}.${source}`,
+    })
+
+    yield {
+      type: EventType.RUN_ERROR,
+      model: options.model,
+      timestamp: Date.now(),
+      message: errorPayload.message,
+      ...(errorPayload.code !== undefined && { code: errorPayload.code }),
+      ...(rawEvent !== undefined && { rawEvent }),
+      error: {
+        message: errorPayload.message,
+        ...(errorPayload.code !== undefined && { code: errorPayload.code }),
+      },
     }
   }
 
@@ -636,15 +646,29 @@ export abstract class OpenAIBaseChatCompletionsTextAdapter<
     )
   }
 
+  /**
+   * 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
   }
 
   /**
@@ -680,13 +704,13 @@ export abstract class OpenAIBaseChatCompletionsTextAdapter<
   protected async *processStreamChunks(
     stream: AsyncIterable<ChatCompletionChunk>,
     options: TextOptions,
-    aguiState: {
-      runId: string
-      threadId: string
-      messageId: string
-      hasEmittedRunStarted: boolean
-    },
+    aguiState: ChatStreamState,
   ): AsyncIterable<StreamChunk> {
+    const normalizeToolInput = createToolInputNormalizer(
+      options.tools,
+      (schema, required) =>
+        this.makeStructuredOutputCompatibleWithMap(schema, required),
+    )
     let accumulatedContent = ''
     let hasEmittedTextMessageStart = false
     let lastModel: string | undefined
@@ -955,8 +979,10 @@ export abstract class OpenAIBaseChatCompletionsTextAdapter<
               if (toolCall.arguments) {
                 try {
                   const parsed: unknown = JSON.parse(toolCall.arguments)
-                  parsedInput =
-                    parsed && typeof parsed === 'object' ? parsed : {}
+                  parsedInput = normalizeToolInput(
+                    toolCall.name,
+                    parsed && typeof parsed === 'object' ? parsed : {},
+                  )
                 } catch (parseError) {
                   options.logger.errors(
                     `${this.name}.processStreamChunks tool-args JSON parse failed`,
@@ -1027,7 +1053,10 @@ export abstract class OpenAIBaseChatCompletionsTextAdapter<
           if (toolCall.arguments) {
             try {
               const parsed: unknown = JSON.parse(toolCall.arguments)
-              parsedInput = parsed && typeof parsed === 'object' ? parsed : {}
+              parsedInput = normalizeToolInput(
+                toolCall.name,
+                parsed && typeof parsed === 'object' ? parsed : {},
+              )
             } catch (parseError) {
               // Mirror the finish_reason path's logger call — a truncated
               // stream emitting malformed tool-call JSON would otherwise
@@ -1136,33 +1165,12 @@ export abstract class OpenAIBaseChatCompletionsTextAdapter<
         }
       }
     } catch (error: unknown) {
-      // Narrow before logging: raw SDK errors can carry request metadata
-      // (including auth headers) which we must never surface to user loggers.
-      const errorPayload = toRunErrorPayload(
+      yield* this.handleChatStreamError(
         error,
-        `${this.name}.processStreamChunks failed`,
+        options,
+        aguiState,
+        'processStreamChunks',
       )
-      const rawEvent = toRunErrorRawEvent(error)
-      options.logger.errors(`${this.name}.processStreamChunks fatal`, {
-        error: errorPayload,
-        source: `${this.name}.processStreamChunks`,
-      })
-
-      // Emit AG-UI RUN_ERROR with conditional `code` spread (see chatStream's
-      // catch block for the rationale). `rawEvent` carries the provider's
-      // structured error body when present.
-      yield {
-        type: EventType.RUN_ERROR,
-        model: options.model,
-        timestamp: Date.now(),
-        message: errorPayload.message,
-        ...(errorPayload.code !== undefined && { code: errorPayload.code }),
-        ...(rawEvent !== undefined && { rawEvent }),
-        error: {
-          message: errorPayload.message,
-          ...(errorPayload.code !== undefined && { code: errorPayload.code }),
-        },
-      }
     }
   }
 

package/src/adapters/chat-completions-tool-converter.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from 'vitest'
+import { convertFunctionToolToChatCompletionsFormat } from './chat-completions-tool-converter'
+import type { Tool } from '@tanstack/ai'
+
+describe('chat-completions tool converter', () => {
+  it('falls back from strict mode when an anyOf variant needs null widening', () => {
+    const out = convertFunctionToolToChatCompletionsFormat(
+      anyOfOptionalVariantTool,
+    )
+
+    expect(out.function.strict).toBe(false)
+  })
+
+  it('falls back from strict mode for boolean schema nodes', () => {
+    const out = convertFunctionToolToChatCompletionsFormat(booleanSchemaTool)
+
+    expect(out.function.strict).toBe(false)
+    expect(out.function.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/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'
@@ -674,15 +676,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
   }
 
   /**
@@ -783,6 +799,11 @@ export abstract class OpenAIBaseResponsesTextAdapter<
       hasEmittedRunStarted: boolean
     },
   ): AsyncIterable<StreamChunk> {
+    const normalizeToolInput = createToolInputNormalizer(
+      options.tools,
+      (schema, required) =>
+        this.makeStructuredOutputCompatibleWithMap(schema, required),
+    )
     let accumulatedContent = ''
     let accumulatedReasoning = ''
 
@@ -1069,6 +1090,17 @@ export abstract class OpenAIBaseResponsesTextAdapter<
         // handle content_part added events for text, reasoning and refusals
         if (chunk.type === 'response.content_part.added') {
           const contentPart = chunk.part
+          // 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
+          }
           // Emit TEXT_MESSAGE_START if this is text content
           if (
             contentPart.type === 'output_text' &&
@@ -1303,7 +1335,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 +1418,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 +1456,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 +1537,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)`,

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'],
+  },
+}