@gajae-code/ai 0.4.5 → 0.5.0

package/src/providers/google-gemini-cli.ts

@@ -25,6 +25,11 @@ import { resolveRetryBudget } from "../utils/retry-budget";
 // Refresh is the sole responsibility of AuthStorage (broker-aware, single-flighted);
 // the stream provider trusts the access token threaded through `options.apiKey`.
 import { normalizeSchemaForCCA } from "../utils/schema";
+import {
+	isForcedToolChoiceUnsupportedError,
+	markToolChoiceIncapability,
+	resolveToolChoice,
+} from "../utils/tool-choice-capability";
 import { ANTIGRAVITY_SYSTEM_INSTRUCTION, getAntigravityUserAgent, getGeminiCliHeaders } from "./google-gemini-headers";
 import type { Content, FunctionCallingConfigMode, ThinkingConfig } from "./google-shared";
 import {
@@ -48,7 +53,7 @@ import {
 export type { GoogleThinkingLevel };
 
 export interface GoogleGeminiCliOptions extends StreamOptions {
-	toolChoice?: "auto" | "none" | "any";
+	toolChoice?: "auto" | "none" | "any" | "required";
 	/**
 	 * Thinking/reasoning configuration.
 	 * - Gemini 2.x models: use `budgetTokens` to set the thinking budget
@@ -324,7 +329,7 @@ export const streamGoogleGeminiCli: StreamFunction<"google-gemini-cli"> = (
 				...(needsClaudeThinkingBetaHeader(model) ? { "anthropic-beta": CLAUDE_THINKING_BETA_HEADER } : {}),
 				...(options?.headers ?? {}),
 			};
-			const requestBodyJson = JSON.stringify(requestBody);
+			let requestBodyJson = JSON.stringify(requestBody);
 			rawRequestDump = {
 				provider: model.provider,
 				api: output.api,
@@ -334,7 +339,13 @@ export const streamGoogleGeminiCli: StreamFunction<"google-gemini-cli"> = (
 				headers: requestHeaders,
 			};
 
-			const response = await fetchWithRetry(
+			const sentForcedToolChoice =
+				(requestBody.request.toolConfig?.functionCallingConfig?.mode === "ANY" ||
+					requestBody.request.toolConfig?.functionCallingConfig?.mode === "VALIDATED") &&
+				options?.toolChoice !== undefined &&
+				options.toolChoice !== "auto" &&
+				options.toolChoice !== "none";
+			let response = await fetchWithRetry(
 				attempt => `${endpoints[Math.min(attempt, endpoints.length - 1)]}/v1internal:streamGenerateContent?alt=sse`,
 				{
 					method: "POST",
@@ -347,6 +358,49 @@ export const streamGoogleGeminiCli: StreamFunction<"google-gemini-cli"> = (
 					fetch: options?.fetch,
 				},
 			);
+			if (!response.ok && sentForcedToolChoice) {
+				const errorText = await response.text();
+				const error = withHttpStatus(
+					new Error(`Cloud Code Assist API error (${response.status}): ${extractErrorMessage(errorText)}`),
+					response.status,
+				);
+				if (firstTokenTime === undefined && isForcedToolChoiceUnsupportedError(error, true)) {
+					const beforeMark = resolveToolChoice(model, options?.toolChoice);
+					markToolChoiceIncapability(model, "auto", error.message);
+					stream.push({
+						type: "toolChoiceIncapability",
+						api: model.api,
+						provider: model.provider,
+						model: model.id,
+						requestedLevel: beforeMark.requestedLevel,
+						resolvedLevel: "auto",
+						reason: error.message,
+						registryKey: beforeMark.registryKey,
+					});
+					requestBody = {
+						...requestBody,
+						request: { ...requestBody.request, toolConfig: undefined },
+					};
+					requestBodyJson = JSON.stringify(requestBody);
+					rawRequestDump = { ...rawRequestDump, body: requestBody };
+					response = await fetchWithRetry(
+						attempt =>
+							`${endpoints[Math.min(attempt, endpoints.length - 1)]}/v1internal:streamGenerateContent?alt=sse`,
+						{
+							method: "POST",
+							headers: requestHeaders,
+							body: requestBodyJson,
+							signal: options?.signal,
+							maxAttempts: 1,
+							defaultDelayMs: attempt => BASE_DELAY_MS * 2 ** attempt,
+							maxDelayMs: options?.maxRetryDelayMs ?? RATE_LIMIT_BUDGET_MS,
+							fetch: options?.fetch,
+						},
+					);
+				} else {
+					throw error;
+				}
+			}
 			if (!response.ok) {
 				const errorText = await response.text();
 				throw withHttpStatus(
@@ -743,13 +797,15 @@ export function buildRequest(
 		request.generationConfig = generationConfig;
 	}
 
+	const resolvedToolChoice = resolveToolChoice(model, options.toolChoice);
 	if (context.tools && context.tools.length > 0) {
 		const convertedTools = convertTools(context.tools, model);
 		request.tools = isAntigravity ? normalizeAntigravityTools(convertedTools) : convertedTools;
-		if (options.toolChoice) {
+		const resolved = resolvedToolChoice;
+		if (resolved.resolvedChoice) {
 			request.toolConfig = {
 				functionCallingConfig: {
-					mode: mapToolChoice(options.toolChoice),
+					mode: mapToolChoice(resolved.resolvedChoice as string),
 				},
 			};
 		}
@@ -763,11 +819,14 @@ export function buildRequest(
 	}
 
 	if (isAntigravity && isClaudeModel(model.id)) {
-		request.toolConfig = {
-			functionCallingConfig: {
-				mode: "VALIDATED" as FunctionCallingConfigMode,
-			},
-		};
+		const resolvedLevel = resolvedToolChoice.resolvedLevel;
+		if (resolvedLevel === "named" || resolvedLevel === "required") {
+			request.toolConfig = {
+				functionCallingConfig: {
+					mode: "VALIDATED" as FunctionCallingConfigMode,
+				},
+			};
+		}
 	}
 
 	if (isAntigravity && shouldInjectAntigravitySystemInstruction(model.id)) {

package/src/providers/google-shared.ts

@@ -22,6 +22,11 @@ import { normalizeSystemPrompts } from "../utils";
 import { AssistantMessageEventStream } from "../utils/event-stream";
 import { finalizeErrorMessage, type RawHttpRequestDump, withHttpStatus } from "../utils/http-inspector";
 import { normalizeSchemaForCCA, normalizeSchemaForGoogle, toolWireSchema } from "../utils/schema";
+import {
+	isForcedToolChoiceUnsupportedError,
+	markToolChoiceIncapability,
+	resolveToolChoice,
+} from "../utils/tool-choice-capability";
 import type {
 	Content,
 	FinishReason,
@@ -59,7 +64,7 @@ export type GoogleThinkingLevel = "THINKING_LEVEL_UNSPECIFIED" | "MINIMAL" | "LO
  * `google-gemini-cli` uses a different transport and request shape — do not extend this for it.
  */
 export interface GoogleSharedStreamOptions extends StreamOptions {
-	toolChoice?: "auto" | "none" | "any";
+	toolChoice?: "auto" | "none" | "any" | "required";
 	thinking?: {
 		enabled: boolean;
 		budgetTokens?: number;
@@ -366,6 +371,7 @@ export function mapToolChoice(choice: string): FunctionCallingConfigMode {
 		case "none":
 			return "NONE";
 		case "any":
+		case "required":
 			return "ANY";
 		default:
 			return "AUTO";
@@ -689,14 +695,15 @@ export function buildGoogleGenerateContentParams<T extends "google-generative-ai
 		...(context.tools && context.tools.length > 0 && { tools: convertTools(context.tools, model) }),
 	};
 
-	if (context.tools && context.tools.length > 0 && options.toolChoice) {
-		config.toolConfig = {
-			functionCallingConfig: {
-				mode: mapToolChoice(options.toolChoice),
-			},
-		};
-	} else {
-		config.toolConfig = undefined;
+	if (context.tools && context.tools.length > 0) {
+		const resolved = resolveToolChoice(model, options.toolChoice);
+		if (resolved.resolvedChoice) {
+			config.toolConfig = {
+				functionCallingConfig: {
+					mode: mapToolChoice(resolved.resolvedChoice as string),
+				},
+			};
+		}
 	}
 
 	if (options.thinking?.enabled && model.reasoning) {
@@ -789,14 +796,56 @@ export function streamGoogleGenAI<T extends "google-generative-ai" | "google-ver
 				headers: plan.headers,
 			};
 
-			const wireBody = paramsToWireBody(params);
+			let wireBody = paramsToWireBody(params);
+			const sentForcedToolChoice =
+				(params.config?.toolConfig?.functionCallingConfig?.mode === "ANY" ||
+					params.config?.toolConfig?.functionCallingConfig?.mode === "VALIDATED") &&
+				options?.toolChoice !== undefined &&
+				options.toolChoice !== "auto" &&
+				options.toolChoice !== "none";
 			const fetchImpl = plan.fetch ?? options?.fetch ?? (globalThis.fetch.bind(globalThis) as FetchImpl);
-			const response = await fetchImpl(plan.url, {
+			let response = await fetchImpl(plan.url, {
 				method: "POST",
 				headers: { ...plan.headers, "Content-Type": "application/json", Accept: "text/event-stream" },
 				body: JSON.stringify(wireBody),
 				signal: options?.signal,
 			});
+			if (!response.ok && sentForcedToolChoice) {
+				const errorText = await response.text().catch(() => "");
+				const error = withHttpStatus(
+					new Error(`Google API error (${response.status}): ${extractGoogleErrorMessage(errorText)}`),
+					response.status,
+				);
+				if (firstTokenTime === undefined && isForcedToolChoiceUnsupportedError(error, true)) {
+					const beforeMark = resolveToolChoice(model, options?.toolChoice);
+					markToolChoiceIncapability(model, "auto", error.message);
+					stream.push({
+						type: "toolChoiceIncapability",
+						api: model.api,
+						provider: model.provider,
+						model: model.id,
+						requestedLevel: beforeMark.requestedLevel,
+						resolvedLevel: "auto",
+						reason: error.message,
+						registryKey: beforeMark.registryKey,
+					});
+					const retryParams = {
+						...params,
+						config: params.config ? { ...params.config, toolConfig: undefined } : params.config,
+					};
+					params = retryParams;
+					rawRequestDump = { ...rawRequestDump, body: params };
+					wireBody = paramsToWireBody(params);
+					response = await fetchImpl(plan.url, {
+						method: "POST",
+						headers: { ...plan.headers, "Content-Type": "application/json", Accept: "text/event-stream" },
+						body: JSON.stringify(wireBody),
+						signal: options?.signal,
+					});
+				} else {
+					throw error;
+				}
+			}
 			if (!response.ok) {
 				const errorText = await response.text().catch(() => "");
 				throw withHttpStatus(
@@ -857,7 +906,7 @@ export function streamGoogleGenAI<T extends "google-generative-ai" | "google-ver
  * `abortSignal` is intentionally dropped — the SDK propagates it via `fetch.signal`,
  * which our caller already wires up through `options.signal`.
  */
-function paramsToWireBody(params: GenerateContentParameters): Record<string, unknown> {
+export function paramsToWireBody(params: GenerateContentParameters): Record<string, unknown> {
 	const body: Record<string, unknown> = { contents: params.contents };
 	const config = params.config;
 	if (!config) return body;

package/src/providers/ollama.ts

@@ -20,6 +20,11 @@ import { finalizeErrorMessage, type RawHttpRequestDump } from "../utils/http-ins
 import { parseStreamingJson } from "../utils/json-parse";
 import { resolveRetryBudget } from "../utils/retry-budget";
 import { toolWireSchema } from "../utils/schema/wire";
+import {
+	isForcedToolChoiceUnsupportedError,
+	markToolChoiceIncapability,
+	resolveToolChoice,
+} from "../utils/tool-choice-capability";
 import { transformMessages } from "./transform-messages";
 
 export interface OllamaChatOptions extends StreamOptions {
@@ -253,10 +258,22 @@ function convertTools(tools: Tool[] | undefined): OllamaFunctionTool[] | undefin
 	}));
 }
 
-function createChatBody(model: Model<"ollama-chat">, context: Context, options: OllamaChatOptions | undefined) {
+export function createChatBody(model: Model<"ollama-chat">, context: Context, options: OllamaChatOptions | undefined) {
 	const think = mapReasoning(options?.reasoning);
-	const toolChoice = mapToolChoice(options?.toolChoice);
-	const selectedTools = selectToolsForToolChoice(context.tools, options?.toolChoice);
+	const resolved = resolveToolChoice(model, options?.toolChoice);
+	const toolChoice = mapToolChoice(resolved.resolvedChoice);
+
+	// Ollama's wire protocol has no named forcing — a named request rides
+	// `tool_choice: "required"` with the tool list narrowed to the target
+	// (issue #1236). Narrow whenever the resolved choice still forces a tool.
+	const shouldNarrowToNamedTool =
+		resolved.requestedLevel === "named" &&
+		(resolved.resolvedLevel === "named" || resolved.resolvedLevel === "required") &&
+		resolved.targetToolName !== undefined;
+	const selectedTools =
+		shouldNarrowToNamedTool && resolved.targetToolName
+			? selectToolsForToolChoice(context.tools, { type: "tool", name: resolved.targetToolName })
+			: context.tools;
 	const tools = convertTools(selectedTools);
 	return {
 		model: model.id,
@@ -382,6 +399,7 @@ export const streamOllama: StreamFunction<"ollama-chat"> = (
 			}
 			const baseUrl = normalizeBaseUrl(model.baseUrl);
 			let body = createChatBody(model, context, options);
+			const sentForcedToolChoice = body.tool_choice === "required";
 			const replacementPayload = await options.onPayload?.(body, model);
 			if (replacementPayload !== undefined) {
 				body = replacementPayload as typeof body;
@@ -394,7 +412,7 @@ export const streamOllama: StreamFunction<"ollama-chat"> = (
 				url: `${baseUrl}/api/chat`,
 				body,
 			};
-			const response = await fetchWithRetry(`${baseUrl}/api/chat`, {
+			let response = await fetchWithRetry(`${baseUrl}/api/chat`, {
 				method: "POST",
 				headers: {
 					...model.headers,
@@ -408,6 +426,44 @@ export const streamOllama: StreamFunction<"ollama-chat"> = (
 				defaultDelayMs: OLLAMA_RETRY_DELAYS_MS,
 				fetch: options.fetch,
 			});
+			if (!response.ok && sentForcedToolChoice) {
+				const error = new Error(
+					`HTTP ${response.status} from ${baseUrl}/api/chat: ${await response.text().catch(() => "")}`,
+				);
+				(error as Error & { status?: number }).status = response.status;
+				if (firstTokenTime === undefined && isForcedToolChoiceUnsupportedError(error, true)) {
+					markToolChoiceIncapability(model, "auto", error.message);
+					stream.push({
+						type: "toolChoiceIncapability",
+						api: model.api,
+						provider: model.provider,
+						model: model.id,
+						requestedLevel: "required",
+						resolvedLevel: "auto",
+						reason: error.message,
+						registryKey: resolveToolChoice(model, options?.toolChoice).registryKey,
+					});
+					body = { ...body };
+					delete (body as { tool_choice?: unknown }).tool_choice;
+					rawRequestDump = { ...rawRequestDump, body };
+					response = await fetchWithRetry(`${baseUrl}/api/chat`, {
+						method: "POST",
+						headers: {
+							...model.headers,
+							...options.headers,
+							Authorization: `Bearer ${apiKey}`,
+							"Content-Type": "application/json",
+						},
+						body: JSON.stringify(body),
+						signal: options.signal,
+						maxAttempts: 1,
+						defaultDelayMs: OLLAMA_RETRY_DELAYS_MS,
+						fetch: options.fetch,
+					});
+				} else {
+					throw error;
+				}
+			}
 			if (!response.ok) {
 				throw new Error(`HTTP ${response.status} from ${baseUrl}/api/chat`);
 			}

package/src/providers/openai-codex-responses.ts

@@ -51,6 +51,11 @@ import { getOpenAIStreamIdleTimeoutMs, iterateWithIdleTimeout } from "../utils/i
 import { parseStreamingJson } from "../utils/json-parse";
 import { resolveRetryBudget } from "../utils/retry-budget";
 import { adaptSchemaForStrict, NO_STRICT, sanitizeSchemaForOpenAIResponses, toolWireSchema } from "../utils/schema";
+import {
+	isForcedToolChoiceUnsupportedError,
+	markToolChoiceIncapability,
+	resolveToolChoice,
+} from "../utils/tool-choice-capability";
 import { compactGrammarDefinition } from "./grammar";
 import { CODEX_BASE_URL, getCodexAccountId, OPENAI_HEADER_VALUES, OPENAI_HEADERS } from "./openai-codex/constants";
 import {
@@ -175,6 +180,47 @@ interface CodexRequestContext {
 	rawRequestDump: RawHttpRequestDump;
 }
 
+async function retryCodexInitialTransportWithoutToolChoice(
+	model: Model<"openai-codex-responses">,
+	options: OpenAICodexResponsesOptions | undefined,
+	requestSetup: CodexRequestSetup,
+	requestContext: CodexRequestContext,
+	stream: AssistantMessageEventStream,
+	error: unknown,
+): Promise<{
+	eventStream: AsyncGenerator<Record<string, unknown>>;
+	requestBodyForState: RequestBody;
+	transport: CodexTransport;
+}> {
+	if (
+		!isForcedToolChoiceUnsupportedError(error, isForcedCodexToolChoice(requestContext.transformedBody.tool_choice))
+	) {
+		throw error;
+	}
+	const reason = await finalizeErrorMessage(error, requestContext.rawRequestDump);
+	markToolChoiceIncapability(model, "auto", reason);
+	const resolvedToolChoice = resolveToolChoice(model, options?.toolChoice);
+	stream.push({
+		type: "toolChoiceIncapability",
+		api: model.api,
+		provider: model.provider,
+		model: model.id,
+		requestedLevel: resolvedToolChoice.requestedLevel,
+		resolvedLevel: "auto",
+		reason,
+		registryKey: resolvedToolChoice.registryKey,
+	});
+	const next = await openCodexSseTransportWithoutToolChoice(
+		model,
+		requestContext,
+		requestSetup,
+		options,
+		requestContext.websocketState,
+	);
+	requestContext.rawRequestDump = { ...requestContext.rawRequestDump, body: next.requestBodyForState };
+	return next;
+}
+
 interface CodexRequestSetup {
 	requestSignal: AbortSignal;
 	wrapCodexSseStream: (source: AsyncGenerator<Record<string, unknown>>) => AsyncGenerator<Record<string, unknown>>;
@@ -601,7 +647,16 @@ async function buildTransformedCodexRequestBody(
 	if (context.tools && context.tools.length > 0) {
 		params.tools = convertOpenAICodexResponsesTools(context.tools, model);
 		if (options?.toolChoice) {
-			const toolChoice = normalizeCodexToolChoice(options.toolChoice, context.tools, model);
+			const resolvedToolChoice = resolveToolChoice(model, options.toolChoice);
+			if (resolvedToolChoice.degraded && resolvedToolChoice.supportSource === "runtime") {
+				logCodexDebug("codex degraded tool_choice after runtime capability discovery", {
+					model: model.id,
+					requestedLevel: resolvedToolChoice.requestedLevel,
+					resolvedLevel: resolvedToolChoice.resolvedLevel,
+					reason: resolvedToolChoice.reason,
+				});
+			}
+			const toolChoice = normalizeCodexToolChoice(resolvedToolChoice.resolvedChoice, context.tools, model);
 			if (toolChoice) {
 				params.tool_choice = toolChoice;
 			}
@@ -754,6 +809,22 @@ async function openCodexSseTransport(
 	return { eventStream, requestBodyForState: structuredCloneJSON(body), transport: "sse" };
 }
 
+async function openCodexSseTransportWithoutToolChoice(
+	model: Model<"openai-codex-responses">,
+	requestContext: CodexRequestContext,
+	requestSetup: CodexRequestSetup,
+	options: OpenAICodexResponsesOptions | undefined,
+	state: CodexWebSocketSessionState | undefined,
+): Promise<{
+	eventStream: AsyncGenerator<Record<string, unknown>>;
+	requestBodyForState: RequestBody;
+	transport: CodexTransport;
+}> {
+	const body = structuredCloneJSON(requestContext.transformedBody);
+	delete body.tool_choice;
+	return openCodexSseTransport(model, requestContext, requestSetup, options, state, body);
+}
+
 async function reopenCodexWebSocketRuntimeStream(
 	context: CodexStreamProcessingContext,
 	runtime: CodexStreamRuntime,
@@ -1273,6 +1344,9 @@ async function recoverCodexStreamError(
 	runtime: CodexStreamRuntime,
 	error: unknown,
 ): Promise<boolean> {
+	if (await tryRetryWithoutForcedToolChoice(context, runtime, error)) {
+		return true;
+	}
 	if (await tryReconnectCodexWebSocketOnConnectionLimit(context, runtime, error)) {
 		return true;
 	}
@@ -1288,6 +1362,69 @@ async function recoverCodexStreamError(
 	return false;
 }
 
+async function tryRetryWithoutForcedToolChoice(
+	context: CodexStreamProcessingContext,
+	runtime: CodexStreamRuntime,
+	error: unknown,
+): Promise<boolean> {
+	if (
+		runtime.providerRetryAttempt > 0 ||
+		context.output.content.length > 0 ||
+		context.firstTokenTime !== undefined ||
+		context.options?.signal?.aborted ||
+		!isForcedToolChoiceUnsupportedError(error, isForcedCodexToolChoice(runtime.requestBodyForState.tool_choice))
+	) {
+		return false;
+	}
+
+	const reason = await finalizeErrorMessage(error, context.requestContext.rawRequestDump);
+	markToolChoiceIncapability(context.model, "auto", reason);
+	const resolvedToolChoice = resolveToolChoice(context.model, context.options?.toolChoice);
+	context.stream.push({
+		type: "toolChoiceIncapability",
+		api: context.model.api,
+		provider: context.model.provider,
+		model: context.model.id,
+		requestedLevel: resolvedToolChoice.requestedLevel,
+		resolvedLevel: "auto",
+		reason,
+		registryKey: resolvedToolChoice.registryKey,
+	});
+
+	runtime.providerRetryAttempt += 1;
+	runtime.currentItem = null;
+	runtime.currentBlock = null;
+	runtime.sawTerminalEvent = false;
+	runtime.nativeOutputItems.length = 0;
+	resetOutputState(context.output);
+	context.firstTokenTime = undefined;
+
+	const websocketState = context.requestContext.websocketState;
+	if (websocketState) {
+		resetCodexWebSocketAppendState(websocketState);
+		resetCodexSessionMetadata(websocketState);
+	}
+	const next = await openCodexSseTransportWithoutToolChoice(
+		context.model,
+		context.requestContext,
+		context.requestSetup,
+		context.options,
+		websocketState,
+	);
+	runtime.eventStream = next.eventStream;
+	runtime.requestBodyForState = next.requestBodyForState;
+	runtime.transport = next.transport;
+	if (websocketState) {
+		websocketState.lastTransport = next.transport;
+	}
+	context.requestContext.rawRequestDump = { ...context.requestContext.rawRequestDump, body: next.requestBodyForState };
+	return true;
+}
+
+function isForcedCodexToolChoice(choice: RequestBody["tool_choice"]): boolean {
+	return !!choice && choice !== "none" && choice !== "auto";
+}
+
 /**
  * Handles `websocket_connection_limit_reached` errors by closing the stale connection
  * and opening a fresh websocket. If content has already been emitted to the caller,
@@ -1546,7 +1683,19 @@ export const streamOpenAICodexResponses: StreamFunction<"openai-codex-responses"
 
 		try {
 			const requestContext = await buildCodexRequestContext(model, context, options, output);
-			const initialTransport = await openInitialCodexEventStream(model, options, requestSetup, requestContext);
+			let initialTransport: Awaited<ReturnType<typeof openInitialCodexEventStream>>;
+			try {
+				initialTransport = await openInitialCodexEventStream(model, options, requestSetup, requestContext);
+			} catch (error) {
+				initialTransport = await retryCodexInitialTransportWithoutToolChoice(
+					model,
+					options,
+					requestSetup,
+					requestContext,
+					stream,
+					error,
+				);
+			}
 			const runtime = createCodexStreamRuntime({
 				...initialTransport,
 				websocketState: requestContext.websocketState,

package/src/providers/openai-completions-compat.ts

@@ -4,12 +4,17 @@ type OpenAIReasoningEffort = "minimal" | "low" | "medium" | "high" | "xhigh" | "
 type ResolvedToolStrictMode = NonNullable<OpenAICompat["toolStrictMode"]> | "mixed";
 
 export type ResolvedOpenAICompat = Required<
-	Omit<OpenAICompat, "openRouterRouting" | "vercelGatewayRouting" | "extraBody" | "toolStrictMode">
+	Omit<
+		OpenAICompat,
+		"openRouterRouting" | "vercelGatewayRouting" | "extraBody" | "toolStrictMode" | "toolChoiceSupport"
+	>
 > & {
 	openRouterRouting?: OpenAICompat["openRouterRouting"];
 	vercelGatewayRouting?: OpenAICompat["vercelGatewayRouting"];
 	extraBody?: OpenAICompat["extraBody"];
 	toolStrictMode: ResolvedToolStrictMode;
+	/** Optional explicit capability override; resolved via deriveToolChoiceSupport. */
+	toolChoiceSupport?: OpenAICompat["toolChoiceSupport"];
 };
 
 function detectStrictModeSupport(provider: string, baseUrl: string): boolean {
@@ -191,6 +196,7 @@ export function detectOpenAICompat(model: Model<"openai-completions">, resolvedB
 		disableReasoningOnForcedToolChoice: isKimiModel || isAnthropicModel,
 		disableReasoningOnToolChoice: isDeepseekFamily && Boolean(model.reasoning) && !isOpenRouter,
 		supportsToolChoice: !isDirectDeepseekReasoning,
+		supportsForcedToolChoice: true,
 		maxTokensField: useMaxTokens ? "max_tokens" : "max_completion_tokens",
 		requiresToolResultName: isMistral,
 		requiresAssistantAfterToolResult: false,
@@ -254,6 +260,8 @@ export function resolveOpenAICompat(
 		reasoningEffortMap: { ...detected.reasoningEffortMap, ...(model.compat.reasoningEffortMap ?? {}) },
 		supportsUsageInStreaming: model.compat.supportsUsageInStreaming ?? detected.supportsUsageInStreaming,
 		supportsToolChoice: model.compat.supportsToolChoice ?? detected.supportsToolChoice,
+		supportsForcedToolChoice: model.compat.supportsForcedToolChoice ?? detected.supportsForcedToolChoice,
+		toolChoiceSupport: model.compat.toolChoiceSupport ?? detected.toolChoiceSupport,
 		maxTokensField: model.compat.maxTokensField ?? detected.maxTokensField,
 		requiresToolResultName: model.compat.requiresToolResultName ?? detected.requiresToolResultName,
 		requiresAssistantAfterToolResult:

package/src/providers/openai-completions.ts

@@ -1,4 +1,4 @@
-import { $env, $inheritedEnv, extractHttpStatusFromError } from "@gajae-code/utils";
+import { $credentialEnv, $env, $inheritedEnv, extractHttpStatusFromError, logger } from "@gajae-code/utils";
 import OpenAI from "openai";
 import type {
 	ChatCompletionAssistantMessageParam,
@@ -61,6 +61,12 @@ import { adaptSchemaForStrict, NO_STRICT, toolWireSchema } from "../utils/schema
 import { wrapFetchForSseDebug } from "../utils/sse-debug";
 import { type HealedToolCall, modelMayLeakKimiToolCalls, ToolCallHealer } from "../utils/tool-call-healing";
 import { isForcedToolChoice, mapToOpenAICompletionsToolChoice } from "../utils/tool-choice";
+import {
+	isForcedToolChoiceUnsupportedError,
+	markToolChoiceIncapability,
+	resolveToolChoice,
+} from "../utils/tool-choice-capability";
+import { COMPOSER_EDIT_DISCIPLINE_PROMPT, isComposerHarnessModel } from "./composer-discipline";
 import {
 	buildCopilotDynamicHeaders,
 	hasCopilotVisionInput,
@@ -493,7 +499,25 @@ export const streamOpenAICompletions: StreamFunction<"openai-completions"> = (
 				});
 			} catch (error) {
 				const capturedErrorResponse = getCapturedErrorResponse();
-				if (
+				const sentForcedToolChoice = isForcedToolChoice(
+					(rawRequestDump?.body as { tool_choice?: unknown } | undefined)?.tool_choice,
+				);
+				if (firstTokenTime === undefined && isForcedToolChoiceUnsupportedError(error, sentForcedToolChoice)) {
+					const reason = await finalizeErrorMessage(error, rawRequestDump, capturedErrorResponse);
+					markToolChoiceIncapability(model, "auto", reason);
+					const resolvedToolChoice = resolveToolChoice(model, options?.toolChoice);
+					stream.push({
+						type: "toolChoiceIncapability",
+						api: model.api,
+						provider: model.provider,
+						model: model.id,
+						requestedLevel: resolvedToolChoice.requestedLevel,
+						resolvedLevel: "auto",
+						reason,
+						registryKey: resolvedToolChoice.registryKey,
+					});
+					openaiStream = await createCompletionsStream();
+				} else if (
 					isOpenRouterAnthropicModel(model) &&
 					!disableStrictTools &&
 					isCompiledGrammarTooLargeStrictError(error, capturedErrorResponse)
@@ -928,12 +952,12 @@ async function createClient(
 	clearCapturedErrorResponse: () => void;
 }> {
 	if (!apiKey) {
-		if (!$env.OPENAI_API_KEY) {
+		apiKey = $credentialEnv("OPENAI_API_KEY");
+		if (!apiKey) {
 			throw new Error(
 				"OpenAI API key is required. Set OPENAI_API_KEY environment variable or pass it as an argument.",
 			);
 		}
-		apiKey = $env.OPENAI_API_KEY;
 	}
 	const rawApiKey = apiKey;
 
@@ -1166,8 +1190,19 @@ function buildParams(
 		params.tools = [];
 	}
 
-	if (options?.toolChoice && compat.supportsToolChoice) {
-		params.tool_choice = mapToOpenAICompletionsToolChoice(options.toolChoice);
+	if (options?.toolChoice) {
+		const toolChoice = resolveToolChoice(model, options.toolChoice, compat);
+		if (toolChoice.degraded && toolChoice.supportSource === "runtime") {
+			logger.debug("openai-completions: degraded tool_choice after runtime capability discovery", {
+				model: model.id,
+				requestedLevel: toolChoice.requestedLevel,
+				resolvedLevel: toolChoice.resolvedLevel,
+				reason: toolChoice.reason,
+			});
+		}
+		if (toolChoice.resolvedChoice !== undefined) {
+			params.tool_choice = mapToOpenAICompletionsToolChoice(toolChoice.resolvedChoice);
+		}
 	}
 
 	if (params.tool_choice === "none" && (!Array.isArray(params.tools) || params.tools.length === 0)) {
@@ -1430,6 +1465,11 @@ export function convertMessages(
 	};
 
 	const systemPrompts = normalizeSystemPrompts(context.systemPrompt);
+	// Composer-harness models need anchor/edit discipline pinned ahead of the
+	// host prompt (see composer-discipline.ts for the observed failure modes).
+	if (systemPrompts.length > 0 && isComposerHarnessModel(model.id)) {
+		systemPrompts.unshift(COMPOSER_EDIT_DISCIPLINE_PROMPT);
+	}
 	if (systemPrompts.length > 0) {
 		const useDeveloperRole = model.reasoning && compat.supportsDeveloperRole;
 		const role = useDeveloperRole ? "developer" : "system";