narada 0.1.28__py3-none-any.whl → 0.1.30__py3-none-any.whl

narada/__init__.py

@@ -9,7 +9,7 @@ from narada_core.errors import (
 from narada_core.models import Agent, File, Response, ResponseContent
 
 from narada.client import Narada
-from narada.config import BrowserConfig
+from narada.config import BrowserConfig, ProxyConfig
 from narada.utils import download_file, render_html
 from narada.version import __version__
 from narada.window import LocalBrowserWindow, RemoteBrowserWindow
@@ -28,6 +28,7 @@ __all__ = [
     "NaradaInitializationError",
     "NaradaTimeoutError",
     "NaradaUnsupportedBrowserError",
+    "ProxyConfig",
     "RemoteBrowserWindow",
     "render_html",
     "Response",

narada/client.py

@@ -21,6 +21,8 @@ from narada_core.errors import (
 from narada_core.models import _SdkConfig
 from playwright._impl._errors import Error as PlaywrightError
 from playwright.async_api import (
+    Browser,
+    CDPSession,
     ElementHandle,
     Page,
     Playwright,
@@ -32,7 +34,7 @@ from playwright.async_api import (
 from playwright.async_api._context_manager import PlaywrightContextManager
 from rich.console import Console
 
-from narada.config import BrowserConfig
+from narada.config import BrowserConfig, ProxyConfig
 from narada.utils import assert_never
 from narada.version import __version__
 from narada.window import LocalBrowserWindow, create_side_panel_url
@@ -146,6 +148,13 @@ class Narada:
 
         config = config or BrowserConfig()
 
+        if config.proxy is not None:
+            raise ValueError(
+                "Proxy configuration is not supported for `initialize_in_existing_browser_window`. "
+                "Proxy settings must be specified when launching Chrome. "
+                "Use `open_and_initialize_browser_window` instead."
+            )
+
         browser = await playwright.chromium.connect_over_cdp(config.cdp_url)
 
         # Generate a unique tag for the initialization URL
@@ -193,6 +202,13 @@ class Narada:
         window_tag = uuid4().hex
         tagged_initialization_url = f"{config.initialization_url}?t={window_tag}"
 
+        # When proxy auth is needed, launch with about:blank to avoid Chrome's startup auth prompt.
+        # We'll set up the CDP auth handler and then navigate to the init URL.
+        proxy_requires_auth = (
+            config.proxy is not None and config.proxy.requires_authentication
+        )
+        launch_url = "about:blank" if proxy_requires_auth else tagged_initialization_url
+
         browser_args = [
             f"--user-data-dir={config.user_data_dir}",
             f"--profile-directory={config.profile_directory}",
@@ -200,11 +216,20 @@ class Narada:
             "--no-default-browser-check",
             "--no-first-run",
             "--new-window",
-            tagged_initialization_url,
-            # TODO: This is needed if we don't use CDP but let Playwright manage the browser.
-            # "--disable-blink-features=AutomationControlled",
+            launch_url,
         ]
 
+        # Add proxy arguments if configured.
+        if config.proxy is not None:
+            config.proxy.validate()
+            browser_args.append(f"--proxy-server={config.proxy.server}")
+
+            if config.proxy.bypass:
+                browser_args.append(f"--proxy-bypass-list={config.proxy.bypass}")
+
+            if config.proxy.ignore_cert_errors:
+                browser_args.append("--ignore-certificate-errors")
+
         # Launch an independent browser process which will not be killed when the current program
         # exits.
         if sys.platform == "win32":
@@ -235,6 +260,14 @@ class Narada:
         browser_window_id = None
         side_panel_page = None
         max_cdp_connect_attempts = 10
+
+        # Track whether we've already navigated from about:blank to the initialization URL.
+        # This is only relevant when proxy auth is enabled, where we launch with about:blank
+        # to set up CDP auth handlers before any network traffic. We must only navigate once,
+        # because on retry iterations context.pages[0] could be any page (side panel, devtools,
+        # etc.) and navigating it would break the initialization flow.
+        did_initial_navigation = False
+
         for attempt in range(max_cdp_connect_attempts):
             try:
                 browser = await playwright.chromium.connect_over_cdp(config.cdp_url)
@@ -246,8 +279,23 @@ class Narada:
                 await asyncio.sleep(2)
                 continue
 
-            # Grab the browser window ID from the page we just opened.
             context = browser.contexts[0]
+
+            # If proxy auth is needed, set up the handler at browser level then navigate to the
+            # initialization page. After navigation succeeds, Chrome has cached the proxy
+            # credentials, so we can detach the CDP session.
+            if proxy_requires_auth and not did_initial_navigation:
+                proxy_cdp_session = (
+                    await self._setup_proxy_authentication_browser_level(
+                        browser, config.proxy
+                    )
+                )
+                blank_page = context.pages[0]
+                await blank_page.goto(tagged_initialization_url)
+                await proxy_cdp_session.detach()
+                did_initial_navigation = True
+
+            # Grab the browser window ID from the page we just opened.
             initialization_page = next(
                 (p for p in context.pages if p.url == tagged_initialization_url), None
             )
@@ -415,6 +463,73 @@ class Narada:
                 initialization_page
             )
 
+    async def _setup_proxy_authentication_browser_level(
+        self, browser: Browser, proxy_config: ProxyConfig
+    ) -> CDPSession:
+        """Sets up proxy authentication handling via CDP at the browser level.
+
+        This uses a browser-level CDP session which can intercept auth challenges before they reach
+        individual pages, preventing Chrome from showing the proxy authentication dialog.
+
+        Chrome caches proxy credentials for the session after the first successful authentication.
+        The caller should detach the returned CDP session after the first navigation succeeds.
+        """
+        cdp_session = await browser.new_browser_cdp_session()
+
+        # Enable Fetch domain with a catch-all pattern to intercept auth challenges.
+        await cdp_session.send(
+            "Fetch.enable",
+            {
+                "handleAuthRequests": True,
+                "patterns": [{"urlPattern": "*"}],
+            },
+        )
+
+        async def handle_auth(params: dict[str, Any]) -> None:
+            request_id = params.get("requestId")
+            auth_challenge = params.get("authChallenge", {})
+
+            # Only handle proxy auth challenges
+            if auth_challenge.get("source") != "Proxy":
+                return
+
+            try:
+                await cdp_session.send(
+                    "Fetch.continueWithAuth",
+                    {
+                        "requestId": request_id,
+                        "authChallengeResponse": {
+                            "response": "ProvideCredentials",
+                            "username": proxy_config.username,
+                            "password": proxy_config.password,
+                        },
+                    },
+                )
+                logging.debug("Browser-level proxy authentication credentials provided")
+            except Exception as e:
+                logging.error("Failed to respond to proxy auth challenge: %s", e)
+
+        async def handle_request_paused(params: dict[str, Any]) -> None:
+            # Continue all paused requests immediately
+            request_id = params.get("requestId")
+            try:
+                await cdp_session.send(
+                    "Fetch.continueRequest", {"requestId": request_id}
+                )
+            except Exception:
+                pass
+
+        cdp_session.on(
+            "Fetch.authRequired",
+            lambda params: asyncio.create_task(handle_auth(params)),
+        )
+        cdp_session.on(
+            "Fetch.requestPaused",
+            lambda params: asyncio.create_task(handle_request_paused(params)),
+        )
+
+        return cdp_session
+
     async def _fix_download_behavior(self, side_panel_page: Page) -> None:
         """Reverts the download behavior to the default behavior for the extension, otherwise our
         extension cannot download files.

narada/config.py

@@ -22,6 +22,50 @@ def _default_user_data_dir() -> str:
     return str(Path("~/.config/narada/user-data-dirs/default").expanduser())
 
 
+@dataclass
+class ProxyConfig:
+    """Configuration for HTTP/HTTPS/SOCKS5 proxy.
+
+    Args:
+        server: Proxy server URL. HTTP and SOCKS proxies are supported, for example
+                "http://myproxy.com:3128" or "socks5://myproxy.com:3128".
+                Short form "myproxy.com:3128" is considered an HTTP proxy.
+        username: Optional username for proxy authentication.
+        password: Optional password for proxy authentication.
+        bypass: Optional comma-separated domains to bypass proxy,
+                for example ".com, chromium.org, .domain.com".
+        ignore_cert_errors: If True, ignore SSL certificate errors. Required for proxies that
+                            perform HTTPS inspection (MITM). Use with caution.
+    """
+
+    server: str
+    username: str | None = None
+    password: str | None = None
+    bypass: str | None = None
+    ignore_cert_errors: bool = False
+
+    @property
+    def requires_authentication(self) -> bool:
+        """Returns True if proxy requires authentication."""
+        return self.username is not None and self.password is not None
+
+    def validate(self) -> None:
+        """Validates the proxy configuration.
+
+        Raises:
+            ValueError: If configuration is invalid.
+        """
+        if not self.server:
+            raise ValueError("Proxy server cannot be empty")
+
+        # Validate that if one credential is provided, both are provided
+        if (self.username is None) != (self.password is None):
+            raise ValueError(
+                "Both username and password must be provided for proxy authentication, "
+                "or neither should be provided"
+            )
+
+
 @dataclass
 class BrowserConfig:
     executable_path: str = field(default_factory=_default_executable_path)
@@ -32,6 +76,7 @@ class BrowserConfig:
     initialization_url: str = "https://app.narada.ai/initialize"
     extension_id: str = "bhioaidlggjdkheaajakomifblpjmokn"
     interactive: bool = True
+    proxy: ProxyConfig | None = None
 
     @property
     def cdp_url(self) -> str:

narada/window.py

@@ -4,12 +4,16 @@ import time
 from abc import ABC
 from http import HTTPStatus
 from pathlib import Path
-from typing import IO, Any, TypeVar, overload
+from typing import IO, Any, Optional, TypeVar, overload
 
 import aiohttp
 from narada_core.actions.models import (
+    ActionTraceItem,
     AgenticSelectorAction,
     AgenticSelectorRequest,
+    AgenticSelectorResponse,
+    AgenticMouseActionRequest,
+    AgenticMouseAction,
     AgenticSelectors,
     AgentResponse,
     AgentUsage,
@@ -21,6 +25,7 @@ from narada_core.actions.models import (
     ReadGoogleSheetRequest,
     ReadGoogleSheetResponse,
     WriteGoogleSheetRequest,
+    RecordedClick,
 )
 from narada_core.errors import (
     NaradaAgentTimeoutError_INTERNAL_DO_NOT_USE,
@@ -121,6 +126,7 @@ class BaseBrowserWindow(ABC):
         variables: dict[str, str] | None = None,
         callback_url: str | None = None,
         callback_secret: str | None = None,
+        callback_headers: dict[str, Any] | None = None,
         timeout: int = 1000,
     ) -> Response[None]: ...
 
@@ -142,6 +148,7 @@ class BaseBrowserWindow(ABC):
         variables: dict[str, str] | None = None,
         callback_url: str | None = None,
         callback_secret: str | None = None,
+        callback_headers: dict[str, Any] | None = None,
         timeout: int = 1000,
     ) -> Response[_StructuredOutput]: ...
 
@@ -162,6 +169,7 @@ class BaseBrowserWindow(ABC):
         variables: dict[str, str] | None = None,
         callback_url: str | None = None,
         callback_secret: str | None = None,
+        callback_headers: dict[str, Any] | None = None,
         timeout: int = 1000,
     ) -> Response:
         """Low-level API for invoking an agent in the Narada extension side panel chat.
@@ -205,6 +213,8 @@ class BaseBrowserWindow(ABC):
             body["callbackUrl"] = callback_url
         if callback_secret is not None:
             body["callbackSecret"] = callback_secret
+        if callback_headers is not None:
+            body["callbackHeaders"] = callback_headers
 
         try:
             async with aiohttp.ClientSession() as session:
@@ -309,12 +319,20 @@ class BaseBrowserWindow(ABC):
         response_content = remote_dispatch_response["response"]
         assert response_content is not None
 
+        action_trace_raw = response_content.get("actionTrace")
+        action_trace = (
+            [ActionTraceItem.model_validate(item) for item in action_trace_raw]
+            if action_trace_raw is not None
+            else None
+        )
+
         return AgentResponse(
             request_id=remote_dispatch_response["requestId"],
             status=remote_dispatch_response["status"],
             text=response_content["text"],
             structured_output=response_content.get("structuredOutput"),
             usage=AgentUsage.model_validate(remote_dispatch_response["usage"]),
+            action_trace=action_trace,
         )
 
     async def agentic_selector(
@@ -325,14 +343,47 @@ class BaseBrowserWindow(ABC):
         fallback_operator_query: str,
         # Larger default timeout because Operator can take a bit to run.
         timeout: int | None = 60,
-    ) -> None:
+    ) -> AgenticSelectorResponse:
         """Performs an action on an element specified by the given selectors, falling back to using
         the Operator agent if the selectors fail to match a unique element.
         """
-        return await self._run_extension_action(
+        response_model = (
+            AgenticSelectorResponse
+            if action["type"] in {"get_text", "get_property"}
+            else None
+        )
+        result = await self._run_extension_action(
             AgenticSelectorRequest(
                 action=action,
                 selectors=selectors,
+                response_model=response_model,
+                fallback_operator_query=fallback_operator_query,
+            ),
+            timeout=timeout,
+        )
+
+        if result is None:
+            return {"value": None}
+
+        return result
+
+    async def agentic_mouse_action(
+        self,
+        *,
+        action: AgenticMouseAction,
+        recorded_click: RecordedClick,
+        fallback_operator_query: str,
+        resize_window: bool = True,
+        timeout: int | None = 60,
+    ) -> None:
+        """Performs a mouse action at the specified click coordinates, falling back to using
+        the Operator agent if the click fails.
+        """
+        return await self._run_extension_action(
+            AgenticMouseActionRequest(
+                action=action,
+                recorded_click=recorded_click,
+                resize_window=resize_window,
                 fallback_operator_query=fallback_operator_query,
             ),
             timeout=timeout,

{narada-0.1.28.dist-info → narada-0.1.30.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: narada
-Version: 0.1.28
+Version: 0.1.30
 Summary: Python client SDK for Narada
 Project-URL: Homepage, https://github.com/NaradaAI/narada-python-sdk/narada
 Project-URL: Repository, https://github.com/NaradaAI/narada-python-sdk
@@ -9,7 +9,7 @@ Author-email: Narada <support@narada.ai>
 License-Expression: Apache-2.0
 Requires-Python: >=3.12
 Requires-Dist: aiohttp>=3.12.13
-Requires-Dist: narada-core==0.0.6
+Requires-Dist: narada-core==0.0.8
 Requires-Dist: playwright>=1.53.0
 Requires-Dist: rich>=14.0.0
 Requires-Dist: semver>=3.0.4

narada-0.1.30.dist-info/RECORD

@@ -0,0 +1,10 @@
+narada/__init__.py,sha256=2AnpZVQpkh4-onnvbgHX1Wlq1Fa8ya4vAzy2fbS0bCY,968
+narada/client.py,sha256=_nTRHkiYt7lmUgO0HibVagrPXf523LCbWx8JmuVGgoo,21622
+narada/config.py,sha256=S0B8GNd-0td_69oKaPN60WAq_ODeYU7avE_KAxN5vCg,3052
+narada/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+narada/utils.py,sha256=gdLwNMXPpRohDcIIe0cB3KhvZ8X1QfAlKVh1sXWeJmk,1284
+narada/version.py,sha256=kwW6yy0_4Pf3kt888eeCG0VwBb2L2rCkrkpdZEC_3rA,193
+narada/window.py,sha256=f4Sy_ouKLF4z_KXupoUi0WaAqpEOPp25lKHP5rY_KOA,19497
+narada-0.1.30.dist-info/METADATA,sha256=xCsQXj57ZyUGjUFT0NFZUNQ3MwxFJCoy7mNKHVdLEjs,5146
+narada-0.1.30.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+narada-0.1.30.dist-info/RECORD,,

narada-0.1.28.dist-info/RECORD

@@ -1,10 +0,0 @@
-narada/__init__.py,sha256=Jk941BV4iy70Ei2MmHkNXEOkZUHBa6Lij_jZZRfiyhg,936
-narada/client.py,sha256=r_aBtqVYEBsr5N9E79qzl8q498F6cnSyejqZWSbB4qU,16768
-narada/config.py,sha256=tvj16P_qAHOFB2O_VlrcizA8SrbmS_Nmkm2r7ltG-VM,1345
-narada/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-narada/utils.py,sha256=gdLwNMXPpRohDcIIe0cB3KhvZ8X1QfAlKVh1sXWeJmk,1284
-narada/version.py,sha256=kwW6yy0_4Pf3kt888eeCG0VwBb2L2rCkrkpdZEC_3rA,193
-narada/window.py,sha256=OGuEs778xjxHivzWlJIIHKZPqGd4Sn9_YVArt_8TYoU,17762
-narada-0.1.28.dist-info/METADATA,sha256=jVmIONyot5rg8HLvqMIpSIjj2h25ycOoTbQcnb_8TnQ,5146
-narada-0.1.28.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-narada-0.1.28.dist-info/RECORD,,