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

aip_agents/sandbox/sandbox_runtime.py

@@ -0,0 +1,967 @@
+"""Provider-agnostic sandbox runtime for PTC.
+
+Orchestrates per-run sandbox lifecycle (create → reuse → cleanup) against the
+generic ``CodeInterpreterSandbox`` interface. Backend selection and all
+create-time asymmetry live behind the provider factory (``sandbox/providers``);
+this runtime never imports a specific backend SDK.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+import asyncio
+import json
+import math
+import os
+from collections.abc import Awaitable, Callable
+from pathlib import Path
+from typing import Any
+
+from gllm_inference.schema import Attachment
+from gllm_tools.code_interpreter.code_sandbox.models import ExecutionResult, ExecutionStatus
+from gllm_tools.code_interpreter.code_sandbox.sandbox import CodeInterpreterSandbox
+
+from aip_agents.sandbox.defaults import (
+    DEFAULT_SANDBOX_PACKAGES,
+    DEFAULT_SANDBOX_TEMPLATE,
+)
+from aip_agents.sandbox.providers import SandboxConfig, get_provider
+from aip_agents.sandbox.types import SandboxExecutionResult
+from aip_agents.sandbox.validation import validate_package_names
+from aip_agents.utils.logger import get_logger
+
+# Type alias for package selector callback.
+# Called after sandbox creation with actual template status (None if template failed).
+PackageSelector = Callable[[str | None], list[str] | None]
+
+logger = get_logger(__name__)
+
+SANDBOX_NOT_INITIALIZED_ERROR = "Sandbox not initialized"
+DEFAULT_PACKAGE_INSTALL_TIMEOUT_SECONDS = 300.0
+E2B_COMMANDS_BACKEND = "e2b_commands"
+E2B_CODE_INTERPRETER_BACKEND = "e2b_code_interpreter"
+E2B_COMMAND_TIMEOUT_SOURCE = "e2b_command_timeout"
+PTC_EXECUTION_TIMEOUT_SOURCE = "ptc_execution_timeout"
+LOCAL_ASYNCIO_TIMEOUT_SOURCE = "local_asyncio_timeout"
+CODE_INTERPRETER_TIMEOUT_SOURCE = "e2b_code_interpreter_status_timeout"
+CODE_INTERPRETER_BACKEND_TIMEOUT_SOURCE = "e2b_code_interpreter_backend_timeout"
+STALE_RUNTIME_TRANSPORT_DIAGNOSTIC = "stale_runtime_transport"
+BACKEND_TIMEOUT_MARKERS = (
+    "unexpectedendofexecution",
+    "deadline exceeded",
+    "timed out",
+)
+BOUND_TO_DIFFERENT_EVENT_LOOP_MARKER = "bound to a different event loop"
+
+_HANDLER_IS_CLOSED_MARKER = "handler is closed"
+_CLOSEABLE_TRANSPORT_ERROR_MARKERS = (
+    _HANDLER_IS_CLOSED_MARKER,
+    "tcptransport closed",
+    "event loop is closed",
+    BOUND_TO_DIFFERENT_EVENT_LOOP_MARKER,
+    "transport closed",
+)
+
+_STALE_RUNTIME_RESULT_MARKER_GROUPS = (
+    ("asyncio.locks.event", BOUND_TO_DIFFERENT_EVENT_LOOP_MARKER),
+    ("tcptransport closed", _HANDLER_IS_CLOSED_MARKER),
+    ("unable to perform operation on", _HANDLER_IS_CLOSED_MARKER),
+)
+
+
+class SandboxRuntime:
+    """Sandbox runtime for executing code in isolated environments.
+
+    This runtime manages per-run sandbox lifecycle:
+    - Create sandbox on first execute
+    - Reuse sandbox for subsequent executes
+    - Destroy sandbox on cleanup
+
+    Example:
+        runtime = SandboxRuntime()
+        result = await runtime.execute(
+            code="print('Hello')",
+            timeout=60.0,
+            files={"tools/mcp.py": "# MCP client code"},
+        )
+        await runtime.cleanup()
+    """
+
+    prefer_python_file_execution = True
+
+    def __init__(
+        self,
+        template: str | None = None,
+        packages: list[str] | None = None,
+        package_selector: PackageSelector | None = None,
+        sandbox_timeout: int = 300,
+        package_install_timeout: float | None = None,
+        auto_build_template: bool = False,
+        build_base_template: str = "code-interpreter-v1",
+        api_key: str | None = None,
+        domain: str | None = None,
+        provider: Any | None = None,
+        # Backward compatibility: accept old parameter name
+        ptc_packages: list[str] | None = None,
+    ) -> None:
+        """Initialize sandbox runtime.
+
+        Args:
+            template: Optional E2B template ID for custom sandbox environments.
+            packages: Packages to install in sandbox. If None or empty, skip install.
+                Overwritten by package_selector if provided.
+            package_selector: Optional callback to select packages after sandbox creation.
+                Called with actual template (None if template failed) to enable smart
+                package selection based on whether template was successfully created.
+            sandbox_timeout: Timeout in seconds for the sandbox session. Defaults to 300.
+                This prevents "port is not open" errors by keeping the sandbox alive.
+            package_install_timeout: Timeout in seconds for package installation.
+                When None, uses the runtime default. Values <= 0 disable the E2B
+                command timeout for package installation.
+            auto_build_template: If True and the requested template returns 404, attempt
+                to build it automatically before falling back to the default sandbox.
+                Building can take several minutes. Defaults to False.
+            build_base_template: Base E2B template to build from when auto-building.
+                Defaults to ``"code-interpreter-v1"``.
+            api_key: Provider API key override. E2B falls back to ``E2B_API_KEY``
+                when not provided.
+            domain: Optional provider domain override. E2B falls back to
+                ``E2B_DOMAIN`` when not provided.
+            provider: Sandbox provider name/enum. Defaults to ``SANDBOX_PROVIDER``
+                then ``"e2b"``.
+            ptc_packages: Deprecated. Use `packages` instead.
+        """
+        self._template = template
+        # Handle backward compatibility
+        if ptc_packages is not None and packages is None:
+            packages = ptc_packages
+        self._packages = packages
+        self._package_selector = package_selector
+        self._provider = provider if provider is not None else os.environ.get("SANDBOX_PROVIDER", "e2b")
+        if self._provider_name == "e2b":
+            self._api_key = api_key if api_key is not None else os.environ.get("E2B_API_KEY")
+            self._domain = domain if domain is not None else os.environ.get("E2B_DOMAIN")
+        else:
+            self._api_key = api_key
+            self._domain = domain
+        self._sandbox: CodeInterpreterSandbox | None = None
+        self._sandbox_created_with_template = False
+        self._reset_listeners: list[Callable[[], None]] = []
+        self._sandbox_timeout = sandbox_timeout
+        self._package_install_timeout = (
+            DEFAULT_PACKAGE_INSTALL_TIMEOUT_SECONDS if package_install_timeout is None else package_install_timeout
+        )
+        self._auto_build_template = auto_build_template
+        self._build_base_template = build_base_template
+
+    @property
+    def _provider_name(self) -> str:
+        """Return the configured provider registry name."""
+        return str(getattr(self._provider, "value", self._provider)).lower()
+
+    async def execute(
+        self,
+        code: str,
+        *,
+        timeout: float = 300,  # NOSONAR - public API; execution uses asyncio.timeout below.
+        files: dict[str, str] | None = None,
+        env: dict[str, str] | None = None,
+        template: str | None = None,
+    ) -> SandboxExecutionResult:
+        """Execute code inside the sandbox.
+
+        Args:
+            code: Python code to execute.
+            timeout: Execution timeout in seconds.
+            files: Files to upload to the sandbox (path -> content).
+            env: Environment variables to set.
+            template: Optional template override for this execution.
+
+        Returns:
+            SandboxExecutionResult with stdout, stderr, and exit_code.
+        """
+        return await self._run_with_stale_runtime_recovery(
+            lambda: self._execute_impl(
+                code,
+                execution_timeout=timeout,
+                files=files,
+                env=env,
+                template=template,
+            ),
+            operation="execute",
+        )
+
+    async def _execute_impl(
+        self,
+        code: str,
+        *,
+        execution_timeout: float,
+        files: dict[str, str] | None,
+        env: dict[str, str] | None,
+        template: str | None,
+    ) -> SandboxExecutionResult:
+        """Execute one code attempt without stale-runtime recovery."""
+        if self._sandbox is None:
+            await self._ensure_sandbox(template or self._template, timeout_budget_seconds=execution_timeout)
+
+        await self._apply_sandbox_timeout()
+
+        if files:
+            await self._upload_files(files)
+
+        async with asyncio.timeout(execution_timeout):
+            return await self._run_code(code, env, timeout=execution_timeout)
+
+    async def execute_command(
+        self,
+        command: str,
+        *,
+        timeout: float = 30,  # NOSONAR - public API; execution uses asyncio.timeout below.
+        env: dict[str, str] | None = None,
+    ) -> SandboxExecutionResult:
+        """Execute a shell command in the sandbox.
+
+        Args:
+            command: Shell command to execute.
+            timeout: Command timeout in seconds.
+            env: Optional environment variables.
+
+        Returns:
+            SandboxExecutionResult containing stdout, stderr, and exit_code.
+
+        Notes:
+            Delegates to the provider-neutral sandbox command surface when
+            available, otherwise falls back to ``execute_code`` with
+            ``subprocess.run`` inside the sandbox.
+        """
+        return await self._run_with_stale_runtime_recovery(
+            lambda: self._execute_command_impl(command, command_timeout=timeout, env=env),
+            operation="execute_command",
+        )
+
+    async def _execute_command_impl(
+        self,
+        command: str,
+        *,
+        command_timeout: float,
+        env: dict[str, str] | None,
+    ) -> SandboxExecutionResult:
+        """Execute one shell command attempt without stale-runtime recovery."""
+        if self._sandbox is None:
+            await self._ensure_sandbox(self._template, timeout_budget_seconds=command_timeout)
+
+        if self._sandbox is None:
+            raise RuntimeError(SANDBOX_NOT_INITIALIZED_ERROR)
+
+        # Refresh sandbox lease before execution so the VM doesn't expire mid-run
+        await self._apply_sandbox_timeout()
+
+        try:
+            # Use asyncio.timeout context manager for cancellation (S6966)
+            async with asyncio.timeout(command_timeout):
+                execute_command = getattr(self._sandbox, "execute_command", None)
+                if callable(execute_command):
+                    result = await execute_command(command, env=env, timeout=command_timeout)
+                    return self._to_command_result(
+                        result,
+                        timeout_seconds=self._normalize_command_timeout(command_timeout),
+                        timeout_source=E2B_COMMAND_TIMEOUT_SOURCE,
+                    )
+                return await self._execute_command_via_code(command, env=env, timeout=command_timeout)
+        except TimeoutError:
+            return self._timeout_result(
+                execution_backend=E2B_COMMANDS_BACKEND,
+                timeout_source=LOCAL_ASYNCIO_TIMEOUT_SOURCE,
+                timeout_seconds=command_timeout,
+                stderr=f"Command execution exceeded local timeout of {command_timeout}s",
+            )
+
+    async def execute_python_file(
+        self,
+        *,
+        code: str,
+        entrypoint_path: str,
+        timeout: float = 300,  # NOSONAR - public API; execution uses asyncio.timeout below.
+        files: dict[str, str] | None = None,
+        env: dict[str, str] | None = None,
+        template: str | None = None,
+    ) -> SandboxExecutionResult:
+        """Upload and execute a Python entrypoint through the generic sandbox runtime."""
+        return await self._run_with_stale_runtime_recovery(
+            lambda: self._execute_python_file_impl(
+                code=code,
+                entrypoint_path=entrypoint_path,
+                execution_timeout=timeout,
+                files=files,
+                env=env,
+                template=template,
+            ),
+            operation="execute_python_file",
+        )
+
+    async def _execute_python_file_impl(
+        self,
+        *,
+        code: str,
+        entrypoint_path: str,
+        execution_timeout: float,
+        files: dict[str, str] | None,
+        env: dict[str, str] | None,
+        template: str | None,
+    ) -> SandboxExecutionResult:
+        """Execute one Python entrypoint attempt without stale-runtime recovery."""
+        if self._sandbox is None:
+            await self._ensure_sandbox(template or self._template, timeout_budget_seconds=execution_timeout)
+
+        if self._sandbox is None:
+            raise RuntimeError(SANDBOX_NOT_INITIALIZED_ERROR)
+
+        await self._apply_sandbox_timeout()
+
+        files_to_upload = dict(files or {})
+        files_to_upload[entrypoint_path] = code
+        if files_to_upload:
+            await self._upload_files(files_to_upload)
+
+        command = "python " + json.dumps(entrypoint_path)
+        try:
+            async with asyncio.timeout(execution_timeout):
+                return await self._execute_command_via_code(command, env=env, timeout=execution_timeout)
+        except TimeoutError:
+            return self._timeout_result(
+                execution_backend=E2B_COMMANDS_BACKEND,
+                timeout_source=LOCAL_ASYNCIO_TIMEOUT_SOURCE,
+                timeout_seconds=execution_timeout,
+                stderr=f"Python entrypoint execution exceeded local timeout of {execution_timeout}s",
+            )
+
+    async def _run_with_stale_runtime_recovery(
+        self,
+        attempt: Callable[[], Awaitable[SandboxExecutionResult]],
+        *,
+        operation: str,
+    ) -> SandboxExecutionResult:
+        """Run one sandbox operation and retry once after stale transport reset."""
+        try:
+            result = await attempt()
+        except Exception as exc:
+            if self._is_stale_runtime_error(exc):
+                logger.info("%s: detected stale runtime/transport (%r), resetting and retrying once", operation, exc)
+                self._reset_for_new_loop()
+                return await attempt()
+            raise
+        if self._is_stale_runtime_result(
+            stdout=result.stdout,
+            stderr=result.stderr,
+            exit_code=result.exit_code,
+            diagnostics=result.diagnostics,
+        ):
+            logger.info("%s: detected stale runtime/transport result, resetting and retrying once", operation)
+            self._reset_for_new_loop()
+            return await attempt()
+        return result
+
+    @staticmethod
+    def _normalize_e2b_timeout(execution_timeout: float) -> int:
+        timeout_seconds = float(execution_timeout)
+        if timeout_seconds <= 0:
+            return 0
+        return math.ceil(timeout_seconds)
+
+    @classmethod
+    def _normalize_command_timeout(cls, execution_timeout: float) -> int:
+        return cls._normalize_e2b_timeout(execution_timeout)
+
+    def _command_diagnostics(
+        self,
+        *,
+        timeout_seconds: float | int,
+        timeout_source: str,
+        timed_out: bool,
+    ) -> dict[str, Any]:
+        active_timeout_seconds = float(timeout_seconds) if timed_out else None
+        diagnostics = self._execution_diagnostics(
+            execution_backend=E2B_COMMANDS_BACKEND,
+            timeout_source=timeout_source if timed_out else None,
+            timeout_seconds=active_timeout_seconds,
+        )
+        diagnostics["e2b_command_timeout_seconds"] = None if timeout_seconds == 0 else float(timeout_seconds)
+        diagnostics["e2b_request_timeout_seconds"] = None
+        return diagnostics
+
+    def _to_command_result(
+        self,
+        result: Any,
+        *,
+        timeout_seconds: float | int,
+        timeout_source: str,
+    ) -> SandboxExecutionResult:
+        stderr = str(getattr(result, "stderr", "") or "")
+        error = str(getattr(result, "error", "") or "")
+        if error:
+            stderr = f"{stderr}\n{error}" if stderr else error
+
+        exit_code = getattr(result, "exit_code", None)
+        if exit_code is None:
+            exit_code = getattr(result, "returncode", 0)
+        exit_code = int(exit_code or 0)
+        timed_out = getattr(result, "status", None) == ExecutionStatus.TIMEOUT or (
+            exit_code != 0 and self._looks_like_timeout(stderr)
+        )
+        diagnostics = self._command_diagnostics(
+            timeout_seconds=timeout_seconds,
+            timeout_source=timeout_source,
+            timed_out=timed_out,
+        )
+        self._mark_stale_runtime_diagnostics(diagnostics, stderr=stderr, error_text=error, exit_code=exit_code)
+        sandbox_result = SandboxExecutionResult(
+            stdout=str(getattr(result, "stdout", "") or ""),
+            stderr=stderr,
+            exit_code=exit_code,
+            timed_out=timed_out,
+            execution_backend=E2B_COMMANDS_BACKEND,
+            timeout_source=timeout_source if timed_out else None,
+            timeout_seconds=float(timeout_seconds) if timed_out else None,
+            diagnostics=diagnostics,
+        )
+        return sandbox_result
+
+    def _timeout_result(
+        self,
+        *,
+        execution_backend: str,
+        timeout_source: str,
+        timeout_seconds: float,
+        stderr: str,
+    ) -> SandboxExecutionResult:
+        return SandboxExecutionResult(
+            stdout="",
+            stderr=stderr,
+            exit_code=1,
+            timed_out=True,
+            execution_backend=execution_backend,
+            timeout_source=timeout_source,
+            timeout_seconds=float(timeout_seconds),
+            diagnostics=self._execution_diagnostics(
+                execution_backend=execution_backend,
+                timeout_source=timeout_source,
+                timeout_seconds=float(timeout_seconds),
+            ),
+        )
+
+    def _execution_diagnostics(
+        self,
+        *,
+        execution_backend: str,
+        timeout_source: str | None = None,
+        timeout_seconds: float | None = None,
+    ) -> dict[str, Any]:
+        diagnostics: dict[str, Any] = {
+            "execution_backend": execution_backend,
+            "sandbox_timeout_seconds": float(self._sandbox_timeout),
+        }
+        if self._sandbox is not None:
+            diagnostics["sandbox_id"] = self._sandbox_identifier(self._sandbox)
+        if timeout_source is not None:
+            diagnostics["timeout_source"] = timeout_source
+        if timeout_seconds is not None:
+            diagnostics["timeout_seconds"] = float(timeout_seconds)
+        return diagnostics
+
+    @staticmethod
+    def _looks_like_timeout(text: str) -> bool:
+        lowered = text.lower()
+        return any(marker in lowered for marker in BACKEND_TIMEOUT_MARKERS)
+
+    async def cleanup(self) -> None:
+        """Destroy the sandbox and release resources."""
+        if self._sandbox is not None:
+            try:
+                logger.info("Destroying sandbox")
+                await self._sandbox.terminate()
+            except Exception as e:
+                logger.warning(f"Error destroying sandbox: {e}")
+            finally:
+                # Reset any process-wide SDK transport state bound to this event loop
+                # (no-op for backends without one). Called via the generic interface.
+                self._sandbox.reset_transport()
+                self._sandbox = None
+
+    @staticmethod
+    def _is_stale_runtime_error(error: BaseException) -> bool:
+        """Return True when *error* looks like a closed-transport or closed-loop failure.
+
+        Covers uvloop ``TCPTransport closed=True ... handler is closed``,
+        asyncio ``Event loop is closed`` / cross-loop binding errors,
+        and anyio/httpcore closed-resource markers.
+
+        Args:
+            error: The exception raised by a sandbox or transport operation.
+
+        Returns:
+            True when the error matches a known stale-transport/loop signature.
+        """
+        current: BaseException | None = error
+        seen: set[int] = set()
+        while current is not None and id(current) not in seen:
+            seen.add(id(current))
+            message = str(current).lower()
+            if any(marker in message for marker in _CLOSEABLE_TRANSPORT_ERROR_MARKERS):
+                return True
+            current = current.__cause__ or current.__context__
+        return False
+
+    @staticmethod
+    def _is_stale_runtime_result(
+        *,
+        stdout: str = "",
+        stderr: str = "",
+        exit_code: int = 0,
+        diagnostics: dict[str, Any] | None = None,
+    ) -> bool:
+        """Return True when a failed result was produced by stale transport state."""
+        _ = stdout, stderr
+        if exit_code == 0:
+            return False
+        return diagnostics is not None and diagnostics.get(STALE_RUNTIME_TRANSPORT_DIAGNOSTIC) is True
+
+    @staticmethod
+    def _looks_like_stale_runtime_output(text: str) -> bool:
+        """Return True when non-user backend error text matches stale transport output."""
+        lowered = text.lower()
+        return any(all(marker in lowered for marker in group) for group in _STALE_RUNTIME_RESULT_MARKER_GROUPS)
+
+    @staticmethod
+    def _looks_like_stale_runtime_stderr(text: str) -> bool:
+        """Return True when backend stderr matches the observed stale-loop result shape."""
+        lowered = text.lower()
+        return "asyncio.locks.event" in lowered and BOUND_TO_DIFFERENT_EVENT_LOOP_MARKER in lowered
+
+    def _sandbox_result_timeout_source(self, status: ExecutionStatus, stderr: str) -> str | None:
+        """Return the timeout source for a code-interpreter result."""
+        if status == ExecutionStatus.TIMEOUT:
+            return CODE_INTERPRETER_TIMEOUT_SOURCE
+        if self._looks_like_timeout(stderr):
+            return CODE_INTERPRETER_BACKEND_TIMEOUT_SOURCE
+        return None
+
+    def _mark_stale_runtime_diagnostics(
+        self,
+        diagnostics: dict[str, Any],
+        *,
+        error: BaseException | None = None,
+        error_text: str = "",
+        stderr: str = "",
+        exit_code: int | None = None,
+    ) -> None:
+        """Mark diagnostics when the failure looks like a stale runtime transport."""
+        if error is not None:
+            if type(error).__name__ != "CommandExitException" and self._is_stale_runtime_error(error):
+                diagnostics[STALE_RUNTIME_TRANSPORT_DIAGNOSTIC] = True
+            return
+
+        if exit_code is None or exit_code == 0:
+            return
+
+        if (error_text and self._looks_like_stale_runtime_output(error_text)) or (
+            stderr and self._looks_like_stale_runtime_stderr(stderr)
+        ):
+            diagnostics[STALE_RUNTIME_TRANSPORT_DIAGNOSTIC] = True
+
+    def _reset_for_new_loop(self) -> None:
+        """Clear loop-bound sandbox state so the next call reconnects on the current loop.
+
+        Does NOT terminate the remote sandbox — that VM may still be alive.  Only
+        the local SDK client state is discarded.  Callers must re-initialise
+        through the normal ``_create_sandbox`` path on the next operation.
+        """
+        sandbox = self._sandbox
+        self._sandbox = None
+        if sandbox is not None:
+            try:
+                # Clear any process-wide SDK transport singleton bound to the dead loop
+                # (no-op for backends without one). Called via the generic interface.
+                sandbox.reset_transport()
+            except Exception as exc:
+                logger.warning("Ignoring transport reset failure during runtime reset: %s", exc)
+        for listener in tuple(self._reset_listeners):
+            try:
+                listener()
+            except Exception as exc:
+                logger.warning("Ignoring runtime reset listener failure: %s", exc)
+
+    def _register_reset_listener(self, callback: Callable[[], None]) -> None:
+        """Register a callback that should run when loop-bound runtime state is reset."""
+        if callback not in self._reset_listeners:
+            self._reset_listeners.append(callback)
+
+    @staticmethod
+    def _sandbox_identifier(sandbox: Any) -> str:
+        """Return a best-effort sandbox identifier from the sandbox interface."""
+        return str(getattr(sandbox, "sandbox_id", None) or "unknown")
+
+    async def download_file(self, file_path: str) -> bytes | None:
+        """Download a file's bytes from the sandbox (binary-safe)."""
+        if self._sandbox is None:
+            raise RuntimeError(SANDBOX_NOT_INITIALIZED_ERROR)
+        return await self._sandbox.download_file(file_path)
+
+    @property
+    def is_active(self) -> bool:
+        """Check if a sandbox is currently active."""
+        return self._sandbox is not None
+
+    @property
+    def sandbox(self) -> CodeInterpreterSandbox | None:
+        """Return the underlying sandbox instance, if active."""
+        return self._sandbox
+
+    @property
+    def created_with_template(self) -> bool:
+        """Whether the active sandbox was created from the requested template."""
+        return self._sandbox_created_with_template
+
+    def _should_skip_default_package_install(self, template: str | None) -> bool:
+        """Determine whether to skip package installation for the default template."""
+        if not self._sandbox_created_with_template:
+            return False
+
+        if template != DEFAULT_SANDBOX_TEMPLATE:
+            return False
+
+        return self._packages == list(DEFAULT_SANDBOX_PACKAGES)
+
+    async def _create_sandbox(
+        self, template: str | None = None, *, timeout_budget_seconds: float | None = None
+    ) -> None:
+        """Create a new sandbox via the selected provider factory.
+
+        Implements canonical runtime rules:
+        - If template provided, try creating sandbox with template
+        - Transient placement failures are retried inside the execution budget
+        - Real template/configuration errors fail fast (provider-owned policy)
+        - Install packages regardless of template usage
+
+        Note: Package installation occurs after sandbox creation.
+
+        Args:
+            template: Optional template ID.
+            timeout_budget_seconds: Remaining execution budget for transient
+                placement retries. None disables budget-gating.
+        """
+        logger.info("Creating sandbox (provider=%s, template=%s)", self._provider_name, template)
+        provider = get_provider(self._provider)
+        result = await provider.create(
+            SandboxConfig(
+                template=template,
+                api_key=self._api_key,
+                domain=self._domain,
+                sandbox_timeout=self._normalize_e2b_timeout(self._sandbox_timeout),
+                auto_build_template=self._auto_build_template,
+                build_base_template=self._build_base_template,
+                packages=self._packages,
+                timeout_budget_seconds=timeout_budget_seconds,
+            )
+        )
+        self._sandbox = result.sandbox
+        self._sandbox_created_with_template = result.created_with_template
+        await self._apply_sandbox_timeout()
+        await self._post_sandbox_setup(template)
+
+    async def _ensure_sandbox(self, template: str | None, *, timeout_budget_seconds: float | None = None) -> None:
+        """Create a sandbox on demand via the configured provider factory."""
+        if self._sandbox is not None:
+            return
+        await self._create_sandbox(template, timeout_budget_seconds=timeout_budget_seconds)
+
+    async def _post_sandbox_setup(self, template: str | None) -> None:
+        """Run package-selector and package installation after sandbox creation."""
+        actual_template = template if self._sandbox_created_with_template else None
+        if self._package_selector is not None:
+            try:
+                self._packages = self._package_selector(actual_template)
+                logger.info(
+                    f"Package selector called with actual_template={actual_template}, "
+                    f"selected packages: {self._packages}"
+                )
+            except Exception as e:
+                logger.exception("Package selector failed: %s", e)
+                await self.cleanup()
+                raise
+
+        await self.configure_packages(self._packages, template=actual_template)
+
+    async def configure_packages(
+        self,
+        packages: list[str] | None,
+        *,
+        template: str | None,
+        package_install_timeout: float | None = None,
+    ) -> None:
+        """Configure and install packages in the current sandbox.
+
+        This public seam lets shared-runtime callers, including PTC adapters,
+        reuse the same package compatibility, skip, validation, and install rules
+        as runtime-owned sandbox setup.
+
+        Args:
+            packages: Packages to install. ``None`` or an empty list skips install.
+            template: Effective template used to create the sandbox, or ``None``
+                when the sandbox uses the default/fallback E2B environment.
+            package_install_timeout: Optional package install timeout override.
+                ``None`` keeps the runtime's existing timeout.
+        """
+        self._packages = packages
+        if package_install_timeout is not None:
+            self._package_install_timeout = package_install_timeout
+
+        # Validate native-tool compatibility after packages are selected
+        await self._validate_native_tool_compatibility(template)
+
+        if self._packages:
+            if self._should_skip_default_package_install(template):
+                logger.info("Skipping package install (default template already includes defaults)")
+            else:
+                await self._install_packages()
+
+    async def configure_sandbox_timeout(self, sandbox_timeout: float) -> None:
+        """Update the sandbox lease timeout used by this runtime."""
+        self._sandbox_timeout = sandbox_timeout
+        await self._apply_sandbox_timeout()
+
+    async def _validate_native_tool_compatibility(self, template: str | None) -> None:
+        """Validate that native AIP tools are only used with the compatible baseline template.
+
+        Native AIP tools require ``DEFAULT_SANDBOX_TEMPLATE``.
+
+        Args:
+            template: The template alias requested by the caller.
+
+        Raises:
+            RuntimeError: If native AIP tools are requested but the effective template
+                is fallback/default or a non-compatible alias.
+        """
+        if not self._packages:
+            return
+
+        # Check if native AIP tools package is in the selected packages
+        has_native_tools = any(pkg.startswith(("aip-agents", "aip-agents-binary")) for pkg in self._packages)
+
+        if has_native_tools and not self._sandbox_created_with_template:
+            error_msg = (
+                f"Native AIP tools require a compatible sandbox template "
+                f"('{DEFAULT_SANDBOX_TEMPLATE}'), but sandbox fell back to the default "
+                f"E2B template which uses an incompatible Python version. "
+                f"Ensure the template '{DEFAULT_SANDBOX_TEMPLATE}' is built and available, "
+                f"or disable native tools."
+            )
+            logger.error(f"ptc_native_runtime_incompatible: template_fallback=True, requested_template={template}")
+            await self.cleanup()
+            raise RuntimeError(error_msg)
+
+        if has_native_tools and template is not None and template != DEFAULT_SANDBOX_TEMPLATE:
+            error_msg = (
+                f"Native AIP tools require template '{DEFAULT_SANDBOX_TEMPLATE}', "
+                f"but received template '{template}'. "
+                f"Use template='{DEFAULT_SANDBOX_TEMPLATE}' or omit template to use the default."
+            )
+            logger.error(
+                f"ptc_native_runtime_incompatible: template_alias={template}, expected_alias={DEFAULT_SANDBOX_TEMPLATE}"
+            )
+            await self.cleanup()
+            raise RuntimeError(error_msg)
+
+    async def _install_packages(self) -> None:
+        """Install packages in the sandbox."""
+        if self._sandbox is None:
+            raise RuntimeError(SANDBOX_NOT_INITIALIZED_ERROR)
+
+        packages = self._packages
+        if packages is None or not packages:
+            return
+
+        # Validate all packages before constructing command
+        validate_package_names(packages)
+
+        # Note: packages_str is safe because packages is a controlled list from
+        # configuration, not user input.
+        packages_str = " ".join(packages)
+        logger.info(f"Installing packages in sandbox: {packages_str}")
+
+        try:
+            command = f"pip install -q {packages_str}"
+            timeout = self._package_install_timeout if self._package_install_timeout > 0 else 0
+            execute_command = getattr(self._sandbox, "execute_command", None)
+            if callable(execute_command):
+                result = await execute_command(command, timeout=timeout)
+            else:
+                result = await self._execute_command_via_code(command, env=None, timeout=timeout)
+        except Exception as e:
+            logger.exception("Error installing packages: %s", e)
+            raise
+
+        if result.exit_code != 0:
+            logger.error(f"Failed to install packages: {result.stderr}")
+            raise RuntimeError(f"Failed to install PTC packages: {result.stderr}")
+
+        logger.info("Packages installed successfully")
+
+    # Backward compatibility alias
+    _install_ptc_packages = _install_packages
+
+    async def _upload_files(self, files: dict[str, str]) -> None:
+        """Upload files to the sandbox working directory via the generic code API.
+
+        Args:
+            files: Mapping of path -> content.
+        """
+        if self._sandbox is None:
+            raise RuntimeError(SANDBOX_NOT_INITIALIZED_ERROR)
+
+        attachments = [self._to_attachment(path, content) for path, content in files.items()]
+        logger.debug("Uploading %s file(s) to sandbox", len(attachments))
+        paths_literal = json.dumps(list(files.keys()))
+        verify_code = (
+            "import json, os\n"
+            f"missing = [p for p in json.loads({paths_literal!r}) if not os.path.exists(p)]\n"
+            "print('\\n'.join(missing))\n"
+            "if missing:\n"
+            "    raise RuntimeError('sandbox upload verification failed')\n"
+        )
+        result = await self._sandbox.execute_code(verify_code, files=attachments, upload_dir="")
+        if result.exit_code != 0:
+            missing = (result.stdout or "").strip() or "unknown"
+            raise RuntimeError(f"Sandbox file upload verification failed; missing after upload: {missing}")
+
+    @staticmethod
+    def _to_attachment(path: str, content: str) -> Attachment:
+        """Build an ``Attachment`` for *path*/*content* (mime/extension are unused by upload)."""
+        return Attachment(
+            filename=path,
+            data=content.encode("utf-8"),
+            mime_type="text/plain",
+            extension=Path(path).suffix.lstrip("."),
+            metadata={},
+        )
+
+    async def _apply_sandbox_timeout(self) -> None:
+        """Apply the configured sandbox session timeout.
+
+        Lease refresh is best-effort: it no-ops for a sandbox without
+        ``set_timeout`` and delegates underlying-SDK error swallowing to the
+        sandbox's ``set_timeout`` (logs a warning, never raises).
+        """
+        if self._sandbox is None:
+            return
+        set_timeout = getattr(self._sandbox, "set_timeout", None)
+        if set_timeout is None:
+            return
+        await set_timeout(self._normalize_e2b_timeout(self._sandbox_timeout))
+
+    async def _run_code(
+        self,
+        code: str,
+        env: dict[str, str] | None = None,
+        timeout: float = 300,  # NOSONAR - forwarded to E2B SDK execute_code; not an async cancellation timeout
+    ) -> SandboxExecutionResult:
+        """Run code in the sandbox and map the result.
+
+        Delegates to the sandbox's ``execute_code`` (which captures stdout/stderr and
+        the formatted error and never raises for execution failures), then maps
+        the returned ``ExecutionResult`` to ``SandboxExecutionResult``.
+
+        Args:
+            code: Code to execute.
+            env: Environment variables.
+            timeout: Execution timeout in seconds, forwarded to the sandbox.
+
+        Returns:
+            SandboxExecutionResult with execution output.
+        """
+        if self._sandbox is None:
+            raise RuntimeError(SANDBOX_NOT_INITIALIZED_ERROR)
+
+        result = await self._sandbox.execute_code(code, timeout=max(1, int(timeout)), env=env)
+        return self._to_sandbox_result(result, timeout_seconds=timeout)
+
+    async def _execute_command_via_code(
+        self,
+        command: str,
+        *,
+        env: dict[str, str] | None,
+        timeout: float,
+    ) -> SandboxExecutionResult:
+        """Execute a shell command through ``execute_code`` for newer E2B wrappers."""
+        if self._sandbox is None:
+            raise RuntimeError(SANDBOX_NOT_INITIALIZED_ERROR)
+
+        env_literal = json.dumps(env or {})
+        command_literal = json.dumps(command)
+        code = f"""
+import json
+import os
+import subprocess
+import sys
+
+env = os.environ.copy()
+env.update(json.loads({env_literal!r}))
+completed = subprocess.run(
+    {command_literal},
+    shell=True,
+    text=True,
+    capture_output=True,
+    timeout={float(timeout)!r},
+    env=env,
+)
+sys.stdout.write(completed.stdout)
+sys.stderr.write(completed.stderr)
+if completed.returncode:
+    raise SystemExit(completed.returncode)
+"""
+        result = await self._run_code(code, timeout=timeout)
+        result.timeout_source = result.timeout_source or (
+            CODE_INTERPRETER_BACKEND_TIMEOUT_SOURCE if result.timed_out else None
+        )
+        if result.timed_out and result.timeout_seconds is None:
+            result.timeout_seconds = float(timeout)
+        if result.diagnostics:
+            result.diagnostics.setdefault("command_fallback", "execute_code_subprocess")
+        return result
+
+    def _to_sandbox_result(
+        self,
+        result: ExecutionResult,
+        *,
+        timeout_seconds: float | None = None,
+    ) -> SandboxExecutionResult:
+        """Map a gllm-tools ``ExecutionResult`` to ``SandboxExecutionResult``.
+
+        The formatted error (traceback + ``name: value``) is appended to stderr so
+        callers that surface stderr to the model keep seeing the full traceback.
+        """
+        stderr = result.stderr or ""
+        if result.error:
+            stderr = f"{stderr}\n{result.error}" if stderr else result.error
+        timeout_source = self._sandbox_result_timeout_source(result.status, stderr)
+        timed_out = timeout_source is not None
+        diagnostics = self._execution_diagnostics(
+            execution_backend=E2B_CODE_INTERPRETER_BACKEND,
+            timeout_source=timeout_source,
+            timeout_seconds=float(timeout_seconds) if timed_out and timeout_seconds is not None else None,
+        )
+        self._mark_stale_runtime_diagnostics(
+            diagnostics,
+            error_text=result.error or "",
+            stderr=result.stderr or "",
+            exit_code=result.exit_code,
+        )
+        return SandboxExecutionResult(
+            stdout=result.stdout or "",
+            stderr=stderr,
+            exit_code=result.exit_code,
+            timed_out=timed_out,
+            execution_backend=E2B_CODE_INTERPRETER_BACKEND,
+            timeout_source=timeout_source,
+            timeout_seconds=float(timeout_seconds) if timed_out and timeout_seconds is not None else None,
+            diagnostics=diagnostics,
+        )