fix(models): reasoning_effort for azure grok-4.3

[andyst-dev]

Refs #3436, refs #3403 — see "Deliberately not changed" for why neither is fully closed here.

Problem

azure-ai-foundry/grok-4.3 declares reasoning: true but omits reasoning_effort from its supportedParameters, so any effort value a client sends is silently dropped at the default-case gate in prepare-request-body.ts before the request is built. The same underlying model already forwards the parameter on its xai and aws-bedrock mappings, both of which declare reasoningEfforts: ["none", "low", "medium", "high"] — Azure Foundry was simply never given the equivalent fix (#3159 scoped its change to the native mappings).

Change

packages/models/src/models/xai.ts:

• Add reasoning_effort to azure-ai-foundry/grok-4.3's inline supportedParameters, and declare reasoningEfforts matching its sibling mappings so /v1/models publishes the accepted tiers.
• Document on xaiSupportedParamsNoFreqPresence why reasoning_effort is deliberately absent from the shared const, so the next reader doesn't add it back wholesale.

packages/models/src/model-metadata.spec.ts:

• New invariant: every xAI mapping that advertises reasoning_effort must also declare reasoningEfforts. The tiers are the record that the deployment was actually verified; without them neither the gateway nor a client knows which values are safe.

packages/actions/src/prepare-request-body.spec.ts:

• Dedicated prepareRequestBody - xAI reasoning_effort describe: positive case for the Azure Foundry mapping, plus negative cases pinning the mappings that deliberately still drop the parameter.
• The pre-existing keeps Grok 4.3 as Azure Foundry chat completions test now asserts reasoning_effort: "medium" is forwarded, where it previously asserted undefined and encoded the bug.

Deliberately not changed

An earlier revision of this PR also enabled reasoning_effort on xai/grok-4, azure-ai-foundry/grok-4-1-fast-reasoning, vertex-openai/grok-4.20-reasoning, xai/grok-4.20-beta-0309-reasoning and xai/grok-build-0.1. Those are reverted:

• grok-4 is documented as rejecting the parameter, and its own mapping comment says the model always reasons.
• grok-build-0.1 and grok-4.20-beta-0309-reasoning were explicitly skipped in feat(models): declare reasoning efforts for xai #3046 for lack of documented values.
• The vertex-openai and Grok 4.1 Fast mappings are exactly the live checks [Bug]: reasoning_effort untested for grok-4.20-reasoning on vertex-openai — deferred check from #3046 #3403 and [Bug]: reasoning_effort dropped entirely for grok-4.3 and grok-4-1-fast-reasoning on azure-ai-foundry #3436 asked for before enabling — that verification still hasn't happened.

The gateway forwards effort verbatim, each of those models has a single routable mapping, and auto routing injects reasoning_effort: "low" on its own — so an unaccepted parameter is a hard user-visible error with no fallback to absorb it. Enabling them needs one live call each first. #3403 and the grok-4-1-fast-reasoning half of #3436 therefore stay open.

Two adjacent gaps are also out of scope here:

• Neither xai nor azure-ai-foundry is in handlesNoneNatively, so none is normalized away on both hosts even though grok-4.3 declares it and aws-bedrock forwards it. Pre-existing on the native mapping; a gateway fix, not a catalogue one.
• The new invariant is xAI-scoped on purpose. A catalogue-wide "reasoning implies reasoning_effort" rule flags 49 mappings, including every OpenAI GPT-5 and Anthropic mapping — correct code, because those providers are handled before the supportedParameters gate.

Validation

• tsc -p packages/actions clean (the previous revision's test helper failed with TS2339 and broke pnpm build).
• 753 tests pass across packages/models, packages/actions, and the gateway/playground specs that touch grok models.
• New metadata invariant confirmed non-vacuous: removing the reasoningEfforts declaration makes it fail and name the offending mapping.
• pnpm format and a full pnpm build.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added configurable reasoning effort for Azure AI Foundry’s Grok 4.3 model, with support for none, low, medium, and high levels.
  • Grok 4.3 now uses medium reasoning effort by default where applicable.

• Bug Fixes

  • Improved reasoning-effort handling across xAI-compatible model integrations.
  • Unsupported reasoning settings are now omitted instead of being forwarded incorrectly.

[coderabbitai]

Walkthrough

The change adds provider-specific reasoning_effort support for Azure AI Foundry Grok 4.3. It documents the xAI parameter exception, validates metadata declarations, and adds request-body regression tests for forwarding and omission.

Changes

xAI reasoning effort support

Layer / File(s)	Summary
Declare xAI reasoning parameters packages/models/src/models/xai.ts, packages/models/src/model-metadata.spec.ts	Azure Grok 4.3 declares none, low, medium, and high reasoning tiers. Metadata tests verify that mappings supporting reasoning_effort declare corresponding tiers.
Validate request forwarding packages/actions/src/prepare-request-body.spec.ts	Tests verify forwarding for Azure Grok 4.3, omission for unsupported xAI and Vertex OpenAI mappings, and the "medium" expectation for Azure Grok 4.3.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• theopenco/llmgateway#3159 — Adds related xAI reasoning-effort support for Grok mappings.
• theopenco/llmgateway#3125 — Declares reasoning-effort values for an xAI Grok 4.3 mapping.
• theopenco/llmgateway#3427 — Adds related reasoning-effort mapping and regression coverage.

Suggested reviewers: steebchen, smakosh

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	The PR fixes Grok 4.3 but does not resolve the linked requirements for Azure Grok 4.1 fast reasoning or Vertex Grok 4.20 reasoning.	Address the remaining linked mappings, or explicitly split and defer those issue requirements with maintainer approval.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Out of Scope Changes check	✅ Passed	The implementation and regression tests stay within the linked objectives for reasoning_effort mapping and request handling.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the main change: fixing reasoning_effort support for the Azure Grok 4.3 model mapping.

✨ 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/actions/src/prepare-request-body.spec.ts`:
- Around line 1120-1141: Update the reasoning_effort test around
prepareRequestBody to verify the supportedParameters gate rather than only
serialization. Assert that all six relevant provider mappings include
"reasoning_effort", or invoke the caller path that filters unsupported
parameters before prepareRequestBody receives them, ensuring the test fails when
the mapping removes the parameter.

🪄 Autofix

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: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 86c2ed39-2532-490f-bd3e-bb5f5633a07d

📥 Commits

Reviewing files that changed from the base of the PR and between 87a403b and ed47305.

📒 Files selected for processing (2)

• packages/actions/src/prepare-request-body.spec.ts
• packages/models/src/models/xai.ts

[coderabbitai]

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Test the supportedParameters gate.

prepareRequestBody serializes any defined reasoning_effort. This test passes if a mapping removes "reasoning_effort" because it passes effort directly to the serializer.

Assert that the six provider mappings contain "reasoning_effort", or exercise the caller that removes unsupported parameters before it calls prepareRequestBody.

Based on learnings: supportedParameters is the source of truth, and the gateway maps unsupported parameters to undefined before request construction.

🤖 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/actions/src/prepare-request-body.spec.ts` around lines 1120 - 1141,
Update the reasoning_effort test around prepareRequestBody to verify the
supportedParameters gate rather than only serialization. Assert that all six
relevant provider mappings include "reasoning_effort", or invoke the caller path
that filters unsupported parameters before prepareRequestBody receives them,
ensuring the test fails when the mapping removes the parameter.

Source: Learnings

[AmineAce]

The Minor comment about test fidelity is worth addressing before merge — right now the tests confirm the request body ends up correct, but don't actually assert that supportedParameters contains "reasoning_effort" for the 6 fixed mappings. That distinction matters: if a future refactor changes how the gate reads supportedParameters, a serialization-only test could keep passing while the actual capability check silently regresses. A direct assertion on each mapping's supportedParameters array would catch that class of regression, not just today's behavior.

[andyst-dev]

Good point — the serialization assertion alone wouldn't catch a refactor that stops reading supportedParameters. Each case now also asserts the capability directly on the mapping:

const modelDef = models.find((m) => m.id === model);
const mapping = modelDef?.providers.find((p) => p.providerId === provider);
expect(mapping?.supportedParameters).toContain("reasoning_effort");

This walks the same resolution path the request builder uses (models.find → providers.find), so a regression in either the catalog entries or the gate's read of supportedParameters fails the test immediately, for all 6 fixed mappings (azure-ai-foundry/grok-4-3, azure-ai-foundry/grok-4-1-fast-reasoning, vertex-openai/grok-4-20-reasoning, xai/grok-4, xai/grok-4-20-beta-0309-reasoning, xai/grok-build-0-1). The body-forwarding assertion stays alongside it.

Validation:

pnpm exec vitest run --config vitest.config.mts packages/actions/src/prepare-request-body.spec.ts
Test Files  1 passed (1)
Tests       249 passed (249)

Branch rebased on current main. New head: 7cff5cc.

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

packages/actions/src/prepare-request-body.spec.ts (1)

2683-2703: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Replace broad type escapes with narrow payload types.

The new tests use any and as any. Define local provider-specific request-body types, then cast through unknown only where the prepareRequestBody union requires narrowing.

• packages/actions/src/prepare-request-body.spec.ts#L2683-L2703: Type the Google tool request body and its schema parameters.
• packages/actions/src/prepare-request-body.spec.ts#L2760-L2780: Reuse the same Google tool request-body type.
• packages/actions/src/prepare-request-body.spec.ts#L5995-L6021: Type provider, webSearchTool, and the DashScope request payload without any.

As per coding guidelines, **/*.{ts,tsx} must “avoid any and as any unless absolutely necessary.”

🤖 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/actions/src/prepare-request-body.spec.ts` around lines 2683 - 2703,
Replace broad any/as any escapes in prepare-request-body.spec.ts with local
provider-specific types: at lines 2683-2703 define and use a Google tool
request-body type including schema parameters, and at lines 2760-2780 reuse it;
at lines 5995-6021 type provider, webSearchTool, and the DashScope request
payload explicitly. Cast through unknown only where prepareRequestBody’s union
requires narrowing, and make no other changes.

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.

Outside diff comments:
In `@packages/actions/src/prepare-request-body.spec.ts`:
- Around line 2683-2703: Replace broad any/as any escapes in
prepare-request-body.spec.ts with local provider-specific types: at lines
2683-2703 define and use a Google tool request-body type including schema
parameters, and at lines 2760-2780 reuse it; at lines 5995-6021 type provider,
webSearchTool, and the DashScope request payload explicitly. Cast through
unknown only where prepareRequestBody’s union requires narrowing, and make no
other changes.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: ac3f09c1-3dad-4987-874d-f578198997cf

📥 Commits

Reviewing files that changed from the base of the PR and between ed47305 and 7cff5cc.

📒 Files selected for processing (1)

• packages/actions/src/prepare-request-body.spec.ts

[steebchen]

Closing in favor of #3483, which carries this work forward with a correction.

E2E-verified this branch against a live xAI key. Three of the six mappings widened here reject reasoning_effort upstream — api.x.ai answers 400 does not support parameter reasoningEffort for grok-4.20-beta-0309-reasoning, grok-build-0.1, and grok-4.20-reasoning. Control requests without the parameter return 200, so the parameter is the sole cause, and streaming behaves the same. For those mappings the omission was the catalogue correctly reflecting upstream rather than the gap #3436/#3403 describe, so declaring it turns every effort-bearing request into a 400.

Concretely, TEST_MODELS="xai/grok-4,xai/grok-4-20-beta-0309-reasoning,xai/grok-build-0-1" pnpm test:e2e fails 4 tests on this branch (chat-reasoning.e2e.ts > basic reasoning and chat-rs.e2e.ts > reasoning + streaming, for both models). The same four pass on main.

Separately, pnpm build fails here: the new spec reads .supportedParameters off the raw catalogue union, which tsc rejects with TS2339 since not every member declares it.

#3483 keeps your addition for xai/grok-4 and the two azure-ai-foundry mappings, restores the shared list for the three rejecting ones with a comment on each explaining why, adds the inverse regression test, and fixes the type error. Scoped e2e is green there. Thanks for finding the underlying gate — the grok-4 and grok-4.3 half of this was a real fix.

---

Generated by Claude Code