portacode 1.4.12.dev9__tar.gz → 1.4.15.dev16__tar.gz

{portacode-1.4.12.dev9 → portacode-1.4.15.dev16}/PKG-INFO

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

{portacode-1.4.12.dev9 → portacode-1.4.15.dev16}/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.15.dev16'
+__version_tuple__ = version_tuple = (1, 4, 15, 'dev16')
 
 __commit_id__ = commit_id = None

{portacode-1.4.12.dev9 → portacode-1.4.15.dev16}/portacode/connection/handlers/WEBSOCKET_PROTOCOL.md

@@ -27,6 +27,10 @@ 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.
 
+### Proxying infrastructure updates
+
+Portacode infrastructure devices (like the proxmox host) can send events on behalf of the LXC Devices they manage. Such messages include the optional `on_behalf_of_device` field and the server silently replaces `device_id` with that child device before routing. The gateway enforces that the sender is the child’s `proxmox_parent` (via `Device.proxmox_parent`) so only the infrastructure owner can impersonate a child device. Messages that fail this check are dropped.
+
 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
@@ -361,6 +365,9 @@ Creates a Portacode-managed LXC container, starts it, and bootstraps the Portaco
 *   `username` (string, optional): OS user to provision (defaults to `svcuser`).
 *   `password` (string, optional): Password for the user (used only during provisioning).
 *   `ssh_key` (string, optional): SSH public key to add to the user.
+*   `device_id` (string, required): ID of the dashboard Device record that represents the container. The handler persists this value in the host metadata file so related events can always be correlated back to that Device.
+*   `device_public_key` (string, optional): PEM-encoded Portacode public key. When supplied together with `device_private_key` the handler injects the keypair, records the device metadata, and runs `portacode service install` automatically.
+*   `device_private_key` (string, optional): PEM-encoded private key that pairs with `device_public_key`. Both key fields must be present for the automatic service-install mode.
 
 **Responses:**
 
@@ -418,6 +425,9 @@ Emitted after a successful `create_proxmox_container` action. Contains the new c
 *   `public_key` (string): Portacode public auth key created inside the new container.
 *   `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).
+*   `device_id` (string): Mirrors the dashboard Device ID supplied with `create_proxmox_container`. The handler records this value in the container metadata file so subsequent events can reference the same Device.
+*   `on_behalf_of_device` (string): Same value as `device_id` when the container host is reporting progress for the child device; only proxmox parents may include this field.
+*   `service_installed` (boolean): True when the handler already ran `portacode service install` (with a provided keypair); otherwise it remains False and the dashboard can call `start_portacode_service`.
 
 ### `proxmox_container_progress`
 
@@ -434,6 +444,7 @@ Sent intermittently while `create_proxmox_container` is executing so callers can
 *   `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.
+ *   `on_behalf_of_device` (string, optional): When present the proxmox device is reporting progress for the referenced dashboard device; the gateway verifies the proxmox node is the child’s `proxmox_parent` before routing the event.
 
 ### `start_portacode_service`
 
@@ -450,6 +461,7 @@ Runs `sudo portacode service install` inside the container after the dashboard h
 *   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.
+*   When `create_proxmox_container` already provided a dashboard-generated keypair, the handler may have installed the service already, so this call is optional unless you need to re-run the install.
 
 ### `proxmox_service_started`
 
@@ -1171,6 +1183,8 @@ Emitted after a successful `create_proxmox_container` action to report the newly
 *   `public_key` (string): Portacode public auth key discovered inside the container.
 *   `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.
+*   `device_id` (string): Mirrors the device ID supplied with `create_proxmox_container` and persisted inside the host metadata file for this CT.
+*   `on_behalf_of_device` (string): Same value as `device_id` when the container host is reporting progress for the child device.
 
 ### `proxmox_container_progress`
 
@@ -1187,6 +1201,7 @@ Sent continuously while `create_proxmox_container` runs so dashboards can show a
 *   `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.
+*   `on_behalf_of_device` (string, optional): Mirrors the child device ID when a proxmox host reports progress for that child; only proxmox parents can supply this field.
 
 ### `proxmox_container_action`