hopx-ai 0.1.15__py3-none-any.whl

hopx_ai/_async_agent_client.py

@@ -0,0 +1,223 @@
+"""Async HTTP client for agent operations with retry logic."""
+
+import asyncio
+import logging
+from typing import Optional, Dict, Any
+import httpx
+from .errors import (
+    FileNotFoundError,
+    FileOperationError,
+    CodeExecutionError,
+    CommandExecutionError,
+    DesktopNotAvailableError,
+    AgentError,
+    NetworkError,
+    TimeoutError as HopxTimeoutError,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class AsyncAgentHTTPClient:
+    """
+    Async HTTP client for agent operations with retry logic and error handling.
+    
+    Features:
+    - Connection pooling (reuses TCP connections)
+    - Automatic retries with exponential backoff
+    - Proper error wrapping to HOPX exceptions
+    - Configurable timeouts
+    """
+    
+    def __init__(
+        self,
+        agent_url: str,
+        *,
+        jwt_token: Optional[str] = None,
+        timeout: int = 30,
+        max_retries: int = 3,
+        token_refresh_callback: Optional[callable] = None,
+    ):
+        """
+        Initialize async agent HTTP client.
+        
+        Args:
+            agent_url: Agent base URL (e.g., https://7777-{id}.domain)
+            jwt_token: JWT token for agent authentication
+            timeout: Default timeout in seconds
+            max_retries: Maximum retry attempts
+            token_refresh_callback: Async callback to refresh token on 401
+        """
+        self._agent_url = agent_url.rstrip('/')
+        self._jwt_token = jwt_token
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._token_refresh_callback = token_refresh_callback
+        
+        # Build headers
+        headers = {}
+        if self._jwt_token:
+            headers['Authorization'] = f'Bearer {self._jwt_token}'
+        
+        # Create reusable async HTTP client with connection pooling
+        self._client = httpx.AsyncClient(
+            timeout=httpx.Timeout(timeout),
+            limits=httpx.Limits(max_connections=10, max_keepalive_connections=5),
+            headers=headers,
+            transport=httpx.AsyncHTTPTransport(
+                local_address="0.0.0.0",  # Force IPv4
+            )
+        )
+        
+        logger.debug(f"Async agent client initialized: {self._agent_url}")
+    
+    async def close(self) -> None:
+        """Close the HTTP client."""
+        await self._client.aclose()
+    
+    def update_jwt_token(self, token: str) -> None:
+        """Update JWT token for agent authentication."""
+        self._jwt_token = token
+        self._client.headers['Authorization'] = f'Bearer {token}'
+    
+    def _should_retry(self, status_code: int) -> bool:
+        """Check if request should be retried."""
+        return status_code in {429, 500, 502, 503, 504}
+    
+    def _get_retry_delay(self, attempt: int) -> float:
+        """Calculate retry delay with exponential backoff."""
+        return min(2 ** attempt, 10)  # Max 10 seconds
+    
+    def _wrap_error(
+        self,
+        error: Exception,
+        operation: str,
+        context: Optional[Dict[str, Any]] = None
+    ) -> AgentError:
+        """Wrap httpx errors into HOPX exceptions."""
+        context = context or {}
+        
+        if isinstance(error, httpx.HTTPStatusError):
+            status_code = error.response.status_code
+            
+            try:
+                error_data = error.response.json()
+                error_code = error_data.get('code', '').upper()
+                error_message = error_data.get('message', str(error))
+            except:
+                error_code = None
+                error_message = str(error)
+            
+            # Map error codes to specific exceptions
+            if error_code == 'FILE_NOT_FOUND':
+                return FileNotFoundError(
+                    error_message,
+                    path=context.get('path'),
+                    code='file_not_found'
+                )
+            elif error_code in ('PATH_NOT_ALLOWED', 'PERMISSION_DENIED'):
+                return FileOperationError(
+                    error_message,
+                    path=context.get('path'),
+                    operation=operation,
+                    code='file_operation_failed'
+                )
+            elif error_code in ('EXECUTION_FAILED', 'EXECUTION_TIMEOUT', 'INVALID_TOKEN'):
+                return CodeExecutionError(
+                    error_message,
+                    exit_code=error_data.get('exit_code'),
+                    code='execution_failed'
+                )
+            elif error_code == 'COMMAND_FAILED':
+                return CommandExecutionError(
+                    error_message,
+                    exit_code=error_data.get('exit_code'),
+                    command=context.get('command'),
+                    code='command_failed'
+                )
+            elif error_code == 'DESKTOP_NOT_AVAILABLE':
+                return DesktopNotAvailableError(
+                    error_message,
+                    missing_dependencies=error_data.get('missing_dependencies', []),
+                    code='desktop_not_available'
+                )
+        
+        elif isinstance(error, httpx.TimeoutException):
+            return HopxTimeoutError(f"{operation} timed out after {self._timeout}s")
+        elif isinstance(error, httpx.NetworkError):
+            return NetworkError(f"{operation} failed: {error}")
+        
+        return AgentError(f"{operation} failed: {error}")
+    
+    async def _request(
+        self,
+        method: str,
+        endpoint: str,
+        operation: str = "request",
+        context: Optional[Dict[str, Any]] = None,
+        **kwargs
+    ) -> Dict[str, Any]:
+        """Make HTTP request with retry logic."""
+        url = f"{self._agent_url}{endpoint}"
+        
+        for attempt in range(self._max_retries):
+            try:
+                response = await self._client.request(method, url, **kwargs)
+                response.raise_for_status()
+                
+                # Handle empty responses (204 No Content)
+                if response.status_code == 204 or not response.content:
+                    return {}
+                
+                if response.headers.get('content-type', '').startswith('application/json'):
+                    return response.json()
+                return {"content": response.content}
+                
+            except httpx.HTTPStatusError as e:
+                # Handle 401 Unauthorized - try to refresh token
+                if e.response.status_code == 401 and self._token_refresh_callback and attempt == 0:
+                    logger.info(f"{operation} got 401 Unauthorized, attempting token refresh...")
+                    try:
+                        # Call async refresh callback to get new token
+                        new_token = await self._token_refresh_callback()
+                        if new_token:
+                            # Update token and retry request
+                            self.update_jwt_token(new_token)
+                            logger.info(f"{operation} token refreshed, retrying request...")
+                            continue
+                    except Exception as refresh_error:
+                        logger.error(f"Token refresh failed: {refresh_error}")
+                        # Fall through to raise original error
+                
+                if not self._should_retry(e.response.status_code) or attempt == self._max_retries - 1:
+                    raise self._wrap_error(e, operation, context)
+                
+                await asyncio.sleep(self._get_retry_delay(attempt))
+                
+            except (httpx.TimeoutException, httpx.NetworkError) as e:
+                if attempt == self._max_retries - 1:
+                    raise self._wrap_error(e, operation, context)
+                
+                await asyncio.sleep(self._get_retry_delay(attempt))
+        
+        raise AgentError(f"{operation} failed after {self._max_retries} retries")
+    
+    async def get(self, endpoint: str, operation: str = "GET request", context: Optional[Dict[str, Any]] = None, **kwargs) -> Dict[str, Any]:
+        """Make GET request."""
+        return await self._request("GET", endpoint, operation=operation, context=context, **kwargs)
+    
+    async def post(self, endpoint: str, operation: str = "POST request", context: Optional[Dict[str, Any]] = None, **kwargs) -> Dict[str, Any]:
+        """Make POST request."""
+        return await self._request("POST", endpoint, operation=operation, context=context, **kwargs)
+    
+    async def put(self, endpoint: str, operation: str = "PUT request", context: Optional[Dict[str, Any]] = None, **kwargs) -> Dict[str, Any]:
+        """Make PUT request."""
+        return await self._request("PUT", endpoint, operation=operation, context=context, **kwargs)
+    
+    async def delete(self, endpoint: str, operation: str = "DELETE request", context: Optional[Dict[str, Any]] = None, **kwargs) -> Dict[str, Any]:
+        """Make DELETE request."""
+        return await self._request("DELETE", endpoint, operation=operation, context=context, **kwargs)
+    
+    async def patch(self, endpoint: str, operation: str = "PATCH request", context: Optional[Dict[str, Any]] = None, **kwargs) -> Dict[str, Any]:
+        """Make PATCH request."""
+        return await self._request("PATCH", endpoint, operation=operation, context=context, **kwargs)

hopx_ai/_async_cache.py

@@ -0,0 +1,38 @@
+"""Async cache operations for sandboxes."""
+
+from typing import Dict, Any
+import logging
+from ._async_agent_client import AsyncAgentHTTPClient
+
+logger = logging.getLogger(__name__)
+
+
+class AsyncCache:
+    """Async cache operations."""
+    
+    def __init__(self, sandbox):
+        """Initialize with sandbox reference."""
+        self._sandbox = sandbox
+        logger.debug("AsyncCache initialized")
+    
+    async def _get_client(self) -> AsyncAgentHTTPClient:
+        """Get agent client from sandbox."""
+        await self._sandbox._ensure_agent_client()
+        return self._sandbox._agent_client
+    
+    async def stats(self) -> Dict[str, Any]:
+        """Get cache statistics."""
+        client = await self._get_client()
+        response = await client.get(
+            "/cache/stats",
+            operation="get cache stats"
+        )
+        return response
+    
+    async def clear(self) -> None:
+        """Clear cache."""
+        client = await self._get_client()
+        await client.post(
+            "/cache/clear",
+            operation="clear cache"
+        )

hopx_ai/_async_client.py

@@ -0,0 +1,230 @@
+"""Async HTTP client with retry logic."""
+
+import os
+import asyncio
+import logging
+from typing import Optional, Dict, Any
+import httpx
+from .errors import (
+    APIError,
+    AuthenticationError,
+    NotFoundError,
+    ValidationError,
+    RateLimitError,
+    ResourceLimitError,
+    ServerError,
+    NetworkError,
+    TimeoutError,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class AsyncHTTPClient:
+    """Async HTTP client with automatic retries and error handling."""
+    
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: str = "https://api.hopx.dev",
+        timeout: int = 60,
+        max_retries: int = 3,
+    ):
+        # API key priority: param > env var > error
+        self.api_key = api_key or os.environ.get("HOPX_API_KEY")
+        if not self.api_key:
+            raise ValueError(
+                "API key required. Pass api_key parameter or set HOPX_API_KEY environment variable.\n"
+                "Get your API key at: https://hopx.ai"
+            )
+        
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        
+        # Force IPv4 to avoid IPv6 timeout issues (270s delay)
+        self._client = httpx.AsyncClient(
+            base_url=self.base_url,
+            timeout=timeout,
+            headers=self._default_headers(),
+            transport=httpx.AsyncHTTPTransport(
+                local_address="0.0.0.0",  # Force IPv4
+                retries=0  # We handle retries ourselves
+            ),
+        )
+    
+    def _default_headers(self) -> Dict[str, str]:
+        """Get default headers for all requests."""
+        return {
+            "X-API-Key": self.api_key,
+            "Content-Type": "application/json",
+            "User-Agent": "bunnyshell-python/0.1.0",
+        }
+    
+    def _should_retry(self, status_code: int, attempt: int) -> bool:
+        """Determine if request should be retried."""
+        if attempt >= self.max_retries:
+            return False
+        
+        # Retry on server errors and rate limits
+        return status_code in (429, 500, 502, 503, 504)
+    
+    def _get_retry_delay(self, attempt: int, retry_after: Optional[int] = None) -> float:
+        """Calculate retry delay with exponential backoff."""
+        if retry_after:
+            return float(retry_after)
+        
+        # Exponential backoff: 1s, 2s, 4s, 8s...
+        return min(2 ** attempt, 60)
+    
+    def _handle_error(self, response: httpx.Response) -> None:
+        """Convert HTTP errors to appropriate exceptions."""
+        try:
+            error_data = response.json().get("error", {})
+            message = error_data.get("message", response.text)
+            code = error_data.get("code")
+            request_id = error_data.get("request_id")
+            details = error_data.get("details", {})
+        except Exception:
+            message = response.text or f"HTTP {response.status_code}"
+            code = None
+            request_id = response.headers.get("X-Request-ID")
+            details = {}
+        
+        kwargs = {
+            "code": code,
+            "request_id": request_id,
+            "details": details,
+            "status_code": response.status_code,
+        }
+        
+        if response.status_code == 401:
+            raise AuthenticationError(message, **kwargs)
+        elif response.status_code == 404:
+            raise NotFoundError(message, **kwargs)
+        elif response.status_code == 400:
+            raise ValidationError(message, **kwargs)
+        elif response.status_code == 429:
+            retry_after = details.get("retry_after_seconds")
+            raise RateLimitError(message, retry_after=retry_after, **kwargs)
+        elif response.status_code == 403 and "limit" in message.lower():
+            raise ResourceLimitError(
+                message,
+                limit=details.get("limit"),
+                current=details.get("current"),
+                available=details.get("available"),
+                upgrade_url=details.get("upgrade_url"),
+                **kwargs
+            )
+        elif response.status_code >= 500:
+            raise ServerError(message, **kwargs)
+        else:
+            raise APIError(message, **kwargs)
+    
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Dict[str, Any]] = None,
+        json: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """
+        Make an async HTTP request with automatic retries.
+        
+        Args:
+            method: HTTP method (GET, POST, DELETE, etc.)
+            path: API endpoint path (without base URL)
+            params: Query parameters
+            json: JSON request body
+        
+        Returns:
+            Response JSON data
+        
+        Raises:
+            HopxError: On API errors
+            NetworkError: On network errors
+            TimeoutError: On timeout
+        """
+        url = f"{self.base_url}/{path.lstrip('/')}"
+        
+        # Debug logging
+        logger.debug(f"{method} {url}")
+        if json:
+            logger.debug(f"Request body: {json}")
+        if params:
+            logger.debug(f"Query params: {params}")
+        
+        for attempt in range(self.max_retries + 1):
+            try:
+                import time
+                start_time = time.time()
+                
+                response = await self._client.request(
+                    method=method,
+                    url=url,
+                    params=params,
+                    json=json,
+                )
+                
+                elapsed = time.time() - start_time
+                logger.debug(f"Response: {response.status_code} ({elapsed:.3f}s)")
+                
+                # Success
+                if response.status_code < 400:
+                    result = response.json()
+                    if logger.isEnabledFor(logging.DEBUG):
+                        logger.debug(f"Response body: {result}")
+                    return result
+                
+                # Should we retry?
+                if self._should_retry(response.status_code, attempt):
+                    retry_after = None
+                    if response.status_code == 429:
+                        try:
+                            retry_after = response.json().get("error", {}).get("details", {}).get("retry_after_seconds")
+                        except Exception:
+                            pass
+                    
+                    delay = self._get_retry_delay(attempt, retry_after)
+                    logger.debug(f"Retrying in {delay}s (attempt {attempt + 1}/{self.max_retries})")
+                    await asyncio.sleep(delay)
+                    continue
+                
+                # Error - no retry
+                self._handle_error(response)
+            
+            except httpx.TimeoutException as e:
+                if attempt < self.max_retries:
+                    delay = self._get_retry_delay(attempt)
+                    logger.debug(f"Timeout, retrying in {delay}s")
+                    await asyncio.sleep(delay)
+                    continue
+                raise TimeoutError(f"Request timed out after {self.timeout}s") from e
+            
+            except httpx.NetworkError as e:
+                if attempt < self.max_retries:
+                    delay = self._get_retry_delay(attempt)
+                    logger.debug(f"Network error, retrying in {delay}s")
+                    await asyncio.sleep(delay)
+                    continue
+                raise NetworkError(f"Network error: {e}") from e
+        
+        raise ServerError("Max retries exceeded")
+    
+    async def get(self, path: str, **kwargs) -> Dict[str, Any]:
+        """GET request."""
+        return await self.request("GET", path, **kwargs)
+    
+    async def post(self, path: str, **kwargs) -> Dict[str, Any]:
+        """POST request."""
+        return await self.request("POST", path, **kwargs)
+    
+    async def delete(self, path: str, **kwargs) -> Dict[str, Any]:
+        """DELETE request."""
+        return await self.request("DELETE", path, **kwargs)
+    
+    async def close(self) -> None:
+        """Close the HTTP client."""
+        await self._client.aclose()
+

hopx_ai/_async_commands.py

@@ -0,0 +1,58 @@
+"""Async command execution for sandboxes."""
+
+from typing import Optional, Dict, Any
+import logging
+from ._async_agent_client import AsyncAgentHTTPClient
+from .models import ExecutionResult
+
+logger = logging.getLogger(__name__)
+
+
+class AsyncCommands:
+    """Async command execution for sandboxes."""
+    
+    def __init__(self, sandbox):
+        """Initialize with sandbox reference."""
+        self._sandbox = sandbox
+        logger.debug("AsyncCommands initialized")
+    
+    async def _get_client(self) -> AsyncAgentHTTPClient:
+        """Get agent client from sandbox."""
+        await self._sandbox._ensure_agent_client()
+        return self._sandbox._agent_client
+    
+    async def run(
+        self,
+        command: str,
+        *,
+        timeout_seconds: int = 60,
+        env: Optional[Dict[str, str]] = None,
+        working_dir: str = "/workspace"
+    ) -> ExecutionResult:
+        """Run shell command."""
+        client = await self._get_client()
+        
+        payload = {
+            "command": command,
+            "timeout": timeout_seconds,
+            "working_dir": working_dir
+        }
+        
+        if env:
+            payload["env"] = env
+        
+        response = await client.post(
+            "/commands/run",
+            json=payload,
+            operation="run command",
+            context={"command": command}
+        )
+        
+        return ExecutionResult(
+            success=response.get("success", True),
+            stdout=response.get("stdout", ""),
+            stderr=response.get("stderr", ""),
+            exit_code=response.get("exit_code", 0),
+            execution_time=response.get("execution_time", 0.0),
+            rich_outputs=[]
+        )