portacode 0.3.12.dev6__tar.gz → 0.3.12.dev7__tar.gz

portacode-0.3.12.dev7/.claude/agents/communication-manager.md

@@ -0,0 +1,5 @@
+---
+name: communication-manager
+description: Expert code protocol engineer. Accurately defines and improves simple yet straightforward and concise scallable communication protocols for websocket communication between devices and user sessions
+tools: Read, Grep, Glob
+---

portacode-0.3.12.dev7/.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "WebFetch(domain:stackoverflow.com)",
+      "Bash(docker-compose logs:*)"
+    ],
+    "deny": []
+  }
+}

{portacode-0.3.12.dev6 → portacode-0.3.12.dev7}/PKG-INFO

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

{portacode-0.3.12.dev6 → portacode-0.3.12.dev7}/docker-compose.yaml

@@ -32,30 +32,6 @@ services:
     volumes:
       - ./server/portacode_django:/app
 
-  portacode-gateway:
-    build:
-      context: ./server
-      dockerfile: Dockerfile
-    container_name: portacode-gateway
-    restart: unless-stopped
-    env_file:
-      - main.env
-    depends_on:
-      db:
-        condition: service_healthy
-      redis:
-        condition: service_started
-    ports:
-      - "8000:8000"
-    volumes:
-      - ./server:/app
-
-  redis:
-    image: redis:7-alpine
-    container_name: portacode-redis
-    restart: unless-stopped
-    ports:
-      - "6379:6379"
 
 volumes:
   pgdata: 

{portacode-0.3.12.dev6 → portacode-0.3.12.dev7}/portacode/_version.py

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

{portacode-0.3.12.dev6 → portacode-0.3.12.dev7}/portacode/connection/handlers/WEBSOCKET_PROTOCOL.md

@@ -2,6 +2,51 @@
 
 This document outlines the WebSocket communication protocol between the Portacode server and the connected client devices.
 
+## Table of Contents
+
+- [Raw Message Format](#raw-message-format)
+- [Actions](#actions)
+  - [Terminal Actions](#terminal-actions)
+    - [`terminal_start`](#terminal_start)
+    - [`terminal_send`](#terminal_send)
+    - [`terminal_stop`](#terminal_stop)
+    - [`terminal_list`](#terminal_list)
+  - [System Actions](#system-actions)
+    - [`system_info`](#system_info)
+  - [File Actions](#file-actions)
+    - [`file_read`](#file_read)
+    - [`file_write`](#file_write)
+    - [`directory_list`](#directory_list)
+    - [`file_info`](#file_info)
+    - [`file_delete`](#file_delete)
+  - [Client Session Management](#client-session-management)
+    - [`client_sessions_update`](#client_sessions_update)
+- [Events](#events)
+  - [Error Events](#error-events)
+    - [`error`](#error)
+  - [Terminal Events](#terminal-events)
+    - [`terminal_started`](#terminal_started)
+    - [`terminal_exit`](#terminal_exit)
+    - [`terminal_send_ack`](#terminal_send_ack)
+    - [`terminal_stopped`](#terminal_stopped)
+    - [`terminal_stop_completed`](#terminal_stop_completed)
+    - [`terminal_list`](#terminal_list-event)
+  - [System Events](#system-events)
+    - [`system_info`](#system_info-event)
+  - [File Events](#file-events)
+    - [`file_read_response`](#file_read_response)
+    - [`file_write_response`](#file_write_response)
+    - [`directory_list_response`](#directory_list_response)
+    - [`file_info_response`](#file_info_response)
+    - [`file_delete_response`](#file_delete_response)
+  - [Client Session Events](#client-session-events)
+    - [`request_client_sessions`](#request_client_sessions)
+  - [Terminal Data](#terminal-data)
+    - [Terminal I/O Data](#terminal_data)
+  - [Server-Side Events](#server-side-events)
+    - [`device_status`](#device_status)
+    - [`devices`](#devices)
+
 ## Raw Message Format
 
 All communication over the WebSocket is managed by a [multiplexer](./multiplex.py) that wraps every message in a JSON object with a `channel` and a `payload`. This allows for multiple virtual communication channels over a single connection.
@@ -41,7 +86,7 @@ Actions are messages sent from the server to the device, placed within the `payl
 
 *   `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): A channel name that the device will echo back in its response. The difference between this field and the `channel` field handled in the device connection [multiplexer](./multiplex.py), is simply that `channel` defines which application in the device is handeling this communication, while `reply_channel` defines which client session on the server side is communicating with the device. That's why the [multiplexer](./multiplex.py) for `channel` is here, while the multiplexer for the `reply_channel` is on the other side of the conversation. A lot like the source port number and destination port number in TCP/IP.
+*   `reply_channel` (string, optional): **DEPRECATED** - A channel name for backward compatibility. Modern implementations should use the `client_sessions` mechanism instead.
 
 ### `terminal_start`
 
@@ -177,6 +222,20 @@ Deletes a file or directory. Handled by [`file_delete`](./file_handlers.py).
 *   On success, the device will respond with a [`file_delete_response`](#file_delete_response) event.
 *   On error, a generic [`error`](#error) event is sent.
 
+### Client Session Management
+
+### `client_sessions_update`
+
+Sends updated client session information to the device. This is a special internal action used by the server to inform devices about connected client sessions.
+
+**Payload Fields:**
+
+*   `sessions` (array, mandatory): Array of client session objects containing connection information.
+
+**Responses:**
+
+This action does not generate a response event.
+
 ---
 
 ## Events
@@ -194,7 +253,8 @@ Events are messages sent from the device to the server, placed within the `paylo
 ```
 
 *   `event` (string, mandatory): The name of the event being sent (e.g., `terminal_started`).
-*   <a name="reply_channel"></a>`reply_channel` (string, optional): If the event is a direct response to an action that included a `reply_channel`, this field will contain the same value. This allows the server to correlate responses with their original requests.
+*   <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.
 
 ### <a name="error"></a>`error`
 
@@ -328,4 +388,53 @@ Confirms that a file or directory has been deleted in response to a `file_delete
 
 *   `path` (string, mandatory): The path of the deleted file or directory.
 *   `deleted_type` (string, mandatory): The type of the deleted item ("file" or "directory").
-*   `success` (boolean, mandatory): Indicates whether the deletion was successful.
+*   `success` (boolean, mandatory): Indicates whether the deletion was successful.
+
+### Client Session Events
+
+### <a name="request_client_sessions"></a>`request_client_sessions`
+
+Sent by the device to request the current list of connected client sessions from the server. This is an internal event used during device initialization and reconnection.
+
+**Event Fields:**
+
+This event carries no additional fields.
+
+### Terminal Data
+
+### <a name="terminal_data"></a>Terminal I/O Data
+
+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.
+
+**Terminal Data Format:**
+
+```json
+{
+  "channel": "<terminal_uuid>",
+  "payload": "<terminal_output_string>"
+}
+```
+
+*   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
+
+### Server-Side Events
+
+### <a name="device_status"></a>`device_status`
+
+Sent by the server to clients to indicate device online/offline status changes.
+
+**Event Fields:**
+
+*   `device` (object, mandatory): Device status information
+  *   `id` (integer, mandatory): Device ID
+  *   `online` (boolean, mandatory): Whether the device is online
+
+### <a name="devices"></a>`devices`
+
+Sent by the server to clients to provide initial device list snapshot.
+
+**Event Fields:**
+
+*   `devices` (array, mandatory): Array of device objects with status information

{portacode-0.3.12.dev6 → portacode-0.3.12.dev7}/portacode/connection/handlers/session.py

@@ -78,8 +78,15 @@ class TerminalSession:
             logger.warning("stdin pipe closed for terminal %s", self.id)
             return
         try:
-            self.proc.stdin.write(data.encode())
-            await self.proc.stdin.drain()
+            if hasattr(self.proc.stdin, 'write') and hasattr(self.proc.stdin, 'drain'):
+                # StreamWriter (pipe fallback)
+                self.proc.stdin.write(data.encode())
+                await self.proc.stdin.drain()
+            else:
+                # File object (PTY)
+                loop = asyncio.get_running_loop()
+                await loop.run_in_executor(None, self.proc.stdin.write, data.encode())
+                await loop.run_in_executor(None, self.proc.stdin.flush)
         except Exception as exc:
             logger.warning("Failed to write to terminal %s: %s", self.id, exc)
 
@@ -301,11 +308,8 @@ class SessionManager:
                 protocol = asyncio.StreamReaderProtocol(reader)
                 await loop.connect_read_pipe(lambda: protocol, os.fdopen(master_fd, "rb", buffering=0))
                 proc.stdout = reader
-                # Use writer for stdin
-                writer_transport, writer_protocol = await loop.connect_write_pipe(
-                    lambda: asyncio.Protocol(), os.fdopen(master_fd, "wb", buffering=0)
-                )
-                proc.stdin = asyncio.StreamWriter(writer_transport, writer_protocol, reader, loop)
+                # Use writer for stdin - create a simple file-like wrapper
+                proc.stdin = os.fdopen(master_fd, "wb", buffering=0)
             except Exception:
                 logger.warning("Failed to allocate PTY, falling back to pipes")
                 proc = await asyncio.create_subprocess_exec(

{portacode-0.3.12.dev6 → portacode-0.3.12.dev7}/portacode/connection/terminal.py

@@ -92,7 +92,12 @@ class ClientSessionManager:
         
         target_sessions = []
         for session in self._client_sessions.values():
-            # If project_id specified, filter by project
+            # Dashboard sessions should receive ALL events regardless of project_id
+            if session.get("connection_type") == "dashboard":
+                target_sessions.append(session.get("channel_name"))
+                continue
+            
+            # For project sessions, filter by project_id if specified
             if project_id and session.get("project_id") != project_id:
                 continue
             target_sessions.append(session.get("channel_name"))
@@ -241,13 +246,17 @@ class TerminalManager:
                 # Handle client sessions update directly (special case)
                 if cmd == "client_sessions_update":
                     sessions = message.get("sessions", [])
-                    logger.info("terminal_manager: Handling client_sessions_update with %d sessions", len(sessions))
+                    logger.info("terminal_manager: 🔔 RECEIVED client_sessions_update with %d sessions", len(sessions))
+                    logger.debug("terminal_manager: Session details: %s", sessions)
                     self._client_session_manager.update_sessions(sessions)
-                    logger.info("terminal_manager: Updated client sessions (%d sessions)", len(sessions))
+                    logger.info("terminal_manager: ✅ Updated client sessions (%d sessions)", len(sessions))
                     
                     # Auto-send initial data to new clients
                     if len(sessions) > 0:
+                        logger.info("terminal_manager: 🚀 Triggering auto-send of initial data to clients")
                         await self._send_initial_data_to_clients()
+                    else:
+                        logger.info("terminal_manager: ℹ️ No sessions to send data to")
                     continue
                 
                 # Dispatch command through registry
@@ -263,37 +272,53 @@ class TerminalManager:
 
     async def _send_initial_data_to_clients(self):
         """Send initial system info and terminal list to connected clients."""
-        logger.info("terminal_manager: Sending initial data to connected clients")
+        logger.info("terminal_manager: 📤 Starting to send initial data to connected clients")
         
         try:
             # Send system_info
-            logger.info("terminal_manager: Sending system_info to clients")
+            logger.info("terminal_manager: 📊 Dispatching system_info command")
             await self._command_registry.dispatch("system_info", {}, None)
+            logger.info("terminal_manager: ✅ system_info dispatch completed")
             
             # Send terminal_list for each project that has connected clients
-            logger.info("terminal_manager: Sending terminal_list to clients")
+            logger.info("terminal_manager: 📋 Preparing to send terminal_list to clients")
             
             # Get unique project IDs from connected clients
             project_ids = set()
-            for session in self._client_session_manager.get_sessions().values():
+            all_sessions = self._client_session_manager.get_sessions()
+            logger.info(f"terminal_manager: Analyzing {len(all_sessions)} client sessions for project IDs")
+            
+            for session in all_sessions.values():
                 project_id = session.get("project_id")
+                connection_type = session.get("connection_type", "unknown")
+                logger.debug(f"terminal_manager: Session {session.get('channel_name')}: project_id={project_id}, type={connection_type}")
                 if project_id:
                     project_ids.add(project_id)
             
+            logger.info(f"terminal_manager: Found {len(project_ids)} unique project IDs: {list(project_ids)}")
+            
             # Send terminal_list for each project, plus one without project_id for general sessions
             if not project_ids:
                 # No specific projects, send general terminal_list
+                logger.info("terminal_manager: 📋 Dispatching general terminal_list (no specific projects)")
                 await self._command_registry.dispatch("terminal_list", {}, None)
+                logger.info("terminal_manager: ✅ General terminal_list dispatch completed")
             else:
                 # Send terminal_list for each project
                 for project_id in project_ids:
+                    logger.info(f"terminal_manager: 📋 Dispatching terminal_list for project {project_id}")
                     await self._command_registry.dispatch("terminal_list", {"project_id": project_id}, None)
+                    logger.info(f"terminal_manager: ✅ Project {project_id} terminal_list dispatch completed")
                     
                 # Also send general terminal_list for dashboard connections
+                logger.info("terminal_manager: 📋 Dispatching general terminal_list for dashboard connections")
                 await self._command_registry.dispatch("terminal_list", {}, None)
+                logger.info("terminal_manager: ✅ General terminal_list for dashboard dispatch completed")
+            
+            logger.info("terminal_manager: 🎉 All initial data sent successfully")
                     
         except Exception as exc:
-            logger.exception("terminal_manager: Error sending initial data to clients: %s", exc)
+            logger.exception("terminal_manager: ❌ Error sending initial data to clients: %s", exc)
 
     # ------------------------------------------------------------------
     # Extension API

{portacode-0.3.12.dev6 → portacode-0.3.12.dev7}/portacode.egg-info/PKG-INFO

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

{portacode-0.3.12.dev6 → portacode-0.3.12.dev7}/portacode.egg-info/SOURCES.txt

@@ -10,6 +10,7 @@ pyproject.toml
 restore.sh
 setup.py
 .claude/settings.local.json
+.claude/agents/communication-manager.md
 portacode/README.md
 portacode/__init__.py
 portacode/__main__.py

portacode-0.3.12.dev6/.claude/settings.local.json

@@ -1,8 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "WebFetch(domain:stackoverflow.com)"
-    ],
-    "deny": []
-  }
-}