Skip to content

An agentic browser harness: an AI side panel & orb in your own logged-in Chrome, Edge, Arc, Brave or even Firefox run by the agent/subscription you already use (Claude Code, Codex, Antigravity). Free, open source, no API key. Also an MCP server.

14.0 KB
Raw Blame
import { beforeEach, describe, expect, test, vi } from 'vitest';
import { fakeBrowser } from 'wxt/testing';
import { success } from '@/lib/actions/protocol';
import { BLOCKED_SITES_KEY } from '@/lib/settings/blocked-sites';

const SERIAL = 'emulator-5554';
const HOME = 'A'.repeat(32);
const OTHER = 'B'.repeat(32);

const phone = vi.hoisted(() => ({
  sent: [] as { method: string; params?: Record<string, unknown> }[],
  location: 'https://news.example/',
  fronted: [] as string[],
  followed: [] as string[],
  tree: undefined as { frame: { id: string; url: string }; childFrames?: { frame: { id: string; url: string } }[] } | undefined,
  read: () => undefined as void,
}));

vi.mock('./socket', () => ({
  DAEMON_STATE_KEY: 'browsentic/daemon',
  sendCdp: async (_serial: string, method: string, params?: Record<string, unknown>) => {
    phone.sent.push({ method, params });
    if (method === 'Page.navigate') phone.location = String(params?.url);
    if (method === 'Page.getFrameTree') return success(phone.tree ? { frameTree: phone.tree } : {});
    if (method === 'Page.createIsolatedWorld') return success({ executionContextId: 1 });
    if (method === 'DOM.describeNode') return success({ node: { frameId: 'AD' } });
    if (method === 'Runtime.evaluate' && String(params?.expression).startsWith('__browsenticPhone.frame')) return success({ result: { objectId: 'IFRAME' } });
    if (method === 'Runtime.evaluate' && String(params?.expression).startsWith('__browsenticPhone.dispatch')) {
      phone.read();
      return success({ result: { value: { ok: true, data: { text: 'what the page says' } } } });
    }
    if (method === 'Runtime.evaluate') return success({ result: { value: JSON.stringify({ url: phone.location, title: 'Landed', readyState: 'complete' }) } });
    if (method === 'Target.createTarget') return success({ targetId: 'C'.repeat(32) });
    if (method === 'Page.getLayoutMetrics') return success({ cssVisualViewport: { clientWidth: 411, clientHeight: 675 } });
    return success({});
  },
  closePhone: () => undefined,
  openPhone: async () => success({}),
  launchPhoneChrome: async () => success({}),
  onPhoneClosed: () => undefined,
  onDaemonClosed: () => undefined,
}));

vi.mock('./phone-mirror', () => ({
  attachedSession: async (_serial: string, targetId: string) => `session-${targetId}`,
  bringToFront: async (_serial: string, targetId: string) => void phone.fronted.push(targetId),
  followTarget: async (targetId: string) => void phone.followed.push(targetId),
}));

const { invokeOnPhone, phoneRoute } = await import('./phone-invoke');
const { phoneAnchor, phoneContext } = await import('./phone-conversation');
const { invokeForHarness } = await import('./invoke');
const { ensureSessionForTab, patchSession } = await import('./tab-sessions');

let mirrorTabId: number;
let desktopTabId: number;

beforeEach(async () => {
  fakeBrowser.reset();
  phone.sent.length = 0;
  phone.fronted.length = 0;
  phone.followed.length = 0;
  phone.location = 'https://news.example/';
  phone.tree = undefined;
  phone.read = () => undefined;
  vi.stubGlobal('fetch', async () => new Response('/* the bundle */'));
  desktopTabId = (await fakeBrowser.tabs.create({ url: 'https://desktop.example/', active: false })).id!;
  mirrorTabId = (await fakeBrowser.tabs.create({ url: 'chrome-extension://abc/phone.html', active: true })).id!;
  await fakeBrowser.storage.session.set({
    'browsentic/phone': {
      serial: SERIAL,
      model: 'Pixel 8',
      mirrorTabId,
      windowId: 1,
      openedAt: 0,
      activeTargetId: HOME,
      targets: [
        { targetId: HOME, url: 'https://news.example/', title: 'News' },
        { targetId: OTHER, url: 'https://shop.example/', title: 'Shop' },
      ],
      tabNumbers: { [HOME]: 1, [OTHER]: 2 },
    },
    'browsentic/daemon': {
      connected: true,
      paired: true,
      lastChangeAt: 0,
      android: { devices: [{ serial: SERIAL, model: 'Pixel 8', android: '16', screen: { width: 1080, height: 2400, density: 420, awake: true }, chrome: { version: '150.0.7871.186' } }] },
    },
  });
});

const block = (...patterns: string[]) => fakeBrowser.storage.local.set({ [BLOCKED_SITES_KEY]: patterns });

describe('which calls go to the phone', () => {
  test('a call landing on the phone tab with no run does, and a desktop tab’s does not', async () => {
    expect(await phoneRoute(mirrorTabId, undefined)).toMatchObject({ serial: SERIAL });
    expect(await phoneRoute(desktopTabId, undefined)).toBeNull();
  });

  test('a run on one phone is told it is gone once the session moved to another phone', async () => {
    const ensured = await ensureSessionForTab({ tabId: mirrorTabId });
    if (!ensured.ok) throw new Error('no session');
    await patchSession(ensured.session.sessionId, { runId: 'run-4', phone: { serial: 'R5CT1234567' } });
    expect(await phoneRoute(mirrorTabId, 'run-4')).toBe('gone');
  });

  test('a run whose conversation lives on the phone tab does, wherever its tab id points', async () => {
    const ensured = await ensureSessionForTab({ tabId: mirrorTabId, url: 'https://news.example/' });
    if (!ensured.ok) throw new Error('no session');
    await patchSession(ensured.session.sessionId, { runId: 'run-1', phone: { serial: SERIAL } });
    expect(await phoneRoute(desktopTabId, 'run-1')).toMatchObject({ serial: SERIAL });
    const desktop = await ensureSessionForTab({ tabId: desktopTabId, url: 'https://desktop.example/' });
    if (!desktop.ok) throw new Error('no session');
    await patchSession(desktop.session.sessionId, { runId: 'run-2' });
    expect(await phoneRoute(mirrorTabId, 'run-2')).toBeNull();
  });

  test('a phone run after the phone went away is told so', async () => {
    const ensured = await ensureSessionForTab({ tabId: mirrorTabId });
    if (!ensured.ok) throw new Error('no session');
    await patchSession(ensured.session.sessionId, { runId: 'run-3', phone: { serial: SERIAL } });
    const stored = (await fakeBrowser.storage.session.get('browsentic/phone'))['browsentic/phone'] as object;
    await fakeBrowser.storage.session.set({ 'browsentic/phone': { ...stored, ended: { reason: 'unplugged', at: 1 } } });
    expect(await invokeForHarness('page.getPageInfo', {}, mirrorTabId, 'run-3')).toMatchObject({ ok: false, error: { code: 'PHONE_GONE' } });
  });

  test('invokeForHarness takes the phone branch before any desktop check of the extension page', async () => {
    expect(await invokeForHarness('page.hoverElement', {}, mirrorTabId)).toMatchObject({ ok: false, error: { code: 'NOT_ON_PHONE' } });
  });
});

describe('a tool on the phone', () => {
  const route = async () => (await phoneRoute(mirrorTabId, undefined))!;

  test('a tool off the list is refused with where it does work', async () => {
    expect(await invokeOnPhone('page.captureDownload', {}, await route())).toEqual({
      ok: false,
      error: { code: 'NOT_ON_PHONE', message: 'page.captureDownload isn’t available on the phone. It works in desktop tabs.' },
    });
  });

  test('a blocked phone page refuses every action, before the phone hears of it', async () => {
    await block('news.example');
    expect(await invokeOnPhone('page.getPageInfo', {}, await route())).toMatchObject({ ok: false, error: { code: 'SITE_BLOCKED' } });
    expect(phone.sent).toEqual([]);
  });

  test('navigating to a blocked host is refused before it goes', async () => {
    await block('bank.example');
    expect(await invokeOnPhone('page.navigate', { url: 'https://bank.example/' }, await route())).toMatchObject({ ok: false, error: { code: 'SITE_BLOCKED' } });
    expect(phone.sent.map(({ method }) => method)).not.toContain('Page.navigate');
  });

  test('a page that lands somewhere blocked is refused after it lands', async () => {
    await block('landing.example');
    const landed = invokeOnPhone('page.navigate', { url: 'https://ok.example/' }, await route());
    phone.location = 'https://landing.example/';
    await fakeBrowser.storage.session.get('browsentic/phone').then(async (stored) => {
      const session = stored['browsentic/phone'] as { targets: { targetId: string; url: string; title: string }[] };
      session.targets[0].url = 'https://landing.example/';
      await fakeBrowser.storage.session.set({ 'browsentic/phone': session });
    });
    expect(await landed).toMatchObject({ ok: false, error: { code: 'SITE_BLOCKED' } });
  });

  test('a phone page that moved on since the last event is judged by where it is now', async () => {
    await block('bank.example');
    phone.tree = { frame: { id: HOME, url: 'https://bank.example/login' } };
    expect(await invokeOnPhone('page.getPageInfo', {}, await route())).toMatchObject({ ok: false, error: { code: 'SITE_BLOCKED' } });
    expect(phone.sent.map(({ method }) => method)).toEqual(['Page.getFrameTree']);
  });

  test('a blocked frame is never entered, and one that becomes blocked refuses everything after', async () => {
    const enter = async () => invokeOnPhone('page.switchFrame', { frame: { selector: 'iframe' } }, await route());
    phone.tree = { frame: { id: HOME, url: 'https://news.example/' }, childFrames: [{ frame: { id: 'AD', url: 'https://ads.example/slot' } }] };
    await block('ads.example');
    expect(await enter()).toMatchObject({ ok: false, error: { code: 'SITE_BLOCKED' } });
    expect(await invokeOnPhone('page.extractText', {}, await route())).toMatchObject({ ok: true });

    await block();
    expect(await enter()).toMatchObject({ ok: true });
    await block('ads.example');
    const before = phone.sent.length;
    expect(await invokeOnPhone('page.extractText', {}, await route())).toMatchObject({ ok: false, error: { code: 'SITE_BLOCKED' } });
    expect(phone.sent.slice(before).some(({ params }) => String(params?.expression).startsWith('__browsenticPhone.dispatch'))).toBe(false);

    await block();
    expect(await invokeOnPhone('page.switchFrame', {}, await route())).toMatchObject({ ok: true });
  });

  test('a read that ends on a blocked page sends nothing back', async () => {
    await block('bank.example');
    phone.tree = { frame: { id: HOME, url: 'https://news.example/' } };
    phone.read = () => void (phone.tree = { frame: { id: HOME, url: 'https://bank.example/' } });
    expect(await invokeOnPhone('page.extractText', {}, await route())).toMatchObject({ ok: false, error: { code: 'SITE_BLOCKED' } });
  });

  test('navigate opens the URL in the phone’s current tab and waits for it to load', async () => {
    expect(await invokeOnPhone('page.navigate', { url: 'https://wikipedia.org/' }, await route())).toEqual({
      ok: true,
      data: { navigatedTo: 'https://wikipedia.org/', finalUrl: 'https://wikipedia.org/', title: 'Landed', loaded: true },
    });
    expect(phone.sent.find(({ method }) => method === 'Page.navigate')).toEqual({ method: 'Page.navigate', params: { url: 'https://wikipedia.org/' } });
  });

  test('switchTab takes the phone’s tab numbers, brings that tab to the front and moves the mirror to it', async () => {
    expect(await invokeOnPhone('page.switchTab', { tabId: 2 }, await route())).toMatchObject({ ok: true, data: { activeTabId: 2 } });
    expect([phone.fronted, phone.followed]).toEqual([[OTHER], [OTHER]]);
    expect(await invokeOnPhone('page.switchTab', {}, await route())).toMatchObject({
      ok: true,
      data: { tabs: [{ tabId: 1, active: true }, { tabId: 2, active: false }] },
    });
  });

  test('a tab on a blocked site is never listed, matched or closed, as on desktop', async () => {
    await block('shop.example');
    expect(await invokeOnPhone('page.switchTab', {}, await route())).toEqual({
      ok: true,
      data: { tabs: [{ tabId: 1, url: 'https://news.example/', title: 'News', active: true }], hidden: 1 },
    });
    const matched = await invokeOnPhone('page.switchTab', { match: 'shop' }, await route());
    expect(matched).toMatchObject({ ok: false, error: { code: 'INVALID_TARGET' } });
    expect(JSON.stringify(matched)).not.toContain('shop.example');
    expect(await invokeOnPhone('page.closeTab', { tabId: 2 }, await route())).toMatchObject({ ok: false, error: { code: 'SITE_BLOCKED' } });
    expect(phone.sent.map(({ method }) => method)).not.toContain('Target.closeTarget');
  });

  test('a blocked phone page still lets the agent switch away or open another tab', async () => {
    await block('news.example');
    expect(await invokeOnPhone('page.switchTab', { tabId: 2 }, await route())).toMatchObject({ ok: true, data: { activeTabId: 2 } });
    expect(await invokeOnPhone('page.openTab', { url: 'https://docs.example/', active: false }, await route())).toMatchObject({ ok: true });
    expect(await invokeOnPhone('page.openTab', { url: 'https://news.example/' }, await route())).toMatchObject({ ok: false, error: { code: 'SITE_BLOCKED' } });
  });

  test('openTab in the background opens in front, as Android insists, then puts the previous tab back', async () => {
    const opened = await invokeOnPhone('page.openTab', { url: 'https://docs.example/', active: false }, await route());
    expect(opened).toMatchObject({ ok: true, data: { tabId: 3, activeTabId: 1 } });
    expect(phone.fronted).toEqual([HOME]);
    expect(phone.followed).toEqual([]);
  });
});

describe('a conversation on the phone tab', () => {
  test('is anchored on the phone’s page, never the extension page', async () => {
    const { anchor, serial } = await phoneAnchor({ tabId: mirrorTabId, url: 'chrome-extension://abc/phone.html', title: 'Android · Pixel 8' });
    expect([anchor.url, anchor.title, serial]).toEqual(['https://news.example/', 'News', SERIAL]);
    expect((await phoneAnchor({ tabId: desktopTabId, url: 'https://desktop.example/' })).serial).toBeUndefined();
  });

  test('tells its run which phone, and the viewport as the page has it now', async () => {
    const ensured = await ensureSessionForTab({ tabId: mirrorTabId });
    if (!ensured.ok) throw new Error('no session');
    expect(await phoneContext({ ...ensured.session, phone: { serial: SERIAL } })).toEqual({
      serial: SERIAL,
      model: 'Pixel 8',
      android: '16',
      chrome: '150.0.7871.186',
      viewport: { width: 411, height: 675, dpr: 2.625 },
    });
    expect(await phoneContext({ ...ensured.session, phone: undefined })).toBeUndefined();
  });
});