fix: undo strict null widening for tool inputs

[jan-kubica]

OpenAI-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 NullWideningMap during 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:

1. pnpm --filter @tanstack/openai-base test:lib — 203 passed
2. pnpm --filter @tanstack/ai-groq test:lib — 36 passed
3. pnpm --filter @tanstack/openai-base test:types and pnpm --filter @tanstack/ai-groq test:types — passed
4. pnpm --filter @tanstack/openai-base test:oxlint and pnpm --filter @tanstack/ai-groq test:oxlint — passed (existing any warnings only)

I did not re-run pnpm test:pr or the e2e spec after the follow-up commit.

Manual test:

1. Define a strict OpenAI-compatible tool with .optional() and .nullable() fields.
2. Call it so the model omits the optional field (wire value null) and sets the nullable field to null.
3. Confirm the tool handler receives the optional field as absent and the nullable field as null.
4. 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.

[coderabbitai]

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_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Strict-mode schema conversion now records null widening and detects unsupported anyOf cases. 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

Layer / File(s)	Summary
Strict-schema widening metadata and fallback 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.ts	Strict conversion returns null-widening maps, propagates metadata through nested schemas and arrays, and disables strict mode for untrackable anyOf widening and boolean schemas.
Streamed tool-input normalization 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.md	Tool-specific normalizers reverse strict null widening, and both OpenAI streaming adapters apply them before emitting completed tool-call inputs.
End-to-end nullable tool execution testing/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.ts	A mocked OpenAI route and Playwright test verify strict schema nullability, restored tool input, follow-up completion, and request count.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant Chat
  participant OpenAIAdapter
  participant ToolInputNormalizer
  participant ToolHandler
  Client->>Chat: Start chat with ask_user tool
  Chat->>OpenAIAdapter: Send strict tool schema
  OpenAIAdapter-->>Chat: Stream tool-call arguments with null values
  Chat->>ToolInputNormalizer: Restore null-widened input
  ToolInputNormalizer-->>Chat: Return normalized tool input
  Chat->>ToolHandler: Execute ask_user
  ToolHandler-->>Chat: Return tool result
  Chat->>OpenAIAdapter: Request follow-up completion
  OpenAIAdapter-->>Client: Stream final assistant text

Loading

Possibly related PRs

• TanStack/ai#732: Applies the same null-widening restoration mechanism to structured-output validation.
• TanStack/ai#786: Extends the strict-schema compatibility logic used by this change.
• TanStack/ai#933: Modifies the shared strict-mode tool-schema fallback logic.

Suggested reviewers: tombeckenham

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly summarizes the primary change: undoing strict null widening for tool inputs.
Description check	✅ Passed	The description follows the required template and clearly documents changes, testing, release impact, risks, and public API considerations.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

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 fbfd4be and 0eeb026.

📒 Files selected for processing (12)

• .changeset/calm-tools-return.md
• packages/openai-base/src/adapters/chat-completions-text.ts
• packages/openai-base/src/adapters/responses-text.ts
• packages/openai-base/src/utils/schema-converter.ts
• packages/openai-base/src/utils/tool-input-normalizer.ts
• packages/openai-base/tests/chat-completions-text.test.ts
• packages/openai-base/tests/responses-text.test.ts
• packages/openai-base/tests/schema-converter.test.ts
• packages/openai-base/tests/tool-input-normalizer.test.ts
• testing/e2e/src/routeTree.gen.ts
• testing/e2e/src/routes/api.openai-strict-tool-null-wire.ts
• testing/e2e/tests/openai-strict-tool-null-wire.spec.ts

[coderabbitai]

🧹 Nitpick comments (1)

packages/openai-base/tests/tool-converter-strict-fallback.test.ts (1)

58-88: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚖️ Poor tradeoff

Relocate 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.ts files 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 0eeb026 and 38ffc6f.

📒 Files selected for processing (4)

• packages/openai-base/src/utils/schema-converter.ts
• packages/openai-base/tests/schema-converter.test.ts
• packages/openai-base/tests/tool-converter-strict-fallback.test.ts
• packages/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

[coderabbitai]

🧹 Nitpick comments (1)

packages/openai-base/tests/tool-input-normalizer.test.ts (1)

1-100: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Move this new unit test alongside tool-input-normalizer.ts.

The current path does not satisfy the repository instruction requiring *.test.ts files alongside their covered source.

As per coding guidelines, “Place unit tests in *.test.ts files 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 38ffc6f and 59525c4.

📒 Files selected for processing (13)

• .changeset/calm-tools-return.md
• packages/openai-base/src/adapters/chat-completions-text.ts
• packages/openai-base/src/adapters/responses-text.ts
• packages/openai-base/src/utils/schema-converter.ts
• packages/openai-base/src/utils/tool-input-normalizer.ts
• packages/openai-base/tests/chat-completions-text.test.ts
• packages/openai-base/tests/responses-text.test.ts
• packages/openai-base/tests/schema-converter.test.ts
• packages/openai-base/tests/tool-converter-strict-fallback.test.ts
• packages/openai-base/tests/tool-input-normalizer.test.ts
• testing/e2e/src/routeTree.gen.ts
• testing/e2e/src/routes/api.openai-strict-tool-null-wire.ts
• testing/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

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 831cf62

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:17 UTC

[github-actions]

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

_{Automated triage — a human review follows.}

[pkg-pr-new]

Open in StackBlitz

@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@939

commit: 831cf62