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 { createServer } from 'node:http';
import type { AddressInfo } from 'node:net';
import { WebSocketServer, type WebSocket } from 'ws';
import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test, vi } from 'vitest';
import type { ControlMessage, ControlRequest } from './control';
import { RemoteBridge } from './remote-bridge';
const TOKEN = 'the-token-in-the-lockfile';
/** The daemon's /control endpoint, answering each request however the test says. */
const http = createServer();
const wss = new WebSocketServer({ noServer: true });
const received: ControlRequest[] = [];
let answer: (request: ControlRequest) => ControlMessage | null;
let daemonSide: WebSocket;
let port: number;
http.on('upgrade', (request, socket, head) => {
if (request.url !== '/control' || request.headers.authorization !== `Bearer ${TOKEN}`) {
socket.end('HTTP/1.1 401 Unauthorized\r\n\r\n');
return;
}
wss.handleUpgrade(request, socket, head, (ws) => {
daemonSide = ws;
ws.on('message', (raw) => {
const parsed = JSON.parse(String(raw)) as ControlRequest;
received.push(parsed);
const reply = answer(parsed);
if (reply) ws.send(JSON.stringify(reply));
});
});
});
beforeAll(async () => {
await new Promise<void>((resolve) => http.listen(0, '127.0.0.1', resolve));
port = (http.address() as AddressInfo).port;
});
afterAll(async () => {
for (const client of wss.clients) client.terminate();
await new Promise((resolve) => http.close(resolve));
});
let bridge: RemoteBridge;
beforeEach(async () => {
received.length = 0;
answer = () => null;
bridge = await RemoteBridge.connect(port, TOKEN, 'run-9');
});
afterEach(async () => {
vi.useRealTimers();
await bridge.close();
});
describe('connecting to the daemon', () => {
test('a client without the lockfile token is turned away', async () => {
await expect(RemoteBridge.connect(port, 'guessed')).rejects.toThrow('401');
});
});
describe('asking the daemon', () => {
test('the tools it describes', async () => {
const tools = [
{ name: 'page.getPageInfo', description: 'Read the page', inputSchema: {} },
{ name: 'page.dragElement', description: 'Drag', inputSchema: {} },
];
const offer = { reserved: ['browsentic.focusShot'], onDemand: ['page.dragElement'], delivery: 'namespaced' as const };
answer = ({ id }) => ({ id, op: 'describe', tools, ...offer });
expect(await bridge.describe()).toStrictEqual({ tools, ...offer, withheld: undefined });
});
test('an action, stamped with the run it belongs to', async () => {
answer = ({ id }) => ({ id, op: 'invoke', result: { ok: true, data: { clicked: true } } });
const result = await bridge.invoke('page.clickElement', { target: { text: 'Buy' } });
expect([result, received[0]]).toEqual([
{ ok: true, data: { clicked: true } },
{ id: expect.any(String), op: 'invoke', action: 'page.clickElement', input: { target: { text: 'Buy' } }, runId: 'run-9', keepAlive: true },
]);
});
test('its status, a pairing code, the paired browsers, its agent, and a revocation', async () => {
const status = { connected: true, daemonVersion: '0.6.2', protocolVersion: 9, port, manifestInSync: true, connectedBrowsers: 1, pairedBrowsers: 1, pairingPending: false };
const agentState = { active: 'claude' as const, runners: [] };
answer = (request) => {
const { id } = request;
if (request.op === 'status') return { id, op: 'status', status };
if (request.op === 'pair') return { id, op: 'pair', code: 'ABCD2345', expiresAt: 1 };
if (request.op === 'sessions') return { id, op: 'sessions', sessions: [] };
if (request.op === 'agent') return { id, op: 'agent', state: agentState };
if (request.op === 'revoke') return { id, op: 'revoke', revoked: 2 };
return null;
};
expect([await bridge.status(), await bridge.pair(), await bridge.sessions(), await bridge.agent({ set: 'codex' }), await bridge.revoke('chrome-extension://x')]).toEqual([
status,
{ id: expect.any(String), op: 'pair', code: 'ABCD2345', expiresAt: 1 },
[],
agentState,
2,
]);
expect(received.slice(3).map(({ id: _id, ...request }) => request)).toEqual([
{ op: 'agent', set: 'codex' },
{ op: 'revoke', origin: 'chrome-extension://x' },
]);
});
test('Android, from a Bridge that speaks it, and refused at once by one too old to answer', async () => {
const status = (protocolVersion: number) => ({ connected: true, daemonVersion: '0.8.1', protocolVersion, port, manifestInSync: true, connectedBrowsers: 1, pairedBrowsers: 1, pairingPending: false });
const state = { enabled: true, ready: false, adb: { found: false }, devices: [] };
let speaks = 23;
answer = (request) => {
const { id } = request;
if (request.op === 'status') return { id, op: 'status', status: status(speaks) };
if (request.op === 'android') return { id, op: 'android', result: { ok: true, data: state } };
return null;
};
expect(await bridge.android({ peek: true })).toEqual({ ok: true, data: state });
speaks = 22;
expect(await bridge.android({ peek: true })).toMatchObject({ ok: false, error: { code: 'UNSUPPORTED' } });
expect(received.map(({ op }) => op)).toEqual(['status', 'android', 'status']);
});
test('an action its caller stops waiting for is cancelled with the daemon, under the same id', async () => {
const abandoned = new AbortController();
const pending = bridge.invoke('page.submitForm', {}, abandoned.signal);
await vi.waitFor(() => expect(received).toHaveLength(1));
abandoned.abort();
const result = await pending;
await vi.waitFor(() => expect(received).toHaveLength(2));
expect([result, received[1]]).toEqual([
{ ok: false, error: { code: 'CANCELLED', message: 'The caller stopped waiting for this call.' } },
{ id: received[0].id, op: 'cancel' },
]);
});
test('a reply for a request nobody is waiting on, or one that is not JSON, is ignored', async () => {
answer = ({ id }) => {
daemonSide.send('not json');
daemonSide.send(JSON.stringify({ id: 'someone-else', op: 'revoke', revoked: 99 }));
return { id, op: 'revoke', revoked: 1 };
};
expect(await bridge.revoke()).toBe(1);
});
test('a manifest change reaches every listener', async () => {
const heard = new Promise<string[]>((resolve) => {
const calls: string[] = [];
bridge.onManifestChanged(() => calls.push('first'));
bridge.onManifestChanged(() => resolve([...calls, 'second']));
});
daemonSide.send(JSON.stringify({ event: 'manifest-changed' }));
expect(await heard).toEqual(['first', 'second']);
});
});
describe('when the daemon does not answer', () => {
/** How long a call waits for the daemon before it gives up, and what it gives up with. */
const giveUp = async <T>(call: () => Promise<T>): Promise<[number, T | string]> => {
vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout', 'Date'] });
const started = Date.now();
let outcome: { value: T | string } | undefined;
call().then(
(value) => (outcome = { value }),
(error: Error) => (outcome = { value: error.message }),
);
while (!outcome) await vi.advanceTimersToNextTimerAsync();
return [Date.now() - started, outcome.value];
};
test('an action gives up after a minute, as the daemon being unreachable', async () => {
expect(await giveUp(() => bridge.invoke('page.clickElement'))).toEqual([
60_000,
{ ok: false, error: { code: 'DAEMON_UNREACHABLE', message: 'The Browsentic daemon did not respond' } },
]);
});
test('an action that declares a timeout waits that long plus ten seconds', async () => {
expect((await giveUp(() => bridge.invoke('page.waitForElement', { timeoutMs: 90_000 })))[0]).toBe(100_000);
});
test('starting a monitor waits a minute, whatever the watch itself is set to', async () => {
expect((await giveUp(() => bridge.invoke('page.startMonitor', { timeoutMs: 600_000 })))[0]).toBe(60_000);
});
test('awaiting a monitor or a pick waits for their own defaults plus ten seconds', async () => {
expect([(await giveUp(() => bridge.invoke('page.awaitMonitor')))[0], (await giveUp(() => bridge.invoke('page.pickElement')))[0]]).toEqual([130_000, 70_000]);
});
test('status and pairing say so, rather than answering with nothing', async () => {
expect([await giveUp(() => bridge.status()), await giveUp(() => bridge.pair()), await giveUp(() => bridge.agent())]).toEqual([
[60_000, 'The Browsentic daemon did not respond to a status request'],
[60_000, 'The Browsentic daemon did not issue a pairing code'],
[60_000, 'The Browsentic daemon did not answer about its agent'],
]);
});
test('lists come back empty and counts as zero', async () => {
expect([await giveUp(() => bridge.describe()), await giveUp(() => bridge.sessions()), await giveUp(() => bridge.revoke())]).toEqual([
[60_000, { tools: [] }],
[60_000, []],
[60_000, 0],
]);
});
describe('while the daemon says it is still working on an action', () => {
const unreachable = { ok: false, error: { code: 'DAEMON_UNREACHABLE', message: 'The Browsentic daemon did not respond' } };
/** Frames on one socket arrive in order, so once the manifest event is heard, so was the frame before it. */
const deliver = async (message: ControlMessage) => {
const read = new Promise<void>((resolve) => bridge.onManifestChanged(resolve));
daemonSide.send(JSON.stringify(message));
daemonSide.send(JSON.stringify({ event: 'manifest-changed' }));
await read;
};
const held = async () => {
const asked = new Promise<string>((resolve) => (answer = ({ id }) => (resolve(id), null)));
vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout', 'Date'] });
const started = Date.now();
const call = bridge.invoke('page.submitForm');
return { id: await asked, call, took: () => Date.now() - started };
};
test('the action outlives the minute, for as long as it keeps hearing so', async () => {
const { id, call, took } = await held();
for (let minute = 0; minute < 3; minute++) {
await vi.advanceTimersByTimeAsync(50_000);
await deliver({ id, op: 'working' });
}
await deliver({ id, op: 'invoke', result: { ok: true, data: { submitted: true } } });
expect([await call, took()]).toEqual([{ ok: true, data: { submitted: true } }, 150_000]);
});
test('once the daemon falls silent, the action gives up a minute after the last word', async () => {
const { id, call, took } = await held();
await vi.advanceTimersByTimeAsync(50_000);
await deliver({ id, op: 'working' });
let outcome: unknown;
void call.then((result) => (outcome = result));
while (!outcome) await vi.advanceTimersToNextTimerAsync();
expect([outcome, took()]).toEqual([unreachable, 110_000]);
});
});
test('once closed, calls fail at once without being sent', async () => {
await bridge.close();
await vi.waitFor(() => expect(daemonSide.readyState).toBe(daemonSide.CLOSED));
expect([await bridge.invoke('page.getPageInfo'), await bridge.describe(), received]).toEqual([
{ ok: false, error: { code: 'DAEMON_UNREACHABLE', message: 'The Browsentic daemon did not respond' } },
{ tools: [] },
[],
]);
});
});