feat(firefox): launch Firefox over WebDriver BiDi

.github/workflows/ci.yml

@@ -210,7 +210,6 @@ jobs:
 
   native-e2e:
     name: Native E2E Tests
-    if: github.event_name != 'pull_request'
     runs-on: ubuntu-latest
     needs: rust
     steps:
@@ -226,21 +225,34 @@ jobs:
           workspaces: cli
 
       - name: Install Chrome
+        if: github.event_name != 'pull_request'
         run: |
           cargo run --manifest-path cli/Cargo.toml -- install --with-deps
 
       - name: Install ffmpeg
         run: sudo apt-get update && sudo apt-get install -y ffmpeg
 
       - name: Install Obscura
+        if: github.event_name != 'pull_request'
         run: |
           mkdir -p "$RUNNER_TEMP/obscura"
           curl -fsSL https://github.com/h4ckf0r0day/obscura/releases/download/v0.2.4/obscura-x86_64-linux.tar.gz \
             | tar xz -C "$RUNNER_TEMP/obscura"
           echo "OBSCURA_BIN=$RUNNER_TEMP/obscura/obscura" >> "$GITHUB_ENV"
 
+      - name: Install Firefox
+        run: |
+          mkdir -p "$RUNNER_TEMP/firefox"
+          curl -fsSL "https://download.mozilla.org/?product=firefox-latest-ssl&os=linux64&lang=en-US" \
+            | tar xJ -C "$RUNNER_TEMP/firefox"
+          echo "FIREFOX_BIN=$RUNNER_TEMP/firefox/firefox/firefox" >> "$GITHUB_ENV"
+
       - name: Run e2e tests
-        run: cargo test --profile ci --manifest-path cli/Cargo.toml e2e -- --ignored --test-threads=1
+        if: github.event_name != 'pull_request'
+        run: cargo test --profile ci --manifest-path cli/Cargo.toml e2e -- --ignored --test-threads=1 --skip e2e_firefox
+
+      - name: Run Firefox e2e tests
+        run: cargo test --profile ci --manifest-path cli/Cargo.toml e2e_firefox -- --ignored --test-threads=1
 
   windows-integration:
     name: Windows Integration Test

README.md

@@ -53,6 +53,8 @@ The CLI sends each command to a background daemon that starts on the first comma
 
 Chrome for Testing is the default browser. You can also attach to a running Chrome with `--cdp` or `--auto-connect` ([CDP mode](https://agent-browser.dev/cdp-mode)), select the [Lightpanda](https://agent-browser.dev/engines/lightpanda) or [Obscura](https://agent-browser.dev/engines/obscura) engine with `--engine`, drive Mobile Safari in the [iOS Simulator](https://agent-browser.dev/ios), or use a cloud browser provider such as [Browserbase](https://agent-browser.dev/providers/browserbase), [Browserless](https://agent-browser.dev/providers/browserless), [Browser Use](https://agent-browser.dev/providers/browser-use), [Kernel](https://agent-browser.dev/providers/kernel), or [AgentCore](https://agent-browser.dev/providers/agentcore).
 
+Select Firefox with `--engine firefox`.
+
 ## For AI agents
 
 The CLI ships skills that match its version:

cli/src/doctor/chrome.rs

@@ -110,6 +110,24 @@ pub(super) fn check(checks: &mut Vec<Check>) {
                     .with_fix("install lightpanda or unset AGENT_BROWSER_ENGINE"),
                 );
             }
+        } else if engine == "firefox" {
+            match crate::native::firefox::process::find_firefox(None) {
+                Ok(path) => {
+                    let version = query_chrome_version(&path)
+                        .map(|v| format!("{v} at "))
+                        .unwrap_or_default();
+                    checks.push(Check::new(
+                        "chrome.engine_firefox",
+                        category,
+                        Status::Pass,
+                        format!("{}{}", version, path.display()),
+                    ));
+                }
+                Err(e) => checks.push(
+                    Check::new("chrome.engine_firefox", category, Status::Fail, e)
+                        .with_fix("install Firefox 150 or newer or unset AGENT_BROWSER_ENGINE"),
+                ),
+            }
         } else if engine == "obscura" {
             // Same lookup as launch, so doctor and launch agree on where the
             // binary is.

cli/src/mcp.rs

@@ -1399,7 +1399,7 @@ fn parity_tools() -> Vec<Value> {
         tool(
             TOOL_COOKIES_GET,
             "Cookies get",
-            "Get cookies.",
+            "Get cookies. When URLs are omitted, Firefox filters to the active page and its frames.",
             json!({}),
             &[],
         ),
@@ -1683,7 +1683,7 @@ fn parity_tools() -> Vec<Value> {
         tool(
             TOOL_STATE_SAVE,
             "State save",
-            "Save cookies and storage state.",
+            "Save cookies and storage state, overwriting the target file.",
             json!({ "path": { "type": "string" } }),
             &["path"],
         ),
@@ -2163,7 +2163,7 @@ fn shared_property(key: &str) -> Value {
         }),
         "restore" => json!({
             "oneOf": [{ "type": "boolean" }, { "type": "string" }],
-            "description": "Restore and auto-save browser state. true keys it by session; a string is an explicit key."
+            "description": "Restore and auto-save browser state. true uses the current session as the key; a string uses that explicit key. Firefox auto-save includes active iframe origins and preserves saved origins it cannot read."
         }),
         "allowedDomains" => json!({
             "type": "array",
@@ -2194,7 +2194,7 @@ fn shared_property(key: &str) -> Value {
     }
 }
 
-const SHARED_ARGUMENTS_INSTRUCTIONS: &str = "Every tool accepts these optional arguments even when its schema does not list them: session (isolated browser session name), restore (true or a key; restores and auto-saves browser state when the call launches the browser), allowedDomains (domain patterns that restrict browser and read traffic when the call launches the browser; also disables RTCPeerConnection in Chromium sessions, and is rejected when the server environment or config already sets allowed domains), capture (set to flow to record the session so flow steps and flow save can turn it into a reusable flow, when the call launches the browser), extraArgs (extra CLI arguments such as --engine; global flags that change network, file, policy, or host access, such as --allowed-domains, --executable-path, --args, and --config, are rejected, so set those in the MCP server environment or config), timeoutMs (positive integer, maximum milliseconds to wait for the tool call), namespace (isolates daemon sockets and restore-state directories), restoreSave (auto, always, or never), restoreCheckUrl, restoreCheckText, and restoreCheckFn (conditions restored state must satisfy), caCert (path to a CA certificate or PEM bundle for the CLI's HTTPS requests and locally launched Chromium on Linux), useSystemCa (boolean, use the OS trust store for the CLI's HTTPS requests), clearCaCert (boolean, clear CA trust retained by the session; cannot be combined with caCert), idleTimeout (such as 30s, 5m, 1h, or milliseconds; defaults to 1h, 0 disables idle shutdown), and relaunch (boolean, relaunch the session's browser even when no setting changed).";
+const SHARED_ARGUMENTS_INSTRUCTIONS: &str = "Every tool accepts these optional arguments even when its schema does not list them: session (isolated browser session name), restore (true or a key; restores and auto-saves browser state when the call launches the browser; Firefox auto-save includes active iframe origins and preserves saved origins it cannot read), allowedDomains (domain patterns that restrict browser and read traffic when the call launches the browser; also disables RTCPeerConnection in Chromium sessions, and is rejected when the server environment or config already sets allowed domains), capture (set to flow to record the session so flow steps and flow save can turn it into a reusable flow, when the call launches the browser), extraArgs (extra CLI arguments such as --engine; global flags that change network, file, policy, or host access, such as --allowed-domains, --executable-path, --args, and --config, are rejected, so set those in the MCP server environment or config), timeoutMs (positive integer, maximum milliseconds to wait for the tool call), namespace (isolates daemon sockets and restore-state directories), restoreSave (auto, always, or never), restoreCheckUrl, restoreCheckText, and restoreCheckFn (conditions restored state must satisfy), caCert (path to a CA certificate or PEM bundle for the CLI's HTTPS requests and locally launched Chromium on Linux), useSystemCa (boolean, use the OS trust store for the CLI's HTTPS requests), clearCaCert (boolean, clear CA trust retained by the session; cannot be combined with caCert), idleTimeout (such as 30s, 5m, 1h, or milliseconds; defaults to 1h, 0 disables idle shutdown), and relaunch (boolean, relaunch the session's browser even when no setting changed).";
 
 /// Levenshtein distance, for suggesting a close argument name.
 fn edit_distance(a: &str, b: &str) -> usize {