Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

16.4 KB
Raw Blame
"""Abstract interface for sandbox backends."""

import asyncio
import os
import posixpath
import re
import shutil
from abc import ABC, abstractmethod
from collections import deque
from collections.abc import AsyncIterator
from dataclasses import dataclass
from pathlib import Path
from typing import Any


@dataclass(frozen=True)
class SandboxFileInfo:
    """A regular file in the sandbox workspace."""

    path: str
    size: int


class SandboxBackend(ABC):
    """Abstract base class for sandbox backends."""

    def __init__(self):
        pass

    @abstractmethod
    async def start(self) -> None:
        """Start the sandbox instance."""

    @abstractmethod
    async def execute(self, command: str, timeout: int = 60, **kwargs: Any) -> str:
        """Execute a command in the sandbox."""

    @abstractmethod
    async def stop(self) -> None:
        """Stop the sandbox instance and clean up resources."""

    @abstractmethod
    def is_running(self) -> bool:
        """Check if the sandbox is running."""

    @property
    @abstractmethod
    def workspace(self) -> Path:
        """Get the sandbox workspace directory on the host."""

    @property
    def sandbox_cwd(self) -> str:
        """Get the current working directory inside the sandbox.

        Returns:
            Path string (e.g., "/", "/workspace")
        """
        return "/"

    def _check_path_restriction(self, path: Path) -> None:
        """Check if path is within workspace (if restricted).

        Args:
            path: Path to check

        Raises:
            PermissionError: If path outside workspace and restriction is enabled
        """

        workspace = self.workspace.resolve()
        resolved = path.resolve()

        if resolved != workspace and workspace not in resolved.parents:
            raise PermissionError(f"Path outside workspace: {path}")

    def _resolve_path(self, path: str) -> Path:
        """Resolve path to sandbox workspace.

        Args:
            path: Input path (absolute or relative)

        Returns:
            Resolved Path object in sandbox workspace
        """
        input_path = Path(path)
        if input_path.is_absolute():
            if path == "/":
                return self.workspace
            return self.workspace / path.lstrip("/")
        return self.workspace / path

    @staticmethod
    def _normalize_workspace_path(path: str) -> str:
        """Normalize a workspace-relative path used by bounded file APIs."""
        value = str(path)
        if value in {"", ".", "./"}:
            return ""
        candidate = Path(value)
        if candidate.is_absolute() or ".." in candidate.parts:
            raise ValueError(f"Path must be relative to the sandbox workspace: {path}")
        return candidate.as_posix().removeprefix("./")

    @staticmethod
    def _join_workspace_path(directory: str, name: str) -> str:
        if not name or name in {".", ".."} or "/" in name:
            raise IOError(f"Invalid sandbox directory entry: {name!r}")
        return posixpath.join(directory, name) if directory else name

    @staticmethod
    def _validate_max_bytes(max_bytes: int | None) -> None:
        if max_bytes is not None and max_bytes < 0:
            raise ValueError("max_bytes must be non-negative")

    @staticmethod
    def _validate_max_entries(max_entries: int | None) -> None:
        if max_entries is not None and max_entries <= 0:
            raise ValueError("max_entries must be positive")

    @staticmethod
    def _read_local_bytes(path: Path, original_path: str, max_bytes: int | None) -> bytes:
        if not path.exists():
            raise FileNotFoundError(f"File not found: {original_path}")
        if not path.is_file():
            raise IOError(f"Not a file: {original_path}")
        with path.open("rb") as stream:
            data = stream.read() if max_bytes is None else stream.read(max_bytes + 1)
        if max_bytes is not None and len(data) > max_bytes:
            raise ValueError(f"File exceeds the {max_bytes}-byte read limit: {original_path}")
        return data

    @staticmethod
    def _copy_local_file(
        source: Path,
        destination: Path,
        original_path: str,
        max_bytes: int | None,
    ) -> int:
        """Copy one host file with bounded memory and remove partial output on failure."""
        if not source.exists():
            raise FileNotFoundError(f"File not found: {original_path}")
        if not source.is_file():
            raise IOError(f"Not a file: {original_path}")
        size = source.stat().st_size
        if max_bytes is not None and size > max_bytes:
            raise ValueError(f"File exceeds the {max_bytes}-byte export limit: {original_path}")
        if source.resolve() == destination.resolve():
            return size
        destination.parent.mkdir(parents=True, exist_ok=True)
        total = 0
        try:
            with source.open("rb") as input_stream, destination.open("wb") as output_stream:
                while chunk := input_stream.read(1024 * 1024):
                    total += len(chunk)
                    if max_bytes is not None and total > max_bytes:
                        raise ValueError(
                            f"File exceeds the {max_bytes}-byte export limit: {original_path}"
                        )
                    output_stream.write(chunk)
        except Exception:
            destination.unlink(missing_ok=True)
            raise
        return total

    @staticmethod
    async def _collect_stream_bytes(
        stream: AsyncIterator[bytes],
        original_path: str,
        max_bytes: int | None,
    ) -> bytes:
        """Collect a byte stream while retaining at most ``max_bytes + 1`` bytes."""
        limit = None if max_bytes is None else max_bytes + 1
        data = bytearray()
        try:
            async for chunk in stream:
                if limit is None:
                    data.extend(chunk)
                    continue
                remaining = limit - len(data)
                if remaining <= 0:
                    break
                data.extend(chunk[:remaining])
                if len(data) >= limit:
                    break
        finally:
            close = getattr(stream, "aclose", None)
            if close is not None:
                await close()
        if max_bytes is not None and len(data) > max_bytes:
            raise ValueError(f"File exceeds the {max_bytes}-byte read limit: {original_path}")
        return bytes(data)

    @staticmethod
    async def _export_stream_to_local(
        stream: AsyncIterator[bytes],
        destination: Path,
        original_path: str,
        max_bytes: int | None,
    ) -> int:
        """Write a remote byte stream locally while retaining only one chunk in memory."""
        await asyncio.to_thread(destination.parent.mkdir, parents=True, exist_ok=True)
        total = 0
        output_stream = None
        try:
            output_stream = await asyncio.to_thread(destination.open, "wb")
            async for chunk in stream:
                if not isinstance(chunk, (bytes, bytearray, memoryview)):
                    raise IOError(f"Sandbox returned invalid file bytes: {original_path}")
                total += len(chunk)
                if max_bytes is not None and total > max_bytes:
                    raise ValueError(
                        f"File exceeds the {max_bytes}-byte export limit: {original_path}"
                    )
                await asyncio.to_thread(output_stream.write, chunk)
        except BaseException:
            if output_stream is not None:
                await asyncio.to_thread(output_stream.close)
                output_stream = None
            await asyncio.to_thread(destination.unlink, missing_ok=True)
            raise
        finally:
            if output_stream is not None:
                await asyncio.to_thread(output_stream.close)
            close = getattr(stream, "aclose", None)
            if close is not None:
                await close()
        return total

    def local_file_path(self, path: str) -> Path | None:
        """Return a safe host path when this sandbox workspace is host-accessible."""
        sandbox_path = self._resolve_path(path)
        self._check_path_restriction(sandbox_path)
        if not sandbox_path.exists():
            raise FileNotFoundError(f"File not found: {path}")
        if not sandbox_path.is_file():
            raise IOError(f"Not a file: {path}")
        return sandbox_path

    async def export_file(
        self,
        path: str,
        destination: Path,
        *,
        max_bytes: int | None = None,
    ) -> int:
        """Export a sandbox file to the host without materializing it in Bot memory."""
        self._validate_max_bytes(max_bytes)
        source = self.local_file_path(path)
        if source is None:
            raise IOError("Sandbox does not expose a host file path or streaming exporter")
        return await asyncio.to_thread(
            self._copy_local_file,
            source,
            destination,
            path,
            max_bytes,
        )

    async def read_file_bytes(self, path: str, *, max_bytes: int | None = None) -> bytes:
        """Read file bytes from sandbox (default implementation: host filesystem).

        Args:
            path: Path to file (absolute or relative to sandbox_cwd)
            max_bytes: Optional hard read limit. At most ``max_bytes + 1``
                bytes are read before an oversized file is rejected.

        Returns:
            File content as bytes

        Raises:
            FileNotFoundError: If file doesn't exist
            IOError: If read fails
            PermissionError: If path outside workspace and restriction is enabled
        """
        self._validate_max_bytes(max_bytes)
        sandbox_path = self.local_file_path(path)
        if sandbox_path is None:
            raise IOError("Sandbox file is not accessible from the host")
        return await asyncio.to_thread(self._read_local_bytes, sandbox_path, path, max_bytes)

    async def list_files(
        self,
        path: str = ".",
        *,
        max_entries: int | None,
    ) -> list[SandboxFileInfo]:
        """Recursively list regular files, with no inventory quota when ``max_entries`` is None.

        Returned paths are relative to the sandbox workspace, including ``path``
        when a subdirectory is requested. A supplied quota counts directories and
        files and raises ValueError on overflow. Symlinks are not followed.
        """
        self._validate_max_entries(max_entries)
        root = self._normalize_workspace_path(path)
        root_path = self._resolve_path(root)
        self._check_path_restriction(root_path)

        def inventory() -> list[SandboxFileInfo]:
            pending = deque([(root, root_path)])
            files: list[SandboxFileInfo] = []
            visited = 0
            while pending:
                directory, local_directory = pending.popleft()
                try:
                    stream = os.scandir(local_directory)
                except FileNotFoundError:
                    continue
                with stream:
                    for entry in stream:
                        visited += 1
                        if max_entries is not None and visited > max_entries:
                            raise ValueError(
                                f"Sandbox workspace inventory exceeds {max_entries} entries"
                            )
                        relative = self._join_workspace_path(directory, entry.name)
                        try:
                            if entry.is_dir(follow_symlinks=False):
                                pending.append((relative, Path(entry.path)))
                            elif entry.is_file(follow_symlinks=False):
                                files.append(
                                    SandboxFileInfo(
                                        path=relative,
                                        size=entry.stat(follow_symlinks=False).st_size,
                                    )
                                )
                        except FileNotFoundError:
                            # The Agent may still be writing while salvage takes its snapshot.
                            continue
            return sorted(files, key=lambda item: item.path)

        return await asyncio.to_thread(inventory)

    async def read_file(self, path: str) -> str:
        """Read file from sandbox (default implementation: host filesystem).

        Args:
            path: Path to file (absolute or relative to sandbox_cwd)

        Returns:
            File content as string

        Raises:
            FileNotFoundError: If file doesn't exist
            IOError: If read fails
            PermissionError: If path outside workspace and restriction is enabled
        """
        data = await self.read_file_bytes(path)
        try:
            return data.decode("utf-8")
        except UnicodeDecodeError:
            # Some benchmark/tool artifacts may contain Windows-1252 smart quotes
            # (e.g. byte 0x92) or other non-UTF-8 bytes.  read_file is a user-facing
            # text tool; preserve progress by decoding lossily instead of failing
            # the entire agent rollout.
            return data.decode("utf-8", errors="replace")

    async def write_file(self, path: str, content: str) -> None:
        """Write file to sandbox (default implementation: host filesystem).

        Args:
            path: Path to file (absolute or relative to sandbox_cwd)
            content: Content to write

        Raises:
            IOError: If write fails
            PermissionError: If path outside workspace and restriction is enabled
        """
        sandbox_path = self._resolve_path(path)
        self._check_path_restriction(sandbox_path)
        sandbox_path.parent.mkdir(parents=True, exist_ok=True)
        sandbox_path.write_text(content, encoding="utf-8")

    async def write_file_bytes(self, path: str, content: bytes) -> None:
        """Write binary content inside the sandbox workspace."""
        sandbox_path = self._resolve_path(path)
        self._check_path_restriction(sandbox_path)
        sandbox_path.parent.mkdir(parents=True, exist_ok=True)
        await asyncio.to_thread(sandbox_path.write_bytes, content)

    async def remove_tree(self, path: str) -> None:
        """Remove one sandbox-relative directory tree."""
        sandbox_path = self._resolve_path(path)
        self._check_path_restriction(sandbox_path)
        if sandbox_path.resolve() == self.workspace.resolve():
            raise PermissionError("Refusing to remove the sandbox workspace root")
        if sandbox_path.exists():
            await asyncio.to_thread(shutil.rmtree, sandbox_path)

    @staticmethod
    def _ensure_command_succeeded(output: str, operation: str) -> None:
        """Raise when a backend's rendered command result contains a non-zero exit code."""
        exit_codes = [
            int(value) for value in re.findall(r"(?:^|\n)Exit code:\s*(-?\d+)(?:\n|$)", str(output))
        ]
        if any(code != 0 for code in exit_codes):
            raise SandboxExecutionError(f"{operation} failed: {output}")

    async def list_dir(self, path: str) -> list[tuple[str, bool]]:
        """List directory in sandbox (default implementation: host filesystem).

        Args:
            path: Path to directory (absolute or relative to sandbox_cwd)

        Returns:
            List of (name, is_dir) tuples

        Raises:
            FileNotFoundError: If directory doesn't exist
            IOError: If not a directory
            PermissionError: If path outside workspace and restriction is enabled
        """
        sandbox_path = self._resolve_path(path)
        self._check_path_restriction(sandbox_path)
        if not sandbox_path.exists():
            raise FileNotFoundError(f"Directory not found: {path}")
        if not sandbox_path.is_dir():
            raise IOError(f"Not a directory: {path}")

        items = []
        for item in sorted(sandbox_path.iterdir()):
            items.append((item.name, item.is_dir()))
        return items


class SandboxError(Exception):
    """Base exception for sandbox errors."""


class SandboxNotStartedError(SandboxError):
    """Raised when trying to execute commands in a non-started sandbox."""


class SandboxDisabledError(SandboxError):
    """Raised when sandbox functionality is disabled."""


class SandboxExecutionError(SandboxError):
    """Raised when sandbox command execution fails."""


class UnsupportedBackendError(SandboxError):
    """Raised when an unsupported sandbox backend is requested."""