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

pbb/daemon/client.py

@@ -0,0 +1,39 @@
+"""Synchronous local daemon client used by the CLI."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from pbb.config import Settings
+
+
+class DaemonUnavailable(RuntimeError):
+    pass
+
+
+class DaemonClient:
+    def __init__(self, settings: Settings) -> None:
+        self.base_url = f"http://{settings.daemon_host}:{settings.daemon_port}"
+        self.timeout = max(settings.timeout / 1000 + 5, 10)
+
+    def request(
+        self, method: str, path: str, payload: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        try:
+            with httpx.Client(timeout=self.timeout, trust_env=False) as client:
+                response = client.request(method, f"{self.base_url}{path}", json=payload)
+        except httpx.RequestError as exc:
+            raise DaemonUnavailable("PBB daemon is not running. Run `pbb start` first.") from exc
+        try:
+            data = response.json()
+        except ValueError as exc:
+            raise DaemonUnavailable("PBB daemon returned an invalid response") from exc
+        return data
+
+    def status(self) -> dict[str, Any]:
+        return self.request("GET", "/status")
+
+    def post(self, path: str, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.request("POST", path, payload or {})

pbb/daemon/server.py

@@ -0,0 +1,36 @@
+"""Daemon process entry point."""
+
+from __future__ import annotations
+
+import argparse
+
+import uvicorn
+
+from pbb.config import load_settings
+from pbb.daemon.app import create_app
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--profile", required=True)
+    parser.add_argument("--browser")
+    parser.add_argument("--port", type=int)
+    args = parser.parse_args()
+    settings = load_settings()
+    if args.port:
+        settings.daemon_port = args.port
+    app = create_app(settings, args.profile, args.browser)
+    config = uvicorn.Config(
+        app,
+        host=settings.daemon_host,
+        port=settings.daemon_port,
+        log_level="info",
+        access_log=False,
+    )
+    server = uvicorn.Server(config)
+    app.state.server = server
+    server.run()
+
+
+if __name__ == "__main__":
+    main()

pbb/utils/__init__.py

@@ -0,0 +1 @@
+"""Internal utility helpers."""

pbb/utils/paths.py

@@ -0,0 +1,40 @@
+"""Platform-specific paths owned by PBB."""
+
+from pathlib import Path
+
+from platformdirs import PlatformDirs
+
+from pbb.constants import APP_NAME
+
+
+def dirs() -> PlatformDirs:
+    return PlatformDirs(APP_NAME, appauthor=False, roaming=False)
+
+
+def data_dir() -> Path:
+    return Path(dirs().user_data_path)
+
+
+def config_dir() -> Path:
+    return Path(dirs().user_config_path)
+
+
+def profiles_dir() -> Path:
+    return data_dir() / "profiles"
+
+
+def logs_dir() -> Path:
+    return data_dir() / "logs"
+
+
+def runtime_dir() -> Path:
+    return data_dir() / "runtime"
+
+
+def default_download_dir() -> Path:
+    return Path.home() / "Downloads" / "PBB"
+
+
+def ensure_app_dirs() -> None:
+    for path in (data_dir(), config_dir(), profiles_dir(), logs_dir(), runtime_dir()):
+        path.mkdir(parents=True, exist_ok=True)

persistent_browser_bridge-0.1.0.dist-info/METADATA

@@ -0,0 +1,210 @@
+Metadata-Version: 2.5
+Name: persistent-browser-bridge
+Version: 0.1.0
+Summary: Give AI coding agents a real persistent browser.
+Author: Persistent Browser Bridge contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,browser-automation,persistent-profile,playwright
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Requires-Dist: fastapi<1,>=0.115
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: platformdirs<5,>=4.2
+Requires-Dist: playwright<2,>=1.48
+Requires-Dist: psutil<8,>=6
+Requires-Dist: pydantic<3,>=2.9
+Requires-Dist: rich<15,>=13.9
+Requires-Dist: typer<1,>=0.12
+Requires-Dist: uvicorn<1,>=0.30
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == 'dev'
+Requires-Dist: mypy<2,>=1.13; extra == 'dev'
+Requires-Dist: pytest-asyncio<1,>=0.24; extra == 'dev'
+Requires-Dist: pytest<9,>=8.3; extra == 'dev'
+Requires-Dist: ruff<1,>=0.8; extra == 'dev'
+Requires-Dist: types-psutil<8,>=6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Persistent Browser Bridge
+
+> Give AI coding agents a real persistent browser.
+
+Persistent Browser Bridge (PBB) is a local browser-control layer built on Playwright. Instead of forcing AI agents to repeatedly inspect screenshots, PBB exposes lightweight DOM-first browser actions while preserving real browser sessions across runs.
+
+**Persistent. DOM-first. Local-first. Agent-friendly. Low-context.**
+
+PBB is an early v0.1 release for normal, authorized browser automation. It is not a CAPTCHA bypass, anti-detection toolkit, credential collector, or scraping-evasion framework.
+
+## Why PBB
+
+Visual automation remains valuable when a page cannot be understood through the DOM. For routine forms, links, text, and downloads, a compact DOM snapshot is faster to inspect and less dependent on screen coordinates. A dedicated persistent browser profile also keeps cookies, local storage, IndexedDB, and login state between runs without touching your everyday browser profile.
+
+| Feature | Computer Use | PBB |
+|---|---|---|
+| Interaction | Visual | DOM-first |
+| Browser state | Depends on environment | Dedicated persistent profile |
+| Login reuse | Environment dependent | Reuses its PBB profile |
+| Element targeting | Vision and coordinates | DOM locators and snapshot references |
+| Downloads | UI dependent | Playwright download events |
+| Agent context | Visual-heavy | Compact DOM snapshot |
+| Recovery | Agent dependent | Basic page and stale-lock recovery |
+| Local-first | Depends | Yes |
+
+PBB complements visual browser automation rather than replacing every use case.
+
+## Architecture
+
+```text
+AI agent -> pbb CLI -> localhost daemon -> Playwright
+         -> real Edge/Chrome -> dedicated persistent profile -> website
+```
+
+The daemon binds to `127.0.0.1` by default and owns the Playwright process, active page, snapshot references, and download handling. CLI commands talk only to that local daemon, so a browser is not restarted for each action.
+
+## Installation
+
+PBB requires Python 3.11 or newer. Edge is preferred, Chrome is supported, and Playwright Chromium is the fallback.
+
+```console
+cd persistent-browser-bridge
+python -m pip install -e .
+```
+
+If no system browser is available, install Playwright Chromium with `python -m playwright install chromium`. The package has not been published to PyPI yet; do not use `pip install persistent-browser-bridge` until a release announcement says otherwise.
+
+## Quick start
+
+```console
+pbb doctor
+pbb profile create default
+pbb start --profile default
+pbb open https://example.com
+pbb snapshot
+pbb text h1
+pbb close
+```
+
+The first start opens a visible browser. Sign in manually when needed. PBB never asks for or stores account passwords; CAPTCHA, 2FA, device confirmation, and reauthentication remain user actions.
+
+## Profiles
+
+PBB profiles are separate from daily Edge and Chrome profiles:
+
+```console
+pbb profile create work
+pbb profile list
+pbb profile path work
+pbb profile delete work
+```
+
+Deletion requires confirmation (or explicit `--yes`) and only removes directories carrying PBB's own profile marker. PBB never deletes native Edge or Chrome lock files.
+
+## CLI
+
+| Command | Purpose |
+|---|---|
+| `pbb start --profile NAME` | Start the daemon and persistent browser |
+| `pbb status` | Show process, profile, browser, page, and tabs |
+| `pbb open URL` | Navigate and wait for `domcontentloaded` |
+| `pbb snapshot` | Return a compact DOM snapshot |
+| `pbb click TARGET` | Click a reference, selector, or semantic target |
+| `pbb fill TARGET VALUE` | Fill a field; password values are never returned |
+| `pbb text TARGET` | Read visible element text |
+| `pbb download TARGET` | Wait for a real download event and save the file |
+| `pbb screenshot [PATH]` | Capture a supporting screenshot |
+| `pbb recover` | Clear stale PBB-owned locks |
+| `pbb close` | Close browser and daemon |
+
+Every action supports `--json`. Failures use a stable shape:
+
+```json
+{"success": false, "error": "element_not_found", "message": "...", "details": {}}
+```
+
+## Snapshots and targets
+
+`pbb snapshot --json` returns the page title, URL, headings, bounded visible text, and interactive elements. It excludes scripts, styles, hidden elements, cookies, password values, and hidden tokens. Internal selectors remain inside the daemon.
+
+```json
+{
+  "success": true,
+  "snapshot_id": "s_123abc",
+  "elements": [
+    {"id": 1, "role": "textbox", "name": "Email", "placeholder": "you@example.com"},
+    {"id": 2, "role": "button", "name": "Sign in"}
+  ]
+}
+```
+
+Use `@1`, `@2`, or the explicit `s_123abc:@2` form. PBB rejects stale references after navigation or when element identity changes. It resolves targets conservatively: snapshot reference, unique selector, exact button/link role, label, placeholder, then exact text. Multiple matches return `ambiguous_target`; PBB never chooses one at random.
+
+PowerShell reserves `@` syntax, so quote references there: `pbb click '@2'`. Bash and similar shells accept `pbb click @2`.
+
+## Downloads
+
+```console
+pbb download "Download PDF"
+pbb download @5 --output ./downloads
+```
+
+PBB waits for Playwright's download event and uses `save_as`. A click that does not emit a download returns `download_not_triggered` rather than reporting false success. The default destination is `~/Downloads/PBB`.
+
+## Configuration
+
+PBB reads `config.toml` from the platform's application config directory. Supported keys are `browser`, `default_profile`, `daemon_host`, `daemon_port`, `download_dir`, `timeout`, `headless`, and `snapshot_max_chars`. v0.1 rejects non-loopback daemon hosts.
+
+Environment overrides: `PBB_BROWSER`, `PBB_PROFILE`, `PBB_PORT`, `PBB_DOWNLOAD_DIR`, and `PBB_TIMEOUT`.
+
+## Privacy and security
+
+PBB runs locally and includes no telemetry. Browser profiles remain on the device. PBB does not upload browsing history, cookies, credentials, or profiles; does not export cookies; and does not access a password manager. Treat the profile directory as sensitive local data. See [SECURITY.md](SECURITY.md).
+
+## Agent integration
+
+Recommended flow: check status, start if needed, inspect `snapshot --json`, use DOM actions, and only fall back to screenshots or Computer Use when the DOM is insufficient. Full guidance is in [docs/agent-integration.md](docs/agent-integration.md).
+
+### Codex integration
+
+Copy this prompt into a project instruction:
+
+```text
+Always prefer Persistent Browser Bridge for browser automation when it is available.
+
+Browser strategy:
+1. Run `pbb status` and start PBB if needed.
+2. Use `pbb snapshot --json` to inspect the current page.
+3. Prefer `pbb click`, `pbb fill`, `pbb text`, and `pbb download`.
+4. Reuse the existing persistent browser profile. Do not launch another browser unless necessary.
+5. Use screenshots or Computer Use only when DOM-based interaction fails.
+6. Never request or store account passwords.
+7. Let the user manually complete authentication, CAPTCHA, 2FA, or device verification.
+8. Continue using the same profile after authentication.
+```
+
+## Python SDK and MCP
+
+A stable Python SDK and MCP server are planned for v0.2. The daemon's local HTTP API is an implementation detail in v0.1 and may change. No SDK or MCP support is claimed in this release.
+
+## Limitations
+
+- Snapshot references are daemon-memory state and do not survive daemon restarts.
+- Shadow DOM, canvas-only controls, cross-origin frames, and highly virtualized UIs may need direct selectors or visual automation.
+- Recovery covers closed pages and stale PBB locks; full crash replay is planned.
+- One daemon controls one profile at a time in v0.1.
+- Benchmarks are not published. PBB is designed to reduce repeated visual context usage, but no token or cost savings are claimed.
+
+## Benchmark framework
+
+The [benchmarks](benchmarks/README.md) directory defines a future comparison schema. Results are coming soon; no fabricated figures are included.
+
+## Roadmap, contributing, and license
+
+See [ROADMAP.md](ROADMAP.md), [CONTRIBUTING.md](CONTRIBUTING.md), and the [MIT License](LICENSE).
+

persistent_browser_bridge-0.1.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+pbb/__init__.py,sha256=Bflqoe-oi00CP2bz5p7ySauUyAvEc_GrrjYT1fYeDB8,114
+pbb/cli.py,sha256=DuUeAZaZADRbdTMZ7skZVhi2w2Cw0JfD7Wc2xzuKqak,10574
+pbb/config.py,sha256=3HTHCU8S41ZCOrZ10HiTI4-5QE1RlVTUYMLHtn-vV84,2056
+pbb/constants.py,sha256=GwuZNE00VnrIlRP4U6k_zgHkJusq6Y71ztzoRQ_yNPA,176
+pbb/browser/__init__.py,sha256=-W8FIMfXuVVOa2pgQYCo4JcXbbjBVRqOsnXgbK13fWM,37
+pbb/browser/browser_detection.py,sha256=BD_gEKJ0M0WS3FwoKNoEznSnTLqde0H1kdHXxDv4RG4,3830
+pbb/browser/locator.py,sha256=PqEu-jI8bF3v2xP1qMMQ5LrDEoBtscZNZmQAyRrgW3k,4030
+pbb/browser/locks.py,sha256=77N6uOKRQfRruzCl67vxk-IRFC_ptYDw4BtOW5GrBok,2312
+pbb/browser/manager.py,sha256=aZGcJtgnkVaQ4xvSZjSWPTxg7FXXKVD5sCIdvalhDhQ,8516
+pbb/browser/profile.py,sha256=uao-WiL0ebKB35S6Zlzjw-mq8M9CtmycTgWgq7LUlfA,1458
+pbb/browser/snapshot.py,sha256=xSSanx2dZxWdyMtQDCorwl7HWxN55Bu8K1rYzZV4plk,6189
+pbb/daemon/__init__.py,sha256=NWyGBC2FHXJ2lVldGx-_sp-KxGyNBezNOxfVsZu49CA,33
+pbb/daemon/app.py,sha256=R5YlzQjTGPH7uZfjy9NjMx5whsmdMEZGsNES-Z7fUhw,4293
+pbb/daemon/client.py,sha256=GSZ3LDYEj3Oi1J0iwYMuY9MPt0bXBXVDsdBlwWyedqA,1291
+pbb/daemon/server.py,sha256=dsP_PGBCe5v5OM1BIgEhbVRXZYlvS7WHr0A5YI05ySY,846
+pbb/utils/__init__.py,sha256=xtcYPLWPmpkNwPMZryCDOULwlGW3L01_LrnjEjGWh5g,32
+pbb/utils/paths.py,sha256=qE1cR7Mr0oRhv4OxeQp2JkvxjHpOX9clifnkjcuwIQo,811
+persistent_browser_bridge-0.1.0.dist-info/METADATA,sha256=Klq32BoE6IZETii69TYa1UzVw4FkU9J3DYBgPg8BG_o,9302
+persistent_browser_bridge-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+persistent_browser_bridge-0.1.0.dist-info/entry_points.txt,sha256=rC_3-Z9kUvFh-vpm9lhXtwrxT4YXOHo-jwU0DgO6xiQ,36
+persistent_browser_bridge-0.1.0.dist-info/licenses/LICENSE,sha256=qwT2ZpRssWo6Hz_4g2cCs956dJM4YzgHbYjQuPaXLc0,1096
+persistent_browser_bridge-0.1.0.dist-info/RECORD,,

persistent_browser_bridge-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

persistent_browser_bridge-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pbb = pbb.cli:app

persistent_browser_bridge-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Persistent Browser Bridge contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+