agentlink-sdk 1.0.0__py3-none-any.whl

agentlink_sdk/client.py

@@ -0,0 +1,672 @@
+"""
+AgentLink SDK Main Client
+
+Provides a high-level, Pythonic API for interacting with the
+China Mobile Cloud AgentLink MCP Gateway.
+
+Supports:
+- Sandbox lifecycle management (create, destroy, list, reuse)
+- Browser automation (navigate, click, type, screenshot, evaluate)
+- Windows desktop control (click, type, PowerShell, screenshot)
+- Generic MCP tool invocation
+"""
+
+import os
+import threading
+import time
+import warnings
+from typing import Any, Dict, List, Optional, Union
+
+from .browser import BrowserController
+from .config import AgentLinkConfig, DEFAULT_MCP_URL
+from .desktop import DesktopController
+from .exceptions import (
+    ConfigurationError,
+    SandboxError,
+)
+from .logger import get_logger, _log_operation_start, _log_operation_success, _log_operation_error
+from .models.results import SandboxResult, ToolResult
+from .models.sandbox import IMAGE_BROWSER, IMAGE_WINDOWS, SandboxSession, SandboxType
+from .transport.mcp import McpTransport
+
+logger = get_logger("client")
+
+# Default sandbox readiness wait time (seconds)
+DEFAULT_SANDBOX_READY_WAIT = 3
+
+
+class AgentLink:
+    """
+    Main client for the AgentLink MCP Gateway.
+
+    Provides a high-level API for cloud sandbox management and automation.
+    Supports browser automation, Windows desktop control, and generic
+    MCP tool invocation.
+
+    Features:
+    - Automatic sandbox creation and caching (reuse across calls)
+    - Thread-safe sandbox cache
+    - MCP Streamable HTTP protocol (JSON-RPC 2.0)
+    - Retry logic and timeout handling
+    - Convenience wrappers for browser and Windows operations
+
+    Usage:
+        ```python
+        from agentlink_sdk import AgentLink
+
+        al = AgentLink(api_key="your-api-key")
+
+        # Browser automation
+        al.browser.go("https://www.baidu.com")
+        al.browser.capture().save("page.png")
+
+        # Desktop control
+        al.desktop.shell("Get-Date")
+        al.desktop.capture().save("desktop.png")
+
+        # Clean up
+        al.cleanup()
+        ```
+
+    Environment Variables:
+        AGENTLINK_API_KEY: API key for authentication.
+        AGENTLINK_MCP_URL: MCP gateway endpoint URL (optional).
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        mcp_url: Optional[str] = None,
+        config: Optional[AgentLinkConfig] = None,
+        request_timeout: Union[int, float] = 30,
+        max_retries: int = 2,
+        sandbox_id: Optional[str] = None,
+        sandbox_type: Union[str, SandboxType] = SandboxType.BROWSER,
+    ):
+        """
+        Initialize the AgentLink client.
+
+        Args:
+            api_key: API key for authentication. Can also be set via
+                     AGENTLINK_API_KEY environment variable.
+            mcp_url: MCP gateway URL. Defaults to the AgentLink cloud endpoint.
+                     Can also be set via AGENTLINK_MCP_URL environment variable.
+            config: Optional pre-built configuration object. If provided,
+                    api_key and mcp_url are ignored.
+            request_timeout: Timeout for MCP tool calls in seconds (default: 30).
+            max_retries: Maximum number of retries for failed operations (default: 2).
+            sandbox_id: Optional existing sandbox ID to reuse. If provided,
+                        the client will use this sandbox instead of creating
+                        a new one on first operation.
+            sandbox_type: Type of the sandbox (default: browser). Used together
+                          with sandbox_id to register the correct sandbox type.
+        """
+        if config is not None:
+            self._config = config
+        else:
+            resolved_key = api_key or os.environ.get("AGENTLINK_API_KEY")
+            resolved_url = mcp_url or os.environ.get("AGENTLINK_MCP_URL", DEFAULT_MCP_URL)
+
+            if not resolved_key:
+                raise ConfigurationError(
+                    "API key is required. Pass api_key parameter or set "
+                    "AGENTLINK_API_KEY environment variable."
+                )
+
+            self._config = AgentLinkConfig(
+                api_key=resolved_key,
+                mcp_url=resolved_url,
+                request_timeout=request_timeout,
+                max_retries=max_retries,
+            )
+
+        self._transport = McpTransport(self._config)
+        self._sandbox_cache: Dict[str, List[SandboxSession]] = {}
+        self._lock = threading.Lock()
+        # Per-image_id locks for fine-grained locking during sandbox creation
+        self._image_locks: Dict[str, threading.Lock] = {}
+        self._image_locks_lock = threading.Lock()  # Protects _image_locks dict
+
+        # Pre-populate sandbox cache if sandbox_id is provided
+        if sandbox_id:
+            if isinstance(sandbox_type, str):
+                sandbox_type = SandboxType(sandbox_type)
+            image_id = sandbox_type.get_image_id()
+            session = SandboxSession(
+                sandbox_id=sandbox_id,
+                image_id=image_id,
+                created_at=time.time(),
+            )
+            self._sandbox_cache.setdefault(image_id, []).append(session)
+            logger.info("Reusing existing sandbox: %s (image=%s)", sandbox_id, image_id)
+
+        # Lazy-initialized controller namespaces
+        self._browser: Optional[BrowserController] = None
+        self._desktop: Optional[DesktopController] = None
+
+        # Stores the exception from __exit__ cleanup (if any), so callers
+        # can inspect it after a ``with`` block to detect sandbox leaks.
+        self.cleanup_error: Optional[Exception] = None
+
+        # Flag to track whether the client has been closed (for idempotency)
+        self._closed: bool = False
+
+    # ---- Controller properties ----
+
+    @property
+    def browser(self) -> BrowserController:
+        """
+        Browser automation controller.
+
+        Returns a :class:`BrowserController` for browser sandbox interactions.
+        Automatically creates / reuses a browser sandbox as needed.
+
+        Example::
+
+            al.browser.go("https://example.com")
+            al.browser.capture().save("screenshot.png")
+        """
+        if self._browser is None:
+            self._browser = BrowserController(self, IMAGE_BROWSER)
+        return self._browser
+
+    @property
+    def desktop(self) -> DesktopController:
+        """
+        Windows desktop automation controller.
+
+        Returns a :class:`DesktopController` for Windows sandbox interactions.
+        Automatically creates / reuses a Windows sandbox as needed.
+
+        Example::
+
+            al.desktop.shell("Get-Date")
+            al.desktop.capture().save("desktop.png")
+        """
+        if self._desktop is None:
+            self._desktop = DesktopController(self, IMAGE_WINDOWS)
+        return self._desktop
+
+    # ---- Sandbox Lifecycle ----
+
+    def create(
+        self,
+        sandbox_type: Union[str, SandboxType] = SandboxType.BROWSER,
+        image_id: Optional[str] = None,
+        wait: int = DEFAULT_SANDBOX_READY_WAIT,
+    ) -> SandboxResult:
+        """
+        Create a new sandbox session.
+
+        Args:
+            sandbox_type: Type of sandbox to create ("browser" or "windows").
+                          Ignored if image_id is provided.
+            image_id: Explicit image ID. Overrides sandbox_type if provided.
+            wait: Seconds to wait for sandbox readiness (default: 3).
+
+        Returns:
+            SandboxResult: Result containing the sandbox ID.
+
+        Raises:
+            SandboxError: If sandbox creation fails.
+        """
+        if image_id is None:
+            if isinstance(sandbox_type, str):
+                sandbox_type = SandboxType(sandbox_type)
+            image_id = sandbox_type.get_image_id()
+
+        _log_operation_start("Creating sandbox", f"image={image_id}")
+
+        try:
+            result = self._transport.call_tool(image_id, "create_sandbox", {})
+
+            if not result.success:
+                detail = result.error or "Unknown error"
+                # Include data payload in error log if present (may contain
+                # server-side details such as stack trace or error codes)
+                if result.data is not None:
+                    logger.error(
+                        "Create sandbox failed: %s | data=%s | content=%s",
+                        detail, result.data, result.content,
+                    )
+                _log_operation_error("Create sandbox", detail)
+                return SandboxResult(success=False, error=detail)
+
+            # Extract sandbox ID
+            sandbox_id: Optional[str] = None
+            if isinstance(result.data, dict):
+                sandbox_id = str(result.data.get("resourceId", result.data.get("sandboxId", "")))
+            elif isinstance(result.data, str):
+                sandbox_id = result.data.strip()
+            else:
+                sandbox_id = result.text.strip()
+
+            if not sandbox_id:
+                _log_operation_error("Create sandbox", "No sandbox ID in response")
+                return SandboxResult(success=False, error="No sandbox ID in response")
+
+            # Wait for readiness
+            if wait > 0:
+                logger.info("Waiting %ds for sandbox readiness...", wait)
+                time.sleep(wait)
+
+            # Cache the session
+            session = SandboxSession(
+                sandbox_id=sandbox_id,
+                image_id=image_id,
+                created_at=time.time(),
+            )
+            with self._lock:
+                self._sandbox_cache.setdefault(image_id, []).append(session)
+
+            _log_operation_success("Sandbox created", f"id={sandbox_id}")
+            return SandboxResult(
+                sandbox_id=sandbox_id,
+                success=True,
+            )
+
+        except Exception as e:
+            _log_operation_error("Create sandbox", str(e))
+            raise SandboxError(f"Failed to create sandbox: {e}", image_id=image_id) from e
+
+    def delete(
+        self,
+        sandbox_id: Optional[str] = None,
+        image_id: Optional[str] = None,
+    ) -> bool:
+        """
+        Delete/destroy a sandbox session.
+
+        Args:
+            sandbox_id: The sandbox ID to destroy. If not provided,
+                        destroys the last cached sandbox for the given image_id.
+            image_id: The image ID associated with the sandbox.
+                      Required if sandbox_id is not provided.
+
+        Returns:
+            bool: True if successfully destroyed, False otherwise.
+        """
+        # If no sandbox_id, try to get from cache using image_id
+        if sandbox_id is None:
+            if image_id is None:
+                logger.warning("Either sandbox_id or image_id must be provided")
+                return False
+            with self._lock:
+                sessions = self._sandbox_cache.get(image_id, [])
+                session = sessions.pop() if sessions else None
+                if not sessions:
+                    self._sandbox_cache.pop(image_id, None)
+            if session:
+                sandbox_id = session.sandbox_id
+            else:
+                logger.warning("No sandbox ID provided and no cached sandbox found for %s", image_id)
+                return False
+
+        # If image_id is not provided, try to find it from cache by sandbox_id
+        if image_id is None:
+            with self._lock:
+                for img_id, sessions in self._sandbox_cache.items():
+                    for s in sessions:
+                        if s.sandbox_id == sandbox_id:
+                            image_id = img_id
+                            break
+                    if image_id is not None:
+                        break
+            if image_id is None:
+                logger.warning(
+                    "Cannot determine image_id for sandbox %s. "
+                    "Please provide image_id explicitly.",
+                    sandbox_id,
+                )
+                return False
+
+        _log_operation_start("Destroying sandbox", f"id={sandbox_id}")
+
+        try:
+            result = self._transport.call_tool(
+                image_id, "destroy_sandbox", {"sandboxId": sandbox_id}
+            )
+
+            # Remove from cache
+            with self._lock:
+                sessions = self._sandbox_cache.get(image_id, [])
+                self._sandbox_cache[image_id] = [
+                    s for s in sessions if s.sandbox_id != sandbox_id
+                ]
+                if not self._sandbox_cache[image_id]:
+                    self._sandbox_cache.pop(image_id, None)
+
+            if result.success:
+                _log_operation_success("Sandbox destroyed", f"id={sandbox_id}")
+            else:
+                _log_operation_error("Destroy sandbox", result.error or "Unknown error")
+
+            return result.success
+
+        except Exception as e:
+            _log_operation_error("Destroy sandbox", str(e))
+            # Still remove from cache to avoid stale references
+            with self._lock:
+                sessions = self._sandbox_cache.get(image_id, [])
+                self._sandbox_cache[image_id] = [
+                    s for s in sessions if s.sandbox_id != sandbox_id
+                ]
+                if not self._sandbox_cache.get(image_id):
+                    self._sandbox_cache.pop(image_id, None)
+            return False
+
+    def _fetch_resource_url(self, sandbox_id: str, image_id: str) -> Optional[str]:
+        """Fetch the preview URL for a sandbox session (no caching).
+
+        Args:
+            sandbox_id: The sandbox session ID.
+            image_id: The image ID to use for the request.
+
+        Returns:
+            str: Preview URL, or None if unavailable.
+        """
+        try:
+            result = self._transport.call_tool(
+                image_id, "get_sandbox_url", {"sandboxId": sandbox_id}
+            )
+            if result.success:
+                url = result.text.strip() or (
+                    result.data.get("resourceUrl") if isinstance(result.data, dict) else None
+                )
+                return url
+            return None
+        except Exception as e:
+            logger.warning("Failed to fetch resource URL: %s", e)
+            return None
+
+    def get_url(self, sandbox_id: str, image_id: Optional[str] = None) -> Optional[str]:
+        """
+        Get the preview URL for a sandbox.
+
+        Args:
+            sandbox_id: The sandbox session ID.
+            image_id: The image ID. If not provided, the method will
+                      look up the image ID from the sandbox cache.
+
+        Returns:
+            str: Preview URL, or None if not available.
+
+        Raises:
+            ValueError: If *image_id* is not provided and *sandbox_id*
+                        is not found in the sandbox cache.
+        """
+        # Auto-detect image_id from sandbox cache if not provided
+        if image_id is None:
+            with self._lock:
+                for img_id, sessions in self._sandbox_cache.items():
+                    for s in sessions:
+                        if s.sandbox_id == sandbox_id:
+                            image_id = img_id
+                            break
+                    if image_id is not None:
+                        break
+            if image_id is None:
+                raise ValueError(
+                    f"image_id not provided and sandbox '{sandbox_id}' not found "
+                    f"in cache; please pass image_id explicitly"
+                )
+
+        return self._fetch_resource_url(sandbox_id, image_id)
+
+    def list_sessions(self) -> List[SandboxSession]:
+        """
+        List all currently cached (active) sandbox sessions.
+
+        Returns:
+            List[SandboxSession]: List of active sessions.
+        """
+        with self._lock:
+            return [s for sessions in self._sandbox_cache.values() for s in sessions]
+
+    def cleanup(self) -> List[str]:
+        """
+        Destroy all cached sandboxes.
+
+        Returns:
+            List[str]: List of destroyed sandbox IDs.
+        """
+        destroyed = []
+        with self._lock:
+            # Collect all (image_id, sandbox_id) pairs
+            pairs = [
+                (img_id, session.sandbox_id)
+                for img_id, sessions in self._sandbox_cache.items()
+                for session in sessions
+            ]
+
+        for img_id, sbx_id in pairs:
+            if self.delete(sandbox_id=sbx_id, image_id=img_id):
+                destroyed.append(sbx_id)
+
+        _log_operation_success("Cleanup complete", f"destroyed {len(destroyed)} sandboxes")
+        return destroyed
+
+    # ---- Generic Tool Calls ----
+
+    def call_tool(
+        self,
+        tool_name: str,
+        image_id: str,
+        arguments: Optional[Dict[str, Any]] = None,
+    ) -> ToolResult:
+        """
+        Call any MCP tool on the specified sandbox type.
+
+        Automatically creates/reuses a sandbox if sandboxId is needed
+        but not provided in the arguments.
+
+        This is a **low-level** API that returns :class:`ToolResult`.
+        For a higher-level experience, use ``al.browser.*`` or ``al.desktop.*``.
+
+        Args:
+            tool_name: Name of the MCP tool to call.
+            image_id: Sandbox image ID (e.g. ``IMAGE_BROWSER`` or ``IMAGE_WINDOWS``).
+            arguments: Tool arguments dict.
+
+        Returns:
+            ToolResult: Parsed result from the tool call.
+        """
+        args = dict(arguments or {})
+        if "sandboxId" not in args:
+            args["sandboxId"] = self._acquire_sandbox(image_id)
+        return self._transport.call_tool(image_id, tool_name, args)
+
+    def list_tools(self, image_id: str) -> ToolResult:
+        """
+        List available MCP tools for the given sandbox type.
+
+        Args:
+            image_id: Sandbox image ID (e.g. ``IMAGE_BROWSER`` or ``IMAGE_WINDOWS``).
+
+        Returns:
+            ToolResult: Result containing the list of available tools.
+        """
+        return self._transport.list_tools(image_id)
+
+    # ---- Internal methods ----
+
+    def _invoke(
+        self,
+        image_id: str,
+        tool_name: str,
+        arguments: Dict[str, Any],
+    ):
+        """
+        Call an MCP tool with automatic sandbox injection.
+
+        If ``sandboxId`` is missing from *arguments*, a sandbox is
+        created or reused and the ID is injected automatically.
+
+        Args:
+            image_id: Sandbox image ID.
+            tool_name: MCP tool name.
+            arguments: Tool arguments dict.
+
+        Returns:
+            ActionResult: Parsed outcome.
+        """
+        from .models.results import ActionResult
+
+        if "sandboxId" not in arguments:
+            sid = self._acquire_sandbox(image_id)
+            arguments = {"sandboxId": sid, **arguments}
+
+        raw = self._transport.call_tool(image_id, tool_name, arguments)
+        return ActionResult(
+            success=raw.success,
+            text=raw.text,
+            data=raw.data,
+            error=raw.error,
+            raw=raw.content,
+        )
+
+    def _invoke_raw(
+        self,
+        image_id: str,
+        tool_name: str,
+        arguments: Dict[str, Any],
+    ) -> dict:
+        """
+        Call an MCP tool and return the raw JSON-RPC response.
+
+        Used for operations (e.g. screenshots) that need to parse
+        binary / image data directly.
+
+        Args:
+            image_id: Sandbox image ID.
+            tool_name: MCP tool name.
+            arguments: Tool arguments dict.
+
+        Returns:
+            dict: Raw JSON-RPC response.
+        """
+        if "sandboxId" not in arguments:
+            sid = self._acquire_sandbox(image_id)
+            arguments = {"sandboxId": sid, **arguments}
+
+        return self._transport.call_tool_raw(image_id, tool_name, arguments)
+
+    def _get_image_lock(self, image_id: str) -> threading.Lock:
+        """Get or create a lock for the specified image_id.
+
+        Uses double-checked locking to safely create per-image locks.
+
+        Args:
+            image_id: The sandbox image ID.
+
+        Returns:
+            threading.Lock: A lock specific to the image_id.
+        """
+        # First check without lock (fast path)
+        lock = self._image_locks.get(image_id)
+        if lock is not None:
+            return lock
+
+        # Acquire lock to safely create new image lock
+        with self._image_locks_lock:
+            # Double-check after acquiring lock
+            lock = self._image_locks.get(image_id)
+            if lock is None:
+                lock = threading.Lock()
+                self._image_locks[image_id] = lock
+            return lock
+
+    def _acquire_sandbox(self, image_id: str) -> str:
+        """
+        Get an existing cached sandbox or create a new one.
+
+        This is the primary method for sandbox reuse.
+        Returns the first available cached sandbox for the given image_id.
+
+        Uses double-checked locking (DCL) with per-image_id fine-grained locks
+        to prevent duplicate sandbox creation under concurrent access while
+        minimizing lock contention across different image types.
+
+        Args:
+            image_id: The sandbox image ID.
+
+        Returns:
+            str: The sandbox ID.
+        """
+        # First check: fast path without any lock
+        sessions = self._sandbox_cache.get(image_id, [])
+        if sessions:
+            session = sessions[0]
+            logger.debug("Reusing cached sandbox: %s", session)
+            return session.sandbox_id
+
+        # Acquire per-image lock for creation phase
+        image_lock = self._get_image_lock(image_id)
+        with image_lock:
+            # Second check: re-check cache after acquiring lock (DCL)
+            # Another thread may have created the sandbox while we waited
+            sessions = self._sandbox_cache.get(image_id, [])
+            if sessions:
+                session = sessions[0]
+                logger.debug("Reusing cached sandbox (after lock): %s", session)
+                return session.sandbox_id
+
+            # Still not cached — create new sandbox while holding the lock
+            # This ensures only one thread creates a sandbox per image_id
+            result = self.create(image_id=image_id)
+            if not result.success:
+                raise SandboxError(
+                    f"Failed to create sandbox: {result.error}",
+                    image_id=image_id,
+                )
+            return result.sandbox_id
+
+    # ---- Context Manager ----
+
+    def __enter__(self) -> "AgentLink":
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Clean up all sandboxes on exit.
+
+        Delegates to :meth:`close` which is idempotent. If cleanup fails,
+        the exception is stored in :attr:`cleanup_error` and a
+        :class:`RuntimeWarning` is emitted so that the caller can detect
+        potential sandbox leaks.
+        """
+        self.close()
+
+    def close(self):
+        """
+        Close the client and release all resources.
+
+        Automatically destroys all cached sandboxes before closing the
+        transport connection. If cleanup fails, the exception is stored
+        in :attr:`cleanup_error` and a :class:`RuntimeWarning` is emitted.
+
+        This method is idempotent — calling it multiple times is safe.
+        Subsequent calls after the first are no-ops.
+        """
+        if self._closed:
+            return
+        self._closed = True
+
+        try:
+            self.cleanup()
+        except Exception as e:
+            self.cleanup_error = e
+            logger.warning("Error during cleanup in close(): %s", e)
+            warnings.warn(
+                f"Sandbox cleanup failed: {e}. "
+                f"Sandboxes may have leaked. "
+                f"Inspect .cleanup_error for details.",
+                RuntimeWarning,
+                stacklevel=1,
+            )
+        finally:
+            self._transport.close()
+
+    def __repr__(self) -> str:
+        with self._lock:
+            n_sessions = sum(len(sessions) for sessions in self._sandbox_cache.values())
+        return f"AgentLink(url={self._config.mcp_url!r}, sessions={n_sessions})"