Skip to content

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

fix: improved session manager

reformedot027fae6c23e6
diff --git a/browser_use/browser/session.py b/browser_use/browser/session.py
index d1b062f99..677414f07 100644
--- a/browser_use/browser/session.py
+++ b/browser_use/browser/session.py
@@ -71,6 +71,10 @@ class CDPSession(BaseModel):
title: str = 'Unknown title'
url: str = 'about:blank'
+ # Lifecycle monitoring (populated by SessionManager)
+ _lifecycle_events: Any = PrivateAttr(default=None)
+ _lifecycle_lock: Any = PrivateAttr(default=None)
+
@classmethod
async def for_target(
cls,
@@ -809,44 +813,13 @@ class BrowserSession(BaseModel):
2. load - Fallback when page has ongoing network activity (all resources loaded)
This gives us instant returns for cached content while being robust for dynamic pages.
+
+ NO handler registration here - handlers are registered ONCE per session in SessionManager.
+ We poll stored events instead to avoid handler accumulation.
"""
cdp_session = await self.get_or_create_cdp_session(target_id, focus=False)
- # Track readiness signals
- ready = asyncio.Event()
- navigation_id = None
- readiness_reason = None
- seen_events = [] # Debug: track all lifecycle events
-
- # Listen to lifecycle events (already enabled globally by SessionManager)
- def on_lifecycle_event(event, session_id=None):
- nonlocal readiness_reason
- if session_id != cdp_session.session_id:
- return
-
- event_name = event.get('name')
- event_loader_id = event.get('loaderId')
-
- # Debug: track all events we see
- seen_events.append(f'{event_name}(loader={event_loader_id[:8] if event_loader_id else "none"})')
-
- # Only respond to events from our navigation (or accept all if no loaderId)
- if event_loader_id and navigation_id and event_loader_id != navigation_id:
- return
-
- # networkIdle - fastest signal when no network requests for ~500ms (great for cache!)
- if event_name == 'networkIdle' and not ready.is_set():
- readiness_reason = 'networkIdle'
- ready.set()
- # load - robust fallback when page has resources loading
- elif event_name == 'load' and not ready.is_set():
- readiness_reason = 'load'
- ready.set()
-
- # Register lifecycle listener (SessionManager enabled these events globally)
- cdp_session.cdp_client.register.Page.lifecycleEvent(on_lifecycle_event)
-
- # Start navigation
+ # Start navigation first
nav_result = await cdp_session.cdp_client.send.Page.navigate(
params={'url': url, 'transitionType': 'address_bar'},
session_id=cdp_session.session_id,
@@ -858,15 +831,67 @@ class BrowserSession(BaseModel):
# Track this specific navigation
navigation_id = nav_result.get('loaderId')
+ start_time = asyncio.get_event_loop().time()
self.logger.debug(
f'[_navigate_and_wait] Started navigation to {url} (loaderId={navigation_id[:8] if navigation_id else "none"})'
)
- # Wait for either networkIdle (fast) or load (fallback)
- try:
- await asyncio.wait_for(ready.wait(), timeout=timeout)
- self.logger.debug(f'✅ Page ready for {url} (signal: {readiness_reason}, saw events: {seen_events})')
- except (TimeoutError, asyncio.TimeoutError):
+ # Poll stored lifecycle events (handler registered once in SessionManager)
+ readiness_reason = None
+ seen_events = [] # Debug: track all lifecycle events we see
+
+ # Check if session has lifecycle monitoring enabled
+ if not hasattr(cdp_session, '_lifecycle_events'):
+ raise RuntimeError(
+ f'❌ Lifecycle monitoring not enabled for {cdp_session.target_id[:8]}! '
+ f'This is a bug - SessionManager should have initialized it. '
+ f'Session: {cdp_session}'
+ )
+
+ # Poll for lifecycle events until timeout
+ poll_interval = 0.05 # Poll every 50ms
+ while (asyncio.get_event_loop().time() - start_time) < timeout:
+ # Check stored events (populated by handler in SessionManager)
+ try:
+ # Get recent events matching our navigation
+ for event_data in list(cdp_session._lifecycle_events):
+ event_name = event_data.get('name')
+ event_loader_id = event_data.get('loaderId')
+
+ # Debug: track events
+ event_str = f'{event_name}(loader={event_loader_id[:8] if event_loader_id else "none"})'
+ if event_str not in seen_events:
+ seen_events.append(event_str)
+
+ # Only respond to events from our navigation (or accept all if no loaderId)
+ if event_loader_id and navigation_id and event_loader_id != navigation_id:
+ continue
+
+ # networkIdle - fastest signal when no network requests for ~500ms (great for cache!)
+ if event_name == 'networkIdle':
+ readiness_reason = 'networkIdle'
+ self.logger.debug(f'✅ Page ready for {url} (signal: {readiness_reason}, saw events: {seen_events})')
+ return
+ # load - robust fallback when page has resources loading
+ elif event_name == 'load':
+ readiness_reason = 'load'
+ self.logger.debug(f'✅ Page ready for {url} (signal: {readiness_reason}, saw events: {seen_events})')
+ return
+
+ except Exception as e:
+ self.logger.debug(f'Error polling lifecycle events: {e}')
+
+ # Wait before next poll
+ await asyncio.sleep(poll_interval)
+
+ # Timeout - continue anyway with detailed diagnostics
+ if not seen_events:
+ self.logger.error(
+ f'❌ No lifecycle events received for {url}! '
+ f'Monitoring may have failed. Target: {cdp_session.target_id[:8]}, '
+ f'LoaderId: {navigation_id[:8] if navigation_id else "none"}'
+ )
+ else:
self.logger.warning(
f'⚠️ Page readiness timeout ({timeout}s) for {url}, continuing anyway. '
f'LoaderId={navigation_id[:8] if navigation_id else "none"}, saw events: {seen_events}'
@@ -1500,6 +1525,11 @@ class BrowserSession(BaseModel):
await self._cdp_client_root.start()
# Initialize event-driven session manager FIRST (before enabling autoAttach)
+ # SessionManager will:
+ # 1. Register attach/detach event handlers
+ # 2. Discover and attach to all existing targets
+ # 3. Initialize sessions and enable lifecycle monitoring
+ # 4. Enable autoAttach for future targets
from browser_use.browser.session_manager import SessionManager
self._session_manager = SessionManager(self)
@@ -1516,30 +1546,6 @@ class BrowserSession(BaseModel):
# Get browser targets to find available contexts/pages
targets = await self._cdp_client_root.send.Target.getTargets()
- # Manually attach to ALL EXISTING targets (autoAttach only fires for new ones)
- # We attach to everything (pages, iframes, workers) for complete coverage
- for target in targets['targetInfos']:
- target_id = target['targetId']
- target_type = target.get('type', 'unknown')
-
- try:
- # Attach to target - this triggers attachedToTarget event
- result = await self._cdp_client_root.send.Target.attachToTarget(
- params={'targetId': target_id, 'flatten': True}
- )
- session_id = result['sessionId']
-
- # Enable auto-attach for this target's children
- await self._cdp_client_root.send.Target.setAutoAttach(
- params={'autoAttach': True, 'waitForDebuggerOnStart': False, 'flatten': True}, session_id=session_id
- )
-
- self.logger.debug(
- f'Attached to existing target: {target_id[:8]}... (type={target_type}, session={session_id[:8]}...)'
- )
- except Exception as e:
- self.logger.debug(f'Failed to attach to existing target {target_id[:8]}... (type={target_type}): {e}')
-
# Find main browser pages (avoiding iframes, workers, extensions, etc.)
page_targets: list[TargetInfo] = [
t
@@ -1558,14 +1564,13 @@ class BrowserSession(BaseModel):
target_id = target['targetId']
self.logger.debug(f'🔄 Redirecting {target_url} to about:blank for target {target_id}')
try:
- # Sessions now exist from manual attachment above
+ # Sessions now exist from SessionManager initialization
session = await 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
)
target['url'] = 'about:blank'
- await asyncio.sleep(0.05) # Let navigation start
except Exception as e:
self.logger.warning(f'Failed to redirect {target_url}: {e}')
@@ -1579,27 +1584,20 @@ class BrowserSession(BaseModel):
self.logger.debug(f'📄 Using existing page: {target_id}')
# Wait for SessionManager to receive the attach event for this target
- # (Chrome will fire Target.attachedToTarget event which SessionManager handles)
+ # (SessionManager already attached to existing targets in start_monitoring())
for _ in range(20): # Wait up to 2 seconds
await asyncio.sleep(0.1)
session = await self._session_manager.get_session_for_target(target_id)
if session:
self.agent_focus = session
- # SessionManager already added it to pool - no need to do it manually
self.logger.debug(f'📄 Agent focus set to {target_id[:8]}...')
break
if not self.agent_focus:
raise RuntimeError(f'Failed to get session for initial target {target_id}')
- # Enable lifecycle events for all existing page sessions now that pool is populated
- # This ensures pages created BEFORE SessionManager started get monitoring enabled
- for tid, cdp_session in list(self._cdp_session_pool.items()):
- target_info = await self._cdp_client_root.send.Target.getTargetInfo(params={'targetId': tid})
- target_type = target_info.get('targetInfo', {}).get('type', 'unknown')
- if target_type in ('page', 'tab'):
- self.logger.debug(f'[connect] Enabling lifecycle monitoring for existing page {tid[:8]}...')
- asyncio.create_task(self._session_manager._enable_page_monitoring(cdp_session))
+ # Note: Lifecycle monitoring is enabled automatically in SessionManager._handle_target_attached()
+ # when targets attach, so no manual enablement needed!
# Enable proxy authentication handling if configured
await self._setup_proxy_auth()
diff --git a/browser_use/browser/session_manager.py b/browser_use/browser/session_manager.py
index df1e5d5ad..8bf2671db 100644
--- a/browser_use/browser/session_manager.py
+++ b/browser_use/browser/session_manager.py
@@ -48,6 +48,7 @@ class SessionManager:
"""Start monitoring Target attach/detach events.
Registers CDP event handlers to keep the session pool synchronized with browser state.
+ Also discovers and initializes all existing targets on startup.
"""
if not self.browser_session._cdp_client_root:
raise RuntimeError('CDP client not initialized')
@@ -55,38 +56,13 @@ class SessionManager:
# Capture cdp_client_root in closure to avoid type errors
cdp_client = self.browser_session._cdp_client_root
- # Enable lifecycle events for ALL existing page sessions in the pool
- for target_id, cdp_session in list(self.browser_session._cdp_session_pool.items()):
- target_type = self._target_types.get(target_id, 'unknown')
- if target_type in ('page', 'tab'):
- self.logger.debug(f'[SessionManager] Enabling monitoring for existing page {target_id[:8]}...')
- asyncio.create_task(self._enable_page_monitoring(cdp_session))
-
# Register synchronous event handlers (CDP requirement)
def on_attached(event: AttachedToTargetEvent, session_id: SessionID | None = None):
- event_session_id = event['sessionId']
- target_type = event['targetInfo'].get('type', 'unknown')
-
- # Enable auto-attach for this session's children
- async def _enable_auto_attach():
- try:
- await cdp_client.send.Target.setAutoAttach(
- params={'autoAttach': True, 'waitForDebuggerOnStart': False, 'flatten': True}, session_id=event_session_id
- )
- self.logger.debug(f'[SessionManager] Auto-attach enabled for {target_type} session {event_session_id[:8]}...')
- except Exception as e:
- error_str = str(e)
- # Expected for short-lived targets (workers, temp iframes) that detach before task executes
- if '-32001' in error_str or 'Session with given id not found' in error_str:
- self.logger.debug(
- f'[SessionManager] Auto-attach skipped for {target_type} session {event_session_id[:8]}... '
- f'(already detached - normal for short-lived targets)'
- )
- else:
- self.logger.debug(f'[SessionManager] Auto-attach failed for {target_type}: {e}')
-
- # Schedule auto-attach and pool management
- asyncio.create_task(_enable_auto_attach())
+ # _handle_target_attached() handles:
+ # - setAutoAttach for children
+ # - Create CDPSession
+ # - Enable monitoring (for pages/tabs)
+ # - Add to pool
asyncio.create_task(self._handle_target_attached(event))
def on_detached(event: DetachedFromTargetEvent, session_id: SessionID | None = None):
@@ -97,6 +73,9 @@ class SessionManager:
self.logger.debug('[SessionManager] Event monitoring started')
+ # Discover and initialize ALL existing targets
+ await self._initialize_existing_targets()
+
async def get_session_for_target(self, target_id: TargetID) -> 'CDPSession | None':
"""Get the current valid session for a target.
@@ -163,6 +142,24 @@ class SessionManager:
f'type={target_type}, waitingForDebugger={waiting_for_debugger})'
)
+ # Enable auto-attach for this session's children (do this FIRST, outside lock)
+ assert self.browser_session._cdp_client_root is not None, 'Root CDP client required'
+ try:
+ await self.browser_session._cdp_client_root.send.Target.setAutoAttach(
+ params={'autoAttach': True, 'waitForDebuggerOnStart': False, 'flatten': True}, session_id=session_id
+ )
+ self.logger.debug(f'[SessionManager] Auto-attach enabled for {target_type} session {session_id[:8]}...')
+ except Exception as e:
+ error_str = str(e)
+ # Expected for short-lived targets (workers, temp iframes) that detach before this executes
+ if '-32001' in error_str or 'Session with given id not found' in error_str:
+ self.logger.debug(
+ f'[SessionManager] Auto-attach skipped for {target_type} session {session_id[:8]}... '
+ f'(already detached - normal for short-lived targets)'
+ )
+ else:
+ self.logger.debug(f'[SessionManager] Auto-attach failed for {target_type}: {e}')
+
async with self._lock:
# Track this session for the target
if target_id not in self._target_sessions:
@@ -198,7 +195,7 @@ class SessionManager:
# Enable lifecycle events and network monitoring for page targets
if target_type in ('page', 'tab'):
- asyncio.create_task(self._enable_page_monitoring(cdp_session))
+ await self._enable_page_monitoring(cdp_session)
else:
# Update existing session with new session_id
existing = self.browser_session._cdp_session_pool[target_id]
@@ -409,10 +406,72 @@ class SessionManager:
except Exception as e:
self.logger.error(f'[SessionManager] ❌ Error during agent_focus recovery: {type(e).__name__}: {e}')
+ async def _initialize_existing_targets(self) -> None:
+ """Discover and initialize all existing targets at startup.
+
+ Attaches to all existing targets. Chrome fires attachedToTarget events which the
+ on_attached handler processes via create_task(). We wait for all sessions to appear
+ in the pool to ensure initialization is complete before returning.
+ """
+ cdp_client = self.browser_session._cdp_client_root
+ assert cdp_client is not None
+
+ # Get all existing targets
+ targets_result = await cdp_client.send.Target.getTargets()
+ existing_targets = targets_result.get('targetInfos', [])
+
+ self.logger.debug(f'[SessionManager] Discovered {len(existing_targets)} existing targets')
+
+ # Track target IDs we're attaching to
+ target_ids_to_initialize = []
+
+ # Attach to ALL existing targets - this triggers attachedToTarget events
+ for target in existing_targets:
+ target_id = target['targetId']
+ target_type = target.get('type', 'unknown')
+
+ try:
+ # Just attach - the on_attached handler does the rest via create_task()
+ await cdp_client.send.Target.attachToTarget(params={'targetId': target_id, 'flatten': True})
+ target_ids_to_initialize.append(target_id)
+ self.logger.debug(f'[SessionManager] Attached to existing target: {target_id[:8]}... (type={target_type})')
+ except Exception as e:
+ self.logger.debug(
+ f'[SessionManager] Failed to attach to existing target {target_id[:8]}... (type={target_type}): {e}'
+ )
+
+ # Wait for all attach handlers to complete by polling for sessions in pool
+ # This is more reliable than sleep - we wait exactly as long as needed
+ max_wait = 2.0 # 2 seconds max - most targets initialize in < 500ms
+ start_time = asyncio.get_event_loop().time()
+
+ while (asyncio.get_event_loop().time() - start_time) < max_wait:
+ # Check if all target sessions are in pool
+ session_checks = []
+ for tid in target_ids_to_initialize:
+ session = await self.get_session_for_target(tid)
+ session_checks.append(session is not None)
+
+ if all(session_checks):
+ self.logger.debug(
+ f'[SessionManager] All {len(self.browser_session._cdp_session_pool)} sessions initialized and ready'
+ )
+ return
+
+ await asyncio.sleep(0.05) # Poll every 50ms
+
+ # Timeout - some sessions didn't initialize (likely short-lived targets that already detached)
+ initialized_count = sum(1 for tid in target_ids_to_initialize if tid in self.browser_session._cdp_session_pool)
+ self.logger.warning(
+ f'[SessionManager] Initialization timeout: {initialized_count}/{len(target_ids_to_initialize)} sessions ready '
+ f'(some targets may have detached during initialization)'
+ )
+
async def _enable_page_monitoring(self, cdp_session: 'CDPSession') -> None:
"""Enable lifecycle events and network monitoring for a page target.
This is called once per page when it's created, avoiding handler accumulation.
+ Registers a SINGLE lifecycle handler per session that stores events for navigations to consume.
Args:
cdp_session: The CDP session to enable monitoring on
@@ -428,6 +487,50 @@ class SessionManager:
await cdp_session.cdp_client.send.Network.enable(session_id=cdp_session.session_id)
self.logger.debug(f'[SessionManager] Enabled network monitoring for target {cdp_session.target_id[:8]}...')
+ # Initialize lifecycle event storage for this session (thread-safe)
+ from collections import deque
+
+ cdp_session._lifecycle_events = deque(maxlen=50) # Keep last 50 events
+ cdp_session._lifecycle_lock = asyncio.Lock()
+
+ # Register ONE handler per session that stores events
+ def on_lifecycle_event(event, session_id=None):
+ if session_id == cdp_session.session_id:
+ # Store event for navigations to consume
+ event_data = {
+ 'name': event.get('name'),
+ 'loaderId': event.get('loaderId'),
+ 'timestamp': asyncio.get_event_loop().time(),
+ }
+ # Append is atomic in CPython, but use lock for safety
+ try:
+ cdp_session._lifecycle_events.append(event_data)
+ except Exception:
+ pass # Session might be detaching
+
+ # Register the handler ONCE (this is the only place we register)
+ cdp_session.cdp_client.register.Page.lifecycleEvent(on_lifecycle_event)
+ self.logger.debug(f'[SessionManager] Registered lifecycle handler for target {cdp_session.target_id[:8]}...')
+
+ # Keep session URL updated on every navigation
+ def on_frame_navigated(event, session_id=None):
+ if session_id == cdp_session.session_id:
+ frame = event.get('frame', {})
+ # Only update URL for main frame (not iframes)
+ if not frame.get('parentId'):
+ new_url = frame.get('url')
+ if new_url:
+ old_url = cdp_session.url
+ cdp_session.url = new_url
+ if old_url != new_url:
+ self.logger.debug(
+ f'[SessionManager] Updated URL for target {cdp_session.target_id[:8]}...: {old_url[:50]} → {new_url[:50]}'
+ )
+
+ # Register frame navigation handler to keep URL fresh
+ cdp_session.cdp_client.register.Page.frameNavigated(on_frame_navigated)
+ self.logger.debug(f'[SessionManager] Registered frame navigation handler for target {cdp_session.target_id[:8]}...')
+
except Exception as e:
# Don't fail - target might be short-lived or already detached
error_str = str(e)