@vortex-os/computer-use 0.1.0

package/scripts/lib.ps1

@@ -0,0 +1,617 @@
+# computer-use — shared logic library (throwaway PoC)
+# Contract (important): functions in this file "return objects only" and write nothing to stdout.
+#   -> shared via dot-source by the standalone scripts (probe/read-ui/point-to-ask) and worker.ps1.
+#   -> output (ConvertTo-Json) and framing are the caller's (adapter's) job. If you need to log, use [Console]::Error.
+# (In the JSON-lines worker, stdout pollution = a broken parser, so this separation is essential — codex cross-check finding #3)
+
+function Initialize-AxEnv {
+  # Heavy one-time setup: encoding, native types, DPI, assemblies. Safe to re-call / re-dot-source (idempotent).
+  if ($script:AxInit) { return }
+  try { [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false) } catch {}
+  try { [Console]::InputEncoding  = [System.Text.UTF8Encoding]::new($false) } catch {}
+  if (-not ('AxNative' -as [type])) {   # avoid redefining an already-defined type (prevents Add-Type conflicts on re-dot-source)
+    Add-Type @"
+using System; using System.Collections.Generic; using System.Runtime.InteropServices; using System.Text;
+public struct AxRECT { public int Left, Top, Right, Bottom; }
+public struct AxWin { public int Pid; public int Left, Top, Right, Bottom; public string Title; }
+public static class AxNative {
+  [DllImport("user32.dll")] public static extern IntPtr SetThreadDpiAwarenessContext(IntPtr v);
+  [DllImport("user32.dll")] public static extern IntPtr GetThreadDpiAwarenessContext();
+  [DllImport("user32.dll")] public static extern int GetAwarenessFromDpiAwarenessContext(IntPtr c);
+  [DllImport("user32.dll")] public static extern bool SetProcessDpiAwarenessContext(IntPtr v);
+  [DllImport("user32.dll")] public static extern IntPtr GetForegroundWindow();
+  [DllImport("user32.dll")] public static extern bool GetWindowRect(IntPtr h, out AxRECT r);
+  [DllImport("user32.dll")] public static extern bool IsIconic(IntPtr h);
+  [DllImport("user32.dll")] public static extern bool IsWindowVisible(IntPtr h);
+  [DllImport("user32.dll")] public static extern int GetWindowThreadProcessId(IntPtr h, out int pid);
+  [DllImport("user32.dll")] public static extern int GetWindowTextLength(IntPtr h);
+  [DllImport("user32.dll", CharSet=CharSet.Unicode)] public static extern int GetWindowTextW(IntPtr h, StringBuilder s, int max);
+  private delegate bool AxEnumProc(IntPtr h, IntPtr l);
+  [DllImport("user32.dll", SetLastError=true)] private static extern bool EnumWindows(AxEnumProc cb, IntPtr l);
+  // Enumerate every visible (not minimized, area>0) top-level window as (pid, rect, title) — so the denylist checks not just the
+  //   main window but secondary windows, popups, and dialogs too (codex r2 BLOCKER). The callback only needs to live for the duration of the synchronous call (hold the delegate in a local variable to prevent GC).
+  //   EnumWindows returning false = a real failure -> throw (since the callback always returns true, false can only mean an API failure). The caller handles it fail-closed (codex r3 LOW).
+  public static List<AxWin> VisibleWindows() {
+    var list = new List<AxWin>();
+    AxEnumProc cb = (h, l) => {
+      if (!IsWindowVisible(h) || IsIconic(h)) return true;
+      AxRECT r; if (!GetWindowRect(h, out r)) return true;
+      if (r.Right - r.Left <= 0 || r.Bottom - r.Top <= 0) return true;
+      int pid; GetWindowThreadProcessId(h, out pid);
+      string title = "";
+      int len = GetWindowTextLength(h);
+      if (len > 0) { var sb = new StringBuilder(len + 2); GetWindowTextW(h, sb, sb.Capacity); title = sb.ToString(); }
+      list.Add(new AxWin { Pid = pid, Left = r.Left, Top = r.Top, Right = r.Right, Bottom = r.Bottom, Title = title });
+      return true;
+    };
+    if (!EnumWindows(cb, IntPtr.Zero)) throw new System.ComponentModel.Win32Exception(Marshal.GetLastWin32Error());
+    GC.KeepAlive(cb);
+    return list;
+  }
+}
+"@
+  }
+  # Per-thread per-monitor-v2 — bypasses pwsh's SYSTEM manifest (coordinates become physical per-monitor).
+  [void][AxNative]::SetProcessDpiAwarenessContext([IntPtr](-4))   # bonus for unaware hosts
+  [void][AxNative]::SetThreadDpiAwarenessContext([IntPtr](-4))    # always works, pwsh included
+  Add-Type -AssemblyName System.Drawing
+  Add-Type -AssemblyName System.Windows.Forms
+  Add-Type -AssemblyName UIAutomationClient
+  Add-Type -AssemblyName UIAutomationTypes
+  Add-Type -AssemblyName WindowsBase
+  $script:AxInit = $true
+}
+
+function Get-AxDpiMode {
+  switch ([AxNative]::GetAwarenessFromDpiAwarenessContext([AxNative]::GetThreadDpiAwarenessContext())) {
+    0 { 'unaware' } 1 { 'system' } 2 { 'per-monitor' } default { '?' }
+  }
+}
+
+function Clamp-AxInt([int]$v, [int]$lo, [int]$hi) { if ($v -lt $lo) { $lo } elseif ($v -gt $hi) { $hi } else { $v } }
+
+# detail preset -> default scale (upscale cap for small regions) and maxSide (downscale cap for large captures). For token efficiency.
+#   gist=flow only (small) / normal=default / text=reading text and code (large). An explicit scale/maxSide (>0) takes precedence over the preset.
+function Get-AxDetailPreset([string]$Detail) {
+  switch ($Detail) {
+    'gist' { @{ scale = 1.0; maxSide = 768 } }
+    'text' { @{ scale = 3.0; maxSide = 1920 } }
+    default { @{ scale = 2.0; maxSide = 1280 } }   # normal (default)
+  }
+}
+
+# Sound alert — call when there's something to show the user during watching (so they notice while looking at a game / another screen). A precursor to future TTS.
+function Get-AxBeepPattern([string]$Pattern) {
+  switch ($Pattern) {
+    'warn'   { @{ count = 2; frequency = 988;  durationMs = 180 } }
+    'urgent' { @{ count = 3; frequency = 1175; durationMs = 160 } }
+    default  { @{ count = 1; frequency = 880;  durationMs = 200 } }   # info
+  }
+}
+function Invoke-AxBeep([string]$Pattern = 'info', [int]$Count = 0, [int]$Frequency = 0, [int]$DurationMs = 0, [int]$GapMs = 120) {
+  $p = Get-AxBeepPattern $Pattern
+  $c = if ($Count -gt 0) { $Count } else { $p.count }
+  $f = if ($Frequency -gt 0) { $Frequency } else { $p.frequency }
+  $d = if ($DurationMs -gt 0) { $DurationMs } else { $p.durationMs }
+  $f = [Math]::Max(37, [Math]::Min(32767, $f))   # valid frequency range for [Console]::Beep
+  $d = [Math]::Max(10, [Math]::Min(5000, $d))
+  $c = [Math]::Max(1, [Math]::Min(10, $c))        # cap to prevent abuse
+  for ($i = 0; $i -lt $c; $i++) {
+    if ($i -gt 0) { Start-Sleep -Milliseconds $GapMs }
+    [Console]::Beep($f, $d)                        # doesn't use stdout (system beep) -> no JSON-lines pollution
+  }
+  return [ordered]@{ ok = $true; pattern = $Pattern; count = $c; frequency = $f; durationMs = $d }
+}
+
+# ---------------- probe ----------------
+function Measure-AxMs([scriptblock]$sb) {
+  $sw = [System.Diagnostics.Stopwatch]::StartNew()
+  $r = & $sb
+  $sw.Stop()
+  [pscustomobject]@{ ms = [math]::Round($sw.Elapsed.TotalMilliseconds, 1); result = $r }
+}
+
+function Get-AxProbe {
+  $out = [ordered]@{}
+  $out.os = [System.Environment]::OSVersion.VersionString
+  $out.is64bitProcess = [System.Environment]::Is64BitProcess
+  $screens = @([System.Windows.Forms.Screen]::AllScreens)
+  $out.displayCount = $screens.Count
+  $out.displays = @($screens | ForEach-Object {
+    [ordered]@{ device = $_.DeviceName; primary = $_.Primary; bounds = "$($_.Bounds.Width)x$($_.Bounds.Height) @ ($($_.Bounds.X),$($_.Bounds.Y))" }
+  })
+  $vs = [System.Windows.Forms.SystemInformation]::VirtualScreen
+  $out.virtualScreen = "$($vs.Width)x$($vs.Height) @ ($($vs.X),$($vs.Y))"
+  $tmp = New-Object System.Drawing.Bitmap 1, 1; $g0 = $null
+  try {
+    $g0 = [System.Drawing.Graphics]::FromImage($tmp)
+    $out.dpi = "$($g0.DpiX)x$($g0.DpiY)  (scale ~$([math]::Round($g0.DpiX/96*100))%)"
+  } finally { if ($g0) { $g0.Dispose() }; $tmp.Dispose() }
+  $cur = [System.Windows.Forms.Cursor]::Position
+  $out.cursor = "$($cur.X),$($cur.Y)"
+  # Latency probe uses a SYNTHETIC fill, NOT a real desktop grab — probe must not capture screen content before a
+  # consented perception call (design 16/24, codex blocker). Times the GDI capture pipeline (alloc + draw + dispose).
+  $cw = 500; $ch = 350; $capMs = @()
+  for ($i = 0; $i -lt 6; $i++) {
+    $m = Measure-AxMs {
+      $bmp = New-Object System.Drawing.Bitmap $cw, $ch; $g = $null
+      try {
+        $g = [System.Drawing.Graphics]::FromImage($bmp)
+        $g.Clear([System.Drawing.Color]::Black)
+        $g.FillRectangle([System.Drawing.Brushes]::Gray, 0, 0, $cw, $ch)
+      } finally { if ($g) { $g.Dispose() }; $bmp.Dispose() }
+    }
+    $capMs += $m.ms
+  }
+  $sorted = @($capMs | Sort-Object)
+  $out.captureMs = [ordered]@{ samples = $capMs; min = $sorted[0]; median = $sorted[[int]($sorted.Count / 2)]; max = $sorted[-1]; note = "synthetic pipeline estimate (no real screen captured); first sample includes JIT warm-up" }
+  $uiaRoot = Measure-AxMs { [System.Windows.Automation.AutomationElement]::RootElement.Current.Name }
+  $out.uiaRootMs = $uiaRoot.ms
+  $out.uiaRootOk = -not [string]::IsNullOrEmpty($uiaRoot.result)   # boolean only — pre-consent probe must not return UI names/text/class (codex #med)
+  $pt = New-Object System.Windows.Point $cur.X, $cur.Y
+  $uiaPt = Measure-AxMs { [System.Windows.Automation.AutomationElement]::FromPoint($pt) }
+  $out.uiaFromPointMs = $uiaPt.ms
+  try {
+    $el = $uiaPt.result
+    $out.uiaAtCursor = [ordered]@{ ok = ($null -ne $el); control = $el.Current.ControlType.ProgrammaticName }   # structural control type only — no name/class/content
+  } catch { $out.uiaAtCursor = [ordered]@{ ok = $false } }
+  $capOk = $out.captureMs.median -lt 300
+  $out.verdict = [ordered]@{
+    hasDisplay = ($screens.Count -gt 0); captureUnder300ms = $capOk; uiaResponsive = ($uiaRoot.ms -lt 1000)
+    grade = $(if ($screens.Count -gt 0 -and $capOk) { "perception available (OK to proceed to P1)" } else { "fall back to P0 (manual paste)" })
+  }
+  return $out
+}
+
+# ---------------- capture ----------------
+function New-AxOutPath([string]$OutDir, $Frame = $null) {
+  # Avoid multi-instance / concurrent-capture collisions — guarantee uniqueness with PID + milliseconds + random number.
+  $stamp = (Get-Date).ToString('HHmmssfff')
+  $rand = Get-Random -Maximum 1000000
+  $fpart = if ($null -ne $Frame) { "_f$Frame" } else { "" }
+  return (Join-Path $OutDir ("pta_{0}_{1}_{2}{3}.png" -f $PID, $stamp, $rand, $fpart))
+}
+
+function Remove-AxStale([string]$OutDir, [int]$MaxAgeMin = 5) {
+  # Clean up orphaned temp files that were read but not deleted (§8). Only those older than 5 minutes -> safe for in-flight work.
+  try {
+    $cut = (Get-Date).AddMinutes(-$MaxAgeMin)
+    Get-ChildItem -Path $OutDir -Filter 'pta_*.png' -File -ErrorAction SilentlyContinue |
+      Where-Object { $_.LastWriteTime -lt $cut } | Remove-Item -Force -ErrorAction SilentlyContinue
+  } catch {}
+}
+
+function Resolve-AxTarget($Region, $WindowMatch, $Monitor, [int]$BoxW, [int]$BoxH) {
+  $cur = [System.Windows.Forms.Cursor]::Position
+  $vs = [System.Windows.Forms.SystemInformation]::VirtualScreen
+  $tgt = 'cursor'; $wt = $null; $md = $null
+  if ($Region) {
+    $tgt = 'region'
+    $p = @($Region -split '[,x× ]+' | Where-Object { $_ -ne '' })
+    if ($p.Count -lt 4) { throw "Region must be in 'x,y,w,h' format: '$Region'" }
+    $x = [int]$p[0]; $y = [int]$p[1]; $w = [int]$p[2]; $h = [int]$p[3]
+  }
+  elseif ($WindowMatch) {
+    $tgt = 'window'
+    $cands = @(Get-Process | Where-Object {
+      $_.MainWindowHandle -ne 0 -and $_.MainWindowTitle -and
+      $_.MainWindowTitle.IndexOf($WindowMatch, [StringComparison]::OrdinalIgnoreCase) -ge 0
+    })
+    if ($cands.Count -eq 0) { throw "window not found: '$WindowMatch'" }
+    $exact = @($cands | Where-Object { $_.MainWindowTitle -eq $WindowMatch })
+    if ($exact.Count -ge 1) { $cands = $exact }
+    if ($cands.Count -gt 1) {
+      # When the denylist is active, don't expose candidate titles (a matched window may be a denylist target, codex r3 MEDIUM). The caller-supplied $WindowMatch is already known, so keep it.
+      if (Test-AxDenyActive) { throw "multiple windows matched ('$WindowMatch') — specify a more precise title (candidate titles omitted: denylist active)" }
+      $titles = @($cands | Select-Object -ExpandProperty MainWindowTitle -Unique)
+      throw "multiple windows matched ('$WindowMatch') — specify a more precise title: $([string]::Join(' | ', $titles))"
+    }
+    $hwnd = $cands[0].MainWindowHandle
+    if ([AxNative]::IsIconic($hwnd)) {
+      if (Test-AxDenyActive) { throw "window is minimized, cannot capture (title omitted: denylist active)" }
+      throw "window is minimized, cannot capture: '$($cands[0].MainWindowTitle)'"
+    }
+    $r = New-Object AxRECT
+    [void][AxNative]::GetWindowRect($hwnd, [ref]$r)
+    $x = $r.Left; $y = $r.Top; $w = $r.Right - $r.Left; $h = $r.Bottom - $r.Top
+    $wt = $cands[0].MainWindowTitle
+  }
+  elseif ($Monitor) {
+    $tgt = 'monitor'
+    $screens = @([System.Windows.Forms.Screen]::AllScreens)
+    if ($Monitor -eq 'primary') { $scr = [System.Windows.Forms.Screen]::PrimaryScreen }
+    else {
+      $idx = [int]$Monitor - 1
+      if ($idx -lt 0 -or $idx -ge $screens.Count) { throw "monitor index out of range (1..$($screens.Count)): '$Monitor'" }
+      $scr = $screens[$idx]
+    }
+    $b = $scr.Bounds; $x = $b.X; $y = $b.Y; $w = $b.Width; $h = $b.Height; $md = $scr.DeviceName
+  }
+  else {
+    $w = $BoxW; $h = $BoxH; $x = $cur.X - [int]($BoxW / 2); $y = $cur.Y - [int]($BoxH / 2)
+  }
+  return @{ target = $tgt; x = $x; y = $y; w = $w; h = $h; winTitle = $wt; monDevice = $md; cursor = "$($cur.X),$($cur.Y)"; vs = $vs }
+}
+
+function Clamp-AxRect($t, [long]$MaxPixels) {
+  $vs = $t.vs
+  $left = [Math]::Max($t.x, $vs.Left); $top = [Math]::Max($t.y, $vs.Top)
+  $right = [Math]::Min($t.x + $t.w, $vs.Right); $bottom = [Math]::Min($t.y + $t.h, $vs.Bottom)
+  $cw = $right - $left; $ch = $bottom - $top
+  if ($cw -lt 1 -or $ch -lt 1) { throw "capture region does not overlap the screen (virtual screen $($vs.Width)x$($vs.Height) @ ($($vs.X),$($vs.Y))): requested $($t.w)x$($t.h) @ ($($t.x),$($t.y))" }
+  if ([long]$cw * [long]$ch -gt $MaxPixels) { throw "capture region too large: $($cw)x$($ch) = $([long]$cw * $ch)px > cap ${MaxPixels}px" }
+  $t.x = $left; $t.y = $top; $t.w = $cw; $t.h = $ch
+  return $t
+}
+
+# ---------------- redaction: window/app blocklist (denylist, §8·§14) ----------------
+# Design: for a (pixel) capture, Node doesn't know which windows are in that rect -> the backend must check "right before" CopyFromScreen
+#   so blocking is consistent across all modes (region/monitor/cursor/window) and on every watch/poll frame (codex BLOCKER). Zero cost when unconfigured.
+function Get-AxDenylist {
+  if ($null -ne $script:AxDenyCache) { return $script:AxDenyCache }   # env is fixed for the process lifetime -> parse once and cache
+  $titles = @(); $procs = @()
+  try { if ($env:VORTEX_CU_DENY_TITLES) { $titles = @([string[]]($env:VORTEX_CU_DENY_TITLES | ConvertFrom-Json)) } } catch {}
+  try { if ($env:VORTEX_CU_DENY_PROCS)  { $procs  = @([string[]]($env:VORTEX_CU_DENY_PROCS  | ConvertFrom-Json)) } } catch {}
+  $script:AxDenyCache = @{ titles = @($titles | Where-Object { $_ }); procs = @($procs | Where-Object { $_ }) }
+  return $script:AxDenyCache
+}
+
+function Test-AxDenyActive { $dl = Get-AxDenylist; return ($dl.titles.Count -gt 0 -or $dl.procs.Count -gt 0) }
+
+function Test-AxRectIntersect([int]$ax, [int]$ay, [int]$aw, [int]$ah, [int]$bx, [int]$by, [int]$bw, [int]$bh) {
+  return -not (($ax + $aw) -le $bx -or ($bx + $bw) -le $ax -or ($ay + $ah) -le $by -or ($by + $bh) -le $ay)
+}
+
+# If a denylist app/window (visibly) overlaps the capture rect ($t: x,y,w,h), return a block reason; otherwise $null. fail-closed:
+#   if window enumeration fails while the denylist is configured, or a proc rule exists but the process of an overlapping window can't be resolved -> block.
+# Uses EnumWindows to check every visible top-level window (not just the main one but popups/dialogs too, codex r2). Occluded windows are over-blocked on the safe side.
+# Limitations (documented): z-order is not considered (an occluded denylist window is still rejected — safe side); child (non-top-level) windows are covered by the parent rect.
+function Test-AxDenylist($t) {
+  $dl = Get-AxDenylist
+  if ($dl.titles.Count -eq 0 -and $dl.procs.Count -eq 0) { return $null }   # not configured -> skip the check entirely (zero cost)
+  $checkProc = $dl.procs.Count -gt 0
+  try { $wins = @([AxNative]::VisibleWindows()) }
+  catch { return @{ reason = 'denylist cannot be verified (window enumeration failed) — fail-closed'; match = '' } }
+  $procCache = @{}
+  foreach ($w in $wins) {
+    if (-not (Test-AxRectIntersect $t.x $t.y $t.w $t.h $w.Left $w.Top ($w.Right - $w.Left) ($w.Bottom - $w.Top))) { continue }
+    foreach ($dt in $dl.titles) {   # title checks are always trustworthy (read directly from the window, no process lookup needed)
+      if ($w.Title -and $w.Title.IndexOf($dt, [StringComparison]::OrdinalIgnoreCase) -ge 0) { return @{ reason = 'denylisted window title in capture region'; match = $dt } }
+    }
+    if ($checkProc) {
+      $info = $procCache[$w.Pid]
+      if ($null -eq $info) {
+        try { $pp = Get-Process -Id ([int]$w.Pid) -ErrorAction Stop; $ppath = $null; try { $ppath = $pp.Path } catch {}; $info = @{ name = $pp.ProcessName; path = $ppath } }
+        catch { return @{ reason = 'denylisted-process rule active but a visible window in the capture region has an unresolvable process — fail-closed'; match = '' } }
+        $procCache[$w.Pid] = $info
+      }
+      foreach ($dp in $dl.procs) {
+        if ($info.name -and $info.name.IndexOf($dp, [StringComparison]::OrdinalIgnoreCase) -ge 0) { return @{ reason = 'denylisted process in capture region'; match = $dp } }
+        if ($info.path -and $info.path.IndexOf($dp, [StringComparison]::OrdinalIgnoreCase) -ge 0) { return @{ reason = 'denylisted process path in capture region'; match = $dp } }
+      }
+    }
+  }
+  return $null
+}
+
+# Denylist check by the title/process of a UIA element (top-level window) — for the read_ui path. fail-closed:
+#   if a rule exists but the title/process can't be evaluated (null / lookup failure), block (codex r2 HIGH). Single target, so the over-blocking risk is low.
+function Test-AxDenylistElement([string]$Title, $ProcId) {
+  $dl = Get-AxDenylist
+  if ($dl.titles.Count -eq 0 -and $dl.procs.Count -eq 0) { return $null }
+  if ($dl.titles.Count -gt 0) {
+    if ([string]::IsNullOrEmpty($Title)) { return @{ reason = 'title-deny rule active but target window title is unavailable — fail-closed'; match = '' } }
+    foreach ($dt in $dl.titles) {
+      if ($Title.IndexOf($dt, [StringComparison]::OrdinalIgnoreCase) -ge 0) { return @{ reason = 'denylisted window title'; match = $dt } }
+    }
+  }
+  if ($dl.procs.Count -gt 0) {
+    if (-not $ProcId) { return @{ reason = 'process-deny rule active but target process id is unavailable — fail-closed'; match = '' } }
+    try {
+      $p = Get-Process -Id ([int]$ProcId) -ErrorAction Stop
+      $pname = $p.ProcessName; $ppath = $null; try { $ppath = $p.Path } catch {}
+      foreach ($dp in $dl.procs) {
+        if ($pname -and $pname.IndexOf($dp, [StringComparison]::OrdinalIgnoreCase) -ge 0) { return @{ reason = 'denylisted process'; match = $dp } }
+        if ($ppath -and $ppath.IndexOf($dp, [StringComparison]::OrdinalIgnoreCase) -ge 0) { return @{ reason = 'denylisted process path'; match = $dp } }
+      }
+    } catch { return @{ reason = 'denylist cannot verify process (fail-closed)'; match = '' } }
+  }
+  return $null
+}
+
+function Get-AxSignature([System.Drawing.Bitmap]$bmp) {
+  $S = 32; $sig = [byte[]]::new($S * $S)
+  $tmp = New-Object System.Drawing.Bitmap $S, $S; $g = $null
+  try {
+    $g = [System.Drawing.Graphics]::FromImage($tmp)
+    $g.InterpolationMode = [System.Drawing.Drawing2D.InterpolationMode]::HighQualityBicubic
+    $g.DrawImage($bmp, 0, 0, $S, $S)
+    for ($yy = 0; $yy -lt $S; $yy++) { for ($xx = 0; $xx -lt $S; $xx++) {
+      $px = $tmp.GetPixel($xx, $yy); $sig[$yy * $S + $xx] = [byte](($px.R * 30 + $px.G * 59 + $px.B * 11) / 100)
+    } }
+  } finally { if ($g) { $g.Dispose() }; $tmp.Dispose() }
+  return $sig
+}
+function Get-AxSigDiffPct($a, $b) {
+  if ($null -eq $a -or $null -eq $b) { return 100.0 }
+  $sum = 0.0
+  for ($i = 0; $i -lt $a.Length; $i++) { $sum += [Math]::Abs([int]$a[$i] - [int]$b[$i]) }
+  return [Math]::Round($sum / $a.Length / 255.0 * 100.0, 2)
+}
+
+function Invoke-AxCapture {
+  param(
+    [int]$BoxW = 600, [int]$BoxH = 400, [double]$Scale = 0, [int]$MaxSide = 0, [long]$MaxPixels = 40000000,
+    [string]$Detail = 'normal',
+    [string]$Region = '', [string]$WindowMatch = '', [string]$Monitor = '',
+    [int]$WatchFrames = 1, [int]$IntervalMs = 1000, [switch]$ChangeOnly, [double]$ChangeThreshold = 2.0,
+    [string]$OutDir = (Join-Path $env:TEMP 'vortex-ax-poc')
+  )
+  $preset = Get-AxDetailPreset $Detail   # an explicit scale/maxSide (>0) takes precedence over the preset
+  if ($Scale -le 0) { $Scale = $preset.scale }
+  if ($MaxSide -le 0) { $MaxSide = $preset.maxSide }
+  if (-not (Test-Path $OutDir)) { New-Item -ItemType Directory -Force -Path $OutDir | Out-Null }
+  Remove-AxStale $OutDir
+  $nFrames = [Math]::Max(1, $WatchFrames)
+  $frames = @(); $prevSig = $null; $saved = 0; $last = $null
+  for ($f = 0; $f -lt $nFrames; $f++) {
+    if ($f -gt 0 -and $IntervalMs -gt 0) { Start-Sleep -Milliseconds $IntervalMs }
+    $sw = [System.Diagnostics.Stopwatch]::StartNew()
+    $t = Clamp-AxRect (Resolve-AxTarget $Region $WindowMatch $Monitor $BoxW $BoxH) $MaxPixels
+    $last = $t
+    $deny = Test-AxDenylist $t   # block right before CopyFromScreen — if a denylist app overlaps the rect, refuse to capture this frame (fail-closed)
+    if ($deny) {
+      $sw.Stop()
+      $frames += [ordered]@{ frame = $f; redacted = $true; reason = $deny.reason; saved = $false; elapsedMs = [math]::Round($sw.Elapsed.TotalMilliseconds, 1) }
+      continue
+    }
+    $src = $null; $dst = $null; $g = $null; $g2 = $null
+    try {
+      $src = New-Object System.Drawing.Bitmap $t.w, $t.h
+      $g = [System.Drawing.Graphics]::FromImage($src)
+      $g.CopyFromScreen($t.x, $t.y, 0, 0, (New-Object System.Drawing.Size $t.w, $t.h))
+      $sig = Get-AxSignature $src
+      $diffPct = Get-AxSigDiffPct $prevSig $sig
+      $changed = ($f -eq 0) -or ($diffPct -ge $ChangeThreshold)
+      $prevSig = $sig
+      if ($ChangeOnly -and -not $changed) {
+        $sw.Stop()
+        $frames += [ordered]@{ frame = $f; changed = $false; changePct = $diffPct; saved = $false; elapsedMs = [math]::Round($sw.Elapsed.TotalMilliseconds, 1) }
+        continue
+      }
+      $effScale = [Math]::Min($Scale, [Math]::Min($MaxSide / $t.w, $MaxSide / $t.h))
+      if ($effScale -le 0) { $effScale = 1.0 }
+      $outW = [Math]::Max(1, [int]($t.w * $effScale)); $outH = [Math]::Max(1, [int]($t.h * $effScale))
+      $dst = New-Object System.Drawing.Bitmap $outW, $outH
+      $g2 = [System.Drawing.Graphics]::FromImage($dst)
+      $g2.InterpolationMode = [System.Drawing.Drawing2D.InterpolationMode]::HighQualityBicubic
+      $g2.DrawImage($src, 0, 0, $outW, $outH)
+      $path = New-AxOutPath $OutDir ($(if ($nFrames -gt 1) { $f } else { $null }))
+      $dst.Save($path, [System.Drawing.Imaging.ImageFormat]::Png)
+      $sw.Stop(); $saved++
+      $frames += [ordered]@{
+        frame = $f; changed = $changed; changePct = $diffPct; saved = $true; path = $path
+        captureRect = "$($t.w)x$($t.h) @ ($($t.x),$($t.y))"; scale = [math]::Round($effScale, 3)
+        outputSize = "$($outW)x$($outH)"; approxTokens = [int]($outW * $outH / 750)
+        elapsedMs = [math]::Round($sw.Elapsed.TotalMilliseconds, 1); bytes = (Get-Item $path).Length
+      }
+    } finally {
+      if ($g2) { $g2.Dispose() }
+      if ($dst) { $dst.Dispose() }
+      if ($g) { $g.Dispose() }
+      if ($src) { $src.Dispose() }
+    }
+  }
+  $vsStr = "$($last.vs.Width)x$($last.vs.Height) @ ($($last.vs.X),$($last.vs.Y))"
+  if ($nFrames -le 1) {
+    $fr = $frames[0]
+    if ($fr.redacted) {
+      $meta = [ordered]@{
+        target = $last.target; redacted = $true; reason = $fr.reason; dpiMode = (Get-AxDpiMode)
+        captureRect = "$($last.w)x$($last.h) @ ($($last.x),$($last.y))"; elapsedMs = $fr.elapsedMs
+      }
+    } else {
+      $meta = [ordered]@{
+        target = $last.target; path = $fr.path; dpiMode = (Get-AxDpiMode); cursor = $last.cursor; virtualScreen = $vsStr
+        captureRect = $fr.captureRect; scale = $fr.scale; outputSize = $fr.outputSize; approxTokens = $fr.approxTokens; elapsedMs = $fr.elapsedMs; bytes = $fr.bytes
+      }
+    }
+  } else {
+    $meta = [ordered]@{
+      target = $last.target; watch = $true; dpiMode = (Get-AxDpiMode); virtualScreen = $vsStr
+      frames = $nFrames; intervalMs = $IntervalMs; changeOnly = [bool]$ChangeOnly; changeThreshold = $ChangeThreshold; saved = $saved; captures = $frames
+    }
+    # Aggregate redaction across multiframe too — if even one frame is redacted, surface it at top-level (audit + prevent title leakage, codex r3 MEDIUM).
+    $redCount = @($frames | Where-Object { $_.redacted }).Count
+    if ($redCount -gt 0) { if ($redCount -ge $frames.Count) { $meta.redacted = $true } else { $meta.partialRedacted = $true } }
+  }
+  # When redacted/partialRedacted, don't expose the denylist window title in the meta (codex r2·r3 MEDIUM).
+  $anyRedacted = ($meta.redacted -eq $true) -or ($meta.partialRedacted -eq $true)
+  if ($last.winTitle -and -not $anyRedacted) { $meta.window = $last.winTitle }
+  if ($last.monDevice -and -not $anyRedacted) { $meta.monitor = $last.monDevice }
+  return $meta
+}
+
+# ---------------- poll_change (single-shot polling primitive for async watch) ----------------
+# Capture the target once -> compare with the previous signature -> immediately return only the change rate. The previous state is kept
+# in the worker's (long-lived process) script scope per watchId -> continuity is preserved across calls (the agent polls every 1-2 seconds). PNG is saved only on changed/baseline.
+if ($null -eq $script:AxWatchState) { $script:AxWatchState = [System.Collections.Hashtable]::new([System.StringComparer]::Ordinal) }  # case-sensitive — prevents watchId slot mix-ups
+
+function Invoke-AxPollChange {
+  param(
+    [int]$BoxW = 600, [int]$BoxH = 400, [double]$Scale = 0, [int]$MaxSide = 0, [long]$MaxPixels = 40000000,
+    [string]$Detail = 'normal', [switch]$IncludeImage,
+    [string]$Region = '', [string]$WindowMatch = '', [string]$Monitor = '',
+    [double]$ChangeThreshold = 2.0, [string]$WatchId = 'default', [switch]$Reset,
+    [string]$OutDir = (Join-Path $env:TEMP 'vortex-ax-poc')
+  )
+  $preset = Get-AxDetailPreset $Detail   # an explicit scale/maxSide (>0) takes precedence over the preset
+  if ($Scale -le 0) { $Scale = $preset.scale }
+  if ($MaxSide -le 0) { $MaxSide = $preset.maxSide }
+  if (-not (Test-Path $OutDir)) { New-Item -ItemType Directory -Force -Path $OutDir | Out-Null }
+  Remove-AxStale $OutDir
+  $sw = [System.Diagnostics.Stopwatch]::StartNew()
+  $t = Clamp-AxRect (Resolve-AxTarget $Region $WindowMatch $Monitor $BoxW $BoxH) $MaxPixels
+  # poll_change captures the screen into memory for the change signature even without includeImage -> always pre-check the denylist (fail-closed).
+  $deny = Test-AxDenylist $t
+  if ($deny) {
+    $sw.Stop()
+    return [ordered]@{
+      target = $t.target; watchId = $WatchId; redacted = $true; reason = $deny.reason
+      captureRect = "$($t.w)x$($t.h) @ ($($t.x),$($t.y))"; dpiMode = (Get-AxDpiMode); elapsedMs = [math]::Round($sw.Elapsed.TotalMilliseconds, 1)
+    }
+  }
+  $src = $null; $dst = $null; $g = $null; $g2 = $null
+  try {
+    $src = New-Object System.Drawing.Bitmap $t.w, $t.h
+    $g = [System.Drawing.Graphics]::FromImage($src)
+    $g.CopyFromScreen($t.x, $t.y, 0, 0, (New-Object System.Drawing.Size $t.w, $t.h))
+    $sig = Get-AxSignature $src
+
+    $prev = if ($Reset) { $null } else { $script:AxWatchState[$WatchId] }
+    $baseline = ($null -eq $prev)
+    $diffPct = if ($baseline) { 0.0 } else { Get-AxSigDiffPct $prev $sig }
+    $changed = (-not $baseline) -and ($diffPct -ge $ChangeThreshold)
+    $script:AxWatchState[$WatchId] = $sig    # update the previous state (continuity)
+
+    $path = $null; $outW = 0; $outH = 0
+    # Default is metadata only (no image saved = token savings). Save only when includeImage, and only when there's something to see (baseline/changed).
+    if ($IncludeImage -and ($baseline -or $changed)) {
+      $effScale = [Math]::Min($Scale, [Math]::Min($MaxSide / $t.w, $MaxSide / $t.h))
+      if ($effScale -le 0) { $effScale = 1.0 }
+      $outW = [Math]::Max(1, [int]($t.w * $effScale)); $outH = [Math]::Max(1, [int]($t.h * $effScale))
+      $dst = New-Object System.Drawing.Bitmap $outW, $outH
+      $g2 = [System.Drawing.Graphics]::FromImage($dst)
+      $g2.InterpolationMode = [System.Drawing.Drawing2D.InterpolationMode]::HighQualityBicubic
+      $g2.DrawImage($src, 0, 0, $outW, $outH)
+      $path = New-AxOutPath $OutDir
+      $dst.Save($path, [System.Drawing.Imaging.ImageFormat]::Png)
+    }
+    $sw.Stop()
+    $meta = [ordered]@{
+      target = $t.target; watchId = $WatchId; baseline = $baseline; changed = $changed
+      changePct = $diffPct; threshold = $ChangeThreshold
+      captureRect = "$($t.w)x$($t.h) @ ($($t.x),$($t.y))"; dpiMode = (Get-AxDpiMode)
+      elapsedMs = [math]::Round($sw.Elapsed.TotalMilliseconds, 1)
+    }
+    if ($path) { $meta.path = $path; $meta.outputSize = "$($outW)x$($outH)"; $meta.approxTokens = [int]($outW * $outH / 750); $meta.bytes = (Get-Item $path).Length }
+    if ($t.winTitle) { $meta.window = $t.winTitle }
+    if ($t.monDevice) { $meta.monitor = $t.monDevice }
+    return $meta
+  } finally {
+    if ($g2) { $g2.Dispose() }
+    if ($dst) { $dst.Dispose() }
+    if ($g) { $g.Dispose() }
+    if ($src) { $src.Dispose() }
+  }
+}
+
+# ---------------- read_ui ----------------
+function Format-AxTrunc([string]$s, [int]$n = 80) {
+  if ([string]::IsNullOrEmpty($s)) { return "" }
+  $s = $s -replace '\s+', ' '
+  if ($s.Length -gt $n) { return $s.Substring(0, $n - 1) + "…" } else { return $s }
+}
+
+function Get-AxElementText($el, $textPat, [int]$TextCap) {
+  $tp = $null
+  if (-not $el.TryGetCurrentPattern($textPat, [ref]$tp)) { return $null }
+  $t0 = [System.Diagnostics.Stopwatch]::StartNew(); $out = ""
+  try {
+    $ranges = $tp.GetVisibleRanges()
+    foreach ($r in $ranges) { $out += $r.GetText($TextCap); if ($out.Length -ge $TextCap) { break } }
+  } catch { try { $out = $tp.DocumentRange.GetText($TextCap) } catch {} }
+  $t0.Stop(); $script:AxTextMs += $t0.Elapsed.TotalMilliseconds
+  if ($out) { $script:AxTextHits++ }
+  return ($out -replace '\s+\r?\n', "`n").Trim()
+}
+
+function Read-AxEl($el, [int]$depth, $ctx) {
+  if ($null -eq $el -or $script:AxCount -ge $ctx.MaxElements) { return $null }
+  $c = $el.Current; $r = $c.BoundingRectangle
+  $isPw = $false; try { $isPw = [bool]$c.IsPassword } catch {}   # password field (§8·§14)
+  $rectStr = if ($r.IsEmpty) { "" } else { "$([int]$r.X),$([int]$r.Y) $([int]$r.Width)x$([int]$r.Height)" }
+  if ($isPw) {
+    # Password element: role/rect/redacted only. Don't emit name either (leak risk), and don't traverse children (a custom password control could leak via name/children, codex r2 HIGH).
+    $script:AxCount++
+    return [ordered]@{ d = $depth; role = ($c.ControlType.ProgrammaticName -replace '^ControlType\.', ''); rect = $rectStr; redacted = $true }
+  }
+  $node = [ordered]@{
+    d = $depth; role = ($c.ControlType.ProgrammaticName -replace '^ControlType\.', ''); name = Format-AxTrunc $c.Name
+    rect = $rectStr
+  }
+  if ($c.AutomationId) { $node.id = Format-AxTrunc $c.AutomationId 40 }
+  $vobj = $null
+  if ($el.TryGetCurrentPattern($ctx.ValuePat, [ref]$vobj)) { $vv = $vobj.Current.Value; if ($vv) { $node.value = Format-AxTrunc $vv } }
+  $txt = Get-AxElementText $el $ctx.TextPat $ctx.TextCap
+  if ($txt) { $node.text = Format-AxTrunc $txt 400 }
+  if ($c.IsOffscreen) { $node.offscreen = $true }
+  $script:AxCount++
+  $kids = @()
+  if ($depth -lt $ctx.MaxDepth) {
+    $child = $ctx.Walker.GetFirstChild($el)
+    while ($null -ne $child -and $script:AxCount -lt $ctx.MaxElements) {
+      $k = Read-AxEl $child ($depth + 1) $ctx
+      if ($k) { $kids += $k }
+      $child = $ctx.Walker.GetNextSibling($child)
+    }
+  }
+  if ($kids.Count -gt 0) { $node.children = $kids }
+  return $node
+}
+
+function Get-AxReadUi([int]$MaxDepth = 5, [int]$MaxElements = 70, [int]$TextCap = 1500, [string]$Target = 'foreground', [string]$WindowMatch = '') {
+  $AE = [System.Windows.Automation.AutomationElement]
+  $ctx = @{
+    ValuePat = [System.Windows.Automation.ValuePattern]::Pattern
+    TextPat  = [System.Windows.Automation.TextPattern]::Pattern
+    Walker   = [System.Windows.Automation.TreeWalker]::ControlViewWalker
+    MaxDepth = $MaxDepth; MaxElements = $MaxElements; TextCap = $TextCap
+  }
+  $script:AxCount = 0; $script:AxTextMs = 0.0; $script:AxTextHits = 0
+  $sw = [System.Diagnostics.Stopwatch]::StartNew()
+  if ($WindowMatch) {
+    $kids = $AE::RootElement.FindAll([System.Windows.Automation.TreeScope]::Children, [System.Windows.Automation.Condition]::TrueCondition)
+    $hits = @()
+    foreach ($w in $kids) { $nm = $w.Current.Name; if ($nm -and $nm.IndexOf($WindowMatch, [StringComparison]::OrdinalIgnoreCase) -ge 0) { $hits += $w } }
+    if ($hits.Count -eq 0) { throw "window not found: '$WindowMatch'" }
+    $exact = @($hits | Where-Object { $_.Current.Name -eq $WindowMatch })
+    if ($exact.Count -ge 1) { $hits = $exact }
+    if ($hits.Count -gt 1) {
+      if (Test-AxDenyActive) { throw "multiple windows matched ('$WindowMatch') — specify a more precise title (candidate titles omitted: denylist active)" }
+      $titles = @($hits | ForEach-Object { $_.Current.Name } | Select-Object -Unique)
+      throw "multiple windows matched ('$WindowMatch') — specify a more precise title: $([string]::Join(' | ', $titles))"
+    }
+    $root = $hits[0]
+  } elseif ($Target -eq 'cursor') {
+    $cur = [System.Windows.Forms.Cursor]::Position
+    $root = $AE::FromPoint((New-Object System.Windows.Point $cur.X, $cur.Y))
+  } else {
+    $root = $AE::FromHandle([AxNative]::GetForegroundWindow())
+  }
+  if ($null -eq $root) { throw "target window not found" }
+  # denylist: check by the title/process of the owning top-level window. Cursor mode can start from a child element, so walk up to the top-level (codex HIGH).
+  $top = $root
+  try {
+    while ($null -ne $top) {
+      $par = $ctx.Walker.GetParent($top)
+      if ($null -eq $par -or $par -eq $AE::RootElement) { break }
+      $top = $par
+    }
+  } catch { $top = $root }
+  $denyTitle = $null; $denyPid = $null
+  try { $denyTitle = $top.Current.Name } catch {}
+  try { $denyPid = $top.Current.ProcessId } catch {}
+  $deny = Test-AxDenylistElement $denyTitle $denyPid
+  if ($deny) {
+    return [ordered]@{ target = $Target; redacted = $true; reason = $deny.reason; elements = 0; imageTokens = 0 }
+  }
+  $tree = Read-AxEl $root 0 $ctx
+  $sw.Stop()
+  return [ordered]@{
+    target = $Target
+    window = [ordered]@{ name = $tree.name; role = $tree.role; rect = $tree.rect }
+    elements = $script:AxCount; elapsedMs = [math]::Round($sw.Elapsed.TotalMilliseconds, 1)
+    textPatternMs = [math]::Round($script:AxTextMs, 1); textHits = $script:AxTextHits; imageTokens = 0; tree = $tree
+  }
+}