@tanstack/openai-base 0.10.1 → 0.10.2

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