agentscope-runtime 1.0.4a1__py3-none-any.whl → 1.0.5.post1__py3-none-any.whl

agentscope_runtime/sandbox/box/sandbox.py

@@ -6,77 +6,56 @@ from typing import Any, Optional
 
 from ..enums import SandboxType
 from ..manager.sandbox_manager import SandboxManager
+from ..manager.server.app import get_config
 
 
 logging.basicConfig(level=logging.INFO)
 logger = logging.getLogger(__name__)
 
 
-class Sandbox:
+class SandboxBase:
     """
-    Sandbox Interface.
+    Common base class for both sync and async Sandbox interfaces.
     """
 
     def __init__(
         self,
         sandbox_id: Optional[str] = None,
-        timeout: int = 3000,  # TODO: enable life circle management
+        timeout: int = 3000,
         base_url: Optional[str] = None,
-        bearer_token: Optional[str] = None,  # TODO: support api_key
+        bearer_token: Optional[str] = None,
         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
+            # Remote Manager
             self.manager_api = SandboxManager(
                 base_url=base_url,
                 bearer_token=bearer_token,
-            ).__enter__()
+            )
         else:
-            # Launch a local manager
-            self.embed_mode = True
+            # Embedded Manager
             self.manager_api = SandboxManager(
+                config=get_config(),
                 default_type=sandbox_type,
             )
 
-        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 = 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()
+    @property
+    def sandbox_id(self) -> Optional[str]:
+        return self._sandbox_id
 
-    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.
-        """
+    @sandbox_id.setter
+    def sandbox_id(self, value: str) -> None:
+        if not value:
+            raise ValueError("Sandbox ID cannot be empty.")
+        self._sandbox_id = value
 
+    def _register_signal_handlers(self):
         def _handler(signum, frame):  # pylint: disable=unused-argument
             logger.debug(
                 f"Received signal {signum}, stopping Sandbox"
@@ -85,7 +64,6 @@ class Sandbox:
             self._cleanup()
             raise SystemExit(0)
 
-        # Windows does not support SIGTERM
         if hasattr(signal, "SIGTERM"):
             signals = [signal.SIGINT, signal.SIGTERM]
         else:
@@ -107,39 +85,36 @@ class Sandbox:
         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}\n"
-                f"{traceback.format_exc()}",
+                f"Cleanup {self.sandbox_id} error: {e}"
+                f"\n{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)
 
@@ -156,15 +131,77 @@ class Sandbox:
     ) -> Any:
         if arguments is None:
             arguments = {}
-
         return self.manager_api.call_tool(self.sandbox_id, name, arguments)
 
-    def add_mcp_servers(
+    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,
+        )
+
+    async def add_mcp_servers_async(
         self,
         server_configs: dict,
         overwrite=False,
     ):
-        return self.manager_api.add_mcp_servers(
+        return await self.manager_api.add_mcp_servers_async(
             self.sandbox_id,
             server_configs,
             overwrite,

agentscope_runtime/sandbox/box/shared/routers/generic.py

@@ -2,7 +2,7 @@
 import io
 import sys
 import logging
-import subprocess
+import asyncio
 import traceback
 from contextlib import redirect_stderr, redirect_stdout
 
@@ -44,26 +44,33 @@ async def run_ipython_cell(
         stdout_buf = io.StringIO()
         stderr_buf = io.StringIO()
 
-        with redirect_stdout(stdout_buf), redirect_stderr(stderr_buf):
-            preprocessing_exc_tuple = None
-            try:
-                transformed_cell = ipy.transform_cell(code)
-            except Exception:
-                transformed_cell = code
-                preprocessing_exc_tuple = sys.exc_info()
-
-            if transformed_cell is None:
-                raise HTTPException(
-                    status_code=500,
-                    detail="IPython cell transformation failed: "
-                    "transformed_cell is None.",
+        def thread_target():
+            with redirect_stdout(stdout_buf), redirect_stderr(stderr_buf):
+                preprocessing_exc_tuple = None
+                try:
+                    transformed_cell = ipy.transform_cell(code)
+                except Exception:
+                    transformed_cell = code
+                    preprocessing_exc_tuple = sys.exc_info()
+
+                if transformed_cell is None:
+                    raise HTTPException(
+                        status_code=500,
+                        detail=(
+                            "IPython cell transformation failed: "
+                            "transformed_cell is None."
+                        ),
+                    )
+
+                asyncio.run(
+                    ipy.run_cell_async(
+                        code,
+                        transformed_cell=transformed_cell,
+                        preprocessing_exc_tuple=preprocessing_exc_tuple,
+                    ),
                 )
 
-            await ipy.run_cell_async(
-                code,
-                transformed_cell=transformed_cell,
-                preprocessing_exc_tuple=preprocessing_exc_tuple,
-            )
+        await asyncio.to_thread(thread_target)
 
         stdout_content = stdout_buf.getvalue()
         stderr_content = stderr_buf.getvalue()
@@ -128,16 +135,16 @@ async def run_shell_command(
         if not command:
             raise HTTPException(status_code=400, detail="Command is required.")
 
-        result = subprocess.run(
+        proc = await asyncio.create_subprocess_shell(
             command,
-            shell=True,
-            stdout=subprocess.PIPE,
-            stderr=subprocess.PIPE,
-            text=True,
-            check=False,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
         )
-        stdout_content = result.stdout
-        stderr_content = result.stderr
+
+        stdout_bytes, stderr_bytes = await proc.communicate()
+
+        stdout_content = stdout_bytes.decode()
+        stderr_content = stderr_bytes.decode()
 
         content_list = []
 
@@ -161,7 +168,7 @@ async def run_shell_command(
             content_list.append(
                 TextContent(
                     type="text",
-                    text=str(result.returncode),
+                    text=str(proc.returncode),
                     description="returncode",
                 ),
             )
@@ -173,7 +180,7 @@ async def run_shell_command(
                     + "\n"
                     + stderr_content
                     + "\n"
-                    + str(result.returncode),
+                    + str(proc.returncode),
                     description="output",
                 ),
             )

agentscope_runtime/sandbox/client/__init__.py

@@ -1,5 +1,10 @@
 # -*- coding: utf-8 -*-
 from .http_client import SandboxHttpClient
 from .training_client import TrainingSandboxClient
+from .async_http_client import SandboxHttpAsyncClient
 
-__all__ = ["SandboxHttpClient", "TrainingSandboxClient"]
+__all__ = [
+    "SandboxHttpClient",
+    "SandboxHttpAsyncClient",
+    "TrainingSandboxClient",
+]

agentscope_runtime/sandbox/client/async_http_client.py

@@ -0,0 +1,339 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=unused-argument
+import logging
+import asyncio
+from typing import Any, Optional
+
+import httpx
+from pydantic import Field
+
+from .base import SandboxHttpBase
+from ..model import ContainerModel
+
+logger = logging.getLogger(__name__)
+
+
+class SandboxHttpAsyncClient(SandboxHttpBase):
+    """
+    A Python async client for interacting with the runtime API.
+    Connect directly to the container.
+    """
+
+    def __init__(
+        self,
+        model: Optional[ContainerModel] = None,
+        timeout: int = 60,
+        domain: str = "localhost",
+    ) -> None:
+        """
+        Initialize the Python async client.
+
+        Args:
+            model (ContainerModel): The pydantic model representing the
+            runtime sandbox.
+        """
+        super().__init__(model, timeout, domain)
+        self.client = httpx.AsyncClient(
+            timeout=self.timeout,
+            headers=self.headers,
+        )
+
+    async def __aenter__(self):
+        # Wait for the runtime api server to be healthy
+        await self.wait_until_healthy()
+        return self
+
+    async def __aexit__(self, exc_type, exc_value, traceback):
+        await self.client.aclose()
+
+    async def _request(self, method: str, url: str, **kwargs):
+        return await self.client.request(method, url, **kwargs)
+
+    async def safe_request(self, method: str, url: str, **kwargs):
+        """
+        Unified HTTP request method with async exception handling.
+        Returns JSON if possible, otherwise plain text.
+        """
+        try:
+            r = await self._request(method, url, **kwargs)
+            r.raise_for_status()
+            try:
+                return r.json()
+            except ValueError:
+                return r.text
+        except httpx.RequestError as e:
+            logger.error(f"HTTP error: {e}")
+            return {
+                "isError": True,
+                "content": [{"type": "text", "text": str(e)}],
+            }
+
+    async def check_health(self) -> bool:
+        """
+        Check if the runtime service is running by verifying the health
+        endpoint.
+
+        Returns:
+            bool: True if the service is reachable, False otherwise.
+        """
+        try:
+            r = await self._request(
+                "get",
+                f"{self.base_url}/healthz",
+            )
+            return r.status_code == 200
+        except httpx.RequestError:
+            return False
+
+    async def wait_until_healthy(self) -> None:
+        """
+        Wait until the runtime service is running for a specified timeout.
+        """
+        start_time = asyncio.get_event_loop().time()
+        while (
+            asyncio.get_event_loop().time() - start_time < self.start_timeout
+        ):
+            if await self.check_health():
+                return
+            await asyncio.sleep(1)
+        raise TimeoutError(
+            "Runtime service did not start within the specified timeout.",
+        )
+
+    async def add_mcp_servers(self, server_configs, overwrite=False):
+        """
+        Add MCP servers to runtime.
+        """
+        endpoint = f"{self.base_url}/mcp/add_servers"
+        return await self.safe_request(
+            "post",
+            endpoint,
+            json={"server_configs": server_configs, "overwrite": overwrite},
+        )
+
+    async def list_tools(self, tool_type=None, **kwargs) -> dict:
+        """
+        List available MCP tools plus generic built-in tools.
+        """
+        data = await self.safe_request(
+            "get",
+            f"{self.base_url}/mcp/list_tools",
+        )
+        if isinstance(data, dict) and "isError" not in data:
+            data["generic"] = self.generic_tools
+            if tool_type:
+                return {tool_type: data.get(tool_type, {})}
+        return data
+
+    async def call_tool(
+        self,
+        name: str,
+        arguments: Optional[dict[str, Any]] = None,
+    ) -> dict:
+        """
+        Call a specific MCP tool.
+
+        If it's a generic tool, call the corresponding local method.
+        """
+        if arguments is None:
+            arguments = {}
+        if name in self.generic_tools:
+            if name == "run_ipython_cell":
+                return await self.run_ipython_cell(**arguments)
+            elif name == "run_shell_command":
+                return await self.run_shell_command(**arguments)
+
+        return await self.safe_request(
+            "post",
+            f"{self.base_url}/mcp/call_tool",
+            json={"tool_name": name, "arguments": arguments},
+        )
+
+    async def run_ipython_cell(
+        self,
+        code: str = Field(description="IPython code to execute"),
+    ) -> dict:
+        """
+        Run an IPython cell.
+        """
+        return await self.safe_request(
+            "post",
+            f"{self.base_url}/tools/run_ipython_cell",
+            json={"code": code},
+        )
+
+    async def run_shell_command(
+        self,
+        command: str = Field(description="Shell command to execute"),
+    ) -> dict:
+        """
+        Run a shell command.
+        """
+        return await self.safe_request(
+            "post",
+            f"{self.base_url}/tools/run_shell_command",
+            json={"command": command},
+        )
+
+    async def commit_changes(
+        self,
+        commit_message: str = "Automated commit",
+    ) -> dict:
+        """
+        Commit the uncommitted changes with a given commit message.
+        """
+        return await self.safe_request(
+            "post",
+            f"{self.base_url}/watcher/commit_changes",
+            json={"commit_message": commit_message},
+        )
+
+    async def generate_diff(
+        self,
+        commit_a: Optional[str] = None,
+        commit_b: Optional[str] = None,
+    ) -> dict:
+        """
+        Generate the diff between two commits or between uncommitted changes
+        and the latest commit.
+        """
+        return await self.safe_request(
+            "post",
+            f"{self.base_url}/watcher/generate_diff",
+            json={"commit_a": commit_a, "commit_b": commit_b},
+        )
+
+    async def git_logs(self) -> dict:
+        """
+        Retrieve the git logs.
+        """
+        return await self.safe_request(
+            "get",
+            f"{self.base_url}/watcher/git_logs",
+        )
+
+    # -------- Workspace File APIs --------
+
+    async def get_workspace_file(self, file_path: str) -> dict:
+        """
+        Retrieve a file from the /workspace directory.
+        """
+        try:
+            endpoint = f"{self.base_url}/workspace/files"
+            params = {"file_path": file_path}
+            r = await self._request("get", endpoint, params=params)
+            r.raise_for_status()
+
+            # Check for empty content
+            if r.headers.get("Content-Length") == "0":
+                logger.warning(f"The file {file_path} is empty.")
+                return {"data": b""}
+
+            # Accumulate the content in chunks
+            file_content = bytearray()
+            async for chunk in r.aiter_bytes():
+                file_content.extend(chunk)
+
+            return {"data": bytes(file_content)}
+        except httpx.RequestError as e:
+            logger.error(f"An error occurred while retrieving the file: {e}")
+            return {
+                "isError": True,
+                "content": [{"type": "text", "text": str(e)}],
+            }
+
+    async def create_or_edit_workspace_file(
+        self,
+        file_path: str,
+        content: str,
+    ) -> dict:
+        """
+        Create or edit a file within the /workspace directory.
+        """
+        return await self.safe_request(
+            "post",
+            f"{self.base_url}/workspace/files",
+            params={"file_path": file_path},
+            json={"content": content},
+        )
+
+    async def list_workspace_directories(
+        self,
+        directory: str = "/workspace",
+    ) -> dict:
+        """
+        List files in the specified directory within the /workspace.
+        """
+        return await self.safe_request(
+            "get",
+            f"{self.base_url}/workspace/list-directories",
+            params={"directory": directory},
+        )
+
+    async def create_workspace_directory(self, directory_path: str) -> dict:
+        """
+        Create a directory within the /workspace directory.
+        """
+        return await self.safe_request(
+            "post",
+            f"{self.base_url}/workspace/directories",
+            params={"directory_path": directory_path},
+        )
+
+    async def delete_workspace_file(self, file_path: str) -> dict:
+        """
+        Delete a file within the /workspace directory.
+        """
+        return await self.safe_request(
+            "delete",
+            f"{self.base_url}/workspace/files",
+            params={"file_path": file_path},
+        )
+
+    async def delete_workspace_directory(
+        self,
+        directory_path: str,
+        recursive: bool = False,
+    ) -> dict:
+        """
+        Delete a directory within the /workspace directory.
+        """
+        return await self.safe_request(
+            "delete",
+            f"{self.base_url}/workspace/directories",
+            params={"directory_path": directory_path, "recursive": recursive},
+        )
+
+    async def move_or_rename_workspace_item(
+        self,
+        source_path: str,
+        destination_path: str,
+    ) -> dict:
+        """
+        Move or rename a file or directory within the /workspace directory.
+        """
+        return await self.safe_request(
+            "put",
+            f"{self.base_url}/workspace/move",
+            params={
+                "source_path": source_path,
+                "destination_path": destination_path,
+            },
+        )
+
+    async def copy_workspace_item(
+        self,
+        source_path: str,
+        destination_path: str,
+    ) -> dict:
+        """
+        Copy a file or directory within the /workspace directory.
+        """
+        return await self.safe_request(
+            "post",
+            f"{self.base_url}/workspace/copy",
+            params={
+                "source_path": source_path,
+                "destination_path": destination_path,
+            },
+        )