fix: undo strict null widening for tool inputs #939
main fromrefs/pull/939/head·merged by AlemTuzlak View on GitHubOpenAI-compatible strict tools promote optional fields to required nullable fields. The model can then send null for an omitted optional. TanStack AI used to validate that null against the original schema, so .optional() failed and the tool did not run.
This PR records which nulls the converter added, then removes only those nulls before the tool runs. A genuine .nullable() null stays.
Changes#
- Record a
NullWideningMapduring the same OpenAI strict-schema conversion that adds nullability. - Remove only provider-synthesized nulls before emitting completed tool input.
- Apply that undo on Chat Completions and Responses, including drain and backfill paths.
- Skip non-strict tools and duplicate tool names.
- Use the same converter for the inverse map as the wire schema, including Groq's override.
- Adapter tests assert the exact tool input with
toEqual. - Tools docs state the optional vs nullable contract.
Checklist#
- I have followed the steps in the Contributing guide.
- I have tested this code locally with
pnpm run test:pr. - Docs: I updated
docs/for this change, or this change is not user-facing. - Changeset: I added a changeset (
pnpm changeset), or this PR does not change a published package.
Release Impact#
- This change affects published code, and I have generated a changeset.
- This change is docs/CI/dev-only (no release).
Testing#
Commands run on the review follow-up:
pnpm --filter @tanstack/openai-base test:lib— 203 passedpnpm --filter @tanstack/ai-groq test:lib— 36 passedpnpm --filter @tanstack/openai-base test:typesandpnpm --filter @tanstack/ai-groq test:types— passedpnpm --filter @tanstack/openai-base test:oxlintandpnpm --filter @tanstack/ai-groq test:oxlint— passed (existinganywarnings only)
I did not re-run pnpm test:pr or the e2e spec after the follow-up commit.
Manual test:
- Define a strict OpenAI-compatible tool with
.optional()and.nullable()fields. - Call it so the model omits the optional field (wire value
null) and sets the nullable field tonull. - Confirm the tool handler receives the optional field as absent and the nullable field as
null. - Confirm the tool executes and the next model turn runs.
How this PR makes testing easy: adapter unit tests, a normalizer unit test for a custom converter, and testing/e2e/tests/openai-strict-tool-null-wire.spec.ts.
Risk / rollback#
Low. If a subclass converter and the inverse map still disagree, an optional null can fail schema validation again. Revert the PR to undo.
Public API change#
Tool authors do not change call sites. Optional vs nullable input now matches the schema:
inputSchema: z.object({
mode: z.enum(["canary"]).optional(),
nullableNote: z.string().nullable(),
})
Adapter authors who change strict conversion should override makeStructuredOutputCompatibleWithMap so the inverse map matches the wire schema. @tanstack/openai-base also exports makeStructuredOutputCompatibleWithMap.
- 1
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. Inline comments: In `@packages/openai-base/src/utils/schema-converter.ts`: - Around line 293-296: Preserve and merge the nullWideningMap returned by coerceStrictSchema for each supported anyOf variant instead of retaining only nested.schema. Update both anyOf handling sites near the prop conversion logic so variant-specific metadata remains associated without marking unrelated genuinely nullable fields, and add a regression test for an optional nested property inside anyOf that verifies provider-added nulls are removed during original-schema validation.🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID:
67373ee5-ff74-40a3-8e8b-9b825e20f5be📥 Commits
Reviewing files that changed from the base of the PR and between fbfd4be3dda591303725664a802e0efbced0d22b and 0eeb0267093ee279d2d38726f936f4e27dfa430d.
📒 Files selected for processing (12)
.changeset/calm-tools-return.mdpackages/openai-base/src/adapters/chat-completions-text.tspackages/openai-base/src/adapters/responses-text.tspackages/openai-base/src/utils/schema-converter.tspackages/openai-base/src/utils/tool-input-normalizer.tspackages/openai-base/tests/chat-completions-text.test.tspackages/openai-base/tests/responses-text.test.tspackages/openai-base/tests/schema-converter.test.tspackages/openai-base/tests/tool-input-normalizer.test.tstesting/e2e/src/routeTree.gen.tstesting/e2e/src/routes/api.openai-strict-tool-null-wire.tstesting/e2e/tests/openai-strict-tool-null-wire.spec.ts
@@ -245,10 +279,18 @@245279 // Step 1: Recurse into nested structures246280 if (prop.type === 'object' && prop.properties) {247- prop = coerceStrictSchema(prop, prop.required || [])281+ const nested = coerceStrictSchema(prop, prop.required || [])282+ prop = nested.schema283+ childMap = nested.nullWideningMap248284 } else if (prop.type === 'array' && prop.items) {285+ const nested = coerceStrictSchema(prop.items, prop.items.required || [])249286 prop = {250287 ...prop,251- items: coerceStrictSchema(prop.items, prop.items.required || []),288+ items: nested.schema,252289 }290+ childMap = nested.nullWideningMap291+ ? { items: nested.nullWideningMap }292+ : undefined253293 } else if (prop.anyOf) {254- prop = coerceStrictSchema(prop, prop.required || [])294+ const nested = coerceStrictSchema(prop, prop.required || [])295+ prop = nested.schema296+ childMap = nested.nullWideningMap🎯 Functional Correctness | 🟠 Major | 🏗️ Heavy lift
Preserve null-widening metadata from
anyOfvariants.These calls retain only
.schema, discarding variantnullWideningMapvalues. Optional fields nested inside a supportedanyOfare therefore widened tonull, but their provider-synthesized nulls cannot be removed before original-schema validation.The map representation must retain variant-specific metadata without conflating genuine nullable fields in another variant. Add a regression test covering an optional nested property inside
anyOf.Also applies to: 345-348
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/openai-base/src/utils/schema-converter.ts` around lines 293 - 296, Preserve and merge the nullWideningMap returned by coerceStrictSchema for each supported anyOf variant instead of retaining only nested.schema. Update both anyOf handling sites near the prop conversion logic so variant-specific metadata remains associated without marking unrelated genuinely nullable fields, and add a regression test for an optional nested property inside anyOf that verifies provider-added nulls are removed during original-schema validation.🧹 Nitpick comments (1)
packages/openai-base/tests/tool-converter-strict-fallback.test.ts (1)
58-88: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚖️ Poor tradeoffRelocate tests alongside the source they cover.
The current file tests multiple modules and is located in a dedicated
tests/directory. Consider splitting this file into separate test files colocated with their respective source modules (e.g.,packages/openai-base/src/adapters/responses-tool-converter.test.ts). As per coding guidelines, place unit tests in*.test.tsfiles alongside the source they cover.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/openai-base/tests/tool-converter-strict-fallback.test.ts` around lines 58 - 88, Split the tests in tool-converter-strict-fallback.test.ts by the source module or converter they cover, and colocate each resulting *.test.ts file beside its corresponding implementation under src, such as responses-tool-converter.test.ts. Preserve all existing test coverage and behavior while removing the multi-module test file from the dedicated tests directory.Source: Coding guidelines
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. Nitpick comments: In `@packages/openai-base/tests/tool-converter-strict-fallback.test.ts`: - Around line 58-88: Split the tests in tool-converter-strict-fallback.test.ts by the source module or converter they cover, and colocate each resulting *.test.ts file beside its corresponding implementation under src, such as responses-tool-converter.test.ts. Preserve all existing test coverage and behavior while removing the multi-module test file from the dedicated tests directory.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID:
a792ea3c-5b8c-4b77-9473-10228ca296ad📥 Commits
Reviewing files that changed from the base of the PR and between 0eeb0267093ee279d2d38726f936f4e27dfa430d and 38ffc6f23eb5f9f9816f0ae1722fd215ded262de.
📒 Files selected for processing (4)
packages/openai-base/src/utils/schema-converter.tspackages/openai-base/tests/schema-converter.test.tspackages/openai-base/tests/tool-converter-strict-fallback.test.tspackages/openai-base/tests/tool-input-normalizer.test.ts
🚧 Files skipped from review as they are similar to previous changes (3)
- packages/openai-base/tests/tool-input-normalizer.test.ts
- packages/openai-base/tests/schema-converter.test.ts
- packages/openai-base/src/utils/schema-converter.ts
🧹 Nitpick comments (1)
packages/openai-base/tests/tool-input-normalizer.test.ts (1)
1-100: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winMove this new unit test alongside
tool-input-normalizer.ts.The current path does not satisfy the repository instruction requiring
*.test.tsfiles alongside their covered source.As per coding guidelines, “Place unit tests in
*.test.tsfiles alongside the source they cover.”<coding_guidelines>🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/openai-base/tests/tool-input-normalizer.test.ts` around lines 1 - 100, Move the createToolInputNormalizer unit tests from the tests directory into a tool-input-normalizer.test.ts file alongside tool-input-normalizer.ts, preserving all existing test cases and imports with paths adjusted for the new location.Source: Coding guidelines
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. Nitpick comments: In `@packages/openai-base/tests/tool-input-normalizer.test.ts`: - Around line 1-100: Move the createToolInputNormalizer unit tests from the tests directory into a tool-input-normalizer.test.ts file alongside tool-input-normalizer.ts, preserving all existing test cases and imports with paths adjusted for the new location.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID:
5488cee5-334f-40d1-8389-cb3979cf2856📥 Commits
Reviewing files that changed from the base of the PR and between 38ffc6f23eb5f9f9816f0ae1722fd215ded262de and 59525c45d3433274f68bf506123daaf3b12ec486.
📒 Files selected for processing (13)
.changeset/calm-tools-return.mdpackages/openai-base/src/adapters/chat-completions-text.tspackages/openai-base/src/adapters/responses-text.tspackages/openai-base/src/utils/schema-converter.tspackages/openai-base/src/utils/tool-input-normalizer.tspackages/openai-base/tests/chat-completions-text.test.tspackages/openai-base/tests/responses-text.test.tspackages/openai-base/tests/schema-converter.test.tspackages/openai-base/tests/tool-converter-strict-fallback.test.tspackages/openai-base/tests/tool-input-normalizer.test.tstesting/e2e/src/routeTree.gen.tstesting/e2e/src/routes/api.openai-strict-tool-null-wire.tstesting/e2e/tests/openai-strict-tool-null-wire.spec.ts
🚧 Files skipped from review as they are similar to previous changes (8)
- testing/e2e/tests/openai-strict-tool-null-wire.spec.ts
- packages/openai-base/src/utils/tool-input-normalizer.ts
- .changeset/calm-tools-return.md
- packages/openai-base/src/adapters/responses-text.ts
- packages/openai-base/tests/responses-text.test.ts
- testing/e2e/src/routeTree.gen.ts
- testing/e2e/src/routes/api.openai-strict-tool-null-wire.ts
- packages/openai-base/src/utils/schema-converter.ts
View your CI Pipeline Execution ↗ for commit 831cf629d266493d49057599461bfcce31ef9ced
Command Status Duration Result nx run-many --targets=build --exclude=examples/...✅ Succeeded 16s View ↗
☁️ Nx Cloud last updated this comment at
2026-08-21 09:18:17UTCgithub-actions[bot](GitHub profile, opens in a new tab) assignedAlemTuzlak
Thanks for the PR, @jan-kubica! 🙌 @AlemTuzlak will take a look.
Automated pre-review checks
- ✅ CI passing
- ✅ No merge conflicts
- ✅ Changeset present
- ✅ E2E test changes included
github-actions[bot](GitHub profile, opens in a new tab) added labelswaiting-on: author
@tanstack/ai
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai@939@tanstack/ai-acp
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-acp@939@tanstack/ai-angular
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-angular@939@tanstack/ai-anthropic
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-anthropic@939@tanstack/ai-bedrock
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-bedrock@939@tanstack/ai-byteplus
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-byteplus@939@tanstack/ai-claude-code
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-claude-code@939@tanstack/ai-client
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-client@939@tanstack/ai-code-mode
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-code-mode@939@tanstack/ai-code-mode-snippets
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-code-mode-snippets@939@tanstack/ai-codex
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-codex@939@tanstack/ai-cohere
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-cohere@939@tanstack/ai-devtools-core
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-devtools-core@939@tanstack/ai-durable-stream
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-durable-stream@939@tanstack/ai-elevenlabs
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-elevenlabs@939@tanstack/ai-event-client
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-event-client@939@tanstack/ai-fal
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-fal@939@tanstack/ai-gemini
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-gemini@939@tanstack/ai-grok
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-grok@939@tanstack/ai-grok-build
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-grok-build@939@tanstack/ai-groq
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-groq@939@tanstack/ai-isolate-cloudflare
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-isolate-cloudflare@939@tanstack/ai-isolate-daytona
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-isolate-daytona@939@tanstack/ai-isolate-node
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-isolate-node@939@tanstack/ai-isolate-quickjs
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-isolate-quickjs@939@tanstack/ai-isolate-quickjs-bun
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-isolate-quickjs-bun@939@tanstack/ai-llmgateway
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-llmgateway@939@tanstack/ai-mcp
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-mcp@939@tanstack/ai-memory
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-memory@939@tanstack/ai-mistral
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-mistral@939@tanstack/ai-ollama
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-ollama@939@tanstack/ai-openai
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-openai@939@tanstack/ai-opencode
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-opencode@939@tanstack/ai-openrouter
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-openrouter@939@tanstack/ai-perplexity
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-perplexity@939@tanstack/ai-persistence
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-persistence@939@tanstack/ai-preact
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-preact@939@tanstack/ai-react
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-react@939@tanstack/ai-react-ui
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-react-ui@939@tanstack/ai-sandbox
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-sandbox@939@tanstack/ai-sandbox-cloudflare
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-sandbox-cloudflare@939@tanstack/ai-sandbox-daytona
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-sandbox-daytona@939@tanstack/ai-sandbox-docker
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-sandbox-docker@939@tanstack/ai-sandbox-local-process
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-sandbox-local-process@939@tanstack/ai-sandbox-sprites
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-sandbox-sprites@939@tanstack/ai-sandbox-vercel
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-sandbox-vercel@939@tanstack/ai-solid
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-solid@939@tanstack/ai-solid-ui
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-solid-ui@939@tanstack/ai-svelte
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-svelte@939@tanstack/ai-utils
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-utils@939@tanstack/ai-vercel-gateway
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-vercel-gateway@939@tanstack/ai-vue
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-vue@939@tanstack/ai-vue-ui
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-vue-ui@939@tanstack/openai-base
npm i https://pkg.pr.new/TanStack/ai/@tanstack/openai-base@939@tanstack/preact-ai-devtools
npm i https://pkg.pr.new/TanStack/ai/@tanstack/preact-ai-devtools@939@tanstack/react-ai-devtools
npm i https://pkg.pr.new/TanStack/ai/@tanstack/react-ai-devtools@939@tanstack/solid-ai-devtools
npm i https://pkg.pr.new/TanStack/ai/@tanstack/solid-ai-devtools@939commit:
831cf62tombeckenham added labelswaiting-on: maintainer
tombeckenham removed labelswaiting-on: author
AlemTuzlak merged thisff27fde
AlemTuzlak closed this
Sign in to join this conversation.
Note
Reviews paused#
It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the
reviews.auto_review.auto_pause_after_reviewed_commitssetting.Use the following commands to manage reviews:
@coderabbitai resumeto resume automatic reviews.@coderabbitai reviewto trigger a single review.Use the checkboxes below for quick actions:
📝 Walkthrough
Walkthrough#
Strict-mode schema conversion now records null widening and detects unsupported
anyOfcases. OpenAI text adapters undo widening for streamed tool arguments, with unit, adapter, and end-to-end tests covering nullable inputs and strict-mode fallback.Changes#
OpenAI tool input null restoration
packages/openai-base/src/utils/schema-converter.ts,packages/openai-base/tests/schema-converter.test.ts,packages/openai-base/src/adapters/*tool-converter.test.ts,packages/openai-base/src/tools/function-tool.test.ts,packages/openai-base/tests/tool-converter-strict-fallback.test.tsanyOfwidening and boolean schemas.packages/openai-base/src/utils/tool-input-normalizer.ts,packages/openai-base/src/utils/tool-input-normalizer.test.ts,packages/openai-base/src/adapters/chat-completions-text.ts,packages/openai-base/src/adapters/responses-text.ts,packages/openai-base/tests/*text.test.ts,.changeset/calm-tools-return.mdtesting/e2e/src/routes/api.openai-strict-tool-null-wire.ts,testing/e2e/src/routeTree.gen.ts,testing/e2e/tests/openai-strict-tool-null-wire.spec.tsEstimated code review effort: 4 (Complex) | ~45 minutes
Sequence Diagram(s)#
Possibly related PRs
Suggested reviewers:
tombeckenham🚥 Pre-merge checks | ✅ 4 | ❌ 1
❌ Failed checks (1 warning)#
✅ Passed checks (4 passed)
✨ Finishing Touches
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.
❤️ Share