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

agentscope_runtime/sandbox/box/browser/browser_sandbox.py

@@ -6,8 +6,8 @@ from urllib.parse import urlparse, urlunparse
 from ...utils import build_image_uri
 from ...registry import SandboxRegistry
 from ...enums import SandboxType
-from ...box.base import BaseSandbox
-from ...box.gui import GUIMixin
+from ...box.base import BaseSandbox, BaseSandboxAsync
+from ...box.gui import GUIMixin, AsyncGUIMixin
 from ...constant import TIMEOUT
 
 
@@ -299,3 +299,199 @@ class BrowserSandbox(GUIMixin, BaseSandbox):
                 "textGone": text_gone,
             },
         )
+
+
+@SandboxRegistry.register(
+    build_image_uri("runtime-sandbox-browser"),
+    sandbox_type=SandboxType.BROWSER_ASYNC,
+    security_level="medium",
+    timeout=TIMEOUT,
+    description="Browser sandbox (Async)",
+)
+class BrowserSandboxAsync(GUIMixin, AsyncGUIMixin, BaseSandboxAsync):
+    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.BROWSER_ASYNC,
+    ):
+        super().__init__(
+            sandbox_id,
+            timeout,
+            base_url,
+            bearer_token,
+            sandbox_type,
+        )
+
+    async def browser_close(self):
+        """Close the current browser page."""
+        return await self.call_tool_async("browser_close", {})
+
+    async def browser_resize(self, width: int, height: int):
+        """Resize the browser window."""
+        return await self.call_tool_async(
+            "browser_resize",
+            {"width": width, "height": height},
+        )
+
+    async def browser_console_messages(self):
+        """Return all console messages from the browser."""
+        return await self.call_tool_async("browser_console_messages", {})
+
+    async def browser_handle_dialog(self, accept: bool, prompt_text: str = ""):
+        """Handle a dialog popup."""
+        return await self.call_tool_async(
+            "browser_handle_dialog",
+            {"accept": accept, "promptText": prompt_text},
+        )
+
+    async def browser_file_upload(self, paths: list):
+        """Upload one or multiple files."""
+        return await self.call_tool_async(
+            "browser_file_upload",
+            {"paths": paths},
+        )
+
+    async def browser_press_key(self, key: str):
+        """Press a key in the browser."""
+        return await self.call_tool_async("browser_press_key", {"key": key})
+
+    async def browser_navigate(self, url: str):
+        """Navigate to a URL."""
+        return await self.call_tool_async("browser_navigate", {"url": url})
+
+    async def browser_navigate_back(self):
+        """Go back in browser history."""
+        return await self.call_tool_async("browser_navigate_back", {})
+
+    async def browser_navigate_forward(self):
+        """Go forward in browser history."""
+        return await self.call_tool_async("browser_navigate_forward", {})
+
+    async def browser_network_requests(self):
+        """Return network requests."""
+        return await self.call_tool_async("browser_network_requests", {})
+
+    async def browser_pdf_save(self, filename: str = ""):
+        """Save page as a PDF."""
+        return await self.call_tool_async(
+            "browser_pdf_save",
+            {"filename": filename},
+        )
+
+    async def browser_take_screenshot(
+        self,
+        raw=False,
+        filename="",
+        element="",
+        ref="",
+    ):
+        """Take a screenshot."""
+        return await self.call_tool_async(
+            "browser_take_screenshot",
+            {"raw": raw, "filename": filename, "element": element, "ref": ref},
+        )
+
+    async def browser_snapshot(self):
+        """Accessibility snapshot."""
+        return await self.call_tool_async("browser_snapshot", {})
+
+    async def browser_click(self, element: str, ref: str):
+        """Click an element."""
+        return await self.call_tool_async(
+            "browser_click",
+            {"element": element, "ref": ref},
+        )
+
+    async def browser_drag(
+        self,
+        start_element: str,
+        start_ref: str,
+        end_element: str,
+        end_ref: str,
+    ):
+        """Drag and drop."""
+        return await self.call_tool_async(
+            "browser_drag",
+            {
+                "startElement": start_element,
+                "startRef": start_ref,
+                "endElement": end_element,
+                "endRef": end_ref,
+            },
+        )
+
+    async def browser_hover(self, element: str, ref: str):
+        """Hover over an element."""
+        return await self.call_tool_async(
+            "browser_hover",
+            {"element": element, "ref": ref},
+        )
+
+    async def browser_type(
+        self,
+        element: str,
+        ref: str,
+        text: str,
+        submit=False,
+        slowly=False,
+    ):
+        """Type text into an element."""
+        return await self.call_tool_async(
+            "browser_type",
+            {
+                "element": element,
+                "ref": ref,
+                "text": text,
+                "submit": submit,
+                "slowly": slowly,
+            },
+        )
+
+    async def browser_select_option(
+        self,
+        element: str,
+        ref: str,
+        values: list,
+    ):
+        """Select options in a dropdown."""
+        return await self.call_tool_async(
+            "browser_select_option",
+            {"element": element, "ref": ref, "values": values},
+        )
+
+    async def browser_tab_list(self):
+        """List all tabs."""
+        return await self.call_tool_async("browser_tab_list", {})
+
+    async def browser_tab_new(self, url: str = ""):
+        """Open a new tab."""
+        return await self.call_tool_async("browser_tab_new", {"url": url})
+
+    async def browser_tab_select(self, index: int):
+        """Select tab by index."""
+        return await self.call_tool_async(
+            "browser_tab_select",
+            {"index": index},
+        )
+
+    async def browser_tab_close(self, index: int = None):
+        """Close a tab."""
+        return await self.call_tool_async(
+            "browser_tab_close",
+            {"index": index},
+        )
+
+    async def browser_wait_for(
+        self,
+        time: float = None,
+        text: str = None,
+        text_gone: str = None,
+    ):
+        """Wait for text or time."""
+        return await self.call_tool_async(
+            "browser_wait_for",
+            {"time": time, "text": text, "textGone": text_gone},
+        )

agentscope_runtime/sandbox/box/filesystem/__init__.py

@@ -1,4 +1,4 @@
 # -*- coding: utf-8 -*-
-from .filesystem_sandbox import FilesystemSandbox
+from .filesystem_sandbox import FilesystemSandbox, FilesystemSandboxAsync
 
-__all__ = ["FilesystemSandbox"]
+__all__ = ["FilesystemSandbox", "FilesystemSandboxAsync"]

agentscope_runtime/sandbox/box/filesystem/filesystem_sandbox.py

@@ -5,8 +5,8 @@ from typing import Optional
 from ...utils import build_image_uri
 from ...registry import SandboxRegistry
 from ...enums import SandboxType
-from ...box.base import BaseSandbox
-from ...box.gui import GUIMixin
+from ...box.base import BaseSandbox, BaseSandboxAsync
+from ...box.gui import GUIMixin, AsyncGUIMixin
 from ...constant import TIMEOUT
 
 
@@ -154,3 +154,100 @@ class FilesystemSandbox(GUIMixin, BaseSandbox):
         Returns the list of directories that this serveris allowed to access.
         """
         return self.call_tool("list_allowed_directories", {})
+
+
+@SandboxRegistry.register(
+    build_image_uri("runtime-sandbox-filesystem"),
+    sandbox_type=SandboxType.FILESYSTEM_ASYNC,
+    security_level="medium",
+    timeout=TIMEOUT,
+    description="Filesystem sandbox (Async)",
+)
+class FilesystemSandboxAsync(GUIMixin, AsyncGUIMixin, BaseSandboxAsync):
+    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.FILESYSTEM_ASYNC,
+    ):
+        super().__init__(
+            sandbox_id,
+            timeout,
+            base_url,
+            bearer_token,
+            sandbox_type,
+        )
+
+    async def read_file(self, path: str):
+        """Read the complete contents of a file."""
+        return await self.call_tool_async("read_file", {"path": path})
+
+    async def read_multiple_files(self, paths: list):
+        """Read the contents of multiple files simultaneously."""
+        return await self.call_tool_async(
+            "read_multiple_files",
+            {"paths": paths},
+        )
+
+    async def write_file(self, path: str, content: str):
+        """Create or overwrite a file with new content."""
+        return await self.call_tool_async(
+            "write_file",
+            {"path": path, "content": content},
+        )
+
+    async def edit_file(self, path: str, edits: list, dry_run: bool = False):
+        """Make line-based edits to a text file."""
+        return await self.call_tool_async(
+            "edit_file",
+            {
+                "path": path,
+                "edits": edits,
+                "dryRun": dry_run,
+            },
+        )
+
+    async def create_directory(self, path: str):
+        """Create a new directory or ensure it exists."""
+        return await self.call_tool_async("create_directory", {"path": path})
+
+    async def list_directory(self, path: str):
+        """Get a detailed listing of all files and directories."""
+        return await self.call_tool_async("list_directory", {"path": path})
+
+    async def directory_tree(self, path: str):
+        """Get a recursive tree view of files and directories as JSON."""
+        return await self.call_tool_async("directory_tree", {"path": path})
+
+    async def move_file(self, source: str, destination: str):
+        """Move or rename files and directories."""
+        return await self.call_tool_async(
+            "move_file",
+            {"source": source, "destination": destination},
+        )
+
+    async def search_files(
+        self,
+        path: str,
+        pattern: str,
+        exclude_patterns: list = [],
+    ):
+        """Recursively search for files and directories matching a pattern."""
+        return await self.call_tool_async(
+            "search_files",
+            {
+                "path": path,
+                "pattern": pattern,
+                "excludePatterns": exclude_patterns,
+            },
+        )
+
+    async def get_file_info(self, path: str):
+        """Retrieve metadata about a file or directory."""
+        return await self.call_tool_async("get_file_info", {"path": path})
+
+    async def list_allowed_directories(self):
+        """Returns directories this server can access."""
+        return await self.call_tool_async("list_allowed_directories", {})

agentscope_runtime/sandbox/box/gui/__init__.py

@@ -1,4 +1,4 @@
 # -*- coding: utf-8 -*-
-from .gui_sandbox import GuiSandbox, GUIMixin
+from .gui_sandbox import GuiSandbox, GuiSandboxAsync, GUIMixin, AsyncGUIMixin
 
-__all__ = ["GuiSandbox", "GUIMixin"]
+__all__ = ["GuiSandbox", "GuiSandboxAsync", "GUIMixin", "AsyncGUIMixin"]

agentscope_runtime/sandbox/box/gui/gui_sandbox.py

@@ -8,7 +8,7 @@ from urllib.parse import urljoin, urlencode
 from ...utils import build_image_uri, get_platform
 from ...registry import SandboxRegistry
 from ...enums import SandboxType
-from ...box.base import BaseSandbox
+from ...box.base import BaseSandbox, BaseSandboxAsync
 from ...constant import TIMEOUT
 
 logger = logging.getLogger(__name__)
@@ -34,6 +34,34 @@ class GUIMixin:
         )
 
 
+class AsyncGUIMixin:
+    async def get_desktop_url_async(self):
+        # Check sandbox 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")
+
+        # Retrieve container information asynchronously
+        info = await self.get_info_async()
+
+        # Default local VNC path and remote VNC relay path
+        path = "/vnc/vnc_lite.html"
+        remote_path = "/vnc/vnc_relay.html"
+        params = {"password": info["runtime_token"]}
+
+        # If base_url is not set, construct the local URL
+        if self.base_url is None:
+            return urljoin(info["url"], path) + "?" + urlencode(params)
+
+        # Construct the remote URL with sandbox ID and VNC relay path
+        return (
+            f"{self.base_url}/desktop/{self.sandbox_id}{remote_path}"
+            f"?{urlencode(params)}"
+        )
+
+
 @SandboxRegistry.register(
     build_image_uri("runtime-sandbox-gui"),
     sandbox_type=SandboxType.GUI,
@@ -121,3 +149,91 @@ class GuiSandbox(GUIMixin, BaseSandbox):
             payload["text"] = text
 
         return self.call_tool("computer", payload)
+
+
+@SandboxRegistry.register(
+    build_image_uri("runtime-sandbox-gui"),
+    sandbox_type=SandboxType.GUI_ASYNC,
+    security_level="high",
+    timeout=TIMEOUT,
+    description="GUI Sandbox (Async)",
+)
+class GuiSandboxAsync(GUIMixin, AsyncGUIMixin, BaseSandboxAsync):
+    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.GUI_ASYNC,
+    ):
+        super().__init__(
+            sandbox_id,
+            timeout,
+            base_url,
+            bearer_token,
+            sandbox_type,
+        )
+        # Architecture compatibility warning
+        if get_platform() == "linux/arm64":
+            logger.warning(
+                "\nCompatibility Notice: This GUI Sandbox may have issues on "
+                "arm64 CPU architectures, due to the computer-use-mcp not "
+                "providing linux/arm64 compatibility. It has been tested "
+                "on Apple M4 chips with Rosetta enabled. However, on M1, M2, "
+                "and M3 chips, Chromium browser might crash due to the missing "
+                "SSE3 instruction set.",
+            )
+
+    async def computer_use(
+        self,
+        action: str,
+        coordinate: Optional[Union[List[float], Tuple[float, float]]] = None,
+        text: Optional[str] = None,
+    ):
+        """
+        Asynchronously use mouse and keyboard to interact with a desktop GUI.
+
+        This method interfaces with the sandbox's GUI environment.
+        You do not have access to a terminal or applications menu;
+        interaction is performed by clicking on desktop icons or using
+        keyboard shortcuts.
+
+        Guidelines:
+            * Prefer keyboard shortcuts where possible over cursor actions.
+            * If visual keyboard hints (two-letter boxes) are shown, typing
+              those letters will click the element — use this where possible.
+            * Applications or actions may require waiting; e.g., repeat
+              screenshots if windows don’t open immediately.
+            * Always determine cursor coordinates using screenshots before moving
+              the cursor to click on elements.
+            * If clicks fail to load content, try adjusting cursor coordinates to
+              center on the target element.
+            * Click with the cursor tip centered on elements, not on edges.
+
+        Args:
+            action (str): The action to perform. Options include:
+                * `key` — Press a key or key combination.
+                * `type` — Type a string of text.
+                * `get_cursor_position` — Get current cursor coordinates (x, y).
+                * `mouse_move` — Move cursor to given (x, y).
+                * `left_click` — Left mouse click.
+                * `left_click_drag` — Click and drag to given (x, y).
+                * `right_click` — Right mouse click.
+                * `middle_click` — Middle mouse click.
+                * `double_click` — Double left mouse click.
+                * `get_screenshot` — Capture screen screenshot.
+            coordinate (list[float] | tuple[float, float], optional):
+                Pixel coordinates (x from left edge, y from top edge).
+            text (str, optional): String to type, or key-combination for `key` action.
+
+        Returns:
+            Any: Tool execution result from the sandbox.
+        """
+        payload = {"action": action}
+        if coordinate is not None:
+            payload["coordinate"] = coordinate
+        if text is not None:
+            payload["text"] = text
+
+        return await self.call_tool_async("computer", payload)

agentscope_runtime/sandbox/box/mobile/__init__.py

@@ -1,4 +1,4 @@
 # -*- coding: utf-8 -*-
-from .mobile_sandbox import MobileSandbox
+from .mobile_sandbox import MobileSandbox, MobileSandboxAsync
 
-__all__ = ["MobileSandbox"]
+__all__ = ["MobileSandbox", "MobileSandboxAsync"]