feat: add verbosity setting for GPT-5 models

- Add VerbosityLevel type definition to model types
- Add verbosity field to ProviderSettings schema
- Create Verbosity UI component for settings
- Add verbosity labels to all localization files
- Integrate verbosity handling in model parameters transformation
- Update OpenAI native handler to support verbosity for GPT-5
- Add comprehensive tests for verbosity setting
- Update existing GPT-5 tests to use verbosity from settings

Author: daniel-lxs

packages/types/src/model.ts

@@ -10,6 +10,16 @@ export const reasoningEffortsSchema = z.enum(reasoningEfforts)
 
 export type ReasoningEffort = z.infer<typeof reasoningEffortsSchema>
 
+/**
+ * Verbosity
+ */
+
+export const verbosityLevels = ["low", "medium", "high"] as const
+
+export const verbosityLevelsSchema = z.enum(verbosityLevels)
+
+export type VerbosityLevel = z.infer<typeof verbosityLevelsSchema>
+
 /**
  * ModelParameter
  */

packages/types/src/provider-settings.ts

@@ -1,6 +1,6 @@
 import { z } from "zod"
 
-import { reasoningEffortsSchema, modelInfoSchema } from "./model.js"
+import { reasoningEffortsSchema, verbosityLevelsSchema, modelInfoSchema } from "./model.js"
 import { codebaseIndexProviderSchema } from "./codebase-index.js"
 
 /**
@@ -79,6 +79,9 @@ const baseProviderSettingsSchema = z.object({
 	reasoningEffort: reasoningEffortsSchema.optional(),
 	modelMaxTokens: z.number().optional(),
 	modelMaxThinkingTokens: z.number().optional(),
+
+	// Model verbosity.
+	verbosity: verbosityLevelsSchema.optional(),
 })
 
 // Several of the providers share common model config properties.

src/api/providers/__tests__/openai-native.spec.ts

@@ -538,16 +538,9 @@ describe("OpenAiNativeHandler", () => {
 			handler = new OpenAiNativeHandler({
 				...mockOptions,
 				apiModelId: "gpt-5-2025-08-07",
+				verbosity: "low", // Set verbosity through options
 			})
 
-			// Test that the handler has verbosity control methods
-			expect(handler.setGpt5Verbosity).toBeDefined()
-			expect(handler.getGpt5Verbosity).toBeDefined()
-
-			// Set verbosity to low
-			handler.setGpt5Verbosity("low")
-			expect(handler.getGpt5Verbosity()).toBe("low")
-
 			// Create a message to verify verbosity is passed
 			const stream = handler.createMessage(systemPrompt, messages)
 			const chunks: any[] = []
@@ -597,11 +590,10 @@ describe("OpenAiNativeHandler", () => {
 			handler = new OpenAiNativeHandler({
 				...mockOptions,
 				apiModelId: "gpt-5-2025-08-07",
+				verbosity: "high", // Set verbosity through options
+				reasoningEffort: "low", // Set reasoning effort
 			})
 
-			// Set both verbosity and reasoning effort
-			handler.setGpt5Verbosity("high")
-
 			const stream = handler.createMessage(systemPrompt, messages)
 			const chunks: any[] = []
 			for await (const chunk of stream) {
@@ -615,7 +607,7 @@ describe("OpenAiNativeHandler", () => {
 					messages: expect.any(Array),
 					stream: true,
 					stream_options: { include_usage: true },
-					reasoning_effort: "minimal", // Default for GPT-5
+					reasoning_effort: "low",
 					verbosity: "high",
 				}),
 			)

src/api/providers/openai-native.ts

@@ -8,6 +8,7 @@ import {
 	openAiNativeModels,
 	OPENAI_NATIVE_DEFAULT_TEMPERATURE,
 	type ReasoningEffort,
+	type VerbosityLevel,
 } from "@roo-code/types"
 
 import type { ApiHandlerOptions } from "../../shared/api"
@@ -24,7 +25,6 @@ import type { SingleCompletionHandler, ApiHandlerCreateMessageMetadata } from ".
 export type OpenAiNativeModel = ReturnType<OpenAiNativeHandler["getModel"]>
 
 // GPT-5 specific types for Responses API
-type Verbosity = "low" | "medium" | "high"
 type ReasoningEffortWithMinimal = ReasoningEffort | "minimal"
 
 interface GPT5ResponsesAPIParams {
@@ -34,7 +34,7 @@ interface GPT5ResponsesAPIParams {
 		effort: ReasoningEffortWithMinimal
 	}
 	text?: {
-		verbosity: Verbosity
+		verbosity: VerbosityLevel
 	}
 }
 
@@ -53,7 +53,6 @@ interface GPT5ResponseChunk {
 export class OpenAiNativeHandler extends BaseProvider implements SingleCompletionHandler {
 	protected options: ApiHandlerOptions
 	private client: OpenAI
-	private gpt5Verbosity: Verbosity = "medium" // Default verbosity for GPT-5
 
 	constructor(options: ApiHandlerOptions) {
 		super()
@@ -146,18 +145,35 @@ export class OpenAiNativeHandler extends BaseProvider implements SingleCompletio
 		systemPrompt: string,
 		messages: Anthropic.Messages.MessageParam[],
 	): ApiStream {
-		const { reasoning } = this.getModel()
+		const { reasoning, verbosity } = this.getModel()
 
-		const stream = await this.client.chat.completions.create({
+		// Prepare the request parameters
+		const params: any = {
 			model: model.id,
 			temperature: this.options.modelTemperature ?? OPENAI_NATIVE_DEFAULT_TEMPERATURE,
 			messages: [{ role: "system", content: systemPrompt }, ...convertToOpenAiMessages(messages)],
 			stream: true,
 			stream_options: { include_usage: true },
 			...(reasoning && reasoning),
-		})
+		}
 
-		yield* this.handleStreamResponse(stream, model)
+		// Add verbosity if supported (for future GPT-5 models)
+		if (verbosity && model.id.startsWith("gpt-5")) {
+			params.verbosity = verbosity
+		}
+
+		const stream = await this.client.chat.completions.create(params)
+
+		if (typeof (stream as any)[Symbol.asyncIterator] !== "function") {
+			throw new Error(
+				"OpenAI SDK did not return an AsyncIterable for streaming response. Please check SDK version and usage.",
+			)
+		}
+
+		yield* this.handleStreamResponse(
+			stream as unknown as AsyncIterable<OpenAI.Chat.Completions.ChatCompletionChunk>,
+			model,
+		)
 	}
 
 	private async *handleGpt5Message(
@@ -172,6 +188,9 @@ export class OpenAiNativeHandler extends BaseProvider implements SingleCompletio
 		// Get reasoning effort, supporting the new "minimal" option for GPT-5
 		const reasoningEffort = this.getGpt5ReasoningEffort(model)
 
+		// Get verbosity from model settings, default to "medium" if not specified
+		const verbosity = model.verbosity || "medium"
+
 		// Prepare the request parameters for Responses API
 		const params: GPT5ResponsesAPIParams = {
 			model: model.id,
@@ -182,7 +201,7 @@ export class OpenAiNativeHandler extends BaseProvider implements SingleCompletio
 				},
 			}),
 			text: {
-				verbosity: this.gpt5Verbosity,
+				verbosity: verbosity,
 			},
 		}
 
@@ -332,16 +351,6 @@ export class OpenAiNativeHandler extends BaseProvider implements SingleCompletio
 		}
 	}
 
-	// Method to set verbosity for GPT-5 models
-	setGpt5Verbosity(verbosity: Verbosity) {
-		this.gpt5Verbosity = verbosity
-	}
-
-	// Method to get current verbosity setting
-	getGpt5Verbosity(): Verbosity {
-		return this.gpt5Verbosity
-	}
-
 	private isGpt5Model(modelId: string): boolean {
 		return modelId.startsWith("gpt-5")
 	}
@@ -411,23 +420,25 @@ export class OpenAiNativeHandler extends BaseProvider implements SingleCompletio
 
 		// The o3 models are named like "o3-mini-[reasoning-effort]", which are
 		// not valid model ids, so we need to strip the suffix.
-		return { id: id.startsWith("o3-mini") ? "o3-mini" : id, info, ...params }
+		return { id: id.startsWith("o3-mini") ? "o3-mini" : id, info, ...params, verbosity: params.verbosity }
 	}
 
 	async completePrompt(prompt: string): Promise<string> {
 		try {
-			const { id, temperature, reasoning } = this.getModel()
+			const { id, temperature, reasoning, verbosity } = this.getModel()
 
-			const params: OpenAI.Chat.Completions.ChatCompletionCreateParamsNonStreaming & { verbosity?: Verbosity } = {
+			const params: OpenAI.Chat.Completions.ChatCompletionCreateParamsNonStreaming & {
+				verbosity?: VerbosityLevel
+			} = {
 				model: id,
 				messages: [{ role: "user", content: prompt }],
 				temperature,
 				...(reasoning && reasoning),
 			}
 
 			// Add verbosity for GPT-5 models
-			if (this.isGpt5Model(id)) {
-				params.verbosity = this.gpt5Verbosity
+			if (this.isGpt5Model(id) && verbosity) {
+				params.verbosity = verbosity
 			}
 
 			const response = await this.client.chat.completions.create(params as any)

src/api/transform/__tests__/model-params.spec.ts

@@ -788,4 +788,101 @@ describe("getModelParams", () => {
 			expect(result.reasoning).toBeUndefined()
 		})
 	})
+
+	describe("Verbosity settings", () => {
+		it("should include verbosity when specified in settings", () => {
+			const model: ModelInfo = {
+				...baseModel,
+			}
+
+			const result = getModelParams({
+				...openaiParams,
+				settings: { verbosity: "low" },
+				model,
+			})
+
+			expect(result.verbosity).toBe("low")
+		})
+
+		it("should handle medium verbosity", () => {
+			const model: ModelInfo = {
+				...baseModel,
+			}
+
+			const result = getModelParams({
+				...openaiParams,
+				settings: { verbosity: "medium" },
+				model,
+			})
+
+			expect(result.verbosity).toBe("medium")
+		})
+
+		it("should handle high verbosity", () => {
+			const model: ModelInfo = {
+				...baseModel,
+			}
+
+			const result = getModelParams({
+				...openaiParams,
+				settings: { verbosity: "high" },
+				model,
+			})
+
+			expect(result.verbosity).toBe("high")
+		})
+
+		it("should return undefined verbosity when not specified", () => {
+			const model: ModelInfo = {
+				...baseModel,
+			}
+
+			const result = getModelParams({
+				...openaiParams,
+				settings: {},
+				model,
+			})
+
+			expect(result.verbosity).toBeUndefined()
+		})
+
+		it("should include verbosity alongside reasoning settings", () => {
+			const model: ModelInfo = {
+				...baseModel,
+				supportsReasoningEffort: true,
+			}
+
+			const result = getModelParams({
+				...openaiParams,
+				settings: {
+					reasoningEffort: "high",
+					verbosity: "low",
+				},
+				model,
+			})
+
+			expect(result.reasoningEffort).toBe("high")
+			expect(result.verbosity).toBe("low")
+			expect(result.reasoning).toEqual({ reasoning_effort: "high" })
+		})
+
+		it("should include verbosity with reasoning budget models", () => {
+			const model: ModelInfo = {
+				...baseModel,
+				supportsReasoningBudget: true,
+			}
+
+			const result = getModelParams({
+				...anthropicParams,
+				settings: {
+					enableReasoningEffort: true,
+					verbosity: "high",
+				},
+				model,
+			})
+
+			expect(result.verbosity).toBe("high")
+			expect(result.reasoningBudget).toBe(8192) // Default thinking tokens
+		})
+	})
 })

src/api/transform/model-params.ts

@@ -1,4 +1,9 @@
-import { type ModelInfo, type ProviderSettings, ANTHROPIC_DEFAULT_MAX_TOKENS } from "@roo-code/types"
+import {
+	type ModelInfo,
+	type ProviderSettings,
+	type VerbosityLevel,
+	ANTHROPIC_DEFAULT_MAX_TOKENS,
+} from "@roo-code/types"
 
 import {
 	DEFAULT_HYBRID_REASONING_MODEL_MAX_TOKENS,
@@ -35,6 +40,7 @@ type BaseModelParams = {
 	temperature: number | undefined
 	reasoningEffort: "low" | "medium" | "high" | undefined
 	reasoningBudget: number | undefined
+	verbosity: VerbosityLevel | undefined
 }
 
 type AnthropicModelParams = {
@@ -76,6 +82,7 @@ export function getModelParams({
 		modelMaxThinkingTokens: customMaxThinkingTokens,
 		modelTemperature: customTemperature,
 		reasoningEffort: customReasoningEffort,
+		verbosity: customVerbosity,
 	} = settings
 
 	// Use the centralized logic for computing maxTokens
@@ -89,6 +96,7 @@ export function getModelParams({
 	let temperature = customTemperature ?? defaultTemperature
 	let reasoningBudget: ModelParams["reasoningBudget"] = undefined
 	let reasoningEffort: ModelParams["reasoningEffort"] = undefined
+	let verbosity: VerbosityLevel | undefined = customVerbosity
 
 	if (shouldUseReasoningBudget({ model, settings })) {
 		// Check if this is a Gemini 2.5 Pro model
@@ -123,7 +131,7 @@ export function getModelParams({
 		reasoningEffort = customReasoningEffort ?? model.reasoningEffort
 	}
 
-	const params: BaseModelParams = { maxTokens, temperature, reasoningEffort, reasoningBudget }
+	const params: BaseModelParams = { maxTokens, temperature, reasoningEffort, reasoningBudget, verbosity }
 
 	if (format === "anthropic") {
 		return {

webview-ui/src/components/settings/ApiOptions.tsx

@@ -91,6 +91,7 @@ import { inputEventTransform, noTransform } from "./transforms"
 import { ModelInfoView } from "./ModelInfoView"
 import { ApiErrorMessage } from "./ApiErrorMessage"
 import { ThinkingBudget } from "./ThinkingBudget"
+import { Verbosity } from "./Verbosity"
 import { DiffSettingsControl } from "./DiffSettingsControl"
 import { TodoListSettingsControl } from "./TodoListSettingsControl"
 import { TemperatureControl } from "./TemperatureControl"
@@ -616,6 +617,12 @@ const ApiOptions = ({
 				modelInfo={selectedModelInfo}
 			/>
 
+			<Verbosity
+				apiConfiguration={apiConfiguration}
+				setApiConfigurationField={setApiConfigurationField}
+				modelInfo={selectedModelInfo}
+			/>
+
 			{!fromWelcomeView && (
 				<Collapsible open={isAdvancedSettingsOpen} onOpenChange={setIsAdvancedSettingsOpen}>
 					<CollapsibleTrigger className="flex items-center gap-1 w-full cursor-pointer hover:opacity-80 mb-2">