@midscene/android 1.12.4-beta-20260903111111.0 → 1.12.4

package/dist/es/cli.mjs

@@ -15,6 +15,8 @@ import { createDefaultMobileActions, defineAction, resolveTextInputOptions, send
 import { getTmpFile, sleep } from "@midscene/core/utils";
 import { MIDSCENE_ADB_PATH, MIDSCENE_ADB_REMOTE_HOST, MIDSCENE_ADB_REMOTE_PORT, MIDSCENE_ANDROID_IME_STRATEGY, MIDSCENE_ANDROID_SCREENSHOT_STRATEGY, globalConfigManager } from "@midscene/shared/env";
 import { ADB, getSdkRootFromEnv } from "appium-adb";
+import { createAgentTestRunnerNodeDefinition } from "@midscene/core/agent/test-runner";
+import { z as v4_z } from "zod/v4";
 var __webpack_modules__ = {
     "./src/resource-path.ts" (__unused_rspack_module, __webpack_exports__, __webpack_require__) {
         __webpack_require__.d(__webpack_exports__, {
@@ -3225,6 +3227,108 @@ const createPlatformActions = (visualActions)=>({
             }
         })
     });
+const defineAndroidAgentNode = createAgentTestRunnerNodeDefinition('an Android Agent');
+const nonBlankText = (description)=>v4_z.string().regex(/\S/, 'value must contain a non-whitespace character').describe(description);
+const launchInputSchema = v4_z.strictObject({
+    uri: nonBlankText('The app, URL, URI, or package name to launch.')
+});
+const terminateInputSchema = v4_z.strictObject({
+    uri: nonBlankText('The package name or app name to terminate.')
+});
+const runAdbShellOptionsInputSchema = v4_z.strictObject({
+    timeout: v4_z.number().int().positive().optional().describe('ADB shell command timeout in milliseconds.')
+});
+const runAdbShellInputSchema = v4_z.strictObject({
+    command: nonBlankText('The shell command to execute, without an adb shell prefix.'),
+    options: runAdbShellOptionsInputSchema.optional()
+});
+const emptyInputSchema = v4_z.strictObject({});
+const launchNode = defineAndroidAgentNode({
+    method: 'launch',
+    description: 'Launch an application through the current Android Agent.',
+    stringInputKey: 'uri',
+    inputSchema: launchInputSchema,
+    toArgs: (input)=>[
+            input.uri
+        ],
+    toResult: (_output, input)=>({
+            summary: `Launched ${input.uri}`
+        })
+});
+const terminateNode = defineAndroidAgentNode({
+    method: 'terminate',
+    description: 'Terminate an application through the current Android Agent.',
+    stringInputKey: 'uri',
+    inputSchema: terminateInputSchema,
+    toArgs: (input)=>[
+            input.uri
+        ],
+    toResult: (_output, input)=>({
+            summary: `Terminated ${input.uri}`
+        })
+});
+const runAdbShellNode = defineAndroidAgentNode({
+    method: 'runAdbShell',
+    title: 'Run an ADB shell command',
+    description: 'Execute a shell command through the current Android Agent. Pass only the shell command, without the adb shell prefix.',
+    stringInputKey: 'command',
+    inputSchema: runAdbShellInputSchema,
+    toArgs (input, context) {
+        context.signal.throwIfAborted();
+        if (/^\s*adb(?:\s|$)/i.test(input.command)) throw new TypeError('command must not include an adb or adb shell prefix.');
+        return [
+            input.command,
+            input.options
+        ];
+    },
+    toResult (stdout) {
+        if ('string' != typeof stdout) throw new TypeError('runAdbShell() must return stdout as a string.');
+        return {
+            summary: `Executed ADB shell command (${stdout.length} stdout characters)`,
+            data: {
+                stdout
+            }
+        };
+    }
+});
+const backNode = defineAndroidAgentNode({
+    method: 'back',
+    description: 'Trigger the Android system back operation.',
+    stringInputKey: false,
+    inputSchema: emptyInputSchema,
+    toArgs: ()=>[],
+    toResult: ()=>({
+            summary: 'Triggered Android back'
+        })
+});
+const homeNode = defineAndroidAgentNode({
+    method: 'home',
+    description: 'Trigger the Android system home operation.',
+    stringInputKey: false,
+    inputSchema: emptyInputSchema,
+    toArgs: ()=>[],
+    toResult: ()=>({
+            summary: 'Triggered Android home'
+        })
+});
+const recentAppsNode = defineAndroidAgentNode({
+    method: 'recentApps',
+    description: 'Trigger the Android system recent apps operation.',
+    stringInputKey: false,
+    inputSchema: emptyInputSchema,
+    toArgs: ()=>[],
+    toResult: ()=>({
+            summary: 'Triggered Android recentApps'
+        })
+});
+const androidAgentTestRunnerNodeDefinitions = [
+    launchNode,
+    terminateNode,
+    runAdbShellNode,
+    backNode,
+    homeNode,
+    recentAppsNode
+];
 const debugUtils = (0, logger_.getDebug)('android:utils');
 async function getConnectedDevices(deviceOptions) {
     let adbExecutable;
@@ -3257,6 +3361,12 @@ function agent_define_property(obj, key, value) {
 }
 const debugAgent = (0, logger_.getDebug)('android:agent');
 class AndroidAgent extends Agent {
+    static getTestRunnerNodeDefinitions() {
+        return [
+            ...Agent.getTestRunnerNodeDefinitions(),
+            ...androidAgentTestRunnerNodeDefinitions
+        ];
+    }
     async launch(uri) {
         const action = this.wrapActionInActionSpace('Launch');
         return action({
@@ -3430,7 +3540,7 @@ class AndroidMidsceneTools extends BaseMidsceneTools {
 const tools = new AndroidMidsceneTools();
 runToolsCLI(tools, 'midscene-android', {
     stripPrefix: 'android_',
-    version: "1.12.4-beta-20260903111111.0",
+    version: "1.12.4",
     extraCommands: createReportCliCommands()
 }).catch((e)=>{
     process.exit(reportCLIError(e));

package/dist/es/index.mjs

@@ -12,6 +12,8 @@ import { MIDSCENE_ADB_PATH, MIDSCENE_ADB_REMOTE_HOST, MIDSCENE_ADB_REMOTE_PORT,
 import { mergeAndNormalizeAppNameMapping, normalizeForComparison, repeat } from "@midscene/shared/utils";
 import { ADB, getSdkRootFromEnv } from "appium-adb";
 import { Agent } from "@midscene/core/agent";
+import { createAgentTestRunnerNodeDefinition } from "@midscene/core/agent/test-runner";
+import { z as v4_z } from "zod/v4";
 import { agentBehaviorInitArgShape, extractAgentBehaviorInitArgs, getAgentInitArgsSignature, shouldRebuildAgentForInitArgs } from "@midscene/shared/agent-tools/agent-behavior-init-args";
 import { BaseMidsceneTools } from "@midscene/shared/agent-tools/base-tools";
 var __webpack_modules__ = {
@@ -3224,6 +3226,108 @@ const defaultAppNameMapping = {
     WeChat: 'com.tencent.mm',
     WhatsApp: 'com.whatsapp'
 };
+const defineAndroidAgentNode = createAgentTestRunnerNodeDefinition('an Android Agent');
+const nonBlankText = (description)=>v4_z.string().regex(/\S/, 'value must contain a non-whitespace character').describe(description);
+const launchInputSchema = v4_z.strictObject({
+    uri: nonBlankText('The app, URL, URI, or package name to launch.')
+});
+const terminateInputSchema = v4_z.strictObject({
+    uri: nonBlankText('The package name or app name to terminate.')
+});
+const runAdbShellOptionsInputSchema = v4_z.strictObject({
+    timeout: v4_z.number().int().positive().optional().describe('ADB shell command timeout in milliseconds.')
+});
+const runAdbShellInputSchema = v4_z.strictObject({
+    command: nonBlankText('The shell command to execute, without an adb shell prefix.'),
+    options: runAdbShellOptionsInputSchema.optional()
+});
+const emptyInputSchema = v4_z.strictObject({});
+const launchNode = defineAndroidAgentNode({
+    method: 'launch',
+    description: 'Launch an application through the current Android Agent.',
+    stringInputKey: 'uri',
+    inputSchema: launchInputSchema,
+    toArgs: (input)=>[
+            input.uri
+        ],
+    toResult: (_output, input)=>({
+            summary: `Launched ${input.uri}`
+        })
+});
+const terminateNode = defineAndroidAgentNode({
+    method: 'terminate',
+    description: 'Terminate an application through the current Android Agent.',
+    stringInputKey: 'uri',
+    inputSchema: terminateInputSchema,
+    toArgs: (input)=>[
+            input.uri
+        ],
+    toResult: (_output, input)=>({
+            summary: `Terminated ${input.uri}`
+        })
+});
+const runAdbShellNode = defineAndroidAgentNode({
+    method: 'runAdbShell',
+    title: 'Run an ADB shell command',
+    description: 'Execute a shell command through the current Android Agent. Pass only the shell command, without the adb shell prefix.',
+    stringInputKey: 'command',
+    inputSchema: runAdbShellInputSchema,
+    toArgs (input, context) {
+        context.signal.throwIfAborted();
+        if (/^\s*adb(?:\s|$)/i.test(input.command)) throw new TypeError('command must not include an adb or adb shell prefix.');
+        return [
+            input.command,
+            input.options
+        ];
+    },
+    toResult (stdout) {
+        if ('string' != typeof stdout) throw new TypeError('runAdbShell() must return stdout as a string.');
+        return {
+            summary: `Executed ADB shell command (${stdout.length} stdout characters)`,
+            data: {
+                stdout
+            }
+        };
+    }
+});
+const backNode = defineAndroidAgentNode({
+    method: 'back',
+    description: 'Trigger the Android system back operation.',
+    stringInputKey: false,
+    inputSchema: emptyInputSchema,
+    toArgs: ()=>[],
+    toResult: ()=>({
+            summary: 'Triggered Android back'
+        })
+});
+const homeNode = defineAndroidAgentNode({
+    method: 'home',
+    description: 'Trigger the Android system home operation.',
+    stringInputKey: false,
+    inputSchema: emptyInputSchema,
+    toArgs: ()=>[],
+    toResult: ()=>({
+            summary: 'Triggered Android home'
+        })
+});
+const recentAppsNode = defineAndroidAgentNode({
+    method: 'recentApps',
+    description: 'Trigger the Android system recent apps operation.',
+    stringInputKey: false,
+    inputSchema: emptyInputSchema,
+    toArgs: ()=>[],
+    toResult: ()=>({
+            summary: 'Triggered Android recentApps'
+        })
+});
+const androidAgentTestRunnerNodeDefinitions = [
+    launchNode,
+    terminateNode,
+    runAdbShellNode,
+    backNode,
+    homeNode,
+    recentAppsNode
+];
 const debugUtils = (0, logger_.getDebug)('android:utils');
 const DETAIL_LOOKUP_ADB_TIMEOUT_MS = 8000;
 const DETAIL_LOOKUP_STEP_TIMEOUT_MS = 2000;
@@ -3324,6 +3428,12 @@ function agent_define_property(obj, key, value) {
 }
 const debugAgent = (0, logger_.getDebug)('android:agent');
 class AndroidAgent extends Agent {
+    static getTestRunnerNodeDefinitions() {
+        return [
+            ...Agent.getTestRunnerNodeDefinitions(),
+            ...androidAgentTestRunnerNodeDefinitions
+        ];
+    }
     async launch(uri) {
         const action = this.wrapActionInActionSpace('Launch');
         return action({
@@ -3495,4 +3605,4 @@ class AndroidMidsceneTools extends BaseMidsceneTools {
     }
 }
 var __webpack_exports__resolveExternalResourcePath = resource_path.J;
-export { AndroidAgent, AndroidDevice, AndroidMidsceneTools, ScrcpyDeviceAdapter, agentFromAdbDevice, getConnectedDevices, getConnectedDevicesWithDetails, overrideAIConfig, __webpack_exports__resolveExternalResourcePath as resolveExternalResourcePath };
+export { AndroidAgent, AndroidDevice, AndroidMidsceneTools, ScrcpyDeviceAdapter, agentFromAdbDevice, androidAgentTestRunnerNodeDefinitions, getConnectedDevices, getConnectedDevicesWithDetails, launchInputSchema, overrideAIConfig, runAdbShellInputSchema, runAdbShellOptionsInputSchema, terminateInputSchema, __webpack_exports__resolveExternalResourcePath as resolveExternalResourcePath };

package/dist/es/test-runner.mjs

@@ -0,0 +1,105 @@
+import { createAgentTestRunnerNodeDefinition } from "@midscene/core/agent/test-runner";
+import { z } from "zod/v4";
+const defineAndroidAgentNode = createAgentTestRunnerNodeDefinition('an Android Agent');
+const nonBlankText = (description)=>z.string().regex(/\S/, 'value must contain a non-whitespace character').describe(description);
+const launchInputSchema = z.strictObject({
+    uri: nonBlankText('The app, URL, URI, or package name to launch.')
+});
+const terminateInputSchema = z.strictObject({
+    uri: nonBlankText('The package name or app name to terminate.')
+});
+const runAdbShellOptionsInputSchema = z.strictObject({
+    timeout: z.number().int().positive().optional().describe('ADB shell command timeout in milliseconds.')
+});
+const runAdbShellInputSchema = z.strictObject({
+    command: nonBlankText('The shell command to execute, without an adb shell prefix.'),
+    options: runAdbShellOptionsInputSchema.optional()
+});
+const emptyInputSchema = z.strictObject({});
+const launchNode = defineAndroidAgentNode({
+    method: 'launch',
+    description: 'Launch an application through the current Android Agent.',
+    stringInputKey: 'uri',
+    inputSchema: launchInputSchema,
+    toArgs: (input)=>[
+            input.uri
+        ],
+    toResult: (_output, input)=>({
+            summary: `Launched ${input.uri}`
+        })
+});
+const terminateNode = defineAndroidAgentNode({
+    method: 'terminate',
+    description: 'Terminate an application through the current Android Agent.',
+    stringInputKey: 'uri',
+    inputSchema: terminateInputSchema,
+    toArgs: (input)=>[
+            input.uri
+        ],
+    toResult: (_output, input)=>({
+            summary: `Terminated ${input.uri}`
+        })
+});
+const runAdbShellNode = defineAndroidAgentNode({
+    method: 'runAdbShell',
+    title: 'Run an ADB shell command',
+    description: 'Execute a shell command through the current Android Agent. Pass only the shell command, without the adb shell prefix.',
+    stringInputKey: 'command',
+    inputSchema: runAdbShellInputSchema,
+    toArgs (input, context) {
+        context.signal.throwIfAborted();
+        if (/^\s*adb(?:\s|$)/i.test(input.command)) throw new TypeError('command must not include an adb or adb shell prefix.');
+        return [
+            input.command,
+            input.options
+        ];
+    },
+    toResult (stdout) {
+        if ('string' != typeof stdout) throw new TypeError('runAdbShell() must return stdout as a string.');
+        return {
+            summary: `Executed ADB shell command (${stdout.length} stdout characters)`,
+            data: {
+                stdout
+            }
+        };
+    }
+});
+const backNode = defineAndroidAgentNode({
+    method: 'back',
+    description: 'Trigger the Android system back operation.',
+    stringInputKey: false,
+    inputSchema: emptyInputSchema,
+    toArgs: ()=>[],
+    toResult: ()=>({
+            summary: 'Triggered Android back'
+        })
+});
+const homeNode = defineAndroidAgentNode({
+    method: 'home',
+    description: 'Trigger the Android system home operation.',
+    stringInputKey: false,
+    inputSchema: emptyInputSchema,
+    toArgs: ()=>[],
+    toResult: ()=>({
+            summary: 'Triggered Android home'
+        })
+});
+const recentAppsNode = defineAndroidAgentNode({
+    method: 'recentApps',
+    description: 'Trigger the Android system recent apps operation.',
+    stringInputKey: false,
+    inputSchema: emptyInputSchema,
+    toArgs: ()=>[],
+    toResult: ()=>({
+            summary: 'Triggered Android recentApps'
+        })
+});
+const androidAgentTestRunnerNodeDefinitions = [
+    launchNode,
+    terminateNode,
+    runAdbShellNode,
+    backNode,
+    homeNode,
+    recentAppsNode
+];
+export { androidAgentTestRunnerNodeDefinitions, launchInputSchema, runAdbShellInputSchema, runAdbShellOptionsInputSchema, terminateInputSchema };

package/dist/lib/cli.js

@@ -1017,6 +1017,115 @@ var __webpack_modules__ = {
             }
         }
     },
+    "./src/test-runner-nodes.ts" (__unused_rspack_module, __webpack_exports__, __webpack_require__) {
+        __webpack_require__.d(__webpack_exports__, {
+            androidAgentTestRunnerNodeDefinitions: ()=>androidAgentTestRunnerNodeDefinitions
+        });
+        const test_runner_namespaceObject = require("@midscene/core/agent/test-runner");
+        const v4_namespaceObject = require("zod/v4");
+        const defineAndroidAgentNode = (0, test_runner_namespaceObject.createAgentTestRunnerNodeDefinition)('an Android Agent');
+        const nonBlankText = (description)=>v4_namespaceObject.z.string().regex(/\S/, 'value must contain a non-whitespace character').describe(description);
+        const launchInputSchema = v4_namespaceObject.z.strictObject({
+            uri: nonBlankText('The app, URL, URI, or package name to launch.')
+        });
+        const terminateInputSchema = v4_namespaceObject.z.strictObject({
+            uri: nonBlankText('The package name or app name to terminate.')
+        });
+        const runAdbShellOptionsInputSchema = v4_namespaceObject.z.strictObject({
+            timeout: v4_namespaceObject.z.number().int().positive().optional().describe('ADB shell command timeout in milliseconds.')
+        });
+        const runAdbShellInputSchema = v4_namespaceObject.z.strictObject({
+            command: nonBlankText('The shell command to execute, without an adb shell prefix.'),
+            options: runAdbShellOptionsInputSchema.optional()
+        });
+        const emptyInputSchema = v4_namespaceObject.z.strictObject({});
+        const launchNode = defineAndroidAgentNode({
+            method: 'launch',
+            description: 'Launch an application through the current Android Agent.',
+            stringInputKey: 'uri',
+            inputSchema: launchInputSchema,
+            toArgs: (input)=>[
+                    input.uri
+                ],
+            toResult: (_output, input)=>({
+                    summary: `Launched ${input.uri}`
+                })
+        });
+        const terminateNode = defineAndroidAgentNode({
+            method: 'terminate',
+            description: 'Terminate an application through the current Android Agent.',
+            stringInputKey: 'uri',
+            inputSchema: terminateInputSchema,
+            toArgs: (input)=>[
+                    input.uri
+                ],
+            toResult: (_output, input)=>({
+                    summary: `Terminated ${input.uri}`
+                })
+        });
+        const runAdbShellNode = defineAndroidAgentNode({
+            method: 'runAdbShell',
+            title: 'Run an ADB shell command',
+            description: 'Execute a shell command through the current Android Agent. Pass only the shell command, without the adb shell prefix.',
+            stringInputKey: 'command',
+            inputSchema: runAdbShellInputSchema,
+            toArgs (input, context) {
+                context.signal.throwIfAborted();
+                if (/^\s*adb(?:\s|$)/i.test(input.command)) throw new TypeError('command must not include an adb or adb shell prefix.');
+                return [
+                    input.command,
+                    input.options
+                ];
+            },
+            toResult (stdout) {
+                if ('string' != typeof stdout) throw new TypeError('runAdbShell() must return stdout as a string.');
+                return {
+                    summary: `Executed ADB shell command (${stdout.length} stdout characters)`,
+                    data: {
+                        stdout
+                    }
+                };
+            }
+        });
+        const backNode = defineAndroidAgentNode({
+            method: 'back',
+            description: 'Trigger the Android system back operation.',
+            stringInputKey: false,
+            inputSchema: emptyInputSchema,
+            toArgs: ()=>[],
+            toResult: ()=>({
+                    summary: 'Triggered Android back'
+                })
+        });
+        const homeNode = defineAndroidAgentNode({
+            method: 'home',
+            description: 'Trigger the Android system home operation.',
+            stringInputKey: false,
+            inputSchema: emptyInputSchema,
+            toArgs: ()=>[],
+            toResult: ()=>({
+                    summary: 'Triggered Android home'
+                })
+        });
+        const recentAppsNode = defineAndroidAgentNode({
+            method: 'recentApps',
+            description: 'Trigger the Android system recent apps operation.',
+            stringInputKey: false,
+            inputSchema: emptyInputSchema,
+            toArgs: ()=>[],
+            toResult: ()=>({
+                    summary: 'Triggered Android recentApps'
+                })
+        });
+        const androidAgentTestRunnerNodeDefinitions = [
+            launchNode,
+            terminateNode,
+            runAdbShellNode,
+            backNode,
+            homeNode,
+            recentAppsNode
+        ];
+    },
     "@midscene/shared/img" (module) {
         module.exports = require("@midscene/shared/img");
     },
@@ -3239,6 +3348,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
                 }
             })
         });
+    var test_runner_nodes = __webpack_require__("./src/test-runner-nodes.ts");
     const debugUtils = (0, logger_.getDebug)('android:utils');
     async function getConnectedDevices(deviceOptions) {
         let adbExecutable;
@@ -3271,6 +3381,12 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
     }
     const debugAgent = (0, logger_.getDebug)('android:agent');
     class AndroidAgent extends agent_namespaceObject.Agent {
+        static getTestRunnerNodeDefinitions() {
+            return [
+                ...agent_namespaceObject.Agent.getTestRunnerNodeDefinitions(),
+                ...test_runner_nodes.androidAgentTestRunnerNodeDefinitions
+            ];
+        }
         async launch(uri) {
             const action = this.wrapActionInActionSpace('Launch');
             return action({
@@ -3444,7 +3560,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.12.4-beta-20260903111111.0",
+        version: "1.12.4",
         extraCommands: (0, core_namespaceObject.createReportCliCommands)()
     }).catch((e)=>{
         process.exit((0, cli_namespaceObject.reportCLIError)(e));

package/dist/lib/index.js

@@ -1017,6 +1017,119 @@ var __webpack_modules__ = {
             }
         }
     },
+    "./src/test-runner-nodes.ts" (__unused_rspack_module, __webpack_exports__, __webpack_require__) {
+        __webpack_require__.d(__webpack_exports__, {
+            androidAgentTestRunnerNodeDefinitions: ()=>androidAgentTestRunnerNodeDefinitions,
+            terminateInputSchema: ()=>terminateInputSchema,
+            runAdbShellInputSchema: ()=>runAdbShellInputSchema,
+            runAdbShellOptionsInputSchema: ()=>runAdbShellOptionsInputSchema,
+            launchInputSchema: ()=>launchInputSchema
+        });
+        const test_runner_namespaceObject = require("@midscene/core/agent/test-runner");
+        const v4_namespaceObject = require("zod/v4");
+        const defineAndroidAgentNode = (0, test_runner_namespaceObject.createAgentTestRunnerNodeDefinition)('an Android Agent');
+        const nonBlankText = (description)=>v4_namespaceObject.z.string().regex(/\S/, 'value must contain a non-whitespace character').describe(description);
+        const launchInputSchema = v4_namespaceObject.z.strictObject({
+            uri: nonBlankText('The app, URL, URI, or package name to launch.')
+        });
+        const terminateInputSchema = v4_namespaceObject.z.strictObject({
+            uri: nonBlankText('The package name or app name to terminate.')
+        });
+        const runAdbShellOptionsInputSchema = v4_namespaceObject.z.strictObject({
+            timeout: v4_namespaceObject.z.number().int().positive().optional().describe('ADB shell command timeout in milliseconds.')
+        });
+        const runAdbShellInputSchema = v4_namespaceObject.z.strictObject({
+            command: nonBlankText('The shell command to execute, without an adb shell prefix.'),
+            options: runAdbShellOptionsInputSchema.optional()
+        });
+        const emptyInputSchema = v4_namespaceObject.z.strictObject({});
+        const launchNode = defineAndroidAgentNode({
+            method: 'launch',
+            description: 'Launch an application through the current Android Agent.',
+            stringInputKey: 'uri',
+            inputSchema: launchInputSchema,
+            toArgs: (input)=>[
+                    input.uri
+                ],
+            toResult: (_output, input)=>({
+                    summary: `Launched ${input.uri}`
+                })
+        });
+        const terminateNode = defineAndroidAgentNode({
+            method: 'terminate',
+            description: 'Terminate an application through the current Android Agent.',
+            stringInputKey: 'uri',
+            inputSchema: terminateInputSchema,
+            toArgs: (input)=>[
+                    input.uri
+                ],
+            toResult: (_output, input)=>({
+                    summary: `Terminated ${input.uri}`
+                })
+        });
+        const runAdbShellNode = defineAndroidAgentNode({
+            method: 'runAdbShell',
+            title: 'Run an ADB shell command',
+            description: 'Execute a shell command through the current Android Agent. Pass only the shell command, without the adb shell prefix.',
+            stringInputKey: 'command',
+            inputSchema: runAdbShellInputSchema,
+            toArgs (input, context) {
+                context.signal.throwIfAborted();
+                if (/^\s*adb(?:\s|$)/i.test(input.command)) throw new TypeError('command must not include an adb or adb shell prefix.');
+                return [
+                    input.command,
+                    input.options
+                ];
+            },
+            toResult (stdout) {
+                if ('string' != typeof stdout) throw new TypeError('runAdbShell() must return stdout as a string.');
+                return {
+                    summary: `Executed ADB shell command (${stdout.length} stdout characters)`,
+                    data: {
+                        stdout
+                    }
+                };
+            }
+        });
+        const backNode = defineAndroidAgentNode({
+            method: 'back',
+            description: 'Trigger the Android system back operation.',
+            stringInputKey: false,
+            inputSchema: emptyInputSchema,
+            toArgs: ()=>[],
+            toResult: ()=>({
+                    summary: 'Triggered Android back'
+                })
+        });
+        const homeNode = defineAndroidAgentNode({
+            method: 'home',
+            description: 'Trigger the Android system home operation.',
+            stringInputKey: false,
+            inputSchema: emptyInputSchema,
+            toArgs: ()=>[],
+            toResult: ()=>({
+                    summary: 'Triggered Android home'
+                })
+        });
+        const recentAppsNode = defineAndroidAgentNode({
+            method: 'recentApps',
+            description: 'Trigger the Android system recent apps operation.',
+            stringInputKey: false,
+            inputSchema: emptyInputSchema,
+            toArgs: ()=>[],
+            toResult: ()=>({
+                    summary: 'Triggered Android recentApps'
+                })
+        });
+        const androidAgentTestRunnerNodeDefinitions = [
+            launchNode,
+            terminateNode,
+            runAdbShellNode,
+            backNode,
+            homeNode,
+            recentAppsNode
+        ];
+    },
     "@midscene/shared/img" (module) {
         module.exports = require("@midscene/shared/img");
     },
@@ -1077,14 +1190,19 @@ var __webpack_exports__ = {};
 (()=>{
     __webpack_require__.r(__webpack_exports__);
     __webpack_require__.d(__webpack_exports__, {
+        launchInputSchema: ()=>test_runner_nodes.launchInputSchema,
+        androidAgentTestRunnerNodeDefinitions: ()=>test_runner_nodes.androidAgentTestRunnerNodeDefinitions,
         AndroidAgent: ()=>AndroidAgent,
         agentFromAdbDevice: ()=>agentFromAdbDevice,
-        getConnectedDevicesWithDetails: ()=>getConnectedDevicesWithDetails,
+        runAdbShellInputSchema: ()=>test_runner_nodes.runAdbShellInputSchema,
         ScrcpyDeviceAdapter: ()=>ScrcpyDeviceAdapter,
-        AndroidMidsceneTools: ()=>AndroidMidsceneTools,
         AndroidDevice: ()=>AndroidDevice,
+        AndroidMidsceneTools: ()=>AndroidMidsceneTools,
+        getConnectedDevicesWithDetails: ()=>getConnectedDevicesWithDetails,
         overrideAIConfig: ()=>env_namespaceObject.overrideAIConfig,
         resolveExternalResourcePath: ()=>resource_path.J,
+        terminateInputSchema: ()=>test_runner_nodes.terminateInputSchema,
+        runAdbShellOptionsInputSchema: ()=>test_runner_nodes.runAdbShellOptionsInputSchema,
         getConnectedDevices: ()=>getConnectedDevices
     });
     const external_node_assert_namespaceObject = require("node:assert");
@@ -3258,6 +3376,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         WeChat: 'com.tencent.mm',
         WhatsApp: 'com.whatsapp'
     };
+    var test_runner_nodes = __webpack_require__("./src/test-runner-nodes.ts");
     const debugUtils = (0, logger_.getDebug)('android:utils');
     const DETAIL_LOOKUP_ADB_TIMEOUT_MS = 8000;
     const DETAIL_LOOKUP_STEP_TIMEOUT_MS = 2000;
@@ -3358,6 +3477,12 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
     }
     const debugAgent = (0, logger_.getDebug)('android:agent');
     class AndroidAgent extends agent_namespaceObject.Agent {
+        static getTestRunnerNodeDefinitions() {
+            return [
+                ...agent_namespaceObject.Agent.getTestRunnerNodeDefinitions(),
+                ...test_runner_nodes.androidAgentTestRunnerNodeDefinitions
+            ];
+        }
         async launch(uri) {
             const action = this.wrapActionInActionSpace('Launch');
             return action({
@@ -3536,20 +3661,30 @@ exports.AndroidDevice = __webpack_exports__.AndroidDevice;
 exports.AndroidMidsceneTools = __webpack_exports__.AndroidMidsceneTools;
 exports.ScrcpyDeviceAdapter = __webpack_exports__.ScrcpyDeviceAdapter;
 exports.agentFromAdbDevice = __webpack_exports__.agentFromAdbDevice;
+exports.androidAgentTestRunnerNodeDefinitions = __webpack_exports__.androidAgentTestRunnerNodeDefinitions;
 exports.getConnectedDevices = __webpack_exports__.getConnectedDevices;
 exports.getConnectedDevicesWithDetails = __webpack_exports__.getConnectedDevicesWithDetails;
+exports.launchInputSchema = __webpack_exports__.launchInputSchema;
 exports.overrideAIConfig = __webpack_exports__.overrideAIConfig;
 exports.resolveExternalResourcePath = __webpack_exports__.resolveExternalResourcePath;
+exports.runAdbShellInputSchema = __webpack_exports__.runAdbShellInputSchema;
+exports.runAdbShellOptionsInputSchema = __webpack_exports__.runAdbShellOptionsInputSchema;
+exports.terminateInputSchema = __webpack_exports__.terminateInputSchema;
 for(var __rspack_i in __webpack_exports__)if (-1 === [
     "AndroidAgent",
     "AndroidDevice",
     "AndroidMidsceneTools",
     "ScrcpyDeviceAdapter",
     "agentFromAdbDevice",
+    "androidAgentTestRunnerNodeDefinitions",
     "getConnectedDevices",
     "getConnectedDevicesWithDetails",
+    "launchInputSchema",
     "overrideAIConfig",
-    "resolveExternalResourcePath"
+    "resolveExternalResourcePath",
+    "runAdbShellInputSchema",
+    "runAdbShellOptionsInputSchema",
+    "terminateInputSchema"
 ].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
 Object.defineProperty(exports, '__esModule', {
     value: true

package/dist/lib/test-runner.js

@@ -0,0 +1,151 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.d = (exports1, definition)=>{
+        for(var key in definition)if (__webpack_require__.o(definition, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
+            enumerable: true,
+            get: definition[key]
+        });
+    };
+})();
+(()=>{
+    __webpack_require__.o = (obj, prop)=>Object.prototype.hasOwnProperty.call(obj, prop);
+})();
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ('undefined' != typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+__webpack_require__.d(__webpack_exports__, {
+    androidAgentTestRunnerNodeDefinitions: ()=>androidAgentTestRunnerNodeDefinitions,
+    terminateInputSchema: ()=>terminateInputSchema,
+    runAdbShellInputSchema: ()=>runAdbShellInputSchema,
+    runAdbShellOptionsInputSchema: ()=>runAdbShellOptionsInputSchema,
+    launchInputSchema: ()=>launchInputSchema
+});
+const test_runner_namespaceObject = require("@midscene/core/agent/test-runner");
+const v4_namespaceObject = require("zod/v4");
+const defineAndroidAgentNode = (0, test_runner_namespaceObject.createAgentTestRunnerNodeDefinition)('an Android Agent');
+const nonBlankText = (description)=>v4_namespaceObject.z.string().regex(/\S/, 'value must contain a non-whitespace character').describe(description);
+const launchInputSchema = v4_namespaceObject.z.strictObject({
+    uri: nonBlankText('The app, URL, URI, or package name to launch.')
+});
+const terminateInputSchema = v4_namespaceObject.z.strictObject({
+    uri: nonBlankText('The package name or app name to terminate.')
+});
+const runAdbShellOptionsInputSchema = v4_namespaceObject.z.strictObject({
+    timeout: v4_namespaceObject.z.number().int().positive().optional().describe('ADB shell command timeout in milliseconds.')
+});
+const runAdbShellInputSchema = v4_namespaceObject.z.strictObject({
+    command: nonBlankText('The shell command to execute, without an adb shell prefix.'),
+    options: runAdbShellOptionsInputSchema.optional()
+});
+const emptyInputSchema = v4_namespaceObject.z.strictObject({});
+const launchNode = defineAndroidAgentNode({
+    method: 'launch',
+    description: 'Launch an application through the current Android Agent.',
+    stringInputKey: 'uri',
+    inputSchema: launchInputSchema,
+    toArgs: (input)=>[
+            input.uri
+        ],
+    toResult: (_output, input)=>({
+            summary: `Launched ${input.uri}`
+        })
+});
+const terminateNode = defineAndroidAgentNode({
+    method: 'terminate',
+    description: 'Terminate an application through the current Android Agent.',
+    stringInputKey: 'uri',
+    inputSchema: terminateInputSchema,
+    toArgs: (input)=>[
+            input.uri
+        ],
+    toResult: (_output, input)=>({
+            summary: `Terminated ${input.uri}`
+        })
+});
+const runAdbShellNode = defineAndroidAgentNode({
+    method: 'runAdbShell',
+    title: 'Run an ADB shell command',
+    description: 'Execute a shell command through the current Android Agent. Pass only the shell command, without the adb shell prefix.',
+    stringInputKey: 'command',
+    inputSchema: runAdbShellInputSchema,
+    toArgs (input, context) {
+        context.signal.throwIfAborted();
+        if (/^\s*adb(?:\s|$)/i.test(input.command)) throw new TypeError('command must not include an adb or adb shell prefix.');
+        return [
+            input.command,
+            input.options
+        ];
+    },
+    toResult (stdout) {
+        if ('string' != typeof stdout) throw new TypeError('runAdbShell() must return stdout as a string.');
+        return {
+            summary: `Executed ADB shell command (${stdout.length} stdout characters)`,
+            data: {
+                stdout
+            }
+        };
+    }
+});
+const backNode = defineAndroidAgentNode({
+    method: 'back',
+    description: 'Trigger the Android system back operation.',
+    stringInputKey: false,
+    inputSchema: emptyInputSchema,
+    toArgs: ()=>[],
+    toResult: ()=>({
+            summary: 'Triggered Android back'
+        })
+});
+const homeNode = defineAndroidAgentNode({
+    method: 'home',
+    description: 'Trigger the Android system home operation.',
+    stringInputKey: false,
+    inputSchema: emptyInputSchema,
+    toArgs: ()=>[],
+    toResult: ()=>({
+            summary: 'Triggered Android home'
+        })
+});
+const recentAppsNode = defineAndroidAgentNode({
+    method: 'recentApps',
+    description: 'Trigger the Android system recent apps operation.',
+    stringInputKey: false,
+    inputSchema: emptyInputSchema,
+    toArgs: ()=>[],
+    toResult: ()=>({
+            summary: 'Triggered Android recentApps'
+        })
+});
+const androidAgentTestRunnerNodeDefinitions = [
+    launchNode,
+    terminateNode,
+    runAdbShellNode,
+    backNode,
+    homeNode,
+    recentAppsNode
+];
+exports.androidAgentTestRunnerNodeDefinitions = __webpack_exports__.androidAgentTestRunnerNodeDefinitions;
+exports.launchInputSchema = __webpack_exports__.launchInputSchema;
+exports.runAdbShellInputSchema = __webpack_exports__.runAdbShellInputSchema;
+exports.runAdbShellOptionsInputSchema = __webpack_exports__.runAdbShellOptionsInputSchema;
+exports.terminateInputSchema = __webpack_exports__.terminateInputSchema;
+for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "androidAgentTestRunnerNodeDefinitions",
+    "launchInputSchema",
+    "runAdbShellInputSchema",
+    "runAdbShellOptionsInputSchema",
+    "terminateInputSchema"
+].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/types/index.d.ts

@@ -6,6 +6,8 @@ import type { Adb } from '@yume-chan/adb';
 import { Agent } from '@midscene/core/agent';
 import { AgentBehaviorInitArgs } from '@midscene/shared/agent-tools/agent-behavior-init-args';
 import { AgentOpt } from '@midscene/core/agent';
+import { AgentTestRunnerNodeDefinition } from '@midscene/core/agent';
+import { AgentTestRunnerNodeDefinition as AgentTestRunnerNodeDefinition_2 } from '@midscene/core/agent/test-runner';
 import { AndroidDeviceInputOpt } from '@midscene/core/device';
 import { AndroidDeviceOpt } from '@midscene/core/device';
 import { BaseMidsceneTools } from '@midscene/shared/agent-tools/base-tools';
@@ -20,12 +22,14 @@ import { Point } from '@midscene/core';
 import { Size } from '@midscene/core';
 import type { ToolDefinition } from '@midscene/shared/agent-tools/types';
 import { UITreeSnapshot } from '@midscene/core';
+import { z } from 'zod/v4';
 
 declare type ActionArgs<T extends DeviceAction> = [ActionParam<T>] extends [undefined] ? [] : [ActionParam<T>];
 
 export declare function agentFromAdbDevice(deviceId?: string, opts?: AndroidAgentOpt & AndroidDeviceOpt): Promise<AndroidAgent>;
 
 export declare class AndroidAgent extends Agent<AndroidDevice> {
+    static getTestRunnerNodeDefinitions(): readonly AgentTestRunnerNodeDefinition[];
     /**
      * Trigger the system back operation on Android devices
      */
@@ -70,6 +74,8 @@ export declare type AndroidAgentOpt = AgentOpt & {
     appNameMapping?: Record<string, string>;
 };
 
+export declare const androidAgentTestRunnerNodeDefinitions: readonly AgentTestRunnerNodeDefinition_2[];
+
 export declare interface AndroidConnectedDevice extends Device {
     model?: string;
     brand?: string;
@@ -368,6 +374,12 @@ export declare function getConnectedDevices(deviceOptions?: AndroidDeviceOpt): P
 
 export declare function getConnectedDevicesWithDetails(deviceOptions?: AndroidDeviceOpt): Promise<AndroidConnectedDevice[]>;
 
+export declare const launchInputSchema: z.ZodObject<{
+    uri: z.ZodString;
+}, z.core.$strict>;
+
+export declare type LaunchNodeInput = z.infer<typeof launchInputSchema>;
+
 export { overrideAIConfig }
 
 /**
@@ -404,13 +416,26 @@ export declare function resolveExternalResourcePath(resourcePath: string, pathEx
 
 export declare type ResolveScrcpyAdbBackend = () => ScrcpyAdbBackend | Promise<ScrcpyAdbBackend>;
 
-declare type RunAdbShellOpt = {
+export declare const runAdbShellInputSchema: z.ZodObject<{
+    command: z.ZodString;
+    options: z.ZodOptional<z.ZodObject<{
+        timeout: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+
+export declare type RunAdbShellNodeInput = z.infer<typeof runAdbShellInputSchema>;
+
+export declare type RunAdbShellOpt = {
     /**
      * ADB shell command execution timeout in milliseconds.
      */
     timeout?: number;
 };
 
+export declare const runAdbShellOptionsInputSchema: z.ZodObject<{
+    timeout: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+
 /** ADB capabilities scrcpy needs from the canonical Appium transport. */
 export declare interface ScrcpyAdbBackend {
     adbHost?: string;
@@ -756,6 +781,12 @@ export declare interface ScrcpyStatus {
 
 declare type ScrollDirection = 'up' | 'down' | 'left' | 'right';
 
+export declare const terminateInputSchema: z.ZodObject<{
+    uri: z.ZodString;
+}, z.core.$strict>;
+
+export declare type TerminateNodeInput = z.infer<typeof terminateInputSchema>;
+
 /**
  * Helper type to convert DeviceAction to wrapped method signature
  */

package/dist/types/test-runner.d.ts

@@ -0,0 +1,31 @@
+import { AgentTestRunnerNodeDefinition } from '@midscene/core/agent/test-runner';
+import { z } from 'zod/v4';
+
+export declare const androidAgentTestRunnerNodeDefinitions: readonly AgentTestRunnerNodeDefinition[];
+
+export declare const launchInputSchema: z.ZodObject<{
+    uri: z.ZodString;
+}, z.core.$strict>;
+
+export declare type LaunchNodeInput = z.infer<typeof launchInputSchema>;
+
+export declare const runAdbShellInputSchema: z.ZodObject<{
+    command: z.ZodString;
+    options: z.ZodOptional<z.ZodObject<{
+        timeout: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+
+export declare type RunAdbShellNodeInput = z.infer<typeof runAdbShellInputSchema>;
+
+export declare const runAdbShellOptionsInputSchema: z.ZodObject<{
+    timeout: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+
+export declare const terminateInputSchema: z.ZodObject<{
+    uri: z.ZodString;
+}, z.core.$strict>;
+
+export declare type TerminateNodeInput = z.infer<typeof terminateInputSchema>;
+
+export { }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@midscene/android",
-  "version": "1.12.4-beta-20260903111111.0",
+  "version": "1.12.4",
   "repository": {
     "type": "git",
     "url": "https://github.com/web-infra-dev/midscene.git",
@@ -31,6 +31,11 @@
       "import": "./dist/es/index.mjs",
       "require": "./dist/lib/index.js"
     },
+    "./test-runner": {
+      "types": "./dist/types/test-runner.d.ts",
+      "import": "./dist/es/test-runner.mjs",
+      "require": "./dist/lib/test-runner.js"
+    },
     "./package.json": "./package.json"
   },
   "dependencies": {
@@ -41,8 +46,9 @@
     "@yume-chan/stream-extra": "2.6.1",
     "appium-adb": "12.12.1",
     "sharp": "^0.34.3",
-    "@midscene/core": "1.12.4-beta-20260903111111.0",
-    "@midscene/shared": "1.12.4-beta-20260903111111.0"
+    "zod": "^3.25.1",
+    "@midscene/core": "1.12.4",
+    "@midscene/shared": "1.12.4"
   },
   "optionalDependencies": {
     "@ffmpeg-installer/ffmpeg": "^1.1.0"
@@ -55,8 +61,7 @@
     "tsx": "^4.19.2",
     "typescript": "^5.8.3",
     "undici": "^6.0.0",
-    "zod": "^3.25.1",
-    "@midscene/playground": "1.12.4-beta-20260903111111.0"
+    "@midscene/playground": "1.12.4"
   },
   "license": "MIT",
   "scripts": {