portacode 1.3.26__tar.gz → 1.3.27.dev0__tar.gz

{portacode-1.3.26 → portacode-1.3.27.dev0}/.claude/settings.local.json

@@ -17,7 +17,6 @@
       "Bash(git -C /home/menas/testing_folder status --porcelain)",
       "Bash(docker-compose restart:*)"
     ],
-    "deny": [],
-    "defaultMode": "acceptEdits"
+    "deny": []
   }
 }

portacode-1.3.27.dev0/MANIFEST.in

@@ -0,0 +1,3 @@
+prune server
+exclude .pypirc
+recursive-include portacode/static *.js *.html

{portacode-1.3.26 → portacode-1.3.27.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: portacode
-Version: 1.3.26
+Version: 1.3.27.dev0
 Summary: Portacode CLI client and SDK
 Home-page: https://github.com/portacode/portacode
 Author: Meena Erian
@@ -23,6 +23,7 @@ Requires-Dist: GitPython>=3.1.45
 Requires-Dist: watchdog>=3.0
 Requires-Dist: diff-match-patch>=20230430
 Requires-Dist: Pygments>=2.14.0
+Requires-Dist: ntplib>=0.4.0
 Provides-Extra: dev
 Requires-Dist: black; extra == "dev"
 Requires-Dist: flake8; extra == "dev"

{portacode-1.3.26 → portacode-1.3.27.dev0}/portacode/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '1.3.26'
-__version_tuple__ = version_tuple = (1, 3, 26)
+__version__ = version = '1.3.27.dev0'
+__version_tuple__ = version_tuple = (1, 3, 27, 'dev0')
 
 __commit_id__ = commit_id = None

{portacode-1.3.26 → portacode-1.3.27.dev0}/portacode/connection/handlers/WEBSOCKET_PROTOCOL.md

@@ -1,10 +1,38 @@
 # WebSocket Communication Protocol
 
-This document outlines the WebSocket communication protocol between the Portacode server and the connected client devices.
+This document outlines the WebSocket communication protocol used in Portacode. The protocol involves three main participants: client sessions, the Portacode server, and devices.
+
+## Architecture Overview
+
+```
+┌─────────────┐          ┌──────────────────┐          ┌─────────────────────────┐
+│   Client    │          │   Portacode      │          │        Device           │
+│   Session   │◄────────►│    Server        │◄────────►│ (Portacode CLI or       │
+│             │          │                  │          │  Python package)        │
+└─────────────┘          └──────────────────┘          └─────────────────────────┘
+     │                           │                                  │
+     │                           │                                  │
+  Client-Side              Acts as middleman                  Device-Side
+  Protocol                 - Routes messages                  Protocol
+                          - Manages sessions
+```
+
+The Portacode server acts as a **routing middleman** between client sessions and devices. It manages routing fields that are included in messages to specify routing destinations but are removed or transformed before reaching the final recipient:
+
+**Routing Fields Behavior:**
+
+- **`device_id`** (Client → Server): Client includes this to specify which device to route to. Server uses it for routing, then **removes it** before forwarding to the device (the device knows the message is for them). Server **adds it** when routing device responses back to clients (so clients know which device the message came from).
+
+- **`client_sessions`** (Device → Server): Device includes this to specify which client session(s) to route to. Server uses it for routing, then **removes it** before forwarding to clients (clients just receive the message without seeing routing metadata).
+
+- **`source_client_session`** (Server → Device): Server **adds this** when forwarding client commands to devices (so device knows which client sent the command and can target responses back). Clients never include this field.
+
+This document describes the complete protocol for communicating with devices through the server, guiding app developers on how to get their client sessions to communicate with devices.
 
 ## Table of Contents
 
-- [Raw Message Format](#raw-message-format)
+- [Raw Message Format On Device Side](#raw-message-format-on-device-side)
+- [Raw Message Format On Client Side](#raw-message-format-on-client-side)
 - [Actions](#actions)
   - [Terminal Actions](#terminal-actions)
     - [`terminal_start`](#terminal_start)
@@ -82,11 +110,11 @@ This document outlines the WebSocket communication protocol between the Portacod
     - [`device_status`](#device_status)
     - [`devices`](#devices)
 
-## Raw Message Format
+## Raw Message Format On Device Side
 
-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.
+Communication between the server and devices uses 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 WebSocket connection.
 
-**Raw Message Structure:**
+**Device-Side Message Structure:**
 
 ```json
 {
@@ -97,9 +125,99 @@ All communication over the WebSocket is managed by a [multiplexer](./multiplex.p
 }
 ```
 
-*   `channel` (string|integer, mandatory): Identifies the virtual channel the message is for. When sending control commands to the device, they should be sent to channel 0 and when the device responsed to such control commands or sends system events, they will also be send on the zero channel. When a terminal session is created in the device, it is assigned a uuid, the uuid becomes the channel for communicating to that specific terminal.
+**Field Descriptions:**
+
+*   `channel` (string|integer, mandatory): Identifies the virtual channel the message is for. When sending control commands to the device, they should be sent to channel 0 and when the device responds to such control commands or sends system events, they will also be sent on the zero channel. When a terminal session is created in the device, it is assigned a uuid, the uuid becomes the channel for communicating to that specific terminal.
 *   `payload` (object, mandatory): The content of the message, which will be either an [Action](#actions) or an [Event](#events) object.
 
+**Channel Types:**
+- **Channel 0** (control channel): Used for system commands, terminal management, file operations, and project state management
+- **Channel UUID** (terminal channel): Used for terminal I/O to a specific terminal session
+
+---
+
+## Raw Message Format On Client Side
+
+Client sessions communicate with the server using a unified message format with the same field names as the device protocol, plus routing information.
+
+**Client-Side Message Structure (Client → Server):**
+
+```json
+{
+  "device_id": <number>,
+  "channel": <number|string>,
+  "payload": {
+    "cmd": "<command_name>",
+    ...command-specific fields
+  }
+}
+```
+
+**Field Descriptions:**
+
+*   `device_id` (number, mandatory): Routing field - specifies which device to send the message to. The server validates that the client has access to this device before forwarding.
+*   `channel` (number|string, mandatory): Same as device protocol - the target channel (0 for control, UUID for terminal). Uses the same field name for consistency.
+*   `payload` (object, mandatory): Same as device protocol - the command payload. Uses the same field name for consistency.
+
+**Server Transformation (Client → Device):**
+
+When the server receives a client message, it:
+1. Validates client has access to the specified `device_id`
+2. **Removes** `device_id` from the message (device doesn't need to be told "this is for you")
+3. **Adds** `source_client_session` to the payload (so device knows which client to respond to)
+4. Forwards to device: `{channel, payload: {...payload, source_client_session}}`
+
+**Server Transformation (Device → Client):**
+
+When the server receives a device response, it:
+1. **Adds** `device_id` to the message (so client knows which device it came from, based on authenticated device connection)
+2. **Removes** `client_sessions` routing metadata (clients don't need to see routing info)
+3. Routes to appropriate client session(s)
+
+**Server Response Format (Server → Client):**
+
+```json
+{
+  "event": "<event_name>",
+  "device_id": <number>,
+  ...event-specific fields
+}
+```
+
+**Field Descriptions:**
+
+*   `event` (string, mandatory): The name of the event being sent.
+*   `device_id` (number, mandatory): Authenticated field - identifies which device the event came from (added by server based on authenticated device connection).
+*   Additional fields depend on the specific event type.
+
+**Example Client Message:**
+```json
+{
+  "device_id": 42,
+  "channel": 0,
+  "payload": {
+    "cmd": "terminal_start",
+    "shell": "bash",
+    "cwd": "/home/user/project"
+  }
+}
+```
+
+**Example Server Response:**
+```json
+{
+  "event": "terminal_started",
+  "device_id": 42,
+  "terminal_id": "uuid-1234-5678",
+  "channel": "uuid-1234-5678",
+  "pid": 12345
+}
+```
+
+**Note:** The server acts as a translator between the client-side and device-side protocols:
+- When a client sends a command, the server transforms it from the client format to the device format
+- When a device sends an event, the server adds the `device_id` and routes it to the appropriate client sessions
+
 ---
 
 ## Actions
@@ -110,18 +228,18 @@ Actions are messages sent from the server to the device, placed within the `payl
 
 ```json
 {
-  "command": "<command_name>",
-  "payload": {
-    "arg1": "value1",
-    "...": "..."
-  },
+  "cmd": "<command_name>",
+  "arg1": "value1",
+  "arg2": "value2",
   "source_client_session": "channel.abc123"
 }
 ```
 
-*   `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.
+**Field Descriptions:**
+
+*   `cmd` (string, mandatory): The name of the action to be executed (e.g., `terminal_start`, `file_read`, `system_info`).
 *   `source_client_session` (string, mandatory): The channel name of the client session that originated this command. This field is automatically added by the server and allows devices to identify which specific client sent the command.
+*   Additional fields depend on the specific command (see individual command documentation below).
 
 **Note**: Actions do not require targeting information - responses are automatically routed using the client session management system.
 

{portacode-1.3.26 → portacode-1.3.27.dev0}/portacode/connection/handlers/base.py

@@ -107,18 +107,22 @@ class AsyncHandler(BaseHandler):
     
     async def handle(self, message: Dict[str, Any], reply_channel: Optional[str] = None) -> None:
         """Handle the command by executing it and sending the response."""
-        logger.info("handler: Processing command %s with reply_channel=%s", 
+        logger.info("handler: Processing command %s with reply_channel=%s",
                    self.command_name, reply_channel)
-        
+
         try:
             response = await self.execute(message)
             logger.info("handler: Command %s executed successfully", self.command_name)
-            
+
             # Handle cases where execute() sends responses directly and returns None
             if response is not None:
+                # Automatically copy request_id if present in the incoming message
+                if "request_id" in message and "request_id" not in response:
+                    response["request_id"] = message["request_id"]
+
                 # Extract project_id from response for session targeting
                 project_id = response.get("project_id")
-                logger.info("handler: %s response project_id=%s, response=%s", 
+                logger.info("handler: %s response project_id=%s, response=%s",
                            self.command_name, project_id, response)
                 await self.send_response(response, reply_channel, project_id)
             else:
@@ -150,7 +154,11 @@ class SyncHandler(BaseHandler):
         try:
             loop = asyncio.get_running_loop()
             response = await loop.run_in_executor(None, self.execute, message)
-            
+
+            # Automatically copy request_id if present in the incoming message
+            if "request_id" in message and "request_id" not in response:
+                response["request_id"] = message["request_id"]
+
             # Extract project_id from response for session targeting
             project_id = response.get("project_id")
             await self.send_response(response, reply_channel, project_id)

{portacode-1.3.26 → portacode-1.3.27.dev0}/portacode/connection/handlers/file_handlers.py

@@ -382,22 +382,18 @@ class ContentRequestHandler(AsyncHandler):
     async def execute(self, message: Dict[str, Any]) -> None:
         """Return content by hash if available, chunked for large content."""
         content_hash = message.get("content_hash")
-        request_id = message.get("request_id")
         source_client_session = message.get("source_client_session")
-        
+
         if not content_hash:
             raise ValueError("content_hash parameter is required")
-        if not request_id:
-            raise ValueError("request_id parameter is required")
-        
+
         # Check if content is in cache
         content = _content_cache.get(content_hash)
-        
+
         if content is not None:
-            # Create base response
+            # Create base response (request_id will be added automatically by base class)
             base_response = {
                 "event": "content_response",
-                "request_id": request_id,
                 "content_hash": content_hash,
                 "success": True,
             }
@@ -411,10 +407,9 @@ class ContentRequestHandler(AsyncHandler):
             
             logger.info(f"Sent content response in {len(responses)} chunk(s) for hash: {content_hash[:16]}...")
         else:
-            # Content not found in cache
+            # Content not found in cache (request_id will be added automatically by base class)
             response = {
                 "event": "content_response",
-                "request_id": request_id,
                 "content_hash": content_hash,
                 "content": None,
                 "success": False,

{portacode-1.3.26 → portacode-1.3.27.dev0}/portacode/connection/handlers/project_state/handlers.py

@@ -683,9 +683,8 @@ class ProjectStateDiffContentHandler(AsyncHandler):
         from_hash = message.get("from_hash")
         to_hash = message.get("to_hash")
         content_type = message.get("content_type")  # 'original', 'modified', 'html_diff'
-        request_id = message.get("request_id")
         source_client_session = message.get("source_client_session")
-        
+
         # Validate required fields
         if not server_project_id:
             raise ValueError("project_id is required")
@@ -697,8 +696,6 @@ class ProjectStateDiffContentHandler(AsyncHandler):
             raise ValueError("to_ref is required")
         if not content_type:
             raise ValueError("content_type is required")
-        if not request_id:
-            raise ValueError("request_id is required")
         if not source_client_session:
             raise ValueError("source_client_session is required")
         
@@ -816,9 +813,12 @@ class ProjectStateDiffContentHandler(AsyncHandler):
                 "from_ref": from_ref,
                 "to_ref": to_ref,
                 "content_type": content_type,
-                "request_id": request_id,
                 "success": success
             }
+
+            # Add request_id if present in original message
+            if "request_id" in message:
+                base_response["request_id"] = message["request_id"]
             
             if from_hash:
                 base_response["from_hash"] = from_hash
@@ -850,9 +850,12 @@ class ProjectStateDiffContentHandler(AsyncHandler):
                 "from_ref": from_ref,
                 "to_ref": to_ref,
                 "content_type": content_type,
-                "request_id": request_id,
                 "success": False,
                 "error": str(e),
                 "chunked": False
             }
+
+            # Add request_id if present in original message
+            if "request_id" in message:
+                error_response["request_id"] = message["request_id"]
             await self.send_response(error_response, project_id=server_project_id)

portacode-1.3.27.dev0/portacode/static/js/test-ntp-clock.html

@@ -0,0 +1,63 @@
+<!DOCTYPE html>
+<html>
+<head>
+    <title>NTP Clock Test</title>
+    <style>
+        body {
+            font-family: monospace;
+            padding: 20px;
+            background: #1e1e1e;
+            color: #d4d4d4;
+        }
+        h1 {
+            color: #4ec9b0;
+        }
+        #status {
+            background: #252526;
+            padding: 15px;
+            border-radius: 5px;
+            border: 1px solid #3e3e42;
+        }
+        .synced {
+            color: #4ec9b0;
+        }
+        .not-synced {
+            color: #f48771;
+        }
+        .label {
+            color: #9cdcfe;
+            font-weight: bold;
+        }
+    </style>
+</head>
+<body>
+    <h1>NTP Clock Test - time.cloudflare.com</h1>
+    <div id="status"></div>
+    <script type="module">
+        import ntpClock from './utils/ntp-clock.js';
+
+        function updateDisplay() {
+            const status = ntpClock.getStatus();
+            const syncClass = status.isSynced ? 'synced' : 'not-synced';
+
+            document.getElementById('status').innerHTML = `
+                <p><span class="label">Sync Status:</span> <span class="${syncClass}">${status.isSynced ? '✅ SYNCED' : '❌ NOT SYNCED'}</span></p>
+                <p><span class="label">NTP Server:</span> ${status.server}</p>
+                <p><span class="label">NTP Time:</span> ${ntpClock.nowISO() || 'null (not synced)'}</p>
+                <p><span class="label">Local Time:</span> ${new Date().toISOString()}</p>
+                <p><span class="label">Offset:</span> ${status.offset !== null ? status.offset.toFixed(2) + 'ms' : 'null'}</p>
+                <p><span class="label">Last Sync:</span> ${status.lastSync || 'Never'}</p>
+                <p><span class="label">Time Since Sync:</span> ${status.timeSinceSync ? (status.timeSinceSync / 1000).toFixed(0) + 's' : 'N/A'}</p>
+            `;
+        }
+
+        // Update display every 100ms
+        setInterval(updateDisplay, 100);
+
+        // Log status to console every 5 seconds
+        setInterval(() => {
+            console.log('NTP Clock Status:', ntpClock.getStatus());
+        }, 5000);
+    </script>
+</body>
+</html>

portacode-1.3.27.dev0/portacode/static/js/utils/ntp-clock.js

@@ -0,0 +1,139 @@
+/**
+ * NTP Clock - Synchronized time source for distributed tracing
+ *
+ * Provides NTP-synchronized timestamps for accurate distributed tracing.
+ * Uses HTTP-based time API since browsers cannot make UDP NTP requests.
+ *
+ * IMPORTANT: All entities (client, server, device) MUST sync to time.cloudflare.com
+ * If sync fails, timestamps will be null to indicate sync failure.
+ */
+class NTPClock {
+    constructor() {
+        this.ntpServer = 'time.cloudflare.com';  // Hardcoded - no fallback
+        this.offset = null;  // Offset from local clock to NTP time (milliseconds), null if not synced
+        this.lastSync = null;
+        this.syncInterval = 5 * 60 * 1000;  // Re-sync every 5 minutes
+        this._syncInProgress = false;
+        this._syncAttempts = 0;
+        this._maxSyncAttempts = 3;
+    }
+
+    /**
+     * Parse Cloudflare trace response to extract timestamp
+     */
+    _parseCloudflareTime(text) {
+        const tsMatch = text.match(/ts=([\d.]+)/);
+        if (tsMatch) {
+            return parseFloat(tsMatch[1]) * 1000;  // Convert to milliseconds
+        }
+        throw new Error('Failed to parse Cloudflare timestamp');
+    }
+
+    /**
+     * Synchronize with Cloudflare NTP via HTTP
+     */
+    async sync() {
+        if (this._syncInProgress) {
+            console.log('NTP sync already in progress, skipping');
+            return false;
+        }
+
+        this._syncInProgress = true;
+        this._syncAttempts++;
+
+        try {
+            const t0 = performance.now();
+            const response = await fetch('https://cloudflare.com/cdn-cgi/trace');
+            const t1 = performance.now();
+
+            const text = await response.text();
+            const serverTime = this._parseCloudflareTime(text);
+
+            const localTime = Date.now();
+            const latency = (t1 - t0) / 2;  // Estimate one-way latency
+
+            // Calculate offset accounting for latency
+            this.offset = serverTime - localTime + latency;
+            this.lastSync = Date.now();
+
+            console.log(
+                `✅ NTP sync successful: offset=${this.offset.toFixed(2)}ms, ` +
+                `latency=${latency.toFixed(2)}ms, server=${this.ntpServer}`
+            );
+
+            this._syncAttempts = 0;  // Reset on success
+            return true;
+
+        } catch (error) {
+            console.warn(`❌ NTP sync failed (attempt ${this._syncAttempts}/${this._maxSyncAttempts}):`, error);
+
+            // If all attempts fail, set offset to null to indicate sync failure
+            if (this._syncAttempts >= this._maxSyncAttempts) {
+                this.offset = null;
+                this.lastSync = null;
+                console.error(`⚠️  NTP sync failed after ${this._maxSyncAttempts} attempts. Timestamps will be null.`);
+                this._syncAttempts = 0;
+            }
+
+            return false;
+        } finally {
+            this._syncInProgress = false;
+        }
+    }
+
+    /**
+     * Get current NTP-synchronized timestamp in milliseconds since epoch
+     * Returns null if not synced
+     */
+    now() {
+        if (this.offset === null) {
+            return null;
+        }
+        return Date.now() + this.offset;
+    }
+
+    /**
+     * Get current NTP-synchronized timestamp in ISO format
+     * Returns null if not synced
+     */
+    nowISO() {
+        const ts = this.now();
+        if (ts === null) {
+            return null;
+        }
+        return new Date(ts).toISOString();
+    }
+
+    /**
+     * Get sync status for debugging
+     */
+    getStatus() {
+        return {
+            server: this.ntpServer,
+            offset: this.offset,
+            lastSync: this.lastSync ? new Date(this.lastSync).toISOString() : null,
+            timeSinceSync: this.lastSync ? Date.now() - this.lastSync : null,
+            isSynced: this.offset !== null
+        };
+    }
+
+    /**
+     * Start automatic periodic synchronization
+     */
+    startAutoSync() {
+        // Initial sync
+        this.sync();
+
+        // Periodic re-sync
+        setInterval(() => {
+            console.log('🔄 Starting periodic NTP sync...');
+            this.sync();
+        }, this.syncInterval);
+    }
+}
+
+// Global instance - auto-starts sync
+const ntpClock = new NTPClock();
+ntpClock.startAutoSync();
+
+export default ntpClock;

portacode-1.3.27.dev0/portacode/utils/__init__.py

@@ -0,0 +1 @@
+"""Portacode utility modules."""

portacode-1.3.27.dev0/portacode/utils/ntp_clock.py

@@ -0,0 +1,151 @@
+"""
+NTP Clock - Synchronized time source for distributed tracing
+
+Provides NTP-synchronized timestamps for accurate distributed tracing.
+Thread-safe implementation with automatic periodic synchronization.
+
+IMPORTANT: All entities (client, server, device) MUST sync to time.cloudflare.com
+If sync fails, timestamps will be None to indicate sync failure.
+"""
+import ntplib
+import time
+import threading
+import logging
+from datetime import datetime, timezone
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+
+class NTPClock:
+    """Thread-safe NTP-synchronized clock."""
+
+    def __init__(self, ntp_server: str = 'time.cloudflare.com'):
+        """Initialize NTP clock.
+
+        Args:
+            ntp_server: NTP server hostname (default: time.cloudflare.com, hardcoded, no fallback)
+        """
+        self.ntp_server = ntp_server
+        self.offset: Optional[float] = None  # Offset from local clock to NTP time (seconds), None if not synced
+        self.last_sync: Optional[float] = None
+        self.sync_interval = 300  # Re-sync every 5 minutes
+        self._lock = threading.Lock()
+        self._sync_in_progress = False
+        self._client = ntplib.NTPClient()
+        self._sync_attempts = 0
+        self._max_sync_attempts = 3
+
+    def sync(self) -> bool:
+        """Synchronize with NTP server.
+
+        Returns:
+            True if sync successful, False otherwise
+        """
+        if self._sync_in_progress:
+            logger.debug("NTP sync already in progress, skipping")
+            return False
+
+        self._sync_in_progress = True
+
+        try:
+            self._sync_attempts += 1
+            response = self._client.request(self.ntp_server, version=3, timeout=2)
+
+            with self._lock:
+                # Offset is difference between NTP time and local time
+                self.offset = response.offset
+                self.last_sync = time.time()
+
+            logger.info(
+                f"✅ NTP sync successful: offset={self.offset*1000:.2f}ms, "
+                f"latency={response.delay*1000:.2f}ms, server={self.ntp_server}"
+            )
+
+            self._sync_attempts = 0  # Reset on success
+            return True
+
+        except Exception as e:
+            logger.warning(f"❌ NTP sync failed (attempt {self._sync_attempts}/{self._max_sync_attempts}): {e}")
+
+            # If all attempts fail, set offset to None to indicate sync failure
+            if self._sync_attempts >= self._max_sync_attempts:
+                with self._lock:
+                    self.offset = None
+                    self.last_sync = None
+                logger.error(f"⚠️  NTP sync failed after {self._max_sync_attempts} attempts. Timestamps will be None.")
+                self._sync_attempts = 0
+
+            return False
+
+        finally:
+            self._sync_in_progress = False
+
+    def now(self) -> Optional[float]:
+        """Get current NTP-synchronized timestamp (seconds since epoch).
+
+        Returns:
+            Timestamp in seconds (Unix epoch) or None if not synced
+        """
+        with self._lock:
+            if self.offset is None:
+                return None
+            return time.time() + self.offset
+
+    def now_ms(self) -> Optional[int]:
+        """Get current NTP-synchronized timestamp in milliseconds.
+
+        Returns:
+            Timestamp in milliseconds (Unix epoch) or None if not synced
+        """
+        ts = self.now()
+        if ts is None:
+            return None
+        return int(ts * 1000)
+
+    def now_iso(self) -> Optional[str]:
+        """Get current NTP-synchronized timestamp in ISO format.
+
+        Returns:
+            ISO 8601 formatted timestamp with UTC timezone or None if not synced
+        """
+        ts = self.now()
+        if ts is None:
+            return None
+        dt = datetime.fromtimestamp(ts, tz=timezone.utc)
+        return dt.isoformat()
+
+    def get_status(self) -> dict:
+        """Get sync status for debugging.
+
+        Returns:
+            Dictionary with sync status information
+        """
+        with self._lock:
+            return {
+                'server': self.ntp_server,
+                'offset_ms': self.offset * 1000 if self.offset is not None else None,
+                'last_sync': datetime.fromtimestamp(self.last_sync, tz=timezone.utc).isoformat() if self.last_sync else None,
+                'time_since_sync_sec': time.time() - self.last_sync if self.last_sync else None,
+                'is_synced': self.offset is not None
+            }
+
+    def start_auto_sync(self):
+        """Start automatic periodic synchronization in background thread."""
+        # Initial sync
+        self.sync()
+
+        def _sync_loop():
+            while True:
+                time.sleep(self.sync_interval)
+                logger.info("🔄 Starting periodic NTP sync...")
+                self.sync()
+
+        thread = threading.Thread(target=_sync_loop, daemon=True, name='ntp-sync')
+        thread.start()
+        logger.info(f"Started NTP auto-sync thread (interval: {self.sync_interval}s, server: {self.ntp_server})")
+
+
+# Global instance - auto-starts sync on import
+ntp_clock = NTPClock()
+ntp_clock.start_auto_sync()

{portacode-1.3.26 → portacode-1.3.27.dev0}/portacode.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: portacode
-Version: 1.3.26
+Version: 1.3.27.dev0
 Summary: Portacode CLI client and SDK
 Home-page: https://github.com/portacode/portacode
 Author: Meena Erian
@@ -23,6 +23,7 @@ Requires-Dist: GitPython>=3.1.45
 Requires-Dist: watchdog>=3.0
 Requires-Dist: diff-match-patch>=20230430
 Requires-Dist: Pygments>=2.14.0
+Requires-Dist: ntplib>=0.4.0
 Provides-Extra: dev
 Requires-Dist: black; extra == "dev"
 Requires-Dist: flake8; extra == "dev"

{portacode-1.3.26 → portacode-1.3.27.dev0}/portacode.egg-info/SOURCES.txt

@@ -13,6 +13,7 @@ restore.sh
 run_tests.py
 setup.py
 test.sh
+test_request_id.py
 .claude/settings.local.json
 .claude/agents/communication-manager.md
 portacode/README.md
@@ -56,6 +57,10 @@ portacode/connection/handlers/project_state/handlers.py
 portacode/connection/handlers/project_state/manager.py
 portacode/connection/handlers/project_state/models.py
 portacode/connection/handlers/project_state/utils.py
+portacode/static/js/test-ntp-clock.html
+portacode/static/js/utils/ntp-clock.js
+portacode/utils/__init__.py
+portacode/utils/ntp_clock.py
 test_modules/README.md
 test_modules/__init__.py
 test_modules/test_device_online.py

{portacode-1.3.26 → portacode-1.3.27.dev0}/portacode.egg-info/requires.txt

@@ -9,6 +9,7 @@ GitPython>=3.1.45
 watchdog>=3.0
 diff-match-patch>=20230430
 Pygments>=2.14.0
+ntplib>=0.4.0
 
 [:platform_system == "Windows"]
 pywinpty>=2.0

{portacode-1.3.26 → portacode-1.3.27.dev0}/setup.py

@@ -17,6 +17,12 @@ setup(
     author_email="hi@menas.pro",
     url="https://github.com/portacode/portacode",
     packages=find_packages(exclude=("tests", "server")),
+    package_data={
+        "portacode": [
+            "static/js/**/*.js",
+            "static/js/**/*.html",
+        ],
+    },
     python_requires=">=3.8",
     install_requires=[
         "click>=8.0",
@@ -31,6 +37,7 @@ setup(
         "watchdog>=3.0",
         "diff-match-patch>=20230430",
         "Pygments>=2.14.0",
+        "ntplib>=0.4.0",
     ],
     extras_require={
         "dev": ["black", "flake8", "pytest"],

portacode-1.3.27.dev0/test_request_id.py

@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+"""
+Test request_id automatic passthrough in handlers
+"""
+import asyncio
+import sys
+import os
+
+# Add parent directory to path
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from portacode.connection.handlers.terminal_handlers import TerminalStartHandler
+from portacode.connection.handlers.file_handlers import ContentRequestHandler
+
+
+class MockChannel:
+    """Mock channel for testing"""
+    def __init__(self):
+        self.sent_messages = []
+
+    async def send(self, data):
+        self.sent_messages.append(data)
+        print(f"📤 Sent: {data}")
+
+
+class MockSessionManager:
+    """Mock session manager"""
+    async def create_session(self, shell=None, cwd=None, project_id=None):
+        return {
+            "terminal_id": "test_terminal_123",
+            "channel": "test_channel_456",
+            "pid": 12345,
+            "shell": shell or "bash",
+            "cwd": cwd,
+            "project_id": project_id
+        }
+
+
+async def test_terminal_start_with_request_id():
+    """Test that terminal_start now automatically includes request_id"""
+    print("\n" + "=" * 70)
+    print("TEST 1: terminal_start with request_id")
+    print("=" * 70)
+
+    mock_channel = MockChannel()
+    context = {
+        "session_manager": MockSessionManager(),
+        "client_session_manager": None
+    }
+
+    handler = TerminalStartHandler(mock_channel, context)
+
+    # Message with request_id
+    message = {
+        "cmd": "terminal_start",
+        "shell": "bash",
+        "request_id": "req_test_001"
+    }
+
+    print(f"📥 Sending message: {message}")
+
+    await handler.handle(message)
+
+    # Check response
+    assert len(mock_channel.sent_messages) > 0, "No response sent"
+    response = mock_channel.sent_messages[0]
+
+    print(f"📬 Response: {response}")
+
+    # Verify request_id was automatically added
+    assert "request_id" in response, "❌ request_id not found in response"
+    assert response["request_id"] == "req_test_001", f"❌ request_id mismatch: {response['request_id']}"
+    assert response["event"] == "terminal_started", f"❌ Wrong event: {response['event']}"
+
+    print("✅ TEST PASSED: request_id automatically added to terminal_started response")
+
+
+async def test_terminal_start_without_request_id():
+    """Test backward compatibility - terminal_start without request_id"""
+    print("\n" + "=" * 70)
+    print("TEST 2: terminal_start without request_id (backward compatibility)")
+    print("=" * 70)
+
+    mock_channel = MockChannel()
+    context = {
+        "session_manager": MockSessionManager(),
+        "client_session_manager": None
+    }
+
+    handler = TerminalStartHandler(mock_channel, context)
+
+    # Message without request_id
+    message = {
+        "cmd": "terminal_start",
+        "shell": "bash"
+    }
+
+    print(f"📥 Sending message: {message}")
+
+    await handler.handle(message)
+
+    # Check response
+    assert len(mock_channel.sent_messages) > 0, "No response sent"
+    response = mock_channel.sent_messages[0]
+
+    print(f"📬 Response: {response}")
+
+    # Verify request_id is NOT in response
+    assert "request_id" not in response, f"❌ request_id should not be in response: {response}"
+    assert response["event"] == "terminal_started", f"❌ Wrong event: {response['event']}"
+
+    print("✅ TEST PASSED: No request_id in response when not in request")
+
+
+async def main():
+    """Run all tests"""
+    print("\n🧪 Testing Centralized request_id Handling")
+    print("=" * 70)
+
+    try:
+        await test_terminal_start_with_request_id()
+        await test_terminal_start_without_request_id()
+
+        print("\n" + "=" * 70)
+        print("🎉 ALL TESTS PASSED")
+        print("=" * 70)
+        print("\nSummary:")
+        print("✅ request_id automatically passed through when present")
+        print("✅ Backward compatible - works without request_id")
+        print("✅ terminal_start now supports request_id (previously didn't)")
+
+        return 0
+
+    except AssertionError as e:
+        print(f"\n❌ TEST FAILED: {e}")
+        return 1
+    except Exception as e:
+        print(f"\n❌ ERROR: {e}")
+        import traceback
+        traceback.print_exc()
+        return 1
+
+
+if __name__ == "__main__":
+    exit_code = asyncio.run(main())
+    sys.exit(exit_code)

portacode-1.3.26/MANIFEST.in

@@ -1,2 +0,0 @@
-prune server
-exclude .pypirc