@gajae-code/ai 0.12.11 → 0.12.13

package/src/providers/anthropic.ts

@@ -395,8 +395,20 @@ export function isAnthropicFastModeUnsupportedError(error: unknown): boolean {
 	return false;
 }
 
+/**
+ * Proxies (e.g. CLIProxyAPI) can deliver Anthropic's 400 body as an in-stream
+ * SSE `error` event on an HTTP 200 response; the thrown error then carries no
+ * HTTP status at all (issue #3900). Accept both the direct 400 and the
+ * statusless SSE shape — the strict `invalid_request_error` message checks in
+ * each matcher keep the statusless branch from claiming unrelated failures.
+ */
+function isAnthropicInvalidRequestStatus(error: unknown): boolean {
+	const status = extractHttpStatusFromError(error);
+	return status === 400 || status === undefined;
+}
+
 export function isAnthropicThinkingBlockMutationError(error: unknown): boolean {
-	if (extractHttpStatusFromError(error) !== 400) return false;
+	if (!isAnthropicInvalidRequestStatus(error)) return false;
 	const message = error instanceof Error ? error.message : String(error);
 	return (
 		/invalid_request_error/i.test(message) &&
@@ -414,7 +426,7 @@ export function isAnthropicThinkingBlockMutationError(error: unknown): boolean {
  * than only the latest one.
  */
 export function isAnthropicThinkingSignatureInvalidError(error: unknown): boolean {
-	if (extractHttpStatusFromError(error) !== 400) return false;
+	if (!isAnthropicInvalidRequestStatus(error)) return false;
 	const message = error instanceof Error ? error.message : String(error);
 	return (
 		/invalid_request_error/i.test(message) &&
@@ -423,6 +435,27 @@ export function isAnthropicThinkingSignatureInvalidError(error: unknown): boolea
 	);
 }
 
+/**
+ * CLIProxyAPI replaces Anthropic's rejection body wholesale instead of forwarding
+ * it: the client only ever sees
+ * `{"type":"error","error":{"type":"api_error","message":"An error occurred while
+ * processing the request."}}`, delivered as an in-stream SSE `error` event on an
+ * HTTP 200 response, so neither the status nor the message survives. Captured CPA
+ * traces for that masked shape carry the thinking-integrity 400 upstream (issue
+ * #3900), and the generic body matches no transient phrase either, so the turn
+ * dies unrecoverably. Nothing in the payload names the cause; callers must pair
+ * this with a request that actually replays signed thinking blocks before
+ * treating it as a thinking-replay rejection.
+ */
+export function isAnthropicMaskedProxyRejection(error: unknown): boolean {
+	const status = extractHttpStatusFromError(error);
+	if (status !== undefined && status !== 400) return false;
+	const message = error instanceof Error ? error.message : String(error);
+	// A body that still names its error type is classified by the strict matchers.
+	if (/invalid_request_error/i.test(message)) return false;
+	return /"type"\s*:\s*"api_error"/.test(message) && /an error occurred while processing/i.test(message);
+}
+
 function hasStrictAnthropicTools(params: MessageCreateParamsStreaming): boolean {
 	const tools = params.tools as Array<{ strict?: unknown }> | undefined;
 	return tools?.some(tool => tool.strict === true) ?? false;
@@ -447,12 +480,21 @@ function dropAnthropicStrictTools(params: MessageCreateParamsStreaming): void {
 	}
 }
 
+function isClaudeFamilyModel(model: Model<"anthropic-messages">): boolean {
+	// Classify the same identifier the request body serializes (`params.model =
+	// model.id` in buildParams); a differing `wireModelId` is not dispatched by
+	// this transport, so it must not drive the cache decision either.
+	const id = model.id;
+	const shortId = id.includes("/") ? id.slice(id.lastIndexOf("/") + 1) : id;
+	return shortId.toLowerCase().startsWith("claude-");
+}
+
 function getCacheControl(
 	model: Model<"anthropic-messages">,
 	baseUrl: string,
 	cacheRetention?: CacheRetention,
 ): { mode: AnthropicCacheMode; cacheControl?: AnthropicCacheControl } {
-	const retention = resolveCacheRetention(cacheRetention, "long");
+	const retention = resolveCacheRetention(cacheRetention ?? model.cacheRetention, "long");
 	if (retention === "none") return { mode: "none" };
 
 	const isCanonicalApi = isAnthropicApiBaseUrl(baseUrl);
@@ -462,7 +504,7 @@ function getCacheControl(
 			? "none"
 			: promptCacheMode === "explicit"
 				? "explicit"
-				: isCanonicalApi
+				: promptCacheMode === "automatic" || isCanonicalApi || isClaudeFamilyModel(model)
 					? "automatic"
 					: "none";
 	if (mode === "none") return { mode };
@@ -1847,7 +1889,12 @@ export const streamAnthropic: StreamFunction<"anthropic-messages"> = (
 						!options?.fallbackManaged &&
 						!repairAllAssistantThinking &&
 						firstTokenTime === undefined &&
-						(thinkingSignatureInvalid || isAnthropicThinkingBlockMutationError(streamFailure))
+						(thinkingSignatureInvalid ||
+							isAnthropicThinkingBlockMutationError(streamFailure) ||
+							// Masked proxy rejection: unclassifiable on its own, so the replayed
+							// request shape is the evidence. Without signed thinking blocks in
+							// flight there is nothing to repair and the error must surface.
+							(isAnthropicMaskedProxyRejection(streamFailure) && hasNativeThinkingBlocks(params.messages)))
 					) {
 						// The mutation 400 blames the "latest assistant message", but its cited
 						// `messages.N.content.M` path can point at an EARLIER replayed turn, so the
@@ -2285,10 +2332,11 @@ function applyExplicitPromptCaching(params: AnthropicCacheParams, cacheControl:
 	const currentUser = params.messages[currentUserIndex];
 	if (!currentUser) return;
 
-	// A tool result is encoded as role "user" on the wire, but belongs to the
-	// preceding assistant turn. Anchor that assistant turn, not the tool result,
-	// so changing tool output does not invalidate the reusable conversation prefix.
-	for (let index = currentUserIndex - 1; index >= 0; index--) {
+	// Tool results are encoded as role "user" on the wire but belong to the
+	// assistant tool-use turn immediately before them. Anchor the latest completed
+	// assistant turn so the reusable prefix advances during an agent tool loop,
+	// while keeping the newest tool output outside the cache boundary.
+	for (let index = params.messages.length - 1; index >= 0; index--) {
 		const message = params.messages[index];
 		if (message?.role !== "assistant" || !Array.isArray(message.content)) continue;
 		if (

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

@@ -1,5 +1,5 @@
 import { $credentialEnv, $env, extractHttpStatusFromError, logger } from "@gajae-code/utils";
-import { AzureOpenAI } from "openai";
+import { APIConnectionTimeoutError, AzureOpenAI } from "openai";
 import type {
 	Tool as OpenAITool,
 	ResponseCreateParamsStreaming,
@@ -22,9 +22,11 @@ import { AssistantMessageEventStream } from "../utils/event-stream";
 import { transportFailureFacts } from "../utils/fallback-transport";
 import { finalizeErrorMessage, type RawHttpRequestDump } from "../utils/http-inspector";
 import {
+	FirstEventTimeoutError,
 	getOpenAIStreamIdleTimeoutMs,
 	getStreamFirstEventTimeoutMs,
 	iterateWithIdleTimeout,
+	resolveOpenAISdkRequestTimeoutMs,
 } from "../utils/idle-iterator";
 import { resolveRetryBudget } from "../utils/retry-budget";
 import { flattenToolRootCombinators, sanitizeSchemaForOpenAIResponses, toolWireSchema } from "../utils/schema";
@@ -44,6 +46,7 @@ import {
 	convertResponsesAssistantMessage,
 	convertResponsesInputContent,
 	createInitialResponsesAssistantMessage,
+	isOpenAIResponsesProgressEvent,
 	normalizeResponsesToolCallIdForTransform,
 	processResponsesStream,
 } from "./openai-responses-shared";
@@ -108,6 +111,7 @@ export const streamAzureOpenAIResponses: StreamFunction<"azure-openai-responses"
 	(async () => {
 		const startTime = Date.now();
 		let firstTokenTime: number | undefined;
+		let streamConnected = false;
 		const deploymentName = resolveDeploymentName(model, options);
 
 		const output: AssistantMessage = createInitialResponsesAssistantMessage(
@@ -162,6 +166,7 @@ export const streamAzureOpenAIResponses: StreamFunction<"azure-openai-responses"
 				rawRequestDump = { ...rawRequestDump, body: params };
 				openaiStream = await client.responses.create(params, { signal: requestSignal });
 			}
+			streamConnected = true;
 			const firstEventTimeoutMs = options?.streamFirstEventTimeoutMs ?? getStreamFirstEventTimeoutMs(idleTimeoutMs);
 			stream.push({ type: "start", partial: output });
 
@@ -173,6 +178,8 @@ export const streamAzureOpenAIResponses: StreamFunction<"azure-openai-responses"
 					errorMessage: "Azure OpenAI responses stream stalled while waiting for the next event",
 					onIdle: () => requestAbortController.abort(),
 					onFirstItemTimeout: () => requestAbortController.abort(),
+					isProgressItem: isOpenAIResponsesProgressEvent,
+					abortSignal: options?.signal,
 				}),
 				output,
 				stream,
@@ -203,10 +210,15 @@ export const streamAzureOpenAIResponses: StreamFunction<"azure-openai-responses"
 		} catch (error) {
 			for (const block of output.content) delete (block as { index?: number }).index;
 			const firstEventTimeoutError = abortTracker.getLocalAbortReason();
+			const normalizedError =
+				!streamConnected && error instanceof APIConnectionTimeoutError
+					? new FirstEventTimeoutError(AZURE_OPENAI_RESPONSES_FIRST_EVENT_TIMEOUT_MESSAGE)
+					: error;
 			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(firstEventTimeoutError ?? normalizedError);
+			output.transportFailure = transportFailureFacts(firstEventTimeoutError ?? normalizedError);
+			output.errorMessage =
+				firstEventTimeoutError?.message ?? (await finalizeErrorMessage(normalizedError, rawRequestDump));
 			output.duration = Date.now() - startTime;
 			if (firstTokenTime) output.ttft = firstTokenTime - startTime;
 			stream.push({ type: "error", reason: output.stopReason, error: output });
@@ -305,6 +317,9 @@ function createClient(model: Model<"azure-openai-responses">, apiKey: string, op
 
 	const baseFetch = wrapOpenAIFetchForBoundedRateLimits(options?.fetch ?? fetch, options?.maxRetryDelayMs);
 	const onSseEvent = options?.onSseEvent;
+	// Bound HTTP request timeout to the first-event window so a stalled-before-headers
+	// fetch cannot wait the SDK's 10-minute default before the transport watchdog arms.
+	const sdkTimeoutMs = resolveOpenAISdkRequestTimeoutMs(model.provider, options?.streamFirstEventTimeoutMs);
 	return new AzureOpenAI({
 		apiKey,
 		apiVersion,
@@ -315,6 +330,7 @@ function createClient(model: Model<"azure-openai-responses">, apiKey: string, op
 		fetch: onSseEvent
 			? wrapFetchForSseDebug(baseFetch, event => onSseEvent(event, model, options?.attemptScope))
 			: baseFetch,
+		...(sdkTimeoutMs !== undefined ? { timeout: sdkTimeoutMs } : {}),
 	});
 }
 

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

@@ -66,6 +66,7 @@ import {
 	toolWireSchema,
 } from "../utils/schema";
 import {
+	isCodexStatuslessNamedToolChoiceNotFoundError,
 	isForcedToolChoiceUnsupportedError,
 	markToolChoiceIncapability,
 	resolveToolChoice,
@@ -247,9 +248,7 @@ async function retryCodexInitialTransportWithoutToolChoice(
 	requestBodyForState: RequestBody;
 	transport: CodexTransport;
 }> {
-	if (
-		!isForcedToolChoiceUnsupportedError(error, isForcedCodexToolChoice(requestContext.transformedBody.tool_choice))
-	) {
+	if (!isCodexForcedToolChoiceUnsupportedError(error, requestContext.transformedBody)) {
 		throw error;
 	}
 	const reason = await finalizeErrorMessage(error, requestContext.rawRequestDump);
@@ -555,10 +554,12 @@ function getCodexServiceTierCostMultiplier(
 
 function resolveCodexCostServiceTier(res: unknown, req?: unknown): ServiceTier | "default" | undefined {
 	switch (res) {
+		case "auto":
+		case "default":
 		case "flex":
-			return "flex";
+		case "scale":
 		case "priority":
-			return "priority";
+			return res;
 		default:
 			if (req === "flex" || req === "priority") {
 				return req;
@@ -1525,7 +1526,7 @@ async function tryRetryWithoutForcedToolChoice(
 		context.output.content.length > 0 ||
 		context.firstTokenTime !== undefined ||
 		context.options?.signal?.aborted ||
-		!isForcedToolChoiceUnsupportedError(error, isForcedCodexToolChoice(runtime.requestBodyForState.tool_choice))
+		!isCodexForcedToolChoiceUnsupportedError(error, runtime.requestBodyForState)
 	) {
 		return false;
 	}
@@ -1577,6 +1578,30 @@ async function tryRetryWithoutForcedToolChoice(
 function isForcedCodexToolChoice(choice: RequestBody["tool_choice"]): boolean {
 	return !!choice && choice !== "none" && choice !== "auto";
 }
+function isCodexForcedToolChoiceUnsupportedError(error: unknown, body: RequestBody): boolean {
+	if (isForcedToolChoiceUnsupportedError(error, isForcedCodexToolChoice(body.tool_choice))) {
+		return true;
+	}
+	return isCodexStatuslessNamedToolChoiceNotFoundError(
+		error,
+		codexNamedFunctionToolChoiceName(body.tool_choice),
+		codexSerializedToolNames(body.tools),
+	);
+}
+
+function codexNamedFunctionToolChoiceName(choice: RequestBody["tool_choice"]): string | undefined {
+	if (!choice || typeof choice !== "object") return undefined;
+	const namedChoice = choice as { type?: unknown; name?: unknown };
+	return namedChoice.type === "function" && typeof namedChoice.name === "string" ? namedChoice.name : undefined;
+}
+
+function codexSerializedToolNames(tools: RequestBody["tools"]): string[] {
+	if (!Array.isArray(tools)) return [];
+	return tools.flatMap(tool => {
+		const name = (tool as { name?: unknown }).name;
+		return typeof name === "string" ? [name] : [];
+	});
+}
 
 /**
  * Handles `websocket_connection_limit_reached` errors by closing the stale connection

package/src/providers/openai-completions.ts

@@ -52,6 +52,7 @@ import {
 	getProviderFirstEventTimeoutFallbackMs,
 	getStreamFirstEventTimeoutMs,
 	iterateWithIdleTimeout,
+	resolveOpenAISdkRequestTimeoutMs,
 } from "../utils/idle-iterator";
 import { isCompleteJson, parseStreamingJson } from "../utils/json-parse";
 import { parseGitHubCopilotApiKey } from "../utils/oauth/github-copilot";
@@ -524,7 +525,7 @@ export const streamOpenAICompletions: StreamFunction<"openai-completions"> = (
 
 		try {
 			const apiKey = options?.apiKey || getEnvApiKey(model.provider) || "";
-			const idleTimeoutMs = getOpenAIStreamIdleTimeoutMs();
+			const idleTimeoutMs = options?.streamIdleTimeoutMs ?? getOpenAIStreamIdleTimeoutMs();
 			const {
 				client,
 				copilotPremiumRequests,
@@ -1233,26 +1234,7 @@ async function createClient(
 	// The OpenAI SDK's default is 10 minutes per attempt × `maxRetries`, which
 	// turns a stalled-before-headers fetch into a multi-minute hang invisible
 	// to the agent loop (the iterator watchdog only arms AFTER `create()` returns).
-	// Using the first-event timeout keeps both layers aligned: the SDK gives up
-	// before the agent watchdog would have, surfacing a real error to the catch
-	// in the IIFE.
-	// A caller may raise `StreamOptions.streamFirstEventTimeoutMs` for a slow-
-	// before-headers provider; respect it so the SDK doesn't give up before the
-	// wrapping watchdog arms. Provider-specific fallbacks apply only when the
-	// caller does not pin a value, so an explicit nonzero override must beat that
-	// fallback even when it is shorter. An explicit `0` disables the watchdog,
-	// and the SDK treats `timeout: 0` as an immediate timeout, so do not pass a
-	// request timeout in that case.
-	const providerFirstEventFallbackMs = getProviderFirstEventTimeoutFallbackMs(model.provider);
-	const envSdkTimeoutMs = getStreamFirstEventTimeoutMs(getOpenAIStreamIdleTimeoutMs(), providerFirstEventFallbackMs);
-	const sdkTimeoutMs =
-		streamFirstEventTimeoutOverride === 0
-			? undefined
-			: streamFirstEventTimeoutOverride !== undefined
-				? providerFirstEventFallbackMs !== undefined
-					? streamFirstEventTimeoutOverride
-					: Math.max(envSdkTimeoutMs ?? 0, streamFirstEventTimeoutOverride)
-				: envSdkTimeoutMs;
+	const sdkTimeoutMs = resolveOpenAISdkRequestTimeoutMs(model.provider, streamFirstEventTimeoutOverride);
 	return {
 		client: new OpenAI({
 			apiKey,

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

@@ -33,6 +33,32 @@ import type { AssistantMessageEventStream } from "../utils/event-stream";
 import { isCompleteJson, parseStreamingJson } from "../utils/json-parse";
 import { joinTextWithImagePlaceholder, NON_VISION_IMAGE_PLACEHOLDER, partitionVisionContent } from "./vision-guard";
 
+const OPENAI_RESPONSES_PROGRESS_EVENT_TYPES = new Set([
+	"response.created",
+	"response.output_item.added",
+	"response.reasoning_summary_part.added",
+	"response.reasoning_summary_text.delta",
+	"response.reasoning_summary_part.done",
+	"response.reasoning_text.delta",
+	"response.content_part.added",
+	"response.output_text.delta",
+	"response.refusal.delta",
+	"response.function_call_arguments.delta",
+	"response.function_call_arguments.done",
+	"response.custom_tool_call_input.delta",
+	"response.custom_tool_call_input.done",
+	"response.output_item.done",
+	"response.completed",
+	"response.failed",
+	"error",
+]);
+
+export function isOpenAIResponsesProgressEvent(event: unknown): boolean {
+	if (!event || typeof event !== "object") return false;
+	const type = (event as { type?: unknown }).type;
+	return typeof type === "string" && OPENAI_RESPONSES_PROGRESS_EVENT_TYPES.has(type);
+}
+
 export function encodeTextSignatureV1(id: string, phase?: TextSignatureV1["phase"]): string {
 	const payload: TextSignatureV1 = { v: 1, id };
 	if (phase) payload.phase = phase;

package/src/providers/openai-responses.ts

@@ -43,6 +43,7 @@ import {
 	getProviderFirstEventTimeoutFallbackMs,
 	getStreamFirstEventTimeoutMs,
 	iterateWithIdleTimeout,
+	resolveOpenAISdkRequestTimeoutMs,
 } from "../utils/idle-iterator";
 import { parseGitHubCopilotApiKey } from "../utils/oauth/github-copilot";
 import { notifyProviderResponse } from "../utils/provider-response";
@@ -85,6 +86,7 @@ import {
 	convertResponsesAssistantMessage,
 	convertResponsesInputContent,
 	createInitialResponsesAssistantMessage,
+	isOpenAIResponsesProgressEvent,
 	normalizeResponsesToolCallIdForTransform,
 	processResponsesStream,
 	repairOrphanResponsesToolOutputs,
@@ -229,32 +231,6 @@ function appendQueryToRequest(input: string | URL | Request, query?: OpenAIRespo
 	return url;
 }
 
-const OPENAI_RESPONSES_PROGRESS_EVENT_TYPES = new Set([
-	"response.created",
-	"response.output_item.added",
-	"response.reasoning_summary_part.added",
-	"response.reasoning_summary_text.delta",
-	"response.reasoning_summary_part.done",
-	"response.reasoning_text.delta",
-	"response.content_part.added",
-	"response.output_text.delta",
-	"response.refusal.delta",
-	"response.function_call_arguments.delta",
-	"response.function_call_arguments.done",
-	"response.custom_tool_call_input.delta",
-	"response.custom_tool_call_input.done",
-	"response.output_item.done",
-	"response.completed",
-	"response.failed",
-	"error",
-]);
-
-function isOpenAIResponsesProgressEvent(event: unknown): boolean {
-	if (!event || typeof event !== "object") return false;
-	const type = (event as { type?: unknown }).type;
-	return typeof type === "string" && OPENAI_RESPONSES_PROGRESS_EVENT_TYPES.has(type);
-}
-
 interface OpenAIResponsesProviderSessionState extends ProviderSessionState {
 	nativeHistoryReplayWarmed: boolean;
 }
@@ -343,6 +319,7 @@ export const streamOpenAIResponses: StreamFunction<"openai-responses"> = (
 				options?.requestMaxRetries,
 				options?.maxRetryDelayMs,
 				options?.attemptScope,
+				options?.streamFirstEventTimeoutMs,
 			);
 			const premiumRequestsTotal = copilotPremiumRequests;
 			const providerSessionState = getOpenAIResponsesProviderSessionState(model, options?.providerSessionState);
@@ -498,6 +475,7 @@ function createClient(
 	requestMaxRetries?: number,
 	maxRetryDelayMs?: number,
 	attemptScope?: import("../types.js").AttemptScopeRef,
+	streamFirstEventTimeoutOverride?: number,
 ): {
 	client: OpenAI;
 	copilotPremiumRequests: number | undefined;
@@ -568,6 +546,9 @@ function createClient(
 		model.requestTransform,
 		`Gajae-Code/${packageJson.version}`,
 	);
+	// Bound HTTP request timeout to the first-event window so a stalled-before-headers
+	// fetch cannot wait the SDK's 10-minute default before the transport watchdog arms.
+	const sdkTimeoutMs = resolveOpenAISdkRequestTimeoutMs(model.provider, streamFirstEventTimeoutOverride);
 	return {
 		client: new OpenAI({
 			apiKey,
@@ -578,6 +559,7 @@ function createClient(
 			fetch: onSseEvent
 				? wrapFetchForSseDebug(transformedFetch, event => onSseEvent(event, model, attemptScope))
 				: transformedFetch,
+			...(sdkTimeoutMs !== undefined ? { timeout: sdkTimeoutMs } : {}),
 		}),
 		copilotPremiumRequests,
 		baseUrl,

package/src/providers/register-builtins.ts

@@ -167,6 +167,7 @@ export function setBedrockProviderModule(module: BedrockProviderModule): void {
 
 const LAZY_STREAM_IDLE_TIMEOUT_ERROR = "Provider stream stalled while waiting for the next event";
 const LAZY_STREAM_FIRST_EVENT_TIMEOUT_ERROR = "Provider stream timed out while waiting for the first event";
+const LAZY_STREAM_NON_PROGRESS_EVENT_TYPES = new Set(["start", "toolChoiceIncapability"]);
 
 function hasFinalResult(
 	source: AsyncIterable<AssistantMessageEvent>,
@@ -184,8 +185,14 @@ function hasFinalResult(
 interface LazyStreamLimits {
 	defaultFirstEventTimeoutMs?: number;
 	defaultIdleTimeoutMs?: number;
+	/** The provider already watches raw transport events, which this normalized wrapper cannot observe. */
+	providerOwnsWatchdog?: boolean;
 }
 
+const PROVIDER_OWNED_STREAM_WATCHDOG: LazyStreamLimits = {
+	providerOwnsWatchdog: true,
+};
+
 /**
  * Cloud Code Assist (google-gemini-cli / google-antigravity) routinely takes
  * longer than the global 100s default to emit its first SSE event when serving
@@ -224,28 +231,34 @@ function forwardStream<TApi extends Api>(
 ): void {
 	(async () => {
 		try {
-			const idleTimeoutMs = options.streamIdleTimeoutMs ?? getStreamIdleTimeoutMs(limits?.defaultIdleTimeoutMs);
-			const firstEventFallbackMs = resolveLazyStreamFirstEventFallbackMs(
-				model.provider,
-				limits?.defaultFirstEventTimeoutMs,
-			);
-			const watchedSource = iterateWithIdleTimeout(source, {
-				idleTimeoutMs,
-				firstItemTimeoutMs:
-					options.streamFirstEventTimeoutMs ?? getStreamFirstEventTimeoutMs(idleTimeoutMs, firstEventFallbackMs),
-				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)),
-				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"
-				// item would flip the watchdog from `firstItemTimeoutMs` to the much shorter
-				// `idleTimeoutMs` while we're still legitimately waiting on the model's
-				// first response (slow first-token from reasoning models, cold proxies, etc.).
-				isProgressItem: event => (event as AssistantMessageEvent).type !== "start",
-			});
+			let watchedSource = source;
+			if (!limits?.providerOwnsWatchdog) {
+				const idleTimeoutMs = options.streamIdleTimeoutMs ?? getStreamIdleTimeoutMs(limits?.defaultIdleTimeoutMs);
+				const firstEventFallbackMs = resolveLazyStreamFirstEventFallbackMs(
+					model.provider,
+					limits?.defaultFirstEventTimeoutMs,
+				);
+				watchedSource = iterateWithIdleTimeout(source, {
+					idleTimeoutMs,
+					firstItemTimeoutMs:
+						options.streamFirstEventTimeoutMs ??
+						getStreamFirstEventTimeoutMs(idleTimeoutMs, firstEventFallbackMs),
+					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)),
+					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
+					// arrives instead of switching early to the shorter idle timeout.
+					isProgressItem: event => {
+						if (!event || typeof event !== "object") return true;
+						const eventType = (event as { type?: unknown }).type;
+						return typeof eventType !== "string" || !LAZY_STREAM_NON_PROGRESS_EVENT_TYPES.has(eventType);
+					},
+				});
+			}
 
 			for await (const event of watchedSource) {
 				target.push(event);
@@ -423,17 +436,29 @@ function loadBedrockProviderModule(): Promise<LazyProviderModule<"bedrock-conver
 // are loaded on first use instead of during package initialization.
 // ---------------------------------------------------------------------------
 
-export const streamAnthropic = createLazyStream(loadAnthropicProviderModule);
-export const streamAzureOpenAIResponses = createLazyStream(loadAzureOpenAIResponsesProviderModule);
+export const streamAnthropic = createLazyStream(loadAnthropicProviderModule, PROVIDER_OWNED_STREAM_WATCHDOG);
+export const streamAzureOpenAIResponses = createLazyStream(
+	loadAzureOpenAIResponsesProviderModule,
+	PROVIDER_OWNED_STREAM_WATCHDOG,
+);
 export const streamGoogle = createLazyStream(loadGoogleProviderModule);
 export const streamGoogleGeminiCli = createLazyStream(
 	loadGoogleGeminiCliProviderModule,
 	GOOGLE_GEMINI_CLI_LAZY_STREAM_LIMITS,
 );
 export const streamGoogleVertex = createLazyStream(loadGoogleVertexProviderModule);
-export const streamOpenAICodexResponses = createLazyStream(loadOpenAICodexResponsesProviderModule);
-export const streamOpenAICompletions = createLazyStream(loadOpenAICompletionsProviderModule);
-export const streamOpenAIResponses = createLazyStream(loadOpenAIResponsesProviderModule);
+export const streamOpenAICodexResponses = createLazyStream(
+	loadOpenAICodexResponsesProviderModule,
+	PROVIDER_OWNED_STREAM_WATCHDOG,
+);
+export const streamOpenAICompletions = createLazyStream(
+	loadOpenAICompletionsProviderModule,
+	PROVIDER_OWNED_STREAM_WATCHDOG,
+);
+export const streamOpenAIResponses = createLazyStream(
+	loadOpenAIResponsesProviderModule,
+	PROVIDER_OWNED_STREAM_WATCHDOG,
+);
 export const streamCursor = createLazyStream(loadCursorProviderModule);
 export const streamOllama = createLazyStream(loadOllamaProviderModule);
 

package/src/types.ts

@@ -743,7 +743,11 @@ export type Static<S> = S extends ZodType ? z.infer<S> : S extends { static: inf
 export type RawArgumentRejectionCode =
 	| "ask-intent-review-requires-positive-round"
 	| "ask-intent-contract-requires-non-empty-authority"
-	| "ask-deep-interview-metadata-requires-deep-interview-gate";
+	| "ask-deep-interview-metadata-requires-deep-interview-gate"
+	| "todo-write-unknown-root-key"
+	| "todo-write-unknown-op-entry-key"
+	| "todo-write-done-drop-requires-target"
+	| "todo-write-unknown-init-entry-key";
 
 export type RawArgumentValidationResult =
 	| { outcome: "passthrough" }
@@ -947,8 +951,10 @@ export interface AnthropicCompat extends ToolChoiceCompat {
 	supportsLongCacheRetention?: boolean;
 	/**
 	 * Prompt-cache transport accepted by this Anthropic-compatible endpoint.
-	 * Canonical Anthropic defaults to `"automatic"`; noncanonical endpoints default
-	 * to `"none"` and must explicitly opt into generated `"explicit"` markers.
+	 * Canonical Anthropic and Claude-family models default to `"automatic"`;
+	 * noncanonical non-Claude endpoints default to `"none"`. Set `"automatic"` to
+	 * opt an otherwise unknown compatible endpoint into top-level caching, `"none"`
+	 * to opt out, or `"explicit"` for endpoints that require block-level markers.
 	 */
 	promptCacheMode?: "none" | "explicit" | "automatic";
 }

package/src/utils/idle-iterator.ts

@@ -68,6 +68,37 @@ export function getStreamFirstEventTimeoutMs(
 	return normalizeIdleTimeoutMs($env.PI_STREAM_FIRST_EVENT_TIMEOUT_MS, fallback);
 }
 
+/**
+ * Resolves the OpenAI SDK client `timeout` so stalled-before-headers requests are
+ * bounded by the same first-event window the transport watchdog uses after
+ * `create()` returns. Without this, providers that only arm
+ * `iterateWithIdleTimeout` post-setup can wait the full SDK default (10 minutes
+ * per attempt) before any provider-owned watchdog exists.
+ *
+ * - Explicit `0` disables the request timeout (the SDK treats `timeout: 0` as an
+ *   immediate failure, so callers that disable the first-event watchdog must not
+ *   pass a timeout).
+ * - Providers with a first-event fallback (Alibaba, Kimi) honor an explicit
+ *   nonzero override as-is, even when shorter than the fallback.
+ * - Other providers floor an explicit override at the env/default first-event
+ *   window so a short post-connect first-event budget cannot kill legitimate
+ *   slow setup.
+ */
+export function resolveOpenAISdkRequestTimeoutMs(
+	provider: string,
+	streamFirstEventTimeoutOverride?: number,
+): number | undefined {
+	const providerFirstEventFallbackMs = getProviderFirstEventTimeoutFallbackMs(provider);
+	const envSdkTimeoutMs = getStreamFirstEventTimeoutMs(getOpenAIStreamIdleTimeoutMs(), providerFirstEventFallbackMs);
+	if (streamFirstEventTimeoutOverride === 0) return undefined;
+	if (streamFirstEventTimeoutOverride !== undefined) {
+		return providerFirstEventFallbackMs !== undefined
+			? streamFirstEventTimeoutOverride
+			: Math.max(envSdkTimeoutMs ?? 0, streamFirstEventTimeoutOverride);
+	}
+	return envSdkTimeoutMs;
+}
+
 export type Watchdog = NodeJS.Timeout | undefined;
 export class FirstEventTimeoutError extends Error {
 	readonly providerCode = STREAM_FIRST_EVENT_TIMEOUT_PROVIDER_CODE;