tools.headless_browser module

Headless Firefox browser automation via Playwright.

Provides navigation, interaction, content extraction, waiting, screenshots, JavaScript execution, cookie management, network interception, session persistence, download handling, and console/dialog tools – all exposed through the v3 multi-tool format.

class tools.headless_browser.HeadlessBrowserManager[source]

Bases: object

Process-wide owner of the shared headless Firefox instance.

Lazily launches a single Playwright Firefox browser and multiplexes it across named contexts (each with its own page, console-log buffer, response-pattern list, intercepted responses, downloads, and dialog handler), so every browser tool and other consumers share one warm browser rather than spawning their own. It tracks usage/error counts and self-heals: too many errors or a disconnected browser trigger a restart. A module-level singleton _bm is the instance everything uses, and it is imported directly by tools/web_scraper.py and bot/voice/puter.py to reuse the same browser.

default_context_id: The default context id.

is_initialized: The is initialized.

last_used: The last used.

usage_count: The usage count.

error_count: The error count.

max_errors_before_restart: The max errors before restart.

idle_timeout: The idle timeout.

_lock: The lock.

default_viewport: The default viewport.

default_user_agent: The default user agent.

__init__()[source]

Set up manager bookkeeping without launching a browser.

Initializes all per-instance state (context/page maps, console-log, interception, download, dialog, and persistent-session registries, the async lock, default viewport/user-agent, and error/usage counters) to empty defaults. The actual Playwright/Firefox launch is deferred to initialize so the module can be imported cheaply.

Called once at import time to build the module-level _bm singleton.

async initialize()[source]

Launch the Firefox browser and create the default context.

Starts Playwright and launches a headless Firefox instance (with autoplay and desktop-notification preferences disabled), then creates the default context so a page is ready to use. Guarded by the async lock and idempotent: if an initialized, live browser already exists it returns immediately. On failure it cleans up and reports False.

Called by ensure_ready and restart in this module, and by browser_create_persistent_context when no Playwright instance exists yet.

Returns:: True if the browser is ready, False if Playwright is missing or the launch failed.
Return type:: bool

async ensure_ready()[source]

Guarantee a live browser, restarting or initializing as needed.

The health gate every page/context accessor calls first. It restarts the browser if the error count has crossed max_errors_before_restart, initializes it if not yet started, and restarts it if the existing browser has lost its connection; on success it refreshes last_used.

Called by ensure_proxied_context, get_page, get_context, create_new_context, browser_emulate_device, and browser_set_geolocation in this module.

Returns:: True when a connected browser is available, False otherwise.
Return type:: bool

async restart()[source]

Tear down and relaunch the browser from scratch.

Recovery path used after repeated errors or a lost connection: it runs cleanup to release all pages/contexts/browser/Playwright resources, then initialize to launch a fresh browser and default context.

Called by ensure_ready in this module and exposed through the browser_restart tool handler.

Returns:: True if the relaunch succeeded, False otherwise.
Return type:: bool

async cleanup()[source]

Close all pages, contexts, the browser, and Playwright.

Best-effort teardown that swallows per-resource errors while closing every open page and context, the browser, and the Playwright driver, clearing the page/context maps and marking the manager uninitialized. Holds the async lock so it cannot race a concurrent initialize.

Called by restart in this module; safe to invoke during shutdown.

async resolve_context_id(context_id, proxy)[source]

Choose the context to use, preferring a proxy-derived one.

Resolves the effective browser context for a request: when proxy is set it routes to the stable SOCKS-backed context from ensure_proxied_context (the proxy deliberately overrides any explicit context_id); otherwise it falls back to context_id or the default context. This is why setting a proxy is enough to isolate a session.

Called by _ctx_or_err in this module (which all proxy-aware browser tools route through).

Parameters:

context_id (Optional[str]) – Explicit context id, used only when no proxy is supplied.
proxy (Optional[str]) – Optional SOCKS proxy URL; when present, wins.

Returns:

The resolved context id to operate on.

Return type: