Skip to content
Source
Sign inSign up
TanStack/ai

fix: undo strict null widening for tool inputs #939

Mergedjan-kubica(GitHub profile, opens in a new tab)merged 9 commits intomain fromrefs/pull/939/headmerged by AlemTuzlak View on GitHub

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.

    1. Review Change Stack

      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 nameStatusExplanationResolution
      Docstring Coverage⚠️ WarningDocstring 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 nameStatusExplanation
      Linked Issues check✅ PassedCheck skipped because no linked issues were found for this pull request.
      Out of Scope Changes check✅ PassedCheck skipped because no linked issues were found for this pull request.
      Title check✅ PassedThe title clearly summarizes the primary change: undoing strict null widening for tool inputs.
      Description check✅ PassedThe 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
      Comment `@coderabbitai help` to get the list of available commands.
    2. 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.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
      OutdatedResolvedby jan-kubica(GitHub profile, opens in a new tab)
    3. 🧹 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 0eeb0267093ee279d2d38726f936f4e27dfa430d and 38ffc6f23eb5f9f9816f0ae1722fd215ded262de.

      📒 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
    4. 🧹 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 38ffc6f23eb5f9f9816f0ae1722fd215ded262de and 59525c45d3433274f68bf506123daaf3b12ec486.

      📒 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
    5. View your CI Pipeline Execution ↗ for commit 831cf629d266493d49057599461bfcce31ef9ced

      CommandStatusDurationResult
      nx run-many --targets=build --exclude=examples/...✅ Succeeded16sView ↗

      ☁️ Nx Cloud last updated this comment at 2026-08-21 09:18:17 UTC

    6. 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.
    7. github-actions[bot](GitHub profile, opens in a new tab) added labelswaiting-on: author

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

    9. tombeckenham added labelswaiting-on: maintainer

    10. tombeckenham removed labelswaiting-on: author

    11. AlemTuzlak merged thisff27fde

    12. AlemTuzlak closed this

Sign in to join this conversation.