@gajae-code/ai 0.2.3 → 0.2.4

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [0.2.4] - 2026-06-02
+
+### Added
+
+- Added configurable provider request and stream retry budgets so hosts can bound transient upstream/server retry behavior separately from session-level retries.
+
 ## [0.2.2] - 2026-05-31
 
 ### Fixed

package/dist/types/providers/anthropic.d.ts

@@ -118,6 +118,7 @@ export type AnthropicClientOptionsArgs = {
     hasTools?: boolean;
     onSseEvent?: AnthropicOptions["onSseEvent"];
     fetch?: FetchImpl;
+    requestMaxRetries?: number;
 };
 export type AnthropicClientOptionsResult = {
     isOAuthToken: boolean;

package/dist/types/types.d.ts

@@ -178,6 +178,16 @@ export interface StreamOptions {
      * Default: 60000 (60 seconds). Set to 0 to disable the cap.
      */
     maxRetryDelayMs?: number;
+    /**
+     * Maximum provider request retries for transports/SDKs that retry before a stream is established.
+     * Counts retries only, not the initial attempt. Providers keep their built-in default when unset.
+     */
+    requestMaxRetries?: number;
+    /**
+     * Maximum provider stream replay retries after a replay-safe transient stream failure.
+     * Counts retries only, not the initial stream attempt. Providers keep their built-in default when unset.
+     */
+    streamMaxRetries?: number;
     /**
      * Optional metadata to include in API requests.
      * Providers extract the fields they understand and ignore the rest.

package/dist/types/utils/retry-budget.d.ts

@@ -0,0 +1 @@
+export declare function resolveRetryBudget(value: number | undefined, fallback: number): number;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/ai",
-	"version": "0.2.3",
+	"version": "0.2.4",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"homepage": "https://gaebal-gajae.dev",
 	"author": "Yeachan-Heo",
@@ -43,7 +43,7 @@
 	"dependencies": {
 		"@anthropic-ai/sdk": "^0.94.0",
 		"@bufbuild/protobuf": "^2.12.0",
-		"@gajae-code/utils": "0.2.3",
+		"@gajae-code/utils": "0.2.4",
 		"openai": "^6.36.0",
 		"partial-json": "^0.1.7",
 		"zod": "4.4.3"

package/src/providers/amazon-bedrock.ts

@@ -31,6 +31,7 @@ import { normalizeToolCallId, resolveCacheRetention } from "../utils";
 import { AssistantMessageEventStream } from "../utils/event-stream";
 import { appendRawHttpRequestDumpFor400, type RawHttpRequestDump, withHttpStatus } from "../utils/http-inspector";
 import { parseStreamingJson } from "../utils/json-parse";
+import { resolveRetryBudget } from "../utils/retry-budget";
 import { toolWireSchema } from "../utils/schema/wire";
 import { resolveAwsCredentials } from "./aws-credentials";
 import { decodeEventStream } from "./aws-eventstream";
@@ -259,6 +260,7 @@ export const streamBedrock: StreamFunction<"bedrock-converse-stream"> = (
 				headers: requestHeaders,
 				body,
 				signal: options.signal,
+				maxAttempts: resolveRetryBudget(options.requestMaxRetries, 4) + 1,
 			});
 
 			if (!response.ok) {

package/src/providers/anthropic.ts

@@ -61,6 +61,7 @@ import { parseJsonWithRepair, parseStreamingJson } from "../utils/json-parse";
 import { parseGitHubCopilotApiKey } from "../utils/oauth/github-copilot";
 import { notifyProviderResponse } from "../utils/provider-response";
 import { isCopilotTransientModelError } from "../utils/retry";
+import { resolveRetryBudget } from "../utils/retry-budget";
 import { COMBINATOR_KEYS, NO_STRICT, toolWireSchema } from "../utils/schema";
 import { spillToDescription } from "../utils/schema/spill";
 import { notifyRawSseEvent, wrapFetchForSseDebug } from "../utils/sse-debug";
@@ -183,12 +184,14 @@ export function buildAnthropicHeaders(options: AnthropicHeaderOptions): Record<s
 			"User-Agent": userAgent,
 		};
 	} else if (!isAnthropicApiBaseUrl(options.baseUrl)) {
+		const incomingUserAgent = getHeaderCaseInsensitive(options.modelHeaders, "User-Agent");
 		return {
 			...modelHeaders,
 			Accept: acceptHeader,
 			Authorization: `Bearer ${options.apiKey}`,
 			...sharedHeaders,
 			"Anthropic-Beta": betaHeader,
+			...(incomingUserAgent ? { "User-Agent": incomingUserAgent } : {}),
 		};
 	} else {
 		return {
@@ -626,6 +629,7 @@ export type AnthropicClientOptionsArgs = {
 	hasTools?: boolean;
 	onSseEvent?: AnthropicOptions["onSseEvent"];
 	fetch?: FetchImpl;
+	requestMaxRetries?: number;
 };
 
 export type AnthropicClientOptionsResult = {
@@ -1057,6 +1061,7 @@ export const streamAnthropic: StreamFunction<"anthropic-messages"> = (
 					hasTools: !!context.tools?.length,
 					onSseEvent: options?.onSseEvent,
 					fetch: options?.fetch,
+					requestMaxRetries: options?.requestMaxRetries,
 				});
 				client = created.client;
 				isOAuthToken = created.isOAuthToken;
@@ -1445,7 +1450,7 @@ export const streamAnthropic: StreamFunction<"anthropic-messages"> = (
 						firstTokenTime === undefined && isProviderRetryableError(streamFailure, model.provider);
 					if (
 						activeAbortTracker.wasCallerAbort() ||
-						providerRetryAttempt >= PROVIDER_MAX_RETRIES ||
+						providerRetryAttempt >= resolveRetryBudget(options?.streamMaxRetries, PROVIDER_MAX_RETRIES) ||
 						(!canRetryTransientEnvelopeFailure && !canRetryProviderFailure)
 					) {
 						throw streamFailure;
@@ -1604,7 +1609,7 @@ export function buildAnthropicClientOptions(args: AnthropicClientOptionsArgs): A
 			apiKey: null,
 			authToken: copilotApiKey,
 			baseURL: baseUrl,
-			maxRetries: 5,
+			maxRetries: resolveRetryBudget(args.requestMaxRetries, 5),
 			dangerouslyAllowBrowser: true,
 			defaultHeaders,
 			logLevel: ANTHROPIC_SDK_LOG_LEVEL,
@@ -1637,7 +1642,7 @@ export function buildAnthropicClientOptions(args: AnthropicClientOptionsArgs): A
 			apiKey: null,
 			authToken: null,
 			baseURL: baseUrl,
-			maxRetries: 5,
+			maxRetries: resolveRetryBudget(args.requestMaxRetries, 5),
 			dangerouslyAllowBrowser: true,
 			defaultHeaders,
 			logLevel: ANTHROPIC_SDK_LOG_LEVEL,
@@ -1650,7 +1655,7 @@ export function buildAnthropicClientOptions(args: AnthropicClientOptionsArgs): A
 		apiKey: oauthToken ? null : apiKey,
 		authToken: oauthToken ? apiKey : undefined,
 		baseURL: baseUrl,
-		maxRetries: 5,
+		maxRetries: resolveRetryBudget(args.requestMaxRetries, 5),
 		dangerouslyAllowBrowser: true,
 		defaultHeaders,
 		logLevel: ANTHROPIC_SDK_LOG_LEVEL,

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

@@ -26,6 +26,7 @@ import {
 	getStreamFirstEventTimeoutMs,
 	iterateWithIdleTimeout,
 } from "../utils/idle-iterator";
+import { resolveRetryBudget } from "../utils/retry-budget";
 import { sanitizeSchemaForOpenAIResponses, toolWireSchema } from "../utils/schema";
 import { wrapFetchForSseDebug } from "../utils/sse-debug";
 import { mapToOpenAIResponsesToolChoice } from "../utils/tool-choice";
@@ -249,7 +250,7 @@ function createClient(model: Model<"azure-openai-responses">, apiKey: string, op
 		apiKey,
 		apiVersion,
 		dangerouslyAllowBrowser: true,
-		maxRetries: 5,
+		maxRetries: resolveRetryBudget(options?.requestMaxRetries, 5),
 		defaultHeaders: headers,
 		baseURL: baseUrl,
 		fetch: onSseEvent ? wrapFetchForSseDebug(baseFetch, event => onSseEvent(event, model)) : baseFetch,

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

@@ -21,6 +21,7 @@ import type {
 import { normalizeSystemPrompts } from "../utils";
 import { AssistantMessageEventStream } from "../utils/event-stream";
 import { appendRawHttpRequestDumpFor400, type RawHttpRequestDump, withHttpStatus } from "../utils/http-inspector";
+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";
@@ -340,7 +341,7 @@ export const streamGoogleGeminiCli: StreamFunction<"google-gemini-cli"> = (
 					headers: requestHeaders,
 					body: requestBodyJson,
 					signal: options?.signal,
-					maxAttempts: MAX_RETRIES + 1,
+					maxAttempts: resolveRetryBudget(options?.requestMaxRetries, MAX_RETRIES) + 1,
 					defaultDelayMs: attempt => BASE_DELAY_MS * 2 ** attempt,
 					maxDelayMs: options?.maxRetryDelayMs ?? RATE_LIMIT_BUDGET_MS,
 					fetch: options?.fetch,
@@ -509,7 +510,8 @@ export const streamGoogleGeminiCli: StreamFunction<"google-gemini-cli"> = (
 			let receivedContent = false;
 			let currentResponse = response;
 
-			for (let emptyAttempt = 0; emptyAttempt <= MAX_EMPTY_STREAM_RETRIES; emptyAttempt++) {
+			const emptyStreamRetryBudget = resolveRetryBudget(options?.streamMaxRetries, MAX_EMPTY_STREAM_RETRIES);
+			for (let emptyAttempt = 0; emptyAttempt <= emptyStreamRetryBudget; emptyAttempt++) {
 				if (options?.signal?.aborted) {
 					throw new Error("Request was aborted");
 				}
@@ -549,7 +551,7 @@ export const streamGoogleGeminiCli: StreamFunction<"google-gemini-cli"> = (
 					break;
 				}
 
-				if (emptyAttempt < MAX_EMPTY_STREAM_RETRIES) {
+				if (emptyAttempt < emptyStreamRetryBudget) {
 					resetOutput();
 				}
 			}

package/src/providers/ollama.ts

@@ -18,6 +18,7 @@ import { normalizeSystemPrompts } from "../utils";
 import { AssistantMessageEventStream } from "../utils/event-stream";
 import { finalizeErrorMessage, type RawHttpRequestDump } from "../utils/http-inspector";
 import { parseStreamingJson } from "../utils/json-parse";
+import { resolveRetryBudget } from "../utils/retry-budget";
 import { toolWireSchema } from "../utils/schema/wire";
 import { transformMessages } from "./transform-messages";
 
@@ -402,6 +403,7 @@ export const streamOllama: StreamFunction<"ollama-chat"> = (
 				},
 				body: JSON.stringify(body),
 				signal: options.signal,
+				maxAttempts: resolveRetryBudget(options.requestMaxRetries, 4) + 1,
 				defaultDelayMs: OLLAMA_RETRY_DELAYS_MS,
 				fetch: options.fetch,
 			});

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

@@ -49,6 +49,7 @@ import { AssistantMessageEventStream } from "../utils/event-stream";
 import { finalizeErrorMessage, type RawHttpRequestDump } from "../utils/http-inspector";
 import { getOpenAIStreamIdleTimeoutMs, iterateWithIdleTimeout } from "../utils/idle-iterator";
 import { parseStreamingJson } from "../utils/json-parse";
+import { resolveRetryBudget } from "../utils/retry-budget";
 import { adaptSchemaForStrict, NO_STRICT, sanitizeSchemaForOpenAIResponses, toolWireSchema } from "../utils/schema";
 import { compactGrammarDefinition } from "./grammar";
 import { CODEX_BASE_URL, getCodexAccountId, OPENAI_HEADER_VALUES, OPENAI_HEADERS } from "./openai-codex/constants";
@@ -227,7 +228,10 @@ function isCodexWebSocketEnvEnabled(): boolean {
 	return $flag("PI_CODEX_WEBSOCKET");
 }
 
-function getCodexWebSocketRetryBudget(): number {
+function getCodexWebSocketRetryBudget(options?: Pick<OpenAICodexResponsesOptions, "streamMaxRetries">): number {
+	if (options?.streamMaxRetries !== undefined) {
+		return resolveRetryBudget(options.streamMaxRetries, CODEX_WEBSOCKET_RETRY_BUDGET);
+	}
 	return parseCodexNonNegativeInteger($env.PI_CODEX_WEBSOCKET_RETRY_BUDGET, CODEX_WEBSOCKET_RETRY_BUDGET);
 }
 
@@ -641,7 +645,7 @@ async function openInitialCodexEventStream(
 }> {
 	const { transformedBody, websocketState } = requestContext;
 	if (websocketState && shouldUseCodexWebSocket(model, websocketState, options?.preferWebsockets)) {
-		const websocketRetryBudget = getCodexWebSocketRetryBudget();
+		const websocketRetryBudget = getCodexWebSocketRetryBudget(options);
 		let websocketRetries = 0;
 		while (true) {
 			try {
@@ -707,7 +711,7 @@ async function openCodexWebSocketTransport(
 		sentModelsEtagHeader: websocketHeaders.has(X_MODELS_ETAG_HEADER),
 		requestType: websocketRequest.type,
 		retry,
-		retryBudget: getCodexWebSocketRetryBudget(),
+		retryBudget: getCodexWebSocketRetryBudget(options),
 	});
 	const eventStream = await openCodexWebSocketEventStream(
 		toWebSocketUrl(requestContext.url),
@@ -744,6 +748,7 @@ async function openCodexSseTransport(
 			requestSetup.requestSignal,
 			event => options?.onSseEvent?.(event, model),
 			options?.fetch,
+			options,
 		),
 	);
 	return { eventStream, requestBodyForState: structuredCloneJSON(body), transport: "sse" };
@@ -1348,7 +1353,7 @@ async function tryRecoverCodexPreviousResponseNotFound(
 		runtime.transport !== "websocket" ||
 		context.output.content.length > 0 ||
 		context.options?.signal?.aborted ||
-		runtime.providerRetryAttempt >= CODEX_MAX_RETRIES
+		runtime.providerRetryAttempt >= resolveRetryBudget(context.options?.streamMaxRetries, CODEX_MAX_RETRIES)
 	) {
 		return false;
 	}
@@ -1390,12 +1395,14 @@ async function tryReplayWebsocketFailureOverSse(
 	const replayingBufferedOutputOverSse = context.output.content.length > 0;
 	const isFatal = isCodexWebSocketFatalError(streamError);
 	const activateFallback =
-		replayingBufferedOutputOverSse || isFatal || runtime.websocketStreamRetries >= getCodexWebSocketRetryBudget();
+		replayingBufferedOutputOverSse ||
+		isFatal ||
+		runtime.websocketStreamRetries >= getCodexWebSocketRetryBudget(context.options);
 	recordCodexWebSocketFailure(state, activateFallback);
 	logCodexDebug("codex websocket stream fallback", {
 		error: streamError.message,
 		retry: runtime.websocketStreamRetries,
-		retryBudget: getCodexWebSocketRetryBudget(),
+		retryBudget: getCodexWebSocketRetryBudget(context.options),
 		activated: activateFallback,
 		fatal: isFatal,
 		replayedBufferedOutput: replayingBufferedOutputOverSse,
@@ -1431,7 +1438,7 @@ async function tryRetryCodexProviderError(
 	if (
 		!isRetryableCodexProviderError(error) ||
 		context.output.content.length > 0 ||
-		runtime.providerRetryAttempt >= CODEX_MAX_RETRIES ||
+		runtime.providerRetryAttempt >= resolveRetryBudget(context.options?.streamMaxRetries, CODEX_MAX_RETRIES) ||
 		context.options?.signal?.aborted
 	) {
 		return false;
@@ -1447,7 +1454,7 @@ async function tryRetryCodexProviderError(
 	logCodexDebug("retrying codex provider stream error", {
 		error: error instanceof Error ? error.message : String(error),
 		retry: runtime.providerRetryAttempt,
-		retryBudget: CODEX_MAX_RETRIES,
+		retryBudget: resolveRetryBudget(context.options?.streamMaxRetries, CODEX_MAX_RETRIES),
 		transport: runtime.transport,
 	});
 
@@ -2187,6 +2194,7 @@ async function openCodexSseEventStream(
 	signal?: AbortSignal,
 	onSseEvent?: OpenAICodexResponsesOptions["onSseEvent"],
 	fetchOverride?: FetchImpl,
+	options?: Pick<OpenAICodexResponsesOptions, "requestMaxRetries">,
 ): Promise<AsyncGenerator<Record<string, unknown>>> {
 	const headers = createCodexHeaders(requestHeaders, accountId, apiKey, sessionId, "sse", state);
 	logCodexDebug("codex request", {
@@ -2201,7 +2209,7 @@ async function openCodexSseEventStream(
 		headers,
 		body: JSON.stringify(body),
 		signal,
-		maxAttempts: CODEX_MAX_RETRIES + 1,
+		maxAttempts: resolveRetryBudget(options?.requestMaxRetries, CODEX_MAX_RETRIES) + 1,
 		defaultDelayMs: attempt => CODEX_RETRY_DELAY_MS * (attempt + 1),
 		maxDelayMs: CODEX_RATE_LIMIT_BUDGET_MS,
 		fetch: fetchOverride,

package/src/providers/openai-completions.ts

@@ -56,6 +56,7 @@ import { parseGitHubCopilotApiKey } from "../utils/oauth/github-copilot";
 import { getKimiCommonHeaders } from "../utils/oauth/kimi";
 import { notifyProviderResponse } from "../utils/provider-response";
 import { callWithCopilotModelRetry } from "../utils/retry";
+import { resolveRetryBudget } from "../utils/retry-budget";
 import { adaptSchemaForStrict, NO_STRICT, toolWireSchema } from "../utils/schema";
 import { wrapFetchForSseDebug } from "../utils/sse-debug";
 import { type HealedToolCall, modelMayLeakKimiToolCalls, ToolCallHealer } from "../utils/tool-call-healing";
@@ -444,6 +445,7 @@ export const streamOpenAICompletions: StreamFunction<"openai-completions"> = (
 				options?.fetch,
 				options?.streamFirstEventTimeoutMs,
 				options?.authCredentialType,
+				options?.requestMaxRetries,
 			);
 			const premiumRequestsTotal = copilotPremiumRequests;
 			getCapturedErrorResponse = captureErrorResponse;
@@ -920,6 +922,7 @@ async function createClient(
 	fetchOverride?: FetchImpl,
 	streamFirstEventTimeoutOverride?: number,
 	authCredentialType?: OpenAICompletionsOptions["authCredentialType"],
+	requestMaxRetries?: number,
 ): Promise<{
 	client: OpenAI;
 	copilotPremiumRequests: number | undefined;
@@ -1051,7 +1054,7 @@ async function createClient(
 			apiKey,
 			baseURL: baseUrl,
 			dangerouslyAllowBrowser: true,
-			maxRetries: 5,
+			maxRetries: resolveRetryBudget(requestMaxRetries, 5),
 			defaultHeaders: headers,
 			defaultQuery: azureDefaultQuery,
 			fetch: debugFetch,

package/src/providers/openai-responses.ts

@@ -42,6 +42,7 @@ import {
 import { parseGitHubCopilotApiKey } from "../utils/oauth/github-copilot";
 import { notifyProviderResponse } from "../utils/provider-response";
 import { callWithCopilotModelRetry } from "../utils/retry";
+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";
@@ -253,6 +254,7 @@ export const streamOpenAIResponses: StreamFunction<"openai-responses"> = (
 				options?.onSseEvent,
 				options?.fetch,
 				options?.authCredentialType,
+				options?.requestMaxRetries,
 			);
 			const premiumRequestsTotal = copilotPremiumRequests;
 			const providerSessionState = getOpenAIResponsesProviderSessionState(model, options?.providerSessionState);
@@ -354,6 +356,7 @@ function createClient(
 	onSseEvent?: OpenAIResponsesOptions["onSseEvent"],
 	fetchOverride?: FetchImpl,
 	authCredentialType?: OpenAIResponsesOptions["authCredentialType"],
+	requestMaxRetries?: number,
 ): {
 	client: OpenAI;
 	copilotPremiumRequests: number | undefined;
@@ -410,7 +413,7 @@ function createClient(
 			apiKey,
 			baseURL: baseUrl,
 			dangerouslyAllowBrowser: true,
-			maxRetries: 5,
+			maxRetries: resolveRetryBudget(requestMaxRetries, 5),
 			defaultHeaders: headers,
 			fetch: onSseEvent
 				? wrapFetchForSseDebug(transformedFetch, event => onSseEvent(event, model))

package/src/stream.ts

@@ -563,6 +563,8 @@ function mapOptionsForApi<TApi extends Api>(
 		headers: options?.headers,
 		initiatorOverride: options?.initiatorOverride,
 		maxRetryDelayMs: options?.maxRetryDelayMs,
+		requestMaxRetries: options?.requestMaxRetries,
+		streamMaxRetries: options?.streamMaxRetries,
 		metadata: options?.metadata,
 		sessionId: options?.sessionId,
 		providerSessionState: options?.providerSessionState,

package/src/types.ts

@@ -310,6 +310,16 @@ export interface StreamOptions {
 	 * Default: 60000 (60 seconds). Set to 0 to disable the cap.
 	 */
 	maxRetryDelayMs?: number;
+	/**
+	 * Maximum provider request retries for transports/SDKs that retry before a stream is established.
+	 * Counts retries only, not the initial attempt. Providers keep their built-in default when unset.
+	 */
+	requestMaxRetries?: number;
+	/**
+	 * Maximum provider stream replay retries after a replay-safe transient stream failure.
+	 * Counts retries only, not the initial stream attempt. Providers keep their built-in default when unset.
+	 */
+	streamMaxRetries?: number;
 	/**
 	 * Optional metadata to include in API requests.
 	 * Providers extract the fields they understand and ignore the rest.

package/src/utils/retry-budget.ts

@@ -0,0 +1,4 @@
+export function resolveRetryBudget(value: number | undefined, fallback: number): number {
+	if (value === undefined || !Number.isFinite(value)) return fallback;
+	return Math.max(0, Math.floor(value));
+}