@copilotkit/aimock 1.42.1 → 1.43.0

package/dist/helpers.js

@@ -26,6 +26,18 @@ function resolveStrictMode(serverDefault, rawHeaders) {
 	return serverDefault ?? false;
 }
 /**
+* 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
 * directly into a journal entry's `response` object:
@@ -142,6 +154,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 +192,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 +321,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 +688,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 +796,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 +945,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 +980,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,7 +988,7 @@ 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) => {
@@ -890,6 +1000,59 @@ function readBody(req, maxBytes = DEFAULT_MAX_BODY_BYTES) {
 	});
 }
 /**
+* 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) {
+				settled = true;
+				reject(err);
+			}
+		});
+	});
+}
+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
 * are lowercased on both sides before comparison.
@@ -1121,7 +1284,51 @@ 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}, … }`;
+}
 
 //#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, 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 };
 //# sourceMappingURL=helpers.js.map