@alfe.ai/remote 0.0.0

package/dist/index.cjs

@@ -0,0 +1,356 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+//#endregion
+let ws = require("ws");
+ws = __toESM(ws);
+//#region src/remote-protocol.ts
+/**
+* Remote-relay framing protocol — multiplexes interactive surfaces (browser
+* screencast + input, terminal PTY) over the single outbound WS between the
+* agent plugin and the Alfe remote relay service. The relay routes frames by
+* `sessionId` (bytes 1-4) without parsing payloads.
+*
+* 5-byte header (WS preserves order, so no sequence numbers):
+*   Byte 0     Frame type (uint8)
+*   Bytes 1-4  Session ID (uint32, big-endian) — one viewer attachment
+*   Bytes 5+   Payload — JSON (utf-8) for control/input, raw bytes for media
+*
+* Direction is enforced at the relay:
+*   • plugin → viewer: SESSION_STATE, NAVIGATION, SCREENCAST_FRAME,
+*     TAKEOVER_GRANTED/DENIED, CONTROL_REVOKED, TERMINAL_DATA
+*   • 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`.
+*/
+const REMOTE_HEADER_SIZE = 5;
+const RemoteFrameType = {
+	SESSION_OPEN: 1,
+	SESSION_CLOSE: 2,
+	SESSION_STATE: 3,
+	NAVIGATION: 4,
+	SCREENCAST_FRAME: 16,
+	SCREENCAST_ACK: 17,
+	INPUT_MOUSE: 32,
+	INPUT_WHEEL: 33,
+	INPUT_KEY: 34,
+	RESIZE: 35,
+	TAKEOVER_REQUEST: 48,
+	TAKEOVER_GRANTED: 49,
+	TAKEOVER_DENIED: 50,
+	RELEASE_CONTROL: 51,
+	CONTROL_REVOKED: 52,
+	TERMINAL_DATA: 64,
+	TERMINAL_INPUT: 65,
+	TERMINAL_RESIZE: 66
+};
+const MIN_FRAME_TYPE = RemoteFrameType.SESSION_OPEN;
+const MAX_FRAME_TYPE = RemoteFrameType.TERMINAL_RESIZE;
+function isRemoteFrame(data) {
+	if (data.length < 5) return false;
+	const type = data[0];
+	return type >= MIN_FRAME_TYPE && type <= MAX_FRAME_TYPE;
+}
+function encodeFrame(type, sessionId, payload) {
+	const body = payload ?? Buffer.alloc(0);
+	const buf = Buffer.allocUnsafe(5 + body.length);
+	buf.writeUInt8(type, 0);
+	buf.writeUInt32BE(sessionId >>> 0, 1);
+	if (body.length > 0) body.copy(buf, 5);
+	return buf;
+}
+function decodeFrame(buf) {
+	if (buf.length < 5) throw new Error(`Remote frame too short: ${String(buf.length)} bytes`);
+	return {
+		type: buf.readUInt8(0),
+		sessionId: buf.readUInt32BE(1),
+		payload: buf.subarray(5)
+	};
+}
+function encodeJsonFrame(type, sessionId, obj) {
+	return encodeFrame(type, sessionId, Buffer.from(JSON.stringify(obj), "utf-8"));
+}
+/** 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`). */
+function decodeJson(payload) {
+	try {
+		return JSON.parse(payload.toString("utf-8"));
+	} catch {
+		return null;
+	}
+}
+/** 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 body = Buffer.allocUnsafe(2 + metaJson.length + jpeg.length);
+	body.writeUInt16BE(metaJson.length, 0);
+	metaJson.copy(body, 2);
+	jpeg.copy(body, 2 + metaJson.length);
+	return encodeFrame(RemoteFrameType.SCREENCAST_FRAME, sessionId, body);
+}
+function decodeScreencastFrame(payload) {
+	if (payload.length < 2) 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;
+	return {
+		meta,
+		jpeg: payload.subarray(2 + metaLen)
+	};
+}
+/** Maximum WS message size (must align across daemon plugin and relay). */
+const REMOTE_MAX_PAYLOAD = 10 * 1024 * 1024;
+//#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.
+*/
+const RECONNECT_DELAYS = [
+	1e3,
+	2e3,
+	4e3,
+	8e3,
+	16e3,
+	3e4
+];
+const HEARTBEAT_INTERVAL_MS = 3e4;
+const defaultLogger = {
+	info: (msg) => {
+		console.log(`[remote-client] ${msg}`);
+	},
+	warn: (msg) => {
+		console.warn(`[remote-client] ${msg}`);
+	},
+	error: (msg) => {
+		console.error(`[remote-client] ${msg}`);
+	},
+	debug: () => {}
+};
+function wsDataToBuffer(data) {
+	if (Buffer.isBuffer(data)) return data;
+	if (Array.isArray(data)) return Buffer.concat(data);
+	return Buffer.from(data);
+}
+var RemoteServiceClient = class {
+	ws = null;
+	stopped = false;
+	connected = false;
+	retryCount = 0;
+	retryTimer = null;
+	heartbeatTimer = null;
+	isAlive = false;
+	log;
+	constructor(options) {
+		this.options = options;
+		this.log = options.logger ?? defaultLogger;
+	}
+	get isConnected() {
+		return this.connected && this.ws?.readyState === ws.default.OPEN;
+	}
+	/** Backpressure signal for the screencast pump — bytes queued but not flushed. */
+	get bufferedAmount() {
+		return this.ws?.bufferedAmount ?? 0;
+	}
+	start() {
+		this.log.debug("RemoteServiceClient starting...");
+		this.stopped = false;
+		this.doConnect();
+	}
+	stop() {
+		this.log.debug("RemoteServiceClient stopping...");
+		this.stopped = true;
+		if (this.retryTimer) {
+			clearTimeout(this.retryTimer);
+			this.retryTimer = null;
+		}
+		this.clearHeartbeat();
+		if (this.ws) {
+			try {
+				this.ws.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. */
+	sendFrame(buf) {
+		if (this.ws?.readyState === ws.default.OPEN) this.ws.send(buf, { binary: true });
+	}
+	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", () => {
+			this.log.info("Connected to remote relay");
+			this.connected = true;
+			this.retryCount = 0;
+			this.startHeartbeat();
+			this.options.onConnectionChange?.(true);
+		});
+		this.ws.on("message", (data, isBinary) => {
+			this.isAlive = true;
+			if (!isBinary) return;
+			const buf = wsDataToBuffer(data);
+			if (!isRemoteFrame(buf)) return;
+			try {
+				this.options.onFrame(decodeFrame(buf));
+			} catch (err) {
+				this.log.warn(`Failed to handle remote frame: ${err.message}`);
+			}
+		});
+		this.ws.on("ping", () => {
+			this.isAlive = true;
+			this.ws?.pong();
+		});
+		this.ws.on("pong", () => {
+			this.isAlive = true;
+		});
+		this.ws.on("close", (code, reason) => {
+			this.clearHeartbeat();
+			this.log.warn(`Disconnected from remote relay (${String(code)}: ${reason.toString()})`);
+			this.connected = false;
+			this.options.onConnectionChange?.(false);
+			this.scheduleReconnect();
+		});
+		this.ws.on("error", (err) => {
+			this.log.error(`Remote relay WS error: ${err.message}`);
+		});
+	}
+	scheduleReconnect() {
+		if (this.stopped) return;
+		const delay = RECONNECT_DELAYS[Math.min(this.retryCount, RECONNECT_DELAYS.length - 1)];
+		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();
+		}, delay);
+	}
+	/**
+	* 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() {
+		this.clearHeartbeat();
+		this.isAlive = true;
+		const timer = setInterval(() => {
+			if (this.ws?.readyState !== ws.default.OPEN) return;
+			if (!this.isAlive) {
+				this.log.warn("Remote relay heartbeat timed out — terminating stale connection");
+				this.ws.terminate();
+				return;
+			}
+			this.isAlive = false;
+			try {
+				this.ws.ping();
+			} catch {}
+		}, HEARTBEAT_INTERVAL_MS);
+		timer.unref();
+		this.heartbeatTimer = timer;
+	}
+	clearHeartbeat() {
+		if (this.heartbeatTimer) {
+			clearInterval(this.heartbeatTimer);
+			this.heartbeatTimer = null;
+		}
+	}
+};
+//#endregion
+//#region src/turn-controller.ts
+var TurnController = class {
+	owner = "agent";
+	waiters = [];
+	onOwnerChange;
+	constructor(options = {}) {
+		this.onOwnerChange = options.onOwnerChange;
+	}
+	get currentOwner() {
+		return this.owner;
+	}
+	get humanInControl() {
+		return this.owner === "human";
+	}
+	/**
+	* 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.
+	*/
+	acquireAgent() {
+		if (this.owner === "agent") return Promise.resolve();
+		return new Promise((resolve) => {
+			this.waiters.push(resolve);
+		});
+	}
+	/**
+	* Grant control to a human. Succeeds unless a human already holds it (single
+	* controller). "Human request always wins over the agent" — the agent parks
+	* at its next `acquireAgent()`.
+	*/
+	grantHuman() {
+		if (this.owner === "human") return false;
+		this.setOwner("human");
+		return true;
+	}
+	/** Return control to the agent and drain any parked automation ops. */
+	releaseHuman() {
+		if (this.owner === "agent") return;
+		this.setOwner("agent");
+		const parked = this.waiters;
+		this.waiters = [];
+		for (const resolve of parked) resolve();
+	}
+	setOwner(owner) {
+		if (this.owner === owner) return;
+		this.owner = owner;
+		this.onOwnerChange?.(owner);
+	}
+};
+//#endregion
+exports.REMOTE_HEADER_SIZE = REMOTE_HEADER_SIZE;
+exports.REMOTE_MAX_PAYLOAD = REMOTE_MAX_PAYLOAD;
+exports.RemoteFrameType = RemoteFrameType;
+exports.RemoteServiceClient = RemoteServiceClient;
+exports.TurnController = TurnController;
+exports.decodeFrame = decodeFrame;
+exports.decodeJson = decodeJson;
+exports.decodeScreencastFrame = decodeScreencastFrame;
+exports.encodeFrame = encodeFrame;
+exports.encodeJsonFrame = encodeJsonFrame;
+exports.encodeScreencastFrame = encodeScreencastFrame;
+exports.isRemoteFrame = isRemoteFrame;

package/dist/index.d.cts

@@ -0,0 +1,243 @@
+//#region src/remote-protocol.d.ts
+/**
+ * Remote-relay framing protocol — multiplexes interactive surfaces (browser
+ * screencast + input, terminal PTY) over the single outbound WS between the
+ * agent plugin and the Alfe remote relay service. The relay routes frames by
+ * `sessionId` (bytes 1-4) without parsing payloads.
+ *
+ * 5-byte header (WS preserves order, so no sequence numbers):
+ *   Byte 0     Frame type (uint8)
+ *   Bytes 1-4  Session ID (uint32, big-endian) — one viewer attachment
+ *   Bytes 5+   Payload — JSON (utf-8) for control/input, raw bytes for media
+ *
+ * Direction is enforced at the relay:
+ *   • plugin → viewer: SESSION_STATE, NAVIGATION, SCREENCAST_FRAME,
+ *     TAKEOVER_GRANTED/DENIED, CONTROL_REVOKED, TERMINAL_DATA
+ *   • 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`.
+ */
+declare const REMOTE_HEADER_SIZE = 5;
+declare const RemoteFrameType: {
+  /** viewer→plugin: a viewer attached. Payload: SessionOpenPayload. */
+  readonly SESSION_OPEN: 1;
+  /** either direction: a viewer detached / session torn down. */
+  readonly SESSION_CLOSE: 2;
+  /** plugin→viewer: current surface state. Payload: SessionStatePayload. */
+  readonly SESSION_STATE: 3;
+  /** plugin→viewer (browser): the page navigated. Payload: { url }. */
+  readonly NAVIGATION: 4;
+  /** plugin→viewer: [metaLen:u16BE][meta JSON][raw JPEG]. */
+  readonly SCREENCAST_FRAME: 16;
+  /** viewer→plugin: { frameSeq } — drives ack-gated backpressure. */
+  readonly SCREENCAST_ACK: 17;
+  readonly INPUT_MOUSE: 32;
+  readonly INPUT_WHEEL: 33;
+  readonly INPUT_KEY: 34;
+  /** viewer→plugin: { width, height, dpr }. */
+  readonly RESIZE: 35;
+  readonly TAKEOVER_REQUEST: 48;
+  readonly TAKEOVER_GRANTED: 49;
+  readonly TAKEOVER_DENIED: 50;
+  readonly RELEASE_CONTROL: 51;
+  readonly CONTROL_REVOKED: 52;
+  /** plugin→viewer: raw PTY output bytes. */
+  readonly TERMINAL_DATA: 64;
+  /** viewer→plugin: raw keystroke bytes. */
+  readonly TERMINAL_INPUT: 65;
+  /** viewer→plugin: { cols, rows }. */
+  readonly TERMINAL_RESIZE: 66;
+};
+type RemoteFrameType = (typeof RemoteFrameType)[keyof typeof RemoteFrameType];
+type RemoteSurface = "browser" | "terminal";
+interface RemoteFrame {
+  type: RemoteFrameType;
+  sessionId: number;
+  payload: Buffer;
+}
+interface SessionOpenPayload {
+  surface: RemoteSurface;
+  /** Browser: initial viewport in device pixels. */
+  width?: number;
+  height?: number;
+  dpr?: number;
+  /** Terminal: initial PTY dimensions. */
+  cols?: number;
+  rows?: number;
+}
+interface SessionStatePayload {
+  surface: RemoteSurface;
+  url?: string;
+  title?: string;
+  loading?: boolean;
+  /** Who currently holds the write token (browser only). */
+  controller?: "agent" | "human" | "none";
+}
+interface ScreencastFrameMeta {
+  deviceWidth: number;
+  deviceHeight: number;
+  frameSeq: number;
+  offsetTop?: number;
+  pageScaleFactor?: number;
+  scrollOffsetX?: number;
+  scrollOffsetY?: number;
+}
+interface MouseInputPayload {
+  type: "mousemoved" | "mousepressed" | "mousereleased";
+  /** Normalized canvas coordinates in [0,1]. */
+  nx: number;
+  ny: number;
+  button?: "none" | "left" | "middle" | "right";
+  buttons?: number;
+  clickCount?: number;
+  modifiers?: number;
+}
+interface WheelInputPayload {
+  nx: number;
+  ny: number;
+  deltaX: number;
+  deltaY: number;
+  modifiers?: number;
+}
+interface KeyInputPayload {
+  type: "keydown" | "keyup" | "char";
+  key?: string;
+  code?: string;
+  text?: string;
+  modifiers?: number;
+}
+interface ResizePayload {
+  width: number;
+  height: number;
+  dpr?: number;
+}
+interface TerminalResizePayload {
+  cols: number;
+  rows: number;
+}
+declare function isRemoteFrame(data: Buffer): boolean;
+declare function encodeFrame(type: RemoteFrameType, sessionId: number, payload?: Buffer): Buffer;
+declare function decodeFrame(buf: Buffer): RemoteFrame;
+declare function encodeJsonFrame(type: RemoteFrameType, sessionId: number, obj: unknown): Buffer;
+/** 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`). */
+declare function decodeJson(payload: Buffer): unknown;
+/** Encode a screencast frame: [metaLen:u16BE][meta JSON][raw JPEG]. The JPEG is
+ * forwarded raw (already base64-decoded from CDP) to avoid base64 bloat. */
+declare function encodeScreencastFrame(sessionId: number, meta: ScreencastFrameMeta, jpeg: Buffer): Buffer;
+declare function decodeScreencastFrame(payload: Buffer): {
+  meta: ScreencastFrameMeta;
+  jpeg: Buffer;
+} | null;
+/** Maximum WS message size (must align across daemon plugin and relay). */
+declare const REMOTE_MAX_PAYLOAD: number;
+//#endregion
+//#region src/surface.d.ts
+interface SurfaceHandler {
+  /** Which surface this handler serves. */
+  readonly surface: RemoteSurface;
+  /** A viewer attached — open the surface for this session. */
+  openSession(sessionId: number, open: SessionOpenPayload): void | Promise<void>;
+  /** A subsequent frame for one of this handler's sessions (not SESSION_OPEN). */
+  handleFrame(frame: RemoteFrame): void;
+  /** The viewer detached — tear down this session's resources. */
+  closeSession(sessionId: number): void;
+}
+//#endregion
+//#region src/types.d.ts
+interface Logger {
+  info(msg: string, ...args: unknown[]): void;
+  warn(msg: string, ...args: unknown[]): void;
+  error(msg: string, ...args: unknown[]): void;
+  debug(msg: string, ...args: unknown[]): void;
+}
+interface RemoteServiceClientOptions {
+  /** Relay WebSocket URL (e.g. wss://remote.dev.alfe.ai/ws). */
+  wsUrl: string;
+  /** Agent API key for Bearer auth on the WS upgrade. */
+  apiKey: string;
+  /**
+   * Handler for every well-formed inbound frame from the relay. The plugin
+   * dispatches by `frame.sessionId` to the owning surface handler. Kept on the
+   * transport as a single callback so this package stays surface-agnostic.
+   */
+  onFrame: (frame: RemoteFrame) => void;
+  /** Called when the WS connection state changes. */
+  onConnectionChange?: (connected: boolean) => void;
+  /** Optional logger (defaults to console). */
+  logger?: Logger;
+}
+//#endregion
+//#region src/client.d.ts
+declare class RemoteServiceClient {
+  private readonly options;
+  private ws;
+  private stopped;
+  private connected;
+  private retryCount;
+  private retryTimer;
+  private heartbeatTimer;
+  private isAlive;
+  private readonly log;
+  constructor(options: RemoteServiceClientOptions);
+  get isConnected(): boolean;
+  /** Backpressure signal for the screencast pump — bytes queued but not flushed. */
+  get bufferedAmount(): number;
+  start(): void;
+  stop(): void;
+  /** Send a pre-encoded binary frame. No-op if the socket isn't open. */
+  sendFrame(buf: Buffer): void;
+  private doConnect;
+  private scheduleReconnect;
+  /**
+   * 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.
+   */
+  private startHeartbeat;
+  private clearHeartbeat;
+}
+//#endregion
+//#region src/turn-controller.d.ts
+/**
+ * TurnController — the write-mutex between agent automation and a human during
+ * a browser co-browse handoff. The plugin owns the single CDP session, so this
+ * lives plugin-side; the relay only forwards the control frames.
+ *
+ * Only *writes* are gated — screencast reads always flow so the human sees the
+ * live page regardless of who holds the token. Agent automation ops call
+ * `acquireAgent()` and park while the human is in control; the human's input is
+ * injected only while `owner === 'human'`.
+ */
+type TurnOwner = "agent" | "human";
+interface TurnControllerOptions {
+  /** Fired whenever ownership changes, so the plugin can emit SESSION_STATE. */
+  onOwnerChange?: (owner: TurnOwner) => void;
+}
+declare class TurnController {
+  private owner;
+  private waiters;
+  private readonly onOwnerChange?;
+  constructor(options?: TurnControllerOptions);
+  get currentOwner(): TurnOwner;
+  get humanInControl(): boolean;
+  /**
+   * 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.
+   */
+  acquireAgent(): Promise<void>;
+  /**
+   * Grant control to a human. Succeeds unless a human already holds it (single
+   * controller). "Human request always wins over the agent" — the agent parks
+   * at its next `acquireAgent()`.
+   */
+  grantHuman(): boolean;
+  /** Return control to the agent and drain any parked automation ops. */
+  releaseHuman(): void;
+  private setOwner;
+}
+//#endregion
+export { KeyInputPayload, type Logger, MouseInputPayload, REMOTE_HEADER_SIZE, REMOTE_MAX_PAYLOAD, RemoteFrame, RemoteFrameType, RemoteServiceClient, type RemoteServiceClientOptions, RemoteSurface, ResizePayload, ScreencastFrameMeta, SessionOpenPayload, SessionStatePayload, type SurfaceHandler, TerminalResizePayload, TurnController, type TurnControllerOptions, type TurnOwner, WheelInputPayload, decodeFrame, decodeJson, decodeScreencastFrame, encodeFrame, encodeJsonFrame, encodeScreencastFrame, isRemoteFrame };

package/dist/index.d.ts

@@ -0,0 +1,243 @@
+//#region src/remote-protocol.d.ts
+/**
+ * Remote-relay framing protocol — multiplexes interactive surfaces (browser
+ * screencast + input, terminal PTY) over the single outbound WS between the
+ * agent plugin and the Alfe remote relay service. The relay routes frames by
+ * `sessionId` (bytes 1-4) without parsing payloads.
+ *
+ * 5-byte header (WS preserves order, so no sequence numbers):
+ *   Byte 0     Frame type (uint8)
+ *   Bytes 1-4  Session ID (uint32, big-endian) — one viewer attachment
+ *   Bytes 5+   Payload — JSON (utf-8) for control/input, raw bytes for media
+ *
+ * Direction is enforced at the relay:
+ *   • plugin → viewer: SESSION_STATE, NAVIGATION, SCREENCAST_FRAME,
+ *     TAKEOVER_GRANTED/DENIED, CONTROL_REVOKED, TERMINAL_DATA
+ *   • 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`.
+ */
+declare const REMOTE_HEADER_SIZE = 5;
+declare const RemoteFrameType: {
+  /** viewer→plugin: a viewer attached. Payload: SessionOpenPayload. */
+  readonly SESSION_OPEN: 1;
+  /** either direction: a viewer detached / session torn down. */
+  readonly SESSION_CLOSE: 2;
+  /** plugin→viewer: current surface state. Payload: SessionStatePayload. */
+  readonly SESSION_STATE: 3;
+  /** plugin→viewer (browser): the page navigated. Payload: { url }. */
+  readonly NAVIGATION: 4;
+  /** plugin→viewer: [metaLen:u16BE][meta JSON][raw JPEG]. */
+  readonly SCREENCAST_FRAME: 16;
+  /** viewer→plugin: { frameSeq } — drives ack-gated backpressure. */
+  readonly SCREENCAST_ACK: 17;
+  readonly INPUT_MOUSE: 32;
+  readonly INPUT_WHEEL: 33;
+  readonly INPUT_KEY: 34;
+  /** viewer→plugin: { width, height, dpr }. */
+  readonly RESIZE: 35;
+  readonly TAKEOVER_REQUEST: 48;
+  readonly TAKEOVER_GRANTED: 49;
+  readonly TAKEOVER_DENIED: 50;
+  readonly RELEASE_CONTROL: 51;
+  readonly CONTROL_REVOKED: 52;
+  /** plugin→viewer: raw PTY output bytes. */
+  readonly TERMINAL_DATA: 64;
+  /** viewer→plugin: raw keystroke bytes. */
+  readonly TERMINAL_INPUT: 65;
+  /** viewer→plugin: { cols, rows }. */
+  readonly TERMINAL_RESIZE: 66;
+};
+type RemoteFrameType = (typeof RemoteFrameType)[keyof typeof RemoteFrameType];
+type RemoteSurface = "browser" | "terminal";
+interface RemoteFrame {
+  type: RemoteFrameType;
+  sessionId: number;
+  payload: Buffer;
+}
+interface SessionOpenPayload {
+  surface: RemoteSurface;
+  /** Browser: initial viewport in device pixels. */
+  width?: number;
+  height?: number;
+  dpr?: number;
+  /** Terminal: initial PTY dimensions. */
+  cols?: number;
+  rows?: number;
+}
+interface SessionStatePayload {
+  surface: RemoteSurface;
+  url?: string;
+  title?: string;
+  loading?: boolean;
+  /** Who currently holds the write token (browser only). */
+  controller?: "agent" | "human" | "none";
+}
+interface ScreencastFrameMeta {
+  deviceWidth: number;
+  deviceHeight: number;
+  frameSeq: number;
+  offsetTop?: number;
+  pageScaleFactor?: number;
+  scrollOffsetX?: number;
+  scrollOffsetY?: number;
+}
+interface MouseInputPayload {
+  type: "mousemoved" | "mousepressed" | "mousereleased";
+  /** Normalized canvas coordinates in [0,1]. */
+  nx: number;
+  ny: number;
+  button?: "none" | "left" | "middle" | "right";
+  buttons?: number;
+  clickCount?: number;
+  modifiers?: number;
+}
+interface WheelInputPayload {
+  nx: number;
+  ny: number;
+  deltaX: number;
+  deltaY: number;
+  modifiers?: number;
+}
+interface KeyInputPayload {
+  type: "keydown" | "keyup" | "char";
+  key?: string;
+  code?: string;
+  text?: string;
+  modifiers?: number;
+}
+interface ResizePayload {
+  width: number;
+  height: number;
+  dpr?: number;
+}
+interface TerminalResizePayload {
+  cols: number;
+  rows: number;
+}
+declare function isRemoteFrame(data: Buffer): boolean;
+declare function encodeFrame(type: RemoteFrameType, sessionId: number, payload?: Buffer): Buffer;
+declare function decodeFrame(buf: Buffer): RemoteFrame;
+declare function encodeJsonFrame(type: RemoteFrameType, sessionId: number, obj: unknown): Buffer;
+/** 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`). */
+declare function decodeJson(payload: Buffer): unknown;
+/** Encode a screencast frame: [metaLen:u16BE][meta JSON][raw JPEG]. The JPEG is
+ * forwarded raw (already base64-decoded from CDP) to avoid base64 bloat. */
+declare function encodeScreencastFrame(sessionId: number, meta: ScreencastFrameMeta, jpeg: Buffer): Buffer;
+declare function decodeScreencastFrame(payload: Buffer): {
+  meta: ScreencastFrameMeta;
+  jpeg: Buffer;
+} | null;
+/** Maximum WS message size (must align across daemon plugin and relay). */
+declare const REMOTE_MAX_PAYLOAD: number;
+//#endregion
+//#region src/surface.d.ts
+interface SurfaceHandler {
+  /** Which surface this handler serves. */
+  readonly surface: RemoteSurface;
+  /** A viewer attached — open the surface for this session. */
+  openSession(sessionId: number, open: SessionOpenPayload): void | Promise<void>;
+  /** A subsequent frame for one of this handler's sessions (not SESSION_OPEN). */
+  handleFrame(frame: RemoteFrame): void;
+  /** The viewer detached — tear down this session's resources. */
+  closeSession(sessionId: number): void;
+}
+//#endregion
+//#region src/types.d.ts
+interface Logger {
+  info(msg: string, ...args: unknown[]): void;
+  warn(msg: string, ...args: unknown[]): void;
+  error(msg: string, ...args: unknown[]): void;
+  debug(msg: string, ...args: unknown[]): void;
+}
+interface RemoteServiceClientOptions {
+  /** Relay WebSocket URL (e.g. wss://remote.dev.alfe.ai/ws). */
+  wsUrl: string;
+  /** Agent API key for Bearer auth on the WS upgrade. */
+  apiKey: string;
+  /**
+   * Handler for every well-formed inbound frame from the relay. The plugin
+   * dispatches by `frame.sessionId` to the owning surface handler. Kept on the
+   * transport as a single callback so this package stays surface-agnostic.
+   */
+  onFrame: (frame: RemoteFrame) => void;
+  /** Called when the WS connection state changes. */
+  onConnectionChange?: (connected: boolean) => void;
+  /** Optional logger (defaults to console). */
+  logger?: Logger;
+}
+//#endregion
+//#region src/client.d.ts
+declare class RemoteServiceClient {
+  private readonly options;
+  private ws;
+  private stopped;
+  private connected;
+  private retryCount;
+  private retryTimer;
+  private heartbeatTimer;
+  private isAlive;
+  private readonly log;
+  constructor(options: RemoteServiceClientOptions);
+  get isConnected(): boolean;
+  /** Backpressure signal for the screencast pump — bytes queued but not flushed. */
+  get bufferedAmount(): number;
+  start(): void;
+  stop(): void;
+  /** Send a pre-encoded binary frame. No-op if the socket isn't open. */
+  sendFrame(buf: Buffer): void;
+  private doConnect;
+  private scheduleReconnect;
+  /**
+   * 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.
+   */
+  private startHeartbeat;
+  private clearHeartbeat;
+}
+//#endregion
+//#region src/turn-controller.d.ts
+/**
+ * TurnController — the write-mutex between agent automation and a human during
+ * a browser co-browse handoff. The plugin owns the single CDP session, so this
+ * lives plugin-side; the relay only forwards the control frames.
+ *
+ * Only *writes* are gated — screencast reads always flow so the human sees the
+ * live page regardless of who holds the token. Agent automation ops call
+ * `acquireAgent()` and park while the human is in control; the human's input is
+ * injected only while `owner === 'human'`.
+ */
+type TurnOwner = "agent" | "human";
+interface TurnControllerOptions {
+  /** Fired whenever ownership changes, so the plugin can emit SESSION_STATE. */
+  onOwnerChange?: (owner: TurnOwner) => void;
+}
+declare class TurnController {
+  private owner;
+  private waiters;
+  private readonly onOwnerChange?;
+  constructor(options?: TurnControllerOptions);
+  get currentOwner(): TurnOwner;
+  get humanInControl(): boolean;
+  /**
+   * 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.
+   */
+  acquireAgent(): Promise<void>;
+  /**
+   * Grant control to a human. Succeeds unless a human already holds it (single
+   * controller). "Human request always wins over the agent" — the agent parks
+   * at its next `acquireAgent()`.
+   */
+  grantHuman(): boolean;
+  /** Return control to the agent and drain any parked automation ops. */
+  releaseHuman(): void;
+  private setOwner;
+}
+//#endregion
+export { KeyInputPayload, type Logger, MouseInputPayload, REMOTE_HEADER_SIZE, REMOTE_MAX_PAYLOAD, RemoteFrame, RemoteFrameType, RemoteServiceClient, type RemoteServiceClientOptions, RemoteSurface, ResizePayload, ScreencastFrameMeta, SessionOpenPayload, SessionStatePayload, type SurfaceHandler, TerminalResizePayload, TurnController, type TurnControllerOptions, type TurnOwner, WheelInputPayload, decodeFrame, decodeJson, decodeScreencastFrame, encodeFrame, encodeJsonFrame, encodeScreencastFrame, isRemoteFrame };

package/dist/index.js

@@ -0,0 +1,321 @@
+import WebSocket from "ws";
+//#region src/remote-protocol.ts
+/**
+* Remote-relay framing protocol — multiplexes interactive surfaces (browser
+* screencast + input, terminal PTY) over the single outbound WS between the
+* agent plugin and the Alfe remote relay service. The relay routes frames by
+* `sessionId` (bytes 1-4) without parsing payloads.
+*
+* 5-byte header (WS preserves order, so no sequence numbers):
+*   Byte 0     Frame type (uint8)
+*   Bytes 1-4  Session ID (uint32, big-endian) — one viewer attachment
+*   Bytes 5+   Payload — JSON (utf-8) for control/input, raw bytes for media
+*
+* Direction is enforced at the relay:
+*   • plugin → viewer: SESSION_STATE, NAVIGATION, SCREENCAST_FRAME,
+*     TAKEOVER_GRANTED/DENIED, CONTROL_REVOKED, TERMINAL_DATA
+*   • 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`.
+*/
+const REMOTE_HEADER_SIZE = 5;
+const RemoteFrameType = {
+	SESSION_OPEN: 1,
+	SESSION_CLOSE: 2,
+	SESSION_STATE: 3,
+	NAVIGATION: 4,
+	SCREENCAST_FRAME: 16,
+	SCREENCAST_ACK: 17,
+	INPUT_MOUSE: 32,
+	INPUT_WHEEL: 33,
+	INPUT_KEY: 34,
+	RESIZE: 35,
+	TAKEOVER_REQUEST: 48,
+	TAKEOVER_GRANTED: 49,
+	TAKEOVER_DENIED: 50,
+	RELEASE_CONTROL: 51,
+	CONTROL_REVOKED: 52,
+	TERMINAL_DATA: 64,
+	TERMINAL_INPUT: 65,
+	TERMINAL_RESIZE: 66
+};
+const MIN_FRAME_TYPE = RemoteFrameType.SESSION_OPEN;
+const MAX_FRAME_TYPE = RemoteFrameType.TERMINAL_RESIZE;
+function isRemoteFrame(data) {
+	if (data.length < 5) return false;
+	const type = data[0];
+	return type >= MIN_FRAME_TYPE && type <= MAX_FRAME_TYPE;
+}
+function encodeFrame(type, sessionId, payload) {
+	const body = payload ?? Buffer.alloc(0);
+	const buf = Buffer.allocUnsafe(5 + body.length);
+	buf.writeUInt8(type, 0);
+	buf.writeUInt32BE(sessionId >>> 0, 1);
+	if (body.length > 0) body.copy(buf, 5);
+	return buf;
+}
+function decodeFrame(buf) {
+	if (buf.length < 5) throw new Error(`Remote frame too short: ${String(buf.length)} bytes`);
+	return {
+		type: buf.readUInt8(0),
+		sessionId: buf.readUInt32BE(1),
+		payload: buf.subarray(5)
+	};
+}
+function encodeJsonFrame(type, sessionId, obj) {
+	return encodeFrame(type, sessionId, Buffer.from(JSON.stringify(obj), "utf-8"));
+}
+/** 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`). */
+function decodeJson(payload) {
+	try {
+		return JSON.parse(payload.toString("utf-8"));
+	} catch {
+		return null;
+	}
+}
+/** 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 body = Buffer.allocUnsafe(2 + metaJson.length + jpeg.length);
+	body.writeUInt16BE(metaJson.length, 0);
+	metaJson.copy(body, 2);
+	jpeg.copy(body, 2 + metaJson.length);
+	return encodeFrame(RemoteFrameType.SCREENCAST_FRAME, sessionId, body);
+}
+function decodeScreencastFrame(payload) {
+	if (payload.length < 2) 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;
+	return {
+		meta,
+		jpeg: payload.subarray(2 + metaLen)
+	};
+}
+/** Maximum WS message size (must align across daemon plugin and relay). */
+const REMOTE_MAX_PAYLOAD = 10 * 1024 * 1024;
+//#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.
+*/
+const RECONNECT_DELAYS = [
+	1e3,
+	2e3,
+	4e3,
+	8e3,
+	16e3,
+	3e4
+];
+const HEARTBEAT_INTERVAL_MS = 3e4;
+const defaultLogger = {
+	info: (msg) => {
+		console.log(`[remote-client] ${msg}`);
+	},
+	warn: (msg) => {
+		console.warn(`[remote-client] ${msg}`);
+	},
+	error: (msg) => {
+		console.error(`[remote-client] ${msg}`);
+	},
+	debug: () => {}
+};
+function wsDataToBuffer(data) {
+	if (Buffer.isBuffer(data)) return data;
+	if (Array.isArray(data)) return Buffer.concat(data);
+	return Buffer.from(data);
+}
+var RemoteServiceClient = class {
+	ws = null;
+	stopped = false;
+	connected = false;
+	retryCount = 0;
+	retryTimer = null;
+	heartbeatTimer = null;
+	isAlive = false;
+	log;
+	constructor(options) {
+		this.options = options;
+		this.log = options.logger ?? defaultLogger;
+	}
+	get isConnected() {
+		return this.connected && this.ws?.readyState === WebSocket.OPEN;
+	}
+	/** Backpressure signal for the screencast pump — bytes queued but not flushed. */
+	get bufferedAmount() {
+		return this.ws?.bufferedAmount ?? 0;
+	}
+	start() {
+		this.log.debug("RemoteServiceClient starting...");
+		this.stopped = false;
+		this.doConnect();
+	}
+	stop() {
+		this.log.debug("RemoteServiceClient stopping...");
+		this.stopped = true;
+		if (this.retryTimer) {
+			clearTimeout(this.retryTimer);
+			this.retryTimer = null;
+		}
+		this.clearHeartbeat();
+		if (this.ws) {
+			try {
+				this.ws.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. */
+	sendFrame(buf) {
+		if (this.ws?.readyState === WebSocket.OPEN) this.ws.send(buf, { binary: true });
+	}
+	doConnect() {
+		if (this.stopped) return;
+		this.log.info(`Connecting to remote relay at ${this.options.wsUrl}...`);
+		this.ws = new WebSocket(this.options.wsUrl, {
+			headers: { authorization: `Bearer ${this.options.apiKey}` },
+			maxPayload: REMOTE_MAX_PAYLOAD,
+			handshakeTimeout: 1e4
+		});
+		this.ws.on("open", () => {
+			this.log.info("Connected to remote relay");
+			this.connected = true;
+			this.retryCount = 0;
+			this.startHeartbeat();
+			this.options.onConnectionChange?.(true);
+		});
+		this.ws.on("message", (data, isBinary) => {
+			this.isAlive = true;
+			if (!isBinary) return;
+			const buf = wsDataToBuffer(data);
+			if (!isRemoteFrame(buf)) return;
+			try {
+				this.options.onFrame(decodeFrame(buf));
+			} catch (err) {
+				this.log.warn(`Failed to handle remote frame: ${err.message}`);
+			}
+		});
+		this.ws.on("ping", () => {
+			this.isAlive = true;
+			this.ws?.pong();
+		});
+		this.ws.on("pong", () => {
+			this.isAlive = true;
+		});
+		this.ws.on("close", (code, reason) => {
+			this.clearHeartbeat();
+			this.log.warn(`Disconnected from remote relay (${String(code)}: ${reason.toString()})`);
+			this.connected = false;
+			this.options.onConnectionChange?.(false);
+			this.scheduleReconnect();
+		});
+		this.ws.on("error", (err) => {
+			this.log.error(`Remote relay WS error: ${err.message}`);
+		});
+	}
+	scheduleReconnect() {
+		if (this.stopped) return;
+		const delay = RECONNECT_DELAYS[Math.min(this.retryCount, RECONNECT_DELAYS.length - 1)];
+		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();
+		}, delay);
+	}
+	/**
+	* 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() {
+		this.clearHeartbeat();
+		this.isAlive = true;
+		const timer = setInterval(() => {
+			if (this.ws?.readyState !== WebSocket.OPEN) return;
+			if (!this.isAlive) {
+				this.log.warn("Remote relay heartbeat timed out — terminating stale connection");
+				this.ws.terminate();
+				return;
+			}
+			this.isAlive = false;
+			try {
+				this.ws.ping();
+			} catch {}
+		}, HEARTBEAT_INTERVAL_MS);
+		timer.unref();
+		this.heartbeatTimer = timer;
+	}
+	clearHeartbeat() {
+		if (this.heartbeatTimer) {
+			clearInterval(this.heartbeatTimer);
+			this.heartbeatTimer = null;
+		}
+	}
+};
+//#endregion
+//#region src/turn-controller.ts
+var TurnController = class {
+	owner = "agent";
+	waiters = [];
+	onOwnerChange;
+	constructor(options = {}) {
+		this.onOwnerChange = options.onOwnerChange;
+	}
+	get currentOwner() {
+		return this.owner;
+	}
+	get humanInControl() {
+		return this.owner === "human";
+	}
+	/**
+	* 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.
+	*/
+	acquireAgent() {
+		if (this.owner === "agent") return Promise.resolve();
+		return new Promise((resolve) => {
+			this.waiters.push(resolve);
+		});
+	}
+	/**
+	* Grant control to a human. Succeeds unless a human already holds it (single
+	* controller). "Human request always wins over the agent" — the agent parks
+	* at its next `acquireAgent()`.
+	*/
+	grantHuman() {
+		if (this.owner === "human") return false;
+		this.setOwner("human");
+		return true;
+	}
+	/** Return control to the agent and drain any parked automation ops. */
+	releaseHuman() {
+		if (this.owner === "agent") return;
+		this.setOwner("agent");
+		const parked = this.waiters;
+		this.waiters = [];
+		for (const resolve of parked) resolve();
+	}
+	setOwner(owner) {
+		if (this.owner === owner) return;
+		this.owner = owner;
+		this.onOwnerChange?.(owner);
+	}
+};
+//#endregion
+export { REMOTE_HEADER_SIZE, REMOTE_MAX_PAYLOAD, RemoteFrameType, RemoteServiceClient, TurnController, decodeFrame, decodeJson, decodeScreencastFrame, encodeFrame, encodeJsonFrame, encodeScreencastFrame, isRemoteFrame };

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@alfe.ai/remote",
+  "version": "0.0.0",
+  "description": "Runtime-agnostic transport for the Alfe interactive remote-control relay — multiplexes browser screencast and terminal PTY surfaces over one outbound WebSocket",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.cjs",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "license": "UNLICENSED",
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint ."
+  }
+}