@copilotkit/aimock 1.42.1 → 1.44.0

package/dist/helpers.d.ts

@@ -1,3 +1,4 @@
+import { LiveFixtureResponse } from "./live-types.js";
 import { AudioResponse, ChatCompletion, ChatCompletionRequest, ContentWithToolCallsResponse, EmbeddingResponse, ErrorResponse, FixtureBlock, FixtureFileBlock, FixtureResponse, ImageResponse, ResponseOverrides, SSEChunk, TextResponse, ToolCall, ToolCallResponse, TranscriptionResponse, VideoResponse } from "./types.js";
 import * as http$1 from "node:http";
 
@@ -44,7 +45,32 @@ declare function strictNoMatchLogLine(method: string, url: string, skippedBySequ
  */
 
 declare function flattenHeaders(headers: http$1.IncomingHttpHeaders): Record<string, string>;
+/** Structural discriminator; registration performs full transcript validation. */
+declare function isLiveResponse(value: unknown): value is LiveFixtureResponse;
 declare function generateId(prefix?: string): string;
+/**
+ * Resolve the request id for this HTTP request.
+ *
+ * - When the caller sends a well-formed `X-Request-Id` (1-128 chars of
+ *   `A-Za-z0-9-_.:`), it is echoed verbatim so distributed traces correlate.
+ * - Otherwise (absent, empty, too long, or illegal characters) a fresh
+ *   `req-…` id is generated — never trust an attacker-controlled correlation
+ *   value to be a valid log key.
+ *
+ * Returns `{ id, generated }`. The server normalizes
+ * `req.headers["x-request-id"]` to the resolved value, so every downstream
+ * `flattenHeaders` journal snapshot carries it with zero per-handler edits —
+ * which also means a MINTED id would otherwise ride the egress header set to
+ * a real provider. The server therefore passes `generated` to
+ * `markMintedRequestId` so `buildForwardHeaders` can drop it; a caller's own
+ * id still forwards verbatim.
+ */
+declare function resolveRequestId(rawHeaders: http$1.IncomingHttpHeaders): {
+  id: string;
+  generated: boolean;
+};
+/** @internal Record that this request's `x-request-id` is aimock's own. */
+
 declare function generateToolCallId(): string;
 declare function generateMessageId(): string;
 declare function generateToolUseId(): string;
@@ -81,6 +107,8 @@ declare function isContentWithToolCallsResponse(r: FixtureResponse): r is Conten
  * guard at {@link resolveResponse}).
  */
 declare function resolveFixtureBlocks(blocks: FixtureFileBlock[]): FixtureBlock[];
+/** Project normalized ordered blocks without changing the fixture or generating ids. */
+
 declare function isErrorResponse(r: FixtureResponse): r is ErrorResponse;
 /**
  * Serialize an ErrorResponse to JSON, stripping the internal-only `status`
@@ -115,6 +143,15 @@ declare function buildTextCompletion(content: string, model: string, reasoning?:
 declare function buildToolCallCompletion(toolCalls: ToolCall[], model: string, reasoning?: string, overrides?: ResponseOverrides, requestMessages?: ChatCompletionRequest["messages"]): ChatCompletion;
 declare function buildContentWithToolCallsChunks(content: string, toolCalls: ToolCall[], model: string, chunkSize: number, reasoning?: string, overrides?: ResponseOverrides, blocks?: FixtureBlock[]): SSEChunk[];
 declare function buildContentWithToolCallsCompletion(content: string, toolCalls: ToolCall[], model: string, reasoning?: string, overrides?: ResponseOverrides, requestMessages?: ChatCompletionRequest["messages"]): ChatCompletion;
+/**
+ * A body read that stopped because the CLIENT sent more bytes than the route
+ * allows. The socket is already destroyed when this rejects, so no status line
+ * ever reaches the caller — but the fault is the caller's, and error arms that
+ * journal and log the failure need to say so. Carrying the classification on
+ * the error type (rather than re-matching the message text) is what lets them:
+ * the message is unchanged from the plain `Error` this replaced.
+ */
+
 /**
  * Generate a deterministic embedding vector from input text.
  * Hashes the input with SHA-256 and spreads the hash bytes across
@@ -141,7 +178,6 @@ declare function buildEmbeddingResponse(embeddings: number[][], model: string, u
   prompt_tokens?: number;
   total_tokens?: number;
 }): EmbeddingAPIResponse;
-//# sourceMappingURL=helpers.d.ts.map
 //#endregion
-export { EmbeddingAPIResponse, FORMAT_TO_CONTENT_TYPE, buildContentWithToolCallsChunks, buildContentWithToolCallsCompletion, buildEmbeddingResponse, buildTextChunks, buildTextCompletion, buildToolCallChunks, buildToolCallCompletion, extractOverrides, flattenHeaders, formatToMime, generateDeterministicEmbedding, generateId, generateMessageId, generateToolCallId, generateToolUseId, isAudioResponse, isContentWithToolCallsResponse, isEmbeddingResponse, isErrorResponse, isImageResponse, isTextResponse, isToolCallResponse, isTranscriptionResponse, isVideoResponse, resolveFixtureBlocks, strictNoMatchLogLine, strictNoMatchMessage };
+export { EmbeddingAPIResponse, FORMAT_TO_CONTENT_TYPE, buildContentWithToolCallsChunks, buildContentWithToolCallsCompletion, buildEmbeddingResponse, buildTextChunks, buildTextCompletion, buildToolCallChunks, buildToolCallCompletion, extractOverrides, flattenHeaders, formatToMime, generateDeterministicEmbedding, generateId, generateMessageId, generateToolCallId, generateToolUseId, isAudioResponse, isContentWithToolCallsResponse, isEmbeddingResponse, isErrorResponse, isImageResponse, isLiveResponse, isTextResponse, isToolCallResponse, isTranscriptionResponse, isVideoResponse, resolveFixtureBlocks, resolveRequestId, strictNoMatchLogLine, strictNoMatchMessage };
 //# sourceMappingURL=helpers.d.ts.map

package/dist/helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"helpers.d.ts","names":[],"sources":["../src/helpers.ts"],"sourcesContent":[],"mappings":";;;;;;AAqSA;;;;;AAqDA;;;;;AAyDA;;;;AAAuE,iBA1TvD,oBAAA,CA0TuD,uBAAA,EAAA,MAAA,CAAA,EAAA,MAAA;AA0BvE;;;;AAA+E,iBAzU/D,oBAAA,CAyU+D,MAAA,EAAA,MAAA,EAAA,GAAA,EAAA,MAAA,EAAA,uBAAA,EAAA,MAAA,CAAA,EAAA,MAAA;AAI/E;;;;;AAOA;;;;;AAUA;AAaA;AAIA;;;;;AAQA;;AAuXc,iBA5oBE,cAAA,CA4oBF,OAAA,EA5oB0B,MAAA,CAAK,mBA4oB/B,CAAA,EA5oBqD,MA4oBrD,CAAA,MAAA,EAAA,MAAA,CAAA;AAEG,iBA3kBD,UAAA,CA2kBC,MAAA,CAAA,EAAA,MAAA,CAAA,EAAA,MAAA;AA2CD,iBAlnBA,kBAAA,CAAA,CAknB+B,EAAA,MAAA;AAAA,iBA9mB/B,iBAAA,CAAA,CA8mB+B,EAAA,MAAA;AAElC,iBA5mBG,iBAAA,CAAA,CA4mBH,EAAA,MAAA;AAIC,iBA5mBE,cAAA,CA4mBF,CAAA,EA5mBoB,eA4mBpB,CAAA,EAAA,CAAA,IA5mB2C,YA4mB3C;AACH,iBAzmBK,kBAAA,CAymBL,CAAA,EAzmB2B,eAymB3B,CAAA,EAAA,CAAA,IAzmBkD,gBAymBlD;AACR,iBAlmBa,8BAAA,CAkmBb,CAAA,EAjmBE,eAimBF,CAAA,EAAA,CAAA,IAhmBK,4BAgmBL;;AAkSH;;;;;;;AA0XA;AAgBA;AAUA;;;;;;;;;;;;;;;;;;;iBAnuCgB,oBAAA,SAA6B,qBAAqB;iBAyDlD,eAAA,IAAmB,uBAAuB;;;;;;;iBA0B1C,mBAAA,IAAuB,uBAAuB;iBAI9C,eAAA,IAAmB,uBAAuB;iBAO1C,eAAA,IAAmB,uBAAuB;;;;;cAU7C,wBAAwB;;;;;iBAarB,YAAA;iBAIA,uBAAA,IAA2B,uBAAuB;iBAQlD,eAAA,IAAmB,uBAAuB;iBAY1C,gBAAA,WACJ,eAAe,mBAAmB,+BAC3C;;;;;;iBAmHa,eAAA,oFAKF,oBACX;iBAqEa,mBAAA,YACH,8EAIC,oBACX;iBAsHa,mBAAA,iEAIF,qCACM,oCACjB;iBAqCa,uBAAA,YACH,2DAGC,qCACM,oCACjB;iBA2Ca,+BAAA,6BAEH,8EAIC,4BACH,iBACR;iBAkSa,mCAAA,6BAEH,2DAGC,qCACM,oCACjB;;;;;;iBAmXa,8BAAA;UAgBC,oBAAA;;;;;;;;;;;;;;;;iBAUD,sBAAA;;;IAIb"}
+{"version":3,"file":"helpers.d.ts","names":[],"sources":["../src/helpers.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;AAmjBA;;;;;AAUA;AAaA;AAIA;;;;AAAuF,iBAtcvE,oBAAA,CAscuE,uBAAA,EAAA,MAAA,CAAA,EAAA,MAAA;AAQvF;;;;AAAuE,iBAncvD,oBAAA,CAmcuD,MAAA,EAAA,MAAA,EAAA,GAAA,EAAA,MAAA,EAAA,uBAAA,EAAA,MAAA,CAAA,EAAA,MAAA;AAYvE;;;;;;;AAqHA;;;;;AA2EA;;;;;;;iBA7iBgB,cAAA,UAAwB,MAAA,CAAK,sBAAsB;;iBAcnD,cAAA,2BAAyC;iBA0DzC,UAAA;;;;;;;;;;;;;;;;;;iBAqBA,gBAAA,aAA6B,MAAA,CAAK;;;;;;iBAqClC,kBAAA,CAAA;iBAIA,iBAAA,CAAA;iBAIA,iBAAA,CAAA;iBAIA,cAAA,IAAkB,uBAAuB;iBAIzC,kBAAA,IAAsB,uBAAuB;iBAQ7C,8BAAA,IACX,uBACG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAmDQ,oBAAA,SAA6B,qBAAqB;;;iBA0ElD,eAAA,IAAmB,uBAAuB;;;;;;;iBA0B1C,mBAAA,IAAuB,uBAAuB;iBAI9C,eAAA,IAAmB,uBAAuB;iBAO1C,eAAA,IAAmB,uBAAuB;;;;;cAU7C,wBAAwB;;;;;iBAarB,YAAA;iBAIA,uBAAA,IAA2B,uBAAuB;iBAQlD,eAAA,IAAmB,uBAAuB;iBAY1C,gBAAA,WACJ,eAAe,mBAAmB,+BAC3C;;;;;;iBAmHa,eAAA,oFAKF,oBACX;iBAqEa,mBAAA,YACH,8EAIC,oBACX;iBAsHa,mBAAA,iEAIF,qCACM,oCACjB;iBAqCa,uBAAA,YACH,2DAGC,qCACM,oCACjB;iBA2Ca,+BAAA,6BAEH,8EAIC,4BACH,iBACR;iBAmSa,mCAAA,6BAEH,2DAGC,qCACM,oCACjB;;;;;;;;;;;;;;;iBA+wBa,8BAAA;UAgBC,oBAAA;;;;;;;;;;;;;;;;iBAUD,sBAAA;;;IAIb"}

package/dist/helpers.js

@@ -1,4 +1,6 @@
-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 { createHash, randomBytes } from "node:crypto";
@@ -25,6 +27,37 @@ 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"
+* only when record mode has an upstream for THIS provider and strict mode is
+* not refusing the miss first. `effectiveStrict` is the header-resolved value
+* from {@link resolveStrictMode}. `record.providers` is read guarded — a JS
+* caller can hand over `record: {}`.
+*/
+function wouldProxyMiss(effectiveStrict, record, providerKey) {
+	if (effectiveStrict || providerKey === void 0) return false;
+	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
@@ -142,6 +175,10 @@ function flattenHeaders(headers) {
 	}
 	return flat;
 }
+/** Structural discriminator; registration performs full transcript validation. */
+function isLiveResponse(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value) && "live" in value;
+}
 function isResponseFactory(r) {
 	return typeof r === "function";
 }
@@ -176,6 +213,57 @@ function normalizeFactoryResponse(raw) {
 function generateId(prefix = "chatcmpl") {
 	return `${prefix}-${randomBytes(12).toString("base64url")}`;
 }
+/**
+* Resolve the request id for this HTTP request.
+*
+* - When the caller sends a well-formed `X-Request-Id` (1-128 chars of
+*   `A-Za-z0-9-_.:`), it is echoed verbatim so distributed traces correlate.
+* - Otherwise (absent, empty, too long, or illegal characters) a fresh
+*   `req-…` id is generated — never trust an attacker-controlled correlation
+*   value to be a valid log key.
+*
+* Returns `{ id, generated }`. The server normalizes
+* `req.headers["x-request-id"]` to the resolved value, so every downstream
+* `flattenHeaders` journal snapshot carries it with zero per-handler edits —
+* which also means a MINTED id would otherwise ride the egress header set to
+* a real provider. The server therefore passes `generated` to
+* `markMintedRequestId` so `buildForwardHeaders` can drop it; a caller's own
+* id still forwards verbatim.
+*/
+function resolveRequestId(rawHeaders) {
+	const raw = rawHeaders["x-request-id"];
+	const first = Array.isArray(raw) ? raw[0] : raw;
+	if (typeof first === "string") {
+		const trimmed = first.trim();
+		if (trimmed.length >= 1 && trimmed.length <= 128 && /^[A-Za-z0-9\-_.:]+$/.test(trimmed)) return {
+			id: trimmed,
+			generated: false
+		};
+	}
+	return {
+		id: generateId("req"),
+		generated: true
+	};
+}
+/**
+* Requests whose `x-request-id` aimock MINTED (the caller sent none, or sent
+* an unusable one). The normalized header is indistinguishable from a
+* caller-supplied one by inspection, so the provenance is tracked out-of-band
+* and keyed on the request object, exactly like the egress auth marker.
+*/
+const mintedRequestIds = /* @__PURE__ */ new WeakSet();
+/** @internal Record that this request's `x-request-id` is aimock's own. */
+function markMintedRequestId(req, generated) {
+	if (generated) mintedRequestIds.add(req);
+}
+/**
+* @internal True when `x-request-id` on this request was minted by aimock.
+* Egress paths use it to avoid transmitting an invented correlation id to a
+* real provider.
+*/
+function hasMintedRequestId(req) {
+	return mintedRequestIds.has(req);
+}
 function generateToolCallId() {
 	return `call_${randomBytes(12).toString("base64url")}`;
 }
@@ -254,6 +342,24 @@ function resolveFixtureBlocks(blocks) {
 		} else throw new Error(`Invalid fixture block at index ${i}: unknown type ${JSON.stringify(b.type)} (expected "text" or "toolCall")`);
 	});
 }
+/** Project normalized ordered blocks without changing the fixture or generating ids. */
+function resolveFixtureBlockOutcome(blocks) {
+	const ordered = resolveFixtureBlocks(blocks);
+	let content = "";
+	const toolCalls = [];
+	for (const block of ordered) if (block.type === "text") content += block.text;
+	else toolCalls.push({
+		name: block.name,
+		arguments: block.arguments,
+		...block.id !== void 0 ? { id: block.id } : {}
+	});
+	return {
+		ordered,
+		content,
+		toolCalls,
+		hasToolCalls: toolCalls.length > 0
+	};
+}
 function isErrorResponse(r) {
 	return "error" in r && r.error !== null && typeof r.error === "object" && "message" in r.error && typeof r.error.message === "string";
 }
@@ -603,7 +709,8 @@ function buildContentWithToolCallsChunks(content, toolCalls, model, chunkSize, r
 	const chunks = [];
 	const fingerprint = overrides?.systemFingerprint;
 	if (blocks && blocks.length > 0) {
-		const ordered = resolveFixtureBlocks(blocks);
+		const outcome = resolveFixtureBlockOutcome(blocks);
+		const ordered = outcome.ordered;
 		if (reasoning) for (let i = 0; i < reasoning.length; i += chunkSize) {
 			const slice = reasoning.slice(i, i + chunkSize);
 			chunks.push({
@@ -710,7 +817,7 @@ function buildContentWithToolCallsChunks(content, toolCalls, model, chunkSize, r
 				index: 0,
 				delta: {},
 				logprobs: null,
-				finish_reason: overrides?.finishReason ?? "tool_calls"
+				finish_reason: overrides?.finishReason ?? (outcome.hasToolCalls ? "tool_calls" : "stop")
 			}],
 			...fingerprint !== void 0 && { system_fingerprint: fingerprint }
 		});
@@ -859,7 +966,31 @@ function buildContentWithToolCallsCompletion(content, toolCalls, model, reasonin
 	};
 }
 const DEFAULT_MAX_BODY_BYTES = 10 * 1024 * 1024;
-function readBody(req, maxBytes = DEFAULT_MAX_BODY_BYTES) {
+/**
+* A body read that stopped because the CLIENT sent more bytes than the route
+* allows. The socket is already destroyed when this rejects, so no status line
+* ever reaches the caller — but the fault is the caller's, and error arms that
+* journal and log the failure need to say so. Carrying the classification on
+* the error type (rather than re-matching the message text) is what lets them:
+* the message is unchanged from the plain `Error` this replaced.
+*/
+var RequestBodyTooLargeError = class extends Error {
+	constructor(maxBytes) {
+		super(`Request body exceeded size limit of ${maxBytes} bytes`);
+		this.maxBytes = maxBytes;
+		this.name = "RequestBodyTooLargeError";
+	}
+};
+/**
+* Read a request body as raw bytes, preserving every octet.
+*
+* This is the byte-level primitive {@link readBody} is built on: routes that
+* must not lose bytes (binary file uploads) take the Buffer, everything else
+* keeps taking the decoded string. Splitting it this way leaves the text path
+* byte-identical — `readBody` performs exactly the same `Buffer.concat(...)`
+* + default (utf8) `toString()` it always did, just one call later.
+*/
+function readBodyBuffer(req, maxBytes = DEFAULT_MAX_BODY_BYTES) {
 	return new Promise((resolve, reject) => {
 		const chunks = [];
 		let totalBytes = 0;
@@ -870,7 +1001,7 @@ function readBody(req, maxBytes = DEFAULT_MAX_BODY_BYTES) {
 			if (totalBytes > maxBytes) {
 				settled = true;
 				req.destroy();
-				reject(/* @__PURE__ */ new Error(`Request body exceeded size limit of ${maxBytes} bytes`));
+				reject(new RequestBodyTooLargeError(maxBytes));
 				return;
 			}
 			chunks.push(chunk);
@@ -878,8 +1009,58 @@ function readBody(req, maxBytes = DEFAULT_MAX_BODY_BYTES) {
 		req.on("end", () => {
 			if (!settled) {
 				settled = true;
-				resolve(Buffer.concat(chunks).toString());
+				resolve(Buffer.concat(chunks));
+			}
+		});
+		req.on("error", (err) => {
+			if (!settled) {
+				settled = true;
+				reject(err);
+			}
+		});
+	});
+}
+/**
+* Read a request body that may legitimately be over-size, without either
+* buffering it all or dropping the socket.
+*
+* {@link readBodyBuffer} answers an over-size body with `req.destroy()`: no
+* status line, no body, no CORS headers. That is the right default for routes
+* whose limit is a pure DoS bound, but it is the wrong answer for a route that
+* owes the caller a `400` describing what was wrong — the caller cannot read an
+* error it never receives. So this variant splits the two concerns:
+*
+* - `maxBytes` bounds MEMORY. Past it the buffered chunks are dropped and the
+*   body is only counted, so peak retention never exceeds `maxBytes` no matter
+*   how large the body is. The caller gets `buffer: null` and answers itself.
+* - `drainMaxBytes` bounds WORK, and is the only socket drop here: a body that
+*   keeps coming past it is not worth draining and rejects as `readBodyBuffer`
+*   would.
+*/
+function readBodyBufferBounded(req, maxBytes, drainMaxBytes) {
+	return new Promise((resolve, reject) => {
+		let chunks = [];
+		let totalBytes = 0;
+		let settled = false;
+		req.on("data", (chunk) => {
+			if (settled) return;
+			totalBytes += chunk.length;
+			if (chunks !== null && totalBytes > maxBytes) chunks = null;
+			if (totalBytes > drainMaxBytes) {
+				settled = true;
+				req.destroy();
+				reject(new RequestBodyTooLargeError(drainMaxBytes));
+				return;
 			}
+			if (chunks !== null) chunks.push(chunk);
+		});
+		req.on("end", () => {
+			if (settled) return;
+			settled = true;
+			resolve({
+				buffer: chunks === null ? null : Buffer.concat(chunks),
+				bytesRead: totalBytes
+			});
 		});
 		req.on("error", (err) => {
 			if (!settled) {
@@ -889,6 +1070,9 @@ function readBody(req, maxBytes = DEFAULT_MAX_BODY_BYTES) {
 		});
 	});
 }
+function readBody(req, maxBytes = DEFAULT_MAX_BODY_BYTES) {
+	return readBodyBuffer(req, maxBytes).then((buf) => buf.toString());
+}
 /**
 * Case-insensitive substring/regex match used for search, rerank, and
 * moderation endpoints where exact casing rarely matters. String patterns
@@ -907,11 +1091,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"];
@@ -935,6 +1122,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.
 */
@@ -1121,7 +1539,64 @@ function buildEmbeddingResponse(embeddings, model, usage) {
 		}
 	};
 }
+/**
+* Build a stable, human-readable identifier for a fixture's match shape, for
+* any log line that has to name WHICH fixture it means. The `Fixture` type
+* carries no `id`/`name`, so the matchers are the only handle a reader has.
+*
+* Used by the relaxed-turnIndex warning (`router.ts`) and by the chaos
+* rejected-value warning (`chaos.ts`); one implementation so the two name the
+* same fixture the same way. The obvious `JSON.stringify(match)` is unfit: it
+* DROPS `predicate` functions (non-serialisable) and serialises any RegExp
+* matcher to `{}`, so a predicate- or regex-gated fixture's warning collapsed to
+* an uninformative "served fixture {}" / `{"userMessage":{}}` blob.
+*
+* Instead we list the PRESENT matcher keys in declaration order, annotating each
+* by VALUE KIND so predicates and regexes survive: `predicate(fn)`,
+* `userMessage(regex)`, `userMessage("hello")`, `turnIndex=0`, etc. The
+* fixture's array `index` is prefixed as a stable positional identifier when
+* the caller knows it (i.e. `>= 0`); callers holding only the fixture object
+* pass `-1` and get the matcher summary alone. String/number values are shown
+* inline (truncated) so a content match remains recognisable; the whole string
+* is capped to keep the log line bounded.
+*/
+const DESCRIBE_MATCH_MAX = 160;
+function describeMatch(match, index) {
+	const parts = [];
+	for (const [key, value] of Object.entries(match)) {
+		if (value === void 0) continue;
+		if (typeof value === "function") parts.push(key === "predicate" ? "[predicate]" : `${key}[fn]`);
+		else if (value instanceof RegExp) parts.push(`${key}(${value})`);
+		else if (typeof value === "string") {
+			const v = value.length > 40 ? `${value.slice(0, 40)}…` : value;
+			parts.push(`${key}(${JSON.stringify(v)})`);
+		} else if (Array.isArray(value)) parts.push(`${key}(${value.length} item${value.length === 1 ? "" : "s"})`);
+		else if (typeof value === "object" && value !== null) {
+			const json = JSON.stringify(value);
+			parts.push(`${key}(${json.length > 40 ? `${json.slice(0, 40)}…` : json})`);
+		} else parts.push(`${key}=${String(value)}`);
+	}
+	const keys = parts.length > 0 ? parts.join(", ") : "no matchers";
+	const full = `${index >= 0 ? `#${index} ` : ""}{ ${keys} }`;
+	if (full.length <= DESCRIBE_MATCH_MAX) return full;
+	const head = full.slice(0, DESCRIBE_MATCH_MAX - 4);
+	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, buildContentWithToolCallsChunks, buildContentWithToolCallsCompletion, buildEmbeddingResponse, buildTextChunks, buildTextCompletion, buildToolCallChunks, buildToolCallCompletion, buildUsageChunk, extractOverrides, flattenHeaders, formatToMime, generateDeterministicEmbedding, generateId, generateMessageId, generateToolCallId, generateToolUseId, getContext, getTestId, isAudioResponse, isContentWithToolCallsResponse, isEmbeddingResponse, isErrorResponse, isImageResponse, isJSONResponse, isJsonObject, isResponseFactory, isTextResponse, isToolCallResponse, isTranscriptionResponse, isVideoResponse, matchesPattern, normalizeEmbeddingInput, normalizeTextInput, readBody, resolveFixtureBlocks, resolveReasoningArtifactsForModel, resolveReasoningForModel, resolveResponse, resolveStrictMode, resolveTestId, resolveUsage, serializeErrorResponse, slugifyContext, slugifyTestId, strictNoMatchLogLine, strictNoMatchMessage, strictOverrideField, validateChatMessages, validateEmbeddingDimensions, validateToolsField };
+export { FORMAT_TO_CONTENT_TYPE, MAX_EMBEDDING_DIMENSIONS, RequestBodyTooLargeError, buildContentWithToolCallsChunks, buildContentWithToolCallsCompletion, buildEmbeddingResponse, buildTextChunks, buildTextCompletion, buildToolCallChunks, buildToolCallCompletion, buildUsageChunk, decodeMcpHeaderValue, 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, parseStrictIntegerText, readBody, readBodyBufferBounded, resolveFixtureBlockOutcome, resolveFixtureBlocks, resolveMcpIdentity, resolveReasoningArtifactsForModel, resolveReasoningForModel, resolveRequestId, resolveResponse, resolveStrictMode, resolveTestId, resolveUsage, serializeErrorResponse, slugifyContext, slugifyTestId, strictNoMatchLogLine, strictNoMatchMessage, strictOverrideField, validateChatMessages, validateEmbeddingDimensions, validateToolsField, wouldProxyMiss };
 //# sourceMappingURL=helpers.js.map