feat(android): add alwaysFetchScreenInfo option to control screen info caching (#1315)

* feat(android): add alwaysFetchScreenInfo option to control screen info caching

Add a new optional parameter `alwaysFetchScreenInfo` to `AndroidDeviceOpt` that allows
users to control whether screen size and orientation information should be fetched on
every call or cached after the first fetch.

- Add `alwaysFetchScreenInfo` parameter to `AndroidDeviceOpt` (defaults to false)
- Add cache fields `cachedScreenSize` and `cachedOrientation` to `AndroidDevice` class
- Update `getScreenSize()` to check and use cache when `alwaysFetchScreenInfo` is false
- Update `getDisplayOrientation()` to use cache when `alwaysFetchScreenInfo` is false
- Update documentation (both English and Chinese) to describe the new parameter

By default, screen info is cached to reduce ADB calls and improve performance. Users can
set `alwaysFetchScreenInfo: true` if they need real-time screen information (e.g., device
rotation scenarios).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* fix(android): pass alwaysFetchScreenInfo option to AndroidDevice

The alwaysFetchScreenInfo parameter was not being passed from agentFromAdbDevice to
AndroidDevice constructor, causing the option to be ignored when creating agents.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: quanru

apps/site/docs/en/mcp-android.mdx

@@ -76,6 +76,7 @@ Midscene MCP provides the following Android device automation tools:
   Parameters:
   - deviceId: (Optional) Device ID to connect to. If not provided, uses the first available device.
   - displayId: (Optional) Display ID for multi-display Android devices (e.g., 0, 1, 2). When specified, all ADB input operations will target this specific display.
+  - alwaysFetchScreenInfo: (Optional) Whether to always fetch screen size and orientation from the device on each call. Defaults to false (uses cache for better performance). Set to true if the device may rotate or you need real-time screen information.
   ```
 
 ### App control

apps/site/docs/zh/mcp-android.mdx

@@ -75,7 +75,8 @@ Midscene MCP 提供以下 Android 设备自动化工具：
   ```
   参数：
   - deviceId：（可选）要连接的设备 ID。如果未提供，使用第一个可用设备
-  - displayId：（可选）多屏 Android 设备的显示屏 ID（如 0、1、2），当指定时，所有 ADB 输入操作将针对此特定显示屏。
+  - displayId：（可选）多屏 Android 设备的显示屏 ID（如 0、1、2），当指定时，所有 ADB 输入操作将针对此特定显示屏
+  - alwaysFetchScreenInfo：（可选）是否每次都重新获取屏幕尺寸和方向信息。默认为 false（使用缓存以提高性能）。如果设备可能会旋转或需要实时屏幕信息，设置为 true
   ```
 
 ### 应用控制

packages/android/src/agent.ts

@@ -45,6 +45,7 @@ export async function agentFromAdbDevice(
     usePhysicalDisplayIdForDisplayLookup:
       opts?.usePhysicalDisplayIdForDisplayLookup,
     screenshotResizeScale: opts?.screenshotResizeScale,
+    alwaysFetchScreenInfo: opts?.alwaysFetchScreenInfo,
   });
 
   await device.connect();

packages/android/src/device.ts

@@ -69,6 +69,7 @@ export type AndroidDeviceOpt = {
   usePhysicalDisplayIdForDisplayLookup?: boolean;
   customActions?: DeviceAction<any>[];
   screenshotResizeScale?: number;
+  alwaysFetchScreenInfo?: boolean; // If true, always fetch screen size and orientation from device on each call; if false (default), cache the first result
 } & AndroidDeviceInputOpt;
 
 export class AndroidDevice implements AbstractInterface {
@@ -82,6 +83,12 @@ export class AndroidDevice implements AbstractInterface {
   private destroyed = false;
   private description: string | undefined;
   private customActions?: DeviceAction<any>[];
+  private cachedScreenSize: {
+    override: string;
+    physical: string;
+    orientation: number;
+  } | null = null;
+  private cachedOrientation: number | null = null;
   interfaceType: InterfaceType = 'android';
   uri: string | undefined;
   options?: AndroidDeviceOpt;
@@ -516,6 +523,12 @@ ${Object.keys(size)
     physical: string;
     orientation: number; // 0=portrait, 1=landscape, 2=reverse portrait, 3=reverse landscape
   }> {
+    // Return cached value if not always fetching and cache exists
+    const shouldCache = !(this.options?.alwaysFetchScreenInfo ?? false);
+    if (shouldCache && this.cachedScreenSize) {
+      return this.cachedScreenSize;
+    }
+
     const adb = await this.getAdb();
 
     // If we have an displayId, try to get size from display info
@@ -550,11 +563,18 @@ ${Object.keys(size)
                   `Using display info for long ID ${physicalDisplayId}: ${sizeStr}, rotation: ${rotation}`,
                 );
 
-                return {
+                const result = {
                   override: sizeStr,
                   physical: sizeStr,
                   orientation: rotation,
                 };
+
+                // Cache the result if caching is enabled
+                if (shouldCache) {
+                  this.cachedScreenSize = result;
+                }
+
+                return result;
               }
             }
           }
@@ -581,11 +601,18 @@ ${Object.keys(size)
                 `Using display info for display ID ${this.options.displayId}: ${sizeStr}, rotation: ${rotation}`,
               );
 
-              return {
+              const result = {
                 override: sizeStr,
                 physical: sizeStr,
                 orientation: rotation,
               };
+
+              // Cache the result if caching is enabled
+              if (shouldCache) {
+                this.cachedScreenSize = result;
+              }
+
+              return result;
             }
           }
         }
@@ -628,7 +655,14 @@ ${Object.keys(size)
     const orientation = await this.getDisplayOrientation();
 
     if (size.override || size.physical) {
-      return { ...size, orientation };
+      const result = { ...size, orientation };
+
+      // Cache the result if caching is enabled
+      if (shouldCache) {
+        this.cachedScreenSize = result;
+      }
+
+      return result;
     }
 
     throw new Error(`Failed to get screen size, output: ${stdout}`);
@@ -703,6 +737,12 @@ ${Object.keys(size)
   }
 
   async getDisplayOrientation(): Promise<number> {
+    // Return cached value if not always fetching and cache exists
+    const shouldCache = !(this.options?.alwaysFetchScreenInfo ?? false);
+    if (shouldCache && this.cachedOrientation !== null) {
+      return this.cachedOrientation;
+    }
+
     const adb = await this.getAdb();
     let orientation = 0;
 
@@ -740,6 +780,11 @@ ${Object.keys(size)
       }
     }
 
+    // Cache the result if caching is enabled
+    if (shouldCache) {
+      this.cachedOrientation = orientation;
+    }
+
     return orientation;
   }
 

packages/core/src/ai-model/common.ts

@@ -693,30 +693,33 @@ export const parseActionParam = (
   rawParam: Record<string, any>,
   zodSchema: z.ZodType<any>,
 ): Record<string, any> => {
+  // Handle undefined or null rawParam by providing an empty object
+  const param = rawParam ?? {};
+
   // Find all locate fields in the schema
   const locateFields = findAllMidsceneLocatorField(zodSchema);
 
   // If there are no locate fields, just do normal validation
   if (locateFields.length === 0) {
-    return zodSchema.parse(rawParam);
+    return zodSchema.parse(param);
   }
 
   // Extract locate field values to restore later
   const locateFieldValues: Record<string, any> = {};
   for (const fieldName of locateFields) {
-    if (fieldName in rawParam) {
-      locateFieldValues[fieldName] = rawParam[fieldName];
+    if (fieldName in param) {
+      locateFieldValues[fieldName] = param[fieldName];
     }
   }
 
   // Build params for validation - skip locate fields and use dummy values
   const paramsForValidation: Record<string, any> = {};
-  for (const key in rawParam) {
+  for (const key in param) {
     if (locateFields.includes(key)) {
       // Use dummy value to satisfy schema validation
       paramsForValidation[key] = { prompt: '_dummy_' };
     } else {
-      paramsForValidation[key] = rawParam[key];
+      paramsForValidation[key] = param[key];
     }
   }