@xrkseek/harness 0.4.1 → 0.4.3

package/node_modules/@xrkseek/exec-computer-use/dist/windows-uia.js

@@ -1,17 +1,79 @@
 /**
  * Windows UI Automation Provider — AX snapshot + Invoke/ValuePattern input.
- * Delivery is "uia" (not cua-driver background SPI). Opt-in via XRK_COMPUTER_USE=1.
+ * Delivery is "uia" (not cua-driver background SPI). Opt-in via XRK_COMPUTER_USE=1
+ * or Settings → Plugins → Computer use (mode=uia).
  */
 import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
 import { buildCaptureResult, DEFAULT_MAX_ELEMENTS } from "./format.js";
-import { mapKeysToSendKeys } from "./keys.js";
+import { escapeSendKeys, mapKeysToSendKeys } from "./keys.js";
 import { ComputerUseError, } from "./types.js";
-async function defaultRunPowerShell(script, signal) {
+/** UIA calls block forever when the target app stops pumping messages. */
+export const DEFAULT_POWERSHELL_TIMEOUT_MS = 25_000;
+/**
+ * Windows PowerShell 5.1 writes stdout in the OEM codepage (GBK on zh-CN), which
+ * mangles every CJK `Name` when decoded as UTF-8. The prelude pins both streams
+ * to UTF-8 so the JSON payload survives round-trip.
+ */
+const PS_PRELUDE = `
+$ErrorActionPreference = 'Stop'
+try { [Console]::OutputEncoding = [System.Text.Encoding]::UTF8 } catch {}
+try { [Console]::ErrorEncoding = [System.Text.Encoding]::UTF8 } catch {}
+Add-Type -AssemblyName UIAutomationClient
+Add-Type -AssemblyName UIAutomationTypes
+function XrkSafeInt {
+  param([double]$Value)
+  if ([double]::IsNaN($Value) -or [double]::IsInfinity($Value)) { return $null }
+  if ($Value -lt [int]::MinValue -or $Value -gt [int]::MaxValue) { return $null }
+  return [int][Math]::Round($Value, [System.MidpointRounding]::AwayFromZero)
+}
+function XrkTopWindows {
+  $cond = New-Object System.Windows.Automation.PropertyCondition(
+    [System.Windows.Automation.AutomationElement]::ControlTypeProperty,
+    [System.Windows.Automation.ControlType]::Window)
+  return [System.Windows.Automation.AutomationElement]::RootElement.FindAll(
+    [System.Windows.Automation.TreeScope]::Children, $cond)
+}
+function XrkProcName([int]$targetPid) {
+  try { return (Get-Process -Id $targetPid -ErrorAction SilentlyContinue).ProcessName } catch { return '' }
+}
+function XrkMatch([string]$hay, [string]$needle) {
+  if ([string]::IsNullOrWhiteSpace($needle)) { return $true }
+  if ([string]::IsNullOrEmpty($hay)) { return $false }
+  return ($hay.IndexOf($needle, [System.StringComparison]::OrdinalIgnoreCase) -ge 0)
+}
+`;
+/**
+ * `powershell.exe` is resolvable only when the parent process inherited the
+ * WindowsPowerShell directory on PATH. A GUI/service parent (Desktop host, a
+ * vitest worker) often has a trimmed PATH and the spawn then dies with ENOENT,
+ * which reads to the model as "computer use is broken". Windows PowerShell 5.1
+ * is deliberate: the UIAutomation client assemblies ship with it, `pwsh` 7 has
+ * them only if the optional module is installed.
+ */
+function powerShellExe() {
+    const root = process.env["SystemRoot"] ?? process.env["WINDIR"] ?? "C:\\Windows";
+    const fixed = join(root, "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+    return existsSync(fixed) ? fixed : "powershell.exe";
+}
+async function defaultRunPowerShell(script, signal, timeoutMs = DEFAULT_POWERSHELL_TIMEOUT_MS) {
     return await new Promise((resolve, reject) => {
-        const child = spawn("powershell.exe", ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-Command", script], { windowsHide: true });
+        const child = spawn(powerShellExe(), ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-Command", script], { windowsHide: true });
         let stdout = "";
         let stderr = "";
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            child.kill();
+            reject(new ComputerUseError(`UIA script timed out after ${timeoutMs}ms (target app may be busy or not pumping UIA messages)`, "COMPUTER_USE_BACKEND"));
+        }, Math.max(1_000, timeoutMs));
         const onAbort = () => {
+            if (settled)
+                return;
+            settled = true;
             child.kill();
             reject(new ComputerUseError("aborted", "COMPUTER_USE_BACKEND"));
         };
@@ -23,13 +85,22 @@ async function defaultRunPowerShell(script, signal) {
             stderr += chunk.toString("utf8");
         });
         child.on("error", (err) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
             signal?.removeEventListener("abort", onAbort);
             reject(new ComputerUseError(`powershell failed: ${err.message}`, "COMPUTER_USE_BACKEND"));
         });
         child.on("close", (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
             signal?.removeEventListener("abort", onAbort);
             if (code !== 0) {
-                reject(new ComputerUseError(`powershell exit ${code}: ${stderr.trim() || stdout.trim() || "no output"}`, "COMPUTER_USE_BACKEND"));
+                const detail = (stderr.trim() || stdout.trim() || "no output").slice(-600);
+                reject(new ComputerUseError(`powershell exit ${code}: ${detail}`, "COMPUTER_USE_BACKEND"));
                 return;
             }
             resolve(stdout.trim());
@@ -41,74 +112,162 @@ function parseJson(raw, label) {
         return JSON.parse(raw);
     }
     catch {
-        throw new ComputerUseError(`invalid ${label} JSON from UIA backend`, "COMPUTER_USE_BACKEND");
+        const snippet = raw.trim().slice(0, 240) || "(empty stdout)";
+        throw new ComputerUseError(`invalid ${label} JSON from UIA backend: ${snippet}`, "COMPUTER_USE_BACKEND");
     }
 }
-/** Compact PowerShell: walk focused (or named) window for ControlType+Name. */
-function captureScript(appFilter, maxElements) {
-    const appLit = JSON.stringify(appFilter ?? "");
-    return `
-Add-Type -AssemblyName UIAutomationClient
-Add-Type -AssemblyName UIAutomationTypes
-$ErrorActionPreference = 'Stop'
+/**
+ * Embed a string as a PowerShell single-quoted literal. `JSON.stringify` emits
+ * double quotes, where PowerShell expands `$` and a stray `'` breaks the script.
+ */
+function psStr(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}
+/**
+ * Walk one top-level window (by app/title match, else the focused window) and
+ * emit ControlType+Name elements as JSON.
+ */
+export function captureScript(options = {}) {
+    const appLit = psStr(options.app?.trim() ?? "");
+    const max = Math.max(1, Math.floor(options.maxElements ?? DEFAULT_MAX_ELEMENTS));
+    const keepOffscreen = options.includeOffscreen ? "$true" : "$false";
+    return `${PS_PRELUDE}
 $appFilter = ${appLit}
-$max = ${maxElements}
-$root = [System.Windows.Automation.AutomationElement]::FocusedElement
-if (-not $root) { $root = [System.Windows.Automation.AutomationElement]::RootElement }
+$max = ${max}
+$keepOffscreen = ${keepOffscreen}
+$maxDepth = 60
+# Cross-process UIA calls are expensive; bound the walk so a giant browser tree
+# cannot outrun the PowerShell timeout.
+$visitCap = [Math]::Max(300, $max * 12 + 200)
 $walker = [System.Windows.Automation.TreeWalker]::ControlViewWalker
-$win = $root
-while ($win -and $win.Current.ControlType -ne [System.Windows.Automation.ControlType]::Window) {
-  $parent = $walker.GetParent($win)
-  if (-not $parent) { break }
-  $win = $parent
-}
-if (-not $win) { $win = $root }
-$title = $win.Current.Name
-$app = $win.Current.Name
-if ($appFilter -ne '' -and $title -notlike "*$appFilter*" -and $app -notlike "*$appFilter*") {
-  $cond = New-Object System.Windows.Automation.PropertyCondition(
-    [System.Windows.Automation.AutomationElement]::NameProperty, $appFilter)
-  $found = [System.Windows.Automation.AutomationElement]::RootElement.FindFirst(
-    [System.Windows.Automation.TreeScope]::Children, $cond)
-  if ($found) { $win = $found; $title = $win.Current.Name; $app = $win.Current.Name }
+
+$focusedWin = $null
+try {
+  $fe = [System.Windows.Automation.AutomationElement]::FocusedElement
+  $cur = $fe
+  while ($cur -and $cur.Current.ControlType -ne [System.Windows.Automation.ControlType]::Window) {
+    $p = $walker.GetParent($cur)
+    if (-not $p) { break }
+    $cur = $p
+  }
+  if ($cur) { $focusedWin = $cur }
+} catch {}
+
+$all = XrkTopWindows
+$win = $null
+$byProc = $null
+$byTitle = $null
+$candidates = New-Object System.Collections.Generic.List[string]
+foreach ($w in $all) {
+  $t = ''
+  try { $t = $w.Current.Name } catch {}
+  $pn = XrkProcName $w.Current.ProcessId
+  $cn = ''
+  try { $cn = $w.Current.ClassName } catch {}
+  if (-not [string]::IsNullOrWhiteSpace($t)) { $candidates.Add($t + ' [' + $pn + ']') }
+  if ($appFilter -eq '') {
+    if (-not $win -and $focusedWin -and $w.Current.NativeWindowHandle -eq $focusedWin.Current.NativeWindowHandle) {
+      $win = $w
+    } elseif (-not $win -and -not [string]::IsNullOrWhiteSpace($t)) {
+      $win = $w
+    }
+    continue
+  }
+  # A process/class hit beats a title that merely mentions the app (a browser tab
+  # titled "...QQ..." must not shadow the real QQ window).
+  if (-not $byProc -and ((XrkMatch $pn $appFilter) -or (XrkMatch $cn $appFilter))) { $byProc = $w }
+  if (-not $byTitle -and (XrkMatch $t $appFilter)) { $byTitle = $w }
+}
+if ($appFilter -ne '' -and -not $win) {
+  if ($focusedWin) {
+    $ft = ''
+    try { $ft = $focusedWin.Current.Name } catch {}
+    $fpn = XrkProcName $focusedWin.Current.ProcessId
+    if ((XrkMatch $fpn $appFilter) -or (XrkMatch $ft $appFilter)) { $win = $focusedWin }
+  }
+  if (-not $win) { $win = $byProc }
+  if (-not $win) { $win = $byTitle }
+}
+if (-not $win) {
+  @{ error = 'app-not-found'; app = ''; windowTitle = ''; elements = @(); candidates = $candidates } | ConvertTo-Json -Depth 6 -Compress
+  return
 }
+
+$title = ''
+try { $title = $win.Current.Name } catch {}
+$targetPid = $win.Current.ProcessId
+$appLabel = XrkProcName $targetPid
+if ([string]::IsNullOrWhiteSpace($appLabel)) { $appLabel = $title }
+
 $elements = New-Object System.Collections.Generic.List[object]
-$stack = New-Object System.Collections.Stack
-$stack.Push($win)
+$seen = New-Object System.Collections.Generic.HashSet[string]
+$queue = New-Object System.Collections.Generic.Queue[object]
+$queue.Enqueue(@{ el = $win; d = 0 })
 $idx = 0
-while ($stack.Count -gt 0 -and $idx -lt $max) {
-  $el = $stack.Pop()
-  $child = $walker.GetFirstChild($el)
-  while ($child) {
-    $stack.Push($child)
-    $child = $walker.GetNextSibling($child)
+$visited = 0
+$dropped = 0
+$exhausted = $true
+while ($queue.Count -gt 0 -and $idx -lt $max -and $visited -lt $visitCap) {
+  $item = $queue.Dequeue()
+  $el = $item.el
+  $depth = $item.d
+  $visited++
+  $rid = ''
+  try { $rid = ($el.GetRuntimeId() -join ',') } catch {}
+  if ($rid -ne '' -and -not $seen.Add($rid)) { continue }
+  $ct = ''
+  try { $ct = $el.Current.ControlType.ProgrammaticName } catch {}
+  $name = ''
+  try { $name = $el.Current.Name } catch {}
+  # Always expand (bounded by depth): gating expansion on $depth -gt 0 meant the
+  # root window never yielded children and every capture came back empty.
+  if ($depth -lt $maxDepth) {
+    try {
+      $child = $walker.GetFirstChild($el)
+      $guard = 0
+      while ($child -and $guard -lt 500 -and ($visited + $guard) -lt $visitCap) {
+        $queue.Enqueue(@{ el = $child; d = ($depth + 1) })
+        $guard++
+        $child = $walker.GetNextSibling($child)
+      }
+    } catch { $dropped++ }
   }
-  $ct = $el.Current.ControlType.ProgrammaticName
-  $name = $el.Current.Name
-  if ([string]::IsNullOrWhiteSpace($name) -and [string]::IsNullOrWhiteSpace($ct)) { continue }
-  if ($ct -eq 'ControlType.Window' -or $ct -eq 'ControlType.Pane') { continue }
-  $idx++
-  $r = $el.Current.BoundingRectangle
-  $elements.Add([pscustomobject]@{
-    index = $idx
-    role = ($ct -replace '^ControlType\\.','')
-    name = ($(if ($name) { $name } else { $ct }))
-    x = [int]$r.X; y = [int]$r.Y; width = [int]$r.Width; height = [int]$r.Height
-    runtimeId = ($el.GetRuntimeId() -join ',')
-  })
-}
-@{ app = $app; windowTitle = $title; elements = $elements } | ConvertTo-Json -Depth 5 -Compress
+  try {
+    if ($el.Current.ProcessId -ne $targetPid) { continue }
+    $role = ($ct -replace '^ControlType\\.','')
+    if ($depth -eq 0) { continue }
+    if (($role -eq 'Window' -or $role -eq 'Pane') -and [string]::IsNullOrWhiteSpace($name)) { continue }
+    $r = $el.Current.BoundingRectangle
+    $x = XrkSafeInt $r.X
+    $y = XrkSafeInt $r.Y
+    $wd = XrkSafeInt $r.Width
+    $ht = XrkSafeInt $r.Height
+    $offscreen = ($null -eq $x -or $null -eq $y -or $null -eq $wd -or $null -eq $ht -or $wd -le 0 -or $ht -le 0)
+    if ($offscreen -and -not $keepOffscreen) { continue }
+    if ([string]::IsNullOrWhiteSpace($name) -and [string]::IsNullOrWhiteSpace($role)) { continue }
+    $idx++
+    $display = $name
+    if ([string]::IsNullOrWhiteSpace($display)) { $display = $ct }
+    $elements.Add([pscustomobject]@{
+      index = $idx
+      role = $role
+      name = $display
+      x = $x; y = $y; width = $wd; height = $ht
+      runtimeId = $rid
+    })
+  } catch { $dropped++ }
+}
+if ($queue.Count -gt 0 -and $visited -ge $visitCap) { $exhausted = $false }
+@{ app = $appLabel; windowTitle = $title; elements = $elements; visited = $visited; dropped = $dropped; exhausted = $exhausted } | ConvertTo-Json -Depth 6 -Compress
 `.trim();
 }
+/** Re-resolve an element by runtime id; Invoke → Select → focus + mouse click. */
 function clickScript(runtimeId) {
-    const idLit = JSON.stringify(runtimeId);
-    return `
-Add-Type -AssemblyName UIAutomationClient
-Add-Type -AssemblyName UIAutomationTypes
-$ErrorActionPreference = 'Stop'
+    const idLit = psStr(runtimeId);
+    return `${PS_PRELUDE}
 $ids = @((${idLit}) -split ',' | ForEach-Object { [int]$_ })
 $el = [System.Windows.Automation.AutomationElement]::AutomationElementFromRuntimeId($ids)
-if (-not $el) { throw 'element not found' }
+if (-not $el) { throw 'element not found (window changed? capture again)' }
 $inv = $null
 if ($el.TryGetCurrentPattern([System.Windows.Automation.InvokePattern]::Pattern, [ref]$inv)) {
   $inv.Invoke()
@@ -121,71 +280,116 @@ if ($el.TryGetCurrentPattern([System.Windows.Automation.SelectionItemPattern]::P
   'clicked-select'
   return
 }
-throw 'element is not invokable via UIA'
+$box = $el.Current.BoundingRectangle
+if ($null -eq (XrkSafeInt $box.X) -or $null -eq (XrkSafeInt $box.Y)) {
+  throw 'element is not invokable via UIA and has no on-screen bounds to click'
+}
+Add-Type -AssemblyName System.Windows.Forms
+Add-Type -AssemblyName System.Drawing
+Add-Type @"
+using System;
+using System.Runtime.InteropServices;
+public static class XrkClick {
+  [DllImport("user32.dll")] public static extern bool SetCursorPos(int x, int y);
+  [DllImport("user32.dll")] public static extern void mouse_event(uint f, uint dx, uint dy, int data, UIntPtr extra);
+  public const uint LEFTDOWN = 0x0002;
+  public const uint LEFTUP = 0x0004;
+}
+"@
+try { $el.SetFocus() } catch {}
+Start-Sleep -Milliseconds 40
+$r = $el.Current.BoundingRectangle
+$x = XrkSafeInt ($r.X + $r.Width / 2)
+$y = XrkSafeInt ($r.Y + $r.Height / 2)
+[void][XrkClick]::SetCursorPos($x, $y)
+[void][XrkClick]::mouse_event([XrkClick]::LEFTDOWN, 0, 0, 0, [UIntPtr]::Zero)
+Start-Sleep -Milliseconds 30
+[void][XrkClick]::mouse_event([XrkClick]::LEFTUP, 0, 0, 0, [UIntPtr]::Zero)
+'clicked-point'
 `.trim();
 }
+/**
+ * ValuePattern first, then clipboard paste (CJK-safe), then escaped SendKeys.
+ * Raw SendKeys mangles `+^%~()` and drops non-ASCII, so the caller passes both
+ * the literal text and a SendKeys-escaped copy.
+ */
 function typeScript(runtimeId, text) {
-    const idLit = JSON.stringify(runtimeId);
-    const textLit = JSON.stringify(text);
-    return `
-Add-Type -AssemblyName UIAutomationClient
-Add-Type -AssemblyName UIAutomationTypes
+    const idLit = psStr(runtimeId);
+    const textLit = psStr(text);
+    const keysLit = psStr(escapeSendKeys(text));
+    return `${PS_PRELUDE}
 Add-Type -AssemblyName System.Windows.Forms
-$ErrorActionPreference = 'Stop'
+$text = ${textLit}
+$escaped = ${keysLit}
 $ids = @((${idLit}) -split ',' | ForEach-Object { [int]$_ })
 $el = [System.Windows.Automation.AutomationElement]::AutomationElementFromRuntimeId($ids)
-if (-not $el) { throw 'element not found' }
+if (-not $el) { throw 'element not found (window changed? capture again)' }
 $val = $null
 if ($el.TryGetCurrentPattern([System.Windows.Automation.ValuePattern]::Pattern, [ref]$val)) {
-  $val.SetValue(${textLit})
-  'typed-value'
-  return
+  try {
+    if (-not $val.Current.IsReadOnly) {
+      $val.SetValue($text)
+      'typed-value'
+      return
+    }
+  } catch {}
+}
+try { $el.SetFocus() } catch {}
+Start-Sleep -Milliseconds 40
+$pasted = $false
+$old = $null
+$clipReadable = $false
+try { $old = Get-Clipboard -ErrorAction Stop; $clipReadable = $true } catch {
+  try { $old = Get-Clipboard -Raw -ErrorAction Stop; $clipReadable = $true } catch {}
+}
+try {
+  Set-Clipboard -Value $text
+  [System.Windows.Forms.SendKeys]::SendWait('^v')
+  Start-Sleep -Milliseconds 30
+  $pasted = $true
+} catch {}
+if ($pasted -and $clipReadable) {
+  try {
+    if ($null -ne $old) { Set-Clipboard -Value ($old -join [Environment]::NewLine) } else { Set-Clipboard -Value '' }
+  } catch {}
+}
+if ($pasted) { 'typed-paste' } else {
+  [System.Windows.Forms.SendKeys]::SendWait($escaped)
+  'typed-sendkeys'
 }
-$el.SetFocus()
-[System.Windows.Forms.SendKeys]::SendWait(${textLit})
-'typed-sendkeys'
 `.trim();
 }
 function keyScript(keysSendWait, runtimeId) {
-    const keysLit = JSON.stringify(keysSendWait);
+    const keysLit = psStr(keysSendWait);
     const focusBlock = runtimeId
         ? `
-$ids = @((${JSON.stringify(runtimeId)}) -split ',' | ForEach-Object { [int]$_ })
+$ids = @((${psStr(runtimeId)}) -split ',' | ForEach-Object { [int]$_ })
 $el = [System.Windows.Automation.AutomationElement]::AutomationElementFromRuntimeId($ids)
-if (-not $el) { throw 'element not found' }
-$el.SetFocus()
+if (-not $el) { throw 'element not found (window changed? capture again)' }
+try { $el.SetFocus() } catch {}
 Start-Sleep -Milliseconds 40
 `
         : "";
-    return `
-Add-Type -AssemblyName UIAutomationClient
-Add-Type -AssemblyName UIAutomationTypes
-Add-Type -AssemblyName System.Windows.Forms
-$ErrorActionPreference = 'Stop'
-${focusBlock}[System.Windows.Forms.SendKeys]::SendWait(${keysLit})
+    return `${PS_PRELUDE}${focusBlock}Add-Type -AssemblyName System.Windows.Forms
+[System.Windows.Forms.SendKeys]::SendWait(${keysLit})
 'keyed'
 `.trim();
 }
 function scrollScript(options) {
     const amount = Math.max(1, Math.min(50, Math.floor(options.amount)));
     const dir = options.direction;
-    const idLit = options.runtimeId
-        ? JSON.stringify(options.runtimeId)
-        : '""';
-    return `
-Add-Type -AssemblyName UIAutomationClient
-Add-Type -AssemblyName UIAutomationTypes
+    const idLit = options.runtimeId ? psStr(options.runtimeId) : "''";
+    return `${PS_PRELUDE}
 Add-Type -AssemblyName System.Windows.Forms
 Add-Type -AssemblyName System.Drawing
-$ErrorActionPreference = 'Stop'
-$dir = ${JSON.stringify(dir)}
+$dir = ${psStr(dir)}
 $amount = ${amount}
 $runtimeId = ${idLit}
 $el = $null
 if ($runtimeId -ne '') {
   $ids = @(($runtimeId) -split ',' | ForEach-Object { [int]$_ })
   $el = [System.Windows.Automation.AutomationElement]::AutomationElementFromRuntimeId($ids)
-  if (-not $el) { throw 'element not found' }
+  if (-not $el) { throw 'element not found (window changed? capture again)' }
 }
 if ($el) {
   $scroll = $null
@@ -206,12 +410,14 @@ if ($el) {
     'scrolled-pattern'
     return
   }
-  $el.SetFocus()
+  try { $el.SetFocus() } catch {}
   Start-Sleep -Milliseconds 40
   $r = $el.Current.BoundingRectangle
-  $x = [int]($r.X + $r.Width / 2)
-  $y = [int]($r.Y + $r.Height / 2)
-  [System.Windows.Forms.Cursor]::Position = New-Object System.Drawing.Point($x, $y)
+  $x = XrkSafeInt ($r.X + $r.Width / 2)
+  $y = XrkSafeInt ($r.Y + $r.Height / 2)
+  if ($null -ne $x -and $null -ne $y) {
+    [System.Windows.Forms.Cursor]::Position = New-Object System.Drawing.Point($x, $y)
+  }
 }
 Add-Type @"
 using System;
@@ -231,53 +437,87 @@ if ($dir -eq 'left' -or $dir -eq 'right') { $flags = [XrkMouseWheel]::MOUSEEVENT
 'scrolled-wheel'
 `.trim();
 }
+/**
+ * Wrap the list in an object and hand the `List` straight to ConvertTo-Json:
+ * a bare piped array serializes as `{"value":[…],"Count":n}` (which reads back as
+ * one window), and `@($list)` around a Generic List makes ConvertTo-Json throw
+ * "Argument types do not match".
+ */
 function listWindowsScript() {
-    return `
-Add-Type -AssemblyName UIAutomationClient
-Add-Type -AssemblyName UIAutomationTypes
-$ErrorActionPreference = 'Stop'
+    return `${PS_PRELUDE}
 $root = [System.Windows.Automation.AutomationElement]::RootElement
 $cond = New-Object System.Windows.Automation.PropertyCondition(
   [System.Windows.Automation.AutomationElement]::ControlTypeProperty,
   [System.Windows.Automation.ControlType]::Window)
 $wins = $root.FindAll([System.Windows.Automation.TreeScope]::Children, $cond)
-$list = @()
+$list = New-Object System.Collections.Generic.List[object]
 foreach ($w in $wins) {
-  $n = $w.Current.Name
-  if ([string]::IsNullOrWhiteSpace($n)) { continue }
-  $list += [pscustomobject]@{ title = $n; pid = $w.Current.ProcessId; app = $n }
+  $n = ''
+  try { $n = $w.Current.Name } catch {}
+  $proc = XrkProcName $w.Current.ProcessId
+  if ([string]::IsNullOrWhiteSpace($n) -and [string]::IsNullOrWhiteSpace($proc)) { continue }
+  $list.Add([pscustomobject]@{ title = $n; pid = $w.Current.ProcessId; app = $proc })
 }
-,@($list) | ConvertTo-Json -Compress
+@{ windows = $list } | ConvertTo-Json -Depth 5 -Compress
 `.trim();
 }
+function finite(...values) {
+    return values.every((v) => typeof v === "number" && Number.isFinite(v));
+}
+/** PowerShell can emit `{}` or `{"value":…}` where an array was expected. */
+function payloadList(value) {
+    return Array.isArray(value) ? value : [];
+}
 /**
  * Windows UI Automation Provider. Requires a desktop session; opt-in with XRK_COMPUTER_USE=1.
  */
 export function createWindowsUiAutomationProvider(options = {}) {
-    const run = options.runPowerShell ?? defaultRunPowerShell;
+    const run = options.runPowerShell ??
+        ((script, signal) => defaultRunPowerShell(script, signal, options.timeoutMs));
     let tokens = new Map();
+    async function runCapture(request, signal, includeOffscreen) {
+        const max = request?.maxElements ?? DEFAULT_MAX_ELEMENTS;
+        const raw = await run(captureScript({
+            ...(request?.app !== undefined ? { app: request.app } : {}),
+            maxElements: max,
+            includeOffscreen,
+        }), signal);
+        return parseJson(raw, "capture");
+    }
     return {
         providerId: "windows-uia",
         delivery: "uia",
         async capture(request, signal) {
-            const max = request?.maxElements ?? DEFAULT_MAX_ELEMENTS;
-            const raw = await run(captureScript(request?.app, max), signal);
-            const payload = parseJson(raw, "capture");
+            let payload = await runCapture(request, signal, false);
+            // Chromium / Electron builds its UIA tree lazily and many widgets report an
+            // empty BoundingRectangle on the first pass — retry once keeping offscreen
+            // nodes instead of handing the model a 0-element snapshot.
+            if (!payload.error && payloadList(payload.elements).length === 0) {
+                const retry = await runCapture(request, signal, true);
+                if (!retry.error)
+                    payload = retry;
+            }
+            if (payload.error === "app-not-found") {
+                const wanted = String(request?.app ?? "").trim();
+                const candidates = payloadList(payload.candidates).slice(0, 8).join("; ");
+                throw new ComputerUseError(`no window matches "${wanted}"${candidates ? ` — open windows: ${candidates}` : ""}`, "COMPUTER_USE_BAD_ARGS");
+            }
             tokens = new Map();
-            const elements = (payload.elements ?? []).map((e) => {
+            const elements = payloadList(payload.elements).map((e) => {
                 if (e.runtimeId)
                     tokens.set(e.index, e.runtimeId);
+                const hasBounds = finite(e.x, e.y, e.width, e.height);
                 return {
                     index: e.index,
                     role: e.role || "unknown",
                     name: e.name || "",
-                    ...(e.x !== undefined
+                    ...(hasBounds
                         ? {
                             bounds: {
-                                x: e.x ?? 0,
-                                y: e.y ?? 0,
-                                width: e.width ?? 0,
-                                height: e.height ?? 0,
+                                x: e.x,
+                                y: e.y,
+                                width: e.width,
+                                height: e.height,
                             },
                         }
                         : {}),
@@ -287,15 +527,25 @@ export function createWindowsUiAutomationProvider(options = {}) {
                 };
             });
             const mode = request?.mode ?? "ax";
-            const note = mode === "vision" || mode === "som"
-                ? "windows-uia has no screenshot overlay yet; AX elements only (delivery=uia, not background SPI)"
-                : "delivery=uia (UI Automation; not cua-driver background SPI)";
+            const notes = [
+                mode === "vision" || mode === "som"
+                    ? "windows-uia has no screenshot overlay yet; AX elements only (delivery=uia, not background SPI)"
+                    : "delivery=uia (UI Automation; not cua-driver background SPI)",
+            ];
+            if (elements.length === 0) {
+                notes.push(payload.exhausted === false
+                    ? "visit budget ran out before any matching node — raise maxElements (the window is large, not empty)"
+                    : "this window exposed no usable UIA elements (custom-drawn or accessibility-disabled apps expose none) — fall back to action=key, or browser_* when the target is a web page");
+            }
+            else if (payload.exhausted === false) {
+                notes.push(`tree truncated at ${elements.length} of more nodes; raise maxElements for more`);
+            }
             return buildCaptureResult({
                 mode: mode === "vision" ? "ax" : mode,
                 app: payload.app ?? "",
                 windowTitle: payload.windowTitle ?? "",
                 elements,
-                note,
+                note: notes.join(" | "),
             });
         },
         async act(request, signal) {
@@ -357,7 +607,7 @@ export function createWindowsUiAutomationProvider(options = {}) {
             }
             const runtimeId = tokens.get(request.element);
             if (!runtimeId) {
-                throw new ComputerUseError(`stale or unknown element [${request.element}] — capture again`, "COMPUTER_USE_STALE_ELEMENT");
+                throw new ComputerUseError(`stale or unknown element [${request.element}] — capture again (elements with no runtime id cannot be targeted)`, "COMPUTER_USE_STALE_ELEMENT");
             }
             if (request.action === "click") {
                 const out = await run(clickScript(runtimeId), signal);
@@ -382,7 +632,14 @@ export function createWindowsUiAutomationProvider(options = {}) {
         async listWindows(signal) {
             const raw = await run(listWindowsScript(), signal);
             const parsed = parseJson(raw, "windows");
-            return Array.isArray(parsed) ? parsed : [parsed];
+            const list = Array.isArray(parsed)
+                ? parsed
+                : payloadList(parsed?.windows);
+            return list.map((w) => ({
+                title: String(w.title ?? ""),
+                ...(w.pid !== undefined ? { pid: w.pid } : {}),
+                ...(w.app ? { app: w.app } : {}),
+            }));
         },
     };
 }