feat(firefox): attach to a running Firefox over WebDriver BiDi

README.md

@@ -53,7 +53,7 @@ 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`. It requires Firefox 150 or newer, uses WebDriver BiDi and Firefox's DevTools accessibility tree for snapshots, and starts with a fresh temporary profile. See the [Firefox engine guide](https://agent-browser.dev/engines/firefox).
+Select Firefox with `--engine firefox`. It requires Firefox 150 or newer, uses WebDriver BiDi and Firefox's DevTools accessibility tree for snapshots, and starts with a fresh temporary profile. You can also attach to a running Firefox with `connect` or `--cdp`. See [CDP mode](https://agent-browser.dev/cdp-mode) for attach setup.
 
 ## For AI agents
 

cli/src/commands.rs

@@ -381,6 +381,24 @@ fn reject_batch_global_flag(batch_item: bool, arg: &str) -> Result<(), ParseErro
     }
 }
 
+pub fn attach_allowed_domains_to_launch_command(cmd: &mut Value, flags: &Flags) {
+    if let Some(ref domains) = flags.allowed_domains {
+        cmd["allowedDomains"] = json!(domains);
+    }
+}
+
+/// Adds the launch settings that also apply when attaching to a running browser.
+pub fn apply_attach_launch_options(cmd: &mut Value, flags: &Flags) {
+    attach_allowed_domains_to_launch_command(cmd, flags);
+    if let Some(ref path) = flags.download_path {
+        cmd["downloadPath"] = json!(path);
+    }
+    if let Some(ref engine) = flags.engine {
+        cmd["engine"] = json!(engine);
+    }
+}
+
+/// Stamps `timeout` on a wait-family command that has none.
 /// Stamps `timeout` on a wait-family command or `flow_save` that has none,
 /// so the client read timeout follows it.
 pub fn inherit_wait_timeout(cmd: &mut Value, timeout: Option<u64>) {
@@ -1393,6 +1411,7 @@ fn parse_command_inner(
                 || endpoint.starts_with("https://")
             {
                 let mut cmd = json!({ "id": id, "action": "launch", "cdpUrl": endpoint });
+                apply_attach_launch_options(&mut cmd, flags);
                 if let Some(ref raw) = flags.cdp_headers {
                     cmd["cdpHeaders"] =
                         parse_cdp_headers(raw).map_err(|message| ParseError::InvalidValue {
@@ -1431,6 +1450,7 @@ fn parse_command_inner(
                     }
                 };
                 let mut cmd = json!({ "id": id, "action": "launch", "cdpPort": port });
+                apply_attach_launch_options(&mut cmd, flags);
                 if let Some(ref raw) = flags.cdp_headers {
                     cmd["cdpHeaders"] =
                         parse_cdp_headers(raw).map_err(|message| ParseError::InvalidValue {
@@ -6585,6 +6605,27 @@ mod tests {
         assert_eq!(cmd["cdpPort"], 1);
     }
 
+    #[test]
+    fn test_connect_forwards_attach_launch_options() {
+        let mut flags = default_flags();
+        flags.download_path = Some("/tmp/downloads".to_string());
+        flags.allowed_domains = Some(vec!["example.com".to_string()]);
+        flags.engine = Some("firefox".to_string());
+        flags.profile = Some("/tmp/profile".to_string());
+        flags.init_scripts = vec!["/tmp/init.js".to_string()];
+
+        let port = parse_command(&args("connect 9222"), &flags).unwrap();
+        assert_eq!(port["downloadPath"], "/tmp/downloads");
+        assert_eq!(port["allowedDomains"], json!(["example.com"]));
+        assert_eq!(port["engine"], "firefox");
+        assert!(port.get("profile").is_none());
+        assert!(port.get("initScripts").is_none());
+
+        let url = parse_command(&args("connect ws://127.0.0.1:9222/session"), &flags).unwrap();
+        assert_eq!(url["downloadPath"], "/tmp/downloads");
+        assert_eq!(url["engine"], "firefox");
+    }
+
     // === Runtime stream control tests ===
 
     #[test]

cli/src/main.rs

@@ -2324,6 +2324,27 @@ mod tests {
         assert_eq!(wire["headed"], true);
     }
 
+    #[test]
+    fn firefox_cdp_flags_travel_with_the_command_settings() {
+        let (command, wire) = settings_of(&[
+            "--engine",
+            "firefox",
+            "--cdp",
+            "9222",
+            "--download-path",
+            "/tmp/downloads",
+            "--allowed-domains",
+            "example.com",
+            "get",
+            "url",
+        ]);
+        assert_eq!(command["action"], "url");
+        assert_eq!(wire["engine"], "firefox");
+        assert_eq!(wire["cdp"], "9222");
+        assert_eq!(wire["download-path"], "/tmp/downloads");
+        assert_eq!(wire["allowed-domains"], json!(["example.com"]));
+    }
+
     #[test]
     fn settings_distinguish_ca_trust_set_omitted_and_cleared() {
         let (_, omitted) = settings_of(&["get", "url"]);

cli/src/mcp.rs

@@ -1862,11 +1862,11 @@ fn parity_tools() -> Vec<Value> {
         ),
         tool(
             TOOL_CONNECT,
-            "Connect CDP",
-            "Connect to a browser over CDP. With pinTab, the session is strictly bound to its own tab: it re-binds by target id after restarts and fails with a tab_gone error instead of adopting another tab. Structured errors include code=tab_gone, data.targetId, and optional sanitized data.lastUrl. Pass pinTab: false to explicitly disable a sticky pin; omit it to keep the current state. The session stays attached until agent_browser_close, so later tools without a connection target use the same browser.",
+            "Connect to browser via CDP or Firefox WebDriver BiDi",
+            "Connect to a browser over CDP or to a running Firefox over WebDriver BiDi. A ws:// URL whose path is /session attaches to Firefox directly; an http(s):// URL or bare port falls back to BiDi when CDP discovery finds nothing. Add ?devtools=<port> to point at the Firefox DevTools server (default 6000). Firefox's RDP companion is unencrypted, so remote Firefox ports must be forwarded through an encrypted tunnel and the connection must use 127.0.0.1. With pinTab on a Chrome CDP session, the session is strictly bound to its own tab: it re-binds by target id after restarts and fails with a tab_gone error instead of adopting another tab. The pinTab binding and its tab_gone guarantee are CDP-only; Firefox attach rejects pinTab. Structured errors include code=tab_gone, data.targetId, and optional sanitized data.lastUrl. Pass pinTab: false to explicitly disable a sticky pin; omit it to keep the current state. The session stays attached until agent_browser_close, so later tools without a connection target use the same browser.",
             json!({
-                "target": { "type": "string", "description": "CDP port or URL." },
-                "pinTab": { "type": "boolean", "description": "Strict session-to-tab binding (sticky for the session). Explicit false disables a sticky pin; omitted leaves it unchanged." }
+                "target": { "type": "string", "description": "CDP port or URL, or a Firefox WebDriver BiDi endpoint such as ws://127.0.0.1:9333/session or http://127.0.0.1:9333?devtools=6080." },
+                "pinTab": { "type": "boolean", "description": "Strict session-to-tab binding (sticky for the session; CDP only, rejected for Firefox attach). Explicit false disables a sticky pin; omitted leaves it unchanged." }
             }),
             &["target"],
         ),
@@ -2853,15 +2853,19 @@ fn call_one_string(arguments: &Value, command: &str, key: &str) -> Result<Value,
     call_cli_tool(arguments, args, None)
 }
 
-fn call_connect(arguments: &Value) -> Result<Value, ProtocolError> {
+fn connect_args(arguments: &Value) -> Result<Vec<String>, ProtocolError> {
     let mut args = vec!["connect".to_string()];
     args.push(required_string(arguments, "target")?);
     match arguments.get("pinTab").and_then(|v| v.as_bool()) {
         Some(true) => args.push("--pin-tab".to_string()),
         Some(false) => args.push("--no-pin-tab".to_string()),
         None => {}
     }
-    call_cli_tool(arguments, args, None)
+    Ok(args)
+}
+
+fn call_connect(arguments: &Value) -> Result<Value, ProtocolError> {
+    call_cli_tool(arguments, connect_args(arguments)?, None)
 }
 
 fn call_optional_one(arguments: &Value, parts: &[&str], key: &str) -> Result<Value, ProtocolError> {
@@ -4843,6 +4847,27 @@ mod tests {
         }
     }
 
+    #[test]
+    fn connect_forwards_a_firefox_bidi_endpoint_to_the_cli_parser() {
+        for target in [
+            "9333",
+            "ws://127.0.0.1:9333/session",
+            "ws://127.0.0.1:9333/session?devtools=6080",
+            "http://127.0.0.1:9333?devtools=6080",
+        ] {
+            let args = connect_args(&json!({ "target": target })).unwrap();
+            assert_eq!(args, vec!["connect", target]);
+            let flags = crate::flags::parse_flags(&args);
+            let command = crate::commands::parse_command(&args, &flags).unwrap();
+            assert_eq!(command["action"], "launch");
+            if target == "9333" {
+                assert_eq!(command["cdpPort"], 9333);
+            } else {
+                assert_eq!(command["cdpUrl"], target);
+            }
+        }
+    }
+
     #[test]
     fn conditional_screenshot_scope_matches_cli_parser() {
         for scope in [