@gajae-code/ai 0.12.0 → 0.12.2

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

@@ -48,9 +48,13 @@ import {
 	sanitizeOpenAIResponsesHistoryItemsForReplay,
 } from "../utils";
 import { AssistantMessageEventStream } from "../utils/event-stream";
-import { transportFailureFacts } from "../utils/fallback-transport";
+import { STREAM_FIRST_EVENT_TIMEOUT_PROVIDER_CODE, transportFailureFacts } from "../utils/fallback-transport";
 import { finalizeErrorMessage, type RawHttpRequestDump } from "../utils/http-inspector";
-import { getOpenAIStreamIdleTimeoutMs, iterateWithIdleTimeout } from "../utils/idle-iterator";
+import {
+	getOpenAIStreamIdleTimeoutMs,
+	getStreamFirstEventTimeoutMs,
+	iterateWithIdleTimeout,
+} from "../utils/idle-iterator";
 import { parseStreamingJson } from "../utils/json-parse";
 import { resolveRetryBudget } from "../utils/retry-budget";
 import {
@@ -103,7 +107,6 @@ const CODEX_MAX_RETRIES = 5;
 const CODEX_RETRY_DELAY_MS = 500;
 const CODEX_WEBSOCKET_CONNECT_TIMEOUT_MS = 10000;
 const CODEX_WEBSOCKET_IDLE_TIMEOUT_MS = 300000;
-const CODEX_WEBSOCKET_FIRST_EVENT_TIMEOUT_MS = 15000;
 const CODEX_WEBSOCKET_RETRY_BUDGET = CODEX_MAX_RETRIES;
 const CODEX_WEBSOCKET_TRANSPORT_ERROR_PREFIX = "Codex websocket transport error";
 const CODEX_PREVIOUS_RESPONSE_STALE_CODES = new Set(["previous_response_not_found", "codex_previous_response_stale"]);
@@ -274,6 +277,7 @@ async function retryCodexInitialTransportWithoutToolChoice(
 
 interface CodexRequestSetup {
 	requestSignal: AbortSignal;
+	firstEventTimeoutMs: number | undefined;
 	wrapCodexSseStream: (source: AsyncGenerator<Record<string, unknown>>) => AsyncGenerator<Record<string, unknown>>;
 	requestAbortController: AbortController;
 }
@@ -355,16 +359,6 @@ function getCodexWebSocketIdleTimeoutMs(overrideMs?: number): number {
 	);
 }
 
-function getCodexWebSocketFirstEventTimeoutMs(idleTimeoutMs: number, overrideMs?: number): number {
-	return (
-		overrideMs ??
-		parseCodexPositiveInteger(
-			$env.PI_CODEX_WEBSOCKET_FIRST_EVENT_TIMEOUT_MS,
-			Math.min(CODEX_WEBSOCKET_FIRST_EVENT_TIMEOUT_MS, idleTimeoutMs),
-		)
-	);
-}
-
 function createCodexProviderSessionState(): CodexProviderSessionState {
 	const state: CodexProviderSessionState = {
 		webSocketSessions: new Map(),
@@ -391,8 +385,12 @@ function getCodexProviderSessionState(
 	return created;
 }
 
-function createCodexWebSocketTransportError(message: string): Error {
-	return new Error(`${CODEX_WEBSOCKET_TRANSPORT_ERROR_PREFIX}: ${message}`);
+function createCodexWebSocketTransportError(message: string, providerCode?: string): Error & { providerCode?: string } {
+	const error = new Error(`${CODEX_WEBSOCKET_TRANSPORT_ERROR_PREFIX}: ${message}`) as Error & {
+		providerCode?: string;
+	};
+	error.providerCode = providerCode;
+	return error;
 }
 
 function isCodexWebSocketFatalError(error: Error): boolean {
@@ -405,6 +403,13 @@ function isCodexWebSocketTransportError(error: unknown): boolean {
 	return error.message.startsWith(CODEX_WEBSOCKET_TRANSPORT_ERROR_PREFIX);
 }
 
+function isCodexFirstEventTimeout(error: unknown): boolean {
+	return (
+		error instanceof Error &&
+		(error as { providerCode?: unknown }).providerCode === STREAM_FIRST_EVENT_TIMEOUT_PROVIDER_CODE
+	);
+}
+
 function isCodexWebSocketRetryableStreamError(error: unknown): boolean {
 	if (!(error instanceof Error) || !isCodexWebSocketTransportError(error)) return false;
 	const message = error.message.toLowerCase();
@@ -607,17 +612,22 @@ function createRequestSetup(options: OpenAICodexResponsesOptions | undefined): C
 	const requestSignal = options?.signal
 		? AbortSignal.any([options.signal, requestAbortController.signal])
 		: requestAbortController.signal;
+	const idleTimeoutMs = options?.streamIdleTimeoutMs ?? getOpenAIStreamIdleTimeoutMs();
+	const firstEventTimeoutMs = options?.streamFirstEventTimeoutMs ?? getStreamFirstEventTimeoutMs(idleTimeoutMs);
 	const wrapCodexSseStream = (
 		source: AsyncGenerator<Record<string, unknown>>,
 	): AsyncGenerator<Record<string, unknown>> =>
 		iterateWithIdleTimeout(source, {
-			idleTimeoutMs: options?.streamIdleTimeoutMs ?? getOpenAIStreamIdleTimeoutMs(),
+			idleTimeoutMs,
+			firstItemTimeoutMs: firstEventTimeoutMs,
+			firstItemErrorMessage: "OpenAI Codex SSE stream timed out while waiting for the first event",
 			errorMessage: "OpenAI Codex SSE stream stalled while waiting for the next event",
 			onIdle: () => requestAbortController.abort(),
+			onFirstItemTimeout: () => requestAbortController.abort(),
 			abortSignal: options?.signal,
 			isProgressItem: isCodexStreamProgressEvent,
 		});
-	return { requestAbortController, requestSignal, wrapCodexSseStream };
+	return { requestAbortController, requestSignal, firstEventTimeoutMs, wrapCodexSseStream };
 }
 
 async function buildCodexRequestContext(
@@ -838,6 +848,7 @@ async function openCodexWebSocketTransport(
 		websocketState,
 		requestSetup.requestSignal,
 		options,
+		requestSetup.firstEventTimeoutMs,
 	);
 	return { eventStream, requestBodyForState, transport: "websocket" };
 }
@@ -1478,7 +1489,7 @@ async function recoverCodexStreamError(
 	runtime: CodexStreamRuntime,
 	error: unknown,
 ): Promise<boolean> {
-	if (context.options?.fallbackManaged) return false;
+	if (isCodexFirstEventTimeout(error)) return false;
 	if (await tryRetryWithoutForcedToolChoice(context, runtime, error)) {
 		return true;
 	}
@@ -2196,7 +2207,6 @@ function headersToRecord(headers: Headers): Record<string, string> {
 
 interface CodexWebSocketConnectionOptions {
 	idleTimeoutMs: number;
-	firstEventTimeoutMs: number;
 	onHandshakeHeaders?: (headers: Headers) => void;
 }
 
@@ -2204,7 +2214,6 @@ class CodexWebSocketConnection {
 	#url: string;
 	#headers: Record<string, string>;
 	#idleTimeoutMs: number;
-	#firstEventTimeoutMs: number;
 	#onHandshakeHeaders?: (headers: Headers) => void;
 	#socket: Bun.WebSocket | null = null;
 	#queue: Array<Record<string, unknown> | Error | null> = [];
@@ -2216,7 +2225,6 @@ class CodexWebSocketConnection {
 		this.#url = url;
 		this.#headers = headers;
 		this.#idleTimeoutMs = options.idleTimeoutMs;
-		this.#firstEventTimeoutMs = options.firstEventTimeoutMs;
 		this.#onHandshakeHeaders = options.onHandshakeHeaders;
 	}
 
@@ -2346,6 +2354,7 @@ class CodexWebSocketConnection {
 	async *streamRequest(
 		request: Record<string, unknown>,
 		signal?: AbortSignal,
+		firstEventTimeoutMs?: number,
 	): AsyncGenerator<Record<string, unknown>> {
 		if (!this.#socket || this.#socket.readyState !== WebSocket.OPEN) {
 			throw createCodexWebSocketTransportError("websocket connection is unavailable");
@@ -2368,11 +2377,11 @@ class CodexWebSocketConnection {
 
 		try {
 			this.#socket.send(JSON.stringify(request));
-			let sawFirstEvent = false;
+			let sawFirstProgress = false;
 			let lastProgressAt = Date.now();
 			while (true) {
-				let timeoutMs = this.#firstEventTimeoutMs;
-				if (sawFirstEvent) {
+				let timeoutMs = firstEventTimeoutMs;
+				if (sawFirstProgress) {
 					timeoutMs = this.#idleTimeoutMs - (Date.now() - lastProgressAt);
 					if (timeoutMs <= 0) {
 						throw createCodexWebSocketTransportError("idle timeout waiting for websocket");
@@ -2380,7 +2389,8 @@ class CodexWebSocketConnection {
 				}
 				const next = await this.#nextMessage(
 					timeoutMs,
-					sawFirstEvent ? "idle timeout waiting for websocket" : "timeout waiting for first websocket event",
+					sawFirstProgress ? "idle timeout waiting for websocket" : "timeout waiting for first websocket event",
+					sawFirstProgress ? undefined : STREAM_FIRST_EVENT_TIMEOUT_PROVIDER_CODE,
 				);
 				if (next instanceof Error) {
 					throw next;
@@ -2388,8 +2398,8 @@ class CodexWebSocketConnection {
 				if (next === null) {
 					throw createCodexWebSocketTransportError("websocket closed before response completion");
 				}
-				sawFirstEvent = true;
 				if (isCodexStreamProgressEvent(next)) {
+					sawFirstProgress = true;
 					lastProgressAt = Date.now();
 				}
 				yield next;
@@ -2425,13 +2435,17 @@ class CodexWebSocketConnection {
 		if (waiter) waiter();
 	}
 
-	async #nextMessage(timeoutMs: number, timeoutReason: string): Promise<Record<string, unknown> | Error | null> {
+	async #nextMessage(
+		timeoutMs: number | undefined,
+		timeoutReason: string,
+		providerCode?: string,
+	): Promise<Record<string, unknown> | Error | null> {
 		while (this.#queue.length === 0) {
 			const { promise, resolve } = Promise.withResolvers<void>();
 			this.#waiters.push(resolve);
 			let timedOut = false;
 			let timeout: NodeJS.Timeout | undefined;
-			if (timeoutMs > 0) {
+			if (timeoutMs !== undefined && timeoutMs > 0) {
 				timeout = setTimeout(() => {
 					timedOut = true;
 					const waiterIndex = this.#waiters.indexOf(resolve);
@@ -2444,7 +2458,10 @@ class CodexWebSocketConnection {
 			await promise;
 			if (timeout) clearTimeout(timeout);
 			if (timedOut && this.#queue.length === 0) {
-				return createCodexWebSocketTransportError(timeoutReason);
+				if (providerCode === STREAM_FIRST_EVENT_TIMEOUT_PROVIDER_CODE) {
+					this.close("first-event-timeout");
+				}
+				return createCodexWebSocketTransportError(timeoutReason, providerCode);
 			}
 		}
 		return this.#queue.shift() ?? null;
@@ -2473,7 +2490,6 @@ async function getOrCreateCodexWebSocketConnection(
 	const idleTimeoutMs = getCodexWebSocketIdleTimeoutMs(options?.streamIdleTimeoutMs);
 	state.connection = new CodexWebSocketConnection(url, headerRecord, {
 		idleTimeoutMs,
-		firstEventTimeoutMs: getCodexWebSocketFirstEventTimeoutMs(idleTimeoutMs, options?.streamFirstEventTimeoutMs),
 		onHandshakeHeaders: handshakeHeaders => {
 			updateCodexSessionMetadataFromHeaders(state, handshakeHeaders);
 		},
@@ -2544,9 +2560,10 @@ async function openCodexWebSocketEventStream(
 	state: CodexWebSocketSessionState,
 	signal?: AbortSignal,
 	options?: Pick<OpenAICodexResponsesOptions, "streamFirstEventTimeoutMs" | "streamIdleTimeoutMs">,
+	firstEventTimeoutMs?: number,
 ): Promise<AsyncGenerator<Record<string, unknown>>> {
 	const connection = await getOrCreateCodexWebSocketConnection(state, url, headers, signal, options);
-	return connection.streamRequest(request, signal);
+	return connection.streamRequest(request, signal, firstEventTimeoutMs);
 }
 
 function createCodexHeaders(

package/src/providers/openai-completions.ts

@@ -47,7 +47,6 @@ import {
 	rewriteCopilotError,
 } from "../utils/http-inspector";
 import {
-	createWatchdog,
 	getOpenAIStreamIdleTimeoutMs,
 	getProviderFirstEventTimeoutFallbackMs,
 	getStreamFirstEventTimeoutMs,
@@ -457,7 +456,6 @@ export const streamOpenAICompletions: StreamFunction<"openai-completions"> = (
 		const output: AssistantMessage = createInitialResponsesAssistantMessage(model.api, model.provider, model.id);
 		let rawRequestDump: RawHttpRequestDump | undefined;
 		const abortTracker = createAbortSourceTracker(options?.signal);
-		const firstEventTimeoutAbortError = new Error(OPENAI_COMPLETIONS_FIRST_EVENT_TIMEOUT_MESSAGE);
 		const { requestAbortController, requestSignal } = abortTracker;
 
 		try {
@@ -579,10 +577,8 @@ export const streamOpenAICompletions: StreamFunction<"openai-completions"> = (
 				model.provider === "alibaba-token-plan"
 					? ALIBABA_TOKEN_PLAN_FIRST_EVENT_TIMEOUT_MS
 					: getProviderFirstEventTimeoutFallbackMs(model.provider);
-			const firstEventWatchdog = createWatchdog(
-				options?.streamFirstEventTimeoutMs ?? getStreamFirstEventTimeoutMs(idleTimeoutMs, firstEventFallbackMs),
-				() => abortTracker.abortLocally(firstEventTimeoutAbortError),
-			);
+			const firstEventTimeoutMs =
+				options?.streamFirstEventTimeoutMs ?? getStreamFirstEventTimeoutMs(idleTimeoutMs, firstEventFallbackMs);
 			if (premiumRequestsTotal !== undefined) {
 				output.usage.premiumRequests = premiumRequestsTotal;
 			}
@@ -769,10 +765,12 @@ export const streamOpenAICompletions: StreamFunction<"openai-completions"> = (
 			};
 
 			for await (const chunk of iterateWithIdleTimeout(openaiStream, {
-				watchdog: firstEventWatchdog,
+				firstItemTimeoutMs: firstEventTimeoutMs,
+				firstItemErrorMessage: OPENAI_COMPLETIONS_FIRST_EVENT_TIMEOUT_MESSAGE,
 				idleTimeoutMs,
 				errorMessage: "OpenAI completions stream stalled while waiting for the next event",
 				onIdle: () => requestAbortController.abort(),
+				onFirstItemTimeout: () => requestAbortController.abort(),
 				abortSignal: options?.signal,
 				isProgressItem: isOpenAICompletionsProgressChunk,
 			})) {
@@ -983,14 +981,17 @@ export const streamOpenAICompletions: StreamFunction<"openai-completions"> = (
 			stream.end();
 		} catch (error) {
 			for (const block of output.content) delete (block as any).index;
-			const firstEventTimeoutError = abortTracker.getLocalAbortReason();
+			const localAbortReason = abortTracker.getLocalAbortReason();
 			const capturedErrorResponse = getCapturedErrorResponse?.();
 			output.stopReason = abortTracker.wasCallerAbort() ? "aborted" : "error";
-			output.errorStatus = extractHttpStatusFromError(error) ?? capturedErrorResponse?.status;
-			output.transportFailure = transportFailureFacts(error, capturedErrorResponse);
+			output.errorStatus =
+				extractHttpStatusFromError(localAbortReason ?? error) ??
+				(localAbortReason ? undefined : capturedErrorResponse?.status);
+			output.transportFailure = localAbortReason
+				? transportFailureFacts(localAbortReason)
+				: transportFailureFacts(error, capturedErrorResponse);
 			output.errorMessage =
-				firstEventTimeoutError?.message ??
-				(await finalizeErrorMessage(error, rawRequestDump, capturedErrorResponse));
+				localAbortReason?.message ?? (await finalizeErrorMessage(error, rawRequestDump, capturedErrorResponse));
 			// Some providers via OpenRouter include extra details here.
 			const rawMetadata = (error as { error?: { metadata?: { raw?: string } } })?.error?.metadata?.raw;
 			if (rawMetadata) output.errorMessage += `\n${rawMetadata}`;

package/src/providers/openai-responses.ts

@@ -37,7 +37,6 @@ import { AssistantMessageEventStream } from "../utils/event-stream";
 import { transportFailureFacts } from "../utils/fallback-transport";
 import { finalizeErrorMessage, type RawHttpRequestDump, rewriteCopilotError } from "../utils/http-inspector";
 import {
-	createWatchdog,
 	getOpenAIStreamIdleTimeoutMs,
 	getStreamFirstEventTimeoutMs,
 	iterateWithIdleTimeout,
@@ -265,7 +264,6 @@ export const streamOpenAIResponses: StreamFunction<"openai-responses"> = (
 		);
 		let rawRequestDump: RawHttpRequestDump | undefined;
 		const abortTracker = createAbortSourceTracker(options?.signal);
-		const firstEventTimeoutAbortError = new Error(OPENAI_RESPONSES_FIRST_EVENT_TIMEOUT_MESSAGE);
 		const { requestAbortController, requestSignal } = abortTracker;
 
 		try {
@@ -337,10 +335,8 @@ export const streamOpenAIResponses: StreamFunction<"openai-responses"> = (
 			});
 			const firstEventFallbackMs =
 				model.provider === "alibaba-token-plan" ? ALIBABA_TOKEN_PLAN_FIRST_EVENT_TIMEOUT_MS : undefined;
-			const firstEventWatchdog = createWatchdog(
-				options?.streamFirstEventTimeoutMs ?? getStreamFirstEventTimeoutMs(idleTimeoutMs, firstEventFallbackMs),
-				() => abortTracker.abortLocally(firstEventTimeoutAbortError),
-			);
+			const firstEventTimeoutMs =
+				options?.streamFirstEventTimeoutMs ?? getStreamFirstEventTimeoutMs(idleTimeoutMs, firstEventFallbackMs);
 			if (premiumRequestsTotal !== undefined) output.usage.premiumRequests = premiumRequestsTotal;
 			stream.push({ type: "start", partial: output });
 
@@ -348,9 +344,11 @@ export const streamOpenAIResponses: StreamFunction<"openai-responses"> = (
 			await processResponsesStream(
 				iterateWithIdleTimeout(openaiStream, {
 					idleTimeoutMs,
-					watchdog: firstEventWatchdog,
+					firstItemTimeoutMs: firstEventTimeoutMs,
+					firstItemErrorMessage: OPENAI_RESPONSES_FIRST_EVENT_TIMEOUT_MESSAGE,
 					errorMessage: "OpenAI responses stream stalled while waiting for the next event",
 					onIdle: () => requestAbortController.abort(),
+					onFirstItemTimeout: () => requestAbortController.abort(),
 					abortSignal: options?.signal,
 					isProgressItem: isOpenAIResponsesProgressEvent,
 				}),
@@ -389,11 +387,11 @@ export const streamOpenAIResponses: StreamFunction<"openai-responses"> = (
 			stream.end();
 		} catch (error) {
 			for (const block of output.content) delete (block as { index?: number }).index;
-			const firstEventTimeoutError = abortTracker.getLocalAbortReason();
+			const localAbortReason = abortTracker.getLocalAbortReason();
 			output.stopReason = abortTracker.wasCallerAbort() ? "aborted" : "error";
-			output.errorStatus = extractHttpStatusFromError(error);
-			output.transportFailure = transportFailureFacts(error);
-			output.errorMessage = firstEventTimeoutError?.message ?? (await finalizeErrorMessage(error, rawRequestDump));
+			output.errorStatus = extractHttpStatusFromError(localAbortReason ?? error);
+			output.transportFailure = transportFailureFacts(localAbortReason ?? error);
+			output.errorMessage = localAbortReason?.message ?? (await finalizeErrorMessage(error, rawRequestDump));
 			output.errorMessage = rewriteCopilotError(output.errorMessage, error, model.provider);
 			// Explicitly mark the poisoned-history rejection so the shared
 			// `invalid_prompt` contract is present even when the SDK error surfaces

package/src/providers/register-builtins.ts

@@ -10,6 +10,7 @@
  * 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,
 	AssistantMessage,
@@ -21,7 +22,13 @@ import type {
 } from "../types";
 import { type AbortSourceTracker, createAbortSourceTracker } from "../utils/abort";
 import { AssistantMessageEventStream as EventStreamImpl } from "../utils/event-stream";
-import { getStreamFirstEventTimeoutMs, getStreamIdleTimeoutMs, iterateWithIdleTimeout } from "../utils/idle-iterator";
+import { transportFailureFacts } from "../utils/fallback-transport";
+import {
+	FirstEventTimeoutError,
+	getStreamFirstEventTimeoutMs,
+	getStreamIdleTimeoutMs,
+	iterateWithIdleTimeout,
+} from "../utils/idle-iterator";
 import type { BedrockOptions } from "./amazon-bedrock";
 import type { AnthropicOptions } from "./anthropic";
 import type { AzureOpenAIResponsesOptions } from "./azure-openai-responses";
@@ -229,7 +236,8 @@ function forwardStream<TApi extends Api>(
 				errorMessage: LAZY_STREAM_IDLE_TIMEOUT_ERROR,
 				firstItemErrorMessage: LAZY_STREAM_FIRST_EVENT_TIMEOUT_ERROR,
 				onIdle: () => abortTracker.abortLocally(new Error(LAZY_STREAM_IDLE_TIMEOUT_ERROR)),
-				onFirstItemTimeout: () => abortTracker.abortLocally(new Error(LAZY_STREAM_FIRST_EVENT_TIMEOUT_ERROR)),
+				onFirstItemTimeout: () =>
+					abortTracker.abortLocally(new FirstEventTimeoutError(LAZY_STREAM_FIRST_EVENT_TIMEOUT_ERROR)),
 				abortSignal: options.signal,
 				// The synthetic `start` event is yielded immediately by every provider before
 				// the upstream model has emitted any tokens. Treating it as the first "real"
@@ -261,6 +269,7 @@ function createLazyLoadErrorMessage<TApi extends Api>(
 	error: unknown,
 	stopReason: Extract<AssistantMessage["stopReason"], "aborted" | "error"> = "error",
 ): AssistantMessage {
+	const transportFailure = transportFailureFacts(error);
 	return {
 		role: "assistant",
 		content: [],
@@ -278,6 +287,7 @@ function createLazyLoadErrorMessage<TApi extends Api>(
 		stopReason,
 		errorMessage:
 			stopReason === "aborted" ? "Request was aborted" : error instanceof Error ? error.message : String(error),
+		...(transportFailure ? { transportFailure } : {}),
 		timestamp: Date.now(),
 	};
 }

package/src/utils/fallback-transport.ts

@@ -5,6 +5,9 @@ export interface FallbackTrigger {
 	retryAfterMs?: number;
 }
 
+/** Stable code for streams that time out before producing semantic progress. */
+export const STREAM_FIRST_EVENT_TIMEOUT_PROVIDER_CODE = "stream_first_event_timeout";
+
 export type TransportHeaders = Headers | Record<string, string | undefined>;
 
 /**
@@ -185,7 +188,8 @@ export function transportFailureFacts(
 		!isQuotaCode(normalizedCode) &&
 		!isAuthCode(normalizedCode) &&
 		!isRateLimitCode(normalizedCode) &&
-		!isContextOverflowCode(normalizedCode)
+		!isContextOverflowCode(normalizedCode) &&
+		normalizedCode !== STREAM_FIRST_EVENT_TIMEOUT_PROVIDER_CODE
 	) {
 		return undefined;
 	}
@@ -256,14 +260,17 @@ export function classifyFallbackTrigger(
 		parseRetryAfterMilliseconds(headers?.get("retry-after-ms") ?? null) ??
 		parseRetryAfterSeconds(headers?.get("retry-after") ?? null);
 	const code = (facts.openaiErrorCode ?? facts.anthropicErrorType ?? facts.providerCode)?.toLowerCase();
-	const triggerClass: FallbackTriggerClass = isQuotaCode(code)
-		? "quota"
-		: facts.status === 401 || facts.status === 403 || isAuthCode(code)
-			? "auth"
-			: facts.status === 429 || isRateLimitCode(code)
-				? "rate_limit"
-				: facts.status !== undefined && facts.status >= 500 && facts.status <= 599
-					? "server"
-					: "other";
+	const triggerClass: FallbackTriggerClass =
+		code === STREAM_FIRST_EVENT_TIMEOUT_PROVIDER_CODE
+			? "server"
+			: isQuotaCode(code)
+				? "quota"
+				: facts.status === 401 || facts.status === 403 || isAuthCode(code)
+					? "auth"
+					: facts.status === 429 || isRateLimitCode(code)
+						? "rate_limit"
+						: facts.status !== undefined && facts.status >= 500 && facts.status <= 599
+							? "server"
+							: "other";
 	return retryAfterMs === undefined ? { class: triggerClass } : { class: triggerClass, retryAfterMs };
 }

package/src/utils/http-inspector.ts

@@ -1,3 +1,4 @@
+import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { APP_NAME, extractHttpStatusFromError, getLogsDir } from "@gajae-code/utils";
 import { isCopilotTransientModelError } from "./retry.js";
@@ -94,6 +95,49 @@ export function formatModelUnavailableGuidance(dump: RawHttpRequestDump | undefi
 	].join("\n");
 }
 
+/**
+ * Cap on retained HTTP 400 request dumps.
+ *
+ * Each dump carries the full sanitized request body, so they are large: a
+ * developer machine accumulated 27,249 files totalling 7.0 GB, averaging 264 KB
+ * each, because nothing ever removed them. The rotating application log already
+ * bounds itself (`maxSize: 10m`, `maxFiles: 5`); these diagnostics get the same
+ * treatment so the newest failures stay available without unbounded growth.
+ */
+const MAX_RETAINED_DUMPS = 50;
+
+/** Directory holding the retained HTTP 400 dumps. */
+export function httpRequestDumpDir(): string {
+	return path.join(getLogsDir(), "http-400-requests");
+}
+
+/**
+ * Drop the oldest dumps beyond the cap. Best-effort: diagnostics must never turn
+ * a request failure into a second failure, so every step swallows its error.
+ *
+ * File names are `${Date.now()}-${hash}.json`, so a lexical sort is chronological
+ * for the millisecond timestamps this writer produces.
+ */
+export async function pruneHttpRequestDumps(dir: string = httpRequestDumpDir()): Promise<number> {
+	const entries = await fs.readdir(dir).catch(() => undefined);
+	if (!entries) return 0;
+
+	const dumps = entries.filter(name => name.endsWith(".json")).sort();
+	if (dumps.length <= MAX_RETAINED_DUMPS) return 0;
+
+	let removed = 0;
+	for (const name of dumps.slice(0, dumps.length - MAX_RETAINED_DUMPS)) {
+		if (
+			await fs.rm(path.join(dir, name), { force: true }).then(
+				() => true,
+				() => false,
+			)
+		)
+			removed++;
+	}
+	return removed;
+}
+
 export async function appendRawHttpRequestDumpFor400(
 	message: string,
 	error: unknown,
@@ -105,10 +149,12 @@ export async function appendRawHttpRequestDumpFor400(
 
 	const sanitizedDump = sanitizeDump(dump);
 	const fileName = `${Date.now()}-${Bun.hash(JSON.stringify(sanitizedDump)).toString(36)}.json`;
-	const filePath = path.join(getLogsDir(), "http-400-requests", fileName);
+	const dumpDir = httpRequestDumpDir();
+	const filePath = path.join(dumpDir, fileName);
 
 	try {
 		await Bun.write(filePath, `${JSON.stringify(sanitizedDump, null, 2)}\n`);
+		await pruneHttpRequestDumps(dumpDir);
 		return `${message}\nraw-http-request=${filePath}\n${RAW_HTTP_REQUEST_PRIVACY_NOTE}`;
 	} catch (writeError) {
 		const writeMessage = writeError instanceof Error ? writeError.message : String(writeError);

package/src/utils/idle-iterator.ts

@@ -1,4 +1,5 @@
 import { $env } from "@gajae-code/utils";
+import { STREAM_FIRST_EVENT_TIMEOUT_PROVIDER_CODE } from "./fallback-transport";
 
 const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 120_000;
 const DEFAULT_STREAM_FIRST_EVENT_TIMEOUT_MS = 100_000;
@@ -66,6 +67,14 @@ export function getStreamFirstEventTimeoutMs(
 }
 
 export type Watchdog = NodeJS.Timeout | undefined;
+export class FirstEventTimeoutError extends Error {
+	readonly providerCode = STREAM_FIRST_EVENT_TIMEOUT_PROVIDER_CODE;
+
+	constructor(message: string) {
+		super(message);
+		this.name = "FirstEventTimeoutError";
+	}
+}
 
 const dummyWatchdog = setTimeout(() => {}, 1);
 clearTimeout(dummyWatchdog);
@@ -228,9 +237,9 @@ export async function* iterateWithIdleTimeout<T>(
 					options.onFirstItemTimeout?.();
 				}
 				closeIterator();
-				throw new Error(
-					!awaitingFirstItem ? options.errorMessage : (options.firstItemErrorMessage ?? options.errorMessage),
-				);
+				throw awaitingFirstItem
+					? new FirstEventTimeoutError(options.firstItemErrorMessage ?? options.errorMessage)
+					: new Error(options.errorMessage);
 			}
 			if (outcome.kind === "error") {
 				throw outcome.error;

package/src/utils/oauth/kimi.ts

@@ -7,7 +7,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { scheduler } from "node:timers/promises";
-import { $env, getAgentDir, isEnoent } from "@gajae-code/utils";
+import { $pickCredentialEnv, getAgentDir, isEnoent } from "@gajae-code/utils";
 import packageJson from "../../../package.json" with { type: "json" };
 import type { OAuthController, OAuthCredentials } from "./types";
 
@@ -38,8 +38,23 @@ interface TokenResponse {
 	interval?: number;
 }
 
+/**
+ * OAuth host for the device flow, from trusted environment sources only.
+ *
+ * This host receives the device-authorization request, the authorization-code
+ * exchange, and the refresh call that carries the existing refresh token, so
+ * whatever can set it can collect the user's Kimi credentials. `$env` merges the
+ * caller's `cwd/.env`, so reading it there would let repository content redirect
+ * the login flow. Resolve it the same way the credentials themselves are:
+ * launching shell plus GJC/user-owned `.env` files, never the project `.env`.
+ */
 function resolveOAuthHost(): string {
-	return $env.KIMI_CODE_OAUTH_HOST || $env.KIMI_OAUTH_HOST || DEFAULT_OAUTH_HOST;
+	return $pickCredentialEnv("KIMI_CODE_OAUTH_HOST", "KIMI_OAUTH_HOST") || DEFAULT_OAUTH_HOST;
+}
+
+/** Test seam: the OAuth host as resolved from trusted env. */
+export function resolveKimiOAuthHostForTest(): string {
+	return resolveOAuthHost();
 }
 
 function formatDeviceModel(system: string, release: string, arch: string): string {

package/src/utils/oauth/perplexity.ts

@@ -186,13 +186,32 @@ async function httpEmailLogin(ctrl: OAuthController): Promise<OAuthCredentials>
  *
  * No browser/manual token paste fallback is used.
  */
+/**
+ * Whether the operator disabled borrowing a token from the native macOS app.
+ *
+ * `GJC_AUTH_NO_BORROW` is the documented name; `PI_AUTH_NO_BORROW` is the legacy
+ * one that was the only name actually read.
+ */
+function authBorrowDisabled(): boolean {
+	return Boolean($env.GJC_AUTH_NO_BORROW || $env.PI_AUTH_NO_BORROW);
+}
+
+/** Test seam: the resolved native-app borrowing opt-out. */
+export function authBorrowDisabledForTest(): boolean {
+	return authBorrowDisabled();
+}
+
 export async function loginPerplexity(ctrl: OAuthController): Promise<OAuthCredentials> {
 	if (!ctrl.onPrompt) {
 		throw new Error("Perplexity login requires onPrompt callback");
 	}
 
-	// Path 1: Native macOS app JWT (skip if PI_AUTH_NO_BORROW=1)
-	if (!$env.PI_AUTH_NO_BORROW) {
+	// Path 1: Native macOS app JWT, skipped when the operator opts out.
+	//
+	// Presence-based on purpose: this is a privacy opt-out, so any set value must
+	// disable borrowing. A boolean contract would let `GJC_AUTH_NO_BORROW=0`
+	// silently re-enable reading a token out of another application.
+	if (!authBorrowDisabled()) {
 		ctrl.onProgress?.("Checking for Perplexity desktop app...");
 		const nativeJwt = await extractFromNativeApp();
 		if (nativeJwt) {

package/src/utils/schema/adapt.ts

@@ -1,4 +1,4 @@
-import { $flag } from "@gajae-code/utils";
+import { $pickflag } from "@gajae-code/utils";
 import { upgradeJsonSchemaTo202012 } from "./draft";
 import { tryEnforceStrictSchema } from "./normalize";
 
@@ -11,7 +11,7 @@ import { tryEnforceStrictSchema } from "./normalize";
  * see `openai-completions`, `openai-responses`, `OpenAI code provider-responses`, and
  * the strict candidate selection in `anthropic`.
  */
-export const NO_STRICT = $flag("PI_NO_STRICT");
+export const NO_STRICT = $pickflag("GJC_NO_STRICT", "PI_NO_STRICT");
 
 /**
  * Consolidated helper for OpenAI-style strict schema enforcement.

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

@@ -175,7 +175,8 @@ export function isForcedToolChoiceUnsupportedError(error: unknown, sentForcedToo
 			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)
+		/does\s+not\s+support\s+forced\s+tool[_\s-]?choices?/is.test(message) ||
+		/tool[_\s-]?choices?\s+['"`][^'"`\r\n]+['"`]\s+not\s+found\s+in\s+['"`]tools['"`]\s+parameter\b/is.test(message)
 	);
 }