@webskill/sdk 0.29.0 → 0.30.0-next.1

package/dist/testing.js

@@ -1,6 +1,7 @@
 import { t as MockLlmClient } from "./llm-eIQNO9tr.js";
 import { t as MemoryArtifactStore } from "./memoryArtifactStore-Bs7glPqm.js";
 import { n as loadGoogleConfigFromEnv, r as loadLlmConfigFromEnv, t as loadAnthropicConfigFromEnv } from "./env-Bj1MI2Ww.js";
+import { a as createWebSocketControllerTransport, c as ControllerRpcError, d as CONTROLLER_PROTOCOL_VERSION, f as CONTROLLER_TOOL_NAMES, i as randomToken, l as controllerError, n as base64UrlToBytes, t as createControllerDevice, u as CONTROLLER_PROTOCOL_LIMITS } from "./device-DMUgqNzr.js";
 
 //#region ../runtime/src/interaction/mockUiBridge.ts
 /**
@@ -63,4 +64,1289 @@ var InMemoryStore = class {
 };
 
 //#endregion
-export { InMemoryStore, MemoryArtifactStore, MockLlmClient, MockUiBridge, loadAnthropicConfigFromEnv, loadGoogleConfigFromEnv, loadLlmConfigFromEnv };
+//#region ../controller/src/testing/referenceController.ts
+var ReferenceController = class {
+	url;
+	options;
+	instanceId;
+	controllerName;
+	server;
+	transports = /* @__PURE__ */ new Set();
+	authorizedTransports = /* @__PURE__ */ new Map();
+	pendingByCode = /* @__PURE__ */ new Map();
+	sessions = /* @__PURE__ */ new Map();
+	grants = /* @__PURE__ */ new Map();
+	nonces = /* @__PURE__ */ new Map();
+	errors = [];
+	readyResults = /* @__PURE__ */ new Map();
+	readyWaiters = /* @__PURE__ */ new Map();
+	pairingOutcomes = /* @__PURE__ */ new Map();
+	pairingWaiters = /* @__PURE__ */ new Map();
+	constructor(url, options = {}) {
+		this.url = url;
+		this.options = options;
+		this.instanceId = options.instanceId ?? "reference-controller";
+		this.controllerName = options.controllerName ?? "Reference Controller";
+	}
+	get grantedDevices() {
+		return [...this.grants.values()];
+	}
+	get observedErrors() {
+		return this.errors;
+	}
+	get connectionCount() {
+		return [...this.transports].filter((transport) => transport.connected).length;
+	}
+	mcpTransport() {
+		const transport = [...this.authorizedTransports.values()].at(-1);
+		if (!transport?.connected) throw controllerError("CONTROLLER_NOT_PAIRED", "No authorized device transport is available");
+		return transport;
+	}
+	deviceTransport() {
+		const transport = [...this.transports].at(-1);
+		if (!transport?.connected) throw controllerError("CONTROLLER_NOT_PAIRED", "No device transport is available");
+		return transport;
+	}
+	async waitForReady(sessionId = [...this.authorizedTransports.keys()].at(-1), timeoutMs = 5e3) {
+		if (!sessionId) throw controllerError("CONTROLLER_NOT_PAIRED", "No device pairing session is available");
+		const existing = this.readyResults.get(sessionId);
+		if (existing) return existing;
+		return await new Promise((resolve, reject) => {
+			const waiters = this.readyWaiters.get(sessionId) ?? [];
+			const timer = setTimeout(() => {
+				this.readyWaiters.delete(sessionId);
+				reject(/* @__PURE__ */ new Error("Device did not announce protocol readiness"));
+			}, timeoutMs);
+			waiters.push({
+				resolve,
+				timer
+			});
+			this.readyWaiters.set(sessionId, waiters);
+		});
+	}
+	async waitForPairingOutcome(sessionId, outcome, timeoutMs = 5e3) {
+		const existing = this.pairingOutcomes.get(sessionId);
+		if (existing) {
+			if (existing !== outcome) throw new Error(`Pairing outcome was ${existing}, expected ${outcome}`);
+			return;
+		}
+		await new Promise((resolve, reject) => {
+			const waiters = this.pairingWaiters.get(sessionId) ?? [];
+			const timer = setTimeout(() => {
+				this.pairingWaiters.delete(sessionId);
+				reject(/* @__PURE__ */ new Error(`Pairing outcome did not arrive: ${outcome}`));
+			}, timeoutMs);
+			waiters.push({
+				resolve,
+				timer
+			});
+			this.pairingWaiters.set(sessionId, waiters);
+		});
+	}
+	async start() {
+		const { WebSocketServer } = await import("ws");
+		const target = new URL(this.url);
+		const server = new WebSocketServer({
+			host: target.hostname.replace(/^\[|\]$/g, ""),
+			port: Number(target.port || 0)
+		});
+		this.server = server;
+		server.on("connection", (socket) => this.accept(socket));
+		await new Promise((resolve, reject) => {
+			server.once("listening", () => resolve());
+			server.once("error", (error) => reject(error));
+		});
+	}
+	accept(socket) {
+		let authorizedSession;
+		const transport = createWebSocketControllerTransport({
+			url: this.url,
+			socket,
+			isAuthorized: () => {
+				if (!authorizedSession) return false;
+				const device = this.grants.get(authorizedSession);
+				return device !== void 0 && !device.revoked && Date.now() <= device.expiresAt;
+			},
+			onControlRequest: async (method, params) => {
+				if (method === "webskill/ping") return {};
+				if (method === "webskill/bye") {
+					await transport.close();
+					return {};
+				}
+				const result = await this.onRequest(method, params, transport, (sessionId) => {
+					authorizedSession = sessionId;
+				}, () => authorizedSession);
+				if (authorizedSession) this.authorizedTransports.set(authorizedSession, transport);
+				return result;
+			},
+			onControlNotification: async (method, params) => {
+				if (method === "webskill/ready" && !this.options.ignoreReady) this.noteReady(params, authorizedSession);
+			},
+			onclose: () => {
+				this.transports.delete(transport);
+				if (authorizedSession && this.authorizedTransports.get(authorizedSession) === transport) {
+					this.authorizedTransports.delete(authorizedSession);
+					this.readyResults.delete(authorizedSession);
+				}
+			},
+			onerror: (error) => this.errors.push(error)
+		});
+		this.transports.add(transport);
+		transport.connect().catch((error) => this.errors.push(error));
+	}
+	noteReady(params, authorizedSession) {
+		if (!authorizedSession || params.deviceEpoch !== authorizedSession) throw controllerError("CONTROLLER_MESSAGE_INVALID", "The ready notification does not match the authorized device epoch");
+		this.readyResults.set(authorizedSession, params);
+		for (const waiter of this.readyWaiters.get(authorizedSession) ?? []) {
+			clearTimeout(waiter.timer);
+			waiter.resolve(params);
+		}
+		this.readyWaiters.delete(authorizedSession);
+	}
+	onRequest(method, params, transport, authorize, currentSession) {
+		switch (method) {
+			case "webskill/hello": return this.hello(params);
+			case "webskill/pair.start": return this.pairStart(params, transport);
+			case "webskill/pair.confirm": return this.pairConfirm(params, authorize);
+			case "webskill/auth.present": return this.authPresent(params, authorize);
+			case "webskill/auth.challenge": return this.authChallenge(currentSession());
+			case "webskill/auth.renew": return this.authRenew(params, authorize);
+			default: throw controllerError("CONTROLLER_CAPABILITY_MISSING", `Unsupported controller request: ${method}`);
+		}
+	}
+	hello(params) {
+		const selected = params.protocolVersions.find((version) => (this.options.allowedProtocolVersions ?? ["0.1"]).includes(version));
+		if (!selected) throw controllerError("CONTROLLER_PROTOCOL_UNSUPPORTED", "No controller protocol version is shared");
+		return {
+			protocolVersion: selected,
+			controllerInstanceId: this.instanceId,
+			controllerName: this.controllerName,
+			excludedOrigins: this.options.excludedOrigins ?? []
+		};
+	}
+	pairStart(params, transport) {
+		const sessionId = randomToken(18);
+		const code = randomCode();
+		const pending = {
+			sessionId,
+			publicKey: params.publicKey,
+			deviceName: params.deviceName,
+			code,
+			expiresAt: Date.now() + CONTROLLER_PROTOCOL_LIMITS.pairingCodeTtlMaxMs,
+			transport,
+			attempts: 0,
+			used: false
+		};
+		this.pendingByCode.set(code, pending);
+		this.sessions.set(sessionId, pending);
+		return {
+			sessionId,
+			code,
+			expiresAt: new Date(pending.expiresAt).toISOString()
+		};
+	}
+	async approveCode(code, options = {}) {
+		const pending = this.pendingByCode.get(code) ?? (options.sessionId ? this.sessions.get(options.sessionId) : void 0);
+		if (!pending || Date.now() > pending.expiresAt) throw controllerError("CONTROLLER_PAIRING_REJECTED", "The pairing code is unknown or expired");
+		pending.attempts += 1;
+		if (pending.attempts > CONTROLLER_PROTOCOL_LIMITS.pairingAttemptsMax) throw controllerError("CONTROLLER_PAIRING_RATE_LIMITED", "Too many pairing attempts");
+		if (code !== pending.code) throw controllerError("CONTROLLER_PAIRING_REJECTED", "The pairing code does not match this pairing session");
+		if (options.publicKeyOverride !== void 0 && options.publicKeyOverride !== pending.publicKey && !this.options.allowDeviceSubstitution) throw controllerError("CONTROLLER_PAIRING_REJECTED", "The pairing code is bound to a different device public key");
+		if (options.sessionId && options.sessionId !== pending.sessionId && !this.options.allowCrossSessionApproval) throw controllerError("CONTROLLER_PAIRING_REJECTED", "The pairing code belongs to a different session");
+		if (options.authenticated === false && !this.options.allowUnauthenticatedApproval) {
+			await transportNotify(pending.transport, "webskill/pair.rejected", {
+				sessionId: pending.sessionId,
+				code: "Unauthenticated approval"
+			});
+			throw controllerError("CONTROLLER_PAIRING_REJECTED", "Approval requires an authenticated controller session");
+		}
+		if (pending.used && !this.options.allowCodeReuse) throw controllerError("CONTROLLER_PAIRING_REJECTED", "The pairing code has already been used");
+		pending.used = true;
+		pending.approvalNonce = randomToken(18);
+		pending.principal = options.principal ?? "Test User";
+		const principal = pending.principal;
+		const notification = {
+			sessionId: pending.sessionId,
+			approvalNonce: pending.approvalNonce,
+			controllerInstanceId: this.instanceId,
+			...this.options.omitPrincipal ? {} : { principal: { displayName: principal } },
+			capabilities: ["browser"],
+			excludedOrigins: []
+		};
+		await transportNotify(pending.transport, "webskill/pair.approved", notification);
+		return true;
+	}
+	async rejectCode(code) {
+		const pending = this.pendingByCode.get(code);
+		if (!pending) throw controllerError("CONTROLLER_PAIRING_REJECTED", "The pairing code is unknown");
+		pending.used = true;
+		await transportNotify(pending.transport, "webskill/pair.rejected", {
+			sessionId: pending.sessionId,
+			code: "Rejected by user"
+		});
+	}
+	async pairConfirm(params, authorize) {
+		const pending = this.sessions.get(params.sessionId);
+		if (!pending || !pending.approvalNonce) throw controllerError("CONTROLLER_PAIRING_REJECTED", "The pairing session has not been approved");
+		if (!params.accepted) {
+			await transportNotify(pending.transport, "webskill/pair.rejected", {
+				sessionId: pending.sessionId,
+				code: "Rejected by device"
+			});
+			this.notePairingOutcome(pending.sessionId, "rejected");
+			return {};
+		}
+		if (!params.signature) throw controllerError("CONTROLLER_PAIRING_REJECTED", "The device confirmation signature is missing");
+		if (!this.options.skipDeviceSignatureVerification) {
+			if (!await verifyDeviceSignature(pending.publicKey, [
+				"webskill-controller/0.1",
+				"pair.confirm",
+				pending.sessionId,
+				pending.approvalNonce
+			].join("\n"), params.signature)) throw controllerError("CONTROLLER_PAIRING_REJECTED", "The device confirmation signature is invalid");
+		}
+		const expiresAt = Date.now() + CONTROLLER_PROTOCOL_LIMITS.grantTtlMaxMs;
+		const grant = randomToken(32);
+		const device = {
+			sessionId: pending.sessionId,
+			publicKey: pending.publicKey,
+			deviceName: pending.deviceName,
+			principal: pending.principal ?? "Test User",
+			grant,
+			expiresAt,
+			revoked: false
+		};
+		this.grants.set(pending.sessionId, device);
+		authorize(pending.sessionId);
+		this.notePairingOutcome(pending.sessionId, "confirmed");
+		return {
+			grant,
+			expiresAt: new Date(expiresAt).toISOString()
+		};
+	}
+	notePairingOutcome(sessionId, outcome) {
+		this.pairingOutcomes.set(sessionId, outcome);
+		for (const waiter of this.pairingWaiters.get(sessionId) ?? []) {
+			clearTimeout(waiter.timer);
+			waiter.resolve();
+		}
+		this.pairingWaiters.delete(sessionId);
+	}
+	authPresent(params, authorize) {
+		const device = [...this.grants.values()].find((candidate) => candidate.grant === params.grant);
+		if (!device) throw controllerError("CONTROLLER_NOT_PAIRED", "The device grant is unknown");
+		authorize(device.sessionId);
+		if (device.revoked || Date.now() > device.expiresAt) throw controllerError("CONTROLLER_NOT_PAIRED", "The device grant is expired or revoked");
+		return { expiresAt: new Date(device.expiresAt).toISOString() };
+	}
+	authChallenge(sessionId) {
+		if (!sessionId) throw controllerError("CONTROLLER_NOT_PAIRED", "No authorized device session is available");
+		const nonce = randomToken(18);
+		const expiresAt = Date.now() + 6e4;
+		this.nonces.set(nonce, {
+			sessionId,
+			expiresAt
+		});
+		return {
+			nonce,
+			expiresAt: new Date(expiresAt).toISOString()
+		};
+	}
+	async authRenew(params, authorize) {
+		const challenge = this.nonces.get(params.nonce);
+		if (!challenge || Date.now() > challenge.expiresAt) throw controllerError("CONTROLLER_NOT_PAIRED", "The renewal challenge is invalid or expired");
+		const device = this.grants.get(challenge.sessionId);
+		if (!device || device.revoked) throw controllerError("CONTROLLER_NOT_PAIRED", "The device grant is revoked");
+		if (!await verifyDeviceSignature(device.publicKey, [
+			"webskill-controller/0.1",
+			"auth.renew",
+			this.instanceId,
+			params.nonce
+		].join("\n"), params.signature)) throw controllerError("CONTROLLER_NOT_PAIRED", "The renewal signature is invalid");
+		this.nonces.delete(params.nonce);
+		device.grant = randomToken(32);
+		device.expiresAt = Date.now() + CONTROLLER_PROTOCOL_LIMITS.grantTtlMaxMs;
+		this.grants.set(device.sessionId, device);
+		authorize(device.sessionId);
+		return {
+			grant: device.grant,
+			expiresAt: new Date(device.expiresAt).toISOString()
+		};
+	}
+	expireGrants() {
+		for (const device of this.grants.values()) device.expiresAt = Date.now() - 1;
+	}
+	async revokeAll(reason = "Revoked by test") {
+		for (const device of this.grants.values()) device.revoked = true;
+		for (const transport of this.transports) await transportNotify(transport, "webskill/auth.revoked", { reason }).catch(() => void 0);
+	}
+	async stop() {
+		for (const transport of this.transports) await transport.close().catch(() => void 0);
+		this.transports.clear();
+		this.readyResults.clear();
+		for (const waiters of [...this.readyWaiters.values(), ...this.pairingWaiters.values()]) for (const waiter of waiters) clearTimeout(waiter.timer);
+		this.readyWaiters.clear();
+		this.pairingWaiters.clear();
+		const server = this.server;
+		this.server = void 0;
+		if (server) {
+			for (const client of server.clients) client.terminate();
+			await new Promise((resolve) => server.close(() => resolve()));
+		}
+	}
+};
+async function transportNotify(transport, method, params) {
+	await transport.notify(method, params);
+}
+async function verifyDeviceSignature(publicKey, text, signature) {
+	const key = await crypto.subtle.importKey("spki", base64UrlToBytes(publicKey), {
+		name: "ECDSA",
+		namedCurve: "P-256"
+	}, false, ["verify"]);
+	return await crypto.subtle.verify({
+		name: "ECDSA",
+		hash: "SHA-256"
+	}, key, base64UrlToBytes(signature), new TextEncoder().encode(text));
+}
+function randomCode() {
+	const alphabet = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
+	const value = [...crypto.getRandomValues(/* @__PURE__ */ new Uint8Array(8))].map((byte) => alphabet[byte % 32]).join("");
+	return `${value.slice(0, 4)}-${value.slice(4)}`;
+}
+
+//#endregion
+//#region ../controller/src/testing/conformance.ts
+var MemoryStore = class {
+	keyPair;
+	pairing;
+	writeState;
+	async loadKeyPair() {
+		return this.keyPair;
+	}
+	async saveKeyPair(keyPair) {
+		this.keyPair = keyPair;
+	}
+	async loadPairing() {
+		return this.pairing;
+	}
+	async savePairing(record) {
+		this.pairing = record;
+	}
+	async loadWriteState() {
+		return this.writeState;
+	}
+	async saveWriteState(state) {
+		this.writeState = state;
+	}
+	async clear() {
+		this.keyPair = void 0;
+		this.pairing = void 0;
+		this.writeState = void 0;
+	}
+};
+var ToolFixture = class {
+	calls = [];
+	auditEvents = [];
+	authorization = "approve";
+	active = 0;
+	maxActive = 0;
+	count = 0;
+	delayMs = 0;
+	auditDelayMs = 0;
+	failCompletionAudit = false;
+	pairingAccepted = true;
+	largeRead = false;
+	confirmationGate;
+	source(name) {
+		return {
+			kind: "controller-fixture",
+			listToolSpecs: async () => [{
+				name,
+				description: `${name} fixture`,
+				inputSchema: {
+					type: "object",
+					properties: {},
+					additionalProperties: false
+				}
+			}],
+			systemPrompt: async () => `Use ${name} only when it is available.`,
+			canHandle: (candidate) => candidate === name,
+			argCaptureTrust: () => void 0,
+			call: async (tool) => await this.call(tool)
+		};
+	}
+	async call(name) {
+		this.calls.push(name);
+		if (name === "perceive_page" && this.largeRead) return {
+			ok: true,
+			content: [{
+				type: "json",
+				data: { oversized: "x".repeat(CONTROLLER_PROTOCOL_LIMITS.maxMessageBytes) }
+			}]
+		};
+		if (name === "act_on_page" || name === "focus_page_tab" || name === "close_page_tab") {
+			if (this.authorization !== "approve" && this.authorization !== "remember") return {
+				ok: false,
+				content: [],
+				error: {
+					code: "PAGE_ACTION_DECLINED",
+					message: `Authorization ${this.authorization}`,
+					data: { retryable: this.authorization !== "deny" }
+				}
+			};
+			this.active += 1;
+			this.maxActive = Math.max(this.maxActive, this.active);
+			if (this.delayMs > 0) await sleep(this.delayMs);
+			this.count += 1;
+			this.active -= 1;
+		}
+		const result = {
+			ok: true,
+			content: [{
+				type: "json",
+				data: {
+					name,
+					count: this.count
+				}
+			}]
+		};
+		if ([
+			"act_on_page",
+			"focus_page_tab",
+			"close_page_tab"
+		].includes(name)) return Object.assign(result, { authorization: this.authorization === "remember" ? "remembered" : "approved" });
+		return result;
+	}
+};
+var ConformanceRun = class {
+	checks = [];
+	only;
+	known = /* @__PURE__ */ new Set();
+	constructor(only) {
+		this.only = only === void 0 ? void 0 : new Set(only);
+	}
+	async check(id, work) {
+		this.known.add(id);
+		if (this.only && !this.only.has(id)) return;
+		try {
+			await work();
+			this.checks.push({
+				id,
+				passed: true
+			});
+		} catch (error) {
+			this.checks.push({
+				id,
+				passed: false,
+				message: error instanceof Error ? error.message : String(error)
+			});
+		}
+	}
+	skip(id, message) {
+		this.known.add(id);
+		if (this.only && !this.only.has(id)) return;
+		this.checks.push({
+			id,
+			passed: false,
+			skipped: true,
+			message
+		});
+	}
+	report() {
+		for (const id of this.only ?? []) if (!this.known.has(id)) this.checks.push({
+			id: "suite.only",
+			passed: false,
+			message: `Unknown conformance check: ${id}`
+		});
+		return {
+			passed: this.checks.every((check) => check.passed || check.skipped === true),
+			checks: this.checks
+		};
+	}
+};
+function assert(value, message) {
+	if (!value) throw new Error(message);
+}
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function waitFor(work, message, timeoutMs = 1e4) {
+	const start = Date.now();
+	while (!await work()) {
+		if (Date.now() - start > timeoutMs) throw new Error(message);
+		await sleep(10);
+	}
+}
+function mcpCaller(transport, epoch = () => void 0, handlers = {}) {
+	let sequence = 0;
+	let nextInvocationSequence = 0;
+	let sequenceEpoch;
+	const invocationSequences = handlers.sequenceHistory ?? /* @__PURE__ */ new Map();
+	const pending = /* @__PURE__ */ new Map();
+	transport.onmessage = (message) => {
+		if (message.id === void 0) return;
+		const entry = pending.get(message.id);
+		if (!entry) return;
+		pending.delete(message.id);
+		clearTimeout(entry.timeout);
+		if (message.error) {
+			const data = message.error.data;
+			entry.reject(new ControllerRpcError(data?.code ?? "CONTROLLER_MESSAGE_INVALID", message.error.message));
+		} else entry.resolve(message);
+	};
+	const invoke = async (method, params) => {
+		const id = ++sequence;
+		let callParams = params;
+		let writeCall = false;
+		let invocationId;
+		if (method === "tools/call") {
+			const input = params;
+			if ([
+				"act_on_page",
+				"focus_page_tab",
+				"close_page_tab"
+			].includes(input.name)) {
+				writeCall = true;
+				invocationId = String(input._meta?.["webskill/invocationId"] ?? `invocation-${invocationSequences.size + 1}`);
+				const callTool = async (tool, args) => {
+					return (await invoke("tools/call", {
+						name: tool,
+						arguments: args,
+						_meta: { "webskill/invocationId": `prepare-${invocationId}` }
+					})).result ?? {};
+				};
+				const args = await handlers.toolArguments?.(input.name, invocationId, callTool);
+				const suppliedSequence = input._meta?.["webskill/sequence"];
+				const knownSequence = invocationSequences.get(invocationId);
+				const suppliedEpoch = input._meta?.["webskill/deviceEpoch"];
+				const deviceEpoch = typeof suppliedEpoch === "string" ? suppliedEpoch : epoch();
+				if (!deviceEpoch) throw new Error("No paired device epoch is available");
+				if (suppliedSequence === void 0 && knownSequence === void 0 && sequenceEpoch !== deviceEpoch) {
+					const data = (await invoke("tools/call", {
+						name: "browser_status",
+						arguments: {},
+						_meta: { "webskill/invocationId": `status-${invocationId}` }
+					})).result?.structuredContent;
+					assert(data?.["deviceEpoch"] === deviceEpoch, "The device epoch changed while restoring the sequence allocator");
+					assert(data?.["writeStateRecoverable"] === true, "The device write state is not recoverable; pair the device again");
+					const watermark = data["writeHighWatermark"];
+					assert(typeof watermark === "number" && Number.isSafeInteger(watermark) && watermark >= 0, "The device returned an invalid write watermark");
+					nextInvocationSequence = watermark;
+					sequenceEpoch = deviceEpoch;
+				}
+				if (invocationId) await handlers.beforeWriteCall?.(invocationId);
+				const invocationSequence = typeof suppliedSequence === "number" ? suppliedSequence : knownSequence ?? ++nextInvocationSequence;
+				if (suppliedSequence === void 0) nextInvocationSequence = Math.max(nextInvocationSequence, invocationSequence);
+				invocationSequences.set(invocationId, invocationSequence);
+				callParams = {
+					...input,
+					...args === void 0 ? {} : { arguments: args },
+					_meta: {
+						...input._meta,
+						"webskill/invocationId": invocationId,
+						"webskill/deviceEpoch": deviceEpoch,
+						"webskill/sequence": invocationSequence
+					}
+				};
+			}
+		}
+		const result = new Promise((resolve, reject) => {
+			const timeout = setTimeout(() => {
+				pending.delete(id);
+				reject(/* @__PURE__ */ new Error(`MCP response timed out: ${method}`));
+			}, 1e4);
+			pending.set(id, {
+				resolve,
+				reject,
+				timeout
+			});
+		});
+		try {
+			await transport.send({
+				jsonrpc: "2.0",
+				id,
+				method,
+				params: callParams
+			});
+		} catch (error) {
+			const entry = pending.get(id);
+			if (entry) clearTimeout(entry.timeout);
+			pending.delete(id);
+			throw error;
+		}
+		if (writeCall && handlers.onWriteCall) {
+			await Promise.all([result, handlers.onWriteCall(result)]);
+			return await result;
+		}
+		return await result;
+	};
+	return invoke;
+}
+function makeDevice(url, store, fixtures, fixture, audit) {
+	return createControllerDevice({
+		url,
+		deviceName: fixtures.deviceName ?? "Conformance Device",
+		hostVersion: fixtures.hostVersion ?? "0.0.0",
+		store,
+		tools: CONTROLLER_TOOL_NAMES.filter((name) => name !== "browser_status").map((name) => fixture.source(name)),
+		confirmPairing: async () => {
+			const accepted = fixture.pairingAccepted;
+			await fixtures.confirmPairing?.(accepted);
+			await fixture.confirmationGate;
+			return accepted;
+		},
+		audit: async (event) => {
+			if (event.data["invocationId"] === "order-a" && event.data["phase"] === "started" && fixture.auditDelayMs > 0) await sleep(fixture.auditDelayMs);
+			if (fixture.failCompletionAudit && event.type === "controller.call" && event.data["invocationId"] === "incomplete-audit" && event.data["phase"] === void 0) throw new Error("Injected completion audit failure");
+			fixture.auditEvents.push(event);
+			audit?.(event);
+		},
+		onError: () => void 0
+	});
+}
+async function pairDevice(device, controller, fixtures, accepted, external = false) {
+	await device.connect();
+	const pairing = external ? await fixtures.startPairing() : await device.startPairing();
+	await controller.approveCode(pairing.code, { principal: fixtures.principal ?? "Conformance User" });
+	if (accepted) {
+		if (external) await fixtures.confirmPairing?.(true);
+		await controller.waitForReady(pairing.sessionId);
+	} else await controller.waitForPairingOutcome(pairing.sessionId, "rejected");
+	return pairing;
+}
+/** @experimental */
+async function runControllerConformance(options) {
+	const run = new ConformanceRun(options.only);
+	if (options.role === "controller") await runControllerRole(run, options);
+	else await runDeviceRole(run, options);
+	return run.report();
+}
+async function runControllerRole(run, options) {
+	const fixtures = options.fixtures ?? {};
+	const external = options.device !== void 0;
+	if (external) {
+		const missing = [
+			"startPairing",
+			"confirmPairing",
+			"setHumanInControl",
+			"resolveAuthorization",
+			"toolArguments",
+			"pageCounter",
+			"maxActiveWrites",
+			"setWriteDelayMs",
+			"setOversizeRead",
+			"interruptConnection",
+			"hasPairingRecord",
+			"auditEvents",
+			"setAuditDelayMs",
+			"failCompletionAudit",
+			"auditWarning",
+			"userError",
+			"prepareAuthorization"
+		].filter((key) => fixtures[key] === void 0);
+		if (missing.length > 0) {
+			run.known.add("suite.device-fixtures");
+			for (const id of options.only ?? []) run.known.add(id);
+			run.checks.push({
+				id: "suite.device-fixtures",
+				passed: false,
+				message: `External device fixtures are required: ${missing.join(", ")}`
+			});
+			return;
+		}
+	}
+	let controller = new ReferenceController(options.url, options.controllerOptions);
+	await controller.start();
+	const store = new MemoryStore();
+	const fixture = new ToolFixture();
+	let releaseRejectedConfirmation;
+	fixture.confirmationGate = new Promise((resolve) => {
+		releaseRejectedConfirmation = resolve;
+	});
+	let device = options.device ?? makeDevice(options.url, store, fixtures, fixture);
+	const epoch = () => external ? controller.grantedDevices.at(-1)?.sessionId : store.pairing?.sessionId;
+	const sequenceHistory = /* @__PURE__ */ new Map();
+	const makeCaller = () => {
+		if (external) {
+			assert(fixtures.toolArguments, "An external device requires real tool arguments");
+			assert(fixtures.resolveAuthorization, "An external device requires a real authorization driver");
+		}
+		return mcpCaller(controller.mcpTransport(), epoch, {
+			sequenceHistory,
+			...external ? { toolArguments: fixtures.toolArguments } : {},
+			...external && fixtures.prepareAuthorization ? { beforeWriteCall: async () => await fixtures.prepareAuthorization(fixture.authorization) } : {},
+			...external && fixtures.resolveAuthorization ? { onWriteCall: async (settled) => await fixtures.resolveAuthorization(fixture.authorization, settled) } : {}
+		});
+	};
+	const writeCount = async () => await fixtures.pageCounter?.() ?? fixture.count;
+	let transport;
+	try {
+		await run.check("handshake.unsupported-version", async () => {
+			transport = createWebSocketControllerTransport({ url: options.url });
+			let rejected;
+			try {
+				await transport.request("webskill/hello", {
+					protocolVersions: ["99.99"],
+					hostName: "Unsupported",
+					hostVersion: "0"
+				}, 3e3);
+			} catch (error) {
+				rejected = error;
+			}
+			assert(rejected instanceof ControllerRpcError && rejected.code === "CONTROLLER_PROTOCOL_UNSUPPORTED", "Unsupported protocol was not rejected");
+			await transport.close();
+		});
+		await run.check("handshake.version-negotiation", async () => {
+			await device.connect();
+			assert(controller.grantedDevices.length === 0, "Handshake unexpectedly created a device grant");
+		});
+		await run.check("auth.mcp-before-pairing", async () => {
+			await fixtures.breakMcpGate?.(device);
+			const caller = mcpCaller(controller.deviceTransport());
+			let rejected;
+			try {
+				await caller("tools/list");
+			} catch (error) {
+				rejected = error;
+			}
+			assert(rejected instanceof ControllerRpcError && rejected.code === "CONTROLLER_NOT_PAIRED", "MCP was available before pairing");
+		});
+		await run.check("pairing.device-confirmation-required", async () => {
+			const code = external ? await fixtures.startPairing() : await device.startPairing();
+			fixture.pairingAccepted = false;
+			await controller.approveCode(code.code, { principal: "Rejected User" });
+			assert(controller.grantedDevices.length === 0, "A grant was issued before device confirmation");
+			if (external) await fixtures.confirmPairing?.(false);
+			releaseRejectedConfirmation?.();
+			await controller.waitForPairingOutcome(code.sessionId, "rejected");
+			await device.unpair();
+		});
+		await run.check("pairing.grant-after-confirmation", async () => {
+			fixture.pairingAccepted = true;
+			fixture.confirmationGate = void 0;
+			if (!external) device = makeDevice(options.url, store, fixtures, fixture);
+			await pairDevice(device, controller, fixtures, true, external);
+			if (external) assert(controller.grantedDevices.length === 1, "No grant was issued after external device confirmation");
+			else assert(store.pairing?.grant, "No grant was stored after confirmation");
+		});
+		await run.check("protocol.ready-and-watermark", async () => {
+			const deviceEpoch = epoch();
+			assert(deviceEpoch, "No paired device epoch is available");
+			const ready = await controller.waitForReady(deviceEpoch);
+			assert(ready.deviceEpoch === deviceEpoch && ready.writeHighWatermark === 0 && ready.writeStateRecoverable === true, "Ready notification did not describe a new recoverable epoch");
+			assert(ready.hostVersion.length > 0, "Ready notification omitted the host version");
+			const statusCaller = makeCaller();
+			await statusCaller("initialize", {
+				protocolVersion: "2025-11-25",
+				capabilities: {},
+				clientInfo: {
+					name: "blackbox-ready",
+					version: "0"
+				}
+			});
+			const data = (await statusCaller("tools/call", {
+				name: "browser_status",
+				arguments: {},
+				_meta: { "webskill/invocationId": "blackbox-status" }
+			})).result?.structuredContent;
+			assert(data?.["deviceEpoch"] === deviceEpoch && data["writeHighWatermark"] === ready.writeHighWatermark && data["writeStateRecoverable"] === true, "browser_status does not agree with the ready notification");
+		});
+		let caller;
+		await run.check("tools.list-exact", async () => {
+			caller = makeCaller();
+			assert((await caller("initialize", {
+				protocolVersion: "2025-11-25",
+				capabilities: {},
+				clientInfo: {
+					name: "conformance",
+					version: "0"
+				}
+			})).result, "MCP initialize did not return a result");
+			const tools = (await caller("tools/list")).result.tools;
+			assert(tools.length === CONTROLLER_TOOL_NAMES.length, `Expected ${CONTROLLER_TOOL_NAMES.length} tools, got ${tools.length}`);
+			assert(tools.every((tool) => CONTROLLER_TOOL_NAMES.includes(tool.name)), "Unexpected controller tool");
+		});
+		await run.check("tools.names-in-text", async () => {
+			assert(caller, "MCP caller is unavailable");
+			const tools = (await caller("tools/list")).result.tools;
+			const names = new Set(tools.map((tool) => tool.name));
+			for (const tool of tools) for (const name of CONTROLLER_TOOL_NAMES) if (tool.description?.includes(name)) assert(names.has(name), `${name} is referenced but unavailable`);
+		});
+		await run.check("message.invalid-kept-alive", async () => {
+			assert(caller, "MCP caller is unavailable");
+			await controller.mcpTransport().send({
+				jsonrpc: "2.0",
+				id: "invalid-control",
+				method: "webskill/ping",
+				params: { unexpected: true }
+			});
+			assert((await caller("tools/call", {
+				name: "browser_status",
+				arguments: {},
+				_meta: { "webskill/invocationId": "still-alive" }
+			})).result, "An invalid control message closed the connection");
+		});
+		await run.check("error.envelope", async () => {
+			assert(caller, "MCP caller is unavailable");
+			let rejected;
+			try {
+				await caller("tools/call", {
+					name: "not_available",
+					arguments: {},
+					_meta: { "webskill/invocationId": "missing-tool" }
+				});
+			} catch (error) {
+				rejected = error;
+			}
+			assert(rejected instanceof ControllerRpcError && rejected.code === "CONTROLLER_CAPABILITY_MISSING", "Missing tool did not return the protocol error envelope");
+			if (external) assert(await fixtures.userError?.() === void 0, "A rejected controller request was surfaced as a device fault");
+		});
+		await run.check("message.oversize-result", async () => {
+			assert(caller, "MCP caller is unavailable");
+			fixture.largeRead = true;
+			if (external) await fixtures.setOversizeRead?.(true);
+			try {
+				const result = await caller("tools/call", {
+					name: "perceive_page",
+					arguments: {},
+					_meta: { "webskill/invocationId": "oversized-result" }
+				});
+				const error = result.result?._meta?.["webskill/error"];
+				assert(error?.code === "CONTROLLER_MESSAGE_INVALID", `Oversized tool result was not converted to a structured error: ${JSON.stringify(result.result?._meta ?? result.error ?? {})}`);
+			} finally {
+				fixture.largeRead = false;
+				if (external) await fixtures.setOversizeRead?.(false);
+			}
+		});
+		await run.check("call.write-idempotent", async () => {
+			assert(caller, "MCP caller is unavailable");
+			const params = {
+				name: "act_on_page",
+				arguments: {},
+				_meta: { "webskill/invocationId": "write-once" }
+			};
+			await caller("tools/call", params);
+			await caller("tools/call", params);
+			assert(await writeCount() === 1, `Write executed ${await writeCount()} times instead of once`);
+		});
+		await run.check("call.write-serialized", async () => {
+			assert(caller, "MCP caller is unavailable");
+			fixture.delayMs = 50;
+			if (external) await fixtures.setWriteDelayMs?.(50);
+			try {
+				await Promise.all([caller("tools/call", {
+					name: "act_on_page",
+					arguments: {},
+					_meta: { "webskill/invocationId": "serial-a" }
+				}), caller("tools/call", {
+					name: "act_on_page",
+					arguments: {},
+					_meta: { "webskill/invocationId": "serial-b" }
+				})]);
+				const maxActive = external ? await fixtures.maxActiveWrites?.() : fixture.maxActive;
+				assert(maxActive === 1, `Writes overlapped: maxActive=${maxActive}`);
+			} finally {
+				fixture.delayMs = 0;
+				if (external) await fixtures.setWriteDelayMs?.(0);
+			}
+		});
+		await run.check("call.transient-retry-new-id", async () => {
+			assert(caller, "MCP caller is unavailable");
+			fixture.authorization = "timeout";
+			const before = await writeCount();
+			const params = {
+				name: "act_on_page",
+				arguments: {},
+				_meta: { "webskill/invocationId": "transient-a" }
+			};
+			const first = await caller("tools/call", params);
+			const repeated = await caller("tools/call", params);
+			assert(first.result?.isError === true && repeated.result?.isError === true, "Transient authorization failure was not returned");
+			assert(await writeCount() === before, "Same ID retry executed a new write");
+			fixture.authorization = "approve";
+			await caller("tools/call", {
+				...params,
+				_meta: { "webskill/invocationId": "transient-b" }
+			});
+			assert(await writeCount() === before + 1, "New ID did not execute a new authorized attempt");
+		});
+		await run.check("call.authorization-declined", async () => {
+			assert(caller, "MCP caller is unavailable");
+			fixture.authorization = "deny";
+			const before = await writeCount();
+			const failure = (await caller("tools/call", {
+				name: "act_on_page",
+				arguments: {},
+				_meta: { "webskill/invocationId": "declined-write" }
+			})).result?._meta?.["webskill/error"];
+			assert(failure?.code === "PAGE_ACTION_DECLINED" && failure.retryable === false, "Declined authorization did not return a non-retryable error");
+			assert(await writeCount() === before, "A declined write executed on the page");
+			fixture.authorization = "approve";
+		});
+		await run.check("call.audit-authorization", async () => {
+			assert(caller, "MCP caller is unavailable");
+			await caller("tools/call", {
+				name: "act_on_page",
+				arguments: {},
+				_meta: {
+					"webskill/invocationId": "audit-write",
+					"webskill/context": { originInvocationId: "audit-parent" }
+				}
+			});
+			assert((await fixtures.auditEvents?.() ?? fixture.auditEvents).some((event) => event.type === "controller.call" && event.data["invocationId"] === "audit-write" && event.data["authorization"] === "approved" && JSON.stringify(event.data["context"]) === JSON.stringify({ originInvocationId: "audit-parent" })), "The controller audit did not correlate the invocation, local authorization source and context");
+		});
+		await run.check("call.admission-order", async () => {
+			assert(caller, "MCP caller is unavailable");
+			const before = await writeCount();
+			fixture.auditDelayMs = 30;
+			if (external) await fixtures.setAuditDelayMs?.(30);
+			try {
+				const responses = await Promise.all([caller("tools/call", {
+					name: "act_on_page",
+					arguments: {},
+					_meta: { "webskill/invocationId": "order-a" }
+				}), caller("tools/call", {
+					name: "act_on_page",
+					arguments: {},
+					_meta: { "webskill/invocationId": "order-b" }
+				})]);
+				for (const response of responses) assert(response.result?.isError !== true, `Adjacent write was rejected: ${JSON.stringify(response.error ?? response.result?._meta ?? {})}`);
+				assert(await writeCount() === before + 2, "An asynchronous audit wait reordered adjacent write admission");
+			} finally {
+				fixture.auditDelayMs = 0;
+				if (external) await fixtures.setAuditDelayMs?.(0);
+			}
+		});
+		await run.check("call.watermark-resync", async () => {
+			assert(caller, "MCP caller is unavailable");
+			const before = await writeCount();
+			caller = makeCaller();
+			await caller("initialize", {
+				protocolVersion: "2025-11-25",
+				capabilities: {},
+				clientInfo: {
+					name: "resumed-controller",
+					version: "0"
+				}
+			});
+			await caller("tools/call", {
+				name: "act_on_page",
+				arguments: {},
+				_meta: { "webskill/invocationId": "resumed-write" }
+			});
+			assert(await writeCount() === before + 1, "A restarted controller could not resume from the device watermark");
+		});
+		await run.check("call.forward-window-invalid", async () => {
+			assert(caller, "MCP caller is unavailable");
+			const before = await writeCount();
+			let rejected;
+			try {
+				await caller("tools/call", {
+					name: "act_on_page",
+					arguments: {},
+					_meta: {
+						"webskill/invocationId": "forward-window",
+						"webskill/sequence": Number.MAX_SAFE_INTEGER - 1
+					}
+				});
+			} catch (error) {
+				rejected = error;
+			}
+			assert(rejected instanceof ControllerRpcError && rejected.code === "CONTROLLER_MESSAGE_INVALID", "A forward-window violation was not rejected as an invalid message");
+			assert(await writeCount() === before, "A forward-window violation executed a write");
+		});
+		await run.check("call.audit-incomplete", async () => {
+			assert(caller, "MCP caller is unavailable");
+			const before = await writeCount();
+			fixture.failCompletionAudit = true;
+			if (external) await fixtures.failCompletionAudit?.(true);
+			const params = {
+				name: "act_on_page",
+				arguments: {},
+				_meta: { "webskill/invocationId": "incomplete-audit" }
+			};
+			try {
+				const first = await caller("tools/call", params);
+				const repeated = await caller("tools/call", params);
+				for (const response of [first, repeated]) {
+					const result = response.result;
+					assert(result?.isError !== true && result?._meta?.["webskill/auditIncomplete"] === true, "Post-execution audit failure did not preserve the real result");
+				}
+				assert(await writeCount() === before + 1, "An audit failure caused the write to execute more than once");
+				if (external) {
+					assert(await fixtures.auditWarning?.(), "The host did not expose the incomplete audit warning");
+					fixture.failCompletionAudit = false;
+					await fixtures.failCompletionAudit?.(false);
+					assert((await caller("tools/call", {
+						name: "browser_status",
+						arguments: {},
+						_meta: { "webskill/invocationId": "after-audit-recovery" }
+					})).result, "The audit recovery call did not succeed");
+					assert(await fixtures.auditWarning?.(), "A later successful audit cleared the warning without acknowledgement");
+				}
+			} finally {
+				fixture.failCompletionAudit = false;
+				if (external) await fixtures.failCompletionAudit?.(false);
+			}
+		});
+		if (!external) run.skip("control.human-cancels-authorization", "A real host authorization UI is required to verify takeover cancellation");
+		else await run.check("control.human-cancels-authorization", async () => {
+			assert(caller, "MCP caller is unavailable");
+			const before = await writeCount();
+			fixture.authorization = "takeover";
+			try {
+				const failure = (await caller("tools/call", {
+					name: "act_on_page",
+					arguments: {},
+					_meta: { "webskill/invocationId": "takeover-write" }
+				})).result?._meta?.["webskill/error"];
+				assert(failure?.code === "CONTROLLER_HUMAN_IN_CONTROL", "A pending authorization was not cancelled by human takeover");
+				assert(await writeCount() === before, "A cancelled authorization executed a page write");
+			} finally {
+				fixture.authorization = "approve";
+				await fixtures.setHumanInControl?.(false);
+			}
+		});
+		await run.check("call.write-evicted", async () => {
+			assert(caller, "MCP caller is unavailable");
+			fixture.authorization = "remember";
+			try {
+				for (let index = 0; index <= CONTROLLER_PROTOCOL_LIMITS.idempotencyCacheEntries; index++) {
+					if (external && index % 16 === 0) console.error(`Controller eviction progress: ${index}`);
+					await caller("tools/call", {
+						name: "act_on_page",
+						arguments: {},
+						_meta: { "webskill/invocationId": `evict-${index}` }
+					});
+					if (index === 1) assert((await fixtures.auditEvents?.() ?? fixture.auditEvents).some((event) => event.data["invocationId"] === "evict-1" && event.data["authorization"] === "remembered"), "The eviction scenario did not obtain remembered authorization through the real consent path");
+				}
+			} finally {
+				fixture.authorization = "approve";
+			}
+			const result = await caller("tools/call", {
+				name: "act_on_page",
+				arguments: {},
+				_meta: { "webskill/invocationId": "write-once" }
+			});
+			const error = result.result?._meta?.["webskill/error"];
+			const payload = result.result;
+			assert(error?.code === "CONTROLLER_INVOCATION_DUPLICATE", `An evicted invocation returned an unexpected result: ${JSON.stringify({
+				rpcError: result.error,
+				isError: payload?.isError,
+				meta: payload?._meta,
+				data: payload?.structuredContent
+			})}`);
+		});
+		await run.check("control.human-in-control", async () => {
+			if (external) await fixtures.setHumanInControl?.(true);
+			else device.setHumanInControl(true);
+			assert(caller, "MCP caller is unavailable");
+			const error = ((await caller("tools/call", {
+				name: "perceive_page",
+				arguments: {},
+				_meta: { "webskill/invocationId": "human-read" }
+			})).result?._meta)?.["webskill/error"];
+			assert(error?.code === "CONTROLLER_HUMAN_IN_CONTROL", "Human-control call was not rejected");
+			if (external) await fixtures.setHumanInControl?.(false);
+			else device.setHumanInControl(false);
+		});
+		await run.check("auth.renew-signature", async () => {
+			const previous = external ? controller.grantedDevices[0]?.grant : store.pairing?.grant;
+			assert(previous, "No grant available for renewal");
+			if (!external && store.pairing) store.pairing = {
+				...store.pairing,
+				grantExpiresAt: (/* @__PURE__ */ new Date(Date.now() - 1)).toISOString()
+			};
+			controller.expireGrants();
+			await device.disconnect();
+			await device.connect();
+			const renewed = external ? controller.grantedDevices[0]?.grant : store.pairing?.grant;
+			assert(renewed && renewed !== previous, "Grant was not renewed with a device signature");
+		});
+		await run.check("auth.reconnect-after-disconnect", async () => {
+			const sessionId = epoch();
+			assert(sessionId, "No paired epoch is available for reconnect");
+			if (external) await fixtures.interruptConnection?.();
+			else await deviceTransport(device).close(3001, "Test reconnect");
+			await waitFor(() => controller.connectionCount === 0, "The old device transport did not close");
+			await controller.waitForReady(sessionId);
+			caller = makeCaller();
+			await caller("initialize", {
+				protocolVersion: "2025-11-25",
+				capabilities: {},
+				clientInfo: {
+					name: "reconnect",
+					version: "0"
+				}
+			});
+			assert((await caller("tools/call", {
+				name: "browser_status",
+				arguments: {},
+				_meta: { "webskill/invocationId": "reconnected-call" }
+			})).result, "MCP was not restored on the new transport");
+			if (external) assert(await fixtures.auditWarning?.(), "Automatic reconnect cleared the audit warning");
+		});
+		await run.check("auth.revoke", async () => {
+			await controller.revokeAll();
+			if (external) {
+				await waitFor(async () => !await fixtures.hasPairingRecord?.(), "Revoked external pairing record was not cleared");
+				assert(await fixtures.auditWarning?.(), "Controller-initiated revocation cleared the audit warning");
+			} else {
+				await waitFor(() => !store.pairing, "Revoked pairing record was not cleared");
+				assert(!store.writeState, "Revoked write state was not cleared");
+			}
+		});
+		await run.check("message.oversize-closes", async () => {
+			const socket = new WebSocket(options.url);
+			await new Promise((resolve) => socket.addEventListener("open", () => resolve(), { once: true }));
+			const payload = JSON.stringify({
+				jsonrpc: "2.0",
+				id: "oversize",
+				method: "webskill/ping",
+				params: { value: "x".repeat(17 * 1024 * 1024) }
+			});
+			for (let index = 0; index < 3; index++) socket.send(payload);
+			const code = await new Promise((resolve) => socket.addEventListener("close", (event) => resolve(event.code), { once: true }));
+			assert(code === 1009, `Expected oversize close code 1009, got ${code}`);
+		});
+		await run.check("auth.instance-mismatch", async () => {
+			if (external) await pairDevice(device, controller, fixtures, true, true);
+			await device.disconnect();
+			if (!external) {
+				store.pairing = {
+					controllerUrl: options.url,
+					controllerInstanceId: "previous-controller-instance",
+					controllerName: "Previous Controller",
+					principalDisplayName: "Previous User",
+					sessionId: "previous-session",
+					grant: "not-used-before-instance-check",
+					grantExpiresAt: new Date(Date.now() + 6e4).toISOString(),
+					declaredOrigins: [],
+					pairedAt: (/* @__PURE__ */ new Date()).toISOString()
+				};
+				device = makeDevice(options.url, store, fixtures, fixture);
+			}
+			await controller.stop();
+			controller = new ReferenceController(options.url, {
+				...options.controllerOptions,
+				instanceId: "different-controller-instance"
+			});
+			await controller.start();
+			let failed = false;
+			try {
+				await device.connect();
+			} catch {
+				failed = true;
+			}
+			assert(failed, "A changed controller instance did not fail closed");
+		});
+	} finally {
+		await device.disconnect().catch(() => void 0);
+		await controller.stop();
+	}
+}
+async function runDeviceRole(run, options) {
+	const fixtures = options.fixtures ?? {};
+	const store = new MemoryStore();
+	const fixture = new ToolFixture();
+	let releaseConfirmation;
+	fixture.confirmationGate = new Promise((resolve) => {
+		releaseConfirmation = resolve;
+	});
+	const device = makeDevice(options.url, store, fixtures, fixture);
+	const freshPairing = async (attack) => {
+		const probeStore = new MemoryStore();
+		const probe = makeDevice(options.url, probeStore, fixtures, new ToolFixture());
+		try {
+			await probe.connect();
+			await attack(await probe.startPairing());
+			return false;
+		} catch {
+			return true;
+		} finally {
+			await probe.disconnect().catch(() => void 0);
+		}
+	};
+	try {
+		let pairing;
+		await run.check("handshake.version-negotiation", async () => {
+			await device.connect();
+			assert(device.state === "unpaired", `Expected unpaired, got ${device.state}`);
+			pairing = await device.startPairing();
+			assert(pairing.code, "Pairing code was not issued");
+		});
+		await run.check("pairing.approval-identity", async () => {
+			assert(pairing, "Pairing was not started");
+			await fixtures.approve?.({
+				code: pairing.code,
+				principal: fixtures.principal ?? "Conformance User"
+			});
+			await waitFor(() => device.state === "awaiting-confirmation", "Approval identity was not delivered");
+		});
+		await run.check("pairing.device-confirmation-required", async () => {
+			assert(device.state === "awaiting-confirmation", "Device confirmation did not remain pending");
+			assert(store.pairing === void 0, "Grant existed before device confirmation");
+		});
+		await run.check("pairing.grant-after-confirmation", async () => {
+			releaseConfirmation?.();
+			await waitFor(() => device.state === "ready", "Grant was not issued after device confirmation");
+			assert(store.pairing?.grant, "Grant was not persisted");
+		});
+		await run.check("pairing.code-bound-to-session", async () => {
+			assert(await freshPairing(async (code) => {
+				await fixtures.approve?.({
+					code: code.code,
+					sessionId: "wrong-session",
+					principal: "Wrong Session User"
+				});
+			}), "A pairing code was accepted across sessions");
+		});
+		await run.check("pairing.code-bound-to-key", async () => {
+			assert(await freshPairing(async (code) => {
+				await fixtures.substituteDeviceKey?.(code.code);
+			}), "A pairing code was accepted with a substituted device key");
+		});
+		await run.check("pairing.attempt-limit", async () => {
+			assert(pairing, "Pairing was not started");
+			let limited = false;
+			try {
+				for (let index = 0; index < 8; index++) await fixtures.attemptInvalidCode?.(pairing.sessionId);
+			} catch {
+				limited = true;
+			}
+			assert(limited, "Repeated invalid pairing attempts were not limited");
+		});
+		await run.check("pairing.code-single-use", async () => {
+			assert(pairing, "Pairing was not started");
+			let rejected = false;
+			try {
+				await fixtures.approve?.({
+					code: pairing.code,
+					principal: "Reuse User"
+				});
+			} catch {
+				rejected = true;
+			}
+			assert(rejected, "A pairing code was accepted twice");
+		});
+		await run.check("pairing.unauthenticated-approval-refused", async () => {
+			assert(await freshPairing(async (code) => {
+				await fixtures.approveUnauthenticated?.({
+					code: code.code,
+					sessionId: code.sessionId
+				});
+			}), "Unauthenticated approval was not rejected");
+		});
+	} finally {
+		releaseConfirmation?.();
+		await device.disconnect().catch(() => void 0);
+	}
+}
+function deviceTransport(device) {
+	const transport = device.transport;
+	if (!transport) throw new Error("Device transport is not connected");
+	return transport;
+}
+
+//#endregion
+export { InMemoryStore, MemoryArtifactStore, MockLlmClient, MockUiBridge, loadAnthropicConfigFromEnv, loadGoogleConfigFromEnv, loadLlmConfigFromEnv, runControllerConformance };