Skip to content

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

feat: added automatic captcha solver handling via CAPTCHA watchdog

reformedoted28e50806dc
diff --git a/browser_use/agent/service.py b/browser_use/agent/service.py
index 04cdfd4ea..cd6ac6967 100644
--- a/browser_use/agent/service.py
+++ b/browser_use/agent/service.py
@@ -1024,6 +1024,25 @@ class Agent(Generic[Context, AgentStructuredOutput]):
browser_state_summary = None
try:
+ if self.browser_session:
+ try:
+ captcha_wait = await self.browser_session.wait_if_captcha_solving()
+ if captcha_wait and captcha_wait.waited:
+ # Reset step timing to exclude the captcha wait from step duration metrics
+ self.step_start_time = time.time()
+ duration_s = captcha_wait.duration_ms / 1000
+ outcome = captcha_wait.result # 'success' | 'failed' | 'timeout'
+ msg = f'Waited {duration_s:.1f}s for {captcha_wait.vendor} CAPTCHA to be solved. Result: {outcome}.'
+ self.logger.info(f'πŸ”’ {msg}')
+ # Inject the outcome so the LLM sees what happened
+ captcha_result = ActionResult(long_term_memory=msg)
+ if self.state.last_result:
+ self.state.last_result.append(captcha_result)
+ else:
+ self.state.last_result = [captcha_result]
+ except Exception as e:
+ self.logger.warning(f'Phase 0 captcha wait failed (non-fatal): {e}')
+
# Phase 1: Prepare context and timing
browser_state_summary = await self._prepare_context(step_info)
diff --git a/browser_use/agent/system_prompts/system_prompt.md b/browser_use/agent/system_prompts/system_prompt.md
index f063d6621..1b86bdad1 100644
--- a/browser_use/agent/system_prompts/system_prompt.md
+++ b/browser_use/agent/system_prompts/system_prompt.md
@@ -65,7 +65,7 @@ Strictly follow these rules while using the browser and navigating the web:
- If research is needed, open a **new tab** instead of reusing the current one.
- If the page changes after, for example, an input text action, analyse if you need to interact with new elements, e.g. selecting the right option from the list.
- By default, only elements in the visible viewport are listed.
-- If a captcha appears, attempt solving it if possible. If not, use fallback strategies (e.g., alternative site, backtrack). Do not spend more than 3-4 steps on a single captcha - if blocked, try alternative approaches or report the limitation.
+- CAPTCHAs are automatically solved by the browser. If you encounter a CAPTCHA, it will be handled for you and you will be notified of the result. Do not attempt to solve CAPTCHAs manually β€” just continue with your task after the CAPTCHA is resolved.
- If the page is not fully loaded, use the wait action.
- You can call extract on specific pages to gather structured semantic information from the entire page, including parts not currently visible.
- Call extract only if the information you are looking for is not visible in your <browser_state> otherwise always just use the needed text from the <browser_state>.
@@ -84,7 +84,7 @@ Strictly follow these rules while using the browser and navigating the web:
1. Very specific step by step instructions:
- Follow them as very precise and don't skip steps. Try to complete everything as requested.
2. Open ended tasks. Plan yourself, be creative in achieving them.
-- If you get stuck e.g. with logins or captcha in open-ended tasks you can re-evaluate the task and try alternative ways, e.g. sometimes accidentally login pops up, even though there some part of the page is accessible or you get some information via web search.
+- If you get stuck e.g. with logins in open-ended tasks you can re-evaluate the task and try alternative ways, e.g. sometimes accidentally login pops up, even though there some part of the page is accessible or you get some information via web search. CAPTCHAs are handled automatically.
- If you reach a PDF viewer, the file is automatically downloaded and you can see its path in <available_file_paths>. You can either read the file or scroll in the page to see more.
- Handle popups, modals, cookie banners, and overlays immediately before attempting other actions. Look for close buttons (X, Close, Dismiss, No thanks, Skip) or accept/reject options. If a popup blocks interaction with the main page, handle it first.
- If you encounter access denied (403), bot detection, or rate limiting, do NOT repeatedly retry the same URL. Try alternative approaches or report the limitation.
@@ -241,7 +241,7 @@ Action list should NEVER be empty.
3. ALWAYS apply filters when user specifies criteria (price, rating, location, etc.)
4. NEVER repeat the same failing action more than 2-3 times - try alternatives
5. NEVER assume success - always verify from screenshot or browser state
-6. If blocked by captcha/login/403, try alternative approaches rather than retrying
+6. CAPTCHAs are solved automatically. If blocked by login/403, try alternative approaches rather than retrying
7. Put ALL relevant findings in done action's text field
8. Match user's requested output format exactly
9. Track progress in memory to avoid loops
@@ -255,7 +255,7 @@ When encountering errors or unexpected states:
2. Check if a popup, modal, or overlay is blocking interaction
3. If an element is not found, scroll to reveal more content
4. If an action fails repeatedly (2-3 times), try an alternative approach
-5. If blocked by login/captcha/403, consider alternative sites or search engines
+5. If blocked by login/403, consider alternative sites or search engines. CAPTCHAs are solved automatically.
6. If the page structure is different than expected, re-analyze and adapt
7. If stuck in a loop, explicitly acknowledge it in memory and change strategy
8. If max_steps is approaching, prioritize completing the most important parts of the task
diff --git a/browser_use/agent/system_prompts/system_prompt_anthropic_flash.md b/browser_use/agent/system_prompts/system_prompt_anthropic_flash.md
index 524b006be..ae16b37de 100644
--- a/browser_use/agent/system_prompts/system_prompt_anthropic_flash.md
+++ b/browser_use/agent/system_prompts/system_prompt_anthropic_flash.md
@@ -31,7 +31,7 @@ Strictly follow these rules while using the browser and navigating the web:
- If research is needed, open a **new tab** instead of reusing the current one.
- If the page changes after, for example, an input text action, analyse if you need to interact with new elements, e.g. selecting the right option from the list.
- By default, only elements in the visible viewport are listed. Scroll to see more elements if needed.
-- If a captcha appears, attempt solving it if possible. If not, use fallback strategies (e.g., alternative site, backtrack). Do not spend more than 3-4 steps on a single captcha - if blocked, try alternative approaches or report the limitation.
+- CAPTCHAs are automatically solved by the browser. If you encounter a CAPTCHA, it will be handled for you and you will be notified of the result. Do not attempt to solve CAPTCHAs manually β€” just continue with your task after the CAPTCHA is resolved.
- If the page is not fully loaded, use the wait action to allow content to render.
- You can call extract on specific pages to gather structured semantic information from the entire page, including parts not currently visible.
- Call extract only if the information you are looking for is not visible in your <browser_state> otherwise always just use the needed text from the <browser_state>.
@@ -46,7 +46,7 @@ Strictly follow these rules while using the browser and navigating the web:
- There are 2 types of tasks:
1. Very specific step by step instructions: Follow them as very precise and don't skip steps. Try to complete everything as requested.
2. Open ended tasks. Plan yourself, be creative in achieving them.
-- If you get stuck e.g. with logins or captcha in open-ended tasks you can re-evaluate the task and try alternative ways, e.g. sometimes accidentally login pops up, even though there some part of the page is accessible or you get some information via web search.
+- If you get stuck e.g. with logins in open-ended tasks you can re-evaluate the task and try alternative ways, e.g. sometimes accidentally login pops up, even though there some part of the page is accessible or you get some information via web search. CAPTCHAs are handled automatically.
- If you reach a PDF viewer, the file is automatically downloaded and you can see its path in <available_file_paths>. You can either read the file or scroll in the page to see more.
- Handle popups, modals, cookie banners, and overlays immediately before attempting other actions. Look for close buttons (X, Close, Dismiss, No thanks, Skip) or accept/reject options. If a popup blocks interaction with the main page, handle it first. Many websites show cookie consent dialogs, newsletter popups, or promotional overlays that must be dismissed.
- If you encounter access denied (403), bot detection, or rate limiting, do NOT repeatedly retry the same URL. Try alternative approaches or report the limitation. Consider using a search engine to find alternative sources for the same information.
@@ -166,7 +166,7 @@ Always put `memory` field before the `action` field.
Your memory field should include your reasoning. Apply these patterns:
- Did the previous action succeed? Verify using screenshot as ground truth.
- What is the current state relative to the user request?
-- Are there any obstacles (popups, captcha, login walls)?
+- Are there any obstacles (popups, login walls)? CAPTCHAs are solved automatically.
- What specific next step will make progress toward the goal?
- If stuck, what alternative approach should you try?
- What information should be remembered for later steps?
@@ -219,7 +219,7 @@ When encountering errors or unexpected states:
2. Check if a popup, modal, or overlay is blocking interaction
3. If an element is not found, scroll to reveal more content
4. If an action fails repeatedly (2-3 times), try an alternative approach
-5. If blocked by login/captcha/403, consider alternative sites or search engines
+5. If blocked by login/403, consider alternative sites or search engines. CAPTCHAs are solved automatically.
6. If the page structure is different than expected, re-analyze and adapt
7. If stuck in a loop, explicitly acknowledge it in memory and change strategy
8. If max_steps is approaching, prioritize completing the most important parts of the task
@@ -230,7 +230,7 @@ When encountering errors or unexpected states:
3. ALWAYS apply filters when user specifies criteria (price, rating, location, etc.)
4. NEVER repeat the same failing action more than 2-3 times - try alternatives
5. NEVER assume success - always verify from screenshot or browser state
-6. If blocked by captcha/login/403, try alternative approaches rather than retrying
+6. CAPTCHAs are solved automatically. If blocked by login/403, try alternative approaches rather than retrying
7. Put ALL relevant findings in done action's text field
8. Match user's requested output format exactly
9. Track progress in memory to avoid loops
diff --git a/browser_use/agent/system_prompts/system_prompt_no_thinking.md b/browser_use/agent/system_prompts/system_prompt_no_thinking.md
index 21eee5e49..6dc986b7f 100644
--- a/browser_use/agent/system_prompts/system_prompt_no_thinking.md
+++ b/browser_use/agent/system_prompts/system_prompt_no_thinking.md
@@ -65,7 +65,7 @@ Strictly follow these rules while using the browser and navigating the web:
- If research is needed, open a **new tab** instead of reusing the current one.
- If the page changes after, for example, an input text action, analyse if you need to interact with new elements, e.g. selecting the right option from the list.
- By default, only elements in the visible viewport are listed.
-- If a captcha appears, attempt solving it if possible. If not, use fallback strategies (e.g., alternative site, backtrack). Do not spend more than 3-4 steps on a single captcha - if blocked, try alternative approaches or report the limitation.
+- CAPTCHAs are automatically solved by the browser. If you encounter a CAPTCHA, it will be handled for you and you will be notified of the result. Do not attempt to solve CAPTCHAs manually β€” just continue with your task after the CAPTCHA is resolved.
- If the page is not fully loaded, use the wait action.
- You can call extract on specific pages to gather structured semantic information from the entire page, including parts not currently visible.
- Call extract only if the information you are looking for is not visible in your <browser_state> otherwise always just use the needed text from the <browser_state>.
@@ -81,7 +81,7 @@ Strictly follow these rules while using the browser and navigating the web:
1. Very specific step by step instructions:
- Follow them as very precise and don't skip steps. Try to complete everything as requested.
2. Open ended tasks. Plan yourself, be creative in achieving them.
-- If you get stuck e.g. with logins or captcha in open-ended tasks you can re-evaluate the task and try alternative ways, e.g. sometimes accidentally login pops up, even though there some part of the page is accessible or you get some information via web search.
+- If you get stuck e.g. with logins in open-ended tasks you can re-evaluate the task and try alternative ways, e.g. sometimes accidentally login pops up, even though there some part of the page is accessible or you get some information via web search. CAPTCHAs are handled automatically.
- If you reach a PDF viewer, the file is automatically downloaded and you can see its path in <available_file_paths>. You can either read the file or scroll in the page to see more.
- Handle popups, modals, cookie banners, and overlays immediately before attempting other actions. Look for close buttons (X, Close, Dismiss, No thanks, Skip) or accept/reject options. If a popup blocks interaction with the main page, handle it first.
- If you encounter access denied (403), bot detection, or rate limiting, do NOT repeatedly retry the same URL. Try alternative approaches or report the limitation.
@@ -224,7 +224,7 @@ Action list should NEVER be empty.
3. ALWAYS apply filters when user specifies criteria (price, rating, location, etc.)
4. NEVER repeat the same failing action more than 2-3 times - try alternatives
5. NEVER assume success - always verify from screenshot or browser state
-6. If blocked by captcha/login/403, try alternative approaches rather than retrying
+6. CAPTCHAs are solved automatically. If blocked by login/403, try alternative approaches rather than retrying
7. Put ALL relevant findings in done action's text field
8. Match user's requested output format exactly
9. Track progress in memory to avoid loops
@@ -238,7 +238,7 @@ When encountering errors or unexpected states:
2. Check if a popup, modal, or overlay is blocking interaction
3. If an element is not found, scroll to reveal more content
4. If an action fails repeatedly (2-3 times), try an alternative approach
-5. If blocked by login/captcha/403, consider alternative sites or search engines
+5. If blocked by login/403, consider alternative sites or search engines. CAPTCHAs are solved automatically.
6. If the page structure is different than expected, re-analyze and adapt
7. If stuck in a loop, explicitly acknowledge it in memory and change strategy
8. If max_steps is approaching, prioritize completing the most important parts of the task
diff --git a/browser_use/browser/events.py b/browser_use/browser/events.py
index afc492de3..db98800e3 100644
--- a/browser_use/browser/events.py
+++ b/browser_use/browser/events.py
@@ -576,6 +576,42 @@ class DialogOpenedEvent(BaseEvent):
# target_id: TargetID # TODO: add this to avoid needing target_id_from_frame() later
+# ============================================================================
+# Captcha Solver Events
+# ============================================================================
+
+
+class CaptchaSolverStartedEvent(BaseEvent):
+ """Captcha solving started by the browser proxy.
+
+ Emitted when the browser proxy detects a CAPTCHA and begins solving it.
+ The agent should wait for a corresponding CaptchaSolverFinishedEvent before proceeding.
+ """
+
+ target_id: TargetID
+ vendor: str # e.g. 'cloudflare', 'recaptcha', 'hcaptcha', 'datadome', 'perimeterx', 'geetest'
+ url: str
+ started_at: int # Unix millis
+
+ event_timeout: float | None = Field(default_factory=lambda: _get_timeout('TIMEOUT_CaptchaSolverStartedEvent', 5.0))
+
+
+class CaptchaSolverFinishedEvent(BaseEvent):
+ """Captcha solving finished by the browser proxy.
+
+ Emitted when the browser proxy finishes solving a CAPTCHA (successfully or not).
+ """
+
+ target_id: TargetID
+ vendor: str
+ url: str
+ duration_ms: int
+ finished_at: int # Unix millis
+ success: bool # Whether the captcha was solved successfully
+
+ event_timeout: float | None = Field(default_factory=lambda: _get_timeout('TIMEOUT_CaptchaSolverFinishedEvent', 5.0))
+
+
# Note: Model rebuilding for forward references is handled in the importing modules
# Events with 'EnhancedDOMTreeNode' forward references (ClickElementEvent, TypeTextEvent,
# ScrollEvent, UploadFileEvent) need model_rebuild() called after imports are complete
diff --git a/browser_use/browser/profile.py b/browser_use/browser/profile.py
index 7b506a783..fd8e34171 100644
--- a/browser_use/browser/profile.py
+++ b/browser_use/browser/profile.py
@@ -602,6 +602,10 @@ class BrowserProfile(BrowserConnectArgs, BrowserLaunchPersistentContextArgs, Bro
default_factory=_get_enable_default_extensions_default,
description="Enable automation-optimized extensions: ad blocking (uBlock Origin), cookie handling (I still don't care about cookies), and URL cleaning (ClearURLs). All extensions work automatically without manual intervention. Extensions are automatically downloaded and loaded when enabled. Can be disabled via BROWSER_USE_DISABLE_EXTENSIONS=1 environment variable.",
)
+ captcha_solver: bool = Field(
+ default=True,
+ description='Enable the captcha solver watchdog that listens for captcha events from the browser proxy. Automatically pauses agent steps while a CAPTCHA is being solved. Only active when the browser emits BrowserUse CDP events (e.g. Browser Use cloud browsers). Harmless when disabled or when events are not emitted.',
+ )
demo_mode: bool = Field(
default=False,
description='Enable demo mode side panel that streams agent logs directly inside the browser window (requires headless=False).',
diff --git a/browser_use/browser/session.py b/browser_use/browser/session.py
index 5fd6f596e..330ba6a3b 100644
--- a/browser_use/browser/session.py
+++ b/browser_use/browser/session.py
@@ -50,6 +50,7 @@ from browser_use.utils import _log_pretty_url, create_task_with_error_handling,
if TYPE_CHECKING:
from browser_use.actor.page import Page
from browser_use.browser.demo_mode import DemoMode
+ from browser_use.browser.watchdogs.captcha_watchdog import CaptchaWaitResult
DEFAULT_BROWSER_PROFILE = BrowserProfile()
@@ -145,6 +146,7 @@ class BrowserSession(BaseModel):
minimum_wait_page_load_time: float | None = None,
wait_for_network_idle_page_load_time: float | None = None,
wait_between_actions: float | None = None,
+ captcha_solver: bool | None = None,
auto_download_pdfs: bool | None = None,
cookie_whitelist_domains: list[str] | None = None,
cross_origin_iframes: bool | None = None,
@@ -211,6 +213,7 @@ class BrowserSession(BaseModel):
deterministic_rendering: bool | None = None,
proxy: ProxySettings | None = None,
enable_default_extensions: bool | None = None,
+ captcha_solver: bool | None = None,
window_size: dict | None = None,
window_position: dict | None = None,
filter_highlight_ids: bool | None = None,
@@ -277,6 +280,7 @@ class BrowserSession(BaseModel):
keep_alive: bool | None = None,
proxy: ProxySettings | None = None,
enable_default_extensions: bool | None = None,
+ captcha_solver: bool | None = None,
window_size: dict | None = None,
window_position: dict | None = None,
minimum_wait_page_load_time: float | None = None,
@@ -458,6 +462,16 @@ class BrowserSession(BaseModel):
except Exception:
return False
+ async def wait_if_captcha_solving(self, timeout: float | None = None) -> 'CaptchaWaitResult | None':
+ """Wait if a captcha is currently being solved by the browser proxy.
+
+ Returns:
+ A CaptchaWaitResult if we had to wait, or None if no captcha was in progress.
+ """
+ if self._captcha_watchdog is not None:
+ return await self._captcha_watchdog.wait_if_captcha_solving(timeout=timeout)
+ return None
+
@property
def cloud_browser(self) -> bool:
"""Whether to use cloud browser service from browser profile."""
@@ -504,6 +518,8 @@ class BrowserSession(BaseModel):
_screenshot_watchdog: Any | None = PrivateAttr(default=None)
_permissions_watchdog: Any | None = PrivateAttr(default=None)
_recording_watchdog: Any | None = PrivateAttr(default=None)
+ _captcha_watchdog: Any | None = PrivateAttr(default=None)
+ _watchdogs_attached: bool = PrivateAttr(default=False)
_cloud_browser_client: CloudBrowserClient = PrivateAttr(default_factory=lambda: CloudBrowserClient())
_demo_mode: 'DemoMode | None' = PrivateAttr(default=None)
@@ -584,6 +600,8 @@ class BrowserSession(BaseModel):
self._screenshot_watchdog = None
self._permissions_watchdog = None
self._recording_watchdog = None
+ self._captcha_watchdog = None
+ self._watchdogs_attached = False
if self._demo_mode:
self._demo_mode.reset()
self._demo_mode = None
@@ -1466,11 +1484,12 @@ class BrowserSession(BaseModel):
async def attach_all_watchdogs(self) -> None:
"""Initialize and attach all watchdogs with explicit handler registration."""
# Prevent duplicate watchdog attachment
- if hasattr(self, '_watchdogs_attached') and self._watchdogs_attached:
+ if self._watchdogs_attached:
self.logger.debug('Watchdogs already attached, skipping duplicate attachment')
return
from browser_use.browser.watchdogs.aboutblank_watchdog import AboutBlankWatchdog
+ from browser_use.browser.watchdogs.captcha_watchdog import CaptchaWatchdog
# from browser_use.browser.crash_watchdog import CrashWatchdog
from browser_use.browser.watchdogs.default_action_watchdog import DefaultActionWatchdog
@@ -1604,6 +1623,12 @@ class BrowserSession(BaseModel):
self._har_recording_watchdog = HarRecordingWatchdog(event_bus=self.event_bus, browser_session=self)
self._har_recording_watchdog.attach_to_session()
+ # Initialize CaptchaWatchdog (listens for captcha solver events from the browser proxy)
+ if self.browser_profile.captcha_solver:
+ CaptchaWatchdog.model_rebuild()
+ self._captcha_watchdog = CaptchaWatchdog(event_bus=self.event_bus, browser_session=self)
+ self._captcha_watchdog.attach_to_session()
+
# Mark watchdogs as attached to prevent duplicate attachment
self._watchdogs_attached = True
diff --git a/browser_use/browser/watchdogs/captcha_watchdog.py b/browser_use/browser/watchdogs/captcha_watchdog.py
new file mode 100644
index 000000000..f3066a418
--- /dev/null
+++ b/browser_use/browser/watchdogs/captcha_watchdog.py
@@ -0,0 +1,202 @@
+"""Captcha solver watchdog β€” monitors captcha events from the browser proxy.
+
+Listens for BrowserUse.captchaSolverStarted/Finished CDP events and exposes a
+wait_if_captcha_solving() method that the agent step loop uses to block until
+a captcha is resolved (with a configurable timeout).
+
+NOTE: Only a single captcha solve is tracked at a time. If multiple captchas
+overlap (e.g. rapid successive navigations), only the latest one is tracked and
+earlier in-flight waits may return prematurely.
+"""
+
+import asyncio
+from dataclasses import dataclass
+from typing import Any, ClassVar, Literal, Optional
+
+from bubus import BaseEvent
+from pydantic import PrivateAttr
+
+from browser_use.browser.events import (
+ BrowserConnectedEvent,
+ BrowserStoppedEvent,
+ CaptchaSolverFinishedEvent,
+ CaptchaSolverStartedEvent,
+ _get_timeout,
+)
+from browser_use.browser.watchdog_base import BaseWatchdog
+
+
+@dataclass
+class CaptchaWaitResult:
+ """Result returned by wait_if_captcha_solving() when the agent had to wait."""
+
+ waited: bool
+ vendor: str
+ url: str
+ duration_ms: int
+ result: Literal['success', 'failed', 'timeout', 'unknown']
+
+
+class CaptchaWatchdog(BaseWatchdog):
+ """Monitors captcha solver events from the browser proxy.
+
+ When the proxy detects a CAPTCHA and starts solving it, a CDP event
+ ``BrowserUse.captchaSolverStarted`` is sent over the WebSocket. This
+ watchdog catches that event and blocks the agent's step loop (via
+ ``wait_if_captcha_solving``) until ``BrowserUse.captchaSolverFinished``
+ arrives or the configurable timeout expires.
+ """
+
+ # Event contracts
+ LISTENS_TO: ClassVar[list[type[BaseEvent]]] = [
+ BrowserConnectedEvent,
+ BrowserStoppedEvent,
+ ]
+ EMITS: ClassVar[list[type[BaseEvent]]] = [
+ CaptchaSolverStartedEvent,
+ CaptchaSolverFinishedEvent,
+ ]
+
+ # --- private state ---
+ _captcha_solving: bool = PrivateAttr(default=False)
+ _captcha_solved_event: asyncio.Event = PrivateAttr(default_factory=asyncio.Event)
+ _captcha_info: dict[str, Any] = PrivateAttr(default_factory=dict)
+ _captcha_result: str = PrivateAttr(default='unknown')
+ _captcha_duration_ms: int = PrivateAttr(default=0)
+ _cdp_handlers_registered: bool = PrivateAttr(default=False)
+
+ def model_post_init(self, __context: Any) -> None:
+ # Start in "not blocked" state so callers never wait when there is no captcha.
+ self._captcha_solved_event.set()
+
+ # ------------------------------------------------------------------
+ # Event handlers
+ # ------------------------------------------------------------------
+
+ async def on_BrowserConnectedEvent(self, event: BrowserConnectedEvent) -> None:
+ """Register CDP event handlers for BrowserUse captcha solver events."""
+ if self._cdp_handlers_registered:
+ self.logger.debug('CaptchaWatchdog: CDP handlers already registered, skipping')
+ return
+
+ cdp_client = self.browser_session.cdp_client
+
+ def _on_captcha_started(event_data: dict, session_id: Optional[str]) -> None:
+ try:
+ self._captcha_solving = True
+ self._captcha_result = 'unknown'
+ self._captcha_duration_ms = 0
+ self._captcha_info = {
+ 'vendor': event_data.get('vendor', 'unknown'),
+ 'url': event_data.get('url', ''),
+ 'targetId': event_data.get('targetId', ''),
+ 'startedAt': event_data.get('startedAt', 0),
+ }
+ # Block any waiter
+ self._captcha_solved_event.clear()
+
+ vendor = self._captcha_info['vendor']
+ url = self._captcha_info['url']
+ self.logger.info(f'πŸ”’ Captcha solving started: {vendor} on {url}')
+
+ self.event_bus.dispatch(
+ CaptchaSolverStartedEvent(
+ target_id=event_data.get('targetId', ''),
+ vendor=vendor,
+ url=url,
+ started_at=event_data.get('startedAt', 0),
+ )
+ )
+ except Exception:
+ self.logger.exception('Error handling captchaSolverStarted CDP event')
+ # Ensure consistent state: unblock any waiter
+ self._captcha_solving = False
+ self._captcha_solved_event.set()
+
+ def _on_captcha_finished(event_data: dict, session_id: Optional[str]) -> None:
+ try:
+ success = event_data.get('success', False)
+ self._captcha_solving = False
+ self._captcha_duration_ms = event_data.get('durationMs', 0)
+ self._captcha_result = 'success' if success else 'failed'
+
+ vendor = event_data.get('vendor', self._captcha_info.get('vendor', 'unknown'))
+ url = event_data.get('url', self._captcha_info.get('url', ''))
+ duration_s = self._captcha_duration_ms / 1000
+
+ self.logger.info(f'πŸ”“ Captcha solving finished: {self._captcha_result} β€” {vendor} on {url} ({duration_s:.1f}s)')
+
+ # Unblock any waiter
+ self._captcha_solved_event.set()
+
+ self.event_bus.dispatch(
+ CaptchaSolverFinishedEvent(
+ target_id=event_data.get('targetId', ''),
+ vendor=vendor,
+ url=url,
+ duration_ms=self._captcha_duration_ms,
+ finished_at=event_data.get('finishedAt', 0),
+ success=success,
+ )
+ )
+ except Exception:
+ self.logger.exception('Error handling captchaSolverFinished CDP event')
+ # Ensure consistent state: unblock any waiter
+ self._captcha_solving = False
+ self._captcha_solved_event.set()
+
+ cdp_client.register.BrowserUse.captchaSolverStarted(_on_captcha_started)
+ cdp_client.register.BrowserUse.captchaSolverFinished(_on_captcha_finished)
+ self._cdp_handlers_registered = True
+ self.logger.debug('πŸ”’ CaptchaWatchdog: registered CDP event handlers for BrowserUse captcha events')
+
+ async def on_BrowserStoppedEvent(self, event: BrowserStoppedEvent) -> None:
+ """Clear captcha state when the browser disconnects so nothing hangs."""
+ self._captcha_solving = False
+ self._captcha_result = 'unknown'
+ self._captcha_duration_ms = 0
+ self._captcha_info = {}
+ self._captcha_solved_event.set()
+ self._cdp_handlers_registered = False
+
+ # ------------------------------------------------------------------
+ # Public API
+ # ------------------------------------------------------------------
+
+ async def wait_if_captcha_solving(self, timeout: float | None = None) -> CaptchaWaitResult | None:
+ """Wait if a captcha is currently being solved.
+
+ Returns:
+ ``None`` if no captcha was in progress.
+ A ``CaptchaWaitResult`` with the outcome otherwise.
+ """
+ if not self._captcha_solving:
+ return None
+
+ if timeout is None:
+ timeout = _get_timeout('TIMEOUT_CaptchaSolverWait', 120.0)
+ vendor = self._captcha_info.get('vendor', 'unknown')
+ url = self._captcha_info.get('url', '')
+ self.logger.info(f'⏳ Waiting for {vendor} captcha to be solved on {url} (timeout={timeout}s)...')
+
+ try:
+ await asyncio.wait_for(self._captcha_solved_event.wait(), timeout=timeout)
+ return CaptchaWaitResult(
+ waited=True,
+ vendor=vendor,
+ url=url,
+ duration_ms=self._captcha_duration_ms,
+ result=self._captcha_result,
+ )
+ except TimeoutError:
+ # Timed out β€” unblock and report
+ self._captcha_solving = False
+ self._captcha_solved_event.set()
+ self.logger.warning(f'⏰ Captcha wait timed out after {timeout}s for {vendor} on {url}')
+ return CaptchaWaitResult(
+ waited=True,
+ vendor=vendor,
+ url=url,
+ duration_ms=int(timeout * 1000),
+ result='timeout',
+ )
diff --git a/pyproject.toml b/pyproject.toml
index cbfc876d2..5cc368eba 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -41,7 +41,7 @@ dependencies = [
"mcp>=1.10.1",
"pypdf>=5.7.0",
"reportlab>=4.0.0",
- "cdp-use>=1.4.4",
+ "cdp-use>=1.4.5",
"pyotp>=2.9.0",
"pillow>=11.2.1",
"cloudpickle>=3.1.1",