@gajae-code/ai 0.4.5 → 0.5.0

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/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
@@ -911,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

package/src/utils/event-stream.ts

@@ -2,7 +2,8 @@ import type { AssistantMessage, AssistantMessageEvent } from "../types";
 
 // Generic event stream class for async iteration
 export class EventStream<T, R = T> implements AsyncIterable<T> {
-	queue: T[] = [];
+	#queue: T[] = [];
+	#queueHead = 0;
 	waiting: Array<{ resolve: (value: IteratorResult<T>) => void; reject: (err: unknown) => void }> = [];
 	done = false;
 	#failed = false;
@@ -25,6 +26,35 @@ export class EventStream<T, R = T> implements AsyncIterable<T> {
 		this.extractResult = extractResult;
 	}
 
+	#enqueue(event: T): void {
+		this.#queue.push(event);
+	}
+
+	#dequeue(): T | undefined {
+		if (this.#queueHead >= this.#queue.length) return undefined;
+		const event = this.#queue[this.#queueHead]!;
+		this.#queue[this.#queueHead] = undefined as T;
+		this.#queueHead++;
+		if (this.#queueHead > 1024 && this.#queueHead * 2 >= this.#queue.length) {
+			this.#queue = this.#queue.slice(this.#queueHead);
+			this.#queueHead = 0;
+		}
+		return event;
+	}
+
+	get #queueLength(): number {
+		return this.#queue.length - this.#queueHead;
+	}
+
+	/**
+	 * Read-only snapshot of the not-yet-consumed events. Always a fresh copy:
+	 * external code can never mutate internal queue state or observe head-index
+	 * tombstones, so the deque cannot desynchronize.
+	 */
+	get queue(): T[] {
+		return this.#queue.slice(this.#queueHead);
+	}
+
 	push(event: T): void {
 		if (this.done) return;
 
@@ -38,7 +68,7 @@ export class EventStream<T, R = T> implements AsyncIterable<T> {
 		if (waiter) {
 			waiter.resolve({ value: event, done: false });
 		} else {
-			this.queue.push(event);
+			this.#enqueue(event);
 		}
 	}
 
@@ -47,7 +77,7 @@ export class EventStream<T, R = T> implements AsyncIterable<T> {
 		if (waiter) {
 			waiter.resolve({ value: event, done: false });
 		} else {
-			this.queue.push(event);
+			this.#enqueue(event);
 		}
 	}
 
@@ -84,8 +114,8 @@ export class EventStream<T, R = T> implements AsyncIterable<T> {
 
 	async *[Symbol.asyncIterator](): AsyncIterator<T> {
 		while (true) {
-			if (this.queue.length > 0) {
-				yield this.queue.shift()!;
+			if (this.#queueLength > 0) {
+				yield this.#dequeue()!;
 			} else if (this.#failed) {
 				throw this.#error;
 			} else if (this.done) {

package/src/utils/tool-choice-capability.ts

@@ -0,0 +1,220 @@
+import { extractHttpStatusFromError } from "@gajae-code/utils/fetch-retry";
+import * as logger from "@gajae-code/utils/logger";
+import type { Api, Model, ToolChoice, ToolChoiceCompat, ToolChoiceSupport, ToolChoiceSupportSource } from "../types";
+
+const supportRank: Record<ToolChoiceSupport, number> = {
+	none: 0,
+	auto: 1,
+	required: 2,
+	named: 3,
+};
+
+const registry = new Map<string, ToolChoiceSupport>();
+const loggedRegistryKeys = new Set<string>();
+
+/**
+ * Claude Mythos accepts tools but rejects forced tool use (Anthropic 400:
+ * "tool_choice forces tool use is not compatible with this model"). Catalog
+ * generation and dynamic discovery use this to default `toolChoiceSupport`.
+ */
+export function isClaudeForcedToolChoiceIncapableModelId(modelId: string): boolean {
+	return /(?:^|[/.])claude-mythos(?:-|$)/i.test(modelId);
+}
+
+/** Derives the effective static tool-choice support from compatibility flags. */
+export function deriveToolChoiceSupport(compat: ToolChoiceCompat | undefined): {
+	support: ToolChoiceSupport;
+	source: "static" | "derived";
+} {
+	if (compat?.toolChoiceSupport) {
+		return { support: compat.toolChoiceSupport, source: "static" };
+	}
+	if (compat?.supportsToolChoice === false) {
+		return { support: "none", source: "derived" };
+	}
+	if (compat?.supportsForcedToolChoice === false) {
+		return { support: "auto", source: "derived" };
+	}
+	return { support: "named", source: "derived" };
+}
+
+/** Returns the registry key used for runtime tool-choice capability overrides. */
+export function toolChoiceRegistryKey(model: Model<Api>): string {
+	return [model.api, model.provider, model.baseUrl, model.wireModelId ?? model.id].join("|");
+}
+
+/** Returns the current runtime tool-choice capability override for a model. */
+export function getToolChoiceCapabilityOverride(model: Model<Api>): ToolChoiceSupport | undefined {
+	return registry.get(toolChoiceRegistryKey(model));
+}
+
+/** Clears runtime tool-choice capability overrides for tests. */
+export function clearToolChoiceIncapabilityRegistryForTests(): void {
+	registry.clear();
+	loggedRegistryKeys.clear();
+}
+
+/** Records a discovered maximum supported tool-choice level for a model. */
+export function markToolChoiceIncapability(model: Model<Api>, maxSupport: ToolChoiceSupport, reason?: string): void {
+	const key = toolChoiceRegistryKey(model);
+	const existing = registry.get(key);
+	const next = existing && supportRank[existing] < supportRank[maxSupport] ? existing : maxSupport;
+	registry.set(key, next);
+
+	if (!loggedRegistryKeys.has(key)) {
+		loggedRegistryKeys.add(key);
+		logger.debug("Discovered tool_choice incapability", {
+			api: model.api,
+			provider: model.provider,
+			baseUrlHost: safeHostname(model.baseUrl),
+			model: model.wireModelId ?? model.id,
+			maxSupport,
+			reason,
+		});
+	}
+}
+
+/**
+ * Resolves a requested tool_choice against static and runtime capability limits.
+ * `compat` overrides `model.compat` for transports that layer URL/provider
+ * detection on top of explicit model overrides (e.g. resolveOpenAICompat).
+ */
+export function resolveToolChoice(
+	model: Model<Api>,
+	requested: ToolChoice | undefined,
+	compat?: ToolChoiceCompat,
+): ResolveToolChoiceResult {
+	const derived = deriveToolChoiceSupport(compat ?? model.compat);
+	const runtime = registry.get(toolChoiceRegistryKey(model));
+	const support = runtime && supportRank[runtime] < supportRank[derived.support] ? runtime : derived.support;
+	const supportSource: ToolChoiceSupportSource = support === derived.support ? derived.source : "runtime";
+	const requestedInfo = requestedToolChoiceLevel(requested);
+	const clampLevel = requestedInfo.requestedLevel === "none" ? "auto" : requestedInfo.requestedLevel;
+	const registryKey = toolChoiceRegistryKey(model);
+
+	if (requested === undefined) {
+		return {
+			requestedChoice: requested,
+			requestedLevel: requestedInfo.requestedLevel,
+			resolvedChoice: undefined,
+			resolvedLevel: "auto",
+			support,
+			supportSource,
+			degraded: false,
+			registryKey,
+		};
+	}
+
+	if (support === "none") {
+		return {
+			requestedChoice: requested,
+			requestedLevel: requestedInfo.requestedLevel,
+			resolvedChoice: undefined,
+			resolvedLevel: "none",
+			support,
+			supportSource,
+			degraded: requestedInfo.requestedLevel !== "none",
+			reason: "tool_choice is not supported by this model",
+			registryKey,
+			targetToolName: requestedInfo.targetToolName,
+		};
+	}
+
+	if (supportRank[support] >= supportRank[clampLevel]) {
+		return {
+			requestedChoice: requested,
+			requestedLevel: requestedInfo.requestedLevel,
+			resolvedChoice: requested,
+			resolvedLevel: requestedInfo.requestedLevel,
+			support,
+			supportSource,
+			degraded: false,
+			registryKey,
+			targetToolName: requestedInfo.targetToolName,
+		};
+	}
+
+	if (requestedInfo.requestedLevel === "named" && support === "required") {
+		return {
+			requestedChoice: requested,
+			requestedLevel: "named",
+			resolvedChoice: "required",
+			resolvedLevel: "required",
+			support,
+			supportSource,
+			degraded: true,
+			reason: "named tool_choice degraded to required",
+			registryKey,
+			targetToolName: requestedInfo.targetToolName,
+		};
+	}
+
+	return {
+		requestedChoice: requested,
+		requestedLevel: requestedInfo.requestedLevel,
+		resolvedChoice: undefined,
+		resolvedLevel: support === "auto" ? "auto" : "none",
+		support,
+		supportSource,
+		degraded: true,
+		reason: "forced tool_choice is not supported by this model",
+		registryKey,
+		targetToolName: requestedInfo.targetToolName,
+	};
+}
+
+/** Detects provider errors indicating forced tool_choice is unsupported. */
+export function isForcedToolChoiceUnsupportedError(error: unknown, sentForcedToolChoice: boolean): boolean {
+	if (!sentForcedToolChoice || extractHttpStatusFromError(error) !== 400) return false;
+	const message = errorMessage(error);
+	return (
+		// `by <something>` continuations ("not supported by billing") describe a
+		// different subject than the model's tool_choice capability — reject them
+		// unless the continuation names the model itself.
+		/tool[_\s-]?choices?\b.*?(not\s+compatible|incompatible|not\s+supported)(?!\s+by\s+(?!(?:this|the)\s+model\b|model\b))/is.test(
+			message,
+		) ||
+		/forces?\s+tool\s+use.*?(not\s+compatible|incompatible|not\s+supported)/is.test(message) ||
+		/does\s+not\s+support\s+forced\s+tool[_\s-]?choices?/is.test(message)
+	);
+}
+
+export type { ToolChoiceCompat, ToolChoiceSupport, ToolChoiceSupportSource } from "../types";
+
+export interface ResolveToolChoiceResult {
+	requestedChoice: ToolChoice | undefined;
+	requestedLevel: ToolChoiceSupport;
+	resolvedChoice: ToolChoice | undefined;
+	resolvedLevel: ToolChoiceSupport;
+	support: ToolChoiceSupport;
+	supportSource: ToolChoiceSupportSource;
+	degraded: boolean;
+	reason?: string;
+	registryKey: string;
+	targetToolName?: string;
+}
+
+function requestedToolChoiceLevel(requested: ToolChoice | undefined): {
+	requestedLevel: ToolChoiceSupport;
+	targetToolName?: string;
+} {
+	if (requested === undefined || requested === "auto") return { requestedLevel: "auto" };
+	if (requested === "none") return { requestedLevel: "none" };
+	if (requested === "any" || requested === "required") return { requestedLevel: "required" };
+	if ("name" in requested) return { requestedLevel: "named", targetToolName: requested.name };
+	return { requestedLevel: "named", targetToolName: requested.function.name };
+}
+
+function errorMessage(error: unknown): string {
+	if (error instanceof Error) return error.message;
+	if (typeof error === "string") return error;
+	return String(error);
+}
+
+function safeHostname(baseUrl: string): string | undefined {
+	try {
+		return new URL(baseUrl).hostname;
+	} catch {
+		return undefined;
+	}
+}