@monoes/monobrowse 1.0.26 → 1.0.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monoes/monobrowse",
-  "version": "1.0.26",
+  "version": "1.0.28",
   "description": "Native browser automation via Chrome DevTools Protocol — the engine powering monomind browse",
   "type": "module",
   "bin": {

package/src/__tests__/disconnect-session.test.ts

@@ -0,0 +1,42 @@
+/**
+ * disconnectSession() — drops this process's CDP connection without touching
+ * the browser (#408).
+ *
+ * `monomind browse` runs inside a CLI that lets the event loop drain instead
+ * of calling process.exit() (ADR-R001). A CDP websocket left open after the
+ * subcommand printed its output kept every `monomind browse …` alive until the
+ * 5 s force-exit watchdog. The embedder calls disconnectSession() once the
+ * subcommand is done; the browser must survive it, because the next command
+ * (a new process) reconnects to that same session.
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+import type { CdpClient } from '../browser/cdp.js';
+import { disconnectSession } from '../cli/commands.js';
+import { session } from '../cli/session.js';
+
+describe('disconnectSession', () => {
+  it('closes the CDP client and clears it, leaving the session record alone', () => {
+    const close = vi.fn();
+    const send = vi.fn();
+    session.client = { close, send } as unknown as CdpClient;
+    session.sessionId = 'sid-1';
+    session.port = 9333;
+
+    disconnectSession();
+
+    expect(close).toHaveBeenCalledTimes(1);
+    // No CDP command either: Browser.close would end the session others reuse.
+    expect(send).not.toHaveBeenCalled();
+    expect(session.client).toBeNull();
+    expect(session.sessionId).toBe('');
+    // The port pin survives so a later in-process command resolves the same session.
+    expect(session.port).toBe(9333);
+  });
+
+  it('is a no-op when no client was ever connected', () => {
+    session.client = null;
+    expect(() => disconnectSession()).not.toThrow();
+    expect(session.client).toBeNull();
+  });
+});

package/src/__tests__/profile-cleanup-close.test.ts

@@ -0,0 +1,285 @@
+/**
+ * #395: closing (or killing) a browser monobrowse launched deletes the temp
+ * profile dir monobrowse created for it — and never a caller-supplied one.
+ *
+ * No real Chrome: launchBrowser spawns a fake-chrome script that behaves
+ * like Chrome where it matters here (creates and writes into its
+ * --user-data-dir, serves /json/version, announces its browser id on stderr,
+ * writes DevToolsActivePort for port 0). Browser.close goes over a fake `ws`
+ * socket that kills the fixture, as a real Chrome exits on it. A client that
+ * never connected drives the kill fallback (its Browser.close fails at once).
+ *
+ * TMPDIR is pointed at a root of each test's own, so both the launch-time
+ * sweep and the default profile dir live there — never the real /tmp.
+ */
+
+import { type ChildProcess, spawn } from 'node:child_process';
+import { chmodSync, existsSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs';
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { createServer } from 'node:net';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+let onBrowserClose: (() => void) | null = null;
+let lastSocket: FakeWs | null = null;
+
+/** Acknowledges every command; `Browser.close` also runs onBrowserClose. */
+class FakeWs {
+  handlers = new Map<string, Array<(...a: unknown[]) => void>>();
+  constructor(public url: string) {
+    lastSocket = this;
+  }
+  on(event: string, fn: (...a: unknown[]) => void): void {
+    if (!this.handlers.has(event)) this.handlers.set(event, []);
+    this.handlers.get(event)!.push(fn);
+  }
+  emit(event: string, ...args: unknown[]): void {
+    for (const fn of [...(this.handlers.get(event) ?? [])]) fn(...args);
+  }
+  send(data: string): void {
+    const { id, method } = JSON.parse(data) as { id: number; method: string };
+    if (method === 'Browser.close') onBrowserClose?.();
+    queueMicrotask(() => this.emit('message', Buffer.from(JSON.stringify({ id, result: {} }))));
+  }
+  close(): void {}
+}
+
+vi.mock('ws', () => ({ WebSocket: FakeWs }));
+
+// Exits once the test process is gone, and within a minute regardless, so a
+// fixture never outlives the run.
+const FAKE_CHROME = `#!/usr/bin/env node
+const parent = process.ppid;
+setInterval(() => {
+  try { if (process.ppid !== parent) process.exit(0); process.kill(parent, 0); } catch { process.exit(0); }
+}, 1000).unref();
+setTimeout(() => process.exit(0), 60000).unref();
+const { createServer } = require('node:http');
+const { mkdirSync, writeFileSync } = require('node:fs');
+const { join } = require('node:path');
+const arg = (k) => process.argv.find((a) => a.startsWith(k + '=')).slice(k.length + 1);
+const dir = arg('--user-data-dir');
+const wanted = Number(arg('--remote-debugging-port'));
+mkdirSync(join(dir, 'Default'), { recursive: true });
+writeFileSync(join(dir, 'Default', 'Preferences'), '{}');
+const server = createServer((req, res) => {
+  const port = server.address().port;
+  const ws = 'ws://127.0.0.1:' + port + '/devtools/browser/fake-' + process.pid;
+  res.writeHead(200, { 'Content-Type': 'application/json' });
+  res.end(req.url === '/json/version'
+    ? JSON.stringify({ Browser: 'Chrome/999.0.0.0', webSocketDebuggerUrl: ws })
+    : '[]');
+});
+server.listen(wanted, '127.0.0.1', () => {
+  const port = server.address().port;
+  if (wanted === 0) writeFileSync(join(dir, 'DevToolsActivePort'), port + '\\n/devtools/browser/fake');
+  process.stderr.write('DevTools listening on ws://127.0.0.1:' + port + '/devtools/browser/fake-' + process.pid + '\\n');
+});
+`;
+
+let root: string;
+let fixtures: string;
+let cwd: string;
+let exe: string;
+const children: ChildProcess[] = [];
+const launchedPids: number[] = [];
+
+beforeEach(async () => {
+  root = await mkdtemp(join(tmpdir(), 'monobrowse-395-root-'));
+  fixtures = await mkdtemp(join(tmpdir(), 'monobrowse-395-fixture-'));
+  cwd = await mkdtemp(join(tmpdir(), 'monobrowse-395-cwd-'));
+  vi.stubEnv('TMPDIR', root);
+  vi.spyOn(process, 'cwd').mockReturnValue(cwd);
+  exe = join(fixtures, 'fake-chrome.cjs');
+  writeFileSync(exe, FAKE_CHROME);
+  chmodSync(exe, 0o755);
+  onBrowserClose = null;
+  lastSocket = null;
+  vi.resetModules();
+});
+
+afterEach(async () => {
+  vi.unstubAllEnvs();
+  vi.restoreAllMocks();
+  for (const pid of launchedPids.splice(0)) {
+    try {
+      process.kill(pid, 'SIGKILL');
+    } catch {
+      /* already gone */
+    }
+  }
+  for (const child of children.splice(0)) child.kill('SIGKILL');
+  for (const dir of [root, fixtures, cwd]) await rm(dir, { recursive: true, force: true });
+});
+
+function freePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const server = createServer();
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      const { port } = server.address() as { port: number };
+      server.close(() => resolve(port));
+    });
+  });
+}
+
+/** A client whose Browser.close is acknowledged, and makes `pid` exit the
+ *  way Chrome does on it. */
+async function gracefulClient(pid: number) {
+  const { CdpClient } = await import('../browser/cdp.js');
+  const client = new CdpClient();
+  const p = client.connect('ws://127.0.0.1:1/devtools/browser/fake');
+  lastSocket!.emit('open');
+  await p;
+  onBrowserClose = () => process.kill(pid, 'SIGTERM');
+  return client;
+}
+
+/** A client that never connected: Browser.close fails at once, so
+ *  closeBrowser takes its kill fallback. */
+async function deadClient() {
+  const { CdpClient } = await import('../browser/cdp.js');
+  return new CdpClient();
+}
+
+async function launch(config: Record<string, unknown>) {
+  const browser = await import('../browser/browser.js');
+  const port = await browser.launchBrowser({ executablePath: exe, ...config });
+  const pid = browser.getLaunchedPid(port)!;
+  launchedPids.push(pid);
+  return { browser, port, pid, dir: browser.getLaunchedUserDataDir(port)! };
+}
+
+describe.skipIf(process.platform === 'win32')('#395 profile dir cleanup on close', () => {
+  it('launch then graceful close removes the default profile dir it created', async () => {
+    const { browser, port, pid, dir } = await launch({ port: await freePort() });
+    expect(dir.startsWith(root)).toBe(true);
+    expect(existsSync(join(dir, 'Default', 'Preferences'))).toBe(true);
+    expect(browser.ownsLaunchedUserDataDir(port)).toBe(true);
+
+    await browser.closeBrowser(await gracefulClient(pid), port);
+
+    expect(existsSync(dir)).toBe(false);
+  }, 20_000);
+
+  it('removes a CLI session profile (port 0, ownsUserDataDir) on close', async () => {
+    const browser = await import('../browser/browser.js');
+    const { sessionProfileDirPath } = await import('../browser/profile-dir.js');
+    const own = sessionProfileDirPath('abcdef12');
+    expect(own.startsWith(root)).toBe(true);
+    const { port, pid, dir } = await launch({ port: 0, userDataDir: own, ownsUserDataDir: true });
+    expect(dir).toBe(own);
+
+    await browser.closeBrowser(await gracefulClient(pid), port);
+
+    expect(existsSync(own)).toBe(false);
+  }, 20_000);
+
+  it('never deletes a caller-supplied userDataDir, even one named like ours', async () => {
+    const mine = join(root, 'my-profile');
+    const lookalike = join(root, `monomind-browse-${process.pid}-0badc0de`);
+    for (const userDataDir of [mine, lookalike]) {
+      mkdirSync(userDataDir);
+      const { browser, port, pid } = await launch({ port: 0, userDataDir });
+      expect(browser.ownsLaunchedUserDataDir(port)).toBe(false);
+      await browser.closeBrowser(await gracefulClient(pid), port);
+      expect(existsSync(join(userDataDir, 'Default', 'Preferences')), userDataDir).toBe(true);
+    }
+  }, 30_000);
+
+  it('the kill fallback removes the created dir once the process is gone', async () => {
+    const { browser, port, pid, dir } = await launch({ port: await freePort() });
+    expect(existsSync(dir)).toBe(true);
+
+    await browser.closeBrowser(await deadClient(), port);
+
+    expect(() => process.kill(pid, 0)).toThrow();
+    expect(existsSync(dir)).toBe(false);
+  }, 20_000);
+
+  it('a failed launch removes the profile dir it created', async () => {
+    const dying = join(fixtures, 'dying-chrome.cjs');
+    writeFileSync(
+      dying,
+      `#!/usr/bin/env node
+const dir = process.argv.find((a) => a.startsWith('--user-data-dir=')).slice(16);
+require('node:fs').mkdirSync(dir, { recursive: true });
+process.exit(1);
+`,
+    );
+    chmodSync(dying, 0o755);
+    const browser = await import('../browser/browser.js');
+    const port = await freePort();
+    await expect(
+      browser.launchBrowser({ port, strictPort: true, executablePath: dying }),
+    ).rejects.toThrow(/exited before the CDP endpoint opened/);
+
+    expect(readdirSync(root)).toEqual([]);
+  }, 20_000);
+});
+
+describe.skipIf(process.platform === 'win32')(
+  '#395 fresh-process close via the persisted session',
+  () => {
+    /** A live stand-in for a Chrome some earlier CLI process launched, its
+     *  profile dir, and the session record that process left behind. */
+    async function persistedSession(ownsUserDataDir: boolean | undefined) {
+      const dir = join(
+        root,
+        `monomind-browse-${process.pid}-5e55107${ownsUserDataDir ? 'a' : 'b'}`,
+      );
+      await mkdir(join(dir, 'Default'), { recursive: true });
+      await writeFile(join(dir, 'Default', 'Preferences'), '{}');
+      const child = spawn(process.execPath, ['-e', 'setInterval(() => {}, 1000)'], {
+        stdio: 'ignore',
+      });
+      children.push(child);
+      await new Promise((resolve) => child.once('spawn', resolve));
+      const port = await freePort();
+      const sessions = join(cwd, '.monomind', 'monobrowse', 'sessions');
+      await mkdir(sessions, { recursive: true });
+      await writeFile(
+        join(sessions, `${port}.json`),
+        JSON.stringify({
+          port,
+          launched: true,
+          pid: child.pid,
+          userDataDir: dir,
+          ownsUserDataDir,
+          savedAt: Date.now(),
+        }),
+      );
+      return { dir, pid: child.pid!, port };
+    }
+
+    it('removes the dir when the record says monobrowse owns it', async () => {
+      const { dir, port } = await persistedSession(true);
+      const browser = await import('../browser/browser.js');
+      const { loadSessionRecord } = await import('../browser/ref-cache.js');
+      expect((await loadSessionRecord(port))?.ownsUserDataDir).toBe(true);
+
+      await browser.closeBrowser(await deadClient(), port);
+
+      expect(existsSync(dir)).toBe(false);
+    }, 20_000);
+
+    it('keeps the dir (still killing the browser) when the record has no ownership flag', async () => {
+      const { dir, pid, port } = await persistedSession(undefined);
+      const browser = await import('../browser/browser.js');
+
+      await browser.closeBrowser(await deadClient(), port);
+
+      for (let i = 0; i < 40; i++) {
+        try {
+          process.kill(pid, 0);
+        } catch {
+          break;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 50));
+      }
+      expect(() => process.kill(pid, 0)).toThrow();
+      expect(existsSync(join(dir, 'Default', 'Preferences'))).toBe(true);
+    }, 20_000);
+  },
+);

package/src/__tests__/profile-dir.test.ts

@@ -0,0 +1,196 @@
+/**
+ * #395: the crash sweep and ownership checks for the temp Chrome profiles
+ * monobrowse creates (profile-dir.ts).
+ *
+ * Every test sweeps a root of its own made with mkdtemp — never the real
+ * /tmp, where other sessions' live Chrome profiles live. (The whole package
+ * run also gets a throwaway TMPDIR, see setup/isolated-tmpdir.global.ts.)
+ */
+
+import { type ChildProcess, spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { lutimes, mkdir, mkdtemp, rm, symlink, utimes, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import {
+  isOwnedProfileDir,
+  isProfileDirInUse,
+  profileDirOwnerPid,
+  removeOwnedProfileDir,
+  sweepStaleProfileDirs,
+} from '../browser/profile-dir.js';
+
+let root: string;
+let outside: string;
+const children: ChildProcess[] = [];
+const HOUR_AGO = new Date(Date.now() - 60 * 60 * 1000);
+
+beforeEach(async () => {
+  root = await mkdtemp(join(tmpdir(), 'monobrowse-sweep-root-'));
+  outside = await mkdtemp(join(tmpdir(), 'monobrowse-sweep-outside-'));
+});
+
+afterEach(async () => {
+  for (const child of children.splice(0)) child.kill('SIGKILL');
+  await rm(root, { recursive: true, force: true });
+  await rm(outside, { recursive: true, force: true });
+});
+
+/** A pid that belonged to a process which has since exited. */
+async function deadPid(): Promise<number> {
+  const child = spawn(process.execPath, ['-e', ''], { stdio: 'ignore' });
+  await new Promise((resolve) => child.once('exit', resolve));
+  return child.pid!;
+}
+
+/** A live process whose command line passes `--user-data-dir=<dir>`, the way
+ *  Chrome's own does. */
+async function holder(dir: string): Promise<ChildProcess> {
+  const child = spawn(
+    process.execPath,
+    ['-e', 'setInterval(() => {}, 1000)', '--', `--user-data-dir=${dir}`],
+    { stdio: 'ignore' },
+  );
+  children.push(child);
+  await new Promise((resolve) => child.once('spawn', resolve));
+  return child;
+}
+
+/** A profile-looking directory with some content, backdated past the grace. */
+async function profile(name: string, opts: { young?: boolean } = {}): Promise<string> {
+  const dir = join(root, name);
+  await mkdir(join(dir, 'Default'), { recursive: true });
+  await writeFile(join(dir, 'Default', 'Preferences'), '{}');
+  if (!opts.young) await utimes(dir, HOUR_AGO, HOUR_AGO);
+  return dir;
+}
+
+describe('#395 profileDirOwnerPid', () => {
+  it('reads the pid from exactly our two name patterns', () => {
+    expect(profileDirOwnerPid('monomind-browser-9222-1234-0a1b2c3d')).toBe(1234);
+    expect(profileDirOwnerPid('monomind-browse-4321-0a1b2c3d')).toBe(4321);
+    for (const name of [
+      'monomind-browse-4321-0A1B2C3D',
+      'monomind-browse-4321-0a1b2c3d0',
+      'monomind-browse-x-0a1b2c3d',
+      'monomind-browser-4321-0a1b2c3d',
+      'xmonomind-browse-4321-0a1b2c3d',
+      'org.chromium.Chromium.abc123',
+    ]) {
+      expect(profileDirOwnerPid(name), name).toBeNull();
+    }
+  });
+});
+
+describe('#395 sweepStaleProfileDirs', () => {
+  it('deletes stale dirs whose owner is dead and nothing uses', async () => {
+    const pid = await deadPid();
+    const a = await profile(`monomind-browser-9222-${pid}-aaaaaaaa`);
+    const b = await profile(`monomind-browse-${pid}-bbbbbbbb`);
+
+    const removed = await sweepStaleProfileDirs({ root });
+
+    expect(removed.sort()).toEqual([a, b].sort());
+    expect(existsSync(a)).toBe(false);
+    expect(existsSync(b)).toBe(false);
+  });
+
+  it('keeps young dirs, dirs whose pid is alive, non-matching names, symlinks and files', async () => {
+    const pid = await deadPid();
+    const young = await profile(`monomind-browse-${pid}-cccccccc`, { young: true });
+    const alive = await profile(`monomind-browse-${process.pid}-dddddddd`);
+    const foreign = [
+      await profile('org.chromium.Chromium.abc123'),
+      await profile(`monomind-browse-${pid}-ABCDEF12`),
+      await profile(`monomind-browse-${pid}-abcdef12-extra`),
+      await profile(`other-monomind-browse-${pid}-abcdef12`),
+    ];
+    // A symlink with our name, pointing out of the root at a real profile.
+    const target = join(outside, 'victim');
+    await mkdir(target);
+    await writeFile(join(target, 'keep.txt'), 'keep');
+    const link = join(root, `monomind-browse-${pid}-11111111`);
+    await symlink(target, link);
+    await lutimes(link, HOUR_AGO, HOUR_AGO);
+    // A plain file with our name.
+    const file = join(root, `monomind-browse-${pid}-22222222`);
+    await writeFile(file, 'not a dir');
+    await utimes(file, HOUR_AGO, HOUR_AGO);
+
+    expect(await sweepStaleProfileDirs({ root })).toEqual([]);
+
+    for (const kept of [young, alive, ...foreign, link, file]) expect(existsSync(kept)).toBe(true);
+    expect(existsSync(join(target, 'keep.txt'))).toBe(true);
+  });
+
+  it.skipIf(process.platform !== 'linux')(
+    'keeps a dir a live process uses as --user-data-dir, though its named pid is dead',
+    async () => {
+      // A CLI `open` exits right after launching, so the pid in the name is
+      // dead while its Chrome runs on: only the live user of the dir says so.
+      const pid = await deadPid();
+      const inUse = await profile(`monomind-browse-${pid}-eeeeeeee`);
+      await holder(inUse);
+
+      expect(await sweepStaleProfileDirs({ root })).toEqual([]);
+      expect(existsSync(inUse)).toBe(true);
+    },
+  );
+
+  it('without /proc, keeps a dir whose SingletonLock names a live pid', async () => {
+    const pid = await deadPid();
+    const locked = await profile(`monomind-browse-${pid}-ffffffff`);
+    await symlink(`somehost-${process.pid}`, join(locked, 'SingletonLock'));
+    await utimes(locked, HOUR_AGO, HOUR_AGO);
+    const staleLock = await profile(`monomind-browse-${pid}-99999999`);
+    await symlink(`somehost-${pid}`, join(staleLock, 'SingletonLock'));
+    await utimes(staleLock, HOUR_AGO, HOUR_AGO);
+
+    expect(await sweepStaleProfileDirs({ root, procDir: null })).toEqual([staleLock]);
+    expect(existsSync(locked)).toBe(true);
+  });
+
+  it('never throws, and sweeps nothing, when the root is missing', async () => {
+    await expect(sweepStaleProfileDirs({ root: join(root, 'missing') })).resolves.toEqual([]);
+  });
+});
+
+describe('#395 isOwnedProfileDir / removeOwnedProfileDir', () => {
+  it('refuses a caller-supplied dir, a dir outside the root, and a symlink', async () => {
+    const caller = join(root, 'my-profile');
+    await mkdir(caller);
+    const nested = join(root, 'sub', `monomind-browse-${process.pid}-aaaaaaaa`);
+    await mkdir(nested, { recursive: true });
+    const target = join(outside, 'victim');
+    await mkdir(target);
+    const link = join(root, `monomind-browse-${process.pid}-bbbbbbbb`);
+    await symlink(target, link);
+
+    for (const dir of [caller, nested, link]) {
+      expect(await isOwnedProfileDir(dir, root), dir).toBe(false);
+      expect(await removeOwnedProfileDir(dir, { root }), dir).toBe(false);
+      expect(existsSync(dir), dir).toBe(true);
+    }
+    expect(existsSync(target)).toBe(true);
+  });
+
+  it('removes an owned dir once its browser pid has exited', async () => {
+    const dir = await profile(`monomind-browse-${process.pid}-cccccccc`, { young: true });
+    const pid = await deadPid();
+    expect(await removeOwnedProfileDir(dir, { root, pid })).toBe(true);
+    expect(existsSync(dir)).toBe(false);
+  });
+
+  it.skipIf(process.platform !== 'linux')(
+    'keeps an owned dir while a live process still uses it',
+    async () => {
+      const dir = await profile(`monomind-browse-${process.pid}-dddddddd`, { young: true });
+      const child = await holder(dir);
+      expect(await isProfileDirInUse(dir)).toBe(true);
+      expect(await removeOwnedProfileDir(dir, { root, pid: child.pid })).toBe(false);
+      expect(existsSync(dir)).toBe(true);
+    },
+    15_000,
+  );
+});

package/src/__tests__/setup/isolated-tmpdir.global.ts

@@ -0,0 +1,28 @@
+/**
+ * Vitest globalSetup: run every monobrowse test worker against a throwaway
+ * TMPDIR (#395).
+ *
+ * launchBrowser() sweeps stale `monomind-browser-*` / `monomind-browse-*`
+ * profile dirs out of os.tmpdir() on every launch. The sweep only removes
+ * dead, idle, unused dirs, but a test run must never touch the real /tmp at
+ * all: other sessions' live Chrome profiles live there. Set in the main
+ * process before any worker starts, so workers and the CLI processes tests
+ * spawn inherit it.
+ */
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+export default function setup(): () => void {
+  const saved = process.env.TMPDIR;
+  // Short on purpose: real-Chrome tests nest their own dirs under it, and
+  // Chrome aborts at startup (SIGABRT) once the unix socket path it makes in
+  // TMPDIR (…/org.chromium.Chromium.XXXXXX/SingletonSocket) passes ~107 bytes.
+  const dir = mkdtempSync(join(tmpdir(), 'mb-'));
+  process.env.TMPDIR = dir;
+  return () => {
+    if (saved === undefined) delete process.env.TMPDIR;
+    else process.env.TMPDIR = saved;
+    rmSync(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 200 });
+  };
+}

package/src/browser/actions-eval.ts

@@ -0,0 +1,118 @@
+import type { CdpClient } from './cdp.js';
+
+export async function pushState(client: CdpClient, sessionId: string, url: string): Promise<void> {
+  // Try Next.js router first, then fallback to history.pushState
+  await evaluateJs(
+    client,
+    sessionId,
+    `
+    (function() {
+      const url = ${JSON.stringify(url)};
+      if (window.next && window.next.router) {
+        window.next.router.push(url).catch(function() {});
+        return;
+      } else {
+        history.pushState({}, '', url);
+        window.dispatchEvent(new PopStateEvent('popstate'));
+      }
+    })()
+  `,
+  );
+}
+
+export async function addInitScript(
+  client: CdpClient,
+  sessionId: string,
+  script: string,
+): Promise<string> {
+  const result = await client.send<{ identifier: string }>(
+    'Page.addScriptToEvaluateOnNewDocument',
+    {
+      source: script,
+    },
+    sessionId,
+  );
+  return result.identifier;
+}
+
+export async function removeInitScript(
+  client: CdpClient,
+  sessionId: string,
+  identifier: string,
+): Promise<void> {
+  await client.send('Page.removeScriptToEvaluateOnNewDocument', { identifier }, sessionId);
+}
+
+// Default cap on how long an evaluateJs() call waits for Runtime.evaluate to
+// resolve. Because this always passes `awaitPromise: true`, an expression
+// like `new Promise(() => {})` never settles — the underlying CdpClient.send()
+// has no timeout of its own (the CDP_RESPONSE_SIZE_LIMIT in cdp.ts only guards
+// the HTTP /json/* endpoints, not WebSocket command responses), so without
+// this the caller (e.g. the `eval` CLI command) would hang forever with
+// nothing to kill it.
+const DEFAULT_EVAL_TIMEOUT_MS = 30_000;
+
+export async function evaluateJs(
+  client: CdpClient,
+  sessionId: string,
+  expression: string,
+  timeoutMs: number = DEFAULT_EVAL_TIMEOUT_MS,
+): Promise<unknown> {
+  const evalPromise = client.send<{
+    result: { value?: unknown; type: string; description?: string };
+    exceptionDetails?: { text: string; exception?: { description?: string } };
+  }>(
+    'Runtime.evaluate',
+    {
+      expression,
+      returnByValue: true,
+      awaitPromise: true,
+    },
+    sessionId,
+  );
+
+  // Not unref'd (same rule as CdpClient.send): this timer settles the awaited
+  // race, so it has to hold the event loop open while the evaluation is in
+  // flight. Cleared in the finally so a fast evaluation does not keep the
+  // process alive for the rest of timeoutMs.
+  let evalTimer: ReturnType<typeof setTimeout> | undefined;
+  let result: Awaited<typeof evalPromise>;
+  try {
+    result = await (timeoutMs > 0
+      ? Promise.race([
+          evalPromise,
+          new Promise<never>((_, reject) => {
+            evalTimer = setTimeout(
+              () => reject(new Error(`JS evaluation timed out after ${timeoutMs}ms`)),
+              timeoutMs,
+            );
+          }),
+        ])
+      : evalPromise);
+  } finally {
+    clearTimeout(evalTimer);
+  }
+
+  if (result.exceptionDetails) {
+    throw new Error(
+      `JS evaluation error: ${result.exceptionDetails.exception?.description ?? result.exceptionDetails.text}`,
+    );
+  }
+
+  return result.result?.value;
+}
+
+export async function readClipboard(client: CdpClient, sessionId: string): Promise<string> {
+  const result = await evaluateJs(client, sessionId, 'navigator.clipboard.readText()');
+  return result as string;
+}
+
+export async function writeClipboard(
+  client: CdpClient,
+  sessionId: string,
+  text: string,
+): Promise<void> {
+  // Cap to 100 KB to prevent OOM when serializing the CDP expression
+  const safeText = text.length > 102_400 ? text.slice(0, 102_400) : text;
+  await evaluateJs(client, sessionId, `navigator.clipboard.writeText(${JSON.stringify(safeText)})`);
+}