Skip to content

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

refactor(workspace): re-organize the code implementation logic of the workspace (#1971)

DavdGao51f15fc2eda5
diff --git a/README.md b/README.md
index 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.md
index 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.py
index 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.py
index 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 tarfile
from abc import abstractmethod
+from copy import deepcopy
+from pathlib import Path
from typing import Self
+from pydantic import AnyUrl
+
+from .._logging import logger
from .._utils._common import _generate_id
from ..mcp import MCPClient
-from ..message import Msg, ToolResultBlock
+from ..message import (
+ Base64Source,
+ DataBlock,
+ Msg,
+ TextBlock,
+ ToolResultBlock,
+ URLSource,
+)
from ..skill import Skill
from ..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 active
backend.
"""
- 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._backend
async 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 ────────────────────────────
- @abstractmethod
async 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),
+ ]
- @abstractmethod
async 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
- @abstractmethod
async 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
- @abstractmethod
async 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)
- @abstractmethod
async 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.py
index 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 hashlib
import io
-import json
-import mimetypes
import os
-import posixpath
-import shlex
import shutil
import sys
import tarfile
-import uuid
-from copy import deepcopy
from typing import Any
-from pydantic import AnyUrl
-
from ..._logging import logger
from ...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 SandboxedWorkspaceBase
from ._docker_backend import DockerBackend
from ._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 are
not 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_WORKDIR
self.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.Docker
self._container: Any = None
self._backend: DockerBackend | None = None
- self._port_mapping: dict[int, int] = {}
self._image_tag: str = ""
- self._gateway: GatewayClient | None = None
- 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 aiodocker
self._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 None
and sys.platform == "linux"
@@ -373,7 +214,6 @@ class DockerWorkspace(WorkspaceBase):
except Exception:
pass
self._container = None
- self._backend = None
if self._client is not None:
try:
@@ -382,377 +222,13 @@ class DockerWorkspace(WorkspaceBase):
pass
self._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.py
index 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 exactly
once 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`` in
its 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 deepcopy
from typing import Any
-from pydantic import AnyUrl
-
from ..._logging import logger
from ...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 SandboxedWorkspaceBase
from .._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 are
not 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.AsyncSandbox
self._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 ─────────────────────────────────────────
@property
def 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.domain
return 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.py
index 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 callers
that ``model_dump()`` it round-trip cleanly. Local stdio/HTTP
session 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 httpx
import mcp.types
from 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_name
self.name = f"mcp__{mcp_name}__{tool.name}"
@@ -108,10 +133,7 @@ class GatewayMCPTool(ToolBase):
self.is_read_only = tool.annotations.readOnlyHint or False
self._tool = tool
- self._gateway_url = gateway_url.rstrip("/")
- self._token = token
- self._http = http
- self._timeout = timeout
+ self._gateway = gateway
async 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 to
the 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) so
the 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 session
machinery, 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 = gateway
if connected:
self._is_connected = True
async 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:
- return
if self._is_connected:
raise RuntimeError(
f"MCP {self.name!r} is already connected. "
"Call close() before reconnecting.",
)
+ assert self._gateway is not None
body = 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 = True
async 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 same
shutdown idiom regardless of transport.
"""
- if not self.is_stateful:
- return
if not self._is_connected:
if ignore_errors:
return
raise RuntimeError(
f"MCP {self.name!r} is not connected. Call connect() first.",
)
+ assert self._gateway is not None
try:
- 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 None
return 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 config
file. 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_port
self.token = token
self.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_dir
async 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 == 200
async 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 client
async 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.py
new file mode 100644
index 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.py
index 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 base64
import hashlib
import json
-import mimetypes
import os
import re
import shutil
-from copy import deepcopy
-from pathlib import Path
from typing import TypedDict
import frontmatter
-from pydantic import AnyUrl
from .._logging import logger
from ..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 LocalBackend
from ._base import WorkspaceBase
@@ -116,7 +94,6 @@ You are responsible for keeping it clean, structured, and easy to navigate over
class 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.py
new file mode 100644
index 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}",
+ )