fix(workers-ai-provider): forward reasoning_effort and chat_template_kwargs (#501)

[threepointone]

Summary

• Forwards reasoning_effort and chat_template_kwargs onto binding.run(model, inputs)'s inputs object instead of silently dropping them into the options arg / REST query string.
• Supports both settings-level and per-call usage (via providerOptions["workers-ai"]; per-call wins).
• Types both fields directly on WorkersAIChatSettings; reasoning_effort: null is preserved as the explicit "disable reasoning" signal.

Closes #501.

Why

modelSettings passed as the 2nd arg of workersAi(modelId, modelSettings) were flowing through getRunOptions() into the 3rd arg (options) of binding.run(model, inputs, options). But Cloudflare Workers AI's reasoning_effort and chat_template_kwargs parameters belong on the 2nd arg (inputs). The result: reasoning models (GLM-4.7-flash, Kimi K2.5/K2.6, GPT-OSS, QwQ) burned the entire output token budget on chain-of-thought with no visible content, because reasoning_effort: "low" was silently ignored. The REST path had an additional latent bug where reasoning_effort: null would throw from createRun at the query-string coercion step.

What changed

src/workersai-chat-settings.ts — typed reasoning_effort and chat_template_kwargs directly on WorkersAIChatSettings alongside the existing [key: string]: unknown escape hatch.

src/workersai-chat-language-model.ts — three surgical changes:

1. buildRunInputs() now pulls both fields from settings and from providerOptions["workers-ai"] (per-call wins via "key" in perCall, so per-call null overrides settings "high"). A typeof + Array.isArray guard protects against malformed runtime values (since "key" in primitive throws).
2. getRunOptions() explicitly destructures the two fields out so they can't leak into ...passthroughOptions (which is what bled into URL query strings / options arg).
3. doGenerate and doStream now wire options.providerOptions through to buildRunInputs.

Usage

// Settings-level
const model = workersai("@cf/zai-org/glm-4.7-flash", {
  reasoning_effort: "low",
  chat_template_kwargs: { enable_thinking: false },
});

// Per-call (overrides settings)
await generateText({
  model,
  prompt,
  providerOptions: {
    "workers-ai": { reasoning_effort: "low" },
  },
});

Test plan

• 15 new unit tests (binding + REST + gateway + providerOptions paths)
• Binding path: reasoning_effort lands on inputs (2nd arg), not options
• Binding path: chat_template_kwargs lands on inputs, not options
• reasoning_effort: null is preserved on inputs
• Omission stays absent from both inputs and options
• Per-call providerOptions["workers-ai"] overrides settings
• Per-call null overrides non-null settings (locks in "key" in precedence)
• Malformed providerOptions["workers-ai"] (string / array) falls back to settings instead of crashing
• Reasoning params + Gateway on binding path — no interference
• Streaming request forwards both fields with stream: true
• REST path: both fields land in the JSON body, not the URL query string
• REST path: reasoning_effort: null round-trips (pre-fix regression)
• REST path: unrelated custom settings (custom_flag: "yes") still flow to the URL query — no regression for existing passthrough behavior
• 250/250 unit tests passing
• Type-check clean

Sibling chat classes (AutoRAGChatLanguageModel, AISearchChatLanguageModel) audited — they don't use binding.run(model, inputs, options) and have no reasoning surface, so no duplicate fix is needed.

Notes for reviewers

• Per-call providerOptions key is "workers-ai" (matches npm package name). Other reasonable candidates are "workersai" (matches the internal provider field prefix) or "workersai.chat" (matches the full provider name). Happy to flip this pre-merge if the maintainers prefer a different convention.
• Split into two commits for auditable review: the original fix, plus a review-driven hardening pass with extra tests and the defensive typeof guard. Happy to squash before merge if preferred.

Made with Cursor

[changeset-bot]

🦋 Changeset detected

Latest commit: 4b25307

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
workers-ai-provider	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in StackBlitz

npx https://pkg.pr.new/cloudflare/ai/ai-gateway-provider@504

npx https://pkg.pr.new/cloudflare/ai/@cloudflare/tanstack-ai@504

npx https://pkg.pr.new/cloudflare/ai/workers-ai-provider@504

commit: 4b25307