@activeagents/browser-sidecar 0.0.0-stage → 1.9.0

package/lib/sidecar.mjs

@@ -0,0 +1,252 @@
+import { mkdtemp, realpath, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { ControlLock } from './control-lock.mjs';
+import { startEgressProxy } from './egress-proxy.mjs';
+import { acceptedHosts } from './guard.mjs';
+import { createHttpServer } from './http-server.mjs';
+import { LiveServer } from './live-server.mjs';
+import { TicketVerifier, ticketKey } from './live-ticket.mjs';
+import { McpGateway } from './mcp-gateway.mjs';
+import { NavigationGuard } from './navigation-guard.mjs';
+import { NetworkPolicy } from './network-policy.mjs';
+import { PAGE_FLUSH_MS, Recorder } from './recorder.mjs';
+import { Screencast } from './screencast.mjs';
+import { exportStorageState } from './storage-state.mjs';
+import { VERSION } from './version.mjs';
+
+const VIEWPORT = { width: 1280, height: 800 };
+// WebRTC sends UDP around the proxy unless told otherwise. The headless
+// shell reads the first switch and headed Chromium the second.
+const WEBRTC_PROXIED_ONLY = ['--force-webrtc-ip-handling-policy=disable_non_proxied_udp', '--webrtc-ip-handling-policy=disable_non_proxied_udp'];
+// How long shutting down waits for the last recording batches to post.
+const RECORDING_DRAIN_MS = 5000;
+
+/**
+ * Checks every request and WebSocket the context's pages open against
+ * `policy.allows`, by URL, before it is sent. Registered once on the
+ * context, so it holds whichever MCP session drives the browser. Playwright
+ * calls a route only for the first URL of a redirect chain; the egress proxy
+ * and the NavigationGuard cover the hops after it.
+ *
+ * @param {import('playwright').BrowserContext} context
+ * @param {NetworkPolicy} policy
+ */
+export async function installNetworkPolicy(context, policy) {
+  await context.route('**/*', async (route) => {
+    const request = route.request();
+    let topLevelNavigation = false;
+    try {
+      topLevelNavigation = request.isNavigationRequest() && request.frame().parentFrame() === null;
+    } catch {
+      // A request without a frame (a worker's) is not a navigation.
+    }
+
+    try {
+      if (policy.allows(request.url(), { topLevelNavigation })) await route.fallback();
+      else await route.abort('blockedbyclient');
+    } catch {
+      // The page went away while the request was decided.
+    }
+  });
+
+  await context.routeWebSocket(/.*/, async (socket) => {
+    if (policy.allows(socket.url())) socket.connectToServer();
+    else await socket.close({ code: 1008, reason: 'Blocked by the sandbox browser' }).catch(() => {});
+  });
+}
+
+async function launchChromium(userDataDir, options) {
+  const { chromium } = await import('playwright');
+  return chromium.launchPersistentContext(userDataDir, options);
+}
+
+// Calls `callback` at `time` (epoch ms). setTimeout fires at once for a delay
+// past 2^31 - 1 ms, so a far deadline is reached in steps.
+function stopAt(time, callback) {
+  const delay = time - Date.now();
+  if (delay <= 0) return callback();
+  setTimeout(() => stopAt(time, callback), Math.min(delay, 2 ** 31 - 1));
+}
+
+/**
+ * The Playwright MCP configuration every session's server runs with.
+ *
+ * @param {{ capabilities: string[] }} config
+ * @param {string} outputDir
+ */
+export function mcpConfig(config, outputDir) {
+  return {
+    browser: { browserName: 'chromium', isolated: false },
+    capabilities: config.capabilities,
+    // Makes browser_close refuse to close the context the sessions share.
+    sharedBrowserContext: true,
+    // Pages would otherwise add tools of their own to the agent's list.
+    webmcp: false,
+    outputDir,
+    filePaths: 'absolute',
+    codegen: 'none',
+    timeouts: { idle: 0 },
+  };
+}
+
+/**
+ * Starts streaming `context` to the live view's viewers (LiveServer), with
+ * one person at a time able to take control of it.
+ *
+ * @param {object} config a parsed configuration with `live` set
+ * @param {import('playwright').BrowserContext} context
+ * @param {{ recorder: Recorder | null, log: (message: string) => void }} options
+ * @returns {Promise<{ server: LiveServer, lock: ControlLock, screencast: Screencast }>}
+ */
+async function startLiveView(config, context, { recorder, log }) {
+  const lock = new ControlLock({ graceMs: config.live.releaseGraceMs });
+  const verifier = new TicketVerifier({ key: ticketKey(config.token), sessionId: config.live.sessionId });
+  let server = null;
+  const screencast = new Screencast({ context, log, onFrame: (frame) => server?.frame(frame), onPageChange: () => server?.pageChanged() });
+  server = new LiveServer({ verifier, lock, screencast, log, onMarker: (data) => recorder?.marker(data) });
+  await screencast.attach();
+  return { server, lock, screencast };
+}
+
+/**
+ * Starts the browser and its MCP endpoint, and returns once the endpoint
+ * listens. Chromium gets a fresh profile directory and is driven over a pipe
+ * (Playwright's --remote-debugging-pipe), so no debugging port is opened.
+ * Every connection it makes goes through the egress proxy, loopback and
+ * WebRTC included. The process's working directory becomes an empty uploads
+ * directory, which is where Playwright MCP reads files to upload from.
+ *
+ * @param {object} config a parsed configuration (see parseConfig)
+ * @param {object} [dependencies]
+ * @param {Function} [dependencies.launch] chromium.launchPersistentContext
+ * @param {Function} [dependencies.createConnection] @playwright/mcp's createConnection
+ * @param {NetworkPolicy} [dependencies.policy] the rules for what the browser may load
+ * @param {(message: string) => void} [dependencies.log]
+ * @returns {Promise<{ port: number, close: (reason?: string, code?: number) => Promise<number>, done: Promise<number> }>}
+ *   `close` stops everything and removes the directories; `done` settles with
+ *   the exit status once it has, whatever stopped it (0, or 1 when the
+ *   browser went away on its own)
+ */
+export async function startSidecar(config, dependencies = {}) {
+  const log = dependencies.log ?? ((message) => process.stderr.write(`browser-sidecar: ${message}\n`));
+  const launch = dependencies.launch ?? launchChromium;
+  const connect = dependencies.createConnection ?? (await import('@playwright/mcp')).createConnection;
+
+  const ownsWorkdir = config.workdir === null;
+  const workdir = config.workdir ?? (await mkdtemp(join(tmpdir(), 'activeagents-browser-')));
+  const profileDir = await mkdtemp(join(workdir, 'profile-'));
+  const uploadsDir = await mkdtemp(join(workdir, 'uploads-'));
+  const outputDir = await mkdtemp(join(workdir, 'output-'));
+  const removeDirectories = async () => {
+    for (const dir of ownsWorkdir ? [workdir] : [profileDir, uploadsDir, outputDir]) {
+      await rm(dir, { recursive: true, force: true }).catch(() => {});
+    }
+  };
+  process.chdir(uploadsDir);
+
+  const policy = dependencies.policy ?? new NetworkPolicy({ appOrigin: config.appOrigin });
+  const proxy = await startEgressProxy({ policy, log });
+  let context;
+  try {
+    context = await launch(profileDir, {
+      headless: config.mode === 'headless',
+      viewport: VIEWPORT,
+      serviceWorkers: 'block',
+      // Chromium sends loopback requests around a proxy unless the bypass
+      // list names <-loopback>. Playwright adds it unless
+      // PLAYWRIGHT_DISABLE_FORCED_CHROMIUM_PROXIED_LOOPBACK is set; naming it
+      // here keeps it either way.
+      proxy: { server: proxy.url, bypass: '<-loopback>' },
+      args: WEBRTC_PROXIED_ONLY,
+      chromiumSandbox: config.chromiumSandbox,
+      handleSIGINT: false,
+      handleSIGTERM: false,
+      handleSIGHUP: false,
+    });
+  } catch (error) {
+    await proxy.close();
+    await removeDirectories();
+    throw error;
+  }
+
+  await installNetworkPolicy(context, policy);
+  if (config.storageState) await context.setStorageState(config.storageState);
+  const guard = new NavigationGuard({ policy, log });
+  guard.attach(context);
+  const recorder = config.recording ? new Recorder({ recording: config.recording, log }) : null;
+  await recorder?.attach(context);
+  const live = config.live ? await startLiveView(config, context, { recorder, log }) : null;
+
+  const gateway = new McpGateway({
+    connect: () => connect(mcpConfig(config, outputDir), async () => context),
+    policy,
+    guard,
+    snapshotDir: await realpath(outputDir),
+    lock: live?.lock,
+    agentWaitMs: config.live?.agentWaitMs,
+    afterCall: (name, args) => {
+      // Playwright MCP numbers tabs from 0 in the order they opened, as context.pages() lists them.
+      if (live && name === 'browser_tabs' && args?.action === 'select' && Number.isInteger(args.index)) void live.screencast.followIndex(args.index);
+    },
+  });
+  let hosts = new Set();
+  const liveOrigins = new Set(config.live?.origins ?? []);
+  const server = createHttpServer({
+    rules: () => ({ token: config.token, hosts, liveOrigins }),
+    gateway,
+    version: VERSION,
+    live: live?.server,
+    storageState: () => exportStorageState(context, config.appOrigin),
+  });
+
+  let closing = null;
+  let finished;
+  const done = new Promise((resolve) => {
+    finished = resolve;
+  });
+  // The first reason to stop decides the exit status: closing the context
+  // here fires its close event too.
+  const close = (reason, exitCode = 0) => {
+    closing ??= (async () => {
+      if (reason) log(`stopping: ${reason}`);
+      server.close();
+      server.closeAllConnections();
+      live?.server.close();
+      await live?.screencast.close();
+      await gateway.closeAll();
+      // The pages hand over the rrweb events they hold, then the context
+      // closes before the recorder, so the recording gets the closing markers.
+      if (recorder) await new Promise((resolve) => setTimeout(resolve, PAGE_FLUSH_MS * 2));
+      await context.close().catch(() => {});
+      await proxy.close();
+      await recorder?.close(RECORDING_DRAIN_MS);
+      await removeDirectories();
+      finished(exitCode);
+      return exitCode;
+    })();
+    return closing;
+  };
+  context.on('close', () => void close('the browser closed', 1));
+
+  try {
+    await new Promise((resolve, reject) => {
+      server.once('error', reject);
+      server.listen(config.port, config.host, resolve);
+    });
+  } catch (error) {
+    await close();
+    throw error;
+  }
+  const { port } = server.address();
+  hosts = acceptedHosts(config.host, port, config.allowedHosts);
+
+  if (config.stopAt !== null) stopAt(config.stopAt, () => void close('the sandbox expired'));
+
+  // The first page opens on the app, so the recording starts there.
+  const [page] = context.pages();
+  page?.goto(config.appOrigin).catch((error) => log(`could not open ${config.appOrigin}: ${error.message}`));
+
+  return { port, close, done };
+}

package/lib/storage-state.mjs

@@ -0,0 +1,76 @@
+// A Playwright storage state (cookies and per-origin localStorage) limited to
+// the sandbox app, the only site its browser opens. The engine keeps one
+// as a project secret, so a later browser of the same app starts signed in.
+
+const SAME_SITE = new Set(['Strict', 'Lax', 'None']);
+
+export class StorageStateError extends Error {}
+
+function fail(message) {
+  throw new StorageStateError(message);
+}
+
+// Whether a cookie for `domain` is sent to `hostname`: the same host, or a
+// parent domain the cookie names with or without its leading dot.
+function cookieDomainMatches(domain, hostname) {
+  const bare = String(domain).replace(/^\./, '').toLowerCase();
+  return bare !== '' && (hostname === bare || hostname.endsWith(`.${bare}`));
+}
+
+function cookie(value, index) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) fail(`cookie ${index + 1} must be an object`);
+  for (const key of ['name', 'value', 'domain', 'path']) {
+    if (typeof value[key] !== 'string') fail(`cookie ${index + 1} needs a string ${key}`);
+  }
+
+  const result = { name: value.name, value: value.value, domain: value.domain, path: value.path || '/' };
+  result.expires = Number.isFinite(value.expires) ? value.expires : -1;
+  result.httpOnly = value.httpOnly === true;
+  result.secure = value.secure === true;
+  result.sameSite = SAME_SITE.has(value.sameSite) ? value.sameSite : 'Lax';
+  return result;
+}
+
+function origin(value, index) {
+  if (!value || typeof value !== 'object' || typeof value.origin !== 'string') fail(`origin ${index + 1} needs an origin`);
+  const localStorage = value.localStorage ?? [];
+  if (!Array.isArray(localStorage) || localStorage.some((item) => typeof item?.name !== 'string' || typeof item?.value !== 'string')) {
+    fail(`origin ${index + 1}'s localStorage must be a list of { name, value } strings`);
+  }
+  return { origin: value.origin, localStorage: localStorage.map(({ name, value: item }) => ({ name, value: item })) };
+}
+
+/**
+ * Validates a storage state and returns the part of it that belongs to
+ * `appOrigin`: the cookies its host is sent and the localStorage of that
+ * origin. Anything else is dropped rather than refused, since a state saved
+ * from a browser that followed a link elsewhere still signs the app in.
+ *
+ * @param {object} state { cookies: [...], origins: [...] }
+ * @param {string} appOrigin e.g. "http://127.0.0.1:3000"
+ * @returns {{ cookies: object[], origins: object[] }}
+ * @throws {StorageStateError} naming the first malformed entry
+ */
+export function appStorageState(state, appOrigin) {
+  if (!state || typeof state !== 'object' || Array.isArray(state)) fail('storage_state must be an object');
+  const cookies = state.cookies ?? [];
+  const origins = state.origins ?? [];
+  if (!Array.isArray(cookies) || !Array.isArray(origins)) fail('storage_state needs cookies and origins lists');
+
+  const { hostname } = new URL(appOrigin);
+  return {
+    cookies: cookies.map(cookie).filter((entry) => cookieDomainMatches(entry.domain, hostname.toLowerCase())),
+    origins: origins.map(origin).filter((entry) => entry.origin === appOrigin),
+  };
+}
+
+/**
+ * The browser context's storage state limited to `appOrigin` (see
+ * appStorageState).
+ *
+ * @param {import('playwright').BrowserContext} context
+ * @param {string} appOrigin
+ */
+export async function exportStorageState(context, appOrigin) {
+  return appStorageState(await context.storageState(), appOrigin);
+}

package/lib/version.mjs

@@ -0,0 +1,5 @@
+import { readFileSync } from 'node:fs';
+
+// The engine refuses a sidecar whose version is not its own, so the version
+// is read from the package the code shipped in rather than kept twice.
+export const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@activeagents/browser-sidecar",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.9.0",
+  "description": "One sandbox's browser for the Active Agent dashboard: Chromium driven over Playwright MCP, recorded with rrweb.",
+  "license": "MIT",
+  "type": "module",
+  "homepage": "https://docs.activeagents.ai/framework/browser-sessions",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/activeagents/activeagent.git",
+    "directory": "browser-sidecar"
+  },
+  "bugs": "https://github.com/activeagents/activeagent/issues",
+  "bin": {
+    "activeagents-browser-sidecar": "bin/browser-sidecar.mjs"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test --test-timeout=120000 test/*.test.mjs"
+  },
+  "dependencies": {
+    "@playwright/mcp": "0.0.83",
+    "@rrweb/record": "2.1.7",
+    "playwright": "1.64.0-alpha-1790635538000",
+    "ws": "8.22.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}