@midscene/android 1.10.5 → 1.10.6-beta-20260717061640.0

package/dist/es/cli.mjs

@@ -52,6 +52,8 @@ var __webpack_modules__ = {
         const KEYFRAME_POLL_INTERVAL_MS = 200;
         const MAX_SCAN_BYTES = 1000;
         const CONNECTION_WAIT_MS = 1000;
+        const MAX_SERVER_OUTPUT_LINES = 100;
+        const SERVER_OUTPUT_DRAIN_TIMEOUT_MS = 500;
         const BUSY_LOOP_WINDOW_MS = 1000;
         const BUSY_LOOP_MAX_READS = 500;
         const BUSY_LOOP_COOLDOWN_MS = 50;
@@ -92,6 +94,8 @@ var __webpack_modules__ = {
                     if (this.scrcpyClient && this.videoStream) return void this.resetIdleTimer();
                     throw new Error('Scrcpy connection failed: another connection attempt did not complete in time');
                 }
+                const serverOutput = [];
+                let serverOutputTask = null;
                 try {
                     this.isConnecting = true;
                     debugScrcpy('Starting scrcpy connection...');
@@ -110,6 +114,7 @@ var __webpack_modules__ = {
                         videoCodecOptions: 'i-frame-interval=0,bitrate-mode=2'
                     });
                     this.scrcpyClient = await AdbScrcpyClient.start(this.adb, DefaultServerPath, scrcpyOptions);
+                    serverOutputTask = this.collectServerOutput(this.scrcpyClient.output, serverOutput);
                     const videoStreamPromise = this.scrcpyClient.videoStream;
                     if (!videoStreamPromise) throw new Error('Scrcpy client did not provide video stream');
                     this.videoStream = await videoStreamPromise;
@@ -126,11 +131,50 @@ var __webpack_modules__ = {
                 } catch (error) {
                     debugScrcpy(`Failed to connect scrcpy: ${error}`);
                     await this.disconnect();
-                    throw error;
+                    if (serverOutputTask) await Promise.race([
+                        serverOutputTask,
+                        new Promise((resolve)=>setTimeout(resolve, SERVER_OUTPUT_DRAIN_TIMEOUT_MS))
+                    ]);
+                    throw this.createConnectionError(error, serverOutput);
                 } finally{
                     this.isConnecting = false;
                 }
             }
+            async collectServerOutput(output, lines) {
+                const reader = output.getReader();
+                try {
+                    while(true){
+                        const { done, value } = await reader.read();
+                        if (done) break;
+                        lines.push(value);
+                        if (lines.length > MAX_SERVER_OUTPUT_LINES) lines.splice(0, lines.length - MAX_SERVER_OUTPUT_LINES);
+                    }
+                } catch (error) {
+                    debugScrcpy(`Failed to read scrcpy server output: ${error}`);
+                } finally{
+                    reader.releaseLock();
+                }
+            }
+            createConnectionError(error, serverOutput) {
+                const errorOutput = this.getErrorOutput(error);
+                const output = [
+                    ...new Set([
+                        ...errorOutput,
+                        ...serverOutput
+                    ])
+                ].filter((line)=>line.trim().length > 0);
+                const message = error instanceof Error ? error.message : String(error);
+                const outputDetails = output.length > 0 ? `\nScrcpy server output:\n${output.join('\n')}` : '';
+                return new Error(`Failed to connect scrcpy: ${message}${outputDetails}`, {
+                    cause: error
+                });
+            }
+            getErrorOutput(error) {
+                if ('object' != typeof error || null === error || !('output' in error)) return [];
+                const output = error.output;
+                if (!Array.isArray(output)) return [];
+                return output.filter((line)=>'string' == typeof line);
+            }
             resolveServerBinPath() {
                 const androidPkgJson = (0, node_module__rspack_import_1.createRequire)(import.meta.url).resolve('@midscene/android/package.json');
                 return node_path__rspack_import_2["default"].join(node_path__rspack_import_2["default"].dirname(androidPkgJson), 'bin', 'scrcpy-server');
@@ -157,6 +201,7 @@ var __webpack_modules__ = {
                 let windowStart = Date.now();
                 let lastBusyWarn = 0;
                 let totalReads = 0;
+                let endReason = 'stream closed';
                 try {
                     while(true){
                         const { done, value } = await reader.read();
@@ -180,10 +225,11 @@ var __webpack_modules__ = {
                         this.processFrame(value);
                     }
                 } catch (error) {
+                    endReason = 'stream error';
                     debugScrcpy(`Frame consumer error (total reads: ${totalReads}): ${error}`);
-                    await this.disconnect();
                 }
-                debugScrcpy(`Frame consumer loop ended normally (total reads: ${totalReads})`);
+                if (this.streamReader === reader) await this.disconnect();
+                debugScrcpy(`Frame consumer loop ended (${endReason}, total reads: ${totalReads})`);
             }
             processFrame(packet) {
                 if ('configuration' === packet.type) {
@@ -417,8 +463,10 @@ var __webpack_modules__ = {
                 this.keyframeResolvers = [];
                 this.keyframeListeners.clear();
                 if (reader) try {
-                    reader.cancel();
-                } catch  {}
+                    await reader.cancel();
+                } catch (error) {
+                    debugScrcpy(`Error cancelling scrcpy stream reader: ${error}`);
+                }
                 if (client) try {
                     await client.close();
                 } catch (error) {
@@ -642,27 +690,52 @@ function _define_property(obj, key, value) {
     return obj;
 }
 const debugAdapter = (0, logger_.getDebug)('android:scrcpy-adapter');
+const SCRCPY_RETRY_COOLDOWN_MS = 5000;
 class ScrcpyDeviceAdapter {
     isEnabled() {
-        if (this.initFailed) return false;
+        if (!this.isConfigured()) return false;
+        return null === this.retryAfter || Date.now() >= this.retryAfter;
+    }
+    getStatus() {
+        return {
+            enabled: this.isConfigured(),
+            connected: this.manager?.isConnected() ?? false,
+            lastError: this.lastError,
+            retryAfter: this.retryAfter
+        };
+    }
+    isConfigured() {
         return this.scrcpyConfig?.enabled ?? scrcpy_manager.o.enabled;
     }
     async initialize(deviceInfo) {
         try {
             const manager = await this.ensureManager(deviceInfo);
             await manager.ensureConnected();
+            this.clearFailure();
         } catch (error) {
-            this.initFailed = true;
+            this.recordFailure(error);
             throw error;
         }
     }
+    recordFailure(error) {
+        this.lastError = error instanceof Error ? error.message : String(error);
+        this.retryAfter = Date.now() + SCRCPY_RETRY_COOLDOWN_MS;
+    }
+    clearFailure() {
+        this.lastError = null;
+        this.retryAfter = null;
+    }
+    ensureRetryReady() {
+        if (null === this.retryAfter || Date.now() >= this.retryAfter) return;
+        throw new Error(`scrcpy retry is cooling down until ${new Date(this.retryAfter).toISOString()}. Last error: ${this.lastError}`);
+    }
     resolveConfig(deviceInfo) {
         if (this.resolvedConfig) return this.resolvedConfig;
         const config = this.scrcpyConfig;
         const maxSize = config?.maxSize ?? scrcpy_manager.o.maxSize;
         const videoBitRate = config?.videoBitRate ?? scrcpy_manager.o.videoBitRate;
         this.resolvedConfig = {
-            enabled: this.isEnabled(),
+            enabled: this.isConfigured(),
             maxSize,
             idleTimeoutMs: config?.idleTimeoutMs ?? scrcpy_manager.o.idleTimeoutMs,
             videoBitRate
@@ -699,14 +772,28 @@ class ScrcpyDeviceAdapter {
         }
     }
     async screenshotBase64(deviceInfo) {
-        const manager = await this.ensureManager(deviceInfo);
-        const screenshotBuffer = await manager.getScreenshotJpeg();
-        return createImgBase64ByFormat('jpeg', screenshotBuffer.toString('base64'));
+        this.ensureRetryReady();
+        try {
+            const manager = await this.ensureManager(deviceInfo);
+            const screenshotBuffer = await manager.getScreenshotJpeg();
+            this.clearFailure();
+            return createImgBase64ByFormat('jpeg', screenshotBuffer.toString('base64'));
+        } catch (error) {
+            this.recordFailure(error);
+            throw error;
+        }
     }
     async subscribeKeyframes(deviceInfo, listener) {
-        const manager = await this.ensureManager(deviceInfo);
-        await manager.ensureConnected();
-        return manager.subscribeKeyframes(listener);
+        this.ensureRetryReady();
+        try {
+            const manager = await this.ensureManager(deviceInfo);
+            await manager.ensureConnected();
+            this.clearFailure();
+            return manager.subscribeKeyframes(listener);
+        } catch (error) {
+            this.recordFailure(error);
+            throw error;
+        }
     }
     getLatestRawKeyframe() {
         return this.manager?.getLatestRawKeyframe() ?? null;
@@ -743,18 +830,21 @@ class ScrcpyDeviceAdapter {
             this.manager = null;
         }
         this.resolvedConfig = null;
+        this.clearFailure();
     }
     constructor(deviceId, scrcpyConfig){
         _define_property(this, "deviceId", void 0);
         _define_property(this, "scrcpyConfig", void 0);
         _define_property(this, "manager", void 0);
         _define_property(this, "resolvedConfig", void 0);
-        _define_property(this, "initFailed", void 0);
+        _define_property(this, "lastError", void 0);
+        _define_property(this, "retryAfter", void 0);
         this.deviceId = deviceId;
         this.scrcpyConfig = scrcpyConfig;
         this.manager = null;
         this.resolvedConfig = null;
-        this.initFailed = false;
+        this.lastError = null;
+        this.retryAfter = null;
     }
 }
 function device_define_property(obj, key, value) {
@@ -881,7 +971,7 @@ class AndroidDevice {
             console.log(`[midscene] Using scrcpy for screenshots (device: ${this.deviceId})`);
         } catch (error) {
             const msg = error instanceof Error ? error.message : String(error);
-            warnDevice(`[midscene] Scrcpy unavailable, using ADB fallback (device: ${this.deviceId}): ${msg}`);
+            warnDevice(`[midscene] Scrcpy unavailable, using ADB fallback (device: ${this.deviceId}): ${msg}. Call retryScrcpy() to retry immediately.`);
         }
         return adb;
     }
@@ -948,6 +1038,16 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
             }
         });
     }
+    getScrcpyStatus() {
+        return this.getScrcpyAdapter().getStatus();
+    }
+    async retryScrcpy() {
+        const adapter = this.getScrcpyAdapter();
+        if (!adapter.getStatus().enabled) throw new Error('scrcpy is disabled in AndroidDevice options');
+        const deviceInfo = await this.getDevicePhysicalInfo();
+        await adapter.initialize(deviceInfo);
+        return adapter.getStatus();
+    }
     getScrcpyAdapter() {
         if (!this.scrcpyAdapter) this.scrcpyAdapter = new ScrcpyDeviceAdapter(this.deviceId, this.options?.scrcpyConfig);
         return this.scrcpyAdapter;
@@ -2176,7 +2276,7 @@ class AndroidMidsceneTools extends BaseMidsceneTools {
 const tools = new AndroidMidsceneTools();
 runToolsCLI(tools, 'midscene-android', {
     stripPrefix: 'android_',
-    version: "1.10.5",
+    version: "1.10.6-beta-20260717061640.0",
     extraCommands: createReportCliCommands()
 }).catch((e)=>{
     process.exit(reportCLIError(e));

package/dist/es/index.mjs

@@ -51,6 +51,8 @@ var __webpack_modules__ = {
         const KEYFRAME_POLL_INTERVAL_MS = 200;
         const MAX_SCAN_BYTES = 1000;
         const CONNECTION_WAIT_MS = 1000;
+        const MAX_SERVER_OUTPUT_LINES = 100;
+        const SERVER_OUTPUT_DRAIN_TIMEOUT_MS = 500;
         const BUSY_LOOP_WINDOW_MS = 1000;
         const BUSY_LOOP_MAX_READS = 500;
         const BUSY_LOOP_COOLDOWN_MS = 50;
@@ -91,6 +93,8 @@ var __webpack_modules__ = {
                     if (this.scrcpyClient && this.videoStream) return void this.resetIdleTimer();
                     throw new Error('Scrcpy connection failed: another connection attempt did not complete in time');
                 }
+                const serverOutput = [];
+                let serverOutputTask = null;
                 try {
                     this.isConnecting = true;
                     debugScrcpy('Starting scrcpy connection...');
@@ -109,6 +113,7 @@ var __webpack_modules__ = {
                         videoCodecOptions: 'i-frame-interval=0,bitrate-mode=2'
                     });
                     this.scrcpyClient = await AdbScrcpyClient.start(this.adb, DefaultServerPath, scrcpyOptions);
+                    serverOutputTask = this.collectServerOutput(this.scrcpyClient.output, serverOutput);
                     const videoStreamPromise = this.scrcpyClient.videoStream;
                     if (!videoStreamPromise) throw new Error('Scrcpy client did not provide video stream');
                     this.videoStream = await videoStreamPromise;
@@ -125,11 +130,50 @@ var __webpack_modules__ = {
                 } catch (error) {
                     debugScrcpy(`Failed to connect scrcpy: ${error}`);
                     await this.disconnect();
-                    throw error;
+                    if (serverOutputTask) await Promise.race([
+                        serverOutputTask,
+                        new Promise((resolve)=>setTimeout(resolve, SERVER_OUTPUT_DRAIN_TIMEOUT_MS))
+                    ]);
+                    throw this.createConnectionError(error, serverOutput);
                 } finally{
                     this.isConnecting = false;
                 }
             }
+            async collectServerOutput(output, lines) {
+                const reader = output.getReader();
+                try {
+                    while(true){
+                        const { done, value } = await reader.read();
+                        if (done) break;
+                        lines.push(value);
+                        if (lines.length > MAX_SERVER_OUTPUT_LINES) lines.splice(0, lines.length - MAX_SERVER_OUTPUT_LINES);
+                    }
+                } catch (error) {
+                    debugScrcpy(`Failed to read scrcpy server output: ${error}`);
+                } finally{
+                    reader.releaseLock();
+                }
+            }
+            createConnectionError(error, serverOutput) {
+                const errorOutput = this.getErrorOutput(error);
+                const output = [
+                    ...new Set([
+                        ...errorOutput,
+                        ...serverOutput
+                    ])
+                ].filter((line)=>line.trim().length > 0);
+                const message = error instanceof Error ? error.message : String(error);
+                const outputDetails = output.length > 0 ? `\nScrcpy server output:\n${output.join('\n')}` : '';
+                return new Error(`Failed to connect scrcpy: ${message}${outputDetails}`, {
+                    cause: error
+                });
+            }
+            getErrorOutput(error) {
+                if ('object' != typeof error || null === error || !('output' in error)) return [];
+                const output = error.output;
+                if (!Array.isArray(output)) return [];
+                return output.filter((line)=>'string' == typeof line);
+            }
             resolveServerBinPath() {
                 const androidPkgJson = (0, node_module__rspack_import_1.createRequire)(import.meta.url).resolve('@midscene/android/package.json');
                 return node_path__rspack_import_2["default"].join(node_path__rspack_import_2["default"].dirname(androidPkgJson), 'bin', 'scrcpy-server');
@@ -156,6 +200,7 @@ var __webpack_modules__ = {
                 let windowStart = Date.now();
                 let lastBusyWarn = 0;
                 let totalReads = 0;
+                let endReason = 'stream closed';
                 try {
                     while(true){
                         const { done, value } = await reader.read();
@@ -179,10 +224,11 @@ var __webpack_modules__ = {
                         this.processFrame(value);
                     }
                 } catch (error) {
+                    endReason = 'stream error';
                     debugScrcpy(`Frame consumer error (total reads: ${totalReads}): ${error}`);
-                    await this.disconnect();
                 }
-                debugScrcpy(`Frame consumer loop ended normally (total reads: ${totalReads})`);
+                if (this.streamReader === reader) await this.disconnect();
+                debugScrcpy(`Frame consumer loop ended (${endReason}, total reads: ${totalReads})`);
             }
             processFrame(packet) {
                 if ('configuration' === packet.type) {
@@ -416,8 +462,10 @@ var __webpack_modules__ = {
                 this.keyframeResolvers = [];
                 this.keyframeListeners.clear();
                 if (reader) try {
-                    reader.cancel();
-                } catch  {}
+                    await reader.cancel();
+                } catch (error) {
+                    debugScrcpy(`Error cancelling scrcpy stream reader: ${error}`);
+                }
                 if (client) try {
                     await client.close();
                 } catch (error) {
@@ -545,27 +593,52 @@ function _define_property(obj, key, value) {
     return obj;
 }
 const debugAdapter = (0, logger_.getDebug)('android:scrcpy-adapter');
+const SCRCPY_RETRY_COOLDOWN_MS = 5000;
 class ScrcpyDeviceAdapter {
     isEnabled() {
-        if (this.initFailed) return false;
+        if (!this.isConfigured()) return false;
+        return null === this.retryAfter || Date.now() >= this.retryAfter;
+    }
+    getStatus() {
+        return {
+            enabled: this.isConfigured(),
+            connected: this.manager?.isConnected() ?? false,
+            lastError: this.lastError,
+            retryAfter: this.retryAfter
+        };
+    }
+    isConfigured() {
         return this.scrcpyConfig?.enabled ?? scrcpy_manager.o.enabled;
     }
     async initialize(deviceInfo) {
         try {
             const manager = await this.ensureManager(deviceInfo);
             await manager.ensureConnected();
+            this.clearFailure();
         } catch (error) {
-            this.initFailed = true;
+            this.recordFailure(error);
             throw error;
         }
     }
+    recordFailure(error) {
+        this.lastError = error instanceof Error ? error.message : String(error);
+        this.retryAfter = Date.now() + SCRCPY_RETRY_COOLDOWN_MS;
+    }
+    clearFailure() {
+        this.lastError = null;
+        this.retryAfter = null;
+    }
+    ensureRetryReady() {
+        if (null === this.retryAfter || Date.now() >= this.retryAfter) return;
+        throw new Error(`scrcpy retry is cooling down until ${new Date(this.retryAfter).toISOString()}. Last error: ${this.lastError}`);
+    }
     resolveConfig(deviceInfo) {
         if (this.resolvedConfig) return this.resolvedConfig;
         const config = this.scrcpyConfig;
         const maxSize = config?.maxSize ?? scrcpy_manager.o.maxSize;
         const videoBitRate = config?.videoBitRate ?? scrcpy_manager.o.videoBitRate;
         this.resolvedConfig = {
-            enabled: this.isEnabled(),
+            enabled: this.isConfigured(),
             maxSize,
             idleTimeoutMs: config?.idleTimeoutMs ?? scrcpy_manager.o.idleTimeoutMs,
             videoBitRate
@@ -602,14 +675,28 @@ class ScrcpyDeviceAdapter {
         }
     }
     async screenshotBase64(deviceInfo) {
-        const manager = await this.ensureManager(deviceInfo);
-        const screenshotBuffer = await manager.getScreenshotJpeg();
-        return createImgBase64ByFormat('jpeg', screenshotBuffer.toString('base64'));
+        this.ensureRetryReady();
+        try {
+            const manager = await this.ensureManager(deviceInfo);
+            const screenshotBuffer = await manager.getScreenshotJpeg();
+            this.clearFailure();
+            return createImgBase64ByFormat('jpeg', screenshotBuffer.toString('base64'));
+        } catch (error) {
+            this.recordFailure(error);
+            throw error;
+        }
     }
     async subscribeKeyframes(deviceInfo, listener) {
-        const manager = await this.ensureManager(deviceInfo);
-        await manager.ensureConnected();
-        return manager.subscribeKeyframes(listener);
+        this.ensureRetryReady();
+        try {
+            const manager = await this.ensureManager(deviceInfo);
+            await manager.ensureConnected();
+            this.clearFailure();
+            return manager.subscribeKeyframes(listener);
+        } catch (error) {
+            this.recordFailure(error);
+            throw error;
+        }
     }
     getLatestRawKeyframe() {
         return this.manager?.getLatestRawKeyframe() ?? null;
@@ -646,18 +733,21 @@ class ScrcpyDeviceAdapter {
             this.manager = null;
         }
         this.resolvedConfig = null;
+        this.clearFailure();
     }
     constructor(deviceId, scrcpyConfig){
         _define_property(this, "deviceId", void 0);
         _define_property(this, "scrcpyConfig", void 0);
         _define_property(this, "manager", void 0);
         _define_property(this, "resolvedConfig", void 0);
-        _define_property(this, "initFailed", void 0);
+        _define_property(this, "lastError", void 0);
+        _define_property(this, "retryAfter", void 0);
         this.deviceId = deviceId;
         this.scrcpyConfig = scrcpyConfig;
         this.manager = null;
         this.resolvedConfig = null;
-        this.initFailed = false;
+        this.lastError = null;
+        this.retryAfter = null;
     }
 }
 function device_define_property(obj, key, value) {
@@ -784,7 +874,7 @@ class AndroidDevice {
             console.log(`[midscene] Using scrcpy for screenshots (device: ${this.deviceId})`);
         } catch (error) {
             const msg = error instanceof Error ? error.message : String(error);
-            warnDevice(`[midscene] Scrcpy unavailable, using ADB fallback (device: ${this.deviceId}): ${msg}`);
+            warnDevice(`[midscene] Scrcpy unavailable, using ADB fallback (device: ${this.deviceId}): ${msg}. Call retryScrcpy() to retry immediately.`);
         }
         return adb;
     }
@@ -851,6 +941,16 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
             }
         });
     }
+    getScrcpyStatus() {
+        return this.getScrcpyAdapter().getStatus();
+    }
+    async retryScrcpy() {
+        const adapter = this.getScrcpyAdapter();
+        if (!adapter.getStatus().enabled) throw new Error('scrcpy is disabled in AndroidDevice options');
+        const deviceInfo = await this.getDevicePhysicalInfo();
+        await adapter.initialize(deviceInfo);
+        return adapter.getStatus();
+    }
     getScrcpyAdapter() {
         if (!this.scrcpyAdapter) this.scrcpyAdapter = new ScrcpyDeviceAdapter(this.deviceId, this.options?.scrcpyConfig);
         return this.scrcpyAdapter;

package/dist/lib/cli.js

@@ -40,6 +40,8 @@ var __webpack_modules__ = {
         const KEYFRAME_POLL_INTERVAL_MS = 200;
         const MAX_SCAN_BYTES = 1000;
         const CONNECTION_WAIT_MS = 1000;
+        const MAX_SERVER_OUTPUT_LINES = 100;
+        const SERVER_OUTPUT_DRAIN_TIMEOUT_MS = 500;
         const BUSY_LOOP_WINDOW_MS = 1000;
         const BUSY_LOOP_MAX_READS = 500;
         const BUSY_LOOP_COOLDOWN_MS = 50;
@@ -80,6 +82,8 @@ var __webpack_modules__ = {
                     if (this.scrcpyClient && this.videoStream) return void this.resetIdleTimer();
                     throw new Error('Scrcpy connection failed: another connection attempt did not complete in time');
                 }
+                const serverOutput = [];
+                let serverOutputTask = null;
                 try {
                     this.isConnecting = true;
                     debugScrcpy('Starting scrcpy connection...');
@@ -98,6 +102,7 @@ var __webpack_modules__ = {
                         videoCodecOptions: 'i-frame-interval=0,bitrate-mode=2'
                     });
                     this.scrcpyClient = await AdbScrcpyClient.start(this.adb, DefaultServerPath, scrcpyOptions);
+                    serverOutputTask = this.collectServerOutput(this.scrcpyClient.output, serverOutput);
                     const videoStreamPromise = this.scrcpyClient.videoStream;
                     if (!videoStreamPromise) throw new Error('Scrcpy client did not provide video stream');
                     this.videoStream = await videoStreamPromise;
@@ -114,11 +119,50 @@ var __webpack_modules__ = {
                 } catch (error) {
                     debugScrcpy(`Failed to connect scrcpy: ${error}`);
                     await this.disconnect();
-                    throw error;
+                    if (serverOutputTask) await Promise.race([
+                        serverOutputTask,
+                        new Promise((resolve)=>setTimeout(resolve, SERVER_OUTPUT_DRAIN_TIMEOUT_MS))
+                    ]);
+                    throw this.createConnectionError(error, serverOutput);
                 } finally{
                     this.isConnecting = false;
                 }
             }
+            async collectServerOutput(output, lines) {
+                const reader = output.getReader();
+                try {
+                    while(true){
+                        const { done, value } = await reader.read();
+                        if (done) break;
+                        lines.push(value);
+                        if (lines.length > MAX_SERVER_OUTPUT_LINES) lines.splice(0, lines.length - MAX_SERVER_OUTPUT_LINES);
+                    }
+                } catch (error) {
+                    debugScrcpy(`Failed to read scrcpy server output: ${error}`);
+                } finally{
+                    reader.releaseLock();
+                }
+            }
+            createConnectionError(error, serverOutput) {
+                const errorOutput = this.getErrorOutput(error);
+                const output = [
+                    ...new Set([
+                        ...errorOutput,
+                        ...serverOutput
+                    ])
+                ].filter((line)=>line.trim().length > 0);
+                const message = error instanceof Error ? error.message : String(error);
+                const outputDetails = output.length > 0 ? `\nScrcpy server output:\n${output.join('\n')}` : '';
+                return new Error(`Failed to connect scrcpy: ${message}${outputDetails}`, {
+                    cause: error
+                });
+            }
+            getErrorOutput(error) {
+                if ('object' != typeof error || null === error || !('output' in error)) return [];
+                const output = error.output;
+                if (!Array.isArray(output)) return [];
+                return output.filter((line)=>'string' == typeof line);
+            }
             resolveServerBinPath() {
                 const androidPkgJson = (0, node_module__rspack_import_1.createRequire)(__rslib_import_meta_url__).resolve('@midscene/android/package.json');
                 return node_path__rspack_import_2_default().join(node_path__rspack_import_2_default().dirname(androidPkgJson), 'bin', 'scrcpy-server');
@@ -145,6 +189,7 @@ var __webpack_modules__ = {
                 let windowStart = Date.now();
                 let lastBusyWarn = 0;
                 let totalReads = 0;
+                let endReason = 'stream closed';
                 try {
                     while(true){
                         const { done, value } = await reader.read();
@@ -168,10 +213,11 @@ var __webpack_modules__ = {
                         this.processFrame(value);
                     }
                 } catch (error) {
+                    endReason = 'stream error';
                     debugScrcpy(`Frame consumer error (total reads: ${totalReads}): ${error}`);
-                    await this.disconnect();
                 }
-                debugScrcpy(`Frame consumer loop ended normally (total reads: ${totalReads})`);
+                if (this.streamReader === reader) await this.disconnect();
+                debugScrcpy(`Frame consumer loop ended (${endReason}, total reads: ${totalReads})`);
             }
             processFrame(packet) {
                 if ('configuration' === packet.type) {
@@ -405,8 +451,10 @@ var __webpack_modules__ = {
                 this.keyframeResolvers = [];
                 this.keyframeListeners.clear();
                 if (reader) try {
-                    reader.cancel();
-                } catch  {}
+                    await reader.cancel();
+                } catch (error) {
+                    debugScrcpy(`Error cancelling scrcpy stream reader: ${error}`);
+                }
                 if (client) try {
                     await client.close();
                 } catch (error) {
@@ -657,27 +705,52 @@ ${stdout ? truncateAdbShellStream(stdout, 'stdout') : EMPTY_ADB_SHELL_STDOUT}`;
         return obj;
     }
     const debugAdapter = (0, logger_.getDebug)('android:scrcpy-adapter');
+    const SCRCPY_RETRY_COOLDOWN_MS = 5000;
     class ScrcpyDeviceAdapter {
         isEnabled() {
-            if (this.initFailed) return false;
+            if (!this.isConfigured()) return false;
+            return null === this.retryAfter || Date.now() >= this.retryAfter;
+        }
+        getStatus() {
+            return {
+                enabled: this.isConfigured(),
+                connected: this.manager?.isConnected() ?? false,
+                lastError: this.lastError,
+                retryAfter: this.retryAfter
+            };
+        }
+        isConfigured() {
             return this.scrcpyConfig?.enabled ?? scrcpy_manager.o.enabled;
         }
         async initialize(deviceInfo) {
             try {
                 const manager = await this.ensureManager(deviceInfo);
                 await manager.ensureConnected();
+                this.clearFailure();
             } catch (error) {
-                this.initFailed = true;
+                this.recordFailure(error);
                 throw error;
             }
         }
+        recordFailure(error) {
+            this.lastError = error instanceof Error ? error.message : String(error);
+            this.retryAfter = Date.now() + SCRCPY_RETRY_COOLDOWN_MS;
+        }
+        clearFailure() {
+            this.lastError = null;
+            this.retryAfter = null;
+        }
+        ensureRetryReady() {
+            if (null === this.retryAfter || Date.now() >= this.retryAfter) return;
+            throw new Error(`scrcpy retry is cooling down until ${new Date(this.retryAfter).toISOString()}. Last error: ${this.lastError}`);
+        }
         resolveConfig(deviceInfo) {
             if (this.resolvedConfig) return this.resolvedConfig;
             const config = this.scrcpyConfig;
             const maxSize = config?.maxSize ?? scrcpy_manager.o.maxSize;
             const videoBitRate = config?.videoBitRate ?? scrcpy_manager.o.videoBitRate;
             this.resolvedConfig = {
-                enabled: this.isEnabled(),
+                enabled: this.isConfigured(),
                 maxSize,
                 idleTimeoutMs: config?.idleTimeoutMs ?? scrcpy_manager.o.idleTimeoutMs,
                 videoBitRate
@@ -714,14 +787,28 @@ ${stdout ? truncateAdbShellStream(stdout, 'stdout') : EMPTY_ADB_SHELL_STDOUT}`;
             }
         }
         async screenshotBase64(deviceInfo) {
-            const manager = await this.ensureManager(deviceInfo);
-            const screenshotBuffer = await manager.getScreenshotJpeg();
-            return (0, img_namespaceObject.createImgBase64ByFormat)('jpeg', screenshotBuffer.toString('base64'));
+            this.ensureRetryReady();
+            try {
+                const manager = await this.ensureManager(deviceInfo);
+                const screenshotBuffer = await manager.getScreenshotJpeg();
+                this.clearFailure();
+                return (0, img_namespaceObject.createImgBase64ByFormat)('jpeg', screenshotBuffer.toString('base64'));
+            } catch (error) {
+                this.recordFailure(error);
+                throw error;
+            }
         }
         async subscribeKeyframes(deviceInfo, listener) {
-            const manager = await this.ensureManager(deviceInfo);
-            await manager.ensureConnected();
-            return manager.subscribeKeyframes(listener);
+            this.ensureRetryReady();
+            try {
+                const manager = await this.ensureManager(deviceInfo);
+                await manager.ensureConnected();
+                this.clearFailure();
+                return manager.subscribeKeyframes(listener);
+            } catch (error) {
+                this.recordFailure(error);
+                throw error;
+            }
         }
         getLatestRawKeyframe() {
             return this.manager?.getLatestRawKeyframe() ?? null;
@@ -758,18 +845,21 @@ ${stdout ? truncateAdbShellStream(stdout, 'stdout') : EMPTY_ADB_SHELL_STDOUT}`;
                 this.manager = null;
             }
             this.resolvedConfig = null;
+            this.clearFailure();
         }
         constructor(deviceId, scrcpyConfig){
             _define_property(this, "deviceId", void 0);
             _define_property(this, "scrcpyConfig", void 0);
             _define_property(this, "manager", void 0);
             _define_property(this, "resolvedConfig", void 0);
-            _define_property(this, "initFailed", void 0);
+            _define_property(this, "lastError", void 0);
+            _define_property(this, "retryAfter", void 0);
             this.deviceId = deviceId;
             this.scrcpyConfig = scrcpyConfig;
             this.manager = null;
             this.resolvedConfig = null;
-            this.initFailed = false;
+            this.lastError = null;
+            this.retryAfter = null;
         }
     }
     function device_define_property(obj, key, value) {
@@ -896,7 +986,7 @@ ${stdout ? truncateAdbShellStream(stdout, 'stdout') : EMPTY_ADB_SHELL_STDOUT}`;
                 console.log(`[midscene] Using scrcpy for screenshots (device: ${this.deviceId})`);
             } catch (error) {
                 const msg = error instanceof Error ? error.message : String(error);
-                warnDevice(`[midscene] Scrcpy unavailable, using ADB fallback (device: ${this.deviceId}): ${msg}`);
+                warnDevice(`[midscene] Scrcpy unavailable, using ADB fallback (device: ${this.deviceId}): ${msg}. Call retryScrcpy() to retry immediately.`);
             }
             return adb;
         }
@@ -963,6 +1053,16 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
                 }
             });
         }
+        getScrcpyStatus() {
+            return this.getScrcpyAdapter().getStatus();
+        }
+        async retryScrcpy() {
+            const adapter = this.getScrcpyAdapter();
+            if (!adapter.getStatus().enabled) throw new Error('scrcpy is disabled in AndroidDevice options');
+            const deviceInfo = await this.getDevicePhysicalInfo();
+            await adapter.initialize(deviceInfo);
+            return adapter.getStatus();
+        }
         getScrcpyAdapter() {
             if (!this.scrcpyAdapter) this.scrcpyAdapter = new ScrcpyDeviceAdapter(this.deviceId, this.options?.scrcpyConfig);
             return this.scrcpyAdapter;
@@ -2191,7 +2291,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
     const tools = new AndroidMidsceneTools();
     (0, cli_namespaceObject.runToolsCLI)(tools, 'midscene-android', {
         stripPrefix: 'android_',
-        version: "1.10.5",
+        version: "1.10.6-beta-20260717061640.0",
         extraCommands: (0, core_namespaceObject.createReportCliCommands)()
     }).catch((e)=>{
         process.exit((0, cli_namespaceObject.reportCLIError)(e));

package/dist/lib/index.js

@@ -40,6 +40,8 @@ var __webpack_modules__ = {
         const KEYFRAME_POLL_INTERVAL_MS = 200;
         const MAX_SCAN_BYTES = 1000;
         const CONNECTION_WAIT_MS = 1000;
+        const MAX_SERVER_OUTPUT_LINES = 100;
+        const SERVER_OUTPUT_DRAIN_TIMEOUT_MS = 500;
         const BUSY_LOOP_WINDOW_MS = 1000;
         const BUSY_LOOP_MAX_READS = 500;
         const BUSY_LOOP_COOLDOWN_MS = 50;
@@ -80,6 +82,8 @@ var __webpack_modules__ = {
                     if (this.scrcpyClient && this.videoStream) return void this.resetIdleTimer();
                     throw new Error('Scrcpy connection failed: another connection attempt did not complete in time');
                 }
+                const serverOutput = [];
+                let serverOutputTask = null;
                 try {
                     this.isConnecting = true;
                     debugScrcpy('Starting scrcpy connection...');
@@ -98,6 +102,7 @@ var __webpack_modules__ = {
                         videoCodecOptions: 'i-frame-interval=0,bitrate-mode=2'
                     });
                     this.scrcpyClient = await AdbScrcpyClient.start(this.adb, DefaultServerPath, scrcpyOptions);
+                    serverOutputTask = this.collectServerOutput(this.scrcpyClient.output, serverOutput);
                     const videoStreamPromise = this.scrcpyClient.videoStream;
                     if (!videoStreamPromise) throw new Error('Scrcpy client did not provide video stream');
                     this.videoStream = await videoStreamPromise;
@@ -114,11 +119,50 @@ var __webpack_modules__ = {
                 } catch (error) {
                     debugScrcpy(`Failed to connect scrcpy: ${error}`);
                     await this.disconnect();
-                    throw error;
+                    if (serverOutputTask) await Promise.race([
+                        serverOutputTask,
+                        new Promise((resolve)=>setTimeout(resolve, SERVER_OUTPUT_DRAIN_TIMEOUT_MS))
+                    ]);
+                    throw this.createConnectionError(error, serverOutput);
                 } finally{
                     this.isConnecting = false;
                 }
             }
+            async collectServerOutput(output, lines) {
+                const reader = output.getReader();
+                try {
+                    while(true){
+                        const { done, value } = await reader.read();
+                        if (done) break;
+                        lines.push(value);
+                        if (lines.length > MAX_SERVER_OUTPUT_LINES) lines.splice(0, lines.length - MAX_SERVER_OUTPUT_LINES);
+                    }
+                } catch (error) {
+                    debugScrcpy(`Failed to read scrcpy server output: ${error}`);
+                } finally{
+                    reader.releaseLock();
+                }
+            }
+            createConnectionError(error, serverOutput) {
+                const errorOutput = this.getErrorOutput(error);
+                const output = [
+                    ...new Set([
+                        ...errorOutput,
+                        ...serverOutput
+                    ])
+                ].filter((line)=>line.trim().length > 0);
+                const message = error instanceof Error ? error.message : String(error);
+                const outputDetails = output.length > 0 ? `\nScrcpy server output:\n${output.join('\n')}` : '';
+                return new Error(`Failed to connect scrcpy: ${message}${outputDetails}`, {
+                    cause: error
+                });
+            }
+            getErrorOutput(error) {
+                if ('object' != typeof error || null === error || !('output' in error)) return [];
+                const output = error.output;
+                if (!Array.isArray(output)) return [];
+                return output.filter((line)=>'string' == typeof line);
+            }
             resolveServerBinPath() {
                 const androidPkgJson = (0, node_module__rspack_import_1.createRequire)(__rslib_import_meta_url__).resolve('@midscene/android/package.json');
                 return node_path__rspack_import_2_default().join(node_path__rspack_import_2_default().dirname(androidPkgJson), 'bin', 'scrcpy-server');
@@ -145,6 +189,7 @@ var __webpack_modules__ = {
                 let windowStart = Date.now();
                 let lastBusyWarn = 0;
                 let totalReads = 0;
+                let endReason = 'stream closed';
                 try {
                     while(true){
                         const { done, value } = await reader.read();
@@ -168,10 +213,11 @@ var __webpack_modules__ = {
                         this.processFrame(value);
                     }
                 } catch (error) {
+                    endReason = 'stream error';
                     debugScrcpy(`Frame consumer error (total reads: ${totalReads}): ${error}`);
-                    await this.disconnect();
                 }
-                debugScrcpy(`Frame consumer loop ended normally (total reads: ${totalReads})`);
+                if (this.streamReader === reader) await this.disconnect();
+                debugScrcpy(`Frame consumer loop ended (${endReason}, total reads: ${totalReads})`);
             }
             processFrame(packet) {
                 if ('configuration' === packet.type) {
@@ -405,8 +451,10 @@ var __webpack_modules__ = {
                 this.keyframeResolvers = [];
                 this.keyframeListeners.clear();
                 if (reader) try {
-                    reader.cancel();
-                } catch  {}
+                    await reader.cancel();
+                } catch (error) {
+                    debugScrcpy(`Error cancelling scrcpy stream reader: ${error}`);
+                }
                 if (client) try {
                     await client.close();
                 } catch (error) {
@@ -578,27 +626,52 @@ ${stdout ? truncateAdbShellStream(stdout, 'stdout') : EMPTY_ADB_SHELL_STDOUT}`;
         return obj;
     }
     const debugAdapter = (0, logger_.getDebug)('android:scrcpy-adapter');
+    const SCRCPY_RETRY_COOLDOWN_MS = 5000;
     class ScrcpyDeviceAdapter {
         isEnabled() {
-            if (this.initFailed) return false;
+            if (!this.isConfigured()) return false;
+            return null === this.retryAfter || Date.now() >= this.retryAfter;
+        }
+        getStatus() {
+            return {
+                enabled: this.isConfigured(),
+                connected: this.manager?.isConnected() ?? false,
+                lastError: this.lastError,
+                retryAfter: this.retryAfter
+            };
+        }
+        isConfigured() {
             return this.scrcpyConfig?.enabled ?? scrcpy_manager.o.enabled;
         }
         async initialize(deviceInfo) {
             try {
                 const manager = await this.ensureManager(deviceInfo);
                 await manager.ensureConnected();
+                this.clearFailure();
             } catch (error) {
-                this.initFailed = true;
+                this.recordFailure(error);
                 throw error;
             }
         }
+        recordFailure(error) {
+            this.lastError = error instanceof Error ? error.message : String(error);
+            this.retryAfter = Date.now() + SCRCPY_RETRY_COOLDOWN_MS;
+        }
+        clearFailure() {
+            this.lastError = null;
+            this.retryAfter = null;
+        }
+        ensureRetryReady() {
+            if (null === this.retryAfter || Date.now() >= this.retryAfter) return;
+            throw new Error(`scrcpy retry is cooling down until ${new Date(this.retryAfter).toISOString()}. Last error: ${this.lastError}`);
+        }
         resolveConfig(deviceInfo) {
             if (this.resolvedConfig) return this.resolvedConfig;
             const config = this.scrcpyConfig;
             const maxSize = config?.maxSize ?? scrcpy_manager.o.maxSize;
             const videoBitRate = config?.videoBitRate ?? scrcpy_manager.o.videoBitRate;
             this.resolvedConfig = {
-                enabled: this.isEnabled(),
+                enabled: this.isConfigured(),
                 maxSize,
                 idleTimeoutMs: config?.idleTimeoutMs ?? scrcpy_manager.o.idleTimeoutMs,
                 videoBitRate
@@ -635,14 +708,28 @@ ${stdout ? truncateAdbShellStream(stdout, 'stdout') : EMPTY_ADB_SHELL_STDOUT}`;
             }
         }
         async screenshotBase64(deviceInfo) {
-            const manager = await this.ensureManager(deviceInfo);
-            const screenshotBuffer = await manager.getScreenshotJpeg();
-            return (0, img_namespaceObject.createImgBase64ByFormat)('jpeg', screenshotBuffer.toString('base64'));
+            this.ensureRetryReady();
+            try {
+                const manager = await this.ensureManager(deviceInfo);
+                const screenshotBuffer = await manager.getScreenshotJpeg();
+                this.clearFailure();
+                return (0, img_namespaceObject.createImgBase64ByFormat)('jpeg', screenshotBuffer.toString('base64'));
+            } catch (error) {
+                this.recordFailure(error);
+                throw error;
+            }
         }
         async subscribeKeyframes(deviceInfo, listener) {
-            const manager = await this.ensureManager(deviceInfo);
-            await manager.ensureConnected();
-            return manager.subscribeKeyframes(listener);
+            this.ensureRetryReady();
+            try {
+                const manager = await this.ensureManager(deviceInfo);
+                await manager.ensureConnected();
+                this.clearFailure();
+                return manager.subscribeKeyframes(listener);
+            } catch (error) {
+                this.recordFailure(error);
+                throw error;
+            }
         }
         getLatestRawKeyframe() {
             return this.manager?.getLatestRawKeyframe() ?? null;
@@ -679,18 +766,21 @@ ${stdout ? truncateAdbShellStream(stdout, 'stdout') : EMPTY_ADB_SHELL_STDOUT}`;
                 this.manager = null;
             }
             this.resolvedConfig = null;
+            this.clearFailure();
         }
         constructor(deviceId, scrcpyConfig){
             _define_property(this, "deviceId", void 0);
             _define_property(this, "scrcpyConfig", void 0);
             _define_property(this, "manager", void 0);
             _define_property(this, "resolvedConfig", void 0);
-            _define_property(this, "initFailed", void 0);
+            _define_property(this, "lastError", void 0);
+            _define_property(this, "retryAfter", void 0);
             this.deviceId = deviceId;
             this.scrcpyConfig = scrcpyConfig;
             this.manager = null;
             this.resolvedConfig = null;
-            this.initFailed = false;
+            this.lastError = null;
+            this.retryAfter = null;
         }
     }
     function device_define_property(obj, key, value) {
@@ -817,7 +907,7 @@ ${stdout ? truncateAdbShellStream(stdout, 'stdout') : EMPTY_ADB_SHELL_STDOUT}`;
                 console.log(`[midscene] Using scrcpy for screenshots (device: ${this.deviceId})`);
             } catch (error) {
                 const msg = error instanceof Error ? error.message : String(error);
-                warnDevice(`[midscene] Scrcpy unavailable, using ADB fallback (device: ${this.deviceId}): ${msg}`);
+                warnDevice(`[midscene] Scrcpy unavailable, using ADB fallback (device: ${this.deviceId}): ${msg}. Call retryScrcpy() to retry immediately.`);
             }
             return adb;
         }
@@ -884,6 +974,16 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
                 }
             });
         }
+        getScrcpyStatus() {
+            return this.getScrcpyAdapter().getStatus();
+        }
+        async retryScrcpy() {
+            const adapter = this.getScrcpyAdapter();
+            if (!adapter.getStatus().enabled) throw new Error('scrcpy is disabled in AndroidDevice options');
+            const deviceInfo = await this.getDevicePhysicalInfo();
+            await adapter.initialize(deviceInfo);
+            return adapter.getStatus();
+        }
         getScrcpyAdapter() {
             if (!this.scrcpyAdapter) this.scrcpyAdapter = new ScrcpyDeviceAdapter(this.deviceId, this.options?.scrcpyConfig);
             return this.scrcpyAdapter;

package/dist/types/index.d.ts

@@ -113,6 +113,10 @@ export declare class AndroidDevice implements AbstractInterface {
     connect(): Promise<ADB>;
     getAdb(): Promise<ADB>;
     private createAdbProxy;
+    /** Current scrcpy configuration, connection, and recovery state. */
+    getScrcpyStatus(): ScrcpyStatus;
+    /** Retry scrcpy initialization without recreating the AndroidDevice. */
+    retryScrcpy(): Promise<ScrcpyStatus>;
     /**
      * Get or create the scrcpy adapter (lazy initialization)
      */
@@ -367,14 +371,19 @@ export declare class ScrcpyDeviceAdapter {
     private scrcpyConfig;
     private manager;
     private resolvedConfig;
-    private initFailed;
+    private lastError;
+    private retryAfter;
     constructor(deviceId: string, scrcpyConfig: ScrcpyConfig | undefined);
     isEnabled(): boolean;
+    getStatus(): ScrcpyStatus;
+    private isConfigured;
     /**
-     * Initialize scrcpy connection. Called once during device.connect().
-     * If initialization fails, marks scrcpy as permanently disabled (no further retries).
+     * Initialize scrcpy connection. Called during device.connect() and explicit retries.
      */
     initialize(deviceInfo: DevicePhysicalInfo): Promise<void>;
+    private recordFailure;
+    private clearFailure;
+    private ensureRetryReady;
     /**
      * Resolve scrcpy config.
      * maxSize defaults to 0 (no scaling, full physical resolution) so the Agent layer
@@ -454,6 +463,9 @@ declare class ScrcpyScreenshotManager {
      * Ensure scrcpy connection is active
      */
     ensureConnected(): Promise<void>;
+    private collectServerOutput;
+    private createConnectionError;
+    private getErrorOutput;
     /**
      * Resolve path to scrcpy server binary
      */
@@ -562,6 +574,13 @@ declare interface ScrcpyScreenshotOptions {
     idleTimeoutMs?: number;
 }
 
+export declare interface ScrcpyStatus {
+    enabled: boolean;
+    connected: boolean;
+    lastError: string | null;
+    retryAfter: number | null;
+}
+
 declare type ScrollDirection = 'up' | 'down' | 'left' | 'right';
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@midscene/android",
-  "version": "1.10.5",
+  "version": "1.10.6-beta-20260717061640.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/web-infra-dev/midscene.git",
@@ -41,8 +41,8 @@
     "@yume-chan/stream-extra": "2.1.0",
     "appium-adb": "12.12.1",
     "sharp": "^0.34.3",
-    "@midscene/shared": "1.10.5",
-    "@midscene/core": "1.10.5"
+    "@midscene/shared": "1.10.6-beta-20260717061640.0",
+    "@midscene/core": "1.10.6-beta-20260717061640.0"
   },
   "optionalDependencies": {
     "@ffmpeg-installer/ffmpeg": "^1.1.0"
@@ -56,7 +56,7 @@
     "undici": "^6.0.0",
     "vitest": "3.0.5",
     "zod": "^3.25.1",
-    "@midscene/playground": "1.10.5"
+    "@midscene/playground": "1.10.6-beta-20260717061640.0"
   },
   "license": "MIT",
   "scripts": {