@gajae-code/ai 0.12.0 → 0.12.1

package/src/providers/google-vertex.ts

@@ -1,4 +1,4 @@
-import { $credentialEnv, $env } from "@gajae-code/utils";
+import { $credentialEnv, $pickCredentialEnv } from "@gajae-code/utils";
 import type { Context, Model, StreamFunction } from "../types";
 import type { AssistantMessageEventStream } from "../utils/event-stream";
 import { getVertexAccessToken } from "./google-auth";
@@ -72,7 +72,7 @@ function resolveApiKey(options?: GoogleVertexOptions): string | undefined {
 }
 
 function resolveProject(options?: GoogleVertexOptions): string {
-	const project = options?.project || $env.GOOGLE_CLOUD_PROJECT || $env.GCLOUD_PROJECT;
+	const project = options?.project || $pickCredentialEnv("GOOGLE_CLOUD_PROJECT", "GCLOUD_PROJECT");
 	if (!project) {
 		throw new Error(
 			"Vertex AI requires a project ID. Set GOOGLE_CLOUD_PROJECT/GCLOUD_PROJECT or pass project in options.",
@@ -84,10 +84,41 @@ function resolveProject(options?: GoogleVertexOptions): string {
 function resolveEndpointHost(location: string): string {
 	return location === "global" ? "aiplatform.googleapis.com" : `${location}-aiplatform.googleapis.com`;
 }
+/**
+ * Vertex location, from trusted environment sources only and constrained to a
+ * region label.
+ *
+ * The location is interpolated into the request **host**
+ * (`${location}-aiplatform.googleapis.com`) as well as the path, and the request
+ * carries `Authorization: Bearer <accessToken>`. A value containing `/`
+ * terminates the authority component, so `evil.example.com/` resolves to origin
+ * `https://evil.example.com` and the Google access token leaves Google entirely.
+ * `$env` merges the caller's `cwd/.env`, so this was reachable from repository
+ * content.
+ *
+ * Both halves are needed: trusted resolution keeps a repository from setting it,
+ * and the shape check keeps any source from turning a region into an authority.
+ */
+const VERTEX_LOCATION_RE = /^[a-z0-9-]+$/;
+
+function assertVertexLocation(location: string): string {
+	if (!VERTEX_LOCATION_RE.test(location)) {
+		throw new Error(
+			`Invalid Vertex AI location ${JSON.stringify(location)}. Expected a region label such as "us-central1" or "global".`,
+		);
+	}
+	return location;
+}
+
 function resolveLocation(options?: GoogleVertexOptions): string {
-	const location = options?.location || $env.GOOGLE_CLOUD_LOCATION;
+	const location = options?.location || $credentialEnv("GOOGLE_CLOUD_LOCATION");
 	if (!location) {
 		throw new Error("Vertex AI requires a location. Set GOOGLE_CLOUD_LOCATION or pass location in options.");
 	}
-	return location;
+	return assertVertexLocation(location);
+}
+
+/** Test seam: the Vertex location as resolved from options plus trusted env. */
+export function resolveVertexLocationForTest(options?: GoogleVertexOptions): string {
+	return resolveLocation(options);
 }

package/src/providers/ollama.ts

@@ -18,7 +18,7 @@ import { normalizeSystemPrompts } from "../utils";
 import { AssistantMessageEventStream } from "../utils/event-stream";
 import { transportFailureFacts } from "../utils/fallback-transport";
 import { finalizeErrorMessage, type RawHttpRequestDump } from "../utils/http-inspector";
-import { parseStreamingJson } from "../utils/json-parse";
+import { isCompleteJson, parseStreamingJson } from "../utils/json-parse";
 import { resolveRetryBudget } from "../utils/retry-budget";
 import { flattenToolRootCombinators, toolWireSchema } from "../utils/schema";
 import {
@@ -26,6 +26,7 @@ import {
 	markToolChoiceIncapability,
 	resolveToolChoice,
 } from "../utils/tool-choice-capability";
+import { flagTruncatedToolCalls } from "./openai-responses-shared";
 import { transformMessages } from "./transform-messages";
 
 export interface OllamaChatOptions extends StreamOptions {
@@ -357,8 +358,10 @@ function endToolCallBlock(stream: AssistantMessageEventStream, output: Assistant
 		return;
 	}
 	const toolCall = block as InternalToolCallBlock;
-	if (toolCall.partialJson) {
-		toolCall.arguments = parseStreamingJson<Record<string, unknown>>(toolCall.partialJson);
+	if (toolCall.partialJson !== undefined) {
+		if (toolCall.partialJson.trim()) {
+			toolCall.arguments = parseStreamingJson<Record<string, unknown>>(toolCall.partialJson);
+		}
 		delete toolCall.partialJson;
 	}
 	stream.push({ type: "toolcall_end", contentIndex: index, toolCall, partial: output });
@@ -393,6 +396,8 @@ export const streamOllama: StreamFunction<"ollama-chat"> = (
 		let activeThinkingIndex: number | undefined;
 		let activeTextIndex: number | undefined;
 		const activeToolIndices = new Set<number>();
+		const unverifiableArgumentToolCallIds = new Set<string>();
+		let sawTerminalChunk = false;
 		try {
 			const apiKey = options.apiKey || getEnvApiKey(model.provider);
 			if (!apiKey) {
@@ -537,6 +542,7 @@ export const streamOllama: StreamFunction<"ollama-chat"> = (
 					for (const call of chunk.message.tool_calls) {
 						const name = call.function?.name ?? "unknown_tool";
 						const rawArgs = call.function?.arguments;
+						const unverifiableArguments = typeof rawArgs !== "string";
 						const partialJson = typeof rawArgs === "string" ? rawArgs : JSON.stringify(rawArgs ?? {});
 						const toolCall: InternalToolCallBlock = {
 							type: "toolCall",
@@ -545,6 +551,7 @@ export const streamOllama: StreamFunction<"ollama-chat"> = (
 							arguments: parseStreamingJson<Record<string, unknown>>(partialJson),
 							partialJson,
 						};
+						if (unverifiableArguments) unverifiableArgumentToolCallIds.add(toolCall.id);
 						output.content.push(toolCall);
 						const index = output.content.length - 1;
 						activeToolIndices.add(index);
@@ -561,6 +568,7 @@ export const streamOllama: StreamFunction<"ollama-chat"> = (
 					}
 				}
 				if (chunk.done) {
+					sawTerminalChunk = true;
 					if (activeThinkingIndex !== undefined) {
 						endThinkingBlock(stream, output, activeThinkingIndex);
 						activeThinkingIndex = undefined;
@@ -569,16 +577,36 @@ export const streamOllama: StreamFunction<"ollama-chat"> = (
 						endTextBlock(stream, output, activeTextIndex);
 						activeTextIndex = undefined;
 					}
+					output.stopReason = mapDoneReason(chunk.done_reason, output);
+					// Ollama still owns every partialJson buffer here; use the helper's
+					// finalized-call branch before endToolCallBlock deletes those buffers.
+					// Non-string arguments have no raw completion evidence, so a length stop
+					// must fail closed rather than trusting normalized or re-serialized values.
+					flagTruncatedToolCalls(
+						output,
+						output.stopReason,
+						block => !unverifiableArgumentToolCallIds.has(block.id),
+					);
+					if (chunk.done_reason === undefined) {
+						for (const block of output.content) {
+							if (block.type !== "toolCall") continue;
+							const partialJson = (block as InternalToolCallBlock).partialJson;
+							if (partialJson !== undefined && !isCompleteJson(partialJson)) block.incompleteArguments = true;
+						}
+					}
 					for (const index of activeToolIndices) {
 						endToolCallBlock(stream, output, index);
 					}
 					activeToolIndices.clear();
-					output.stopReason = mapDoneReason(chunk.done_reason, output);
 					output.usage.input = chunk.prompt_eval_count ?? 0;
 					output.usage.output = chunk.eval_count ?? 0;
 					output.usage.totalTokens = output.usage.input + output.usage.output;
+					break;
 				}
 			}
+			if (!sawTerminalChunk) {
+				throw new Error("Ollama stream ended before terminal done chunk");
+			}
 			output.duration = Date.now() - startTime;
 			if (firstTokenTime) {
 				output.ttft = firstTokenTime - startTime;

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