@ai-agent-forge/plugin-desktop-windows-observe 0.85.0

package/dist/windows-uia-adapter.js

@@ -0,0 +1,711 @@
+/**
+ * Inlined from agent-forge `src/plugins/desktop/windows-uia-adapter.ts`
+ * (D-075 S3 extraction) so this package keeps its dependency closure limited
+ * to the plugin SDK and typebox. Semantics are unchanged: the full driver
+ * (query + action PowerShell scripts) is carried completely even though this
+ * observe package only exposes the read-only capability surface. This file is
+ * a deliberate copy shared (not imported) with
+ * `plugins/desktop-windows-input/src/windows-uia-adapter.ts`; keep both
+ * copies in sync.
+ */
+import { spawnSync as nodeSpawnSync } from "node:child_process";
+import { detachedFreeze } from "@agent-forge/plugin-sdk";
+import { findDesktopReplaySessionMismatch, requiresDesktopUserConfirmation } from "./types.js";
+const READONLY_CAPABILITIES = ["desktop-session", "desktop-uia"];
+const SUPPORTED_ACTIONS = [
+    "focus",
+    "click",
+    "type",
+    "key",
+    "scroll",
+];
+const error = (code, message, causeCode) => ({
+    version: 1,
+    code,
+    message,
+    ...(causeCode === undefined ? {} : { causeCode }),
+});
+const unsupported = (operationId, reason, causeCode = "platform-unavailable") => ({
+    version: 1,
+    operationId,
+    status: "unsupported",
+    summary: reason,
+    error: error(causeCode === "action-unsupported" ? "action_unsupported" : "platform_unavailable", reason, causeCode),
+});
+const rectangle = (raw) => ({
+    x: Number.isFinite(raw.x) ? Number(raw.x) : 0,
+    y: Number.isFinite(raw.y) ? Number(raw.y) : 0,
+    width: Number.isFinite(raw.width) ? Number(raw.width) : 0,
+    height: Number.isFinite(raw.height) ? Number(raw.height) : 0,
+});
+const QUERY_SCRIPT = `
+try {
+  Add-Type -AssemblyName UIAutomationClient -ErrorAction Stop
+  Add-Type -AssemblyName UIAutomationTypes -ErrorAction Stop
+  function SafeInt($value) {
+    $number = [double]$value
+    if ([double]::IsNaN($number) -or [double]::IsInfinity($number)) { return 0 }
+    return [int][math]::Round($number)
+  }
+  function Get-ControlId($node, [int]$index) {
+    $automationId = [string]$node.Current.AutomationId
+    $name = [string]$node.Current.Name
+    $role = [string]$node.Current.ControlType.ProgrammaticName
+    if ($automationId.Length -gt 0) { return $automationId }
+    if ($name.Length -gt 0) { return $role + ':' + $name }
+    return $role + ':' + $index
+  }
+  $root = [System.Windows.Automation.AutomationElement]::RootElement
+  $windowWalker = [System.Windows.Automation.TreeWalker]::ControlViewWalker
+  $windows = [System.Collections.Generic.List[object]]::new()
+  $controls = [System.Collections.Generic.List[object]]::new()
+  $focusedMatches = [System.Collections.Generic.List[object]]::new()
+  $focused = $null
+  try { $focused = [System.Windows.Automation.AutomationElement]::FocusedElement } catch {}
+  $maxWindows = 256
+  $maxControlsPerWindow = 1000
+  $maxControlsTotal = 10000
+  $maxDepth = 32
+  function Add-Descendants($node, [int64]$windowHandle, [int]$depth, [ref]$count) {
+    if ($null -eq $node -or $depth -gt $maxDepth -or $count.Value -ge $maxControlsPerWindow -or $controls.Count -ge $maxControlsTotal) { return }
+    $index = $count.Value
+    $count.Value = $count.Value + 1
+    $childRect = $node.Current.BoundingRectangle
+    $controlId = Get-ControlId $node $index
+    $value = $null
+    try {
+      $pattern = $null
+      if ($node.TryGetCurrentPattern([System.Windows.Automation.ValuePattern]::Pattern, [ref]$pattern)) { $value = [string]$pattern.Current.Value }
+    } catch {}
+    $name = [string]$node.Current.Name
+    $nativeWindowHandle = [int64]$node.Current.NativeWindowHandle
+    if ($null -eq $value -and $name.Length -gt 0) { $value = $name }
+    $controls.Add([pscustomobject]@{ windowHandle=$windowHandle; nativeWindowHandle=$nativeWindowHandle; controlId=$controlId; name=$name; role=[string]$node.Current.ControlType.ProgrammaticName; enabled=[bool]$node.Current.IsEnabled; value=$value; x=(SafeInt $childRect.X); y=(SafeInt $childRect.Y); width=(SafeInt $childRect.Width); height=(SafeInt $childRect.Height) })
+    try {
+      if ($null -ne $focused -and $node.Equals($focused)) { $focusedMatches.Add([pscustomobject]@{ windowHandle=$windowHandle; controlId=$controlId }) }
+    } catch {}
+    $child = $windowWalker.GetFirstChild($node)
+    while ($null -ne $child -and $count.Value -lt $maxControlsPerWindow) {
+      Add-Descendants $child $windowHandle ($depth + 1) $count
+      $child = $windowWalker.GetNextSibling($child)
+    }
+  }
+  $window = $windowWalker.GetFirstChild($root)
+  $windowCount = 0
+  while ($null -ne $window -and $windowCount -lt $maxWindows) {
+    $handle = [int64]$window.Current.NativeWindowHandle
+    if ($handle -ne 0) {
+      $rect = $window.Current.BoundingRectangle
+      $processId = [int]$window.Current.ProcessId
+      $windows.Add([pscustomobject]@{ handle=$handle; processId=$processId; name=[string]$window.Current.Name; x=(SafeInt $rect.X); y=(SafeInt $rect.Y); width=(SafeInt $rect.Width); height=(SafeInt $rect.Height) })
+      $windowCount++
+      $child = $windowWalker.GetFirstChild($window)
+      $count = 0
+      while ($null -ne $child -and $count -lt $maxControlsPerWindow -and $controls.Count -lt $maxControlsTotal) {
+        Add-Descendants $child $handle 1 ([ref]$count)
+        $child = $windowWalker.GetNextSibling($child)
+      }
+    }
+    $window = $windowWalker.GetNextSibling($window)
+  }
+  $focusedControl = if ($focusedMatches.Count -gt 0) { $focusedMatches[0] } else { $null }
+  [pscustomobject]@{ windows=@($windows); controls=@($controls); focusedControl=$focusedControl; available=$true } | ConvertTo-Json -Compress -Depth 8
+} catch {
+  [pscustomobject]@{ available=$false; error=[string]$_.Exception.Message } | ConvertTo-Json -Compress -Depth 5
+}`;
+const ACTION_SCRIPT = `
+try {
+  Add-Type -AssemblyName UIAutomationClient -ErrorAction Stop
+  Add-Type -AssemblyName UIAutomationTypes -ErrorAction Stop
+  $payload = $env:AGENT_FORGE_UIA_INPUT | ConvertFrom-Json
+  $handle = [int64]$payload.target.windowHandle
+  $window = [System.Windows.Automation.AutomationElement]::FromHandle([IntPtr]$handle)
+  if ($null -eq $window) { throw 'Window handle is no longer available' }
+  $walker = [System.Windows.Automation.TreeWalker]::ControlViewWalker
+  $target = $window
+  $script:AgentForgeTarget = $null
+  if ($null -ne $payload.target.controlId) {
+    $controlHandle = [int64]$payload.target.controlWindowHandle
+    if ($controlHandle -gt 0) {
+      try {
+        $candidate = [System.Windows.Automation.AutomationElement]::FromHandle([IntPtr]$controlHandle)
+        if ($null -ne $candidate) {
+          $candidateAutomationId = [string]$candidate.Current.AutomationId
+          $candidateName = [string]$candidate.Current.Name
+          $candidateRole = [string]$candidate.Current.ControlType.ProgrammaticName
+          $candidateId = if ($candidateAutomationId.Length -gt 0) { $candidateAutomationId } elseif ($candidateName.Length -gt 0) { $candidateRole + ':' + $candidateName } else { $null }
+          if ($candidateId -eq [string]$payload.target.controlId) { $script:AgentForgeTarget = $candidate }
+        }
+      } catch {}
+    }
+    $maxDepth = 32
+    $maxVisited = 1000
+    function Find-Descendant($node, [int]$depth, [ref]$visited) {
+      if ($null -eq $node -or $depth -gt $maxDepth -or $visited.Value -ge $maxVisited -or $null -ne $script:AgentForgeTarget) { return }
+      $visited.Value = $visited.Value + 1
+      $automationId = [string]$node.Current.AutomationId
+      $name = [string]$node.Current.Name
+      $role = [string]$node.Current.ControlType.ProgrammaticName
+      $id = if ($automationId.Length -gt 0) { $automationId } elseif ($name.Length -gt 0) { $role + ':' + $name } else { $role + ':' + ($visited.Value - 1) }
+      if ($id -eq [string]$payload.target.controlId) { $script:AgentForgeTarget = $node; return }
+      $child = $walker.GetFirstChild($node)
+      while ($null -ne $child -and $visited.Value -lt $maxVisited -and $null -eq $script:AgentForgeTarget) {
+        Find-Descendant $child ($depth + 1) $visited
+        $child = $walker.GetNextSibling($child)
+      }
+    }
+    $visited = 0
+    if ($null -eq $script:AgentForgeTarget) {
+      $node = $walker.GetFirstChild($window)
+      while ($null -ne $node -and $visited -lt $maxVisited -and $null -eq $script:AgentForgeTarget) {
+        Find-Descendant $node 1 ([ref]$visited)
+        $node = $walker.GetNextSibling($node)
+      }
+    }
+    if ($null -eq $script:AgentForgeTarget) { throw ('Control was not found: ' + [string]$payload.target.controlId) }
+    $target = $script:AgentForgeTarget
+  }
+  if ($payload.action.kind -eq 'focus') { $target.SetFocus() }
+  elseif ($payload.action.kind -eq 'click') {
+    $pattern = $null
+    $invoked = $false
+    try {
+      if ($target.TryGetCurrentPattern([System.Windows.Automation.InvokePattern]::Pattern, [ref]$pattern)) {
+        $pattern.Invoke()
+        $invoked = $true
+      }
+    } catch {}
+    if (-not $invoked) {
+      if ($controlHandle -le 0) { throw 'Control does not support InvokePattern' }
+      try {
+        Add-Type @'
+using System;
+using System.Runtime.InteropServices;
+public static class AgentForgeNativeClick {
+  [DllImport("user32.dll", CharSet=CharSet.Unicode, SetLastError=true)]
+  public static extern IntPtr SendMessageTimeout(IntPtr hWnd, uint Msg, IntPtr wParam, IntPtr lParam, uint flags, uint timeout, out IntPtr result);
+}
+'@
+        $sendResult = [IntPtr]::Zero
+        $callResult = [AgentForgeNativeClick]::SendMessageTimeout([IntPtr]$controlHandle, 0x00F5, [IntPtr]::Zero, [IntPtr]::Zero, 0x0002, 3000, [ref]$sendResult)
+        if ($callResult -eq [IntPtr]::Zero) { throw 'Target click failed' }
+      } catch { throw 'Target click failed' }
+    }
+  } elseif ($payload.action.kind -eq 'type') {
+    $pattern = $null
+    $set = $false
+    try {
+      if ($target.TryGetCurrentPattern([System.Windows.Automation.ValuePattern]::Pattern, [ref]$pattern)) {
+        $pattern.SetValue([string]$payload.action.text)
+        $set = $true
+      }
+    } catch {}
+    if (-not $set) {
+      $legacy = $null
+      try {
+        if ($target.TryGetCurrentPattern([System.Windows.Automation.LegacyIAccessiblePattern]::Pattern, [ref]$legacy)) {
+          $legacy.SetValue([string]$payload.action.text)
+          $set = $true
+        }
+      } catch {}
+    }
+    if (-not $set) {
+      if ($controlHandle -le 0) { throw 'Control does not support ValuePattern or LegacyIAccessiblePattern' }
+      try {
+        Add-Type @'
+using System;
+using System.Runtime.InteropServices;
+public static class AgentForgeNativeText {
+  [DllImport("user32.dll", CharSet=CharSet.Unicode, SetLastError=true)]
+  public static extern IntPtr SendMessageTimeout(IntPtr hWnd, uint Msg, IntPtr wParam, string lParam, uint flags, uint timeout, out IntPtr result);
+}
+'@
+        $sendResult = [IntPtr]::Zero
+        $callResult = [AgentForgeNativeText]::SendMessageTimeout([IntPtr]$controlHandle, 0x000C, [IntPtr]::Zero, [string]$payload.action.text, 0x0002, 3000, [ref]$sendResult)
+        if ($callResult -eq [IntPtr]::Zero -or $sendResult -eq [IntPtr]::Zero) { throw 'Target text update failed' }
+      } catch { throw 'Target text update failed' }
+    }
+  } elseif ($payload.action.kind -eq 'key') {
+    $keyText = [string]$payload.action.key
+    $hasSendKeysSyntax = $keyText -match '[+%^{}]'
+    if (-not $hasSendKeysSyntax -and $controlHandle -gt 0) {
+      # Plain text with a real control handle: deliver synchronously through
+      # SendMessage WM_CHAR. Queued input (SendInput / WScript SendKeys) never
+      # reaches GUI windows in non-interactive or remote desktop sessions, while
+      # synchronous SendMessage does — the same path that type (WM_SETTEXT) and
+      # click (BM_CLICK) already use. Keyboard focus is not required.
+      Add-Type @'
+using System;
+using System.Runtime.InteropServices;
+public static class AgentForgeNativeKey {
+  [DllImport("user32.dll", SetLastError=true)] public static extern IntPtr SendMessage(IntPtr hWnd, uint Msg, IntPtr wParam, IntPtr lParam);
+}
+'@
+      foreach ($ch in $keyText.ToCharArray()) {
+        [AgentForgeNativeKey]::SendMessage([IntPtr]$controlHandle, 0x0102, [IntPtr][char]$ch, [IntPtr]::Zero) | Out-Null
+      }
+    } else {
+      if ($payload.target.controlId) { $target.SetFocus() }
+      $wshell = New-Object -ComObject WScript.Shell
+      $wshell.SendKeys($keyText)
+    }
+  } elseif ($payload.action.kind -eq 'scroll') {
+    Add-Type @'
+using System;
+using System.Runtime.InteropServices;
+public static class AgentForgeNativeScroll {
+  [DllImport("user32.dll", SetLastError=true)]
+  public static extern bool SetCursorPos(int X, int Y);
+  [DllImport("user32.dll")]
+  public static extern void mouse_event(uint dwFlags, int dx, int dy, int dwData, UIntPtr dwExtraInfo);
+}
+'@
+    $direction = [string]$payload.action.text
+    $directionMatch = [regex]::Match($direction, '^(up|down)(?::(\\d+))?$')
+    if (-not $directionMatch.Success) { throw 'Scroll direction must be up or down with optional :lines' }
+    $lines = if ($directionMatch.Groups[2].Value) { [int]$directionMatch.Groups[2].Value } else { 3 }
+    if ($lines -lt 1 -or $lines -gt 100) { throw 'Scroll lines must be between 1 and 100' }
+    try {
+      $rect = $target.Current.BoundingRectangle
+      $centerX = [int]($rect.X + $rect.Width / 2)
+      $centerY = [int]($rect.Y + $rect.Height / 2)
+      [AgentForgeNativeScroll]::SetCursorPos($centerX, $centerY) | Out-Null
+    } catch {}
+    $wheelDelta = 120 * $lines
+    if ($direction.StartsWith('down')) { $wheelDelta = -$wheelDelta }
+    [AgentForgeNativeScroll]::mouse_event(0x0800, 0, 0, $wheelDelta, [UIntPtr]::Zero)
+  } else { throw ('Action kind is not supported by UI Automation: ' + [string]$payload.action.kind) }
+  [pscustomobject]@{ ok=$true } | ConvertTo-Json -Compress
+} catch {
+  $message = [string]$_.Exception.Message
+  $code = if ($message -match 'Window handle is no longer available|Control was not found') { 'stale_target' } else { 'action_failed' }
+  $reason = if ($message -match 'ValuePattern|LegacyIAccessiblePattern') { 'value_pattern_unavailable' } elseif ($message -match 'InvokePattern') { 'invoke_pattern_unavailable' } elseif ($message -match 'SetFocus') { 'focus_failed' } else { 'uia_action_exception' }
+  [pscustomobject]@{ ok=$false; code=$code; reason=$reason } | ConvertTo-Json -Compress
+}`;
+const parseJson = (stdout) => {
+    try {
+        const parsed = JSON.parse(stdout.trim());
+        return typeof parsed === "object" && parsed !== null ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+export class WindowsUiAutomationDriver {
+    driverId = "windows-uia";
+    driverVersion = "1.0.0";
+    command;
+    timeoutMs;
+    platform;
+    spawn;
+    sessions = new Map();
+    targets = new Map();
+    sessionTargetKeys = new Map();
+    latestObservationIds = new Map();
+    observedSessions = new Set();
+    nextSessionId = 1;
+    nextObservationId = 1;
+    constructor(options = {}) {
+        this.command = options.command ?? "powershell.exe";
+        this.timeoutMs = options.timeoutMs ?? 15_000;
+        this.platform = options.platform ?? process.platform;
+        this.spawn =
+            options.spawnSync ??
+                ((command, args, spawnOptions) => nodeSpawnSync(command, args, spawnOptions));
+    }
+    probe() {
+        if (this.platform !== "win32") {
+            return {
+                available: false,
+                platform: this.platform,
+                driver: "windows-uia",
+                reason: "Windows UI Automation requires win32",
+            };
+        }
+        const result = this.run(QUERY_SCRIPT);
+        if (result === undefined)
+            return {
+                available: false,
+                platform: this.platform,
+                driver: "windows-uia",
+                reason: "PowerShell or UIAutomationClient is unavailable",
+            };
+        return result.available === true
+            ? {
+                available: true,
+                platform: this.platform,
+                driver: "windows-uia",
+                capabilities: READONLY_CAPABILITIES,
+            }
+            : {
+                available: false,
+                platform: this.platform,
+                driver: "windows-uia",
+                reason: "UI Automation probe failed",
+            };
+    }
+    openSession(request) {
+        const probe = this.probe();
+        if (!probe.available)
+            return {
+                status: "unsupported",
+                error: error("platform_unavailable", probe.reason ?? "Windows UI Automation is unavailable", "platform-unavailable"),
+            };
+        const session = detachedFreeze({
+            version: 1,
+            sessionId: `desktop-windows-session-${this.nextSessionId++}`,
+            isolation: request.isolation,
+            status: "ready",
+            ...(request.applicationId === undefined ? {} : { applicationId: request.applicationId }),
+        });
+        this.sessions.set(session.sessionId, session);
+        return { status: "succeeded", session };
+    }
+    observe(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (session === undefined)
+            return this.failed("observe", "session_not_found", "Session does not exist");
+        if (session.status === "stopped")
+            return this.cancelled("observe", "Session has been stopped");
+        const raw = this.run(QUERY_SCRIPT);
+        if (raw === undefined || raw.available !== true) {
+            this.invalidateObservation(sessionId);
+            return unsupported("observe", "Windows UI Automation observation failed");
+        }
+        return this.toObservation(session, raw);
+    }
+    execute(request) {
+        const session = this.sessions.get(request.sessionId);
+        if (session === undefined)
+            return this.failed(request.operationId, "session_not_found", "Session does not exist");
+        if (session.status === "stopped")
+            return this.cancelled(request.operationId, "Session has been stopped");
+        if (requiresDesktopUserConfirmation(request.action.kind))
+            return {
+                version: 1,
+                operationId: request.operationId,
+                status: "needs_user",
+                summary: `User confirmation required for ${request.action.kind}`,
+                error: error("needs_user", `The ${request.action.kind} action is paused for the user`, request.action.kind),
+            };
+        if (!SUPPORTED_ACTIONS.includes(request.action.kind))
+            return unsupported(request.operationId, "The selected Windows UI Automation adapter does not support this action", "action-unsupported");
+        if (request.action.target === undefined)
+            return this.failed(request.operationId, "target_required", "This desktop action requires an observed target");
+        if (request.action.kind === "type" && typeof request.action.text !== "string")
+            return this.failed(request.operationId, "text_required", "Type action requires text");
+        if (request.action.kind === "key" && typeof request.action.key !== "string")
+            return this.failed(request.operationId, "key_required", "Key action requires a key sequence");
+        if (request.action.kind === "scroll" && typeof request.action.text !== "string")
+            return this.failed(request.operationId, "direction_required", "Scroll action requires an up/down direction");
+        const postconditions = request.postconditions ?? [];
+        if (postconditions.length > 0 && request.reobserveAfterAction === false)
+            return this.failed(request.operationId, "reobserve_required", "Postconditions require an action re-observation");
+        const target = this.resolveTarget(request.sessionId, request.action.target);
+        if (target === undefined)
+            return this.failed(request.operationId, this.observedSessions.has(request.sessionId) ? "stale_target" : "target_not_found", this.observedSessions.has(request.sessionId)
+                ? "Target identity is stale; reobserve the desktop before retrying"
+                : "Target identity was not observed by UI Automation");
+        const raw = this.run(ACTION_SCRIPT, { action: request.action, target: target ?? {} });
+        if (raw === undefined)
+            return unsupported(request.operationId, "Windows UI Automation action failed");
+        if (raw.ok !== true) {
+            if (raw.code === "stale_target") {
+                this.invalidateObservation(request.sessionId);
+                return this.failed(request.operationId, "stale_target", "Target identity is stale; reobserve the desktop before retrying");
+            }
+            const causeCode = typeof raw.reason === "string" &&
+                [
+                    "value_pattern_unavailable",
+                    "invoke_pattern_unavailable",
+                    "focus_failed",
+                    "uia_action_exception",
+                ].includes(raw.reason)
+                ? raw.reason
+                : "uia_action_exception";
+            return this.failed(request.operationId, "action_failed", "UI Automation action failed", causeCode);
+        }
+        const observation = request.reobserveAfterAction === false ? undefined : this.observe(request.sessionId);
+        const verification = this.verifyPostconditions(postconditions, observation);
+        if (postconditions.length > 0 && verification.status === "unknown")
+            return {
+                version: 1,
+                operationId: request.operationId,
+                status: "failed",
+                summary: "Desktop action completed but could not be re-observed",
+                verification,
+                error: error("verification_unavailable", "The requested desktop state could not be re-observed", "reobserve-failed"),
+            };
+        if (verification.status === "failed")
+            return {
+                version: 1,
+                operationId: request.operationId,
+                status: "failed",
+                summary: "Desktop action completed but a postcondition failed",
+                ...(observation !== undefined && "observationId" in observation ? { observation } : {}),
+                verification,
+                error: error("postcondition_failed", "The requested desktop state was not observed", "verification-failed"),
+            };
+        return {
+            version: 1,
+            operationId: request.operationId,
+            status: "succeeded",
+            summary: "Desktop action completed through Windows UI Automation",
+            ...(observation !== undefined && "observationId" in observation ? { observation } : {}),
+            verification,
+        };
+    }
+    stop(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (session === undefined)
+            return this.failed("stop", "session_not_found", "Session does not exist");
+        const stopped = detachedFreeze({ ...session, status: "stopped" });
+        this.sessions.set(sessionId, stopped);
+        this.invalidateObservation(sessionId);
+        return stopped;
+    }
+    run(script, payload) {
+        if (this.platform !== "win32")
+            return undefined;
+        const env = {};
+        for (const key of ["SystemRoot", "WINDIR", "PATH", "PATHEXT", "ComSpec", "TEMP", "TMP"]) {
+            const value = process.env[key];
+            if (value !== undefined)
+                env[key] = value;
+        }
+        if (payload !== undefined)
+            env.AGENT_FORGE_UIA_INPUT = JSON.stringify(payload);
+        const result = this.spawn(this.command, ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-Command", script], { encoding: "utf8", timeout: this.timeoutMs, windowsHide: true, env });
+        if (result.error !== undefined || result.status !== 0)
+            return undefined;
+        return parseJson(result.stdout);
+    }
+    toObservation(session, raw) {
+        this.invalidateObservation(session.sessionId);
+        const observationId = `desktop-windows-observation-${this.nextObservationId++}`;
+        const targetKeys = new Set();
+        this.sessionTargetKeys.set(session.sessionId, targetKeys);
+        const windows = [];
+        for (const item of raw.windows ?? []) {
+            if (!Number.isFinite(item.handle))
+                continue;
+            const handle = Number(item.handle);
+            const windowId = `window-${handle}`;
+            windows.push({
+                version: 1,
+                windowId,
+                appId: `process:${Number(item.processId ?? 0)}`,
+                title: item.name ?? "",
+                bounds: rectangle(item),
+            });
+        }
+        const visibleWindows = session.applicationId === undefined
+            ? windows
+            : windows.filter((window) => window.appId === session.applicationId);
+        for (const window of visibleWindows) {
+            const handle = Number(/^window-(\d+)$/.exec(window.windowId)?.[1]);
+            if (!Number.isFinite(handle))
+                continue;
+            const key = this.targetKey(session.sessionId, "window", window.windowId);
+            this.targets.set(key, { sessionId: session.sessionId, observationId, windowHandle: handle });
+            targetKeys.add(key);
+        }
+        const controls = [];
+        for (const item of raw.controls ?? []) {
+            if (!Number.isFinite(item.windowHandle))
+                continue;
+            const windowId = `window-${Number(item.windowHandle)}`;
+            if (!visibleWindows.some((window) => window.windowId === windowId))
+                continue;
+            const controlId = `${windowId}:${item.controlId ?? "control"}`;
+            const key = this.targetKey(session.sessionId, "control", controlId);
+            this.targets.set(key, {
+                sessionId: session.sessionId,
+                observationId,
+                windowHandle: Number(item.windowHandle),
+                ...(Number.isFinite(item.nativeWindowHandle) && Number(item.nativeWindowHandle) > 0
+                    ? { controlWindowHandle: Number(item.nativeWindowHandle) }
+                    : {}),
+                controlId: item.controlId,
+            });
+            targetKeys.add(key);
+            controls.push({
+                version: 1,
+                controlId,
+                windowId,
+                role: item.role ?? "",
+                name: item.name ?? "",
+                bounds: rectangle(item),
+                enabled: item.enabled !== false,
+                ...(typeof item.value === "string" && item.value.length > 0 ? { value: item.value } : {}),
+            });
+        }
+        const focusedControl = raw.focusedControl;
+        const focusedWindowId = Number.isFinite(focusedControl?.windowHandle)
+            ? `window-${Number(focusedControl?.windowHandle)}`
+            : undefined;
+        const focusedControlId = focusedWindowId === undefined || typeof focusedControl?.controlId !== "string"
+            ? undefined
+            : `${focusedWindowId}:${focusedControl.controlId}`;
+        const observation = detachedFreeze({
+            version: 1,
+            sessionId: session.sessionId,
+            observationId,
+            source: "windows-uia",
+            windows: visibleWindows,
+            controls,
+            ...(focusedControlId !== undefined && controls.some((control) => control.controlId === focusedControlId)
+                ? { focusedControlId }
+                : {}),
+        });
+        this.latestObservationIds.set(session.sessionId, observationId);
+        this.observedSessions.add(session.sessionId);
+        return observation;
+    }
+    resolveTarget(sessionId, target) {
+        const identity = target.kind === "control" ? target.controlId : target.windowId;
+        const record = this.targets.get(this.targetKey(sessionId, target.kind, identity));
+        if (record === undefined ||
+            record.sessionId !== sessionId ||
+            record.observationId !== this.latestObservationIds.get(sessionId))
+            return undefined;
+        return {
+            windowHandle: record.windowHandle,
+            ...(record.controlWindowHandle === undefined ? {} : { controlWindowHandle: record.controlWindowHandle }),
+            ...(record.controlId === undefined ? {} : { controlId: record.controlId }),
+        };
+    }
+    targetKey(sessionId, kind, identity) {
+        return `${sessionId}:${kind}:${identity}`;
+    }
+    invalidateObservation(sessionId) {
+        for (const key of this.sessionTargetKeys.get(sessionId) ?? [])
+            this.targets.delete(key);
+        this.sessionTargetKeys.delete(sessionId);
+        this.latestObservationIds.delete(sessionId);
+    }
+    verifyPostconditions(postconditions, observation) {
+        if (postconditions.length === 0)
+            return { status: "passed", checks: [] };
+        if (observation === undefined || !("observationId" in observation))
+            return { status: "unknown", checks: ["observation-unavailable"] };
+        const checks = [];
+        for (const condition of postconditions) {
+            const passed = this.checkPostcondition(condition, observation);
+            checks.push(`${condition.kind}:${passed ? "passed" : "failed"}`);
+            if (!passed)
+                return { status: "failed", checks };
+        }
+        return { status: "passed", checks };
+    }
+    checkPostcondition(condition, observation) {
+        if (condition.kind === "window-exists")
+            return observation.windows.some((window) => window.windowId === condition.windowId);
+        if (condition.kind === "control-exists")
+            return observation.controls.some((control) => control.controlId === condition.controlId);
+        if (condition.kind === "focused")
+            return observation.focusedControlId === condition.controlId;
+        const target = condition.target;
+        if (target.kind === "window") {
+            const window = observation.windows.find((item) => item.windowId === target.windowId);
+            if (window === undefined || condition.property !== "name")
+                return false;
+            return window.title === condition.expected;
+        }
+        const control = observation.controls.find((item) => {
+            if (item.controlId !== target.controlId)
+                return false;
+            return target.windowId === undefined || item.windowId === target.windowId;
+        });
+        if (control === undefined)
+            return false;
+        if (condition.property === "enabled")
+            return control.enabled === condition.expected;
+        if (condition.property === "name")
+            return control.name === condition.expected;
+        return control.value === condition.expected;
+    }
+    failed(operationId, code, message, causeCode) {
+        return { version: 1, operationId, status: "failed", summary: message, error: error(code, message, causeCode) };
+    }
+    cancelled(operationId, message) {
+        return {
+            version: 1,
+            operationId,
+            status: "cancelled",
+            summary: message,
+            error: error("cancelled", message, "stopped"),
+        };
+    }
+}
+/** Adapter facade that adds replay and the needs_user gate around a Windows driver. */
+export class DesktopWindowsAdapter {
+    adapterId = "desktop-windows-uia";
+    adapterVersion = "1.0.0";
+    capabilities = READONLY_CAPABILITIES;
+    driver;
+    constructor(driver = new WindowsUiAutomationDriver()) {
+        this.driver = driver;
+    }
+    probe() {
+        return this.driver.probe();
+    }
+    openSession(request) {
+        return this.driver.openSession(request);
+    }
+    observe(sessionId) {
+        return this.driver.observe(sessionId);
+    }
+    reobserve(sessionId) {
+        return this.driver.observe(sessionId);
+    }
+    execute(request) {
+        if (requiresDesktopUserConfirmation(request.action.kind)) {
+            return {
+                version: 1,
+                operationId: request.operationId,
+                status: "needs_user",
+                summary: `User confirmation required for ${request.action.kind}`,
+                error: error("needs_user", `The ${request.action.kind} action is paused for the user`, request.action.kind),
+            };
+        }
+        return this.driver.execute(request);
+    }
+    stop(sessionId) {
+        return this.driver.stop(sessionId);
+    }
+    replay(request) {
+        const mismatchedOperationId = findDesktopReplaySessionMismatch(request);
+        if (mismatchedOperationId !== undefined)
+            return detachedFreeze({
+                version: 1,
+                status: "failed",
+                results: [
+                    {
+                        version: 1,
+                        operationId: mismatchedOperationId,
+                        status: "failed",
+                        summary: "Replay operation session does not match the replay session",
+                        error: error("session_mismatch", "Replay operation session does not match the replay session", "replay-session"),
+                    },
+                ],
+            });
+        const results = [];
+        for (const operation of request.operations) {
+            const result = this.execute(operation);
+            results.push(result);
+            if (request.stopOnFailure && result.status !== "succeeded")
+                return detachedFreeze({
+                    version: 1,
+                    status: result.status === "cancelled"
+                        ? "cancelled"
+                        : result.status === "needs_user"
+                            ? "needs_user"
+                            : "failed",
+                    results,
+                });
+        }
+        return detachedFreeze({ version: 1, status: "succeeded", results });
+    }
+}
+//# sourceMappingURL=windows-uia-adapter.js.map