@postqode/browser

Browser automation tools for @postqode/agent. Uses playwright-core (peer dependency) under the hood.

What ships

Two API shapes. Pick the one that matches your agent's needs.

Stateless (one Chrome per call)

• browser_navigate_and_read — opens a URL headless, extracts visible text, closes the browser. Caps returned text at maxChars (default 8000). Honors the agent's ctx.signal for mid-navigation abort.

Use when the agent only needs to read pages during research.

import { createCodingAgent } from "@postqode/coding-agent"
import { createBrowserTools } from "@postqode/browser"

const agent = createCodingAgent({
	api,
	extraTools: createBrowserTools(),
})
await agent.run("Fetch https://example.com and summarize the headline.")

Session-based (shared page across tool calls)

A BrowserSession keeps one Browser + BrowserContext alive across the whole conversation, with multi-tab support, buffered console + network logs, configurable dialog policy, network mocking and Playwright tracing. 34 session-bound tools operate on the active tab — related primitives are collapsed into action-discriminator tools (cookies, localStorage, sessionStorage, state, route, tracing, mouse, key) so the full surface fits in ~2,500 prompt tokens.

Navigation

| Tool | Purpose | |---|---| | browser_navigate | Goto URL, wait for load / domcontentloaded / networkidle. | | browser_navigate_back | Go back (or forward) in history. | | browser_reload | Reload the active page. |

Observation

| Tool | Purpose | |---|---| | browser_read | Visible text (optionally CSS-scoped). | | browser_snapshot | ARIA accessibility snapshot (YAML). Prefer for stable element refs. | | browser_screenshot | PNG of page or selector; save to path or return base64. | | browser_pdf | Render the page as PDF (Chromium-only). |

Interaction

| Tool | Purpose | |---|---| | browser_click / browser_dblclick | Click or double-click a selector's nth match. | | browser_hover | Move the mouse over a selector. | | browser_type | Fill an input; optional clear + Enter-press. | | browser_select_option | Select <option> by value or label. | | browser_check / browser_uncheck | Tick / untick a checkbox or radio. | | browser_file_upload | Set files on <input type=file> from absolute paths. | | browser_drag | Drag one selector onto another. | | browser_press_key | Press a key (Enter, Escape, ArrowDown, Control+A …); optional selector to focus first. | | browser_wait | Wait for a selector to attach OR a load-state. |

Low-level mouse + keyboard

| Tool | Purpose | |---|---| | browser_mouse_move / _down / _up / _wheel | Absolute-coordinate mouse primitives. | | browser_key_down / _up | Hold / release a key for chord input. |

JS / state

| Tool | Purpose | |---|---| | browser_eval | Run JS in the page context; JSON-serialize the result. | | browser_resize | Resize the viewport. | | browser_tabs | List / new / select / close tabs. |

Inspection

| Tool | Purpose | |---|---| | browser_console_messages | Buffered console + page-errors; filter by type, clear. | | browser_network_requests | Buffered network requests; filter by URL / resource type / failed-only. | | browser_handle_dialog | Pre-register accept/dismiss (with optional prompt text) for the next dialog. |

Cookies + storage

| Tool | Purpose | |---|---| | browser_cookie_list / _get / _set / _delete / _clear | Manage browser cookies. | | browser_localstorage_list / _get / _set / _delete / _clear | Per-origin localStorage. | | browser_sessionstorage_list / _get / _set / _delete / _clear | Per-origin sessionStorage. | | browser_state_save / _state_load | Persist / restore the full Playwright storage state. | | browser_delete_data | Clear cookies + storage for the active origin. |

Network mocking + offline

| Tool | Purpose | |---|---| | browser_route | Register an abort / fulfill / continue mock for a URL pattern. | | browser_route_list / browser_unroute | List / remove registered routes. | | browser_network_state_set | Toggle context offline. |

Tracing

| Tool | Purpose | |---|---| | browser_tracing_start / browser_tracing_stop | Playwright trace recording (saves a .zip). |

Lifecycle

| Tool | Purpose | |---|---| | browser_close | Explicit teardown (next call auto-reopens). |

import { BrowserSession, createBrowserTools } from "@postqode/browser"
import { createCodingAgent } from "@postqode/coding-agent"

const session = new BrowserSession({ headless: true })
try {
	const agent = createCodingAgent({
		api,
		extraTools: createBrowserTools({ session }),
	})
	await agent.run(
		"Open example.com/login, type 'admin' into #user, click #submit, then screenshot the dashboard.",
	)
} finally {
	await session.close()
}

BrowserSession config:

| Field | Default | Purpose | |---|---|---| | headless | true | Launch headless. | | defaultTimeoutMs | 30000 | Per-operation timeout. | | viewport | 1280×800 | Initial viewport. | | userAgent | — | UA override. | | launchArgs | — | Extra chromium args. |

Aborting the agent's ctx.signal auto-closes the session.

Peer dep

playwright-core >= 1.58.0. Install in the consumer's project. Inside this monorepo the root already depends on it for the extension's existing browser mode, so no separate install is needed.

Design note

The VS Code-side browser code (src/services/browser/BrowserSession.ts, UrlContentFetcher.ts, BrowserToolHandler.ts) stays in the extension — it's entangled with Controller, @shared/ExtensionMessage, and the legacy IFullyManagedTool interface. That is a different product surface (the "Browser Agent" mode's UI); the package here is the portable SDK path.

Sibling packages

• @postqode/ai — provider registry.
• @postqode/agent — Tool contract this package implements.
• @postqode/coding-agent — merge via extraTools.