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
test(agent): pin what a site-mapping run may read, where it may go and what it may spend
Shahriar0cf77d7f9620
diff --git a/src/daemon/agent/mapping.test.ts b/src/daemon/agent/mapping.test.tsnew file mode 100644index 0000000..fcf7d06--- /dev/null+++ b/src/daemon/agent/mapping.test.ts@@ -0,0 +1,128 @@+import { describe, expect, test } from 'vitest';+import { failure, success } from '@/lib/actions/protocol';+import { SAVE_SITE_MAP_ACTION } from '@/lib/actions/reserved';+import { gateMappingInvoke, noteMappingResult, type MapRun } from './mapping';++const mapRun = (settings: Partial<MapRun['settings']> = {}, visited: string[] = []): MapRun => ({+ target: { host: 'www.example.com', origin: 'https://www.example.com', domain: 'example.com', name: 'example-com' },+ staging: { id: 'staging-1', dir: '/staging', screenshots: '/staging/screenshots', evidence: '/staging/evidence', pages: '/staging/pages' },+ index: { source: 'none', documents: 0, urlCount: 0, truncated: false, paths: [], patterns: [], raw: '' },+ settings: { research: true, allowClicks: false, maxPages: 3, maxScreenshots: 2, timeoutMs: 60_000, ...settings },+ shots: 0,+ pagesVisited: new Set(visited),+ offSite: null,+ submitted: false,+});++const verdict = (run: MapRun, action: string, input: unknown = {}) => {+ const gate = gateMappingInvoke(run, action, input);+ return gate.allow ? 'allowed' : gate.result.ok ? 'allowed' : gate.result.error.code;+};++describe('what a mapping run may do', () => {+ test('looking at a page is allowed', () => {+ expect(['page.getPageInfo', 'page.extractText', 'page.scrollTo', 'page.hoverElement', 'page.findSearch'].map((action) => verdict(mapRun(), action))).toEqual(+ Array(5).fill('allowed'),+ );+ });++ test('changing a page is not', () => {+ expect(['page.fillInput', 'page.submitForm', 'page.typeText', 'page.runScript'].map((action) => verdict(mapRun(), action))).toEqual(+ Array(4).fill('MAPPING_READ_ONLY'),+ );+ });++ test('clicking is refused unless the settings allow it', () => {+ expect([verdict(mapRun(), 'page.clickElement'), verdict(mapRun({ allowClicks: true }), 'page.clickElement')]).toEqual(['MAPPING_READ_ONLY', 'allowed']);+ });++ test('handing in the report is always allowed, and no other reserved action is', () => {+ expect([verdict(mapRun(), SAVE_SITE_MAP_ACTION), verdict(mapRun(), 'browsentic.focusShot')]).toEqual(['allowed', 'UNKNOWN_ACTION']);+ });+});++describe('navigating while mapping', () => {+ test('any page on the site being mapped is allowed', () => {+ expect(verdict(mapRun(), 'page.navigate', { url: 'https://www.example.com/pricing' })).toBe('allowed');+ });++ test('another origin is off the site, subdomain or not', () => {+ expect(+ ['https://evil.example/', 'https://docs.example.com/', 'http://www.example.com/'].map((url) => verdict(mapRun(), 'page.navigate', { url })),+ ).toEqual(Array(3).fill('MAPPING_OFF_SITE'));+ });++ test('a relative address is refused with an example of an absolute one', () => {+ const gate = gateMappingInvoke(mapRun(), 'page.navigate', { url: '/pricing' });+ expect(gate).toEqual({+ allow: false,+ result: failure('MAPPING_OFF_SITE', 'While mapping, page_navigate needs an absolute URL like https://www.example.com/pricing — not "/pricing".'),+ });+ });++ test('going back or forward is refused, because history can lead anywhere, but reloading is fine', () => {+ expect(['back', 'forward', 'reload'].map((action) => verdict(mapRun(), 'page.navigate', { action }))).toEqual([+ 'MAPPING_OFF_SITE',+ 'MAPPING_OFF_SITE',+ 'allowed',+ ]);+ });++ test('navigating nowhere is invalid', () => {+ expect([verdict(mapRun(), 'page.navigate', {}), verdict(mapRun(), 'page.navigate', { url: ' ' })]).toEqual(['INVALID_INPUT', 'INVALID_INPUT']);+ });++ test('once the page budget is spent, only pages already seen may be revisited', () => {+ const run = mapRun({ maxPages: 2 }, ['/', '/pricing']);+ expect([+ verdict(run, 'page.navigate', { url: 'https://www.example.com/docs' }),+ verdict(run, 'page.navigate', { url: 'https://www.example.com/pricing?plan=pro' }),+ ]).toEqual(['MAPPING_BUDGET', 'allowed']);+ });+});++describe('drifting off the site', () => {+ test('a tab that lands elsewhere may only navigate back until it returns', () => {+ const run = mapRun();+ noteMappingResult(run, 'page.navigate', success({ navigatedTo: 'https://accounts.example.net/login' }));+ const whileAway = [verdict(run, 'page.getPageInfo'), verdict(run, 'page.navigate', { url: 'https://www.example.com/' })];+ noteMappingResult(run, 'page.getPageInfo', success({ document: { url: 'https://www.example.com/' } }));+ expect([whileAway, verdict(run, 'page.getPageInfo'), run.offSite]).toEqual([['MAPPING_OFF_SITE', 'allowed'], 'allowed', null]);+ });++ test('each page landed on is counted once, by path', () => {+ const run = mapRun();+ for (const url of ['https://www.example.com/', 'https://www.example.com/pricing', 'https://www.example.com/pricing#faq']) {+ noteMappingResult(run, 'page.navigate', success({ navigatedTo: url }));+ }+ expect([...run.pagesVisited]).toEqual(['/', '/pricing']);+ });++ test('a failed action, or one that says nothing about where the tab is, changes nothing', () => {+ const run = mapRun();+ noteMappingResult(run, 'page.navigate', failure('TIMEOUT', 'slow'));+ noteMappingResult(run, 'page.extractText', success({ content: 'https://evil.example' }));+ noteMappingResult(run, 'page.navigate', success({ navigatedTo: 'not a url' }));+ expect([run.pagesVisited.size, run.offSite]).toEqual([0, null]);+ });+});++describe('screenshots while mapping', () => {+ test('each is saved into the staged map, numbered and named after the last page seen', () => {+ const run = mapRun({}, ['/', '/Plans & Pricing']);+ expect(gateMappingInvoke(run, 'page.screenshot', {})).toEqual({+ allow: true,+ saveTo: { dir: '/staging/screenshots', filename: '01-plans-pricing.png' },+ });+ });++ test('the home page is named home', () => {+ expect(gateMappingInvoke(mapRun(), 'page.screenshot', {})).toMatchObject({ saveTo: { filename: '01-home.png' } });+ });++ test('a taken screenshot counts against the budget, and a spent budget refuses the next', () => {+ const run = mapRun({ maxScreenshots: 1 });+ noteMappingResult(run, 'page.screenshot', success({ dataUrl: 'data:image/png;base64,' }));+ expect([run.shots, verdict(run, 'page.screenshot')]).toEqual([1, 'MAPPING_BUDGET']);+ });+});