Luigit
repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by admin

extensions/firefox-bidi/README.md

Raw
Rendered preview
firefox-bidi

firefox-bidi

Use Firefox from Pi when you want Pi to drive a real browser through WebDriver BiDi. It is useful for opening pages, exercising browser behavior, inspecting results, or recording a screencast with Firefox-specific tooling.

Installation

First use

Enable codemode or tool_search so Pi can discover Firefox, then ask Pi to perform browser task. Firefox starts only when Pi first uses it and gets a fresh temporary profile.

Use tool_search to find firefox_bidi, then open http://localhost:3000 and check whether the login form is usable.

Run /firefox when you want to declare Firefox directly to Pi instead of discovering it. Run /firefox close to stop Firefox and remove its direct declaration; later scripts can still launch it. On resume, Pi restores recorded tool declarations first; --firefox or firefox-bidi.enable: true can add the direct declaration at startup, including after an additive --tools -firefox_bidi removal. An explicit tool allowlist omitting Firefox, or its inclusion in --exclude-tools, still forbids activation.

What to expect

Pi uses the bundled Firefox guidance when it needs to compose WebDriver BiDi requests. Pi can send related browser actions together, receive browser responses and events, and wait for an expected event. Firefox is headless unless Pi starts it with a visible window. Firefox is discovered on PATH or in standard Windows system-wide and per-user installation locations. Set firefox-bidi.executablePath or FIREFOX_BIN to override discovery. Set firefox-bidi.screencastDir when Firefox screencasts should use a different default destination.

Codemode returns typed results with outcome, session metadata, responses, and events. When truncated is true, read payloadSpool selectively for omitted data. Protocol errors mark a partial outcome but allow later independent frames to run; cancellation and transport failures skip remaining frames. Page and event content remains untrusted.

Privacy and control

Pi sends raw WebDriver BiDi commands to the Firefox process it starts. Browser responses, events, screencasts, and page content can contain sensitive data. Use the fresh default profile for isolated work. Using privileged system access is a deliberate browser-launch choice, not a sandbox.

Reference

Commands

Command Purpose
/firefox Declare firefox_bidi directly (/firefox), or tear down (/firefox close)

Setting names

Setting Environment CLI flag
firefox-bidi.enable PI_FIREFOX --firefox
firefox-bidi.executablePath FIREFOX_BIN
firefox-bidi.screencastDir
<img src="assets/banner.svg" alt="firefox-bidi" height="70">

# firefox-bidi

Use Firefox from Pi when you want Pi to drive a real browser through WebDriver BiDi.
It is useful for opening pages, exercising browser behavior, inspecting results, or recording a screencast with Firefox-specific tooling.

[Installation](../../README.md#install)

## First use

Enable `codemode` or `tool_search` so Pi can discover Firefox, then ask Pi to perform browser task.
Firefox starts only when Pi first uses it and gets a fresh temporary profile.

```text
Use tool_search to find firefox_bidi, then open http://localhost:3000 and check whether the login form is usable.
```

Run `/firefox` when you want to declare Firefox directly to Pi instead of discovering it.
Run `/firefox close` to stop Firefox and remove its direct declaration; later scripts can still launch it.
On resume, Pi restores recorded tool declarations first; `--firefox` or `firefox-bidi.enable: true` can add the direct declaration at startup, including after an additive `--tools -firefox_bidi` removal.
An explicit tool allowlist omitting Firefox, or its inclusion in `--exclude-tools`, still forbids activation.

## What to expect

Pi uses the bundled Firefox guidance when it needs to compose WebDriver BiDi requests.
Pi can send related browser actions together, receive browser responses and events, and wait for an expected event.
Firefox is headless unless Pi starts it with a visible window.
Firefox is discovered on `PATH` or in standard Windows system-wide and per-user installation locations.
Set `firefox-bidi.executablePath` or `FIREFOX_BIN` to override discovery.
Set `firefox-bidi.screencastDir` when Firefox screencasts should use a different default destination.

Codemode returns typed results with `outcome`, session metadata, responses, and events.
When `truncated` is true, read `payloadSpool` selectively for omitted data.
Protocol errors mark a partial outcome but allow later independent frames to run; cancellation and transport failures skip remaining frames.
Page and event content remains untrusted.

## Privacy and control

Pi sends raw WebDriver BiDi commands to the Firefox process it starts.
Browser responses, events, screencasts, and page content can contain sensitive data.
Use the fresh default profile for isolated work.
Using privileged system access is a deliberate browser-launch choice, not a sandbox.

## Reference

<!-- config:start -->
### Commands

| Command | Purpose |
| --- | --- |
| `/firefox` | Declare firefox_bidi directly (/firefox), or tear down (/firefox close) |

### Setting names

| Setting | Environment | CLI flag |
| --- | --- | --- |
| `firefox-bidi.enable` | `PI_FIREFOX` | `--firefox` |
| `firefox-bidi.executablePath` | `FIREFOX_BIN` |   |
| `firefox-bidi.screencastDir` |   |   |
<!-- config:end -->