@tanstack/openai-base 0.10.0 → 0.10.2

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

package/src/utils/tool-input-normalizer.test.ts

@@ -0,0 +1,146 @@
+import { describe, expect, it } from 'vitest'
+import { createToolInputNormalizer } from './tool-input-normalizer'
+import type { Tool } from '@tanstack/ai'
+
+describe('createToolInputNormalizer', () => {
+  it('removes a null synthesized for an optional enum', () => {
+    const tool: Tool = {
+      name: 'optional_enum',
+      description: 'Uses an optional literal value',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          value: { type: 'string', enum: ['canary'] },
+        },
+        required: [],
+      },
+    }
+    const normalize = createToolInputNormalizer([tool])
+
+    expect(normalize(tool.name, { value: null })).toEqual({})
+  })
+
+  it('leaves non-strict tool inputs unchanged', () => {
+    const tool: Tool = {
+      name: 'non_strict',
+      description: 'Uses a schema outside the strict subset',
+      inputSchema: {
+        type: 'object',
+        properties: { optional: { type: 'string' } },
+        oneOf: [{ required: ['optional'] }, { required: [] }],
+      },
+    }
+    const normalize = createToolInputNormalizer([tool])
+    const input = { optional: null }
+
+    expect(normalize(tool.name, input)).toBe(input)
+  })
+
+  it('does not guess when public tool names are ambiguous', () => {
+    const tools: Array<Tool> = [
+      {
+        name: 'duplicate',
+        description: 'First tool',
+        inputSchema: {
+          type: 'object',
+          properties: { firstOptional: { type: 'string' } },
+        },
+      },
+      {
+        name: 'duplicate',
+        description: 'Second tool',
+        inputSchema: {
+          type: 'object',
+          properties: { secondOptional: { type: 'string' } },
+        },
+      },
+    ]
+    const normalize = createToolInputNormalizer(tools)
+    const input = { firstOptional: null, secondOptional: null }
+
+    expect(normalize('duplicate', input)).toBe(input)
+  })
+
+  it('leaves anyOf inputs unchanged when variant widening is ambiguous', () => {
+    const tool: Tool = {
+      name: 'union',
+      description: 'Uses variant-specific nullability',
+      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'],
+      },
+    }
+    const normalize = createToolInputNormalizer([tool])
+    const input = { value: { kind: 'nullable', note: null } }
+
+    expect(normalize(tool.name, input)).toBe(input)
+  })
+
+  it.each([
+    ['const', { anyOf: [{ type: 'string' }, { const: null }] }],
+    ['enum', { anyOf: [{ type: 'string' }, { enum: [null] }] }],
+  ])('preserves genuine null accepted by an anyOf %s branch', (_, value) => {
+    const tool: Tool = {
+      name: 'nullable_union',
+      description: 'Uses an optional union that genuinely accepts null',
+      inputSchema: {
+        type: 'object',
+        properties: { value },
+        required: [],
+      },
+    }
+    const normalize = createToolInputNormalizer([tool])
+    const input = { value: null }
+
+    expect(normalize(tool.name, input)).toBe(input)
+  })
+
+  it('builds the inverse map from the supplied converter', () => {
+    const tool: Tool = {
+      name: 'ask',
+      description: 'Ask',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          note: { type: 'string' },
+        },
+        required: ['note'],
+      },
+    }
+
+    const defaultNormalize = createToolInputNormalizer([tool])
+    expect(defaultNormalize(tool.name, { note: null })).toEqual({ note: null })
+
+    const normalize = createToolInputNormalizer([tool], () => ({
+      schema: {
+        type: 'object',
+        properties: { note: { type: ['string', 'null'] } },
+        required: ['note'],
+      },
+      nullWideningMap: { properties: { note: { widened: true } } },
+    }))
+    expect(normalize(tool.name, { note: null })).toEqual({})
+  })
+})

package/src/utils/tool-input-normalizer.ts

@@ -0,0 +1,55 @@
+import { undoNullWidening } from '@tanstack/ai-utils'
+import {
+  isStrictModeCompatible,
+  makeStructuredOutputCompatibleWithMap,
+} from './schema-converter'
+import type { JSONSchema, Tool } from '@tanstack/ai'
+import type { NullWideningMap } from '@tanstack/ai-utils'
+import type { StructuredOutputCompatibility } from './schema-converter'
+
+type ToolInputNormalizer = (toolName: string, input: unknown) => unknown
+
+type SchemaConverterWithMap = (
+  schema: Record<string, any>,
+  originalRequired?: Array<string>,
+) => StructuredOutputCompatibility
+
+/**
+ * Build the inverse transform for the strict tool schemas sent in one request.
+ * Pass the same converter the request used so subclass schema tweaks stay
+ * aligned with undo. Non-strict tools are excluded because they were not
+ * null-widened on the wire.
+ */
+export function createToolInputNormalizer(
+  tools: Array<Tool> | undefined,
+  convertSchema: SchemaConverterWithMap = makeStructuredOutputCompatibleWithMap,
+): ToolInputNormalizer {
+  const maps = new Map<string, NullWideningMap>()
+  const seenNames = new Set<string>()
+  const ambiguousNames = new Set<string>()
+
+  for (const tool of tools ?? []) {
+    if (ambiguousNames.has(tool.name)) continue
+    if (seenNames.has(tool.name)) {
+      maps.delete(tool.name)
+      ambiguousNames.add(tool.name)
+      continue
+    }
+    seenNames.add(tool.name)
+
+    const inputSchema = (tool.inputSchema ?? {
+      type: 'object',
+      properties: {},
+      required: [],
+    }) as JSONSchema
+    if (!isStrictModeCompatible(inputSchema)) continue
+
+    const { nullWideningMap } = convertSchema(
+      inputSchema,
+      inputSchema.required || [],
+    )
+    if (nullWideningMap) maps.set(tool.name, nullWideningMap)
+  }
+
+  return (toolName, input) => undoNullWidening(input, maps.get(toolName))
+}