@aryee337/aery-ai 0.2.28 → 0.2.29

package/src/utils/overflow.ts

@@ -0,0 +1,137 @@
+import type { AssistantMessage } from "../types";
+
+/**
+ * Regex patterns to detect context overflow errors from different providers.
+ *
+ * These patterns match error messages returned when the input exceeds
+ * the model's context window.
+ *
+ * Provider-specific patterns (with example error messages):
+ *
+ * - Anthropic: "prompt is too long: 213462 tokens > 200000 maximum"
+ * - OpenAI: "Your input exceeds the context window of this model"
+ * - Google: "The input token count (1196265) exceeds the maximum number of tokens allowed (1048575)"
+ * - xAI: "This model's maximum prompt length is 131072 but the request contains 537812 tokens"
+ * - Groq: "Please reduce the length of the messages or completion"
+ * - OpenRouter: "This endpoint's maximum context length is X tokens. However, you requested about Y tokens"
+ * - llama.cpp: "the request exceeds the available context size, try increasing it"
+ * - LM Studio: "tokens to keep from the initial prompt is greater than the context length"
+ * - GitHub Copilot: "prompt token count of X exceeds the limit of Y"
+ * - MiniMax: "invalid params, context window exceeds limit"
+ * - Kimi For Coding: "Your request exceeded model token limit: X (requested: Y)"
+ * - Anthropic 413: "request_too_large" / "Request exceeds the maximum size" (payload too large)
+ * - HTTP 413 variants: "Payload Too Large" / "Request Entity Too Large"
+ * - z.ai / GLM: Returns finish_reason: "model_context_window_exceeded" mapped to error message
+ * - z.ai: Does NOT error, accepts overflow silently - handled via usage.input > contextWindow
+ * - Ollama: Silently truncates input - not detectable via error message
+ */
+const OVERFLOW_PATTERNS = [
+	/prompt is too long/i, // Anthropic
+	/input is too long for requested model/i, // Amazon Bedrock
+	/exceeds the context window/i, // OpenAI (Completions & Responses API)
+	/input token count.*exceeds the maximum/i, // Google (Gemini)
+	/maximum prompt length is \d+/i, // xAI (Grok)
+	/reduce the length of the messages/i, // Groq
+	/maximum context length is \d+ tokens/i, // OpenRouter (all backends)
+	/exceeds the limit of \d+/i, // GitHub Copilot
+	/exceeds the available context size/i, // llama.cpp server
+	/requested tokens?.*exceed.*context (window|length|size)/i, // llama.cpp / OpenAI-compatible local servers
+	/context (window|length|size).*(exceeded|overflow|too small)/i, // Generic local server variants
+	/(prompt|input).*(too long|too large).*(context|n_ctx)/i, // llama.cpp phrasing variants
+	/requested tokens?.*(exceeds?|greater than).*(n_ctx|context)/i, // llama.cpp n_ctx variants
+	/greater than the context length/i, // LM Studio
+	/context window exceeds limit/i, // MiniMax
+	/exceeded model token limit/i, // Kimi For Coding
+	/context[_ ]length[_ ]exceeded/i, // Generic fallback
+	/too many tokens/i, // Generic fallback
+	/token limit exceeded/i, // Generic fallback
+	/request_too_large/i, // Anthropic 413 (request body too large)
+	/request exceeds the maximum size/i, // Anthropic 413 variant
+	/payload too large/i, // Generic HTTP 413 variant
+	/entity too large/i, // Generic HTTP 413 variant
+	/\b413\b.*\b(request|payload|entity)\b.*\btoo large\b/i, // "413 Request Entity Too Large" variants
+	/model_context_window_exceeded/i, // z.ai non-standard finish_reason surfaced as error text
+];
+/**
+ * Check if an assistant message represents a context overflow error.
+ *
+ * This handles two cases:
+ * 1. Error-based overflow: Most providers return stopReason "error" with a
+ *    specific error message pattern.
+ * 2. Silent overflow: Some providers accept overflow requests and return
+ *    successfully. For these, we check if usage.input exceeds the context window.
+ *
+ * ## Reliability by Provider
+ *
+ * **Reliable detection (returns error with detectable message):**
+ * - Anthropic: "prompt is too long: X tokens > Y maximum"
+ * - OpenAI (Completions & Responses): "exceeds the context window"
+ * - Google Gemini: "input token count exceeds the maximum"
+ * - xAI (Grok): "maximum prompt length is X but request contains Y"
+ * - Groq: "reduce the length of the messages"
+ * - Cerebras: 400/413 status code (no body)
+ * - Mistral: 400/413 status code (no body)
+ * - HTTP 413 payload/entity-too-large variants
+ * - OpenRouter (all backends): "maximum context length is X tokens"
+ * - llama.cpp: "exceeds the available context size"
+ * - LM Studio: "greater than the context length"
+ * - Kimi For Coding: "exceeded model token limit: X (requested: Y)"
+ * - Anthropic 413: "request_too_large" (request body exceeds size limit)
+ * - HTTP 413: "Payload Too Large" / "Request Entity Too Large"
+ *
+ * **Unreliable detection:**
+ * - z.ai: Sometimes accepts overflow silently (detectable via usage.input > contextWindow),
+ *   sometimes returns rate limit errors. Pass contextWindow param to detect silent overflow.
+ * - Ollama: Silently truncates input without error. Cannot be detected via this function.
+ *   The response will have usage.input < expected, but we don't know the expected value.
+ *
+ * ## Custom Providers
+ *
+ * If you've added custom models via settings.json, this function may not detect
+ * overflow errors from those providers. To add support:
+ *
+ * 1. Send a request that exceeds the model's context window
+ * 2. Check the errorMessage in the response
+ * 3. Create a regex pattern that matches the error
+ * 4. The pattern should be added to OVERFLOW_PATTERNS in this file, or
+ *    check the errorMessage yourself before calling this function
+ *
+ * @param message - The assistant message to check
+ * @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;
+		}
+
+		// 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;
+		}
+	}
+
+	// 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;
+		}
+	}
+
+	return false;
+}
+
+/**
+ * Get the overflow patterns for testing purposes.
+ */
+export function getOverflowPatterns(): RegExp[] {
+	return [...OVERFLOW_PATTERNS];
+}

package/src/utils/parse-bind.ts

@@ -0,0 +1,54 @@
+/**
+ * Shared `host:port` parser used by the auth-broker and auth-gateway boot
+ * paths. Centralized so the two servers can't drift on what they accept (the
+ * gateway used to silently allow empty hostnames; this fixes it).
+ */
+
+export interface ParsedBind {
+	hostname: string;
+	port: number;
+}
+
+function parsePort(raw: string, bind: string): number {
+	if (!/^\d+$/.test(raw)) {
+		throw new Error(`Invalid bind '${bind}'; port must be an integer.`);
+	}
+	const port = Number.parseInt(raw, 10);
+	if (!Number.isFinite(port) || port < 0 || port > 65535) {
+		throw new Error(`Invalid bind '${bind}'; port out of range.`);
+	}
+	return port;
+}
+
+/**
+ * Parse a `host:port` (or bare `port`, which assumes loopback) string.
+ *
+ * Accepts:
+ *   - `"4000"`            → `127.0.0.1:4000`
+ *   - `"0.0.0.0:4000"`    → as written
+ *   - `"[::1]:4000"`      → as written (brackets retained, Bun handles them)
+ *
+ * Rejects:
+ *   - empty input
+ *   - empty hostname (`":4000"`)
+ *   - non-integer / out-of-range port
+ */
+export function parseBind(raw: string): ParsedBind {
+	const trimmed = raw.trim();
+	if (trimmed.length === 0) {
+		throw new Error("Invalid bind; expected 'host:port' or 'port'.");
+	}
+	if (/^\d+$/.test(trimmed)) {
+		return { hostname: "127.0.0.1", port: parsePort(trimmed, raw) };
+	}
+	const lastColon = trimmed.lastIndexOf(":");
+	if (lastColon < 0) {
+		throw new Error(`Invalid bind '${raw}'; expected 'host:port' or 'port'.`);
+	}
+	const hostPart = trimmed.slice(0, lastColon);
+	const portPart = trimmed.slice(lastColon + 1);
+	if (hostPart.length === 0) {
+		throw new Error(`Invalid bind '${raw}'; host must not be empty.`);
+	}
+	return { hostname: hostPart, port: parsePort(portPart, raw) };
+}

package/src/utils/provider-response.ts

@@ -0,0 +1,30 @@
+import type { Api, Model, ProviderResponseMetadata, StreamOptions } from "../types";
+
+export function normalizeProviderResponse(
+	response: Response,
+	requestId?: string | null,
+	metadata?: Record<string, unknown>,
+): ProviderResponseMetadata {
+	const headers: Record<string, string> = {};
+	response.headers.forEach((value, key) => {
+		headers[key.toLowerCase()] = value;
+	});
+	const providerResponse: ProviderResponseMetadata = {
+		status: response.status,
+		headers,
+	};
+	if (requestId !== undefined) providerResponse.requestId = requestId;
+	if (metadata !== undefined) providerResponse.metadata = metadata;
+	return providerResponse;
+}
+
+export async function notifyProviderResponse(
+	options: Pick<StreamOptions, "onResponse"> | undefined,
+	response: Response,
+	model?: Model<Api>,
+	requestId?: string | null,
+	metadata?: Record<string, unknown>,
+): Promise<void> {
+	if (!options?.onResponse) return;
+	await options.onResponse(normalizeProviderResponse(response, requestId, metadata), model);
+}

package/src/utils/request-debug.ts

@@ -0,0 +1,336 @@
+import { Buffer } from "node:buffer";
+import * as fs from "node:fs/promises";
+import type { FetchImpl } from "../types";
+
+const REQUEST_DEBUG_ENV = "PI_REQ_DEBUG";
+const DEBUG_FETCH_MARKER = Symbol("aery.requestDebugFetch");
+const textEncoder = new TextEncoder();
+const utf8Decoder = new TextDecoder("utf-8", { fatal: true });
+
+let nextSessionId = 1;
+
+type DebugFetch = FetchImpl & { [DEBUG_FETCH_MARKER]?: true };
+type RequestBodyInit = NonNullable<RequestInit["body"]>;
+
+type RequestDebugBody = { body: unknown } | { bodyText: string } | { bodyBase64: string } | { bodyUnavailable: string };
+
+export type RequestDebugHeaders = Headers | Record<string, string | string[] | number | undefined | null> | undefined;
+
+export interface RequestDebugPayload {
+	method: string;
+	url: string;
+	headers?: RequestDebugHeaders;
+	body?: unknown;
+	bodyText?: string;
+	bodyBase64?: string;
+	bodyUnavailable?: string;
+	protocol?: string;
+}
+
+export interface RequestDebugResponseLog {
+	write(chunk: Uint8Array | string): void;
+	close(): Promise<void>;
+}
+
+export interface RequestDebugSession {
+	readonly id: number;
+	readonly requestPath: string;
+	readonly responsePath: string;
+	openResponseLog(statusLine: string, headers?: RequestDebugHeaders): Promise<RequestDebugResponseLog>;
+	wrapResponse(response: Response): Promise<Response>;
+}
+
+export function isRequestDebugEnabled(): boolean {
+	return Bun.env[REQUEST_DEBUG_ENV] === "1";
+}
+
+export function wrapFetchForRequestDebug(fetchImpl: FetchImpl): FetchImpl {
+	if (!isRequestDebugEnabled()) return fetchImpl;
+	const maybeWrapped = fetchImpl as DebugFetch;
+	if (maybeWrapped[DEBUG_FETCH_MARKER]) return fetchImpl;
+
+	const wrapped = Object.assign(
+		async (input: string | URL | Request, init?: RequestInit): Promise<Response> => {
+			const session = await createFetchRequestDebugSession(input, init);
+			const response = await fetchImpl(input, init);
+			return session.wrapResponse(response);
+		},
+		fetchImpl.preconnect ? { preconnect: fetchImpl.preconnect } : {},
+		{ [DEBUG_FETCH_MARKER]: true as const },
+	);
+	return wrapped;
+}
+
+export function withRequestDebugFetch<T extends { fetch?: FetchImpl } | undefined>(options: T): T {
+	if (!isRequestDebugEnabled()) return options;
+	const fetchImpl = options?.fetch ?? (globalThis.fetch as FetchImpl);
+	const wrapped = wrapFetchForRequestDebug(fetchImpl);
+	return { ...(options ?? {}), fetch: wrapped } as T;
+}
+
+export async function createRequestDebugSession(payload: RequestDebugPayload): Promise<RequestDebugSession> {
+	const { id, requestPath, responsePath, handle } = await reserveRequestDebugFile();
+	const requestDump: Record<string, unknown> = {
+		id,
+		protocol: payload.protocol ?? "http",
+		method: payload.method,
+		url: payload.url,
+	};
+	const headers = headersToRecord(payload.headers);
+	if (headers) requestDump.headers = headers;
+	if (payload.body !== undefined) requestDump.body = payload.body;
+	if (payload.bodyText !== undefined) requestDump.bodyText = payload.bodyText;
+	if (payload.bodyBase64 !== undefined) requestDump.bodyBase64 = payload.bodyBase64;
+	if (payload.bodyUnavailable !== undefined) requestDump.bodyUnavailable = payload.bodyUnavailable;
+
+	try {
+		await handle.writeFile(`${JSON.stringify(requestDump, null, 2)}\n`, "utf8");
+	} finally {
+		await handle.close();
+	}
+
+	return new FileRequestDebugSession(id, requestPath, responsePath);
+}
+
+async function createFetchRequestDebugSession(
+	input: string | URL | Request,
+	init: RequestInit | undefined,
+): Promise<RequestDebugSession> {
+	const headers = resolveRequestHeaders(input, init);
+	const body = await snapshotRequestBody(input, init, headers.get("content-type"));
+	return createRequestDebugSession({
+		method: resolveRequestMethod(input, init),
+		url: resolveRequestUrl(input),
+		headers,
+		...body,
+	});
+}
+
+class FileRequestDebugSession implements RequestDebugSession {
+	readonly id: number;
+	readonly requestPath: string;
+	readonly responsePath: string;
+
+	constructor(id: number, requestPath: string, responsePath: string) {
+		this.id = id;
+		this.requestPath = requestPath;
+		this.responsePath = responsePath;
+	}
+
+	async openResponseLog(statusLine: string, headers?: RequestDebugHeaders): Promise<RequestDebugResponseLog> {
+		const handle = await fs.open(this.responsePath, "wx");
+		const headerBlock = formatResponseHeaderBlock(statusLine, headers);
+		await handle.write(textEncoder.encode(headerBlock));
+		return new FileRequestDebugResponseLog(handle);
+	}
+
+	async wrapResponse(response: Response): Promise<Response> {
+		const log = await this.openResponseLog(`HTTP ${response.status} ${response.statusText}`.trim(), response.headers);
+		if (!response.body) {
+			await log.close();
+			return response;
+		}
+
+		const reader = response.body.getReader();
+		const teed = new ReadableStream<Uint8Array>({
+			async pull(controller) {
+				try {
+					const { done, value } = await reader.read();
+					if (done) {
+						await log.close();
+						controller.close();
+						return;
+					}
+					log.write(value);
+					controller.enqueue(value);
+				} catch (error) {
+					await log.close().catch(() => undefined);
+					controller.error(error);
+				}
+			},
+			async cancel(reason) {
+				try {
+					await reader.cancel(reason);
+				} finally {
+					await log.close();
+				}
+			},
+		});
+
+		const wrapped = new Response(teed, {
+			status: response.status,
+			statusText: response.statusText,
+			headers: response.headers,
+		});
+		copyResponseMetadata(wrapped, response);
+		return wrapped;
+	}
+}
+
+class FileRequestDebugResponseLog implements RequestDebugResponseLog {
+	#handle: fs.FileHandle | undefined;
+	#pending: Promise<void> = Promise.resolve();
+
+	constructor(handle: fs.FileHandle) {
+		this.#handle = handle;
+	}
+
+	write(chunk: Uint8Array | string): void {
+		const handle = this.#handle;
+		if (!handle) return;
+		const bytes = typeof chunk === "string" ? textEncoder.encode(chunk) : chunk.slice();
+		this.#pending = this.#pending.then(async () => {
+			await handle.write(bytes);
+		});
+	}
+
+	async close(): Promise<void> {
+		const handle = this.#handle;
+		if (!handle) return;
+		this.#handle = undefined;
+		try {
+			await this.#pending;
+		} finally {
+			await handle.close();
+		}
+	}
+}
+
+function copyResponseMetadata(target: Response, source: Response): void {
+	const sourceUrl = source.url;
+	if (!sourceUrl) return;
+	try {
+		Object.defineProperty(target, "url", { value: sourceUrl, configurable: true });
+	} catch {
+		// Some runtimes may expose Response.url as non-configurable. The body
+		// capture remains correct; callers that need url already tolerate the
+		// platform default on other response wrappers in this package.
+	}
+}
+
+async function reserveRequestDebugFile(): Promise<{
+	id: number;
+	requestPath: string;
+	responsePath: string;
+	handle: fs.FileHandle;
+}> {
+	for (;;) {
+		const id = nextSessionId++;
+		const requestPath = `rr-session-${id}.json`;
+		try {
+			const handle = await fs.open(requestPath, "wx");
+			return { id, requestPath, responsePath: `rr-session-${id}.res.log`, handle };
+		} catch (error) {
+			if (isFileExistsError(error)) continue;
+			throw error;
+		}
+	}
+}
+
+function resolveRequestMethod(input: string | URL | Request, init: RequestInit | undefined): string {
+	return (init?.method ?? (input instanceof Request ? input.method : "GET")).toUpperCase();
+}
+
+function resolveRequestUrl(input: string | URL | Request): string {
+	return input instanceof Request ? input.url : input.toString();
+}
+
+function resolveRequestHeaders(input: string | URL | Request, init: RequestInit | undefined): Headers {
+	if (init?.headers) return new Headers(init.headers);
+	return input instanceof Request ? new Headers(input.headers) : new Headers();
+}
+
+async function snapshotRequestBody(
+	input: string | URL | Request,
+	init: RequestInit | undefined,
+	contentType: string | null,
+): Promise<RequestDebugBody | undefined> {
+	if (init?.body !== undefined && init.body !== null) return snapshotBodyInit(init.body, contentType);
+	if (input instanceof Request && input.body) {
+		return snapshotBytes(new Uint8Array(await input.clone().arrayBuffer()), contentType);
+	}
+	return undefined;
+}
+
+async function snapshotBodyInit(body: RequestBodyInit, contentType: string | null): Promise<RequestDebugBody> {
+	if (typeof body === "string") return snapshotText(body, contentType);
+	if (body instanceof URLSearchParams) return { bodyText: body.toString() };
+	if (body instanceof FormData) return { bodyUnavailable: "FormData" };
+	if (body instanceof Blob) return snapshotBytes(new Uint8Array(await body.arrayBuffer()), body.type || contentType);
+	if (body instanceof ArrayBuffer) return snapshotBytes(new Uint8Array(body), contentType);
+	if (ArrayBuffer.isView(body)) {
+		return snapshotBytes(new Uint8Array(body.buffer, body.byteOffset, body.byteLength), contentType);
+	}
+	if (body instanceof ReadableStream) return { bodyUnavailable: "ReadableStream" };
+	return { bodyText: String(body) };
+}
+
+function snapshotBytes(bytes: Uint8Array, contentType: string | null): RequestDebugBody {
+	try {
+		return snapshotText(utf8Decoder.decode(bytes), contentType);
+	} catch {
+		return { bodyBase64: Buffer.from(bytes).toString("base64") };
+	}
+}
+
+function snapshotText(text: string, contentType: string | null): RequestDebugBody {
+	if (isJsonContentType(contentType) || looksLikeJson(text)) {
+		try {
+			return { body: JSON.parse(text) };
+		} catch {
+			// Fall through to bodyText: malformed JSON is still useful as raw text.
+		}
+	}
+	return { bodyText: text };
+}
+
+function isJsonContentType(contentType: string | null): boolean {
+	if (!contentType) return false;
+	const lower = contentType.toLowerCase();
+	return lower.includes("application/json") || lower.includes("+json");
+}
+
+function looksLikeJson(text: string): boolean {
+	const trimmed = text.trimStart();
+	return trimmed.startsWith("{") || trimmed.startsWith("[");
+}
+
+function formatResponseHeaderBlock(statusLine: string, headers?: RequestDebugHeaders): string {
+	const lines = [statusLine];
+	const record = headersToRecord(headers);
+	if (record) {
+		for (const name in record) {
+			const value = record[name];
+			if (Array.isArray(value)) {
+				for (const item of value) lines.push(`${name}: ${item}`);
+			} else {
+				lines.push(`${name}: ${value}`);
+			}
+		}
+	}
+	return `${lines.join("\r\n")}\r\n\r\n`;
+}
+
+function headersToRecord(headers: RequestDebugHeaders): Record<string, string | string[]> | undefined {
+	if (!headers) return undefined;
+	const record: Record<string, string | string[]> = {};
+	let hasHeaders = false;
+	if (headers instanceof Headers) {
+		headers.forEach((value, key) => {
+			hasHeaders = true;
+			record[key] = value;
+		});
+	} else {
+		for (const key in headers) {
+			const value = headers[key];
+			if (value === undefined || value === null) continue;
+			hasHeaders = true;
+			record[key] = Array.isArray(value) ? value.map(String) : String(value);
+		}
+	}
+	return hasHeaders ? record : undefined;
+}
+
+function isFileExistsError(error: unknown): boolean {
+	return typeof error === "object" && error !== null && (error as { code?: unknown }).code === "EEXIST";
+}

package/src/utils/retry-after.ts

@@ -0,0 +1,110 @@
+export type HeadersLike = Headers | Record<string, string | undefined> | undefined | null;
+
+const RETRY_AFTER_HINT = "retry-after-ms=";
+
+export function formatErrorMessageWithRetryAfter(error: unknown, headers?: HeadersLike): string {
+	const message = error instanceof Error ? error.message : JSON.stringify(error);
+	if (message.includes(RETRY_AFTER_HINT)) {
+		return message;
+	}
+
+	const retryAfterMs = getRetryAfterMsFromHeaders(headers ?? getHeadersFromError(error));
+	if (retryAfterMs === undefined) {
+		return message;
+	}
+
+	return `${message} ${RETRY_AFTER_HINT}${retryAfterMs}`;
+}
+
+export function getRetryAfterMsFromHeaders(headers: HeadersLike): number | undefined {
+	if (!headers) return undefined;
+
+	const retryAfter = parseRetryAfterHeader(getHeaderValue(headers, "retry-after"));
+	const resetMs = parseResetHeader(getHeaderValue(headers, "x-ratelimit-reset-ms"), "ms");
+	const resetSeconds = parseResetHeader(getHeaderValue(headers, "x-ratelimit-reset"), "s");
+
+	const candidates = [retryAfter, resetMs, resetSeconds].filter((value): value is number => value !== undefined);
+	if (candidates.length === 0) return undefined;
+	return Math.max(...candidates);
+}
+
+function getHeadersFromError(error: unknown): HeadersLike {
+	if (!error || typeof error !== "object") return undefined;
+	const record = error as { headers?: unknown; response?: { headers?: unknown }; cause?: unknown };
+	const direct = extractHeaders(record.headers) ?? extractHeaders(record.response?.headers);
+	if (direct) return direct;
+	if (record.cause) return getHeadersFromError(record.cause);
+	return undefined;
+}
+
+function extractHeaders(value: unknown): HeadersLike {
+	if (!value) return undefined;
+	if (value instanceof Headers) return value;
+	if (typeof value === "object") return value as Record<string, string | undefined>;
+	return undefined;
+}
+
+function getHeaderValue(headers: Headers | Record<string, string | undefined>, name: string): string | undefined {
+	if (headers instanceof Headers) {
+		const value = headers.get(name);
+		return value ?? undefined;
+	}
+
+	const target = name.toLowerCase();
+	for (const [key, value] of Object.entries(headers)) {
+		if (key.toLowerCase() === target && typeof value === "string") {
+			return value;
+		}
+	}
+	return undefined;
+}
+
+function parseRetryAfterHeader(value: string | undefined): number | undefined {
+	if (!value) return undefined;
+	const trimmed = value.trim();
+	if (!trimmed) return undefined;
+
+	const numeric = Number(trimmed);
+	if (Number.isFinite(numeric)) {
+		if (numeric <= 0) return undefined;
+		return Math.ceil(numeric * 1000);
+	}
+
+	const dateMs = Date.parse(trimmed);
+	if (!Number.isNaN(dateMs)) {
+		const delay = dateMs - Date.now();
+		return delay > 0 ? Math.ceil(delay) : undefined;
+	}
+
+	return undefined;
+}
+
+function parseResetHeader(value: string | undefined, unit: "ms" | "s"): number | undefined {
+	if (!value) return undefined;
+	const numeric = Number(value);
+	if (!Number.isFinite(numeric) || numeric <= 0) return undefined;
+
+	const nowMs = Date.now();
+	let targetMs: number | undefined;
+
+	if (unit === "ms") {
+		if (numeric > 1e12) {
+			targetMs = numeric;
+		} else if (numeric > 1e9) {
+			targetMs = numeric * 1000;
+		} else {
+			return Math.ceil(numeric);
+		}
+	} else {
+		if (numeric > 1e12) {
+			targetMs = numeric;
+		} else if (numeric > 1e9) {
+			targetMs = numeric * 1000;
+		} else {
+			return Math.ceil(numeric * 1000);
+		}
+	}
+
+	if (targetMs <= nowMs) return undefined;
+	return Math.ceil(targetMs - nowMs);
+}