@gitkraken/core-gitlens 0.5.110 → 0.5.111

package/src/plus/ai/providers/openAICompatibleProviderBase.ts

@@ -1,13 +1,30 @@
 import { CancellationError, isCancellationError } from '../../../utils/cancellation.js';
 import { uuid } from '../../../utils/crypto.js';
-import { getLoggableName } from '../../../utils/logger.js';
+import { getLoggableName, Logger } from '../../../utils/logger.js';
 import { maybeStartScopedLogger } from '../../../utils/logger.scoped.js';
 import type { AIProviders } from '../constants.js';
 import { AIError, AIErrorReason } from '../errors.js';
 import type { AIActionType, AIModel, AIProviderDescriptor } from '../models/model.js';
-import type { AIChatMessage, AIChatMessageRole, AIProvider, AIProviderResponse } from '../models/provider.js';
+import type {
+	AIChatMessage,
+	AIChatMessageRole,
+	AIFinishReason,
+	AIProvider,
+	AIProviderResponse,
+	AIResponseFormat,
+	AIToolCall,
+	AIToolDefinition,
+	JSONSchema,
+} from '../models/provider.js';
 import { getActionName, getReducedMaxInputTokens, getValidatedTemperature } from '../utils/ai.utils.js';
 import type { AIProviderContext } from './context.js';
+import { isResponseFormatRejected, rememberResponseFormatRejection } from './responseFormatCache.js';
+
+// Native-format rejection wording varies by provider ("response_format", "structured outputs",
+// Gemini's "Json mode is not enabled", and its OpenAI-compat layer's `generation_config.response_schema`
+// path in INVALID_ARGUMENT bodies, ...)
+const formatRejectionRegex =
+	/response[_ ]?(?:format|schema)|structured[_ ]?output|output_config|json_schema|json[_ ]?mode/i;
 
 export abstract class OpenAICompatibleProviderBase<T extends AIProviders> implements AIProvider<T> {
 	constructor(protected readonly context: AIProviderContext) {}
@@ -54,6 +71,14 @@ export abstract class OpenAICompatibleProviderBase<T extends AIProviders> implem
 
 	abstract getModels(): Promise<readonly AIModel<T>[]>;
 
+	protected isResponseFormatSessionRejected(model: AIModel<T>, responseFormat: AIResponseFormat): boolean {
+		return isResponseFormatRejected(this.id, model, responseFormat);
+	}
+
+	protected rememberResponseFormatRejection(model: AIModel<T>, responseFormat: AIResponseFormat): void {
+		rememberResponseFormatRejection(this.id, model, responseFormat);
+	}
+
 	protected abstract getUrl(_model: AIModel<T>): string | undefined;
 
 	protected getHeaders<TAction extends AIActionType>(
@@ -76,11 +101,13 @@ export abstract class OpenAICompatibleProviderBase<T extends AIProviders> implem
 		action: TAction,
 		model: AIModel<T>,
 		apiKey: string,
-		getMessages: (maxInputTokens: number, retries: number) => Promise<AIChatMessage[]>,
+		getMessages: (maxInputTokens: number, retries: number) => Promise<AIChatMessage<AIChatMessageRole>[]>,
 		options: {
 			signal: AbortSignal;
 			modelOptions?: { outputTokens?: number; temperature?: number };
 			conversationId?: string;
+			responseFormat?: AIResponseFormat;
+			tools?: readonly AIToolDefinition[];
 		},
 	): Promise<AIProviderResponse<void> | undefined> {
 		using scope = maybeStartScopedLogger(`${getLoggableName(this)}.sendRequest`);
@@ -92,8 +119,10 @@ export abstract class OpenAICompatibleProviderBase<T extends AIProviders> implem
 				apiKey,
 				getMessages,
 				options.modelOptions,
+				options.responseFormat,
 				options.signal,
 				options.conversationId,
+				options.tools,
 			);
 			return result;
 		} catch (ex) {
@@ -116,18 +145,27 @@ export abstract class OpenAICompatibleProviderBase<T extends AIProviders> implem
 		action: TAction,
 		model: AIModel<T>,
 		apiKey: string,
-		messages: (maxInputTokens: number, retries: number) => Promise<AIChatMessage[]>,
+		messages: (maxInputTokens: number, retries: number) => Promise<AIChatMessage<AIChatMessageRole>[]>,
 		modelOptions?: { outputTokens?: number; temperature?: number },
+		responseFormat?: AIResponseFormat,
 		signal?: AbortSignal,
 		conversationId?: string,
+		tools?: readonly AIToolDefinition[],
 	): Promise<AIProviderResponse<void>> {
 		let retries = 0;
 		let maxInputTokens = model.maxTokens.input;
+		// Latched when the provider rejects the `tools` field, so the retry drops tools entirely and
+		// the caller can stop offering them for the rest of the session.
+		let toolsRejected = false;
 
 		while (true) {
+			const useTools = tools?.length && !toolsRejected ? tools : undefined;
+			const { messages: msgs, system } = this.extractSystemPrompt(await messages(maxInputTokens, retries));
 			const request: ChatCompletionRequest = {
 				model: model.id,
-				...this.extractSystemPrompt(await messages(maxInputTokens, retries)),
+				messages: this.serializeMessages(msgs),
+				...(system != null ? { system: system } : undefined),
+				...(useTools != null ? this.serializeTools(useTools) : undefined),
 				stream: false,
 				max_completion_tokens: model.maxTokens.output
 					? Math.min(modelOptions?.outputTokens ?? Infinity, model.maxTokens.output)
@@ -138,22 +176,98 @@ export abstract class OpenAICompatibleProviderBase<T extends AIProviders> implem
 					this.context.defaultTemperature,
 				),
 			};
+			if (
+				responseFormat != null &&
+				!this.isResponseFormatSessionRejected(model, responseFormat) &&
+				this.supportsResponseFormat(model)
+			) {
+				this.applyResponseFormat(request, model, responseFormat);
+			}
+
+			let rsp = await this.fetchCore(action, model, apiKey, request, signal, conversationId);
+			// Read once and forward to `handleFetchFailure` so the error body isn't decoded twice
+			let errorBody: string | undefined;
+			if (!rsp.ok && (request.response_format != null || request.output_config != null)) {
+				// If the native format was rejected (stale model snapshot, older Azure api-version,
+				// proxy converter gaps, OpenRouter's require_parameters matching no endpoint), strip
+				// it and resend the same request — the prompt still describes the JSON. Resending
+				// directly avoids re-running the (non-idempotent) prompt build and its side effects
+				// Leave it `undefined` (not '') when the read fails, so `handleFetchFailure` falls
+				// back to reading the still-unconsumed response instead of parsing an empty string
+				errorBody = await rsp
+					.clone()
+					.text()
+					.catch(() => undefined);
+				if (this.isResponseFormatRejection(rsp.status, errorBody ?? '')) {
+					Logger.warn(
+						`(${this.name}) ${model.id}: native response format was rejected (${rsp.status}); retrying without it`,
+					);
+					const rejected = responseFormat;
+					responseFormat = undefined;
+					delete request.response_format;
+					delete request.output_config;
+					delete request.provider;
+					rsp = await this.fetchCore(action, model, apiKey, request, signal, conversationId);
+					errorBody = undefined;
+					// Memoize only when stripping fixed it — proof the format (not e.g. an oversized
+					// prompt behind the same wrapped status) caused the failure
+					if (rsp.ok && rejected != null) {
+						this.rememberResponseFormatRejection(model, rejected);
+					}
+				}
+			}
 
-			const rsp = await this.fetchCore(action, model, apiKey, request, signal, conversationId);
 			if (!rsp.ok) {
-				const result = await this.handleFetchFailure(rsp, action, model, retries, maxInputTokens);
+				const result = await this.handleFetchFailure(
+					rsp,
+					action,
+					model,
+					retries,
+					maxInputTokens,
+					errorBody,
+					useTools != null,
+				);
 				if (result.retry) {
 					maxInputTokens = result.maxInputTokens;
+					if (result.withoutTools) {
+						// Say so explicitly: the caller degrades silently by design, so the only remaining
+						// evidence would be `toolCalls=0` — indistinguishable from a model that simply chose
+						// not to consult the repository. That ambiguity is the whole reason to log it.
+						Logger.warn(
+							`(${this.name}) ${model.id}: tools were rejected (${rsp.status}); retrying without them — repository consultation is unavailable for the rest of this session`,
+						);
+						toolsRejected = true;
+					}
 					retries++;
 					continue;
 				}
 			}
 
 			const data: ChatCompletionResponse = (await rsp.json()) as ChatCompletionResponse;
+			const toolCalls = this.parseToolCalls(data);
+			// A tool-call-only turn carries no text, which `extractContent` correctly reports as '' — it
+			// selects the text block by type, so a `tool_use` (or thinking) block is never mistaken for one.
+			// The calls ride alongside on `toolCalls` below.
+			const content = this.extractContent(data);
+			// Some providers/proxies (e.g. OpenRouter) report upstream failures as an OK response
+			// carrying an error envelope and no choices — surface that instead of empty content
+			if (!content && toolCalls == null && data.error != null) {
+				if (data.error.code === 429 || data.error.code === '429') {
+					throw new AIError(
+						AIErrorReason.RateLimitOrFundsExceeded,
+						new Error(`(${this.name}) ${data.error.message || 'Rate limit exceeded'}`),
+					);
+				}
+				throw new Error(`(${this.name}) ${data.error.message || 'Unknown error'}`);
+			}
+
 			const result: AIProviderResponse<void> = {
 				id: data.id ?? uuid(),
-				content: data.choices?.[0].message.content?.trim() ?? data.content?.[0]?.text?.trim() ?? '',
+				content: content,
+				finishReason: this.extractFinishReason(data),
 				model: model,
+				...(toolCalls?.length ? { toolCalls: toolCalls } : undefined),
+				...(toolsRejected ? { toolsRejected: true } : undefined),
 				usage: {
 					promptTokens: data.usage?.prompt_tokens ?? data.usage?.input_tokens,
 					completionTokens: data.usage?.completion_tokens ?? data.usage?.output_tokens,
@@ -185,13 +299,196 @@ export abstract class OpenAICompatibleProviderBase<T extends AIProviders> implem
 		return { messages: messages };
 	}
 
+	/** Whether the given model accepts a native response-format/schema field; when false the
+	 *  prompt's JSON description is the only format control (the request is unchanged).
+	 *  Dynamic-catalog providers (GitKraken, OpenRouter) populate
+	 *  {@link AIModel.supportsStructuredOutputs}; static providers override with id-based gates */
+	protected supportsResponseFormat(model: AIModel<T>): boolean {
+		return model.supportsStructuredOutputs ?? true;
+	}
+
+	/**
+	 * Whether a failed response reads as a rejection of the `tools` field rather than a problem with the
+	 * prompt — the trigger for one retry without tools, so a tool-using feature degrades to single-shot
+	 * instead of failing outright.
+	 *
+	 * Providers that wrap upstream rejections in their own envelope (e.g. GitKraken) must override this:
+	 * the wrapper's prose names neither "tool" nor "function", so the text match here cannot see through
+	 * it and the fallback would never fire.
+	 */
+	protected isToolsRejection(status: number, message: string | undefined): boolean {
+		if (status !== 400 || !message) return false;
+
+		const m = message.toLowerCase();
+		return (
+			(m.includes('tool') || m.includes('function')) &&
+			(m.includes('unsupported') ||
+				m.includes('not supported') ||
+				m.includes('unknown') ||
+				m.includes('unrecognized') ||
+				m.includes('invalid') ||
+				m.includes('unexpected'))
+		);
+	}
+
+	/** Whether a failed response means the native response format itself was rejected — the
+	 *  trigger for stripping it and retrying via the prompt-described JSON. Providers that wrap
+	 *  upstream rejections in their own envelope (e.g. GitKraken) extend this */
+	protected isResponseFormatRejection(status: number, body: string): boolean {
+		return (
+			(status === 400 && formatRejectionRegex.test(body)) ||
+			// OpenRouter answers 404 when `require_parameters` matches no serving endpoint
+			(status === 404 && /no endpoints found/i.test(body))
+		);
+	}
+
+	/** Translates the canonical response format onto the request; called only when
+	 *  {@link supportsResponseFormat} allows it. Base emits the OpenAI `response_format.json_schema`
+	 *  envelope. Overrides must REPLACE this for providers with a different native field
+	 *  (e.g. Anthropic `output_config`) — never leave both on the request. */
+	protected applyResponseFormat(
+		request: ChatCompletionRequest,
+		_model: AIModel<T>,
+		responseFormat: AIResponseFormat,
+	): void {
+		request.response_format = {
+			type: 'json_schema',
+			json_schema: {
+				name: responseFormat.name,
+				strict: true,
+				schema: responseFormat.schema,
+			},
+		};
+	}
+
+	// Finds the text block by type rather than position — with some Anthropic models (e.g. Sonnet 5,
+	// where thinking runs by default) a thinking block can precede the text block
+	protected extractContent(data: ChatCompletionResponse): string {
+		return (
+			data.choices?.[0]?.message?.content?.trim() ??
+			data.content?.find(b => b.type === 'text')?.text?.trim() ??
+			''
+		);
+	}
+
+	/** Normalizes abnormal completion signals (all arrive as HTTP 200) so consumers can
+	 *  distinguish truncated/filtered/refused output from a malformed-but-complete reply */
+	protected extractFinishReason(data: ChatCompletionResponse): AIFinishReason | undefined {
+		const choice = data.choices?.[0];
+		if (choice != null) {
+			// Truthy check — some OpenAI-compatible servers serialize `"refusal": ""` on normal replies
+			if (choice.message?.refusal) return 'refusal';
+			if (choice.finish_reason === 'length') return 'length';
+			if (choice.finish_reason === 'content_filter') return 'content_filter';
+			return undefined;
+		}
+
+		switch (data.stop_reason) {
+			// `model_context_window_exceeded` means the context filled before the output limit — the
+			// reply is truncated all the same
+			case 'max_tokens':
+			case 'model_context_window_exceeded':
+				return 'length';
+			case 'refusal':
+				return 'refusal';
+			default:
+				return undefined;
+		}
+	}
+
+	/**
+	 * Maps messages onto the provider's wire shape. The default is OpenAI Chat Completions: assistant
+	 * tool calls go in `tool_calls` with `arguments` JSON-stringified, and tool results are `tool`-role
+	 * entries keyed by `tool_call_id`. Providers with a different tool encoding (e.g. Anthropic's
+	 * content blocks) override this.
+	 */
+	protected serializeMessages(messages: AIChatMessage<AIChatMessageRole>[]): unknown[] {
+		return messages.map(m => {
+			if (m.role === 'tool') {
+				// A tool result is only addressable by the id of the call it answers. Without one, send it
+				// as plain text — the same shape used for providers that can't carry tool calls at all —
+				// rather than a `tool_call_id: undefined` the provider rejects with nothing to trace it to.
+				if (m.toolCallId == null) return { role: 'user', content: m.content };
+
+				return { role: 'tool', tool_call_id: m.toolCallId, content: m.content };
+			}
+
+			if (m.role === 'assistant' && m.toolCalls?.length) {
+				return {
+					role: 'assistant',
+					// OpenAI requires `content` to be present, but allows null on a tool-call-only turn
+					content: m.content || null,
+					tool_calls: m.toolCalls.map(c => ({
+						id: c.id,
+						type: 'function',
+						function: { name: c.name, arguments: JSON.stringify(c.args) },
+						// Only the GitKraken proxy mints these, so the field can only ever be present on a
+						// conversation with that proxy — no other provider sees it.
+						...(c.providerSignature != null ? { thought_signature: c.providerSignature } : undefined),
+					})),
+				};
+			}
+
+			return { role: m.role, content: m.content };
+		});
+	}
+
+	/** Returns the tool-related request fields. The default is the OpenAI `function` envelope. */
+	protected serializeTools(tools: readonly AIToolDefinition[]): { tools: unknown[] } {
+		return {
+			tools: tools.map(t => ({
+				type: 'function',
+				function: { name: t.name, description: t.description, parameters: t.parameters },
+			})),
+		};
+	}
+
+	/**
+	 * Extracts tool calls from a response, handling both the OpenAI shape
+	 * (`choices[].message.tool_calls`, whose `arguments` is a JSON string) and the Anthropic shape
+	 * (`content[]` blocks of type `tool_use`) — mirroring how {@link fetch} already reads content
+	 * from both.
+	 */
+	protected parseToolCalls(data: ChatCompletionResponse): AIToolCall[] | undefined {
+		const calls: AIToolCall[] = [];
+
+		for (const call of data.choices?.[0]?.message?.tool_calls ?? []) {
+			let args: Record<string, unknown> = {};
+			try {
+				// Providers can emit '' for a no-argument call
+				args = call.function.arguments ? (JSON.parse(call.function.arguments) as Record<string, unknown>) : {};
+			} catch {
+				// Leave args empty — the tool dispatcher reports the resulting validation error back to
+				// the model, which is more recoverable than failing the whole request here.
+			}
+
+			calls.push({
+				id: call.id,
+				name: call.function.name,
+				args: args,
+				...(call.thought_signature != null ? { providerSignature: call.thought_signature } : undefined),
+			});
+		}
+
+		for (const block of data.content ?? []) {
+			if (block.type !== 'tool_use' || block.id == null || block.name == null) continue;
+
+			calls.push({ id: block.id, name: block.name, args: block.input ?? {} });
+		}
+
+		return calls.length ? calls : undefined;
+	}
+
 	protected async handleFetchFailure<TAction extends AIActionType>(
 		rsp: Response,
 		_action: TAction,
 		model: AIModel<T>,
 		retries: number,
 		maxInputTokens: number,
-	): Promise<{ retry: true; maxInputTokens: number }> {
+		/** The already-read error body, when the caller had to read it (avoids a second decode) */
+		body?: string,
+		sentTools?: boolean,
+	): Promise<{ retry: true; maxInputTokens: number; withoutTools?: boolean }> {
 		if (rsp.status === 404) {
 			throw new AIError(
 				AIErrorReason.Unauthorized,
@@ -209,7 +506,9 @@ export abstract class OpenAICompatibleProviderBase<T extends AIProviders> implem
 
 		let json;
 		try {
-			json = (await rsp.json()) as { error?: { code: string; message: string } } | undefined;
+			json = (body != null ? JSON.parse(body) : await rsp.json()) as
+				| { error?: { code: string; message: string } }
+				| undefined;
 		} catch {}
 
 		if (Array.isArray(json)) {
@@ -226,6 +525,13 @@ export abstract class OpenAICompatibleProviderBase<T extends AIProviders> implem
 			);
 		}
 
+		// A provider that advertises the OpenAI shape but rejects `tools` (an older or partial
+		// implementation) gets one retry without them, so the caller degrades to text-only instead of
+		// failing outright.
+		if (sentTools && this.isToolsRejection(rsp.status, json?.error?.message)) {
+			return { retry: true, maxInputTokens: maxInputTokens, withoutTools: true };
+		}
+
 		throw new Error(`(${this.name}) ${rsp.status}: ${json?.error?.message || rsp.statusText}`);
 	}
 
@@ -242,11 +548,23 @@ export abstract class OpenAICompatibleProviderBase<T extends AIProviders> implem
 			throw new Error(`(${this.name}) ${getActionName(action)}: No URL configured`);
 		}
 
+		const body = JSON.stringify(request);
+
+		// A rejected request is otherwise undiagnosable: a proxying backend reports only its own
+		// "upstream AI provider error (<provider> HTTP <status>)", so which field the upstream objected to
+		// can only be inferred. Log the request's shape — which fields were sent, and how much — but not
+		// the messages, which carry the user's source code.
+		Logger.trace(
+			`(${this.name}) ${getActionName(action)} → ${model.id}: fields=[${Object.keys(request)
+				.sort()
+				.join(',')}] bytes=${body.length}`,
+		);
+
 		try {
 			return await this.context.fetch(url, {
 				headers: await this.getHeaders(action, apiKey, model, url, conversationId),
 				method: 'POST',
-				body: JSON.stringify(request),
+				body: body,
 				signal: signal,
 			});
 		} catch (ex) {
@@ -256,13 +574,17 @@ export abstract class OpenAICompatibleProviderBase<T extends AIProviders> implem
 	}
 }
 
-interface ChatCompletionRequest {
+export interface ChatCompletionRequest {
 	model: string;
-	messages: AIChatMessage<AIChatMessageRole>[];
+	/** Provider-shaped messages from {@link OpenAICompatibleProviderBase.serializeMessages} */
+	messages: unknown[];
 
 	/** Anthropic carries the initial system prompt here instead of as a `system`-role message */
 	system?: string;
 
+	/** Tool definitions, shaped by {@link OpenAICompatibleProviderBase.serializeTools} */
+	tools?: unknown[];
+
 	/** @deprecated but used by Anthropic & Gemini */
 	max_tokens?: number;
 	/** Currently can't be used for Anthropic & Gemini */
@@ -274,9 +596,16 @@ interface ChatCompletionRequest {
 
 	/** Not supported by many models/providers */
 	reasoning_effort?: 'low' | 'medium' | 'high';
+
+	/** OpenAI-compatible structured output (set via {@link OpenAICompatibleProviderBase.applyResponseFormat}) */
+	response_format?: { type: 'json_schema'; json_schema: { name: string; strict: boolean; schema: JSONSchema } };
+	/** Anthropic-native structured output (set only by the Anthropic override) */
+	output_config?: { format: { type: 'json_schema'; schema: JSONSchema } };
+	/** OpenRouter-only routing constraint (set only by the OpenRouter override) */
+	provider?: { require_parameters: boolean };
 }
 
-interface ChatCompletionResponse {
+export interface ChatCompletionResponse {
 	id: string;
 	model: string;
 	/** OpenAI compatible output */
@@ -285,12 +614,26 @@ interface ChatCompletionResponse {
 		message: {
 			role: string;
 			content: string | null;
-			refusal: string | null;
+			/** OpenAI-only; most OpenAI-compatible servers omit it entirely */
+			refusal?: string | null;
+			tool_calls?: {
+				id: string;
+				type: string;
+				function: { name: string; arguments: string };
+				/** GitKraken proxy only — an opaque provider reasoning token to round-trip */
+				thought_signature?: string;
+			}[];
 		};
 		finish_reason: string;
 	}[];
-	/** Anthropic output */
-	content?: { type: 'text'; text: string }[];
+	/** Anthropic output (non-text blocks, e.g. thinking, carry no text). `tool_use` blocks add the
+	 *  call fields, which is why `id`/`name` are optional here — {@link parseToolCalls} narrows on
+	 *  `type` and then checks them. */
+	content?: { type: string; text?: string; id?: string; name?: string; input?: Record<string, unknown> }[];
+	/** Error envelope some providers/proxies return with an OK status (e.g. OpenRouter upstream failures) */
+	error?: { message?: string; code?: number | string } | null;
+	/** Anthropic stop reason */
+	stop_reason?: string;
 	usage: {
 		/** OpenAI compatible */
 		prompt_tokens?: number;

package/src/plus/ai/providers/openRouterProvider.ts

@@ -1,6 +1,8 @@
 import { isCancellationError } from '../../../utils/cancellation.js';
 import { openRouterProviderDescriptor as provider } from '../constants.js';
 import type { AIActionType, AIModel } from '../models/model.js';
+import type { AIResponseFormat } from '../models/provider.js';
+import type { ChatCompletionRequest } from './openAICompatibleProviderBase.js';
 import { OpenAICompatibleProviderBase } from './openAICompatibleProviderBase.js';
 
 type OpenRouterModel = AIModel<typeof provider.id>;
@@ -8,6 +10,7 @@ type OpenRouterModel = AIModel<typeof provider.id>;
 export class OpenRouterProvider extends OpenAICompatibleProviderBase<typeof provider.id> {
 	readonly id = provider.id;
 	readonly name = provider.name;
+	readonly supportsTools = true;
 	protected readonly descriptor = provider;
 	protected readonly config = {
 		keyUrl: 'https://openrouter.ai/keys',
@@ -40,6 +43,7 @@ export class OpenRouterProvider extends OpenAICompatibleProviderBase<typeof prov
 				top_provider: {
 					max_completion_tokens?: number;
 				};
+				supported_parameters?: string[];
 			}[];
 		};
 
@@ -55,10 +59,23 @@ export class OpenRouterProvider extends OpenAICompatibleProviderBase<typeof prov
 					},
 					provider: provider,
 					temperature: null,
+					// OpenRouter hard-errors when `response_format` reaches a model that doesn't advertise support
+					supportsStructuredOutputs: m.supported_parameters?.includes('structured_outputs') ?? false,
 				}) satisfies OpenRouterModel,
 		);
 	}
 
+	protected override applyResponseFormat(
+		request: ChatCompletionRequest,
+		model: AIModel<typeof provider.id>,
+		responseFormat: AIResponseFormat,
+	): void {
+		super.applyResponseFormat(request, model, responseFormat);
+		// `supported_parameters` is a union across the providers serving a model — restrict routing
+		// to providers that actually support every parameter sent
+		request.provider = { require_parameters: true };
+	}
+
 	protected getUrl(_model: AIModel<typeof provider.id>): string {
 		return 'https://openrouter.ai/api/v1/chat/completions';
 	}

package/src/plus/ai/providers/openaiProvider.ts

@@ -10,6 +10,7 @@ const models: OpenAIModel[] = openAIModels(provider);
 export class OpenAIProvider extends OpenAICompatibleProviderBase<typeof provider.id> {
 	readonly id = provider.id;
 	readonly name = provider.name;
+	readonly supportsTools = true;
 	protected readonly descriptor = provider;
 	protected readonly config = {
 		keyUrl: 'https://platform.openai.com/account/api-keys',

package/src/plus/ai/providers/responseFormatCache.ts

@@ -0,0 +1,39 @@
+import type { AIModel } from '../models/model.js';
+import type { AIResponseFormat } from '../models/provider.js';
+
+/**
+ * `providerId:modelId:schemaName` keys whose native format was rejected. Module-scoped because the
+ * service constructs a fresh provider instance per request, so instance state wouldn't survive to
+ * skip the doomed probe. Keyed per schema: e.g. GitKraken-Gemini rejects the null-union review
+ * schemas but happily enforces the commits schema on the same model.
+ *
+ * Lives in its own (dependency-free) module so the AI service can clear it without statically
+ * importing a provider implementation — every provider is loaded lazily into the `ai` chunk.
+ */
+const rejectedResponseFormats = new Set<string>();
+
+function getKey(providerId: string, model: AIModel, responseFormat: AIResponseFormat): string {
+	return `${providerId}:${model.id}:${responseFormat.name}`;
+}
+
+export function isResponseFormatRejected(
+	providerId: string,
+	model: AIModel,
+	responseFormat: AIResponseFormat,
+): boolean {
+	return rejectedResponseFormats.has(getKey(providerId, model, responseFormat));
+}
+
+export function rememberResponseFormatRejection(
+	providerId: string,
+	model: AIModel,
+	responseFormat: AIResponseFormat,
+): void {
+	rejectedResponseFormats.add(getKey(providerId, model, responseFormat));
+}
+
+/** Drops the remembered rejections; shares the provider model-list cache's lifetime, so a
+ *  misclassified rejection can't outlive the capability data it was inferred from */
+export function clearResponseFormatRejections(): void {
+	rejectedResponseFormats.clear();
+}

package/src/plus/ai/providers/xaiProvider.ts

@@ -4,6 +4,12 @@ import { OpenAICompatibleProviderBase } from './openAICompatibleProviderBase.js'
 
 type XAIModel = AIModel<typeof provider.id>;
 const models: XAIModel[] = [
+	{
+		id: 'grok-4.6',
+		name: 'Grok 4.6',
+		maxTokens: { input: 500000, output: 65536 }, // xAI publishes no output cap; mirrors Grok 4.5 to bound cost
+		provider: provider,
+	},
 	{
 		id: 'grok-4.5',
 		name: 'Grok 4.5',
@@ -13,7 +19,7 @@ const models: XAIModel[] = [
 	{
 		id: 'grok-4.3',
 		name: 'Grok 4.3',
-		maxTokens: { input: 1048576, output: 65536 },
+		maxTokens: { input: 1000000, output: 65536 },
 		provider: provider,
 		default: true,
 	},
@@ -23,12 +29,15 @@ const models: XAIModel[] = [
 		maxTokens: { input: 131072, output: 4096 },
 		provider: provider,
 		hidden: true,
+		// Structured outputs require grok-2-1212 or newer; grok-beta predates that floor
+		supportsStructuredOutputs: false,
 	},
 ];
 
 export class XAIProvider extends OpenAICompatibleProviderBase<typeof provider.id> {
 	readonly id = provider.id;
 	readonly name = provider.name;
+	readonly supportsTools = true;
 	protected readonly descriptor = provider;
 	protected readonly config = {
 		keyUrl: 'https://console.x.ai/',

package/src/plus/ai/utils/ai.utils.ts

@@ -1,4 +1,10 @@
 import type { AIActionType, AIModel } from '../models/model.js';
+import type { AIFinishReason } from '../models/provider.js';
+
+/** Whether the model declined to fulfill the request (refused or content-filtered) */
+export function didModelDecline(finishReason: AIFinishReason | undefined): boolean {
+	return finishReason === 'refusal' || finishReason === 'content_filter';
+}
 
 export function getActionName(action: AIActionType): string {
 	switch (action) {
@@ -32,6 +38,14 @@ export function getValidatedTemperature(
 	modelTemperature?: number | null,
 	defaultTemperature?: number,
 ): number | undefined {
+	// `temperature: null` on the model is a capability statement, not a default: the model rejects the
+	// parameter (reasoning models, Anthropic Opus 4.7+/Sonnet 5, Gemini 3.x) or the catalog can't
+	// promise it accepts one (every GitKraken-proxy and OpenRouter model). It therefore has to win over
+	// a caller-supplied value — callers merge as `modelOptions?.temperature ?? model.temperature`, and
+	// `0 ?? null` is `0`, so an explicit 0 would otherwise defeat the opt-out and be sent anyway.
+	// It also covers upstreams the id check below can't see: a proxy model is `openai:gpt-5.6-…`, not
+	// `gpt-5.6-…`, so `startsWith` misses it while the upstream still 400s on a non-default value.
+	if (model.temperature === null) return undefined;
 	if (modelTemperature === null) return undefined;
 	// GPT5 doesn't support anything but the default temperature
 	if (model.id.startsWith('gpt-5')) return undefined;