@aiscene/shared 8.0.1 → 8.0.3

package/dist/es/cli/cli-args.mjs

@@ -0,0 +1,95 @@
+import { z } from "zod";
+import { getKeyAliases } from "../key-alias-utils.mjs";
+function parseValue(raw) {
+    if (raw.startsWith('{') || raw.startsWith('[')) try {
+        return JSON.parse(raw);
+    } catch  {}
+    if (/^-?\d+(\.\d+)?$/.test(raw)) return Number(raw);
+    return raw;
+}
+function walkCliArgs(args, setArgValue) {
+    for(let i = 0; i < args.length; i++){
+        const arg = args[i];
+        if (!arg.startsWith('--')) continue;
+        const body = arg.slice(2);
+        const eqIdx = body.indexOf('=');
+        if (eqIdx >= 0) setArgValue(body.slice(0, eqIdx), parseValue(body.slice(eqIdx + 1)));
+        else if (args[i + 1] && !args[i + 1].startsWith('--')) {
+            i++;
+            setArgValue(body, parseValue(args[i]));
+        } else setArgValue(body, true);
+    }
+}
+function parseCliArgs(args) {
+    const result = {};
+    walkCliArgs(args, (key, value)=>{
+        result[key] = value;
+    });
+    return result;
+}
+function formatCliOptionName(name) {
+    return `--${name}`;
+}
+function getCliOptionDisplay(key, cliOption) {
+    const label = formatCliOptionName(cliOption?.preferredName ?? key);
+    const aliases = [
+        ...new Set(cliOption?.aliases ?? [])
+    ].map((alias)=>formatCliOptionName(alias)).filter((alias)=>alias !== label);
+    return {
+        label,
+        aliases
+    };
+}
+function getAcceptedCliOptionNames(key, cliOption) {
+    return [
+        ...new Set(cliOption ? [
+            cliOption.preferredName ?? key,
+            ...cliOption.aliases ?? []
+        ] : [
+            key,
+            ...getKeyAliases(key)
+        ])
+    ];
+}
+function toOptionalCliSchemaField(field) {
+    if ('object' == typeof field && null !== field && 'function' == typeof field.optional) return field.optional();
+    const description = 'object' == typeof field && null !== field && "description" in field && 'string' == typeof field.description ? field.description : void 0;
+    return description ? z.any().describe(description) : z.any();
+}
+function buildCliArgSchema(def) {
+    return Object.fromEntries(Object.entries(def.schema).flatMap(([key, zodType])=>getAcceptedCliOptionNames(key, def.cli?.options?.[key]).map((cliKey)=>[
+                cliKey,
+                toOptionalCliSchemaField(zodType)
+            ])));
+}
+function buildDisallowedCliSpellings(def) {
+    const disallowedSpellings = new Set();
+    for (const [key] of Object.entries(def.schema)){
+        const cliOption = def.cli?.options?.[key];
+        const acceptedNames = new Set(getAcceptedCliOptionNames(key, cliOption));
+        const knownSpellings = new Set([
+            key,
+            ...getKeyAliases(key),
+            ...cliOption?.preferredName ? getKeyAliases(cliOption.preferredName) : [],
+            ...cliOption?.aliases ?? []
+        ]);
+        for (const spelling of knownSpellings)if (!acceptedNames.has(spelling)) disallowedSpellings.add(spelling);
+    }
+    return disallowedSpellings;
+}
+function formatCliValidationError(scriptName, commandName, def, rawArgs) {
+    if (0 === Object.keys(def.schema).length) return;
+    const cliSchema = z.object(buildCliArgSchema(def)).strict();
+    const parsed = cliSchema.safeParse(rawArgs);
+    if (parsed.success) return;
+    const disallowedSpellings = buildDisallowedCliSpellings(def);
+    const unknownKeys = parsed.error.issues.flatMap((issue)=>'unrecognized_keys' === issue.code ? issue.keys : []);
+    if (unknownKeys.length > 0) return unknownKeys.map((key)=>{
+        if (disallowedSpellings.has(key)) return `Unsupported option "--${key}" for ${scriptName} ${commandName}.`;
+        return `Unknown option "--${key}" for ${scriptName} ${commandName}.`;
+    }).join('\n');
+    const [issue] = parsed.error.issues;
+    const optionName = 'string' == typeof issue?.path[0] ? `--${issue.path[0]}` : 'CLI arguments';
+    return `Invalid value for "${optionName}" in ${scriptName} ${commandName}: ${issue?.message ?? parsed.error.message}`;
+}
+export { formatCliValidationError, getCliOptionDisplay, parseCliArgs, parseValue };

package/dist/es/cli/cli-error.mjs

@@ -0,0 +1,24 @@
+function _define_property(obj, key, value) {
+    if (key in obj) Object.defineProperty(obj, key, {
+        value: value,
+        enumerable: true,
+        configurable: true,
+        writable: true
+    });
+    else obj[key] = value;
+    return obj;
+}
+class CLIError extends Error {
+    constructor(message, exitCode = 1){
+        super(message), _define_property(this, "exitCode", void 0), this.exitCode = exitCode;
+    }
+}
+function reportCLIError(error, log = console.error) {
+    if (error instanceof CLIError) {
+        log(error.message);
+        return error.exitCode;
+    }
+    log(error);
+    return 1;
+}
+export { CLIError, reportCLIError };

package/dist/es/cli/cli-runner.mjs

@@ -3,44 +3,9 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import dotenv from "dotenv";
 import { getDebug } from "../logger.mjs";
-function _define_property(obj, key, value) {
-    if (key in obj) Object.defineProperty(obj, key, {
-        value: value,
-        enumerable: true,
-        configurable: true,
-        writable: true
-    });
-    else obj[key] = value;
-    return obj;
-}
+import { formatCliValidationError, getCliOptionDisplay, parseCliArgs, parseValue } from "./cli-args.mjs";
+import { CLIError, reportCLIError } from "./cli-error.mjs";
 const debug = getDebug('cli-runner');
-class CLIError extends Error {
-    constructor(message, exitCode = 1){
-        super(message), _define_property(this, "exitCode", void 0), this.exitCode = exitCode;
-    }
-}
-function parseValue(raw) {
-    if (raw.startsWith('{') || raw.startsWith('[')) try {
-        return JSON.parse(raw);
-    } catch  {}
-    if (/^-?\d+(\.\d+)?$/.test(raw)) return Number(raw);
-    return raw;
-}
-function parseCliArgs(args) {
-    const result = {};
-    for(let i = 0; i < args.length; i++){
-        const arg = args[i];
-        if (!arg.startsWith('--')) continue;
-        const body = arg.slice(2);
-        const eqIdx = body.indexOf('=');
-        if (eqIdx >= 0) result[body.slice(0, eqIdx)] = parseValue(body.slice(eqIdx + 1));
-        else if (args[i + 1] && !args[i + 1].startsWith('--')) {
-            i++;
-            result[body] = parseValue(args[i]);
-        } else result[body] = true;
-    }
-    return result;
-}
 function outputContentItem(item, isError) {
     switch(item.type){
         case 'text':
@@ -72,10 +37,13 @@ function printCommandHelp(scriptName, cmd) {
     console.log(def.description);
     const schemaEntries = Object.entries(def.schema);
     if (schemaEntries.length > 0) {
+        const optionWidth = Math.max(22, ...schemaEntries.map(([key])=>getCliOptionDisplay(key, def.cli?.options?.[key]).label.length));
         console.log('\nOptions:');
         for (const [key, zodType] of schemaEntries){
+            const { label, aliases } = getCliOptionDisplay(key, def.cli?.options?.[key]);
             const desc = zodType.description ?? '';
-            console.log(`  --${key.padEnd(20)} ${desc}`);
+            const aliasText = aliases.length > 0 ? ` (aliases: ${aliases.join(', ')})` : '';
+            console.log(`  ${label.padEnd(optionWidth)} ${desc}${aliasText}`);
         }
     }
 }
@@ -137,16 +105,18 @@ async function runToolsCLI(tools, scriptName, options) {
         throw new CLIError(`Unknown command: ${commandName}`);
     }
     const parsedArgs = parseCliArgs(restArgs);
-    debug('command: %s, args: %s', match.name, JSON.stringify(parsedArgs));
     if (true === parsedArgs.help) {
         debug('showing command help for: %s', match.name);
         printCommandHelp(scriptName, match);
         return;
     }
+    const cliValidationError = formatCliValidationError(scriptName, match.name, match.def, parsedArgs);
+    if (cliValidationError) throw new CLIError(cliValidationError);
+    debug('command: %s, args: %s', match.name, JSON.stringify(parsedArgs));
     const result = await match.def.handler(parsedArgs);
     debug('command %s completed, isError: %s', match.name, result.isError ?? false);
     outputResult(result);
     await tools.destroy();
     if (result.isError) throw new CLIError('Command failed', 1);
 }
-export { CLIError, parseCliArgs, parseValue, removePrefix, runToolsCLI };
+export { CLIError, parseCliArgs, parseValue, removePrefix, reportCLIError, runToolsCLI };

package/dist/es/cli/index.mjs

@@ -1,2 +1,4 @@
-import { CLIError, parseCliArgs, parseValue, removePrefix, runToolsCLI } from "./cli-runner.mjs";
-export { CLIError, parseCliArgs, parseValue, removePrefix, runToolsCLI };
+import { CLIError, reportCLIError } from "./cli-error.mjs";
+import { parseCliArgs, parseValue } from "./cli-args.mjs";
+import { removePrefix, runToolsCLI } from "./cli-runner.mjs";
+export { CLIError, parseCliArgs, parseValue, removePrefix, reportCLIError, runToolsCLI };

package/dist/es/constants/example-code.mjs

@@ -28,8 +28,8 @@ aiQuery<T>(queryObject: Record<string, string>): Promise<T> // Extracts data fro
 // The following is test code for Midscene AI, for reference
 // The following is Playwright syntax, you can use Playwright to assist in test generation
 import { test as base } from '@playwright/test';
-import type { PlayWrightAiFixtureType } from '@midscene/web/playwright';
-import { PlaywrightAiFixture } from '@midscene/web/playwright';
+import type { PlayWrightAiFixtureType } from '@aiscene/web/playwright';
+import { PlaywrightAiFixture } from '@aiscene/web/playwright';
 
 const test = base.extend<PlayWrightAiFixtureType>(PlaywrightAiFixture({
   waitForNetworkIdleTimeout: 2000, // optional, the timeout for waiting for network idle between each action, default is 2000ms

package/dist/es/constants/index.mjs

@@ -15,9 +15,14 @@ var constants_NodeType = /*#__PURE__*/ function(NodeType) {
 }({});
 const PLAYGROUND_SERVER_PORT = 5800;
 const SCRCPY_SERVER_PORT = 5700;
+const SCRCPY_ADB_CONNECT_TIMEOUT_MS = 10000;
+const SCRCPY_PUSH_TIMEOUT_MS = 10000;
+const SCRCPY_START_TIMEOUT_MS = 15000;
+const SCRCPY_VIDEO_STREAM_TIMEOUT_MS = 15000;
+const SCRCPY_PREVIEW_METADATA_TIMEOUT_MS = SCRCPY_ADB_CONNECT_TIMEOUT_MS + SCRCPY_PUSH_TIMEOUT_MS + SCRCPY_START_TIMEOUT_MS + SCRCPY_VIDEO_STREAM_TIMEOUT_MS + 5000;
 const WEBDRIVER_ELEMENT_ID_KEY = 'element-6066-11e4-a52e-4f735466cecf';
 const DEFAULT_WDA_PORT = 8100;
 const DEFAULT_WAIT_FOR_NAVIGATION_TIMEOUT = 5000;
 const DEFAULT_WAIT_FOR_NETWORK_IDLE_TIMEOUT = 2000;
 const DEFAULT_WAIT_FOR_NETWORK_IDLE_CONCURRENCY = 2;
-export { CONTAINER_MINI_HEIGHT, CONTAINER_MINI_WIDTH, DEFAULT_WAIT_FOR_NAVIGATION_TIMEOUT, DEFAULT_WAIT_FOR_NETWORK_IDLE_CONCURRENCY, DEFAULT_WAIT_FOR_NETWORK_IDLE_TIMEOUT, DEFAULT_WDA_PORT, constants_NodeType as NodeType, PLAYGROUND_SERVER_PORT, PLAYWRIGHT_EXAMPLE_CODE, SCRCPY_SERVER_PORT, TEXT_MAX_SIZE, TEXT_SIZE_THRESHOLD, WEBDRIVER_ELEMENT_ID_KEY, YAML_EXAMPLE_CODE };
+export { CONTAINER_MINI_HEIGHT, CONTAINER_MINI_WIDTH, DEFAULT_WAIT_FOR_NAVIGATION_TIMEOUT, DEFAULT_WAIT_FOR_NETWORK_IDLE_CONCURRENCY, DEFAULT_WAIT_FOR_NETWORK_IDLE_TIMEOUT, DEFAULT_WDA_PORT, constants_NodeType as NodeType, PLAYGROUND_SERVER_PORT, PLAYWRIGHT_EXAMPLE_CODE, SCRCPY_ADB_CONNECT_TIMEOUT_MS, SCRCPY_PREVIEW_METADATA_TIMEOUT_MS, SCRCPY_PUSH_TIMEOUT_MS, SCRCPY_SERVER_PORT, SCRCPY_START_TIMEOUT_MS, SCRCPY_VIDEO_STREAM_TIMEOUT_MS, TEXT_MAX_SIZE, TEXT_SIZE_THRESHOLD, WEBDRIVER_ELEMENT_ID_KEY, YAML_EXAMPLE_CODE };

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

@@ -24,14 +24,17 @@ class ModelConfigManager {
         this.modelConfigMap = {
             default: {
                 ...defaultConfig,
+                intent: 'default',
                 createOpenAIClient: this.createOpenAIClientFn
             },
             insight: {
                 ...insightConfig || defaultConfig,
+                intent: 'insight',
                 createOpenAIClient: this.createOpenAIClientFn
             },
             planning: {
                 ...planningConfig || defaultConfig,
+                intent: 'planning',
                 createOpenAIClient: this.createOpenAIClientFn
             }
         };

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

@@ -4,6 +4,9 @@ import { getDebug } from "../logger.mjs";
 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 = ()=>"8.0.3";
+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,
     planning: PLANNING_MODEL_CONFIG_KEYS,
@@ -14,7 +17,7 @@ const getUITarsModelVersion = (modelFamily)=>{
     if ('vlm-ui-tars-doubao' === modelFamily || 'vlm-ui-tars-doubao-1.5' === modelFamily) return UITarsModelVersion.DOUBAO_1_5_20B;
 };
 const validateModelFamily = (modelFamily)=>{
-    if (modelFamily && !MODEL_FAMILY_VALUES.includes(modelFamily)) throw new Error(`Invalid MIDSCENE_MODEL_FAMILY value: ${modelFamily}`);
+    if (modelFamily && !MODEL_FAMILY_VALUES.includes(modelFamily)) throw new Error(getInvalidModelFamilyMessage(modelFamily));
 };
 const legacyConfigToModelFamily = (provider)=>{
     const isDoubao = provider[MIDSCENE_USE_DOUBAO_VISION];
@@ -90,6 +93,7 @@ const parseOpenaiSdkConfig = ({ keys, provider, useLegacyLogic = false })=>{
         modelName: modelName,
         modelDescription,
         intent: '-',
+        slot: '-',
         timeout: provider[keys.timeout] ? Number(provider[keys.timeout]) : void 0,
         temperature,
         retryCount: (()=>{
@@ -132,6 +136,7 @@ const decideModelConfigFromIntentConfig = (intent, configMap)=>{
         useLegacyLogic: 'default' === intent
     });
     finalResult.intent = intent;
+    finalResult.slot = intent;
     debugLog('decideModelConfig result by agent.modelConfig() with intent', intent, maskConfig({
         ...finalResult
     }));

package/dist/es/env/types.mjs

@@ -35,6 +35,7 @@ const MIDSCENE_ADB_REMOTE_PORT = 'MIDSCENE_ADB_REMOTE_PORT';
 const MIDSCENE_ANDROID_IME_STRATEGY = 'MIDSCENE_ANDROID_IME_STRATEGY';
 const MIDSCENE_IOS_DEVICE_UDID = 'MIDSCENE_IOS_DEVICE_UDID';
 const MIDSCENE_IOS_SIMULATOR_UDID = 'MIDSCENE_IOS_SIMULATOR_UDID';
+const MIDSCENE_IOS_DEVICE_CLASS_OVERRIDE = 'MIDSCENE_IOS_DEVICE_CLASS_OVERRIDE';
 const MIDSCENE_CACHE = 'MIDSCENE_CACHE';
 const MIDSCENE_USE_VLM_UI_TARS = 'MIDSCENE_USE_VLM_UI_TARS';
 const MIDSCENE_USE_QWEN_VL = 'MIDSCENE_USE_QWEN_VL';
@@ -209,4 +210,4 @@ var types_UITarsModelVersion = /*#__PURE__*/ function(UITarsModelVersion) {
     UITarsModelVersion["DOUBAO_1_5_20B"] = "doubao-1.5-20B";
     return UITarsModelVersion;
 }({});
-export { ALL_ENV_KEYS, BASIC_ENV_KEYS, BOOLEAN_ENV_KEYS, DOCKER_CONTAINER, GLOBAL_ENV_KEYS, MATCH_BY_POSITION, MIDSCENE_ADB_PATH, MIDSCENE_ADB_REMOTE_HOST, MIDSCENE_ADB_REMOTE_PORT, MIDSCENE_ANDROID_IME_STRATEGY, MIDSCENE_CACHE, MIDSCENE_CACHE_MAX_FILENAME_LENGTH, MIDSCENE_DANGEROUSLY_PRINT_ALL_CONFIG, MIDSCENE_DEBUG_MODE, MIDSCENE_DEBUG_MODEL_PROFILE, MIDSCENE_DEBUG_MODEL_RESPONSE, MIDSCENE_INSIGHT_MODEL_API_KEY, MIDSCENE_INSIGHT_MODEL_BASE_URL, MIDSCENE_INSIGHT_MODEL_EXTRA_BODY_JSON, MIDSCENE_INSIGHT_MODEL_FAMILY, MIDSCENE_INSIGHT_MODEL_HTTP_PROXY, MIDSCENE_INSIGHT_MODEL_INIT_CONFIG_JSON, MIDSCENE_INSIGHT_MODEL_NAME, MIDSCENE_INSIGHT_MODEL_REASONING_BUDGET, MIDSCENE_INSIGHT_MODEL_REASONING_EFFORT, MIDSCENE_INSIGHT_MODEL_REASONING_ENABLED, MIDSCENE_INSIGHT_MODEL_RETRY_COUNT, MIDSCENE_INSIGHT_MODEL_RETRY_INTERVAL, MIDSCENE_INSIGHT_MODEL_SOCKS_PROXY, MIDSCENE_INSIGHT_MODEL_TEMPERATURE, MIDSCENE_INSIGHT_MODEL_TIMEOUT, MIDSCENE_IOS_DEVICE_UDID, MIDSCENE_IOS_SIMULATOR_UDID, MIDSCENE_LANGFUSE_DEBUG, MIDSCENE_LANGSMITH_DEBUG, MIDSCENE_MCP_ANDROID_MODE, MIDSCENE_MCP_CHROME_PATH, MIDSCENE_MCP_USE_PUPPETEER_MODE, MIDSCENE_MODEL_API_KEY, MIDSCENE_MODEL_BASE_URL, MIDSCENE_MODEL_EXTRA_BODY_JSON, MIDSCENE_MODEL_FAMILY, MIDSCENE_MODEL_HTTP_PROXY, MIDSCENE_MODEL_INIT_CONFIG_JSON, MIDSCENE_MODEL_MAX_TOKENS, MIDSCENE_MODEL_NAME, MIDSCENE_MODEL_REASONING_BUDGET, MIDSCENE_MODEL_REASONING_EFFORT, MIDSCENE_MODEL_REASONING_ENABLED, MIDSCENE_MODEL_RETRY_COUNT, MIDSCENE_MODEL_RETRY_INTERVAL, MIDSCENE_MODEL_SOCKS_PROXY, MIDSCENE_MODEL_TEMPERATURE, MIDSCENE_MODEL_TIMEOUT, MIDSCENE_OPENAI_HTTP_PROXY, MIDSCENE_OPENAI_INIT_CONFIG_JSON, MIDSCENE_OPENAI_SOCKS_PROXY, MIDSCENE_PLANNING_MODEL_API_KEY, MIDSCENE_PLANNING_MODEL_BASE_URL, MIDSCENE_PLANNING_MODEL_EXTRA_BODY_JSON, MIDSCENE_PLANNING_MODEL_FAMILY, MIDSCENE_PLANNING_MODEL_HTTP_PROXY, MIDSCENE_PLANNING_MODEL_INIT_CONFIG_JSON, MIDSCENE_PLANNING_MODEL_NAME, MIDSCENE_PLANNING_MODEL_REASONING_BUDGET, MIDSCENE_PLANNING_MODEL_REASONING_EFFORT, MIDSCENE_PLANNING_MODEL_REASONING_ENABLED, MIDSCENE_PLANNING_MODEL_RETRY_COUNT, MIDSCENE_PLANNING_MODEL_RETRY_INTERVAL, MIDSCENE_PLANNING_MODEL_SOCKS_PROXY, MIDSCENE_PLANNING_MODEL_TEMPERATURE, MIDSCENE_PLANNING_MODEL_TIMEOUT, MIDSCENE_PREFERRED_LANGUAGE, MIDSCENE_REPLANNING_CYCLE_LIMIT, MIDSCENE_REPORT_QUIET, MIDSCENE_REPORT_TAG_NAME, MIDSCENE_RUN_DIR, MIDSCENE_USE_DOUBAO_VISION, MIDSCENE_USE_GEMINI, MIDSCENE_USE_QWEN3_VL, MIDSCENE_USE_QWEN_VL, MIDSCENE_USE_VLM_UI_TARS, MIDSCENE_USE_VL_MODEL, MODEL_ENV_KEYS, MODEL_FAMILY_VALUES, NUMBER_ENV_KEYS, OPENAI_API_KEY, OPENAI_BASE_URL, OPENAI_MAX_TOKENS, STRING_ENV_KEYS, types_UITarsModelVersion as UITarsModelVersion, UNUSED_ENV_KEYS };
+export { ALL_ENV_KEYS, BASIC_ENV_KEYS, BOOLEAN_ENV_KEYS, DOCKER_CONTAINER, GLOBAL_ENV_KEYS, MATCH_BY_POSITION, MIDSCENE_ADB_PATH, MIDSCENE_ADB_REMOTE_HOST, MIDSCENE_ADB_REMOTE_PORT, MIDSCENE_ANDROID_IME_STRATEGY, MIDSCENE_CACHE, MIDSCENE_CACHE_MAX_FILENAME_LENGTH, MIDSCENE_DANGEROUSLY_PRINT_ALL_CONFIG, MIDSCENE_DEBUG_MODE, MIDSCENE_DEBUG_MODEL_PROFILE, MIDSCENE_DEBUG_MODEL_RESPONSE, MIDSCENE_INSIGHT_MODEL_API_KEY, MIDSCENE_INSIGHT_MODEL_BASE_URL, MIDSCENE_INSIGHT_MODEL_EXTRA_BODY_JSON, MIDSCENE_INSIGHT_MODEL_FAMILY, MIDSCENE_INSIGHT_MODEL_HTTP_PROXY, MIDSCENE_INSIGHT_MODEL_INIT_CONFIG_JSON, MIDSCENE_INSIGHT_MODEL_NAME, MIDSCENE_INSIGHT_MODEL_REASONING_BUDGET, MIDSCENE_INSIGHT_MODEL_REASONING_EFFORT, MIDSCENE_INSIGHT_MODEL_REASONING_ENABLED, MIDSCENE_INSIGHT_MODEL_RETRY_COUNT, MIDSCENE_INSIGHT_MODEL_RETRY_INTERVAL, MIDSCENE_INSIGHT_MODEL_SOCKS_PROXY, MIDSCENE_INSIGHT_MODEL_TEMPERATURE, MIDSCENE_INSIGHT_MODEL_TIMEOUT, MIDSCENE_IOS_DEVICE_CLASS_OVERRIDE, MIDSCENE_IOS_DEVICE_UDID, MIDSCENE_IOS_SIMULATOR_UDID, MIDSCENE_LANGFUSE_DEBUG, MIDSCENE_LANGSMITH_DEBUG, MIDSCENE_MCP_ANDROID_MODE, MIDSCENE_MCP_CHROME_PATH, MIDSCENE_MCP_USE_PUPPETEER_MODE, MIDSCENE_MODEL_API_KEY, MIDSCENE_MODEL_BASE_URL, MIDSCENE_MODEL_EXTRA_BODY_JSON, MIDSCENE_MODEL_FAMILY, MIDSCENE_MODEL_HTTP_PROXY, MIDSCENE_MODEL_INIT_CONFIG_JSON, MIDSCENE_MODEL_MAX_TOKENS, MIDSCENE_MODEL_NAME, MIDSCENE_MODEL_REASONING_BUDGET, MIDSCENE_MODEL_REASONING_EFFORT, MIDSCENE_MODEL_REASONING_ENABLED, MIDSCENE_MODEL_RETRY_COUNT, MIDSCENE_MODEL_RETRY_INTERVAL, MIDSCENE_MODEL_SOCKS_PROXY, MIDSCENE_MODEL_TEMPERATURE, MIDSCENE_MODEL_TIMEOUT, MIDSCENE_OPENAI_HTTP_PROXY, MIDSCENE_OPENAI_INIT_CONFIG_JSON, MIDSCENE_OPENAI_SOCKS_PROXY, MIDSCENE_PLANNING_MODEL_API_KEY, MIDSCENE_PLANNING_MODEL_BASE_URL, MIDSCENE_PLANNING_MODEL_EXTRA_BODY_JSON, MIDSCENE_PLANNING_MODEL_FAMILY, MIDSCENE_PLANNING_MODEL_HTTP_PROXY, MIDSCENE_PLANNING_MODEL_INIT_CONFIG_JSON, MIDSCENE_PLANNING_MODEL_NAME, MIDSCENE_PLANNING_MODEL_REASONING_BUDGET, MIDSCENE_PLANNING_MODEL_REASONING_EFFORT, MIDSCENE_PLANNING_MODEL_REASONING_ENABLED, MIDSCENE_PLANNING_MODEL_RETRY_COUNT, MIDSCENE_PLANNING_MODEL_RETRY_INTERVAL, MIDSCENE_PLANNING_MODEL_SOCKS_PROXY, MIDSCENE_PLANNING_MODEL_TEMPERATURE, MIDSCENE_PLANNING_MODEL_TIMEOUT, MIDSCENE_PREFERRED_LANGUAGE, MIDSCENE_REPLANNING_CYCLE_LIMIT, MIDSCENE_REPORT_QUIET, MIDSCENE_REPORT_TAG_NAME, MIDSCENE_RUN_DIR, MIDSCENE_USE_DOUBAO_VISION, MIDSCENE_USE_GEMINI, MIDSCENE_USE_QWEN3_VL, MIDSCENE_USE_QWEN_VL, MIDSCENE_USE_VLM_UI_TARS, MIDSCENE_USE_VL_MODEL, MODEL_ENV_KEYS, MODEL_FAMILY_VALUES, NUMBER_ENV_KEYS, OPENAI_API_KEY, OPENAI_BASE_URL, OPENAI_MAX_TOKENS, STRING_ENV_KEYS, types_UITarsModelVersion as UITarsModelVersion, UNUSED_ENV_KEYS };

package/dist/es/env/utils.mjs

@@ -5,14 +5,6 @@ const globalModelConfigManager = new ModelConfigManager();
 const globalConfigManager = new GlobalConfigManager();
 globalConfigManager.registerModelConfigManager(globalModelConfigManager);
 globalModelConfigManager.registerGlobalConfigManager(globalConfigManager);
-async function getCurrentTime(device, useDeviceTimestamp) {
-    if (useDeviceTimestamp && device?.getTimestamp) try {
-        return await device.getTimestamp();
-    } catch (error) {
-        console.warn(`Failed to get device time, falling back to system time: ${error}`);
-    }
-    return Date.now();
-}
 const getPreferredLanguage = ()=>{
     const prefer = globalConfigManager.getEnvConfigValue(MIDSCENE_PREFERRED_LANGUAGE);
     if (prefer) return prefer;
@@ -23,4 +15,4 @@ const getPreferredLanguage = ()=>{
 const overrideAIConfig = (newConfig, extendMode = false)=>{
     globalConfigManager.overrideAIConfig(newConfig, extendMode);
 };
-export { getCurrentTime, getPreferredLanguage, globalConfigManager, globalModelConfigManager, overrideAIConfig };
+export { getPreferredLanguage, globalConfigManager, globalModelConfigManager, overrideAIConfig };

package/dist/es/extractor/index.mjs

@@ -1,5 +1,5 @@
 import { descriptionOfTree, traverseTree, treeToList, trimAttributes, truncateText } from "./tree.mjs";
 import { extractTextWithPosition, extractTreeNode, extractTreeNodeAsString } from "./web-extractor.mjs";
 import { getElementInfoByXpath, getElementXpath, getNodeInfoByXpath, getXpathsById, getXpathsByPoint } from "./locator.mjs";
-import { generateElementByRect, isNotContainerElement } from "./dom-util.mjs";
-export { descriptionOfTree, generateElementByRect, getElementInfoByXpath, getElementXpath, getNodeInfoByXpath, getXpathsById, getXpathsByPoint, isNotContainerElement, traverseTree, treeToList, trimAttributes, truncateText, extractTreeNode as webExtractNodeTree, extractTreeNodeAsString as webExtractNodeTreeAsString, extractTextWithPosition as webExtractTextWithPosition };
+import { generateElementByPoint, generateElementByRect, isNotContainerElement } from "./dom-util.mjs";
+export { descriptionOfTree, generateElementByPoint, generateElementByRect, getElementInfoByXpath, getElementXpath, getNodeInfoByXpath, getXpathsById, getXpathsByPoint, isNotContainerElement, traverseTree, treeToList, trimAttributes, truncateText, extractTreeNode as webExtractNodeTree, extractTreeNodeAsString as webExtractNodeTreeAsString, extractTextWithPosition as webExtractTextWithPosition };

package/dist/es/img/index.mjs

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

package/dist/es/img/info.mjs

@@ -26,4 +26,10 @@ function isValidJPEGImageBuffer(buffer) {
 function isValidImageBuffer(buffer) {
     return isValidPNGImageBuffer(buffer) || isValidJPEGImageBuffer(buffer);
 }
-export { imageInfoOfBase64, isValidImageBuffer, isValidJPEGImageBuffer, isValidPNGImageBuffer };
+function validateScreenshotBuffer(screenshotBuffer, { label, minBufferSize = 0 }) {
+    const bufferSize = screenshotBuffer?.length ?? 0;
+    if (!screenshotBuffer || 0 === bufferSize) throw new Error(`${label} validation failed: buffer size ${bufferSize} bytes`);
+    if (!isValidImageBuffer(screenshotBuffer)) throw new Error(`${label} buffer has invalid image format`);
+    if (minBufferSize > 0 && bufferSize < minBufferSize) throw new Error(`${label} validation failed: buffer size ${bufferSize} bytes (minimum: ${minBufferSize})`);
+}
+export { imageInfoOfBase64, isValidImageBuffer, isValidJPEGImageBuffer, isValidPNGImageBuffer, validateScreenshotBuffer };

package/dist/es/key-alias-utils.mjs

@@ -0,0 +1,19 @@
+function kebabToCamel(str) {
+    return str.replace(/-([a-z])/g, (_, letter)=>letter.toUpperCase());
+}
+function camelToKebab(str) {
+    return str.replace(/[A-Z]/g, (letter)=>`-${letter.toLowerCase()}`).replace(/^-/, '');
+}
+function getKeyAliases(key) {
+    return [
+        ...new Set([
+            key,
+            kebabToCamel(key),
+            camelToKebab(key)
+        ])
+    ];
+}
+function isRecord(value) {
+    return 'object' == typeof value && null !== value && !Array.isArray(value);
+}
+export { camelToKebab, getKeyAliases, isRecord, kebabToCamel };

package/dist/es/mcp/base-server.mjs

@@ -1,9 +1,10 @@
 import { randomUUID } from "node:crypto";
-import { setIsMcp } from "../utils.mjs";
+import { setIsMcp } from "@aiscene/shared/utils";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import express from "express";
+import { getErrorMessage } from "./error-formatter.mjs";
 function _define_property(obj, key, value) {
     if (key in obj) Object.defineProperty(obj, key, {
         value: value,
@@ -45,7 +46,7 @@ class BaseMCPServer {
         try {
             await this.toolsManager.initTools();
         } catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
+            const message = getErrorMessage(error);
             console.error(`Failed to initialize tools: ${message}`);
             console.error('Tools will be initialized on first use');
         }
@@ -71,7 +72,7 @@ class BaseMCPServer {
         try {
             await this.mcpServer.connect(transport);
         } catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
+            const message = getErrorMessage(error);
             console.error(`Failed to connect MCP stdio transport: ${message}`);
             throw new Error(`Failed to initialize MCP stdio transport: ${message}`);
         }
@@ -142,7 +143,7 @@ class BaseMCPServer {
                     });
                 }
             } catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
+                const message = getErrorMessage(error);
                 const duration = Date.now() - startTime;
                 console.error(`[${new Date().toISOString()}] [${requestId}] MCP request error after ${duration}ms: ${message}`);
                 if (!res.headersSent) res.status(500).json({
@@ -170,7 +171,7 @@ class BaseMCPServer {
                 for (const session of sessions.values())try {
                     await session.transport.close();
                 } catch (error) {
-                    const message = error instanceof Error ? error.message : String(error);
+                    const message = getErrorMessage(error);
                     console.error(`Failed to close session ${session.transport.sessionId}: ${message}`);
                 }
                 sessions.clear();
@@ -205,7 +206,7 @@ class BaseMCPServer {
         try {
             await this.mcpServer.connect(transport);
         } catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
+            const message = getErrorMessage(error);
             console.error(`[${new Date().toISOString()}] Failed to connect MCP transport: ${message}`);
             if (transport.sessionId) sessions.delete(transport.sessionId);
             throw new Error(`Failed to initialize MCP session: ${message}`);
@@ -224,7 +225,7 @@ class BaseMCPServer {
                 sessions.delete(sid);
                 console.log(`[${new Date().toISOString()}] Session ${sid} cleaned up due to inactivity (remaining: ${sessions.size})`);
             } catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
+                const message = getErrorMessage(error);
                 console.error(`[${new Date().toISOString()}] Failed to close session ${sid} during cleanup: ${message}`);
                 sessions.delete(sid);
             }
@@ -237,7 +238,7 @@ class BaseMCPServer {
             for (const session of sessions.values())try {
                 session.transport.close();
             } catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
+                const message = getErrorMessage(error);
                 console.error(`Error closing session during shutdown: ${message}`);
             }
             sessions.clear();
@@ -250,7 +251,7 @@ class BaseMCPServer {
                     this.performCleanup().finally(()=>process.exit(1));
                 }, 5000);
             } catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
+                const message = getErrorMessage(error);
                 console.error(`Error closing HTTP server: ${message}`);
                 this.performCleanup().finally(()=>process.exit(1));
             }

package/dist/es/mcp/base-tools.mjs

@@ -1,5 +1,8 @@
-import { parseBase64 } from "../img/index.mjs";
-import { getDebug } from "../logger.mjs";
+import { parseBase64 } from "@aiscene/shared/img";
+import { getDebug } from "@aiscene/shared/logger";
+import { camelToKebab, getKeyAliases } from "../key-alias-utils.mjs";
+import { generateCliReportSession, readCliReportSession, writeCliReportSession } from "./cli-report-session.mjs";
+import { createNamespacedInitArgSchema, extractNamespacedArgs, sanitizeNamespacedArgs } from "./init-arg-utils.mjs";
 import { generateCommonTools, generateToolsFromActionSpace } from "./tool-generator.mjs";
 function _define_property(obj, key, value) {
     if (key in obj) Object.defineProperty(obj, key, {
@@ -13,9 +16,74 @@ function _define_property(obj, key, value) {
 }
 const debug = getDebug('mcp:base-tools');
 class BaseMidsceneTools {
+    getInitArgKeys() {
+        return this.initArgSpec ? Object.keys(this.initArgSpec.shape) : [];
+    }
+    extractAgentInitParam(args) {
+        if (!this.initArgSpec) return;
+        const extracted = extractNamespacedArgs(args, this.initArgSpec.namespace, this.getInitArgKeys());
+        if (this.initArgSpec.adapt) return this.initArgSpec.adapt(extracted);
+        return extracted;
+    }
+    sanitizeToolArgs(args) {
+        if (!this.initArgSpec) return args;
+        return sanitizeNamespacedArgs(args, this.initArgSpec.namespace, this.getInitArgKeys());
+    }
+    getAgentInitArgSchema() {
+        if (!this.initArgSpec) return {};
+        return createNamespacedInitArgSchema(this.initArgSpec.namespace, this.initArgSpec.shape);
+    }
+    getAgentInitArgCliMetadata() {
+        if (!this.initArgSpec?.cli) return;
+        const options = Object.fromEntries(this.getInitArgKeys().map((key)=>{
+            const canonicalKey = `${this.initArgSpec.namespace}.${key}`;
+            const preferredName = this.initArgSpec.cli?.preferredNames?.[key] ?? (this.initArgSpec.cli?.preferBareKeys ? camelToKebab(key) : canonicalKey);
+            const acceptedNames = new Set([
+                preferredName,
+                ...this.initArgSpec.cli?.preferBareKeys ? getKeyAliases(key) : getKeyAliases(canonicalKey)
+            ]);
+            acceptedNames.delete(preferredName);
+            return [
+                canonicalKey,
+                {
+                    preferredName,
+                    aliases: [
+                        ...acceptedNames
+                    ]
+                }
+            ];
+        }));
+        return {
+            options
+        };
+    }
     preparePlatformTools() {
         return [];
     }
+    getCliReportSessionName() {}
+    createNewCliReportSession(targetIdentity) {
+        const sessionName = this.getCliReportSessionName();
+        if (!sessionName) return;
+        return generateCliReportSession(sessionName, targetIdentity);
+    }
+    commitCliReportSession(session) {
+        if (session) writeCliReportSession(session);
+    }
+    readCliReportFileName() {
+        const sessionName = this.getCliReportSessionName();
+        if (!sessionName) return;
+        return readCliReportSession(sessionName)?.reportFileName;
+    }
+    readCliReportAgentOptions() {
+        const reportFileName = this.readCliReportFileName();
+        if (!reportFileName) return;
+        return {
+            reportFileName,
+            reportAttributes: {
+                'data-group-id': reportFileName
+            }
+        };
+    }
     async initTools() {
         this.toolDefinitions = [];
         const platformTools = this.preparePlatformTools();
@@ -30,8 +98,8 @@ class BaseMidsceneTools {
             await tempDevice.destroy?.();
             debug('Action space from temporary device:', actionSpace.map((a)=>a.name).join(', '));
         }
-        const actionTools = generateToolsFromActionSpace(actionSpace, ()=>this.ensureAgent());
-        const commonTools = generateCommonTools(()=>this.ensureAgent());
+        const actionTools = generateToolsFromActionSpace(actionSpace, (args = {})=>this.ensureAgent(this.extractAgentInitParam(args)), (args = {})=>this.sanitizeToolArgs(args), this.getAgentInitArgSchema(), this.getAgentInitArgCliMetadata());
+        const commonTools = generateCommonTools((args = {})=>this.ensureAgent(this.extractAgentInitParam(args)), this.getAgentInitArgSchema(), this.getAgentInitArgCliMetadata());
         this.toolDefinitions.push(...actionTools, ...commonTools);
         debug('Total tools prepared:', this.toolDefinitions.length);
     }

package/dist/es/mcp/cli-report-session.mjs

@@ -0,0 +1,78 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { getMidsceneRunBaseDir, getMidsceneRunSubDir } from "../common.mjs";
+const sessionDirName = 'cli-report-session';
+function sanitizeSessionName(sessionName) {
+    return sessionName.replace(/[^a-zA-Z0-9._-]/g, '_') || 'default';
+}
+function sanitizeFileSegment(segment) {
+    const sanitized = segment.replace(/[^a-zA-Z0-9._-]/g, '_') || 'unknown';
+    return sanitized.slice(0, 80);
+}
+function ensureHtmlFileName(reportFileName) {
+    return reportFileName.endsWith('.html') ? reportFileName : `${reportFileName}.html`;
+}
+function formatDateForFileName(date) {
+    const pad = (value)=>String(value).padStart(2, '0');
+    const day = [
+        date.getFullYear(),
+        pad(date.getMonth() + 1),
+        pad(date.getDate())
+    ].join('-');
+    const time = [
+        pad(date.getHours()),
+        pad(date.getMinutes()),
+        pad(date.getSeconds())
+    ].join('-');
+    return `${day}_${time}`;
+}
+function randomId() {
+    return Math.random().toString(36).slice(2, 10);
+}
+function getCliReportSessionDir() {
+    const dir = join(getMidsceneRunBaseDir(), sessionDirName);
+    if (!existsSync(dir)) mkdirSync(dir, {
+        recursive: true
+    });
+    return dir;
+}
+function getCliReportSessionPath(sessionName) {
+    return join(getCliReportSessionDir(), `${sanitizeSessionName(sessionName)}.json`);
+}
+function generateCliReportSession(sessionName, targetIdentity) {
+    const identitySegment = targetIdentity ? `-${sanitizeFileSegment(targetIdentity)}` : '';
+    const reportFileName = `${sanitizeSessionName(sessionName)}${identitySegment}-${formatDateForFileName(new Date())}-${randomId()}`;
+    const reportPath = join(getMidsceneRunSubDir('report'), ensureHtmlFileName(reportFileName));
+    const session = {
+        version: 1,
+        sessionName,
+        ...targetIdentity ? {
+            targetIdentity
+        } : {},
+        reportFileName,
+        reportPath,
+        createdAt: Date.now()
+    };
+    return session;
+}
+function writeCliReportSession(session) {
+    writeFileSync(getCliReportSessionPath(session.sessionName), JSON.stringify(session, null, 2), 'utf-8');
+}
+function createCliReportSession(sessionName, targetIdentity) {
+    const session = generateCliReportSession(sessionName, targetIdentity);
+    writeCliReportSession(session);
+    return session;
+}
+function readCliReportSession(sessionName) {
+    const sessionPath = getCliReportSessionPath(sessionName);
+    if (!existsSync(sessionPath)) return;
+    try {
+        const raw = readFileSync(sessionPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (1 !== parsed.version || parsed.sessionName !== sessionName || 'string' != typeof parsed.reportFileName || !parsed.reportFileName.trim() || /[\\/]/.test(parsed.reportFileName)) return;
+        return parsed;
+    } catch  {
+        return;
+    }
+}
+export { createCliReportSession, generateCliReportSession, readCliReportSession, writeCliReportSession };