@tanstack/openai-base 0.10.1 → 0.10.2

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

package/src/utils/schema-converter.ts

@@ -1,3 +1,5 @@
+import type { NullWideningMap } from '@tanstack/ai-utils'
+
 /**
  * String `format` values accepted by OpenAI's strict Structured Outputs subset.
  * Any other format (e.g. "uri", "uri-reference", "regex") causes the API to
@@ -61,7 +63,35 @@ export function makeStructuredOutputCompatible(
   schema: Record<string, any>,
   originalRequired?: Array<string>,
 ): Record<string, any> {
-  return stripUnsupportedFormats(coerceStrictSchema(schema, originalRequired))
+  return makeStructuredOutputCompatibleWithMap(schema, originalRequired).schema
+}
+
+export interface StructuredOutputCompatibility {
+  schema: Record<string, any>
+  nullWideningMap: NullWideningMap | undefined
+}
+
+interface CoercedStrictSchema extends StructuredOutputCompatibility {
+  hasUntrackableAnyOfWidening: boolean
+}
+
+/**
+ * Strict-schema conversion plus an exact map of the nullability introduced by
+ * that conversion. Consumers can pass provider output through
+ * `undoNullWidening` before validating it against the original schema.
+ */
+export function makeStructuredOutputCompatibleWithMap(
+  schema: Record<string, any>,
+  originalRequired?: Array<string>,
+): StructuredOutputCompatibility {
+  const { schema: strictSchema, nullWideningMap } = coerceStrictSchema(
+    schema,
+    originalRequired,
+  )
+  return {
+    schema: stripUnsupportedFormats(strictSchema),
+    nullWideningMap,
+  }
 }
 
 /**
@@ -118,6 +148,9 @@ const TYPE_INDICATOR_KEYWORDS: ReadonlyArray<string> = [
  * 3. It contains an open object schema. OpenAI strict mode requires objects to
  *    set `additionalProperties: false`, which would change the semantics of a
  *    free-form map rather than merely normalizing it.
+ * 4. An `anyOf` variant itself needs null widening. The inverse map is
+ *    intentionally schema-blind, so it cannot select a variant without risking
+ *    removal of a genuine nullable value accepted by another variant.
  *
  * Conservative by design: for (1) keywords are matched as object keys, so a
  * property literally named e.g. `oneOf` also trips it. That only costs that one
@@ -128,10 +161,24 @@ export function isStrictModeCompatible(schema: unknown): boolean {
   return (
     !containsStrictUnsupportedKeyword(schema) &&
     !containsTypelessSchema(schema) &&
-    !containsOpenObject(schema)
+    !containsOpenObject(schema) &&
+    !containsUntrackableAnyOfWidening(schema)
   )
 }
 
+/**
+ * Reports strict conversions whose synthesized nulls cannot be represented by
+ * the schema-blind inverse map. Optional `anyOf` wrappers remain supported:
+ * only widening introduced inside one of their variants triggers fallback.
+ */
+function containsUntrackableAnyOfWidening(schema: unknown): boolean {
+  if (schema === null || typeof schema !== 'object' || Array.isArray(schema)) {
+    return false
+  }
+  return coerceStrictSchema(schema as Record<string, any>)
+    .hasUntrackableAnyOfWidening
+}
+
 /**
  * Reports object schemas that cannot be closed without changing their input
  * semantics. Objects with `properties` and no explicit
@@ -184,8 +231,10 @@ function containsStrictUnsupportedKeyword(node: unknown): boolean {
 /** A schema-position node that declares no type and so 400s strict mode. */
 function isTypelessSchema(node: unknown): boolean {
   if (node === null || typeof node !== 'object' || Array.isArray(node)) {
-    // boolean schemas (`true`/`false`) and non-objects aren't typeless props.
-    return false
+    // JSON Schema permits bare boolean nodes; malformed inputs may contain
+    // other primitives. OpenAI's strict subset requires a declared type, so
+    // preserve the containing tool by sending it in non-strict mode.
+    return true
   }
   return !TYPE_INDICATOR_KEYWORDS.some((key) => key in node)
 }
@@ -225,11 +274,42 @@ function containsTypelessSchema(node: unknown): boolean {
  * additionalProperties). Kept private so the public entry point can apply the
  * format-stripping pass exactly once over the fully-rewritten tree.
  */
+function pruneMap(map: NullWideningMap): NullWideningMap | undefined {
+  return Object.keys(map).length > 0 ? map : undefined
+}
+
+function isSchemaObject(schema: unknown): schema is Record<string, any> {
+  return typeof schema === 'object' && schema !== null && !Array.isArray(schema)
+}
+
+/** Whether every active JSON Schema constraint at this node admits null. */
+function acceptsNull(schema: unknown): boolean {
+  if (schema === true) return true
+  if (!isSchemaObject(schema)) return false
+
+  if ('const' in schema && schema.const !== null) return false
+  if (Array.isArray(schema.enum) && !schema.enum.includes(null)) return false
+
+  if (typeof schema.type === 'string' && schema.type !== 'null') return false
+  if (Array.isArray(schema.type) && !schema.type.includes('null')) return false
+
+  if (
+    Array.isArray(schema.anyOf) &&
+    !schema.anyOf.some((variant: unknown) => acceptsNull(variant))
+  ) {
+    return false
+  }
+
+  return true
+}
+
 function coerceStrictSchema(
   schema: Record<string, any>,
   originalRequired?: Array<string>,
-): Record<string, any> {
+): CoercedStrictSchema {
   const result = { ...schema }
+  const nullWideningMap: NullWideningMap = {}
+  let hasUntrackableAnyOfWidening = false
   const required =
     originalRequired ??
     (Array.isArray(result['required']) ? result['required'] : [])
@@ -237,22 +317,36 @@ function coerceStrictSchema(
   if (result.type === 'object' && result.properties) {
     const properties = { ...result.properties }
     const allPropertyNames = Object.keys(properties)
+    const propertyMaps: Record<string, NullWideningMap> = {}
 
     for (const propName of allPropertyNames) {
       let prop = properties[propName]
       const wasOptional = !required.includes(propName)
+      let childMap: NullWideningMap | undefined
+      let widenedHere = false
 
       // Step 1: Recurse into nested structures
-      if (prop.type === 'object' && prop.properties) {
-        prop = coerceStrictSchema(prop, prop.required || [])
-      } else if (prop.type === 'array' && prop.items) {
+      if (isSchemaObject(prop) && prop.type === 'object' && prop.properties) {
+        const nested = coerceStrictSchema(prop, prop.required || [])
+        prop = nested.schema
+        childMap = nested.nullWideningMap
+        hasUntrackableAnyOfWidening ||= nested.hasUntrackableAnyOfWidening
+      } else if (isSchemaObject(prop) && prop.type === 'array' && prop.items) {
+        const nested = coerceStrictSchema(prop.items, prop.items.required || [])
         prop = {
           ...prop,
-          items: coerceStrictSchema(prop.items, prop.items.required || []),
+          items: nested.schema,
         }
-      } else if (prop.anyOf) {
-        prop = coerceStrictSchema(prop, prop.required || [])
-      } else if (prop.oneOf) {
+        childMap = nested.nullWideningMap
+          ? { items: nested.nullWideningMap }
+          : undefined
+        hasUntrackableAnyOfWidening ||= nested.hasUntrackableAnyOfWidening
+      } else if (isSchemaObject(prop) && prop.anyOf) {
+        const nested = coerceStrictSchema(prop, prop.required || [])
+        prop = nested.schema
+        childMap = nested.nullWideningMap
+        hasUntrackableAnyOfWidening ||= nested.hasUntrackableAnyOfWidening
+      } else if (isSchemaObject(prop) && prop.oneOf) {
         throw new Error(
           'oneOf is not supported in OpenAI structured output schemas. Check the supported outputs here: https://platform.openai.com/docs/guides/structured-outputs#supported-types',
         )
@@ -260,34 +354,81 @@ function coerceStrictSchema(
 
       // Step 2: Apply null-widening for optional properties (after recursion)
       if (wasOptional) {
-        if (prop.anyOf) {
-          // For anyOf, add a null variant if not already present
-          if (!prop.anyOf.some((v: any) => v.type === 'null')) {
+        const originallyAcceptedNull = acceptsNull(prop)
+
+        // `type: [..., 'null']` alone does not make null valid when an enum or
+        // const still excludes it; strict decoding would be forced to emit the
+        // original literal instead of the synthetic omission marker.
+        if (isSchemaObject(prop) && 'const' in prop && prop.const !== null) {
+          const { const: constValue, ...withoutConst } = prop
+          prop = { ...withoutConst, enum: [constValue, null] }
+        } else if (
+          isSchemaObject(prop) &&
+          Array.isArray(prop.enum) &&
+          !prop.enum.includes(null)
+        ) {
+          prop = { ...prop, enum: [...prop.enum, null] }
+        }
+
+        if (isSchemaObject(prop) && prop.anyOf) {
+          // A genuine null branch can use type, enum, or const. Only add a
+          // provider omission marker when the original union rejected null.
+          if (!acceptsNull(prop)) {
             prop = { ...prop, anyOf: [...prop.anyOf, { type: 'null' }] }
           }
-        } else if (prop.type && !Array.isArray(prop.type)) {
+        } else if (
+          isSchemaObject(prop) &&
+          prop.type &&
+          !Array.isArray(prop.type)
+        ) {
           prop = { ...prop, type: [prop.type, 'null'] }
-        } else if (Array.isArray(prop.type) && !prop.type.includes('null')) {
+        } else if (
+          isSchemaObject(prop) &&
+          Array.isArray(prop.type) &&
+          !prop.type.includes('null')
+        ) {
           prop = { ...prop, type: [...prop.type, 'null'] }
         }
+
+        widenedHere = !originallyAcceptedNull && acceptsNull(prop)
       }
 
       properties[propName] = prop
+      if (childMap || widenedHere) {
+        propertyMaps[propName] = {
+          ...(childMap ?? {}),
+          ...(widenedHere ? { widened: true } : {}),
+        }
+      }
     }
 
     result.properties = properties
     result.required = allPropertyNames
     result.additionalProperties = false
+    if (Object.keys(propertyMaps).length > 0) {
+      nullWideningMap.properties = propertyMaps
+    }
   }
 
   if (result.type === 'array' && result.items) {
-    result.items = coerceStrictSchema(result.items, result.items.required || [])
+    const nested = coerceStrictSchema(result.items, result.items.required || [])
+    result.items = nested.schema
+    if (nested.nullWideningMap) {
+      nullWideningMap.items = nested.nullWideningMap
+    }
+    hasUntrackableAnyOfWidening ||= nested.hasUntrackableAnyOfWidening
   }
 
   if (result.anyOf && Array.isArray(result.anyOf)) {
-    result.anyOf = result.anyOf.map((variant) =>
+    const variants = result.anyOf.map((variant) =>
       coerceStrictSchema(variant, variant.required || []),
     )
+    result.anyOf = variants.map((variant) => variant.schema)
+    hasUntrackableAnyOfWidening ||= variants.some(
+      (variant) =>
+        variant.nullWideningMap !== undefined ||
+        variant.hasUntrackableAnyOfWidening,
+    )
   }
 
   if (result.oneOf) {
@@ -296,5 +437,9 @@ function coerceStrictSchema(
     )
   }
 
-  return result
+  return {
+    schema: result,
+    nullWideningMap: pruneMap(nullWideningMap),
+    hasUntrackableAnyOfWidening,
+  }
 }