browser_supervisor.py 28 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580
  1. """Persistent CDP supervisor for browser dialog + frame detection.
  2. One ``CDPSupervisor`` per Hermes ``task_id`` with a reachable CDP endpoint: one
  3. persistent WebSocket, ``Page`` / ``Runtime`` / ``Target`` events on every attached
  4. session (top page + auto-attached OOPIF / worker targets), pending dialogs + frame
  5. tree exposed via a thread-safe snapshot. Not in the tool schema — output reaches the
  6. agent via ``browser_dialog``. Dialog capture and frame tracking
  7. are mixins (``browser_supervisor_dialogs`` / ``browser_supervisor_frames``).
  8. Design spec: ``website/docs/developer-guide/browser-supervisor.md``.
  9. """
  10. from __future__ import annotations
  11. import asyncio
  12. import contextlib
  13. import json
  14. import logging
  15. import threading
  16. import time
  17. from dataclasses import dataclass
  18. from typing import Any, Callable, Dict, List, Optional, Tuple, TYPE_CHECKING
  19. from tools.browser_supervisor_dialogs import (
  20. DEFAULT_DIALOG_POLICY, DEFAULT_DIALOG_TIMEOUT_S, RECENT_DIALOGS_MAX, _VALID_POLICIES, DialogRecord,
  21. DialogSupervisionMixin, PendingDialog,
  22. )
  23. from tools.browser_supervisor_frames import FrameInfo, FrameTrackingMixin
  24. # ``websockets`` costs ~22 ms at import and is only needed once a supervisor connects.
  25. if TYPE_CHECKING:
  26. from websockets.asyncio.client import ClientConnection
  27. from tools.browser_supervisor_capture import CapturedCDP
  28. logger = logging.getLogger(__name__)
  29. # Browserbase can transiently drop a CDP socket while a short-lived client
  30. # reconnects. A locally owned browser endpoint, however, is gone for good
  31. # once its process exits; leave enough room for the former without leaking a
  32. # supervisor thread and warnings forever for the latter.
  33. MAX_POST_ATTACH_RECONNECT_FAILURES = 5
  34. def _redact_cdp_error_text(exc: object) -> str:
  35. """Redact CDP endpoint credentials from an exception's (or URL's) string form.
  36. ``websockets`` bakes the raw URL (``?token=`` / ``user:pass@``) into its exception
  37. messages, so every egress point turning one into log/re-raise text MUST route through
  38. here; falls back to a fixed sentinel if redaction itself raises (err toward masking)."""
  39. try:
  40. from agent.redact import redact_cdp_url
  41. return redact_cdp_url(str(exc))
  42. except Exception:
  43. return "<error redacted>"
  44. class _LoopUnavailable(RuntimeError):
  45. """The supervisor loop refused new work (closed / shutting down)."""
  46. def _schedule(coro, loop, *, timeout: float):
  47. """Run ``coro`` on the supervisor loop from a sync caller and wait for its result."""
  48. from agent.async_utils import safe_schedule_threadsafe
  49. fut = safe_schedule_threadsafe(coro, loop)
  50. if fut is None:
  51. raise _LoopUnavailable("Browser supervisor loop unavailable")
  52. return fut.result(timeout=timeout)
  53. def _fail(error: str) -> dict[str, Any]:
  54. return {"ok": False, "error": error}
  55. def _err(exc: BaseException) -> dict[str, Any]:
  56. return _fail(f"{type(exc).__name__}: {exc}")
  57. @dataclass(frozen=True)
  58. class SupervisorSnapshot:
  59. """Read-only snapshot of supervisor state for tool handlers."""
  60. pending_dialogs: tuple[PendingDialog, ...]
  61. recent_dialogs: tuple[DialogRecord, ...]
  62. frame_tree: dict[str, Any]
  63. active: bool # False if supervisor is detached/stopped
  64. cdp_url: str
  65. task_id: str
  66. def to_dict(self) -> dict[str, Any]:
  67. """Serialize for inclusion in tool output."""
  68. out: dict[str, Any] = {"pending_dialogs": [d.to_dict() for d in self.pending_dialogs], "frame_tree": self.frame_tree}
  69. if self.recent_dialogs:
  70. out["recent_dialogs"] = [d.to_dict() for d in self.recent_dialogs]
  71. return out
  72. class CDPSupervisor(DialogSupervisionMixin, FrameTrackingMixin):
  73. """One supervisor per (task_id, cdp_url) pair. ``start()`` spawns a daemon thread
  74. running its own asyncio loop, connects, attaches to the first page target, enables
  75. domains and auto-attach. ``snapshot()`` / ``respond_to_dialog()`` / ``evaluate_runtime()``
  76. are sync, thread-safe bridges onto that loop; all CDP I/O lives on the loop."""
  77. def __init__(self, task_id: str, cdp_url: str, *, dialog_policy: str = DEFAULT_DIALOG_POLICY,
  78. dialog_timeout_s: float = DEFAULT_DIALOG_TIMEOUT_S) -> None:
  79. if dialog_policy not in _VALID_POLICIES:
  80. raise ValueError(f"Invalid dialog_policy {dialog_policy!r}; must be one of {sorted(_VALID_POLICIES)}")
  81. self.task_id = task_id
  82. self.cdp_url = cdp_url
  83. self.dialog_policy = dialog_policy
  84. self.dialog_timeout_s = float(dialog_timeout_s)
  85. # State protected by ``_state_lock`` for cross-thread reads.
  86. self._state_lock = threading.Lock()
  87. self._pending_dialogs: dict[str, PendingDialog] = {}
  88. self._recent_dialogs: list[DialogRecord] = []
  89. self._frames: dict[str, FrameInfo] = {}
  90. self._active = False
  91. # Supervisor loop machinery — populated in start().
  92. self._loop: Optional[asyncio.AbstractEventLoop] = None
  93. self._thread: Optional[threading.Thread] = None
  94. self._ready_event = threading.Event()
  95. self._start_error: Optional[BaseException] = None
  96. self._stop_requested = False
  97. # CDP call tracking (runs on supervisor loop only).
  98. self._next_call_id = 1
  99. self._pending_calls: dict[int, asyncio.Future] = {}
  100. self._ws: Optional[ClientConnection] = None
  101. self._page_session_id: Optional[str] = None
  102. # Dialog auto-dismiss watchdog handles (per dialog id) + id generator.
  103. self._dialog_watchdogs: dict[str, asyncio.TimerHandle] = {}
  104. self._dialog_seq = 0
  105. # ── Public sync API ──────────────────────────────────────────────────────
  106. def start(self, timeout: float = 15.0) -> None:
  107. """Launch the background loop and block until attachment completes; raises what attach failed with (redacted)."""
  108. if self._thread and self._thread.is_alive():
  109. return
  110. self._ready_event.clear()
  111. self._start_error, self._stop_requested = None, False
  112. self._thread = threading.Thread(target=self._thread_main, name=f"cdp-supervisor-{self.task_id}", daemon=True)
  113. self._thread.start()
  114. if not self._ready_event.wait(timeout=timeout):
  115. self.stop()
  116. raise TimeoutError(f"CDP supervisor did not attach within {timeout}s "
  117. f"(cdp_url={_redact_cdp_error_text(self.cdp_url)[:80]}...)")
  118. if (err := self._start_error) is not None:
  119. self.stop()
  120. # ``err`` is a raw ``websockets`` exception embedding the full cdp_url (token /
  121. # userinfo): re-raise redacted, ``from None`` so the traceback chain leaks nothing.
  122. raise RuntimeError(f"CDP supervisor failed to start: {_redact_cdp_error_text(err)}") from None
  123. def stop(self, timeout: float = 5.0) -> None:
  124. """Cancel the supervisor task and join the thread."""
  125. self._stop_requested = True
  126. loop = self._loop
  127. if loop is not None and loop.is_running():
  128. # Close the WebSocket from inside the loop so ``async for raw in self._ws``
  129. # returns cleanly, ``_run`` hits its ``finally``, THEN the thread exits.
  130. with contextlib.suppress(Exception): # loop already shutting down / close timed out
  131. _schedule(self._close_ws(), loop, timeout=2.0)
  132. if self._thread is not None:
  133. self._thread.join(timeout=timeout)
  134. self._set_active(False)
  135. def _set_active(self, value: bool) -> None:
  136. with self._state_lock:
  137. self._active = value
  138. def snapshot(self) -> SupervisorSnapshot:
  139. """Return an immutable snapshot of current state."""
  140. with self._state_lock:
  141. return SupervisorSnapshot(
  142. pending_dialogs=tuple(self._pending_dialogs.values()),
  143. recent_dialogs=tuple(self._recent_dialogs[-RECENT_DIALOGS_MAX:]),
  144. frame_tree=self._build_frame_tree_locked(),
  145. active=self._active, cdp_url=self.cdp_url, task_id=self.task_id,
  146. )
  147. def respond_to_dialog(self, action: str, *, prompt_text: Optional[str] = None,
  148. dialog_id: Optional[str] = None, timeout: float = 10.0) -> dict[str, Any]:
  149. """Accept/dismiss a pending dialog (sync bridge onto the supervisor loop). Returns
  150. ``{"ok": True, "dialog"}`` or ``{"ok": False, "error"}`` for recoverable errors."""
  151. if action not in {"accept", "dismiss"}:
  152. return _fail(f"action must be 'accept' or 'dismiss', got {action!r}")
  153. with self._state_lock:
  154. if not self._active:
  155. return _fail("supervisor is not active")
  156. pending = list(self._pending_dialogs.values())
  157. if not pending:
  158. return _fail("no dialog is currently open")
  159. if dialog_id:
  160. dialog = self._pending_dialogs.get(dialog_id)
  161. if dialog is None:
  162. return _fail(f"dialog_id {dialog_id!r} not found (known: {sorted(self._pending_dialogs)})")
  163. elif len(pending) > 1:
  164. return _fail(f"{len(pending)} pending dialogs; specify dialog_id. Candidates: {[d.id for d in pending]}")
  165. else:
  166. dialog = pending[0]
  167. loop = self._loop
  168. if loop is None:
  169. return _fail("supervisor loop is not running")
  170. try:
  171. coro = self._handle_dialog_cdp(dialog, accept=(action == "accept"), prompt_text=prompt_text or "")
  172. _schedule(coro, loop, timeout=timeout)
  173. except _LoopUnavailable as e:
  174. return _fail(str(e))
  175. except Exception as e:
  176. return _err(e)
  177. return {"ok": True, "dialog": dialog.to_dict()}
  178. def evaluate_runtime(self, expression: str, *, return_by_value: bool = True,
  179. await_promise: bool = True, timeout: float = 10.0) -> dict[str, Any]:
  180. """Evaluate ``expression`` in the page's Runtime context over the live WS.
  181. Returns ``{"ok": True, "result", "result_type"}`` or ``{"ok": False, "error"}``.
  182. ``return_by_value=True`` JSON-serializes the result (DevTools-console
  183. semantics); non-serializable objects come back as a description string."""
  184. loop = self._loop
  185. if loop is None or not loop.is_running():
  186. return _fail("supervisor loop is not running")
  187. with self._state_lock:
  188. active, session_id = self._active, self._page_session_id
  189. if not active:
  190. return _fail("supervisor is not active")
  191. if not session_id:
  192. return _fail("supervisor has no attached page session")
  193. def _run_eval(by_value: bool) -> dict[str, Any]:
  194. # userGesture: clipboard / fullscreen APIs need user activation.
  195. params = {"expression": expression, "returnByValue": by_value,
  196. "awaitPromise": await_promise, "userGesture": True}
  197. coro = self._cdp("Runtime.evaluate", params, session_id=session_id, timeout=timeout)
  198. return _schedule(coro, loop, timeout=timeout + 1)
  199. try:
  200. response = _run_eval(return_by_value)
  201. except Exception as exc:
  202. # Deep-serializing live DOM nodes / NodeLists / Window can blow past
  203. # CDP's recursion guard (``Object reference chain is too long``).
  204. # Retry once with returnByValue=False so Chrome returns the description.
  205. if not (return_by_value and "reference chain is too long" in str(exc).lower()):
  206. return _err(exc)
  207. try:
  208. response = _run_eval(False)
  209. except Exception as exc2:
  210. return _err(exc2)
  211. # Response: {"result": {"result": {"type", "value", ...}, "exceptionDetails"?}}
  212. result_payload = response.get("result", {}) if isinstance(response, dict) else {}
  213. exception_details = result_payload.get("exceptionDetails")
  214. if exception_details:
  215. exc_text = exception_details.get("text") or "JavaScript exception"
  216. description = (exception_details.get("exception") or {}).get("description")
  217. return _fail(f"{exc_text}: {description}" if description else exc_text)
  218. result_obj = result_payload.get("result", {})
  219. result_type = result_obj.get("type", "undefined")
  220. if "value" in result_obj:
  221. value = result_obj["value"]
  222. elif result_type == "undefined":
  223. value = None
  224. else:
  225. # Non-serializable (functions, DOM nodes…) — give the model the browser's description.
  226. value = result_obj.get("description") or result_obj.get("unserializableValue")
  227. return {"ok": True, "result": value, "result_type": result_type}
  228. def focus_page(self, origin: str, *, accept: Optional[str] = None, timeout: float = 10.0) -> dict[str, Any]:
  229. """Re-attach the supervisor's page session to an open page target on ``origin``
  230. (``scheme://host[:port]``). The initial attach picks the FIRST page target, but tools
  231. that open their own tabs (browser_exec) put the login form somewhere else. With
  232. ``accept`` (a JS expression) the first same-origin tab where it evaluates truthy wins,
  233. so a login and a checkout tab on one site resolve to the right one. Returns
  234. ``{"ok": True, "url"}`` or ``{"ok": False, "error"}``; on failure the previous session stays."""
  235. loop = self._loop
  236. if loop is None or not loop.is_running():
  237. return _fail("supervisor loop is not running")
  238. async def _attach(target_id: str) -> str:
  239. attach = await self._cdp("Target.attachToTarget", {"targetId": target_id, "flatten": True}, timeout=timeout)
  240. sid = attach["result"]["sessionId"]
  241. await self._enable_page_domains(sid, timeout=timeout)
  242. await self._install_dialog_bridge(sid)
  243. return sid
  244. async def _focus() -> dict[str, Any]:
  245. from agent.vault_store import normalize_origin
  246. targets = (await self._cdp("Target.getTargets", timeout=timeout)).get("result", {}).get("targetInfos", [])
  247. candidates = []
  248. for t in targets:
  249. url = str(t.get("url") or "")
  250. try:
  251. # origin="" = any http(s) page (used to FIND the login tab before its origin is known)
  252. if t.get("type") == "page" and url.startswith(("http://", "https://")) \
  253. and (not origin or normalize_origin(url) == origin):
  254. candidates.append((t["targetId"], url))
  255. except Exception:
  256. continue
  257. for target_id, url in candidates:
  258. sid = await _attach(target_id)
  259. if accept:
  260. probe = await self._cdp("Runtime.evaluate", {"expression": accept, "returnByValue": True},
  261. session_id=sid, timeout=timeout)
  262. if not probe.get("result", {}).get("result", {}).get("value"):
  263. await self._cdp("Target.detachFromTarget", {"sessionId": sid}, timeout=timeout)
  264. continue
  265. with self._state_lock:
  266. self._page_session_id = sid
  267. return {"ok": True, "url": url}
  268. return _fail(f"no open page on {origin or 'any site'}" + (" with the expected form" if accept and candidates else ""))
  269. try:
  270. return _schedule(_focus(), loop, timeout=timeout + 1)
  271. except Exception as exc:
  272. return _err(exc)
  273. # ── Supervisor loop internals ────────────────────────────────────────────
  274. def _thread_main(self) -> None:
  275. """Entry point for the supervisor's dedicated thread."""
  276. loop = asyncio.new_event_loop()
  277. self._loop = loop
  278. try:
  279. asyncio.set_event_loop(loop)
  280. loop.run_until_complete(self._run())
  281. except BaseException as e:
  282. if not self._fail_start(e):
  283. logger.warning("CDP supervisor %s crashed: %s", self.task_id, e)
  284. finally:
  285. # Cancel + flush remaining tasks before closing the loop to avoid
  286. # "Task was destroyed but it is pending" warnings.
  287. with contextlib.suppress(Exception):
  288. pending = [t for t in asyncio.all_tasks(loop) if not t.done()]
  289. for t in pending:
  290. t.cancel()
  291. if pending:
  292. loop.run_until_complete(asyncio.gather(*pending, return_exceptions=True))
  293. with contextlib.suppress(Exception):
  294. loop.close()
  295. self._set_active(False)
  296. def _fail_start(self, e: BaseException) -> bool:
  297. """Propagate ``e`` to ``start()`` if we never got ready; True if it was consumed."""
  298. if self._ready_event.is_set():
  299. return False
  300. self._start_error = e
  301. self._ready_event.set()
  302. return True
  303. async def _close_ws(self) -> None:
  304. """Detach and close the current WebSocket, swallowing close errors."""
  305. ws, self._ws = self._ws, None
  306. if ws is not None:
  307. with contextlib.suppress(Exception):
  308. await ws.close()
  309. def _reconnect_budget_spent(self, failures: int, e: BaseException) -> bool:
  310. """True once ``failures`` consecutive post-attach reconnects failed: log ONE final line
  311. and drop this supervisor from the registry so a dead endpoint (its Chrome exited with
  312. the task) leaves neither a retrying thread nor a stale registry entry behind. A later
  313. browser call for the task starts a fresh supervisor via ``get_or_start``."""
  314. if failures < MAX_POST_ATTACH_RECONNECT_FAILURES:
  315. return False
  316. logger.warning("CDP supervisor %s: stopped after %s failed reconnect attempts: %s",
  317. self.task_id, failures, _redact_cdp_error_text(e))
  318. if SUPERVISOR_REGISTRY.get(self.task_id) is self:
  319. SUPERVISOR_REGISTRY._pop(self.task_id)
  320. return True
  321. async def _run(self) -> None:
  322. """Top-level reconnecting supervisor coroutine. Browserbase tears down the CDP
  323. socket whenever a short-lived client (a per-call browser_cdp or harness CDP connection)
  324. disconnects, so on drop we reset per-session ids, re-attach, and keep going.
  325. A failure before the first successful attach is fatal for ``start()``."""
  326. reconnect_failures, last_success_at, backoff = 0, 0.0, 0.5
  327. import websockets # deferred: only supervisors that connect pay the import
  328. from agent.proxy_bypass import loopback_connect_kwargs
  329. connect_kwargs = {"max_size": 50 * 1024 * 1024, **loopback_connect_kwargs(self.cdp_url)}
  330. while not self._stop_requested:
  331. try:
  332. self._ws = await asyncio.wait_for(websockets.connect(self.cdp_url, **connect_kwargs), timeout=10.0)
  333. except Exception as e:
  334. if self._fail_start(e):
  335. return
  336. reconnect_failures += 1
  337. if self._reconnect_budget_spent(reconnect_failures, e):
  338. return
  339. logger.warning("CDP supervisor %s: connect failed (attempt %s/%s): %s",
  340. self.task_id, reconnect_failures, MAX_POST_ATTACH_RECONNECT_FAILURES,
  341. _redact_cdp_error_text(e))
  342. await asyncio.sleep(min(backoff, 10.0))
  343. backoff = min(backoff * 2, 10.0)
  344. continue
  345. reader_task = asyncio.create_task(self._read_loop(), name="cdp-reader")
  346. try:
  347. # Reset the per-connection page session id; ``_pending_dialogs`` / ``_frames``
  348. # are deliberately kept — they reconcile as fresh events arrive (worst case a
  349. # stale dialog entry is rejected with "no dialog is showing", logged only).
  350. self._page_session_id = None
  351. await self._attach_initial_page()
  352. self._set_active(True)
  353. last_success_at = time.time()
  354. reconnect_failures = 0
  355. backoff = 0.5 # reset after a successful attach
  356. self._ready_event.set()
  357. await reader_task
  358. except BaseException as e:
  359. if self._fail_start(e):
  360. raise
  361. reconnect_failures += 1
  362. if self._reconnect_budget_spent(reconnect_failures, e):
  363. return
  364. logger.warning("CDP supervisor %s: session dropped after %.1fs (attempt %s/%s): %s",
  365. self.task_id, time.time() - last_success_at, reconnect_failures,
  366. MAX_POST_ATTACH_RECONNECT_FAILURES, _redact_cdp_error_text(e))
  367. finally:
  368. self._set_active(False)
  369. if not reader_task.done():
  370. reader_task.cancel()
  371. with contextlib.suppress(asyncio.CancelledError, Exception):
  372. await reader_task
  373. for handle in self._dialog_watchdogs.values():
  374. handle.cancel()
  375. self._dialog_watchdogs.clear()
  376. await self._close_ws()
  377. # Replies to calls still in flight died with the socket: fail them now
  378. # instead of letting each caller sit out its full timeout.
  379. for fut in self._pending_calls.values():
  380. if not fut.done():
  381. fut.set_exception(ConnectionError("CDP connection closed before reply"))
  382. self._pending_calls.clear()
  383. if self._stop_requested:
  384. return
  385. logger.debug("CDP supervisor %s: reconnecting in %.1fs...", self.task_id, backoff)
  386. await asyncio.sleep(backoff)
  387. backoff = min(backoff * 2, 10.0)
  388. async def _attach_initial_page(self) -> None:
  389. """Find (or create) a page target, attach flattened, enable domains, install dialog bridge."""
  390. targets = (await self._cdp("Target.getTargets")).get("result", {}).get("targetInfos", [])
  391. page_target = next((t for t in targets if t.get("type") == "page"), None)
  392. if page_target is None:
  393. page_target = (await self._cdp("Target.createTarget", {"url": "about:blank"}))["result"]
  394. attach = await self._cdp("Target.attachToTarget", {"targetId": page_target["targetId"], "flatten": True})
  395. self._page_session_id = sid = attach["result"]["sessionId"]
  396. await self._enable_page_domains(sid, timeout=10.0)
  397. await self._install_dialog_bridge(sid)
  398. async def _cdp(self, method: str, params: Optional[dict[str, Any]] = None, *,
  399. session_id: Optional[str] = None, timeout: Optional[float] = 10.0) -> dict[str, Any]:
  400. """Send a CDP command and await its response."""
  401. if self._ws is None:
  402. raise RuntimeError("supervisor WebSocket is not connected")
  403. call_id, self._next_call_id = self._next_call_id, self._next_call_id + 1
  404. payload: dict[str, Any] = {"id": call_id, "method": method}
  405. payload.update({k: v for k, v in (("params", params), ("sessionId", session_id)) if v})
  406. fut: asyncio.Future = asyncio.get_running_loop().create_future()
  407. self._pending_calls[call_id] = fut
  408. await self._ws.send(json.dumps(payload))
  409. try:
  410. return await asyncio.wait_for(fut, timeout=timeout)
  411. finally:
  412. self._pending_calls.pop(call_id, None)
  413. async def _read_loop(self) -> None:
  414. """Continuously dispatch incoming CDP frames (responses → futures, events → handlers)."""
  415. assert self._ws is not None
  416. try:
  417. async for raw in self._ws:
  418. if self._stop_requested:
  419. break
  420. try:
  421. msg = json.loads(raw)
  422. except Exception:
  423. logger.debug("CDP supervisor: non-JSON frame dropped")
  424. continue
  425. if "id" in msg:
  426. fut = self._pending_calls.pop(msg["id"], None)
  427. if fut is None or fut.done():
  428. continue
  429. if "error" in msg:
  430. fut.set_exception(RuntimeError(f"CDP error on id={msg['id']}: {msg['error']}"))
  431. else:
  432. fut.set_result(msg)
  433. elif handler := self._EVENT_HANDLERS.get(msg.get("method")):
  434. result = handler(self, msg.get("params", {}), msg.get("sessionId"))
  435. if result is not None:
  436. await result
  437. except Exception as e:
  438. logger.debug("CDP read loop exited: %s", e)
  439. # CDP event → handler(self, params, session_id). Async handlers return an
  440. # awaitable that ``_read_loop`` awaits; sync handlers return None.
  441. _EVENT_HANDLERS: dict[str, Callable[..., Any]] = {
  442. **DialogSupervisionMixin.EVENT_HANDLERS, **FrameTrackingMixin.EVENT_HANDLERS
  443. }
  444. class _SupervisorRegistry:
  445. """Process-global (task_id → supervisor) map with idempotent start/stop (``SUPERVISOR_REGISTRY``)."""
  446. def __init__(self) -> None:
  447. self._lock = threading.Lock()
  448. self._by_task: dict[str, CDPSupervisor] = {}
  449. self._home_by_task: dict[str, str] = {} # profile home that started it (``stop_home``)
  450. def get(self, task_id: str) -> Optional[CDPSupervisor]:
  451. with self._lock:
  452. return self._by_task.get(task_id)
  453. def _pop(self, task_id: str) -> Optional[CDPSupervisor]:
  454. with self._lock:
  455. self._home_by_task.pop(task_id, None)
  456. return self._by_task.pop(task_id, None)
  457. def capture(self, task_id: str, *, timeout: float = 10.0) -> CapturedCDP:
  458. """Public CDP seam for trusted in-process plugins: a handle pinned to this task's
  459. current connection and default page session (``tools.browser_supervisor_capture``)."""
  460. from tools.browser_supervisor_capture import capture
  461. return capture(self, task_id, timeout=timeout)
  462. def get_or_start(self, task_id: str, cdp_url: str, *, dialog_policy: str = DEFAULT_DIALOG_POLICY,
  463. dialog_timeout_s: float = DEFAULT_DIALOG_TIMEOUT_S, start_timeout: float = 15.0) -> CDPSupervisor:
  464. """Idempotently ensure a supervisor runs for ``(task_id, cdp_url)``; one bound to a
  465. different ``cdp_url`` or unhealthy (dead thread / stopped loop) is stopped and replaced."""
  466. from hermes_constants import hermes_home_key
  467. home = hermes_home_key()
  468. with self._lock:
  469. existing = self._by_task.get(task_id)
  470. if existing is not None:
  471. thread, loop = existing._thread, existing._loop
  472. healthy = thread is not None and thread.is_alive() and loop is not None and loop.is_running()
  473. if existing.cdp_url == cdp_url and healthy:
  474. return existing
  475. self._by_task.pop(task_id, None)
  476. if existing is not None:
  477. existing.stop()
  478. supervisor = CDPSupervisor(task_id=task_id, cdp_url=cdp_url,
  479. dialog_policy=dialog_policy, dialog_timeout_s=dialog_timeout_s)
  480. supervisor.start(timeout=start_timeout)
  481. with self._lock:
  482. # Guard against a concurrent get_or_start from another thread.
  483. already = self._by_task.get(task_id)
  484. if already is not None and already.cdp_url == cdp_url:
  485. supervisor.stop()
  486. return already
  487. self._by_task[task_id] = supervisor
  488. self._home_by_task[task_id] = home
  489. return supervisor
  490. def stop(self, task_id: str) -> None:
  491. supervisor = self._pop(task_id)
  492. if supervisor is not None:
  493. supervisor.stop()
  494. def stop_home(self, home_key: str) -> None:
  495. """Stop the supervisors one profile home started (``/browser connect`` on a multiplexed gateway)."""
  496. with self._lock:
  497. tasks = [task for task, home in self._home_by_task.items() if home == home_key]
  498. for task_id in tasks:
  499. self.stop(task_id)
  500. def stop_all(self) -> None:
  501. """Stop every running supervisor. For shutdown / test teardown."""
  502. with self._lock:
  503. items = list(self._by_task.values())
  504. self._by_task.clear()
  505. self._home_by_task.clear()
  506. for supervisor in items:
  507. supervisor.stop()
  508. SUPERVISOR_REGISTRY = _SupervisorRegistry()
  509. __all__ = ["SUPERVISOR_REGISTRY", "CDPSupervisor", "SupervisorSnapshot", "_SupervisorRegistry"]