agentscope-runtime 0.2.0b2__py3-none-any.whl → 1.0.0__py3-none-any.whl

agentscope_runtime/sandbox/box/mobile/mobile_sandbox.py

@@ -0,0 +1,216 @@
+# -*- coding: utf-8 -*-
+import logging
+import os
+import platform
+from typing import Optional, List, Union
+
+from agentscope_runtime.sandbox.box.sandbox import Sandbox
+
+from ...utils import build_image_uri
+from ...registry import SandboxRegistry
+from ...enums import SandboxType
+from ...constant import TIMEOUT
+
+logger = logging.getLogger(__name__)
+
+
+class HostPrerequisiteError(Exception):
+    """Custom exception raised when host prerequisites
+    for MobileSandbox are not met."""
+
+
+@SandboxRegistry.register(
+    build_image_uri("runtime-sandbox-mobile"),
+    sandbox_type=SandboxType.MOBILE,
+    security_level="high",
+    timeout=TIMEOUT,
+    description="Mobile Sandbox",
+    runtime_config={"privileged": True},
+)
+class MobileSandbox(Sandbox):
+    _host_check_done = False
+
+    def __init__(  # pylint: disable=useless-parent-delegation
+        self,
+        sandbox_id: Optional[str] = None,
+        timeout: int = 3000,
+        base_url: Optional[str] = None,
+        bearer_token: Optional[str] = None,
+        sandbox_type: SandboxType = SandboxType.MOBILE,
+    ):
+        if not self.__class__._host_check_done:
+            self._check_host_readiness()
+            self.__class__._host_check_done = True
+
+        super().__init__(
+            sandbox_id,
+            timeout,
+            base_url,
+            bearer_token,
+            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"
+                "=========================================================",
+            )
+
+        if platform.system() == "Linux":
+            required_devices = [
+                "/dev/binder",
+                "/dev/hwbinder",
+                "/dev/vndbinder",
+                "/dev/ashmem",
+            ]
+
+            missing_devices = [
+                dev for dev in required_devices if not os.path.exists(dev)
+            ]
+
+            if missing_devices:
+                error_message = (
+                    f"\n========== HOST PREREQUISITE FAILED ==========\n"
+                    f"MobileSandbox requires specific kernel \
+                        modules on the host machine.\n"
+                    f"The following required device files are missing:\n"
+                    f"  - {', '.join(missing_devices)}\n\n"
+                    "To fix this, please run the following \
+                        commands on your Linux host:\n\n"
+                    "1. Install extra kernel modules:\n"
+                    "   sudo apt update && \
+                        sudo apt install -y linux-modules-extra-`uname -r`\n\n"
+                    "2. Load modules and create device nodes:\n"
+                    '   sudo modprobe binder_linux devices=\
+                        "binder,hwbinder,vndbinder"\n'
+                    "   sudo modprobe ashmem_linux\n\n"
+                    "After running these commands, verify with:\n"
+                    "   ls -l /dev/binder* /dev/ashmem\n"
+                    "=================================================="
+                )
+                raise HostPrerequisiteError(error_message)
+
+        logger.info("Host environment check passed.")
+
+    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,
+    ):
+        """A general-purpose method to execute various ADB actions.
+
+        This function acts as a low-level dispatcher for
+        different ADB commands. Only the parameters relevant
+        to the specified `action` should be provided.
+        For actions involving coordinates, the values are absolute
+        pixels, with the origin (0, 0) at the top-left of the screen.
+
+        Args:
+            action (str): The specific ADB action to perform.
+                Examples: 'tap', 'swipe', 'input_text', 'key_event',
+                'get_screenshot', 'get_screen_resolution'.
+            coordinate (Optional[List[int]]):
+                The [x, y] coordinates for a 'tap' action.
+            start (Optional[List[int]]):
+                The starting [x, y] coordinates for a 'swipe' action.
+            end (Optional[List[int]]):
+                The ending [x, y] coordinates for a 'swipe' action.
+            duration (int, optional):
+                The duration of a 'swipe' gesture in milliseconds.
+            code (int | str, optional):
+                The key event code (e.g., 3) or name
+                (e.g., 'HOME') for the 'key_event' action.
+            text (Optional[str]):
+                The text string to be entered for the 'input_text' 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 self.call_tool("adb", payload)
+
+    def mobile_get_screen_resolution(self):
+        """Get the screen resolution of the connected mobile device."""
+        return self.call_tool("adb", {"action": "get_screen_resolution"})
+
+    def mobile_tap(self, x: int, y: int):
+        """Tap a specific coordinate on the screen.
+
+        Args:
+            x (int): The x-coordinate in pixels from the left edge.
+            y (int): The y-coordinate in pixels from the top edge.
+        """
+        return self.call_tool("adb", {"action": "tap", "coordinate": [x, y]})
+
+    def mobile_swipe(
+        self,
+        start: List[int],
+        end: List[int],
+        duration: Optional[int] = None,
+    ):
+        """
+        Perform a swipe gesture on the screen
+        from a start point to an end point.
+
+        Args:
+            start (Optional[List[int]]):
+                The starting coordinates [x, y] in pixels.
+            end (Optional[List[int]]):
+                The ending coordinates [x, y] in pixels.
+            duration (int, optional):
+                The duration of the swipe in milliseconds.
+        """
+        return self.call_tool(
+            "adb",
+            {
+                "action": "swipe",
+                "start": start,
+                "end": end,
+                **({} if duration is None else {"duration": duration}),
+            },
+        )
+
+    def mobile_input_text(self, text: str):
+        """Input a text string into the currently focused UI element.
+
+        Args:
+            text (str): The string to be inputted.
+        """
+        return self.call_tool("adb", {"action": "input_text", "text": text})
+
+    def mobile_key_event(self, code: Union[int, str]):
+        """Send an Android key event to the device.
+
+        Args:
+            code (int | str): The key event code (e.g., 3 for HOME) or a
+                              string representation (e.g., 'HOME', 'BACK').
+        """
+        return self.call_tool("adb", {"action": "key_event", "code": code})
+
+    def mobile_get_screenshot(self):
+        """Take a screenshot of the current device screen."""
+        return self.call_tool("adb", {"action": "get_screenshot"})

agentscope_runtime/sandbox/box/training_box/training_box.py

@@ -206,7 +206,7 @@ class TrainingSandbox(Sandbox):
 
 
 @SandboxRegistry.register(
-    build_image_uri("runtime-sandbox-appworld", arm64_compatible=False),
+    build_image_uri("runtime-sandbox-appworld"),
     sandbox_type=SandboxType.APPWORLD,
     runtime_config={"shm_size": "5.06gb"},
     security_level="medium",
@@ -251,7 +251,7 @@ DATASET_SUB_TYPE = os.environ.get("DATASET_SUB_TYPE", "multi_turn")
 
 
 @SandboxRegistry.register(
-    build_image_uri("runtime-sandbox-bfcl", arm64_compatible=False),
+    build_image_uri("runtime-sandbox-bfcl"),
     sandbox_type=SandboxType.BFCL,
     runtime_config={"shm_size": "8.06gb"},
     security_level="medium",

agentscope_runtime/sandbox/client/http_client.py

@@ -96,6 +96,7 @@ class SandboxHttpClient:
         headers = {
             "Content-Type": "application/json",
             "x-agentrun-session-id": "s" + self.session_id,
+            "x-agentscope-runtime-session-id": "s" + self.session_id,
         }
         if self.secret:
             headers["Authorization"] = f"Bearer {self.secret}"

agentscope_runtime/sandbox/enums.py

@@ -66,5 +66,7 @@ class SandboxType(DynamicEnum):
     BROWSER = "browser"
     FILESYSTEM = "filesystem"
     GUI = "gui"
+    MOBILE = "mobile"
     APPWORLD = "appworld"
     BFCL = "bfcl"
+    AGENTBAY = "agentbay"

agentscope_runtime/sandbox/manager/sandbox_manager.py

@@ -188,6 +188,10 @@ class SandboxManager:
                 )
 
                 self.client = AgentRunClient(config=self.config)
+            elif self.container_deployment == "fc":
+                from ...common.container_clients.fc_client import FCClient
+
+                self.client = FCClient(config=self.config)
             else:
                 raise NotImplementedError("Not implemented")
         else:
@@ -486,7 +490,11 @@ class SandboxManager:
                 mount_dir = os.path.join(self.default_mount_dir, session_id)
                 os.makedirs(mount_dir, exist_ok=True)
 
-        if mount_dir and self.container_deployment != "agentrun":
+        if (
+            mount_dir
+            and self.container_deployment != "agentrun"
+            and self.container_deployment != "fc"
+        ):
             if not os.path.isabs(mount_dir):
                 mount_dir = os.path.abspath(mount_dir)
 
@@ -501,6 +509,7 @@ class SandboxManager:
             mount_dir
             and storage_path
             and self.container_deployment != "agentrun"
+            and self.container_deployment != "fc"
         ):
             self.storage.download_folder(storage_path, mount_dir)
 
@@ -516,7 +525,11 @@ class SandboxManager:
             runtime_token = secrets.token_hex(16)
 
             # Prepare volume bindings if a mount directory is provided
-            if mount_dir and self.container_deployment != "agentrun":
+            if (
+                mount_dir
+                and self.container_deployment != "agentrun"
+                and self.container_deployment != "fc"
+            ):
                 volume_bindings = {
                     mount_dir: {
                         "bind": self.workdir,

agentscope_runtime/sandbox/manager/server/app.py

@@ -93,6 +93,18 @@ def get_config() -> SandboxManagerEnvConfig:
             agent_run_prefix=settings.AGENT_RUN_PREFIX,
             agentrun_log_project=settings.AGENT_RUN_LOG_PROJECT,
             agentrun_log_store=settings.AGENT_RUN_LOG_STORE,
+            fc_access_key_id=settings.FC_ACCESS_KEY_ID,
+            fc_access_key_secret=settings.FC_ACCESS_KEY_SECRET,
+            fc_account_id=settings.FC_ACCOUNT_ID,
+            fc_region_id=settings.FC_REGION_ID,
+            fc_cpu=settings.FC_CPU,
+            fc_memory=settings.FC_MEMORY,
+            fc_vpc_id=settings.FC_VPC_ID,
+            fc_vswitch_ids=settings.FC_VSWITCH_IDS,
+            fc_security_group_id=settings.FC_SECURITY_GROUP_ID,
+            fc_prefix=settings.FC_PREFIX,
+            fc_log_project=settings.FC_LOG_PROJECT,
+            fc_log_store=settings.FC_LOG_STORE,
         )
     return _config
 

agentscope_runtime/sandbox/manager/server/config.py

@@ -28,6 +28,7 @@ class Settings(BaseSettings):
         "cloud",
         "k8s",
         "agentrun",
+        "fc",
     ] = "docker"
     DEFAULT_MOUNT_DIR: str = "sessions_mount_dir"
     # Read-only mounts (host_path -> container_path)
@@ -77,6 +78,24 @@ class Settings(BaseSettings):
     AGENT_RUN_LOG_PROJECT: Optional[str] = None
     AGENT_RUN_LOG_STORE: Optional[str] = None
 
+    # FC settings
+    FC_ACCOUNT_ID: Optional[str] = None
+    FC_ACCESS_KEY_ID: Optional[str] = None
+    FC_ACCESS_KEY_SECRET: Optional[str] = None
+    FC_REGION_ID: str = "cn-hangzhou"
+
+    FC_CPU: float = 2.0
+    FC_MEMORY: int = 2048
+
+    FC_VPC_ID: Optional[str] = None
+    FC_VSWITCH_IDS: Optional[list[str]] = None
+    FC_SECURITY_GROUP_ID: Optional[str] = None
+
+    FC_PREFIX: str = "agentscope-sandbox"
+
+    FC_LOG_PROJECT: Optional[str] = None
+    FC_LOG_STORE: Optional[str] = None
+
     model_config = ConfigDict(
         case_sensitive=True,
         extra="allow",

agentscope_runtime/sandbox/model/manager_config.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-# pylint: disable=no-self-argument
+# pylint: disable=no-self-argument, too-many-branches
 import os
 from typing import Optional, Literal, Tuple, Dict
 from pydantic import BaseModel, Field, model_validator
@@ -32,10 +32,11 @@ class SandboxManagerEnvConfig(BaseModel):
         "cloud",
         "k8s",
         "agentrun",
+        "fc",
     ] = Field(
         ...,
         description="Container deployment backend: 'docker', 'cloud', 'k8s'"
-        "or 'agentrun'.",
+        " 'agentrun' or 'fc'.",
     )
 
     default_mount_dir: Optional[str] = Field(
@@ -180,6 +181,62 @@ class SandboxManagerEnvConfig(BaseModel):
         description="Log store for AgentRun.",
     )
 
+    # FC settings
+    fc_access_key_id: Optional[str] = Field(
+        None,
+        description="Access key ID for FC. Required if "
+        "container_deployment is 'fc'.",
+    )
+    fc_access_key_secret: Optional[str] = Field(
+        None,
+        description="Access key secret for FC. "
+        "Required if container_deployment is 'fc'.",
+    )
+    fc_account_id: Optional[str] = Field(
+        None,
+        description="Account ID for FC. Required if "
+        "container_deployment is 'fc'.",
+    )
+    fc_region_id: str = Field(
+        "cn-hangzhou",
+        description="Region ID for FC.",
+    )
+    fc_cpu: float = Field(
+        2.0,
+        description="CPU allocation for FC containers.",
+    )
+    fc_memory: int = Field(
+        2048,
+        description="Memory allocation for FC containers in MB.",
+    )
+    fc_vpc_id: Optional[str] = Field(
+        None,
+        description="VPC ID for FC. Required if container_deployment "
+        "is 'FC'.",
+    )
+    fc_vswitch_ids: Optional[list[str]] = Field(
+        None,
+        description="VSwitch IDs for FC. Required if "
+        "container_deployment is 'FC'.",
+    )
+    fc_security_group_id: Optional[str] = Field(
+        None,
+        description="Security group ID for FC. "
+        "Required if container_deployment is 'FC'.",
+    )
+    fc_prefix: str = Field(
+        "agentscope-sandbox_",
+        description="Prefix for FC resources.",
+    )
+    fc_log_project: Optional[str] = Field(
+        None,
+        description="Log project for FC.",
+    )
+    fc_log_store: Optional[str] = Field(
+        None,
+        description="Log store for FC.",
+    )
+
     @model_validator(mode="after")
     def check_settings(self):
         if self.default_mount_dir:
@@ -249,4 +306,24 @@ class SandboxManagerEnvConfig(BaseModel):
                         f"container_deployment is 'agentrun'",
                     )
 
+        if self.container_deployment == "fc":
+            required_fc_fields = [
+                self.fc_access_key_id,
+                self.fc_access_key_secret,
+                self.fc_account_id,
+            ]
+            for field_name, field_value in zip(
+                [
+                    "fc_access_key_id",
+                    "fc_access_key_secret",
+                    "fc_account_id",
+                ],
+                required_fc_fields,
+            ):
+                if not field_value:
+                    raise ValueError(
+                        f"{field_name} must be set when "
+                        f"container_deployment is 'fc'",
+                    )
+
         return self

agentscope_runtime/sandbox/utils.py

@@ -13,7 +13,6 @@ def build_image_uri(
     tag: str = None,
     registry: str = None,
     namespace: str = None,
-    arm64_compatible: bool = True,
 ) -> str:
     """
     Build a fully qualified Docker image URI.
@@ -30,12 +29,6 @@ def build_image_uri(
         If empty or whitespace, registry prefix will be omitted.
     namespace : str, optional
         Docker image namespace. Defaults to the global ``IMAGE_NAMESPACE``.
-    arm64_compatible : bool, optional
-        Whether the image is ARM64-compatible without special tagging.
-        If ``True`` (default), the tag is returned unchanged.
-        If ``False``, the function will detect the current machine
-        architecture and append ``-arm64`` to the tag if running on ARM64 (
-        e.g., ``arm64``, ``aarch64``).
 
     Returns
     -------
@@ -55,10 +48,6 @@ def build_image_uri(
     >>> build_image_uri("runtime-sandbox-base", registry="")
     'agentscope/runtime-sandbox-base:latest'
 
-    >>> build_image_uri("runtime-sandbox-base", arm64_compatible=False)
-    'agentscope-registry.ap-southeast-1.cr.aliyuncs.com/agentscope/runtime
-    -sandbox-base:latest-arm64'
-    # (Above example assumes running on ARM64 machine)
     """
     reg = registry if registry is not None else REGISTRY
     reg = "" if reg.strip() == "" else f"{reg.strip()}/"
@@ -66,13 +55,6 @@ def build_image_uri(
     final_namespace = namespace if namespace is not None else IMAGE_NAMESPACE
     final_tag = tag or IMAGE_TAG
 
-    # TODO: make manifest compatible and remove this
-    # Adjust tag based on ARM64 compatibility
-    if not arm64_compatible:
-        machine = platform.machine().lower()
-        if "arm" in machine or "aarch64" in machine:
-            final_tag = f"{final_tag}-arm64"
-
     return f"{reg}{final_namespace}/{image_name}:{final_tag}"