@mindexec/cli 0.2.116 → 0.2.117

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindexec/cli",
-  "version": "0.2.116",
+  "version": "0.2.117",
   "description": "MindExec local runtime and bridge CLI",
   "main": "server.js",
   "type": "module",
@@ -20,7 +20,7 @@
   "scripts": {
     "start": "node launch-bridge.cjs",
     "dev": "node launch-bridge.cjs --watch",
-    "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/auth-session-smoke.mjs && node --check scripts/remote-hub-smoke.mjs && node --check scripts/remote-hub-scale-smoke.mjs && node --check scripts/remote-fleet-render-smoke.mjs && node --check scripts/remote-http-smoke.mjs && node --check scripts/remote-frame-ws-smoke.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/auth-session-smoke.mjs && node --check scripts/remote-hub-smoke.mjs && node --check scripts/remote-hub-scale-smoke.mjs && node --check scripts/remote-fleet-render-smoke.mjs && node --check scripts/remote-http-smoke.mjs && node --check scripts/remote-frame-ws-smoke.mjs && node --check scripts/remote-agent-ws-smoke.mjs",
     "test:auth": "node scripts/auth-session-smoke.mjs",
     "test:remote": "node scripts/remote-hub-smoke.mjs",
     "test:remote:scale": "node scripts/remote-hub-scale-smoke.mjs",
@@ -47,7 +47,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@mindexec/remote": "^0.1.16",
+    "@mindexec/remote": "^0.1.17",
     "@openai/codex-sdk": "^0.137.0",
     "chokidar": "^3.6.0",
     "cors": "^2.8.5",

package/remote-hub.js

@@ -592,10 +592,266 @@ function writeJsonLine(socket, payload) {
         return false;
     }
 
+    if (socket.__remoteHubWebSocket === true && typeof socket.sendJson === 'function') {
+        return socket.sendJson(payload);
+    }
+
     socket.write(`${JSON.stringify(payload)}\n`);
     return true;
 }
 
+function isRemoteHubWebSocketUpgradeStart(buffer) {
+    if (!Buffer.isBuffer(buffer) || buffer.length < 4) {
+        return false;
+    }
+
+    return buffer.subarray(0, Math.min(buffer.length, 16)).toString('latin1').startsWith('GET ');
+}
+
+function parseRemoteHubWebSocketUpgrade(buffer) {
+    const headerEnd = buffer.indexOf('\r\n\r\n');
+    if (headerEnd < 0) {
+        return null;
+    }
+
+    const headerText = buffer.subarray(0, headerEnd).toString('latin1');
+    const lines = headerText.split('\r\n');
+    const requestLine = lines.shift() || '';
+    const [method, path] = requestLine.split(/\s+/);
+    const headers = {};
+    for (const line of lines) {
+        const separator = line.indexOf(':');
+        if (separator <= 0) {
+            continue;
+        }
+
+        headers[line.slice(0, separator).trim().toLowerCase()] = line.slice(separator + 1).trim();
+    }
+
+    return {
+        method,
+        path,
+        headers,
+        head: buffer.subarray(headerEnd + 4)
+    };
+}
+
+function buildRemoteHubWebSocketAcceptKey(key) {
+    return crypto
+        .createHash('sha1')
+        .update(`${key}258EAFA5-E914-47DA-95CA-C5AB0DC85B11`)
+        .digest('base64');
+}
+
+function buildRemoteHubWebSocketFrame(opcode, payload) {
+    const body = Buffer.isBuffer(payload) ? payload : Buffer.from(String(payload || ''), 'utf8');
+    let header = null;
+    if (body.length < 126) {
+        header = Buffer.allocUnsafe(2);
+        header[0] = 0x80 | opcode;
+        header[1] = body.length;
+    } else if (body.length <= 0xffff) {
+        header = Buffer.allocUnsafe(4);
+        header[0] = 0x80 | opcode;
+        header[1] = 126;
+        header.writeUInt16BE(body.length, 2);
+    } else {
+        header = Buffer.allocUnsafe(10);
+        header[0] = 0x80 | opcode;
+        header[1] = 127;
+        header.writeBigUInt64BE(BigInt(body.length), 2);
+    }
+
+    return Buffer.concat([header, body], header.length + body.length);
+}
+
+function parseRemoteHubWebSocketBinaryFrame(buffer) {
+    if (!Buffer.isBuffer(buffer) || buffer.length < 5) {
+        return null;
+    }
+
+    const metaLength = buffer.readUInt32BE(0);
+    if (!Number.isFinite(metaLength)
+        || metaLength <= 0
+        || metaLength > 64 * 1024
+        || 4 + metaLength >= buffer.length) {
+        return null;
+    }
+
+    const header = JSON.parse(buffer.subarray(4, 4 + metaLength).toString('utf8'));
+    const payload = buffer.subarray(4 + metaLength);
+    return { header, payload };
+}
+
+class RemoteHubWebSocketAgentSocket {
+    constructor(socket) {
+        this.__remoteHubWebSocket = true;
+        this.socket = socket;
+        this.remoteAddress = socket.remoteAddress;
+        this.remotePort = socket.remotePort;
+        this.destroyed = false;
+        this.buffer = Buffer.alloc(0);
+        this.fragmentOpcode = 0;
+        this.fragments = [];
+        this.onTextMessage = () => {};
+        this.onBinaryMessage = () => {};
+        this.onCloseMessage = () => {};
+    }
+
+    setNoDelay() {}
+
+    setKeepAlive() {}
+
+    sendJson(payload) {
+        return this.sendText(JSON.stringify(payload));
+    }
+
+    write(payload) {
+        if (this.destroyed) {
+            return false;
+        }
+
+        const text = (Buffer.isBuffer(payload) ? payload.toString('utf8') : String(payload || '')).replace(/\n$/, '');
+        return this.sendText(text);
+    }
+
+    sendText(text) {
+        return this.sendFrame(0x1, Buffer.from(String(text || ''), 'utf8'));
+    }
+
+    sendFrame(opcode, payload) {
+        if (this.destroyed || this.socket.destroyed) {
+            return false;
+        }
+
+        try {
+            this.socket.write(buildRemoteHubWebSocketFrame(opcode, payload));
+            return true;
+        } catch {
+            this.destroy();
+            return false;
+        }
+    }
+
+    destroy() {
+        if (this.destroyed) {
+            return;
+        }
+
+        this.destroyed = true;
+        try {
+            if (!this.socket.destroyed) {
+                this.socket.write(buildRemoteHubWebSocketFrame(0x8, Buffer.alloc(0)));
+            }
+        } catch {
+            // Ignore close-frame failures.
+        }
+        try {
+            this.socket.destroy();
+        } catch {
+            // Ignore socket destroy failures.
+        }
+    }
+
+    handleData(chunk) {
+        if (this.destroyed) {
+            return;
+        }
+
+        this.buffer = this.buffer.length > 0
+            ? Buffer.concat([this.buffer, chunk])
+            : chunk;
+
+        while (!this.destroyed) {
+            if (this.buffer.length < 2) {
+                return;
+            }
+
+            const first = this.buffer[0];
+            const second = this.buffer[1];
+            const fin = (first & 0x80) !== 0;
+            const opcode = first & 0x0f;
+            const masked = (second & 0x80) !== 0;
+            let payloadLength = second & 0x7f;
+            let offset = 2;
+
+            if (payloadLength === 126) {
+                if (this.buffer.length < offset + 2) return;
+                payloadLength = this.buffer.readUInt16BE(offset);
+                offset += 2;
+            } else if (payloadLength === 127) {
+                if (this.buffer.length < offset + 8) return;
+                const bigLength = this.buffer.readBigUInt64BE(offset);
+                if (bigLength > BigInt(Number.MAX_SAFE_INTEGER)) {
+                    this.destroy();
+                    return;
+                }
+                payloadLength = Number(bigLength);
+                offset += 8;
+            }
+
+            if (!masked) {
+                this.destroy();
+                return;
+            }
+
+            if (this.buffer.length < offset + 4 + payloadLength) {
+                return;
+            }
+
+            const mask = this.buffer.subarray(offset, offset + 4);
+            offset += 4;
+            const payload = Buffer.from(this.buffer.subarray(offset, offset + payloadLength));
+            this.buffer = this.buffer.subarray(offset + payloadLength);
+            for (let index = 0; index < payload.length; index += 1) {
+                payload[index] ^= mask[index & 3];
+            }
+
+            if (opcode === 0x8) {
+                this.destroyed = true;
+                this.onCloseMessage('websocket-close');
+                try {
+                    this.socket.destroy();
+                } catch {
+                    // Ignore socket destroy failures.
+                }
+                return;
+            }
+
+            if (opcode === 0x9) {
+                this.sendFrame(0xA, payload);
+                continue;
+            }
+
+            if (opcode === 0xA) {
+                continue;
+            }
+
+            let messageOpcode = opcode;
+            let messagePayload = payload;
+            if (!fin) {
+                this.fragmentOpcode = opcode;
+                this.fragments = [payload];
+                continue;
+            }
+
+            if (opcode === 0x0) {
+                this.fragments.push(payload);
+                messageOpcode = this.fragmentOpcode;
+                messagePayload = Buffer.concat(this.fragments);
+                this.fragmentOpcode = 0;
+                this.fragments = [];
+            }
+
+            if (messageOpcode === 0x1) {
+                this.onTextMessage(messagePayload.toString('utf8'));
+            } else if (messageOpcode === 0x2) {
+                this.onBinaryMessage(messagePayload);
+            }
+        }
+    }
+}
+
 export function createRemoteHub(options = {}) {
     const env = options.env || process.env;
     const logEvent = options.logEvent || (() => {});
@@ -1921,7 +2177,146 @@ export function createRemoteHub(options = {}) {
         }
     }
 
-    function handleSocket(socket) {
+    function handleWebSocketAgentSocket(socket) {
+        allSockets.add(socket);
+        socket.setNoDelay(true);
+        socket.setKeepAlive(true, heartbeatMs);
+
+        const state = {
+            authenticated: false,
+            device: null
+        };
+
+        const helloTimer = setTimeout(() => {
+            if (!state.authenticated) {
+                writeJsonLine(socket, { type: 'error', error: 'hello-timeout' });
+                socket.destroy();
+            }
+        }, 10000);
+
+        socket.onTextMessage = text => {
+            try {
+                handleAgentMessage(socket, state, parseJsonLine(String(text || '')));
+            } catch (err) {
+                writeJsonLine(socket, { type: 'error', error: 'invalid-json' });
+                logWarn('remote', `invalid websocket agent message: ${err?.message || err}`);
+            }
+        };
+
+        socket.onBinaryMessage = payload => {
+            try {
+                const packet = parseRemoteHubWebSocketBinaryFrame(payload);
+                if (!packet?.header || !Buffer.isBuffer(packet.payload)) {
+                    writeJsonLine(socket, { type: 'error', error: 'invalid-websocket-binary-frame' });
+                    return;
+                }
+
+                const frameKind = safeString(packet.header.frameKind || packet.header.kind || packet.header.frameType, 40).toLowerCase();
+                const maxBytes = frameKind === 'thumbnail'
+                    ? MAX_THUMBNAIL_BINARY_BYTES
+                    : MAX_STREAM_BINARY_BYTES;
+                const byteLength = Number(packet.header.byteLength ?? packet.header.payloadBytes ?? packet.payload.length);
+                if (!Number.isFinite(byteLength)
+                    || byteLength < 1
+                    || byteLength > maxBytes
+                    || byteLength !== packet.payload.length) {
+                    writeJsonLine(socket, { type: 'error', error: 'invalid-binary-frame' });
+                    logWarn('remote', 'invalid websocket binary frame from agent.');
+                    return;
+                }
+
+                handleAgentBinaryFrame(socket, state, packet.header, packet.payload);
+            } catch (err) {
+                writeJsonLine(socket, { type: 'error', error: 'invalid-websocket-binary-frame' });
+                logWarn('remote', `invalid websocket binary frame: ${err?.message || err}`);
+            }
+        };
+
+        const detach = reason => {
+            allSockets.delete(socket);
+            clearTimeout(helloTimer);
+            detachSocket(socket, reason);
+        };
+
+        socket.onCloseMessage = reason => detach(reason || 'websocket-closed');
+        socket.socket.on('close', () => detach('websocket-closed'));
+        socket.socket.on('error', err => detach(err?.message || 'websocket-error'));
+    }
+
+    function handleWebSocketUpgradeSocket(socket, firstChunk) {
+        let upgradeBuffer = Buffer.isBuffer(firstChunk) ? firstChunk : Buffer.from(firstChunk);
+        let onUpgradeData = null;
+        const fail = (status, message) => {
+            try {
+                socket.write(`HTTP/1.1 ${status} ${message}\r\nConnection: close\r\n\r\n`);
+            } catch {
+                // Ignore write failures while rejecting the upgrade.
+            }
+            socket.destroy();
+        };
+
+        const completeUpgrade = () => {
+            const request = parseRemoteHubWebSocketUpgrade(upgradeBuffer);
+            if (!request) {
+                return false;
+            }
+
+            const upgrade = String(request.headers.upgrade || '').toLowerCase();
+            const connection = String(request.headers.connection || '').toLowerCase();
+            const key = safeString(request.headers['sec-websocket-key'], 256);
+            const pathName = safeString(String(request.path || '').split('?')[0], 128) || '/';
+            const allowedPath = pathName === '/'
+                || pathName === '/remote-agent'
+                || pathName === '/api/remote/agent/ws';
+            if (request.method !== 'GET'
+                || upgrade !== 'websocket'
+                || !connection.includes('upgrade')
+                || !key
+                || !allowedPath) {
+                fail(400, 'Bad Request');
+                return true;
+            }
+
+            const acceptKey = buildRemoteHubWebSocketAcceptKey(key);
+            socket.write([
+                'HTTP/1.1 101 Switching Protocols',
+                'Upgrade: websocket',
+                'Connection: Upgrade',
+                `Sec-WebSocket-Accept: ${acceptKey}`,
+                '\r\n'
+            ].join('\r\n'));
+
+            if (onUpgradeData) {
+                socket.removeListener('data', onUpgradeData);
+            }
+            const wsSocket = new RemoteHubWebSocketAgentSocket(socket);
+            const onFrameData = chunk => wsSocket.handleData(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+            socket.on('data', onFrameData);
+            socket.once('close', () => {
+                socket.removeListener('data', onFrameData);
+            });
+            handleWebSocketAgentSocket(wsSocket);
+            if (request.head.length > 0) {
+                wsSocket.handleData(request.head);
+            }
+            return true;
+        };
+
+        onUpgradeData = chunk => {
+            upgradeBuffer = Buffer.concat([upgradeBuffer, Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)]);
+            if (upgradeBuffer.length > 16 * 1024) {
+                fail(431, 'Request Header Fields Too Large');
+                return;
+            }
+            completeUpgrade();
+        };
+
+        if (!completeUpgrade()) {
+            socket.on('data', onUpgradeData);
+        }
+    }
+
+    function handleTcpAgentSocket(socket, firstChunk = null) {
         allSockets.add(socket);
         socket.setNoDelay(true);
         socket.setKeepAlive(true, heartbeatMs);
@@ -1940,7 +2335,7 @@ export function createRemoteHub(options = {}) {
             }
         }, 10000);
 
-        socket.on('data', chunk => {
+        const processData = chunk => {
             const incoming = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
             state.buffer = state.buffer.length > 0
                 ? Buffer.concat([state.buffer, incoming])
@@ -1999,7 +2394,12 @@ export function createRemoteHub(options = {}) {
                     logWarn('remote', `invalid agent message: ${err?.message || err}`);
                 }
             }
-        });
+        };
+
+        socket.on('data', processData);
+        if (firstChunk) {
+            processData(firstChunk);
+        }
 
         socket.on('close', () => {
             allSockets.delete(socket);
@@ -2013,6 +2413,22 @@ export function createRemoteHub(options = {}) {
         });
     }
 
+    function handleSocket(socket) {
+        socket.once('data', chunk => {
+            const firstChunk = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            if (isRemoteHubWebSocketUpgradeStart(firstChunk)) {
+                handleWebSocketUpgradeSocket(socket, firstChunk);
+                return;
+            }
+
+            handleTcpAgentSocket(socket, firstChunk);
+        });
+
+        socket.once('error', () => {
+            // The transport-specific handler owns logging after the first byte.
+        });
+    }
+
     async function start() {
         if (!enabled || started) {
             return getStatus({ includeSecrets: false });

package/scripts/remote-agent-ws-smoke.mjs

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+
+import assert from 'node:assert/strict';
+import { WebSocket } from 'ws';
+import { createRemoteHub } from '../remote-hub.js';
+
+const PAIR_TOKEN = 'remote-agent-ws-smoke-token';
+const DEVICE_ID = 'remote-agent-ws-smoke-device';
+const SMOKE_PNG = Buffer.from(
+    'iVBORw0KGgoAAAANSUhEUgAAAAIAAAABCAYAAAD0In+KAAAADElEQVR42mP8z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC',
+    'base64');
+
+function wait(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+async function waitFor(predicate, timeoutMs = 5000, label = 'condition') {
+    const startedAt = Date.now();
+    while (Date.now() - startedAt < timeoutMs) {
+        const value = predicate();
+        if (value) {
+            return value;
+        }
+        await wait(25);
+    }
+
+    throw new Error(`Timed out waiting for ${label}.`);
+}
+
+function writeAgentBinaryFrame(ws, header, payload) {
+    const framePayload = Buffer.isBuffer(payload) ? payload : Buffer.from(payload);
+    const metadata = Buffer.from(JSON.stringify({
+        ...header,
+        type: 'frame.binary',
+        byteLength: framePayload.length
+    }), 'utf8');
+    const packet = Buffer.allocUnsafe(4 + metadata.length + framePayload.length);
+    packet.writeUInt32BE(metadata.length, 0);
+    metadata.copy(packet, 4);
+    framePayload.copy(packet, 4 + metadata.length);
+    ws.send(packet);
+}
+
+const hub = createRemoteHub({
+    env: {
+        MINDEXEC_REMOTE_HUB: '1',
+        REMOTE_HUB_HOST: '127.0.0.1',
+        REMOTE_HUB_PORT: '0',
+        REMOTE_HUB_PAIR_TOKEN: PAIR_TOKEN
+    }
+});
+
+let ws = null;
+
+try {
+    await hub.start();
+    const status = hub.getStatus({ includeSecrets: true });
+    assert.equal(status.started, true);
+
+    ws = new WebSocket(`ws://127.0.0.1:${status.port}/remote-agent`);
+    const received = [];
+    ws.on('message', data => {
+        if (typeof data !== 'string' && !Buffer.isBuffer(data)) {
+            return;
+        }
+
+        const text = Buffer.isBuffer(data) ? data.toString('utf8') : data;
+        if (!text.trim().startsWith('{')) {
+            return;
+        }
+
+        received.push(JSON.parse(text));
+    });
+
+    await new Promise((resolve, reject) => {
+        ws.once('open', resolve);
+        ws.once('error', reject);
+    });
+
+    ws.send(JSON.stringify({
+        type: 'hello',
+        pairToken: PAIR_TOKEN,
+        deviceId: DEVICE_ID,
+        deviceName: 'Remote Agent WS Smoke',
+        hostname: 'remote-agent-ws-smoke',
+        platform: process.platform,
+        arch: process.arch,
+        pid: process.pid,
+        agentVersion: '0.0.0-ws-smoke',
+        runtime: 'node-smoke',
+        capabilities: {
+            status: true,
+            thumbnail: true,
+            liveStream: true,
+            binaryFrames: true,
+            control: true,
+            computerAgent: true,
+            taskDispatch: true,
+            aiAssist: false
+        }
+    }));
+    ws.send(JSON.stringify({
+        type: 'status',
+        status: {
+            uptimeSec: 1,
+            totalMem: 2,
+            freeMem: 1,
+            timestamp: new Date().toISOString()
+        }
+    }));
+
+    await waitFor(() => received.find(item => item.type === 'welcome'), 5000, 'welcome');
+    const device = await waitFor(() => {
+        const current = hub.listDevices();
+        return current.length === 1 && current[0].deviceId === DEVICE_ID ? current[0] : null;
+    }, 5000, 'device registration');
+    assert.equal(device.connected, true);
+    assert.equal(device.capabilities.binaryFrames, true);
+
+    const inputCommand = hub.sendInputControl(DEVICE_ID, { type: 'noop' });
+    assert.equal(inputCommand.ok, true);
+    const inputMessage = await waitFor(
+        () => received.find(item => item.commandId === inputCommand.commandId),
+        5000,
+        'input command');
+    assert.equal(inputMessage.command, 'input.control');
+    ws.send(JSON.stringify({
+        type: 'command.result',
+        commandId: inputCommand.commandId,
+        result: {
+            input: true,
+            handled: true
+        }
+    }));
+    await waitFor(() => hub.listDevices()[0]?.counters?.commandResultsReceived === 1, 5000, 'input result');
+
+    const thumbnailCommand = hub.requestThumbnail(DEVICE_ID, {
+        streamId: 'remote-agent-ws-thumb',
+        maxWidth: 320,
+        maxHeight: 180,
+        quality: 50
+    });
+    assert.equal(thumbnailCommand.ok, true);
+    await waitFor(
+        () => received.find(item => item.commandId === thumbnailCommand.commandId),
+        5000,
+        'thumbnail command');
+    writeAgentBinaryFrame(ws, {
+        frameKind: 'thumbnail',
+        commandId: thumbnailCommand.commandId,
+        streamId: 'remote-agent-ws-thumb',
+        frameSeq: 11,
+        width: 2,
+        height: 1,
+        mimeType: 'image/png',
+        capturedAt: new Date().toISOString()
+    }, SMOKE_PNG);
+    const thumbnailDevice = await waitFor(() => {
+        const current = hub.listDevices()[0];
+        return current?.latestThumbnail?.frameSeq === 11 ? current : null;
+    }, 5000, 'websocket binary thumbnail');
+    assert.equal(thumbnailDevice.latestThumbnail.transport, 'binary');
+    assert.equal(thumbnailDevice.latestThumbnail.byteLength, SMOKE_PNG.length);
+
+    const liveCommand = hub.startLiveStream(DEVICE_ID, {
+        streamId: 'remote-agent-ws-live',
+        fps: 10,
+        maxWidth: 320,
+        maxHeight: 180,
+        quality: 50
+    });
+    assert.equal(liveCommand.ok, true);
+    await waitFor(
+        () => received.find(item => item.commandId === liveCommand.commandId),
+        5000,
+        'live command');
+    writeAgentBinaryFrame(ws, {
+        frameKind: 'stream',
+        commandId: liveCommand.commandId,
+        streamId: 'remote-agent-ws-live',
+        frameSeq: 12,
+        width: 2,
+        height: 1,
+        mimeType: 'image/png',
+        fps: 10,
+        capturedAt: new Date().toISOString()
+    }, SMOKE_PNG);
+    const liveDevice = await waitFor(() => {
+        const current = hub.listDevices()[0];
+        return current?.latestLiveFrame?.frameSeq === 12 ? current : null;
+    }, 5000, 'websocket binary live frame');
+    assert.equal(liveDevice.latestLiveFrame.transport, 'binary');
+    assert.equal(liveDevice.latestLiveFrame.streamId, 'remote-agent-ws-live');
+
+    ws.close();
+    console.log('RemoteAgent WebSocket smoke OK');
+} finally {
+    if (ws && ws.readyState === WebSocket.OPEN) {
+        ws.close();
+    }
+    await hub.close();
+}