Metadata-Version: 2.4
Name: maestro-browser-bridge
Version: 1.24.0
Summary: Local browser bridge for Remote AI Maestro — runs a Playwright-managed Chromium and exposes BROWSER_* commands over WebSocket.
Author-email: Shaun <scwj1210@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/shaunchew/remote-ai-maestro
Project-URL: Repository, https://github.com/shaunchew/remote-ai-maestro
Project-URL: Documentation, https://github.com/shaunchew/remote-ai-maestro#readme
Project-URL: Issues, https://github.com/shaunchew/remote-ai-maestro/issues
Keywords: remote,ai,browser,playwright,chromium,automation,maestro
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: websockets>=13.0
Requires-Dist: click>=8.0
Requires-Dist: pydantic>=2
Requires-Dist: structlog>=24
Requires-Dist: playwright>=1.45
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.23; extra == "test"
Requires-Dist: pytest-mock>=3.12; extra == "test"

# maestro-browser-bridge

Local browser bridge for [Remote AI Maestro](https://remote-ai-maestro.thesavvydeveloper.com).

The bridge is the companion app you install on the same laptop where you keep
your real browser. It launches a Playwright-managed Chromium in an *isolated*
profile and exposes it over a WebSocket so an AI agent running inside a Maestro
sandbox can drive it — navigate, click, type, screenshot, read DOM, capture
console logs.

This is the **Phase 2** counterpart to the simpler Phase 1 `maestro browser
open <url>` command, which only pops URLs in your already-open browser via the
frontend's `window.open`. The bridge gives Claude (or any agent) real browser
control without ever touching your logged-in Chrome profile.

## Why a separate process

The AI agent runs on a remote machine (or an EC2 sandbox) but the browser to
be controlled lives on your local desktop. There is no other process that runs
on the user's actual laptop in a known-good location — the agent daemon runs
on whichever machine the sandbox is bound to, which may be EC2. So we ship a
dedicated bridge process that runs *on the user's laptop*, maintains an
outbound WebSocket to the relay, and translates `BROWSER_*` messages into
Playwright calls.

The bridge is per-user (one bridge per laptop) — distinct from the agent
daemon, which is per-machine. Relay routing maps `user_id → bridge`.

## Install

```bash
pip install maestro-browser-bridge

# Pre-download the Playwright Chromium binary (~200MB)
playwright install chromium

# Configure once
maestro-browser-bridge configure \
  --relay-url wss://relay.thesavvydeveloper.com \
  --user-id YOUR_USER_UUID \
  --user-token YOUR_BRIDGE_TOKEN

# Start
maestro-browser-bridge start
```

`--detach` is wired but not yet implemented; for now run the bridge in the
foreground (or wrap it in your own service manager — `launchd` / `systemd`
unit shipping is planned).

## Status

This package is the **scaffold** for the Phase 2 work tracked in
`_reference/11_BROWSER_CONTROL.md` and `implementation_plan.md`'s
"BC — Browser Control (Phase 2)" section. The protocol models, dispatch
shell, and CLI surface are in place; the actual Playwright handlers raise
`NotImplementedError` and will be wired in subsequent commits (BC.1.2 in the
plan).

## Development

```bash
# Editable install with test deps (from the repo root)
pip install -e ./bridge[test]

# Run tests
cd bridge && pytest

# Smoke check the CLI
maestro-browser-bridge --version
maestro-browser-bridge --help
```

## References

- Architecture & wire protocol: `_reference/11_BROWSER_CONTROL.md`
- Milestone plan: `_reference/12_BROWSER_PHASE2_PLAN.md`
- Pip package contract: `implementation_plan.md` § BC.1

## License

MIT
