@webskill/sdk 0.28.1 → 0.30.0-next.1

package/dist/device-DMUgqNzr.js

@@ -0,0 +1,1782 @@
+import { t as WebSkillError } from "./errors-BDZNpC13.js";
+import { l as PERCEIVE_PAGE_TOOL, n as FOCUS_PAGE_TAB_TOOL, o as PAGE_ACTION_TOOL, r as LIST_PAGE_TABS_TOOL, t as CLOSE_PAGE_TAB_TOOL } from "./toolSource-DMCTnSVg.js";
+import { Validator } from "@cfworker/json-schema";
+
+//#region ../controller/src/constants.ts
+/** @stable */
+const CONTROLLER_PROTOCOL_VERSION = "0.1";
+/** @experimental */
+const CONTROLLER_TOOL_NAMES = [
+	"browser_status",
+	PERCEIVE_PAGE_TOOL,
+	PAGE_ACTION_TOOL,
+	LIST_PAGE_TABS_TOOL,
+	FOCUS_PAGE_TAB_TOOL,
+	CLOSE_PAGE_TAB_TOOL
+];
+/** @experimental */
+const CONTROLLER_PROTOCOL_LIMITS = {
+	maxMessageBytes: 16 * 1024 * 1024,
+	oversizeWindowMs: 6e4,
+	oversizeThreshold: 3,
+	invocationContextMaxBytes: 4096,
+	pairingCodeTtlMaxMs: 6e5,
+	pairingAttemptsMax: 5,
+	deviceConfirmTimeoutMs: 12e4,
+	grantTtlMaxMs: 36e5,
+	heartbeatIntervalMs: 2e4,
+	heartbeatTimeoutMs: 45e3,
+	reconnectMaxDelayMs: 3e4,
+	localAuthorizationTimeoutMs: 12e4,
+	idempotencyCacheEntries: 256,
+	idempotencyCacheTtlMs: 6e5
+};
+const CONTROLLER_JSONRPC_CODES = {
+	CONTROLLER_MESSAGE_INVALID: -32602,
+	CONTROLLER_CAPABILITY_MISSING: -32602,
+	CONTROLLER_NOT_PAIRED: -32001,
+	CONTROLLER_PROTOCOL_UNSUPPORTED: -32002,
+	CONTROLLER_PAIRING_REJECTED: -32003,
+	CONTROLLER_PAIRING_RATE_LIMITED: -32004,
+	CONTROLLER_HUMAN_IN_CONTROL: -32e3,
+	CONTROLLER_INVOCATION_DUPLICATE: -32005
+};
+/** @experimental */
+const CONTROLLER_ERROR_RETRYABLE = {
+	CONTROLLER_PROTOCOL_UNSUPPORTED: false,
+	CONTROLLER_MESSAGE_INVALID: false,
+	CONTROLLER_NOT_PAIRED: false,
+	CONTROLLER_PAIRING_REJECTED: false,
+	CONTROLLER_PAIRING_RATE_LIMITED: true,
+	CONTROLLER_CAPABILITY_MISSING: false,
+	CONTROLLER_HUMAN_IN_CONTROL: true,
+	CONTROLLER_INVOCATION_DUPLICATE: false
+};
+const CONTROLLER_WRITE_TOOLS = [
+	PAGE_ACTION_TOOL,
+	FOCUS_PAGE_TAB_TOOL,
+	CLOSE_PAGE_TAB_TOOL
+];
+
+//#endregion
+//#region ../controller/src/errors.ts
+var ControllerRpcError = class extends Error {
+	code;
+	retryable;
+	constructor(code, message) {
+		super(message);
+		this.name = "ControllerRpcError";
+		this.code = code;
+		this.retryable = CONTROLLER_ERROR_RETRYABLE[code];
+	}
+};
+function controllerError(code, message) {
+	return new ControllerRpcError(code, message);
+}
+function asControllerRpcError(error) {
+	if (error instanceof ControllerRpcError) return error;
+	if (error instanceof WebSkillError && error.code.startsWith("CONTROLLER_")) return new ControllerRpcError(error.code, error.message);
+	return new ControllerRpcError("CONTROLLER_MESSAGE_INVALID", error instanceof Error ? error.message : String(error));
+}
+function toJsonRpcError(error) {
+	const normalized = asControllerRpcError(error);
+	return {
+		code: CONTROLLER_JSONRPC_CODES[normalized.code],
+		message: normalized.message,
+		data: {
+			code: normalized.code,
+			retryable: normalized.retryable
+		}
+	};
+}
+
+//#endregion
+//#region ../controller/src/jsonRpc.ts
+function byteLength(value) {
+	return new TextEncoder().encode(value).byteLength;
+}
+function isJsonRpcObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value) && value.jsonrpc === "2.0";
+}
+
+//#endregion
+//#region ../controller/schema/protocol.schema.json
+var protocol_schema_default = {
+	$schema: "https://json-schema.org/draft/2020-12/schema",
+	$id: "https://webskill.dev/schema/controller/0.1/protocol.schema.json",
+	title: "Protocol",
+	type: "object",
+	$defs: {
+		"ProtocolVersion": {
+			"title": "ProtocolVersion",
+			"type": "string",
+			"pattern": "^[0-9]+\\.[0-9]+$",
+			"maxLength": 16
+		},
+		"IsoDateTime": {
+			"title": "IsoDateTime",
+			"type": "string",
+			"format": "date-time",
+			"maxLength": 40
+		},
+		"Base64Url": {
+			"title": "Base64Url",
+			"type": "string",
+			"pattern": "^[A-Za-z0-9_-]*$",
+			"maxLength": 8192
+		},
+		"Origin": {
+			"title": "Origin",
+			"type": "string",
+			"pattern": "^https?://[^/]+$",
+			"maxLength": 2048
+		},
+		"BoundedString": {
+			"title": "BoundedString",
+			"type": "string",
+			"maxLength": 4096
+		},
+		"InvocationMeta": {
+			"title": "InvocationMeta",
+			"type": "object",
+			"required": ["webskill/invocationId"],
+			"properties": {
+				"webskill/invocationId": {
+					"type": "string",
+					"pattern": "^[A-Za-z0-9._:-]{1,128}$"
+				},
+				"webskill/deviceEpoch": { "$ref": "#/$defs/BoundedString" },
+				"webskill/sequence": {
+					"type": "integer",
+					"minimum": 1
+				},
+				"webskill/context": {
+					"type": "object",
+					"maxProperties": 128
+				}
+			},
+			"additionalProperties": true
+		},
+		"Principal": {
+			"title": "Principal",
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["displayName"],
+			"properties": { "displayName": { "$ref": "#/$defs/BoundedString" } }
+		},
+		"HelloParams": {
+			"title": "HelloParams",
+			"type": "object",
+			"additionalProperties": false,
+			"required": [
+				"protocolVersions",
+				"hostName",
+				"hostVersion"
+			],
+			"properties": {
+				"protocolVersions": {
+					"type": "array",
+					"minItems": 1,
+					"maxItems": 8,
+					"items": { "$ref": "#/$defs/ProtocolVersion" }
+				},
+				"hostName": { "$ref": "#/$defs/BoundedString" },
+				"hostVersion": { "$ref": "#/$defs/BoundedString" },
+				"deviceFingerprint": { "$ref": "#/$defs/BoundedString" }
+			}
+		},
+		"HelloResult": {
+			"title": "HelloResult",
+			"type": "object",
+			"additionalProperties": false,
+			"required": [
+				"protocolVersion",
+				"controllerInstanceId",
+				"controllerName",
+				"excludedOrigins"
+			],
+			"properties": {
+				"protocolVersion": { "$ref": "#/$defs/ProtocolVersion" },
+				"controllerInstanceId": { "$ref": "#/$defs/BoundedString" },
+				"controllerName": { "$ref": "#/$defs/BoundedString" },
+				"excludedOrigins": {
+					"type": "array",
+					"maxItems": 128,
+					"items": { "$ref": "#/$defs/Origin" }
+				}
+			}
+		},
+		"PairStartParams": {
+			"title": "PairStartParams",
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["publicKey", "deviceName"],
+			"properties": {
+				"publicKey": { "$ref": "#/$defs/Base64Url" },
+				"deviceName": { "$ref": "#/$defs/BoundedString" }
+			}
+		},
+		"PairStartResult": {
+			"title": "PairStartResult",
+			"type": "object",
+			"additionalProperties": false,
+			"required": [
+				"sessionId",
+				"code",
+				"expiresAt"
+			],
+			"properties": {
+				"sessionId": { "$ref": "#/$defs/BoundedString" },
+				"code": {
+					"type": "string",
+					"pattern": "^[A-Z0-9-]+$",
+					"maxLength": 32
+				},
+				"expiresAt": { "$ref": "#/$defs/IsoDateTime" }
+			}
+		},
+		"PairApprovedParams": {
+			"title": "PairApprovedParams",
+			"type": "object",
+			"additionalProperties": false,
+			"required": [
+				"sessionId",
+				"approvalNonce",
+				"controllerInstanceId",
+				"principal",
+				"capabilities",
+				"excludedOrigins"
+			],
+			"properties": {
+				"sessionId": { "$ref": "#/$defs/BoundedString" },
+				"approvalNonce": { "$ref": "#/$defs/Base64Url" },
+				"controllerInstanceId": { "$ref": "#/$defs/BoundedString" },
+				"principal": { "$ref": "#/$defs/Principal" },
+				"capabilities": {
+					"type": "array",
+					"maxItems": 128,
+					"items": { "$ref": "#/$defs/BoundedString" }
+				},
+				"excludedOrigins": {
+					"type": "array",
+					"maxItems": 128,
+					"items": { "$ref": "#/$defs/Origin" }
+				}
+			}
+		},
+		"PairRejectedParams": {
+			"title": "PairRejectedParams",
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["sessionId", "code"],
+			"properties": {
+				"sessionId": { "$ref": "#/$defs/BoundedString" },
+				"code": { "$ref": "#/$defs/BoundedString" }
+			}
+		},
+		"PairConfirmParams": {
+			"title": "PairConfirmParams",
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["sessionId", "accepted"],
+			"properties": {
+				"sessionId": { "$ref": "#/$defs/BoundedString" },
+				"accepted": { "type": "boolean" },
+				"signature": { "$ref": "#/$defs/Base64Url" }
+			}
+		},
+		"PairConfirmResult": {
+			"title": "PairConfirmResult",
+			"type": "object",
+			"additionalProperties": false,
+			"properties": {
+				"grant": { "$ref": "#/$defs/BoundedString" },
+				"expiresAt": { "$ref": "#/$defs/IsoDateTime" }
+			}
+		},
+		"AuthPresentParams": {
+			"title": "AuthPresentParams",
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["grant"],
+			"properties": { "grant": { "$ref": "#/$defs/BoundedString" } }
+		},
+		"AuthPresentResult": {
+			"title": "AuthPresentResult",
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["expiresAt"],
+			"properties": { "expiresAt": { "$ref": "#/$defs/IsoDateTime" } }
+		},
+		"AuthChallengeParams": {
+			"title": "AuthChallengeParams",
+			"type": "object",
+			"additionalProperties": false,
+			"properties": {}
+		},
+		"AuthChallengeResult": {
+			"title": "AuthChallengeResult",
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["nonce", "expiresAt"],
+			"properties": {
+				"nonce": { "$ref": "#/$defs/Base64Url" },
+				"expiresAt": { "$ref": "#/$defs/IsoDateTime" }
+			}
+		},
+		"AuthRenewParams": {
+			"title": "AuthRenewParams",
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["nonce", "signature"],
+			"properties": {
+				"nonce": { "$ref": "#/$defs/Base64Url" },
+				"signature": { "$ref": "#/$defs/Base64Url" }
+			}
+		},
+		"AuthRenewResult": {
+			"title": "AuthRenewResult",
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["grant", "expiresAt"],
+			"properties": {
+				"grant": { "$ref": "#/$defs/BoundedString" },
+				"expiresAt": { "$ref": "#/$defs/IsoDateTime" }
+			}
+		},
+		"AuthRevokedParams": {
+			"title": "AuthRevokedParams",
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["reason"],
+			"properties": { "reason": { "$ref": "#/$defs/BoundedString" } }
+		},
+		"OriginsParams": {
+			"title": "OriginsParams",
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["excludedOrigins"],
+			"properties": { "excludedOrigins": {
+				"type": "array",
+				"maxItems": 128,
+				"items": { "$ref": "#/$defs/Origin" }
+			} }
+		},
+		"HumanControlParams": {
+			"title": "HumanControlParams",
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["inControl", "at"],
+			"properties": {
+				"inControl": { "type": "boolean" },
+				"at": { "$ref": "#/$defs/IsoDateTime" }
+			}
+		},
+		"ReadyParams": {
+			"title": "ReadyParams",
+			"type": "object",
+			"additionalProperties": false,
+			"required": [
+				"deviceEpoch",
+				"writeHighWatermark",
+				"hostVersion",
+				"writeStateRecoverable"
+			],
+			"properties": {
+				"deviceEpoch": { "$ref": "#/$defs/BoundedString" },
+				"writeHighWatermark": {
+					"type": "integer",
+					"minimum": 0
+				},
+				"hostVersion": { "$ref": "#/$defs/BoundedString" },
+				"writeStateRecoverable": { "type": "boolean" }
+			}
+		},
+		"PingParams": {
+			"title": "PingParams",
+			"type": "object",
+			"additionalProperties": false,
+			"properties": {}
+		},
+		"PingResult": {
+			"title": "PingResult",
+			"type": "object",
+			"additionalProperties": false,
+			"properties": {}
+		},
+		"ByeParams": {
+			"title": "ByeParams",
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["code", "message"],
+			"properties": {
+				"code": { "$ref": "#/$defs/BoundedString" },
+				"message": { "$ref": "#/$defs/BoundedString" }
+			}
+		}
+	}
+};
+
+//#endregion
+//#region ../controller/src/validate.ts
+/** @experimental */
+const CONTROLLER_PROTOCOL_SCHEMA = protocol_schema_default;
+const METHOD_DEFINITIONS = {
+	"webskill/hello": "Hello",
+	"webskill/pair.start": "PairStart",
+	"webskill/pair.approved": "PairApproved",
+	"webskill/pair.rejected": "PairRejected",
+	"webskill/pair.confirm": "PairConfirm",
+	"webskill/auth.present": "AuthPresent",
+	"webskill/auth.challenge": "AuthChallenge",
+	"webskill/auth.renew": "AuthRenew",
+	"webskill/auth.revoked": "AuthRevoked",
+	"webskill/origins": "Origins",
+	"webskill/control.human": "HumanControl",
+	"webskill/ready": "Ready",
+	"webskill/ping": "Ping",
+	"webskill/bye": "Bye"
+};
+/** @experimental */
+function validateControllerMessage(method, kind, value) {
+	const definition = METHOD_DEFINITIONS[method];
+	if (!definition) return {
+		valid: false,
+		errors: [`Unknown controller method: ${method}`]
+	};
+	const def = protocol_schema_default.$defs[`${definition}${kind === "params" ? "Params" : "Result"}`];
+	if (!def) return {
+		valid: false,
+		errors: [`Missing schema for ${method} ${kind}`]
+	};
+	const result = new Validator({
+		...def,
+		$schema: "https://json-schema.org/draft/2020-12/schema",
+		$defs: protocol_schema_default.$defs
+	}, "2020-12", false).validate(value);
+	return {
+		valid: result.valid,
+		errors: result.errors.map((error) => `${error.instanceLocation || "/"}: ${error.error}`)
+	};
+}
+
+//#endregion
+//#region ../controller/src/transport.ts
+var SocketChannel = class {
+	options;
+	socket;
+	pending = /* @__PURE__ */ new Map();
+	sequence = 0;
+	opened = false;
+	closed = false;
+	connectPromise;
+	oversizeTimes = [];
+	maxMessageBytes;
+	defaultTimeoutMs;
+	mcpCallbacks = {};
+	constructor(options) {
+		this.options = options;
+		this.maxMessageBytes = options.maxMessageBytes ?? CONTROLLER_PROTOCOL_LIMITS.maxMessageBytes;
+		this.defaultTimeoutMs = options.requestTimeoutMs ?? CONTROLLER_PROTOCOL_LIMITS.heartbeatTimeoutMs;
+	}
+	async connect() {
+		if (this.opened && !this.closed) return;
+		if (this.connectPromise) return await this.connectPromise;
+		this.connectPromise = this.openSocket();
+		try {
+			await this.connectPromise;
+		} finally {
+			this.connectPromise = void 0;
+		}
+	}
+	async openSocket() {
+		const socket = this.options.socket ?? this.createSocket();
+		this.socket = socket;
+		if (this.options.socket) {
+			this.opened = true;
+			this.attach(socket);
+			return;
+		}
+		await new Promise((resolve, reject) => {
+			socket.onopen = () => {
+				this.opened = true;
+				resolve();
+			};
+			socket.onerror = (event) => {
+				const error = /* @__PURE__ */ new Error(`Controller WebSocket failed: ${String(event)}`);
+				this.options.onerror?.(error);
+				if (!this.opened) reject(error);
+			};
+			this.attach(socket);
+		});
+	}
+	createSocket() {
+		const Ctor = this.options.WebSocket ?? globalThis.WebSocket;
+		if (!Ctor) throw new Error("WebSocket is not available in this environment");
+		return new Ctor(this.options.url);
+	}
+	emitError(error) {
+		this.options.onerror?.(error);
+		this.mcpCallbacks.onerror?.(error);
+	}
+	attach(socket) {
+		socket.onclose = () => {
+			if (!this.opened) return;
+			this.handleClose();
+		};
+		socket.onmessage = (event) => {
+			this.handleMessage(event.data).catch((error) => this.emitError(error instanceof Error ? error : new Error(String(error))));
+		};
+	}
+	sendRaw(value) {
+		if (!this.socket || !this.opened || this.closed) throw new Error("Controller WebSocket is not connected");
+		const text = JSON.stringify(value);
+		if (byteLength(text) > this.maxMessageBytes) throw controllerError("CONTROLLER_MESSAGE_INVALID", "Controller message exceeds the protocol size limit");
+		this.socket.send(text);
+	}
+	validate(method, kind, value) {
+		const result = validateControllerMessage(method, kind, value);
+		if (!result.valid) throw controllerError("CONTROLLER_MESSAGE_INVALID", `Invalid ${method} ${kind}: ${result.errors.join("; ")}`);
+	}
+	async request(method, params, timeoutMs) {
+		await this.connect();
+		this.validate(method, "params", params);
+		const id = `ws-${++this.sequence}`;
+		const promise = new Promise((resolve, reject) => {
+			const timeout = setTimeout(() => {
+				this.pending.delete(id);
+				reject(/* @__PURE__ */ new Error(`Controller request timed out: ${method}`));
+			}, timeoutMs ?? this.defaultTimeoutMs);
+			this.pending.set(id, {
+				method,
+				resolve,
+				reject,
+				timeout
+			});
+		});
+		try {
+			this.sendRaw({
+				jsonrpc: "2.0",
+				id,
+				method,
+				params
+			});
+		} catch (error) {
+			const pending = this.pending.get(id);
+			if (pending?.timeout) clearTimeout(pending.timeout);
+			this.pending.delete(id);
+			throw error;
+		}
+		return await promise;
+	}
+	async notify(method, params) {
+		await this.connect();
+		this.validate(method, "params", params);
+		this.sendRaw({
+			jsonrpc: "2.0",
+			method,
+			params
+		});
+	}
+	registerOversize(message) {
+		const now = Date.now();
+		const windowMs = CONTROLLER_PROTOCOL_LIMITS.oversizeWindowMs;
+		this.oversizeTimes = this.oversizeTimes.filter((time) => now - time <= windowMs);
+		this.oversizeTimes.push(now);
+		if (message?.id !== void 0) this.sendRaw({
+			jsonrpc: "2.0",
+			id: message.id,
+			error: toJsonRpcError(controllerError("CONTROLLER_MESSAGE_INVALID", "Controller message exceeds the protocol size limit"))
+		});
+		if (this.oversizeTimes.length >= CONTROLLER_PROTOCOL_LIMITS.oversizeThreshold) this.socket?.close(1009, "Controller message size limit exceeded repeatedly");
+	}
+	async handleMessage(raw) {
+		const text = typeof raw === "string" ? raw : String(raw);
+		if (byteLength(text) > this.maxMessageBytes) {
+			let parsed;
+			try {
+				const candidate = JSON.parse(text);
+				if (isJsonRpcObject(candidate)) parsed = candidate;
+			} catch {
+				parsed = void 0;
+			}
+			this.registerOversize(parsed);
+			return;
+		}
+		let message;
+		try {
+			message = JSON.parse(text);
+		} catch {
+			this.options.onerror?.(/* @__PURE__ */ new Error("Invalid JSON received on the controller channel"));
+			return;
+		}
+		if (!isJsonRpcObject(message)) {
+			this.options.onerror?.(/* @__PURE__ */ new Error("Invalid JSON-RPC object received on the controller channel"));
+			return;
+		}
+		if (message.id !== void 0 && message.method === void 0) {
+			const pending = this.pending.get(message.id);
+			if (!pending) {
+				this.options.onmessage?.(message);
+				return;
+			}
+			this.pending.delete(message.id);
+			if (pending.timeout) clearTimeout(pending.timeout);
+			if (message.error) {
+				const code = message.error.data?.code ?? "CONTROLLER_MESSAGE_INVALID";
+				pending.reject(new ControllerRpcError(code, message.error.message));
+				return;
+			}
+			try {
+				this.validate(pending.method, "result", message.result);
+				pending.resolve(message.result);
+			} catch (error) {
+				pending.reject(error instanceof Error ? error : new Error(String(error)));
+			}
+			return;
+		}
+		if (typeof message.method !== "string") return;
+		if (!message.method.startsWith("webskill/")) {
+			if (this.options.isAuthorized?.() !== true) {
+				if (message.id !== void 0) this.sendRaw({
+					jsonrpc: "2.0",
+					id: message.id,
+					error: toJsonRpcError(controllerError("CONTROLLER_NOT_PAIRED", "The controller device is not paired"))
+				});
+				return;
+			}
+			this.options.onmessage?.(message);
+			return;
+		}
+		if (message.id === void 0) {
+			try {
+				this.validate(message.method, "params", message.params);
+				await this.options.onControlNotification?.(message.method, message.params);
+			} catch (error) {
+				this.options.onerror?.(error instanceof Error ? error : new Error(String(error)));
+			}
+			return;
+		}
+		try {
+			this.validate(message.method, "params", message.params);
+			const result = await this.options.onControlRequest?.(message.method, message.params);
+			this.validate(message.method, "result", result);
+			this.sendRaw({
+				jsonrpc: "2.0",
+				id: message.id,
+				result
+			});
+		} catch (error) {
+			this.sendRaw({
+				jsonrpc: "2.0",
+				id: message.id,
+				error: toJsonRpcError(error)
+			});
+		}
+	}
+	handleClose() {
+		if (this.closed) return;
+		this.closed = true;
+		this.opened = false;
+		const error = /* @__PURE__ */ new Error("Controller WebSocket closed");
+		for (const pending of this.pending.values()) {
+			if (pending.timeout) clearTimeout(pending.timeout);
+			pending.reject(error);
+		}
+		this.pending.clear();
+		this.options.onclose?.();
+		this.mcpCallbacks.onclose?.();
+	}
+	async close(code = 1e3, reason = "Controller channel closed") {
+		if (!this.socket || this.closed) return;
+		this.socket.close(code, reason);
+		this.handleClose();
+	}
+};
+/** @experimental */
+function createWebSocketControllerTransport(options) {
+	const channel = new SocketChannel(options);
+	const transport = {
+		get connected() {
+			return channel.opened && !channel.closed;
+		},
+		onControlRequest: void 0,
+		onControlNotification: void 0,
+		onmessage: void 0,
+		onerror: void 0,
+		onclose: void 0,
+		connect: () => channel.connect(),
+		start: () => channel.connect(),
+		request: (method, params, timeoutMs) => channel.request(method, params, timeoutMs),
+		notify: (method, params) => channel.notify(method, params),
+		send: async (message) => channel.sendRaw(message),
+		close: (code, reason) => channel.close(code, reason)
+	};
+	for (const key of [
+		"onControlRequest",
+		"onControlNotification",
+		"onmessage",
+		"onerror",
+		"onclose"
+	]) {
+		const isMcpLifecycle = key === "onerror" || key === "onclose";
+		Object.defineProperty(transport, key, {
+			get: () => isMcpLifecycle ? channel.mcpCallbacks[key] : options[key],
+			set: (value) => {
+				if (isMcpLifecycle) channel.mcpCallbacks[key] = value;
+				else options[key] = value;
+			},
+			enumerable: true,
+			configurable: true
+		});
+	}
+	return transport;
+}
+
+//#endregion
+//#region ../controller/src/device/crypto.ts
+function bytesToBase64Url(bytes) {
+	let binary = "";
+	const chunk = 32768;
+	for (let index = 0; index < bytes.length; index += chunk) binary += String.fromCharCode(...bytes.subarray(index, index + chunk));
+	return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+function base64UrlToBytes(value) {
+	const base64 = value.replace(/-/g, "+").replace(/_/g, "/");
+	const padded = base64 + "=".repeat((4 - base64.length % 4) % 4);
+	const binary = atob(padded);
+	return Uint8Array.from(binary, (char) => char.charCodeAt(0));
+}
+async function generateDeviceKeyPair() {
+	return await crypto.subtle.generateKey({
+		name: "ECDSA",
+		namedCurve: "P-256"
+	}, false, ["sign", "verify"]);
+}
+async function exportPublicKey(keyPair) {
+	return bytesToBase64Url(new Uint8Array(await crypto.subtle.exportKey("spki", keyPair.publicKey)));
+}
+async function signDeviceText(keyPair, value) {
+	const signature = await crypto.subtle.sign({
+		name: "ECDSA",
+		hash: "SHA-256"
+	}, keyPair.privateKey, new TextEncoder().encode(value));
+	return bytesToBase64Url(new Uint8Array(signature));
+}
+async function fingerprintOfBytes(bytes, bytesToShow = 10) {
+	const buffer = new ArrayBuffer(bytes.byteLength);
+	new Uint8Array(buffer).set(bytes);
+	return [...new Uint8Array(await crypto.subtle.digest("SHA-256", buffer)).subarray(0, bytesToShow)].map((byte) => byte.toString(16).padStart(2, "0")).join("").toUpperCase().match(/.{1,4}/g)?.join("-") ?? "";
+}
+async function deviceFingerprint(keyPair) {
+	return await fingerprintOfBytes(base64UrlToBytes(await exportPublicKey(keyPair)), 10);
+}
+/** @experimental */
+async function instanceFingerprint(instanceId) {
+	return await fingerprintOfBytes(new TextEncoder().encode(instanceId), 8);
+}
+function stableJson(value) {
+	if (value === null || typeof value !== "object") return JSON.stringify(value);
+	if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+	const object = value;
+	return `{${Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${stableJson(object[key])}`).join(",")}}`;
+}
+async function argsDigest(args) {
+	return bytesToBase64Url(new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(stableJson(args)))));
+}
+function randomToken(bytes = 32) {
+	return bytesToBase64Url(crypto.getRandomValues(new Uint8Array(bytes)));
+}
+function originFromControllerUrl(raw) {
+	const url = new URL(raw);
+	if (url.protocol === "wss:") return `https://${url.host}`;
+	if (url.protocol === "ws:") return `http://${url.host}`;
+	throw new WebSkillError("VALIDATION_FAILED", "Controller URL must use ws:// or wss://");
+}
+function isLoopbackHost(hostname) {
+	const host = hostname.replace(/^\[|\]$/g, "").toLowerCase();
+	return host === "::1" || host === "localhost" || host.endsWith(".localhost") || /^127(?:\.[0-9]{1,3}){3}$/.test(host);
+}
+function assertControllerUrl(raw) {
+	let url;
+	try {
+		url = new URL(raw);
+	} catch {
+		throw new WebSkillError("VALIDATION_FAILED", "Controller URL must be an absolute WebSocket URL");
+	}
+	if (url.protocol !== "ws:" && url.protocol !== "wss:") throw new WebSkillError("VALIDATION_FAILED", "Controller URL must use ws:// or wss://");
+	if (url.protocol === "ws:" && !isLoopbackHost(url.hostname)) throw new WebSkillError("VALIDATION_FAILED", "Non-loopback controllers must use wss://");
+	return url;
+}
+
+//#endregion
+//#region ../controller/src/device/tools.ts
+function isWriteTool(name) {
+	return CONTROLLER_WRITE_TOOLS.includes(name);
+}
+function browserStatusTool() {
+	return {
+		name: "browser_status",
+		description: "Read the extension version, protocol version, connection state, human-control state and excluded origins.",
+		inputSchema: {
+			type: "object",
+			properties: {},
+			additionalProperties: false
+		}
+	};
+}
+async function listControllerTools(sources) {
+	const tools = [browserStatusTool()];
+	for (const source of sources) {
+		const specs = await source.listToolSpecs();
+		for (const spec of specs) {
+			if (!CONTROLLER_TOOL_NAMES.includes(spec.name)) continue;
+			tools.push({
+				name: spec.name,
+				...spec.description === void 0 ? {} : { description: spec.description },
+				inputSchema: spec.inputSchema
+			});
+		}
+	}
+	return tools;
+}
+async function controllerInstructions(sources) {
+	const parts = [];
+	for (const source of sources) {
+		if (!(await source.listToolSpecs()).some((spec) => CONTROLLER_TOOL_NAMES.includes(spec.name))) continue;
+		const prompt = await source.systemPrompt?.();
+		if (prompt) parts.push(prompt);
+	}
+	return parts.length > 0 ? parts.join("\n\n") : void 0;
+}
+async function callControllerTool(sources, name, args, invocationId) {
+	const source = sources.find((candidate) => candidate.canHandle(name));
+	if (!source) throw controllerError("CONTROLLER_CAPABILITY_MISSING", `Controller tool is unavailable: ${name}`);
+	return await source.call(name, args, {
+		runId: invocationId ?? `controller-${name}`,
+		...invocationId === void 0 ? {} : { invocationId }
+	});
+}
+function toolResultError(error) {
+	const value = error;
+	const code = value?.code ?? "TOOL_EXECUTION_FAILED";
+	const message = value?.message ?? String(error);
+	const retryable = value?.data?.retryable === true || value?.details?.retryable === true || code in CONTROLLER_ERROR_RETRYABLE && CONTROLLER_ERROR_RETRYABLE[code];
+	return {
+		isError: true,
+		content: [{
+			type: "text",
+			text: message
+		}],
+		_meta: { "webskill/error": {
+			code,
+			message,
+			retryable
+		} }
+	};
+}
+function mapToolResult(result) {
+	if (!result.ok) return toolResultError(result.error ?? {
+		code: "TOOL_EXECUTION_FAILED",
+		message: "Controller tool failed"
+	});
+	const content = [];
+	let structuredContent;
+	for (const part of result.content) if (part.type === "text") content.push({
+		type: "text",
+		text: part.text ?? ""
+	});
+	else if (part.type === "json") {
+		const data = part.data ?? part.text;
+		content.push({
+			type: "text",
+			text: typeof data === "string" ? data : JSON.stringify(data)
+		});
+		if (typeof data === "object" && data !== null && !Array.isArray(data)) structuredContent = data;
+	} else if (part.type === "image") content.push({
+		type: "image",
+		mimeType: part.mimeType,
+		data: part.data
+	});
+	else return toolResultError(new ControllerRpcError("CONTROLLER_CAPABILITY_MISSING", `Controller result type is unsupported: ${part.type}`));
+	return {
+		content,
+		...structuredContent === void 0 ? {} : { structuredContent }
+	};
+}
+
+//#endregion
+//#region ../controller/src/device/index.ts
+const INVOCATION_ID = /^[A-Za-z0-9._:-]{1,128}$/;
+function errorCode(error) {
+	if (error instanceof WebSkillError) return error.code;
+	if (error instanceof ControllerRpcError) return error.code;
+	return "TOOL_EXECUTION_FAILED";
+}
+var DeviceSession = class {
+	options;
+	stateValue = "idle";
+	human = false;
+	transport;
+	pairing;
+	pendingPairing;
+	pendingApproval;
+	pairingCodeValue;
+	controllerInstance;
+	controllerName = "Controller";
+	excluded = /* @__PURE__ */ new Set();
+	keyPair;
+	connectPromise;
+	reconnectTimer;
+	heartbeatTimer;
+	renewTimer;
+	pairingTimer;
+	reconnectAttempt = 0;
+	intentionalClose = false;
+	mcpServer;
+	mcpStart;
+	writeQueue = Promise.resolve();
+	writeCache = /* @__PURE__ */ new Map();
+	restoredPairing = false;
+	writeState;
+	writeRecoverable = true;
+	lifecycleGeneration = 0;
+	lastToolNames = "";
+	constructor(options) {
+		this.options = options;
+		this.excluded.add(originFromControllerUrl(options.url));
+		for (const origin of options.excludedOrigins ?? []) this.excluded.add(origin);
+	}
+	get state() {
+		return this.stateValue;
+	}
+	get humanInControl() {
+		return this.human;
+	}
+	get writeStateRecoverable() {
+		return this.writeRecoverable;
+	}
+	get excludedOrigins() {
+		return [...this.excluded].sort();
+	}
+	get pairingCode() {
+		return this.pairingCodeValue;
+	}
+	get controllerInstanceId() {
+		return this.controllerInstance;
+	}
+	get controllerOrigin() {
+		return originFromControllerUrl(this.options.url);
+	}
+	now() {
+		return this.options.now?.() ?? Date.now();
+	}
+	setState(state) {
+		if (this.stateValue === state) return;
+		this.stateValue = state;
+		this.options.onStateChange?.(state);
+	}
+	reportError(error) {
+		const code = errorCode(error);
+		this.options.onError?.({
+			code,
+			message: error instanceof Error ? error.message : String(error)
+		});
+	}
+	audit(event) {
+		const audited = event.type === "controller.call" && typeof event.data["tool"] === "string" ? {
+			...event,
+			data: {
+				...event.data,
+				operation: isWriteTool(event.data["tool"]) ? "write" : "read"
+			}
+		} : event;
+		const pending = Promise.resolve(this.options.audit?.(audited));
+		pending.catch((error) => this.reportError(error));
+		return pending;
+	}
+	async connect() {
+		if (this.transport?.connected && [
+			"ready",
+			"unpaired",
+			"pairing",
+			"awaiting-confirmation"
+		].includes(this.stateValue)) return;
+		if (this.connectPromise) return await this.connectPromise;
+		this.intentionalClose = false;
+		this.connectPromise = this.open();
+		try {
+			await this.connectPromise;
+		} finally {
+			this.connectPromise = void 0;
+		}
+	}
+	async open() {
+		assertControllerUrl(this.options.url);
+		this.clearReconnect();
+		this.setState("connecting");
+		const transport = createWebSocketControllerTransport({
+			url: this.options.url,
+			...this.options.WebSocket === void 0 ? {} : { WebSocket: this.options.WebSocket },
+			isAuthorized: () => this.stateValue === "ready",
+			onControlRequest: (method, params) => this.onControlRequest(method, params),
+			onControlNotification: (method, params) => this.onControlNotification(method, params),
+			onclose: () => this.onTransportClose(),
+			onerror: (error) => this.reportError(error)
+		});
+		this.transport = transport;
+		try {
+			await transport.connect();
+			this.setState("handshaking");
+			const hello = await transport.request("webskill/hello", {
+				protocolVersions: ["0.1"],
+				hostName: this.options.deviceName,
+				hostVersion: this.options.hostVersion,
+				...this.keyPair === void 0 ? {} : { deviceFingerprint: await deviceFingerprint(this.keyPair) }
+			});
+			if (hello.protocolVersion !== "0.1") throw controllerError("CONTROLLER_PROTOCOL_UNSUPPORTED", `Controller protocol ${hello.protocolVersion} is not supported`);
+			this.controllerInstance = hello.controllerInstanceId;
+			this.controllerName = hello.controllerName;
+			this.mergeOrigins(hello.excludedOrigins);
+			this.startHeartbeat();
+			this.pairing = await this.options.store.loadPairing();
+			if (this.pairing) this.mergeOrigins(this.pairing.declaredOrigins);
+			this.options.onExcludedOriginsChange?.(this.excludedOrigins);
+			if (!this.pairing) {
+				this.setState("unpaired");
+				return;
+			}
+			if (this.pairing.controllerInstanceId !== hello.controllerInstanceId) {
+				const error = controllerError("CONTROLLER_NOT_PAIRED", "Controller instance changed; pair the device again");
+				this.reportError(error);
+				this.setState("failed");
+				this.intentionalClose = true;
+				await transport.close(1e3, "Controller instance changed");
+				throw error;
+			}
+			this.restoredPairing = true;
+			const writeState = await this.options.store.loadWriteState?.();
+			this.writeState = writeState?.epoch === this.pairing.sessionId && Number.isSafeInteger(writeState.highWatermark) && writeState.highWatermark >= 0 ? writeState : void 0;
+			this.writeRecoverable = this.writeState !== void 0;
+			await this.authorizeExistingPairing();
+		} catch (error) {
+			this.reportError(error);
+			this.stopHeartbeat();
+			if (!this.intentionalClose && this.pairing) {
+				this.setState("offline");
+				this.scheduleReconnect();
+			} else this.setState("failed");
+			throw error;
+		}
+	}
+	async authorizeExistingPairing() {
+		const record = this.pairing;
+		if (!record) return;
+		this.setState("authorizing");
+		try {
+			const result = await this.transport.request("webskill/auth.present", { grant: record.grant });
+			this.pairing = {
+				...record,
+				grantExpiresAt: result.expiresAt
+			};
+			await this.options.store.savePairing(this.pairing);
+			await this.becomeReady();
+		} catch (error) {
+			if (error instanceof ControllerRpcError && error.code === "CONTROLLER_NOT_PAIRED") try {
+				await this.renewGrant();
+				await this.becomeReady();
+				return;
+			} catch {
+				await this.options.store.savePairing(void 0);
+				this.pairing = void 0;
+				this.setState("unpaired");
+				return;
+			}
+			throw error;
+		}
+	}
+	async renewGrant() {
+		const record = this.pairing;
+		if (!record) throw controllerError("CONTROLLER_NOT_PAIRED", "No paired device grant is available");
+		const keyPair = this.keyPair ?? await this.options.store.loadKeyPair();
+		if (!keyPair) throw controllerError("CONTROLLER_NOT_PAIRED", "The device key pair is unavailable");
+		this.keyPair = keyPair;
+		const challenge = await this.transport.request("webskill/auth.challenge", {});
+		if (Date.parse(challenge.expiresAt) <= this.now()) throw controllerError("CONTROLLER_NOT_PAIRED", "The grant renewal challenge has expired");
+		const signature = await signDeviceText(keyPair, [
+			"webskill-controller/0.1",
+			"auth.renew",
+			record.controllerInstanceId,
+			challenge.nonce
+		].join("\n"));
+		const renewed = await this.transport.request("webskill/auth.renew", {
+			nonce: challenge.nonce,
+			signature
+		});
+		this.pairing = {
+			...record,
+			grant: renewed.grant,
+			grantExpiresAt: renewed.expiresAt
+		};
+		await this.options.store.savePairing(this.pairing);
+	}
+	async startWriteEpoch(sessionId) {
+		this.restoredPairing = false;
+		this.writeRecoverable = true;
+		this.writeCache.clear();
+		this.writeState = {
+			epoch: sessionId,
+			highWatermark: 0
+		};
+		await this.options.store.saveWriteState?.(this.writeState);
+	}
+	async persistWriteState() {
+		if (this.writeState) await this.options.store.saveWriteState?.(this.writeState);
+	}
+	async becomeReady() {
+		this.reconnectAttempt = 0;
+		await this.startMcp();
+		const epoch = this.pairing?.sessionId ?? this.writeState?.epoch;
+		if (!epoch) throw controllerError("CONTROLLER_NOT_PAIRED", "The device has no pairing epoch for the ready notification");
+		this.setState("ready");
+		await this.transport?.notify("webskill/ready", {
+			deviceEpoch: epoch,
+			writeHighWatermark: this.writeState?.highWatermark ?? 0,
+			hostVersion: this.options.hostVersion,
+			writeStateRecoverable: this.writeRecoverable
+		});
+		this.audit({
+			type: "controller.connection",
+			data: {
+				state: "ready",
+				controllerOrigin: this.controllerOrigin,
+				controllerInstance: this.controllerInstance ?? ""
+			}
+		});
+		this.scheduleRenewal();
+	}
+	async startPairing() {
+		if (this.stateValue === "ready") throw controllerError("CONTROLLER_PAIRING_REJECTED", "The device is already paired");
+		if (!this.transport?.connected || [
+			"idle",
+			"offline",
+			"failed"
+		].includes(this.stateValue)) await this.connect();
+		if (!this.transport?.connected || this.stateValue !== "unpaired") throw controllerError("CONTROLLER_PAIRING_REJECTED", "The controller is not ready for pairing");
+		this.keyPair = await this.options.store.loadKeyPair() ?? await generateDeviceKeyPair();
+		await this.options.store.saveKeyPair(this.keyPair);
+		const publicKey = await exportPublicKey(this.keyPair);
+		const fingerprint = await deviceFingerprint(this.keyPair);
+		const started = await this.transport.request("webskill/pair.start", {
+			publicKey,
+			deviceName: this.options.deviceName
+		});
+		this.pendingPairing = {
+			...started,
+			publicKey,
+			deviceFingerprint: fingerprint
+		};
+		this.pendingApproval = void 0;
+		this.pairingCodeValue = {
+			...started,
+			deviceFingerprint: fingerprint
+		};
+		this.setState("pairing");
+		this.audit({
+			type: "controller.pairing",
+			data: {
+				phase: "started",
+				sessionId: started.sessionId
+			}
+		});
+		const ttl = Math.max(1, Date.parse(started.expiresAt) - this.now());
+		this.pairingTimer = setTimeout(() => {
+			if (this.stateValue === "pairing" || this.stateValue === "awaiting-confirmation") {
+				this.pendingPairing = void 0;
+				this.pendingApproval = void 0;
+				this.pairingCodeValue = void 0;
+				this.setState("unpaired");
+				this.reportError(controllerError("CONTROLLER_PAIRING_REJECTED", "The pairing session has expired"));
+			}
+		}, ttl);
+		return this.pairingCodeValue;
+	}
+	onPairApproved(approval) {
+		const pending = this.pendingPairing;
+		if (!pending || pending.sessionId !== approval.sessionId || this.stateValue !== "pairing") return;
+		if (approval.controllerInstanceId !== this.controllerInstance) {
+			this.reportError(controllerError("CONTROLLER_NOT_PAIRED", "The approval came from a different controller instance"));
+			return;
+		}
+		this.pendingApproval = approval;
+		this.mergeOrigins(approval.excludedOrigins);
+		this.setState("awaiting-confirmation");
+		this.confirmApprovedPairing(approval).catch((error) => this.reportError(error));
+	}
+	async confirmApprovedPairing(approval) {
+		let accepted = false;
+		let timer;
+		try {
+			accepted = await Promise.race([this.options.confirmPairing({
+				...approval,
+				controllerName: this.controllerName
+			}), new Promise((_, reject) => {
+				timer = setTimeout(() => reject(controllerError("CONTROLLER_PAIRING_REJECTED", "Device-side pairing confirmation timed out")), CONTROLLER_PROTOCOL_LIMITS.deviceConfirmTimeoutMs);
+			})]);
+		} catch (error) {
+			this.reportError(error);
+		} finally {
+			if (timer) clearTimeout(timer);
+		}
+		if (!this.pendingPairing || this.pendingPairing.sessionId !== approval.sessionId) return;
+		let signature;
+		if (accepted) signature = await signDeviceText(this.keyPair, [
+			"webskill-controller/0.1",
+			"pair.confirm",
+			approval.sessionId,
+			approval.approvalNonce
+		].join("\n"));
+		const result = await this.transport.request("webskill/pair.confirm", {
+			sessionId: approval.sessionId,
+			accepted,
+			...signature === void 0 ? {} : { signature }
+		});
+		if (!accepted) {
+			this.pendingPairing = void 0;
+			this.pendingApproval = void 0;
+			this.pairingCodeValue = void 0;
+			this.setState("unpaired");
+			return;
+		}
+		if (!result.grant || !result.expiresAt) throw controllerError("CONTROLLER_PAIRING_REJECTED", "The controller did not return a device grant");
+		const record = {
+			controllerUrl: this.options.url,
+			controllerInstanceId: approval.controllerInstanceId,
+			controllerName: this.controllerName,
+			principalDisplayName: approval.principal.displayName,
+			sessionId: approval.sessionId,
+			grant: result.grant,
+			grantExpiresAt: result.expiresAt,
+			declaredOrigins: this.excludedOrigins,
+			pairedAt: new Date(this.now()).toISOString()
+		};
+		this.pairing = record;
+		await this.options.store.savePairing(record);
+		await this.startWriteEpoch(record.sessionId);
+		this.pendingPairing = void 0;
+		this.pendingApproval = void 0;
+		this.pairingCodeValue = void 0;
+		this.clearPairingTimer();
+		this.audit({
+			type: "controller.pairing",
+			data: {
+				phase: "confirmed",
+				sessionId: approval.sessionId,
+				principal: approval.principal.displayName
+			}
+		});
+		await this.becomeReady();
+	}
+	onPairRejected(rejected) {
+		if (this.pendingPairing?.sessionId !== rejected.sessionId) return;
+		this.pendingPairing = void 0;
+		this.pendingApproval = void 0;
+		this.pairingCodeValue = void 0;
+		this.clearPairingTimer();
+		this.setState("unpaired");
+		this.reportError(controllerError("CONTROLLER_PAIRING_REJECTED", rejected.code));
+		this.audit({
+			type: "controller.pairing",
+			data: {
+				phase: "rejected",
+				sessionId: rejected.sessionId
+			}
+		});
+	}
+	mergeOrigins(origins) {
+		const previous = this.excludedOrigins;
+		for (const origin of origins) this.excluded.add(origin);
+		const next = this.excludedOrigins;
+		if (next.length !== previous.length) {
+			this.options.onExcludedOriginsChange?.(next);
+			this.audit({
+				type: "controller.origins",
+				data: {
+					effective: next,
+					removedFromDeclaration: previous.filter((origin) => !origins.includes(origin))
+				}
+			});
+			if (this.pairing) {
+				this.pairing = {
+					...this.pairing,
+					declaredOrigins: next
+				};
+				this.options.store.savePairing(this.pairing).catch((error) => this.reportError(error));
+			}
+		}
+	}
+	onControlRequest(method, _params) {
+		if (method === "webskill/ping") return {};
+		if (method === "webskill/bye") {
+			this.transport?.close();
+			return {};
+		}
+		throw controllerError("CONTROLLER_CAPABILITY_MISSING", `Unsupported controller request: ${method}`);
+	}
+	onControlNotification(method, params) {
+		switch (method) {
+			case "webskill/pair.approved":
+				this.onPairApproved(params);
+				return;
+			case "webskill/pair.rejected":
+				this.onPairRejected(params);
+				return;
+			case "webskill/origins":
+				this.mergeOrigins(params.excludedOrigins);
+				return;
+			case "webskill/auth.revoked":
+				this.onRevoked(params.reason);
+				return;
+			case "webskill/bye":
+				this.transport?.close();
+				return;
+			default: this.reportError(controllerError("CONTROLLER_CAPABILITY_MISSING", `Unsupported controller notification: ${method}`));
+		}
+	}
+	async onRevoked(reason) {
+		this.lifecycleGeneration += 1;
+		await this.options.store.savePairing(void 0);
+		this.pairing = void 0;
+		this.writeState = void 0;
+		this.restoredPairing = false;
+		this.writeRecoverable = true;
+		this.writeCache.clear();
+		await this.options.store.saveWriteState?.(void 0);
+		await this.stopMcp();
+		this.setState("unpaired");
+		this.audit({
+			type: "controller.pairing",
+			data: {
+				phase: "unpaired",
+				reason
+			}
+		});
+		this.reportError(controllerError("CONTROLLER_NOT_PAIRED", `The device grant was revoked: ${reason}`));
+	}
+	startHeartbeat() {
+		this.stopHeartbeat();
+		this.heartbeatTimer = setInterval(() => {
+			if (!this.transport?.connected) return;
+			this.transport.request("webskill/ping", {}, CONTROLLER_PROTOCOL_LIMITS.heartbeatTimeoutMs).catch((error) => {
+				this.reportError(error);
+				this.transport?.close(1001, "Controller heartbeat timed out");
+			});
+		}, CONTROLLER_PROTOCOL_LIMITS.heartbeatIntervalMs);
+	}
+	stopHeartbeat() {
+		if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
+		this.heartbeatTimer = void 0;
+	}
+	scheduleRenewal() {
+		if (this.renewTimer) clearTimeout(this.renewTimer);
+		const record = this.pairing;
+		if (!record) return;
+		const remaining = Math.max(1, Date.parse(record.grantExpiresAt) - this.now());
+		this.renewTimer = setTimeout(() => {
+			this.renewGrant().then(() => this.scheduleRenewal()).catch((error) => {
+				this.reportError(error);
+				this.onRevoked("grant-renewal-failed");
+			});
+		}, Math.max(1, Math.floor(remaining * .8)));
+	}
+	onTransportClose() {
+		this.lifecycleGeneration += 1;
+		this.stopHeartbeat();
+		if (this.renewTimer) clearTimeout(this.renewTimer);
+		this.stopMcp();
+		if (this.pendingPairing && (this.stateValue === "pairing" || this.stateValue === "awaiting-confirmation")) {
+			this.pendingPairing = void 0;
+			this.pendingApproval = void 0;
+			this.pairingCodeValue = void 0;
+			this.clearPairingTimer();
+			this.setState("unpaired");
+		}
+		if (!this.intentionalClose && this.pairing) {
+			this.setState("offline");
+			this.scheduleReconnect();
+		}
+	}
+	clearReconnect() {
+		if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
+		this.reconnectTimer = void 0;
+	}
+	scheduleReconnect() {
+		if (this.reconnectTimer || this.intentionalClose || !this.pairing) return;
+		const base = Math.min(1e3 * 2 ** this.reconnectAttempt, CONTROLLER_PROTOCOL_LIMITS.reconnectMaxDelayMs);
+		this.reconnectAttempt += 1;
+		const jitter = base * (Math.random() * .4 - .2);
+		this.reconnectTimer = setTimeout(() => {
+			this.reconnectTimer = void 0;
+			this.connect().catch(() => void 0);
+		}, Math.max(100, Math.floor(base + jitter)));
+	}
+	async disconnect(reason = "User disconnected") {
+		this.lifecycleGeneration += 1;
+		this.intentionalClose = true;
+		this.clearReconnect();
+		this.stopHeartbeat();
+		this.clearPairingTimer();
+		if (this.renewTimer) clearTimeout(this.renewTimer);
+		const transport = this.transport;
+		this.transport = void 0;
+		if (transport?.connected) {
+			await transport.notify("webskill/bye", {
+				code: "disconnect",
+				message: reason
+			}).catch(() => void 0);
+			await transport.close(1e3, reason);
+		}
+		await this.stopMcp();
+		this.setState("idle");
+	}
+	async unpair() {
+		const sessionId = this.pairing?.sessionId ?? this.pendingPairing?.sessionId;
+		this.audit({
+			type: "controller.pairing",
+			data: {
+				phase: "unpaired",
+				...sessionId === void 0 ? {} : { sessionId }
+			}
+		});
+		await this.disconnect("Device unpaired");
+		await this.options.store.clear();
+		this.pairing = void 0;
+		this.keyPair = void 0;
+		this.writeState = void 0;
+		this.restoredPairing = false;
+		this.writeRecoverable = true;
+		this.writeCache.clear();
+		this.pendingPairing = void 0;
+		this.pendingApproval = void 0;
+		this.pairingCodeValue = void 0;
+		this.excluded = /* @__PURE__ */ new Set([this.controllerOrigin]);
+		this.setState("idle");
+	}
+	setHumanInControl(inControl) {
+		if (this.human === inControl) return;
+		this.lifecycleGeneration += 1;
+		this.human = inControl;
+		this.audit({
+			type: "controller.human-control",
+			data: { inControl }
+		});
+		if (this.transport?.connected) this.transport.notify("webskill/control.human", {
+			inControl,
+			at: new Date(this.now()).toISOString()
+		}).catch((error) => this.reportError(error));
+	}
+	clearPairingTimer() {
+		if (this.pairingTimer) clearTimeout(this.pairingTimer);
+		this.pairingTimer = void 0;
+	}
+	async startMcp() {
+		if (this.mcpServer || this.mcpStart) return await this.mcpStart;
+		this.mcpStart = this.startMcpServer();
+		try {
+			await this.mcpStart;
+		} finally {
+			this.mcpStart = void 0;
+		}
+	}
+	async startMcpServer() {
+		const transport = this.transport;
+		if (!transport) throw controllerError("CONTROLLER_NOT_PAIRED", "The device transport is unavailable");
+		let ServerCtor;
+		let ValidatorCtor;
+		let ListToolsSchema;
+		let CallToolSchema;
+		let McpErrorCtor;
+		try {
+			const [serverModule, validatorModule, typesModule] = await Promise.all([
+				import("@modelcontextprotocol/sdk/server/index.js"),
+				import("@modelcontextprotocol/sdk/validation/cfworker"),
+				import("@modelcontextprotocol/sdk/types.js")
+			]);
+			ServerCtor = serverModule.Server;
+			ValidatorCtor = validatorModule.CfWorkerJsonSchemaValidator;
+			ListToolsSchema = typesModule.ListToolsRequestSchema;
+			CallToolSchema = typesModule.CallToolRequestSchema;
+			McpErrorCtor = typesModule.McpError;
+		} catch (error) {
+			throw new WebSkillError("MCP_ENDPOINT_UNAVAILABLE", "The MCP SDK is required to start the controller device", error);
+		}
+		const instructions = await controllerInstructions(this.options.tools);
+		const server = new ServerCtor({
+			name: "webskill-extension",
+			version: this.options.hostVersion
+		}, {
+			capabilities: { tools: { listChanged: true } },
+			...instructions === void 0 ? {} : { instructions },
+			jsonSchemaValidator: new ValidatorCtor()
+		});
+		server.setRequestHandler(ListToolsSchema, async () => ({ tools: await this.listTools() }));
+		server.setRequestHandler(CallToolSchema, async (request) => {
+			try {
+				return await this.onToolCall(request.params);
+			} catch (error) {
+				if (error instanceof ControllerRpcError) {
+					const rpc = toJsonRpcError(error);
+					throw new McpErrorCtor(rpc.code, rpc.message, rpc.data);
+				}
+				throw error;
+			}
+		});
+		await server.connect(transport);
+		if (transport !== this.transport || !transport.connected) {
+			await server.close();
+			throw controllerError("CONTROLLER_MESSAGE_INVALID", "Controller transport changed while starting MCP");
+		}
+		this.mcpServer = server;
+	}
+	async stopMcp() {
+		const server = this.mcpServer;
+		this.mcpServer = void 0;
+		if (server) await server.close().catch(() => void 0);
+	}
+	async listTools() {
+		const tools = await listControllerTools(this.options.tools);
+		this.lastToolNames = tools.map((tool) => tool.name).sort().join("\n");
+		return tools;
+	}
+	readInvocation(params) {
+		const input = params;
+		if (input._meta !== void 0 && (typeof input._meta !== "object" || input._meta === null || Array.isArray(input._meta))) throw controllerError("CONTROLLER_MESSAGE_INVALID", "Tool _meta must be a JSON object");
+		const meta = input._meta ?? {};
+		const id = meta["webskill/invocationId"];
+		if (typeof id !== "string" || !INVOCATION_ID.test(id)) throw controllerError("CONTROLLER_MESSAGE_INVALID", "A valid webskill/invocationId is required for every tool call");
+		const epoch = meta["webskill/deviceEpoch"];
+		if (epoch !== void 0 && (typeof epoch !== "string" || !INVOCATION_ID.test(epoch))) throw controllerError("CONTROLLER_MESSAGE_INVALID", "webskill/deviceEpoch must match the pairing session ID");
+		const sequence = meta["webskill/sequence"];
+		if (sequence !== void 0 && (!Number.isSafeInteger(sequence) || sequence < 1)) throw controllerError("CONTROLLER_MESSAGE_INVALID", "webskill/sequence must be a positive integer");
+		const context = meta["webskill/context"];
+		if (context !== void 0 && (typeof context !== "object" || context === null || Array.isArray(context))) throw controllerError("CONTROLLER_MESSAGE_INVALID", "webskill/context must be a JSON object");
+		if (context !== void 0 && byteLength(JSON.stringify(context)) > CONTROLLER_PROTOCOL_LIMITS.invocationContextMaxBytes) throw controllerError("CONTROLLER_MESSAGE_INVALID", "webskill/context exceeds the protocol size limit");
+		const args = input.arguments ?? {};
+		if (typeof args !== "object" || args === null || Array.isArray(args)) throw controllerError("CONTROLLER_MESSAGE_INVALID", "Tool arguments must be a JSON object");
+		return {
+			id,
+			...epoch === void 0 ? {} : { epoch },
+			...sequence === void 0 ? {} : { sequence },
+			...context === void 0 ? {} : { context },
+			args
+		};
+	}
+	async onToolCall(params) {
+		try {
+			const { id, epoch, sequence, context, args } = this.readInvocation(params);
+			const toolName = params.name;
+			if (typeof toolName !== "string" || !toolName) throw controllerError("CONTROLLER_CAPABILITY_MISSING", "A tool name is required");
+			if (isWriteTool(toolName)) {
+				const result = await this.executeWrite(id, epoch, sequence, toolName, args, context, this.human);
+				try {
+					await this.refreshTools();
+				} catch (error) {
+					this.reportError(error);
+				}
+				return result;
+			}
+			if (this.human && toolName !== "browser_status") return toolResultError(controllerError("CONTROLLER_HUMAN_IN_CONTROL", "The user is in control of the browser"));
+			if (!(await listControllerTools(this.options.tools)).some((tool) => tool.name === toolName)) {
+				await this.audit({
+					type: "controller.call",
+					data: {
+						invocationId: id,
+						tool: toolName,
+						phase: "rejected",
+						code: "CONTROLLER_CAPABILITY_MISSING"
+					}
+				});
+				throw controllerError("CONTROLLER_CAPABILITY_MISSING", `Controller tool is unavailable: ${toolName}`);
+			}
+			await this.audit({
+				type: "controller.call",
+				data: {
+					invocationId: id,
+					tool: toolName,
+					phase: "started",
+					...context === void 0 ? {} : { context }
+				}
+			});
+			const result = this.fitResult(await this.executeRead(toolName, args));
+			await this.auditCall(id, toolName, result, context);
+			await this.refreshTools();
+			return result;
+		} catch (error) {
+			if (error instanceof ControllerRpcError && ["CONTROLLER_MESSAGE_INVALID", "CONTROLLER_CAPABILITY_MISSING"].includes(error.code)) throw error;
+			this.reportError(error);
+			return toolResultError(error);
+		}
+	}
+	fitResult(result) {
+		if (byteLength(JSON.stringify(result)) <= CONTROLLER_PROTOCOL_LIMITS.maxMessageBytes) return result;
+		return toolResultError(controllerError("CONTROLLER_MESSAGE_INVALID", "Controller tool result exceeds the protocol size limit"));
+	}
+	async executeRead(name, args, invocationId) {
+		if (name === "browser_status") return mapToolResult({
+			ok: true,
+			content: [{
+				type: "json",
+				data: {
+					hostVersion: this.options.hostVersion,
+					protocolVersion: "0.1",
+					humanInControl: this.human,
+					connectionState: this.stateValue,
+					excludedOrigins: this.excludedOrigins,
+					deviceEpoch: this.writeState?.epoch ?? this.pairing?.sessionId ?? "",
+					writeHighWatermark: this.writeState?.highWatermark ?? 0,
+					writeStateRecoverable: this.writeRecoverable
+				}
+			}]
+		});
+		const result = await callControllerTool(this.options.tools, name, args, invocationId);
+		const mapped = mapToolResult(result);
+		if (result.authorization) return {
+			...mapped,
+			_meta: {
+				...mapped._meta,
+				"webskill/authorization": result.authorization
+			}
+		};
+		return mapped;
+	}
+	async executeWrite(id, epoch, sequence, name, args, context, rejectNewInvocation = false) {
+		this.pruneWriteCache();
+		if (epoch === void 0 || sequence === void 0) throw controllerError("CONTROLLER_MESSAGE_INVALID", "Write calls require webskill/deviceEpoch and webskill/sequence");
+		const state = this.writeState;
+		const duplicate = (message) => toolResultError(controllerError("CONTROLLER_INVOCATION_DUPLICATE", message));
+		if (this.restoredPairing && state === void 0 || state?.epoch !== epoch) return duplicate("The invocation epoch or recoverable write state is not valid for this pairing");
+		const existing = this.writeCache.get(id);
+		if (existing) {
+			if (existing.epoch !== epoch || existing.sequence !== sequence || existing.tool !== name) return toolResultError(controllerError("CONTROLLER_MESSAGE_INVALID", "The invocation ID was reused with different protocol metadata"));
+			const [digest, originalDigest] = await Promise.all([argsDigest(args), existing.argsDigest]);
+			if (digest !== originalDigest) return toolResultError(controllerError("CONTROLLER_MESSAGE_INVALID", "The invocation ID was reused with different tool arguments"));
+			return await existing.promise;
+		}
+		if (rejectNewInvocation) return toolResultError(controllerError("CONTROLLER_HUMAN_IN_CONTROL", "The user is in control of the browser"));
+		if (sequence <= state.highWatermark) return duplicate("The invocation sequence is outside the recoverable result window; do not retry it without user confirmation");
+		if (sequence > state.highWatermark + CONTROLLER_PROTOCOL_LIMITS.idempotencyCacheEntries) throw controllerError("CONTROLLER_MESSAGE_INVALID", "The invocation sequence exceeds the acceptable forward window");
+		this.writeState = {
+			epoch,
+			highWatermark: sequence
+		};
+		const generation = this.lifecycleGeneration;
+		const execute = async () => {
+			try {
+				await this.persistWriteState();
+				if (generation !== this.lifecycleGeneration || this.human || this.stateValue !== "ready") return toolResultError(controllerError(this.human ? "CONTROLLER_HUMAN_IN_CONTROL" : "CONTROLLER_NOT_PAIRED", "The queued write was cancelled before it could execute"));
+				await this.audit({
+					type: "controller.call",
+					data: {
+						invocationId: id,
+						tool: name,
+						phase: "started",
+						...context === void 0 ? {} : { context }
+					}
+				});
+				if (!(await listControllerTools(this.options.tools)).some((tool) => tool.name === name)) {
+					await this.audit({
+						type: "controller.call",
+						data: {
+							invocationId: id,
+							tool: name,
+							phase: "rejected",
+							code: "CONTROLLER_CAPABILITY_MISSING"
+						}
+					});
+					throw controllerError("CONTROLLER_CAPABILITY_MISSING", `Controller tool is unavailable: ${name}`);
+				}
+				if (generation !== this.lifecycleGeneration || this.human || this.stateValue !== "ready") return toolResultError(controllerError(this.human ? "CONTROLLER_HUMAN_IN_CONTROL" : "CONTROLLER_NOT_PAIRED", "The queued write was cancelled before it could execute"));
+				const result = this.fitResult(await this.executeRead(name, args, id));
+				try {
+					await this.auditCall(id, name, result, context);
+				} catch (error) {
+					this.reportError(error);
+					return {
+						...result,
+						_meta: {
+							...result._meta,
+							"webskill/auditIncomplete": true
+						}
+					};
+				}
+				return result;
+			} catch (error) {
+				if (error instanceof ControllerRpcError && ["CONTROLLER_MESSAGE_INVALID", "CONTROLLER_CAPABILITY_MISSING"].includes(error.code)) throw error;
+				this.reportError(error);
+				return toolResultError(error);
+			}
+		};
+		const queued = this.writeQueue.then(execute, execute);
+		const entry = {
+			epoch,
+			sequence,
+			tool: name,
+			argsDigest: argsDigest(args),
+			promise: queued.then((result) => {
+				entry.result = result;
+				entry.completedAt = this.now();
+				this.pruneWriteCache();
+				return result;
+			}, (error) => {
+				entry.completedAt = this.now();
+				this.pruneWriteCache();
+				throw error;
+			})
+		};
+		this.writeCache.set(id, entry);
+		this.writeQueue = queued.then(() => void 0, () => void 0);
+		return await entry.promise;
+	}
+	pruneWriteCache() {
+		const now = this.now();
+		for (const [key, entry] of this.writeCache) if (entry.completedAt !== void 0 && now - entry.completedAt > CONTROLLER_PROTOCOL_LIMITS.idempotencyCacheTtlMs) this.writeCache.delete(key);
+		if (this.writeCache.size <= CONTROLLER_PROTOCOL_LIMITS.idempotencyCacheEntries) return;
+		for (const [key, entry] of this.writeCache) {
+			if (entry.completedAt === void 0) continue;
+			this.writeCache.delete(key);
+			if (this.writeCache.size <= CONTROLLER_PROTOCOL_LIMITS.idempotencyCacheEntries) return;
+		}
+	}
+	async auditCall(invocationId, tool, result, context) {
+		const failure = result._meta?.["webskill/error"];
+		await this.audit({
+			type: "controller.call",
+			data: {
+				invocationId,
+				tool,
+				ok: result.isError !== true,
+				...failure?.code === void 0 ? {} : { code: failure.code },
+				...result._meta?.["webskill/authorization"] === void 0 ? {} : { authorization: result._meta["webskill/authorization"] },
+				...context === void 0 ? {} : { context }
+			}
+		});
+	}
+	async refreshTools() {
+		if (this.stateValue !== "ready" || !this.transport?.connected) return;
+		const names = (await listControllerTools(this.options.tools)).map((tool) => tool.name).sort().join("\n");
+		if (names === this.lastToolNames) return;
+		this.lastToolNames = names;
+		await this.transport.send({
+			jsonrpc: "2.0",
+			method: "notifications/tools/list_changed"
+		});
+	}
+};
+/** @experimental */
+function createControllerDevice(options) {
+	assertControllerUrl(options.url);
+	return new DeviceSession(options);
+}
+
+//#endregion
+export { createWebSocketControllerTransport as a, ControllerRpcError as c, CONTROLLER_PROTOCOL_VERSION as d, CONTROLLER_TOOL_NAMES as f, randomToken as i, controllerError as l, base64UrlToBytes as n, CONTROLLER_PROTOCOL_SCHEMA as o, instanceFingerprint as r, validateControllerMessage as s, createControllerDevice as t, CONTROLLER_PROTOCOL_LIMITS as u };