portacode 2.0.0.dev0__tar.gz → 2.0.1__tar.gz

{portacode-2.0.0.dev0 → portacode-2.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: portacode
-Version: 2.0.0.dev0
+Version: 2.0.1
 Summary: Device agent for the AI platform that builds, tests, deploys, and operates real software
 Home-page: https://portacode.com/
 Author: Meena Erian

{portacode-2.0.0.dev0 → portacode-2.0.1}/portacode/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '2.0.0.dev0'
-__version_tuple__ = version_tuple = (2, 0, 0, 'dev0')
+__version__ = version = '2.0.1'
+__version_tuple__ = version_tuple = (2, 0, 1)
 
 __commit_id__ = commit_id = None

{portacode-2.0.0.dev0 → portacode-2.0.1}/portacode/connection/guest_host_protocol.py

@@ -24,6 +24,7 @@ GUEST_HOST_REQUEST_COMMANDS = frozenset(
         "configure_proxmox_container_expose_ports",
         "start_proxmox_container",
         "stop_proxmox_container",
+        "restart_proxmox_container",
         "remove_proxmox_container",
         "create_proxmox_container",
     }
@@ -32,14 +33,23 @@ GUEST_HOST_COMMAND_OPERATIONS = {
     "configure_proxmox_container_expose_ports": "expose_ports",
     "start_proxmox_container": "power",
     "stop_proxmox_container": "power",
+    "restart_proxmox_container": "power",
     "remove_proxmox_container": "delete",
     "create_proxmox_container": "provision",
 }
 
-# The protocol reserves additional commands for staged rollout, but this CLI
-# release advertises and executes only the operation validated end-to-end.
+# Every advertised operation is mapped to its existing, independently
+# registered legacy handler.  Server-side capability and runtime gates still
+# control which operations are actually sent through this protocol.
 GUEST_HOST_EXECUTABLE_COMMANDS = frozenset(
-    {"configure_proxmox_container_expose_ports"}
+    {
+        "configure_proxmox_container_expose_ports",
+        "start_proxmox_container",
+        "stop_proxmox_container",
+        "restart_proxmox_container",
+        "remove_proxmox_container",
+        "create_proxmox_container",
+    }
 )
 
 

{portacode-2.0.0.dev0 → portacode-2.0.1}/portacode/connection/handlers/WEBSOCKET_PROTOCOL.md

@@ -88,6 +88,18 @@ versions continue using existing commands while flags are disabled. Unknown
 message types or commands must fail closed; they must never fall through to an
 ordinary client-session handler.
 
+Protocol version 1 defines these request types and command mappings:
+
+- `expose_ports` → `configure_proxmox_container_expose_ports`;
+- `power` → `start_proxmox_container`, `stop_proxmox_container`, or `restart_proxmox_container`;
+- `delete` → `remove_proxmox_container`;
+- `provision` → `create_proxmox_container`.
+
+Supporting CLI versions advertise the enabled set in
+`system_info.protocol_capabilities.guest_host_requests.request_types`. The
+server must check that per-host list as well as its per-operation runtime flag
+before selecting this transport. Otherwise it uses the unchanged legacy path.
+
 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
@@ -534,6 +546,14 @@ Stops a running Portacode-managed container. Handled by [`StopProxmoxContainerHa
 *   Emits a [`proxmox_container_action`](#proxmox_container_action-event) event with `action="stop"` and the refreshed infra snapshot.
 *   Emits an [`error`](#error) event on failure.
 
+### `restart_proxmox_container`
+
+Stops and starts a Portacode-managed container as one validated host-side
+operation. It accepts the same required `child_device_id` and optional `ctid`
+fields as the start/stop actions. The handler verifies the child-to-container
+mapping before changing state, then emits `proxmox_container_action` with
+`action="restart"`.
+
 ### `remove_proxmox_container`
 
 Deletes a managed container from Proxmox (stopping it first if necessary) and removes the stored metadata file. Handled by [`RemoveProxmoxContainerHandler`](./proxmox_infra.py).

{portacode-2.0.0.dev0 → portacode-2.0.1}/portacode/connection/handlers/__init__.py

@@ -60,6 +60,7 @@ from .proxmox_infra import (
     StartPortacodeServiceHandler,
     StartProxmoxContainerHandler,
     StopProxmoxContainerHandler,
+    RestartProxmoxContainerHandler,
     RemoveProxmoxContainerHandler,
 )
 from .cloudflare_tunnel import CloudflareTunnelSetupHandler
@@ -132,6 +133,7 @@ __all__ = [
     "StartPortacodeServiceHandler",
     "StartProxmoxContainerHandler",
     "StopProxmoxContainerHandler",
+    "RestartProxmoxContainerHandler",
     "RemoveProxmoxContainerHandler",
     "UpdatePortacodeHandler",
     "RevertProxmoxInfraHandler",

{portacode-2.0.0.dev0 → portacode-2.0.1}/portacode/connection/handlers/proxmox_infra.py

@@ -5165,6 +5165,68 @@ class StopProxmoxContainerHandler(SyncHandler):
         }
 
 
+class RestartProxmoxContainerHandler(SyncHandler):
+    """Restart a managed container as one validated host-side operation."""
+
+    @property
+    def command_name(self) -> str:
+        return "restart_proxmox_container"
+
+    def execute(self, message: Dict[str, Any]) -> Dict[str, Any]:
+        child_device_id = (message.get("child_device_id") or "").strip()
+        if not child_device_id:
+            raise ValueError("child_device_id is required for restart_proxmox_container")
+        config = _ensure_infra_configured()
+        proxmox = _connect_proxmox(config)
+        node = _get_node_from_config(config)
+        try:
+            vmid = _parse_ctid(message)
+        except ValueError:
+            try:
+                vmid = _resolve_vmid_for_device(child_device_id)
+            except _DeviceLookupError:
+                vmid = _resolve_vmid_for_device_in_proxmox(proxmox, node, child_device_id)
+        _ensure_container_managed(proxmox, node, vmid, device_id=child_device_id)
+
+        stop_status, stop_elapsed = _stop_container(proxmox, node, vmid)
+        start_status, start_elapsed = _start_container(proxmox, node, vmid)
+        _update_container_record(vmid, {"status": "running"})
+
+        forwarding_ip_updated = False
+        try:
+            from .cloudflare_forwarding import reconcile_container_forwarding_ip
+
+            forwarding_ip_updated = reconcile_container_forwarding_ip(
+                child_device_id,
+                proxmox=proxmox,
+                node=node,
+                lease_attempts=6,
+                lease_retry_seconds=1.0,
+            )
+        except Exception:
+            logger.warning(
+                "Unable to reconcile exposed IP after restarting container device_id=%s vmid=%s",
+                child_device_id,
+                vmid,
+                exc_info=True,
+            )
+
+        return {
+            "event": "proxmox_container_action",
+            "action": "restart",
+            "success": True,
+            "ctid": str(vmid),
+            "message": f"Restarted container {vmid} in {stop_elapsed + start_elapsed:.1f}s.",
+            "details": {
+                "stop_exitstatus": stop_status.get("exitstatus"),
+                "start_exitstatus": start_status.get("exitstatus"),
+                "forwarding_ip_updated": forwarding_ip_updated,
+            },
+            "status": start_status.get("status") or "running",
+            "infra": get_infra_snapshot(),
+        }
+
+
 class RemoveProxmoxContainerHandler(SyncHandler):
     """Delete a managed container via the Proxmox API."""
 

{portacode-2.0.0.dev0 → portacode-2.0.1}/portacode/connection/handlers/system_handlers.py

@@ -632,7 +632,7 @@ class SystemInfoHandler(SyncHandler):
         info["protocol_capabilities"] = {
             "guest_host_requests": {
                 "protocol_version": 1,
-                "request_types": ["expose_ports"],
+                "request_types": ["expose_ports", "power", "delete", "provision"],
                 "message_types": [
                     "guest_host_request",
                     "guest_host_ack",

{portacode-2.0.0.dev0 → portacode-2.0.1}/portacode/connection/handlers/test_proxmox_infra.py

@@ -5,6 +5,7 @@ from unittest.mock import MagicMock, patch
 
 from portacode.connection.handlers.proxmox_infra import (
     RemoveProxmoxContainerHandler,
+    RestartProxmoxContainerHandler,
     _build_full_container_summary,
     _compose_managed_containers_summary,
     _build_bootstrap_steps,
@@ -36,6 +37,31 @@ from portacode.connection.handlers.proxmox_infra import (
 
 
 class ProxmoxInfraHandlerTests(TestCase):
+    @patch("portacode.connection.handlers.proxmox_infra.get_infra_snapshot", return_value={})
+    @patch("portacode.connection.handlers.proxmox_infra._update_container_record")
+    @patch("portacode.connection.handlers.proxmox_infra._start_container")
+    @patch("portacode.connection.handlers.proxmox_infra._stop_container")
+    @patch("portacode.connection.handlers.proxmox_infra._ensure_container_managed")
+    @patch("portacode.connection.handlers.proxmox_infra._resolve_vmid_for_device", return_value=101)
+    @patch("portacode.connection.handlers.proxmox_infra._get_node_from_config", return_value="pve")
+    @patch("portacode.connection.handlers.proxmox_infra._connect_proxmox")
+    @patch("portacode.connection.handlers.proxmox_infra._ensure_infra_configured", return_value={})
+    def test_restart_validates_child_then_stops_and_starts_once(
+        self, _config, connect, _node, _resolve, ensure_managed, stop, start, update, _snapshot
+    ):
+        stop.return_value = ({"exitstatus": "OK", "status": "stopped"}, 1.0)
+        start.return_value = ({"exitstatus": "OK", "status": "running"}, 2.0)
+        handler = RestartProxmoxContainerHandler(MagicMock(), {})
+
+        result = handler.execute({"child_device_id": "42"})
+
+        ensure_managed.assert_called_once_with(connect.return_value, "pve", 101, device_id="42")
+        stop.assert_called_once_with(connect.return_value, "pve", 101)
+        start.assert_called_once_with(connect.return_value, "pve", 101)
+        update.assert_called_once_with(101, {"status": "running"})
+        self.assertEqual(result["action"], "restart")
+        self.assertTrue(result["success"])
+
     def test_container_config_memory_is_always_mib_even_above_10000(self):
         self.assertEqual(
             _pick_container_ram_mib("lxc", {"memory": 32768}, {"maxmem": 34359738368}),

{portacode-2.0.0.dev0 → portacode-2.0.1}/portacode/connection/terminal.py

@@ -74,6 +74,7 @@ from .handlers import (
     StartPortacodeServiceHandler,
     StartProxmoxContainerHandler,
     StopProxmoxContainerHandler,
+    RestartProxmoxContainerHandler,
     RemoveProxmoxContainerHandler,
     CloudflareTunnelSetupHandler,
     CloudflareForwardingHandler,
@@ -110,6 +111,10 @@ from portacode.tunneling.privileged import read_text, run, write_text
 logger = logging.getLogger(__name__)
 EXPOSED_SERVICES_MONITOR_PATH = "/etc/portacode/exposed_services.json"
 EXPOSED_SERVICES_MONITOR_INTERVAL_S = 2.0
+SYSTEM_INFO_INTERVAL_S = 10.0
+# System information includes optional Proxmox and Playwright probes.  Those
+# probes must never hold up the websocket loop; ping_timeout is only 20s.
+SYSTEM_INFO_COLLECTION_TIMEOUT_S = 8.0
 EXPOSED_SERVICES_MISSING_SIGNATURE = "__missing__"
 EXPOSED_SERVICES_INVALID_SIGNATURE = "__invalid__"
 EXPOSED_SERVICES_ENV_PATH = Path("/etc/portacode/exposed_services.env")
@@ -595,6 +600,7 @@ class TerminalManager:
         self._command_registry.register(StartPortacodeServiceHandler)
         self._command_registry.register(StartProxmoxContainerHandler)
         self._command_registry.register(StopProxmoxContainerHandler)
+        self._command_registry.register(RestartProxmoxContainerHandler)
         self._command_registry.register(RemoveProxmoxContainerHandler)
         self._command_registry.register(RevertProxmoxInfraHandler)
         self._command_registry.register(CloudflareTunnelSetupHandler)
@@ -774,16 +780,46 @@ class TerminalManager:
 
     async def _periodic_system_info(self) -> None:
         """Send system_info event every 10 seconds when clients are connected."""
+        collection_task: Optional[asyncio.Task] = None
         while True:
             try:
-                await asyncio.sleep(10)
-                if self._client_session_manager.has_interested_clients():
+                await asyncio.sleep(SYSTEM_INFO_INTERVAL_S)
+                if not self._client_session_manager.has_interested_clients():
+                    continue
+
+                # SystemInfoHandler is synchronous and, on Proxmox hosts, may
+                # wait on the five-minute inventory reconciliation or a slow
+                # local API call.  Run one collection at a time off-loop so a
+                # slow probe cannot starve websocket reads, pings, or pongs.
+                if collection_task is None:
                     from .handlers.system_handlers import SystemInfoHandler
+
                     handler = SystemInfoHandler(self._control_channel, self._context)
-                    system_info = handler.execute({})
-                    await self._send_session_aware(system_info)
+                    collection_task = asyncio.create_task(
+                        asyncio.to_thread(handler.execute, {})
+                    )
+                try:
+                    system_info = await asyncio.wait_for(
+                        asyncio.shield(collection_task),
+                        timeout=SYSTEM_INFO_COLLECTION_TIMEOUT_S,
+                    )
+                except asyncio.TimeoutError:
+                    logger.warning(
+                        "System info collection is still running after %.1fs; "
+                        "keeping websocket responsive and skipping this update",
+                        SYSTEM_INFO_COLLECTION_TIMEOUT_S,
+                    )
+                    continue
+
+                collection_task = None
+                await self._send_session_aware(system_info)
+            except asyncio.CancelledError:
+                if collection_task is not None:
+                    collection_task.cancel()
+                raise
             except Exception as exc:
                 logger.exception("Error in periodic system info: %s", exc)
+                collection_task = None
                 continue
 
     async def _periodic_provisioning_template_maintenance(self) -> None:

{portacode-2.0.0.dev0 → portacode-2.0.1}/portacode/connection/test_guest_host_terminal.py

@@ -30,6 +30,21 @@ class Registry:
         return self.handler if command == self.handler.command_name else None
 
 
+class CommandRecordingHandler(SyncHandler):
+    def __init__(self, control_channel, session, command):
+        super().__init__(control_channel, session)
+        self._command = command
+        self.messages = []
+
+    @property
+    def command_name(self):
+        return self._command
+
+    def execute(self, message):
+        self.messages.append(message)
+        return {"event": "handled", "command": self._command}
+
+
 def request(request_id="ghr-1", target="42"):
     return {
         "type": GUEST_HOST_REQUEST,
@@ -76,11 +91,36 @@ class GuestHostTerminalTests(IsolatedAsyncioTestCase):
         await self.manager._handle_guest_host_request(envelope)
         self.assertEqual(self.manager._control_channel.sent, [])
 
-    async def test_reserved_but_unimplemented_request_type_is_rejected(self):
+    async def test_enabled_request_without_registered_handler_is_rejected(self):
         envelope = request()
         envelope["command"] = "stop_proxmox_container"
         envelope["authorization"]["operation"] = "power.stop"
         await self.manager._handle_guest_host_request(envelope)
         ack, result = self.manager._control_channel.sent
-        self.assertFalse(ack["data"]["accepted"])
-        self.assertEqual(result["data"]["error_code"], "unsupported_request_type")
+        self.assertTrue(ack["data"]["accepted"])
+        self.assertEqual(result["data"]["error_code"], "handler_unavailable")
+
+    async def test_each_advertised_operation_delegates_to_existing_handler(self):
+        cases = (
+            ("start_proxmox_container", "power.start"),
+            ("stop_proxmox_container", "power.stop"),
+            ("restart_proxmox_container", "power.reboot"),
+            ("remove_proxmox_container", "delete"),
+            ("create_proxmox_container", "provision"),
+        )
+        for command, operation in cases:
+            with self.subTest(command=command):
+                handler = CommandRecordingHandler(self.manager._control_channel, {}, command)
+                self.manager._command_registry = Registry(handler)
+                self.manager._control_channel.sent.clear()
+                envelope = request(request_id=f"ghr-{command}")
+                envelope["command"] = command
+                envelope["authorization"]["operation"] = operation
+
+                await self.manager._handle_guest_host_request(envelope)
+
+                ack, result = self.manager._control_channel.sent
+                self.assertTrue(ack["data"]["accepted"])
+                self.assertTrue(result["data"]["success"])
+                self.assertEqual(len(handler.messages), 1)
+                self.assertEqual(handler.messages[0]["child_device_id"], "42")

portacode-2.0.1/portacode/tests/test_terminal_periodic_system_info.py

@@ -0,0 +1,78 @@
+import asyncio
+import threading
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+
+from portacode.connection import terminal
+from portacode.connection.handlers.system_handlers import SystemInfoHandler
+
+
+def _manager_with_interested_client():
+    manager = object.__new__(terminal.TerminalManager)
+    manager._client_session_manager = SimpleNamespace(
+        has_interested_clients=lambda: True
+    )
+    manager._control_channel = object()
+    manager._context = {}
+    manager._send_session_aware = AsyncMock()
+    return manager
+
+
+@pytest.mark.asyncio
+async def test_slow_system_info_does_not_block_loop_or_start_duplicate_collection(
+    monkeypatch,
+):
+    started = threading.Event()
+    release = threading.Event()
+    calls = 0
+
+    def blocking_execute(_self, _message):
+        nonlocal calls
+        calls += 1
+        started.set()
+        release.wait(timeout=1)
+        return {"event": "system_info", "info": {}}
+
+    monkeypatch.setattr(SystemInfoHandler, "execute", blocking_execute)
+    monkeypatch.setattr(terminal, "SYSTEM_INFO_INTERVAL_S", 0.001)
+    monkeypatch.setattr(terminal, "SYSTEM_INFO_COLLECTION_TIMEOUT_S", 0.005)
+    manager = _manager_with_interested_client()
+    periodic = asyncio.create_task(manager._periodic_system_info())
+
+    try:
+        assert await asyncio.to_thread(started.wait, 0.2)
+        # If collection ran on the event loop, this timer could not fire while
+        # blocking_execute waits. Several timeout cycles must still reuse the
+        # same in-flight worker.
+        await asyncio.wait_for(asyncio.sleep(0.02), timeout=0.05)
+        assert calls == 1
+        manager._send_session_aware.assert_not_awaited()
+    finally:
+        release.set()
+        periodic.cancel()
+        with pytest.raises(asyncio.CancelledError):
+            await periodic
+
+
+@pytest.mark.asyncio
+async def test_completed_system_info_is_sent(monkeypatch):
+    payload = {"event": "system_info", "info": {"proxmox": {}}}
+    monkeypatch.setattr(SystemInfoHandler, "execute", lambda _self, _message: payload)
+    monkeypatch.setattr(terminal, "SYSTEM_INFO_INTERVAL_S", 0.001)
+    monkeypatch.setattr(terminal, "SYSTEM_INFO_COLLECTION_TIMEOUT_S", 0.1)
+    manager = _manager_with_interested_client()
+    periodic = asyncio.create_task(manager._periodic_system_info())
+
+    try:
+        async def wait_for_send():
+            while not manager._send_session_aware.await_count:
+                await asyncio.sleep(0.001)
+
+        await asyncio.wait_for(wait_for_send(), timeout=0.2)
+        manager._send_session_aware.assert_awaited_with(payload)
+    finally:
+        periodic.cancel()
+        with pytest.raises(asyncio.CancelledError):
+            await periodic

{portacode-2.0.0.dev0 → portacode-2.0.1}/portacode.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: portacode
-Version: 2.0.0.dev0
+Version: 2.0.1
 Summary: Device agent for the AI platform that builds, tests, deploys, and operates real software
 Home-page: https://portacode.com/
 Author: Meena Erian

{portacode-2.0.0.dev0 → portacode-2.0.1}/portacode.egg-info/SOURCES.txt

@@ -374,6 +374,7 @@ portacode/tests/test_github_credential.py
 portacode/tests/test_image_read_handler.py
 portacode/tests/test_resumable_transfer_handlers.py
 portacode/tests/test_system_handlers.py
+portacode/tests/test_terminal_periodic_system_info.py
 portacode/tunneling/__init__.py
 portacode/tunneling/cloudflared_login.py
 portacode/tunneling/ensure_cloudflared.py