@mindexec/cli 0.2.2 → 0.2.4

package/remote-hub.js

@@ -0,0 +1,737 @@
+import net from 'net';
+import os from 'os';
+import crypto from 'crypto';
+
+const DEFAULT_REMOTE_HUB_PORT = 5197;
+const DEFAULT_REMOTE_HUB_HOST = '127.0.0.1';
+const DEFAULT_HEARTBEAT_MS = 5000;
+const MAX_LINE_CHARS = 4 * 1024 * 1024;
+const MAX_THUMBNAIL_BASE64_CHARS = 3 * 1024 * 1024;
+const MAX_AGENT_TASK_CHARS = 4000;
+const MAX_AGENT_TASK_RESULT_CHARS = 3000;
+const RECENT_TASK_LIMIT = 12;
+const REMOTE_PROTOCOL_VERSION = 1;
+
+function isEnabledValue(value, fallback = true) {
+    if (value === undefined || value === null || value === '') {
+        return fallback;
+    }
+
+    return /^(1|true|yes|on)$/i.test(String(value).trim());
+}
+
+function isDisabledValue(value) {
+    return /^(1|true|yes|on)$/i.test(String(value || '').trim());
+}
+
+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 normalizePort(value) {
+    return clampNumber(value, 0, 65535, DEFAULT_REMOTE_HUB_PORT);
+}
+
+function safeString(value, maxLength = 200) {
+    return String(value ?? '').replace(/[\r\n\t]/g, ' ').trim().slice(0, maxLength);
+}
+
+function safeText(value, maxLength = 1000) {
+    return String(value ?? '').replace(/\0/g, '').trim().slice(0, maxLength);
+}
+
+function normalizeDeviceId(value) {
+    const id = safeString(value, 128).replace(/[^a-zA-Z0-9_.:-]/g, '-');
+    return id || crypto.randomUUID();
+}
+
+function maskToken(token) {
+    const value = String(token || '');
+    if (value.length <= 8) {
+        return value ? '****' : '';
+    }
+
+    return `${value.slice(0, 4)}...${value.slice(-4)}`;
+}
+
+function timingSafeStringEqual(left, right) {
+    const a = Buffer.from(String(left || ''), 'utf8');
+    const b = Buffer.from(String(right || ''), 'utf8');
+    if (a.length !== b.length) {
+        return false;
+    }
+
+    return crypto.timingSafeEqual(a, b);
+}
+
+function parseJsonLine(line) {
+    const text = String(line || '').trim();
+    if (!text) {
+        return null;
+    }
+
+    return JSON.parse(text);
+}
+
+function serializeDevice(device) {
+    if (!device) {
+        return null;
+    }
+
+    return {
+        deviceId: device.deviceId,
+        sessionId: device.sessionId,
+        deviceName: device.deviceName,
+        hostname: device.hostname,
+        platform: device.platform,
+        arch: device.arch,
+        pid: device.pid,
+        agentVersion: device.agentVersion,
+        capabilities: { ...device.capabilities },
+        connected: device.connected,
+        connectedAt: device.connectedAt,
+        disconnectedAt: device.disconnectedAt,
+        lastSeenAt: device.lastSeenAt,
+        lastStatusAt: device.lastStatusAt,
+        lastDisconnectReason: device.lastDisconnectReason,
+        remoteAddress: device.remoteAddress,
+        remotePort: device.remotePort,
+        latestThumbnail: device.latestThumbnail ? { ...device.latestThumbnail } : null,
+        latestTask: device.latestTask ? { ...device.latestTask } : null,
+        recentTasks: Array.isArray(device.recentTasks)
+            ? device.recentTasks.map(task => ({ ...task }))
+            : [],
+        status: { ...device.status },
+        counters: { ...device.counters }
+    };
+}
+
+function writeJsonLine(socket, payload) {
+    if (!socket || socket.destroyed) {
+        return false;
+    }
+
+    socket.write(`${JSON.stringify(payload)}\n`);
+    return true;
+}
+
+export function createRemoteHub(options = {}) {
+    const env = options.env || process.env;
+    const logEvent = options.logEvent || (() => {});
+    const logWarn = options.logWarn || (() => {});
+    const emitEvent = options.emitEvent || (() => {});
+
+    const enabled = isEnabledValue(env.MINDEXEC_REMOTE_HUB ?? env.REMOTE_HUB_ENABLED, true)
+        && !isDisabledValue(env.REMOTE_HUB_DISABLED);
+    const host = safeString(env.REMOTE_HUB_HOST || DEFAULT_REMOTE_HUB_HOST, 128);
+    const requestedPort = normalizePort(env.REMOTE_HUB_PORT || DEFAULT_REMOTE_HUB_PORT);
+    const heartbeatMs = clampNumber(env.REMOTE_HUB_HEARTBEAT_MS, 1000, 60000, DEFAULT_HEARTBEAT_MS);
+    const pairToken = safeString(
+        env.REMOTE_HUB_PAIR_TOKEN || env.MINDEXEC_REMOTE_PAIR_TOKEN || crypto.randomBytes(6).toString('hex'),
+        256);
+
+    const devices = new Map();
+    const sockets = new Map();
+    const allSockets = new Set();
+    let server = null;
+    let started = false;
+    let boundPort = requestedPort;
+    let lastError = '';
+
+    function getStatus({ includeSecrets = false } = {}) {
+        const connectedDevices = [...devices.values()].filter(device => device.connected).length;
+        return {
+            enabled,
+            started,
+            host,
+            port: boundPort || requestedPort,
+            protocol: 'tcp-jsonl',
+            protocolVersion: REMOTE_PROTOCOL_VERSION,
+            heartbeatMs,
+            agentPackage: '@mindexec/remote',
+            agentEndpoint: `${host}:${boundPort || requestedPort}`,
+            pairToken: includeSecrets ? pairToken : undefined,
+            pairTokenPreview: maskToken(pairToken),
+            deviceCount: devices.size,
+            connectedDeviceCount: connectedDevices,
+            canvasDeviceListMode: 'all-devices',
+            canvasPagination: 'none',
+            externalExposure: host === '0.0.0.0' || host === '::',
+            lastError
+        };
+    }
+
+    function listDevices() {
+        return [...devices.values()]
+            .map(serializeDevice)
+            .filter(Boolean)
+            .sort((a, b) => {
+                const nameCompare = String(a.deviceName || '').localeCompare(String(b.deviceName || ''));
+                if (nameCompare !== 0) {
+                    return nameCompare;
+                }
+
+                return String(a.deviceId).localeCompare(String(b.deviceId));
+            });
+    }
+
+    function emitRemoteEvent(type, device = null, extra = {}) {
+        emitEvent(type, {
+            ...extra,
+            remoteHub: getStatus({ includeSecrets: false }),
+            device: serializeDevice(device)
+        });
+    }
+
+    function closeExistingDeviceSocket(deviceId, nextSessionId) {
+        const existing = devices.get(deviceId);
+        if (!existing?.socket || existing.socket.destroyed) {
+            return;
+        }
+
+        existing.lastDisconnectReason = 'replaced-by-new-session';
+        writeJsonLine(existing.socket, {
+            type: 'disconnect',
+            reason: 'replaced-by-new-session',
+            nextSessionId
+        });
+        existing.socket.destroy();
+    }
+
+    function attachDevice(socket, hello) {
+        const now = new Date().toISOString();
+        const sessionId = crypto.randomUUID();
+        const deviceId = normalizeDeviceId(hello.deviceId);
+
+        closeExistingDeviceSocket(deviceId, sessionId);
+
+        const device = {
+            socket,
+            deviceId,
+            sessionId,
+            deviceName: safeString(hello.deviceName || hello.hostname || deviceId, 120),
+            hostname: safeString(hello.hostname, 120),
+            platform: safeString(hello.platform, 80),
+            arch: safeString(hello.arch, 40),
+            pid: Number.isFinite(Number(hello.pid)) ? Number(hello.pid) : 0,
+            agentVersion: safeString(hello.agentVersion, 40),
+            capabilities: typeof hello.capabilities === 'object' && hello.capabilities
+                ? { ...hello.capabilities }
+                : {},
+            connected: true,
+            connectedAt: now,
+            disconnectedAt: '',
+            lastSeenAt: now,
+            lastStatusAt: '',
+            lastDisconnectReason: '',
+            remoteAddress: socket.remoteAddress || '',
+            remotePort: socket.remotePort || 0,
+            status: {},
+            latestThumbnail: null,
+            latestTask: null,
+            recentTasks: [],
+            pendingTaskCommands: new Map(),
+            counters: {
+                messagesReceived: 1,
+                statusReceived: 0,
+                commandsSent: 0,
+                commandResultsReceived: 0,
+                thumbnailFramesReceived: 0,
+                thumbnailFramesDropped: 0,
+                tasksQueued: 0,
+                taskResultsReceived: 0,
+                taskResultsFailed: 0
+            }
+        };
+
+        devices.set(deviceId, device);
+        sockets.set(socket, deviceId);
+        writeJsonLine(socket, {
+            type: 'welcome',
+            protocolVersion: REMOTE_PROTOCOL_VERSION,
+            sessionId,
+            deviceId,
+            heartbeatMs,
+            serverTime: now
+        });
+
+        logEvent('remote', `device connected ${device.deviceName} (${deviceId})`, 'success');
+        emitRemoteEvent('RemoteDeviceConnected', device);
+        return device;
+    }
+
+    function detachSocket(socket, reason = 'socket-closed') {
+        const deviceId = sockets.get(socket);
+        sockets.delete(socket);
+        if (!deviceId) {
+            return;
+        }
+
+        const device = devices.get(deviceId);
+        if (!device || device.socket !== socket) {
+            return;
+        }
+
+        device.connected = false;
+        device.socket = null;
+        device.disconnectedAt = new Date().toISOString();
+        device.lastDisconnectReason = reason;
+        logWarn('remote', `device disconnected ${device.deviceName} (${deviceId}): ${reason}`);
+        emitRemoteEvent('RemoteDeviceDisconnected', device, { reason });
+    }
+
+    function rememberDeviceTask(device, task) {
+        if (!device || !task) {
+            return null;
+        }
+
+        const existingIndex = device.recentTasks.findIndex(item =>
+            item.taskId === task.taskId || item.commandId === task.commandId);
+        if (existingIndex >= 0) {
+            device.recentTasks.splice(existingIndex, 1);
+        }
+
+        device.recentTasks.unshift(task);
+        if (device.recentTasks.length > RECENT_TASK_LIMIT) {
+            device.recentTasks.length = RECENT_TASK_LIMIT;
+        }
+
+        device.latestTask = task;
+        if (task.commandId) {
+            device.pendingTaskCommands.set(task.commandId, task);
+        }
+
+        return task;
+    }
+
+    function summarizeTaskResult(result) {
+        if (result && typeof result === 'object') {
+            return safeText(
+                result.summary
+                    || result.message
+                    || result.output
+                    || result.result
+                    || JSON.stringify(result),
+                MAX_AGENT_TASK_RESULT_CHARS);
+        }
+
+        return safeText(result ?? '', MAX_AGENT_TASK_RESULT_CHARS);
+    }
+
+    function applyTaskResult(device, commandId, result, error) {
+        if (!device || !commandId) {
+            return null;
+        }
+
+        const resultTaskId = result && typeof result === 'object'
+            ? safeString(result.taskId, 128)
+            : '';
+        const task = resultTaskId
+            ? device.recentTasks.find(item => item.taskId === resultTaskId)
+            : device.pendingTaskCommands.get(commandId);
+        if (!task) {
+            return null;
+        }
+
+        const now = device.lastSeenAt || new Date().toISOString();
+        const status = error
+            ? 'failed'
+            : safeString(result?.status, 40) || 'completed';
+        task.status = status;
+        task.updatedAt = now;
+        task.completedAt = safeString(result?.completedAt, 80) || now;
+        task.error = error;
+        task.resultSummary = error || summarizeTaskResult(result);
+        task.resultKind = safeString(result?.kind || result?.mode || 'agent-task', 80);
+        device.latestTask = task;
+        device.pendingTaskCommands.delete(commandId);
+        device.counters.taskResultsReceived += 1;
+        if (error) {
+            device.counters.taskResultsFailed += 1;
+        }
+
+        return task;
+    }
+
+    function handleAgentMessage(socket, state, message) {
+        if (!message || typeof message !== 'object') {
+            return;
+        }
+
+        if (!state.authenticated) {
+            if (message.type !== 'hello') {
+                writeJsonLine(socket, { type: 'error', error: 'hello-required' });
+                socket.destroy();
+                return;
+            }
+
+            if (!timingSafeStringEqual(message.pairToken, pairToken)) {
+                writeJsonLine(socket, { type: 'error', error: 'invalid-pair-token' });
+                socket.destroy();
+                return;
+            }
+
+            state.authenticated = true;
+            state.device = attachDevice(socket, message);
+            return;
+        }
+
+        const device = state.device;
+        if (!device) {
+            socket.destroy();
+            return;
+        }
+
+        device.counters.messagesReceived += 1;
+        device.lastSeenAt = new Date().toISOString();
+
+        switch (message.type) {
+            case 'heartbeat':
+            case 'status':
+                device.status = typeof message.status === 'object' && message.status
+                    ? { ...message.status }
+                    : {};
+                device.lastStatusAt = device.lastSeenAt;
+                device.counters.statusReceived += 1;
+                emitRemoteEvent('RemoteDeviceStatus', device);
+                break;
+            case 'command.result':
+                device.counters.commandResultsReceived += 1;
+                {
+                    const commandId = safeString(message.commandId, 128);
+                    const error = safeString(message.error, 500);
+                    const task = applyTaskResult(device, commandId, message.result ?? null, error);
+                    if (task) {
+                        emitRemoteEvent('RemoteTaskResult', device, {
+                            commandId,
+                            taskId: task.taskId,
+                            status: task.status,
+                            error: task.error
+                        });
+                    }
+                }
+                emitRemoteEvent('RemoteCommandResult', device, {
+                    commandId: safeString(message.commandId, 128),
+                    result: message.result ?? null,
+                    error: safeString(message.error, 500)
+                });
+                break;
+            case 'thumbnail.frame': {
+                const frameData = safeString(message.data, MAX_THUMBNAIL_BASE64_CHARS + 1);
+                const frameSeq = Number(message.frameSeq);
+                if (!frameData || frameData.length > MAX_THUMBNAIL_BASE64_CHARS || !Number.isFinite(frameSeq)) {
+                    device.counters.thumbnailFramesDropped += 1;
+                    emitRemoteEvent('RemoteFrameDropped', device, {
+                        reason: 'invalid-thumbnail-frame',
+                        frameSeq: Number.isFinite(frameSeq) ? frameSeq : null
+                    });
+                    break;
+                }
+
+                const mimeType = safeString(message.mimeType || message.format || 'image/jpeg', 80) || 'image/jpeg';
+                const capturedAt = safeString(message.capturedAt, 80) || device.lastSeenAt;
+                device.latestThumbnail = {
+                    streamId: safeString(message.streamId, 128) || 'thumbnail',
+                    frameSeq,
+                    commandId: safeString(message.commandId, 128),
+                    width: Number.isFinite(Number(message.width)) ? Number(message.width) : 0,
+                    height: Number.isFinite(Number(message.height)) ? Number(message.height) : 0,
+                    mimeType,
+                    format: mimeType,
+                    capturedAt,
+                    receivedAt: device.lastSeenAt,
+                    byteLength: Math.floor(frameData.length * 3 / 4),
+                    dataUrl: frameData.startsWith('data:')
+                        ? frameData
+                        : `data:${mimeType};base64,${frameData}`
+                };
+                device.counters.thumbnailFramesReceived += 1;
+                emitRemoteEvent('RemoteFrameReceived', device, {
+                    streamId: device.latestThumbnail.streamId,
+                    frameSeq,
+                    width: device.latestThumbnail.width,
+                    height: device.latestThumbnail.height
+                });
+                break;
+            }
+            default:
+                emitRemoteEvent('RemoteAgentMessageIgnored', device, {
+                    messageType: safeString(message.type, 80)
+                });
+                break;
+        }
+    }
+
+    function handleSocket(socket) {
+        allSockets.add(socket);
+        socket.setEncoding('utf8');
+        socket.setNoDelay(true);
+        socket.setKeepAlive(true, heartbeatMs);
+
+        const state = {
+            authenticated: false,
+            device: null,
+            buffer: ''
+        };
+
+        const helloTimer = setTimeout(() => {
+            if (!state.authenticated) {
+                writeJsonLine(socket, { type: 'error', error: 'hello-timeout' });
+                socket.destroy();
+            }
+        }, 10000);
+
+        socket.on('data', chunk => {
+            state.buffer += chunk;
+            if (state.buffer.length > MAX_LINE_CHARS) {
+                writeJsonLine(socket, { type: 'error', error: 'message-too-large' });
+                socket.destroy();
+                return;
+            }
+
+            let newlineIndex = state.buffer.indexOf('\n');
+            while (newlineIndex >= 0) {
+                const line = state.buffer.slice(0, newlineIndex);
+                state.buffer = state.buffer.slice(newlineIndex + 1);
+
+                try {
+                    const message = parseJsonLine(line);
+                    handleAgentMessage(socket, state, message);
+                } catch (err) {
+                    writeJsonLine(socket, { type: 'error', error: 'invalid-json' });
+                    logWarn('remote', `invalid agent message: ${err?.message || err}`);
+                }
+
+                newlineIndex = state.buffer.indexOf('\n');
+            }
+        });
+
+        socket.on('close', () => {
+            allSockets.delete(socket);
+            clearTimeout(helloTimer);
+            detachSocket(socket);
+        });
+        socket.on('error', err => {
+            allSockets.delete(socket);
+            clearTimeout(helloTimer);
+            detachSocket(socket, err?.message || 'socket-error');
+        });
+    }
+
+    async function start() {
+        if (!enabled || started) {
+            return getStatus({ includeSecrets: false });
+        }
+
+        await new Promise((resolve, reject) => {
+            server = net.createServer(handleSocket);
+            server.once('error', err => {
+                lastError = err?.message || String(err);
+                server = null;
+                reject(err);
+            });
+            server.listen(requestedPort, host, () => {
+                started = true;
+                boundPort = server.address()?.port || requestedPort;
+                lastError = '';
+                logEvent('remote', `RemoteHub listening on tcp://${host}:${boundPort}`, 'success');
+                if (host === '0.0.0.0' || host === '::') {
+                    logWarn('remote', 'RemoteHub is externally reachable. Use a strong pairing token and trusted network.');
+                }
+                emitRemoteEvent('RemoteHubStarted', null);
+                resolve();
+            });
+        });
+
+        return getStatus({ includeSecrets: false });
+    }
+
+    async function close() {
+        for (const device of devices.values()) {
+            if (device.socket && !device.socket.destroyed) {
+                writeJsonLine(device.socket, { type: 'disconnect', reason: 'hub-shutdown' });
+                device.socket.destroy();
+            }
+        }
+
+        for (const socket of allSockets) {
+            if (!socket.destroyed) {
+                socket.destroy();
+            }
+        }
+
+        sockets.clear();
+        if (!server) {
+            started = false;
+            return;
+        }
+
+        await new Promise(resolve => {
+            let settled = false;
+            const settle = () => {
+                if (settled) {
+                    return;
+                }
+
+                settled = true;
+                clearTimeout(closeTimer);
+                resolve();
+            };
+
+            const closeTimer = setTimeout(settle, 1000);
+            closeTimer.unref?.();
+
+            try {
+                server.close(settle);
+            } catch {
+                settle();
+            }
+        });
+
+        server = null;
+        started = false;
+    }
+
+    function disconnectDevice(deviceId, reason = 'manager-disconnect') {
+        const device = devices.get(String(deviceId || ''));
+        if (!device?.socket || device.socket.destroyed) {
+            return false;
+        }
+
+        writeJsonLine(device.socket, { type: 'disconnect', reason });
+        device.socket.destroy();
+        return true;
+    }
+
+    function sendCommand(deviceId, command) {
+        const device = devices.get(String(deviceId || ''));
+        if (!device?.socket || device.socket.destroyed || !device.connected) {
+            return { ok: false, error: 'device-not-connected' };
+        }
+
+        const commandId = safeString(command?.commandId, 128) || crypto.randomUUID();
+        const payload = {
+            type: 'command',
+            commandId,
+            command: safeString(command?.command || 'ping', 80),
+            payload: command?.payload ?? null,
+            issuedAt: new Date().toISOString()
+        };
+
+        writeJsonLine(device.socket, payload);
+        device.counters.commandsSent += 1;
+        emitRemoteEvent('RemoteCommandQueued', device, {
+            commandId,
+            command: payload.command
+        });
+        return { ok: true, commandId };
+    }
+
+    function requestAgentTask(deviceId, options = {}) {
+        const device = devices.get(String(deviceId || ''));
+        if (!device?.socket || device.socket.destroyed || !device.connected) {
+            return { ok: false, error: 'device-not-connected' };
+        }
+
+        const instruction = safeText(options.instruction, MAX_AGENT_TASK_CHARS);
+        if (!instruction) {
+            return { ok: false, error: 'missing-instruction' };
+        }
+
+        const now = new Date().toISOString();
+        const commandId = safeString(options.commandId, 128) || crypto.randomUUID();
+        const taskId = safeString(options.taskId, 128) || crypto.randomUUID();
+        const title = safeString(options.title, 120)
+            || safeString(instruction.split(/\r?\n/)[0], 120)
+            || 'Remote task';
+        const task = {
+            taskId,
+            commandId,
+            title,
+            instructionPreview: safeText(instruction, 320),
+            status: 'queued',
+            approvalLevel: 'task-only',
+            requestedAt: now,
+            sentAt: now,
+            updatedAt: now,
+            completedAt: '',
+            error: '',
+            resultKind: '',
+            resultSummary: ''
+        };
+
+        const sent = writeJsonLine(device.socket, {
+            type: 'command',
+            commandId,
+            command: 'agent.task',
+            payload: {
+                taskId,
+                title,
+                instruction,
+                approvalLevel: 'task-only',
+                requestedAt: now
+            },
+            issuedAt: now
+        });
+
+        if (!sent) {
+            return { ok: false, error: 'device-not-connected' };
+        }
+
+        device.counters.commandsSent += 1;
+        device.counters.tasksQueued += 1;
+        rememberDeviceTask(device, task);
+        emitRemoteEvent('RemoteTaskQueued', device, {
+            commandId,
+            taskId,
+            title
+        });
+        return { ok: true, commandId, taskId };
+    }
+
+    function requestThumbnail(deviceId, options = {}) {
+        return sendCommand(deviceId, {
+            command: 'thumbnail.capture',
+            commandId: safeString(options.commandId, 128) || crypto.randomUUID(),
+            payload: {
+                streamId: safeString(options.streamId, 128) || `thumb-${Date.now()}`,
+                maxWidth: clampNumber(options.maxWidth, 160, 1920, 360),
+                maxHeight: clampNumber(options.maxHeight, 90, 1080, 220),
+                quality: clampNumber(options.quality, 20, 95, 55),
+                requestedAt: new Date().toISOString()
+            }
+        });
+    }
+
+    function getDeviceThumbnail(deviceId) {
+        const device = devices.get(String(deviceId || ''));
+        return device?.latestThumbnail ? { ...device.latestThumbnail } : null;
+    }
+
+    return {
+        start,
+        close,
+        getStatus,
+        listDevices,
+        disconnectDevice,
+        sendCommand,
+        requestAgentTask,
+        requestThumbnail,
+        getDeviceThumbnail,
+        getPairToken: () => pairToken
+    };
+}
+
+export function getDefaultRemoteAgentDeviceInfo() {
+    return {
+        hostname: os.hostname(),
+        platform: os.platform(),
+        arch: os.arch(),
+        pid: process.pid
+    };
+}