@midscene/shared 1.8.5-beta-20260525033347.0 → 1.8.5

package/dist/lib/env/types.js

@@ -46,6 +46,7 @@ __webpack_require__.d(__webpack_exports__, {
     MIDSCENE_INSIGHT_MODEL_FAMILY: ()=>MIDSCENE_INSIGHT_MODEL_FAMILY,
     MIDSCENE_INSIGHT_MODEL_HTTP_PROXY: ()=>MIDSCENE_INSIGHT_MODEL_HTTP_PROXY,
     MIDSCENE_INSIGHT_MODEL_INIT_CONFIG_JSON: ()=>MIDSCENE_INSIGHT_MODEL_INIT_CONFIG_JSON,
+    MIDSCENE_INSIGHT_MODEL_MAX_TOKENS: ()=>MIDSCENE_INSIGHT_MODEL_MAX_TOKENS,
     MIDSCENE_INSIGHT_MODEL_NAME: ()=>MIDSCENE_INSIGHT_MODEL_NAME,
     MIDSCENE_INSIGHT_MODEL_REASONING_BUDGET: ()=>MIDSCENE_INSIGHT_MODEL_REASONING_BUDGET,
     MIDSCENE_INSIGHT_MODEL_REASONING_EFFORT: ()=>MIDSCENE_INSIGHT_MODEL_REASONING_EFFORT,
@@ -88,6 +89,7 @@ __webpack_require__.d(__webpack_exports__, {
     MIDSCENE_PLANNING_MODEL_FAMILY: ()=>MIDSCENE_PLANNING_MODEL_FAMILY,
     MIDSCENE_PLANNING_MODEL_HTTP_PROXY: ()=>MIDSCENE_PLANNING_MODEL_HTTP_PROXY,
     MIDSCENE_PLANNING_MODEL_INIT_CONFIG_JSON: ()=>MIDSCENE_PLANNING_MODEL_INIT_CONFIG_JSON,
+    MIDSCENE_PLANNING_MODEL_MAX_TOKENS: ()=>MIDSCENE_PLANNING_MODEL_MAX_TOKENS,
     MIDSCENE_PLANNING_MODEL_NAME: ()=>MIDSCENE_PLANNING_MODEL_NAME,
     MIDSCENE_PLANNING_MODEL_REASONING_BUDGET: ()=>MIDSCENE_PLANNING_MODEL_REASONING_BUDGET,
     MIDSCENE_PLANNING_MODEL_REASONING_EFFORT: ()=>MIDSCENE_PLANNING_MODEL_REASONING_EFFORT,
@@ -177,6 +179,7 @@ const MIDSCENE_INSIGHT_MODEL_BASE_URL = 'MIDSCENE_INSIGHT_MODEL_BASE_URL';
 const MIDSCENE_INSIGHT_MODEL_API_KEY = 'MIDSCENE_INSIGHT_MODEL_API_KEY';
 const MIDSCENE_INSIGHT_MODEL_INIT_CONFIG_JSON = 'MIDSCENE_INSIGHT_MODEL_INIT_CONFIG_JSON';
 const MIDSCENE_INSIGHT_MODEL_EXTRA_BODY_JSON = 'MIDSCENE_INSIGHT_MODEL_EXTRA_BODY_JSON';
+const MIDSCENE_INSIGHT_MODEL_MAX_TOKENS = 'MIDSCENE_INSIGHT_MODEL_MAX_TOKENS';
 const MIDSCENE_INSIGHT_MODEL_TIMEOUT = 'MIDSCENE_INSIGHT_MODEL_TIMEOUT';
 const MIDSCENE_INSIGHT_MODEL_TEMPERATURE = 'MIDSCENE_INSIGHT_MODEL_TEMPERATURE';
 const MIDSCENE_INSIGHT_MODEL_RETRY_COUNT = 'MIDSCENE_INSIGHT_MODEL_RETRY_COUNT';
@@ -192,6 +195,7 @@ const MIDSCENE_PLANNING_MODEL_BASE_URL = 'MIDSCENE_PLANNING_MODEL_BASE_URL';
 const MIDSCENE_PLANNING_MODEL_API_KEY = 'MIDSCENE_PLANNING_MODEL_API_KEY';
 const MIDSCENE_PLANNING_MODEL_INIT_CONFIG_JSON = 'MIDSCENE_PLANNING_MODEL_INIT_CONFIG_JSON';
 const MIDSCENE_PLANNING_MODEL_EXTRA_BODY_JSON = 'MIDSCENE_PLANNING_MODEL_EXTRA_BODY_JSON';
+const MIDSCENE_PLANNING_MODEL_MAX_TOKENS = 'MIDSCENE_PLANNING_MODEL_MAX_TOKENS';
 const MIDSCENE_PLANNING_MODEL_TIMEOUT = 'MIDSCENE_PLANNING_MODEL_TIMEOUT';
 const MIDSCENE_PLANNING_MODEL_TEMPERATURE = 'MIDSCENE_PLANNING_MODEL_TEMPERATURE';
 const MIDSCENE_PLANNING_MODEL_RETRY_COUNT = 'MIDSCENE_PLANNING_MODEL_RETRY_COUNT';
@@ -219,13 +223,10 @@ const BOOLEAN_ENV_KEYS = [
     MIDSCENE_REPORT_QUIET
 ];
 const NUMBER_ENV_KEYS = [
-    MIDSCENE_MODEL_MAX_TOKENS,
     MIDSCENE_CACHE_MAX_FILENAME_LENGTH,
     MIDSCENE_REPLANNING_CYCLE_LIMIT
 ];
 const STRING_ENV_KEYS = [
-    MIDSCENE_MODEL_MAX_TOKENS,
-    OPENAI_MAX_TOKENS,
     MIDSCENE_ADB_PATH,
     MIDSCENE_ADB_REMOTE_HOST,
     MIDSCENE_ADB_REMOTE_PORT,
@@ -251,6 +252,7 @@ const MODEL_ENV_KEYS = [
     MIDSCENE_MODEL_BASE_URL,
     MIDSCENE_MODEL_SOCKS_PROXY,
     MIDSCENE_MODEL_HTTP_PROXY,
+    MIDSCENE_MODEL_MAX_TOKENS,
     MIDSCENE_MODEL_TIMEOUT,
     MIDSCENE_MODEL_TEMPERATURE,
     MIDSCENE_MODEL_RETRY_COUNT,
@@ -266,6 +268,7 @@ const MODEL_ENV_KEYS = [
     MIDSCENE_USE_VL_MODEL,
     OPENAI_API_KEY,
     OPENAI_BASE_URL,
+    OPENAI_MAX_TOKENS,
     MIDSCENE_OPENAI_INIT_CONFIG_JSON,
     MIDSCENE_OPENAI_HTTP_PROXY,
     MIDSCENE_OPENAI_SOCKS_PROXY,
@@ -276,6 +279,7 @@ const MODEL_ENV_KEYS = [
     MIDSCENE_INSIGHT_MODEL_API_KEY,
     MIDSCENE_INSIGHT_MODEL_INIT_CONFIG_JSON,
     MIDSCENE_INSIGHT_MODEL_EXTRA_BODY_JSON,
+    MIDSCENE_INSIGHT_MODEL_MAX_TOKENS,
     MIDSCENE_INSIGHT_MODEL_TIMEOUT,
     MIDSCENE_INSIGHT_MODEL_TEMPERATURE,
     MIDSCENE_INSIGHT_MODEL_RETRY_COUNT,
@@ -291,6 +295,7 @@ const MODEL_ENV_KEYS = [
     MIDSCENE_PLANNING_MODEL_API_KEY,
     MIDSCENE_PLANNING_MODEL_INIT_CONFIG_JSON,
     MIDSCENE_PLANNING_MODEL_EXTRA_BODY_JSON,
+    MIDSCENE_PLANNING_MODEL_MAX_TOKENS,
     MIDSCENE_PLANNING_MODEL_TIMEOUT,
     MIDSCENE_PLANNING_MODEL_TEMPERATURE,
     MIDSCENE_PLANNING_MODEL_RETRY_COUNT,
@@ -352,6 +357,7 @@ exports.MIDSCENE_INSIGHT_MODEL_EXTRA_BODY_JSON = __webpack_exports__.MIDSCENE_IN
 exports.MIDSCENE_INSIGHT_MODEL_FAMILY = __webpack_exports__.MIDSCENE_INSIGHT_MODEL_FAMILY;
 exports.MIDSCENE_INSIGHT_MODEL_HTTP_PROXY = __webpack_exports__.MIDSCENE_INSIGHT_MODEL_HTTP_PROXY;
 exports.MIDSCENE_INSIGHT_MODEL_INIT_CONFIG_JSON = __webpack_exports__.MIDSCENE_INSIGHT_MODEL_INIT_CONFIG_JSON;
+exports.MIDSCENE_INSIGHT_MODEL_MAX_TOKENS = __webpack_exports__.MIDSCENE_INSIGHT_MODEL_MAX_TOKENS;
 exports.MIDSCENE_INSIGHT_MODEL_NAME = __webpack_exports__.MIDSCENE_INSIGHT_MODEL_NAME;
 exports.MIDSCENE_INSIGHT_MODEL_REASONING_BUDGET = __webpack_exports__.MIDSCENE_INSIGHT_MODEL_REASONING_BUDGET;
 exports.MIDSCENE_INSIGHT_MODEL_REASONING_EFFORT = __webpack_exports__.MIDSCENE_INSIGHT_MODEL_REASONING_EFFORT;
@@ -394,6 +400,7 @@ exports.MIDSCENE_PLANNING_MODEL_EXTRA_BODY_JSON = __webpack_exports__.MIDSCENE_P
 exports.MIDSCENE_PLANNING_MODEL_FAMILY = __webpack_exports__.MIDSCENE_PLANNING_MODEL_FAMILY;
 exports.MIDSCENE_PLANNING_MODEL_HTTP_PROXY = __webpack_exports__.MIDSCENE_PLANNING_MODEL_HTTP_PROXY;
 exports.MIDSCENE_PLANNING_MODEL_INIT_CONFIG_JSON = __webpack_exports__.MIDSCENE_PLANNING_MODEL_INIT_CONFIG_JSON;
+exports.MIDSCENE_PLANNING_MODEL_MAX_TOKENS = __webpack_exports__.MIDSCENE_PLANNING_MODEL_MAX_TOKENS;
 exports.MIDSCENE_PLANNING_MODEL_NAME = __webpack_exports__.MIDSCENE_PLANNING_MODEL_NAME;
 exports.MIDSCENE_PLANNING_MODEL_REASONING_BUDGET = __webpack_exports__.MIDSCENE_PLANNING_MODEL_REASONING_BUDGET;
 exports.MIDSCENE_PLANNING_MODEL_REASONING_EFFORT = __webpack_exports__.MIDSCENE_PLANNING_MODEL_REASONING_EFFORT;
@@ -446,6 +453,7 @@ for(var __rspack_i in __webpack_exports__)if (-1 === [
     "MIDSCENE_INSIGHT_MODEL_FAMILY",
     "MIDSCENE_INSIGHT_MODEL_HTTP_PROXY",
     "MIDSCENE_INSIGHT_MODEL_INIT_CONFIG_JSON",
+    "MIDSCENE_INSIGHT_MODEL_MAX_TOKENS",
     "MIDSCENE_INSIGHT_MODEL_NAME",
     "MIDSCENE_INSIGHT_MODEL_REASONING_BUDGET",
     "MIDSCENE_INSIGHT_MODEL_REASONING_EFFORT",
@@ -488,6 +496,7 @@ for(var __rspack_i in __webpack_exports__)if (-1 === [
     "MIDSCENE_PLANNING_MODEL_FAMILY",
     "MIDSCENE_PLANNING_MODEL_HTTP_PROXY",
     "MIDSCENE_PLANNING_MODEL_INIT_CONFIG_JSON",
+    "MIDSCENE_PLANNING_MODEL_MAX_TOKENS",
     "MIDSCENE_PLANNING_MODEL_NAME",
     "MIDSCENE_PLANNING_MODEL_REASONING_BUDGET",
     "MIDSCENE_PLANNING_MODEL_REASONING_EFFORT",

package/dist/lib/mcp/tool-generator.js

@@ -24,13 +24,15 @@ var __webpack_require__ = {};
 var __webpack_exports__ = {};
 __webpack_require__.r(__webpack_exports__);
 __webpack_require__.d(__webpack_exports__, {
+    generateCommonTools: ()=>generateCommonTools,
     generateToolsFromActionSpace: ()=>generateToolsFromActionSpace,
-    generateCommonTools: ()=>generateCommonTools
+    composeUserPrompt: ()=>external_user_prompt_js_namespaceObject.composeUserPrompt
 });
 const img_namespaceObject = require("@midscene/shared/img");
 const external_zod_namespaceObject = require("zod");
 const external_zod_schema_utils_js_namespaceObject = require("../zod-schema-utils.js");
 const external_error_formatter_js_namespaceObject = require("./error-formatter.js");
+const external_user_prompt_js_namespaceObject = require("./user-prompt.js");
 function describeActionForMCP(action) {
     const actionDesc = action.description || `Execute ${action.name} action`;
     if (!action.paramSchema) return `${action.name} action, ${actionDesc}`;
@@ -365,6 +367,9 @@ function generateCommonTools(getAgent, initArgSchema = {}, initArgCliMetadata) {
                     const agent = await getAgent(args);
                     const screenshot = await agent.page?.screenshotBase64();
                     if (!screenshot) return createErrorResult('Screenshot not available');
+                    await agent.recordToReport?.('take_screenshot', {
+                        screenshotBase64: screenshot
+                    });
                     const { mimeType, body } = (0, img_namespaceObject.parseBase64)(screenshot);
                     return {
                         content: [
@@ -398,15 +403,7 @@ function generateCommonTools(getAgent, initArgSchema = {}, initArgCliMetadata) {
                     const result = await agent.aiAction(prompt, {
                         deepThink: false
                     });
-                    const screenshotResult = await captureScreenshotResult(agent, 'act');
-                    if (result) {
-                        const message = 'string' == typeof result ? result : JSON.stringify(result);
-                        screenshotResult.content.unshift({
-                            type: 'text',
-                            text: `Task finished, message: ${message}`
-                        });
-                    }
-                    return screenshotResult;
+                    return await captureScreenshotResult(agent, 'act', result);
                 } catch (error) {
                     const errorMessage = (0, external_error_formatter_js_namespaceObject.getErrorMessage)(error);
                     console.error('Error executing act:', errorMessage);
@@ -419,6 +416,7 @@ function generateCommonTools(getAgent, initArgSchema = {}, initArgCliMetadata) {
             description: 'Assert a natural language statement against the current page/screen.',
             schema: {
                 prompt: external_zod_namespaceObject.z.string().describe('Natural language assertion to verify, e.g. "there is a login button visible"'),
+                ...external_user_prompt_js_namespaceObject.promptInputExtraSchema,
                 ...initArgSchema
             },
             cli: mergeToolCliMetadata(void 0, initArgCliMetadata),
@@ -427,7 +425,13 @@ function generateCommonTools(getAgent, initArgSchema = {}, initArgCliMetadata) {
                 try {
                     const agent = await getAgent(args);
                     if (!agent.aiAssert) return createErrorResult('assert is not supported by this agent');
-                    await agent.aiAssert(prompt);
+                    const userPrompt = (0, external_user_prompt_js_namespaceObject.composeUserPrompt)({
+                        prompt,
+                        image: args.image,
+                        imageName: args.imageName,
+                        convertHttpImage2Base64: args.convertHttpImage2Base64
+                    });
+                    await agent.aiAssert(userPrompt);
                     return {
                         content: [
                             {
@@ -445,9 +449,11 @@ function generateCommonTools(getAgent, initArgSchema = {}, initArgCliMetadata) {
         }
     ];
 }
+exports.composeUserPrompt = __webpack_exports__.composeUserPrompt;
 exports.generateCommonTools = __webpack_exports__.generateCommonTools;
 exports.generateToolsFromActionSpace = __webpack_exports__.generateToolsFromActionSpace;
 for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "composeUserPrompt",
     "generateCommonTools",
     "generateToolsFromActionSpace"
 ].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];

package/dist/lib/mcp/user-prompt.js

@@ -0,0 +1,103 @@
+"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__, {
+    promptInputExtraSchema: ()=>promptInputExtraSchema,
+    composeUserPrompt: ()=>composeUserPrompt
+});
+const external_zod_namespaceObject = require("zod");
+function normalizeStringList(raw, fieldName) {
+    if (null == raw) return [];
+    if ('string' == typeof raw) {
+        const trimmed = raw.trim();
+        return trimmed ? [
+            trimmed
+        ] : [];
+    }
+    if (Array.isArray(raw)) return raw.map((item, index)=>{
+        if ('string' != typeof item) throw new Error(`${fieldName}[${index}]: expected a string.`);
+        return item.trim();
+    });
+    throw new Error(`${fieldName}: expected a string or string array, got ${typeof raw}.`);
+}
+function composeImages(input) {
+    const urls = normalizeStringList(input.image, 'image');
+    const names = normalizeStringList(input.imageName, 'imageName');
+    if (urls.length !== names.length) throw new Error(`image/imageName: expected the same number of --image and --image-name values, got ${urls.length} image(s) and ${names.length} image name(s).`);
+    return urls.map((url, index)=>({
+            name: names[index],
+            url
+        }));
+}
+function coerceBoolean(value) {
+    if (null == value) return;
+    if ('boolean' == typeof value) return value;
+    if ('string' == typeof value) {
+        const trimmed = value.trim();
+        if (!trimmed) return;
+        const v = trimmed.toLowerCase();
+        if ('true' === v || '1' === v) return true;
+        if ('false' === v || '0' === v) return false;
+        throw new Error(`convertHttpImage2Base64: expected "true", "false", "1", or "0"; got ${JSON.stringify(value)}.`);
+    }
+    throw new Error(`convertHttpImage2Base64: expected a boolean, got ${typeof value}.`);
+}
+function composeUserPrompt(input) {
+    const images = composeImages({
+        image: input.image,
+        imageName: input.imageName
+    });
+    const convertFlag = coerceBoolean(input.convertHttpImage2Base64);
+    if (0 === images.length && void 0 === convertFlag) return input.prompt;
+    const payload = {
+        prompt: input.prompt
+    };
+    if (images.length > 0) payload.images = images;
+    if (void 0 !== convertFlag) payload.convertHttpImage2Base64 = convertFlag;
+    return payload;
+}
+const promptInputExtraSchema = {
+    image: external_zod_namespaceObject.z.union([
+        external_zod_namespaceObject.z.string(),
+        external_zod_namespaceObject.z.array(external_zod_namespaceObject.z.string())
+    ]).optional().describe('Reference image URL/path. Repeat --image for multiple images.'),
+    imageName: external_zod_namespaceObject.z.union([
+        external_zod_namespaceObject.z.string(),
+        external_zod_namespaceObject.z.array(external_zod_namespaceObject.z.string())
+    ]).optional().describe('Reference image name. Repeat --image-name; must align with --image order.'),
+    convertHttpImage2Base64: external_zod_namespaceObject.z.union([
+        external_zod_namespaceObject.z.boolean(),
+        external_zod_namespaceObject.z.string()
+    ]).optional().describe('If true, convert http(s) image URLs to base64 before sending to the model.')
+};
+exports.composeUserPrompt = __webpack_exports__.composeUserPrompt;
+exports.promptInputExtraSchema = __webpack_exports__.promptInputExtraSchema;
+for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "composeUserPrompt",
+    "promptInputExtraSchema"
+].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/types/cli/cli-args.d.ts

@@ -6,3 +6,11 @@ export declare function getCliOptionDisplay(key: string, cliOption?: ToolCliOpti
     aliases: string[];
 };
 export declare function formatCliValidationError(scriptName: string, commandName: string, def: ToolDefinition, rawArgs: Record<string, unknown>): string | undefined;
+/**
+ * Move CLI args parsed under accepted alias spellings (kebab-case, alternate
+ * casings, `cli.options.aliases` entries) onto the schema's canonical key so
+ * tool handlers can read them with a single field name regardless of which
+ * spelling the user typed. Throws `CLIError` on conflicting double-spellings
+ * (e.g. both `--imageName` and `--image-name`).
+ */
+export declare function canonicalizeCliArgKeys(scriptName: string, commandName: string, def: ToolDefinition, rawArgs: Record<string, unknown>): Record<string, unknown>;

package/dist/types/constants/example-code.d.ts

@@ -1,2 +1,2 @@
-export declare const PLAYWRIGHT_EXAMPLE_CODE = "\n// Reference the following code to generate Midscene test cases\n// The following is test code for Midscene AI, for reference\n// The following is Playwright syntax, you can use Playwright to assist in test generation\nIMPORTANT: Follow these exact type signatures for AI functions:\n\n// Type signatures for AI functions:\naiAct(prompt: string, options?: { cacheable?: boolean, deepThink?: 'unset' | true | false }): Promise<void>\naiInput(text: string, locate: string, options?: { deepLocate?: boolean, xpath?: string, cacheable?: boolean }): Promise<void>\naiTap(locate: string, options?: { deepLocate?: boolean, xpath?: string, cacheable?: boolean }): Promise<void>\naiHover(locate: string, options?: { deepLocate?: boolean, xpath?: string, cacheable?: boolean }): Promise<void>\naiDoubleClick(locate: string, options?: { deepLocate?: boolean, xpath?: string, cacheable?: boolean }): Promise<void>\naiKeyboardPress(key: string, locate?: string, options?: { deepLocate?: boolean, xpath?: string, cacheable?: boolean }): Promise<void>\naiScroll(locate: string | undefined, options: {\n  direction?: 'up' | 'down' | 'left' | 'right',\n  scrollType?: 'singleAction' | 'scrollToBottom' | 'scrollToTop' | 'scrollToRight' | 'scrollToLeft',\n  distance?: number | null,\n  deepLocate?: boolean,\n  xpath?: string,\n  cacheable?: boolean\n}): Promise<void>\naiAssert(assertion: string, options?: { errorMessage?: string }): Promise<void>\naiWaitFor(prompt: string, options?: { timeout?: number }): Promise<void>\naiQuery<T>(queryObject: Record<string, string>): Promise<T> // Extracts data from page based on descriptions\n\n// examples:\n// Reference the following code to generate Midscene test cases\n// The following is test code for Midscene AI, for reference\n// The following is Playwright syntax, you can use Playwright to assist in test generation\nimport { test as base } from '@playwright/test';\nimport type { PlayWrightAiFixtureType } from '@midscene/web/playwright';\nimport { PlaywrightAiFixture } from '@midscene/web/playwright';\n\nconst test = base.extend<PlayWrightAiFixtureType>(PlaywrightAiFixture({\n  waitForNetworkIdleTimeout: 2000, // optional, the timeout for waiting for network idle between each action, default is 2000ms\n}));\n\n\ntest.beforeEach(async ({ page }) => {\n  await page.goto('https://www.xxx.com/');\n  await page.setViewportSize({ width: 1920, height: 1080 });\n});\n\ntest('ai shop', async ({\n  aiAct,\n  aiInput,\n  aiAssert,\n  aiQuery,\n  aiKeyboardPress,\n  aiHover,\n  aiTap,\n  aiWaitFor,\n  agentForPage,\n  page,\n}) => {\n  // login\n  await aiAssert('The page shows the login interface');\n  await aiInput('user_name', 'in user name input');\n  await aiInput('password', 'in password input');\n  await aiKeyboardPress('Enter', 'Login Button');\n\n  // check the login success\n  await aiWaitFor('The page shows that the loading is complete');\n  await aiAssert('The current page shows the product detail page');\n\n  // check the product info\n  const dataA = await aiQuery({\n    userInfo: 'User information in the format {name: string}',\n    theFirstProductInfo: 'The first product info in the format {name: string, price: number}',\n  });\n  expect(dataA.theFirstProductInfo.name).toBe('xxx');\n  expect(dataA.theFirstProductInfo.price).toBe(100);\n\n\n  // add to cart\n  await aiTap('click add to cart button');\n  \n  await aiTap('click right top cart icon');\n  await aiAssert('The cart icon shows the number 1');\n});\n";
+export declare const PLAYWRIGHT_EXAMPLE_CODE = "\n// Reference the following code to generate Midscene test cases\n// The following is test code for Midscene AI, for reference\n// The following is Playwright syntax, you can use Playwright to assist in test generation\nIMPORTANT: Follow these exact type signatures for AI functions:\n\n// Type signatures for AI functions:\naiAct(prompt: string, options?: { cacheable?: boolean, deepThink?: 'unset' | true | false }): Promise<string | undefined>\naiInput(text: string, locate: string, options?: { deepLocate?: boolean, xpath?: string, cacheable?: boolean }): Promise<void>\naiTap(locate: string, options?: { deepLocate?: boolean, xpath?: string, cacheable?: boolean }): Promise<void>\naiHover(locate: string, options?: { deepLocate?: boolean, xpath?: string, cacheable?: boolean }): Promise<void>\naiDoubleClick(locate: string, options?: { deepLocate?: boolean, xpath?: string, cacheable?: boolean }): Promise<void>\naiKeyboardPress(key: string, locate?: string, options?: { deepLocate?: boolean, xpath?: string, cacheable?: boolean }): Promise<void>\naiScroll(locate: string | undefined, options: {\n  direction?: 'up' | 'down' | 'left' | 'right',\n  scrollType?: 'singleAction' | 'scrollToBottom' | 'scrollToTop' | 'scrollToRight' | 'scrollToLeft',\n  distance?: number | null,\n  deepLocate?: boolean,\n  xpath?: string,\n  cacheable?: boolean\n}): Promise<void>\naiAssert(assertion: string, options?: { errorMessage?: string }): Promise<void>\naiWaitFor(prompt: string, options?: { timeout?: number }): Promise<void>\naiQuery<T>(queryObject: Record<string, string>): Promise<T> // Extracts data from page based on descriptions\n\n// examples:\n// Reference the following code to generate Midscene test cases\n// The following is test code for Midscene AI, for reference\n// The following is Playwright syntax, you can use Playwright to assist in test generation\nimport { test as base } from '@playwright/test';\nimport type { PlayWrightAiFixtureType } from '@midscene/web/playwright';\nimport { PlaywrightAiFixture } from '@midscene/web/playwright';\n\nconst test = base.extend<PlayWrightAiFixtureType>(PlaywrightAiFixture({\n  waitForNetworkIdleTimeout: 2000, // optional, the timeout for waiting for network idle between each action, default is 2000ms\n}));\n\n\ntest.beforeEach(async ({ page }) => {\n  await page.goto('https://www.xxx.com/');\n  await page.setViewportSize({ width: 1920, height: 1080 });\n});\n\ntest('ai shop', async ({\n  aiAct,\n  aiInput,\n  aiAssert,\n  aiQuery,\n  aiKeyboardPress,\n  aiHover,\n  aiTap,\n  aiWaitFor,\n  agentForPage,\n  page,\n}) => {\n  // login\n  await aiAssert('The page shows the login interface');\n  await aiInput('user_name', 'in user name input');\n  await aiInput('password', 'in password input');\n  await aiKeyboardPress('Enter', 'Login Button');\n\n  // check the login success\n  await aiWaitFor('The page shows that the loading is complete');\n  await aiAssert('The current page shows the product detail page');\n\n  // check the product info\n  const dataA = await aiQuery({\n    userInfo: 'User information in the format {name: string}',\n    theFirstProductInfo: 'The first product info in the format {name: string, price: number}',\n  });\n  expect(dataA.theFirstProductInfo.name).toBe('xxx');\n  expect(dataA.theFirstProductInfo.price).toBe(100);\n\n\n  // add to cart\n  await aiTap('click add to cart button');\n  \n  await aiTap('click right top cart icon');\n  await aiAssert('The cart icon shows the number 1');\n});\n";
 export declare const YAML_EXAMPLE_CODE = "\nCRITICAL - YAML Indentation Rules:\nFor actions with additional parameters (aiScroll, aiInput, aiKeyboardPress), the parameters must be SIBLING keys at the SAME indentation level as the action key, NOT nested children indented further.\nCORRECT (parameters align with the action key):\n      - aiScroll:\n        direction: 'down'\n        scrollType: 'singleAction'\n        distance: 500\n        locate: \"main content area\"\n      - aiInput: 'text value'\n        locate: 'input field description'\nWRONG (parameters are indented further than the action key, DO NOT do this):\n      - aiScroll:\n          direction: 'down'\n          scrollType: 'singleAction'\n      - aiInput: 'text value'\n          locate: 'input field description'\n\n1. Format:\n\nweb:\n  url: \"starting_url\"\n  viewportWidth: 1280\n  viewportHeight: 960\n\ntasks:\n  - name: \"descriptive task name\"\n    flow:\n      - aiTap: \"element description\"\n        xpath: '/html/body/div[1]/button[1]'\n      - aiInput: 'text value'\n        locate: 'input field description'\n        xpath: '/html/body/div[1]/input[1]'\n      - aiScroll:\n        direction: 'down'\n        scrollType: 'singleAction'\n        distance: 500\n        locate: \"scrollable area description\"\n        xpath: '/html/body/div[1]/main[1]'\n      - aiAssert: \"expected state\"\n      - sleep: 1000\n\n2. Action Types:\n- aiTap: for clicks (natural language targeting)\n- aiInput: for text input with 'locate' field\n- aiScroll: with direction and scrollType\n- aiAssert: for validations\n- sleep: for delays (milliseconds)\n\n\n\nYAML type\ntasks:\n  - name: <name>\n    continueOnError: <boolean> # Optional, whether to continue to the next task on error, defaults to false.\n    flow:\n      # Auto Planning (.ai)\n      # ----------------\n\n      # Perform an interaction. `ai` is a shorthand for `aiAct`.\n      - ai: <prompt>\n        cacheable: <boolean> # Optional, whether to cache the result of this API call when the [caching feature](./caching.mdx) is enabled. Defaults to True.\n\n      # This usage is the same as `ai`.\n      - aiAct: <prompt>\n        cacheable: <boolean> # Optional, whether to cache the result of this API call when the [caching feature](./caching.mdx) is enabled. Defaults to True.\n\n      # Instant Action (.aiTap, .aiDoubleClick, .aiHover, .aiInput, .aiKeyboardPress, .aiScroll)\n      # ----------------\n\n      # Tap an element described by a prompt.\n      - aiTap: <prompt>\n        deepLocate: <boolean> # Optional, whether to use deepLocate to precisely locate the element. Defaults to False.\n        xpath: <xpath> # Optional, the xpath of the target element for the operation. If provided, Midscene will prioritize this xpath to find the element before using the cache and the AI model. Defaults to empty.\n        cacheable: <boolean> # Optional, whether to cache the result of this API call when the [caching feature](./caching.mdx) is enabled. Defaults to True.\n\n      # Double click an element described by a prompt.\n      - aiDoubleClick: <prompt>\n        deepLocate: <boolean> # Optional, whether to use deepLocate to precisely locate the element. Defaults to False.\n        xpath: <xpath> # Optional, the xpath of the target element for the operation. If provided, Midscene will prioritize this xpath to find the element before using the cache and the AI model. Defaults to empty.\n        cacheable: <boolean> # Optional, whether to cache the result of this API call when the [caching feature](./caching.mdx) is enabled. Defaults to True.\n\n      # Hover over an element described by a prompt.\n      - aiHover: <prompt>\n        deepLocate: <boolean> # Optional, whether to use deepLocate to precisely locate the element. Defaults to False.\n        xpath: <xpath> # Optional, the xpath of the target element for the operation. If provided, Midscene will prioritize this xpath to find the element before using the cache and the AI model. Defaults to empty.\n        cacheable: <boolean> # Optional, whether to cache the result of this API call when the [caching feature](./caching.mdx) is enabled. Defaults to True.\n\n      # Input text into an element described by a prompt.\n      - aiInput: <final text content of the input>\n        locate: <prompt>\n        deepLocate: <boolean> # Optional, whether to use deepLocate to precisely locate the element. Defaults to False.\n        xpath: <xpath> # Optional, the xpath of the target element for the operation. If provided, Midscene will prioritize this xpath to find the element before using the cache and the AI model. Defaults to empty.\n        cacheable: <boolean> # Optional, whether to cache the result of this API call when the [caching feature](./caching.mdx) is enabled. Defaults to True.\n\n      # Press a key (e.g., Enter, Tab, Escape) on an element described by a prompt.\n      - aiKeyboardPress: <key>\n        locate: <prompt>\n        deepLocate: <boolean> # Optional, whether to use deepLocate to precisely locate the element. Defaults to False.\n        xpath: <xpath> # Optional, the xpath of the target element for the operation. If provided, Midscene will prioritize this xpath to find the element before using the cache and the AI model. Defaults to empty.\n        cacheable: <boolean> # Optional, whether to cache the result of this API call when the [caching feature](./caching.mdx) is enabled. Defaults to True.\n\n      # Scroll globally or on an element described by a prompt.\n      - aiScroll:\n        direction: 'up' # or 'down' | 'left' | 'right'\n        scrollType: 'singleAction' # or 'scrollToTop' | 'scrollToBottom' | 'scrollToLeft' | 'scrollToRight'\n        distance: <number> # Optional, the scroll distance in pixels.\n        locate: <prompt> # Optional, the element to scroll on.\n        deepLocate: <boolean> # Optional, whether to use deepLocate to precisely locate the element. Defaults to False.\n        xpath: <xpath> # Optional, the xpath of the target element for the operation. If provided, Midscene will prioritize this xpath to find the element before using the cache and the AI model. Defaults to empty.\n        cacheable: <boolean> # Optional, whether to cache the result of this API call when the [caching feature](./caching.mdx) is enabled. Defaults to True.\n\n      # Record the current screenshot with a description in the report file.\n      - recordToReport: <title> # Optional, the title of the screenshot. If not provided, the title will be 'untitled'.\n        content: <content> # Optional, the description of the screenshot.\n\n      # Data Extraction\n      # ----------------\n\n      # Perform a query that returns a JSON object.\n      - aiQuery: <prompt> # Remember to describe the format of the result in the prompt.\n        name: <name> # The key for the query result in the JSON output.\n\n      # More APIs\n      # ----------------\n\n      # Wait for a condition to be met, with a timeout (in ms, optional, defaults to 30000).\n      - aiWaitFor: <prompt>\n        timeout: <ms>\n\n      # Perform an assertion.\n      - aiAssert: <prompt>\n        errorMessage: <error-message> # Optional, the error message to print if the assertion fails.\n\n      # Wait for a specified amount of time.\n      - sleep: <ms>\n\n      # Execute a piece of JavaScript code in the web page context.\n      - javascript: <javascript>\n        name: <name> # Optional, assign a name to the return value, which will be used as a key in the JSON output.\n\n  - name: <name>\n    flow:\n      # ...\n";

package/dist/types/env/constants.d.ts

@@ -12,6 +12,7 @@ interface IModelConfigKeys {
     openaiApiKey: string;
     openaiExtraConfig: string;
     extraBody: string;
+    maxTokens: string;
     /**
      * Extra
      */

package/dist/types/env/types.d.ts

@@ -75,6 +75,7 @@ export declare const MIDSCENE_INSIGHT_MODEL_BASE_URL = "MIDSCENE_INSIGHT_MODEL_B
 export declare const MIDSCENE_INSIGHT_MODEL_API_KEY = "MIDSCENE_INSIGHT_MODEL_API_KEY";
 export declare const MIDSCENE_INSIGHT_MODEL_INIT_CONFIG_JSON = "MIDSCENE_INSIGHT_MODEL_INIT_CONFIG_JSON";
 export declare const MIDSCENE_INSIGHT_MODEL_EXTRA_BODY_JSON = "MIDSCENE_INSIGHT_MODEL_EXTRA_BODY_JSON";
+export declare const MIDSCENE_INSIGHT_MODEL_MAX_TOKENS = "MIDSCENE_INSIGHT_MODEL_MAX_TOKENS";
 export declare const MIDSCENE_INSIGHT_MODEL_TIMEOUT = "MIDSCENE_INSIGHT_MODEL_TIMEOUT";
 export declare const MIDSCENE_INSIGHT_MODEL_TEMPERATURE = "MIDSCENE_INSIGHT_MODEL_TEMPERATURE";
 export declare const MIDSCENE_INSIGHT_MODEL_RETRY_COUNT = "MIDSCENE_INSIGHT_MODEL_RETRY_COUNT";
@@ -90,6 +91,7 @@ export declare const MIDSCENE_PLANNING_MODEL_BASE_URL = "MIDSCENE_PLANNING_MODEL
 export declare const MIDSCENE_PLANNING_MODEL_API_KEY = "MIDSCENE_PLANNING_MODEL_API_KEY";
 export declare const MIDSCENE_PLANNING_MODEL_INIT_CONFIG_JSON = "MIDSCENE_PLANNING_MODEL_INIT_CONFIG_JSON";
 export declare const MIDSCENE_PLANNING_MODEL_EXTRA_BODY_JSON = "MIDSCENE_PLANNING_MODEL_EXTRA_BODY_JSON";
+export declare const MIDSCENE_PLANNING_MODEL_MAX_TOKENS = "MIDSCENE_PLANNING_MODEL_MAX_TOKENS";
 export declare const MIDSCENE_PLANNING_MODEL_TIMEOUT = "MIDSCENE_PLANNING_MODEL_TIMEOUT";
 export declare const MIDSCENE_PLANNING_MODEL_TEMPERATURE = "MIDSCENE_PLANNING_MODEL_TEMPERATURE";
 export declare const MIDSCENE_PLANNING_MODEL_RETRY_COUNT = "MIDSCENE_PLANNING_MODEL_RETRY_COUNT";
@@ -109,21 +111,21 @@ export declare const UNUSED_ENV_KEYS: string[];
  */
 export declare const BASIC_ENV_KEYS: readonly ["MIDSCENE_DEBUG_MODE", "MIDSCENE_DEBUG_MODEL_PROFILE", "MIDSCENE_DEBUG_MODEL_RESPONSE", "MIDSCENE_RUN_DIR"];
 export declare const BOOLEAN_ENV_KEYS: readonly ["MIDSCENE_CACHE", "MIDSCENE_MCP_USE_PUPPETEER_MODE", "MIDSCENE_MCP_ANDROID_MODE", "MIDSCENE_LANGSMITH_DEBUG", "MIDSCENE_LANGFUSE_DEBUG", "MIDSCENE_REPORT_QUIET"];
-export declare const NUMBER_ENV_KEYS: readonly ["MIDSCENE_MODEL_MAX_TOKENS", "MIDSCENE_CACHE_MAX_FILENAME_LENGTH", "MIDSCENE_REPLANNING_CYCLE_LIMIT"];
-export declare const STRING_ENV_KEYS: readonly ["MIDSCENE_MODEL_MAX_TOKENS", "OPENAI_MAX_TOKENS", "MIDSCENE_ADB_PATH", "MIDSCENE_ADB_REMOTE_HOST", "MIDSCENE_ADB_REMOTE_PORT", "MIDSCENE_ANDROID_IME_STRATEGY", "MIDSCENE_IOS_DEVICE_UDID", "MIDSCENE_IOS_SIMULATOR_UDID", "MIDSCENE_REPORT_TAG_NAME", "MIDSCENE_PREFERRED_LANGUAGE", "MATCH_BY_POSITION", "MIDSCENE_MCP_CHROME_PATH", "DOCKER_CONTAINER"];
+export declare const NUMBER_ENV_KEYS: readonly ["MIDSCENE_CACHE_MAX_FILENAME_LENGTH", "MIDSCENE_REPLANNING_CYCLE_LIMIT"];
+export declare const STRING_ENV_KEYS: readonly ["MIDSCENE_ADB_PATH", "MIDSCENE_ADB_REMOTE_HOST", "MIDSCENE_ADB_REMOTE_PORT", "MIDSCENE_ANDROID_IME_STRATEGY", "MIDSCENE_IOS_DEVICE_UDID", "MIDSCENE_IOS_SIMULATOR_UDID", "MIDSCENE_REPORT_TAG_NAME", "MIDSCENE_PREFERRED_LANGUAGE", "MATCH_BY_POSITION", "MIDSCENE_MCP_CHROME_PATH", "DOCKER_CONTAINER"];
 /**
  * Non model related env keys, used for globally controlling the behavior of midscene
  * Can not be override by agent.modelConfig but can be override by overrideAIConfig
  * Can be access at any time
  */
-export declare const GLOBAL_ENV_KEYS: readonly ["MIDSCENE_CACHE", "MIDSCENE_MCP_USE_PUPPETEER_MODE", "MIDSCENE_MCP_ANDROID_MODE", "MIDSCENE_LANGSMITH_DEBUG", "MIDSCENE_LANGFUSE_DEBUG", "MIDSCENE_REPORT_QUIET", "MIDSCENE_MODEL_MAX_TOKENS", "MIDSCENE_CACHE_MAX_FILENAME_LENGTH", "MIDSCENE_REPLANNING_CYCLE_LIMIT", "MIDSCENE_MODEL_MAX_TOKENS", "OPENAI_MAX_TOKENS", "MIDSCENE_ADB_PATH", "MIDSCENE_ADB_REMOTE_HOST", "MIDSCENE_ADB_REMOTE_PORT", "MIDSCENE_ANDROID_IME_STRATEGY", "MIDSCENE_IOS_DEVICE_UDID", "MIDSCENE_IOS_SIMULATOR_UDID", "MIDSCENE_REPORT_TAG_NAME", "MIDSCENE_PREFERRED_LANGUAGE", "MATCH_BY_POSITION", "MIDSCENE_MCP_CHROME_PATH", "DOCKER_CONTAINER"];
+export declare const GLOBAL_ENV_KEYS: readonly ["MIDSCENE_CACHE", "MIDSCENE_MCP_USE_PUPPETEER_MODE", "MIDSCENE_MCP_ANDROID_MODE", "MIDSCENE_LANGSMITH_DEBUG", "MIDSCENE_LANGFUSE_DEBUG", "MIDSCENE_REPORT_QUIET", "MIDSCENE_CACHE_MAX_FILENAME_LENGTH", "MIDSCENE_REPLANNING_CYCLE_LIMIT", "MIDSCENE_ADB_PATH", "MIDSCENE_ADB_REMOTE_HOST", "MIDSCENE_ADB_REMOTE_PORT", "MIDSCENE_ANDROID_IME_STRATEGY", "MIDSCENE_IOS_DEVICE_UDID", "MIDSCENE_IOS_SIMULATOR_UDID", "MIDSCENE_REPORT_TAG_NAME", "MIDSCENE_PREFERRED_LANGUAGE", "MATCH_BY_POSITION", "MIDSCENE_MCP_CHROME_PATH", "DOCKER_CONTAINER"];
 /**
  * Model related eve keys, used for declare which model to use.
  * Can be override by both agent.modelConfig and overrideAIConfig
  * Can only be access after agent.constructor
  */
-export declare const MODEL_ENV_KEYS: readonly ["MIDSCENE_MODEL_NAME", "MIDSCENE_MODEL_INIT_CONFIG_JSON", "MIDSCENE_MODEL_EXTRA_BODY_JSON", "MIDSCENE_MODEL_API_KEY", "MIDSCENE_MODEL_BASE_URL", "MIDSCENE_MODEL_SOCKS_PROXY", "MIDSCENE_MODEL_HTTP_PROXY", "MIDSCENE_MODEL_TIMEOUT", "MIDSCENE_MODEL_TEMPERATURE", "MIDSCENE_MODEL_RETRY_COUNT", "MIDSCENE_MODEL_RETRY_INTERVAL", "MIDSCENE_MODEL_REASONING_EFFORT", "MIDSCENE_MODEL_REASONING_ENABLED", "MIDSCENE_MODEL_REASONING_BUDGET", "MIDSCENE_USE_VLM_UI_TARS", "MIDSCENE_USE_QWEN_VL", "MIDSCENE_USE_QWEN3_VL", "MIDSCENE_USE_DOUBAO_VISION", "MIDSCENE_USE_GEMINI", "MIDSCENE_USE_VL_MODEL", "OPENAI_API_KEY", "OPENAI_BASE_URL", "MIDSCENE_OPENAI_INIT_CONFIG_JSON", "MIDSCENE_OPENAI_HTTP_PROXY", "MIDSCENE_OPENAI_SOCKS_PROXY", "MIDSCENE_INSIGHT_MODEL_NAME", "MIDSCENE_INSIGHT_MODEL_SOCKS_PROXY", "MIDSCENE_INSIGHT_MODEL_HTTP_PROXY", "MIDSCENE_INSIGHT_MODEL_BASE_URL", "MIDSCENE_INSIGHT_MODEL_API_KEY", "MIDSCENE_INSIGHT_MODEL_INIT_CONFIG_JSON", "MIDSCENE_INSIGHT_MODEL_EXTRA_BODY_JSON", "MIDSCENE_INSIGHT_MODEL_TIMEOUT", "MIDSCENE_INSIGHT_MODEL_TEMPERATURE", "MIDSCENE_INSIGHT_MODEL_RETRY_COUNT", "MIDSCENE_INSIGHT_MODEL_RETRY_INTERVAL", "MIDSCENE_INSIGHT_MODEL_FAMILY", "MIDSCENE_INSIGHT_MODEL_REASONING_EFFORT", "MIDSCENE_INSIGHT_MODEL_REASONING_ENABLED", "MIDSCENE_INSIGHT_MODEL_REASONING_BUDGET", "MIDSCENE_PLANNING_MODEL_NAME", "MIDSCENE_PLANNING_MODEL_SOCKS_PROXY", "MIDSCENE_PLANNING_MODEL_HTTP_PROXY", "MIDSCENE_PLANNING_MODEL_BASE_URL", "MIDSCENE_PLANNING_MODEL_API_KEY", "MIDSCENE_PLANNING_MODEL_INIT_CONFIG_JSON", "MIDSCENE_PLANNING_MODEL_EXTRA_BODY_JSON", "MIDSCENE_PLANNING_MODEL_TIMEOUT", "MIDSCENE_PLANNING_MODEL_TEMPERATURE", "MIDSCENE_PLANNING_MODEL_RETRY_COUNT", "MIDSCENE_PLANNING_MODEL_RETRY_INTERVAL", "MIDSCENE_PLANNING_MODEL_FAMILY", "MIDSCENE_PLANNING_MODEL_REASONING_EFFORT", "MIDSCENE_PLANNING_MODEL_REASONING_ENABLED", "MIDSCENE_PLANNING_MODEL_REASONING_BUDGET", "MIDSCENE_MODEL_FAMILY"];
-export declare const ALL_ENV_KEYS: readonly [...string[], "MIDSCENE_DEBUG_MODE", "MIDSCENE_DEBUG_MODEL_PROFILE", "MIDSCENE_DEBUG_MODEL_RESPONSE", "MIDSCENE_RUN_DIR", "MIDSCENE_CACHE", "MIDSCENE_MCP_USE_PUPPETEER_MODE", "MIDSCENE_MCP_ANDROID_MODE", "MIDSCENE_LANGSMITH_DEBUG", "MIDSCENE_LANGFUSE_DEBUG", "MIDSCENE_REPORT_QUIET", "MIDSCENE_MODEL_MAX_TOKENS", "MIDSCENE_CACHE_MAX_FILENAME_LENGTH", "MIDSCENE_REPLANNING_CYCLE_LIMIT", "MIDSCENE_MODEL_MAX_TOKENS", "OPENAI_MAX_TOKENS", "MIDSCENE_ADB_PATH", "MIDSCENE_ADB_REMOTE_HOST", "MIDSCENE_ADB_REMOTE_PORT", "MIDSCENE_ANDROID_IME_STRATEGY", "MIDSCENE_IOS_DEVICE_UDID", "MIDSCENE_IOS_SIMULATOR_UDID", "MIDSCENE_REPORT_TAG_NAME", "MIDSCENE_PREFERRED_LANGUAGE", "MATCH_BY_POSITION", "MIDSCENE_MCP_CHROME_PATH", "DOCKER_CONTAINER", "MIDSCENE_MODEL_NAME", "MIDSCENE_MODEL_INIT_CONFIG_JSON", "MIDSCENE_MODEL_EXTRA_BODY_JSON", "MIDSCENE_MODEL_API_KEY", "MIDSCENE_MODEL_BASE_URL", "MIDSCENE_MODEL_SOCKS_PROXY", "MIDSCENE_MODEL_HTTP_PROXY", "MIDSCENE_MODEL_TIMEOUT", "MIDSCENE_MODEL_TEMPERATURE", "MIDSCENE_MODEL_RETRY_COUNT", "MIDSCENE_MODEL_RETRY_INTERVAL", "MIDSCENE_MODEL_REASONING_EFFORT", "MIDSCENE_MODEL_REASONING_ENABLED", "MIDSCENE_MODEL_REASONING_BUDGET", "MIDSCENE_USE_VLM_UI_TARS", "MIDSCENE_USE_QWEN_VL", "MIDSCENE_USE_QWEN3_VL", "MIDSCENE_USE_DOUBAO_VISION", "MIDSCENE_USE_GEMINI", "MIDSCENE_USE_VL_MODEL", "OPENAI_API_KEY", "OPENAI_BASE_URL", "MIDSCENE_OPENAI_INIT_CONFIG_JSON", "MIDSCENE_OPENAI_HTTP_PROXY", "MIDSCENE_OPENAI_SOCKS_PROXY", "MIDSCENE_INSIGHT_MODEL_NAME", "MIDSCENE_INSIGHT_MODEL_SOCKS_PROXY", "MIDSCENE_INSIGHT_MODEL_HTTP_PROXY", "MIDSCENE_INSIGHT_MODEL_BASE_URL", "MIDSCENE_INSIGHT_MODEL_API_KEY", "MIDSCENE_INSIGHT_MODEL_INIT_CONFIG_JSON", "MIDSCENE_INSIGHT_MODEL_EXTRA_BODY_JSON", "MIDSCENE_INSIGHT_MODEL_TIMEOUT", "MIDSCENE_INSIGHT_MODEL_TEMPERATURE", "MIDSCENE_INSIGHT_MODEL_RETRY_COUNT", "MIDSCENE_INSIGHT_MODEL_RETRY_INTERVAL", "MIDSCENE_INSIGHT_MODEL_FAMILY", "MIDSCENE_INSIGHT_MODEL_REASONING_EFFORT", "MIDSCENE_INSIGHT_MODEL_REASONING_ENABLED", "MIDSCENE_INSIGHT_MODEL_REASONING_BUDGET", "MIDSCENE_PLANNING_MODEL_NAME", "MIDSCENE_PLANNING_MODEL_SOCKS_PROXY", "MIDSCENE_PLANNING_MODEL_HTTP_PROXY", "MIDSCENE_PLANNING_MODEL_BASE_URL", "MIDSCENE_PLANNING_MODEL_API_KEY", "MIDSCENE_PLANNING_MODEL_INIT_CONFIG_JSON", "MIDSCENE_PLANNING_MODEL_EXTRA_BODY_JSON", "MIDSCENE_PLANNING_MODEL_TIMEOUT", "MIDSCENE_PLANNING_MODEL_TEMPERATURE", "MIDSCENE_PLANNING_MODEL_RETRY_COUNT", "MIDSCENE_PLANNING_MODEL_RETRY_INTERVAL", "MIDSCENE_PLANNING_MODEL_FAMILY", "MIDSCENE_PLANNING_MODEL_REASONING_EFFORT", "MIDSCENE_PLANNING_MODEL_REASONING_ENABLED", "MIDSCENE_PLANNING_MODEL_REASONING_BUDGET", "MIDSCENE_MODEL_FAMILY"];
+export declare const MODEL_ENV_KEYS: readonly ["MIDSCENE_MODEL_NAME", "MIDSCENE_MODEL_INIT_CONFIG_JSON", "MIDSCENE_MODEL_EXTRA_BODY_JSON", "MIDSCENE_MODEL_API_KEY", "MIDSCENE_MODEL_BASE_URL", "MIDSCENE_MODEL_SOCKS_PROXY", "MIDSCENE_MODEL_HTTP_PROXY", "MIDSCENE_MODEL_MAX_TOKENS", "MIDSCENE_MODEL_TIMEOUT", "MIDSCENE_MODEL_TEMPERATURE", "MIDSCENE_MODEL_RETRY_COUNT", "MIDSCENE_MODEL_RETRY_INTERVAL", "MIDSCENE_MODEL_REASONING_EFFORT", "MIDSCENE_MODEL_REASONING_ENABLED", "MIDSCENE_MODEL_REASONING_BUDGET", "MIDSCENE_USE_VLM_UI_TARS", "MIDSCENE_USE_QWEN_VL", "MIDSCENE_USE_QWEN3_VL", "MIDSCENE_USE_DOUBAO_VISION", "MIDSCENE_USE_GEMINI", "MIDSCENE_USE_VL_MODEL", "OPENAI_API_KEY", "OPENAI_BASE_URL", "OPENAI_MAX_TOKENS", "MIDSCENE_OPENAI_INIT_CONFIG_JSON", "MIDSCENE_OPENAI_HTTP_PROXY", "MIDSCENE_OPENAI_SOCKS_PROXY", "MIDSCENE_INSIGHT_MODEL_NAME", "MIDSCENE_INSIGHT_MODEL_SOCKS_PROXY", "MIDSCENE_INSIGHT_MODEL_HTTP_PROXY", "MIDSCENE_INSIGHT_MODEL_BASE_URL", "MIDSCENE_INSIGHT_MODEL_API_KEY", "MIDSCENE_INSIGHT_MODEL_INIT_CONFIG_JSON", "MIDSCENE_INSIGHT_MODEL_EXTRA_BODY_JSON", "MIDSCENE_INSIGHT_MODEL_MAX_TOKENS", "MIDSCENE_INSIGHT_MODEL_TIMEOUT", "MIDSCENE_INSIGHT_MODEL_TEMPERATURE", "MIDSCENE_INSIGHT_MODEL_RETRY_COUNT", "MIDSCENE_INSIGHT_MODEL_RETRY_INTERVAL", "MIDSCENE_INSIGHT_MODEL_FAMILY", "MIDSCENE_INSIGHT_MODEL_REASONING_EFFORT", "MIDSCENE_INSIGHT_MODEL_REASONING_ENABLED", "MIDSCENE_INSIGHT_MODEL_REASONING_BUDGET", "MIDSCENE_PLANNING_MODEL_NAME", "MIDSCENE_PLANNING_MODEL_SOCKS_PROXY", "MIDSCENE_PLANNING_MODEL_HTTP_PROXY", "MIDSCENE_PLANNING_MODEL_BASE_URL", "MIDSCENE_PLANNING_MODEL_API_KEY", "MIDSCENE_PLANNING_MODEL_INIT_CONFIG_JSON", "MIDSCENE_PLANNING_MODEL_EXTRA_BODY_JSON", "MIDSCENE_PLANNING_MODEL_MAX_TOKENS", "MIDSCENE_PLANNING_MODEL_TIMEOUT", "MIDSCENE_PLANNING_MODEL_TEMPERATURE", "MIDSCENE_PLANNING_MODEL_RETRY_COUNT", "MIDSCENE_PLANNING_MODEL_RETRY_INTERVAL", "MIDSCENE_PLANNING_MODEL_FAMILY", "MIDSCENE_PLANNING_MODEL_REASONING_EFFORT", "MIDSCENE_PLANNING_MODEL_REASONING_ENABLED", "MIDSCENE_PLANNING_MODEL_REASONING_BUDGET", "MIDSCENE_MODEL_FAMILY"];
+export declare const ALL_ENV_KEYS: readonly [...string[], "MIDSCENE_DEBUG_MODE", "MIDSCENE_DEBUG_MODEL_PROFILE", "MIDSCENE_DEBUG_MODEL_RESPONSE", "MIDSCENE_RUN_DIR", "MIDSCENE_CACHE", "MIDSCENE_MCP_USE_PUPPETEER_MODE", "MIDSCENE_MCP_ANDROID_MODE", "MIDSCENE_LANGSMITH_DEBUG", "MIDSCENE_LANGFUSE_DEBUG", "MIDSCENE_REPORT_QUIET", "MIDSCENE_CACHE_MAX_FILENAME_LENGTH", "MIDSCENE_REPLANNING_CYCLE_LIMIT", "MIDSCENE_ADB_PATH", "MIDSCENE_ADB_REMOTE_HOST", "MIDSCENE_ADB_REMOTE_PORT", "MIDSCENE_ANDROID_IME_STRATEGY", "MIDSCENE_IOS_DEVICE_UDID", "MIDSCENE_IOS_SIMULATOR_UDID", "MIDSCENE_REPORT_TAG_NAME", "MIDSCENE_PREFERRED_LANGUAGE", "MATCH_BY_POSITION", "MIDSCENE_MCP_CHROME_PATH", "DOCKER_CONTAINER", "MIDSCENE_MODEL_NAME", "MIDSCENE_MODEL_INIT_CONFIG_JSON", "MIDSCENE_MODEL_EXTRA_BODY_JSON", "MIDSCENE_MODEL_API_KEY", "MIDSCENE_MODEL_BASE_URL", "MIDSCENE_MODEL_SOCKS_PROXY", "MIDSCENE_MODEL_HTTP_PROXY", "MIDSCENE_MODEL_MAX_TOKENS", "MIDSCENE_MODEL_TIMEOUT", "MIDSCENE_MODEL_TEMPERATURE", "MIDSCENE_MODEL_RETRY_COUNT", "MIDSCENE_MODEL_RETRY_INTERVAL", "MIDSCENE_MODEL_REASONING_EFFORT", "MIDSCENE_MODEL_REASONING_ENABLED", "MIDSCENE_MODEL_REASONING_BUDGET", "MIDSCENE_USE_VLM_UI_TARS", "MIDSCENE_USE_QWEN_VL", "MIDSCENE_USE_QWEN3_VL", "MIDSCENE_USE_DOUBAO_VISION", "MIDSCENE_USE_GEMINI", "MIDSCENE_USE_VL_MODEL", "OPENAI_API_KEY", "OPENAI_BASE_URL", "OPENAI_MAX_TOKENS", "MIDSCENE_OPENAI_INIT_CONFIG_JSON", "MIDSCENE_OPENAI_HTTP_PROXY", "MIDSCENE_OPENAI_SOCKS_PROXY", "MIDSCENE_INSIGHT_MODEL_NAME", "MIDSCENE_INSIGHT_MODEL_SOCKS_PROXY", "MIDSCENE_INSIGHT_MODEL_HTTP_PROXY", "MIDSCENE_INSIGHT_MODEL_BASE_URL", "MIDSCENE_INSIGHT_MODEL_API_KEY", "MIDSCENE_INSIGHT_MODEL_INIT_CONFIG_JSON", "MIDSCENE_INSIGHT_MODEL_EXTRA_BODY_JSON", "MIDSCENE_INSIGHT_MODEL_MAX_TOKENS", "MIDSCENE_INSIGHT_MODEL_TIMEOUT", "MIDSCENE_INSIGHT_MODEL_TEMPERATURE", "MIDSCENE_INSIGHT_MODEL_RETRY_COUNT", "MIDSCENE_INSIGHT_MODEL_RETRY_INTERVAL", "MIDSCENE_INSIGHT_MODEL_FAMILY", "MIDSCENE_INSIGHT_MODEL_REASONING_EFFORT", "MIDSCENE_INSIGHT_MODEL_REASONING_ENABLED", "MIDSCENE_INSIGHT_MODEL_REASONING_BUDGET", "MIDSCENE_PLANNING_MODEL_NAME", "MIDSCENE_PLANNING_MODEL_SOCKS_PROXY", "MIDSCENE_PLANNING_MODEL_HTTP_PROXY", "MIDSCENE_PLANNING_MODEL_BASE_URL", "MIDSCENE_PLANNING_MODEL_API_KEY", "MIDSCENE_PLANNING_MODEL_INIT_CONFIG_JSON", "MIDSCENE_PLANNING_MODEL_EXTRA_BODY_JSON", "MIDSCENE_PLANNING_MODEL_MAX_TOKENS", "MIDSCENE_PLANNING_MODEL_TIMEOUT", "MIDSCENE_PLANNING_MODEL_TEMPERATURE", "MIDSCENE_PLANNING_MODEL_RETRY_COUNT", "MIDSCENE_PLANNING_MODEL_RETRY_INTERVAL", "MIDSCENE_PLANNING_MODEL_FAMILY", "MIDSCENE_PLANNING_MODEL_REASONING_EFFORT", "MIDSCENE_PLANNING_MODEL_REASONING_ENABLED", "MIDSCENE_PLANNING_MODEL_REASONING_BUDGET", "MIDSCENE_MODEL_FAMILY"];
 export type TEnvKeys = (typeof ALL_ENV_KEYS)[number];
 export type TGlobalConfig = Record<TEnvKeys, string | undefined>;
 /**
@@ -139,6 +141,7 @@ export interface IModelConfigForInsight {
     [MIDSCENE_INSIGHT_MODEL_API_KEY]?: string;
     [MIDSCENE_INSIGHT_MODEL_INIT_CONFIG_JSON]?: string;
     [MIDSCENE_INSIGHT_MODEL_EXTRA_BODY_JSON]?: string;
+    [MIDSCENE_INSIGHT_MODEL_MAX_TOKENS]?: string;
     [MIDSCENE_INSIGHT_MODEL_TIMEOUT]?: string;
     [MIDSCENE_INSIGHT_MODEL_TEMPERATURE]?: string;
     [MIDSCENE_INSIGHT_MODEL_FAMILY]?: TModelFamily;
@@ -151,6 +154,7 @@ export interface IModelConfigForPlanning {
     [MIDSCENE_PLANNING_MODEL_API_KEY]?: string;
     [MIDSCENE_PLANNING_MODEL_INIT_CONFIG_JSON]?: string;
     [MIDSCENE_PLANNING_MODEL_EXTRA_BODY_JSON]?: string;
+    [MIDSCENE_PLANNING_MODEL_MAX_TOKENS]?: string;
     [MIDSCENE_PLANNING_MODEL_TIMEOUT]?: string;
     [MIDSCENE_PLANNING_MODEL_TEMPERATURE]?: string;
     [MIDSCENE_PLANNING_MODEL_FAMILY]?: TModelFamily;
@@ -171,6 +175,7 @@ export interface IModelConfigForDefault {
     [MIDSCENE_MODEL_API_KEY]?: string;
     [MIDSCENE_MODEL_INIT_CONFIG_JSON]?: string;
     [MIDSCENE_MODEL_EXTRA_BODY_JSON]?: string;
+    [MIDSCENE_MODEL_MAX_TOKENS]?: string;
     [MIDSCENE_MODEL_FAMILY]?: TModelFamily;
     [MIDSCENE_MODEL_TEMPERATURE]?: string;
     [MIDSCENE_MODEL_REASONING_EFFORT]?: string;
@@ -184,6 +189,7 @@ export interface IModelConfigForDefaultLegacy {
     [OPENAI_BASE_URL]?: string;
     [OPENAI_API_KEY]?: string;
     [MIDSCENE_OPENAI_INIT_CONFIG_JSON]?: string;
+    [OPENAI_MAX_TOKENS]?: string;
 }
 /**
  * - insight: Visual Question Answering and Visual Grounding (unified)
@@ -252,6 +258,10 @@ export interface IModelConfig {
      * Example: { "chat_template_kwargs": { "enable_thinking": true } }
      */
     extraBody?: Record<string, unknown>;
+    /**
+     * max_tokens for model responses.
+     */
+    maxTokens?: number;
     /**
      * Timeout for API calls in milliseconds.
      * If not set, uses OpenAI SDK default (10 minutes).

package/dist/types/mcp/tool-generator.d.ts

@@ -1,4 +1,6 @@
 import type { ActionSpaceItem, BaseAgent, ToolCliMetadata, ToolDefinition, ToolSchema } from './types';
+import { composeUserPrompt } from './user-prompt';
+export { composeUserPrompt };
 /**
  * Converts DeviceAction from actionSpace into MCP ToolDefinition
  * This is the core logic that removes need for hardcoded tool definitions

package/dist/types/mcp/types.d.ts

@@ -80,6 +80,22 @@ export interface ActionSpaceItem {
     args?: Record<string, unknown>;
     paramSchema?: z.ZodTypeAny;
 }
+/**
+ * Structural shape compatible with @midscene/core `TUserPrompt`.
+ * Declared locally to avoid a circular dep on `@midscene/core` from `@midscene/shared`.
+ *
+ * Currently consumed only by the `assert` tool in `generateCommonTools`.
+ * `aiAction` and `aiWaitFor` stay string-only at the CLI surface because the
+ * tools generator does not yet expose multimodal entry points for them.
+ */
+export type UserPromptLike = string | {
+    prompt: string;
+    images?: Array<{
+        name: string;
+        url: string;
+    }>;
+    convertHttpImage2Base64?: boolean;
+};
 /**
  * Base agent interface
  * Represents a platform-specific agent (Android, iOS, Web)
@@ -91,10 +107,14 @@ export interface BaseAgent {
     page?: {
         screenshotBase64(): Promise<string>;
     };
+    recordToReport?: (title?: string, opt?: {
+        content?: string;
+        screenshotBase64?: string;
+    }) => Promise<void>;
     callActionInActionSpace?: (actionName: string, params?: unknown) => Promise<unknown>;
     aiAction?: (description: string, params?: Record<string, unknown>) => Promise<unknown>;
     aiWaitFor?: (assertion: string, options: Record<string, unknown>) => Promise<unknown>;
-    aiAssert?: (assertion: string, msg?: string, options?: Record<string, unknown>) => Promise<unknown>;
+    aiAssert?: (assertion: UserPromptLike, msg?: string, options?: Record<string, unknown>) => Promise<unknown>;
 }
 /**
  * Base device interface for temporary device instances

package/dist/types/mcp/user-prompt.d.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+import type { UserPromptLike } from './types';
+export declare function composeUserPrompt(input: {
+    prompt: string;
+    image?: unknown;
+    imageName?: unknown;
+    convertHttpImage2Base64?: unknown;
+}): UserPromptLike;
+export declare const promptInputExtraSchema: {
+    image: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>>;
+    imageName: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>>;
+    convertHttpImage2Base64: z.ZodOptional<z.ZodUnion<[z.ZodBoolean, z.ZodString]>>;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@midscene/shared",
-  "version": "1.8.5-beta-20260525033347.0",
+  "version": "1.8.5",
   "repository": "https://github.com/web-infra-dev/midscene",
   "homepage": "https://midscenejs.com/",
   "types": "./dist/types/index.d.ts",

package/src/cli/cli-args.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { getKeyAliases } from '../key-alias-utils';
 import type { ToolCliOption, ToolDefinition } from '../mcp/types';
+import { CLIError } from './cli-error';
 
 export function parseValue(raw: string): unknown {
   if (raw.startsWith('{') || raw.startsWith('[')) {
@@ -44,7 +45,19 @@ export function parseCliArgs(args: string[]): Record<string, unknown> {
   const result: Record<string, unknown> = {};
 
   walkCliArgs(args, (key, value) => {
-    result[key] = value;
+    const existing = result[key];
+    if (existing === undefined) {
+      result[key] = value;
+      return;
+    }
+
+    if (Array.isArray(existing)) {
+      existing.push(value);
+      result[key] = existing;
+      return;
+    }
+
+    result[key] = [existing, value];
   });
 
   return result;
@@ -171,3 +184,54 @@ export function formatCliValidationError(
     typeof issue?.path[0] === 'string' ? `--${issue.path[0]}` : 'CLI arguments';
   return `Invalid value for "${optionName}" in ${scriptName} ${commandName}: ${issue?.message ?? parsed.error.message}`;
 }
+
+/**
+ * Move CLI args parsed under accepted alias spellings (kebab-case, alternate
+ * casings, `cli.options.aliases` entries) onto the schema's canonical key so
+ * tool handlers can read them with a single field name regardless of which
+ * spelling the user typed. Throws `CLIError` on conflicting double-spellings
+ * (e.g. both `--imageName` and `--image-name`).
+ */
+export function canonicalizeCliArgKeys(
+  scriptName: string,
+  commandName: string,
+  def: ToolDefinition,
+  rawArgs: Record<string, unknown>,
+): Record<string, unknown> {
+  if (Object.keys(def.schema).length === 0) return rawArgs;
+
+  const result: Record<string, unknown> = { ...rawArgs };
+
+  for (const schemaKey of Object.keys(def.schema)) {
+    const cliOption = def.cli?.options?.[schemaKey];
+    const acceptedSpellings = getAcceptedCliOptionNames(schemaKey, cliOption);
+
+    let chosenSpelling: string | undefined;
+    let chosenValue: unknown;
+
+    for (const spelling of acceptedSpellings) {
+      if (spelling === schemaKey) continue;
+      if (!(spelling in result)) continue;
+      if (chosenSpelling !== undefined) {
+        throw new CLIError(
+          `Conflicting CLI options "--${chosenSpelling}" and "--${spelling}" for ${scriptName} ${commandName}: both target "${schemaKey}". Use one spelling.`,
+        );
+      }
+      chosenSpelling = spelling;
+      chosenValue = result[spelling];
+    }
+
+    if (chosenSpelling === undefined) continue;
+
+    if (schemaKey in result && result[schemaKey] !== chosenValue) {
+      throw new CLIError(
+        `Conflicting CLI options "--${schemaKey}" and "--${chosenSpelling}" for ${scriptName} ${commandName}: both target "${schemaKey}". Use one spelling.`,
+      );
+    }
+
+    result[schemaKey] = chosenValue;
+    delete result[chosenSpelling];
+  }
+
+  return result;
+}

package/src/cli/cli-runner.ts

@@ -10,6 +10,7 @@ import type {
   ToolResultContent,
 } from '../mcp/types';
 import {
+  canonicalizeCliArgKeys,
   formatCliValidationError,
   getCliOptionDisplay,
   parseCliArgs,
@@ -214,9 +215,16 @@ export async function runToolsCLI(
     throw new CLIError(cliValidationError);
   }
 
-  debug('command: %s, args: %s', match.name, JSON.stringify(parsedArgs));
+  const handlerArgs = canonicalizeCliArgKeys(
+    scriptName,
+    match.name,
+    match.def,
+    parsedArgs,
+  );
+
+  debug('command: %s, args: %s', match.name, JSON.stringify(handlerArgs));
 
-  const result = await match.def.handler(parsedArgs);
+  const result = await match.def.handler(handlerArgs);
   debug(
     'command %s completed, isError: %s',
     match.name,