@mindexec/cli 0.2.1 → 0.2.3

package/README.md

@@ -45,6 +45,44 @@ precompressed static files from the npm bundle by default. Use
 `-KeepPackagedGalleryImages` or `-KeepPackagedPrecompressedAssets` only when
 testing a full untrimmed local package.
 
+## Remote Direct quick start
+
+LocalBridge also starts a separate RemoteHub listener for direct remote-agent
+experiments. By default it binds to loopback only:
+
+```bash
+npx @mindexec/cli
+npx @mindexec/remote connect --manager 127.0.0.1:5197 --pair <pair-token>
+```
+
+Read the pair token from the protected local endpoint:
+
+```bash
+curl -H "X-Bridge-Token: <bridge-token>" http://127.0.0.1:5147/api/remote/status
+```
+
+LAN/direct mode must be enabled explicitly by changing the RemoteHub bind host:
+
+```powershell
+$env:REMOTE_HUB_HOST="0.0.0.0"
+$env:REMOTE_HUB_PORT="5197"
+$env:REMOTE_HUB_PAIR_TOKEN="<strong-token>"
+npx @mindexec/cli
+```
+
+Device inventory is intentionally not paginated:
+
+```bash
+curl -H "X-Bridge-Token: <bridge-token>" http://127.0.0.1:5147/api/remote/devices
+```
+
+Request and read the latest view-only thumbnail for a connected device:
+
+```bash
+curl -X POST -H "X-Bridge-Token: <bridge-token>" http://127.0.0.1:5147/api/remote/devices/<device-id>/thumbnail/request
+curl -H "X-Bridge-Token: <bridge-token>" http://127.0.0.1:5147/api/remote/devices/<device-id>/thumbnail
+```
+
 ?먮뒗 ?꾩뿭 ?ㅼ튂 ???ㅽ뻾?⑸땲??
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindexec/cli",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "MindExec local runtime and bridge CLI",
   "main": "server.js",
   "type": "module",
@@ -8,8 +8,9 @@
     "start-bridge.bat",
     "start-bridge.sh",
     "launch-bridge.cjs",
-    "server.js",
-    "codex-runtime.js",
+    "server.js",
+    "remote-hub.js",
+    "codex-runtime.js",
     "port-guard.cjs",
     "wwwroot/",
     "scripts/",
@@ -19,7 +20,8 @@
   "scripts": {
     "start": "node launch-bridge.cjs",
     "dev": "node launch-bridge.cjs --watch",
-    "test:syntax": "node --check server.js && node --check codex-runtime.js && node --check launch-bridge.cjs && node --check port-guard.cjs && node --check scripts/setup-tree-sitter-grammars.mjs",
+    "test:syntax": "node --check server.js && node --check remote-hub.js && node --check codex-runtime.js && node --check launch-bridge.cjs && node --check port-guard.cjs && node --check scripts/setup-tree-sitter-grammars.mjs && node --check scripts/remote-hub-smoke.mjs",
+    "test:remote": "node scripts/remote-hub-smoke.mjs",
     "pack:dry": "npm pack --dry-run",
     "setup:grammars": "node scripts/setup-tree-sitter-grammars.mjs",
     "postinstall": "npm run setup:grammars"

package/remote-hub.js

@@ -0,0 +1,571 @@
+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 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 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,
+        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,
+            counters: {
+                messagesReceived: 1,
+                statusReceived: 0,
+                commandsSent: 0,
+                commandResultsReceived: 0,
+                thumbnailFramesReceived: 0,
+                thumbnailFramesDropped: 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 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;
+                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 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,
+        requestThumbnail,
+        getDeviceThumbnail,
+        getPairToken: () => pairToken
+    };
+}
+
+export function getDefaultRemoteAgentDeviceInfo() {
+    return {
+        hostname: os.hostname(),
+        platform: os.platform(),
+        arch: os.arch(),
+        pid: process.pid
+    };
+}