@gajae-code/ai 0.13.2 → 0.14.0

package/src/stream.ts

@@ -32,6 +32,7 @@ import type { CursorOptions } from "./providers/cursor";
 import type { GoogleOptions } from "./providers/google";
 import type { GoogleGeminiCliOptions } from "./providers/google-gemini-cli";
 import type { GoogleVertexOptions } from "./providers/google-vertex";
+import type { KiroCodeWhispererOptions } from "./providers/kiro-codewhisperer";
 import type { OllamaChatOptions } from "./providers/ollama";
 import type { OpenAICompletionsOptions } from "./providers/openai-completions";
 // Heavy provider stream functions are imported lazily via register-builtins,
@@ -46,6 +47,7 @@ import {
 	streamGoogle,
 	streamGoogleGeminiCli,
 	streamGoogleVertex,
+	streamKiroCodeWhisperer,
 	streamOllama,
 	streamOpenAICodexResponses,
 	streamOpenAICompletions,
@@ -119,6 +121,11 @@ const serviceProviderMap: Record<string, KeyResolver> = {
 	tavily: "TAVILY_API_KEY",
 	parallel: "PARALLEL_API_KEY",
 	kagi: "KAGI_API_KEY",
+	// Kiro uses AWS SSO OIDC OAuth flow; bearer token is stored as the OAuth access token.
+	kiro: () => {
+		const bearerToken = $credentialEnv("AWS_BEARER_TOKEN_KIRO");
+		if (bearerToken) return bearerToken;
+	},
 	// GitHub Copilot uses GitHub personal access token
 	"github-copilot": () => $pickCredentialEnv("COPILOT_GITHUB_TOKEN", "GH_TOKEN", "GITHUB_TOKEN"),
 	// Foundry mode optionally switches Anthropic auth to enterprise gateway credentials.
@@ -156,6 +163,7 @@ const serviceProviderMap: Record<string, KeyResolver> = {
 	nvidia: "NVIDIA_API_KEY",
 	nanogpt: "NANO_GPT_API_KEY",
 	"lm-studio": "LM_STUDIO_API_KEY",
+	omlx: "OMLX_API_KEY",
 	ollama: "OLLAMA_API_KEY",
 	"ollama-cloud": "OLLAMA_CLOUD_API_KEY",
 	"llama.cpp": "LLAMA_CPP_API_KEY",
@@ -330,6 +338,12 @@ export function stream<TApi extends Api>(
 	} else if (model.api === "bedrock-converse-stream") {
 		// Bedrock doesn't have any API keys instead it sources credentials from standard AWS env variables or from given AWS profile.
 		return streamBedrock(model as Model<"bedrock-converse-stream">, context, (options || {}) as BedrockOptions);
+	} else if (model.api === "kiro-codewhisperer-stream") {
+		return streamKiroCodeWhisperer(
+			model as Model<"kiro-codewhisperer-stream">,
+			context,
+			(options || {}) as KiroCodeWhispererOptions,
+		);
 	}
 
 	const apiKey = options?.apiKey || (model.provider === "opencodex" ? "local" : getEnvApiKey(model.provider));
@@ -480,7 +494,11 @@ export function streamSimple<TApi extends Api>(
 	}
 	const retryApiKey = options?.onAuthError ? (options.apiKey ?? getEnvApiKey(model.provider)) : undefined;
 	if (retryApiKey) {
-		const outer = new AssistantMessageEventStream();
+		const consumerAbortController = new AbortController();
+		const outer = new AssistantMessageEventStream(() => consumerAbortController.abort());
+		const requestSignal = options?.signal
+			? AbortSignal.any([options.signal, consumerAbortController.signal])
+			: consumerAbortController.signal;
 		const onAuthError = options!.onAuthError!;
 		const runAttempt = async (apiKey: string, captureAuthFailure: boolean): Promise<AuthRetryFailure | undefined> => {
 			const bufferedEvents: AssistantMessageEvent[] = [];
@@ -491,7 +509,12 @@ export function streamSimple<TApi extends Api>(
 			};
 
 			try {
-				const inner = streamSimple(model, context, { ...options, apiKey, onAuthError: undefined });
+				const inner = streamSimple(model, context, {
+					...options,
+					apiKey,
+					onAuthError: undefined,
+					signal: requestSignal,
+				});
 				for await (const event of inner) {
 					if (!emittedReplayUnsafeEvent && event.type === "start") {
 						bufferedEvents.push(event);

package/src/types.ts

@@ -23,6 +23,7 @@ import type {
 import type { GoogleOptions } from "./providers/google";
 import type { GoogleGeminiCliOptions } from "./providers/google-gemini-cli";
 import type { GoogleVertexOptions } from "./providers/google-vertex";
+import type { KiroCodeWhispererOptions } from "./providers/kiro-codewhisperer";
 import type { OllamaChatOptions } from "./providers/ollama";
 import type { OpenAICodexResponsesOptions } from "./providers/openai-codex-responses";
 import type { OpenAICompletionsOptions } from "./providers/openai-completions";
@@ -43,7 +44,8 @@ export type KnownApi =
 	| "google-gemini-cli"
 	| "google-vertex"
 	| "ollama-chat"
-	| "cursor-agent";
+	| "cursor-agent"
+	| "kiro-codewhisperer-stream";
 export type Api = KnownApi | (string & {});
 export interface ApiOptionsMap {
 	"anthropic-messages": AnthropicOptions;
@@ -57,6 +59,7 @@ export interface ApiOptionsMap {
 	"google-vertex": GoogleVertexOptions;
 	"ollama-chat": OllamaChatOptions;
 	"cursor-agent": CursorOptions;
+	"kiro-codewhisperer-stream": KiroCodeWhispererOptions;
 }
 // Compile-time exhaustiveness check - this will fail if ApiOptionsMap doesn't have all KnownApi keys
 type _CheckExhaustive =
@@ -116,6 +119,7 @@ export interface ThinkingConfig {
 export const KNOWN_PROVIDERS = [
 	"alibaba-token-plan",
 	"amazon-bedrock",
+	"kiro",
 	"azure-openai",
 	"anthropic",
 	"google",
@@ -172,6 +176,7 @@ export const KNOWN_PROVIDERS = [
 	"xiaomi-token-plan-cn",
 	"zenmux",
 	"lm-studio",
+	"omlx",
 ] as const;
 
 export type KnownProvider = (typeof KNOWN_PROVIDERS)[number];
@@ -577,13 +582,37 @@ export interface ToolCall {
 	 */
 	customWireName?: string;
 	/**
-	 * Set when the provider detected the argument JSON was truncated — the model
-	 * hit its output-token limit (or the response was otherwise cut short) before
-	 * emitting a complete arguments object. The `arguments` field then holds a
-	 * best-effort partial parse and must not be executed as-is; the agent loop
-	 * rejects the call with a retryable error instead.
+	 * Set when the provider detected the argument JSON was not safely executable —
+	 * the model hit its output-token limit (or the response was otherwise cut short)
+	 * before emitting a complete arguments object, the terminal payload was malformed,
+	 * the streamed and terminal payloads conflicted, or the tool-call identity was
+	 * ambiguous on the wire. The `arguments` field then holds a best-effort partial
+	 * parse and must not be executed as-is; the agent loop rejects the call with a
+	 * retryable, reason-specific error instead.
 	 */
 	incompleteArguments?: boolean;
+	/**
+	 * When `incompleteArguments` is set, the typed cause so the agent loop can give
+	 * reason-specific recovery guidance:
+	 *  - `"truncated"`: the response was cut short mid-arguments (output-token limit).
+	 *  - `"malformed"`: the terminal arguments did not decode to a valid JSON object.
+	 *  - `"conflicting"`: the streamed and terminal argument payloads disagree.
+	 *  - `"ambiguous"`: the tool-call identity could not be unambiguously resolved
+	 *    (duplicate `call_id`, id/call_id collision, etc.), so attribution is unsafe.
+	 * Absent when `incompleteArguments` is not set. Existing callers that read only
+	 * `incompleteArguments` continue to work.
+	 */
+	incompleteArgumentsReason?: "truncated" | "malformed" | "conflicting" | "ambiguous";
+	/**
+	 * Set when the raw argument JSON spelled a printable non-ASCII character as a
+	 * `\uXXXX` escape instead of literal UTF-8. Such a payload parses cleanly but
+	 * is unverifiable: one mistyped hex digit decodes to a different, equally
+	 * valid character, so the text can be silently wrong with no in-band evidence.
+	 * The agent loop rejects the call with a retryable error instead of executing
+	 * it. Escapes that are required (control characters) or unavoidable (lone
+	 * surrogates) never set this.
+	 */
+	escapedNonAsciiArguments?: boolean;
 }
 
 export interface Usage {
@@ -634,7 +663,7 @@ export interface Usage {
 }
 
 export type StopReason = "stop" | "length" | "toolUse" | "error" | "aborted";
-export type AssistantErrorKind = "provider_safety_stop";
+export type AssistantErrorKind = "provider_safety_stop" | "local_snapshot_failure" | "local_buffer_overflow";
 
 export interface OpenAIResponsesHistoryPayload {
 	type: "openaiResponsesHistory";

package/src/usage/grok-cli.ts

@@ -13,8 +13,15 @@ interface BillingUsage {
 	used: number;
 	billingPeriodEnd: string;
 }
+
+interface WeeklyBillingUsage {
+	creditUsagePercent: number;
+	billingPeriodEnd: string;
+}
+
 const DEFAULT_GROK_BUILD_BASE_URL = "https://cli-chat-proxy.grok.com/v1";
 const ALLOWED_GROK_BUILD_HOSTS = new Set(["cli-chat-proxy.grok.com"]);
+const GROK_WEEKLY_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
 
 function isRecord(value: unknown): value is Record<string, unknown> {
 	return !!value && typeof value === "object";
@@ -46,6 +53,23 @@ export function parseGrokCliBillingUsage(payload: unknown): BillingUsage {
 	return { monthlyLimit, used, billingPeriodEnd };
 }
 
+export function parseGrokCliWeeklyBillingUsage(payload: unknown): WeeklyBillingUsage | undefined {
+	if (!isRecord(payload) || !isRecord(payload.config)) return undefined;
+	const currentPeriod = isRecord(payload.config.currentPeriod) ? payload.config.currentPeriod : undefined;
+	if (currentPeriod?.type !== "USAGE_PERIOD_TYPE_WEEKLY") return undefined;
+
+	const billingPeriodEnd = payload.config.billingPeriodEnd;
+	if (typeof billingPeriodEnd !== "string" || !Number.isFinite(new Date(billingPeriodEnd).getTime())) {
+		return undefined;
+	}
+
+	const rawCreditUsagePercent = payload.config.creditUsagePercent;
+	const creditUsagePercent = rawCreditUsagePercent === undefined ? 0 : finiteNumber(rawCreditUsagePercent);
+	if (creditUsagePercent === undefined) return undefined;
+
+	return { creditUsagePercent, billingPeriodEnd };
+}
+
 function isAllowedGrokCredentialHost(baseUrl: string): boolean {
 	try {
 		const url = new URL(baseUrl);
@@ -108,6 +132,33 @@ function buildMonthlyUsageLimit(usage: BillingUsage, nowMs: number): UsageLimit
 	};
 }
 
+function buildWeeklyUsageLimit(usage: WeeklyBillingUsage): UsageLimit {
+	const percent = Math.min(Math.max(usage.creditUsagePercent, 0), 100);
+	const usedFraction = percent / 100;
+	const resetsAt = new Date(usage.billingPeriodEnd).getTime();
+	return {
+		id: "grok-build:weekly",
+		label: "SuperGrok weekly credits",
+		scope: { provider: "grok-build", shared: true, windowId: "weekly" },
+		window: {
+			id: "weekly",
+			label: "Weekly",
+			durationMs: GROK_WEEKLY_WINDOW_MS,
+			resetsAt,
+		},
+		amount: {
+			unit: "percent",
+			used: percent,
+			limit: 100,
+			remaining: 100 - percent,
+			usedFraction,
+			remainingFraction: 1 - usedFraction,
+		},
+		status: percent >= 95 ? "exhausted" : percent >= 80 ? "warning" : "ok",
+		notes: [`${percent}% used`],
+	};
+}
+
 export const grokCliUsageProvider: UsageProvider = {
 	id: "grok-build",
 
@@ -151,10 +202,42 @@ export const grokCliUsageProvider: UsageProvider = {
 		}
 
 		const nowMs = Date.now();
+		let weekly: WeeklyBillingUsage | undefined;
+		try {
+			const weeklyResponse = await ctx.fetch(`${billingBaseUrl}/billing?format=credits`, {
+				headers: {
+					Authorization: `Bearer ${accessToken}`,
+					"x-xai-token-auth": "xai-grok-cli",
+					accept: "application/json",
+				},
+				signal: params.signal,
+			});
+			if (weeklyResponse.ok) {
+				weekly = parseGrokCliWeeklyBillingUsage((await weeklyResponse.json()) as unknown);
+			}
+		} catch (error) {
+			if (params.signal?.aborted && billing.monthlyLimit <= 0) throw error;
+			ctx.logger?.debug("Grok Build weekly billing request failed", { error: String(error) });
+		}
+
+		const limits: UsageLimit[] = [];
+		if (billing.monthlyLimit > 0) {
+			limits.push(buildMonthlyUsageLimit(billing, nowMs));
+		}
+		if (weekly) {
+			limits.push(buildWeeklyUsageLimit(weekly));
+		}
+		if (limits.length === 0) {
+			ctx.logger?.warn("Grok Build billing response contained no usable quota", {
+				provider: params.provider,
+			});
+			return null;
+		}
+
 		return {
 			provider: "grok-build",
 			fetchedAt: nowMs,
-			limits: [buildMonthlyUsageLimit(billing, nowMs)],
+			limits,
 			metadata: {
 				email: params.credential.email,
 				accountId: params.credential.accountId,
@@ -167,6 +250,8 @@ export const grokCliUsageProvider: UsageProvider = {
 
 export const grokCliRankingStrategy: CredentialRankingStrategy = {
 	findWindowLimits(report) {
+		const weekly = report.limits.find(limit => limit.id === "grok-build:weekly");
+		if (weekly) return { secondary: weekly };
 		const monthly = report.limits.find(limit => limit.id === "grok-build:7d");
 		return { secondary: monthly };
 	},

package/src/usage.ts

@@ -131,6 +131,12 @@ export interface UsageLogger {
 }
 
 /** Credential bundle for usage endpoints. */
+/** MCP OAuth authority carried through usage-triggered refresh. */
+export interface UsageMCPOAuthBinding {
+	resourceOrigin: string;
+	tokenEndpoint: string;
+}
+
 export interface UsageCredential {
 	type: "api_key" | "oauth";
 	apiKey?: string;
@@ -141,6 +147,7 @@ export interface UsageCredential {
 	projectId?: string;
 	email?: string;
 	enterpriseUrl?: string;
+	mcpBinding?: UsageMCPOAuthBinding;
 	metadata?: Record<string, unknown>;
 }
 

package/src/utils/discovery/openai-compatible.ts

@@ -1,8 +1,10 @@
 import { UNK_CONTEXT_WINDOW, UNK_MAX_TOKENS } from "@gajae-code/ai";
 import * as z from "zod/v4";
 import type { Api, FetchImpl, Model, Provider } from "../../types";
+import { toNumber } from "../../utils";
 
 const MODELS_PATH = "/models";
+const MAX_MODELS_RESPONSE_BYTES = 1_000_000;
 
 /**
  * Minimal OpenAI-style model entry shape consumed by discovery.
@@ -100,6 +102,26 @@ export interface FetchOpenAICompatibleModelsOptions<TApi extends Api> {
 	) => Model<TApi> | null;
 }
 
+/**
+ * Resolves an endpoint for an implicit local provider without allowing an
+ * environment override to turn its keyless discovery into a remote request.
+ */
+export function resolveLoopbackOpenAIBaseUrl(value: string | undefined, fallback: string): string {
+	const candidate = value?.trim();
+	if (!candidate) return fallback;
+	try {
+		const parsed = new URL(candidate);
+		const host = parsed.hostname.toLowerCase();
+		const isLoopback = host === "localhost" || host === "::1" || /^127(?:\.\d{1,3}){3}$/.test(host);
+		if ((parsed.protocol === "http:" || parsed.protocol === "https:") && isLoopback) {
+			return candidate;
+		}
+	} catch {
+		// Fall back to the fixed loopback endpoint below.
+	}
+	return fallback;
+}
+
 /**
  * Fetches and normalizes an OpenAI-compatible `/models` catalog.
  *
@@ -128,7 +150,9 @@ export async function fetchOpenAICompatibleModels<TApi extends Api>(
 		response = await fetchImpl(buildModelsUrl(baseUrl), {
 			method: "GET",
 			headers: requestHeaders,
-			signal: options.signal,
+			signal: options.signal
+				? AbortSignal.any([options.signal, AbortSignal.timeout(5_000)])
+				: AbortSignal.timeout(5_000),
 		});
 	} catch {
 		return null;
@@ -144,7 +168,7 @@ export async function fetchOpenAICompatibleModels<TApi extends Api>(
 
 	let payload: unknown;
 	try {
-		payload = await response.json();
+		payload = JSON.parse(await readModelsResponse(response));
 	} catch {
 		return null;
 	}
@@ -162,6 +186,17 @@ export async function fetchOpenAICompatibleModels<TApi extends Api>(
 
 	const deduped = new Map<string, Model<TApi>>();
 	for (const entry of entries) {
+		const rawContextWindow = firstPositiveModelNumber(
+			UNK_CONTEXT_WINDOW,
+			entry.max_model_len,
+			entry.context_length,
+			entry.context_window,
+			entry.max_context_length,
+			entry.max_position_embeddings,
+		);
+
+		const rawMaxTokens = firstPositiveModelNumber(UNK_MAX_TOKENS, entry.max_tokens, entry.max_output_tokens);
+
 		const defaults: Model<TApi> = {
 			id: entry.id,
 			name: typeof entry.name === "string" && entry.name.length > 0 ? entry.name : entry.id,
@@ -171,8 +206,8 @@ export async function fetchOpenAICompatibleModels<TApi extends Api>(
 			reasoning: false,
 			input: ["text"],
 			cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-			contextWindow: UNK_CONTEXT_WINDOW,
-			maxTokens: UNK_MAX_TOKENS,
+			contextWindow: rawContextWindow,
+			maxTokens: rawMaxTokens,
 		};
 
 		const mapped = options.mapModel?.(entry, defaults, context) ?? defaults;
@@ -188,6 +223,39 @@ export async function fetchOpenAICompatibleModels<TApi extends Api>(
 	return Array.from(deduped.values()).sort((left, right) => left.id.localeCompare(right.id));
 }
 
+async function readModelsResponse(response: Response): Promise<string> {
+	const contentLength = Number(response.headers.get("content-length"));
+	if (Number.isFinite(contentLength) && contentLength > MAX_MODELS_RESPONSE_BYTES) {
+		throw new Error("OpenAI-compatible models response exceeds the size limit");
+	}
+	if (!response.body) return "";
+	const reader = response.body.getReader();
+	const chunks: Uint8Array[] = [];
+	let total = 0;
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			if (!value) continue;
+			total += value.byteLength;
+			if (total > MAX_MODELS_RESPONSE_BYTES) {
+				await reader.cancel();
+				throw new Error("OpenAI-compatible models response exceeds the size limit");
+			}
+			chunks.push(value);
+		}
+	} finally {
+		reader.releaseLock();
+	}
+	const body = new Uint8Array(total);
+	let offset = 0;
+	for (const chunk of chunks) {
+		body.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	return new TextDecoder().decode(body);
+}
+
 function normalizeBaseUrl(baseUrl: string): string {
 	const trimmed = baseUrl.trim();
 	if (!trimmed) {
@@ -244,3 +312,20 @@ function extractModelEntriesFromNode(node: unknown): ParsedOpenAICompatibleModel
 
 	return null;
 }
+
+/**
+ * First finite positive number among candidates, else the fallback.
+ *
+ * Rejects non-numbers, non-finite values (JSON `1e400` parses to
+ * `Infinity`), zero, and negatives so a malformed catalog field can never
+ * poison compaction thresholds or output budgets with `Infinity`.
+ */
+function firstPositiveModelNumber(fallback: number, ...candidates: readonly unknown[]): number {
+	for (const candidate of candidates) {
+		const value = toNumber(candidate);
+		if (value !== undefined && value > 0 && Number.isFinite(value)) {
+			return value;
+		}
+	}
+	return fallback;
+}

package/src/utils/event-stream.ts

@@ -35,8 +35,9 @@ export class EventStream<T, R = T> implements AsyncIterable<T> {
 	rejectFinalResult!: (err: unknown) => void;
 	isComplete: (event: T) => boolean;
 	extractResult: (event: T) => R;
+	#onConsumerClose?: () => void;
 
-	constructor(isComplete: (event: T) => boolean, extractResult: (event: T) => R) {
+	constructor(isComplete: (event: T) => boolean, extractResult: (event: T) => R, onConsumerClose?: () => void) {
 		const { promise, resolve, reject } = Promise.withResolvers<R>();
 		// Prevent an unhandled rejection when fail() is called but nobody awaits result().
 		// Callers who do await result() still receive the rejection normally.
@@ -46,6 +47,7 @@ export class EventStream<T, R = T> implements AsyncIterable<T> {
 		this.rejectFinalResult = reject;
 		this.isComplete = isComplete;
 		this.extractResult = extractResult;
+		this.#onConsumerClose = onConsumerClose;
 	}
 
 	#enqueue(node: QueueNode<T>): void {
@@ -82,6 +84,11 @@ export class EventStream<T, R = T> implements AsyncIterable<T> {
 		return this.#pendingConsumerDrains.size;
 	}
 
+	/** Whether an async iterator is currently consuming this stream. */
+	get hasActiveConsumer(): boolean {
+		return this.#activeConsumerCount > 0;
+	}
+
 	#settleConsumerDrain(drain: ConsumerDrain, status: "resolve" | "reject", reason?: unknown): void {
 		if (drain.settled) return;
 		drain.settled = true;
@@ -235,6 +242,7 @@ export class EventStream<T, R = T> implements AsyncIterable<T> {
 		} finally {
 			this.#activeConsumerCount -= 1;
 			this.#settleAllConsumerDrains("reject", new Error("Event stream consumer stopped before drain completed"));
+			if (!this.done) this.#onConsumerClose?.();
 		}
 	}
 
@@ -244,7 +252,7 @@ export class EventStream<T, R = T> implements AsyncIterable<T> {
 }
 
 export class AssistantMessageEventStream extends EventStream<AssistantMessageEvent, AssistantMessage> {
-	constructor() {
+	constructor(onConsumerClose?: () => void) {
 		super(
 			event => event.type === "done" || event.type === "error",
 			event => {
@@ -255,6 +263,7 @@ export class AssistantMessageEventStream extends EventStream<AssistantMessageEve
 				}
 				throw new Error("Unexpected event type for final result");
 			},
+			onConsumerClose,
 		);
 	}
 }

package/src/utils/fallback-transport.ts

@@ -49,6 +49,16 @@ export interface TransportFailureFacts {
 	/** OpenAI's typed `error.code`, preserved separately at the transport boundary. */
 	openaiErrorCode?: string;
 	headers?: Record<string, string>;
+	/** Safe request-size observation for retry amplification policy. Never contains body content. */
+	requestBytes?: number;
+	/** Time spent waiting for the first semantic stream event on the failed request. */
+	firstEventElapsedMs?: number;
+	/** Configured first-event window before any bounded endpoint grace. */
+	firstEventTimeoutMs?: number;
+	/** Coarse endpoint class; deliberately excludes host, path, credentials, and query parameters. */
+	endpointClass?: "canonical" | "custom";
+	/** Provider-supplied ceiling for total attempts, including the initial request. */
+	retryMaxAttempts?: number;
 }
 
 /** Opaque per-invocation marker required by managed fallback transport calls. */
@@ -118,6 +128,14 @@ function finiteStatus(value: unknown): number | undefined {
 	return typeof value === "number" && Number.isFinite(value) ? value : undefined;
 }
 
+function finiteNonNegativeInteger(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : undefined;
+}
+
+function finitePositiveInteger(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : undefined;
+}
+
 function stringValue(value: unknown): string | undefined {
 	return typeof value === "string" ? value : undefined;
 }
@@ -207,6 +225,13 @@ export function transportFailureFacts(
 	// (consumers deliberately re-run transportFailureFacts on embedded facts).
 	const headers = retainedHeaderRecord(rawHeaders);
 	const normalizedCode = providerCode?.toLowerCase();
+	const requestBytes = finiteNonNegativeInteger(propertyOf(value, "requestBytes"));
+	const firstEventElapsedMs = finiteNonNegativeInteger(propertyOf(value, "firstEventElapsedMs"));
+	const firstEventTimeoutMs = finiteNonNegativeInteger(propertyOf(value, "firstEventTimeoutMs"));
+	const retryMaxAttempts = finitePositiveInteger(propertyOf(value, "retryMaxAttempts"));
+	const endpointClassValue = propertyOf(value, "endpointClass");
+	const endpointClass =
+		endpointClassValue === "canonical" || endpointClassValue === "custom" ? endpointClassValue : undefined;
 	if (
 		status === undefined &&
 		headers === undefined &&
@@ -215,11 +240,28 @@ export function transportFailureFacts(
 		!isRateLimitCode(normalizedCode) &&
 		!isContextOverflowCode(normalizedCode) &&
 		normalizedCode !== STREAM_FIRST_EVENT_TIMEOUT_PROVIDER_CODE &&
-		normalizedCode !== EMPTY_RESPONSE_PROVIDER_CODE
+		normalizedCode !== EMPTY_RESPONSE_PROVIDER_CODE &&
+		requestBytes === undefined &&
+		firstEventElapsedMs === undefined &&
+		firstEventTimeoutMs === undefined &&
+		endpointClass === undefined &&
+		retryMaxAttempts === undefined
 	) {
 		return undefined;
 	}
-	return { kind: "transport", status, providerCode, anthropicErrorType, openaiErrorCode, headers };
+	return {
+		kind: "transport",
+		status,
+		providerCode,
+		anthropicErrorType,
+		openaiErrorCode,
+		headers,
+		...(requestBytes === undefined ? {} : { requestBytes }),
+		...(firstEventElapsedMs === undefined ? {} : { firstEventElapsedMs }),
+		...(firstEventTimeoutMs === undefined ? {} : { firstEventTimeoutMs }),
+		...(endpointClass === undefined ? {} : { endpointClass }),
+		...(retryMaxAttempts === undefined ? {} : { retryMaxAttempts }),
+	};
 }
 
 function headersOf(headers: TransportHeaders | undefined): Headers | undefined {

package/src/utils/http-inspector.ts

@@ -12,6 +12,7 @@ export type RawHttpRequestDump = {
 	url?: string;
 	headers?: Record<string, string>;
 	body?: unknown;
+	diagnostics?: Record<string, unknown>;
 };
 
 export type CapturedHttpErrorResponse = {

package/src/utils/idle-iterator.ts

@@ -106,12 +106,30 @@ export function resolveOpenAISdkRequestTimeoutMs(
 }
 
 export type Watchdog = NodeJS.Timeout | undefined;
+export interface FirstEventTimeoutFacts {
+	requestBytes?: number;
+	firstEventElapsedMs?: number;
+	firstEventTimeoutMs?: number;
+	endpointClass?: "canonical" | "custom";
+	retryMaxAttempts?: number;
+}
+
 export class FirstEventTimeoutError extends Error {
 	readonly providerCode = STREAM_FIRST_EVENT_TIMEOUT_PROVIDER_CODE;
+	readonly requestBytes?: number;
+	readonly firstEventElapsedMs?: number;
+	readonly firstEventTimeoutMs?: number;
+	readonly endpointClass?: "canonical" | "custom";
+	readonly retryMaxAttempts?: number;
 
-	constructor(message: string) {
+	constructor(message: string, facts: FirstEventTimeoutFacts = {}) {
 		super(message);
 		this.name = "FirstEventTimeoutError";
+		this.requestBytes = facts.requestBytes;
+		this.firstEventElapsedMs = facts.firstEventElapsedMs;
+		this.firstEventTimeoutMs = facts.firstEventTimeoutMs;
+		this.endpointClass = facts.endpointClass;
+		this.retryMaxAttempts = facts.retryMaxAttempts;
 	}
 }
 
@@ -202,6 +220,8 @@ export async function* iterateWithIdleTimeout<T>(
 		}
 	};
 	let lastProgressAt = Date.now();
+	const firstItemDeadlineAt =
+		firstItemTimeoutMs !== undefined && firstItemTimeoutMs > 0 ? Date.now() + firstItemTimeoutMs : undefined;
 
 	const noTimeoutEnforced =
 		(firstItemTimeoutMs === undefined || firstItemTimeoutMs <= 0) &&
@@ -210,7 +230,8 @@ export async function* iterateWithIdleTimeout<T>(
 	while (true) {
 		let activeTimeoutMs: number | undefined;
 		if (awaitingFirstItem) {
-			activeTimeoutMs = firstItemTimeoutMs;
+			activeTimeoutMs =
+				firstItemDeadlineAt === undefined ? undefined : Math.max(0, firstItemDeadlineAt - Date.now());
 		} else if (options.idleTimeoutMs !== undefined && options.idleTimeoutMs > 0) {
 			activeTimeoutMs = options.idleTimeoutMs - (Date.now() - lastProgressAt);
 			// The idle deadline may already have elapsed because the *consumer*
@@ -235,10 +256,7 @@ export async function* iterateWithIdleTimeout<T>(
 
 		let timer: NodeJS.Timeout | undefined;
 		let resolveTimeout: ((value: { kind: "timeout" }) => void) | undefined;
-		const enforceTimeout =
-			!noTimeoutEnforced &&
-			activeTimeoutMs !== undefined &&
-			(awaitingFirstItem ? activeTimeoutMs > 0 : activeTimeoutMs >= 0);
+		const enforceTimeout = !noTimeoutEnforced && activeTimeoutMs !== undefined && activeTimeoutMs >= 0;
 		if (enforceTimeout) {
 			const { promise, resolve } = Promise.withResolvers<{ kind: "timeout" }>();
 			resolveTimeout = resolve;
@@ -283,6 +301,11 @@ export async function* iterateWithIdleTimeout<T>(
 			if (outcome.kind === "error") {
 				throw outcome.error;
 			}
+			if (awaitingFirstItem && firstItemDeadlineAt !== undefined && Date.now() >= firstItemDeadlineAt) {
+				options.onFirstItemTimeout?.();
+				closeIterator();
+				throw new FirstEventTimeoutError(options.firstItemErrorMessage ?? options.errorMessage);
+			}
 			if (outcome.result.done) {
 				markFirstItemReceived();
 				return;