@midscene/shared 1.9.7 → 1.9.8-beta-20260618091332.0

package/dist/es/env/parse-model-config.mjs

@@ -5,7 +5,7 @@ import { assert } from "../utils.mjs";
 import { maskConfig, parseJson } from "./helper.mjs";
 import { initDebugConfig } from "./init-debug.mjs";
 const MODEL_CONFIG_DOC_URL = 'https://midscenejs.com/model-common-config.html';
-const getCurrentVersion = ()=>"1.9.7";
+const getCurrentVersion = ()=>"1.9.8-beta-20260618091332.0";
 const getInvalidModelFamilyMessage = (modelFamily)=>`Invalid MIDSCENE_MODEL_FAMILY value: ${modelFamily}. Current version v${getCurrentVersion()} accepts the following model families: ${MODEL_FAMILY_VALUES.join(', ')}. You can also visit ${MODEL_CONFIG_DOC_URL} for the latest configuration information.`;
 const KEYS_MAP = {
     insight: INSIGHT_MODEL_CONFIG_KEYS,

package/dist/es/img/index.mjs

@@ -1,4 +1,4 @@
 import { imageInfoOfBase64, isValidImageBuffer, isValidJPEGImageBuffer, isValidPNGImageBuffer, validateScreenshotBuffer } from "./info.mjs";
-import { createImgBase64ByFormat, cropByRect, httpImg2Base64, inferBase64ImageFormat, localImg2Base64, normalizeBase64Image, paddingToMatchBlockByBase64, parseBase64, preProcessImageUrl, resizeAndConvertImgBuffer, resizeImgBase64, saveBase64Image, scaleImage, zoomForGPT4o } from "./transform.mjs";
+import { createImgBase64ByFormat, cropByRect, httpImg2Base64, inferBase64ImageFormat, localImg2Base64, normalizeBase64Image, normalizeScreenshotBase64, paddingToMatchBlockByBase64, parseBase64, preProcessImageUrl, resizeAndConvertImgBuffer, resizeImgBase64, saveBase64Image, scaleImage, zoomForGPT4o } from "./transform.mjs";
 import { annotateRects, compositeElementInfoImg, compositePointMarkerImg, processImageElementInfo } from "./box-select.mjs";
-export { annotateRects, compositeElementInfoImg, compositePointMarkerImg, createImgBase64ByFormat, cropByRect, httpImg2Base64, imageInfoOfBase64, inferBase64ImageFormat, isValidImageBuffer, isValidJPEGImageBuffer, isValidPNGImageBuffer, localImg2Base64, normalizeBase64Image, paddingToMatchBlockByBase64, parseBase64, preProcessImageUrl, processImageElementInfo, resizeAndConvertImgBuffer, resizeImgBase64, saveBase64Image, scaleImage, validateScreenshotBuffer, zoomForGPT4o };
+export { annotateRects, compositeElementInfoImg, compositePointMarkerImg, createImgBase64ByFormat, cropByRect, httpImg2Base64, imageInfoOfBase64, inferBase64ImageFormat, isValidImageBuffer, isValidJPEGImageBuffer, isValidPNGImageBuffer, localImg2Base64, normalizeBase64Image, normalizeScreenshotBase64, paddingToMatchBlockByBase64, parseBase64, preProcessImageUrl, processImageElementInfo, resizeAndConvertImgBuffer, resizeImgBase64, saveBase64Image, scaleImage, validateScreenshotBuffer, zoomForGPT4o };

package/dist/es/img/transform.mjs

@@ -71,6 +71,8 @@ async function resizeAndConvertImgBuffer(inputFormat, inputData, newSize) {
 }
 const normalizeBase64Body = (body)=>body.replace(/\s/g, '');
 const base64ImageDataUrlPattern = /^data:image\/[a-zA-Z0-9.+-]+;base64,/i;
+const supportedScreenshotDataUriPattern = /^data:image\/(png|jpe?g);base64,([\s\S]*)$/i;
+const rawBase64BodyPattern = /^[A-Za-z0-9+/=\s]+$/;
 const inferBase64ImageFormat = (base64Body)=>{
     if (base64Body.startsWith('iVBORw0KGgo')) return 'png';
     return 'jpeg';
@@ -83,6 +85,21 @@ function detectImageMimeTypeFromBuffer(buffer) {
     if (buffer.length >= 2 && 0x42 === buffer[0] && 0x4d === buffer[1]) return 'image/bmp';
 }
 const createImgBase64ByFormat = (format, body)=>`data:image/${format};base64,${normalizeBase64Body(body)}`;
+const normalizeScreenshotBase64 = (base64, options)=>{
+    const label = options?.label ?? 'screenshot base64';
+    const trimmedBase64 = base64.trim();
+    if (!trimmedBase64) throw new Error(`${label} cannot be empty`);
+    const dataUriMatch = trimmedBase64.match(supportedScreenshotDataUriPattern);
+    if (dataUriMatch) {
+        const imageFormat = 'jpg' === dataUriMatch[1].toLowerCase() ? 'jpeg' : dataUriMatch[1].toLowerCase();
+        const body = dataUriMatch[2];
+        if (!normalizeBase64Body(body)) throw new Error(`${label} cannot be empty`);
+        return createImgBase64ByFormat(imageFormat, body);
+    }
+    if (trimmedBase64.startsWith('data:')) throw new Error(`${label} must be a PNG/JPEG data URI or raw PNG base64 string`);
+    if (!rawBase64BodyPattern.test(trimmedBase64)) throw new Error(`${label} must be a PNG/JPEG data URI or raw PNG base64 string`);
+    return createImgBase64ByFormat('png', trimmedBase64);
+};
 const normalizeBase64Image = (base64)=>{
     const trimmedBase64 = base64.trim();
     if (base64ImageDataUrlPattern.test(trimmedBase64)) return trimmedBase64;
@@ -293,4 +310,4 @@ async function scaleImage(imageBase64, scale) {
         imageBase64: base64
     };
 }
-export { createImgBase64ByFormat, cropByRect, httpImg2Base64, inferBase64ImageFormat, localImg2Base64, normalizeBase64Body, normalizeBase64Image, paddingToMatchBlock, paddingToMatchBlockByBase64, parseBase64, photonFromBase64, photonToBase64, preProcessImageUrl, resizeAndConvertImgBuffer, resizeImgBase64, saveBase64Image, scaleImage, zoomForGPT4o };
+export { createImgBase64ByFormat, cropByRect, httpImg2Base64, inferBase64ImageFormat, localImg2Base64, normalizeBase64Body, normalizeBase64Image, normalizeScreenshotBase64, paddingToMatchBlock, paddingToMatchBlockByBase64, parseBase64, photonFromBase64, photonToBase64, preProcessImageUrl, resizeAndConvertImgBuffer, resizeImgBase64, saveBase64Image, scaleImage, zoomForGPT4o };

package/dist/es/mcp/agent-behavior-init-args.mjs

@@ -0,0 +1,44 @@
+import { z } from "zod";
+const agentBehaviorInitArgShape = {
+    aiActContext: z.string().optional().describe('Background knowledge passed to aiAct. Default: no extra context.'),
+    replanningCycleLimit: z.number().int().nonnegative().optional().describe('Maximum number of replanning cycles for aiAct. Default: model adapter default.'),
+    waitAfterAction: z.number().nonnegative().optional().describe('Wait time in milliseconds after each action execution. Default: 300ms.'),
+    screenshotShrinkFactor: z.number().min(1).optional().describe('Screenshot shrink factor before sending images to AI. Default: 1; high values may reduce recognition quality, especially on mobile.')
+};
+function extractAgentBehaviorInitArgs(extracted) {
+    if (!extracted) return;
+    const agentOptions = {
+        ...'string' == typeof extracted.aiActContext ? {
+            aiActContext: extracted.aiActContext
+        } : {},
+        ...'string' == typeof extracted.aiActionContext ? {
+            aiActionContext: extracted.aiActionContext
+        } : {},
+        ...'number' == typeof extracted.replanningCycleLimit ? {
+            replanningCycleLimit: extracted.replanningCycleLimit
+        } : {},
+        ...'number' == typeof extracted.waitAfterAction ? {
+            waitAfterAction: extracted.waitAfterAction
+        } : {},
+        ...'number' == typeof extracted.screenshotShrinkFactor ? {
+            screenshotShrinkFactor: extracted.screenshotShrinkFactor
+        } : {}
+    };
+    return Object.keys(agentOptions).length > 0 ? agentOptions : void 0;
+}
+function stableJsonValue(value) {
+    if (Array.isArray(value)) return value.map(stableJsonValue);
+    if (value && 'object' == typeof value) return Object.fromEntries(Object.entries(value).sort(([left], [right])=>left.localeCompare(right)).map(([key, nestedValue])=>[
+            key,
+            stableJsonValue(nestedValue)
+        ]));
+    return value;
+}
+function getAgentInitArgsSignature(initArgs) {
+    if (!initArgs || 0 === Object.keys(initArgs).length) return;
+    return JSON.stringify(stableJsonValue(initArgs));
+}
+function shouldRebuildAgentForInitArgs(currentSignature, nextSignature) {
+    return currentSignature !== nextSignature && (void 0 !== currentSignature || void 0 !== nextSignature);
+}
+export { agentBehaviorInitArgShape, extractAgentBehaviorInitArgs, getAgentInitArgsSignature, shouldRebuildAgentForInitArgs };

package/dist/es/mcp/index.mjs

@@ -1,6 +1,7 @@
 export * from "./base-server.mjs";
 export * from "./base-tools.mjs";
 export * from "./tool-defaults.mjs";
+export * from "./agent-behavior-init-args.mjs";
 export * from "./init-arg-utils.mjs";
 export * from "./error-formatter.mjs";
 export * from "./tool-generator.mjs";

package/dist/es/mcp/tool-generator.mjs

@@ -48,13 +48,14 @@ function getZodObjectShape(value) {
 function isRecord(value) {
     return 'object' == typeof value && null !== value && !Array.isArray(value);
 }
-function makePromptOptional(shape, wrapInOptional) {
+function makePromptOptional(shape, wrapInOptional, description) {
     const newShape = {
         ...shape
     };
     newShape.prompt = shape.prompt.optional();
     let newSchema = z.object(newShape).passthrough();
     if (wrapInOptional) newSchema = newSchema.optional();
+    if (description) newSchema = newSchema.describe(description);
     return newSchema;
 }
 function transformSchemaField(key, value) {
@@ -62,7 +63,7 @@ function transformSchemaField(key, value) {
     const shape = getZodObjectShape(innerValue);
     if (shape && isMidsceneLocatorField(innerValue)) return [
         key,
-        makePromptOptional(shape, isOptional)
+        makePromptOptional(shape, isOptional, getZodDescription(value))
     ];
     return [
         key,

package/dist/lib/env/parse-model-config.js

@@ -37,7 +37,7 @@ const external_utils_js_namespaceObject = require("../utils.js");
 const external_helper_js_namespaceObject = require("./helper.js");
 const external_init_debug_js_namespaceObject = require("./init-debug.js");
 const MODEL_CONFIG_DOC_URL = 'https://midscenejs.com/model-common-config.html';
-const getCurrentVersion = ()=>"1.9.7";
+const getCurrentVersion = ()=>"1.9.8-beta-20260618091332.0";
 const getInvalidModelFamilyMessage = (modelFamily)=>`Invalid MIDSCENE_MODEL_FAMILY value: ${modelFamily}. Current version v${getCurrentVersion()} accepts the following model families: ${external_types_js_namespaceObject.MODEL_FAMILY_VALUES.join(', ')}. You can also visit ${MODEL_CONFIG_DOC_URL} for the latest configuration information.`;
 const KEYS_MAP = {
     insight: external_constants_js_namespaceObject.INSIGHT_MODEL_CONFIG_KEYS,

package/dist/lib/img/index.js

@@ -33,6 +33,7 @@ __webpack_require__.d(__webpack_exports__, {
     saveBase64Image: ()=>external_transform_js_namespaceObject.saveBase64Image,
     isValidImageBuffer: ()=>external_info_js_namespaceObject.isValidImageBuffer,
     validateScreenshotBuffer: ()=>external_info_js_namespaceObject.validateScreenshotBuffer,
+    normalizeScreenshotBase64: ()=>external_transform_js_namespaceObject.normalizeScreenshotBase64,
     preProcessImageUrl: ()=>external_transform_js_namespaceObject.preProcessImageUrl,
     annotateRects: ()=>external_box_select_js_namespaceObject.annotateRects,
     compositeElementInfoImg: ()=>external_box_select_js_namespaceObject.compositeElementInfoImg,
@@ -64,6 +65,7 @@ exports.isValidJPEGImageBuffer = __webpack_exports__.isValidJPEGImageBuffer;
 exports.isValidPNGImageBuffer = __webpack_exports__.isValidPNGImageBuffer;
 exports.localImg2Base64 = __webpack_exports__.localImg2Base64;
 exports.normalizeBase64Image = __webpack_exports__.normalizeBase64Image;
+exports.normalizeScreenshotBase64 = __webpack_exports__.normalizeScreenshotBase64;
 exports.paddingToMatchBlockByBase64 = __webpack_exports__.paddingToMatchBlockByBase64;
 exports.parseBase64 = __webpack_exports__.parseBase64;
 exports.preProcessImageUrl = __webpack_exports__.preProcessImageUrl;
@@ -88,6 +90,7 @@ for(var __rspack_i in __webpack_exports__)if (-1 === [
     "isValidPNGImageBuffer",
     "localImg2Base64",
     "normalizeBase64Image",
+    "normalizeScreenshotBase64",
     "paddingToMatchBlockByBase64",
     "parseBase64",
     "preProcessImageUrl",

package/dist/lib/img/transform.js

@@ -42,6 +42,7 @@ __webpack_require__.d(__webpack_exports__, {
     resizeAndConvertImgBuffer: ()=>resizeAndConvertImgBuffer,
     resizeImgBase64: ()=>resizeImgBase64,
     saveBase64Image: ()=>saveBase64Image,
+    normalizeScreenshotBase64: ()=>normalizeScreenshotBase64,
     preProcessImageUrl: ()=>preProcessImageUrl,
     cropByRect: ()=>cropByRect,
     scaleImage: ()=>scaleImage,
@@ -129,6 +130,8 @@ async function resizeAndConvertImgBuffer(inputFormat, inputData, newSize) {
 }
 const normalizeBase64Body = (body)=>body.replace(/\s/g, '');
 const base64ImageDataUrlPattern = /^data:image\/[a-zA-Z0-9.+-]+;base64,/i;
+const supportedScreenshotDataUriPattern = /^data:image\/(png|jpe?g);base64,([\s\S]*)$/i;
+const rawBase64BodyPattern = /^[A-Za-z0-9+/=\s]+$/;
 const inferBase64ImageFormat = (base64Body)=>{
     if (base64Body.startsWith('iVBORw0KGgo')) return 'png';
     return 'jpeg';
@@ -141,6 +144,21 @@ function detectImageMimeTypeFromBuffer(buffer) {
     if (buffer.length >= 2 && 0x42 === buffer[0] && 0x4d === buffer[1]) return 'image/bmp';
 }
 const createImgBase64ByFormat = (format, body)=>`data:image/${format};base64,${normalizeBase64Body(body)}`;
+const normalizeScreenshotBase64 = (base64, options)=>{
+    const label = options?.label ?? 'screenshot base64';
+    const trimmedBase64 = base64.trim();
+    if (!trimmedBase64) throw new Error(`${label} cannot be empty`);
+    const dataUriMatch = trimmedBase64.match(supportedScreenshotDataUriPattern);
+    if (dataUriMatch) {
+        const imageFormat = 'jpg' === dataUriMatch[1].toLowerCase() ? 'jpeg' : dataUriMatch[1].toLowerCase();
+        const body = dataUriMatch[2];
+        if (!normalizeBase64Body(body)) throw new Error(`${label} cannot be empty`);
+        return createImgBase64ByFormat(imageFormat, body);
+    }
+    if (trimmedBase64.startsWith('data:')) throw new Error(`${label} must be a PNG/JPEG data URI or raw PNG base64 string`);
+    if (!rawBase64BodyPattern.test(trimmedBase64)) throw new Error(`${label} must be a PNG/JPEG data URI or raw PNG base64 string`);
+    return createImgBase64ByFormat('png', trimmedBase64);
+};
 const normalizeBase64Image = (base64)=>{
     const trimmedBase64 = base64.trim();
     if (base64ImageDataUrlPattern.test(trimmedBase64)) return trimmedBase64;
@@ -358,6 +376,7 @@ exports.inferBase64ImageFormat = __webpack_exports__.inferBase64ImageFormat;
 exports.localImg2Base64 = __webpack_exports__.localImg2Base64;
 exports.normalizeBase64Body = __webpack_exports__.normalizeBase64Body;
 exports.normalizeBase64Image = __webpack_exports__.normalizeBase64Image;
+exports.normalizeScreenshotBase64 = __webpack_exports__.normalizeScreenshotBase64;
 exports.paddingToMatchBlock = __webpack_exports__.paddingToMatchBlock;
 exports.paddingToMatchBlockByBase64 = __webpack_exports__.paddingToMatchBlockByBase64;
 exports.parseBase64 = __webpack_exports__.parseBase64;
@@ -377,6 +396,7 @@ for(var __rspack_i in __webpack_exports__)if (-1 === [
     "localImg2Base64",
     "normalizeBase64Body",
     "normalizeBase64Image",
+    "normalizeScreenshotBase64",
     "paddingToMatchBlock",
     "paddingToMatchBlockByBase64",
     "parseBase64",

package/dist/lib/mcp/agent-behavior-init-args.js

@@ -0,0 +1,87 @@
+"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__, {
+    extractAgentBehaviorInitArgs: ()=>extractAgentBehaviorInitArgs,
+    agentBehaviorInitArgShape: ()=>agentBehaviorInitArgShape,
+    getAgentInitArgsSignature: ()=>getAgentInitArgsSignature,
+    shouldRebuildAgentForInitArgs: ()=>shouldRebuildAgentForInitArgs
+});
+const external_zod_namespaceObject = require("zod");
+const agentBehaviorInitArgShape = {
+    aiActContext: external_zod_namespaceObject.z.string().optional().describe('Background knowledge passed to aiAct. Default: no extra context.'),
+    replanningCycleLimit: external_zod_namespaceObject.z.number().int().nonnegative().optional().describe('Maximum number of replanning cycles for aiAct. Default: model adapter default.'),
+    waitAfterAction: external_zod_namespaceObject.z.number().nonnegative().optional().describe('Wait time in milliseconds after each action execution. Default: 300ms.'),
+    screenshotShrinkFactor: external_zod_namespaceObject.z.number().min(1).optional().describe('Screenshot shrink factor before sending images to AI. Default: 1; high values may reduce recognition quality, especially on mobile.')
+};
+function extractAgentBehaviorInitArgs(extracted) {
+    if (!extracted) return;
+    const agentOptions = {
+        ...'string' == typeof extracted.aiActContext ? {
+            aiActContext: extracted.aiActContext
+        } : {},
+        ...'string' == typeof extracted.aiActionContext ? {
+            aiActionContext: extracted.aiActionContext
+        } : {},
+        ...'number' == typeof extracted.replanningCycleLimit ? {
+            replanningCycleLimit: extracted.replanningCycleLimit
+        } : {},
+        ...'number' == typeof extracted.waitAfterAction ? {
+            waitAfterAction: extracted.waitAfterAction
+        } : {},
+        ...'number' == typeof extracted.screenshotShrinkFactor ? {
+            screenshotShrinkFactor: extracted.screenshotShrinkFactor
+        } : {}
+    };
+    return Object.keys(agentOptions).length > 0 ? agentOptions : void 0;
+}
+function stableJsonValue(value) {
+    if (Array.isArray(value)) return value.map(stableJsonValue);
+    if (value && 'object' == typeof value) return Object.fromEntries(Object.entries(value).sort(([left], [right])=>left.localeCompare(right)).map(([key, nestedValue])=>[
+            key,
+            stableJsonValue(nestedValue)
+        ]));
+    return value;
+}
+function getAgentInitArgsSignature(initArgs) {
+    if (!initArgs || 0 === Object.keys(initArgs).length) return;
+    return JSON.stringify(stableJsonValue(initArgs));
+}
+function shouldRebuildAgentForInitArgs(currentSignature, nextSignature) {
+    return currentSignature !== nextSignature && (void 0 !== currentSignature || void 0 !== nextSignature);
+}
+exports.agentBehaviorInitArgShape = __webpack_exports__.agentBehaviorInitArgShape;
+exports.extractAgentBehaviorInitArgs = __webpack_exports__.extractAgentBehaviorInitArgs;
+exports.getAgentInitArgsSignature = __webpack_exports__.getAgentInitArgsSignature;
+exports.shouldRebuildAgentForInitArgs = __webpack_exports__.shouldRebuildAgentForInitArgs;
+for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "agentBehaviorInitArgShape",
+    "extractAgentBehaviorInitArgs",
+    "getAgentInitArgsSignature",
+    "shouldRebuildAgentForInitArgs"
+].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/lib/mcp/index.js

@@ -1,5 +1,8 @@
 "use strict";
 var __webpack_modules__ = {
+    "./agent-behavior-init-args" (module) {
+        module.exports = require("./agent-behavior-init-args.js");
+    },
     "./base-server" (module) {
         module.exports = require("./base-server.js");
     },
@@ -86,33 +89,37 @@ var __webpack_exports__ = {};
     var __rspack_reexport = {};
     for(const __rspack_import_key in _tool_defaults__rspack_import_2)if ("default" !== __rspack_import_key) __rspack_reexport[__rspack_import_key] = ()=>_tool_defaults__rspack_import_2[__rspack_import_key];
     __webpack_require__.d(__webpack_exports__, __rspack_reexport);
-    var _init_arg_utils__rspack_import_3 = __webpack_require__("./init-arg-utils");
+    var _agent_behavior_init_args__rspack_import_3 = __webpack_require__("./agent-behavior-init-args");
+    var __rspack_reexport = {};
+    for(const __rspack_import_key in _agent_behavior_init_args__rspack_import_3)if ("default" !== __rspack_import_key) __rspack_reexport[__rspack_import_key] = ()=>_agent_behavior_init_args__rspack_import_3[__rspack_import_key];
+    __webpack_require__.d(__webpack_exports__, __rspack_reexport);
+    var _init_arg_utils__rspack_import_4 = __webpack_require__("./init-arg-utils");
     var __rspack_reexport = {};
-    for(const __rspack_import_key in _init_arg_utils__rspack_import_3)if ("default" !== __rspack_import_key) __rspack_reexport[__rspack_import_key] = ()=>_init_arg_utils__rspack_import_3[__rspack_import_key];
+    for(const __rspack_import_key in _init_arg_utils__rspack_import_4)if ("default" !== __rspack_import_key) __rspack_reexport[__rspack_import_key] = ()=>_init_arg_utils__rspack_import_4[__rspack_import_key];
     __webpack_require__.d(__webpack_exports__, __rspack_reexport);
-    var _error_formatter__rspack_import_4 = __webpack_require__("./error-formatter");
+    var _error_formatter__rspack_import_5 = __webpack_require__("./error-formatter");
     var __rspack_reexport = {};
-    for(const __rspack_import_key in _error_formatter__rspack_import_4)if ("default" !== __rspack_import_key) __rspack_reexport[__rspack_import_key] = ()=>_error_formatter__rspack_import_4[__rspack_import_key];
+    for(const __rspack_import_key in _error_formatter__rspack_import_5)if ("default" !== __rspack_import_key) __rspack_reexport[__rspack_import_key] = ()=>_error_formatter__rspack_import_5[__rspack_import_key];
     __webpack_require__.d(__webpack_exports__, __rspack_reexport);
-    var _tool_generator__rspack_import_5 = __webpack_require__("./tool-generator");
+    var _tool_generator__rspack_import_6 = __webpack_require__("./tool-generator");
     var __rspack_reexport = {};
-    for(const __rspack_import_key in _tool_generator__rspack_import_5)if ("default" !== __rspack_import_key) __rspack_reexport[__rspack_import_key] = ()=>_tool_generator__rspack_import_5[__rspack_import_key];
+    for(const __rspack_import_key in _tool_generator__rspack_import_6)if ("default" !== __rspack_import_key) __rspack_reexport[__rspack_import_key] = ()=>_tool_generator__rspack_import_6[__rspack_import_key];
     __webpack_require__.d(__webpack_exports__, __rspack_reexport);
-    var _types__rspack_import_6 = __webpack_require__("./types");
+    var _types__rspack_import_7 = __webpack_require__("./types");
     var __rspack_reexport = {};
-    for(const __rspack_import_key in _types__rspack_import_6)if ("default" !== __rspack_import_key) __rspack_reexport[__rspack_import_key] = ()=>_types__rspack_import_6[__rspack_import_key];
+    for(const __rspack_import_key in _types__rspack_import_7)if ("default" !== __rspack_import_key) __rspack_reexport[__rspack_import_key] = ()=>_types__rspack_import_7[__rspack_import_key];
     __webpack_require__.d(__webpack_exports__, __rspack_reexport);
-    var _inject_report_html_plugin__rspack_import_7 = __webpack_require__("./inject-report-html-plugin");
+    var _inject_report_html_plugin__rspack_import_8 = __webpack_require__("./inject-report-html-plugin");
     var __rspack_reexport = {};
-    for(const __rspack_import_key in _inject_report_html_plugin__rspack_import_7)if ("default" !== __rspack_import_key) __rspack_reexport[__rspack_import_key] = ()=>_inject_report_html_plugin__rspack_import_7[__rspack_import_key];
+    for(const __rspack_import_key in _inject_report_html_plugin__rspack_import_8)if ("default" !== __rspack_import_key) __rspack_reexport[__rspack_import_key] = ()=>_inject_report_html_plugin__rspack_import_8[__rspack_import_key];
     __webpack_require__.d(__webpack_exports__, __rspack_reexport);
-    var _launcher_helper__rspack_import_8 = __webpack_require__("./launcher-helper");
+    var _launcher_helper__rspack_import_9 = __webpack_require__("./launcher-helper");
     var __rspack_reexport = {};
-    for(const __rspack_import_key in _launcher_helper__rspack_import_8)if ("default" !== __rspack_import_key) __rspack_reexport[__rspack_import_key] = ()=>_launcher_helper__rspack_import_8[__rspack_import_key];
+    for(const __rspack_import_key in _launcher_helper__rspack_import_9)if ("default" !== __rspack_import_key) __rspack_reexport[__rspack_import_key] = ()=>_launcher_helper__rspack_import_9[__rspack_import_key];
     __webpack_require__.d(__webpack_exports__, __rspack_reexport);
-    var _chrome_path__rspack_import_9 = __webpack_require__("./chrome-path");
+    var _chrome_path__rspack_import_10 = __webpack_require__("./chrome-path");
     var __rspack_reexport = {};
-    for(const __rspack_import_key in _chrome_path__rspack_import_9)if ("default" !== __rspack_import_key) __rspack_reexport[__rspack_import_key] = ()=>_chrome_path__rspack_import_9[__rspack_import_key];
+    for(const __rspack_import_key in _chrome_path__rspack_import_10)if ("default" !== __rspack_import_key) __rspack_reexport[__rspack_import_key] = ()=>_chrome_path__rspack_import_10[__rspack_import_key];
     __webpack_require__.d(__webpack_exports__, __rspack_reexport);
 })();
 for(var __rspack_i in __webpack_exports__)exports[__rspack_i] = __webpack_exports__[__rspack_i];

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

@@ -78,13 +78,14 @@ function getZodObjectShape(value) {
 function isRecord(value) {
     return 'object' == typeof value && null !== value && !Array.isArray(value);
 }
-function makePromptOptional(shape, wrapInOptional) {
+function makePromptOptional(shape, wrapInOptional, description) {
     const newShape = {
         ...shape
     };
     newShape.prompt = shape.prompt.optional();
     let newSchema = external_zod_namespaceObject.z.object(newShape).passthrough();
     if (wrapInOptional) newSchema = newSchema.optional();
+    if (description) newSchema = newSchema.describe(description);
     return newSchema;
 }
 function transformSchemaField(key, value) {
@@ -92,7 +93,7 @@ function transformSchemaField(key, value) {
     const shape = getZodObjectShape(innerValue);
     if (shape && (0, external_zod_schema_utils_js_namespaceObject.isMidsceneLocatorField)(innerValue)) return [
         key,
-        makePromptOptional(shape, isOptional)
+        makePromptOptional(shape, isOptional, (0, external_zod_schema_utils_js_namespaceObject.getZodDescription)(value))
     ];
     return [
         key,

package/dist/types/img/index.d.ts

@@ -1,3 +1,3 @@
 export { imageInfoOfBase64, isValidPNGImageBuffer, isValidJPEGImageBuffer, isValidImageBuffer, validateScreenshotBuffer, type ValidateScreenshotBufferOptions, } from './info';
-export { resizeAndConvertImgBuffer, resizeImgBase64, zoomForGPT4o, saveBase64Image, paddingToMatchBlockByBase64, cropByRect, scaleImage, localImg2Base64, httpImg2Base64, preProcessImageUrl, parseBase64, createImgBase64ByFormat, inferBase64ImageFormat, normalizeBase64Image, } from './transform';
+export { resizeAndConvertImgBuffer, resizeImgBase64, zoomForGPT4o, saveBase64Image, paddingToMatchBlockByBase64, cropByRect, scaleImage, localImg2Base64, httpImg2Base64, preProcessImageUrl, parseBase64, createImgBase64ByFormat, inferBase64ImageFormat, normalizeBase64Image, normalizeScreenshotBase64, type NormalizeScreenshotBase64Options, } from './transform';
 export { processImageElementInfo, compositeElementInfoImg, compositePointMarkerImg, annotateRects, } from './box-select';

package/dist/types/img/transform.d.ts

@@ -29,6 +29,10 @@ export declare function resizeAndConvertImgBuffer(inputFormat: string, inputData
 export declare const normalizeBase64Body: (body: string) => string;
 export declare const inferBase64ImageFormat: (base64Body: string) => "jpeg" | "png";
 export declare const createImgBase64ByFormat: (format: string, body: string) => string;
+export interface NormalizeScreenshotBase64Options {
+    label?: string;
+}
+export declare const normalizeScreenshotBase64: (base64: string, options?: NormalizeScreenshotBase64Options) => string;
 export declare const normalizeBase64Image: (base64: string) => string;
 export declare function resizeImgBase64(inputBase64: string, newSize: {
     width: number;

package/dist/types/mcp/agent-behavior-init-args.d.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+export interface AgentBehaviorInitArgs {
+    aiActContext?: string;
+    aiActionContext?: string;
+    replanningCycleLimit?: number;
+    waitAfterAction?: number;
+    screenshotShrinkFactor?: number;
+}
+export declare const agentBehaviorInitArgShape: {
+    aiActContext: z.ZodOptional<z.ZodString>;
+    replanningCycleLimit: z.ZodOptional<z.ZodNumber>;
+    waitAfterAction: z.ZodOptional<z.ZodNumber>;
+    screenshotShrinkFactor: z.ZodOptional<z.ZodNumber>;
+};
+export declare function extractAgentBehaviorInitArgs(extracted: Partial<AgentBehaviorInitArgs> | undefined): AgentBehaviorInitArgs | undefined;
+export declare function getAgentInitArgsSignature(initArgs: object | undefined): string | undefined;
+export declare function shouldRebuildAgentForInitArgs(currentSignature: string | undefined, nextSignature: string | undefined): boolean;

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

@@ -1,6 +1,7 @@
 export * from './base-server';
 export * from './base-tools';
 export * from './tool-defaults';
+export * from './agent-behavior-init-args';
 export * from './init-arg-utils';
 export * from './error-formatter';
 export * from './tool-generator';

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

@@ -97,6 +97,21 @@ export type UserPromptLike = string | {
     }>;
     convertHttpImage2Base64?: boolean;
 };
+export interface RecordToReportScreenshot {
+    /**
+     * PNG/JPEG data URI, or raw PNG base64 body.
+     */
+    base64: string;
+    description?: string;
+}
+export interface RecordToReportOptions {
+    content?: string;
+    /**
+     * @deprecated Use `screenshots: [{ base64 }]` instead.
+     */
+    screenshotBase64?: string;
+    screenshots?: RecordToReportScreenshot[];
+}
 /**
  * Base agent interface
  * Represents a platform-specific agent (Android, iOS, Web)
@@ -108,10 +123,7 @@ export interface BaseAgent {
     page?: {
         screenshotBase64(): Promise<string>;
     };
-    recordToReport?: (title?: string, opt?: {
-        content?: string;
-        screenshotBase64?: string;
-    }) => Promise<void>;
+    recordToReport?: (title?: string, opt?: RecordToReportOptions) => 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>;

package/package.json

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

package/src/img/index.ts

@@ -21,6 +21,8 @@ export {
   createImgBase64ByFormat,
   inferBase64ImageFormat,
   normalizeBase64Image,
+  normalizeScreenshotBase64,
+  type NormalizeScreenshotBase64Options,
 } from './transform';
 export {
   processImageElementInfo,

package/src/img/transform.ts

@@ -157,6 +157,9 @@ export async function resizeAndConvertImgBuffer(
 export const normalizeBase64Body = (body: string) => body.replace(/\s/g, '');
 
 const base64ImageDataUrlPattern = /^data:image\/[a-zA-Z0-9.+-]+;base64,/i;
+const supportedScreenshotDataUriPattern =
+  /^data:image\/(png|jpe?g);base64,([\s\S]*)$/i;
+const rawBase64BodyPattern = /^[A-Za-z0-9+/=\s]+$/;
 
 export const inferBase64ImageFormat = (base64Body: string) => {
   if (base64Body.startsWith('iVBORw0KGgo')) {
@@ -207,6 +210,48 @@ export const createImgBase64ByFormat = (format: string, body: string) => {
   return `data:image/${format};base64,${normalizeBase64Body(body)}`;
 };
 
+export interface NormalizeScreenshotBase64Options {
+  label?: string;
+}
+
+export const normalizeScreenshotBase64 = (
+  base64: string,
+  options?: NormalizeScreenshotBase64Options,
+) => {
+  const label = options?.label ?? 'screenshot base64';
+  const trimmedBase64 = base64.trim();
+  if (!trimmedBase64) {
+    throw new Error(`${label} cannot be empty`);
+  }
+
+  const dataUriMatch = trimmedBase64.match(supportedScreenshotDataUriPattern);
+  if (dataUriMatch) {
+    const imageFormat =
+      dataUriMatch[1].toLowerCase() === 'jpg'
+        ? 'jpeg'
+        : dataUriMatch[1].toLowerCase();
+    const body = dataUriMatch[2];
+    if (!normalizeBase64Body(body)) {
+      throw new Error(`${label} cannot be empty`);
+    }
+    return createImgBase64ByFormat(imageFormat, body);
+  }
+
+  if (trimmedBase64.startsWith('data:')) {
+    throw new Error(
+      `${label} must be a PNG/JPEG data URI or raw PNG base64 string`,
+    );
+  }
+
+  if (!rawBase64BodyPattern.test(trimmedBase64)) {
+    throw new Error(
+      `${label} must be a PNG/JPEG data URI or raw PNG base64 string`,
+    );
+  }
+
+  return createImgBase64ByFormat('png', trimmedBase64);
+};
+
 export const normalizeBase64Image = (base64: string) => {
   const trimmedBase64 = base64.trim();
   if (base64ImageDataUrlPattern.test(trimmedBase64)) {

package/src/mcp/agent-behavior-init-args.ts

@@ -0,0 +1,109 @@
+import { z } from 'zod';
+
+export interface AgentBehaviorInitArgs {
+  aiActContext?: string;
+  aiActionContext?: string;
+  replanningCycleLimit?: number;
+  waitAfterAction?: number;
+  screenshotShrinkFactor?: number;
+}
+
+type ExposedAgentBehaviorInitArgKey = Exclude<
+  keyof AgentBehaviorInitArgs,
+  'aiActionContext'
+>;
+
+export const agentBehaviorInitArgShape = {
+  aiActContext: z
+    .string()
+    .optional()
+    .describe(
+      'Background knowledge passed to aiAct. Default: no extra context.',
+    ),
+  replanningCycleLimit: z
+    .number()
+    .int()
+    .nonnegative()
+    .optional()
+    .describe(
+      'Maximum number of replanning cycles for aiAct. Default: model adapter default.',
+    ),
+  waitAfterAction: z
+    .number()
+    .nonnegative()
+    .optional()
+    .describe(
+      'Wait time in milliseconds after each action execution. Default: 300ms.',
+    ),
+  screenshotShrinkFactor: z
+    .number()
+    .min(1)
+    .optional()
+    .describe(
+      'Screenshot shrink factor before sending images to AI. Default: 1; high values may reduce recognition quality, especially on mobile.',
+    ),
+} satisfies Record<ExposedAgentBehaviorInitArgKey, z.ZodTypeAny>;
+
+export function extractAgentBehaviorInitArgs(
+  extracted: Partial<AgentBehaviorInitArgs> | undefined,
+): AgentBehaviorInitArgs | undefined {
+  if (!extracted) {
+    return undefined;
+  }
+
+  const agentOptions: AgentBehaviorInitArgs = {
+    ...(typeof extracted.aiActContext === 'string'
+      ? { aiActContext: extracted.aiActContext }
+      : {}),
+    ...(typeof extracted.aiActionContext === 'string'
+      ? { aiActionContext: extracted.aiActionContext }
+      : {}),
+    ...(typeof extracted.replanningCycleLimit === 'number'
+      ? { replanningCycleLimit: extracted.replanningCycleLimit }
+      : {}),
+    ...(typeof extracted.waitAfterAction === 'number'
+      ? { waitAfterAction: extracted.waitAfterAction }
+      : {}),
+    ...(typeof extracted.screenshotShrinkFactor === 'number'
+      ? { screenshotShrinkFactor: extracted.screenshotShrinkFactor }
+      : {}),
+  };
+
+  return Object.keys(agentOptions).length > 0 ? agentOptions : undefined;
+}
+
+function stableJsonValue(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map(stableJsonValue);
+  }
+
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, nestedValue]) => [key, stableJsonValue(nestedValue)]),
+    );
+  }
+
+  return value;
+}
+
+export function getAgentInitArgsSignature(
+  initArgs: object | undefined,
+): string | undefined {
+  if (!initArgs || Object.keys(initArgs).length === 0) {
+    return undefined;
+  }
+
+  return JSON.stringify(stableJsonValue(initArgs));
+}
+
+export function shouldRebuildAgentForInitArgs(
+  currentSignature: string | undefined,
+  nextSignature: string | undefined,
+): boolean {
+  return (
+    currentSignature !== nextSignature &&
+    (currentSignature !== undefined || nextSignature !== undefined)
+  );
+}

package/src/mcp/index.ts

@@ -1,6 +1,7 @@
 export * from './base-server';
 export * from './base-tools';
 export * from './tool-defaults';
+export * from './agent-behavior-init-args';
 export * from './init-arg-utils';
 export * from './error-formatter';
 export * from './tool-generator';

package/src/mcp/tool-generator.ts

@@ -129,6 +129,7 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 function makePromptOptional(
   shape: Record<string, z.ZodTypeAny>,
   wrapInOptional: boolean,
+  description?: string | null,
 ): z.ZodTypeAny {
   const newShape = { ...shape };
   newShape.prompt = shape.prompt.optional();
@@ -137,6 +138,9 @@ function makePromptOptional(
   if (wrapInOptional) {
     newSchema = newSchema.optional();
   }
+  if (description) {
+    newSchema = newSchema.describe(description);
+  }
   return newSchema;
 }
 
@@ -151,7 +155,10 @@ function transformSchemaField(
   const shape = getZodObjectShape(innerValue);
 
   if (shape && isMidsceneLocatorField(innerValue)) {
-    return [key, makePromptOptional(shape, isOptional)];
+    return [
+      key,
+      makePromptOptional(shape, isOptional, getZodDescription(value)),
+    ];
   }
   return [key, value];
 }

package/src/mcp/types.ts

@@ -100,6 +100,23 @@ export type UserPromptLike =
       convertHttpImage2Base64?: boolean;
     };
 
+export interface RecordToReportScreenshot {
+  /**
+   * PNG/JPEG data URI, or raw PNG base64 body.
+   */
+  base64: string;
+  description?: string;
+}
+
+export interface RecordToReportOptions {
+  content?: string;
+  /**
+   * @deprecated Use `screenshots: [{ base64 }]` instead.
+   */
+  screenshotBase64?: string;
+  screenshots?: RecordToReportScreenshot[];
+}
+
 /**
  * Base agent interface
  * Represents a platform-specific agent (Android, iOS, Web)
@@ -113,7 +130,7 @@ export interface BaseAgent {
   };
   recordToReport?: (
     title?: string,
-    opt?: { content?: string; screenshotBase64?: string },
+    opt?: RecordToReportOptions,
   ) => Promise<void>;
   callActionInActionSpace?: (
     actionName: string,