hopx-ai 0.1.17__py3-none-any.whl

hopx_ai/_async_files_clean.py

@@ -0,0 +1,489 @@
+"""File operations resource for Bunnyshell Sandboxes."""
+
+from typing import List, Optional, Union, AsyncIterator, Dict, Any
+import logging
+from .models import FileInfo
+from ._agent_client import AgentHTTPClient
+
+logger = logging.getLogger(__name__)
+
+
+class Files:
+    """
+    File operations resource.
+    
+    Provides methods for reading, writing, uploading, downloading, and managing files
+    inside the sandbox.
+    
+    Features:
+    - Text and binary file support
+    - Automatic retry with exponential backoff
+    - Connection pooling for efficiency
+    - Proper error handling
+    
+    Example:
+        >>> sandbox = Sandbox.create(template="code-interpreter")
+        >>> 
+        >>> # Text files
+        >>> sandbox.files.write('/workspace/hello.py', 'print("Hello, World!")')
+        >>> content = sandbox.files.read('/workspace/hello.py')
+        >>> 
+        >>> # Binary files
+        >>> sandbox.files.write_bytes('/workspace/image.png', image_bytes)
+        >>> data = sandbox.files.read_bytes('/workspace/image.png')
+        >>> 
+        >>> # List files
+        >>> files = sandbox.files.list('/workspace')
+        >>> for f in files:
+        ...     print(f"{f.name}: {f.size_kb:.2f} KB")
+    """
+    
+    def __init__(self, client: AgentHTTPClient, sandbox: Optional[Any] = None):
+        """
+        Initialize Files resource.
+        
+        Args:
+            client: Shared agent HTTP client
+            sandbox: Parent sandbox instance for lazy WebSocket init
+        """
+        self._client = client
+        self._sandbox = sandbox
+        logger.debug("Files resource initialized")
+    
+    def read(self, path: str, *, timeout: Optional[int] = None) -> str:
+        """
+        Read text file contents.
+        
+        For binary files, use read_bytes() instead.
+        
+        Args:
+            path: File path (e.g., '/workspace/data.txt')
+            timeout: Request timeout in seconds (overrides default)
+        
+        Returns:
+            File contents as string
+        
+        Raises:
+            FileNotFoundError: If file doesn't exist
+            FileOperationError: If read fails
+        
+        Example:
+            >>> content = sandbox.files.read('/workspace/data.txt')
+            >>> print(content)
+        """
+        logger.debug(f"Reading text file: {path}")
+        
+        response = self._client.get(
+            "/files/read",
+            params={"path": path},
+            operation="read file",
+            context={"path": path},
+            timeout=timeout
+        )
+        
+        data = response.json()
+        return data.get("content", "")
+    
+    def read_bytes(self, path: str, *, timeout: Optional[int] = None) -> bytes:
+        """
+        Read binary file contents.
+        
+        Use this for images, PDFs, or any binary data.
+        
+        Args:
+            path: File path (e.g., '/workspace/plot.png')
+            timeout: Request timeout in seconds (overrides default)
+        
+        Returns:
+            File contents as bytes
+        
+        Raises:
+            FileNotFoundError: If file doesn't exist
+            FileOperationError: If read fails
+        
+        Example:
+            >>> # Read matplotlib plot
+            >>> plot_data = sandbox.files.read_bytes('/workspace/plot.png')
+            >>> with open('local_plot.png', 'wb') as f:
+            ...     f.write(plot_data)
+        """
+        logger.debug(f"Reading binary file: {path}")
+        
+        response = self._client.get(
+            "/files/download",
+            params={"path": path},
+            operation="read binary file",
+            context={"path": path},
+            timeout=timeout
+        )
+        
+        return response.content
+    
+    def write(
+        self,
+        path: str,
+        content: str,
+        mode: str = "0644",
+        *,
+        timeout: Optional[int] = None
+    ) -> None:
+        """
+        Write text file contents.
+        
+        For binary files, use write_bytes() instead.
+        
+        Args:
+            path: File path (e.g., '/workspace/output.txt')
+            content: File contents to write (string)
+            mode: File permissions (default: '0644')
+            timeout: Request timeout in seconds (overrides default)
+        
+        Raises:
+            FileOperationError: If write fails
+        
+        Example:
+            >>> sandbox.files.write('/workspace/hello.py', 'print("Hello!")')
+            >>> 
+            >>> # With custom permissions
+            >>> sandbox.files.write('/workspace/script.sh', '#!/bin/bash\\necho hi', mode='0755')
+        """
+        logger.debug(f"Writing text file: {path} ({len(content)} chars)")
+        
+        self._client.post(
+            "/files/write",
+            json={
+                "path": path,
+                "content": content,
+                "mode": mode
+            },
+            operation="write file",
+            context={"path": path},
+            timeout=timeout
+        )
+    
+    def write_bytes(
+        self,
+        path: str,
+        content: bytes,
+        mode: str = "0644",
+        *,
+        timeout: Optional[int] = None
+    ) -> None:
+        """
+        Write binary file contents.
+        
+        Use this for images, PDFs, or any binary data.
+        
+        Args:
+            path: File path (e.g., '/workspace/image.png')
+            content: File contents to write (bytes)
+            mode: File permissions (default: '0644')
+            timeout: Request timeout in seconds (overrides default)
+        
+        Raises:
+            FileOperationError: If write fails
+        
+        Example:
+            >>> # Save image
+            >>> with open('image.png', 'rb') as f:
+            ...     image_data = f.read()
+            >>> sandbox.files.write_bytes('/workspace/image.png', image_data)
+        """
+        logger.debug(f"Writing binary file: {path} ({len(content)} bytes)")
+        
+        # Encode bytes to base64 for JSON transport
+        import base64
+        content_b64 = base64.b64encode(content).decode('ascii')
+        
+        self._client.post(
+            "/files/write",
+            json={
+                "path": path,
+                "content": content_b64,
+                "mode": mode,
+                "encoding": "base64"
+            },
+            operation="write binary file",
+            context={"path": path},
+            timeout=timeout
+        )
+    
+    def list(self, path: str = "/workspace", *, timeout: Optional[int] = None) -> List[FileInfo]:
+        """
+        List directory contents.
+        
+        Args:
+            path: Directory path (default: '/workspace')
+            timeout: Request timeout in seconds (overrides default)
+        
+        Returns:
+            List of FileInfo objects
+        
+        Raises:
+            FileNotFoundError: If directory doesn't exist
+            FileOperationError: If list fails
+        
+        Example:
+            >>> files = sandbox.files.list('/workspace')
+            >>> for f in files:
+            ...     if f.is_file:
+            ...         print(f"📄 {f.name}: {f.size_kb:.2f} KB")
+            ...     else:
+            ...         print(f"📁 {f.name}/")
+        """
+        logger.debug(f"Listing directory: {path}")
+        
+        response = self._client.get(
+            "/files/list",
+            params={"path": path},
+            operation="list directory",
+            context={"path": path},
+            timeout=timeout
+        )
+        
+        data = response.json()
+        
+        files = []
+        for item in data.get("files", []):
+            files.append(FileInfo(
+                name=item.get("name", ""),
+                path=item.get("path", ""),
+                size=item.get("size", 0),
+                is_directory=item.get("is_directory", item.get("is_dir", False)),  # Support both
+                permissions=item.get("permissions", item.get("mode", "")),  # Support both
+                modified_time=item.get("modified_time", item.get("modified"))  # Support both
+            ))
+        
+        return files
+    
+    def upload(
+        self,
+        local_path: str,
+        remote_path: str,
+        *,
+        timeout: Optional[int] = None
+    ) -> None:
+        """
+        Upload file from local filesystem to sandbox.
+        
+        Args:
+            local_path: Path to local file
+            remote_path: Destination path in sandbox
+            timeout: Request timeout in seconds (overrides default, recommended: 60+)
+        
+        Raises:
+            FileNotFoundError: If local file doesn't exist
+            FileOperationError: If upload fails
+        
+        Example:
+            >>> # Upload local file to sandbox
+            >>> sandbox.files.upload('./data.csv', '/workspace/data.csv')
+            >>> 
+            >>> # Upload with custom timeout for large file
+            >>> sandbox.files.upload('./large.zip', '/workspace/large.zip', timeout=120)
+        """
+        logger.debug(f"Uploading file: {local_path} -> {remote_path}")
+        
+        with open(local_path, 'rb') as f:
+            self._client.post(
+                "/files/upload",
+                files={"file": f},
+                data={"path": remote_path},
+                operation="upload file",
+                context={"path": remote_path},
+                timeout=timeout or 60  # Default 60s for uploads
+            )
+    
+    def download(
+        self,
+        remote_path: str,
+        local_path: str,
+        *,
+        timeout: Optional[int] = None
+    ) -> None:
+        """
+        Download file from sandbox to local filesystem.
+        
+        Args:
+            remote_path: Path in sandbox
+            local_path: Destination path on local filesystem
+            timeout: Request timeout in seconds (overrides default, recommended: 60+)
+        
+        Raises:
+            FileNotFoundError: If file doesn't exist in sandbox
+            FileOperationError: If download fails
+        
+        Example:
+            >>> # Download file from sandbox
+            >>> sandbox.files.download('/workspace/result.csv', './result.csv')
+            >>> 
+            >>> # Download plot
+            >>> sandbox.files.download('/workspace/plot.png', './plot.png')
+        """
+        logger.debug(f"Downloading file: {remote_path} -> {local_path}")
+        
+        response = self._client.get(
+            "/files/download",
+            params={"path": remote_path},
+            operation="download file",
+            context={"path": remote_path},
+            timeout=timeout or 60  # Default 60s for downloads
+        )
+        
+        with open(local_path, 'wb') as f:
+            f.write(response.content)
+    
+    def exists(self, path: str, *, timeout: Optional[int] = None) -> bool:
+        """
+        Check if file or directory exists.
+        
+        Args:
+            path: File or directory path
+            timeout: Request timeout in seconds (overrides default)
+        
+        Returns:
+            True if exists, False otherwise
+        
+        Example:
+            >>> if sandbox.files.exists('/workspace/data.csv'):
+            ...     print("File exists!")
+            ... else:
+            ...     print("File not found")
+        """
+        logger.debug(f"Checking if exists: {path}")
+        
+        try:
+            response = self._client.get(
+                "/files/exists",
+                params={"path": path},
+                operation="check file exists",
+                context={"path": path},
+                timeout=timeout or 10
+            )
+            data = response.json()
+            return data.get("exists", False)
+        except Exception:
+            return False
+    
+    def remove(self, path: str, *, timeout: Optional[int] = None) -> None:
+        """
+        Delete file or directory.
+        
+        Args:
+            path: Path to file or directory to delete
+            timeout: Request timeout in seconds (overrides default)
+        
+        Raises:
+            FileNotFoundError: If file doesn't exist
+            FileOperationError: If delete fails
+        
+        Example:
+            >>> # Remove file
+            >>> sandbox.files.remove('/workspace/temp.txt')
+            >>> 
+            >>> # Remove directory (recursive)
+            >>> sandbox.files.remove('/workspace/old_data')
+        """
+        logger.debug(f"Removing: {path}")
+        
+        self._client.delete(
+            "/files/remove",
+            params={"path": path},
+            operation="remove file",
+            context={"path": path},
+            timeout=timeout
+        )
+    
+    def mkdir(self, path: str, *, timeout: Optional[int] = None) -> None:
+        """
+        Create directory.
+        
+        Args:
+            path: Directory path to create
+            timeout: Request timeout in seconds (overrides default)
+        
+        Raises:
+            FileOperationError: If mkdir fails
+        
+        Example:
+            >>> # Create directory
+            >>> sandbox.files.mkdir('/workspace/data')
+            >>> 
+            >>> # Create nested directories
+            >>> sandbox.files.mkdir('/workspace/project/src')
+        """
+        logger.debug(f"Creating directory: {path}")
+        
+        self._client.post(
+            "/files/mkdir",
+            json={"path": path},
+            operation="create directory",
+            context={"path": path},
+            timeout=timeout
+        )
+    
+    async def watch(
+        self,
+        path: str = "/workspace",
+        *,
+        timeout: Optional[int] = None
+    ) -> AsyncIterator[Dict[str, Any]]:
+        """
+        Watch filesystem for changes via WebSocket.
+        
+        Stream file system events (create, modify, delete, rename) in real-time.
+        
+        Args:
+            path: Path to watch (default: /workspace)
+            timeout: Connection timeout in seconds
+        
+        Yields:
+            Change event dictionaries:
+            - {"type": "change", "path": "...", "event": "created", "timestamp": "..."}
+            - {"type": "change", "path": "...", "event": "modified", "timestamp": "..."}
+            - {"type": "change", "path": "...", "event": "deleted", "timestamp": "..."}
+            - {"type": "change", "path": "...", "event": "renamed", "timestamp": "..."}
+        
+        Note:
+            Requires websockets library: pip install websockets
+        
+        Example:
+            >>> import asyncio
+            >>> 
+            >>> async def watch_files():
+            ...     sandbox = Sandbox.create(template="code-interpreter")
+            ...     
+            ...     # Start watching
+            ...     async for event in sandbox.files.watch("/workspace"):
+            ...         print(f"{event['event']}: {event['path']}")
+            ...         
+            ...         # Stop after 10 events
+            ...         if event_count >= 10:
+            ...             break
+            >>> 
+            >>> asyncio.run(watch_files())
+        """
+        # Lazy-load WebSocket client from sandbox if needed
+        if self._sandbox is not None:
+            self._sandbox._ensure_ws_client()
+            ws_client = self._sandbox._ws_client
+        else:
+            raise RuntimeError(
+                "WebSocket client not available. "
+                "File watching requires websockets library: pip install websockets"
+            )
+        
+        # Connect to file watcher endpoint
+        async with await ws_client.connect("/files/watch", timeout=timeout) as ws:
+            # Send watch request
+            await ws_client.send_message(ws, {
+                "action": "watch",
+                "path": path
+            })
+            
+            # Stream change events
+            async for message in ws_client.iter_messages(ws):
+                yield message
+    
+    def __repr__(self) -> str:
+        return f"<Files client={self._client}>"

hopx_ai/_async_terminal.py

@@ -0,0 +1,184 @@
+"""Async interactive terminal access via WebSocket."""
+
+import logging
+from typing import Optional, AsyncIterator, Dict, Any
+
+try:
+    from websockets.client import WebSocketClientProtocol
+    import websockets
+    WEBSOCKETS_AVAILABLE = True
+except ImportError:
+    WEBSOCKETS_AVAILABLE = False
+    WebSocketClientProtocol = Any  # type: ignore
+
+logger = logging.getLogger(__name__)
+
+
+class AsyncTerminal:
+    """
+    Async interactive terminal resource with PTY support via WebSocket.
+    
+    Provides real-time terminal access to the sandbox for interactive commands.
+    
+    Features:
+    - Full PTY support
+    - Real-time output streaming
+    - Terminal resize support
+    - Process exit notifications
+    
+    Example:
+        >>> async def interactive_terminal():
+        ...     sandbox = await AsyncSandbox.create(template="code-interpreter")
+        ...     
+        ...     # Connect to terminal
+        ...     async with await sandbox.terminal.connect() as ws:
+        ...         # Send command
+        ...         await sandbox.terminal.send_input(ws, "ls -la\\n")
+        ...         
+        ...         # Receive output
+        ...         async for message in sandbox.terminal.iter_output(ws):
+        ...             if message['type'] == 'output':
+        ...                 print(message['data'], end='')
+        ...             elif message['type'] == 'exit':
+        ...                 print(f"\\nProcess exited: {message['code']}")
+        ...                 break
+    """
+    
+    def __init__(self, sandbox):
+        """
+        Initialize AsyncTerminal resource.
+        
+        Args:
+            sandbox: Parent AsyncSandbox instance
+        """
+        if not WEBSOCKETS_AVAILABLE:
+            raise ImportError(
+                "websockets library is required for terminal features. "
+                "Install with: pip install websockets"
+            )
+        
+        self._sandbox = sandbox
+        self._ws_url = None
+        logger.debug("AsyncTerminal resource initialized")
+    
+    async def _get_ws_url(self) -> str:
+        """Get WebSocket URL from sandbox."""
+        if self._ws_url is None:
+            info = await self._sandbox.get_info()
+            agent_url = info.public_host.rstrip('/')
+            # Convert https:// to wss://
+            self._ws_url = agent_url.replace('https://', 'wss://').replace('http://', 'ws://')
+        return self._ws_url
+    
+    async def connect(
+        self,
+        *,
+        timeout: Optional[int] = 30
+    ) -> WebSocketClientProtocol:
+        """
+        Connect to interactive terminal.
+        
+        Args:
+            timeout: Connection timeout in seconds
+        
+        Returns:
+            WebSocket connection (use with async context manager)
+        
+        Example:
+            >>> async with await sandbox.terminal.connect() as ws:
+            ...     await sandbox.terminal.send_input(ws, "echo 'Hello'\\n")
+            ...     async for msg in sandbox.terminal.iter_output(ws):
+            ...         print(msg['data'], end='')
+            ...         if msg['type'] == 'exit':
+            ...             break
+        """
+        ws_url = await self._get_ws_url()
+        
+        # Connect to WebSocket (no auth needed - agent handles it)
+        ws = await websockets.connect(
+            f"{ws_url}/terminal",
+            open_timeout=timeout
+        )
+        
+        return ws
+    
+    async def send_input(
+        self,
+        ws: WebSocketClientProtocol,
+        data: str
+    ) -> None:
+        """
+        Send input to terminal.
+        
+        Args:
+            ws: WebSocket connection
+            data: Input data (include \\n for commands)
+        
+        Example:
+            >>> await terminal.send_input(ws, "ls -la\\n")
+            >>> await terminal.send_input(ws, "cd /workspace\\n")
+        """
+        import json
+        await ws.send(json.dumps({
+            "type": "input",
+            "data": data
+        }))
+    
+    async def resize(
+        self,
+        ws: WebSocketClientProtocol,
+        cols: int,
+        rows: int
+    ) -> None:
+        """
+        Resize terminal window.
+        
+        Args:
+            ws: WebSocket connection
+            cols: Number of columns
+            rows: Number of rows
+        
+        Example:
+            >>> await terminal.resize(ws, cols=120, rows=40)
+        """
+        import json
+        await ws.send(json.dumps({
+            "type": "resize",
+            "cols": cols,
+            "rows": rows
+        }))
+    
+    async def iter_output(
+        self,
+        ws: WebSocketClientProtocol
+    ) -> AsyncIterator[Dict[str, Any]]:
+        """
+        Iterate over terminal output messages.
+        
+        Args:
+            ws: WebSocket connection
+        
+        Yields:
+            Message dictionaries:
+            - {"type": "output", "data": "..."}
+            - {"type": "exit", "code": 0}
+        
+        Example:
+            >>> async for message in terminal.iter_output(ws):
+            ...     if message['type'] == 'output':
+            ...         print(message['data'], end='')
+            ...     elif message['type'] == 'exit':
+            ...         print(f"Exit code: {message['code']}")
+            ...         break
+        """
+        import json
+        async for message in ws:
+            try:
+                data = json.loads(message)
+                yield data
+            except json.JSONDecodeError:
+                # Skip invalid messages
+                continue
+    
+    def __repr__(self) -> str:
+        return f"<AsyncTerminal sandbox={self._sandbox.sandbox_id}>"