@midscene/android 1.5.3-beta-20260309062917.0 → 1.5.3

package/dist/es/cli.mjs

@@ -8,6 +8,7 @@ import { BaseMidsceneTools } from "@midscene/shared/mcp";
 import { Agent } from "@midscene/core/agent";
 import { mergeAndNormalizeAppNameMapping, normalizeForComparison, repeat } from "@midscene/shared/utils";
 import node_assert from "node:assert";
+import { execFile } from "node:child_process";
 import { defineAction, defineActionClearInput, defineActionCursorMove, defineActionDoubleClick, defineActionDragAndDrop, defineActionKeyboardPress, defineActionScroll, defineActionSwipe, defineActionTap, normalizeMobileSwipeParam } from "@midscene/core/device";
 import { getTmpFile, sleep } from "@midscene/core/utils";
 import { MIDSCENE_ADB_PATH, MIDSCENE_ADB_REMOTE_HOST, MIDSCENE_ADB_REMOTE_PORT, MIDSCENE_ANDROID_IME_STRATEGY, globalConfigManager } from "@midscene/shared/env";
@@ -50,6 +51,10 @@ var __webpack_modules__ = {
         const KEYFRAME_POLL_INTERVAL_MS = 200;
         const MAX_SCAN_BYTES = 1000;
         const CONNECTION_WAIT_MS = 1000;
+        const BUSY_LOOP_WINDOW_MS = 1000;
+        const BUSY_LOOP_MAX_READS = 500;
+        const BUSY_LOOP_COOLDOWN_MS = 50;
+        const BUSY_LOOP_WARN_INTERVAL_MS = 5000;
         const DEFAULT_SCRCPY_CONFIG = {
             enabled: false,
             maxSize: DEFAULT_MAX_SIZE,
@@ -147,16 +152,37 @@ var __webpack_modules__ = {
                 this.consumeFramesLoop(reader);
             }
             async consumeFramesLoop(reader) {
+                let readCount = 0;
+                let windowStart = Date.now();
+                let lastBusyWarn = 0;
+                let totalReads = 0;
                 try {
                     while(true){
                         const { done, value } = await reader.read();
                         if (done) break;
+                        totalReads++;
+                        readCount++;
+                        const now = Date.now();
+                        const elapsed = now - windowStart;
+                        if (elapsed >= BUSY_LOOP_WINDOW_MS) {
+                            const readsPerSec = readCount / elapsed * 1000;
+                            if (readCount > BUSY_LOOP_MAX_READS) {
+                                if (now - lastBusyWarn >= BUSY_LOOP_WARN_INTERVAL_MS) {
+                                    warnScrcpy(`[CPU-DIAG] Possible busy loop detected! ${readCount} reads in ${elapsed}ms (${readsPerSec.toFixed(0)} reads/sec). Total reads: ${totalReads}. Throttling with ${BUSY_LOOP_COOLDOWN_MS}ms delay.`);
+                                    lastBusyWarn = now;
+                                }
+                                await new Promise((resolve)=>setTimeout(resolve, BUSY_LOOP_COOLDOWN_MS));
+                            } else debugScrcpy(`[CPU-DIAG] Frame loop stats: ${readCount} reads in ${elapsed}ms (${readsPerSec.toFixed(1)} reads/sec), total: ${totalReads}`);
+                            readCount = 0;
+                            windowStart = Date.now();
+                        }
                         this.processFrame(value);
                     }
                 } catch (error) {
-                    debugScrcpy(`Frame consumer error: ${error}`);
+                    debugScrcpy(`Frame consumer error (total reads: ${totalReads}): ${error}`);
                     await this.disconnect();
                 }
+                debugScrcpy(`Frame consumer loop ended normally (total reads: ${totalReads})`);
             }
             processFrame(packet) {
                 if ('configuration' === packet.type) {
@@ -1171,14 +1197,23 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         const androidScreenshotPath = `/data/local/tmp/ms_${screenshotId}.png`;
         const useShellScreencap = 'number' == typeof this.options?.displayId;
         try {
-            if (useShellScreencap) throw new Error('Using shell screencap for displayId');
-            debugDevice('Taking screenshot via adb.takeScreenshot');
-            screenshotBuffer = await adb.takeScreenshot(null);
-            debugDevice('adb.takeScreenshot completed');
-            if (!screenshotBuffer) throw new Error('Failed to capture screenshot: screenshotBuffer is null');
-            if (!isValidImageBuffer(screenshotBuffer)) {
-                debugDevice('Invalid image buffer detected: not a valid image format');
-                throw new Error('Screenshot buffer has invalid format: could not find valid image signature');
+            if (!useShellScreencap && this.takeScreenshotFailCount < AndroidDevice.TAKE_SCREENSHOT_FAIL_THRESHOLD) {
+                debugDevice('Taking screenshot via adb.takeScreenshot');
+                screenshotBuffer = await adb.takeScreenshot(null);
+                debugDevice('adb.takeScreenshot completed');
+                if (!screenshotBuffer) {
+                    this.takeScreenshotFailCount++;
+                    throw new Error('Failed to capture screenshot: screenshotBuffer is null');
+                }
+                if (!isValidImageBuffer(screenshotBuffer)) {
+                    debugDevice('Invalid image buffer detected: not a valid image format');
+                    this.takeScreenshotFailCount++;
+                    throw new Error('Screenshot buffer has invalid format: could not find valid image signature');
+                }
+                this.takeScreenshotFailCount = 0;
+            } else {
+                if (this.takeScreenshotFailCount >= AndroidDevice.TAKE_SCREENSHOT_FAIL_THRESHOLD) debugDevice('Skipping takeScreenshot (failed %d consecutive times), using shell screencap directly', this.takeScreenshotFailCount);
+                throw new Error('Using shell screencap directly');
             }
             const validScreenshotBufferSize = this.options?.minScreenshotBufferSize ?? 10240;
             if (validScreenshotBufferSize > 0 && screenshotBuffer.length < validScreenshotBufferSize) {
@@ -1210,9 +1245,18 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
                 if (!isValidImageBuffer(screenshotBuffer)) throw new Error('Fallback screenshot buffer has invalid PNG format');
                 debugDevice(`Fallback screenshot validated successfully: ${screenshotBuffer.length} bytes`);
             } finally{
-                Promise.resolve().then(()=>adb.shell(`rm ${androidScreenshotPath}`)).catch((error)=>{
-                    debugDevice(`Failed to delete remote screenshot: ${error}`);
+                const adbPath = adb.executable?.path ?? 'adb';
+                const child = execFile(adbPath, [
+                    '-s',
+                    this.deviceId,
+                    'shell',
+                    `rm ${androidScreenshotPath}`
+                ], {
+                    timeout: 3000
+                }, (err)=>{
+                    if (err) debugDevice('Failed to delete remote screenshot: %s', err.message);
                 });
+                child.unref();
             }
         }
         if (!screenshotBuffer) throw new Error('Failed to capture screenshot: all methods failed');
@@ -1656,6 +1700,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         device_define_property(this, "scrcpyAdapter", null);
         device_define_property(this, "appNameMapping", {});
         device_define_property(this, "cachedAdjustScale", null);
+        device_define_property(this, "takeScreenshotFailCount", 0);
         device_define_property(this, "interfaceType", 'android');
         device_define_property(this, "uri", void 0);
         device_define_property(this, "options", void 0);
@@ -1665,6 +1710,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         this.customActions = options?.customActions;
     }
 }
+device_define_property(AndroidDevice, "TAKE_SCREENSHOT_FAIL_THRESHOLD", 3);
 const runAdbShellParamSchema = z.object({
     command: z.string().describe('ADB shell command to execute')
 });

package/dist/es/index.mjs

@@ -3,6 +3,7 @@ import * as __rspack_external_node_fs_5ea92f0c from "node:fs";
 import * as __rspack_external_node_module_ab9f2194 from "node:module";
 import * as __rspack_external_node_path_c5b9b54f from "node:path";
 import node_assert from "node:assert";
+import { execFile } from "node:child_process";
 import { getMidsceneLocationSchema, z } from "@midscene/core";
 import { defineAction, defineActionClearInput, defineActionCursorMove, defineActionDoubleClick, defineActionDragAndDrop, defineActionKeyboardPress, defineActionScroll, defineActionSwipe, defineActionTap, normalizeMobileSwipeParam } from "@midscene/core/device";
 import { getTmpFile, sleep } from "@midscene/core/utils";
@@ -48,6 +49,10 @@ var __webpack_modules__ = {
         const KEYFRAME_POLL_INTERVAL_MS = 200;
         const MAX_SCAN_BYTES = 1000;
         const CONNECTION_WAIT_MS = 1000;
+        const BUSY_LOOP_WINDOW_MS = 1000;
+        const BUSY_LOOP_MAX_READS = 500;
+        const BUSY_LOOP_COOLDOWN_MS = 50;
+        const BUSY_LOOP_WARN_INTERVAL_MS = 5000;
         const DEFAULT_SCRCPY_CONFIG = {
             enabled: false,
             maxSize: DEFAULT_MAX_SIZE,
@@ -145,16 +150,37 @@ var __webpack_modules__ = {
                 this.consumeFramesLoop(reader);
             }
             async consumeFramesLoop(reader) {
+                let readCount = 0;
+                let windowStart = Date.now();
+                let lastBusyWarn = 0;
+                let totalReads = 0;
                 try {
                     while(true){
                         const { done, value } = await reader.read();
                         if (done) break;
+                        totalReads++;
+                        readCount++;
+                        const now = Date.now();
+                        const elapsed = now - windowStart;
+                        if (elapsed >= BUSY_LOOP_WINDOW_MS) {
+                            const readsPerSec = readCount / elapsed * 1000;
+                            if (readCount > BUSY_LOOP_MAX_READS) {
+                                if (now - lastBusyWarn >= BUSY_LOOP_WARN_INTERVAL_MS) {
+                                    warnScrcpy(`[CPU-DIAG] Possible busy loop detected! ${readCount} reads in ${elapsed}ms (${readsPerSec.toFixed(0)} reads/sec). Total reads: ${totalReads}. Throttling with ${BUSY_LOOP_COOLDOWN_MS}ms delay.`);
+                                    lastBusyWarn = now;
+                                }
+                                await new Promise((resolve)=>setTimeout(resolve, BUSY_LOOP_COOLDOWN_MS));
+                            } else debugScrcpy(`[CPU-DIAG] Frame loop stats: ${readCount} reads in ${elapsed}ms (${readsPerSec.toFixed(1)} reads/sec), total: ${totalReads}`);
+                            readCount = 0;
+                            windowStart = Date.now();
+                        }
                         this.processFrame(value);
                     }
                 } catch (error) {
-                    debugScrcpy(`Frame consumer error: ${error}`);
+                    debugScrcpy(`Frame consumer error (total reads: ${totalReads}): ${error}`);
                     await this.disconnect();
                 }
+                debugScrcpy(`Frame consumer loop ended normally (total reads: ${totalReads})`);
             }
             processFrame(packet) {
                 if ('configuration' === packet.type) {
@@ -1073,14 +1099,23 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         const androidScreenshotPath = `/data/local/tmp/ms_${screenshotId}.png`;
         const useShellScreencap = 'number' == typeof this.options?.displayId;
         try {
-            if (useShellScreencap) throw new Error('Using shell screencap for displayId');
-            debugDevice('Taking screenshot via adb.takeScreenshot');
-            screenshotBuffer = await adb.takeScreenshot(null);
-            debugDevice('adb.takeScreenshot completed');
-            if (!screenshotBuffer) throw new Error('Failed to capture screenshot: screenshotBuffer is null');
-            if (!isValidImageBuffer(screenshotBuffer)) {
-                debugDevice('Invalid image buffer detected: not a valid image format');
-                throw new Error('Screenshot buffer has invalid format: could not find valid image signature');
+            if (!useShellScreencap && this.takeScreenshotFailCount < AndroidDevice.TAKE_SCREENSHOT_FAIL_THRESHOLD) {
+                debugDevice('Taking screenshot via adb.takeScreenshot');
+                screenshotBuffer = await adb.takeScreenshot(null);
+                debugDevice('adb.takeScreenshot completed');
+                if (!screenshotBuffer) {
+                    this.takeScreenshotFailCount++;
+                    throw new Error('Failed to capture screenshot: screenshotBuffer is null');
+                }
+                if (!isValidImageBuffer(screenshotBuffer)) {
+                    debugDevice('Invalid image buffer detected: not a valid image format');
+                    this.takeScreenshotFailCount++;
+                    throw new Error('Screenshot buffer has invalid format: could not find valid image signature');
+                }
+                this.takeScreenshotFailCount = 0;
+            } else {
+                if (this.takeScreenshotFailCount >= AndroidDevice.TAKE_SCREENSHOT_FAIL_THRESHOLD) debugDevice('Skipping takeScreenshot (failed %d consecutive times), using shell screencap directly', this.takeScreenshotFailCount);
+                throw new Error('Using shell screencap directly');
             }
             const validScreenshotBufferSize = this.options?.minScreenshotBufferSize ?? 10240;
             if (validScreenshotBufferSize > 0 && screenshotBuffer.length < validScreenshotBufferSize) {
@@ -1112,9 +1147,18 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
                 if (!isValidImageBuffer(screenshotBuffer)) throw new Error('Fallback screenshot buffer has invalid PNG format');
                 debugDevice(`Fallback screenshot validated successfully: ${screenshotBuffer.length} bytes`);
             } finally{
-                Promise.resolve().then(()=>adb.shell(`rm ${androidScreenshotPath}`)).catch((error)=>{
-                    debugDevice(`Failed to delete remote screenshot: ${error}`);
+                const adbPath = adb.executable?.path ?? 'adb';
+                const child = execFile(adbPath, [
+                    '-s',
+                    this.deviceId,
+                    'shell',
+                    `rm ${androidScreenshotPath}`
+                ], {
+                    timeout: 3000
+                }, (err)=>{
+                    if (err) debugDevice('Failed to delete remote screenshot: %s', err.message);
                 });
+                child.unref();
             }
         }
         if (!screenshotBuffer) throw new Error('Failed to capture screenshot: all methods failed');
@@ -1558,6 +1602,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         device_define_property(this, "scrcpyAdapter", null);
         device_define_property(this, "appNameMapping", {});
         device_define_property(this, "cachedAdjustScale", null);
+        device_define_property(this, "takeScreenshotFailCount", 0);
         device_define_property(this, "interfaceType", 'android');
         device_define_property(this, "uri", void 0);
         device_define_property(this, "options", void 0);
@@ -1567,6 +1612,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         this.customActions = options?.customActions;
     }
 }
+device_define_property(AndroidDevice, "TAKE_SCREENSHOT_FAIL_THRESHOLD", 3);
 const runAdbShellParamSchema = z.object({
     command: z.string().describe('ADB shell command to execute')
 });

package/dist/es/mcp-server.mjs

@@ -6,6 +6,7 @@ import { BaseMCPServer, BaseMidsceneTools, createMCPServerLauncher } from "@mids
 import { Agent } from "@midscene/core/agent";
 import { mergeAndNormalizeAppNameMapping, normalizeForComparison, repeat } from "@midscene/shared/utils";
 import node_assert from "node:assert";
+import { execFile } from "node:child_process";
 import { getMidsceneLocationSchema, z } from "@midscene/core";
 import { defineAction, defineActionClearInput, defineActionCursorMove, defineActionDoubleClick, defineActionDragAndDrop, defineActionKeyboardPress, defineActionScroll, defineActionSwipe, defineActionTap, normalizeMobileSwipeParam } from "@midscene/core/device";
 import { getTmpFile, sleep } from "@midscene/core/utils";
@@ -49,6 +50,10 @@ var __webpack_modules__ = {
         const KEYFRAME_POLL_INTERVAL_MS = 200;
         const MAX_SCAN_BYTES = 1000;
         const CONNECTION_WAIT_MS = 1000;
+        const BUSY_LOOP_WINDOW_MS = 1000;
+        const BUSY_LOOP_MAX_READS = 500;
+        const BUSY_LOOP_COOLDOWN_MS = 50;
+        const BUSY_LOOP_WARN_INTERVAL_MS = 5000;
         const DEFAULT_SCRCPY_CONFIG = {
             enabled: false,
             maxSize: DEFAULT_MAX_SIZE,
@@ -146,16 +151,37 @@ var __webpack_modules__ = {
                 this.consumeFramesLoop(reader);
             }
             async consumeFramesLoop(reader) {
+                let readCount = 0;
+                let windowStart = Date.now();
+                let lastBusyWarn = 0;
+                let totalReads = 0;
                 try {
                     while(true){
                         const { done, value } = await reader.read();
                         if (done) break;
+                        totalReads++;
+                        readCount++;
+                        const now = Date.now();
+                        const elapsed = now - windowStart;
+                        if (elapsed >= BUSY_LOOP_WINDOW_MS) {
+                            const readsPerSec = readCount / elapsed * 1000;
+                            if (readCount > BUSY_LOOP_MAX_READS) {
+                                if (now - lastBusyWarn >= BUSY_LOOP_WARN_INTERVAL_MS) {
+                                    warnScrcpy(`[CPU-DIAG] Possible busy loop detected! ${readCount} reads in ${elapsed}ms (${readsPerSec.toFixed(0)} reads/sec). Total reads: ${totalReads}. Throttling with ${BUSY_LOOP_COOLDOWN_MS}ms delay.`);
+                                    lastBusyWarn = now;
+                                }
+                                await new Promise((resolve)=>setTimeout(resolve, BUSY_LOOP_COOLDOWN_MS));
+                            } else debugScrcpy(`[CPU-DIAG] Frame loop stats: ${readCount} reads in ${elapsed}ms (${readsPerSec.toFixed(1)} reads/sec), total: ${totalReads}`);
+                            readCount = 0;
+                            windowStart = Date.now();
+                        }
                         this.processFrame(value);
                     }
                 } catch (error) {
-                    debugScrcpy(`Frame consumer error: ${error}`);
+                    debugScrcpy(`Frame consumer error (total reads: ${totalReads}): ${error}`);
                     await this.disconnect();
                 }
+                debugScrcpy(`Frame consumer loop ended normally (total reads: ${totalReads})`);
             }
             processFrame(packet) {
                 if ('configuration' === packet.type) {
@@ -1170,14 +1196,23 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         const androidScreenshotPath = `/data/local/tmp/ms_${screenshotId}.png`;
         const useShellScreencap = 'number' == typeof this.options?.displayId;
         try {
-            if (useShellScreencap) throw new Error('Using shell screencap for displayId');
-            debugDevice('Taking screenshot via adb.takeScreenshot');
-            screenshotBuffer = await adb.takeScreenshot(null);
-            debugDevice('adb.takeScreenshot completed');
-            if (!screenshotBuffer) throw new Error('Failed to capture screenshot: screenshotBuffer is null');
-            if (!isValidImageBuffer(screenshotBuffer)) {
-                debugDevice('Invalid image buffer detected: not a valid image format');
-                throw new Error('Screenshot buffer has invalid format: could not find valid image signature');
+            if (!useShellScreencap && this.takeScreenshotFailCount < AndroidDevice.TAKE_SCREENSHOT_FAIL_THRESHOLD) {
+                debugDevice('Taking screenshot via adb.takeScreenshot');
+                screenshotBuffer = await adb.takeScreenshot(null);
+                debugDevice('adb.takeScreenshot completed');
+                if (!screenshotBuffer) {
+                    this.takeScreenshotFailCount++;
+                    throw new Error('Failed to capture screenshot: screenshotBuffer is null');
+                }
+                if (!isValidImageBuffer(screenshotBuffer)) {
+                    debugDevice('Invalid image buffer detected: not a valid image format');
+                    this.takeScreenshotFailCount++;
+                    throw new Error('Screenshot buffer has invalid format: could not find valid image signature');
+                }
+                this.takeScreenshotFailCount = 0;
+            } else {
+                if (this.takeScreenshotFailCount >= AndroidDevice.TAKE_SCREENSHOT_FAIL_THRESHOLD) debugDevice('Skipping takeScreenshot (failed %d consecutive times), using shell screencap directly', this.takeScreenshotFailCount);
+                throw new Error('Using shell screencap directly');
             }
             const validScreenshotBufferSize = this.options?.minScreenshotBufferSize ?? 10240;
             if (validScreenshotBufferSize > 0 && screenshotBuffer.length < validScreenshotBufferSize) {
@@ -1209,9 +1244,18 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
                 if (!isValidImageBuffer(screenshotBuffer)) throw new Error('Fallback screenshot buffer has invalid PNG format');
                 debugDevice(`Fallback screenshot validated successfully: ${screenshotBuffer.length} bytes`);
             } finally{
-                Promise.resolve().then(()=>adb.shell(`rm ${androidScreenshotPath}`)).catch((error)=>{
-                    debugDevice(`Failed to delete remote screenshot: ${error}`);
+                const adbPath = adb.executable?.path ?? 'adb';
+                const child = execFile(adbPath, [
+                    '-s',
+                    this.deviceId,
+                    'shell',
+                    `rm ${androidScreenshotPath}`
+                ], {
+                    timeout: 3000
+                }, (err)=>{
+                    if (err) debugDevice('Failed to delete remote screenshot: %s', err.message);
                 });
+                child.unref();
             }
         }
         if (!screenshotBuffer) throw new Error('Failed to capture screenshot: all methods failed');
@@ -1655,6 +1699,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         device_define_property(this, "scrcpyAdapter", null);
         device_define_property(this, "appNameMapping", {});
         device_define_property(this, "cachedAdjustScale", null);
+        device_define_property(this, "takeScreenshotFailCount", 0);
         device_define_property(this, "interfaceType", 'android');
         device_define_property(this, "uri", void 0);
         device_define_property(this, "options", void 0);
@@ -1664,6 +1709,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         this.customActions = options?.customActions;
     }
 }
+device_define_property(AndroidDevice, "TAKE_SCREENSHOT_FAIL_THRESHOLD", 3);
 const runAdbShellParamSchema = z.object({
     command: z.string().describe('ADB shell command to execute')
 });

package/dist/lib/cli.js

@@ -40,6 +40,10 @@ var __webpack_modules__ = {
         const KEYFRAME_POLL_INTERVAL_MS = 200;
         const MAX_SCAN_BYTES = 1000;
         const CONNECTION_WAIT_MS = 1000;
+        const BUSY_LOOP_WINDOW_MS = 1000;
+        const BUSY_LOOP_MAX_READS = 500;
+        const BUSY_LOOP_COOLDOWN_MS = 50;
+        const BUSY_LOOP_WARN_INTERVAL_MS = 5000;
         const DEFAULT_SCRCPY_CONFIG = {
             enabled: false,
             maxSize: DEFAULT_MAX_SIZE,
@@ -137,16 +141,37 @@ var __webpack_modules__ = {
                 this.consumeFramesLoop(reader);
             }
             async consumeFramesLoop(reader) {
+                let readCount = 0;
+                let windowStart = Date.now();
+                let lastBusyWarn = 0;
+                let totalReads = 0;
                 try {
                     while(true){
                         const { done, value } = await reader.read();
                         if (done) break;
+                        totalReads++;
+                        readCount++;
+                        const now = Date.now();
+                        const elapsed = now - windowStart;
+                        if (elapsed >= BUSY_LOOP_WINDOW_MS) {
+                            const readsPerSec = readCount / elapsed * 1000;
+                            if (readCount > BUSY_LOOP_MAX_READS) {
+                                if (now - lastBusyWarn >= BUSY_LOOP_WARN_INTERVAL_MS) {
+                                    warnScrcpy(`[CPU-DIAG] Possible busy loop detected! ${readCount} reads in ${elapsed}ms (${readsPerSec.toFixed(0)} reads/sec). Total reads: ${totalReads}. Throttling with ${BUSY_LOOP_COOLDOWN_MS}ms delay.`);
+                                    lastBusyWarn = now;
+                                }
+                                await new Promise((resolve)=>setTimeout(resolve, BUSY_LOOP_COOLDOWN_MS));
+                            } else debugScrcpy(`[CPU-DIAG] Frame loop stats: ${readCount} reads in ${elapsed}ms (${readsPerSec.toFixed(1)} reads/sec), total: ${totalReads}`);
+                            readCount = 0;
+                            windowStart = Date.now();
+                        }
                         this.processFrame(value);
                     }
                 } catch (error) {
-                    debugScrcpy(`Frame consumer error: ${error}`);
+                    debugScrcpy(`Frame consumer error (total reads: ${totalReads}): ${error}`);
                     await this.disconnect();
                 }
+                debugScrcpy(`Frame consumer loop ended normally (total reads: ${totalReads})`);
             }
             processFrame(packet) {
                 if ('configuration' === packet.type) {
@@ -525,6 +550,7 @@ var __webpack_exports__ = {};
     };
     const external_node_assert_namespaceObject = require("node:assert");
     var external_node_assert_default = /*#__PURE__*/ __webpack_require__.n(external_node_assert_namespaceObject);
+    const external_node_child_process_namespaceObject = require("node:child_process");
     var external_node_fs_ = __webpack_require__("node:fs");
     var external_node_fs_default = /*#__PURE__*/ __webpack_require__.n(external_node_fs_);
     var external_node_module_ = __webpack_require__("node:module");
@@ -1186,14 +1212,23 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
             const androidScreenshotPath = `/data/local/tmp/ms_${screenshotId}.png`;
             const useShellScreencap = 'number' == typeof this.options?.displayId;
             try {
-                if (useShellScreencap) throw new Error('Using shell screencap for displayId');
-                debugDevice('Taking screenshot via adb.takeScreenshot');
-                screenshotBuffer = await adb.takeScreenshot(null);
-                debugDevice('adb.takeScreenshot completed');
-                if (!screenshotBuffer) throw new Error('Failed to capture screenshot: screenshotBuffer is null');
-                if (!(0, img_namespaceObject.isValidImageBuffer)(screenshotBuffer)) {
-                    debugDevice('Invalid image buffer detected: not a valid image format');
-                    throw new Error('Screenshot buffer has invalid format: could not find valid image signature');
+                if (!useShellScreencap && this.takeScreenshotFailCount < AndroidDevice.TAKE_SCREENSHOT_FAIL_THRESHOLD) {
+                    debugDevice('Taking screenshot via adb.takeScreenshot');
+                    screenshotBuffer = await adb.takeScreenshot(null);
+                    debugDevice('adb.takeScreenshot completed');
+                    if (!screenshotBuffer) {
+                        this.takeScreenshotFailCount++;
+                        throw new Error('Failed to capture screenshot: screenshotBuffer is null');
+                    }
+                    if (!(0, img_namespaceObject.isValidImageBuffer)(screenshotBuffer)) {
+                        debugDevice('Invalid image buffer detected: not a valid image format');
+                        this.takeScreenshotFailCount++;
+                        throw new Error('Screenshot buffer has invalid format: could not find valid image signature');
+                    }
+                    this.takeScreenshotFailCount = 0;
+                } else {
+                    if (this.takeScreenshotFailCount >= AndroidDevice.TAKE_SCREENSHOT_FAIL_THRESHOLD) debugDevice('Skipping takeScreenshot (failed %d consecutive times), using shell screencap directly', this.takeScreenshotFailCount);
+                    throw new Error('Using shell screencap directly');
                 }
                 const validScreenshotBufferSize = this.options?.minScreenshotBufferSize ?? 10240;
                 if (validScreenshotBufferSize > 0 && screenshotBuffer.length < validScreenshotBufferSize) {
@@ -1225,9 +1260,18 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
                     if (!(0, img_namespaceObject.isValidImageBuffer)(screenshotBuffer)) throw new Error('Fallback screenshot buffer has invalid PNG format');
                     debugDevice(`Fallback screenshot validated successfully: ${screenshotBuffer.length} bytes`);
                 } finally{
-                    Promise.resolve().then(()=>adb.shell(`rm ${androidScreenshotPath}`)).catch((error)=>{
-                        debugDevice(`Failed to delete remote screenshot: ${error}`);
+                    const adbPath = adb.executable?.path ?? 'adb';
+                    const child = (0, external_node_child_process_namespaceObject.execFile)(adbPath, [
+                        '-s',
+                        this.deviceId,
+                        'shell',
+                        `rm ${androidScreenshotPath}`
+                    ], {
+                        timeout: 3000
+                    }, (err)=>{
+                        if (err) debugDevice('Failed to delete remote screenshot: %s', err.message);
                     });
+                    child.unref();
                 }
             }
             if (!screenshotBuffer) throw new Error('Failed to capture screenshot: all methods failed');
@@ -1671,6 +1715,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
             device_define_property(this, "scrcpyAdapter", null);
             device_define_property(this, "appNameMapping", {});
             device_define_property(this, "cachedAdjustScale", null);
+            device_define_property(this, "takeScreenshotFailCount", 0);
             device_define_property(this, "interfaceType", 'android');
             device_define_property(this, "uri", void 0);
             device_define_property(this, "options", void 0);
@@ -1680,6 +1725,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
             this.customActions = options?.customActions;
         }
     }
+    device_define_property(AndroidDevice, "TAKE_SCREENSHOT_FAIL_THRESHOLD", 3);
     const runAdbShellParamSchema = core_namespaceObject.z.object({
         command: core_namespaceObject.z.string().describe('ADB shell command to execute')
     });

package/dist/lib/index.js

@@ -40,6 +40,10 @@ var __webpack_modules__ = {
         const KEYFRAME_POLL_INTERVAL_MS = 200;
         const MAX_SCAN_BYTES = 1000;
         const CONNECTION_WAIT_MS = 1000;
+        const BUSY_LOOP_WINDOW_MS = 1000;
+        const BUSY_LOOP_MAX_READS = 500;
+        const BUSY_LOOP_COOLDOWN_MS = 50;
+        const BUSY_LOOP_WARN_INTERVAL_MS = 5000;
         const DEFAULT_SCRCPY_CONFIG = {
             enabled: false,
             maxSize: DEFAULT_MAX_SIZE,
@@ -137,16 +141,37 @@ var __webpack_modules__ = {
                 this.consumeFramesLoop(reader);
             }
             async consumeFramesLoop(reader) {
+                let readCount = 0;
+                let windowStart = Date.now();
+                let lastBusyWarn = 0;
+                let totalReads = 0;
                 try {
                     while(true){
                         const { done, value } = await reader.read();
                         if (done) break;
+                        totalReads++;
+                        readCount++;
+                        const now = Date.now();
+                        const elapsed = now - windowStart;
+                        if (elapsed >= BUSY_LOOP_WINDOW_MS) {
+                            const readsPerSec = readCount / elapsed * 1000;
+                            if (readCount > BUSY_LOOP_MAX_READS) {
+                                if (now - lastBusyWarn >= BUSY_LOOP_WARN_INTERVAL_MS) {
+                                    warnScrcpy(`[CPU-DIAG] Possible busy loop detected! ${readCount} reads in ${elapsed}ms (${readsPerSec.toFixed(0)} reads/sec). Total reads: ${totalReads}. Throttling with ${BUSY_LOOP_COOLDOWN_MS}ms delay.`);
+                                    lastBusyWarn = now;
+                                }
+                                await new Promise((resolve)=>setTimeout(resolve, BUSY_LOOP_COOLDOWN_MS));
+                            } else debugScrcpy(`[CPU-DIAG] Frame loop stats: ${readCount} reads in ${elapsed}ms (${readsPerSec.toFixed(1)} reads/sec), total: ${totalReads}`);
+                            readCount = 0;
+                            windowStart = Date.now();
+                        }
                         this.processFrame(value);
                     }
                 } catch (error) {
-                    debugScrcpy(`Frame consumer error: ${error}`);
+                    debugScrcpy(`Frame consumer error (total reads: ${totalReads}): ${error}`);
                     await this.disconnect();
                 }
+                debugScrcpy(`Frame consumer loop ended normally (total reads: ${totalReads})`);
             }
             processFrame(packet) {
                 if ('configuration' === packet.type) {
@@ -442,6 +467,7 @@ var __webpack_exports__ = {};
     });
     const external_node_assert_namespaceObject = require("node:assert");
     var external_node_assert_default = /*#__PURE__*/ __webpack_require__.n(external_node_assert_namespaceObject);
+    const external_node_child_process_namespaceObject = require("node:child_process");
     var external_node_fs_ = __webpack_require__("node:fs");
     var external_node_fs_default = /*#__PURE__*/ __webpack_require__.n(external_node_fs_);
     var external_node_module_ = __webpack_require__("node:module");
@@ -1106,14 +1132,23 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
             const androidScreenshotPath = `/data/local/tmp/ms_${screenshotId}.png`;
             const useShellScreencap = 'number' == typeof this.options?.displayId;
             try {
-                if (useShellScreencap) throw new Error('Using shell screencap for displayId');
-                debugDevice('Taking screenshot via adb.takeScreenshot');
-                screenshotBuffer = await adb.takeScreenshot(null);
-                debugDevice('adb.takeScreenshot completed');
-                if (!screenshotBuffer) throw new Error('Failed to capture screenshot: screenshotBuffer is null');
-                if (!(0, img_namespaceObject.isValidImageBuffer)(screenshotBuffer)) {
-                    debugDevice('Invalid image buffer detected: not a valid image format');
-                    throw new Error('Screenshot buffer has invalid format: could not find valid image signature');
+                if (!useShellScreencap && this.takeScreenshotFailCount < AndroidDevice.TAKE_SCREENSHOT_FAIL_THRESHOLD) {
+                    debugDevice('Taking screenshot via adb.takeScreenshot');
+                    screenshotBuffer = await adb.takeScreenshot(null);
+                    debugDevice('adb.takeScreenshot completed');
+                    if (!screenshotBuffer) {
+                        this.takeScreenshotFailCount++;
+                        throw new Error('Failed to capture screenshot: screenshotBuffer is null');
+                    }
+                    if (!(0, img_namespaceObject.isValidImageBuffer)(screenshotBuffer)) {
+                        debugDevice('Invalid image buffer detected: not a valid image format');
+                        this.takeScreenshotFailCount++;
+                        throw new Error('Screenshot buffer has invalid format: could not find valid image signature');
+                    }
+                    this.takeScreenshotFailCount = 0;
+                } else {
+                    if (this.takeScreenshotFailCount >= AndroidDevice.TAKE_SCREENSHOT_FAIL_THRESHOLD) debugDevice('Skipping takeScreenshot (failed %d consecutive times), using shell screencap directly', this.takeScreenshotFailCount);
+                    throw new Error('Using shell screencap directly');
                 }
                 const validScreenshotBufferSize = this.options?.minScreenshotBufferSize ?? 10240;
                 if (validScreenshotBufferSize > 0 && screenshotBuffer.length < validScreenshotBufferSize) {
@@ -1145,9 +1180,18 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
                     if (!(0, img_namespaceObject.isValidImageBuffer)(screenshotBuffer)) throw new Error('Fallback screenshot buffer has invalid PNG format');
                     debugDevice(`Fallback screenshot validated successfully: ${screenshotBuffer.length} bytes`);
                 } finally{
-                    Promise.resolve().then(()=>adb.shell(`rm ${androidScreenshotPath}`)).catch((error)=>{
-                        debugDevice(`Failed to delete remote screenshot: ${error}`);
+                    const adbPath = adb.executable?.path ?? 'adb';
+                    const child = (0, external_node_child_process_namespaceObject.execFile)(adbPath, [
+                        '-s',
+                        this.deviceId,
+                        'shell',
+                        `rm ${androidScreenshotPath}`
+                    ], {
+                        timeout: 3000
+                    }, (err)=>{
+                        if (err) debugDevice('Failed to delete remote screenshot: %s', err.message);
                     });
+                    child.unref();
                 }
             }
             if (!screenshotBuffer) throw new Error('Failed to capture screenshot: all methods failed');
@@ -1591,6 +1635,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
             device_define_property(this, "scrcpyAdapter", null);
             device_define_property(this, "appNameMapping", {});
             device_define_property(this, "cachedAdjustScale", null);
+            device_define_property(this, "takeScreenshotFailCount", 0);
             device_define_property(this, "interfaceType", 'android');
             device_define_property(this, "uri", void 0);
             device_define_property(this, "options", void 0);
@@ -1600,6 +1645,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
             this.customActions = options?.customActions;
         }
     }
+    device_define_property(AndroidDevice, "TAKE_SCREENSHOT_FAIL_THRESHOLD", 3);
     const runAdbShellParamSchema = core_namespaceObject.z.object({
         command: core_namespaceObject.z.string().describe('ADB shell command to execute')
     });

package/dist/lib/mcp-server.js

@@ -40,6 +40,10 @@ var __webpack_modules__ = {
         const KEYFRAME_POLL_INTERVAL_MS = 200;
         const MAX_SCAN_BYTES = 1000;
         const CONNECTION_WAIT_MS = 1000;
+        const BUSY_LOOP_WINDOW_MS = 1000;
+        const BUSY_LOOP_MAX_READS = 500;
+        const BUSY_LOOP_COOLDOWN_MS = 50;
+        const BUSY_LOOP_WARN_INTERVAL_MS = 5000;
         const DEFAULT_SCRCPY_CONFIG = {
             enabled: false,
             maxSize: DEFAULT_MAX_SIZE,
@@ -137,16 +141,37 @@ var __webpack_modules__ = {
                 this.consumeFramesLoop(reader);
             }
             async consumeFramesLoop(reader) {
+                let readCount = 0;
+                let windowStart = Date.now();
+                let lastBusyWarn = 0;
+                let totalReads = 0;
                 try {
                     while(true){
                         const { done, value } = await reader.read();
                         if (done) break;
+                        totalReads++;
+                        readCount++;
+                        const now = Date.now();
+                        const elapsed = now - windowStart;
+                        if (elapsed >= BUSY_LOOP_WINDOW_MS) {
+                            const readsPerSec = readCount / elapsed * 1000;
+                            if (readCount > BUSY_LOOP_MAX_READS) {
+                                if (now - lastBusyWarn >= BUSY_LOOP_WARN_INTERVAL_MS) {
+                                    warnScrcpy(`[CPU-DIAG] Possible busy loop detected! ${readCount} reads in ${elapsed}ms (${readsPerSec.toFixed(0)} reads/sec). Total reads: ${totalReads}. Throttling with ${BUSY_LOOP_COOLDOWN_MS}ms delay.`);
+                                    lastBusyWarn = now;
+                                }
+                                await new Promise((resolve)=>setTimeout(resolve, BUSY_LOOP_COOLDOWN_MS));
+                            } else debugScrcpy(`[CPU-DIAG] Frame loop stats: ${readCount} reads in ${elapsed}ms (${readsPerSec.toFixed(1)} reads/sec), total: ${totalReads}`);
+                            readCount = 0;
+                            windowStart = Date.now();
+                        }
                         this.processFrame(value);
                     }
                 } catch (error) {
-                    debugScrcpy(`Frame consumer error: ${error}`);
+                    debugScrcpy(`Frame consumer error (total reads: ${totalReads}): ${error}`);
                     await this.disconnect();
                 }
+                debugScrcpy(`Frame consumer loop ended normally (total reads: ${totalReads})`);
             }
             processFrame(packet) {
                 if ('configuration' === packet.type) {
@@ -539,6 +564,7 @@ var __webpack_exports__ = {};
     };
     const external_node_assert_namespaceObject = require("node:assert");
     var external_node_assert_default = /*#__PURE__*/ __webpack_require__.n(external_node_assert_namespaceObject);
+    const external_node_child_process_namespaceObject = require("node:child_process");
     var external_node_fs_ = __webpack_require__("node:fs");
     var external_node_fs_default = /*#__PURE__*/ __webpack_require__.n(external_node_fs_);
     var external_node_module_ = __webpack_require__("node:module");
@@ -1201,14 +1227,23 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
             const androidScreenshotPath = `/data/local/tmp/ms_${screenshotId}.png`;
             const useShellScreencap = 'number' == typeof this.options?.displayId;
             try {
-                if (useShellScreencap) throw new Error('Using shell screencap for displayId');
-                debugDevice('Taking screenshot via adb.takeScreenshot');
-                screenshotBuffer = await adb.takeScreenshot(null);
-                debugDevice('adb.takeScreenshot completed');
-                if (!screenshotBuffer) throw new Error('Failed to capture screenshot: screenshotBuffer is null');
-                if (!(0, img_namespaceObject.isValidImageBuffer)(screenshotBuffer)) {
-                    debugDevice('Invalid image buffer detected: not a valid image format');
-                    throw new Error('Screenshot buffer has invalid format: could not find valid image signature');
+                if (!useShellScreencap && this.takeScreenshotFailCount < AndroidDevice.TAKE_SCREENSHOT_FAIL_THRESHOLD) {
+                    debugDevice('Taking screenshot via adb.takeScreenshot');
+                    screenshotBuffer = await adb.takeScreenshot(null);
+                    debugDevice('adb.takeScreenshot completed');
+                    if (!screenshotBuffer) {
+                        this.takeScreenshotFailCount++;
+                        throw new Error('Failed to capture screenshot: screenshotBuffer is null');
+                    }
+                    if (!(0, img_namespaceObject.isValidImageBuffer)(screenshotBuffer)) {
+                        debugDevice('Invalid image buffer detected: not a valid image format');
+                        this.takeScreenshotFailCount++;
+                        throw new Error('Screenshot buffer has invalid format: could not find valid image signature');
+                    }
+                    this.takeScreenshotFailCount = 0;
+                } else {
+                    if (this.takeScreenshotFailCount >= AndroidDevice.TAKE_SCREENSHOT_FAIL_THRESHOLD) debugDevice('Skipping takeScreenshot (failed %d consecutive times), using shell screencap directly', this.takeScreenshotFailCount);
+                    throw new Error('Using shell screencap directly');
                 }
                 const validScreenshotBufferSize = this.options?.minScreenshotBufferSize ?? 10240;
                 if (validScreenshotBufferSize > 0 && screenshotBuffer.length < validScreenshotBufferSize) {
@@ -1240,9 +1275,18 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
                     if (!(0, img_namespaceObject.isValidImageBuffer)(screenshotBuffer)) throw new Error('Fallback screenshot buffer has invalid PNG format');
                     debugDevice(`Fallback screenshot validated successfully: ${screenshotBuffer.length} bytes`);
                 } finally{
-                    Promise.resolve().then(()=>adb.shell(`rm ${androidScreenshotPath}`)).catch((error)=>{
-                        debugDevice(`Failed to delete remote screenshot: ${error}`);
+                    const adbPath = adb.executable?.path ?? 'adb';
+                    const child = (0, external_node_child_process_namespaceObject.execFile)(adbPath, [
+                        '-s',
+                        this.deviceId,
+                        'shell',
+                        `rm ${androidScreenshotPath}`
+                    ], {
+                        timeout: 3000
+                    }, (err)=>{
+                        if (err) debugDevice('Failed to delete remote screenshot: %s', err.message);
                     });
+                    child.unref();
                 }
             }
             if (!screenshotBuffer) throw new Error('Failed to capture screenshot: all methods failed');
@@ -1686,6 +1730,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
             device_define_property(this, "scrcpyAdapter", null);
             device_define_property(this, "appNameMapping", {});
             device_define_property(this, "cachedAdjustScale", null);
+            device_define_property(this, "takeScreenshotFailCount", 0);
             device_define_property(this, "interfaceType", 'android');
             device_define_property(this, "uri", void 0);
             device_define_property(this, "options", void 0);
@@ -1695,6 +1740,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
             this.customActions = options?.customActions;
         }
     }
+    device_define_property(AndroidDevice, "TAKE_SCREENSHOT_FAIL_THRESHOLD", 3);
     const runAdbShellParamSchema = core_namespaceObject.z.object({
         command: core_namespaceObject.z.string().describe('ADB shell command to execute')
     });

package/dist/types/index.d.ts

@@ -74,6 +74,8 @@ export declare class AndroidDevice implements AbstractInterface {
     private scrcpyAdapter;
     private appNameMapping;
     private cachedAdjustScale;
+    private takeScreenshotFailCount;
+    private static readonly TAKE_SCREENSHOT_FAIL_THRESHOLD;
     interfaceType: InterfaceType;
     uri: string | undefined;
     options?: AndroidDeviceOpt;
@@ -337,6 +339,8 @@ declare class ScrcpyScreenshotManager {
     private startFrameConsumer;
     /**
      * Main frame consumption loop
+     * Includes busy-loop detection: if reader.read() resolves too fast
+     * (e.g. broken stream returning immediately), we throttle to prevent 100% CPU.
      */
     private consumeFramesLoop;
     /**

package/dist/types/mcp-server.d.ts

@@ -75,6 +75,8 @@ declare class AndroidDevice implements AbstractInterface {
     private scrcpyAdapter;
     private appNameMapping;
     private cachedAdjustScale;
+    private takeScreenshotFailCount;
+    private static readonly TAKE_SCREENSHOT_FAIL_THRESHOLD;
     interfaceType: InterfaceType;
     uri: string | undefined;
     options?: AndroidDeviceOpt;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@midscene/android",
-  "version": "1.5.3-beta-20260309062917.0",
+  "version": "1.5.3",
   "description": "Android automation library for Midscene",
   "keywords": [
     "Android UI automation",
@@ -41,8 +41,8 @@
     "@yume-chan/stream-extra": "^1.0.0",
     "appium-adb": "12.12.1",
     "sharp": "^0.34.3",
-    "@midscene/core": "1.5.3-beta-20260309062917.0",
-    "@midscene/shared": "1.5.3-beta-20260309062917.0"
+    "@midscene/core": "1.5.3",
+    "@midscene/shared": "1.5.3"
   },
   "optionalDependencies": {
     "@ffmpeg-installer/ffmpeg": "^1.1.0"
@@ -56,7 +56,7 @@
     "tsx": "^4.19.2",
     "vitest": "3.0.5",
     "zod": "3.24.3",
-    "@midscene/playground": "1.5.3-beta-20260309062917.0"
+    "@midscene/playground": "1.5.3"
   },
   "license": "MIT",
   "scripts": {