@mindexec/cli 0.2.5 → 0.2.7

package/README.md

@@ -83,6 +83,18 @@ curl -X POST -H "X-Bridge-Token: <bridge-token>" http://127.0.0.1:5147/api/remot
 curl -H "X-Bridge-Token: <bridge-token>" http://127.0.0.1:5147/api/remote/devices/<device-id>/thumbnail
 ```
 
+Start, read, and stop the focused view-only RemoteFast live stream:
+
+```bash
+curl -X POST -H "X-Bridge-Token: <bridge-token>" -H "Content-Type: application/json" \
+  -d "{\"fps\":12,\"maxWidth\":960,\"maxHeight\":540,\"quality\":60}" \
+  http://127.0.0.1:5147/api/remote/devices/<device-id>/live/start
+
+curl -H "X-Bridge-Token: <bridge-token>" http://127.0.0.1:5147/api/remote/devices/<device-id>/live/frame
+
+curl -X POST -H "X-Bridge-Token: <bridge-token>" http://127.0.0.1:5147/api/remote/devices/<device-id>/live/stop
+```
+
 Queue a safe task-only instruction for one device or all connected devices:
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindexec/cli",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "MindExec local runtime and bridge CLI",
   "main": "server.js",
   "type": "module",
@@ -8,9 +8,9 @@
     "start-bridge.bat",
     "start-bridge.sh",
     "launch-bridge.cjs",
-    "server.js",
-    "remote-hub.js",
-    "codex-runtime.js",
+    "server.js",
+    "remote-hub.js",
+    "codex-runtime.js",
     "port-guard.cjs",
     "wwwroot/",
     "scripts/",
@@ -20,8 +20,8 @@
   "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/remote-hub-smoke.mjs",
-    "test:remote": "node scripts/remote-hub-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/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

@@ -7,6 +7,7 @@ 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_STREAM_BASE64_CHARS = 3 * 1024 * 1024;
 const MAX_AGENT_TASK_CHARS = 4000;
 const MAX_AGENT_TASK_RESULT_CHARS = 3000;
 const RECENT_TASK_LIMIT = 12;
@@ -118,6 +119,8 @@ function serializeDevice(device) {
         remoteAddress: device.remoteAddress,
         remotePort: device.remotePort,
         latestThumbnail: device.latestThumbnail ? { ...device.latestThumbnail } : null,
+        latestLiveFrame: device.latestLiveFrame ? { ...device.latestLiveFrame } : null,
+        activeLiveStream: device.activeLiveStream ? { ...device.activeLiveStream } : null,
         latestTask: device.latestTask ? { ...device.latestTask } : null,
         recentTasks: Array.isArray(device.recentTasks)
             ? device.recentTasks.map(task => ({ ...task }))
@@ -249,6 +252,8 @@ export function createRemoteHub(options = {}) {
             remotePort: socket.remotePort || 0,
             status: {},
             latestThumbnail: null,
+            latestLiveFrame: null,
+            activeLiveStream: null,
             latestTask: null,
             recentTasks: [],
             pendingTaskCommands: new Map(),
@@ -259,6 +264,10 @@ export function createRemoteHub(options = {}) {
                 commandResultsReceived: 0,
                 thumbnailFramesReceived: 0,
                 thumbnailFramesDropped: 0,
+                liveFramesReceived: 0,
+                liveFramesDropped: 0,
+                liveStreamsStarted: 0,
+                liveStreamsStopped: 0,
                 tasksQueued: 0,
                 taskResultsReceived: 0,
                 taskResultsFailed: 0
@@ -297,6 +306,11 @@ export function createRemoteHub(options = {}) {
         device.socket = null;
         device.disconnectedAt = new Date().toISOString();
         device.lastDisconnectReason = reason;
+        if (device.activeLiveStream) {
+            device.activeLiveStream.active = false;
+            device.activeLiveStream.stoppedAt = device.disconnectedAt;
+            device.activeLiveStream.stopReason = reason;
+        }
         logWarn('remote', `device disconnected ${device.deviceName} (${deviceId}): ${reason}`);
         emitRemoteEvent('RemoteDeviceDisconnected', device, { reason });
     }
@@ -475,6 +489,62 @@ export function createRemoteHub(options = {}) {
                 });
                 break;
             }
+            case 'stream.frame': {
+                const frameData = safeString(message.data, MAX_STREAM_BASE64_CHARS + 1);
+                const frameSeq = Number(message.frameSeq);
+                const streamId = safeString(message.streamId, 128) || 'live';
+                if (!device.activeLiveStream?.active || device.activeLiveStream.streamId !== streamId) {
+                    device.counters.liveFramesDropped += 1;
+                    emitRemoteEvent('RemoteFrameDropped', device, {
+                        reason: 'stale-live-stream-frame',
+                        streamId,
+                        frameSeq: Number.isFinite(frameSeq) ? frameSeq : null
+                    });
+                    break;
+                }
+
+                if (!frameData || frameData.length > MAX_STREAM_BASE64_CHARS || !Number.isFinite(frameSeq)) {
+                    device.counters.liveFramesDropped += 1;
+                    emitRemoteEvent('RemoteFrameDropped', device, {
+                        reason: 'invalid-live-frame',
+                        streamId,
+                        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.latestLiveFrame = {
+                    streamId,
+                    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,
+                    mode: safeString(message.mode || device.activeLiveStream.mode || 'remote-fast', 80),
+                    fps: Number.isFinite(Number(message.fps)) ? Number(message.fps) : device.activeLiveStream.fps,
+                    capturedAt,
+                    receivedAt: device.lastSeenAt,
+                    byteLength: Math.floor(frameData.length * 3 / 4),
+                    dataUrl: frameData.startsWith('data:')
+                        ? frameData
+                        : `data:${mimeType};base64,${frameData}`
+                };
+                device.activeLiveStream.lastFrameAt = device.lastSeenAt;
+                device.activeLiveStream.lastFrameSeq = frameSeq;
+                device.activeLiveStream.framesReceived = (device.activeLiveStream.framesReceived || 0) + 1;
+                device.counters.liveFramesReceived += 1;
+                emitRemoteEvent('RemoteFrameReceived', device, {
+                    streamId,
+                    frameSeq,
+                    width: device.latestLiveFrame.width,
+                    height: device.latestLiveFrame.height,
+                    mode: device.latestLiveFrame.mode
+                });
+                break;
+            }
             default:
                 emitRemoteEvent('RemoteAgentMessageIgnored', device, {
                     messageType: safeString(message.type, 80)
@@ -731,6 +801,100 @@ export function createRemoteHub(options = {}) {
         });
     }
 
+    function startLiveStream(deviceId, options = {}) {
+        const device = devices.get(String(deviceId || ''));
+        if (!device?.socket || device.socket.destroyed || !device.connected) {
+            return { ok: false, error: 'device-not-connected' };
+        }
+        if (!readCapabilityFlag(device.capabilities, 'liveStream')) {
+            return { ok: false, error: 'device-live-stream-unavailable' };
+        }
+
+        const now = new Date().toISOString();
+        const streamId = safeString(options.streamId, 128) || `live-${Date.now()}`;
+        const fps = clampNumber(options.fps, 1, 24, 12);
+        const commandId = safeString(options.commandId, 128) || crypto.randomUUID();
+        const result = sendCommand(deviceId, {
+            command: 'stream.start',
+            commandId,
+            payload: {
+                streamId,
+                mode: safeString(options.mode, 80) || 'remote-fast',
+                fps,
+                maxWidth: clampNumber(options.maxWidth, 320, 2560, 960),
+                maxHeight: clampNumber(options.maxHeight, 180, 1440, 540),
+                quality: clampNumber(options.quality, 20, 95, 60),
+                requestedAt: now
+            }
+        });
+
+        if (!result.ok) {
+            return result;
+        }
+
+        device.activeLiveStream = {
+            streamId,
+            commandId,
+            active: true,
+            mode: 'remote-fast',
+            fps,
+            startedAt: now,
+            stoppedAt: '',
+            stopReason: '',
+            lastFrameAt: '',
+            lastFrameSeq: 0,
+            framesReceived: 0
+        };
+        device.counters.liveStreamsStarted += 1;
+        emitRemoteEvent('RemoteLiveStreamStarted', device, {
+            streamId,
+            commandId,
+            fps
+        });
+
+        return { ok: true, commandId, streamId, fps };
+    }
+
+    function stopLiveStream(deviceId, options = {}) {
+        const device = devices.get(String(deviceId || ''));
+        if (!device?.socket || device.socket.destroyed || !device.connected) {
+            return { ok: false, error: 'device-not-connected' };
+        }
+
+        const streamId = safeString(options.streamId, 128) || device.activeLiveStream?.streamId || '';
+        const commandId = safeString(options.commandId, 128) || crypto.randomUUID();
+        const result = sendCommand(deviceId, {
+            command: 'stream.stop',
+            commandId,
+            payload: {
+                streamId,
+                requestedAt: new Date().toISOString()
+            }
+        });
+
+        if (!result.ok) {
+            return result;
+        }
+
+        if (device.activeLiveStream && (!streamId || device.activeLiveStream.streamId === streamId)) {
+            device.activeLiveStream.active = false;
+            device.activeLiveStream.stoppedAt = new Date().toISOString();
+            device.activeLiveStream.stopReason = 'manager-request';
+        }
+        device.counters.liveStreamsStopped += 1;
+        emitRemoteEvent('RemoteLiveStreamStopped', device, {
+            streamId,
+            commandId
+        });
+
+        return { ok: true, commandId, streamId };
+    }
+
+    function getDeviceLiveFrame(deviceId) {
+        const device = devices.get(String(deviceId || ''));
+        return device?.latestLiveFrame ? { ...device.latestLiveFrame } : null;
+    }
+
     function getDeviceThumbnail(deviceId) {
         const device = devices.get(String(deviceId || ''));
         return device?.latestThumbnail ? { ...device.latestThumbnail } : null;
@@ -745,6 +909,9 @@ export function createRemoteHub(options = {}) {
         sendCommand,
         requestAgentTask,
         requestThumbnail,
+        startLiveStream,
+        stopLiveStream,
+        getDeviceLiveFrame,
         getDeviceThumbnail,
         getPairToken: () => pairToken
     };

package/scripts/remote-hub-smoke.mjs

@@ -61,6 +61,7 @@ try {
             status: true,
             thumbnail: false,
             control: false,
+            liveStream: true,
             computerAgent: true,
             taskDispatch: true,
             aiAssist: true,
@@ -112,6 +113,59 @@ try {
     assert.equal(thumbnailDevice.latestThumbnail.streamId, 'smoke-thumb');
     assert.equal(thumbnailDevice.counters.thumbnailFramesReceived, 1);
 
+    const liveCommand = hub.startLiveStream('smoke-device', {
+        streamId: 'smoke-live',
+        fps: 5,
+        maxWidth: 320,
+        maxHeight: 180,
+        quality: 50
+    });
+    assert.equal(liveCommand.ok, true);
+    writeJsonLine(socket, {
+        type: 'stream.frame',
+        commandId: liveCommand.commandId,
+        streamId: 'smoke-live',
+        frameSeq: 2,
+        width: 2,
+        height: 1,
+        mimeType: 'image/png',
+        mode: 'remote-fast',
+        fps: 5,
+        capturedAt: new Date().toISOString(),
+        data: 'iVBORw0KGgoAAAANSUhEUgAAAAIAAAABCAYAAAD0In+KAAAADElEQVR42mP8z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC'
+    });
+
+    const liveDevice = await waitFor(() => {
+        const current = hub.listDevices();
+        return current[0]?.latestLiveFrame?.streamId === 'smoke-live' ? current[0] : null;
+    });
+    assert.equal(liveDevice.activeLiveStream.active, true);
+    assert.equal(liveDevice.latestLiveFrame.mode, 'remote-fast');
+    assert.equal(liveDevice.counters.liveFramesReceived, 1);
+
+    const staleFrameBefore = liveDevice.counters.liveFramesDropped;
+    writeJsonLine(socket, {
+        type: 'stream.frame',
+        streamId: 'stale-live',
+        frameSeq: 3,
+        width: 2,
+        height: 1,
+        mimeType: 'image/png',
+        capturedAt: new Date().toISOString(),
+        data: 'iVBORw0KGgoAAAANSUhEUgAAAAIAAAABCAYAAAD0In+KAAAADElEQVR42mP8z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC'
+    });
+    const staleDropDevice = await waitFor(() => {
+        const current = hub.listDevices();
+        return current[0]?.counters?.liveFramesDropped > staleFrameBefore ? current[0] : null;
+    });
+    assert.equal(staleDropDevice.latestLiveFrame.streamId, 'smoke-live');
+
+    const stopLiveCommand = hub.stopLiveStream('smoke-device', {
+        streamId: 'smoke-live'
+    });
+    assert.equal(stopLiveCommand.ok, true);
+    assert.equal(hub.listDevices()[0].activeLiveStream.active, false);
+
     const taskCommand = hub.requestAgentTask('smoke-device', {
         instruction: 'Summarize current desktop status for the manager.',
         title: 'Smoke task'

package/server.js

@@ -7048,6 +7048,34 @@ app.post('/api/remote/devices/:deviceId/thumbnail/request', (req, res) => {
     }));
 });
 
+app.get('/api/remote/devices/:deviceId/live/frame', (req, res) => {
+    res.setHeader('Cache-Control', 'no-store');
+    const frame = remoteHub.getDeviceLiveFrame(req.params.deviceId);
+    if (!frame) {
+        res.status(404).json({ ok: false, error: 'live-frame-not-available' });
+        return;
+    }
+
+    res.json({ ok: true, frame });
+});
+
+app.post('/api/remote/devices/:deviceId/live/start', (req, res) => {
+    res.json(remoteHub.startLiveStream(req.params.deviceId, {
+        streamId: req.body?.streamId,
+        mode: req.body?.mode,
+        fps: req.body?.fps,
+        maxWidth: req.body?.maxWidth,
+        maxHeight: req.body?.maxHeight,
+        quality: req.body?.quality
+    }));
+});
+
+app.post('/api/remote/devices/:deviceId/live/stop', (req, res) => {
+    res.json(remoteHub.stopLiveStream(req.params.deviceId, {
+        streamId: req.body?.streamId
+    }));
+});
+
 app.get('/api/codex/capabilities', async (req, res) => {
     try {
         res.json(await getCodexRuntime().getCapabilities());