portacode 1.3.26__py3-none-any.whl → 1.3.27__py3-none-any.whl

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'
+__version_tuple__ = version_tuple = (1, 3, 27)
 
 __commit_id__ = commit_id = None

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/connection/handlers/base.py

@@ -4,6 +4,7 @@ import asyncio
 import logging
 from abc import ABC, abstractmethod
 from typing import Any, Dict, Optional, TYPE_CHECKING
+from portacode.utils.ntp_clock import ntp_clock
 
 if TYPE_CHECKING:
     from ..multiplex import Channel
@@ -42,35 +43,45 @@ class BaseHandler(ABC):
     
     async def send_response(self, payload: Dict[str, Any], reply_channel: Optional[str] = None, project_id: str = None) -> None:
         """Send a response back to the gateway with client session awareness.
-        
+
         Args:
             payload: Response payload
             reply_channel: Optional reply channel for backward compatibility
             project_id: Optional project filter for targeting specific sessions
         """
+        # Add device_send timestamp if trace present
+        if "trace" in payload and "request_id" in payload:
+            device_send_time = ntp_clock.now_ms()
+            if device_send_time is not None:
+                payload["trace"]["device_send"] = device_send_time
+                # Update ping to show total time from client_send
+                if "client_send" in payload["trace"]:
+                    payload["trace"]["ping"] = device_send_time - payload["trace"]["client_send"]
+                logger.info(f"📤 Device sending traced response: {payload['request_id']}")
+
         # Get client session manager from context
         client_session_manager = self.context.get("client_session_manager")
-        
+
         if client_session_manager and client_session_manager.has_interested_clients():
             # Get target sessions
             target_sessions = client_session_manager.get_target_sessions(project_id)
             if not target_sessions:
                 logger.debug("handler: No target sessions found, skipping response send")
                 return
-            
+
             # Add session targeting information
             enhanced_payload = dict(payload)
             enhanced_payload["client_sessions"] = target_sessions
-            
+
             # Add backward compatibility reply_channel (first session if not provided)
             if not reply_channel:
                 reply_channel = client_session_manager.get_reply_channel_for_compatibility()
             if reply_channel:
                 enhanced_payload["reply_channel"] = reply_channel
-            
-            logger.debug("handler: Sending response to %d client sessions: %s", 
+
+            logger.debug("handler: Sending response to %d client sessions: %s",
                         len(target_sessions), target_sessions)
-            
+
             await self.control_channel.send(enhanced_payload)
         else:
             # Fallback to original behavior if no client session manager or no clients
@@ -107,18 +118,43 @@ 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)
-        
+
+        # Add handler_dispatch timestamp if trace present
+        if "trace" in message and "request_id" in message:
+            handler_dispatch_time = ntp_clock.now_ms()
+            if handler_dispatch_time is not None:
+                message["trace"]["handler_dispatch"] = handler_dispatch_time
+                # Update ping to show total time from client_send
+                if "client_send" in message["trace"]:
+                    message["trace"]["ping"] = handler_dispatch_time - message["trace"]["client_send"]
+                logger.info(f"🔧 Handler dispatching: {message['request_id']} ({self.command_name})")
+
         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"]
+
+                # Pass through trace from request to response (add to existing trace, don't create new one)
+                if "trace" in message and "request_id" in message:
+                    response["trace"] = dict(message["trace"])
+                    handler_complete_time = ntp_clock.now_ms()
+                    if handler_complete_time is not None:
+                        response["trace"]["handler_complete"] = handler_complete_time
+                        # Update ping to show total time from client_send
+                        if "client_send" in response["trace"]:
+                            response["trace"]["ping"] = handler_complete_time - response["trace"]["client_send"]
+                        logger.info(f"✅ Handler completed: {message['request_id']} ({self.command_name})")
+
                 # 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:
@@ -147,10 +183,32 @@ class SyncHandler(BaseHandler):
     
     async def handle(self, message: Dict[str, Any], reply_channel: Optional[str] = None) -> None:
         """Handle the command by executing it in an executor and sending the response."""
+        # Add handler_dispatch timestamp if trace present
+        if "trace" in message and "request_id" in message:
+            handler_dispatch_time = ntp_clock.now_ms()
+            if handler_dispatch_time is not None:
+                message["trace"]["handler_dispatch"] = handler_dispatch_time
+                # Update ping to show total time from client_send
+                if "client_send" in message["trace"]:
+                    message["trace"]["ping"] = handler_dispatch_time - message["trace"]["client_send"]
+                logger.info(f"🔧 Handler dispatching: {message['request_id']} ({self.command_name})")
+
         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"]
+
+            # Pass through trace from request to response (add to existing trace, don't create new one)
+            if "trace" in message and "request_id" in message:
+                response["trace"] = dict(message["trace"])
+                handler_complete_time = ntp_clock.now_ms()
+                if handler_complete_time is not None:
+                    response["trace"]["handler_complete"] = handler_complete_time
+                    logger.info(f"✅ Handler completed: {message['request_id']} ({self.command_name})")
+
             # Extract project_id from response for session targeting
             project_id = response.get("project_id")
             await self.send_response(response, reply_channel, project_id)

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/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/connection/handlers/registry.py

@@ -2,6 +2,7 @@
 
 import logging
 from typing import Dict, Type, Any, Optional, List, TYPE_CHECKING
+from portacode.utils.ntp_clock import ntp_clock
 
 if TYPE_CHECKING:
     from ..multiplex import Channel
@@ -72,22 +73,32 @@ class CommandRegistry:
     
     async def dispatch(self, command_name: str, message: Dict[str, Any], reply_channel: Optional[str] = None) -> bool:
         """Dispatch a command to its handler.
-        
+
         Args:
             command_name: The command name
             message: The command message
             reply_channel: Optional reply channel
-            
+
         Returns:
             True if handler was found and executed, False otherwise
         """
         logger.info("registry: Dispatching command '%s' with reply_channel=%s", command_name, reply_channel)
-        
+
+        # Add device_receive timestamp if trace present
+        if "trace" in message and "request_id" in message:
+            device_receive_time = ntp_clock.now_ms()
+            if device_receive_time is not None:
+                message["trace"]["device_receive"] = device_receive_time
+                # Update ping to show total time from client_send
+                if "client_send" in message["trace"]:
+                    message["trace"]["ping"] = device_receive_time - message["trace"]["client_send"]
+                logger.info(f"📨 Device received traced message: {message['request_id']}")
+
         handler = self.get_handler(command_name)
         if handler is None:
             logger.warning("registry: No handler found for command: %s", command_name)
             return False
-        
+
         try:
             await handler.handle(message, reply_channel)
             logger.info("registry: Successfully dispatched command '%s'", command_name)

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/static/js/utils/ntp-clock.js

@@ -0,0 +1,141 @@
+/**
+ * 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 {
+            // Capture local time BEFORE the fetch to avoid timing drift
+            const localTimeBeforeFetch = Date.now();
+            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 latency = (t1 - t0) / 2;  // Estimate one-way latency
+
+            // Calculate offset: server generated timestamp at local time (localTimeBeforeFetch + latency)
+            // So offset = serverTime - (localTimeBeforeFetch + latency)
+            this.offset = serverTime - (localTimeBeforeFetch + 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/utils/NTP_ARCHITECTURE.md

@@ -0,0 +1,136 @@
+# NTP Clock Architecture
+
+## Overview
+
+All entities (client, server, device) synchronize to **time.cloudflare.com** for distributed tracing.
+
+## Architecture: Single Package for Everything
+
+All NTP clock implementations (Python and JavaScript) are in the **portacode package** to ensure DRY principles.
+
+## Python Implementation
+
+**Location:** `portacode/utils/ntp_clock.py` (in portacode package)
+
+### Import Path
+```python
+from portacode.utils.ntp_clock import ntp_clock
+```
+
+### Usage Locations
+1. **Django Server Consumers** (`server/portacode_django/dashboard/consumers.py`)
+2. **Device Base Handlers** (`portacode/connection/handlers/base.py`)
+3. **Device Client** (`server/portacode_django/data/services/device_client.py`)
+4. **Any Python code with portacode installed**
+
+### Dependencies
+- `setup.py`: Added `ntplib>=0.4.0` to `install_requires`
+- `server/portacode_django/requirements.txt`: Added `portacode>=1.3.26`
+
+### API
+```python
+# Get NTP-synchronized timestamp (None if not synced)
+ntp_clock.now_ms()      # milliseconds
+ntp_clock.now()         # seconds
+ntp_clock.now_iso()     # ISO format
+
+# Check sync status
+status = ntp_clock.get_status()
+# {
+#   'server': 'time.cloudflare.com',
+#   'offset_ms': 6.04,
+#   'last_sync': '2025-10-05T04:37:12.768445+00:00',
+#   'is_synced': True
+# }
+```
+
+## JavaScript Implementation
+
+**Location:** `portacode/static/js/utils/ntp-clock.js` (in portacode package)
+
+### Django Setup
+
+Django will serve static files from the portacode package automatically after `collectstatic`:
+
+```python
+# Django settings.py - no changes needed, just ensure:
+INSTALLED_APPS = [
+    # ... other apps
+    'portacode',  # Add portacode as an installed app (optional, for admin integration)
+]
+
+# Static files will be collected from portacode package
+STATIC_URL = '/static/'
+```
+
+After installing portacode (`pip install portacode` or `pip install -e .`), run:
+```bash
+python manage.py collectstatic
+```
+
+This will copy `portacode/static/js/utils/ntp-clock.js` to Django's static files directory.
+
+### Import Path (in Django templates/JS)
+```javascript
+import ntpClock from '/static/js/utils/ntp-clock.js';
+// or relative to your JS file:
+import ntpClock from './utils/ntp-clock.js';
+```
+
+### Usage Locations
+1. **Dashboard WebSocket** (`websocket-service.js`)
+2. **Project WebSocket** (`websocket-service-project.js`)
+
+### API
+```javascript
+// Get NTP-synchronized timestamp (null if not synced)
+ntpClock.now()          // milliseconds
+ntpClock.nowISO()       // ISO format
+
+// Check sync status
+const status = ntpClock.getStatus();
+// {
+//   server: 'time.cloudflare.com',
+//   offset: 6.04,
+//   lastSync: '2025-10-05T04:37:12.768445+00:00',
+//   isSynced: true
+// }
+```
+
+## Design Principles
+
+1. **DRY (Don't Repeat Yourself)**
+   - **Python:** Single implementation in portacode package (`portacode/utils/ntp_clock.py`)
+   - **JavaScript:** Single implementation in portacode package (`portacode/static/js/utils/ntp-clock.js`)
+   - Both served from the same package, no duplication across repos
+
+2. **No Fallback Servers**
+   - All entities MUST sync to time.cloudflare.com
+   - If sync fails, timestamps are None/null
+   - Ensures all timestamps are comparable
+
+3. **Auto-Sync**
+   - Re-syncs every 5 minutes automatically
+   - Initial sync on import/load
+   - Max 3 retry attempts before marking as failed
+
+4. **Thread-Safe (Python)**
+   - Uses threading.Lock for concurrent access
+   - Background daemon thread for periodic sync
+
+## Testing
+
+### Python
+```bash
+python tools/test_python_ntp_clock.py
+```
+
+### JavaScript
+The test file is included in the package at `portacode/static/js/test-ntp-clock.html`.
+
+After Django collectstatic, open: `/static/js/test-ntp-clock.html` in browser
+
+Or run directly from package:
+```bash
+python -c "import portacode, os; print(os.path.join(os.path.dirname(portacode.__file__), 'static/js/test-ntp-clock.html'))"
+```

portacode/utils/__init__.py

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

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.dist-info → portacode-1.3.27.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: portacode
-Version: 1.3.26
+Version: 1.3.27
 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.dist-info → portacode-1.3.27.dist-info}/RECORD

@@ -1,7 +1,7 @@
 portacode/README.md,sha256=4dKtpvR8LNgZPVz37GmkQCMWIr_u25Ao63iW56s7Ke4,775
 portacode/__init__.py,sha256=oB3sV1wXr-um-RXio73UG8E5Xx6cF2ZVJveqjNmC-vQ,1086
 portacode/__main__.py,sha256=jmHTGC1hzmo9iKJLv-SSYe9BSIbPPZ2IOpecI03PlTs,296
-portacode/_version.py,sha256=SuapxdEzR3ZIC18_-TLYJjA4kj4DA2PG_8e-FJuLuQA,706
+portacode/_version.py,sha256=lfm8QKOCYrPf3hyLkHj9R9SFlWO01BBk81sZeN5NiXw,706
 portacode/cli.py,sha256=eDqcZMVFHKzqqWxedhhx8ylu5WMVCLqeJQkbPR7RcJE,16333
 portacode/data.py,sha256=5-s291bv8J354myaHm1Y7CQZTZyRzMU3TGe5U4hb-FA,1591
 portacode/keypair.py,sha256=PAcOYqlVLOoZTPYi6LvLjfsY6BkrWbLOhSZLb8r5sHs,3635
@@ -13,14 +13,14 @@ portacode/connection/client.py,sha256=P5ubshMFbyV8PkGZxU2o_70gIYEy3Pv_R5blmF2ylW
 portacode/connection/multiplex.py,sha256=L-TxqJ_ZEbfNEfu1cwxgJ5vUdyRzZjsMy2Kx1diiZys,5237
 portacode/connection/terminal.py,sha256=euST6O_3hm9qsBk52xTXORTKfKqsMYnTHuZjvlitYSE,42307
 portacode/connection/handlers/README.md,sha256=HsLZG1QK1JNm67HsgL6WoDg9nxzKXxwkc5fJPFJdX5g,12169
-portacode/connection/handlers/WEBSOCKET_PROTOCOL.md,sha256=0KBoJzqemXbvpu8Ps7LitLwRYhJNtzcTJ5WAHMGgAuc,62509
+portacode/connection/handlers/WEBSOCKET_PROTOCOL.md,sha256=U-d58S-X2r5T6QAu-6NOzCIJg71FIj_vmOdUGCWFIhw,68211
 portacode/connection/handlers/__init__.py,sha256=4nv3Z4TGYjWcauKPWsbL_FbrTXApI94V7j6oiU1Vv-o,2144
-portacode/connection/handlers/base.py,sha256=C-H61CUHM2k431CG0usd7eEqklDj9pnuXHujBwhTugk,6666
+portacode/connection/handlers/base.py,sha256=oENFb-Fcfzwk99Qx8gJQriEMiwSxwygwjOiuCH36hM4,10231
 portacode/connection/handlers/chunked_content.py,sha256=h6hXRmxSeOgnIxoU8CkmvEf2Odv-ajPrpHIe_W3GKcA,9251
-portacode/connection/handlers/file_handlers.py,sha256=CGMooOrfGbKx-bHA8vr8lmPG-vHw1DJlVWf6TLpfMJU,15355
+portacode/connection/handlers/file_handlers.py,sha256=1Thp8cqbtJAY96QfO1huZwbWhQcaL9zh28wtNNjsmJk,15218
 portacode/connection/handlers/project_aware_file_handlers.py,sha256=n0M2WmBNWPwzigdIkyZiAsePUQGXVqYSsDyOxm-Nsok,9253
 portacode/connection/handlers/project_state_handlers.py,sha256=v6ZefGW9i7n1aZLq2jOGumJIjYb6aHlPI4m1jkYewm8,1686
-portacode/connection/handlers/registry.py,sha256=ebi0vhR1XXSYU7mJXlQJ4MjBYaMygGYqX7ReK7vsZ7o,5558
+portacode/connection/handlers/registry.py,sha256=pFO-pYAeRXu_Jzb8YdLqHgeyUP-PaGZq0_C37unV3F4,6174
 portacode/connection/handlers/session.py,sha256=O7TMI5cRziOiXEBWCfBshkMpEthhjvKqGL0hhNOG1wU,26716
 portacode/connection/handlers/system_handlers.py,sha256=65V5ctT0dIBc-oWG91e62MbdvU0z6x6JCTQuIqCWmZ0,5242
 portacode/connection/handlers/tab_factory.py,sha256=VBZnwtxgeNJCsfBzUjkFWAAGBdijvai4MS2dXnhFY8U,18000
@@ -29,11 +29,16 @@ portacode/connection/handlers/project_state/README.md,sha256=trdd4ig6ungmwH5SpbS
 portacode/connection/handlers/project_state/__init__.py,sha256=5ucIqk6Iclqg6bKkL8r_wVs5Tlt6B9J7yQH6yQUt7gc,2541
 portacode/connection/handlers/project_state/file_system_watcher.py,sha256=w-93ioUZZKZxzPFr8djJnGhWjMVFVdDsmo0fVAukoKk,10150
 portacode/connection/handlers/project_state/git_manager.py,sha256=fA0RbWCblpJep13L4MdqnEP4sE1qWc7Y66vrIo_SWps,76575
-portacode/connection/handlers/project_state/handlers.py,sha256=nkednSbCC-0n3ZtzesaWd9_NFfxNjS4lyVNnbsYs0Zk,37823
+portacode/connection/handlers/project_state/handlers.py,sha256=03RYNeWfX_Ym9Lx4VdA6iwLSWFdjRtjWI5T1buBg4Mc,37941
 portacode/connection/handlers/project_state/manager.py,sha256=03mN0H9TqVa_ohD5U5-5ZywDGj0s8-y1IxGdb07dZn8,57636
 portacode/connection/handlers/project_state/models.py,sha256=EZTKvxHKs8QlQUbzI0u2IqfzfRRXZixUIDBwTGCJATI,4313
 portacode/connection/handlers/project_state/utils.py,sha256=LsbQr9TH9Bz30FqikmtTxco4PlB_n0kUIuPKQ6Fb_mo,1665
-portacode-1.3.26.dist-info/licenses/LICENSE,sha256=2FGbCnUDgRYuQTkB1O1dUUpu5CVAjK1j4_p6ack9Z54,1066
+portacode/static/js/test-ntp-clock.html,sha256=bUow9sifIuLNPqKvuPbpQozmEE6RhdCI4Plib3CqUmw,2130
+portacode/static/js/utils/ntp-clock.js,sha256=KMeHGT-IlUSlxVRZZ899z25dQCJh6EJbgXjlh8dD8vA,4495
+portacode/utils/NTP_ARCHITECTURE.md,sha256=WkESTbz5SNAgdmDKk3DrHMhtYOPji_Kt3_a9arWdRig,3894
+portacode/utils/__init__.py,sha256=NgBlWTuNJESfIYJzP_3adI1yJQJR0XJLRpSdVNaBAN0,33
+portacode/utils/ntp_clock.py,sha256=6QJOVZr9VQuxIyJt9KNG4dR-nZ3bKNyipMxjqDWP89Y,5152
+portacode-1.3.27.dist-info/licenses/LICENSE,sha256=2FGbCnUDgRYuQTkB1O1dUUpu5CVAjK1j4_p6ack9Z54,1066
 test_modules/README.md,sha256=Do_agkm9WhSzueXjRAkV_xEj6Emy5zB3N3VKY5Roce8,9274
 test_modules/__init__.py,sha256=1LcbHodIHsB0g-g4NGjSn6AMuCoGbymvXPYLOb6Z7F0,53
 test_modules/test_device_online.py,sha256=yiSyVaMwKAugqIX_ZIxmLXiOlmA_8IRXiUp12YmpB98,1653
@@ -58,8 +63,8 @@ testing_framework/core/playwright_manager.py,sha256=9kGXJtRpRNEhaSlV7XVXvx4UQSHS
 testing_framework/core/runner.py,sha256=j2QwNJmAxVBmJvcbVS7DgPJUKPNzqfLmt_4NNdaKmZU,19297
 testing_framework/core/shared_cli_manager.py,sha256=BESSNtyQb7BOlaOvZmm04T8Uezjms4KCBs2MzTxvzYQ,8790
 testing_framework/core/test_discovery.py,sha256=2FZ9fJ8Dp5dloA-fkgXoJ_gCMC_nYPBnA3Hs2xlagzM,4928
-portacode-1.3.26.dist-info/METADATA,sha256=-cJuyxEf9rr4AcyR-NcnZj-48wrOo2MVlFKrkF2vO6E,6960
-portacode-1.3.26.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-portacode-1.3.26.dist-info/entry_points.txt,sha256=lLUUL-BM6_wwe44Xv0__5NQ1BnAz6jWjSMFvZdWW3zU,48
-portacode-1.3.26.dist-info/top_level.txt,sha256=TGhTYUxfW8SyVZc_zGgzjzc24gGT7nSw8Qf73liVRKM,41
-portacode-1.3.26.dist-info/RECORD,,
+portacode-1.3.27.dist-info/METADATA,sha256=3achcETltaOKmWGJ6gje69ghCufW6F3KtizLCtGjEf0,6989
+portacode-1.3.27.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+portacode-1.3.27.dist-info/entry_points.txt,sha256=lLUUL-BM6_wwe44Xv0__5NQ1BnAz6jWjSMFvZdWW3zU,48
+portacode-1.3.27.dist-info/top_level.txt,sha256=TGhTYUxfW8SyVZc_zGgzjzc24gGT7nSw8Qf73liVRKM,41
+portacode-1.3.27.dist-info/RECORD,,