@aiscene/android 1.6.7 → 1.6.8

package/dist/es/index.mjs

@@ -3,11 +3,12 @@ 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, defineActionDoubleClick, defineActionDragAndDrop, defineActionKeyboardPress, defineActionScroll, defineActionTap } from "@midscene/core/device";
+import { defineAction, defineActionClearInput, defineActionCursorMove, defineActionDoubleClick, defineActionDragAndDrop, defineActionKeyboardPress, defineActionPinch, defineActionScroll, defineActionSwipe, defineActionTap, normalizeMobileSwipeParam, normalizePinchParam } 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, overrideAIConfig } from "@midscene/shared/env";
-import { createImgBase64ByFormat, isValidPNGImageBuffer } from "@midscene/shared/img";
+import { createImgBase64ByFormat, isValidImageBuffer } from "@midscene/shared/img";
 import { mergeAndNormalizeAppNameMapping, normalizeForComparison, repeat } from "@midscene/shared/utils";
 import { ADB } from "appium-adb";
 import { Agent } from "@midscene/core/agent";
@@ -578,6 +579,9 @@ const defaultNormalScrollDuration = 1000;
 const IME_STRATEGY_ALWAYS_YADB = 'always-yadb';
 const IME_STRATEGY_YADB_FOR_NON_ASCII = 'yadb-for-non-ascii';
 const debugDevice = (0, logger_.getDebug)('android:device');
+function escapeForShell(text) {
+    return text.replace(/'/g, "'\\''").replace(/\n/g, '\\n');
+}
 class AndroidDevice {
     actionSpace() {
         const defaultActions = [
@@ -605,6 +609,12 @@ class AndroidDevice {
                     ]).default('replace').optional().describe('Input mode: "replace" (default) - clear the field and input the value; "typeOnly" - type the value directly without clearing the field first; "clear" - clear the field without inputting new text.')),
                     locate: getMidsceneLocationSchema().describe('The input field to be filled').optional()
                 }),
+                sample: {
+                    value: 'test@example.com',
+                    locate: {
+                        prompt: 'the email input field'
+                    }
+                },
                 call: async (param)=>{
                     const element = param.locate;
                     if ('typeOnly' !== param.mode) await this.clearInput(element);
@@ -650,9 +660,21 @@ class AndroidDevice {
                     y: to.center[1]
                 });
             }),
+            defineActionSwipe(async (param)=>{
+                const { startPoint, endPoint, duration, repeatCount } = normalizeMobileSwipeParam(param, await this.size());
+                for(let i = 0; i < repeatCount; i++)await this.mouseDrag(startPoint, endPoint, duration);
+            }),
             defineActionKeyboardPress(async (param)=>{
                 await this.keyboardPress(param.keyName);
             }),
+            defineActionCursorMove(async (param)=>{
+                const arrowKey = 'left' === param.direction ? 'ArrowLeft' : 'ArrowRight';
+                const times = param.times ?? 1;
+                for(let i = 0; i < times; i++){
+                    await this.keyboardPress(arrowKey);
+                    await sleep(100);
+                }
+            }),
             defineAction({
                 name: 'LongPress',
                 description: 'Trigger a long press on the screen at specified element',
@@ -660,6 +682,11 @@ class AndroidDevice {
                     duration: z.number().optional().describe('The duration of the long press in milliseconds'),
                     locate: getMidsceneLocationSchema().describe('The element to be long pressed')
                 }),
+                sample: {
+                    locate: {
+                        prompt: 'the message bubble'
+                    }
+                },
                 call: async (param)=>{
                     const element = param.locate;
                     if (!element) throw new Error('LongPress requires an element to be located');
@@ -679,6 +706,12 @@ class AndroidDevice {
                     duration: z.number().optional().describe('The duration of the pull (in milliseconds)'),
                     locate: getMidsceneLocationSchema().optional().describe('The element to start the pull from (optional)')
                 }),
+                sample: {
+                    direction: 'down',
+                    locate: {
+                        prompt: 'the center of the content list area'
+                    }
+                },
                 call: async (param)=>{
                     const element = param.locate;
                     const startPoint = element ? {
@@ -691,6 +724,16 @@ class AndroidDevice {
                     else throw new Error(`Unknown pull direction: ${param.direction}`);
                 }
             }),
+            defineActionPinch(async (param)=>{
+                const { centerX, centerY, startDistance, endDistance, duration } = normalizePinchParam(param, await this.size());
+                const { x: adjCenterX, y: adjCenterY } = await this.adjustCoordinates(centerX, centerY);
+                const ratio = 0 !== adjCenterX && 0 !== centerX ? adjCenterX / centerX : 1;
+                const adjStartDist = Math.round(startDistance * ratio);
+                const adjEndDist = Math.round(endDistance * ratio);
+                await this.ensureYadb();
+                const adb = await this.getAdb();
+                await adb.shell(`app_process${this.getDisplayArg()} -Djava.class.path=/data/local/tmp/yadb /data/local/tmp com.ysbing.yadb.Main -pinch ${adjCenterX} ${adjCenterY} ${adjStartDist} ${adjEndDist} ${duration}`);
+            }),
             defineActionClearInput(async (param)=>{
                 await this.clearInput(param.locate);
             })
@@ -835,66 +878,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
     async execYadb(keyboardContent) {
         await this.ensureYadb();
         const adb = await this.getAdb();
-        try {
-            const command = `app_process${this.getDisplayArg()} -Djava.class.path=/data/local/tmp/yadb /data/local/tmp com.ysbing.yadb.Main -keyboard "${keyboardContent}"`;
-            debugDevice(`Executing YADB input: "${keyboardContent}"`);
-            const inputPromise = adb.shell(command);
-            const timeoutPromise = new Promise((_, reject)=>setTimeout(()=>reject(new Error('YADB timeout')), 1000));
-            await Promise.race([
-                inputPromise,
-                timeoutPromise
-            ]);
-            debugDevice(`YADB input completed: "${keyboardContent}"`);
-        } catch (error) {
-            const isAccessibilityConflict = error?.cause?.stderr?.includes('UiAutomationService') || error?.cause?.stderr?.includes('already registered') || error?.message?.includes('UiAutomationService');
-            if (isAccessibilityConflict) {
-                debugDevice("YADB failed due to AccessibilityService conflict (likely Appium running), falling back to clipboard method");
-                await this.inputViaClipboard(keyboardContent);
-            } else 'YADB timeout' === error.message ? debugDevice(`YADB timed out after 2s, assuming input succeeded: "${keyboardContent}"`) : debugDevice(`YADB execution may have completed despite error: ${error}`);
-        }
-    }
-    async inputViaClipboard(text) {
-        const adb = await this.getAdb();
-        try {
-            debugDevice(`Inputting via clipboard: "${text}"`);
-            const escapedText = text.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
-            const setClipboardCmd = `
-        content insert --uri content://settings/system --bind name:s:clipboard_text --bind value:s:"${escapedText}"
-      `;
-            await adb.shell(setClipboardCmd);
-            await sleep(100);
-            await adb.shell('input keyevent KEYCODE_PASTE');
-            await sleep(100);
-            debugDevice(`Clipboard input completed via content provider: "${text}"`);
-        } catch (error1) {
-            debugDevice(`Content provider clipboard failed, trying clipper app: ${error1}`);
-            try {
-                const base64Text = Buffer.from(text, 'utf-8').toString('base64');
-                await adb.shell(`am broadcast -a clipper.set -e text "${base64Text}"`);
-                await sleep(100);
-                await adb.shell('input keyevent KEYCODE_PASTE');
-                await sleep(100);
-                debugDevice(`Clipboard input completed via clipper: "${text}"`);
-            } catch (error2) {
-                debugDevice(`All clipboard methods failed: ${error2}`);
-                const isPureAscii = /^[\x00-\x7F]*$/.test(text);
-                if (isPureAscii) {
-                    debugDevice(`Using ADB inputText for ASCII text: "${text}"`);
-                    await adb.inputText(text);
-                } else await this.inputCharByChar(text);
-            }
-        }
-    }
-    async inputCharByChar(text) {
-        const adb = await this.getAdb();
-        debugDevice(`Inputting character by character (slow method): "${text}"`);
-        const chars = Array.from(text);
-        for (const char of chars){
-            if (' ' === char) await adb.shell('input keyevent KEYCODE_SPACE');
-            else await adb.shell(`input text "${char}"`);
-            await sleep(50);
-        }
-        debugDevice("Character-by-character input completed");
+        await adb.shell(`app_process${this.getDisplayArg()} -Djava.class.path=/data/local/tmp/yadb /data/local/tmp com.ysbing.yadb.Main -keyboard '${keyboardContent}'`);
     }
     async getElementsInfo() {
         return [];
@@ -907,6 +891,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
     }
     async getScreenSize() {
         const shouldCache = !(this.options?.alwaysRefreshScreenInfo ?? false);
+        debugDevice(`getScreenSize: alwaysRefreshScreenInfo=${this.options?.alwaysRefreshScreenInfo}, shouldCache=${shouldCache}, hasCachedSize=${!!this.cachedScreenSize}`);
         if (shouldCache && this.cachedScreenSize) return this.cachedScreenSize;
         const adb = await this.getAdb();
         if ('number' == typeof this.options?.displayId) try {
@@ -1040,6 +1025,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
     }
     async getDisplayOrientation() {
         const shouldCache = !(this.options?.alwaysRefreshScreenInfo ?? false);
+        debugDevice(`getDisplayOrientation: alwaysRefreshScreenInfo=${this.options?.alwaysRefreshScreenInfo}, shouldCache=${shouldCache}, hasCachedOrientation=${null !== this.cachedOrientation}`);
         if (shouldCache && null !== this.cachedOrientation) return this.cachedOrientation;
         const adb = await this.getAdb();
         let orientation = 0;
@@ -1065,6 +1051,15 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         if (shouldCache) this.cachedOrientation = orientation;
         return orientation;
     }
+    async getOrientedPhysicalSize() {
+        const info = await this.getDevicePhysicalInfo();
+        const isLandscape = 1 === info.orientation || 3 === info.orientation;
+        const shouldSwap = true !== info.isCurrentOrientation && isLandscape;
+        return {
+            width: shouldSwap ? info.physicalHeight : info.physicalWidth,
+            height: shouldSwap ? info.physicalWidth : info.physicalHeight
+        };
+    }
     async size() {
         const deviceInfo = await this.getDevicePhysicalInfo();
         const adapter = this.getScrcpyAdapter();
@@ -1091,7 +1086,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
             height: logicalHeight
         };
     }
-    async cacheFeatureForPoint(center, options) {
+    async cacheFeatureForPoint(center) {
         const { width, height } = await this.size();
         debugDevice('cacheFeatureForPoint: center=[%s,%s], screen=[%s,%s]', center[0], center[1], width, height);
         return {
@@ -1171,14 +1166,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 (!isValidPNGImageBuffer(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) {
@@ -1207,12 +1211,21 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
                 screenshotBuffer = await external_node_fs_["default"].promises.readFile(screenshotPath);
                 const validScreenshotBufferSize = this.options?.minScreenshotBufferSize ?? 10240;
                 if (!screenshotBuffer || validScreenshotBufferSize > 0 && screenshotBuffer.length < validScreenshotBufferSize) throw new Error(`Fallback screenshot validation failed: buffer size ${screenshotBuffer?.length || 0} bytes (minimum: ${validScreenshotBufferSize})`);
-                if (!isValidPNGImageBuffer(screenshotBuffer)) throw new Error('Fallback screenshot buffer has invalid PNG format');
+                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');
@@ -1375,24 +1388,32 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         if (!this.yadbPushed) {
             const adb = await this.getAdb();
             const androidPkgJson = (0, external_node_module_.createRequire)(import.meta.url).resolve('@aiscene/android/package.json');
-            const yadbDir = external_node_path_["default"].join(external_node_path_["default"].dirname(androidPkgJson), 'bin');
-            await adb.push(yadbDir, '/data/local/tmp');
+            const yadbBin = external_node_path_["default"].join(external_node_path_["default"].dirname(androidPkgJson), 'bin', 'yadb');
+            await adb.push(yadbBin, '/data/local/tmp');
             this.yadbPushed = true;
         }
     }
     shouldUseYadbForText(text) {
         const hasNonAscii = /[\x80-\uFFFF]/.test(text);
         const hasFormatSpecifiers = /%[a-zA-Z]/.test(text);
-        return hasNonAscii || hasFormatSpecifiers;
+        const hasShellSpecialChars = /[\\`$]/.test(text);
+        const hasBothQuotes = text.includes('"') && text.includes("'");
+        return hasNonAscii || hasFormatSpecifiers || hasShellSpecialChars || hasBothQuotes;
     }
     async keyboardType(text, options) {
         if (!text) return;
         const adb = await this.getAdb();
-        const shouldUseYadb = this.shouldUseYadbForText(text);
         const IME_STRATEGY = (this.options?.imeStrategy || globalConfigManager.getEnvConfigValue(MIDSCENE_ANDROID_IME_STRATEGY)) ?? IME_STRATEGY_YADB_FOR_NON_ASCII;
         const shouldAutoDismissKeyboard = options?.autoDismissKeyboard ?? this.options?.autoDismissKeyboard ?? true;
-        if (IME_STRATEGY === IME_STRATEGY_ALWAYS_YADB || IME_STRATEGY === IME_STRATEGY_YADB_FOR_NON_ASCII && shouldUseYadb) await this.execYadb(text);
-        else await adb.inputText(text);
+        const useYadb = IME_STRATEGY === IME_STRATEGY_ALWAYS_YADB || IME_STRATEGY === IME_STRATEGY_YADB_FOR_NON_ASCII && this.shouldUseYadbForText(text);
+        if (useYadb) await this.execYadb(escapeForShell(text));
+        else {
+            const segments = text.split('\n');
+            for(let i = 0; i < segments.length; i++){
+                if (segments[i].length > 0) await adb.inputText(segments[i]);
+                if (i < segments.length - 1) await adb.keyevent(66);
+            }
+        }
         if (true === shouldAutoDismissKeyboard) await this.hideKeyboard(options);
     }
     normalizeKeyName(key) {
@@ -1440,12 +1461,12 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
     }
     async mouseClick(x, y) {
         const adb = await this.getAdb();
-        const { x: adjustedX, y: adjustedY } = this.adjustCoordinates(x, y);
+        const { x: adjustedX, y: adjustedY } = await this.adjustCoordinates(x, y);
         await adb.shell(`input${this.getDisplayArg()} swipe ${adjustedX} ${adjustedY} ${adjustedX} ${adjustedY} 150`);
     }
     async mouseDoubleClick(x, y) {
         const adb = await this.getAdb();
-        const { x: adjustedX, y: adjustedY } = this.adjustCoordinates(x, y);
+        const { x: adjustedX, y: adjustedY } = await this.adjustCoordinates(x, y);
         const tapCommand = `input${this.getDisplayArg()} tap ${adjustedX} ${adjustedY}`;
         await adb.shell(tapCommand);
         await sleep(50);
@@ -1456,8 +1477,8 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
     }
     async mouseDrag(from, to, duration) {
         const adb = await this.getAdb();
-        const { x: fromX, y: fromY } = this.adjustCoordinates(from.x, from.y);
-        const { x: toX, y: toY } = this.adjustCoordinates(to.x, to.y);
+        const { x: fromX, y: fromY } = await this.adjustCoordinates(from.x, from.y);
+        const { x: toX, y: toY } = await this.adjustCoordinates(to.x, to.y);
         const swipeDuration = duration ?? defaultNormalScrollDuration;
         await adb.shell(`input${this.getDisplayArg()} swipe ${fromX} ${fromY} ${toX} ${toY} ${swipeDuration}`);
     }
@@ -1467,16 +1488,16 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         const n = 4;
         const startX = Math.round(deltaX < 0 ? width / n * (n - 1) : width / n);
         const startY = Math.round(deltaY < 0 ? height / n * (n - 1) : height / n);
-        const maxNegativeDeltaX = startX;
-        const maxPositiveDeltaX = Math.round(width / n * (n - 1));
-        const maxNegativeDeltaY = startY;
-        const maxPositiveDeltaY = Math.round(height / n * (n - 1));
+        const maxPositiveDeltaX = startX;
+        const maxNegativeDeltaX = width - startX;
+        const maxPositiveDeltaY = startY;
+        const maxNegativeDeltaY = height - startY;
         deltaX = Math.max(-maxNegativeDeltaX, Math.min(deltaX, maxPositiveDeltaX));
         deltaY = Math.max(-maxNegativeDeltaY, Math.min(deltaY, maxPositiveDeltaY));
         const endX = Math.round(startX - deltaX);
         const endY = Math.round(startY - deltaY);
-        const { x: adjustedStartX, y: adjustedStartY } = this.adjustCoordinates(startX, startY);
-        const { x: adjustedEndX, y: adjustedEndY } = this.adjustCoordinates(endX, endY);
+        const { x: adjustedStartX, y: adjustedStartY } = await this.adjustCoordinates(startX, startY);
+        const { x: adjustedEndX, y: adjustedEndY } = await this.adjustCoordinates(endX, endY);
         const adb = await this.getAdb();
         const swipeDuration = duration ?? defaultNormalScrollDuration;
         await adb.shell(`input${this.getDisplayArg()} swipe ${adjustedStartX} ${adjustedStartY} ${adjustedEndX} ${adjustedEndY} ${swipeDuration}`);
@@ -1487,6 +1508,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         this.cachedPhysicalDisplayId = void 0;
         this.cachedScreenSize = null;
         this.cachedOrientation = null;
+        this.scalingRatio = 1;
         if (this.scrcpyAdapter) {
             await this.scrcpyAdapter.disconnect();
             this.scrcpyAdapter = null;
@@ -1526,7 +1548,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
     }
     async longPress(x, y, duration = 2000) {
         const adb = await this.getAdb();
-        const { x: adjustedX, y: adjustedY } = this.adjustCoordinates(x, y);
+        const { x: adjustedX, y: adjustedY } = await this.adjustCoordinates(x, y);
         await adb.shell(`input${this.getDisplayArg()} swipe ${adjustedX} ${adjustedY} ${adjustedX} ${adjustedY} ${duration}`);
     }
     async pullDown(startPoint, distance, duration = 800) {
@@ -1548,8 +1570,8 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
     }
     async pullDrag(from, to, duration) {
         const adb = await this.getAdb();
-        const { x: fromX, y: fromY } = this.adjustCoordinates(from.x, from.y);
-        const { x: toX, y: toY } = this.adjustCoordinates(to.x, to.y);
+        const { x: fromX, y: fromY } = await this.adjustCoordinates(from.x, from.y);
+        const { x: toX, y: toY } = await this.adjustCoordinates(to.x, to.y);
         await adb.shell(`input${this.getDisplayArg()} swipe ${fromX} ${fromY} ${toX} ${toY} ${duration}`);
     }
     async pullUp(startPoint, distance, duration = 600) {
@@ -1636,7 +1658,6 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         device_define_property(this, "yadbPushed", false);
         device_define_property(this, "devicePixelRatio", 1);
         device_define_property(this, "devicePixelRatioInitialized", false);
-        device_define_property(this, "scalingRatio", 1);
         device_define_property(this, "adb", null);
         device_define_property(this, "connectingAdb", null);
         device_define_property(this, "destroyed", false);
@@ -1647,6 +1668,8 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         device_define_property(this, "cachedPhysicalDisplayId", void 0);
         device_define_property(this, "scrcpyAdapter", null);
         device_define_property(this, "appNameMapping", {});
+        device_define_property(this, "scalingRatio", 1);
+        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);
@@ -1656,6 +1679,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')
 });
@@ -1668,6 +1692,9 @@ const createPlatformActions = (device)=>({
             description: 'Execute ADB shell command on Android device',
             interfaceAlias: 'runAdbShell',
             paramSchema: runAdbShellParamSchema,
+            sample: {
+                command: 'dumpsys window displays | grep -E "mCurrentFocus"'
+            },
             call: async (param)=>{
                 if (!param.command || '' === param.command.trim()) throw new Error('RunAdbShell requires a non-empty command parameter');
                 const adb = await device.getAdb();
@@ -1679,6 +1706,9 @@ const createPlatformActions = (device)=>({
             description: 'Launch an Android app or URL',
             interfaceAlias: 'launch',
             paramSchema: launchParamSchema,
+            sample: {
+                uri: 'com.example.app'
+            },
             call: async (param)=>{
                 if (!param.uri || '' === param.uri.trim()) throw new Error('Launch requires a non-empty uri parameter');
                 await device.launch(param.uri);