portacode 1.4.11.dev5__py3-none-any.whl → 1.4.12.dev3__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.4.11.dev5'
-__version_tuple__ = version_tuple = (1, 4, 11, 'dev5')
+__version__ = version = '1.4.12.dev3'
+__version_tuple__ = version_tuple = (1, 4, 12, 'dev3')
 
 __commit_id__ = commit_id = None

portacode/connection/handlers/WEBSOCKET_PROTOCOL.md

@@ -367,6 +367,45 @@ Creates a Portacode-managed LXC container, starts it, and bootstraps the Portaco
 *   On success, the device will emit a [`proxmox_container_created`](#proxmox_container_created-event) event that includes the Portacode auth key produced inside the container.
 *   On failure, the device will emit an [`error`](#error) event.
 
+### `start_proxmox_container`
+
+Starts a previously provisioned, Portacode-managed LXC container. Handled by [`StartProxmoxContainerHandler`](./proxmox_infra.py).
+
+**Payload Fields:**
+
+*   `ctid` (string, required): Identifier of the container to start.
+
+**Responses:**
+
+*   Emits a [`proxmox_container_action`](#proxmox_container_action-event) event with `action="start"` and the refreshed infra snapshot.
+*   Emits an [`error`](#error) event when the request cannot be fulfilled (e.g., missing infra config, CT not tagged as managed, or API failure).
+
+### `stop_proxmox_container`
+
+Stops a running Portacode-managed container. Handled by [`StopProxmoxContainerHandler`](./proxmox_infra.py).
+
+**Payload Fields:**
+
+*   `ctid` (string, required): Identifier of the container to stop.
+
+**Responses:**
+
+*   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.
+
+### `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).
+
+**Payload Fields:**
+
+*   `ctid` (string, required): Identifier of the container to delete.
+
+**Responses:**
+
+*   Emits a [`proxmox_container_action`](#proxmox_container_action-event) event with `action="remove"` and the refreshed infra snapshot after deletion.
+*   Emits an [`error`](#error) event on failure.
+
 ### `proxmox_container_created`
 
 Emitted after a successful `create_proxmox_container` action. Contains the new container ID, the Portacode public key produced inside the container, and the bootstrap logs.
@@ -380,6 +419,48 @@ Emitted after a successful `create_proxmox_container` action. Contains the new c
 *   `container` (object): Metadata such as `vmid`, `hostname`, `template`, `storage`, `disk_gib`, `ram_mib`, and `cpus`.
 *   `setup_steps` (array[object]): Detailed bootstrap step results (name, stdout/stderr, elapsed time, and status).
 
+### `proxmox_container_progress`
+
+Sent intermittently while `create_proxmox_container` is executing so callers can display a progress indicator. Each notification describes the currently running step (validation, provisioning, or each bootstrap command) and whether it succeeded or failed.
+
+**Event Fields:**
+
+*   `step_index` (integer): 1-based index of the current step inside the entire provisioning sequence.
+*   `total_steps` (integer): Total number of steps that must run before provisioning completes.
+*   `step_name` (string): Internal step identifier (e.g., `create_container`, `apt_update`, `portacode_connect`).
+*   `step_label` (string): Human-friendly label suitable for UI (e.g., `Create container`, `Apt update`).
+*   `status` (string): One of `in_progress`, `completed`, or `failed`.
+*   `phase` (string): Either `lifecycle` (environment/container lifecycle) or `bootstrap` (per-command bootstrap work).
+*   `message` (string): Short description of what is happening or why a failure occurred.
+*   `details` (object, optional): Contains `attempt` (if retries were needed) and `error_summary` when a step fails.
+*   `request_id` (string, optional): Mirrors the request ID from the incoming `create_proxmox_container` payload when available.
+
+### `start_portacode_service`
+
+Runs `sudo portacode service install` inside the container after the dashboard has created the corresponding Device record with the supplied public key.
+
+**Payload Fields:**
+
+*   `ctid` (string, required): Container ID target.
+*   `step_index` (integer, required): Next step index to render inside `proxmox_container_progress`.
+*   `total_steps` (integer, required): The overall total number of steps (including lifecycle, bootstrap, and service installation).
+
+**Responses:**
+
+*   Emits additional [`proxmox_container_progress`](#proxmox_container_progress-event) events to report the authentication and service-install steps.
+*   On success, emits a [`proxmox_service_started`](#proxmox_service_started-event).
+*   On failure, emits a generic [`error`](#error) event.
+
+### `proxmox_service_started`
+
+Indicates that `portacode service install` finished successfully inside a managed container.
+
+**Event Fields:**
+
+*   `success` (boolean): True when the install succeeded.
+*   `message` (string): Success summary (e.g., `Portacode service install completed`).
+*   `ctid` (string): Container ID.
+
 ### `clock_sync_request`
 
 Internal event that devices send to the gateway to request the authoritative server timestamp (used for adjusting `portacode.utils.ntp_clock`). The gateway responds immediately with [`clock_sync_response`](#clock_sync_response).
@@ -1025,21 +1106,37 @@ Provides system information in response to a `system_info` action. Handled by [`
     *   `proxmox` (object): Detection hints for Proxmox VE nodes:
         *   `is_proxmox_node` (boolean): True when Proxmox artifacts (e.g., `/etc/proxmox-release`) exist.
         *   `version` (string|null): Raw contents of `/etc/proxmox-release` when readable.
-        *   `infra` (object): Portacode infrastructure configuration snapshot:
-            *   `configured` (boolean): True when `setup_proxmox_infra` stored an API token.
-            *   `host` (string|null): Hostname used for the API client (usually `localhost`).
-            *   `node` (string|null): Proxmox node name that was targeted.
-            *   `user` (string|null): API token owner (e.g., `root@pam`).
-            *   `token_name` (string|null): API token identifier.
-            *   `default_storage` (string|null): Storage pool chosen for future containers.
-            *   `templates` (array[string]): Cached list of available LXC templates.
-            *   `last_verified` (string|null): ISO timestamp when the token was last validated.
-            *   `network` (object):
-                *   `applied` (boolean): True when the bridge/NAT services were successfully configured.
-                *   `message` (string|null): Informational text about the network setup attempt.
-                *   `bridge` (string): The bridge interface configured (typically `vmbr1`).
-                *   `health` (string|null): `"healthy"` when the connectivity verification succeeded.
-            *   `node_status` (object|null): Status response returned by the Proxmox API when validating the token.
+            *   `infra` (object): Portacode infrastructure configuration snapshot:
+                *   `configured` (boolean): True when `setup_proxmox_infra` stored an API token.
+                *   `host` (string|null): Hostname used for the API client (usually `localhost`).
+                *   `node` (string|null): Proxmox node name that was targeted.
+                *   `user` (string|null): API token owner (e.g., `root@pam`).
+                *   `token_name` (string|null): API token identifier.
+                *   `default_storage` (string|null): Storage pool chosen for future containers.
+                *   `templates` (array[string]): Cached list of available LXC templates.
+                *   `last_verified` (string|null): ISO timestamp when the token was last validated.
+                *   `network` (object):
+                    *   `applied` (boolean): True when the bridge/NAT services were successfully configured.
+                    *   `message` (string|null): Informational text about the network setup attempt.
+                    *   `bridge` (string): The bridge interface configured (typically `vmbr1`).
+                    *   `health` (string|null): `"healthy"` when the connectivity verification succeeded.
+                *   `node_status` (object|null): Status response returned by the Proxmox API when validating the token.
+                *   `managed_containers` (object): Cached summary of the Portacode-managed containers:
+                    *   `updated_at` (string): ISO timestamp when this snapshot was last refreshed.
+                    *   `count` (integer): Number of managed containers.
+                    *   `total_ram_mib` (integer): RAM footprint summed across all containers.
+                    *   `total_disk_gib` (integer): Disk footprint summed across all containers.
+                    *   `total_cpu_share` (number): CPU shares requested across all containers.
+                    *   `containers` (array[object]): Container summaries with the following fields:
+                        *   `vmid` (string|null): Numeric CT ID.
+                        *   `hostname` (string|null): Hostname configured in the CT.
+                        *   `template` (string|null): Template identifier used.
+                        *   `storage` (string|null): Storage pool backing the rootfs.
+                        *   `disk_gib` (integer): Rootfs size in GiB.
+                        *   `ram_mib` (integer): Memory size in MiB.
+                        *   `cpu_share` (number): vCPU-equivalent share requested at creation.
+                        *   `status` (string): Lowercase lifecycle status (e.g., `running`, `stopped`, `deleted`).
+                        *   `created_at` (string|null): ISO timestamp recorded when the CT was provisioned.
     *   `portacode_version` (string): Installed CLI version returned by `portacode.__version__`.
 
 ### `proxmox_infra_configured`
@@ -1075,6 +1172,36 @@ Emitted after a successful `create_proxmox_container` action to report the newly
 *   `container` (object): Metadata such as `vmid`, `hostname`, `template`, `storage`, `disk_gib`, `ram_mib`, and `cpus`.
 *   `setup_steps` (array[object]): Detailed bootstrap step reports including stdout/stderr, elapsed time, and pass/fail status.
 
+### `proxmox_container_progress`
+
+Sent continuously while `create_proxmox_container` runs so dashboards can show a progress bar tied to each lifecycle and bootstrap step.
+
+**Event Fields:**
+
+*   `step_index` (integer): 1-based position of the step inside the entire provisioning workflow.
+*   `total_steps` (integer): Total number of lifecycle and bootstrap steps for the current operation.
+*   `step_name` (string): Internal identifier (e.g., `validate_environment`, `install_deps`, `portacode_connect`).
+*   `step_label` (string): Friendly label suitable for the UI.
+*   `status` (string): One of `in_progress`, `completed`, or `failed`.
+*   `phase` (string): Either `lifecycle` (node validation/container lifecycle) or `bootstrap` (commands run inside the CT).
+*   `message` (string): Short human-readable description of the action or failure.
+*   `details` (object, optional): Contains `attempt` (when retries are used) and `error_summary` on failure.
+*   `request_id` (string, optional): Mirrors the `create_proxmox_container` request when provided.
+
+### `proxmox_container_action`
+
+Emitted after `start_proxmox_container`, `stop_proxmox_container`, or `remove_proxmox_container` commands complete. Each event includes the refreshed infra snapshot so dashboards can immediately display the latest managed container totals even though the `proxmox.infra.managed_containers` cache updates only every ~30 seconds.
+
+**Event Fields:**
+
+*   `action` (string): The action that ran (`start`, `stop`, or `remove`).
+*   `success` (boolean): True when the requested action succeeded.
+*   `ctid` (string): Target CT ID.
+*   `message` (string): Human-friendly summary (e.g., `Stopped container 103`).
+*   `status` (string): The container’s new status (e.g., `running`, `stopped`, `deleted`).
+*   `details` (object, optional): Exit status information (e.g., `exitstatus`, `stop_exitstatus`, `delete_exitstatus`).
+*   `infra` (object): Same snapshot described under [`system_info`](#system_info-event) `proxmox.infra`, including the updated `managed_containers` summary.
+
 ### <a name="clock_sync_response"></a>`clock_sync_response`
 
 Reply sent by the gateway immediately after receiving a `clock_sync_request`. Devices use this event plus the measured round-trip time to keep their local `ntp_clock` offset accurate.

portacode/connection/handlers/__init__.py

@@ -45,6 +45,10 @@ from .proxmox_infra import (
     ConfigureProxmoxInfraHandler,
     CreateProxmoxContainerHandler,
     RevertProxmoxInfraHandler,
+    StartPortacodeServiceHandler,
+    StartProxmoxContainerHandler,
+    StopProxmoxContainerHandler,
+    RemoveProxmoxContainerHandler,
 )
 
 __all__ = [
@@ -84,6 +88,10 @@ __all__ = [
     "ProjectStateGitUnstageHandler",
     "ProjectStateGitRevertHandler",
     "ProjectStateGitCommitHandler",
+    "StartPortacodeServiceHandler",
+    "StartProxmoxContainerHandler",
+    "StopProxmoxContainerHandler",
+    "RemoveProxmoxContainerHandler",
     "UpdatePortacodeHandler",
     "RevertProxmoxInfraHandler",
 ]