@testdriverai/runner 7.8.0-canary.10

package/lib/automation.js.bak

@@ -0,0 +1,882 @@
+/**
+ * automation.js — Cross-platform desktop automation module (Node.js)
+ *
+ * Drop-in replacement for pyautogui-cli.py. Uses @nut-tree/nut-js for
+ * mouse, keyboard, and screenshot operations. 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 } = 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.API_ROOT || process.env.TD_API_ROOT || 'https://api.testdriver.ai';
+const API_KEY = process.env.TD_API_KEY;
+
+// ─── Lazy-load @nut-tree-fork/nut-js (heavy native deps) ────────────────────
+
+let _nut = null;
+function getNut() {
+  if (!_nut) {
+    _nut = require('@nut-tree-fork/nut-js');
+    // Disable nut.js automatic mouse speed — we want instant moves like pyautogui
+    _nut.mouse.config.mouseSpeed = 0;
+    _nut.mouse.config.autoDelayMs = 0;
+    _nut.keyboard.config.autoDelayMs = 0;
+  }
+  return _nut;
+}
+
+// ─── Key name mapping: pyautogui key names → nut-js Key enum ─────────────────
+
+function mapKey(keyName) {
+  const { Key } = getNut();
+
+  // Direct mappings for common keys
+  const keyMap = {
+    // Letters
+    'a': Key.A, 'b': Key.B, 'c': Key.C, 'd': Key.D, 'e': Key.E,
+    'f': Key.F, 'g': Key.G, 'h': Key.H, 'i': Key.I, 'j': Key.J,
+    'k': Key.K, 'l': Key.L, 'm': Key.M, 'n': Key.N, 'o': Key.O,
+    'p': Key.P, 'q': Key.Q, 'r': Key.R, 's': Key.S, 't': Key.T,
+    'u': Key.U, 'v': Key.V, 'w': Key.W, 'x': Key.X, 'y': Key.Y,
+    'z': Key.Z,
+
+    // Numbers
+    '0': Key.Num0, '1': Key.Num1, '2': Key.Num2, '3': Key.Num3,
+    '4': Key.Num4, '5': Key.Num5, '6': Key.Num6, '7': Key.Num7,
+    '8': Key.Num8, '9': Key.Num9,
+
+    // Function keys
+    'f1': Key.F1, 'f2': Key.F2, 'f3': Key.F3, 'f4': Key.F4,
+    'f5': Key.F5, 'f6': Key.F6, 'f7': Key.F7, 'f8': Key.F8,
+    'f9': Key.F9, 'f10': Key.F10, 'f11': Key.F11, 'f12': Key.F12,
+
+    // Modifiers
+    'shift': Key.LeftShift, 'shiftleft': Key.LeftShift, 'shiftright': Key.RightShift,
+    'ctrl': Key.LeftControl, 'ctrlleft': Key.LeftControl, 'ctrlright': Key.RightControl,
+    'control': Key.LeftControl,
+    'alt': Key.LeftAlt, 'altleft': Key.LeftAlt, 'altright': Key.RightAlt,
+    'command': Key.LeftSuper, 'cmd': Key.LeftSuper, 'super': Key.LeftSuper,
+    'win': Key.LeftSuper, 'winleft': Key.LeftSuper, 'winright': Key.RightSuper,
+    'meta': Key.LeftSuper,
+
+    // Navigation
+    'enter': Key.Enter, 'return': Key.Enter,
+    'tab': Key.Tab,
+    'space': Key.Space, ' ': Key.Space,
+    'backspace': Key.Backspace,
+    'delete': Key.Delete, 'del': Key.Delete,
+    'escape': Key.Escape, 'esc': Key.Escape,
+    'insert': Key.Insert,
+    'home': Key.Home, 'end': Key.End,
+    'pageup': Key.PageUp, 'pagedown': Key.PageDown,
+
+    // Arrow keys
+    'up': Key.Up, 'down': Key.Down, 'left': Key.Left, 'right': Key.Right,
+
+    // Symbols
+    'minus': Key.Minus, '-': Key.Minus,
+    'equal': Key.Equal, '=': Key.Equal,
+    'bracketleft': Key.LeftBracket, '[': Key.LeftBracket,
+    'bracketright': Key.RightBracket, ']': Key.RightBracket,
+    'backslash': Key.Backslash, '\\': Key.Backslash,
+    'semicolon': Key.Semicolon, ';': Key.Semicolon,
+    'quote': Key.Quote, "'": Key.Quote,
+    'comma': Key.Comma, ',': Key.Comma,
+    'period': Key.Period, '.': Key.Period,
+    'slash': Key.Slash, '/': Key.Slash,
+    'grave': Key.Grave, '`': Key.Grave,
+
+    // Misc
+    'capslock': Key.CapsLock,
+    'numlock': Key.NumLock,
+    'scrolllock': Key.ScrollLock,
+    'printscreen': Key.Print,
+    'pause': Key.Pause,
+  };
+
+  const mapped = keyMap[keyName.toLowerCase()];
+  if (mapped !== undefined) return mapped;
+
+  // Fallback: try uppercase enum lookup
+  const upper = keyName.charAt(0).toUpperCase() + keyName.slice(1);
+  if (Key[upper] !== undefined) return Key[upper];
+
+  throw new Error(`Unknown key: ${keyName}`);
+}
+
+// ─── 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();
+          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;
+    this._logicalScreen = null; // cached {width, height} of logical screen
+  }
+
+  /**
+   * Get the logical screen dimensions (cached).
+   */
+  async _getLogicalScreen() {
+    if (this._logicalScreen) return this._logicalScreen;
+    try {
+      const { screen } = getNut();
+      const w = await screen.width();
+      const h = await screen.height();
+      this._logicalScreen = { width: w, height: h };
+      console.log(`[automation] Logical screen: ${w}x${h}`);
+    } catch (err) {
+      console.warn('[automation] Could not determine screen size, using 1366x768:', err.message);
+      this._logicalScreen = { width: 1366, height: 768 };
+    }
+    return this._logicalScreen;
+  }
+
+  /**
+   * Scale coordinates from SDK space (TD_RESOLUTION = 1366x768) to
+   * logical mouse coordinate space. The SDK always resizes screenshots
+   * to 1366x768 before sending to AI, so AI returns coordinates in that
+   * space. nut-js mouse operates in logical screen coordinates.
+   * On cloud sandboxes (1366x768 resolution), this is a no-op.
+   */
+  async _scaleCoords(x, y) {
+    const SDK_WIDTH = 1366;
+    const SDK_HEIGHT = 768;
+    const logical = await this._getLogicalScreen();
+    if (logical.width === SDK_WIDTH && logical.height === SDK_HEIGHT) {
+      return { x, y };
+    }
+    return {
+      x: Math.round(x * (logical.width / SDK_WIDTH)),
+      y: Math.round(y * (logical.height / SDK_HEIGHT)),
+    };
+  }
+
+  /**
+   * Release all modifier keys to prevent stuck keys.
+   * Mirrors pyautogui-cli.py's release_modifiers().
+   */
+  async releaseModifiers() {
+    const { keyboard, Key } = getNut();
+    const modifiers = [
+      Key.LeftShift, Key.RightShift,
+      Key.LeftControl, Key.RightControl,
+      Key.LeftAlt, Key.RightAlt,
+      Key.LeftSuper, Key.RightSuper,
+    ];
+    for (const mod of modifiers) {
+      try {
+        await keyboard.releaseKey(mod);
+      } 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 = {}) {
+    const { mouse, keyboard, screen, Button, Key, Point } = getNut();
+    // 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': {
+        const mv = await this._scaleCoords(data.x, data.y);
+        console.log(`[automation] move: raw(${data.x},${data.y}) → scaled(${mv.x},${mv.y})`);
+        await mouse.setPosition(new Point(mv.x, mv.y));
+        return true;
+      }
+
+      case 'moverel': {
+        const pos = await mouse.getPosition();
+        const dr = await this._scaleCoords(data.x, data.y);
+        await mouse.setPosition(new Point(pos.x + dr.x, pos.y + dr.y));
+        return true;
+      }
+
+      case 'click':
+      case 'leftclick': {
+        const btn = this._mapButton(data.button || 'left');
+        if (data.x != null && data.y != null) {
+          const sc = await this._scaleCoords(data.x, data.y);
+          console.log(`[automation] click: raw(${data.x},${data.y}) → scaled(${sc.x},${sc.y})`);
+          await mouse.setPosition(new Point(sc.x, sc.y));
+        }
+        await mouse.click(btn);
+        return true;
+      }
+
+      case 'rightclick': {
+        if (data.x != null && data.y != null) {
+          const sc = await this._scaleCoords(data.x, data.y);
+          await mouse.setPosition(new Point(sc.x, sc.y));
+        }
+        await mouse.click(Button.RIGHT);
+        return true;
+      }
+
+      case 'middleclick': {
+        if (data.x != null && data.y != null) {
+          const sc = await this._scaleCoords(data.x, data.y);
+          await mouse.setPosition(new Point(sc.x, sc.y));
+        }
+        await mouse.click(Button.MIDDLE);
+        return true;
+      }
+
+      case 'doubleclick': {
+        if (data.x != null && data.y != null) {
+          const sc = await this._scaleCoords(data.x, data.y);
+          await mouse.setPosition(new Point(sc.x, sc.y));
+        }
+        await mouse.doubleClick(Button.LEFT);
+        return true;
+      }
+
+      case 'tripleclick': {
+        if (data.x != null && data.y != null) {
+          const sc = await this._scaleCoords(data.x, data.y);
+          await mouse.setPosition(new Point(sc.x, sc.y));
+        }
+        // nut-js doesn't have tripleClick — simulate with 3 rapid clicks
+        await mouse.click(Button.LEFT);
+        await mouse.click(Button.LEFT);
+        await mouse.click(Button.LEFT);
+        return true;
+      }
+
+      case 'mousedown':
+      case 'mousepress': {
+        const btn = this._mapButton(data.button || 'left');
+        if (data.x != null && data.y != null) {
+          const sc = await this._scaleCoords(data.x, data.y);
+          await mouse.setPosition(new Point(sc.x, sc.y));
+        }
+        await mouse.pressButton(btn);
+        return true;
+      }
+
+      case 'mouseup':
+      case 'mouserelease': {
+        const btn = this._mapButton(data.button || 'left');
+        if (data.x != null && data.y != null) {
+          const sc = await this._scaleCoords(data.x, data.y);
+          await mouse.setPosition(new Point(sc.x, sc.y));
+        }
+        await mouse.releaseButton(btn);
+        return true;
+      }
+
+      case 'scroll': {
+        const amount = data.amount || 0;
+        // nut-js scrollDown/scrollUp take positive values
+        if (amount > 0) {
+          await mouse.scrollUp(Math.abs(amount));
+        } else if (amount < 0) {
+          await mouse.scrollDown(Math.abs(amount));
+        }
+        return true;
+      }
+
+      case 'write': {
+        // Type each character — matches pyautogui.write() behavior (types literal characters)
+        await keyboard.type(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
+          const keys = data.keys.map(k => mapKey(k));
+          for (const key of keys) {
+            await keyboard.pressKey(key);
+          }
+          for (const key of keys.reverse()) {
+            await keyboard.releaseKey(key);
+          }
+        } else {
+          const key = mapKey(data.key || data.keys);
+          await keyboard.pressKey(key);
+          await keyboard.releaseKey(key);
+        }
+        await this.releaseModifiers();
+        return true;
+      }
+
+      case 'hotkey': {
+        const keys = data.keys.map(k => mapKey(k));
+        // Press all keys down, then release in reverse order
+        for (const key of keys) {
+          await keyboard.pressKey(key);
+        }
+        for (const key of keys.reverse()) {
+          await keyboard.releaseKey(key);
+        }
+        await this.releaseModifiers();
+        return true;
+      }
+
+      case 'keydown': {
+        const key = mapKey(data.key);
+        await keyboard.pressKey(key);
+        return true;
+      }
+
+      case 'keyup': {
+        const key = mapKey(data.key);
+        await keyboard.releaseKey(key);
+        return true;
+      }
+
+      case 'get-mouse-position': {
+        const pos = await mouse.getPosition();
+        return { x: pos.x, y: pos.y };
+      }
+
+      case 'get-screen-size': {
+        const region = await screen.width();
+        const height = await screen.height();
+        return { width: region, height };
+      }
+
+      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;
+        try {
+          const result = await this._shell.run(data.command, timeout, {
+            onChunk: (text) => {
+              // Emit streaming chunk so AblyService can forward to SDK
+              this.emit('exec.output', { requestId, chunk: text });
+            },
+          });
+          // SDK expects { out: { returncode, stdout, stderr } }
+          // ShellSession.run() already returns { stdout, stderr, returncode, success }
+          return {
+            out: {
+              returncode: result.returncode,
+              stdout: result.stdout,
+              stderr: result.stderr,
+            },
+          };
+        } catch (err) {
+          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}`);
+    }
+  }
+
+  // ── Button mapping ─────────────────────────────────────────────────
+
+  _mapButton(button) {
+    const { Button } = getNut();
+    switch ((button || 'left').toLowerCase()) {
+      case 'left': return Button.LEFT;
+      case 'right': return Button.RIGHT;
+      case 'middle': return Button.MIDDLE;
+      default: return Button.LEFT;
+    }
+  }
+
+  // ── S3 Upload (for large screenshots that exceed Ably limits) ──────
+
+  async _uploadToS3(buffer, sandboxId, contentType = 'image/jpeg') {
+    if (!API_KEY || !sandboxId) {
+      throw new Error('API_KEY and sandboxId required for S3 upload');
+    }
+
+    // Get presigned URL from API (30s timeout)
+    const response = await fetch(`${API_ROOT}/api/v7/runner/upload-url`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        apiKey: API_KEY,
+        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, uploaded via S3) ──────────────
+
+  async _captureScreenshot() {
+    const { screen } = getNut();
+    const sharp = require('sharp');
+
+    // Capture screen via nut-js with timeout — screen.grab() can hang if display is unavailable
+    const image = await Promise.race([
+      screen.grab(),
+      new Promise((_, reject) =>
+        setTimeout(() => reject(new Error(
+          'Screenshot capture timed out after 15s — display may be unavailable'
+        )), 15000)
+      ),
+    ]);
+
+    // image.data is raw RGBA pixel buffer, image.width/height are physical pixels
+    const physicalWidth = image.width;
+    const physicalHeight = image.height;
+
+    // Get logical screen size for Retina handling
+    const logicalWidth = await screen.width();
+    const logicalHeight = await screen.height();
+
+    // Create sharp pipeline
+    let pipeline = sharp(Buffer.from(image.data), {
+      raw: {
+        width: physicalWidth,
+        height: physicalHeight,
+        channels: 4,
+      },
+    });
+
+    // Resize from physical to logical pixels if needed (Retina displays)
+    if (physicalWidth !== logicalWidth || physicalHeight !== logicalHeight) {
+      pipeline = pipeline.resize(logicalWidth, logicalHeight);
+    }
+
+    // Encode as lossless PNG with no compression
+    const buffer = await pipeline.png({ compressionLevel: 0 }).toBuffer();
+
+    return buffer.toString('base64');
+  }
+
+  // ── 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,
+      };
+    }
+  }
+
+  // NOTE: _captureScreenshot is defined above (with Retina handling)
+
+  // ── Cleanup ────────────────────────────────────────────────────────
+
+  cleanup() {
+    this._shell.cleanup();
+  }
+}
+
+module.exports = { Automation };