# 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.