Luigit
repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by admin

extensions/firefox-bidi/README.md

Raw
Rendered preview

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