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 { mkdirSync, rmSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
import { ToolListChangedNotificationSchema } from '@modelcontextprotocol/sdk/types.js';
import { afterEach, describe, expect, test } from 'vitest';
import { failure, success, type ActionResult } from '@/lib/actions/protocol';
import type { ToolDescriptor } from '@/lib/actions/manifest';
import { describeActions } from '@/lib/actions/registry';
import { FOCUS_SHOT_ACTION, SAVE_SITE_MAP_ACTION } from '@/lib/actions/reserved';
import { toolNameFor } from '@/lib/actions/tool-names';
import { configPath } from './agent/config';
import type { Bridge, BridgeStatus, Described } from './control';
import { FENCE_NOTE, IMAGE_NOTE, INJECT_ACTION, policyFrom } from './guardrails';
import { stateDir } from './lockfile';
import { grouped } from './tool-groups';
import { createMcpServer } from './server';
import { toolHost } from './tool-host';
const KEY = 'sk-ant-api03-AbCdEfGhIjKlMnOpQrStUvWxYz012345';
const GROUPED = describeActions()
.filter((action) => grouped(action.name))
.map((action) => action.name);
const PNG = 'data:image/png;base64,iVBORw0KGgo=';
type Answer = (action: string, input: unknown) => ActionResult;
/** A bridge that answers each action from a table, and remembers what it was asked. */
function fakeBridge(
answers: Record<string, ActionResult> | Answer = {},
status: Partial<BridgeStatus> = {},
tools: ToolDescriptor[] = describeActions(),
offer: Omit<Described, 'tools'> = {},
) {
const asked: [string, unknown][] = [];
const listeners: (() => void)[] = [];
const answer: Answer = typeof answers === 'function' ? answers : (action) => answers[action] ?? failure('UNKNOWN_ACTION', action);
const bridge: Bridge = {
describe: async () => ({ tools, ...offer }),
invoke: async (action, input) => {
asked.push([action, input]);
return answer(action, input);
},
status: async () => ({
connected: true,
daemonVersion: '0.0.0-test',
protocolVersion: 1,
port: 0,
manifestInSync: true,
connectedBrowsers: 1,
pairedBrowsers: 1,
pairingPending: false,
...status,
}),
onManifestChanged: (listener) => listeners.push(listener),
close: async () => {},
};
return { bridge, asked, changeManifest: () => listeners.forEach((listener) => listener()) };
}
async function connect(bridge: Bridge, opts: { agentRun?: boolean; resultBytes?: number } = {}): Promise<Client> {
const server = createMcpServer(bridge, '0.0.0-test', opts);
const [clientSide, serverSide] = InMemoryTransport.createLinkedPair();
const client = new Client({ name: 'test-client', version: '0.0.0' });
await Promise.all([server.connect(serverSide), client.connect(clientSide)]);
return client;
}
const call = async (client: Client, name: string, args: Record<string, unknown> = {}) =>
(await client.callTool({ name, arguments: args })) as { isError?: boolean; content: { type: string; text?: string; data?: string; mimeType?: string }[] };
const texts = (result: Awaited<ReturnType<typeof call>>) => result.content.flatMap((part) => (part.type === 'text' ? [part.text ?? ''] : []));
afterEach(() => {
rmSync(configPath, { force: true });
});
describe('the tool list', () => {
test('mirrors the action registry, plus the status tool and the guide opener', async () => {
const { tools } = await (await connect(fakeBridge().bridge)).listTools();
expect(tools.map(({ name, description, inputSchema }) => ({ name, description, inputSchema }))).toEqual([
...describeActions().map((action) => ({ name: toolNameFor(action.name), description: action.description, inputSchema: action.inputSchema })),
expect.objectContaining({ name: 'browsentic_status' }),
expect.objectContaining({ name: 'browsentic_openSkill' }),
]);
});
test('the guide opener names every guide, in the words of the need, with a schema that takes only those names', async () => {
const { tools } = await (await connect(fakeBridge().bridge)).listTools();
const opener = tools.find((tool) => tool.name === 'browsentic_openSkill')!;
expect({
lines: opener.description!.split('\n').slice(1).map((line) => line.split(':')[0]),
captcha: opener.description!.includes('- captcha: get past a “verify you are human” check'),
names: (opener.inputSchema.properties as { name: { enum: string[] } }).name.enum,
}).toEqual({
lines: ['- captcha', '- theming', '- diagnostics', '- monitoring', '- downloads', '- drag'],
captcha: true,
names: ['captcha', 'theming', 'diagnostics', 'monitoring', 'downloads', 'drag'],
});
});
test('the server instructions carry the same index, well inside what a client keeps of them', async () => {
const instructions = (await connect(fakeBridge().bridge)).getInstructions() ?? '';
expect({
opener: instructions.includes('opened with browsentic_openSkill'),
chromium: instructions.includes('- diagnostics: read the console errors, exceptions and failed requests behind a page that misbehaves (Chromium browsers only)'),
kept: instructions.length < 4_096,
}).toEqual({ opener: true, chromium: true, kept: true });
});
test('a run that reaches the grouped tools on demand lists the rest, then the tool that runs those', async () => {
const onDemand = GROUPED;
const { tools } = await (await connect(fakeBridge({}, {}, describeActions(), { reserved: [], onDemand, delivery: 'on-demand' }).bridge, { agentRun: true })).listTools();
expect(tools.map((tool) => tool.name)).toEqual([
...describeActions().filter((action) => !onDemand.includes(action.name)).map((action) => toolNameFor(action.name)),
'browsentic_status',
'browsentic_openSkill',
'browsentic_use',
]);
});
test('a namespaced run lists every tool to an MCP client, which takes no namespaces, and its guides say to call them by name', async () => {
const offer = { reserved: [], onDemand: GROUPED, delivery: 'namespaced' as const };
const client = await connect(fakeBridge({}, {}, describeActions(), offer).bridge, { agentRun: true });
const { tools } = await client.listTools();
const [guide] = texts(await call(client, 'browsentic_openSkill', { name: 'drag' }));
expect([tools.length, tools.some((tool) => tool.name === 'browsentic_use'), guide.split('\n\n')[2]]).toEqual([
describeActions().length + 2,
false,
'Call them by name, as you would any other tool.',
]);
});
test("a namespaced run hands a CLI that takes namespaces each group apart, named and described by its index line, for the CLI's own search", async () => {
const offer = { reserved: [], onDemand: GROUPED, delivery: 'namespaced' as const };
const host = toolHost(fakeBridge({}, {}, describeActions(), offer).bridge, { agentRun: true, namespaces: true, policy: policyFrom(undefined), tag: 'tag' });
const { tools, groups } = await host.list();
const [guide] = texts((await host.call('browsentic_openSkill', { name: 'captcha' })) as Awaited<ReturnType<typeof call>>);
expect({
listed: tools.map((tool) => tool.name).filter((name) => GROUPED.map(toolNameFor).includes(name) || name === 'browsentic_use'),
groups: groups.map((group) => [group.description.split(':')[0], group.name, group.tools.map((tool) => tool.name)]),
captcha: groups[0].description,
guide: guide.split('\n\n').find((part) => part.startsWith('They load')),
}).toEqual({
listed: [],
groups: [
['captcha', 'captcha', ['page_findCaptcha', 'page_solveCaptcha']],
['theming', 'theming', ['page_readTheme', 'page_auditContrast', 'page_applyTheme']],
['diagnostics', 'diagnostics', ['page_startDiagnostics', 'page_readConsole', 'page_readNetwork', 'page_stopDiagnostics']],
[
'monitoring',
'monitoring',
['page_findProgress', 'page_startMonitor', 'page_monitorStatus', 'page_awaitMonitor', 'page_stopMonitor', 'page_startTimer', 'page_timerStatus', 'page_stopTimer'],
],
['downloads', 'downloads', ['page_captureDownload', 'page_listDownloads']],
['drag', 'drag', ['page_dragElement']],
],
captcha: 'captcha: get past a “verify you are human” check: reCAPTCHA, hCaptcha, Turnstile',
guide:
'They load when you search for them: tool_search with "captcha" loads them all, then call each by name. Inside exec they are tools.captcha__<tool>, such as tools.captcha__page_findCaptcha.',
});
});
test('a namespaced run keeps a grouped tool it withholds, as on the phone, in its own group, so exec names it alike on every turn', async () => {
const off = ['page.findCaptcha', 'page.solveCaptcha', INJECT_ACTION];
const all = describeActions();
const offer = {
reserved: [],
withheld: all.filter((tool) => off.includes(tool.name)),
onDemand: GROUPED.filter((name) => !off.includes(name)),
delivery: 'namespaced' as const,
};
const bridge = fakeBridge({}, {}, all.filter((tool) => !off.includes(tool.name)), offer).bridge;
const { withheld, groups } = await toolHost(bridge, { agentRun: true, namespaces: true, policy: policyFrom(undefined), tag: 'tag' }).list();
expect({
withheld: withheld.map((tool) => tool.name),
captcha: groups.find((group) => group.name === 'captcha')?.tools.map((tool) => tool.name),
}).toEqual({ withheld: [toolNameFor(INJECT_ACTION)], captcha: ['page_findCaptcha', 'page_solveCaptcha'] });
});
test('a reserved tool is listed only when the daemon offers it to this caller', async () => {
const offered = (reserved: string[]) => fakeBridge({}, {}, describeActions(), { reserved }).bridge;
const names = async (bridge: Bridge) => (await (await connect(bridge, { agentRun: true })).listTools()).tools.slice(-2).map((tool) => tool.name);
expect([await names(offered([FOCUS_SHOT_ACTION])), await names(offered([]))]).toEqual([
['browsentic_openSkill', toolNameFor(FOCUS_SHOT_ACTION)],
['browsentic_status', 'browsentic_openSkill'],
]);
});
test('a daemon too old to say what it offers leaves an agent run with both reserved tools', async () => {
const { tools } = await (await connect(fakeBridge().bridge, { agentRun: true })).listTools();
expect(tools.slice(-4).map((tool) => tool.name)).toEqual([
'browsentic_status',
'browsentic_openSkill',
toolNameFor(SAVE_SITE_MAP_ACTION),
toolNameFor(FOCUS_SHOT_ACTION),
]);
});
test('an extension that describes an action no MCP client could call is refused, not passed on', async () => {
const client = await connect(fakeBridge({}, {}, [{ name: 'page.read page', description: '', inputSchema: { type: 'object' } }]).bridge);
await expect(client.listTools()).rejects.toThrow(/invalid MCP tool name/);
});
test('a manifest change reaches the client as a tool-list change', async () => {
const { bridge, changeManifest } = fakeBridge();
const client = await connect(bridge);
const notified = new Promise<void>((resolve) => client.setNotificationHandler(ToolListChangedNotificationSchema, () => resolve()));
changeManifest();
await expect(notified).resolves.toBeUndefined();
});
});
describe('a tool call', () => {
test('is handed to the bridge as the action it names, with its arguments', async () => {
const { bridge, asked } = fakeBridge({ 'page.clickElement': success({ clicked: true }) });
await call(await connect(bridge), 'page_clickElement', { target: { text: 'Buy' } });
expect(asked).toEqual([['page.clickElement', { target: { text: 'Buy' } }]]);
});
test('a page result comes back fenced as untrusted data, with any credential in it sealed', async () => {
const client = await connect(fakeBridge({ 'page.extractText': success({ content: `Your API key is ${KEY}` }) }).bridge);
const [body] = texts(await call(client, 'page_extractText'));
expect({
note: body.startsWith(FENCE_NOTE),
opens: /<<<untrusted-page-data:[0-9a-f]+>>>/.test(body),
closes: /<<<\/untrusted-page-data:[0-9a-f]+>>>/.test(body),
leaks: body.includes('AbCdEfGhIj'),
sealed: body.includes('⟦api-key:'),
}).toEqual({ note: true, opens: true, closes: true, leaks: false, sealed: true });
});
test('an acknowledgement is not fenced, but is still sealed', async () => {
const client = await connect(fakeBridge({ 'page.closeTab': success({ closed: KEY }) }).bridge);
const [body] = texts(await call(client, 'page_closeTab'));
expect([body.includes('untrusted-page-data'), body.includes('AbCdEfGhIj')]).toEqual([false, false]);
});
test('fencing can be turned off in config', async () => {
writeFileSync(configPath, JSON.stringify({ guardrails: { fence: false } }));
const client = await connect(fakeBridge({ 'page.extractText': success({ content: 'Pricing' }) }).bridge);
expect(texts(await call(client, 'page_extractText'))).toEqual([JSON.stringify({ content: 'Pricing' })]);
});
test('a failure comes back as an error that reads CODE: message, unfenced', async () => {
const client = await connect(fakeBridge({ 'page.clickElement': failure('TARGET_NOT_FOUND', 'No element matched "Buy".') }).bridge);
expect(await call(client, 'page_clickElement')).toEqual({
isError: true,
content: [{ type: 'text', text: 'TARGET_NOT_FOUND: No element matched "Buy".' }],
});
});
});
describe('a result, for an agent CLI that keeps long ones from its model', () => {
const LIMIT = 40_000;
test('over the limit is refused whole, saying the call went through and how to ask for less', async () => {
const client = await connect(fakeBridge({ 'page.getPageInfo': success({ links: 'x'.repeat(LIMIT) }) }).bridge, { resultBytes: LIMIT });
const result = await call(client, 'page_getPageInfo');
const [text] = texts(result);
expect([result.isError, text.startsWith('RESULT_TOO_LARGE: The call went through'), text.includes('maxPerKind')]).toEqual([true, true, true]);
});
test('is counted in bytes, so text that fits in characters can still be over', async () => {
const client = await connect(fakeBridge({ 'page.getPageInfo': success({ title: 'é'.repeat(LIMIT / 2) }) }).bridge, { resultBytes: LIMIT });
expect((await call(client, 'page_getPageInfo')).isError).toBe(true);
});
test('within it comes back as is, and a picture beside it does not count', async () => {
const big = `data:image/png;base64,${'A'.repeat(200_000)}`;
const client = await connect(fakeBridge({ 'page.screenshot': success({ dataUrl: big, format: 'png', width: 1280, height: 800 }) }).bridge, { resultBytes: LIMIT });
const result = await call(client, 'page_screenshot');
expect([result.isError, result.content.map((part) => part.type)]).toEqual([undefined, ['image', 'text']]);
});
test('a long read is asked for a group that fits, and a short one as asked', async () => {
const { bridge, asked } = fakeBridge({ 'page.extractText': success({ content: 'Pricing' }) });
const client = await connect(bridge, { resultBytes: LIMIT });
for (const args of [{}, { maxLength: 100_000 }, { maxLength: 500 }]) await call(client, 'page_extractText', args);
expect(asked.map(([, input]) => (input as { maxLength?: number }).maxLength)).toEqual([10_000, 10_000, 500]);
});
test('with no limit, nothing is refused or narrowed', async () => {
const { bridge, asked } = fakeBridge({ 'page.extractText': success({ content: 'x'.repeat(100_000) }) });
const result = await call(await connect(bridge), 'page_extractText', { maxLength: 100_000 });
expect([result.isError, asked]).toEqual([undefined, [['page.extractText', { maxLength: 100_000 }]]]);
});
});
test('a call the client stops waiting for tells the bridge so', async () => {
let given: AbortSignal | undefined;
const { bridge } = fakeBridge();
bridge.invoke = (_action, _input, signal) => {
given = signal;
return new Promise((resolve) => signal?.addEventListener('abort', () => resolve(failure('CANCELLED', 'gone'))));
};
const client = await connect(bridge);
const abandoned = new AbortController();
const pending = client.callTool({ name: 'page_clickElement', arguments: {} }, undefined, { signal: abandoned.signal });
await expect.poll(() => given).toBeDefined();
abandoned.abort();
await expect(pending).rejects.toThrow();
await expect.poll(() => given?.aborted).toBe(true);
});
describe('a screenshot', () => {
const shot = (data: Record<string, unknown>) => fakeBridge({ 'page.screenshot': success({ dataUrl: PNG, format: 'png', width: 1280, height: 800, ...data }) }).bridge;
test('comes back as the image, with a note that what it shows is untrusted', async () => {
const result = await call(await connect(shot({})), 'page_screenshot');
expect(result.content).toEqual([
{ type: 'image', data: 'iVBORw0KGgo=', mimeType: 'image/png' },
{ type: 'text', text: `${IMAGE_NOTE} Captured 1280×800 png.` },
]);
});
test('a saved screenshot says where it is, so the agent can show it', async () => {
const [note] = texts(await call(await connect(shot({ savedTo: '/Users/you/browsentic/screenshot/pricing.png' })), 'page_screenshot'));
expect(note).toContain('Saved to /Users/you/browsentic/screenshot/pricing.png. Show this screenshot to the user');
});
test('a save that failed is reported alongside a capture that did not', async () => {
const [note] = texts(await call(await connect(shot({ saveError: 'EACCES: permission denied', truncated: true })), 'page_screenshot'));
expect([note.includes('Requested save failed: EACCES: permission denied.'), note.includes('the bottom is cut off')]).toEqual([true, true]);
});
test('a result with no image in it is shown as it is', async () => {
const client = await connect(fakeBridge({ 'page.screenshot': success({ skipped: true }) }).bridge);
expect(texts(await call(client, 'page_screenshot'))).toEqual([JSON.stringify({ skipped: true })]);
});
});
describe('an open captcha challenge', () => {
test('comes back fenced, with the challenge attached as its picture', async () => {
const client = await connect(
fakeBridge({
'page.solveCaptcha': success({
state: 'challenge',
challenge: { kind: 'tiles', prompt: 'Select all images with a bus', tiles: 9, image: PNG, imageWidth: 788, imageHeight: 788 },
}),
}).bridge,
);
const result = await call(client, 'page_solveCaptcha');
expect({
fenced: result.content[0].text?.includes('untrusted-page-data'),
carriesImage: result.content[0].text?.includes('base64'),
image: result.content[1],
note: result.content[2].text,
}).toEqual({
fenced: true,
carriesImage: false,
image: { type: 'image', data: 'iVBORw0KGgo=', mimeType: 'image/png' },
note: `${IMAGE_NOTE} This is the open captcha challenge, 788×788 pixels, each tile numbered in its corner.`,
});
});
test('a solved captcha is only the result', async () => {
const client = await connect(fakeBridge({ 'page.solveCaptcha': success({ state: 'solved', solved: true }) }).bridge);
expect((await call(client, 'page_solveCaptcha')).content).toHaveLength(1);
});
});
describe('a picked element', () => {
test('comes back fenced, with its photograph attached', async () => {
const client = await connect(fakeBridge({ 'page.pickElement': success({ selector: 'button#buy', text: 'Buy now', shot: { dataUrl: PNG } }) }).bridge);
const result = await call(client, 'page_pickElement');
expect({
fenced: result.content[0].text?.includes('untrusted-page-data'),
carriesShot: result.content[0].text?.includes('dataUrl'),
image: result.content[1],
note: result.content[2].text,
}).toEqual({
fenced: true,
carriesShot: false,
image: { type: 'image', data: 'iVBORw0KGgo=', mimeType: 'image/png' },
note: `${IMAGE_NOTE} This is the picked element photographed at the instant the user clicked it.`,
});
});
test('without a photograph it is only the fenced result', async () => {
const client = await connect(fakeBridge({ 'page.pickElement': success({ selector: 'button#buy' }) }).bridge);
expect((await call(client, 'page_pickElement')).content).toHaveLength(1);
});
test("the element the user pointed at before the instruction comes back as its image", async () => {
const client = await connect(fakeBridge({ [FOCUS_SHOT_ACTION]: success({ dataUrl: PNG }) }).bridge, { agentRun: true });
expect((await call(client, toolNameFor(FOCUS_SHOT_ACTION))).content).toEqual([
{ type: 'image', data: 'iVBORw0KGgo=', mimeType: 'image/png' },
{ type: 'text', text: `${IMAGE_NOTE} This is the element the user pointed at with A-Eye, as it stood when they picked it.` },
]);
});
test('with no pick attached to the instruction, the focus shot is the failure it returned', async () => {
const client = await connect(fakeBridge({ [FOCUS_SHOT_ACTION]: failure('NO_FOCUS', 'No element was picked.') }).bridge, { agentRun: true });
expect(await call(client, toolNameFor(FOCUS_SHOT_ACTION))).toMatchObject({ isError: true });
});
});
describe('a guide', () => {
const open = async (name: unknown, tools?: ToolDescriptor[]) => call(await connect(fakeBridge({}, {}, tools).bridge), 'browsentic_openSkill', { name });
test("opens with its skill, then each of its tools with the description and schema it is listed with", async () => {
const [text] = texts(await open('drag'));
const drag = describeActions().find((action) => action.name === 'page.dragElement')!;
expect(text).toBe(
`# The drag guide\n\n## Its tools\n\nCall them by name, as you would any other tool.\n\n` +
`### page_dragElement\n${drag.description}\nInput schema: ${JSON.stringify(drag.inputSchema)}`,
);
});
test('tells a run that reaches its tools on demand to call them through browsentic_use', async () => {
const onDemand = GROUPED;
const client = await connect(fakeBridge({}, {}, describeActions(), { reserved: [], onDemand, delivery: 'on-demand' }).bridge);
const [text] = texts(await call(client, 'browsentic_openSkill', { name: 'drag' }));
expect(text.split('\n\n')[2]).toBe(
'They are not in your tool list. Call each through browsentic_use, its name as action and its parameters as input: {"action": "page_dragElement", "input": {...}}.',
);
});
test('monitoring teaches watching and timers, in that order, and lists all eight tools', async () => {
const [text] = texts(await open('monitoring'));
expect({
order: text.indexOf('You are setting up a watch') < text.indexOf('The extension keeps the clock'),
tools: [...text.matchAll(/^### (\S+)$/gm)].map((match) => match[1]),
}).toEqual({
order: true,
tools: ['page_findProgress', 'page_startMonitor', 'page_monitorStatus', 'page_awaitMonitor', 'page_stopMonitor', 'page_startTimer', 'page_timerStatus', 'page_stopTimer'],
});
});
test('a skill the user rewrote is the one the guide opens with', async () => {
mkdirSync(join(stateDir, 'skills'), { recursive: true });
writeFileSync(join(stateDir, 'skills', 'captcha.md'), '---\nname: captcha\ndescription: mine\n---\nAsk me before any captcha.\n');
try {
const [text] = texts(await open('captcha'));
expect(text.startsWith('# The captcha guide\n\nAsk me before any captcha.\n\n## Its tools')).toBe(true);
} finally {
rmSync(join(stateDir, 'skills'), { recursive: true, force: true });
}
});
test('opens by its skill or any of its tools as well as by its own name', async () => {
const heading = async (name: string) => texts(await open(name))[0].split('\n')[0];
expect(await Promise.all(['theming', 'page-theming', 'page_applyTheme', 'page.readTheme', 'auditContrast', 'scheduled-jobs'].map(heading))).toEqual([
'# The theming guide',
'# The theming guide',
'# The theming guide',
'# The theming guide',
'# The theming guide',
'# The monitoring guide',
]);
});
test('names what this run is not offered, and refuses a guide with nothing to offer', async () => {
const phone = describeActions().filter((action) => ['page.findProgress', 'page.startTimer', 'page.timerStatus', 'page.stopTimer'].includes(action.name));
const monitoring = await open('monitoring', phone);
const firefox = await open('captcha', describeActions('firefox'));
expect({
offered: [...texts(monitoring)[0].matchAll(/^### (\S+)$/gm)].map((match) => match[1]),
missing: texts(monitoring)[0].endsWith('Not offered in this run: page_startMonitor, page_monitorStatus, page_awaitMonitor, page_stopMonitor.'),
firefox: [firefox.isError, texts(firefox)[0]],
}).toEqual({
offered: ['page_findProgress', 'page_startTimer', 'page_timerStatus', 'page_stopTimer'],
missing: true,
firefox: [true, 'UNAVAILABLE: None of the captcha tools are offered in this run; they run only in a Chromium browser such as Chrome or Edge, on a computer.'],
});
});
test('an unknown name is answered with every guide there is', async () => {
const reply = await open('sliders');
expect([reply.isError, texts(reply)[0].split('\n').slice(0, 2)]).toEqual([
true,
['UNKNOWN_SKILL: There is no guide named "sliders". The guides are:', '- captcha: get past a “verify you are human” check: reCAPTCHA, hCaptcha, Turnstile (Chromium browsers only)'],
]);
});
});
describe('a call through browsentic_use', () => {
test('reaches the bridge exactly as the listed tool would, and reads back the same', async () => {
const answers = { 'page.dragElement': success({ dropped: true }) };
const direct = fakeBridge(answers);
const through = fakeBridge(answers);
const input = { from: { text: 'Card' }, to: { text: 'Done' } };
const replies = [
await call(await connect(direct.bridge), 'page_dragElement', input),
await call(await connect(through.bridge), 'browsentic_use', { action: 'page_dragElement', input }),
];
expect([through.asked, replies[1].content.length, texts(replies[1])[0].replace(/[0-9a-f]{8,}/g, '')]).toEqual([
direct.asked,
replies[0].content.length,
texts(replies[0])[0].replace(/[0-9a-f]{8,}/g, ''),
]);
});
test('takes the action as an agent CLI shows its tool', async () => {
const { bridge, asked } = fakeBridge({ 'page.dragElement': success({ dragged: true }) });
const client = await connect(bridge);
for (const action of ['mcp__browsentic__page_dragElement', 'browsentic__page_dragElement', 'browsentic_page_dragElement']) {
await call(client, 'browsentic_use', { action, input: { from: 1 } });
}
expect(asked.map(([action]) => action)).toEqual(['page.dragElement', 'page.dragElement', 'page.dragElement']);
});
test('takes the action as its tool, its action or bare, and the input as an object, a JSON string or flat', async () => {
const { bridge, asked } = fakeBridge({ 'page.solveCaptcha': success({ state: 'solved' }) });
const client = await connect(bridge);
await call(client, 'browsentic_use', { action: 'page_solveCaptcha', input: { tiles: [1] } });
await call(client, 'browsentic_use', { action: 'page.solveCaptcha', input: '{"tiles":[2]}' });
await call(client, 'browsentic_use', { action: 'solveCaptcha', tiles: [3] });
await call(client, 'browsentic_use', { action: 'solveCaptcha' });
expect(asked).toEqual([
['page.solveCaptcha', { tiles: [1] }],
['page.solveCaptcha', { tiles: [2] }],
['page.solveCaptcha', { tiles: [3] }],
['page.solveCaptcha', {}],
]);
});
test("renders a result as its own tool does: an open captcha comes back as its picture", async () => {
const challenge = { kind: 'tiles', prompt: 'Select all buses', image: PNG, imageWidth: 300, imageHeight: 300 };
const client = await connect(fakeBridge({ 'page.solveCaptcha': success({ state: 'challenge', challenge }) }).bridge);
const reply = await call(client, 'browsentic_use', { action: 'solveCaptcha' });
expect(reply.content.map((part) => part.type)).toEqual(['text', 'image', 'text']);
});
test('invalid input comes back with the schema to correct it by', async () => {
const client = await connect(fakeBridge({ 'page.dragElement': failure('INVALID_INPUT', '✖ Invalid input') }).bridge);
const [text] = texts(await call(client, 'browsentic_use', { action: 'dragElement', input: { from: 3 } }));
const schema = describeActions().find((action) => action.name === 'page.dragElement')!.inputSchema;
expect(text).toBe(`INVALID_INPUT: ✖ Invalid input\npage_dragElement takes: ${JSON.stringify(schema)}`);
});
test('input that is not an object is refused before it reaches the browser', async () => {
const { bridge, asked } = fakeBridge();
const reply = await call(await connect(bridge), 'browsentic_use', { action: 'dragElement', input: '[1, 2' });
expect([reply.isError, texts(reply)[0], asked]).toEqual([
true,
"INVALID_INPUT: input must be an object, or a JSON string of one, holding page_dragElement's parameters.",
[],
]);
});
test('an action that does not exist, or is not a page action, is answered with the guides and never invoked', async () => {
const { bridge, asked } = fakeBridge();
const client = await connect(bridge);
const replies = await Promise.all(['page_sliders', 'browsentic_status', 'browsentic_use'].map((action) => call(client, 'browsentic_use', { action })));
expect([replies.map((reply) => texts(reply)[0].split('\n')[0]), asked]).toEqual([
[
'UNKNOWN_ACTION: There is no browser action named "page_sliders". Open the guide that covers what you need with browsentic_openSkill:',
'UNKNOWN_ACTION: There is no browser action named "browsentic_status". Open the guide that covers what you need with browsentic_openSkill:',
'UNKNOWN_ACTION: There is no browser action named "browsentic_use". Open the guide that covers what you need with browsentic_openSkill:',
],
[],
]);
});
});
describe('the status tool', () => {
const statusOf = async (answers: Record<string, ActionResult>, status: Partial<BridgeStatus> = {}) =>
JSON.parse(texts(await call(await connect(fakeBridge(answers, status).bridge), 'browsentic_status'))[0]) as Record<string, unknown>;
test('with no browser connected, it says to open one', async () => {
expect(await statusOf({}, { connected: false })).toMatchObject({ connected: false, activeTab: null, hint: 'Open your browser with the Browsentic extension loaded.' });
});
test('with a browser connected, it names the active tab and any monitors running', async () => {
const status = await statusOf({
'page.getPageInfo': success({ document: { url: 'https://example.com/pricing', title: 'Pricing' }, layout: { diagram: '' } }),
'page.monitorStatus': success({ monitors: [{ monitorId: 'm1', label: 'Export', host: 'example.com', phase: 'running', percent: 40, internal: 'x' }] }),
});
expect([status.activeTab, status.monitors, 'hint' in status]).toEqual([
{ url: 'https://example.com/pricing', title: 'Pricing' },
[{ monitorId: 'm1', label: 'Export', host: 'example.com', phase: 'running', percent: 40 }],
false,
]);
});
test('an extension and a Bridge of different versions, and a tab it cannot read, are both explained', async () => {
const status = await statusOf({ 'page.getPageInfo': failure('TAB_UNREACHABLE', 'chrome:// page') }, { manifestInSync: false });
expect({ activeTab: status.activeTab, drifted: String(status.hint).includes('different versions'), unreadable: String(status.hint).includes('Cannot read the active tab (TAB_UNREACHABLE)') }).toEqual({
activeTab: null,
drifted: true,
unreadable: true,
});
});
});
describe('resources', () => {
const pageInfo = success({ document: { url: 'https://example.com', title: 'Example' }, layout: { diagram: '[header] [main] [footer]' } });
test('three read-only views of the page are listed', async () => {
const { resources } = await (await connect(fakeBridge().bridge)).listResources();
expect(resources.map((resource) => resource.uri)).toEqual(['browsentic://page/current', 'browsentic://page/diagram', 'browsentic://page/text']);
});
test("the page's text is read fenced and sealed", async () => {
const client = await connect(fakeBridge({ 'page.extractText': success({ content: `token ${KEY}` }) }).bridge);
const [{ text }] = (await client.readResource({ uri: 'browsentic://page/text' })).contents as { text: string }[];
expect([text.includes('untrusted-page-data'), text.includes('AbCdEfGhIj')]).toEqual([true, false]);
});
test("the diagram is only the page's layout, and asks for as little as it can", async () => {
const { bridge, asked } = fakeBridge({ 'page.getPageInfo': pageInfo });
const [{ text }] = (await (await connect(bridge)).readResource({ uri: 'browsentic://page/diagram' })).contents as { text: string }[];
expect([text.includes('[header] [main] [footer]'), text.includes('example.com'), asked]).toEqual([true, false, [['page.getPageInfo', { maxPerKind: 1 }]]]);
});
test('the snapshot is the whole page info', async () => {
const [{ text }] = (await (await connect(fakeBridge({ 'page.getPageInfo': pageInfo }).bridge)).readResource({ uri: 'browsentic://page/current' }))
.contents as { text: string }[];
expect(text).toContain('"title": "Example"');
});
// Resources have no error result, so a failure has to be thrown to reach the client at all.
test('a page that cannot be read throws, with the code and message', async () => {
const client = await connect(fakeBridge({ 'page.getPageInfo': failure('TAB_UNREACHABLE', 'The active tab is a chrome:// page') }).bridge);
await expect(client.readResource({ uri: 'browsentic://page/current' })).rejects.toThrow('TAB_UNREACHABLE: The active tab is a chrome:// page');
});
test('a resource that does not exist throws', async () => {
await expect((await connect(fakeBridge().bridge)).readResource({ uri: 'browsentic://page/cookies' })).rejects.toThrow('Unknown resource');
});
});