@copilotkit/aimock 1.45.1 → 1.47.0

package/dist/helpers.js

@@ -1,3 +1,6 @@
+import { estimatePromptTokens as estimatePromptTokens$1, estimateTokens as estimateTokens$1 } from "./response/usage/estimate.js";
+import { render, resolve } from "./response/usage/codecs/openai.js";
+import { renderError } from "./response/errors.js";
 import { DEFAULT_TEST_ID, MCP_FAKES_ECHO_LIMIT } from "./constants.js";
 import { cutText } from "./echo-text.js";
 import { build, fixed, msg, quote } from "./message-text.js";
@@ -212,12 +215,331 @@ function requireEmittedFunctionToolCalls(response, wire) {
 	if (Array.isArray(response.blocks) && response.blocks.length > 0) return [];
 	return requireFunctionToolCalls(response.toolCalls ?? []);
 }
-/** True for the fixture tool-call errors a handler surfaces as a coded 500. */
+/**
+* A fixture's model-generated `files` reached a wire that has no faithful
+* projection for them. Gemini (`inlineData` parts) and the OpenAI Responses
+* API (`image_generation_call` items, `image/*` only) serve generated files.
+* Chat Completions (OpenAI, Azure OpenAI, OpenRouter and BytePlus ModelArk)
+* and Anthropic Messages raise this through {@link rejectGeneratedFiles}, and
+* the Responses API raises a subclass for a non-`image/*` file, before any
+* content is written. The handler surfaces it as a coded 500
+* (`aimock_unsupported_generated_file`) like {@link UnsupportedToolCallError}.
+*/
+var UnsupportedGeneratedFileError = class extends Error {
+	wire;
+	constructor(wire) {
+		super(`aimock: fixture "files" (model-generated files) are only supported on Gemini and the OpenAI Responses API; this request arrived on ${wire}`);
+		this.name = "UnsupportedGeneratedFileError";
+		this.wire = wire;
+	}
+};
+/**
+* Reject a fixture that sets a non-empty `files` on a wire that cannot carry
+* model-generated files. Throws {@link UnsupportedGeneratedFileError} naming
+* `wire`. A malformed `files` value (see {@link fixtureFiles}) throws
+* {@link InvalidFixtureOutputError} (`aimock_invalid_fixture_file`) first.
+* Chat Completions and Anthropic Messages call this. Gemini and OpenAI
+* Responses serve `files`; other wires ignore the field.
+*/
+function rejectGeneratedFiles(response, wire) {
+	if (fixtureFiles(response.files).length > 0) throw new UnsupportedGeneratedFileError(wire);
+}
+/**
+* A fixture's `citations` or `files` is malformed: not an array, an entry
+* missing a required field, a non-integer offset, citation offsets outside
+* `0 <= startIndex <= endIndex <= text.length`, a file citation `index`
+* outside `0 <= index <= text.length`, an offset or `index` that splits a
+* UTF-16 surrogate pair, a citation that mixes URL and file citation fields,
+* or any `citations` but an empty array on a turn with no text (tool calls
+* only, `blocks` with no text block, or empty content). The wires that read
+* these keys (Chat Completions, Anthropic Messages, Gemini and OpenAI
+* Responses) read them
+* through {@link fixtureFiles} and {@link fixtureCitations}, which throw this
+* at serve time, before any byte is written; the handler surfaces it as a
+* coded 500 like {@link UnsupportedGeneratedFileError}. Other wires ignore
+* `citations` and `files`, so they never throw this. The message names the
+* offending entry and how to fix the fixture.
+*/
+var InvalidFixtureOutputError = class extends Error {
+	code;
+	constructor(code, problem) {
+		super(`aimock: invalid fixture "${code === "aimock_invalid_fixture_file" ? "files" : "citations"}": ${problem}`);
+		this.name = "InvalidFixtureOutputError";
+		this.code = code;
+	}
+};
+/**
+* A short description of a fixture value for an error message. Never throws:
+* a programmatic fixture can hold values JSON cannot carry (BigInt, Symbol,
+* function, NaN, Infinity), and each gets a readable name.
+*/
+function describeFixtureValue(value) {
+	if (value === void 0) return "undefined";
+	if (Array.isArray(value)) return "an array";
+	if (value !== null && typeof value === "object") return "an object";
+	if (typeof value === "function") return "a function";
+	if (typeof value === "symbol") return value.toString();
+	if (typeof value === "bigint") return `${value}n`;
+	if (typeof value === "number" && !Number.isFinite(value)) return String(value);
+	const json = JSON.stringify(value);
+	return json.length > 40 ? `${json.slice(0, 37)}...` : json;
+}
+/**
+* The UTF-16 index `at` falls between the two halves of a surrogate pair, so
+* a span that starts or ends there cuts a character in half.
+*/
+function splitsSurrogatePair(text, at) {
+	if (at <= 0 || at >= text.length) return false;
+	const before = text.charCodeAt(at - 1);
+	const after = text.charCodeAt(at);
+	return before >= 55296 && before <= 56319 && after >= 56320 && after <= 57343;
+}
+/**
+* `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;
+}
+/** The message for a citation offset that splits a surrogate pair. */
+function surrogateSplitProblem(where, at) {
+	return `${where} ${at} splits a UTF-16 surrogate pair (one character, e.g. an emoji); fix the offset to fall before or after the whole character`;
+}
+/** Fields only a URL citation has. */
+const URL_CITATION_FIELDS = [
+	"url",
+	"title",
+	"startIndex",
+	"endIndex"
+];
+/** Fields only a file citation has. */
+const FILE_CITATION_FIELDS = [
+	"fileId",
+	"filename",
+	"index"
+];
+/**
+* A citation that mixes URL and file citation fields, or a file-shaped one
+* (`fileId` / `filename` / `index`) with no `type`, which would otherwise be
+* read as a URL citation and lose its file data. Undefined when the fields
+* agree.
+*/
+function mixedCitationProblem(citation, i) {
+	const present = (names) => names.filter((n) => citation[n] != null);
+	const fileFields = present(FILE_CITATION_FIELDS);
+	if (fileFields.length === 0) return void 0;
+	const urlFields = present(URL_CITATION_FIELDS);
+	const fix = citation.type === "file" ? `remove the URL citation fields (${urlFields.join(", ")}) from this file citation` : citation.type === "url" ? `remove the file citation fields (${fileFields.join(", ")}) from this URL citation, or set type: "file" for a file citation` : `set type: "file" for a file citation, or remove the stray fields`;
+	if (urlFields.length > 0) return `citations[${i}] mixes URL citation fields (${urlFields.join(", ")}) with file citation fields (${fileFields.join(", ")}); ${fix}`;
+	if (citation.type == null) return `citations[${i}] has file citation fields (${fileFields.join(", ")}) but no type; ${fix}`;
+	if (citation.type === "url") return `citations[${i}] has type "url" but file citation fields (${fileFields.join(", ")}); ${fix}`;
+}
+/** "an object", "a string", ... for a value that should have been an array. */
+function describeFixtureKind(value) {
+	if (value === null) return "null";
+	if (value !== null && typeof value === "object") return "an object";
+	return typeof value === "string" ? "a string" : `a ${typeof value}`;
+}
+/**
+* What is wrong with a fixture `files` value, or undefined when it is absent
+* or an array of `{ mimeType, data }` string pairs. Shared by the serve-time
+* check ({@link fixtureFiles}) and fixture load validation.
+*/
+function fixtureFilesProblem(files) {
+	if (files === void 0 || files === null) return void 0;
+	if (!Array.isArray(files)) return `"files" must be an array of { mimeType, data } objects, got ${describeFixtureKind(files)}; wrap a single file in [ ]`;
+	for (let i = 0; i < files.length; i++) {
+		const file = files[i];
+		if (file === null || typeof file !== "object" || Array.isArray(file)) return `files[${i}] must be a { mimeType, data } object, got ${describeFixtureValue(file)}`;
+		const { mimeType, data } = file;
+		if (typeof mimeType !== "string" || mimeType.length === 0) return `files[${i}].mimeType must be a non-empty string, got ${describeFixtureValue(mimeType)}; set the file's MIME type, e.g. "image/png"`;
+		if (typeof data !== "string") return `files[${i}].data must be a string, got ${describeFixtureValue(data)}; set the base64-encoded file bytes`;
+	}
+}
+/**
+* What is wrong with a fixture `citations` value, or undefined when it is
+* absent or valid: an array of citation objects. A URL citation (no `type`,
+* or `type: "url"`) has a non-empty string `url`, an optional string `title`
+* and optional integer offsets. A file citation (`type: "file"`) has a
+* non-empty string `fileId` and `filename` and an optional integer `index`;
+* it has no `url`. When `text` is given, the resolved offsets must also
+* satisfy `0 <= startIndex <= endIndex <= text.length`, and a file citation's
+* `index` must satisfy `0 <= index <= text.length`, and no offset may split a
+* UTF-16 surrogate pair. A citation must not mix URL and file citation
+* fields, and one with file fields needs `type: "file"`. A `null` value, or a
+* `null` optional field, is treated as absent. An empty `text` is a turn with
+* no text (tool calls only, `blocks` with no text block, or empty content): a
+* well-formed non-empty array is then a problem, since there is nothing to
+* cite; a malformed value is reported by its shape first. Shared by the
+* serve-time check ({@link fixtureCitations}) and fixture load validation.
+*/
+function fixtureCitationsProblem(citations, text) {
+	if (citations === void 0 || citations === null) return void 0;
+	if (!Array.isArray(citations)) return `"citations" must be an array of { url, title?, startIndex?, endIndex? } or { type: "file", fileId, filename, index? } objects, got ${describeFixtureKind(citations)}; wrap a single citation in [ ]`;
+	const shape = citationEntriesProblem(citations, void 0);
+	if (shape !== void 0 || text === void 0) return shape;
+	if (text === "" && citations.length > 0) return "\"citations\" has nothing to cite: this turn has no text (only tool calls, or empty content); add text to the response or remove the citations";
+	return citationEntriesProblem(citations, text);
+}
+/**
+* What is wrong with the entries of a `citations` array, or undefined when
+* all are valid. Offsets are checked against `text` only when it is given. A
+* `null` optional field (`type`, `title`, `startIndex`, `endIndex`, `index`)
+* is treated as absent, as a `null` top-level key is.
+*/
+function citationEntriesProblem(citations, text) {
+	for (let i = 0; i < citations.length; i++) {
+		const citation = citations[i];
+		if (citation === null || typeof citation !== "object" || Array.isArray(citation)) return `citations[${i}] must be a { url, title?, startIndex?, endIndex? } or { type: "file", fileId, filename, index? } object, got ${describeFixtureValue(citation)}`;
+		const fields = citation;
+		const url = fields.url;
+		const type = fields.type ?? void 0;
+		const title = fields.title ?? void 0;
+		const startIndex = fields.startIndex ?? void 0;
+		const endIndex = fields.endIndex ?? void 0;
+		if (type === void 0 || type === "url" || type === "file") {
+			const mixed = mixedCitationProblem(citation, i);
+			if (mixed !== void 0) return mixed;
+		}
+		if (type === "file") {
+			const problem = fixtureFileCitationProblem(citation, i, text);
+			if (problem !== void 0) return problem;
+			continue;
+		}
+		if (type !== void 0 && type !== "url") return `citations[${i}].type must be "url" or "file" when set, got ${describeFixtureValue(type)}; omit it for a URL citation`;
+		if (typeof url !== "string" || url.length === 0) return `citations[${i}].url must be a non-empty string, got ${describeFixtureValue(url)}; set the cited source URL`;
+		if (title !== void 0 && typeof title !== "string") return `citations[${i}].title must be a string when set, got ${describeFixtureValue(title)}`;
+		for (const [name, value] of [["startIndex", startIndex], ["endIndex", endIndex]]) if (value !== void 0 && !Number.isInteger(value)) return `citations[${i}].${name} must be an integer when set, got ${describeFixtureValue(value)}; give a character offset into the text, or omit it`;
+		if (text === void 0) continue;
+		const start = startIndex ?? 0;
+		const end = endIndex ?? text.length;
+		if (start < 0 || start > end || end > text.length) return `citations[${i}] offsets must satisfy 0 <= startIndex <= endIndex <= text length (${text.length}), got startIndex ${start}, endIndex ${end}; fix the offsets, or omit them to cite the whole text`;
+		if (splitsSurrogatePair(text, start)) return surrogateSplitProblem(`citations[${i}].startIndex`, start);
+		if (splitsSurrogatePair(text, end)) return surrogateSplitProblem(`citations[${i}].endIndex`, end);
+	}
+}
+/** What is wrong with the file citation `citations[i]`, or undefined when valid. */
+function fixtureFileCitationProblem(citation, i, text) {
+	const { fileId, filename } = citation;
+	const index = citation.index ?? void 0;
+	if (typeof fileId !== "string" || fileId.length === 0) return `citations[${i}].fileId must be a non-empty string, got ${describeFixtureValue(fileId)}; set the cited file's ID, e.g. "file-abc123"`;
+	if (typeof filename !== "string" || filename.length === 0) return `citations[${i}].filename must be a non-empty string, got ${describeFixtureValue(filename)}; set the cited file's name`;
+	if (index !== void 0 && !Number.isInteger(index)) return `citations[${i}].index must be an integer when set, got ${describeFixtureValue(index)}; give a character position in the text, or omit it`;
+	if (text === void 0) return void 0;
+	const at = index ?? text.length;
+	if (at < 0 || at > text.length) return `citations[${i}].index must satisfy 0 <= index <= text length (${text.length}), got ${at}; fix the index, or omit it to cite the end of the text`;
+	if (splitsSurrogatePair(text, at)) return surrogateSplitProblem(`citations[${i}].index`, at);
+}
+/**
+* Fixture `citations`, checked against the text they cite: the array itself,
+* or empty when absent. Throws {@link InvalidFixtureOutputError}
+* (`aimock_invalid_fixture_citation`) for every problem
+* {@link fixtureCitationsProblem} reports: a malformed value, an offset
+* outside the text or one that splits a surrogate pair, mixed URL and file
+* citation fields, or citations on a turn with no text (`content` is empty:
+* tool calls only, `blocks` with no text block, or empty content). Every
+* provider that reads `citations` goes through this.
+*/
+function fixtureCitations(content, citations) {
+	const problem = fixtureCitationsProblem(citations, content);
+	if (problem !== void 0) throw new InvalidFixtureOutputError("aimock_invalid_fixture_citation", problem);
+	return citations ?? [];
+}
+/**
+* Fixture `files`, checked: the array itself, or empty when absent. Throws
+* {@link InvalidFixtureOutputError} (`aimock_invalid_fixture_file`) for a
+* malformed value. Every provider that reads `files` goes through this.
+*/
+function fixtureFiles(files) {
+	const problem = fixtureFilesProblem(files);
+	if (problem !== void 0) throw new InvalidFixtureOutputError("aimock_invalid_fixture_file", problem);
+	return files ?? [];
+}
+/**
+* Fixture URL `citations` against the text they cite, with defaults applied:
+* the title falls back to the URL and the offsets to the whole text. Empty
+* when the fixture sets none. File citations (`type: "file"`) are skipped:
+* only OpenAI Responses has a wire shape for them (`file_citation`), and it
+* builds those itself. Chat Completions, Anthropic Messages and Gemini, which
+* resolve through here, serve URL citations only. This reads `citations`
+* through {@link fixtureCitations}, so it is the serve-time check for those
+* three wires: every problem {@link fixtureCitationsProblem} reports against
+* `content`, including one in a file citation it then skips, throws
+* {@link InvalidFixtureOutputError} (`aimock_invalid_fixture_citation`).
+* OpenAI Responses calls {@link fixtureCitations} directly. Other wires
+* ignore `citations`.
+*/
+function resolveCitations(content, citations) {
+	return fixtureCitations(content, citations).flatMap((c) => c.type === "file" ? [] : [c]).map((c) => ({
+		url: c.url,
+		title: c.title ?? c.url,
+		startIndex: c.startIndex ?? 0,
+		endIndex: c.endIndex ?? content.length
+	}));
+}
+/**
+* Fixture `citations` as Chat Completions `url_citation` annotations. File
+* citations are skipped (see {@link resolveCitations}): Chat Completions has no
+* `file_citation` annotation.
+*/
+function chatCompletionAnnotations(content, citations) {
+	return resolveCitations(content, citations).map((c) => ({
+		type: "url_citation",
+		url_citation: {
+			url: c.url,
+			title: c.title,
+			start_index: c.startIndex,
+			end_index: c.endIndex
+		}
+	}));
+}
+/** `{ annotations }` for a Chat Completions message, or nothing when the fixture has no citations. */
+function annotationsField(content, overrides) {
+	const annotations = chatCompletionAnnotations(content, overrides?.citations);
+	return annotations.length > 0 ? { annotations } : {};
+}
+/**
+* The streamed form of {@link chatCompletionAnnotations}: one chunk whose
+* `delta.annotations` holds every annotation, sent after the content and
+* before the finish chunk. Nothing when the fixture has no citations.
+*/
+function chatAnnotationChunks(content, overrides, envelope) {
+	const annotations = chatCompletionAnnotations(content, overrides?.citations);
+	if (annotations.length === 0) return [];
+	const fingerprint = overrides?.systemFingerprint;
+	return [{
+		id: envelope.id,
+		object: "chat.completion.chunk",
+		created: envelope.created,
+		model: envelope.model,
+		choices: [{
+			index: 0,
+			delta: { annotations },
+			logprobs: null,
+			finish_reason: null
+		}],
+		...fingerprint !== void 0 && { system_fingerprint: fingerprint }
+	}];
+}
+/** True for the fixture errors a handler surfaces as a coded 500. */
 function isFixtureToolCallError(error) {
-	return error instanceof InvalidToolArgumentsError || error instanceof UnsupportedToolCallError || error instanceof InvalidFixtureToolCallError;
+	return error instanceof InvalidToolArgumentsError || error instanceof UnsupportedToolCallError || error instanceof InvalidFixtureToolCallError || error instanceof UnsupportedGeneratedFileError || error instanceof InvalidFixtureOutputError;
 }
 /** The aimock error code carried in every provider envelope for a fixture tool-call error. */
 function fixtureToolCallErrorCode(error) {
+	if (error instanceof UnsupportedGeneratedFileError) return "aimock_unsupported_generated_file";
+	if (error instanceof InvalidFixtureOutputError) return error.code;
 	if (error instanceof UnsupportedToolCallError) return "aimock_unsupported_tool_call";
 	if (error instanceof InvalidFixtureToolCallError) return error.code;
 	return "aimock_invalid_tool_arguments";
@@ -236,9 +558,10 @@ function googleFixtureToolCallErrorDetails(code) {
 	}];
 }
 /**
-* Run a WebSocket preflight `check` that may raise a fixture tool-call error
-* ({@link InvalidToolArgumentsError}, {@link UnsupportedToolCallError} or
-* {@link InvalidFixtureToolCallError}).
+* Run a WebSocket preflight `check` that may raise a fixture error
+* ({@link InvalidToolArgumentsError}, {@link UnsupportedToolCallError},
+* {@link InvalidFixtureToolCallError}, {@link UnsupportedGeneratedFileError}
+* or {@link InvalidFixtureOutputError}).
 * Such an error marks the already-journaled entry as a 500 carrying the
 * message, then propagates to the transport's error handler.
 */
@@ -253,27 +576,6 @@ function journalFixtureToolCallError(journalEntry, check) {
 		throw error;
 	}
 }
-/**
-* Resolve effective strict mode from per-request header and server default.
-* Header values override the server default — same precedence pattern as chaos
-* config headers (see resolveChaosConfig in chaos.ts).
-*
-* Header: `X-AIMock-Strict` — "true"/"1" → strict on, "false"/"0" → strict off
-* (case-insensitive, surrounding whitespace trimmed).
-* When absent or unrecognised, falls back to the server-level default.
-*/
-function resolveStrictMode(serverDefault, rawHeaders) {
-	if (rawHeaders) {
-		const header = rawHeaders["x-aimock-strict"];
-		const rawVal = typeof header === "string" ? header : Array.isArray(header) ? header[0] : void 0;
-		if (typeof rawVal === "string") {
-			const val = rawVal.trim().toLowerCase();
-			if (val === "true" || val === "1") return true;
-			if (val === "false" || val === "0") return false;
-		}
-	}
-	return serverDefault ?? false;
-}
 const STRICT_INTEGER_RE = /^\d+$/;
 /**
 * Strict decimal-integer grammar shared by the query/list parsers that grew
@@ -306,18 +608,6 @@ function wouldProxyMiss(effectiveStrict, record, providerKey) {
 	return Boolean(record?.providers?.[providerKey]);
 }
 /**
-* Returns `true` or `false` when the X-AIMock-Strict header overrides the
-* server default, or `undefined` when it doesn't. Designed to be spread
-* directly into a journal entry's `response` object:
-*
-*   response: { status, fixture, ...strictOverrideField(defaults.strict, req.headers) }
-*/
-function strictOverrideField(serverDefault, rawHeaders) {
-	const effective = resolveStrictMode(serverDefault, rawHeaders);
-	if (effective !== (serverDefault ?? false)) return { strictOverride: effective };
-	return {};
-}
-/**
 * Build the strict-mode 503 error message, distinguishing a true no-match from
 * a sequence/turn-exhausted miss.
 *
@@ -1055,12 +1345,7 @@ function isErrorResponse(r) {
 * response body.  Real LLM APIs don't include it.
 */
 function serializeErrorResponse(response) {
-	return JSON.stringify({ error: {
-		message: response.error.message,
-		type: response.error.type ?? "server_error",
-		param: response.error.param ?? null,
-		code: response.error.code ?? null
-	} });
+	return renderError("openai", "fixture", response.error).body;
 }
 function isEmbeddingResponse(r) {
 	return "embedding" in r && Array.isArray(r.embedding);
@@ -1101,9 +1386,47 @@ function isVideoResponse(r) {
 function isJSONResponse(r) {
 	return "json" in r && r.json !== void 0;
 }
+/**
+* Every key some other response guard reads. A response carrying any of them
+* is that type (with a stray `raw` key the loader has always ignored), never
+* a raw response — so adding raw support changes nothing for such fixtures.
+*/
+const NON_RAW_RESPONSE_MARKERS = [
+	"content",
+	"toolCalls",
+	"blocks",
+	"responsesBlocks",
+	"customToolCalls",
+	"error",
+	"embedding",
+	"image",
+	"images",
+	"audio",
+	"transcription",
+	"video",
+	"json",
+	"live"
+];
+/**
+* @internal Whether `r` is a raw passthrough response: `raw` is a non-null,
+* non-array object and no other response type's marker key is present. The
+* shape of `raw` itself is checked by the loader and again at serve time.
+* Exported for in-repo use only; not part of the public API.
+*
+* A fixture added in code can hold a response that is not an object (null, a
+* string). `in` throws on such a value, so it is simply not raw.
+*/
+function isRawResponse(r) {
+	if (typeof r !== "object" || r === null || !("raw" in r)) return false;
+	const raw = r.raw;
+	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return false;
+	return !NON_RAW_RESPONSE_MARKERS.some((marker) => marker in r);
+}
 function extractOverrides(response) {
 	const r = response;
 	return {
+		...r.citations !== void 0 && { citations: r.citations },
+		...r.files !== void 0 && { files: r.files },
 		...r.id !== void 0 && { id: r.id },
 		...r.created !== void 0 && { created: r.created },
 		...r.model !== void 0 && { model: r.model },
@@ -1111,6 +1434,7 @@ function extractOverrides(response) {
 		...r.systemFingerprint !== void 0 && { systemFingerprint: r.systemFingerprint },
 		...r.finishReason !== void 0 && { finishReason: r.finishReason },
 		...r.role !== void 0 && { role: r.role },
+		...r.phase !== void 0 && { phase: r.phase },
 		...r.provider !== void 0 && { provider: r.provider },
 		...r.nativeFinishReason !== void 0 && { nativeFinishReason: r.nativeFinishReason }
 	};
@@ -1120,18 +1444,13 @@ function extractOverrides(response) {
 * Uses the ~4 characters per token heuristic common for English text.
 */
 function estimateTokens(text) {
-	return Math.max(1, Math.ceil(text.length / 4));
+	return estimateTokens$1(text);
 }
 /**
 * Estimate prompt tokens from a request's messages array.
 */
 function estimatePromptTokens(messages) {
-	let totalChars = 0;
-	for (const msg of messages) if (typeof msg.content === "string") totalChars += msg.content.length;
-	else if (Array.isArray(msg.content)) {
-		for (const part of msg.content) if (part.text) totalChars += part.text.length;
-	}
-	return Math.max(1, Math.ceil(totalChars / 4));
+	return estimatePromptTokens$1(messages);
 }
 /**
 * Build usage object: use explicit overrides if provided, otherwise estimate.
@@ -1142,26 +1461,10 @@ function estimatePromptTokens(messages) {
 * so the streaming path does not re-implement the estimation logic.
 */
 function resolveUsage(overrides, promptText, completionText) {
-	if (overrides?.usage) {
-		const u = overrides.usage;
-		const hasExplicitTokens = u.prompt_tokens !== void 0 || u.completion_tokens !== void 0 || u.total_tokens !== void 0 || u.input_tokens !== void 0 || u.output_tokens !== void 0 || u.promptTokenCount !== void 0 || u.candidatesTokenCount !== void 0 || u.totalTokenCount !== void 0;
-		const fallbackPrompt = hasExplicitTokens ? 0 : estimateTokens(promptText || "x");
-		const fallbackCompletion = hasExplicitTokens ? 0 : estimateTokens(completionText || "x");
-		const prompt = u.prompt_tokens ?? u.input_tokens ?? u.promptTokenCount ?? fallbackPrompt;
-		const completion = u.completion_tokens ?? u.output_tokens ?? u.candidatesTokenCount ?? fallbackCompletion;
-		return {
-			prompt_tokens: prompt,
-			completion_tokens: completion,
-			total_tokens: u.total_tokens ?? u.totalTokenCount ?? prompt + completion
-		};
-	}
-	const prompt = estimateTokens(promptText || "x");
-	const completion = estimateTokens(completionText || "x");
-	return {
-		prompt_tokens: prompt,
-		completion_tokens: completion,
-		total_tokens: prompt + completion
-	};
+	return render(resolve(overrides, {
+		promptText,
+		completionText
+	}));
 }
 /**
 * Build an SSE usage chunk for streaming responses.
@@ -1233,6 +1536,11 @@ function buildTextChunks(content, model, chunkSize, reasoning, overrides) {
 			...fingerprint !== void 0 && { system_fingerprint: fingerprint }
 		});
 	}
+	chunks.push(...chatAnnotationChunks(content, overrides, {
+		id,
+		created,
+		model: effectiveModel
+	}));
 	chunks.push({
 		id,
 		object: "chat.completion.chunk",
@@ -1252,6 +1560,7 @@ function buildTextChunks(content, model, chunkSize, reasoning, overrides) {
 function buildOpenAIReasoningChunks(reasoning, model, chunkSize, exposeReasoning, overrides) {
 	return buildTextChunks(exposeReasoning ? reasoning : "", model, chunkSize, void 0, {
 		...overrides,
+		citations: void 0,
 		role: "assistant",
 		finishReason: "length"
 	}).map((chunk) => ({
@@ -1280,6 +1589,7 @@ function buildOpenAIReasoningCompletion(reasoning, model, exposeReasoning, overr
 	const visible = exposeReasoning ? reasoning : "";
 	const completion = buildTextCompletion(visible, model, void 0, {
 		...overrides,
+		citations: void 0,
 		role: "assistant",
 		finishReason: "length",
 		usage: void 0
@@ -1309,6 +1619,7 @@ function buildOpenAIReasoningCompletion(reasoning, model, exposeReasoning, overr
 function buildOpenAIContentFilterChunks(model, overrides) {
 	return buildTextChunks("", model, 1, void 0, {
 		...overrides,
+		citations: void 0,
 		role: "assistant",
 		finishReason: "content_filter"
 	}).map((chunk) => ({
@@ -1326,6 +1637,7 @@ function buildOpenAIContentFilterChunks(model, overrides) {
 function buildOpenAIContentFilterCompletion(model, overrides, requestMessages) {
 	const completion = buildTextCompletion("", model, void 0, {
 		...overrides,
+		citations: void 0,
 		role: "assistant",
 		finishReason: "content_filter",
 		usage: void 0
@@ -1346,6 +1658,7 @@ function buildOpenAIContentFilterCompletion(model, overrides, requestMessages) {
 function buildOpenAIRefusalChunks(refusal, model, chunkSize, overrides) {
 	return buildTextChunks(refusal, model, chunkSize, void 0, {
 		...overrides,
+		citations: void 0,
 		role: "assistant",
 		finishReason: "stop"
 	}).map((chunk) => ({
@@ -1366,6 +1679,7 @@ function buildOpenAIRefusalChunks(refusal, model, chunkSize, overrides) {
 function buildOpenAIRefusalCompletion(refusal, model, overrides, requestMessages) {
 	const completion = buildTextCompletion(refusal, model, void 0, {
 		...overrides,
+		citations: void 0,
 		role: "assistant",
 		finishReason: "stop",
 		usage: void 0
@@ -1383,6 +1697,7 @@ function buildOpenAIRefusalCompletion(refusal, model, overrides, requestMessages
 	};
 }
 function buildToolCallChunks(toolCalls, model, chunkSize, reasoning, overrides) {
+	fixtureCitations("", overrides?.citations);
 	const id = overrides?.id ?? generateId();
 	const created = overrides?.created ?? Math.floor(Date.now() / 1e3);
 	const effectiveModel = overrides?.model ?? model;
@@ -1493,7 +1808,8 @@ function buildTextCompletion(content, model, reasoning, overrides, requestMessag
 				role: overrides?.role ?? "assistant",
 				content,
 				refusal: null,
-				...reasoning ? { reasoning_content: reasoning } : {}
+				...reasoning ? { reasoning_content: reasoning } : {},
+				...annotationsField(content, overrides)
 			},
 			logprobs: null,
 			finish_reason: overrides?.finishReason ?? "stop"
@@ -1503,6 +1819,7 @@ function buildTextCompletion(content, model, reasoning, overrides, requestMessag
 	};
 }
 function buildToolCallCompletion(toolCalls, model, reasoning, overrides, requestMessages) {
+	fixtureCitations("", overrides?.citations);
 	const promptText = requestMessages ? requestMessages.map((m) => typeof m.content === "string" ? m.content : Array.isArray(m.content) ? m.content.map((p) => p.text ?? "").join("") : "").join("") : "";
 	const completionText = toolCalls.map((tc) => tc.name + tc.arguments).join("");
 	return {
@@ -1639,6 +1956,11 @@ function buildContentWithToolCallsChunks(content, toolCalls, model, chunkSize, r
 			}
 			tcIdx++;
 		}
+		chunks.push(...chatAnnotationChunks(outcome.content, overrides, {
+			id,
+			created,
+			model: effectiveModel
+		}));
 		chunks.push({
 			id,
 			object: "chat.completion.chunk",
@@ -1750,6 +2072,11 @@ function buildContentWithToolCallsChunks(content, toolCalls, model, chunkSize, r
 			});
 		}
 	}
+	chunks.push(...chatAnnotationChunks(content, overrides, {
+		id,
+		created,
+		model: effectiveModel
+	}));
 	chunks.push({
 		id,
 		object: "chat.completion.chunk",
@@ -1787,7 +2114,8 @@ function buildContentWithToolCallsCompletion(content, toolCalls, model, reasonin
 						name: tc.name,
 						arguments: tc.arguments
 					}
-				}))
+				})),
+				...annotationsField(content, overrides)
 			},
 			logprobs: null,
 			finish_reason: overrides?.finishReason ?? "tool_calls"
@@ -2429,5 +2757,5 @@ function parseMcpUndeclared(raw) {
 }
 
 //#endregion
-export { FORMAT_TO_CONTENT_TYPE, InvalidFixtureToolCallError, InvalidToolArgumentsError, MAX_EMBEDDING_DIMENSIONS, RequestBodyTooLargeError, UnsupportedToolCallError, assertCustomToolCalls, assertResponsesToolCalls, buildContentWithToolCallsChunks, buildContentWithToolCallsCompletion, buildEmbeddingResponse, buildOpenAIContentFilterChunks, buildOpenAIContentFilterCompletion, buildOpenAIReasoningChunks, buildOpenAIReasoningCompletion, buildOpenAIRefusalChunks, buildOpenAIRefusalCompletion, buildTextChunks, buildTextCompletion, buildToolCallChunks, buildToolCallCompletion, buildUsageChunk, createServerFixtureList, decodeMcpHeaderValue, describeMatch, estimatePromptTokens, estimateTokens, extractOverrides, fixtureListTarget, fixtureToolCallErrorCode, flattenHeaders, formatToMime, generateDeterministicEmbedding, generateId, generateMessageId, generateToolCallId, generateToolUseId, getContext, getTestId, googleFixtureToolCallErrorDetails, hasMintedRequestId, isAudioResponse, isCombinedFixtureResponse, isContentWithToolCallsResponse, isEmbeddingResponse, isErrorResponse, isExtendedResponsesToolsList, isFixtureToolCallError, isImageResponse, isJSONResponse, isJsonObject, isLiveResponse, isResponseFactory, isServerOwnedFixtures, isTextResponse, isToolCallResponse, isTranscriptionResponse, isVideoResponse, journalFixtureToolCallError, keepAuthoredToolArguments, markExtendedResponsesToolsRequest, markMintedRequestId, markServerOwnedFixtures, matchesPattern, normalizeEmbeddingInput, normalizeTextInput, parseStrictIntegerText, prepareOpenAIChatMisbehavior, readBody, readBodyBufferBounded, rebuildOrderedBlocks, rejectResponsesOnlyToolCalls, requireEmittedFunctionToolCalls, requireFunctionToolCalls, requireServedFunctionToolCalls, resolveFixtureBlockOutcome, resolveFixtureBlocks, resolveMcpIdentity, resolveOpenAIChatMisbehaviorUsage, resolveReasoningArtifactsForModel, resolveReasoningForModel, resolveRequestId, resolveResponse, resolveResponsesBlocks, resolveServedBlockOutcome, resolveStrictMode, resolveTestId, resolveUsage, runWithToolArgumentsScope, serializeErrorResponse, servedToolArgs, servedToolCalls, slugifyContext, slugifyTestId, strictNoMatchLogLine, strictNoMatchMessage, strictOverrideField, strictToolArgumentsEnabled, toolArgsForWire, toolCallFixtureBlock, validateChatMessages, validateEmbeddingDimensions, validateToolsField, withServedToolCalls, withoutLegacyNamespaces, withoutResponsesToolKeys, wouldProxyMiss };
+export { FORMAT_TO_CONTENT_TYPE, InvalidFixtureOutputError, InvalidFixtureToolCallError, InvalidToolArgumentsError, MAX_EMBEDDING_DIMENSIONS, RequestBodyTooLargeError, UnsupportedGeneratedFileError, UnsupportedToolCallError, assertCustomToolCalls, assertResponsesToolCalls, buildContentWithToolCallsChunks, buildContentWithToolCallsCompletion, buildEmbeddingResponse, buildOpenAIContentFilterChunks, buildOpenAIContentFilterCompletion, buildOpenAIReasoningChunks, buildOpenAIReasoningCompletion, buildOpenAIRefusalChunks, buildOpenAIRefusalCompletion, buildTextChunks, buildTextCompletion, buildToolCallChunks, buildToolCallCompletion, buildUsageChunk, createServerFixtureList, decodeMcpHeaderValue, describeMatch, estimatePromptTokens, estimateTokens, extractOverrides, fixtureCitations, fixtureCitationsProblem, fixtureFiles, fixtureFilesProblem, fixtureListTarget, fixtureToolCallErrorCode, flattenHeaders, formatToMime, generateDeterministicEmbedding, generateId, generateMessageId, generateToolCallId, generateToolUseId, getContext, getTestId, googleFixtureToolCallErrorDetails, hasMintedRequestId, isAudioResponse, isCombinedFixtureResponse, isContentWithToolCallsResponse, isEmbeddingResponse, isErrorResponse, isExtendedResponsesToolsList, isFixtureToolCallError, isImageResponse, isJSONResponse, isJsonObject, isLiveResponse, isRawResponse, isResponseFactory, isServerOwnedFixtures, isTextResponse, isToolCallResponse, isTranscriptionResponse, isVideoResponse, journalFixtureToolCallError, keepAuthoredToolArguments, markExtendedResponsesToolsRequest, markMintedRequestId, markServerOwnedFixtures, matchesPattern, normalizeEmbeddingInput, normalizeTextInput, parseStrictIntegerText, prepareOpenAIChatMisbehavior, readBody, readBodyBufferBounded, rebuildOrderedBlocks, rejectGeneratedFiles, rejectResponsesOnlyToolCalls, requireEmittedFunctionToolCalls, requireFunctionToolCalls, requireServedFunctionToolCalls, resolveCitations, resolveFixtureBlockOutcome, resolveFixtureBlocks, resolveMcpIdentity, resolveOpenAIChatMisbehaviorUsage, resolveReasoningArtifactsForModel, resolveReasoningForModel, resolveRequestId, resolveResponse, resolveResponsesBlocks, resolveServedBlockOutcome, resolveTestId, resolveUsage, runWithToolArgumentsScope, serializeErrorResponse, servedToolArgs, servedToolCalls, slugifyContext, slugifyTestId, strictNoMatchLogLine, strictNoMatchMessage, strictToolArgumentsEnabled, surrogateSafeChunks, toolArgsForWire, toolCallFixtureBlock, validateChatMessages, validateEmbeddingDimensions, validateToolsField, withServedToolCalls, withoutLegacyNamespaces, withoutResponsesToolKeys, wouldProxyMiss };
 //# sourceMappingURL=helpers.js.map