@livedesk/client 0.1.239 → 0.1.241

package/src/runtime/linux-video-acceleration.js

@@ -1,390 +1,390 @@
-import { spawn, spawnSync } from 'node:child_process';
-import { accessSync, constants, existsSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
-import { delimiter, join, resolve } from 'node:path';
-
-const PROBE_TIMEOUT_MS = 6_000;
-const INTEL_VENDOR_ID = '0x8086';
-const AMD_VENDOR_ID = '0x1002';
-
-function cleanText(value, maxLength = 320) {
-  return String(value ?? '').replace(/[\r\n\t]+/g, ' ').trim().slice(0, maxLength);
-}
-
-function executableExists(path) {
-  try {
-    accessSync(path, constants.X_OK);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function uniquePaths(values) {
-  const result = [];
-  for (const value of values) {
-    const candidate = String(value || '').trim();
-    if (!candidate) continue;
-    let normalized = candidate;
-    try {
-      normalized = realpathSync(candidate);
-    } catch {
-      normalized = resolve(candidate);
-    }
-    if (!result.includes(normalized)) result.push(normalized);
-  }
-  return result;
-}
-
-export function findExecutable(name, options = {}) {
-  const platform = options.platform || process.platform;
-  const env = options.env || process.env;
-  const exists = options.executableExists || executableExists;
-  const executableName = platform === 'win32' && !String(name).toLowerCase().endsWith('.exe')
-    ? `${name}.exe`
-    : String(name);
-  const candidates = String(env.PATH || '')
-    .split(delimiter)
-    .filter(Boolean)
-    .map(entry => join(entry, executableName));
-  return candidates.find(candidate => exists(candidate)) || '';
-}
-
-function findLinuxRenderDevices(options = {}) {
-  if (Array.isArray(options.renderDevices)) {
-    return uniquePaths(options.renderDevices);
-  }
-  const driRoot = options.driRoot || '/dev/dri';
-  try {
-    return uniquePaths(readdirSync(driRoot)
-      .filter(name => /^renderD\d+$/.test(name))
-      .map(name => join(driRoot, name))
-      .filter(executable => existsSync(executable)));
-  } catch {
-    return [];
-  }
-}
-
-function resolveSystemFfmpeg(options = {}) {
-  const env = options.env || process.env;
-  const exists = options.executableExists || executableExists;
-  const explicit = String(env.LIVEDESK_SYSTEM_FFMPEG || '').trim();
-  const candidates = uniquePaths([
-    explicit,
-    '/usr/bin/ffmpeg',
-    '/usr/local/bin/ffmpeg',
-    '/snap/bin/ffmpeg',
-    findExecutable('ffmpeg', { ...options, env, platform: 'linux', executableExists: exists })
-  ]);
-  return candidates.find(candidate => exists(candidate) && !candidate.includes('/node_modules/')) || '';
-}
-
-function readGpuVendor(renderDevice, options = {}) {
-  if (options.gpuVendor) return String(options.gpuVendor).trim().toLowerCase();
-  try {
-    return readFileSync(`/sys/class/drm/${renderDevice.split('/').pop()}/device/vendor`, 'utf8').trim().toLowerCase();
-  } catch {
-    return '';
-  }
-}
-
-export function detectLinuxPackageManager(options = {}) {
-  const managers = [
-    { id: 'apt', command: 'apt-get' },
-    { id: 'dnf', command: 'dnf' },
-    { id: 'pacman', command: 'pacman' },
-    { id: 'zypper', command: 'zypper' }
-  ];
-  for (const manager of managers) {
-    const path = findExecutable(manager.command, { ...options, platform: 'linux' });
-    if (path) return { ...manager, path };
-  }
-  return null;
-}
-
-function packagesFor(managerId, gpuVendor) {
-  if (managerId === 'apt') {
-    if (gpuVendor === INTEL_VENDOR_ID) return ['ffmpeg', 'vainfo', 'intel-media-va-driver', 'i965-va-driver'];
-    if (gpuVendor === AMD_VENDOR_ID) return ['ffmpeg', 'vainfo', 'mesa-va-drivers'];
-    return ['ffmpeg', 'vainfo'];
-  }
-  if (managerId === 'dnf') {
-    return ['ffmpeg', 'libva-utils'];
-  }
-  if (managerId === 'pacman') {
-    if (gpuVendor === INTEL_VENDOR_ID) return ['ffmpeg', 'libva-utils', 'intel-media-driver', 'libva-intel-driver'];
-    if (gpuVendor === AMD_VENDOR_ID) return ['ffmpeg', 'libva-utils', 'libva-mesa-driver'];
-    return ['ffmpeg', 'libva-utils'];
-  }
-  if (managerId === 'zypper') {
-    return ['ffmpeg', 'libva-utils'];
-  }
-  return [];
-}
-
-export function buildLinuxVideoInstallPlan(status, options = {}) {
-  const manager = options.packageManager || status?.packageManager;
-  if (!manager?.id || !manager?.path) return null;
-  const packages = packagesFor(manager.id, status?.gpuVendor || '');
-  if (packages.length === 0) return null;
-  let args;
-  if (manager.id === 'apt' || manager.id === 'dnf') {
-    args = ['install', '-y', ...packages];
-  } else if (manager.id === 'pacman') {
-    args = ['-S', '--needed', '--noconfirm', ...packages];
-  } else if (manager.id === 'zypper') {
-    args = ['--non-interactive', 'install', ...packages];
-  } else {
-    return null;
-  }
-  return {
-    manager,
-    packages,
-    args,
-    displayCommand: `sudo ${manager.command} ${args.join(' ')}`
-  };
-}
-
-export function probeLinuxVideoAcceleration(ffmpegPath, renderDevice, options = {}) {
-  const run = options.spawnSyncImpl || spawnSync;
-  const env = options.env || process.env;
-  const drivers = Array.isArray(options.drivers) && options.drivers.length > 0
-    ? options.drivers
-    : ['', 'iHD', 'i965'];
-  let lastError = '';
-  for (const driver of drivers) {
-    const probeEnv = { ...env };
-    if (driver) probeEnv.LIBVA_DRIVER_NAME = driver;
-    else delete probeEnv.LIBVA_DRIVER_NAME;
-    const result = run(ffmpegPath, [
-      '-hide_banner', '-loglevel', 'error',
-      '-vaapi_device', renderDevice,
-      '-f', 'lavfi',
-      '-i', 'color=c=black:s=64x64:r=1',
-      '-vf', 'format=nv12,hwupload',
-      '-frames:v', '1',
-      '-an',
-      '-c:v', 'h264_vaapi',
-      '-f', 'h264',
-      'pipe:1'
-    ], {
-      env: probeEnv,
-      encoding: null,
-      timeout: options.timeoutMs || PROBE_TIMEOUT_MS,
-      maxBuffer: 2 * 1024 * 1024,
-      windowsHide: true
-    });
-    const outputBytes = Buffer.isBuffer(result.stdout) ? result.stdout.length : 0;
-    if (result.status === 0 && outputBytes > 0) {
-      return {
-        ok: true,
-        encoder: 'h264_vaapi',
-        driver: driver || 'auto',
-        outputBytes
-      };
-    }
-    lastError = cleanText(
-      result.error?.message
-      || (Buffer.isBuffer(result.stderr) ? result.stderr.toString('utf8') : result.stderr)
-      || `ffmpeg exited with ${result.status ?? 'no status'}`
-    );
-  }
-  return { ok: false, error: lastError || 'VAAPI hardware encoding probe failed.' };
-}
-
-function baseStatus(platform) {
-  return {
-    platform,
-    supported: platform === 'linux',
-    state: platform === 'linux' ? 'checking' : 'not-applicable',
-    ready: false,
-    busy: false,
-    canInstall: false,
-    encoder: '',
-    driver: '',
-    ffmpegPath: '',
-    renderDevice: '',
-    gpuVendor: '',
-    packageManager: null,
-    manualCommand: '',
-    message: '',
-    error: '',
-    checkedAt: new Date().toISOString()
-  };
-}
-
-export function inspectLinuxVideoAcceleration(options = {}) {
-  const platform = options.platform || process.platform;
-  const status = baseStatus(platform);
-  if (platform !== 'linux') return status;
-
-  const renderDevices = findLinuxRenderDevices(options);
-  const renderDevice = renderDevices[0] || '';
-  const packageManager = options.packageManager === undefined
-    ? detectLinuxPackageManager(options)
-    : options.packageManager;
-  const gpuVendor = renderDevice ? readGpuVendor(renderDevice, options) : '';
-  Object.assign(status, { renderDevice, gpuVendor, packageManager });
-  const installPlan = buildLinuxVideoInstallPlan(status, { packageManager });
-  status.canInstall = Boolean(installPlan);
-  status.manualCommand = installPlan?.displayCommand || '';
-
-  if (!renderDevice) {
-    status.state = 'unavailable';
-    status.message = 'No Linux hardware video device was found.';
-    return status;
-  }
-
-  const ffmpegPath = options.ffmpegPath === undefined
-    ? resolveSystemFfmpeg(options)
-    : String(options.ffmpegPath || '');
-  status.ffmpegPath = ffmpegPath;
-  if (!ffmpegPath) {
-    status.state = 'setup-required';
-    status.message = 'Hardware video setup is available.';
-    return status;
-  }
-
-  const probe = (options.probeImpl || probeLinuxVideoAcceleration)(ffmpegPath, renderDevice, options);
-  if (!probe?.ok) {
-    status.state = 'setup-required';
-    status.message = 'Hardware video needs setup.';
-    status.error = cleanText(probe?.error || 'VAAPI hardware encoding probe failed.');
-    return status;
-  }
-
-  status.state = 'ready';
-  status.ready = true;
-  status.canInstall = false;
-  status.encoder = cleanText(probe.encoder || 'h264_vaapi', 80);
-  status.driver = cleanText(probe.driver || 'auto', 80);
-  status.message = 'VAAPI hardware video is ready.';
-  status.error = '';
-  return status;
-}
-
-function runChild(command, args, options = {}) {
-  const launch = options.spawnImpl || spawn;
-  return new Promise((resolvePromise, reject) => {
-    let child;
-    try {
-      child = launch(command, args, {
-        env: options.env || process.env,
-        stdio: 'inherit',
-        windowsHide: true
-      });
-    } catch (error) {
-      reject(error);
-      return;
-    }
-    child.once('error', reject);
-    child.once('exit', (code, signal) => resolvePromise({ code: code ?? 1, signal: signal || '' }));
-  });
-}
-
-export async function installLinuxVideoAcceleration(currentStatus, options = {}) {
-  if ((options.platform || process.platform) !== 'linux') {
-    return { ...baseStatus(options.platform || process.platform), state: 'not-applicable', error: 'linux-required' };
-  }
-  const plan = buildLinuxVideoInstallPlan(currentStatus, options);
-  if (!plan) {
-    return {
-      ...currentStatus,
-      state: 'error',
-      busy: false,
-      ready: false,
-      error: 'No supported Linux package manager was found.'
-    };
-  }
-
-  const env = options.env || process.env;
-  const find = name => findExecutable(name, { ...options, env, platform: 'linux' });
-  const isRoot = options.isRoot ?? (typeof process.getuid === 'function' && process.getuid() === 0);
-  const pkexec = find('pkexec');
-  const sudo = find('sudo');
-  const graphicalSession = Boolean(env.DISPLAY || env.WAYLAND_DISPLAY);
-  let command = '';
-  let args = [];
-  let elevation = '';
-  if (isRoot) {
-    command = plan.manager.path;
-    args = plan.args;
-    elevation = 'root';
-  } else if (pkexec && graphicalSession) {
-    command = pkexec;
-    args = [plan.manager.path, ...plan.args];
-    elevation = 'pkexec';
-  } else if (sudo && (options.stdinIsTTY ?? process.stdin.isTTY)) {
-    command = sudo;
-    args = [plan.manager.path, ...plan.args];
-    elevation = 'sudo';
-  } else {
-    return {
-      ...currentStatus,
-      state: 'error',
-      busy: false,
-      ready: false,
-      manualCommand: plan.displayCommand,
-      error: 'Administrator approval is unavailable in this session.'
-    };
-  }
-
-  options.onProgress?.({
-    ...currentStatus,
-    state: 'installing',
-    busy: true,
-    ready: false,
-    error: '',
-    message: 'Installing Linux hardware video support…',
-    elevation
-  });
-
-  let result;
-  try {
-    result = options.runInstall
-      ? await options.runInstall({ command, args, plan, elevation })
-      : await runChild(command, args, { ...options, env });
-  } catch (error) {
-    return {
-      ...currentStatus,
-      state: 'error',
-      busy: false,
-      ready: false,
-      manualCommand: plan.displayCommand,
-      error: cleanText(error?.message || error)
-    };
-  }
-  if (result?.code !== 0) {
-    return {
-      ...currentStatus,
-      state: 'error',
-      busy: false,
-      ready: false,
-      manualCommand: plan.displayCommand,
-      error: `Package installation stopped with exit code ${result?.code ?? 'unknown'}.`
-    };
-  }
-
-  const refreshed = (options.inspectImpl || inspectLinuxVideoAcceleration)({
-    ...options,
-    platform: 'linux',
-    packageManager: plan.manager,
-    ffmpegPath: undefined
-  });
-  if (!refreshed.ready) {
-    return {
-      ...refreshed,
-      state: 'error',
-      busy: false,
-      ready: false,
-      canInstall: true,
-      manualCommand: plan.displayCommand,
-      error: refreshed.error || 'Hardware video was installed but the VAAPI test did not pass.'
-    };
-  }
-  return {
-    ...refreshed,
-    busy: false,
-    restartAgent: true,
-    message: 'VAAPI hardware video is ready. Restarting the LiveDesk Agent…'
-  };
-}
+import { spawn, spawnSync } from 'node:child_process';
+import { accessSync, constants, existsSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
+import { delimiter, join, resolve } from 'node:path';
+
+const PROBE_TIMEOUT_MS = 6_000;
+const INTEL_VENDOR_ID = '0x8086';
+const AMD_VENDOR_ID = '0x1002';
+
+function cleanText(value, maxLength = 320) {
+  return String(value ?? '').replace(/[\r\n\t]+/g, ' ').trim().slice(0, maxLength);
+}
+
+function executableExists(path) {
+  try {
+    accessSync(path, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function uniquePaths(values) {
+  const result = [];
+  for (const value of values) {
+    const candidate = String(value || '').trim();
+    if (!candidate) continue;
+    let normalized = candidate;
+    try {
+      normalized = realpathSync(candidate);
+    } catch {
+      normalized = resolve(candidate);
+    }
+    if (!result.includes(normalized)) result.push(normalized);
+  }
+  return result;
+}
+
+export function findExecutable(name, options = {}) {
+  const platform = options.platform || process.platform;
+  const env = options.env || process.env;
+  const exists = options.executableExists || executableExists;
+  const executableName = platform === 'win32' && !String(name).toLowerCase().endsWith('.exe')
+    ? `${name}.exe`
+    : String(name);
+  const candidates = String(env.PATH || '')
+    .split(delimiter)
+    .filter(Boolean)
+    .map(entry => join(entry, executableName));
+  return candidates.find(candidate => exists(candidate)) || '';
+}
+
+function findLinuxRenderDevices(options = {}) {
+  if (Array.isArray(options.renderDevices)) {
+    return uniquePaths(options.renderDevices);
+  }
+  const driRoot = options.driRoot || '/dev/dri';
+  try {
+    return uniquePaths(readdirSync(driRoot)
+      .filter(name => /^renderD\d+$/.test(name))
+      .map(name => join(driRoot, name))
+      .filter(executable => existsSync(executable)));
+  } catch {
+    return [];
+  }
+}
+
+function resolveSystemFfmpeg(options = {}) {
+  const env = options.env || process.env;
+  const exists = options.executableExists || executableExists;
+  const explicit = String(env.LIVEDESK_SYSTEM_FFMPEG || '').trim();
+  const candidates = uniquePaths([
+    explicit,
+    '/usr/bin/ffmpeg',
+    '/usr/local/bin/ffmpeg',
+    '/snap/bin/ffmpeg',
+    findExecutable('ffmpeg', { ...options, env, platform: 'linux', executableExists: exists })
+  ]);
+  return candidates.find(candidate => exists(candidate) && !candidate.includes('/node_modules/')) || '';
+}
+
+function readGpuVendor(renderDevice, options = {}) {
+  if (options.gpuVendor) return String(options.gpuVendor).trim().toLowerCase();
+  try {
+    return readFileSync(`/sys/class/drm/${renderDevice.split('/').pop()}/device/vendor`, 'utf8').trim().toLowerCase();
+  } catch {
+    return '';
+  }
+}
+
+export function detectLinuxPackageManager(options = {}) {
+  const managers = [
+    { id: 'apt', command: 'apt-get' },
+    { id: 'dnf', command: 'dnf' },
+    { id: 'pacman', command: 'pacman' },
+    { id: 'zypper', command: 'zypper' }
+  ];
+  for (const manager of managers) {
+    const path = findExecutable(manager.command, { ...options, platform: 'linux' });
+    if (path) return { ...manager, path };
+  }
+  return null;
+}
+
+function packagesFor(managerId, gpuVendor) {
+  if (managerId === 'apt') {
+    if (gpuVendor === INTEL_VENDOR_ID) return ['ffmpeg', 'vainfo', 'intel-media-va-driver', 'i965-va-driver'];
+    if (gpuVendor === AMD_VENDOR_ID) return ['ffmpeg', 'vainfo', 'mesa-va-drivers'];
+    return ['ffmpeg', 'vainfo'];
+  }
+  if (managerId === 'dnf') {
+    return ['ffmpeg', 'libva-utils'];
+  }
+  if (managerId === 'pacman') {
+    if (gpuVendor === INTEL_VENDOR_ID) return ['ffmpeg', 'libva-utils', 'intel-media-driver', 'libva-intel-driver'];
+    if (gpuVendor === AMD_VENDOR_ID) return ['ffmpeg', 'libva-utils', 'libva-mesa-driver'];
+    return ['ffmpeg', 'libva-utils'];
+  }
+  if (managerId === 'zypper') {
+    return ['ffmpeg', 'libva-utils'];
+  }
+  return [];
+}
+
+export function buildLinuxVideoInstallPlan(status, options = {}) {
+  const manager = options.packageManager || status?.packageManager;
+  if (!manager?.id || !manager?.path) return null;
+  const packages = packagesFor(manager.id, status?.gpuVendor || '');
+  if (packages.length === 0) return null;
+  let args;
+  if (manager.id === 'apt' || manager.id === 'dnf') {
+    args = ['install', '-y', ...packages];
+  } else if (manager.id === 'pacman') {
+    args = ['-S', '--needed', '--noconfirm', ...packages];
+  } else if (manager.id === 'zypper') {
+    args = ['--non-interactive', 'install', ...packages];
+  } else {
+    return null;
+  }
+  return {
+    manager,
+    packages,
+    args,
+    displayCommand: `sudo ${manager.command} ${args.join(' ')}`
+  };
+}
+
+export function probeLinuxVideoAcceleration(ffmpegPath, renderDevice, options = {}) {
+  const run = options.spawnSyncImpl || spawnSync;
+  const env = options.env || process.env;
+  const drivers = Array.isArray(options.drivers) && options.drivers.length > 0
+    ? options.drivers
+    : ['', 'iHD', 'i965'];
+  let lastError = '';
+  for (const driver of drivers) {
+    const probeEnv = { ...env };
+    if (driver) probeEnv.LIBVA_DRIVER_NAME = driver;
+    else delete probeEnv.LIBVA_DRIVER_NAME;
+    const result = run(ffmpegPath, [
+      '-hide_banner', '-loglevel', 'error',
+      '-vaapi_device', renderDevice,
+      '-f', 'lavfi',
+      '-i', 'color=c=black:s=64x64:r=1',
+      '-vf', 'format=nv12,hwupload',
+      '-frames:v', '1',
+      '-an',
+      '-c:v', 'h264_vaapi',
+      '-f', 'h264',
+      'pipe:1'
+    ], {
+      env: probeEnv,
+      encoding: null,
+      timeout: options.timeoutMs || PROBE_TIMEOUT_MS,
+      maxBuffer: 2 * 1024 * 1024,
+      windowsHide: true
+    });
+    const outputBytes = Buffer.isBuffer(result.stdout) ? result.stdout.length : 0;
+    if (result.status === 0 && outputBytes > 0) {
+      return {
+        ok: true,
+        encoder: 'h264_vaapi',
+        driver: driver || 'auto',
+        outputBytes
+      };
+    }
+    lastError = cleanText(
+      result.error?.message
+      || (Buffer.isBuffer(result.stderr) ? result.stderr.toString('utf8') : result.stderr)
+      || `ffmpeg exited with ${result.status ?? 'no status'}`
+    );
+  }
+  return { ok: false, error: lastError || 'VAAPI hardware encoding probe failed.' };
+}
+
+function baseStatus(platform) {
+  return {
+    platform,
+    supported: platform === 'linux',
+    state: platform === 'linux' ? 'checking' : 'not-applicable',
+    ready: false,
+    busy: false,
+    canInstall: false,
+    encoder: '',
+    driver: '',
+    ffmpegPath: '',
+    renderDevice: '',
+    gpuVendor: '',
+    packageManager: null,
+    manualCommand: '',
+    message: '',
+    error: '',
+    checkedAt: new Date().toISOString()
+  };
+}
+
+export function inspectLinuxVideoAcceleration(options = {}) {
+  const platform = options.platform || process.platform;
+  const status = baseStatus(platform);
+  if (platform !== 'linux') return status;
+
+  const renderDevices = findLinuxRenderDevices(options);
+  const renderDevice = renderDevices[0] || '';
+  const packageManager = options.packageManager === undefined
+    ? detectLinuxPackageManager(options)
+    : options.packageManager;
+  const gpuVendor = renderDevice ? readGpuVendor(renderDevice, options) : '';
+  Object.assign(status, { renderDevice, gpuVendor, packageManager });
+  const installPlan = buildLinuxVideoInstallPlan(status, { packageManager });
+  status.canInstall = Boolean(installPlan);
+  status.manualCommand = installPlan?.displayCommand || '';
+
+  if (!renderDevice) {
+    status.state = 'unavailable';
+    status.message = 'No Linux hardware video device was found.';
+    return status;
+  }
+
+  const ffmpegPath = options.ffmpegPath === undefined
+    ? resolveSystemFfmpeg(options)
+    : String(options.ffmpegPath || '');
+  status.ffmpegPath = ffmpegPath;
+  if (!ffmpegPath) {
+    status.state = 'setup-required';
+    status.message = 'Hardware video setup is available.';
+    return status;
+  }
+
+  const probe = (options.probeImpl || probeLinuxVideoAcceleration)(ffmpegPath, renderDevice, options);
+  if (!probe?.ok) {
+    status.state = 'setup-required';
+    status.message = 'Hardware video needs setup.';
+    status.error = cleanText(probe?.error || 'VAAPI hardware encoding probe failed.');
+    return status;
+  }
+
+  status.state = 'ready';
+  status.ready = true;
+  status.canInstall = false;
+  status.encoder = cleanText(probe.encoder || 'h264_vaapi', 80);
+  status.driver = cleanText(probe.driver || 'auto', 80);
+  status.message = 'VAAPI hardware video is ready.';
+  status.error = '';
+  return status;
+}
+
+function runChild(command, args, options = {}) {
+  const launch = options.spawnImpl || spawn;
+  return new Promise((resolvePromise, reject) => {
+    let child;
+    try {
+      child = launch(command, args, {
+        env: options.env || process.env,
+        stdio: 'inherit',
+        windowsHide: true
+      });
+    } catch (error) {
+      reject(error);
+      return;
+    }
+    child.once('error', reject);
+    child.once('exit', (code, signal) => resolvePromise({ code: code ?? 1, signal: signal || '' }));
+  });
+}
+
+export async function installLinuxVideoAcceleration(currentStatus, options = {}) {
+  if ((options.platform || process.platform) !== 'linux') {
+    return { ...baseStatus(options.platform || process.platform), state: 'not-applicable', error: 'linux-required' };
+  }
+  const plan = buildLinuxVideoInstallPlan(currentStatus, options);
+  if (!plan) {
+    return {
+      ...currentStatus,
+      state: 'error',
+      busy: false,
+      ready: false,
+      error: 'No supported Linux package manager was found.'
+    };
+  }
+
+  const env = options.env || process.env;
+  const find = name => findExecutable(name, { ...options, env, platform: 'linux' });
+  const isRoot = options.isRoot ?? (typeof process.getuid === 'function' && process.getuid() === 0);
+  const pkexec = find('pkexec');
+  const sudo = find('sudo');
+  const graphicalSession = Boolean(env.DISPLAY || env.WAYLAND_DISPLAY);
+  let command = '';
+  let args = [];
+  let elevation = '';
+  if (isRoot) {
+    command = plan.manager.path;
+    args = plan.args;
+    elevation = 'root';
+  } else if (pkexec && graphicalSession) {
+    command = pkexec;
+    args = [plan.manager.path, ...plan.args];
+    elevation = 'pkexec';
+  } else if (sudo && (options.stdinIsTTY ?? process.stdin.isTTY)) {
+    command = sudo;
+    args = [plan.manager.path, ...plan.args];
+    elevation = 'sudo';
+  } else {
+    return {
+      ...currentStatus,
+      state: 'error',
+      busy: false,
+      ready: false,
+      manualCommand: plan.displayCommand,
+      error: 'Administrator approval is unavailable in this session.'
+    };
+  }
+
+  options.onProgress?.({
+    ...currentStatus,
+    state: 'installing',
+    busy: true,
+    ready: false,
+    error: '',
+    message: 'Installing Linux hardware video support…',
+    elevation
+  });
+
+  let result;
+  try {
+    result = options.runInstall
+      ? await options.runInstall({ command, args, plan, elevation })
+      : await runChild(command, args, { ...options, env });
+  } catch (error) {
+    return {
+      ...currentStatus,
+      state: 'error',
+      busy: false,
+      ready: false,
+      manualCommand: plan.displayCommand,
+      error: cleanText(error?.message || error)
+    };
+  }
+  if (result?.code !== 0) {
+    return {
+      ...currentStatus,
+      state: 'error',
+      busy: false,
+      ready: false,
+      manualCommand: plan.displayCommand,
+      error: `Package installation stopped with exit code ${result?.code ?? 'unknown'}.`
+    };
+  }
+
+  const refreshed = (options.inspectImpl || inspectLinuxVideoAcceleration)({
+    ...options,
+    platform: 'linux',
+    packageManager: plan.manager,
+    ffmpegPath: undefined
+  });
+  if (!refreshed.ready) {
+    return {
+      ...refreshed,
+      state: 'error',
+      busy: false,
+      ready: false,
+      canInstall: true,
+      manualCommand: plan.displayCommand,
+      error: refreshed.error || 'Hardware video was installed but the VAAPI test did not pass.'
+    };
+  }
+  return {
+    ...refreshed,
+    busy: false,
+    restartAgent: true,
+    message: 'VAAPI hardware video is ready. Restarting the LiveDesk Agent…'
+  };
+}