clean up & hardening

Author: rcholic

sentience/actions.py

@@ -1,10 +1,13 @@
+from typing import Optional
+
 """
 Actions v1 - click, type, press
 """
 
 import time
 
 from .browser import AsyncSentienceBrowser, SentienceBrowser
+from .browser_evaluator import BrowserEvaluator
 from .models import ActionResult, BBox, Snapshot
 from .snapshot import snapshot, snapshot_async
 
@@ -59,41 +62,22 @@ def click(  # noqa: C901
             else:
                 # Fallback to JS click if element not found in snapshot
                 try:
-                    success = browser.page.evaluate(
-                        """
-                        (id) => {
-                            return window.sentience.click(id);
-                        }
-                        """,
-                        element_id,
+                    success = BrowserEvaluator.call_sentience_method(
+                        browser.page, "click", element_id
                     )
                 except Exception:
                     # Navigation might have destroyed context, assume success if URL changed
                     success = True
         except Exception:
             # Fallback to JS click on error
             try:
-                success = browser.page.evaluate(
-                    """
-                    (id) => {
-                        return window.sentience.click(id);
-                    }
-                    """,
-                    element_id,
-                )
+                success = BrowserEvaluator.call_sentience_method(browser.page, "click", element_id)
             except Exception:
                 # Navigation might have destroyed context, assume success if URL changed
                 success = True
     else:
         # Legacy JS-based click
-        success = browser.page.evaluate(
-            """
-            (id) => {
-                return window.sentience.click(id);
-            }
-            """,
-            element_id,
-        )
+        success = BrowserEvaluator.call_sentience_method(browser.page, "click", element_id)
 
     # Wait a bit for navigation/DOM updates
     try:

sentience/agent.py

@@ -100,7 +100,9 @@ def _compute_hash(self, text: str) -> str:
         """Compute SHA256 hash of text."""
         return hashlib.sha256(text.encode("utf-8")).hexdigest()
 
-    def _get_element_bbox(self, element_id: int | None, snap: Snapshot) -> dict[str, float] | None:
+    def _get_element_bbox(
+        self, element_id: int | None, snap: Snapshot
+    ) -> dict[str, float] | None:
         """Get bounding box for an element from snapshot."""
         if element_id is None:
             return None
@@ -872,7 +874,9 @@ def _compute_hash(self, text: str) -> str:
         """Compute SHA256 hash of text."""
         return hashlib.sha256(text.encode("utf-8")).hexdigest()
 
-    def _get_element_bbox(self, element_id: int | None, snap: Snapshot) -> dict[str, float] | None:
+    def _get_element_bbox(
+        self, element_id: int | None, snap: Snapshot
+    ) -> dict[str, float] | None:
         """Get bounding box for an element from snapshot."""
         if element_id is None:
             return None

sentience/base_agent.py

@@ -1,3 +1,5 @@
+from typing import Optional
+
 """
 BaseAgent: Abstract base class for all Sentience agents
 Defines the interface that all agent implementations must follow

sentience/browser.py

@@ -8,6 +8,7 @@
 import tempfile
 import time
 from pathlib import Path
+from typing import Optional, Union
 from urllib.parse import urlparse
 
 from playwright.async_api import BrowserContext as AsyncBrowserContext

sentience/browser_evaluator.py

@@ -0,0 +1,279 @@
+"""
+Browser evaluation helper for common window.sentience API patterns.
+
+Consolidates repeated patterns for:
+- Waiting for extension injection
+- Calling window.sentience methods
+- Error handling with diagnostics
+"""
+
+from typing import Any, Optional, Union
+
+from playwright.async_api import Page as AsyncPage
+from playwright.sync_api import Page
+
+from .browser import AsyncSentienceBrowser, SentienceBrowser
+
+
+class BrowserEvaluator:
+    """Helper class for common browser evaluation patterns"""
+
+    @staticmethod
+    def wait_for_extension(
+        page: Union[Page, AsyncPage],
+        timeout_ms: int = 5000,
+    ) -> None:
+        """
+        Wait for window.sentience API to be available.
+
+        Args:
+            page: Playwright Page instance (sync or async)
+            timeout_ms: Timeout in milliseconds (default: 5000)
+
+        Raises:
+            RuntimeError: If extension fails to inject within timeout
+        """
+        if hasattr(page, "wait_for_function"):
+            # Sync page
+            try:
+                page.wait_for_function(
+                    "typeof window.sentience !== 'undefined'",
+                    timeout=timeout_ms,
+                )
+            except Exception as e:
+                diag = BrowserEvaluator._gather_diagnostics(page)
+                raise RuntimeError(
+                    f"Sentience extension failed to inject window.sentience API. "
+                    f"Is the extension loaded? Diagnostics: {diag}"
+                ) from e
+        else:
+            # Async page - should use async version
+            raise TypeError("Use wait_for_extension_async for async pages")
+
+    @staticmethod
+    async def wait_for_extension_async(
+        page: AsyncPage,
+        timeout_ms: int = 5000,
+    ) -> None:
+        """
+        Wait for window.sentience API to be available (async).
+
+        Args:
+            page: Playwright AsyncPage instance
+            timeout_ms: Timeout in milliseconds (default: 5000)
+
+        Raises:
+            RuntimeError: If extension fails to inject within timeout
+        """
+        try:
+            await page.wait_for_function(
+                "typeof window.sentience !== 'undefined'",
+                timeout=timeout_ms,
+            )
+        except Exception as e:
+            diag = await BrowserEvaluator._gather_diagnostics_async(page)
+            raise RuntimeError(
+                f"Sentience extension failed to inject window.sentience API. "
+                f"Is the extension loaded? Diagnostics: {diag}"
+            ) from e
+
+    @staticmethod
+    def _gather_diagnostics(page: Union[Page, AsyncPage]) -> dict[str, Any]:
+        """
+        Gather diagnostics about extension state.
+
+        Args:
+            page: Playwright Page instance
+
+        Returns:
+            Dictionary with diagnostic information
+        """
+        try:
+            if hasattr(page, "evaluate"):
+                # Sync page
+                return page.evaluate(
+                    """() => ({
+                        sentience_defined: typeof window.sentience !== 'undefined',
+                        extension_id: document.documentElement.dataset.sentienceExtensionId || 'not set',
+                        url: window.location.href
+                    })"""
+                )
+            else:
+                return {"error": "Could not gather diagnostics - invalid page type"}
+        except Exception:
+            return {"error": "Could not gather diagnostics"}
+
+    @staticmethod
+    async def _gather_diagnostics_async(page: AsyncPage) -> dict[str, Any]:
+        """
+        Gather diagnostics about extension state (async).
+
+        Args:
+            page: Playwright AsyncPage instance
+
+        Returns:
+            Dictionary with diagnostic information
+        """
+        try:
+            return await page.evaluate(
+                """() => ({
+                    sentience_defined: typeof window.sentience !== 'undefined',
+                    extension_id: document.documentElement.dataset.sentienceExtensionId || 'not set',
+                    url: window.location.href
+                })"""
+            )
+        except Exception:
+            return {"error": "Could not gather diagnostics"}
+
+    @staticmethod
+    def call_sentience_method(
+        page: Page,
+        method_name: str,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Any:
+        """
+        Call a window.sentience method with error handling.
+
+        Args:
+            page: Playwright Page instance (sync)
+            method_name: Name of the method (e.g., "snapshot", "click")
+            *args: Positional arguments to pass to the method
+            **kwargs: Keyword arguments to pass to the method
+
+        Returns:
+            Result from the method call
+
+        Raises:
+            RuntimeError: If method is not available or call fails
+        """
+        # Build JavaScript call
+        if args and kwargs:
+            # Both args and kwargs - use object spread
+            js_code = f"""
+            (args, kwargs) => {{
+                return window.sentience.{method_name}(...args, kwargs);
+            }}
+            """
+            result = page.evaluate(js_code, list(args), kwargs)
+        elif args:
+            # Only args
+            js_code = f"""
+            (args) => {{
+                return window.sentience.{method_name}(...args);
+            }}
+            """
+            result = page.evaluate(js_code, list(args))
+        elif kwargs:
+            # Only kwargs - pass as single object
+            js_code = f"""
+            (options) => {{
+                return window.sentience.{method_name}(options);
+            }}
+            """
+            result = page.evaluate(js_code, kwargs)
+        else:
+            # No arguments
+            js_code = f"""
+            () => {{
+                return window.sentience.{method_name}();
+            }}
+            """
+            result = page.evaluate(js_code)
+
+        return result
+
+    @staticmethod
+    async def call_sentience_method_async(
+        page: AsyncPage,
+        method_name: str,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Any:
+        """
+        Call a window.sentience method with error handling (async).
+
+        Args:
+            page: Playwright AsyncPage instance
+            method_name: Name of the method (e.g., "snapshot", "click")
+            *args: Positional arguments to pass to the method
+            **kwargs: Keyword arguments to pass to the method
+
+        Returns:
+            Result from the method call
+
+        Raises:
+            RuntimeError: If method is not available or call fails
+        """
+        # Build JavaScript call
+        if args and kwargs:
+            js_code = f"""
+            (args, kwargs) => {{
+                return window.sentience.{method_name}(...args, kwargs);
+            }}
+            """
+            result = await page.evaluate(js_code, list(args), kwargs)
+        elif args:
+            js_code = f"""
+            (args) => {{
+                return window.sentience.{method_name}(...args);
+            }}
+            """
+            result = await page.evaluate(js_code, list(args))
+        elif kwargs:
+            js_code = f"""
+            (options) => {{
+                return window.sentience.{method_name}(options);
+            }}
+            """
+            result = await page.evaluate(js_code, kwargs)
+        else:
+            js_code = f"""
+            () => {{
+                return window.sentience.{method_name}();
+            }}
+            """
+            result = await page.evaluate(js_code)
+
+        return result
+
+    @staticmethod
+    def verify_method_exists(
+        page: Page,
+        method_name: str,
+    ) -> bool:
+        """
+        Verify that a window.sentience method exists.
+
+        Args:
+            page: Playwright Page instance (sync)
+            method_name: Name of the method to check
+
+        Returns:
+            True if method exists, False otherwise
+        """
+        try:
+            return page.evaluate(f"typeof window.sentience.{method_name} !== 'undefined'")
+        except Exception:
+            return False
+
+    @staticmethod
+    async def verify_method_exists_async(
+        page: AsyncPage,
+        method_name: str,
+    ) -> bool:
+        """
+        Verify that a window.sentience method exists (async).
+
+        Args:
+            page: Playwright AsyncPage instance
+            method_name: Name of the method to check
+
+        Returns:
+            True if method exists, False otherwise
+        """
+        try:
+            return await page.evaluate(f"typeof window.sentience.{method_name} !== 'undefined'")
+        except Exception:
+            return False
+