copilot-liku-cli 0.0.4 → 0.0.8

package/src/main/system-automation.js

@@ -26,8 +26,40 @@ const ACTION_TYPES = {
   // Semantic element-based actions (preferred - more reliable)
   CLICK_ELEMENT: 'click_element',   // Click element found by text/name
   FIND_ELEMENT: 'find_element',     // Find element and return its info
+  // Pattern-first UIA actions (Phase 3 — no mouse injection needed)
+  SET_VALUE: 'set_value',           // Set value via ValuePattern
+  SCROLL_ELEMENT: 'scroll_element', // Scroll via ScrollPattern + mouse wheel fallback
+  EXPAND_ELEMENT: 'expand_element', // Expand via ExpandCollapsePattern
+  COLLAPSE_ELEMENT: 'collapse_element', // Collapse via ExpandCollapsePattern
+  GET_TEXT: 'get_text',             // Read text via TextPattern/ValuePattern/Name
+  // Direct command execution (most reliable for terminal operations)
+  RUN_COMMAND: 'run_command',       // Run shell command directly
+  FOCUS_WINDOW: 'focus_window',     // Focus a specific window
+  BRING_WINDOW_TO_FRONT: 'bring_window_to_front',
+  SEND_WINDOW_TO_BACK: 'send_window_to_back',
+  MINIMIZE_WINDOW: 'minimize_window',
+  RESTORE_WINDOW: 'restore_window',
 };
 
+// Dangerous command patterns that require confirmation
+const DANGEROUS_COMMAND_PATTERNS = [
+  // Destructive file operations
+  /\b(rm|del|erase|rmdir|rd)\s+(-[rf]+|\/[sq]+|\*)/i,
+  /Remove-Item.*-Recurse.*-Force/i,
+  /\bformat\s+[a-z]:/i,  // Match "format C:" but not "Format-Table"
+  // System modification
+  /\b(shutdown|restart|reboot)\b/i,
+  /\breg\s+(delete|add)\b/i,
+  /\bnet\s+(user|localgroup)\b/i,
+  // Elevated operations
+  /\b(sudo|runas)\b/i,
+  /Start-Process.*-Verb\s+RunAs/i,
+  /Set-ExecutionPolicy/i,
+  /Stop-Process.*-Force/i,
+  // Dangerous downloads
+  /\b(curl|wget|Invoke-WebRequest|iwr|irm)\b.*\|\s*(bash|sh|iex|Invoke-Expression)/i,
+];
+
 // Key mappings for special keys
 const SPECIAL_KEYS = {
   'enter': '{ENTER}',
@@ -204,12 +236,28 @@ public class ClickThrough {
 
     [DllImport("user32.dll")]
     public static extern int GetWindowLong(IntPtr hWnd, int nIndex);
+    
+    [DllImport("user32.dll")]
+    public static extern bool IsIconic(IntPtr hWnd);
+    
+    [DllImport("user32.dll")]
+    public static extern bool ShowWindow(IntPtr hWnd, int nCmdShow);
+
+    [DllImport("user32.dll", SetLastError = true)]
+    public static extern bool SystemParametersInfo(uint uiAction, uint uiParam, IntPtr pvParam, uint fWinIni);
+
+    [DllImport("user32.dll")]
+    public static extern void SwitchToThisWindow(IntPtr hWnd, bool fAltTab);
 
     public const int GWL_EXSTYLE = -20;
     public const int WS_EX_TRANSPARENT = 0x20;
     public const int WS_EX_LAYERED = 0x80000;
     public const int WS_EX_TOOLWINDOW = 0x80;
     public const uint GA_ROOT = 2;
+    public const int SW_RESTORE = 9;
+    public const uint SPI_GETFOREGROUNDLOCKTIMEOUT = 0x2000;
+    public const uint SPI_SETFOREGROUNDLOCKTIMEOUT = 0x2001;
+    public const uint SPIF_SENDCHANGE = 0x02;
 
     [DllImport("user32.dll", CharSet = CharSet.Auto)]
     public static extern int GetClassName(IntPtr hWnd, StringBuilder lpClassName, int nMaxCount);
@@ -218,19 +266,50 @@ public class ClickThrough {
     public static extern int GetWindowText(IntPtr hWnd, StringBuilder lpString, int nMaxCount);
 
     public static void ForceForeground(IntPtr hwnd) {
-        // Get the currently active window
+        if (hwnd == IntPtr.Zero) return;
+        
+        // Restore if minimized
+        if (IsIconic(hwnd)) {
+            ShowWindow(hwnd, SW_RESTORE);
+            System.Threading.Thread.Sleep(50);
+        }
+        
         IntPtr foreground = GetForegroundWindow();
-        uint foregroundThread = GetWindowThreadProcessId(foreground, IntPtr.Zero);
-        uint currentThread = GetCurrentThreadId();
+        if (foreground == hwnd) return;
+        
+        // 1. Unlock Focus Stealing
+        int originalTimeout = 0;
+        IntPtr timeoutPtr = Marshal.AllocHGlobal(4);
+        try {
+            SystemParametersInfo(SPI_GETFOREGROUNDLOCKTIMEOUT, 0, timeoutPtr, 0);
+            originalTimeout = Marshal.ReadInt32(timeoutPtr);
+            SystemParametersInfo(SPI_SETFOREGROUNDLOCKTIMEOUT, 0, IntPtr.Zero, SPIF_SENDCHANGE);
+        } catch {}
 
-        // Attach our thread to the currently active window thread
-        // This allows SetForegroundWindow to work
-        if (foregroundThread != currentThread) {
-            AttachThreadInput(currentThread, foregroundThread, true);
-            SetForegroundWindow(hwnd);
-            AttachThreadInput(currentThread, foregroundThread, false);
-        } else {
-            SetForegroundWindow(hwnd);
+        try {
+            uint foregroundThread = GetWindowThreadProcessId(foreground, IntPtr.Zero);
+            uint currentThread = GetCurrentThreadId();
+            bool success = false;
+
+            // 2. AttachThreadInput + SetForegroundWindow
+            if (foregroundThread != currentThread) {
+                AttachThreadInput(currentThread, foregroundThread, true);
+                success = SetForegroundWindow(hwnd);
+                AttachThreadInput(currentThread, foregroundThread, false);
+            } else {
+                success = SetForegroundWindow(hwnd);
+            }
+            
+            // 3. Last Resort: SwitchToThisWindow
+            if (!success) {
+                SwitchToThisWindow(hwnd, true);
+            }
+        } finally {
+            try {
+                Marshal.WriteInt32(timeoutPtr, originalTimeout);
+                SystemParametersInfo(SPI_SETFOREGROUNDLOCKTIMEOUT, 0, timeoutPtr, SPIF_SENDCHANGE);
+            } catch {}
+            Marshal.FreeHGlobal(timeoutPtr);
         }
     }
 
@@ -318,6 +397,225 @@ public class ClickThrough {
   console.log(`[AUTOMATION] ${button} click at (${x}, ${y}) (click-through enabled)`);
 }
 
+/**
+ * Focus a specific window by its handle
+ */
+async function focusWindow(hwnd) {
+    if (!hwnd) return;
+    
+    const script = `
+Add-Type -TypeDefinition @"
+using System;
+using System.Runtime.InteropServices;
+
+public class WindowFocus {
+    [DllImport("user32.dll")]
+    public static extern bool SetForegroundWindow(IntPtr hWnd);
+    [DllImport("user32.dll")]
+    public static extern bool AttachThreadInput(uint idAttach, uint idAttachTo, bool fAttach);
+    [DllImport("user32.dll")]
+    public static extern uint GetWindowThreadProcessId(IntPtr hWnd, IntPtr lpdwProcessId);
+    [DllImport("kernel32.dll")]
+    public static extern uint GetCurrentThreadId();
+    [DllImport("user32.dll")]
+    public static extern IntPtr GetForegroundWindow();
+    [DllImport("user32.dll")]
+    public static extern bool IsIconic(IntPtr hWnd);
+    [DllImport("user32.dll")]
+    public static extern bool ShowWindow(IntPtr hWnd, int nCmdShow);
+    [DllImport("user32.dll", SetLastError = true)]
+    public static extern bool SystemParametersInfo(uint uiAction, uint uiParam, IntPtr pvParam, uint fWinIni);
+    [DllImport("user32.dll")]
+    public static extern void SwitchToThisWindow(IntPtr hWnd, bool fAltTab);
+    
+    public const int SW_RESTORE = 9;
+    public const uint SPI_GETFOREGROUNDLOCKTIMEOUT = 0x2000;
+    public const uint SPI_SETFOREGROUNDLOCKTIMEOUT = 0x2001;
+    public const uint SPIF_SENDCHANGE = 0x02;
+
+    public static void Focus(IntPtr hwnd) {
+        if (hwnd == IntPtr.Zero) return;
+        
+        // Restore if minimized
+        if (IsIconic(hwnd)) {
+            ShowWindow(hwnd, SW_RESTORE);
+            System.Threading.Thread.Sleep(100);
+        }
+
+        IntPtr foreground = GetForegroundWindow();
+        if (foreground == hwnd) return;
+        
+        // 1. Try to unlock Focus Stealing capability
+        int originalTimeout = 0;
+        IntPtr timeoutPtr = Marshal.AllocHGlobal(4);
+        try {
+            SystemParametersInfo(SPI_GETFOREGROUNDLOCKTIMEOUT, 0, timeoutPtr, 0);
+            originalTimeout = Marshal.ReadInt32(timeoutPtr);
+            
+            // Set timeout to 0 to bypass lock
+            SystemParametersInfo(SPI_SETFOREGROUNDLOCKTIMEOUT, 0, IntPtr.Zero, SPIF_SENDCHANGE);
+        } catch {}
+
+        try {
+            uint foregroundThread = GetWindowThreadProcessId(foreground, IntPtr.Zero);
+            uint currentThread = GetCurrentThreadId();
+            bool success = false;
+
+            // 2. Try AttachThreadInput + SetForegroundWindow
+            if (foregroundThread != currentThread) {
+                AttachThreadInput(currentThread, foregroundThread, true);
+                success = SetForegroundWindow(hwnd);
+                AttachThreadInput(currentThread, foregroundThread, false);
+            } else {
+                success = SetForegroundWindow(hwnd);
+            }
+            
+            // 3. Last Resort: SwitchToThisWindow
+            if (!success) {
+                SwitchToThisWindow(hwnd, true);
+            }
+        } finally {
+            // Restore original timeout
+            try {
+                Marshal.WriteInt32(timeoutPtr, originalTimeout);
+                SystemParametersInfo(SPI_SETFOREGROUNDLOCKTIMEOUT, 0, timeoutPtr, SPIF_SENDCHANGE);
+            } catch {}
+            Marshal.FreeHGlobal(timeoutPtr);
+        }
+    }
+}
+"@
+[WindowFocus]::Focus([IntPtr]::new(${hwnd}))
+`;
+    await executePowerShell(script);
+    console.log(`[AUTOMATION] Focused window handle: ${hwnd}`);
+}
+
+/**
+ * Resolve window handle from action payload (handle, title, process, class)
+ */
+async function resolveWindowHandle(action = {}) {
+  const directHandle = action.hwnd ?? action.windowHandle;
+  if (directHandle !== undefined && directHandle !== null && Number.isFinite(Number(directHandle))) {
+    return Number(directHandle);
+  }
+
+  const title = (action.title || '').replace(/'/g, "''");
+  const processName = (action.processName || '').replace(/'/g, "''");
+  const className = (action.className || '').replace(/'/g, "''");
+
+  if (!title && !processName && !className) {
+    return null;
+  }
+
+  const script = `
+Add-Type @'
+using System;
+using System.Collections.Generic;
+using System.Runtime.InteropServices;
+using System.Text;
+
+public class WindowResolver {
+    [DllImport("user32.dll")] public static extern bool EnumWindows(EnumWindowsProc cb, IntPtr lParam);
+    [DllImport("user32.dll")] public static extern bool IsWindowVisible(IntPtr hWnd);
+    [DllImport("user32.dll")] public static extern int GetWindowText(IntPtr hWnd, StringBuilder text, int count);
+    [DllImport("user32.dll")] public static extern int GetClassName(IntPtr hWnd, StringBuilder name, int count);
+    [DllImport("user32.dll")] public static extern uint GetWindowThreadProcessId(IntPtr hWnd, out uint pid);
+    public delegate bool EnumWindowsProc(IntPtr hWnd, IntPtr lParam);
+    public static List<IntPtr> windows = new List<IntPtr>();
+    public static void Find() {
+        windows.Clear();
+        EnumWindows((h, l) => { if (IsWindowVisible(h)) windows.Add(h); return true; }, IntPtr.Zero);
+    }
+}
+'@
+
+$title = '${title}'.ToLower()
+$proc = '${processName}'
+$class = '${className}'.ToLower()
+
+[WindowResolver]::Find()
+foreach ($hwnd in [WindowResolver]::windows) {
+    $titleSB = New-Object System.Text.StringBuilder 256
+    $classSB = New-Object System.Text.StringBuilder 256
+    [void][WindowResolver]::GetWindowText($hwnd, $titleSB, 256)
+    [void][WindowResolver]::GetClassName($hwnd, $classSB, 256)
+
+    $t = $titleSB.ToString()
+    if ([string]::IsNullOrWhiteSpace($t)) { continue }
+    $c = $classSB.ToString()
+
+    if ($title -and -not $t.ToLower().Contains($title)) { continue }
+    if ($class -and -not $c.ToLower().Contains($class)) { continue }
+
+    if ($proc) {
+        $pid = 0
+        [void][WindowResolver]::GetWindowThreadProcessId($hwnd, [ref]$pid)
+        $p = Get-Process -Id $pid -ErrorAction SilentlyContinue
+        if (-not $p -or $p.ProcessName -ne $proc) { continue }
+    }
+
+    $hwnd.ToInt64()
+    exit
+}
+`;
+
+  try {
+    const output = await executePowerShell(script);
+    const parsed = Number(output);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+async function minimizeWindow(hwnd) {
+  const script = `
+Add-Type @'
+using System;
+using System.Runtime.InteropServices;
+public class WinMin {
+  [DllImport("user32.dll")] public static extern bool ShowWindow(IntPtr hWnd, int nCmdShow);
+}
+'@
+[WinMin]::ShowWindow([IntPtr]::new(${hwnd}), 6) | Out-Null
+`;
+  await executePowerShell(script);
+}
+
+async function restoreWindow(hwnd) {
+  const script = `
+Add-Type @'
+using System;
+using System.Runtime.InteropServices;
+public class WinRestore {
+  [DllImport("user32.dll")] public static extern bool ShowWindow(IntPtr hWnd, int nCmdShow);
+}
+'@
+[WinRestore]::ShowWindow([IntPtr]::new(${hwnd}), 9) | Out-Null
+`;
+  await executePowerShell(script);
+}
+
+async function sendWindowToBack(hwnd) {
+  const script = `
+Add-Type @'
+using System;
+using System.Runtime.InteropServices;
+public class WinZ {
+  [DllImport("user32.dll")] public static extern bool SetWindowPos(IntPtr hWnd, IntPtr hWndInsertAfter, int X, int Y, int cx, int cy, uint uFlags);
+  public static readonly IntPtr HWND_BOTTOM = new IntPtr(1);
+  public const uint SWP_NOSIZE = 0x0001;
+  public const uint SWP_NOMOVE = 0x0002;
+  public const uint SWP_NOACTIVATE = 0x0010;
+  public const uint SWP_NOOWNERZORDER = 0x0200;
+}
+'@
+[WinZ]::SetWindowPos([IntPtr]::new(${hwnd}), [WinZ]::HWND_BOTTOM, 0, 0, 0, 0, [WinZ]::SWP_NOSIZE -bor [WinZ]::SWP_NOMOVE -bor [WinZ]::SWP_NOACTIVATE -bor [WinZ]::SWP_NOOWNERZORDER) | Out-Null
+`;
+  await executePowerShell(script);
+}
+
 /**
  * Double click at coordinates - FIXED for transparent overlay click-through
  */
@@ -788,6 +1086,129 @@ function sleep(ms) {
   return new Promise(resolve => setTimeout(resolve, ms));
 }
 
+// ===== DIRECT COMMAND EXECUTION =====
+// Most reliable for terminal operations - runs shell commands directly
+
+/**
+ * Truncate output for token efficiency while preserving useful info
+ */
+function truncateOutput(output, maxLen = 4000) {
+  if (!output || output.length <= maxLen) return output;
+  
+  const headLen = Math.floor(maxLen * 0.4);
+  const tailLen = Math.floor(maxLen * 0.4);
+  
+  return output.slice(0, headLen) + 
+    `\n\n... [${output.length - headLen - tailLen} characters truncated] ...\n\n` +
+    output.slice(-tailLen);
+}
+
+/**
+ * Check if a command is dangerous and requires confirmation
+ */
+function isCommandDangerous(command) {
+  return DANGEROUS_COMMAND_PATTERNS.some(pattern => pattern.test(command));
+}
+
+/**
+ * Execute a shell command directly
+ * This is the MOST RELIABLE way to run terminal commands!
+ */
+async function executeCommand(command, options = {}) {
+  const { 
+    cwd = os.homedir(), 
+    shell = 'powershell', 
+    timeout = 30000,
+    maxOutput = 50000 
+  } = options;
+  
+  console.log(`[AUTOMATION] Executing command: ${command}`);
+  console.log(`[AUTOMATION] Working directory: ${cwd}, Shell: ${shell}`);
+  
+  return new Promise((resolve) => {
+    const startTime = Date.now();
+    
+    // Determine shell executable
+    let shellExe;
+    let shellArgs;
+    if (shell === 'cmd') {
+      shellExe = 'cmd.exe';
+      shellArgs = ['/c', command];
+    } else if (shell === 'bash') {
+      shellExe = 'bash';
+      shellArgs = ['-c', command];
+    } else {
+      // Default: PowerShell
+      shellExe = 'powershell.exe';
+      shellArgs = ['-NoProfile', '-Command', command];
+    }
+    
+    const { spawn } = require('child_process');
+    const child = spawn(shellExe, shellArgs, {
+      cwd: cwd || os.homedir(),
+      timeout: Math.min(timeout, 120000),
+      shell: false,
+      windowsHide: true
+    });
+    
+    let stdout = '';
+    let stderr = '';
+    let killed = false;
+    
+    // Set timeout
+    const timer = setTimeout(() => {
+      killed = true;
+      child.kill('SIGTERM');
+    }, Math.min(timeout, 120000));
+    
+    child.stdout.on('data', (data) => {
+      stdout += data.toString();
+      // Prevent memory issues
+      if (stdout.length > maxOutput * 2) {
+        stdout = stdout.slice(-maxOutput);
+      }
+    });
+    
+    child.stderr.on('data', (data) => {
+      stderr += data.toString();
+      if (stderr.length > maxOutput) {
+        stderr = stderr.slice(-maxOutput);
+      }
+    });
+    
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      const duration = Date.now() - startTime;
+      
+      const result = {
+        success: code === 0 && !killed,
+        stdout: truncateOutput(stdout.trim(), 4000),
+        stderr: stderr.trim().slice(0, 1000),
+        exitCode: killed ? -1 : (code || 0),
+        duration,
+        truncated: stdout.length > 4000,
+        originalLength: stdout.length,
+        timedOut: killed
+      };
+      
+      console.log(`[AUTOMATION] Command completed: exit=${result.exitCode}, duration=${duration}ms, output=${result.stdout.length} chars`);
+      resolve(result);
+    });
+    
+    child.on('error', (err) => {
+      clearTimeout(timer);
+      resolve({
+        success: false,
+        stdout: '',
+        stderr: err.message,
+        exitCode: -1,
+        duration: Date.now() - startTime,
+        error: err.message
+      });
+    });
+  });
+}
+
 // ===== SEMANTIC ELEMENT-BASED AUTOMATION =====
 // More reliable than coordinate-based - finds elements by their properties
 
@@ -813,9 +1234,12 @@ function executePowerShellScript(scriptContent, timeoutMs = 10000) {
       try { fs.unlinkSync(scriptFile); } catch (e) {}
       
       if (error) {
-        resolve({ error: error.message, stderr });
+        console.error(`[AUTOMATION] Script failed: ${error.message}`);
+        console.error(`[AUTOMATION] STDERR: ${stderr}`);
+        // Return structured error instead of failing promise
+        resolve({ error: error.message, stderr, stdout, failed: true });
       } else {
-        resolve({ stdout: stdout.trim(), stderr });
+        resolve({ stdout: stdout.trim(), stderr, success: true });
       }
     });
   });
@@ -835,67 +1259,151 @@ async function findElementByText(searchText, options = {}) {
   const { controlType = '', exact = false } = options;
   
   const psScript = `
-Add-Type -AssemblyName UIAutomationClient
-Add-Type -AssemblyName UIAutomationTypes
-
-function Find-ElementByText {
-    param(
-        [string]$SearchText,
-        [string]$ControlType = "",
-        [bool]$ExactMatch = $false
-    )
+$ErrorActionPreference = 'Stop'
+$ProgressPreference = 'SilentlyContinue'
+
+try {
+    Add-Type -AssemblyName UIAutomationClient
+    Add-Type -AssemblyName UIAutomationTypes
+} catch {
+    Write-Output '{"error": "Failed to load UIAutomation assemblies"}'
+    exit 0
+}
+
+function Find-InElement {
+    param($Root, $Text, $IsExact, $CtrlType)
     
-    $root = [System.Windows.Automation.AutomationElement]::RootElement
     $condition = [System.Windows.Automation.Condition]::TrueCondition
     
-    # Find all elements
-    $elements = $root.FindAll([System.Windows.Automation.TreeScope]::Descendants, $condition)
-    
-    $results = @()
-    foreach ($el in $elements) {
+    # Use TreeWalker for lighter iteration than FindAll if possible, but FindAll is easier to robustly code
+    # Optimization: Filter by ControlType if provided to reduce elements
+    if ($CtrlType) {
+        # Check if known type to map to Condition
+        # Skipping for now to keep string matching simple
+    }
+
+    try {
+        $elements = $Root.FindAll([System.Windows.Automation.TreeScope]::Descendants, $condition)
+        
+        foreach ($el in $elements) {
+            try {
+                if (-not $el.Current.IsEnabled -or $el.Current.IsOffscreen) { continue }
+                
+                $name = $el.Current.Name
+                if ([string]::IsNullOrEmpty($name)) { continue }
+                
+                $match = $false
+                if ($IsExact) { $match = ($name -eq $Text) }
+                else { $match = ($name -like "*$Text*") }
+                
+                if ($match) {
+                     # Optional ControlType check
+                     if ($CtrlType -and $el.Current.ControlType.ProgrammaticName -notlike "*$CtrlType*") { continue }
+                     
+                     return $el
+                }
+            } catch {}
+        }
+    } catch {}
+    return $null
+}
+
+function Get-ElementData {
+    param($el)
+    try {
+        $rect = $el.Current.BoundingRectangle
+        if ($rect.Width -le 0 -or $rect.Height -le 0) { return $null }
+        
+        # Walk up to find the parent Window handle
+        $handle = 0
         try {
-            $name = $el.Current.Name
-            $ctrlType = $el.Current.ControlType.ProgrammaticName
-            
-            # Check text match
-            $textMatch = $false
-            if ($ExactMatch) {
-                $textMatch = ($name -eq $SearchText)
+            if ($el.Current.NativeWindowHandle -ne 0) {
+                $handle = $el.Current.NativeWindowHandle
             } else {
-                $textMatch = ($name -like "*$SearchText*")
-            }
-            
-            if (-not $textMatch) { continue }
-            
-            # Check control type filter
-            if ($ControlType -ne "" -and $ctrlType -notlike "*$ControlType*") { continue }
-            
-            $rect = $el.Current.BoundingRectangle
-            if ($rect.Width -le 0 -or $rect.Height -le 0) { continue }
-            
-            $results += @{
-                Name = $name
-                ControlType = $ctrlType
-                AutomationId = $el.Current.AutomationId
-                ClassName = $el.Current.ClassName
-                Bounds = @{
-                    X = [int]$rect.X
-                    Y = [int]$rect.Y
-                    Width = [int]$rect.Width
-                    Height = [int]$rect.Height
-                    CenterX = [int]($rect.X + $rect.Width / 2)
-                    CenterY = [int]($rect.Y + $rect.Height / 2)
+                $walker = [System.Windows.Automation.TreeWalker]::ControlViewWalker
+                $parent = $walker.GetParent($el)
+                $maxSteps = 10
+                while ($parent -and $maxSteps -gt 0) {
+                   if ($parent.Current.NativeWindowHandle -ne 0) {
+                       $handle = $parent.Current.NativeWindowHandle
+                       break
+                   }
+                   $parent = $walker.GetParent($parent)
+                   $maxSteps--
                 }
-                IsEnabled = $el.Current.IsEnabled
             }
         } catch {}
+
+        return @{
+            Name = $el.Current.Name
+            ControlType = $el.Current.ControlType.ProgrammaticName
+            AutomationId = $el.Current.AutomationId
+            WindowHandle = $handle
+            Bounds = @{
+                X = [int]$rect.X
+                Y = [int]$rect.Y
+                Width = [int]$rect.Width
+                Height = [int]$rect.Height
+                CenterX = [int]($rect.X + $rect.Width / 2)
+                CenterY = [int]($rect.Y + $rect.Height / 2)
+            }
+        }
+    } catch { return $null }
+}
+
+try {
+    $searchText = "${searchText.replace(/"/g, '`"')}"
+    $controlType = "${controlType}"
+    $exact = $${exact}
+    
+    # 1. Search Active Window (Fast Path)
+    # Using System.Windows.Forms to get active window handle is unreliable in pure scripts sometimes
+    # Use Automation Root -> First child focus? No, FocusElement.
+    
+    try {
+       $focused = [System.Windows.Automation.AutomationElement]::FocusedElement
+       if ($focused) {
+            # Walk up to get the window
+            $walker = [System.Windows.Automation.TreeWalker]::ControlViewWalker
+            $node = $focused
+            while ($node -and $node.Current.ControlType.Id -ne [System.Windows.Automation.ControlType]::Window.Id) {
+                try { $parent = $walker.GetParent($node); $node = $parent } catch { break }
+            }
+            if ($node) {
+                # Found active window, search it
+                $found = Find-InElement -Root $node -Text $searchText -IsExact $exact -CtrlType $controlType
+                if ($found) {
+                    $data = Get-ElementData -el $found
+                    if ($data) {
+                        $data | ConvertTo-Json -Compress
+                        exit 0
+                    }
+                }
+            }
+       }
+    } catch {}
+
+    # 2. Iterate Top Level Windows (Robust Path)
+    $root = [System.Windows.Automation.AutomationElement]::RootElement
+    $winCondition = New-Object System.Windows.Automation.PropertyCondition([System.Windows.Automation.AutomationElement]::ControlTypeProperty, [System.Windows.Automation.ControlType]::Window)
+    $windows = $root.FindAll([System.Windows.Automation.TreeScope]::Children, $winCondition)
+    
+    foreach ($win in $windows) {
+        $found = Find-InElement -Root $win -Text $searchText -IsExact $exact -CtrlType $controlType
+        if ($found) {
+            $data = Get-ElementData -el $found
+            if ($data) {
+                $data | ConvertTo-Json -Compress
+                exit 0
+            }
+        }
     }
     
-    return $results
-}
+    Write-Output '{"error": "Element not found"}'
 
-$results = Find-ElementByText -SearchText "${searchText.replace(/"/g, '`"')}" -ControlType "${controlType}" -ExactMatch $${exact}
-$results | ConvertTo-Json -Depth 5
+} catch {
+    Write-Output "{\\"error\\": \\"$($_.Exception.Message.Replace('"', '\\"'))\\"}"
+}
 `;
 
   const result = await executePowerShellScript(psScript, 15000);
@@ -905,7 +1413,13 @@ $results | ConvertTo-Json -Depth 5
   }
   
   try {
-    let elements = JSON.parse(result.stdout || '[]');
+    let elements = JSON.parse(result.stdout.trim() || '[]');
+    
+    // Check for error object from PowerShell
+    if (!Array.isArray(elements) && elements.error) {
+        return { success: false, error: elements.error };
+    }
+
     if (!Array.isArray(elements)) {
       elements = elements ? [elements] : [];
     }
@@ -954,6 +1468,13 @@ async function clickElementByText(searchText, options = {}) {
   
   console.log(`[AUTOMATION] Found "${el.Name}" at center (${CenterX}, ${CenterY})`);
   
+  // Ensure the window containing the element is focused (fixes obscured window issues)
+  if (el.WindowHandle && el.WindowHandle !== 0) {
+    console.log(`[AUTOMATION] Auto-focusing window handle: ${el.WindowHandle}`);
+    await focusWindow(el.WindowHandle);
+    await sleep(150);
+  }
+  
   // Use UI Automation Invoke pattern for buttons (more reliable than mouse simulation)
   if (options.useInvoke !== false && el.ControlType && el.ControlType.includes('Button')) {
     console.log(`[AUTOMATION] Using Invoke pattern for button`);
@@ -984,70 +1505,20 @@ async function invokeElementByText(searchText, options = {}) {
   const exact = options.exact === true;
   
   const psScript = `
-Add-Type -AssemblyName UIAutomationClient
-Add-Type -AssemblyName UIAutomationTypes
+$ErrorActionPreference = 'Stop'
+$ProgressPreference = 'SilentlyContinue'
 
-$searchText = "${searchText.replace(/"/g, '`"')}"
-$controlType = "${controlType}"
-$exactMatch = $${exact}
-
-$root = [System.Windows.Automation.AutomationElement]::RootElement
-$condition = [System.Windows.Automation.Condition]::TrueCondition
-$elements = $root.FindAll([System.Windows.Automation.TreeScope]::Descendants, $condition)
-
-$found = $null
-foreach ($el in $elements) {
-    try {
-        $name = $el.Current.Name
-        $ctrlType = $el.Current.ControlType.ProgrammaticName
-        
-        $textMatch = $false
-        if ($exactMatch) {
-            $textMatch = ($name -eq $searchText)
-        } else {
-            $textMatch = ($name -like "*$searchText*")
-        }
-        
-        if (-not $textMatch) { continue }
-        if ($controlType -ne "" -and $ctrlType -notlike "*$controlType*") { continue }
-        
-        $rect = $el.Current.BoundingRectangle
-        if ($rect.Width -le 0 -or $rect.Height -le 0) { continue }
-        
-        $found = $el
-        break
-    } catch {}
-}
-
-if ($found -eq $null) {
-    Write-Output '{"success": false, "error": "Element not found"}'
-    exit
+try {
+    Add-Type -AssemblyName UIAutomationClient
+    Add-Type -AssemblyName UIAutomationTypes
+} catch {
+    Write-Output '{"error": "Failed to load UIAutomation assemblies"}'
+    exit 0
 }
 
-# Try Invoke pattern first
+# Define ClickHelper globally to avoid type re-definition errors and syntax issues
 try {
-    $invokePattern = $found.GetCurrentPattern([System.Windows.Automation.InvokePattern]::Pattern)
-    $invokePattern.Invoke()
-    $name = $found.Current.Name
-    $rect = $found.Current.BoundingRectangle
-    Write-Output "{\\"success\\": true, \\"method\\": \\"Invoke\\", \\"name\\": \\"$name\\", \\"x\\": $([int]($rect.X + $rect.Width/2)), \\"y\\": $([int]($rect.Y + $rect.Height/2))}"
-} catch {
-    # Try Toggle pattern for toggle buttons
-    try {
-        $togglePattern = $found.GetCurrentPattern([System.Windows.Automation.TogglePattern]::Pattern)
-        $togglePattern.Toggle()
-        $name = $found.Current.Name
-        Write-Output "{\\"success\\": true, \\"method\\": \\"Toggle\\", \\"name\\": \\"$name\\"}"
-    } catch {
-        # Try SetFocus and send click
-        try {
-            $found.SetFocus()
-            Start-Sleep -Milliseconds 100
-            $rect = $found.Current.BoundingRectangle
-            $x = [int]($rect.X + $rect.Width / 2)
-            $y = [int]($rect.Y + $rect.Height / 2)
-            
-            Add-Type -TypeDefinition @'
+Add-Type -TypeDefinition @'
 using System;
 using System.Runtime.InteropServices;
 public class ClickHelper {
@@ -1062,13 +1533,124 @@ public class ClickHelper {
     }
 }
 '@
-            [ClickHelper]::Click($x, $y)
-            $name = $found.Current.Name
-            Write-Output "{\\"success\\": true, \\"method\\": \\"FocusClick\\", \\"name\\": \\"$name\\", \\"x\\": $x, \\"y\\": $y}"
-        } catch {
-            Write-Output "{\\"success\\": false, \\"error\\": \\"$($_.Exception.Message)\\"}"
+} catch {}
+
+function Invoke-FoundElement {
+    param($element)
+    try {
+        # Try Invoke pattern first
+        if ($element.GetCurrentPattern([System.Windows.Automation.InvokePattern]::Pattern)) {
+            $invokePattern = $element.GetCurrentPattern([System.Windows.Automation.InvokePattern]::Pattern)
+            $invokePattern.Invoke()
+            $name = $element.Current.Name
+            $rect = $element.Current.BoundingRectangle
+            Write-Output "{\\"success\\": true, \\"method\\": \\"Invoke\\", \\"name\\": \\"$name\\", \\"x\\": $([int]($rect.X + $rect.Width/2)), \\"y\\": $([int]($rect.Y + $rect.Height/2))}"
+            return $true
+        }
+    } catch {}
+
+    try {
+        # Try Toggle pattern
+        if ($element.GetCurrentPattern([System.Windows.Automation.TogglePattern]::Pattern)) {
+            $togglePattern = $element.GetCurrentPattern([System.Windows.Automation.TogglePattern]::Pattern)
+            $togglePattern.Toggle()
+            $name = $element.Current.Name
+            Write-Output "{\\"success\\": true, \\"method\\": \\"Toggle\\", \\"name\\": \\"$name\\"}"
+            return $true
+        }
+    } catch {}
+    
+    # Try Select (if Item)
+    try {
+        if ($element.GetCurrentPattern([System.Windows.Automation.SelectionItemPattern]::Pattern)) {
+            $selPattern = $element.GetCurrentPattern([System.Windows.Automation.SelectionItemPattern]::Pattern)
+            $selPattern.Select()
+            $name = $element.Current.Name
+            Write-Output "{\\"success\\": true, \\"method\\": \\"Select\\", \\"name\\": \\"$name\\"}"
+            return $true
         }
+    } catch {}
+
+    # Fallback to Focus + Click
+    try {
+        $element.SetFocus()
+        Start-Sleep -Milliseconds 100
+        $rect = $element.Current.BoundingRectangle
+        $x = [int]($rect.X + $rect.Width / 2)
+        $y = [int]($rect.Y + $rect.Height / 2)
+        
+        [ClickHelper]::Click($x, $y)
+        $name = $element.Current.Name
+        Write-Output "{\\"success\\": true, \\"method\\": \\"FocusClick\\", \\"name\\": \\"$name\\", \\"x\\": $x, \\"y\\": $y}"
+        return $true
+    } catch {
+        return $false
+    }
+}
+
+function Find-And-Invoke {
+    param($Root, $Text, $IsExact, $CtrlType)
+    
+    $condition = [System.Windows.Automation.Condition]::TrueCondition
+    try {
+        $elements = $Root.FindAll([System.Windows.Automation.TreeScope]::Descendants, $condition)
+        
+        foreach ($el in $elements) {
+            try {
+                if (-not $el.Current.IsEnabled -or $el.Current.IsOffscreen) { continue }
+                
+                $name = $el.Current.Name
+                if ([string]::IsNullOrEmpty($name)) { continue }
+                
+                $match = $false
+                if ($IsExact) { $match = ($name -eq $Text) }
+                else { $match = ($name -like "*$Text*") }
+                
+                if ($match) {
+                     if ($CtrlType -and $el.Current.ControlType.ProgrammaticName -notlike "*$CtrlType*") { continue }
+                     
+                     if (Invoke-FoundElement -element $el) {
+                         exit 0
+                     }
+                }
+            } catch {}
+        }
+    } catch {}
+}
+
+$searchText = "${searchText.replace(/"/g, '`"')}"
+$controlType = "${controlType}"
+$exact = $${exact}
+
+try {
+    # 1. Search Active Window
+    try {
+       $focused = [System.Windows.Automation.AutomationElement]::FocusedElement
+       if ($focused) {
+            $walker = [System.Windows.Automation.TreeWalker]::ControlViewWalker
+            $node = $focused
+            while ($node -and $node.Current.ControlType.Id -ne [System.Windows.Automation.ControlType]::Window.Id) {
+                try { $parent = $walker.GetParent($node); $node = $parent } catch { break }
+            }
+            if ($node) {
+                Find-And-Invoke -Root $node -Text $searchText -IsExact $exact -CtrlType $controlType
+            }
+       }
+    } catch {}
+
+    # 2. Iterate Top Level Windows
+    $root = [System.Windows.Automation.AutomationElement]::RootElement
+    $winCondition = New-Object System.Windows.Automation.PropertyCondition([System.Windows.Automation.AutomationElement]::ControlTypeProperty, [System.Windows.Automation.ControlType]::Window)
+    $windows = $root.FindAll([System.Windows.Automation.TreeScope]::Children, $winCondition)
+    
+    foreach ($win in $windows) {
+        Find-And-Invoke -Root $win -Text $searchText -IsExact $exact -CtrlType $controlType
     }
+    
+    Write-Output '{"success": false, "error": "Element not found or not interactable"}'
+
+} catch {
+    Write-Output "{\\"success\\": false, \\"error\\": \\"Script Error: $($_.Exception.Message.Replace('"', '\\"'))\\"}"
 }
 `;
 
@@ -1175,9 +1757,14 @@ async function executeAction(action) {
         break;
         
       case ACTION_TYPES.SCREENSHOT:
-        // This will be handled by the caller (main process)
+        // Scoped screenshot — caller resolves capture based on scope
         result.needsScreenshot = true;
-        result.message = 'Screenshot requested';
+        result.scope = action.scope || 'screen';         // screen | region | window | element
+        result.region = action.region || null;            // {x, y, width, height} for scope=region
+        result.hwnd = action.hwnd || null;                // window handle for scope=window
+        result.elementCriteria = action.elementCriteria || null; // {text, controlType} for scope=element
+        result.targetRegionId = action.targetRegionId || null;
+        result.message = `Screenshot requested (scope: ${result.scope})`;
         break;
       
       // Semantic element-based actions (MORE RELIABLE than coordinates)
@@ -1196,6 +1783,127 @@ async function executeAction(action) {
         });
         result = { ...result, ...findResult };
         break;
+      
+      case ACTION_TYPES.RUN_COMMAND:
+        const cmdResult = await executeCommand(action.command, {
+          cwd: action.cwd,
+          shell: action.shell || 'powershell',
+          timeout: action.timeout || 30000
+        });
+        result = { 
+          ...result, 
+          ...cmdResult,
+          command: action.command,
+          cwd: action.cwd || os.homedir()
+        };
+        result.message = cmdResult.success 
+          ? `Command completed (exit ${cmdResult.exitCode})`
+          : `Command failed: ${cmdResult.stderr || cmdResult.error}`;
+        break;
+
+      case ACTION_TYPES.FOCUS_WINDOW:
+      case ACTION_TYPES.BRING_WINDOW_TO_FRONT: {
+        const hwnd = await resolveWindowHandle(action);
+        if (!hwnd) {
+          throw new Error('Window not found. Provide hwnd/windowHandle or title/processName/className.');
+        }
+        await focusWindow(hwnd);
+        result.message = `Brought window ${hwnd} to front`;
+        break;
+      }
+
+      case ACTION_TYPES.SEND_WINDOW_TO_BACK: {
+        const hwnd = await resolveWindowHandle(action);
+        if (!hwnd) {
+          throw new Error('Window not found. Provide hwnd/windowHandle or title/processName/className.');
+        }
+        await sendWindowToBack(hwnd);
+        result.message = `Sent window ${hwnd} to back`;
+        break;
+      }
+
+      case ACTION_TYPES.MINIMIZE_WINDOW: {
+        const hwnd = await resolveWindowHandle(action);
+        if (!hwnd) {
+          throw new Error('Window not found. Provide hwnd/windowHandle or title/processName/className.');
+        }
+        await minimizeWindow(hwnd);
+        result.message = `Minimized window ${hwnd}`;
+        break;
+      }
+
+      case ACTION_TYPES.RESTORE_WINDOW: {
+        const hwnd = await resolveWindowHandle(action);
+        if (!hwnd) {
+          throw new Error('Window not found. Provide hwnd/windowHandle or title/processName/className.');
+        }
+        await restoreWindow(hwnd);
+        result.message = `Restored window ${hwnd}`;
+        break;
+      }
+
+      // ── Phase 3: Pattern-first UIA actions ──────────────────
+      case ACTION_TYPES.SET_VALUE: {
+        const uia = require('./ui-automation');
+        const svResult = await uia.setElementValue(
+          action.criteria || { text: action.text, automationId: action.automationId, controlType: action.controlType },
+          action.value
+        );
+        result = { ...result, ...svResult };
+        result.message = svResult.success
+          ? `Set value via ${svResult.method} on element`
+          : `Set value failed: ${svResult.error}`;
+        break;
+      }
+
+      case ACTION_TYPES.SCROLL_ELEMENT: {
+        const uia = require('./ui-automation');
+        const seResult = await uia.scrollElement(
+          action.criteria || { text: action.text, automationId: action.automationId, controlType: action.controlType },
+          { direction: action.direction || 'down', amount: action.amount ?? -1 }
+        );
+        result = { ...result, ...seResult };
+        result.message = seResult.success
+          ? `Scrolled ${action.direction || 'down'} via ${seResult.method}`
+          : `Scroll failed: ${seResult.error}`;
+        break;
+      }
+
+      case ACTION_TYPES.EXPAND_ELEMENT: {
+        const uia = require('./ui-automation');
+        const exResult = await uia.expandElement(
+          action.criteria || { text: action.text, automationId: action.automationId, controlType: action.controlType }
+        );
+        result = { ...result, ...exResult };
+        result.message = exResult.success
+          ? `Expanded element (${exResult.stateBefore} → ${exResult.stateAfter})`
+          : `Expand failed: ${exResult.error}`;
+        break;
+      }
+
+      case ACTION_TYPES.COLLAPSE_ELEMENT: {
+        const uia = require('./ui-automation');
+        const clResult = await uia.collapseElement(
+          action.criteria || { text: action.text, automationId: action.automationId, controlType: action.controlType }
+        );
+        result = { ...result, ...clResult };
+        result.message = clResult.success
+          ? `Collapsed element (${clResult.stateBefore} → ${clResult.stateAfter})`
+          : `Collapse failed: ${clResult.error}`;
+        break;
+      }
+
+      case ACTION_TYPES.GET_TEXT: {
+        const uia = require('./ui-automation');
+        const gtResult = await uia.getElementText(
+          action.criteria || { text: action.text, automationId: action.automationId, controlType: action.controlType }
+        );
+        result = { ...result, ...gtResult };
+        result.message = gtResult.success
+          ? `Got text via ${gtResult.method}: "${(gtResult.text || '').slice(0, 50)}"`
+          : `Get text failed: ${gtResult.error}`;
+        break;
+      }
         
       default:
         throw new Error(`Unknown action type: ${action.type}`);
@@ -1312,12 +2020,22 @@ module.exports = {
   click,
   doubleClick,
   typeText,
+  focusWindow,
   pressKey,
   scroll,
   drag,
   sleep,
   getActiveWindowTitle,
+  resolveWindowHandle,
+  minimizeWindow,
+  restoreWindow,
+  sendWindowToBack,
   // Semantic element-based automation (preferred approach)
   findElementByText,
   clickElementByText,
+  // v0.0.5: Command execution
+  DANGEROUS_COMMAND_PATTERNS,
+  isCommandDangerous,
+  truncateOutput,
+  executeCommand,
 };