Build and run agents you can see, understand and trust.
Python agentchatbotlarge-language-modelsllmllm-agentmcpmulti-agentmulti-modalreact-agentrealtime-agentvoice-agentvoice-assistant
feat(workspace): support builtin tools for the e2b and docker workspaces (#1903)
DavdGaobd28474b8238
diff --git a/.github/workflows/github-monitor.yml b/.github/workflows/github-monitor.ymlindex 481f6108d..777c721f7 100644--- a/.github/workflows/github-monitor.yml+++ b/.github/workflows/github-monitor.yml@@ -15,7 +15,7 @@ on:types: [opened, closed, reopened]issue_comment:types: [created]- pull_request:+ pull_request_target:# synchronize is silent (stored only) — see SILENT_REALTIME_EVENTS in scripts/config.py.# It's needed for the daily "PRs with new commits to re-review" section.types: [opened, closed, reopened, synchronize, review_requested]diff --git a/src/agentscope/tool/__init__.py b/src/agentscope/tool/__init__.pyindex 1ca29b31c..f58f5f3c8 100644--- a/src/agentscope/tool/__init__.py+++ b/src/agentscope/tool/__init__.py@@ -14,6 +14,9 @@ from ._builtin import (Grep,Read,Write,+ BackendBase,+ ExecResult,+ LocalBackend,)from ._task import (TaskUpdate,@@ -38,6 +41,9 @@ __all__ = ["ToolResponse","RegisteredTool",# Builtin tools+ "BackendBase",+ "LocalBackend",+ "ExecResult","ResetTools","Bash","Edit",diff --git a/src/agentscope/tool/_builtin/__init__.py b/src/agentscope/tool/_builtin/__init__.pyindex 48215f950..5e63a9561 100644--- a/src/agentscope/tool/_builtin/__init__.py+++ b/src/agentscope/tool/_builtin/__init__.py@@ -1,16 +1,16 @@# -*- coding: utf-8 -*-"""The builtin tools in agentscope."""-from ._meta import ResetTools-from ._skill import SkillViewer+from ._backend import BackendBase, ExecResult, LocalBackendfrom ._bash import Bashfrom ._edit import Editfrom ._glob import Globfrom ._grep import Grep+from ._meta import ResetToolsfrom ._read import Read+from ._skill import SkillViewerfrom ._write import Write-__all__ = ["ResetTools","SkillViewer",@@ -20,4 +20,7 @@ __all__ = ["Grep","Read","Write",+ "BackendBase",+ "LocalBackend",+ "ExecResult",]diff --git a/src/agentscope/tool/_builtin/_backend.py b/src/agentscope/tool/_builtin/_backend.pynew file mode 100644index 000000000..f291b85c5--- /dev/null+++ b/src/agentscope/tool/_builtin/_backend.py@@ -0,0 +1,526 @@+# -*- coding: utf-8 -*-+"""Backend abstraction for builtin tools.++Provides a :class:`BackendBase` abstract base class that captures the+core I/O primitives shared across all six builtin tools (Bash, Read,+Write, Edit, Grep, Glob).++Every backend implements exactly **three** abstract primitives whose+mechanism genuinely differs per environment:++* :meth:`BackendBase.exec_shell` — run a program from an argv list+ (no shell; callers needing shell features wrap with ``sh -c``).+* :meth:`BackendBase.read_file` — read raw bytes.+* :meth:`BackendBase.write_file` — write raw bytes.++All remaining filesystem operations (``file_exists``, ``is_dir``,+``list_dir``, ``stat_mtime``, ``delete_path``) are derived on the base+class from ``exec_shell`` and work out-of-the-box for any remote+backend. A backend that has a cheaper native path (e.g.+:class:`LocalBackend` using ``os.*``) simply overrides them.++Concrete implementations:++* :class:`LocalBackend` — default; uses ``asyncio`` subprocesses,+ ``aiofiles``, and ``os.*`` for host-local I/O. Injected automatically+ when no explicit backend is given.+* ``DockerBackend`` — uses ``aiodocker`` exec / archive APIs.+* ``E2BBackend`` — uses the E2B SDK ``commands`` / ``files`` APIs.++By accepting a ``BackendBase`` parameter, each builtin tool can+operate identically in local, Docker, and E2B workspaces without any+workspace-specific branching inside the tool code itself.+"""++from __future__ import annotations++import asyncio+import os+import shlex+import shutil+from abc import ABC, abstractmethod+from dataclasses import dataclass+from typing import Any++import aiofiles++# ── data class ─────────────────────────────────────────────────────────+++@dataclass(frozen=True, slots=True)+class ExecResult:+ """Result of running a shell command via a backend.++ Attributes:+ exit_code: Process exit code. ``-1`` conventionally indicates+ an internal failure (timeout, connection error, …).+ stdout: Raw bytes captured from standard output.+ stderr: Raw bytes captured from standard error.+ """++ exit_code: int+ stdout: bytes+ stderr: bytes++ def ok(self) -> bool:+ """Whether the command exited successfully.++ Returns:+ `bool`:+ ``True`` iff the command exited with code ``0``.+ """+ return self.exit_code == 0+++# ── helpers ────────────────────────────────────────────────────────────+++def _normalize_newlines(text: str) -> str:+ """Normalize Windows/old-Mac line endings to ``\\n``.++ Converts ``\\r\\n`` (Windows) and lone ``\\r`` (classic Mac) to a+ single ``\\n``. Builtin tools read files as raw bytes (so binary+ payloads survive intact); when the bytes are decoded as text for+ line-based caching, editing, or matching, the line endings must be+ normalized so that content written on Windows behaves identically to+ content written on POSIX.++ Args:+ text (`str`):+ Decoded file contents.++ Returns:+ `str`:+ The text with all line endings collapsed to ``\\n``.+ """+ return text.replace("\r\n", "\n").replace("\r", "\n")+++# ── base class ─────────────────────────────────────────────────────────+++class BackendBase(ABC):+ """Filesystem + subprocess interface consumed by builtin tools.++ Subclasses must implement three abstract primitives — ``exec_shell``,+ ``read_file``, and ``write_file`` — which are the only operations+ whose mechanism genuinely differs per environment. The remaining+ filesystem helpers are implemented here on top of ``exec_shell`` and+ work for any backend whose shell is POSIX-like; a backend with a+ cheaper native path may override them (see :class:`LocalBackend`).+ """++ # ── abstract primitives ────────────────────────────────────────++ @abstractmethod+ async def exec_shell(+ self,+ command: list[str],+ *,+ cwd: str | None = None,+ timeout: float | None = None,+ ) -> ExecResult:+ """Run a program directly from an argument vector.++ *command* is an executable followed by its arguments — it is+ **not** passed through a shell, so callers never have to quote+ or escape arguments and there is no platform-specific quoting+ bug. This makes the primitive portable to Windows, where POSIX+ single-quote escaping (``shlex.quote``) is not understood by+ ``cmd.exe``.++ Callers that genuinely need shell features (pipes, redirects,+ ``&&``) must wrap their command line explicitly, e.g.+ ``["/bin/sh", "-c", command_line]``.++ Args:+ command (`list[str]`):+ Executable path/name followed by its arguments.+ cwd (`str | None`, optional):+ Working directory to run the command in. When ``None``+ the backend's default working directory is used.+ timeout (`float | None`, optional):+ Maximum number of seconds to wait. When ``None`` the+ call waits indefinitely. On timeout the result carries+ an ``exit_code`` of ``-1``.++ Returns:+ `ExecResult`:+ The captured exit code, stdout, and stderr.+ """++ @abstractmethod+ async def read_file(self, path: str) -> bytes:+ """Read the full contents of ``path`` as raw bytes.++ Args:+ path (`str`):+ Path to the file inside the backend's environment.++ Returns:+ `bytes`:+ The raw file contents.+ """++ @abstractmethod+ async def write_file(self, path: str, data: bytes) -> None:+ """Write ``data`` to ``path``, creating parent directories.++ Args:+ path (`str`):+ Destination path inside the backend's environment.+ data (`bytes`):+ The raw bytes to write.+ """++ # ── derived filesystem ops (shell-based defaults) ──────────────++ async def file_exists(self, path: str) -> bool:+ """Return ``True`` if ``path`` exists (file or directory).++ Args:+ path (`str`):+ Path to test inside the backend's environment.++ Returns:+ `bool`:+ ``True`` if the path exists, ``False`` otherwise.+ """+ result = await self.exec_shell(["test", "-e", path])+ return result.ok()++ async def is_dir(self, path: str) -> bool:+ """Return ``True`` if ``path`` is an existing directory.++ Args:+ path (`str`):+ Path to test inside the backend's environment.++ Returns:+ `bool`:+ ``True`` if the path is an existing directory.+ """+ result = await self.exec_shell(["test", "-d", path])+ return result.ok()++ async def list_dir(+ self,+ path: str,+ *,+ recursive: bool = False,+ ) -> list[str]:+ """List entries under ``path``.++ Output is NUL-delimited (``find -print0`` / ``-printf '%f\\0'``)+ and split on ``\\0`` so that file names containing spaces or+ newlines are handled correctly. ``find -printf`` is a GNU+ extension; backends running on non-GNU userlands should override+ this method.++ Args:+ path (`str`):+ Directory to list inside the backend's environment.+ recursive (`bool`, optional):+ When ``True``, return all files underneath ``path`` as+ paths (like ``find path -type f``). When ``False``+ (default), return the immediate children's base names+ (like ``os.listdir``).++ Returns:+ `list[str]`:+ The matched entries, or an empty list if ``path`` does+ not exist or cannot be listed.+ """+ if recursive:+ command = ["find", path, "-type", "f", "-print0"]+ else:+ command = [+ "find",+ path,+ "-mindepth",+ "1",+ "-maxdepth",+ "1",+ "-printf",+ "%f\\0",+ ]+ result = await self.exec_shell(command)+ if not result.ok():+ return []+ return [+ part.decode("utf-8", errors="surrogateescape")+ for part in result.stdout.split(b"\0")+ if part+ ]++ async def stat_mtime(self, path: str) -> float | None:+ """Return the modification time of ``path``, or ``None``.++ Tries GNU ``stat -c %Y`` first and falls back to BSD+ ``stat -f %m`` so the same call works across coreutils and+ BSD/macOS userlands. The two attempts are combined with ``||``,+ so this default wraps a ``sh -c`` script; backends without a+ POSIX shell (e.g. :class:`LocalBackend`) override it.++ Args:+ path (`str`):+ Path to stat inside the backend's environment.++ Returns:+ `float | None`:+ The modification time as a POSIX timestamp, or ``None``+ if the path does not exist or cannot be stat'd.+ """+ quoted = shlex.quote(path)+ script = (+ f"stat -c %Y {quoted} 2>/dev/null || "+ f"stat -f %m {quoted} 2>/dev/null"+ )+ result = await self.exec_shell(["sh", "-c", script])+ if not result.ok():+ return None+ try:+ return float(+ result.stdout.decode("utf-8", errors="replace").strip(),+ )+ except ValueError:+ return None++ async def delete_path(self, path: str) -> None:+ """Delete ``path`` (file or directory tree).++ If ``path`` does not exist the call is a silent no-op (like+ ``rm -rf``). Handles both files and directories (recursively).++ Args:+ path (`str`):+ Path to delete inside the backend's environment.+ """+ await self.exec_shell(["rm", "-rf", path])+++# ── local backend ──────────────────────────────────────────────────────+++def _subprocess_creation_kwargs() -> dict[str, Any]:+ """Return platform-specific subprocess creation options.++ Returns:+ `dict[str, Any]`:+ Extra keyword arguments for ``create_subprocess_shell``.+ Empty on POSIX; on Windows it sets ``creationflags`` to+ suppress a console window.+ """+ if os.name != "nt":+ return {}++ import subprocess++ return {+ "creationflags": getattr(+ subprocess,+ "CREATE_NO_WINDOW",+ 0x08000000,+ ),+ }+++class LocalBackend(BackendBase):+ """Host-local :class:`BackendBase` implementation.++ Uses ``asyncio.create_subprocess_exec``, ``aiofiles``, and the+ ``os`` module. This is the default backend injected when no+ explicit one is given to a builtin tool. Commands are spawned+ directly from their argument vector (no shell), which avoids the+ POSIX-vs-``cmd.exe`` quoting mismatch and makes the backend work on+ Windows. The derived filesystem helpers are overridden with native+ ``os.*`` calls — faster and more robust than shelling out, and+ portable to Windows where ``test`` / ``find`` / ``stat`` are+ unavailable.+ """++ async def exec_shell(+ self,+ command: list[str],+ *,+ cwd: str | None = None,+ timeout: float | None = None,+ ) -> ExecResult:+ """Run a program via ``asyncio.create_subprocess_exec``.++ The program is spawned directly from *command* without an+ intervening shell, so no argument quoting is required and the+ same code path works on POSIX and Windows.++ Args:+ command (`list[str]`):+ Executable path/name followed by its arguments.+ cwd (`str | None`, optional):+ Working directory for the subprocess. When ``None`` the+ current process working directory is used.+ timeout (`float | None`, optional):+ Maximum number of seconds to wait before the process is+ killed and an ``exit_code`` of ``-1`` is returned.++ Returns:+ `ExecResult`:+ The captured exit code, stdout, and stderr. If the+ executable cannot be found or spawned, ``exit_code`` is+ ``127`` (matching a shell's "command not found"), with+ the OS error message on stderr.+ """+ kwargs = _subprocess_creation_kwargs()+ if cwd is not None:+ kwargs["cwd"] = cwd++ try:+ process = await asyncio.create_subprocess_exec(+ *command,+ stdout=asyncio.subprocess.PIPE,+ stderr=asyncio.subprocess.PIPE,+ **kwargs,+ )+ except (FileNotFoundError, NotADirectoryError, OSError) as exc:+ # The executable could not be found or spawned. A shell would+ # have returned 127 ("command not found"); mirror that so+ # callers see a normal non-zero ExecResult instead of an+ # exception.+ return ExecResult(+ exit_code=127,+ stdout=b"",+ stderr=str(exc).encode("utf-8"),+ )++ try:+ stdout, stderr = await asyncio.wait_for(+ process.communicate(),+ timeout=timeout,+ )+ except asyncio.TimeoutError:+ process.kill()+ await process.communicate()+ return ExecResult(exit_code=-1, stdout=b"", stderr=b"timed out")++ return ExecResult(+ exit_code=process.returncode or 0,+ stdout=stdout,+ stderr=stderr,+ )++ async def read_file(self, path: str) -> bytes:+ """Read a local file as raw bytes.++ Args:+ path (`str`):+ Path to the local file.++ Returns:+ `bytes`:+ The raw file contents.+ """+ async with aiofiles.open(path, mode="rb") as f:+ return await f.read()++ async def write_file(self, path: str, data: bytes) -> None:+ """Write *data* to a local file, creating parent dirs.++ Args:+ path (`str`):+ Destination path on the local filesystem.+ data (`bytes`):+ The raw bytes to write.+ """+ parent = os.path.dirname(path)+ if parent:+ os.makedirs(parent, exist_ok=True)+ async with aiofiles.open(path, mode="wb") as f:+ await f.write(data)++ async def file_exists(self, path: str) -> bool:+ """Check if a local path exists.++ Args:+ path (`str`):+ Path to test.++ Returns:+ `bool`:+ ``True`` if the path exists.+ """+ return os.path.exists(path)++ async def is_dir(self, path: str) -> bool:+ """Check if a local path is a directory.++ Args:+ path (`str`):+ Path to test.++ Returns:+ `bool`:+ ``True`` if the path is an existing directory.+ """+ return os.path.isdir(path)++ async def list_dir(+ self,+ path: str,+ *,+ recursive: bool = False,+ ) -> list[str]:+ """List local directory entries.++ Mirrors the base contract using native ``os`` calls.++ Args:+ path (`str`):+ Directory to list.+ recursive (`bool`, optional):+ When ``True``, return file paths underneath ``path``+ (``os.walk``). When ``False`` (default), return the+ immediate children's base names (``os.listdir``).++ Returns:+ `list[str]`:+ The matched entries.+ """+ if recursive:+ results: list[str] = []+ for root, _dirs, files in os.walk(path):+ for f in files:+ results.append(os.path.join(root, f))+ return results+ return os.listdir(path)++ async def stat_mtime(self, path: str) -> float | None:+ """Return the modification time of a local file.++ Args:+ path (`str`):+ Path to stat.++ Returns:+ `float | None`:+ The modification time as a POSIX timestamp, or ``None``+ if the path does not exist or cannot be stat'd.+ """+ try:+ return os.stat(path).st_mtime+ except (OSError, FileNotFoundError):+ return None++ async def delete_path(self, path: str) -> None:+ """Delete a local file or directory tree.++ No-op if *path* does not exist.++ Args:+ path (`str`):+ Path to delete.+ """+ if not os.path.exists(path):+ return+ if os.path.isdir(path):+ shutil.rmtree(path)+ else:+ os.remove(path)diff --git a/src/agentscope/tool/_builtin/_bash.py b/src/agentscope/tool/_builtin/_bash.pyindex 96cb7275a..8e04dfed0 100644--- a/src/agentscope/tool/_builtin/_bash.py+++ b/src/agentscope/tool/_builtin/_bash.py@@ -3,7 +3,6 @@import osfrom typing import AsyncGenerator, Any, Listimport re-import asynciofrom ._bash_parser import BashCommandParserfrom .._base import ToolBase, ToolMiddlewareBase@@ -18,24 +17,9 @@ from ...permission import (PermissionMode,PermissionRule,)-from ...message import TextBlock+from ...message import TextBlock, ToolResultStatefrom .._response import ToolChunk---def _subprocess_creation_kwargs() -> dict[str, Any]:- """Return platform-specific subprocess creation options."""- if os.name != "nt":- return {}-- import subprocess-- return {- "creationflags": getattr(- subprocess,- "CREATE_NO_WINDOW",- 0x08000000,- ),- }+from ._backend import BackendBaseclass Bash(ToolBase):@@ -156,6 +140,7 @@ easier to review tool calls and give permission.dangerous_directories: list[str] = DEFAULT_DANGEROUS_DIRECTORIES,cwd: str | os.PathLike[str] | None = None,middlewares: List[ToolMiddlewareBase] | None = None,+ backend: BackendBase | None = None,) -> None:"""Initialize the bash tool.@@ -177,7 +162,11 @@ easier to review tool calls and give permission.The working directory used when executing bash commands.middlewares (`List[ToolMiddlewareBase] | None`, optional):Tool middlewares wrapping the tool execution.+ backend (`BackendBase | None`, optional):+ The sandbox backend to use for shell execution. When+ ``None``, a :class:`LocalBackend` is created."""+ from ._backend import LocalBackendsuper().__init__(middlewares=middlewares)self._bash_parser = BashCommandParser()@@ -185,6 +174,7 @@ easier to review tool calls and give permission.self.dangerous_files = list(dangerous_files)self.dangerous_directories = list(dangerous_directories)self._cwd = os.fspath(cwd) if cwd is not None else None+ self._backend = backend or LocalBackend()async def check_read_only(self,@@ -689,32 +679,44 @@ easier to review tool calls and give permission.timeout_sec = timeout_ms / 1000.0try:- # Create subprocess- subprocess_kwargs = _subprocess_creation_kwargs()- if self._cwd is not None:- subprocess_kwargs["cwd"] = self._cwd- process = await asyncio.create_subprocess_shell(- command,- stdout=asyncio.subprocess.PIPE,- stderr=asyncio.subprocess.PIPE,- **subprocess_kwargs,- )-- # Wait for completion with timeout- stdout_bytes, stderr_bytes = await asyncio.wait_for(- process.communicate(),+ # ``command`` is a full shell command line (it may contain+ # pipes, redirects, ``&&``, …), so wrap it in a shell — the+ # backend primitive runs the argv directly without one. Pick+ # the platform's native shell so the Windows experience that+ # ``main`` had (commands interpreted by ``cmd.exe``) is+ # preserved; POSIX hosts use ``/bin/sh``.+ if os.name == "nt":+ shell_command = ["cmd", "/c", command]+ else:+ shell_command = ["/bin/sh", "-c", command]+ result = await self._backend.exec_shell(+ shell_command,+ cwd=self._cwd,timeout=timeout_sec,)# Decode and normalize line endings- stdout = stdout_bytes.decode("utf-8", errors="replace").replace(- "\r\n",- "\n",- )- stderr = stderr_bytes.decode("utf-8", errors="replace").replace(- "\r\n",- "\n",- )+ stdout = result.stdout.decode(+ "utf-8",+ errors="replace",+ ).replace("\r\n", "\n")+ stderr = result.stderr.decode(+ "utf-8",+ errors="replace",+ ).replace("\r\n", "\n")++ # Check for timeout (backend returns exit_code=-1,+ # stderr=b"timed out")+ if result.exit_code == -1 and result.stderr == b"timed out":+ error_msg = (+ f"Command timed out after {timeout_ms}ms: {command}"+ )+ yield ToolChunk(+ content=[TextBlock(text=error_msg)],+ state=ToolResultState.ERROR,+ is_last=True,+ )+ return# Combine outputoutput = stdout@@ -728,21 +730,23 @@ easier to review tool calls and give permission.output = output[:30000] + "\n... (output truncated)"# Check exit code- if process.returncode != 0:+ if not result.ok():# Command failed- result = f"Command failed: {command}\n"+ error_result = f"Command failed: {command}\n"if stdout:- result += f"\nStdout:\n{stdout}"+ error_result += f"\nStdout:\n{stdout}"if stderr:- result += f"\nStderr:\n{stderr}"+ error_result += f"\nStderr:\n{stderr}"# Truncate error message if needed- if len(result) > 30000:- result = result[:30000] + "\n... (output truncated)"+ if len(error_result) > 30000:+ error_result = (+ error_result[:30000] + "\n... (output truncated)"+ )yield ToolChunk(- content=[TextBlock(text=result)],- state="error",+ content=[TextBlock(text=error_result)],+ state=ToolResultState.ERROR,is_last=True,)else:@@ -750,24 +754,15 @@ easier to review tool calls and give permission.# which will be converted to "finished" in ToolResponseyield ToolChunk(content=[TextBlock(text=output)],- state="running",+ state=ToolResultState.RUNNING,is_last=True,)- except asyncio.TimeoutError:- # Timeout occurred- error_msg = f"Command timed out after {timeout_ms}ms: {command}"- yield ToolChunk(- content=[TextBlock(text=error_msg)],- state="error",- is_last=True,- )-except Exception as e:# Other errorserror_msg = f"Command failed: {command}\nError: {str(e)}"yield ToolChunk(content=[TextBlock(text=error_msg)],- state="error",+ state=ToolResultState.ERROR,is_last=True,)diff --git a/src/agentscope/tool/_builtin/_edit.py b/src/agentscope/tool/_builtin/_edit.pyindex caa79ae53..863a71996 100644--- a/src/agentscope/tool/_builtin/_edit.py+++ b/src/agentscope/tool/_builtin/_edit.py@@ -4,8 +4,6 @@ import fnmatchimport osfrom typing import Any, List-import aiofiles-from .._base import ToolBase, ToolMiddlewareBasefrom .._constants import (DEFAULT_DANGEROUS_FILES,@@ -21,6 +19,7 @@ from ...permission import (from .._response import ToolChunkfrom ...message import TextBlock, ToolResultStatefrom ...state import AgentState+from ._backend import BackendBase, _normalize_newlinesclass Edit(ToolBase):@@ -90,6 +89,7 @@ Usage:dangerous_files: list[str] = DEFAULT_DANGEROUS_FILES,dangerous_directories: list[str] = DEFAULT_DANGEROUS_DIRECTORIES,middlewares: List[ToolMiddlewareBase] | None = None,+ backend: BackendBase | None = None,) -> None:"""Initialize the edit tool.@@ -109,10 +109,16 @@ Usage:directory check.middlewares (`List[ToolMiddlewareBase] | None`, optional):Tool middlewares wrapping the tool execution.+ backend (`BackendBase | None`, optional):+ The sandbox backend to use for file I/O. When ``None``,+ a :class:`LocalBackend` is created."""+ from ._backend import LocalBackend+super().__init__(middlewares=middlewares)self.dangerous_files = list(dangerous_files)self.dangerous_directories = list(dangerous_directories)+ self._backend = backend or LocalBackend()async def check_permissions(self,@@ -261,7 +267,7 @@ Usage:)# Check file exists- if not os.path.exists(file_path):+ if not await self._backend.file_exists(file_path):return ToolChunk(content=[TextBlock(text=f"Error: File not found: {file_path}"),@@ -302,14 +308,14 @@ Usage:)content = "".join(cache.lines)else:- # No state provided, read from disk+ # No state provided, read from backendtry:- async with aiofiles.open(- file_path,- "r",- encoding="utf-8",- ) as f:- content = await f.read()+ raw = await self._backend.read_file(file_path)+ # Normalize CRLF/CR to match the cached-content path and+ # the LF-based old_string the caller supplies.+ content = _normalize_newlines(+ raw.decode("utf-8", errors="replace"),+ )except Exception as e:return ToolChunk(content=[TextBlock(text=f"Error reading file: {str(e)}")],@@ -359,14 +365,12 @@ Usage:1,)- # Write updated content back to file+ # Write updated content back to file via backendtry:- async with aiofiles.open(+ await self._backend.write_file(file_path,- "w",- encoding="utf-8",- ) as f:- await f.write(updated_content)+ updated_content.encode("utf-8"),+ )except Exception as e:return ToolChunk(content=[TextBlock(text=f"Error writing file: {str(e)}")],diff --git a/src/agentscope/tool/_builtin/_glob.py b/src/agentscope/tool/_builtin/_glob.pyindex 80c3d1bdc..563c56374 100644--- a/src/agentscope/tool/_builtin/_glob.py+++ b/src/agentscope/tool/_builtin/_glob.py@@ -1,19 +1,43 @@# -*- coding: utf-8 -*-"""The glob tool in agentscope."""++from __future__ import annotations+import fnmatch+import jsonimport os-import re-from typing import Any, List+import sys+from typing import TYPE_CHECKING, Any, List-from .._base import ToolBase, ToolMiddlewareBase+from ...message import TextBlock, ToolResultStatefrom ...permission import (+ PermissionBehavior,PermissionContext,PermissionDecision,- PermissionBehavior,PermissionRule,)+from .._base import ToolBase, ToolMiddlewareBasefrom .._response import ToolChunk-from ...message import TextBlock++if TYPE_CHECKING:+ from ._backend import BackendBase+++def _default_glob_helper_path() -> str:+ """Resolve the on-disk path of the bundled ``_glob_helper.py`` script.++ Used by :class:`Glob` when no explicit ``glob_helper_path`` is+ provided (i.e. the local-workspace case). The path is obtained via+ :mod:`importlib.resources` so it works for both editable and+ installed packages.+ """+ import importlib.resources as _res++ ref = _res.files("agentscope.tool._builtin._scripts").joinpath(+ "_glob_helper.py",+ )+ # as_posix() on a MultiplexedPath / PosixPath gives a str path+ return str(ref)class Glob(ToolBase):@@ -57,6 +81,8 @@ codebase.""" # ignore: E501def __init__(self,+ backend: BackendBase | None = None,+ glob_helper_path: str | None = None,middlewares: List[ToolMiddlewareBase] | None = None,) -> None:"""Initialize the glob tool.@@ -64,8 +90,30 @@ codebase.""" # ignore: E501Args:middlewares (`List[ToolMiddlewareBase] | None`, optional):Tool middlewares wrapping the tool execution.+ backend (`BackendBase | None`, optional):+ The sandbox backend to use. When ``None``, a+ :class:`LocalBackend` is created automatically.+ glob_helper_path (`str | None`, optional):+ Filesystem path (inside the backend's environment) to+ the ``_glob_helper.py`` script. When ``None``, the+ path is resolved from the installed package resources+ (suitable for :class:`LocalBackend`). Remote backends+ (Docker, E2B) should pass the path where the script+ was deployed during workspace initialization."""+ from ._backend import LocalBackend+super().__init__(middlewares=middlewares)+ self._backend = backend or LocalBackend()+ # When running against the host, invoke the helper with the+ # current interpreter (``sys.executable``) rather than assuming+ # ``python3`` is on PATH.+ self._is_local = isinstance(self._backend, LocalBackend)+ self._glob_helper_path = (+ glob_helper_path+ if glob_helper_path is not None+ else _default_glob_helper_path()+ )async def check_permissions(self,@@ -155,123 +203,6 @@ codebase.""" # ignore: E501),]- def glob_part_to_regex(self, part: str) -> re.Pattern:- """Convert a glob pattern part to a regex pattern.-- Args:- part: A single part of a glob pattern (e.g., '*.py', 'test_??.py')-- Returns:- A compiled regex pattern- """- regex_str = ""- i = 0- while i < len(part):- c = part[i]- if c == "*":- regex_str += ".*"- elif c == "?":- regex_str += "."- elif c in ".^$+{}[]|()\\":- regex_str += "\\" + c- else:- regex_str += c- i += 1- return re.compile(f"^{regex_str}$")-- def collect_all(self, current_dir: str, results: list[str]) -> None:- """Recursively collect all files in a directory.-- Args:- current_dir: The directory to collect files from- results: The list to append matched file paths to- """- try:- for root, _dirs, files in os.walk(current_dir):- for file in files:- results.append(os.path.join(root, file))- except (PermissionError, OSError):- # Skip unreadable directories silently- pass-- def match_parts(- self,- parts: list[str],- part_index: int,- current_dir: str,- results: list[str],- ) -> None:- """Recursively match path parts against directory entries.-- Args:- parts: The split glob pattern parts- part_index: The current index in the parts array- current_dir: The current directory being traversed- results: The list to append matched file paths to- """- if part_index >= len(parts):- return-- part = parts[part_index]- is_last = part_index == len(parts) - 1-- if part == "**":- if is_last:- self.collect_all(current_dir, results)- else:- # Match in current directory- self.match_parts(parts, part_index + 1, current_dir, results)- # Recursively match in subdirectories- try:- with os.scandir(current_dir) as entries:- for entry in entries:- if entry.is_dir(follow_symlinks=False):- self.match_parts(- parts,- part_index,- entry.path,- results,- )- except (PermissionError, OSError):- # Skip unreadable directories silently- pass- else:- regex = self.glob_part_to_regex(part)- try:- with os.scandir(current_dir) as entries:- for entry in entries:- if regex.match(entry.name):- full_path = entry.path- if is_last:- if entry.is_file(follow_symlinks=False):- results.append(full_path)- elif entry.is_dir(follow_symlinks=False):- self.match_parts(- parts,- part_index + 1,- full_path,- results,- )- except (PermissionError, OSError):- # Skip unreadable directories silently- pass-- def glob_match(self, pattern: str, base_dir: str) -> list[str]:- """Match files against a glob pattern starting from the given- base directory.-- Args:- pattern: The glob pattern to match against- base_dir: The base directory to search from-- Returns:- A list of matched file paths- """- results: list[str] = []- parts = [p for p in re.split(r"[\\/]+", pattern) if p]- self.match_parts(parts, 0, base_dir, results)- return results-async def call( # type: ignore[override]self,pattern: str,@@ -279,33 +210,82 @@ codebase.""" # ignore: E501) -> ToolChunk:"""Execute the glob pattern matching and return the results.+ Invokes the standalone ``_glob_helper.py`` script via+ ``exec_shell``. The script performs high-performance+ ``os.walk`` + ``os.scandir`` matching and returns results+ sorted by modification time (newest first) as JSON.++ This unified path works identically across Local, Docker,+ and E2B backends.+Args:- pattern: The glob pattern to match against- path: Optional base directory to search from (defaults to cwd)+ pattern (`str`):+ The glob pattern to match against (e.g. ``**/*.py``).+ path (`str | None`, optional):+ Base directory to search from. Defaults to the current+ working directory when ``None``.Returns:`ToolChunk`:- The content contains the matched file paths joined by- newlines, or an error message if the directory is not found or- no files match the pattern.+ On success, the matched file paths joined by newlines+ (or a "no files found" message). If the base directory+ is missing or the helper fails, an error chunk with+ ``ToolResultState.ERROR``."""base_dir = path if path else os.getcwd()- if not os.path.exists(base_dir):+ # The base must be an existing directory; a regular file would+ # otherwise be accepted here and fail later with a confusing+ # error from the helper.+ if not await self._backend.is_dir(base_dir):return ToolChunk(- content=[TextBlock(text=f"Directory not found: {base_dir}")],- state="error",+ content=[+ TextBlock(text=f"Directory not found: {base_dir}"),+ ],+ state=ToolResultState.ERROR,is_last=True,)- matches = self.glob_match(pattern, base_dir)+ # Invoke the glob helper script via exec_shell as an argv list+ # (run directly, without a shell, so no platform-specific+ # quoting is needed). Use the current interpreter locally+ # (``python3`` may be absent, e.g. on Windows or venvs exposing+ # only ``python``); remote backends run inside Linux images+ # where ``python3`` is the safe choice.+ python = sys.executable if self._is_local else "python3"+ command = [+ python,+ self._glob_helper_path,+ "--pattern",+ pattern,+ "--base-dir",+ base_dir,+ ]+ result = await self._backend.exec_shell(command, timeout=30.0)++ # A non-zero exit means the helper itself failed (missing+ # interpreter/script, permission error, …) — surface it rather+ # than masking it as an empty match.+ if not result.ok():+ stderr = result.stderr.decode("utf-8", errors="replace").strip()+ return ToolChunk(+ content=[+ TextBlock(+ text=f"Glob helper failed: {stderr}"+ if stderr+ else "Glob helper failed with no error output.",+ ),+ ],+ state=ToolResultState.ERROR,+ is_last=True,+ )- # Sort by modification time (newest first)try:- matches.sort(key=lambda p: os.stat(p).st_mtime, reverse=True)- except (OSError, FileNotFoundError):- # If we can't stat some files, just keep the unsorted order- pass+ matches = json.loads(+ result.stdout.decode("utf-8", errors="replace"),+ )+ except (json.JSONDecodeError, ValueError):+ matches = []if len(matches) == 0:return ToolChunk(@@ -314,12 +294,12 @@ codebase.""" # ignore: E501text=f"No files found matching pattern: {pattern}",),],- state="running",+ state=ToolResultState.RUNNING,is_last=True,)return ToolChunk(content=[TextBlock(text="\n".join(matches))],- state="running",+ state=ToolResultState.RUNNING,is_last=True,)diff --git a/src/agentscope/tool/_builtin/_grep.py b/src/agentscope/tool/_builtin/_grep.pyindex a142deefc..c358e919d 100644--- a/src/agentscope/tool/_builtin/_grep.py+++ b/src/agentscope/tool/_builtin/_grep.py@@ -1,13 +1,10 @@# -*- coding: utf-8 -*-"""The grep tool in agentscope."""-import asyncioimport fnmatchimport os-import shutilfrom typing import Any, List, Literalfrom .._base import ToolBase, ToolMiddlewareBase-from ..._logging import loggerfrom ...permission import (PermissionContext,PermissionDecision,@@ -16,6 +13,7 @@ from ...permission import ()from .._response import ToolChunkfrom ...message import TextBlock, ToolResultState+from ._backend import BackendBase# Version control system directories to exclude from searchesVCS_DIRECTORIES_TO_EXCLUDE = [@@ -160,22 +158,24 @@ class Grep(ToolBase):def __init__(self,middlewares: List[ToolMiddlewareBase] | None = None,+ backend: BackendBase | None = None,) -> None:"""Initialize the grep tool.Args:middlewares (`List[ToolMiddlewareBase] | None`, optional):Tool middlewares wrapping the tool execution.+ backend (`BackendBase | None`, optional):+ The sandbox backend to use for shell execution. When+ ``None``, a :class:`LocalBackend` is created.+ Ripgrep is always invoked via ``exec_shell`` so that+ the same code path works for local, Docker, and E2B+ backends."""+ from ._backend import LocalBackend+super().__init__(middlewares=middlewares)- self._rg_path = shutil.which("rg")- if self._rg_path is None:- logger.warning(- "ripgrep (rg) binary not found. To use the Grep tool, "- "install ripgrep: pip install agentscope[tools] or "- "brew install ripgrep / apt install ripgrep / "- "choco install ripgrep",- )+ self._backend = backend or LocalBackend()async def check_permissions(self,@@ -277,37 +277,39 @@ class Grep(ToolBase):search_path: str,timeout: int = 30,) -> list[str]:- """Run ripgrep and return output lines."""- full_args: list = [self._rg_path, *args, search_path]+ """Run ripgrep and return output lines.++ Builds an argument vector and dispatches it through+ ``backend.exec_shell`` (which runs the program directly, without+ a shell), so the same code path works for local, Docker, and E2B+ backends and needs no platform-specific argument quoting.+ """+ command = ["rg", *args, search_path]- proc = await asyncio.create_subprocess_exec(- *full_args,- stdout=asyncio.subprocess.PIPE,- stderr=asyncio.subprocess.PIPE,+ result = await self._backend.exec_shell(+ command,+ timeout=float(timeout),)- try:- stdout, stderr = await asyncio.wait_for(- proc.communicate(),- timeout=timeout,- )- except asyncio.TimeoutError as e:- proc.kill()- await proc.communicate()+ if result.exit_code == -1 and result.stderr == b"timed out":raise RipgrepTimeoutError(f"Ripgrep search timed out after {timeout} seconds. ""Try searching a more specific path or pattern.",[],- ) from e+ )- # returncode 0 = matches found, 1 = no matches (both are success)- if proc.returncode not in (0, 1):- error_msg = stderr.decode("utf-8", errors="ignore").strip()+ # returncode 0 = matches found, 1 = no matches+ if result.exit_code not in (0, 1):+ error_msg = result.stderr.decode(+ "utf-8",+ errors="ignore",+ ).strip()raise RuntimeError(- f"ripgrep error (code {proc.returncode}): {error_msg}",+ f"ripgrep error (code {result.exit_code}): {error_msg}",)- raw = stdout.decode("utf-8", errors="ignore")+ raw = result.stdout.decode("utf-8", errors="ignore")+lines = [line.rstrip("\r") for line in raw.split("\n") if line.rstrip("\r")]@@ -351,20 +353,6 @@ class Grep(ToolBase):n: Show line numbers (content mode only, default True)**kwargs: Additional parameters (-A, -B, -C)"""- if self._rg_path is None:- return ToolChunk(- content=[- TextBlock(- text="ripgrep (rg) not found. Please install it: "- "macOS: brew install ripgrep | "- "Linux: apt/yum install ripgrep | "- "Windows: choco install ripgrep",- ),- ],- state=ToolResultState.ERROR,- is_last=True,- )-search_path = path or os.getcwd()args: list[str] = ["--hidden"]diff --git a/src/agentscope/tool/_builtin/_read.py b/src/agentscope/tool/_builtin/_read.pyindex d5087e5dd..b45e2e6c7 100644--- a/src/agentscope/tool/_builtin/_read.py+++ b/src/agentscope/tool/_builtin/_read.py@@ -4,8 +4,6 @@ import fnmatchimport osfrom typing import Any, List-import aiofiles-from .._base import ToolBase, ToolMiddlewareBasefrom ...permission import (PermissionContext,@@ -16,6 +14,7 @@ from ...permission import (from .._response import ToolChunkfrom ...message import TextBlock, ToolResultStatefrom ...state import AgentState+from ._backend import BackendBase, _normalize_newlinesclass Read(ToolBase):@@ -73,6 +72,7 @@ Usage:self,max_line_characters: int = 2000,middlewares: List[ToolMiddlewareBase] | None = None,+ backend: BackendBase | None = None,) -> None:"""Initialize the read tool.@@ -85,9 +85,15 @@ Usage:content.middlewares (`List[ToolMiddlewareBase] | None`, optional):Tool middlewares wrapping the tool execution.+ backend (`BackendBase | None`, optional):+ The sandbox backend to use for file I/O. When ``None``,+ a :class:`LocalBackend` is created."""+ from ._backend import LocalBackend+super().__init__(middlewares=middlewares)self._max_line_characters = max_line_characters+ self._backend = backend or LocalBackend()async def check_permissions(self,@@ -193,7 +199,7 @@ Usage:)# Check file exists- if not os.path.exists(file_path):+ if not await self._backend.file_exists(file_path):return ToolChunk(content=[TextBlock(text=f"Error: File does not exist: {file_path}"),@@ -203,7 +209,7 @@ Usage:)# Check it's not a directory- if os.path.isdir(file_path):+ if await self._backend.is_dir(file_path):return ToolChunk(content=[TextBlock(@@ -216,7 +222,7 @@ Usage:)try:- # Read file content with aiofiles+ # Read file content via backendlines = Noneif _agent_state is not None:cache = await _agent_state.tool_context.get_cache(file_path)@@ -224,13 +230,13 @@ Usage:lines = cache.linesif lines is None:- async with aiofiles.open(- file_path,- mode="r",- encoding="utf-8",- errors="replace",- ) as f:- lines = await f.readlines()+ raw = await self._backend.read_file(file_path)+ content_str = raw.decode("utf-8", errors="replace")+ # Normalize CRLF/CR so cached lines end in "\n" regardless+ # of the platform the file was written on (Windows text+ # files use "\r\n").+ content_str = _normalize_newlines(content_str)+ lines = content_str.splitlines(keepends=True)# Cache file if state is providedif _agent_state is not None:diff --git a/src/agentscope/tool/_builtin/_scripts/__init__.py b/src/agentscope/tool/_builtin/_scripts/__init__.pynew file mode 100644index 000000000..596df86db--- /dev/null+++ b/src/agentscope/tool/_builtin/_scripts/__init__.py@@ -0,0 +1,9 @@+# -*- coding: utf-8 -*-+"""Standalone helper scripts shipped as package resources.++Scripts in this package are deployed into remote workspaces (Docker /+E2B) at initialization time and invoked via ``exec_shell``. They must+remain importable *without* ``agentscope`` installed — the host reads+them as raw bytes via :mod:`importlib.resources` and ships them into+the workspace environment.+"""diff --git a/src/agentscope/tool/_builtin/_scripts/_glob_helper.py b/src/agentscope/tool/_builtin/_scripts/_glob_helper.pynew file mode 100644index 000000000..d6025eca3--- /dev/null+++ b/src/agentscope/tool/_builtin/_scripts/_glob_helper.py@@ -0,0 +1,215 @@+#!/usr/bin/env python3+# -*- coding: utf-8 -*-+"""Standalone glob helper script for agentscope builtin tools.++This script is designed to run **without** agentscope installed. It is+deployed into remote workspaces (Docker / E2B) at initialization time+and invoked via ``exec_shell`` by the :class:`Glob` tool.++Usage::++ python3 _glob_helper.py --pattern '**/*.py' --base-dir /workspace++Output: a JSON array of matching file paths, sorted by modification+time (newest first). Exits with code 0 on success (even when no+matches are found — the array is simply empty).+"""++from __future__ import annotations++import argparse+import json+import os+import re+import sys++# ── glob matching (mirrors the logic from Glob tool) ──────────────+++def _glob_part_to_regex(part: str) -> re.Pattern[str]:+ """Convert a single glob pattern segment to a compiled regex.++ Translates glob wildcards (``*`` → ``.*``, ``?`` → ``.``) and+ escapes regex meta-characters so that a segment like ``*.py``+ becomes the anchored pattern ``^.*\\.py$``.++ Args:+ part: One path segment of a glob pattern (e.g. ``*.py``+ or ``test_*``).++ Returns:+ A compiled :class:`re.Pattern` anchored with ``^…$``.+ """+ regex_str = ""+ for c in part:+ if c == "*":+ regex_str += ".*"+ elif c == "?":+ regex_str += "."+ elif c in ".^$+{}[]|()\\":+ regex_str += "\\" + c+ else:+ regex_str += c+ return re.compile(f"^{regex_str}$")+++def _collect_all(current_dir: str, results: list[str]) -> None:+ """Recursively collect all file paths under *current_dir*.++ Uses :func:`os.walk` to traverse the directory tree.+ ``PermissionError`` and ``OSError`` are silently ignored so that+ inaccessible subtrees do not abort the entire glob operation.++ Args:+ current_dir: Root directory to walk.+ results: Accumulator list; matched file paths are appended+ in-place.+ """+ try:+ for root, _dirs, files in os.walk(current_dir):+ for fname in files:+ results.append(os.path.join(root, fname))+ except (PermissionError, OSError):+ pass+++def _match_parts(+ parts: list[str],+ part_index: int,+ current_dir: str,+ results: list[str],+) -> None:+ """Recursively match glob pattern *parts* against directory entries.++ Walks the filesystem starting from *current_dir*, consuming one+ pattern segment per directory level. The ``**`` segment is handled+ specially: it matches zero or more intermediate directories by+ recursing into every subdirectory while keeping the same+ *part_index*, and also advancing to the next segment in the+ current directory.++ Args:+ parts: The glob pattern split into path segments+ (e.g. ``["src", "**", "*.py"]``).+ part_index: Index into *parts* indicating which segment is+ being matched at this recursion level.+ current_dir: The directory currently being scanned.+ results: Accumulator list; matched file paths are appended+ in-place.+ """+ if part_index >= len(parts):+ return++ part = parts[part_index]+ is_last = part_index == len(parts) - 1++ if part == "**":+ if is_last:+ _collect_all(current_dir, results)+ else:+ _match_parts(parts, part_index + 1, current_dir, results)+ try:+ with os.scandir(current_dir) as entries:+ for entry in entries:+ if entry.is_dir(follow_symlinks=False):+ _match_parts(+ parts,+ part_index,+ entry.path,+ results,+ )+ except (PermissionError, OSError):+ pass+ else:+ regex = _glob_part_to_regex(part)+ try:+ with os.scandir(current_dir) as entries:+ for entry in entries:+ if regex.match(entry.name):+ full_path = entry.path+ if is_last:+ if entry.is_file(follow_symlinks=False):+ results.append(full_path)+ elif entry.is_dir(follow_symlinks=False):+ _match_parts(+ parts,+ part_index + 1,+ full_path,+ results,+ )+ except (PermissionError, OSError):+ pass+++def glob_match(pattern: str, base_dir: str) -> list[str]:+ """Match files against a glob pattern starting from *base_dir*.++ Splits *pattern* on path separators (``/`` or ``\\``) and+ delegates to :func:`_match_parts` for recursive directory+ traversal. Supports ``*`` (any characters within a segment),+ ``?`` (single character), and ``**`` (zero or more directories).++ Args:+ pattern: Glob pattern such as ``"**/*.py"`` or+ ``"src/utils/*.txt"``.+ base_dir: Absolute path of the directory to search from.++ Returns:+ A list of absolute file paths that match *pattern*. The+ list is unsorted; callers should sort as needed (e.g. by+ modification time).+ """+ results: list[str] = []+ parts = [p for p in re.split(r"[\\/]+", pattern) if p]+ _match_parts(parts, 0, base_dir, results)+ return results+++# ── entry point ───────────────────────────────────────────────────+++def main() -> None:+ """CLI entry point: parse ``--pattern`` and ``--base-dir``, run+ the glob, and print results as a JSON array to stdout.++ The results are sorted by file modification time (newest first).+ If *base_dir* does not exist, an empty JSON array ``[]`` is+ printed and the process exits with code 0.+ """+ parser = argparse.ArgumentParser(+ description="Glob file matching with mtime sorting.",+ )+ parser.add_argument(+ "--pattern",+ required=True,+ help="Glob pattern (e.g. '**/*.py')",+ )+ parser.add_argument(+ "--base-dir",+ required=True,+ help="Base directory to search from",+ )+ args = parser.parse_args()++ if not os.path.isdir(args.base_dir):+ # Empty result for non-existent directory (caller handles+ # the "directory not found" error message).+ json.dump([], sys.stdout)+ return++ matches = glob_match(args.pattern, args.base_dir)++ # Sort by modification time, newest first.+ def _mtime(path: str) -> float:+ try:+ return os.stat(path).st_mtime+ except (OSError, FileNotFoundError):+ return 0.0++ matches.sort(key=_mtime, reverse=True)++ json.dump(matches, sys.stdout)+++if __name__ == "__main__":+ main()diff --git a/src/agentscope/tool/_builtin/_write.py b/src/agentscope/tool/_builtin/_write.pyindex 7e162738f..d7060df82 100644--- a/src/agentscope/tool/_builtin/_write.py+++ b/src/agentscope/tool/_builtin/_write.py@@ -2,11 +2,8 @@"""The write tool in agentscope."""import fnmatchimport os-from pathlib import Pathfrom typing import Any, List-import aiofiles-from .._base import ToolBase, ToolMiddlewareBasefrom .._constants import (DEFAULT_DANGEROUS_FILES,@@ -22,6 +19,7 @@ from ...permission import (from .._response import ToolChunkfrom ...message import TextBlock, ToolResultStatefrom ...state import AgentState+from ._backend import BackendBaseclass Write(ToolBase):@@ -68,6 +66,7 @@ Usage:dangerous_files: list[str] = DEFAULT_DANGEROUS_FILES,dangerous_directories: list[str] = DEFAULT_DANGEROUS_DIRECTORIES,middlewares: List[ToolMiddlewareBase] | None = None,+ backend: BackendBase | None = None,) -> None:"""Initialize the write tool.@@ -87,11 +86,18 @@ Usage:directory check.middlewares (`List[ToolMiddlewareBase] | None`, optional):Tool middlewares wrapping the tool execution.+ backend (`BackendBase | None`, optional):+ The sandbox backend to use for file I/O. When ``None``,+ a :class:`LocalBackend` is created."""+ from ._backend import LocalBackend+super().__init__(middlewares=middlewares)self.dangerous_files = list(dangerous_files)self.dangerous_directories = list(dangerous_directories)+ self._backend = backend or LocalBackend()+async def check_permissions(self,tool_input: dict[str, Any],@@ -235,7 +241,10 @@ Usage:)# Check if file exists, it must be read first if it exists- if os.path.exists(file_path) and _agent_state is not None:+ if (+ await self._backend.file_exists(file_path)+ and _agent_state is not None+ ):cache = await _agent_state.tool_context.get_cache(file_path)if cache is None:return ToolChunk(@@ -250,13 +259,11 @@ Usage:is_last=True,)- # Create parent directories if they don't exist- parent_dir = Path(file_path).parent- os.makedirs(parent_dir, exist_ok=True)-- # Write content to file- async with aiofiles.open(file_path, mode="w", encoding="utf-8") as f:- await f.write(content)+ # Write content to file (backend handles parent dir creation)+ await self._backend.write_file(+ file_path,+ content.encode("utf-8"),+ )# Count lines in contentline_count = len(content.split("\n"))diff --git a/src/agentscope/workspace/__init__.py b/src/agentscope/workspace/__init__.pyindex 875872eaa..37531571f 100644--- a/src/agentscope/workspace/__init__.py+++ b/src/agentscope/workspace/__init__.py@@ -5,14 +5,16 @@from ._base import WorkspaceBasefrom ._local_workspace import LocalWorkspacefrom ._offload_protocol import Offloader-from ._docker import DockerWorkspace-from ._e2b import E2BWorkspace+from ._docker import DockerBackend, DockerWorkspace+from ._e2b import E2BWorkspace, E2BBackend__all__ = ["WorkspaceBase","LocalWorkspace",+ "DockerBackend","DockerWorkspace",+ "E2BBackend","E2BWorkspace","Offloader",]diff --git a/src/agentscope/workspace/_docker/Dockerfile.template b/src/agentscope/workspace/_docker/Dockerfile.templateindex 74c01745a..22bb6a843 100644--- a/src/agentscope/workspace/_docker/Dockerfile.template+++ b/src/agentscope/workspace/_docker/Dockerfile.template@@ -12,7 +12,7 @@# ``INSTALLER_NO_MODIFY_PATH=1`` suppresses the installer's attempt to# patch shell rc files (we don't need it — PATH already covers it).RUN apt-get update \- && apt-get install -y --no-install-recommends curl ca-certificates \+ && apt-get install -y --no-install-recommends curl ca-certificates ripgrep \&& rm -rf /var/lib/apt/lists/* \&& curl -LsSf https://astral.sh/uv/install.sh \| env UV_INSTALL_DIR=/usr/local/bin INSTALLER_NO_MODIFY_PATH=1 sh@@ -41,5 +41,7 @@ RUN uv pip install -r {gateway_home}/requirements.txt# graph (skill, tool, …). The script imports only# ``agentscope.mcp.MCPClient``.COPY _mcp_gateway_app.py {gateway_home}/_mcp_gateway_app.py+# Glob helper script used by the builtin Glob tool.+COPY _glob_helper.py {gateway_home}/_glob_helper.pyWORKDIR {container_workdir}diff --git a/src/agentscope/workspace/_docker/__init__.py b/src/agentscope/workspace/_docker/__init__.pyindex 37eb79152..1363a9854 100644--- a/src/agentscope/workspace/_docker/__init__.py+++ b/src/agentscope/workspace/_docker/__init__.py@@ -8,5 +8,6 @@ reached over HTTP — see :mod:`agentscope.workspace._gateway_client`."""from ._docker_workspace import DockerWorkspace+from ._docker_backend import DockerBackend-__all__ = ["DockerWorkspace"]+__all__ = ["DockerWorkspace", "DockerBackend"]diff --git a/src/agentscope/workspace/_docker/_docker_backend.py b/src/agentscope/workspace/_docker/_docker_backend.pynew file mode 100644index 000000000..8b2afa4f6--- /dev/null+++ b/src/agentscope/workspace/_docker/_docker_backend.py@@ -0,0 +1,180 @@+# -*- coding: utf-8 -*-+"""Docker container :class:`BackendBase` implementation.++Wraps the ``aiodocker`` container APIs (``exec``, ``get_archive``,+``put_archive``) into the three backend primitives (``exec_shell``,+``read_file``, ``write_file``) so that builtin tools (Bash, Read,+Write, Edit, Grep, Glob) can operate inside a Docker container+transparently. All derived filesystem helpers (``file_exists``,+``is_dir``, ``list_dir``, ``stat_mtime``, ``delete_path``) are+inherited from :class:`BackendBase`, which implements them via+``exec_shell``.+"""++from __future__ import annotations++import asyncio+import io+import posixpath+import tarfile+from typing import Any++from ...tool import BackendBase, ExecResult+++class DockerBackend(BackendBase):+ """Backend that delegates to a running Docker container.++ Only the three abstract primitives (``exec_shell``, ``read_file``,+ ``write_file``) are implemented here; the derived filesystem helpers+ are inherited from :class:`BackendBase`.++ Args:+ container (`Any`):+ An ``aiodocker`` container object (must already be started).+ workdir (`str`):+ Default working directory for ``exec_shell`` calls inside+ the container.+ """++ def __init__(self, container: Any, workdir: str) -> None:+ """Initialize the Docker backend.++ Args:+ container (`Any`):+ A started ``aiodocker`` container object.+ workdir (`str`):+ Default working directory for ``exec_shell`` calls+ inside the container.+ """+ self._container = container+ self._workdir = workdir++ # ── exec ───────────────────────────────────────────────────────++ async def exec_shell(+ self,+ command: list[str],+ *,+ cwd: str | None = None,+ timeout: float | None = None,+ ) -> ExecResult:+ """Run a program directly inside the container.++ *command* is an argv list executed via the container ``exec``+ API without an intervening shell. Callers needing shell features+ wrap their command line as ``["sh", "-c", line]``.++ Args:+ command (`list[str]`):+ Executable path/name followed by its arguments.+ cwd (`str | None`, optional):+ Working directory inside the container. When ``None``+ the backend's default ``workdir`` is used.+ timeout (`float | None`, optional):+ Maximum number of seconds to wait before returning an+ ``exit_code`` of ``-1``. When ``None`` the call waits+ indefinitely.++ Returns:+ `ExecResult`:+ The captured exit code, stdout, and stderr.+ """++ async def _run() -> ExecResult:+ exec_obj = await self._container.exec(+ cmd=command,+ workdir=cwd or self._workdir,+ )+ stdout_parts: list[bytes] = []+ stderr_parts: list[bytes] = []+ async with exec_obj.start() as stream:+ while True:+ msg = await stream.read_out()+ if msg is None:+ break+ if msg.stream == 1:+ stdout_parts.append(msg.data)+ else:+ stderr_parts.append(msg.data)+ inspect = await exec_obj.inspect()+ code = inspect.get("ExitCode", -1)+ if code is None:+ code = -1+ return ExecResult(+ exit_code=int(code),+ stdout=b"".join(stdout_parts),+ stderr=b"".join(stderr_parts),+ )++ if timeout is None:+ return await _run()+ try:+ return await asyncio.wait_for(_run(), timeout=timeout)+ except asyncio.TimeoutError:+ return ExecResult(+ exit_code=-1,+ stdout=b"",+ stderr=b"timed out",+ )++ # ── file I/O ───────────────────────────────────────────────────++ async def read_file(self, path: str) -> bytes:+ """Fetch a file from the container via ``get_archive``.++ Args:+ path (`str`):+ Path to the file inside the container.++ Returns:+ `bytes`:+ The raw file contents.++ Raises:+ `FileNotFoundError`:+ If the path does not exist inside the container.+ """+ from aiodocker import exceptions as aiodocker_exceptions++ try:+ tar = await self._container.get_archive(path)+ except aiodocker_exceptions.DockerError as exc:+ if exc.status == 404:+ raise FileNotFoundError(+ f"not found in container: {path}",+ ) from exc+ raise++ try:+ for member in tar.getmembers():+ if member.isfile():+ f = tar.extractfile(member)+ if f:+ return f.read()+ finally:+ tar.close()+ raise FileNotFoundError(f"not found in container: {path}")++ async def write_file(self, path: str, data: bytes) -> None:+ """Write raw bytes to a file inside the container.++ Creates the parent directory first since ``put_archive``+ requires it to exist.++ Args:+ path (`str`):+ Destination path inside the container.+ data (`bytes`):+ The raw bytes to write.+ """+ parent = posixpath.dirname(path) or "/"+ name = posixpath.basename(path)++ await self.exec_shell(["mkdir", "-p", parent])+ buf = io.BytesIO()+ with tarfile.open(fileobj=buf, mode="w") as tf:+ info = tarfile.TarInfo(name=name)+ info.size = len(data)+ tf.addfile(info, io.BytesIO(data))+ await self._container.put_archive(parent, buf.getvalue())diff --git a/src/agentscope/workspace/_docker/_docker_workspace.py b/src/agentscope/workspace/_docker/_docker_workspace.pyindex 5978b38cd..22a670e7c 100644--- a/src/agentscope/workspace/_docker/_docker_workspace.py+++ b/src/agentscope/workspace/_docker/_docker_workspace.py@@ -39,7 +39,6 @@ import sysimport tarfileimport uuidfrom copy import deepcopy-from dataclasses import dataclassfrom typing import Anyfrom pydantic import AnyUrl@@ -61,6 +60,7 @@ from .._gateway_client import (GatewayClient,GatewayMCPClient,)+from ._docker_backend import DockerBackendfrom ._make_dockerfile import (CONTAINER_DATA_DIR,CONTAINER_SESSIONS_DIR,@@ -73,10 +73,10 @@ from ._make_dockerfile import (GATEWAY_LOG,GATEWAY_SCRIPT,GATEWAY_VENV,+ GLOB_HELPER_SCRIPT,prepare_build_context,)-_DEFAULT_INSTRUCTIONS = """<workspace>You have a Docker-based workspace. All tool calls execute **inside thecontainer** at ``{workdir}``.@@ -95,32 +95,6 @@ and processes.</workspace>"""-# ── small helpers ──────────────────────────────────────────────────---@dataclass(frozen=True, slots=True)-class _ExecResult:- """Result of running a command inside the container via ``docker exec``.-- Attributes:- exit_code: Process exit code from the container.- ``-1`` indicates the exec call timed out or the engine- failed to report a code.- stdout: Raw bytes captured from the command's stdout- (channel ``1`` of the docker exec stream).- stderr: Raw bytes captured from the command's stderr- (channel ``2`` of the docker exec stream).- """-- exit_code: int- stdout: bytes- stderr: bytes-- def ok(self) -> bool:- """Return ``True`` iff the command exited with code ``0``."""- return self.exit_code == 0--# ── the workspace ──────────────────────────────────────────────────@@ -227,6 +201,7 @@ class DockerWorkspace(WorkspaceBase):# ── runtime state ───────────────────────────────────────self._client: Any = None # aiodocker.Dockerself._container: Any = None+ self._backend: DockerBackend | None = Noneself._port_mapping: dict[int, int] = {}self._image_tag: str = ""self._gateway: GatewayClient | None = None@@ -312,6 +287,14 @@ class DockerWorkspace(WorkspaceBase):The gateway process keeps running with no upstream MCPs.``default_mcps`` / ``skill_paths`` are not re-seeded."""+ if self._backend is None:+ raise RuntimeError(+ "DockerWorkspace is not initialized: its container "+ "backend is unavailable. Use 'async with workspace:' "+ "or call 'await workspace.initialize()' before "+ "'reset()'.",+ )+async with self._mcp_lock, self._skill_lock:for gw_client in list(self._gateway_clients.values()):try:@@ -325,14 +308,12 @@ class DockerWorkspace(WorkspaceBase):self._gateway_clients.clear()self._mcps = []- paths = [+ for path in (CONTAINER_SESSIONS_DIR,CONTAINER_DATA_DIR,CONTAINER_SKILLS_DIR,- ]- await self._exec(- "rm -rf " + " ".join(shlex.quote(p) for p in paths),- )+ ):+ await self._backend.delete_path(path)# Rewrite ``.mcp`` to an empty list so a future restart does# not fall back to ``default_mcps`` (which would only happen@@ -366,11 +347,19 @@ class DockerWorkspace(WorkspaceBase):# transparently, so this only matters on Linux. Best-effort:# exec failures are swallowed, and we still tear the# container down.- if self.host_workdir is not None and sys.platform == "linux":+ if (+ self.host_workdir is not None+ and sys.platform == "linux"+ and self._backend is not None+ ):try:- await self._exec(- f"chown -R {os.getuid()}:{os.getgid()} "- f"{shlex.quote(CONTAINER_WORKDIR)}",+ await self._backend.exec_shell(+ [+ "chown",+ "-R",+ f"{os.getuid()}:{os.getgid()}",+ CONTAINER_WORKDIR,+ ],timeout=10.0,)except Exception:@@ -384,6 +373,7 @@ class DockerWorkspace(WorkspaceBase):except Exception:passself._container = None+ self._backend = Noneif self._client is not None:try:@@ -410,10 +400,36 @@ class DockerWorkspace(WorkspaceBase):async def list_tools(self) -> list[ToolBase]:"""Built-in tools exposed by the workspace itself.- Always empty — every tool reaches the agent through an MCP- server registered on the in-container gateway.+ Returns the six builtin tools (Bash, Read, Write, Edit, Grep,+ Glob), each backed by the workspace's :class:`DockerBackend`+ that executes inside the container.++ Raises:+ `RuntimeError`:+ If the workspace has not been initialized yet (the+ container-backed backend is unavailable). Without this+ guard the builtin tools would silently fall back to a+ :class:`LocalBackend` and run on the host instead of+ inside the container."""- return []+ if self._backend is None:+ raise RuntimeError(+ "DockerWorkspace is not initialized: its container "+ "backend is unavailable. Use 'async with workspace:' "+ "or call 'await workspace.initialize()' before "+ "'list_tools()'.",+ )++ from ...tool._builtin import Bash, Edit, Glob, Grep, Read, Write++ return [+ Bash(cwd=CONTAINER_WORKDIR, backend=self._backend),+ Edit(backend=self._backend),+ Glob(backend=self._backend, glob_helper_path=GLOB_HELPER_SCRIPT),+ Grep(backend=self._backend),+ Read(backend=self._backend),+ Write(backend=self._backend),+ ]async def list_mcps(self) -> list[MCPClient]:"""Return one :class:`GatewayMCPClient` per registered MCP.@@ -438,9 +454,13 @@ class DockerWorkspace(WorkspaceBase):"""import frontmatter as fm- result = await self._exec(- f"find {CONTAINER_SKILLS_DIR} -name SKILL.md "- f"2>/dev/null || true",+ result = await self._backend.exec_shell(+ [+ "sh",+ "-c",+ f"find {CONTAINER_SKILLS_DIR} -name SKILL.md "+ f"2>/dev/null || true",+ ],)if not result.ok():return []@@ -453,7 +473,7 @@ class DockerWorkspace(WorkspaceBase):if not md_path:continuetry:- raw = await self._read(md_path)+ raw = await self._backend.read_file(md_path)doc = fm.loads(raw.decode("utf-8"))name = doc.get("name")desc = doc.get("description")@@ -563,15 +583,16 @@ class DockerWorkspace(WorkspaceBase):)async with self._skill_lock:- await self._exec(f"mkdir -p {CONTAINER_SKILLS_DIR}")+ await self._backend.exec_shell(+ ["mkdir", "-p", CONTAINER_SKILLS_DIR],+ )dir_name = os.path.basename(os.path.abspath(skill_path))# Refuse to overwrite an existing directory of the same name —# mirrors the conflict-rejection behaviour of ``mkdir`` here# rather than LocalWorkspace's full hash-dedup index.- check = await self._exec(- f"test -e "- f"{shlex.quote(CONTAINER_SKILLS_DIR + '/' + dir_name)}",+ check = await self._backend.exec_shell(+ ["test", "-e", CONTAINER_SKILLS_DIR + "/" + dir_name],)if check.ok():raise ValueError(@@ -620,12 +641,7 @@ class DockerWorkspace(WorkspaceBase):raise KeyError(f"Skill {name!r} not found. Available: {available}",)- result = await self._exec(f"rm -rf {shlex.quote(target_dir)}")- if not result.ok():- raise RuntimeError(- f"Failed to remove skill {name!r}: "- f"{result.stderr.decode(errors='replace')}",- )+ await self._backend.delete_path(target_dir)# ── offload ─────────────────────────────────────────────────@@ -674,13 +690,13 @@ class DockerWorkspace(WorkspaceBase):msg.content = contentlines.append(msg.model_dump_json())- await self._exec(f"mkdir -p {shlex.quote(base)}")+ await self._backend.exec_shell(["mkdir", "-p", base])existing = b""try:- existing = await self._read(path)+ existing = await self._backend.read_file(path)except (FileNotFoundError, OSError):pass- await self._write(+ await self._backend.write_file(path,existing + ("\n".join(lines) + "\n").encode("utf-8"),)@@ -730,8 +746,11 @@ class DockerWorkspace(WorkspaceBase):f"media_type='{block.source.media_type}'/>",)- await self._exec(f"mkdir -p {shlex.quote(base)}")- await self._write(path, "".join(parts).encode("utf-8"))+ await self._backend.exec_shell(["mkdir", "-p", base])+ await self._backend.write_file(+ path,+ "".join(parts).encode("utf-8"),+ )return path# ── internals: image build ──────────────────────────────────@@ -880,13 +899,20 @@ class DockerWorkspace(WorkspaceBase):)self._port_mapping[self.gateway_port] = int(bindings[0]["HostPort"])+ # Create the backend now that the container is running. All+ # subsequent container I/O in this workspace goes through it.+ self._backend = DockerBackend(self._container, CONTAINER_WORKDIR)+# Ensure the in-container persistence dirs exist (also makes a# newly-bind-mounted host workdir agentscope-shaped on first use).- await self._exec(- "mkdir -p "- f"{shlex.quote(CONTAINER_DATA_DIR)} "- f"{shlex.quote(CONTAINER_SKILLS_DIR)} "- f"{shlex.quote(CONTAINER_SESSIONS_DIR)}",+ await self._backend.exec_shell(+ [+ "mkdir",+ "-p",+ CONTAINER_DATA_DIR,+ CONTAINER_SKILLS_DIR,+ CONTAINER_SESSIONS_DIR,+ ],)async def _restore_or_seed_mcps(self) -> list[MCPClient]:@@ -960,8 +986,10 @@ class DockerWorkspace(WorkspaceBase):"token": self._gateway_token,"servers": [m.model_dump(mode="json") for m in self._mcps],}- await self._exec(f"mkdir -p {shlex.quote(GATEWAY_HOME)}")- await self._write(+ await self._backend.exec_shell(+ ["mkdir", "-p", GATEWAY_HOME],+ )+ await self._backend.write_file(GATEWAY_CONFIG,json.dumps(cfg, indent=2, ensure_ascii=False).encode("utf-8"),)@@ -988,7 +1016,7 @@ class DockerWorkspace(WorkspaceBase):f"> {shlex.quote(GATEWAY_LOG)} 2>&1 &")# Detach: we don't await stream completion, just kick it off.- await self._exec(cmd)+ await self._backend.exec_shell(["sh", "-c", cmd])async def _wait_for_gateway(self, timeout: float = 30.0) -> None:"""Block until the gateway answers ``/health`` with 200.@@ -1015,7 +1043,7 @@ class DockerWorkspace(WorkspaceBase):delay = min(delay * 1.5, 1.0)# Last-ditch: dump the gateway log to help debug startup failures.try:- log = await self._read(GATEWAY_LOG)+ log = await self._backend.read_file(GATEWAY_LOG)tail = log[-2000:].decode(errors="replace")except Exception:tail = "<no gateway log available>"@@ -1056,153 +1084,6 @@ class DockerWorkspace(WorkspaceBase):e,)- # ── internals: container I/O ────────────────────────────────-- async def _exec(- self,- command: str,- *,- timeout: float | None = None,- ) -> _ExecResult:- """Run ``sh -c <command>`` inside the container.-- The exec stream is consumed entirely so that ``stdout`` /- ``stderr`` capture both stream channels in order. The- container's ``CONTAINER_WORKDIR`` is used as the working- directory.-- Args:- command: Shell command string. Caller is responsible for- quoting via :func:`shlex.quote`.- timeout: Maximum seconds to wait for completion. ``None``- waits indefinitely; on timeout an- :class:`_ExecResult` with ``exit_code=-1`` and- ``stderr=b"timed out"`` is returned (no exception).-- Returns:- The captured exit code and IO streams.- """-- async def _run() -> _ExecResult:- exec_obj = await self._container.exec(- cmd=["sh", "-c", command],- workdir=CONTAINER_WORKDIR,- )- stdout: list[bytes] = []- stderr: list[bytes] = []- # ``exec_obj.start()`` returns aiodocker's ``Stream``- # object — an async context manager wrapping a- # persistent HTTP/1.1-Upgrade connection to the docker- # daemon. Drain it with ``read_out()``: each call yields- # a ``Message(stream=int, data=bytes)`` (channel 1 =- # stdout, channel 2 = stderr), or ``None`` at EOF when- # the exec process exits. ``async with`` is required —- # without it the underlying ``ClientResponse`` is leaked- # and asyncio logs ``Unclosed response`` at GC time,- # which on a closed event loop manifests as ``Event loop- # is closed`` errors during pytest teardown.- async with exec_obj.start() as stream:- while True:- msg = await stream.read_out()- if msg is None:- break- if msg.stream == 1:- stdout.append(msg.data)- else:- stderr.append(msg.data)- inspect = await exec_obj.inspect()- code = inspect.get("ExitCode", -1)- if code is None:- code = -1- return _ExecResult(- exit_code=int(code),- stdout=b"".join(stdout),- stderr=b"".join(stderr),- )-- if timeout is None:- return await _run()- try:- return await asyncio.wait_for(_run(), timeout=timeout)- except asyncio.TimeoutError:- return _ExecResult(- exit_code=-1,- stdout=b"",- stderr=b"timed out",- )-- async def _read(self, path: str) -> bytes:- """Fetch a file from the container as raw bytes.-- Uses ``get_archive`` (tarfile stream) and extracts the first- regular member. Compatible with the two stream shapes that- aiodocker emits (sync ``dict`` payload or async chunk stream).-- Args:- path: Absolute container-side path of the file to read.-- Returns:- The file contents.-- Raises:- FileNotFoundError: If the path does not exist in the- container, or if the tar stream contains no regular- file at that path.- """-- from aiodocker import exceptions as aiodocker_exceptions-- try:- # ``get_archive`` returns an already-parsed- # :class:`tarfile.TarFile` (the daemon serves the file- # entry as a tar stream, aiodocker drains it into memory- # for us). Iterate members and return the first regular- # file's bytes.- tar = await self._container.get_archive(path)- except aiodocker_exceptions.DockerError as exc:- # The daemon answers with 404 + ``"Could not find the file- # ... in container ..."`` when ``path`` is missing.- # Translate that to ``FileNotFoundError`` so callers can- # use the standard exception type instead of leaking the- # aiodocker-specific class.- if exc.status == 404:- raise FileNotFoundError(- f"not found in container: {path}",- ) from exc- raise-- try:- for member in tar.getmembers():- if member.isfile():- f = tar.extractfile(member)- if f:- return f.read()- finally:- tar.close()- raise FileNotFoundError(f"not found in container: {path}")-- async def _write(self, path: str, data: bytes) -> None:- """Write raw bytes to a file inside the container.-- Creates the parent directory with ``mkdir -p`` first, then- uploads a single-entry tar via ``put_archive``. Overwrites- an existing file at the same path.-- Args:- path: Absolute container-side destination path.- data: Raw file contents.- """- parent = posixpath.dirname(path) or "/"- name = posixpath.basename(path)-- await self._exec(f"mkdir -p {shlex.quote(parent)}")- buf = io.BytesIO()- with tarfile.open(fileobj=buf, mode="w") as tf:- info = tarfile.TarInfo(name=name)- info.size = len(data)- tf.addfile(info, io.BytesIO(data))- await self._container.put_archive(parent, buf.getvalue())-# ── internals: data offload ────────────────────────────────async def _offload_data_block(self, block: DataBlock) -> DataBlock:@@ -1228,8 +1109,13 @@ class DockerWorkspace(WorkspaceBase):h = hashlib.sha256(block.source.data.encode()).hexdigest()ext = mimetypes.guess_extension(block.source.media_type) or ".bin"path = f"{CONTAINER_DATA_DIR}/{h}{ext}"- await self._exec(f"mkdir -p {shlex.quote(CONTAINER_DATA_DIR)}")- await self._write(path, base64.b64decode(block.source.data))+ await self._backend.exec_shell(+ ["mkdir", "-p", CONTAINER_DATA_DIR],+ )+ await self._backend.write_file(+ path,+ base64.b64decode(block.source.data),+ )return DataBlock(id=block.id,name=block.name,diff --git a/src/agentscope/workspace/_docker/_make_dockerfile.py b/src/agentscope/workspace/_docker/_make_dockerfile.pyindex e60b005a5..332c2eb9b 100644--- a/src/agentscope/workspace/_docker/_make_dockerfile.py+++ b/src/agentscope/workspace/_docker/_make_dockerfile.py@@ -40,6 +40,7 @@ from .._utils import (_is_released_install,_is_source_ignored,_read_gateway_script_bytes,+ _read_glob_helper_bytes,)# ── shared constants (also imported by _docker_workspace) ──────────@@ -63,6 +64,8 @@ GATEWAY_LOG = f"{GATEWAY_HOME}/gateway.log"# pulls in skill/tool/local_workspace/docker_workspace and their heavy# transitive dependencies).GATEWAY_SCRIPT = f"{GATEWAY_HOME}/_mcp_gateway_app.py"+# Standalone glob helper script used by the Glob builtin tool.+GLOB_HELPER_SCRIPT = f"{GATEWAY_HOME}/_glob_helper.py"IMAGE_REPO = "agentscope-workspace"@@ -240,15 +243,16 @@ def prepare_build_context()requirements_text = _render_requirements(extra_pip_list)- # Read the gateway script bytes once — we both hash them into the- # image tag (so script edits invalidate the image cache) and write- # them into the build context so the Dockerfile can ``COPY`` them- # to ``GATEWAY_SCRIPT``.+ # Read helper scripts once — we both hash them into the image tag+ # (so edits invalidate the image cache) and write them into the+ # build context so the Dockerfile can ``COPY`` them.gateway_script_bytes = _read_gateway_script_bytes()+ glob_helper_bytes = _read_glob_helper_bytes()copy_files: dict[str, bytes] = {"requirements.txt": requirements_text.encode("utf-8"),"_mcp_gateway_app.py": gateway_script_bytes,+ "_glob_helper.py": glob_helper_bytes,}if source_root is not None:# Synthetic entry: the directory tree is too large to inline, so we@@ -264,6 +268,7 @@ def prepare_build_context(copy_files["requirements.txt"],)(ctx_dir / "_mcp_gateway_app.py").write_bytes(gateway_script_bytes)+ (ctx_dir / "_glob_helper.py").write_bytes(glob_helper_bytes)if source_root is not None:shutil.copytree(source_root,diff --git a/src/agentscope/workspace/_e2b/__init__.py b/src/agentscope/workspace/_e2b/__init__.pyindex ebd7f7b77..56f8f582e 100644--- a/src/agentscope/workspace/_e2b/__init__.py+++ b/src/agentscope/workspace/_e2b/__init__.py@@ -7,6 +7,6 @@ poke at the underlying module layout."""from ._e2b_workspace import E2BWorkspace+from ._e2b_backend import E2BBackend--__all__ = ["E2BWorkspace"]+__all__ = ["E2BWorkspace", "E2BBackend"]diff --git a/src/agentscope/workspace/_e2b/_bootstrap.py b/src/agentscope/workspace/_e2b/_bootstrap.pyindex 1a57c451d..84405d776 100644--- a/src/agentscope/workspace/_e2b/_bootstrap.py+++ b/src/agentscope/workspace/_e2b/_bootstrap.py@@ -38,7 +38,6 @@ from .._utils import (_is_source_ignored,)-# ── shared constants ───────────────────────────────────────────────#: Default E2B template. Matches the SDK's ``base`` template — has@@ -68,6 +67,8 @@ GATEWAY_HOME = f"{SANDBOX_USER_HOME}/.agentscope"GATEWAY_VENV = f"{GATEWAY_HOME}/.venv"GATEWAY_VENV_PY = f"{GATEWAY_VENV}/bin/python"GATEWAY_SCRIPT = f"{GATEWAY_HOME}/_mcp_gateway_app.py"+# Standalone glob helper script used by the builtin Glob tool.+GLOB_HELPER_SCRIPT = f"{GATEWAY_HOME}/_glob_helper.py"GATEWAY_CONFIG = f"{GATEWAY_HOME}/gateway.config.json"GATEWAY_LOG = f"{GATEWAY_HOME}/gateway.log"@@ -81,8 +82,11 @@ UV_BIN = f"{SANDBOX_USER_HOME}/.local/bin/uv"METADATA_WORKSPACE_ID_KEY = "agentscope.workspace.id"#: Tarball drop point for dev-mode ``agentscope`` source uploads.-DEV_SRC_TAR = "/tmp/agentscope_src.tar"-DEV_SRC_DIR = "/tmp/agentscope_src"+#: Lives under ``GATEWAY_HOME`` (user-owned) instead of ``/tmp``+#: because the E2B ``files.write`` API runs as ``user`` and ``/tmp``+#: can have restrictive permissions after a sandbox pause/resume cycle.+DEV_SRC_TAR = f"{GATEWAY_HOME}/agentscope_src.tar"+DEV_SRC_DIR = f"{GATEWAY_HOME}/agentscope_src"# ── source tarball (dev mode only) ─────────────────────────────────@@ -146,7 +150,13 @@ def bootstrap_commands(# the command idempotent in case bootstrap is re-run.f"mkdir -p {SANDBOX_DATA_DIR} {SANDBOX_SKILLS_DIR} "f"{SANDBOX_SESSIONS_DIR} {GATEWAY_HOME}",- # 2. Astral uv — same shell installer as Docker. The base E2B+ # 2. Install ripgrep for the Grep builtin tool. The base E2B+ # image runs as non-root, so we use sudo. ``apt-get update``+ # + install is idempotent — safe to re-run on resume.+ "sudo apt-get update -qq "+ "&& sudo apt-get install -y --no-install-recommends ripgrep "+ "&& sudo rm -rf /var/lib/apt/lists/*",+ # 3. Astral uv — same shell installer as Docker. The base E2B# image already ships ``curl``; we land uv at# ``$HOME/.local/bin`` since the sandbox user has no sudo by# default. ``INSTALLER_NO_MODIFY_PATH=1`` suppresses shell@@ -154,10 +164,10 @@ def bootstrap_commands(f"curl -LsSf https://astral.sh/uv/install.sh "f"| env UV_INSTALL_DIR={SANDBOX_USER_HOME}/.local/bin "f"INSTALLER_NO_MODIFY_PATH=1 sh",- # 3. Gateway venv + base requirements.+ # 4. Gateway venv + base requirements.f"{UV_BIN} venv {GATEWAY_VENV}",f"{UV_BIN} pip install --python {GATEWAY_VENV_PY} {pip_args}",- # 4. agentscope itself (mode-dependent).+ # 5. agentscope itself (mode-dependent).install_agentscope_cmd,]diff --git a/src/agentscope/workspace/_e2b/_e2b_backend.py b/src/agentscope/workspace/_e2b/_e2b_backend.pynew file mode 100644index 000000000..0794507db--- /dev/null+++ b/src/agentscope/workspace/_e2b/_e2b_backend.py@@ -0,0 +1,150 @@+# -*- coding: utf-8 -*-+"""E2B sandbox :class:`BackendBase` implementation.++Wraps the E2B SDK's ``commands.run`` and ``files.*`` APIs into the+three backend primitives (``exec_shell``, ``read_file``,+``write_file``) so that builtin tools (Bash, Read, Write, Edit, Grep,+Glob) can operate inside an E2B cloud sandbox transparently. All+derived filesystem helpers (``file_exists``, ``is_dir``, ``list_dir``,+``stat_mtime``, ``delete_path``) are inherited from+:class:`BackendBase`, which implements them via ``exec_shell``.+"""++from __future__ import annotations++import posixpath+import shlex+from typing import Any++from ...tool import BackendBase, ExecResult+++class E2BBackend(BackendBase):+ """Backend that delegates to a running E2B sandbox.++ Only the three abstract primitives (``exec_shell``, ``read_file``,+ ``write_file``) are implemented here; the derived filesystem helpers+ are inherited from :class:`BackendBase`.++ Args:+ sandbox (`Any`):+ An ``e2b.AsyncSandbox`` object (must already be started /+ connected).+ workdir (`str`):+ Default working directory for ``exec_shell`` calls inside+ the sandbox.+ """++ def __init__(self, sandbox: Any, workdir: str) -> None:+ """Initialize the E2B backend.++ Args:+ sandbox (`Any`):+ A started / connected ``e2b.AsyncSandbox`` object.+ workdir (`str`):+ Default working directory for ``exec_shell`` calls+ inside the sandbox.+ """+ self._sandbox = sandbox+ self._workdir = workdir++ # ── exec ───────────────────────────────────────────────────────++ async def exec_shell(+ self,+ command: list[str],+ *,+ cwd: str | None = None,+ timeout: float | None = None,+ ) -> ExecResult:+ """Run a program inside the sandbox via ``commands.run``.++ *command* is an argv list. The E2B ``commands.run`` API takes a+ single shell command line, so the argv is POSIX-quoted back into+ a string before dispatch (the sandbox is always Linux). Callers+ needing shell features pass ``["sh", "-c", line]``.++ Args:+ command (`list[str]`):+ Executable path/name followed by its arguments.+ cwd (`str | None`, optional):+ Working directory inside the sandbox. When ``None`` the+ backend's default ``workdir`` is used.+ timeout (`float | None`, optional):+ Maximum number of seconds to wait. When ``None`` the+ SDK default applies.++ Returns:+ `ExecResult`:+ The captured exit code, stdout, and stderr. A non-zero+ command exit is reported as a normal result; transport+ errors yield an ``exit_code`` of ``-1``.+ """+ from e2b import CommandExitException++ command_line = " ".join(shlex.quote(arg) for arg in command)+ kwargs: dict[str, Any] = {"cwd": cwd or self._workdir}+ if timeout is not None:+ kwargs["timeout"] = timeout+ try:+ res = await self._sandbox.commands.run(command_line, **kwargs)+ return ExecResult(+ exit_code=int(res.exit_code or 0),+ stdout=(res.stdout or "").encode("utf-8"),+ stderr=(res.stderr or "").encode("utf-8"),+ )+ except CommandExitException as e:+ return ExecResult(+ exit_code=int(e.exit_code or 1),+ stdout=(e.stdout or "").encode("utf-8"),+ stderr=(e.stderr or "").encode("utf-8"),+ )+ except Exception as e: # noqa: BLE001+ return ExecResult(+ exit_code=-1,+ stdout=b"",+ stderr=str(e).encode("utf-8"),+ )++ # ── file I/O ───────────────────────────────────────────────────++ async def read_file(self, path: str) -> bytes:+ """Read a file from the sandbox via ``files.read``.++ Args:+ path (`str`):+ Path to the file inside the sandbox.++ Returns:+ `bytes`:+ The raw file contents.++ Raises:+ `FileNotFoundError`:+ If the path does not exist inside the sandbox.+ """+ from e2b import FileNotFoundException++ try:+ data = await self._sandbox.files.read(path, format="bytes")+ except FileNotFoundException as exc:+ raise FileNotFoundError(+ f"not found in sandbox: {path}",+ ) from exc+ return bytes(data)++ async def write_file(self, path: str, data: bytes) -> None:+ """Write *data* to a file inside the sandbox.++ Creates parent directories via ``exec_shell`` first.++ Args:+ path (`str`):+ Destination path inside the sandbox.+ data (`bytes`):+ The raw bytes to write.+ """+ parent = posixpath.dirname(path)+ if parent:+ await self.exec_shell(["mkdir", "-p", parent])+ await self._sandbox.files.write(path, data)diff --git a/src/agentscope/workspace/_e2b/_e2b_workspace.py b/src/agentscope/workspace/_e2b/_e2b_workspace.pyindex bec916049..e5f30119a 100644--- a/src/agentscope/workspace/_e2b/_e2b_workspace.py+++ b/src/agentscope/workspace/_e2b/_e2b_workspace.py@@ -44,7 +44,6 @@ import posixpathimport shleximport uuidfrom copy import deepcopy-from dataclasses import dataclassfrom typing import Anyfrom pydantic import AnyUrl@@ -66,6 +65,12 @@ from .._gateway_client import (GatewayClient,GatewayMCPClient,)+from .._utils import (+ _agentscope_version,+ _is_released_install,+ _read_gateway_script_bytes,+ _read_glob_helper_bytes,+)from ._bootstrap import (DEFAULT_GATEWAY_PORT,DEFAULT_TEMPLATE,@@ -76,6 +81,7 @@ from ._bootstrap import (GATEWAY_LOG,GATEWAY_SCRIPT,GATEWAY_VENV_PY,+ GLOB_HELPER_SCRIPT,METADATA_WORKSPACE_ID_KEY,SANDBOX_DATA_DIR,SANDBOX_MCP_FILE,@@ -88,12 +94,7 @@ from ._bootstrap import (render_install_agentscope_cmd_dev,render_install_agentscope_cmd_released,)-from .._utils import (- _agentscope_version,- _is_released_install,- _read_gateway_script_bytes,-)-+from ._e2b_backend import E2BBackend_DEFAULT_INSTRUCTIONS = """<workspace>You have an E2B-based cloud workspace. All tool calls execute **inside@@ -113,30 +114,6 @@ and processes.</workspace>"""-# ── small helpers ──────────────────────────────────────────────────---@dataclass(frozen=True, slots=True)-class _ExecResult:- """Result of running a command inside the sandbox via ``commands.run``.-- Attributes:- exit_code: Process exit code from the sandbox. ``-1`` indicates- the SDK raised before producing a result (e.g. timeout or- connection error captured in :attr:`stderr`).- stdout: Captured stdout as raw bytes.- stderr: Captured stderr as raw bytes.- """-- exit_code: int- stdout: bytes- stderr: bytes-- def ok(self) -> bool:- """Return ``True`` iff the command exited with code ``0``."""- return self.exit_code == 0--# ── the workspace ──────────────────────────────────────────────────@@ -228,6 +205,7 @@ class E2BWorkspace(WorkspaceBase):# ── runtime state ───────────────────────────────────────self._sandbox: Any = None # e2b.AsyncSandbox+ self._backend: E2BBackend | None = Noneself._gateway: GatewayClient | None = Noneself._gateway_token: str = ""self._mcps: list[MCPClient] = []@@ -273,19 +251,22 @@ class E2BWorkspace(WorkspaceBase):returnawait self._attach_or_create_sandbox()+ self._backend = E2BBackend(self._sandbox, workdir=SANDBOX_WORKDIR)# If the gateway script is missing, the sandbox is fresh (or# a prior bootstrap was interrupted). Re-running bootstrap is# safe because every step is idempotent (mkdir -p, uv venv,# uv pip install).if not await self._sandbox.files.exists(GATEWAY_SCRIPT):- # ``_exec`` pins ``cwd=SANDBOX_WORKDIR`` so the very first- # bootstrap command (which itself is ``mkdir -p``) would- # fail before it ran when the dir does not yet exist.- # Create it directly via the SDK with no cwd to break the- # chicken-and-egg.- await self._sandbox.commands.run(- f"mkdir -p {shlex.quote(SANDBOX_WORKDIR)}",+ # The backend pins ``cwd=SANDBOX_WORKDIR`` so the very+ # first bootstrap command (which itself is ``mkdir -p``)+ # would fail before it ran when the dir does not yet+ # exist. Use ``cwd="/"`` to break the chicken-and-egg —+ # ``mkdir -p`` itself never fails on an already-existing+ # directory.+ await self._backend.exec_shell(+ ["mkdir", "-p", SANDBOX_WORKDIR],+ cwd="/",)await self._run_bootstrap()@@ -297,8 +278,8 @@ class E2BWorkspace(WorkspaceBase):# init mints a new bearer token, so an old gateway listening# on the port would happily accept old-token requests but# reject new ones — kill it before starting the new one.- await self._exec(- "pkill -f _mcp_gateway_app.py || true",+ await self._backend.exec_shell(+ ["sh", "-c", "pkill -f _mcp_gateway_app.py || true"],)await self._write_gateway_config()@@ -337,6 +318,13 @@ class E2BWorkspace(WorkspaceBase):sandbox. The gateway process keeps running with no upstreamMCPs. ``default_mcps`` / ``skill_paths`` are not re-seeded."""+ if self._backend is None:+ raise RuntimeError(+ "E2BWorkspace is not initialized: its sandbox backend "+ "is unavailable. Use 'async with workspace:' or call "+ "'await workspace.initialize()' before 'reset()'.",+ )+async with self._mcp_lock, self._skill_lock:for gw_client in list(self._gateway_clients.values()):try:@@ -350,14 +338,12 @@ class E2BWorkspace(WorkspaceBase):self._gateway_clients.clear()self._mcps = []- paths = [+ for path in (SANDBOX_SESSIONS_DIR,SANDBOX_DATA_DIR,SANDBOX_SKILLS_DIR,- ]- await self._exec(- "rm -rf " + " ".join(shlex.quote(p) for p in paths),- )+ ):+ await self._backend.delete_path(path)# Rewrite ``.mcp`` to an empty list so a future restart does# not fall back to ``default_mcps``.@@ -388,6 +374,7 @@ class E2BWorkspace(WorkspaceBase):except Exception as e:logger.warning("E2BWorkspace: pause failed: %s", e)self._sandbox = None+ self._backend = Noneself.is_alive = False@@ -405,8 +392,37 @@ class E2BWorkspace(WorkspaceBase):# ── tool / MCP / skill discovery ────────────────────────────async def list_tools(self) -> list[ToolBase]:- """No built-in tools — every tool reaches the agent via MCP."""- return []+ """Built-in tools backed by the E2B sandbox.++ Returns the six builtin tools (Bash, Read, Write, Edit, Grep,+ Glob), each backed by the workspace's :class:`E2BBackend`+ that executes inside the sandbox.++ Raises:+ `RuntimeError`:+ If the workspace has not been initialized yet (the+ sandbox-backed backend is unavailable). Without this+ guard the builtin tools would silently fall back to a+ :class:`LocalBackend` and run on the host instead of+ inside the sandbox.+ """+ if self._backend is None:+ raise RuntimeError(+ "E2BWorkspace is not initialized: its sandbox backend "+ "is unavailable. Use 'async with workspace:' or call "+ "'await workspace.initialize()' before 'list_tools()'.",+ )++ from ...tool._builtin import Bash, Edit, Glob, Grep, Read, Write++ return [+ Bash(cwd=SANDBOX_WORKDIR, backend=self._backend),+ Edit(backend=self._backend),+ Glob(backend=self._backend, glob_helper_path=GLOB_HELPER_SCRIPT),+ Grep(backend=self._backend),+ Read(backend=self._backend),+ Write(backend=self._backend),+ ]async def list_mcps(self) -> list[MCPClient]:"""Return one :class:`GatewayMCPClient` per registered MCP.@@ -426,9 +442,13 @@ class E2BWorkspace(WorkspaceBase):"""import frontmatter as fm- result = await self._exec(- f"find {SANDBOX_SKILLS_DIR} -name SKILL.md "- f"2>/dev/null || true",+ result = await self._backend.exec_shell(+ [+ "sh",+ "-c",+ f"find {SANDBOX_SKILLS_DIR} -name SKILL.md "+ f"2>/dev/null || true",+ ],)if not result.ok():return []@@ -441,7 +461,7 @@ class E2BWorkspace(WorkspaceBase):if not md_path:continuetry:- raw = await self._read(md_path)+ raw = await self._backend.read_file(md_path)doc = fm.loads(raw.decode("utf-8"))name = doc.get("name")desc = doc.get("description")@@ -516,11 +536,13 @@ class E2BWorkspace(WorkspaceBase):)async with self._skill_lock:- await self._exec(f"mkdir -p {SANDBOX_SKILLS_DIR}")+ await self._backend.exec_shell(+ ["mkdir", "-p", SANDBOX_SKILLS_DIR],+ )dir_name = os.path.basename(os.path.abspath(skill_path))- check = await self._exec(- f"test -e {shlex.quote(SANDBOX_SKILLS_DIR + '/' + dir_name)}",+ check = await self._backend.exec_shell(+ ["test", "-e", SANDBOX_SKILLS_DIR + "/" + dir_name],)if check.ok():raise ValueError(@@ -535,7 +557,7 @@ class E2BWorkspace(WorkspaceBase):remote = f"{SANDBOX_SKILLS_DIR}/{dir_name}/{rel}"with open(local, "rb") as f:data = f.read()- await self._sandbox.files.write(remote, data)+ await self._backend.write_file(remote, data)logger.info("E2BWorkspace: added skill %r at %s/%s",@@ -557,12 +579,7 @@ class E2BWorkspace(WorkspaceBase):raise KeyError(f"Skill {name!r} not found. Available: {available}",)- result = await self._exec(f"rm -rf {shlex.quote(target_dir)}")- if not result.ok():- raise RuntimeError(- f"Failed to remove skill {name!r}: "- f"{result.stderr.decode(errors='replace')}",- )+ await self._backend.delete_path(target_dir)# ── offload ─────────────────────────────────────────────────@@ -596,13 +613,13 @@ class E2BWorkspace(WorkspaceBase):msg.content = contentlines.append(msg.model_dump_json())- await self._exec(f"mkdir -p {shlex.quote(base)}")+ await self._backend.exec_shell(["mkdir", "-p", base])existing = b""try:- existing = await self._read(path)+ existing = await self._backend.read_file(path)except FileNotFoundError:pass- await self._sandbox.files.write(+ await self._backend.write_file(path,existing + ("\n".join(lines) + "\n").encode("utf-8"),)@@ -635,8 +652,8 @@ class E2BWorkspace(WorkspaceBase):f"media_type='{block.source.media_type}'/>",)- await self._exec(f"mkdir -p {shlex.quote(base)}")- await self._sandbox.files.write(+ await self._backend.exec_shell(["mkdir", "-p", base])+ await self._backend.write_file(path,"".join(parts).encode("utf-8"),)@@ -805,7 +822,7 @@ class E2BWorkspace(WorkspaceBase):else:log_bootstrap_attempt(self.workspace_id, "dev")tar_bytes = build_source_tarball()- await self._sandbox.files.write(DEV_SRC_TAR, tar_bytes)+ await self._backend.write_file(DEV_SRC_TAR, tar_bytes)install_cmd = render_install_agentscope_cmd_dev()commands = bootstrap_commands(@@ -813,7 +830,10 @@ class E2BWorkspace(WorkspaceBase):install_agentscope_cmd=install_cmd,)for cmd in commands:- r = await self._exec(cmd, timeout=600.0)+ r = await self._backend.exec_shell(+ ["sh", "-c", cmd],+ timeout=600.0,+ )if not r.ok():raise RuntimeError(f"E2BWorkspace bootstrap failed (exit {r.exit_code}) "@@ -822,9 +842,15 @@ class E2BWorkspace(WorkspaceBase):f"stdout: {r.stdout.decode(errors='replace')}",)+ # Upload helper scripts used by builtin tools.+ await self._backend.write_file(+ GLOB_HELPER_SCRIPT,+ _read_glob_helper_bytes(),+ )+# Upload the gateway script last so its presence is the# idempotency marker we probe in :meth:`initialize`.- await self._sandbox.files.write(+ await self._backend.write_file(GATEWAY_SCRIPT,_read_gateway_script_bytes(),)@@ -840,7 +866,7 @@ class E2BWorkspace(WorkspaceBase):``default_mcps``."""try:- raw = await self._read(SANDBOX_MCP_FILE)+ raw = await self._backend.read_file(SANDBOX_MCP_FILE)except FileNotFoundError:return list(self.default_mcps)try:@@ -866,8 +892,10 @@ class E2BWorkspace(WorkspaceBase):ensure_ascii=False,)try:- await self._exec(f"mkdir -p {shlex.quote(SANDBOX_WORKDIR)}")- await self._sandbox.files.write(+ await self._backend.exec_shell(+ ["mkdir", "-p", SANDBOX_WORKDIR],+ )+ await self._backend.write_file(SANDBOX_MCP_FILE,payload.encode("utf-8"),)@@ -884,8 +912,10 @@ class E2BWorkspace(WorkspaceBase):"token": self._gateway_token,"servers": [m.model_dump(mode="json") for m in self._mcps],}- await self._exec(f"mkdir -p {shlex.quote(GATEWAY_HOME)}")- await self._sandbox.files.write(+ await self._backend.exec_shell(+ ["mkdir", "-p", GATEWAY_HOME],+ )+ await self._backend.write_file(GATEWAY_CONFIG,json.dumps(cfg, indent=2, ensure_ascii=False).encode("utf-8"),)@@ -899,7 +929,7 @@ class E2BWorkspace(WorkspaceBase):f"--port {self.gateway_port} "f"> {shlex.quote(GATEWAY_LOG)} 2>&1 &")- await self._exec(cmd)+ await self._backend.exec_shell(["sh", "-c", cmd])async def _wait_for_gateway(self, timeout: float = 30.0) -> None:"""Block until the gateway answers ``/health`` with 200."""@@ -912,7 +942,7 @@ class E2BWorkspace(WorkspaceBase):await asyncio.sleep(delay)delay = min(delay * 1.5, 1.0)try:- log = await self._read(GATEWAY_LOG)+ log = await self._backend.read_file(GATEWAY_LOG)tail = log[-2000:].decode(errors="replace")except Exception:tail = "<no gateway log available>"@@ -930,8 +960,13 @@ class E2BWorkspace(WorkspaceBase):"""if not self.skill_paths:return- listing = await self._exec(- f"ls -A {shlex.quote(SANDBOX_SKILLS_DIR)} 2>/dev/null || true",+ listing = await self._backend.exec_shell(+ [+ "sh",+ "-c",+ f"ls -A {shlex.quote(SANDBOX_SKILLS_DIR)} "+ f"2>/dev/null || true",+ ],)if listing.ok() and listing.stdout.strip():return@@ -945,66 +980,6 @@ class E2BWorkspace(WorkspaceBase):e,)- # ── internals: sandbox I/O ──────────────────────────────────-- async def _exec(- self,- command: str,- *,- timeout: float | None = None,- ) -> _ExecResult:- """Run ``sh -c <command>`` inside the sandbox via the SDK.-- ``commands.run`` raises :class:`CommandExitException` on- non-zero exit by default; we catch it and translate into the- same :class:`_ExecResult` shape Docker uses, so callers can do- ``if not r.ok(): ...`` consistently. Other SDK errors also- come back as a non-zero ``_ExecResult`` rather than bubbling up- — long-running ``mkdir -p`` and ``find`` calls should never- crash the workspace.- """- from e2b import CommandExitException-- kwargs: dict[str, Any] = {"cwd": SANDBOX_WORKDIR}- if timeout is not None:- kwargs["timeout"] = timeout- try:- res = await self._sandbox.commands.run(command, **kwargs)- return _ExecResult(- exit_code=int(res.exit_code or 0),- stdout=(res.stdout or "").encode("utf-8"),- stderr=(res.stderr or "").encode("utf-8"),- )- except CommandExitException as e:- return _ExecResult(- exit_code=int(e.exit_code or 1),- stdout=(e.stdout or "").encode("utf-8"),- stderr=(e.stderr or "").encode("utf-8"),- )- except Exception as e: # noqa: BLE001- return _ExecResult(- exit_code=-1,- stdout=b"",- stderr=str(e).encode("utf-8"),- )-- async def _read(self, path: str) -> bytes:- """Read a file from the sandbox.-- Translates the SDK's ``FileNotFoundException`` into the stdlib- ``FileNotFoundError`` so callers can use the standard- exception type (matching :meth:`DockerWorkspace._read`).- """- from e2b import FileNotFoundException-- try:- data = await self._sandbox.files.read(path, format="bytes")- except FileNotFoundException as exc:- raise FileNotFoundError(- f"not found in sandbox: {path}",- ) from exc- return bytes(data)-# ── internals: data offload ────────────────────────────────async def _offload_data_block(self, block: DataBlock) -> DataBlock:@@ -1020,8 +995,10 @@ class E2BWorkspace(WorkspaceBase):h = hashlib.sha256(block.source.data.encode()).hexdigest()ext = mimetypes.guess_extension(block.source.media_type) or ".bin"path = f"{SANDBOX_DATA_DIR}/{h}{ext}"- await self._exec(f"mkdir -p {shlex.quote(SANDBOX_DATA_DIR)}")- await self._sandbox.files.write(+ await self._backend.exec_shell(+ ["mkdir", "-p", SANDBOX_DATA_DIR],+ )+ await self._backend.write_file(path,base64.b64decode(block.source.data),)diff --git a/src/agentscope/workspace/_local_workspace.py b/src/agentscope/workspace/_local_workspace.pyindex 7e9cf71c8..aadb5c626 100644--- a/src/agentscope/workspace/_local_workspace.py+++ b/src/agentscope/workspace/_local_workspace.py@@ -1,5 +1,6 @@# -*- coding: utf-8 -*-"""The local workspace class."""+import asyncioimport base64import hashlib@@ -12,32 +13,31 @@ from copy import deepcopyfrom pathlib import Pathfrom typing import TypedDict-import aiofiles-import aiofiles.ospathimport frontmatterfrom pydantic import AnyUrl-from ._base import WorkspaceBase+from .._logging import loggerfrom ..mcp import MCPClientfrom ..message import (- TextBlock,+ Base64Source,DataBlock,- ToolResultBlock,Msg,+ TextBlock,+ ToolResultBlock,URLSource,- Base64Source,)from ..skill import Skillfrom ..tool import (- ToolBase,Bash,Edit,Glob,Grep,Read,+ ToolBase,Write,)-from .._logging import logger+from ..tool._builtin._backend import LocalBackend+from ._base import WorkspaceBaseclass _SkillEntry(TypedDict):@@ -170,6 +170,7 @@ class LocalWorkspace(WorkspaceBase):self.skill_paths: list[str] = list(skill_paths or [])# ── runtime state ───────────────────────────────────────+ self._backend = LocalBackend()self._mcps: list[MCPClient] = []self._skill_lock = asyncio.Lock()@@ -191,18 +192,18 @@ class LocalWorkspace(WorkspaceBase):# Restore or seed MCPsmcp_file = os.path.join(self.workdir, ".mcp")- if await aiofiles.ospath.exists(mcp_file):- async with aiofiles.open(mcp_file, "r", encoding="utf-8") as f:- raw_list = json.loads(await f.read())- for m in raw_list:- try:- self._mcps.append(MCPClient.model_validate(m))- except Exception as e:- logger.warning(- "Skipping invalid MCP entry '%s': %s",- m.get("name", "?"),- e,- )+ if await self._backend.file_exists(mcp_file):+ raw = await self._backend.read_file(mcp_file)+ raw_list = json.loads(raw.decode("utf-8"))+ for m in raw_list:+ try:+ self._mcps.append(MCPClient.model_validate(m))+ except Exception as e:+ logger.warning(+ "Skipping invalid MCP entry '%s': %s",+ m.get("name", "?"),+ e,+ )else:self._mcps = list(self.default_mcps)await self._save_mcp_file()@@ -313,8 +314,9 @@ class LocalWorkspace(WorkspaceBase):if updated:skills_file["skills"] = existing- skills_file["skills_dir_mtime"] = await aiofiles.ospath.getmtime(- skills_dir,+ mtime = await self._backend.stat_mtime(skills_dir)+ skills_file["skills_dir_mtime"] = (+ mtime if mtime is not None else 0.0)await self._save_skills_file(skills_dir, skills_file)@@ -334,12 +336,12 @@ class LocalWorkspace(WorkspaceBase):`_SkillsFile`: The parsed index, or a fresh empty structure."""path = os.path.join(skills_dir, ".skills")- if not await aiofiles.ospath.exists(path):+ if not await self._backend.file_exists(path):return {"skills_dir_mtime": 0.0, "skills": {}}try:- async with aiofiles.open(path, "r", encoding="utf-8") as f:- data = json.loads(await f.read())+ raw = await self._backend.read_file(path)+ data = json.loads(raw.decode("utf-8"))return _SkillsFile(skills_dir_mtime=float(data.get("skills_dir_mtime", 0.0)),skills=data.get("skills", {}),@@ -361,8 +363,10 @@ class LocalWorkspace(WorkspaceBase):"""path = os.path.join(skills_dir, ".skills")try:- async with aiofiles.open(path, "w", encoding="utf-8") as f:- await f.write(json.dumps(data, indent=2, ensure_ascii=False))+ await self._backend.write_file(+ path,+ json.dumps(data, indent=2, ensure_ascii=False).encode("utf-8"),+ )except Exception as e:logger.warning("Failed to save .skills to %s: %s", path, str(e))@@ -385,7 +389,7 @@ class LocalWorkspace(WorkspaceBase):try:# Check if SKILL.md exists- if not await aiofiles.ospath.isfile(skill_md_path):+ if not await self._backend.file_exists(skill_md_path):logger.warning("Invalid skill at %s: SKILL.md not found",skill_path,@@ -393,12 +397,8 @@ class LocalWorkspace(WorkspaceBase):return None# Read and parse SKILL.md- async with aiofiles.open(- skill_md_path,- "r",- encoding="utf-8",- ) as f:- content_str = await f.read()+ raw = await self._backend.read_file(skill_md_path)+ content_str = raw.decode("utf-8")# Parse frontmattercontent = frontmatter.loads(content_str)@@ -452,7 +452,9 @@ class LocalWorkspace(WorkspaceBase):return skill_path, skill_name, skill_hashasync def _offload_data_block(self, data_block: DataBlock) -> DataBlock:- """Offload the data block by persisting it as local files. This avoids+ """Offload the data block by persisting it as local files.++ Uses the backend to write the decoded binary data, avoidingembedding large base64-encoded data directly in the offload files,keeping them lightweight and readable.@@ -474,14 +476,15 @@ class LocalWorkspace(WorkspaceBase):# no need to read and compare bytes.hash_str = hashlib.sha256(data_block.source.data.encode()).hexdigest()ext = mimetypes.guess_extension(data_block.source.media_type) or ".bin"- path = os.path.join(self.workdir, "data", f"{hash_str}{ext}")+ data_dir = os.path.join(self.workdir, "data")+ path = os.path.join(data_dir, f"{hash_str}{ext}")# Reuse the existing file directly — same hash ⟹ same content.- if not await aiofiles.ospath.exists(path):- # Write decoded bytes to disk and return a URL-source DataBlock.- os.makedirs(os.path.dirname(path), exist_ok=True)- async with aiofiles.open(path, "wb") as f:- await f.write(base64.b64decode(data_block.source.data))+ if not await self._backend.file_exists(path):+ await self._backend.write_file(+ path,+ base64.b64decode(data_block.source.data),+ )return DataBlock(id=data_block.id,@@ -510,15 +513,11 @@ class LocalWorkspace(WorkspaceBase):`str`:The file path to the offloaded message."""- path = os.path.join(- self.workdir,- "sessions",- session_id,- "context.jsonl",- )+ base = os.path.join(self.workdir, "sessions", session_id)+ path = os.path.join(base, "context.jsonl")copied_msgs = deepcopy(msgs)- msgs_strs = []+ lines: list[str] = []for msg in copied_msgs:if not isinstance(msg.content, str):content = []@@ -531,20 +530,21 @@ class LocalWorkspace(WorkspaceBase):else:content.append(block)msg.content = content- msgs_strs.append(msg.model_dump_json())-- msgs_str = "\n".join(msgs_strs)- # Create parent directory if it doesn't exist- os.makedirs(os.path.dirname(path), exist_ok=True)- # Offload the context into the local file- # Always end with a newline to ensure proper JSONL format when- # appending- async with aiofiles.open(+ lines.append(msg.model_dump_json())++ payload = "\n".join(lines) + "\n"++ # Read existing content if any, then append. ``write_file``+ # creates parent directories, so no explicit mkdir is needed.+ existing = b""+ try:+ existing = await self._backend.read_file(path)+ except (FileNotFoundError, OSError):+ pass+ await self._backend.write_file(path,- mode="a",- encoding="utf-8",- ) as file:- await file.write(msgs_str + "\n")+ existing + payload.encode("utf-8"),+ )return pathasync def offload_tool_result(@@ -565,47 +565,40 @@ class LocalWorkspace(WorkspaceBase):`str`:The file path to the offloaded tool results."""- path = os.path.join(- self.workdir,- "sessions",- session_id,- f"tool_result-{tool_result.id}.txt",- )+ base = os.path.join(self.workdir, "sessions", session_id)+ path = os.path.join(base, f"tool_result-{tool_result.id}.txt")# Avoid filename conflictindex = 1- while os.path.exists(path):+ while await self._backend.file_exists(path):path = os.path.join(- self.workdir,- "sessions",- session_id,+ base,f"tool_result-{tool_result.id}({index}).txt",)index += 1- res_strs = []+ parts: list[str] = []if isinstance(tool_result.output, str):- res_strs.append(tool_result.output)+ parts.append(tool_result.output)else:for block in tool_result.output:if isinstance(block, TextBlock):- res_strs.append(block.text)+ parts.append(block.text)elif isinstance(block, DataBlock):if isinstance(block.source, Base64Source):data_block = await self._offload_data_block(block)url = data_block.source.urlelse:url = block.source.url- res_strs.append(+ parts.append(f"<data url='{url}' name='{block.name}' "f"media_type='{block.source.media_type}'/>",)- # Create parent directory if it doesn't exist- os.makedirs(os.path.dirname(path), exist_ok=True)- async with aiofiles.open(path, mode="w", encoding="utf-8") as file:- await file.write("".join(res_strs))-+ await self._backend.write_file(+ path,+ "".join(parts).encode("utf-8"),+ )return pathasync def close(self) -> None:@@ -654,28 +647,29 @@ class LocalWorkspace(WorkspaceBase):self._mcps = []mcp_file = os.path.join(self.workdir, ".mcp")- if await aiofiles.ospath.exists(mcp_file):- await asyncio.to_thread(os.remove, mcp_file)+ await self._backend.delete_path(mcp_file)async with self._skill_lock:- path = os.path.join(self.workdir, "skills")- if await aiofiles.ospath.isdir(path):- await asyncio.to_thread(shutil.rmtree, path)+ skills_path = os.path.join(self.workdir, "skills")+ await self._backend.delete_path(skills_path)for sub in ("sessions", "data"):path = os.path.join(self.workdir, sub)- if await aiofiles.ospath.isdir(path):- await asyncio.to_thread(shutil.rmtree, path)+ await self._backend.delete_path(path)async def list_tools(self) -> list[ToolBase]:- """List all tools available in the workspace."""+ """List all tools available in the workspace.++ Returns the six builtin tools (Bash, Read, Write, Edit, Grep,+ Glob), each backed by the workspace's :class:`LocalBackend`.+ """return [- Bash(cwd=self.workdir),- Edit(),- Glob(),- Grep(),- Read(),- Write(),+ Bash(cwd=self.workdir, backend=self._backend),+ Edit(backend=self._backend),+ Glob(backend=self._backend),+ Grep(backend=self._backend),+ Read(backend=self._backend),+ Write(backend=self._backend),]async def list_skills(self) -> list[Skill]:@@ -691,11 +685,13 @@ class LocalWorkspace(WorkspaceBase):"""skills_dir = os.path.join(self.workdir, "skills")async with self._skill_lock:- if not await aiofiles.ospath.isdir(skills_dir):+ if not await self._backend.is_dir(skills_dir):return []skills_file = await self._load_skills_file(skills_dir)- current_mtime = await aiofiles.ospath.getmtime(skills_dir)+ current_mtime = await self._backend.stat_mtime(skills_dir)+ if current_mtime is None:+ current_mtime = 0.0# Detect if the skills directory has changed since last indexingif current_mtime != skills_file["skills_dir_mtime"]:@@ -753,14 +749,13 @@ class LocalWorkspace(WorkspaceBase):original_mtime = skills_file["skills_dir_mtime"]# Collect actual subdirectories on disk- def _list_dirs() -> set[str]:- return {- d- for d in os.listdir(skills_dir)- if os.path.isdir(os.path.join(skills_dir, d))- }+ entries = await self._backend.list_dir(skills_dir)+ actual_dirs: set[str] = set()+ for d in entries:+ dir_path = os.path.join(skills_dir, d)+ if await self._backend.is_dir(dir_path):+ actual_dirs.add(d)- actual_dirs = await asyncio.to_thread(_list_dirs)indexed_dirs = set(existing.keys())updated = False@@ -846,18 +841,16 @@ class LocalWorkspace(WorkspaceBase):skill_md_path = os.path.join(skill_dir, "SKILL.md")try:- if not await aiofiles.ospath.isfile(skill_md_path):+ if not await self._backend.file_exists(skill_md_path):return None- updated_at = await aiofiles.ospath.getmtime(skill_md_path)+ updated_at = await self._backend.stat_mtime(skill_md_path)+ if updated_at is None:+ updated_at = 0.0- async with aiofiles.open(- skill_md_path,- "r",- encoding="utf-8",- ) as f:- content_str = await f.read()- content = frontmatter.loads(content_str)+ raw = await self._backend.read_file(skill_md_path)+ content_str = raw.decode("utf-8")+ content = frontmatter.loads(content_str)description = content.get("description")if not description:@@ -892,14 +885,14 @@ class LocalWorkspace(WorkspaceBase):mcp_file = os.path.join(self.workdir, ".mcp")try:# callers have lock.- async with aiofiles.open(mcp_file, "w", encoding="utf-8") as f:- await f.write(- json.dumps(- [m.model_dump() for m in self._mcps],- indent=2,- ensure_ascii=False,- ),- )+ await self._backend.write_file(+ mcp_file,+ json.dumps(+ [m.model_dump() for m in self._mcps],+ indent=2,+ ensure_ascii=False,+ ).encode("utf-8"),+ )except Exception as e:logger.warning("Failed to save .mcp to %s: %s", mcp_file, str(e))@@ -1019,8 +1012,9 @@ class LocalWorkspace(WorkspaceBase):existing[dir_name] = {"hash": skill_hash, "skill_name": agent_name}skills_file["skills"] = existing- skills_file["skills_dir_mtime"] = await aiofiles.ospath.getmtime(- skills_dir,+ mtime = await self._backend.stat_mtime(skills_dir)+ skills_file["skills_dir_mtime"] = (+ mtime if mtime is not None else 0.0)await self._save_skills_file(skills_dir, skills_file)@@ -1039,7 +1033,7 @@ class LocalWorkspace(WorkspaceBase):"""skills_dir = os.path.join(self.workdir, "skills")async with self._skill_lock:- if not await aiofiles.ospath.isdir(skills_dir):+ if not await self._backend.is_dir(skills_dir):logger.warning("Skills directory does not exist; cannot remove skill %r",name,@@ -1060,8 +1054,8 @@ class LocalWorkspace(WorkspaceBase):returnskill_dir_path = os.path.join(skills_dir, target_dir)- if await aiofiles.ospath.isdir(skill_dir_path):- await asyncio.to_thread(shutil.rmtree, skill_dir_path)+ if await self._backend.is_dir(skill_dir_path):+ await self._backend.delete_path(skill_dir_path)logger.info("Removed skill '%s' from %s",name,@@ -1078,7 +1072,8 @@ class LocalWorkspace(WorkspaceBase):del existing[target_dir]skills_file["skills"] = existing- skills_file["skills_dir_mtime"] = await aiofiles.ospath.getmtime(- skills_dir,+ mtime = await self._backend.stat_mtime(skills_dir)+ skills_file["skills_dir_mtime"] = (+ mtime if mtime is not None else 0.0)await self._save_skills_file(skills_dir, skills_file)diff --git a/src/agentscope/workspace/_utils.py b/src/agentscope/workspace/_utils.pyindex 132dd135b..2266c382f 100644--- a/src/agentscope/workspace/_utils.py+++ b/src/agentscope/workspace/_utils.py@@ -16,7 +16,6 @@ that consume these helpers live next to it underimport importlib.resources as _resfrom pathlib import Path-# ── shared constants ───────────────────────────────────────────────#: Minimum Python packages the gateway script needs at runtime.@@ -161,3 +160,25 @@ def _read_gateway_script_bytes() -> bytes:.joinpath("_mcp_gateway_app.py").read_bytes())+++# ── builtin tool helper scripts ───────────────────────────────────+++def _read_glob_helper_bytes() -> bytes:+ """Read the standalone glob helper script as bytes.++ The script ships at+ ``agentscope/tool/_builtin/_scripts/_glob_helper.py``. Both Docker+ and E2B backends copy it into the workspace so the :class:`Glob`+ tool can invoke it uniformly via ``exec_shell``.++ Returns:+ `bytes`:+ The raw contents of the ``_glob_helper.py`` script.+ """+ return (+ _res.files("agentscope.tool._builtin._scripts")+ .joinpath("_glob_helper.py")+ .read_bytes()+ )diff --git a/tests/backend_docker_test.py b/tests/backend_docker_test.pynew file mode 100644index 000000000..93fbc5244--- /dev/null+++ b/tests/backend_docker_test.py@@ -0,0 +1,218 @@+# -*- coding: utf-8 -*-+# pylint: disable=protected-access+"""Test cases for :class:`DockerBackend`.++Validates that the three backend primitives (``exec_shell``,+``read_file``, ``write_file``) and the inherited shell-based filesystem+helpers behave correctly inside a real Docker container.++The suite is skipped unless:++* the Docker daemon is reachable (probed via ``docker info``), and+* the host is Linux — the project only validates the Docker backend on+ Ubuntu/Linux CI runners; spinning containers up on other hosts is+ out of scope for these tests.++A live container is obtained by initializing a :class:`DockerWorkspace`+and reusing its already-wired :class:`DockerBackend` (``ws._backend``),+which avoids duplicating the container bring-up logic here.+"""++import shutil+import subprocess+import sys+import tempfile+import unittest+import uuid+from unittest.async_case import IsolatedAsyncioTestCase++from agentscope.tool import ExecResult+from agentscope.workspace import DockerWorkspace, DockerBackend+from agentscope.workspace._docker._make_dockerfile import CONTAINER_WORKDIR+++# ── availability checks ────────────────────────────────────────────+++def _docker_available() -> bool:+ """Return ``True`` iff the Docker daemon is reachable.++ Probes via the ``docker`` CLI (cheap, synchronous) so the result can+ gate the module at import time.+ """+ if shutil.which("docker") is None:+ return False+ try:+ result = subprocess.run(+ ["docker", "info"],+ capture_output=True,+ timeout=5,+ check=False,+ )+ return result.returncode == 0+ except (subprocess.TimeoutExpired, FileNotFoundError, OSError):+ return False+++_IS_LINUX = sys.platform == "linux"+_DOCKER_OK = _IS_LINUX and _docker_available()+_SKIP_REASON = "Docker backend is only tested on Linux with a live daemon"++[email protected](_DOCKER_OK, _SKIP_REASON)+class TestDockerBackend(IsolatedAsyncioTestCase):+ """Test cases for ``DockerBackend`` against a live container."""++ async def asyncSetUp(self) -> None:+ """Start a workspace and reuse its wired backend.++ The ``workspace_id`` is randomised so concurrent / repeated runs+ do not collide on the deterministic container name.+ """+ # pylint: disable=consider-using-with+ self.temp_dir = tempfile.TemporaryDirectory()+ self.workspace = DockerWorkspace(+ workspace_id=f"test-{uuid.uuid4().hex[:8]}",+ host_workdir=self.temp_dir.name,+ )+ await self.workspace.initialize()+ self.backend = self.workspace._backend+ self.assertIsInstance(self.backend, DockerBackend)++ async def asyncTearDown(self) -> None:+ """Stop the container and drop the temp host dir."""+ try:+ await self.workspace.close()+ finally:+ self.temp_dir.cleanup()++ # ── exec ───────────────────────────────────────────────────────++ async def test_exec_returns_stdout(self) -> None:+ """A program's stdout/exit code are captured into ``ExecResult``."""+ result = await self.backend.exec_shell(["echo", "hello world"])+ self.assertIsInstance(result, ExecResult)+ self.assertTrue(result.ok())+ self.assertEqual(result.stdout.decode().strip(), "hello world")++ async def test_exec_nonzero_exit(self) -> None:+ """A non-zero exit is reported as a normal (non-raising) result."""+ result = await self.backend.exec_shell(+ ["sh", "-c", "echo oops >&2; exit 4"],+ )+ self.assertEqual(result.exit_code, 4)+ self.assertIn("oops", result.stderr.decode())++ async def test_exec_argv_not_shell_split(self) -> None:+ """A single argv element with metacharacters reaches the program+ intact (no shell interposed by the primitive)."""+ tricky = "a b $(echo x) | ;"+ result = await self.backend.exec_shell(["echo", tricky])+ self.assertTrue(result.ok())+ self.assertEqual(result.stdout.decode().rstrip("\n"), tricky)++ async def test_exec_cwd_default_is_workdir(self) -> None:+ """With no explicit ``cwd`` the container workdir is used."""+ result = await self.backend.exec_shell(["pwd"])+ self.assertTrue(result.ok())+ self.assertEqual(result.stdout.decode().strip(), CONTAINER_WORKDIR)++ async def test_exec_timeout_returns_minus_one(self) -> None:+ """A command exceeding ``timeout`` reports the -1 sentinel."""+ result = await self.backend.exec_shell(+ ["sleep", "10"],+ timeout=0.5,+ )+ self.assertEqual(result.exit_code, -1)+ self.assertEqual(result.stderr, b"timed out")++ # ── file I/O ───────────────────────────────────────────────────++ async def test_write_then_read_roundtrip(self) -> None:+ """Bytes written into the container are read back verbatim."""+ path = f"{CONTAINER_WORKDIR}/roundtrip.txt"+ payload = b"hello\nworld\n"+ await self.backend.write_file(path, payload)+ self.assertEqual(await self.backend.read_file(path), payload)++ async def test_write_creates_parent_dirs(self) -> None:+ """``write_file`` creates missing parent directories."""+ path = f"{CONTAINER_WORKDIR}/a/b/c/file.txt"+ await self.backend.write_file(path, b"x")+ self.assertEqual(await self.backend.read_file(path), b"x")++ async def test_write_preserves_binary(self) -> None:+ """Raw bytes (incl. NULs and high bytes) survive the round-trip."""+ path = f"{CONTAINER_WORKDIR}/bin.dat"+ payload = b"a\r\nb\x00\xffc"+ await self.backend.write_file(path, payload)+ self.assertEqual(await self.backend.read_file(path), payload)++ async def test_read_missing_file_raises(self) -> None:+ """Reading a non-existent file raises ``FileNotFoundError``."""+ with self.assertRaises(FileNotFoundError):+ await self.backend.read_file(f"{CONTAINER_WORKDIR}/nope.txt")++ # ── derived filesystem helpers (shell-based) ───────────────────++ async def test_file_exists_and_is_dir(self) -> None:+ """``file_exists`` / ``is_dir`` reflect the container filesystem."""+ path = f"{CONTAINER_WORKDIR}/f.txt"+ await self.backend.write_file(path, b"x")+ self.assertTrue(await self.backend.file_exists(path))+ self.assertTrue(await self.backend.file_exists(CONTAINER_WORKDIR))+ self.assertTrue(await self.backend.is_dir(CONTAINER_WORKDIR))+ self.assertFalse(await self.backend.is_dir(path))+ self.assertFalse(+ await self.backend.file_exists(+ f"{CONTAINER_WORKDIR}/missing",+ ),+ )++ async def test_list_dir(self) -> None:+ """Non-recursive ``list_dir`` returns immediate child base names."""+ base = f"{CONTAINER_WORKDIR}/listing"+ await self.backend.write_file(f"{base}/a.txt", b"x")+ await self.backend.write_file(f"{base}/b.txt", b"x")+ entries = await self.backend.list_dir(base)+ self.assertEqual(sorted(entries), ["a.txt", "b.txt"])++ async def test_list_dir_recursive(self) -> None:+ """Recursive ``list_dir`` returns file paths underneath the root."""+ base = f"{CONTAINER_WORKDIR}/rec"+ await self.backend.write_file(f"{base}/top.txt", b"x")+ await self.backend.write_file(f"{base}/sub/nested.txt", b"x")+ entries = await self.backend.list_dir(base, recursive=True)+ basenames = sorted(e.rsplit("/", 1)[-1] for e in entries)+ self.assertEqual(basenames, ["nested.txt", "top.txt"])++ async def test_stat_mtime(self) -> None:+ """``stat_mtime`` returns a float for an existing path, None else."""+ path = f"{CONTAINER_WORKDIR}/stat.txt"+ await self.backend.write_file(path, b"x")+ mtime = await self.backend.stat_mtime(path)+ self.assertIsInstance(mtime, float)+ self.assertIsNone(+ await self.backend.stat_mtime(+ f"{CONTAINER_WORKDIR}/missing",+ ),+ )++ async def test_delete_path(self) -> None:+ """``delete_path`` removes files and trees; missing is a no-op."""+ path = f"{CONTAINER_WORKDIR}/to_delete.txt"+ await self.backend.write_file(path, b"x")+ await self.backend.delete_path(path)+ self.assertFalse(await self.backend.file_exists(path))++ tree = f"{CONTAINER_WORKDIR}/tree"+ await self.backend.write_file(f"{tree}/deep/f.txt", b"x")+ await self.backend.delete_path(tree)+ self.assertFalse(await self.backend.file_exists(tree))++ # Deleting a non-existent path must not raise.+ await self.backend.delete_path(f"{CONTAINER_WORKDIR}/missing")+++if __name__ == "__main__":+ unittest.main()diff --git a/tests/backend_e2b_test.py b/tests/backend_e2b_test.pynew file mode 100644index 000000000..532c4e269--- /dev/null+++ b/tests/backend_e2b_test.py@@ -0,0 +1,153 @@+# -*- coding: utf-8 -*-+# pylint: disable=protected-access+"""Test cases for :class:`E2BBackend`.++Validates that the three backend primitives (``exec_shell``,+``read_file``, ``write_file``) and the inherited shell-based filesystem+helpers behave correctly inside a real E2B cloud sandbox.++The whole module is skipped unless the ``E2B_API_KEY`` environment+variable is set, because every test requires a live E2B sandbox. CI+runs without E2B credentials are therefore unaffected; when a key *is*+present the tests exercise the real ``commands.run`` / ``files.*`` APIs.++A live sandbox is obtained by initializing an :class:`E2BWorkspace` and+reusing its already-wired :class:`E2BBackend` (``ws._backend``), which+avoids duplicating the sandbox bring-up logic here.+"""++import os+import unittest+from unittest.async_case import IsolatedAsyncioTestCase++from agentscope.tool import ExecResult+from agentscope.workspace import E2BWorkspace+from agentscope.workspace import E2BBackend+from agentscope.workspace._e2b._bootstrap import SANDBOX_WORKDIR+++# ── E2B availability check ─────────────────────────────────────────++_E2B_API_KEY = os.getenv("E2B_API_KEY", "")+_SKIP_REASON = "E2B_API_KEY environment variable is not set"++[email protected](_E2B_API_KEY, _SKIP_REASON)+class TestE2BBackend(IsolatedAsyncioTestCase):+ """Test cases for ``E2BBackend`` against a live sandbox.++ Each test creates a real E2B cloud sandbox via ``E2BWorkspace`` and+ tears it down (``close`` → sandbox pause) afterwards.+ """++ async def asyncSetUp(self) -> None:+ """Start a workspace and reuse its wired backend."""+ self.workspace = E2BWorkspace(api_key=_E2B_API_KEY)+ await self.workspace.initialize()+ self.backend = self.workspace._backend+ self.assertIsInstance(self.backend, E2BBackend)++ async def asyncTearDown(self) -> None:+ """Pause / close the sandbox."""+ await self.workspace.close()++ # ── exec ───────────────────────────────────────────────────────++ async def test_exec_returns_stdout(self) -> None:+ """A program's stdout/exit code are captured into ``ExecResult``."""+ result = await self.backend.exec_shell(["echo", "hello world"])+ self.assertIsInstance(result, ExecResult)+ self.assertTrue(result.ok())+ self.assertEqual(result.stdout.decode().strip(), "hello world")++ async def test_exec_nonzero_exit(self) -> None:+ """A non-zero command exit is reported as a normal result."""+ result = await self.backend.exec_shell(+ ["sh", "-c", "echo oops >&2; exit 4"],+ )+ self.assertEqual(result.exit_code, 4)+ self.assertIn("oops", result.stderr.decode())++ async def test_exec_argv_quoting_preserved(self) -> None:+ """An argv element with spaces / metacharacters survives the+ POSIX-quote round-trip the backend does for ``commands.run``."""+ tricky = "a b c | ;"+ result = await self.backend.exec_shell(["echo", tricky])+ self.assertTrue(result.ok())+ self.assertEqual(result.stdout.decode().rstrip("\n"), tricky)++ async def test_exec_cwd_default_is_workdir(self) -> None:+ """With no explicit ``cwd`` the sandbox workdir is used."""+ result = await self.backend.exec_shell(["pwd"])+ self.assertTrue(result.ok())+ self.assertEqual(result.stdout.decode().strip(), SANDBOX_WORKDIR)++ # ── file I/O ───────────────────────────────────────────────────++ async def test_write_then_read_roundtrip(self) -> None:+ """Bytes written into the sandbox are read back verbatim."""+ path = f"{SANDBOX_WORKDIR}/roundtrip.txt"+ payload = b"hello\nworld\n"+ await self.backend.write_file(path, payload)+ self.assertEqual(await self.backend.read_file(path), payload)++ async def test_write_creates_parent_dirs(self) -> None:+ """``write_file`` creates missing parent directories."""+ path = f"{SANDBOX_WORKDIR}/a/b/c/file.txt"+ await self.backend.write_file(path, b"x")+ self.assertEqual(await self.backend.read_file(path), b"x")++ async def test_read_missing_file_raises(self) -> None:+ """Reading a non-existent file raises ``FileNotFoundError``."""+ with self.assertRaises(FileNotFoundError):+ await self.backend.read_file(f"{SANDBOX_WORKDIR}/nope.txt")++ # ── derived filesystem helpers (shell-based) ───────────────────++ async def test_file_exists_and_is_dir(self) -> None:+ """``file_exists`` / ``is_dir`` reflect the sandbox filesystem."""+ path = f"{SANDBOX_WORKDIR}/f.txt"+ await self.backend.write_file(path, b"x")+ self.assertTrue(await self.backend.file_exists(path))+ self.assertTrue(await self.backend.is_dir(SANDBOX_WORKDIR))+ self.assertFalse(await self.backend.is_dir(path))+ self.assertFalse(+ await self.backend.file_exists(f"{SANDBOX_WORKDIR}/missing"),+ )++ async def test_list_dir(self) -> None:+ """Non-recursive ``list_dir`` returns immediate child base names."""+ base = f"{SANDBOX_WORKDIR}/listing"+ await self.backend.write_file(f"{base}/a.txt", b"x")+ await self.backend.write_file(f"{base}/b.txt", b"x")+ entries = await self.backend.list_dir(base)+ self.assertEqual(sorted(entries), ["a.txt", "b.txt"])++ async def test_stat_mtime(self) -> None:+ """``stat_mtime`` returns a float for an existing path, None else."""+ path = f"{SANDBOX_WORKDIR}/stat.txt"+ await self.backend.write_file(path, b"x")+ mtime = await self.backend.stat_mtime(path)+ self.assertIsInstance(mtime, float)+ self.assertIsNone(+ await self.backend.stat_mtime(f"{SANDBOX_WORKDIR}/missing"),+ )++ async def test_delete_path(self) -> None:+ """``delete_path`` removes files and trees; missing is a no-op."""+ path = f"{SANDBOX_WORKDIR}/to_delete.txt"+ await self.backend.write_file(path, b"x")+ await self.backend.delete_path(path)+ self.assertFalse(await self.backend.file_exists(path))++ tree = f"{SANDBOX_WORKDIR}/tree"+ await self.backend.write_file(f"{tree}/deep/f.txt", b"x")+ await self.backend.delete_path(tree)+ self.assertFalse(await self.backend.file_exists(tree))++ # Deleting a non-existent path must not raise.+ await self.backend.delete_path(f"{SANDBOX_WORKDIR}/missing")+++if __name__ == "__main__":+ unittest.main()diff --git a/tests/backend_local_test.py b/tests/backend_local_test.pynew file mode 100644index 000000000..3d23366d9--- /dev/null+++ b/tests/backend_local_test.py@@ -0,0 +1,329 @@+# -*- coding: utf-8 -*-+"""Test cases for :class:`LocalBackend` and the backend helpers.++Exercises the three abstract primitives (``exec_shell``, ``read_file``,+``write_file``) plus the derived filesystem helpers (``file_exists``,+``is_dir``, ``list_dir``, ``stat_mtime``, ``delete_path``) of the+host-local backend, and the module-level ``normalize_newlines`` helper.++``LocalBackend`` is designed to run on every platform (it spawns+programs from an argv list without a shell and implements the+filesystem helpers with native ``os.*`` calls), so the bulk of this+module runs on Windows too. Only the handful of cases that genuinely+rely on a POSIX shell / POSIX-only utilities are skipped on Windows.+"""++import os+import sys+import tempfile+import unittest+from unittest.async_case import IsolatedAsyncioTestCase++from agentscope.tool import ExecResult, LocalBackend+from agentscope.tool._builtin._backend import _normalize_newlines++_IS_WINDOWS = sys.platform == "win32"+++class TestNormalizeNewlines(unittest.TestCase):+ """Unit tests for the ``normalize_newlines`` helper (pure, no I/O)."""++ def test_crlf_collapsed_to_lf(self) -> None:+ """Windows ``\\r\\n`` is collapsed to a single ``\\n``."""+ self.assertEqual(+ _normalize_newlines("a\r\nb\r\nc"),+ "a\nb\nc",+ )++ def test_lone_cr_collapsed_to_lf(self) -> None:+ """Classic-Mac lone ``\\r`` is collapsed to ``\\n``."""+ self.assertEqual(_normalize_newlines("a\rb\rc"), "a\nb\nc")++ def test_mixed_endings(self) -> None:+ """A mix of ``\\r\\n``, ``\\r`` and ``\\n`` normalizes uniformly."""+ self.assertEqual(+ _normalize_newlines("a\r\nb\rc\nd"),+ "a\nb\nc\nd",+ )++ def test_plain_lf_unchanged(self) -> None:+ """Text already using ``\\n`` is returned unchanged."""+ self.assertEqual(_normalize_newlines("a\nb\nc"), "a\nb\nc")++ def test_no_double_collapse(self) -> None:+ """``\\r\\n`` becomes exactly one ``\\n`` (not two)."""+ self.assertEqual(_normalize_newlines("a\r\n\r\nb"), "a\n\nb")+++class TestLocalBackendExec(IsolatedAsyncioTestCase):+ """Test cases for ``LocalBackend.exec_shell``."""++ async def asyncSetUp(self) -> None:+ """Build a fresh backend per test."""+ self.backend = LocalBackend()++ async def test_exec_returns_stdout(self) -> None:+ """A program's stdout/exit code are captured into ``ExecResult``.++ Uses the current interpreter so the test is portable across+ platforms (no reliance on ``echo`` / shell builtins).+ """+ result = await self.backend.exec_shell(+ [sys.executable, "-c", "print('hello world')"],+ )+ self.assertIsInstance(result, ExecResult)+ self.assertTrue(result.ok())+ self.assertEqual(result.exit_code, 0)+ self.assertEqual(result.stdout.decode().strip(), "hello world")+ self.assertEqual(result.stderr, b"")++ async def test_exec_captures_stderr_and_exit_code(self) -> None:+ """A non-zero exit and stderr bytes are reported faithfully."""+ result = await self.backend.exec_shell(+ [+ sys.executable,+ "-c",+ "import sys; sys.stderr.write('boom'); sys.exit(3)",+ ],+ )+ self.assertFalse(result.ok())+ self.assertEqual(result.exit_code, 3)+ self.assertEqual(result.stderr.decode().strip(), "boom")++ async def test_exec_argv_not_split_by_shell(self) -> None:+ """Arguments are passed verbatim (no shell word-splitting/globbing).++ A single argument containing spaces and shell metacharacters must+ reach the program intact, proving no shell is interposed.+ """+ tricky = "a b $(echo x) | & ; '\""+ result = await self.backend.exec_shell(+ [sys.executable, "-c", "import sys; print(sys.argv[1])", tricky],+ )+ self.assertTrue(result.ok())+ self.assertEqual(result.stdout.decode().rstrip("\r\n"), tricky)++ async def test_exec_cwd_is_respected(self) -> None:+ """``cwd`` sets the subprocess working directory."""+ with tempfile.TemporaryDirectory() as tmp:+ result = await self.backend.exec_shell(+ [sys.executable, "-c", "import os; print(os.getcwd())"],+ cwd=tmp,+ )+ self.assertTrue(result.ok())+ self.assertEqual(+ os.path.realpath(result.stdout.decode().strip()),+ os.path.realpath(tmp),+ )++ async def test_missing_executable_returns_127(self) -> None:+ """An unspawnable executable yields exit code 127 (not an exception).++ Mirrors a shell's "command not found" so callers see a normal+ non-zero ``ExecResult``.+ """+ result = await self.backend.exec_shell(+ ["this_executable_does_not_exist_xyz", "--nope"],+ )+ self.assertEqual(result.exit_code, 127)+ self.assertEqual(result.stdout, b"")+ self.assertNotEqual(result.stderr, b"")++ async def test_timeout_returns_minus_one(self) -> None:+ """A command exceeding ``timeout`` is killed and reports -1.++ The sentinel ``ExecResult(exit_code=-1, stderr=b"timed out")`` is+ what Grep/Glob check for, so it is asserted exactly.+ """+ result = await self.backend.exec_shell(+ [sys.executable, "-c", "import time; time.sleep(10)"],+ timeout=0.2,+ )+ self.assertEqual(result.exit_code, -1)+ self.assertEqual(result.stderr, b"timed out")+++class TestLocalBackendFileIO(IsolatedAsyncioTestCase):+ """Test cases for ``read_file`` / ``write_file`` round-trips."""++ async def asyncSetUp(self) -> None:+ """Build a backend and a temp dir per test."""+ # pylint: disable=consider-using-with+ self.backend = LocalBackend()+ self.temp_dir = tempfile.TemporaryDirectory()++ async def asyncTearDown(self) -> None:+ """Drop the temp dir."""+ self.temp_dir.cleanup()++ async def test_write_then_read_roundtrip(self) -> None:+ """Bytes written are read back verbatim."""+ path = os.path.join(self.temp_dir.name, "file.txt")+ payload = b"hello\nworld\n"+ await self.backend.write_file(path, payload)+ self.assertEqual(await self.backend.read_file(path), payload)++ async def test_write_creates_parent_dirs(self) -> None:+ """``write_file`` creates missing parent directories."""+ path = os.path.join(self.temp_dir.name, "a", "b", "c", "file.txt")+ await self.backend.write_file(path, b"x")+ self.assertTrue(os.path.exists(path))+ self.assertEqual(await self.backend.read_file(path), b"x")++ async def test_write_preserves_binary_and_crlf(self) -> None:+ """Raw bytes (incl. ``\\r\\n`` and NULs) survive the round-trip.++ The backend deals in raw bytes; newline normalization happens+ later in the text layer, never here.+ """+ path = os.path.join(self.temp_dir.name, "bin.dat")+ payload = b"a\r\nb\x00\xffc"+ await self.backend.write_file(path, payload)+ self.assertEqual(await self.backend.read_file(path), payload)++ async def test_read_missing_file_raises(self) -> None:+ """Reading a non-existent file raises ``FileNotFoundError``."""+ path = os.path.join(self.temp_dir.name, "nope.txt")+ with self.assertRaises(FileNotFoundError):+ await self.backend.read_file(path)+++class TestLocalBackendFilesystemHelpers(IsolatedAsyncioTestCase):+ """Test cases for the derived filesystem helpers (native ``os.*``)."""++ async def asyncSetUp(self) -> None:+ """Build a backend and a temp dir per test."""+ # pylint: disable=consider-using-with+ self.backend = LocalBackend()+ self.temp_dir = tempfile.TemporaryDirectory()++ async def asyncTearDown(self) -> None:+ """Drop the temp dir."""+ self.temp_dir.cleanup()++ async def test_file_exists(self) -> None:+ """``file_exists`` is True for files and dirs, False otherwise."""+ path = os.path.join(self.temp_dir.name, "f.txt")+ await self.backend.write_file(path, b"x")+ self.assertTrue(await self.backend.file_exists(path))+ self.assertTrue(await self.backend.file_exists(self.temp_dir.name))+ self.assertFalse(+ await self.backend.file_exists(+ os.path.join(self.temp_dir.name, "missing"),+ ),+ )++ async def test_is_dir(self) -> None:+ """``is_dir`` distinguishes directories from files."""+ path = os.path.join(self.temp_dir.name, "f.txt")+ await self.backend.write_file(path, b"x")+ self.assertTrue(await self.backend.is_dir(self.temp_dir.name))+ self.assertFalse(await self.backend.is_dir(path))+ self.assertFalse(+ await self.backend.is_dir(+ os.path.join(self.temp_dir.name, "missing"),+ ),+ )++ async def test_list_dir_shallow(self) -> None:+ """Non-recursive ``list_dir`` returns immediate child base names."""+ for name in ("a.txt", "b.txt"):+ await self.backend.write_file(+ os.path.join(self.temp_dir.name, name),+ b"x",+ )+ os.makedirs(os.path.join(self.temp_dir.name, "sub"))+ entries = await self.backend.list_dir(self.temp_dir.name)+ self.assertEqual(sorted(entries), ["a.txt", "b.txt", "sub"])++ async def test_list_dir_recursive(self) -> None:+ """Recursive ``list_dir`` returns file paths underneath the root."""+ await self.backend.write_file(+ os.path.join(self.temp_dir.name, "top.txt"),+ b"x",+ )+ await self.backend.write_file(+ os.path.join(self.temp_dir.name, "sub", "nested.txt"),+ b"x",+ )+ entries = await self.backend.list_dir(+ self.temp_dir.name,+ recursive=True,+ )+ basenames = sorted(os.path.basename(e) for e in entries)+ self.assertEqual(basenames, ["nested.txt", "top.txt"])++ async def test_stat_mtime(self) -> None:+ """``stat_mtime`` returns a float for an existing path, None else."""+ path = os.path.join(self.temp_dir.name, "f.txt")+ await self.backend.write_file(path, b"x")+ mtime = await self.backend.stat_mtime(path)+ self.assertIsInstance(mtime, float)+ self.assertIsNone(+ await self.backend.stat_mtime(+ os.path.join(self.temp_dir.name, "missing"),+ ),+ )++ async def test_delete_path_file(self) -> None:+ """``delete_path`` removes a single file."""+ path = os.path.join(self.temp_dir.name, "f.txt")+ await self.backend.write_file(path, b"x")+ await self.backend.delete_path(path)+ self.assertFalse(os.path.exists(path))++ async def test_delete_path_tree(self) -> None:+ """``delete_path`` removes a directory tree recursively."""+ nested = os.path.join(self.temp_dir.name, "d", "e")+ os.makedirs(nested)+ await self.backend.write_file(+ os.path.join(nested, "f.txt"),+ b"x",+ )+ target = os.path.join(self.temp_dir.name, "d")+ await self.backend.delete_path(target)+ self.assertFalse(os.path.exists(target))++ async def test_delete_path_missing_is_noop(self) -> None:+ """Deleting a non-existent path is a silent no-op (like rm -rf)."""+ # Must not raise.+ await self.backend.delete_path(+ os.path.join(self.temp_dir.name, "missing"),+ )+++ _IS_WINDOWS,+ "POSIX shell (/bin/sh) is not available on Windows",+)+class TestLocalBackendShellWrapping(IsolatedAsyncioTestCase):+ """Cases that explicitly use ``sh -c`` (POSIX-only, skipped on Windows).++ The backend primitive never invokes a shell itself; these tests cover+ the documented escape hatch where a *caller* wraps a command line as+ ``["/bin/sh", "-c", line]`` to use pipes / redirects / ``&&``.+ """++ async def asyncSetUp(self) -> None:+ """Build a backend per test."""+ self.backend = LocalBackend()++ async def test_sh_c_pipeline(self) -> None:+ """A piped command line runs when wrapped in ``sh -c``."""+ result = await self.backend.exec_shell(+ ["/bin/sh", "-c", "printf 'a\\nb\\na\\n' | sort | uniq"],+ )+ self.assertTrue(result.ok())+ self.assertEqual(result.stdout.decode().split(), ["a", "b"])++ async def test_sh_c_and_chain(self) -> None:+ """``&&`` chaining works through ``sh -c``."""+ result = await self.backend.exec_shell(+ ["/bin/sh", "-c", "true && echo chained"],+ )+ self.assertTrue(result.ok())+ self.assertEqual(result.stdout.decode().strip(), "chained")+++if __name__ == "__main__":+ unittest.main()diff --git a/tests/builtin_bash_test.py b/tests/builtin_bash_test.pyindex a42f530af..659436230 100644--- a/tests/builtin_bash_test.py+++ b/tests/builtin_bash_test.py@@ -1,18 +1,22 @@# -*- coding: utf-8 -*-"""Bash tool test case."""++import osimport sysimport unittestfrom unittest.async_case import IsolatedAsyncioTestCasefrom unittest.mock import AsyncMock, MagicMock, patch-from agentscope.tool import ToolChunk, Bash-from agentscope.tool._builtin._bash import _subprocess_creation_kwargs+from agentscope.message import TextBlockfrom agentscope.permission import (- PermissionContext,PermissionBehavior,+ PermissionContext,PermissionRule,)-from agentscope.message import TextBlock+from agentscope.tool import Bash, ToolChunk+from agentscope.tool._builtin._backend import (+ _subprocess_creation_kwargs,+)class BashSubprocessKwargsTest(unittest.TestCase):@@ -20,12 +24,15 @@ class BashSubprocessKwargsTest(unittest.TestCase):def test_non_windows_subprocess_kwargs_are_empty(self) -> None:"""On non-Windows the helper returns no extra subprocess kwargs."""- with patch("agentscope.tool._builtin._bash.os.name", "posix"):+ with patch(+ "agentscope.tool._builtin._backend.os.name",+ "posix",+ ):self.assertEqual(_subprocess_creation_kwargs(), {})def test_windows_subprocess_kwargs_hide_console(self) -> None:"""On Windows the helper sets ``creationflags`` to hide the console."""- with patch("agentscope.tool._builtin._bash.os.name", "nt"):+ with patch("agentscope.tool._builtin._backend.os.name", "nt"):self.assertEqual(_subprocess_creation_kwargs(),{"creationflags": 0x08000000},@@ -43,14 +50,27 @@ class BashCwdTest(IsolatedAsyncioTestCase):create_process = AsyncMock(return_value=process)with patch(- "agentscope.tool._builtin._bash.asyncio.create_subprocess_shell",+ "agentscope.tool._builtin._backend."+ "asyncio.create_subprocess_exec",create_process,):chunks = []async for chunk in await Bash(cwd="workspace")(command="pwd"):chunks.append(chunk)+ # cwd is forwarded, and the command line is wrapped in the+ # platform's native shell (the backend primitive runs an argv+ # without a shell): ``cmd /c`` on Windows, ``/bin/sh -c`` else.self.assertEqual(create_process.call_args.kwargs["cwd"], "workspace")+ expected_argv = (+ ("cmd", "/c", "pwd")+ if os.name == "nt"+ else ("/bin/sh", "-c", "pwd")+ )+ self.assertEqual(+ create_process.call_args.args,+ expected_argv,+ )self.assertEqual(chunks[0].state, "running")diff --git a/tests/workspace_docker_test.py b/tests/workspace_docker_test.pyindex 1e3acef22..96c278002 100644--- a/tests/workspace_docker_test.py+++ b/tests/workspace_docker_test.py@@ -24,6 +24,7 @@ Two practical differences vs. the local tests:The whole module is skipped when no Docker daemon is reachable."""+import base64import hashlibimport os@@ -40,6 +41,7 @@ from urllib.parse import urlparseimport aiofilesfrom agentscope.message import (+ AssistantMsg,Base64Source,DataBlock,Msg,@@ -48,7 +50,6 @@ from agentscope.message import (ToolResultState,URLSource,UserMsg,- AssistantMsg,)from agentscope.permission import PermissionBehavior, PermissionDecisionfrom agentscope.tool import ToolBase, ToolChunk@@ -58,7 +59,6 @@ from agentscope.workspace._docker._make_dockerfile import (CONTAINER_SKILLS_DIR,)-# ── docker daemon detection ────────────────────────────────────────@@ -150,7 +150,7 @@ class TestDockerWorkspaceOffload(IsolatedAsyncioTestCase):self.temp_dir = tempfile.TemporaryDirectory()self.workspace = DockerWorkspace(workspace_id=f"test-{uuid.uuid4().hex[:8]}",- workdir=self.temp_dir.name,+ host_workdir=self.temp_dir.name,)await self.workspace.initialize()@@ -534,7 +534,7 @@ class TestDockerWorkspaceSkills(IsolatedAsyncioTestCase):self.workspace = DockerWorkspace(workspace_id=f"test-{uuid.uuid4().hex[:8]}",- workdir=self.temp_dir.name,+ host_workdir=self.temp_dir.name,skill_paths=[skill1, skill2],)await self.workspace.initialize()@@ -570,7 +570,7 @@ class TestDockerWorkspaceSkills(IsolatedAsyncioTestCase):self.workspace = DockerWorkspace(workspace_id=f"test-{uuid.uuid4().hex[:8]}",- workdir=self.temp_dir.name,+ host_workdir=self.temp_dir.name,skill_paths=[skill1, skill2],)await self.workspace.initialize()@@ -603,7 +603,7 @@ class TestDockerWorkspaceSkills(IsolatedAsyncioTestCase):"""Empty workspace → empty skill list (no errors)."""self.workspace = DockerWorkspace(workspace_id=f"test-{uuid.uuid4().hex[:8]}",- workdir=self.temp_dir.name,+ host_workdir=self.temp_dir.name,)await self.workspace.initialize()skills = await self.workspace.list_skills()@@ -613,7 +613,7 @@ class TestDockerWorkspaceSkills(IsolatedAsyncioTestCase):"""``add_skill`` after init shows up in subsequent ``list_skills``."""self.workspace = DockerWorkspace(workspace_id=f"test-{uuid.uuid4().hex[:8]}",- workdir=self.temp_dir.name,+ host_workdir=self.temp_dir.name,)await self.workspace.initialize()self.assertListEqual(await self.workspace.list_skills(), [])@@ -633,7 +633,7 @@ class TestDockerWorkspaceSkills(IsolatedAsyncioTestCase):"""``add_skill`` rejects directories without SKILL.md."""self.workspace = DockerWorkspace(workspace_id=f"test-{uuid.uuid4().hex[:8]}",- workdir=self.temp_dir.name,+ host_workdir=self.temp_dir.name,)await self.workspace.initialize()@@ -671,7 +671,7 @@ class TestDockerWorkspaceLifecycle(IsolatedAsyncioTestCase):"""Calling ``initialize`` on a live workspace is a no-op."""ws = DockerWorkspace(workspace_id=self.workspace_id,- workdir=self.temp_dir.name,+ host_workdir=self.temp_dir.name,)try:await ws.initialize()@@ -688,7 +688,7 @@ class TestDockerWorkspaceLifecycle(IsolatedAsyncioTestCase):"""``close`` flips ``is_alive`` and tears the container down."""ws = DockerWorkspace(workspace_id=self.workspace_id,- workdir=self.temp_dir.name,+ host_workdir=self.temp_dir.name,)await ws.initialize()self.assertTrue(ws.is_alive)@@ -701,7 +701,7 @@ class TestDockerWorkspaceLifecycle(IsolatedAsyncioTestCase):"""No MCPs registered → ``list_mcps`` returns an empty list."""ws = DockerWorkspace(workspace_id=self.workspace_id,- workdir=self.temp_dir.name,+ host_workdir=self.temp_dir.name,)try:await ws.initialize()@@ -709,15 +709,33 @@ class TestDockerWorkspaceLifecycle(IsolatedAsyncioTestCase):finally:await ws.close()- async def test_list_tools_empty(self) -> None:- """``list_tools`` is always empty — every tool is an MCP tool."""+ async def test_list_tools_builtin(self) -> None:+ """returns the six builtin tools backed by DockerBackend."""+ from agentscope.tool._builtin import (+ Bash,+ Edit,+ Glob,+ Grep,+ Read,+ Write,+ )+ from agentscope.workspace._docker._docker_backend import DockerBackend+ws = DockerWorkspace(workspace_id=self.workspace_id,- workdir=self.temp_dir.name,+ host_workdir=self.temp_dir.name,)try:await ws.initialize()- self.assertListEqual(await ws.list_tools(), [])+ tools = await ws.list_tools()+ self.assertEqual(len(tools), 6)++ expected_types = {Bash, Edit, Glob, Grep, Read, Write}+ actual_types = {type(t) for t in tools}+ self.assertSetEqual(actual_types, expected_types)++ for tool in tools:+ self.assertIsInstance(tool._backend, DockerBackend)finally:await ws.close()@@ -734,7 +752,7 @@ class TestDockerWorkspaceLifecycle(IsolatedAsyncioTestCase):ws1 = DockerWorkspace(workspace_id=self.workspace_id,- workdir=self.temp_dir.name,+ host_workdir=self.temp_dir.name,)await ws1.initialize()await ws1.offload_context(session_id, [msg])@@ -750,7 +768,7 @@ class TestDockerWorkspaceLifecycle(IsolatedAsyncioTestCase):ws2 = DockerWorkspace(workspace_id=self.workspace_id,- workdir=self.temp_dir.name,+ host_workdir=self.temp_dir.name,)try:await ws2.initialize()@@ -767,7 +785,7 @@ class TestDockerWorkspaceLifecycle(IsolatedAsyncioTestCase):"""``reset`` removes ``sessions/`` and ``data/`` (host-visible)."""ws = DockerWorkspace(workspace_id=self.workspace_id,- workdir=self.temp_dir.name,+ host_workdir=self.temp_dir.name,)try:await ws.initialize()