browser_cdp_tool.py 27 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509
  1. #!/usr/bin/env python3
  2. """Raw Chrome DevTools Protocol (CDP) passthrough tool ``browser_cdp``.
  3. Sends arbitrary CDP commands to the browser's DevTools WebSocket when a CDP URL is
  4. configured (``/browser connect`` → ``BROWSER_CDP_URL``, ``browser.cdp_url``). Escape hatch
  5. for operations ``browser_exec``'s helpers don't cover. Method reference:
  6. https://chromedevtools.github.io/devtools-protocol/
  7. """
  8. from __future__ import annotations
  9. import asyncio
  10. import json
  11. import logging
  12. from typing import Any, Callable, Dict, Optional
  13. from tools.registry import registry, tool_error
  14. logger = logging.getLogger(__name__)
  15. CDP_DOCS_URL = "https://chromedevtools.github.io/devtools-protocol/"
  16. # Browser/target inspection and tab management that never reads page body/cookies/DOM/storage — stays
  17. # usable so the model can list, open, switch and close tabs or navigate away from a blocked page. Methods
  18. # that take a url (Page.navigate, Target.createTarget) are still held to _METHOD_PARAM_GUARDS.
  19. _CDP_PRIVATE_PAGE_ALLOWED_METHODS = {
  20. "Browser.getVersion", "Target.getTargets", "Target.attachToTarget", "Target.detachFromTarget",
  21. "Target.createTarget", "Target.activateTarget", "Target.closeTarget",
  22. "Page.navigate", "Page.reload", "Page.stopLoading",
  23. }
  24. # method → result paths that are ALWAYS opaque base64 (protocol-declared binary).
  25. # redact_sensitive_text's Fernet pattern ("gAAAA" + base64 alphabet) can match arbitrary
  26. # spans inside such payloads and corrupt the decoded bytes; the payload is not free text
  27. # the model reads, so redaction protects no secret there.
  28. _CDP_ALWAYS_BINARY_PATHS: dict[str, tuple] = {
  29. "Page.captureScreenshot": (("data",),), "Page.printToPDF": (("data",),),
  30. "Network.streamResourceContent": (("bufferedData",),), "HeadlessExperimental.beginFrame": (("screenshotData",),),
  31. "CacheStorage.requestCachedResponse": (("response", "body"),),
  32. }
  33. # method → result paths that are opaque base64 ONLY when the carrying dict has a
  34. # ``base64Encoded`` sibling that is exactly ``True``; otherwise text → redacted.
  35. _CDP_FLAGGED_BINARY_PATHS: dict[str, tuple] = {
  36. "Network.getResponseBody": (("body",),), "Fetch.getResponseBody": (("body",),),
  37. "IO.read": (("data",),), "Network.getRequestPostData": (("postData",),),
  38. }
  39. def _redact_cdp_output(
  40. value: Any,
  41. *,
  42. always_paths: tuple = (),
  43. flagged_paths: tuple = (),
  44. _depth: int = 0,
  45. ) -> Any:
  46. """Redact browser-originated CDP result text; opaque bytes stay byte-identical.
  47. Exemptions come ONLY from the calling method's spec as exact result paths. Path
  48. suffixes propagate only into the matching subtree, so ``base64Encoded`` is honored
  49. solely as a sibling on the trusted carrier object — never as ambient trust a
  50. ``Runtime.evaluate`` by-value object could spoof.
  51. ``_depth`` stops a page-controlled tree from raising RecursionError. The
  52. unread remainder is replaced, not returned raw.
  53. See #94138, #94142.
  54. """
  55. from agent.redact import (
  56. REDACT_WALK_DEPTH_MARKER,
  57. REDACT_WALK_MAX_DEPTH,
  58. redact_sensitive_text,
  59. )
  60. if _depth >= REDACT_WALK_MAX_DEPTH:
  61. return REDACT_WALK_DEPTH_MARKER
  62. if isinstance(value, str):
  63. return redact_sensitive_text(value, force=True)
  64. if isinstance(value, (list, tuple)):
  65. return type(value)(
  66. _redact_cdp_output(item, _depth=_depth + 1) for item in value
  67. )
  68. if not isinstance(value, dict):
  69. return value
  70. base64_flagged = value.get("base64Encoded") is True
  71. def leaf(paths: tuple, key: str) -> bool:
  72. return any(len(p) == 1 and p[0] == key for p in paths)
  73. def descend(paths: tuple, key: str) -> tuple:
  74. return tuple(p[1:] for p in paths if len(p) > 1 and p[0] == key)
  75. redacted: dict[str, Any] = {}
  76. for key, item in value.items():
  77. opaque = leaf(always_paths, key) or (leaf(flagged_paths, key) and base64_flagged)
  78. out_key = redact_sensitive_text(key, force=True) if isinstance(key, str) else key # by-value objects can carry a secret as a KEY
  79. redacted[out_key] = item if isinstance(item, str) and opaque else _redact_cdp_output(
  80. item,
  81. always_paths=descend(always_paths, key),
  82. flagged_paths=descend(flagged_paths, key),
  83. _depth=_depth + 1,
  84. )
  85. return redacted
  86. # ``websockets`` is a direct dependency; wrap so a stale env yields a clean error.
  87. try:
  88. import websockets
  89. from websockets.exceptions import WebSocketException
  90. _WS_AVAILABLE = True
  91. except ImportError:
  92. websockets = None # type: ignore[assignment]
  93. WebSocketException = Exception # type: ignore[assignment,misc]
  94. _WS_AVAILABLE = False
  95. def _run_async(coro):
  96. """Run an async coroutine from a sync handler, safe inside or outside a loop."""
  97. try:
  98. loop = asyncio.get_running_loop()
  99. except RuntimeError:
  100. loop = None
  101. if loop and loop.is_running():
  102. import concurrent.futures
  103. import contextvars
  104. with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
  105. return pool.submit(contextvars.copy_context().run, asyncio.run, coro).result()
  106. return asyncio.run(coro)
  107. def _resolve_cdp_endpoint() -> str:
  108. """Normalized CDP WebSocket URL via ``browser_session_cdp.get_cdp_override``, or ""."""
  109. from tools.browser_session_cdp import get_cdp_override
  110. return (get_cdp_override() or "").strip()
  111. def _blocked(message: str, method: str) -> str:
  112. return tool_error(message, method=method, cdp_docs=CDP_DOCS_URL)
  113. def _expression_private_target(params: dict[str, Any], blocked: Callable[[str], bool]) -> Optional[str]:
  114. from tools.browser_url_policy import expression_targets_private_url
  115. return expression_targets_private_url(str(params.get("expression") or ""), blocked=blocked)
  116. def _navigate_private_target(params: dict[str, Any], blocked: Callable[[str], bool]) -> Optional[str]:
  117. """Blocked URL literal for ``Page.navigate`` params, else ``None``."""
  118. target_url = str(params.get("url") or "").strip()
  119. return target_url if target_url and blocked(target_url) else None
  120. def _new_tab_private_target(params: dict[str, Any], blocked: Callable[[str], bool]) -> Optional[str]:
  121. """``Target.createTarget``: a blank tab (``about:blank``, Chrome's default for no url) reaches nothing, so
  122. it opens before scripts are installed or a page is chosen; any other url is held to ``Page.navigate``'s
  123. rule (``url_blocked`` refuses every other non-http scheme)."""
  124. if str(params.get("url") or "").strip().lower() == "about:blank":
  125. return None
  126. return _navigate_private_target(params, blocked)
  127. # method → (probe(params, blocked) -> blocked literal | None, error template)
  128. _METHOD_PARAM_GUARDS = {
  129. "Page.navigate": (_navigate_private_target,
  130. "Blocked: CDP Page.navigate target is a private or internal address ({})."),
  131. "Target.createTarget": (_new_tab_private_target,
  132. "Blocked: CDP Target.createTarget url is a private or internal address ({})."),
  133. "Runtime.evaluate": (_expression_private_target,
  134. "Blocked: CDP Runtime.evaluate expression targets a private or internal address ({})."),
  135. }
  136. # _current_page_private_url's verdict when the target list cannot be read: refuse, never assume public.
  137. _PAGE_URL_UNVERIFIED = "<unverified>"
  138. # Browser-internal pages carry no web origin a worker or browser-level call could borrow, so an open new tab
  139. # must not lock every target-less call (url_blocked rejects their schemes as unsupported).
  140. _ORIGINLESS_PAGE_PREFIXES = ("about:", "chrome:", "chrome-untrusted:", "chrome-search:", "devtools:", "edge:", "brave:")
  141. def _current_page_private_url(endpoint: str, target_id: Optional[str]) -> Optional[str]:
  142. """The private/internal URL a non-allow-listed call would reach (or ``_PAGE_URL_UNVERIFIED``), else None.
  143. Fail-closed, read from ``Target.getTargets`` on the same endpoint. Only a ``page`` target whose own URL
  144. is known passes on that URL alone. A browser-level call (no target) or a worker / iframe / unknown
  145. target runs with some page's origin (a SharedWorker's ``fetch('/')`` reads its private page;
  146. ``Storage.*`` spans every origin), so it is refused while ANY page target is private."""
  147. from tools.browser_url_policy import url_blocked
  148. if not endpoint or not _WS_AVAILABLE:
  149. return _PAGE_URL_UNVERIFIED
  150. try:
  151. infos = _run_async(_cdp_call(endpoint, "Target.getTargets", {}, None, 5.0)).get("targetInfos") or []
  152. except (TimeoutError, RuntimeError, OSError, ValueError, WebSocketException) as exc:
  153. logger.debug("browser_cdp: page-URL probe failed: %s", exc)
  154. return _PAGE_URL_UNVERIFIED
  155. acted = next((t for t in infos if t.get("targetId") == target_id), None) if target_id else None
  156. url = str((acted or {}).get("url") or "")
  157. if url and url_blocked(url):
  158. return url
  159. if url and acted.get("type") == "page":
  160. return None
  161. page_urls = (str(t.get("url") or "") for t in infos if t.get("type") == "page")
  162. return next((u for u in page_urls if u and not u.startswith(_ORIGINLESS_PAGE_PREFIXES) and url_blocked(u)), None)
  163. # Input.* only types text or dispatches key/mouse events; a URL in its text is never fetched by the call.
  164. _TEXT_INPUT_METHOD_PREFIX = "Input."
  165. # Nor are these methods' URL params: blocklist / interception match patterns (wildcard hosts, often
  166. # naming the very hosts being blocked), dialog answer text, cookie scope URLs.
  167. _CDP_NON_FETCHING_METHODS = frozenset({
  168. "Network.setBlockedURLs", "Network.setRequestInterception", "Fetch.enable",
  169. "Page.handleJavaScriptDialog",
  170. "Network.setCookie", "Network.setCookies", "Network.deleteCookies", "Storage.setCookies",
  171. })
  172. def _param_url_literals(value: Any, key: str = "") -> list[str]:
  173. """Every URL a CDP call's params name: each ``url`` value whole, plus the ``http(s)://`` and
  174. protocol-relative ``//host`` literals in every string at any depth (``Network.loadNetworkResource``,
  175. ``Runtime.callFunctionOn`` bodies, ``Page.addScriptToEvaluateOnNewDocument`` sources, injected HTML)."""
  176. from tools.browser_url_policy import url_literals
  177. if isinstance(value, str):
  178. return ([value.strip()] if key == "url" and value.strip() else []) + url_literals(value, protocol_relative=True)
  179. if isinstance(value, dict):
  180. return [u for k, v in value.items() for u in _param_url_literals(v, str(k))]
  181. if isinstance(value, (list, tuple)):
  182. return [u for v in value for u in _param_url_literals(v, key)]
  183. return []
  184. def _fetched_param_urls(method: str, params: dict[str, Any]) -> list[str]:
  185. """The distinct URLs a call's params could make the browser fetch (none for text input or the
  186. non-fetching methods above)."""
  187. if method.startswith(_TEXT_INPUT_METHOD_PREFIX) or method in _CDP_NON_FETCHING_METHODS:
  188. return []
  189. return list(dict.fromkeys(_param_url_literals(params)))
  190. def _browser_cdp_private_guard(*, method: str, params: dict[str, Any], endpoint: str = "",
  191. target_id: Optional[str] = None) -> Optional[str]:
  192. """Apply the browser SSRF/private-page guard to raw CDP calls.
  193. Raw CDP shares the cloud/private-network boundary of ``browser_exec``'s URL policy and must not become
  194. its bypass, so a page whose URL cannot be verified as public refuses page-reading methods.
  195. """
  196. from tools.browser_url_policy import eval_ssrf_guard_active, literal_targets_metadata, url_blocked
  197. guard_active = eval_ssrf_guard_active()
  198. guard = _METHOD_PARAM_GUARDS.get(method)
  199. if guard_active and guard is not None:
  200. probe, template = guard
  201. literal = probe(params or {}, url_blocked)
  202. if literal:
  203. return _blocked(template.format(literal), method)
  204. # The cloud-metadata floor applies with the private guard on or off, sidecar and local Chromium included,
  205. # as in browser_exec's _url_policy_error (#16234), to every URL the call could fetch.
  206. literals = _fetched_param_urls(method, params or {})
  207. metadata = next((u for u in literals if literal_targets_metadata(u)), None)
  208. if metadata:
  209. return _blocked(f"Blocked: CDP {method} targets a cloud metadata endpoint ({metadata}).", method)
  210. if not guard_active:
  211. return None
  212. if guard is None:
  213. # A public page does not make an unlisted method's own URL params safe: Network.loadNetworkResource
  214. # fetches its ``url`` from the browser's network position whatever page is open.
  215. literal = next((u for u in literals if u.lower().startswith(("http://", "https://")) and url_blocked(u)), None)
  216. if literal:
  217. return _blocked(f"Blocked: CDP {method} params target a private or internal address ({literal}).",
  218. method)
  219. if method not in _CDP_PRIVATE_PAGE_ALLOWED_METHODS:
  220. blocked_url = _current_page_private_url(endpoint, target_id)
  221. if blocked_url == _PAGE_URL_UNVERIFIED:
  222. return _blocked(f"Blocked: could not read the browser's targets to verify that raw CDP method "
  223. f"{method!r} cannot reach a private or internal page.", method)
  224. if blocked_url:
  225. return _blocked(f"Blocked: page URL targets a private or internal address ({blocked_url}). "
  226. f"Raw CDP method {method!r} could expose private page content or state.", method)
  227. return None
  228. async def _cdp_call(ws_url: str, method: str, params: dict[str, Any], target_id: Optional[str],
  229. timeout: float) -> dict[str, Any]:
  230. """Make a single CDP call. With ``target_id``, ``Target.attachToTarget(flatten=True)`` multiplexes a
  231. page-level session over the browser-level WebSocket; without it ``method`` runs at browser level."""
  232. assert websockets is not None # guarded by _WS_AVAILABLE at call-site
  233. from agent.proxy_bypass import loopback_connect_kwargs
  234. # max_size=None: CDP responses (e.g. DOM.getDocument) can be large; ping_interval=None: CDP
  235. # servers don't expect pings.
  236. async with websockets.connect(ws_url, max_size=None, open_timeout=timeout, close_timeout=5,
  237. ping_interval=None, **loopback_connect_kwargs(ws_url)) as ws:
  238. next_id = 1
  239. async def _send(req: dict[str, Any], what: str) -> dict[str, Any]:
  240. nonlocal next_id
  241. call_id, next_id = next_id, next_id + 1
  242. await ws.send(json.dumps({"id": call_id, **req}))
  243. deadline = asyncio.get_running_loop().time() + timeout
  244. while True: # ignore events / out-of-order responses
  245. remaining = deadline - asyncio.get_running_loop().time()
  246. if remaining <= 0:
  247. raise TimeoutError(f"Timed out {what}")
  248. msg = json.loads(await asyncio.wait_for(ws.recv(), timeout=remaining))
  249. if msg.get("id") == call_id:
  250. return msg
  251. req: dict[str, Any] = {"method": method, "params": params or {}}
  252. if target_id:
  253. msg = await _send({"method": "Target.attachToTarget", "params": {"targetId": target_id, "flatten": True}},
  254. f"attaching to target {target_id}")
  255. if "error" in msg:
  256. raise RuntimeError(f"Target.attachToTarget failed: {msg['error']}")
  257. session_id = msg.get("result", {}).get("sessionId")
  258. if not session_id:
  259. raise RuntimeError("Target.attachToTarget did not return a sessionId")
  260. req["sessionId"] = session_id
  261. msg = await _send(req, f"waiting for response to {method}")
  262. if "error" in msg:
  263. raise RuntimeError(f"CDP error: {msg['error']}")
  264. return msg.get("result", {})
  265. def _browser_cdp_via_supervisor(task_id: str, frame_id: str, method: str, params: Optional[dict[str, Any]],
  266. timeout: float) -> str:
  267. """Route a CDP call through the live supervisor session for an OOPIF frame."""
  268. try:
  269. from tools.browser_supervisor import SUPERVISOR_REGISTRY # type: ignore[import-not-found]
  270. except Exception as exc: # pragma: no cover — defensive
  271. return tool_error(f"CDP supervisor is not available: {exc}. frame_id routing requires a running "
  272. "supervisor attached via /browser connect or an active Browserbase session.")
  273. supervisor = SUPERVISOR_REGISTRY.get(task_id)
  274. if supervisor is None:
  275. return tool_error(f"No CDP supervisor is attached for task={task_id!r}. Call browser_exec or "
  276. "/browser connect first so the supervisor can attach; Page.getFrameTree lists the "
  277. "frame ids you can pass here.")
  278. tree = supervisor.snapshot().frame_tree
  279. frame_info: Optional[dict[str, Any]] = next(
  280. (f for f in [tree.get("top"), *(tree.get("children") or [])] if f and f.get("frame_id") == frame_id), None)
  281. if frame_info is None: # frame_tree is capped at 30 entries — check the raw frames dict too.
  282. with supervisor._state_lock: # type: ignore[attr-defined]
  283. raw = supervisor._frames.get(frame_id) # type: ignore[attr-defined]
  284. frame_info = raw.to_dict() if raw is not None else None
  285. if frame_info is None:
  286. return tool_error(f"frame_id {frame_id!r} not found in supervisor state. "
  287. "Call Page.getFrameTree to see the current frames.")
  288. child_sid = frame_info.get("session_id")
  289. if not child_sid: # same-origin iframes have no dedicated session; reach them via contentWindow/contentDocument
  290. return tool_error(f"frame_id {frame_id!r} is not an out-of-process iframe (no dedicated CDP session). "
  291. "For same-origin iframes, use `browser_cdp(method='Runtime.evaluate', params={'expression': "
  292. "\"document.querySelector('iframe').contentDocument.title\"})` at the top-level page instead.")
  293. loop = supervisor._loop # type: ignore[attr-defined]
  294. if loop is None or not loop.is_running():
  295. return tool_error("CDP supervisor loop is not running. Try reconnecting with /browser connect.")
  296. try:
  297. from agent.async_utils import safe_schedule_threadsafe
  298. fut = safe_schedule_threadsafe(
  299. supervisor._cdp(method, params or {}, session_id=child_sid, timeout=timeout), loop) # type: ignore[attr-defined]
  300. if fut is None:
  301. return tool_error("CDP call via supervisor failed: loop unavailable", cdp_docs=CDP_DOCS_URL)
  302. result_msg = fut.result(timeout=timeout + 2)
  303. except Exception as exc:
  304. return tool_error(f"CDP call via supervisor failed: {type(exc).__name__}: {exc}", cdp_docs=CDP_DOCS_URL)
  305. return json.dumps({"success": True, "method": method, "frame_id": frame_id, "session_id": child_sid,
  306. "result": result_msg.get("result", {})}, ensure_ascii=False)
  307. def browser_cdp(method: str, params: Optional[dict[str, Any]] = None, target_id: Optional[str] = None,
  308. frame_id: Optional[str] = None, timeout: float = 30.0, task_id: Optional[str] = None) -> str:
  309. """Send a raw CDP command (see ``CDP_DOCS_URL``). ``target_id`` attaches a fresh stateless connection
  310. to a tab; ``frame_id`` (an OOPIF from ``Page.getFrameTree``) routes through the supervisor's live
  311. WebSocket instead — the only reliable way to evaluate inside an iframe where fresh per-call connections
  312. hit signed-URL expiry (Browserbase). Both paths share the same private-page/SSRF guard. Returns JSON
  313. ``{"success": True, "method", "result"}`` or ``{"error": ...}``."""
  314. effective_task_id = task_id or "default"
  315. if frame_id:
  316. # An OOPIF's frame id is its iframe target id, so the guard judges that frame (or fails closed).
  317. blocked = _browser_cdp_private_guard(method=method, params=params or {}, target_id=frame_id,
  318. endpoint=_resolve_cdp_endpoint() if _WS_AVAILABLE else "")
  319. if blocked:
  320. return blocked
  321. return _browser_cdp_via_supervisor(task_id=effective_task_id, frame_id=frame_id, method=method,
  322. params=params, timeout=timeout)
  323. if not method or not isinstance(method, str):
  324. return tool_error("'method' is required (e.g. 'Target.getTargets')", cdp_docs=CDP_DOCS_URL)
  325. if not _WS_AVAILABLE:
  326. return tool_error("The 'websockets' Python package is required but not installed. "
  327. "Run: hermes pm repair")
  328. endpoint = _resolve_cdp_endpoint()
  329. if not endpoint:
  330. return tool_error("No CDP endpoint is available. Run '/browser connect' to attach to a running Chrome, "
  331. "Brave, Chromium, or Edge browser, or set 'browser.cdp_url' in config.yaml.", cdp_docs=CDP_DOCS_URL)
  332. if not endpoint.startswith(("ws://", "wss://")):
  333. return tool_error(f"CDP endpoint is not a WebSocket URL: {endpoint!r}. Expected ws://... or wss://... — "
  334. "the /browser connect resolver should have rewritten this. Check that a Chromium-family "
  335. "browser is actually listening on the debug port.")
  336. call_params: dict[str, Any] = params or {}
  337. if not isinstance(call_params, dict):
  338. return tool_error(f"'params' must be an object/dict, got {type(call_params).__name__}")
  339. blocked = _browser_cdp_private_guard(method=method, params=call_params, endpoint=endpoint, target_id=target_id)
  340. if blocked:
  341. return blocked
  342. try:
  343. safe_timeout = float(timeout) if timeout else 30.0
  344. except (TypeError, ValueError):
  345. safe_timeout = 30.0
  346. safe_timeout = max(1.0, min(safe_timeout, 300.0))
  347. try:
  348. result = _run_async(_cdp_call(endpoint, method, call_params, target_id, safe_timeout))
  349. except TimeoutError as exc:
  350. return tool_error(f"CDP call timed out after {safe_timeout}s: {exc}", method=method)
  351. except RuntimeError as exc:
  352. return tool_error(str(exc), method=method)
  353. except WebSocketException as exc:
  354. return tool_error(f"WebSocket error talking to CDP at {endpoint}: {exc}. The browser may have "
  355. "disconnected — try '/browser connect' again.", method=method)
  356. except Exception as exc: # pragma: no cover — unexpected
  357. logger.exception("browser_cdp unexpected error")
  358. return tool_error(f"Unexpected error: {type(exc).__name__}: {exc}", method=method)
  359. payload: dict[str, Any] = {"success": True, "method": method, "result": _redact_cdp_output(
  360. result, always_paths=_CDP_ALWAYS_BINARY_PATHS.get(method, ()),
  361. flagged_paths=_CDP_FLAGGED_BINARY_PATHS.get(method, ()))}
  362. if target_id:
  363. payload["target_id"] = target_id
  364. return json.dumps(payload, ensure_ascii=False)
  365. BROWSER_CDP_SCHEMA: dict[str, Any] = {
  366. "name": "browser_cdp",
  367. "description": (
  368. "Send a raw Chrome DevTools Protocol (CDP) command. Escape hatch for browser operations the other "
  369. "browser tools don't cover.\n\n"
  370. "**Requires a reachable CDP endpoint.** Available when the user has run '/browser connect' to attach "
  371. "to a running Chrome, Brave, Chromium, or Edge browser, or when 'browser.cdp_url' is set in "
  372. "config.yaml. Not currently wired up for cloud backends (Browserbase, Browser Use, Firecrawl) — "
  373. "those expose CDP per session but live-session routing is a follow-up. If the tool is in your toolset "
  374. "at all, a CDP endpoint is already reachable.\n\n"
  375. f"**CDP method reference:** {CDP_DOCS_URL} — use an available documentation lookup or extraction "
  376. "tool on a method's URL (e.g. '/tot/Page/#method-handleJavaScriptDialog') to look up parameters and "
  377. "return shape.\n\n"
  378. "**Common patterns:**\n"
  379. "- List tabs: method='Target.getTargets', params={}\n"
  380. "- Handle a native JS dialog: method='Page.handleJavaScriptDialog', "
  381. "params={'accept': true, 'promptText': ''}, target_id=<tabId>\n"
  382. "- Get all cookies: method='Network.getAllCookies', params={}\n"
  383. "- Eval in a specific tab: method='Runtime.evaluate', params={'expression': '...', 'returnByValue': true}, "
  384. "target_id=<tabId>\n"
  385. "- Set viewport for a tab: method='Emulation.setDeviceMetricsOverride', "
  386. "params={'width': 1280, 'height': 720, 'deviceScaleFactor': 1, 'mobile': false}, target_id=<tabId>\n\n"
  387. "**Usage rules:**\n"
  388. "- Browser-level methods (Target.*, Browser.*, Storage.*): omit target_id and frame_id.\n"
  389. "- Page-level methods (Page.*, Runtime.*, DOM.*, Emulation.*, Network.* scoped to a tab): pass "
  390. "target_id from Target.getTargets.\n"
  391. "- **Cross-origin iframe scope** (Runtime.evaluate inside an OOPIF, Page.* targeting a frame target, "
  392. "etc.): pass a frame_id from Page.getFrameTree. This routes through the CDP "
  393. "supervisor's live connection — the only reliable way on Browserbase where stateless CDP calls hit "
  394. "signed-URL expiry.\n"
  395. "- Each stateless call (without frame_id) is independent — sessions and event subscriptions do not "
  396. "persist between calls. For stateful workflows, prefer the dedicated browser tools or use frame_id "
  397. "routing."
  398. ),
  399. "parameters": {
  400. "type": "object",
  401. "properties": {
  402. "method": {"type": "string", "description": (
  403. "CDP method name, e.g. 'Target.getTargets', 'Runtime.evaluate', 'Page.handleJavaScriptDialog'.")},
  404. "params": {"type": "object", "properties": {}, "additionalProperties": True, "description": (
  405. "Method-specific parameters as a JSON object. Omit or pass {} for methods that take no parameters.")},
  406. "target_id": {"type": "string", "description": (
  407. "Optional. Target/tab ID from Target.getTargets result (each entry's 'targetId'). Use for "
  408. "page-level methods at the top-level tab scope. Mutually exclusive with frame_id.")},
  409. "frame_id": {"type": "string", "description": (
  410. "Optional. Out-of-process iframe (OOPIF) frame id from Page.getFrameTree. "
  411. "When set, routes the call through the CDP supervisor's live session for "
  412. "that iframe. Essential for Runtime.evaluate inside cross-origin iframes, especially on "
  413. "Browserbase where fresh per-call CDP connections can't keep up with signed URL rotation. For "
  414. "same-origin iframes, use parent contentWindow/contentDocument from Runtime.evaluate at the "
  415. "top-level page instead.")},
  416. "timeout": {"type": "number", "default": 30, "description": "Timeout in seconds (default 30, max 300)."},
  417. },
  418. "required": ["method"],
  419. },
  420. }
  421. def _browser_cdp_check() -> bool:
  422. """Availability check: offered only when a static CDP URL is set (a launched or cloud per-session
  423. ``cdp_url`` isn't surfaced) and the browser surface exists (browser-harness importable). Raw (no-I/O)
  424. gate: check_fns run at every startup, and resolving the endpoint over HTTP here would block launch on
  425. a stale endpoint."""
  426. from tools.browser_session_cdp import get_cdp_override_raw
  427. from tools.browser_use_cli import browser_exec_available
  428. return bool(browser_exec_available() and get_cdp_override_raw())
  429. registry.register(
  430. name="browser_cdp",
  431. toolset="browser-cdp",
  432. schema=BROWSER_CDP_SCHEMA,
  433. handler=lambda args, **kw: browser_cdp(
  434. method=args.get("method", ""), params=args.get("params"), target_id=args.get("target_id"),
  435. frame_id=args.get("frame_id"), timeout=args.get("timeout", 30.0), task_id=kw.get("task_id"),
  436. ),
  437. check_fn=_browser_cdp_check,
  438. emoji="🧪",
  439. )