@copilotkit/aimock 1.32.0 → 1.33.0

package/dist/recorder.js

@@ -1,6 +1,6 @@
 import { DEFAULT_TEST_ID } from "./constants.js";
 import { normalizeModelName } from "./model-utils.js";
-import { getTestId, slugifyTestId } from "./helpers.js";
+import { getTestId, slugifyContext, slugifyTestId } from "./helpers.js";
 import { getLastMessageByRole, getTextContent } from "./router.js";
 import { writeErrorResponse } from "./sse-writer.js";
 import { capturedRedactedData, collapseStreamingResponse } from "./stream-collapse.js";
@@ -14,6 +14,52 @@ import { StringDecoder } from "node:string_decoder";
 
 //#region src/recorder.ts
 /** Headers to strip when proxying — hop-by-hop (RFC 2616 §13.5.1) + client-set. */
+/**
+* Default ceiling (bytes) for the in-memory proxy-path buffer. Chosen well
+* under V8's ~512 MiB max string length so `rawBuffer.toString()` /
+* stream-collapse never throws `RangeError: Invalid string length`, and so a
+* single huge proxied response cannot spike the heap unbounded. Overridable
+* via `RecordConfig.maxProxyBufferBytes` / `--max-proxy-buffer-bytes`.
+*/
+const DEFAULT_MAX_PROXY_BUFFER_BYTES = 64 * 1024 * 1024;
+/**
+* Default ceiling for the number of SSE/NDJSON/EventStream frames whose
+* per-frame state (`frameTimestamps`, parse buffers) aimock retains for a
+* single proxied response. Frame state is count-indexed, not byte-sized, so a
+* long-lived / never-ending stream accumulates `frameTimestamps` entries (and,
+* if a frame never completes, parse-buffer bytes) UNBOUNDED even when the byte
+* cap is generous — observed as multi-GB heap growth over many hours from a few
+* long nested-sub-agent streams. Tripping truncation on EITHER bytes OR frame
+* count bounds both. 5M frames is generous for any real response (a normal
+* completion is hundreds-to-thousands of frames) while still bounding a runaway
+* stream to ~tens of MB of frame state. Overridable via
+* `RecordConfig.maxProxyBufferFrames` / `--max-proxy-buffer-frames`.
+*/
+const DEFAULT_MAX_PROXY_BUFFER_FRAMES = 5e6;
+/**
+* Absolute hard ceiling (bytes) for any in-memory proxy buffer, independent of
+* the configurable `maxProxyBufferBytes`. V8's maximum STRING length on 64-bit
+* is 2^29 - 1 (~512 MiB of UTF-16 code units), and the proxy buffer is
+* eventually stringified via `rawBuffer.toString()` for collapse/relay — so the
+* BYTE buffer must stay safely under that string limit or the toString throws
+* `RangeError: Invalid string length`. 256 MiB of bytes is well under the
+* ~512 MiB string-length boundary (these are different units — bytes vs UTF-16
+* code units — but 256 MiB of bytes can never decode to more than 256 Mi code
+* units, comfortably below 2^29 - 1). Used to clamp the configurable cap AND to
+* bound the non-progressive relay buffer that must be retained past a cap trip.
+*/
+const PROXY_BUFFER_HARD_CEILING = 256 * 1024 * 1024;
+/**
+* Test-only override of the effective hard ceiling. Lets the proxy-buffer
+* enforcement suite exercise the >hard-ceiling fail-loud path with a small
+* body instead of streaming 256 MiB. `undefined` (the default) uses the real
+* `PROXY_BUFFER_HARD_CEILING`. NEVER set from production code.
+*/
+let proxyBufferHardCeilingOverride;
+/** Effective hard ceiling, honoring any active test-only override. */
+function effectiveHardCeiling() {
+	return proxyBufferHardCeilingOverride ?? PROXY_BUFFER_HARD_CEILING;
+}
 const STRIP_HEADERS = new Set([
 	"connection",
 	"keep-alive",
@@ -59,6 +105,19 @@ function sanitizeHeaderValue(value) {
 	return value.replace(/[^\t\x20-\x7e\x80-\xff]/g, "?");
 }
 /**
+* Resolve a `content-type` header value to a single string. Node's
+* `http.IncomingHttpHeaders` types `content-type` as `string | string[]`, and
+* a constructed/proxied header object CAN carry an array (e.g. duplicated
+* header lines surfaced by some HTTP stacks). `join(", ")`-ing such an array
+* produces a malformed `Content-Type: application/json, text/html` value — pick
+* the FIRST element instead, which is the value the client should act on.
+* Returns `""` when the header is absent or an empty array.
+*/
+function pickContentType(contentType) {
+	if (Array.isArray(contentType)) return contentType.length > 0 ? contentType[0] : "";
+	return contentType ?? "";
+}
+/**
 * Write a built fixture to disk (snapshot vs. timestamp file layout) and, when
 * the match is non-empty, register it in the in-memory cache so subsequent
 * identical requests match. Extracted from `proxyAndRecord` so the fal
@@ -91,7 +150,8 @@ function persistFixture(opts) {
 		}
 	} else {
 		const timestampFile = `${providerKey}-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}-${crypto$1.randomUUID().slice(0, 8)}.json`;
-		filepath = fixture.match.context ? path.join(fixturePath, fixture.match.context, timestampFile) : path.join(fixturePath, timestampFile);
+		const contextSegment = fixture.match.context ? slugifyContext(fixture.match.context) : void 0;
+		filepath = contextSegment ? path.join(fixturePath, contextSegment, timestampFile) : path.join(fixturePath, timestampFile);
 	}
 	const fileWarnings = [...isEmptyMatch ? ["Empty match criteria — this fixture will not match any request"] : [], ...warnings];
 	try {
@@ -102,14 +162,19 @@ function persistFixture(opts) {
 			const existingFixtures = Array.isArray(existing.fixtures) ? existing.fixtures : void 0;
 			if (existingFixtures === void 0 && existing.fixtures !== void 0) logger.warn(`Existing fixture file ${filepath} has a non-array "fixtures" — discarding it and starting fresh`);
 			fileContent = { fixtures: [...existingFixtures ?? [], fixture] };
-			if (typeof existing._warning === "string" && existing._warning) fileWarnings.unshift(...existing._warning.split("; "));
+			if (Array.isArray(existing._warnings)) fileWarnings.unshift(...existing._warnings.filter((w) => typeof w === "string"));
+			else if (typeof existing._warning === "string" && existing._warning) fileWarnings.unshift(...existing._warning.split("; "));
 		} catch (mergeErr) {
 			const msg = mergeErr instanceof Error ? mergeErr.message : "unknown";
 			logger.warn(`Could not read existing fixture file ${filepath} (${msg}) — overwriting`);
 			fileContent = { fixtures: [fixture] };
 		}
 		else fileContent = { fixtures: [fixture] };
-		if (fileWarnings.length > 0) fileContent._warning = [...new Set(fileWarnings)].join("; ");
+		if (fileWarnings.length > 0) {
+			const dedupedWarnings = [...new Set(fileWarnings)];
+			fileContent._warnings = dedupedWarnings;
+			fileContent._warning = dedupedWarnings.join("; ");
+		}
 		const tmpPath = filepath + ".tmp." + process.pid;
 		fs.writeFileSync(tmpPath, JSON.stringify(fileContent, null, 2), "utf-8");
 		fs.renameSync(tmpPath, filepath);
@@ -160,15 +225,21 @@ async function proxyAndRecord(req, res, request, providerKey, pathname, fixtures
 	let upstreamHeaders;
 	let upstreamBody;
 	let rawBuffer;
+	let bufferTruncated = false;
+	let truncationCap;
+	let totalBytes = 0;
+	let hardCeilingExceeded = false;
 	let streamedToClient = false;
 	let clientDisconnected = false;
 	let frameTimestamps = [];
 	let streamStartTime = 0;
+	const maxProxyBufferBytes = clampMaxBufferBytes(record.maxProxyBufferBytes);
+	const maxProxyBufferFrames = clampMaxBufferFrames(record.maxProxyBufferFrames);
 	try {
 		const result = await makeUpstreamRequest(target, forwardHeaders, requestBody, res, req.method, defaults.logger, {
 			upstreamTimeoutMs: record.upstreamTimeoutMs,
 			bodyTimeoutMs: record.bodyTimeoutMs
-		});
+		}, maxProxyBufferBytes, maxProxyBufferFrames);
 		upstreamStatus = result.status;
 		upstreamHeaders = result.headers;
 		upstreamBody = result.body;
@@ -177,6 +248,10 @@ async function proxyAndRecord(req, res, request, providerKey, pathname, fixtures
 		clientDisconnected = result.clientDisconnected;
 		frameTimestamps = result.frameTimestamps;
 		streamStartTime = result.streamStartTime;
+		bufferTruncated = result.bufferTruncated;
+		truncationCap = result.truncationCap;
+		totalBytes = result.totalBytes;
+		hardCeilingExceeded = result.hardCeilingExceeded;
 	} catch (err) {
 		const msg = err instanceof Error ? err.message : "Unknown proxy error";
 		defaults.logger.error(`Proxy request failed: ${msg}`);
@@ -186,16 +261,40 @@ async function proxyAndRecord(req, res, request, providerKey, pathname, fixtures
 				message: `Proxy to upstream failed: ${msg}`,
 				type: "proxy_error"
 			} }));
-		} else res.end();
+		} else res.destroy();
+		return "relayed";
+	}
+	if (bufferTruncated) {
+		const capDetail = truncationCap === "frame" ? `the ${maxProxyBufferFrames}-frame cap` : `the ${maxProxyBufferBytes}-byte cap`;
+		if (!streamedToClient && hardCeilingExceeded && !res.headersSent) {
+			const ceilingMiB = Math.round(PROXY_BUFFER_HARD_CEILING / (1024 * 1024));
+			defaults.logger.error(`Upstream response exceeded the ${ceilingMiB} MiB proxy hard ceiling (saw ${totalBytes} bytes) on a non-progressive body — cannot relay the full body and refusing to relay a truncated one; returning 502`);
+			res.writeHead(502, { "Content-Type": "application/json" });
+			res.end(JSON.stringify({ error: {
+				message: `Upstream response exceeds ${ceilingMiB}MiB proxy ceiling`,
+				type: "proxy_error"
+			} }));
+			return "relayed";
+		}
+		defaults.logger.warn(`Upstream response exceeded ${capDetail} (saw ${totalBytes} bytes) — relayed to client, recording skipped`);
+		if (!streamedToClient && !res.headersSent) {
+			const clientStatus = upstreamStatus >= 200 && upstreamStatus < 300 ? 200 : 502;
+			const relayHeaders = {};
+			const ct = upstreamHeaders["content-type"];
+			relayHeaders["Content-Type"] = (Array.isArray(ct) ? ct.join(", ") : ct ?? "") || "application/json";
+			res.writeHead(clientStatus, relayHeaders);
+			res.end(rawBuffer);
+		} else if (!res.writableEnded) res.end();
 		return "relayed";
 	}
 	const contentType = upstreamHeaders["content-type"];
-	const ctString = Array.isArray(contentType) ? contentType.join(", ") : contentType ?? "";
+	const ctString = pickContentType(contentType);
 	const isBinaryStream = ctString.toLowerCase().includes("application/vnd.amazon.eventstream");
 	const collapsed = collapseStreamingResponse(ctString, providerKey, isBinaryStream ? rawBuffer : upstreamBody, defaults.logger);
 	let fixtureResponse;
-	if (ctString.toLowerCase().startsWith("audio/") && rawBuffer.length > 0) {
+	if (ctString.toLowerCase().startsWith("audio/") && upstreamStatus >= 200 && upstreamStatus < 300) {
 		const audioFormat = ctString.toLowerCase().replace("audio/", "").replace("mpeg", "mp3").split(";")[0].trim();
+		if (rawBuffer.length === 0) defaults.logger.warn("Audio response had a zero-length body — recording an empty audio fixture");
 		fixtureResponse = {
 			audio: rawBuffer.toString("base64"),
 			...audioFormat && audioFormat !== "mp3" ? { format: audioFormat } : {}
@@ -295,15 +394,7 @@ async function proxyAndRecord(req, res, request, providerKey, pathname, fixtures
 				json: parsedResponse,
 				status: upstreamStatus
 			};
-		} else {
-			let encodingFormat;
-			try {
-				encodingFormat = rawBody ? JSON.parse(rawBody).encoding_format : void 0;
-			} catch (err) {
-				defaults.logger.debug(`Could not parse encoding_format from raw body: ${err instanceof Error ? err.message : "unknown error"}`);
-			}
-			fixtureResponse = buildFixtureResponse(parsedResponse, upstreamStatus, encodingFormat, defaults.logger);
-		}
+		} else fixtureResponse = buildFixtureResponse(parsedResponse, upstreamStatus, defaults.logger);
 	}
 	if (clientDisconnected) {
 		defaults.logger.warn("Client disconnected mid-stream — skipping fixture save to avoid truncated data");
@@ -404,11 +495,31 @@ function clampTimeout(value, fallback) {
 	if (value == null || !Number.isFinite(value) || value <= 0) return fallback;
 	return value;
 }
-function makeUpstreamRequest(target, headers, body, clientRes, method = "POST", logger, timeouts) {
+/**
+* Sanitize the configured proxy-buffer cap: non-finite or non-positive values
+* fall back to the default. Also hard-clamps to just under V8's max string
+* length so a misconfigured large value can never permit an over-string-limit
+* buffer to reach `.toString()`.
+*/
+function clampMaxBufferBytes(value) {
+	if (value == null || !Number.isFinite(value) || value <= 0) return DEFAULT_MAX_PROXY_BUFFER_BYTES;
+	return Math.min(value, PROXY_BUFFER_HARD_CEILING);
+}
+/**
+* Sanitize the configured proxy-buffer frame cap: non-finite or non-positive
+* values fall back to the default. Bounds the count-indexed per-frame state
+* (`frameTimestamps` + parse buffers) that the byte cap cannot bound on its own.
+*/
+function clampMaxBufferFrames(value) {
+	if (value == null || !Number.isFinite(value) || value <= 0) return DEFAULT_MAX_PROXY_BUFFER_FRAMES;
+	return Math.floor(value);
+}
+function makeUpstreamRequest(target, headers, body, clientRes, method = "POST", logger, timeouts, maxBufferBytes = DEFAULT_MAX_PROXY_BUFFER_BYTES, maxBufferFrames = DEFAULT_MAX_PROXY_BUFFER_FRAMES) {
 	return new Promise((resolve, reject) => {
 		const transport = target.protocol === "https:" ? https : http$1;
 		const UPSTREAM_TIMEOUT_MS = clampTimeout(timeouts?.upstreamTimeoutMs, 3e4);
 		const BODY_TIMEOUT_MS = clampTimeout(timeouts?.bodyTimeoutMs, 3e4);
+		let requestSendTime = 0;
 		const req = transport.request(target, {
 			method,
 			timeout: UPSTREAM_TIMEOUT_MS,
@@ -421,14 +532,14 @@ function makeUpstreamRequest(target, headers, body, clientRes, method = "POST",
 				req.destroy(/* @__PURE__ */ new Error(`Upstream response timed out after ${BODY_TIMEOUT_MS / 1e3}s`));
 			});
 			const ct = res.headers["content-type"];
-			const ctStr = Array.isArray(ct) ? ct.join(", ") : ct ?? "";
+			const ctStr = pickContentType(ct);
 			const ctLower = ctStr.toLowerCase();
 			const isSSE = ctLower.includes("text/event-stream");
 			const isNDJSON = ctLower.includes("application/x-ndjson");
 			const isBinaryEventStream = ctLower.includes("application/vnd.amazon.eventstream");
 			const isProgressiveStream = isSSE || isNDJSON || isBinaryEventStream;
 			const frameTimestamps = [];
-			const streamStartTime = Date.now();
+			const streamStartTime = requestSendTime || Date.now();
 			let frameBuffer = "";
 			const frameDecoder = new StreamingFrameDecoder();
 			let binaryFrameBuffer = Buffer.alloc(0);
@@ -450,22 +561,75 @@ function makeUpstreamRequest(target, headers, body, clientRes, method = "POST",
 					if (!clientRes.writableFinished) {
 						clientDisconnected = true;
 						req.destroy();
+						res.removeListener("data", onUpstreamData);
+						chunks.length = 0;
+						bufferedBytes = 0;
+						frameTimestamps.length = 0;
+						frameBuffer = "";
+						binaryFrameBuffer = Buffer.alloc(0);
 					}
 				});
 			}
 			const chunks = [];
-			res.on("data", (chunk) => {
-				chunks.push(chunk);
-				if (isSSE || isNDJSON) {
+			let bufferedBytes = 0;
+			let totalBytes = 0;
+			let bufferTruncated = false;
+			/** Which cap tripped truncation — surfaced to the caller for an accurate warning. */
+			let truncationCap;
+			const hardCeiling = effectiveHardCeiling();
+			/**
+			* True when a NON-progressive upstream body exceeded `hardCeiling`, so
+			* the buffered `rawBuffer` is a PARTIAL copy that must NOT be relayed as
+			* success. Distinct from `bufferTruncated` (which also covers the
+			* under-ceiling over-soft-cap case where the full body IS retained).
+			*/
+			let hardCeilingExceeded = false;
+			const tripTruncation = (cap) => {
+				bufferTruncated = true;
+				truncationCap = cap;
+				frameTimestamps.length = 0;
+				frameBuffer = "";
+				frameDecoder.end();
+				binaryFrameBuffer = Buffer.alloc(0);
+				if (isProgressiveStream) {
+					chunks.length = 0;
+					bufferedBytes = 0;
+				}
+				const detail = cap === "byte" ? `byte cap (${maxBufferBytes} bytes)` : `frame cap (${maxBufferFrames} frames)`;
+				logger?.warn(`Upstream response exceeded the proxy buffer ${detail} — relaying full body to client, but skipping in-memory collapse/recording to bound memory`);
+			};
+			const onUpstreamData = (chunk) => {
+				totalBytes += chunk.length;
+				if (!bufferTruncated && bufferedBytes + chunk.length > maxBufferBytes) tripTruncation("byte");
+				else if (!bufferTruncated && frameTimestamps.length >= maxBufferFrames) tripTruncation("frame");
+				if (!bufferTruncated) {
+					chunks.push(chunk);
+					bufferedBytes += chunk.length;
+				} else if (!isProgressiveStream) if (bufferedBytes + chunk.length <= hardCeiling) {
+					chunks.push(chunk);
+					bufferedBytes += chunk.length;
+				} else hardCeilingExceeded = true;
+				if (!bufferTruncated && (isSSE || isNDJSON)) {
 					frameBuffer += frameDecoder.write(chunk);
 					const delimiter = isNDJSON ? /\r?\n/ : /\r?\n\r?\n/;
 					const parts = frameBuffer.split(delimiter);
-					for (let fi = 0; fi < parts.length - 1; fi++) if (parts[fi].trim().length > 0) frameTimestamps.push(Date.now());
-					frameBuffer = parts[parts.length - 1];
+					for (let fi = 0; fi < parts.length - 1; fi++) {
+						if (frameTimestamps.length >= maxBufferFrames) {
+							tripTruncation("frame");
+							break;
+						}
+						if (parts[fi].trim().length > 0) frameTimestamps.push(Date.now());
+					}
+					if (!bufferTruncated) frameBuffer = parts[parts.length - 1];
 				}
-				if (isBinaryEventStream) {
+				if (!bufferTruncated && isBinaryEventStream) if (bufferedBytes + binaryFrameBuffer.length > maxBufferBytes) tripTruncation("byte");
+				else {
 					binaryFrameBuffer = Buffer.concat([binaryFrameBuffer, chunk]);
 					while (binaryFrameBuffer.length >= 4) {
+						if (frameTimestamps.length >= maxBufferFrames) {
+							tripTruncation("frame");
+							break;
+						}
 						const totalLen = binaryFrameBuffer.readUInt32BE(0);
 						if (totalLen < 12 || binaryFrameBuffer.length < totalLen) break;
 						frameTimestamps.push(Date.now());
@@ -478,11 +642,12 @@ function makeUpstreamRequest(target, headers, body, clientRes, method = "POST",
 					logger?.debug(`Failed to relay chunk to client: ${writeErr instanceof Error ? writeErr.message : "unknown"}`);
 					clientDisconnected = true;
 				}
-			});
+			};
+			res.on("data", onUpstreamData);
 			res.on("error", reject);
 			res.on("end", () => {
 				if (res.socket) res.setTimeout(0);
-				if (isSSE || isNDJSON) {
+				if (!bufferTruncated && (isSSE || isNDJSON)) {
 					frameBuffer += frameDecoder.end();
 					if (frameBuffer.trim().length > 0) frameTimestamps.push(Date.now());
 				}
@@ -492,15 +657,20 @@ function makeUpstreamRequest(target, headers, body, clientRes, method = "POST",
 				} catch (endErr) {
 					logger?.debug(`Failed to end client response: ${endErr instanceof Error ? endErr.message : "unknown"}`);
 				}
+				const bodyString = !bufferTruncated || bufferTruncated && !streamedToClient ? rawBuffer.toString() : "";
 				resolve({
 					status: res.statusCode ?? 500,
 					headers: res.headers,
-					body: rawBuffer.toString(),
+					body: bodyString,
 					rawBuffer,
 					streamedToClient,
 					clientDisconnected,
 					frameTimestamps,
-					streamStartTime
+					streamStartTime,
+					bufferTruncated,
+					truncationCap,
+					totalBytes,
+					hardCeilingExceeded
 				});
 			});
 		});
@@ -508,6 +678,7 @@ function makeUpstreamRequest(target, headers, body, clientRes, method = "POST",
 			req.destroy(/* @__PURE__ */ new Error(`Upstream request timed out after ${UPSTREAM_TIMEOUT_MS / 1e3}s: ${target.href}`));
 		});
 		req.on("error", reject);
+		requestSendTime = Date.now();
 		req.write(body);
 		req.end();
 	});
@@ -522,10 +693,23 @@ function logDroppedReasoningSignature(logger, reasoning, reasoningSignature) {
 	if (reasoningSignature && !reasoning) logger?.warn("Dropping captured reasoningSignature — no plaintext reasoning to attach it to");
 }
 /**
+* Coerce a tool call's `arguments` field into the string the fixture contract
+* requires (types.ts `ToolCall.arguments: string`). When the upstream omits the
+* arguments field entirely, `JSON.stringify(undefined)` yields the JS value
+* `undefined` (not a string), which then gets dropped on disk-write and breaks
+* cross-provider replay through the OpenAI streaming path. Coalesce to "{}" so
+* `arguments` is ALWAYS a string, matching the streaming recorder's behavior.
+*/
+function toToolCallArguments(raw) {
+	if (typeof raw === "string") return raw;
+	if (raw === void 0 || raw === null) return "{}";
+	return JSON.stringify(raw);
+}
+/**
 * Detect the response format from the parsed upstream JSON and convert
 * it into an aimock FixtureResponse.
 */
-function buildFixtureResponse(parsed, status, encodingFormat, logger) {
+function buildFixtureResponse(parsed, status, logger) {
 	if (parsed === null || parsed === void 0) return {
 		error: {
 			message: "Upstream returned non-JSON response",
@@ -548,19 +732,24 @@ function buildFixtureResponse(parsed, status, encodingFormat, logger) {
 	if (Array.isArray(obj.data) && obj.data.length > 0) {
 		const first = obj.data[0];
 		if (Array.isArray(first.embedding)) return { embedding: first.embedding };
-		if (typeof first.embedding === "string" && encodingFormat === "base64") {
+		if (typeof first.embedding === "string") {
 			const buf = Buffer.from(first.embedding, "base64");
-			if (buf.byteLength % 4 !== 0) return { embedding: [] };
-			const copied = new Uint8Array(buf);
-			const floats = new Float32Array(copied.buffer, 0, buf.byteLength / 4);
-			return { embedding: Array.from(floats) };
+			if (buf.byteLength === 0 || buf.byteLength % 4 !== 0) logger?.warn(`Could not decode base64 embedding (byteLength=${buf.byteLength} is not a positive multiple of 4) — saving as error fixture`);
+			else {
+				const copied = new Uint8Array(buf);
+				const floats = new Float32Array(copied.buffer, 0, buf.byteLength / 4);
+				return { embedding: Array.from(floats) };
+			}
 		}
-		if (first.url || first.b64_json) {
-			const images = obj.data.map((item) => ({
+		if (obj.data.some((item) => item.url || item.b64_json)) {
+			const dataItems = obj.data;
+			const images = dataItems.filter((item) => item.url || item.b64_json).map((item) => ({
 				...item.url ? { url: String(item.url) } : {},
 				...item.b64_json ? { b64Json: String(item.b64_json) } : {},
 				...item.revised_prompt ? { revisedPrompt: String(item.revised_prompt) } : {}
 			}));
+			const droppedCount = dataItems.length - images.length;
+			if (droppedCount > 0) logger?.warn(`Dropped ${droppedCount} image item(s) from batch lacking a non-empty url or b64_json`);
 			if (images.length === 1) return { image: images[0] };
 			return { images };
 		}
@@ -573,7 +762,7 @@ function buildFixtureResponse(parsed, status, encodingFormat, logger) {
 		if (images.length === 1) return { image: images[0] };
 		return { images };
 	}
-	if (typeof obj.text === "string" && (obj.task === "transcribe" || obj.language !== void 0 || obj.duration !== void 0)) return { transcription: {
+	if (typeof obj.text === "string" && (obj.task === "transcribe" || obj.language !== void 0 && obj.duration !== void 0) && !("choices" in obj) && !("candidates" in obj) && !("object" in obj) && !("message" in obj) && !("outputs" in obj)) return { transcription: {
 		text: obj.text,
 		...obj.language ? { language: String(obj.language) } : {},
 		...obj.duration !== void 0 ? { duration: Number(obj.duration) } : {},
@@ -590,7 +779,7 @@ function buildFixtureResponse(parsed, status, encodingFormat, logger) {
 		if (hasToolCalls) {
 			const toolCalls = fnCallOutputs.map((o) => ({
 				name: String(o.name),
-				arguments: typeof o.arguments === "string" ? o.arguments : JSON.stringify(o.arguments),
+				arguments: toToolCallArguments(o.arguments),
 				...o.id ? { id: String(o.id) } : {}
 			}));
 			if (hasContent) return {
@@ -619,13 +808,13 @@ function buildFixtureResponse(parsed, status, encodingFormat, logger) {
 		if (message) {
 			const hasToolCalls = Array.isArray(message.tool_calls) && message.tool_calls.length > 0;
 			const hasContent = typeof message.content === "string" && message.content.length > 0;
-			const openaiReasoning = typeof message.reasoning_content === "string" && message.reasoning_content.length > 0 ? message.reasoning_content : void 0;
+			const openaiReasoning = typeof message.reasoning_content === "string" && message.reasoning_content.length > 0 ? message.reasoning_content : typeof message.reasoning === "string" && message.reasoning.length > 0 ? message.reasoning : void 0;
 			if (hasToolCalls) {
 				const toolCalls = message.tool_calls.map((tc) => {
 					const fn = tc.function;
 					return {
 						name: String(fn.name),
-						arguments: String(fn.arguments),
+						arguments: toToolCallArguments(fn.arguments),
 						...tc.id ? { id: String(tc.id) } : {}
 					};
 				});
@@ -671,7 +860,7 @@ function buildFixtureResponse(parsed, status, encodingFormat, logger) {
 		if (hasToolCalls) {
 			const toolCalls = toolUseBlocks.map((b) => ({
 				name: String(b.name),
-				arguments: typeof b.input === "string" ? b.input : JSON.stringify(b.input),
+				arguments: toToolCallArguments(b.input),
 				...b.id ? { id: String(b.id) } : {}
 			}));
 			if (hasContent) return {
@@ -705,12 +894,18 @@ function buildFixtureResponse(parsed, status, encodingFormat, logger) {
 		const content = obj.candidates[0].content;
 		if (content && Array.isArray(content.parts)) {
 			const parts = content.parts;
-			const audioParts = parts.filter((p) => p.inlineData && typeof p.inlineData.mimeType === "string" && p.inlineData.mimeType.startsWith("audio/"));
+			const audioParts = parts.filter((p) => {
+				const inline = p.inlineData;
+				if (inline === void 0 || inline === null || typeof inline.data !== "string" || inline.data.length === 0) return false;
+				const mt = inline.mimeType;
+				if (typeof mt === "string" && mt.length > 0) return mt.startsWith("audio/");
+				return true;
+			});
 			if (audioParts.length > 0) {
 				const inlineData = audioParts[0].inlineData;
 				return { audio: {
 					b64Json: String(inlineData.data ?? ""),
-					contentType: String(inlineData.mimeType)
+					contentType: typeof inlineData.mimeType === "string" && inlineData.mimeType.length > 0 ? inlineData.mimeType : "audio/mpeg"
 				} };
 			}
 			const fnCallParts = parts.filter((p) => p.functionCall);
@@ -725,7 +920,7 @@ function buildFixtureResponse(parsed, status, encodingFormat, logger) {
 					const fc = p.functionCall;
 					return {
 						name: String(fc.name),
-						arguments: typeof fc.args === "string" ? fc.args : JSON.stringify(fc.args)
+						arguments: toToolCallArguments(fc.args)
 					};
 				});
 				if (hasContent) return {
@@ -767,7 +962,7 @@ function buildFixtureResponse(parsed, status, encodingFormat, logger) {
 					const tu = b.toolUse;
 					return {
 						name: String(tu.name ?? ""),
-						arguments: typeof tu.input === "string" ? tu.input : JSON.stringify(tu.input),
+						arguments: toToolCallArguments(tu.input),
 						...tu.toolUseId ? { id: String(tu.toolUseId) } : {}
 					};
 				});
@@ -794,18 +989,18 @@ function buildFixtureResponse(parsed, status, encodingFormat, logger) {
 	if (typeof obj.finish_reason === "string" && obj.message && typeof obj.message === "object" && Array.isArray(obj.message.content)) {
 		const msg = obj.message;
 		const contentBlocks = msg.content;
-		const textBlock = contentBlocks.find((b) => b.type === "text" && typeof b.text === "string");
-		const hasContent = textBlock && typeof textBlock.text === "string" && textBlock.text.length > 0;
+		const joinedText = contentBlocks.filter((b) => b.type === "text" && typeof b.text === "string").map((b) => String(b.text ?? "")).join("");
+		const hasContent = joinedText.length > 0;
 		const toolCallBlocks = contentBlocks.filter((b) => b.type === "tool_call");
 		const msgToolCalls = Array.isArray(msg.tool_calls) ? msg.tool_calls : [];
 		if (toolCallBlocks.length > 0) {
 			const toolCalls = toolCallBlocks.map((b) => ({
 				name: String(b.name ?? b.function?.name ?? ""),
-				arguments: typeof b.parameters === "string" ? b.parameters : typeof b.parameters === "object" ? JSON.stringify(b.parameters) : typeof b.function?.arguments === "string" ? String(b.function.arguments) : JSON.stringify(b.function?.arguments),
+				arguments: typeof b.parameters === "string" ? b.parameters : typeof b.parameters === "object" ? JSON.stringify(b.parameters) : typeof b.function?.arguments === "string" ? String(b.function.arguments) : toToolCallArguments(b.function?.arguments),
 				...b.id ? { id: String(b.id) } : {}
 			}));
 			if (hasContent) return {
-				content: textBlock.text,
+				content: joinedText,
 				toolCalls
 			};
 			return { toolCalls };
@@ -815,17 +1010,18 @@ function buildFixtureResponse(parsed, status, encodingFormat, logger) {
 				const fn = tc.function;
 				return {
 					name: String(tc.name ?? fn?.name ?? ""),
-					arguments: typeof tc.parameters === "string" ? tc.parameters : typeof tc.parameters === "object" ? JSON.stringify(tc.parameters) : typeof fn?.arguments === "string" ? String(fn.arguments) : JSON.stringify(fn?.arguments),
+					arguments: typeof tc.parameters === "string" ? tc.parameters : typeof tc.parameters === "object" ? JSON.stringify(tc.parameters) : typeof fn?.arguments === "string" ? String(fn.arguments) : toToolCallArguments(fn?.arguments),
 					...tc.id ? { id: String(tc.id) } : {}
 				};
 			});
 			if (hasContent) return {
-				content: textBlock.text,
+				content: joinedText,
 				toolCalls
 			};
 			return { toolCalls };
 		}
-		if (hasContent) return { content: textBlock.text };
+		if (hasContent) return { content: joinedText };
+		return { content: "" };
 	}
 	if (obj.message && typeof obj.message === "object") {
 		const msg = obj.message;
@@ -836,7 +1032,7 @@ function buildFixtureResponse(parsed, status, encodingFormat, logger) {
 				const fn = tc.function;
 				return {
 					name: String(fn.name ?? ""),
-					arguments: typeof fn.arguments === "string" ? fn.arguments : JSON.stringify(fn.arguments)
+					arguments: toToolCallArguments(fn.arguments)
 				};
 			});
 			if (hasOllamaContent) return {
@@ -851,7 +1047,8 @@ function buildFixtureResponse(parsed, status, encodingFormat, logger) {
 			if (typeof first.text === "string") return { content: first.text };
 		}
 	}
-	if (typeof obj.response === "string" && "done" in obj) return { content: obj.response };
+	if (typeof obj.response === "string" && typeof obj.done === "boolean") return { content: obj.response };
+	logger?.warn(`Could not detect response format from upstream (status=${status}) — saving as error fixture; top-level keys: [${Object.keys(obj).join(", ")}]`);
 	return {
 		error: {
 			message: "Could not detect response format from upstream",