@livedesk/client 0.1.0

package/bin/livedesk-client-node.js

@@ -0,0 +1,930 @@
+#!/usr/bin/env node
+
+import net from 'net';
+import os from 'os';
+import path from 'path';
+import crypto from 'crypto';
+import { promises as fs } from 'fs';
+
+const AGENT_VERSION = '0.1.15-livedesk.1';
+const DEFAULT_MANAGER = '127.0.0.1:5197';
+const DEFAULT_HEARTBEAT_MS = 5000;
+const DEFAULT_AI_MODEL = 'gpt-5.4-mini';
+const DEFAULT_LIVE_FPS = 20;
+const MAX_LIVE_FPS = 24;
+const MAX_FRAME_BASE64_CHARS = 3 * 1024 * 1024;
+const MAX_AI_OUTPUT_CHARS = 6000;
+
+function printHelp() {
+    console.log(`
+LiveDesk Client
+
+Usage:
+  npx @livedesk/client connect --manager 127.0.0.1:5197 --pair <token>
+
+Options:
+  --manager <host:port>  RemoteHub address. Default: ${DEFAULT_MANAGER}
+  --pair <token>         RemoteHub pairing token. Can also use LIVEDESK_CLIENT_PAIR_TOKEN.
+  --name <name>          Friendly device name. Default: OS hostname.
+  --heartbeat <ms>       Status heartbeat interval. Default: ${DEFAULT_HEARTBEAT_MS}
+  --device-id <id>       Stable device id. Default: generated and saved per OS user.
+  --thumbnail            Enable thumbnail capture when supported. Default on Windows.
+  --no-thumbnail         Disable thumbnail capture capability.
+  --live                 Enable focused live screen streaming. Default on.
+  --no-live              Disable focused live screen streaming.
+  --tasks                Enable safe remote task inbox. Default on.
+  --no-tasks             Disable remote task dispatch capability.
+  --ai                   Enable OpenAI-backed remote AI assist tasks.
+  --no-ai                Disable OpenAI-backed remote AI assist tasks.
+  --ai-model <model>     OpenAI model for AI assist. Default: ${DEFAULT_AI_MODEL}
+  --fake-ai              Use deterministic AI assist responses for smoke tests.
+  --fake-thumbnail       Use generated thumbnail frames for smoke tests.
+  --exit-on-disconnect   Exit after manager disconnect. Useful for tests.
+  --once                 Connect, send one status packet, and exit after welcome.
+  --version              Show the agent version.
+  --help                 Show this help.
+`.trim());
+}
+
+function isTruthy(value) {
+    return /^(1|true|yes|on)$/i.test(String(value || '').trim());
+}
+
+function isFalsy(value) {
+    return /^(0|false|no|off)$/i.test(String(value || '').trim());
+}
+
+function parseArgs(argv) {
+    const defaultDesktopCaptureEnabled = os.platform() === 'win32';
+    const result = {
+        command: 'connect',
+        manager: process.env.LIVEDESK_CLIENT_MANAGER || process.env.MINDEXEC_REMOTE_MANAGER || DEFAULT_MANAGER,
+        pair: process.env.LIVEDESK_CLIENT_PAIR_TOKEN || process.env.MINDEXEC_REMOTE_PAIR_TOKEN || '',
+        name: process.env.LIVEDESK_CLIENT_NAME || process.env.MINDEXEC_REMOTE_NAME || os.hostname(),
+        heartbeatMs: DEFAULT_HEARTBEAT_MS,
+        deviceId: '',
+        thumbnailEnabled: defaultDesktopCaptureEnabled && !isFalsy(process.env.LIVEDESK_CLIENT_THUMBNAIL ?? process.env.MINDEXEC_REMOTE_THUMBNAIL),
+        liveEnabled: defaultDesktopCaptureEnabled && !isFalsy(process.env.LIVEDESK_CLIENT_LIVE ?? process.env.MINDEXEC_REMOTE_LIVE),
+        taskEnabled: !isFalsy(process.env.LIVEDESK_CLIENT_TASKS ?? process.env.MINDEXEC_REMOTE_TASKS),
+        aiEnabled: isTruthy(process.env.LIVEDESK_CLIENT_AI || process.env.MINDEXEC_REMOTE_AI),
+        aiModel: process.env.LIVEDESK_CLIENT_AI_MODEL || process.env.MINDEXEC_REMOTE_AI_MODEL || process.env.OPENAI_MODEL || DEFAULT_AI_MODEL,
+        openAiApiKey: process.env.OPENAI_API_KEY || '',
+        fakeAi: isTruthy(process.env.LIVEDESK_CLIENT_FAKE_AI || process.env.MINDEXEC_REMOTE_FAKE_AI),
+        fakeThumbnail: isTruthy(process.env.LIVEDESK_CLIENT_FAKE_THUMBNAIL || process.env.MINDEXEC_REMOTE_FAKE_THUMBNAIL),
+        exitOnDisconnect: false,
+        once: false,
+        version: false,
+        help: false
+    };
+
+    const args = [...argv];
+    if (args[0] && !args[0].startsWith('-')) {
+        result.command = args.shift();
+    }
+
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        switch (arg) {
+            case '--manager':
+                result.manager = args[++index] || result.manager;
+                break;
+            case '--pair':
+                result.pair = args[++index] || '';
+                break;
+            case '--name':
+                result.name = args[++index] || result.name;
+                break;
+            case '--heartbeat':
+                result.heartbeatMs = Number(args[++index] || DEFAULT_HEARTBEAT_MS);
+                break;
+            case '--device-id':
+                result.deviceId = args[++index] || '';
+                break;
+            case '--thumbnail':
+                result.thumbnailEnabled = true;
+                break;
+            case '--no-thumbnail':
+                result.thumbnailEnabled = false;
+                break;
+            case '--live':
+                result.liveEnabled = true;
+                break;
+            case '--no-live':
+                result.liveEnabled = false;
+                break;
+            case '--tasks':
+                result.taskEnabled = true;
+                break;
+            case '--no-tasks':
+                result.taskEnabled = false;
+                break;
+            case '--ai':
+                result.aiEnabled = true;
+                result.taskEnabled = true;
+                break;
+            case '--no-ai':
+                result.aiEnabled = false;
+                break;
+            case '--ai-model':
+                result.aiModel = args[++index] || result.aiModel;
+                break;
+            case '--fake-ai':
+                result.fakeAi = true;
+                result.aiEnabled = true;
+                result.taskEnabled = true;
+                break;
+            case '--fake-thumbnail':
+                result.fakeThumbnail = true;
+                result.thumbnailEnabled = true;
+                break;
+            case '--exit-on-disconnect':
+                result.exitOnDisconnect = true;
+                break;
+            case '--once':
+                result.once = true;
+                break;
+            case '--help':
+            case '-h':
+                result.help = true;
+                break;
+            case '--version':
+            case '-v':
+                result.version = true;
+                break;
+            default:
+                throw new Error(`Unknown option: ${arg}`);
+        }
+    }
+
+    if (!Number.isFinite(result.heartbeatMs) || result.heartbeatMs < 1000) {
+        result.heartbeatMs = DEFAULT_HEARTBEAT_MS;
+    }
+
+    return result;
+}
+
+function parseManagerAddress(value) {
+    let text = String(value || DEFAULT_MANAGER).trim();
+    text = text.replace(/^tcp:\/\//i, '');
+    const separator = text.lastIndexOf(':');
+    if (separator <= 0) {
+        return {
+            host: text || '127.0.0.1',
+            port: 5197
+        };
+    }
+
+    const host = text.slice(0, separator).trim() || '127.0.0.1';
+    const port = Number(text.slice(separator + 1));
+    return {
+        host,
+        port: Number.isFinite(port) ? port : 5197
+    };
+}
+
+function normalizeDeviceId(value) {
+    return String(value || '').trim().replace(/[^a-zA-Z0-9_.:-]/g, '-').slice(0, 128);
+}
+
+async function getDeviceId(explicitDeviceId = '') {
+    const explicit = normalizeDeviceId(explicitDeviceId);
+    if (explicit) {
+        return explicit;
+    }
+
+    const stateDir = path.join(os.homedir(), '.livedesk-client');
+    const statePath = path.join(stateDir, 'device.json');
+    try {
+        const state = JSON.parse(await fs.readFile(statePath, 'utf8'));
+        const existing = normalizeDeviceId(state.deviceId);
+        if (existing) {
+            return existing;
+        }
+    } catch {
+        // Create a new device id below.
+    }
+
+    const deviceId = `livedesk-${crypto.randomUUID()}`;
+    await fs.mkdir(stateDir, { recursive: true });
+    await fs.writeFile(statePath, JSON.stringify({
+        deviceId,
+        createdAt: new Date().toISOString()
+    }, null, 2));
+    return deviceId;
+}
+
+function getStatus() {
+    const totalMem = os.totalmem();
+    const freeMem = os.freemem();
+    return {
+        uptimeSec: Math.round(os.uptime()),
+        loadavg: os.loadavg(),
+        totalMem,
+        freeMem,
+        usedMemRatio: totalMem > 0 ? Number(((totalMem - freeMem) / totalMem).toFixed(4)) : 0,
+        platform: os.platform(),
+        release: os.release(),
+        timestamp: new Date().toISOString()
+    };
+}
+
+function writeJsonLine(socket, payload) {
+    if (!socket || socket.destroyed) {
+        return false;
+    }
+
+    socket.write(`${JSON.stringify(payload)}\n`);
+    return true;
+}
+
+function wait(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+function clampNumber(value, min, max, fallback) {
+    const number = Number(value);
+    if (!Number.isFinite(number)) {
+        return fallback;
+    }
+
+    return Math.max(min, Math.min(max, Math.floor(number)));
+}
+
+function createFakeThumbnailFrame(options, payload, frameSeq) {
+    const width = clampNumber(payload?.maxWidth, 160, 1920, 360);
+    const height = clampNumber(payload?.maxHeight, 90, 1080, 220);
+    const now = new Date().toISOString();
+    const title = String(options.name || os.hostname()).replace(/[<>&"']/g, '_');
+    const svg = [
+        `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}">`,
+        '<rect width="100%" height="100%" fill="#0f172a"/>',
+        '<rect x="14" y="14" width="calc(100% - 28px)" height="calc(100% - 28px)" rx="12" fill="#1e293b" stroke="#38bdf8" stroke-width="2"/>',
+        `<text x="28" y="48" fill="#e2e8f0" font-family="Arial, sans-serif" font-size="20" font-weight="700">${title}</text>`,
+        `<text x="28" y="82" fill="#93c5fd" font-family="Arial, sans-serif" font-size="14">LiveDesk Client Thumbnail</text>`,
+        `<text x="28" y="${height - 30}" fill="#94a3b8" font-family="Consolas, monospace" font-size="12">${now}</text>`,
+        '</svg>'
+    ].join('');
+
+    return {
+        frameSeq,
+        width,
+        height,
+        mimeType: 'image/svg+xml',
+        data: Buffer.from(svg, 'utf8').toString('base64'),
+        capturedAt: now
+    };
+}
+
+function readJpegDimensions(buffer) {
+    if (!Buffer.isBuffer(buffer) || buffer.length < 4 || buffer[0] !== 0xff || buffer[1] !== 0xd8) {
+        return { width: 0, height: 0 };
+    }
+
+    let offset = 2;
+    while (offset + 9 < buffer.length) {
+        if (buffer[offset] !== 0xff) {
+            offset += 1;
+            continue;
+        }
+
+        const marker = buffer[offset + 1];
+        const blockLength = buffer.readUInt16BE(offset + 2);
+        if (blockLength < 2) {
+            break;
+        }
+
+        const isStartOfFrame = marker >= 0xc0
+            && marker <= 0xcf
+            && ![0xc4, 0xc8, 0xcc].includes(marker);
+        if (isStartOfFrame) {
+            return {
+                height: buffer.readUInt16BE(offset + 5),
+                width: buffer.readUInt16BE(offset + 7)
+            };
+        }
+
+        offset += 2 + blockLength;
+    }
+
+    return { width: 0, height: 0 };
+}
+
+async function captureNativeDesktopFrame(frameSeq) {
+    const screenshotModule = await import('node-screenshots');
+    const Monitor = screenshotModule.Monitor || screenshotModule.default?.Monitor;
+    if (!Monitor?.all) {
+        throw new Error('node-screenshots Monitor API is unavailable.');
+    }
+
+    const monitors = Monitor.all();
+    const monitor = monitors.find(item => item?.isPrimary?.() === true) || monitors[0];
+    if (!monitor?.captureImage) {
+        throw new Error('No capturable desktop monitor was found.');
+    }
+
+    const image = await monitor.captureImage();
+    const jpeg = await image.toJpeg();
+    const buffer = Buffer.isBuffer(jpeg) ? jpeg : Buffer.from(jpeg);
+    if (buffer.toString('base64').length > MAX_FRAME_BASE64_CHARS) {
+        throw new Error('Desktop capture exceeded the remote frame size limit.');
+    }
+
+    const dimensions = readJpegDimensions(buffer);
+    return {
+        frameSeq,
+        width: dimensions.width,
+        height: dimensions.height,
+        mimeType: 'image/jpeg',
+        data: buffer.toString('base64'),
+        capturedAt: new Date().toISOString()
+    };
+}
+
+async function captureDesktopThumbnailFrame(payload, frameSeq) {
+    return await captureNativeDesktopFrame(frameSeq);
+}
+
+async function captureScreenFrame(options, payload, frameSeq, capability = 'thumbnail') {
+    const enabled = capability === 'live' ? options.liveEnabled : options.thumbnailEnabled;
+    if (!enabled) {
+        throw new Error(`${capability} capability is disabled`);
+    }
+
+    return options.fakeThumbnail
+        ? createFakeThumbnailFrame(options, payload, frameSeq)
+        : await captureDesktopThumbnailFrame(payload, frameSeq);
+}
+
+async function captureThumbnailFrame(options, payload, frameSeq) {
+    return await captureScreenFrame(options, payload, frameSeq, 'thumbnail');
+}
+
+function normalizeApprovalLevel(value) {
+    const level = String(value || 'task-only').trim().toLowerCase();
+    return level === 'ai-assist' ? 'ai-assist' : 'task-only';
+}
+
+function buildAiPrompt(options, payload, instruction) {
+    const title = String(payload?.title || 'Remote AI task').trim();
+    return [
+        'You are the LiveDesk client AI assistant running on a controlled remote computer.',
+        'Complete the manager task as a text-only assistant.',
+        'Do not claim you used shell commands, file writes, browser automation, keyboard input, or mouse input.',
+        'If the task requires external side effects, explain what would be needed and stop.',
+        '',
+        `Device: ${options.name} (${os.hostname()}, ${os.platform()} ${os.release()}, ${os.arch()})`,
+        `Task title: ${title}`,
+        '',
+        'Manager instruction:',
+        instruction
+    ].join('\n');
+}
+
+function extractResponseText(response) {
+    if (typeof response?.output_text === 'string' && response.output_text.trim()) {
+        return response.output_text.trim();
+    }
+
+    const parts = [];
+    if (Array.isArray(response?.output)) {
+        for (const item of response.output) {
+            if (!Array.isArray(item?.content)) {
+                continue;
+            }
+
+            for (const content of item.content) {
+                if (typeof content?.text === 'string') {
+                    parts.push(content.text);
+                }
+                if (typeof content?.output_text === 'string') {
+                    parts.push(content.output_text);
+                }
+            }
+        }
+    }
+
+    return parts.join('\n').trim();
+}
+
+async function runAiAssistTask(options, payload, instruction) {
+    if (!options.aiEnabled) {
+        throw new Error('AI assist capability is disabled. Start the agent with --ai to enable it.');
+    }
+
+    if (options.fakeAi) {
+        return {
+            text: [
+                `Fake AI assist completed on ${options.name}.`,
+                '',
+                `Instruction: ${instruction.slice(0, 500)}`,
+                '',
+                'No shell, file, input, browser, or persistent side effects were performed.'
+            ].join('\n'),
+            model: 'fake-ai',
+            responseId: `fake-ai-${String(payload?.taskId || crypto.randomUUID()).slice(0, 96)}`
+        };
+    }
+
+    if (!options.openAiApiKey) {
+        throw new Error('OPENAI_API_KEY is required for --ai remote tasks.');
+    }
+
+    const openaiModule = await import('openai');
+    const OpenAI = openaiModule.default || openaiModule.OpenAI;
+    const client = new OpenAI({ apiKey: options.openAiApiKey });
+    const model = String(payload?.model || options.aiModel || DEFAULT_AI_MODEL).trim() || DEFAULT_AI_MODEL;
+    const response = await client.responses.create({
+        model,
+        input: buildAiPrompt(options, payload, instruction)
+    });
+    const text = extractResponseText(response);
+    if (!text) {
+        throw new Error('AI assist returned no text output.');
+    }
+
+    return {
+        text: text.slice(0, MAX_AI_OUTPUT_CHARS),
+        model,
+        responseId: response?.id || ''
+    };
+}
+
+function clampInteger(value, min, max, fallback) {
+    const number = Number(value);
+    if (!Number.isFinite(number)) {
+        return fallback;
+    }
+
+    return Math.max(min, Math.min(max, Math.floor(number)));
+}
+
+function stopLiveStream(activeStreams, streamId = '') {
+    if (streamId) {
+        const existing = activeStreams.get(streamId);
+        if (existing?.timer) {
+            clearInterval(existing.timer);
+        }
+        activeStreams.delete(streamId);
+        return existing ? 1 : 0;
+    }
+
+    let stopped = 0;
+    for (const stream of activeStreams.values()) {
+        if (stream?.timer) {
+            clearInterval(stream.timer);
+            stopped += 1;
+        }
+    }
+    activeStreams.clear();
+    return stopped;
+}
+
+function startLiveStream(socket, options, message, nextFrameSeq, activeStreams) {
+    if (!options.liveEnabled) {
+        throw new Error('live stream capability is disabled');
+    }
+
+    const payload = message.payload || {};
+    const streamId = String(payload.streamId || `live-${Date.now()}`)
+        .replace(/[^a-zA-Z0-9_.:-]/g, '-')
+        .slice(0, 128) || `live-${Date.now()}`;
+    const fps = clampInteger(payload.fps, 1, MAX_LIVE_FPS, DEFAULT_LIVE_FPS);
+    const intervalMs = Math.max(33, Math.round(1000 / fps));
+    stopLiveStream(activeStreams, streamId);
+
+    const stream = {
+        streamId,
+        fps,
+        intervalMs,
+        inFlight: false,
+        stopped: false,
+        frameDrops: 0,
+        timer: null
+    };
+
+    const captureAndSend = async () => {
+        if (stream.stopped || stream.inFlight || socket.destroyed) {
+            if (stream.inFlight) {
+                stream.frameDrops += 1;
+            }
+            return;
+        }
+
+        stream.inFlight = true;
+        try {
+            const frame = await captureScreenFrame(options, payload, nextFrameSeq(), 'live');
+            if (String(frame.data || '').length > MAX_FRAME_BASE64_CHARS) {
+                stream.frameDrops += 1;
+                return;
+            }
+
+            const sent = writeJsonLine(socket, {
+                type: 'stream.frame',
+                commandId: message.commandId,
+                streamId,
+                frameSeq: frame.frameSeq,
+                width: frame.width,
+                height: frame.height,
+                mimeType: frame.mimeType,
+                capturedAt: frame.capturedAt,
+                fps,
+                mode: 'remote-fast',
+                droppedByAgent: stream.frameDrops,
+                data: frame.data
+            });
+
+            if (!sent) {
+                stream.stopped = true;
+                stopLiveStream(activeStreams, streamId);
+            }
+        } catch {
+            stream.frameDrops += 1;
+        } finally {
+            stream.inFlight = false;
+        }
+    };
+
+    stream.timer = setInterval(() => {
+        captureAndSend().catch(() => {
+            stream.frameDrops += 1;
+        });
+    }, intervalMs);
+    stream.timer.unref?.();
+    activeStreams.set(streamId, stream);
+    captureAndSend().catch(() => {
+        stream.frameDrops += 1;
+    });
+    return { streamId, fps, intervalMs };
+}
+
+async function handleRemoteCommand(socket, options, message, nextFrameSeq, activeStreams) {
+    const command = String(message.command || '');
+    if (command === 'ping') {
+        writeJsonLine(socket, {
+            type: 'command.result',
+            commandId: message.commandId,
+            result: {
+                pong: true,
+                at: new Date().toISOString()
+            }
+        });
+        return;
+    }
+
+    if (command === 'agent.task') {
+        if (!options.taskEnabled) {
+            writeJsonLine(socket, {
+                type: 'command.result',
+                commandId: message.commandId,
+                error: 'remote task capability is disabled'
+            });
+            return;
+        }
+
+        const payload = message.payload || {};
+        const instruction = String(payload.instruction || '').replace(/\0/g, '').trim().slice(0, 4000);
+        if (!instruction) {
+            writeJsonLine(socket, {
+                type: 'command.result',
+                commandId: message.commandId,
+                error: 'missing task instruction'
+            });
+            return;
+        }
+
+        const approvalLevel = normalizeApprovalLevel(payload.approvalLevel);
+        const completedAt = new Date().toISOString();
+        const title = String(payload.title || instruction.split(/\r?\n/)[0] || 'Remote task')
+            .replace(/[\r\n\t]/g, ' ')
+            .trim()
+            .slice(0, 120);
+        if (approvalLevel === 'ai-assist') {
+            try {
+                const aiResult = await runAiAssistTask(options, payload, instruction);
+                writeJsonLine(socket, {
+                    type: 'command.result',
+                    commandId: message.commandId,
+                    result: {
+                        kind: 'agent.task',
+                        mode: 'ai-assist',
+                        taskId: String(payload.taskId || '').slice(0, 128),
+                        title,
+                        status: 'completed',
+                        summary: aiResult.text,
+                        sideEffects: 'none',
+                        model: aiResult.model,
+                        responseId: aiResult.responseId,
+                        instructionPreview: instruction.slice(0, 320),
+                        completedAt: new Date().toISOString()
+                    }
+                });
+            } catch (error) {
+                writeJsonLine(socket, {
+                    type: 'command.result',
+                    commandId: message.commandId,
+                    error: error?.message || String(error)
+                });
+            }
+            return;
+        }
+
+        writeJsonLine(socket, {
+            type: 'command.result',
+            commandId: message.commandId,
+            result: {
+                kind: 'agent.task',
+                mode: 'task-only',
+                taskId: String(payload.taskId || '').slice(0, 128),
+                title,
+                status: 'completed',
+                summary: `Task received by ${options.name}. Safe task-only mode confirmed receipt without shell, file, input, or browser side effects.`,
+                sideEffects: 'none',
+                instructionPreview: instruction.slice(0, 320),
+                device: {
+                    hostname: os.hostname(),
+                    platform: os.platform(),
+                    release: os.release(),
+                    arch: os.arch()
+                },
+                completedAt
+            }
+        });
+        return;
+    }
+
+    if (command === 'thumbnail.capture') {
+        try {
+            const frameSeq = nextFrameSeq();
+            const frame = await captureThumbnailFrame(options, message.payload || {}, frameSeq);
+            writeJsonLine(socket, {
+                type: 'thumbnail.frame',
+                commandId: message.commandId,
+                streamId: message.payload?.streamId || 'thumbnail',
+                frameSeq: frame.frameSeq,
+                width: frame.width,
+                height: frame.height,
+                mimeType: frame.mimeType,
+                capturedAt: frame.capturedAt,
+                data: frame.data
+            });
+            writeJsonLine(socket, {
+                type: 'command.result',
+                commandId: message.commandId,
+                result: {
+                    thumbnail: true,
+                    frameSeq: frame.frameSeq,
+                    width: frame.width,
+                    height: frame.height,
+                    capturedAt: frame.capturedAt
+                }
+            });
+        } catch (error) {
+            writeJsonLine(socket, {
+                type: 'command.result',
+                commandId: message.commandId,
+                error: error?.message || String(error)
+            });
+        }
+        return;
+    }
+
+    if (command === 'stream.start') {
+        try {
+            const started = startLiveStream(socket, options, message, nextFrameSeq, activeStreams);
+            writeJsonLine(socket, {
+                type: 'command.result',
+                commandId: message.commandId,
+                result: {
+                    stream: true,
+                    started: true,
+                    streamId: started.streamId,
+                    fps: started.fps,
+                    intervalMs: started.intervalMs,
+                    mode: 'remote-fast',
+                    viewOnly: true,
+                    inputControl: false,
+                    startedAt: new Date().toISOString()
+                }
+            });
+        } catch (error) {
+            writeJsonLine(socket, {
+                type: 'command.result',
+                commandId: message.commandId,
+                error: error?.message || String(error)
+            });
+        }
+        return;
+    }
+
+    if (command === 'stream.stop') {
+        const streamId = String(message.payload?.streamId || '').slice(0, 128);
+        const stopped = stopLiveStream(activeStreams, streamId);
+        writeJsonLine(socket, {
+            type: 'command.result',
+            commandId: message.commandId,
+            result: {
+                stream: true,
+                stopped: true,
+                streamId,
+                stoppedCount: stopped,
+                stoppedAt: new Date().toISOString()
+            }
+        });
+        return;
+    }
+
+    if (command === 'input.control') {
+        writeJsonLine(socket, {
+            type: 'command.result',
+            commandId: message.commandId,
+            error: 'input control is only available in the C# RemoteFast engine'
+        });
+        return;
+    }
+
+    writeJsonLine(socket, {
+        type: 'command.result',
+        commandId: message.commandId,
+        error: `Unsupported command: ${command}`
+    });
+}
+
+function connectOnce(options, deviceId) {
+    const manager = parseManagerAddress(options.manager);
+    return new Promise((resolve, reject) => {
+        const socket = net.createConnection({
+            host: manager.host,
+            port: manager.port
+        });
+
+        let buffer = '';
+        let heartbeatTimer = null;
+        let resolved = false;
+        let frameSeq = 0;
+        const activeStreams = new Map();
+
+        function cleanup() {
+            if (heartbeatTimer) {
+                clearInterval(heartbeatTimer);
+                heartbeatTimer = null;
+            }
+            stopLiveStream(activeStreams);
+        }
+
+        function finish(error = null) {
+            if (resolved) {
+                return;
+            }
+            resolved = true;
+            cleanup();
+            if (!socket.destroyed) {
+                socket.destroy();
+            }
+            if (error) {
+                reject(error);
+            } else {
+                resolve();
+            }
+        }
+
+        socket.setEncoding('utf8');
+        socket.setNoDelay(true);
+        socket.setKeepAlive(true, options.heartbeatMs);
+
+        socket.once('connect', () => {
+            writeJsonLine(socket, {
+                type: 'hello',
+                pairToken: options.pair,
+                deviceId,
+                deviceName: options.name,
+                hostname: os.hostname(),
+                platform: os.platform(),
+                arch: os.arch(),
+                pid: process.pid,
+                agentVersion: AGENT_VERSION,
+                capabilities: {
+                    status: true,
+                    thumbnail: options.thumbnailEnabled,
+                    liveStream: options.liveEnabled,
+                    control: false,
+                    computerAgent: options.taskEnabled,
+                    taskDispatch: options.taskEnabled,
+                    aiAssist: options.taskEnabled && options.aiEnabled && (options.fakeAi || !!options.openAiApiKey),
+                    aiModel: options.aiModel,
+                    aiProvider: options.fakeAi ? 'fake' : (options.openAiApiKey ? 'openai' : ''),
+                    externalEffects: false
+                }
+            });
+        });
+
+        socket.on('data', chunk => {
+            buffer += chunk;
+            let newlineIndex = buffer.indexOf('\n');
+            while (newlineIndex >= 0) {
+                const line = buffer.slice(0, newlineIndex).trim();
+                buffer = buffer.slice(newlineIndex + 1);
+                newlineIndex = buffer.indexOf('\n');
+                if (!line) {
+                    continue;
+                }
+
+                const message = JSON.parse(line);
+                if (message.type === 'welcome') {
+                    console.log(`Connected to RemoteHub as ${options.name} (${deviceId})`);
+                    writeJsonLine(socket, {
+                        type: 'status',
+                        status: getStatus()
+                    });
+                    if (options.once) {
+                        finish();
+                        return;
+                    }
+
+                    heartbeatTimer = setInterval(() => {
+                        writeJsonLine(socket, {
+                            type: 'status',
+                            status: getStatus()
+                        });
+                    }, options.heartbeatMs);
+                } else if (message.type === 'command') {
+                    handleRemoteCommand(socket, options, message, () => {
+                        frameSeq += 1;
+                        return frameSeq;
+                    }, activeStreams).catch(error => {
+                        writeJsonLine(socket, {
+                            type: 'command.result',
+                            commandId: message.commandId,
+                            error: error?.message || String(error)
+                        });
+                    });
+                } else if (message.type === 'disconnect') {
+                    finish();
+                    return;
+                } else if (message.type === 'error') {
+                    finish(new Error(message.error || 'RemoteHub rejected the connection.'));
+                    return;
+                }
+            }
+        });
+
+        socket.once('error', err => finish(err));
+        socket.once('close', () => finish());
+    });
+}
+
+async function connectWithRetry(options) {
+    if (!options.pair) {
+        throw new Error('Missing --pair token. Get it from the manager RemoteHub status.');
+    }
+
+    const deviceId = await getDeviceId(options.deviceId);
+    let attempt = 0;
+    let stopping = false;
+
+    process.once('SIGINT', () => {
+        stopping = true;
+        console.log('\nStopping LiveDesk Client...');
+    });
+    process.once('SIGTERM', () => {
+        stopping = true;
+    });
+
+    while (!stopping) {
+        try {
+            await connectOnce(options, deviceId);
+            if (options.once || options.exitOnDisconnect || stopping) {
+                return;
+            }
+            attempt = 0;
+        } catch (err) {
+            attempt += 1;
+            const delayMs = Math.min(10000, 500 * attempt);
+            console.error(`RemoteHub connection failed: ${err?.message || err}. Retrying in ${delayMs}ms.`);
+            await wait(delayMs);
+        }
+    }
+}
+
+async function main() {
+    const options = parseArgs(process.argv.slice(2));
+    if (options.version || options.command === 'version') {
+        console.log(AGENT_VERSION);
+        return;
+    }
+
+    if (options.help || options.command === 'help') {
+        printHelp();
+        return;
+    }
+
+    if (options.command !== 'connect') {
+        throw new Error(`Unknown command: ${options.command}`);
+    }
+
+    await connectWithRetry(options);
+}
+
+main().catch(err => {
+    console.error(err?.message || err);
+    process.exit(1);
+});