Skip to content

Build and run agents you can see, understand and trust.

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.yml
index 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__.py
index 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__.py
index 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, LocalBackend
from ._bash import Bash
from ._edit import Edit
from ._glob import Glob
from ._grep import Grep
+from ._meta import ResetTools
from ._read import Read
+from ._skill import SkillViewer
from ._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.py
new file mode 100644
index 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.py
index 96cb7275a..8e04dfed0 100644
--- a/src/agentscope/tool/_builtin/_bash.py
+++ b/src/agentscope/tool/_builtin/_bash.py
@@ -3,7 +3,6 @@
import os
from typing import AsyncGenerator, Any, List
import re
-import asyncio
from ._bash_parser import BashCommandParser
from .._base import ToolBase, ToolMiddlewareBase
@@ -18,24 +17,9 @@ from ...permission import (
PermissionMode,
PermissionRule,
)
-from ...message import TextBlock
+from ...message import TextBlock, ToolResultState
from .._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 BackendBase
class 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 LocalBackend
super().__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.0
try:
- # 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 output
output = 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 ToolResponse
yield 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 errors
error_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.py
index caa79ae53..863a71996 100644
--- a/src/agentscope/tool/_builtin/_edit.py
+++ b/src/agentscope/tool/_builtin/_edit.py
@@ -4,8 +4,6 @@ import fnmatch
import os
from typing import Any, List
-import aiofiles
-
from .._base import ToolBase, ToolMiddlewareBase
from .._constants import (
DEFAULT_DANGEROUS_FILES,
@@ -21,6 +19,7 @@ from ...permission import (
from .._response import ToolChunk
from ...message import TextBlock, ToolResultState
from ...state import AgentState
+from ._backend import BackendBase, _normalize_newlines
class 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 backend
try:
- 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 backend
try:
- 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.py
index 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 json
import 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, ToolResultState
from ...permission import (
+ PermissionBehavior,
PermissionContext,
PermissionDecision,
- PermissionBehavior,
PermissionRule,
)
+from .._base import ToolBase, ToolMiddlewareBase
from .._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: E501
def __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: E501
Args:
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: E501
text=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.py
index 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 asyncio
import fnmatch
import os
-import shutil
from typing import Any, List, Literal
from .._base import ToolBase, ToolMiddlewareBase
-from ..._logging import logger
from ...permission import (
PermissionContext,
PermissionDecision,
@@ -16,6 +13,7 @@ from ...permission import (
)
from .._response import ToolChunk
from ...message import TextBlock, ToolResultState
+from ._backend import BackendBase
# Version control system directories to exclude from searches
VCS_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.py
index d5087e5dd..b45e2e6c7 100644
--- a/src/agentscope/tool/_builtin/_read.py
+++ b/src/agentscope/tool/_builtin/_read.py
@@ -4,8 +4,6 @@ import fnmatch
import os
from typing import Any, List
-import aiofiles
-
from .._base import ToolBase, ToolMiddlewareBase
from ...permission import (
PermissionContext,
@@ -16,6 +14,7 @@ from ...permission import (
from .._response import ToolChunk
from ...message import TextBlock, ToolResultState
from ...state import AgentState
+from ._backend import BackendBase, _normalize_newlines
class 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 backend
lines = None
if _agent_state is not None:
cache = await _agent_state.tool_context.get_cache(file_path)
@@ -224,13 +230,13 @@ Usage:
lines = cache.lines
if 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 provided
if _agent_state is not None:
diff --git a/src/agentscope/tool/_builtin/_scripts/__init__.py b/src/agentscope/tool/_builtin/_scripts/__init__.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
index 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 fnmatch
import os
-from pathlib import Path
from typing import Any, List
-import aiofiles
-
from .._base import ToolBase, ToolMiddlewareBase
from .._constants import (
DEFAULT_DANGEROUS_FILES,
@@ -22,6 +19,7 @@ from ...permission import (
from .._response import ToolChunk
from ...message import TextBlock, ToolResultState
from ...state import AgentState
+from ._backend import BackendBase
class 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 content
line_count = len(content.split("\n"))
diff --git a/src/agentscope/workspace/__init__.py b/src/agentscope/workspace/__init__.py
index 875872eaa..37531571f 100644
--- a/src/agentscope/workspace/__init__.py
+++ b/src/agentscope/workspace/__init__.py
@@ -5,14 +5,16 @@
from ._base import WorkspaceBase
from ._local_workspace import LocalWorkspace
from ._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.template
index 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.py
WORKDIR {container_workdir}
diff --git a/src/agentscope/workspace/_docker/__init__.py b/src/agentscope/workspace/_docker/__init__.py
index 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.py
new file mode 100644
index 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.py
index 5978b38cd..22a670e7c 100644
--- a/src/agentscope/workspace/_docker/_docker_workspace.py
+++ b/src/agentscope/workspace/_docker/_docker_workspace.py
@@ -39,7 +39,6 @@ import sys
import tarfile
import uuid
from copy import deepcopy
-from dataclasses import dataclass
from typing import Any
from pydantic import AnyUrl
@@ -61,6 +60,7 @@ from .._gateway_client import (
GatewayClient,
GatewayMCPClient,
)
+from ._docker_backend import DockerBackend
from ._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 the
container** 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.Docker
self._container: Any = None
+ self._backend: DockerBackend | None = None
self._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:
pass
self._container = None
+ self._backend = None
if 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:
continue
try:
- 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 = content
lines.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.py
index 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__.py
index 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.py
index 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.py
new file mode 100644
index 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.py
index bec916049..e5f30119a 100644
--- a/src/agentscope/workspace/_e2b/_e2b_workspace.py
+++ b/src/agentscope/workspace/_e2b/_e2b_workspace.py
@@ -44,7 +44,6 @@ import posixpath
import shlex
import uuid
from copy import deepcopy
-from dataclasses import dataclass
from typing import Any
from 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 = None
self._gateway: GatewayClient | None = None
self._gateway_token: str = ""
self._mcps: list[MCPClient] = []
@@ -273,19 +251,22 @@ class E2BWorkspace(WorkspaceBase):
return
await 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 upstream
MCPs. ``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 = None
self.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:
continue
try:
- 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 = content
lines.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.py
index 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 asyncio
import base64
import hashlib
@@ -12,32 +13,31 @@ from copy import deepcopy
from pathlib import Path
from typing import TypedDict
-import aiofiles
-import aiofiles.ospath
import frontmatter
from pydantic import AnyUrl
-from ._base import WorkspaceBase
+from .._logging import logger
from ..mcp import MCPClient
from ..message import (
- TextBlock,
+ Base64Source,
DataBlock,
- ToolResultBlock,
Msg,
+ TextBlock,
+ ToolResultBlock,
URLSource,
- Base64Source,
)
from ..skill import Skill
from ..tool import (
- ToolBase,
Bash,
Edit,
Glob,
Grep,
Read,
+ ToolBase,
Write,
)
-from .._logging import logger
+from ..tool._builtin._backend import LocalBackend
+from ._base import WorkspaceBase
class _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 MCPs
mcp_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 frontmatter
content = frontmatter.loads(content_str)
@@ -452,7 +452,9 @@ class LocalWorkspace(WorkspaceBase):
return skill_path, skill_name, skill_hash
async 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, avoiding
embedding 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 path
async 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 conflict
index = 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.url
else:
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 path
async 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 indexing
if 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):
return
skill_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.py
index 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 under
import importlib.resources as _res
from 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
index 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 os
import sys
import unittest
from unittest.async_case import IsolatedAsyncioTestCase
from 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 TextBlock
from 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.py
index 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 base64
import hashlib
import os
@@ -40,6 +41,7 @@ from urllib.parse import urlparse
import aiofiles
from agentscope.message import (
+ AssistantMsg,
Base64Source,
DataBlock,
Msg,
@@ -48,7 +50,6 @@ from agentscope.message import (
ToolResultState,
URLSource,
UserMsg,
- AssistantMsg,
)
from agentscope.permission import PermissionBehavior, PermissionDecision
from 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()