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.
TypeScript agentic-browseragentic-browsingagy-cliaiai-agentai-browser-extensionai-toolsbrave-extensionbrowser-agentbrowser-automationbrowser-extensionbrowser-usebrowserskillchrome-extensionclaude-codecodexfirefox-addonmcp-servernanobrowserweb-automation
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';
import type { CdpEvent } from './socket';
import type { MirrorMessage } from '@/lib/phone/mirror';
const SERIAL = 'emulator-5554';
const FRONT = 'A'.repeat(32);
const BACK = 'B'.repeat(32);
const socket = vi.hoisted(() => ({ sent: [] as { method: string; params?: Record<string, unknown>; sessionId?: string }[], events: [] as ((event: CdpEvent) => void)[] }));
vi.mock('./socket', () => ({
DAEMON_STATE_KEY: 'browsentic/daemon',
sendCdp: async (_serial: string, method: string, params?: Record<string, unknown>, sessionId?: string) => {
socket.sent.push({ method, params, sessionId });
if (method === 'Target.attachToTarget') return success({ sessionId: `session-${params?.targetId}` });
if (method === 'Runtime.evaluate') return success({ result: { value: sessionId === `session-${FRONT}` ? 'visible' : 'hidden' } });
if (method === 'Page.getNavigationHistory') return success({ currentIndex: 1, entries: [{ id: 1, url: 'https://a.example/', title: 'A' }, { id: 2, url: 'https://b.example/', title: 'B' }] });
return success({});
},
onCdpEvent: (listener: (event: CdpEvent) => void) => socket.events.push(listener),
onPhoneClosed: () => undefined,
onDaemonClosed: () => undefined,
closePhone: () => undefined,
openPhone: async () => success({}),
launchPhoneChrome: async () => success({}),
}));
type Phone = typeof import('./phone');
let readPhone: Phone['readPhone'];
const connectListeners: ((port: unknown) => void)[] = [];
/** The page's end of the port, as the background sees it. */
function connectPage() {
const received: MirrorMessage[] = [];
const messageListeners: ((message: unknown) => void)[] = [];
const port = {
name: 'browsentic/phone',
postMessage: (message: MirrorMessage) => received.push(message),
onMessage: { addListener: (listener: (message: unknown) => void) => messageListeners.push(listener) },
onDisconnect: { addListener: () => undefined },
};
connectListeners.forEach((listener) => listener(port));
return { received, say: (message: unknown) => messageListeners.forEach((listener) => listener(message)) };
}
const methods = () => socket.sent.map(({ method }) => method);
const settle = () => new Promise((resolve) => setTimeout(resolve, 20));
const emit = (event: Omit<CdpEvent, 't' | 'serial'>) => socket.events.forEach((listener) => listener({ t: 'cdpEvent', serial: SERIAL, ...event }));
beforeEach(async () => {
fakeBrowser.reset();
socket.sent.length = 0;
socket.events.length = 0;
connectListeners.length = 0;
Object.assign(fakeBrowser.runtime, { onConnect: { addListener: (listener: (port: unknown) => void) => connectListeners.push(listener) } });
vi.resetModules();
({ readPhone } = await import('./phone'));
(await import('./phone-mirror')).servePhoneMirror();
await fakeBrowser.storage.session.set({
'browsentic/phone': {
serial: SERIAL,
mirrorTabId: 9,
windowId: 1,
openedAt: 0,
transport: 'usb',
targets: [
{ targetId: BACK, url: 'https://b.example/', title: 'B' },
{ targetId: FRONT, url: 'https://a.example/', title: 'A' },
],
},
});
});
describe('the mirror in the background', () => {
test('a session the extension ended attaches afresh next time, since a new connection knows none of the old sessions', async () => {
const { attachedSession } = await import('./phone-mirror');
const { endPhone } = await import('./phone');
await attachedSession(SERIAL, FRONT);
await attachedSession(SERIAL, FRONT);
await endPhone('closed');
await attachedSession(SERIAL, FRONT);
expect(methods().filter((method) => method === 'Target.attachToTarget')).toHaveLength(2);
});
test('watching follows the tab in front, not the first listed, and streams it', async () => {
const page = connectPage();
page.say({ op: 'watch' });
await settle();
expect((await readPhone())?.activeTargetId).toBe(FRONT);
expect(socket.sent.find(({ method }) => method === 'Page.startScreencast')).toEqual({
method: 'Page.startScreencast',
params: { format: 'jpeg', quality: 60, maxWidth: 720, maxHeight: 1600, everyNthFrame: 1 },
sessionId: `session-${FRONT}`,
});
expect(page.received.find((message) => message.kind === 'page')).toMatchObject({ targetId: FRONT, url: 'https://b.example/', canGoBack: true, canGoForward: false });
});
test('a frame goes to the page, and the page’s ack goes to the phone', async () => {
const page = connectPage();
page.say({ op: 'watch' });
await settle();
emit({ method: 'Page.screencastFrame', params: { data: 'JPEG', sessionId: 7, metadata: { deviceWidth: 411, pageScaleFactor: 1 } }, sessionId: `session-${FRONT}` });
expect(page.received.find((message) => message.kind === 'frame')).toEqual({ kind: 'frame', data: 'JPEG', frame: 7, metadata: { deviceWidth: 411, pageScaleFactor: 1 } });
page.say({ op: 'ack', frame: 7 });
await settle();
expect(socket.sent.at(-1)).toEqual({ method: 'Page.screencastFrameAck', params: { sessionId: 7 }, sessionId: `session-${FRONT}` });
});
test('a finger’s moves while one is on its way collapse into the latest, and the lift still follows', async () => {
const page = connectPage();
page.say({ op: 'watch' });
await settle();
socket.sent.length = 0;
page.say({ op: 'touch', type: 'touchStart', x: 10, y: 10 });
for (let step = 1; step <= 5; step++) page.say({ op: 'touch', type: 'touchMove', x: 10, y: 10 + step * 10 });
page.say({ op: 'touch', type: 'touchEnd', x: 10, y: 60 });
await settle();
expect(socket.sent.map(({ params }) => [params?.type, params?.touchPoints])).toEqual([
['touchStart', [{ x: 10, y: 10 }]],
['touchMove', [{ x: 10, y: 60 }]],
['touchEnd', []],
]);
});
test('a blocked site typed in the address bar is refused before the phone hears of it', async () => {
await fakeBrowser.storage.local.set({ [BLOCKED_SITES_KEY]: ['bank.example'] });
const page = connectPage();
page.say({ op: 'watch' });
await settle();
page.say({ op: 'go', url: 'https://bank.example/login' });
await settle();
expect(methods()).not.toContain('Page.navigate');
expect(page.received.at(-1)).toMatchObject({ kind: 'error' });
page.say({ op: 'go', url: 'https://ok.example/' });
await settle();
expect(socket.sent.at(-1)).toMatchObject({ method: 'Page.navigate', params: { url: 'https://ok.example/' } });
});
test('the tab list follows the phone and leaves out the phantom target', async () => {
connectPage();
emit({ method: 'Target.targetCreated', params: { targetInfo: { targetId: '1', type: 'page', url: 'https://a.example/', title: 'A' } } });
emit({ method: 'Target.targetCreated', params: { targetInfo: { targetId: 'C'.repeat(32), type: 'page', url: 'https://c.example/', title: 'C' } } });
emit({ method: 'Target.targetCreated', params: { targetInfo: { targetId: 'D'.repeat(32), type: 'service_worker', url: 'https://c.example/sw.js', title: '' } } });
emit({ method: 'Target.targetDestroyed', params: { targetId: BACK } });
await settle();
expect((await readPhone())?.targets.map(({ targetId }) => targetId[0])).toEqual(['A', 'C']);
});
test('back steps to the previous history entry', async () => {
const page = connectPage();
page.say({ op: 'watch' });
await settle();
page.say({ op: 'back' });
await settle();
expect(socket.sent.at(-1)).toEqual({ method: 'Page.navigateToHistoryEntry', params: { entryId: 1 }, sessionId: `session-${FRONT}` });
});
test('while A-Eye waits, the page is told, its pointer steers the lens with aims collapsed, and the phone is never touched', async () => {
const { steerLensFromMirror } = await import('./phone-mirror');
const page = connectPage();
page.say({ op: 'watch' });
await settle();
socket.sent.length = 0;
const steered: unknown[] = [];
const release = steerLensFromMirror(FRONT, async (command) => void steered.push(command));
expect(page.received.at(-1)).toEqual({ kind: 'lens', active: true });
expect(connectPage().received).toContainEqual({ kind: 'lens', active: true });
for (let step = 1; step <= 4; step++) page.say({ op: 'lens', lens: { op: 'aim', x: step, y: step } });
page.say({ op: 'lens', lens: { op: 'pick', x: 4, y: 4 } });
await settle();
expect(steered).toEqual([
{ op: 'aim', x: 1, y: 1 },
{ op: 'aim', x: 4, y: 4 },
{ op: 'pick', x: 4, y: 4 },
]);
expect(methods().filter((method) => method.startsWith('Input.'))).toEqual([]);
release();
expect(page.received.at(-1)).toEqual({ kind: 'lens', active: false });
page.say({ op: 'lens', lens: { op: 'pick', x: 4, y: 4 } });
await settle();
expect(steered).toHaveLength(3);
});
test('a lens left on a tab the mirror moved away from is only ever cancelled', async () => {
const { steerLensFromMirror } = await import('./phone-mirror');
const page = connectPage();
page.say({ op: 'watch' });
await settle();
const steered: unknown[] = [];
steerLensFromMirror(BACK, async (command) => void steered.push(command));
page.say({ op: 'lens', lens: { op: 'pick', x: 4, y: 4 } });
page.say({ op: 'lens', lens: { op: 'cancel' } });
await settle();
expect(steered).toEqual([{ op: 'cancel' }]);
});
});