@midscene/ios 1.7.6 → 1.7.7-beta-20260428092036.0

package/dist/es/bin.mjs

@@ -3,6 +3,7 @@ import { createMjpegPreviewDescriptor, definePlaygroundPlatform, launchPreparedP
 import { DEFAULT_WDA_PORT, PLAYGROUND_SERVER_PORT } from "@midscene/shared/constants";
 import { findAvailablePort } from "@midscene/shared/node";
 import { Agent } from "@midscene/core/agent";
+import { MIDSCENE_IOS_DEVICE_CLASS_OVERRIDE } from "@midscene/shared/env";
 import { getDebug } from "@midscene/shared/logger";
 import { mergeAndNormalizeAppNameMapping, normalizeForComparison } from "@midscene/shared/utils";
 import node_assert from "node:assert";
@@ -666,7 +667,7 @@ const WDA_HTTP_METHODS = [
     'PUT'
 ];
 const DEFAULT_WDA_MJPEG_PORT = 9100;
-class device_IOSDevice {
+class IOSDevice {
     actionSpace() {
         const defaultActions = [
             defineActionTap(async (param)=>{
@@ -1267,6 +1268,8 @@ const createPlatformActions = (device)=>({
             sample: {
                 uri: 'com.apple.Preferences'
             },
+            delayBeforeRunner: 0,
+            delayAfterRunner: 0,
             call: async (param)=>{
                 if (!param.uri || '' === param.uri.trim()) throw new Error('Terminate requires a non-empty uri parameter');
                 await device.terminate(param.uri);
@@ -1275,6 +1278,8 @@ const createPlatformActions = (device)=>({
         IOSHomeButton: defineAction({
             name: 'IOSHomeButton',
             description: 'Trigger the system "home" operation on iOS devices',
+            delayBeforeRunner: 0,
+            delayAfterRunner: 0,
             call: async ()=>{
                 await device.home();
             }
@@ -1297,7 +1302,7 @@ function agent_define_property(obj, key, value) {
     else obj[key] = value;
     return obj;
 }
-getDebug('ios:agent');
+const debugAgent = getDebug('ios:agent');
 class IOSAgent extends Agent {
     async launch(uri) {
         const action = this.wrapActionInActionSpace('Launch');
@@ -1324,6 +1329,22 @@ class IOSAgent extends Agent {
         this.appSwitcher = this.createActionWrapper('IOSAppSwitcher');
     }
 }
+async function agentFromWebDriverAgent(opts) {
+    debugAgent('Creating iOS agent with WebDriverAgent');
+    const overrideModule = opts?.iOSDeviceClassOverride?.trim() || opts?.iosDeviceClassOverride?.trim() || process.env[MIDSCENE_IOS_DEVICE_CLASS_OVERRIDE]?.trim();
+    let DeviceClass = IOSDevice;
+    if (overrideModule) try {
+        const overrideExports = await import(overrideModule);
+        const overrideDeviceClass = Object.prototype.hasOwnProperty.call(overrideExports, 'IOSDevice') ? overrideExports.IOSDevice : overrideExports.default;
+        if ('function' != typeof overrideDeviceClass) throw new Error(`Module "${overrideModule}" does not export a valid iOS device class (expected "IOSDevice" or default export).`);
+        DeviceClass = overrideDeviceClass;
+    } catch (error) {
+        throw new Error(`Failed to load iOS device class override from "${overrideModule}". Please make sure the package is installed and exports IOSDevice (or default) with Midscene-compatible methods. Original error: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const device = new DeviceClass(opts || {});
+    await device.connect();
+    return new IOSAgent(device, opts);
+}
 const iosPlaygroundPlatform = definePlaygroundPlatform({
     id: 'ios',
     title: 'Midscene iOS Playground',
@@ -1362,14 +1383,10 @@ const iosPlaygroundPlatform = definePlaygroundPlatform({
                 const host = 'string' == typeof input?.host && input.host.trim() ? input.host.trim().replace(/^https?:\/\//, '') : 'localhost';
                 const port = 'number' == typeof input?.port ? input.port : Number.parseInt(String(input?.port ?? DEFAULT_WDA_PORT), 10);
                 if (Number.isNaN(port) || port < 1 || port > 65535) throw new Error(`Invalid WebDriverAgent port: ${String(input?.port)}`);
-                const connectAgent = async ()=>{
-                    const newDevice = new device_IOSDevice({
+                const connectAgent = async ()=>agentFromWebDriverAgent({
                         wdaHost: host,
                         wdaPort: port
                     });
-                    await newDevice.connect();
-                    return new IOSAgent(newDevice);
-                };
                 const agent = await connectAgent();
                 const deviceInfo = await agent.interface.getConnectedDeviceInfo?.();
                 const displayName = deviceInfo ? `${deviceInfo.name} (${deviceInfo.model})` : `${host}:${port}`;

package/dist/es/cli.mjs

@@ -3,6 +3,7 @@ import { reportCLIError, runToolsCLI } from "@midscene/shared/cli";
 import { getDebug } from "@midscene/shared/logger";
 import { BaseMidsceneTools } from "@midscene/shared/mcp/base-tools";
 import { Agent } from "@midscene/core/agent";
+import { MIDSCENE_IOS_DEVICE_CLASS_OVERRIDE } from "@midscene/shared/env";
 import { mergeAndNormalizeAppNameMapping, normalizeForComparison } from "@midscene/shared/utils";
 import node_assert from "node:assert";
 import { defineAction, defineActionClearInput, defineActionCursorMove, defineActionDoubleClick, defineActionDragAndDrop, defineActionKeyboardPress, defineActionLongPress, defineActionPinch, defineActionScroll, defineActionSwipe, defineActionTap, normalizeMobileSwipeParam, normalizePinchParam } from "@midscene/core/device";
@@ -1266,6 +1267,8 @@ const createPlatformActions = (device)=>({
             sample: {
                 uri: 'com.apple.Preferences'
             },
+            delayBeforeRunner: 0,
+            delayAfterRunner: 0,
             call: async (param)=>{
                 if (!param.uri || '' === param.uri.trim()) throw new Error('Terminate requires a non-empty uri parameter');
                 await device.terminate(param.uri);
@@ -1274,6 +1277,8 @@ const createPlatformActions = (device)=>({
         IOSHomeButton: defineAction({
             name: 'IOSHomeButton',
             description: 'Trigger the system "home" operation on iOS devices',
+            delayBeforeRunner: 0,
+            delayAfterRunner: 0,
             call: async ()=>{
                 await device.home();
             }
@@ -1325,7 +1330,17 @@ class IOSAgent extends Agent {
 }
 async function agentFromWebDriverAgent(opts) {
     debugAgent('Creating iOS agent with WebDriverAgent');
-    const device = new IOSDevice(opts || {});
+    const overrideModule = opts?.iOSDeviceClassOverride?.trim() || opts?.iosDeviceClassOverride?.trim() || process.env[MIDSCENE_IOS_DEVICE_CLASS_OVERRIDE]?.trim();
+    let DeviceClass = IOSDevice;
+    if (overrideModule) try {
+        const overrideExports = await import(overrideModule);
+        const overrideDeviceClass = Object.prototype.hasOwnProperty.call(overrideExports, 'IOSDevice') ? overrideExports.IOSDevice : overrideExports.default;
+        if ('function' != typeof overrideDeviceClass) throw new Error(`Module "${overrideModule}" does not export a valid iOS device class (expected "IOSDevice" or default export).`);
+        DeviceClass = overrideDeviceClass;
+    } catch (error) {
+        throw new Error(`Failed to load iOS device class override from "${overrideModule}". Please make sure the package is installed and exports IOSDevice (or default) with Midscene-compatible methods. Original error: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const device = new DeviceClass(opts || {});
     await device.connect();
     return new IOSAgent(device, opts);
 }
@@ -1432,7 +1447,7 @@ class IOSMidsceneTools extends BaseMidsceneTools {
 const tools = new IOSMidsceneTools();
 runToolsCLI(tools, 'midscene-ios', {
     stripPrefix: 'ios_',
-    version: "1.7.6",
+    version: "1.7.7-beta-20260428092036.0",
     extraCommands: createReportCliCommands()
 }).catch((e)=>{
     process.exit(reportCLIError(e));

package/dist/es/index.mjs

@@ -8,8 +8,8 @@ import { getDebug } from "@midscene/shared/logger";
 import { mergeAndNormalizeAppNameMapping, normalizeForComparison } from "@midscene/shared/utils";
 import { WDAManager, WebDriverClient } from "@midscene/webdriver";
 import { Agent } from "@midscene/core/agent";
+import { MIDSCENE_IOS_DEVICE_CLASS_OVERRIDE, overrideAIConfig } from "@midscene/shared/env";
 import { BaseMidsceneTools } from "@midscene/shared/mcp/base-tools";
-import { overrideAIConfig } from "@midscene/shared/env";
 import { exec } from "node:child_process";
 import { platform } from "node:os";
 import { promisify } from "node:util";
@@ -1088,6 +1088,8 @@ const createPlatformActions = (device)=>({
             sample: {
                 uri: 'com.apple.Preferences'
             },
+            delayBeforeRunner: 0,
+            delayAfterRunner: 0,
             call: async (param)=>{
                 if (!param.uri || '' === param.uri.trim()) throw new Error('Terminate requires a non-empty uri parameter');
                 await device.terminate(param.uri);
@@ -1096,6 +1098,8 @@ const createPlatformActions = (device)=>({
         IOSHomeButton: defineAction({
             name: 'IOSHomeButton',
             description: 'Trigger the system "home" operation on iOS devices',
+            delayBeforeRunner: 0,
+            delayAfterRunner: 0,
             call: async ()=>{
                 await device.home();
             }
@@ -1331,7 +1335,17 @@ class IOSAgent extends Agent {
 }
 async function agentFromWebDriverAgent(opts) {
     debugAgent('Creating iOS agent with WebDriverAgent');
-    const device = new IOSDevice(opts || {});
+    const overrideModule = opts?.iOSDeviceClassOverride?.trim() || opts?.iosDeviceClassOverride?.trim() || process.env[MIDSCENE_IOS_DEVICE_CLASS_OVERRIDE]?.trim();
+    let DeviceClass = IOSDevice;
+    if (overrideModule) try {
+        const overrideExports = await import(overrideModule);
+        const overrideDeviceClass = Object.prototype.hasOwnProperty.call(overrideExports, 'IOSDevice') ? overrideExports.IOSDevice : overrideExports.default;
+        if ('function' != typeof overrideDeviceClass) throw new Error(`Module "${overrideModule}" does not export a valid iOS device class (expected "IOSDevice" or default export).`);
+        DeviceClass = overrideDeviceClass;
+    } catch (error) {
+        throw new Error(`Failed to load iOS device class override from "${overrideModule}". Please make sure the package is installed and exports IOSDevice (or default) with Midscene-compatible methods. Original error: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const device = new DeviceClass(opts || {});
     await device.connect();
     return new IOSAgent(device, opts);
 }
@@ -1519,14 +1533,10 @@ const iosPlaygroundPlatform = definePlaygroundPlatform({
                 const host = 'string' == typeof input?.host && input.host.trim() ? input.host.trim().replace(/^https?:\/\//, '') : 'localhost';
                 const port = 'number' == typeof input?.port ? input.port : Number.parseInt(String(input?.port ?? DEFAULT_WDA_PORT), 10);
                 if (Number.isNaN(port) || port < 1 || port > 65535) throw new Error(`Invalid WebDriverAgent port: ${String(input?.port)}`);
-                const connectAgent = async ()=>{
-                    const newDevice = new IOSDevice({
+                const connectAgent = async ()=>agentFromWebDriverAgent({
                         wdaHost: host,
                         wdaPort: port
                     });
-                    await newDevice.connect();
-                    return new IOSAgent(newDevice);
-                };
                 const agent = await connectAgent();
                 const deviceInfo = await agent.interface.getConnectedDeviceInfo?.();
                 const displayName = deviceInfo ? `${deviceInfo.name} (${deviceInfo.model})` : `${host}:${port}`;

package/dist/es/mcp-server.mjs

@@ -1,5 +1,6 @@
 import { BaseMCPServer, createMCPServerLauncher } from "@midscene/shared/mcp";
 import { Agent } from "@midscene/core/agent";
+import { MIDSCENE_IOS_DEVICE_CLASS_OVERRIDE } from "@midscene/shared/env";
 import { getDebug } from "@midscene/shared/logger";
 import { mergeAndNormalizeAppNameMapping, normalizeForComparison } from "@midscene/shared/utils";
 import node_assert from "node:assert";
@@ -1266,6 +1267,8 @@ const createPlatformActions = (device)=>({
             sample: {
                 uri: 'com.apple.Preferences'
             },
+            delayBeforeRunner: 0,
+            delayAfterRunner: 0,
             call: async (param)=>{
                 if (!param.uri || '' === param.uri.trim()) throw new Error('Terminate requires a non-empty uri parameter');
                 await device.terminate(param.uri);
@@ -1274,6 +1277,8 @@ const createPlatformActions = (device)=>({
         IOSHomeButton: defineAction({
             name: 'IOSHomeButton',
             description: 'Trigger the system "home" operation on iOS devices',
+            delayBeforeRunner: 0,
+            delayAfterRunner: 0,
             call: async ()=>{
                 await device.home();
             }
@@ -1325,7 +1330,17 @@ class IOSAgent extends Agent {
 }
 async function agentFromWebDriverAgent(opts) {
     debugAgent('Creating iOS agent with WebDriverAgent');
-    const device = new IOSDevice(opts || {});
+    const overrideModule = opts?.iOSDeviceClassOverride?.trim() || opts?.iosDeviceClassOverride?.trim() || process.env[MIDSCENE_IOS_DEVICE_CLASS_OVERRIDE]?.trim();
+    let DeviceClass = IOSDevice;
+    if (overrideModule) try {
+        const overrideExports = await import(overrideModule);
+        const overrideDeviceClass = Object.prototype.hasOwnProperty.call(overrideExports, 'IOSDevice') ? overrideExports.IOSDevice : overrideExports.default;
+        if ('function' != typeof overrideDeviceClass) throw new Error(`Module "${overrideModule}" does not export a valid iOS device class (expected "IOSDevice" or default export).`);
+        DeviceClass = overrideDeviceClass;
+    } catch (error) {
+        throw new Error(`Failed to load iOS device class override from "${overrideModule}". Please make sure the package is installed and exports IOSDevice (or default) with Midscene-compatible methods. Original error: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const device = new DeviceClass(opts || {});
     await device.connect();
     return new IOSAgent(device, opts);
 }
@@ -1436,7 +1451,7 @@ class IOSMCPServer extends BaseMCPServer {
     constructor(toolsManager){
         super({
             name: '@midscene/ios-mcp',
-            version: "1.7.6",
+            version: "1.7.7-beta-20260428092036.0",
             description: 'Control the iOS device using natural language commands'
         }, toolsManager);
     }

package/dist/lib/bin.js

@@ -27,6 +27,7 @@ const playground_namespaceObject = require("@midscene/playground");
 const constants_namespaceObject = require("@midscene/shared/constants");
 const node_namespaceObject = require("@midscene/shared/node");
 const agent_namespaceObject = require("@midscene/core/agent");
+const env_namespaceObject = require("@midscene/shared/env");
 const logger_namespaceObject = require("@midscene/shared/logger");
 const utils_namespaceObject = require("@midscene/shared/utils");
 const defaultAppNameMapping = {
@@ -691,7 +692,7 @@ const WDA_HTTP_METHODS = [
     'PUT'
 ];
 const DEFAULT_WDA_MJPEG_PORT = 9100;
-class device_IOSDevice {
+class IOSDevice {
     actionSpace() {
         const defaultActions = [
             (0, device_namespaceObject.defineActionTap)(async (param)=>{
@@ -1292,6 +1293,8 @@ const createPlatformActions = (device)=>({
             sample: {
                 uri: 'com.apple.Preferences'
             },
+            delayBeforeRunner: 0,
+            delayAfterRunner: 0,
             call: async (param)=>{
                 if (!param.uri || '' === param.uri.trim()) throw new Error('Terminate requires a non-empty uri parameter');
                 await device.terminate(param.uri);
@@ -1300,6 +1303,8 @@ const createPlatformActions = (device)=>({
         IOSHomeButton: (0, device_namespaceObject.defineAction)({
             name: 'IOSHomeButton',
             description: 'Trigger the system "home" operation on iOS devices',
+            delayBeforeRunner: 0,
+            delayAfterRunner: 0,
             call: async ()=>{
                 await device.home();
             }
@@ -1322,7 +1327,7 @@ function agent_define_property(obj, key, value) {
     else obj[key] = value;
     return obj;
 }
-(0, logger_namespaceObject.getDebug)('ios:agent');
+const debugAgent = (0, logger_namespaceObject.getDebug)('ios:agent');
 class IOSAgent extends agent_namespaceObject.Agent {
     async launch(uri) {
         const action = this.wrapActionInActionSpace('Launch');
@@ -1349,6 +1354,22 @@ class IOSAgent extends agent_namespaceObject.Agent {
         this.appSwitcher = this.createActionWrapper('IOSAppSwitcher');
     }
 }
+async function agentFromWebDriverAgent(opts) {
+    debugAgent('Creating iOS agent with WebDriverAgent');
+    const overrideModule = opts?.iOSDeviceClassOverride?.trim() || opts?.iosDeviceClassOverride?.trim() || process.env[env_namespaceObject.MIDSCENE_IOS_DEVICE_CLASS_OVERRIDE]?.trim();
+    let DeviceClass = IOSDevice;
+    if (overrideModule) try {
+        const overrideExports = await import(overrideModule);
+        const overrideDeviceClass = Object.prototype.hasOwnProperty.call(overrideExports, 'IOSDevice') ? overrideExports.IOSDevice : overrideExports.default;
+        if ('function' != typeof overrideDeviceClass) throw new Error(`Module "${overrideModule}" does not export a valid iOS device class (expected "IOSDevice" or default export).`);
+        DeviceClass = overrideDeviceClass;
+    } catch (error) {
+        throw new Error(`Failed to load iOS device class override from "${overrideModule}". Please make sure the package is installed and exports IOSDevice (or default) with Midscene-compatible methods. Original error: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const device = new DeviceClass(opts || {});
+    await device.connect();
+    return new IOSAgent(device, opts);
+}
 const iosPlaygroundPlatform = (0, playground_namespaceObject.definePlaygroundPlatform)({
     id: 'ios',
     title: 'Midscene iOS Playground',
@@ -1387,14 +1408,10 @@ const iosPlaygroundPlatform = (0, playground_namespaceObject.definePlaygroundPla
                 const host = 'string' == typeof input?.host && input.host.trim() ? input.host.trim().replace(/^https?:\/\//, '') : 'localhost';
                 const port = 'number' == typeof input?.port ? input.port : Number.parseInt(String(input?.port ?? constants_namespaceObject.DEFAULT_WDA_PORT), 10);
                 if (Number.isNaN(port) || port < 1 || port > 65535) throw new Error(`Invalid WebDriverAgent port: ${String(input?.port)}`);
-                const connectAgent = async ()=>{
-                    const newDevice = new device_IOSDevice({
+                const connectAgent = async ()=>agentFromWebDriverAgent({
                         wdaHost: host,
                         wdaPort: port
                     });
-                    await newDevice.connect();
-                    return new IOSAgent(newDevice);
-                };
                 const agent = await connectAgent();
                 const deviceInfo = await agent.interface.getConnectedDeviceInfo?.();
                 const displayName = deviceInfo ? `${deviceInfo.name} (${deviceInfo.model})` : `${host}:${port}`;

package/dist/lib/cli.js

@@ -26,6 +26,7 @@ const cli_namespaceObject = require("@midscene/shared/cli");
 const logger_namespaceObject = require("@midscene/shared/logger");
 const base_tools_namespaceObject = require("@midscene/shared/mcp/base-tools");
 const agent_namespaceObject = require("@midscene/core/agent");
+const env_namespaceObject = require("@midscene/shared/env");
 const utils_namespaceObject = require("@midscene/shared/utils");
 const defaultAppNameMapping = {
     微信: 'com.tencent.xin',
@@ -1290,6 +1291,8 @@ const createPlatformActions = (device)=>({
             sample: {
                 uri: 'com.apple.Preferences'
             },
+            delayBeforeRunner: 0,
+            delayAfterRunner: 0,
             call: async (param)=>{
                 if (!param.uri || '' === param.uri.trim()) throw new Error('Terminate requires a non-empty uri parameter');
                 await device.terminate(param.uri);
@@ -1298,6 +1301,8 @@ const createPlatformActions = (device)=>({
         IOSHomeButton: (0, device_namespaceObject.defineAction)({
             name: 'IOSHomeButton',
             description: 'Trigger the system "home" operation on iOS devices',
+            delayBeforeRunner: 0,
+            delayAfterRunner: 0,
             call: async ()=>{
                 await device.home();
             }
@@ -1349,7 +1354,17 @@ class IOSAgent extends agent_namespaceObject.Agent {
 }
 async function agentFromWebDriverAgent(opts) {
     debugAgent('Creating iOS agent with WebDriverAgent');
-    const device = new IOSDevice(opts || {});
+    const overrideModule = opts?.iOSDeviceClassOverride?.trim() || opts?.iosDeviceClassOverride?.trim() || process.env[env_namespaceObject.MIDSCENE_IOS_DEVICE_CLASS_OVERRIDE]?.trim();
+    let DeviceClass = IOSDevice;
+    if (overrideModule) try {
+        const overrideExports = await import(overrideModule);
+        const overrideDeviceClass = Object.prototype.hasOwnProperty.call(overrideExports, 'IOSDevice') ? overrideExports.IOSDevice : overrideExports.default;
+        if ('function' != typeof overrideDeviceClass) throw new Error(`Module "${overrideModule}" does not export a valid iOS device class (expected "IOSDevice" or default export).`);
+        DeviceClass = overrideDeviceClass;
+    } catch (error) {
+        throw new Error(`Failed to load iOS device class override from "${overrideModule}". Please make sure the package is installed and exports IOSDevice (or default) with Midscene-compatible methods. Original error: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const device = new DeviceClass(opts || {});
     await device.connect();
     return new IOSAgent(device, opts);
 }
@@ -1456,7 +1471,7 @@ class IOSMidsceneTools extends base_tools_namespaceObject.BaseMidsceneTools {
 const tools = new IOSMidsceneTools();
 (0, cli_namespaceObject.runToolsCLI)(tools, 'midscene-ios', {
     stripPrefix: 'ios_',
-    version: "1.7.6",
+    version: "1.7.7-beta-20260428092036.0",
     extraCommands: (0, core_namespaceObject.createReportCliCommands)()
 }).catch((e)=>{
     process.exit((0, cli_namespaceObject.reportCLIError)(e));

package/dist/lib/index.js

@@ -1124,6 +1124,8 @@ const createPlatformActions = (device)=>({
             sample: {
                 uri: 'com.apple.Preferences'
             },
+            delayBeforeRunner: 0,
+            delayAfterRunner: 0,
             call: async (param)=>{
                 if (!param.uri || '' === param.uri.trim()) throw new Error('Terminate requires a non-empty uri parameter');
                 await device.terminate(param.uri);
@@ -1132,6 +1134,8 @@ const createPlatformActions = (device)=>({
         IOSHomeButton: (0, device_namespaceObject.defineAction)({
             name: 'IOSHomeButton',
             description: 'Trigger the system "home" operation on iOS devices',
+            delayBeforeRunner: 0,
+            delayAfterRunner: 0,
             call: async ()=>{
                 await device.home();
             }
@@ -1145,6 +1149,7 @@ const createPlatformActions = (device)=>({
         })
     });
 const agent_namespaceObject = require("@midscene/core/agent");
+const env_namespaceObject = require("@midscene/shared/env");
 const defaultAppNameMapping = {
     微信: 'com.tencent.xin',
     企业微信: 'com.tencent.ww',
@@ -1368,7 +1373,17 @@ class IOSAgent extends agent_namespaceObject.Agent {
 }
 async function agentFromWebDriverAgent(opts) {
     debugAgent('Creating iOS agent with WebDriverAgent');
-    const device = new IOSDevice(opts || {});
+    const overrideModule = opts?.iOSDeviceClassOverride?.trim() || opts?.iosDeviceClassOverride?.trim() || process.env[env_namespaceObject.MIDSCENE_IOS_DEVICE_CLASS_OVERRIDE]?.trim();
+    let DeviceClass = IOSDevice;
+    if (overrideModule) try {
+        const overrideExports = await import(overrideModule);
+        const overrideDeviceClass = Object.prototype.hasOwnProperty.call(overrideExports, 'IOSDevice') ? overrideExports.IOSDevice : overrideExports.default;
+        if ('function' != typeof overrideDeviceClass) throw new Error(`Module "${overrideModule}" does not export a valid iOS device class (expected "IOSDevice" or default export).`);
+        DeviceClass = overrideDeviceClass;
+    } catch (error) {
+        throw new Error(`Failed to load iOS device class override from "${overrideModule}". Please make sure the package is installed and exports IOSDevice (or default) with Midscene-compatible methods. Original error: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const device = new DeviceClass(opts || {});
     await device.connect();
     return new IOSAgent(device, opts);
 }
@@ -1473,7 +1488,6 @@ class IOSMidsceneTools extends base_tools_namespaceObject.BaseMidsceneTools {
         }), mcp_tools_define_property(this, "lastOptsSignature", void 0);
     }
 }
-const env_namespaceObject = require("@midscene/shared/env");
 const external_node_child_process_namespaceObject = require("node:child_process");
 const external_node_os_namespaceObject = require("node:os");
 const external_node_util_namespaceObject = require("node:util");
@@ -1565,14 +1579,10 @@ const iosPlaygroundPlatform = (0, playground_namespaceObject.definePlaygroundPla
                 const host = 'string' == typeof input?.host && input.host.trim() ? input.host.trim().replace(/^https?:\/\//, '') : 'localhost';
                 const port = 'number' == typeof input?.port ? input.port : Number.parseInt(String(input?.port ?? constants_namespaceObject.DEFAULT_WDA_PORT), 10);
                 if (Number.isNaN(port) || port < 1 || port > 65535) throw new Error(`Invalid WebDriverAgent port: ${String(input?.port)}`);
-                const connectAgent = async ()=>{
-                    const newDevice = new IOSDevice({
+                const connectAgent = async ()=>agentFromWebDriverAgent({
                         wdaHost: host,
                         wdaPort: port
                     });
-                    await newDevice.connect();
-                    return new IOSAgent(newDevice);
-                };
                 const agent = await connectAgent();
                 const deviceInfo = await agent.interface.getConnectedDeviceInfo?.();
                 const displayName = deviceInfo ? `${deviceInfo.name} (${deviceInfo.model})` : `${host}:${port}`;

package/dist/lib/mcp-server.js

@@ -39,6 +39,7 @@ __webpack_require__.d(__webpack_exports__, {
 });
 const mcp_namespaceObject = require("@midscene/shared/mcp");
 const agent_namespaceObject = require("@midscene/core/agent");
+const env_namespaceObject = require("@midscene/shared/env");
 const logger_namespaceObject = require("@midscene/shared/logger");
 const utils_namespaceObject = require("@midscene/shared/utils");
 const defaultAppNameMapping = {
@@ -1305,6 +1306,8 @@ const createPlatformActions = (device)=>({
             sample: {
                 uri: 'com.apple.Preferences'
             },
+            delayBeforeRunner: 0,
+            delayAfterRunner: 0,
             call: async (param)=>{
                 if (!param.uri || '' === param.uri.trim()) throw new Error('Terminate requires a non-empty uri parameter');
                 await device.terminate(param.uri);
@@ -1313,6 +1316,8 @@ const createPlatformActions = (device)=>({
         IOSHomeButton: (0, device_namespaceObject.defineAction)({
             name: 'IOSHomeButton',
             description: 'Trigger the system "home" operation on iOS devices',
+            delayBeforeRunner: 0,
+            delayAfterRunner: 0,
             call: async ()=>{
                 await device.home();
             }
@@ -1364,7 +1369,17 @@ class IOSAgent extends agent_namespaceObject.Agent {
 }
 async function agentFromWebDriverAgent(opts) {
     debugAgent('Creating iOS agent with WebDriverAgent');
-    const device = new IOSDevice(opts || {});
+    const overrideModule = opts?.iOSDeviceClassOverride?.trim() || opts?.iosDeviceClassOverride?.trim() || process.env[env_namespaceObject.MIDSCENE_IOS_DEVICE_CLASS_OVERRIDE]?.trim();
+    let DeviceClass = IOSDevice;
+    if (overrideModule) try {
+        const overrideExports = await import(overrideModule);
+        const overrideDeviceClass = Object.prototype.hasOwnProperty.call(overrideExports, 'IOSDevice') ? overrideExports.IOSDevice : overrideExports.default;
+        if ('function' != typeof overrideDeviceClass) throw new Error(`Module "${overrideModule}" does not export a valid iOS device class (expected "IOSDevice" or default export).`);
+        DeviceClass = overrideDeviceClass;
+    } catch (error) {
+        throw new Error(`Failed to load iOS device class override from "${overrideModule}". Please make sure the package is installed and exports IOSDevice (or default) with Midscene-compatible methods. Original error: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const device = new DeviceClass(opts || {});
     await device.connect();
     return new IOSAgent(device, opts);
 }
@@ -1476,7 +1491,7 @@ class IOSMCPServer extends mcp_namespaceObject.BaseMCPServer {
     constructor(toolsManager){
         super({
             name: '@midscene/ios-mcp',
-            version: "1.7.6",
+            version: "1.7.7-beta-20260428092036.0",
             description: 'Control the iOS device using natural language commands'
         }, toolsManager);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@midscene/ios",
-  "version": "1.7.6",
+  "version": "1.7.7-beta-20260428092036.0",
   "description": "iOS automation library for Midscene",
   "keywords": [
     "iOS UI automation",
@@ -43,10 +43,10 @@
   "dependencies": {
     "@inquirer/prompts": "^7.8.6",
     "open": "10.1.0",
-    "@midscene/core": "1.7.6",
-    "@midscene/webdriver": "1.7.6",
-    "@midscene/shared": "1.7.6",
-    "@midscene/playground": "1.7.6"
+    "@midscene/core": "1.7.7-beta-20260428092036.0",
+    "@midscene/shared": "1.7.7-beta-20260428092036.0",
+    "@midscene/webdriver": "1.7.7-beta-20260428092036.0",
+    "@midscene/playground": "1.7.7-beta-20260428092036.0"
   },
   "devDependencies": {
     "@rslib/core": "^0.18.3",

package/static/index.html

@@ -1 +1 @@
-<!doctype html><html><head><link rel="icon" href="/favicon.ico"><title>Midscene Playground</title><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><script defer src="/static/js/lib-react.7b1abe58.js"></script><script defer src="/static/js/883.516361ae.js"></script><script defer src="/static/js/index.8f7b788e.js"></script><link href="/static/css/index.dc500f18.css" rel="stylesheet"></head><body><div id="root"></div></body></html>
+<!doctype html><html><head><link rel="icon" href="/favicon.ico"><title>Midscene Playground</title><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><script defer src="/static/js/lib-react.7b1abe58.js"></script><script defer src="/static/js/883.516361ae.js"></script><script defer src="/static/js/index.c01e1ead.js"></script><link href="/static/css/index.a02873b3.css" rel="stylesheet"></head><body><div id="root"></div></body></html>