pi-firefox-bidi: estensione pi per WebDriver BiDi + delegazione agy

2026-08-12 13:50:47 +02:00
commit 58187dca64
4 changed files with 411 additions and 0 deletions
@@ -0,0 +1,56 @@
+# pi-firefox-bidi
+
+Estensione per **pi agent**: controllo bidirezionale di **Firefox** tramite
+**WebDriver BiDi** (navigazione, screenshot allegati al contesto, eval JS,
+eventi asincroni) e delegazione asincrona ad **Antigravity CLI** (`agy`).
+
+## Architettura
+
+```
+pi agent (questa estensione) ──HTTP JSON──► Browser Bridge (bridge.py)
+                                             └──WebSocket BiDi──► Firefox (ws://127.0.0.1:9222)
+```
+
+- **Firefox ESR 128+**: Remote Agent BiDi nativo con `--remote-debugging-port 9222`
+  (nessun geckodriver). Endpoint unico `ws://127.0.0.1:9222/session`, loopback only.
+- **Browser Bridge** (`~/Dev/firefox-bidi/bridge/bridge.py`, Python + websockets):
+  possiede la sessione BiDi, espone HTTP JSON su `:8787` e un endpoint MCP minimale
+  (`/mcp`) per Antigravity CLI.
+- **Script di avvio** (`~/Dev/firefox-bidi/start-firefox-bidi.sh`):
+  - `start` → profilo dedicato `bidi-profile` (automazione pulita)
+  - `start-main` → **profilo principale** (login/cookie intatti; chiude l'istanza
+    attiva se serve, lock esclusivo)
+  - `status` / `stop` / `foreground`
+
+## Tool registrati
+
+| Tool | Funzione |
+|---|---|
+| `browser_start` / `browser_stop` / `browser_status` | ciclo di vita Firefox + bridge |
+| `browser_navigate(url)` | naviga e attende il carico |
+| `browser_screenshot(path?, fullPage?)` | PNG su disco, **allegato come immagine al contesto** |
+| `browser_eval(expression)` | `script.evaluate` |
+| `browser_send(method, params)` | comando BiDi grezzo |
+| `browser_events(action, module?)` | coda eventi asincroni (log, network, browsingContext) |
+| `agy_delegate(prompt, conversation?, model?)` | pi → agy headless (`--output-format stream-json`) |
+| `bridge_notify(event, payload)` | webhook locale `:8790` (agy/bridge → pi) |
+
+## Installazione
+
+```bash
+pi install git:git.enne2.net/enne2/pi-firefox-bidi
+# oppure in dev:  pi -e /home/enne2/Dev/pi-firefox-bidi
+```
+
+Requisiti runtime (sulla macchina, non nel package):
+- `firefox` (ESR 128+) e `python3` con `websockets` (`pip install --target <dir> websockets` se PEP 668 blocca `--user`)
+- Variabili opzionali: `FIREFOX_BIDI_BRIDGE` (default `http://127.0.0.1:8787`),
+  `FIREFOX_BIDI_SCRIPT`, `FIREFOX_BIDI_BRIDGE_PY` (default `~/Dev/firefox-bidi/...`)
+
+## Sicurezza
+
+Il Remote Agent di Firefox ascolta solo su `127.0.0.1`; con `start-main` il
+controllo BiDi espone anche i login reali del profilo: **non esporre mai la
+porta 9222 fuori dalla macchina**. Il bridge MCP richiede token
+(`FIREFOX_BIDI_TOKEN`). Evitare `--dangerously-skip-permissions` per
+l'orchestrazione generale.