@mindexec/cli 0.2.394 → 0.2.396

package/package.json

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

package/remote-hub.js

@@ -20,7 +20,73 @@ const RECENT_THUMBNAIL_FRAME_CACHE_LIMIT = 4;
 const RECENT_LIVE_FRAME_CACHE_LIMIT = 80;
 const RECENT_THUMBNAIL_FRAME_CACHE_MAX_BYTES = 3 * 1024 * 1024;
 const RECENT_LIVE_FRAME_CACHE_MAX_BYTES = 24 * 1024 * 1024;
-const REMOTE_PROTOCOL_VERSION = 1;
+const REMOTE_PROTOCOL_VERSION = 2;
+const REMOTE_AGENT_PROTOCOL = 'mindexec.remote.agent';
+const REMOTE_FRAME_PROTOCOL = 'mindexec.remote.frame.v2';
+const REMOTE_FRAME_PROTOCOL_VERSION = 2;
+const REMOTE_FRAME_HANDSHAKE = 'smartview-request-open-frame';
+const DEFAULT_REMOTE_FRAME_MODE = 'remote-fast';
+const REMOTE_FRAME_MODE_PROFILES = Object.freeze({
+    thumbnail: Object.freeze({
+        mode: 'thumbnail',
+        label: 'Thumbnail PNG/JPEG Binary',
+        transport: 'ws-binary',
+        encoding: 'image',
+        codec: 'image',
+        compression: 'image/*',
+        profile: 'thumbnail-binary-v1',
+        modeVersion: 1,
+        implemented: true
+    }),
+    'remote-fast': Object.freeze({
+        mode: 'remote-fast',
+        label: 'RemoteFast JPEG Binary',
+        transport: 'ws-binary',
+        encoding: 'image',
+        codec: 'jpeg',
+        compression: 'image/jpeg',
+        profile: 'jpeg-binary-v1',
+        modeVersion: 1,
+        implemented: true
+    }),
+    'remote-quality': Object.freeze({
+        mode: 'remote-quality',
+        label: 'RemoteQuality JPEG Binary',
+        transport: 'ws-binary',
+        encoding: 'image',
+        codec: 'jpeg',
+        compression: 'image/jpeg',
+        profile: 'jpeg-quality-binary-v1',
+        modeVersion: 1,
+        implemented: true
+    }),
+    'video-codec': Object.freeze({
+        mode: 'video-codec',
+        label: 'Video Codec Stream',
+        transport: 'ws-binary',
+        encoding: 'video',
+        codec: 'video',
+        compression: 'video/*',
+        profile: 'future-video-codec',
+        modeVersion: 0,
+        implemented: false
+    })
+});
+const REMOTE_FRAME_MODE_ALIASES = new Map([
+    ['fast', 'remote-fast'],
+    ['remotefast', 'remote-fast'],
+    ['remote_fast', 'remote-fast'],
+    ['remote-fast', 'remote-fast'],
+    ['quality', 'remote-quality'],
+    ['remotequality', 'remote-quality'],
+    ['remote_quality', 'remote-quality'],
+    ['remote-quality', 'remote-quality'],
+    ['thumb', 'thumbnail'],
+    ['thumbnail', 'thumbnail'],
+    ['video', 'video-codec'],
+    ['codec', 'video-codec'],
+    ['video-codec', 'video-codec']
+]);
 const MAX_SYNTHETIC_DEVICES = 1000;
 const DEFAULT_HOST_TARGET_LEASE_MS = 30000;
 const DUPLICATE_DEVICE_ACTIVE_REJECT_MS = 15000;
@@ -58,6 +124,115 @@ function safeString(value, maxLength = 200) {
     return String(value ?? '').replace(/[\r\n\t]/g, ' ').trim().slice(0, maxLength);
 }
 
+function normalizeRemoteFrameMode(value, fallback = DEFAULT_REMOTE_FRAME_MODE) {
+    const requested = safeString(value, 80).toLowerCase();
+    const fallbackMode = REMOTE_FRAME_MODE_PROFILES[fallback] ? fallback : DEFAULT_REMOTE_FRAME_MODE;
+    if (!requested) {
+        return fallbackMode;
+    }
+
+    const normalized = REMOTE_FRAME_MODE_ALIASES.get(requested) || requested;
+    const profile = REMOTE_FRAME_MODE_PROFILES[normalized];
+    if (!profile || profile.implemented !== true) {
+        return fallbackMode;
+    }
+
+    return normalized;
+}
+
+function serializeRemoteFrameModeProfile(profile) {
+    return {
+        mode: profile.mode,
+        label: profile.label,
+        transport: profile.transport,
+        encoding: profile.encoding,
+        codec: profile.codec,
+        compression: profile.compression,
+        profile: profile.profile,
+        modeVersion: profile.modeVersion,
+        implemented: profile.implemented === true
+    };
+}
+
+function getRemoteFrameModeProfile(value, fallback = DEFAULT_REMOTE_FRAME_MODE) {
+    const mode = normalizeRemoteFrameMode(value, fallback);
+    return serializeRemoteFrameModeProfile(REMOTE_FRAME_MODE_PROFILES[mode]);
+}
+
+function getSupportedRemoteFrameModeProfiles() {
+    return Object.values(REMOTE_FRAME_MODE_PROFILES)
+        .filter(profile => profile.implemented === true)
+        .map(serializeRemoteFrameModeProfile);
+}
+
+function buildRemoteFrameProtocolDescriptor() {
+    return {
+        protocol: REMOTE_FRAME_PROTOCOL,
+        version: REMOTE_FRAME_PROTOCOL_VERSION,
+        handshake: REMOTE_FRAME_HANDSHAKE,
+        defaultMode: DEFAULT_REMOTE_FRAME_MODE,
+        modes: getSupportedRemoteFrameModeProfiles()
+    };
+}
+
+function buildRemoteFrameTransferDescriptor(value, fallback = DEFAULT_REMOTE_FRAME_MODE) {
+    const profile = getRemoteFrameModeProfile(value, fallback);
+    return {
+        mode: profile.mode,
+        frameMode: profile.mode,
+        frameProfile: profile.profile,
+        encoding: profile.encoding,
+        codec: profile.codec,
+        compression: profile.compression,
+        transferProtocol: REMOTE_FRAME_PROTOCOL,
+        transferProtocolVersion: REMOTE_FRAME_PROTOCOL_VERSION,
+        handshake: REMOTE_FRAME_HANDSHAKE
+    };
+}
+
+function buildRemoteFrameTransferDescriptorFromMessage(message = {}, fallback = DEFAULT_REMOTE_FRAME_MODE) {
+    const descriptor = buildRemoteFrameTransferDescriptor(message.frameMode || message.mode, fallback);
+    return {
+        ...descriptor,
+        frameProfile: safeString(message.frameProfile, 80) || descriptor.frameProfile,
+        encoding: safeString(message.encoding, 40) || descriptor.encoding,
+        codec: safeString(message.codec, 40) || descriptor.codec,
+        compression: safeString(message.compression || message.mimeType || message.format, 80) || descriptor.compression,
+        transferProtocol: safeString(message.transferProtocol, 80) || descriptor.transferProtocol,
+        transferProtocolVersion: Number.isFinite(Number(message.transferProtocolVersion))
+            ? Math.max(1, Math.floor(Number(message.transferProtocolVersion)))
+            : descriptor.transferProtocolVersion,
+        handshake: safeString(message.handshake, 80) || descriptor.handshake
+    };
+}
+
+function normalizeIncomingFrameModeProfile(value) {
+    if (!value) {
+        return null;
+    }
+
+    if (typeof value === 'string') {
+        return getRemoteFrameModeProfile(value);
+    }
+
+    if (typeof value !== 'object') {
+        return null;
+    }
+
+    const profile = buildRemoteFrameTransferDescriptor(value.mode || value.frameMode || value.profile);
+    return {
+        mode: profile.mode,
+        label: safeString(value.label, 80) || profile.mode,
+        transport: safeString(value.transport, 40) || 'ws-binary',
+        encoding: safeString(value.encoding, 40) || profile.encoding,
+        codec: safeString(value.codec, 40) || profile.codec,
+        compression: safeString(value.compression, 80) || profile.compression,
+        profile: safeString(value.profile || value.frameProfile, 80) || profile.frameProfile,
+        modeVersion: Number.isFinite(Number(value.modeVersion)) ? Math.max(0, Math.floor(Number(value.modeVersion))) : 1,
+        implemented: value.implemented !== false
+    };
+}
+
 function isLoopbackHost(value) {
     const host = String(value || '').trim().toLowerCase();
     return host === 'localhost'
@@ -542,6 +717,12 @@ function serializeDevice(device, options = {}) {
         arch: device.arch,
         pid: device.pid,
         agentVersion: device.agentVersion,
+        protocol: device.protocol,
+        protocolVersion: device.protocolVersion,
+        frameProtocol: device.frameProtocol ? { ...device.frameProtocol } : null,
+        frameModes: Array.isArray(device.frameModes)
+            ? device.frameModes.map(profile => ({ ...profile }))
+            : [],
         capabilities: { ...device.capabilities },
         connected: device.connected,
         connectedAt: device.connectedAt,
@@ -1086,6 +1267,9 @@ export function createRemoteHub(options = {}) {
             port: boundPort || requestedPort,
             protocol: 'tcp-jsonl',
             protocolVersion: REMOTE_PROTOCOL_VERSION,
+            agentProtocol: REMOTE_AGENT_PROTOCOL,
+            frameProtocol: buildRemoteFrameProtocolDescriptor(),
+            frameModes: getSupportedRemoteFrameModeProfiles(),
             heartbeatMs,
             taskTimeoutMs,
             managerPackage,
@@ -1183,6 +1367,7 @@ export function createRemoteHub(options = {}) {
 
     function makeSyntheticFrame(device, streamId, mode = 'thumbnail', options = {}) {
         const now = new Date().toISOString();
+        const descriptor = buildRemoteFrameTransferDescriptor(mode, mode === 'thumbnail' ? 'thumbnail' : DEFAULT_REMOTE_FRAME_MODE);
         const frameSeq = Number(device?.counters?.thumbnailFramesReceived || 0)
             + Number(device?.counters?.liveFramesReceived || 0)
             + 1;
@@ -1195,6 +1380,14 @@ export function createRemoteHub(options = {}) {
             mimeType: 'image/png',
             format: 'image/png',
             mode,
+            frameMode: descriptor.frameMode,
+            frameProfile: descriptor.frameProfile,
+            encoding: descriptor.encoding,
+            codec: 'png',
+            compression: 'image/png',
+            transferProtocol: descriptor.transferProtocol,
+            transferProtocolVersion: descriptor.transferProtocolVersion,
+            handshake: descriptor.handshake,
             fps: clampNumber(options.fps, 1, 24, mode === 'remote-fast' ? 20 : 1),
             capturedAt: now,
             receivedAt: now,
@@ -1239,7 +1432,7 @@ export function createRemoteHub(options = {}) {
             return null;
         }
 
-        const frame = makeSyntheticFrame(device, streamId || device.activeLiveStream.streamId, 'remote-fast', {
+        const frame = makeSyntheticFrame(device, streamId || device.activeLiveStream.streamId, device.activeLiveStream.mode || DEFAULT_REMOTE_FRAME_MODE, {
             commandId: options.commandId || device.activeLiveStream.commandId,
             width: options.maxWidth || 960,
             height: options.maxHeight || 540,
@@ -1482,11 +1675,23 @@ export function createRemoteHub(options = {}) {
             }
 
             if (isLive) {
+                const transfer = buildRemoteFrameTransferDescriptor(DEFAULT_REMOTE_FRAME_MODE);
                 device.activeLiveStream = {
                     streamId: `synthetic-live-${ordinal}`,
                     commandId: `synthetic-live-command-${ordinal}`,
                     active: true,
-                    mode: 'remote-fast',
+                    open: true,
+                    openedAt: seenAt,
+                    openTransport: 'synthetic',
+                    mode: transfer.mode,
+                    frameMode: transfer.frameMode,
+                    frameProfile: transfer.frameProfile,
+                    encoding: transfer.encoding,
+                    codec: transfer.codec,
+                    compression: transfer.compression,
+                    transferProtocol: transfer.transferProtocol,
+                    transferProtocolVersion: transfer.transferProtocolVersion,
+                    handshake: transfer.handshake,
                     fps: 20,
                     startedAt: seenAt,
                     stoppedAt: '',
@@ -1543,6 +1748,24 @@ export function createRemoteHub(options = {}) {
 
         closeExistingDeviceSocket(deviceId, sessionId);
 
+        const frameProtocol = typeof hello.frameProtocol === 'object' && hello.frameProtocol
+            ? { ...hello.frameProtocol }
+            : null;
+        const frameModes = Array.isArray(hello.frameModes)
+            ? hello.frameModes.map(normalizeIncomingFrameModeProfile).filter(Boolean)
+            : [];
+        const capabilities = typeof hello.capabilities === 'object' && hello.capabilities
+            ? { ...hello.capabilities }
+            : {};
+        if (!capabilities.frameProtocol) {
+            capabilities.frameProtocol = frameProtocol || buildRemoteFrameProtocolDescriptor();
+        }
+        if (!capabilities.frameModes) {
+            capabilities.frameModes = frameModes.length > 0
+                ? frameModes.map(profile => ({ ...profile }))
+                : getSupportedRemoteFrameModeProfiles();
+        }
+
         const device = {
             socket,
             deviceId,
@@ -1553,9 +1776,11 @@ export function createRemoteHub(options = {}) {
             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 }
-                : {},
+            protocol: safeString(hello.protocol, 80) || REMOTE_AGENT_PROTOCOL,
+            protocolVersion: Number.isFinite(Number(hello.protocolVersion)) ? Math.max(1, Math.floor(Number(hello.protocolVersion))) : 1,
+            frameProtocol: frameProtocol || buildRemoteFrameProtocolDescriptor(),
+            frameModes: frameModes.length > 0 ? frameModes : getSupportedRemoteFrameModeProfiles(),
+            capabilities,
             connected: true,
             connectedAt: now,
             disconnectedAt: '',
@@ -1584,10 +1809,13 @@ export function createRemoteHub(options = {}) {
         sockets.set(socket, deviceId);
         writeJsonLine(socket, {
             type: 'welcome',
+            protocol: REMOTE_AGENT_PROTOCOL,
             protocolVersion: REMOTE_PROTOCOL_VERSION,
             sessionId,
             deviceId,
             heartbeatMs,
+            frameProtocol: buildRemoteFrameProtocolDescriptor(),
+            frameModes: getSupportedRemoteFrameModeProfiles(),
             serverTime: now
         });
 
@@ -2023,6 +2251,7 @@ export function createRemoteHub(options = {}) {
         const payload = buildFramePayloadBuffer(framePayload, frameData);
         const contentHash = buildFrameContentHash(message, payload);
         const sameContentStreak = computeSameContentStreak(device.latestThumbnail, contentHash);
+        const transfer = buildRemoteFrameTransferDescriptorFromMessage(message, 'thumbnail');
         device.latestThumbnail = {
             streamId: safeString(message.streamId, 128) || 'thumbnail',
             frameSeq,
@@ -2031,6 +2260,14 @@ export function createRemoteHub(options = {}) {
             height: Number.isFinite(Number(message.height)) ? Number(message.height) : 0,
             mimeType,
             format: mimeType,
+            frameMode: transfer.frameMode,
+            frameProfile: transfer.frameProfile,
+            encoding: transfer.encoding,
+            codec: transfer.codec,
+            compression: transfer.compression || mimeType,
+            transferProtocol: transfer.transferProtocol,
+            transferProtocolVersion: transfer.transferProtocolVersion,
+            handshake: transfer.handshake,
             capturedAt,
             receivedAt: device.lastSeenAt,
             byteLength,
@@ -2055,6 +2292,49 @@ export function createRemoteHub(options = {}) {
         return true;
     }
 
+    function applyLiveStreamOpen(device, message, transport = 'json') {
+        const streamId = safeString(message.streamId, 128) || 'live';
+        if (!device.activeLiveStream?.active || device.activeLiveStream.streamId !== streamId) {
+            emitRemoteEvent('RemoteLiveStreamOpenIgnored', device, {
+                reason: 'stale-live-stream-open',
+                streamId,
+                transport
+            });
+            return false;
+        }
+
+        const transfer = buildRemoteFrameTransferDescriptorFromMessage(message, device.activeLiveStream.mode || DEFAULT_REMOTE_FRAME_MODE);
+        const openedAt = safeString(message.openedAt, 80) || device.lastSeenAt || new Date().toISOString();
+        device.activeLiveStream = {
+            ...device.activeLiveStream,
+            open: true,
+            openedAt,
+            openTransport: transport,
+            mode: transfer.mode,
+            frameMode: transfer.frameMode,
+            frameProfile: transfer.frameProfile,
+            encoding: transfer.encoding,
+            codec: transfer.codec,
+            compression: transfer.compression,
+            transferProtocol: transfer.transferProtocol,
+            transferProtocolVersion: transfer.transferProtocolVersion,
+            handshake: transfer.handshake,
+            width: Number.isFinite(Number(message.width)) ? Number(message.width) : Number(device.activeLiveStream.width || 0),
+            height: Number.isFinite(Number(message.height)) ? Number(message.height) : Number(device.activeLiveStream.height || 0),
+            openedFrameSeq: Number.isFinite(Number(message.frameSeq)) ? Number(message.frameSeq) : Number(device.activeLiveStream.openedFrameSeq || 0)
+        };
+        emitRemoteEvent('RemoteLiveStreamOpened', device, {
+            streamId,
+            mode: transfer.mode,
+            frameMode: transfer.frameMode,
+            frameProfile: transfer.frameProfile,
+            encoding: transfer.encoding,
+            compression: transfer.compression,
+            transport
+        });
+        return true;
+    }
+
     function applyLiveFrame(device, message, framePayload, transport = 'json-base64') {
         const frameData = Buffer.isBuffer(framePayload)
             ? ''
@@ -2091,6 +2371,21 @@ export function createRemoteHub(options = {}) {
         const payload = buildFramePayloadBuffer(framePayload, frameData);
         const contentHash = buildFrameContentHash(message, payload);
         const sameContentStreak = computeSameContentStreak(device.latestLiveFrame, contentHash);
+        const transfer = buildRemoteFrameTransferDescriptorFromMessage(message, device.activeLiveStream.mode || DEFAULT_REMOTE_FRAME_MODE);
+        if (device.activeLiveStream.open !== true) {
+            device.activeLiveStream.open = true;
+            device.activeLiveStream.openedAt = device.lastSeenAt;
+            device.activeLiveStream.openTransport = `${transport}-implicit`;
+            device.activeLiveStream.mode = transfer.mode;
+            device.activeLiveStream.frameMode = transfer.frameMode;
+            device.activeLiveStream.frameProfile = transfer.frameProfile;
+            device.activeLiveStream.encoding = transfer.encoding;
+            device.activeLiveStream.codec = transfer.codec;
+            device.activeLiveStream.compression = transfer.compression;
+            device.activeLiveStream.transferProtocol = transfer.transferProtocol;
+            device.activeLiveStream.transferProtocolVersion = transfer.transferProtocolVersion;
+            device.activeLiveStream.handshake = transfer.handshake;
+        }
         device.latestLiveFrame = {
             streamId,
             frameSeq,
@@ -2099,7 +2394,15 @@ export function createRemoteHub(options = {}) {
             height: Number.isFinite(Number(message.height)) ? Number(message.height) : 0,
             mimeType,
             format: mimeType,
-            mode: safeString(message.mode || device.activeLiveStream.mode || 'remote-fast', 80),
+            mode: transfer.mode,
+            frameMode: transfer.frameMode,
+            frameProfile: transfer.frameProfile,
+            encoding: transfer.encoding,
+            codec: transfer.codec,
+            compression: transfer.compression || mimeType,
+            transferProtocol: transfer.transferProtocol,
+            transferProtocolVersion: transfer.transferProtocolVersion,
+            handshake: transfer.handshake,
             fps: Number.isFinite(Number(message.fps)) ? Number(message.fps) : device.activeLiveStream.fps,
             capturedAt,
             receivedAt: device.lastSeenAt,
@@ -2123,6 +2426,15 @@ export function createRemoteHub(options = {}) {
         device.activeLiveStream.lastFrameAt = device.lastSeenAt;
         device.activeLiveStream.lastFrameSeq = frameSeq;
         device.activeLiveStream.framesReceived = (device.activeLiveStream.framesReceived || 0) + 1;
+        device.activeLiveStream.mode = transfer.mode;
+        device.activeLiveStream.frameMode = transfer.frameMode;
+        device.activeLiveStream.frameProfile = transfer.frameProfile;
+        device.activeLiveStream.encoding = transfer.encoding;
+        device.activeLiveStream.codec = transfer.codec;
+        device.activeLiveStream.compression = transfer.compression;
+        device.activeLiveStream.transferProtocol = transfer.transferProtocol;
+        device.activeLiveStream.transferProtocolVersion = transfer.transferProtocolVersion;
+        device.activeLiveStream.handshake = transfer.handshake;
         device.counters.liveFramesReceived += 1;
         emitRemoteEvent('RemoteFrameReceived', device, {
             streamId,
@@ -2237,6 +2549,10 @@ export function createRemoteHub(options = {}) {
                 applyThumbnailFrame(device, message, message.data, 'json-base64');
                 break;
             }
+            case 'stream.open': {
+                applyLiveStreamOpen(device, message, 'json');
+                break;
+            }
             case 'stream.frame': {
                 applyLiveFrame(device, message, message.data, 'json-base64');
                 break;
@@ -2895,12 +3211,24 @@ export function createRemoteHub(options = {}) {
             const streamId = safeString(options.streamId, 128) || `live-${Date.now()}`;
             const fps = clampNumber(options.fps, 1, 24, 20);
             const commandId = safeString(options.commandId, 128) || crypto.randomUUID();
+            const transfer = buildRemoteFrameTransferDescriptor(options.mode || DEFAULT_REMOTE_FRAME_MODE);
             device.counters.commandsSent += 1;
             device.activeLiveStream = {
                 streamId,
                 commandId,
                 active: true,
-                mode: 'remote-fast',
+                open: true,
+                openedAt: now,
+                openTransport: 'synthetic',
+                mode: transfer.mode,
+                frameMode: transfer.frameMode,
+                frameProfile: transfer.frameProfile,
+                encoding: transfer.encoding,
+                codec: transfer.codec,
+                compression: transfer.compression,
+                transferProtocol: transfer.transferProtocol,
+                transferProtocolVersion: transfer.transferProtocolVersion,
+                handshake: transfer.handshake,
                 fps,
                 startedAt: now,
                 stoppedAt: '',
@@ -2920,9 +3248,10 @@ export function createRemoteHub(options = {}) {
                 streamId,
                 commandId,
                 fps,
+                mode: transfer.mode,
                 synthetic: true
             });
-            return { ok: true, commandId, streamId, fps, synthetic: true };
+            return { ok: true, commandId, streamId, fps, mode: transfer.mode, frameMode: transfer.frameMode, synthetic: true };
         }
 
         if (!device?.socket || device.socket.destroyed || !device.connected) {
@@ -2936,12 +3265,21 @@ export function createRemoteHub(options = {}) {
         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 transfer = buildRemoteFrameTransferDescriptor(options.mode || DEFAULT_REMOTE_FRAME_MODE);
         const result = sendCommand(deviceId, {
             command: 'stream.start',
             commandId,
             payload: {
                 streamId,
-                mode: safeString(options.mode, 80) || 'remote-fast',
+                mode: transfer.mode,
+                frameMode: transfer.frameMode,
+                frameProfile: transfer.frameProfile,
+                encoding: transfer.encoding,
+                codec: transfer.codec,
+                compression: transfer.compression,
+                transferProtocol: transfer.transferProtocol,
+                transferProtocolVersion: transfer.transferProtocolVersion,
+                handshake: transfer.handshake,
                 fps,
                 maxWidth: clampNumber(options.maxWidth, 320, 2560, 960),
                 maxHeight: clampNumber(options.maxHeight, 180, 1440, 540),
@@ -2958,7 +3296,18 @@ export function createRemoteHub(options = {}) {
             streamId,
             commandId,
             active: true,
-            mode: 'remote-fast',
+            open: false,
+            openedAt: '',
+            openTransport: '',
+            mode: transfer.mode,
+            frameMode: transfer.frameMode,
+            frameProfile: transfer.frameProfile,
+            encoding: transfer.encoding,
+            codec: transfer.codec,
+            compression: transfer.compression,
+            transferProtocol: transfer.transferProtocol,
+            transferProtocolVersion: transfer.transferProtocolVersion,
+            handshake: transfer.handshake,
             fps,
             startedAt: now,
             stoppedAt: '',
@@ -2971,10 +3320,12 @@ export function createRemoteHub(options = {}) {
         emitRemoteEvent('RemoteLiveStreamStarted', device, {
             streamId,
             commandId,
-            fps
+            fps,
+            mode: transfer.mode,
+            frameMode: transfer.frameMode
         });
 
-        return { ok: true, commandId, streamId, fps };
+        return { ok: true, commandId, streamId, fps, mode: transfer.mode, frameMode: transfer.frameMode };
     }
 
     function stopLiveStream(deviceId, options = {}) {

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

@@ -162,6 +162,7 @@ async function connectManagedAgent(clientBridge, managerEndpoint, staleEndpoint)
     const result = await fetchJson(`${clientBridge.baseUrl}/api/remote/agent/connect`, {
         method: 'POST',
         body: JSON.stringify({
+            manager: managerEndpoint,
             managerCandidates: [staleEndpoint, managerEndpoint],
             pairToken: PAIR_TOKEN,
             leaseId: LEASE_ID,
@@ -216,9 +217,9 @@ async function main() {
         assert.equal(firstAgent.ready, true, JSON.stringify(firstAgent));
         assert.equal(firstAgent.usingNpx, false, JSON.stringify(firstAgent));
         assert.match(String(firstAgent.launcher || ''), /mindexec-remote-fast/i);
-        assert.ok(
-            firstConnectMs < 4500,
-            `managed RemoteAgent must race slow endpoint candidates instead of waiting sequentially, got ${firstConnectMs}ms`);
+        assert.equal(firstAgent.manager, managerEndpoint, JSON.stringify(firstAgent));
+        assert.equal(firstAgent.managerCandidates?.[0], managerEndpoint, JSON.stringify(firstAgent.managerCandidates));
+        assert.ok(firstConnectMs < 4500, `managed RemoteAgent selected manager should connect promptly, got ${firstConnectMs}ms`);
 
         const connectedDevice = await waitFor(async () => {
             const result = await fetchJson(`${hostBridge.baseUrl}/api/remote/devices`);
@@ -248,7 +249,7 @@ async function main() {
         assert.equal(secondAgent.usingNpx, false, JSON.stringify(secondAgent));
         assert.match(String(secondAgent.launcher || ''), /mindexec-remote-fast/i);
         assert.equal(secondAgent.managerCandidates?.[0], managerEndpoint, JSON.stringify(secondAgent.managerCandidates));
-        assert.equal(secondAgent.managerCandidates?.[1], staleEndpoint, JSON.stringify(secondAgent.managerCandidates));
+        assert.equal(secondAgent.managerCandidates?.length, 1, JSON.stringify(secondAgent.managerCandidates));
 
         const staleReport = await fetchJson(`${clientBridge.baseUrl}/api/remote/agent/sync-report`, {
             method: 'POST',

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

@@ -88,6 +88,25 @@ try {
         pid: process.pid,
         agentVersion: '0.0.0-ws-smoke',
         runtime: 'node-smoke',
+        protocol: 'mindexec.remote.agent',
+        protocolVersion: 2,
+        frameProtocol: {
+            protocol: 'mindexec.remote.frame.v2',
+            version: 2,
+            handshake: 'smartview-request-open-frame',
+            defaultMode: 'remote-fast'
+        },
+        frameModes: [{
+            mode: 'remote-fast',
+            label: 'RemoteFast JPEG Binary',
+            transport: 'ws-binary',
+            encoding: 'image',
+            codec: 'jpeg',
+            compression: 'image/jpeg',
+            profile: 'jpeg-binary-v1',
+            modeVersion: 1,
+            implemented: true
+        }],
         capabilities: {
             status: true,
             thumbnail: true,
@@ -109,13 +128,20 @@ try {
         }
     }));
 
-    await waitFor(() => received.find(item => item.type === 'welcome'), 5000, 'welcome');
+    const welcome = await waitFor(() => received.find(item => item.type === 'welcome'), 5000, 'welcome');
+    assert.equal(welcome.protocol, 'mindexec.remote.agent');
+    assert.equal(welcome.frameProtocol?.handshake, 'smartview-request-open-frame');
+    assert.equal(welcome.frameProtocol?.defaultMode, 'remote-fast');
+    assert.ok(welcome.frameModes?.some(item => item.mode === 'remote-fast'));
     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);
+    assert.equal(device.protocol, 'mindexec.remote.agent');
+    assert.equal(device.frameProtocol?.handshake, 'smartview-request-open-frame');
+    assert.ok(device.frameModes?.some(item => item.mode === 'remote-fast'));
 
     const inputCommand = hub.sendInputControl(DEVICE_ID, { type: 'noop' });
     assert.equal(inputCommand.ok, true);
@@ -170,10 +196,36 @@ try {
         quality: 50
     });
     assert.equal(liveCommand.ok, true);
-    await waitFor(
+    const liveMessage = await waitFor(
         () => received.find(item => item.commandId === liveCommand.commandId),
         5000,
         'live command');
+    assert.equal(liveMessage.command, 'stream.start');
+    assert.equal(liveMessage.payload?.handshake, 'smartview-request-open-frame');
+    assert.equal(liveMessage.payload?.mode, 'remote-fast');
+    assert.equal(liveMessage.payload?.frameMode, 'remote-fast');
+    assert.equal(liveMessage.payload?.frameProfile, 'jpeg-binary-v1');
+    assert.equal(liveMessage.payload?.compression, 'image/jpeg');
+    assert.equal(liveMessage.payload?.transferProtocol, 'mindexec.remote.frame.v2');
+    ws.send(JSON.stringify({
+        type: 'stream.open',
+        commandId: liveCommand.commandId,
+        streamId: 'remote-agent-ws-live',
+        mode: 'remote-fast',
+        frameMode: 'remote-fast',
+        frameProfile: 'jpeg-binary-v1',
+        encoding: 'image',
+        codec: 'png',
+        compression: 'image/png',
+        transferProtocol: 'mindexec.remote.frame.v2',
+        transferProtocolVersion: 2,
+        handshake: 'smartview-request-open-frame',
+        fps: 10,
+        width: 2,
+        height: 1,
+        openedAt: new Date().toISOString()
+    }));
+    await waitFor(() => hub.listDevices()[0]?.activeLiveStream?.open === true, 5000, 'live stream open');
     writeAgentBinaryFrame(ws, {
         frameKind: 'stream',
         commandId: liveCommand.commandId,
@@ -182,6 +234,15 @@ try {
         width: 2,
         height: 1,
         mimeType: 'image/png',
+        mode: 'remote-fast',
+        frameMode: 'remote-fast',
+        frameProfile: 'jpeg-binary-v1',
+        encoding: 'image',
+        codec: 'png',
+        compression: 'image/png',
+        transferProtocol: 'mindexec.remote.frame.v2',
+        transferProtocolVersion: 2,
+        handshake: 'smartview-request-open-frame',
         fps: 10,
         capturedAt: new Date().toISOString()
     }, SMOKE_PNG);
@@ -191,6 +252,12 @@ try {
     }, 5000, 'websocket binary live frame');
     assert.equal(liveDevice.latestLiveFrame.transport, 'binary');
     assert.equal(liveDevice.latestLiveFrame.streamId, 'remote-agent-ws-live');
+    assert.equal(liveDevice.activeLiveStream.open, true);
+    assert.equal(liveDevice.activeLiveStream.frameMode, 'remote-fast');
+    assert.equal(liveDevice.latestLiveFrame.frameMode, 'remote-fast');
+    assert.equal(liveDevice.latestLiveFrame.frameProfile, 'jpeg-binary-v1');
+    assert.equal(liveDevice.latestLiveFrame.compression, 'image/png');
+    assert.equal(liveDevice.latestLiveFrame.transferProtocol, 'mindexec.remote.frame.v2');
 
     ws.close();
     console.log('RemoteAgent WebSocket smoke OK');

package/scripts/remote-hub-smoke.mjs

@@ -214,6 +214,23 @@ try {
         quality: 50
     });
     assert.equal(liveCommand.ok, true);
+    assert.equal(liveCommand.frameMode, 'remote-fast');
+    writeJsonLine(socket, {
+        type: 'stream.open',
+        commandId: liveCommand.commandId,
+        streamId: 'smoke-live',
+        mode: 'remote-fast',
+        frameMode: 'remote-fast',
+        frameProfile: 'jpeg-binary-v1',
+        encoding: 'image',
+        codec: 'png',
+        compression: 'image/png',
+        transferProtocol: 'mindexec.remote.frame.v2',
+        transferProtocolVersion: 2,
+        handshake: 'smartview-request-open-frame',
+        fps: 5,
+        openedAt: new Date().toISOString()
+    });
     writeJsonLine(socket, {
         type: 'stream.frame',
         commandId: liveCommand.commandId,
@@ -223,6 +240,14 @@ try {
         height: 1,
         mimeType: 'image/png',
         mode: 'remote-fast',
+        frameMode: 'remote-fast',
+        frameProfile: 'jpeg-binary-v1',
+        encoding: 'image',
+        codec: 'png',
+        compression: 'image/png',
+        transferProtocol: 'mindexec.remote.frame.v2',
+        transferProtocolVersion: 2,
+        handshake: 'smartview-request-open-frame',
         fps: 5,
         capturedAt: new Date().toISOString(),
         data: 'iVBORw0KGgoAAAANSUhEUgAAAAIAAAABCAYAAAD0In+KAAAADElEQVR42mP8z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC'
@@ -233,7 +258,11 @@ try {
         return current[0]?.latestLiveFrame?.streamId === 'smoke-live' ? current[0] : null;
     });
     assert.equal(liveDevice.activeLiveStream.active, true);
+    assert.equal(liveDevice.activeLiveStream.open, true);
+    assert.equal(liveDevice.activeLiveStream.handshake, 'smartview-request-open-frame');
     assert.equal(liveDevice.latestLiveFrame.mode, 'remote-fast');
+    assert.equal(liveDevice.latestLiveFrame.frameMode, 'remote-fast');
+    assert.equal(liveDevice.latestLiveFrame.compression, 'image/png');
     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');
@@ -247,6 +276,14 @@ try {
         height: 1,
         mimeType: 'image/png',
         mode: 'remote-fast',
+        frameMode: 'remote-fast',
+        frameProfile: 'jpeg-binary-v1',
+        encoding: 'image',
+        codec: 'png',
+        compression: 'image/png',
+        transferProtocol: 'mindexec.remote.frame.v2',
+        transferProtocolVersion: 2,
+        handshake: 'smartview-request-open-frame',
         fps: 5,
         capturedAt: new Date().toISOString()
     }, smokePngFrame);
@@ -265,6 +302,8 @@ try {
     const serializedBinaryLiveFrame = hub.getDeviceLiveFrame('smoke-device', { includeDataUrl: false });
     assert.equal(serializedBinaryLiveFrame.streamId, 'smoke-live');
     assert.equal(serializedBinaryLiveFrame.frameSeq, 5);
+    assert.equal(serializedBinaryLiveFrame.frameMode, 'remote-fast');
+    assert.equal(serializedBinaryLiveFrame.compression, 'image/png');
     assert.equal(serializedBinaryLiveFrame.contentHash, binaryLiveDevice.latestLiveFrame.contentHash);
     assert.ok(serializedBinaryLiveFrame.framePath.includes('/api/remote/devices/smoke-device/live/frame?'));
     assert.ok(!('dataUrl' in serializedBinaryLiveFrame));

package/scripts/remote-registry-follower-smoke.mjs

@@ -584,7 +584,8 @@ async function main() {
         assert.equal(firstAgent.usingNpx, false, JSON.stringify(firstAgent));
         assert.match(String(firstAgent.launcher || ''), /mindexec-remote-fast/i);
         assert.equal(firstAgent.manager, hostAEndpoint);
-        assert.equal(firstAgent.managerCandidates?.[0], staleEndpoint, JSON.stringify(firstAgent.managerCandidates));
+        assert.equal(firstAgent.managerCandidates?.[0], hostAEndpoint, JSON.stringify(firstAgent.managerCandidates));
+        assert.equal(firstAgent.managerCandidates?.length, 1, JSON.stringify(firstAgent.managerCandidates));
         assert.ok(
             fakeSupabase.requests.some(request =>
                 request.method === 'POST'

package/server.js

@@ -2550,12 +2550,14 @@ function clampRemoteFrameWsNumber(value, min, max, fallback) {
 }
 
 function normalizeRemoteFrameWsLiveOptions(payload = {}) {
+    const mode = String(payload.frameMode || payload.mode || 'remote-fast').trim() || 'remote-fast';
     return {
         fps: clampRemoteFrameWsNumber(payload.fps, 1, 24, REMOTE_FRAME_WS_DEFAULT_FPS),
         maxWidth: clampRemoteFrameWsNumber(payload.maxWidth, 320, 2560, REMOTE_FRAME_WS_DEFAULT_MAX_WIDTH),
         maxHeight: clampRemoteFrameWsNumber(payload.maxHeight, 180, 1440, REMOTE_FRAME_WS_DEFAULT_MAX_HEIGHT),
         quality: clampRemoteFrameWsNumber(payload.quality, 20, 95, REMOTE_FRAME_WS_DEFAULT_QUALITY),
-        mode: String(payload.mode || 'remote-fast').trim() || 'remote-fast'
+        mode,
+        frameMode: mode
     };
 }
 
@@ -2671,6 +2673,14 @@ function buildRemoteFrameBinaryPacket(frameEvent) {
         height: Number(frame.height || 0) || 0,
         mimeType: frameEvent.mimeType || frame.mimeType || frame.format || 'image/jpeg',
         mode: frame.mode || '',
+        frameMode: frame.frameMode || frame.mode || '',
+        frameProfile: frame.frameProfile || '',
+        encoding: frame.encoding || '',
+        codec: frame.codec || '',
+        compression: frame.compression || frame.mimeType || frame.format || '',
+        transferProtocol: frame.transferProtocol || '',
+        transferProtocolVersion: Number(frame.transferProtocolVersion || 0) || 0,
+        handshake: frame.handshake || '',
         fps: Number(frame.fps || 0) || 0,
         capturedAt: frame.capturedAt || '',
         receivedAt: frame.receivedAt || '',
@@ -3625,7 +3635,9 @@ const REMOTE_AGENT_DEFAULT_ENGINE = 'auto';
 const REMOTE_AGENT_SYNC_REPORT_LOG_REPEAT_MS = 30000;
 const REMOTE_AGENT_SYNC_REPORT_WAKE_MS = Math.max(500, Number(process.env.MINDEXEC_REMOTE_AGENT_SYNC_REPORT_WAKE_MS || 1500) || 1500);
 const REMOTE_AGENT_RACE_START_STAGGER_MS = Math.max(0, Number(process.env.MINDEXEC_REMOTE_AGENT_RACE_STAGGER_MS ?? 0) || 0);
-const REMOTE_AGENT_MAX_PARALLEL_CANDIDATES = 6;
+const REMOTE_AGENT_MAX_PARALLEL_CANDIDATES = Math.max(
+    1,
+    Math.min(6, Number(process.env.MINDEXEC_REMOTE_AGENT_MAX_PARALLEL_CANDIDATES || 1) || 1));
 const REMOTE_AGENT_RECENT_MANAGER_CACHE_TTL_MS = 30 * 24 * 60 * 60 * 1000;
 const REMOTE_AGENT_RECENT_MANAGER_CACHE_LIMIT = 64;
 const REMOTE_AGENT_RECENT_MANAGER_DEFAULT_KEY = 'default';
@@ -7397,7 +7409,7 @@ async function runRemoteRegistryFollowerOnce(trigger = 'timer') {
         }
 
         const connect = await startRemoteAgentConnection({
-            manager: target.endpointCandidates[0],
+            manager: target.endpoint,
             managerCandidates: target.endpointCandidates,
             pairToken: target.pairToken,
             leaseId: target.leaseId,