@mindexec/cli 0.2.107 → 0.2.108

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindexec/cli",
-  "version": "0.2.107",
+  "version": "0.2.108",
   "description": "MindExec local runtime and bridge CLI",
   "main": "server.js",
   "type": "module",

package/remote-hub.js

@@ -15,6 +15,11 @@ const MAX_AGENT_TASK_CHARS = 4000;
 const MAX_AGENT_TASK_RESULT_CHARS = 3000;
 const RECENT_TASK_LIMIT = 12;
 const RECENT_TASK_BATCH_LIMIT = 16;
+const RECENT_FRAME_CACHE_TTL_MS = 5000;
+const RECENT_THUMBNAIL_FRAME_CACHE_LIMIT = 4;
+const RECENT_LIVE_FRAME_CACHE_LIMIT = 24;
+const RECENT_THUMBNAIL_FRAME_CACHE_MAX_BYTES = 3 * 1024 * 1024;
+const RECENT_LIVE_FRAME_CACHE_MAX_BYTES = 8 * 1024 * 1024;
 const REMOTE_PROTOCOL_VERSION = 1;
 const MAX_SYNTHETIC_DEVICES = 1000;
 const DEFAULT_HOST_TARGET_LEASE_MS = 30000;
@@ -374,6 +379,153 @@ function serializeRemoteFrame(frame, deviceId, frameKind, options = {}) {
     return serialized;
 }
 
+function getRecentFrameCache(device, frameKind) {
+    if (!device) {
+        return null;
+    }
+
+    if (!device.recentFramePayloads) {
+        device.recentFramePayloads = {
+            thumbnail: [],
+            live: []
+        };
+    }
+
+    const kind = frameKind === 'thumbnail' ? 'thumbnail' : 'live';
+    if (!Array.isArray(device.recentFramePayloads[kind])) {
+        device.recentFramePayloads[kind] = [];
+    }
+
+    return device.recentFramePayloads[kind];
+}
+
+function getRecentFrameCacheLimit(frameKind) {
+    return frameKind === 'thumbnail'
+        ? RECENT_THUMBNAIL_FRAME_CACHE_LIMIT
+        : RECENT_LIVE_FRAME_CACHE_LIMIT;
+}
+
+function getRecentFrameCacheMaxBytes(frameKind) {
+    return frameKind === 'thumbnail'
+        ? RECENT_THUMBNAIL_FRAME_CACHE_MAX_BYTES
+        : RECENT_LIVE_FRAME_CACHE_MAX_BYTES;
+}
+
+function pruneRecentFrameCache(cache, frameKind, nowMs = Date.now()) {
+    if (!Array.isArray(cache)) {
+        return;
+    }
+
+    const limit = getRecentFrameCacheLimit(frameKind);
+    const maxBytes = getRecentFrameCacheMaxBytes(frameKind);
+    let byteTotal = 0;
+    for (let index = cache.length - 1; index >= 0; index -= 1) {
+        const entry = cache[index];
+        const frame = entry?.frame;
+        if (!entry
+            || entry.expiresAt <= nowMs
+            || !frame
+            || !Buffer.isBuffer(frame.payload)
+            || !Number.isFinite(Number(frame.frameSeq))
+            || !safeString(frame.accessToken, 128)) {
+            cache.splice(index, 1);
+        }
+    }
+
+    for (let index = 0; index < cache.length; index += 1) {
+        const entry = cache[index];
+        const byteLength = Number(entry?.byteLength || entry?.frame?.payload?.length || 0) || 0;
+        byteTotal += byteLength;
+        if (index >= limit || byteTotal > maxBytes) {
+            cache.splice(index);
+            break;
+        }
+    }
+}
+
+function rememberRecentFramePayload(device, frameKind, frame) {
+    if (!device || !frame || !Buffer.isBuffer(frame.payload)) {
+        return;
+    }
+
+    const frameSeq = Number(frame.frameSeq);
+    const accessToken = safeString(frame.accessToken, 128);
+    if (!Number.isFinite(frameSeq) || !accessToken) {
+        return;
+    }
+
+    const kind = frameKind === 'thumbnail' ? 'thumbnail' : 'live';
+    const cache = getRecentFrameCache(device, kind);
+    if (!cache) {
+        return;
+    }
+
+    const nowMs = Date.now();
+    const normalizedSeq = Math.floor(frameSeq);
+    for (let index = cache.length - 1; index >= 0; index -= 1) {
+        const existing = cache[index]?.frame;
+        if (Number(existing?.frameSeq) === normalizedSeq
+            || safeString(existing?.accessToken, 128) === accessToken) {
+            cache.splice(index, 1);
+        }
+    }
+
+    cache.unshift({
+        frame,
+        byteLength: frame.payload.length,
+        cachedAt: nowMs,
+        expiresAt: nowMs + RECENT_FRAME_CACHE_TTL_MS
+    });
+    pruneRecentFrameCache(cache, kind, nowMs);
+}
+
+function isFramePayloadRequestMatch(frame, options = {}) {
+    if (!frame || !Buffer.isBuffer(frame.payload)) {
+        return false;
+    }
+
+    const requestedSeq = Number(options.frameSeq);
+    if (Number.isFinite(requestedSeq) && Math.floor(requestedSeq) !== Number(frame.frameSeq)) {
+        return false;
+    }
+
+    const token = safeString(options.token, 128);
+    if (token && !timingSafeStringEqual(token, frame.accessToken)) {
+        return false;
+    }
+
+    if (options.requireToken === true && !token) {
+        return false;
+    }
+
+    return true;
+}
+
+function findRecentFramePayload(device, frameKind, options = {}) {
+    const kind = frameKind === 'thumbnail' ? 'thumbnail' : 'live';
+    const latest = kind === 'thumbnail'
+        ? device?.latestThumbnail
+        : device?.latestLiveFrame;
+    if (isFramePayloadRequestMatch(latest, options)) {
+        return latest;
+    }
+
+    const token = safeString(options.token, 128);
+    const requestedSeq = Number(options.frameSeq);
+    if (!token && !Number.isFinite(requestedSeq)) {
+        return null;
+    }
+
+    const cache = getRecentFrameCache(device, kind);
+    if (!cache) {
+        return null;
+    }
+
+    pruneRecentFrameCache(cache, kind);
+    const entry = cache.find(item => isFramePayloadRequestMatch(item?.frame, options));
+    return entry?.frame || null;
+}
+
 function serializeDevice(device, options = {}) {
     if (!device) {
         return null;
@@ -809,6 +961,7 @@ export function createRemoteHub(options = {}) {
         delete frame.mode;
         delete frame.fps;
         device.latestThumbnail = frame;
+        rememberRecentFramePayload(device, 'thumbnail', frame);
         device.lastSeenAt = frame.receivedAt;
         device.counters.thumbnailFramesReceived += 1;
         emitRemoteEvent('RemoteFrameReceived', device, {
@@ -831,6 +984,7 @@ export function createRemoteHub(options = {}) {
             fps: options.fps || device.activeLiveStream.fps
         });
         device.latestLiveFrame = frame;
+        rememberRecentFramePayload(device, 'live', frame);
         device.activeLiveStream.lastFrameAt = frame.receivedAt;
         device.activeLiveStream.lastFrameSeq = frame.frameSeq;
         device.activeLiveStream.framesReceived = (device.activeLiveStream.framesReceived || 0) + 1;
@@ -968,6 +1122,10 @@ export function createRemoteHub(options = {}) {
                 },
                 latestThumbnail: null,
                 latestLiveFrame: null,
+                recentFramePayloads: {
+                    thumbnail: [],
+                    live: []
+                },
                 activeLiveStream: null,
                 latestTask,
                 recentTasks: latestTask ? [latestTask] : [],
@@ -992,6 +1150,7 @@ export function createRemoteHub(options = {}) {
                 frame.receivedAt = seenAt;
                 frame.capturedAt = seenAt;
                 device.latestThumbnail = frame;
+                rememberRecentFramePayload(device, 'thumbnail', frame);
                 device.counters.thumbnailFramesReceived = 1;
             }
 
@@ -1074,6 +1233,10 @@ export function createRemoteHub(options = {}) {
             status: {},
             latestThumbnail: null,
             latestLiveFrame: null,
+            recentFramePayloads: {
+                thumbnail: [],
+                live: []
+            },
             activeLiveStream: null,
             latestTask: null,
             recentTasks: [],
@@ -1545,6 +1708,7 @@ export function createRemoteHub(options = {}) {
             payload,
             accessToken: createFrameAccessToken()
         };
+        rememberRecentFramePayload(device, 'thumbnail', device.latestThumbnail);
         device.counters.thumbnailFramesReceived += 1;
         emitRemoteEvent('RemoteFrameReceived', device, {
             streamId: device.latestThumbnail.streamId,
@@ -1615,6 +1779,7 @@ export function createRemoteHub(options = {}) {
             payload,
             accessToken: createFrameAccessToken()
         };
+        rememberRecentFramePayload(device, 'live', device.latestLiveFrame);
         device.activeLiveStream.lastFrameAt = device.lastSeenAt;
         device.activeLiveStream.lastFrameSeq = frameSeq;
         device.activeLiveStream.framesReceived = (device.activeLiveStream.framesReceived || 0) + 1;
@@ -2376,29 +2541,18 @@ export function createRemoteHub(options = {}) {
 
     function getFramePayload(deviceId, frameKind, options = {}) {
         const device = devices.get(String(deviceId || ''));
-        const frame = frameKind === 'thumbnail'
-            ? device?.latestThumbnail
-            : device?.latestLiveFrame;
-        if (!frame || !Buffer.isBuffer(frame.payload)) {
-            return null;
-        }
-
-        const requestedSeq = Number(options.frameSeq);
-        if (Number.isFinite(requestedSeq) && Math.floor(requestedSeq) !== frame.frameSeq) {
-            return null;
-        }
-
-        const token = safeString(options.token, 128);
-        if (token && !timingSafeStringEqual(token, frame.accessToken)) {
+        if (!device) {
             return null;
         }
 
-        if (options.requireToken === true && !token) {
+        const kind = frameKind === 'thumbnail' ? 'thumbnail' : 'live';
+        const frame = findRecentFramePayload(device, kind, options);
+        if (!frame) {
             return null;
         }
 
         return {
-            frame: serializeRemoteFrame(frame, device.deviceId, frameKind, { includeDataUrl: false }),
+            frame: serializeRemoteFrame(frame, device.deviceId, kind, { includeDataUrl: false }),
             payload: frame.payload,
             mimeType: safeString(frame.mimeType || frame.format || 'application/octet-stream', 120) || 'application/octet-stream',
             byteLength: frame.payload.length

package/scripts/remote-hub-smoke.mjs

@@ -143,6 +143,8 @@ try {
     });
     assert.equal(thumbnailDevice.latestThumbnail.streamId, 'smoke-thumb');
     assert.equal(thumbnailDevice.counters.thumbnailFramesReceived, 1);
+    const serializedFirstThumbnail = hub.getDeviceThumbnail('smoke-device', { includeDataUrl: false });
+    const serializedFirstThumbnailUrl = new URL(serializedFirstThumbnail.framePath, 'http://127.0.0.1');
 
     const binaryThumbnailCommand = hub.requestThumbnail('smoke-device', {
         streamId: 'smoke-thumb-binary',
@@ -190,6 +192,14 @@ try {
     assert.equal(thumbnailPayload?.mimeType, 'image/png');
     assert.equal(thumbnailPayload?.byteLength, smokePngFrame.length);
     assert.equal(Buffer.compare(thumbnailPayload.payload, smokePngFrame), 0);
+    const retainedThumbnailPayload = hub.getFramePayload('smoke-device', 'thumbnail', {
+        token: serializedFirstThumbnailUrl.searchParams.get('token'),
+        frameSeq: serializedFirstThumbnailUrl.searchParams.get('seq'),
+        requireToken: true
+    });
+    assert.equal(retainedThumbnailPayload?.frame?.frameSeq, 1);
+    assert.equal(retainedThumbnailPayload?.byteLength, smokePngFrame.length);
+    assert.equal(Buffer.compare(retainedThumbnailPayload.payload, smokePngFrame), 0);
     assert.equal(hub.getFramePayload('smoke-device', 'thumbnail', {
         token: 'wrong-token',
         frameSeq: 4,
@@ -225,6 +235,8 @@ try {
     assert.equal(liveDevice.activeLiveStream.active, true);
     assert.equal(liveDevice.latestLiveFrame.mode, 'remote-fast');
     assert.equal(liveDevice.counters.liveFramesReceived, 1);
+    const serializedFirstLiveFrame = hub.getDeviceLiveFrame('smoke-device', { includeDataUrl: false });
+    const serializedFirstLiveUrl = new URL(serializedFirstLiveFrame.framePath, 'http://127.0.0.1');
 
     writeBinaryFrame(socket, {
         frameKind: 'stream',
@@ -267,6 +279,14 @@ try {
     assert.equal(livePayload?.mimeType, 'image/png');
     assert.equal(livePayload?.byteLength, smokePngFrame.length);
     assert.equal(Buffer.compare(livePayload.payload, smokePngFrame), 0);
+    const retainedLivePayload = hub.getFramePayload('smoke-device', 'live', {
+        token: serializedFirstLiveUrl.searchParams.get('token'),
+        frameSeq: serializedFirstLiveUrl.searchParams.get('seq'),
+        requireToken: true
+    });
+    assert.equal(retainedLivePayload?.frame?.frameSeq, 2);
+    assert.equal(retainedLivePayload?.byteLength, smokePngFrame.length);
+    assert.equal(Buffer.compare(retainedLivePayload.payload, smokePngFrame), 0);
     assert.equal(hub.getFramePayload('smoke-device', 'live', {
         token: serializedLiveUrl.searchParams.get('token'),
         frameSeq: 4,