@aiscene/shared 8.0.2 → 8.0.4

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

@@ -1,27 +1,62 @@
 import node_assert from "node:assert";
 import get_photon from "./get-photon.mjs";
-async function imageInfoOfBase64(imageBase64) {
-    if (!imageBase64 || 'string' != typeof imageBase64) throw new Error('Invalid image base64: data is empty or not a string');
-    const base64Data = imageBase64.replace(/^data:image\/\w+;base64,/, '');
-    if (!base64Data || 0 === base64Data.length) throw new Error('Invalid image base64: no data after stripping prefix');
-    if (!/^[A-Za-z0-9+/]*={0,2}$/.test(base64Data)) throw new Error('Invalid image base64: contains invalid characters');
-    if (base64Data.length < 4) throw new Error(`Invalid image base64: data too short (${base64Data.length} characters)`);
-    try {
-        const { PhotonImage } = await get_photon();
-        const result = PhotonImage.new_from_base64(base64Data);
-        const image = result instanceof Promise ? await result : result;
-        const width = image.get_width();
-        const height = image.get_height();
-        image.free();
+const isJpegStartOfFrameMarker = (marker)=>marker >= 0xc0 && marker <= 0xcf && 0xc4 !== marker && 0xc8 !== marker && 0xcc !== marker;
+function jpegInfoFromBuffer(imageBuffer) {
+    let offset = 2;
+    while(offset < imageBuffer.length){
+        if (0xff !== imageBuffer[offset]) {
+            offset += 1;
+            continue;
+        }
+        while(offset < imageBuffer.length && 0xff === imageBuffer[offset])offset += 1;
+        if (offset >= imageBuffer.length) break;
+        const marker = imageBuffer[offset];
+        offset += 1;
+        if (0xd9 === marker || 0xda === marker) break;
+        if (0x01 === marker || 0xd8 === marker || marker >= 0xd0 && marker <= 0xd7) continue;
+        if (offset + 2 > imageBuffer.length) break;
+        const segmentLength = imageBuffer.readUInt16BE(offset);
+        if (segmentLength < 2 || offset + segmentLength > imageBuffer.length) break;
+        if (isJpegStartOfFrameMarker(marker)) {
+            if (segmentLength < 7) break;
+            const height = imageBuffer.readUInt16BE(offset + 3);
+            const width = imageBuffer.readUInt16BE(offset + 5);
+            node_assert(width && height, 'Invalid image: cannot get width or height');
+            return {
+                width,
+                height
+            };
+        }
+        offset += segmentLength;
+    }
+    throw new Error('Invalid image: cannot get JPEG width or height');
+}
+function encodedImageInfoOfBuffer(imageBuffer) {
+    if (isValidPNGImageBuffer(imageBuffer)) {
+        const width = imageBuffer.readUInt32BE(16);
+        const height = imageBuffer.readUInt32BE(20);
         node_assert(width && height, 'Invalid image: cannot get width or height');
         return {
             width,
             height
         };
-    } catch (error) {
-        if (error instanceof Error && error.message.includes('unreachable')) throw new Error(`Failed to decode image: invalid or corrupted image data. Original error: ${error.message}`);
-        throw error;
     }
+    if (isValidJPEGImageBuffer(imageBuffer)) return jpegInfoFromBuffer(imageBuffer);
+    throw new Error('Invalid image: unsupported format');
+}
+async function imageInfoOfBase64(imageBase64) {
+    const { PhotonImage } = await get_photon();
+    const base64Data = imageBase64.replace(/^data:image\/\w+;base64,/, '');
+    const result = PhotonImage.new_from_base64(base64Data);
+    const image = result instanceof Promise ? await result : result;
+    const width = image.get_width();
+    const height = image.get_height();
+    image.free();
+    node_assert(width && height, 'Invalid image: cannot get width or height');
+    return {
+        width,
+        height
+    };
 }
 function isValidPNGImageBuffer(buffer) {
     if (!buffer || buffer.length < 8) return false;
@@ -35,4 +70,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 { encodedImageInfoOfBuffer, imageInfoOfBase64, isValidImageBuffer, isValidJPEGImageBuffer, isValidPNGImageBuffer, validateScreenshotBuffer };

package/dist/es/img/photon-loader.mjs

@@ -0,0 +1,4 @@
+async function loadPhotonModule() {
+    return import("@silvia-odwyer/photon");
+}
+export { loadPhotonModule };

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 "@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 { setIsMcp } from "../utils.mjs";
+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 };

package/dist/es/mcp/error-formatter.mjs

@@ -0,0 +1,19 @@
+function getErrorMessage(error) {
+    if (error instanceof Error) return error.message;
+    if (null == error) return String(error);
+    if ('object' != typeof error) return String(error);
+    const candidate = extractStringMessage(error);
+    if (candidate) return candidate;
+    try {
+        return JSON.stringify(error);
+    } catch  {
+        return Object.prototype.toString.call(error);
+    }
+}
+function extractStringMessage(error) {
+    const anyError = error;
+    if ('string' == typeof anyError.message && anyError.message) return anyError.message;
+    if (anyError.error && 'string' == typeof anyError.error.message && anyError.error.message) return anyError.error.message;
+    if (anyError.cause && 'string' == typeof anyError.cause.message && anyError.cause.message) return anyError.cause.message;
+}
+export { getErrorMessage };

package/dist/es/mcp/index.mjs

@@ -1,5 +1,7 @@
 export * from "./base-server.mjs";
 export * from "./base-tools.mjs";
+export * from "./init-arg-utils.mjs";
+export * from "./error-formatter.mjs";
 export * from "./tool-generator.mjs";
 export * from "./types.mjs";
 export * from "./inject-report-html-plugin.mjs";

package/dist/es/mcp/init-arg-utils.mjs

@@ -0,0 +1,38 @@
+import { getKeyAliases, isRecord } from "../key-alias-utils.mjs";
+function readAliasedValue(args, key) {
+    for (const alias of getKeyAliases(key))if (alias in args) return args[alias];
+}
+function readNamespacedArg(args, namespace, key) {
+    const namespacedArgs = readAliasedValue(args, namespace);
+    if (isRecord(namespacedArgs)) {
+        const nestedValue = readAliasedValue(namespacedArgs, key);
+        if (void 0 !== nestedValue) return nestedValue;
+    }
+    const dottedValue = readAliasedValue(args, `${namespace}.${key}`);
+    if (void 0 !== dottedValue) return dottedValue;
+    const directValue = readAliasedValue(args, key);
+    if (void 0 !== directValue) return directValue;
+}
+function extractNamespacedArgs(args, namespace, keys) {
+    const extracted = {};
+    for (const key of keys){
+        const value = readNamespacedArg(args, namespace, key);
+        if (void 0 !== value) extracted[key] = value;
+    }
+    return Object.keys(extracted).length > 0 ? extracted : void 0;
+}
+function sanitizeNamespacedArgs(args, namespace, keys) {
+    const excludedKeys = new Set(getKeyAliases(namespace));
+    for (const key of keys){
+        for (const alias of getKeyAliases(key))excludedKeys.add(alias);
+        for (const alias of getKeyAliases(`${namespace}.${key}`))excludedKeys.add(alias);
+    }
+    return Object.fromEntries(Object.entries(args).filter(([key])=>!excludedKeys.has(key)));
+}
+function createNamespacedInitArgSchema(namespace, shape) {
+    return Object.fromEntries(Object.entries(shape).map(([key, value])=>[
+            `${namespace}.${key}`,
+            value
+        ]));
+}
+export { createNamespacedInitArgSchema, extractNamespacedArgs, sanitizeNamespacedArgs };

package/dist/es/mcp/inject-report-html-plugin.mjs

@@ -9,7 +9,7 @@ function injectReportHtmlFromCore(packageDir) {
         setup (api) {
             api.onAfterBuild(()=>{
                 const coreUtilsPath = node_path.resolve(packageDir, '..', 'core', 'dist', 'lib', 'utils.js');
-                if (!node_fs.existsSync(coreUtilsPath)) return void console.warn('[inject-report-html] @midscene/core dist not found, skipping');
+                if (!node_fs.existsSync(coreUtilsPath)) return void console.warn('[inject-report-html] @aiscene/core dist not found, skipping');
                 const coreContent = node_fs.readFileSync(coreUtilsPath, 'utf-8');
                 if (!coreContent.includes(REPLACED_MARK)) return void console.warn('[inject-report-html] HTML not found in core dist. Ensure report builds first.');
                 const markerIndex = coreContent.indexOf(REPLACED_MARK);

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

@@ -1,9 +1,7 @@
+import { parseBase64 } from "@aiscene/shared/img";
 import { z } from "zod";
-import { parseBase64 } from "../img/index.mjs";
 import { getZodDescription, getZodTypeName, isMidsceneLocatorField, unwrapZodField } from "../zod-schema-utils.mjs";
-function getErrorMessage(error) {
-    return error instanceof Error ? error.message : String(error);
-}
+import { getErrorMessage } from "./error-formatter.mjs";
 function describeActionForMCP(action) {
     const actionDesc = action.description || `Execute ${action.name} action`;
     if (!action.paramSchema) return `${action.name} action, ${actionDesc}`;
@@ -70,10 +68,13 @@ function transformSchemaField(key, value) {
         value
     ];
 }
-function extractActionSchema(paramSchema) {
+function extractActionSchema(paramSchema, actionName) {
     if (!paramSchema) return {};
     const shape = getZodObjectShape(paramSchema);
-    if (!shape) return paramSchema;
+    if (!shape) {
+        const typeName = paramSchema?._def?.typeName ?? 'unknown';
+        throw new Error(`Action "${actionName}" declared a non-object paramSchema (${typeName}). CLI and MCP tool schemas must be a ZodObject (e.g. z.object({ uri: z.string() })) or undefined. Wrap primitive fields in an object schema.`);
+    }
     return Object.fromEntries(Object.entries(shape).map(([key, value])=>transformSchemaField(key, value)));
 }
 function getPromptText(prompt) {
@@ -279,17 +280,30 @@ async function captureFailureResult(agent, actionName, errorMessage) {
         };
     }
 }
-function generateToolsFromActionSpace(actionSpace, getAgent) {
+function mergeToolCliMetadata(base, extra) {
+    const options = {
+        ...base?.options ?? {},
+        ...extra?.options ?? {}
+    };
+    return Object.keys(options).length > 0 ? {
+        options
+    } : void 0;
+}
+function generateToolsFromActionSpace(actionSpace, getAgent, sanitizeArgs = (args)=>args, initArgSchema = {}, initArgCliMetadata) {
     return actionSpace.map((action)=>{
-        const schema = extractActionSchema(action.paramSchema);
+        const schema = {
+            ...extractActionSchema(action.paramSchema, action.name),
+            ...initArgSchema
+        };
         return {
             name: action.name,
             description: describeActionForMCP(action),
             schema,
+            cli: initArgCliMetadata,
             handler: async (args)=>{
                 try {
-                    const agent = await getAgent();
-                    const normalizedArgs = normalizeActionArgs(args, action.paramSchema);
+                    const agent = await getAgent(args);
+                    const normalizedArgs = normalizeActionArgs(sanitizeArgs(args), action.paramSchema);
                     let actionResult;
                     try {
                         actionResult = await executeAction(agent, action.name, normalizedArgs);
@@ -308,15 +322,18 @@ function generateToolsFromActionSpace(actionSpace, getAgent) {
         };
     });
 }
-function generateCommonTools(getAgent) {
+function generateCommonTools(getAgent, initArgSchema = {}, initArgCliMetadata) {
     return [
         {
             name: 'take_screenshot',
             description: 'Capture screenshot of current page/screen',
-            schema: {},
-            handler: async ()=>{
+            schema: {
+                ...initArgSchema
+            },
+            cli: initArgCliMetadata,
+            handler: async (args = {})=>{
                 try {
-                    const agent = await getAgent();
+                    const agent = await getAgent(args);
                     const screenshot = await agent.page?.screenshotBase64();
                     if (!screenshot) return createErrorResult('Screenshot not available');
                     const { mimeType, body } = parseBase64(screenshot);
@@ -340,12 +357,14 @@ function generateCommonTools(getAgent) {
             name: 'act',
             description: 'Execute a natural language action. The AI will plan and perform multi-step operations in a single invocation, useful for transient UI interactions (e.g., Spotlight, dropdown menus) that disappear between separate commands.',
             schema: {
-                prompt: z.string().describe('Natural language description of the action to perform, e.g. "press Command+Space, type Safari, press Enter"')
+                prompt: z.string().describe('Natural language description of the action to perform, e.g. "press Command+Space, type Safari, press Enter"'),
+                ...initArgSchema
             },
-            handler: async (args)=>{
+            cli: mergeToolCliMetadata(void 0, initArgCliMetadata),
+            handler: async (args = {})=>{
                 const prompt = args.prompt;
                 try {
-                    const agent = await getAgent();
+                    const agent = await getAgent(args);
                     if (!agent.aiAction) return createErrorResult('act is not supported by this agent');
                     const result = await agent.aiAction(prompt, {
                         deepThink: false
@@ -365,6 +384,35 @@ function generateCommonTools(getAgent) {
                     return createErrorResult(`Failed to execute act: ${errorMessage}`);
                 }
             }
+        },
+        {
+            name: 'assert',
+            description: 'Assert a natural language statement against the current page/screen.',
+            schema: {
+                prompt: z.string().describe('Natural language assertion to verify, e.g. "there is a login button visible"'),
+                ...initArgSchema
+            },
+            cli: mergeToolCliMetadata(void 0, initArgCliMetadata),
+            handler: async (args = {})=>{
+                const prompt = args.prompt;
+                try {
+                    const agent = await getAgent(args);
+                    if (!agent.aiAssert) return createErrorResult('assert is not supported by this agent');
+                    await agent.aiAssert(prompt);
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: 'Assertion passed.'
+                            }
+                        ]
+                    };
+                } catch (error) {
+                    const errorMessage = getErrorMessage(error);
+                    console.error('Error executing assert:', errorMessage);
+                    return createErrorResult(`Failed to execute assert: ${errorMessage}`);
+                }
+            }
         }
     ];
 }