feat(gateway): add verbosity param for gpt-5.6 models

Support OpenAI's verbosity parameter (low/medium/high) end to end:

- accept top-level verbosity in /v1/chat/completions and
  text.verbosity in /v1/responses
- validate against a new verbosity capability flag on provider
  mappings (400 for unsupported models)
- forward as text.verbosity on the Responses API and top-level
  verbosity on Chat Completions; strip it when auto routing or
  retry fallback lands on a mapping without support
- enable the flag on the gpt-5.6-sol/terra/luna OpenAI mappings

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: steebchen

apps/gateway/src/chat/chat.ts

@@ -1453,6 +1453,7 @@ chat.openapi(completions, async (c) => {
 		sensitive_word_check,
 		image_config,
 		effort,
+		verbosity,
 		service_tier,
 		web_search,
 		plugins,
@@ -2498,6 +2499,7 @@ chat.openapi(completions, async (c) => {
 			response_format,
 			reasoning_effort,
 			reasoning_max_tokens,
+			verbosity,
 			tools,
 			tool_choice,
 			webSearchTool,
@@ -6109,6 +6111,7 @@ chat.openapi(completions, async (c) => {
 				service_tier,
 				configIndex,
 			),
+			verbosity,
 		);
 	} catch (e) {
 		// Surface typed pre-upstream input errors in the activity feed as a
@@ -6316,6 +6319,7 @@ chat.openapi(completions, async (c) => {
 				n,
 				providerCacheControlEnabled,
 				service_tier,
+				verbosity,
 			},
 		);
 	}

apps/gateway/src/chat/schemas/completions.ts

@@ -304,6 +304,16 @@ export const completionsRequestSchema = z.object({
 				"Controls the computational effort for supported models (currently only claude-opus-4-5-20251101)",
 			example: "medium",
 		}),
+	verbosity: z
+		.enum(["low", "medium", "high"])
+		.nullable()
+		.optional()
+		.transform((val) => (val === null ? undefined : val))
+		.openapi({
+			description:
+				"Controls how detailed the model's responses are. Only supported by OpenAI GPT-5.6 and later models; requests to models without verbosity support return a 400 error.",
+			example: "low",
+		}),
 	service_tier: z
 		.enum(["auto", "default", "flex", "priority"])
 		.optional()

apps/gateway/src/chat/tools/resolve-provider-context.ts

@@ -140,6 +140,7 @@ export interface ProviderContextOptions {
 	n?: number;
 	providerCacheControlEnabled: boolean;
 	service_tier?: "auto" | "default" | "flex" | "priority";
+	verbosity?: "low" | "medium" | "high";
 }
 
 interface ProjectInfo {
@@ -643,6 +644,7 @@ export async function resolveProviderContext(
 		options.providerCacheControlEnabled,
 		options.n,
 		options.service_tier,
+		options.verbosity,
 	);
 
 	// Post-validation of max_tokens in request body

apps/gateway/src/chat/tools/validate-model-capabilities.spec.ts

@@ -132,6 +132,50 @@ describe("validateModelCapabilities - vision", () => {
 	});
 });
 
+describe("validateModelCapabilities - verbosity", () => {
+	const verbosityModel = getModel("gpt-5.6-terra");
+
+	it("allows verbosity for models that support it", () => {
+		expect(() =>
+			validateModelCapabilities(verbosityModel, "gpt-5.6-terra", undefined, {
+				verbosity: "low",
+			}),
+		).not.toThrow();
+	});
+
+	it("rejects verbosity for models without support", () => {
+		expect(() =>
+			validateModelCapabilities(noVisionModel, "deepseek-v4-flash", undefined, {
+				verbosity: "low",
+			}),
+		).toThrow(HTTPException);
+	});
+
+	it("skips the verbosity check for auto and custom models", () => {
+		expect(() =>
+			validateModelCapabilities(noVisionModel, "auto", undefined, {
+				verbosity: "low",
+			}),
+		).not.toThrow();
+		expect(() =>
+			validateModelCapabilities(noVisionModel, "custom", undefined, {
+				verbosity: "low",
+			}),
+		).not.toThrow();
+	});
+
+	it("does not check verbosity when it is not specified", () => {
+		expect(() =>
+			validateModelCapabilities(
+				noVisionModel,
+				"deepseek-v4-flash",
+				undefined,
+				{},
+			),
+		).not.toThrow();
+	});
+});
+
 describe("validateModelCapabilities - custom providers", () => {
 	it("skips all capability checks when the provider is custom", () => {
 		expect(() =>

apps/gateway/src/chat/tools/validate-model-capabilities.ts

@@ -17,6 +17,7 @@ export interface ValidateModelCapabilitiesOptions {
 	};
 	reasoning_effort?: string;
 	reasoning_max_tokens?: number;
+	verbosity?: string;
 	tools?: unknown[];
 	tool_choice?: unknown;
 	webSearchTool?: WebSearchTool;
@@ -42,6 +43,7 @@ export function validateModelCapabilities(
 		response_format,
 		reasoning_effort,
 		reasoning_max_tokens,
+		verbosity,
 		tools,
 		tool_choice,
 		webSearchTool,
@@ -189,6 +191,30 @@ export function validateModelCapabilities(
 		}
 	}
 
+	// Check if verbosity is specified but model doesn't support it
+	// Skip this check for "auto" and "custom" models as they will be resolved dynamically
+	if (
+		verbosity !== undefined &&
+		requestedModel !== "auto" &&
+		requestedModel !== "custom"
+	) {
+		const providersToCheck = requestedProvider
+			? modelInfo.providers.filter(
+					(p) => (p as ProviderModelMapping).providerId === requestedProvider,
+				)
+			: modelInfo.providers;
+
+		const supportsVerbosity = providersToCheck.some(
+			(provider) => (provider as ProviderModelMapping).verbosity === true,
+		);
+
+		if (!supportsVerbosity) {
+			throw new HTTPException(400, {
+				message: `Model ${requestedModel} does not support the verbosity parameter. Remove the verbosity parameter or use a model that supports it (OpenAI GPT-5.6 and later).`,
+			});
+		}
+	}
+
 	// Check if reasoning.max_tokens is specified but model doesn't support it
 	// Skip this check for "auto" and "custom" models as they will be resolved dynamically
 	if (

apps/gateway/src/responses/responses.ts

@@ -324,6 +324,9 @@ responses.post("/", async (c) => {
 	if (req.reasoning?.effort) {
 		chatRequest.reasoning_effort = req.reasoning.effort;
 	}
+	if (req.text?.verbosity !== undefined) {
+		chatRequest.verbosity = req.text.verbosity;
+	}
 	if (req.prompt_cache_key !== undefined) {
 		chatRequest.prompt_cache_key = req.prompt_cache_key;
 	}

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

@@ -51,6 +51,7 @@ async function prepareOpenAITextRequest(options: {
 	promptCacheKey?: string;
 	promptCacheRetention?: "in_memory" | "24h";
 	serviceTier?: "flex" | "priority";
+	verbosity?: "low" | "medium" | "high";
 }) {
 	const model = options.model ?? "gpt-5.5";
 	return await prepareRequestBody(
@@ -85,6 +86,7 @@ async function prepareOpenAITextRequest(options: {
 		true,
 		undefined,
 		options.serviceTier,
+		options.verbosity,
 	);
 }
 
@@ -622,6 +624,86 @@ describe("prepareRequestBody - OpenAI service tiers", () => {
 	});
 });
 
+describe("prepareRequestBody - verbosity", () => {
+	test("forwards verbosity to gpt-5.6 chat completions", async () => {
+		const requestBody = (await prepareOpenAITextRequest({
+			model: "gpt-5.6-terra",
+			verbosity: "low",
+		})) as { verbosity?: string };
+
+		expect(requestBody.verbosity).toBe("low");
+	});
+
+	test("forwards verbosity as text.verbosity to gpt-5.6 Responses API", async () => {
+		const requestBody = (await prepareOpenAITextRequest({
+			model: "gpt-5.6-sol",
+			useResponsesApi: true,
+			verbosity: "high",
+		})) as { text?: { verbosity?: string } };
+
+		expect(requestBody.text?.verbosity).toBe("high");
+	});
+
+	test("keeps text.format when verbosity is combined with response_format", async () => {
+		const requestBody = (await prepareRequestBody(
+			"openai",
+			"gpt-5.6-luna",
+			null,
+			"gpt-5.6-luna",
+			[{ role: "user", content: "Hello!" }],
+			false,
+			undefined,
+			undefined,
+			undefined,
+			undefined,
+			undefined,
+			{ type: "json_object" },
+			undefined,
+			undefined,
+			undefined,
+			false,
+			false,
+			20,
+			null,
+			undefined,
+			undefined,
+			undefined,
+			undefined,
+			undefined,
+			undefined,
+			true, // useResponsesApi
+			undefined,
+			undefined,
+			true,
+			undefined,
+			undefined,
+			"medium", // verbosity
+		)) as { text?: { format?: { type: string }; verbosity?: string } };
+
+		expect(requestBody.text?.format?.type).toBe("json_object");
+		expect(requestBody.text?.verbosity).toBe("medium");
+	});
+
+	test("strips verbosity for models without verbosity support", async () => {
+		const requestBody = (await prepareOpenAITextRequest({
+			model: "gpt-4o",
+			verbosity: "low",
+		})) as { verbosity?: string };
+
+		expect(requestBody.verbosity).toBeUndefined();
+	});
+
+	test("strips verbosity from the Responses API body for unsupported models", async () => {
+		const requestBody = (await prepareOpenAITextRequest({
+			model: "gpt-5.5",
+			useResponsesApi: true,
+			verbosity: "low",
+		})) as { text?: { verbosity?: string } };
+
+		expect(requestBody.text?.verbosity).toBeUndefined();
+	});
+});
+
 describe("prepareRequestBody - reasoning_effort none", () => {
 	async function prepare(options: {
 		provider: Parameters<typeof prepareRequestBody>[0];

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

@@ -891,6 +891,7 @@ export async function prepareRequestBody(
 	providerCacheControlEnabled = true,
 	n?: number,
 	service_tier?: "auto" | "default" | "flex" | "priority",
+	verbosity?: "low" | "medium" | "high",
 ): Promise<ProviderRequestBody | FormData> {
 	tools = normalizeToolParameters(tools);
 	const modelDef = models.find((m) => m.id === usedInternalModel);
@@ -928,6 +929,17 @@ export async function prepareRequestBody(
 		reasoning_effort = undefined;
 	}
 
+	// `verbosity` is only understood by OpenAI GPT-5.6+ models. Capability
+	// validation rejects unsupported pinned models upfront, but auto routing and
+	// retry fallbacks can still land on a mapping without verbosity support, so
+	// strip it here instead of forwarding an unknown parameter upstream.
+	if (
+		verbosity !== undefined &&
+		providerMappingForOptions?.verbosity !== true
+	) {
+		verbosity = undefined;
+	}
+
 	// `max` is Anthropic's top effort tier (above `xhigh`). Providers without a
 	// native `max` level treat it as an alias for `high` (e.g. OpenAI, Google,
 	// DeepSeek). Anthropic-family branches use `reasoning_effort` directly and
@@ -1632,6 +1644,13 @@ export async function prepareRequestBody(
 					}
 				}
 
+				if (verbosity !== undefined) {
+					responsesBody.text = {
+						...responsesBody.text,
+						verbosity,
+					};
+				}
+
 				return responsesBody;
 			} else {
 				// Use regular chat completions format
@@ -1731,6 +1750,9 @@ export async function prepareRequestBody(
 						requestBody.reasoning_effort = genericReasoningEffort;
 					}
 				}
+				if (verbosity !== undefined) {
+					requestBody.verbosity = verbosity;
+				}
 				if (n !== undefined && n > 1) {
 					requestBody.n = n;
 				}

packages/models/src/models.ts

@@ -329,6 +329,11 @@ export interface ProviderModelMapping {
 	 * Whether this model supports reasoning mode
 	 */
 	reasoning?: boolean;
+	/**
+	 * Whether this model supports the OpenAI `verbosity` parameter
+	 * (low/medium/high response detail control, GPT-5.6 and later)
+	 */
+	verbosity?: boolean;
 	/**
 	 * Whether the provider returns reasoning inside tagged content (e.g. <think>...</think>)
 	 * that needs to be split into separate reasoning and content fields

packages/models/src/models/openai.ts

@@ -1751,6 +1751,7 @@ export const openaiModels = [
 				webSearchPrice: "0.01",
 				reasoning: true,
 				reasoningOutput: "omit",
+				verbosity: true,
 				supportsResponsesApi: true,
 				jsonOutputSchema: true,
 				supportedParameters: [
@@ -1759,6 +1760,7 @@ export const openaiModels = [
 					"frequency_penalty",
 					"presence_penalty",
 					"response_format",
+					"verbosity",
 				],
 				jsonOutput: true,
 			},
@@ -1790,6 +1792,7 @@ export const openaiModels = [
 				webSearchPrice: "0.01",
 				reasoning: true,
 				reasoningOutput: "omit",
+				verbosity: true,
 				supportsResponsesApi: true,
 				jsonOutputSchema: true,
 				supportedParameters: [
@@ -1798,6 +1801,7 @@ export const openaiModels = [
 					"frequency_penalty",
 					"presence_penalty",
 					"response_format",
+					"verbosity",
 				],
 				jsonOutput: true,
 			},
@@ -1829,6 +1833,7 @@ export const openaiModels = [
 				webSearchPrice: "0.01",
 				reasoning: true,
 				reasoningOutput: "omit",
+				verbosity: true,
 				supportsResponsesApi: true,
 				jsonOutputSchema: true,
 				supportedParameters: [
@@ -1837,6 +1842,7 @@ export const openaiModels = [
 					"frequency_penalty",
 					"presence_penalty",
 					"response_format",
+					"verbosity",
 				],
 				jsonOutput: true,
 			},