@gajae-code/ai 0.18.6 → 0.18.7

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 ## [Unreleased]
 
+## [0.18.7] - 2026-10-04
+
+### Fixed
+
+- Explicitly emit `strict: false` for non-strict OpenAI Responses and Codex Responses function tools.
+
+- Salvage finalized Codex tool calls when an empty assistant message item opens before a transient stream close, while still failing closed on non-empty text.
+
+- Preserve finalized Codex tool calls when the stream ends without a terminal event, including an empty trailing message; unfinished calls and visible text still fail closed.
+
+- Add Codex request-timeout salvage refusal diagnostics and replay coverage for complete `todo_write` calls.
+
+- Salvage complete Codex function calls when the SSE or WebSocket idle watchdog ends a stalled stream.
+
+- **Kiro OAuth CodeWhisperer wire protocol**: Corrected critical wire protocol issues in the streaming transport:
+  - Fixed typo in request header `amzn-X-amz-target` → `x-amz-target`
+  - Changed streaming service target from `AmazonCodeWhispererService.GenerateAssistantResponse` to `AmazonCodeWhispererStreamingService.GenerateAssistantResponse`
+  - Fixed content-type from `application/json` to `application/x-amz-json-1.0`
+  - Moved `profileArn` from header to request body `conversationState`
+  - Flattened `userInputMessageContext.tools` from nested `{tools: [...]}` to direct array
+  - Fixed event payload handling for flat `{content}` structure (not nested `{assistantResponseEvent: {content}}`)
+  - Implemented accumulation of streaming tool input fragments per `toolUseId` until `stop` signal
+  - Cross-verified against kiro-api-key.ts headers implementation
+  - Reported by: nomo via wire protocol validation failures
+
 ## [0.18.6] - 2026-10-03
 
 ### Added

package/dist/types/providers/openai-codex-responses.d.ts

@@ -77,3 +77,4 @@ type CodexToolPayload = {
 /** @internal Exported for tests. */
 export declare function convertOpenAICodexResponsesTools(tools: Tool[], model: Model<"openai-codex-responses">): CodexToolPayload[];
 declare function isRetryableCodexFailureEvent(rawEvent: Record<string, unknown>): boolean;
+export declare function isExplicitCodexTerminalVeto(code?: string, providerMessage?: string): boolean;

package/dist/types/types.d.ts

@@ -640,6 +640,8 @@ export interface AssistantMessage {
      * supplied no trustworthy structured evidence.
      */
     providerDiagnostic?: ProviderDiagnostic;
+    /** Redacted first-event transport timing and chunk-shape diagnostics for Google Gemini CLI. */
+    googleGeminiCliDiagnostics?: GoogleGeminiCliDiagnostics;
     /** Typed upstream failure facts retained for retry classification without parsing errorMessage. */
     transportFailure?: TransportFailureFacts;
     /**
@@ -658,6 +660,19 @@ export interface AssistantMessage {
     /** Prompt-prefix fingerprint of the request that produced this message. */
     promptPrefix?: PromptPrefixTelemetry;
 }
+export interface GoogleGeminiCliDiagnostics {
+    responseAtMs?: number;
+    firstRawSseAtMs?: number;
+    chunkCounts: {
+        content: number;
+        thinking: number;
+        functionCall: number;
+        usageOnly: number;
+        other: number;
+    };
+    firstEventTimeoutMs?: number;
+    firstEventTimeoutSource?: "stream-option" | "env" | "idle-timeout" | "provider-fallback" | "default";
+}
 export interface ToolResultMessage<TDetails = any> {
     role: "toolResult";
     toolCallId: string;

package/dist/types/utils/idle-iterator.d.ts

@@ -72,6 +72,7 @@ export interface FirstEventTimeoutFacts {
     requestBytes?: number;
     firstEventElapsedMs?: number;
     firstEventTimeoutMs?: number;
+    firstEventTimeoutSource?: "stream-option" | "env" | "idle-timeout" | "provider-fallback" | "default";
     endpointClass?: "canonical" | "custom";
     retryMaxAttempts?: number;
 }
@@ -80,6 +81,7 @@ export declare class FirstEventTimeoutError extends Error {
     readonly requestBytes?: number;
     readonly firstEventElapsedMs?: number;
     readonly firstEventTimeoutMs?: number;
+    readonly firstEventTimeoutSource?: FirstEventTimeoutFacts["firstEventTimeoutSource"];
     readonly endpointClass?: "canonical" | "custom";
     readonly retryMaxAttempts?: number;
     constructor(message: string, facts?: FirstEventTimeoutFacts);

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/ai",
-	"version": "0.18.6",
+	"version": "0.18.7",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"homepage": "https://gajae-code.com",
 	"author": "Yeachan-Heo and Gajae Code Contributors",
@@ -41,8 +41,8 @@
 		"@agentclientprotocol/sdk": "1.3.0",
 		"@anthropic-ai/sdk": "^0.94.0",
 		"@bufbuild/protobuf": "^2.12.0",
-		"@gajae-code/natives": "0.18.6",
-		"@gajae-code/utils": "0.18.6",
+		"@gajae-code/natives": "0.18.7",
+		"@gajae-code/utils": "0.18.7",
 		"openai": "^6.36.0",
 		"partial-json": "^0.1.7",
 		"zod": "4.4.3"

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

@@ -16,6 +16,7 @@ import type {
 	Api,
 	AssistantMessage,
 	Context,
+	GoogleGeminiCliDiagnostics,
 	Model,
 	StreamFunction,
 	StreamOptions,
@@ -27,6 +28,7 @@ import { normalizeSystemPrompts } from "../utils";
 import { AssistantMessageEventStream } from "../utils/event-stream";
 import { transportFailureFacts } from "../utils/fallback-transport";
 import { appendRawHttpRequestDumpFor400, type RawHttpRequestDump, withHttpStatus } from "../utils/http-inspector";
+import { FirstEventTimeoutError } from "../utils/idle-iterator";
 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`.
@@ -325,6 +327,29 @@ export const streamGoogleGeminiCli: StreamFunction<"google-gemini-cli"> = (
 			timestamp: Date.now(),
 		};
 		let rawRequestDump: RawHttpRequestDump | undefined;
+		const googleGeminiCliDiagnostics: GoogleGeminiCliDiagnostics = {
+			chunkCounts: { content: 0, thinking: 0, functionCall: 0, usageOnly: 0, other: 0 },
+		};
+		(
+			stream as AssistantMessageEventStream & { googleGeminiCliDiagnostics?: GoogleGeminiCliDiagnostics }
+		).googleGeminiCliDiagnostics = googleGeminiCliDiagnostics;
+		const recordTimeoutDiagnostics = (): void => {
+			const reason = options?.signal?.reason;
+			if (!(reason instanceof FirstEventTimeoutError)) return;
+			googleGeminiCliDiagnostics.firstEventTimeoutMs = reason.firstEventTimeoutMs;
+			googleGeminiCliDiagnostics.firstEventTimeoutSource = reason.firstEventTimeoutSource;
+			(
+				reason as FirstEventTimeoutError & {
+					googleGeminiCliDiagnostics?: GoogleGeminiCliDiagnostics;
+				}
+			).googleGeminiCliDiagnostics = googleGeminiCliDiagnostics;
+		};
+		options?.signal?.addEventListener("abort", recordTimeoutDiagnostics, { once: true });
+		const recordResponse = (): void => {
+			if (googleGeminiCliDiagnostics.responseAtMs === undefined) {
+				googleGeminiCliDiagnostics.responseAtMs = Date.now() - startTime;
+			}
+		};
 
 		try {
 			const apiKeyRaw = options?.apiKey;
@@ -405,6 +430,7 @@ export const streamGoogleGeminiCli: StreamFunction<"google-gemini-cli"> = (
 					fetch: options?.fetch,
 				},
 			);
+			recordResponse();
 			if (!response.ok && sentForcedToolChoice) {
 				const errorText = await response.text();
 				const error = createGeminiCliHttpError(response, errorText);
@@ -447,6 +473,7 @@ export const streamGoogleGeminiCli: StreamFunction<"google-gemini-cli"> = (
 							fetch: options?.fetch,
 						},
 					);
+					recordResponse();
 				} else {
 					throw error;
 				}
@@ -496,20 +523,29 @@ export const streamGoogleGeminiCli: StreamFunction<"google-gemini-cli"> = (
 				for await (const chunk of readSseJson<CloudCodeAssistResponseChunk>(
 					activeResponse.body!,
 					options?.signal,
-					event =>
+					event => {
+						if (googleGeminiCliDiagnostics.firstRawSseAtMs === undefined) {
+							googleGeminiCliDiagnostics.firstRawSseAtMs = Date.now() - startTime;
+						}
 						options?.onSseEvent?.(
 							{ event: event.event, data: event.data, raw: [...event.raw] },
 							model,
 							options?.attemptScope,
-						),
+						);
+					},
 				)) {
 					const responseData = chunk.response;
-					if (!responseData) continue;
+					if (!responseData) {
+						googleGeminiCliDiagnostics.chunkCounts.other += 1;
+						continue;
+					}
 
 					const candidate = responseData.candidates?.[0];
+					let chunkKind: keyof GoogleGeminiCliDiagnostics["chunkCounts"] = "other";
 					if (candidate?.content?.parts) {
 						for (const part of candidate.content.parts) {
 							if (part.text !== undefined) {
+								chunkKind = isThinkingPart(part) ? "thinking" : "content";
 								hasContent = true;
 								const isThinking = isThinkingPart(part);
 								if (
@@ -550,6 +586,7 @@ export const streamGoogleGeminiCli: StreamFunction<"google-gemini-cli"> = (
 							}
 
 							if (part.functionCall) {
+								chunkKind = "functionCall";
 								hasContent = true;
 								if (currentBlock) {
 									pushBlockEndEvent(currentBlock, blockIndex(), output, stream);
@@ -618,6 +655,7 @@ export const streamGoogleGeminiCli: StreamFunction<"google-gemini-cli"> = (
 					}
 
 					if (responseData.usageMetadata) {
+						if (chunkKind === "other") chunkKind = "usageOnly";
 						// promptTokenCount includes cachedContentTokenCount, so subtract to get fresh input
 						const promptTokens = responseData.usageMetadata.promptTokenCount || 0;
 						const cacheReadTokens = responseData.usageMetadata.cachedContentTokenCount || 0;
@@ -639,6 +677,7 @@ export const streamGoogleGeminiCli: StreamFunction<"google-gemini-cli"> = (
 						};
 						calculateCost(model, output.usage);
 					}
+					googleGeminiCliDiagnostics.chunkCounts[chunkKind] += 1;
 				}
 
 				if (currentBlock) {
@@ -676,6 +715,7 @@ export const streamGoogleGeminiCli: StreamFunction<"google-gemini-cli"> = (
 						body: requestBodyJson,
 						signal: options?.signal,
 					});
+					recordResponse();
 
 					if (!currentResponse.ok) {
 						const retryErrorText = await currentResponse.text();
@@ -711,6 +751,11 @@ export const streamGoogleGeminiCli: StreamFunction<"google-gemini-cli"> = (
 			stream.push({ type: "done", reason: output.stopReason, message: output });
 			stream.end();
 		} catch (error) {
+			const timeoutError = options?.signal?.reason;
+			if (timeoutError instanceof FirstEventTimeoutError) {
+				googleGeminiCliDiagnostics.firstEventTimeoutMs = timeoutError.firstEventTimeoutMs;
+				googleGeminiCliDiagnostics.firstEventTimeoutSource = timeoutError.firstEventTimeoutSource;
+			}
 			for (const block of output.content) {
 				if ("index" in block) {
 					delete (block as { index?: number }).index;
@@ -719,6 +764,7 @@ export const streamGoogleGeminiCli: StreamFunction<"google-gemini-cli"> = (
 			output.stopReason = options?.signal?.aborted ? "aborted" : "error";
 			output.errorStatus = extractHttpStatusFromError(error);
 			output.transportFailure = transportFailureFacts(error);
+			output.googleGeminiCliDiagnostics = googleGeminiCliDiagnostics;
 			output.errorMessage = await appendRawHttpRequestDumpFor400(
 				error instanceof Error ? error.message : JSON.stringify(error),
 				error,

package/src/providers/kiro-codewhisperer.ts

@@ -74,7 +74,7 @@ interface WireUserMessage {
 		content: string;
 		modelId?: string;
 		userInputMessageContext?: {
-			tools?: { tools: WireToolSpec[] };
+			tools?: WireToolSpec[];
 			toolResults?: WireToolResult[];
 			editorStateContext?: Record<string, unknown>;
 		};
@@ -108,25 +108,19 @@ interface GenerateAssistantResponseRequest {
 // ─────────────────────────────────────────────────────────────────────────────
 
 interface AssistantResponseEvent {
-	assistantResponseEvent?: {
-		content?: string;
-	};
+	content?: string;
 }
 
 interface ToolUseEventPayload {
-	toolUseEvent?: {
-		toolUseId?: string;
-		name?: string;
-		input?: unknown;
-		stop?: { stopReason?: string };
-	};
+	toolUseId?: string;
+	name?: string;
+	input?: string;
+	stop?: boolean;
 }
 
 interface MessageMetadataEvent {
-	messageMetadataEvent?: {
-		conversationId?: string;
-		utteranceId?: string;
-	};
+	conversationId?: string;
+	utteranceId?: string;
 }
 
 interface ErrorPayload {
@@ -169,6 +163,8 @@ export const streamKiroCodeWhisperer: StreamFunction<"kiro-codewhisperer-stream"
 	(async () => {
 		const startTime = Date.now();
 		let firstTokenTime: number | undefined;
+		// Accumulator for streaming tool input fragments, keyed by toolUseId
+		const toolInputAccumulator = new Map<string, { name: string; input: string }>();
 
 		const output: AssistantMessage = {
 			role: "assistant",
@@ -190,6 +186,7 @@ export const streamKiroCodeWhisperer: StreamFunction<"kiro-codewhisperer-stream"
 
 		const blocks = output.content as Block[];
 		const region = options.region ?? $env.KIRO_REGION ?? $env.AWS_REGION ?? $env.AWS_DEFAULT_REGION ?? DEFAULT_REGION;
+		let started = false; // Track whether start event has been emitted
 
 		try {
 			assertAwsRegionLabel(region);
@@ -222,24 +219,24 @@ export const streamKiroCodeWhisperer: StreamFunction<"kiro-codewhisperer-stream"
 			const bodyText = JSON.stringify(requestBody);
 			const body = new TextEncoder().encode(bodyText);
 			const requestHeaders: Record<string, string> = {
-				"content-type": "application/json",
-				accept: "application/vnd.amazon.eventstream",
-				authorization: `Bearer ${bearerToken}`,
-				"amzn-X-amz-target": "AmazonCodeWhispererService.GenerateAssistantResponse",
+				"Content-Type": "application/x-amz-json-1.0",
+				Accept: "application/vnd.amazon.eventstream",
+				Authorization: `Bearer ${bearerToken}`,
+				"X-Amz-Target": "AmazonCodeWhispererStreamingService.GenerateAssistantResponse",
 			};
 
-			if (options.profileArn) {
-				requestHeaders["x-amzn-codewhisperer-proflearn"] = options.profileArn;
-			}
-
-			// Merge user-provided headers
+			// Merge user-provided headers (case-insensitively)
+			const headersList = new Headers(requestHeaders);
 			if (options.headers) {
-				Object.assign(requestHeaders, options.headers);
+				const userHeaders = new Headers(options.headers);
+				userHeaders.forEach((value, key) => {
+					headersList.set(key, value);
+				});
 			}
 
 			const response = await fetch(url, {
 				method: "POST",
-				headers: requestHeaders,
+				headers: headersList,
 				body,
 				redirect: "error",
 				signal: options.signal,
@@ -300,11 +297,12 @@ export const streamKiroCodeWhisperer: StreamFunction<"kiro-codewhisperer-stream"
 				switch (eventType) {
 					case "assistantResponseEvent": {
 						const ev = payload as AssistantResponseEvent;
-						const content = ev.assistantResponseEvent?.content;
+						const content = ev.content;
 						if (content) {
 							if (!firstTokenTime) firstTokenTime = Date.now();
-							if (blocks.length === 0) {
+							if (!started) {
 								stream.push({ type: "start", partial: output });
+								started = true;
 							}
 							handleTextDelta(content, blocks, output, stream);
 						}
@@ -313,16 +311,21 @@ export const streamKiroCodeWhisperer: StreamFunction<"kiro-codewhisperer-stream"
 					case "toolUseEvent": {
 						const ev = payload as ToolUseEventPayload;
 						if (!firstTokenTime) firstTokenTime = Date.now();
-						if (blocks.length === 0) {
+						if (!started) {
 							stream.push({ type: "start", partial: output });
+							started = true;
+						}
+						handleToolUseEvent(ev, blocks, output, stream, toolInputAccumulator);
+						// Clear accumulator for completed tool
+						if (ev.stop) {
+							toolInputAccumulator.delete(ev.toolUseId ?? "");
 						}
-						handleToolUseEvent(ev, blocks, output, stream);
 						break;
 					}
 					case "messageMetadataEvent": {
 						const ev = payload as MessageMetadataEvent;
-						if (ev.messageMetadataEvent?.conversationId) {
-							output.responseId = ev.messageMetadataEvent.conversationId;
+						if (ev.conversationId) {
+							output.responseId = ev.conversationId;
 						}
 						break;
 					}
@@ -349,6 +352,12 @@ export const streamKiroCodeWhisperer: StreamFunction<"kiro-codewhisperer-stream"
 
 			if (options.signal?.aborted) throw new Error("Request was aborted");
 
+			// Reject EOF while tool input is still being accumulated
+			if (toolInputAccumulator.size > 0) {
+				const unfinishedIds = Array.from(toolInputAccumulator.keys()).join(", ");
+				throw new Error(`Kiro CodeWhisperer stream ended with incomplete tool calls: ${unfinishedIds}`);
+			}
+
 			// Finalize blocks
 			for (const block of blocks) {
 				delete block.index;
@@ -456,9 +465,7 @@ function buildConversationState(
 		if (!currentMessage.userInputMessage.userInputMessageContext) {
 			currentMessage.userInputMessage.userInputMessageContext = {};
 		}
-		currentMessage.userInputMessage.userInputMessageContext.tools = {
-			tools: convertTools(context.tools),
-		};
+		currentMessage.userInputMessage.userInputMessageContext.tools = convertTools(context.tools);
 	}
 
 	return {
@@ -601,44 +608,55 @@ function handleToolUseEvent(
 	blocks: Block[],
 	output: AssistantMessage,
 	stream: AssistantMessageEventStream,
+	accumulator: Map<string, { name: string; input: string }>,
 ): void {
-	const toolEvent = ev.toolUseEvent;
-	if (!toolEvent) return;
+	const name = ev.name ?? "";
+	const input = ev.input ?? "";
+
+	// Determine the tool ID: use provided ID, or find the currently active tool call
+	let toolUseId = ev.toolUseId;
+	if (!toolUseId) {
+		// ID-less fragment: associate with the currently active tool call
+		// Find the last tool call being accumulated (the most recently started tool)
+		const keys = Array.from(accumulator.keys());
+		if (keys.length > 0) {
+			toolUseId = keys[keys.length - 1];
+		} else {
+			// No active tool calls; create a placeholder entry (should rarely happen)
+			toolUseId = "";
+		}
+	}
+
+	// Accumulate input fragments per toolUseId
+	let accumulated = accumulator.get(toolUseId);
+	if (!accumulated) {
+		accumulated = { name, input: "" };
+		accumulator.set(toolUseId, accumulated);
+	}
+	accumulated.input += input;
 
-	const toolUseId = toolEvent.toolUseId ?? "";
-	const name = toolEvent.name ?? "";
+	// Update name if provided and not yet set
+	if (name && !accumulated.name) {
+		accumulated.name = name;
+	}
 
-	// If input is provided as a complete object, emit toolcall_end
-	if (toolEvent.input !== undefined && toolEvent.input !== null) {
-		const inputStr = typeof toolEvent.input === "string" ? toolEvent.input : JSON.stringify(toolEvent.input);
+	// Emit toolcall_end only when we have a stop signal
+	if (ev.stop) {
+		const inputStr = accumulated.input;
 		const toolCall: ToolCall = {
 			type: "toolCall",
 			id: toolUseId,
-			name,
+			name: accumulated.name,
 			arguments: safeParseJson(inputStr) as Record<string, any>,
 		};
-		if (typeof toolEvent.input === "string") captureUnicodeEscapeEvidence(toolCall, inputStr);
+		captureUnicodeEscapeEvidence(toolCall, inputStr);
 
 		const newBlock: Block = { ...toolCall, index: blocks.length };
-		if (typeof toolEvent.input === "string") captureUnicodeEscapeEvidence(newBlock, inputStr);
+		captureUnicodeEscapeEvidence(newBlock, inputStr);
 		blocks.push(newBlock);
 		stream.push({ type: "toolcall_end", contentIndex: newBlock.index!, toolCall, partial: output });
-		return;
+		accumulator.delete(toolUseId);
 	}
-
-	// Otherwise, accumulate partial input (if the service streams it in chunks)
-	// The published model does not document chunked tool input for CodeWhisperer,
-	// so this path handles the case defensively but expects complete input per event.
-	const toolCall: ToolCall = {
-		type: "toolCall",
-		id: toolUseId,
-		name,
-		arguments: {},
-	};
-
-	const newBlock: Block = { ...toolCall, index: blocks.length };
-	blocks.push(newBlock);
-	stream.push({ type: "toolcall_end", contentIndex: newBlock.index!, toolCall, partial: output });
 }
 
 // ─────────────────────────────────────────────────────────────────────────────

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

@@ -77,3 +77,4 @@ type CodexToolPayload = {
 /** @internal Exported for tests. */
 export declare function convertOpenAICodexResponsesTools(tools: Tool[], model: Model<"openai-codex-responses">): CodexToolPayload[];
 declare function isRetryableCodexFailureEvent(rawEvent: Record<string, unknown>): boolean;
+export declare function isExplicitCodexTerminalVeto(code?: string, providerMessage?: string): boolean;

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

@@ -190,6 +190,12 @@ const CODEX_NON_RETRYABLE_EVENT_CODES = new Set([
 ]);
 const CODEX_NON_RETRYABLE_EVENT_MESSAGE =
 	/invalid[_ -]function[_ -]parameters|invalid schema for function|invalid[_ -]tool[_ -]schema|schema must have type ["']?object["']?|request blocked[^\n]*invalid[_ -]prompt|code=invalid[_ -]prompt/i;
+const CODEX_EXPLICIT_TERMINAL_VETO_CODES = new Set([
+	"invalid_function_parameters",
+	"invalid_schema",
+	"invalid_tool_schema",
+	"invalid_prompt",
+]);
 const CODEX_RETRYABLE_EVENT_MESSAGE =
 	/processing your request|retry your request|temporar(?:y|ily)|overloaded|service.?unavailable|internal error|server error/i;
 const CODEX_ACCOUNT_MODEL_UNAVAILABLE_MESSAGE = /\bnot supported when using codex with a chatgpt account\b/i;
@@ -371,6 +377,10 @@ type CodexOutputBlock =
 			doneInput?: string;
 			argumentsComplete?: boolean;
 			argumentsAuthoritative?: boolean;
+			sourceItemId?: string;
+			sourceCallId?: string;
+			sourceName?: string;
+			sourceOutputIndex?: number;
 	  });
 export interface OpenAICodexWebSocketDebugStats {
 	fullContextRequests: number;
@@ -470,6 +480,7 @@ interface CodexStreamRuntime {
 	currentItemOutputIndex?: number;
 	currentBlock: CodexOutputBlock | null;
 	nativeOutputItems: Array<Record<string, unknown>>;
+	nativeOutputItemOutputIndexes: Array<number | undefined>;
 	websocketStreamRetries: number;
 	providerRetryAttempt: number;
 	toolChoiceFallbackAttempted: boolean;
@@ -818,6 +829,10 @@ function removeTransientBlockIndices(output: AssistantMessage): void {
 			delete (block as { doneInput?: string }).doneInput;
 			delete (block as { argumentsComplete?: boolean }).argumentsComplete;
 			delete (block as { argumentsAuthoritative?: boolean }).argumentsAuthoritative;
+			delete (block as { sourceItemId?: string }).sourceItemId;
+			delete (block as { sourceCallId?: string }).sourceCallId;
+			delete (block as { sourceName?: string }).sourceName;
+			delete (block as { sourceOutputIndex?: number }).sourceOutputIndex;
 		}
 	}
 }
@@ -1220,6 +1235,7 @@ function createCodexStreamRuntime(initial: {
 		currentItemOutputIndex: undefined,
 		currentBlock: null,
 		nativeOutputItems: [],
+		nativeOutputItemOutputIndexes: [],
 		websocketStreamRetries: 0,
 		providerRetryAttempt: 0,
 		toolChoiceFallbackAttempted: initial.toolChoiceFallbackApplied === true,
@@ -1255,6 +1271,13 @@ async function processCodexResponseStream(
 				});
 				if (runtime.sawTerminalEvent) break;
 			}
+			if (!runtime.sawTerminalEvent) {
+				trySalvageCodexFinalizedToolCalls(
+					context,
+					runtime,
+					new Error("Codex stream ended before terminal completion event"),
+				);
+			}
 			return { firstTokenTime };
 		} catch (error) {
 			if (trySalvageCodexFinalizedToolCalls(context, runtime, error)) {
@@ -1274,38 +1297,82 @@ function trySalvageCodexFinalizedToolCalls(
 	error: unknown,
 ): boolean {
 	const toolCalls = context.output.content.filter((block): block is ToolCall => block.type === "toolCall");
-	const activeToolCall =
-		runtime.currentItem?.type === "function_call" && runtime.currentBlock?.type === "toolCall"
-			? runtime.currentBlock
-			: undefined;
-	const completeActiveToolCall =
-		activeToolCall?.argumentsComplete === true &&
-		(activeToolCall.argumentsAuthoritative === true || Object.keys(activeToolCall.arguments).length > 0);
+	const completeToolCalls = toolCalls.filter(toolCall => {
+		const block = toolCall as ToolCall & {
+			argumentsComplete?: boolean;
+			argumentsAuthoritative?: boolean;
+			sourceItemId?: string;
+			sourceCallId?: string;
+		};
+		return (
+			!runtime.finalizedToolCallIds.has(toolCall.id) &&
+			block.argumentsComplete === true &&
+			typeof block.sourceItemId === "string" &&
+			typeof block.sourceCallId === "string" &&
+			(block.argumentsAuthoritative === true || Object.keys(block.arguments).length > 0)
+		);
+	});
 	const hasCompleteArguments = toolCalls.every(
-		toolCall =>
-			runtime.finalizedToolCallIds.has(toolCall.id) || (toolCall === activeToolCall && completeActiveToolCall),
+		toolCall => runtime.finalizedToolCallIds.has(toolCall.id) || completeToolCalls.includes(toolCall),
 	);
-	const isIdleStall =
-		error instanceof Error && error.message === "OpenAI Codex SSE stream stalled while waiting for the next event";
+	const isIdleStall = isCodexIdleStall(error);
+	const hasEmptyActiveMessage =
+		runtime.currentItem?.type === "message" &&
+		runtime.currentBlock?.type === "text" &&
+		runtime.currentItem.content.every(content =>
+			content.type === "output_text" ? content.text === "" : content.refusal === "",
+		);
+	// EOF proves a closed stream, but only finalized calls are safe without a timeout event.
+	const isUnexpectedStreamEnd =
+		error instanceof Error && error.message === "Codex stream ended before terminal completion event";
 	const canSalvageFinalizedCall =
-		isCodexTransientStreamClose(error) &&
+		(isCodexTransientStreamClose(error) || isUnexpectedStreamEnd) &&
 		!runtime.toolArgumentCorrelationFailed &&
 		toolCalls.length > 0 &&
 		(runtime.currentBlock === null ||
-			(runtime.currentItem?.type === "reasoning" && runtime.currentBlock?.type === "thinking")) &&
-		context.output.content.every(block => block.type === "thinking" || block.type === "toolCall") &&
+			runtime.currentBlock?.type === "toolCall" ||
+			(runtime.currentItem?.type === "reasoning" && runtime.currentBlock?.type === "thinking") ||
+			hasEmptyActiveMessage) &&
+		context.output.content.every(
+			block =>
+				block.type === "thinking" || block.type === "toolCall" || (block.type === "text" && block.text === ""),
+		) &&
 		toolCalls.every(toolCall => runtime.finalizedToolCallIds.has(toolCall.id));
 	const canSalvageCompleteArguments =
 		(isCodexTransientStreamClose(error) || isIdleStall) &&
 		!runtime.toolArgumentCorrelationFailed &&
 		toolCalls.length > 0 &&
-		context.output.content.every(block => block.type === "thinking" || block.type === "toolCall") &&
+		(runtime.currentBlock === null ||
+			runtime.currentBlock?.type === "toolCall" ||
+			(runtime.currentItem?.type === "reasoning" && runtime.currentBlock?.type === "thinking") ||
+			hasEmptyActiveMessage) &&
+		context.output.content.every(
+			block =>
+				block.type === "thinking" || block.type === "toolCall" || (block.type === "text" && block.text === ""),
+		) &&
 		hasCompleteArguments;
 	if (!canSalvageFinalizedCall && !canSalvageCompleteArguments) {
+		logCodexDebug("codex stream close salvage refused", {
+			toolArgumentCorrelationFailed: runtime.toolArgumentCorrelationFailed,
+			argumentsComplete: toolCalls.map(toolCall => {
+				const block = toolCall as ToolCall & { argumentsComplete?: boolean };
+				return block.argumentsComplete === true;
+			}),
+			sourceItemIdPresent: toolCalls.map(toolCall => {
+				const block = toolCall as ToolCall & { sourceItemId?: string };
+				return typeof block.sourceItemId === "string";
+			}),
+			sourceCallIdPresent: toolCalls.map(toolCall => {
+				const block = toolCall as ToolCall & { sourceCallId?: string };
+				return typeof block.sourceCallId === "string";
+			}),
+			currentItemType: runtime.currentItem?.type ?? null,
+			currentBlockType: runtime.currentBlock?.type ?? null,
+		});
 		return false;
 	}
 
-	if (canSalvageFinalizedCall && runtime.currentBlock?.type === "thinking") {
+	if ((canSalvageFinalizedCall || canSalvageCompleteArguments) && runtime.currentBlock?.type === "thinking") {
 		context.stream.push({
 			type: "thinking_end",
 			contentIndex: context.output.content.length - 1,
@@ -1317,33 +1384,72 @@ function trySalvageCodexFinalizedToolCalls(
 		runtime.currentBlock = null;
 	}
 
-	if (canSalvageCompleteArguments && activeToolCall && !runtime.finalizedToolCallIds.has(activeToolCall.id)) {
-		const item = runtime.currentItem;
-		const toolCall: ToolCall = {
-			type: "toolCall",
-			id: activeToolCall.id,
-			name: activeToolCall.name,
-			arguments: activeToolCall.arguments,
-		};
-		const rawPartialJson = activeToolCall.partialJson;
-		captureUnicodeEscapeEvidence(toolCall, rawPartialJson);
-		Object.assign(activeToolCall, toolCall);
-		captureUnicodeEscapeEvidence(activeToolCall, rawPartialJson);
-		delete (activeToolCall as { partialJson?: string }).partialJson;
-		delete (activeToolCall as { argumentsComplete?: boolean }).argumentsComplete;
-		delete (activeToolCall as { argumentsAuthoritative?: boolean }).argumentsAuthoritative;
-		runtime.finalizedToolCallIds.add(toolCall.id);
-		runtime.nativeOutputItems.push({
-			...item,
-			arguments: JSON.stringify(toolCall.arguments),
-			status: "completed",
-		} as Record<string, unknown>);
-		context.stream.push({
-			type: "toolcall_end",
-			contentIndex: context.output.content.length - 1,
-			toolCall,
-			partial: context.output,
-		});
+	if (canSalvageCompleteArguments) {
+		for (const toolCallBlock of completeToolCalls) {
+			const activeToolCall = toolCallBlock as ToolCall & {
+				partialJson: string;
+				argumentsComplete?: boolean;
+				argumentsAuthoritative?: boolean;
+				sourceItemId?: string;
+				sourceCallId?: string;
+				sourceName?: string;
+				sourceOutputIndex?: number;
+			};
+			const item =
+				runtime.currentBlock === activeToolCall && runtime.currentItem?.type === "function_call"
+					? runtime.currentItem
+					: {
+							type: "function_call",
+							id: activeToolCall.sourceItemId,
+							call_id: activeToolCall.sourceCallId,
+							name: activeToolCall.sourceName ?? codexToolWireName(activeToolCall.name),
+							arguments: activeToolCall.partialJson,
+						};
+			if (typeof item.id !== "string" || typeof item.call_id !== "string") continue;
+			const toolCall: ToolCall = {
+				type: "toolCall",
+				id: activeToolCall.id,
+				name: activeToolCall.name,
+				arguments: activeToolCall.arguments,
+			};
+			const rawPartialJson = activeToolCall.partialJson;
+			const sourceOutputIndex = activeToolCall.sourceOutputIndex;
+			captureUnicodeEscapeEvidence(toolCall, rawPartialJson);
+			Object.assign(activeToolCall, toolCall);
+			captureUnicodeEscapeEvidence(activeToolCall, rawPartialJson);
+			delete (activeToolCall as { partialJson?: string }).partialJson;
+			delete (activeToolCall as { argumentsComplete?: boolean }).argumentsComplete;
+			delete (activeToolCall as { argumentsAuthoritative?: boolean }).argumentsAuthoritative;
+			delete (activeToolCall as { sourceItemId?: string }).sourceItemId;
+			delete (activeToolCall as { sourceCallId?: string }).sourceCallId;
+			delete (activeToolCall as { sourceName?: string }).sourceName;
+			delete (activeToolCall as { sourceOutputIndex?: number }).sourceOutputIndex;
+			runtime.finalizedToolCallIds.add(toolCall.id);
+			const nativeOutputItem = {
+				...item,
+				name:
+					typeof item.name === "string"
+						? item.name
+						: (activeToolCall.sourceName ?? codexToolWireName(activeToolCall.name)),
+				arguments: JSON.stringify(toolCall.arguments),
+				status: "completed",
+			} as Record<string, unknown>;
+			const insertionIndex =
+				typeof sourceOutputIndex === "number"
+					? runtime.nativeOutputItemOutputIndexes.findIndex(
+							outputIndex => typeof outputIndex === "number" && outputIndex > sourceOutputIndex,
+						)
+					: -1;
+			const resolvedInsertionIndex = insertionIndex === -1 ? runtime.nativeOutputItems.length : insertionIndex;
+			runtime.nativeOutputItems.splice(resolvedInsertionIndex, 0, nativeOutputItem);
+			runtime.nativeOutputItemOutputIndexes.splice(resolvedInsertionIndex, 0, sourceOutputIndex);
+			context.stream.push({
+				type: "toolcall_end",
+				contentIndex: context.output.content.indexOf(activeToolCall),
+				toolCall,
+				partial: context.output,
+			});
+		}
 		runtime.currentItem = null;
 		runtime.currentBlock = null;
 	}
@@ -1377,7 +1483,15 @@ function isCodexTransientStreamClose(error: unknown): boolean {
 		message.includes("stream disconnected before completion") ||
 		message.includes("stream closed before response.completed") ||
 		message.includes("websocket closed before response completion");
-	return hasRequestTimeout && hasClosedStreamMessage;
+	return (hasRequestTimeout && hasClosedStreamMessage) || isCodexIdleStall(error);
+}
+
+function isCodexIdleStall(error: unknown): boolean {
+	if (!(error instanceof Error)) return false;
+	return (
+		error.message === "OpenAI Codex SSE stream stalled while waiting for the next event" ||
+		error.message === `${CODEX_WEBSOCKET_TRANSPORT_ERROR_PREFIX}: idle timeout waiting for websocket`
+	);
 }
 
 function handleCodexStreamEvent(args: {
@@ -1403,6 +1517,9 @@ function handleCodexStreamEvent(args: {
 		runtime.currentItemOutputIndex = typeof rawEvent.output_index === "number" ? rawEvent.output_index : undefined;
 		runtime.currentBlock = createOutputBlockForItem(item);
 		if (!runtime.currentBlock) return firstTokenTime;
+		if (runtime.currentBlock.type === "toolCall" && typeof runtime.currentItemOutputIndex === "number") {
+			runtime.currentBlock.sourceOutputIndex = runtime.currentItemOutputIndex;
+		}
 		const currentBlock = runtime.currentBlock;
 		if (
 			currentBlock.type === "toolCall" &&
@@ -1558,7 +1675,11 @@ function createOutputBlockForItem(item: CodexEventItem): CodexOutputBlock | null
 		const block: ToolCall & {
 			partialJson: string;
 			argumentsComplete: boolean;
-			argumentsAuthoritative: boolean;
+			argumentsAuthoritative?: boolean;
+			sourceItemId?: string;
+			sourceCallId?: string;
+			sourceName?: string;
+			sourceOutputIndex?: number;
 		} = {
 			type: "toolCall",
 			id: encodeResponsesToolCallId(item.call_id, item.id),
@@ -1567,6 +1688,9 @@ function createOutputBlockForItem(item: CodexEventItem): CodexOutputBlock | null
 			partialJson: initialArguments,
 			argumentsComplete: hasValidInitialArguments && Object.keys(parsedArguments).length > 0,
 			argumentsAuthoritative: false,
+			sourceItemId: item.id,
+			sourceCallId: item.call_id,
+			sourceName: item.name,
 		};
 		captureUnicodeEscapeEvidence(block, initialArguments);
 		return block;
@@ -1821,6 +1945,9 @@ function handleOutputItemDone(
 ): void {
 	const item = structuredCloneJSON(rawEvent.item) as CodexEventItem;
 	runtime.nativeOutputItems.push(item as unknown as Record<string, unknown>);
+	runtime.nativeOutputItemOutputIndexes.push(
+		typeof rawEvent.output_index === "number" ? rawEvent.output_index : undefined,
+	);
 
 	if (item.type === "reasoning" && runtime.currentBlock?.type === "thinking") {
 		const block = runtime.currentBlock;
@@ -1920,6 +2047,10 @@ function handleOutputItemDone(
 		delete (runtime.currentBlock as { argumentsComplete?: boolean }).argumentsComplete;
 		delete (runtime.currentBlock as { argumentsAuthoritative?: boolean }).argumentsAuthoritative;
 		delete (runtime.currentBlock as { doneInput?: string }).doneInput;
+		delete (runtime.currentBlock as { sourceItemId?: string }).sourceItemId;
+		delete (runtime.currentBlock as { sourceCallId?: string }).sourceCallId;
+		delete (runtime.currentBlock as { sourceName?: string }).sourceName;
+		delete (runtime.currentBlock as { sourceOutputIndex?: number }).sourceOutputIndex;
 		runtime.canSafelyReplayWebsocketOverSse = false;
 		stream.push({ type: "toolcall_end", contentIndex: blockIndex(), toolCall, partial: output });
 		runtime.currentItem = null;
@@ -2126,6 +2257,7 @@ async function tryRetryWithoutForcedToolChoice(
 	runtime.currentBlock = null;
 	runtime.sawTerminalEvent = false;
 	runtime.nativeOutputItems.length = 0;
+	runtime.nativeOutputItemOutputIndexes.length = 0;
 	runtime.finalizedToolCallIds.clear();
 	runtime.toolArgumentCorrelationFailed = false;
 	resetOutputState(context.output);
@@ -2225,6 +2357,7 @@ async function tryReconnectCodexWebSocketOnConnectionLimit(
 		runtime.currentItem = null;
 		runtime.currentBlock = null;
 		runtime.nativeOutputItems.length = 0;
+		runtime.nativeOutputItemOutputIndexes.length = 0;
 		runtime.finalizedToolCallIds.clear();
 		runtime.toolArgumentCorrelationFailed = false;
 		resetOutputState(context.output);
@@ -2284,6 +2417,7 @@ async function tryRecoverCodexPreviousResponseNotFound(
 	runtime.currentBlock = null;
 	runtime.sawTerminalEvent = false;
 	runtime.nativeOutputItems.length = 0;
+	runtime.nativeOutputItemOutputIndexes.length = 0;
 	runtime.finalizedToolCallIds.clear();
 	runtime.toolArgumentCorrelationFailed = false;
 	resetOutputState(context.output);
@@ -2345,6 +2479,7 @@ async function tryReplayWebsocketFailureOverSse(
 		runtime.currentItem = null;
 		runtime.currentBlock = null;
 		runtime.nativeOutputItems.length = 0;
+		runtime.nativeOutputItemOutputIndexes.length = 0;
 		runtime.finalizedToolCallIds.clear();
 		runtime.toolArgumentCorrelationFailed = false;
 		resetOutputState(context.output);
@@ -2389,6 +2524,7 @@ async function tryRetryCodexProviderError(
 	runtime.currentBlock = null;
 	runtime.sawTerminalEvent = false;
 	runtime.nativeOutputItems.length = 0;
+	runtime.nativeOutputItemOutputIndexes.length = 0;
 	runtime.finalizedToolCallIds.clear();
 	runtime.toolArgumentCorrelationFailed = false;
 	resetOutputState(context.output);
@@ -2455,17 +2591,24 @@ async function handleCodexStreamFailure(
 	output.stopReason = context.options?.signal?.aborted ? "aborted" : "error";
 	output.errorStatus = extractHttpStatusFromError(error);
 	const transportFailure = transportFailureFacts(error);
+	const codexError = error instanceof CodexProviderStreamError ? error : undefined;
+	const explicitTerminalVeto =
+		codexError !== undefined && isExplicitCodexTerminalVeto(codexError.code, codexError.providerMessage);
 	const typedProviderCode =
-		error instanceof CodexProviderStreamError && CODEX_TYPED_TRANSPORT_PROVIDER_CODES.has(error.code ?? "")
-			? error.code
+		codexError !== undefined && CODEX_TYPED_TRANSPORT_PROVIDER_CODES.has(codexError.code ?? "")
+			? codexError.code
 			: undefined;
 	output.transportFailure = typedProviderCode
-		? {
-				...(transportFailure ?? { kind: "transport" as const }),
-				providerCode: typedProviderCode,
-				...(error instanceof CodexProviderStreamError && error.deterministicVeto ? { retryMaxAttempts: 1 } : {}),
-			}
-		: transportFailure;
+		? explicitTerminalVeto
+			? undefined
+			: {
+					...(transportFailure ?? { kind: "transport" as const }),
+					providerCode: typedProviderCode,
+					...(codexError?.deterministicVeto ? { retryMaxAttempts: 1 } : {}),
+				}
+		: explicitTerminalVeto
+			? undefined
+			: transportFailure;
 	output.errorMessage = await finalizeErrorMessage(error, context.requestContext.rawRequestDump);
 	output.duration = Date.now() - context.startTime;
 	if (context.firstTokenTime) {
@@ -3594,7 +3737,7 @@ export function convertOpenAICodexResponsesTools(
 			name: codexToolWireName(tool.name),
 			description: tool.description || "",
 			parameters,
-			...(effectiveStrict && { strict: true }),
+			strict: effectiveStrict,
 		};
 	});
 	// Tool definitions bypass the `input`/`instructions` sanitizers, so a
@@ -3673,6 +3816,13 @@ function isCodexDeterministicVeto(code: string, message: string): boolean {
 	);
 }
 
+export function isExplicitCodexTerminalVeto(code?: string, providerMessage?: string): boolean {
+	return (
+		CODEX_EXPLICIT_TERMINAL_VETO_CODES.has(code?.toLowerCase() ?? "") ||
+		CODEX_NON_RETRYABLE_EVENT_MESSAGE.test(providerMessage ?? "")
+	);
+}
+
 function createCodexProviderStreamError(rawEvent: Record<string, unknown>): CodexProviderStreamError {
 	const code = getCodexEventErrorCode(rawEvent);
 	const message = getCodexEventErrorMessage(rawEvent);

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

@@ -19,6 +19,8 @@ interface HealthPayload {
 	ok?: unknown;
 	pid?: unknown;
 	port?: unknown;
+	status?: unknown;
+	service?: unknown;
 	version?: unknown;
 }
 
@@ -103,7 +105,10 @@ async function fetchJson(url: string, signal?: AbortSignal): Promise<unknown> {
 function isOpenCodexHealth(payload: unknown, expectedPort: number): boolean {
 	if (!payload || typeof payload !== "object" || Array.isArray(payload)) return false;
 	const health = payload as HealthPayload;
-	return health.ok === true && health.version === "opencodex" && health.port === expectedPort;
+	const identityOk =
+		(health.ok === true && health.version === "opencodex") ||
+		(health.status === "ok" && health.service === "opencodex");
+	return identityOk && health.port === expectedPort;
 }
 
 export async function resolveOpenCodexEndpoint(signal?: AbortSignal): Promise<OpenCodexEndpoint | undefined> {

package/src/providers/openai-responses.ts

@@ -1006,7 +1006,7 @@ export function convertTools(tools: Tool[], strictMode: boolean, model: Model<"o
 			name: tool.name,
 			description: tool.description || "",
 			parameters,
-			...(effectiveStrict && { strict: true }),
+			strict: effectiveStrict,
 		} as OpenAITool;
 	});
 	// Tool definitions bypass the `input`/`instructions` sanitizers, so a

package/src/providers/register-builtins.ts

@@ -11,6 +11,7 @@
  * loader: heavy SDKs stay out of the CLI startup parse graph.
  */
 
+import { $env } from "@gajae-code/utils";
 import type {
 	Api,
 	AssistantMessage,
@@ -280,16 +281,33 @@ function forwardStream<TApi extends Api>(
 					model.provider,
 					limits?.defaultFirstEventTimeoutMs,
 				);
+				const firstEventTimeoutMs =
+					options.streamFirstEventTimeoutMs ?? getStreamFirstEventTimeoutMs(idleTimeoutMs, firstEventFallbackMs);
+				const firstEventTimeoutSource =
+					options.streamFirstEventTimeoutMs !== undefined
+						? "stream-option"
+						: $env.PI_STREAM_FIRST_EVENT_TIMEOUT_MS !== undefined &&
+								Number.isFinite(Number($env.PI_STREAM_FIRST_EVENT_TIMEOUT_MS))
+							? "env"
+							: idleTimeoutMs !== undefined &&
+									(firstEventFallbackMs === undefined || idleTimeoutMs >= firstEventFallbackMs)
+								? "idle-timeout"
+								: firstEventFallbackMs !== undefined
+									? "provider-fallback"
+									: "default";
 				watchedSource = iterateWithIdleTimeout(source, {
 					idleTimeoutMs,
-					firstItemTimeoutMs:
-						options.streamFirstEventTimeoutMs ??
-						getStreamFirstEventTimeoutMs(idleTimeoutMs, firstEventFallbackMs),
+					firstItemTimeoutMs: firstEventTimeoutMs,
 					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 FirstEventTimeoutError(LAZY_STREAM_FIRST_EVENT_TIMEOUT_ERROR)),
+						abortTracker.abortLocally(
+							new FirstEventTimeoutError(LAZY_STREAM_FIRST_EVENT_TIMEOUT_ERROR, {
+								firstEventTimeoutMs,
+								firstEventTimeoutSource,
+							}),
+						),
 					abortSignal: options.signal,
 					// Synthetic starts and tool-capability negotiation are control-plane events,
 					// not model progress. Keep the first-event window active until assistant output
@@ -313,7 +331,7 @@ function forwardStream<TApi extends Api>(
 			}
 		} catch (error) {
 			const stopReason = abortTracker.wasCallerAbort() ? "aborted" : "error";
-			const message = createLazyLoadErrorMessage(model, error, stopReason);
+			const message = createLazyLoadErrorMessage(model, error, stopReason, source);
 			target.push({ type: "error", reason: stopReason, error: message });
 			target.end(message);
 		}
@@ -324,8 +342,37 @@ function createLazyLoadErrorMessage<TApi extends Api>(
 	model: Model<TApi>,
 	error: unknown,
 	stopReason: Extract<AssistantMessage["stopReason"], "aborted" | "error"> = "error",
+	source?: AsyncIterable<AssistantMessageEvent>,
 ): AssistantMessage {
 	const transportFailure = transportFailureFacts(error);
+	const carriedDiagnostics =
+		source && typeof source === "object"
+			? (source as { googleGeminiCliDiagnostics?: AssistantMessage["googleGeminiCliDiagnostics"] })
+					.googleGeminiCliDiagnostics
+			: undefined;
+	const diagnostics =
+		carriedDiagnostics ??
+		(error instanceof FirstEventTimeoutError
+			? (
+					error as FirstEventTimeoutError & {
+						googleGeminiCliDiagnostics?: AssistantMessage["googleGeminiCliDiagnostics"];
+					}
+				).googleGeminiCliDiagnostics
+			: undefined);
+	if (diagnostics && typeof error === "object" && error !== null) {
+		const timeoutFacts = error as {
+			firstEventTimeoutMs?: unknown;
+			firstEventTimeoutSource?: unknown;
+		};
+		if (typeof timeoutFacts.firstEventTimeoutMs === "number") {
+			diagnostics.firstEventTimeoutMs = timeoutFacts.firstEventTimeoutMs;
+		}
+		if (typeof timeoutFacts.firstEventTimeoutSource === "string") {
+			diagnostics.firstEventTimeoutSource = timeoutFacts.firstEventTimeoutSource as NonNullable<
+				AssistantMessage["googleGeminiCliDiagnostics"]
+			>["firstEventTimeoutSource"];
+		}
+	}
 	return {
 		role: "assistant",
 		content: [],
@@ -344,6 +391,7 @@ function createLazyLoadErrorMessage<TApi extends Api>(
 		errorMessage:
 			stopReason === "aborted" ? "Request was aborted" : error instanceof Error ? error.message : String(error),
 		...(transportFailure ? { transportFailure } : {}),
+		...(diagnostics ? { googleGeminiCliDiagnostics: diagnostics } : {}),
 		timestamp: Date.now(),
 	};
 }

package/src/types.d.ts

@@ -640,6 +640,8 @@ export interface AssistantMessage {
      * supplied no trustworthy structured evidence.
      */
     providerDiagnostic?: ProviderDiagnostic;
+    /** Redacted first-event transport timing and chunk-shape diagnostics for Google Gemini CLI. */
+    googleGeminiCliDiagnostics?: GoogleGeminiCliDiagnostics;
     /** Typed upstream failure facts retained for retry classification without parsing errorMessage. */
     transportFailure?: TransportFailureFacts;
     /**
@@ -658,6 +660,19 @@ export interface AssistantMessage {
     /** Prompt-prefix fingerprint of the request that produced this message. */
     promptPrefix?: PromptPrefixTelemetry;
 }
+export interface GoogleGeminiCliDiagnostics {
+    responseAtMs?: number;
+    firstRawSseAtMs?: number;
+    chunkCounts: {
+        content: number;
+        thinking: number;
+        functionCall: number;
+        usageOnly: number;
+        other: number;
+    };
+    firstEventTimeoutMs?: number;
+    firstEventTimeoutSource?: "stream-option" | "env" | "idle-timeout" | "provider-fallback" | "default";
+}
 export interface ToolResultMessage<TDetails = any> {
     role: "toolResult";
     toolCallId: string;

package/src/types.ts

@@ -881,6 +881,8 @@ export interface AssistantMessage {
 	 * supplied no trustworthy structured evidence.
 	 */
 	providerDiagnostic?: ProviderDiagnostic;
+	/** Redacted first-event transport timing and chunk-shape diagnostics for Google Gemini CLI. */
+	googleGeminiCliDiagnostics?: GoogleGeminiCliDiagnostics;
 	/** Typed upstream failure facts retained for retry classification without parsing errorMessage. */
 	transportFailure?: TransportFailureFacts;
 	/**
@@ -900,6 +902,20 @@ export interface AssistantMessage {
 	promptPrefix?: PromptPrefixTelemetry;
 }
 
+export interface GoogleGeminiCliDiagnostics {
+	responseAtMs?: number;
+	firstRawSseAtMs?: number;
+	chunkCounts: {
+		content: number;
+		thinking: number;
+		functionCall: number;
+		usageOnly: number;
+		other: number;
+	};
+	firstEventTimeoutMs?: number;
+	firstEventTimeoutSource?: "stream-option" | "env" | "idle-timeout" | "provider-fallback" | "default";
+}
+
 export interface ToolResultMessage<TDetails = any> {
 	role: "toolResult";
 	toolCallId: string;

package/src/utils/idle-iterator.d.ts

@@ -72,6 +72,7 @@ export interface FirstEventTimeoutFacts {
     requestBytes?: number;
     firstEventElapsedMs?: number;
     firstEventTimeoutMs?: number;
+    firstEventTimeoutSource?: "stream-option" | "env" | "idle-timeout" | "provider-fallback" | "default";
     endpointClass?: "canonical" | "custom";
     retryMaxAttempts?: number;
 }
@@ -80,6 +81,7 @@ export declare class FirstEventTimeoutError extends Error {
     readonly requestBytes?: number;
     readonly firstEventElapsedMs?: number;
     readonly firstEventTimeoutMs?: number;
+    readonly firstEventTimeoutSource?: FirstEventTimeoutFacts["firstEventTimeoutSource"];
     readonly endpointClass?: "canonical" | "custom";
     readonly retryMaxAttempts?: number;
     constructor(message: string, facts?: FirstEventTimeoutFacts);

package/src/utils/idle-iterator.ts

@@ -179,6 +179,7 @@ export interface FirstEventTimeoutFacts {
 	requestBytes?: number;
 	firstEventElapsedMs?: number;
 	firstEventTimeoutMs?: number;
+	firstEventTimeoutSource?: "stream-option" | "env" | "idle-timeout" | "provider-fallback" | "default";
 	endpointClass?: "canonical" | "custom";
 	retryMaxAttempts?: number;
 }
@@ -188,6 +189,7 @@ export class FirstEventTimeoutError extends Error {
 	readonly requestBytes?: number;
 	readonly firstEventElapsedMs?: number;
 	readonly firstEventTimeoutMs?: number;
+	readonly firstEventTimeoutSource?: FirstEventTimeoutFacts["firstEventTimeoutSource"];
 	readonly endpointClass?: "canonical" | "custom";
 	readonly retryMaxAttempts?: number;
 
@@ -197,6 +199,7 @@ export class FirstEventTimeoutError extends Error {
 		this.requestBytes = facts.requestBytes;
 		this.firstEventElapsedMs = facts.firstEventElapsedMs;
 		this.firstEventTimeoutMs = facts.firstEventTimeoutMs;
+		this.firstEventTimeoutSource = facts.firstEventTimeoutSource;
 		this.endpointClass = facts.endpointClass;
 		this.retryMaxAttempts = facts.retryMaxAttempts;
 	}