@livedesk/client 0.1.179 → 0.1.181

package/README.md

@@ -51,8 +51,9 @@ the matching callback URL to Supabase Auth redirect URLs.
 The client registers the device, sends status heartbeats, can return
 Hub-requested thumbnails, can stream a focused view-only live screen, and
 can receive safe task-only instructions. The C# RemoteFast engine also supports
-keyboard/mouse control on Windows, macOS, and Linux/X11, file transfer, and
-Windows system-audio loopback playback. macOS control requires Accessibility
+keyboard/mouse control on Windows, macOS, and Linux/X11, file transfer, and
+system-audio playback from Windows, macOS, and Linux. Linux captures the default
+output through PipeWire `pw-record` or PulseAudio `parec`. macOS control requires Accessibility
 permission for the terminal app that started LiveDesk; screen streaming and
 system-audio capture require Screen Recording permission. LiveDesk checks these
 permissions without opening repeated system dialogs and prints the matching

package/bin/livedesk-client.js

@@ -13,6 +13,10 @@ import { formatClientVersionBanner, readClientPackageVersion } from './client-ve
 import { createClientRuntimeServer } from '../src/runtime/client-runtime-server.js';
 import { installAgentTerminationHandlers } from '../src/runtime/agent-process-lifecycle.js';
 import { createHubWakeListener } from '../src/runtime/hub-wake-listener.js';
+import {
+    inspectLinuxVideoAcceleration,
+    installLinuxVideoAcceleration
+} from '../src/runtime/linux-video-acceleration.js';
 import { normalizeRuntimeAuthSession } from '../../runtime-core/src/auth-session.js';
 import { startRoleTransitionSupervisor } from '../../runtime-core/src/role-transition-supervisor.js';
 
@@ -48,10 +52,13 @@ const CLIENT_AUTH_STORAGE_KEY = 'livedesk.client.supabase.auth';
 const CLIENT_HUB_TARGET_CACHE_STORAGE_KEY = 'livedesk.client.last-hub-target';
 const DEVICE_ROLE_CACHE_PATH = join(UNIFIED_CLIENT_STATE_DIR, 'device-role.json');
 const FAST_PREFLIGHT_CACHE_PATH = join(UNIFIED_CLIENT_STATE_DIR, 'fast-preflight.json');
+const CLIENT_SLOT_PATH = join(UNIFIED_CLIENT_STATE_DIR, 'device-slot.json');
 const CLIENT_UPDATE_STATE_PATH = process.env.LIVEDESK_CLIENT_UPDATE_STATE_PATH
     || join(UNIFIED_CLIENT_STATE_DIR, 'client-update.json');
 let activeAgentProcess = null;
 let roleRestartRequest = null;
+let agentRestartRequest = null;
+let linuxVideoAccelerationStatus = null;
 let discoveryWakeController = new AbortController();
 let networkChangeMonitor = null;
 const sessionRefreshesInFlight = new WeakMap();
@@ -436,10 +443,48 @@ function normalizeSlotNumber(value) {
     if (!Number.isInteger(number) || number < 1 || number > 999) {
         return '';
     }
-    return String(number);
-}
-
-function upsertForwardedOption(args, flag, value) {
+    return String(number);
+}
+
+function readSavedDeviceSlot(deviceId = '') {
+    try {
+        const state = JSON.parse(readFileSync(CLIENT_SLOT_PATH, 'utf8'));
+        const savedDeviceId = String(state?.deviceId || '').trim();
+        const expectedDeviceId = String(deviceId || '').trim();
+        if (savedDeviceId && expectedDeviceId && savedDeviceId !== expectedDeviceId) {
+            return '';
+        }
+        return normalizeSlotNumber(state?.slotNumber);
+    } catch {
+        return '';
+    }
+}
+
+function writeSavedDeviceSlot(deviceId, slotNumber) {
+    const normalizedDeviceId = String(deviceId || '').trim();
+    const normalizedSlot = normalizeSlotNumber(slotNumber);
+    if (!normalizedDeviceId || !normalizedSlot) {
+        throw new Error('device-id-and-slot-required');
+    }
+    mkdirSync(dirname(CLIENT_SLOT_PATH), { recursive: true });
+    const temporaryPath = `${CLIENT_SLOT_PATH}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`;
+    try {
+        writeFileSync(temporaryPath, JSON.stringify({
+            deviceId: normalizedDeviceId,
+            slotNumber: Number(normalizedSlot),
+            updatedAt: new Date().toISOString()
+        }, null, 2), 'utf8');
+        try { chmodSync(temporaryPath, 0o600); } catch { /* Windows profile ACLs remain authoritative. */ }
+        renameSync(temporaryPath, CLIENT_SLOT_PATH);
+        try { chmodSync(CLIENT_SLOT_PATH, 0o600); } catch { /* Windows profile ACLs remain authoritative. */ }
+    } catch (error) {
+        rmSync(temporaryPath, { force: true });
+        throw error;
+    }
+    return Number(normalizedSlot);
+}
+
+function upsertForwardedOption(args, flag, value) {
     if (!value) {
         return args;
     }
@@ -2975,6 +3020,7 @@ async function chooseClientConnection(supabase, options = {}) {
             appVersion: process.env.LIVEDESK_NPM_LAUNCHER_VERSION || readPackageVersion(),
             deviceId: options.deviceId,
             engine: options.engine,
+            slot: options.slot,
             savedSession: options.savedSession,
             initialChoice: options.initialChoice,
             initialChoiceMessage: options.initialChoiceMessage,
@@ -3033,7 +3079,41 @@ async function chooseClientConnection(supabase, options = {}) {
                 requestLocalDiscoveryWake('role-change');
                 try { activeAgentProcess?.kill(); } catch { /* the lifecycle loop observes the role request */ }
                 return { ok: true, restarting: true, role, roleVersion };
-            },
+            },
+            videoAcceleration: linuxVideoAccelerationStatus,
+            installVideoAcceleration: async () => {
+                const result = await installLinuxVideoAcceleration(
+                    linuxVideoAccelerationStatus || inspectLinuxVideoAcceleration()
+                );
+                linuxVideoAccelerationStatus = result;
+                return result;
+            },
+            onVideoAccelerationReady: result => {
+                if (!result?.ready || process.platform !== 'linux') return;
+                agentRestartRequest = {
+                    reason: 'linux-video-acceleration-ready',
+                    requestedAt: new Date().toISOString()
+                };
+                requestLocalDiscoveryWake('linux-video-acceleration-ready');
+                try { activeAgentProcess?.kill(); } catch { /* the lifecycle loop restarts with the new ffmpeg preference */ }
+            },
+            assignSlot: async request => {
+                const result = await requestHubSlotAssignment(request);
+                if (result?.ok !== true) {
+                    return result;
+                }
+                const slotNumber = writeSavedDeviceSlot(request.deviceId, result.slotNumber);
+                agentRestartRequest = {
+                    reason: 'slot-updated',
+                    slotNumber,
+                    requestedAt: new Date().toISOString()
+                };
+                requestLocalDiscoveryWake('slot-updated');
+                setTimeout(() => {
+                    try { activeAgentProcess?.kill(); } catch { /* the lifecycle loop restarts with the saved slot */ }
+                }, 150);
+                return { ...result, slotNumber, saved: true, restarting: true };
+            },
             onRestart: () => process.kill(process.pid, 'SIGTERM'),
             onShutdown: () => process.kill(process.pid, 'SIGTERM'),
             onDisconnect: () => activeAgentProcess?.kill(),
@@ -3075,7 +3155,7 @@ async function chooseClientConnection(supabase, options = {}) {
     return { ...choice, connectionPage };
 }
 
-function parseManagerEndpoint(value) {
+function parseManagerEndpoint(value) {
     let text = String(value || '').trim().replace(/^tcp:\/\//i, '');
     const separator = text.lastIndexOf(':');
     if (separator <= 0) {
@@ -3086,9 +3166,71 @@ function parseManagerEndpoint(value) {
     if (!host || !Number.isFinite(port)) {
         return null;
     }
-    return { host, port };
-}
-
+    return { host, port };
+}
+
+function requestHubSlotAssignment({ manager, pairToken, deviceId, slotNumber, timeoutMs = 5000 }) {
+    const endpoint = parseManagerEndpoint(manager);
+    const normalizedPairToken = String(pairToken || '').trim();
+    const normalizedDeviceId = String(deviceId || '').trim();
+    const normalizedSlot = normalizeSlotNumber(slotNumber);
+    if (!endpoint) {
+        return Promise.resolve({ ok: false, error: 'hub-endpoint-unavailable' });
+    }
+    if (!normalizedPairToken) {
+        return Promise.resolve({ ok: false, error: 'hub-pair-token-unavailable' });
+    }
+    if (!normalizedDeviceId) {
+        return Promise.resolve({ ok: false, error: 'device-id-required' });
+    }
+    if (!normalizedSlot) {
+        return Promise.resolve({ ok: false, error: 'invalid-slot-number' });
+    }
+
+    return new Promise(resolveAssignment => {
+        const socket = net.createConnection(endpoint);
+        let settled = false;
+        let buffer = '';
+        const settle = result => {
+            if (settled) return;
+            settled = true;
+            socket.removeAllListeners();
+            socket.destroy();
+            resolveAssignment(result);
+        };
+        socket.setEncoding('utf8');
+        socket.setTimeout(timeoutMs);
+        socket.once('connect', () => {
+            socket.write(`${JSON.stringify({
+                type: 'slot.assign',
+                pairToken: normalizedPairToken,
+                deviceId: normalizedDeviceId,
+                slotNumber: Number(normalizedSlot)
+            })}\n`);
+        });
+        socket.on('data', chunk => {
+            buffer += chunk;
+            const newlineIndex = buffer.indexOf('\n');
+            if (newlineIndex < 0) return;
+            try {
+                const response = JSON.parse(buffer.slice(0, newlineIndex).trim());
+                if (response?.type !== 'slot.assignment') {
+                    settle({ ok: false, error: response?.error || 'unexpected-hub-response' });
+                    return;
+                }
+                settle(response);
+            } catch {
+                settle({ ok: false, error: 'invalid-hub-response' });
+            }
+        });
+        socket.once('timeout', () => settle({ ok: false, error: 'hub-slot-request-timeout' }));
+        socket.once('error', error => settle({ ok: false, error: error?.message || 'hub-slot-request-failed' }));
+        socket.once('close', () => {
+            if (!settled) settle({ ok: false, error: 'hub-slot-response-missing' });
+        });
+    });
+}
+
 export function canConnectToEndpoint(endpoint, timeoutMs = ENDPOINT_PROBE_TIMEOUT_MS) {
     const parsedEndpoint = parseManagerEndpoint(endpoint);
     if (!parsedEndpoint) {
@@ -3734,7 +3876,7 @@ function buildClientAgentEnvironment(prepared) {
     return env;
 }
 
-function buildFastEnvironment(prepared) {
+function buildFastEnvironment(prepared) {
     const env = buildClientAgentEnvironment(prepared);
     env.LIVEDESK_NODE_EXECUTABLE = process.execPath;
     env.LIVEDESK_CLIENT_PACKAGE_VERSION = readPackageVersion();
@@ -3743,7 +3885,11 @@ function buildFastEnvironment(prepared) {
     const configuredPaths = env.LIVEDESK_FFMPEG_PATHS
         ? env.LIVEDESK_FFMPEG_PATHS.split(separator).filter(Boolean)
         : [];
-    const configuredSingle = env.LIVEDESK_FFMPEG ? [env.LIVEDESK_FFMPEG] : [];
+    const configuredSingle = env.LIVEDESK_FFMPEG ? [env.LIVEDESK_FFMPEG] : [];
+    const systemHardwareFfmpeg = process.platform === 'linux'
+        && linuxVideoAccelerationStatus?.ready
+        ? [linuxVideoAccelerationStatus.ffmpegPath]
+        : [];
     const merged = [];
     const addMerged = path => {
         const value = String(path || '').trim();
@@ -3759,18 +3905,26 @@ function buildFastEnvironment(prepared) {
         if (bundledFfmpegPaths[0]) {
             env.LIVEDESK_FFMPEG = bundledFfmpegPaths[0];
         }
-    } else {
-        configuredPaths.forEach(addMerged);
-        configuredSingle.forEach(addMerged);
-        bundledFfmpegPaths.forEach(addMerged);
-        if (!env.LIVEDESK_FFMPEG && merged[0]) {
-            env.LIVEDESK_FFMPEG = merged[0];
-        }
-    }
+    } else {
+        configuredPaths.forEach(addMerged);
+        configuredSingle.forEach(addMerged);
+        systemHardwareFfmpeg.forEach(addMerged);
+        bundledFfmpegPaths.forEach(addMerged);
+        if (!env.LIVEDESK_FFMPEG && merged[0]) {
+            env.LIVEDESK_FFMPEG = merged[0];
+        }
+    }
 
-    if (merged.length > 0) {
-        env.LIVEDESK_FFMPEG_PATHS = merged.join(separator);
-    }
+    if (merged.length > 0) {
+        env.LIVEDESK_FFMPEG_PATHS = merged.join(separator);
+    }
+    if (process.platform === 'linux'
+        && linuxVideoAccelerationStatus?.ready
+        && linuxVideoAccelerationStatus.driver
+        && linuxVideoAccelerationStatus.driver !== 'auto'
+        && !env.LIBVA_DRIVER_NAME) {
+        env.LIBVA_DRIVER_NAME = linuxVideoAccelerationStatus.driver;
+    }
 
     if (process.platform === 'darwin' || process.platform === 'linux' || env.LIVEDESK_DEBUG_FFMPEG === '1') {
         const describe = path => path.includes('ffmpeg-static')
@@ -4008,12 +4162,28 @@ export async function runClientRuntime(argv = process.argv.slice(2)) {
         return;
     }
 
-    console.log(formatClientVersionBanner());
+    console.log(formatClientVersionBanner());
+    linuxVideoAccelerationStatus = inspectLinuxVideoAcceleration();
+    if (process.platform === 'linux') {
+        const accelerationLabel = linuxVideoAccelerationStatus.ready
+            ? `${linuxVideoAccelerationStatus.encoder} via ${linuxVideoAccelerationStatus.ffmpegPath}`
+            : linuxVideoAccelerationStatus.message || linuxVideoAccelerationStatus.state;
+        console.log(`[LiveDesk Client] Linux video acceleration: ${accelerationLabel}`);
+    }
 
-    let connectionPage = null;
-    while (true) {
-        const prepared = await prepareLoginConnection(parsed, connectionPage);
-        connectionPage = prepared.connectionPage || connectionPage;
+    let connectionPage = null;
+    while (true) {
+        const savedSlot = readSavedDeviceSlot(parsed.deviceId);
+        if (savedSlot) {
+            parsed.slot = savedSlot;
+        }
+        const prepared = await prepareLoginConnection(parsed, connectionPage);
+        connectionPage = prepared.connectionPage || connectionPage;
+        prepared.connectionPage?.update({
+            manager: prepared.manager,
+            pairToken: prepared.pair,
+            slotNumber: Number(prepared.slot || 0)
+        });
         const roleRestartBeforeAgent = connectionPage?.getRoleRestartRequest?.() || roleRestartRequest;
         if (roleRestartBeforeAgent?.role) {
             if (isTruthy(process.env.LIVEDESK_DESKTOP_HOST)) process.exit(43);
@@ -4114,8 +4284,23 @@ export async function runClientRuntime(argv = process.argv.slice(2)) {
             await spawnUnifiedRoleRestart(requestedRoleRestart.role);
             connectionPage?.close?.();
             process.exit(0);
-        }
-        if (result?.signal) {
+        }
+        if (agentRestartRequest) {
+            const restart = agentRestartRequest;
+            agentRestartRequest = null;
+            connectionPage?.update({
+                agent: {
+                    requestedEngine: prepared.engine,
+                    state: 'reconnecting'
+                },
+                message: restart.reason === 'slot-updated'
+                    ? `Slot ${String(restart.slotNumber || prepared.slot || '').padStart(3, '0')} saved. Restarting the LiveDesk Agent.`
+                    : 'Linux hardware video is ready. Restarting the LiveDesk Agent.'
+            });
+            console.log(`[LiveDesk Client] Restarting Agent after ${restart.reason}.`);
+            continue;
+        }
+        if (result?.signal) {
             connectionPage?.close?.();
             process.kill(process.pid, result.signal);
             return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livedesk/client",
-  "version": "0.1.179",
+  "version": "0.1.181",
   "description": "LiveDesk local remote client",
   "type": "module",
   "bin": {
@@ -39,10 +39,10 @@
     "ws": "^8.18.3"
   },
   "optionalDependencies": {
-    "@livedesk/fast-linux-x64": "0.1.385",
-    "@livedesk/fast-osx-arm64": "0.1.385",
-    "@livedesk/fast-osx-x64": "0.1.385",
-    "@livedesk/fast-win-x64": "0.1.385"
+    "@livedesk/fast-linux-x64": "0.1.387",
+    "@livedesk/fast-osx-arm64": "0.1.387",
+    "@livedesk/fast-osx-x64": "0.1.387",
+    "@livedesk/fast-win-x64": "0.1.387"
   },
   "publishConfig": {
     "access": "public"

package/src/runtime/client-runtime-server.js

@@ -43,6 +43,13 @@ function normalizePort(value, fallback = DEFAULT_PORT) {
   return Number.isInteger(port) && port >= 1 && port <= 65535 ? port : fallback;
 }
 
+function normalizeSlotNumber(value) {
+  const slotNumber = Number(String(value ?? '').trim());
+  return Number.isInteger(slotNumber) && slotNumber >= 1 && slotNumber <= 999
+    ? slotNumber
+    : 0;
+}
+
 function readCpuTotals() {
   return os.cpus().reduce((totals, cpu) => {
     const times = Object.values(cpu.times || {}).map(Number);
@@ -543,8 +550,10 @@ export function createClientRuntimeServer(options = {}) {
   let networkRefreshTimer;
   const csrfToken = randomBytes(32).toString('hex');
   const state = {
-    route: '/computer',
+    route: '/computer',
     manager: '',
+    pairToken: '',
+    slotNumber: normalizeSlotNumber(options.slot),
     assignedHubId: '',
     endpointCandidates: [],
     roleVersion: 0,
@@ -552,6 +561,9 @@ export function createClientRuntimeServer(options = {}) {
     message: 'Sign in with Google or enter a Hub PIN to start this Client.',
     startup: false,
     agent: { requestedEngine: normalizeString(options.engine, 40), state: 'waiting', pid: null, engine: '' },
+    videoAcceleration: options.videoAcceleration && typeof options.videoAcceleration === 'object'
+      ? { ...options.videoAcceleration, busy: false }
+      : null,
     lastError: '',
     auth: {
       lastAttemptAt: '',
@@ -719,8 +731,9 @@ export function createClientRuntimeServer(options = {}) {
       runtimeId: `client-${snapshot.runtimePid}-${snapshot.startedAt}`,
       runtimePid: snapshot.runtimePid,
       startedAt: snapshot.startedAt,
-      route: state.route,
+      route: state.route,
       manager: state.manager,
+      slotNumber: state.slotNumber,
       assignedHubId: state.assignedHubId,
       endpointCandidates: state.endpointCandidates,
       roleVersion: state.roleVersion,
@@ -731,8 +744,9 @@ export function createClientRuntimeServer(options = {}) {
       message: state.message,
       lastError: state.lastError,
       auth: { ...state.auth },
-      startup: state.startup,
-      agent: { ...state.agent, pid: runtime.getSnapshot().agentPid },
+      startup: state.startup,
+      agent: { ...state.agent, pid: runtime.getSnapshot().agentPid },
+      videoAcceleration: state.videoAcceleration ? { ...state.videoAcceleration } : null,
       system: {
         platform: process.platform,
         arch: process.arch,
@@ -951,13 +965,121 @@ export function createClientRuntimeServer(options = {}) {
       setTimeout(() => options.onRestart?.(), 150);
       return;
     }
-    if (pathname === '/api/runtime/shutdown' && req.method === 'POST') {
-      runtime.emit('runtime.shutdown.requested', { role: 'client' });
+    if (pathname === '/api/runtime/shutdown' && req.method === 'POST') {
+      runtime.emit('runtime.shutdown.requested', { role: 'client' });
       respondJson(200, { ok: true, shuttingDown: true, role: 'client' });
-      setTimeout(() => options.onShutdown?.(), 150);
-      return;
-    }
-    if (pathname === '/api/runtime/switch-role' && req.method === 'POST') {
+      setTimeout(() => options.onShutdown?.(), 150);
+      return;
+    }
+    if (pathname === '/api/client/slot' && req.method === 'POST') {
+      const body = parseJsonBody(await readBody(req));
+      const slotNumber = normalizeSlotNumber(body.slotNumber ?? body.slot);
+      if (!slotNumber) {
+        respondJson(400, { ok: false, error: 'invalid-slot-number', slotNumber: state.slotNumber });
+        return;
+      }
+      if (!state.manager || !state.pairToken || state.agent.state !== 'running') {
+        respondJson(409, { ok: false, error: 'hub-not-connected', slotNumber: state.slotNumber });
+        return;
+      }
+      if (typeof options.assignSlot !== 'function') {
+        respondJson(409, { ok: false, error: 'slot-assignment-unavailable', slotNumber: state.slotNumber });
+        return;
+      }
+      runtime.emit('client.slot.assignment-requested', {
+        deviceId,
+        previousSlotNumber: state.slotNumber,
+        slotNumber
+      });
+      try {
+        const result = await options.assignSlot({
+          manager: state.manager,
+          pairToken: state.pairToken,
+          deviceId,
+          slotNumber
+        });
+        if (result?.ok !== true) {
+          const error = normalizeString(result?.error, 120) || 'slot-assignment-failed';
+          runtime.emit('client.slot.assignment-rejected', {
+            deviceId,
+            slotNumber,
+            error,
+            conflictDeviceId: normalizeString(result?.conflict?.deviceId, 160)
+          });
+          respondJson(error === 'slot-taken' ? 409 : 502, {
+            ...(result && typeof result === 'object' ? result : {}),
+            ok: false,
+            error,
+            slotNumber: state.slotNumber
+          });
+          return;
+        }
+        state.slotNumber = slotNumber;
+        state.message = `Slot ${String(slotNumber).padStart(3, '0')} saved. Reconnecting this Client.`;
+        runtime.emit('client.slot.assigned', { deviceId, slotNumber });
+        respondJson(200, { ...getState(), ...result, ok: true, slotNumber });
+      } catch (error) {
+        const message = normalizeString(error?.message || error, 240) || 'slot-assignment-failed';
+        runtime.emit('client.slot.assignment-failed', { deviceId, slotNumber, error: message });
+        respondJson(502, { ok: false, error: message, slotNumber: state.slotNumber });
+      }
+      return;
+    }
+    if (pathname === '/api/client/video-acceleration/install' && req.method === 'POST') {
+      if (process.platform !== 'linux') {
+        respondJson(409, { ok: false, error: 'linux-video-acceleration-only' });
+        return;
+      }
+      if (state.videoAcceleration?.busy) {
+        respondJson(409, { ok: false, error: 'video-acceleration-install-in-progress', ...getState() });
+        return;
+      }
+      if (typeof options.installVideoAcceleration !== 'function') {
+        respondJson(409, { ok: false, error: 'video-acceleration-install-unavailable' });
+        return;
+      }
+      state.videoAcceleration = {
+        ...(state.videoAcceleration || {}),
+        supported: true,
+        state: 'installing',
+        busy: true,
+        ready: false,
+        error: '',
+        message: 'Installing Linux hardware video support…'
+      };
+      runtime.emit('client.video-acceleration.installing', {
+        packageManager: normalizeString(state.videoAcceleration.packageManager?.id, 40)
+      });
+      try {
+        const result = await options.installVideoAcceleration();
+        state.videoAcceleration = {
+          ...(result && typeof result === 'object' ? result : {}),
+          busy: false
+        };
+        const ok = state.videoAcceleration.ready === true;
+        runtime.emit(ok ? 'client.video-acceleration.ready' : 'client.video-acceleration.failed', {
+          encoder: normalizeString(state.videoAcceleration.encoder, 80),
+          driver: normalizeString(state.videoAcceleration.driver, 80),
+          error: normalizeString(state.videoAcceleration.error, 240)
+        });
+        respondJson(ok ? 200 : 409, { ...getState(), ok });
+        if (ok && state.videoAcceleration.restartAgent) {
+          setTimeout(() => options.onVideoAccelerationReady?.(state.videoAcceleration), 150);
+        }
+      } catch (error) {
+        state.videoAcceleration = {
+          ...(state.videoAcceleration || {}),
+          state: 'error',
+          busy: false,
+          ready: false,
+          error: normalizeString(error?.message || error, 320)
+        };
+        runtime.emit('client.video-acceleration.failed', { error: state.videoAcceleration.error });
+        respondJson(409, { ok: false, ...getState(), error: state.videoAcceleration.error });
+      }
+      return;
+    }
+    if (pathname === '/api/runtime/switch-role' && req.method === 'POST') {
       const body = parseJsonBody(await readBody(req));
       if (String(body.role || '').trim().toLowerCase() !== 'hub') {
         respondJson(400, { ok: false, error: 'client-can-only-transition-to-hub' });
@@ -1077,6 +1199,8 @@ export function createClientRuntimeServer(options = {}) {
         if (patch.agent.state === 'running') runtime.update({ state: RuntimeState.RUNNING }, 'agent-running');
       }
       if (patch.manager) state.manager = normalizeString(patch.manager, 256);
+      if (patch.pairToken) state.pairToken = normalizeString(patch.pairToken, 256);
+      if (normalizeSlotNumber(patch.slotNumber)) state.slotNumber = normalizeSlotNumber(patch.slotNumber);
       if (patch.assignedHubId) state.assignedHubId = normalizeString(patch.assignedHubId, 160);
       if (patch.message) state.message = normalizeString(patch.message, 1000);
       if (Number.isInteger(patch.roleVersion)) state.roleVersion = patch.roleVersion;

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

@@ -0,0 +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…'
+  };
+}