@activeagents/browser-sidecar 0.0.0-stage → 1.9.0

package/lib/control-lock.mjs

@@ -0,0 +1,210 @@
+import { EventEmitter } from 'node:events';
+
+// The Playwright MCP tools that only look at the browser. Every other tool
+// changes the page, and waits while a person holds control.
+export const OBSERVING_TOOLS = new Set([
+  'browser_snapshot',
+  'browser_take_screenshot',
+  'browser_console_messages',
+  'browser_network_requests',
+  'browser_network_request',
+  'browser_find',
+  'browser_generate_locator',
+  'browser_wait_for',
+  'browser_verify_element_visible',
+  'browser_verify_list_visible',
+  'browser_verify_text_visible',
+  'browser_verify_value',
+  'browser_pdf_save',
+  'browser_get_config',
+]);
+
+// The _meta key a refused call's result names the person driving under.
+export const TAKEOVER_META = 'activeagents/takeover';
+
+/**
+ * Whether the tool call `name` with `args` would change what the browser
+ * shows.
+ *
+ * @param {string} name
+ * @param {object} [args]
+ */
+export function changesPage(name, args = {}) {
+  if (name === 'browser_tabs') return args?.action !== 'list';
+  return !OBSERVING_TOOLS.has(name);
+}
+
+/**
+ * Whether the holders' users `a` and `b` are the same person. A user with no
+ * id is nobody in particular, so is never the same as anyone.
+ *
+ * @param {{ id: string|null }} a
+ * @param {{ id: string|null }} b
+ */
+export function sameUser(a, b) {
+  return a.id !== null && a.id === b.id;
+}
+
+/**
+ * Used to let one person at a time drive the browser by hand. While someone
+ * holds control, an agent's call that changes the page waits for them to
+ * hand it back (#admit).
+ *
+ * A holder is identified by the key of their connection, and is a
+ * `{ key, user: { id, name }, since }`. A user with an id may move control
+ * between their own connections: a second tab, or a reconnect.
+ *
+ * Events:
+ *   change         (holder, previous, reason) whenever the holder changes;
+ *                  reason is "taken", "moved", "handed_back", "disconnected"
+ *                  or "closed"
+ *   agent_waiting  ({ tool, since }) an agent's call began to wait
+ *   agent_done     ({ tool, admitted }) it stopped waiting, run or refused
+ */
+export class ControlLock extends EventEmitter {
+  /**
+   * @param {object} [options]
+   * @param {number} [options.graceMs] how long control stays with a holder whose connection dropped
+   * @param {() => number} [options.now] epoch milliseconds
+   */
+  constructor({ graceMs = 10_000, now = Date.now } = {}) {
+    super();
+    this.graceMs = graceMs;
+    this.now = now;
+    this.holder = null;
+    this.graceTimer = null;
+    this.waiting = new Set();
+    this.closed = false;
+  }
+
+  /**
+   * Gives control to the connection `key`, for `user`, unless another
+   * person holds it.
+   *
+   * @param {string} key
+   * @param {{ id: string|null, name: string|null }} user
+   * @returns {{ holder: object, taken: boolean }} taken is false when someone else holds it
+   */
+  acquire(key, user) {
+    const previous = this.holder;
+    if (this.closed) return { holder: previous, taken: false };
+    if (previous?.key === key) return { holder: previous, taken: true };
+    if (previous && !sameUser(previous.user, user)) return { holder: previous, taken: false };
+
+    this.clearGrace();
+    this.holder = { key, user, since: previous?.since ?? this.now() };
+    this.emit('change', this.holder, previous, previous ? 'moved' : 'taken');
+    return { holder: this.holder, taken: true };
+  }
+
+  /**
+   * Takes control from the connection `key`, when it holds it.
+   *
+   * @param {string} key
+   * @param {string} [reason]
+   * @returns {boolean} whether it held control
+   */
+  release(key, reason = 'handed_back') {
+    if (this.holder?.key !== key) return false;
+
+    this.clearGrace();
+    const previous = this.holder;
+    this.holder = null;
+    this.emit('change', null, previous, reason);
+    return true;
+  }
+
+  /**
+   * Notes that the connection `key` closed: when it holds control, control
+   * is released after the grace period, unless its user takes it up again
+   * from another connection first.
+   *
+   * @param {string} key
+   */
+  disconnected(key) {
+    if (this.holder?.key !== key) return;
+
+    this.clearGrace();
+    this.graceTimer = setTimeout(() => this.release(key, 'disconnected'), this.graceMs);
+    this.graceTimer.unref?.();
+  }
+
+  /**
+   * Lets an agent's tool call through, at once when it does not change the
+   * page or nobody holds control, and otherwise once control is handed back
+   * within `waitMs`.
+   *
+   * @param {string} name the tool
+   * @param {object} args its arguments
+   * @param {number} waitMs
+   * @returns {Promise<{ holder: object }|{ stopping: true }|null>} null to run the call; otherwise why it
+   *   is refused: the holder who kept control past `waitMs`, or `stopping` when the lock closed meanwhile
+   */
+  async admit(name, args, waitMs) {
+    if (!this.holder || !changesPage(name, args)) return null;
+
+    const wait = { tool: name, since: this.now() };
+    const deadline = wait.since + waitMs;
+    this.waiting.add(wait);
+    this.emit('agent_waiting', wait);
+    // Someone may take control again between its release and this call
+    // going ahead, so the wait goes on until control is free at that moment.
+    while (this.holder && !this.closed && deadline > this.now()) {
+      if (!(await this.waitUntilFree(deadline - this.now()))) break;
+    }
+    let refusal = null;
+    if (this.closed) refusal = { stopping: true };
+    else if (this.holder) refusal = { holder: this.holder };
+    this.waiting.delete(wait);
+    this.emit('agent_done', { tool: name, admitted: refusal === null });
+    return refusal;
+  }
+
+  /**
+   * Resolves true once nobody holds control, or false after `timeoutMs`.
+   *
+   * @param {number} timeoutMs
+   * @returns {Promise<boolean>}
+   */
+  waitUntilFree(timeoutMs) {
+    if (!this.holder) return Promise.resolve(true);
+    if (this.closed) return Promise.resolve(false);
+
+    return new Promise((resolve) => {
+      const finish = (free) => {
+        clearTimeout(timer);
+        this.off('change', onChange);
+        this.off('closed', onClosed);
+        resolve(free);
+      };
+      const onChange = (holder) => {
+        if (!holder) finish(true);
+      };
+      const onClosed = () => finish(false);
+      const timer = setTimeout(() => finish(false), timeoutMs);
+      this.on('change', onChange);
+      this.on('closed', onClosed);
+    });
+  }
+
+  // The longest-waiting agent call, or null.
+  get agentWaiting() {
+    const [first] = this.waiting;
+    return first ?? null;
+  }
+
+  // Releases control for good, refusing the agent calls still waiting: the
+  // browser is stopping.
+  close() {
+    if (this.closed) return;
+    this.closed = true;
+    this.emit('closed');
+    if (this.holder) this.release(this.holder.key, 'closed');
+    this.clearGrace();
+  }
+
+  clearGrace() {
+    if (this.graceTimer !== null) clearTimeout(this.graceTimer);
+    this.graceTimer = null;
+  }
+}

package/lib/egress-proxy.mjs

@@ -0,0 +1,127 @@
+import http from 'node:http';
+import net from 'node:net';
+
+// Headers that belong to one hop and are never passed across the proxy.
+const HOP_BY_HOP = new Set([
+  'connection', 'proxy-connection', 'keep-alive', 'proxy-authorization', 'proxy-authenticate', 'te', 'trailer', 'transfer-encoding', 'upgrade',
+]);
+
+function endToEndHeaders(headers) {
+  const named = String(headers.connection ?? '').toLowerCase().split(',').map((name) => name.trim());
+  return Object.fromEntries(Object.entries(headers).filter(([name]) => !HOP_BY_HOP.has(name) && !named.includes(name)));
+}
+
+// "example.com:443" or "[::1]:8080" as a host and port, or null.
+function authority(text) {
+  const match = /^(\[[^\]]+\]|[^:]+):(\d{1,5})$/.exec(text ?? '');
+  if (!match) return null;
+  const port = Number(match[2]);
+  return port > 0 && port < 65536 ? { hostname: match[1], port } : null;
+}
+
+function refuse(response, status, reason) {
+  response.writeHead(status, { 'content-type': 'text/plain; charset=utf-8', connection: 'close' });
+  response.end(`Blocked by the sandbox browser: ${reason}\n`);
+}
+
+/**
+ * Starts the forward proxy every connection the browser opens goes through,
+ * and returns once it listens on loopback. Each plain HTTP request and each
+ * CONNECT tunnel (HTTPS and WebSockets) is checked with
+ * `policy.destination`, and the upstream connection is made to the address
+ * that check returned, never to a name resolved again. A refused request is
+ * answered 403; a refused tunnel is never opened.
+ *
+ * @param {object} options
+ * @param {{ destination(hostname: string, port: number): Promise<{ address: string | null, refusal: string | null }> }} options.policy
+ * @param {(message: string) => void} [options.log]
+ * @returns {Promise<{ url: string, close: () => Promise<void> }>}
+ */
+export async function startEgressProxy({ policy, log = () => {} }) {
+  const agent = new http.Agent({ keepAlive: true });
+  const sockets = new Set();
+  const track = (socket) => {
+    sockets.add(socket);
+    socket.once('close', () => sockets.delete(socket));
+  };
+
+  const server = http.createServer(async (request, response) => {
+    let target;
+    try {
+      target = new URL(request.url);
+    } catch {
+      return refuse(response, 400, 'not a proxy request');
+    }
+    if (target.protocol !== 'http:') return refuse(response, 400, `${target.protocol} requests are not proxied`);
+
+    const port = Number(target.port || 80);
+    const { address, refusal } = await policy.destination(target.hostname, port);
+    if (refusal) {
+      log(`refused a request: ${refusal}`);
+      return refuse(response, 403, refusal);
+    }
+
+    const upstream = http.request({
+      host: address,
+      port,
+      method: request.method,
+      path: `${target.pathname}${target.search}`,
+      headers: endToEndHeaders(request.headers),
+      setHost: false,
+      agent,
+    });
+    upstream.on('response', (answer) => {
+      response.writeHead(answer.statusCode, answer.statusMessage, endToEndHeaders(answer.headers));
+      answer.pipe(response);
+    });
+    upstream.on('error', (error) => {
+      if (response.headersSent) response.destroy();
+      else refuse(response, 502, `${target.host} could not be reached (${error.code ?? error.message})`);
+    });
+    response.on('close', () => {
+      if (!response.writableFinished) upstream.destroy();
+    });
+    request.pipe(upstream);
+  });
+
+  server.on('connection', track);
+  server.on('connect', async (request, socket, head) => {
+    socket.on('error', () => {});
+    const requested = authority(request.url);
+    const { address, refusal } = requested
+      ? await policy.destination(requested.hostname, requested.port)
+      : { address: null, refusal: `${request.url} is not a host and port` };
+    if (refusal) {
+      log(`refused a connection: ${refusal}`);
+      socket.end('HTTP/1.1 403 Forbidden\r\ncontent-length: 0\r\nconnection: close\r\n\r\n');
+      return;
+    }
+
+    const upstream = net.connect(requested.port, address);
+    track(upstream);
+    upstream.on('error', () => socket.destroy());
+    socket.on('close', () => upstream.destroy());
+    upstream.once('connect', () => {
+      socket.write('HTTP/1.1 200 Connection Established\r\n\r\n');
+      if (head.length > 0) upstream.write(head);
+      upstream.pipe(socket);
+      socket.pipe(upstream);
+    });
+  });
+
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', resolve);
+  });
+
+  return {
+    url: `http://127.0.0.1:${server.address().port}`,
+    close: async () => {
+      await new Promise((resolve) => {
+        server.close(() => resolve());
+        for (const socket of sockets) socket.destroy();
+      });
+      agent.destroy();
+    },
+  };
+}

package/lib/guard.mjs

@@ -0,0 +1,86 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
+
+const LOOPBACK_NAMES = ['127.0.0.1', 'localhost', '[::1]'];
+
+function hostName(host) {
+  return host.includes(':') && !host.startsWith('[') ? `[${host}]` : host;
+}
+
+/**
+ * Returns the Host header values a request to the sidecar may carry: the
+ * address it listens on and, when that is loopback or every interface, the
+ * loopback names, each with the port; and `extra` as given (the names the
+ * sidecar is reached by inside a container network).
+ *
+ * @param {string} host the listening address
+ * @param {number} port the listening port
+ * @param {string[]} extra Host values to accept as given
+ * @returns {Set<string>}
+ */
+export function acceptedHosts(host, port, extra = []) {
+  const names = new Set([hostName(host.toLowerCase())]);
+  if (['127.0.0.1', 'localhost', '::1', '0.0.0.0', '::'].includes(host)) {
+    for (const name of LOOPBACK_NAMES) names.add(name);
+  }
+  names.delete('0.0.0.0');
+  names.delete('[::]');
+
+  const accepted = new Set([...names].map((name) => `${name}:${port}`));
+  for (const value of extra) accepted.add(value.toLowerCase());
+  return accepted;
+}
+
+function digest(value) {
+  return createHash('sha256').update(value).digest();
+}
+
+function bearerMatches(header, token) {
+  const match = /^Bearer\s+(\S+)\s*$/i.exec(header ?? '');
+  return match !== null && timingSafeEqual(digest(match[1]), digest(token));
+}
+
+/**
+ * Checks one HTTP request, or WebSocket upgrade, before anything else reads
+ * it. A request must name an accepted Host, which defeats DNS rebinding,
+ * carry no Origin unless that origin is allowed (a page in a browser always
+ * sends one), and carry the bearer token.
+ *
+ * @param {import('node:http').IncomingMessage} request
+ * @param {{ token: string, hosts: Set<string>, origins?: Set<string> }} rules
+ * @returns {{ status: number, message: string } | null} the refusal, or null to proceed
+ */
+export function refusal(request, { token, hosts, origins = new Set() }) {
+  const host = (request.headers.host ?? '').toLowerCase();
+  if (!hosts.has(host)) return { status: 403, message: 'Host not allowed' };
+
+  const origin = request.headers.origin;
+  if (origin !== undefined && !origins.has(origin)) return { status: 403, message: 'Origin not allowed' };
+
+  if (!bearerMatches(request.headers.authorization, token)) return { status: 401, message: 'Missing or invalid bearer token' };
+
+  return null;
+}
+
+/**
+ * Checks a WebSocket upgrade to the live view before it is accepted. The
+ * dashboard's page opens it, so it carries the dashboard's Origin, and it
+ * carries no token: a viewer proves who they are with the ticket in its
+ * first message (LiveServer). The request must name an accepted Host, come
+ * from one of `origins`, and carry no query, which keeps a ticket out of
+ * URLs and the logs that record them.
+ *
+ * @param {import('node:http').IncomingMessage} request
+ * @param {{ hosts: Set<string>, origins: Set<string> }} rules
+ * @returns {{ status: number, message: string } | null} the refusal, or null to proceed
+ */
+export function liveRefusal(request, { hosts, origins }) {
+  const host = (request.headers.host ?? '').toLowerCase();
+  if (!hosts.has(host)) return { status: 403, message: 'Host not allowed' };
+
+  const origin = request.headers.origin;
+  if (typeof origin !== 'string' || !origins.has(origin.toLowerCase())) return { status: 403, message: 'Origin not allowed' };
+
+  if (request.url.includes('?')) return { status: 400, message: 'The live view takes no query' };
+
+  return null;
+}

package/lib/http-server.mjs

@@ -0,0 +1,124 @@
+import http from 'node:http';
+
+import { liveRefusal, refusal } from './guard.mjs';
+import { LIVE_PATH } from './live-server.mjs';
+
+// Larger than any tool call the engine sends.
+export const MAX_BODY_BYTES = 4 * 1024 * 1024;
+
+function respond(response, status, body, headers = {}) {
+  const text = body === undefined ? '' : JSON.stringify(body);
+  response.writeHead(status, {
+    'content-type': 'application/json',
+    'cache-control': 'no-store',
+    'content-length': Buffer.byteLength(text),
+    ...headers,
+  });
+  response.end(text);
+}
+
+function readBody(request) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let size = 0;
+    request.on('data', (chunk) => {
+      size += chunk.length;
+      if (size > MAX_BODY_BYTES) {
+        reject(Object.assign(new Error('The body is too large'), { status: 413 }));
+        request.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    request.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+    request.on('error', reject);
+  });
+}
+
+function pathOf(request) {
+  try {
+    return new URL(request.url, 'http://sidecar').pathname;
+  } catch {
+    return null;
+  }
+}
+
+function rejectUpgrade(socket, status) {
+  socket.end(`HTTP/1.1 ${status} ${http.STATUS_CODES[status]}\r\nConnection: close\r\nContent-Length: 0\r\n\r\n`);
+}
+
+/**
+ * Creates the sidecar's HTTP server:
+ *
+ *   GET    /health         { status: "ok", version }
+ *   POST   /mcp            one JSON-RPC message, answered as JSON (McpGateway)
+ *   DELETE /mcp            ends the session named by Mcp-Session-Id
+ *   GET    /live           the live view's WebSocket (LiveServer), when `live` is given
+ *   GET    /storage-state  the browser's cookies and localStorage for the
+ *                          app's origin, so a sign-in can be kept
+ *
+ * Every request, and every WebSocket upgrade other than the live view's, is
+ * checked by guard.refusal before anything else happens. The live view's
+ * upgrade is checked by guard.liveRefusal instead, and any other upgrade is
+ * refused.
+ *
+ * @param {object} options
+ * @param {() => { token: string, hosts: Set<string>, origins?: Set<string>, liveOrigins?: Set<string> }} options.rules
+ *   what the guards check against, read per request since the port is known only once listening
+ * @param {{ handle: Function, closeSession: Function }} options.gateway
+ * @param {string} options.version
+ * @param {{ handleUpgrade: Function } | null} [options.live] a LiveServer
+ * @param {() => Promise<object>} [options.storageState] returns what GET /storage-state answers
+ * @returns {import('node:http').Server}
+ */
+export function createHttpServer({ rules, gateway, version, live = null, storageState = null }) {
+  const server = http.createServer(async (request, response) => {
+    const denied = refusal(request, rules());
+    if (denied) return respond(response, denied.status, { error: denied.message });
+
+    const path = new URL(request.url, 'http://sidecar').pathname;
+    try {
+      if (path === '/health' && request.method === 'GET') return respond(response, 200, { status: 'ok', version });
+      if (path === '/storage-state' && request.method === 'GET' && storageState) {
+        return respond(response, 200, { storage_state: await storageState() });
+      }
+      if (path !== '/mcp') return respond(response, 404, { error: 'Not found' });
+
+      const sessionId = request.headers['mcp-session-id'];
+      if (request.method === 'DELETE') {
+        const closed = typeof sessionId === 'string' && (await gateway.closeSession(sessionId));
+        return respond(response, closed ? 200 : 404, closed ? { closed: true } : { error: 'Session not found' });
+      }
+      if (request.method !== 'POST') return respond(response, 405, { error: 'POST JSON-RPC here' }, { allow: 'POST, DELETE' });
+
+      let message;
+      try {
+        message = JSON.parse(await readBody(request));
+      } catch (error) {
+        if (error.status) throw error;
+        return respond(response, 400, { jsonrpc: '2.0', id: null, error: { code: -32700, message: 'The body is not JSON' } });
+      }
+
+      const result = await gateway.handle(message, typeof sessionId === 'string' ? sessionId : undefined);
+      return respond(response, result.status, result.body, result.headers);
+    } catch (error) {
+      if (!response.headersSent) respond(response, error.status ?? 500, { error: error.status ? error.message : 'Internal error' });
+      if (!error.status) process.stderr.write(`browser-sidecar: ${error.stack ?? error}\n`);
+    }
+  });
+
+  server.on('upgrade', (request, socket, head) => {
+    const current = rules();
+    if (live && pathOf(request) === LIVE_PATH) {
+      const denied = liveRefusal(request, { hosts: current.hosts, origins: current.liveOrigins ?? new Set() });
+      if (denied) rejectUpgrade(socket, denied.status);
+      else live.handleUpgrade(request, socket, head);
+      return;
+    }
+
+    rejectUpgrade(socket, (refusal(request, current) ?? { status: 404 }).status);
+  });
+  server.on('clientError', (_error, socket) => socket.destroy());
+
+  return server;
+}

package/lib/input.mjs

@@ -0,0 +1,137 @@
+// Turns the input a viewer relays into Chrome DevTools Protocol commands for
+// the page on screen. A viewer sends pointer positions as fractions of the
+// frame it was shown (0 to 1 from the left and top), and they are scaled to
+// the page's CSS pixels from the latest frame's metadata.
+//
+// Messages:
+//   { type: "mouse", action: "move"|"down"|"up", x, y, button, clickCount, modifiers }
+//   { type: "wheel", x, y, deltaX, deltaY, modifiers }
+//   { type: "key", action: "down"|"up", key, code, keyCode, modifiers }
+//   { type: "text", text }
+//
+// `modifiers` is the CDP bit field: Alt 1, Ctrl 2, Meta 4, Shift 8.
+
+const MOUSE_TYPES = { move: 'mouseMoved', down: 'mousePressed', up: 'mouseReleased' };
+const BUTTONS = new Set(['none', 'left', 'middle', 'right']);
+const CTRL = 2;
+const META = 4;
+const MAX_KEY_CHARS = 32;
+const MAX_TEXT_CHARS = 2000;
+const MAX_WHEEL_DELTA = 10_000;
+// The text a key types when its key value is not the character itself.
+const KEY_TEXT = { Enter: '\r' };
+// Windows virtual key codes, for a key the viewer sent none for.
+const KEY_CODES = {
+  Backspace: 8, Tab: 9, Enter: 13, Shift: 16, Control: 17, Alt: 18, Pause: 19, CapsLock: 20, Escape: 27, ' ': 32,
+  PageUp: 33, PageDown: 34, End: 35, Home: 36, ArrowLeft: 37, ArrowUp: 38, ArrowRight: 39, ArrowDown: 40,
+  Insert: 45, Delete: 46, Meta: 91,
+};
+
+function fraction(value) {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 1;
+}
+
+function modifiers(value) {
+  return Number.isInteger(value) && value >= 0 && value <= 15 ? value : 0;
+}
+
+function boundedNumber(value, limit) {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return 0;
+  return Math.max(-limit, Math.min(limit, value));
+}
+
+/**
+ * Returns the CSS pixel position of a point given as fractions of a frame
+ * whose metadata is `metadata`, or null without a frame to scale by.
+ *
+ * @param {{ x: number, y: number }} point
+ * @param {{ deviceWidth: number, deviceHeight: number, offsetTop?: number } | null} metadata
+ * @returns {{ x: number, y: number } | null}
+ */
+export function pagePoint({ x, y }, metadata) {
+  if (!fraction(x) || !fraction(y) || !metadata) return null;
+  const { deviceWidth, deviceHeight, offsetTop = 0 } = metadata;
+  if (!(deviceWidth > 0) || !(deviceHeight > 0)) return null;
+
+  return { x: Math.round(x * deviceWidth), y: Math.round(y * deviceHeight + offsetTop) };
+}
+
+/**
+ * Returns `[method, params]` for one relayed input message, or null when the
+ * message is not one the viewer may send, or a pointer message arrives
+ * before any frame was shown.
+ *
+ * @param {object} message
+ * @param {object | null} metadata the latest frame's metadata
+ * @returns {[string, object] | null}
+ */
+export function inputCommand(message, metadata) {
+  switch (message?.type) {
+    case 'mouse':
+      return mouseCommand(message, metadata);
+    case 'wheel':
+      return wheelCommand(message, metadata);
+    case 'key':
+      return keyCommand(message);
+    case 'text':
+      return textCommand(message);
+    default:
+      return null;
+  }
+}
+
+function mouseCommand(message, metadata) {
+  const type = MOUSE_TYPES[message.action];
+  const point = pagePoint(message, metadata);
+  if (!type || !point) return null;
+
+  const button = BUTTONS.has(message.button) ? message.button : type === 'mouseMoved' ? 'none' : 'left';
+  const clickCount = Number.isInteger(message.clickCount) && message.clickCount >= 0 && message.clickCount <= 3 ? message.clickCount : 1;
+  const params = { type, ...point, button, modifiers: modifiers(message.modifiers) };
+  if (type !== 'mouseMoved') params.clickCount = clickCount;
+  return ['Input.dispatchMouseEvent', params];
+}
+
+function wheelCommand(message, metadata) {
+  const point = pagePoint(message, metadata);
+  if (!point) return null;
+
+  return ['Input.dispatchMouseEvent', {
+    type: 'mouseWheel',
+    ...point,
+    deltaX: boundedNumber(message.deltaX, MAX_WHEEL_DELTA),
+    deltaY: boundedNumber(message.deltaY, MAX_WHEEL_DELTA),
+    modifiers: modifiers(message.modifiers),
+  }];
+}
+
+// The text a key down types: the character of a printable key, or Enter's
+// carriage return. A key pressed with Ctrl or Meta is a shortcut and types
+// nothing.
+function keyText(key, mask) {
+  if (mask & (CTRL | META)) return '';
+  if (KEY_TEXT[key]) return KEY_TEXT[key];
+  return [...key].length === 1 ? key : '';
+}
+
+function keyCommand(message) {
+  const { action, key } = message;
+  if ((action !== 'down' && action !== 'up') || typeof key !== 'string' || key === '' || key.length > MAX_KEY_CHARS) return null;
+
+  const code = typeof message.code === 'string' && message.code.length <= MAX_KEY_CHARS ? message.code : '';
+  const mask = modifiers(message.modifiers);
+  let keyCode = Number.isInteger(message.keyCode) && message.keyCode > 0 && message.keyCode < 256 ? message.keyCode : KEY_CODES[key];
+  if (keyCode === undefined && /^[a-z0-9]$/i.test(key)) keyCode = key.toUpperCase().charCodeAt(0);
+
+  const params = { key, code, modifiers: mask, windowsVirtualKeyCode: keyCode ?? 0 };
+  if (action === 'up') return ['Input.dispatchKeyEvent', { type: 'keyUp', ...params }];
+
+  const text = keyText(key, mask);
+  return ['Input.dispatchKeyEvent', text ? { type: 'keyDown', ...params, text, unmodifiedText: text } : { type: 'rawKeyDown', ...params }];
+}
+
+function textCommand(message) {
+  if (typeof message.text !== 'string' || message.text === '' || message.text.length > MAX_TEXT_CHARS) return null;
+
+  return ['Input.insertText', { text: message.text }];
+}