@godscene/shared 1.7.11

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

@@ -0,0 +1,53 @@
+import node_fs from "node:fs";
+import node_path from "node:path";
+const MAGIC_STRING = 'REPLACE_ME_WITH_REPORT_HTML';
+const REPLACED_MARK = '/*REPORT_HTML_REPLACED*/';
+const REG_EXP_FOR_REPLACE = /\/\*REPORT_HTML_REPLACED\*\/.*/;
+function injectReportHtmlFromCore(packageDir) {
+    return {
+        name: 'inject-report-html-from-core',
+        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] @godscene/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);
+                const jsonStart = markerIndex + REPLACED_MARK.length;
+                let jsonEnd = jsonStart;
+                if ('"' === coreContent[jsonStart]) {
+                    jsonEnd = jsonStart + 1;
+                    while(jsonEnd < coreContent.length)if ('\\' === coreContent[jsonEnd]) jsonEnd += 2;
+                    else if ('"' === coreContent[jsonEnd]) {
+                        jsonEnd += 1;
+                        break;
+                    } else jsonEnd += 1;
+                }
+                const jsonString = coreContent.slice(jsonStart, jsonEnd);
+                if (!jsonString || jsonString.length < 10) return void console.warn('[inject-report-html] Failed to extract HTML from core');
+                const finalContent = `${REPLACED_MARK}${jsonString}`;
+                const distDir = node_path.join(packageDir, 'dist');
+                if (!node_fs.existsSync(distDir)) return;
+                const jsFiles = node_fs.readdirSync(distDir).filter((f)=>f.endsWith('.js'));
+                let injectedCount = 0;
+                for (const file of jsFiles){
+                    const filePath = node_path.join(distDir, file);
+                    const content = node_fs.readFileSync(filePath, 'utf-8');
+                    if (content.includes(REPLACED_MARK)) {
+                        if (REG_EXP_FOR_REPLACE.test(content)) {
+                            node_fs.writeFileSync(filePath, content.replace(REG_EXP_FOR_REPLACE, ()=>finalContent));
+                            console.log(`[inject-report-html] Updated: ${file}`);
+                            injectedCount++;
+                        }
+                    } else if (content.includes(`'${MAGIC_STRING}'`)) {
+                        node_fs.writeFileSync(filePath, content.replace(`'${MAGIC_STRING}'`, ()=>finalContent));
+                        console.log(`[inject-report-html] Injected: ${file}`);
+                        injectedCount++;
+                    }
+                }
+                if (injectedCount > 0) console.log(`[inject-report-html] Completed: ${injectedCount} file(s)`);
+            });
+        }
+    };
+}
+export { injectReportHtmlFromCore };

package/dist/es/mcp/launcher-helper.mjs

@@ -0,0 +1,52 @@
+function createMCPServerLauncher(config) {
+    const { agent, platformName, ToolsManagerClass, MCPServerClass } = config;
+    function validateAgent() {
+        const device = agent.interface;
+        if (!device) throw new Error(`Agent must have an 'interface' property that references the underlying device.
+Please ensure your agent instance is properly initialized with a device interface.
+Expected: agent.interface to be defined, but got: ${typeof device}
+Solution: Check that your agent constructor properly sets the interface property.`);
+    }
+    function createToolsManager() {
+        const toolsManager = new ToolsManagerClass();
+        toolsManager.agent = agent;
+        return toolsManager;
+    }
+    function logStartupInfo(mode, additionalInfo) {
+        const device = agent.interface;
+        console.log(`Starting Midscene ${platformName} MCP Server (${mode})...`);
+        console.log(`Agent: ${agent.constructor.name}`);
+        console.log(`Device: ${device.constructor.name}`);
+        if (additionalInfo?.port !== void 0) console.log(`Port: ${additionalInfo.port}`);
+        if (additionalInfo?.host) console.log(`Host: ${additionalInfo.host}`);
+    }
+    return {
+        async launch (options = {}) {
+            const { verbose = true } = options;
+            validateAgent();
+            if (verbose) logStartupInfo('stdio');
+            const toolsManager = createToolsManager();
+            const server = new MCPServerClass(toolsManager);
+            const result = await server.launch();
+            if (verbose) console.log(`${platformName} MCP Server started (stdio mode)`);
+            return result;
+        },
+        async launchHttp (options) {
+            const { port, host = 'localhost', verbose = true } = options;
+            validateAgent();
+            if (verbose) logStartupInfo('HTTP', {
+                port,
+                host
+            });
+            const toolsManager = createToolsManager();
+            const server = new MCPServerClass(toolsManager);
+            const result = await server.launchHttp({
+                port,
+                host
+            });
+            if (verbose) console.log(`${platformName} MCP Server started on http://${result.host}:${result.port}/mcp`);
+            return result;
+        }
+    };
+}
+export { createMCPServerLauncher };

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

@@ -0,0 +1,419 @@
+import { parseBase64 } from "@godscene/shared/img";
+import { z } from "zod";
+import { getZodDescription, getZodTypeName, isMidsceneLocatorField, unwrapZodField } from "../zod-schema-utils.mjs";
+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}`;
+    const shape = getZodObjectShape(action.paramSchema);
+    if (!shape) {
+        const typeName = getZodTypeName(action.paramSchema);
+        const description = getZodDescription(action.paramSchema);
+        const paramDesc = description ? `${typeName} - ${description}` : typeName;
+        return `${action.name} action, ${actionDesc}. Parameter: ${paramDesc}`;
+    }
+    const paramDescriptions = [];
+    for (const [key, field] of Object.entries(shape))if (field && 'object' == typeof field) {
+        const isFieldOptional = 'function' == typeof field.isOptional && field.isOptional();
+        const typeName = getZodTypeName(field);
+        const description = getZodDescription(field);
+        let paramStr = `${key}${isFieldOptional ? '?' : ''} (${typeName})`;
+        if (description) paramStr += ` - ${description}`;
+        paramDescriptions.push(paramStr);
+    }
+    if (0 === paramDescriptions.length) return `${action.name} action, ${actionDesc}`;
+    return `${action.name} action, ${actionDesc}. Parameters: ${paramDescriptions.join('; ')}`;
+}
+function isZodOptional(value) {
+    return '_def' in value && value._def?.typeName === 'ZodOptional';
+}
+function unwrapOptional(value) {
+    if (isZodOptional(value)) return {
+        innerValue: value._def.innerType,
+        isOptional: true
+    };
+    return {
+        innerValue: value,
+        isOptional: false
+    };
+}
+function getZodObjectShape(value) {
+    if (!value) return;
+    const actualValue = unwrapZodField(value);
+    if (actualValue._def?.typeName !== 'ZodObject') return;
+    if ('function' == typeof actualValue._def.shape) return actualValue._def.shape();
+    return actualValue.shape;
+}
+function isRecord(value) {
+    return 'object' == typeof value && null !== value && !Array.isArray(value);
+}
+function makePromptOptional(shape, wrapInOptional) {
+    const newShape = {
+        ...shape
+    };
+    newShape.prompt = shape.prompt.optional();
+    let newSchema = z.object(newShape).passthrough();
+    if (wrapInOptional) newSchema = newSchema.optional();
+    return newSchema;
+}
+function transformSchemaField(key, value) {
+    const { innerValue, isOptional } = unwrapOptional(value);
+    const shape = getZodObjectShape(innerValue);
+    if (shape && isMidsceneLocatorField(innerValue)) return [
+        key,
+        makePromptOptional(shape, isOptional)
+    ];
+    return [
+        key,
+        value
+    ];
+}
+function extractActionSchema(paramSchema, actionName) {
+    if (!paramSchema) return {};
+    const shape = getZodObjectShape(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) {
+    if ('string' == typeof prompt) return prompt;
+    if (isRecord(prompt) && 'string' == typeof prompt.prompt) return prompt.prompt;
+}
+function moveLocateExtrasIntoPrompt(value, locateFieldKeys) {
+    const promptText = getPromptText(value.prompt);
+    if (!promptText) return value;
+    const normalizedPrompt = isRecord(value.prompt) ? {
+        ...value.prompt
+    } : {
+        prompt: promptText
+    };
+    const normalizedLocate = {};
+    let movedExtraField = false;
+    for (const [key, fieldValue] of Object.entries(value))if ('prompt' !== key) {
+        if (locateFieldKeys.has(key)) {
+            normalizedLocate[key] = fieldValue;
+            continue;
+        }
+        movedExtraField = true;
+        if (!(key in normalizedPrompt)) normalizedPrompt[key] = fieldValue;
+    }
+    if (!movedExtraField) return value;
+    return {
+        ...normalizedLocate,
+        prompt: normalizedPrompt
+    };
+}
+function normalizeLocateLikeArg(value, fieldSchema) {
+    if ('string' == typeof value) return {
+        prompt: value
+    };
+    if (!isRecord(value)) return value;
+    const shape = getZodObjectShape(fieldSchema);
+    if (!shape) return value;
+    return moveLocateExtrasIntoPrompt(value, new Set(Object.keys(shape)));
+}
+function normalizeActionArgs(args, paramSchema) {
+    if (!paramSchema) return args;
+    const shape = getZodObjectShape(paramSchema);
+    if (!shape) return args;
+    return Object.fromEntries(Object.entries(args).map(([key, value])=>{
+        const fieldSchema = shape[key];
+        if (!fieldSchema) return [
+            key,
+            value
+        ];
+        if (isMidsceneLocatorField(fieldSchema)) return [
+            key,
+            normalizeLocateLikeArg(value, fieldSchema)
+        ];
+        return [
+            key,
+            value
+        ];
+    }));
+}
+function serializeArgsToDescription(args) {
+    try {
+        return Object.entries(args).map(([key, value])=>{
+            if ('object' == typeof value && null !== value) try {
+                return `${key}: ${JSON.stringify(value)}`;
+            } catch  {
+                return `${key}: [object]`;
+            }
+            return `${key}: "${value}"`;
+        }).join(', ');
+    } catch (error) {
+        const errorMessage = getErrorMessage(error);
+        console.error('Error serializing args:', errorMessage);
+        return `[args serialization failed: ${errorMessage}]`;
+    }
+}
+function buildActionInstruction(actionName, args) {
+    const locatePrompt = isRecord(args.locate) ? getPromptText(args.locate.prompt) : void 0;
+    switch(actionName){
+        case 'Tap':
+            return locatePrompt ? `Tap on "${locatePrompt}"` : 'Tap';
+        case 'Input':
+            {
+                const value = args.value ?? args.content ?? '';
+                return locatePrompt ? `Input "${value}" into "${locatePrompt}"` : `Input "${value}"`;
+            }
+        case 'Scroll':
+            {
+                const direction = args.direction ?? 'down';
+                return locatePrompt ? `Scroll ${direction} on "${locatePrompt}"` : `Scroll ${direction}`;
+            }
+        case 'Hover':
+            return locatePrompt ? `Hover over "${locatePrompt}"` : 'Hover';
+        case 'KeyboardPress':
+            {
+                const key = args.value ?? args.key ?? '';
+                return `Press key "${key}"`;
+            }
+        default:
+            {
+                const argsDescription = serializeArgsToDescription(args);
+                return argsDescription ? `${actionName}: ${argsDescription}` : actionName;
+            }
+    }
+}
+async function executeAction(agent, actionName, args) {
+    if (agent.callActionInActionSpace) return agent.callActionInActionSpace(actionName, args);
+    if (agent.aiAction) {
+        const instruction = buildActionInstruction(actionName, args);
+        return agent.aiAction(instruction);
+    }
+    throw new Error(`Action "${actionName}" is not supported by this agent`);
+}
+async function captureScreenshotResult(agent, actionName, actionResult) {
+    const content = [
+        {
+            type: 'text',
+            text: `Action "${actionName}" completed.`
+        }
+    ];
+    if (void 0 !== actionResult) content.push({
+        type: 'text',
+        text: `Result: ${serializeActionResult(actionResult)}`
+    });
+    try {
+        const screenshot = await agent.page?.screenshotBase64();
+        if (!screenshot) return {
+            content
+        };
+        const { mimeType, body } = parseBase64(screenshot);
+        content.push({
+            type: 'image',
+            data: body,
+            mimeType
+        });
+        return {
+            content
+        };
+    } catch (error) {
+        const errorMessage = getErrorMessage(error);
+        console.error('Error capturing screenshot:', errorMessage);
+        content[0] = {
+            type: 'text',
+            text: `Action "${actionName}" completed (screenshot unavailable: ${errorMessage})`
+        };
+        return {
+            content
+        };
+    }
+}
+function serializeActionResult(actionResult) {
+    if ('string' == typeof actionResult) return actionResult;
+    try {
+        return JSON.stringify(actionResult);
+    } catch  {
+        return String(actionResult);
+    }
+}
+function createErrorResult(message) {
+    return {
+        content: [
+            {
+                type: 'text',
+                text: message
+            }
+        ],
+        isError: true
+    };
+}
+async function captureFailureResult(agent, actionName, errorMessage) {
+    const warningText = `Warning: Action "${actionName}" failed: ${errorMessage}. Check the screenshot below for the current page state and decide how to proceed.`;
+    try {
+        const screenshot = await agent.page?.screenshotBase64();
+        if (!screenshot) return {
+            content: [
+                {
+                    type: 'text',
+                    text: warningText
+                }
+            ]
+        };
+        const { mimeType, body } = parseBase64(screenshot);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: warningText
+                },
+                {
+                    type: 'image',
+                    data: body,
+                    mimeType
+                }
+            ]
+        };
+    } catch  {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: warningText
+                }
+            ]
+        };
+    }
+}
+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, action.name),
+            ...initArgSchema
+        };
+        return {
+            name: action.name,
+            description: describeActionForMCP(action),
+            schema,
+            cli: initArgCliMetadata,
+            handler: async (args)=>{
+                try {
+                    const agent = await getAgent(args);
+                    const normalizedArgs = normalizeActionArgs(sanitizeArgs(args), action.paramSchema);
+                    let actionResult;
+                    try {
+                        actionResult = await executeAction(agent, action.name, normalizedArgs);
+                    } catch (error) {
+                        const errorMessage = getErrorMessage(error);
+                        console.error(`Error executing action "${action.name}":`, errorMessage);
+                        return await captureFailureResult(agent, action.name, errorMessage);
+                    }
+                    return await captureScreenshotResult(agent, action.name, actionResult);
+                } catch (error) {
+                    const errorMessage = getErrorMessage(error);
+                    console.error(`Error in handler for "${action.name}":`, errorMessage);
+                    return createErrorResult(`Failed to get agent or execute action "${action.name}": ${errorMessage}`);
+                }
+            }
+        };
+    });
+}
+function generateCommonTools(getAgent, initArgSchema = {}, initArgCliMetadata) {
+    return [
+        {
+            name: 'take_screenshot',
+            description: 'Capture screenshot of current page/screen',
+            schema: {
+                ...initArgSchema
+            },
+            cli: initArgCliMetadata,
+            handler: async (args = {})=>{
+                try {
+                    const agent = await getAgent(args);
+                    const screenshot = await agent.page?.screenshotBase64();
+                    if (!screenshot) return createErrorResult('Screenshot not available');
+                    const { mimeType, body } = parseBase64(screenshot);
+                    return {
+                        content: [
+                            {
+                                type: 'image',
+                                data: body,
+                                mimeType
+                            }
+                        ]
+                    };
+                } catch (error) {
+                    const errorMessage = getErrorMessage(error);
+                    console.error('Error taking screenshot:', errorMessage);
+                    return createErrorResult(`Failed to capture screenshot: ${errorMessage}`);
+                }
+            }
+        },
+        {
+            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"'),
+                ...initArgSchema
+            },
+            cli: mergeToolCliMetadata(void 0, initArgCliMetadata),
+            handler: async (args = {})=>{
+                const prompt = args.prompt;
+                try {
+                    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
+                    });
+                    const screenshotResult = await captureScreenshotResult(agent, 'act');
+                    if (result) {
+                        const message = 'string' == typeof result ? result : JSON.stringify(result);
+                        screenshotResult.content.unshift({
+                            type: 'text',
+                            text: `Task finished, message: ${message}`
+                        });
+                    }
+                    return screenshotResult;
+                } catch (error) {
+                    const errorMessage = getErrorMessage(error);
+                    console.error('Error executing act:', errorMessage);
+                    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}`);
+                }
+            }
+        }
+    ];
+}
+export { generateCommonTools, generateToolsFromActionSpace };

package/dist/es/mcp/types.mjs

@@ -0,0 +1,3 @@
+const defaultAppLoadingTimeoutMs = 10000;
+const defaultAppLoadingCheckIntervalMs = 2000;
+export { defaultAppLoadingCheckIntervalMs, defaultAppLoadingTimeoutMs };