fix: pass AI Config model parameters through to every provider handler

[apucacao]

Every time I ask "how would I use the turnkey SDK here?", I hear about how model params aren't currently being passed to models. This PR fixes that.

Not entirely sure about the implementation though: we ended up definiting the list of params supported by each of the underlying SDKs, because I couldn't find a better export from those packages, and iterating on types felt harder than the explicit list. The downside is that if/when things change, we'd need to update the code. But presumably we already need to do that for our model parameter schemas in Gonfalon.

---

Model parameters set in an AI Config were silently ignored by most handlers. Every handler now passes them through to the provider, limited to an allowlist of model and run settings per handler. Unknown keys are dropped.

• model.parameters comes from the AI Config, so no handler forwards credentials, base URLs or other endpoint and connection settings, timeouts or retries, request header, body or query overrides, remote MCP servers, or Claude Agents host-process settings (cwd, env, permissionMode, the executable path, and so on), in any spelling. Each handler has a test that a bag containing all of them produces options with none of them.
• Configs use snake_case (max_turns, top_p), the providers' own names and what the UI writes.
• Anthropic and OpenAI clients take snake_case, so those handlers pass keys through as-is.
• Agent SDKs and LangChain read camelCase, so those handlers convert top-level keys. If both spellings are set, snake_case wins.
• Nested values are passed as written, except where the SDK reads a different shape: Claude Agents gets thinking.budget_tokens as budgetTokens, and OpenAI Agents gets context_management[].compact_threshold as compactThreshold.
• The Vercel AI SDK handlers map keys onto the AI SDK's own call settings, such as max_tokens to maxOutputTokens. headers and providerOptions are not forwarded: call-level headers replace the provider's Authorization header, and the AI Gateway reads credentials and routing from providerOptions. vercelEvaluate no longer reads model.parameters.
• The Claude Agents and OpenAI Agents native graphs forward each node's settings, plus maxTurns, as the Python native graphs do.

🤖 Generated with Claude Code

---

Note

Overview
AI Config model.parameters are now applied across all provider handlers instead of being ignored or blindly spread into SDK constructors.

Shared helpers in @launchdarkly/ai-server (normalizeModelParameters, pickForwardedModelParameters, camelizeModelParameters) normalize the config bag and pick only allowlisted generation/run settings per handler. Credentials, endpoints, headers, model_kwargs / providerData, remote MCP, and Claude Agents host-process options are never forwarded; handler-owned fields (model, messages/input, tools, streaming flags) still win at merge time.

Per-stack behavior: raw Anthropic/OpenAI message handlers keep snake_case on the wire, with renames like UI effort → output_config.effort and Chat Completions token limits → Responses max_output_tokens. Agent/LangChain/Vercel paths camelize top-level keys (max_turns → maxTurns) and map nested shapes where SDKs differ (e.g. Claude Agents thinking.budget_tokens → budgetTokens, OpenAI Agents maxTurns on Runner.run). Native graphs forward each node’s settings like the Python SDK.

Docs warn integrators not to spread config.model.parameters into LangChain constructors. Coverage adds never-forwarded fixtures, extensive unit tests, and wire-level tests with real SDK + stubbed fetch.

^{Reviewed by Cursor Bugbot for commit 532a0ee. Bugbot is set up for automated code reviews on this repo. Configure here.}

[apucacao]

bugbot run

[cursor]

Stale Bugbot comment from a previous run.

[apucacao]

bugbot run

[cursor]

Stale Bugbot comment from a previous run.

[apucacao]

bugbot run

[cursor]

Stale Bugbot comment from a previous run.

[jeffdupont]

Parity note alongside my review of python #107 (launchdarkly/python-ai-sdk#107). The two messages handlers match Python: allowlists, the effort → output_config and max_tokens → max_output_tokens renames, and unknown keys dropped. The agent and LangChain handlers don't match. Python allowlists every handler. Here the whole model.parameters bag is camelCased and spread in with no filtering, so:

• LangChain (modelConstructorArgs): api_key becomes apiKey, which ChatOpenAI and ChatAnthropic use. anthropic_api_url, configuration, client_options, timeout, max_retries and Bedrock credentials / region / endpoint_host also reach the constructors. Spreading the raw bag predates this PR, but camelCasing is what makes the snake_case spellings the UI writes take effect.
• Claude Agents (buildQueryOptions): cwd, env, permissionMode, extraArgs, pathToClaudeCodeExecutable, executable and allowDangerouslySkipPermissions can all come from a config. The Python PR has the same problem with its allowlist; details are in my inline comment there.
• Nested keys aren't converted: thinking.budget_tokens stays snake_case, but the Claude Agent SDK reads budgetTokens, so the thinking budget is probably ignored. The same goes for context_management[].compact_threshold in openai-agents. I haven't confirmed either at runtime.
• Native graphs: neither the claude-agents nor the openai-agents native graph forwards parameters or maxTurns; Python's do.
• New public names: camelizeModelParameters, normalizeModelParameters and pickForwardedModelParameters are exported from the client root (index.ts:87,93,97). For the 1.0 surface they belong in the internal group.

The monorepo has no spec for forwarding these parameters, and open monorepo #10 says not to rename or filter keys. I'd suggest agreeing one rule in TESTING.md (allowlist per handler, connection and host keys never forwarded) and landing both PRs against it.

[apucacao]

bugbot run

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Stale Bugbot comment from a previous run.

[jeffdupont]

Requesting changes for the security issues below. Re-reviewed at 4241d75. yarn build passes, and yarn test passes: exit 0, 1238 tests across the workspaces.

New since my review: the Vercel parameter mapping (d2a52ae, 4241d75). The rename and camelize logic is right, and the compile-time check against the AI SDK's own types is a good guard. The tests catch the fix: reverting buildModelParameterOptions to pass the raw bag through fails 7 vercel-messages tests and 6 vercel-agents tests.

GA blocker in the new code: headers is on the allowlist, so a config can replace the customer's API key. FORWARDED_MODEL_PARAMETER_KEYS includes headers (vercel-messages/src/model-parameters.ts, and the same list in vercel-agents), and the AI SDK lets call-level headers win over the provider's. I probed it through buildModelParameterOptions into generateText. With the provider built with apiKey: 'CUSTOMER' and a config that sets headers: { Authorization: 'Bearer ATTACKER' }, the request went out with authorization: Bearer ATTACKER, on both @ai-sdk/openai and the Vercel Gateway. This is the same issue as python #103's extra_headers. FORWARDED_EVALUATE_PARAMETER_KEYS forwards headers to experimental_evaluate too (from the code; I didn't probe it). Could headers move to the excluded keys in all three lists? providerOptions deserves a look too, since some providers accept routing and credential settings in it. I haven't tested that.

Repro (a vitest file in packages/vercel-messages/src/, run at 4241d754; it passes, meaning the config's header won):

import { it, expect } from 'vitest';
import { generateText } from 'ai';
import { createOpenAI } from '@ai-sdk/openai';
import { buildModelParameterOptions } from './model-parameters.js';

it('a config header replaces the customer API key', async () => {
  const seen: Record<string, string>[] = [];
  const fetch = async (_url: unknown, init: RequestInit) => {
    seen.push(Object.fromEntries(new Headers(init.headers).entries()));
    return new Response(JSON.stringify({ error: { message: 'x' } }), { status: 401 });
  };
  const provider = createOpenAI({ apiKey: 'CUSTOMER', fetch: fetch as typeof globalThis.fetch });
  const opts = buildModelParameterOptions({ headers: { Authorization: 'Bearer ATTACKER' } } as never);
  await generateText({ model: provider('gpt-4o'), prompt: 'hi', maxRetries: 0, ...opts }).catch(() => {});
  expect(seen[0]?.authorization).toBe('Bearer ATTACKER');
});

The handler spreads these options into generateText / streamText (vercel-messages/src/handler.ts:280, :329). Inverting that assertion makes a good regression test once headers is excluded.

Still open, no reply on either thread:

1. Claude Agents spreads the whole bag into query() options (thread 1, GA blocker). No change. claude-agents/src/handler.ts:997 and :1124 still pass camelizeModelParameters(normalizeModelParameters(...)) with no allowlist, so cwd, env, permissionMode, pathToClaudeCodeExecutable and allowDangerouslySkipPermissions can all come from a config.

2. LangChain constructor args (thread 2). No change. langchain-messages/src/handler.ts:175, and the same in langchain-agents, still spread the camelized bag, so api_key → apiKey, anthropic_api_url and client_options reach the constructors.

3. OpenAI Agents forwards extraHeaders / extraBody / extraQuery. Bugbot flagged this on the current head (openai-agents/src/handler.ts:510): buildModelSettings camelizes the whole bag into ModelSettings, so a config can inject request headers or body fields on every model call. Same class as the Vercel headers bug; I haven't probed it.

openai-agents has no allowlist at all. Python #107 allowlists every handler, so those three JS handlers are where the two SDKs disagree. Nested keys (thinking.budget_tokens) are still left in snake_case, which I raised in my first review.

There's no TESTING.md section for parameter forwarding. python #107 needs the same, so one shared spec section listing the excluded keys (credentials, base URLs, headers, host-process settings) would keep both languages aligned.

[apucacao]

bugbot run

[cursor]

Stale Bugbot comment from a previous run.

[apucacao]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 532a0ee. Configure here.}