Consistent Tab IDs & Global Tag Targeting (#892)

Introduces stable per-tab IDs and a global `--tab <id>` flag for scoping individual commands to a specific tab.

Breaking change: response payloads for `tab_list`, `tab_new`, `tab_switch`, `tab_close`, and `window_new` now use `tabId` instead of `index`. `tab_close` returns `{tabId, closed: true}` instead of `{closed, activeIndex}`. `agent-browser tab <unknown>` now errors instead of silently listing tabs.

Follow-up PR to land immediately after this fixes a compile error on the provider direct-page path, clears per-tab daemon state around scoped switches, and implements active-tab restoration so `--tab N` is non-intrusive as intended.

Author: DJRHails

cli/src/commands.rs

@@ -1010,28 +1010,35 @@ fn parse_command_inner(args: &[String], flags: &Flags) -> Result<Value, ParseErr
         }
 
         // === Tabs ===
-        "tab" => match rest.first().copied() {
-            Some("new") => {
-                let mut cmd = json!({ "id": id, "action": "tab_new" });
-                if let Some(url) = rest.get(1) {
-                    cmd["url"] = json!(url);
+        "tab" => {
+            const VALID: &[&str] = &["list", "new", "close", "<id>"];
+            match rest.first().copied() {
+                Some("new") => {
+                    let mut cmd = json!({ "id": id, "action": "tab_new" });
+                    if let Some(url) = rest.get(1) {
+                        cmd["url"] = json!(url);
+                    }
+                    Ok(cmd)
                 }
-                Ok(cmd)
-            }
-            Some("list") => Ok(json!({ "id": id, "action": "tab_list" })),
-            Some("close") => {
-                let mut cmd = json!({ "id": id, "action": "tab_close" });
-                if let Some(index) = rest.get(1).and_then(|s| s.parse::<i32>().ok()) {
-                    cmd["index"] = json!(index);
+                Some("list") => Ok(json!({ "id": id, "action": "tab_list" })),
+                Some("close") => {
+                    let mut cmd = json!({ "id": id, "action": "tab_close" });
+                    if let Some(tab_id) = rest.get(1).and_then(|s| s.parse::<i32>().ok()) {
+                        cmd["tabId"] = json!(tab_id);
+                    }
+                    Ok(cmd)
                 }
-                Ok(cmd)
-            }
-            Some(n) if n.parse::<i32>().is_ok() => {
-                let index = n.parse::<i32>().expect("already checked parse succeeds");
-                Ok(json!({ "id": id, "action": "tab_switch", "index": index }))
+                Some(n) if n.parse::<i32>().is_ok() => {
+                    let tab_id = n.parse::<i32>().expect("already checked parse succeeds");
+                    Ok(json!({ "id": id, "action": "tab_switch", "tabId": tab_id }))
+                }
+                Some(sub) => Err(ParseError::UnknownSubcommand {
+                    subcommand: sub.to_string(),
+                    valid_options: VALID,
+                }),
+                None => Ok(json!({ "id": id, "action": "tab_list" })),
             }
-            _ => Ok(json!({ "id": id, "action": "tab_list" })),
-        },
+        }
 
         // === Window ===
         "window" => {
@@ -2335,6 +2342,7 @@ mod tests {
     fn default_flags() -> Flags {
         Flags {
             session: "test".to_string(),
+            tab: None,
             json: false,
             headed: false,
             debug: false,
@@ -2847,7 +2855,7 @@ mod tests {
     fn test_tab_switch() {
         let cmd = parse_command(&args("tab 2"), &default_flags()).unwrap();
         assert_eq!(cmd["action"], "tab_switch");
-        assert_eq!(cmd["index"], 2);
+        assert_eq!(cmd["tabId"], 2);
     }
 
     #[test]
@@ -2856,6 +2864,42 @@ mod tests {
         assert_eq!(cmd["action"], "tab_close");
     }
 
+    #[test]
+    fn test_tab_close_with_id() {
+        let cmd = parse_command(&args("tab close 2"), &default_flags()).unwrap();
+        assert_eq!(cmd["action"], "tab_close");
+        assert_eq!(cmd["tabId"], 2);
+    }
+
+    #[test]
+    fn test_tab_switch_sends_tab_id() {
+        let cmd = parse_command(&args("tab 2"), &default_flags()).unwrap();
+        assert_eq!(cmd["tabId"], 2);
+        assert!(cmd.get("index").is_none());
+    }
+
+    #[test]
+    fn test_tab_close_sends_tab_id() {
+        let cmd = parse_command(&args("tab close 3"), &default_flags()).unwrap();
+        assert_eq!(cmd["tabId"], 3);
+        assert!(cmd.get("index").is_none());
+    }
+
+    #[test]
+    fn test_tab_no_args_defaults_to_list() {
+        let cmd = parse_command(&args("tab"), &default_flags()).unwrap();
+        assert_eq!(cmd["action"], "tab_list");
+    }
+
+    #[test]
+    fn test_tab_unknown_subcommand_errors() {
+        let result = parse_command(&args("tab select 3"), &default_flags());
+        assert!(
+            result.is_err(),
+            "tab select should error, not silently fall through to tab_list"
+        );
+    }
+
     // === Network ===
 
     #[test]

cli/src/flags.rs

@@ -57,6 +57,7 @@ pub struct Config {
     pub json: Option<bool>,
     pub debug: Option<bool>,
     pub session: Option<String>,
+    pub tab: Option<u32>,
     pub session_name: Option<String>,
     pub executable_path: Option<String>,
     pub extensions: Option<Vec<String>>,
@@ -98,6 +99,7 @@ impl Config {
             json: other.json.or(self.json),
             debug: other.debug.or(self.debug),
             session: other.session.or(self.session),
+            tab: other.tab.or(self.tab),
             session_name: other.session_name.or(self.session_name),
             executable_path: other.executable_path.or(self.executable_path),
             extensions: match (self.extensions, other.extensions) {
@@ -196,6 +198,7 @@ fn parse_bool_arg(args: &[String], i: usize) -> (bool, bool) {
 fn extract_config_path(args: &[String]) -> Option<Option<String>> {
     const FLAGS_WITH_VALUE: &[&str] = &[
         "--session",
+        "--tab",
         "--headers",
         "--executable-path",
         "--cdp",
@@ -273,6 +276,7 @@ pub struct Flags {
     pub headed: bool,
     pub debug: bool,
     pub session: String,
+    pub tab: Option<u32>,
     pub headers: Option<String>,
     pub executable_path: Option<String>,
     pub cdp: Option<String>,
@@ -355,6 +359,7 @@ pub fn parse_flags(args: &[String]) -> Flags {
             .ok()
             .or(config.session)
             .unwrap_or_else(|| "default".to_string()),
+        tab: config.tab,
         headers: config.headers,
         executable_path: env::var("AGENT_BROWSER_EXECUTABLE_PATH")
             .ok()
@@ -492,6 +497,12 @@ pub fn parse_flags(args: &[String]) -> Flags {
                     i += 1;
                 }
             }
+            "--tab" => {
+                if let Some(s) = args.get(i + 1) {
+                    flags.tab = s.parse::<u32>().ok();
+                    i += 1;
+                }
+            }
             "--idle-timeout" => {
                 if let Some(s) = args.get(i + 1) {
                     match parse_idle_timeout(s) {
@@ -775,6 +786,7 @@ pub fn clean_args(args: &[String]) -> Vec<String> {
     // Global flags that always take a value (need to skip the next arg too)
     const GLOBAL_FLAGS_WITH_VALUE: &[&str] = &[
         "--session",
+        "--tab",
         "--headers",
         "--executable-path",
         "--cdp",
@@ -1441,4 +1453,25 @@ mod tests {
         let clean = clean_args(&input);
         assert_eq!(clean, vec!["open", "example.com"]);
     }
+
+    // === Tab flag tests ===
+
+    #[test]
+    fn test_parse_tab_flag() {
+        let flags = parse_flags(&args("--tab 4 snapshot"));
+        assert_eq!(flags.tab, Some(4));
+    }
+
+    #[test]
+    fn test_clean_args_removes_tab_flag() {
+        let cleaned = clean_args(&args("--tab 4 snapshot"));
+        assert_eq!(cleaned, vec!["snapshot"]);
+    }
+
+    #[test]
+    fn test_parse_tab_config() {
+        let json = r#"{"tab": 4}"#;
+        let config: Config = serde_json::from_str(json).unwrap();
+        assert_eq!(config.tab, Some(4));
+    }
 }

cli/src/main.rs

@@ -738,6 +738,12 @@ fn main() {
         }
     };
 
+    if let Some(tab_id) = flags.tab {
+        if cmd.get("tabId").is_none() {
+            cmd["tabId"] = json!(tab_id);
+        }
+    }
+
     // Handle --password-stdin for auth save
     if cmd.get("action").and_then(|v| v.as_str()) == Some("auth_save") {
         if cmd.get("password").is_some() {

cli/src/native/actions.rs

@@ -662,7 +662,9 @@ impl DaemonState {
                         .await;
                     }
 
+                    let tab_id = mgr.assign_tab_id();
                     mgr.add_page(super::browser::PageInfo {
+                        tab_id,
                         target_id: te.target_info.target_id.clone(),
                         session_id: attach.session_id,
                         url: te.target_info.url.clone(),
@@ -1273,6 +1275,20 @@ pub async fn execute_command(cmd: &Value, state: &mut DaemonState) -> Value {
         );
     }
 
+    // Pre-dispatch: if tabId is set on a non-tab command, switch to that tab first
+    if !matches!(
+        action,
+        "tab_list" | "tab_new" | "tab_switch" | "tab_close" | "launch" | "close"
+    ) {
+        if let Some(tab_id) = cmd.get("tabId").and_then(|v| v.as_u64()) {
+            if let Some(ref mut mgr) = state.browser {
+                if let Err(e) = mgr.tab_switch_by_id(tab_id as u32).await {
+                    return error_response(&id, &e);
+                }
+            }
+        }
+    }
+
     let result = match action {
         "launch" => handle_launch(cmd, state).await,
         "navigate" => handle_navigate(cmd, state).await,
@@ -3647,14 +3663,14 @@ async fn handle_tab_new(cmd: &Value, state: &mut DaemonState) -> Result<Value, S
 
 async fn handle_tab_switch(cmd: &Value, state: &mut DaemonState) -> Result<Value, String> {
     let mgr = state.browser.as_mut().ok_or("Browser not launched")?;
-    let index = cmd
-        .get("index")
+    let tab_id = cmd
+        .get("tabId")
         .and_then(|v| v.as_u64())
-        .ok_or("Missing 'index' parameter")? as usize;
+        .ok_or("Missing 'tabId' parameter")? as u32;
     state.ref_map.clear();
     state.iframe_sessions.clear();
     state.active_frame_id = None;
-    let result = mgr.tab_switch(index).await?;
+    let result = mgr.tab_switch_by_id(tab_id).await?;
 
     if let Some(ref server) = state.stream_server {
         if let Ok(dims) = mgr
@@ -3679,14 +3695,11 @@ async fn handle_tab_switch(cmd: &Value, state: &mut DaemonState) -> Result<Value
 
 async fn handle_tab_close(cmd: &Value, state: &mut DaemonState) -> Result<Value, String> {
     let mgr = state.browser.as_mut().ok_or("Browser not launched")?;
-    let index = cmd
-        .get("index")
-        .and_then(|v| v.as_u64())
-        .map(|i| i as usize);
+    let tab_id = cmd.get("tabId").and_then(|v| v.as_u64()).map(|i| i as u32);
     state.ref_map.clear();
     state.iframe_sessions.clear();
     state.active_frame_id = None;
-    mgr.tab_close(index).await
+    mgr.tab_close_by_id(tab_id).await
 }
 
 async fn handle_viewport(cmd: &Value, state: &mut DaemonState) -> Result<Value, String> {
@@ -4065,7 +4078,9 @@ async fn handle_recording_start(cmd: &Value, state: &mut DaemonState) -> Result<
         }
 
         // Add page and switch to it
+        let tab_id = mgr.assign_tab_id();
         mgr.add_page(super::browser::PageInfo {
+            tab_id,
             target_id: create_result.target_id,
             session_id: new_session_id.clone(),
             url: nav_url.clone(),
@@ -5976,7 +5991,9 @@ async fn handle_window_new(cmd: &Value, state: &mut DaemonState) -> Result<Value
         )
         .await?;
 
+    let tab_id = mgr.assign_tab_id();
     mgr.add_page(super::browser::PageInfo {
+        tab_id,
         target_id: create_result.target_id,
         session_id: attach.session_id,
         url: "about:blank".to_string(),
@@ -6004,7 +6021,7 @@ async fn handle_window_new(cmd: &Value, state: &mut DaemonState) -> Result<Value
     let total = mgr.page_count();
     state.ref_map.clear();
 
-    Ok(json!({ "index": total - 1, "total": total }))
+    Ok(json!({ "tabId": tab_id, "total": total }))
 }
 
 async fn handle_diff_screenshot(cmd: &Value, state: &DaemonState) -> Result<Value, String> {