# firefox-bidi

Drive Firefox from Pi with raw W3C WebDriver BiDi frames: send a batch of `{id?, method, params}` frames, receive verbatim responses plus captured events.

Protocol knowledge, launch policy, and Firefox capability deltas live in the bundled skill: `skills/firefox-bidi/SKILL.md`.

## Usage

- `/firefox` — activate the `firefox_bidi` tool; Firefox launches lazily on first call with a fresh temp profile.
- `/firefox close` — shut the browser down and deactivate the tool.
- `firefox_bidi` batches ≤64 raw BiDi frames; whole-value `{{id.result.path}}` references preserve strings, numbers, booleans, null, arrays, and objects.
- Use `{{{{id.result.path}}}}` to send a literal placeholder; embedded references stringify primitives and reject arrays, objects, or null.
- Frame IDs cannot be reused during the lifetime of the browser, including after a timeout.
- `wait` accepts one event method or an array of ≤8 methods; each matching event is consumed once, including repeated methods.
- Waits listen only for events arriving during that call; `waitContext` optionally filters `params.context`.
- Running launch options cannot be changed silently, including `access`; use `/firefox close` before relaunching.
- UTF-8 request budget is 1 MiB per frame; inline responses are limited to 256 KiB each and reserve 896 KiB of the 1 MiB tool payload, with larger successful results spooled to disk, up to 32 MiB across browser relaunches in one Pi session.
- Spool writes finish before results return; failed writes return a frame error rather than a broken file reference.
- Event history keeps 200 entries; individual events above 8 KiB are summarized, including matched waits.
- Tool payload stays within 1 MiB UTF-8; oldest events are omitted first if needed, while oversized session metadata or waits are replaced by truncation markers.
- Spool files referenced by results remain on disk after `/firefox close`, then extension-owned spool directories are removed at session shutdown.

## Requirements

- Firefox on `PATH`, or `firefox-bidi.executablePath` / `FIREFOX_BIN` pointing at the binary.
- Missing binaries produce a startup warning and a fast, clear tool error.

## Settings

Settings live under `firefox-bidi` in user `~/.pi/agent/settings.json` or project `.pi/settings.json`.

| Key | Flag | Env | Type | Default |
| --- | --- | --- | --- | --- |
| `firefox-bidi.enable` | `--firefox` | `PI_FIREFOX` | boolean | `false` |
| `firefox-bidi.executablePath` | none | `FIREFOX_BIN` | non-empty string | `firefox` on `PATH` |
| `firefox-bidi.screencastDir` | none | none | non-empty string | Gecko default `~/Downloads` |

- `enable` activates `firefox_bidi` at session start without `/firefox`.
- `executablePath` overrides the Firefox binary used at launch.
- `screencastDir` sets the default `browsingContext.startScreencast` output directory; an explicit `destinationFolder` param wins.
- `pi --firefox` enables the tool for that run; being a boolean flag, it can only turn the tool on.
- Precedence per key: flag, env, trusted project, user, default.
- Project settings are read only when the project is trusted.
- Env booleans accept `true`, `false`, `1`, or `0`; settings booleans must be JSON booleans.
- An empty env value counts as set and is invalid.
- Invalid values never fall back to a lower source.
- Invalid `enable` leaves the tool inactive and warns at session start.
- Invalid `executablePath` warns at session start and fails the launching tool call.
- Invalid `screencastDir` fails the tool call carrying `browsingContext.startScreencast`.

## Debugging

Set `PI_FIREFOX_BIDI_DEBUG=1` for metadata-only diagnostics, or configure user-level `pi-ext.debug`.
See [extension debug contract](../DEBUG.md) for selection, files, and record guarantees.
Launch, teardown, command, and batch spans distinguish errors; batch records include successful, failed, skipped, and timed-out wait counts.

## Benchmarks

- `mise run //extensions/firefox-bidi:bench` — batch hot path, fake socket.
- `mise run //extensions/firefox-bidi:bench-e2e` — same batch shape against a real headless Firefox.
- Methodology: `__bench__/README.md`.