aip-agents-binary 0.0.0__py3-none-any.whl

aip_agents/middleware/backends/sandbox.py

@@ -0,0 +1,1431 @@
+"""E2B sandbox filesystem backend implementation.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import concurrent.futures
+import fnmatch
+import json
+import threading
+import unicodedata
+from collections.abc import Awaitable, Callable
+from pathlib import PurePosixPath
+from typing import Any, cast
+
+from gllm_tools.code_interpreter.code_template.models import SandboxProvider
+
+from aip_agents.middleware.backends.protocol import (
+    BackendProtocol,
+    EditResult,
+    ExecuteResult,
+    FileInfo,
+    GrepMatch,
+    WriteResult,
+)
+from aip_agents.middleware.backends.sandbox_files import STALE_FILE_UPLOAD_MARKER, GenericSandboxFiles
+from aip_agents.middleware.backends.utils import (
+    format_content_with_line_numbers,
+    perform_string_replacement,
+    redact_secrets,
+)
+from aip_agents.sandbox.defaults import DEFAULT_SANDBOX_TEMPLATE
+from aip_agents.sandbox.sandbox_runtime import SandboxRuntime
+from aip_agents.utils.logger import get_logger
+
+__all__ = ["SandboxBackend"]
+
+logger = get_logger(__name__)
+
+_METADATA_DIR_NAME = ".aip-backend-metadata"
+_BINARY_INDEX_FILENAME = "binary-paths.json"
+
+# Fallback base_dir when the caller does not pass one and ``$HOME`` cannot be
+# resolved. Matches E2B's default unprivileged user home (``/home/user``) rather
+# than a root-level ``/workspace`` the sandbox ``user`` cannot create.
+_DEFAULT_BASE_DIR = "/home/user/workspace"
+
+
+class SandboxBackend(BackendProtocol):
+    """BackendProtocol implementation backed by E2B sandbox files API."""
+
+    def __init__(
+        self,
+        template: str | None = DEFAULT_SANDBOX_TEMPLATE,
+        base_dir: str | None = None,
+        allow_execute: bool = True,
+        env: dict[str, str] | None = None,
+        timeout_seconds: int = 300,
+        auto_build_template: bool = True,
+        provider: SandboxProvider | None = None,
+        runtime: SandboxRuntime | None = None,
+    ) -> None:
+        """Initialize sandbox backend.
+
+        Args:
+            template: E2B template ID. Defaults to ``DEFAULT_SANDBOX_TEMPLATE``
+                (project-managed template alias). If that template fails to create,
+                the runtime falls back to E2B's default code-interpreter template.
+                Pass ``None`` to always use E2B's default template directly.
+                The template must include a running Jupyter kernel on port 49999;
+                otherwise ``execute`` calls will fail with a "port is not open"
+                502 error.
+            base_dir: Base workspace directory inside sandbox. When ``None``
+                (the default), it is resolved at runtime to ``$HOME/workspace``
+                inside the sandbox (falling back to ``/home/user/workspace``),
+                so the directory is always writable by the sandbox user rather
+                than requiring root for a root-level ``/workspace``.
+            allow_execute: Whether execute is enabled.
+            env: Optional environment variables to pass to sandbox command
+                execution. Values are forwarded only for execute calls.
+            timeout_seconds: Default runtime execution timeout.
+            auto_build_template: If True and the requested template returns 404,
+                automatically build it before falling back to the default sandbox.
+                Building can take several minutes. Defaults to True.
+            provider: Sandbox backend (``SandboxProvider``). When None, defaults to the
+                ``SANDBOX_PROVIDER`` env, then ``SandboxProvider.E2B``.
+            runtime: Optional injected runtime for testing or sharing.
+        """
+        self.template = template
+        self._base_dir_explicit = base_dir is not None
+        self.base_dir = (base_dir or _DEFAULT_BASE_DIR).rstrip("/") or "/"
+        self.allow_execute = allow_execute
+        self._env = dict(env) if env else None
+        self.timeout_seconds = timeout_seconds
+        self.auto_build_template = auto_build_template
+        self.provider = provider
+        self._runtime = runtime
+        self._runtime_lock = asyncio.Lock()
+        self._runtime_loop: asyncio.AbstractEventLoop | None = None
+        self._runtime_reset_listener_registered = False
+        self._base_dir_initialized = False
+        self._files_client: Any | None = None
+        self._binary_paths: set[str] = set()
+        self._capture_runtime_loop()
+        self._attach_runtime_reset_listener(self._runtime)
+
+    def _capture_runtime_loop(self) -> None:
+        """Capture the current event loop if one is running, for use in _run_sync."""
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            return
+        if loop.is_closed():
+            return
+        self._runtime_loop = loop
+
+    @property
+    def runtime(self) -> SandboxRuntime:
+        """Get initialized runtime.
+
+        Raises:
+            RuntimeError: If runtime was not initialized yet.
+        """
+        if self._runtime is None:
+            raise RuntimeError("Runtime not initialized.")
+        return self._runtime
+
+    async def _ensure_runtime_instance(self) -> Any:
+        """Create the sandbox runtime lazily without initializing filesystem state."""
+        self._capture_runtime_loop()
+
+        if self._runtime is None:
+            async with self._runtime_lock:
+                if self._runtime is None:
+                    self._runtime = SandboxRuntime(
+                        template=self.template,
+                        auto_build_template=self.auto_build_template,
+                        provider=self.provider,
+                    )
+                    self._attach_runtime_reset_listener(self._runtime)
+        return self.runtime
+
+    async def _ensure_runtime(self) -> SandboxRuntime:
+        """Create and initialize the sandbox runtime lazily.
+
+        Creates a new ``SandboxRuntime`` the first time it is called and
+        caches the instance for subsequent calls.  After the runtime is
+        available the method also ensures that ``base_dir`` has been created
+        inside the sandbox (idempotent, guarded by ``_base_dir_initialized``).
+        All state mutations are serialised through ``_runtime_lock`` to avoid
+        races in concurrent async callers.
+
+        Returns:
+            The initialised :class:`SandboxRuntime` instance.
+        """
+        await self._ensure_runtime_instance()
+
+        if not self._base_dir_initialized:
+            async with self._runtime_lock:
+                if not self._base_dir_initialized:
+                    files = await self._get_files_client()
+                    if not self._base_dir_explicit and getattr(self.runtime, "files", None) is None:
+                        await self._resolve_home_base_dir()
+                    await files.make_dir(self.base_dir)
+                    self._base_dir_initialized = True
+        return self.runtime
+
+    async def _resolve_home_base_dir(self) -> None:
+        """Point the default base_dir at the sandbox user's own home directory.
+
+        The default ``base_dir`` assumes an E2B-style ``/home/user`` home, but
+        other providers may run the sandbox as a different user (e.g. root).
+        When the caller did not pass an explicit ``base_dir``, query ``$HOME``
+        inside the sandbox and use ``<home>/workspace`` so the base directory is
+        always writable by the sandbox user. If the query yields no usable
+        absolute path, the ``/home/user/workspace`` default is kept.
+        """
+        result = await self.runtime.execute_command('printf %s "$HOME"', timeout=min(self.timeout_seconds, 10))
+        # Only trust stdout when the probe clearly succeeded; a non-zero exit means
+        # $HOME is unknown, so keep the /home/user/workspace default.
+        home = (result.stdout or "").strip() if getattr(result, "exit_code", 1) == 0 else ""
+        if home.startswith("/"):
+            home = home.rstrip("/")
+            if home:  # guard against HOME="/" collapsing to a root-level "/workspace"
+                self.base_dir = f"{home}/workspace"
+
+    async def ensure_runtime(self) -> SandboxRuntime:
+        """Return the initialized runtime for callers that need to share this sandbox."""
+        return await self._ensure_runtime()
+
+    async def _get_files_client(self) -> Any:
+        """Return a generic filesystem client over the runtime's sandbox.
+
+        Triggers sandbox creation with a lightweight ``true`` command, then wraps the
+        runtime's ``CodeInterpreterSandbox`` in :class:`GenericSandboxFiles` (which uses
+        ``download_file`` / ``execute_code`` / ``execute_command`` — provider-neutral,
+        binary-safe). The adapter is cached on the instance so repeat calls never
+        re-enter sandbox initialization (important because synchronous callers like
+        ``ExecuteTool._read_file_bytes`` run via ``_run_async_in_thread`` on a fresh
+        event loop).
+
+        Returns:
+            A :class:`GenericSandboxFiles` exposing ``read`` / ``write`` / ``list`` /
+            ``make_dir``.
+
+        Raises:
+            RuntimeError: If the sandbox cannot be initialized.
+        """
+        if self._files_client is not None:
+            return self._files_client
+
+        runtime = self.runtime
+        runtime_files = getattr(runtime, "files", None)
+        if runtime_files is not None:
+            self._files_client = runtime_files
+            return self._files_client
+
+        await runtime.execute_command("true", timeout=self.timeout_seconds)
+        sandbox = runtime.sandbox
+        if sandbox is None:
+            raise RuntimeError("Sandbox is not available")
+        self._files_client = GenericSandboxFiles(sandbox)
+        return self._files_client
+
+    def _invalidate_cached_files_client(self) -> None:
+        """Drop backend-owned file client state after loop-bound runtime recovery."""
+        self._files_client = None
+        self._base_dir_initialized = False
+
+    def _attach_runtime_reset_listener(self, runtime: SandboxRuntime | None) -> None:
+        """Register a cache invalidation callback on runtime-backed sandboxes once."""
+        if self._runtime_reset_listener_registered or runtime is None:
+            return
+        if not isinstance(getattr(runtime, "_reset_listeners", None), list):
+            return
+        runtime._register_reset_listener(self._invalidate_cached_files_client)
+        self._runtime_reset_listener_registered = True
+
+    def _resolve_path(self, path: str) -> str:
+        """Resolve a given path to an absolute path within base_dir.
+
+        This method ensures all paths are resolved within the sandbox's base_dir
+        to prevent directory traversal attacks. It handles various input formats
+        including relative paths, absolute paths, and paths containing parent
+        directory references ("..").
+
+        The security check uses Path.relative_to() which raises ValueError if the
+        resolved path is not a subpath of base_dir, effectively blocking traversal
+        attempts like "../../../etc/passwd".
+
+        Args:
+            path: The input path to resolve. Can be:
+                - Relative path (e.g., "subdir/file.txt")
+                - Absolute path within base_dir (e.g., "/workspace/subdir/file.txt")
+                - Root reference ("/")
+                - Paths with parent references (e.g., "../file.txt") - will be blocked
+
+        Returns:
+            A normalized absolute path string within base_dir.
+
+        Raises:
+            ValueError: If the path escapes base_dir through directory traversal
+                (e.g., using ".." to navigate above the workspace root).
+
+        Examples:
+            >>> backend = SandboxBackend(base_dir="/workspace")
+
+            # Relative paths are resolved against base_dir
+            >>> backend._resolve_path("subdir/file.txt")
+            '/workspace/subdir/file.txt'
+
+            # Absolute paths within base_dir are preserved
+            >>> backend._resolve_path("/workspace/subdir/file.txt")
+            '/workspace/subdir/file.txt'
+
+            # Root reference returns base_dir
+            >>> backend._resolve_path("/")
+            '/workspace'
+
+            # Parent directory references within bounds are normalized
+            >>> backend._resolve_path("subdir/../file.txt")
+            '/workspace/file.txt'
+
+            # Path traversal attempts raise ValueError
+            >>> backend._resolve_path("../../../etc/passwd")
+            ValueError: Path escapes base_dir: '../../../etc/passwd'
+
+            >>> backend._resolve_path("/etc/passwd")
+            ValueError: Path escapes base_dir: '/etc/passwd'
+
+        Note:
+            This method is critical for security. Never skip the relative_to()
+            check as it prevents access to files outside the sandbox workspace.
+        """
+        normalized_path = path.replace("\\", "/")
+        if normalized_path == "/":
+            candidate_path = self.base_dir
+        elif normalized_path.startswith(f"{self.base_dir}/") or normalized_path == self.base_dir:
+            candidate_path = normalized_path
+        elif normalized_path.startswith("/"):
+            candidate_path = f"{self.base_dir}/{normalized_path.lstrip('/')}"
+        else:
+            candidate_path = f"{self.base_dir}/{normalized_path}"
+
+        resolved_path = self._normalize_sandbox_path(candidate_path)
+        base_dir_prefix = "/" if self.base_dir == "/" else f"{self.base_dir}/"
+        if resolved_path != self.base_dir and not resolved_path.startswith(base_dir_prefix):
+            raise ValueError(f"Path escapes base_dir: {path!r}")
+
+        return resolved_path
+
+    def _to_relative_path(self, path: str) -> str:
+        """Convert an absolute sandbox path to a base_dir-relative path.
+
+        This method strips the base_dir prefix from absolute paths to produce
+        relative paths that are portable and consistent across different backends.
+        It's used to normalize paths returned by filesystem operations.
+
+        Args:
+            path: An absolute path within the sandbox (e.g., "/workspace/file.txt").
+
+        Returns:
+            A relative path string with base_dir removed. Returns "/" if the path
+            equals base_dir, or the original path if it doesn't start with base_dir.
+
+        Examples:
+            >>> backend = SandboxBackend(base_dir="/workspace")
+
+            # Normal case: path within workspace
+            >>> backend._to_relative_path("/workspace/subdir/file.txt")
+            'subdir/file.txt'
+
+            # Path is exactly base_dir
+            >>> backend._to_relative_path("/workspace")
+            '/'
+
+            # Path doesn't start with base_dir (edge case)
+            >>> backend._to_relative_path("/other/path")
+            'other/path'
+        """
+        if path.startswith(f"{self.base_dir}/"):
+            return path[len(self.base_dir) + 1 :]
+        if path == self.base_dir:
+            return "/"
+        return path.lstrip("/")
+
+    def _metadata_dir_path(self) -> str:
+        """Return the private backend metadata directory path."""
+        if self.base_dir == "/":
+            return f"/{_METADATA_DIR_NAME}"
+        return f"{self.base_dir}/{_METADATA_DIR_NAME}"
+
+    def _binary_index_path(self) -> str:
+        """Return the persisted binary provenance index path."""
+        return f"{self._metadata_dir_path()}/{_BINARY_INDEX_FILENAME}"
+
+    def _is_metadata_path(self, full_path: str) -> bool:
+        """Return whether a sandbox path points inside private backend metadata."""
+        metadata_dir = self._metadata_dir_path()
+        return full_path == metadata_dir or full_path.startswith(f"{metadata_dir}/")
+
+    def _binary_marker(self, full_path: str) -> str:
+        """Return a stable marker for backend-local file provenance."""
+        return self._to_relative_path(full_path)
+
+    async def _load_binary_paths(self) -> None:
+        """Load byte-write provenance markers persisted by earlier backend instances."""
+        files_client = await self._get_files_client()
+        try:
+            content = await files_client.read(self._binary_index_path())
+        except Exception:
+            return
+        try:
+            data = json.loads(content)
+        except (TypeError, json.JSONDecodeError):
+            return
+        if isinstance(data, list):
+            self._binary_paths.update(item for item in data if isinstance(item, str))
+
+    async def _save_binary_paths(self) -> None:
+        """Persist byte-write provenance markers for future backend instances."""
+        files_client = await self._get_files_client()
+        try:
+            await files_client.make_dir(self._metadata_dir_path())
+        except Exception:
+            pass
+        await files_client.write(self._binary_index_path(), json.dumps(sorted(self._binary_paths), indent=2))
+
+    async def _is_binary_path(self, full_path: str) -> bool:
+        """Return whether a path was written through the byte API."""
+        marker = self._binary_marker(full_path)
+        if marker not in self._binary_paths:
+            await self._load_binary_paths()
+        return marker in self._binary_paths
+
+    def _normalize_sandbox_path(self, path: str) -> str:
+        """Normalize a workspace-relative path to prevent directory traversal."""
+        parts: list[str] = []
+        for part in path.split("/"):
+            if not part or part == ".":
+                continue
+            if part == "..":
+                if parts:
+                    parts.pop()
+                continue
+            parts.append(part)
+        return "/" + "/".join(parts)
+
+    @staticmethod
+    def _has_binary_controls(content: str) -> bool:
+        """Return whether text contains non-printable, non-whitespace controls."""
+        return any(not ch.isprintable() and not ch.isspace() and unicodedata.category(ch) != "Cf" for ch in content)
+
+    def _is_binary_payload(self, full_path: str, content: Any) -> bool:
+        """Return whether a sandbox file should be treated as binary."""
+        if self._binary_marker(full_path) in self._binary_paths or isinstance(content, bytes | bytearray):
+            return True
+        if isinstance(content, str):
+            return self._has_binary_controls(content)
+        return False
+
+    def _reject_binary_text(self, full_path: str, file_path: str, content: Any) -> None:
+        """Reject text operations on known or detected binary payloads."""
+        if self._is_binary_payload(full_path, content):
+            raise ValueError(f"File '{file_path}' is binary and cannot be read as text")
+
+    async def _read_text_file(self, file_path: str) -> tuple[Any, str, str]:
+        """Resolve and read a text file with stale-transport-aware error mapping."""
+        await self._ensure_runtime()
+        files_client = await self._get_files_client()
+        full_path = self._resolve_path(file_path)
+        if await self._is_binary_path(full_path):
+            raise ValueError(f"File '{file_path}' is binary and cannot be read as text")
+        content = await files_client.read(full_path)
+        return files_client, full_path, content
+
+    @staticmethod
+    def _slice_line_window(content: str, line_offset: int, limit: int) -> str:
+        """Return a numbered line window from *content*."""
+        lines = content.split("\n")
+        selected_lines = lines[max(0, line_offset) : max(0, line_offset) + max(0, limit)]
+        selected_content = "\n".join(selected_lines)
+        if not selected_content:
+            return ""
+        return format_content_with_line_numbers(selected_content, offset=max(0, line_offset))
+
+    @staticmethod
+    def _slice_char_window(content: str, char_offset: int, max_chars: int) -> str:
+        """Return a raw character window from *content*."""
+        start = max(0, char_offset)
+        if len(content) == 0:
+            return ""
+        if start >= len(content):
+            return "[End of file reached]"
+        end = min(len(content), start + max_chars)
+        return content[start:end]
+
+    async def _write_text_with_stale_retry(
+        self,
+        files_client: Any,
+        full_path: str,
+        content: str,
+        *,
+        operation: str,
+    ) -> bool:
+        """Write text once, retrying a stale transport exactly once."""
+        retry_after_stale = False
+        try:
+            await files_client.write(full_path, content)
+            return True
+        except Exception as error:
+            if not SandboxRuntime._is_stale_runtime_error(error):
+                raise
+
+            logger.info(
+                "%s: detected stale filesystem transport (%r), resetting and retrying once",
+                operation,
+                error,
+            )
+            self._reset_backend_runtime()
+            files_client = await self._get_files_client()
+            retry_after_stale = True
+
+        if retry_after_stale:
+            try:
+                await files_client.write(full_path, content)
+            except Exception as retry_error:
+                if SandboxRuntime._is_stale_runtime_error(retry_error):
+                    return False
+                raise retry_error
+        return True
+
+    @staticmethod
+    def _coerce_text_content(file_data: Any) -> str:
+        """Coerce batch file payloads to text."""
+        return file_data if isinstance(file_data, str) else str(file_data)
+
+    async def _write_files_batch(self, files_client: Any, files: dict[str, Any]) -> None:
+        """Write a batch of workspace files using a shared files client."""
+        for file_path, file_data in files.items():
+            await self._ensure_parent_dir(file_path)
+            await files_client.write(self._resolve_path(file_path), self._coerce_text_content(file_data))
+
+    def _is_directory_entry(self, entry: Any) -> bool:
+        """Determine if a filesystem entry from the E2B files client is a directory."""
+        entry_type = getattr(entry, "type", None)
+        type_value = getattr(entry_type, "value", entry_type)
+        return str(type_value).lower() == "dir"
+
+    def _resolve_child_path(self, directory: str, child_name: str) -> str | None:
+        """Resolve a listed child entry to a safe absolute sandbox path.
+
+        This helper is used by :meth:`aget_files` when recursively collecting
+        checkpoint state from the sandbox workspace. It joins a directory returned
+        by the E2B files client with a child entry name, normalizes ``.`` / ``..``
+        segments, and rejects any child that would escape ``self.base_dir``.
+
+        Args:
+            directory: Absolute sandbox directory currently being traversed
+                (for example ``"/workspace"`` or ``"/workspace/subdir"``).
+            child_name: Raw child entry name returned by the files client.
+
+        Returns:
+            The normalized absolute child path when it stays within
+            ``self.base_dir``. Returns ``None`` when the child would escape the
+            sandbox workspace and should be skipped.
+
+        Examples:
+            Normal child paths remain inside the workspace:
+            >>> backend = SandboxBackend(base_dir="/workspace")
+            >>> backend._resolve_child_path("/workspace", "notes.txt")
+            '/workspace/notes.txt'
+            Nested relative paths are normalized safely:
+            >>> backend._resolve_child_path("/workspace/config", "./app.conf")
+            '/workspace/config/app.conf'
+            Parent-directory escapes are rejected:
+            >>> backend._resolve_child_path("/workspace", "../escape.txt") is None
+            True
+            Traversal that stays inside the workspace is allowed:
+            >>> backend._resolve_child_path("/workspace/nested", "../safe.txt")
+            '/workspace/safe.txt'
+        """
+        child_path = self._normalize_sandbox_path(f"{directory}/{child_name}")
+        base_dir_with_sep = "/" if self.base_dir == "/" else f"{self.base_dir}/"
+        if child_path == self.base_dir or child_path.startswith(base_dir_with_sep):
+            return child_path
+        return None
+
+    async def _collect_sandbox_files(
+        self,
+        files_client: Any,
+        directory: str,
+        files: dict[str, Any],
+        visited: set[str],
+    ) -> None:
+        """Recursively collect text files under *directory* into *files*."""
+        if directory in visited:
+            return
+        visited.add(directory)
+
+        entries = await files_client.list(directory)
+        for entry in entries:
+            child_path = self._resolve_child_path(directory, str(getattr(entry, "name", "")))
+            if child_path is None or self._is_metadata_path(child_path):
+                continue
+            if self._is_directory_entry(entry):
+                await self._collect_sandbox_files(files_client, child_path, files, visited)
+                continue
+            files[self._to_relative_path(child_path)] = await files_client.read(child_path)
+
+    @staticmethod
+    def _close_coroutine_if_needed(coro: Any) -> None:
+        if asyncio.iscoroutine(coro):
+            coro.close()
+
+    def _raise_missing_owner_loop(self, coro: Any) -> None:
+        self._close_coroutine_if_needed(coro)
+        raise RuntimeError(
+            "SandboxBackend sync bridge has no owning loop in this worker thread. "
+            "Call an async backend method (e.g. await backend._ensure_runtime()) "
+            "on the owning loop before invoking sync methods from executors."
+        )
+
+    def _raise_sync_on_owner_loop(self, coro: Any) -> None:
+        self._close_coroutine_if_needed(coro)
+        raise RuntimeError(
+            "SandboxBackend sync methods cannot run on the owning event-loop thread. "
+            "Use the async backend methods instead."
+        )
+
+    def _run_sync(self, coro: Any) -> Any:
+        """Run an async coroutine synchronously, bridging across a running event loop when present.
+
+        Convenience wrapper used by the synchronous public API (e.g.
+        :meth:`read`, :meth:`write`, :meth:`execute`) so that callers that
+        cannot use ``await`` can still drive async backend operations.
+
+        When called from a non-async thread while **no** event loop is running
+        (the common case in tests and standalone scripts), ``asyncio.run`` is
+        used directly, which creates a fresh loop and tears it down.
+
+        When called from a worker thread spawned by a running event loop (the
+        production case — LangGraph tool execution inside a uvloop server),
+        ``asyncio.run_coroutine_threadsafe`` schedules the coroutine onto the
+        **original** running loop so that all asyncio primitives (``Lock``,
+        ``Event``, etc.) stay bound to that loop.  The calling thread blocks on
+        ``Future.result()`` until the coroutine completes.
+
+        Args:
+            coro: An awaitable / coroutine to execute.
+
+        Returns:
+            The return value produced by *coro*.
+        """
+        loop = self._runtime_loop
+        running_loop: asyncio.AbstractEventLoop | None = None
+
+        try:
+            running_loop = asyncio.get_running_loop()
+        except RuntimeError:
+            pass
+
+        if loop is None or loop.is_closed():
+            if running_loop is None:
+                if threading.current_thread() is not threading.main_thread():
+                    self._raise_missing_owner_loop(coro)
+                return asyncio.run(coro)
+            self._runtime_loop = running_loop
+            loop = running_loop
+
+        if running_loop is loop:
+            self._raise_sync_on_owner_loop(coro)
+
+        fut = asyncio.run_coroutine_threadsafe(coro, loop)
+        try:
+            return fut.result()
+        except concurrent.futures.CancelledError as exc:
+            raise asyncio.CancelledError() from exc
+
+    async def _ensure_parent_dir(self, file_path: str) -> None:
+        """Ensure the parent directory of *file_path* exists in the sandbox.
+
+        E2B's files API returns HTTP 404 when the target path's parent directory
+        does not exist.  This method creates it via ``make_dir`` before every
+        write, swallowing errors so that an already-existing directory does not
+        surface as a failure.
+
+        Args:
+            file_path: Workspace-relative or absolute destination path whose
+                parent directory should be pre-created.
+        """
+        resolved: str = self._resolve_path(file_path)
+        parent = str(PurePosixPath(resolved).parent)
+        if parent in ("", "/", self.base_dir):
+            return
+        files_client = await self._get_files_client()
+        try:
+            await files_client.make_dir(parent)
+        except Exception:
+            pass
+
+    def ls_info(self, path: str) -> list[FileInfo]:
+        """List files and subdirectories at *path* (synchronous).
+
+        Synchronous wrapper around :meth:`als_info`.
+
+        Args:
+            path: Workspace-relative or absolute path of the directory to list.
+
+        Returns:
+            A list of :class:`~aip_agents.middleware.backends.protocol.FileInfo`
+            objects describing each entry in the directory.
+        """
+        return self._run_sync(self.als_info(path))
+
+    async def als_info(self, path: str) -> list[FileInfo]:
+        """List files and subdirectories at *path* (async).
+
+        Resolves *path* to an absolute sandbox path, calls the E2B files
+        client ``list`` API, and converts the raw entries into
+        :class:`~aip_agents.middleware.backends.protocol.FileInfo` objects
+        with workspace-relative paths.
+
+        Args:
+            path: Workspace-relative or absolute path of the directory to list.
+
+        Returns:
+            A list of :class:`~aip_agents.middleware.backends.protocol.FileInfo`
+            objects describing each entry in the directory.
+        """
+
+        async def _attempt() -> list[FileInfo]:
+            await self._ensure_runtime()
+            files_client = await self._get_files_client()
+            full_path = self._resolve_path(path)
+            try:
+                entries = await files_client.list(full_path)
+            except FileNotFoundError:
+                if full_path != self.base_dir:
+                    raise
+                self._base_dir_initialized = False
+                await self._ensure_runtime()
+                files_client = await self._get_files_client()
+                entries = await files_client.list(full_path)
+
+            results: list[FileInfo] = []
+            for entry in entries:
+                entry_path = f"{full_path}/{entry.name}".replace("//", "/")
+                if self._is_metadata_path(entry_path):
+                    continue
+                rel_path = self._to_relative_path(entry_path)
+                is_dir = self._is_directory_entry(entry)
+                if is_dir:
+                    results.append(FileInfo(path=rel_path, type="directory", size=None))
+                else:
+                    results.append(
+                        FileInfo(path=rel_path, type="file", size=getattr(entry, "size", None)),
+                    )
+            return results
+
+        return await self._run_with_stale_files_recovery(_attempt, operation="als_info")
+
+    def read(
+        self,
+        file_path: str,
+        line_offset: int = 0,
+        limit: int = 2000,
+        *,
+        offset: int | None = None,
+        thread_id: str = "default",
+    ) -> str:
+        """Read a file's contents with line numbers (synchronous).
+
+        Synchronous wrapper around :meth:`aread`.
+
+        Args:
+            file_path: Workspace-relative or absolute path of the file to read.
+            line_offset: Zero-based index of the first line to return. Defaults to 0.
+            limit: Maximum number of lines to return. Defaults to 2000.
+            offset: Deprecated alias for ``line_offset``.
+            thread_id: Unused for sandbox backends. Accepted for protocol compatibility.
+
+        Returns:
+            A string of the requested lines prefixed with 1-based line numbers,
+            or an empty string if the selected region is empty.
+        """
+        return self._run_sync(
+            self.aread(
+                file_path,
+                line_offset=line_offset,
+                limit=limit,
+                offset=offset,
+                thread_id=thread_id,
+            )
+        )
+
+    async def aread(
+        self,
+        file_path: str,
+        line_offset: int = 0,
+        limit: int = 2000,
+        *,
+        offset: int | None = None,
+        thread_id: str = "default",
+    ) -> str:
+        """Read a file's contents with line numbers (async).
+
+        Reads the full file from the sandbox via the E2B files client, then
+        slices the requested line window and delegates formatting to
+        :func:`~aip_agents.middleware.backends.utils.format_content_with_line_numbers`.
+
+        Args:
+            file_path: Workspace-relative or absolute path of the file to read.
+            line_offset: Zero-based index of the first line to return. Defaults to 0.
+            limit: Maximum number of lines to return. Defaults to 2000.
+            offset: Deprecated alias for ``line_offset``.
+            thread_id: Unused for sandbox backends. Accepted for protocol compatibility.
+
+        Returns:
+            A string of the requested lines prefixed with 1-based line numbers,
+            or an empty string if the selected region is empty.
+        """
+        _ = thread_id
+        if offset is not None:
+            if line_offset != 0 and line_offset != offset:
+                raise ValueError("Conflicting values provided for line_offset and offset")
+            line_offset = offset
+
+        async def _attempt() -> str:
+            _, full_path, content = await self._read_text_file(file_path)
+            self._reject_binary_text(full_path, file_path, content)
+            return self._slice_line_window(content, line_offset, limit)
+
+        return await self._run_with_stale_files_recovery(_attempt, operation="aread")
+
+    async def aread_bytes(self, file_path: str) -> bytes:
+        """Read file content as raw bytes (async).
+
+        Attempts to call ``read_bytes`` on the E2B files client when available
+        (avoiding a UTF-8 decode/encode round-trip); falls back to the text
+        ``read`` API and encodes the result as UTF-8.
+
+        Args:
+            file_path: Workspace-relative or absolute path of the file to read.
+
+        Returns:
+            The raw byte content of the file.
+        """
+
+        async def _attempt() -> bytes:
+            await self._ensure_runtime()
+            files_client = await self._get_files_client()
+            full_path = self._resolve_path(file_path)
+            # The files client raises FileNotFoundError / IsADirectoryError directly.
+            content = await files_client.read(full_path, format="bytes")
+            if isinstance(content, bytes | bytearray):
+                return bytes(content)
+            return str(content).encode("utf-8")
+
+        return await self._run_with_stale_files_recovery(_attempt, operation="aread_bytes")
+
+    def read_bytes(self, file_path: str) -> bytes:
+        """Read file content as raw bytes (synchronous).
+
+        Synchronous wrapper around :meth:`aread_bytes`.
+
+        Args:
+            file_path: Workspace-relative or absolute path of the file to read.
+
+        Returns:
+            The raw byte content of the file.
+        """
+        return self._run_sync(self.aread_bytes(file_path))
+
+    def read_chars(self, file_path: str, char_offset: int = 0, max_chars: int = 20000) -> str:
+        """Read a file's contents by character position (synchronous).
+
+        Synchronous wrapper around :meth:`aread_chars`.
+
+        Args:
+            file_path: Workspace-relative or absolute path of the file to read.
+            char_offset: Character position to start from (0-indexed). Defaults to 0.
+            max_chars: Maximum number of characters to read. Defaults to 20000.
+
+        Returns:
+            File content without line numbers (raw characters).
+        """
+        return self._run_sync(self.aread_chars(file_path, char_offset=char_offset, max_chars=max_chars))
+
+    async def aread_chars(self, file_path: str, char_offset: int = 0, max_chars: int = 20000) -> str:
+        """Read a file's contents by character position (async).
+
+        Provides character-based pagination for reading large files that may have
+        very long single lines. Reads the full file and slices the requested
+        character window.
+
+        Args:
+            file_path: Workspace-relative or absolute path of the file to read.
+            char_offset: Character position to start from (0-indexed). Defaults to 0.
+            max_chars: Maximum number of characters to read. Defaults to 20000.
+
+        Returns:
+            File content without line numbers (raw characters).
+
+        Raises:
+            FileNotFoundError: If file does not exist.
+        """
+
+        async def _attempt() -> str:
+            _, full_path, content = await self._read_text_file(file_path)
+            self._reject_binary_text(full_path, file_path, content)
+            return self._slice_char_window(content, char_offset, max_chars)
+
+        return await self._run_with_stale_files_recovery(_attempt, operation="aread_chars")
+
+    def write(self, file_path: str, content: str) -> WriteResult:
+        """Write *content* to a file, creating it if necessary (synchronous).
+
+        Synchronous wrapper around :meth:`awrite`.
+
+        Args:
+            file_path: Workspace-relative or absolute destination path.
+            content: Text content to write.
+
+        Returns:
+            A :class:`~aip_agents.middleware.backends.protocol.WriteResult`
+            indicating success and the resolved path.
+        """
+        return self._run_sync(self.awrite(file_path, content))
+
+    def write_bytes(self, file_path: str, content: bytes) -> WriteResult:
+        """Write raw bytes to a file (synchronous)."""
+        self._run_sync(self.awrite_bytes(file_path, content))
+        return WriteResult(path=file_path, success=True)
+
+    async def awrite(self, file_path: str, content: str) -> WriteResult:
+        """Write *content* to a file, creating it if necessary (async).
+
+        Resolves *file_path* to an absolute sandbox path, ensures the parent
+        directory exists via :meth:`_ensure_parent_dir`, then delegates to the
+        E2B files client ``write`` API.
+
+        Args:
+            file_path: Workspace-relative or absolute destination path.
+            content: Text content to write.
+
+        Returns:
+            A :class:`~aip_agents.middleware.backends.protocol.WriteResult`
+            indicating success and the resolved path.
+        """
+
+        async def _attempt() -> WriteResult:
+            await self._ensure_runtime()
+            await self._ensure_parent_dir(file_path)
+            files_client = await self._get_files_client()
+            full_path = self._resolve_path(file_path)
+            await files_client.write(full_path, content)
+            marker = self._binary_marker(full_path)
+            if marker in self._binary_paths:
+                self._binary_paths.discard(marker)
+                await self._save_binary_paths()
+            return WriteResult(path=file_path, success=True)
+
+        return await self._run_with_stale_files_recovery(_attempt, operation="awrite")
+
+    async def awrite_bytes(self, file_path: str, content_bytes: bytes) -> None:
+        """Write raw bytes to a file, creating it if necessary (async).
+
+        Binary counterpart of :meth:`awrite`.  Ensures the parent directory
+        exists before writing so that callers (e.g. the AIP runner hydration
+        path) do not need to reach into ``_get_files_client`` or
+        ``_resolve_path`` directly.
+
+        Args:
+            file_path: Workspace-relative or absolute destination path.
+            content_bytes: Raw bytes to write.
+        """
+
+        async def _attempt() -> None:
+            await self._ensure_runtime()
+            await self._ensure_parent_dir(file_path)
+            files_client = await self._get_files_client()
+            full_path = self._resolve_path(file_path)
+            await files_client.write(full_path, content_bytes)
+            self._binary_paths.add(self._binary_marker(full_path))
+            await self._save_binary_paths()
+
+        await self._run_with_stale_files_recovery(_attempt, operation="awrite_bytes")
+
+    def edit(
+        self,
+        file_path: str,
+        old_string: str,
+        new_string: str,
+        replace_all: bool = False,
+    ) -> EditResult:
+        """Replace a string inside a file (synchronous).
+
+        Synchronous wrapper around :meth:`aedit`.
+
+        Args:
+            file_path: Workspace-relative or absolute path of the file to edit.
+            old_string: The exact substring to search for.
+            new_string: The replacement text.
+            replace_all: When ``True``, replace every occurrence of
+                *old_string*; when ``False`` (default), replace only the
+                first occurrence.
+
+        Returns:
+            An :class:`~aip_agents.middleware.backends.protocol.EditResult`
+            with ``success=True`` and an occurrence count on success, or
+            ``success=False`` and an ``error`` message on failure.
+        """
+        return self._run_sync(self.aedit(file_path, old_string, new_string, replace_all=replace_all))
+
+    async def aedit(
+        self,
+        file_path: str,
+        old_string: str,
+        new_string: str,
+        replace_all: bool = False,
+    ) -> EditResult:
+        """Replace a string inside a file (async).
+
+        Reads the current file content from the sandbox, performs the string
+        replacement via
+        :func:`~aip_agents.middleware.backends.utils.perform_string_replacement`,
+        and writes the result back.  Returns an error result if the file does
+        not exist or the replacement fails.
+
+        Args:
+            file_path: Workspace-relative or absolute path of the file to edit.
+            old_string: The exact substring to search for.
+            new_string: The replacement text.
+            replace_all: When ``True``, replace every occurrence of
+                *old_string*; when ``False`` (default), replace only the
+                first occurrence.
+
+        Returns:
+            An :class:`~aip_agents.middleware.backends.protocol.EditResult`
+            with ``success=True`` and an occurrence count on success, or
+            ``success=False`` and an ``error`` message on failure.
+        """
+
+        async def _attempt() -> EditResult:
+            try:
+                files_client, full_path, content = await self._read_text_file(file_path)
+            except ValueError:
+                return EditResult(
+                    path=file_path,
+                    error=f"Error: '{file_path}' is binary and cannot be edited",
+                    success=False,
+                )
+            except Exception as error:
+                if SandboxRuntime._is_stale_runtime_error(error):
+                    raise
+                return EditResult(
+                    path=file_path,
+                    error=f"Error: File '{file_path}' not found ({error})",
+                    success=False,
+                )
+
+            if self._is_binary_payload(full_path, content):
+                return EditResult(
+                    path=file_path, error=f"Error: '{file_path}' is binary and cannot be edited", success=False
+                )
+
+            replacement = perform_string_replacement(content, old_string, new_string, replace_all)
+            if isinstance(replacement, str):
+                return EditResult(path=file_path, error=replacement, success=False)
+
+            new_content, occurrences = replacement
+            if not await self._write_text_with_stale_retry(
+                files_client,
+                full_path,
+                new_content,
+                operation="aedit",
+            ):
+                return EditResult(
+                    path=file_path,
+                    error=f"Error: stale transport remained after retry while editing '{file_path}'",
+                    success=False,
+                )
+            marker = self._binary_marker(full_path)
+            if marker in self._binary_paths:
+                self._binary_paths.discard(marker)
+                await self._save_binary_paths()
+            return EditResult(path=file_path, occurrences=occurrences, success=True)
+
+        return await self._run_with_stale_files_recovery(_attempt, operation="aedit")
+
+    def glob_info(self, pattern: str, path: str = "/") -> list[FileInfo]:
+        """Find files matching a glob pattern (synchronous).
+
+        Synchronous wrapper around :meth:`aglob_info`.
+
+        Args:
+            pattern: A glob pattern (e.g. ``"**/*.py"``) matched against
+                workspace-relative paths and bare file names.
+            path: Root directory to search.  Defaults to the workspace root
+                (``"/"``).
+
+        Returns:
+            A list of :class:`~aip_agents.middleware.backends.protocol.FileInfo`
+            objects for all matching entries.
+        """
+        return self._run_sync(self.aglob_info(pattern, path=path))
+
+    async def aglob_info(self, pattern: str, path: str = "/") -> list[FileInfo]:
+        """Find files matching a glob pattern (async).
+
+        Recursively lists all entries under *path* using the E2B files client
+        and filters them with :func:`fnmatch.fnmatch` against both the
+        workspace-relative path and the bare file name.
+
+        Args:
+            pattern: A glob pattern (e.g. ``"**/*.py"``) matched against
+                workspace-relative paths and bare file names.
+            path: Root directory to search.  Defaults to the workspace root
+                (``"/"``).
+
+        Returns:
+            A list of :class:`~aip_agents.middleware.backends.protocol.FileInfo`
+            objects for all matching entries.
+        """
+
+        async def _attempt() -> list[FileInfo]:
+            await self._ensure_runtime()
+            files_client = await self._get_files_client()
+            base_path = self._resolve_path(path)
+            entries = await files_client.list(base_path)
+
+            matches: list[FileInfo] = []
+            for entry in entries:
+                full_entry_path = f"{base_path}/{entry.name}".replace("//", "/")
+                if self._is_metadata_path(full_entry_path):
+                    continue
+                rel_path = self._to_relative_path(full_entry_path)
+                if not (fnmatch.fnmatch(rel_path, pattern) or fnmatch.fnmatch(entry.name, pattern)):
+                    continue
+
+                is_dir = "dir" in str(getattr(entry, "type", ""))
+                if is_dir:
+                    matches.append(FileInfo(path=rel_path, type="directory", size=None))
+                else:
+                    matches.append(FileInfo(path=rel_path, type="file", size=getattr(entry, "size", None)))
+            return matches
+
+        return await self._run_with_stale_files_recovery(_attempt, operation="aglob_info")
+
+    def grep_raw(self, pattern: str, path: str | None = None) -> list[GrepMatch] | str:
+        """Search for a text pattern across files (synchronous).
+
+        Synchronous wrapper around :meth:`agrep_raw`.
+
+        Args:
+            pattern: Literal string to search for (passed to ``rg -F``).
+            path: Directory or file to search within.  Defaults to
+                ``base_dir`` when ``None``.
+
+        Returns:
+            A list of :class:`~aip_agents.middleware.backends.protocol.GrepMatch`
+            objects on success.
+        """
+        return self._run_sync(self.agrep_raw(pattern, path=path))
+
+    async def agrep_raw(self, pattern: str, path: str | None = None) -> list[GrepMatch] | str:
+        """Search for a literal text pattern across sandbox files (async).
+
+        Uses the sandbox files API instead of shell execution so pattern and path
+        arguments never become executable command text.
+
+        Args:
+            pattern: Literal string to search for.
+            path: Directory or file to search within.  Defaults to
+                ``base_dir`` when ``None``.
+
+        Returns:
+            A list of :class:`~aip_agents.middleware.backends.protocol.GrepMatch`
+            objects on success.
+        """
+
+        async def _attempt() -> list[GrepMatch] | str:
+            await self._ensure_runtime()
+            files_client = await self._get_files_client()
+            search_path = self._resolve_path(path or self.base_dir)
+
+            try:
+                return await self._agrep_directory(files_client, search_path, pattern)
+            except Exception as exc:
+                if SandboxRuntime._is_stale_runtime_error(exc):
+                    raise
+                return await self._agrep_file(files_client, search_path, pattern)
+
+        return await self._run_with_stale_files_recovery(_attempt, operation="agrep_raw")
+
+    async def _agrep_directory(self, files_client: Any, directory: str, pattern: str) -> list[GrepMatch]:
+        """Search a sandbox directory recursively via the files API."""
+        matches: list[GrepMatch] = []
+        entries = await files_client.list(directory)
+        for entry in entries:
+            full_path = self._resolve_child_path(directory, entry.name)
+            if full_path is None or self._is_metadata_path(full_path):
+                continue
+            if self._is_directory_entry(entry):
+                matches.extend(await self._agrep_directory(files_client, full_path, pattern))
+                continue
+            matches.extend(await self._agrep_file(files_client, full_path, pattern))
+        return matches
+
+    async def _agrep_file(self, files_client: Any, full_path: str, pattern: str) -> list[GrepMatch]:
+        """Search one sandbox file via the files API."""
+        if self._is_metadata_path(full_path) or await self._is_binary_path(full_path):
+            return []
+        try:
+            content = await files_client.read(full_path)
+        except Exception as exc:
+            if SandboxRuntime._is_stale_runtime_error(exc):
+                raise
+            return []
+        if not isinstance(content, str) or self._is_binary_payload(full_path, content):
+            return []
+        return [
+            GrepMatch(path=self._to_relative_path(full_path), line_number=line_number, content=line_text)
+            for line_number, line_text in enumerate(content.splitlines(), start=1)
+            if pattern in line_text
+        ]
+
+    def grep(self, pattern: str, path: str | None = None) -> list[GrepMatch]:
+        """Search for a text pattern, always returning a list (synchronous).
+
+        Calls :meth:`grep_raw` and suppresses the error-string variant,
+        returning an empty list whenever the underlying search fails.
+
+        Args:
+            pattern: Literal string to search for.
+            path: Directory or file to search within.  Defaults to
+                ``base_dir`` when ``None``.
+
+        Returns:
+            A (possibly empty) list of
+            :class:`~aip_agents.middleware.backends.protocol.GrepMatch` objects.
+        """
+        result = self.grep_raw(pattern, path=path)
+        if isinstance(result, str):
+            return []
+        return result
+
+    def execute(self, command: str, timeout: int = 30) -> ExecuteResult:
+        """Execute a shell command inside the sandbox (synchronous).
+
+        Synchronous wrapper around :meth:`aexecute`.
+
+        Args:
+            command: Shell command string to run.
+            timeout: Maximum number of seconds to wait for the command to
+                finish.  Defaults to 30.
+
+        Returns:
+            An :class:`~aip_agents.middleware.backends.protocol.ExecuteResult`
+            containing ``stdout``, ``stderr``, and ``exit_code``.
+
+        Raises:
+            PermissionError: If ``allow_execute`` is ``False``.
+        """
+        return self._run_sync(self.aexecute(command, timeout=timeout))
+
+    def _reset_backend_runtime(self) -> None:
+        """Clear cached loop-bound state for fresh recreation on the current loop.
+
+        Resets the SandboxRuntime's loop-bound sandbox client (if any) and
+        clears the cached files-client and base-dir flags so that the next
+        ``_ensure_runtime()`` re-initialises transport on the current loop
+        without discarding an injected runtime reference.
+        """
+        runtime = self._runtime
+        if isinstance(runtime, SandboxRuntime):
+            runtime._reset_for_new_loop()
+        self._invalidate_cached_files_client()
+
+    async def _run_with_stale_files_recovery(
+        self,
+        attempt: Callable[[], Awaitable[Any]],
+        *,
+        operation: str,
+    ) -> Any:
+        """Run one filesystem operation and retry once after stale transport reset."""
+        try:
+            return await attempt()
+        except Exception as exc:
+            if SandboxRuntime._is_stale_runtime_error(exc) or self._is_stale_files_error(exc):
+                logger.info(
+                    "%s: detected stale filesystem transport (%r), resetting and retrying once",
+                    operation,
+                    exc,
+                )
+                self._reset_backend_runtime()
+                return await attempt()
+            raise
+
+    @staticmethod
+    def _is_stale_files_error(error: BaseException) -> bool:
+        """Return True for filesystem adapter errors caused by dropped uploads."""
+        current: BaseException | None = error
+        seen: set[int] = set()
+        while current is not None and id(current) not in seen:
+            seen.add(id(current))
+            if STALE_FILE_UPLOAD_MARKER in str(current).lower():
+                return True
+            current = current.__cause__ or current.__context__
+        return False
+
+    async def _aexecute_runtime_result(self, command: str, timeout: int) -> Any:
+        """Execute a single runtime command attempt without backend recovery."""
+        runtime = await self._ensure_runtime_instance()
+        runtime_any = cast(Any, runtime)
+        command_env = self._env
+        execute_command = getattr(runtime_any, "execute_command", None)
+        if callable(execute_command):
+            return await execute_command(command, timeout=timeout, env=command_env)
+        return await runtime_any.execute(command, timeout=timeout, env=command_env)
+
+    def _to_execute_result(self, result: Any) -> ExecuteResult:
+        """Convert a runtime execution result into the backend protocol shape."""
+        return ExecuteResult(
+            stdout=redact_secrets(result.stdout, self._env),
+            stderr=redact_secrets(result.stderr, self._env),
+            exit_code=result.exit_code,
+            truncated=False,
+        )
+
+    @staticmethod
+    def _is_diagnostic_stale_result(result: Any) -> bool:
+        """Return True when runtime diagnostics explicitly mark a stale transport."""
+        if getattr(result, "exit_code", 0) == 0:
+            return False
+        diagnostics = getattr(result, "diagnostics", {}) or {}
+        return diagnostics.get("stale_runtime_transport") is True
+
+    async def _aexecute_impl(self, command: str, timeout: int) -> ExecuteResult:
+        """Execute a single command attempt (internal, without recovery)."""
+        result = await self._aexecute_runtime_result(command, timeout)
+        return self._to_execute_result(result)
+
+    async def aexecute(self, command: str, timeout: int = 30) -> ExecuteResult:
+        """Execute a shell command inside the sandbox (async).
+
+        Delegates shell execution to runtime when available. For
+        :class:`SandboxRuntime`, this uses its dedicated command path.
+
+        When the runtime or its underlying transport was bound to a now-closed
+        event loop (uvloop ``TCPTransport closed``, asyncio
+        ``Event loop is closed``, etc.), this method resets the cached runtime
+        and retries once.
+
+        Args:
+            command: Shell command string to run.
+            timeout: Maximum number of seconds to wait for the command to
+                finish.  Defaults to 30.
+
+        Returns:
+            An :class:`~aip_agents.middleware.backends.protocol.ExecuteResult`
+            containing ``stdout``, ``stderr``, ``exit_code``, and
+            ``truncated=False``.
+
+        Raises:
+            PermissionError: If ``allow_execute`` is ``False``.
+        """
+        if not self.allow_execute:
+            raise PermissionError("execute() disabled for this backend")
+        try:
+            result = await self._aexecute_runtime_result(command, timeout)
+        except Exception as exc:
+            if SandboxRuntime._is_stale_runtime_error(exc):
+                logger.info(
+                    "aexecute: detected stale runtime/transport (%r), resetting and retrying once",
+                    exc,
+                )
+                self._reset_backend_runtime()
+                return await self._aexecute_impl(command, timeout)
+            raise
+        if self._is_diagnostic_stale_result(result):
+            logger.info("aexecute: detected stale runtime/transport result, resetting and retrying once")
+            self._reset_backend_runtime()
+            return await self._aexecute_impl(command, timeout)
+        return self._to_execute_result(result)
+
+    def set_files(self, files: dict[str, Any], thread_id: str = "default") -> None:
+        """Write a batch of files into the sandbox workspace (synchronous).
+
+        Synchronous wrapper around :meth:`aset_files`.
+
+        Args:
+            files: Mapping of workspace-relative file paths to their text
+                content.  Non-string values are coerced with ``str()``.
+            thread_id: Logical thread identifier (reserved for future
+                partitioned workspace support). Defaults to ``"default"``.
+        """
+        self._run_sync(self.aset_files(files, thread_id=thread_id))
+
+    async def aset_files(self, files: dict[str, Any], thread_id: str = "default") -> None:
+        """Write a batch of files into the sandbox workspace (async).
+
+        Iterates over *files* and writes each entry to the sandbox via the E2B
+        files client.  Paths are resolved relative to ``base_dir``.
+
+        Args:
+            files: Mapping of workspace-relative file paths to their text
+                content.  Non-string values are coerced with ``str()``.
+            thread_id: Logical thread identifier (reserved for future
+                partitioned workspace support). Defaults to ``"default"``.
+        """
+        _ = thread_id
+
+        async def _attempt() -> None:
+            await self._ensure_runtime()
+            files_client = await self._get_files_client()
+            await self._write_files_batch(files_client, files)
+
+        await self._run_with_stale_files_recovery(_attempt, operation="aset_files")
+
+    def get_files(self, thread_id: str = "default") -> dict[str, Any]:
+        """Read all files from the sandbox workspace for checkpointing (synchronous).
+
+        Synchronous wrapper around :meth:`aget_files`.
+
+        Args:
+            thread_id: Logical thread identifier (reserved for future
+                partitioned workspace support). Defaults to ``"default"``.
+
+        Returns:
+            A mapping of workspace-relative file paths to their text content.
+        """
+        return self._run_sync(self.aget_files(thread_id=thread_id))
+
+    async def aget_files(self, thread_id: str = "default") -> dict[str, Any]:
+        """Read all files from the sandbox workspace for checkpointing (async).
+
+        Recursively walks entries under ``base_dir`` and reads the text content
+        of each file via the E2B files client.
+
+        Args:
+            thread_id: Logical thread identifier (reserved for future
+                partitioned workspace support). Defaults to ``"default"``.
+
+        Returns:
+            A mapping of workspace-relative file paths to their text content.
+        """
+        _ = thread_id
+
+        async def _attempt() -> dict[str, Any]:
+            await self._ensure_runtime()
+            files_client = await self._get_files_client()
+            files: dict[str, Any] = {}
+            await self._collect_sandbox_files(files_client, self.base_dir, files, set())
+            return files
+
+        return await self._run_with_stale_files_recovery(_attempt, operation="aget_files")
+
+    async def cleanup(self) -> None:
+        """Release all sandbox resources and reset internal state."""
+        if self._runtime is not None:
+            await self._runtime.cleanup()
+        self._runtime = None
+        self._files_client = None
+        self._runtime_loop = None
+        self._base_dir_initialized = False
+        self._binary_paths.clear()