@mindexec/cli 0.2.339 → 0.2.341

package/codex-runtime.js

@@ -1,13 +1,15 @@
 import { promises as fs, readFileSync } from 'fs';
 import path from 'path';
 import os from 'os';
-import { exec, spawn } from 'child_process';
+import { exec, execFile, spawn } from 'child_process';
 import { promisify } from 'util';
 import crypto from 'crypto';
 
 const execAsync = promisify(exec);
+const execFileAsync = promisify(execFile);
 
 const PROVIDER_KIND = Object.freeze({
+    fixtureReadOnly: 'FixtureReadOnly',
     typeScriptSdk: 'TypeScriptSdk',
     appServerJsonRpc: 'AppServerJsonRpc',
     legacyExec: 'LegacyExec',
@@ -40,6 +42,8 @@ const TEMP_DIR = '.ai/codex';
 const CODEX_CONFIG_PATH = path.join(os.homedir(), '.codex', 'config.toml');
 const CODEX_SOURCE_HOME = path.join(os.homedir(), '.codex');
 const CODEX_RUNTIME_HOME_ENV = 'MINDEXEC_CODEX_HOME';
+const CODEX_PATH_ENV = 'MINDEXEC_CODEX_PATH';
+const CODEX_USE_SOURCE_HOME_ENV = 'MINDEXEC_CODEX_USE_SOURCE_HOME';
 const DEFAULT_CODEX_RUNTIME_HOME = path.join(os.homedir(), '.mindexec', 'codex-runtime');
 const CODEX_RUNTIME_CONFIG_MARKER = '# Generated by MindExec LocalBridge for isolated AI node runs.';
 const CODEX_RUNTIME_AUTH_FILES = ['auth.json'];
@@ -80,6 +84,10 @@ function normalizeProviderKind(value) {
         return '';
     }
 
+    if (normalized === 'fixture' || normalized === 'fixturereadonly' || normalized === 'fixture-readonly' || normalized === 'fixture_readonly' || normalized === 'test-fixture') {
+        return PROVIDER_KIND.fixtureReadOnly;
+    }
+
     if (normalized === 'typescriptsdk' || normalized === 'typescript-sdk' || normalized === 'type_script_sdk') {
         return PROVIDER_KIND.typeScriptSdk;
     }
@@ -99,6 +107,10 @@ function isEnabledEnv(value) {
     return /^(1|true|yes|on)$/i.test(String(value || '').trim());
 }
 
+function isFixtureProviderEnabled() {
+    return isEnabledEnv(process.env.MINDEXEC_CODEX_FIXTURE_PROVIDER);
+}
+
 function unquoteTomlKey(value) {
     const text = String(value || '').trim();
     if (text.length >= 2 && ((text.startsWith('"') && text.endsWith('"')) || (text.startsWith("'") && text.endsWith("'")))) {
@@ -109,7 +121,7 @@ function unquoteTomlKey(value) {
 }
 
 function readConfiguredMcpServerNames() {
-    if (isEnabledEnv(process.env.MINDEXEC_CODEX_INHERIT_MCP)) {
+    if (!isEnabledEnv(process.env.MINDEXEC_CODEX_DISABLE_SOURCE_MCP)) {
         return [];
     }
 
@@ -159,10 +171,23 @@ function buildCodexSdkConfigOverrides() {
 }
 
 function resolveCodexRuntimeHome() {
+    if (isEnabledEnv(process.env[CODEX_USE_SOURCE_HOME_ENV])) {
+        return CODEX_SOURCE_HOME;
+    }
+
     const configured = String(process.env[CODEX_RUNTIME_HOME_ENV] || '').trim();
     return path.resolve(configured || DEFAULT_CODEX_RUNTIME_HOME);
 }
 
+function isUsingSourceCodexHome() {
+    return path.resolve(resolveCodexRuntimeHome()).toLowerCase() === path.resolve(CODEX_SOURCE_HOME).toLowerCase();
+}
+
+function resolveCodexPathOverride() {
+    const configured = String(process.env[CODEX_PATH_ENV] || '').trim();
+    return configured ? path.resolve(configured) : null;
+}
+
 async function copyCodexRuntimeFileIfPresent(fileName, runtimeHome) {
     const source = path.join(CODEX_SOURCE_HOME, fileName);
     const target = path.join(runtimeHome, fileName);
@@ -179,8 +204,33 @@ async function copyCodexRuntimeFileIfPresent(fileName, runtimeHome) {
     }
 }
 
-async function ensureCodexRuntimeHome() {
+function buildCodexRuntimeConfig(trustedDirectory = '') {
+    const lines = [
+        CODEX_RUNTIME_CONFIG_MARKER,
+        '# User MCP server definitions are intentionally not inherited here.',
+        '# LocalBridge passes model, sandbox, and reasoning options per run.'
+    ];
+
+    const resolvedTrustedDirectory = String(trustedDirectory || '').trim()
+        ? path.resolve(trustedDirectory)
+        : '';
+    if (resolvedTrustedDirectory) {
+        lines.push(
+            '',
+            `[projects.${JSON.stringify(resolvedTrustedDirectory)}]`,
+            'trust_level = "trusted"'
+        );
+    }
+
+    return `${lines.join('\n')}\n`;
+}
+
+async function ensureCodexRuntimeHome(trustedDirectory = '') {
     const runtimeHome = resolveCodexRuntimeHome();
+    if (isUsingSourceCodexHome()) {
+        return runtimeHome;
+    }
+
     await fs.mkdir(runtimeHome, { recursive: true });
     await fs.mkdir(path.join(runtimeHome, 'sessions'), { recursive: true });
     await fs.mkdir(path.join(runtimeHome, 'generated_images'), { recursive: true });
@@ -199,11 +249,7 @@ async function ensureCodexRuntimeHome() {
     }
 
     if (shouldWriteConfig) {
-        await fs.writeFile(
-            configPath,
-            `${CODEX_RUNTIME_CONFIG_MARKER}\n# User MCP server definitions are intentionally not inherited here.\n# LocalBridge passes model, sandbox, and reasoning options per run.\n`,
-            'utf8'
-        );
+        await fs.writeFile(configPath, buildCodexRuntimeConfig(trustedDirectory), 'utf8');
     }
 
     return runtimeHome;
@@ -218,10 +264,22 @@ function buildCodexChildEnv() {
     }
 
     env.CODEX_HOME = resolveCodexRuntimeHome();
-    env.MINDEXEC_CODEX_ISOLATED_HOME = '1';
+    if (isUsingSourceCodexHome()) {
+        delete env.MINDEXEC_CODEX_ISOLATED_HOME;
+    } else {
+        env.MINDEXEC_CODEX_ISOLATED_HOME = '1';
+    }
     return env;
 }
 
+function createCodexSdkClient(sdk) {
+    return new sdk.Codex({
+        codexPathOverride: resolveCodexPathOverride(),
+        env: buildCodexChildEnv(),
+        config: buildCodexSdkConfigOverrides()
+    });
+}
+
 function appendCodexIsolationConfigArgs(args) {
     for (const name of readConfiguredMcpServerNames()) {
         args.push('--config', `mcp_servers.${name}.enabled=false`);
@@ -268,12 +326,51 @@ function normalizeApprovalPolicy(value, sandboxMode) {
     }
 
     if (normalized === 'never' && sandboxMode !== 'danger-full-access') {
-        return 'on-request';
+        return 'never';
     }
 
     return 'on-request';
 }
 
+function isPathInside(parentPath, candidatePath) {
+    const relativePath = path.relative(path.resolve(parentPath), path.resolve(candidatePath));
+    return relativePath === '' || (relativePath && !relativePath.startsWith('..') && !path.isAbsolute(relativePath));
+}
+
+function normalizeAdditionalDirectories(value, workingDirectory, sandboxMode) {
+    const resolvedWorkingDirectory = path.resolve(workingDirectory);
+    const candidates = sandboxMode === 'workspace-write'
+        ? [resolvedWorkingDirectory]
+        : [];
+
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            const raw = String(item || '').trim();
+            if (!raw) {
+                continue;
+            }
+
+            const resolved = path.resolve(path.isAbsolute(raw)
+                ? raw
+                : path.join(resolvedWorkingDirectory, raw));
+            candidates.push(resolved);
+        }
+    }
+
+    const normalized = [];
+    for (const candidate of candidates) {
+        if (!isPathInside(resolvedWorkingDirectory, candidate)) {
+            continue;
+        }
+
+        if (!normalized.includes(candidate)) {
+            normalized.push(candidate);
+        }
+    }
+
+    return normalized;
+}
+
 function normalizeOutputSchema(value) {
     if (value == null) {
         return undefined;
@@ -461,6 +558,7 @@ function buildThreadOptions(body, workingDirectory) {
     const prompt = String(body?.instruction || body?.prompt || '').trim();
     const sandboxMode = normalizeSandbox(body?.sandbox || body?.sandboxMode, body?.intent || body?.nodeKind, prompt);
     const approvalPolicy = normalizeApprovalPolicy(body?.approvalPolicy, sandboxMode);
+    const additionalDirectories = normalizeAdditionalDirectories(body?.additionalDirectories, workingDirectory, sandboxMode);
     const options = {
         workingDirectory,
         skipGitRepoCheck: true,
@@ -469,6 +567,10 @@ function buildThreadOptions(body, workingDirectory) {
         approvalPolicy
     };
 
+    if (additionalDirectories.length > 0) {
+        options.additionalDirectories = additionalDirectories;
+    }
+
     const model = String(body?.model || '').trim();
     if (model) {
         options.model = model;
@@ -492,7 +594,12 @@ function serializeThreadOptionsForStatus(options) {
         sandboxMode: API_SANDBOX_BY_SDK_VALUE[options?.sandboxMode] || options?.sandboxMode || null,
         reasoningEffort: options?.modelReasoningEffort || null,
         approvalPolicy: options?.approvalPolicy || null,
-        workingDirectory: options?.workingDirectory || null
+        workingDirectory: options?.workingDirectory || null,
+        additionalDirectories: Array.isArray(options?.additionalDirectories)
+            ? [...options.additionalDirectories]
+            : [],
+        networkAccessEnabled: options?.networkAccessEnabled === undefined ? null : Boolean(options.networkAccessEnabled),
+        webSearchMode: options?.webSearchMode || null
     };
 }
 
@@ -513,7 +620,7 @@ async function checkLegacyAvailability() {
     }
 
     try {
-        const { stdout, stderr } = await execAsync('codex --version', {
+        const { stdout, stderr } = await execFileAsync(resolveCodexPathOverride() || 'codex', ['--version'], {
             timeout: 6000,
             windowsHide: true,
             maxBuffer: 512 * 1024
@@ -559,12 +666,22 @@ export function createCodexRuntime(options) {
     const activeTurns = new Map();
 
     async function getCapabilities() {
+        const fixtureEnabled = isFixtureProviderEnabled();
         const [sdk, legacy, modelCatalog] = await Promise.all([
             checkSdkAvailability(packageRoot),
             checkLegacyAvailability(),
             getModelCatalog()
         ]);
-        const preferredProviderKind = sdk.available
+        const fixture = {
+            kind: PROVIDER_KIND.fixtureReadOnly,
+            available: fixtureEnabled,
+            implemented: true,
+            version: fixtureEnabled ? 'local-smoke' : null,
+            error: fixtureEnabled ? null : 'Enable MINDEXEC_CODEX_FIXTURE_PROVIDER=1 for local contract smokes only.'
+        };
+        const preferredProviderKind = fixtureEnabled
+            ? PROVIDER_KIND.fixtureReadOnly
+            : sdk.available
             ? PROVIDER_KIND.typeScriptSdk
             : legacy.available
                 ? PROVIDER_KIND.legacyExec
@@ -574,6 +691,7 @@ export function createCodexRuntime(options) {
             success: preferredProviderKind !== PROVIDER_KIND.unavailable,
             preferredProviderKind,
             providers: [
+                fixture,
                 sdk,
                 {
                     kind: PROVIDER_KIND.appServerJsonRpc,
@@ -602,6 +720,13 @@ export function createCodexRuntime(options) {
 
     async function resolveProvider(requestedProviderKind) {
         const requested = normalizeProviderKind(requestedProviderKind);
+        if (isFixtureProviderEnabled() && (!requested || requested === PROVIDER_KIND.fixtureReadOnly)) {
+            return PROVIDER_KIND.fixtureReadOnly;
+        }
+        if (requested === PROVIDER_KIND.fixtureReadOnly) {
+            return PROVIDER_KIND.unavailable;
+        }
+
         const sdk = await checkSdkAvailability(packageRoot);
         const legacy = requested === PROVIDER_KIND.typeScriptSdk
             ? null
@@ -629,13 +754,32 @@ export function createCodexRuntime(options) {
         const threadOptions = buildThreadOptions(body, workingDirectory);
         const now = new Date().toISOString();
 
+        if (providerKind === PROVIDER_KIND.fixtureReadOnly) {
+            const localThreadId = `fixture_${crypto.randomUUID()}`;
+            threads.set(localThreadId, {
+                providerKind,
+                createdAtUtc: now,
+                updatedAtUtc: now,
+                options: threadOptions,
+                officialThreadId: localThreadId,
+                lastStatus: 'created'
+            });
+
+            return makeEmptyResult({
+                success: true,
+                providerKind,
+                threadId: localThreadId,
+                status: 'created',
+                startedAtUtc: now,
+                completedAtUtc: now,
+                sandboxMode: API_SANDBOX_BY_SDK_VALUE[threadOptions.sandboxMode] || threadOptions.sandboxMode
+            });
+        }
+
         if (providerKind === PROVIDER_KIND.typeScriptSdk) {
             const sdk = await loadCodexSdk();
-            await ensureCodexRuntimeHome();
-            const codex = new sdk.Codex({
-                env: buildCodexChildEnv(),
-                config: buildCodexSdkConfigOverrides()
-            });
+            await ensureCodexRuntimeHome(workingDirectory);
+            const codex = createCodexSdkClient(sdk);
             const thread = codex.startThread(threadOptions);
             const localThreadId = `local_${crypto.randomUUID()}`;
             threads.set(localThreadId, {
@@ -697,11 +841,8 @@ export function createCodexRuntime(options) {
         }
 
         const sdk = await loadCodexSdk();
-        await ensureCodexRuntimeHome();
-        const codex = new sdk.Codex({
-            env: buildCodexChildEnv(),
-            config: buildCodexSdkConfigOverrides()
-        });
+        await ensureCodexRuntimeHome(threadOptions?.workingDirectory);
+        const codex = createCodexSdkClient(sdk);
         const officialId = requestedThreadId && !requestedThreadId.startsWith('local_')
             ? requestedThreadId
             : '';
@@ -825,6 +966,72 @@ export function createCodexRuntime(options) {
         return result;
     }
 
+    async function runFixtureThread(body, workingDirectory, prompt, startedAtUtc) {
+        const threadOptions = buildThreadOptions(body, workingDirectory);
+        const threadId = String(body.threadId || `fixture_${crypto.randomUUID()}`);
+        const turnId = `turn_${crypto.randomUUID()}`;
+        const sandboxMode = API_SANDBOX_BY_SDK_VALUE[threadOptions.sandboxMode] || threadOptions.sandboxMode;
+        const violations = [];
+
+        if (sandboxMode !== 'read_only') {
+            violations.push(`sandbox=${sandboxMode || 'missing'}`);
+        }
+        if (threadOptions.webSearchMode !== 'disabled') {
+            violations.push(`webSearchMode=${threadOptions.webSearchMode || 'missing'}`);
+        }
+        if (threadOptions.networkAccessEnabled !== false) {
+            violations.push(`networkAccessEnabled=${String(threadOptions.networkAccessEnabled)}`);
+        }
+        if (threadOptions.approvalPolicy !== 'on-request') {
+            violations.push(`approvalPolicy=${threadOptions.approvalPolicy || 'missing'}`);
+        }
+
+        const result = makeEmptyResult({
+            providerKind: PROVIDER_KIND.fixtureReadOnly,
+            threadId,
+            turnId,
+            status: violations.length > 0 ? 'failed' : 'completed',
+            startedAtUtc,
+            completedAtUtc: new Date().toISOString(),
+            sandboxMode,
+            rawEventCount: 1
+        });
+
+        if (violations.length > 0) {
+            result.error = `FixtureReadOnly refused unsafe Codex request: ${violations.join(', ')}`;
+            result.summary = 'The local fixture provider blocks non-read-only CodeMaster execution contracts.';
+        } else {
+            result.success = true;
+            result.summary = 'FixtureReadOnly validated the CodeMaster LocalBridge Codex handoff.';
+            result.finalResponse = [
+                'LocalBridge Codex fixture completed a read-only CodeMaster run.',
+                `Sandbox=${sandboxMode}; approval=${threadOptions.approvalPolicy}; networkAccess=${threadOptions.networkAccessEnabled}; webSearch=${threadOptions.webSearchMode}.`,
+                `WorkingDirectory=${workingDirectory}.`,
+                `InstructionChars=${prompt.length}; changedFiles=0; commandLogs=0.`
+            ].join('\n');
+        }
+
+        threads.set(threadId, {
+            providerKind: PROVIDER_KIND.fixtureReadOnly,
+            createdAtUtc: startedAtUtc,
+            updatedAtUtc: result.completedAtUtc,
+            options: threadOptions,
+            officialThreadId: threadId,
+            lastStatus: result.status,
+            lastResult: result
+        });
+
+        log('Codex fixture run complete', {
+            threadId,
+            turnId,
+            sandbox: sandboxMode,
+            cwd: workingDirectory,
+            success: result.success
+        });
+
+        return result;
+    }
+
     async function runLegacyExec(body, workingDirectory, prompt, startedAtUtc) {
         const threadOptions = buildThreadOptions(body, workingDirectory);
         const turnId = `turn_${crypto.randomUUID()}`;
@@ -842,7 +1049,7 @@ export function createCodexRuntime(options) {
         const tempDir = path.join(workingDirectory, TEMP_DIR);
         const schema = normalizeOutputSchema(body.outputSchema || body.outputSchemaJson);
         let schemaPath = null;
-        await ensureCodexRuntimeHome();
+        await ensureCodexRuntimeHome(workingDirectory);
         const args = [
             'exec',
             '-',
@@ -852,10 +1059,14 @@ export function createCodexRuntime(options) {
             'plugins',
             '--disable',
             'shell_snapshot',
+            '--cd',
+            workingDirectory,
             '-s',
             threadOptions.sandboxMode,
             '--config',
-            `model_reasoning_effort=${threadOptions.modelReasoningEffort}`
+            `model_reasoning_effort=${threadOptions.modelReasoningEffort}`,
+            '--config',
+            `approval_policy="${threadOptions.approvalPolicy}"`
         ];
         appendCodexIsolationConfigArgs(args);
 
@@ -863,6 +1074,18 @@ export function createCodexRuntime(options) {
             args.push('-m', threadOptions.model);
         }
 
+        for (const directory of threadOptions.additionalDirectories || []) {
+            args.push('--add-dir', directory);
+        }
+
+        if (threadOptions.networkAccessEnabled !== undefined) {
+            args.push('--config', `sandbox_workspace_write.network_access=${Boolean(threadOptions.networkAccessEnabled)}`);
+        }
+
+        if (threadOptions.webSearchMode) {
+            args.push('--config', `web_search="${threadOptions.webSearchMode}"`);
+        }
+
         if (schema) {
             await fs.mkdir(tempDir, { recursive: true });
             schemaPath = path.join(tempDir, `${crypto.randomUUID()}.schema.json`);
@@ -882,7 +1105,7 @@ export function createCodexRuntime(options) {
 
         try {
             const childResult = await new Promise((resolve) => {
-                const child = spawn('codex', args, {
+                const child = spawn(resolveCodexPathOverride() || 'codex', args, {
                     cwd: workingDirectory,
                     env: buildCodexChildEnv(),
                     windowsHide: true,
@@ -972,6 +1195,10 @@ export function createCodexRuntime(options) {
         const workingDirectory = await resolveWorkingDirectory(body.workingDir || body.workingDirectory || '');
         const providerKind = await resolveProvider(body.providerKind || body.runtime);
 
+        if (providerKind === PROVIDER_KIND.fixtureReadOnly) {
+            return runFixtureThread(body, workingDirectory, prompt, startedAtUtc);
+        }
+
         if (providerKind === PROVIDER_KIND.typeScriptSdk) {
             return runSdkThread(body, workingDirectory, prompt, startedAtUtc);
         }
@@ -1014,11 +1241,8 @@ export function createCodexRuntime(options) {
             const workingDirectory = await resolveWorkingDirectory(body.workingDir || body.workingDirectory || '');
             const threadOptions = buildThreadOptions(body, workingDirectory);
             const sdk = await loadCodexSdk();
-            await ensureCodexRuntimeHome();
-            const codex = new sdk.Codex({
-                env: buildCodexChildEnv(),
-                config: buildCodexSdkConfigOverrides()
-            });
+            await ensureCodexRuntimeHome(workingDirectory);
+            const codex = createCodexSdkClient(sdk);
             const thread = codex.resumeThread(threadId, threadOptions);
             threads.set(threadId, {
                 providerKind,

package/package.json

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

package/remote-hub.js

@@ -1925,6 +1925,54 @@ export function createRemoteHub(options = {}) {
             : 0;
     }
 
+    function readFrameDroppedByAgent(message) {
+        const value = Number(message.droppedByAgent ?? message.agentDrops ?? message.drops);
+        return Number.isFinite(value) && value >= 0
+            ? Math.round(value)
+            : 0;
+    }
+
+    function readFrameDirtyRectCount(message) {
+        if (Array.isArray(message.dirtyRects)) {
+            return message.dirtyRects.length;
+        }
+
+        const value = Number(message.dirtyRectCount ?? message.dirtyRegionCount ?? message.changedRegionCount);
+        return Number.isFinite(value) && value >= 0
+            ? Math.round(value)
+            : 0;
+    }
+
+    function readFrameDirtyPixelRatio(message) {
+        const value = Number(message.dirtyPixelRatio ?? message.dirtyRatio ?? message.dirtyAreaRatio ?? message.changedPixelRatio);
+        if (!Number.isFinite(value) || value < 0) {
+            return 0;
+        }
+
+        if (value <= 1) {
+            return value;
+        }
+
+        if (value <= 100) {
+            return value / 100;
+        }
+
+        return 1;
+    }
+
+    function readFrameDeltaEncoded(message) {
+        const value = message.deltaEncoded ?? message.isDeltaEncoded ?? message.deltaFrame;
+        if (typeof value === 'boolean') {
+            return value;
+        }
+
+        if (typeof value === 'number') {
+            return value > 0;
+        }
+
+        return /^(1|true|yes|on|delta)$/i.test(String(value || '').trim());
+    }
+
     function computeSameContentStreak(previousFrame, contentHash) {
         if (!contentHash || !previousFrame?.contentHash || previousFrame.contentHash !== contentHash) {
             return 0;
@@ -1956,6 +2004,11 @@ export function createRemoteHub(options = {}) {
         const payload = buildFramePayloadBuffer(framePayload, frameData);
         const contentHash = buildFrameContentHash(message, payload);
         const sameContentStreak = computeSameContentStreak(device.latestThumbnail, contentHash);
+        const droppedByAgent = readFrameDroppedByAgent(message);
+        const dirtyRectCount = readFrameDirtyRectCount(message);
+        const dirtyPixelRatio = readFrameDirtyPixelRatio(message);
+        const codec = safeString(message.codec || message.encoder || message.encoding, 80);
+        const deltaEncoded = readFrameDeltaEncoded(message);
         device.latestThumbnail = {
             streamId: safeString(message.streamId, 128) || 'thumbnail',
             frameSeq,
@@ -1971,6 +2024,11 @@ export function createRemoteHub(options = {}) {
             contentHash,
             captureMs: readFrameCaptureMs(message),
             sameContentStreak,
+            droppedByAgent,
+            dirtyRectCount,
+            dirtyPixelRatio,
+            codec,
+            deltaEncoded,
             payload,
             accessToken: createFrameAccessToken()
         };
@@ -1983,7 +2041,12 @@ export function createRemoteHub(options = {}) {
             height: device.latestThumbnail.height,
             transport,
             contentHash,
-            sameContentStreak
+            sameContentStreak,
+            droppedByAgent,
+            dirtyRectCount,
+            dirtyPixelRatio,
+            codec,
+            deltaEncoded
         });
         return true;
     }
@@ -2024,6 +2087,11 @@ export function createRemoteHub(options = {}) {
         const payload = buildFramePayloadBuffer(framePayload, frameData);
         const contentHash = buildFrameContentHash(message, payload);
         const sameContentStreak = computeSameContentStreak(device.latestLiveFrame, contentHash);
+        const droppedByAgent = readFrameDroppedByAgent(message);
+        const dirtyRectCount = readFrameDirtyRectCount(message);
+        const dirtyPixelRatio = readFrameDirtyPixelRatio(message);
+        const codec = safeString(message.codec || message.encoder || message.encoding, 80);
+        const deltaEncoded = readFrameDeltaEncoded(message);
         device.latestLiveFrame = {
             streamId,
             frameSeq,
@@ -2041,6 +2109,11 @@ export function createRemoteHub(options = {}) {
             contentHash,
             captureMs: readFrameCaptureMs(message),
             sameContentStreak,
+            droppedByAgent,
+            dirtyRectCount,
+            dirtyPixelRatio,
+            codec,
+            deltaEncoded,
             payload,
             accessToken: createFrameAccessToken()
         };
@@ -2065,7 +2138,12 @@ export function createRemoteHub(options = {}) {
             mode: device.latestLiveFrame.mode,
             transport,
             contentHash,
-            sameContentStreak
+            sameContentStreak,
+            droppedByAgent,
+            dirtyRectCount,
+            dirtyPixelRatio,
+            codec,
+            deltaEncoded
         });
         return true;
     }

package/scripts/remote-fast-live-rate-smoke.mjs

@@ -16,6 +16,8 @@ const LOCAL_BRIDGE_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url
 const REQUESTED_FPS = Number(process.env.MINDEXEC_REMOTE_LIVE_RATE_REQUEST_FPS || 12);
 const SAMPLE_MS = Number(process.env.MINDEXEC_REMOTE_LIVE_RATE_SAMPLE_MS || 3500);
 const MIN_EFFECTIVE_FPS = Number(process.env.MINDEXEC_REMOTE_LIVE_RATE_MIN_FPS || 10);
+const MAX_DROP_RATIO = Number(process.env.MINDEXEC_REMOTE_LIVE_RATE_MAX_DROP_RATIO || 0.2);
+const MAX_SEQ_GAP = Number(process.env.MINDEXEC_REMOTE_LIVE_RATE_MAX_SEQ_GAP || 4);
 
 function wait(ms) {
     return new Promise(resolve => setTimeout(resolve, ms));
@@ -216,14 +218,26 @@ function summarizeFrames(frames) {
     const fps = frames.length > 1 ? ((frames.length - 1) * 1000) / durationMs : 0;
     const seqs = frames.map(frame => Number(frame.metadata.frameSeq || 0)).filter(Number.isFinite);
     const uniqueSeqs = new Set(seqs);
+    const firstSeq = seqs[0] || 0;
+    const lastSeq = seqs[seqs.length - 1] || 0;
+    const expectedSeqs = lastSeq >= firstSeq ? lastSeq - firstSeq + 1 : uniqueSeqs.size;
+    const droppedSeqs = Math.max(0, expectedSeqs - uniqueSeqs.size);
+    let maxSeqGap = 0;
+    for (let index = 1; index < seqs.length; index += 1) {
+        maxSeqGap = Math.max(maxSeqGap, Math.max(0, seqs[index] - seqs[index - 1] - 1));
+    }
     const byteLengths = frames.map(frame => Number(frame.payload?.length || 0)).filter(value => value > 0);
     return {
         frames: frames.length,
         uniqueSeqs: uniqueSeqs.size,
+        expectedSeqs,
+        droppedSeqs,
+        dropRatio: expectedSeqs > 0 ? droppedSeqs / expectedSeqs : 0,
+        maxSeqGap,
         durationMs,
         fps,
-        firstSeq: seqs[0] || 0,
-        lastSeq: seqs[seqs.length - 1] || 0,
+        firstSeq,
+        lastSeq,
         minBytes: byteLengths.length > 0 ? Math.min(...byteLengths) : 0,
         maxBytes: byteLengths.length > 0 ? Math.max(...byteLengths) : 0,
         metadataFps: Number(last?.metadata?.fps || 0) || 0,
@@ -320,8 +334,10 @@ async function main() {
         assert.equal(summary.metadataFps, REQUESTED_FPS, JSON.stringify(summary));
         assert.equal(summary.mode, 'remote-fast', JSON.stringify(summary));
         assert.ok(summary.fps >= MIN_EFFECTIVE_FPS, `RemoteFast live-rate too low: ${JSON.stringify(summary)}`);
+        assert.ok(summary.dropRatio <= MAX_DROP_RATIO, `RemoteFast live-rate dropped too many frame sequences: ${JSON.stringify(summary)}`);
+        assert.ok(summary.maxSeqGap <= MAX_SEQ_GAP, `RemoteFast live-rate sequence gap too large: ${JSON.stringify(summary)}`);
 
-        console.log(`RemoteFast live-rate smoke OK (${summary.frames} frames, ${summary.fps.toFixed(1)} fps, bytes ${summary.minBytes}-${summary.maxBytes})`);
+        console.log(`RemoteFast live-rate smoke OK (${summary.frames} frames, ${summary.fps.toFixed(1)} fps, drop ${(summary.dropRatio * 100).toFixed(1)}%, max gap ${summary.maxSeqGap}, bytes ${summary.minBytes}-${summary.maxBytes})`);
     } finally {
         if (ws && ws.readyState === WebSocket.OPEN) {
             ws.close();