@copilotkit/aimock 1.45.1 → 1.47.0

package/dist/responses.js

@@ -1,11 +1,18 @@
+import { renderError } from "./response/errors.js";
 import { isReasoningModel } from "./model-utils.js";
-import { assertCustomToolCalls, assertResponsesToolCalls, extractOverrides, flattenHeaders, generateId, generateToolCallId, getContext, getTestId, isCombinedFixtureResponse, isErrorResponse, isJsonObject, isTextResponse, isToolCallResponse, prepareOpenAIChatMisbehavior, resolveFixtureBlocks, resolveOpenAIChatMisbehaviorUsage, resolveReasoningForModel, resolveResponse, resolveServedBlockOutcome, resolveStrictMode, serializeErrorResponse, servedToolCalls, strictNoMatchLogLine, strictNoMatchMessage, strictOverrideField, toolCallFixtureBlock, withoutLegacyNamespaces } from "./helpers.js";
-import { calculateDelay, delay, writeErrorResponse } from "./sse-writer.js";
+import { resolveRequestDecisions, strictOverrideField } from "./response/policy.js";
+import { UnsupportedGeneratedFileError, assertCustomToolCalls, assertResponsesToolCalls, extractOverrides, fixtureCitations, fixtureFiles, flattenHeaders, generateId, generateToolCallId, getContext, getTestId, isCombinedFixtureResponse, isErrorResponse, isJsonObject, isRawResponse, isTextResponse, isToolCallResponse, prepareOpenAIChatMisbehavior, resolveFixtureBlocks, resolveOpenAIChatMisbehaviorUsage, resolveReasoningForModel, resolveResponse, resolveServedBlockOutcome, serializeErrorResponse, servedToolCalls, strictNoMatchLogLine, strictNoMatchMessage, surrogateSafeChunks, toolCallFixtureBlock, withoutLegacyNamespaces } from "./helpers.js";
+import { typedSseCodec, writeErrorResponse } from "./sse-writer.js";
 import { applyChaosAsync } from "./chaos.js";
 import { planMisbehavior, recordMisbehaviorOutcome } from "./misbehavior.js";
 import { matchFixtureDiagnostic, recordMatchOptions, setResponsesOfferedTools } from "./router.js";
 import { proxyAndRecord } from "./recorder.js";
-import { createInterruptionSignal } from "./interruption.js";
+import { extendRecordedTimings, misbehaviorPayloadLength, nonStreamingTimingEnabled, responsesOutputFrames, responsesPayloadLength } from "./response/timing.js";
+import { deliverJson, deliverStream } from "./response/deliver.js";
+import { proxyInterruption, withHangUpDetection } from "./response/proxy.js";
+import { serveRawResponse } from "./response/raw.js";
+import { render } from "./response/usage/codecs/responses.js";
+import { mapResponsesFinish } from "./response/finish.js";
 import { randomBytes } from "node:crypto";
 
 //#region src/responses.ts
@@ -310,25 +317,7 @@ function validateResponsesTools(tools) {
 }
 function responsesStatus(finishReason, defaultStatus) {
 	if (!finishReason) return defaultStatus;
-	if (finishReason === "stop") return "completed";
-	if (finishReason === "tool_calls") return "completed";
-	if (finishReason === "length") return "incomplete";
-	if (finishReason === "content_filter") return "failed";
-	return finishReason;
-}
-function responsesUsage(overrides) {
-	if (!overrides?.usage) return {
-		input_tokens: 0,
-		output_tokens: 0,
-		total_tokens: 0
-	};
-	const input = overrides.usage.input_tokens ?? overrides.usage.prompt_tokens ?? 0;
-	const output = overrides.usage.output_tokens ?? overrides.usage.completion_tokens ?? 0;
-	return {
-		input_tokens: input,
-		output_tokens: output,
-		total_tokens: overrides.usage.total_tokens ?? input + output
-	};
+	return mapResponsesFinish(finishReason);
 }
 function responseId() {
 	return generateId("resp");
@@ -338,7 +327,7 @@ function itemId() {
 }
 function buildTextStreamEvents(content, model, chunkSize, reasoning, webSearches, overrides, emitEncryptedReasoning = false, synthesizeSummarylessReasoning = false) {
 	const { respId, created, events, prefixOutputItems, nextOutputIndex } = buildResponsePreamble(model, chunkSize, reasoning, webSearches, overrides, emitEncryptedReasoning, synthesizeSummarylessReasoning);
-	const { events: msgEvents, msgItem } = buildMessageOutputEvents(content, chunkSize, nextOutputIndex);
+	const { events: msgEvents, msgItem } = buildMessageOutputEvents(content, chunkSize, nextOutputIndex, overrides?.phase, buildAnnotations(content, overrides?.citations));
 	events.push(...msgEvents);
 	events.push({
 		type: "response.completed",
@@ -349,7 +338,7 @@ function buildTextStreamEvents(content, model, chunkSize, reasoning, webSearches
 			model: overrides?.model ?? model,
 			status: responsesStatus(overrides?.finishReason, "completed"),
 			output: [...prefixOutputItems, msgItem],
-			usage: responsesUsage(overrides)
+			usage: render(overrides)
 		}
 	});
 	return events;
@@ -447,6 +436,7 @@ function buildToolCallStreamEvents(toolCalls, model, chunkSize, reasoning, webSe
 }
 function toolCallStreamEvents(toolCalls, model, chunkSize, reasoning, webSearches, overrides, emitEncryptedReasoning = false, synthesizeSummarylessReasoning = false) {
 	assertResponsesToolCalls(toolCalls);
+	fixtureCitations("", overrides?.citations);
 	const { respId, created, events, prefixOutputItems, nextOutputIndex } = buildResponsePreamble(model, chunkSize, reasoning, webSearches, overrides, emitEncryptedReasoning, synthesizeSummarylessReasoning);
 	const fcOutputItems = [];
 	for (let idx = 0; idx < toolCalls.length; idx++) {
@@ -463,7 +453,7 @@ function toolCallStreamEvents(toolCalls, model, chunkSize, reasoning, webSearche
 			model: overrides?.model ?? model,
 			status: responsesStatus(overrides?.finishReason, "completed"),
 			output: [...prefixOutputItems, ...fcOutputItems],
-			usage: responsesUsage(overrides)
+			usage: render(overrides)
 		}
 	});
 	return events;
@@ -683,6 +673,79 @@ function buildWebSearchStreamEvents(queries, startOutputIndex) {
 	}
 	return events;
 }
+/**
+* A Responses `image_generation_call` output item for one fixture file (see
+* `ResponseOutputItem.ImageGenerationCall` in the openai SDK): `result` holds
+* the base64 bytes once completed and is null while in progress.
+*/
+function imageGenerationCallItem(id, file, status) {
+	return {
+		type: "image_generation_call",
+		id,
+		status,
+		result: status === "completed" ? file.data : null
+	};
+}
+/**
+* A fixture file that is not `image/*` reached the Responses API, which
+* carries generated files only as `image_generation_call` items. Surfaces as
+* the same coded 500 (`aimock_unsupported_generated_file`), naming `mimeType`.
+*/
+var NonImageGeneratedFileError = class extends UnsupportedGeneratedFileError {
+	constructor(mimeType) {
+		super("the OpenAI Responses API");
+		this.message = `aimock: fixture "files" on the OpenAI Responses API carry only image/* files (as image_generation_call items); got mimeType "${mimeType}"`;
+	}
+};
+/**
+* Throw {@link NonImageGeneratedFileError} for the first fixture file whose
+* `mimeType` is not `image/*`. Called before any output item is built, so
+* nothing reaches the client.
+*/
+function requireImageFiles(files) {
+	const nonImage = files.find((f) => !f.mimeType.toLowerCase().startsWith("image/"));
+	if (nonImage) throw new NonImageGeneratedFileError(nonImage.mimeType);
+}
+/** Fixture `files` as completed `image_generation_call` items (non-streaming). */
+function imageGenerationCallItems(files) {
+	const validated = fixtureFiles(files);
+	requireImageFiles(validated);
+	return validated.map((f) => imageGenerationCallItem(generateId("ig"), f, "completed"));
+}
+/**
+* Streamed form of {@link imageGenerationCallItems}: per file, the item's
+* `output_item.added`, the `image_generation_call` `in_progress`,
+* `generating` and `completed` events, then `output_item.done` carrying the
+* completed item.
+*/
+function buildImageGenerationStreamEvents(files, startOutputIndex) {
+	requireImageFiles(files);
+	const events = [];
+	files.forEach((file, i) => {
+		const id = generateId("ig");
+		const outputIndex = startOutputIndex + i;
+		events.push({
+			type: "response.output_item.added",
+			output_index: outputIndex,
+			item: imageGenerationCallItem(id, file, "in_progress")
+		});
+		for (const phase of [
+			"in_progress",
+			"generating",
+			"completed"
+		]) events.push({
+			type: `response.image_generation_call.${phase}`,
+			output_index: outputIndex,
+			item_id: id
+		});
+		events.push({
+			type: "response.output_item.done",
+			output_index: outputIndex,
+			item: imageGenerationCallItem(id, file, "completed")
+		});
+	});
+	return events;
+}
 function buildResponsePreamble(model, chunkSize, reasoning, webSearches, overrides, emitEncryptedReasoning = false, synthesizeSummarylessReasoning = false, forceReasoning = false) {
 	const respId = overrides?.id ?? responseId();
 	const created = overrides?.created ?? Math.floor(Date.now() / 1e3);
@@ -726,6 +789,13 @@ function buildResponsePreamble(model, chunkSize, reasoning, webSearches, overrid
 		for (const de of doneEvents) prefixOutputItems.push(de.item);
 		nextOutputIndex += webSearches.length;
 	}
+	const files = fixtureFiles(overrides?.files);
+	if (files.length > 0) {
+		const fileEvents = buildImageGenerationStreamEvents(files, nextOutputIndex);
+		events.push(...fileEvents);
+		for (const e of fileEvents) if (e.type === "response.output_item.done") prefixOutputItems.push(e.item);
+		nextOutputIndex += files.length;
+	}
 	return {
 		respId,
 		created,
@@ -734,7 +804,84 @@ function buildResponsePreamble(model, chunkSize, reasoning, webSearches, overrid
 		nextOutputIndex
 	};
 }
-function buildMessageOutputEvents(content, chunkSize, outputIndex) {
+/**
+* Fixture `citations` as `output_text` annotations for each text in `texts`
+* (one per message item), in fixture order: a URL citation becomes
+* `url_citation`, a file citation (`type: "file"`) becomes `file_citation`
+* (`file_id`, `filename`, `index`; see `ResponseOutputText.FileCitation` in
+* the openai SDK). Offsets index the joined text of all texts, as on every
+* other provider. A URL citation is a range and goes only to the text holding
+* its `startIndex`. A file citation is a point after the cited text, so it
+* goes to the last text starting before its `index`: an `index` equal to a
+* text's end stays at the end of that text (not at 0 of the next text), and
+* an `index` of 0 goes to the first text. Each citation is rebased onto its
+* text since Responses offsets are per `output_text`, with `end_index`
+* clamped to it. Anthropic and Gemini need no point rule: they have no file
+* citation. Anthropic URL citations follow the same start-owns-range rule;
+* Gemini does not, and splits a citation that spans several text parts into
+* one grounding support per part (see geminiGroundingSupports).
+* Missing offsets take the defaults `resolveCitations` applies: a URL
+* citation starts at 0 and ends at the end of the joined text, so one without
+* offsets goes on the first text and covers all of it; a file citation's
+* `index` defaults to the end of the joined text (the last text).
+*/
+function blockAnnotations(texts, citations) {
+	const perText = texts.map(() => []);
+	if (texts.length === 0) {
+		fixtureCitations("", citations);
+		return perText;
+	}
+	const starts = [];
+	let offset = 0;
+	for (const text of texts) {
+		starts.push(offset);
+		offset += text.length;
+	}
+	const joinedLength = offset;
+	const ownerOf = (start) => {
+		let owner = 0;
+		for (let k = 1; k < starts.length; k++) if (starts[k] <= start) owner = k;
+		return owner;
+	};
+	const pointOwnerOf = (index) => {
+		let owner = 0;
+		for (let k = 1; k < starts.length; k++) if (starts[k] < index) owner = k;
+		return owner;
+	};
+	for (const c of fixtureCitations(texts.join(""), citations)) {
+		if (c.type === "file") {
+			const index = c.index ?? joinedLength;
+			const owner = pointOwnerOf(index);
+			perText[owner].push({
+				type: "file_citation",
+				file_id: c.fileId,
+				filename: c.filename,
+				index: index - starts[owner]
+			});
+			continue;
+		}
+		const start = c.startIndex ?? 0;
+		const end = c.endIndex ?? joinedLength;
+		const owner = ownerOf(start);
+		perText[owner].push({
+			type: "url_citation",
+			url: c.url,
+			title: c.title ?? c.url,
+			start_index: start - starts[owner],
+			end_index: Math.min(end - starts[owner], texts[owner].length)
+		});
+	}
+	return perText;
+}
+/** {@link blockAnnotations} for a turn with a single text. */
+function buildAnnotations(content, citations) {
+	return blockAnnotations([content], citations)[0];
+}
+/** The annotations of each text block in `blocks`, in block order. */
+function orderedBlockAnnotations(blocks, citations) {
+	return blockAnnotations(blocks.flatMap((b) => b.type === "text" ? [b.text] : []), citations);
+}
+function buildMessageOutputEvents(content, chunkSize, outputIndex, phase, annotations) {
 	const msgId = itemId();
 	const events = [];
 	events.push({
@@ -745,6 +892,7 @@ function buildMessageOutputEvents(content, chunkSize, outputIndex) {
 			id: msgId,
 			status: "in_progress",
 			role: "assistant",
+			...phase !== void 0 ? { phase } : {},
 			content: []
 		}
 	});
@@ -773,6 +921,16 @@ function buildMessageOutputEvents(content, chunkSize, outputIndex) {
 		content_index: 0,
 		text: content
 	});
+	annotations.forEach((annotation, annotationIndex) => {
+		events.push({
+			type: "response.output_text.annotation.added",
+			item_id: msgId,
+			output_index: outputIndex,
+			content_index: 0,
+			annotation_index: annotationIndex,
+			annotation
+		});
+	});
 	events.push({
 		type: "response.content_part.done",
 		item_id: msgId,
@@ -781,7 +939,7 @@ function buildMessageOutputEvents(content, chunkSize, outputIndex) {
 		part: {
 			type: "output_text",
 			text: content,
-			annotations: []
+			annotations
 		}
 	});
 	const msgItem = {
@@ -789,10 +947,11 @@ function buildMessageOutputEvents(content, chunkSize, outputIndex) {
 		id: msgId,
 		status: "completed",
 		role: "assistant",
+		...phase !== void 0 ? { phase } : {},
 		content: [{
 			type: "output_text",
 			text: content,
-			annotations: []
+			annotations
 		}]
 	};
 	events.push({
@@ -847,24 +1006,6 @@ function buildFunctionCallOutputEvents(toolCall, chunkSize, outputIndex) {
 	};
 }
 /**
-* `text` cut into slices of at most `chunkSize` UTF-16 units, never between
-* the two halves of a surrogate pair: a cut that would land inside a pair
-* moves back before it, or, when that would leave the slice empty
-* (`chunkSize` 1), forward past it. The slices rejoin to `text` exactly.
-*/
-function surrogateSafeChunks(text, chunkSize) {
-	const chunks = [];
-	for (let i = 0; i < text.length;) {
-		let end = Math.min(i + chunkSize, text.length);
-		const high = text.charCodeAt(end - 1);
-		const low = text.charCodeAt(end);
-		if (high >= 55296 && high <= 56319 && low >= 56320 && low <= 57343) end = end - 1 > i ? end - 1 : end + 1;
-		chunks.push(text.slice(i, end));
-		i = end;
-	}
-	return chunks;
-}
-/**
 * Emit output_item.added → custom_tool_call_input.delta×N →
 * custom_tool_call_input.done → output_item.done for one `custom_tool_call` at
 * `outputIndex`, returning the completed item. An empty `input`
@@ -907,7 +1048,7 @@ function buildCustomToolCallOutputEvents(call, chunkSize, outputIndex) {
 function buildToolCallOutputEvents(call, chunkSize, outputIndex) {
 	return isCustomEmittable(call) ? buildCustomToolCallOutputEvents(call, chunkSize, outputIndex) : buildFunctionCallOutputEvents(call, chunkSize, outputIndex);
 }
-function buildOutputPrefix(content, model, reasoning, webSearches, emitEncryptedReasoning = false, synthesizeSummarylessReasoning = false) {
+function buildOutputPrefix(content, model, reasoning, webSearches, emitEncryptedReasoning = false, synthesizeSummarylessReasoning = false, phase, citations, files) {
 	const output = [];
 	if (reasoning || shouldSynthesizeBlobOnlyReasoning(reasoning, model, synthesizeSummarylessReasoning)) output.push(buildReasoningOutputItem(generateId("rs"), {
 		summaryText: reasoning,
@@ -922,15 +1063,17 @@ function buildOutputPrefix(content, model, reasoning, webSearches, emitEncrypted
 			query
 		}
 	});
+	output.push(...imageGenerationCallItems(files));
 	output.push({
 		type: "message",
 		id: itemId(),
 		status: "completed",
 		role: "assistant",
+		...phase !== void 0 ? { phase } : {},
 		content: [{
 			type: "output_text",
 			text: content,
-			annotations: []
+			annotations: buildAnnotations(content, citations)
 		}]
 	});
 	return output;
@@ -943,14 +1086,15 @@ function buildResponseEnvelope(model, output, overrides) {
 		model: overrides?.model ?? model,
 		status: responsesStatus(overrides?.finishReason, "completed"),
 		output,
-		usage: responsesUsage(overrides)
+		usage: render(overrides)
 	};
 }
 function buildTextResponse(content, model, reasoning, webSearches, overrides, emitEncryptedReasoning = false, synthesizeSummarylessReasoning = false) {
-	return buildResponseEnvelope(model, buildOutputPrefix(content, model, reasoning, webSearches, emitEncryptedReasoning, synthesizeSummarylessReasoning), overrides);
+	return buildResponseEnvelope(model, buildOutputPrefix(content, model, reasoning, webSearches, emitEncryptedReasoning, synthesizeSummarylessReasoning, overrides?.phase, overrides?.citations, overrides?.files), overrides);
 }
 function buildToolCallResponse(toolCalls, model, reasoning, webSearches, overrides, emitEncryptedReasoning = false, synthesizeSummarylessReasoning = false) {
 	assertResponsesToolCalls(toolCalls);
+	fixtureCitations("", overrides?.citations);
 	const output = [];
 	if (reasoning || shouldSynthesizeBlobOnlyReasoning(reasoning, model, synthesizeSummarylessReasoning)) output.push(buildReasoningOutputItem(generateId("rs"), {
 		summaryText: reasoning,
@@ -965,6 +1109,7 @@ function buildToolCallResponse(toolCalls, model, reasoning, webSearches, overrid
 			query
 		}
 	});
+	output.push(...imageGenerationCallItems(overrides?.files));
 	for (const tc of toolCalls) output.push(buildToolCallOutputItem(tc));
 	return buildResponseEnvelope(model, output, overrides);
 }
@@ -982,9 +1127,11 @@ function contentWithToolCallsStreamEvents(content, toolCalls, model, chunkSize,
 	const orderedOutputItems = [];
 	if (ordered && ordered.length > 0) {
 		let outputIndex = nextOutputIndex;
+		const textAnnotations = orderedBlockAnnotations(ordered, overrides?.citations);
+		let textPos = 0;
 		for (const block of ordered) {
 			if (block.type === "text") {
-				const { events: msgEvents, msgItem } = buildMessageOutputEvents(block.text, chunkSize, outputIndex);
+				const { events: msgEvents, msgItem } = buildMessageOutputEvents(block.text, chunkSize, outputIndex, overrides?.phase, textAnnotations[textPos++]);
 				events.push(...msgEvents);
 				orderedOutputItems.push(msgItem);
 			} else {
@@ -996,7 +1143,7 @@ function contentWithToolCallsStreamEvents(content, toolCalls, model, chunkSize,
 		}
 	} else {
 		assertResponsesToolCalls(toolCalls);
-		const { events: msgEvents, msgItem } = buildMessageOutputEvents(content, chunkSize, nextOutputIndex);
+		const { events: msgEvents, msgItem } = buildMessageOutputEvents(content, chunkSize, nextOutputIndex, overrides?.phase, buildAnnotations(content, overrides?.citations));
 		events.push(...msgEvents);
 		orderedOutputItems.push(msgItem);
 		for (let idx = 0; idx < toolCalls.length; idx++) {
@@ -1014,7 +1161,7 @@ function contentWithToolCallsStreamEvents(content, toolCalls, model, chunkSize,
 			model: overrides?.model ?? model,
 			status: responsesStatus(overrides?.finishReason, "completed"),
 			output: [...prefixOutputItems, ...orderedOutputItems],
-			usage: responsesUsage(overrides)
+			usage: render(overrides)
 		}
 	});
 	return events;
@@ -1024,16 +1171,17 @@ function buildToolCallOutputItem(tc) {
 	if (isCustomEmittable(tc)) return customToolCallItem(tc, customToolCallItemId(), tc.id || generateToolCallId(), requireFixtureToolInput(tc.input), "completed");
 	return functionCallItem(tc, generateId("fc"), tc.id || generateToolCallId(), requireFixtureToolArguments(tc.arguments), "completed");
 }
-function buildMessageOutputItem(content) {
+function buildMessageOutputItem(content, phase, annotations) {
 	return {
 		type: "message",
 		id: itemId(),
 		status: "completed",
 		role: "assistant",
+		...phase !== void 0 ? { phase } : {},
 		content: [{
 			type: "output_text",
 			text: content,
-			annotations: []
+			annotations
 		}]
 	};
 }
@@ -1053,40 +1201,18 @@ function buildContentWithToolCallsResponse(content, toolCalls, model, reasoning,
 				query
 			}
 		});
-		for (const block of ordered) if (block.type === "text") output.push(buildMessageOutputItem(block.text));
+		output.push(...imageGenerationCallItems(overrides?.files));
+		const textAnnotations = orderedBlockAnnotations(ordered, overrides?.citations);
+		let textPos = 0;
+		for (const block of ordered) if (block.type === "text") output.push(buildMessageOutputItem(block.text, overrides?.phase, textAnnotations[textPos++]));
 		else output.push(buildToolCallOutputItem(block));
 		return buildResponseEnvelope(model, output, overrides);
 	}
 	assertResponsesToolCalls(toolCalls);
-	const output = buildOutputPrefix(content, model, reasoning, webSearches, emitEncryptedReasoning, synthesizeSummarylessReasoning);
+	const output = buildOutputPrefix(content, model, reasoning, webSearches, emitEncryptedReasoning, synthesizeSummarylessReasoning, overrides?.phase, overrides?.citations, overrides?.files);
 	for (const tc of toolCalls) output.push(buildToolCallOutputItem(tc));
 	return buildResponseEnvelope(model, output, overrides);
 }
-async function writeResponsesSSEStream(res, events, optionsOrLatency) {
-	const opts = typeof optionsOrLatency === "number" ? { latency: optionsOrLatency } : optionsOrLatency ?? {};
-	const latency = opts.latency ?? 0;
-	const profile = opts.streamingProfile;
-	const { recordedTimings, replaySpeed } = opts;
-	const signal = opts.signal;
-	const onChunkSent = opts.onChunkSent;
-	if (res.writableEnded) return true;
-	res.setHeader("Content-Type", "text/event-stream");
-	res.setHeader("Cache-Control", "no-cache");
-	res.setHeader("Connection", "keep-alive");
-	let chunkIndex = 0;
-	for (const event of events) {
-		const chunkDelay = calculateDelay(chunkIndex, profile, latency, recordedTimings, replaySpeed);
-		if (chunkDelay > 0) await delay(chunkDelay, signal);
-		if (signal?.aborted) return false;
-		if (res.writableEnded) return true;
-		res.write(`event: ${event.type}\ndata: ${JSON.stringify(event)}\n\n`);
-		onChunkSent?.();
-		if (signal?.aborted) return false;
-		chunkIndex++;
-	}
-	if (!res.writableEnded) res.end();
-	return true;
-}
 async function handleResponses(req, res, raw, fixtures, journal, defaults, setCorsHeaders) {
 	setCorsHeaders(res);
 	let responsesReq;
@@ -1104,11 +1230,11 @@ async function handleResponses(req, res, raw, fixtures, journal, defaults, setCo
 				fixture: null
 			}
 		});
-		writeErrorResponse(res, 400, JSON.stringify({ error: {
+		writeErrorResponse(res, 400, renderError("openai", "validation", {
 			message: `Malformed JSON: ${detail}`,
 			type: "invalid_request_error",
 			code: "invalid_json"
-		} }));
+		}).body);
 		return;
 	}
 	if (!isJsonObject(responsesReq)) {
@@ -1122,10 +1248,10 @@ async function handleResponses(req, res, raw, fixtures, journal, defaults, setCo
 				fixture: null
 			}
 		});
-		writeErrorResponse(res, 400, JSON.stringify({ error: {
+		writeErrorResponse(res, 400, renderError("openai", "validation", {
 			message: "Request body must be a JSON object",
 			type: "invalid_request_error"
-		} }));
+		}).body);
 		return;
 	}
 	let inputError;
@@ -1152,10 +1278,10 @@ async function handleResponses(req, res, raw, fixtures, journal, defaults, setCo
 				fixture: null
 			}
 		});
-		writeErrorResponse(res, 400, JSON.stringify({ error: {
+		writeErrorResponse(res, 400, renderError("openai", "validation", {
 			message: validationError,
 			type: "invalid_request_error"
-		} }));
+		}).body);
 		return;
 	}
 	const extendedTools = defaults.responsesTools === "extended";
@@ -1168,7 +1294,10 @@ async function handleResponses(req, res, raw, fixtures, journal, defaults, setCo
 	const emitEncryptedReasoning = requestWantsEncryptedReasoning(responsesReq);
 	const synthesizeSummarylessReasoning = requestIncludesEncryptedReasoning(responsesReq);
 	const testId = getTestId(req);
-	const { fixture, skippedBySequenceOrTurn } = matchFixtureDiagnostic(fixtures, completionReq, journal.getFixtureMatchCountsForTest(testId), defaults.requestTransform, recordMatchOptions(!!defaults.record, defaults.logger));
+	const { fixture, skippedBySequenceOrTurn } = matchFixtureDiagnostic(fixtures, completionReq, journal.getFixtureMatchCountsForTest(testId), defaults.requestTransform, {
+		...recordMatchOptions(!!defaults.record, defaults.logger),
+		wire: "openai-responses"
+	});
 	if (fixture) {
 		defaults.logger.debug(`Responses fixture matched for ${req.method ?? "POST"} ${req.url ?? "/v1/responses"}`);
 		journal.incrementFixtureMatchCount(fixture, fixtures, testId);
@@ -1180,7 +1309,7 @@ async function handleResponses(req, res, raw, fixtures, journal, defaults, setCo
 		body: completionReq
 	}, fixture ? "fixture" : "proxy", defaults.registry, defaults.logger)) return;
 	if (!fixture) {
-		if (resolveStrictMode(defaults.strict, req.headers)) {
+		if (resolveRequestDecisions(defaults.strict, req.headers).fixtureMiss) {
 			const strictStatus = 503;
 			const strictMessage = strictNoMatchMessage(skippedBySequenceOrTurn);
 			defaults.logger.error(strictNoMatchLogLine(req.method ?? "POST", req.url ?? "/v1/responses", skippedBySequenceOrTurn));
@@ -1195,15 +1324,15 @@ async function handleResponses(req, res, raw, fixtures, journal, defaults, setCo
 					...strictOverrideField(defaults.strict, req.headers)
 				}
 			});
-			writeErrorResponse(res, strictStatus, JSON.stringify({ error: {
+			writeErrorResponse(res, strictStatus, renderError("openai", "strict-miss", {
 				message: strictMessage,
 				type: "invalid_request_error",
 				code: "no_fixture_match"
-			} }));
+			}).body);
 			return;
 		}
 		if (defaults.record) {
-			const outcome = await proxyAndRecord(req, res, completionReq, "openai", req.url ?? "/v1/responses", fixtures, defaults, raw);
+			const { outcome, clientHungUp } = await withHangUpDetection(req, res, () => proxyAndRecord(req, res, completionReq, "openai", req.url ?? "/v1/responses", fixtures, defaults, raw));
 			if (outcome === "handled_by_hook") return;
 			if (outcome !== "not_configured") {
 				journal.add({
@@ -1214,7 +1343,8 @@ async function handleResponses(req, res, raw, fixtures, journal, defaults, setCo
 					response: {
 						status: res.statusCode ?? 200,
 						fixture: null,
-						source: "proxy"
+						source: "proxy",
+						...proxyInterruption(res, clientHungUp)
 					}
 				});
 				return;
@@ -1231,11 +1361,11 @@ async function handleResponses(req, res, raw, fixtures, journal, defaults, setCo
 				...strictOverrideField(defaults.strict, req.headers)
 			}
 		});
-		writeErrorResponse(res, 404, JSON.stringify({ error: {
+		writeErrorResponse(res, 404, renderError("openai", "fixture-miss", {
 			message: "No fixture matched",
 			type: "invalid_request_error",
 			code: "no_fixture_match"
-		} }));
+		}).body);
 		return;
 	}
 	const resolvedResponse = await resolveResponse(fixture, completionReq);
@@ -1268,20 +1398,34 @@ async function handleResponses(req, res, raw, fixtures, journal, defaults, setCo
 			testId
 		});
 		if (!misbehavior.summary?.evaluations.some((evaluation) => evaluation.outcome === "error")) defaults.logger.error(misbehavior.message);
-		writeErrorResponse(res, misbehavior.status, JSON.stringify({ error: {
+		writeErrorResponse(res, misbehavior.status, renderError("openai", "misbehavior", {
 			message: misbehavior.message,
 			type: "invalid_request_error",
 			code: misbehavior.code
-		} }));
+		}).body);
 		return;
 	}
 	const latency = fixture.latency ?? defaults.latency;
 	const chunkSize = Math.max(1, fixture.chunkSize ?? defaults.chunkSize);
 	const fixtureTimings = fixture.recordedTimings;
 	const effectiveReplaySpeed = fixture.replaySpeed ?? defaults.replaySpeed;
+	const streamTiming = {
+		latency,
+		streamingProfile: fixture.streamingProfile,
+		recordedTimings: fixtureTimings,
+		replaySpeed: effectiveReplaySpeed
+	};
+	const timedJson = nonStreamingTimingEnabled(fixture, "other");
+	const jsonPayloadLength = (r, reasoning) => responsesPayloadLength(r, reasoning) + responsesOutputFrames(r) * chunkSize;
+	const jsonOpts = (payloadLength, duplicateId = false) => ({
+		surface: "other",
+		payloadLength: timedJson ? payloadLength() : 0,
+		chunkSize,
+		recordedTimings: fixtureTimings,
+		duplicateId,
+		replaySpeed: effectiveReplaySpeed
+	});
 	if (misbehavior.kind === "applied") {
-		const prepared = prepareResponsesMisbehavior(misbehavior);
-		const output = buildResponsesMisbehavior(prepared, completionReq, chunkSize, emitEncryptedReasoning);
 		const entry = journal.add({
 			method: req.method ?? "POST",
 			path: req.url ?? "/v1/responses",
@@ -1292,41 +1436,50 @@ async function handleResponses(req, res, raw, fixtures, journal, defaults, setCo
 				fixture
 			}
 		});
-		recordMisbehaviorOutcome({
+		const prepared = prepareResponsesMisbehavior(misbehavior);
+		const build = () => buildResponsesMisbehavior(prepared, completionReq, chunkSize, emitEncryptedReasoning);
+		const record = () => recordMisbehaviorOutcome({
 			entry,
 			summary: prepared.summary,
 			defaults,
 			testId
 		});
+		const output = timedJson && responsesReq.stream !== true ? void 0 : build();
+		if (output) record();
 		if (responsesReq.stream !== true) {
-			res.writeHead(200, { "Content-Type": "application/json" });
-			res.end(JSON.stringify(output.response));
+			const servedReasoning = prepared.reasoning ?? ("reasoning" in prepared.response ? prepared.response.reasoning : void 0);
+			await deliverJson(res, entry, fixture, () => {
+				if (output) return output.response;
+				const built = build();
+				record();
+				return built.response;
+			}, jsonOpts(() => misbehaviorPayloadLength(prepared, servedReasoning, jsonPayloadLength), !!prepared.duplicateId));
 		} else {
-			const appliedTimings = prepared.duplicateId && fixtureTimings ? {
-				...fixtureTimings,
-				interChunkDelaysMs: [...fixtureTimings.interChunkDelaysMs]
-			} : fixtureTimings;
-			if (prepared.duplicateId && appliedTimings) {
-				const lastGap = appliedTimings.interChunkDelaysMs.at(-1) ?? 0;
-				while (appliedTimings.interChunkDelaysMs.length < output.events.length - 1) appliedTimings.interChunkDelaysMs.push(lastGap);
-			}
-			const interruption = createInterruptionSignal(fixture);
-			if (!await writeResponsesSSEStream(res, output.events, {
-				latency,
-				streamingProfile: fixture.streamingProfile,
-				recordedTimings: appliedTimings,
-				replaySpeed: effectiveReplaySpeed,
-				signal: interruption?.signal,
-				onChunkSent: interruption?.tick
-			})) {
-				if (!res.writableEnded) res.destroy();
-				entry.response.interrupted = true;
-				entry.response.interruptReason = interruption?.reason();
-			}
-			interruption?.cleanup();
+			const { events } = output ?? build();
+			await deliverStream(res, entry, fixture, typedSseCodec(), events, {
+				...streamTiming,
+				recordedTimings: extendRecordedTimings(fixtureTimings, events.length, !!prepared.duplicateId)
+			});
 		}
 		return;
 	}
+	if (isRawResponse(response)) {
+		await serveRawResponse({
+			wire: "openai-responses",
+			stream: responsesReq.stream === true,
+			req,
+			res,
+			fixture,
+			response,
+			body: completionReq,
+			journal,
+			defaults,
+			testId,
+			misbehaviorSummary: misbehavior.summary,
+			errorWire: "openai"
+		});
+		return;
+	}
 	if (isErrorResponse(response)) {
 		const status = response.status ?? 500;
 		recordMisbehaviorOutcome({
@@ -1349,7 +1502,7 @@ async function handleResponses(req, res, raw, fixtures, journal, defaults, setCo
 	}
 	if (isCombinedFixtureResponse(response)) {
 		const overrides = extractOverrides(response);
-		const effectiveStrict = resolveStrictMode(defaults.strict, req.headers);
+		const effectiveStrict = resolveRequestDecisions(defaults.strict, req.headers).reasoningSuppression;
 		const effReasoning = resolveReasoningForModel(response.reasoning, completionReq.model, effectiveStrict, defaults.logger);
 		const journalEntry = journal.add({
 			method: req.method ?? "POST",
@@ -1370,32 +1523,16 @@ async function handleResponses(req, res, raw, fixtures, journal, defaults, setCo
 		const ordered = resolveServedBlockOutcome(response)?.ordered;
 		if (!ordered) assertCustomToolCalls(response);
 		const toolCalls = servedToolCalls(response);
-		if (responsesReq.stream !== true) {
-			const body = buildContentWithToolCallsResponse(response.content ?? "", toolCalls, completionReq.model, effReasoning, response.webSearches, overrides, ordered, emitEncryptedReasoning, synthesizeSummarylessReasoning);
-			res.writeHead(200, { "Content-Type": "application/json" });
-			res.end(JSON.stringify(body));
-		} else {
+		if (responsesReq.stream !== true) await deliverJson(res, journalEntry, fixture, () => buildContentWithToolCallsResponse(response.content ?? "", toolCalls, completionReq.model, effReasoning, response.webSearches, overrides, ordered, emitEncryptedReasoning, synthesizeSummarylessReasoning), jsonOpts(() => jsonPayloadLength(response, effReasoning)));
+		else {
 			const events = contentWithToolCallsStreamEvents(response.content ?? "", toolCalls, completionReq.model, chunkSize, effReasoning, response.webSearches, overrides, ordered, emitEncryptedReasoning, synthesizeSummarylessReasoning);
-			const interruption = createInterruptionSignal(fixture);
-			if (!await writeResponsesSSEStream(res, events, {
-				latency,
-				streamingProfile: fixture.streamingProfile,
-				recordedTimings: fixtureTimings,
-				replaySpeed: effectiveReplaySpeed,
-				signal: interruption?.signal,
-				onChunkSent: interruption?.tick
-			})) {
-				if (!res.writableEnded) res.destroy();
-				journalEntry.response.interrupted = true;
-				journalEntry.response.interruptReason = interruption?.reason();
-			}
-			interruption?.cleanup();
+			await deliverStream(res, journalEntry, fixture, typedSseCodec(), events, streamTiming);
 		}
 		return;
 	}
 	if (isTextResponse(response)) {
 		const overrides = extractOverrides(response);
-		const effectiveStrict = resolveStrictMode(defaults.strict, req.headers);
+		const effectiveStrict = resolveRequestDecisions(defaults.strict, req.headers).reasoningSuppression;
 		const effReasoning = resolveReasoningForModel(response.reasoning, completionReq.model, effectiveStrict, defaults.logger);
 		const journalEntry = journal.add({
 			method: req.method ?? "POST",
@@ -1413,32 +1550,16 @@ async function handleResponses(req, res, raw, fixtures, journal, defaults, setCo
 			defaults,
 			testId
 		});
-		if (responsesReq.stream !== true) {
-			const body = buildTextResponse(response.content, completionReq.model, effReasoning, response.webSearches, overrides, emitEncryptedReasoning, synthesizeSummarylessReasoning);
-			res.writeHead(200, { "Content-Type": "application/json" });
-			res.end(JSON.stringify(body));
-		} else {
+		if (responsesReq.stream !== true) await deliverJson(res, journalEntry, fixture, () => buildTextResponse(response.content, completionReq.model, effReasoning, response.webSearches, overrides, emitEncryptedReasoning, synthesizeSummarylessReasoning), jsonOpts(() => jsonPayloadLength(response, effReasoning)));
+		else {
 			const events = buildTextStreamEvents(response.content, completionReq.model, chunkSize, effReasoning, response.webSearches, overrides, emitEncryptedReasoning, synthesizeSummarylessReasoning);
-			const interruption = createInterruptionSignal(fixture);
-			if (!await writeResponsesSSEStream(res, events, {
-				latency,
-				streamingProfile: fixture.streamingProfile,
-				recordedTimings: fixtureTimings,
-				replaySpeed: effectiveReplaySpeed,
-				signal: interruption?.signal,
-				onChunkSent: interruption?.tick
-			})) {
-				if (!res.writableEnded) res.destroy();
-				journalEntry.response.interrupted = true;
-				journalEntry.response.interruptReason = interruption?.reason();
-			}
-			interruption?.cleanup();
+			await deliverStream(res, journalEntry, fixture, typedSseCodec(), events, streamTiming);
 		}
 		return;
 	}
 	if (isToolCallResponse(response)) {
 		const overrides = extractOverrides(response);
-		const effectiveStrict = resolveStrictMode(defaults.strict, req.headers);
+		const effectiveStrict = resolveRequestDecisions(defaults.strict, req.headers).reasoningSuppression;
 		const effReasoning = resolveReasoningForModel(response.reasoning, completionReq.model, effectiveStrict, defaults.logger);
 		const journalEntry = journal.add({
 			method: req.method ?? "POST",
@@ -1457,26 +1578,10 @@ async function handleResponses(req, res, raw, fixtures, journal, defaults, setCo
 			testId
 		});
 		assertCustomToolCalls(response);
-		if (responsesReq.stream !== true) {
-			const body = buildToolCallResponse(servedToolCalls(response), completionReq.model, effReasoning, response.webSearches, overrides, emitEncryptedReasoning, synthesizeSummarylessReasoning);
-			res.writeHead(200, { "Content-Type": "application/json" });
-			res.end(JSON.stringify(body));
-		} else {
+		if (responsesReq.stream !== true) await deliverJson(res, journalEntry, fixture, () => buildToolCallResponse(servedToolCalls(response), completionReq.model, effReasoning, response.webSearches, overrides, emitEncryptedReasoning, synthesizeSummarylessReasoning), jsonOpts(() => jsonPayloadLength(response, effReasoning)));
+		else {
 			const events = toolCallStreamEvents(servedToolCalls(response), completionReq.model, chunkSize, effReasoning, response.webSearches, overrides, emitEncryptedReasoning, synthesizeSummarylessReasoning);
-			const interruption = createInterruptionSignal(fixture);
-			if (!await writeResponsesSSEStream(res, events, {
-				latency,
-				streamingProfile: fixture.streamingProfile,
-				recordedTimings: fixtureTimings,
-				replaySpeed: effectiveReplaySpeed,
-				signal: interruption?.signal,
-				onChunkSent: interruption?.tick
-			})) {
-				if (!res.writableEnded) res.destroy();
-				journalEntry.response.interrupted = true;
-				journalEntry.response.interruptReason = interruption?.reason();
-			}
-			interruption?.cleanup();
+			await deliverStream(res, journalEntry, fixture, typedSseCodec(), events, streamTiming);
 		}
 		return;
 	}
@@ -1495,10 +1600,10 @@ async function handleResponses(req, res, raw, fixtures, journal, defaults, setCo
 		defaults,
 		testId
 	});
-	writeErrorResponse(res, 500, JSON.stringify({ error: {
+	writeErrorResponse(res, 500, renderError("openai", "unknown-response", {
 		message: "Fixture response did not match any known type",
 		type: "server_error"
-	} }));
+	}).body);
 }
 /** Prepare call IDs once, retaining the engine's effective blocks and exact served-call metadata. */
 function prepareResponsesMisbehavior(plan) {
@@ -1511,7 +1616,11 @@ function buildResponsesMisbehavior(plan, request, chunkSize, emitEncryptedReason
 	const overrides = extractOverrides(response);
 	const reasoning = plan.reasoning ?? ("reasoning" in response ? response.reasoning : void 0);
 	const webSearches = "webSearches" in response ? response.webSearches : void 0;
-	const { respId, created, events, prefixOutputItems, nextOutputIndex } = buildResponsePreamble(request.model, chunkSize, reasoning, webSearches, overrides, emitEncryptedReasoning, false, plan.reasoning !== void 0);
+	const outputWithheld = plan.refusal !== void 0 || plan.summary.fault === "empty-response" || plan.stop === "content_filter" || plan.reasoning !== void 0;
+	const { respId, created, events, prefixOutputItems, nextOutputIndex } = buildResponsePreamble(request.model, chunkSize, reasoning, webSearches, outputWithheld ? {
+		...overrides,
+		files: void 0
+	} : overrides, emitEncryptedReasoning, false, plan.reasoning !== void 0);
 	const output = [...prefixOutputItems];
 	let outputIndex = nextOutputIndex;
 	const incomplete = plan.stop === "length" || plan.stop === "content_filter";
@@ -1526,6 +1635,7 @@ function buildResponsesMisbehavior(plan, request, chunkSize, emitEncryptedReason
 			type: "message",
 			role: "assistant",
 			status: "completed",
+			...overrides.phase !== void 0 ? { phase: overrides.phase } : {},
 			content: [part]
 		};
 		const position = {
@@ -1568,16 +1678,18 @@ function buildResponsesMisbehavior(plan, request, chunkSize, emitEncryptedReason
 			item
 		});
 		output.push(item);
-	} else if (plan.summary.fault !== "empty-response" && plan.stop !== "content_filter" && plan.reasoning === void 0) {
+	} else if (!outputWithheld) {
 		const combined = isCombinedFixtureResponse(response);
 		const blocks = (combined ? resolveServedBlockOutcome(response) : void 0)?.ordered ?? [..."content" in response && typeof response.content === "string" ? [{
 			type: "text",
 			text: response.content
 		}] : [], ...combined || isToolCallResponse(response) ? servedToolCalls(response).map(toolCallFixtureBlock) : []];
 		let callIndex = 0;
+		const textAnnotations = orderedBlockAnnotations(blocks, overrides.citations);
+		let textPos = 0;
 		for (const block of blocks) {
 			if (block.type === "text") {
-				const message = buildMessageOutputEvents(block.text, chunkSize, outputIndex);
+				const message = buildMessageOutputEvents(block.text, chunkSize, outputIndex, overrides.phase, textAnnotations[textPos++]);
 				events.push(...message.events);
 				output.push(message.msgItem);
 			} else {
@@ -1606,11 +1718,7 @@ function buildResponsesMisbehavior(plan, request, chunkSize, emitEncryptedReason
 		status: incomplete ? "incomplete" : responsesStatus(overrides?.finishReason, "completed"),
 		...incomplete ? { incomplete_details: { reason: plan.stop === "content_filter" ? "content_filter" : "max_output_tokens" } } : {},
 		output,
-		usage: {
-			input_tokens: usage.prompt_tokens,
-			output_tokens: usage.completion_tokens,
-			total_tokens: usage.total_tokens
-		}
+		usage: render({ usage })
 	};
 	events.push({
 		type: incomplete ? "response.incomplete" : "response.completed",