browser-control-and-automation-cli 0.1.1.dev3__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (104) hide show
  1. browser_cli/__init__.py +7 -0
  2. browser_cli/actions/__init__.py +5 -0
  3. browser_cli/actions/cli_specs.py +868 -0
  4. browser_cli/agent_scope/__init__.py +14 -0
  5. browser_cli/automation/__init__.py +11 -0
  6. browser_cli/automation/api/__init__.py +5 -0
  7. browser_cli/automation/api/server.py +321 -0
  8. browser_cli/automation/hooks.py +42 -0
  9. browser_cli/automation/loader.py +134 -0
  10. browser_cli/automation/models.py +127 -0
  11. browser_cli/automation/persistence/__init__.py +5 -0
  12. browser_cli/automation/persistence/store.py +682 -0
  13. browser_cli/automation/projections.py +279 -0
  14. browser_cli/automation/publisher.py +153 -0
  15. browser_cli/automation/scheduler/__init__.py +5 -0
  16. browser_cli/automation/scheduler/schedule.py +113 -0
  17. browser_cli/automation/service/__init__.py +8 -0
  18. browser_cli/automation/service/__main__.py +64 -0
  19. browser_cli/automation/service/client.py +232 -0
  20. browser_cli/automation/service/runtime.py +388 -0
  21. browser_cli/automation/toml.py +35 -0
  22. browser_cli/automation/web/__init__.py +5 -0
  23. browser_cli/automation/web/assets.py +377 -0
  24. browser_cli/browser/__init__.py +1 -0
  25. browser_cli/browser/models.py +44 -0
  26. browser_cli/browser/network_capture.py +392 -0
  27. browser_cli/browser/service.py +1519 -0
  28. browser_cli/browser/session.py +158 -0
  29. browser_cli/browser/snapshot.py +35 -0
  30. browser_cli/browser/stealth.py +450 -0
  31. browser_cli/cli/__init__.py +1 -0
  32. browser_cli/cli/error_hints.py +26 -0
  33. browser_cli/cli/main.py +298 -0
  34. browser_cli/commands/__init__.py +1 -0
  35. browser_cli/commands/action.py +25 -0
  36. browser_cli/commands/automation.py +304 -0
  37. browser_cli/commands/doctor.py +336 -0
  38. browser_cli/commands/install_skills.py +138 -0
  39. browser_cli/commands/paths.py +31 -0
  40. browser_cli/commands/read.py +33 -0
  41. browser_cli/commands/reload.py +51 -0
  42. browser_cli/commands/status.py +444 -0
  43. browser_cli/commands/task.py +71 -0
  44. browser_cli/constants.py +97 -0
  45. browser_cli/daemon/__init__.py +1 -0
  46. browser_cli/daemon/__main__.py +34 -0
  47. browser_cli/daemon/app.py +941 -0
  48. browser_cli/daemon/browser_service.py +998 -0
  49. browser_cli/daemon/client.py +280 -0
  50. browser_cli/daemon/models.py +63 -0
  51. browser_cli/daemon/runtime_presentation.py +167 -0
  52. browser_cli/daemon/server.py +103 -0
  53. browser_cli/daemon/state.py +15 -0
  54. browser_cli/daemon/transport.py +77 -0
  55. browser_cli/drivers/__init__.py +6 -0
  56. browser_cli/drivers/_extension/__init__.py +1 -0
  57. browser_cli/drivers/_extension/artifact_actions.py +154 -0
  58. browser_cli/drivers/_extension/dialog_actions.py +35 -0
  59. browser_cli/drivers/_extension/input_actions.py +63 -0
  60. browser_cli/drivers/_extension/locator_actions.py +100 -0
  61. browser_cli/drivers/_extension/observe_actions.py +285 -0
  62. browser_cli/drivers/_extension/page_actions.py +210 -0
  63. browser_cli/drivers/_extension/state_actions.py +134 -0
  64. browser_cli/drivers/base.py +391 -0
  65. browser_cli/drivers/extension_driver.py +33 -0
  66. browser_cli/drivers/models.py +21 -0
  67. browser_cli/drivers/playwright_driver.py +499 -0
  68. browser_cli/error_codes.py +27 -0
  69. browser_cli/errors.py +146 -0
  70. browser_cli/exit_codes.py +9 -0
  71. browser_cli/extension/__init__.py +32 -0
  72. browser_cli/extension/protocol.py +222 -0
  73. browser_cli/extension/session.py +393 -0
  74. browser_cli/network.py +147 -0
  75. browser_cli/outputs/__init__.py +1 -0
  76. browser_cli/outputs/json.py +10 -0
  77. browser_cli/outputs/render.py +7 -0
  78. browser_cli/packaged_skills/__init__.py +1 -0
  79. browser_cli/packaged_skills/browser-cli-converge/SKILL.md +62 -0
  80. browser_cli/packaged_skills/browser-cli-delivery/SKILL.md +61 -0
  81. browser_cli/packaged_skills/browser-cli-explore/SKILL.md +77 -0
  82. browser_cli/profiles/__init__.py +1 -0
  83. browser_cli/profiles/discovery.py +185 -0
  84. browser_cli/refs/__init__.py +17 -0
  85. browser_cli/refs/generator.py +386 -0
  86. browser_cli/refs/models.py +127 -0
  87. browser_cli/refs/registry.py +51 -0
  88. browser_cli/refs/resolver.py +214 -0
  89. browser_cli/tabs/__init__.py +5 -0
  90. browser_cli/tabs/registry.py +283 -0
  91. browser_cli/task_runtime/__init__.py +31 -0
  92. browser_cli/task_runtime/client.py +107 -0
  93. browser_cli/task_runtime/entrypoint.py +110 -0
  94. browser_cli/task_runtime/errors.py +17 -0
  95. browser_cli/task_runtime/flow.py +171 -0
  96. browser_cli/task_runtime/models.py +97 -0
  97. browser_cli/task_runtime/read.py +71 -0
  98. browser_cli/task_runtime/templates.py +58 -0
  99. browser_control_and_automation_cli-0.1.1.dev3.dist-info/METADATA +340 -0
  100. browser_control_and_automation_cli-0.1.1.dev3.dist-info/RECORD +104 -0
  101. browser_control_and_automation_cli-0.1.1.dev3.dist-info/WHEEL +5 -0
  102. browser_control_and_automation_cli-0.1.1.dev3.dist-info/entry_points.txt +2 -0
  103. browser_control_and_automation_cli-0.1.1.dev3.dist-info/licenses/LICENSE +21 -0
  104. browser_control_and_automation_cli-0.1.1.dev3.dist-info/top_level.txt +1 -0
@@ -0,0 +1,998 @@
1
+ """Driver-managing browser service used by the daemon."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import asyncio
6
+ import contextlib
7
+ import logging
8
+ from dataclasses import dataclass
9
+ from typing import Any
10
+
11
+ from browser_cli.daemon.runtime_presentation import build_runtime_presentation
12
+ from browser_cli.drivers.base import BrowserDriver
13
+ from browser_cli.drivers.extension_driver import ExtensionDriver
14
+ from browser_cli.drivers.playwright_driver import PlaywrightDriver
15
+ from browser_cli.errors import (
16
+ EmptyContentError,
17
+ InvalidInputError,
18
+ NoSnapshotContextError,
19
+ OperationFailedError,
20
+ RefNotFoundError,
21
+ )
22
+ from browser_cli.extension import ExtensionHub
23
+ from browser_cli.profiles.discovery import ChromeEnvironment
24
+ from browser_cli.refs import SemanticRefResolver, SemanticSnapshotGenerator, SnapshotRegistry
25
+ from browser_cli.tabs import TabRegistry
26
+ from browser_cli.tabs.registry import TabRecord
27
+
28
+ logger = logging.getLogger(__name__)
29
+
30
+
31
+ @dataclass(slots=True)
32
+ class _StabilityMetrics:
33
+ commands_started: int = 0
34
+ driver_switches: int = 0
35
+ workspace_rebuilds: int = 0
36
+ extension_disconnects: int = 0
37
+ cleanup_failures: int = 0
38
+ last_cleanup_error: str | None = None
39
+ active_command: str | None = None
40
+
41
+ def snapshot(self, *, command_depth: int) -> dict[str, Any]:
42
+ return {
43
+ "active_command": self.active_command,
44
+ "command_depth": command_depth,
45
+ "commands_started": self.commands_started,
46
+ "driver_switches": self.driver_switches,
47
+ "workspace_rebuilds": self.workspace_rebuilds,
48
+ "extension_disconnects": self.extension_disconnects,
49
+ "cleanup_failures": self.cleanup_failures,
50
+ "last_cleanup_error": self.last_cleanup_error,
51
+ }
52
+
53
+
54
+ class BrowserService:
55
+ INITIAL_EXTENSION_WAIT_SECONDS = 3.0
56
+ READ_NAVIGATION_TIMEOUT_SECONDS = 30.0
57
+ READ_SETTLE_TIMEOUT_MS = 1_200
58
+ READ_SCROLL_PAUSE_MS = 450
59
+ READ_SCROLL_MAX_ROUNDS = 8
60
+ READ_SCROLL_STABLE_ROUNDS = 2
61
+
62
+ def __init__(
63
+ self,
64
+ tabs: TabRegistry | None = None,
65
+ chrome_environment: ChromeEnvironment | None = None,
66
+ *,
67
+ headless: bool | None = None,
68
+ ) -> None:
69
+ self._tabs = tabs or TabRegistry()
70
+ self._playwright = PlaywrightDriver(
71
+ chrome_environment=chrome_environment, headless=headless
72
+ )
73
+ self._extension_hub = ExtensionHub()
74
+ if hasattr(self._extension_hub, "set_status_provider"):
75
+ self._extension_hub.set_status_provider(self.runtime_status_for_popup)
76
+ if hasattr(self._extension_hub, "set_workspace_rebuild_handler"):
77
+ self._extension_hub.set_workspace_rebuild_handler(self.rebuild_workspace_binding)
78
+ self._extension = ExtensionDriver(self._extension_hub)
79
+ self._snapshot_registry = SnapshotRegistry()
80
+ self._ref_resolver = SemanticRefResolver()
81
+ self._snapshot_generator = SemanticSnapshotGenerator()
82
+ self._driver_name: str | None = None
83
+ self._driver: BrowserDriver | None = None
84
+ self._watch_task: asyncio.Task[None] | None = None
85
+ self._command_depth = 0
86
+ self._pending_driver: str | None = None
87
+ self._pending_reason: str | None = None
88
+ self._last_runtime_meta: dict[str, Any] = {}
89
+ self._last_transition: dict[str, Any] | None = None
90
+ self._stability = _StabilityMetrics()
91
+ self._page_counter = 0
92
+ self._rebind_lock = asyncio.Lock()
93
+
94
+ @property
95
+ def chrome_environment(self) -> ChromeEnvironment | None:
96
+ if self._driver_name == "playwright":
97
+ return self._playwright.chrome_environment
98
+ return None
99
+
100
+ def configure_environment(self, chrome_environment: ChromeEnvironment) -> None:
101
+ self._playwright.configure_environment(chrome_environment)
102
+
103
+ async def ensure_extension_listener_started(self) -> None:
104
+ await self._extension_hub.ensure_started()
105
+
106
+ async def begin_command(self, action: str) -> None:
107
+ await self.ensure_started()
108
+ self._stability.commands_started += 1
109
+ self._stability.active_command = action
110
+ if self._driver_name == "extension":
111
+ session = self._extension_hub.session
112
+ if session is None or not session.hello.has_required_capabilities():
113
+ self._stability.extension_disconnects += 1
114
+ logger.warning(
115
+ "Extension unavailable at command start; rebinding to playwright for action=%s",
116
+ action,
117
+ )
118
+ await self._activate_driver("playwright", reason="extension-disconnected-command")
119
+ await self._maybe_apply_pending_rebind()
120
+ self._command_depth += 1
121
+ self._last_runtime_meta = {"driver": self.active_driver_name, "command": action}
122
+
123
+ async def end_command(self) -> dict[str, Any]:
124
+ self._command_depth = max(0, self._command_depth - 1)
125
+ if self._command_depth == 0:
126
+ self._stability.active_command = None
127
+ await self._maybe_apply_pending_rebind()
128
+ meta = dict(self._last_runtime_meta)
129
+ self._last_runtime_meta = {}
130
+ return meta
131
+
132
+ @property
133
+ def active_driver_name(self) -> str:
134
+ return self._driver_name or "playwright"
135
+
136
+ async def ensure_started(self) -> None:
137
+ await self._extension_hub.ensure_started()
138
+ if self._watch_task is None:
139
+ self._watch_task = asyncio.create_task(self._watch_extension_changes())
140
+ if self._driver is not None:
141
+ return
142
+ session = None
143
+ try:
144
+ session = await self._extension_hub.wait_for_session(
145
+ self.INITIAL_EXTENSION_WAIT_SECONDS
146
+ )
147
+ except asyncio.CancelledError:
148
+ raise
149
+ except TimeoutError:
150
+ logger.info(
151
+ "Extension did not connect within %.1fs; falling back to playwright",
152
+ self.INITIAL_EXTENSION_WAIT_SECONDS,
153
+ )
154
+ except Exception:
155
+ logger.warning(
156
+ "Extension startup wait failed; falling back to playwright",
157
+ exc_info=True,
158
+ )
159
+ target = (
160
+ "extension" if session and session.hello.has_required_capabilities() else "playwright"
161
+ )
162
+ logger.info("Selecting startup driver=%s", target)
163
+ await self._activate_driver(target, reason="startup")
164
+
165
+ async def stop(self) -> dict[str, Any]:
166
+ if self._watch_task is not None:
167
+ self._watch_task.cancel()
168
+ try:
169
+ await self._watch_task
170
+ except asyncio.CancelledError:
171
+ pass
172
+ except Exception:
173
+ pass
174
+ self._watch_task = None
175
+ shutdown: dict[str, Any] = {}
176
+ cleanup_error: str | None = None
177
+ try:
178
+ if self._driver_name == "extension":
179
+ shutdown = await self._extension.stop()
180
+ elif self._driver_name == "playwright":
181
+ shutdown = await self._playwright.stop()
182
+ else:
183
+ shutdown = {}
184
+ except Exception as exc:
185
+ cleanup_error = str(exc)
186
+ logger.warning(
187
+ "Driver stop failed for %s: %s", self._driver_name or "none", cleanup_error
188
+ )
189
+ shutdown = {}
190
+ await self._extension_hub.stop()
191
+ with contextlib.suppress(Exception):
192
+ await self._playwright.stop()
193
+ self._driver = None
194
+ self._driver_name = None
195
+ self._stability.active_command = None
196
+ self._snapshot_registry.clear()
197
+ if cleanup_error:
198
+ shutdown["cleanup_error"] = cleanup_error
199
+ return shutdown
200
+
201
+ async def runtime_status(self, *, warmup: bool = False) -> dict[str, Any]:
202
+ if warmup:
203
+ await self.ensure_started()
204
+ extension_health = await self._extension.health()
205
+ playwright_health = await self._playwright.health()
206
+ extension_details = dict(extension_health.details)
207
+ playwright_details = dict(playwright_health.details)
208
+ workspace_window_state = dict(extension_details.get("workspace_window_state") or {})
209
+ if self._driver_name == "extension" or bool(extension_details.get("connected")):
210
+ with contextlib.suppress(Exception):
211
+ workspace_window_state = await self._extension.workspace_status()
212
+ profile_source: str | None = None
213
+ profile_dir: str | None = None
214
+ profile_directory: str | None = None
215
+ if self._driver_name == "extension":
216
+ profile_source = "extension"
217
+ else:
218
+ environment = self._playwright.chrome_environment
219
+ if environment is not None:
220
+ profile_source = environment.source
221
+ profile_dir = str(environment.user_data_dir)
222
+ profile_directory = environment.profile_directory
223
+ return {
224
+ "browser_started": self._driver is not None,
225
+ "active_driver": self._driver_name,
226
+ "profile_source": profile_source,
227
+ "profile_dir": profile_dir,
228
+ "profile_directory": profile_directory,
229
+ "playwright": {
230
+ "available": playwright_health.available,
231
+ "details": playwright_details,
232
+ },
233
+ "extension": {
234
+ "available": extension_health.available,
235
+ "connected": bool(extension_details.get("connected")),
236
+ "capability_complete": bool(extension_details.get("capability_complete")),
237
+ "missing_capabilities": list(extension_details.get("missing_capabilities") or []),
238
+ "details": extension_details,
239
+ },
240
+ "workspace_window_state": workspace_window_state,
241
+ "last_transition": (
242
+ dict(self._last_transition) if self._last_transition is not None else None
243
+ ),
244
+ "pending_rebind": (
245
+ {
246
+ "target": self._pending_driver,
247
+ "reason": self._pending_reason,
248
+ }
249
+ if self._pending_driver
250
+ else (
251
+ {
252
+ "target": "playwright",
253
+ "reason": "extension-disconnected-waiting-command",
254
+ }
255
+ if self._driver_name == "extension"
256
+ and not bool(extension_details.get("connected"))
257
+ else None
258
+ )
259
+ ),
260
+ "tabs": await self._tab_runtime_status(),
261
+ "stability": self._stability.snapshot(command_depth=self._command_depth),
262
+ }
263
+
264
+ async def runtime_status_for_popup(self) -> dict[str, Any]:
265
+ raw_status = await self.runtime_status(warmup=False)
266
+ return {
267
+ **raw_status,
268
+ "presentation": build_runtime_presentation(raw_status),
269
+ }
270
+
271
+ async def rebuild_workspace_binding(self) -> dict[str, Any]:
272
+ await self.ensure_started()
273
+ if self._driver_name != "extension":
274
+ raise OperationFailedError(
275
+ "Workspace binding rebuild is only available in extension mode."
276
+ )
277
+ rebuilt = await self._extension.rebuild_workspace_binding()
278
+ self._snapshot_registry.clear()
279
+ await self._tabs.clear()
280
+ self._stability.workspace_rebuilds += 1
281
+ self._last_transition = {
282
+ "driver_changed_from": "extension",
283
+ "driver_changed_to": "extension",
284
+ "driver_reason": "workspace-binding-rebuilt",
285
+ "state_reset": True,
286
+ }
287
+ return {
288
+ **rebuilt,
289
+ "tab_state_reset": True,
290
+ }
291
+
292
+ async def _tab_runtime_status(self) -> dict[str, Any]:
293
+ records, active_by_agent = await self._tabs.snapshot_state()
294
+ return {
295
+ "count": len(records),
296
+ "busy_count": sum(1 for record in records if record.busy is not None),
297
+ "active_by_agent": active_by_agent,
298
+ "records": [self._serialize_tab_record(record) for record in records],
299
+ }
300
+
301
+ @staticmethod
302
+ def _serialize_tab_record(record: TabRecord) -> dict[str, Any]:
303
+ return {
304
+ "page_id": record.page_id,
305
+ "owner_agent_id": record.owner_agent_id,
306
+ "url": record.url,
307
+ "title": record.title,
308
+ "busy": record.busy is not None,
309
+ "last_snapshot_id": record.last_snapshot_id,
310
+ }
311
+
312
+ async def new_tab(
313
+ self,
314
+ *,
315
+ url: str | None = None,
316
+ wait_until: str = "load",
317
+ timeout_seconds: float | None = None,
318
+ ) -> dict[str, Any]:
319
+ page_id = self._next_page_id()
320
+ return await self._active_driver().new_tab(
321
+ page_id=page_id,
322
+ url=url,
323
+ wait_until=wait_until,
324
+ timeout_seconds=timeout_seconds,
325
+ )
326
+
327
+ async def read_page(
328
+ self,
329
+ *,
330
+ url: str,
331
+ output_mode: str = "html",
332
+ scroll_bottom: bool = False,
333
+ ) -> dict[str, Any]:
334
+ if output_mode not in {"html", "snapshot"}:
335
+ raise InvalidInputError(f"Unsupported read output mode: {output_mode}")
336
+ page = await self.new_tab(
337
+ url=url, wait_until="load", timeout_seconds=self.READ_NAVIGATION_TIMEOUT_SECONDS
338
+ )
339
+ page_id = str(page["page_id"])
340
+ try:
341
+ await self.wait(page_id, seconds=self.READ_SETTLE_TIMEOUT_MS / 1000.0)
342
+ if scroll_bottom:
343
+ await self._scroll_page_to_bottom(page_id)
344
+ await self.wait(page_id, seconds=self.READ_SETTLE_TIMEOUT_MS / 1000.0)
345
+ if output_mode == "snapshot":
346
+ body = str(
347
+ (await self.capture_snapshot(page_id, interactive=False, full_page=True))[
348
+ "tree"
349
+ ]
350
+ )
351
+ else:
352
+ body = str((await self.capture_html(page_id))["html"])
353
+ if not body.strip():
354
+ raise EmptyContentError()
355
+ payload = {
356
+ "page_id": page_id,
357
+ "body": body,
358
+ "output_mode": output_mode,
359
+ "url": str(page["url"]),
360
+ }
361
+ chrome_environment = self._playwright.chrome_environment
362
+ if chrome_environment is not None:
363
+ payload["used_fallback_profile"] = chrome_environment.source == "fallback"
364
+ if chrome_environment.source == "fallback":
365
+ payload["fallback_profile_dir"] = str(chrome_environment.user_data_dir)
366
+ payload["fallback_reason"] = chrome_environment.fallback_reason
367
+ if chrome_environment.profile_name:
368
+ payload["profile_name"] = chrome_environment.profile_name
369
+ payload["profile_directory"] = chrome_environment.profile_directory
370
+ return payload
371
+ finally:
372
+ with contextlib.suppress(Exception):
373
+ await self.close_tab(page_id)
374
+
375
+ async def close_tab(self, page_id: str) -> dict[str, Any]:
376
+ self._snapshot_registry.clear_page(page_id)
377
+ return await self._active_driver().close_tab(page_id)
378
+
379
+ async def get_page_summary(self, page_id: str) -> dict[str, Any]:
380
+ return await self._active_driver().get_page_summary(page_id)
381
+
382
+ async def get_page_info(self, page_id: str) -> dict[str, Any]:
383
+ return await self._active_driver().get_page_info(page_id)
384
+
385
+ async def capture_html(self, page_id: str) -> dict[str, Any]:
386
+ return await self._active_driver().capture_html(page_id)
387
+
388
+ async def capture_snapshot(
389
+ self,
390
+ page_id: str,
391
+ *,
392
+ interactive: bool = False,
393
+ full_page: bool = True,
394
+ ) -> dict[str, Any]:
395
+ snapshot_input = await self._active_driver().capture_snapshot_input(
396
+ page_id,
397
+ interactive=interactive,
398
+ full_page=full_page,
399
+ )
400
+ semantic_snapshot = self._snapshot_generator.snapshot_from_raw_text(
401
+ snapshot_input.raw_snapshot,
402
+ page_id=page_id,
403
+ captured_url=snapshot_input.captured_url,
404
+ interactive=interactive,
405
+ full_page=full_page,
406
+ captured_at=snapshot_input.captured_at,
407
+ )
408
+ state = self._snapshot_registry.store(semantic_snapshot)
409
+ return {
410
+ "page_id": page_id,
411
+ "tree": semantic_snapshot.tree,
412
+ "snapshot_id": semantic_snapshot.metadata.snapshot_id,
413
+ "captured_url": state.captured_url,
414
+ "captured_at": state.captured_at,
415
+ "refs_summary": [
416
+ {
417
+ "ref": ref,
418
+ **data.to_summary(),
419
+ }
420
+ for ref, data in semantic_snapshot.refs.items()
421
+ ],
422
+ }
423
+
424
+ async def navigate(
425
+ self, page_id: str, url: str, *, wait_until: str = "load", timeout_seconds: float = 30.0
426
+ ) -> dict[str, Any]:
427
+ self._snapshot_registry.clear_page(page_id)
428
+ return await self._active_driver().navigate(
429
+ page_id, url, wait_until=wait_until, timeout_seconds=timeout_seconds
430
+ )
431
+
432
+ async def reload(
433
+ self, page_id: str, *, wait_until: str = "load", timeout_seconds: float = 30.0
434
+ ) -> dict[str, Any]:
435
+ self._snapshot_registry.clear_page(page_id)
436
+ return await self._active_driver().reload(
437
+ page_id, wait_until=wait_until, timeout_seconds=timeout_seconds
438
+ )
439
+
440
+ async def go_back(self, page_id: str) -> dict[str, Any]:
441
+ self._snapshot_registry.clear_page(page_id)
442
+ return await self._active_driver().go_back(page_id)
443
+
444
+ async def go_forward(self, page_id: str) -> dict[str, Any]:
445
+ self._snapshot_registry.clear_page(page_id)
446
+ return await self._active_driver().go_forward(page_id)
447
+
448
+ async def resize(self, page_id: str, *, width: int, height: int) -> dict[str, Any]:
449
+ return await self._active_driver().resize(page_id, width=width, height=height)
450
+
451
+ async def click_ref(self, page_id: str, ref: str) -> dict[str, Any]:
452
+ return await self._active_driver().click(page_id, await self._require_locator(page_id, ref))
453
+
454
+ async def double_click_ref(self, page_id: str, ref: str) -> dict[str, Any]:
455
+ return await self._active_driver().double_click(
456
+ page_id, await self._require_locator(page_id, ref)
457
+ )
458
+
459
+ async def hover_ref(self, page_id: str, ref: str) -> dict[str, Any]:
460
+ return await self._active_driver().hover(page_id, await self._require_locator(page_id, ref))
461
+
462
+ async def focus_ref(self, page_id: str, ref: str) -> dict[str, Any]:
463
+ return await self._active_driver().focus(page_id, await self._require_locator(page_id, ref))
464
+
465
+ async def fill_ref(
466
+ self, page_id: str, ref: str, text: str, *, submit: bool = False
467
+ ) -> dict[str, Any]:
468
+ return await self._active_driver().fill(
469
+ page_id, await self._require_locator(page_id, ref), text, submit=submit
470
+ )
471
+
472
+ async def fill_form(
473
+ self, page_id: str, fields: list[dict[str, Any]], *, submit: bool = False
474
+ ) -> dict[str, Any]:
475
+ for field in fields:
476
+ ref = str(field.get("ref") or "").strip()
477
+ text = str(field.get("text") or "")
478
+ if not ref:
479
+ raise InvalidInputError("Each fill-form field must include a ref.")
480
+ await self.fill_ref(page_id, ref, text, submit=False)
481
+ if submit and fields:
482
+ await self._active_driver().press_key(page_id, "Enter")
483
+ return {"page_id": page_id, "filled_fields": len(fields), "submitted": submit}
484
+
485
+ async def select_option(self, page_id: str, ref: str, text: str) -> dict[str, Any]:
486
+ return await self._active_driver().select_option(
487
+ page_id, await self._require_locator(page_id, ref), text
488
+ )
489
+
490
+ async def list_options(self, page_id: str, ref: str) -> dict[str, Any]:
491
+ return await self._active_driver().list_options(
492
+ page_id, await self._require_locator(page_id, ref)
493
+ )
494
+
495
+ async def check_ref(self, page_id: str, ref: str) -> dict[str, Any]:
496
+ return await self._active_driver().check(
497
+ page_id, await self._require_locator(page_id, ref), checked=True
498
+ )
499
+
500
+ async def uncheck_ref(self, page_id: str, ref: str) -> dict[str, Any]:
501
+ return await self._active_driver().check(
502
+ page_id, await self._require_locator(page_id, ref), checked=False
503
+ )
504
+
505
+ async def scroll_to_ref(self, page_id: str, ref: str) -> dict[str, Any]:
506
+ return await self._active_driver().scroll_to(
507
+ page_id, await self._require_locator(page_id, ref)
508
+ )
509
+
510
+ async def drag_ref(self, page_id: str, start_ref: str, end_ref: str) -> dict[str, Any]:
511
+ return await self._active_driver().drag(
512
+ page_id,
513
+ await self._require_locator(page_id, start_ref),
514
+ await self._require_locator(page_id, end_ref),
515
+ )
516
+
517
+ async def upload_file(self, page_id: str, ref: str, file_path: str) -> dict[str, Any]:
518
+ return await self._active_driver().upload(
519
+ page_id, await self._require_locator(page_id, ref), file_path
520
+ )
521
+
522
+ async def evaluate(self, page_id: str, code: str) -> dict[str, Any]:
523
+ return await self._active_driver().evaluate(page_id, code)
524
+
525
+ async def evaluate_on_ref(self, page_id: str, ref: str, code: str) -> dict[str, Any]:
526
+ return await self._active_driver().evaluate_on(
527
+ page_id, await self._require_locator(page_id, ref), code
528
+ )
529
+
530
+ async def wait(
531
+ self,
532
+ page_id: str,
533
+ *,
534
+ seconds: float | None = None,
535
+ text: str | None = None,
536
+ gone: bool = False,
537
+ exact: bool = False,
538
+ ) -> dict[str, Any]:
539
+ return await self._active_driver().wait(
540
+ page_id, seconds=seconds, text=text, gone=gone, exact=exact
541
+ )
542
+
543
+ async def wait_for_network_idle(
544
+ self, page_id: str, *, timeout_seconds: float = 30.0
545
+ ) -> dict[str, Any]:
546
+ return await self._active_driver().wait_for_network_idle(
547
+ page_id, timeout_seconds=timeout_seconds
548
+ )
549
+
550
+ async def start_console_capture(self, page_id: str) -> dict[str, Any]:
551
+ return await self._active_driver().start_console_capture(page_id)
552
+
553
+ async def get_console_messages(
554
+ self, page_id: str, *, message_type: str | None = None, clear: bool = True
555
+ ) -> dict[str, Any]:
556
+ return await self._active_driver().get_console_messages(
557
+ page_id, message_type=message_type, clear=clear
558
+ )
559
+
560
+ async def stop_console_capture(self, page_id: str) -> dict[str, Any]:
561
+ return await self._active_driver().stop_console_capture(page_id)
562
+
563
+ async def start_network_capture(self, page_id: str) -> dict[str, Any]:
564
+ return await self._active_driver().start_network_capture(page_id)
565
+
566
+ async def wait_for_network_record(
567
+ self,
568
+ page_id: str,
569
+ *,
570
+ url_contains: str | None = None,
571
+ url_regex: str | None = None,
572
+ method: str | None = None,
573
+ status: int | None = None,
574
+ resource_type: str | None = None,
575
+ mime_contains: str | None = None,
576
+ include_static: bool = False,
577
+ timeout_seconds: float = 30.0,
578
+ ) -> dict[str, Any]:
579
+ return await self._active_driver().wait_for_network_record(
580
+ page_id,
581
+ url_contains=url_contains,
582
+ url_regex=url_regex,
583
+ method=method,
584
+ status=status,
585
+ resource_type=resource_type,
586
+ mime_contains=mime_contains,
587
+ include_static=include_static,
588
+ timeout_seconds=timeout_seconds,
589
+ )
590
+
591
+ async def get_network_records(
592
+ self,
593
+ page_id: str,
594
+ *,
595
+ url_contains: str | None = None,
596
+ url_regex: str | None = None,
597
+ method: str | None = None,
598
+ status: int | None = None,
599
+ resource_type: str | None = None,
600
+ mime_contains: str | None = None,
601
+ include_static: bool = False,
602
+ clear: bool = True,
603
+ ) -> dict[str, Any]:
604
+ return await self._active_driver().get_network_records(
605
+ page_id,
606
+ url_contains=url_contains,
607
+ url_regex=url_regex,
608
+ method=method,
609
+ status=status,
610
+ resource_type=resource_type,
611
+ mime_contains=mime_contains,
612
+ include_static=include_static,
613
+ clear=clear,
614
+ )
615
+
616
+ async def stop_network_capture(self, page_id: str) -> dict[str, Any]:
617
+ return await self._active_driver().stop_network_capture(page_id)
618
+
619
+ async def get_cookies(
620
+ self,
621
+ page_id: str,
622
+ *,
623
+ name: str | None = None,
624
+ domain: str | None = None,
625
+ path: str | None = None,
626
+ ) -> dict[str, Any]:
627
+ return await self._active_driver().get_cookies(page_id, name=name, domain=domain, path=path)
628
+
629
+ async def set_cookie(
630
+ self,
631
+ page_id: str,
632
+ *,
633
+ name: str,
634
+ value: str,
635
+ domain: str | None = None,
636
+ path: str = "/",
637
+ expires: float | None = None,
638
+ http_only: bool = False,
639
+ secure: bool = False,
640
+ same_site: str | None = None,
641
+ ) -> dict[str, Any]:
642
+ return await self._active_driver().set_cookie(
643
+ page_id,
644
+ name=name,
645
+ value=value,
646
+ domain=domain,
647
+ path=path,
648
+ expires=expires,
649
+ http_only=http_only,
650
+ secure=secure,
651
+ same_site=same_site,
652
+ )
653
+
654
+ async def clear_cookies(
655
+ self,
656
+ page_id: str,
657
+ *,
658
+ name: str | None = None,
659
+ domain: str | None = None,
660
+ path: str | None = None,
661
+ ) -> dict[str, Any]:
662
+ return await self._active_driver().clear_cookies(
663
+ page_id, name=name, domain=domain, path=path
664
+ )
665
+
666
+ async def save_storage_state(self, page_id: str, *, path: str | None = None) -> dict[str, Any]:
667
+ return await self._active_driver().save_storage_state(page_id, path=path)
668
+
669
+ async def load_storage_state(self, page_id: str, *, path: str) -> dict[str, Any]:
670
+ return await self._active_driver().load_storage_state(page_id, path=path)
671
+
672
+ async def verify_text(
673
+ self, page_id: str, *, text: str, exact: bool = False, timeout_seconds: float = 5.0
674
+ ) -> dict[str, Any]:
675
+ return await self._active_driver().verify_text(
676
+ page_id, text=text, exact=exact, timeout_seconds=timeout_seconds
677
+ )
678
+
679
+ async def verify_url(
680
+ self, page_id: str, *, expected: str, exact: bool = False
681
+ ) -> dict[str, Any]:
682
+ return await self._active_driver().verify_url(page_id, expected=expected, exact=exact)
683
+
684
+ async def verify_title(
685
+ self, page_id: str, *, expected: str, exact: bool = False
686
+ ) -> dict[str, Any]:
687
+ return await self._active_driver().verify_title(page_id, expected=expected, exact=exact)
688
+
689
+ async def verify_visible(
690
+ self, page_id: str, *, role: str, name: str, timeout_seconds: float = 5.0
691
+ ) -> dict[str, Any]:
692
+ return await self._active_driver().verify_visible(
693
+ page_id,
694
+ role=role,
695
+ name=name,
696
+ timeout_seconds=timeout_seconds,
697
+ )
698
+
699
+ async def verify_state(self, page_id: str, *, ref: str, state: str) -> dict[str, Any]:
700
+ return await self._active_driver().verify_state(
701
+ page_id, locator=await self._require_locator(page_id, ref), state=state
702
+ )
703
+
704
+ async def verify_value(self, page_id: str, *, ref: str, expected: str) -> dict[str, Any]:
705
+ return await self._active_driver().verify_value(
706
+ page_id, locator=await self._require_locator(page_id, ref), expected=expected
707
+ )
708
+
709
+ async def type_text(self, page_id: str, text: str, *, submit: bool = False) -> dict[str, Any]:
710
+ return await self._active_driver().type_text(page_id, text, submit=submit)
711
+
712
+ async def press_key(self, page_id: str, key: str) -> dict[str, Any]:
713
+ return await self._active_driver().press_key(page_id, key)
714
+
715
+ async def key_down(self, page_id: str, key: str) -> dict[str, Any]:
716
+ return await self._active_driver().key_down(page_id, key)
717
+
718
+ async def key_up(self, page_id: str, key: str) -> dict[str, Any]:
719
+ return await self._active_driver().key_up(page_id, key)
720
+
721
+ async def wheel(self, page_id: str, *, dx: int = 0, dy: int = 700) -> dict[str, Any]:
722
+ return await self._active_driver().wheel(page_id, dx=dx, dy=dy)
723
+
724
+ async def mouse_move(self, page_id: str, *, x: int, y: int) -> dict[str, Any]:
725
+ return await self._active_driver().mouse_move(page_id, x=x, y=y)
726
+
727
+ async def mouse_click(
728
+ self,
729
+ page_id: str,
730
+ *,
731
+ x: int,
732
+ y: int,
733
+ button: str = "left",
734
+ count: int = 1,
735
+ ) -> dict[str, Any]:
736
+ return await self._active_driver().mouse_click(
737
+ page_id, x=x, y=y, button=button, count=count
738
+ )
739
+
740
+ async def mouse_drag(
741
+ self, page_id: str, *, x1: int, y1: int, x2: int, y2: int
742
+ ) -> dict[str, Any]:
743
+ return await self._active_driver().mouse_drag(page_id, x1=x1, y1=y1, x2=x2, y2=y2)
744
+
745
+ async def mouse_down(self, page_id: str, *, button: str = "left") -> dict[str, Any]:
746
+ return await self._active_driver().mouse_down(page_id, button=button)
747
+
748
+ async def mouse_up(self, page_id: str, *, button: str = "left") -> dict[str, Any]:
749
+ return await self._active_driver().mouse_up(page_id, button=button)
750
+
751
+ async def screenshot(
752
+ self, page_id: str, *, path: str, full_page: bool = False
753
+ ) -> dict[str, Any]:
754
+ return await self._active_driver().screenshot(page_id, path=path, full_page=full_page)
755
+
756
+ async def save_pdf(self, page_id: str, *, path: str) -> dict[str, Any]:
757
+ return await self._active_driver().save_pdf(page_id, path=path)
758
+
759
+ async def setup_dialog_handler(
760
+ self,
761
+ page_id: str,
762
+ *,
763
+ default_action: str = "accept",
764
+ default_prompt_text: str | None = None,
765
+ ) -> dict[str, Any]:
766
+ return await self._active_driver().setup_dialog_handler(
767
+ page_id,
768
+ default_action=default_action,
769
+ default_prompt_text=default_prompt_text,
770
+ )
771
+
772
+ async def handle_dialog(
773
+ self,
774
+ page_id: str,
775
+ *,
776
+ accept: bool,
777
+ prompt_text: str | None = None,
778
+ ) -> dict[str, Any]:
779
+ return await self._active_driver().handle_dialog(
780
+ page_id, accept=accept, prompt_text=prompt_text
781
+ )
782
+
783
+ async def remove_dialog_handler(self, page_id: str) -> dict[str, Any]:
784
+ return await self._active_driver().remove_dialog_handler(page_id)
785
+
786
+ async def start_tracing(
787
+ self,
788
+ page_id: str,
789
+ *,
790
+ screenshots: bool = True,
791
+ snapshots: bool = True,
792
+ sources: bool = False,
793
+ ) -> dict[str, Any]:
794
+ return await self._active_driver().start_tracing(
795
+ page_id,
796
+ screenshots=screenshots,
797
+ snapshots=snapshots,
798
+ sources=sources,
799
+ )
800
+
801
+ async def add_trace_chunk(self, page_id: str, *, title: str | None = None) -> dict[str, Any]:
802
+ return await self._active_driver().add_trace_chunk(page_id, title=title)
803
+
804
+ async def stop_tracing(self, page_id: str, *, path: str | None = None) -> dict[str, Any]:
805
+ return await self._active_driver().stop_tracing(page_id, path=path)
806
+
807
+ async def start_video(
808
+ self, page_id: str, *, width: int | None = None, height: int | None = None
809
+ ) -> dict[str, Any]:
810
+ return await self._active_driver().start_video(page_id, width=width, height=height)
811
+
812
+ async def stop_video(self, page_id: str, *, path: str | None = None) -> dict[str, Any]:
813
+ return await self._active_driver().stop_video(page_id, path=path)
814
+
815
+ async def search(self, *, query: str, engine: str = "duckduckgo") -> dict[str, Any]:
816
+ return await self.new_tab(
817
+ url=PlaywrightDriver.build_search_url(query, engine), wait_until="load"
818
+ )
819
+
820
+ async def _require_locator(self, page_id: str, ref: str):
821
+ state = self._snapshot_registry.get(page_id)
822
+ if state is None:
823
+ raise NoSnapshotContextError()
824
+ locator = self._ref_resolver.build_locator_spec(ref, state.refs)
825
+ if locator is None:
826
+ normalized = self._ref_resolver.parse_ref(ref)
827
+ if normalized is None:
828
+ raise InvalidInputError(f"Invalid ref: {ref}")
829
+ raise RefNotFoundError()
830
+ return locator
831
+
832
+ async def _scroll_page_to_bottom(self, page_id: str) -> None:
833
+ previous_height: int | None = None
834
+ stable_rounds = 0
835
+ for _ in range(self.READ_SCROLL_MAX_ROUNDS):
836
+ before_payload = await self.evaluate(
837
+ page_id,
838
+ """() => ({
839
+ height: Math.max(document.body.scrollHeight, document.documentElement.scrollHeight)
840
+ })""",
841
+ )
842
+ current_height = int((before_payload.get("result") or {}).get("height") or 0)
843
+ await self.evaluate(
844
+ page_id,
845
+ """() => {
846
+ const height = Math.max(document.body.scrollHeight, document.documentElement.scrollHeight);
847
+ window.scrollTo(0, height);
848
+ return height;
849
+ }""",
850
+ )
851
+ await self.wait(page_id, seconds=self.READ_SCROLL_PAUSE_MS / 1000.0)
852
+ after_payload = await self.evaluate(
853
+ page_id,
854
+ """() => ({
855
+ height: Math.max(document.body.scrollHeight, document.documentElement.scrollHeight)
856
+ })""",
857
+ )
858
+ new_height = int((after_payload.get("result") or {}).get("height") or 0)
859
+ if previous_height is None:
860
+ previous_height = current_height
861
+ if new_height <= previous_height:
862
+ stable_rounds += 1
863
+ if stable_rounds >= self.READ_SCROLL_STABLE_ROUNDS:
864
+ return
865
+ else:
866
+ stable_rounds = 0
867
+ previous_height = new_height
868
+
869
+ async def _activate_driver(self, driver_name: str, *, reason: str) -> None:
870
+ async with self._rebind_lock:
871
+ if self._driver_name == driver_name and self._driver is not None:
872
+ return
873
+ old_driver_name = self._driver_name
874
+ logger.info(
875
+ "Rebinding driver from=%s to=%s reason=%s",
876
+ old_driver_name or "none",
877
+ driver_name,
878
+ reason,
879
+ )
880
+ records, active_by_agent = await self._tabs.snapshot_state()
881
+ if old_driver_name == "extension":
882
+ await self._stop_driver_for_transition("extension")
883
+ elif old_driver_name == "playwright":
884
+ await self._stop_driver_for_transition("playwright")
885
+ self._driver = None
886
+ self._driver_name = None
887
+ if driver_name == "extension":
888
+ await self._extension.ensure_started()
889
+ self._driver = self._extension
890
+ else:
891
+ await self._playwright.ensure_started()
892
+ self._driver = self._playwright
893
+ self._driver_name = driver_name
894
+ self._snapshot_registry.clear()
895
+ await self._tabs.clear_snapshot_state()
896
+ state_reset = False
897
+ if records:
898
+ state_reset = True
899
+ reopened: list[tuple[TabRecord, dict[str, Any]]] = []
900
+ for record in records:
901
+ reopened_page = await self._driver.new_tab(
902
+ page_id=record.page_id,
903
+ url=record.url,
904
+ wait_until="load",
905
+ timeout_seconds=self.READ_NAVIGATION_TIMEOUT_SECONDS,
906
+ )
907
+ reopened.append((record, reopened_page))
908
+ for record, reopened_page in reopened:
909
+ await self._tabs.update_tab(
910
+ record.page_id,
911
+ url=str(reopened_page.get("url") or record.url),
912
+ title=str(reopened_page.get("title") or record.title),
913
+ )
914
+ for agent_id, page_id in active_by_agent.items():
915
+ try:
916
+ await self._tabs.set_active_tab(agent_id, page_id)
917
+ await self._driver.switch_tab(page_id)
918
+ except Exception:
919
+ pass
920
+ self._last_runtime_meta = {
921
+ "driver": self._driver_name,
922
+ "driver_reason": reason,
923
+ }
924
+ if old_driver_name and old_driver_name != driver_name:
925
+ self._stability.driver_switches += 1
926
+ self._last_transition = {
927
+ "driver_changed_from": old_driver_name,
928
+ "driver_changed_to": driver_name,
929
+ "driver_reason": reason,
930
+ "state_reset": state_reset,
931
+ }
932
+ self._last_runtime_meta.update(self._last_transition)
933
+ logger.info(
934
+ "Driver rebound active=%s restored_tabs=%d state_reset=%s",
935
+ self._driver_name,
936
+ len(records),
937
+ state_reset,
938
+ )
939
+
940
+ async def _stop_driver_for_transition(self, driver_name: str | None) -> None:
941
+ try:
942
+ if driver_name == "extension":
943
+ await self._extension.stop()
944
+ elif driver_name == "playwright":
945
+ await self._playwright.stop()
946
+ except Exception as exc:
947
+ self._stability.cleanup_failures += 1
948
+ self._stability.last_cleanup_error = str(exc)
949
+ logger.warning("Driver stop failed for %s during transition: %s", driver_name, exc)
950
+
951
+ async def _watch_extension_changes(self) -> None:
952
+ try:
953
+ while True:
954
+ await self._extension_hub.wait_for_change()
955
+ session = self._extension_hub.session
956
+ target: str | None = None
957
+ reason: str | None = None
958
+ if session is not None and session.hello.has_required_capabilities():
959
+ if self._driver_name != "extension":
960
+ target = "extension"
961
+ reason = "extension-connected"
962
+ elif self._driver_name == "extension":
963
+ logger.warning(
964
+ "Extension disconnected while extension driver is active; holding driver until next command"
965
+ )
966
+ if not target:
967
+ continue
968
+ try:
969
+ if self._command_depth == 0:
970
+ await self._activate_driver(target, reason=reason or "rebind")
971
+ else:
972
+ self._pending_driver = target
973
+ self._pending_reason = reason
974
+ except Exception:
975
+ self._pending_driver = None
976
+ self._pending_reason = None
977
+ except asyncio.CancelledError:
978
+ return
979
+
980
+ async def _maybe_apply_pending_rebind(self) -> None:
981
+ if self._command_depth != 0:
982
+ return
983
+ if not self._pending_driver:
984
+ return
985
+ target = self._pending_driver
986
+ reason = self._pending_reason or "pending-rebind"
987
+ self._pending_driver = None
988
+ self._pending_reason = None
989
+ await self._activate_driver(target, reason=reason)
990
+
991
+ def _active_driver(self) -> BrowserDriver:
992
+ if self._driver is None:
993
+ raise OperationFailedError("Browser backend is not started.")
994
+ return self._driver
995
+
996
+ def _next_page_id(self) -> str:
997
+ self._page_counter += 1
998
+ return f"page_{self._page_counter:04d}"