@linxiraos/pi-ai 1.0.0

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/proxy.ts

@@ -0,0 +1,314 @@
+import * as net from "node:net";
+import * as tls from "node:tls";
+import * as AIError from "../error";
+import type { FetchImpl } from "../types";
+
+/**
+ * Checks if a host is local or cloud metadata, which should always bypass the proxy
+ * (e.g. localhost, 127/8, ::1, 169.254.169.254, metadata.google.internal).
+ */
+export function isLocalOrMetadataHost(host: string): boolean {
+	const lowerHost = host.toLowerCase();
+
+	// Hostnames: localhost and the cloud metadata service.
+	if (lowerHost === "localhost" || lowerHost.endsWith(".localhost") || lowerHost === "metadata.google.internal") {
+		return true;
+	}
+
+	// Strip IPv6 brackets before numeric checks.
+	const ip = lowerHost.replace(/^\[|\]$/g, "");
+
+	// IPv4 loopback (127/8), unspecified (0/8), RFC1918 private (10/8, 172.16/12,
+	// 192.168/16) and link-local (169.254/16 — covers IMDS 169.254.169.254 and
+	// ECS credentials 169.254.170.2). None are reachable through a remote egress
+	// proxy, and credential/metadata probes must never leak to one.
+	const v4 = ip.match(/^(\d{1,3})\.(\d{1,3})\.\d{1,3}\.\d{1,3}$/);
+	if (v4) {
+		const a = Number(v4[1]);
+		const b = Number(v4[2]);
+		if (a === 127 || a === 10 || a === 0) return true;
+		if (a === 169 && b === 254) return true;
+		if (a === 192 && b === 168) return true;
+		if (a === 172 && b >= 16 && b <= 31) return true;
+		return false;
+	}
+
+	// IPv6 loopback (::1), unspecified (::), link-local (fe80::/10) and
+	// unique-local (fc00::/7 — covers EC2 IPv6 IMDS fd00:ec2::254).
+	if (ip === "::1" || ip === "::") return true;
+	if (/^fe[89ab][0-9a-f]:/.test(ip)) return true;
+	if (/^f[cd][0-9a-f]{2}:/.test(ip)) return true;
+
+	return false;
+}
+
+/**
+ * Check if the url should bypass the proxy due to hard-coded localhost/metadata checks
+ * or custom NO_PROXY/no_proxy environment variables rules.
+ */
+export function shouldBypassProxy(urlObj: URL): boolean {
+	if (isLocalOrMetadataHost(urlObj.hostname)) {
+		return true;
+	}
+
+	const noProxyVal = Bun.env.NO_PROXY || Bun.env.no_proxy;
+	if (!noProxyVal) {
+		return false;
+	}
+
+	const rules = noProxyVal
+		.split(/[,\s]+/)
+		.map(r => r.trim())
+		.filter(Boolean);
+	const targetHost = urlObj.hostname.toLowerCase();
+	const targetPort = urlObj.port || (urlObj.protocol === "https:" || urlObj.protocol === "wss:" ? "443" : "80");
+
+	for (const rule of rules) {
+		if (rule === "*") {
+			return true;
+		}
+
+		let ruleHost = rule.toLowerCase();
+		let rulePort: string | undefined;
+
+		if (ruleHost.includes("]:")) {
+			const lastColon = ruleHost.lastIndexOf(":");
+			rulePort = ruleHost.slice(lastColon + 1);
+			ruleHost = ruleHost.slice(0, lastColon);
+		} else if (!ruleHost.includes("]") && ruleHost.includes(":")) {
+			const lastColon = ruleHost.lastIndexOf(":");
+			rulePort = ruleHost.slice(lastColon + 1);
+			ruleHost = ruleHost.slice(0, lastColon);
+		}
+
+		// Strip IPv6 brackets
+		ruleHost = ruleHost.replace(/^\[|\]$/g, "");
+
+		if (rulePort && rulePort !== targetPort) {
+			continue;
+		}
+
+		// Match host part
+		if (ruleHost.startsWith(".")) {
+			const suffix = ruleHost;
+			const cleanRule = ruleHost.slice(1);
+			if (targetHost === cleanRule || targetHost.endsWith(suffix)) {
+				return true;
+			}
+		} else {
+			if (targetHost === ruleHost || targetHost.endsWith(`.${ruleHost}`)) {
+				return true;
+			}
+		}
+	}
+
+	return false;
+}
+
+const proxyCache = new Map<string, string | undefined>();
+
+/** Test seam: clears the provider proxy cache. */
+export function __resetProxyCache(): void {
+	proxyCache.clear();
+}
+
+/**
+ * Normalizes provider id (e.g. github-copilot -> PI_PROXY_GITHUB_COPILOT) and looks it up.
+ * If not found, falls back to PI_PROXY. Results are memoized because env values are static
+ * for the lifetime of the process and this function is called for every outgoing request.
+ */
+export function getProxyForProvider(provider: string): string | undefined {
+	if (proxyCache.has(provider)) {
+		return proxyCache.get(provider);
+	}
+
+	const normalized = provider.toUpperCase().replace(/[^A-Z0-9]/g, "_");
+	const envKey = `PI_PROXY_${normalized}`;
+	const value = Bun.env[envKey] || Bun.env.PI_PROXY;
+	proxyCache.set(provider, value);
+	return value;
+}
+
+/** Resolves provider-specific and standard proxy variables for a target URL, honoring NO_PROXY. */
+export function getProxyForUrl(provider: string, url: URL): string | undefined {
+	if (shouldBypassProxy(url)) return undefined;
+	const protocolProxy =
+		url.protocol === "https:" || url.protocol === "wss:"
+			? Bun.env.HTTPS_PROXY || Bun.env.https_proxy
+			: Bun.env.HTTP_PROXY || Bun.env.http_proxy;
+	return getProxyForProvider(provider) || protocolProxy || Bun.env.ALL_PROXY || Bun.env.all_proxy || undefined;
+}
+
+/**
+ * Wraps a fetch implementation to inject proxy options for non-local hosts.
+ */
+export function wrapFetchForProxy(fetchImpl: FetchImpl, provider: string): FetchImpl {
+	const proxyUrl = getProxyForProvider(provider);
+	if (!proxyUrl) {
+		return fetchImpl;
+	}
+
+	const wrapped = async (input: string | URL | Request, init?: RequestInit): Promise<Response> => {
+		const urlStr = input instanceof Request ? input.url : input.toString();
+		let urlObj: URL;
+		try {
+			urlObj = new URL(urlStr);
+		} catch {
+			// Fallback to calling fetch unmodified if URL is unparseable
+			return fetchImpl(input, init);
+		}
+
+		if (shouldBypassProxy(urlObj)) {
+			return fetchImpl(input, init);
+		}
+
+		const mergedInit = { ...(init ?? {}), proxy: proxyUrl };
+		return fetchImpl(input, mergedInit);
+	};
+
+	if (fetchImpl.preconnect) {
+		wrapped.preconnect = fetchImpl.preconnect;
+	}
+	return wrapped;
+}
+
+export interface ConnectProxiedSocketOptions {
+	/** Caller cancellation for the proxy TCP/TLS handshake and CONNECT tunnel. */
+	signal?: AbortSignal;
+	/** Maximum wall-clock time to establish the final TLS tunnel. Disabled when absent or non-positive. */
+	timeoutMs?: number;
+	/** Target TLS profile. Cursor defaults to HTTP/2 when this is absent. */
+	tls?: tls.ConnectionOptions;
+}
+
+/**
+ * Tunnel a socket connection through an HTTP CONNECT proxy.
+ * This is used specifically to wrap Node's `http2.connect(baseUrl, { createConnection })` for Cursor.
+ */
+export async function connectProxiedSocket(
+	proxyUrlStr: string,
+	targetUrlStr: string,
+	options?: ConnectProxiedSocketOptions,
+): Promise<tls.TLSSocket> {
+	if (options?.signal?.aborted) {
+		throw new AIError.AbortError("Proxy tunnel aborted");
+	}
+
+	const proxyUrl = new URL(proxyUrlStr);
+	const targetUrl = new URL(targetUrlStr);
+
+	const useProxySsl = proxyUrl.protocol === "https:";
+	const proxyPort = proxyUrl.port ? parseInt(proxyUrl.port, 10) : useProxySsl ? 443 : 80;
+	const proxyHost = proxyUrl.hostname;
+
+	const targetPort = targetUrl.port ? parseInt(targetUrl.port, 10) : 443;
+	const targetHost = targetUrl.hostname;
+
+	const { promise, resolve, reject } = Promise.withResolvers<tls.TLSSocket>();
+
+	const readyEvent = useProxySsl ? "secureConnect" : "connect";
+	let rawSocket: net.Socket | undefined;
+	let tunnelSocket: tls.TLSSocket | undefined;
+	let timeout: NodeJS.Timeout | undefined;
+	let responseData = "";
+	let settled = false;
+
+	const cleanup = (): void => {
+		if (timeout) {
+			clearTimeout(timeout);
+			timeout = undefined;
+		}
+		options?.signal?.removeEventListener("abort", onAbort);
+		rawSocket?.off("error", onRawError);
+		rawSocket?.off(readyEvent, onProxyReady);
+		rawSocket?.off("data", onProxyData);
+		tunnelSocket?.off("secureConnect", onTunnelReady);
+		tunnelSocket?.off("error", onTunnelError);
+	};
+	const destroyInProgress = (): void => {
+		tunnelSocket?.destroy();
+		rawSocket?.destroy();
+	};
+	const rejectOnce = (error: Error): void => {
+		if (settled) return;
+		settled = true;
+		cleanup();
+		destroyInProgress();
+		reject(error);
+	};
+	const resolveOnce = (socket: tls.TLSSocket): void => {
+		if (settled) return;
+		settled = true;
+		cleanup();
+		resolve(socket);
+	};
+	const onAbort = (): void => rejectOnce(new AIError.AbortError("Proxy tunnel aborted"));
+	const onRawError = (error: Error): void => rejectOnce(error);
+	const onTunnelError = (error: Error): void => rejectOnce(error);
+	const onTunnelReady = (): void => {
+		if (!tunnelSocket) return;
+		resolveOnce(tunnelSocket);
+	};
+	const onProxyData = (chunk: Buffer): void => {
+		if (!rawSocket) return;
+		responseData += chunk.toString("binary");
+		if (!responseData.includes("\r\n\r\n")) return;
+
+		rawSocket.off("data", onProxyData);
+		rawSocket.off("error", onRawError);
+
+		const firstLine = responseData.split("\r\n")[0];
+		if (!firstLine.includes(" 200 ")) {
+			rejectOnce(new AIError.ValidationError(`Proxy tunnel failed: ${firstLine}`));
+			return;
+		}
+
+		const tlsOptions = options?.tls;
+		tunnelSocket = tls.connect({
+			...tlsOptions,
+			socket: rawSocket,
+			servername: tlsOptions?.servername ?? targetHost,
+			ALPNProtocols: tlsOptions?.ALPNProtocols ?? ["h2"],
+		});
+		tunnelSocket.once("secureConnect", onTunnelReady);
+		tunnelSocket.once("error", onTunnelError);
+	};
+	const onProxyReady = (): void => {
+		if (!rawSocket) return;
+		let connectReq = `CONNECT ${targetHost}:${targetPort} HTTP/1.1\r\n` + `Host: ${targetHost}:${targetPort}\r\n`;
+
+		if (proxyUrl.username || proxyUrl.password) {
+			const creds = Buffer.from(
+				`${decodeURIComponent(proxyUrl.username)}:${decodeURIComponent(proxyUrl.password)}`,
+			).toString("base64");
+			connectReq += `Proxy-Authorization: Basic ${creds}\r\n`;
+		}
+		connectReq += "\r\n";
+
+		rawSocket.write(connectReq);
+		rawSocket.on("data", onProxyData);
+	};
+
+	options?.signal?.addEventListener("abort", onAbort, { once: true });
+	if (options?.timeoutMs !== undefined && Number.isFinite(options.timeoutMs) && options.timeoutMs > 0) {
+		const timeoutMs = Math.trunc(options.timeoutMs);
+		timeout = setTimeout(() => {
+			rejectOnce(new AIError.StreamTimeoutError(`Proxy tunnel timed out after ${timeoutMs}ms`));
+		}, timeoutMs);
+		timeout.unref?.();
+	}
+
+	rawSocket = useProxySsl
+		? tls.connect({
+				host: proxyHost,
+				port: proxyPort,
+			})
+		: net.connect({
+				host: proxyHost,
+				port: proxyPort,
+			});
+	rawSocket.once("error", onRawError);
+	rawSocket.once(readyEvent, onProxyReady);
+
+	return promise;
+}

package/src/utils/request-debug.ts

@@ -0,0 +1,351 @@
+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("omp.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;
+}
+
+interface ReservedRequestDebugFile {
+	id: number;
+	requestPath: string;
+	responsePath: string;
+	handle: fs.FileHandle;
+	overwrite: boolean;
+}
+
+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>;
+}
+
+function isRequestDebugEnvEnabled(): boolean {
+	return Bun.env[REQUEST_DEBUG_ENV] === "1";
+}
+
+export function isRequestDebugEnabled(): boolean {
+	return isRequestDebugEnvEnabled();
+}
+
+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> => {
+			if (!isRequestDebugEnabled()) return fetchImpl(input, init);
+			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, overwrite } = 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, overwrite);
+}
+
+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;
+	readonly #overwriteResponseLog: boolean;
+
+	constructor(id: number, requestPath: string, responsePath: string, overwriteResponseLog: boolean) {
+		this.id = id;
+		this.requestPath = requestPath;
+		this.responsePath = responsePath;
+		this.#overwriteResponseLog = overwriteResponseLog;
+	}
+
+	async openResponseLog(statusLine: string, headers?: RequestDebugHeaders): Promise<RequestDebugResponseLog> {
+		const handle = await fs.open(this.responsePath, this.#overwriteResponseLog ? "w" : "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();
+	#closed: Promise<void> | undefined;
+
+	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);
+		});
+	}
+
+	close(): Promise<void> {
+		if (this.#closed) return this.#closed;
+		const handle = this.#handle;
+		if (!handle) return Promise.resolve();
+		this.#handle = undefined;
+		this.#closed = (async () => {
+			try {
+				await this.#pending;
+			} finally {
+				await handle.close();
+			}
+		})();
+		return this.#closed;
+	}
+}
+
+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<ReservedRequestDebugFile> {
+	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, overwrite: false };
+		} 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";
+}