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.

test(daemon): serve MCP to a real client from a fake bridge, and pin the tool list, fencing, sealing, images and resources

Shahriar2625c1236884
diff --git a/src/daemon/server.test.ts b/src/daemon/server.test.ts
new file mode 100644
index 0000000..eb6be9f
--- /dev/null
+++ b/src/daemon/server.test.ts
@@ -0,0 +1,261 @@
+import { rmSync, writeFileSync } from 'node:fs';
+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 } from './control';
+import { FENCE_NOTE, IMAGE_NOTE } from './guardrails';
+import { createMcpServer } from './server';
+
+const KEY = 'sk-ant-api03-AbCdEfGhIjKlMnOpQrStUvWxYz012345';
+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()) {
+ 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,
+ 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,
+ 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 } = {}): 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', 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' }),
+ ]);
+ });
+
+ test("an agent run is also offered the site-map report and the picked element's screenshot", async () => {
+ const { tools } = await (await connect(fakeBridge().bridge, { agentRun: true })).listTools();
+ expect(tools.slice(-3).map((tool) => tool.name)).toEqual(['browsentic_status', 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' }, null, 2)]);
+ });
+
+ 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 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 }, null, 2)]);
+ });
+});
+
+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('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 older than the daemon, 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, stale: String(status.hint).includes('older build'), unreadable: String(status.hint).includes('Cannot read the active tab (TAB_UNREACHABLE)') }).toEqual({
+ activeTab: null,
+ stale: 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');
+ });
+});