Build and run agents you can see, understand and trust.
Python agentchatbotlarge-language-modelsllmllm-agentmcpmulti-agentmulti-modalreact-agentrealtime-agentvoice-agentvoice-assistant
refactor(workspace): re-organize the code implementation logic of the workspace (#1971)
DavdGao51f15fc2eda5
diff --git a/README.md b/README.mdindex 201591fc8..d3ab8dcd1 100644--- a/README.md+++ b/README.md@@ -73,6 +73,7 @@ rather than constraining them with strict prompts and opinionated orchestrations## News<!-- BEGIN NEWS -->+- **[2026-06] `FEAT`:** Agentic Memory supported. [Example](https://github.com/agentscope-ai/agentscope/tree/main/examples/long_term_memory/agentic_memory) | [Docs](https://docs.agentscope.io/latest/en/building-blocks/long-term-memory)- **[2026-06] `FEAT`:** Distributed & Multi-Tenancy & Multi-Session RAG service supported. [Docs](https://docs.agentscope.io/latest/en/deploy/agent-team)- **[2026-06] `FEAT`:** RAG supported. [Example](https://github.com/agentscope-ai/agentscope/tree/main/examples/rag) | [Docs](https://docs.agentscope.io/latest/en/building-blocks/rag)- **[2026-06] `INTE`:** Mem0 supported. [Example](https://github.com/agentscope-ai/agentscope/tree/main/examples/long_term_memory) | [Docs](https://docs.agentscope.io/latest/en)diff --git a/README_zh.md b/README_zh.mdindex e432138c3..479e4238e 100644--- a/README_zh.md+++ b/README_zh.md@@ -79,6 +79,7 @@ AgentScope 2.0 是一款面向生产、易于使用的智能体框架,提供## 新闻<!-- BEGIN NEWS -->+- **[2026-06] `功能`:** 支持 Agentic Memory。 [样例](https://github.com/agentscope-ai/agentscope/tree/main/examples/long_term_memory/agentic_memory) | [文档](https://docs.agentscope.io/latest/zh/building-blocks/long-term-memory)- **[2026-06] `功能`:** 支持分布式 & 多租户 & 多会话 RAG 服务。 [文档](https://docs.agentscope.io/latest/en/deploy/agent-team)- **[2026-06] `功能`:** 支持多模态 RAG。 [样例](https://github.com/agentscope-ai/agentscope/tree/main/examples/rag) | [文档](https://docs.agentscope.io/latest/en/building-blocks/rag)- **[2026-06] `集成`:** 集成 Mem0 长期记忆。 [Example](https://github.com/agentscope-ai/agentscope/tree/main/examples/long_term_memory) | [Docs](https://docs.agentscope.io/latest/zh)diff --git a/src/agentscope/tool/_builtin/_backend.py b/src/agentscope/tool/_builtin/_backend.pyindex fbac19dfd..a777312f3 100644--- a/src/agentscope/tool/_builtin/_backend.py+++ b/src/agentscope/tool/_builtin/_backend.py@@ -174,6 +174,20 @@ class BackendBase(ABC):"""return self._path_module.dirname(path)+ def basename(self, path: str) -> str:+ """Return the final component of ``path``.++ Args:+ path (`str`):+ A path inside the backend's environment.++ Returns:+ `str`:+ Everything after the last path separator. Empty string+ if ``path`` ends with a separator.+ """+ return self._path_module.basename(path)+def isabs(self, path: str) -> bool:"""Return ``True`` if ``path`` is absolute in the backend.diff --git a/src/agentscope/workspace/_base.py b/src/agentscope/workspace/_base.pyindex b82fa46f1..f828270f6 100644--- a/src/agentscope/workspace/_base.py+++ b/src/agentscope/workspace/_base.py@@ -1,5 +1,5 @@# -*- coding: utf-8 -*--"""WorkspaceBase — abstract interface for agent workspaces.+"""WorkspaceBase — abstract interface and shared backend-driven impl.A workspace provides:@@ -10,44 +10,101 @@ A workspace provides:Three concrete implementations:-- `LocalWorkspace` — local filesystem.-- `DockerWorkspace` — Docker container.-- `E2BWorkspace` — E2B cloud sandbox.+- :class:`agentscope.workspace.LocalWorkspace` — local filesystem.+- :class:`agentscope.workspace.DockerWorkspace` — Docker container.+- :class:`agentscope.workspace.E2BWorkspace` — E2B cloud sandbox.Consumers:- **Agent** — calls ``list_mcps``, ``list_skills``, ``list_tools``,``offload_context``, ``offload_tool_result``.- **User** — dynamically adds/removes MCPs and skills via- ``add_mcp``, ``remove_mcp``, ``add_skill``, ``remove_skill``.+ ``add_mcp`` / ``remove_mcp`` / ``add_skill`` / ``remove_skill``.- **Developer** — manages lifecycle via ``initialize`` / ``close``.-- **Backend consumers** access the active backend via ``get_backend``.+- **Backend consumers** access the active backend via :meth:`get_backend`.++Shared implementation+---------------------++The base class implements every operation that can be expressed against+the workspace's :class:`BackendBase` plus a fixed layout derived from+``workdir``:++.. code-block:: text++ {workdir}/+ ├── .mcp # persisted MCP client configs (JSON array)+ ├── data/ # offloaded multimodal payloads+ ├── skills/ # skill subdirectories+ └── sessions/ # per-session context and tool-result files++Subclasses only set ``self.workdir`` (the agent-visible root); all+other directory paths are derived via :meth:`BackendBase.join_path`,+keeping path semantics consistent with whichever backend is bound."""+import asyncio+import base64+import hashlib+import io+import json+import mimetypes+import os+import tarfilefrom abc import abstractmethod+from copy import deepcopy+from pathlib import Pathfrom typing import Self+from pydantic import AnyUrl++from .._logging import loggerfrom .._utils._common import _generate_idfrom ..mcp import MCPClient-from ..message import Msg, ToolResultBlock+from ..message import (+ Base64Source,+ DataBlock,+ Msg,+ TextBlock,+ ToolResultBlock,+ URLSource,+)from ..skill import Skillfrom ..tool import BackendBase, ToolBase+_EXTRACT_TAR_SHIM = (+ "import tarfile, sys, os\n"+ "src, dst = sys.argv[1], sys.argv[2]\n"+ "os.makedirs(dst, exist_ok=True)\n"+ "dst_real = os.path.realpath(dst)\n"+ "tf = tarfile.open(src)\n"+ "try:\n"+ " members = tf.getmembers()\n"+ " for m in members:\n"+ " target = os.path.realpath(os.path.join(dst, m.name))\n"+ " if not (target == dst_real"+ " or target.startswith(dst_real + os.sep)):\n"+ " raise Exception('unsafe tar member: ' + m.name)\n"+ " tf.extractall(dst, members=members)\n"+ "finally:\n"+ " tf.close()\n"+ "os.unlink(src)\n"+)+class WorkspaceBase:"""Abstract base class for all workspace implementations.Subclasses provide concrete behaviour for one execution backend(local filesystem, Docker container, E2B sandbox). The base class- only fixes the lifecycle contract (``initialize`` / ``close`` /- ``reset``), the ``async with`` protocol, and the discovery /- offload / add-remove method signatures consumed by ``Agent`` and- by the workspace manager layer.-- State held on the base class is intentionally minimal:- ``workspace_id`` (stable identifier, generated if not given) and- ``is_alive`` (lifecycle flag). All backend-specific state lives on- the subclass.+ owns:++ - lifecycle scaffolding (``async with`` protocol, ``is_alive``);+ - the canonical workspace layout derived from ``workdir`` (data/,+ skills/, sessions/, .mcp);+ - shared backend-driven implementations of offload, MCP+ persistence and a basic skill manager that subclasses can+ override (LocalWorkspace does, with a hash-indexed variant)."""workspace_id: str@@ -62,10 +119,120 @@ class WorkspaceBase:_backend: BackendBase | None"""Current execution backend, available through :meth:`get_backend`."""- def __init__(self, workspace_id: str | None) -> None:- """Initialize the workspace base instance."""+ default_mcps: list[MCPClient]+ """MCP clients to seed on first :meth:`initialize` when the+ persisted ``.mcp`` file is absent."""++ skill_paths: list[str]+ """Local skill directories to seed on first :meth:`initialize`."""++ _mcps: list[MCPClient]+ """Currently registered MCP clients (in-memory authoritative copy).++ For sandbox-gateway subclasses this list mirrors the spec the+ gateway was registered with (live handles hang off+ :class:`SandboxedWorkspaceBase._gateway_clients`); for+ :class:`LocalWorkspace` it *is* the live handle list.+ """++ _mcp_lock: asyncio.Lock+ """Guards mutation of :attr:`_mcps` and the ``.mcp`` file."""++ _skill_lock: asyncio.Lock+ """Guards mutation of the ``skills/`` directory."""++ _glob_helper_path: str | None = None+ """Optional path (backend-side) to the ``Glob`` helper script.++ ``None`` means the :class:`Glob` builtin tool falls back to its+ default behaviour (suitable for :class:`LocalBackend`). Remote+ backends override this with a sandbox-/container-side script path+ so :class:`Glob` can run efficiently inside the workspace.+ """++ def __init__(+ self,+ *,+ workspace_id: str | None = None,+ default_mcps: list[MCPClient] | None = None,+ skill_paths: list[str] | None = None,+ ) -> None:+ """Initialise the shared workspace state.++ Subclasses must call ``super().__init__`` and then set+ :attr:`workdir` themselves before any base-class method is+ invoked. Backend binding (``self._backend``) is left to the+ subclass (Local sets it eagerly; Docker/E2B set it during+ :meth:`initialize`).++ Args:+ workspace_id (`str | None`, optional):+ Existing identifier to adopt; ``None`` mints a fresh+ UUID.+ default_mcps (`list[MCPClient] | None`, optional):+ MCP clients to register when the workspace boots+ without a persisted ``.mcp`` file.+ skill_paths (`list[str] | None`, optional):+ Local skill directories to copy into ``skills/`` on+ first start.+ """self.workspace_id = workspace_id or _generate_id()self.is_alive = False+ self._backend = None++ self.default_mcps = list(default_mcps or [])+ self.skill_paths = list(skill_paths or [])++ self._mcps = []+ self._mcp_lock = asyncio.Lock()+ self._skill_lock = asyncio.Lock()++ # ── derived paths ──────────────────────────────────────────────++ @property+ def _data_dir(self) -> str:+ """``${workdir}/data`` — offloaded multimodal payloads."""+ return self.get_backend().join_path(self.workdir, "data")++ @property+ def _skills_dir(self) -> str:+ """``${workdir}/skills`` — skill subdirectories."""+ return self.get_backend().join_path(self.workdir, "skills")++ @property+ def _sessions_dir(self) -> str:+ """``${workdir}/sessions`` — per-session offload files."""+ return self.get_backend().join_path(self.workdir, "sessions")++ @property+ def _mcp_file(self) -> str:+ """``${workdir}/.mcp`` — persisted MCP registrations."""+ return self.get_backend().join_path(self.workdir, ".mcp")++ @property+ def is_persistent(self) -> bool:+ """Whether the workspace storage survives :meth:`close`.++ Defaults to ``True``. Subclasses with conditional persistence+ (e.g. :class:`DockerWorkspace` without a host bind-mount)+ override this to gate the cost of writing ``.mcp`` and other+ files that would not survive the next session.+ """+ return True++ @staticmethod+ def _path_to_file_uri(path: str) -> str:+ """Convert an absolute backend-side path to a ``file://`` URI.++ Absolute POSIX paths (every remote backend, plus+ :class:`LocalBackend` on Linux/macOS) start with ``/`` and use+ the plain ``file://{path}`` form. Windows absolute paths+ (e.g. ``C:\\Users\\...``) round-trip through+ :meth:`pathlib.Path.as_uri` to produce ``file:///C:/...`` form.+ """+ if path.startswith("/"):+ return f"file://{path}"+ return Path(path).as_uri()# ── lifecycle (developer) ──────────────────────────────────────@@ -102,13 +269,12 @@ class WorkspaceBase:If the workspace has not been initialized or has no activebackend."""- backend = getattr(self, "_backend", None)- if not isinstance(backend, BackendBase):+ if self._backend is None:raise RuntimeError(f"{type(self).__name__} has no active backend. ""Initialize the workspace before requesting its backend.",)- return backend+ return self._backendasync def __aenter__(self) -> Self:"""Context manager support for ``async with``. Calls ``initialize()``@@ -131,23 +297,148 @@ class WorkspaceBase:async def get_instructions(self) -> str:"""Workspace-specific system prompt fragment."""- # ── for Agent: tool & resource discovery ───────────────────────+ # ── for Agent: tool & MCP discovery ────────────────────────────- @abstractmethodasync def list_tools(self) -> list[ToolBase]:- """Built-in tools scoped to this workspace."""+ """Built-in tools scoped to this workspace.++ Returns the six builtin tools (:class:`Bash`, :class:`Edit`,+ :class:`Glob`, :class:`Grep`, :class:`Read`, :class:`Write`),+ each bound to the workspace's active backend so that all+ filesystem and process I/O happens inside the workspace's+ execution environment. :class:`Bash` is rooted at+ :attr:`workdir`; :class:`Glob` receives the optional+ :attr:`_glob_helper_path` when the backend ships one.++ Raises:+ RuntimeError:+ If the workspace has not been initialised yet.+ """+ from ..tool import Bash, Edit, Glob, Grep, Read, Write++ backend = self.get_backend()+ glob_kwargs: dict = {"backend": backend}+ if self._glob_helper_path is not None:+ glob_kwargs["glob_helper_path"] = self._glob_helper_path+ return [+ Bash(cwd=self.workdir, backend=backend),+ Edit(backend=backend),+ Glob(**glob_kwargs),+ Grep(backend=backend),+ Read(backend=backend),+ Write(backend=backend),+ ]- @abstractmethodasync def list_mcps(self) -> list[MCPClient]:- """Active MCP clients (each provides its own tools)."""+ """Return the currently registered MCP clients."""+ return list(self._mcps)++ # ── for User: dynamic MCP management ───────────────────────────@abstractmethod- async def list_skills(self) -> list[Skill]:- """Skills available in this workspace."""+ async def add_mcp(self, mcp_client: MCPClient) -> None:+ """Register a new MCP server.- # ── for Agent: offload ─────────────────────────────────────────+ Args:+ mcp_client (`MCPClient`):+ The MCP to register.++ Raises:+ `ValueError`:+ If an MCP with the same name already exists.+ """@abstractmethod+ async def remove_mcp(self, name: str) -> None:+ """Deregister an MCP server by name.++ Args:+ name (`str`):+ MCP name to remove. Unknown names log a warning and+ return silently.+ """++ # ── MCP persistence (shared) ───────────────────────────────────++ async def _save_mcp_file(self) -> None:+ """Persist ``self._mcps`` to ``${workdir}/.mcp`` via backend.++ No-op when :attr:`is_persistent` is ``False`` (e.g. ephemeral+ Docker container without a host bind-mount). Failures are+ logged but not raised — the in-memory MCP list remains the+ authoritative copy regardless of whether disk persistence+ succeeded.++ Callers are expected to hold :attr:`_mcp_lock` already.+ """+ if not self.is_persistent:+ return+ backend = self._backend+ if backend is None:+ return+ payload = json.dumps(+ [m.model_dump(mode="json") for m in self._mcps],+ indent=2,+ ensure_ascii=False,+ ).encode("utf-8")+ try:+ await backend.write_file(self._mcp_file, payload)+ except Exception as e:+ logger.warning(+ "Failed to save MCP file at %s: %s",+ self._mcp_file,+ e,+ )++ async def _restore_or_seed_mcps(self) -> list[MCPClient]:+ """Read ``${workdir}/.mcp`` if present, else return ``default_mcps``.++ Decoding / validation failures are downgraded to warnings and+ treated as a missing file — :attr:`default_mcps` is returned so+ a corrupted persistence file cannot block startup.+ """+ if not self.is_persistent:+ return list(self.default_mcps)+ backend = self._backend+ if backend is None:+ return list(self.default_mcps)+ try:+ if not await backend.file_exists(self._mcp_file):+ return list(self.default_mcps)+ raw = await backend.read_file(self._mcp_file)+ except (FileNotFoundError, OSError) as e:+ logger.warning(+ "Failed to read MCP file at %s, falling back to "+ "default_mcps: %s",+ self._mcp_file,+ e,+ )+ return list(self.default_mcps)+ try:+ data = json.loads(raw.decode("utf-8"))+ except Exception as e:+ logger.warning(+ "Failed to parse MCP file at %s, falling back to "+ "default_mcps: %s",+ self._mcp_file,+ e,+ )+ return list(self.default_mcps)+ result: list[MCPClient] = []+ for m in data:+ try:+ result.append(MCPClient.model_validate(m))+ except Exception as e:+ name = m.get("name", "?") if isinstance(m, dict) else "?"+ logger.warning(+ "Skipping invalid MCP entry %r: %s",+ name,+ e,+ )+ return result++ # ── for Agent: offload (shared) ────────────────────────────────+async def offload_context(self,session_id: str,@@ -155,76 +446,332 @@ class WorkspaceBase:) -> str:"""Persist compressed context for agentic retrieval.+ Appends every message in ``msgs`` to+ ``${workdir}/sessions/<session_id>/context.jsonl`` (one+ message per JSONL line). Inline base64+ :class:`DataBlock` payloads are extracted into ``data/`` and+ rewritten as ``file://`` URL blocks before serialisation so+ the JSONL line size stays bounded.+Args:- session_id: Unique session identifier used to- partition offloaded data.- msgs: Conversation messages to offload.+ session_id (`str`):+ Session-scope key used to partition offloaded data+ (one subdirectory per session).+ msgs (`list[Msg]`):+ Conversation messages to offload. Not mutated — a+ deep copy is used internally.Returns:- Path or identifier for the offloaded data.+ `str`:+ Backend-side path of the JSONL file that received+ the new lines."""+ backend = self.get_backend()+ base = backend.join_path(self._sessions_dir, session_id)+ path = backend.join_path(base, "context.jsonl")++ copied = deepcopy(msgs)+ lines: list[str] = []+ for msg in copied:+ if not isinstance(msg.content, str):+ content: list = []+ for block in msg.content:+ if isinstance(block, DataBlock) and isinstance(+ block.source,+ Base64Source,+ ):+ block = await self._offload_data_block(block)+ content.append(block)+ msg.content = content+ lines.append(msg.model_dump_json())++ payload = "\n".join(lines) + "\n"++ existing = b""+ try:+ existing = await backend.read_file(path)+ except (FileNotFoundError, OSError):+ pass+ await backend.write_file(path, existing + payload.encode("utf-8"))+ return path- @abstractmethodasync def offload_tool_result(self,session_id: str,tool_result: ToolResultBlock,) -> str:- """Persist a tool result for agentic retrieval.+ """Persist a single tool result as a flat text file.++ Writes ``${workdir}/sessions/<session_id>/tool_result-<id>.txt``.+ Text blocks are concatenated verbatim; :class:`DataBlock` items+ emit ``<data url='…' name='…' media_type='…'/>`` placeholders,+ with inline base64 payloads first offloaded to ``data/``.++ On a filename clash (same tool-result ``id`` written twice in+ one session) the new file is suffixed with ``(1)``, ``(2)``,+ … to avoid clobbering the prior content.Args:- session_id: Unique session identifier used to- partition offloaded data.- tool_result: The tool result block to offload.+ session_id (`str`):+ Session-scope key used to partition offloaded data.+ tool_result (`ToolResultBlock`):+ The tool result block to persist.Returns:- Path or identifier for the offloaded data.+ `str`:+ Backend-side path of the offloaded text file."""-- # ── for User: dynamic MCP management ───────────────────────────-- @abstractmethod- async def add_mcp(self, mcp_client: MCPClient) -> None:- """Dynamically register a new MCP server.+ backend = self.get_backend()+ base = backend.join_path(self._sessions_dir, session_id)+ path = backend.join_path(base, f"tool_result-{tool_result.id}.txt")++ index = 1+ while await backend.file_exists(path):+ path = backend.join_path(+ base,+ f"tool_result-{tool_result.id}({index}).txt",+ )+ index += 1++ parts: list[str] = []+ if isinstance(tool_result.output, str):+ parts.append(tool_result.output)+ else:+ for block in tool_result.output:+ if isinstance(block, TextBlock):+ parts.append(block.text)+ elif isinstance(block, DataBlock):+ if isinstance(block.source, Base64Source):+ d = await self._offload_data_block(block)+ url = str(d.source.url)+ else:+ url = str(block.source.url)+ parts.append(+ f"<data url='{url}' name='{block.name}' "+ f"media_type='{block.source.media_type}'/>",+ )++ await backend.write_file(path, "".join(parts).encode("utf-8"))+ return path++ async def _offload_data_block(self, block: DataBlock) -> DataBlock:+ """Persist a base64 :class:`DataBlock` under ``data/``.++ The decoded payload is stored at+ ``${workdir}/data/<sha256-of-base64>.<ext>``. Hashing the+ *base64* text rather than the decoded bytes lets a second+ offload of the same block short-circuit (same key → same+ file → no write).Args:- mcp_client: An :class:`MCPClient` instance describing- the MCP server to add.+ block (`DataBlock`):+ A data block. Blocks already backed by a+ :class:`URLSource` are returned unchanged.- Raises:- ValueError: If an MCP with the same name already exists.+ Returns:+ `DataBlock`:+ A new :class:`DataBlock` whose source is a ``file://``+ URL pointing at the persisted file inside the+ workspace."""+ if not isinstance(block.source, Base64Source):+ return block++ backend = self.get_backend()+ hash_str = hashlib.sha256(block.source.data.encode()).hexdigest()+ ext = mimetypes.guess_extension(block.source.media_type) or ".bin"+ path = backend.join_path(self._data_dir, f"{hash_str}{ext}")++ if not await backend.file_exists(path):+ await backend.write_file(+ path,+ base64.b64decode(block.source.data),+ )- @abstractmethod- async def remove_mcp(self, name: str) -> None:- """Dynamically remove an MCP server by name.+ return DataBlock(+ id=block.id,+ name=block.name,+ source=URLSource(+ url=AnyUrl(self._path_to_file_uri(path)),+ media_type=block.source.media_type,+ ),+ )- Args:- name: Name of the MCP server to remove.- """+ # ── skill management (shared, simple) ──────────────────────────- # ── for User: dynamic skill management ─────────────────────────+ async def list_skills(self) -> list[Skill]:+ """Enumerate skills under ``${workdir}/skills``.++ Walks ``skills/`` recursively, parses every ``SKILL.md``'s+ YAML front matter, and yields one :class:`Skill` per file+ that has both ``name`` and ``description``.++ Subclasses with richer indexing (e.g.+ :class:`LocalWorkspace` with its ``.skills`` hash index)+ override this method.++ Returns:+ `list[Skill]`:+ Skills available to the agent. Empty when ``skills/``+ is missing or contains no parseable ``SKILL.md``.+ """+ import frontmatter as fm++ backend = self.get_backend()+ if not await backend.is_dir(self._skills_dir):+ return []++ entries = await backend.list_dir(self._skills_dir, recursive=True)++ skills: list[Skill] = []+ for md_path in entries:+ if backend.basename(md_path) != "SKILL.md":+ continue+ try:+ raw = await backend.read_file(md_path)+ doc = fm.loads(raw.decode("utf-8"))+ name = doc.get("name")+ desc = doc.get("description")+ if not name or not desc:+ continue+ skills.append(+ Skill(+ name=str(name),+ description=str(desc),+ dir=backend.dirname(md_path),+ markdown=doc.content or "",+ updated_at=0.0,+ ),+ )+ except Exception as e:+ logger.warning("Failed to load skill %s: %s", md_path, e)+ return skills- @abstractmethodasync def add_skill(self, skill_path: str) -> None:- """Add a skill from a local directory path.+ """Copy a local skill directory into ``${workdir}/skills``.++ Tars the directory on the host, writes the archive to the+ backend's tmp area, and extracts it via ``python3 -c`` inside+ the sandbox — two round trips regardless of skill size, and+ portable across any backend whose image ships ``python3``+ (same contract as the gateway shim).- The directory must contain a ``SKILL.md`` with ``name``- and ``description`` in its YAML front matter.+ Subclasses with richer dedup (e.g. :class:`LocalWorkspace`+ with hash-indexed conflict resolution) override this method.Args:- skill_path: Absolute or relative path to the skill- directory on the local filesystem.+ skill_path (`str`):+ Path to a skill directory on the local filesystem.++ Raises:+ ValueError:+ If ``SKILL.md`` is missing or a directory with the+ same basename already exists in ``skills/``.+ RuntimeError:+ If extraction inside the sandbox fails."""+ skill_md = os.path.join(skill_path, "SKILL.md")+ if not os.path.isfile(skill_md):+ raise ValueError(+ f"Invalid skill at {skill_path!r}: SKILL.md not found",+ )++ backend = self.get_backend()++ async with self._skill_lock:+ dir_name = os.path.basename(os.path.abspath(skill_path))+ remote_dir = backend.join_path(self._skills_dir, dir_name)++ if await backend.file_exists(remote_dir):+ raise ValueError(+ f"Skill directory {dir_name!r} already exists in "+ f"{self._skills_dir}",+ )++ buf = io.BytesIO()+ with tarfile.open(fileobj=buf, mode="w") as tf:+ tf.add(skill_path, arcname=dir_name)+ tar_bytes = buf.getvalue()++ tmp_path = f"/tmp/skill-{_generate_id()}.tar"+ await backend.write_file(tmp_path, tar_bytes)++ await backend.exec_shell(+ ["mkdir", "-p", self._skills_dir],+ )+ result = await backend.exec_shell(+ [+ "python3",+ "-c",+ _EXTRACT_TAR_SHIM,+ tmp_path,+ self._skills_dir,+ ],+ )+ if not result.ok():+ raise RuntimeError(+ f"Failed to extract skill {dir_name!r}: "+ f"{result.stderr.decode('utf-8', 'replace')}",+ )++ logger.info("Added skill %r at %s", dir_name, remote_dir)- @abstractmethodasync def remove_skill(self, name: str) -> None:- """Remove a skill by its agent-facing name.+ """Remove a skill by its agent-facing ``name`` (front matter).++ Looks up the skill via :meth:`list_skills` and ``rm -rf``-style+ deletes its directory through the backend.Args:- name: The ``name`` field from the skill's- ``SKILL.md`` front matter.+ name (`str`):+ The agent-facing name of the skill to remove.Raises:- KeyError: If the skill is not found in the workspace.+ KeyError:+ If the skill is not found in the workspace.+ """+ backend = self.get_backend()+ skills = await self.list_skills()+ target_dir: str | None = None+ for s in skills:+ if s.name == name:+ target_dir = s.dir+ break+ if target_dir is None:+ available = [s.name for s in skills]+ raise KeyError(+ f"Skill {name!r} not found. Available: {available}",+ )+ await backend.delete_path(target_dir)+ logger.info("Removed skill %r at %s", name, target_dir)++ async def _seed_skills(self) -> None:+ """Copy :attr:`skill_paths` into ``${workdir}/skills`` once.++ Skips seeding when:++ - :attr:`skill_paths` is empty;+ - the backend is not bound; or+ - ``skills/`` already contains entries (assume the prior+ run, or the user, is the source of truth).++ Individual failures are logged and skipped — a single bad+ skill cannot block startup."""+ if not self.skill_paths:+ return+ backend = self._backend+ if backend is None:+ return+ entries = await backend.list_dir(self._skills_dir)+ if entries:+ return+ for path in self.skill_paths:+ try:+ await self.add_skill(path)+ except Exception as e:+ logger.warning(+ "Skip skill %r: %s",+ path,+ e,+ )diff --git a/src/agentscope/workspace/_docker/_docker_workspace.py b/src/agentscope/workspace/_docker/_docker_workspace.pyindex 22a670e7c..152213fe4 100644--- a/src/agentscope/workspace/_docker/_docker_workspace.py+++ b/src/agentscope/workspace/_docker/_docker_workspace.py@@ -25,46 +25,18 @@ and shipped into the container via the gateway config file — it is*not* persisted."""-import asyncio-import base64-import hashlibimport io-import json-import mimetypesimport os-import posixpath-import shleximport shutilimport sysimport tarfile-import uuid-from copy import deepcopyfrom typing import Any-from pydantic import AnyUrl-from ..._logging import loggerfrom ...mcp import MCPClient-from ...message import (- Base64Source,- DataBlock,- Msg,- TextBlock,- ToolResultBlock,- URLSource,-)-from ...skill import Skill-from ...tool import ToolBase-from .._base import WorkspaceBase-from .._gateway_client import (- GatewayClient,- GatewayMCPClient,-)+from .._sandboxed_base import SandboxedWorkspaceBasefrom ._docker_backend import DockerBackendfrom ._make_dockerfile import (- CONTAINER_DATA_DIR,- CONTAINER_SESSIONS_DIR,- CONTAINER_SKILLS_DIR,CONTAINER_WORKDIR,DEFAULT_BASE_IMAGE,DEFAULT_GATEWAY_PORT,@@ -98,13 +70,20 @@ and processes.# ── the workspace ──────────────────────────────────────────────────-class DockerWorkspace(WorkspaceBase):+class DockerWorkspace(SandboxedWorkspaceBase):"""Workspace backed by a Docker container.``default_mcps`` and ``skill_paths`` are seed-time inputs and arenot retained as instance state past :meth:`initialize`."""+ _glob_helper_path = GLOB_HELPER_SCRIPT+ _gateway_home = GATEWAY_HOME+ _gateway_config = GATEWAY_CONFIG+ _gateway_log = GATEWAY_LOG+ _gateway_script = GATEWAY_SCRIPT+ _gateway_python = f"{GATEWAY_VENV}/bin/python"+def __init__(self,*,@@ -122,59 +101,37 @@ class DockerWorkspace(WorkspaceBase):) -> None:"""Construct a :class:`DockerWorkspace`.- The workspace is *not* started here; call :meth:`initialize`+ The workspace is *not* started here — call :meth:`initialize`(or use the workspace as an ``async`` context manager).Args:workspace_id (`str | None`, optional):- Existing workspace identifier to adopt. ``None``- generates a fresh UUID. When the same- ``workspace_id`` is paired with a persistent- ``workdir``, restarts are stable across processes.+ Existing workspace identifier to adopt; ``None`` mints+ a fresh UUID.base_image (`str`, defaults to `DEFAULT_BASE_IMAGE`):Base Docker image. Must provide ``python3`` in- ``$PATH`` (e.g. ``"python:3.11-slim"``). The image is- rebuilt on top of this base via the dynamic- Dockerfile (uv venv + agentscope install + optional- node + ``extra_pip``).+ ``$PATH``.host_workdir (`str | None`, optional):- Host directory bind-mounted to ``/workspace`` inside- the container. ``None`` makes the workspace- ephemeral — files written under ``/workspace`` live- only in the container's writable layer and are lost- on :meth:`close`. When set, the directory is created- on demand and the ``.mcp`` / ``skills/`` /- ``sessions/`` / ``data/`` layout is mirrored- host-side.+ Host directory bind-mounted to ``/workspace``. ``None``+ makes the workspace ephemeral.node_version (`str | None`, optional):- Major Node.js version to bake into the image (e.g.- ``"20"``). ``None`` skips Node entirely.+ Major Node.js version to bake into the image.extra_pip (`list[str] | None`, optional):- Extra Python packages to install into the gateway- venv at image-build time.+ Extra Python packages installed into the gateway venv+ at image-build time.gateway_port (`int`, defaults to `DEFAULT_GATEWAY_PORT`):- TCP port the gateway listens on inside the- container; always exposed to a randomly assigned- host port.+ TCP port the gateway listens on inside the container+ (no host port mapping).env (`dict[str, str] | None`, optional):Environment variables to set inside the container.instructions (`str`, defaults to `_DEFAULT_INSTRUCTIONS`):- System-prompt fragment template returned by- :meth:`get_instructions`. Supports the ``{workdir}``- placeholder, replaced with the container-side path.+ System-prompt fragment template; supports ``{workdir}``.default_mcps (`list[MCPClient] | None`, optional):- Initial MCPs registered on first :meth:`initialize`.- On subsequent restarts with a persistent ``workdir``- these are ignored in favour of the persisted- ``<workdir>/.mcp`` file.+ MCPs registered on first init when no persisted+ ``.mcp`` exists.skill_paths (`list[str] | None`, optional):- Local skill directories seeded into- ``<workdir>/skills`` on first :meth:`initialize`- (only when ``workdir`` is set; subsequent starts- treat the host directory as the source of truth).+ Local skill dirs seeded into ``skills/`` on first init."""- super().__init__(workspace_id=workspace_id)-# Backwards compatibility: accept legacy ``workdir`` kwarg.if "workdir" in kwargs:logger.warning(@@ -184,6 +141,12 @@ class DockerWorkspace(WorkspaceBase):if host_workdir is None:host_workdir = kwargs.pop("workdir")+ super().__init__(+ workspace_id=workspace_id,+ default_mcps=default_mcps,+ skill_paths=skill_paths,+ )+# ── serializable config ─────────────────────────────────self.workdir = CONTAINER_WORKDIRself.base_image = base_image@@ -194,159 +157,37 @@ class DockerWorkspace(WorkspaceBase):self.env: dict[str, str] = dict(env or {})self.instructions = instructions- # ── seed-only ───────────────────────────────────────────- self.default_mcps: list[MCPClient] = list(default_mcps or [])- self.skill_paths: list[str] = list(skill_paths or [])-- # ── runtime state ───────────────────────────────────────+ # ── runtime state (Docker-only) ─────────────────────────self._client: Any = None # aiodocker.Dockerself._container: Any = Noneself._backend: DockerBackend | None = None- self._port_mapping: dict[int, int] = {}self._image_tag: str = ""- self._gateway: GatewayClient | None = None- self._gateway_token: str = ""- self._mcps: list[MCPClient] = []- self._gateway_clients: dict[str, GatewayMCPClient] = {}- self._mcp_lock = asyncio.Lock()- self._skill_lock = asyncio.Lock()-- # ── lifecycle ───────────────────────────────────────────────-- async def initialize(self) -> None:- """Build / reuse the image, start the container, launch the gateway.-- Steps:-- 1. Build the workspace image (or reuse a tag-cache hit).- 2. Restore MCPs from ``<workdir>/.mcp`` if present, else seed- from ``default_mcps``.- 3. Mint a fresh gateway bearer token (not persisted).- 4. Start the container with the gateway port mapped to a host- port and ``workdir`` (if any) bind-mounted.- 5. Drop ``gateway.config.json`` into the container, launch the- gateway via ``python -m agentscope.workspace._mcp_gateway``,- and wait for ``/health`` to return 200.- 6. Pull the gateway-side MCP view back as- :class:`GatewayMCPClient` instances.- 7. Persist ``.mcp`` and seed skills (only when ``workdir`` is- set).- Idempotent — calling on an already-alive workspace is a no-op.+ @property+ def is_persistent(self) -> bool:+ """``True`` iff a host bind-mount preserves the workspace."""+ return self.host_workdir is not None- Raises:- RuntimeError: If the image build fails, the gateway port- fails to bind, or the gateway does not become healthy- within 30 seconds.- """- if self.is_alive:- return+ # ── lifecycle hooks ─────────────────────────────────────────+ async def _provision_backend(self) -> None:+ """Build / reuse the image and start the container."""import aiodockerself._client = aiodocker.Docker()-await self._build_or_reuse_image()-- self._mcps = await self._restore_or_seed_mcps()-- self._gateway_token = uuid.uuid4().hex-await self._create_and_start_container()- await self._write_gateway_config()- await self._start_gateway_process()-- host_port = self._port_mapping[self.gateway_port]- self._gateway = GatewayClient(- base_url=f"http://127.0.0.1:{host_port}",- token=self._gateway_token,- timeout=30.0,- )- await self._wait_for_gateway()-- # Pull back the gateway-side MCP view as GatewayMCPClient instances.- # The gateway loaded these from the config we just wrote, so the set- # matches self._mcps name-for-name.- self._gateway_clients = {- c.name: c for c in await self._gateway.list_mcps()- }-- if self.host_workdir is not None:- await self._save_mcp_file()- await self._seed_skills()-- self.is_alive = True-- async def reset(self) -> None:- """Return the workspace to an empty state.-- Deregisters every MCP from the gateway (``DELETE /mcps/{name}``- for each), clears the local handles, and wipes ``.mcp``,- ``skills/``, ``sessions/``, and ``data/`` inside the container.- 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:- await gw_client.close()- except Exception as e:- logger.warning(- "MCP %r close failed during reset: %s",- gw_client.name,- e,- )- self._gateway_clients.clear()- self._mcps = []-- for path in (- CONTAINER_SESSIONS_DIR,- CONTAINER_DATA_DIR,- CONTAINER_SKILLS_DIR,- ):- 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- # if the file were missing).- if self.host_workdir is not None:- await self._save_mcp_file()-- async def close(self) -> None:+ async def _teardown_backend(self) -> None:"""Stop and remove the container; release the aiodocker client.- The cached image and the host ``workdir`` are intentionally- left behind — a subsequent :meth:`initialize` reuses both.- Errors during gateway/container teardown are swallowed so- that ``close`` is always safe to call (e.g. from- ``__aexit__``).+ Errors are swallowed so teardown is always safe."""- if self._gateway is not None:- try:- await self._gateway.aclose()- except Exception:- pass- self._gateway = None- self._gateway_clients.clear()-if self._container is not None:- # Linux native docker preserves container-side ownership on- # bind-mounted host paths verbatim — files written by the- # in-container root process land on host as root, so a- # non-root host user (CI runner, IDE user) cannot remove- # them. macOS Docker Desktop / Windows Docker remap uids- # transparently, so this only matters on Linux. Best-effort:- # exec failures are swallowed, and we still tear the- # container down.+ # On Linux native docker, the in-container root process+ # writes bind-mount files with container-side ownership;+ # restore ownership to the host user so they can be+ # removed. macOS/Windows Docker remap uids transparently.if (self.host_workdir is not Noneand sys.platform == "linux"@@ -373,7 +214,6 @@ class DockerWorkspace(WorkspaceBase):except Exception:passself._container = None- self._backend = Noneif self._client is not None:try:@@ -382,377 +222,13 @@ class DockerWorkspace(WorkspaceBase):passself._client = None- self.is_alive = False-# ── instructions ────────────────────────────────────────────async def get_instructions(self) -> str:- """Return the system-prompt fragment for this workspace.-- The configured ``instructions`` template is formatted with the- container-side ``{workdir}`` (i.e. ``/workspace``), since the- agent always sees container-internal paths.- """+ """Return the system-prompt fragment, formatted with the+ container-side ``{workdir}``."""return self.instructions.format(workdir=CONTAINER_WORKDIR)- # ── tool / MCP / skill discovery ────────────────────────────-- async def list_tools(self) -> list[ToolBase]:- """Built-in tools exposed by the workspace itself.-- 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.- """- 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.-- Each entry's ``name`` matches the upstream MCP server name and- all of its protocol calls (connect / close / list_tools /- get_tool / tool ``__call__``) are routed over HTTP to the- in-container gateway.- """- return list(self._gateway_clients.values())-- async def list_skills(self) -> list[Skill]:- """Enumerate skills by scanning ``skills/`` inside the container.-- For each ``SKILL.md`` found, parses the YAML front-matter and- yields a :class:`Skill`. Files missing a ``name`` or- ``description`` field are skipped.-- Returns:- Skills available to the agent. Empty when the directory- is missing or contains no parseable ``SKILL.md`` files.- """- import frontmatter as fm-- 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 []- listing = result.stdout.decode(errors="replace").strip()- if not listing:- return []-- skills: list[Skill] = []- for md_path in (line.strip() for line in listing.split("\n")):- if not md_path:- continue- try:- raw = await self._backend.read_file(md_path)- doc = fm.loads(raw.decode("utf-8"))- name = doc.get("name")- desc = doc.get("description")- if not name or not desc:- continue- skills.append(- Skill(- name=str(name),- description=str(desc),- dir=posixpath.dirname(md_path),- markdown=doc.content or "",- updated_at=0.0,- ),- )- except Exception as e:- logger.warning("Failed to load skill %s: %s", md_path, e)- return skills-- # ── dynamic MCP management ──────────────────────────────────-- async def add_mcp(self, mcp_client: MCPClient) -> None:- """Register a new MCP server on the in-container gateway.-- Serialises the supplied client, registers it on the gateway- (which spawns the upstream MCP session inside the container),- and adds the corresponding :class:`GatewayMCPClient` handle to- :meth:`list_mcps`. The change is persisted to ``.mcp`` when- ``workdir`` is set.-- Args:- mcp_client: An :class:`MCPClient` describing the upstream- server (stdio / HTTP / SSE config). Its- ``model_dump()`` is what the gateway consumes, so any- ``MCPClient`` subclass is accepted.-- Raises:- ValueError: If an MCP with the same name is already- registered in this workspace.- RuntimeError: If the gateway rejects the registration- (e.g. upstream command not found inside the- container).- """- async with self._mcp_lock:- if mcp_client.name in self._gateway_clients:- raise ValueError(- f"MCP {mcp_client.name!r} already exists in workspace.",- )- spec = mcp_client.model_dump(mode="json")- gw_client = self._gateway.make_client(spec)- await gw_client.connect()- self._mcps.append(mcp_client)- self._gateway_clients[gw_client.name] = gw_client- if self.host_workdir is not None:- await self._save_mcp_file()-- async def remove_mcp(self, name: str) -> None:- """Unregister an MCP server by name.-- Tells the gateway to close the upstream session and drops the- :class:`GatewayMCPClient` handle from :meth:`list_mcps`. The- change is persisted to ``.mcp`` when ``workdir`` is set.-- Args:- name: The ``name`` field of the registered MCP. If no- MCP by that name exists, a warning is logged and the- call is a no-op (matching the silent behaviour of the- local workspace).- """- async with self._mcp_lock:- gw_client = self._gateway_clients.pop(name, None)- if gw_client is None:- logger.warning("MCP %r not found in workspace", name)- return- try:- await gw_client.close()- except Exception as e:- logger.warning("MCP %r close failed: %s", name, e)- self._mcps = [m for m in self._mcps if m.name != name]- if self.host_workdir is not None:- await self._save_mcp_file()-- # ── dynamic skill management ────────────────────────────────-- async def add_skill(self, skill_path: str) -> None:- """Copy a local skill directory into ``skills/`` inside the container.-- The directory must contain a ``SKILL.md`` with ``name`` and- ``description`` fields in its YAML front matter (validated- host-side before any container I/O). The directory is- tarred and uploaded via ``put_archive``; a directory of the- same basename already present in the container is rejected- rather than overwritten.-- Args:- skill_path: Absolute or relative path to a skill- directory on the host filesystem.-- Raises:- ValueError: If ``SKILL.md`` is missing, or a directory- with the same basename already exists in the- container's ``skills/``.- """- skill_md = os.path.join(skill_path, "SKILL.md")- if not os.path.isfile(skill_md):- raise ValueError(- f"Invalid skill at {skill_path!r}: SKILL.md not found",- )-- async with self._skill_lock:- 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._backend.exec_shell(- ["test", "-e", CONTAINER_SKILLS_DIR + "/" + dir_name],- )- if check.ok():- raise ValueError(- f"Skill directory {dir_name!r} already exists in "- f"{CONTAINER_SKILLS_DIR}",- )-- buf = io.BytesIO()- with tarfile.open(fileobj=buf, mode="w") as tf:- tf.add(skill_path, arcname=dir_name)- await self._container.put_archive(- CONTAINER_SKILLS_DIR,- buf.getvalue(),- )- logger.info(- "DockerWorkspace: added skill %r at %s/%s",- dir_name,- CONTAINER_SKILLS_DIR,- dir_name,- )-- async def remove_skill(self, name: str) -> None:- """Delete a skill directory by its agent-facing name.-- Looks up the skill by the ``name`` field of its- ``SKILL.md``, then ``rm -rf`` its directory inside the- container.-- Args:- name: The agent-facing skill name (the ``name`` value in- the SKILL.md front matter, *not* the directory name).-- Raises:- KeyError: If no skill with that ``name`` is found.- RuntimeError: If the in-container ``rm -rf`` returns a- non-zero exit code.- """- skills = await self.list_skills()- target_dir: str | None = None- for s in skills:- if s.name == name:- target_dir = s.dir- break- if target_dir is None:- available = [s.name for s in skills]- raise KeyError(- f"Skill {name!r} not found. Available: {available}",- )- await self._backend.delete_path(target_dir)-- # ── offload ─────────────────────────────────────────────────-- async def offload_context(- self,- session_id: str,- msgs: list[Msg],- ) -> str:- """Persist a batch of messages as JSONL inside the container.-- Each message is appended to- ``sessions/<session_id>/context.jsonl``. Inline base64- :class:`DataBlock` payloads are extracted into the shared- ``data/`` directory and rewritten as ``file://`` URL blocks- before serialisation, keeping the JSONL line size bounded.-- Args:- session_id (`str`):- Session-scope key used to partition offloaded files- (one subdirectory per session).- msgs (`list[Msg]`):- Messages to append. Not mutated — a deep copy is- used internally so the caller's blocks remain- base64-inline.-- Returns:- `str`:- The container-side path of the JSONL file that- received the new lines.- """- base = f"{CONTAINER_SESSIONS_DIR}/{session_id}"- path = f"{base}/context.jsonl"-- copied = deepcopy(msgs)- lines: list[str] = []- for msg in copied:- if not isinstance(msg.content, str):- content = []- for block in msg.content:- if isinstance(block, DataBlock) and isinstance(- block.source,- Base64Source,- ):- block = await self._offload_data_block(block)- content.append(block)- msg.content = content- lines.append(msg.model_dump_json())-- await self._backend.exec_shell(["mkdir", "-p", base])- existing = b""- try:- existing = await self._backend.read_file(path)- except (FileNotFoundError, OSError):- pass- await self._backend.write_file(- path,- existing + ("\n".join(lines) + "\n").encode("utf-8"),- )- return path-- async def offload_tool_result(- self,- session_id: str,- tool_result: ToolResultBlock,- ) -> str:- """Persist a single tool result as a flat text file.-- Writes ``sessions/<session_id>/tool_result-<id>.txt`` inside- the container. Text blocks are concatenated verbatim;- :class:`DataBlock` items are emitted as- ``<data url='…' name='…' media_type='…'/>`` placeholders,- with inline base64 payloads first offloaded to ``data/``.-- Args:- session_id (`str`):- Session-scope key used to partition offloaded files.- tool_result (`ToolResultBlock`):- The tool result block to persist.-- Returns:- `str`:- The container-side path of the offloaded text file.- """- base = f"{CONTAINER_SESSIONS_DIR}/{session_id}"- path = f"{base}/tool_result-{tool_result.id}.txt"-- parts: list[str] = []- if isinstance(tool_result.output, str):- parts.append(tool_result.output)- else:- for block in tool_result.output:- if isinstance(block, TextBlock):- parts.append(block.text)- elif isinstance(block, DataBlock):- if isinstance(block.source, Base64Source):- d = await self._offload_data_block(block)- url = str(d.source.url)- else:- url = str(block.source.url)- parts.append(- f"<data url='{url}' name='{block.name}' "- f"media_type='{block.source.media_type}'/>",- )-- await self._backend.exec_shell(["mkdir", "-p", base])- await self._backend.write_file(- path,- "".join(parts).encode("utf-8"),- )- return path-# ── internals: image build ──────────────────────────────────async def _build_or_reuse_image(self) -> None:@@ -839,22 +315,11 @@ class DockerWorkspace(WorkspaceBase):async def _create_and_start_container(self) -> None:"""Create + start the workspace container.- Wires up:-- * ``Cmd: ["sleep", "infinity"]`` so the container stays up- even when the gateway is restarted.- * ``ExposedPorts`` / ``PortBindings`` for ``gateway_port``- (random host port, ``127.0.0.1`` only).+ * ``Cmd: ["sleep", "infinity"]`` keeps it up across gateway+ restarts.* Optional bind mount ``host workdir → /workspace``.- * ``agentscope.workspace.id`` label for later discovery.-- Resolves the assigned host port into ``self._port_mapping``- and pre-creates the in-container persistence directories- (``data/`` / ``skills/`` / ``sessions/``).-- Raises:- RuntimeError: If the gateway port did not bind to any- host port (typically a docker daemon issue).+ * The gateway port stays internal — calls run from inside the+ sandbox via :class:`GatewayClient`, so no host port mapping."""config: dict[str, Any] = {"Image": self._image_tag,@@ -864,18 +329,11 @@ class DockerWorkspace(WorkspaceBase):"agentscope.workspace": "true","agentscope.workspace.id": self.workspace_id,},- "ExposedPorts": {f"{self.gateway_port}/tcp": {}},}if self.env:config["Env"] = [f"{k}={v}" for k, v in self.env.items()]- host_config: dict[str, Any] = {- "PortBindings": {- f"{self.gateway_port}/tcp": [- {"HostIp": "127.0.0.1", "HostPort": ""},- ],- },- }+ host_config: dict[str, Any] = {}if self.host_workdir is not None:os.makedirs(self.host_workdir, exist_ok=True)host_config["Binds"] = [@@ -889,238 +347,18 @@ class DockerWorkspace(WorkspaceBase):)await self._container.start()- info = await self._container.show()- ports_info = info.get("NetworkSettings", {}).get("Ports") or {}- bindings = ports_info.get(f"{self.gateway_port}/tcp", []) or []- if not bindings:- raise RuntimeError(- f"gateway port {self.gateway_port} did not bind to a "- "host port",- )- 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).+ # Pre-create the persistence directories (also shapes a newly+ # bind-mounted host workdir on first use).await self._backend.exec_shell(["mkdir","-p",- CONTAINER_DATA_DIR,- CONTAINER_SKILLS_DIR,- CONTAINER_SESSIONS_DIR,+ self._data_dir,+ self._skills_dir,+ self._sessions_dir,],)-- async def _restore_or_seed_mcps(self) -> list[MCPClient]:- """Decide the MCP set to ship to the gateway on startup.-- * No ``workdir`` → return ``default_mcps`` (purely ephemeral).- * ``workdir`` set, ``<workdir>/.mcp`` missing → return- ``default_mcps`` and let the next ``_save_mcp_file`` write- it.- * ``<workdir>/.mcp`` present → :meth:`MCPClient.model_validate`- each entry and return them. A read / parse error is- logged and the call falls back to ``default_mcps`` rather- than crashing the whole workspace.-- Returns:- The MCPClient instances to register on the gateway.- """- if self.host_workdir is None:- return list(self.default_mcps)- host_mcp = os.path.join(self.host_workdir, ".mcp")- if not os.path.isfile(host_mcp):- return list(self.default_mcps)- try:- with open(host_mcp, encoding="utf-8") as f:- data = json.load(f)- return [MCPClient.model_validate(m) for m in data]- except Exception as e:- logger.warning(- "DockerWorkspace: failed to read %s, falling back to "- "default_mcps: %s",- host_mcp,- e,- )- return list(self.default_mcps)-- async def _save_mcp_file(self) -> None:- """Persist ``self._mcps`` to ``<workdir>/.mcp`` (host-side JSON).-- No-op when ``workdir`` is ``None``. Failures are logged but- not raised — losing the persistence file should not- propagate as an MCP-add/remove error to the caller.- """- if self.host_workdir is None:- return- host_mcp = os.path.join(self.host_workdir, ".mcp")- try:- os.makedirs(self.host_workdir, exist_ok=True)- with open(host_mcp, "w", encoding="utf-8") as f:- json.dump(- [m.model_dump() for m in self._mcps],- f,- indent=2,- ensure_ascii=False,- )- except Exception as e:- logger.warning(- "DockerWorkspace: failed to save %s: %s",- host_mcp,- e,- )-- async def _write_gateway_config(self) -> None:- """Drop the gateway's ``--config`` JSON into the container.-- The file at :data:`GATEWAY_CONFIG` carries the freshly minted- bearer token plus the MCP server specs the gateway should- bring up at start. This is the *only* path the bearer token- crosses — it never lands on host disk.- """- cfg = {- "token": self._gateway_token,- "servers": [m.model_dump(mode="json") for m in self._mcps],- }- 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"),- )-- async def _start_gateway_process(self) -> None:- """Launch the gateway inside the container as a detached process.-- Runs ``nohup python <GATEWAY_SCRIPT> --config <GATEWAY_CONFIG>- --port <gateway_port>`` from the baked-in venv. The script is- invoked by path (not via ``python -m``) so Python does not- auto-import ``agentscope.workspace.__init__`` and the heavy- module graph it pulls in. stdout/stderr are redirected to- :data:`GATEWAY_LOG` so :meth:`_wait_for_gateway` can dump the- tail when startup fails.-- We do not block on this exec call; readiness is detected via- the ``/health`` poll instead.- """- cmd = (- f"nohup {shlex.quote(GATEWAY_VENV + '/bin/python')} -u "- f"{shlex.quote(GATEWAY_SCRIPT)} "- f"--config {shlex.quote(GATEWAY_CONFIG)} "- f"--port {self.gateway_port} "- f"> {shlex.quote(GATEWAY_LOG)} 2>&1 &"- )- # Detach: we don't await stream completion, just kick it off.- 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.-- Uses an exponentially-backed-off poll capped at 1 s. When- the deadline expires, attempts to read the gateway log and- surfaces the tail in the raised error so callers can see the- actual startup failure.-- Args:- timeout: Maximum seconds to wait for readiness.-- Raises:- RuntimeError: If the gateway does not become healthy- before the deadline.- """- assert self._gateway is not None- deadline = asyncio.get_event_loop().time() + timeout- delay = 0.1- while asyncio.get_event_loop().time() < deadline:- if await self._gateway.health():- return- await asyncio.sleep(delay)- delay = min(delay * 1.5, 1.0)- # Last-ditch: dump the gateway log to help debug startup failures.- try:- log = await self._backend.read_file(GATEWAY_LOG)- tail = log[-2000:].decode(errors="replace")- except Exception:- tail = "<no gateway log available>"- raise RuntimeError(- f"gateway did not become healthy within {timeout}s. "- f"Tail of {GATEWAY_LOG}:\n{tail}",- )-- async def _seed_skills(self) -> None:- """Copy ``self.skill_paths`` into ``skills/`` once, on first init.-- Skips seeding when (a) ``workdir`` is unset, (b) ``skill_paths``- is empty, or (c) the host-side ``skills/`` directory already- contains entries — meaning the user (or a prior init) is the- source of truth and we should not append duplicates.-- Failures on individual paths are logged and skipped rather- than raised, so that one bad skill cannot block startup.- """- if not self.skill_paths or self.host_workdir is None:- return- skills_host = os.path.join(self.host_workdir, "skills")- # The bind mount lazily materialises ``<workdir>/skills`` on- # host the first time the container writes into it, so on a- # fresh workdir the host path may not exist yet — create it- # so the next check has something to inspect.- os.makedirs(skills_host, exist_ok=True)- if os.listdir(skills_host):- # already seeded (or user pre-populated) — leave as-is.- return- for path in self.skill_paths:- try:- await self.add_skill(path)- except Exception as e:- logger.warning(- "DockerWorkspace: skip skill %r: %s",- path,- e,- )-- # ── internals: data offload ────────────────────────────────-- async def _offload_data_block(self, block: DataBlock) -> DataBlock:- """Persist a base64 :class:`DataBlock` under ``data/``.-- The decoded payload is stored at- ``data/<sha256-of-original-base64>.<ext>``, where ``<ext>`` is- guessed from the block's media type. Hashing the *base64*- text rather than the decoded bytes lets a second offload of- the same block short-circuit (same key, same file).-- Args:- block: An inline-base64 data block.-- Returns:- A new :class:`DataBlock` whose source is a ``file://``- URL pointing at the persisted file inside the container.- Blocks already backed by a :class:`URLSource` are returned- unchanged (nothing to persist).- """- if not isinstance(block.source, Base64Source):- return block- 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._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,- source=URLSource(- url=AnyUrl(f"file://{path}"),- media_type=block.source.media_type,- ),- )diff --git a/src/agentscope/workspace/_e2b/_e2b_workspace.py b/src/agentscope/workspace/_e2b/_e2b_workspace.pyindex e5f30119a..34450a305 100644--- a/src/agentscope/workspace/_e2b/_e2b_workspace.py+++ b/src/agentscope/workspace/_e2b/_e2b_workspace.py@@ -23,8 +23,10 @@ Docker engine for the E2B SDK (``e2b.AsyncSandbox``):``files.exists(GATEWAY_SCRIPT)`` probe so the cost is paid exactlyonce per sandbox lifetime.* **MCP gateway.** Identical to Docker: a FastAPI process inside the- sandbox, host-side talks to it over HTTPS via E2B's proxy- (``sandbox.get_host(port)`` + ``X-Access-Token`` header).+ sandbox. All host-side calls drive the gateway through+ :class:`GatewayClient`, which runs an in-sandbox ``python3 -c`` shim+ via :meth:`E2BBackend.exec_shell` — no host→sandbox network+ reachability is required.* **Service-layer index.** The host stores only ``workspace_id``;the sandbox carries ``METADATA_WORKSPACE_ID_KEY = workspace_id`` inits E2B metadata. Manager code calls ``AsyncSandbox.list(query=...)``@@ -35,36 +37,11 @@ manager handles cache, TTL eviction and metadata-based reattachment."""import asyncio-import base64-import hashlib-import json-import mimetypes-import os-import posixpath-import shlex-import uuid-from copy import deepcopyfrom typing import Any-from pydantic import AnyUrl-from ..._logging import loggerfrom ...mcp import MCPClient-from ...message import (- Base64Source,- DataBlock,- Msg,- TextBlock,- ToolResultBlock,- URLSource,-)-from ...skill import Skill-from ...tool import ToolBase-from .._base import WorkspaceBase-from .._gateway_client import (- GatewayClient,- GatewayMCPClient,-)+from .._sandboxed_base import SandboxedWorkspaceBasefrom .._utils import (_agentscope_version,_is_released_install,@@ -83,10 +60,6 @@ from ._bootstrap import (GATEWAY_VENV_PY,GLOB_HELPER_SCRIPT,METADATA_WORKSPACE_ID_KEY,- SANDBOX_DATA_DIR,- SANDBOX_MCP_FILE,- SANDBOX_SESSIONS_DIR,- SANDBOX_SKILLS_DIR,SANDBOX_WORKDIR,bootstrap_commands,build_source_tarball,@@ -117,13 +90,20 @@ and processes.# ── the workspace ──────────────────────────────────────────────────-class E2BWorkspace(WorkspaceBase):+class E2BWorkspace(SandboxedWorkspaceBase):"""Workspace backed by an E2B cloud sandbox.``default_mcps`` and ``skill_paths`` are seed-time inputs and arenot retained as instance state past :meth:`initialize`."""+ _glob_helper_path = GLOB_HELPER_SCRIPT+ _gateway_home = GATEWAY_HOME+ _gateway_config = GATEWAY_CONFIG+ _gateway_log = GATEWAY_LOG+ _gateway_script = GATEWAY_SCRIPT+ _gateway_python = GATEWAY_VENV_PY+def __init__(self,*,@@ -142,50 +122,43 @@ class E2BWorkspace(WorkspaceBase):) -> None:"""Construct an :class:`E2BWorkspace`.- The sandbox is *not* started here; call :meth:`initialize`+ The sandbox is *not* started here — call :meth:`initialize`(or use the workspace as an ``async`` context manager).Args:workspace_id (`str | None`, optional):- Stable identifier; doubles as the value stored in the- sandbox's ``agentscope.workspace.id`` metadata for- later reattachment. ``None`` generates a fresh UUID.+ Stable identifier; also stored in sandbox metadata for+ reattachment.template (`str`, defaults to `DEFAULT_TEMPLATE`):- E2B template id. Defaults to ``"base"`` — the stock- Ubuntu image with python3 + curl, which is enough for- the bootstrap to install uv on top.+ E2B template id.api_key (`str`, defaults to `""`):- E2B API key. ``""`` falls back to the ``E2B_API_KEY``- env var.+ E2B API key (``""`` falls back to ``E2B_API_KEY``).domain (`str`, defaults to `""`):- Optional custom E2B domain (self-hosted etc.).+ Optional custom E2B domain.timeout_seconds (`int`, defaults to `DEFAULT_TIMEOUT`):- Sandbox keep-alive timeout passed to ``create`` /- ``connect``.+ Sandbox keep-alive timeout.gateway_port (`int`, defaults to `DEFAULT_GATEWAY_PORT`):TCP port the in-sandbox gateway listens on.env (`dict[str, str] | None`, optional):- Environment variables baked into the sandbox at- create time (``envs`` parameter on the SDK side).+ Environment variables baked into the sandbox.sandbox_metadata (`dict[str, str] | None`, optional):- Extra metadata merged with- ``{METADATA_WORKSPACE_ID_KEY: workspace_id}``. Useful- for attaching ``user_id`` / ``agent_id`` for E2B- dashboard filtering.+ Extra metadata merged with the workspace-id tag.extra_pip (`list[str] | None`, optional):- Extra Python packages to install into the gateway- venv during bootstrap.+ Extra Python packages installed into the gateway venv+ during bootstrap.instructions (`str`, defaults to `_DEFAULT_INSTRUCTIONS`):- System-prompt fragment template returned by- :meth:`get_instructions`.+ System-prompt fragment template (supports ``{workdir}``).default_mcps (`list[MCPClient] | None`, optional):- Initial MCPs registered on first :meth:`initialize`.- Subsequent restarts read ``$workdir/.mcp`` instead.+ MCPs registered on first init when no persisted+ ``.mcp`` exists.skill_paths (`list[str] | None`, optional):- Local skill directories seeded into- ``$workdir/skills`` on first :meth:`initialize`.+ Local skill dirs seeded into ``skills/`` on first init."""- super().__init__(workspace_id=workspace_id)+ super().__init__(+ workspace_id=workspace_id,+ default_mcps=default_mcps,+ skill_paths=skill_paths,+ )# ── serializable config ─────────────────────────────────self.workdir = SANDBOX_WORKDIR@@ -199,184 +172,55 @@ class E2BWorkspace(WorkspaceBase):self.extra_pip: list[str] = list(extra_pip or [])self.instructions = instructions- # ── seed-only ───────────────────────────────────────────- self.default_mcps: list[MCPClient] = list(default_mcps or [])- self.skill_paths: list[str] = list(skill_paths or [])-- # ── runtime state ───────────────────────────────────────+ # ── runtime state (E2B-only) ────────────────────────────self._sandbox: Any = None # e2b.AsyncSandboxself._backend: E2BBackend | None = None- self._gateway: GatewayClient | None = None- self._gateway_token: str = ""- self._mcps: list[MCPClient] = []- self._gateway_clients: dict[str, GatewayMCPClient] = {}- self._mcp_lock = asyncio.Lock()- self._skill_lock = asyncio.Lock()- # ── lifecycle ───────────────────────────────────────────────+ # ── lifecycle hooks ─────────────────────────────────────────@propertydef sandbox_id(self) -> str | None:"""E2B sandbox id, or ``None`` if not started."""return self._sandbox.sandbox_id if self._sandbox else None- async def initialize(self) -> None:- """Reattach or create the sandbox, then start the gateway.-- Steps:-- 1. Look up an existing sandbox via- ``AsyncSandbox.list(query=SandboxQuery(metadata=...))``.- If found, ``AsyncSandbox.connect(sandbox_id=...)`` reattaches- — it auto-resumes paused sandboxes.- 2. If not found, ``AsyncSandbox.create(...)`` provisions a- fresh sandbox tagged with our metadata and runs bootstrap- (uv → gateway venv → agentscope ``--no-deps`` → upload- gateway script).- 3. If bootstrap output is missing on a reattached sandbox- (e.g. a previous bootstrap was interrupted), run bootstrap- again — detected by ``files.exists(GATEWAY_SCRIPT)``.- 4. Restore MCPs from ``$workdir/.mcp`` if present, else seed- from ``default_mcps``.- 5. Mint a fresh gateway bearer token (not persisted).- 6. Kill any leftover gateway process, drop a fresh- ``gateway.config.json`` into the sandbox, launch the- gateway, wait for ``/health``.- 7. Pull the gateway-side MCP view back as- :class:`GatewayMCPClient` instances.-- Idempotent — a no-op when already alive.- """- if self.is_alive:- return+ async def _provision_backend(self) -> None:+ """Reattach or create the sandbox and bind the backend.+ First-time provisioning also runs bootstrap (uv → gateway+ venv → agentscope → gateway script upload). Bootstrap is+ detected by ``files.exists(GATEWAY_SCRIPT)`` and every step+ is idempotent so an interrupted bootstrap re-runs cleanly.+ """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 the gateway script is missing, the sandbox is fresh (or a+ # prior bootstrap was interrupted). Every bootstrap step is+ # idempotent so re-running is safe.if not await self._sandbox.files.exists(GATEWAY_SCRIPT):# 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.+ # first bootstrap command (a ``mkdir -p``) would fail+ # before it ran when the dir does not yet exist. Use+ # ``cwd="/"`` to break the chicken-and-egg.await self._backend.exec_shell(["mkdir", "-p", SANDBOX_WORKDIR],cwd="/",)await self._run_bootstrap()- self._mcps = await self._restore_or_seed_mcps()-- self._gateway_token = uuid.uuid4().hex-- # Stop any stale gateway from a previous resume cycle. Each- # 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._backend.exec_shell(- ["sh", "-c", "pkill -f _mcp_gateway_app.py || true"],- )-- await self._write_gateway_config()- await self._start_gateway_process()-- host = self._sandbox.get_host(self.gateway_port)- self._gateway = GatewayClient(- base_url=f"https://{host}",- token=self._gateway_token,- timeout=30.0,- extra_headers=self._sandbox_proxy_headers(),- )- await self._wait_for_gateway()-- self._gateway_clients = {- c.name: c for c in await self._gateway.list_mcps()- }-- # Persist the MCP set unconditionally so a freshly seeded- # ``self._mcps`` (default_mcps path) is rewritten as the- # canonical ``.mcp`` for the next restart, and a restored set- # is round-tripped harmlessly. ``_seed_skills`` itself is- # idempotent — it short-circuits when the sandbox-side- # ``skills/`` already has entries.- await self._save_mcp_file()- await self._seed_skills()-- self.is_alive = True-- async def reset(self) -> None:- """Return the workspace to an empty state.-- Mirrors :meth:`DockerWorkspace.reset`: deregisters every MCP- from the gateway, clears the local handles, and wipes- ``.mcp``, ``skills/``, ``sessions/``, and ``data/`` inside the- 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 def _teardown_backend(self) -> None:+ """Pause the sandbox (keep filesystem) and drop the handle.- async with self._mcp_lock, self._skill_lock:- for gw_client in list(self._gateway_clients.values()):- try:- await gw_client.close()- except Exception as e:- logger.warning(- "MCP %r close failed during reset: %s",- gw_client.name,- e,- )- self._gateway_clients.clear()- self._mcps = []-- for path in (- SANDBOX_SESSIONS_DIR,- SANDBOX_DATA_DIR,- SANDBOX_SKILLS_DIR,- ):- await self._backend.delete_path(path)-- # Rewrite ``.mcp`` to an empty list so a future restart does- # not fall back to ``default_mcps``.- await self._save_mcp_file()-- async def close(self) -> None:- """Pause the sandbox and release host-side resources.-- ``sandbox.pause()`` (not ``kill()``) keeps the sandbox's- filesystem so the next :meth:`initialize` can reattach to it- via metadata lookup. The host-side gateway client is closed- first so its connection pool is released cleanly.-- Errors during teardown are swallowed so ``close`` is always- safe to call (e.g. from ``__aexit__``).+ ``sandbox.pause()`` — not ``kill()`` — so the next+ :meth:`initialize` can reattach via metadata lookup and+ auto-resume. Errors are swallowed."""- if self._gateway is not None:- try:- await self._gateway.aclose()- except Exception:- pass- self._gateway = None- self._gateway_clients.clear()-if self._sandbox is not None:try:await self._sandbox.pause()except Exception as e:logger.warning("E2BWorkspace: pause failed: %s", e)self._sandbox = None- self._backend = None-- self.is_alive = False# ── instructions ────────────────────────────────────────────@@ -389,276 +233,6 @@ class E2BWorkspace(WorkspaceBase):"""return self.instructions.format(workdir=SANDBOX_WORKDIR)- # ── tool / MCP / skill discovery ────────────────────────────-- async def list_tools(self) -> list[ToolBase]:- """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.-- Each entry's ``name`` matches the upstream MCP server name and- all of its protocol calls are routed over HTTPS to the- in-sandbox gateway.- """- return list(self._gateway_clients.values())-- async def list_skills(self) -> list[Skill]:- """Enumerate skills by scanning ``skills/`` inside the sandbox.-- Reads each ``SKILL.md`` via the SDK's ``files.read`` and parses- the YAML front-matter. Files missing ``name`` or ``description``- are skipped.- """- import frontmatter as fm-- 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 []- listing = result.stdout.decode(errors="replace").strip()- if not listing:- return []-- skills: list[Skill] = []- for md_path in (line.strip() for line in listing.split("\n")):- if not md_path:- continue- try:- raw = await self._backend.read_file(md_path)- doc = fm.loads(raw.decode("utf-8"))- name = doc.get("name")- desc = doc.get("description")- if not name or not desc:- continue- skills.append(- Skill(- name=str(name),- description=str(desc),- dir=posixpath.dirname(md_path),- markdown=doc.content or "",- updated_at=0.0,- ),- )- except Exception as e:- logger.warning("Failed to load skill %s: %s", md_path, e)- return skills-- # ── dynamic MCP management ──────────────────────────────────-- async def add_mcp(self, mcp_client: MCPClient) -> None:- """Register a new MCP server on the in-sandbox gateway.-- Mirrors :meth:`DockerWorkspace.add_mcp` but persists ``.mcp``- unconditionally — the sandbox filesystem is always- persistent for E2B.- """- async with self._mcp_lock:- if mcp_client.name in self._gateway_clients:- raise ValueError(- f"MCP {mcp_client.name!r} already exists in workspace.",- )- spec = mcp_client.model_dump(mode="json")- assert self._gateway is not None- gw_client = self._gateway.make_client(spec)- await gw_client.connect()- self._mcps.append(mcp_client)- self._gateway_clients[gw_client.name] = gw_client- await self._save_mcp_file()-- async def remove_mcp(self, name: str) -> None:- """Unregister an MCP server by name.-- Mirrors :meth:`DockerWorkspace.remove_mcp`.- """- async with self._mcp_lock:- gw_client = self._gateway_clients.pop(name, None)- if gw_client is None:- logger.warning("MCP %r not found in workspace", name)- return- try:- await gw_client.close()- except Exception as e:- logger.warning("MCP %r close failed: %s", name, e)- self._mcps = [m for m in self._mcps if m.name != name]- await self._save_mcp_file()-- # ── dynamic skill management ────────────────────────────────-- async def add_skill(self, skill_path: str) -> None:- """Upload a local skill directory into ``skills/`` inside the sandbox.-- The directory must contain a ``SKILL.md`` with ``name`` and- ``description`` in its YAML front matter. A directory of the- same basename already in the sandbox is rejected rather than- overwritten.- """- skill_md = os.path.join(skill_path, "SKILL.md")- if not os.path.isfile(skill_md):- raise ValueError(- f"Invalid skill at {skill_path!r}: SKILL.md not found",- )-- async with self._skill_lock:- await self._backend.exec_shell(- ["mkdir", "-p", SANDBOX_SKILLS_DIR],- )- dir_name = os.path.basename(os.path.abspath(skill_path))-- check = await self._backend.exec_shell(- ["test", "-e", SANDBOX_SKILLS_DIR + "/" + dir_name],- )- if check.ok():- raise ValueError(- f"Skill directory {dir_name!r} already exists in "- f"{SANDBOX_SKILLS_DIR}",- )-- for root, _dirs, files in os.walk(skill_path):- for fname in files:- local = os.path.join(root, fname)- rel = os.path.relpath(local, skill_path)- remote = f"{SANDBOX_SKILLS_DIR}/{dir_name}/{rel}"- with open(local, "rb") as f:- data = f.read()- await self._backend.write_file(remote, data)-- logger.info(- "E2BWorkspace: added skill %r at %s/%s",- dir_name,- SANDBOX_SKILLS_DIR,- dir_name,- )-- async def remove_skill(self, name: str) -> None:- """Delete a skill directory by its agent-facing name."""- skills = await self.list_skills()- target_dir: str | None = None- for s in skills:- if s.name == name:- target_dir = s.dir- break- if target_dir is None:- available = [s.name for s in skills]- raise KeyError(- f"Skill {name!r} not found. Available: {available}",- )- await self._backend.delete_path(target_dir)-- # ── offload ─────────────────────────────────────────────────-- async def offload_context(- self,- session_id: str,- msgs: list[Msg],- ) -> str:- """Persist a batch of messages as JSONL inside the sandbox.-- Same shape as :meth:`DockerWorkspace.offload_context`: each- :class:`Msg` becomes a line; inline base64 :class:`DataBlock`- payloads are extracted into ``data/`` and replaced with- ``file://`` URL blocks.- """- base = f"{SANDBOX_SESSIONS_DIR}/{session_id}"- path = f"{base}/context.jsonl"-- copied = deepcopy(msgs)- lines: list[str] = []- for msg in copied:- if not isinstance(msg.content, str):- content = []- for block in msg.content:- if isinstance(block, DataBlock) and isinstance(- block.source,- Base64Source,- ):- block = await self._offload_data_block(block)- content.append(block)- msg.content = content- lines.append(msg.model_dump_json())-- await self._backend.exec_shell(["mkdir", "-p", base])- existing = b""- try:- existing = await self._backend.read_file(path)- except FileNotFoundError:- pass- await self._backend.write_file(- path,- existing + ("\n".join(lines) + "\n").encode("utf-8"),- )- return path-- async def offload_tool_result(- self,- session_id: str,- tool_result: ToolResultBlock,- ) -> str:- """Persist a single tool result as a flat text file."""- base = f"{SANDBOX_SESSIONS_DIR}/{session_id}"- path = f"{base}/tool_result-{tool_result.id}.txt"-- parts: list[str] = []- if isinstance(tool_result.output, str):- parts.append(tool_result.output)- else:- for block in tool_result.output:- if isinstance(block, TextBlock):- parts.append(block.text)- elif isinstance(block, DataBlock):- if isinstance(block.source, Base64Source):- d = await self._offload_data_block(block)- url = str(d.source.url)- else:- url = str(block.source.url)- parts.append(- f"<data url='{url}' name='{block.name}' "- f"media_type='{block.source.media_type}'/>",- )-- await self._backend.exec_shell(["mkdir", "-p", base])- await self._backend.write_file(- path,- "".join(parts).encode("utf-8"),- )- return path-# ── internals: sandbox attach / create ─────────────────────async def _attach_or_create_sandbox(self) -> None:@@ -790,20 +364,6 @@ class E2BWorkspace(WorkspaceBase):opts["domain"] = self.domainreturn opts- def _sandbox_proxy_headers(self) -> dict[str, str]:- """Headers required by the E2B proxy to reach the gateway port.-- E2B's edge proxy gates non-default ports behind the- ``X-Access-Token`` header tied to the sandbox. The token is- exposed on the sandbox object as ``traffic_access_token``.- """- if self._sandbox is None:- return {}- token = getattr(self._sandbox, "traffic_access_token", None)- if not token:- return {}- return {"X-Access-Token": token}-# ── internals: bootstrap ────────────────────────────────────async def _run_bootstrap(self) -> None:@@ -854,159 +414,3 @@ class E2BWorkspace(WorkspaceBase):GATEWAY_SCRIPT,_read_gateway_script_bytes(),)-- # ── internals: gateway lifecycle ────────────────────────────-- async def _restore_or_seed_mcps(self) -> list[MCPClient]:- """Decide the MCP set to ship to the gateway on startup.-- * ``$workdir/.mcp`` missing → return ``default_mcps``.- * ``.mcp`` present → :meth:`MCPClient.model_validate` each- entry. Read / parse error → log and fall back to- ``default_mcps``.- """- try:- raw = await self._backend.read_file(SANDBOX_MCP_FILE)- except FileNotFoundError:- return list(self.default_mcps)- try:- data = json.loads(raw.decode("utf-8"))- return [MCPClient.model_validate(m) for m in data]- except Exception as e:- logger.warning(- "E2BWorkspace: failed to parse %s, falling back to "- "default_mcps: %s",- SANDBOX_MCP_FILE,- e,- )- return list(self.default_mcps)-- async def _save_mcp_file(self) -> None:- """Persist ``self._mcps`` to ``$workdir/.mcp`` inside the sandbox.-- Failures are logged but not raised.- """- payload = json.dumps(- [m.model_dump(mode="json") for m in self._mcps],- indent=2,- ensure_ascii=False,- )- try:- await self._backend.exec_shell(- ["mkdir", "-p", SANDBOX_WORKDIR],- )- await self._backend.write_file(- SANDBOX_MCP_FILE,- payload.encode("utf-8"),- )- except Exception as e:- logger.warning(- "E2BWorkspace: failed to save %s: %s",- SANDBOX_MCP_FILE,- e,- )-- async def _write_gateway_config(self) -> None:- """Drop the gateway's ``--config`` JSON into the sandbox."""- cfg = {- "token": self._gateway_token,- "servers": [m.model_dump(mode="json") for m in self._mcps],- }- 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"),- )-- async def _start_gateway_process(self) -> None:- """Launch the gateway inside the sandbox as a detached process."""- cmd = (- f"nohup {shlex.quote(GATEWAY_VENV_PY)} -u "- f"{shlex.quote(GATEWAY_SCRIPT)} "- f"--config {shlex.quote(GATEWAY_CONFIG)} "- f"--port {self.gateway_port} "- f"> {shlex.quote(GATEWAY_LOG)} 2>&1 &"- )- 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."""- assert self._gateway is not None- deadline = asyncio.get_event_loop().time() + timeout- delay = 0.1- while asyncio.get_event_loop().time() < deadline:- if await self._gateway.health():- return- await asyncio.sleep(delay)- delay = min(delay * 1.5, 1.0)- try:- log = await self._backend.read_file(GATEWAY_LOG)- tail = log[-2000:].decode(errors="replace")- except Exception:- tail = "<no gateway log available>"- raise RuntimeError(- f"gateway did not become healthy within {timeout}s. "- f"Tail of {GATEWAY_LOG}:\n{tail}",- )-- async def _seed_skills(self) -> None:- """Copy ``self.skill_paths`` into ``skills/`` once, on first init.-- Skips seeding when ``skill_paths`` is empty or the sandbox-side- ``skills/`` already contains entries — meaning the user (or a- prior init) is the source of truth.- """- if not self.skill_paths:- return- 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- for path in self.skill_paths:- try:- await self.add_skill(path)- except Exception as e:- logger.warning(- "E2BWorkspace: skip skill %r: %s",- path,- e,- )-- # ── internals: data offload ────────────────────────────────-- async def _offload_data_block(self, block: DataBlock) -> DataBlock:- """Persist a base64 :class:`DataBlock` under ``data/``.-- Mirrors :meth:`DockerWorkspace._offload_data_block` exactly,- only the I/O primitive differs. Hashing the *base64* text- rather than decoded bytes keeps the key short-circuit: a- repeat offload of the same block writes the same file.- """- if not isinstance(block.source, Base64Source):- return block- 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._backend.exec_shell(- ["mkdir", "-p", SANDBOX_DATA_DIR],- )- await self._backend.write_file(- path,- base64.b64decode(block.source.data),- )- return DataBlock(- id=block.id,- name=block.name,- source=URLSource(- url=AnyUrl(f"file://{path}"),- media_type=block.source.media_type,- ),- )diff --git a/src/agentscope/workspace/_gateway_client.py b/src/agentscope/workspace/_gateway_client.pyindex 6f05b0649..59de89f34 100644--- a/src/agentscope/workspace/_gateway_client.py+++ b/src/agentscope/workspace/_gateway_client.py@@ -1,30 +1,54 @@# -*- coding: utf-8 -*--"""Host-side client for the in-workspace MCP gateway.+"""Host-side client for the in-sandbox MCP gateway, driven through+``backend.exec_shell``.Three classes live here:* :class:`GatewayClient` — workspace-side facade over the gateway's- ``/health`` and ``/mcps`` endpoints. Used by ``DockerWorkspace`` (and- later ``E2BWorkspace``) for top-level operations.+ ``/health`` and ``/mcps`` endpoints. Used by :class:`DockerWorkspace`+ and :class:`E2BWorkspace` for top-level operations.* :class:`GatewayMCPClient` — an :class:`MCPClient` subclass whose- protocol behaviour is replaced by HTTP calls to the gateway. The- field surface is identical to ``MCPClient`` (instances are built from+ protocol behaviour is replaced by gateway-relayed calls. The field+ surface is identical to ``MCPClient`` (instances are built from``MCPClient.model_dump()`` data the gateway returns), so callersthat ``model_dump()`` it round-trip cleanly. Local stdio/HTTPsession machinery is bypassed: ``model_post_init`` is a no-op,- ``connect`` POSTs to ``/mcps``, ``close`` DELETEs ``/mcps/{name}``,- and ``list_tools`` / ``get_tool`` fetch / wrap upstream tools.+ ``connect`` registers via ``POST /mcps``, ``close`` deregisters via+ ``DELETE /mcps/{name}``, and ``list_raw_tools`` / ``get_tool`` fetch+ / wrap upstream tools.* :class:`GatewayMCPTool` — :class:`ToolBase` subclass whose- ``__call__`` posts to ``/mcps/{name}/tools/{tool}`` and reconstructs- the returned ``ToolChunk``.+ ``__call__`` invokes the upstream tool via+ ``POST /mcps/{name}/tools/{tool}`` and reconstructs the returned+ ``ToolChunk``.++Transport+---------++Unlike a normal HTTP client, **every** request runs **inside the+sandbox**. The host serialises the request body (if any) to a tempfile+via :meth:`BackendBase.write_file`, then spawns a tiny Python script+through :meth:`BackendBase.exec_shell` (see+:mod:`agentscope.workspace._gateway_shim`) which performs the actual+``urllib.request`` call against the gateway's loopback port, writes a+JSON envelope to stdout, and exits 0. The host parses the envelope and+reconstructs status code + response bytes (base64-decoded inline, or+read back from a sandbox tempfile for large payloads).++This removes the host→sandbox network reachability requirement+(previously satisfied by Docker port mapping or the E2B HTTPS proxy);+the gateway listens on a fixed loopback port inside the sandbox and is+no longer reachable from the host at all."""-import contextlib-from typing import Any, AsyncIterator+from __future__ import annotations++import base64+import json+import uuid+from typing import TYPE_CHECKING, Any-import httpximport mcp.typesfrom pydantic import PrivateAttr@@ -35,17 +59,26 @@ from ..permission import (PermissionDecision,)from ..tool import ToolBase, ToolChunk+from ._gateway_shim import (+ BODY_INLINE_LIMIT,+ SANDBOX_TMP_DIR,+ SHIM_SCRIPT,+)++if TYPE_CHECKING:+ from ..tool import BackendBase, ExecResult# ── tool ───────────────────────────────────────────────────────────class GatewayMCPTool(ToolBase):- """An MCP tool whose ``__call__`` is a single HTTP POST to the gateway.+ """An MCP tool whose ``__call__`` is one ``exec_shell``-driven+ request to the gateway.- Mirrors :class:`agentscope.tool.MCPTool` field-by-field so the toolkit- treats it identically (same ``name`` format, same permission policy)- — only the call path changes.+ Mirrors :class:`agentscope.tool.MCPTool` field-by-field so the+ toolkit treats it identically (same ``name`` format, same+ permission policy) — only the call path changes."""is_mcp: bool = True@@ -55,40 +88,32 @@ class GatewayMCPTool(ToolBase):self,mcp_name: str,tool: mcp.types.Tool,- gateway_url: str,- token: str,- http: httpx.AsyncClient | None = None,- timeout: float | None = None,+ gateway: "GatewayClient",) -> None:"""Build a gateway-backed MCP tool.The instance mirrors the field surface of:class:`agentscope.tool.MCPTool` (``name``, ``description``,``input_schema``, ``is_read_only``, …) so the host-side toolkit- cannot tell the difference between a local MCP tool and one that- forwards through the in-container gateway.+ cannot tell the difference between a local MCP tool and one+ that forwards through the in-sandbox gateway.Args:- mcp_name: Name of the upstream MCP server this tool belongs- to. Used both for the visible ``mcp__{mcp}__{tool}``- name and for the gateway URL path.- tool: Raw upstream tool descriptor as returned by the- gateway. Its ``name`` is the upstream-side identifier- (no ``mcp__`` prefix), ``inputSchema`` is forwarded- verbatim, and ``annotations.readOnlyHint`` drives the- permission policy.- gateway_url: Host-visible base URL of the gateway, e.g.- ``http://127.0.0.1:<host_port>``. Trailing slash is- stripped.- token: Bearer token the host injected into the gateway's- config; sent as ``Authorization: Bearer …`` on every- call.- http: Shared :class:`httpx.AsyncClient` to reuse connection- pooling across many tool calls. When ``None`` each- ``__call__`` creates and disposes a one-shot client.- timeout: Per-call HTTP timeout in seconds. Only consulted- when ``http`` is ``None`` (the shared client carries- its own timeout).+ mcp_name (`str`):+ Name of the upstream MCP server this tool belongs to.+ Used both for the visible ``mcp__{mcp}__{tool}`` name+ and for the gateway URL path.+ tool (`mcp.types.Tool`):+ Raw upstream tool descriptor as returned by the gateway.+ Its ``name`` is the upstream-side identifier (no+ ``mcp__`` prefix), ``inputSchema`` is forwarded verbatim,+ and ``annotations.readOnlyHint`` drives the permission+ policy.+ gateway (`GatewayClient`):+ The workspace-side gateway facade that owns the+ backend handle, gateway port, and bearer token. All+ tool invocations are dispatched through its+ :meth:`GatewayClient.exec_request`."""self.mcp_name = mcp_nameself.name = f"mcp__{mcp_name}__{tool.name}"@@ -108,10 +133,7 @@ class GatewayMCPTool(ToolBase):self.is_read_only = tool.annotations.readOnlyHint or Falseself._tool = tool- self._gateway_url = gateway_url.rstrip("/")- self._token = token- self._http = http- self._timeout = timeout+ self._gateway = gatewayasync def check_permissions(self,@@ -134,11 +156,13 @@ class GatewayMCPTool(ToolBase):)async def __call__(self, **kwargs: Any) -> ToolChunk:- """Invoke the upstream tool by POSTing to- ``/mcps/{mcp}/tools/{tool}`` on the gateway.+ """Invoke the upstream tool by relaying+ ``POST /mcps/{mcp}/tools/{tool}`` to the gateway via the+ sandbox shim.Args:- **kwargs: Tool arguments forwarded as the JSON body's+ **kwargs:+ Tool arguments forwarded as the JSON body's``arguments`` field; the gateway re-dispatches them tothe upstream MCP session.@@ -150,29 +174,21 @@ class GatewayMCPTool(ToolBase):about the failure instead of crashing.Raises:- RuntimeError: If the gateway returns 2xx but no ``chunk``- payload (protocol violation on the gateway side).+ `RuntimeError`:+ If the gateway returns 2xx but no ``chunk`` payload+ (protocol violation on the gateway side)."""- url = (- f"{self._gateway_url}/mcps/{self.mcp_name}"- f"/tools/{self._tool.name}"+ status, body = await self._gateway.exec_request(+ "POST",+ f"/mcps/{self.mcp_name}/tools/{self._tool.name}",+ body={"arguments": kwargs},)- headers = _bearer_headers(self._token)- async with _http_session(self._http, self._timeout) as http:- resp = await http.post(- url,- json={"arguments": kwargs},- headers=headers,+ if status >= 400:+ return ToolChunk(+ content=[{"type": "text", "text": _safe_detail(status, body)}],+ state=ToolResultState.ERROR,)- if resp.status_code >= 400:- # Surface gateway-side error as a failed ToolChunk so- # the agent loop can reason about it instead of crashing.- detail = _safe_detail(resp)- return ToolChunk(- content=[{"type": "text", "text": detail}],- state=ToolResultState.ERROR,- )- payload = resp.json()+ payload = json.loads(body)chunk_dict = payload.get("chunk")if chunk_dict is None:raise RuntimeError(@@ -185,24 +201,21 @@ class GatewayMCPTool(ToolBase):class GatewayMCPClient(MCPClient):- """An :class:`MCPClient` whose protocol logic is replaced by HTTP.+ """An :class:`MCPClient` whose protocol logic is replaced by+ gateway-relayed calls.- Constructed from the dict returned by ``GET /mcps`` (or freshly from- user input via :meth:`GatewayClient.make_client`). The local MCP- machinery is short-circuited entirely:+ Constructed from the dict returned by ``GET /mcps`` (or freshly+ from user input via :meth:`GatewayClient.make_client`). The local+ MCP machinery is short-circuited entirely:* ``model_post_init`` does nothing (parent's ``_initialize_client``is never called — no stdio context manager is built).- * ``connect`` POSTs to ``/mcps`` to register-and-start the upstream- server inside the gateway.- * ``close`` DELETEs ``/mcps/{name}``.- * ``list_tools`` / ``get_tool`` fetch and wrap upstream tools.+ * ``connect`` registers the MCP on the gateway via ``POST /mcps``.+ * ``close`` deregisters via ``DELETE /mcps/{name}``.+ * ``list_raw_tools`` / ``get_tool`` fetch and wrap upstream tools."""- _gateway_url: str = PrivateAttr(default="")- _gateway_token: str = PrivateAttr(default="")- _http_timeout: float | None = PrivateAttr(default=None)- _http: httpx.AsyncClient | None = PrivateAttr(default=None)+ _gateway: "GatewayClient | None" = PrivateAttr(default=None)def model_post_init(self, __context: Any) -> None:"""Skip the parent's stdio/HTTP client preparation.@@ -211,7 +224,7 @@ class GatewayMCPClient(MCPClient):local stdio context manager (or wires up an HTTP client) sothe in-process session can be opened. For:class:`GatewayMCPClient` all MCP-side work happens inside the- gateway container; the host-side proxy needs no local session+ gateway sandbox; the host-side proxy needs no local sessionmachinery, so this override is a no-op."""return@@ -220,14 +233,11 @@ class GatewayMCPClient(MCPClient):def attach(self,+ gateway: "GatewayClient",*,- gateway_url: str,- token: str,- http: httpx.AsyncClient | None,- timeout: float | None,connected: bool = False,) -> None:- """Wire this client to a gateway transport.+ """Wire this client to a gateway facade.:class:`GatewayMCPClient` is normally produced by``model_validate(spec)`` over a dict returned by the gateway's@@ -241,98 +251,90 @@ class GatewayMCPClient(MCPClient):``protected-access`` warnings.Args:- gateway_url: Host-visible base URL of the gateway (e.g.- ``http://127.0.0.1:<host_port>``). Trailing slash is- stripped before storage.- token: Bearer token the host generated for this gateway.- Sent as ``Authorization: Bearer …`` on every request.- http: Shared :class:`httpx.AsyncClient` provided by the- owning :class:`GatewayClient` so connection pooling is- shared across all derived clients and tools. When- ``None`` each call creates a one-shot client.- timeout: Default per-request timeout in seconds, used only- when ``http`` is ``None``.- connected: When ``True``, mark this client as already- connected (i.e. the gateway is already maintaining the- upstream session). Used by- :meth:`GatewayClient.list_mcps` for clients that came- back from the gateway as registered. Leave ``False``- when the caller will call :meth:`connect` themselves.+ gateway (`GatewayClient`):+ The workspace-side gateway facade that owns the+ sandbox backend handle, gateway port, and bearer+ token. All subsequent calls are dispatched through its+ :meth:`GatewayClient.exec_request`.+ connected (`bool`, defaults to `False`):+ When ``True``, mark this client as already connected+ (i.e. the gateway is already maintaining the upstream+ session). Used by :meth:`GatewayClient.list_mcps` for+ clients that came back from the gateway as registered.+ Leave ``False`` when the caller will call+ :meth:`connect` themselves."""- self._gateway_url = gateway_url.rstrip("/")- self._gateway_token = token- self._http = http- self._http_timeout = timeout+ self._gateway = gatewayif connected:self._is_connected = Trueasync def connect(self) -> None:"""Register this MCP on the gateway via ``POST /mcps``.- Stateless MCPs are a no-op (the gateway invokes them on- demand). Stateful MCPs are registered and started inside the- gateway container; this method blocks until the gateway has- confirmed the upstream connection.+ All MCPs (stateless and stateful) must be registered so that+ ``/mcps/{name}/tools/{tool}`` can locate the client. For+ stateful MCPs the gateway additionally opens the upstream+ session before responding.Raises:- RuntimeError: If the client is already connected, or if- the gateway returns a 4xx/5xx response.+ `RuntimeError`:+ If the client is already connected, the gateway is+ unreachable, or the gateway returns a 4xx/5xx+ response."""- if not self.is_stateful:- returnif self._is_connected:raise RuntimeError(f"MCP {self.name!r} is already connected. ""Call close() before reconnecting.",)+ assert self._gateway is not Nonebody = self.model_dump(mode="json")- async with _http_session(self._http, self._http_timeout) as http:- resp = await http.post(- f"{self._gateway_url}/mcps",- json=body,- headers=_bearer_headers(self._gateway_token),+ status, resp_body = await self._gateway.exec_request(+ "POST",+ "/mcps",+ body=body,+ )+ if status >= 400:+ raise RuntimeError(+ f"gateway failed to add MCP {self.name!r}: "+ f"{_safe_detail(status, resp_body)}",)- if resp.status_code >= 400:- raise RuntimeError(- f"gateway failed to add MCP {self.name!r}: "- f"{_safe_detail(resp)}",- )self._is_connected = Trueasync def close(self, ignore_errors: bool = True) -> None:"""Deregister this MCP from the gateway via``DELETE /mcps/{name}``.- Stateless MCPs are a no-op. For stateful MCPs the gateway- closes the upstream session before responding.+ All MCPs are deregistered from the gateway registry; the+ gateway additionally closes the upstream session for stateful+ clients before responding.Args:- ignore_errors: When ``True`` (the default), suppress both- "not connected" precondition failures and- gateway-side 4xx/5xx responses; when ``False`` such- conditions raise :class:`RuntimeError`. Mirrors+ ignore_errors (`bool`, defaults to `True`):+ When ``True`` (the default), suppress both "not+ connected" precondition failures and gateway-side+ 4xx/5xx responses; when ``False`` such conditions+ raise :class:`RuntimeError`. Mirrors:meth:`MCPClient.close` so callers can use the sameshutdown idiom regardless of transport."""- if not self.is_stateful:- returnif not self._is_connected:if ignore_errors:returnraise RuntimeError(f"MCP {self.name!r} is not connected. Call connect() first.",)+ assert self._gateway is not Nonetry:- async with _http_session(self._http, self._http_timeout) as http:- resp = await http.delete(- f"{self._gateway_url}/mcps/{self.name}",- headers=_bearer_headers(self._gateway_token),+ status, resp_body = await self._gateway.exec_request(+ "DELETE",+ f"/mcps/{self.name}",+ )+ if status >= 400 and not ignore_errors:+ raise RuntimeError(+ f"gateway failed to remove MCP {self.name!r}: "+ f"{_safe_detail(status, resp_body)}",)- if resp.status_code >= 400 and not ignore_errors:- raise RuntimeError(- f"gateway failed to remove MCP {self.name!r}: "- f"{_safe_detail(resp)}",- )except Exception:if not ignore_errors:raise@@ -357,22 +359,26 @@ class GatewayMCPClient(MCPClient):The upstream-named, post-filter tool descriptors.Raises:- httpx.HTTPStatusError: If the gateway returns a non-2xx- response.+ `RuntimeError`:+ If the gateway returns a non-2xx response."""- async with _http_session(self._http, self._http_timeout) as http:- resp = await http.get(- f"{self._gateway_url}/mcps/{self.name}/tools",- headers=_bearer_headers(self._gateway_token),+ assert self._gateway is not None+ status, body = await self._gateway.exec_request(+ "GET",+ f"/mcps/{self.name}/tools",+ )+ if status >= 400:+ raise RuntimeError(+ f"gateway failed to list tools for MCP {self.name!r}: "+ f"{_safe_detail(status, body)}",)- resp.raise_for_status()- data = resp.json()+ data = json.loads(body)raw_tools = [mcp.types.Tool.model_validate(d) for d in data]self._cached_tools = raw_tools- # Honour the same enable/disable filtering MCPClient does locally —- # gateway returns the unfiltered upstream view.+ # Honour the same enable/disable filtering MCPClient does+ # locally — gateway returns the unfiltered upstream view.if self.enable_tools is not None:raw_tools = [t for t in raw_tools if t.name in self.enable_tools]if self.disable_tools is not None:@@ -393,17 +399,11 @@ class GatewayMCPClient(MCPClient):``disable_tools`` would have hidden are still resolvable —matching :meth:`MCPClient.get_tool`'s behaviour.- The wrapped tool inherits the gateway-wide HTTP timeout- (``_http_timeout``, set via :meth:`attach`). Per-call execution- timeout is the upstream MCP server's responsibility — it is- carried in :attr:`MCPClient.execution_timeout`, serialised into- the spec, and reconstructed on the gateway side; the host has- no need to override it.-Args:- name: Upstream tool name (no ``mcp__`` prefix). The- returned :class:`GatewayMCPTool` exposes the prefixed- form via its own ``name`` attribute.+ name (`str`):+ Upstream tool name (no ``mcp__`` prefix). The returned+ :class:`GatewayMCPTool` exposes the prefixed form via+ its own ``name`` attribute.Returns:`GatewayMCPTool`:@@ -411,8 +411,9 @@ class GatewayMCPClient(MCPClient):to be ``await``-ed or registered with a toolkit.Raises:- ValueError: If no tool with that upstream name exists on- the gateway side.+ `ValueError`:+ If no tool with that upstream name exists on the+ gateway side."""if self._cached_tools is None:await self.list_raw_tools()@@ -427,20 +428,23 @@ class GatewayMCPClient(MCPClient):def _wrap_tool(self, tool: mcp.types.Tool) -> GatewayMCPTool:"""Build a :class:`GatewayMCPTool` bound to this client's- gateway transport. Always uses the client-wide- ``_http_timeout`` — there is no per-call override path.+ gateway facade.Args:- tool: Raw upstream tool descriptor (typically pulled out of+ tool (`mcp.types.Tool`):+ Raw upstream tool descriptor (typically pulled out of``_cached_tools``).++ Returns:+ `GatewayMCPTool`:+ The host-side wrapper that will relay every call+ through the gateway facade."""+ assert self._gateway is not Nonereturn GatewayMCPTool(mcp_name=self.name,tool=tool,- gateway_url=self._gateway_url,- token=self._gateway_token,- http=self._http,- timeout=self._http_timeout,+ gateway=self._gateway,)@@ -448,77 +452,82 @@ class GatewayMCPClient(MCPClient):class GatewayClient:- """Workspace-side facade over the in-container MCP gateway.-- Owns a shared :class:`httpx.AsyncClient` so all derived- :class:`GatewayMCPClient` and :class:`GatewayMCPTool` instances- share connection pooling.+ """Workspace-side facade over the in-sandbox MCP gateway.- The gateway ``base_url`` is the host-visible URL (e.g.- ``http://127.0.0.1:<host_port>`` after Docker port mapping); the- ``token`` is the bearer the host generated and shipped into the- container's gateway config.+ Every method dispatches through :meth:`exec_request`, which in+ turn drives :meth:`BackendBase.exec_shell` on the workspace's+ backend so the network call always happens **inside** the sandbox.+ No host port mapping or HTTPS proxy is required."""def __init__(self,- base_url: str,+ backend: "BackendBase",+ gateway_port: int,token: str,+ *,timeout: float | None = None,- extra_headers: dict[str, str] | None = None,+ inline_limit: int = BODY_INLINE_LIMIT,+ tmp_dir: str = SANDBOX_TMP_DIR,) -> None:"""Build a workspace-side gateway facade.Args:- base_url: Host-visible base URL of the gateway, e.g.- ``http://127.0.0.1:<host_port>`` after Docker port- mapping or ``https://<sandbox-id>.e2b.dev`` for E2B.- Trailing slash is stripped.- token: Bearer token shared with the gateway via its config+ backend (`BackendBase`):+ The workspace's backend handle. Every gateway request+ runs as ``backend.exec_shell([...])`` inside the+ sandbox (Docker container or E2B sandbox).+ gateway_port (`int`):+ TCP port the gateway listens on inside the sandbox.+ The URL dialed by the shim is always+ ``http://127.0.0.1:<gateway_port>``.+ token (`str`):+ Bearer token shared with the gateway via its configfile. Sent as ``Authorization: Bearer …`` on every- request and propagated to every derived- :class:`GatewayMCPClient` / :class:`GatewayMCPTool` via- :meth:`make_client`.- timeout: Default HTTP timeout in seconds, applied to the- shared :class:`httpx.AsyncClient` (see- :meth:`_client`) and propagated to every derived- :class:`GatewayMCPClient` via :meth:`make_client`.- There is no per-call override path; per-tool execution- timeouts live on :attr:`MCPClient.execution_timeout`- and are honoured upstream inside the gateway.- extra_headers: Default headers applied to every request- through the shared httpx client (in addition to the- per-call bearer). :class:`E2BWorkspace` uses this to- inject E2B's ``X-Access-Token`` proxy header.+ request. Pass an empty string to skip auth (useful+ only in tests).+ timeout (`float | None`, defaults to `None`):+ Per-request timeout in seconds, passed straight through+ to :meth:`BackendBase.exec_shell`. The shim itself+ does not apply an HTTP-level timeout — long-running+ MCP tools are limited only by the backend exec+ timeout. ``None`` waits indefinitely.+ inline_limit (`int`, defaults to `BODY_INLINE_LIMIT`):+ Threshold (in bytes) below which response bodies ride+ inline through stdout as base64. Larger bodies are+ spilled to a sandbox tempfile and fetched via+ :meth:`BackendBase.read_file` to avoid loading multi-MB+ payloads through the exec stdout channel.+ tmp_dir (`str`, defaults to `SANDBOX_TMP_DIR`):+ Sandbox-side directory used for both request body+ tempfiles (host → sandbox) and oversized response+ spills (sandbox → host). Must be writable by the+ gateway process; ``/tmp`` works on every supported+ image."""- self.base_url = base_url.rstrip("/")+ self.backend = backend+ self.gateway_port = gateway_portself.token = tokenself.timeout = timeout- self.extra_headers: dict[str, str] = dict(extra_headers or {})- self._http: httpx.AsyncClient | None = None-- def _client(self) -> httpx.AsyncClient:- """Return (lazily creating on first use) the shared- :class:`httpx.AsyncClient` reused by every gateway request."""- if self._http is None:- self._http = httpx.AsyncClient(- timeout=self.timeout,- headers=self.extra_headers or None,- )- return self._http-- def _headers(self) -> dict[str, str]:- """Build the bearer-auth header dict for direct- :class:`GatewayClient` calls (``/health``, ``/mcps``)."""- return _bearer_headers(self.token)+ self.inline_limit = inline_limit+ self.tmp_dir = tmp_dirasync def health(self) -> bool:- """Probe ``/health`` — used by the workspace to wait for readiness."""+ """Probe ``/health`` — used by the workspace to wait for+ readiness.++ Returns:+ `bool`:+ ``True`` iff the gateway answered ``200``. Any other+ outcome (shim transport failure, non-200 status)+ returns ``False``; callers are expected to retry until+ this flips.+ """try:- resp = await self._client().get(f"{self.base_url}/health")+ status, _ = await self.exec_request("GET", "/health")except Exception:return False- return resp.status_code == 200+ return status == 200async def list_mcps(self) -> list[GatewayMCPClient]:"""Fetch every MCP currently registered on the gateway.@@ -536,15 +545,16 @@ class GatewayClient:this list straight to its consumer.Raises:- httpx.HTTPStatusError: If the gateway returns a non-2xx- response.+ `RuntimeError`:+ If the gateway returns a non-2xx response."""- resp = await self._client().get(- f"{self.base_url}/mcps",- headers=self._headers(),- )- resp.raise_for_status()- return [self.make_client(spec, connected=True) for spec in resp.json()]+ status, body = await self.exec_request("GET", "/mcps")+ if status >= 400:+ raise RuntimeError(+ f"gateway failed to list MCPs: {_safe_detail(status, body)}",+ )+ specs = json.loads(body)+ return [self.make_client(spec, connected=True) for spec in specs]def make_client(self,@@ -555,22 +565,24 @@ class GatewayClient:"""Build a :class:`GatewayMCPClient` wired to this gateway.Reconstructs the public field surface from ``spec`` via- :meth:`MCPClient.model_validate`, then hands the- transport-related private state to the new client through+ :meth:`MCPClient.model_validate`, then hands the transport+ handle to the new client through:meth:`GatewayMCPClient.attach`. Doing the wiring through``attach`` keeps the writes inside the target class and avoids``protected-access`` warnings on every assignment.Args:- spec: A dict produced by ``MCPClient.model_dump(mode="json")``+ spec (`dict[str, Any]`):+ A dict produced by ``MCPClient.model_dump(mode="json")``— typically the body returned by the gateway's``GET /mcps`` endpoint, or built from user input by``DockerWorkspace.add_mcp``.- connected: When ``True``, mark the new client as already- connected so :meth:`GatewayMCPClient.connect` need not- run again. Set by :meth:`list_mcps` for clients that- came back from the gateway already registered. Leave- ``False`` for fresh clients the caller will explicitly+ connected (`bool`, defaults to `False`):+ When ``True``, mark the new client as already connected+ so :meth:`GatewayMCPClient.connect` need not run again.+ Set by :meth:`list_mcps` for clients that came back+ from the gateway already registered. Leave ``False``+ for fresh clients the caller will explicitly``await client.connect()`` on (the ``add_mcp`` path).Returns:@@ -580,55 +592,164 @@ class GatewayClient:``await client.connect()`` unless ``connected=True``."""client = GatewayMCPClient.model_validate(spec)- client.attach(- gateway_url=self.base_url,- token=self.token,- http=self._client(),- timeout=self.timeout,- connected=connected,- )+ client.attach(self, connected=connected)return clientasync def aclose(self) -> None:- """Close the shared HTTP client."""- if self._http is not None:- await self._http.aclose()- self._http = None+ """No-op kept for API parity with the previous httpx-based+ client.+ The new transport holds no host-side resources (every call is+ a one-shot ``exec_shell``), so there is nothing to close. The+ method stays so callers can keep their existing shutdown+ idiom.+ """+ return-# ── module-private utilities ───────────────────────────────────────+ # ── transport ─────────────────────────────────────────────────+ async def exec_request(+ self,+ method: str,+ path: str,+ *,+ body: Any = None,+ ) -> tuple[int, bytes]:+ """Relay one HTTP request through the sandbox.++ Mechanics:++ 1. If ``body`` is given, JSON-encode it and write it to+ ``${tmp_dir}/<uuid>.json`` inside the sandbox via+ :meth:`BackendBase.write_file`.+ 2. Run ``python3 -c <SHIM_SCRIPT> <method> <url> <token>+ <body_file_or_""> <inline_limit> <tmp_dir>`` via+ :meth:`BackendBase.exec_shell`. The shim performs the+ ``urllib.request`` call against the gateway's loopback port+ and prints a JSON envelope to stdout.+ 3. Parse the envelope. Inline bodies are base64-decoded;+ oversized bodies are pulled back from+ ``envelope["body_file"]`` via :meth:`BackendBase.read_file`+ and then deleted.++ Both the request and response temp files are best-effort+ cleaned up so a crash does not leak files into the sandbox's+ ``${tmp_dir}``.-def _bearer_headers(token: str) -> dict[str, str]:- if token:- return {"Authorization": f"Bearer {token}"}- return {}+ Args:+ method (`str`):+ HTTP verb (``GET`` / ``POST`` / ``DELETE``).+ path (`str`):+ Path-only URL relative to the gateway root, e.g.+ ``/mcps`` or ``/mcps/<name>/tools/<tool>``. Always+ starts with ``/``.+ body (`Any`, optional):+ JSON-serializable request body. ``None`` (the default)+ means no body — typical for ``GET`` / ``DELETE``.+ Returns:+ `tuple[int, bytes]`:+ The HTTP status code returned by the gateway, paired+ with the raw response body bytes (always decoded;+ callers ``json.loads`` it themselves when needed).-async def _http_session(- shared: httpx.AsyncClient | None,- timeout: float | None,-) -> AsyncIterator[httpx.AsyncClient]:- """Yield a shared httpx client when injected, else a one-shot client.+ Raises:+ `RuntimeError`:+ If the shim crashed (non-zero exit code, non-JSON+ stdout) or reported a transport failure+ (``status == -1`` — gateway unreachable, urllib+ error, …).+ """+ body_file = ""+ wrote_body_file: str | None = None+ if body is not None:+ body_file = f"{self.tmp_dir}/{uuid.uuid4().hex}.json"+ wrote_body_file = body_file+ await self.backend.write_file(+ body_file,+ json.dumps(body, ensure_ascii=False).encode("utf-8"),+ )- The shared variant lets the workspace pool connections across many- tool calls without each call paying the TLS/handshake cost.- """- if shared is not None:- yield shared- else:- async with httpx.AsyncClient(timeout=timeout) as http:- yield http+ try:+ result: "ExecResult" = await self.backend.exec_shell(+ [+ "python3",+ "-c",+ SHIM_SCRIPT,+ method,+ f"http://127.0.0.1:{self.gateway_port}{path}",+ self.token or "",+ body_file,+ str(self.inline_limit),+ self.tmp_dir,+ ],+ timeout=self.timeout,+ )+ finally:+ if wrote_body_file is not None:+ try:+ await self.backend.delete_path(wrote_body_file)+ except Exception:+ pass++ if result.exit_code != 0:+ raise RuntimeError(+ f"gateway shim exited with {result.exit_code}: "+ f"{result.stderr.decode(errors='replace')[:500]}",+ )++ try:+ env = json.loads(result.stdout)+ except Exception as e:+ raise RuntimeError(+ "gateway shim produced non-JSON stdout: "+ f"{result.stdout[:200]!r}",+ ) from e+ status = int(env["status"])+ if status == -1:+ raise RuntimeError(+ "gateway request failed: "+ f"{env.get('error', 'unknown error')}",+ )-def _safe_detail(resp: httpx.Response) -> str:+ if "body_file" in env:+ spilled = env["body_file"]+ body_bytes = await self.backend.read_file(spilled)+ try:+ await self.backend.delete_path(spilled)+ except Exception:+ pass+ else:+ body_bytes = base64.b64decode(env.get("body", ""))++ return status, body_bytes+++# ── module-private utilities ───────────────────────────────────────+++def _safe_detail(status: int, body: bytes) -> str:"""Best-effort extraction of an HTTPException-style detail from a- response."""+ gateway response body.++ Args:+ status (`int`):+ HTTP status code returned by the gateway.+ body (`bytes`):+ Raw response body bytes — typically a JSON object from+ FastAPI's ``HTTPException``, but tolerate anything.++ Returns:+ `str`:+ A human-readable diagnostic that always starts with+ ``HTTP <status>:`` so it slots into the same exception /+ ``ToolChunk`` messages as the previous httpx-based code.+ """try:- body = resp.json()+ data = json.loads(body)except Exception:- return f"HTTP {resp.status_code}: {resp.text[:200]}"- if isinstance(body, dict) and "detail" in body:- return f"HTTP {resp.status_code}: {body['detail']}"- return f"HTTP {resp.status_code}: {str(body)[:200]}"+ return f"HTTP {status}: {body[:200].decode(errors='replace')}"+ if isinstance(data, dict) and "detail" in data:+ return f"HTTP {status}: {data['detail']}"+ return f"HTTP {status}: {str(data)[:200]}"diff --git a/src/agentscope/workspace/_gateway_shim.py b/src/agentscope/workspace/_gateway_shim.pynew file mode 100644index 000000000..31d49d479--- /dev/null+++ b/src/agentscope/workspace/_gateway_shim.py@@ -0,0 +1,139 @@+# -*- coding: utf-8 -*-+"""Tiny Python script that runs **inside the sandbox** to relay a single+HTTP request to the gateway, plus the host-side helpers that drive it+through :class:`agentscope.tool.BackendBase.exec_shell`.++Architectural shift+-------------------++Previously the workspace reached its in-sandbox MCP gateway through a+host-visible URL — DockerWorkspace mapped the gateway TCP port to a+random host port and dialed ``http://127.0.0.1:<host_port>``;+E2BWorkspace used ``sandbox.get_host(port)`` + ``X-Access-Token`` to+ride E2B's HTTPS proxy. Both flows require host → sandbox network+reachability.++The new flow is: **every request runs inside the sandbox**. The host+spawns a short Python script there via ``backend.exec_shell`` which+makes the call against the gateway's loopback port using nothing but+the standard library (``urllib.request``), serialises the response into+a self-describing JSON envelope, and prints it to stdout. The host+reads stdout back as an ``ExecResult`` and reconstructs the status+code and body bytes (response headers are not transmitted — callers+consume JSON bodies directly).++Why ``python3 -c`` (and not ``curl``)+-------------------------------------++* ``python3`` is guaranteed by every backend we support — the gateway+ itself is a Python process, and our Dockerfile sets up a venv. We+ cannot make the same guarantee for ``curl`` on third-party E2B+ templates.+* No new dependency: ``urllib.request`` is stdlib.+* argv stays free of shell-special characters; the whole script is one+ argv element delivered to ``python3 -c`` via the backend's argv-based+ ``exec_shell`` (Docker passes ``cmd=`` directly; E2B's ``shlex.quote``+ POSIX-quotes the element). No interpolation, no escape bugs.++Wire format+-----------++Stdout always carries a single JSON object — even on transport failure+the shim exits 0 and reports the error in the envelope, so callers+need only one parse path::++ {+ "status": <int>, # HTTP status, or -1 on error+ "body": "<base64-of-bytes>", # only when status >= 0 and small+ "body_file": "<sandbox-path>", # only when body is large+ "error": "<short message>" # only when status == -1+ }++For typical MCP tool calls (≤ 1 MiB) the body rides inline as base64.+For exceptional payloads (> ``BODY_INLINE_LIMIT`` bytes) the shim+spills to ``/tmp/<uuid>.bin`` and returns the path; the caller reads+that file via ``backend.read_file`` and deletes it. This avoids loading+multi-megabyte responses through stdout, which both ``aiodocker`` and+``e2b`` accumulate in host RAM.+"""++from __future__ import annotations++# Request bodies larger than this go through a temp file rather than+# riding through stdout. 4 MiB comfortably covers any real MCP tool+# result without paying the disk-roundtrip cost on the common path.+BODY_INLINE_LIMIT = 4 * 1024 * 1024++# Where the shim spills oversized payloads. ``/tmp`` is writable on+# every backend image (Docker python:3.11-slim, E2B default templates).+SANDBOX_TMP_DIR = "/tmp"+++# The shim itself. Embedded as a string so it ships with this module —+# the host always knows the exact source the sandbox is executing.+#+# Conventions kept tight on purpose:+# * stdlib-only;+# * no shebang (we always invoke as ``python3 -c``);+# * exit code is always 0 — failures land in the envelope;+# * stderr is intentionally untouched so a Python traceback (e.g.+# syntax error after a botched edit) is visible to the caller.+#+# ``sys.argv`` layout when run via ``python3 -c``::+#+# argv[0] = "-c" (Python convention)+# argv[1] = method (e.g. "GET" / "POST" / "DELETE")+# argv[2] = url (e.g. "http://127.0.0.1:5600/health")+# argv[3] = token (bearer; empty string for none)+# argv[4] = body_file or "" (path readable on the sandbox)+# argv[5] = inline_limit (bytes; int as str)+# argv[6] = tmp_dir (where to spill oversized responses)+SHIM_SCRIPT = r"""+import sys, json, base64, uuid, os+import urllib.request, urllib.error++method = sys.argv[1]+url = sys.argv[2]+token = sys.argv[3]+body_file = sys.argv[4]+inline_limit = int(sys.argv[5])+tmp_dir = sys.argv[6]++body = None+if body_file:+ with open(body_file, "rb") as f:+ body = f.read()++req = urllib.request.Request(url, data=body, method=method)+if token:+ req.add_header("Authorization", "Bearer " + token)+if body is not None:+ req.add_header("Content-Type", "application/json")++try:+ with urllib.request.urlopen(req) as resp:+ status = int(resp.status)+ resp_body = resp.read()+except urllib.error.HTTPError as e:+ status = int(e.code)+ try:+ resp_body = e.read()+ except Exception:+ resp_body = b""+except Exception as e:+ json.dump(+ {"status": -1, "error": type(e).__name__ + ": " + str(e)},+ sys.stdout,+ )+ sys.exit(0)++env = {"status": status}+if len(resp_body) > inline_limit:+ p = os.path.join(tmp_dir, uuid.uuid4().hex + ".bin")+ with open(p, "wb") as f:+ f.write(resp_body)+ env["body_file"] = p+else:+ env["body"] = base64.b64encode(resp_body).decode("ascii")+json.dump(env, sys.stdout)+"""diff --git a/src/agentscope/workspace/_local_workspace.py b/src/agentscope/workspace/_local_workspace.pyindex aadb5c626..7db64c20b 100644--- a/src/agentscope/workspace/_local_workspace.py+++ b/src/agentscope/workspace/_local_workspace.py@@ -2,40 +2,18 @@"""The local workspace class."""import asyncio-import base64import hashlibimport json-import mimetypesimport osimport reimport shutil-from copy import deepcopy-from pathlib import Pathfrom typing import TypedDictimport frontmatter-from pydantic import AnyUrlfrom .._logging import loggerfrom ..mcp import MCPClient-from ..message import (- Base64Source,- DataBlock,- Msg,- TextBlock,- ToolResultBlock,- URLSource,-)from ..skill import Skill-from ..tool import (- Bash,- Edit,- Glob,- Grep,- Read,- ToolBase,- Write,-)from ..tool._builtin._backend import LocalBackendfrom ._base import WorkspaceBase@@ -116,7 +94,6 @@ You are responsible for keeping it clean, structured, and easy to navigate overclass LocalWorkspace(WorkspaceBase):- # pylint: disable=line-too-long"""Local-directory workspace.Layout::@@ -126,7 +103,7 @@ class LocalWorkspace(WorkspaceBase):├── data/ # offloaded multimodal files├── skills/ # skill subdirectories└── sessions/ # per-session context and tool-result files- """ # noqa: E501+ """def __init__(self,@@ -451,156 +428,6 @@ 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.-- 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.-- Args:- data_block (`DataBlock`):- The data block with base64 source.-- Returns:- `DataBlock`:- A new data block with the same metadata but with the source- replaced by the local file path where the data is stored.- """- if isinstance(data_block.source, URLSource):- return data_block-- # Use the full SHA-256 hex digest (256-bit) as the filename stem.- # A full hash collision is computationally infeasible, so an existing- # file with the same name is guaranteed to have identical content —- # 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"- 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 self._backend.file_exists(path):- await self._backend.write_file(- path,- base64.b64decode(data_block.source.data),- )-- return DataBlock(- id=data_block.id,- name=data_block.name,- source=URLSource(- url=AnyUrl(Path(path).as_uri()),- media_type=data_block.source.media_type,- ),- )-- async def offload_context(- self,- session_id: str,- msgs: list[Msg],- ) -> str:- """Offload the compressed messages into the local directory for- further processing.-- Args:- session_id (`str`):- The session id.- msgs (`list[Msg]`):- The messages to offload.-- Returns:- `str`:- The file path to the offloaded message.- """- base = os.path.join(self.workdir, "sessions", session_id)- path = os.path.join(base, "context.jsonl")-- copied_msgs = deepcopy(msgs)- lines: list[str] = []- for msg in copied_msgs:- if not isinstance(msg.content, str):- content = []- for block in msg.content:- if isinstance(block, DataBlock) and isinstance(- block.source,- Base64Source,- ):- content.append(await self._offload_data_block(block))- else:- content.append(block)- msg.content = content- 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,- existing + payload.encode("utf-8"),- )- return path-- async def offload_tool_result(- self,- session_id: str,- tool_result: ToolResultBlock,- ) -> str:- """Offload the tool results into the local directory for agentic- retrieval.-- Args:- session_id (`str`):- The session id.- tool_result (`ToolResultBlock`):- The tool result.-- Returns:- `str`:- The file path to the offloaded tool results.- """- 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 await self._backend.file_exists(path):- path = os.path.join(- base,- f"tool_result-{tool_result.id}({index}).txt",- )- index += 1-- parts: list[str] = []- if isinstance(tool_result.output, str):- parts.append(tool_result.output)- else:- for block in tool_result.output:- if isinstance(block, TextBlock):- 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- parts.append(- f"<data url='{url}' name='{block.name}' "- f"media_type='{block.source.media_type}'/>",- )-- await self._backend.write_file(- path,- "".join(parts).encode("utf-8"),- )- return path-async def close(self) -> None:"""Close every stateful MCP attached to this workspace.@@ -657,21 +484,6 @@ class LocalWorkspace(WorkspaceBase):path = os.path.join(self.workdir, sub)await self._backend.delete_path(path)- async def list_tools(self) -> list[ToolBase]:- """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, 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]:"""List all skills available in the workspace.@@ -876,31 +688,12 @@ class LocalWorkspace(WorkspaceBase):)return None- async def list_mcps(self) -> list[MCPClient]:- """Return all MCP clients attached to this workspace."""- return self._mcps-- async def _save_mcp_file(self) -> None:- """Persist the current MCP client list to ``.mcp`` in workdir."""- mcp_file = os.path.join(self.workdir, ".mcp")- try:- # callers have lock.- 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))-async def add_mcp(self, mcp_client: MCPClient) -> None:"""Add an MCP client, connect it if stateful, and persist.Args:- mcp_client: The MCP client to add.+ mcp_client (`MCPClient`):+ The MCP client to add."""async with self._mcp_lock:if mcp_client.is_stateful and not mcp_client.is_connected:@@ -912,7 +705,8 @@ class LocalWorkspace(WorkspaceBase):"""Remove an MCP client by name, disconnecting it if stateful.Args:- name: The ``name`` field of the client to remove.+ name (`str`):+ The ``name`` field of the client to remove."""async with self._mcp_lock:for i, mcp in enumerate(self._mcps):diff --git a/src/agentscope/workspace/_sandboxed_base.py b/src/agentscope/workspace/_sandboxed_base.pynew file mode 100644index 000000000..09c0e43a3--- /dev/null+++ b/src/agentscope/workspace/_sandboxed_base.py@@ -0,0 +1,350 @@+# -*- coding: utf-8 -*-+"""SandboxedWorkspaceBase — shared implementation for gateway-backed+sandbox workspaces (Docker, E2B, and future K8s / Daytona etc.).++Extends :class:`WorkspaceBase` with a full template-method lifecycle+around an in-sandbox MCP gateway. Concrete subclasses only need to+provide:++- :meth:`_provision_backend` — create / attach the sandbox and bind+ ``self._backend`` (a :class:`BackendBase` implementation).+- :meth:`_teardown_backend` — destroy / pause the sandbox and release+ backend-specific resources.+- five gateway-path class attributes (see below) pinned to whatever+ paths the subclass's bootstrap places files at.++Every gateway concern — writing config, launching the process,+polling ``/health``, dispatching :meth:`add_mcp` / :meth:`remove_mcp`+through :class:`GatewayClient`, restoring / persisting the ``.mcp``+file, wiping state on :meth:`reset` — lives here so it is written+exactly once.+"""++import asyncio+import json+import shlex+import uuid+from abc import abstractmethod+from typing import TYPE_CHECKING++from .._logging import logger+from ..mcp import MCPClient+from ._base import WorkspaceBase+from ._gateway_client import GatewayClient++if TYPE_CHECKING:+ from ._gateway_client import GatewayMCPClient+++class SandboxedWorkspaceBase(WorkspaceBase):+ """Base class for workspaces backed by an in-sandbox MCP gateway.++ Subclasses set the following class attributes (usually to module+ constants defined by the backend's bootstrap):++ - :attr:`gateway_port` — TCP port the gateway listens on.+ - :attr:`_gateway_home` — directory that holds gateway files.+ - :attr:`_gateway_config` — path to ``gateway.config.json``.+ - :attr:`_gateway_log` — path to the gateway log.+ - :attr:`_gateway_script` — path to the gateway entry script.+ - :attr:`_gateway_python` — path to the gateway venv's python.+ """++ gateway_port: int+ """TCP port the in-sandbox gateway listens on."""++ _gateway_home: str+ """Sandbox-side directory holding the gateway config and log."""++ _gateway_config: str+ """Sandbox-side path of ``gateway.config.json``."""++ _gateway_log: str+ """Sandbox-side path of the gateway stdout/stderr log."""++ _gateway_script: str+ """Sandbox-side path of the gateway entry script."""++ _gateway_python: str+ """Sandbox-side path of the gateway venv python interpreter."""++ _gateway: GatewayClient | None+ """Workspace-side gateway facade. ``None`` before init / after close."""++ _gateway_clients: "dict[str, GatewayMCPClient]"+ """Gateway-wrapped MCP handles keyed by ``MCPClient.name``."""++ _gateway_token: str+ """Bearer token minted per :meth:`initialize`; never persisted."""++ def __init__(+ self,+ *,+ workspace_id: str | None = None,+ default_mcps: list[MCPClient] | None = None,+ skill_paths: list[str] | None = None,+ ) -> None:+ """Initialise sandbox-workspace state.++ Args:+ workspace_id (`str | None`, optional):+ Existing identifier; ``None`` mints a fresh UUID.+ default_mcps (`list[MCPClient] | None`, optional):+ MCPs registered when no persisted ``.mcp`` exists.+ skill_paths (`list[str] | None`, optional):+ Local skill dirs seeded on first start.+ """+ super().__init__(+ workspace_id=workspace_id,+ default_mcps=default_mcps,+ skill_paths=skill_paths,+ )+ self._gateway = None+ self._gateway_clients = {}+ self._gateway_token = ""++ # ── subclass hooks ────────────────────────────────────────────++ @abstractmethod+ async def _provision_backend(self) -> None:+ """Provision the sandbox and bind ``self._backend``.++ Called once per :meth:`initialize`. Implementations must+ leave ``self._backend`` as a live :class:`BackendBase`+ instance ready to accept ``exec_shell`` / ``write_file`` /+ ``read_file`` calls. Any first-time bootstrap (installing the+ gateway venv, uploading scripts) should happen here.+ """++ @abstractmethod+ async def _teardown_backend(self) -> None:+ """Destroy or pause the sandbox and release resources.++ Called once per :meth:`close`, *after* the gateway facade has+ been closed. Implementations should be idempotent and swallow+ exceptions so ``close`` never raises.+ """++ # ── lifecycle template methods ────────────────────────────────++ async def initialize(self) -> None:+ """Provision the sandbox, restore MCPs, start the gateway.++ Idempotent — a no-op when already alive.+ """+ if self.is_alive:+ return++ await self._provision_backend()+ assert (+ self._backend is not None+ ), "_provision_backend must set self._backend before returning"++ self._mcps = await self._restore_or_seed_mcps()+ self._gateway_token = uuid.uuid4().hex++ # Kill any leftover gateway from a previous resume. Each init+ # mints a fresh bearer token, so a stale gateway would accept+ # old-token requests but reject new ones. Idempotent (``|| true``).+ await self._backend.exec_shell(+ ["sh", "-c", "pkill -f _mcp_gateway_app.py || true"],+ )++ await self._write_gateway_config()+ await self._start_gateway_process()++ self._gateway = GatewayClient(+ backend=self._backend,+ gateway_port=self.gateway_port,+ token=self._gateway_token,+ timeout=30.0,+ )+ await self._wait_for_gateway()++ # The gateway loaded the same set we just wrote — name-for-name.+ self._gateway_clients = {+ c.name: c for c in await self._gateway.list_mcps()+ }++ # ``_save_mcp_file`` is a persistence-gated no-op when the+ # workspace is ephemeral; ``_seed_skills`` short-circuits when+ # ``skills/`` already has entries.+ await self._save_mcp_file()+ await self._seed_skills()++ self.is_alive = True++ async def close(self) -> None:+ """Close the gateway facade, then tear down the sandbox.++ Idempotent — errors are swallowed so ``close`` is always+ safe to call.+ """+ if self._gateway is not None:+ try:+ await self._gateway.aclose()+ except Exception:+ pass+ self._gateway = None+ self._gateway_clients.clear()++ try:+ await self._teardown_backend()+ finally:+ self._backend = None+ self.is_alive = False++ async def reset(self) -> None:+ """Wipe workspace state; keep the sandbox and gateway alive.++ Deregisters every MCP from the gateway, clears local handles,+ and wipes ``.mcp``, ``skills/``, ``sessions/``, and ``data/``.+ ``default_mcps`` / ``skill_paths`` are not re-seeded.+ """+ backend = self.get_backend()+ async with self._mcp_lock, self._skill_lock:+ for gw_client in list(self._gateway_clients.values()):+ try:+ await gw_client.close()+ except Exception as e:+ logger.warning(+ "MCP %r close failed during reset: %s",+ gw_client.name,+ e,+ )+ self._gateway_clients.clear()+ self._mcps = []++ for path in (+ self._sessions_dir,+ self._data_dir,+ self._skills_dir,+ ):+ await backend.delete_path(path)++ # Empty out .mcp so a restart won't fall back to default_mcps.+ await self._save_mcp_file()++ # ── MCP management (gateway-routed) ───────────────────────────++ async def list_mcps(self) -> list[MCPClient]:+ """Gateway-wrapped MCP handles, one per registered MCP."""+ return list(self._gateway_clients.values())++ async def add_mcp(self, mcp_client: MCPClient) -> None:+ """Register a new MCP server through the in-sandbox gateway.++ Args:+ mcp_client (`MCPClient`):+ The MCP to register.++ Raises:+ `ValueError`:+ If an MCP with the same name already exists.+ `RuntimeError`:+ If the gateway is not attached or rejects the+ registration.+ """+ if self._gateway is None:+ raise RuntimeError("Workspace has no MCP gateway attached.")+ async with self._mcp_lock:+ if mcp_client.name in self._gateway_clients:+ raise ValueError(+ f"MCP {mcp_client.name!r} already exists in workspace.",+ )+ spec = mcp_client.model_dump(mode="json")+ gw_client = self._gateway.make_client(spec)+ await gw_client.connect()+ self._mcps.append(mcp_client)+ self._gateway_clients[gw_client.name] = gw_client+ await self._save_mcp_file()++ async def remove_mcp(self, name: str) -> None:+ """Deregister an MCP server by name.++ Args:+ name (`str`):+ MCP name to remove. Unknown names log a warning and+ return silently.++ Raises:+ `RuntimeError`:+ If the gateway is not attached.+ """+ if self._gateway is None:+ raise RuntimeError("Workspace has no MCP gateway attached.")+ async with self._mcp_lock:+ gw_client = self._gateway_clients.pop(name, None)+ if gw_client is None:+ logger.warning("MCP %r not found in workspace", name)+ return+ try:+ await gw_client.close()+ except Exception as e:+ logger.warning("MCP %r close failed: %s", name, e)+ self._mcps = [m for m in self._mcps if m.name != name]+ await self._save_mcp_file()++ # ── gateway lifecycle helpers ─────────────────────────────────++ async def _write_gateway_config(self) -> None:+ """Drop ``gateway.config.json`` into the sandbox.++ Carries the freshly minted bearer token plus the MCP server+ specs the gateway should bring up at startup.+ """+ backend = self.get_backend()+ cfg = {+ "token": self._gateway_token,+ "servers": [m.model_dump(mode="json") for m in self._mcps],+ }+ await backend.exec_shell(["mkdir", "-p", self._gateway_home])+ await backend.write_file(+ self._gateway_config,+ json.dumps(cfg, indent=2, ensure_ascii=False).encode("utf-8"),+ )++ async def _start_gateway_process(self) -> None:+ """Launch the gateway inside the sandbox as a detached process."""+ backend = self.get_backend()+ cmd = (+ f"nohup {shlex.quote(self._gateway_python)} -u "+ f"{shlex.quote(self._gateway_script)} "+ f"--config {shlex.quote(self._gateway_config)} "+ f"--port {self.gateway_port} "+ f"> {shlex.quote(self._gateway_log)} 2>&1 &"+ )+ await 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.++ On timeout, dump the tail of the gateway log so startup+ failures are visible in the raised error.++ Args:+ timeout (`float`, defaults to 30.0):+ Maximum seconds to wait for readiness.++ Raises:+ RuntimeError: If the gateway does not become healthy+ before the deadline.+ """+ assert self._gateway is not None+ backend = self.get_backend()+ deadline = asyncio.get_event_loop().time() + timeout+ delay = 0.1+ while asyncio.get_event_loop().time() < deadline:+ if await self._gateway.health():+ return+ await asyncio.sleep(delay)+ delay = min(delay * 1.5, 1.0)+ try:+ log = await backend.read_file(self._gateway_log)+ tail = log[-2000:].decode(errors="replace")+ except Exception:+ tail = "<no gateway log available>"+ raise RuntimeError(+ f"gateway did not become healthy within {timeout}s. "+ f"Tail of {self._gateway_log}:\n{tail}",+ )