portacode 1.4.12.dev9__tar.gz → 1.4.13.dev1__tar.gz

{portacode-1.4.12.dev9 → portacode-1.4.13.dev1}/PKG-INFO

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

{portacode-1.4.12.dev9 → portacode-1.4.13.dev1}/portacode/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '1.4.12.dev9'
-__version_tuple__ = version_tuple = (1, 4, 12, 'dev9')
+__version__ = version = '1.4.13.dev1'
+__version_tuple__ = version_tuple = (1, 4, 13, 'dev1')
 
 __commit_id__ = commit_id = None

{portacode-1.4.12.dev9 → portacode-1.4.13.dev1}/portacode/connection/handlers/WEBSOCKET_PROTOCOL.md

@@ -27,6 +27,8 @@ The Portacode server acts as a **routing middleman** between client sessions and
 
 - **`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.
 
+Device handlers that want to respond only to the session that issued a given command can rely on the helper defined in `portacode/connection/handlers/base.py` (`BaseHandler.send_response_to_source_session`). It wraps the boilerplate of reusing `request_id`/`trace`, injecting `client_sessions=[source_client_session]`, and sending via the control channel so the handler does not need to manually reconstruct routing metadata for each reply.
+
 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

{portacode-1.4.12.dev9 → portacode-1.4.13.dev1}/portacode/connection/handlers/base.py

@@ -88,6 +88,42 @@ class BaseHandler(ABC):
             if reply_channel:
                 payload["reply_channel"] = reply_channel
             await self.control_channel.send(payload)
+
+    async def send_response_to_source_session(
+        self,
+        message: Dict[str, Any],
+        payload: Dict[str, Any],
+        reply_channel: Optional[str] = None,
+    ) -> None:
+        """Send a response directly to the client session that issued ``message``.
+
+        This bypasses ``ClientSessionManager`` routing and ensures only the session
+        whose ``source_client_session`` was injected by the server will receive the
+        response. The helper also copies ``request_id``/``trace`` timing data so tracing
+        and logging remain consistent.
+        """
+        response = dict(payload)
+        request_id = message.get("request_id")
+        if request_id and "request_id" not in response:
+            response["request_id"] = request_id
+
+        if "trace" in message and "request_id" in message and "trace" not in response:
+            trace_data = dict(message["trace"])
+            handler_complete_time = ntp_clock.now_ms()
+            if handler_complete_time is not None:
+                trace_data["handler_complete"] = handler_complete_time
+                if "client_send" in trace_data:
+                    trace_data["ping"] = handler_complete_time - trace_data["client_send"]
+            response["trace"] = trace_data
+
+        source_client_session = message.get("source_client_session")
+        if source_client_session:
+            response["client_sessions"] = [source_client_session]
+
+        if reply_channel:
+            response["reply_channel"] = reply_channel
+
+        await self.control_channel.send(response)
     
     async def send_error(self, message: str, reply_channel: Optional[str] = None, project_id: str = None) -> None:
         """Send an error response with client session awareness.
@@ -141,22 +177,16 @@ class AsyncHandler(BaseHandler):
                 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"])
+                if "trace" in message and "request_id" in message and "trace" not in response:
+                    trace_data = 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",
-                           self.command_name, project_id, response)
-                await self.send_response(response, reply_channel, project_id)
+                        trace_data["handler_complete"] = handler_complete_time
+                        if "client_send" in trace_data:
+                            trace_data["ping"] = handler_complete_time - trace_data["client_send"]
+                    response["trace"] = trace_data
+                    logger.info(f"✅ Handler completed: {message['request_id']} ({self.command_name})")
+
             else:
                 logger.info("handler: %s handled response transmission directly", self.command_name)
         except Exception as exc:
@@ -216,4 +246,4 @@ class SyncHandler(BaseHandler):
             logger.exception("Error in sync handler %s: %s", self.command_name, exc)
             # Extract project_id from original message for error targeting
             project_id = message.get("project_id")
-            await self.send_error(str(exc), reply_channel, project_id) 
+            await self.send_error(str(exc), reply_channel, project_id) 

{portacode-1.4.12.dev9 → portacode-1.4.13.dev1}/portacode/connection/handlers/proxmox_infra.py

@@ -59,6 +59,7 @@ def _emit_progress_event(
     message: str,
     phase: str,
     request_id: Optional[str],
+    client_sessions: Optional[List[str]] = None,
     details: Optional[Dict[str, Any]] = None,
 ) -> None:
     loop = handler.context.get("event_loop")
@@ -84,6 +85,8 @@ def _emit_progress_event(
         payload["request_id"] = request_id
     if details:
         payload["details"] = details
+    if client_sessions:
+        payload["client_sessions"] = client_sessions
 
     future = asyncio.run_coroutine_threadsafe(handler.send_response(payload), loop)
     future.add_done_callback(
@@ -1050,8 +1053,14 @@ class CreateProxmoxContainerHandler(SyncHandler):
         return "create_proxmox_container"
 
     def execute(self, message: Dict[str, Any]) -> Dict[str, Any]:
-        logger.info("create_proxmox_container command received")
         request_id = message.get("request_id")
+        source_client_session = message.get("source_client_session")
+        logger.info(
+            "create_proxmox_container command received request_id=%s client_session=%s",
+            request_id,
+            source_client_session,
+        )
+        client_sessions = [source_client_session] if source_client_session else None
         bootstrap_user, bootstrap_password, bootstrap_ssh_key = _get_provisioning_user_info(message)
         bootstrap_steps = _build_bootstrap_steps(bootstrap_user, bootstrap_password, bootstrap_ssh_key)
         total_steps = 3 + len(bootstrap_steps) + 2
@@ -1075,6 +1084,7 @@ class CreateProxmoxContainerHandler(SyncHandler):
                 message=start_message,
                 phase="lifecycle",
                 request_id=request_id,
+                client_sessions=client_sessions,
             )
             try:
                 result = action()
@@ -1089,6 +1099,7 @@ class CreateProxmoxContainerHandler(SyncHandler):
                     message=f"{step_label} failed: {exc}",
                     phase="lifecycle",
                     request_id=request_id,
+                    client_sessions=client_sessions,
                     details={"error": str(exc)},
                 )
                 raise
@@ -1102,6 +1113,7 @@ class CreateProxmoxContainerHandler(SyncHandler):
                 message=success_message,
                 phase="lifecycle",
                 request_id=request_id,
+                client_sessions=client_sessions,
             )
             current_step_index += 1
             return result
@@ -1131,7 +1143,7 @@ class CreateProxmoxContainerHandler(SyncHandler):
             payload["cpuunits"] = max(int(payload["cpus"] * 1024), 10)
             payload["memory"] = int(payload["ram_mib"])
             payload["node"] = node
-            logger.debug(
+            logger.info(
                 "Provisioning container node=%s template=%s ram=%s cpu=%s storage=%s",
                 node,
                 payload["template"],
@@ -1144,6 +1156,12 @@ class CreateProxmoxContainerHandler(SyncHandler):
             payload["created_at"] = datetime.utcnow().isoformat() + "Z"
             payload["status"] = "creating"
             _write_container_record(vmid, payload)
+            logger.info(
+                "Container record written vmid=%s hostname=%s client_session=%s",
+                vmid,
+                payload["hostname"],
+                source_client_session,
+            )
             return proxmox, node, vmid, payload
 
         proxmox, node, vmid, payload = _run_lifecycle_step(
@@ -1202,9 +1220,16 @@ class CreateProxmoxContainerHandler(SyncHandler):
                 message=message_text,
                 phase="bootstrap",
                 request_id=request_id,
+                client_sessions=client_sessions,
                 details=details or None,
             )
 
+        logger.info(
+            "Bootstrapping Portacode in container vmid=%s user=%s client_session=%s",
+            vmid,
+            payload["username"],
+            source_client_session,
+        )
         public_key, steps = _bootstrap_portacode(
             vmid,
             payload["username"],
@@ -1217,7 +1242,7 @@ class CreateProxmoxContainerHandler(SyncHandler):
         )
         current_step_index += len(bootstrap_steps)
 
-        return {
+        response = {
             "event": "proxmox_container_created",
             "success": True,
             "message": f"Container {vmid} is ready and Portacode key captured.",
@@ -1234,6 +1259,10 @@ class CreateProxmoxContainerHandler(SyncHandler):
             },
             "setup_steps": steps,
         }
+        if client_sessions:
+            response["client_sessions"] = client_sessions
+        response["_reply_to_source_session"] = True
+        return response
 
 
 class StartPortacodeServiceHandler(SyncHandler):
@@ -1261,6 +1290,15 @@ class StartPortacodeServiceHandler(SyncHandler):
         start_index = int(message.get("step_index", 1))
         total_steps = int(message.get("total_steps", start_index + 2))
         request_id = message.get("request_id")
+        source_client_session = message.get("source_client_session")
+        client_sessions = [source_client_session] if source_client_session else None
+
+        logger.info(
+            "start_portacode_service invoked vmid=%s user=%s client_session=%s",
+            vmid,
+            user,
+            source_client_session,
+        )
 
         auth_step_name = "setup_device_authentication"
         auth_label = "Setting up device authentication"
@@ -1274,6 +1312,7 @@ class StartPortacodeServiceHandler(SyncHandler):
             message="Notifying the server of the new device…",
             phase="service",
             request_id=request_id,
+            client_sessions=client_sessions,
         )
         _emit_progress_event(
             self,
@@ -1285,6 +1324,7 @@ class StartPortacodeServiceHandler(SyncHandler):
             message="Authentication metadata recorded.",
             phase="service",
             request_id=request_id,
+            client_sessions=client_sessions,
         )
 
         install_step = start_index + 1
@@ -1299,6 +1339,7 @@ class StartPortacodeServiceHandler(SyncHandler):
             message="Running sudo portacode service install…",
             phase="service",
             request_id=request_id,
+            client_sessions=client_sessions,
         )
 
         cmd = f"su - {user} -c 'sudo -S portacode service install'"
@@ -1315,6 +1356,7 @@ class StartPortacodeServiceHandler(SyncHandler):
                 message=f"{install_label} failed: {res.get('stderr') or res.get('stdout')}",
                 phase="service",
                 request_id=request_id,
+                client_sessions=client_sessions,
                 details={
                     "stderr": res.get("stderr"),
                     "stdout": res.get("stdout"),
@@ -1322,6 +1364,12 @@ class StartPortacodeServiceHandler(SyncHandler):
             )
             raise RuntimeError(res.get("stderr") or res.get("stdout") or "Service install failed")
 
+        logger.info(
+            "portacode service install command completed vmid=%s returncode=%s",
+            vmid,
+            res["returncode"],
+        )
+
         _emit_progress_event(
             self,
             step_index=install_step,
@@ -1332,14 +1380,19 @@ class StartPortacodeServiceHandler(SyncHandler):
             message="Portacode service install finished.",
             phase="service",
             request_id=request_id,
+            client_sessions=client_sessions,
         )
 
-        return {
+        response = {
             "event": "proxmox_service_started",
             "success": True,
             "message": "Portacode service install completed",
             "ctid": str(vmid),
         }
+        if client_sessions:
+            response["client_sessions"] = client_sessions
+        response["_reply_to_source_session"] = True
+        return response
 
 
 class StartProxmoxContainerHandler(SyncHandler):
@@ -1355,12 +1408,20 @@ class StartProxmoxContainerHandler(SyncHandler):
         proxmox = _connect_proxmox(config)
         node = _get_node_from_config(config)
         _ensure_container_managed(proxmox, node, vmid)
+        source_client_session = message.get("source_client_session")
+        client_sessions = [source_client_session] if source_client_session else None
+
+        logger.info(
+            "start_proxmox_container invoked vmid=%s client_session=%s",
+            vmid,
+            source_client_session,
+        )
 
         status, elapsed = _start_container(proxmox, node, vmid)
         _update_container_record(vmid, {"status": "running"})
 
         infra = get_infra_snapshot()
-        return {
+        response = {
             "event": "proxmox_container_action",
             "action": "start",
             "success": True,
@@ -1370,6 +1431,10 @@ class StartProxmoxContainerHandler(SyncHandler):
             "status": status.get("status"),
             "infra": infra,
         }
+        if client_sessions:
+            response["client_sessions"] = client_sessions
+        response["_reply_to_source_session"] = True
+        return response
 
 
 class StopProxmoxContainerHandler(SyncHandler):
@@ -1385,6 +1450,14 @@ class StopProxmoxContainerHandler(SyncHandler):
         proxmox = _connect_proxmox(config)
         node = _get_node_from_config(config)
         _ensure_container_managed(proxmox, node, vmid)
+        source_client_session = message.get("source_client_session")
+        client_sessions = [source_client_session] if source_client_session else None
+
+        logger.info(
+            "stop_proxmox_container invoked vmid=%s client_session=%s",
+            vmid,
+            source_client_session,
+        )
 
         status, elapsed = _stop_container(proxmox, node, vmid)
         final_status = status.get("status") or "stopped"
@@ -1396,7 +1469,7 @@ class StopProxmoxContainerHandler(SyncHandler):
             if final_status != "running" and elapsed == 0.0
             else f"Stopped container {vmid} in {elapsed:.1f}s."
         )
-        return {
+        response = {
             "event": "proxmox_container_action",
             "action": "stop",
             "success": True,
@@ -1406,6 +1479,10 @@ class StopProxmoxContainerHandler(SyncHandler):
             "status": final_status,
             "infra": infra,
         }
+        if client_sessions:
+            response["client_sessions"] = client_sessions
+        response["_reply_to_source_session"] = True
+        return response
 
 
 class RemoveProxmoxContainerHandler(SyncHandler):
@@ -1421,13 +1498,21 @@ class RemoveProxmoxContainerHandler(SyncHandler):
         proxmox = _connect_proxmox(config)
         node = _get_node_from_config(config)
         _ensure_container_managed(proxmox, node, vmid)
+        source_client_session = message.get("source_client_session")
+        client_sessions = [source_client_session] if source_client_session else None
+
+        logger.info(
+            "remove_proxmox_container invoked vmid=%s client_session=%s",
+            vmid,
+            source_client_session,
+        )
 
         stop_status, stop_elapsed = _stop_container(proxmox, node, vmid)
         delete_status, delete_elapsed = _delete_container(proxmox, node, vmid)
         _remove_container_record(vmid)
 
         infra = get_infra_snapshot()
-        return {
+        response = {
             "event": "proxmox_container_action",
             "action": "remove",
             "success": True,
@@ -1440,6 +1525,10 @@ class RemoveProxmoxContainerHandler(SyncHandler):
             "status": "deleted",
             "infra": infra,
         }
+        if client_sessions:
+            response["client_sessions"] = client_sessions
+        response["_reply_to_source_session"] = True
+        return response
 
 
 class ConfigureProxmoxInfraHandler(SyncHandler):
@@ -1453,13 +1542,19 @@ class ConfigureProxmoxInfraHandler(SyncHandler):
         verify_ssl = bool(message.get("verify_ssl"))
         if not token_identifier or not token_value:
             raise ValueError("token_identifier and token_value are required")
+        source_client_session = message.get("source_client_session")
+        client_sessions = [source_client_session] if source_client_session else None
         snapshot = configure_infrastructure(token_identifier, token_value, verify_ssl=verify_ssl)
-        return {
+        response = {
             "event": "proxmox_infra_configured",
             "success": True,
             "message": "Proxmox infrastructure configured",
             "infra": snapshot,
         }
+        if client_sessions:
+            response["client_sessions"] = client_sessions
+        response["_reply_to_source_session"] = True
+        return response
 
 
 class RevertProxmoxInfraHandler(SyncHandler):
@@ -1468,10 +1563,16 @@ class RevertProxmoxInfraHandler(SyncHandler):
         return "revert_proxmox_infra"
 
     def execute(self, message: Dict[str, Any]) -> Dict[str, Any]:
+        source_client_session = message.get("source_client_session")
+        client_sessions = [source_client_session] if source_client_session else None
         snapshot = revert_infrastructure()
-        return {
+        response = {
             "event": "proxmox_infra_reverted",
             "success": True,
             "message": "Proxmox infrastructure configuration reverted",
             "infra": snapshot,
         }
+        if client_sessions:
+            response["client_sessions"] = client_sessions
+        response["_reply_to_source_session"] = True
+        return response

{portacode-1.4.12.dev9 → portacode-1.4.13.dev1}/portacode.egg-info/PKG-INFO

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