maestro-browser-bridge 1.18.0__tar.gz

maestro_browser_bridge-1.18.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: maestro-browser-bridge
+Version: 1.18.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

maestro_browser_bridge-1.18.0/README.md

@@ -0,0 +1,82 @@
+# 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

maestro_browser_bridge-1.18.0/maestro_browser_bridge/__init__.py

@@ -0,0 +1,12 @@
+"""Maestro Browser Bridge — local Playwright-driven Chromium for the
+Remote AI Maestro platform.
+
+The bridge runs on the user's *local* laptop (not on a registered Maestro
+"machine") and maintains an outbound WebSocket to the relay so AI agents
+running inside remote sandboxes can drive a real browser the user can see
+and intervene in.
+
+See ``_reference/11_BROWSER_CONTROL.md`` for the design spec.
+"""
+
+__version__ = "0.1.0"

maestro_browser_bridge-1.18.0/maestro_browser_bridge/cli.py

@@ -0,0 +1,269 @@
+"""Click CLI for the ``maestro-browser-bridge`` package.
+
+Subcommands mirror the shape of ``remotedev-agent``'s CLI so the install
+experience is familiar:
+
+- ``configure`` — write config to ``~/.maestro/bridge-config.json``.
+- ``start`` — load config and run the daemon (``--detach`` stubbed).
+- ``stop`` — placeholder.
+- ``status`` — print version + config path.
+- ``install-service`` — placeholder (launchd/systemd installer lands in BC.1.4).
+- ``--version`` — read from package metadata.
+
+Only the bits required by the acceptance criteria are wired today; the
+``daemon.py`` skeleton already documents the rest as TODOs.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+
+import click
+
+from .config import CONFIG_FILE, DEFAULT_LOCAL_PORT, BridgeConfig
+from .logging import configure_logging
+
+
+def _package_version() -> str:
+    """Resolve the installed package version, falling back to ``__init__.__version__``.
+
+    Mirrors the pattern in ``agent/remotedev_agent/cli.py`` so source-checkout
+    runs (without dist-info) still produce something useful.
+    """
+    try:
+        return _pkg_version("maestro-browser-bridge")
+    except PackageNotFoundError:
+        from . import __version__
+        return __version__
+
+
+@click.group()
+@click.version_option(version=_package_version(), prog_name="maestro-browser-bridge")
+def cli() -> None:
+    """Maestro Browser Bridge — local Playwright Chromium controller."""
+    # Configure structlog once per CLI invocation. Cheap (idempotent), and
+    # ensures even short-lived commands like ``status`` emit JSON in prod.
+    configure_logging()
+
+
+# ---------------------------------------------------------------------------
+# configure
+# ---------------------------------------------------------------------------
+
+
+@cli.command()
+@click.option(
+    "--relay-url",
+    required=True,
+    help="WebSocket URL of the Maestro relay (e.g. wss://relay.thesavvydeveloper.com).",
+)
+@click.option(
+    "--user-id",
+    required=True,
+    help="Maestro user UUID — determines relay routing (user_id → bridge).",
+)
+@click.option(
+    "--user-token",
+    required=True,
+    help="Per-user bridge token issued by the backend.",
+)
+@click.option(
+    "--port",
+    type=int,
+    default=DEFAULT_LOCAL_PORT,
+    show_default=True,
+    help="Local loopback port for the dev WS server.",
+)
+def configure(relay_url: str, user_id: str, user_token: str, port: int) -> None:
+    """Persist bridge configuration to ``~/.maestro/bridge-config.json``.
+
+    The file is written 0600 inside a 0700 directory — equivalent posture
+    to the agent's config, since the bridge token is approximately as
+    sensitive as a Maestro JWT.
+    """
+    config = BridgeConfig(
+        relay_url=relay_url,
+        user_id=user_id,
+        user_token=user_token,
+        port=port,
+    )
+    config.save()
+    click.echo(f"Config saved to {CONFIG_FILE}.")
+    click.echo("Start the bridge with: maestro-browser-bridge start")
+
+
+# ---------------------------------------------------------------------------
+# start
+# ---------------------------------------------------------------------------
+
+
+@cli.command()
+@click.option(
+    "--detach",
+    "-d",
+    is_flag=True,
+    help="Run in the background (not yet implemented — exits non-zero).",
+)
+def start(detach: bool) -> None:
+    """Launch the bridge daemon in the foreground.
+
+    ``--detach`` is wired so the flag is visible in ``--help`` but the
+    background-launch path (PID file, log rotation, daemonization) lands
+    in a later milestone — see ``agent/remotedev_agent/process_manager.py``
+    for the pattern we'll mirror.
+    """
+    if detach:
+        click.echo("detach not yet implemented", err=True)
+        raise SystemExit(1)
+
+    try:
+        config = BridgeConfig.load()
+    except FileNotFoundError as e:
+        click.echo(str(e), err=True)
+        raise SystemExit(1)
+
+    # Import inside the command so test collection (which doesn't run
+    # ``start``) doesn't pay the cost of pulling in websockets / playwright
+    # just to introspect ``--help``.
+    from .daemon import BridgeDaemon
+
+    click.echo(f"Starting bridge for user {config.user_id}...")
+    daemon = BridgeDaemon(config)
+    try:
+        asyncio.run(daemon.run())
+    except KeyboardInterrupt:
+        # Ctrl-C is a normal exit path during dev; don't print a stack
+        # trace at the user.
+        click.echo("Bridge stopped.")
+
+
+# ---------------------------------------------------------------------------
+# stop
+# ---------------------------------------------------------------------------
+
+
+@cli.command("stop")
+def cmd_stop() -> None:
+    """Stop a detached bridge daemon (placeholder).
+
+    Implementation lands alongside ``--detach`` in BC.1.4 — same
+    process-manager surface as the agent.
+    """
+    click.echo("stop not yet implemented — run the bridge in the foreground for now.")
+
+
+# ---------------------------------------------------------------------------
+# status
+# ---------------------------------------------------------------------------
+
+
+@cli.command("status")
+def cmd_status() -> None:
+    """Print version + config path. Loads the saved config when available."""
+    click.echo(f"maestro-browser-bridge {_package_version()}")
+    click.echo(f"Config file: {CONFIG_FILE}")
+    try:
+        config = BridgeConfig.load()
+    except FileNotFoundError:
+        click.echo("Config: NOT CONFIGURED (run 'maestro-browser-bridge configure ...').")
+        return
+    click.echo(f"Relay URL:   {config.relay_url}")
+    click.echo(f"User ID:     {config.user_id}")
+    click.echo(f"Local port:  {config.port}")
+    # NB — never print user_token; it's roughly as sensitive as a session JWT.
+
+
+# ---------------------------------------------------------------------------
+# install-service
+# ---------------------------------------------------------------------------
+
+
+@cli.command("install-service")
+def install_service() -> None:
+    """Install as a background service (placeholder).
+
+    Plan: mirror ``agent/remotedev_agent/service/`` — launchd on macOS,
+    systemd on Linux. Tracked in BC.1.4.
+    """
+    click.echo("install-service not yet implemented — see BC.1.4 in implementation_plan.md.")
+
+
+# ---------------------------------------------------------------------------
+# Kill switch — pause / resume (BC.6.1)
+# ---------------------------------------------------------------------------
+
+
+def _send_bridge_control(action: str) -> dict:
+    """Send a BRIDGE_CONTROL command to the running bridge via 127.0.0.1.
+
+    Synchronous — uses raw asyncio.run + websockets.connect so the CLI
+    doesn't need to manage an event loop itself. Returns the parsed
+    reply dict, raises ``ClickException`` on connect / I/O failure.
+    """
+    import asyncio
+    import json as _json
+
+    try:
+        config = BridgeConfig.load()
+    except FileNotFoundError as e:
+        raise click.ClickException(str(e))
+
+    async def _go() -> dict:
+        # Import lazily so ``--help`` / ``status`` don't pay the websockets cost.
+        import websockets
+
+        url = f"ws://127.0.0.1:{config.port}"
+        async with websockets.connect(url, open_timeout=2.0) as ws:
+            await ws.send(_json.dumps({"type": "BRIDGE_CONTROL", "action": action}))
+            reply_raw = await ws.recv()
+            return _json.loads(reply_raw if isinstance(reply_raw, str) else reply_raw.decode("utf-8"))
+
+    try:
+        return asyncio.run(_go())
+    except (ConnectionRefusedError, OSError) as e:
+        raise click.ClickException(
+            f"Could not reach bridge on 127.0.0.1:{config.port} ({e}). "
+            "Is 'maestro-browser-bridge start' running?"
+        )
+    except Exception as e:  # noqa: BLE001
+        raise click.ClickException(f"Bridge control failed: {e}")
+
+
+@cli.command("pause")
+def cmd_pause() -> None:
+    """Pause the bridge — every BROWSER_COMMAND will fail until ``resume``.
+
+    Use this as a kill switch if Claude is doing something you don't
+    want it to. State is in-memory only, so a daemon restart implicitly
+    resumes — that's intentional, so the recovery path is just
+    ``maestro-browser-bridge start``.
+    """
+    reply = _send_bridge_control("pause")
+    if not reply.get("ok"):
+        raise click.ClickException(reply.get("error") or "Unknown error")
+    click.echo("Bridge paused. Resume with 'maestro-browser-bridge resume'.")
+
+
+@cli.command("resume")
+def cmd_resume() -> None:
+    """Resume the bridge after a ``pause``."""
+    reply = _send_bridge_control("resume")
+    if not reply.get("ok"):
+        raise click.ClickException(reply.get("error") or "Unknown error")
+    click.echo("Bridge resumed.")
+
+
+@cli.command("bridge-status")
+def cmd_bridge_status() -> None:
+    """Print the running bridge's runtime state (paused / allowlist / rate)."""
+    reply = _send_bridge_control("status")
+    if not reply.get("ok"):
+        raise click.ClickException(reply.get("error") or "Unknown error")
+    click.echo(f"paused:             {reply.get('paused')}")
+    click.echo(f"allowlist hosts:    {reply.get('allowlist_size')}")
+    click.echo(f"rate limit / min:   {reply.get('rate_limit_per_min')}")
+
+
+if __name__ == "__main__":
+    cli()

maestro_browser_bridge-1.18.0/maestro_browser_bridge/config.py

@@ -0,0 +1,83 @@
+"""Bridge configuration — persisted as JSON in the user's home dir.
+
+Mirrors ``agent/remotedev_agent/config.py`` so the file-on-disk semantics
+(0600 mode, parent dir 0700) are uniform across both daemons. We store the
+config in ``~/.maestro/`` rather than ``~/.remotedev/`` because the bridge
+is a *user-scoped* service (one per laptop, not per machine) while the agent
+is *machine-scoped*. Sharing a dir would conflate two different identities.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+
+# ``~/.maestro`` is the per-user config root for the bridge. The agent uses
+# ``~/.remotedev`` instead — intentionally a different namespace so that an
+# uninstall of one doesn't blow away the other's state.
+CONFIG_DIR = Path.home() / ".maestro"
+CONFIG_FILE = CONFIG_DIR / "bridge-config.json"
+
+# Default port for the local WS server. ``127.0.0.1:7654`` is mentioned in
+# the spec; bound to loopback only — never exposed on a public interface
+# because the bridge can issue privileged Playwright commands.
+DEFAULT_LOCAL_PORT = 7654
+
+
+@dataclass
+class BridgeConfig:
+    """Configuration for the local browser bridge.
+
+    Attributes:
+        relay_url: WebSocket URL of the Maestro relay (e.g.
+            ``wss://relay.thesavvydeveloper.com``). The bridge will dial
+            ``<relay_url>/ws/browser-bridge/<user_id>`` on start.
+        user_id: UUID of the Maestro user this bridge belongs to. Determines
+            relay routing — one bridge per user (vs. agents which are
+            per-machine).
+        user_token: Bridge token issued by the backend (single-use issuance,
+            see ``POST /browser-bridges`` in the BC.2 plan). Used both as the
+            ``X-Bridge-Token`` header on connect and as the HMAC signing key
+            for every WS message.
+        port: Local loopback port for the in-process WS server. Defaults to
+            7654. Bound to ``127.0.0.1`` — never a public interface.
+        allowlist_extra: User-added hosts the bridge allows for navigate.
+            Merged with the default allowlist in ``security.py``.
+        rate_limit_per_min: Per-minute BROWSER_COMMAND budget. Defaults to
+            60 — enough for an interactive user, low enough to bound a
+            runaway script.
+    """
+
+    relay_url: str
+    user_id: str
+    user_token: str
+    port: int = DEFAULT_LOCAL_PORT
+    allowlist_extra: list[str] = field(default_factory=list)
+    rate_limit_per_min: int = 60
+
+    def save(self) -> None:
+        """Persist config to ``~/.maestro/bridge-config.json`` with 0600 mode.
+
+        The 0600 / 0700 combo prevents other users on a shared machine from
+        reading the bridge token, which is equivalent in blast radius to the
+        user's Maestro JWT.
+        """
+        CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+        os.chmod(CONFIG_DIR, 0o700)
+        CONFIG_FILE.write_text(json.dumps(asdict(self), indent=2))
+        os.chmod(CONFIG_FILE, 0o600)
+
+    @classmethod
+    def load(cls) -> "BridgeConfig":
+        """Read the saved config, or raise ``FileNotFoundError`` with a hint."""
+        if not CONFIG_FILE.exists():
+            raise FileNotFoundError(
+                f"Config not found at {CONFIG_FILE}. "
+                "Run 'maestro-browser-bridge configure --relay-url ... --user-id ... --user-token ...' first."
+            )
+        data = json.loads(CONFIG_FILE.read_text())
+        # Tolerate older configs that don't carry ``port`` by letting the
+        # dataclass default kick in.
+        return cls(**data)