portacode 0.2.3.dev0__tar.gz → 0.2.4.dev0__tar.gz

{portacode-0.2.3.dev0 → portacode-0.2.4.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: portacode
-Version: 0.2.3.dev0
+Version: 0.2.4.dev0
 Summary: Portacode CLI client and SDK
 Home-page: https://github.com/portacode/portacode
 Author: Meena Erian

{portacode-0.2.3.dev0 → portacode-0.2.4.dev0}/portacode/_version.py

@@ -17,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.2.3.dev'
-__version_tuple__ = version_tuple = (0, 2, 3, 'dev0')
+__version__ = version = '0.2.4.dev'
+__version_tuple__ = version_tuple = (0, 2, 4, 'dev0')

portacode-0.2.4.dev0/portacode/connection/handlers/README.md

@@ -0,0 +1,427 @@
+# Portacode Handler System
+
+This directory contains the modular command handler system for the Portacode client. The system provides a clean, extensible architecture for processing commands from the gateway.
+
+## Architecture Overview
+
+The handler system consists of:
+
+- **Base Handler Classes**: `BaseHandler`, `AsyncHandler`, `SyncHandler`
+- **Command Registry**: `CommandRegistry` for managing and dispatching handlers
+- **Session Management**: `SessionManager` for terminal session lifecycle
+- **Specific Handlers**: Individual command implementations
+
+## Existing Handlers
+
+### Terminal Handlers (`terminal_handlers.py`)
+
+1. **`TerminalStartHandler`** - `terminal_start`
+   - Starts new terminal sessions
+   - Supports shell and cwd parameters
+   - Handles both Windows (ConPTY) and Unix (PTY) systems
+
+2. **`TerminalSendHandler`** - `terminal_send` 
+   - Sends data to existing terminal sessions
+   - Requires terminal_id and data parameters
+
+3. **`TerminalStopHandler`** - `terminal_stop`
+   - Terminates terminal sessions
+   - Cleans up resources and sends exit events
+
+4. **`TerminalListHandler`** - `terminal_list`
+   - Lists all active terminal sessions
+   - Returns session metadata and buffer contents
+
+### System Handlers (`system_handlers.py`)
+
+1. **`SystemInfoHandler`** - `system_info`
+   - Provides system resource information
+   - Returns CPU, memory, and disk usage data
+
+## Adding New Handlers
+
+### 1. Asynchronous Handlers
+
+For commands that need to perform I/O operations, use `AsyncHandler`:
+
+```python
+from .base import AsyncHandler
+from typing import Any, Dict
+
+class FileReadHandler(AsyncHandler):
+    """Handler for reading file contents."""
+    
+    @property
+    def command_name(self) -> str:
+        return "file_read"
+    
+    async def execute(self, message: Dict[str, Any]) -> Dict[str, Any]:
+        """Read file contents asynchronously."""
+        file_path = message.get("path")
+        if not file_path:
+            raise ValueError("path parameter is required")
+        
+        # Async file operations
+        import aiofiles
+        async with aiofiles.open(file_path, 'r') as f:
+            content = await f.read()
+        
+        return {
+            "event": "file_read_response",
+            "path": file_path,
+            "content": content,
+        }
+```
+
+### 2. Synchronous Handlers
+
+For CPU-bound operations or simple synchronous tasks, use `SyncHandler`:
+
+```python
+from .base import SyncHandler
+from typing import Any, Dict
+import os
+
+class DirectoryListHandler(SyncHandler):
+    """Handler for listing directory contents."""
+    
+    @property
+    def command_name(self) -> str:
+        return "directory_list"
+    
+    def execute(self, message: Dict[str, Any]) -> Dict[str, Any]:
+        """List directory contents synchronously."""
+        path = message.get("path", ".")
+        
+        try:
+            items = []
+            for item in os.listdir(path):
+                item_path = os.path.join(path, item)
+                items.append({
+                    "name": item,
+                    "is_dir": os.path.isdir(item_path),
+                    "size": os.path.getsize(item_path) if os.path.isfile(item_path) else 0,
+                })
+            
+            return {
+                "event": "directory_list_response",
+                "path": path,
+                "items": items,
+            }
+        except Exception as e:
+            raise RuntimeError(f"Failed to list directory: {e}")
+```
+
+### 3. Complex Handler with Context Access
+
+Handlers can access shared context and services:
+
+```python
+from .base import AsyncHandler
+from typing import Any, Dict
+
+class ProcessManagementHandler(AsyncHandler):
+    """Handler for managing processes on the device."""
+    
+    @property 
+    def command_name(self) -> str:
+        return "process_management"
+    
+    async def execute(self, message: Dict[str, Any]) -> Dict[str, Any]:
+        """Manage processes with access to session manager."""
+        action = message.get("action")  # "list", "kill", "start"
+        
+        # Access session manager from context
+        session_manager = self.context.get("session_manager")
+        if not session_manager:
+            raise RuntimeError("Session manager not available")
+        
+        if action == "list":
+            import psutil
+            processes = []
+            for proc in psutil.process_iter(['pid', 'name', 'cpu_percent']):
+                try:
+                    processes.append(proc.info)
+                except (psutil.NoSuchProcess, psutil.AccessDenied):
+                    continue
+            
+            return {
+                "event": "process_list_response",
+                "processes": processes,
+            }
+        
+        elif action == "kill":
+            pid = message.get("pid")
+            if not pid:
+                raise ValueError("pid parameter required for kill action")
+            
+            import psutil
+            try:
+                process = psutil.Process(pid)
+                process.terminate()
+                return {
+                    "event": "process_killed",
+                    "pid": pid,
+                }
+            except psutil.NoSuchProcess:
+                raise ValueError(f"Process {pid} not found")
+        
+        else:
+            raise ValueError(f"Unknown action: {action}")
+```
+
+### 4. Handler with Custom Response Handling
+
+You can override the `handle` method for custom response behavior:
+
+```python
+from .base import BaseHandler
+from typing import Any, Dict, Optional
+
+class StreamingHandler(BaseHandler):
+    """Handler that streams responses."""
+    
+    @property
+    def command_name(self) -> str:
+        return "streaming_data"
+    
+    async def handle(self, message: Dict[str, Any], reply_channel: Optional[str] = None) -> None:
+        """Handle streaming data with custom response handling."""
+        try:
+            # Send initial response
+            await self.send_response({
+                "event": "streaming_started",
+                "message": "Starting data stream",
+            }, reply_channel)
+            
+            # Stream data
+            for i in range(10):
+                await asyncio.sleep(0.1)
+                await self.send_response({
+                    "event": "streaming_data",
+                    "chunk": i,
+                    "data": f"Data chunk {i}",
+                }, reply_channel)
+            
+            # Send completion
+            await self.send_response({
+                "event": "streaming_completed",
+                "message": "Stream completed",
+            }, reply_channel)
+            
+        except Exception as exc:
+            await self.send_error(str(exc), reply_channel)
+```
+
+## Registering Handlers
+
+### 1. Automatic Registration
+
+Add your handler to the `__init__.py` file and register it in `TerminalManager._register_default_handlers()`:
+
+```python
+# In __init__.py
+from .file_handlers import FileReadHandler, DirectoryListHandler
+
+# In terminal.py _register_default_handlers()
+def _register_default_handlers(self) -> None:
+    """Register the default command handlers."""
+    # ... existing handlers ...
+    self._command_registry.register(FileReadHandler)
+    self._command_registry.register(DirectoryListHandler)
+```
+
+### 2. Dynamic Registration
+
+Register handlers at runtime:
+
+```python
+# In your code
+terminal_manager.register_handler(MyCustomHandler)
+
+# List all registered commands
+commands = terminal_manager.list_commands()
+print(f"Available commands: {commands}")
+
+# Unregister if needed
+terminal_manager.unregister_handler("my_command")
+```
+
+## Handler Guidelines
+
+### Best Practices
+
+1. **Command Naming**: Use descriptive, action-oriented names (`file_read`, `system_info`)
+2. **Error Handling**: Always validate input parameters and provide meaningful error messages
+3. **Response Format**: Use consistent response formats with `event` field
+4. **Resource Management**: Clean up resources in exception handlers
+5. **Logging**: Use appropriate logging levels for debugging and monitoring
+
+### Parameter Validation
+
+```python
+def execute(self, message: Dict[str, Any]) -> Dict[str, Any]:
+    # Validate required parameters
+    required_params = ["param1", "param2"]
+    for param in required_params:
+        if param not in message:
+            raise ValueError(f"Missing required parameter: {param}")
+    
+    # Validate parameter types
+    if not isinstance(message.get("count"), int):
+        raise ValueError("count parameter must be an integer")
+    
+    # Your logic here...
+```
+
+### Error Handling
+
+```python
+async def execute(self, message: Dict[str, Any]) -> Dict[str, Any]:
+    try:
+        # Your logic here
+        result = await some_async_operation()
+        return {"event": "success", "result": result}
+    except FileNotFoundError:
+        raise ValueError("File not found")
+    except PermissionError:
+        raise RuntimeError("Permission denied")
+    except Exception as e:
+        raise RuntimeError(f"Unexpected error: {e}")
+```
+
+## Testing Handlers
+
+### Unit Testing
+
+```python
+import pytest
+from unittest.mock import Mock, AsyncMock
+from portacode.connection.handlers.your_handler import YourHandler
+
+@pytest.mark.asyncio
+async def test_your_handler():
+    # Mock control channel
+    control_channel = AsyncMock()
+    
+    # Mock context
+    context = {"session_manager": Mock()}
+    
+    # Create handler
+    handler = YourHandler(control_channel, context)
+    
+    # Test execute
+    message = {"param1": "value1"}
+    result = await handler.execute(message)
+    
+    assert result["event"] == "expected_event"
+    assert result["data"] == "expected_data"
+```
+
+### Integration Testing
+
+```python
+# Test with real TerminalManager
+terminal_manager = TerminalManager(mock_multiplexer)
+terminal_manager.register_handler(YourHandler)
+
+# Simulate command
+message = {"cmd": "your_command", "param1": "value1"}
+# Process through control loop...
+```
+
+## Communication Protocol
+
+### Command Format
+
+Commands from the gateway follow this format:
+
+```json
+{
+  "cmd": "command_name",
+  "param1": "value1", 
+  "param2": "value2",
+  "reply_channel": "optional_reply_channel"
+}
+```
+
+### Response Format
+
+Responses to the gateway should follow this format:
+
+```json
+{
+  "event": "event_name",
+  "data": "response_data",
+  "reply_channel": "reply_channel_if_provided"
+}
+```
+
+### Error Format
+
+Error responses:
+
+```json
+{
+  "event": "error",
+  "message": "Error description",
+  "reply_channel": "reply_channel_if_provided"
+}
+```
+
+## Advanced Topics
+
+### Custom Context
+
+You can extend the context with custom services:
+
+```python
+# In TerminalManager._set_mux()
+self._context = {
+    "session_manager": self._session_manager,
+    "mux": mux,
+    "file_manager": FileManager(),
+    "process_manager": ProcessManager(),
+}
+```
+
+### Handler Chaining
+
+Handlers can call other handlers:
+
+```python
+async def execute(self, message: Dict[str, Any]) -> Dict[str, Any]:
+    # Get another handler
+    other_handler = self.context.get("command_registry").get_handler("other_command")
+    if other_handler:
+        intermediate_result = await other_handler.execute(message)
+        # Process intermediate result...
+    
+    return final_result
+```
+
+### Middleware Pattern
+
+Create middleware handlers that wrap other handlers:
+
+```python
+class LoggingMiddleware(BaseHandler):
+    def __init__(self, control_channel, context, wrapped_handler):
+        super().__init__(control_channel, context)
+        self.wrapped_handler = wrapped_handler
+    
+    async def handle(self, message, reply_channel=None):
+        logger.info(f"Executing command: {message.get('cmd')}")
+        start_time = time.time()
+        
+        try:
+            result = await self.wrapped_handler.handle(message, reply_channel)
+            duration = time.time() - start_time
+            logger.info(f"Command completed in {duration:.2f}s")
+            return result
+        except Exception as e:
+            logger.error(f"Command failed: {e}")
+            raise
+```
+
+This modular system provides a clean, extensible architecture for adding new functionality to the Portacode client while maintaining backward compatibility and code organization. 

{portacode-0.2.3.dev0 → portacode-0.2.4.dev0}/portacode/connection/handlers/__init__.py

@@ -14,6 +14,13 @@ from .terminal_handlers import (
     TerminalListHandler,
 )
 from .system_handlers import SystemInfoHandler
+from .file_handlers import (
+    FileReadHandler,
+    FileWriteHandler,
+    DirectoryListHandler,
+    FileInfoHandler,
+    FileDeleteHandler,
+)
 
 __all__ = [
     "BaseHandler",
@@ -25,4 +32,10 @@ __all__ = [
     "TerminalStopHandler",
     "TerminalListHandler",
     "SystemInfoHandler",
+    # File operation handlers (optional - register as needed)
+    "FileReadHandler",
+    "FileWriteHandler", 
+    "DirectoryListHandler",
+    "FileInfoHandler",
+    "FileDeleteHandler",
 ] 

portacode-0.2.4.dev0/portacode/connection/handlers/file_handlers.py

@@ -0,0 +1,209 @@
+"""File operation handlers for demonstrating the send_command functionality."""
+
+import os
+import logging
+from typing import Any, Dict
+from pathlib import Path
+
+from .base import AsyncHandler, SyncHandler
+
+logger = logging.getLogger(__name__)
+
+
+class FileReadHandler(SyncHandler):
+    """Handler for reading file contents."""
+    
+    @property
+    def command_name(self) -> str:
+        return "file_read"
+    
+    def execute(self, message: Dict[str, Any]) -> Dict[str, Any]:
+        """Read file contents."""
+        file_path = message.get("path")
+        if not file_path:
+            raise ValueError("path parameter is required")
+        
+        try:
+            with open(file_path, 'r', encoding='utf-8') as f:
+                content = f.read()
+            
+            return {
+                "event": "file_read_response",
+                "path": file_path,
+                "content": content,
+                "size": len(content),
+            }
+        except FileNotFoundError:
+            raise ValueError(f"File not found: {file_path}")
+        except PermissionError:
+            raise RuntimeError(f"Permission denied: {file_path}")
+        except UnicodeDecodeError:
+            raise RuntimeError(f"File is not text or uses unsupported encoding: {file_path}")
+
+
+class FileWriteHandler(SyncHandler):
+    """Handler for writing file contents."""
+    
+    @property
+    def command_name(self) -> str:
+        return "file_write"
+    
+    def execute(self, message: Dict[str, Any]) -> Dict[str, Any]:
+        """Write file contents."""
+        file_path = message.get("path")
+        content = message.get("content", "")
+        
+        if not file_path:
+            raise ValueError("path parameter is required")
+        
+        try:
+            # Create parent directories if they don't exist
+            Path(file_path).parent.mkdir(parents=True, exist_ok=True)
+            
+            with open(file_path, 'w', encoding='utf-8') as f:
+                f.write(content)
+            
+            return {
+                "event": "file_write_response",
+                "path": file_path,
+                "bytes_written": len(content.encode('utf-8')),
+                "success": True,
+            }
+        except PermissionError:
+            raise RuntimeError(f"Permission denied: {file_path}")
+        except OSError as e:
+            raise RuntimeError(f"Failed to write file: {e}")
+
+
+class DirectoryListHandler(SyncHandler):
+    """Handler for listing directory contents."""
+    
+    @property
+    def command_name(self) -> str:
+        return "directory_list"
+    
+    def execute(self, message: Dict[str, Any]) -> Dict[str, Any]:
+        """List directory contents."""
+        path = message.get("path", ".")
+        show_hidden = message.get("show_hidden", False)
+        
+        try:
+            items = []
+            for item in os.listdir(path):
+                # Skip hidden files unless requested
+                if not show_hidden and item.startswith('.'):
+                    continue
+                    
+                item_path = os.path.join(path, item)
+                try:
+                    stat_info = os.stat(item_path)
+                    items.append({
+                        "name": item,
+                        "is_dir": os.path.isdir(item_path),
+                        "is_file": os.path.isfile(item_path),
+                        "size": stat_info.st_size,
+                        "modified": stat_info.st_mtime,
+                        "permissions": oct(stat_info.st_mode)[-3:],
+                    })
+                except (OSError, PermissionError):
+                    # Skip items we can't stat
+                    continue
+            
+            return {
+                "event": "directory_list_response",
+                "path": path,
+                "items": items,
+                "count": len(items),
+            }
+        except FileNotFoundError:
+            raise ValueError(f"Directory not found: {path}")
+        except PermissionError:
+            raise RuntimeError(f"Permission denied: {path}")
+        except NotADirectoryError:
+            raise ValueError(f"Path is not a directory: {path}")
+
+
+class FileInfoHandler(SyncHandler):
+    """Handler for getting file/directory information."""
+    
+    @property
+    def command_name(self) -> str:
+        return "file_info"
+    
+    def execute(self, message: Dict[str, Any]) -> Dict[str, Any]:
+        """Get file or directory information."""
+        path = message.get("path")
+        if not path:
+            raise ValueError("path parameter is required")
+        
+        try:
+            stat_info = os.stat(path)
+            
+            return {
+                "event": "file_info_response",
+                "path": path,
+                "exists": True,
+                "is_file": os.path.isfile(path),
+                "is_dir": os.path.isdir(path),
+                "is_symlink": os.path.islink(path),
+                "size": stat_info.st_size,
+                "modified": stat_info.st_mtime,
+                "accessed": stat_info.st_atime,
+                "created": stat_info.st_ctime,
+                "permissions": oct(stat_info.st_mode)[-3:],
+                "owner_uid": stat_info.st_uid,
+                "group_gid": stat_info.st_gid,
+            }
+        except FileNotFoundError:
+            return {
+                "event": "file_info_response", 
+                "path": path,
+                "exists": False,
+            }
+        except PermissionError:
+            raise RuntimeError(f"Permission denied: {path}")
+
+
+class FileDeleteHandler(SyncHandler):
+    """Handler for deleting files and directories."""
+    
+    @property
+    def command_name(self) -> str:
+        return "file_delete"
+    
+    def execute(self, message: Dict[str, Any]) -> Dict[str, Any]:
+        """Delete a file or directory."""
+        path = message.get("path")
+        recursive = message.get("recursive", False)
+        
+        if not path:
+            raise ValueError("path parameter is required")
+        
+        try:
+            if os.path.isfile(path):
+                os.remove(path)
+                deleted_type = "file"
+            elif os.path.isdir(path):
+                if recursive:
+                    import shutil
+                    shutil.rmtree(path)
+                else:
+                    os.rmdir(path)
+                deleted_type = "directory"
+            else:
+                raise ValueError(f"Path does not exist: {path}")
+            
+            return {
+                "event": "file_delete_response",
+                "path": path,
+                "deleted_type": deleted_type,
+                "success": True,
+            }
+        except FileNotFoundError:
+            raise ValueError(f"Path not found: {path}")
+        except PermissionError:
+            raise RuntimeError(f"Permission denied: {path}")
+        except OSError as e:
+            if "Directory not empty" in str(e):
+                raise ValueError(f"Directory not empty (use recursive=True): {path}")
+            raise RuntimeError(f"Failed to delete: {e}") 

{portacode-0.2.3.dev0 → portacode-0.2.4.dev0}/portacode/connection/handlers/session.py

@@ -164,13 +164,10 @@ class SessionManager:
     def __init__(self, mux):
         self.mux = mux
         self._sessions: Dict[str, TerminalSession] = {}
-        self._next_channel = 100
 
-    def _allocate_channel_id(self) -> int:
-        """Allocate a new channel ID for a terminal session."""
-        cid = self._next_channel
-        self._next_channel += 1
-        return cid
+    def _allocate_channel_id(self) -> str:
+        """Allocate a new unique channel ID for a terminal session using UUID."""
+        return uuid.uuid4().hex
 
     async def create_session(self, shell: Optional[str] = None, cwd: Optional[str] = None) -> Dict[str, Any]:
         """Create a new terminal session."""
@@ -182,7 +179,7 @@ class SessionManager:
         if shell is None:
             shell = os.getenv("SHELL") if not _IS_WINDOWS else os.getenv("COMSPEC", "cmd.exe")
 
-        logger.info("Launching terminal %s using shell=%s on channel=%d", term_id, shell, channel_id)
+        logger.info("Launching terminal %s using shell=%s on channel=%s", term_id, shell, channel_id)
 
         if _IS_WINDOWS:
             try:
@@ -265,11 +262,8 @@ class SessionManager:
     def reattach_sessions(self, mux):
         """Reattach sessions to a new multiplexer after reconnection."""
         self.mux = mux
-        highest_cid = self._next_channel
         
         for sess in self._sessions.values():
-            cid = sess.channel.id
-            sess.channel = self.mux.get_channel(cid)
-            highest_cid = max(highest_cid, cid + 1)
-        
-        self._next_channel = max(self._next_channel, highest_cid) 
+            # Get the existing channel ID (now UUID string)
+            channel_id = sess.channel.id
+            sess.channel = self.mux.get_channel(channel_id) 

{portacode-0.2.3.dev0 → portacode-0.2.4.dev0}/portacode/connection/multiplex.py

@@ -4,7 +4,7 @@ import asyncio
 import json
 import logging
 from asyncio import Queue
-from typing import Any, Dict
+from typing import Any, Dict, Union
 
 __all__ = ["Multiplexer", "Channel"]
 
@@ -14,7 +14,7 @@ logger = logging.getLogger(__name__)
 class Channel:
     """Represents a virtual duplex channel over a single WebSocket connection."""
 
-    def __init__(self, channel_id: int, multiplexer: "Multiplexer"):
+    def __init__(self, channel_id: Union[int, str], multiplexer: "Multiplexer"):
         self.id = channel_id
         self._mux = multiplexer
         self._incoming: "Queue[Any]" = asyncio.Queue()
@@ -35,27 +35,27 @@ class Multiplexer:
 
     Messages exchanged over the WebSocket are JSON objects with two keys:
 
-    * ``channel`` – integer channel id.
+    * ``channel`` – integer or string channel id.
     * ``payload``  – arbitrary JSON-serialisable object.
     """
 
     def __init__(self, send_func):
         self._send_func = send_func  # async function (str) -> None
-        self._channels: Dict[int, Channel] = {}
+        self._channels: Dict[Union[int, str], Channel] = {}
 
-    def get_channel(self, channel_id: int) -> Channel:
+    def get_channel(self, channel_id: Union[int, str]) -> Channel:
         if channel_id not in self._channels:
             self._channels[channel_id] = Channel(channel_id, self)
         return self._channels[channel_id]
 
-    async def _send_on_channel(self, channel_id: int, payload: Any) -> None:
+    async def _send_on_channel(self, channel_id: Union[int, str], payload: Any) -> None:
         frame = json.dumps({"channel": channel_id, "payload": payload})
         await self._send_func(frame)
 
     async def on_raw_message(self, raw: str) -> None:
         try:
             data = json.loads(raw)
-            channel_id = int(data["channel"])
+            channel_id = data["channel"]  # Can be int or str now
             payload = data.get("payload")
         except (ValueError, KeyError) as exc:
             logger.warning("Discarding malformed frame: %s", exc)

{portacode-0.2.3.dev0 → portacode-0.2.4.dev0}/portacode.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: portacode
-Version: 0.2.3.dev0
+Version: 0.2.4.dev0
 Summary: Portacode CLI client and SDK
 Home-page: https://github.com/portacode/portacode
 Author: Meena Erian

{portacode-0.2.3.dev0 → portacode-0.2.4.dev0}/portacode.egg-info/SOURCES.txt

@@ -25,8 +25,10 @@ portacode/connection/__init__.py
 portacode/connection/client.py
 portacode/connection/multiplex.py
 portacode/connection/terminal.py
+portacode/connection/handlers/README.md
 portacode/connection/handlers/__init__.py
 portacode/connection/handlers/base.py
+portacode/connection/handlers/file_handlers.py
 portacode/connection/handlers/registry.py
 portacode/connection/handlers/session.py
 portacode/connection/handlers/system_handlers.py