Skip to content

Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.

refactor: enhance session management and error handling in BrowserSession

reformedot77d7f161fb7b
diff --git a/browser_use/browser/session.py b/browser_use/browser/session.py
index 9995a8622..6aed1e052 100644
--- a/browser_use/browser/session.py
+++ b/browser_use/browser/session.py
@@ -1145,15 +1145,22 @@ class BrowserSession(BaseModel):
ValueError: If target doesn't exist or session is not available.
"""
assert self._cdp_client_root is not None, 'Root CDP client not initialized'
- assert self.agent_focus_target_id is not None, 'Agent focus not initialized'
assert self.session_manager is not None, 'SessionManager not initialized'
- # If no target_id specified, use current agent focus
+ # If no target_id specified, ensure current agent focus is valid and wait for recovery if needed
if target_id is None:
+ # Validate and wait for focus recovery if stale (centralized protection)
+ focus_valid = await self.session_manager.ensure_valid_focus(timeout=5.0)
+ if not focus_valid:
+ raise ValueError(
+ 'No valid agent focus available - target may have detached and recovery failed. '
+ 'This indicates browser is in an unstable state.'
+ )
+
+ assert self.agent_focus_target_id is not None, 'Focus validation passed but agent_focus_target_id is None'
target_id = self.agent_focus_target_id
- # Get session from event-driven pool
- session = self.session_manager.get_session_for_target(target_id)
+ session = self.session_manager._get_session_for_target(target_id)
if not session:
# Session not in pool yet - wait for attach event
@@ -1162,7 +1169,7 @@ class BrowserSession(BaseModel):
# Wait up to 2 seconds for the attach event
for attempt in range(20):
await asyncio.sleep(0.1)
- session = self.session_manager.get_session_for_target(target_id)
+ session = self.session_manager._get_session_for_target(target_id)
if session:
self.logger.debug(f'[SessionManager] Target appeared after {attempt * 100}ms')
break
@@ -1184,14 +1191,17 @@ class BrowserSession(BaseModel):
target_type = target.target_type if target else 'unknown'
if target_type == 'page':
- self.logger.debug(f'[SessionManager] Switching focus: {self.agent_focus_target_id[:8]}... → {target_id[:8]}...')
+ # Format current focus safely (could be None after detach)
+ current_focus = self.agent_focus_target_id[:8] if self.agent_focus_target_id else 'None'
+ self.logger.debug(f'[SessionManager] Switching focus: {current_focus}... → {target_id[:8]}...')
self.agent_focus_target_id = target_id
else:
# Ignore focus request for non-page targets (iframes, workers, etc.)
# These can detach at any time, causing agent_focus to point to dead target
+ current_focus = self.agent_focus_target_id[:8] if self.agent_focus_target_id else 'None'
self.logger.debug(
f'[SessionManager] Ignoring focus request for {target_type} target {target_id[:8]}... '
- f'(agent_focus stays on {self.agent_focus_target_id[:8]}...)'
+ f'(agent_focus stays on {current_focus}...)'
)
# Resume if waiting for debugger
@@ -1456,14 +1466,11 @@ class BrowserSession(BaseModel):
target_id = target.target_id
self.logger.debug(f'🔄 Redirecting {target_url} to about:blank for target {target_id}')
try:
- # Sessions now exist from SessionManager initialization
- session = self.session_manager.get_session_for_target(target_id)
- if session:
- await session.cdp_client.send.Page.navigate(
- params={'url': 'about:blank'}, session_id=session.session_id
- )
- # Update target url
- target.url = 'about:blank'
+ # Use public API with focus=False to avoid changing focus during init
+ session = await self.get_or_create_cdp_session(target_id, focus=False)
+ await session.cdp_client.send.Page.navigate(params={'url': 'about:blank'}, session_id=session.session_id)
+ # Update target url
+ target.url = 'about:blank'
except Exception as e:
self.logger.warning(f'Failed to redirect {target_url}: {e}')
@@ -1476,18 +1483,14 @@ class BrowserSession(BaseModel):
target_id = page_targets_from_manager[0].target_id
self.logger.debug(f'📄 Using existing page: {target_id}')
- # Wait for SessionManager to receive the attach event for this target
- # (SessionManager already attached to existing targets in start_monitoring())
- for _ in range(20): # Wait up to 2 seconds
- await asyncio.sleep(0.1)
- session = self.session_manager.get_session_for_target(target_id)
- if session:
- self.agent_focus_target_id = target_id
- self.logger.debug(f'📄 Agent focus set to {target_id[:8]}...')
- break
-
- if not self.agent_focus_target_id:
- raise RuntimeError(f'Failed to get session for initial target {target_id}')
+ # Set up initial focus using the public API
+ # Note: get_or_create_cdp_session() will wait for attach event and set focus
+ try:
+ await self.get_or_create_cdp_session(target_id, focus=True)
+ # agent_focus_target_id is now set by get_or_create_cdp_session
+ self.logger.debug(f'📄 Agent focus set to {target_id[:8]}...')
+ except ValueError as e:
+ raise RuntimeError(f'Failed to get session for initial target {target_id}: {e}') from e
# Note: Lifecycle monitoring is enabled automatically in SessionManager._handle_target_attached()
# when targets attach, so no manual enablement needed!
@@ -1552,13 +1555,12 @@ class BrowserSession(BaseModel):
# Also enable on the focused target's session if available to ensure events are delivered
try:
if self.agent_focus_target_id:
- cdp_session = self.session_manager.get_session_for_target(self.agent_focus_target_id)
- if cdp_session:
- await cdp_session.cdp_client.send.Fetch.enable(
- params={'handleAuthRequests': True},
- session_id=cdp_session.session_id,
- )
- self.logger.debug('Fetch.enable(handleAuthRequests=True) enabled on focused session')
+ cdp_session = await self.get_or_create_cdp_session(self.agent_focus_target_id, focus=False)
+ await cdp_session.cdp_client.send.Fetch.enable(
+ params={'handleAuthRequests': True},
+ session_id=cdp_session.session_id,
+ )
+ self.logger.debug('Fetch.enable(handleAuthRequests=True) enabled on focused session')
except Exception as e:
self.logger.debug(f'Fetch.enable on focused session failed: {type(e).__name__}: {e}')
@@ -1636,10 +1638,9 @@ class BrowserSession(BaseModel):
self._cdp_client_root.register.Fetch.authRequired(_on_auth_required)
self._cdp_client_root.register.Fetch.requestPaused(_on_request_paused)
if self.agent_focus_target_id:
- cdp_session = self.session_manager.get_session_for_target(self.agent_focus_target_id)
- if cdp_session:
- cdp_session.cdp_client.register.Fetch.authRequired(_on_auth_required)
- cdp_session.cdp_client.register.Fetch.requestPaused(_on_request_paused)
+ cdp_session = await self.get_or_create_cdp_session(self.agent_focus_target_id, focus=False)
+ cdp_session.cdp_client.register.Fetch.authRequired(_on_auth_required)
+ cdp_session.cdp_client.register.Fetch.requestPaused(_on_request_paused)
self.logger.debug('Registered Fetch.authRequired handlers')
except Exception as e:
self.logger.debug(f'Failed to register authRequired handlers: {type(e).__name__}: {e}')
@@ -1674,12 +1675,12 @@ class BrowserSession(BaseModel):
# Ensure Fetch is enabled for the current focused target's session, too
try:
if self.agent_focus_target_id:
- cdp_session = self.session_manager.get_session_for_target(self.agent_focus_target_id)
- if cdp_session:
- await cdp_session.cdp_client.send.Fetch.enable(
- params={'handleAuthRequests': True, 'patterns': [{'urlPattern': '*'}]},
- session_id=cdp_session.session_id,
- )
+ # Use safe API with focus=False to avoid changing focus
+ cdp_session = await self.get_or_create_cdp_session(self.agent_focus_target_id, focus=False)
+ await cdp_session.cdp_client.send.Fetch.enable(
+ params={'handleAuthRequests': True, 'patterns': [{'urlPattern': '*'}]},
+ session_id=cdp_session.session_id,
+ )
except Exception as e:
self.logger.debug(f'Fetch.enable on focused session failed: {type(e).__name__}: {e}')
except Exception as e:
@@ -2710,9 +2711,10 @@ class BrowserSession(BaseModel):
# Set viewport for specific target
cdp_session = await self.get_or_create_cdp_session(target_id, focus=False)
elif self.agent_focus_target_id:
- # Use current focus
- cdp_session = self.session_manager.get_session_for_target(self.agent_focus_target_id)
- if not cdp_session:
+ # Use current focus - use safe API with focus=False to avoid changing focus
+ try:
+ cdp_session = await self.get_or_create_cdp_session(self.agent_focus_target_id, focus=False)
+ except ValueError:
self.logger.warning('Cannot set viewport: focused target has no sessions')
return
else:
@@ -2924,9 +2926,10 @@ class BrowserSession(BaseModel):
# Only process the current focus target
if self.agent_focus_target_id and target_id != self.agent_focus_target_id:
continue
- # Use the existing agent_focus target's session
- cdp_session = self.session_manager.get_session_for_target(self.agent_focus_target_id)
- if not cdp_session:
+ # Use the existing agent_focus target's session - use safe API with focus=False
+ try:
+ cdp_session = await self.get_or_create_cdp_session(self.agent_focus_target_id, focus=False)
+ except ValueError:
continue # Skip if no session available
else:
# Get cached session for this target (don't change focus - iterating frames)
@@ -3158,12 +3161,16 @@ class BrowserSession(BaseModel):
# Strategy 4: Fallback to agent_focus_target_id (the page where agent is currently working)
if self.agent_focus_target_id:
target = self.session_manager.get_target(self.agent_focus_target_id)
- cdp_session = self.session_manager.get_session_for_target(self.agent_focus_target_id)
- if cdp_session and target:
- self.logger.warning(
- f'⚠️ Node {node.backend_node_id} has no session/frame/target info. Using agent_focus session: {target.url}'
- )
+ try:
+ # Use safe API with focus=False to avoid changing focus
+ cdp_session = await self.get_or_create_cdp_session(self.agent_focus_target_id, focus=False)
+ if target:
+ self.logger.warning(
+ f'⚠️ Node {node.backend_node_id} has no session/frame/target info. Using agent_focus session: {target.url}'
+ )
return cdp_session
+ except ValueError:
+ pass # Fall through to last resort
# Last resort: use main session
self.logger.error(f'❌ No session info for node {node.backend_node_id} and no agent_focus available. Using main session.')
diff --git a/browser_use/browser/session_manager.py b/browser_use/browser/session_manager.py
index 2ee01fa75..5e521c9c8 100644
--- a/browser_use/browser/session_manager.py
+++ b/browser_use/browser/session_manager.py
@@ -48,6 +48,11 @@ class SessionManager:
self._lock = asyncio.Lock()
self._recovery_lock = asyncio.Lock()
+ # Focus recovery coordination - event-driven instead of polling
+ self._recovery_in_progress: bool = False
+ self._recovery_complete_event: asyncio.Event | None = None
+ self._recovery_task: asyncio.Task | None = None
+
async def start_monitoring(self) -> None:
"""Start monitoring Target attach/detach events.
@@ -106,8 +111,11 @@ class SessionManager:
# Discover and initialize ALL existing targets
await self._initialize_existing_targets()
- def get_session_for_target(self, target_id: TargetID) -> 'CDPSession | None':
- """Get ANY valid session for a target (picks first available).
+ def _get_session_for_target(self, target_id: TargetID) -> 'CDPSession | None':
+ """Internal: Get ANY valid session for a target (picks first available).
+
+ ⚠️ INTERNAL API - Use browser_session.get_or_create_cdp_session() instead!
+ This method has no validation, no focus management, no recovery.
Args:
target_id: Target ID to get session for
@@ -117,6 +125,25 @@ class SessionManager:
"""
session_ids = self._target_sessions.get(target_id, set())
if not session_ids:
+ # Check if this is the focused target - indicates stale focus that needs cleanup
+ if self.browser_session.agent_focus_target_id == target_id:
+ self.logger.warning(
+ f'[SessionManager] ⚠️ Attempted to get session for stale focused target {target_id[:8]}... '
+ f'Clearing stale focus and triggering recovery.'
+ )
+
+ # Clear stale focus immediately (defense in depth)
+ self.browser_session.agent_focus_target_id = None
+
+ # Trigger recovery if not already in progress
+ if not self._recovery_in_progress:
+ self.logger.warning('[SessionManager] Recovery was not in progress! Triggering now.')
+ self._recovery_task = create_task_with_error_handling(
+ self._recover_agent_focus(target_id),
+ name='recover_agent_focus_from_stale_get',
+ logger_instance=self.logger,
+ suppress_exceptions=False,
+ )
return None
return self._sessions.get(next(iter(session_ids)))
@@ -258,15 +285,86 @@ class SessionManager:
return None
return self.get_target(self.browser_session.agent_focus_target_id)
- def get_focused_session(self) -> 'CDPSession | None':
- """Get a session for the currently focused target.
+ async def ensure_valid_focus(self, timeout: float = 3.0) -> bool:
+ """Ensure agent_focus_target_id points to a valid, attached CDP session.
+
+ If the focus target is stale (detached), this method waits for automatic recovery.
+ Uses event-driven coordination instead of polling for efficiency.
+
+ Args:
+ timeout: Maximum time to wait for recovery in seconds (default: 3.0)
Returns:
- CDPSession for focused target, None if no focus
+ True if focus is valid or successfully recovered, False if no focus or recovery failed
"""
if not self.browser_session.agent_focus_target_id:
- return None
- return self.get_session_for_target(self.browser_session.agent_focus_target_id)
+ # No focus at all - might be initial state or complete failure
+ if self._recovery_in_progress and self._recovery_complete_event:
+ # Recovery is happening, wait for it
+ try:
+ await asyncio.wait_for(self._recovery_complete_event.wait(), timeout=timeout)
+ # Check again after recovery - simple existence check
+ focus_id = self.browser_session.agent_focus_target_id
+ return bool(focus_id and self._get_session_for_target(focus_id))
+ except TimeoutError:
+ self.logger.error(f'[SessionManager] ❌ Timed out waiting for recovery after {timeout}s')
+ return False
+ return False
+
+ # Simple existence check - does the focused target have a session?
+ cdp_session = self._get_session_for_target(self.browser_session.agent_focus_target_id)
+ if cdp_session:
+ # Session exists - validate it's still active
+ is_valid = await self.validate_session(self.browser_session.agent_focus_target_id)
+ if is_valid:
+ return True
+
+ # Focus is stale - wait for recovery using event instead of polling
+ stale_target_id = self.browser_session.agent_focus_target_id
+ self.logger.warning(
+ f'[SessionManager] ⚠️ Stale agent_focus detected (target {stale_target_id[:8] if stale_target_id else "None"}... detached), '
+ f'waiting for recovery...'
+ )
+
+ # Check if recovery is already in progress
+ if not self._recovery_in_progress:
+ self.logger.warning(
+ '[SessionManager] ⚠️ Recovery not in progress for stale focus! '
+ 'This indicates a bug - recovery should have been triggered.'
+ )
+ return False
+
+ # Wait for recovery complete event (event-driven, not polling!)
+ if self._recovery_complete_event:
+ try:
+ start_time = asyncio.get_event_loop().time()
+ await asyncio.wait_for(self._recovery_complete_event.wait(), timeout=timeout)
+ elapsed = asyncio.get_event_loop().time() - start_time
+
+ # Verify recovery succeeded - simple existence check
+ focus_id = self.browser_session.agent_focus_target_id
+ if focus_id and self._get_session_for_target(focus_id):
+ self.logger.info(
+ f'[SessionManager] ✅ Agent focus recovered to {self.browser_session.agent_focus_target_id[:8]}... '
+ f'after {elapsed * 1000:.0f}ms'
+ )
+ return True
+ else:
+ self.logger.error(
+ f'[SessionManager] ❌ Recovery completed but focus still invalid after {elapsed * 1000:.0f}ms'
+ )
+ return False
+
+ except TimeoutError:
+ self.logger.error(
+ f'[SessionManager] ❌ Recovery timed out after {timeout}s '
+ f'(was: {stale_target_id[:8] if stale_target_id else "None"}..., '
+ f'now: {self.browser_session.agent_focus_target_id[:8] if self.browser_session.agent_focus_target_id else "None"})'
+ )
+ return False
+ else:
+ self.logger.error('[SessionManager] ❌ Recovery event not initialized')
+ return False
async def _handle_target_attached(self, event: AttachedToTargetEvent) -> None:
"""Handle Target.attachedToTarget event.
@@ -417,6 +515,18 @@ class SessionManager:
# Check if agent_focus points to this target
agent_focus_lost = self.browser_session.agent_focus_target_id == target_id
+ # Immediately clear stale focus to prevent operations on detached target
+ if agent_focus_lost:
+ self.logger.debug(
+ f'[SessionManager] Clearing stale agent_focus_target_id {target_id[:8]}... '
+ f'to prevent operations on detached target'
+ )
+ self.browser_session.agent_focus_target_id = None
+
+ # Get target type before removing (needed for TabClosedEvent dispatch)
+ target = self._targets.get(target_id)
+ target_type = target.target_type if target else None
+
# Remove target (entity) from owned data
if target_id in self._targets:
self._targets.pop(target_id)
@@ -433,10 +543,6 @@ class SessionManager:
f'session={session_id[:8]}... (target was already removed or attach event was missed)'
)
- # Get target type before cleaning up (needed for TabClosedEvent dispatch)
- target = self._targets.get(target_id)
- target_type = target.target_type if target else None
-
# Remove session from owned sessions dict
if session_id in self._sessions:
self._sessions.pop(session_id)
@@ -462,32 +568,63 @@ class SessionManager:
# Auto-recover agent_focus outside the lock to avoid blocking other operations
if agent_focus_lost:
- await self._recover_agent_focus(target_id)
+ # Create recovery task instead of awaiting directly - allows concurrent operations to wait on same recovery
+ if not self._recovery_in_progress:
+ self._recovery_task = create_task_with_error_handling(
+ self._recover_agent_focus(target_id),
+ name='recover_agent_focus',
+ logger_instance=self.logger,
+ suppress_exceptions=False,
+ )
async def _recover_agent_focus(self, crashed_target_id: TargetID) -> None:
"""Auto-recover agent_focus when the focused target crashes/detaches.
Uses recovery lock to prevent concurrent recovery attempts from creating multiple emergency tabs.
+ Coordinates with ensure_valid_focus() via events for efficient waiting.
Args:
crashed_target_id: The target ID that was lost
"""
- # Prevent concurrent recovery attempts
- async with self._recovery_lock:
- # Check if another recovery already fixed agent_focus
- if self.browser_session.agent_focus_target_id and self.browser_session.agent_focus_target_id != crashed_target_id:
- self.logger.debug(
- f'[SessionManager] Agent focus already recovered by concurrent operation '
- f'(now: {self.browser_session.agent_focus_target_id[:8]}...), skipping recovery'
+ try:
+ # Prevent concurrent recovery attempts
+ async with self._recovery_lock:
+ # Set recovery state INSIDE lock to prevent race conditions
+ if self._recovery_in_progress:
+ self.logger.debug('[SessionManager] Recovery already in progress, waiting for it to complete')
+ # Wait for ongoing recovery instead of starting a new one
+ if self._recovery_complete_event:
+ try:
+ await asyncio.wait_for(self._recovery_complete_event.wait(), timeout=5.0)
+ except TimeoutError:
+ self.logger.error('[SessionManager] Timed out waiting for ongoing recovery')
+ return
+
+ # Set recovery state
+ self._recovery_in_progress = True
+ self._recovery_complete_event = asyncio.Event()
+
+ # Check if another recovery already fixed agent_focus
+ if self.browser_session.agent_focus_target_id and self.browser_session.agent_focus_target_id != crashed_target_id:
+ self.logger.debug(
+ f'[SessionManager] Agent focus already recovered by concurrent operation '
+ f'(now: {self.browser_session.agent_focus_target_id[:8]}...), skipping recovery'
+ )
+ return
+
+ # Note: agent_focus_target_id may already be None (cleared in _handle_target_detached)
+ current_focus_desc = (
+ f'{self.browser_session.agent_focus_target_id[:8]}...'
+ if self.browser_session.agent_focus_target_id
+ else 'None (already cleared)'
)
- return
- self.logger.warning(
- f'[SessionManager] Agent focus target {crashed_target_id[:8]}... detached! '
- f'Auto-recovering by switching to another target...'
- )
+ self.logger.warning(
+ f'[SessionManager] Agent focus target {crashed_target_id[:8]}... detached! '
+ f'Current focus: {current_focus_desc}. Auto-recovering by switching to another target...'
+ )
- try:
+ # Perform recovery (outside lock to allow concurrent operations)
# Try to find another valid page target
page_targets = self.get_all_page_targets()
@@ -510,11 +647,13 @@ class SessionManager:
self.browser_session.event_bus.dispatch(TabCreatedEvent(url='about:blank', target_id=new_target_id))
- # Wait for attach event to create session, then update agent_focus
+ # Wait for CDP attach event to create session
+ # Note: This polling is necessary - waiting for external Chrome CDP event
+ # _handle_target_attached will add session to pool when Chrome fires attachedToTarget
new_session = None
for attempt in range(20): # Wait up to 2 seconds
await asyncio.sleep(0.1)
- new_session = self.get_session_for_target(new_target_id)
+ new_session = self._get_session_for_target(new_target_id)
if new_session:
break
@@ -550,9 +689,10 @@ class SessionManager:
self.logger.warning(f'[SessionManager] Created emergency fallback tab {fallback_target_id[:8]}...')
# Try one more time with fallback
+ # Note: This polling is necessary - waiting for external Chrome CDP event
for _ in range(20):
await asyncio.sleep(0.1)
- fallback_session = self.get_session_for_target(fallback_target_id)
+ fallback_session = self._get_session_for_target(fallback_target_id)
if fallback_session:
self.browser_session.agent_focus_target_id = fallback_target_id
self.logger.warning(f'[SessionManager] ⚠️ Agent focus set to emergency fallback: {fallback_target_id[:8]}...')
@@ -572,6 +712,14 @@ class SessionManager:
except Exception as e:
self.logger.error(f'[SessionManager] ❌ Error during agent_focus recovery: {type(e).__name__}: {e}')
+ finally:
+ # Always signal completion and reset recovery state
+ # This allows all waiting operations to proceed (success or failure)
+ if self._recovery_complete_event:
+ self._recovery_complete_event.set()
+ self._recovery_in_progress = False
+ self._recovery_task = None
+ self.logger.debug('[SessionManager] Recovery state reset')
async def _initialize_existing_targets(self) -> None:
"""Discover and initialize all existing targets at startup.
@@ -618,7 +766,7 @@ class SessionManager:
while True:
ready_count = 0
for tid in target_ids_to_wait_for:
- session = self.get_session_for_target(tid)
+ session = self._get_session_for_target(tid)
if session:
target = self._targets.get(tid)
target_type = target.target_type if target else 'unknown'
@@ -648,7 +796,7 @@ class SessionManager:
# Timeout - count what's ready
ready_count = 0
for tid in target_ids_to_wait_for:
- session = self.get_session_for_target(tid)
+ session = self._get_session_for_target(tid)
if session:
target = self._targets.get(tid)
target_type = target.target_type if target else 'unknown'
diff --git a/browser_use/browser/watchdogs/default_action_watchdog.py b/browser_use/browser/watchdogs/default_action_watchdog.py
index 849f3b601..2a6050b06 100644
--- a/browser_use/browser/watchdogs/default_action_watchdog.py
+++ b/browser_use/browser/watchdogs/default_action_watchdog.py
@@ -1630,12 +1630,8 @@ class DefaultActionWatchdog(BaseWatchdog):
True if successful, False if failed
"""
try:
- # Get CDP client and session
- assert self.browser_session.agent_focus_target_id is not None, (
- 'CDP session not initialized - browser may not be connected yet'
- )
- cdp_session = self.browser_session.session_manager.get_focused_session()
- assert cdp_session is not None, 'No session for focused target'
+ # Get focused CDP session using public API (validates and waits for recovery if needed)
+ cdp_session = await self.browser_session.get_or_create_cdp_session()
cdp_client = cdp_session.cdp_client
session_id = cdp_session.session_id
@@ -1779,12 +1775,8 @@ class DefaultActionWatchdog(BaseWatchdog):
except Exception as e:
self.logger.debug(f'Error getting frame session: {e}, using main session')
- # Use main target session
- assert self.browser_session.agent_focus_target_id is not None, (
- 'CDP session not initialized - browser may not be connected yet'
- )
- cdp_session = self.browser_session.session_manager.get_focused_session()
- assert cdp_session is not None, 'No session for focused target'
+ # Use main target session - get_or_create_cdp_session validates focus automatically
+ cdp_session = await self.browser_session.get_or_create_cdp_session()
return cdp_session.session_id
async def on_GoBackEvent(self, event: GoBackEvent) -> None:
@@ -2107,12 +2099,9 @@ class DefaultActionWatchdog(BaseWatchdog):
# TODO: handle looking for text inside cross-origin iframes as well
- # Get CDP client and session
- cdp_client = self.browser_session.cdp_client
- if self.browser_session.agent_focus_target_id is None:
- raise BrowserError('CDP session not initialized - browser may not be connected yet')
- cdp_session = self.browser_session.session_manager.get_focused_session()
- assert cdp_session is not None, 'No session for focused target'
+ # Get focused CDP session using public API (validates and waits for recovery if needed)
+ cdp_session = await self.browser_session.get_or_create_cdp_session()
+ cdp_client = cdp_session.cdp_client
session_id = cdp_session.session_id
# Enable DOM
diff --git a/browser_use/browser/watchdogs/dom_watchdog.py b/browser_use/browser/watchdogs/dom_watchdog.py
index 40612112e..2127ceab0 100644
--- a/browser_use/browser/watchdogs/dom_watchdog.py
+++ b/browser_use/browser/watchdogs/dom_watchdog.py
@@ -100,9 +100,7 @@ class DOMWatchdog(BaseWatchdog):
from browser_use.browser.views import NetworkRequest
try:
- if not self.browser_session.agent_focus_target_id:
- return []
-
+ # get_or_create_cdp_session() now handles focus validation automatically
cdp_session = await self.browser_session.get_or_create_cdp_session(focus=True)
# Use performance API to get pending requests
@@ -257,14 +255,10 @@ class DOMWatchdog(BaseWatchdog):
self.logger.debug('🔍 DOMWatchdog.on_BrowserStateRequestEvent: STARTING browser state request')
page_url = await self.browser_session.get_current_page_url()
self.logger.debug(f'🔍 DOMWatchdog.on_BrowserStateRequestEvent: Got page URL: {page_url}')
+
+ # Get focused session for logging (validation already done by get_current_page_url)
if self.browser_session.agent_focus_target_id:
- cdp_session = self.browser_session.session_manager.get_focused_session()
- session_id = cdp_session.session_id if cdp_session else 'unknown'
- self.logger.debug(
- f'Current page URL: {page_url}, target_id: {self.browser_session.agent_focus_target_id}, session_id: {session_id}'
- )
- else:
- self.logger.debug(f'Current page URL: {page_url}, no cdp_session attached')
+ self.logger.debug(f'Current page URL: {page_url}, target_id: {self.browser_session.agent_focus_target_id}')
# check if we should skip DOM tree build for pointless pages
not_a_meaningful_website = page_url.lower().split(':', 1)[0] not in ('http', 'https')
@@ -679,8 +673,6 @@ class DOMWatchdog(BaseWatchdog):
try:
self.logger.debug('🔍 DOMWatchdog._capture_clean_screenshot: Capturing clean screenshot...')
- # Ensure we have a focused CDP session
- assert self.browser_session.agent_focus_target_id is not None, 'No current target ID'
await self.browser_session.get_or_create_cdp_session(target_id=self.browser_session.agent_focus_target_id, focus=True)
# Check if handler is registered
@@ -754,10 +746,7 @@ class DOMWatchdog(BaseWatchdog):
from browser_use.browser.views import PageInfo
- # Get CDP session for the current target
- if not self.browser_session.agent_focus_target_id:
- raise RuntimeError('No active CDP session - browser may not be connected yet')
-
+ # get_or_create_cdp_session() handles focus validation automatically
cdp_session = await self.browser_session.get_or_create_cdp_session(
target_id=self.browser_session.agent_focus_target_id, focus=True
)
diff --git a/browser_use/browser/watchdogs/downloads_watchdog.py b/browser_use/browser/watchdogs/downloads_watchdog.py
index 87a0e2f3a..21ee583a6 100644
--- a/browser_use/browser/watchdogs/downloads_watchdog.py
+++ b/browser_use/browser/watchdogs/downloads_watchdog.py
@@ -91,9 +91,11 @@ class DownloadsWatchdog(BaseWatchdog):
async def on_BrowserStateRequestEvent(self, event: BrowserStateRequestEvent) -> None:
"""Handle browser state request events."""
- cdp_session = self.browser_session.session_manager.get_focused_session()
- if not cdp_session:
- return
+ # Use public API - automatically validates and waits for recovery if needed
+ try:
+ cdp_session = await self.browser_session.get_or_create_cdp_session()
+ except ValueError:
+ return # No valid focus, skip
url = await self.browser_session.get_current_page_url()
if not url:
@@ -955,9 +957,11 @@ class DownloadsWatchdog(BaseWatchdog):
"""
self.logger.debug(f'[DownloadsWatchdog] Checking if target {target_id} is PDF viewer...')
- session = self.browser_session.session_manager.get_session_for_target(target_id)
- if not session:
- self.logger.warning(f'[DownloadsWatchdog] No session found for {target_id}')
+ # Use safe API - focus=False to avoid changing focus during PDF check
+ try:
+ session = await self.browser_session.get_or_create_cdp_session(target_id, focus=False)
+ except ValueError as e:
+ self.logger.warning(f'[DownloadsWatchdog] No session found for {target_id}: {e}')
return False
# Get URL from target
diff --git a/browser_use/browser/watchdogs/popups_watchdog.py b/browser_use/browser/watchdogs/popups_watchdog.py
index b7ef5442c..50986e2f3 100644
--- a/browser_use/browser/watchdogs/popups_watchdog.py
+++ b/browser_use/browser/watchdogs/popups_watchdog.py
@@ -102,18 +102,20 @@ class PopupsWatchdog(BaseWatchdog):
# Approach 2: Try with current agent focus session
if not dismissed and self.browser_session._cdp_client_root and self.browser_session.agent_focus_target_id:
try:
- cdp_session = self.browser_session.session_manager.get_focused_session()
- if cdp_session:
- self.logger.debug(f'🔄 Approach 2: Using agent focus session {cdp_session.session_id[-8:]}')
- await asyncio.wait_for(
- self.browser_session._cdp_client_root.send.Page.handleJavaScriptDialog(
- params={'accept': should_accept},
- session_id=cdp_session.session_id,
- ),
- timeout=0.5,
- )
- dismissed = True
- self.logger.info('✅ Dialog handled successfully via agent focus session')
+ # Use public API with focus=False to avoid changing focus during popup dismissal
+ cdp_session = await self.browser_session.get_or_create_cdp_session(
+ self.browser_session.agent_focus_target_id, focus=False
+ )
+ self.logger.debug(f'🔄 Approach 2: Using agent focus session {cdp_session.session_id[-8:]}')
+ await asyncio.wait_for(
+ self.browser_session._cdp_client_root.send.Page.handleJavaScriptDialog(
+ params={'accept': should_accept},
+ session_id=cdp_session.session_id,
+ ),
+ timeout=0.5,
+ )
+ dismissed = True
+ self.logger.info('✅ Dialog handled successfully via agent focus session')
except (TimeoutError, Exception) as e:
self.logger.debug(f'Approach 2 failed: {type(e).__name__}')
diff --git a/browser_use/dom/service.py b/browser_use/dom/service.py
index 2b7365c7d..843749b0c 100644
--- a/browser_use/dom/service.py
+++ b/browser_use/dom/service.py
@@ -534,8 +534,12 @@ class DomService:
height=snapshot_data.bounds.height,
)
- session = self.browser_session.session_manager.get_session_for_target(target_id)
- session_id = session.session_id if session else None
+ try:
+ session = await self.browser_session.get_or_create_cdp_session(target_id, focus=False)
+ session_id = session.session_id
+ except ValueError:
+ # Target may have detached during DOM construction
+ session_id = None
dom_tree_node = EnhancedDOMTreeNode(
node_id=node['nodeId'],
diff --git a/browser_use/utils.py b/browser_use/utils.py
index bc36f0990..4a5602997 100644
--- a/browser_use/utils.py
+++ b/browser_use/utils.py
@@ -684,14 +684,20 @@ def create_task_with_error_handling(
coro: The coroutine to wrap in a task
name: Optional name for the task (useful for debugging)
logger_instance: Optional logger instance to use. If None, uses module logger.
- suppress_exceptions: If True, exceptions are only logged and not re-raised. Default False.
+ suppress_exceptions: If True, logs exceptions at ERROR level. If False, logs at WARNING level
+ and exceptions remain retrievable via task.exception() if the caller awaits the task.
+ Default False.
Returns:
asyncio.Task: The created task with exception handling callback
Example:
- # Instead of: asyncio.create_task(some_async_function())
- # Use: create_task_with_error_handling(some_async_function(), name="my_task")
+ # Fire-and-forget with suppressed exceptions
+ create_task_with_error_handling(some_async_function(), name="my_task", suppress_exceptions=True)
+
+ # Task with retrievable exceptions (if you plan to await it)
+ task = create_task_with_error_handling(critical_function(), name="critical")
+ result = await task # Will raise the exception if one occurred
"""
task = asyncio.create_task(coro, name=name)
log = logger_instance or logger
@@ -703,16 +709,20 @@ def create_task_with_error_handling(
exc = t.exception()
if exc is not None:
task_name = t.get_name() if hasattr(t, 'get_name') else 'unnamed'
- log.error(f'Exception in background task [{task_name}]: {type(exc).__name__}: {exc}', exc_info=exc)
-
- # Re-raise if not suppressed (useful for critical tasks)
- if not suppress_exceptions:
- raise exc
+ if suppress_exceptions:
+ log.error(f'Exception in background task [{task_name}]: {type(exc).__name__}: {exc}', exc_info=exc)
+ else:
+ # Log at warning level when not suppressed - exception remains retrievable via task.exception()
+ log.warning(
+ f'Exception in background task [{task_name}]: {type(exc).__name__}: {exc} '
+ f'(exception retrievable via task.exception() if awaited)',
+ exc_info=exc,
+ )
except asyncio.CancelledError:
# Task was cancelled, this is normal behavior
pass
except Exception as e:
- # Catch any other exception during exception handling
+ # Catch any other exception during exception handling (e.g., t.exception() itself failing)
task_name = t.get_name() if hasattr(t, 'get_name') else 'unnamed'
log.error(f'Error handling exception in task [{task_name}]: {type(e).__name__}: {e}')