@gajae-code/ai 0.4.4 → 0.5.0

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";

package/src/providers/openai-request-transform.ts

@@ -39,6 +39,7 @@ const OPENAI_PROXY_STRIP_HEADERS = [
 	"x-stainless-helper-method",
 	"openai-organization",
 	"openai-project",
+	"openai-beta",
 ] as const;
 
 function resolveRequestTransform(

package/src/providers/openai-responses.ts

@@ -1,4 +1,11 @@
-import { $env, $inheritedEnv, extractHttpStatusFromError, structuredCloneJSON } from "@gajae-code/utils";
+import {
+	$credentialEnv,
+	$env,
+	$inheritedEnv,
+	extractHttpStatusFromError,
+	logger,
+	structuredCloneJSON,
+} from "@gajae-code/utils";
 import OpenAI from "openai";
 import type {
 	Tool as OpenAITool,
@@ -46,6 +53,11 @@ import { resolveRetryBudget } from "../utils/retry-budget";
 import { adaptSchemaForStrict, NO_STRICT, sanitizeSchemaForOpenAIResponses, toolWireSchema } from "../utils/schema";
 import { wrapFetchForSseDebug } from "../utils/sse-debug";
 import { mapToOpenAIResponsesToolChoice, type OpenAIResponsesToolChoice } from "../utils/tool-choice";
+import {
+	isForcedToolChoiceUnsupportedError,
+	markToolChoiceIncapability,
+	resolveToolChoice,
+} from "../utils/tool-choice-capability";
 import {
 	buildCopilotDynamicHeaders,
 	hasCopilotVisionInput,
@@ -278,7 +290,31 @@ export const streamOpenAIResponses: StreamFunction<"openai-responses"> = (
 					return data;
 				},
 				{ provider: model.provider, signal: requestSignal },
-			);
+			).catch(async error => {
+				if (!isForcedToolChoiceUnsupportedError(error, isForcedOpenAIResponsesToolChoice(params.tool_choice))) {
+					throw error;
+				}
+				const reason = await finalizeErrorMessage(error, 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,
+				});
+				delete params.tool_choice;
+				if (rawRequestDump) rawRequestDump.body = params;
+				const { data, response, request_id } = await client.responses
+					.create(params, { signal: requestSignal })
+					.withResponse();
+				await notifyProviderResponse(options, response, model, request_id);
+				return data;
+			});
 			const firstEventWatchdog = createWatchdog(
 				options?.streamFirstEventTimeoutMs ?? getStreamFirstEventTimeoutMs(idleTimeoutMs),
 				() => abortTracker.abortLocally(firstEventTimeoutAbortError),
@@ -363,12 +399,12 @@ function createClient(
 	baseUrl: string | undefined;
 } {
 	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;
 
@@ -490,7 +526,16 @@ function buildParams(
 	if (context.tools) {
 		params.tools = convertTools(context.tools, supportsStrictMode(model), model);
 		if (options?.toolChoice) {
-			params.tool_choice = mapOpenAIResponsesToolChoiceForTools(options.toolChoice, context.tools, model);
+			const toolChoice = resolveToolChoice(model, options.toolChoice);
+			if (toolChoice.degraded && toolChoice.supportSource === "runtime") {
+				logger.debug("openai-responses: degraded tool_choice after runtime capability discovery", {
+					model: model.id,
+					requestedLevel: toolChoice.requestedLevel,
+					resolvedLevel: toolChoice.resolvedLevel,
+					reason: toolChoice.reason,
+				});
+			}
+			params.tool_choice = mapOpenAIResponsesToolChoiceForTools(toolChoice.resolvedChoice, context.tools, model);
 		}
 		// The apply_patch spec §1 marks only `apply_patch` itself as
 		// `supports_parallel_tool_calls = false`. OpenAI's Responses API
@@ -651,6 +696,10 @@ export function mapOpenAIResponsesToolChoiceForTools(
 	return customTool ? { type: "custom", name: customTool.customWireName ?? customTool.name } : mapped;
 }
 
+function isForcedOpenAIResponsesToolChoice(choice: unknown): boolean {
+	return !!choice && choice !== "none" && choice !== "auto";
+}
+
 /** @internal Exported for tests. */
 export function convertTools(tools: Tool[], strictMode: boolean, model: Model<"openai-responses">): OpenAITool[] {
 	const allowFreeform = supportsFreeformApplyPatch(model);

package/src/providers/register-builtins.ts

@@ -6,9 +6,9 @@
  * openai) at startup. The loaded module promise is cached so subsequent calls
  * reuse the same import.
  *
- * NOTE: stream.ts currently imports providers directly, so this file is not yet
- * wired into the main streaming path. It provides the infrastructure for lazy
- * loading that can be integrated when stream.ts is refactored.
+ * stream.ts imports its provider stream functions from this module (see the
+ * lazy wrappers below), so this file IS the main streaming path's provider
+ * loader: heavy SDKs stay out of the CLI startup parse graph.
  */
 import type {
 	Api,
@@ -390,9 +390,8 @@ function loadBedrockProviderModule(): Promise<LazyProviderModule<"bedrock-conver
 // ---------------------------------------------------------------------------
 // Lazy stream function exports
 //
-// These use the same names as the direct provider stream functions. When
-// stream.ts is updated to import from this module instead of individual
-// providers, the lazy loading will take effect on the main code path.
+// Provider registry code imports these wrappers so the concrete provider modules
+// are loaded on first use instead of during package initialization.
 // ---------------------------------------------------------------------------
 
 export const streamAnthropic = createLazyStream(loadAnthropicProviderModule);

package/src/stream.ts

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { $env, $inheritedEnv, $pickenv, extractHttpStatusFromError } from "@gajae-code/utils";
+import { $credentialEnv, $env, $pickCredentialEnv, extractHttpStatusFromError } from "@gajae-code/utils";
 import { getCustomApi } from "./api-registry";
 import type { Effort } from "./model-thinking";
 import {
@@ -61,7 +61,7 @@ let cachedVertexAdcCredentialsExists: boolean | null = null;
 
 function hasVertexAdcCredentials(): boolean {
 	if (cachedVertexAdcCredentialsExists === null) {
-		const gacPath = $env.GOOGLE_APPLICATION_CREDENTIALS;
+		const gacPath = $credentialEnv("GOOGLE_APPLICATION_CREDENTIALS");
 		if (gacPath) {
 			cachedVertexAdcCredentialsExists = fs.existsSync(gacPath);
 		} else {
@@ -77,7 +77,7 @@ type KeyResolver = string | (() => string | undefined);
 
 const serviceProviderMap: Record<string, KeyResolver> = {
 	"alibaba-coding-plan": "ALIBABA_CODING_PLAN_API_KEY",
-	openai: () => $inheritedEnv("OPENAI_API_KEY") ?? $env.OPENAI_API_KEY,
+	openai: () => $credentialEnv("OPENAI_API_KEY"),
 	google: "GEMINI_API_KEY",
 	groq: "GROQ_API_KEY",
 	cerebras: "CEREBRAS_API_KEY",
@@ -107,18 +107,18 @@ const serviceProviderMap: Record<string, KeyResolver> = {
 	parallel: "PARALLEL_API_KEY",
 	kagi: "KAGI_API_KEY",
 	// GitHub Copilot uses GitHub personal access token
-	"github-copilot": () => $pickenv("COPILOT_GITHUB_TOKEN", "GH_TOKEN", "GITHUB_TOKEN"),
+	"github-copilot": () => $pickCredentialEnv("COPILOT_GITHUB_TOKEN", "GH_TOKEN", "GITHUB_TOKEN"),
 	// Foundry mode optionally switches Anthropic auth to enterprise gateway credentials.
 	anthropic: () =>
 		isFoundryEnabled()
-			? $pickenv("ANTHROPIC_FOUNDRY_API_KEY", "ANTHROPIC_OAUTH_TOKEN", "ANTHROPIC_API_KEY")
-			: $pickenv("ANTHROPIC_OAUTH_TOKEN", "ANTHROPIC_API_KEY"),
+			? $pickCredentialEnv("ANTHROPIC_FOUNDRY_API_KEY", "ANTHROPIC_OAUTH_TOKEN", "ANTHROPIC_API_KEY")
+			: $pickCredentialEnv("ANTHROPIC_OAUTH_TOKEN", "ANTHROPIC_API_KEY"),
 	"gitlab-duo": "GITLAB_TOKEN",
 	// Vertex AI supports either GOOGLE_CLOUD_API_KEY or Application Default Credentials.
 	"google-vertex": () => {
-		if ($env.GOOGLE_CLOUD_API_KEY) {
-			return $env.GOOGLE_CLOUD_API_KEY;
-		}
+		const googleCloudApiKey = $credentialEnv("GOOGLE_CLOUD_API_KEY");
+		if (googleCloudApiKey) return googleCloudApiKey;
+
 		const hasCredentials = hasVertexAdcCredentials();
 		const hasProject = !!($env.GOOGLE_CLOUD_PROJECT || $env.GCLOUD_PROJECT);
 		const hasLocation = !!$env.GOOGLE_CLOUD_LOCATION;
@@ -133,13 +133,18 @@ const serviceProviderMap: Record<string, KeyResolver> = {
 	// 4. AWS_CONTAINER_CREDENTIALS_* - ECS/Task IAM role credentials
 	// 5. AWS_WEB_IDENTITY_TOKEN_FILE + AWS_ROLE_ARN - IRSA (EKS) web identity
 	"amazon-bedrock": () => {
+		const awsProfile = $credentialEnv("AWS_PROFILE");
+		const awsAccessKeyId = $credentialEnv("AWS_ACCESS_KEY_ID");
+		const awsSecretAccessKey = $credentialEnv("AWS_SECRET_ACCESS_KEY");
+		const awsBearerToken = $credentialEnv("AWS_BEARER_TOKEN_BEDROCK");
 		const hasEcsCredentials =
-			!!$env.AWS_CONTAINER_CREDENTIALS_RELATIVE_URI || !!$env.AWS_CONTAINER_CREDENTIALS_FULL_URI;
-		const hasWebIdentity = !!$env.AWS_WEB_IDENTITY_TOKEN_FILE && !!$env.AWS_ROLE_ARN;
+			!!$credentialEnv("AWS_CONTAINER_CREDENTIALS_RELATIVE_URI") ||
+			!!$credentialEnv("AWS_CONTAINER_CREDENTIALS_FULL_URI");
+		const hasWebIdentity = !!$credentialEnv("AWS_WEB_IDENTITY_TOKEN_FILE") && !!$credentialEnv("AWS_ROLE_ARN");
 		if (
-			$env.AWS_PROFILE ||
-			($env.AWS_ACCESS_KEY_ID && $env.AWS_SECRET_ACCESS_KEY) ||
-			$env.AWS_BEARER_TOKEN_BEDROCK ||
+			awsProfile ||
+			(awsAccessKeyId && awsSecretAccessKey) ||
+			awsBearerToken ||
 			hasEcsCredentials ||
 			hasWebIdentity
 		) {
@@ -148,7 +153,7 @@ const serviceProviderMap: Record<string, KeyResolver> = {
 	},
 	synthetic: "SYNTHETIC_API_KEY",
 	"cloudflare-ai-gateway": "CLOUDFLARE_AI_GATEWAY_API_KEY",
-	huggingface: () => $pickenv("HUGGINGFACE_HUB_TOKEN", "HF_TOKEN"),
+	huggingface: () => $pickCredentialEnv("HUGGINGFACE_HUB_TOKEN", "HF_TOKEN"),
 	litellm: "LITELLM_API_KEY",
 	moonshot: "MOONSHOT_API_KEY",
 	nvidia: "NVIDIA_API_KEY",
@@ -158,7 +163,7 @@ const serviceProviderMap: Record<string, KeyResolver> = {
 	"ollama-cloud": "OLLAMA_CLOUD_API_KEY",
 	"llama.cpp": "LLAMA_CPP_API_KEY",
 	qianfan: "QIANFAN_API_KEY",
-	"qwen-portal": () => $pickenv("QWEN_OAUTH_TOKEN", "QWEN_PORTAL_API_KEY"),
+	"qwen-portal": () => $pickCredentialEnv("QWEN_OAUTH_TOKEN", "QWEN_PORTAL_API_KEY"),
 	together: "TOGETHER_API_KEY",
 	zenmux: "ZENMUX_API_KEY",
 	venice: "VENICE_API_KEY",
@@ -169,13 +174,13 @@ const serviceProviderMap: Record<string, KeyResolver> = {
 /**
  * Get API key for provider from known environment variables, e.g. OPENAI_API_KEY.
  *
- * Will not return API keys for providers that require OAuth tokens.
- * Checks Bun.env, then cwd/.env, then ~/.env.
+ * Provider authentication intentionally excludes cwd/.env values. Project dotenv files are
+ * loaded into $env for app/tool execution, but must not silently fund GJC model requests.
  */
 export function getEnvApiKey(provider: string): string | undefined {
 	const resolver = serviceProviderMap[provider];
 	if (typeof resolver === "string") {
-		return $env[resolver];
+		return $credentialEnv(resolver);
 	}
 	return resolver?.();
 }

package/src/types.ts

@@ -161,6 +161,18 @@ export type ToolChoice =
 	| { type: "function"; function: { name: string } }
 	| { type: "tool"; name: string };
 
+export type ToolChoiceSupport = "none" | "auto" | "required" | "named";
+export type ToolChoiceSupportSource = "static" | "derived" | "runtime";
+
+export interface ToolChoiceCompat {
+	/** Maximum supported tool_choice level. */
+	toolChoiceSupport?: ToolChoiceSupport;
+	/** Legacy flag for accepting the tool_choice parameter. */
+	supportsToolChoice?: boolean;
+	/** Legacy flag for forced tool_choice support. */
+	supportsForcedToolChoice?: boolean;
+}
+
 // Base options all providers share
 export type CacheRetention = "none" | "short" | "long";
 
@@ -705,13 +717,24 @@ export type AssistantMessageEvent =
 			contentIndex?: undefined;
 			reason: Extract<StopReason, "aborted" | "error">;
 			error: AssistantMessage;
+	  }
+	| {
+			type: "toolChoiceIncapability";
+			contentIndex?: undefined;
+			api: string;
+			provider: string;
+			model: string;
+			requestedLevel: ToolChoiceSupport;
+			resolvedLevel: ToolChoiceSupport;
+			reason: string;
+			registryKey: string;
 	  };
 
 /**
  * Compatibility settings for openai-completions API.
  * Use this to override URL-based auto-detection for custom providers.
  */
-export interface OpenAICompat {
+export interface OpenAICompat extends ToolChoiceCompat {
 	/** Whether the provider supports the `store` field. Default: auto-detected from URL. */
 	supportsStore?: boolean;
 	/** Whether the provider supports the `developer` role (vs `system`). Default: auto-detected from URL. */
@@ -757,6 +780,8 @@ export interface OpenAICompat {
 	requiresAssistantContentForToolCalls?: boolean;
 	/** Whether the provider supports the `tool_choice` parameter. Default: true. */
 	supportsToolChoice?: boolean;
+	/** Whether `tool_choice` may force a tool (`required` / named tool). Default: true. */
+	supportsForcedToolChoice?: boolean;
 	/**
 	 * Drop reasoning fields (`reasoning_effort`, OpenRouter `reasoning`) for
 	 * the request when `tool_choice` forces a tool call. Mirrors the Anthropic
@@ -789,7 +814,7 @@ export interface OpenAICompat {
  * Use this to disable features that strict-by-default Anthropic accepts but
  * that proxy gateways (Vertex AI, AWS Bedrock-style fronts, etc.) reject.
  */
-export interface AnthropicCompat {
+export interface AnthropicCompat extends ToolChoiceCompat {
 	/**
 	 * Drop the top-level `strict: true` field on tool definitions. Vertex AI's
 	 * Anthropic-compatible endpoint rejects unknown tool fields with
@@ -805,6 +830,10 @@ export interface AnthropicCompat {
 	disableAdaptiveThinking?: boolean;
 	/** Whether tools may include Anthropic's per-tool eager_input_streaming flag. Default: true. */
 	supportsEagerToolInputStreaming?: boolean;
+	/** Whether the provider accepts the `tool_choice` parameter at all. Default: true. */
+	supportsToolChoice?: boolean;
+	/** Whether `tool_choice` may force a tool (`any` / named `tool`). Default: true except known incompatible Anthropic models. */
+	supportsForcedToolChoice?: boolean;
 	/** Whether long prompt-cache retention (`ttl: "1h"`) is supported. Default: true for canonical Anthropic API. */
 	supportsLongCacheRetention?: boolean;
 }
@@ -907,7 +936,16 @@ export interface Model<TApi extends Api = any> {
 		? OpenAICompat
 		: TApi extends "anthropic-messages"
 			? AnthropicCompat
-			: never;
+			: TApi extends
+						| "bedrock-converse-stream"
+						| "google-generative-ai"
+						| "google-gemini-cli"
+						| "google-vertex"
+						| "ollama-chat"
+						| "azure-openai-responses"
+						| "openai-codex-responses"
+				? ToolChoiceCompat
+				: never;
 	/**
 	 * Which shape to use when exposing the OpenAI code backend `apply_patch` tool to this model.
 	 * Generated catalog policy sets `"freeform"` for first-party GPT-5 Responses