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

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

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

coderabbitai Bot reviewed Jul 16, 2026

View reviewed changes

Comment thread packages/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

coderabbitai Bot reviewed Jul 16, 2026

View reviewed changes

jan-kubica added 3 commits July 17, 2026 07:14

fix: normalize strict optional tool inputs

173a5e8

fix: avoid ambiguous anyOf null normalization

d3c7c70

fix: widen optional literal schemas

59525c4

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

coderabbitai Bot reviewed Jul 17, 2026

View reviewed changes

test: colocate strict tool regressions

d45e03d

coderabbitai Bot mentioned this pull request Jul 17, 2026

fix: normalize Mistral strict null inputs #956

Draft

7 tasks

jan-kubica added 2 commits July 17, 2026 13:40

fix: fall back for boolean OpenAI schema nodes

482581a

fix: preserve nullable OpenAI union inputs

27e1655

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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 6 commits into
TanStack:mainfrom
jan-kubica:fix/strict-optional-null-input

jan-kubica commented Jul 14, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jul 14, 2026 •

edited

Loading

Reviews paused

Walkthrough

Changes

Sequence Diagram(s)

❌ Failed checks (1 warning)

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Uh oh!

Conversation

jan-kubica commented Jul 14, 2026 • edited by coderabbitai Bot Loading 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!

coderabbitai Bot 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!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

jan-kubica commented Jul 14, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jul 14, 2026 •

edited

Loading