dsh-pve-vm 0.1.0 → 0.2.0

package/lib/config.js

@@ -12,7 +12,11 @@ import z from '@deepseek-ai/schemastery';
 /** Text input script inside a Linux guest (used by `vm_type_text`). */
 export const DEFAULT_GUEST_TYPE_COMMAND = [
   'set -e',
-  'text=$(printf %s "$1" | base64 -d)',
+  // `$(...)` strips trailing newlines, and without them the text cannot be
+  // "submitted" with Enter: `vm_type_text` with a trailing \"\\n\" silently typed
+  // the line and left the prompt waiting.
+  'text=$(printf %s "$1" | base64 -d; printf X)',
+  'text=${text%X}',
   'uid=""; home=""; disp=""; xauth=""',
   'for s in $(loginctl list-sessions --no-legend 2>/dev/null | awk \'{print $1}\'); do',
   '  [ "$(loginctl show-session "$s" -p Active --value 2>/dev/null)" = "yes" ] || continue',
@@ -22,7 +26,15 @@ export const DEFAULT_GUEST_TYPE_COMMAND = [
   '  [ -n "$disp" ] && break',
   'done',
   '[ -n "$disp" ] || disp=":0"',
-  '[ -n "$home" ] && [ -f "$home/.Xauthority" ] && xauth="$home/.Xauthority"',
+  '[ -n "$uid" ] || uid=$(id -u)',
+  // XAUTHORITY. GDM (RedOS 8, RHEL) keeps it in /run/user/<uid>/gdm/Xauthority,
+  // and ~/.Xauthority may not exist at all — xdotool then talked to X with no
+  // authorization whatsoever, got "No protocol specified" and typed nothing
+  // (found during acceptance on 2026-10-13, RedOS 8 + MATE + GDM).
+  'if [ -n "$home" ] && [ -f "$home/.Xauthority" ]; then xauth="$home/.Xauthority"',
+  'elif [ -f "/run/user/$uid/gdm/Xauthority" ]; then xauth="/run/user/$uid/gdm/Xauthority"',
+  'else xauth=$(ls -1 /run/user/$uid/*/Xauthority /run/user/$uid/xauth* 2>/dev/null | head -1)',
+  'fi',
   'run() { if [ -n "$xauth" ]; then XAUTHORITY="$xauth" DISPLAY="$disp" "$@"; else DISPLAY="$disp" "$@"; fi; }',
   'if command -v xdotool >/dev/null 2>&1; then run xdotool type --delay 12 --clearmodifiers -- "$text"; exit 0; fi',
   'if command -v wtype >/dev/null 2>&1; then',
@@ -44,10 +56,16 @@ export const CONFIG_KEYS = [
   'allowVmids',
   'enableConsole',
   'enableGuest',
+  'inputChannel',
+  'sendkeyDelayMs',
   'consoleTimeoutMs',
   'sessionIdleMs',
   'guestTimeoutMs',
   'guestTypeCommand',
+  'viewAutoOpen',
+  'viewFollowAgent',
+  'viewFps',
+  'viewScale',
 ];
 
 /** Settings schema: the id of the entry in `cordis.patch.yml` must match `pve-vm`. */
@@ -129,6 +147,36 @@ export const Config = z.object({
       'Script for typing non-ASCII text in a Linux guest: takes the base64 text as its first argument ($1).',
     )
     .volatile(),
+  viewAutoOpen: z
+    .boolean()
+    .default(false)
+    .description(
+      'Open the "VM screen" tab in the right sidebar by itself when the agent touches a VM console.',
+    )
+    .volatile(),
+  viewFollowAgent: z
+    .boolean()
+    .default(true)
+    .description('The panel follows the VM the agent is working with by default.')
+    .volatile(),
+  viewFps: z
+    .number()
+    .step(1)
+    .min(1)
+    .max(4)
+    .default(2)
+    .description('How many frames per second the panel asks the node for (1–4).')
+    .volatile(),
+  viewScale: z
+    .number()
+    .step(1)
+    .min(1)
+    .max(4)
+    .default(2)
+    .description(
+      'Frame resolution divisor in the panel: 1 — native, 2 — half (default), 4 — quarter.',
+    )
+    .volatile(),
 });
 
 /**
@@ -157,7 +205,7 @@ function expandHome(path) {
 /**
  * Reduce the settings slice to a shape convenient for the tools.
  * @param {Record<string, unknown>} section the result of {@link snapshot}.
- * @returns {{ssh:object,allowVmids:number[],enableConsole:boolean,enableGuest:boolean,consoleTimeoutMs:number,sessionIdleMs:number,guestTimeoutMs:number,guestTypeCommand:string}}
+ * @returns {{ssh:object,allowVmids:number[],enableConsole:boolean,enableGuest:boolean,consoleTimeoutMs:number,sessionIdleMs:number,guestTimeoutMs:number,guestTypeCommand:string,view:{autoOpen:boolean,followAgent:boolean,fps:number,scale:number}}}
  */
 export function resolveSettings(section) {
   const allowVmids = Array.isArray(section.allowVmids)
@@ -181,5 +229,25 @@ export function resolveSettings(section) {
     sessionIdleMs: Number(section.sessionIdleMs ?? 300000),
     guestTimeoutMs: Number(section.guestTimeoutMs ?? 60000),
     guestTypeCommand: typeof section.guestTypeCommand === 'string' ? section.guestTypeCommand : DEFAULT_GUEST_TYPE_COMMAND,
+    view: {
+      autoOpen: section.viewAutoOpen === true,
+      followAgent: section.viewFollowAgent !== false,
+      fps: clampNumber(section.viewFps, 1, 4, 2),
+      scale: clampNumber(section.viewScale, 1, 4, 2),
+    },
   };
 }
+
+/**
+ * An integer inside bounds (for the panel fields: fps and the resolution divisor).
+ * @param {unknown} value live settings value.
+ * @param {number} min lower bound.
+ * @param {number} max upper bound.
+ * @param {number} fallback default value.
+ * @returns {number} a usable number.
+ */
+function clampNumber(value, min, max, fallback) {
+  const parsed = Math.round(Number(value));
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.max(min, Math.min(max, parsed));
+}

package/lib/png.js

@@ -106,6 +106,25 @@ export function downscaleBox(image, factor) {
   return { width, height, data: out, scale: 1 / step };
 }
 
+/**
+ * An almost single-colour frame: most often a blanked display or a black lock screen.
+ * The check samples coarsely instead of scanning a million pixels. It lives here, not in
+ * the tools, because the observation panel needs the very same verdict.
+ * @param {{width:number,height:number,data:Uint8Array}} image RGBA frame.
+ * @returns {boolean} true when the frame is practically one colour.
+ */
+export function looksBlank(image) {
+  const step = Math.max(4, Math.floor((image.width * image.height) / 4096)) * 4;
+  let min = 255;
+  let max = 0;
+  for (let i = 0; i < image.data.length; i += step) {
+    const value = image.data[i];
+    if (value < min) min = value;
+    if (value > max) max = value;
+  }
+  return max - min <= 6;
+}
+
 /**
  * Rectangle cropping; the coordinates are clipped to the frame.
  * @param {{width:number,height:number,data:Uint8Array}} image the source RGBA frame.

package/lib/rfb.js

@@ -350,19 +350,38 @@ export class RfbClient extends EventEmitter {
 
   /**
    * Read messages until the next FramebufferUpdate.
-   * @param {{timeoutMs?:number}} [options] wait timeout.
-   * @returns {Promise<{rectangles:number, bytes:number, resized:boolean, cursor:boolean, bell:boolean}>}
+   *
+   * `idleOk` is what the observation panel needs: it asks for an incremental frame
+   * often, and "nothing changed" is a normal answer from QEMU (it simply stays
+   * silent). Silence at a message boundary is safe — the current framebuffer is
+   * returned. A timeout in the middle of a message means half a frame was lost,
+   * which is a real error and the session has to be recreated.
+   * @param {{timeoutMs?:number, idleOk?:boolean}} [options] wait timeout and tolerance for silence.
+   * @returns {Promise<{rectangles:number, bytes:number, resized:boolean, cursor:boolean, bell:boolean, idle?:boolean}>}
    */
   async waitForUpdate(options = {}) {
     const deadline = Date.now() + (options.timeoutMs ?? this.timeoutMs);
+    const idleOk = options.idleOk === true;
     let rectangles = 0;
     let cursorUpdated = false;
     let bell = false;
     let resized = false;
     for (;;) {
       const left = deadline - Date.now();
-      if (left <= 0) throw new RfbError('timeout waiting for an RFB frame', 'TIMEOUT');
-      const type = (await this.reader.exact(1, left))[0];
+      if (left <= 0) {
+        if (idleOk) return { rectangles: 0, bytes: 0, resized: false, cursor: false, bell: false, idle: true };
+        throw new RfbError('timeout waiting for an RFB frame', 'TIMEOUT');
+      }
+      let first;
+      try {
+        first = await this.reader.exact(1, left);
+      } catch (error) {
+        if (idleOk && error?.code === 'TIMEOUT') {
+          return { rectangles: 0, bytes: 0, resized: false, cursor: false, bell: false, idle: true };
+        }
+        throw error;
+      }
+      const type = first[0];
       if (type === 0) {
         const header = await this.reader.exact(3, left);
         const count = header.readUInt16BE(1);

package/lib/routes.js

@@ -0,0 +1,197 @@
+/**
+ * HTTP routes of the observation panel: `/pve-vm/console/*`.
+ *
+ * Why HTTP and not a harness RPC. The panel is an ordinary page of the same origin,
+ * and frames are easy to pull with `fetch`; the browser-skill overview is built the
+ * same way (`/bsk-observation/*`). The routes register on the `webServer` service; a
+ * composition without a web server (a headless profile) simply never registers them,
+ * while the agent tools keep working as usual.
+ *
+ * Security. A VM screen is sensitive: passwords, chats, a working desktop. So these
+ * routes carry their own fence: we answer only when Host is a loopback authority
+ * (localhost / 127.0.0.0/8 / [::1]), a present Origin matches Host, and
+ * `sec-fetch-site: cross-site` is refused outright; POST must be `application/json`,
+ * so a cross-site simple request never reaches the handler. DSH itself applies the
+ * same order of checks to `/api` (`@deepseek-ai/dsh-client-connection`), and so does
+ * browser-skill; it is repeated here so that the published plugin depends on no
+ * internal package.
+ */
+import { VmError } from './session.js';
+
+/** Base path of the panel routes. */
+export const VIEW_BASE = '/pve-vm/console';
+
+/** Error codes to HTTP statuses. */
+const STATUS_BY_CODE = {
+  BAD_VMID: 400,
+  NOT_ALLOWED: 403,
+  CHANNEL_DISABLED: 403,
+  CONSOLE_CLOSED: 409,
+  CONSOLE_FAILED: 502,
+  SSH_FAILED: 502,
+  EOF: 502,
+  TIMEOUT: 504,
+};
+
+/** Answer with JSON. */
+function sendJson(res, status, body) {
+  const payload = Buffer.from(JSON.stringify(body), 'utf8');
+  res.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'content-length': String(payload.length),
+    'cache-control': 'no-store',
+  });
+  res.end(payload);
+}
+
+/** Turn a panel request failure into a response. */
+function fail(res, error) {
+  if (res.headersSent) {
+    res.end();
+    return;
+  }
+  const code = error instanceof VmError ? error.code : undefined;
+  const status = STATUS_BY_CODE[code] ?? 500;
+  sendJson(res, status, { error: error?.message ?? String(error), ...(code ? { code } : {}) });
+}
+
+/**
+ * The fence's verdict: the reason for refusal, or undefined.
+ * @param {import('node:http').IncomingMessage} req the request.
+ * @returns {string|undefined} the reason for refusal.
+ */
+function fenceViolation(req) {
+  const host = req.headers.host ?? '';
+  const hostname = /^\[.*\](?::\d+)?$/.test(host) ? host.slice(1, host.indexOf(']')) : host.split(':')[0];
+  const loopback =
+    hostname === 'localhost' ||
+    hostname.endsWith('.localhost') ||
+    hostname === '::1' ||
+    /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(hostname);
+  if (!loopback) return 'host is not a loopback authority';
+  const origin = req.headers.origin;
+  if (origin !== undefined && origin !== 'null') {
+    let originHost;
+    try {
+      originHost = new URL(origin).host;
+    } catch {
+      return 'unparseable Origin header';
+    }
+    if (originHost !== host) return 'Origin does not match Host';
+  }
+  if (req.headers['sec-fetch-site'] === 'cross-site') return 'sec-fetch-site: cross-site';
+  if (req.method === 'POST') {
+    const contentType = req.headers['content-type'] ?? '';
+    if (!/^\s*application\/json\s*(;|$)/.test(contentType)) return 'POST requires an application/json body';
+  }
+  return undefined;
+}
+
+/** Run the fence; true means the request was already refused and answered. */
+function fenceRejected(req, res) {
+  const violation = fenceViolation(req);
+  if (violation === undefined) return false;
+  sendJson(res, 403, { error: `forbidden: ${violation}` });
+  return true;
+}
+
+/** Read the JSON body of a small request. */
+async function readJsonBody(req) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of req) {
+    size += chunk.length;
+    if (size > 64 * 1024) throw new VmError('request body is too large', 'BAD_BODY');
+    chunks.push(chunk);
+  }
+  if (size === 0) return {};
+  try {
+    return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+  } catch {
+    throw new VmError('request body is not JSON', 'BAD_BODY');
+  }
+}
+
+/**
+ * Register the panel routes on the web server.
+ * @param {object} webServer the `webServer` service.
+ * @param {{view: object}} deps the observation panel.
+ * @returns {() => void} disposer removing the routes.
+ */
+export function registerViewRoutes(webServer, deps) {
+  const view = deps.view;
+  const disposers = [
+    webServer.register({
+      kind: 'exact',
+      path: `${VIEW_BASE}/state`,
+      handler: (req, res) => {
+        if (req.method !== 'GET') {
+          sendJson(res, 405, { error: 'method not allowed' });
+          return;
+        }
+        if (fenceRejected(req, res)) return;
+        try {
+          sendJson(res, 200, view.state());
+        } catch (error) {
+          fail(res, error);
+        }
+      },
+    }),
+    webServer.register({
+      kind: 'exact',
+      path: `${VIEW_BASE}/frame`,
+      handler: async (req, res) => {
+        if (req.method !== 'GET') {
+          sendJson(res, 405, { error: 'method not allowed' });
+          return;
+        }
+        if (fenceRejected(req, res)) return;
+        const url = new URL(req.url ?? '/', 'http://localhost');
+        const rawScale = url.searchParams.get('scale');
+        try {
+          const { png, meta } = await view.frame(Number(url.searchParams.get('vmid')), {
+            scale: rawScale === null ? undefined : Number(rawScale),
+            cursor: url.searchParams.get('cursor') !== '0',
+          });
+          res.writeHead(200, {
+            'content-type': 'image/png',
+            'content-length': String(png.length),
+            'cache-control': 'no-store, max-age=0',
+            'x-pve-vm-vmid': String(meta.vmid),
+            'x-pve-vm-resolution': `${meta.width}x${meta.height}`,
+            'x-pve-vm-capture': `${meta.captureWidth}x${meta.captureHeight}`,
+            'x-pve-vm-scale': String(meta.scale),
+            'x-pve-vm-pointer': `${meta.pointerX},${meta.pointerY}`,
+            'x-pve-vm-cursor': meta.cursorDrawn ? '1' : '0',
+            'x-pve-vm-blank': meta.blank ? '1' : '0',
+            'x-pve-vm-session': meta.sessionAlive ? 'alive' : 'closed',
+          });
+          res.end(png);
+        } catch (error) {
+          fail(res, error);
+        }
+      },
+    }),
+    webServer.register({
+      kind: 'exact',
+      path: `${VIEW_BASE}/release`,
+      handler: async (req, res) => {
+        if (req.method !== 'POST') {
+          sendJson(res, 405, { error: 'method not allowed' });
+          return;
+        }
+        if (fenceRejected(req, res)) return;
+        try {
+          const body = await readJsonBody(req);
+          const closed = view.release(Number(body.vmid));
+          sendJson(res, 200, { closed });
+        } catch (error) {
+          fail(res, error);
+        }
+      },
+    }),
+  ];
+  return () => {
+    for (const dispose of disposers.reverse()) dispose();
+  };
+}

package/lib/session.js

@@ -55,10 +55,20 @@ export class VmController {
     this.sessions = new Map();
     /** @type {Map<number, string>} */
     this.osCache = new Map();
+    /** The last VM whose console the agent touched: the panel auto-opens on it. */
+    this.lastConsole = null;
     this.reaper = setInterval(() => this.#reapIdle(), 30000);
     this.reaper.unref?.();
   }
 
+  /**
+   * The last console use: the observation panel shows this VM.
+   * @returns {{vmid:number, at:number}|null} vmid and time (ms), or null.
+   */
+  lastConsoleUse() {
+    return this.lastConsole;
+  }
+
   /** Validate the VM id against the allowlist and the channel switches. */
   assertAllowed(vmid, channel) {
     const settings = this.deps.settings();
@@ -252,6 +262,19 @@ export class VmController {
     } catch (error) {
       session.alive = false;
       this.#drop(vmid);
+      // RFB sees EOF before ssh has finished exiting, and the most valuable
+      // explanation — the node's stderr — is lost. Give ssh a short grace
+      // period: without it "the VNC stream was closed by the node" cannot tell
+      // an sshd without AcceptEnv (`LC_PVE_TICKET not set, VNC proxy without
+      // password is forbidden`) from a powered-off VM or a busy QMP socket.
+      // Verified by a negative test on 2026-10-13 (sshd on :2222, no AcceptEnv).
+      const detail = await Promise.race([
+        handle.done.then(() => stderr.trim()).catch(() => ''),
+        new Promise((resolve) => setTimeout(() => resolve(''), 1500)),
+      ]);
+      if (detail.length > 0 && error?.code === 'EOF') {
+        throw new VmError(`failed to open the console of VM ${vmid}: ${detail}`, 'CONSOLE_FAILED');
+      }
       throw error;
     }
     this.sessions.set(vmid, session);
@@ -262,12 +285,19 @@ export class VmController {
    * Run an operation with exclusive access to the VM console.
    * @param {number} vmid VM id.
    * @param {(client: RfbClient, session: object) => Promise<T>} operation the action.
-   * @param {{signal?: AbortSignal}} [options]
+   * @param {{signal?: AbortSignal, mark?:boolean}} [options] cancellation and the "the agent worked with this VM" mark.
    * @returns {Promise<T>}
    * @template T
    */
   async withConsole(vmid, operation, options = {}) {
     const id = this.assertAllowed(vmid, 'console');
+    // A mark for the observation panel: it follows the VM the agent works with.
+    // The panel watches frames through this very method, so it has to suppress the
+    // mark (`mark: false`) — otherwise watching declares itself agent work and the
+    // "follow the agent" mode jumps between VMs (seen on a live panel 2026-10-13:
+    // right after a restart `last` named the VM the owner was watching, while no
+    // tool had touched it).
+    if (options.mark !== false) this.lastConsole = { vmid: id, at: Date.now() };
     const session = await this.#consoleSession(id, options.signal);
     const run = async () => {
       if (!session.alive) {
@@ -281,6 +311,12 @@ export class VmController {
         if (error?.code === 'EOF' || error?.code === 'TIMEOUT') {
           session.alive = false;
           this.#drop(id);
+          // A stream that died mid-way is explained by ssh's stderr: for
+          // instance `qm vncproxy` exiting on its own 15-minute idle timeout.
+          const detail = session.stderrText?.() ?? '';
+          if (detail.length > 0) {
+            throw new VmError(`${error.message}; ssh: ${detail}`, error.code);
+          }
         }
         throw error;
       }

package/lib/ssh.js

@@ -72,13 +72,30 @@ export function guestPingCommand(vmid) {
 
 /**
  * Detect the guest OS from the agent's response.
+ *
+ * The guest agent reports `id` from `/etc/os-release` (`ID=`), and every distro
+ * uses its own name there: `redos`, `debian`, `ubuntu`, `altlinux`, `astra-linux`…
+ * So "id == linux" is not a usable Linux test — it filtered out almost every real
+ * distribution (found during acceptance on 2026-10-13: RedOS 8 reports `redos`,
+ * Debian reports `debian`; both landed in `other` and every `vm_*` tool refused
+ * to work). Windows must be checked first: its agent also reports
+ * `kernel-release` (the NT build number), so "has kernel-release => Linux" is
+ * wrong on its own — the order of the checks matters.
+ *
  * @param {unknown} osinfo the parsed `get-osinfo` JSON.
  * @returns {'windows'|'linux'|'other'}
  */
 export function guestOsFamily(osinfo) {
   const id = String(osinfo?.id ?? '').toLowerCase();
-  if (id.includes('windows') || id === 'mswindows') return 'windows';
-  if (id === 'linux' || id.includes('linux')) return 'linux';
+  const name = String(osinfo?.name ?? '').toLowerCase();
+  const pretty = String(osinfo?.['pretty-name'] ?? '').toLowerCase();
+  if (id === 'mswindows' || id.includes('windows') || name.includes('windows')) return 'windows';
+  if (id.includes('linux') || name.includes('linux') || pretty.includes('linux')) return 'linux';
+  // Whatever is left is a non-Windows guest that answered get-osinfo. Only
+  // Windows and Linux are supported, so it is Linux; `kernel-release` is a
+  // sanity check on the reply (an empty agent response never reaches here).
+  const kernel = String(osinfo?.['kernel-release'] ?? '');
+  if (kernel.length > 0) return 'linux';
   return 'other';
 }
 

package/lib/view.js

@@ -0,0 +1,145 @@
+/**
+ * The live VM screen for the observation panel.
+ *
+ * Why a separate module. The agent's tools capture a frame on demand and hand it
+ * back as an attachment; a panel needs something else: often, cheaply, and without
+ * attachments — "what is on screen right now". The frame comes from **the same**
+ * RFB session the tools use (`VmController.withConsole`), therefore:
+ *
+ *   • no second VNC session to the VM appears, and the `qm vncproxy` password is
+ *     not reset under the agent's feet;
+ *   • there is still exactly one session queue — the panel and the agent never
+ *     tear the stream for each other;
+ *   • a session the panel holds open is not reaped by the idle reaper (every
+ *     capture refreshes `lastUsed`).
+ *
+ * Frames are requested incrementally: when the screen did not change QEMU stays
+ * silent and the panel gets the current framebuffer from the client's memory (see
+ * `idleOk` in `RfbClient.waitForUpdate`).
+ */
+import { encodePng, downscaleBox, looksBlank } from './png.js';
+
+/** Lower bound on waiting for QEMU: below it we simply cannot read the answer. */
+const MIN_WAIT_MS = 120;
+/**
+ * Upper bound on waiting. This is exactly how long the panel holds the session
+ * queue when the screen does not change (QEMU stays silent on an incremental
+ * request) — and therefore how long the agent waits for its own operation.
+ * 250 ms is enough: QEMU hands over changed regions right after the request, and
+ * anything that happens later is picked up by the next frame.
+ */
+const MAX_WAIT_MS = 250;
+/** zlib level for panel frames: speed over size, the channel is loopback. */
+const PNG_LEVEL = 3;
+/** Allowed resolution divisors (1 — native). */
+const DIVISORS = [1, 2, 3, 4];
+
+/**
+ * How long to wait for a frame at the panel's pace.
+ * @param {number} fps frames per second from the settings.
+ * @returns {number} wait timeout, ms.
+ */
+function waitForFps(fps) {
+  const interval = 1000 / Math.max(1, fps);
+  return Math.max(MIN_WAIT_MS, Math.min(MAX_WAIT_MS, Math.round(interval - 50)));
+}
+
+/**
+ * One VM's screen as the agent sees it.
+ */
+export class ConsoleView {
+  /**
+   * @param {{controller: object, settings: () => object}} deps the VM controller and live settings.
+   */
+  constructor(deps) {
+    this.deps = deps;
+    /** @type {Map<string, Promise<object>>} captures already running: two clients do not queue twice. */
+    this.pending = new Map();
+  }
+
+  /** State for the panel: what is allowed, what is alive, whom to follow. */
+  state() {
+    const settings = this.deps.settings();
+    const last = this.deps.controller.lastConsoleUse();
+    return {
+      allowed: settings.allowVmids,
+      consoleEnabled: settings.enableConsole,
+      sessions: this.deps.controller.listSessions(),
+      last: last ? { vmid: last.vmid, at: last.at } : null,
+      view: settings.view,
+    };
+  }
+
+  /**
+   * A frame of the VM screen as PNG.
+   * @param {number} vmid VM id.
+   * @param {{scale?:number, cursor?:boolean}} [options] resolution divisor and whether to draw the cursor.
+   * @returns {Promise<{png:Buffer, meta:object}>} the PNG and its metadata.
+   */
+  frame(vmid, options = {}) {
+    const settings = this.deps.settings();
+    const id = this.deps.controller.assertAllowed(vmid, 'console');
+    const divisor = DIVISORS.includes(Number(options.scale)) ? Number(options.scale) : settings.view.scale;
+    const drawCursor = options.cursor !== false;
+    const key = `${id}:${divisor}:${drawCursor ? 1 : 0}`;
+    const running = this.pending.get(key);
+    if (running !== undefined) return running;
+    const task = this.#capture(id, divisor, drawCursor, waitForFps(settings.view.fps)).finally(() => {
+      this.pending.delete(key);
+    });
+    this.pending.set(key, task);
+    return task;
+  }
+
+  /**
+   * Close the VM console session (the panel's "disconnect" button).
+   * @param {number} vmid VM id.
+   * @returns {boolean} true when a session existed and was closed.
+   */
+  release(vmid) {
+    return this.deps.controller.close(vmid);
+  }
+
+  /**
+   * Capture a frame with exclusive access to the console.
+   * @param {number} vmid VM id.
+   * @param {number} divisor resolution divisor.
+   * @param {boolean} drawCursor whether to draw the cursor.
+   * @param {number} waitMs how long to wait for the incremental answer.
+   * @returns {Promise<{png:Buffer, meta:object}>}
+   */
+  async #capture(vmid, divisor, drawCursor, waitMs) {
+    // `mark: false` — watching is not agent work: otherwise the panel would move
+    // the "whom to follow" mark on every frame.
+    return this.deps.controller.withConsole(
+      vmid,
+      async (client, session) => {
+        // The first frame of a session is requested in full: a fresh client has no
+        // "changed" regions yet, and an incremental request could stay silent.
+        client.requestUpdate({ incremental: client.bytesIn > 0 });
+        await client.waitForUpdate({ timeoutMs: waitMs, idleOk: true });
+        const frame = client.snapshot({ drawCursor });
+        const scaled = divisor > 1 ? downscaleBox(frame, divisor) : { ...frame, scale: 1 };
+        const png = encodePng(scaled, { level: PNG_LEVEL });
+        return {
+          png,
+          meta: {
+            vmid,
+            width: frame.width,
+            height: frame.height,
+            captureWidth: scaled.width,
+            captureHeight: scaled.height,
+            scale: divisor,
+            pointerX: client.pointer.x,
+            pointerY: client.pointer.y,
+            cursorDrawn: Boolean(client.cursor) && drawCursor,
+            blank: looksBlank(frame),
+            bytes: png.length,
+            sessionAlive: session.alive !== false,
+          },
+        };
+      },
+      { mark: false },
+    );
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-pve-vm",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Proxmox VE VM control for DeepSeek Harness: see the screen and click in a VM console over VNC, plus commands, files and typed text through the QEMU guest agent.",
   "type": "module",
   "license": "MIT",
@@ -58,6 +58,7 @@
       "inject": [
         "@deepseek-ai/dsh-client-ui-settings",
         "@deepseek-ai/dsh-client-ui-slots",
+        "@deepseek-ai/dsh-client-ui-sidebar-right",
         "@deepseek-ai/dsh-client-locale"
       ]
     }
@@ -74,7 +75,7 @@
     "@deepseek-ai/schemastery": "^3.18.4"
   },
   "scripts": {
-    "check": "node --check index.js && node --check client.js && node --check lib/config.js && node --check lib/guest.js && node --check lib/hmp.js && node --check lib/keys.js && node --check lib/png.js && node --check lib/rfb.js && node --check lib/session.js && node --check lib/ssh.js && node --check tools/console.js && node --check tools/guest.js",
+    "check": "node --check index.js && node --check client.js && node --check lib/config.js && node --check lib/guest.js && node --check lib/hmp.js && node --check lib/keys.js && node --check lib/png.js && node --check lib/rfb.js && node --check lib/routes.js && node --check lib/session.js && node --check lib/ssh.js && node --check lib/view.js && node --check tools/console.js && node --check tools/guest.js",
     "test": "node tools/check-plugin.mjs && node tools/check-client.mjs",
     "prepublishOnly": "npm run check",
     "probe": "node tools/probe-rfb.mjs"