@oh-my-pi/pi-ai 15.5.12 → 15.5.15

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [Unreleased]
 
+## [15.5.15] - 2026-05-30
+
+### Added
+
+- Added `PI_REQ_DEBUG=1` request/response recording for provider transports. Each request writes `rr-session-N.json`; each received response writes `rr-session-N.res.log` with response headers followed by raw body bytes.
+
+### Fixed
+
+- Fixed OpenCode-Go dynamic model refresh downgrading `qwen3.7-max` from Anthropic Messages to OpenAI-compatible transport, which caused `401 Model qwen3.7-max is not supported for format oa-compat` after `/v1/models` cache refreshes.
+
 ## [15.5.12] - 2026-05-29
 ### Removed
 

package/dist/types/provider-models/openai-compat.d.ts

@@ -142,8 +142,8 @@ export interface OpenCodeModelManagerConfig {
     apiKey?: string;
     baseUrl?: string;
 }
-export declare function opencodeZenModelManagerOptions(config?: OpenCodeModelManagerConfig): ModelManagerOptions<"openai-completions">;
-export declare function opencodeGoModelManagerOptions(config?: OpenCodeModelManagerConfig): ModelManagerOptions<"openai-completions">;
+export declare function opencodeZenModelManagerOptions(config?: OpenCodeModelManagerConfig): ModelManagerOptions<Api>;
+export declare function opencodeGoModelManagerOptions(config?: OpenCodeModelManagerConfig): ModelManagerOptions<Api>;
 export interface OllamaModelManagerConfig {
     apiKey?: string;
     baseUrl?: string;

package/dist/types/utils/request-debug.d.ts

@@ -0,0 +1,29 @@
+import type { FetchImpl } from "../types";
+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 declare function isRequestDebugEnabled(): boolean;
+export declare function wrapFetchForRequestDebug(fetchImpl: FetchImpl): FetchImpl;
+export declare function withRequestDebugFetch<T extends {
+    fetch?: FetchImpl;
+} | undefined>(options: T): T;
+export declare function createRequestDebugSession(payload: RequestDebugPayload): Promise<RequestDebugSession>;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-ai",
-	"version": "15.5.12",
+	"version": "15.5.15",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -40,7 +40,7 @@
 	"dependencies": {
 		"@anthropic-ai/sdk": "^0.94.0",
 		"@bufbuild/protobuf": "^2.12.0",
-		"@oh-my-pi/pi-utils": "15.5.12",
+		"@oh-my-pi/pi-utils": "15.5.15",
 		"openai": "^6.36.0",
 		"partial-json": "^0.1.7",
 		"zod": "4.4.3"

package/src/model-manager.ts

@@ -289,20 +289,22 @@ function retainModelIds<TApi extends Api>(
  * arms calling `resolveProviderModels` with the same `staticModels` array)
  * skip the JSON+hash work after the first call.
  */
+const MODEL_CACHE_FINGERPRINT_VERSION = "merge-v2";
 const kStaticFingerprint = Symbol("model-manager.staticFingerprint");
 type ModelArrayWithFingerprint = readonly Model<Api>[] & { [kStaticFingerprint]?: string };
 function fingerprintStatic<TApi extends Api>(
 	models: readonly Model<TApi>[],
 	dynamicModelsAuthoritative = false,
 ): string {
-	if (models.length === 0) return "empty";
-	if (dynamicModelsAuthoritative) return `authoritative:${fingerprintStatic(models)}`;
+	if (models.length === 0) return `${MODEL_CACHE_FINGERPRINT_VERSION}:empty`;
+	if (dynamicModelsAuthoritative)
+		return `${MODEL_CACHE_FINGERPRINT_VERSION}:authoritative:${fingerprintStatic(models)}`;
 	const tagged = models as ModelArrayWithFingerprint;
 	const cached = tagged[kStaticFingerprint];
 	if (cached !== undefined) return cached;
 	// `Bun.hash` returns a `bigint`; base36 keeps the string short for the
 	// SQLite column without sacrificing distinguishability.
-	const fingerprint = Bun.hash(JSON.stringify(models)).toString(36);
+	const fingerprint = `${MODEL_CACHE_FINGERPRINT_VERSION}:${Bun.hash(JSON.stringify(models)).toString(36)}`;
 	tagged[kStaticFingerprint] = fingerprint;
 	return fingerprint;
 }

package/src/models.json

@@ -78417,9 +78417,9 @@
 		"mimo-v2-flash": {
 			"id": "mimo-v2-flash",
 			"name": "MiMo-V2-Flash",
-			"api": "anthropic-messages",
+			"api": "openai-completions",
 			"provider": "xiaomi",
-			"baseUrl": "https://api.xiaomimimo.com/anthropic",
+			"baseUrl": "https://api.xiaomimimo.com/v1",
 			"reasoning": true,
 			"input": [
 				"text"
@@ -78432,18 +78432,25 @@
 			},
 			"contextWindow": 262144,
 			"maxTokens": 65536,
+			"compat": {
+				"supportsStore": false,
+				"thinkingFormat": "zai",
+				"reasoningContentField": "reasoning_content",
+				"requiresReasoningContentForToolCalls": true,
+				"allowsSyntheticReasoningContentForToolCalls": false
+			},
 			"thinking": {
-				"mode": "budget",
+				"mode": "effort",
 				"minLevel": "minimal",
-				"maxLevel": "xhigh"
+				"maxLevel": "high"
 			}
 		},
 		"mimo-v2-omni": {
 			"id": "mimo-v2-omni",
 			"name": "MiMo-V2-Omni",
-			"api": "anthropic-messages",
+			"api": "openai-completions",
 			"provider": "xiaomi",
-			"baseUrl": "https://api.xiaomimimo.com/anthropic",
+			"baseUrl": "https://api.xiaomimimo.com/v1",
 			"reasoning": true,
 			"input": [
 				"text",
@@ -78457,18 +78464,25 @@
 			},
 			"contextWindow": 262144,
 			"maxTokens": 131072,
+			"compat": {
+				"supportsStore": false,
+				"thinkingFormat": "zai",
+				"reasoningContentField": "reasoning_content",
+				"requiresReasoningContentForToolCalls": true,
+				"allowsSyntheticReasoningContentForToolCalls": false
+			},
 			"thinking": {
-				"mode": "budget",
+				"mode": "effort",
 				"minLevel": "minimal",
-				"maxLevel": "xhigh"
+				"maxLevel": "high"
 			}
 		},
 		"mimo-v2-pro": {
 			"id": "mimo-v2-pro",
 			"name": "MiMo-V2-Pro",
-			"api": "anthropic-messages",
+			"api": "openai-completions",
 			"provider": "xiaomi",
-			"baseUrl": "https://api.xiaomimimo.com/anthropic",
+			"baseUrl": "https://api.xiaomimimo.com/v1",
 			"reasoning": true,
 			"input": [
 				"text"
@@ -78481,18 +78495,25 @@
 			},
 			"contextWindow": 1048576,
 			"maxTokens": 131072,
+			"compat": {
+				"supportsStore": false,
+				"thinkingFormat": "zai",
+				"reasoningContentField": "reasoning_content",
+				"requiresReasoningContentForToolCalls": true,
+				"allowsSyntheticReasoningContentForToolCalls": false
+			},
 			"thinking": {
-				"mode": "budget",
+				"mode": "effort",
 				"minLevel": "minimal",
-				"maxLevel": "xhigh"
+				"maxLevel": "high"
 			}
 		},
 		"mimo-v2.5": {
 			"id": "mimo-v2.5",
 			"name": "MiMo-V2.5",
-			"api": "anthropic-messages",
+			"api": "openai-completions",
 			"provider": "xiaomi",
-			"baseUrl": "https://api.xiaomimimo.com/anthropic",
+			"baseUrl": "https://api.xiaomimimo.com/v1",
 			"reasoning": true,
 			"input": [
 				"text",
@@ -78506,18 +78527,25 @@
 			},
 			"contextWindow": 1048576,
 			"maxTokens": 131072,
+			"compat": {
+				"supportsStore": false,
+				"thinkingFormat": "zai",
+				"reasoningContentField": "reasoning_content",
+				"requiresReasoningContentForToolCalls": true,
+				"allowsSyntheticReasoningContentForToolCalls": false
+			},
 			"thinking": {
-				"mode": "budget",
+				"mode": "effort",
 				"minLevel": "minimal",
-				"maxLevel": "xhigh"
+				"maxLevel": "high"
 			}
 		},
 		"mimo-v2.5-pro": {
 			"id": "mimo-v2.5-pro",
 			"name": "MiMo-V2.5-Pro",
-			"api": "anthropic-messages",
+			"api": "openai-completions",
 			"provider": "xiaomi",
-			"baseUrl": "https://api.xiaomimimo.com/anthropic",
+			"baseUrl": "https://api.xiaomimimo.com/v1",
 			"reasoning": true,
 			"input": [
 				"text"
@@ -78530,10 +78558,17 @@
 			},
 			"contextWindow": 1048576,
 			"maxTokens": 131072,
+			"compat": {
+				"supportsStore": false,
+				"thinkingFormat": "zai",
+				"reasoningContentField": "reasoning_content",
+				"requiresReasoningContentForToolCalls": true,
+				"allowsSyntheticReasoningContentForToolCalls": false
+			},
 			"thinking": {
-				"mode": "budget",
+				"mode": "effort",
 				"minLevel": "minimal",
-				"maxLevel": "xhigh"
+				"maxLevel": "high"
 			}
 		}
 	},

package/src/provider-models/openai-compat.ts

@@ -1218,37 +1218,62 @@ export interface OpenCodeModelManagerConfig {
 	baseUrl?: string;
 }
 
+function normalizeOpenCodeBasePath(baseUrl: string | undefined, fallbackBasePath: string): string {
+	const value = normalizeAnthropicBaseUrl(baseUrl, fallbackBasePath);
+	return value.endsWith("/v1") ? value.slice(0, -3) : value;
+}
+
+function openCodeBaseUrlForApi(api: Api, basePath: string): string {
+	return api === "anthropic-messages" ? basePath : `${basePath}/v1`;
+}
+
 function openCodeModelManagerOptions(
 	providerId: "opencode-go" | "opencode-zen",
-	defaultBaseUrl: string,
+	defaultBasePath: string,
 	config?: OpenCodeModelManagerConfig,
-): ModelManagerOptions<"openai-completions"> {
+): ModelManagerOptions<Api> {
 	const apiKey = config?.apiKey;
-	const baseUrl = config?.baseUrl ?? defaultBaseUrl;
+	const basePath = normalizeOpenCodeBasePath(config?.baseUrl, defaultBasePath);
+	const discoveryBaseUrl = openCodeBaseUrlForApi("openai-completions", basePath);
+	const references = createBundledReferenceMap<Api>(providerId);
 	return {
 		providerId,
 		...(apiKey && {
 			fetchDynamicModels: () =>
-				fetchOpenAICompatibleModels({
+				fetchOpenAICompatibleModels<Api>({
 					api: "openai-completions",
 					provider: providerId,
-					baseUrl,
+					baseUrl: discoveryBaseUrl,
 					apiKey,
+					mapModel: (entry, defaults) => {
+						const reference = references.get(defaults.id);
+						const name = toModelName(entry.name, reference?.name ?? defaults.name);
+						if (!reference) {
+							return {
+								...defaults,
+								name,
+							};
+						}
+						return {
+							...reference,
+							id: defaults.id,
+							name,
+							baseUrl: openCodeBaseUrlForApi(reference.api, basePath),
+							contextWindow: toPositiveNumber(entry.context_length, reference.contextWindow),
+							maxTokens: toPositiveNumber(entry.max_completion_tokens, reference.maxTokens),
+						};
+					},
 				}),
 		}),
 	};
 }
 
-export function opencodeZenModelManagerOptions(
-	config?: OpenCodeModelManagerConfig,
-): ModelManagerOptions<"openai-completions"> {
-	return openCodeModelManagerOptions("opencode-zen", "https://opencode.ai/zen/v1", config);
+export function opencodeZenModelManagerOptions(config?: OpenCodeModelManagerConfig): ModelManagerOptions<Api> {
+	return openCodeModelManagerOptions("opencode-zen", "https://opencode.ai/zen", config);
 }
 
-export function opencodeGoModelManagerOptions(
-	config?: OpenCodeModelManagerConfig,
-): ModelManagerOptions<"openai-completions"> {
-	return openCodeModelManagerOptions("opencode-go", "https://opencode.ai/zen/go/v1", config);
+export function opencodeGoModelManagerOptions(config?: OpenCodeModelManagerConfig): ModelManagerOptions<Api> {
+	return openCodeModelManagerOptions("opencode-go", "https://opencode.ai/zen/go", config);
 }
 
 // ---------------------------------------------------------------------------
@@ -2643,9 +2668,16 @@ const MODELS_DEV_PROVIDER_DESCRIPTORS_CODING_PLANS: readonly ModelsDevProviderDe
 	// --- zAI ---
 	anthropicMessagesDescriptor("zai-coding-plan", "zai", "https://api.z.ai/api/anthropic"),
 	// --- Xiaomi ---
-	anthropicMessagesDescriptor("xiaomi", "xiaomi", "https://api.xiaomimimo.com/anthropic", {
+	openAiCompletionsDescriptor("xiaomi", "xiaomi", "https://api.xiaomimimo.com/v1", {
 		defaultContextWindow: 262144,
 		defaultMaxTokens: 8192,
+		compat: {
+			supportsStore: false,
+			thinkingFormat: "zai",
+			reasoningContentField: "reasoning_content",
+			requiresReasoningContentForToolCalls: true,
+			allowsSyntheticReasoningContentForToolCalls: false,
+		},
 	}),
 	// --- MiniMax Coding Plan ---
 	openAiCompletionsDescriptor("minimax-coding-plan", "minimax-code", "https://api.minimax.io/v1", {

package/src/providers/amazon-bedrock.ts

@@ -273,6 +273,7 @@ export const streamBedrock: StreamFunction<"bedrock-converse-stream"> = (
 				headers: requestHeaders,
 				body,
 				signal: options.signal,
+				fetch: options.fetch,
 			});
 
 			if (!response.ok) {

package/src/providers/anthropic.ts

@@ -654,17 +654,6 @@ function convertContentBlocks(
 	return blocks;
 }
 
-/**
- * Marker phrase that Claude has been observed to hallucinate inside reasoning summaries
- * (e.g. "I don't see any current rewritten thinking or next thinking to process. Could
- * you provide..."). When this substring appears in a streamed thinking block we collapse
- * the entire block to {@link BROKEN_THINKING_REPLACEMENT} and drop the signature so
- * downstream UI/transcripts don't surface the meta-prompt and replay can't re-anchor on
- * the garbled chain.
- */
-const BROKEN_THINKING_MARKER = "rewritten thinking";
-const BROKEN_THINKING_REPLACEMENT = "Thinking...";
-
 export type AnthropicEffort = "low" | "medium" | "high" | "xhigh" | "max";
 export type AnthropicThinkingDisplay = "summarized" | "omitted";
 
@@ -1221,12 +1210,6 @@ export const streamAnthropic: StreamFunction<"anthropic-messages"> = (
 			const requestTimeoutMs =
 				firstEventTimeoutMs !== undefined && firstEventTimeoutMs > 0 ? firstEventTimeoutMs : undefined;
 			const blocks = output.content as Block[];
-			// Recent Claude releases occasionally hallucinate meta-prompts asking the operator
-			// to supply "rewritten thinking" / "next thinking" as reasoning content. The summary
-			// is useless and confuses the UI, so we collapse any thinking block whose stream
-			// contains the marker phrase down to a plain "Thinking..." placeholder and drop the
-			// (now invalid) signature so subsequent turns don't replay the garbled chain.
-			const suppressedThinkingBlocks = new WeakSet<Block>();
 			stream.push({ type: "start", partial: output });
 			// Retry loop for transient errors from the stream.
 			// Provider-level transport/rate-limit failures: only before any streamed content starts.
@@ -1381,14 +1364,7 @@ export const streamAnthropic: StreamFunction<"anthropic-messages"> = (
 								const index = blocks.findIndex(b => b.index === event.index);
 								const block = blocks[index];
 								if (block && block.type === "thinking") {
-									if (suppressedThinkingBlocks.has(block)) continue;
 									block.thinking += event.delta.thinking;
-									if (block.thinking.includes(BROKEN_THINKING_MARKER)) {
-										suppressedThinkingBlocks.add(block);
-										block.thinking = BROKEN_THINKING_REPLACEMENT;
-										block.thinkingSignature = "";
-										continue;
-									}
 									stream.push({
 										type: "thinking_delta",
 										contentIndex: index,
@@ -1412,7 +1388,7 @@ export const streamAnthropic: StreamFunction<"anthropic-messages"> = (
 							} else if (event.delta.type === "signature_delta") {
 								const index = blocks.findIndex(b => b.index === event.index);
 								const block = blocks[index];
-								if (block && block.type === "thinking" && !suppressedThinkingBlocks.has(block)) {
+								if (block && block.type === "thinking") {
 									block.thinkingSignature = block.thinkingSignature || "";
 									block.thinkingSignature += event.delta.signature;
 								}
@@ -1430,14 +1406,6 @@ export const streamAnthropic: StreamFunction<"anthropic-messages"> = (
 										partial: output,
 									});
 								} else if (block.type === "thinking") {
-									if (
-										!suppressedThinkingBlocks.has(block) &&
-										block.thinking.includes(BROKEN_THINKING_MARKER)
-									) {
-										suppressedThinkingBlocks.add(block);
-										block.thinking = BROKEN_THINKING_REPLACEMENT;
-										block.thinkingSignature = "";
-									}
 									stream.push({
 										type: "thinking_end",
 										contentIndex: index,

package/src/providers/cursor.ts

@@ -28,6 +28,7 @@ import type {
 import { normalizeSystemPrompts } from "../utils";
 import { AssistantMessageEventStream } from "../utils/event-stream";
 import { parseStreamingJson } from "../utils/json-parse";
+import { createRequestDebugSession, isRequestDebugEnabled, type RequestDebugResponseLog } from "../utils/request-debug";
 import { formatErrorMessageWithRetryAfter } from "../utils/retry-after";
 import { toolWireSchema } from "../utils/schema/wire";
 import type { McpToolDefinition } from "./cursor/gen/agent_pb";
@@ -331,6 +332,7 @@ export const streamCursor: StreamFunction<"cursor-agent"> = (
 		let h2Client: http2.ClientHttp2Session | null = null;
 		let h2Request: http2.ClientHttp2Stream | null = null;
 		let heartbeatTimer: NodeJS.Timeout | null = null;
+		let debugResponseLogPromise: Promise<RequestDebugResponseLog | undefined> | undefined;
 
 		try {
 			const apiKey = options?.apiKey;
@@ -351,11 +353,10 @@ export const streamCursor: StreamFunction<"cursor-agent"> = (
 			const requestContextTools = buildMcpToolDefinitions(context.tools);
 
 			const baseUrl = model.baseUrl || CURSOR_API_URL;
-			h2Client = http2.connect(baseUrl);
-
-			h2Request = h2Client.request({
+			const requestPath = "/agent.v1.AgentService/Run";
+			const requestHeaders = {
 				":method": "POST",
-				":path": "/agent.v1.AgentService/Run",
+				":path": requestPath,
 				"content-type": "application/connect+proto",
 				"connect-protocol-version": "1",
 				te: "trailers",
@@ -364,7 +365,20 @@ export const streamCursor: StreamFunction<"cursor-agent"> = (
 				"x-cursor-client-version": CURSOR_CLIENT_VERSION,
 				"x-cursor-client-type": "cli",
 				"x-request-id": crypto.randomUUID(),
-			});
+			};
+			const debugSession = isRequestDebugEnabled()
+				? await createRequestDebugSession({
+						protocol: "http2",
+						method: "POST",
+						url: new URL(requestPath, baseUrl).toString(),
+						headers: requestHeaders,
+						bodyBase64: Buffer.from(requestBytes).toString("base64"),
+					})
+				: undefined;
+
+			h2Client = http2.connect(baseUrl);
+
+			h2Request = h2Client.request(requestHeaders);
 
 			stream.push({ type: "start", partial: output });
 
@@ -408,7 +422,19 @@ export const streamCursor: StreamFunction<"cursor-agent"> = (
 
 			let resolveH2: (() => void) | undefined;
 
+			h2Request.on("response", headers => {
+				debugResponseLogPromise = debugSession?.openResponseLog(
+					`HTTP/2 ${headers[":status"] ?? ""}`.trim(),
+					headers,
+				);
+			});
+
 			h2Request.on("data", (chunk: Buffer) => {
+				if (debugResponseLogPromise) {
+					void debugResponseLogPromise.then(log => {
+						log?.write(chunk);
+					});
+				}
 				pendingBuffer = Buffer.concat([pendingBuffer, chunk]);
 
 				while (pendingBuffer.length >= 5) {
@@ -480,29 +506,44 @@ export const streamCursor: StreamFunction<"cursor-agent"> = (
 			await new Promise<void>((resolve, reject) => {
 				resolveH2 = resolve;
 
+				const closeDebugLog = async (): Promise<void> => {
+					const log = await debugResponseLogPromise;
+					await log?.close();
+				};
+
 				h2Request!.on("trailers", trailers => {
 					const status = trailers["grpc-status"];
 					const msg = trailers["grpc-message"];
 					if (status && status !== "0") {
-						reject(new Error(`gRPC error ${status}: ${decodeURIComponent(String(msg || ""))}`));
+						void closeDebugLog().finally(() => {
+							reject(new Error(`gRPC error ${status}: ${decodeURIComponent(String(msg || ""))}`));
+						});
 					}
 				});
 
 				h2Request!.on("end", () => {
 					resolveH2 = undefined;
-					if (endStreamError) {
-						reject(endStreamError);
-						return;
-					}
-					resolve();
+					void closeDebugLog()
+						.then(() => {
+							if (endStreamError) {
+								reject(endStreamError);
+								return;
+							}
+							resolve();
+						})
+						.catch(reject);
 				});
 
-				h2Request!.on("error", reject);
+				h2Request!.on("error", error => {
+					void closeDebugLog().finally(() => reject(error));
+				});
 
 				if (options?.signal) {
 					options.signal.addEventListener("abort", () => {
 						h2Request?.close();
-						reject(new Error("Request was aborted"));
+						void closeDebugLog().finally(() => {
+							reject(new Error("Request was aborted"));
+						});
 					});
 				}
 			});
@@ -557,6 +598,8 @@ export const streamCursor: StreamFunction<"cursor-agent"> = (
 			stream.push({ type: "error", reason: output.stopReason, error: output });
 			stream.end();
 		} finally {
+			const log = await debugResponseLogPromise;
+			await log?.close();
 			if (heartbeatTimer) {
 				clearInterval(heartbeatTimer);
 				heartbeatTimer = null;

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

@@ -54,6 +54,7 @@ import {
 	iterateWithIdleTimeout,
 } from "../utils/idle-iterator";
 import { parseStreamingJson } from "../utils/json-parse";
+import { createRequestDebugSession, isRequestDebugEnabled, type RequestDebugResponseLog } from "../utils/request-debug";
 import { adaptSchemaForStrict, NO_STRICT, sanitizeSchemaForOpenAIResponses, toolWireSchema } from "../utils/schema";
 import { notifyRawSseEvent } from "../utils/sse-debug";
 import { compactGrammarDefinition } from "./grammar";
@@ -2046,6 +2047,8 @@ class CodexWebSocketConnection {
 	#streamObserver?: (event: RawSseEvent) => void;
 	#heartbeatInterval: NodeJS.Timeout | undefined;
 	#removePongListener?: () => void;
+	#handshakeHeaders?: Headers;
+	#debugResponseLog?: RequestDebugResponseLog;
 	/**
 	 * Wall-clock of the most recent inbound activity on this socket — any
 	 * decoded message, any pong, or the moment the handshake completed. Used
@@ -2189,6 +2192,7 @@ class CodexWebSocketConnection {
 			// the liveness clock — what matters for reuse health is that the upstream
 			// is still talking to us, not that every frame is well-formed.
 			this.#lastInboundAt = Date.now();
+			this.#writeDebugWebSocketFrame(event.data);
 			try {
 				const text = typeof event.data === "string" ? event.data : Buffer.from(event.data).toString("utf-8");
 				if (!text) return;
@@ -2256,6 +2260,19 @@ class CodexWebSocketConnection {
 		}
 
 		try {
+			const debugSession = isRequestDebugEnabled()
+				? await createRequestDebugSession({
+						protocol: "websocket",
+						method: "POST",
+						url: this.#url,
+						headers: this.#headers,
+						body: request,
+					})
+				: undefined;
+			this.#debugResponseLog = debugSession
+				? await debugSession.openResponseLog("WebSocket 101 Switching Protocols", this.#handshakeHeaders)
+				: undefined;
+
 			const requestPayload = JSON.stringify(request);
 			notifyCodexWebSocketOutbound(onSseEvent, request, requestPayload);
 			try {
@@ -2336,14 +2353,35 @@ class CodexWebSocketConnection {
 			if (signal) {
 				signal.removeEventListener("abort", onAbort);
 			}
+			const debugResponseLog = this.#debugResponseLog;
+			this.#debugResponseLog = undefined;
+			await debugResponseLog?.close();
 		}
 	}
 
 	#captureHandshakeHeaders(socket: Bun.WebSocket, openEvent?: Event): void {
-		if (!this.#onHandshakeHeaders) return;
 		const headers = extractCodexWebSocketHandshakeHeaders(socket, openEvent);
 		if (!headers) return;
-		this.#onHandshakeHeaders(headers);
+		this.#handshakeHeaders = headers;
+		this.#onHandshakeHeaders?.(headers);
+	}
+
+	#writeDebugWebSocketFrame(data: unknown): void {
+		const log = this.#debugResponseLog;
+		if (!log) return;
+		if (typeof data === "string") {
+			log.write(data);
+			return;
+		}
+		if (data instanceof Uint8Array) {
+			log.write(data);
+			return;
+		}
+		if (data instanceof ArrayBuffer) {
+			log.write(new Uint8Array(data));
+			return;
+		}
+		log.write(String(data));
 	}
 
 	#startHeartbeat(socket: Bun.WebSocket): void {

package/src/providers/openai-completions-compat.ts

@@ -208,6 +208,11 @@ export function detectOpenAICompat(model: Model<"openai-completions">, resolvedB
 		requiresAssistantAfterToolResult: false,
 		requiresThinkingAsText: isMistral,
 		requiresMistralToolIds: isMistral,
+		// Only Kimi's native hosts (Moonshot / Kimi-code, matched by `isMoonshotKimi`)
+		// speak the z.ai binary `thinking: { type }` field. Kimi reached through
+		// OpenAI-compatible proxies — Fireworks' Fire Pass router, OpenCode's gateway,
+		// etc. — drives reasoning via OpenAI-style `reasoning_effort`
+		// (low|medium|high|xhigh|max|none), so those stay on the "openai" path.
 		thinkingFormat:
 			isZai || isZhipu || isMoonshotKimi
 				? "zai"

package/src/providers/openai-completions.ts

@@ -1341,29 +1341,56 @@ export function parseChunkUsage(
 	const completionTokenDetails = getOptionalObjectProperty(rawUsage, "completion_tokens_details");
 	const cachedTokens =
 		getOptionalNumberProperty(rawUsage, "cached_tokens") ??
+		getOptionalNumberProperty(rawUsage, "prompt_cache_hit_tokens") ??
 		(promptTokenDetails ? getOptionalNumberProperty(promptTokenDetails, "cached_tokens") : undefined) ??
 		0;
 	// OpenRouter exposes cache writes via `prompt_tokens_details.cache_write_tokens`
-	// and INCLUDES them in `prompt_tokens`. Without subtracting, cache-write tokens
-	// leak into `input` (e.g. GLM/Anthropic via OpenRouter on a fresh cache).
+	// and INCLUDES them in `prompt_tokens` — they are billed on top of the input, so
+	// we subtract them to get the real billed input.
+	// DeepSeek exposes cache hit/miss via `prompt_cache_hit_tokens` /
+	// `prompt_cache_miss_tokens` at the top level where `prompt_tokens` equals their
+	// sum. The miss portion IS the billed input — we must NOT subtract it.
 	// Ref: https://openrouter.ai/docs/guides/best-practices/prompt-caching
-	const cacheWriteTokens = promptTokenDetails
-		? (getOptionalNumberProperty(promptTokenDetails, "cache_write_tokens") ?? 0)
-		: 0;
+	// Ref: https://api-docs.deepseek.com/api/create-chat-completion
+	//
+	// Resolve cacheWrite from both possible sources separately.
+	// They have different billing semantics: OpenRouter's cache_write is billed
+	// on top of prompt_tokens, while DeepSeek's miss IS the billed input.
+	const cacheWriteOpenRouter = promptTokenDetails
+		? getOptionalNumberProperty(promptTokenDetails, "cache_write_tokens")
+		: undefined;
+	const cacheWriteDeepSeek = getOptionalNumberProperty(rawUsage, "prompt_cache_miss_tokens");
+	// Prefer OpenRouter's value for the input subtraction; fall back to DeepSeek.
+	const cacheWriteTokens = cacheWriteOpenRouter ?? cacheWriteDeepSeek ?? 0;
+
 	const reasoningTokens =
 		(completionTokenDetails ? getOptionalNumberProperty(completionTokenDetails, "reasoning_tokens") : undefined) ?? 0;
 	const promptTokens = getOptionalNumberProperty(rawUsage, "prompt_tokens") ?? 0;
-	const input = Math.max(0, promptTokens - cachedTokens - cacheWriteTokens);
+
+	const isDeepSeekNative =
+		getOptionalNumberProperty(rawUsage, "prompt_cache_hit_tokens") !== undefined && cacheWriteDeepSeek !== undefined;
+	// Only use the DeepSeek input path when cacheWrite came from DeepSeek's
+	// miss field, not from prompt_tokens_details. Avoids false positives when
+	// DeepSeek models route through OpenRouter (which may pass through native
+	// fields alongside its own cache_write_tokens).
+	const isDeepSeekUsage = isDeepSeekNative && cacheWriteOpenRouter === undefined && cacheWriteDeepSeek > 0;
+	const input = isDeepSeekUsage
+		? Math.max(0, promptTokens - cachedTokens)
+		: Math.max(0, promptTokens - cachedTokens - cacheWriteTokens);
 	// Per OpenAI's CompletionUsage spec, `reasoning_tokens` is a subset of
 	// `completion_tokens` (which is the total billed output). Adding them would
 	// double-count.
 	const outputTokens = getOptionalNumberProperty(rawUsage, "completion_tokens") ?? 0;
+	// DeepSeek only exposes cache hit/miss (no cache-write data).
+	// Emitting miss tokens as cacheWrite would make downstream consumers
+	// double-count them (input already equals miss for DeepSeek).
+	const emittedCacheWrite = isDeepSeekUsage ? 0 : cacheWriteTokens;
 	const usage: AssistantMessage["usage"] = {
 		input,
 		output: outputTokens,
 		cacheRead: cachedTokens,
-		cacheWrite: cacheWriteTokens,
-		totalTokens: input + outputTokens + cachedTokens + cacheWriteTokens,
+		cacheWrite: emittedCacheWrite,
+		totalTokens: input + outputTokens + cachedTokens + emittedCacheWrite,
 		...(reasoningTokens > 0 ? { reasoningTokens } : {}),
 		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
 		...(premiumRequests !== undefined ? { premiumRequests } : {}),

package/src/stream.ts

@@ -61,6 +61,7 @@ import type {
 } from "./types";
 import { AssistantMessageEventStream } from "./utils/event-stream";
 import { isFoundryEnabled } from "./utils/foundry";
+import { withRequestDebugFetch } from "./utils/request-debug";
 
 let cachedVertexAdcCredentialsExists: boolean | null = null;
 
@@ -295,42 +296,50 @@ export function stream<TApi extends Api>(
 	context: Context,
 	options?: OptionsForApi<TApi>,
 ): AssistantMessageEventStream {
+	const requestOptions = withRequestDebugFetch(options as StreamOptions | undefined) as
+		| OptionsForApi<TApi>
+		| undefined;
+
 	// Check custom API registry first (extension-provided APIs like "vertex-claude-api")
 	const customApiProvider = getCustomApi(model.api);
 	if (customApiProvider) {
-		return customApiProvider.stream(model, context, options as StreamOptions);
+		return customApiProvider.stream(model, context, requestOptions as StreamOptions);
 	}
 
 	if (isGitLabDuoModel(model)) {
-		const apiKey = (options as StreamOptions | undefined)?.apiKey || getEnvApiKey(model.provider);
+		const apiKey = (requestOptions as StreamOptions | undefined)?.apiKey || getEnvApiKey(model.provider);
 		if (!apiKey) {
 			throw new Error(`No API key for provider: ${model.provider}`);
 		}
 		return streamGitLabDuo(model, context, {
-			...(options as SimpleStreamOptions | undefined),
+			...(requestOptions as SimpleStreamOptions | undefined),
 			apiKey,
 		});
 	}
 
 	// Vertex AI uses Application Default Credentials, not API keys
 	if (model.api === "google-vertex") {
-		return streamGoogleVertex(model as Model<"google-vertex">, context, options as GoogleVertexOptions);
+		return streamGoogleVertex(model as Model<"google-vertex">, context, requestOptions as GoogleVertexOptions);
 	} else if (model.api === "bedrock-converse-stream") {
 		// Bedrock doesn't have any API keys instead it sources credentials from standard AWS env variables or from given AWS profile.
-		return streamBedrock(model as Model<"bedrock-converse-stream">, context, (options || {}) as BedrockOptions);
+		return streamBedrock(
+			model as Model<"bedrock-converse-stream">,
+			context,
+			(requestOptions || {}) as BedrockOptions,
+		);
 	}
 
-	const apiKey = options?.apiKey || getEnvApiKey(model.provider);
+	const apiKey = requestOptions?.apiKey || getEnvApiKey(model.provider);
 	if (!apiKey) {
 		throw new Error(`No API key for provider: ${model.provider}`);
 	}
 	const providerOptions = isGoogleVertexAuthenticatedModel(model)
 		? {
-				...options,
+				...requestOptions,
 				apiKey: "vertex-adc",
-				fetch: createVertexAuthenticatedFetch(options as StreamOptions | undefined),
+				fetch: createVertexAuthenticatedFetch(requestOptions as StreamOptions | undefined),
 			}
-		: { ...options, apiKey };
+		: { ...requestOptions, apiKey };
 
 	const api: Api = model.api;
 	switch (api) {
@@ -430,10 +439,13 @@ export function streamSimple<TApi extends Api>(
 	context: Context,
 	options?: SimpleStreamOptions,
 ): AssistantMessageEventStream {
-	const retryApiKey = options?.onAuthError ? (options.apiKey ?? getEnvApiKey(model.provider)) : undefined;
+	const requestOptions = withRequestDebugFetch(options);
+	const retryApiKey = requestOptions?.onAuthError
+		? (requestOptions.apiKey ?? getEnvApiKey(model.provider))
+		: undefined;
 	if (retryApiKey) {
 		const outer = new AssistantMessageEventStream();
-		const onAuthError = options!.onAuthError!;
+		const onAuthError = requestOptions!.onAuthError!;
 		const runAttempt = async (apiKey: string, captureAuthFailure: boolean): Promise<AuthRetryFailure | undefined> => {
 			const bufferedEvents: AssistantMessageEvent[] = [];
 			let emittedReplayUnsafeEvent = false;
@@ -443,7 +455,7 @@ export function streamSimple<TApi extends Api>(
 			};
 
 			try {
-				const inner = streamSimple(model, context, { ...options, apiKey, onAuthError: undefined });
+				const inner = streamSimple(model, context, { ...requestOptions, apiKey, onAuthError: undefined });
 				for await (const event of inner) {
 					if (!emittedReplayUnsafeEvent && event.type === "start") {
 						bufferedEvents.push(event);
@@ -519,26 +531,26 @@ export function streamSimple<TApi extends Api>(
 	// extension-registered APIs can't accidentally override a configured
 	// pi-native transport.
 	if (model.transport === "pi-native") {
-		return streamPiNative(model, context, options);
+		return streamPiNative(model, context, requestOptions);
 	}
 
 	// Check custom API registry (extension-provided APIs)
 	const customApiProvider = getCustomApi(model.api);
 	if (customApiProvider) {
-		return customApiProvider.streamSimple(model, context, options);
+		return customApiProvider.streamSimple(model, context, requestOptions);
 	}
 
 	// Vertex AI uses Application Default Credentials, not API keys
 	if (model.api === "google-vertex") {
-		const providerOptions = mapOptionsForApi(model, options, undefined);
+		const providerOptions = mapOptionsForApi(model, requestOptions, undefined);
 		return stream(model, context, providerOptions);
 	} else if (model.api === "bedrock-converse-stream") {
 		// Bedrock doesn't have any API keys instead it sources credentials from standard AWS env variables or from given AWS profile.
-		const providerOptions = mapOptionsForApi(model, options, undefined);
+		const providerOptions = mapOptionsForApi(model, requestOptions, undefined);
 		return stream(model, context, providerOptions);
 	}
 
-	const apiKey = options?.apiKey || getEnvApiKey(model.provider);
+	const apiKey = requestOptions?.apiKey || getEnvApiKey(model.provider);
 	if (!apiKey) {
 		throw new Error(`No API key for provider: ${model.provider}`);
 	}
@@ -546,7 +558,7 @@ export function streamSimple<TApi extends Api>(
 	// GitLab Duo - wraps Anthropic/OpenAI behind GitLab AI Gateway direct access tokens
 	if (isGitLabDuoModel(model)) {
 		return streamGitLabDuo(model, context, {
-			...options,
+			...requestOptions,
 			apiKey,
 		});
 	}
@@ -555,9 +567,9 @@ export function streamSimple<TApi extends Api>(
 	if (isKimiModel(model)) {
 		// Pass raw SimpleStreamOptions - streamKimi handles mapping internally
 		return streamKimi(model as Model<"openai-completions">, context, {
-			...options,
+			...requestOptions,
 			apiKey,
-			format: options?.kimiApiFormat ?? "anthropic",
+			format: requestOptions?.kimiApiFormat ?? "anthropic",
 		});
 	}
 
@@ -565,13 +577,12 @@ export function streamSimple<TApi extends Api>(
 	if (isSyntheticModel(model)) {
 		// Pass raw SimpleStreamOptions - streamSynthetic handles mapping internally
 		return streamSynthetic(model as Model<"openai-completions">, context, {
-			...options,
+			...requestOptions,
 			apiKey,
-			format: options?.syntheticApiFormat ?? "openai", // Default to OpenAI format
+			format: requestOptions?.syntheticApiFormat ?? "openai", // Default to OpenAI format
 		});
 	}
-
-	const providerOptions = mapOptionsForApi(model, options, apiKey);
+	const providerOptions = mapOptionsForApi(model, requestOptions, apiKey);
 	return stream(model, context, providerOptions);
 }
 
@@ -716,6 +727,7 @@ function mapOptionsForApi<TApi extends Api>(
 		onResponse: options?.onResponse,
 		onSseEvent: options?.onSseEvent,
 		execHandlers: options?.execHandlers,
+		fetch: options?.fetch,
 	};
 
 	switch (model.api) {

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("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;
+}
+
+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";
+}