@copilotkit/aimock 1.44.0 → 1.45.0

package/dist/mcp-fakes.js

@@ -1,4 +1,5 @@
 import { DEFAULT_TEST_ID, MCP_FAKES_ECHO_LIMIT } from "./constants.js";
+import { cutText } from "./echo-text.js";
 import { build, fixed, fullText, jsonText, msg, quote, quoteJson } from "./message-text.js";
 import { FixtureLoadError } from "./fixture-loader.js";
 
@@ -46,7 +47,10 @@ const BLOCK_KEYS = new Set([
 	"scope",
 	"mount",
 	"undeclaredTools",
-	"tools"
+	"tools",
+	"list",
+	"recorded",
+	"timing"
 ]);
 const TOOL_KEYS = new Set([
 	"name",
@@ -59,8 +63,21 @@ const CALL_KEYS = new Set([
 	"anyArgs",
 	"result",
 	"error",
-	"id"
+	"id",
+	"notifications",
+	"durationMs"
 ]);
+/**
+* C9: most events one fake event log keeps (per test id, and the untagged
+* log). Past it the oldest event is dropped and the log's report says
+* `evicted: true`. Report-only: claims and snapshots never read it.
+*/
+const MCP_FAKES_MAX_EVENTS_PER_LOG = 1e3;
+/**
+* Largest `args` (JSON, UTF-8 bytes) an event keeps. A larger one is stored as
+* `{ __aimock_truncated: true, originalByteSize }`, the journal `capBody` shape.
+*/
+const MCP_FAKES_MAX_EVENT_ARGS_BYTES = 4096;
 const SCOPE_KEYS = new Set(["testId", "context"]);
 const TIER_ORDER = [
 	"testId+context",
@@ -68,6 +85,29 @@ const TIER_ORDER = [
 	"context",
 	"shared"
 ];
+/** The last `seq` given to an event, shared by every store in the process. */
+let lastEventSeq = 0;
+/**
+* An event's `args` as the log keeps it: a frozen copy when its JSON is at
+* most `MCP_FAKES_MAX_EVENT_ARGS_BYTES` UTF-8 bytes, else the journal's
+* truncation marker. A value with no JSON text (`undefined`, or one whose
+* `JSON.stringify` throws) is kept as its rendered text.
+*/
+function boundedArgs(args) {
+	let text;
+	try {
+		text = JSON.stringify(args);
+	} catch {
+		text = void 0;
+	}
+	if (text === void 0) return args === void 0 ? void 0 : echo(args);
+	const size = Buffer.byteLength(text, "utf8");
+	if (size > MCP_FAKES_MAX_EVENT_ARGS_BYTES) return Object.freeze({
+		__aimock_truncated: true,
+		originalByteSize: size
+	});
+	return deepFreeze(JSON.parse(text));
+}
 /**
 * The error a failed add throws. It is a `FixtureLoadError` whose `rule`,
 * `file`, `blockId` and `entryId` are those of the first error, and whose
@@ -150,6 +190,17 @@ function hasOwnKey(obj, key) {
 function shown(value, max = MCP_FAKES_ECHO_LIMIT) {
 	return jsonText(render(value), max);
 }
+/**
+* One user value as message text: `shown`, built alone, so cut to `limit`
+* chars as the builder cuts it. A `limit` below 1 keeps nothing (`""`), as
+* `cutText` does; a `NaN` limit is a `RangeError`.
+*
+* @internal
+*/
+function echo(value, limit = MCP_FAKES_ECHO_LIMIT) {
+	if (!(limit >= 1)) return cutText(render(value), limit, "json");
+	return build(msg`${shown(value, limit)}`);
+}
 function render(value) {
 	if (value === void 0) return "undefined";
 	if (typeof value === "number" && !Number.isFinite(value)) return String(value);
@@ -651,10 +702,11 @@ function shape(required, optional = {}) {
 * `Annotations.lastModified`.
 */
 const ISO_DATETIME = /^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$/;
+const mustBeIsoDateTime = (v, p) => typeof v === "string" && ISO_DATETIME.test(v) ? null : msg`${pathPart(p)} must be an ISO 8601 date-time with seconds and an offset, got ${shown(v)}`;
 const ANNOTATIONS = shape({}, {
 	audience: arrayOf(oneOf(["user", "assistant"])),
 	priority: (v, p) => typeof v === "number" && v >= 0 && v <= 1 ? null : msg`${pathPart(p)} must be a number from 0 to 1, got ${shown(v)}`,
-	lastModified: (v, p) => typeof v === "string" && ISO_DATETIME.test(v) ? null : msg`${pathPart(p)} must be an ISO 8601 date-time with seconds and an offset, got ${shown(v)}`
+	lastModified: mustBeIsoDateTime
 });
 const ICON = shape({ src: mustBeString }, {
 	mimeType: mustBeString,
@@ -772,6 +824,59 @@ function inputSchemaProblem(schema) {
 	if (!isPlainObject(schema)) return mustBeObject(schema, "inputSchema");
 	return jsonProblem(schema, "inputSchema") ?? INPUT_SCHEMA(schema, "inputSchema");
 }
+/** A finite number >= 0 (FA3 `atMs`, FA4 `durationMs`). */
+const mustBeNonNegative = (v, p) => typeof v === "number" && Number.isFinite(v) && v >= 0 ? null : msg`${pathPart(p)} must be a number >= 0, got ${shown(v)}`;
+/** FA2 `recorded`. Other keys are not checked. */
+const RECORDED = shape({
+	upstream: mustBeString,
+	protocolVersion: mustBeString,
+	aimockVersion: mustBeString,
+	at: mustBeIsoDateTime
+}, { serverInfo: mustBeObject });
+/** One FA3 notification. Other keys are not checked. */
+const NOTIFICATION = shape({
+	atMs: mustBeNonNegative,
+	method: mustBeString,
+	params: mustBeObject
+});
+/** FA1: an array of JSON objects, each with a string `name`, no name twice. */
+function listProblem(v) {
+	if (!Array.isArray(v)) return msg`list must be an array of tool objects, got ${shown(v)}`;
+	const json = jsonProblem(v, "list");
+	if (json) return json;
+	const names = /* @__PURE__ */ new Set();
+	for (let i = 0; i < v.length; i++) {
+		const tool = v[i];
+		if (!isPlainObject(tool) || typeof tool.name !== "string") return msg`list[${i}] must be a tool object with a string name, got ${shown(tool)}`;
+		if (names.has(tool.name)) return msg`list[${i}] repeats the tool name ${quote(tool.name)}`;
+		names.add(tool.name);
+	}
+	return null;
+}
+/** FA2. */
+function recordedProblem(v) {
+	if (!isPlainObject(v)) return msg`recorded must be a JSON object, got ${shown(v)}`;
+	return jsonProblem(v, "recorded") ?? RECORDED(v, "recorded");
+}
+/** FA3. */
+function notificationsProblem(v) {
+	if (!Array.isArray(v)) return msg`notifications must be an array, got ${shown(v)}`;
+	return jsonProblem(v, "notifications") ?? arrayOf(NOTIFICATION, "an array of notifications")(v, "notifications");
+}
+/**
+* A malformed FA key of one block (and, for FA3/FA4, one entry): the 1.44.0
+* rule `mcp-fakes/bad-block:h`, with the `record-replay/fa-*` value first in
+* the message detail (`[mcp-fakes/bad-block:h] [record-replay/fa-list] ...`).
+*/
+function faError(ctx, faRule, detail, entryId = null) {
+	return new FixtureLoadError({
+		rule: "mcp-fakes/bad-block:h",
+		file: ctx.source,
+		blockId: ctx.blockId,
+		entryId,
+		detail: msg`[${fixed(faRule)}] ${detail}`
+	});
+}
 /**
 * Validate one call entry of the input snapshot. Every error goes to
 * `errors`; returns its entry id whether or not it is clean, so that the
@@ -795,6 +900,14 @@ function validateCall(raw, toolName, label, index, ctx, errors) {
 	}
 	const before = errors.length;
 	for (const key of presentKeys(raw)) if (!CALL_KEYS.has(key)) bad("h", msg`has unknown key ${shown(key)}`);
+	if (has(raw, "notifications")) {
+		const problem = notificationsProblem(raw.notifications);
+		if (problem) errors.push(faError(ctx, "record-replay/fa-notifications", msg`${where} ${problem}`, entryId));
+	}
+	if (has(raw, "durationMs")) {
+		const problem = mustBeNonNegative(raw.durationMs, "durationMs");
+		if (problem) errors.push(faError(ctx, "record-replay/fa-duration", msg`${where} ${problem}`, entryId));
+	}
 	if (has(raw, "id") && !isNonEmptyString(raw.id)) bad("d", msg`id must be a non-empty string, got ${shown(raw.id)}`);
 	if (has(raw, "anyArgs") && raw.anyArgs !== true) bad("j", msg`anyArgs must be true, got ${shown(raw.anyArgs)}`);
 	const hasArgs = has(raw, "args");
@@ -817,13 +930,17 @@ function validateCall(raw, toolName, label, index, ctx, errors) {
 	};
 	const match = hasArgs ? { args: copyJson(raw.args, true) } : { anyArgs: true };
 	const answer = hasResult ? { result: copyJson(raw.result, true) } : { error: raw.error };
+	const recorded = {};
+	if (has(raw, "notifications")) recorded.notifications = copyJson(raw.notifications, true);
+	if (has(raw, "durationMs")) recorded.durationMs = raw.durationMs;
 	return {
 		entryId,
 		call: Object.freeze({
 			id: entryId,
 			index,
 			...match,
-			...answer
+			...answer,
+			...recorded
 		})
 	};
 }
@@ -891,6 +1008,17 @@ function validateBlock(raw, source, blockIndex, load, errors) {
 	}
 	const before = errors.length;
 	for (const key of presentKeys(raw)) if (!BLOCK_KEYS.has(key)) errors.push(badBlock(ctx, "h", msg`block has unknown key ${shown(key)}`));
+	if (has(raw, "list")) {
+		const problem = listProblem(raw.list);
+		if (problem) errors.push(faError(ctx, "record-replay/fa-list", problem));
+	}
+	if (has(raw, "recorded")) {
+		const problem = recordedProblem(raw.recorded);
+		if (problem) errors.push(faError(ctx, "record-replay/fa-recorded", problem));
+	}
+	let timing = "recorded";
+	if (has(raw, "timing")) if (raw.timing === "recorded" || raw.timing === "immediate") timing = raw.timing;
+	else errors.push(faError(ctx, "record-replay/fa-timing", msg`timing must be "recorded" or "immediate", got ${shown(raw.timing)}`));
 	const scope = validateScope(raw.scope, ctx, errors);
 	let undeclared;
 	if (has(raw, "undeclaredTools")) if (raw.undeclaredTools === "allow" || raw.undeclaredTools === "deny") undeclared = raw.undeclaredTools;
@@ -947,7 +1075,10 @@ function validateBlock(raw, source, blockIndex, load, errors) {
 			tier: tierOf(scope),
 			mount,
 			...undeclared !== void 0 ? { undeclaredTools: undeclared } : {},
-			tools: Object.freeze(tools)
+			tools: Object.freeze(tools),
+			...has(raw, "list") ? { list: copyJson(raw.list, true) } : {},
+			...has(raw, "recorded") ? { recorded: copyJson(raw.recorded, true) } : {},
+			timing
 		}),
 		entryIds,
 		warnings
@@ -1194,6 +1325,21 @@ var McpFakeStore = class {
 	*/
 	loadCounts = /* @__PURE__ */ new Map();
 	maxTestIds;
+	/**
+	* RP2 fake event logs: supplied test id → its events, oldest first. Map
+	* insertion order is the FIFO order of the test-id cap.
+	*/
+	events = /* @__PURE__ */ new Map();
+	/** The event log of requests with no test id: a ring of the newest events. */
+	untaggedEvents = [];
+	/** The untagged event log dropped an event (C9). */
+	untaggedOverflow = false;
+	/**
+	* C9: test ids whose event log overflowed or was evicted, so their report
+	* is incomplete (`evicted: true`). Report-only: `claim`, `snapshot` and
+	* `policy` never read it, so tool calls are unchanged.
+	*/
+	reportOverflow = /* @__PURE__ */ new Set();
 	constructor(options = {}) {
 		this.maxTestIds = checkCap(options.maxTestIds ?? MCP_FAKES_DEFAULT_MAX_TEST_IDS);
 	}
@@ -1238,10 +1384,10 @@ var McpFakeStore = class {
 	add(sources, origin) {
 		const originData = snapshotInput(origin);
 		const kind = isPlainObject(originData) ? originData.kind : void 0;
-		if (kind !== "file" && kind !== "code" && kind !== "control-api") throw new McpFakesAddError([badBlock({
+		if (kind !== "file" && kind !== "code" && kind !== "control-api" && kind !== "record") throw new McpFakesAddError([badBlock({
 			source: null,
 			blockId: null
-		}, "i", isPlainObject(originData) ? msg`origin.kind must be "file", "code" or "control-api", got ${shown(kind)}` : msg`origin must be an object { kind }, got ${shown(originData)}`)], []);
+		}, "i", isPlainObject(originData) ? msg`origin.kind must be "file", "code", "control-api" or "record", got ${shown(kind)}` : msg`origin must be an object { kind }, got ${shown(originData)}`)], []);
 		const runtimeNumber = kind === "file" ? null : this.nextRuntimeNumber(kind);
 		const runtimeSource = runtimeNumber === null ? null : `${kind}#${runtimeNumber}`;
 		const input = snapshotInput(sources, MCP_FAKES_MAX_DEPTH + 2);
@@ -1390,11 +1536,172 @@ var McpFakeStore = class {
 			this.consumed.clear();
 			this.untagged.clear();
 			this.evicted.clear();
+			this.events.clear();
+			this.reportOverflow.clear();
+			this.untaggedEvents = [];
+			this.untaggedOverflow = false;
 			return;
 		}
 		this.consumed.delete(testId);
 		this.evicted.delete(testId);
-		if (testId === MCP_FAKES_DEFAULT_TEST_ID) this.untagged.clear();
+		this.events.delete(testId);
+		this.reportOverflow.delete(testId);
+		if (testId === MCP_FAKES_DEFAULT_TEST_ID) {
+			this.untagged.clear();
+			this.untaggedEvents = [];
+			this.untaggedOverflow = false;
+		}
+	}
+	/**
+	* MR12: mark entries consumed for `testId` (null = untagged), as a claim
+	* would. Ids not loaded on this mount are ignored, and so is a test id the
+	* cap evicted (its claims fail as `evicted` until it is reset).
+	*/
+	markConsumed(testId, entryIds) {
+		if (testId !== null && this.evicted.has(testId)) return;
+		const known = entryIds.filter((entryId) => this.ids.has(entryId));
+		if (known.length === 0) return;
+		const state = this.stateFor(testId);
+		for (const entryId of known) state.add(entryId);
+	}
+	/**
+	* AM7/FA1: the `list` of the most specific applicable tier that has one,
+	* else null. Inside a tier, the first block in load order with a `list`.
+	*/
+	recordedList(identity) {
+		const blocks = this.applicable(identity);
+		for (const tier of TIER_ORDER) {
+			const block = blocks.find((b) => b.tier === tier && b.list !== void 0);
+			if (block?.list) return block.list;
+		}
+		return null;
+	}
+	/** FA5 timing and the FA3/FA4 values of an answered entry (for MR15 framing). */
+	replayOf(entryId) {
+		for (const block of this.blocks) for (const tool of block.tools) {
+			const entry = tool.calls.find((c) => c.id === entryId);
+			if (entry) return {
+				timing: block.timing,
+				notifications: entry.notifications ?? NO_NOTIFICATIONS,
+				durationMs: entry.durationMs
+			};
+		}
+		return null;
+	}
+	/** C7: true when any loaded call entry has a `notifications/message` (gates logging). */
+	hasRecordedLogs() {
+		return this.blocks.some((block) => block.tools.some((tool) => tool.calls.some((call) => call.notifications?.some((n) => n.method === "notifications/message"))));
+	}
+	/**
+	* RP2: append one event to the identity's log, with the next process-wide
+	* `seq` and its `args` bounded (`MCP_FAKES_MAX_EVENT_ARGS_BYTES`). A log
+	* past `MCP_FAKES_MAX_EVENTS_PER_LOG` drops its oldest event and its report
+	* says `evicted: true`; a new test id past the test-id cap evicts the
+	* oldest test id's log the same way (C9). Never touches consumption state.
+	*/
+	logEvent(identity, event) {
+		lastEventSeq += 1;
+		const stored = Object.freeze({
+			...event,
+			args: boundedArgs(event.args),
+			seq: lastEventSeq
+		});
+		const testId = identity.testId;
+		if (testId === null) {
+			this.untaggedEvents.push(stored);
+			if (this.untaggedEvents.length > MCP_FAKES_MAX_EVENTS_PER_LOG) {
+				this.untaggedEvents.shift();
+				this.untaggedOverflow = true;
+			}
+			return;
+		}
+		let log = this.events.get(testId);
+		if (!log) {
+			log = [];
+			this.events.set(testId, log);
+			this.enforceEventCap();
+		}
+		log.push(stored);
+		if (log.length > MCP_FAKES_MAX_EVENTS_PER_LOG) {
+			log.shift();
+			this.reportOverflow.add(testId);
+		}
+	}
+	/**
+	* RP3 parts for this mount (report assembly is src/mcp-fakes-report.ts).
+	* `served`, `failures` and `unfaked` come from the events whose context is
+	* exactly `context`, in `seq` order; `unconsumed` (tiers `testId+context`
+	* and `testId`) and `sharedUnconsumed` (tiers `context` and `shared`) are
+	* the applicable entries of this store that `testId` has not consumed,
+	* labelled with `mount`, the path the store's mock is served at. Every
+	* block in the store answers there (`claim` does not read `block.mount`),
+	* so none is left out by its own `mount` value: a mock that loaded its own
+	* fakes (default mount "/mcp") and is mounted at another path still reports
+	* them. Reads only: building a report changes no state.
+	*/
+	reportPart(testId, context, mount) {
+		const part = {
+			evicted: testId === null ? this.untaggedOverflow : this.evicted.has(testId) || this.reportOverflow.has(testId),
+			served: [],
+			unconsumed: [],
+			unfaked: [],
+			failures: [],
+			sharedUnconsumed: []
+		};
+		const log = testId === null ? this.untaggedEvents : this.events.get(testId) ?? [];
+		for (const event of log) {
+			if (event.context !== context) continue;
+			const { seq, tool, args } = event;
+			if (event.outcome === "answered") part.served.push({
+				entryId: event.entryId,
+				mount: event.mount,
+				tool,
+				args,
+				seq
+			});
+			else if (event.outcome === "unfaked") part.unfaked.push({
+				mount: event.mount,
+				tool,
+				args,
+				answeredBy: event.answeredBy
+			});
+			else part.failures.push({
+				code: event.code,
+				mount: event.mount,
+				tool,
+				args,
+				seq
+			});
+		}
+		const used = this.stateOf(testId);
+		for (const block of this.applicable({
+			testId,
+			context,
+			undeclared: null
+		})) {
+			const own = block.tier === "testId+context" || block.tier === "testId";
+			for (const tool of block.tools) for (const call of tool.calls) {
+				if (used?.has(call.id)) continue;
+				if (!own) part.sharedUnconsumed.push({
+					entryId: call.id,
+					mount,
+					tool: tool.name
+				});
+				else if (call.args) part.unconsumed.push({
+					entryId: call.id,
+					mount,
+					tool: tool.name,
+					args: copyJson(call.args)
+				});
+				else part.unconsumed.push({
+					entryId: call.id,
+					mount,
+					tool: tool.name,
+					anyArgs: true
+				});
+			}
+		}
+		return part;
 	}
 	/** Every entry id on this mount, in load order. */
 	allEntryIds() {
@@ -1581,9 +1888,25 @@ var McpFakeStore = class {
 			if (this.consumed.size <= this.maxTestIds) break;
 			this.consumed.delete(oldest);
 			this.evicted.add(oldest);
+			if (this.events.delete(oldest)) this.reportOverflow.add(oldest);
+		}
+		this.enforceEventCap();
+	}
+	/**
+	* The test-id FIFO cap on event logs: evict the oldest logs until the cap
+	* holds, marking each in the report-only `reportOverflow` (never `evicted`).
+	*/
+	enforceEventCap() {
+		if (this.maxTestIds === 0) return;
+		for (const oldest of this.events.keys()) {
+			if (this.events.size <= this.maxTestIds) break;
+			this.events.delete(oldest);
+			this.reportOverflow.add(oldest);
 		}
 	}
 };
+/** `replayOf` notifications of an entry that recorded none. */
+const NO_NOTIFICATIONS = Object.freeze([]);
 /**
 * The detail of a block-id collision (bad block (f)). The message prefix
 * already names the block id, so the detail names the two sources.