feat: agents never steal focus in BrowserClaw (#2531)

* feat(claw-mcp): tabs new and pages.newPage always open in the background

Agents can no longer request a foreground tab. The background field is
still accepted and ignored so clients holding the old schema keep working,
but it is hidden from the tool schema. Conformance cases stop assuming an
agent-opened page becomes the active tab.

* feat(patches): automation never steals focus pref and Browser gates

Adds browseros.automation_never_steals_focus (default on for BrowserClaw).
With it on, a tab with a DevTools client attached cannot switch the user's
active tab or raise the window through Browser::ActivateContents, and tabs
or popups its pages open after an agent click land in the background
(Browser::AddNewContents, mirroring the upstream actor gate).

* feat(patches): Browser.createTab defaults to background; activate commands honour the focus pref

createTab now opens tabs in the background unless background=false is
passed, and an explicit false only selects the tab within its window.
Under browseros.automation_never_steals_focus, activateTab stops raising
the window, activateWindow becomes a no-op, and createWindow plus
setWindowVisibility(activate) show windows inactive.

* test(claw-mcp): retired tabs background field stays accepted but inert

Author: shadowfax92

packages/browseros-agent/contracts/claw-mcp/tests/cases-snapshot-concurrency.ts

@@ -452,7 +452,6 @@ export const snapshotConcurrencyCases: ContractCase[] = [
         const result = await ctx.mcp.callTool('tabs', {
           action: 'new',
           url: mixedFrameUrl(ctx),
-          background: false,
         })
         const text = expectOk(result, 'tabs new mixed-frame auto-context')
         page = parsePageId(result)

packages/browseros-agent/contracts/claw-mcp/tests/cases-tabs.ts

@@ -21,13 +21,12 @@ function parseGroupId(text: string): string {
 
 export const tabsCases: ContractCase[] = [
   {
-    name: 'tabs: new foreground page opens with auto-context',
+    name: 'tabs: new page opens with auto-context',
     smoke: true,
     async run(ctx) {
       const result = await ctx.mcp.callTool('tabs', {
         action: 'new',
         url: ctx.fixture('/links.html'),
-        background: false,
       })
       const text = expectOk(result, 'tabs new')
       const page = parsePageId(result)
@@ -51,35 +50,31 @@ export const tabsCases: ContractCase[] = [
     },
   },
   {
-    name: 'tabs: active reports the focused page',
+    name: 'tabs: active reports the user tab, never an agent-opened page',
     async run(ctx) {
+      // Agents cannot request a foreground tab, so the page opened here must
+      // stay out of `tabs active`; the user's tab keeps that role.
       const page = await ctx.openPage(ctx.fixture('/form.html'))
-      let text = ''
-      await waitUntil(async () => {
-        text = expectOk(
-          await ctx.mcp.callTool('tabs', { action: 'active' }),
-          'tabs active',
-        )
-        return text.includes('/form.html') || text.includes(`${page}`)
-      }, 'active tab to report the focused form page')
+      const text = expectOk(
+        await ctx.mcp.callTool('tabs', { action: 'active' }),
+        'tabs active',
+      )
+      if (!text.startsWith('Active page:')) {
+        throw new Error(`tabs active did not report a page: ${text}`)
+      }
+      if (text.includes(`[${page}]`)) {
+        throw new Error(`agent-opened page became active: ${text}`)
+      }
     },
   },
   {
-    name: 'tabs: background page stays inactive and hidden is rejected',
+    name: 'tabs: new page stays inactive and hidden is rejected',
     async run(ctx) {
-      const focused = await ctx.openPage(ctx.fixture('/form.html'))
-      await waitUntil(async () => {
-        const active = expectOk(
-          await ctx.mcp.callTool('tabs', { action: 'active' }),
-        )
-        return active.includes(`[${focused}]`)
-      }, 'the foreground page to receive focus')
       const result = await ctx.mcp.callTool('tabs', {
         action: 'new',
         url: ctx.fixture('/links.html'),
-        background: true,
       })
-      expectOk(result, 'tabs new background')
+      expectOk(result, 'tabs new')
       const opened = parsePageId(result)
       const active = expectOk(
         await ctx.mcp.callTool('tabs', { action: 'active' }),
@@ -95,9 +90,8 @@ export const tabsCases: ContractCase[] = [
         }),
         'tabs new hidden',
       )
-      // Track for cleanup — openPage was bypassed to control background creation.
+      // Track for cleanup — openPage was bypassed to call the tool directly.
       await ctx.mcp.callTool('tabs', { action: 'close', page: opened })
-      await ctx.mcp.callTool('tabs', { action: 'close', page: focused })
     },
   },
   {

packages/browseros-agent/contracts/claw-mcp/tests/rust-conformance.test.ts

@@ -117,7 +117,6 @@ function makeContext(run: ServerRun): CaseContext {
       const result = await session.callTool('tabs', {
         action: 'new',
         url,
-        background: false,
       })
       if (result.isError) {
         throw new Error(`tabs new failed: ${textOf(result)}`)

packages/browseros-agent/crates/browseros-mcp/src/tests.rs

@@ -489,6 +489,9 @@ fn tab_and_window_schemas_omit_hidden_controls() {
     let tabs = tool_by_name("tabs");
     let tabs_schema = Value::Object(tabs.input_schema.as_ref().clone());
     assert!(tabs_schema.pointer("/properties/hidden").is_none());
+    // Focus is the user's call: agents cannot ask for a foreground tab.
+    assert!(tabs_schema.pointer("/properties/background").is_none());
+    assert!(!tabs.description.contains("foreground"));
 
     let windows = tool_by_name("windows");
     let windows_schema = Value::Object(windows.input_schema.as_ref().clone());

packages/browseros-agent/crates/browseros-mcp/src/tools/mod.rs

@@ -111,7 +111,3 @@ fn metadata_for_tool(name: &str) -> ToolMetadata {
         ),
     }
 }
-
-fn default_true() -> bool {
-    true
-}

packages/browseros-agent/crates/browseros-mcp/src/tools/run.rs

@@ -35,7 +35,7 @@ const DESCRIPTION: &str = r#"The primary way to drive the browser - prefer run f
 The return shapes below are stable. Do NOT probe them at runtime (no typeof / Object.keys / getOwnPropertyNames) and do NOT re-open a page to inspect what a call returned; that just piles up duplicate tabs. Reuse a pageId across steps.
 
 Pages (pageId is a NUMBER):
-  browser.pages.newPage(url)   -> pageId (number). Use it directly; it is not an object. Opens in the background so it does not steal the user's focus; pass { background: false } only when the user asks to bring the tab to the front.
+  browser.pages.newPage(url)   -> pageId (number). Use it directly; it is not an object. Always opens in the background; it never switches the user's tab.
   browser.pages.close(pageId)  -> undefined. Closes a page you own.
   browser.pages.list()         -> [{ pageId, url, title, ownership, ownerLabel, ... }] for EVERY open tab in the browser, including the user's and other agents'. `ownership` is "mine" | "user" | "other-agent"; "other-agent" tabs also carry ownerLabel. Act only on your own ("mine") tabs. Leave "user" and "other-agent" tabs alone unless the user explicitly asks you to work on one.
   browser.pages.getInfo(pageId)-> { pageId, url, title, ... } or null
@@ -655,12 +655,10 @@ impl BrowserBridge {
                     .race(self.ctx.session.pages.new_page(
                         &url,
                         NewPageOptions {
-                            // Default to a background tab so a working agent does
-                            // not steal the user's focus, matching the granular
-                            // tabs-new default. An explicit background:false opens
-                            // it active, which the agent should do only when the
-                            // user asks to bring a tab to the front.
-                            background: optional_bool_field(opts, "background")?.or(Some(true)),
+                            // Always a background tab: an agent must never switch
+                            // the user's tab. A `background` option is ignored
+                            // rather than rejected so older scripts keep working.
+                            background: Some(true),
                             window_id,
                             tab_group_id,
                         },
@@ -1045,17 +1043,6 @@ fn optional_object_arg(
     }
 }
 
-fn optional_bool_field(
-    object: Option<&Map<String, Value>>,
-    name: &str,
-) -> Result<Option<bool>, String> {
-    match object.and_then(|object| object.get(name)) {
-        None | Some(Value::Null) => Ok(None),
-        Some(Value::Bool(value)) => Ok(Some(*value)),
-        Some(_) => Err(format!("{name} must be a boolean")),
-    }
-}
-
 fn optional_i64_field(
     object: Option<&Map<String, Value>>,
     name: &str,
@@ -2159,7 +2146,7 @@ return { pageId: page.pageId, tabId: page.tabId, url: page.url, title: page.titl
         let result = run_tool_with_ctx(
             r#"
 return await browser.pages.newPage('https://new.example', {
-  background: true,
+  background: false,
   windowId: 88,
   tabGroupId: 'group-opts',
 });
@@ -2184,6 +2171,8 @@ return await browser.pages.newPage('https://new.example', {
             create_params.first().and_then(|params| params.get("url")),
             Some(&json!("https://new.example"))
         );
+        // `background: false` is accepted but ignored: agents never get a
+        // foreground tab.
         assert_eq!(
             create_params
                 .first()

packages/browseros-agent/crates/browseros-mcp/src/tools/tabs.rs

@@ -9,7 +9,7 @@ use serde_json::json;
 
 const DESCRIPTION: &str = "\
 Manage browser tabs: list open pages (with their page ids), show the active page, \
-open a new page (snapshot attached), or close one. \
+open a new page in the background (snapshot attached), or close one. \
 Use the returned page id with snapshot/act/navigate.";
 
 #[derive(Debug, Clone, Default, Deserialize, JsonSchema)]
@@ -29,9 +29,12 @@ struct TabsArgs {
     action: TabsAction,
     /// URL for action="new" (defaults to about:blank).
     url: Option<String>,
-    /// Open without stealing focus for action="new".
-    #[serde(default = "super::default_true")]
-    background: bool,
+    /// Retired: new pages always open in the background so an agent never
+    /// switches the user's tab. Still accepted, and ignored, so clients that
+    /// cached the old schema do not trip `deny_unknown_fields`.
+    #[serde(default, rename = "background")]
+    #[schemars(skip)]
+    _background: Option<bool>,
     /// Page id for action="close".
     page: Option<u32>,
 }
@@ -87,7 +90,9 @@ fn handler<'a>(
                     .new_page(
                         args.url.as_deref().unwrap_or("about:blank"),
                         NewPageOptions {
-                            background: Some(args.background),
+                            // Never foreground: focus decisions belong to the user
+                            // (cockpit Watch), not to the agent.
+                            background: Some(true),
                             window_id: ctx.defaults.default_window_id.clone(),
                             tab_group_id: ctx.defaults.default_tab_group_id.clone(),
                         },
@@ -118,3 +123,26 @@ fn format_page_line(page: &browseros_core::pages::PageInfo) -> String {
         format!("[{}] {} ({})", page.page_id.0, page.url, page.title)
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::{TabsAction, TabsArgs};
+    use serde_json::json;
+
+    #[test]
+    fn retired_background_field_is_accepted_and_ignored() -> anyhow::Result<()> {
+        // Clients that cached the old schema still send it; it must not trip
+        // `deny_unknown_fields`, and it must not influence the tab's focus.
+        let args: TabsArgs =
+            serde_json::from_value(json!({ "action": "new", "background": false }))?;
+        assert!(matches!(args.action, TabsAction::New));
+        assert_eq!(args._background, Some(false));
+        Ok(())
+    }
+
+    #[test]
+    fn unknown_fields_are_still_rejected() {
+        let result = serde_json::from_value::<TabsArgs>(json!({ "action": "new", "hidden": true }));
+        assert!(result.is_err_and(|error| error.to_string().contains("hidden")));
+    }
+}

packages/browseros/chromium_patches/chrome/browser/browseros/core/browseros_prefs.cc

@@ -1,9 +1,9 @@
 diff --git a/chrome/browser/browseros/core/browseros_prefs.cc b/chrome/browser/browseros/core/browseros_prefs.cc
 new file mode 100644
-index 0000000000000..274fa0c0a3d79
+index 0000000000000000000000000000000000000000..68597d68ae413015f8783404d822d8a3f7dacb44
 --- /dev/null
 +++ b/chrome/browser/browseros/core/browseros_prefs.cc
-@@ -0,0 +1,125 @@
+@@ -0,0 +1,133 @@
 +// Copyright 2025 The Chromium Authors
 +// Use of this source code is governed by a BSD-style license that can be
 +// found in the LICENSE file.
@@ -39,6 +39,10 @@ index 0000000000000..274fa0c0a3d79
 +
 +  registry->RegisterBooleanPref(prefs::kNtpFocusContent, false);
 +  registry->RegisterBooleanPref(prefs::kOnboardingCompleted, false);
++  // BrowserClaw is a browser for agents: they work in the background by
++  // default. BrowserOS keeps stock focus behaviour.
++  registry->RegisterBooleanPref(prefs::kAutomationNeverStealsFocus,
++                                IsBrowserClawProduct());
 +}
 +
 +bool ShouldShowLLMChat(PrefService* pref_service) {
@@ -104,6 +108,10 @@ index 0000000000000..274fa0c0a3d79
 +  return pref_service->GetBoolean(prefs::kNtpFocusContent);
 +}
 +
++bool AutomationNeverStealsFocus(PrefService* pref_service) {
++  return pref_service->GetBoolean(prefs::kAutomationNeverStealsFocus);
++}
++
 +const char* GetVisibilityPrefForAction(actions::ActionId id) {
 +  switch (id) {
 +    case kActionSidePanelShowThirdPartyLlm:

packages/browseros/chromium_patches/chrome/browser/browseros/core/browseros_prefs.h

@@ -1,9 +1,9 @@
 diff --git a/chrome/browser/browseros/core/browseros_prefs.h b/chrome/browser/browseros/core/browseros_prefs.h
 new file mode 100644
-index 0000000000000..b04a6ef039a6b
+index 0000000000000000000000000000000000000000..893ade589e58d07c85848b790079481c2452b9e7
 --- /dev/null
 +++ b/chrome/browser/browseros/core/browseros_prefs.h
-@@ -0,0 +1,111 @@
+@@ -0,0 +1,125 @@
 +// Copyright 2025 The Chromium Authors
 +// Use of this source code is governed by a BSD-style license that can be
 +// found in the LICENSE file.
@@ -58,6 +58,16 @@ index 0000000000000..b04a6ef039a6b
 +
 +inline constexpr char kOnboardingCompleted[] = "browseros.onboarding_completed";
 +
++// Boolean: Automation-driven tabs never pull the user's attention. A tab counts
++// as automation-driven while a DevTools client is attached to it, which is
++// every tab the claw-server (or any CDP client) acts on. With the pref on such
++// a tab cannot switch the user's active tab or raise the window, and tabs or
++// popups its pages open land in the background. Gates live in
++// Browser::ActivateContents, Browser::AddNewContents and the DevTools
++// BrowserHandler. Default: true for BrowserClaw, false for BrowserOS.
++inline constexpr char kAutomationNeverStealsFocus[] =
++    "browseros.automation_never_steals_focus";
++
 +}  // namespace prefs
 +
 +// Registers BrowserOS profile preferences.
@@ -109,6 +119,10 @@ index 0000000000000..b04a6ef039a6b
 +// Check if NTP content should receive focus instead of the omnibox.
 +bool IsNtpFocusContentEnabled(PrefService* pref_service);
 +
++// Check if automation-driven tabs must never steal focus. Callers decide per
++// tab by combining this with content::DevToolsAgentHost::IsDebuggerAttached().
++bool AutomationNeverStealsFocus(PrefService* pref_service);
++
 +// Get the visibility pref key for an action, or nullptr if none exists.
 +const char* GetVisibilityPrefForAction(actions::ActionId id);
 +