@alfe.ai/remote 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,36 @@
+# `@alfe.ai/remote`
+
+Shared transport and frame codec for Alfe's interactive browser and terminal
+relay. The package provides:
+
+- `RemoteServiceClient`, one outbound authenticated WebSocket per agent;
+- the five-byte multiplexed binary frame codec and direction helpers;
+- bounded runtime decoders for relay control payloads;
+- `SurfaceHandler` and `TurnController` contracts used by the browser and
+  terminal packages.
+
+## Client usage
+
+```ts
+import { RemoteServiceClient } from "@alfe.ai/remote";
+
+const client = new RemoteServiceClient({
+  wsUrl: "wss://remote.dev.alfe.ai/ws",
+  apiKey: process.env.ALFE_API_KEY!,
+  onFrame: (frame) => routeFrame(frame),
+});
+
+client.start();
+```
+
+The relay URL is an authentication boundary because the API key is sent in the
+WebSocket upgrade. Production callers must derive or authorize the exact relay
+host from trusted Alfe configuration. The client requires WSS, permits plain WS
+only for loopback development, rejects URL userinfo/fragments, and redacts query
+parameters from logs.
+
+Inbound and outbound frames are capped at 10 MiB. Control JSON is capped at
+64 KiB. Use the exported shape-specific decoders instead of casting
+`decodeJson()` results at a surface boundary.
+
+See [Alfe](https://alfe.ai) and the [documentation](https://docs.alfe.ai).

package/dist/index.cjs

@@ -41,9 +41,15 @@ ws = __toESM(ws);
 *   • viewer → plugin: SESSION_OPEN, SESSION_CLOSE, SCREENCAST_ACK, INPUT_*,
 *     RESIZE, TAKEOVER_REQUEST, RELEASE_CONTROL, TERMINAL_INPUT, TERMINAL_RESIZE
 *
-* Keep this file byte-identical with `services/remote/src/remote-protocol.ts`.
+* Keep agent-facing frame values byte-compatible with
+* `services/remote/src/remote-protocol.ts`. The relay may define private frame
+* types that it consumes without forwarding them to the agent.
 */
 const REMOTE_HEADER_SIZE = 5;
+/** Maximum complete WebSocket message size, including the five-byte header. */
+const REMOTE_MAX_PAYLOAD = 10 * 1024 * 1024;
+/** Control payloads are deliberately much smaller than media/terminal frames. */
+const REMOTE_MAX_JSON_PAYLOAD = 64 * 1024;
 const RemoteFrameType = {
 	SESSION_OPEN: 1,
 	SESSION_CLOSE: 2,
@@ -64,36 +70,76 @@ const RemoteFrameType = {
 	TERMINAL_INPUT: 65,
 	TERMINAL_RESIZE: 66
 };
-const MIN_FRAME_TYPE = RemoteFrameType.SESSION_OPEN;
-const MAX_FRAME_TYPE = RemoteFrameType.TERMINAL_RESIZE;
+const VALID_FRAME_TYPES = new Set(Object.values(RemoteFrameType));
+const RELAY_TO_AGENT_FRAME_TYPES = new Set([
+	RemoteFrameType.SESSION_OPEN,
+	RemoteFrameType.SESSION_CLOSE,
+	RemoteFrameType.SCREENCAST_ACK,
+	RemoteFrameType.INPUT_MOUSE,
+	RemoteFrameType.INPUT_WHEEL,
+	RemoteFrameType.INPUT_KEY,
+	RemoteFrameType.RESIZE,
+	RemoteFrameType.TAKEOVER_REQUEST,
+	RemoteFrameType.RELEASE_CONTROL,
+	RemoteFrameType.TERMINAL_INPUT,
+	RemoteFrameType.TERMINAL_RESIZE
+]);
+const AGENT_TO_RELAY_FRAME_TYPES = new Set([
+	RemoteFrameType.SESSION_CLOSE,
+	RemoteFrameType.SESSION_STATE,
+	RemoteFrameType.NAVIGATION,
+	RemoteFrameType.SCREENCAST_FRAME,
+	RemoteFrameType.TAKEOVER_GRANTED,
+	RemoteFrameType.TAKEOVER_DENIED,
+	RemoteFrameType.CONTROL_REVOKED,
+	RemoteFrameType.TERMINAL_DATA
+]);
+function isRemoteFrameType(value) {
+	return typeof value === "number" && VALID_FRAME_TYPES.has(value);
+}
+function isRelayToAgentFrameType(value) {
+	return typeof value === "number" && RELAY_TO_AGENT_FRAME_TYPES.has(value);
+}
+function isAgentToRelayFrameType(value) {
+	return typeof value === "number" && AGENT_TO_RELAY_FRAME_TYPES.has(value);
+}
 function isRemoteFrame(data) {
-	if (data.length < 5) return false;
-	const type = data[0];
-	return type >= MIN_FRAME_TYPE && type <= MAX_FRAME_TYPE;
+	return Buffer.isBuffer(data) && data.length >= 5 && data.length <= 10485760 && isRemoteFrameType(data[0]);
 }
 function encodeFrame(type, sessionId, payload) {
+	if (!isRemoteFrameType(type)) throw new TypeError("Remote frame type is invalid");
+	if (!Number.isInteger(sessionId) || sessionId < 0 || sessionId > 4294967295) throw new RangeError("Remote session ID must be an unsigned 32-bit integer");
+	if (payload !== void 0 && !Buffer.isBuffer(payload)) throw new TypeError("Remote frame payload must be a Buffer");
 	const body = payload ?? Buffer.alloc(0);
+	if (body.length > 10485755) throw new RangeError(`Remote frame exceeds the ${String(REMOTE_MAX_PAYLOAD)} byte limit`);
 	const buf = Buffer.allocUnsafe(5 + body.length);
 	buf.writeUInt8(type, 0);
-	buf.writeUInt32BE(sessionId >>> 0, 1);
+	buf.writeUInt32BE(sessionId, 1);
 	if (body.length > 0) body.copy(buf, 5);
 	return buf;
 }
 function decodeFrame(buf) {
+	if (!Buffer.isBuffer(buf)) throw new TypeError("Remote frame must be a Buffer");
 	if (buf.length < 5) throw new Error(`Remote frame too short: ${String(buf.length)} bytes`);
+	if (buf.length > 10485760) throw new RangeError(`Remote frame exceeds the ${String(REMOTE_MAX_PAYLOAD)} byte limit`);
+	const type = buf.readUInt8(0);
+	if (!isRemoteFrameType(type)) throw new Error(`Unknown remote frame type: ${String(type)}`);
 	return {
-		type: buf.readUInt8(0),
+		type,
 		sessionId: buf.readUInt32BE(1),
 		payload: buf.subarray(5)
 	};
 }
 function encodeJsonFrame(type, sessionId, obj) {
-	return encodeFrame(type, sessionId, Buffer.from(JSON.stringify(obj), "utf-8"));
+	if (obj === void 0 || typeof obj === "function" || typeof obj === "symbol") throw new TypeError("Remote JSON payload is not serializable");
+	const json = JSON.stringify(obj);
+	const payload = Buffer.from(json, "utf-8");
+	if (payload.length > 65536) throw new RangeError(`Remote JSON payload exceeds the ${String(REMOTE_MAX_JSON_PAYLOAD)} byte limit`);
+	return encodeFrame(type, sessionId, payload);
 }
-/** Best-effort JSON decode — returns null on a malformed payload so a single
-* corrupt frame can't crash the per-session handler. Callers assert the shape
-* (e.g. `decodeJson(p) as SessionOpenPayload | null`). */
+/** Best-effort bounded JSON decode. Shape-specific callers use the decoders below. */
 function decodeJson(payload) {
+	if (!Buffer.isBuffer(payload) || payload.length < 1 || payload.length > 65536) return null;
 	try {
 		return JSON.parse(payload.toString("utf-8"));
 	} catch {
@@ -103,7 +149,11 @@ function decodeJson(payload) {
 /** Encode a screencast frame: [metaLen:u16BE][meta JSON][raw JPEG]. The JPEG is
 * forwarded raw (already base64-decoded from CDP) to avoid base64 bloat. */
 function encodeScreencastFrame(sessionId, meta, jpeg) {
-	const metaJson = Buffer.from(JSON.stringify(meta), "utf-8");
+	const normalizedMeta = normalizeScreencastFrameMeta(meta);
+	if (normalizedMeta === null) throw new TypeError("Screencast metadata is invalid");
+	if (!isJpeg(jpeg)) throw new TypeError("Screencast content must be a non-empty JPEG image");
+	const metaJson = Buffer.from(JSON.stringify(normalizedMeta), "utf-8");
+	if (metaJson.length > 65535) throw new RangeError("Screencast metadata is too large");
 	const body = Buffer.allocUnsafe(2 + metaJson.length + jpeg.length);
 	body.writeUInt16BE(metaJson.length, 0);
 	metaJson.copy(body, 2);
@@ -111,30 +161,169 @@ function encodeScreencastFrame(sessionId, meta, jpeg) {
 	return encodeFrame(RemoteFrameType.SCREENCAST_FRAME, sessionId, body);
 }
 function decodeScreencastFrame(payload) {
-	if (payload.length < 2) return null;
+	if (!Buffer.isBuffer(payload) || payload.length < 2 || payload.length > 10485755) return null;
 	const metaLen = payload.readUInt16BE(0);
-	if (payload.length < 2 + metaLen) return null;
-	const meta = decodeJson(payload.subarray(2, 2 + metaLen));
-	if (!meta) return null;
+	if (metaLen < 1 || payload.length < 2 + metaLen) return null;
+	const meta = normalizeScreencastFrameMeta(decodeJson(payload.subarray(2, 2 + metaLen)));
+	const jpeg = payload.subarray(2 + metaLen);
+	if (meta === null || !isJpeg(jpeg)) return null;
 	return {
 		meta,
-		jpeg: payload.subarray(2 + metaLen)
+		jpeg
 	};
 }
-/** Maximum WS message size (must align across daemon plugin and relay). */
-const REMOTE_MAX_PAYLOAD = 10 * 1024 * 1024;
+function decodeSessionOpenPayload(payload) {
+	const value = decodeJson(payload);
+	if (!isRecord(value) || value.surface !== "browser" && value.surface !== "terminal") return null;
+	const surface = value.surface;
+	const width = optionalBoundedNumber(value.width, 1, 32768, true);
+	const height = optionalBoundedNumber(value.height, 1, 32768, true);
+	const dpr = optionalBoundedNumber(value.dpr, .1, 10, false);
+	const cols = optionalBoundedNumber(value.cols, 1, 1e3, true);
+	const rows = optionalBoundedNumber(value.rows, 1, 1e3, true);
+	if (width === false || height === false || dpr === false || cols === false || rows === false) return null;
+	if (surface === "browser" && (cols !== void 0 || rows !== void 0)) return null;
+	if (surface === "terminal" && (width !== void 0 || height !== void 0 || dpr !== void 0)) return null;
+	return compact({
+		surface,
+		width,
+		height,
+		dpr,
+		cols,
+		rows
+	});
+}
+function decodeScreencastAckPayload(payload) {
+	const value = decodeJson(payload);
+	return isRecord(value) && isUint32(value.frameSeq) ? { frameSeq: value.frameSeq } : null;
+}
+function decodeResizePayload(payload) {
+	const value = decodeJson(payload);
+	if (!isRecord(value)) return null;
+	if (!boundedNumber(value.width, 1, 32768, true) || !boundedNumber(value.height, 1, 32768, true)) return null;
+	const dpr = optionalBoundedNumber(value.dpr, .1, 10, false);
+	if (dpr === false) return null;
+	return compact({
+		width: value.width,
+		height: value.height,
+		dpr
+	});
+}
+function decodeMouseInputPayload(payload) {
+	const value = decodeJson(payload);
+	if (!isRecord(value)) return null;
+	const inputTypes = new Set([
+		"mousemoved",
+		"mousepressed",
+		"mousereleased"
+	]);
+	const buttons = optionalBoundedNumber(value.buttons, 0, 31, true);
+	const clickCount = optionalBoundedNumber(value.clickCount, 0, 10, true);
+	const modifiers = optionalBoundedNumber(value.modifiers, 0, 15, true);
+	const validButton = value.button === void 0 || typeof value.button === "string" && [
+		"none",
+		"left",
+		"middle",
+		"right"
+	].includes(value.button);
+	if (typeof value.type !== "string" || !inputTypes.has(value.type) || !boundedNumber(value.nx, 0, 1, false) || !boundedNumber(value.ny, 0, 1, false) || !validButton || buttons === false || clickCount === false || modifiers === false) return null;
+	return compact({
+		type: value.type,
+		nx: value.nx,
+		ny: value.ny,
+		button: value.button,
+		buttons,
+		clickCount,
+		modifiers
+	});
+}
+function decodeWheelInputPayload(payload) {
+	const value = decodeJson(payload);
+	if (!isRecord(value)) return null;
+	const modifiers = optionalBoundedNumber(value.modifiers, 0, 15, true);
+	if (!boundedNumber(value.nx, 0, 1, false) || !boundedNumber(value.ny, 0, 1, false) || !boundedNumber(value.deltaX, -1e6, 1e6, false) || !boundedNumber(value.deltaY, -1e6, 1e6, false) || modifiers === false) return null;
+	return compact({
+		nx: value.nx,
+		ny: value.ny,
+		deltaX: value.deltaX,
+		deltaY: value.deltaY,
+		modifiers
+	});
+}
+function decodeKeyInputPayload(payload) {
+	const value = decodeJson(payload);
+	if (!isRecord(value) || ![
+		"keydown",
+		"keyup",
+		"char"
+	].includes(String(value.type))) return null;
+	const key = optionalBoundedString(value.key, 256);
+	const code = optionalBoundedString(value.code, 256);
+	const text = optionalBoundedString(value.text, 4096);
+	const modifiers = optionalBoundedNumber(value.modifiers, 0, 15, true);
+	if (key === false || code === false || text === false || modifiers === false) return null;
+	return compact({
+		type: value.type,
+		key,
+		code,
+		text,
+		modifiers
+	});
+}
+function decodeTerminalResizePayload(payload) {
+	const value = decodeJson(payload);
+	if (!isRecord(value) || !boundedNumber(value.cols, 1, 1e3, true) || !boundedNumber(value.rows, 1, 1e3, true)) return null;
+	return {
+		cols: value.cols,
+		rows: value.rows
+	};
+}
+function normalizeScreencastFrameMeta(value) {
+	if (!isRecord(value)) return null;
+	if (!boundedNumber(value.deviceWidth, 1, 32768, false) || !boundedNumber(value.deviceHeight, 1, 32768, false) || !isUint32(value.frameSeq)) return null;
+	const offsetTop = optionalBoundedNumber(value.offsetTop, -1e6, 1e6, false);
+	const pageScaleFactor = optionalBoundedNumber(value.pageScaleFactor, .01, 100, false);
+	const scrollOffsetX = optionalBoundedNumber(value.scrollOffsetX, -1e7, 1e7, false);
+	const scrollOffsetY = optionalBoundedNumber(value.scrollOffsetY, -1e7, 1e7, false);
+	if (offsetTop === false || pageScaleFactor === false || scrollOffsetX === false || scrollOffsetY === false) return null;
+	return compact({
+		deviceWidth: value.deviceWidth,
+		deviceHeight: value.deviceHeight,
+		frameSeq: value.frameSeq,
+		offsetTop,
+		pageScaleFactor,
+		scrollOffsetX,
+		scrollOffsetY
+	});
+}
+function isJpeg(value) {
+	return Buffer.isBuffer(value) && value.length >= 3 && value[0] === 255 && value[1] === 216 && value[2] === 255;
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isUint32(value) {
+	return Number.isInteger(value) && typeof value === "number" && value >= 0 && value <= 4294967295;
+}
+function boundedNumber(value, min, max, integer) {
+	return typeof value === "number" && Number.isFinite(value) && (!integer || Number.isInteger(value)) && value >= min && value <= max;
+}
+function optionalBoundedNumber(value, min, max, integer) {
+	if (value === void 0) return void 0;
+	return boundedNumber(value, min, max, integer) ? value : false;
+}
+function optionalBoundedString(value, maxLength) {
+	if (value === void 0) return void 0;
+	return typeof value === "string" && value.length <= maxLength ? value : false;
+}
+function compact(value) {
+	return Object.fromEntries(Object.entries(value).filter(([, field]) => field !== void 0));
+}
 //#endregion
 //#region src/client.ts
 /**
-* RemoteServiceClient — runtime-agnostic outbound WS client to the Alfe remote
-* relay service. Brings up a persistent WebSocket, decodes binary frames and
-* hands them to a surface-agnostic `onFrame` callback, exposes `sendFrame` for
-* outbound frames, and reconnects with backoff.
-*
-* One client per agent. Multiple viewer attachments (browser + terminal) are
-* multiplexed by the relay over the single WS using `sessionId`.
-*
-* Reconnect + heartbeat logic mirrors `@alfe.ai/console-client`'s client.
+* Runtime-agnostic, generation-fenced WebSocket client for the Alfe remote
+* relay. One connection multiplexes every browser and terminal viewer session.
 */
 const RECONNECT_DELAYS = [
 	1e3,
@@ -145,6 +334,8 @@ const RECONNECT_DELAYS = [
 	3e4
 ];
 const HEARTBEAT_INTERVAL_MS = 3e4;
+const MAX_REMOTE_URL_LENGTH = 2048;
+const MAX_API_KEY_LENGTH = 16384;
 const defaultLogger = {
 	info: (msg) => {
 		console.log(`[remote-client] ${msg}`);
@@ -162,17 +353,49 @@ function wsDataToBuffer(data) {
 	if (Array.isArray(data)) return Buffer.concat(data);
 	return Buffer.from(data);
 }
+function validateOptions(options) {
+	if (typeof options.wsUrl !== "string" || options.wsUrl.length < 1 || options.wsUrl.length > MAX_REMOTE_URL_LENGTH) throw new TypeError("Remote relay URL must contain 1 to 2048 characters");
+	let url;
+	try {
+		url = new URL(options.wsUrl);
+	} catch {
+		throw new TypeError("Remote relay URL is invalid");
+	}
+	const loopback = isLoopbackHostname(url.hostname);
+	if (url.protocol !== "wss:" && !(url.protocol === "ws:" && loopback) || url.username || url.password || url.hash) throw new TypeError("Remote relay URL must use WSS without userinfo or fragments (WS is loopback-only)");
+	if (typeof options.apiKey !== "string" || options.apiKey.trim().length < 1 || options.apiKey !== options.apiKey.trim() || options.apiKey.length > MAX_API_KEY_LENGTH || /[\r\n]/u.test(options.apiKey)) throw new TypeError("Remote relay API key is invalid");
+	if (typeof options.onFrame !== "function") throw new TypeError("Remote frame callback is required");
+	if (options.onConnectionChange !== void 0 && typeof options.onConnectionChange !== "function") throw new TypeError("Remote connection callback must be a function");
+	return {
+		url,
+		endpointLabel: `${url.origin}${url.pathname}`
+	};
+}
+function isLoopbackHostname(hostname) {
+	const normalized = hostname.toLowerCase().replace(/^\[|\]$/gu, "");
+	if (normalized === "localhost" || normalized === "::1") return true;
+	return /^127\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/u.exec(normalized)?.slice(1).every((part) => Number(part) <= 255) ?? false;
+}
+function errorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
 var RemoteServiceClient = class {
 	ws = null;
-	stopped = false;
+	stopped = true;
 	connected = false;
+	generation = 0;
 	retryCount = 0;
 	retryTimer = null;
 	heartbeatTimer = null;
 	isAlive = false;
 	log;
+	relayUrl;
+	endpointLabel;
 	constructor(options) {
 		this.options = options;
+		const validated = validateOptions(options);
+		this.relayUrl = validated.url;
+		this.endpointLabel = validated.endpointLabel;
 		this.log = options.logger ?? defaultLogger;
 	}
 	get isConnected() {
@@ -180,110 +403,159 @@ var RemoteServiceClient = class {
 	}
 	/** Backpressure signal for the screencast pump — bytes queued but not flushed. */
 	get bufferedAmount() {
-		return this.ws?.bufferedAmount ?? 0;
+		return this.ws?.readyState === ws.default.OPEN ? this.ws.bufferedAmount : 0;
 	}
+	/** Start one connection lifecycle. Repeated starts in the same lifecycle are no-ops. */
 	start() {
+		if (!this.stopped) return;
 		this.log.debug("RemoteServiceClient starting...");
 		this.stopped = false;
-		this.doConnect();
+		this.retryCount = 0;
+		const generation = ++this.generation;
+		this.doConnect(generation);
 	}
+	/** Stop the current lifecycle and invalidate every callback owned by it. */
 	stop() {
+		if (this.stopped) return;
 		this.log.debug("RemoteServiceClient stopping...");
 		this.stopped = true;
-		if (this.retryTimer) {
-			clearTimeout(this.retryTimer);
-			this.retryTimer = null;
-		}
+		this.generation += 1;
+		this.clearRetry();
 		this.clearHeartbeat();
-		if (this.ws) {
+		const socket = this.ws;
+		this.ws = null;
+		this.setConnected(false);
+		if (socket) {
+			socket.removeAllListeners();
+			socket.on("error", () => {});
 			try {
-				this.ws.close(1e3, "client shutdown");
+				if (socket.readyState === ws.default.CONNECTING) socket.terminate();
+				else socket.close(1e3, "client shutdown");
 			} catch {}
-			this.ws = null;
 		}
-		this.connected = false;
 	}
-	/** Send a pre-encoded binary frame. No-op if the socket isn't open. */
+	/** Send a validated pre-encoded agent→relay frame when the socket is open. */
 	sendFrame(buf) {
-		if (this.ws?.readyState === ws.default.OPEN) this.ws.send(buf, { binary: true });
+		if (!isRemoteFrame(buf) || !isAgentToRelayFrameType(buf[0])) throw new TypeError("Outbound remote frame is malformed or invalid for the agent-to-relay direction");
+		const socket = this.ws;
+		if (socket?.readyState !== ws.default.OPEN) return;
+		try {
+			socket.send(buf, { binary: true }, (error) => {
+				if (error && this.isCurrent(socket, this.generation)) this.log.warn(`Failed to send a remote frame: ${error.message}`);
+			});
+		} catch (error) {
+			this.log.warn(`Failed to send a remote frame: ${errorMessage(error)}`);
+		}
 	}
-	doConnect() {
-		if (this.stopped) return;
-		this.log.info(`Connecting to remote relay at ${this.options.wsUrl}...`);
-		this.ws = new ws.default(this.options.wsUrl, {
-			headers: { authorization: `Bearer ${this.options.apiKey}` },
-			maxPayload: REMOTE_MAX_PAYLOAD,
-			handshakeTimeout: 1e4
-		});
-		this.ws.on("open", () => {
+	doConnect(generation) {
+		if (!this.isActive(generation) || this.ws !== null) return;
+		this.log.info(`Connecting to remote relay at ${this.endpointLabel}...`);
+		let socket;
+		try {
+			socket = new ws.default(this.relayUrl, {
+				headers: { authorization: `Bearer ${this.options.apiKey}` },
+				maxPayload: REMOTE_MAX_PAYLOAD,
+				handshakeTimeout: 1e4
+			});
+		} catch (error) {
+			this.log.error(`Could not create remote relay WebSocket: ${errorMessage(error)}`);
+			this.scheduleReconnect(generation);
+			return;
+		}
+		this.ws = socket;
+		socket.on("open", () => {
+			if (!this.isCurrent(socket, generation)) return;
 			this.log.info("Connected to remote relay");
-			this.connected = true;
 			this.retryCount = 0;
-			this.startHeartbeat();
-			this.options.onConnectionChange?.(true);
+			this.setConnected(true);
+			this.startHeartbeat(socket, generation);
 		});
-		this.ws.on("message", (data, isBinary) => {
+		socket.on("message", (data, isBinary) => {
+			if (!this.isCurrent(socket, generation)) return;
 			this.isAlive = true;
 			if (!isBinary) return;
 			const buf = wsDataToBuffer(data);
-			if (!isRemoteFrame(buf)) return;
+			if (!isRemoteFrame(buf) || !isRelayToAgentFrameType(buf[0])) return;
 			try {
-				this.options.onFrame(decodeFrame(buf));
-			} catch (err) {
-				this.log.warn(`Failed to handle remote frame: ${err.message}`);
+				Promise.resolve(this.options.onFrame(decodeFrame(buf))).catch((error) => {
+					this.log.warn(`Failed to handle remote frame: ${errorMessage(error)}`);
+				});
+			} catch (error) {
+				this.log.warn(`Failed to handle remote frame: ${errorMessage(error)}`);
 			}
 		});
-		this.ws.on("ping", () => {
+		socket.on("ping", () => {
+			if (!this.isCurrent(socket, generation)) return;
 			this.isAlive = true;
-			this.ws?.pong();
 		});
-		this.ws.on("pong", () => {
-			this.isAlive = true;
+		socket.on("pong", () => {
+			if (this.isCurrent(socket, generation)) this.isAlive = true;
 		});
-		this.ws.on("close", (code, reason) => {
+		socket.on("close", (code, reason) => {
+			if (!this.isCurrent(socket, generation)) return;
+			this.ws = null;
 			this.clearHeartbeat();
 			this.log.warn(`Disconnected from remote relay (${String(code)}: ${reason.toString()})`);
-			this.connected = false;
-			this.options.onConnectionChange?.(false);
-			this.scheduleReconnect();
+			this.setConnected(false);
+			this.scheduleReconnect(generation);
 		});
-		this.ws.on("error", (err) => {
-			this.log.error(`Remote relay WS error: ${err.message}`);
+		socket.on("error", (error) => {
+			if (this.isCurrent(socket, generation)) this.log.error(`Remote relay WS error: ${error.message}`);
 		});
 	}
-	scheduleReconnect() {
-		if (this.stopped) return;
-		const delay = RECONNECT_DELAYS[Math.min(this.retryCount, RECONNECT_DELAYS.length - 1)];
+	scheduleReconnect(generation) {
+		if (!this.isActive(generation) || this.retryTimer !== null) return;
+		const delay = RECONNECT_DELAYS[Math.min(this.retryCount, RECONNECT_DELAYS.length - 1)] ?? 3e4;
 		this.retryCount += 1;
 		this.log.info(`Reconnecting to remote relay in ${String(delay)}ms (attempt ${String(this.retryCount)})...`);
-		this.retryTimer = setTimeout(() => {
-			this.retryTimer = null;
-			this.doConnect();
+		const timer = setTimeout(() => {
+			if (this.retryTimer === timer) this.retryTimer = null;
+			this.doConnect(generation);
 		}, delay);
+		timer.unref();
+		this.retryTimer = timer;
 	}
-	/**
-	* Detect a silently-dropped connection. Each tick: if no inbound liveness
-	* (pong/ping/message) was seen since the last tick, force-close so the
-	* `close` handler reconnects; otherwise send a fresh ping and arm the next.
-	*/
-	startHeartbeat() {
+	startHeartbeat(socket, generation) {
 		this.clearHeartbeat();
 		this.isAlive = true;
 		const timer = setInterval(() => {
-			if (this.ws?.readyState !== ws.default.OPEN) return;
+			if (!this.isCurrent(socket, generation) || socket.readyState !== ws.default.OPEN) return;
 			if (!this.isAlive) {
 				this.log.warn("Remote relay heartbeat timed out — terminating stale connection");
-				this.ws.terminate();
+				socket.terminate();
 				return;
 			}
 			this.isAlive = false;
 			try {
-				this.ws.ping();
+				socket.ping();
 			} catch {}
 		}, HEARTBEAT_INTERVAL_MS);
 		timer.unref();
 		this.heartbeatTimer = timer;
 	}
+	setConnected(connected) {
+		if (this.connected === connected) return;
+		this.connected = connected;
+		try {
+			Promise.resolve(this.options.onConnectionChange?.(connected)).catch((error) => {
+				this.log.warn(`Remote connection callback failed: ${errorMessage(error)}`);
+			});
+		} catch (error) {
+			this.log.warn(`Remote connection callback failed: ${errorMessage(error)}`);
+		}
+	}
+	isActive(generation) {
+		return !this.stopped && this.generation === generation;
+	}
+	isCurrent(socket, generation) {
+		return this.isActive(generation) && this.ws === socket;
+	}
+	clearRetry() {
+		if (this.retryTimer) {
+			clearTimeout(this.retryTimer);
+			this.retryTimer = null;
+		}
+	}
 	clearHeartbeat() {
 		if (this.heartbeatTimer) {
 			clearInterval(this.heartbeatTimer);
@@ -309,12 +581,29 @@ var TurnController = class {
 	/**
 	* Resolve once the agent is (again) allowed to drive. Resolves immediately if
 	* the agent already holds the token; otherwise parks until `releaseHuman()`.
-	* Every automation op awaits this before touching the page.
+	* Every automation op awaits this before touching the page. Cancellation
+	* removes only this waiter and never changes the current human owner.
 	*/
-	acquireAgent() {
+	acquireAgent(signal) {
+		if (signal?.aborted) return Promise.reject(/* @__PURE__ */ new Error("Agent turn acquisition interrupted"));
 		if (this.owner === "agent") return Promise.resolve();
-		return new Promise((resolve) => {
-			this.waiters.push(resolve);
+		return new Promise((resolve, reject) => {
+			const cleanup = () => {
+				const index = this.waiters.indexOf(resume);
+				if (index !== -1) this.waiters.splice(index, 1);
+				signal?.removeEventListener("abort", onAbort);
+			};
+			const resume = () => {
+				cleanup();
+				resolve();
+			};
+			const onAbort = () => {
+				cleanup();
+				reject(/* @__PURE__ */ new Error("Agent turn acquisition interrupted"));
+			};
+			this.waiters.push(resume);
+			signal?.addEventListener("abort", onAbort, { once: true });
+			if (signal?.aborted) onAbort();
 		});
 	}
 	/**
@@ -343,14 +632,25 @@ var TurnController = class {
 };
 //#endregion
 exports.REMOTE_HEADER_SIZE = REMOTE_HEADER_SIZE;
+exports.REMOTE_MAX_JSON_PAYLOAD = REMOTE_MAX_JSON_PAYLOAD;
 exports.REMOTE_MAX_PAYLOAD = REMOTE_MAX_PAYLOAD;
 exports.RemoteFrameType = RemoteFrameType;
 exports.RemoteServiceClient = RemoteServiceClient;
 exports.TurnController = TurnController;
 exports.decodeFrame = decodeFrame;
 exports.decodeJson = decodeJson;
+exports.decodeKeyInputPayload = decodeKeyInputPayload;
+exports.decodeMouseInputPayload = decodeMouseInputPayload;
+exports.decodeResizePayload = decodeResizePayload;
+exports.decodeScreencastAckPayload = decodeScreencastAckPayload;
 exports.decodeScreencastFrame = decodeScreencastFrame;
+exports.decodeSessionOpenPayload = decodeSessionOpenPayload;
+exports.decodeTerminalResizePayload = decodeTerminalResizePayload;
+exports.decodeWheelInputPayload = decodeWheelInputPayload;
 exports.encodeFrame = encodeFrame;
 exports.encodeJsonFrame = encodeJsonFrame;
 exports.encodeScreencastFrame = encodeScreencastFrame;
+exports.isAgentToRelayFrameType = isAgentToRelayFrameType;
+exports.isRelayToAgentFrameType = isRelayToAgentFrameType;
 exports.isRemoteFrame = isRemoteFrame;
+exports.isRemoteFrameType = isRemoteFrameType;