@midscene/computer 1.8.0 → 1.8.1

package/dist/es/cli.mjs

@@ -1,20 +1,20 @@
-import { createReportCliCommands, getMidsceneLocationSchema, z } from "@midscene/core";
+import { createReportCliCommands, z } from "@midscene/core";
 import { reportCLIError, runToolsCLI } from "@midscene/shared/cli";
 import { getDebug } from "@midscene/shared/logger";
 import { BaseMidsceneTools } from "@midscene/shared/mcp/base-tools";
 import { Agent } from "@midscene/core/agent";
 import node_assert from "node:assert";
-import { execFileSync, execSync, spawn as external_node_child_process_spawn, spawnSync } from "node:child_process";
-import { existsSync as external_node_fs_existsSync } from "node:fs";
+import { execFileSync, execSync, spawn, spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
-import { dirname as external_node_path_dirname, resolve as external_node_path_resolve } from "node:path";
-import { fileURLToPath as external_node_url_fileURLToPath } from "node:url";
-import { actionHoverParamSchema, defineAction as device_defineAction, defineActionClearInput as device_defineActionClearInput, defineActionDoubleClick as device_defineActionDoubleClick, defineActionDragAndDrop as device_defineActionDragAndDrop, defineActionKeyboardPress as device_defineActionKeyboardPress, defineActionRightClick as device_defineActionRightClick, defineActionScroll as device_defineActionScroll, defineActionTap as device_defineActionTap } from "@midscene/core/device";
-import { sleep as utils_sleep } from "@midscene/core/utils";
+import { dirname, resolve as external_node_path_resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { defineAction, defineActionsFromInputPrimitives } from "@midscene/core/device";
+import { sleep } from "@midscene/core/utils";
 import { createImgBase64ByFormat } from "@midscene/shared/img";
 import screenshot_desktop from "screenshot-desktop";
-import "node:events";
-import "node:readline";
+import { once } from "node:events";
+import { createInterface } from "node:readline";
 const debugXvfb = getDebug('computer:xvfb');
 function checkXvfbInstalled() {
     try {
@@ -27,7 +27,7 @@ function checkXvfbInstalled() {
     }
 }
 function findAvailableDisplay(startFrom = 99) {
-    for(let n = startFrom; n < startFrom + 100; n++)if (!external_node_fs_existsSync(`/tmp/.X${n}-lock`)) return n;
+    for(let n = startFrom; n < startFrom + 100; n++)if (!existsSync(`/tmp/.X${n}-lock`)) return n;
     throw new Error(`No available display number found (checked ${startFrom} to ${startFrom + 99})`);
 }
 function startXvfb(options) {
@@ -36,7 +36,7 @@ function startXvfb(options) {
     const display = `:${displayNum}`;
     return new Promise((resolve, reject)=>{
         debugXvfb(`Starting Xvfb on display ${display} with resolution ${resolution}`);
-        const xvfbProcess = external_node_child_process_spawn('Xvfb', [
+        const xvfbProcess = spawn('Xvfb', [
             display,
             '-screen',
             '0',
@@ -92,15 +92,6 @@ function _define_property(obj, key, value) {
     else obj[key] = value;
     return obj;
 }
-const computerInputParamSchema = z.object({
-    value: z.string().describe('The text to input'),
-    mode: z["enum"]([
-        'replace',
-        'clear',
-        'append'
-    ]).default('replace').optional().describe('Input mode: replace, clear, or append'),
-    locate: getMidsceneLocationSchema().describe('The input field to be filled').optional()
-});
 const SMOOTH_MOVE_STEPS_TAP = 8;
 const SMOOTH_MOVE_STEPS_MOUSE_MOVE = 10;
 const SMOOTH_MOVE_DELAY_TAP = 8;
@@ -239,13 +230,13 @@ function getPhasedScrollBinary() {
     const require = createRequire(import.meta.url);
     let pkgRoot = null;
     try {
-        pkgRoot = external_node_path_dirname(require.resolve('@midscene/computer/package.json'));
+        pkgRoot = dirname(require.resolve('@midscene/computer/package.json'));
     } catch  {
-        const hereDir = external_node_path_dirname(external_node_url_fileURLToPath(import.meta.url));
+        const hereDir = dirname(fileURLToPath(import.meta.url));
         for (const candidate of [
             external_node_path_resolve(hereDir, '..'),
             external_node_path_resolve(hereDir, '../..')
-        ])if (external_node_fs_existsSync(external_node_path_resolve(candidate, 'package.json'))) {
+        ])if (existsSync(external_node_path_resolve(candidate, 'package.json'))) {
             pkgRoot = candidate;
             break;
         }
@@ -256,7 +247,7 @@ function getPhasedScrollBinary() {
         return null;
     }
     const binPath = external_node_path_resolve(pkgRoot, 'bin/darwin/phased-scroll');
-    if (!external_node_fs_existsSync(binPath)) {
+    if (!existsSync(binPath)) {
         debugDevice('phased-scroll binary not found at', binPath);
         phasedScrollBinaryPath = null;
         return null;
@@ -299,7 +290,7 @@ async function smoothMoveMouse(targetX, targetY, steps, stepDelay) {
         const stepX = Math.round(currentPos.x + (targetX - currentPos.x) * i / steps);
         const stepY = Math.round(currentPos.y + (targetY - currentPos.y) * i / steps);
         libnut.moveMouse(stepX, stepY);
-        await utils_sleep(stepDelay);
+        await sleep(stepDelay);
     }
 }
 const KEY_NAME_MAP = {
@@ -411,7 +402,7 @@ Available Displays: ${displays.length > 0 ? displays.map((d)=>d.name).join(', ')
     }
     async healthCheck() {
         console.log('[HealthCheck] Starting health check...');
-        console.log("[HealthCheck] @midscene/computer v1.8.0");
+        console.log("[HealthCheck] @midscene/computer v1.8.1");
         console.log('[HealthCheck] Taking screenshot...');
         const screenshotTimeout = 15000;
         let timeoutId;
@@ -433,7 +424,7 @@ Available Displays: ${displays.length > 0 ? displays.map((d)=>d.name).join(', ')
         const targetY = startPos.y + offsetY;
         console.log(`[HealthCheck] Moving mouse to (${targetX}, ${targetY})...`);
         libnut.moveMouse(targetX, targetY);
-        await utils_sleep(50);
+        await sleep(50);
         const movedPos = libnut.getMousePos();
         console.log(`[HealthCheck] Mouse position after move: (${movedPos.x}, ${movedPos.y})`);
         const deltaX = Math.abs(movedPos.x - targetX);
@@ -477,21 +468,38 @@ Available Displays: ${displays.length > 0 ? displays.map((d)=>d.name).join(', ')
         debugDevice('Taking screenshot', {
             displayId: this.displayId
         });
-        try {
-            const options = {
-                format: 'png'
-            };
-            if (void 0 !== this.displayId) if ('darwin' === process.platform) {
-                const screenIndex = Number(this.displayId);
-                if (!Number.isNaN(screenIndex)) options.screen = screenIndex;
-            } else options.screen = this.displayId;
-            debugDevice('Screenshot options', options);
+        const options = {
+            format: 'png'
+        };
+        if (void 0 !== this.displayId) if ('darwin' === process.platform) {
+            const screenIndex = Number(this.displayId);
+            if (!Number.isNaN(screenIndex)) options.screen = screenIndex;
+        } else options.screen = this.displayId;
+        debugDevice('Screenshot options', options);
+        const MAX_ATTEMPTS = 3;
+        const RETRY_DELAY_MS = 300;
+        let lastRawMessage = '';
+        for(let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++)try {
             const buffer = await screenshot_desktop(options);
+            if (attempt > 1) debugDevice(`Screenshot succeeded on attempt ${attempt}`);
             return createImgBase64ByFormat('png', buffer.toString('base64'));
         } catch (error) {
-            debugDevice(`Screenshot failed: ${error}`);
-            throw new Error(`Failed to take screenshot: ${error}`);
+            lastRawMessage = error instanceof Error ? error.message : String(error);
+            const isMacTransient = 'darwin' === process.platform && /could not create image from display/i.test(lastRawMessage);
+            const willRetry = isMacTransient && attempt < MAX_ATTEMPTS;
+            debugDevice(`Screenshot attempt ${attempt} failed: ${lastRawMessage}${willRetry ? ' — retrying' : ''}`);
+            if (!willRetry) break;
+            await sleep(RETRY_DELAY_MS);
         }
+        if ('darwin' === process.platform && /could not create image from display/i.test(lastRawMessage)) throw new Error(`Failed to take screenshot on macOS: the host process is missing Screen Recording permission, or the target display is locked/sleeping.
+
+Please follow these steps:
+1. Open System Settings > Privacy & Security > Screen Recording
+2. Enable the application running this script (e.g., Terminal, iTerm2, VS Code, WebStorm, or Midscene Studio)
+3. Fully quit and relaunch that application after granting permission — macOS only re-reads this permission on process launch.
+
+Original error: ${lastRawMessage}`);
+        throw new Error(`Failed to take screenshot: ${lastRawMessage}`);
     }
     async size() {
         node_assert(libnut, 'libnut not initialized');
@@ -516,7 +524,7 @@ Available Displays: ${displays.length > 0 ? displays.map((d)=>d.name).join(', ')
         const oldClipboard = await clipboardy.default.read().catch(()=>'');
         try {
             await clipboardy.default.write(text);
-            await utils_sleep(50);
+            await sleep(50);
             if (this.useAppleScript) sendKeyViaAppleScript('v', [
                 'command'
             ]);
@@ -526,7 +534,7 @@ Available Displays: ${displays.length > 0 ? displays.map((d)=>d.name).join(', ')
                     modifier
                 ]);
             }
-            await utils_sleep(100);
+            await sleep(100);
         } finally{
             if (oldClipboard) await clipboardy.default.write(oldClipboard).catch(()=>{
                 debugDevice('Failed to restore clipboard content');
@@ -537,228 +545,111 @@ Available Displays: ${displays.length > 0 ? displays.map((d)=>d.name).join(', ')
         node_assert(libnut, 'libnut not initialized');
         await this.typeViaClipboard(text);
     }
+    async selectAllAndDelete() {
+        node_assert(libnut, 'libnut not initialized');
+        if (this.useAppleScript) {
+            sendKeyViaAppleScript('a', [
+                'command'
+            ]);
+            await sleep(50);
+            sendKeyViaAppleScript('backspace', []);
+            return;
+        }
+        const modifier = 'darwin' === process.platform ? 'command' : 'control';
+        libnut.keyTap('a', [
+            modifier
+        ]);
+        await sleep(50);
+        libnut.keyTap('backspace');
+    }
+    async pressKeyboardShortcut(keyName) {
+        node_assert(libnut, 'libnut not initialized');
+        const keys = keyName.split('+');
+        const modifiers = keys.slice(0, -1).map(normalizeKeyName);
+        const key = normalizePrimaryKey(keys[keys.length - 1]);
+        debugDevice('KeyboardPress', {
+            original: keyName,
+            key,
+            modifiers,
+            driver: this.useAppleScript ? "applescript" : 'libnut'
+        });
+        if (this.useAppleScript) sendKeyViaAppleScript(key, modifiers);
+        else if (modifiers.length > 0) libnut.keyTap(key, modifiers);
+        else libnut.keyTap(key);
+    }
+    async performScroll(param) {
+        node_assert(libnut, 'libnut not initialized');
+        if (param.locate) {
+            const element = param.locate;
+            const [x, y] = element.center;
+            libnut.moveMouse(Math.round(x), Math.round(y));
+        }
+        const scrollType = param?.scrollType;
+        const edgeSpec = scrollType && scrollType in EDGE_SCROLL_SPEC ? EDGE_SCROLL_SPEC[scrollType] : null;
+        if (edgeSpec) {
+            if (runPhasedScroll(edgeSpec.direction, EDGE_SCROLL_TOTAL_PX, EDGE_SCROLL_STEPS)) return void await sleep(SCROLL_COMPLETE_DELAY);
+            if (this.useAppleScript) {
+                sendKeyViaAppleScript(edgeSpec.key);
+                await sleep(SCROLL_COMPLETE_DELAY);
+                return;
+            }
+            const [dx, dy] = edgeSpec.libnut;
+            for(let i = 0; i < SCROLL_REPEAT_COUNT; i++){
+                libnut.scrollMouse(dx, dy);
+                await sleep(SCROLL_STEP_DELAY);
+            }
+            return;
+        }
+        if ('singleAction' === scrollType || !scrollType) {
+            const distance = param?.distance || 500;
+            const direction = param?.direction || 'down';
+            const isKnownDirection = 'up' === direction || 'down' === direction || 'left' === direction || 'right' === direction;
+            if (isKnownDirection) {
+                const steps = Math.max(PHASED_MIN_STEPS, Math.round(distance / PHASED_PIXELS_PER_STEP));
+                if (runPhasedScroll(direction, distance, steps)) return void await sleep(SCROLL_COMPLETE_DELAY);
+            }
+            if (this.useAppleScript && ('up' === direction || 'down' === direction)) {
+                const pages = Math.max(1, Math.round(distance / APPROX_VIEWPORT_HEIGHT_PX));
+                const key = 'up' === direction ? 'pageup' : 'pagedown';
+                for(let i = 0; i < pages; i++){
+                    sendKeyViaAppleScript(key);
+                    await sleep(SCROLL_STEP_DELAY);
+                }
+                await sleep(SCROLL_COMPLETE_DELAY);
+                return;
+            }
+            const ticks = Math.ceil(distance / 100);
+            const directionMap = {
+                up: [
+                    0,
+                    ticks
+                ],
+                down: [
+                    0,
+                    -ticks
+                ],
+                left: [
+                    -ticks,
+                    0
+                ],
+                right: [
+                    ticks,
+                    0
+                ]
+            };
+            const [dx, dy] = directionMap[direction] || [
+                0,
+                -ticks
+            ];
+            libnut.scrollMouse(dx, dy);
+            await sleep(SCROLL_COMPLETE_DELAY);
+            return;
+        }
+        throw new Error(`Unknown scroll type: ${scrollType}, param: ${JSON.stringify(param)}`);
+    }
     actionSpace() {
         const defaultActions = [
-            device_defineActionTap(async (param)=>{
-                node_assert(libnut, 'libnut not initialized');
-                const element = param.locate;
-                node_assert(element, 'Element not found, cannot tap');
-                const [x, y] = element.center;
-                const targetX = Math.round(x);
-                const targetY = Math.round(y);
-                await smoothMoveMouse(targetX, targetY, SMOOTH_MOVE_STEPS_TAP, SMOOTH_MOVE_DELAY_TAP);
-                libnut.mouseToggle('down', 'left');
-                await utils_sleep(CLICK_HOLD_DURATION);
-                libnut.mouseToggle('up', 'left');
-            }),
-            device_defineActionDoubleClick(async (param)=>{
-                node_assert(libnut, 'libnut not initialized');
-                const element = param.locate;
-                node_assert(element, 'Element not found, cannot double click');
-                const [x, y] = element.center;
-                libnut.moveMouse(Math.round(x), Math.round(y));
-                libnut.mouseClick('left', true);
-            }),
-            device_defineActionRightClick(async (param)=>{
-                node_assert(libnut, 'libnut not initialized');
-                const element = param.locate;
-                node_assert(element, 'Element not found, cannot right click');
-                const [x, y] = element.center;
-                libnut.moveMouse(Math.round(x), Math.round(y));
-                libnut.mouseClick('right');
-            }),
-            device_defineAction({
-                name: 'MouseMove',
-                description: 'Move the mouse to the element',
-                interfaceAlias: 'aiHover',
-                paramSchema: actionHoverParamSchema,
-                sample: {
-                    locate: {
-                        prompt: 'the navigation menu item "Products"'
-                    }
-                },
-                call: async (param)=>{
-                    node_assert(libnut, 'libnut not initialized');
-                    const element = param.locate;
-                    node_assert(element, 'Element not found, cannot move mouse');
-                    const [x, y] = element.center;
-                    const targetX = Math.round(x);
-                    const targetY = Math.round(y);
-                    await smoothMoveMouse(targetX, targetY, SMOOTH_MOVE_STEPS_MOUSE_MOVE, SMOOTH_MOVE_DELAY_MOUSE_MOVE);
-                    await utils_sleep(MOUSE_MOVE_EFFECT_WAIT);
-                }
-            }),
-            device_defineAction({
-                name: 'Input',
-                description: 'Input text into the input field',
-                interfaceAlias: 'aiInput',
-                paramSchema: computerInputParamSchema,
-                sample: {
-                    value: 'test@example.com',
-                    locate: {
-                        prompt: 'the email input field'
-                    }
-                },
-                call: async (param)=>{
-                    node_assert(libnut, 'libnut not initialized');
-                    const element = param.locate;
-                    if (element) {
-                        const [x, y] = element.center;
-                        libnut.moveMouse(Math.round(x), Math.round(y));
-                        libnut.mouseClick('left');
-                        await utils_sleep(INPUT_FOCUS_DELAY);
-                        if ('append' !== param.mode) {
-                            if (this.useAppleScript) {
-                                sendKeyViaAppleScript('a', [
-                                    'command'
-                                ]);
-                                await utils_sleep(50);
-                                sendKeyViaAppleScript('backspace', []);
-                            } else {
-                                const modifier = 'darwin' === process.platform ? 'command' : 'control';
-                                libnut.keyTap('a', [
-                                    modifier
-                                ]);
-                                await utils_sleep(50);
-                                libnut.keyTap('backspace');
-                            }
-                            await utils_sleep(INPUT_CLEAR_DELAY);
-                        }
-                    }
-                    if ('clear' === param.mode) return;
-                    if (!param.value) return;
-                    await this.smartTypeString(param.value);
-                }
-            }),
-            device_defineActionScroll(async (param)=>{
-                node_assert(libnut, 'libnut not initialized');
-                if (param.locate) {
-                    const element = param.locate;
-                    const [x, y] = element.center;
-                    libnut.moveMouse(Math.round(x), Math.round(y));
-                }
-                const scrollType = param?.scrollType;
-                const edgeSpec = scrollType && scrollType in EDGE_SCROLL_SPEC ? EDGE_SCROLL_SPEC[scrollType] : null;
-                if (edgeSpec) {
-                    if (runPhasedScroll(edgeSpec.direction, EDGE_SCROLL_TOTAL_PX, EDGE_SCROLL_STEPS)) return void await utils_sleep(SCROLL_COMPLETE_DELAY);
-                    if (this.useAppleScript) {
-                        sendKeyViaAppleScript(edgeSpec.key);
-                        await utils_sleep(SCROLL_COMPLETE_DELAY);
-                        return;
-                    }
-                    const [dx, dy] = edgeSpec.libnut;
-                    for(let i = 0; i < SCROLL_REPEAT_COUNT; i++){
-                        libnut.scrollMouse(dx, dy);
-                        await utils_sleep(SCROLL_STEP_DELAY);
-                    }
-                    return;
-                }
-                if ('singleAction' === scrollType || !scrollType) {
-                    const distance = param?.distance || 500;
-                    const direction = param?.direction || 'down';
-                    const isKnownDirection = 'up' === direction || 'down' === direction || 'left' === direction || 'right' === direction;
-                    if (isKnownDirection) {
-                        const steps = Math.max(PHASED_MIN_STEPS, Math.round(distance / PHASED_PIXELS_PER_STEP));
-                        if (runPhasedScroll(direction, distance, steps)) return void await utils_sleep(SCROLL_COMPLETE_DELAY);
-                    }
-                    if (this.useAppleScript && ('up' === direction || 'down' === direction)) {
-                        const pages = Math.max(1, Math.round(distance / APPROX_VIEWPORT_HEIGHT_PX));
-                        const key = 'up' === direction ? 'pageup' : 'pagedown';
-                        for(let i = 0; i < pages; i++){
-                            sendKeyViaAppleScript(key);
-                            await utils_sleep(SCROLL_STEP_DELAY);
-                        }
-                        await utils_sleep(SCROLL_COMPLETE_DELAY);
-                        return;
-                    }
-                    const ticks = Math.ceil(distance / 100);
-                    const directionMap = {
-                        up: [
-                            0,
-                            ticks
-                        ],
-                        down: [
-                            0,
-                            -ticks
-                        ],
-                        left: [
-                            -ticks,
-                            0
-                        ],
-                        right: [
-                            ticks,
-                            0
-                        ]
-                    };
-                    const [dx, dy] = directionMap[direction] || [
-                        0,
-                        -ticks
-                    ];
-                    libnut.scrollMouse(dx, dy);
-                    await utils_sleep(SCROLL_COMPLETE_DELAY);
-                    return;
-                }
-                throw new Error(`Unknown scroll type: ${scrollType}, param: ${JSON.stringify(param)}`);
-            }),
-            device_defineActionKeyboardPress(async (param)=>{
-                node_assert(libnut, 'libnut not initialized');
-                if (param.locate) {
-                    const [x, y] = param.locate.center;
-                    libnut.moveMouse(Math.round(x), Math.round(y));
-                    libnut.mouseClick('left');
-                    await utils_sleep(50);
-                }
-                const keys = param.keyName.split('+');
-                const modifiers = keys.slice(0, -1).map(normalizeKeyName);
-                const key = normalizePrimaryKey(keys[keys.length - 1]);
-                debugDevice('KeyboardPress', {
-                    original: param.keyName,
-                    key,
-                    modifiers,
-                    driver: this.useAppleScript ? "applescript" : 'libnut'
-                });
-                if (this.useAppleScript) sendKeyViaAppleScript(key, modifiers);
-                else if (modifiers.length > 0) libnut.keyTap(key, modifiers);
-                else libnut.keyTap(key);
-            }),
-            device_defineActionDragAndDrop(async (param)=>{
-                node_assert(libnut, 'libnut not initialized');
-                const from = param.from;
-                const to = param.to;
-                node_assert(from, 'missing "from" param for drag and drop');
-                node_assert(to, 'missing "to" param for drag and drop');
-                const [fromX, fromY] = from.center;
-                const [toX, toY] = to.center;
-                libnut.moveMouse(Math.round(fromX), Math.round(fromY));
-                libnut.mouseToggle('down', 'left');
-                await utils_sleep(100);
-                libnut.moveMouse(Math.round(toX), Math.round(toY));
-                await utils_sleep(100);
-                libnut.mouseToggle('up', 'left');
-            }),
-            device_defineActionClearInput(async (param)=>{
-                node_assert(libnut, 'libnut not initialized');
-                const element = param.locate;
-                node_assert(element, 'Element not found, cannot clear input');
-                const [x, y] = element.center;
-                libnut.moveMouse(Math.round(x), Math.round(y));
-                libnut.mouseClick('left');
-                await utils_sleep(100);
-                if (this.useAppleScript) {
-                    sendKeyViaAppleScript('a', [
-                        'command'
-                    ]);
-                    await utils_sleep(50);
-                    sendKeyViaAppleScript('backspace', []);
-                } else {
-                    const modifier = 'darwin' === process.platform ? 'command' : 'control';
-                    libnut.keyTap('a', [
-                        modifier
-                    ]);
-                    libnut.keyTap('backspace');
-                }
-                await utils_sleep(50);
-            })
+            ...defineActionsFromInputPrimitives(this.inputPrimitives)
         ];
         const platformActions = Object.values(createPlatformActions());
         const customActions = this.options?.customActions || [];
@@ -796,6 +687,88 @@ Available Displays: ${displays.length > 0 ? displays.map((d)=>d.name).join(', ')
         _define_property(this, "xvfbCleanup", void 0);
         _define_property(this, "useAppleScript", void 0);
         _define_property(this, "uri", void 0);
+        _define_property(this, "inputPrimitives", {
+            pointer: {
+                tap: async ({ x, y })=>{
+                    node_assert(libnut, 'libnut not initialized');
+                    const targetX = Math.round(x);
+                    const targetY = Math.round(y);
+                    await smoothMoveMouse(targetX, targetY, SMOOTH_MOVE_STEPS_TAP, SMOOTH_MOVE_DELAY_TAP);
+                    libnut.mouseToggle('down', 'left');
+                    await sleep(CLICK_HOLD_DURATION);
+                    libnut.mouseToggle('up', 'left');
+                },
+                doubleClick: async ({ x, y })=>{
+                    node_assert(libnut, 'libnut not initialized');
+                    libnut.moveMouse(Math.round(x), Math.round(y));
+                    libnut.mouseClick('left', true);
+                },
+                rightClick: async ({ x, y })=>{
+                    node_assert(libnut, 'libnut not initialized');
+                    libnut.moveMouse(Math.round(x), Math.round(y));
+                    libnut.mouseClick('right');
+                },
+                hover: async ({ x, y })=>{
+                    node_assert(libnut, 'libnut not initialized');
+                    await smoothMoveMouse(Math.round(x), Math.round(y), SMOOTH_MOVE_STEPS_MOUSE_MOVE, SMOOTH_MOVE_DELAY_MOUSE_MOVE);
+                    await sleep(MOUSE_MOVE_EFFECT_WAIT);
+                },
+                dragAndDrop: async (from, to)=>{
+                    node_assert(libnut, 'libnut not initialized');
+                    libnut.moveMouse(Math.round(from.x), Math.round(from.y));
+                    libnut.mouseToggle('down', 'left');
+                    await sleep(100);
+                    libnut.moveMouse(Math.round(to.x), Math.round(to.y));
+                    await sleep(100);
+                    libnut.mouseToggle('up', 'left');
+                }
+            },
+            keyboard: {
+                typeText: async (value, opts)=>{
+                    node_assert(libnut, 'libnut not initialized');
+                    const element = opts?.target;
+                    if (element) {
+                        const [x, y] = element.center;
+                        libnut.moveMouse(Math.round(x), Math.round(y));
+                        libnut.mouseClick('left');
+                        await sleep(INPUT_FOCUS_DELAY);
+                        if (opts?.replace !== false) {
+                            await this.selectAllAndDelete();
+                            await sleep(INPUT_CLEAR_DELAY);
+                        }
+                    }
+                    await this.smartTypeString(value);
+                },
+                keyboardPress: async (keyName, opts)=>{
+                    node_assert(libnut, 'libnut not initialized');
+                    const target = opts?.target;
+                    if (target) {
+                        const [x, y] = target.center;
+                        libnut.moveMouse(Math.round(x), Math.round(y));
+                        libnut.mouseClick('left');
+                        await sleep(50);
+                    }
+                    await this.pressKeyboardShortcut(keyName);
+                },
+                clearInput: async (target)=>{
+                    node_assert(libnut, 'libnut not initialized');
+                    if (target) {
+                        const element = target;
+                        const [x, y] = element.center;
+                        libnut.moveMouse(Math.round(x), Math.round(y));
+                        libnut.mouseClick('left');
+                        await sleep(100);
+                    }
+                    await this.selectAllAndDelete();
+                    await sleep(50);
+                }
+            },
+            scroll: {
+                scroll: async (param)=>{
+                    await this.performScroll(param);
+                }
+            }
+        });
         this.options = options;
         this.displayId = options?.displayId;
         this.useAppleScript = 'darwin' === process.platform && options?.keyboardDriver !== 'libnut';
@@ -803,15 +776,584 @@ Available Displays: ${displays.length > 0 ? displays.map((d)=>d.name).join(', ')
 }
 function createPlatformActions() {
     return {
-        ListDisplays: device_defineAction({
+        ListDisplays: defineAction({
             name: 'ListDisplays',
             description: 'List all available displays/monitors',
             call: async ()=>await ComputerDevice.listDisplays()
         })
     };
 }
-getDebug('rdp:backend');
-getDebug('rdp:device');
+const platformBinaryMap = {
+    darwin: {
+        directory: 'darwin',
+        fileName: 'rdp-helper'
+    },
+    linux: {
+        directory: 'linux',
+        fileName: 'rdp-helper'
+    },
+    win32: {
+        directory: 'win32',
+        fileName: 'rdp-helper.exe'
+    }
+};
+function getPlatformBinary(platform) {
+    if (platform in platformBinaryMap) return platformBinaryMap[platform];
+}
+function currentDirname() {
+    if ('undefined' != typeof __dirname) return __dirname;
+    return dirname(fileURLToPath(import.meta.url));
+}
+function getRdpHelperBinaryPath() {
+    const platformBinary = getPlatformBinary(process.platform);
+    if (!platformBinary) throw new Error(`@midscene/computer RDP helper does not support platform ${process.platform}`);
+    const hereDir = currentDirname();
+    const candidateRoots = [
+        external_node_path_resolve(hereDir, '../..'),
+        external_node_path_resolve(hereDir, '../../..')
+    ];
+    for (const root of candidateRoots){
+        const binaryPath = external_node_path_resolve(root, 'bin', platformBinary.directory, platformBinary.fileName);
+        if (existsSync(binaryPath)) return binaryPath;
+    }
+    throw new Error(`RDP helper binary not found for ${process.platform}. Run \`pnpm --filter @midscene/computer run build:native\` first.`);
+}
+function backend_client_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('rdp:backend');
+const HELPER_SHUTDOWN_TIMEOUT_MS = 3000;
+const MAX_STDERR_LINES = 40;
+class HelperProcessRDPBackendClient {
+    async connect(config) {
+        this.fatalHelperError = void 0;
+        await this.ensureHelperStarted();
+        const response = await this.send({
+            type: 'connect',
+            config
+        });
+        if ('connected' !== response.type) throw new Error(`Expected connected response, got ${response.type}`);
+        this.connected = true;
+        this.fatalHelperError = void 0;
+        return response.info;
+    }
+    async disconnect() {
+        const child = this.child;
+        if (!child) return;
+        let disconnectError;
+        if (this.connected && null === child.exitCode) try {
+            const response = await this.send({
+                type: 'disconnect'
+            });
+            this.expectOk(response, 'disconnect');
+        } catch (error) {
+            disconnectError = error instanceof Error ? error : new Error(String(error));
+        }
+        this.connected = false;
+        this.fatalHelperError = void 0;
+        await this.shutdownHelper();
+        if (disconnectError && !/RDP helper exited unexpectedly|RDP helper is not running|RDP helper shut down/u.test(disconnectError.message)) throw disconnectError;
+    }
+    async screenshotBase64() {
+        const response = await this.send({
+            type: 'screenshot'
+        });
+        if ('screenshot' !== response.type) throw new Error(`Expected screenshot response, got ${response.type}`);
+        return response.base64;
+    }
+    async size() {
+        const response = await this.send({
+            type: 'size'
+        });
+        if ('size' !== response.type) throw new Error(`Expected size response, got ${response.type}`);
+        return response.size;
+    }
+    async mouseMove(x, y) {
+        const response = await this.send({
+            type: 'mouseMove',
+            x,
+            y
+        });
+        this.expectOk(response, 'mouseMove');
+    }
+    async mouseButton(button, action) {
+        const response = await this.send({
+            type: 'mouseButton',
+            button,
+            action
+        });
+        this.expectOk(response, 'mouseButton');
+    }
+    async wheel(direction, amount, x, y) {
+        const response = await this.send({
+            type: 'wheel',
+            direction,
+            amount,
+            x,
+            y
+        });
+        this.expectOk(response, 'wheel');
+    }
+    async keyPress(keyName) {
+        const response = await this.send({
+            type: 'keyPress',
+            keyName
+        });
+        this.expectOk(response, 'keyPress');
+    }
+    async typeText(text) {
+        const response = await this.send({
+            type: 'typeText',
+            text
+        });
+        this.expectOk(response, 'typeText');
+    }
+    async clearInput() {
+        const response = await this.send({
+            type: 'clearInput'
+        });
+        this.expectOk(response, 'clearInput');
+    }
+    async ensureHelperStarted() {
+        if (this.child && null === this.child.exitCode) return;
+        const helperPath = this.resolveHelperPath();
+        debug('starting rdp helper', {
+            helperPath
+        });
+        const child = this.spawnFn(helperPath, [], {
+            stdio: [
+                'pipe',
+                'pipe',
+                'pipe'
+            ]
+        });
+        child.stdout.setEncoding('utf8');
+        child.stderr.setEncoding('utf8');
+        this.child = child;
+        this.stderrLines.length = 0;
+        this.stdoutReader = createInterface({
+            input: child.stdout,
+            crlfDelay: 1 / 0
+        });
+        this.stderrReader = createInterface({
+            input: child.stderr,
+            crlfDelay: 1 / 0
+        });
+        this.stdoutReader.on('line', (line)=>{
+            this.handleStdoutLine(line);
+        });
+        this.stderrReader.on('line', (line)=>{
+            this.captureStderrLine(line);
+        });
+        child.on('exit', (code, signal)=>{
+            this.connected = false;
+            const error = this.createHelperError(`RDP helper exited unexpectedly (code=${code}, signal=${signal})`);
+            this.fatalHelperError = error;
+            this.rejectPending(error);
+            this.disposeReaders();
+            this.child = void 0;
+        });
+        child.on('error', (error)=>{
+            this.connected = false;
+            const helperError = this.createHelperError(`Failed to start RDP helper: ${error.message}`);
+            this.fatalHelperError = helperError;
+            this.rejectPending(helperError);
+            this.disposeReaders();
+            this.child = void 0;
+        });
+    }
+    handleStdoutLine(line) {
+        if (!line.trim()) return;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        } catch (error) {
+            const protocolError = this.createHelperError(`RDP helper emitted malformed JSON: ${line}`);
+            this.rejectPending(protocolError);
+            this.shutdownHelper(protocolError);
+            return;
+        }
+        const pending = this.pending.get(parsed.id);
+        if (!pending) return void debug('dropping response for unknown request id', parsed);
+        this.pending.delete(parsed.id);
+        if (parsed.ok) return void pending.resolve(parsed.payload);
+        pending.reject(this.createHelperError(parsed.error.message, parsed.error.code));
+    }
+    captureStderrLine(line) {
+        if (!line.trim()) return;
+        this.stderrLines.push(line);
+        if (this.stderrLines.length > MAX_STDERR_LINES) this.stderrLines.shift();
+    }
+    async send(payload) {
+        if ('connect' !== payload.type && this.fatalHelperError && (!this.child || null !== this.child.exitCode)) throw this.fatalHelperError;
+        await this.ensureHelperStarted();
+        const child = this.child;
+        if (!child || null !== child.exitCode) throw this.createHelperError('RDP helper is not running');
+        const id = `req-${++this.nextRequestId}`;
+        const request = {
+            id,
+            payload
+        };
+        return new Promise((resolve, reject)=>{
+            this.pending.set(id, {
+                resolve,
+                reject
+            });
+            child.stdin.write(`${JSON.stringify(request)}\n`, (error)=>{
+                if (!error) return;
+                this.pending.delete(id);
+                reject(this.createHelperError(`Failed to send ${payload.type} request to RDP helper: ${error.message}`));
+            });
+        });
+    }
+    expectOk(response, actionName) {
+        if ('ok' !== response.type) throw new Error(`Expected ok response for ${actionName}, got ${response.type}`);
+    }
+    rejectPending(error) {
+        for (const { reject } of this.pending.values())reject(error);
+        this.pending.clear();
+    }
+    createHelperError(message, code) {
+        const stderrSummary = this.stderrLines.join('\n').trim();
+        const suffix = stderrSummary ? `\nHelper stderr:\n${stderrSummary}` : '';
+        const error = new Error(`${message}${suffix}`);
+        if (code) error.name = code;
+        return error;
+    }
+    disposeReaders() {
+        this.stdoutReader?.close();
+        this.stderrReader?.close();
+        this.stdoutReader = void 0;
+        this.stderrReader = void 0;
+    }
+    async shutdownHelper(rootError) {
+        const child = this.child;
+        this.child = void 0;
+        this.disposeReaders();
+        if (!child) return;
+        this.rejectPending(rootError || this.createHelperError('RDP helper shut down'));
+        if (null !== child.exitCode) return;
+        child.stdin.end();
+        const exited = Promise.race([
+            once(child, 'exit'),
+            new Promise((resolve)=>{
+                setTimeout(()=>resolve('timeout'), HELPER_SHUTDOWN_TIMEOUT_MS);
+            })
+        ]);
+        const result = await exited;
+        if ('timeout' !== result) return;
+        child.kill('SIGTERM');
+        const terminated = Promise.race([
+            once(child, 'exit'),
+            new Promise((resolve)=>{
+                setTimeout(()=>resolve('timeout'), HELPER_SHUTDOWN_TIMEOUT_MS);
+            })
+        ]);
+        const terminateResult = await terminated;
+        if ('timeout' !== terminateResult) return;
+        child.kill('SIGKILL');
+        await once(child, 'exit');
+    }
+    constructor(options){
+        backend_client_define_property(this, "spawnFn", void 0);
+        backend_client_define_property(this, "resolveHelperPath", void 0);
+        backend_client_define_property(this, "child", void 0);
+        backend_client_define_property(this, "stdoutReader", void 0);
+        backend_client_define_property(this, "stderrReader", void 0);
+        backend_client_define_property(this, "pending", new Map());
+        backend_client_define_property(this, "stderrLines", []);
+        backend_client_define_property(this, "nextRequestId", 0);
+        backend_client_define_property(this, "connected", false);
+        backend_client_define_property(this, "fatalHelperError", void 0);
+        this.spawnFn = options?.spawnFn || spawn;
+        const overridePath = options?.helperPath;
+        this.resolveHelperPath = overridePath ? ()=>overridePath : getRdpHelperBinaryPath;
+    }
+}
+function createDefaultRDPBackendClient() {
+    return new HelperProcessRDPBackendClient();
+}
+function device_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 device_debug = getDebug('rdp:device');
+const device_SMOOTH_MOVE_STEPS_TAP = 8;
+const device_SMOOTH_MOVE_STEPS_MOUSE_MOVE = 10;
+const SMOOTH_MOVE_STEPS_DRAG = 12;
+const device_SMOOTH_MOVE_DELAY_TAP = 8;
+const device_SMOOTH_MOVE_DELAY_MOUSE_MOVE = 10;
+const SMOOTH_MOVE_DELAY_DRAG = 10;
+const device_MOUSE_MOVE_EFFECT_WAIT = 300;
+const device_CLICK_HOLD_DURATION = 50;
+const DRAG_HOLD_DURATION = 100;
+const device_INPUT_FOCUS_DELAY = 300;
+const device_INPUT_CLEAR_DELAY = 150;
+const device_SCROLL_STEP_DELAY = 100;
+const device_SCROLL_COMPLETE_DELAY = 500;
+const DEFAULT_SCROLL_DISTANCE = 480;
+const device_EDGE_SCROLL_STEPS = 10;
+const DEFAULT_SCROLL_STEP_AMOUNT = 120;
+class RDPDevice {
+    describe() {
+        const port = this.options.port || 3389;
+        const username = this.options.username ? ` as ${this.options.username}` : '';
+        const session = this.connectionInfo?.sessionId ? ` [session ${this.connectionInfo.sessionId}]` : '';
+        return `RDP Device ${this.options.host}:${port}${username}${session}`;
+    }
+    async connect() {
+        this.throwIfDestroyed();
+        device_debug('connecting to rdp backend', {
+            host: this.options.host,
+            port: this.options.port,
+            username: this.options.username
+        });
+        this.connectionInfo = await this.backend.connect(this.options);
+        this.cursorPosition = [
+            Math.round(this.connectionInfo.size.width / 2),
+            Math.round(this.connectionInfo.size.height / 2)
+        ];
+    }
+    async screenshotBase64() {
+        this.assertConnected();
+        return this.backend.screenshotBase64();
+    }
+    async size() {
+        this.assertConnected();
+        return this.backend.size();
+    }
+    async destroy() {
+        if (this.destroyed) return;
+        this.destroyed = true;
+        this.connectionInfo = void 0;
+        this.cursorPosition = void 0;
+        await this.backend.disconnect();
+    }
+    actionSpace() {
+        const defaultActions = [
+            ...defineActionsFromInputPrimitives(this.inputPrimitives),
+            defineAction({
+                name: 'ListDisplays',
+                description: 'List all available displays/monitors',
+                call: async ()=>{
+                    this.assertConnected();
+                    const size = await this.size();
+                    return [
+                        {
+                            id: this.connectionInfo?.sessionId || this.options.host,
+                            name: `RDP ${this.connectionInfo?.server || this.options.host} (${size.width}x${size.height})`,
+                            primary: true
+                        }
+                    ];
+                }
+            })
+        ];
+        return [
+            ...defaultActions,
+            ...this.options.customActions || []
+        ];
+    }
+    assertConnected() {
+        this.throwIfDestroyed();
+        if (!this.connectionInfo) throw new Error('RDPDevice is not connected');
+    }
+    throwIfDestroyed() {
+        if (this.destroyed) throw new Error('RDPDevice has been destroyed');
+    }
+    async moveToElement(element, options) {
+        this.assertConnected();
+        const targetX = Math.round(element.center[0]);
+        const targetY = Math.round(element.center[1]);
+        await this.movePointer(targetX, targetY, options);
+    }
+    async clearInput() {
+        if (this.backend.clearInput) return void await this.backend.clearInput();
+        await this.backend.keyPress('Control+A');
+        await this.backend.keyPress('Backspace');
+    }
+    edgeScrollDirection(scrollType) {
+        switch(scrollType){
+            case 'scrollToTop':
+                return 'up';
+            case 'scrollToBottom':
+                return 'down';
+            case 'scrollToLeft':
+                return 'left';
+            case 'scrollToRight':
+                return 'right';
+            case 'singleAction':
+                return 'down';
+            default:
+                throw new Error(`Unsupported scroll type: ${scrollType}`);
+        }
+    }
+    async movePointer(targetX, targetY, options) {
+        this.assertConnected();
+        const start = this.cursorPosition || [
+            targetX,
+            targetY
+        ];
+        const steps = Math.max(1, options?.steps || 1);
+        const stepDelayMs = options?.stepDelayMs || 0;
+        for(let step = 1; step <= steps; step++){
+            const x = Math.round(start[0] + (targetX - start[0]) * step / steps);
+            const y = Math.round(start[1] + (targetY - start[1]) * step / steps);
+            await this.backend.mouseMove(x, y);
+            this.cursorPosition = [
+                x,
+                y
+            ];
+            if (stepDelayMs > 0 && step < steps) await sleep(stepDelayMs);
+        }
+        if (options?.settleDelayMs) await sleep(options.settleDelayMs);
+    }
+    async performWheel(direction, amount, x, y) {
+        let remaining = Math.abs(amount);
+        if (0 === remaining) remaining = DEFAULT_SCROLL_STEP_AMOUNT;
+        while(remaining > 0){
+            const chunk = Math.min(remaining, DEFAULT_SCROLL_STEP_AMOUNT);
+            await this.backend.wheel(direction, chunk, x, y);
+            remaining -= chunk;
+            if (remaining > 0) await sleep(device_SCROLL_STEP_DELAY);
+        }
+    }
+    constructor(options){
+        device_define_property(this, "interfaceType", 'rdp');
+        device_define_property(this, "options", void 0);
+        device_define_property(this, "backend", void 0);
+        device_define_property(this, "connectionInfo", void 0);
+        device_define_property(this, "destroyed", false);
+        device_define_property(this, "cursorPosition", void 0);
+        device_define_property(this, "uri", void 0);
+        device_define_property(this, "inputPrimitives", {
+            pointer: {
+                tap: async ({ x, y })=>{
+                    await this.movePointer(Math.round(x), Math.round(y), {
+                        steps: device_SMOOTH_MOVE_STEPS_TAP,
+                        stepDelayMs: device_SMOOTH_MOVE_DELAY_TAP
+                    });
+                    await this.backend.mouseButton('left', 'down');
+                    await sleep(device_CLICK_HOLD_DURATION);
+                    await this.backend.mouseButton('left', 'up');
+                },
+                doubleClick: async ({ x, y })=>{
+                    await this.movePointer(Math.round(x), Math.round(y), {
+                        steps: device_SMOOTH_MOVE_STEPS_TAP,
+                        stepDelayMs: device_SMOOTH_MOVE_DELAY_TAP
+                    });
+                    await this.backend.mouseButton('left', 'doubleClick');
+                },
+                rightClick: async ({ x, y })=>{
+                    await this.movePointer(Math.round(x), Math.round(y), {
+                        steps: device_SMOOTH_MOVE_STEPS_TAP,
+                        stepDelayMs: device_SMOOTH_MOVE_DELAY_TAP
+                    });
+                    await this.backend.mouseButton('right', 'click');
+                },
+                hover: async ({ x, y })=>{
+                    await this.movePointer(Math.round(x), Math.round(y), {
+                        steps: device_SMOOTH_MOVE_STEPS_MOUSE_MOVE,
+                        stepDelayMs: device_SMOOTH_MOVE_DELAY_MOUSE_MOVE,
+                        settleDelayMs: device_MOUSE_MOVE_EFFECT_WAIT
+                    });
+                },
+                dragAndDrop: async (from, to)=>{
+                    await this.movePointer(Math.round(from.x), Math.round(from.y), {
+                        steps: device_SMOOTH_MOVE_STEPS_TAP,
+                        stepDelayMs: device_SMOOTH_MOVE_DELAY_TAP
+                    });
+                    await this.backend.mouseButton('left', 'down');
+                    await sleep(DRAG_HOLD_DURATION);
+                    await this.movePointer(Math.round(to.x), Math.round(to.y), {
+                        steps: SMOOTH_MOVE_STEPS_DRAG,
+                        stepDelayMs: SMOOTH_MOVE_DELAY_DRAG
+                    });
+                    await sleep(DRAG_HOLD_DURATION);
+                    await this.backend.mouseButton('left', 'up');
+                }
+            },
+            keyboard: {
+                typeText: async (value, opts)=>{
+                    this.assertConnected();
+                    const target = opts?.target;
+                    if (target) {
+                        await this.inputPrimitives.pointer.tap({
+                            x: target.center[0],
+                            y: target.center[1]
+                        });
+                        await sleep(device_INPUT_FOCUS_DELAY);
+                    }
+                    if (opts?.replace !== false) {
+                        await this.clearInput();
+                        await sleep(device_INPUT_CLEAR_DELAY);
+                    }
+                    if (opts?.focusOnly || !value) return;
+                    await this.backend.typeText(value);
+                },
+                clearInput: async (target)=>{
+                    this.assertConnected();
+                    const element = target;
+                    if (element) {
+                        await this.inputPrimitives.pointer.tap({
+                            x: element.center[0],
+                            y: element.center[1]
+                        });
+                        await sleep(device_INPUT_FOCUS_DELAY);
+                    }
+                    await this.clearInput();
+                    await sleep(device_INPUT_CLEAR_DELAY);
+                },
+                keyboardPress: async (keyName, opts)=>{
+                    this.assertConnected();
+                    const target = opts?.target;
+                    if (target) await this.inputPrimitives.pointer.tap({
+                        x: target.center[0],
+                        y: target.center[1]
+                    });
+                    await this.backend.keyPress(keyName);
+                }
+            },
+            scroll: {
+                scroll: async (param)=>{
+                    this.assertConnected();
+                    const target = param.locate;
+                    if (target) await this.moveToElement(target, {
+                        steps: device_SMOOTH_MOVE_STEPS_MOUSE_MOVE,
+                        stepDelayMs: device_SMOOTH_MOVE_DELAY_MOUSE_MOVE
+                    });
+                    if (param.scrollType && 'singleAction' !== param.scrollType) {
+                        const direction = this.edgeScrollDirection(param.scrollType);
+                        for(let i = 0; i < device_EDGE_SCROLL_STEPS; i++)await this.performWheel(direction, DEFAULT_SCROLL_DISTANCE, target?.center[0], target?.center[1]);
+                        await sleep(device_SCROLL_COMPLETE_DELAY);
+                        return;
+                    }
+                    await this.performWheel(param.direction || 'down', param.distance || DEFAULT_SCROLL_DISTANCE, target?.center[0], target?.center[1]);
+                    await sleep(device_SCROLL_COMPLETE_DELAY);
+                }
+            }
+        });
+        this.options = {
+            port: 3389,
+            securityProtocol: 'auto',
+            ignoreCertificate: false,
+            ...options
+        };
+        this.backend = options.backend || createDefaultRDPBackendClient();
+    }
+}
 class ComputerAgent extends Agent {
 }
 function createLocalComputerDevice(opts) {
@@ -823,12 +1365,33 @@ function createLocalComputerDevice(opts) {
         xvfbResolution: opts?.xvfbResolution
     });
 }
+function createRDPComputerDevice(opts) {
+    return new RDPDevice({
+        host: opts.host,
+        port: opts.port,
+        username: opts.username,
+        password: opts.password,
+        domain: opts.domain,
+        adminSession: opts.adminSession,
+        ignoreCertificate: opts.ignoreCertificate,
+        securityProtocol: opts.securityProtocol,
+        desktopWidth: opts.desktopWidth,
+        desktopHeight: opts.desktopHeight,
+        backend: opts.backend,
+        customActions: opts.customActions
+    });
+}
 async function agentForComputer(opts) {
     const device = createLocalComputerDevice(opts);
     await device.connect();
     return new ComputerAgent(device, opts);
 }
 const agentFromComputer = agentForComputer;
+async function agentForRDPComputer(opts) {
+    const device = createRDPComputerDevice(opts);
+    await device.connect();
+    return new ComputerAgent(device, opts);
+}
 function mcp_tools_define_property(obj, key, value) {
     if (key in obj) Object.defineProperty(obj, key, {
         value: value,
@@ -840,10 +1403,61 @@ function mcp_tools_define_property(obj, key, value) {
     return obj;
 }
 const mcp_tools_debug = getDebug('mcp:computer-tools');
+const RDP_SECURITY_PROTOCOLS = [
+    'auto',
+    'tls',
+    'nla',
+    'rdp'
+];
 const computerInitArgShape = {
-    displayId: z.string().optional().describe('Display ID (from computer_list_displays)'),
-    headless: z.boolean().optional().describe('Start virtual display via Xvfb (Linux only)')
+    displayId: z.string().optional().describe('Display ID for local mode (from computer_list_displays). Ignored when host is set.'),
+    headless: z.boolean().optional().describe('Start virtual display via Xvfb (Linux local mode only). Ignored when host is set.'),
+    host: z.string().optional().describe('RDP host (FQDN or IP). Set this to switch into RDP mode.'),
+    port: z.number().optional().describe('RDP port (default 3389). Requires host.'),
+    username: z.string().optional().describe('RDP username. Requires host.'),
+    password: z.string().optional().describe('RDP password. Requires host. Prefer setting via environment or a secrets manager.'),
+    domain: z.string().optional().describe('RDP domain. Requires host.'),
+    adminSession: z.boolean().optional().describe('Attach to the RDP admin/console session. Requires host.'),
+    ignoreCertificate: z.boolean().optional().describe('Skip TLS certificate validation. Requires host.'),
+    securityProtocol: z["enum"](RDP_SECURITY_PROTOCOLS).optional().describe('RDP security protocol negotiation (default auto). Requires host.'),
+    desktopWidth: z.number().optional().describe('Remote desktop width in pixels. Requires host.'),
+    desktopHeight: z.number().optional().describe('Remote desktop height in pixels. Requires host.')
 };
+function adaptComputerInitArgs(extracted) {
+    if (!extracted || 0 === Object.keys(extracted).length) return;
+    if (extracted.host) {
+        const { displayId: _d, headless: _h, ...rdpFields } = extracted;
+        return {
+            mode: 'rdp',
+            ...rdpFields,
+            host: extracted.host
+        };
+    }
+    return {
+        mode: 'local',
+        displayId: extracted.displayId,
+        headless: extracted.headless
+    };
+}
+function shouldRetargetAgent(opts) {
+    if (!opts) return false;
+    if ('rdp' === opts.mode) return true;
+    return void 0 !== opts.displayId || void 0 !== opts.headless;
+}
+function describeConnectTarget(opts) {
+    if (opts?.mode === 'rdp') {
+        const portSuffix = opts.port ? `:${opts.port}` : '';
+        const userSuffix = opts.username ? ` as ${opts.username}` : '';
+        return ` via RDP (${opts.host}${portSuffix}${userSuffix})`;
+    }
+    if (opts?.mode === 'local' && opts.displayId) return ` (Display: ${opts.displayId})`;
+    return ' (Primary display)';
+}
+function getCliReportSessionTarget(opts) {
+    if (opts?.mode === 'rdp') return `rdp:${opts.host}`;
+    if (opts?.mode === 'local' && opts.displayId) return opts.displayId;
+    return 'primary';
+}
 class ComputerMidsceneTools extends BaseMidsceneTools {
     getCliReportSessionName() {
         return 'midscene-computer';
@@ -852,9 +1466,7 @@ class ComputerMidsceneTools extends BaseMidsceneTools {
         return new ComputerDevice({});
     }
     async ensureAgent(opts) {
-        const displayId = opts?.displayId;
-        const headless = opts?.headless;
-        if (this.agent && (void 0 !== displayId || void 0 !== headless)) {
+        if (this.agent && shouldRetargetAgent(opts)) {
             try {
                 await this.agent.destroy?.();
             } catch (error) {
@@ -863,8 +1475,20 @@ class ComputerMidsceneTools extends BaseMidsceneTools {
             this.agent = void 0;
         }
         if (this.agent) return this.agent;
-        mcp_tools_debug('Creating Computer agent with displayId:', displayId || 'primary');
         const reportOptions = this.readCliReportAgentOptions();
+        if (opts?.mode === 'rdp') {
+            mcp_tools_debug('Creating RDP Computer agent for host:', opts.host);
+            const { mode: _mode, ...rdpFields } = opts;
+            const agent = await agentForRDPComputer({
+                ...rdpFields,
+                ...reportOptions ?? {}
+            });
+            this.agent = agent;
+            return agent;
+        }
+        const displayId = opts?.mode === 'local' ? opts.displayId : void 0;
+        const headless = opts?.mode === 'local' ? opts.headless : void 0;
+        mcp_tools_debug('Creating Computer agent with displayId:', displayId || 'primary');
         const agentOpts = {
             ...displayId ? {
                 displayId
@@ -882,12 +1506,12 @@ class ComputerMidsceneTools extends BaseMidsceneTools {
         return [
             {
                 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.',
+                description: "Connect to a computer desktop. Default (local) mode controls the local machine; pass displayId to target a specific local display (see computer_list_displays). Pass host to switch to RDP mode and connect to a remote Windows desktop via the RDP helper binary. RDP-related options (port/username/password/domain/securityProtocol/ignoreCertificate/adminSession/desktopWidth/desktopHeight) only take effect when host is set.",
                 schema: this.getAgentInitArgSchema(),
                 cli: this.getAgentInitArgCliMetadata(),
                 handler: async (args)=>{
                     const initArgs = this.extractAgentInitParam(args);
-                    const reportSession = this.createNewCliReportSession(initArgs?.displayId ?? 'primary');
+                    const reportSession = this.createNewCliReportSession(getCliReportSessionTarget(initArgs));
                     this.commitCliReportSession(reportSession);
                     if (this.agent) {
                         try {
@@ -903,7 +1527,7 @@ class ComputerMidsceneTools extends BaseMidsceneTools {
                         content: [
                             {
                                 type: 'text',
-                                text: `Connected to computer${initArgs?.displayId ? ` (Display: ${initArgs.displayId})` : ' (Primary display)'}`
+                                text: `Connected to computer${describeConnectTarget(initArgs)}`
                             },
                             ...this.buildScreenshotContent(screenshot)
                         ]
@@ -941,14 +1565,14 @@ class ComputerMidsceneTools extends BaseMidsceneTools {
             cli: {
                 preferBareKeys: true
             },
-            adapt: (extracted)=>extracted
+            adapt: (extracted)=>adaptComputerInitArgs(extracted)
         });
     }
 }
 const tools = new ComputerMidsceneTools();
 runToolsCLI(tools, 'midscene-computer', {
     stripPrefix: 'computer_',
-    version: "1.8.0",
+    version: "1.8.1",
     extraCommands: createReportCliCommands()
 }).catch((e)=>{
     process.exit(reportCLIError(e));