@testdriverai/runner 7.8.0-canary.10

package/lib/automation.js

@@ -0,0 +1,786 @@
+/**
+ * automation.js — Cross-platform desktop automation module (Node.js)
+ *
+ * Uses pyautogui (Python) via subprocess calls for mouse, keyboard, and
+ * screenshot operations. The pyautogui + pyautogui-cli packages are installed
+ * via pip in the Dockerfile / packer build. Uses child_process for exec,
+ * focus-window, get-active-window, and network commands.
+ *
+ * Same command interface as pyautogui-cli.py:
+ *   dispatch(command, data) → Promise<result>
+ *
+ * Protocol (matches pyautogui-cli.py):
+ *   Returns the "result" value on success (true, base64 string, object, etc.)
+ *   Throws on error (caller wraps into { error: message })
+ */
+const { spawn, execFile } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+const { EventEmitter } = require('events');
+
+const IS_WINDOWS = process.platform === 'win32';
+const IS_LINUX = process.platform === 'linux';
+const IS_MACOS = process.platform === 'darwin';
+
+// ─── Ensure DISPLAY is set on Linux ──────────────────────────────────────────
+// The entrypoint runs the runner as 'user' (via runuser) so it shares the X
+// session directly. DISPLAY should already be inherited, but set a fallback
+// just in case.
+if (IS_LINUX && !process.env.DISPLAY) {
+  process.env.DISPLAY = ':0';
+}
+
+// ─── Configuration ───────────────────────────────────────────────────────────
+
+const API_ROOT = process.env.TD_API_ROOT || process.env.API_ROOT || 'https://api.testdriver.ai';
+const API_KEY = process.env.TD_API_KEY;
+
+// ─── pyautogui via Python subprocess ─────────────────────────────────────────
+// Calls pyautogui functions via `python3 -c` (or `python -c` on Windows).
+// Each command spawns a short-lived Python process. The pyautogui library is
+// installed via `pip install pyautogui-cli` (which depends on pyautogui).
+//
+// String arguments (text, key names) are passed via sys.argv to avoid
+// shell injection and escaping issues.
+
+const PYTHON = IS_WINDOWS ? 'python' : 'python3';
+const PY_IMPORT = IS_LINUX
+  ? "import os; os.environ['DISPLAY'] = ':0'; import pyautogui, sys; pyautogui.FAILSAFE = False; "
+  : 'import pyautogui, sys; pyautogui.FAILSAFE = False; ';
+
+/**
+ * Run a pyautogui Python script via subprocess.
+ * @param {string} script — Python code (pyautogui + sys are already imported via PY_IMPORT prefix)
+ * @param {string[]} [extraArgs=[]] — additional args available as sys.argv[1], sys.argv[2], etc.
+ * @param {number} [timeout=15000] — subprocess timeout in ms
+ * @returns {Promise<string>} stdout output (trimmed)
+ */
+function runPyAutoGUI(script, extraArgs = [], timeout = 15000) {
+  return new Promise((resolve, reject) => {
+    // Always force DISPLAY=:0 on Linux so pyautogui can connect to X11
+    const env = { ...process.env };
+    if (IS_LINUX) {
+      env.DISPLAY = env.DISPLAY || ':0';
+    }
+    execFile(PYTHON, ['-c', PY_IMPORT + script, ...extraArgs.map(String)], {
+      encoding: 'utf-8',
+      timeout,
+      env,
+    }, (err, stdout, stderr) => {
+      if (err) {
+        const msg = (stderr || '').trim() || err.message;
+        reject(new Error(`pyautogui command failed: ${msg}`));
+      } else {
+        resolve((stdout || '').trim());
+      }
+    });
+  });
+}
+
+// ─── Persistent shell session ────────────────────────────────────────────────
+
+class ShellSession {
+  constructor() {
+    this._process = null;
+    this._stderrLines = [];
+    this._lock = false;
+  }
+
+  _ensureStarted() {
+    if (this._process && this._process.exitCode === null) return;
+
+    let cmd;
+    let env;
+
+    if (IS_WINDOWS) {
+      cmd = ['powershell', ['-NoExit', '-ExecutionPolicy', 'Bypass', '-Command', '-']];
+    } else {
+      cmd = ['/bin/bash', ['--norc', '--noprofile', '-i']];
+    }
+    env = { ...process.env };
+
+    this._process = spawn(cmd[0], cmd[1], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env,
+    });
+
+    this._process.stderr.on('data', (chunk) => {
+      this._stderrLines.push(chunk.toString());
+    });
+
+    this._process.on('error', (err) => {
+      console.error(`[automation] Shell error: ${err.message}`);
+    });
+
+    this._process.on('exit', (code) => {
+      console.log(`[automation] Shell exited (code=${code})`);
+      this._process = null;
+    });
+  }
+
+  /**
+   * Run a command in the persistent shell session.
+   * @param {string} command - The command to run
+   * @param {number} [timeout=30] - Timeout in seconds
+   * @param {object} [options] - Additional options
+   * @param {function} [options.onChunk] - Callback for streaming stdout chunks: (text: string) => void
+   * @returns {Promise<{stdout: string, stderr: string, returncode: number, success: boolean}>}
+   */
+  async run(command, timeout = 30, options = {}) {
+    const { onChunk } = options;
+
+    // Wait for any in-flight command (simple serial lock)
+    while (this._lock) {
+      await new Promise(r => setTimeout(r, 50));
+    }
+    this._lock = true;
+
+    try {
+      this._ensureStarted();
+
+      const delimiter = `###END_OF_OUTPUT_${Date.now()}_${Math.random().toString(36).slice(2)}###`;
+      const fullCommand = IS_WINDOWS
+        ? `${command}\nWrite-Output '${delimiter}'\n`
+        : `${command}\necho '${delimiter}'\n`;
+
+      // Clear stderr buffer
+      this._stderrLines = [];
+
+      return await new Promise((resolve, reject) => {
+        const timeoutMs = timeout * 1000;
+        const timer = setTimeout(() => {
+          cleanup();
+          // Kill the shell process so the hung command doesn't block
+          // subsequent commands. A fresh shell will be spawned on next run().
+          console.warn(`[shell] Command timed out after ${timeout}s — killing shell to recover`);
+          try {
+            if (this._process) {
+              this._process.stdin.end();
+              this._process.kill('SIGKILL');
+            }
+          } catch (e) {
+            console.warn('[shell] Failed to kill timed-out shell:', e.message);
+          }
+          this._process = null;
+          resolve({
+            stdout: '',
+            stderr: 'Command timed out',
+            returncode: -1,
+            success: false,
+          });
+        }, timeoutMs);
+
+        const stdoutLines = [];
+
+        const onData = (chunk) => {
+          const text = chunk.toString();
+          const lines = text.split('\n');
+          for (const line of lines) {
+            if (line.includes(delimiter)) {
+              cleanup();
+              const stdout = stdoutLines.join('\n').replace(/\n$/, '');
+              const stderr = this._stderrLines.join('').replace(/\n$/, '');
+              resolve({
+                stdout,
+                stderr,
+                returncode: 0,
+                success: true,
+              });
+              return;
+            }
+            stdoutLines.push(line);
+          }
+
+          // Stream chunk to caller if callback provided
+          if (onChunk) {
+            try {
+              onChunk(text);
+            } catch (e) {
+              // Don't let streaming errors break the command
+              console.warn('[shell] onChunk callback error:', e.message);
+            }
+          }
+        };
+
+        const cleanup = () => {
+          clearTimeout(timer);
+          this._process.stdout.removeListener('data', onData);
+        };
+
+        this._process.stdout.on('data', onData);
+        this._process.stdin.write(fullCommand);
+      });
+    } catch (err) {
+      return {
+        stdout: '',
+        stderr: err.message,
+        returncode: -1,
+        success: false,
+      };
+    } finally {
+      this._lock = false;
+    }
+  }
+
+  cleanup() {
+    if (this._process) {
+      try {
+        this._process.stdin.end();
+        this._process.kill();
+      } catch {}
+      this._process = null;
+    }
+  }
+}
+
+// ─── Script runner helper (matches pyautogui-cli.py's run_script) ────────────
+
+function runScript(args, timeout = 30) {
+  return new Promise((resolve) => {
+    const spawnArgs = args;
+    const env = { ...process.env };
+
+    const proc = spawn(spawnArgs[0], spawnArgs.slice(1), {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env,
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    proc.stdout.on('data', (chunk) => { stdout += chunk.toString(); });
+    proc.stderr.on('data', (chunk) => { stderr += chunk.toString(); });
+
+    const timer = setTimeout(() => {
+      proc.kill();
+      resolve({
+        stdout: '',
+        stderr: 'Command timed out',
+        returncode: -1,
+        success: false,
+      });
+    }, timeout * 1000);
+
+    proc.on('close', (code) => {
+      clearTimeout(timer);
+      resolve({
+        stdout,
+        stderr,
+        returncode: code,
+        success: code === 0,
+      });
+    });
+
+    proc.on('error', (err) => {
+      clearTimeout(timer);
+      resolve({
+        stdout: '',
+        stderr: err.message,
+        returncode: -1,
+        success: false,
+      });
+    });
+  });
+}
+
+// ─── Automation class ────────────────────────────────────────────────────────
+
+class Automation extends EventEmitter {
+  constructor(options = {}) {
+    super();
+    this._shell = new ShellSession();
+    this._sandboxId = options.sandboxId;
+    this._apiRoot = options.apiRoot;
+    this._apiKey = options.apiKey;
+  }
+
+  /**
+   * Release all modifier keys to prevent stuck keys.
+   * Mirrors pyautogui-cli.py's release_modifiers().
+   * Done in a single Python call for efficiency.
+   */
+  async releaseModifiers() {
+    try {
+      await runPyAutoGUI(
+        "for k in ['shift','shiftleft','shiftright','ctrl','ctrlleft','ctrlright'," +
+        "'alt','altleft','altright','command','win','winleft','winright']:\n" +
+        " try: pyautogui.keyUp(k)\n" +
+        " except: pass"
+      );
+    } catch {}
+  }
+
+  /**
+   * Dispatch a command by name — same interface as pyautogui-cli.py's dispatch_command.
+   * @param {string} command - Command name (e.g. 'click', 'screenshot', 'exec')
+   * @param {object} data - Command data/parameters
+   * @returns {Promise<*>} Result value (true, base64 string, object, etc.)
+   */
+  async dispatch(command, data = {}) {
+    // Normalize command: strip 'commands.' or 'system.' prefix
+    let normalizedCommand = command;
+    if (command && command.startsWith('commands.')) {
+      normalizedCommand = command.slice('commands.'.length);
+    } else if (command && command.startsWith('system.')) {
+      normalizedCommand = command.slice('system.'.length);
+    }
+    // Normalize camelCase to lowercase (e.g. leftClick → leftclick, mouseDown → mousedown)
+    normalizedCommand = normalizedCommand.toLowerCase();
+
+    console.log(`[automation] dispatch: "${command}" → "${normalizedCommand}", data keys: ${Object.keys(data).join(',')}`);
+    this.emit('log', `dispatch: "${command}" → "${normalizedCommand}"`);
+    if (normalizedCommand === 'write') {
+      console.log(`[automation] write text: "${data.text}" (length: ${data.text?.length})`);
+      this.emit('log', `write text: "${data.text}" (length: ${data.text?.length})`);
+    }
+    if (normalizedCommand === 'press') {
+      console.log(`[automation] press keys:`, JSON.stringify(data.keys || data.key));
+      this.emit('log', `press keys: ${JSON.stringify(data.keys || data.key)}`);
+    }
+
+    switch (normalizedCommand) {
+      case 'move':
+      case 'movemouse': {
+        console.log(`[automation] move: (${data.x},${data.y})`);
+        await runPyAutoGUI(`pyautogui.moveTo(${data.x}, ${data.y})`);
+        return true;
+      }
+
+      case 'moverel': {
+        await runPyAutoGUI(`pyautogui.moveRel(${data.x}, ${data.y})`);
+        return true;
+      }
+
+      case 'click':
+      case 'leftclick': {
+        const button = data.button || 'left';
+        if (data.x != null && data.y != null) {
+          console.log(`[automation] click: (${data.x},${data.y})`);
+          await runPyAutoGUI(`pyautogui.click(${data.x}, ${data.y}, button=sys.argv[1])`, [button]);
+        } else {
+          await runPyAutoGUI(`pyautogui.click(button=sys.argv[1])`, [button]);
+        }
+        return true;
+      }
+
+      case 'rightclick': {
+        if (data.x != null && data.y != null) {
+          await runPyAutoGUI(`pyautogui.rightClick(${data.x}, ${data.y})`);
+        } else {
+          await runPyAutoGUI('pyautogui.rightClick()');
+        }
+        return true;
+      }
+
+      case 'middleclick': {
+        if (data.x != null && data.y != null) {
+          await runPyAutoGUI(`pyautogui.middleClick(${data.x}, ${data.y})`);
+        } else {
+          await runPyAutoGUI('pyautogui.middleClick()');
+        }
+        return true;
+      }
+
+      case 'doubleclick': {
+        if (data.x != null && data.y != null) {
+          await runPyAutoGUI(`pyautogui.doubleClick(${data.x}, ${data.y})`);
+        } else {
+          await runPyAutoGUI('pyautogui.doubleClick()');
+        }
+        return true;
+      }
+
+      case 'tripleclick': {
+        if (data.x != null && data.y != null) {
+          await runPyAutoGUI(`pyautogui.tripleClick(${data.x}, ${data.y})`);
+        } else {
+          await runPyAutoGUI('pyautogui.tripleClick()');
+        }
+        return true;
+      }
+
+      case 'mousedown':
+      case 'mousepress': {
+        const button = data.button || 'left';
+        if (data.x != null && data.y != null) {
+          await runPyAutoGUI(`pyautogui.mouseDown(x=${data.x}, y=${data.y}, button=sys.argv[1])`, [button]);
+        } else {
+          await runPyAutoGUI(`pyautogui.mouseDown(button=sys.argv[1])`, [button]);
+        }
+        return true;
+      }
+
+      case 'mouseup':
+      case 'mouserelease': {
+        const button = data.button || 'left';
+        if (data.x != null && data.y != null) {
+          await runPyAutoGUI(`pyautogui.mouseUp(x=${data.x}, y=${data.y}, button=sys.argv[1])`, [button]);
+        } else {
+          await runPyAutoGUI(`pyautogui.mouseUp(button=sys.argv[1])`, [button]);
+        }
+        return true;
+      }
+
+      case 'scroll': {
+        const raw = data.amount || 0;
+        // pyautogui.scroll(): positive = up, negative = down
+        const amount = data.direction === 'down' ? -Math.abs(raw) : Math.abs(raw);
+        await runPyAutoGUI(`pyautogui.scroll(${amount})`);
+        return true;
+      }
+
+      case 'write': {
+        // Type each character — matches pyautogui.write() behavior
+        // Text passed via sys.argv[1] to avoid escaping issues
+        await runPyAutoGUI('pyautogui.write(sys.argv[1])', [data.text || '']);
+        await this.releaseModifiers();
+        return true;
+      }
+
+      case 'press': {
+        // SDK sends { keys: [...] } (array) or { key: 'x' } (singular)
+        if (data.keys && Array.isArray(data.keys)) {
+          // Multiple keys = hotkey/combo — pass via sys.argv[1:]
+          await runPyAutoGUI('pyautogui.hotkey(*sys.argv[1:])', data.keys);
+        } else {
+          const key = data.key || data.keys;
+          await runPyAutoGUI('pyautogui.press(sys.argv[1])', [key]);
+        }
+        await this.releaseModifiers();
+        return true;
+      }
+
+      case 'hotkey': {
+        // Pass all keys via sys.argv[1:]
+        await runPyAutoGUI('pyautogui.hotkey(*sys.argv[1:])', data.keys);
+        await this.releaseModifiers();
+        return true;
+      }
+
+      case 'keydown': {
+        await runPyAutoGUI('pyautogui.keyDown(sys.argv[1])', [data.key]);
+        return true;
+      }
+
+      case 'keyup': {
+        await runPyAutoGUI('pyautogui.keyUp(sys.argv[1])', [data.key]);
+        return true;
+      }
+
+      case 'get-mouse-position': {
+        const output = await runPyAutoGUI(
+          'pos = pyautogui.position(); print(f"{pos.x},{pos.y}")'
+        );
+        const [px, py] = output.split(',').map(Number);
+        return { x: px, y: py };
+      }
+
+      case 'get-screen-size': {
+        const output = await runPyAutoGUI(
+          'size = pyautogui.size(); print(f"{size.width},{size.height}")'
+        );
+        const [w, h] = output.split(',').map(Number);
+        return { width: w, height: h };
+      }
+
+      case 'alert': {
+        // No direct equivalent in Node — execute via shell
+        if (IS_LINUX) {
+          await runScript(['zenity', '--info', '--text', data.text], 10);
+        } else if (IS_MACOS) {
+          await runScript(['osascript', '-e', `display dialog "${data.text}"`], 10);
+        } else {
+          await runScript(['powershell', '-Command', `Add-Type -AssemblyName System.Windows.Forms; [System.Windows.Forms.MessageBox]::Show("${data.text}")`], 10);
+        }
+        return true;
+      }
+
+      case 'focus-window': {
+        return await this._focusWindow(data);
+      }
+
+      case 'focus-application': {
+        return await this._focusWindow({
+          ...data,
+          title: data.title || data.name || data.appName || '',
+        });
+      }
+
+      case 'get-active-window': {
+        return await this._getActiveWindow(data);
+      }
+
+      case 'network': {
+        return await this._getNetwork(data);
+      }
+
+      case 'exec': {
+        const timeout = data.timeout || 30;
+        return await this._shell.run(data.command, timeout);
+      }
+
+      // SDK sends 'commands.run' for exec — map to shell command
+      case 'run': {
+        const timeout = Math.ceil((data.timeout || 300000) / 1000); // ms to seconds
+        const requestId = data.requestId;
+
+        // Buffer stdout chunks to ~16KB before emitting over Ably.
+        // This reduces message count while keeping each message well under
+        // Ably's 64KB limit. The SDK accumulates these chunks and reconstructs
+        // the full stdout — the final response only carries returncode + stderr.
+        const CHUNK_FLUSH_SIZE = 16 * 1024; // 16KB
+        let chunkBuffer = '';
+        const flushChunkBuffer = () => {
+          if (chunkBuffer.length > 0) {
+            this.emit('exec.output', { requestId, chunk: chunkBuffer });
+            chunkBuffer = '';
+          }
+        };
+
+        try {
+          const result = await this._shell.run(data.command, timeout, {
+            onChunk: (text) => {
+              chunkBuffer += text;
+              if (chunkBuffer.length >= CHUNK_FLUSH_SIZE) {
+                flushChunkBuffer();
+              }
+            },
+          });
+
+          // Flush any remaining buffered output
+          flushChunkBuffer();
+
+          // Only send returncode + stderr in the final response.
+          // stdout was already streamed via exec.output chunks — sending it
+          // again here would duplicate data AND can exceed Ably's 64KB message
+          // limit when the command produces large output (e.g. dashcam stop).
+          return {
+            out: {
+              returncode: result.returncode,
+              stdout: '',
+              stderr: result.stderr,
+            },
+          };
+        } catch (err) {
+          flushChunkBuffer();
+          return {
+            out: {
+              returncode: 1,
+              stdout: '',
+              stderr: err.message,
+            },
+          };
+        }
+      }
+
+      case 'extract':
+      case 'remember':
+      case 'screenshot': {
+        console.log(`[automation] Handling ${normalizedCommand} command - will capture and upload to S3`);
+        // For extract/remember: capture screenshot, upload to S3, return s3Key
+        // SDK will then call API with the s3Key
+        // For system.screenshot (normalized to 'screenshot'): same flow (return s3Key instead of base64)
+        
+        // Capture screenshot locally
+        console.log('[automation] Step 1: Capturing screenshot...');
+        const screenshot = await this._captureScreenshot();
+        console.log(`[automation] Step 2: Screenshot captured, size: ${screenshot.length} bytes (base64)`);
+        const buffer = Buffer.from(screenshot, 'base64');
+        console.log(`[automation] Step 3: Buffer created, size: ${buffer.length} bytes`);
+
+        // Upload screenshot to S3 and return key
+        console.log('[automation] Step 4: Uploading to S3...');
+        const s3Key = await this._uploadToS3(buffer, this._sandboxId, 'image/png');
+        console.log(`[automation] Step 5: Upload complete, s3Key: ${s3Key}`);
+        
+        return { s3Key };
+      }
+
+      case 'ping':
+        return 'pong';
+
+      default:
+        throw new Error(`Unknown command: ${command}`);
+    }
+  }
+
+  // ── S3 Upload (for large screenshots that exceed Ably limits) ──────
+
+  async _uploadToS3(buffer, sandboxId, contentType = 'image/jpeg') {
+    const apiKey = this._apiKey || API_KEY;
+    if (!apiKey || !sandboxId) {
+      throw new Error('API_KEY and sandboxId required for S3 upload');
+    }
+
+    // Use instance-level apiRoot (passed from runner) with fallback to module-level constant
+    const apiRoot = this._apiRoot || API_ROOT;
+
+    // Get presigned URL from API (30s timeout)
+    const response = await fetch(`${apiRoot}/api/v7/runner/upload-url`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        apiKey,
+        sandboxId,
+        contentType,
+      }),
+      signal: AbortSignal.timeout(30000),
+    });
+
+    if (!response.ok) {
+      const text = await response.text();
+      throw new Error(`Failed to get upload URL: ${response.status} ${text}`);
+    }
+
+    const { uploadUrl, s3Key } = await response.json();
+    console.log(`[automation] Got S3 upload URL, s3Key: ${s3Key}`);
+
+    // Upload to S3 (30s timeout)
+    const uploadResponse = await fetch(uploadUrl, {
+      method: 'PUT',
+      headers: { 'Content-Type': contentType },
+      body: buffer,
+      signal: AbortSignal.timeout(30000),
+    });
+
+    if (!uploadResponse.ok) {
+      console.error(`[automation] S3 upload failed: status=${uploadResponse.status}`);
+      throw new Error(`S3 upload failed: ${uploadResponse.status}`);
+    }
+
+    console.log(`[automation] S3 upload successful, returning s3Key: ${s3Key}`);
+    return s3Key;
+  }
+
+  // ── Screenshot (highest quality PNG, via pyautogui → temp file → sharp) ──
+
+  async _captureScreenshot() {
+    const sharp = require('sharp');
+    const tmpFile = path.join(os.tmpdir(), `td_screenshot_${Date.now()}.png`);
+
+    try {
+      // Capture screenshot via pyautogui → saves to temp file
+      // Python handles Retina downscale: if physical size differs from logical,
+      // the image is resized to logical dimensions before saving.
+      await runPyAutoGUI(
+        'img = pyautogui.screenshot()\n' +
+        'logical = pyautogui.size()\n' +
+        'if img.size[0] != logical[0] or img.size[1] != logical[1]:\n' +
+        '    from PIL import Image\n' +
+        '    img = img.resize((logical[0], logical[1]), Image.LANCZOS)\n' +
+        'img.save(sys.argv[1], format="PNG")',
+        [tmpFile],
+        20000
+      );
+
+      // Read the PNG and re-encode with sharp (lossless, no compression)
+      const pngBuffer = fs.readFileSync(tmpFile);
+      const buffer = await sharp(pngBuffer)
+        .png({ compressionLevel: 0 })
+        .toBuffer();
+
+      return buffer.toString('base64');
+    } finally {
+      // Clean up temp file
+      try { fs.unlinkSync(tmpFile); } catch {}
+    }
+  }
+
+  // ── Focus window (platform-specific) ───────────────────────────────
+
+  async _focusWindow(data) {
+    const title = data.title || '';
+    const timeout = data.timeout || 30;
+
+    if (IS_WINDOWS) {
+      const scriptPath = path.join(__dirname, '..', 'focusWindow.ps1');
+      const action = data.action || 'Focus';
+      return await runScript(
+        ['powershell', '-ExecutionPolicy', 'Bypass', '-File', scriptPath, title, action],
+        timeout,
+      );
+    } else {
+      // Linux: try jumpapp first, then xdotool fallback
+      let result = await runScript(['jumpapp', '-f', title], Math.min(timeout, 10));
+      if (!result.success) {
+        result = await runScript(
+          ['xdotool', 'search', '--name', title, 'windowactivate'],
+          Math.min(timeout, 10),
+        );
+      }
+      return result;
+    }
+  }
+
+  // ── Get active window (platform-specific) ──────────────────────────
+
+  async _getActiveWindow(data) {
+    const timeout = data.timeout || 10;
+
+    if (IS_WINDOWS) {
+      const scriptPath = path.join(__dirname, '..', 'getActiveWindow.ps1');
+      const result = await runScript(
+        ['powershell', '-ExecutionPolicy', 'Bypass', '-File', scriptPath],
+        timeout,
+      );
+      if (result.success) {
+        try {
+          return JSON.parse(result.stdout.trim());
+        } catch {
+          return result;
+        }
+      }
+      return result;
+    } else {
+      // Linux: xdotool
+      const result = await runScript(
+        ['bash', '-c', "xdotool getactivewindow getwindowname 2>/dev/null || echo ''"],
+        timeout,
+      );
+      return {
+        name: result.success ? result.stdout.trim() : '',
+        success: result.success,
+      };
+    }
+  }
+
+  // ── Network info (platform-specific) ───────────────────────────────
+
+  async _getNetwork(data) {
+    const timeout = data.timeout || 10;
+
+    if (IS_WINDOWS) {
+      const scriptPath = path.join(__dirname, '..', 'network.ps1');
+      const result = await runScript(
+        ['powershell', '-ExecutionPolicy', 'Bypass', '-File', scriptPath],
+        timeout,
+      );
+      if (result.success) {
+        try {
+          return JSON.parse(result.stdout.trim());
+        } catch {
+          return result;
+        }
+      }
+      return result;
+    } else {
+      const result = await runScript(
+        ['bash', '-c', "ip -j addr show 2>/dev/null || ifconfig -a 2>/dev/null || echo '{}'"],
+        timeout,
+      );
+      return {
+        stdout: result.stdout,
+        success: result.success,
+      };
+    }
+  }
+
+  // ── Cleanup ────────────────────────────────────────────────────────
+
+  cleanup() {
+    this._shell.cleanup();
+  }
+}
+
+module.exports = { Automation };