@godscene/shared 1.7.11

package/dist/es/logger.mjs

@@ -0,0 +1,64 @@
+import node_fs from "node:fs";
+import node_path from "node:path";
+import node_util from "node:util";
+import debug from "debug";
+import { getMidsceneRunSubDir } from "./common.mjs";
+import { ifInNode } from "./utils.mjs";
+const topicPrefix = 'midscene';
+const logStreams = new Map();
+const debugInstances = new Map();
+function getLogStream(topic) {
+    const topicFileName = topic.replace(/:/g, '-');
+    if (!logStreams.has(topicFileName)) {
+        const logFile = node_path.join(getMidsceneRunSubDir('log'), `${topicFileName}.log`);
+        const stream = node_fs.createWriteStream(logFile, {
+            flags: 'a'
+        });
+        logStreams.set(topicFileName, stream);
+    }
+    return logStreams.get(topicFileName);
+}
+function writeLogToFile(topic, message) {
+    if (!ifInNode) return;
+    const stream = getLogStream(topic);
+    const now = new Date();
+    const isoDate = now.toLocaleDateString('sv-SE');
+    const isoTime = now.toLocaleTimeString('sv-SE');
+    const milliseconds = now.getMilliseconds().toString().padStart(3, '0');
+    const timezoneOffsetMinutes = now.getTimezoneOffset();
+    const sign = timezoneOffsetMinutes <= 0 ? '+' : '-';
+    const hours = Math.floor(Math.abs(timezoneOffsetMinutes) / 60).toString().padStart(2, '0');
+    const minutes = (Math.abs(timezoneOffsetMinutes) % 60).toString().padStart(2, '0');
+    const timezoneString = `${sign}${hours}:${minutes}`;
+    const localISOTime = `${isoDate}T${isoTime}.${milliseconds}${timezoneString}`;
+    stream.write(`[${localISOTime}] ${message}\n`);
+}
+function getDebug(topic, options) {
+    const fullTopic = `${topicPrefix}:${topic}`;
+    const withConsole = options?.console ?? false;
+    const cacheKey = withConsole ? `${fullTopic}:withConsole` : fullTopic;
+    if (!debugInstances.has(cacheKey)) if (withConsole) {
+        const baseFn = getDebug(topic);
+        const wrapper = (...args)=>{
+            baseFn(...args);
+            console.warn('[Midscene]', ...args);
+        };
+        debugInstances.set(cacheKey, wrapper);
+    } else {
+        const debugFn = debug(fullTopic);
+        const wrapper = (...args)=>{
+            if (ifInNode) {
+                const message = node_util.format(...args);
+                writeLogToFile(topic, message);
+            }
+            debugFn(...args);
+        };
+        debugInstances.set(cacheKey, wrapper);
+    }
+    return debugInstances.get(cacheKey);
+}
+function enableDebug(topic) {
+    if (ifInNode) return;
+    debug.enable(`${topicPrefix}:${topic}`);
+}
+export { enableDebug, getDebug };

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

@@ -0,0 +1,282 @@
+import { randomUUID } from "node:crypto";
+import { setIsMcp } from "@godscene/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,
+        enumerable: true,
+        configurable: true,
+        writable: true
+    });
+    else obj[key] = value;
+    return obj;
+}
+const CLI_ARGS_CONFIG = {
+    mode: {
+        type: 'string',
+        default: 'stdio'
+    },
+    port: {
+        type: 'string',
+        default: '3000'
+    },
+    host: {
+        type: 'string',
+        default: 'localhost'
+    }
+};
+function launchMCPServer(server, args) {
+    if ('http' === args.mode) return server.launchHttp({
+        port: Number.parseInt(args.port || '3000', 10),
+        host: args.host || 'localhost'
+    });
+    return server.launch();
+}
+const SESSION_TIMEOUT_MS = 1800000;
+const CLEANUP_INTERVAL_MS = 300000;
+const MAX_SESSIONS = 100;
+class BaseMCPServer {
+    async initializeToolsManager() {
+        setIsMcp(true);
+        this.toolsManager = this.providedToolsManager || this.createToolsManager();
+        try {
+            await this.toolsManager.initTools();
+        } catch (error) {
+            const message = getErrorMessage(error);
+            console.error(`Failed to initialize tools: ${message}`);
+            console.error('Tools will be initialized on first use');
+        }
+        this.toolsManager.attachToServer(this.mcpServer);
+    }
+    async performCleanup() {
+        console.error(`${this.config.name} closing...`);
+        this.mcpServer.close();
+        await this.toolsManager?.destroy?.().catch(console.error);
+    }
+    async launch() {
+        console.log = (...args)=>{
+            console.error('[LOG]', ...args);
+        };
+        console.info = (...args)=>{
+            console.error('[INFO]', ...args);
+        };
+        console.debug = (...args)=>{
+            console.error('[DEBUG]', ...args);
+        };
+        await this.initializeToolsManager();
+        const transport = new StdioServerTransport();
+        try {
+            await this.mcpServer.connect(transport);
+        } catch (error) {
+            const message = getErrorMessage(error);
+            console.error(`Failed to connect MCP stdio transport: ${message}`);
+            throw new Error(`Failed to initialize MCP stdio transport: ${message}`);
+        }
+        let isShuttingDown = false;
+        const cleanup = ()=>{
+            if (isShuttingDown) return;
+            isShuttingDown = true;
+            console.error(`${this.config.name} shutting down...`);
+            this.performCleanup().finally(()=>process.exit(0));
+        };
+        process.on('uncaughtException', (error)=>{
+            if ('EPIPE' === error.code || 'ERR_STREAM_DESTROYED' === error.code) return void cleanup();
+            console.error(`[${this.config.name}] Uncaught Exception:`, error);
+            console.error('Stack:', error.stack);
+        });
+        process.on('unhandledRejection', (reason)=>{
+            console.error(`[${this.config.name}] Unhandled Rejection:`, reason);
+            if (reason instanceof Error) console.error('Stack:', reason.stack);
+        });
+        process.stdin.on('close', cleanup);
+        process.stdin.on('end', cleanup);
+        process.stdout.on('error', cleanup);
+        process.once('SIGINT', cleanup);
+        process.once('SIGTERM', cleanup);
+        process.once('SIGHUP', cleanup);
+        return {
+            close: async ()=>{
+                this.performCleanup();
+            }
+        };
+    }
+    async launchHttp(options) {
+        if (!Number.isInteger(options.port) || options.port < 1 || options.port > 65535) throw new Error(`Invalid port number: ${options.port}. Port must be between 1 and 65535.`);
+        await this.initializeToolsManager();
+        const app = express();
+        app.use(express.json({
+            limit: '10mb'
+        }));
+        const sessions = new Map();
+        app.all('/mcp', async (req, res)=>{
+            const startTime = Date.now();
+            const requestId = randomUUID().substring(0, 8);
+            try {
+                const rawSessionId = req.headers['mcp-session-id'];
+                const sessionId = Array.isArray(rawSessionId) ? rawSessionId[0] : rawSessionId;
+                let session = sessionId ? sessions.get(sessionId) : void 0;
+                if (!session && 'POST' === req.method) {
+                    if (sessions.size >= MAX_SESSIONS) {
+                        console.error(`[${new Date().toISOString()}] [${requestId}] Session limit reached: ${sessions.size}/${MAX_SESSIONS}`);
+                        res.status(503).json({
+                            error: 'Too many active sessions',
+                            message: 'Server is at maximum capacity. Please try again later.'
+                        });
+                        return;
+                    }
+                    session = await this.createHttpSession(sessions);
+                    console.log(`[${new Date().toISOString()}] [${requestId}] New session created: ${session.transport.sessionId}`);
+                }
+                if (session) {
+                    session.lastAccessedAt = new Date();
+                    await session.transport.handleRequest(req, res, req.body);
+                    const duration = Date.now() - startTime;
+                    console.log(`[${new Date().toISOString()}] [${requestId}] Request completed in ${duration}ms`);
+                } else {
+                    console.error(`[${new Date().toISOString()}] [${requestId}] Invalid session or GET without session`);
+                    res.status(400).json({
+                        error: 'Invalid session or GET without session'
+                    });
+                }
+            } catch (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({
+                    error: 'Internal server error',
+                    message: 'Failed to process MCP request'
+                });
+            }
+        });
+        const host = options.host || 'localhost';
+        const server = app.listen(options.port, host, ()=>{
+            console.log(`${this.config.name} HTTP server listening on http://${host}:${options.port}/mcp`);
+        }).on('error', (error)=>{
+            if ('EADDRINUSE' === error.code) console.error(`ERROR: Port ${options.port} is already in use.\nPlease try a different port: --port=<number>\nExample: --mode=http --port=${options.port + 1}`);
+            else if ('EACCES' === error.code) console.error(`ERROR: Permission denied to bind to port ${options.port}.\nPorts below 1024 require root/admin privileges.\nPlease use a port above 1024 or run with elevated privileges.`);
+            else console.error(`ERROR: Failed to start HTTP server on ${host}:${options.port}\nReason: ${error.message}\nCode: ${error.code || 'unknown'}`);
+            process.exit(1);
+        });
+        const cleanupInterval = this.startSessionCleanup(sessions);
+        this.setupHttpShutdownHandlers(server, sessions, cleanupInterval);
+        return {
+            port: options.port,
+            host,
+            close: async ()=>{
+                clearInterval(cleanupInterval);
+                for (const session of sessions.values())try {
+                    await session.transport.close();
+                } catch (error) {
+                    const message = getErrorMessage(error);
+                    console.error(`Failed to close session ${session.transport.sessionId}: ${message}`);
+                }
+                sessions.clear();
+                return new Promise((resolve)=>{
+                    server.close(async (err)=>{
+                        if (err) console.error('Error closing HTTP server:', err);
+                        await this.performCleanup();
+                        resolve();
+                    });
+                });
+            }
+        };
+    }
+    async createHttpSession(sessions) {
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: ()=>randomUUID(),
+            onsessioninitialized: (sid)=>{
+                sessions.set(sid, {
+                    transport,
+                    createdAt: new Date(),
+                    lastAccessedAt: new Date()
+                });
+                console.log(`[${new Date().toISOString()}] Session ${sid} initialized (total: ${sessions.size})`);
+            }
+        });
+        transport.onclose = ()=>{
+            if (transport.sessionId) {
+                sessions.delete(transport.sessionId);
+                console.log(`[${new Date().toISOString()}] Session ${transport.sessionId} closed (remaining: ${sessions.size})`);
+            }
+        };
+        try {
+            await this.mcpServer.connect(transport);
+        } catch (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}`);
+        }
+        return {
+            transport,
+            createdAt: new Date(),
+            lastAccessedAt: new Date()
+        };
+    }
+    startSessionCleanup(sessions) {
+        return setInterval(()=>{
+            const now = Date.now();
+            for (const [sid, session] of sessions)if (now - session.lastAccessedAt.getTime() > SESSION_TIMEOUT_MS) try {
+                session.transport.close();
+                sessions.delete(sid);
+                console.log(`[${new Date().toISOString()}] Session ${sid} cleaned up due to inactivity (remaining: ${sessions.size})`);
+            } catch (error) {
+                const message = getErrorMessage(error);
+                console.error(`[${new Date().toISOString()}] Failed to close session ${sid} during cleanup: ${message}`);
+                sessions.delete(sid);
+            }
+        }, CLEANUP_INTERVAL_MS);
+    }
+    setupHttpShutdownHandlers(server, sessions, cleanupInterval) {
+        const cleanup = ()=>{
+            console.error(`${this.config.name} shutting down...`);
+            clearInterval(cleanupInterval);
+            for (const session of sessions.values())try {
+                session.transport.close();
+            } catch (error) {
+                const message = getErrorMessage(error);
+                console.error(`Error closing session during shutdown: ${message}`);
+            }
+            sessions.clear();
+            try {
+                server.close(()=>{
+                    this.performCleanup().finally(()=>process.exit(0));
+                });
+                setTimeout(()=>{
+                    console.error('Forcefully shutting down after timeout');
+                    this.performCleanup().finally(()=>process.exit(1));
+                }, 5000);
+            } catch (error) {
+                const message = getErrorMessage(error);
+                console.error(`Error closing HTTP server: ${message}`);
+                this.performCleanup().finally(()=>process.exit(1));
+            }
+        };
+        process.once('SIGINT', cleanup);
+        process.once('SIGTERM', cleanup);
+    }
+    getServer() {
+        return this.mcpServer;
+    }
+    getToolsManager() {
+        return this.toolsManager;
+    }
+    constructor(config, toolsManager){
+        _define_property(this, "mcpServer", void 0);
+        _define_property(this, "toolsManager", void 0);
+        _define_property(this, "config", void 0);
+        _define_property(this, "providedToolsManager", void 0);
+        this.config = config;
+        this.mcpServer = new McpServer({
+            name: config.name,
+            version: config.version,
+            description: config.description
+        });
+        this.providedToolsManager = toolsManager;
+    }
+}
+export { BaseMCPServer, CLI_ARGS_CONFIG, launchMCPServer };

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

@@ -0,0 +1,159 @@
+import { parseBase64 } from "@godscene/shared/img";
+import { getDebug } from "@godscene/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, {
+        value: value,
+        enumerable: true,
+        configurable: true,
+        writable: true
+    });
+    else obj[key] = value;
+    return obj;
+}
+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();
+        this.toolDefinitions.push(...platformTools);
+        let actionSpace;
+        if (this.agent) {
+            actionSpace = await this.agent.getActionSpace();
+            debug('Action space from agent:', actionSpace.map((a)=>a.name).join(', '));
+        } else {
+            const tempDevice = this.createTemporaryDevice();
+            actionSpace = tempDevice.actionSpace();
+            await tempDevice.destroy?.();
+            debug('Action space from temporary device:', actionSpace.map((a)=>a.name).join(', '));
+        }
+        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);
+    }
+    attachToServer(server) {
+        this.mcpServer = server;
+        if (0 === this.toolDefinitions.length) debug('Warning: No tools to register. Tools may be initialized lazily.');
+        for (const toolDef of this.toolDefinitions)this.mcpServer.tool(toolDef.name, toolDef.description, toolDef.schema, toolDef.handler);
+        debug('Registered', this.toolDefinitions.length, 'tools');
+    }
+    async destroy() {
+        await this.agent?.destroy?.();
+    }
+    getToolDefinitions() {
+        return this.toolDefinitions;
+    }
+    setAgent(agent) {
+        this.agent = agent;
+    }
+    buildScreenshotContent(screenshot) {
+        const { mimeType, body } = parseBase64(screenshot);
+        return [
+            {
+                type: 'image',
+                data: body,
+                mimeType
+            }
+        ];
+    }
+    buildTextResult(text) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text
+                }
+            ]
+        };
+    }
+    createDisconnectHandler(platformName) {
+        return async ()=>{
+            if (!this.agent) return this.buildTextResult('No active connection to disconnect');
+            try {
+                await this.agent.destroy?.();
+            } catch (error) {
+                debug('Failed to destroy agent during disconnect:', error);
+            }
+            this.agent = void 0;
+            return this.buildTextResult(`Disconnected from ${platformName}`);
+        };
+    }
+    constructor(){
+        _define_property(this, "mcpServer", void 0);
+        _define_property(this, "agent", void 0);
+        _define_property(this, "toolDefinitions", []);
+    }
+}
+export { BaseMidsceneTools };

package/dist/es/mcp/chrome-path.mjs

@@ -0,0 +1,35 @@
+import { existsSync } from "node:fs";
+import { MIDSCENE_MCP_CHROME_PATH, globalConfigManager } from "../env/index.mjs";
+function getSystemChromePath() {
+    const platform = process.platform;
+    const chromePaths = {
+        darwin: [
+            '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+            '/Applications/Chromium.app/Contents/MacOS/Chromium'
+        ],
+        win32: [
+            'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+            'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
+            `C:\\Users\\${process.env.USERNAME ?? process.env.USER}\\AppData\\Local\\Google\\Chrome\\Application\\chrome.exe`
+        ],
+        linux: [
+            '/opt/google/chrome/chrome',
+            '/opt/google/chrome/google-chrome',
+            '/usr/bin/google-chrome-stable',
+            '/usr/bin/google-chrome',
+            '/usr/bin/chromium-browser',
+            '/usr/bin/chromium',
+            '/snap/bin/chromium'
+        ]
+    };
+    const paths = chromePaths[platform] ?? [];
+    return paths.find((p)=>existsSync(p));
+}
+function resolveChromePath() {
+    const envPath = globalConfigManager.getEnvConfigValue(MIDSCENE_MCP_CHROME_PATH);
+    if (envPath && 'auto' !== envPath && existsSync(envPath)) return envPath;
+    const systemPath = getSystemChromePath();
+    if (systemPath) return systemPath;
+    throw new Error('Chrome not found. Install Google Chrome or set MIDSCENE_MCP_CHROME_PATH environment variable.');
+}
+export { getSystemChromePath, resolveChromePath };

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

@@ -0,0 +1,9 @@
+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";
+export * from "./launcher-helper.mjs";
+export * from "./chrome-path.mjs";