portacode 0.3.12.dev8__tar.gz → 0.3.12.dev9__tar.gz

{portacode-0.3.12.dev8 → portacode-0.3.12.dev9}/PKG-INFO

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

{portacode-0.3.12.dev8 → portacode-0.3.12.dev9}/portacode/_version.py

@@ -17,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.3.12.dev8'
-__version_tuple__ = version_tuple = (0, 3, 12, 'dev8')
+__version__ = version = '0.3.12.dev9'
+__version_tuple__ = version_tuple = (0, 3, 12, 'dev9')

{portacode-0.3.12.dev8 → portacode-0.3.12.dev9}/portacode/connection/handlers/WEBSOCKET_PROTOCOL.md

@@ -26,6 +26,7 @@ This document outlines the WebSocket communication protocol between the Portacod
     - [`error`](#error)
   - [Terminal Events](#terminal-events)
     - [`terminal_started`](#terminal_started)
+    - [`terminal_data`](#terminal_data)
     - [`terminal_exit`](#terminal_exit)
     - [`terminal_send_ack`](#terminal_send_ack)
     - [`terminal_stopped`](#terminal_stopped)
@@ -79,14 +80,14 @@ Actions are messages sent from the server to the device, placed within the `payl
   "payload": {
     "arg1": "value1",
     "...": "..."
-  },
-  "reply_channel": "<channel_name>"
+  }
 }
 ```
 
 *   `command` (string, mandatory): The name of the action to be executed (e.g., `terminal_start`).
 *   `payload` (object, mandatory): An object containing the specific arguments for the action.
-*   `reply_channel` (string, optional): **DEPRECATED** - A channel name for backward compatibility. Modern implementations should use the `client_sessions` mechanism instead.
+
+**Note**: Actions do not require targeting information - responses are automatically routed using the client session management system.
 
 ### `terminal_start`
 
@@ -248,13 +249,22 @@ Events are messages sent from the device to the server, placed within the `paylo
 {
   "event": "<event_name>",
   // Event-specific fields...
-  "reply_channel": "<channel_name>"
+  "device_id": 123,
+  "project_id": "<project_uuid>",
+  "client_sessions": ["channel.abc123", "channel.def456"]
 }
 ```
 
+**Standard Fields (automatically added by the system):**
+
 *   `event` (string, mandatory): The name of the event being sent (e.g., `terminal_started`).
-*   <a name="reply_channel"></a>`reply_channel` (string, optional): **DEPRECATED** - For backward compatibility only. Modern events include `client_sessions` array for targeting.
-*   `client_sessions` (array, optional): Array of client session channel names that should receive this event. This is the modern way to target specific connected clients.
+*   `device_id` (integer, mandatory): The ID of the authenticated device that generated this event. **Added by the server based on the authenticated connection for security** - devices cannot self-identify.
+*   `project_id` (string, optional): The project UUID associated with this event, used for project-scoped filtering. Sent by the device.
+*   `client_sessions` (array, optional): Array of client session channel names that should receive this event. **Added by the device's terminal manager** based on interested client sessions. When present, the event is sent only to these specific sessions. When absent, the event is broadcast to all sessions for the device owner.
+
+**Event-Specific Fields:**
+
+Each event type includes additional fields specific to its purpose, documented in the individual event sections below.
 
 ### <a name="error"></a>`error`
 
@@ -274,6 +284,41 @@ Confirms that a new terminal session has been successfully started. Triggered by
 *   `channel` (string, mandatory): The channel name for terminal I/O.
 *   `project_id` (string, optional): The project ID associated with the terminal.
 
+### <a name="terminal_data"></a>`terminal_data`
+
+Streams real-time terminal output data from a running terminal session to connected clients. This event is automatically generated whenever the terminal process produces output (stdout/stderr). Generated by [`TerminalSession`](./session.py) through the terminal manager's session-aware messaging system.
+
+**Event-Specific Fields:**
+
+*   `channel` (string, mandatory): The terminal UUID identifying which terminal session produced this output. This matches the `terminal_id` from the corresponding `terminal_started` event.
+*   `data` (string, mandatory): The raw terminal output data. **See detailed description below.**
+
+**The `data` Field - Detailed Specification:**
+
+The `data` field contains the exact bytes output by the terminal process, decoded as a UTF-8 string with error handling:
+
+*   **Encoding**: UTF-8 with `errors="ignore"` - invalid UTF-8 sequences are silently dropped
+*   **Content**: Raw terminal output including:
+  - Regular command output (stdout)
+  - Error messages (stderr) - combined with stdout in PTY mode  
+  - ANSI escape sequences for colors, cursor positioning, screen clearing, etc.
+  - Control characters (newlines, tabs, backspace, etc.)
+  - Shell prompts and interactive application output
+*   **Buffering**: Data is read in 1024-byte chunks from the terminal process and sent immediately (no line buffering)
+*   **Binary Safety**: Binary data is handled via UTF-8 decoding with error tolerance
+*   **Size**: Individual chunks are typically ≤1024 characters, but can be smaller for real-time responsiveness
+
+**Examples of `data` content:**
+```
+"Hello, World!\n"                           // Simple command output
+"\u001b[32mSuccess\u001b[0m\n"             // ANSI colored text  
+"user@host:~/project$ "                     // Shell prompt
+"\u001b[2J\u001b[H"                         // Clear screen escape sequence
+"Progress: [████████████████████] 100%\r"   // Progress bar with carriage return
+```
+
+**Security Note**: The `device_id` field is automatically injected by the server based on the authenticated connection - the device cannot and should not specify its own ID. The `project_id` and `client_sessions` fields are added by the device's terminal manager for proper routing and filtering.
+
 ### <a name="terminal_exit"></a>`terminal_exit`
 
 Notifies the server that a terminal session has terminated. This can be due to the process ending or the session being stopped. Handled by [`terminal_start`](./terminal_handlers.py).
@@ -402,11 +447,33 @@ This event carries no additional fields.
 
 ### Terminal Data
 
-### <a name="terminal_data"></a>Terminal I/O Data
+### Terminal I/O Data Formats
+
+Terminal I/O data can be sent in two formats depending on the implementation:
+
+#### Modern Format (Recommended)
+
+Terminal data is sent as a proper [`terminal_data`](#terminal_data) event on the control channel (channel 0) with client session targeting support:
+
+```json
+{
+  "channel": 0,
+  "payload": {
+    "event": "terminal_data",
+    "channel": "<terminal_uuid>",
+    "data": "<terminal_output_string>",
+    "device_id": 123,
+    "project_id": "<project_uuid>",
+    "client_sessions": ["channel.abc123", "channel.def456"]
+  }
+}
+```
+
+This format follows the standard event structure with automatic system field injection (device_id, project_id, client_sessions) for proper routing and security.
 
-Terminal input/output data is sent directly on terminal channels (not on the control channel). Each terminal session has its own dedicated channel identified by the terminal's UUID.
+#### Legacy Format (Deprecated)
 
-**Terminal Data Format:**
+Terminal data sent directly on terminal channels (not on the control channel):
 
 ```json
 {
@@ -416,8 +483,9 @@ Terminal input/output data is sent directly on terminal channels (not on the con
 ```
 
 *   Terminal output is sent as raw string data in the payload
-*   Input to terminals is sent the same way but in the opposite direction
-*   No event wrapper is used for terminal I/O data
+*   Input to terminals is sent the same way but in the opposite direction  
+*   No event wrapper or client targeting is used
+*   This format broadcasts to all sessions for the device owner
 
 ### Server-Side Events
 

{portacode-0.3.12.dev8 → portacode-0.3.12.dev9}/portacode/connection/handlers/session.py

@@ -4,6 +4,7 @@ import asyncio
 import logging
 import os
 import sys
+import time
 import uuid
 from asyncio.subprocess import Process
 from pathlib import Path
@@ -13,6 +14,10 @@ from collections import deque
 if TYPE_CHECKING:
     from ..multiplex import Channel
 
+# Terminal data rate limiting configuration
+TERMINAL_DATA_RATE_LIMIT_MS = 200  # Minimum time between terminal_data events (milliseconds)
+TERMINAL_DATA_MAX_WAIT_MS = 1000   # Maximum time to wait before sending accumulated data (milliseconds)
+
 logger = logging.getLogger(__name__)
 
 _IS_WINDOWS = sys.platform.startswith("win")
@@ -44,6 +49,11 @@ class TerminalSession:
         self.terminal_manager = terminal_manager
         self._reader_task: Optional[asyncio.Task[None]] = None
         self._buffer: deque[str] = deque(maxlen=400)
+        
+        # Rate limiting for terminal_data events
+        self._last_send_time: float = 0
+        self._pending_data: str = ""
+        self._debounce_task: Optional[asyncio.Task[None]] = None
 
     async def start_io_forwarding(self) -> None:
         """Spawn background task that copies stdout/stderr to the channel."""
@@ -57,23 +67,9 @@ class TerminalSession:
                         break
                     text = data.decode(errors="ignore")
                     logging.getLogger("portacode.terminal").debug(f"[MUX] Terminal {self.id} output: {text!r}")
-                    self._buffer.append(text)
-                    try:
-                        # Send terminal data via control channel with client session targeting
-                        if self.terminal_manager:
-                            await self.terminal_manager._send_session_aware({
-                                "event": "terminal_data",
-                                "channel": self.id,
-                                "data": text,
-                                "project_id": self.project_id
-                            }, project_id=self.project_id)
-                        else:
-                            # Fallback to raw channel for backward compatibility
-                            await self.channel.send(text)
-                    except Exception as exc:
-                        logger.warning("Failed to forward terminal output: %s", exc)
-                        await asyncio.sleep(0.5)
-                        continue
+                    
+                    # Use rate-limited sending instead of immediate sending
+                    await self._handle_terminal_data(text)
             finally:
                 if self.proc and self.proc.returncode is None:
                     pass  # Keep alive across reconnects
@@ -129,6 +125,20 @@ class TerminalSession:
                     except asyncio.CancelledError:
                         pass
             
+            # Cancel and flush any pending terminal data
+            if self._debounce_task and not self._debounce_task.done():
+                logger.info("session.stop: Cancelling debounce task for session %s", self.id)
+                self._debounce_task.cancel()
+                try:
+                    await self._debounce_task
+                except asyncio.CancelledError:
+                    pass
+            
+            # Send any remaining pending data
+            if self._pending_data:
+                logger.info("session.stop: Flushing pending terminal data for session %s", self.id)
+                await self._flush_pending_data()
+            
             # Wait for process to exit
             if self.proc.returncode is None:
                 logger.info("session.stop: Waiting for process to exit for session %s", self.id)
@@ -143,6 +153,70 @@ class TerminalSession:
             logger.exception("session.stop: Error stopping session %s: %s", self.id, exc)
             raise
 
+    async def _send_terminal_data_now(self, data: str) -> None:
+        """Send terminal data immediately and update last send time."""
+        self._last_send_time = time.time()
+        
+        # Add to buffer for snapshots
+        self._buffer.append(data)
+        
+        try:
+            # Send terminal data via control channel with client session targeting
+            if self.terminal_manager:
+                await self.terminal_manager._send_session_aware({
+                    "event": "terminal_data",
+                    "channel": self.id,
+                    "data": data,
+                    "project_id": self.project_id
+                }, project_id=self.project_id)
+            else:
+                # Fallback to raw channel for backward compatibility
+                await self.channel.send(data)
+        except Exception as exc:
+            logger.warning("Failed to forward terminal output: %s", exc)
+
+    async def _flush_pending_data(self) -> None:
+        """Send accumulated pending data and reset pending buffer."""
+        if self._pending_data:
+            data_to_send = self._pending_data
+            self._pending_data = ""
+            await self._send_terminal_data_now(data_to_send)
+        
+        # Clear the debounce task
+        self._debounce_task = None
+
+    async def _handle_terminal_data(self, data: str) -> None:
+        """Handle new terminal data with rate limiting and debouncing."""
+        current_time = time.time()
+        time_since_last_send = (current_time - self._last_send_time) * 1000  # Convert to milliseconds
+        
+        # Add new data to pending buffer
+        self._pending_data += data
+        
+        # Cancel existing debounce task if any
+        if self._debounce_task and not self._debounce_task.done():
+            self._debounce_task.cancel()
+        
+        if time_since_last_send >= TERMINAL_DATA_RATE_LIMIT_MS:
+            # Enough time has passed, send immediately
+            await self._flush_pending_data()
+        else:
+            # Too soon, set up debounce timer
+            async def _debounce_timer():
+                try:
+                    # Wait for either the rate limit period or max wait time
+                    wait_time = min(
+                        (TERMINAL_DATA_RATE_LIMIT_MS - time_since_last_send) / 1000,
+                        TERMINAL_DATA_MAX_WAIT_MS / 1000
+                    )
+                    await asyncio.sleep(wait_time)
+                    await self._flush_pending_data()
+                except asyncio.CancelledError:
+                    # Timer was cancelled, another data event came in
+                    pass
+            
+            self._debounce_task = asyncio.create_task(_debounce_timer())
+
     def snapshot_buffer(self) -> str:
         """Return concatenated last buffer contents suitable for UI."""
         return "".join(self._buffer)
@@ -197,23 +271,9 @@ class WindowsTerminalSession(TerminalSession):
                     else:
                         text = data
                     logging.getLogger("portacode.terminal").debug(f"[MUX] Terminal {self.id} output: {text!r}")
-                    self._buffer.append(text)
-                    try:
-                        # Send terminal data via control channel with client session targeting
-                        if self.terminal_manager:
-                            await self.terminal_manager._send_session_aware({
-                                "event": "terminal_data",
-                                "channel": self.id,
-                                "data": text,
-                                "project_id": self.project_id
-                            }, project_id=self.project_id)
-                        else:
-                            # Fallback to raw channel for backward compatibility
-                            await self.channel.send(text)
-                    except Exception as exc:
-                        logger.warning("Failed to forward terminal output: %s", exc)
-                        await asyncio.sleep(0.5)
-                        continue
+                    
+                    # Use rate-limited sending instead of immediate sending
+                    await self._handle_terminal_data(text)
             finally:
                 if self._pty and self._pty.isalive():
                     self._pty.kill()
@@ -258,6 +318,20 @@ class WindowsTerminalSession(TerminalSession):
                     except asyncio.CancelledError:
                         pass
             
+            # Cancel and flush any pending terminal data
+            if self._debounce_task and not self._debounce_task.done():
+                logger.info("session.stop: Cancelling debounce task for Windows session %s", self.id)
+                self._debounce_task.cancel()
+                try:
+                    await self._debounce_task
+                except asyncio.CancelledError:
+                    pass
+            
+            # Send any remaining pending data
+            if self._pending_data:
+                logger.info("session.stop: Flushing pending terminal data for Windows session %s", self.id)
+                await self._flush_pending_data()
+            
             logger.info("session.stop: Successfully stopped Windows session %s", self.id)
                 
         except Exception as exc:

{portacode-0.3.12.dev8 → portacode-0.3.12.dev9}/portacode.egg-info/PKG-INFO

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