Skip to content

Secure, Fast, and Extensible Sandbox runtime for AI agents.

13.7 KB
Raw Blame
#
# Copyright 2025 The OpenSandbox Authors
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
"""
Synchronous command adapter implementation (including SSE streaming).
"""

import logging
from datetime import timedelta

import httpx

from opensandbox._httpx import build_redirect_client_options
from opensandbox.adapters.converter.command_execution import (
    build_run_command_request_body as _build_run_command_request_body,
)
from opensandbox.adapters.converter.command_execution import (
    build_run_in_session_request_body as _build_run_in_session_request_body,
)
from opensandbox.adapters.converter.command_execution import (
    decode_sse_event_data as _decode_sse_event_data,
)
from opensandbox.adapters.converter.command_execution import (
    infer_foreground_exit_code as _infer_foreground_exit_code,
)
from opensandbox.adapters.converter.command_execution import (
    resolve_run_in_session_timeout as _resolve_run_in_session_timeout,
)
from opensandbox.adapters.converter.env_entry import (
    build_set_env_command,
    raise_for_set_env_failure,
)
from opensandbox.adapters.converter.exception_converter import (
    ExceptionConverter,
)
from opensandbox.adapters.converter.response_handler import (
    build_api_exception_from_httpx,
    handle_api_error,
)
from opensandbox.adapters.sse import iter_sse_events
from opensandbox.config.connection_sync import ConnectionConfigSync
from opensandbox.exceptions import InvalidArgumentException
from opensandbox.models.execd import (
    CommandLogs,
    CommandStatus,
    Execution,
    RunCommandOpts,
)
from opensandbox.models.execd_sync import ExecutionHandlersSync
from opensandbox.models.sandboxes import SandboxEndpoint
from opensandbox.sync.adapters.converter.execution_event_dispatcher import (
    ExecutionEventDispatcherSync,
)
from opensandbox.sync.services.command import CommandsSync
from opensandbox.transport import sse_timeout, streaming_transport

logger = logging.getLogger(__name__)


class CommandsAdapterSync(CommandsSync):
    """
    Synchronous implementation of :class:`~opensandbox.sync.services.command.CommandsSync`.

    This adapter wraps openapi-python-client generated clients for simple operations and
    uses direct ``httpx`` streaming for SSE (Server-Sent Events) command execution output.
    """

    RUN_COMMAND_PATH = "/command"
    SESSION_PATH = "/session"
    RUN_IN_SESSION_PATH = "/session/{session_id}/run"

    def __init__(
        self, connection_config: ConnectionConfigSync, execd_endpoint: SandboxEndpoint
    ) -> None:
        """
        Initialize the command adapter (sync).

        Args:
            connection_config: Connection configuration (shared transport, headers, timeouts)
            execd_endpoint: Endpoint for execd service
        """
        self.connection_config = connection_config
        self.execd_endpoint = execd_endpoint

        from opensandbox.api.execd import Client

        base_url = f"{self.connection_config.protocol}://{self.execd_endpoint.endpoint}"
        timeout_seconds = self.connection_config.request_timeout.total_seconds()
        timeout = httpx.Timeout(timeout_seconds)

        headers = self.execd_endpoint.build_request_headers(self.connection_config)

        self._client = Client(
            base_url=base_url,
            timeout=timeout,
            follow_redirects=self.connection_config.follow_redirects,
        )

        self._httpx_client = httpx.Client(
            base_url=base_url,
            headers=headers,
            timeout=timeout,
            transport=self.connection_config.transport,
            **build_redirect_client_options(self.connection_config, base_url),
        )
        self._client.set_httpx_client(self._httpx_client)

        # SSE client: read timeout bounds the wait for response headers and the gap
        # between stream bytes (see sse_timeout); endpoint headers already in headers
        sse_headers = {
            **headers,
            "Accept": "text/event-stream",
            "Cache-Control": "no-cache",
        }
        # SSE bootstraps keep only the wake-timeout retry: a non-idempotent
        # status opt-in would cause duplicate execution on a resent SSE POST.
        self._sse_client = httpx.Client(
            headers=sse_headers,
            timeout=sse_timeout(timeout_seconds),
            transport=streaming_transport(self.connection_config.transport),
            **build_redirect_client_options(self.connection_config, base_url),
        )

    def _get_execd_url(self, path: str) -> str:
        """Build URL for execd endpoint."""
        return (
            f"{self.connection_config.protocol}://{self.execd_endpoint.endpoint}{path}"
        )

    def _execute_streaming_request(
        self,
        *,
        url: str,
        json_body: dict,
        handlers: ExecutionHandlersSync | None,
        infer_exit_code: bool,
        failure_message: str,
        is_background: bool = False,
    ) -> Execution:
        execution = Execution(id=None, execution_count=None, result=[], error=None)
        dispatcher = ExecutionEventDispatcherSync(execution, handlers)

        with self._sse_client.stream("POST", url, json=json_body) as response:
            if response.status_code != 200:
                response.read()
                raise build_api_exception_from_httpx(response, failure_message)

            for event in iter_sse_events(response):
                event_node = _decode_sse_event_data(event.data)
                if event_node is None:
                    continue
                dispatcher.dispatch(event_node)
                # Foreground responses drain to EOF (no break below): older
                # servers may emit trailing output after the completion event.
                if is_background and event_node.type == "execution_complete":
                    # Background commands are done once execution_complete
                    # arrives; do not wait for the chunked terminator, which
                    # older execd versions delay with a grace-period sleep and can
                    # be lost if the connection is closed early (#1528).
                    break

        if infer_exit_code:
            execution.exit_code = _infer_foreground_exit_code(execution)

        return execution

    def run(
        self,
        command: str | list[str],
        *,
        opts: RunCommandOpts | None = None,
        handlers: ExecutionHandlersSync | None = None,
    ) -> Execution:
        if isinstance(command, str) and not command.strip():
            raise InvalidArgumentException("Command cannot be empty")

        try:
            opts = opts or RunCommandOpts()
            json_body = _build_run_command_request_body(command, opts).to_dict()
            url = self._get_execd_url(self.RUN_COMMAND_PATH)
            return self._execute_streaming_request(
                url=url,
                json_body=json_body,
                handlers=handlers,
                infer_exit_code=not opts.background,
                failure_message="Failed to run command",
                is_background=opts.background,
            )

        except Exception as e:
            logger.error("Failed to run command", exc_info=e)
            raise ExceptionConverter.to_sandbox_exception(e) from e

    def set_env(self, key: str, value: str) -> None:
        """Persist an environment variable for future commands and sessions."""
        command = build_set_env_command(key, value)
        try:
            execution = self.run(command)
        except Exception as e:
            logger.error("Failed to run command", exc_info=e)
            raise ExceptionConverter.to_sandbox_exception(e) from e
        raise_for_set_env_failure(key, execution)

    def interrupt(self, execution_id: str) -> None:
        """
        Interrupt a running command execution.

        Args:
            execution_id: Execution id returned by execd for the running command
        """
        try:
            from opensandbox.api.execd.api.command import interrupt_command

            response_obj = interrupt_command.sync_detailed(
                client=self._client, id=execution_id
            )
            handle_api_error(response_obj, "Interrupt command")
        except Exception as e:
            logger.error("Failed to interrupt command", exc_info=e)
            raise ExceptionConverter.to_sandbox_exception(e) from e

    def get_command_status(self, execution_id: str) -> CommandStatus:
        """Get the current running status for a command."""
        try:
            from opensandbox.adapters.converter.command_model_converter import (
                to_command_status,
            )
            from opensandbox.adapters.converter.response_handler import require_parsed
            from opensandbox.api.execd.api.command import get_command_status
            from opensandbox.api.execd.models import CommandStatusResponse

            response_obj = get_command_status.sync_detailed(
                client=self._client,
                id=execution_id,
            )
            handle_api_error(response_obj, "Get command status")
            parsed = require_parsed(
                response_obj, CommandStatusResponse, "Get command status"
            )
            return to_command_status(parsed)
        except Exception as e:
            logger.error("Failed to get command status", exc_info=e)
            raise ExceptionConverter.to_sandbox_exception(e) from e

    def get_background_command_logs(
        self, execution_id: str, cursor: int | None = None
    ) -> CommandLogs:
        """Get background command logs (non-streamed)."""
        try:
            from opensandbox.adapters.converter.response_handler import require_parsed
            from opensandbox.api.execd.api.command import get_background_command_logs
            from opensandbox.api.execd.types import UNSET

            response_obj = get_background_command_logs.sync_detailed(
                client=self._client,
                id=execution_id,
                cursor=cursor if cursor is not None else UNSET,
            )
            handle_api_error(response_obj, "Get command logs")
            content = require_parsed(response_obj, str, "Get command logs")
            cursor_header = response_obj.headers.get("EXECD-COMMANDS-TAIL-CURSOR")
            next_cursor = None
            if cursor_header:
                try:
                    next_cursor = int(cursor_header)
                except ValueError:
                    next_cursor = None
            return CommandLogs(content=content, cursor=next_cursor)
        except Exception as e:
            logger.error("Failed to get command logs", exc_info=e)
            raise ExceptionConverter.to_sandbox_exception(e) from e

    def create_session(self, *, working_directory: str | None = None) -> str:
        from opensandbox.adapters.converter.response_handler import require_parsed
        from opensandbox.api.execd.api.command import create_session
        from opensandbox.api.execd.models.create_session_request import (
            CreateSessionRequest,
        )
        from opensandbox.api.execd.models.create_session_response import (
            CreateSessionResponse,
        )
        from opensandbox.api.execd.types import UNSET

        body = (
            CreateSessionRequest(cwd=working_directory) if working_directory else UNSET
        )
        try:
            response_obj = create_session.sync_detailed(client=self._client, body=body)
            handle_api_error(response_obj, "create_session")
            parsed = require_parsed(
                response_obj, CreateSessionResponse, "create_session"
            )
            return parsed.session_id
        except Exception as e:
            raise ExceptionConverter.to_sandbox_exception(e) from e

    def run_in_session(
        self,
        session_id: str,
        command: str,
        *,
        working_directory: str | None = None,
        timeout: timedelta | None = None,
        handlers: ExecutionHandlersSync | None = None,
    ) -> Execution:
        if not (session_id and session_id.strip()):
            raise InvalidArgumentException("session_id cannot be empty")
        if not (command and command.strip()):
            raise InvalidArgumentException("command cannot be empty")

        timeout_ms = _resolve_run_in_session_timeout(timeout)
        body = _build_run_in_session_request_body(
            command, working_directory, timeout_ms
        )
        url = self._get_execd_url(
            self.RUN_IN_SESSION_PATH.format(session_id=session_id)
        )
        try:
            return self._execute_streaming_request(
                url=url,
                json_body=body.to_dict(),
                handlers=handlers,
                infer_exit_code=True,
                failure_message="run_in_session failed",
            )
        except Exception as e:
            raise ExceptionConverter.to_sandbox_exception(e) from e

    def delete_session(self, session_id: str) -> None:
        if not (session_id and session_id.strip()):
            raise InvalidArgumentException("session_id cannot be empty")
        from opensandbox.api.execd.api.command import delete_session

        try:
            response_obj = delete_session.sync_detailed(
                client=self._client, session_id=session_id
            )
            handle_api_error(response_obj, "delete_session")
        except Exception as e:
            raise ExceptionConverter.to_sandbox_exception(e) from e