dsh-pve-vm 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -3,6 +3,72 @@
 All notable changes to this plugin are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), versions follow [SemVer](https://semver.org/).
 
+## [0.2.0] — 2026-10-13
+
+Watch the agent work: a live VM screen in the right sidebar of the web UI.
+
+### Added
+
+* **The “VM screen” tab** — a right-sidebar panel that streams the frames the agent sees. The frames
+  come from the agent's own RFB session, so no second VNC session appears and the `qm vncproxy`
+  password is never reset; captures and tools share one session queue. Watch-only by design: the
+  panel injects nothing into the guest.
+* **`viewAutoOpen`** (off by default) — reveal the tab by itself when the agent touches a console.
+* **`viewFollowAgent`** (on by default) — the panel follows the VM the agent works with; a VM chip
+  pins it by hand. Watching never counts as agent work: frame requests suppress the activity mark
+  (`withConsole(..., { mark: false })`), so the panel cannot chase itself.
+* **`viewFps`** (2) and **`viewScale`** (2) — frame pace and resolution divisor, both changeable on
+  the fly inside the panel.
+* **Host routes** `/pve-vm/console/state`, `/frame` and `/release` on the harness web server,
+  registered only when the composition has a `webServer`. They carry a loopback-only fence: Host must
+  be loopback, a present Origin must match Host, `sec-fetch-site: cross-site` is refused and POST must
+  be `application/json`. A harness bound to a LAN therefore keeps the panel dark.
+* `RfbClient.waitForUpdate({ idleOk: true })` — silence at a message boundary means "the screen did
+  not change" instead of an error, while a timeout inside a message stays fatal.
+
+### Fixed
+
+* **`inputChannel` and `sendkeyDelayMs` never reached the tools.** Both keys were missing from
+  `CONFIG_KEYS`, so `snapshot()` dropped them and every run silently used the built-in `auto`/80 ms
+  defaults. The form accepted the values, the code ignored them.
+
+## [0.1.1] — 2026-10-13
+
+Linux guest support. Everything below was found by running the plugin against a real RedOS 8
+guest with a MATE desktop, not by reading the code.
+
+### Fixed
+
+* **Guest OS detection rejected almost every Linux distribution.** The guest agent reports `id`
+  from `/etc/os-release`, and only IDs containing `linux` were accepted — RedOS reports `redos`,
+  Debian `debian`, Ubuntu `ubuntu`. All of them landed in `other` and every `vm_*` tool answered
+  *running a shell command is not supported for guest OS «other»*, so the whole guest-agent half
+  was dead on Linux. Windows was unaffected (`mswindows`), which is why it went unnoticed.
+  Windows is now matched first, Linux by `id`/`name`/`pretty-name`, and a non-Windows guest that
+  answered `get-osinfo` with a non-empty `kernel-release` counts as Linux.
+* **`vm_type_text` typed nothing on a GDM desktop.** The built-in typing script used
+  `$home/.Xauthority`, which does not exist when GDM owns the session — RedOS and RHEL keep the
+  file at `/run/user/<uid>/gdm/Xauthority`. `xdotool` then talked to the X server with no
+  authorization at all, failed with *No protocol specified*, and the text never appeared. The
+  script now tries `~/.Xauthority`, then the GDM path, then any `/run/user/<uid>/*/Xauthority`.
+* **`vm_type_text` could not submit text.** `text=$(… | base64 -d)` — command substitution strips
+  trailing newlines, so text ending in `"\n"` was typed without pressing Enter and the shell
+  prompt never came back.
+* **Console errors hid the actual cause.** When the node's `sshd` does not accept `AcceptEnv`,
+  `LC_PVE_TICKET` never arrives and `qm vncproxy` exits with a precise
+  *LC_PVE_TICKET not set, VNC proxy without password is forbidden* — but the RFB reader saw EOF
+  before ssh had finished exiting, so only *the VNC stream was closed by the node* surfaced. The
+  ssh stderr is now reported (after a short grace period), both during the handshake and when a
+  live session dies mid-way.
+
+### Known limitations
+
+* Proxmox applies a **default 5-second timeout to QMP commands** (`PVE/QMPClient.pm`), and
+  `guest-exec` waits for the guest agent to acknowledge. While a previous long command is still
+  running inside the guest that acknowledgement arrives too late and the call fails with
+  *qmp command 'guest-exec' failed - got timeout*. On an idle guest 10 out of 10 calls complete
+  in about a second. `vm_exec` is currently synchronous and does not retry.
+
 ## [0.1.0] — 2026-10-13
 
 Initial public release.

package/README.md

@@ -30,6 +30,9 @@ agent ──► plugin ──► ssh ──► node: qm vncproxy ──► unix
 * **Clipboard** — `console_paste` writes UTF-8 text into the guest clipboard over RFB and presses
   Ctrl+V; `console_clipboard` reads the guest clipboard back, so text can leave the VM without OCR.
 * **A settings card** in the web UI (English and Russian labels), backed by the profile patch layer.
+* **A live screen panel** — the “VM screen” tab in the right sidebar shows the frames the agent
+  sees, taken from the very same VNC session, while the agent works. It follows the agent's VM
+  automatically or stays on the VM you pick by hand. Watching only: the panel never clicks or types.
 * **Zero runtime dependencies** — RFB, DES authentication, keysym tables and PNG encoding are
   implemented in this package on top of `node:crypto` and `node:zlib`. There is nothing to install
   on the host, and nothing to install on the node either.
@@ -95,6 +98,10 @@ layer, and the same values can be edited there by hand:
     sessionIdleMs: 300000
     guestTimeoutMs: 60000
     guestTypeCommand: ''        # script for typing non-ASCII text into a Linux guest
+    viewAutoOpen: false         # open the "VM screen" tab by itself when the agent touches a console
+    viewFollowAgent: true       # the panel follows the VM the agent works with
+    viewFps: 2                  # frame pace in the panel, 1–4
+    viewScale: 2                # frame resolution divisor: 1 native, 2 half, 4 quarter
 ```
 
 **First run checklist**
@@ -137,6 +144,33 @@ Every action tool accepts a common tail: `observe` (return a frame after the act
 | `vm_type_text` | `vmid`, `text`, `settleMs?`, `observe?` | Type text through the best available channel: ASCII → console, non-ASCII → the user session on Windows / `xdotool`–`wtype` on Linux. |
 | `vm_status` | `vmid?` | Is the VM allowed, does the agent answer, which OS, are there open console sessions. |
 
+## Watch the VM screen live
+
+The **VM screen** tab in the right sidebar shows what the agent sees while it works. Add it from the
+sidebar guide, or let `viewAutoOpen` reveal it the moment the agent touches a console.
+
+* The frames are taken from the agent's own RFB session — **no second VNC session appears** and the
+  `qm vncproxy` password is never reset under the agent's feet. Captures and the agent's tools share
+  one session queue, so they never tear the stream for each other.
+* `viewFollowAgent` keeps the panel on the VM the agent is working with; clicking a VM chip pins the
+  panel to that VM instead. `viewFps` (1–4) and `viewScale` (1 / 2 / 4) control the pace and the
+  resolution, and both can be changed on the fly inside the panel.
+* The panel is **watch-only**: no clicks, no typing, nothing is injected into the guest. A blank
+  frame is called out explicitly — the guest blanked its display or is locked.
+* Frames are served by the plugin's own routes (`/pve-vm/console/frame`, `/state`, `/release`) on the
+  harness web server, behind a loopback-only fence: a request is answered only when the `Host` is
+  loopback (`localhost`, `127.0.0.0/8`, `[::1]`), a present `Origin` matches `Host`, and
+  `sec-fetch-site: cross-site` is refused. If you bind the harness to your LAN, the panel stays dark
+  by design — the same fence the harness applies to `/api`.
+* **The fence is loopback, not the harness token.** These routes live outside `/api`, so the
+  harness URL token does not cover them (the browser-skill overview works the same way). Any
+  process on the same machine can therefore pull frames or call `/release`; that is the accepted
+  price of loading frames without a token on a single-user box. Serve VMs you would not mind a
+  local user seeing, and harden with a harness-issued token if that is not acceptable.
+* The console session stays open while the panel streams (the idle reaper does not take it); the
+  panel's “disconnect console” button closes it immediately. Streaming pauses by itself when the tab
+  is hidden.
+
 ## How it works
 
 * **Transport.** A VM has no TCP VNC port: QEMU listens on the unix socket