@midscene/android 1.10.6-beta-20260716090839.0 → 1.10.6

package/dist/es/cli.mjs

@@ -14,7 +14,7 @@ import { createDefaultMobileActions, defineAction } 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";
 import { createImgBase64ByFormat, validateScreenshotBuffer } from "@midscene/shared/img";
-import { ADB as external_appium_adb_ADB } from "appium-adb";
+import { ADB, getSdkRootFromEnv } from "appium-adb";
 var __webpack_modules__ = {
     "./src/scrcpy-manager.ts" (__unused_rspack_module, __webpack_exports__, __webpack_require__) {
         __webpack_require__.d(__webpack_exports__, {
@@ -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) {
@@ -630,6 +678,35 @@ const defaultAppNameMapping = {
 var external_node_fs_ = __webpack_require__("node:fs");
 var external_node_module_ = __webpack_require__("node:module");
 var external_node_path_ = __webpack_require__("node:path");
+const warnAdb = (0, logger_.getDebug)('android:adb', {
+    console: true
+});
+async function adb_createAndroidAdb({ adbExecTimeout, deviceId, deviceOptions }) {
+    const androidAdbPath = deviceOptions?.androidAdbPath || globalConfigManager.getEnvConfigValue(MIDSCENE_ADB_PATH);
+    const remoteAdbHost = deviceOptions?.remoteAdbHost || globalConfigManager.getEnvConfigValue(MIDSCENE_ADB_REMOTE_HOST);
+    const remoteAdbPort = deviceOptions?.remoteAdbPort || globalConfigManager.getEnvConfigValue(MIDSCENE_ADB_REMOTE_PORT);
+    const adbOptions = {
+        udid: deviceId,
+        adbExecTimeout,
+        remoteAdbHost: remoteAdbHost || void 0,
+        remoteAdbPort: remoteAdbPort ? Number(remoteAdbPort) : void 0
+    };
+    if (androidAdbPath) return new ADB({
+        ...adbOptions,
+        executable: {
+            path: androidAdbPath,
+            defaultArgs: []
+        }
+    });
+    const sdkRoot = getSdkRootFromEnv();
+    if (sdkRoot) try {
+        return await ADB.createADB(adbOptions);
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        warnAdb(`Unable to initialize adb from Android SDK at "${sdkRoot}", falling back to adb from PATH: ${message}`);
+    }
+    return new ADB(adbOptions);
+}
 var scrcpy_manager = __webpack_require__("./src/scrcpy-manager.ts");
 function _define_property(obj, key, value) {
     if (key in obj) Object.defineProperty(obj, key, {
@@ -642,27 +719,56 @@ function _define_property(obj, key, value) {
     return obj;
 }
 const debugAdapter = (0, logger_.getDebug)('android:scrcpy-adapter');
+const SCRCPY_RETRY_COOLDOWN_MS = 5000;
+const DEFAULT_ADB_SERVER_ENDPOINT = {
+    host: '127.0.0.1',
+    port: 5037
+};
 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
@@ -676,10 +782,8 @@ class ScrcpyDeviceAdapter {
             const { Adb, AdbServerClient } = await import("@yume-chan/adb");
             const { AdbServerNodeTcpConnector } = await import("@yume-chan/adb-server-node-tcp");
             const { ScrcpyScreenshotManager: ScrcpyManager } = await Promise.resolve().then(__webpack_require__.bind(__webpack_require__, "./src/scrcpy-manager.ts"));
-            const adbClient = new AdbServerClient(new AdbServerNodeTcpConnector({
-                host: '127.0.0.1',
-                port: 5037
-            }));
+            const adbServerEndpoint = await this.resolveAdbServerEndpoint();
+            const adbClient = new AdbServerClient(new AdbServerNodeTcpConnector(adbServerEndpoint));
             const adb = new Adb(await adbClient.createTransport({
                 serial: this.deviceId
             }));
@@ -699,14 +803,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 +861,23 @@ class ScrcpyDeviceAdapter {
             this.manager = null;
         }
         this.resolvedConfig = null;
+        this.clearFailure();
     }
-    constructor(deviceId, scrcpyConfig){
+    constructor(deviceId, scrcpyConfig, resolveAdbServerEndpoint = ()=>DEFAULT_ADB_SERVER_ENDPOINT){
         _define_property(this, "deviceId", void 0);
         _define_property(this, "scrcpyConfig", void 0);
+        _define_property(this, "resolveAdbServerEndpoint", 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.resolveAdbServerEndpoint = resolveAdbServerEndpoint;
         this.manager = null;
         this.resolvedConfig = null;
-        this.initFailed = false;
+        this.lastError = null;
+        this.retryAfter = null;
     }
 }
 function device_define_property(obj, key, value) {
@@ -881,7 +1004,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;
     }
@@ -893,18 +1016,10 @@ class AndroidDevice {
             let error = null;
             debugDevice(`Initializing ADB with device ID: ${this.deviceId}`);
             try {
-                const androidAdbPath = this.options?.androidAdbPath || globalConfigManager.getEnvConfigValue(MIDSCENE_ADB_PATH);
-                const remoteAdbHost = this.options?.remoteAdbHost || globalConfigManager.getEnvConfigValue(MIDSCENE_ADB_REMOTE_HOST);
-                const remoteAdbPort = this.options?.remoteAdbPort || globalConfigManager.getEnvConfigValue(MIDSCENE_ADB_REMOTE_PORT);
-                this.adb = new external_appium_adb_ADB({
-                    udid: this.deviceId,
+                this.adb = await adb_createAndroidAdb({
                     adbExecTimeout: 60000,
-                    executable: androidAdbPath ? {
-                        path: androidAdbPath,
-                        defaultArgs: []
-                    } : void 0,
-                    remoteAdbHost: remoteAdbHost || void 0,
-                    remoteAdbPort: remoteAdbPort ? Number(remoteAdbPort) : void 0
+                    deviceId: this.deviceId,
+                    deviceOptions: this.options
                 });
                 const size = await this.getScreenSize();
                 this.description = `
@@ -939,8 +1054,9 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
                     } catch (error) {
                         const methodName = String(prop);
                         const deviceId = this.deviceId;
-                        debugDevice(`ADB error with device ${deviceId} when calling ${methodName}: ${error}`);
-                        throw new Error(`ADB error with device ${deviceId} when calling ${methodName}, please check https://midscenejs.com/integrate-with-android.html#faq : ${error.message}`, {
+                        const adbExecutable = target.executable.path;
+                        debugDevice(`ADB error with device ${deviceId} when calling ${methodName} (ADB executable: ${adbExecutable}): ${error}`);
+                        throw new Error(`ADB error with device ${deviceId} when calling ${methodName} (ADB executable: ${adbExecutable}), please check https://midscenejs.com/integrate-with-android.html#faq : ${error.message}`, {
                             cause: error
                         });
                     }
@@ -948,8 +1064,24 @@ ${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);
+        if (!this.scrcpyAdapter) this.scrcpyAdapter = new ScrcpyDeviceAdapter(this.deviceId, this.options?.scrcpyConfig, async ()=>{
+            const adb = await this.getAdb();
+            return {
+                host: adb.adbHost ?? '127.0.0.1',
+                port: adb.adbPort ?? 5037
+            };
+        });
         return this.scrcpyAdapter;
     }
     async openScrcpyFrameSource() {
@@ -1981,17 +2113,21 @@ const createPlatformActions = (device)=>({
         })
     });
 const debugUtils = (0, logger_.getDebug)('android:utils');
-async function getConnectedDevices() {
+async function getConnectedDevices(deviceOptions) {
+    let adbExecutable;
     try {
-        const adb = await external_appium_adb_ADB.createADB({
-            adbExecTimeout: 60000
+        const adb = await adb_createAndroidAdb({
+            adbExecTimeout: 60000,
+            deviceOptions
         });
+        adbExecutable = adb.executable.path;
         const devices = await adb.getConnectedDevices();
         debugUtils(`Found ${devices.length} connected devices: `, devices);
         return devices;
     } catch (error) {
         console.error('Failed to get device list:', error);
-        throw new Error(`Unable to get connected Android device list, please check https://midscenejs.com/integrate-with-android.html#faq : ${error.message}`, {
+        const adbExecutableContext = adbExecutable ? ` (ADB executable: ${adbExecutable})` : '';
+        throw new Error(`Unable to get connected Android device list${adbExecutableContext}, please check https://midscenejs.com/integrate-with-android.html#faq : ${error.message}`, {
             cause: error
         });
     }
@@ -2047,7 +2183,7 @@ class AndroidAgent extends Agent {
 }
 async function agentFromAdbDevice(deviceId, opts) {
     if (!deviceId) {
-        const devices = await getConnectedDevices();
+        const devices = await getConnectedDevices(opts);
         if (0 === devices.length) throw new Error('No Android devices found. Please connect an Android device and ensure ADB is properly configured. Run `adb devices` to verify device connection.');
         deviceId = devices[0].udid;
         debugAgent('deviceId not specified, will use the first device (id = %s)', deviceId);
@@ -2176,7 +2312,7 @@ class AndroidMidsceneTools extends BaseMidsceneTools {
 const tools = new AndroidMidsceneTools();
 runToolsCLI(tools, 'midscene-android', {
     stripPrefix: 'android_',
-    version: "1.10.6-beta-20260716090839.0",
+    version: "1.10.6",
     extraCommands: createReportCliCommands()
 }).catch((e)=>{
     process.exit(reportCLIError(e));