@copilotkit/aimock 1.43.0 → 1.45.0

package/dist/helpers.js

@@ -1,9 +1,258 @@
-import { DEFAULT_TEST_ID } from "./constants.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";
 import { isReasoningModel } from "./model-utils.js";
 import { isRecognizedApiKeyHeader } from "./api-key-auth.js";
+import { AsyncLocalStorage } from "node:async_hooks";
 import { createHash, randomBytes } from "node:crypto";
 
 //#region src/helpers.ts
+/** Preserve authored text for string wires without silently repairing invalid JSON. */
+function toolArgsForWire(tc) {
+	const raw = tc.arguments || "{}";
+	try {
+		const value = JSON.parse(raw);
+		return {
+			kind: "parsed",
+			value,
+			text: JSON.stringify(value),
+			raw
+		};
+	} catch {
+		return {
+			kind: "verbatim",
+			raw
+		};
+	}
+}
+/** Object wires reject the verbatim branch; string wires never need this error. */
+var InvalidToolArgumentsError = class extends Error {
+	toolName;
+	parseDiagnostic;
+	constructor(tc) {
+		let parseDiagnostic = "";
+		try {
+			JSON.parse(tc.arguments || "{}");
+		} catch (error) {
+			parseDiagnostic = error instanceof Error ? error.message : String(error);
+		}
+		super(`aimock: fixture tool call "${tc.name}" has invalid JSON arguments; this wire carries arguments as an object. Use a wire that carries tool arguments as a string to test malformed JSON. (${parseDiagnostic})`);
+		this.name = "InvalidToolArgumentsError";
+		this.toolName = tc.name;
+		this.parseDiagnostic = parseDiagnostic;
+	}
+};
+const toolArgumentsScope = new AsyncLocalStorage();
+/** Run `fn` with the `strictToolArguments` setting and logger of one request. */
+function runWithToolArgumentsScope(scope, fn) {
+	return toolArgumentsScope.run(scope, fn);
+}
+/** Whether `strictToolArguments` is on for the request being served (default off). */
+function strictToolArgumentsEnabled() {
+	return toolArgumentsScope.getStore()?.strict === true;
+}
+/**
+* Serve the rest of this request's tool arguments as authored (the
+* `strictToolArguments` behavior). An applied misbehavior fault calls this so
+* that the malformed arguments it injects are not replaced with `{}`; the
+* planner only applies a fault to a fixture whose own arguments are valid
+* wherever the default would replace them.
+*/
+function keepAuthoredToolArguments() {
+	const scope = toolArgumentsScope.getStore();
+	if (scope) scope.strict = true;
+}
+/**
+* The fixture tool-call arguments a wire serves on its normal (no misbehavior)
+* path. Valid JSON gives the parsed value, its re-serialized text, and the
+* authored text. Invalid JSON logs one warning and, by default, is served as
+* `{}` / `"{}"`, as in 1.44.0. With `strictToolArguments`, an object wire
+* (`"object"`) throws {@link InvalidToolArgumentsError} and a string wire
+* (`"string"`) serves the authored text unchanged.
+*/
+function servedToolArgs(tc, wire, logger) {
+	const args = toolArgsForWire(tc);
+	if (args.kind === "parsed") return args;
+	const scope = toolArgumentsScope.getStore();
+	(logger ?? scope?.logger)?.warn(`Malformed JSON in fixture tool call arguments for "${tc.name}": ${tc.arguments}`);
+	if (scope?.strict !== true) return {
+		value: {},
+		text: "{}",
+		raw: "{}"
+	};
+	if (wire === "object") throw new InvalidToolArgumentsError(tc);
+	return {
+		value: void 0,
+		text: args.raw,
+		raw: args.raw
+	};
+}
+/**
+* A custom (freeform) tool call reached a wire that has no faithful projection
+* for it. Only the OpenAI Responses API (HTTP and WebSocket) emits custom tool
+* calls, from a fixture's `customToolCalls` or a `customToolCall` block in its
+* `responsesBlocks`. The handlers of the other wires raise this through
+* {@link rejectResponsesOnlyToolCalls} (usually via
+* {@link requireEmittedFunctionToolCalls}) before they write any content.
+* Ollama `/api/generate` is the exception: it rejects every tool-call fixture
+* with a 400 before this check.
+*/
+var UnsupportedToolCallError = class extends Error {
+	toolName;
+	wire;
+	constructor(toolName, wire) {
+		super(`aimock: fixture tool call "${toolName}" is a custom tool call, which only the OpenAI Responses API supports; this request arrived on ${wire}`);
+		this.name = "UnsupportedToolCallError";
+		this.toolName = toolName;
+		this.wire = wire;
+	}
+};
+/**
+* A fixture tool call is malformed: a `toolCalls` entry that is not an object,
+* a malformed `customToolCalls` entry, or a malformed tool block in
+* `responsesBlocks`. Programmatic and factory fixtures skip load validation,
+* so this request-time guard is their validation for the rules
+* {@link assertResponsesToolCalls} and {@link resolveResponsesBlocks} check.
+* An HTTP request then fails with a 500 that carries this message and `code`;
+* a WebSocket turn gets the transport's error message with the code. A
+* malformed legacy `blocks` entry keeps the plain Error of
+* {@link resolveFixtureBlocks}.
+*/
+var InvalidFixtureToolCallError = class extends Error {
+	code = "aimock_invalid_fixture_tool_call";
+	constructor(index, problem, carrier = "toolCalls") {
+		super(carrier === "blocks" ? `Invalid fixture block at index ${index}: ${problem}` : `Invalid fixture tool call: ${problem} (${carrier}[${index}])`);
+		this.name = "InvalidFixtureToolCallError";
+	}
+};
+/**
+* Request-time guard for one custom tool call (a `customToolCalls` entry).
+* Programmatic and factory fixtures skip load validation, so this is their
+* validation: an object with a non-empty string `name`, a string `input`, no
+* `arguments`, a string `id` when present and a non-empty string `namespace`
+* when present.
+*/
+function assertCustomToolCall(call, index) {
+	const fail = (problem) => {
+		throw new InvalidFixtureToolCallError(index, problem, "customToolCalls");
+	};
+	if (!isPlainObject(call)) fail("expected an object");
+	const tc = call;
+	if (tc.namespace !== void 0 && (typeof tc.namespace !== "string" || tc.namespace === "")) fail("\"namespace\" must be a non-empty string when present");
+	if (typeof tc.name !== "string" || tc.name === "") fail("custom tool call requires a non-empty string \"name\" field");
+	if (typeof tc.input !== "string") fail("\"input\" must be a string for a custom tool call");
+	if (tc.arguments !== void 0) fail("custom tool call takes \"input\", not \"arguments\"");
+	if (tc.id !== void 0 && typeof tc.id !== "string") fail("custom tool call \"id\" must be a string when present");
+}
+/**
+* Validate a response's `customToolCalls` (OpenAI Responses only) before it is
+* served. Throws {@link InvalidFixtureToolCallError} on the first malformed
+* entry. The key is new, so no fixture of an earlier release reaches this.
+*/
+function assertCustomToolCalls(response) {
+	const list = response.customToolCalls;
+	if (list === void 0) return;
+	if (!Array.isArray(list)) throw new InvalidFixtureToolCallError(0, "customToolCalls must be an array", "customToolCalls");
+	list.forEach((call, i) => assertCustomToolCall(call, i));
+}
+/**
+* Validate the custom calls among the tool calls the OpenAI Responses API is
+* about to serve (see {@link servedToolCalls}). Function calls are not
+* checked here: they keep the handling of earlier releases (a non-string
+* `arguments` fails with the uncoded error of the Responses builders).
+*/
+function assertResponsesToolCalls(calls) {
+	let customIndex = 0;
+	for (const tc of calls) if (isPlainObject(tc) && tc.type === "custom") assertCustomToolCall(tc, customIndex++);
+}
+/**
+* A fixture's `toolCalls` for a wire that cannot carry custom tool calls.
+* Every entry is a function call and passes through unchanged, exactly as in
+* earlier releases (the builders read its `name`, `arguments` and `id`; its
+* Responses-only `namespace` is not emitted). Custom calls live in
+* `customToolCalls`, which {@link rejectResponsesOnlyToolCalls} rejects.
+*/
+function requireFunctionToolCalls(calls) {
+	return calls;
+}
+/**
+* Reject the Responses-only custom tool calls on a wire that cannot carry
+* them: a non-empty `customToolCalls`, or a `customToolCall` block in
+* `responsesBlocks`. Throws {@link UnsupportedToolCallError} naming `wire`.
+* Both keys are new, so no fixture of an earlier release reaches this error.
+*/
+function rejectResponsesOnlyToolCalls(response, wire) {
+	const r = response;
+	if (Array.isArray(r.customToolCalls) && r.customToolCalls.length > 0) {
+		const first = r.customToolCalls[0];
+		throw new UnsupportedToolCallError(isPlainObject(first) && typeof first.name === "string" ? first.name : "", wire);
+	}
+	if (Array.isArray(r.responsesBlocks)) {
+		for (const block of r.responsesBlocks) if (isPlainObject(block) && block.type === "customToolCall") throw new UnsupportedToolCallError(typeof block.name === "string" ? block.name : "", wire);
+	}
+}
+/**
+* {@link rejectResponsesOnlyToolCalls}, then {@link requireFunctionToolCalls}
+* on the response's `toolCalls` (ignoring any `blocks`).
+*/
+function requireServedFunctionToolCalls(response, wire) {
+	rejectResponsesOnlyToolCalls(response, wire);
+	return requireFunctionToolCalls(response.toolCalls ?? []);
+}
+/**
+* The function calls a non-Responses wire emits for this response, after
+* {@link rejectResponsesOnlyToolCalls}. Non-empty ordered `blocks` are
+* authoritative: the builders stream them (and validate them through
+* {@link resolveFixtureBlocks}) and never emit the legacy `toolCalls`, so the
+* result is empty. Without blocks, `toolCalls` is checked by
+* {@link requireFunctionToolCalls}.
+*/
+function requireEmittedFunctionToolCalls(response, wire) {
+	rejectResponsesOnlyToolCalls(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. */
+function isFixtureToolCallError(error) {
+	return error instanceof InvalidToolArgumentsError || error instanceof UnsupportedToolCallError || error instanceof InvalidFixtureToolCallError;
+}
+/** The aimock error code carried in every provider envelope for a fixture tool-call error. */
+function fixtureToolCallErrorCode(error) {
+	if (error instanceof UnsupportedToolCallError) return "aimock_unsupported_tool_call";
+	if (error instanceof InvalidFixtureToolCallError) return error.code;
+	return "aimock_invalid_tool_arguments";
+}
+/**
+* Google RPC error `details` carrying an aimock fixture tool-call code, for the
+* Gemini, Vertex AI and Gemini Live envelopes (`google.rpc.ErrorInfo`: an
+* UPPER_SNAKE `reason`, a `domain`, and string `metadata`).
+*/
+function googleFixtureToolCallErrorDetails(code) {
+	return [{
+		"@type": "type.googleapis.com/google.rpc.ErrorInfo",
+		reason: code.toUpperCase(),
+		domain: "aimock",
+		metadata: { code }
+	}];
+}
+/**
+* Run a WebSocket preflight `check` that may raise a fixture tool-call error
+* ({@link InvalidToolArgumentsError}, {@link UnsupportedToolCallError} or
+* {@link InvalidFixtureToolCallError}).
+* Such an error marks the already-journaled entry as a 500 carrying the
+* message, then propagates to the transport's error handler.
+*/
+function journalFixtureToolCallError(journalEntry, check) {
+	try {
+		return check();
+	} catch (error) {
+		if (isFixtureToolCallError(error)) {
+			journalEntry.response.status = 500;
+			journalEntry.response.error = error.message;
+		}
+		throw error;
+	}
+}
 /**
 * Resolve effective strict mode from per-request header and server default.
 * Header values override the server default — same precedence pattern as chaos
@@ -25,6 +274,25 @@ function resolveStrictMode(serverDefault, rawHeaders) {
 	}
 	return serverDefault ?? false;
 }
+const STRICT_INTEGER_RE = /^\d+$/;
+/**
+* Strict decimal-integer grammar shared by the query/list parsers that grew
+* their own local copy on separate branches (files `limit`, fine-tuning
+* `limit`, chaos integer fields): an unsigned digit run and nothing else — no
+* sign, no exponent, no radix prefix, no surrounding whitespace (callers that
+* accept padded input trim before calling).
+*
+* Deliberately narrower than `Number()`, which reads `0x10` as 16, `1e3` as
+* 1000 and strips whitespace and a leading `+`. Returns the value, or `null`
+* when the text is not a safe integer literal. Range checks and error
+* messages stay with the callers — this is the grammar gate only, so sharing
+* it cannot change any surface's accepted range or its 400 text.
+*/
+function parseStrictIntegerText(text) {
+	if (!STRICT_INTEGER_RE.test(text)) return null;
+	const n = Number(text);
+	return Number.isSafeInteger(n) ? n : null;
+}
 /**
 * Would a fixture miss on this request have been forwarded upstream? This is
 * the ONE rule behind the no-fixture chaos journal `source` label: "proxy"
@@ -161,14 +429,192 @@ function isLiveResponse(value) {
 function isResponseFactory(r) {
 	return typeof r === "function";
 }
+const serverFixtureLists = /* @__PURE__ */ new WeakMap();
+/**
+* Array methods that read elements and write them back. On a server list
+* they run on the caller's array, so the extended view of an element is
+* never written into it.
+*/
+const ELEMENT_MOVING_METHODS = new Set([
+	"copyWithin",
+	"fill",
+	"pop",
+	"push",
+	"reverse",
+	"shift",
+	"sort",
+	"splice",
+	"unshift"
+]);
+/**
+* The fixture list one server reads and writes: a live view of the caller's
+* `fixtures` array, with its own identity. The matcher reads the server's
+* `responsesTools` mode from the list it is given, so every handler on every
+* wire sees that server's mode without extra parameters, and two servers that
+* share one array each keep their own mode. With `"extended"`, reading an
+* element gives `extendedView(element)` (the fixture with its held keys
+* applied); the caller's array and its fixtures are never changed for it.
+* Writes (push, splice, `length = 0`, ...) reach the caller's array.
+*/
+function createServerFixtureList(fixtures, mode, extendedView) {
+	const boundMethods = /* @__PURE__ */ new Map();
+	const list = new Proxy(fixtures, { get(target, key) {
+		const value = Reflect.get(target, key);
+		if (typeof value === "function") {
+			if (!ELEMENT_MOVING_METHODS.has(key)) return value;
+			let bound = boundMethods.get(key);
+			if (bound === void 0) {
+				bound = value.bind(target);
+				boundMethods.set(key, bound);
+			}
+			return bound;
+		}
+		if (typeof key !== "string" || mode() !== "extended") return value;
+		const first = key.charCodeAt(0);
+		if (first < 48 || first > 57 || value === null || typeof value !== "object") return value;
+		return extendedView(value);
+	} });
+	serverFixtureLists.set(list, {
+		target: fixtures,
+		mode
+	});
+	return list;
+}
+/** Fixture arrays that only their own server reads: see {@link markServerOwnedFixtures}. */
+const serverOwnedFixtureArrays = /* @__PURE__ */ new WeakSet();
+/**
+* @internal Mark `fixtures` as an array no other server reads (LLMock's own
+* array). A server may change the fixtures it makes itself (the control API)
+* in place only in such an array; in a caller's array, which another server
+* may share, they stay as made and an extended server reads them through its
+* view.
+*/
+function markServerOwnedFixtures(fixtures) {
+	serverOwnedFixtureArrays.add(fixtures);
+}
+/** Whether the array behind `fixtures` (a server list or an array) is server-owned. */
+function isServerOwnedFixtures(fixtures) {
+	return serverOwnedFixtureArrays.has(fixtureListTarget(fixtures));
+}
+/** Whether `fixtures` is the list of a server running with `responsesTools: "extended"`. */
+function isExtendedResponsesToolsList(fixtures) {
+	return serverFixtureLists.get(fixtures)?.mode() === "extended";
+}
+/** The caller's array behind a server list; any other array is itself. */
+function fixtureListTarget(fixtures) {
+	return serverFixtureLists.get(fixtures)?.target ?? fixtures;
+}
+/**
+* Requests matched against an extended fixture list. {@link resolveResponse}
+* reads it, so the response a handler serves follows the same mode as the
+* match that chose its fixture.
+*/
+const extendedResponsesToolsRequests = /* @__PURE__ */ new WeakSet();
+/** Mark `request` as matched with `responsesTools: "extended"`. */
+function markExtendedResponsesToolsRequest(request) {
+	extendedResponsesToolsRequests.add(request);
+}
+/**
+* Drop `customToolCalls` and `responsesBlocks`, for responses served without
+* `responsesTools: "extended"`. Earlier releases ignored both keys, so a
+* fixture that carries them serves exactly as before. Returns the same object
+* when neither key is set.
+*/
+function withoutResponsesToolKeys(response) {
+	if (!isPlainObject(response)) return response;
+	if (!("customToolCalls" in response) && !("responsesBlocks" in response)) return response;
+	const copy = { ...response };
+	delete copy.customToolCalls;
+	delete copy.responsesBlocks;
+	return copy;
+}
 async function resolveResponse(fixture, request) {
-	if (typeof fixture.response === "function") try {
-		return normalizeFactoryResponse(await fixture.response(request));
-	} catch (err) {
-		const msg = err instanceof Error ? err.message : String(err);
-		throw new Error(`Response factory threw: ${msg}`, { cause: err });
+	const served = (response) => sanitizeFixtureResponse(extendedResponsesToolsRequests.has(request) ? response : withoutResponsesToolKeys(response));
+	if (typeof fixture.response === "function") {
+		let normalized;
+		try {
+			normalized = normalizeFactoryResponse(await fixture.response(request));
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			throw new Error(`Response factory threw: ${msg}`, { cause: err });
+		}
+		return served(normalized);
 	}
-	return fixture.response;
+	return served(fixture.response);
+}
+function isPlainObject(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/** A non-empty string, the only valid value of a tool call's `namespace`. */
+function isValidNamespace(value) {
+	return typeof value === "string" && value !== "";
+}
+/**
+* Drop the keys a served `toolCalls` entry or `toolCall` block ignores, so
+* no handler reads them: on a `toolCalls` entry, `type` and `input` (a
+* `toolCalls` entry is always a function call; custom calls live in
+* `customToolCalls`) and an invalid `namespace` (not a non-empty string); on a
+* `toolCall` block, `input` and an invalid `namespace`. Earlier releases
+* ignored all of these, so fixtures that carry them serve exactly as before.
+* Returns the same object when nothing needs dropping. `customToolCalls` and
+* `responsesBlocks` are new keys and are validated, not sanitized.
+*/
+function sanitizeFixtureResponse(response) {
+	if (!isPlainObject(response)) return response;
+	const r = response;
+	const dropKeys = (entry, keys) => {
+		if (!isPlainObject(entry)) return entry;
+		const drop = keys.filter((key) => key in entry && (key !== "namespace" || !isValidNamespace(entry.namespace)));
+		if (drop.length === 0) return entry;
+		const copy = { ...entry };
+		for (const key of drop) delete copy[key];
+		return copy;
+	};
+	const sanitizeList = (list, pick) => {
+		if (!Array.isArray(list)) return list;
+		const next = list.map(pick);
+		return next.some((entry, k) => entry !== list[k]) ? next : list;
+	};
+	const toolCalls = sanitizeList(r.toolCalls, (entry) => dropKeys(entry, [
+		"type",
+		"input",
+		"namespace"
+	]));
+	let blocks = sanitizeList(r.blocks, (entry) => isPlainObject(entry) && entry.type === "toolCall" ? dropKeys(entry, ["input", "namespace"]) : entry);
+	if (!(Array.isArray(r.blocks) && r.blocks.length > 0) && Array.isArray(r.responsesBlocks) && r.responsesBlocks.length > 0 && !r.responsesBlocks.some((entry) => isPlainObject(entry) && entry.type === "customToolCall")) blocks = r.responsesBlocks;
+	if (toolCalls === r.toolCalls && blocks === r.blocks) return response;
+	const copy = { ...r };
+	if (toolCalls !== r.toolCalls) copy.toolCalls = toolCalls;
+	if (blocks !== r.blocks) copy.blocks = blocks;
+	return copy;
+}
+/**
+* Drop `namespace` from every `toolCalls` entry and `toolCall` block, for
+* OpenAI Responses requests served without `responsesTools: "extended"`:
+* earlier releases never emitted it. (Without that mode, resolveResponse has
+* already dropped `customToolCalls` and `responsesBlocks`.) Returns the same
+* object when no namespace is set.
+*/
+function withoutLegacyNamespaces(response) {
+	if (!isPlainObject(response)) return response;
+	const r = response;
+	const strip = (list, isTarget) => {
+		if (!Array.isArray(list)) return list;
+		if (!list.some((entry) => isPlainObject(entry) && isTarget(entry) && "namespace" in entry)) return list;
+		return list.map((entry) => {
+			if (!isPlainObject(entry) || !isTarget(entry) || !("namespace" in entry)) return entry;
+			const copy = { ...entry };
+			delete copy.namespace;
+			return copy;
+		});
+	};
+	const toolCalls = strip(r.toolCalls, () => true);
+	const blocks = strip(r.blocks, (entry) => entry.type === "toolCall");
+	if (toolCalls === r.toolCalls && blocks === r.blocks) return response;
+	const copy = { ...r };
+	if (toolCalls !== r.toolCalls) copy.toolCalls = toolCalls;
+	if (blocks !== r.blocks) copy.blocks = blocks;
+	return copy;
 }
 function normalizeFactoryResponse(raw) {
 	const r = { ...raw };
@@ -187,6 +633,10 @@ function normalizeFactoryResponse(raw) {
 		};
 		return { ...block };
 	});
+	if (Array.isArray(r.responsesBlocks)) r.responsesBlocks = r.responsesBlocks.map((block) => isPlainObject(block) && block.type === "toolCall" && typeof block.arguments === "object" && block.arguments !== null ? {
+		...block,
+		arguments: JSON.stringify(block.arguments)
+	} : block);
 	return r;
 }
 function generateId(prefix = "chatcmpl") {
@@ -258,6 +708,12 @@ function isTextResponse(r) {
 function isToolCallResponse(r) {
 	return "toolCalls" in r && Array.isArray(r.toolCalls) && !("content" in r && typeof r.content === "string");
 }
+/**
+* Whether `r` is a combined content + tool calls response: a string `content`
+* with a `toolCalls` array, or a non-empty `blocks` array. Public, with the
+* 1.44.0 result for every input; `responsesBlocks` does not count. aimock's
+* own handlers use {@link isCombinedFixtureResponse}, which also counts it.
+*/
 function isContentWithToolCallsResponse(r) {
 	const o = r;
 	const hasContentAndToolCalls = "content" in r && typeof o.content === "string" && "toolCalls" in r && Array.isArray(o.toolCalls);
@@ -265,6 +721,19 @@ function isContentWithToolCallsResponse(r) {
 	return hasContentAndToolCalls || hasNonEmptyBlocks;
 }
 /**
+* @internal The combined-response guard aimock's handlers, validation and
+* misbehavior use: {@link isContentWithToolCallsResponse} plus a non-empty
+* `responsesBlocks`. In legacy mode those keys are dropped before serving, so
+* only `responsesTools: "extended"` sees the extra clause.
+*/
+function isCombinedFixtureResponse(r) {
+	const o = r;
+	const hasContentAndToolCalls = "content" in r && typeof o.content === "string" && "toolCalls" in r && Array.isArray(o.toolCalls);
+	const hasNonEmptyBlocks = Array.isArray(o.blocks) && o.blocks.length > 0;
+	const hasNonEmptyResponsesBlocks = Array.isArray(o.responsesBlocks) && o.responsesBlocks.length > 0;
+	return hasContentAndToolCalls || hasNonEmptyBlocks || hasNonEmptyResponsesBlocks;
+}
+/**
 * Validate and pass through the ordered `blocks` field of a combined
 * content+toolCalls fixture. Used ONLY on the new block-iteration path (when a
 * fixture explicitly sets `blocks`); it is NOT a legacy-order reconstructor —
@@ -291,7 +760,9 @@ function isContentWithToolCallsResponse(r) {
 * optional string `id`. The return type guarantees `arguments: string` — every
 * caller relies on that. Throws on a malformed array or entry — same fail-fast
 * idiom as the other fixture validators in this module (see e.g. the factory
-* guard at {@link resolveResponse}).
+* guard at {@link resolveResponse}). A `customToolCall` block is not a
+* `blocks` entry (it belongs in `responsesBlocks`, see
+* {@link resolveResponsesBlocks}) and fails as an unknown type.
 */
 function resolveFixtureBlocks(blocks) {
 	if (!Array.isArray(blocks)) throw new Error(`Invalid fixture blocks: expected an array, got ${typeof blocks}`);
@@ -321,6 +792,130 @@ function resolveFixtureBlocks(blocks) {
 		} else throw new Error(`Invalid fixture block at index ${i}: unknown type ${JSON.stringify(b.type)} (expected "text" or "toolCall")`);
 	});
 }
+/**
+* Validate and normalize a fixture's `responsesBlocks` (OpenAI Responses
+* only). Same rules and normalized copy as {@link resolveFixtureBlocks}, plus:
+* a `customToolCall` block with a non-empty string `name`, a string `input`
+* (never parsed or stringified), no `arguments` and an optional string `id`;
+* on either tool block, `namespace` must be a non-empty string when present,
+* and a `toolCall` block carries no `input`. The key is new, so a malformed
+* tool block throws the coded {@link InvalidFixtureToolCallError}; a malformed
+* text block or an unknown type throws a plain Error.
+*/
+function resolveResponsesBlocks(blocks) {
+	if (!Array.isArray(blocks)) throw new Error(`Invalid fixture responsesBlocks: expected an array, got ${typeof blocks}`);
+	return blocks.map((block, i) => {
+		if (!isPlainObject(block)) throw new Error(`Invalid fixture block at index ${i}: expected an object`);
+		const b = block;
+		const failToolCall = (problem) => {
+			throw new InvalidFixtureToolCallError(i, problem, "blocks");
+		};
+		if ((b.type === "toolCall" || b.type === "customToolCall") && b.namespace !== void 0 && (typeof b.namespace !== "string" || b.namespace === "")) failToolCall("\"namespace\" must be a non-empty string when present");
+		const namespace = typeof b.namespace === "string" ? { namespace: b.namespace } : {};
+		const id = typeof b.id === "string" ? { id: b.id } : {};
+		if (b.type === "text") {
+			if (typeof b.text !== "string") throw new Error(`Invalid fixture block at index ${i}: "text" block requires a string "text" field`);
+			return {
+				type: "text",
+				text: b.text
+			};
+		}
+		if (b.type === "toolCall") {
+			if (b.input !== void 0) failToolCall("\"input\" is only valid on a \"customToolCall\" block");
+			if (typeof b.name !== "string") failToolCall("\"toolCall\" block requires a string \"name\" field");
+			if (b.id !== void 0 && typeof b.id !== "string") failToolCall("\"toolCall\" block \"id\" must be a string when present");
+			const args = typeof b.arguments === "object" && b.arguments !== null ? JSON.stringify(b.arguments) : b.arguments;
+			if (typeof args !== "string") failToolCall("\"toolCall\" block requires a string or object \"arguments\" field");
+			return {
+				type: "toolCall",
+				name: b.name,
+				arguments: args,
+				...id,
+				...namespace
+			};
+		}
+		if (b.type === "customToolCall") {
+			if (typeof b.name !== "string" || b.name === "") failToolCall("\"customToolCall\" block requires a non-empty string \"name\" field");
+			if (typeof b.input !== "string") failToolCall("\"customToolCall\" block requires a string \"input\" field");
+			if (b.arguments !== void 0) failToolCall("\"customToolCall\" block takes \"input\", not \"arguments\"");
+			if (b.id !== void 0 && typeof b.id !== "string") failToolCall("\"customToolCall\" block \"id\" must be a string when present");
+			return {
+				type: "customToolCall",
+				name: b.name,
+				input: b.input,
+				...id,
+				...namespace
+			};
+		}
+		throw new Error(`Invalid fixture block at index ${i}: unknown type ${JSON.stringify(b.type)} (expected "text", "toolCall" or "customToolCall")`);
+	});
+}
+/** Allocate the exact OpenAI call identities once for both wire output and observations. */
+function prepareOpenAIChatMisbehavior(plan) {
+	const response = plan.response;
+	const combined = isCombinedFixtureResponse(response);
+	const outcome = combined ? resolveServedBlockOutcome(response) : void 0;
+	const calls = outcome?.toolCalls ?? (combined || isToolCallResponse(response) ? servedToolCalls(response) : []);
+	const duplicate = plan.duplicateId;
+	const toolCalls = calls.map((call, index) => ({
+		...call,
+		...index === duplicate?.destinationIndex ? {} : { id: call.id || generateToolCallId() }
+	}));
+	if (duplicate) toolCalls[duplicate.destinationIndex].id = toolCalls[duplicate.sourceIndex].id;
+	let preparedResponse = { ...response };
+	if ("usage" in preparedResponse) delete preparedResponse.usage;
+	if (plan.stop === "length") preparedResponse = {
+		...preparedResponse,
+		finishReason: "length"
+	};
+	if (outcome) preparedResponse = withServedToolCalls({
+		...preparedResponse,
+		content: outcome.content
+	}, toolCalls, rebuildOrderedBlocks(outcome.ordered, toolCalls));
+	else if (combined || isToolCallResponse(response)) preparedResponse = withServedToolCalls(preparedResponse, toolCalls);
+	return {
+		...plan,
+		response: preparedResponse,
+		summary: {
+			...plan.summary,
+			servedToolCalls: toolCalls.map(servedMisbehaviorToolCall)
+		}
+	};
+}
+/**
+* The journaled form of a served misbehavior tool call: `{ name, arguments,
+* id }`. A Responses custom tool call adds `type: "custom"` and carries its
+* free-text `input` in `arguments`; `namespace` is recorded only when set.
+*/
+function servedMisbehaviorToolCall(call) {
+	const namespace = call.namespace !== void 0 ? { namespace: call.namespace } : {};
+	return call.type === "custom" ? {
+		type: "custom",
+		name: call.name,
+		arguments: call.input,
+		id: call.id,
+		...namespace
+	} : {
+		name: call.name,
+		arguments: call.arguments,
+		id: call.id,
+		...namespace
+	};
+}
+/** The text a tool call contributes to an estimated completion: name plus arguments or input. */
+function toolCallUsageText(call) {
+	return call.name + (call.type === "custom" ? call.input : call.arguments);
+}
+/** Estimate once from the full applied output, before any delivery interruption. */
+function resolveOpenAIChatMisbehaviorUsage(plan, request, exposeReasoning = true) {
+	const response = plan.response;
+	const combined = isCombinedFixtureResponse(response);
+	const outcome = combined ? resolveServedBlockOutcome(response) : void 0;
+	const calls = outcome?.toolCalls ?? (combined || isToolCallResponse(response) ? servedToolCalls(response) : []);
+	const content = outcome?.content ?? ("content" in response && typeof response.content === "string" ? response.content : "");
+	const reasoning = plan.reasoning ?? ("reasoning" in response && typeof response.reasoning === "string" ? response.reasoning : "");
+	return resolveUsage(void 0, request.messages.map((message) => typeof message.content === "string" ? message.content : Array.isArray(message.content) ? message.content.map((part) => part.text ?? "").join("") : "").join(""), content + calls.map(toolCallUsageText).join("") + (plan.refusal ?? "") + (exposeReasoning ? reasoning : ""));
+}
 /** Project normalized ordered blocks without changing the fixture or generating ids. */
 function resolveFixtureBlockOutcome(blocks) {
 	const ordered = resolveFixtureBlocks(blocks);
@@ -339,6 +934,118 @@ function resolveFixtureBlockOutcome(blocks) {
 		hasToolCalls: toolCalls.length > 0
 	};
 }
+/**
+* Every tool call a response serves, in order: the function calls of
+* `toolCalls`, then the custom calls of `customToolCalls` (each tagged
+* `type: "custom"`). Only the OpenAI Responses API may serve the custom ones;
+* the other wires reject a non-empty `customToolCalls` first
+* ({@link rejectResponsesOnlyToolCalls}).
+*/
+function servedToolCalls(response) {
+	const calls = [...response.toolCalls ?? []];
+	for (const call of Array.isArray(response.customToolCalls) ? response.customToolCalls : []) calls.push(isPlainObject(call) ? {
+		...call,
+		type: "custom"
+	} : call);
+	return calls;
+}
+/**
+* Resolve the ordered blocks a response serves, with each tool block projected
+* to its {@link FixtureToolCall}: a non-empty `responsesBlocks` (OpenAI
+* Responses only, through {@link resolveResponsesBlocks}), else a non-empty
+* legacy `blocks` (through {@link resolveFixtureBlocks}, which rejects a
+* `customToolCall` block with the error of earlier releases). Undefined when
+* the response has neither.
+*/
+function resolveServedBlockOutcome(response) {
+	const r = response;
+	let ordered;
+	let source;
+	if (Array.isArray(r.responsesBlocks) && r.responsesBlocks.length > 0) {
+		ordered = resolveResponsesBlocks(r.responsesBlocks);
+		source = "responsesBlocks";
+	} else if (Array.isArray(r.blocks) && r.blocks.length > 0) {
+		ordered = resolveFixtureBlocks(r.blocks);
+		source = "blocks";
+	} else return void 0;
+	let content = "";
+	const toolCalls = [];
+	for (const block of ordered) if (block.type === "text") content += block.text;
+	else toolCalls.push(fixtureBlockToolCall(block));
+	return {
+		ordered,
+		content,
+		toolCalls,
+		hasToolCalls: toolCalls.length > 0,
+		source
+	};
+}
+/**
+* Write rewritten served tool calls (and, with `ordered`, rebuilt ordered
+* blocks) back into a copy of `response`, split by carrier: function calls go
+* to `toolCalls`, custom calls to `customToolCalls`, and the blocks to
+* `responsesBlocks` when the response served those, else to `blocks`.
+*/
+function withServedToolCalls(response, toolCalls, ordered) {
+	const functionCalls = [];
+	const customCalls = [];
+	for (const call of toolCalls) if (call.type === "custom") customCalls.push(call);
+	else functionCalls.push(call);
+	const out = {
+		...response,
+		toolCalls: functionCalls
+	};
+	if (customCalls.length > 0 || "customToolCalls" in response) out.customToolCalls = customCalls;
+	if (ordered) {
+		const r = response;
+		if (Array.isArray(r.responsesBlocks) && r.responsesBlocks.length > 0) out.responsesBlocks = ordered;
+		else out.blocks = ordered;
+	}
+	return out;
+}
+/** Project one normalized tool block to the matching served tool call. */
+function fixtureBlockToolCall(block) {
+	const id = block.id !== void 0 ? { id: block.id } : {};
+	const namespace = block.namespace !== void 0 ? { namespace: block.namespace } : {};
+	return block.type === "customToolCall" ? {
+		type: "custom",
+		name: block.name,
+		input: block.input,
+		...id,
+		...namespace
+	} : {
+		name: block.name,
+		arguments: block.arguments,
+		...id,
+		...namespace
+	};
+}
+/** Project one served tool call back to its ordered tool block. */
+function toolCallFixtureBlock(call) {
+	const id = call.id !== void 0 ? { id: call.id } : {};
+	const namespace = call.namespace !== void 0 ? { namespace: call.namespace } : {};
+	return call.type === "custom" ? {
+		type: "customToolCall",
+		name: call.name,
+		input: call.input,
+		...id,
+		...namespace
+	} : {
+		type: "toolCall",
+		name: call.name,
+		arguments: call.arguments,
+		...id,
+		...namespace
+	};
+}
+/**
+* Rebuild ordered blocks after their tool calls were rewritten one-for-one:
+* text blocks are copied and the Nth tool block becomes `toolCalls[N]`.
+*/
+function rebuildOrderedBlocks(ordered, toolCalls) {
+	let callIndex = 0;
+	return ordered.map((block) => block.type === "text" ? { ...block } : toolCallFixtureBlock(toolCalls[callIndex++]));
+}
 function isErrorResponse(r) {
 	return "error" in r && r.error !== null && typeof r.error === "object" && "message" in r.error && typeof r.error.message === "string";
 }
@@ -416,6 +1123,17 @@ function estimateTokens(text) {
 	return Math.max(1, Math.ceil(text.length / 4));
 }
 /**
+* 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));
+}
+/**
 * Build usage object: use explicit overrides if provided, otherwise estimate.
 *
 * Shared by BOTH the non-streaming completion builders (below) and the
@@ -530,6 +1248,140 @@ function buildTextChunks(content, model, chunkSize, reasoning, overrides) {
 	});
 	return chunks;
 }
+/** K9 exposure is selected by the provider path, never the echoed response model. */
+function buildOpenAIReasoningChunks(reasoning, model, chunkSize, exposeReasoning, overrides) {
+	return buildTextChunks(exposeReasoning ? reasoning : "", model, chunkSize, void 0, {
+		...overrides,
+		role: "assistant",
+		finishReason: "length"
+	}).map((chunk) => ({
+		...chunk,
+		choices: chunk.choices.map((choice) => ({
+			...choice,
+			delta: choice.delta.role !== void 0 ? {
+				role: "assistant",
+				content: null
+			} : typeof choice.delta.content === "string" ? {
+				role: "assistant",
+				content: "",
+				reasoning: choice.delta.content,
+				reasoning_details: [{
+					type: "reasoning.text",
+					text: choice.delta.content,
+					format: "unknown",
+					index: 0
+				}]
+			} : {}
+		}))
+	}));
+}
+/** Render exposed reasoning or native OpenAI's empty length completion. */
+function buildOpenAIReasoningCompletion(reasoning, model, exposeReasoning, overrides, requestMessages) {
+	const visible = exposeReasoning ? reasoning : "";
+	const completion = buildTextCompletion(visible, model, void 0, {
+		...overrides,
+		role: "assistant",
+		finishReason: "length",
+		usage: void 0
+	}, requestMessages);
+	return {
+		...completion,
+		choices: completion.choices.map((choice) => ({
+			...choice,
+			message: {
+				role: "assistant",
+				content: null,
+				refusal: null,
+				...exposeReasoning ? {
+					reasoning: visible,
+					reasoning_details: [{
+						type: "reasoning.text",
+						text: visible,
+						format: "unknown",
+						index: 0
+					}]
+				} : {}
+			}
+		}))
+	};
+}
+/** Render withheld output with only the role and native content-filter terminal. */
+function buildOpenAIContentFilterChunks(model, overrides) {
+	return buildTextChunks("", model, 1, void 0, {
+		...overrides,
+		role: "assistant",
+		finishReason: "content_filter"
+	}).map((chunk) => ({
+		...chunk,
+		choices: chunk.choices.map((choice) => ({
+			...choice,
+			delta: choice.delta.role !== void 0 ? {
+				role: "assistant",
+				content: null
+			} : {}
+		}))
+	}));
+}
+/** Non-streaming filtered output contains no answer, refusal text, reasoning, or calls. */
+function buildOpenAIContentFilterCompletion(model, overrides, requestMessages) {
+	const completion = buildTextCompletion("", model, void 0, {
+		...overrides,
+		role: "assistant",
+		finishReason: "content_filter",
+		usage: void 0
+	}, requestMessages);
+	return {
+		...completion,
+		choices: completion.choices.map((choice) => ({
+			...choice,
+			message: {
+				role: "assistant",
+				content: null,
+				refusal: null
+			}
+		}))
+	};
+}
+/** Render an applied refusal on its own channel without ordinary content or reasoning. */
+function buildOpenAIRefusalChunks(refusal, model, chunkSize, overrides) {
+	return buildTextChunks(refusal, model, chunkSize, void 0, {
+		...overrides,
+		role: "assistant",
+		finishReason: "stop"
+	}).map((chunk) => ({
+		...chunk,
+		choices: chunk.choices.map((choice) => {
+			const delta = choice.delta.role !== void 0 ? {
+				role: "assistant",
+				content: null
+			} : typeof choice.delta.content === "string" ? { refusal: choice.delta.content } : {};
+			return {
+				...choice,
+				delta
+			};
+		})
+	}));
+}
+/** Refusal-only counterpart of the ordinary text completion builder. */
+function buildOpenAIRefusalCompletion(refusal, model, overrides, requestMessages) {
+	const completion = buildTextCompletion(refusal, model, void 0, {
+		...overrides,
+		role: "assistant",
+		finishReason: "stop",
+		usage: void 0
+	}, requestMessages);
+	return {
+		...completion,
+		choices: completion.choices.map((choice) => ({
+			...choice,
+			message: {
+				role: "assistant",
+				content: null,
+				refusal
+			}
+		}))
+	};
+}
 function buildToolCallChunks(toolCalls, model, chunkSize, reasoning, overrides) {
 	const id = overrides?.id ?? generateId();
 	const created = overrides?.created ?? Math.floor(Date.now() / 1e3);
@@ -1070,11 +1922,14 @@ function matchesPattern(text, pattern) {
 	return result;
 }
 /**
-* The ONE definition of "which test does this traffic belong to": the
-* `X-Test-Id` header wins, then `?testId=` in the query string, then
-* `DEFAULT_TEST_ID`. Every per-test axis (fixture match-counts, the journal
-* filter, chaos scoping) resolves through this, so a caller that tags one way
-* can never land in two different scopes.
+* Which test LLM and other HTTP-route traffic belongs to: the `X-Test-Id`
+* header (raw, not percent-decoded) wins, then `?testId=` in the query string
+* (read through `URLSearchParams`, so percent-decoded and with `+` as a
+* space), then `DEFAULT_TEST_ID`. Every per-test axis of those routes
+* (fixture match-counts, the journal filter, chaos scoping) resolves through
+* this. MCP mounts resolve the test id with {@link resolveMcpIdentity}
+* instead, which percent-decodes the header, so `X-Test-Id: a%20b` is `a%20b`
+* here and `a b` there. Both read a `+` in the query as a space.
 */
 function resolveTestId(headers, url) {
 	const headerValue = headers["x-test-id"];
@@ -1098,6 +1953,237 @@ function getContext(req) {
 	} else if (typeof headerValue === "string" && headerValue) return headerValue;
 }
 /**
+* Decode one MCP identity value: an `X-Test-Id` / `X-AIMock-Context` header
+* value, and also each query name and (through {@link decodeMcpQueryValue})
+* each `?testId=` / `?context=` / `?undeclared=` query value. Clients send `encodeURIComponent(id)` because
+* `fetch` rejects characters such as `›` in a header. A value that is not
+* valid percent-encoding (a raw `applies 50% discount`) is used as-is, with
+* `fellBack: true` so the caller can log the fallback. Only that `URIError`
+* is caught; any other throw propagates. MCP requests only: LLM routes read
+* the header raw and the query through `URLSearchParams` (see
+* {@link resolveTestId}).
+*/
+function decodeMcpHeaderValue(raw) {
+	try {
+		return {
+			value: decodeURIComponent(raw),
+			fellBack: false
+		};
+	} catch (err) {
+		if (!(err instanceof URIError)) throw err;
+		return {
+			value: raw,
+			fellBack: true
+		};
+	}
+}
+/**
+* Decode one MCP query value (`?testId=`, `?context=`, `?undeclared=`) the way
+* `URLSearchParams` reads it (spec I1): a `+` is a space, then the value is
+* percent-decoded by the {@link decodeMcpHeaderValue} rule. So a query built
+* with `URL.searchParams.set(...)` (a space sent as `+`) and one built with
+* `encodeURIComponent` both resolve to the id itself. A value that is not
+* valid percent-encoding is used as-is (its `+` still a space), with
+* `fellBack: true`.
+*/
+function decodeMcpQueryValue(raw) {
+	return decodeMcpHeaderValue(raw.replace(/\+/g, " "));
+}
+/**
+* Every value of the header `name`, one per header line: `[]` when absent.
+* Node joins a repeated header into one comma-joined `req.headers` string, so
+* the values come from `req.headersDistinct` (one element per line) when the
+* request has it. A caller without it (a hand-built request) is read from
+* `req.headers`: one element for a string, each element for an array.
+*/
+function headerValues(req, name) {
+	const distinct = req.headersDistinct?.[name];
+	if (distinct !== void 0) return distinct;
+	const value = req.headers[name];
+	if (value === void 0) return [];
+	return Array.isArray(value) ? value : [value];
+}
+/**
+* Every pair of a query string, in order, each name decoded by the
+* `decodeMcpHeaderValue` rule. A bare `name` with no `=` counts as an
+* occurrence with an empty value, so `?testId&testId=t1` has two. Each value
+* is left raw for the caller to decode with {@link decodeMcpQueryValue}.
+* A name that is not valid percent-encoding (`test%Id`) gets `name: null`: it
+* matches no field, and the caller counts it.
+*/
+function queryPairs(query) {
+	if (query === "") return [];
+	return query.split("&").map((pair) => {
+		const eq = pair.indexOf("=");
+		const key = decodeMcpHeaderValue(eq === -1 ? pair : pair.slice(0, eq));
+		return {
+			name: key.fellBack ? null : key.value,
+			value: eq === -1 ? "" : pair.slice(eq + 1)
+		};
+	});
+}
+/**
+* A request value as a message part, the way the message builder quotes every
+* user string: JSON-quoted (quotes and control characters escaped), then cut
+* once as JSON text, so the whole echo, quotes, escapes and the
+* `… (<n> more chars)` count included, fits in `MCP_FAKES_ECHO_LIMIT` and the
+* cut never splits a JSON escape or a surrogate pair.
+*/
+function echoIdentityValue(value) {
+	return quote(value, MCP_FAKES_ECHO_LIMIT);
+}
+const MCP_IDENTITY_INPUTS = {
+	testId: {
+		header: "x-test-id",
+		query: "testId",
+		label: "X-Test-Id"
+	},
+	context: {
+		header: "x-aimock-context",
+		query: "context",
+		label: "X-AIMock-Context"
+	},
+	undeclared: {
+		header: "x-aimock-mcp-undeclared",
+		query: "undeclared",
+		label: "X-AIMock-MCP-Undeclared"
+	}
+};
+/**
+* Resolve the identity (test id, context, undeclared override) of one MCP request.
+* Each field resolves on its own, first of: the header, the query parameter,
+* the session value bound at `initialize`. A field sent more than once on
+* either path (more than one header line, read from `headersDistinct` because
+* Node joins repeated lines into one `headers` string; a header array from a
+* hand-built request; a repeated query name) is an error
+* (`MCP_DUPLICATE_IDENTITY`), even when the other path also carries it. For
+* the test id and the context, a header value is decoded with
+* `decodeURIComponent` (raw value on failure, with `fellBack` set) and a query
+* value the way `URLSearchParams` reads it (spec I1): a `+` is a space, then
+* the same `decodeURIComponent` rule. So `encodeURIComponent` output (what
+* clients send) and a query built with `URL.searchParams` both decode to the
+* id itself, while a raw `+` is a `+` in the header and a space in the query.
+* When both paths carry a test id or a context, the header is used and the
+* query value is ignored, even if the two differ, but an ignored query value
+* that does not decode still sets `fellBack`. The undeclared header is not
+* percent-decoded; its query value is, by the same query rule. Both are
+* trimmed and compared case-insensitively. `supplied` says whether the
+* request itself carried a non-empty header or query value for the field,
+* never `resolveTestId`'s result (which returns `"__default__"` when nothing
+* is sent). Blank values: an empty value is not supplied and falls through;
+* it is never rejected. A whitespace-only value is not supplied for the
+* undeclared override (it is trimmed), but is a real value for the test id
+* and the context, which match exactly and are never trimmed (Node trims a
+* header value, so only the query or a hand-built request can carry one). A
+* lone query name with no `=` carries no value. An empty session value counts
+* as none, and a missing `req.url` as `/`. A field with no value anywhere is
+* `null`. An unrecognized undeclared override on the header or the query is
+* an error (`ok: false`), not a fall-through: both are checked before the
+* header one is used, so a valid header does not hide a mistyped query value.
+* Bad percent-encoding is never silent: a test id or context value that does
+* not decode sets `fellBack`, on either path, used or ignored; an undeclared
+* query value that does not decode is that error, with the message saying
+* so; and a query name that does not decode matches no field and is counted
+* in `undecodedQueryNames`. `resolveTestId` / `getContext` stay unchanged for
+* LLM routes.
+*/
+function resolveMcpIdentity(req, session) {
+	const url = req.url ?? "/";
+	const qIdx = url.indexOf("?");
+	const pairs = queryPairs(qIdx === -1 ? "" : url.slice(qIdx + 1));
+	const raw = {};
+	for (const field of [
+		"testId",
+		"context",
+		"undeclared"
+	]) {
+		const input = MCP_IDENTITY_INPUTS[field];
+		const sent = [["header", headerValues(req, input.header)], ["query", pairs.filter((p) => p.name === input.query).map((p) => p.value)]];
+		for (const [source, values] of sent) if (values.length > 1) {
+			const label = source === "header" ? msg`${fixed(input.label)} header` : msg`?${fixed(input.query)}= query parameter`;
+			return {
+				ok: false,
+				error: {
+					code: "MCP_DUPLICATE_IDENTITY",
+					status: 400,
+					field,
+					source,
+					count: values.length,
+					message: build(msg`Duplicate ${label}: ${values.length} values sent, expected one`)
+				}
+			};
+		}
+		raw[field] = {
+			header: sent[0][1][0],
+			query: sent[1][1][0]
+		};
+	}
+	const fromRequest = (field) => {
+		const { header, query: q } = raw[field];
+		const fromQuery = q ? decodeMcpQueryValue(q) : null;
+		if (header) {
+			const used = decodeMcpHeaderValue(header);
+			return {
+				value: used.value,
+				fellBack: used.fellBack || (fromQuery?.fellBack ?? false)
+			};
+		}
+		return fromQuery ?? {
+			value: null,
+			fellBack: false
+		};
+	};
+	const testId = fromRequest("testId");
+	const context = fromRequest("context");
+	let undeclared = null;
+	for (const source of ["header", "query"]) {
+		const sent = raw.undeclared[source];
+		if (sent === void 0) continue;
+		const decoded = source === "header" ? {
+			value: sent,
+			fellBack: false
+		} : decodeMcpQueryValue(sent);
+		if (decoded.value.trim() === "") continue;
+		const parsed = parseMcpUndeclared(decoded.value);
+		if (parsed === null) {
+			const echoed = echoIdentityValue(sent);
+			const label = source === "header" ? msg`X-AIMock-MCP-Undeclared header` : msg`?undeclared= query parameter`;
+			const note = decoded.fellBack ? msg` (not valid percent-encoding)` : msg``;
+			return {
+				ok: false,
+				error: {
+					code: "MCP_INVALID_UNDECLARED",
+					status: 400,
+					field: "undeclared",
+					source,
+					raw: cutText(sent),
+					message: build(msg`Invalid ${label} value ${echoed}${note}: expected allow or deny`)
+				}
+			};
+		}
+		undeclared ??= parsed;
+	}
+	const undecodedQueryNames = pairs.filter((p) => p.name === null).length;
+	return {
+		ok: true,
+		identity: {
+			testId: testId.value ?? (session?.testId || null),
+			context: context.value ?? (session?.context || null),
+			undeclared: undeclared ?? session?.undeclared ?? null
+		},
+		supplied: {
+			testId: testId.value !== null,
+			context: context.value !== null,
+			undeclared: undeclared !== null
+		},
+		fellBack: {
+			testId: testId.fellBack,
+			context: context.fellBack
+		},
+		...undecodedQueryNames > 0 ? { undecodedQueryNames } : {}
+	};
+}
+/**
 * Convert a test ID (e.g. Playwright titlePath) into a filesystem-safe slug
 * suitable for use as a directory name in snapshot-style recording.
 */
@@ -1328,7 +2414,20 @@ function describeMatch(match, index) {
 	const cut = head.lastIndexOf(", ");
 	return `${cut > 0 ? head.slice(0, cut) : head}, … }`;
 }
+/**
+* Parse an `X-AIMock-MCP-Undeclared` header or `?undeclared=` value.
+* Modeled on {@link resolveStrictMode}: case-insensitive, surrounding
+* whitespace trimmed. Returns `null` when unrecognised; unlike the strict
+* header, {@link resolveMcpIdentity} turns that into an error rather than a
+* fall-through, because falling through would turn a mistyped `deny` into
+* the permissive default.
+*/
+function parseMcpUndeclared(raw) {
+	const val = raw.trim().toLowerCase();
+	if (val === "allow" || val === "deny") return val;
+	return null;
+}
 
 //#endregion
-export { FORMAT_TO_CONTENT_TYPE, MAX_EMBEDDING_DIMENSIONS, RequestBodyTooLargeError, buildContentWithToolCallsChunks, buildContentWithToolCallsCompletion, buildEmbeddingResponse, buildTextChunks, buildTextCompletion, buildToolCallChunks, buildToolCallCompletion, buildUsageChunk, describeMatch, extractOverrides, flattenHeaders, formatToMime, generateDeterministicEmbedding, generateId, generateMessageId, generateToolCallId, generateToolUseId, getContext, getTestId, hasMintedRequestId, isAudioResponse, isContentWithToolCallsResponse, isEmbeddingResponse, isErrorResponse, isImageResponse, isJSONResponse, isJsonObject, isLiveResponse, isResponseFactory, isTextResponse, isToolCallResponse, isTranscriptionResponse, isVideoResponse, markMintedRequestId, matchesPattern, normalizeEmbeddingInput, normalizeTextInput, readBody, readBodyBufferBounded, resolveFixtureBlockOutcome, resolveFixtureBlocks, resolveReasoningArtifactsForModel, resolveReasoningForModel, resolveRequestId, resolveResponse, resolveStrictMode, resolveTestId, resolveUsage, serializeErrorResponse, slugifyContext, slugifyTestId, strictNoMatchLogLine, strictNoMatchMessage, strictOverrideField, validateChatMessages, validateEmbeddingDimensions, validateToolsField, wouldProxyMiss };
+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 };
 //# sourceMappingURL=helpers.js.map