@sayknow-cli/ai 0.3.16 → 0.4.1

package/src/utils/event-stream.ts

@@ -1,10 +1,32 @@
 import type { AssistantMessage, AssistantMessageEvent } from "../types";
 
+interface EventQueueNode<T> {
+	type: "event";
+	event: T;
+}
+
+type QueueNode<T> = EventQueueNode<T> | { type: "consumer-drain"; drain: ConsumerDrain };
+
+interface ConsumerDrain {
+	settled: boolean;
+	signal: AbortSignal;
+	abortListener: () => void;
+	resolve: () => void;
+	reject: (reason: unknown) => void;
+}
+
+function abortReason(signal: AbortSignal): unknown {
+	return signal.reason ?? new DOMException("The operation was aborted.", "AbortError");
+}
+
 // Generic event stream class for async iteration
+
 export class EventStream<T, R = T> implements AsyncIterable<T> {
-	#queue: T[] = [];
+	#queue: QueueNode<T>[] = [];
 	#queueHead = 0;
 	waiting: Array<{ resolve: (value: IteratorResult<T>) => void; reject: (err: unknown) => void }> = [];
+	#pendingConsumerDrains = new Set<ConsumerDrain>();
+	#activeConsumerCount = 0;
 	done = false;
 	#failed = false;
 	#error: unknown = undefined;
@@ -26,20 +48,20 @@ export class EventStream<T, R = T> implements AsyncIterable<T> {
 		this.extractResult = extractResult;
 	}
 
-	#enqueue(event: T): void {
-		this.#queue.push(event);
+	#enqueue(node: QueueNode<T>): void {
+		this.#queue.push(node);
 	}
 
-	#dequeue(): T | undefined {
+	#dequeue(): QueueNode<T> | undefined {
 		if (this.#queueHead >= this.#queue.length) return undefined;
-		const event = this.#queue[this.#queueHead]!;
-		this.#queue[this.#queueHead] = undefined as T;
+		const node = this.#queue[this.#queueHead]!;
+		this.#queue[this.#queueHead] = undefined as unknown as QueueNode<T>;
 		this.#queueHead++;
 		if (this.#queueHead > 1024 && this.#queueHead * 2 >= this.#queue.length) {
 			this.#queue = this.#queue.slice(this.#queueHead);
 			this.#queueHead = 0;
 		}
-		return event;
+		return node;
 	}
 
 	get #queueLength(): number {
@@ -49,40 +71,114 @@ export class EventStream<T, R = T> implements AsyncIterable<T> {
 	/**
 	 * Read-only snapshot of the not-yet-consumed events. Always a fresh copy:
 	 * external code can never mutate internal queue state or observe head-index
-	 * tombstones, so the deque cannot desynchronize.
+	 * tombstones or private consumer-drain sentinels, so the deque cannot desynchronize.
 	 */
 	get queue(): T[] {
-		return this.#queue.slice(this.#queueHead);
+		return this.#queue.slice(this.#queueHead).flatMap(node => (node.type === "event" ? [node.event] : []));
 	}
 
-	push(event: T): void {
-		if (this.done) return;
+	/** Read-only test seam for outstanding consumer-drain waiters. */
+	get pendingConsumerDrainCountForTests(): number {
+		return this.#pendingConsumerDrains.size;
+	}
 
-		if (this.isComplete(event)) {
-			this.done = true;
-			this.resolveFinalResult(this.extractResult(event));
+	#settleConsumerDrain(drain: ConsumerDrain, status: "resolve" | "reject", reason?: unknown): void {
+		if (drain.settled) return;
+		drain.settled = true;
+		this.#pendingConsumerDrains.delete(drain);
+		drain.signal.removeEventListener("abort", drain.abortListener);
+		if (status === "resolve") {
+			drain.resolve();
+		} else {
+			drain.reject(reason);
 		}
+	}
 
-		// Deliver to waiting consumer or queue it
-		const waiter = this.waiting.shift();
-		if (waiter) {
-			waiter.resolve({ value: event, done: false });
-		} else {
-			this.#enqueue(event);
+	#settleAllConsumerDrains(status: "resolve" | "reject", reason?: unknown): void {
+		for (const drain of this.#pendingConsumerDrains) {
+			this.#settleConsumerDrain(drain, status, reason);
 		}
 	}
 
+	#drainQueuedNodesToWaitingConsumers(): void {
+		while (this.waiting.length > 0 && this.#queueLength > 0) {
+			const node = this.#dequeue()!;
+			if (node.type === "consumer-drain") {
+				this.#settleConsumerDrain(node.drain, "resolve");
+
+				continue;
+			}
+			this.waiting.shift()!.resolve({ value: node.event, done: false });
+		}
+	}
+
+	#dequeueEvent(): EventQueueNode<T> | undefined {
+		while (this.#queueLength > 0) {
+			const node = this.#dequeue()!;
+			if (node.type === "event") return node;
+			this.#settleConsumerDrain(node.drain, "resolve");
+		}
+		return undefined;
+	}
+
+	push(event: T): void {
+		if (this.done) return;
+		try {
+			if (this.isComplete(event)) {
+				const result = this.extractResult(event);
+				this.done = true;
+				this.resolveFinalResult(result);
+			}
+		} catch (error) {
+			this.fail(error);
+			return;
+		}
+		this.deliver(event);
+	}
+
 	deliver(event: T): void {
-		const waiter = this.waiting.shift();
-		if (waiter) {
-			waiter.resolve({ value: event, done: false });
-		} else {
-			this.#enqueue(event);
+		if (this.#queueLength === 0) {
+			const waiter = this.waiting.shift();
+			if (waiter) {
+				waiter.resolve({ value: event, done: false });
+				return;
+			}
 		}
+		this.#enqueue({ type: "event", event });
+		this.#drainQueuedNodesToWaitingConsumers();
+	}
+
+	/**
+	 * Resolves after every event enqueued before this call has been yielded and
+	 * the consumer asks the iterator for its next node. The private sentinel is
+	 * never exposed through the async iterator.
+	 */
+	waitForConsumerDrain(signal: AbortSignal): Promise<void> {
+		if (signal.aborted) return Promise.reject(abortReason(signal));
+		if (this.#failed) return Promise.reject(this.#error);
+		if (this.done && this.#activeConsumerCount === 0) {
+			if (this.#queueLength === 0) return Promise.resolve();
+			return Promise.reject(new Error("Event stream ended before queued events could be drained"));
+		}
+
+		const { promise, resolve, reject } = Promise.withResolvers<void>();
+		let drain!: ConsumerDrain;
+		const abortListener = () => this.#settleConsumerDrain(drain, "reject", abortReason(signal));
+
+		drain = { settled: false, signal, abortListener, resolve, reject };
+		this.#pendingConsumerDrains.add(drain);
+		signal.addEventListener("abort", abortListener, { once: true });
+		this.#enqueue({ type: "consumer-drain", drain });
+		this.#drainQueuedNodesToWaitingConsumers();
+		return promise;
 	}
 
 	end(result?: R): void {
 		this.done = true;
+		if (this.#activeConsumerCount === 0) {
+			this.#settleAllConsumerDrains("reject", new Error("Event stream ended before consumer drain completed"));
+		}
+
 		if (result !== undefined) {
 			this.resolveFinalResult(result);
 		}
@@ -94,6 +190,9 @@ export class EventStream<T, R = T> implements AsyncIterable<T> {
 	}
 
 	endWaiting(): void {
+		if (this.#activeConsumerCount === 0) {
+			this.#settleAllConsumerDrains("reject", new Error("Event stream ended before consumer drain completed"));
+		}
 		while (this.waiting.length > 0) {
 			const waiter = this.waiting.shift()!;
 			waiter.resolve({ value: undefined as any, done: true });
@@ -105,6 +204,8 @@ export class EventStream<T, R = T> implements AsyncIterable<T> {
 		this.done = true;
 		this.#failed = true;
 		this.#error = err;
+		this.#settleAllConsumerDrains("reject", err);
+
 		this.rejectFinalResult(err);
 		while (this.waiting.length > 0) {
 			const waiter = this.waiting.shift()!;
@@ -113,20 +214,27 @@ export class EventStream<T, R = T> implements AsyncIterable<T> {
 	}
 
 	async *[Symbol.asyncIterator](): AsyncIterator<T> {
-		while (true) {
-			if (this.#queueLength > 0) {
-				yield this.#dequeue()!;
-			} else if (this.#failed) {
-				throw this.#error;
-			} else if (this.done) {
-				return;
-			} else {
-				const result = await new Promise<IteratorResult<T>>((resolve, reject) =>
-					this.waiting.push({ resolve, reject }),
-				);
-				if (result.done) return;
-				yield result.value;
+		this.#activeConsumerCount += 1;
+		try {
+			while (true) {
+				const node = this.#dequeueEvent();
+				if (node !== undefined) {
+					yield node.event;
+				} else if (this.#failed) {
+					throw this.#error;
+				} else if (this.done) {
+					return;
+				} else {
+					const result = await new Promise<IteratorResult<T>>((resolve, reject) =>
+						this.waiting.push({ resolve, reject }),
+					);
+					if (result.done) return;
+					yield result.value;
+				}
 			}
+		} finally {
+			this.#activeConsumerCount -= 1;
+			this.#settleAllConsumerDrains("reject", new Error("Event stream consumer stopped before drain completed"));
 		}
 	}
 
@@ -149,24 +257,4 @@ export class AssistantMessageEventStream extends EventStream<AssistantMessageEve
 			},
 		);
 	}
-
-	override push(event: AssistantMessageEvent): void {
-		if (this.done) return;
-
-		// Completion resolves the final result and still emits the terminal event.
-		if (this.isComplete(event)) {
-			this.done = true;
-			this.resolveFinalResult(this.extractResult(event));
-		}
-
-		this.deliver(event);
-	}
-
-	override end(result?: AssistantMessage): void {
-		this.done = true;
-		if (result !== undefined) {
-			this.resolveFinalResult(result);
-		}
-		this.endWaiting();
-	}
 }

package/src/utils/fallback-transport.ts

@@ -0,0 +1,269 @@
+export type FallbackTriggerClass = "rate_limit" | "quota" | "auth" | "server" | "unknown" | "other";
+
+export interface FallbackTrigger {
+	class: FallbackTriggerClass;
+	retryAfterMs?: number;
+}
+
+export type TransportHeaders = Headers | Record<string, string | undefined>;
+
+/**
+ * Structured facts from an upstream HTTP or transport failure. Retry decisions
+ * must use these facts rather than provider- or application-owned error text.
+ *
+ * `headers` is always a plain record limited to the retained retry-signal
+ * entries: facts travel on persisted `AssistantMessage`s and through
+ * `structuredClone` snapshots (managed fallback attempt staging), so they must
+ * never carry a live `Headers` instance — cloning one throws `DataCloneError`
+ * ("The object can not be cloned.") and masks the real provider failure.
+ */
+export interface TransportFailureFacts {
+	kind: "transport";
+	status?: number;
+	/** Canonical provider error code used for fallback classification. */
+	providerCode?: string;
+	/** Anthropic's typed `error.type`, preserved separately at the transport boundary. */
+	anthropicErrorType?: string;
+	/** OpenAI's typed `error.code`, preserved separately at the transport boundary. */
+	openaiErrorCode?: string;
+	headers?: Record<string, string>;
+}
+
+/** Opaque per-invocation marker required by managed fallback transport calls. */
+export interface FallbackAttemptToken {
+	readonly modelKey: string;
+	readonly attemptId: string | number;
+}
+
+const issuedAttemptTokens = new WeakSet<object>();
+const consumedAttemptTokens = new WeakSet<object>();
+
+/**
+ * Marks a single outer fallback invocation. Accounting belongs to the caller;
+ * this token prevents managed transport calls from silently bypassing it.
+ */
+export function beginAttempt(modelKey: string, attemptId: string | number): FallbackAttemptToken {
+	const token = Object.freeze({ modelKey, attemptId });
+	issuedAttemptTokens.add(token);
+	return token;
+}
+
+export function assertManagedAttempt(
+	options: { fallbackManaged?: boolean; fallbackAttempt?: FallbackAttemptToken } | undefined,
+): void {
+	if (!options?.fallbackManaged) return;
+	const token = options.fallbackAttempt;
+	if (!token || !issuedAttemptTokens.has(token)) {
+		throw new Error("fallbackManaged transport invocation requires a token returned by beginAttempt()");
+	}
+	if (consumedAttemptTokens.has(token)) {
+		throw new Error("fallbackManaged transport invocation cannot reuse a beginAttempt() token");
+	}
+	consumedAttemptTokens.add(token);
+}
+
+/**
+ * Compatibility input for callers that have not yet wrapped their HTTP facts
+ * in the discriminated form. Only its structured fields are inspected.
+ */
+export interface FallbackTriggerInput {
+	status?: number;
+	providerCode?: string;
+	code?: string;
+	headers?: TransportHeaders;
+	response?: { status?: number; headers?: TransportHeaders };
+	error?: { code?: string; type?: string };
+}
+
+function isTransportHeaders(value: unknown): value is TransportHeaders {
+	try {
+		return value instanceof Headers || (!!value && typeof value === "object");
+	} catch {
+		return false;
+	}
+}
+
+function propertyOf(value: unknown, name: string): unknown {
+	if (!value || typeof value !== "object") return undefined;
+	try {
+		return Reflect.get(value, name);
+	} catch {
+		return undefined;
+	}
+}
+
+function finiteStatus(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function stringValue(value: unknown): string | undefined {
+	return typeof value === "string" ? value : undefined;
+}
+
+/** Retry-signal headers retained on transport facts; everything else is dropped. */
+const RETAINED_TRANSPORT_HEADERS = ["retry-after", "retry-after-ms"] as const;
+
+const RETAINED_TRANSPORT_HEADER_SET: ReadonlySet<string> = new Set(RETAINED_TRANSPORT_HEADERS);
+
+/**
+ * Reduce transport headers to the retained retry-signal entries in a plain
+ * record, so facts stay structured-cloneable and JSON-serializable and never
+ * persist arbitrary response headers into session files.
+ *
+ * Exception-safe by contract: inspection uses only `Headers.get()` results
+ * that are primitive strings or own data-descriptor record entries. Any
+ * failure omits headers instead of throwing — status/providerCode facts
+ * extracted by the caller must survive a hostile headers object.
+ */
+function retainedHeaderRecord(headers: TransportHeaders | undefined): Record<string, string> | undefined {
+	if (headers === undefined) return undefined;
+	let record: Record<string, string> | undefined;
+	try {
+		if (headers instanceof Headers) {
+			for (const name of RETAINED_TRANSPORT_HEADERS) {
+				const value = headers.get(name);
+				if (typeof value !== "string") continue;
+				record ??= {};
+				record[name] = value;
+			}
+			return record;
+		}
+		for (const key of Object.keys(headers)) {
+			const descriptor = Object.getOwnPropertyDescriptor(headers, key);
+			if (!descriptor || !("value" in descriptor) || typeof descriptor.value !== "string") continue;
+			const name = key.toLowerCase();
+			if (!RETAINED_TRANSPORT_HEADER_SET.has(name)) continue;
+			record ??= {};
+			record[name] = descriptor.value;
+		}
+		return record;
+	} catch {
+		return undefined;
+	}
+}
+
+/** Extracts only explicit HTTP/transport metadata; it never parses error text. */
+export function transportFailureFacts(
+	error: unknown,
+	capturedResponse?: { status?: number; headers?: TransportHeaders },
+): TransportFailureFacts | undefined {
+	if (!error || typeof error !== "object") return undefined;
+	const value = error as FallbackTriggerInput & { kind?: unknown; type?: unknown };
+	const response = propertyOf(value, "response");
+	const nestedError = propertyOf(value, "error");
+	const status =
+		finiteStatus(propertyOf(value, "status")) ??
+		finiteStatus(propertyOf(response, "status")) ??
+		finiteStatus(propertyOf(capturedResponse, "status"));
+	const anthropicErrorType = stringValue(propertyOf(nestedError, "type")) ?? stringValue(propertyOf(value, "type"));
+	const openaiErrorCode =
+		stringValue(propertyOf(value, "openaiErrorCode")) ?? stringValue(propertyOf(nestedError, "code"));
+	const providerCode =
+		stringValue(propertyOf(value, "providerCode")) ??
+		openaiErrorCode ??
+		stringValue(propertyOf(value, "code")) ??
+		anthropicErrorType;
+	const errorHeaders = propertyOf(value, "headers");
+	const responseHeaders = propertyOf(response, "headers");
+	const capturedHeaders = propertyOf(capturedResponse, "headers");
+	const rawHeaders = isTransportHeaders(errorHeaders)
+		? errorHeaders
+		: isTransportHeaders(responseHeaders)
+			? responseHeaders
+			: isTransportHeaders(capturedHeaders)
+				? capturedHeaders
+				: undefined;
+	// Normalize BEFORE the existence gate so normalization is idempotent:
+	// facts built from an error whose headers carry no retained retry signal
+	// must not exist on the first pass and then vanish when re-normalized
+	// (consumers deliberately re-run transportFailureFacts on embedded facts).
+	const headers = retainedHeaderRecord(rawHeaders);
+	const normalizedCode = providerCode?.toLowerCase();
+	if (
+		status === undefined &&
+		headers === undefined &&
+		!isQuotaCode(normalizedCode) &&
+		!isAuthCode(normalizedCode) &&
+		!isRateLimitCode(normalizedCode) &&
+		!isContextOverflowCode(normalizedCode)
+	) {
+		return undefined;
+	}
+	return { kind: "transport", status, providerCode, anthropicErrorType, openaiErrorCode, headers };
+}
+
+function headersOf(headers: TransportHeaders | undefined): Headers | undefined {
+	if (headers instanceof Headers) return headers;
+	return headers ? new Headers(headers as Record<string, string>) : undefined;
+}
+
+function parseRetryAfterSeconds(value: string | null, now = Date.now()): number | undefined {
+	if (!value) return undefined;
+	const seconds = Number(value);
+	if (Number.isFinite(seconds) && seconds >= 0) return Math.round(seconds * 1000);
+	const date = Date.parse(value);
+	return Number.isFinite(date) ? Math.max(0, date - now) : undefined;
+}
+
+function parseRetryAfterMilliseconds(value: string | null): number | undefined {
+	if (!value) return undefined;
+	const milliseconds = Number(value);
+	return Number.isFinite(milliseconds) && milliseconds >= 0 ? Math.round(milliseconds) : undefined;
+}
+
+function isContextOverflowCode(code: string | undefined): boolean {
+	return code === "context_length_exceeded";
+}
+function isQuotaCode(code: string | undefined): boolean {
+	return (
+		code === "insufficient_quota" ||
+		code === "quota_exceeded" ||
+		code === "quota_exhausted" ||
+		code === "usage_limit_reached" ||
+		code === "usage_not_included" ||
+		code === "out_of_credits"
+	);
+}
+
+function isAuthCode(code: string | undefined): boolean {
+	return (
+		code === "authentication_error" ||
+		code === "invalid_api_key" ||
+		code === "invalid_token" ||
+		code === "token_expired" ||
+		code === "unauthorized" ||
+		code === "forbidden"
+	);
+}
+
+function isRateLimitCode(code: string | undefined): boolean {
+	return (
+		code === "rate_limit" ||
+		code === "rate_limit_error" ||
+		code === "rate_limit_exceeded" ||
+		code === "too_many_requests"
+	);
+}
+
+/** Classifies only typed upstream transport facts without consuming response bodies. */
+export function classifyFallbackTrigger(
+	errorOrFacts: TransportFailureFacts | FallbackTriggerInput | unknown,
+): FallbackTrigger {
+	const facts = transportFailureFacts(errorOrFacts);
+	if (!facts) return { class: "other" };
+	const headers = headersOf(facts.headers);
+	const retryAfterMs =
+		parseRetryAfterMilliseconds(headers?.get("retry-after-ms") ?? null) ??
+		parseRetryAfterSeconds(headers?.get("retry-after") ?? null);
+	const code = (facts.openaiErrorCode ?? facts.anthropicErrorType ?? facts.providerCode)?.toLowerCase();
+	const triggerClass: FallbackTriggerClass = isQuotaCode(code)
+		? "quota"
+		: facts.status === 401 || facts.status === 403 || isAuthCode(code)
+			? "auth"
+			: facts.status === 429 || isRateLimitCode(code)
+				? "rate_limit"
+				: facts.status !== undefined && facts.status >= 500 && facts.status <= 599
+					? "server"
+					: "other";
+	return retryAfterMs === undefined ? { class: triggerClass } : { class: triggerClass, retryAfterMs };
+}

package/src/utils/overflow.ts

@@ -1,4 +1,5 @@
 import type { AssistantMessage } from "../types";
+import type { TransportFailureFacts } from "./fallback-transport";
 
 /**
  * Regex patterns to detect context overflow errors from different providers.
@@ -119,48 +120,88 @@ const EMPTY_RESPONSE_USAGE_THRESHOLD = 5;
  * @param contextWindow - Optional context window size for detecting silent overflow (z.ai)
  * @returns true if the message indicates a context overflow
  */
-export function isContextOverflow(message: AssistantMessage, contextWindow?: number): boolean {
-	// Case 1: Check error message patterns
-	if (message.stopReason === "error" && message.errorMessage) {
-		// Check known patterns
-		if (OVERFLOW_PATTERNS.some(p => p.test(message.errorMessage!))) {
-			return true;
-		}
+/**
+ * Authoritatively classify a context overflow from the assistant result and
+ * normalized transport facts. Typed facts take precedence over provider prose:
+ * an explicit non-overflow transport failure cannot be upgraded by hostile or
+ * misleading error text.
+ */
+const OVERFLOW_PROVIDER_CODES = new Set(["context_length_exceeded", "request_too_large"]);
+const NON_OVERFLOW_PROVIDER_CODES = new Set([
+	"invalid_request_error",
+	"authentication_error",
+	"invalid_api_key",
+	"invalid_token",
+	"token_expired",
+	"unauthorized",
+	"forbidden",
+	"insufficient_quota",
+	"quota_exceeded",
+	"quota_exhausted",
+	"usage_limit_reached",
+	"usage_not_included",
+	"out_of_credits",
+	"rate_limit",
+	"rate_limit_error",
+	"rate_limit_exceeded",
+	"too_many_requests",
+]);
+
+function transportCodes(transportFailure: TransportFailureFacts | undefined): string[] {
+	return [transportFailure?.openaiErrorCode, transportFailure?.anthropicErrorType, transportFailure?.providerCode]
+		.filter((code): code is string => typeof code === "string")
+		.map(code => code.toLowerCase());
+}
+
+function hasTypedNonOverflowCode(transportFailure: TransportFailureFacts | undefined): boolean {
+	return transportCodes(transportFailure).some(code => NON_OVERFLOW_PROVIDER_CODES.has(code));
+}
+
+function isTypedNoBodyOverflow(
+	message: AssistantMessage,
+	transportFailure: TransportFailureFacts | undefined,
+): boolean {
+	if (transportFailure?.status !== 400 && transportFailure?.status !== 413) return false;
+	return !message.errorMessage || /\b4(00|13)\s*(status code)?\s*\(no body\)/i.test(message.errorMessage);
+}
 
-		// Cerebras and Mistral return 400/413 with no body for context overflow.
-		// Proxy providers (e.g. api.synthetic.new) wrap upstream 400/413 no-body
-		// responses in a JSON envelope, so the status code phrase may appear
-		// anywhere in the message rather than at its start.
-		// Note: 429 is rate limiting (requests/tokens per time), NOT context overflow
-		if (/\b4(00|13)\s*(status code)?\s*\(no body\)/i.test(message.errorMessage)) {
-			return true;
-		}
+export function classifyContextOverflow(
+	message: AssistantMessage,
+	transportFailure?: TransportFailureFacts,
+	contextWindow?: number,
+): boolean {
+	if (transportFailure?.status === 429) return false;
+	const typedCodes = transportCodes(transportFailure);
+	if (typedCodes.some(code => OVERFLOW_PROVIDER_CODES.has(code))) return true;
+	if (hasTypedNonOverflowCode(transportFailure)) return false;
+	if (isTypedNoBodyOverflow(message, transportFailure)) return true;
+
+	const errorMessage = message.errorMessage;
+	if (message.stopReason === "error" && errorMessage) {
+		if (OVERFLOW_PATTERNS.some(pattern => pattern.test(errorMessage))) return true;
+		if (/\b4(00|13)\s*(status code)?\s*\(no body\)/i.test(errorMessage)) return true;
 	}
 
-	// Case 2: Usage-based overflow (silent or provider-specific)
 	if (contextWindow) {
 		const inputTokens = message.usage.input + message.usage.cacheRead + message.usage.cacheWrite;
-		if (inputTokens > contextWindow) {
-			return true;
-		}
+		if (inputTokens > contextWindow) return true;
 	}
 
-	// Case 3: Empty response with anomalously low usage (proxy-level overflow)
-	// Some proxies (e.g. LiteLLM) return a "successful" response (stopReason "stop")
-	// with empty content and a near-zero token count when the upstream model's
-	// context window is exceeded. This is distinct from silent overflow (Case 2),
-	// where the provider reports the real input token count. Here the proxy
-	// fabricates a bogus usage (input: 1, output: 1) that is far below any
-	// realistic turn, so we detect it heuristically.
-	if (
+	return (
 		message.stopReason === "stop" &&
 		message.content.length === 0 &&
 		message.usage.input + message.usage.output <= EMPTY_RESPONSE_USAGE_THRESHOLD
-	) {
-		return true;
-	}
+	);
+}
 
-	return false;
+/**
+ * Check if an assistant message represents a context overflow error.
+ *
+ * Callers with normalized transport facts should use {@link classifyContextOverflow}
+ * so typed provider codes take precedence over error prose.
+ */
+export function isContextOverflow(message: AssistantMessage, contextWindow?: number): boolean {
+	return classifyContextOverflow(message, undefined, contextWindow);
 }
 
 /**

package/src/utils/retry.ts

@@ -34,9 +34,9 @@ const COPILOT_MODEL_RETRY_BASE_DELAY_MS = 400;
  */
 export async function callWithCopilotModelRetry<T>(
 	fn: () => Promise<T>,
-	options: { provider: string; signal?: AbortSignal; retryBaseDelayMs?: number },
+	options: { provider: string; signal?: AbortSignal; retryBaseDelayMs?: number; fallbackManaged?: boolean },
 ): Promise<T> {
-	if (options.provider !== "github-copilot") return fn();
+	if (options.provider !== "github-copilot" || options.fallbackManaged) return fn();
 
 	let lastError: unknown;
 	const retryBaseDelayMs = options.retryBaseDelayMs ?? COPILOT_MODEL_RETRY_BASE_DELAY_MS;