@gajae-code/ai 0.11.1 → 0.11.2

package/src/utils/fallback-transport.ts

@@ -1,4 +1,4 @@
-export type FallbackTriggerClass = "rate_limit" | "quota" | "auth" | "server" | "other";
+export type FallbackTriggerClass = "rate_limit" | "quota" | "auth" | "server" | "unknown" | "other";
 
 export interface FallbackTrigger {
 	class: FallbackTriggerClass;
@@ -10,12 +10,23 @@ 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;
-	headers?: TransportHeaders;
+	/** 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. */
@@ -65,7 +76,70 @@ export interface FallbackTriggerInput {
 }
 
 function isTransportHeaders(value: unknown): value is TransportHeaders {
-	return value instanceof Headers || (!!value && typeof value === "object");
+	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. */
@@ -75,40 +149,47 @@ export function transportFailureFacts(
 ): 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 =
-		typeof value.status === "number"
-			? value.status
-			: typeof value.response?.status === "number"
-				? value.response.status
-				: capturedResponse?.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 =
-		typeof value.providerCode === "string"
-			? value.providerCode
-			: typeof value.code === "string"
-				? value.code
-				: typeof value.error?.code === "string"
-					? value.error.code
-					: typeof value.type === "string"
-						? value.type
-						: typeof value.error?.type === "string"
-							? value.error.type
-							: undefined;
-	const headers = isTransportHeaders(value.headers)
-		? value.headers
-		: isTransportHeaders(value.response?.headers)
-			? value.response.headers
-			: capturedResponse?.headers;
+		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)
+		!isRateLimitCode(normalizedCode) &&
+		!isContextOverflowCode(normalizedCode)
 	) {
 		return undefined;
 	}
-	return { kind: "transport", status, providerCode, headers };
+	return { kind: "transport", status, providerCode, anthropicErrorType, openaiErrorCode, headers };
 }
 
 function headersOf(headers: TransportHeaders | undefined): Headers | undefined {
@@ -130,6 +211,9 @@ function parseRetryAfterMilliseconds(value: string | null): number | undefined {
 	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" ||
@@ -171,7 +255,7 @@ export function classifyFallbackTrigger(
 	const retryAfterMs =
 		parseRetryAfterMilliseconds(headers?.get("retry-after-ms") ?? null) ??
 		parseRetryAfterSeconds(headers?.get("retry-after") ?? null);
-	const code = facts.providerCode?.toLowerCase();
+	const code = (facts.openaiErrorCode ?? facts.anthropicErrorType ?? facts.providerCode)?.toLowerCase();
 	const triggerClass: FallbackTriggerClass = isQuotaCode(code)
 		? "quota"
 		: facts.status === 401 || facts.status === 403 || isAuthCode(code)

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);
 }
 
 /**