fix: undo strict null widening for tool inputs by jan-kubica · Pull Request #939 · TanStack/ai

jan-kubica · 2026-07-14T22:59:09Z

🎯 Changes

OpenAI-compatible strict function schemas promote optional properties to required nullable properties. The model can therefore return null for an omitted optional field, but TanStack AI subsequently validates that value against the original Standard Schema, where .optional() accepts absence/undefined, not null. This prevents otherwise valid server tools from executing.

This PR:

records a NullWideningMap during the same OpenAI strict-schema conversion that adds nullability
removes only provider-synthesized nulls before emitting completed tool input, while preserving nulls the original schema genuinely allows
applies the normalization to both Chat Completions and Responses, including their completion/backfill paths
leaves non-strict tools and ambiguous duplicate tool names untouched
adds adapter unit coverage plus a mocked Responses wire round trip that validates and executes the original Zod tool schema across two model turns

Test plan

pnpm run test:pr
pnpm --filter @tanstack/openai-base test:lib (134 tests)
pnpm --filter @tanstack/ai-e2e test:e2e -- openai-strict-tool-null-wire.spec.ts
pnpm --filter @tanstack/ai-e2e test:e2e (347 passed, 2 unrelated flaky tests passed on retry, 1 gated live smoke skipped)

✅ Checklist

I have followed the steps in the Contributing guide.
I have tested this code locally with pnpm run test:pr.

🚀 Release Impact

This change affects published code, and I have generated a changeset.
This change is docs/CI/dev-only (no release).

Summary by CodeRabbit

Bug Fixes
- Preserved explicit null values for streamed OpenAI-compatible tool-call inputs by undoing strict null widening before validating/emitting tool-call payloads.
- Applied consistent tool-argument normalization across both chat completions and responses adapters.
- Strengthened strict-mode schema compatibility detection, including additional anyOf edge cases.
Tests
- Added streaming, schema-converter, unit, and end-to-end coverage for strict-tool-null handling, including ambiguous and fallback scenarios.

coderabbitai · 2026-07-14T22:59:17Z

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

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
Title check	✅ Passed	The title clearly summarizes the main change: undoing strict null widening for tool inputs.
Description check	✅ Passed	The description covers the required changes, checklist, test plan, and release impact sections with concrete details.
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.

✨ 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

_{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

tombeckenham · 2026-08-10T09:13:39Z

Maintainer sweep: rebased onto main (force-with-lease). CI approval handled if it was waiting.

nx-cloud · 2026-08-10T09:24:04Z

View your CI Pipeline Execution ↗ for commit 26d7fd3

Command	Status	Duration	Result
`nx run-many --targets=build --exclude=examples/...`	✅ Succeeded	17s	View ↗

☁️ Nx Cloud last updated this comment at 2026-08-10 09:24:03 UTC

github-actions · 2026-08-13T10:31:40Z

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.}

jan-kubica force-pushed the fix/strict-optional-null-input branch from 2a6c4c8 to 0eeb026Compare July 16, 2026 08:49

jan-kubica marked this pull request as ready for review July 16, 2026 08:49

coderabbitaiBot reviewed Jul 16, 2026
View reviewed changes

Comment threadpackages/openai-base/src/utils/schema-converter.ts Outdated

jan-kubica mentioned this pull request Jul 16, 2026
fix: normalize OpenAI strict tool inputs at the adapter boundary stella/stella#1174
Merged

coderabbitaiBot reviewed Jul 16, 2026
View reviewed changes

jan-kubica force-pushed the fix/strict-optional-null-input branch from 38ffc6f to 59525c4Compare July 17, 2026 06:09

coderabbitaiBot reviewed Jul 17, 2026
View reviewed changes

coderabbitaiBot mentioned this pull request Jul 17, 2026
fix: normalize Mistral strict null inputs #956
Draft
7 tasks

jan-kubica added 6 commits August 10, 2026 19:13

fix: normalize strict optional tool inputs
f6cb3f7

fix: avoid ambiguous anyOf null normalization
749ed71

fix: widen optional literal schemas
4ae7c9d

test: colocate strict tool regressions
e2b604b

fix: fall back for boolean OpenAI schema nodes
5a10725

fix: preserve nullable OpenAI union inputs
26d7fd3

tombeckenham force-pushed the fix/strict-optional-null-input branch from 27e1655 to 26d7fd3Compare August 10, 2026 09:13

ci: apply automated fixes
2285c9f

github-actionsBot assigned AlemTuzlak Aug 13, 2026

github-actionsBot added the waiting-on: author Waiting for the author to respond or update label Aug 13, 2026

Navigation Menu

Uh oh!

Uh oh!

fix: undo strict null widening for tool inputs - #939

fix: undo strict null widening for tool inputs#939
jan-kubica wants to merge 7 commits into
TanStack:mainfrom
jan-kubica:fix/strict-optional-null-input

jan-kubica commented Jul 14, 2026•
edited by coderabbitai Bot
Loading

Uh oh!

coderabbitaiBot commented Jul 14, 2026•
edited
Loading

Reviews paused

Walkthrough

Changes

Sequence Diagram(s)

❌ Failed checks (1 warning)

Uh oh!

coderabbitaiBot left a comment

Uh oh!

Uh oh!

coderabbitaiBot left a comment

Uh oh!

coderabbitaiBot left a comment

Uh oh!

tombeckenham commented Aug 10, 2026

Uh oh!

nx-cloudBot commented Aug 10, 2026

Uh oh!

github-actionsBot commented Aug 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Uh oh!

Conversation

jan-kubica commented Jul 14, 2026• edited by coderabbitai BotLoading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🎯 Changes

Test plan

✅ Checklist

🚀 Release Impact

Summary by CodeRabbit

Uh oh!

coderabbitaiBot commented Jul 14, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reviews paused

Walkthrough

Changes

Sequence Diagram(s)

❌ Failed checks (1 warning)

Uh oh!

coderabbitaiBot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

coderabbitaiBot left a comment

Choose a reason for hiding this comment

Uh oh!

coderabbitaiBot left a comment

Choose a reason for hiding this comment

Uh oh!

tombeckenham commented Aug 10, 2026

Uh oh!

nx-cloudBot commented Aug 10, 2026

Uh oh!

github-actionsBot commented Aug 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jan-kubica commented Jul 14, 2026•
edited by coderabbitai Bot
Loading

coderabbitaiBot commented Jul 14, 2026•
edited
Loading