persistent-browser-bridge 0.1.0__py3-none-any.whl

pbb/browser/snapshot.py

@@ -0,0 +1,139 @@
+"""Compact, safe DOM snapshots for agents."""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass
+from typing import Any
+
+from playwright.async_api import Page
+
+SNAPSHOT_SCRIPT = r"""
+() => {
+  const visible = (el) => {
+    const s = getComputedStyle(el), r = el.getBoundingClientRect();
+    return s.visibility !== 'hidden' && s.display !== 'none' && s.opacity !== '0' && r.width > 0 && r.height > 0;
+  };
+  const exposed = (el) => {
+    if (!visible(el)) return false;
+    const r = el.getBoundingClientRect();
+    if (r.bottom <= 0 || r.right <= 0 || r.top >= innerHeight || r.left >= innerWidth) return false;
+    const x = Math.max(0, Math.min(innerWidth - 1, r.left + r.width / 2));
+    const y = Math.max(0, Math.min(innerHeight - 1, r.top + r.height / 2));
+    const top = document.elementFromPoint(x, y);
+    return !!top && (el.contains(top) || top.contains(el));
+  };
+  const clean = (v) => (v || '').replace(/\s+/g, ' ').trim();
+  const selector = (el) => {
+    if (el.id && CSS.escape) return '#' + CSS.escape(el.id);
+    const parts = [];
+    let node = el;
+    while (node && node.nodeType === Node.ELEMENT_NODE && node !== document.body) {
+      let part = node.tagName.toLowerCase();
+      const parent = node.parentElement;
+      if (parent) {
+        const siblings = [...parent.children].filter(x => x.tagName === node.tagName);
+        if (siblings.length > 1) part += `:nth-of-type(${siblings.indexOf(node) + 1})`;
+      }
+      parts.unshift(part); node = parent;
+      if (parts.length >= 6) break;
+    }
+    return parts.join(' > ');
+  };
+  const roleOf = (el) => {
+    if (el.getAttribute('role')) return el.getAttribute('role');
+    const tag = el.tagName.toLowerCase(), type = (el.getAttribute('type') || '').toLowerCase();
+    if (tag === 'a' && el.hasAttribute('href')) return 'link';
+    if (tag === 'button' || type === 'button' || type === 'submit' || type === 'reset') return 'button';
+    if (tag === 'textarea' || (tag === 'input' && !['button','submit','reset','checkbox','radio','file','hidden'].includes(type))) return 'textbox';
+    if (type === 'checkbox') return 'checkbox';
+    if (type === 'radio') return 'radio';
+    if (tag === 'select') return 'combobox';
+    return tag;
+  };
+  const nameOf = (el) => {
+    const aria = el.getAttribute('aria-label'); if (aria) return clean(aria);
+    const labelled = el.getAttribute('aria-labelledby');
+    if (labelled) return clean(labelled.split(/\s+/).map(id => document.getElementById(id)?.innerText || '').join(' '));
+    if (el.labels?.length) return clean([...el.labels].map(x => x.innerText).join(' '));
+    return clean(el.innerText || el.getAttribute('alt') || el.getAttribute('title') || el.getAttribute('name') || el.getAttribute('placeholder'));
+  };
+  const candidates = [...document.querySelectorAll('a[href],button,input:not([type=hidden]),textarea,select,[role],[contenteditable=true]')]
+    .filter(visible).slice(0, 500);
+  const elements = candidates.map((el, index) => {
+    const type = (el.getAttribute('type') || '').toLowerCase();
+    const item = {id:index + 1, role:roleOf(el), name:nameOf(el), selector:selector(el)};
+    for (const [key, value] of [['placeholder',el.getAttribute('placeholder')],['href',el.getAttribute('href')],['type',type]]) {
+      if (value) item[key] = clean(value).slice(0, 500);
+    }
+    if (type !== 'password' && ['checkbox','radio'].includes(type)) item.checked = !!el.checked;
+    if (el.disabled) item.disabled = true;
+    return item;
+  });
+  const headings = [...document.querySelectorAll('h1,h2,h3')].filter(visible).slice(0, 30)
+    .map(el => ({level:Number(el.tagName[1]), text:clean(el.innerText).slice(0, 500)})).filter(x => x.text);
+  const root = document.querySelector('main') || document.body;
+  const blocks = [...root.querySelectorAll('p,li,dt,dd,blockquote,pre,article,[role=article],[role=status],[role=alert]')]
+    .filter(exposed).map(el => clean(el.innerText)).filter(Boolean);
+  const text = clean(blocks.length ? blocks.join(' ') : root.innerText).slice(0, 20000);
+  return {elements, headings, text};
+}
+"""
+
+
+@dataclass
+class SnapshotStore:
+    snapshot_id: str = ""
+    page_url: str = ""
+    elements: dict[int, dict[str, Any]] | None = None
+
+    def update(self, url: str, elements: list[dict[str, Any]]) -> None:
+        digest = hashlib.sha256((url + repr(elements)).encode()).hexdigest()[:10]
+        self.snapshot_id = f"s_{digest}"
+        self.page_url = url
+        self.elements = {int(item["id"]): item for item in elements}
+
+    def get(self, element_id: int) -> dict[str, Any] | None:
+        return (self.elements or {}).get(element_id)
+
+
+async def capture_snapshot(page: Page, store: SnapshotStore, max_chars: int) -> dict[str, Any]:
+    raw = await page.evaluate(SNAPSHOT_SCRIPT)
+    elements = raw["elements"]
+    store.update(page.url, elements)
+    public_keys = {"id", "role", "name", "placeholder", "href", "type", "checked", "disabled"}
+    public_elements = [{k: v for k, v in item.items() if k in public_keys} for item in elements]
+    return {
+        "success": True,
+        "snapshot_id": store.snapshot_id,
+        "url": page.url,
+        "title": await page.title(),
+        "elements": public_elements,
+        "headings": raw["headings"],
+        "text": raw["text"][:max_chars],
+        "truncated": len(raw["text"]) > max_chars,
+    }
+
+
+def format_snapshot(data: dict[str, Any]) -> str:
+    lines = [
+        "PAGE",
+        f"Title: {data['title']}",
+        f"URL: {data['url']}",
+        f"Snapshot: {data['snapshot_id']}",
+        "",
+        "INTERACTIVE ELEMENTS",
+    ]
+    for item in data["elements"]:
+        lines.append(f"[{item['id']}] {item['role']}")
+        for key in ("name", "placeholder", "href", "type", "checked", "disabled"):
+            if key in item and item[key] not in {"", None}:
+                lines.append(f"{key}: {item[key]}")
+        lines.append("")
+    if data["headings"]:
+        lines.append("HEADINGS")
+        lines.extend(f"[H{x['level']}] {x['text']}" for x in data["headings"])
+        lines.append("")
+    if data["text"]:
+        lines.extend(("TEXT", data["text"]))
+    return "\n".join(lines).rstrip()

pbb/cli.py

@@ -0,0 +1,305 @@
+"""Agent-friendly command-line interface."""
+
+from __future__ import annotations
+
+import json
+import os
+import socket
+import subprocess
+import sys
+import time
+from pathlib import Path
+from typing import Any
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from pbb.browser.browser_detection import detect_browsers
+from pbb.browser.locks import ProfileLock, ProfileLockedError
+from pbb.browser.profile import create_profile, delete_profile, list_profiles, profile_path
+from pbb.browser.snapshot import format_snapshot
+from pbb.config import config_path, load_settings
+from pbb.daemon.client import DaemonClient, DaemonUnavailable
+from pbb.utils.paths import logs_dir, profiles_dir
+
+app = typer.Typer(no_args_is_help=True, help="Persistent, DOM-first browser control for AI agents.")
+profile_app = typer.Typer(help="Manage dedicated PBB browser profiles.")
+app.add_typer(profile_app, name="profile")
+console = Console(stderr=False)
+error_console = Console(stderr=True)
+
+
+def emit(data: dict[str, Any], as_json: bool, title: str | None = None) -> None:
+    if as_json:
+        # Keep agent output valid even when a Windows console uses a legacy code page.
+        sys.stdout.write(json.dumps(data, ensure_ascii=True, default=str) + "\n")
+        sys.stdout.flush()
+        if not data.get("success", False):
+            raise typer.Exit(1)
+        return
+    if not data.get("success", False):
+        error_console.print(f"[red]{data.get('error', 'error')}:[/red] {data.get('message', '')}")
+        if data.get("details"):
+            error_console.print_json(json.dumps(data["details"], default=str))
+        raise typer.Exit(1)
+    if title:
+        console.print(f"[bold]{title}[/bold]")
+    for key, value in data.items():
+        if key not in {"success", "details"} and value is not None:
+            console.print(f"{key.replace('_', ' ').title()}: {value}")
+
+
+def call(path: str, payload: dict[str, Any] | None, as_json: bool, title: str) -> dict[str, Any]:
+    try:
+        data = DaemonClient(load_settings()).post(path, payload)
+    except DaemonUnavailable as exc:
+        data = {"success": False, "error": "daemon_not_running", "message": str(exc), "details": {}}
+    emit(data, as_json, title)
+    return data
+
+
+def _port_available(host: str, port: int) -> bool:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        try:
+            sock.bind((host, port))
+            return True
+        except OSError:
+            return False
+
+
+@app.command()
+def start(
+    profile: str = typer.Option(None, help="Dedicated PBB profile name."),
+    browser: str = typer.Option(None, help="edge, chrome, chromium, or auto."),
+    json_output: bool = typer.Option(False, "--json", help="Emit machine-readable JSON."),
+) -> None:
+    """Start the local daemon and persistent browser."""
+    settings = load_settings()
+    selected_profile = profile or settings.default_profile
+    client = DaemonClient(settings)
+    try:
+        current = client.status()
+        current["message"] = "PBB already running"
+        emit(current, json_output, "PBB already running")
+        return
+    except DaemonUnavailable:
+        pass
+    if not _port_available(settings.daemon_host, settings.daemon_port):
+        emit(
+            {
+                "success": False,
+                "error": "port_in_use",
+                "message": f"Port {settings.daemon_port} is already in use",
+                "details": {},
+            },
+            json_output,
+        )
+    create_profile(selected_profile)
+    log_path = logs_dir() / "daemon.log"
+    log_handle = log_path.open("a", encoding="utf-8")
+    command = [sys.executable, "-m", "pbb.daemon.server", "--profile", selected_profile]
+    if browser:
+        command.extend(("--browser", browser))
+    creationflags = 0
+    if os.name == "nt":
+        creationflags = subprocess.CREATE_NEW_PROCESS_GROUP | subprocess.DETACHED_PROCESS
+    process = subprocess.Popen(
+        command,
+        stdin=subprocess.DEVNULL,
+        stdout=log_handle,
+        stderr=log_handle,
+        close_fds=True,
+        creationflags=creationflags,
+    )
+    log_handle.close()
+    deadline = time.monotonic() + 30
+    last_error = "daemon startup timed out"
+    while time.monotonic() < deadline:
+        time.sleep(0.25)
+        try:
+            data = client.status()
+            emit(data, json_output, "PBB started")
+            return
+        except DaemonUnavailable as exc:
+            last_error = str(exc)
+            if process.poll() is not None:
+                last_error = f"daemon exited with code {process.returncode}"
+                break
+    emit(
+        {
+            "success": False,
+            "error": "daemon_start_failed",
+            "message": last_error,
+            "details": {"log": str(log_path)},
+        },
+        json_output,
+    )
+
+
+@app.command()
+def status(json_output: bool = typer.Option(False, "--json")) -> None:
+    """Show daemon, browser, profile, and current page status."""
+    try:
+        data = DaemonClient(load_settings()).status()
+    except DaemonUnavailable as exc:
+        data = {"success": False, "error": "daemon_not_running", "message": str(exc), "details": {}}
+    emit(data, json_output, "PBB Status")
+
+
+@app.command("open")
+def open_url(url: str, json_output: bool = typer.Option(False, "--json")) -> None:
+    """Navigate the active page to URL."""
+    call("/navigate", {"url": url}, json_output, "Page opened")
+
+
+@app.command()
+def snapshot(json_output: bool = typer.Option(False, "--json")) -> None:
+    """Capture a compact, safe DOM snapshot."""
+    try:
+        data = DaemonClient(load_settings()).post("/snapshot")
+    except DaemonUnavailable as exc:
+        data = {"success": False, "error": "daemon_not_running", "message": str(exc), "details": {}}
+    if data.get("success") and not json_output:
+        console.print(format_snapshot(data))
+        return
+    emit(data, json_output)
+
+
+@app.command()
+def click(target: str, json_output: bool = typer.Option(False, "--json")) -> None:
+    """Click a snapshot reference, selector, or semantic target."""
+    call("/click", {"target": target}, json_output, "Click complete")
+
+
+@app.command()
+def fill(target: str, value: str, json_output: bool = typer.Option(False, "--json")) -> None:
+    """Fill an input without echoing its value in output."""
+    call("/fill", {"target": target, "value": value}, json_output, "Fill complete")
+
+
+@app.command()
+def text(target: str, json_output: bool = typer.Option(False, "--json")) -> None:
+    """Read visible text from a target."""
+    call("/text", {"target": target}, json_output, "Text")
+
+
+@app.command()
+def download(
+    target: str,
+    output: Path = typer.Option(None, help="Destination directory or file."),
+    json_output: bool = typer.Option(False, "--json"),
+) -> None:
+    """Click a target and save the resulting Playwright download."""
+    call(
+        "/download",
+        {"target": target, "output": str(output) if output else None},
+        json_output,
+        "Download complete",
+    )
+
+
+@app.command()
+def screenshot(
+    output: Path = typer.Argument(Path("pbb-screenshot.png")),
+    full_page: bool = typer.Option(False, "--full-page"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> None:
+    """Save a screenshot as a secondary inspection aid."""
+    call(
+        "/screenshot",
+        {"output": str(output), "full_page": full_page},
+        json_output,
+        "Screenshot saved",
+    )
+
+
+@app.command()
+def close(json_output: bool = typer.Option(False, "--json")) -> None:
+    """Close the browser and stop the daemon."""
+    call("/shutdown", {}, json_output, "PBB closed")
+
+
+@app.command()
+def shutdown(json_output: bool = typer.Option(False, "--json")) -> None:
+    """Alias for close."""
+    close(json_output)
+
+
+@app.command()
+def recover(json_output: bool = typer.Option(False, "--json")) -> None:
+    """Remove stale PBB-owned profile locks only."""
+    cleared: list[str] = []
+    for name in list_profiles():
+        lock = ProfileLock(profile_path(name), name)
+        if lock.clear_stale():
+            cleared.append(name)
+    emit({"success": True, "cleared_profiles": cleared}, json_output, "Recovery complete")
+
+
+@app.command()
+def doctor(json_output: bool = typer.Option(False, "--json")) -> None:
+    """Check Python, browsers, directories, and daemon port."""
+    settings = load_settings()
+    browsers = [item.as_dict() for item in detect_browsers()]
+    result = {
+        "success": True,
+        "python": sys.version.split()[0],
+        "playwright": "installed",
+        "browsers": browsers,
+        "profiles_directory": str(profiles_dir()),
+        "config": str(config_path()),
+        "daemon_port": settings.daemon_port,
+        "port_available": _port_available(settings.daemon_host, settings.daemon_port),
+    }
+    emit(result, json_output, "Persistent Browser Bridge Doctor")
+
+
+@profile_app.command("create")
+def profile_create(name: str, json_output: bool = typer.Option(False, "--json")) -> None:
+    path = create_profile(name)
+    emit({"success": True, "profile": name, "path": str(path)}, json_output, "Profile ready")
+
+
+@profile_app.command("list")
+def profile_list(json_output: bool = typer.Option(False, "--json")) -> None:
+    names = list_profiles()
+    if json_output:
+        emit({"success": True, "profiles": names}, True)
+        return
+    table = Table(title="PBB Profiles")
+    table.add_column("Name")
+    table.add_column("Path")
+    for name in names:
+        table.add_row(name, str(profile_path(name)))
+    console.print(table)
+
+
+@profile_app.command("path")
+def profile_show_path(name: str) -> None:
+    console.print(str(profile_path(name)))
+
+
+@profile_app.command("delete")
+def profile_delete(
+    name: str,
+    yes: bool = typer.Option(False, "--yes", "-y", help="Confirm deletion."),
+    json_output: bool = typer.Option(False, "--json"),
+) -> None:
+    if not yes and not typer.confirm(f"Delete PBB profile '{name}' and its browser data?"):
+        raise typer.Abort()
+    try:
+        lock = ProfileLock(profile_path(name), name)
+        if lock.path.exists() and not lock.is_stale():
+            raise ProfileLockedError(f"Profile '{name}' is currently in use")
+        delete_profile(name)
+        emit({"success": True, "deleted": name}, json_output, "Profile deleted")
+    except (FileNotFoundError, ProfileLockedError) as exc:
+        emit(
+            {"success": False, "error": "profile_locked", "message": str(exc), "details": {}},
+            json_output,
+        )
+
+
+if __name__ == "__main__":
+    app()

pbb/config.py

@@ -0,0 +1,66 @@
+"""Configuration loading with TOML and environment overrides."""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field, field_validator
+
+from pbb.constants import DEFAULT_HOST, DEFAULT_PORT
+from pbb.utils.paths import config_dir, default_download_dir, ensure_app_dirs
+
+
+class Settings(BaseModel):
+    browser: str = "auto"
+    default_profile: str = "default"
+    daemon_host: str = DEFAULT_HOST
+    daemon_port: int = Field(DEFAULT_PORT, ge=1024, le=65535)
+    download_dir: Path = Field(default_factory=default_download_dir)
+    timeout: int = Field(15_000, ge=1000, le=300_000)
+    headless: bool = False
+    snapshot_max_chars: int = Field(5000, ge=500, le=100_000)
+
+    @field_validator("daemon_host")
+    @classmethod
+    def localhost_only(cls, value: str) -> str:
+        if value not in {"127.0.0.1", "localhost", "::1"}:
+            raise ValueError("v0.1 only permits a loopback daemon host")
+        return value
+
+    @field_validator("browser")
+    @classmethod
+    def known_browser(cls, value: str) -> str:
+        normalized = value.lower()
+        if normalized not in {"edge", "chrome", "chromium", "auto"}:
+            raise ValueError("browser must be edge, chrome, chromium, or auto")
+        return normalized
+
+
+ENV_MAP = {
+    "PBB_BROWSER": ("browser", str),
+    "PBB_PROFILE": ("default_profile", str),
+    "PBB_PORT": ("daemon_port", int),
+    "PBB_DOWNLOAD_DIR": ("download_dir", Path),
+    "PBB_TIMEOUT": ("timeout", int),
+}
+
+
+def config_path() -> Path:
+    return config_dir() / "config.toml"
+
+
+def load_settings() -> Settings:
+    ensure_app_dirs()
+    values: dict[str, Any] = {}
+    path = config_path()
+    if path.exists():
+        with path.open("rb") as handle:
+            values.update(tomllib.load(handle))
+    for env_name, (field_name, converter) in ENV_MAP.items():
+        raw = os.getenv(env_name)
+        if raw is not None:
+            values[field_name] = converter(raw)
+    return Settings.model_validate(values)

pbb/constants.py

@@ -0,0 +1,7 @@
+"""Project-wide constants."""
+
+APP_NAME = "PersistentBrowserBridge"
+APP_AUTHOR = "PersistentBrowserBridge"
+DEFAULT_HOST = "127.0.0.1"
+DEFAULT_PORT = 8765
+__version__ = "0.1.0"

pbb/daemon/__init__.py

@@ -0,0 +1 @@
+"""Local-only browser daemon."""

pbb/daemon/app.py

@@ -0,0 +1,137 @@
+"""FastAPI application served only on loopback."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Any
+
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+from playwright.async_api import Error as PlaywrightError
+from pydantic import BaseModel
+
+from pbb.browser.locator import LocatorResolutionError
+from pbb.browser.manager import BrowserManager
+from pbb.config import Settings
+
+
+class NavigateRequest(BaseModel):
+    url: str
+
+
+class TargetRequest(BaseModel):
+    target: str
+
+
+class FillRequest(TargetRequest):
+    value: str
+
+
+class DownloadRequest(TargetRequest):
+    output: str | None = None
+
+
+class ScreenshotRequest(BaseModel):
+    output: str = "pbb-screenshot.png"
+    full_page: bool = False
+
+
+def error(code: str, message: str, details: dict[str, Any] | None = None) -> dict[str, Any]:
+    return {"success": False, "error": code, "message": message, "details": details or {}}
+
+
+def create_app(settings: Settings, profile: str, browser: str | None = None) -> FastAPI:
+    manager = BrowserManager(settings, profile, browser)
+
+    @asynccontextmanager
+    async def lifespan(_app: FastAPI):
+        await manager.start()
+        try:
+            yield
+        finally:
+            await manager.close()
+
+    app = FastAPI(
+        title="Persistent Browser Bridge",
+        version="0.1.0",
+        docs_url=None,
+        redoc_url=None,
+        lifespan=lifespan,
+    )
+    app.state.manager = manager
+    app.state.server = None
+
+    @app.exception_handler(LocatorResolutionError)
+    async def locator_error(_request: Request, exc: LocatorResolutionError) -> JSONResponse:
+        return JSONResponse(error(exc.code, str(exc), exc.details), status_code=400)
+
+    @app.exception_handler(PlaywrightError)
+    async def playwright_error(_request: Request, exc: PlaywrightError) -> JSONResponse:
+        message = str(exc)
+        lowered = message.lower()
+        code = "page_closed" if "closed" in lowered else "browser_disconnected"
+        return JSONResponse(error(code, message), status_code=409)
+
+    @app.exception_handler(Exception)
+    async def internal_error(_request: Request, exc: Exception) -> JSONResponse:
+        return JSONResponse(error("internal_error", str(exc)), status_code=500)
+
+    @app.get("/status")
+    async def status() -> dict[str, Any]:
+        result = await manager.status()
+        result.update({"daemon_running": True, "pid": os.getpid()})
+        return result
+
+    @app.post("/start")
+    async def start() -> dict[str, Any]:
+        await manager.start()
+        return await status()
+
+    @app.post("/navigate")
+    async def navigate(request: NavigateRequest) -> dict[str, Any]:
+        return await manager.navigate(request.url)
+
+    @app.post("/snapshot")
+    async def snapshot() -> dict[str, Any]:
+        return await manager.snapshot()
+
+    @app.post("/click")
+    async def click(request: TargetRequest) -> dict[str, Any]:
+        return await manager.click(request.target)
+
+    @app.post("/fill")
+    async def fill(request: FillRequest) -> dict[str, Any]:
+        return await manager.fill(request.target, request.value)
+
+    @app.post("/text")
+    async def text(request: TargetRequest) -> dict[str, Any]:
+        return await manager.text(request.target)
+
+    @app.post("/download")
+    async def download(request: DownloadRequest) -> dict[str, Any]:
+        output = Path(request.output) if request.output else None
+        return await manager.download(request.target, output)
+
+    @app.post("/screenshot")
+    async def screenshot(request: ScreenshotRequest) -> dict[str, Any]:
+        return await manager.screenshot(Path(request.output), request.full_page)
+
+    @app.post("/close")
+    async def close() -> dict[str, Any]:
+        await manager.close()
+        return {"success": True, "browser_running": False}
+
+    @app.post("/shutdown")
+    async def stop() -> dict[str, Any]:
+        async def request_exit() -> None:
+            await asyncio.sleep(0.1)
+            if app.state.server is not None:
+                app.state.server.should_exit = True
+
+        asyncio.create_task(request_exit())
+        return {"success": True, "message": "PBB daemon is shutting down"}
+
+    return app