refactor(providers): map xAI tool_choice to the Responses API shape with a typed request body (#2036)

* refactor(providers): map xAI tool_choice to the Responses API shape with a typed request body

Extracted from the abort-signal series unit (PR 1293) at reviewer
request so that unit stays abort-wiring only:

- xai: replace the `as any` tool_choice cast with an explicit
  mapToolChoice mapping (Chat Completions nests named-tool references
  under function/custom; the Responses API puts the name at the top
  level; allowed_tools entries are flattened).
- xai: type the request body as ResponseCreateParamsStreaming (drops
  five lint suppressions) and send max_output_tokens/temperature
  unconditionally - getModel() always resolves them.
- anthropic-vertex: drop the no-op content_block_stop case (the
  comment itself noted no action is needed; NativeToolCallParser
  handles tool-call completion).

Verification: 75/75 green in xai.spec.ts + anthropic-vertex.spec.ts;
tsc --noEmit 0 errors; eslint --max-warnings=0 clean on touched files
(xai.ts suppression count 7 -> 2); prettier clean.

* Address review: reject malformed allowed_tools function entries

Chat Completions allowlist entries are open records, so a function entry
can arrive with a missing or non-string name. Forwarding such an entry
unchanged would send the nested Chat Completions shape to the Responses
API, which cannot express that allowlist entry, and how xAI handles the
malformed payload is unspecified. mapToolChoice now rejects function
entries without a valid string name at the boundary (before
responses.create); non-function entries still pass through unchanged.

The pass-through test now pins only the non-function case; a new test
rejects four malformed function-entry shapes (null name, null ref,
function value, non-string name) and asserts no request is issued
(negative control verified: reverting the throw to a pass-through fails
the new test).

Verification at this head: 25/25 green in xai.spec.ts; tsc --noEmit 0
errors; eslint --max-warnings=0 clean on touched files; prettier clean.

* chore(lint): take upstream baseline suppressions for xai.ts

The merge brings main xai responses-create code whose as-any casts main suppresses (count 7 in upstream eslint-suppressions.json). Locally the auto-merge kept the older count 2, so compile lint flagged the inherited casts. Use the upstream baseline instead of leaving the branch red.

* chore(lint): right-size the xai suppression to the merged any count

The merge keeps five as-any occurrences in xai.ts (two in the mapResponseTools signature, three in the responses create call); the upstream baseline of seven would leave stale suppressions, which eslint rejects. Set the count to the actual five.

* test(xai): assert request options without the extra call-argument shape

The merge with main makes responses.create take a second options argument. Rewriting the assertions to inspect mock.calls[0][0] left the old second expectation argument in place, which failed type-check (toEqual takes one argument). Each assertion now checks the request body and the separate options argument explicitly (signal/timeout, forwarded timeout, absent options). xai.spec.ts 49 passed; tsc clean for the file.

* fix(xai): bridge the abort signal only after request construction

Review follow-up: mapToolChoice throws for malformed allowed_tools entries, and the abort bridge cleanup only covers the request that follows. The bridge now registers after the whole request body (including the tool-choice mapping) is built, so a construction failure cannot leave a listener on metadata.abortSignal. The malformed-entry test now passes an abortSignal and asserts addEventListener was never called. xai.spec.ts 49 passed; tsc clean.

* chore(lint): flag unneeded type assertions in api/

---------

Co-authored-by: Eason Liang <easonliang28@gmail.com>
Co-authored-by: Elliott de Launay <edelauna@gmail.com>

Author: 3 people

src/api/providers/__tests__/xai.spec.ts

@@ -143,7 +143,7 @@ export class AnthropicVertexHandler extends BaseProvider implements SingleComple
 			for await (const chunk of stream) {
 				switch (chunk.type) {
 					case "message_start": {
-						const usage = chunk.message!.usage
+						const usage = chunk.message.usage
 
 						// `output_tokens_details.thinking_tokens` decomposes the billed
 						// output into internal reasoning tokens; surfaced for per-turn
@@ -155,19 +155,19 @@ export class AnthropicVertexHandler extends BaseProvider implements SingleComple
 							cacheWriteTokens: usage.cache_creation_input_tokens || undefined,
 							cacheReadTokens: usage.cache_read_input_tokens || undefined,
 							...(typeof usage.output_tokens_details?.thinking_tokens === "number"
-								? { reasoningTokens: usage.output_tokens_details!.thinking_tokens }
+								? { reasoningTokens: usage.output_tokens_details.thinking_tokens }
 								: {}),
 						}
 
 						break
 					}
 					case "message_delta": {
-						const deltaThinkingTokens = chunk.usage!.output_tokens_details?.thinking_tokens
+						const deltaThinkingTokens = chunk.usage.output_tokens_details?.thinking_tokens
 
 						yield {
 							type: "usage",
 							inputTokens: 0,
-							outputTokens: chunk.usage!.output_tokens || 0,
+							outputTokens: chunk.usage.output_tokens || 0,
 							...(typeof deltaThinkingTokens === "number"
 								? { reasoningTokens: deltaThinkingTokens }
 								: {}),
@@ -176,17 +176,17 @@ export class AnthropicVertexHandler extends BaseProvider implements SingleComple
 						break
 					}
 					case "content_block_start": {
-						switch (chunk.content_block!.type) {
+						switch (chunk.content_block.type) {
 							case "text": {
-								if (chunk.index! > 0) {
+								if (chunk.index > 0) {
 									yield { type: "text", text: "\n" }
 								}
 
-								yield { type: "text", text: chunk.content_block!.text }
+								yield { type: "text", text: chunk.content_block.text }
 								break
 							}
 							case "thinking": {
-								if (chunk.index! > 0) {
+								if (chunk.index > 0) {
 									yield { type: "reasoning", text: "\n" }
 								}
 
@@ -198,8 +198,8 @@ export class AnthropicVertexHandler extends BaseProvider implements SingleComple
 								yield {
 									type: "tool_call_partial",
 									index: chunk.index,
-									id: chunk.content_block!.id,
-									name: chunk.content_block!.name,
+									id: chunk.content_block.id,
+									name: chunk.content_block.name,
 									arguments: undefined,
 								}
 								break
@@ -209,9 +209,9 @@ export class AnthropicVertexHandler extends BaseProvider implements SingleComple
 						break
 					}
 					case "content_block_delta": {
-						switch (chunk.delta!.type) {
+						switch (chunk.delta.type) {
 							case "text_delta": {
-								yield { type: "text", text: chunk.delta!.text }
+								yield { type: "text", text: chunk.delta.text }
 								break
 							}
 							case "thinking_delta": {

src/api/providers/anthropic-vertex.ts

@@ -32,7 +32,7 @@ import {
 // Pre-sorted list of known Anthropic model IDs (lowercased) by length (descending) for case-insensitive substring matching.
 const ANTHROPIC_MODEL_IDS_SORTED_LOWER = (Object.keys(anthropicModels) as AnthropicModelId[])
 	.map((id) => id.toLowerCase())
-	.sort((a, b) => b.length - a.length) as string[]
+	.sort((a, b) => b.length - a.length)
 
 // Original-case mapping: lowercase key → original AnthropicModelId for lookup.
 const ANTHROPIC_MODEL_ID_LOWER_TO_ORIGINAL = Object.fromEntries(
@@ -405,7 +405,7 @@ export class AnthropicHandler extends BaseProvider implements SingleCompletionHa
 			return anthropicModels[anthropicDefaultModelId]
 		}
 
-		const originalId = ANTHROPIC_MODEL_ID_LOWER_TO_ORIGINAL[matchedLower] as AnthropicModelId
+		const originalId = ANTHROPIC_MODEL_ID_LOWER_TO_ORIGINAL[matchedLower]
 		return anthropicModels[originalId]
 	}
 

src/api/providers/anthropic.ts

@@ -9,7 +9,6 @@ import {
 	providerIdentifiers,
 	type ModelInfo,
 	type ModelRecord,
-	type NanoGptRoutingPreference,
 	type ReasoningEffortExtended,
 } from "@roo-code/types"
 
@@ -115,10 +114,7 @@ export class NanoGptHandler extends RouterProvider implements SingleCompletionHa
 	}
 
 	private getRequestModelId(canonicalModelId: string): string {
-		return applyNanoGptRoutingPreference(
-			canonicalModelId,
-			this.options.nanoGptRoutingPreference as NanoGptRoutingPreference | undefined,
-		)
+		return applyNanoGptRoutingPreference(canonicalModelId, this.options.nanoGptRoutingPreference)
 	}
 
 	private createSafeError(operation: string, error: unknown): Error {

src/api/providers/nanogpt.ts

@@ -627,7 +627,7 @@ export class OpenAiCodexHandler extends BaseProvider implements SingleCompletion
 						if (block.type === "text") {
 							content.push({ type: "input_text", text: block.text })
 						} else if (block.type === "image") {
-							const image = block as Anthropic.Messages.ImageBlockParam
+							const image = block
 							if (image.source.type === "base64") {
 								const imageUrl = `data:${image.source.media_type};base64,${image.source.data}`
 								content.push({ type: "input_image", image_url: imageUrl })

src/api/providers/openai-codex.ts

@@ -145,8 +145,7 @@ export class OpenAiNativeHandler extends BaseProvider implements SingleCompletio
 			usage.cache_read_input_tokens ?? usage.cache_read_tokens ?? usage.cached_tokens ?? cachedFromDetails ?? 0
 
 		// Resolve effective tier: prefer actual tier from response; otherwise requested tier
-		const effectiveTier =
-			this.lastServiceTier || (this.options.openAiNativeServiceTier as ServiceTier | undefined) || undefined
+		const effectiveTier = this.lastServiceTier || this.options.openAiNativeServiceTier || undefined
 		const effectiveInfo = this.applyServiceTierPricing(model.info, effectiveTier)
 
 		// Pass total input tokens directly to calculateApiCostOpenAI
@@ -486,7 +485,7 @@ export class OpenAiNativeHandler extends BaseProvider implements SingleCompletio
 						if (block.type === "text") {
 							content.push({ type: "input_text", text: block.text })
 						} else if (block.type === "image") {
-							const image = block as Anthropic.Messages.ImageBlockParam
+							const image = block
 							if (image.source.type === "base64") {
 								const imageUrl = `data:${image.source.media_type};base64,${image.source.data}`
 								content.push({ type: "input_image", image_url: imageUrl })
@@ -1551,7 +1550,7 @@ export class OpenAiNativeHandler extends BaseProvider implements SingleCompletio
 
 			// Include text.verbosity only when the model explicitly supports it
 			if (model.info.supportsVerbosity === true) {
-				requestBody.text = { verbosity: (verbosity || "medium") as VerbosityLevel }
+				requestBody.text = { verbosity: verbosity || "medium" }
 			}
 
 			// Enable extended prompt cache retention for eligible models

src/api/providers/openai-native.ts

@@ -62,6 +62,61 @@ export class XAIHandler extends BaseProvider implements SingleCompletionHandler
 		return { id, info, ...params }
 	}
 
+	/**
+	 * Map a Chat Completions tool choice to the Responses API shape so TypeScript
+	 * validates the provider payload (the APIs use different object forms for the
+	 * named-tool choices: Chat Completions nests the name under `function`/`custom`,
+	 * Responses API puts it at the top level). String options (auto/required/none)
+	 * are identical in both APIs and pass through unchanged. `allowed_tools`
+	 * entries keep their allowlist mode, but Chat Completions function references
+	 * ({ type: "function", function: { name } }) are flattened to the Responses
+	 * API shape ({ type: "function", name }); other entry types pass through
+	 * unchanged.
+	 */
+	private mapToolChoice(
+		toolChoice: NonNullable<OpenAI.Chat.ChatCompletionCreateParams["tool_choice"]>,
+	): OpenAI.Responses.ResponseCreateParamsStreaming["tool_choice"] {
+		if (typeof toolChoice === "string") {
+			return toolChoice
+		}
+		switch (toolChoice.type) {
+			case "function":
+				return { type: "function", name: toolChoice.function.name }
+			case "custom":
+				return { type: "custom", name: toolChoice.custom.name }
+			case "allowed_tools":
+				return {
+					type: "allowed_tools",
+					mode: toolChoice.allowed_tools.mode,
+					tools: toolChoice.allowed_tools.tools.map((entry) => {
+						// Chat Completions allowlist entries nest the function reference
+						// ({ type: "function", function: { name } }); the Responses API
+						// expects the name at the top level ({ type: "function", name }).
+						// The Chat Completions type allows open records, so a function
+						// entry can arrive malformed (missing or non-string name).
+						// Forwarding it unchanged would send the nested Chat Completions
+						// shape to the Responses API, which cannot express that allowlist
+						// entry, and how xAI handles the malformed payload is unspecified;
+						// reject it at the boundary instead.
+						if (entry["type"] === "function") {
+							const functionRef = entry["function"]
+							const name =
+								functionRef != null && typeof functionRef === "object"
+									? (functionRef as Record<string, unknown>)["name"]
+									: undefined
+							if (typeof name !== "string") {
+								throw new Error(
+									'xAI: allowed_tools entry of type "function" is missing a valid function name',
+								)
+							}
+							return { type: "function", name }
+						}
+						return entry
+					}),
+				}
+		}
+	}
+
 	/**
 	 * Convert tools from OpenAI Chat Completions format to Responses API format.
 	 * Chat Completions: { type: "function", function: { name, description, parameters } }
@@ -101,18 +156,11 @@ export class XAIHandler extends BaseProvider implements SingleCompletionHandler
 		// Convert directly from Anthropic format to Responses API input format
 		const input = convertToResponsesApiInput(messages)
 		const responseTools = this.mapResponseTools(metadata?.tools)
-
-		// Bridge the external abort signal from request metadata into a per-request
-		// controller so the SDK call is cancelled when the owning request is aborted
-		// (or when the signal is already aborted). Without an external signal the
-		// client-level timeout configured in the constructor remains the only
-		// cancellation mechanism, preserving the existing behavior.
-		const externalAbortSignal = metadata?.abortSignal
-		const { signal: abortSignal, dispose: removeExternalAbortListener } =
-			bridgeExternalAbortSignal(externalAbortSignal)
+		const toolChoice = metadata?.tool_choice
+		const parallelToolCalls = metadata?.parallelToolCalls
 
 		// Build request options
-		const requestBody: Record<string, any> = {
+		const requestBody: OpenAI.Responses.ResponseCreateParamsStreaming = {
 			model: model.id,
 			instructions: systemPrompt,
 			input: input,
@@ -121,19 +169,16 @@ export class XAIHandler extends BaseProvider implements SingleCompletionHandler
 			include: ["reasoning.encrypted_content"],
 		}
 
-		if (model.maxTokens) {
-			requestBody.max_output_tokens = model.maxTokens
-		}
-
-		if (model.temperature !== undefined) {
-			requestBody.temperature = model.temperature
-		}
+		// Model params are always resolved by getModel(); send them unconditionally.
+		requestBody.max_output_tokens = model.maxTokens
+		requestBody.temperature = model.temperature
 
 		if (responseTools) {
 			requestBody.tools = responseTools
-			// Cast tool_choice since metadata uses Chat Completions types but Responses API has its own type
-			requestBody.tool_choice = (metadata?.tool_choice ?? "auto") as any
-			requestBody.parallel_tool_calls = metadata?.parallelToolCalls ?? true
+			// Metadata carries a Chat Completions tool choice; the Responses API
+			// uses its own shape, so map it explicitly instead of casting.
+			requestBody.tool_choice = this.mapToolChoice(toolChoice === undefined ? "auto" : toolChoice)
+			requestBody.parallel_tool_calls = parallelToolCalls ?? true
 		}
 
 		// Pass reasoning effort for models that support it (e.g., grok-4.5, grok-3-mini).
@@ -143,11 +188,19 @@ export class XAIHandler extends BaseProvider implements SingleCompletionHandler
 			requestBody.reasoning = { effort: model.reasoning.reasoning_effort }
 		}
 
+		// Bridge the external abort signal only after every throw-prone part of the request
+		// construction (notably mapToolChoice, which rejects malformed allowed_tools entries)
+		// has run: the bridge's cleanup covers the request below, not construction failures,
+		// so registering earlier would leak a listener on metadata.abortSignal.
+		const externalAbortSignal = metadata?.abortSignal
+		const { signal: abortSignal, dispose: removeExternalAbortListener } =
+			bridgeExternalAbortSignal(externalAbortSignal)
+
 		try {
 			let stream: AsyncIterable<any>
 			try {
 				stream = (await this.client.responses.create(
-					{ ...requestBody, stream: true } as any,
+					requestBody,
 					abortSignal ? { signal: abortSignal } : undefined,
 				)) as unknown as AsyncIterable<any>
 			} catch (error) {

src/api/providers/xai.ts

@@ -137,7 +137,7 @@ export function getModelParams({
 		// Here we simply propagate the resolved effort into the params, while
 		// still treating "disable" as an omission.
 		if (effort && effort !== "disable") {
-			reasoningEffort = effort as ReasoningEffortExtended
+			reasoningEffort = effort
 		}
 	}
 

src/api/transform/model-params.ts

@@ -465,7 +465,7 @@ export function convertToOpenAiMessages(
 						] as OpenAI.Chat.ChatCompletionToolMessageParam
 						if (lastToolMessage?.role === "tool") {
 							const additionalText = filteredNonToolMessages
-								.map((part) => sanitizeSurrogates((part as Anthropic.TextBlockParam).text))
+								.map((part) => sanitizeSurrogates(part.text))
 								.join("\n")
 							lastToolMessage.content = `${lastToolMessage.content}\n\n${additionalText}`
 						}

src/api/transform/openai-format.ts

@@ -63,7 +63,7 @@ export const getOpenRouterReasoning = ({
 		? { max_tokens: reasoningBudget }
 		: shouldUseReasoningEffort({ model, settings })
 			? reasoningEffort && reasoningEffort !== "disable"
-				? { effort: reasoningEffort as ReasoningEffortExtended }
+				? { effort: reasoningEffort }
 				: undefined
 			: undefined
 
@@ -185,8 +185,7 @@ export const getGeminiReasoning = ({
 	// We intentionally ignore enableReasoningEffort here so that explicitly chosen
 	// efforts in the UI (e.g. "High" for gemini-3-pro-preview) always translate
 	// into a thinkingConfig, regardless of legacy boolean flags.
-	const selectedEffort = (settings.reasoningEffort ?? model.reasoningEffort) as
-		ReasoningEffortExtended | "disable" | undefined
+	const selectedEffort = settings.reasoningEffort ?? model.reasoningEffort
 
 	// Respect "off" / unset semantics from the effort selector itself.
 	if (!selectedEffort || selectedEffort === "disable") {