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 { readFileSync } from 'node:fs';
import { createServer, type IncomingMessage, type Server } from 'node:http';
import { afterEach, beforeEach, describe, expect, test } from 'vitest';
import { WebSocketServer, type WebSocket } from 'ws';
import type { ActionResult, SocketFrame } from '@/lib/actions/protocol';
import type { AndroidState } from '@/lib/phone/types';
import { logPath } from '../lockfile';
import { startRelay, type CdpRequest, type PhoneOwner, type Relay } from './relay';
const SERIAL = 'emulator-5554';
const PAGE = 'A1B2C3D4E5F60718293A4B5C6D7E8F90';
/** Chrome on the phone, as far as the relay sees it through the forwarded port. */
class FakeChrome {
readonly paths: string[] = [];
readonly origins: (string | undefined)[] = [];
readonly commands: { method: string; params?: Record<string, unknown>; sessionId?: string }[] = [];
readonly sockets: WebSocket[] = [];
/** How long the DevTools connection waits before Chrome takes it. */
upgradeDelayMs = 0;
/** A command that makes Chrome hang up instead of answering. */
hangUpOn?: string;
private http!: Server;
async listen(): Promise<number> {
const wss = new WebSocketServer({ noServer: true });
this.http = createServer((req, res) => {
this.paths.push(req.url ?? '');
if (req.url !== '/json/version') return res.writeHead(404).end();
const { port } = this.http.address() as { port: number };
res.writeHead(200, { 'content-type': 'application/json' }).end(
JSON.stringify({ Browser: 'Chrome/150.0.7871.186', 'Android-Package': 'com.android.chrome', webSocketDebuggerUrl: `ws://127.0.0.1:${port}/devtools/browser` }),
);
});
this.http.on('upgrade', (req: IncomingMessage, socket, head) => {
this.origins.push(req.headers.origin);
setTimeout(() => wss.handleUpgrade(req, socket, head, (ws) => this.serve(ws)), this.upgradeDelayMs);
});
await new Promise<void>((resolve) => this.http.listen(0, '127.0.0.1', resolve));
return (this.http.address() as { port: number }).port;
}
async close(): Promise<void> {
for (const socket of this.sockets) socket.terminate();
await new Promise((resolve) => this.http.close(resolve));
}
emit(method: string, params: Record<string, unknown>, sessionId?: string): void {
for (const socket of this.sockets) socket.send(JSON.stringify({ method, params, sessionId }));
}
hangUp(): void {
for (const socket of this.sockets) socket.terminate();
}
private serve(ws: WebSocket): void {
this.sockets.push(ws);
ws.on('message', (raw) => {
const { id, method, params, sessionId } = JSON.parse(String(raw));
this.commands.push({ method, params, sessionId });
const reply = (body: object) => ws.send(JSON.stringify({ id, ...body }));
if (method === this.hangUpOn) ws.terminate();
else if (method === 'Target.setDiscoverTargets') reply({ result: {} });
else if (method === 'Target.getTargets') {
reply({
result: {
targetInfos: [
{ targetId: PAGE, type: 'page', url: 'https://example.com/', title: 'Example' },
{ targetId: '1', type: 'page', url: 'https://example.com/', title: 'Example' },
{ targetId: 'B'.repeat(32), type: 'service_worker', url: 'https://example.com/sw.js', title: '' },
],
},
});
} else if (method === 'Runtime.evaluate') reply({ result: { result: { type: 'string', value: 'Example' } } });
else if (method === 'Page.navigate') {
reply({ result: { frameId: 'F' } });
ws.send(JSON.stringify({ method: 'Page.frameStartedLoading', params: { frameId: 'F' } }));
} else if (method === 'Hang.forever') return;
else if (method !== 'Page.screencastFrameAck') reply({ error: { code: -32601, message: `'${method}' wasn't found` } });
});
}
}
class Owner implements PhoneOwner {
readonly sent: SocketFrame[] = [];
isOpen = true;
bufferedAmount = 0;
constructor(readonly id: string) {}
send(frame: SocketFrame): void {
this.sent.push(frame);
}
events(): string[] {
return this.sent.flatMap((frame) => (frame.t === 'cdpEvent' ? [frame.method] : []));
}
answer(id: string): ActionResult | undefined {
return this.sent.flatMap((frame) => (frame.t === 'cdpResult' && frame.id === id ? [frame.result] : []))[0];
}
}
const READY: AndroidState = {
enabled: true,
ready: true,
adb: { found: true },
devices: [{ serial: SERIAL, transport: 'usb', state: 'ready', chrome: { installed: true, running: true, debuggable: true } }],
};
let chrome: FakeChrome;
let port: number;
let state: AndroidState;
let forwards: { made: string[]; removed: number[] };
let sessions: AndroidState['session'][];
let relay: Relay;
const TIMEOUTS = { connect: 1_000, command: 100, slow: 200 };
function startTestRelay(timeouts = TIMEOUTS): Relay {
return startRelay({
server: {
forward: async (serial, remote) => {
forwards.made.push(`${serial} ${remote}`);
return port;
},
removeForward: async (_serial, local) => {
forwards.removed.push(local);
},
},
state: async () => state,
onSession: (session) => sessions.push(session),
timeouts,
});
}
beforeEach(async () => {
chrome = new FakeChrome();
port = await chrome.listen();
state = READY;
forwards = { made: [], removed: [] };
sessions = [];
relay = startTestRelay();
});
afterEach(async () => {
await relay.stop();
await chrome.close();
});
/** Sends a command the way the Bridge does, and reads the answer the relay gave the owner. */
async function ask(owner: Owner, request: CdpRequest): Promise<ActionResult | undefined> {
await relay.command(owner, request);
return owner.answer(request.id);
}
const until = async (done: () => boolean) => {
for (let tries = 0; !done(); tries++) {
if (tries > 200) throw new Error('timed out waiting');
await new Promise((resolve) => setTimeout(resolve, 5));
}
};
describe('opening a phone', () => {
test('forwards the DevTools socket, connects with no Origin, and lists only real pages', async () => {
const owner = new Owner('chrome-1');
expect(await relay.open(owner, SERIAL)).toEqual({
ok: true,
data: {
device: READY.devices[0],
targets: [{ targetId: PAGE, url: 'https://example.com/', title: 'Example' }],
browserVersion: 'Chrome/150.0.7871.186',
},
});
expect(forwards.made).toEqual([`${SERIAL} localabstract:chrome_devtools_remote`]);
expect(chrome.paths).toEqual(['/json/version']);
expect(chrome.origins).toEqual([undefined]);
expect(chrome.commands.map(({ method }) => method)).toEqual(['Target.setDiscoverTargets', 'Target.getTargets']);
expect(sessions).toEqual([{ serial: SERIAL, since: expect.any(String) }]);
});
test('a phone that is not there, or whose Chrome is closed, is refused before any forward', async () => {
const owner = new Owner('chrome-1');
expect(await relay.open(owner, 'R5CT1234567')).toMatchObject({ ok: false, error: { code: 'NO_DEVICE' } });
state = { ...READY, devices: [{ ...READY.devices[0], chrome: { installed: true, running: true, debuggable: false } }] };
expect(await relay.open(owner, SERIAL)).toMatchObject({ ok: false, error: { code: 'CHROME_NOT_RUNNING' } });
expect(forwards.made).toEqual([]);
});
test('two opens at once make one session, and asking again answers from it', async () => {
const owner = new Owner('chrome-1');
const [first, second] = await Promise.all([relay.open(owner, SERIAL), relay.open(owner, SERIAL)]);
expect([first.ok, second.ok]).toEqual([true, true]);
expect(forwards.made).toHaveLength(1);
expect(chrome.sockets).toHaveLength(1);
});
test('a second browser is told another owns the phone, for opens and for commands', async () => {
await relay.open(new Owner('chrome-1'), SERIAL);
const other = new Owner('edge-1');
expect(await relay.open(other, SERIAL)).toMatchObject({ ok: false, error: { code: 'NOT_OWNER' } });
expect(await ask(other, { t: 'cdp', id: 'x', serial: SERIAL, method: 'Runtime.evaluate' })).toMatchObject({
ok: false,
error: { code: 'NOT_OWNER' },
});
});
test('a Chrome that refuses the connection leaves no forward behind', async () => {
await chrome.close();
expect(await relay.open(new Owner('chrome-1'), SERIAL)).toMatchObject({ ok: false, error: { code: 'PHONE_GONE' } });
expect(forwards.removed).toEqual([port]);
chrome = new FakeChrome();
await chrome.listen();
});
test('a Chrome too slow to take the connection is hung up on, not left to connect later', async () => {
await relay.stop();
relay = startTestRelay({ ...TIMEOUTS, connect: 100 });
chrome.upgradeDelayMs = 300;
expect(await relay.open(new Owner('chrome-1'), SERIAL)).toMatchObject({ ok: false, error: { code: 'PHONE_GONE' } });
await new Promise((resolve) => setTimeout(resolve, 400));
expect(chrome.sockets.filter((socket) => socket.readyState === socket.OPEN)).toEqual([]);
});
test('a Chrome that goes away while the session opens is no session at all', async () => {
chrome.hangUpOn = 'Target.setDiscoverTargets';
expect(await relay.open(new Owner('chrome-1'), SERIAL)).toMatchObject({ ok: false, error: { code: 'PHONE_GONE' } });
expect(forwards.removed).toEqual([port]);
expect(sessions.at(-1)).toBeUndefined();
});
});
describe('letting go while a phone is opening', () => {
beforeEach(() => {
chrome.upgradeDelayMs = 100;
});
/** Wrapped, so awaiting this waits for the forward and not for the open itself. */
const opening = async (owner: Owner) => {
const attempt = relay.open(owner, SERIAL);
await until(() => forwards.made.length === 1);
return { attempt };
};
test('a browser that goes away leaves nothing behind, and the next one can open the phone', async () => {
const leaving = new Owner('chrome-1');
const { attempt } = await opening(leaving);
await relay.release(leaving);
expect(await attempt).toMatchObject({ ok: false, error: { code: 'PHONE_GONE' } });
expect([forwards.removed, sessions]).toEqual([[port], []]);
expect(await relay.open(new Owner('chrome-2'), SERIAL)).toMatchObject({ ok: true });
});
test('switching Android off ends it there', async () => {
const owner = new Owner('chrome-1');
const { attempt } = await opening(owner);
await relay.close(owner, SERIAL);
expect(await attempt).toMatchObject({ ok: false, error: { code: 'PHONE_GONE' } });
expect(forwards.removed).toEqual([port]);
});
test('another browser switching Android off does not end it', async () => {
const owner = new Owner('chrome-1');
const { attempt } = await opening(owner);
await relay.close(new Owner('edge-1'), SERIAL);
expect(await attempt).toMatchObject({ ok: true });
});
test('the Bridge stopping waits for it, removes its forward, and opens nothing after', async () => {
const { attempt } = await opening(new Owner('chrome-1'));
await relay.stop();
expect(forwards.removed).toEqual([port]);
expect(await attempt).toMatchObject({ ok: false, error: { code: 'PHONE_GONE' } });
expect(await relay.open(new Owner('chrome-1'), SERIAL)).toMatchObject({ ok: false, error: { code: 'PHONE_GONE' } });
});
});
describe('commands and events', () => {
let owner: Owner;
beforeEach(async () => {
owner = new Owner('chrome-1');
await relay.open(owner, SERIAL);
});
test('a command goes to the phone with its session id, and its answer comes back', async () => {
const result = await ask(owner, { t: 'cdp', id: 'f1', serial: SERIAL, method: 'Runtime.evaluate', params: { expression: 'document.title' }, sessionId: 'S1' });
expect(result).toEqual({ ok: true, data: { result: { type: 'string', value: 'Example' } } });
expect(chrome.commands.at(-1)).toEqual({ method: 'Runtime.evaluate', params: { expression: 'document.title' }, sessionId: 'S1' });
});
test('a command can ask to wait longer than the default, for a page-side wait', async () => {
const asked = ask(owner, { t: 'cdp', id: 'f7', serial: SERIAL, method: 'Hang.forever', timeoutMs: 400 });
await new Promise((resolve) => setTimeout(resolve, 200));
expect(await Promise.race([asked, Promise.resolve('still waiting')])).toBe('still waiting');
expect(await asked).toMatchObject({ ok: false, error: { code: 'TIMEOUT' } });
});
test('Chrome\'s refusal is CDP_ERROR in its own words, and silence is TIMEOUT', async () => {
expect(await ask(owner, { t: 'cdp', id: 'f2', serial: SERIAL, method: 'Nope.nope' })).toEqual({
ok: false,
error: { code: 'CDP_ERROR', message: "'Nope.nope' wasn't found" },
});
expect(await ask(owner, { t: 'cdp', id: 'f3', serial: SERIAL, method: 'Hang.forever' })).toMatchObject({
ok: false,
error: { code: 'TIMEOUT' },
});
});
test('a command for a phone with no session is PHONE_GONE', async () => {
expect(await ask(owner, { t: 'cdp', id: 'f4', serial: 'R5CT1234567', method: 'Runtime.evaluate' })).toMatchObject({
ok: false,
error: { code: 'PHONE_GONE' },
});
});
test('a command with no method is refused before it reaches the phone', async () => {
const sent = chrome.commands.length;
expect(await ask(owner, { t: 'cdp', id: 'f8', serial: SERIAL } as unknown as CdpRequest)).toMatchObject({ ok: false, error: { code: 'INVALID_INPUT' } });
expect(chrome.commands).toHaveLength(sent);
});
test('an answer reaches the owner in the order Chrome sent it among the events', async () => {
owner.sent.length = 0;
await relay.command(owner, { t: 'cdp', id: 'f9', serial: SERIAL, method: 'Page.navigate', params: { url: 'https://example.com/b' } });
await until(() => owner.events().length === 1);
expect(owner.sent.map((frame) => (frame.t === 'cdpEvent' ? frame.method : frame.t))).toEqual(['cdpResult', 'Page.frameStartedLoading']);
});
test('every event reaches the owner, with the session it came from', async () => {
chrome.emit('Target.targetCreated', { targetInfo: { targetId: PAGE } });
chrome.emit('Page.screencastFrame', { data: 'jpeg', sessionId: 1, metadata: {} }, 'S1');
await until(() => owner.events().length === 2);
expect(owner.sent.at(-1)).toEqual({ t: 'cdpEvent', serial: SERIAL, method: 'Page.screencastFrame', params: { data: 'jpeg', sessionId: 1, metadata: {} }, sessionId: 'S1' });
});
test('a backed-up owner misses screencast frames, which the Bridge acks itself, and nothing else', async () => {
owner.bufferedAmount = 5 * 1024 * 1024;
chrome.emit('Page.screencastFrame', { data: 'jpeg', sessionId: 7, metadata: {} }, 'S1');
chrome.emit('Page.frameNavigated', { frame: { id: 'F' } }, 'S1');
await until(() => owner.events().length === 1);
expect(owner.events()).toEqual(['Page.frameNavigated']);
await until(() => chrome.commands.some(({ method }) => method === 'Page.screencastFrameAck'));
expect(chrome.commands.at(-1)).toEqual({ method: 'Page.screencastFrameAck', params: { sessionId: 7 }, sessionId: 'S1' });
});
test('the log names each method and never what it carried', async () => {
await relay.command(owner, { t: 'cdp', id: 'f5', serial: SERIAL, method: 'Input.insertText', params: { text: 'hunter2-secret' } });
await relay.command(owner, { t: 'cdp', id: 'f6', serial: SERIAL, method: 'Page.screencastFrameAck', params: { sessionId: 1 } });
chrome.emit('Page.screencastFrame', { data: 'FRAME-PIXELS', sessionId: 2, metadata: {} });
await until(() => owner.events().length === 1);
const logged = readFileSync(logPath, 'utf8');
expect(logged).toMatch(/phone emulator-5554 Input\.insertText CDP_ERROR in \d+ ms/);
expect(logged).not.toMatch(/hunter2-secret|FRAME-PIXELS|Page\.screencastFrameAck/);
});
});
describe('when a session ends', () => {
let owner: Owner;
beforeEach(async () => {
owner = new Owner('chrome-1');
await relay.open(owner, SERIAL);
});
test('Chrome going away fails the command in flight, tells the owner why, and removes the forward', async () => {
const pending = ask(owner, { t: 'cdp', id: 'g1', serial: SERIAL, method: 'Hang.forever' });
await until(() => chrome.commands.some(({ method }) => method === 'Hang.forever'));
chrome.hangUp();
expect(await pending).toMatchObject({ ok: false, error: { code: 'PHONE_GONE' } });
await until(() => owner.sent.some((frame) => frame.t === 'phoneClosed'));
expect(owner.sent.filter((frame) => frame.t === 'phoneClosed')).toEqual([{ t: 'phoneClosed', serial: SERIAL, reason: 'chrome-exited' }]);
expect(forwards.removed).toEqual([port]);
expect(sessions.at(-1)).toBeUndefined();
});
test('a phone that left adb\'s list was unplugged', async () => {
state = { ...READY, ready: false, devices: [] };
chrome.hangUp();
await until(() => owner.sent.some((frame) => frame.t === 'phoneClosed'));
expect(owner.sent.find((frame) => frame.t === 'phoneClosed')).toMatchObject({ reason: 'unplugged' });
});
test('the owner closing it, or going away, ends it quietly and removes the forward', async () => {
await relay.close(owner, SERIAL);
expect(forwards.removed).toEqual([port]);
await relay.open(owner, SERIAL);
await relay.release(owner);
expect(forwards.removed).toEqual([port, port]);
expect(owner.sent.filter((frame) => frame.t === 'phoneClosed')).toEqual([]);
});
test('another browser cannot close it', async () => {
await relay.close(new Owner('edge-1'), SERIAL);
expect(forwards.removed).toEqual([]);
});
test('the Bridge stopping tells the owner and removes the forward', async () => {
await relay.stop();
expect(owner.sent.filter((frame) => frame.t === 'phoneClosed')).toEqual([{ t: 'phoneClosed', serial: SERIAL, reason: 'bridge-stopping' }]);
expect(forwards.removed).toEqual([port]);
});
});