@midscene/computer 1.4.6 → 1.4.7

package/dist/lib/index.js

@@ -36,12 +36,14 @@ var __webpack_require__ = {};
 var __webpack_exports__ = {};
 __webpack_require__.r(__webpack_exports__);
 __webpack_require__.d(__webpack_exports__, {
+    checkComputerEnvironment: ()=>checkComputerEnvironment,
+    checkXvfbInstalled: ()=>checkXvfbInstalled,
     checkAccessibilityPermission: ()=>checkAccessibilityPermission,
+    agentFromComputer: ()=>agentFromComputer,
+    needsXvfb: ()=>needsXvfb,
     overrideAIConfig: ()=>env_namespaceObject.overrideAIConfig,
     getConnectedDisplays: ()=>getConnectedDisplays,
-    checkComputerEnvironment: ()=>checkComputerEnvironment,
     ComputerDevice: ()=>ComputerDevice,
-    agentFromComputer: ()=>agentFromComputer,
     ComputerAgent: ()=>ComputerAgent
 });
 const external_node_assert_namespaceObject = require("node:assert");
@@ -55,6 +57,74 @@ const img_namespaceObject = require("@midscene/shared/img");
 const logger_namespaceObject = require("@midscene/shared/logger");
 const external_screenshot_desktop_namespaceObject = require("screenshot-desktop");
 var external_screenshot_desktop_default = /*#__PURE__*/ __webpack_require__.n(external_screenshot_desktop_namespaceObject);
+const external_node_fs_namespaceObject = require("node:fs");
+const debugXvfb = (0, logger_namespaceObject.getDebug)('computer:xvfb');
+function checkXvfbInstalled() {
+    try {
+        (0, external_node_child_process_namespaceObject.execSync)('which Xvfb', {
+            stdio: 'ignore'
+        });
+        return true;
+    } catch  {
+        return false;
+    }
+}
+function findAvailableDisplay(startFrom = 99) {
+    for(let n = startFrom; n < startFrom + 100; n++)if (!(0, external_node_fs_namespaceObject.existsSync)(`/tmp/.X${n}-lock`)) return n;
+    throw new Error(`No available display number found (checked ${startFrom} to ${startFrom + 99})`);
+}
+function startXvfb(options) {
+    const resolution = options?.resolution || '1920x1080x24';
+    const displayNum = options?.displayNumber ?? findAvailableDisplay();
+    const display = `:${displayNum}`;
+    return new Promise((resolve, reject)=>{
+        debugXvfb(`Starting Xvfb on display ${display} with resolution ${resolution}`);
+        const xvfbProcess = (0, external_node_child_process_namespaceObject.spawn)('Xvfb', [
+            display,
+            '-screen',
+            '0',
+            resolution,
+            '-ac',
+            '-nolisten',
+            'tcp'
+        ], {
+            stdio: 'ignore'
+        });
+        let settled = false;
+        xvfbProcess.on('error', (err)=>{
+            if (!settled) {
+                settled = true;
+                reject(new Error(`Failed to start Xvfb: ${err.message}`));
+            }
+        });
+        xvfbProcess.on('exit', (code)=>{
+            if (!settled) {
+                settled = true;
+                reject(new Error(`Xvfb exited unexpectedly with code ${code}`));
+            }
+        });
+        const instance = {
+            process: xvfbProcess,
+            display,
+            stop () {
+                try {
+                    xvfbProcess.kill('SIGTERM');
+                } catch  {}
+            }
+        };
+        setTimeout(()=>{
+            if (!settled) {
+                settled = true;
+                debugXvfb(`Xvfb started on display ${display}`);
+                resolve(instance);
+            }
+        }, 500);
+    });
+}
+function needsXvfb(explicitOpt) {
+    if ('linux' !== process.platform) return false;
+    return true === explicitOpt;
+}
 function _define_property(obj, key, value) {
     if (key in obj) Object.defineProperty(obj, key, {
         value: value,
@@ -225,53 +295,74 @@ class ComputerDevice {
     async connect() {
         debugDevice('Connecting to computer device');
         try {
+            const headless = this.options?.headless ?? 'true' === process.env.MIDSCENE_COMPUTER_HEADLESS_LINUX;
+            if (needsXvfb(headless)) {
+                if (!checkXvfbInstalled()) throw new Error('Xvfb is required for headless mode but not installed. Install: sudo apt-get install xvfb');
+                this.xvfbInstance = await startXvfb({
+                    resolution: this.options?.xvfbResolution
+                });
+                process.env.DISPLAY = this.xvfbInstance.display;
+                debugDevice(`Xvfb started on display ${this.xvfbInstance.display}`);
+                this.xvfbCleanup = ()=>{
+                    if (this.xvfbInstance) {
+                        this.xvfbInstance.stop();
+                        this.xvfbInstance = void 0;
+                    }
+                };
+                process.on('exit', this.xvfbCleanup);
+                process.on('SIGINT', this.xvfbCleanup);
+                process.on('SIGTERM', this.xvfbCleanup);
+            }
             device_libnut = await getLibnut();
             const size = await this.size();
             const displays = await ComputerDevice.listDisplays();
+            const headlessInfo = this.xvfbInstance ? `\nHeadless: true (Xvfb on ${this.xvfbInstance.display})` : '';
             this.description = `
 Type: Computer
 Platform: ${process.platform}
 Display: ${this.displayId || 'Primary'}
 Screen Size: ${size.width}x${size.height}
-Available Displays: ${displays.length > 0 ? displays.map((d)=>d.name).join(', ') : 'Unknown'}
+Available Displays: ${displays.length > 0 ? displays.map((d)=>d.name).join(', ') : 'Unknown'}${headlessInfo}
 `;
             debugDevice('Computer device connected', this.description);
+            await this.healthCheck();
         } catch (error) {
+            if (this.xvfbInstance) {
+                this.xvfbInstance.stop();
+                this.xvfbInstance = void 0;
+            }
             debugDevice(`Failed to connect: ${error}`);
             throw new Error(`Unable to connect to computer device: ${error}`);
         }
-        await this.healthCheck();
     }
     async healthCheck() {
         console.log('[HealthCheck] Starting health check...');
         console.log('[HealthCheck] Taking screenshot...');
-        try {
-            const base64 = await this.screenshotBase64();
-            console.log(`[HealthCheck] Screenshot succeeded (length=${base64.length})`);
-        } catch (error) {
-            console.error(`[HealthCheck] Screenshot failed: ${error}`);
-            process.exit(1);
-        }
+        const screenshotTimeout = 15000;
+        let timeoutId;
+        const timeoutPromise = new Promise((_, reject)=>{
+            timeoutId = setTimeout(()=>reject(new Error('Screenshot timed out')), screenshotTimeout);
+        });
+        const base64 = await Promise.race([
+            this.screenshotBase64().finally(()=>clearTimeout(timeoutId)),
+            timeoutPromise
+        ]);
+        console.log(`[HealthCheck] Screenshot succeeded (length=${base64.length})`);
         console.log('[HealthCheck] Moving mouse...');
-        try {
-            external_node_assert_default()(device_libnut, 'libnut not initialized');
-            const startPos = device_libnut.getMousePos();
-            console.log(`[HealthCheck] Current mouse position: (${startPos.x}, ${startPos.y})`);
-            const offsetX = Math.floor(40 * Math.random()) + 10;
-            const offsetY = Math.floor(40 * Math.random()) + 10;
-            const targetX = startPos.x + offsetX;
-            const targetY = startPos.y + offsetY;
-            console.log(`[HealthCheck] Moving mouse to (${targetX}, ${targetY})...`);
-            device_libnut.moveMouse(targetX, targetY);
-            await (0, utils_namespaceObject.sleep)(50);
-            const movedPos = device_libnut.getMousePos();
-            console.log(`[HealthCheck] Mouse position after move: (${movedPos.x}, ${movedPos.y})`);
-            device_libnut.moveMouse(startPos.x, startPos.y);
-            console.log(`[HealthCheck] Mouse restored to (${startPos.x}, ${startPos.y})`);
-        } catch (error) {
-            console.error(`[HealthCheck] Mouse move failed: ${error}`);
-            process.exit(1);
-        }
+        external_node_assert_default()(device_libnut, 'libnut not initialized');
+        const startPos = device_libnut.getMousePos();
+        console.log(`[HealthCheck] Current mouse position: (${startPos.x}, ${startPos.y})`);
+        const offsetX = Math.floor(40 * Math.random()) + 10;
+        const offsetY = Math.floor(40 * Math.random()) + 10;
+        const targetX = startPos.x + offsetX;
+        const targetY = startPos.y + offsetY;
+        console.log(`[HealthCheck] Moving mouse to (${targetX}, ${targetY})...`);
+        device_libnut.moveMouse(targetX, targetY);
+        await (0, utils_namespaceObject.sleep)(50);
+        const movedPos = device_libnut.getMousePos();
+        console.log(`[HealthCheck] Mouse position after move: (${movedPos.x}, ${movedPos.y})`);
+        device_libnut.moveMouse(startPos.x, startPos.y);
+        console.log(`[HealthCheck] Mouse restored to (${startPos.x}, ${startPos.y})`);
         console.log('[HealthCheck] Health check passed');
     }
     async screenshotBase64() {
@@ -301,8 +392,7 @@ Available Displays: ${displays.length > 0 ? displays.map((d)=>d.name).join(', ')
             const screenSize = device_libnut.getScreenSize();
             return {
                 width: screenSize.width,
-                height: screenSize.height,
-                dpr: 1
+                height: screenSize.height
             };
         } catch (error) {
             debugDevice(`Failed to get screen size: ${error}`);
@@ -567,6 +657,16 @@ Available Displays: ${displays.length > 0 ? displays.map((d)=>d.name).join(', ')
     }
     async destroy() {
         if (this.destroyed) return;
+        if (this.xvfbInstance) {
+            this.xvfbInstance.stop();
+            this.xvfbInstance = void 0;
+        }
+        if (this.xvfbCleanup) {
+            process.removeListener('exit', this.xvfbCleanup);
+            process.removeListener('SIGINT', this.xvfbCleanup);
+            process.removeListener('SIGTERM', this.xvfbCleanup);
+            this.xvfbCleanup = void 0;
+        }
         this.destroyed = true;
         debugDevice('Computer device destroyed');
     }
@@ -579,6 +679,8 @@ Available Displays: ${displays.length > 0 ? displays.map((d)=>d.name).join(', ')
         _define_property(this, "displayId", void 0);
         _define_property(this, "description", void 0);
         _define_property(this, "destroyed", false);
+        _define_property(this, "xvfbInstance", void 0);
+        _define_property(this, "xvfbCleanup", void 0);
         _define_property(this, "useAppleScript", void 0);
         _define_property(this, "uri", void 0);
         this.options = options;
@@ -674,7 +776,9 @@ exports.ComputerDevice = __webpack_exports__.ComputerDevice;
 exports.agentFromComputer = __webpack_exports__.agentFromComputer;
 exports.checkAccessibilityPermission = __webpack_exports__.checkAccessibilityPermission;
 exports.checkComputerEnvironment = __webpack_exports__.checkComputerEnvironment;
+exports.checkXvfbInstalled = __webpack_exports__.checkXvfbInstalled;
 exports.getConnectedDisplays = __webpack_exports__.getConnectedDisplays;
+exports.needsXvfb = __webpack_exports__.needsXvfb;
 exports.overrideAIConfig = __webpack_exports__.overrideAIConfig;
 for(var __rspack_i in __webpack_exports__)if (-1 === [
     "ComputerAgent",
@@ -682,7 +786,9 @@ for(var __rspack_i in __webpack_exports__)if (-1 === [
     "agentFromComputer",
     "checkAccessibilityPermission",
     "checkComputerEnvironment",
+    "checkXvfbInstalled",
     "getConnectedDisplays",
+    "needsXvfb",
     "overrideAIConfig"
 ].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
 Object.defineProperty(exports, '__esModule', {

package/dist/lib/mcp-server.js

@@ -53,6 +53,74 @@ const img_namespaceObject = require("@midscene/shared/img");
 const logger_namespaceObject = require("@midscene/shared/logger");
 const external_screenshot_desktop_namespaceObject = require("screenshot-desktop");
 var external_screenshot_desktop_default = /*#__PURE__*/ __webpack_require__.n(external_screenshot_desktop_namespaceObject);
+const external_node_fs_namespaceObject = require("node:fs");
+const debugXvfb = (0, logger_namespaceObject.getDebug)('computer:xvfb');
+function checkXvfbInstalled() {
+    try {
+        (0, external_node_child_process_namespaceObject.execSync)('which Xvfb', {
+            stdio: 'ignore'
+        });
+        return true;
+    } catch  {
+        return false;
+    }
+}
+function findAvailableDisplay(startFrom = 99) {
+    for(let n = startFrom; n < startFrom + 100; n++)if (!(0, external_node_fs_namespaceObject.existsSync)(`/tmp/.X${n}-lock`)) return n;
+    throw new Error(`No available display number found (checked ${startFrom} to ${startFrom + 99})`);
+}
+function startXvfb(options) {
+    const resolution = options?.resolution || '1920x1080x24';
+    const displayNum = options?.displayNumber ?? findAvailableDisplay();
+    const display = `:${displayNum}`;
+    return new Promise((resolve, reject)=>{
+        debugXvfb(`Starting Xvfb on display ${display} with resolution ${resolution}`);
+        const xvfbProcess = (0, external_node_child_process_namespaceObject.spawn)('Xvfb', [
+            display,
+            '-screen',
+            '0',
+            resolution,
+            '-ac',
+            '-nolisten',
+            'tcp'
+        ], {
+            stdio: 'ignore'
+        });
+        let settled = false;
+        xvfbProcess.on('error', (err)=>{
+            if (!settled) {
+                settled = true;
+                reject(new Error(`Failed to start Xvfb: ${err.message}`));
+            }
+        });
+        xvfbProcess.on('exit', (code)=>{
+            if (!settled) {
+                settled = true;
+                reject(new Error(`Xvfb exited unexpectedly with code ${code}`));
+            }
+        });
+        const instance = {
+            process: xvfbProcess,
+            display,
+            stop () {
+                try {
+                    xvfbProcess.kill('SIGTERM');
+                } catch  {}
+            }
+        };
+        setTimeout(()=>{
+            if (!settled) {
+                settled = true;
+                debugXvfb(`Xvfb started on display ${display}`);
+                resolve(instance);
+            }
+        }, 500);
+    });
+}
+function needsXvfb(explicitOpt) {
+    if ('linux' !== process.platform) return false;
+    return true === explicitOpt;
+}
 function _define_property(obj, key, value) {
     if (key in obj) Object.defineProperty(obj, key, {
         value: value,
@@ -223,53 +291,74 @@ class ComputerDevice {
     async connect() {
         debugDevice('Connecting to computer device');
         try {
+            const headless = this.options?.headless ?? 'true' === process.env.MIDSCENE_COMPUTER_HEADLESS_LINUX;
+            if (needsXvfb(headless)) {
+                if (!checkXvfbInstalled()) throw new Error('Xvfb is required for headless mode but not installed. Install: sudo apt-get install xvfb');
+                this.xvfbInstance = await startXvfb({
+                    resolution: this.options?.xvfbResolution
+                });
+                process.env.DISPLAY = this.xvfbInstance.display;
+                debugDevice(`Xvfb started on display ${this.xvfbInstance.display}`);
+                this.xvfbCleanup = ()=>{
+                    if (this.xvfbInstance) {
+                        this.xvfbInstance.stop();
+                        this.xvfbInstance = void 0;
+                    }
+                };
+                process.on('exit', this.xvfbCleanup);
+                process.on('SIGINT', this.xvfbCleanup);
+                process.on('SIGTERM', this.xvfbCleanup);
+            }
             libnut = await getLibnut();
             const size = await this.size();
             const displays = await ComputerDevice.listDisplays();
+            const headlessInfo = this.xvfbInstance ? `\nHeadless: true (Xvfb on ${this.xvfbInstance.display})` : '';
             this.description = `
 Type: Computer
 Platform: ${process.platform}
 Display: ${this.displayId || 'Primary'}
 Screen Size: ${size.width}x${size.height}
-Available Displays: ${displays.length > 0 ? displays.map((d)=>d.name).join(', ') : 'Unknown'}
+Available Displays: ${displays.length > 0 ? displays.map((d)=>d.name).join(', ') : 'Unknown'}${headlessInfo}
 `;
             debugDevice('Computer device connected', this.description);
+            await this.healthCheck();
         } catch (error) {
+            if (this.xvfbInstance) {
+                this.xvfbInstance.stop();
+                this.xvfbInstance = void 0;
+            }
             debugDevice(`Failed to connect: ${error}`);
             throw new Error(`Unable to connect to computer device: ${error}`);
         }
-        await this.healthCheck();
     }
     async healthCheck() {
         console.log('[HealthCheck] Starting health check...');
         console.log('[HealthCheck] Taking screenshot...');
-        try {
-            const base64 = await this.screenshotBase64();
-            console.log(`[HealthCheck] Screenshot succeeded (length=${base64.length})`);
-        } catch (error) {
-            console.error(`[HealthCheck] Screenshot failed: ${error}`);
-            process.exit(1);
-        }
+        const screenshotTimeout = 15000;
+        let timeoutId;
+        const timeoutPromise = new Promise((_, reject)=>{
+            timeoutId = setTimeout(()=>reject(new Error('Screenshot timed out')), screenshotTimeout);
+        });
+        const base64 = await Promise.race([
+            this.screenshotBase64().finally(()=>clearTimeout(timeoutId)),
+            timeoutPromise
+        ]);
+        console.log(`[HealthCheck] Screenshot succeeded (length=${base64.length})`);
         console.log('[HealthCheck] Moving mouse...');
-        try {
-            external_node_assert_default()(libnut, 'libnut not initialized');
-            const startPos = libnut.getMousePos();
-            console.log(`[HealthCheck] Current mouse position: (${startPos.x}, ${startPos.y})`);
-            const offsetX = Math.floor(40 * Math.random()) + 10;
-            const offsetY = Math.floor(40 * Math.random()) + 10;
-            const targetX = startPos.x + offsetX;
-            const targetY = startPos.y + offsetY;
-            console.log(`[HealthCheck] Moving mouse to (${targetX}, ${targetY})...`);
-            libnut.moveMouse(targetX, targetY);
-            await (0, utils_namespaceObject.sleep)(50);
-            const movedPos = libnut.getMousePos();
-            console.log(`[HealthCheck] Mouse position after move: (${movedPos.x}, ${movedPos.y})`);
-            libnut.moveMouse(startPos.x, startPos.y);
-            console.log(`[HealthCheck] Mouse restored to (${startPos.x}, ${startPos.y})`);
-        } catch (error) {
-            console.error(`[HealthCheck] Mouse move failed: ${error}`);
-            process.exit(1);
-        }
+        external_node_assert_default()(libnut, 'libnut not initialized');
+        const startPos = libnut.getMousePos();
+        console.log(`[HealthCheck] Current mouse position: (${startPos.x}, ${startPos.y})`);
+        const offsetX = Math.floor(40 * Math.random()) + 10;
+        const offsetY = Math.floor(40 * Math.random()) + 10;
+        const targetX = startPos.x + offsetX;
+        const targetY = startPos.y + offsetY;
+        console.log(`[HealthCheck] Moving mouse to (${targetX}, ${targetY})...`);
+        libnut.moveMouse(targetX, targetY);
+        await (0, utils_namespaceObject.sleep)(50);
+        const movedPos = libnut.getMousePos();
+        console.log(`[HealthCheck] Mouse position after move: (${movedPos.x}, ${movedPos.y})`);
+        libnut.moveMouse(startPos.x, startPos.y);
+        console.log(`[HealthCheck] Mouse restored to (${startPos.x}, ${startPos.y})`);
         console.log('[HealthCheck] Health check passed');
     }
     async screenshotBase64() {
@@ -299,8 +388,7 @@ Available Displays: ${displays.length > 0 ? displays.map((d)=>d.name).join(', ')
             const screenSize = libnut.getScreenSize();
             return {
                 width: screenSize.width,
-                height: screenSize.height,
-                dpr: 1
+                height: screenSize.height
             };
         } catch (error) {
             debugDevice(`Failed to get screen size: ${error}`);
@@ -565,6 +653,16 @@ Available Displays: ${displays.length > 0 ? displays.map((d)=>d.name).join(', ')
     }
     async destroy() {
         if (this.destroyed) return;
+        if (this.xvfbInstance) {
+            this.xvfbInstance.stop();
+            this.xvfbInstance = void 0;
+        }
+        if (this.xvfbCleanup) {
+            process.removeListener('exit', this.xvfbCleanup);
+            process.removeListener('SIGINT', this.xvfbCleanup);
+            process.removeListener('SIGTERM', this.xvfbCleanup);
+            this.xvfbCleanup = void 0;
+        }
         this.destroyed = true;
         debugDevice('Computer device destroyed');
     }
@@ -577,6 +675,8 @@ Available Displays: ${displays.length > 0 ? displays.map((d)=>d.name).join(', ')
         _define_property(this, "displayId", void 0);
         _define_property(this, "description", void 0);
         _define_property(this, "destroyed", false);
+        _define_property(this, "xvfbInstance", void 0);
+        _define_property(this, "xvfbCleanup", void 0);
         _define_property(this, "useAppleScript", void 0);
         _define_property(this, "uri", void 0);
         this.options = options;
@@ -605,7 +705,7 @@ class ComputerMidsceneTools extends mcp_namespaceObject.BaseMidsceneTools {
     createTemporaryDevice() {
         return new ComputerDevice({});
     }
-    async ensureAgent(displayId) {
+    async ensureAgent(displayId, headless) {
         if (this.agent && displayId) {
             try {
                 await this.agent.destroy?.();
@@ -616,10 +716,15 @@ class ComputerMidsceneTools extends mcp_namespaceObject.BaseMidsceneTools {
         }
         if (this.agent) return this.agent;
         debug('Creating Computer agent with displayId:', displayId || 'primary');
-        const opts = displayId ? {
-            displayId
-        } : void 0;
-        const agent = await agentFromComputer(opts);
+        const opts = {
+            ...displayId ? {
+                displayId
+            } : {},
+            ...void 0 !== headless ? {
+                headless
+            } : {}
+        };
+        const agent = await agentFromComputer(Object.keys(opts).length > 0 ? opts : void 0);
         this.agent = agent;
         return agent;
     }
@@ -629,10 +734,11 @@ class ComputerMidsceneTools extends mcp_namespaceObject.BaseMidsceneTools {
                 name: 'computer_connect',
                 description: 'Connect to computer desktop. Provide displayId to connect to a specific display (use computer_list_displays to get available IDs). If not provided, uses the primary display.',
                 schema: {
-                    displayId: core_namespaceObject.z.string().optional().describe('Display ID (from computer_list_displays)')
+                    displayId: core_namespaceObject.z.string().optional().describe('Display ID (from computer_list_displays)'),
+                    headless: core_namespaceObject.z.boolean().optional().describe('Start virtual display via Xvfb (Linux only)')
                 },
-                handler: async ({ displayId })=>{
-                    const agent = await this.ensureAgent(displayId);
+                handler: async ({ displayId, headless })=>{
+                    const agent = await this.ensureAgent(displayId, headless);
                     const screenshot = await agent.interface.screenshotBase64();
                     return {
                         content: [

package/dist/types/index.d.ts

@@ -30,6 +30,11 @@ export declare function checkAccessibilityPermission(promptIfNeeded?: boolean):
  */
 export declare function checkComputerEnvironment(): Promise<EnvironmentCheck>;
 
+/**
+ * Check if Xvfb is installed on the system
+ */
+export declare function checkXvfbInstalled(): boolean;
+
 export declare class ComputerAgent extends Agent<ComputerDevice> {
 }
 
@@ -41,6 +46,8 @@ export declare class ComputerDevice implements AbstractInterface {
     private displayId?;
     private description?;
     private destroyed;
+    private xvfbInstance?;
+    private xvfbCleanup?;
     /**
      * On macOS, use AppleScript for keyboard operations by default
      * to avoid focus issues with system overlays (e.g. Spotlight).
@@ -86,6 +93,17 @@ export declare interface ComputerDeviceOpt {
      * - 'libnut': Use libnut's keyTap (faster but may not work with some TUI apps)
      */
     keyboardDriver?: 'applescript' | 'libnut';
+    /**
+     * Headless mode via Xvfb (Linux only).
+     * - true: start Xvfb virtual display
+     * - false/undefined: do not start Xvfb
+     * Can also be set via MIDSCENE_COMPUTER_HEADLESS_LINUX=true environment variable.
+     */
+    headless?: boolean;
+    /**
+     * Resolution for Xvfb virtual display (default '1920x1080x24')
+     */
+    xvfbResolution?: string;
 }
 
 export declare interface DisplayInfo {
@@ -106,6 +124,13 @@ declare interface EnvironmentCheck {
  */
 export declare function getConnectedDisplays(): Promise<DisplayInfo[]>;
 
+/**
+ * Determine whether Xvfb is needed.
+ * Only starts when explicitly requested via `headless: true`.
+ * Non-Linux platforms always return false.
+ */
+export declare function needsXvfb(explicitOpt?: boolean): boolean;
+
 export { overrideAIConfig }
 
 export { }

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

@@ -19,6 +19,8 @@ declare class ComputerDevice implements AbstractInterface {
     private displayId?;
     private description?;
     private destroyed;
+    private xvfbInstance?;
+    private xvfbCleanup?;
     /**
      * On macOS, use AppleScript for keyboard operations by default
      * to avoid focus issues with system overlays (e.g. Spotlight).
@@ -64,6 +66,17 @@ declare interface ComputerDeviceOpt {
      * - 'libnut': Use libnut's keyTap (faster but may not work with some TUI apps)
      */
     keyboardDriver?: 'applescript' | 'libnut';
+    /**
+     * Headless mode via Xvfb (Linux only).
+     * - true: start Xvfb virtual display
+     * - false/undefined: do not start Xvfb
+     * Can also be set via MIDSCENE_COMPUTER_HEADLESS_LINUX=true environment variable.
+     */
+    headless?: boolean;
+    /**
+     * Resolution for Xvfb virtual display (default '1920x1080x24')
+     */
+    xvfbResolution?: string;
 }
 
 /**
@@ -81,7 +94,7 @@ export declare class ComputerMCPServer extends BaseMCPServer {
  */
 declare class ComputerMidsceneTools extends BaseMidsceneTools<ComputerAgent> {
     protected createTemporaryDevice(): ComputerDevice;
-    protected ensureAgent(displayId?: string): Promise<ComputerAgent>;
+    protected ensureAgent(displayId?: string, headless?: boolean): Promise<ComputerAgent>;
     /**
      * Provide Computer-specific platform tools
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@midscene/computer",
-  "version": "1.4.6",
+  "version": "1.4.7",
   "description": "Midscene.js Computer Desktop Automation",
   "license": "MIT",
   "repository": {
@@ -36,8 +36,8 @@
     "@computer-use/libnut": "^4.2.0",
     "clipboardy": "^4.0.0",
     "screenshot-desktop": "^1.15.3",
-    "@midscene/core": "1.4.6",
-    "@midscene/shared": "1.4.6"
+    "@midscene/shared": "1.4.7",
+    "@midscene/core": "1.4.7"
   },
   "optionalDependencies": {
     "node-mac-permissions": "2.5.0"