@agent-forge/plugin-browser-playwright

Built-in Playwright browser capability plugin for Agent Forge — the product's single browser channel. It registers seventeen base tools covering the common Playwright operations prewritten so the model calls them directly; full-control hosts with an interaction face additionally register browser_login for persistent sign-in. browser_evaluate is the declared escape hatch for everything the built-in tools do not cover. agent-forge.browser.fetch@1 is the plugin-to-plugin face used by consumer plugins to load a page through the shared named profile without exposing Playwright or storage state.

Playwright is never bundled: the package has no Playwright dependency. The driver resolves playwright at connect time from <agentDir>/browser-deps via createRequire, and browser_setup installs it on first use (npm install playwright --prefix <dir>, then npx playwright install chromium, browsers pinned to <dir>/browsers through PLAYWRIGHT_BROWSERS_PATH). Every other browser tool, when it finds Playwright missing, returns a structured failure whose message carries the two exact install commands plus a pointer to browser_setup.

Tool surface

Session and setup

| Tool | Parameters | Notes | | --- | --- | --- | | browser_navigate | {url, waitUntil?} | Opens the session on first use. | | browser_login | {url, profile?, timeoutMs?} | Full-control + interaction only. Opens a visible Chromium window with the named profile (default), lets the user sign in, and saves the storage state only after the interaction confirm. Confirmation timeout defaults to 300s (60s..600s); cancel/timeout/close saves nothing. | | browser_setup | {} | Installs Playwright + Chromium into <agentDir>/browser-deps; short-circuits with alreadyInstalled. |

Observation (registered in readonly mode too)

| Tool | Parameters | Notes | | --- | --- | --- | | browser_snapshot | {includeDom?, includeA11y?, includeStyles?, includeScreenshot?} | a11y evidence is the Playwright aria snapshot (bounded 16KiB), DOM is page.content() (bounded 64KiB). Screenshots ride as image content blocks (PNG, 16MiB capture bound); the host's image normalizer owns the provider inline budget for every tool. Evidence carries only a byte-count marker. Styles capture is declared not_supported_in_this_build; the parameter is accepted for contract compatibility. The summary and evidence also report the most recent downloaded file, if any. | | browser_assert_postcondition | {condition} — one condition or an array of 1..32 (all ANDed) | Over url / element / text / console / network state; console and network come from 200-entry page ring buffers. | | browser_collect_evidence | {kind: console\|network\|snapshot} | Raw bounded evidence dump. | | browser_console | {level?, contains?, limit?} | Reads the console ring buffer. level is comma-combined error/warning/info/debug (info also matches Playwright's log type); limit defaults to 50, capped at 200. Returns {total, returned:[{type,text,location?,timestamp}]}; auto-accepted dialogs appear as type: "dialog" entries. | | browser_network | {containsUrl?, status?, method?, limit?} | Reads the network ring buffer. Returns {total, returned:[{method,url,status,timestamp,durationMs?,sizeBytes?}]}; duration/size are included only when the request timing and content-length header are available. | | browser_performance | {} | Navigation Timing (TTFB / DOMContentLoaded / load), paint (FP/FCP), resource summary (count, total transfer bytes, slowest 5 by duration), and DOM node count. Read-only. | | browser_wait | {until: selector\|navigation\|networkidle\|time, locator?, ms?} | selector requires locator (waits for visible); time requires ms. ms is clamped to 0..30000 (default 30000 for the non-time kinds). Returns requested/effective/actual wait durations; timeout failures map to browser_wait_timeout. |

Interaction (never registered in readonly mode)

| Tool | Parameters | Notes | | --- | --- | --- | | browser_locator_action | {locator: {kind: css\|id\|role\|text\|test-id, value, name?}, action, value?, key?, delay?} | Actions: click, dblclick, rightclick, fill, type, press, hover, select, check, uncheck, clear, upload (value = one absolute path or a JSON array of paths, applied via setInputFiles), scroll (value = <direction>:<pixels>, e.g. down:500; scrolls the element into view, then wheels by pixels). Returns a post-action aria-snapshot fragment. | | browser_evaluate | {expression, arg?} | Escape hatch — only use when no built-in tool covers the operation. Runs page.evaluate; the JSON-serialized result is bounded to 64KiB (undefined serializes as undefined); 30s wall-clock timeout leaves the page-side script to finish on its own. Dialogs fired during evaluation are auto-accepted. | | browser_drag | {from, to, steps?} | Hover source → mouse down → stepped mouse.move to the target center by geometry (Locator.hover has no steps option, so the refined movement is a wheel-free mouse move; steps defaults to 8, clamped 1..100) → mouse up. The target is deliberately not hovered while the button is down. Skips the refined move when the target has no bounding box. | | browser_mouse | {action: move\|click\|dblclick\|rightclick\|wheel, x, y, deltaX?, deltaY?, button?} | Raw viewport-coordinate actions without needing an element; wheel is the basic page-scroll primitive. | | browser_press_key | {key, delay?} | Page-level page.keyboard.press with Playwright key names (Control+a, Enter, Meta+c). | | browser_tabs | {action: list\|new\|switch\|close, index?, url?} | Tab set tracked by the driver; switch re-points the current page for all subsequent tools. | | browser_storage | {action: get-cookies\|set-cookie\|clear-cookies\|get-local\|set-local\|clear-local, name?, value?, domain?, path?, expires?, key?} | Cookies go through the context (set-cookie requires name/value/domain); localStorage through the page. | | browser_viewport | {action: set\|get, width?, height?} | set clamps both dimensions into 320..7680 and reports the requested values when clamping occurred. |

All results are PluginResultV1; structured payloads (console/network entries, performance metrics, evaluate results, storage and tab state) are carried as bounded JSON text (64KiB) in evidence summaries. Readonly host mode registers exactly the seven observation tools (snapshot, assert_postcondition, collect_evidence, console, network, performance, wait); everything that changes browser or disk state never registers there.

Shared browser profiles and browser.fetch@1

browser_login writes <agentDir>/browser/profiles/<name>/storage-state.json (0600) and keeps the previous snapshot as storage-state.backup.json. The profile lock (.lock) is held from snapshot load through browser close; a second writer returns browser_profile_busy after a 10s wait. Snapshots are capped at 10 MiB and written through a same-directory temp file + fsync + rename.

agent-forge.browser.fetch@1 (declared under provides) is the read-only retrieval face: it loads the named snapshot without the write lock, opens headless Chromium, and returns {version, finalUrl, title?, text, truncated} with at most 16K characters. It never returns cookies, localStorage, or auth files. The capability is also provided in readonly mode; browser_login is not. The shared profile is a convenience boundary, not a credential-isolation boundary — generic browser_storage and page scripts can still read what the loaded context exposes.

Built-in dialog and download policies

No dedicated tools; the driver applies both policies to every opened page:

• Dialogs are auto-accepted (dialog.accept()) and recorded into the console ring buffer as a [dialog] <type>: <message> entry, so browser_console and the console postcondition can observe them.
• Downloads are saved into <agentDir>/browser-deps/downloads/ (directory created lazily) and the most recent filename is attached to browser_snapshot results. When no agentDir is known, the filename is still reported but the file is not saved.

Injection surface

createBrowserCapabilityFactoryV1(runtime) accepts any BrowserRuntimeV1 = {connect(): Promise<BrowserDriverV1>; setup?(); login?(); fetch?()} — tests and brokered hosts inject fakes. The shipped runtime, PlaywrightBrowserRuntimeV1, supports agentDir/browserDepsDir/headless, plus deterministic spawnSync/resolvePlaywright/loadPlaywright/ensureDir seams for the installer, the lazy module load, and the downloads directory. The default export of dist/entry.js composes it from the host's api.host.agentDir.

Real-browser test

The deterministic suites never download or spawn anything. A real end-to-end session (install -> navigate example.com -> snapshot -> click -> console -> performance -> evaluate -> press key -> viewport -> close) runs only with AGENT_FORGE_BROWSER_REAL_TEST=1 and network access; it uses a throwaway agent dir and removes it afterwards.

Development

npm install --ignore-scripts        # repo root, creates the workspace symlink
npm run build                       # plugins/browser-playwright (tsgo)
npm test                            # vitest; the entry fidelity test requires `npm run build` first