agentscope-runtime 1.0.4__py3-none-any.whl → 1.0.4a1__py3-none-any.whl

agentscope_runtime/sandbox/box/mobile/mobile_sandbox.py

@@ -5,7 +5,7 @@ import platform
 from typing import Optional, List, Union
 from urllib.parse import urlencode, urljoin
 
-from ..sandbox import Sandbox, SandboxAsync
+from agentscope_runtime.sandbox.box.sandbox import Sandbox
 
 from ...utils import build_image_uri
 from ...registry import SandboxRegistry
@@ -15,107 +15,6 @@ from ...constant import TIMEOUT
 logger = logging.getLogger(__name__)
 
 
-class HostPrerequisiteError(Exception):
-    """Exception raised when host prerequisites
-    for MobileSandbox are not met."""
-
-
-def _check_host_readiness() -> None:
-    logger.info(
-        "Performing one-time host environment check for MobileSandbox...",
-    )
-
-    architecture = platform.machine().lower()
-    if architecture in ("aarch64", "arm64"):
-        logger.warning(
-            "\n======================== WARNING ========================\n"
-            "ARM64/aarch64 architecture detected (e.g., Apple M-series).\n"
-            "Running this mobile sandbox on a non-x86_64 host may lead \n"
-            " to unexpected compatibility or performance issues.\n"
-            "=========================================================",
-        )
-
-    os_type = platform.system()
-    if os_type == "Linux":
-        try:
-            result = subprocess.run(
-                ["lsmod"],
-                capture_output=True,
-                text=True,
-                check=True,
-            )
-            loaded_modules = result.stdout
-        except (FileNotFoundError, subprocess.CalledProcessError):
-            loaded_modules = ""
-            logger.warning(
-                "Could not execute 'lsmod' to verify kernel modules.",
-            )
-
-        if "binder_linux" not in loaded_modules:
-            error_message = (
-                "\n========== HOST PREREQUISITE FAILED ==========\n"
-                "MobileSandbox requires specific kernel modules"
-                " that appear to be missing or not loaded.\n\n"
-                "To fix this, please run the following commands"
-                " on your Linux host:\n\n"
-                "## Install required kernel modules\n"
-                "sudo apt update"
-                " && sudo apt install -y linux-modules-extra-`uname -r`\n"
-                "sudo modprobe binder_linux"
-                ' devices="binder,hwbinder,vndbinder"\n'
-                "## (Optional) Load the ashmem driver for older kernels\n"
-                "sudo modprobe ashmem_linux\n"
-                "=================================================="
-            )
-            raise HostPrerequisiteError(error_message)
-
-    if os_type == "Windows":
-        try:
-            result = subprocess.run(
-                ["wsl", "lsmod"],
-                capture_output=True,
-                text=True,
-                check=True,
-                encoding="utf-8",
-            )
-            loaded_modules = result.stdout
-        except (FileNotFoundError, subprocess.CalledProcessError):
-            loaded_modules = ""
-            logger.warning(
-                "Could not execute 'wsl lsmod' to verify kernel modules.",
-            )
-
-        if "binder_linux" not in loaded_modules:
-            error_message = (
-                "\n========== HOST PREREQUISITE FAILED ==========\n"
-                "MobileSandbox on Windows requires Docker Desktop "
-                "with the WSL 2 backend.\n"
-                "The required kernel modules seem to be missing "
-                "in your WSL 2 environment.\n\n"
-                "To fix this, please follow these steps:\n\n"
-                "1. **Ensure Docker Desktop is using WSL 2**:\n"
-                "   - Open Docker Desktop -> Settings -> General.\n"
-                "   - Make sure 'Use the WSL 2 based engine' "
-                "is checked.\n\n"
-                "2. **Ensure WSL is installed and updated**:\n"
-                "   - Open PowerShell or Command Prompt "
-                "as Administrator.\n"
-                "   - Run: wsl --install\n"
-                "   - Run: wsl --update\n"
-                "   (An update usually installs a recent Linux kernel "
-                "with the required modules.)\n\n"
-                "3. **Verify manually (Optional)**:\n"
-                "   - After updating, run 'wsl lsmod | findstr binder' "
-                "in your terminal.\n"
-                "   - If it shows 'binder_linux', "
-                "the issue should be resolved.\n"
-                "=================================================="
-            )
-            raise HostPrerequisiteError(error_message)
-
-    logger.info("Host environment check passed.")
-
-
 class MobileMixin:
     @property
     def mobile_url(self):
@@ -142,41 +41,9 @@ class MobileMixin:
         )
 
 
-class AsyncMobileMixin:
-    async def get_mobile_url_async(self):
-        """
-        Asynchronously retrieve the mobile VNC/websockify connection URL.
-
-        Returns:
-            str: Fully qualified URL to access the mobile sandbox UI remotely.
-
-        Raises:
-            RuntimeError: If the sandbox is not healthy.
-        """
-        # Check health asynchronously
-        is_healthy = await self.manager_api.check_health_async(
-            identity=self.sandbox_id,
-        )
-        if not is_healthy:
-            raise RuntimeError(f"Sandbox {self.sandbox_id} is not healthy")
-
-        # Get container info asynchronously
-        info = await self.get_info_async()
-
-        # Local path and remote path (currently the same)
-        path = "/websockify/"
-        remote_path = "/websockify/"
-        params = {"password": info["runtime_token"]}
-
-        # Local URL if base_url is not set
-        if self.base_url is None:
-            return urljoin(info["url"], path) + "?" + urlencode(params)
-
-        # Remote URL
-        return (
-            f"{self.base_url}/desktop/{self.sandbox_id}{remote_path}"
-            f"?{urlencode(params)}"
-        )
+class HostPrerequisiteError(Exception):
+    """Exception raised when host prerequisites
+    for MobileSandbox are not met."""
 
 
 @SandboxRegistry.register(
@@ -199,7 +66,7 @@ class MobileSandbox(MobileMixin, Sandbox):
         sandbox_type: SandboxType = SandboxType.MOBILE,
     ):
         if base_url is None and not self.__class__._host_check_done:
-            _check_host_readiness()
+            self._check_host_readiness()
             self.__class__._host_check_done = True
 
         super().__init__(
@@ -210,6 +77,101 @@ class MobileSandbox(MobileMixin, Sandbox):
             sandbox_type,
         )
 
+    def _check_host_readiness(self) -> None:
+        logger.info(
+            "Performing one-time host environment check for MobileSandbox...",
+        )
+
+        architecture = platform.machine().lower()
+        if architecture in ("aarch64", "arm64"):
+            logger.warning(
+                "\n======================== WARNING ========================\n"
+                "ARM64/aarch64 architecture detected (e.g., Apple M-series).\n"
+                "Running this mobile sandbox on a non-x86_64 host may lead \n"
+                " to unexpected compatibility or performance issues.\n"
+                "=========================================================",
+            )
+
+        os_type = platform.system()
+        if os_type == "Linux":
+            try:
+                result = subprocess.run(
+                    ["lsmod"],
+                    capture_output=True,
+                    text=True,
+                    check=True,
+                )
+                loaded_modules = result.stdout
+            except (FileNotFoundError, subprocess.CalledProcessError):
+                loaded_modules = ""
+                logger.warning(
+                    "Could not execute 'lsmod' to verify kernel modules.",
+                )
+
+            if "binder_linux" not in loaded_modules:
+                error_message = (
+                    "\n========== HOST PREREQUISITE FAILED ==========\n"
+                    "MobileSandbox requires specific kernel modules"
+                    " that appear to be missing or not loaded.\n\n"
+                    "To fix this, please run the following commands"
+                    " on your Linux host:\n\n"
+                    "## Install required kernel modules\n"
+                    "sudo apt update"
+                    " && sudo apt install -y linux-modules-extra-`uname -r`\n"
+                    "sudo modprobe binder_linux"
+                    ' devices="binder,hwbinder,vndbinder"\n'
+                    "## (Optional) Load the ashmem driver for older kernels\n"
+                    "sudo modprobe ashmem_linux\n"
+                    "=================================================="
+                )
+                raise HostPrerequisiteError(error_message)
+
+        if os_type == "Windows":
+            try:
+                result = subprocess.run(
+                    ["wsl", "lsmod"],
+                    capture_output=True,
+                    text=True,
+                    check=True,
+                    encoding="utf-8",
+                )
+                loaded_modules = result.stdout
+            except (FileNotFoundError, subprocess.CalledProcessError):
+                loaded_modules = ""
+                logger.warning(
+                    "Could not execute 'wsl lsmod' to verify kernel modules.",
+                )
+
+            if "binder_linux" not in loaded_modules:
+                error_message = (
+                    "\n========== HOST PREREQUISITE FAILED ==========\n"
+                    "MobileSandbox on Windows requires Docker Desktop "
+                    "with the WSL 2 backend.\n"
+                    "The required kernel modules seem to be missing "
+                    "in your WSL 2 environment.\n\n"
+                    "To fix this, please follow these steps:\n\n"
+                    "1. **Ensure Docker Desktop is using WSL 2**:\n"
+                    "   - Open Docker Desktop -> Settings -> General.\n"
+                    "   - Make sure 'Use the WSL 2 based engine' "
+                    "is checked.\n\n"
+                    "2. **Ensure WSL is installed and updated**:\n"
+                    "   - Open PowerShell or Command Prompt "
+                    "as Administrator.\n"
+                    "   - Run: wsl --install\n"
+                    "   - Run: wsl --update\n"
+                    "   (An update usually installs a recent Linux kernel "
+                    "with the required modules.)\n\n"
+                    "3. **Verify manually (Optional)**:\n"
+                    "   - After updating, run 'wsl lsmod | findstr binder' "
+                    "in your terminal.\n"
+                    "   - If it shows 'binder_linux', "
+                    "the issue should be resolved.\n"
+                    "=================================================="
+                )
+                raise HostPrerequisiteError(error_message)
+
+        logger.info("Host environment check passed.")
+
     def adb_use(
         self,
         action: str,
@@ -326,112 +288,3 @@ class MobileSandbox(MobileMixin, Sandbox):
     def mobile_get_screenshot(self):
         """Take a screenshot of the current device screen."""
         return self.call_tool("adb", {"action": "get_screenshot"})
-
-
-@SandboxRegistry.register(
-    build_image_uri("runtime-sandbox-mobile"),
-    sandbox_type=SandboxType.MOBILE_ASYNC,
-    security_level="high",
-    timeout=TIMEOUT,
-    description="Mobile Sandbox (Async)",
-    runtime_config={"privileged": True},
-)
-class MobileSandboxAsync(MobileMixin, AsyncMobileMixin, SandboxAsync):
-    _host_check_done = False
-
-    def __init__(
-        self,
-        sandbox_id: Optional[str] = None,
-        timeout: int = 3000,
-        base_url: Optional[str] = None,
-        bearer_token: Optional[str] = None,
-        sandbox_type: SandboxType = SandboxType.MOBILE_ASYNC,
-    ):
-        if base_url is None and not self.__class__._host_check_done:
-            _check_host_readiness()
-            self.__class__._host_check_done = True
-
-        super().__init__(
-            sandbox_id,
-            timeout,
-            base_url,
-            bearer_token,
-            sandbox_type,
-        )
-
-    async def adb_use(
-        self,
-        action: str,
-        coordinate: Optional[List[int]] = None,
-        start: Optional[List[int]] = None,
-        end: Optional[List[int]] = None,
-        duration: Optional[int] = None,
-        code: Optional[Union[int, str]] = None,
-        text: Optional[str] = None,
-    ):
-        """
-        Asynchronously execute a general-purpose ADB action.
-        """
-        payload = {"action": action}
-        if coordinate is not None:
-            payload["coordinate"] = coordinate
-        if start is not None:
-            payload["start"] = start
-        if end is not None:
-            payload["end"] = end
-        if duration is not None:
-            payload["duration"] = duration
-        if code is not None:
-            payload["code"] = code
-        if text is not None:
-            payload["text"] = text
-
-        return await self.call_tool_async("adb", payload)
-
-    async def mobile_get_screen_resolution(self):
-        """Asynchronously get the screen resolution."""
-        return await self.call_tool_async(
-            "adb",
-            {"action": "get_screen_resolution"},
-        )
-
-    async def mobile_tap(self, coordinate: List[int]):
-        """Asynchronously tap specific screen coordinates."""
-        return await self.call_tool_async(
-            "adb",
-            {"action": "tap", "coordinate": coordinate},
-        )
-
-    async def mobile_swipe(
-        self,
-        start: List[int],
-        end: List[int],
-        duration: Optional[int] = None,
-    ):
-        """Asynchronously perform a swipe gesture."""
-        payload = {
-            "action": "swipe",
-            "start": start,
-            "end": end,
-        }
-        if duration is not None:
-            payload["duration"] = duration
-        return await self.call_tool_async("adb", payload)
-
-    async def mobile_input_text(self, text: str):
-        """Asynchronously input text into the focused UI element."""
-        return await self.call_tool_async(
-            "adb",
-            {"action": "input_text", "text": text},
-        )
-
-    async def mobile_key_event(self, code: Union[int, str]):
-        """Asynchronously send a key event to the device."""
-        return await self.call_tool_async(
-            "adb",
-            {"action": "key_event", "code": code},
-        )
-
-    async def mobile_get_screenshot(self):
-        """Asynchronously take a screenshot."""
-        return await self.call_tool_async("adb", {"action": "get_screenshot"})

agentscope_runtime/sandbox/box/sandbox.py

@@ -12,46 +12,71 @@ logging.basicConfig(level=logging.INFO)
 logger = logging.getLogger(__name__)
 
 
-class SandboxBase:
+class Sandbox:
     """
-    Common base class for both sync and async Sandbox interfaces.
+    Sandbox Interface.
     """
 
     def __init__(
         self,
         sandbox_id: Optional[str] = None,
-        timeout: int = 3000,
+        timeout: int = 3000,  # TODO: enable life circle management
         base_url: Optional[str] = None,
-        bearer_token: Optional[str] = None,
+        bearer_token: Optional[str] = None,  # TODO: support api_key
         sandbox_type: SandboxType = SandboxType.BASE,
     ) -> None:
+        """
+        Initialize the sandbox interface.
+        """
         self.base_url = base_url
-        self.embed_mode = not bool(base_url)
-        self.sandbox_type = sandbox_type
-        self.timeout = timeout
-        self._sandbox_id = sandbox_id
-
         if base_url:
+            self.embed_mode = False
             self.manager_api = SandboxManager(
                 base_url=base_url,
                 bearer_token=bearer_token,
-            )
+            ).__enter__()
         else:
+            # Launch a local manager
+            self.embed_mode = True
             self.manager_api = SandboxManager(
                 default_type=sandbox_type,
             )
 
-    @property
-    def sandbox_id(self) -> Optional[str]:
-        return self._sandbox_id
+        if sandbox_id is None:
+            logger.debug(
+                "You are using embed mode, it might take several seconds to "
+                "init the runtime, please wait.",
+            )
 
-    @sandbox_id.setter
-    def sandbox_id(self, value: str) -> None:
-        if not value:
-            raise ValueError("Sandbox ID cannot be empty.")
-        self._sandbox_id = value
+            sandbox_id = self.manager_api.create_from_pool(
+                sandbox_type=SandboxType(sandbox_type).value,
+            )
+            if sandbox_id is None:
+                raise RuntimeError(
+                    "No sandbox available. "
+                    "Please check if sandbox images exist, build or pull "
+                    "missing images in sandbox server.",
+                )
+            self._sandbox_id = sandbox_id
+
+        self._sandbox_id = sandbox_id
+        self.sandbox_type = sandbox_type
+        self.timeout = timeout
+
+        # Clean up function enabled in embed mode
+        if self.embed_mode:
+            atexit.register(self._cleanup)
+            self._register_signal_handlers()
+
+    def _register_signal_handlers(self) -> None:
+        """
+        Register signal handlers for graceful shutdown and cleanup.
+        Handles SIGINT (Ctrl+C) and, if available, SIGTERM to ensure that
+        the sandbox is properly cleaned up when the process receives these
+        signals. On platforms where SIGTERM is not available (e.g.,
+        Windows), only SIGINT is handled.
+        """
 
-    def _register_signal_handlers(self):
         def _handler(signum, frame):  # pylint: disable=unused-argument
             logger.debug(
                 f"Received signal {signum}, stopping Sandbox"
@@ -60,6 +85,7 @@ class SandboxBase:
             self._cleanup()
             raise SystemExit(0)
 
+        # Windows does not support SIGTERM
         if hasattr(signal, "SIGTERM"):
             signals = [signal.SIGINT, signal.SIGTERM]
         else:
@@ -81,36 +107,39 @@ class SandboxBase:
         specific sandbox instance.
         """
         try:
+            # Remote not need to close the embed_manager
             if self.embed_mode:
+                # Clean all
                 self.manager_api.__exit__(None, None, None)
             else:
+                # Clean the specific sandbox
                 self.manager_api.release(self.sandbox_id)
         except Exception as e:
             import traceback
 
             logger.error(
-                f"Cleanup {self.sandbox_id} error: {e}"
-                f"\n{traceback.format_exc()}",
+                f"Cleanup {self.sandbox_id} error: {e}\n"
+                f"{traceback.format_exc()}",
             )
 
-
-class Sandbox(SandboxBase):
     def __enter__(self):
-        # Create sandbox if sandbox_id not provided
-        if self.sandbox_id is None:
-            self.sandbox_id = self.manager_api.create_from_pool(
-                sandbox_type=SandboxType(self.sandbox_type).value,
-            )
-            if self.sandbox_id is None:
-                raise RuntimeError("No sandbox available.")
-            if self.embed_mode:
-                atexit.register(self._cleanup)
-                self._register_signal_handlers()
         return self
 
     def __exit__(self, exc_type, exc_value, traceback):
         self._cleanup()
 
+    @property
+    def sandbox_id(self) -> str:
+        """Get the sandbox ID."""
+        return self._sandbox_id
+
+    @sandbox_id.setter
+    def sandbox_id(self, value: str) -> None:
+        """Set the sandbox ID."""
+        if not value:
+            raise ValueError("Sandbox ID cannot be empty.")
+        self._sandbox_id = value
+
     def get_info(self) -> dict:
         return self.manager_api.get_info(self.sandbox_id)
 
@@ -127,77 +156,15 @@ class Sandbox(SandboxBase):
     ) -> Any:
         if arguments is None:
             arguments = {}
-        return self.manager_api.call_tool(self.sandbox_id, name, arguments)
 
-    def add_mcp_servers(self, server_configs: dict, overwrite=False):
-        return self.manager_api.add_mcp_servers(
-            self.sandbox_id,
-            server_configs,
-            overwrite,
-        )
-
-
-class SandboxAsync(SandboxBase):
-    async def __aenter__(self):
-        if self.sandbox_id is None:
-            self.sandbox_id = await self.manager_api.create_from_pool_async(
-                sandbox_type=SandboxType(self.sandbox_type).value,
-            )
-            if self.sandbox_id is None:
-                raise RuntimeError("No sandbox available.")
-            if self.embed_mode:
-                atexit.register(self._cleanup)
-                self._register_signal_handlers()
-        return self
-
-    async def __aexit__(self, exc_type, exc_value, traceback):
-        await self._cleanup_async()
-
-    async def _cleanup_async(self):
-        try:
-            if self.embed_mode:
-                await self.manager_api.__aexit__(None, None, None)
-            else:
-                await self.manager_api.release_async(self.sandbox_id)
-        except Exception as e:
-            import traceback
-
-            logger.error(
-                f"Async Cleanup {self.sandbox_id} error: {e}"
-                f"\n{traceback.format_exc()}",
-            )
-
-    async def get_info_async(self) -> dict:
-        return await self.manager_api.get_info_async(self.sandbox_id)
-
-    async def list_tools_async(
-        self,
-        tool_type: Optional[str] = None,
-    ) -> dict:
-        return await self.manager_api.list_tools_async(
-            self.sandbox_id,
-            tool_type=tool_type,
-        )
-
-    async def call_tool_async(
-        self,
-        name: str,
-        arguments: Optional[dict[str, Any]] = None,
-    ) -> Any:
-        if arguments is None:
-            arguments = {}
-        return await self.manager_api.call_tool_async(
-            self.sandbox_id,
-            name,
-            arguments,
-        )
+        return self.manager_api.call_tool(self.sandbox_id, name, arguments)
 
-    async def add_mcp_servers_async(
+    def add_mcp_servers(
         self,
         server_configs: dict,
         overwrite=False,
     ):
-        return await self.manager_api.add_mcp_servers_async(
+        return self.manager_api.add_mcp_servers(
             self.sandbox_id,
             server_configs,
             overwrite,