@ludi-uni/ludi-agent-kit 0.1.0

package/skills/visual-verification/scripts/common.ps1

@@ -0,0 +1,387 @@
+Set-StrictMode -Version Latest
+
+function Get-FfmpegPath {
+    [OutputType([string])]
+    [CmdletBinding()]
+    param()
+
+    try {
+        $command = Get-Command ffmpeg -ErrorAction Stop
+    }
+    catch {
+        throw 'ffmpeg was not found on PATH.'
+    }
+
+    if ($command.CommandType -ne [System.Management.Automation.CommandTypes]::Application) {
+        throw "ffmpeg resolved to '$($command.CommandType)', not an executable application."
+    }
+
+    return [IO.Path]::GetFullPath($command.Source)
+}
+
+function New-VisualRun {
+    [OutputType([pscustomobject])]
+    [CmdletBinding()]
+    param(
+        [string]$RunDirectory,
+        [Parameter(Mandatory)]
+        [ValidateNotNullOrEmpty()]
+        [string]$Kind
+    )
+
+    if (-not [string]::IsNullOrWhiteSpace($RunDirectory)) {
+        if (-not (Test-Path -LiteralPath $RunDirectory -PathType Container)) {
+            throw "The explicit run directory does not exist: $RunDirectory"
+        }
+
+        $resolvedRunDirectory = [IO.Path]::GetFullPath($RunDirectory)
+        return [pscustomobject]@{
+            RunId        = Split-Path -Leaf $resolvedRunDirectory
+            RunDirectory = $resolvedRunDirectory
+            Kind         = $Kind
+        }
+    }
+
+    $evidenceRoot = Join-Path ([IO.Path]::GetTempPath()) 'agent-verification-lab'
+    New-Item -ItemType Directory -Path $evidenceRoot -Force | Out-Null
+
+    do {
+        $candidate = Join-Path $evidenceRoot ([Guid]::NewGuid().ToString('N'))
+    } while (Test-Path -LiteralPath $candidate)
+
+    New-Item -ItemType Directory -Path $candidate -ErrorAction Stop | Out-Null
+    return [pscustomobject]@{
+        RunId        = Split-Path -Leaf $candidate
+        RunDirectory = [IO.Path]::GetFullPath($candidate)
+        Kind         = $Kind
+    }
+}
+
+function New-VisualEvidenceRun {
+    [OutputType([string])]
+    [CmdletBinding()]
+    param(
+        [string]$RunDirectory
+    )
+
+    return (New-VisualRun -RunDirectory $RunDirectory -Kind 'visual').RunDirectory
+}
+
+function Assert-OutputAvailable {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [string]$Path,
+        [switch]$Overwrite
+    )
+
+    if (-not (Test-Path -LiteralPath $Path)) {
+        return
+    }
+
+    $item = Get-Item -LiteralPath $Path -Force
+    if ($item.PSIsContainer) {
+        throw "Output path is a directory: $Path"
+    }
+
+    if (-not $Overwrite) {
+        throw "Output already exists; specify -Overwrite to replace it: $Path"
+    }
+}
+
+function Get-VisualVerificationNativeMethods {
+    [OutputType([type])]
+    [CmdletBinding()]
+    param()
+
+    $nativeMethods = 'VisualVerification.NativeMethods' -as [type]
+    if ($null -eq $nativeMethods) {
+        Add-Type -TypeDefinition @'
+using System;
+using System.Runtime.InteropServices;
+using System.Text;
+
+namespace VisualVerification
+{
+    public static class NativeMethods
+    {
+        [StructLayout(LayoutKind.Sequential)]
+        public struct RECT
+        {
+            public int Left;
+            public int Top;
+            public int Right;
+            public int Bottom;
+        }
+
+        public delegate bool EnumWindowsProc(IntPtr hWnd, IntPtr lParam);
+
+        [DllImport("user32.dll")]
+        public static extern bool EnumWindows(EnumWindowsProc lpEnumFunc, IntPtr lParam);
+
+        [DllImport("user32.dll")]
+        public static extern bool IsWindow(IntPtr hWnd);
+
+        [DllImport("user32.dll")]
+        public static extern bool IsWindowVisible(IntPtr hWnd);
+
+        [DllImport("user32.dll")]
+        public static extern int GetWindowTextLength(IntPtr hWnd);
+
+        [DllImport("user32.dll", CharSet = CharSet.Unicode)]
+        public static extern int GetWindowText(IntPtr hWnd, StringBuilder lpString, int nMaxCount);
+
+        [DllImport("user32.dll")]
+        public static extern bool GetWindowRect(IntPtr hWnd, out RECT lpRect);
+    }
+}
+'@
+        $nativeMethods = 'VisualVerification.NativeMethods' -as [type]
+    }
+
+    return $nativeMethods
+}
+
+function Resolve-CaptureTarget {
+    [OutputType([pscustomobject])]
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [ValidateSet('desktop', 'region', 'window')]
+        [string]$Mode,
+        [Nullable[int]]$X,
+        [Nullable[int]]$Y,
+        [Nullable[int]]$Width,
+        [Nullable[int]]$Height,
+        [string]$WindowTitle,
+        [IntPtr]$Hwnd = [IntPtr]::Zero
+    )
+
+    $hasRegionArgument = $null -ne $X -or $null -ne $Y -or $null -ne $Width -or $null -ne $Height
+    $hasTitle = -not [string]::IsNullOrWhiteSpace($WindowTitle)
+    $hasHwnd = $Hwnd -ne [IntPtr]::Zero
+
+    switch ($Mode) {
+        'desktop' {
+            if ($hasRegionArgument -or $hasTitle -or $hasHwnd) {
+                throw 'Desktop capture cannot include region or window target arguments.'
+            }
+
+            return [pscustomobject]@{
+                InputName        = 'desktop'
+                InputOptions     = [string[]]@('-i', 'desktop')
+                Bounds           = $null
+                TargetDescription = 'desktop'
+            }
+        }
+
+        'region' {
+            if ($hasTitle -or $hasHwnd) {
+                throw 'Region capture cannot include window target arguments.'
+            }
+
+            if ($null -eq $X -or $null -eq $Y -or $null -eq $Width -or $null -eq $Height) {
+                throw 'Region capture requires X, Y, Width, and Height.'
+            }
+
+            if ($Width -le 0 -or $Height -le 0) {
+                throw 'Region capture Width and Height must be positive.'
+            }
+
+            $bounds = [pscustomobject]@{
+                X      = [int]$X
+                Y      = [int]$Y
+                Width  = [int]$Width
+                Height = [int]$Height
+            }
+
+            return [pscustomobject]@{
+                InputName        = 'desktop'
+                InputOptions     = [string[]]@(
+                    '-video_size', "$($bounds.Width)x$($bounds.Height)",
+                    '-offset_x', [string]$bounds.X,
+                    '-offset_y', [string]$bounds.Y,
+                    '-i', 'desktop'
+                )
+                Bounds           = $bounds
+                TargetDescription = "region x=$($bounds.X) y=$($bounds.Y) width=$($bounds.Width) height=$($bounds.Height)"
+            }
+        }
+
+        'window' {
+            if ($hasRegionArgument) {
+                throw 'Window capture cannot include region target arguments.'
+            }
+
+            if ($hasTitle -eq $hasHwnd) {
+                throw 'Window capture requires exactly one of WindowTitle or Hwnd.'
+            }
+
+            $nativeMethods = Get-VisualVerificationNativeMethods
+            if ($hasTitle) {
+                $matches = [System.Collections.Generic.List[IntPtr]]::new()
+                $callback = [VisualVerification.NativeMethods+EnumWindowsProc]{
+                    param([IntPtr]$candidate, [IntPtr]$unused)
+
+                    if (-not [VisualVerification.NativeMethods]::IsWindowVisible($candidate)) {
+                        return $true
+                    }
+
+                    $titleLength = [VisualVerification.NativeMethods]::GetWindowTextLength($candidate)
+                    if ($titleLength -le 0) {
+                        return $true
+                    }
+
+                    $titleBuilder = [System.Text.StringBuilder]::new($titleLength + 1)
+                    [void][VisualVerification.NativeMethods]::GetWindowText($candidate, $titleBuilder, $titleBuilder.Capacity)
+                    if ($titleBuilder.ToString() -ceq $WindowTitle) {
+                        [void]$matches.Add($candidate)
+                    }
+
+                    return $true
+                }
+                [void][VisualVerification.NativeMethods]::EnumWindows($callback, [IntPtr]::Zero)
+
+                if ($matches.Count -eq 0) {
+                    throw "No visible window exactly matches title '$WindowTitle'."
+                }
+
+                if ($matches.Count -ne 1) {
+                    throw "Window title '$WindowTitle' is ambiguous; $($matches.Count) visible windows match exactly."
+                }
+
+                $Hwnd = $matches[0]
+            }
+
+            if (-not [VisualVerification.NativeMethods]::IsWindow($Hwnd)) {
+                throw "Hwnd '$Hwnd' is not a valid window."
+            }
+
+            if (-not [VisualVerification.NativeMethods]::IsWindowVisible($Hwnd)) {
+                throw "Hwnd '$Hwnd' is not visible."
+            }
+
+            $rect = [VisualVerification.NativeMethods+RECT]::new()
+            if (-not [VisualVerification.NativeMethods]::GetWindowRect($Hwnd, [ref]$rect)) {
+                throw "GetWindowRect failed for Hwnd '$Hwnd'."
+            }
+
+            $windowWidth = $rect.Right - $rect.Left
+            $windowHeight = $rect.Bottom - $rect.Top
+            if ($windowWidth -le 0 -or $windowHeight -le 0) {
+                throw "Hwnd '$Hwnd' has invalid bounds."
+            }
+
+            $bounds = [pscustomobject]@{
+                X      = $rect.Left
+                Y      = $rect.Top
+                Width  = $windowWidth
+                Height = $windowHeight
+            }
+            $handleText = "0x$($Hwnd.ToInt64().ToString('X'))"
+
+            return [pscustomobject]@{
+                InputName        = 'desktop'
+                InputOptions     = [string[]]@(
+                    '-video_size', "$($bounds.Width)x$($bounds.Height)",
+                    '-offset_x', [string]$bounds.X,
+                    '-offset_y', [string]$bounds.Y,
+                    '-i', 'desktop'
+                )
+                Bounds           = $bounds
+                TargetDescription = "window $handleText x=$($bounds.X) y=$($bounds.Y) width=$($bounds.Width) height=$($bounds.Height)"
+            }
+        }
+    }
+}
+
+function Invoke-Ffmpeg {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [string]$FfmpegPath,
+        [Parameter(Mandatory)]
+        [string[]]$Arguments,
+        [Parameter(Mandatory)]
+        [string]$Operation
+    )
+
+    $ffmpegArguments = [string[]]@('-hide_banner', '-loglevel', 'error', '-nostdin') + $Arguments
+    $diagnostics = & $FfmpegPath @ffmpegArguments 2>&1
+    $exitCode = $LASTEXITCODE
+    if ($exitCode -ne 0) {
+        $diagnosticText = ($diagnostics | ForEach-Object { $_.ToString() }) -join [Environment]::NewLine
+        throw "FFmpeg $Operation failed with exit code $exitCode.$([Environment]::NewLine)$diagnosticText"
+    }
+}
+
+function Write-ResultJson {
+    [OutputType([string])]
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [pscustomobject]$Result
+    )
+
+    if ([string]::IsNullOrWhiteSpace($Result.run_directory)) {
+        throw 'Result.run_directory is required.'
+    }
+
+    $runDirectory = [IO.Path]::GetFullPath($Result.run_directory)
+    if (-not (Test-Path -LiteralPath $runDirectory -PathType Container)) {
+        throw "Result run directory does not exist: $runDirectory"
+    }
+
+    $Result.run_directory = $runDirectory
+    $resultPath = Join-Path $runDirectory 'result.json'
+    if (Test-Path -LiteralPath $resultPath -PathType Leaf) {
+        try {
+            $previous = Get-Content -LiteralPath $resultPath -Raw -ErrorAction Stop | ConvertFrom-Json -ErrorAction Stop
+        }
+        catch {
+            throw "Existing result.json cannot be read safely: $resultPath"
+        }
+
+        if ($previous.run_directory -ne $runDirectory) {
+            throw "Existing result.json belongs to a different run directory: $resultPath"
+        }
+
+        $artifactKeys = [System.Collections.Generic.HashSet[string]]::new([StringComparer]::OrdinalIgnoreCase)
+        $artifacts = [System.Collections.Generic.List[object]]::new()
+        foreach ($artifact in @($previous.artifacts) + @($Result.artifacts)) {
+            if ($null -eq $artifact) {
+                continue
+            }
+
+            $key = "$($artifact.role)`0$($artifact.path)"
+            if ($artifactKeys.Add($key)) {
+                [void]$artifacts.Add($artifact)
+            }
+        }
+        $Result.artifacts = @($artifacts)
+    }
+
+    $json = $Result | ConvertTo-Json -Depth 8
+    Set-Content -LiteralPath $resultPath -Value $json -Encoding utf8NoBOM -NoNewline -ErrorAction Stop
+    return [IO.Path]::GetFullPath($resultPath)
+}
+
+function Write-VisualResult {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [string]$RunDirectory,
+        [Parameter(Mandatory)]
+        [string]$OutputPath,
+        [Parameter(Mandatory)]
+        [string]$Kind,
+        [string]$ResultJsonPath
+    )
+
+    Write-Output "RUN_DIRECTORY=$([IO.Path]::GetFullPath($RunDirectory))"
+    Write-Output "OUTPUT_PATH=$([IO.Path]::GetFullPath($OutputPath))"
+    Write-Output "KIND=$Kind"
+    if (-not [string]::IsNullOrWhiteSpace($ResultJsonPath)) {
+        Write-Output "RESULT_JSON=$([IO.Path]::GetFullPath($ResultJsonPath))"
+    }
+}

package/skills/visual-verification/scripts/contact-sheet.ps1

@@ -0,0 +1,121 @@
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory)]
+    [ValidateNotNullOrEmpty()]
+    [string]$InputDirectory,
+    [int]$Columns = 4,
+    [double]$Interval = 0.5,
+    [int]$CellWidth = 640,
+    [string]$OutputPath,
+    [string]$RunDirectory,
+    [switch]$Overwrite
+)
+
+$common = Join-Path $PSScriptRoot 'common.ps1'
+. $common
+
+if (-not (Test-Path -LiteralPath $InputDirectory -PathType Container)) {
+    throw "Input directory does not exist or is not a directory: $InputDirectory"
+}
+
+if ($Columns -lt 1 -or $Columns -gt 10) {
+    throw 'Columns must be between 1 and 10.'
+}
+
+if ([double]::IsNaN($Interval) -or [double]::IsInfinity($Interval) -or $Interval -le 0) {
+    throw 'Interval must be positive.'
+}
+
+if ($CellWidth -lt 64 -or $CellWidth -gt 1920) {
+    throw 'CellWidth must be between 64 and 1920.'
+}
+
+$resolvedInputDirectory = [IO.Path]::GetFullPath($InputDirectory)
+$frames = @(
+    Get-ChildItem -LiteralPath $resolvedInputDirectory -Filter 'frame-*.png' -File |
+        ForEach-Object {
+            if ($_.Name -match '^frame-(\d+)\.png$') {
+                [pscustomobject]@{
+                    Path  = $_.FullName
+                    Index = [long]$Matches[1]
+                    Name  = $_.Name
+                }
+            }
+        } |
+        Sort-Object -Property Index, Name
+)
+
+if ($frames.Count -eq 0) {
+    throw "No frame-*.png files were found in: $resolvedInputDirectory"
+}
+
+if ($frames.Count -gt 100) {
+    throw 'Contact sheets support at most 100 frames.'
+}
+
+$run = New-VisualRun -RunDirectory $RunDirectory -Kind 'visual'
+$resolvedRunDirectory = $run.RunDirectory
+if ([string]::IsNullOrWhiteSpace($OutputPath)) {
+    $OutputPath = Join-Path $resolvedRunDirectory 'contact-sheet.png'
+}
+
+$resolvedOutputPath = [IO.Path]::GetFullPath($OutputPath)
+Assert-OutputAvailable -Path $resolvedOutputPath -Overwrite:$Overwrite
+
+$invariantCulture = [Globalization.CultureInfo]::InvariantCulture
+$intervalText = $Interval.ToString('G17', $invariantCulture)
+$frameRateText = (1 / $Interval).ToString('G17', $invariantCulture)
+$columnsText = $Columns.ToString($invariantCulture)
+$rows = [int][Math]::Ceiling($frames.Count / [double]$Columns)
+$rowsText = $rows.ToString($invariantCulture)
+$cellWidthText = $CellWidth.ToString($invariantCulture)
+$cellHeight = [int][Math]::Ceiling(($CellWidth * 9.0) / 32.0) * 2
+$cellHeightText = $cellHeight.ToString($invariantCulture)
+$fontPath = Join-Path $env:WINDIR 'Fonts\arial.ttf'
+if (-not (Test-Path -LiteralPath $fontPath -PathType Leaf)) {
+    throw "Required label font does not exist: $fontPath"
+}
+
+$fontForFilter = [IO.Path]::GetFullPath($fontPath).Replace('\', '/').Replace(':', '\:')
+
+$ffmpegArguments = [System.Collections.Generic.List[string]]::new()
+foreach ($frame in $frames) {
+    $ffmpegArguments.Add('-framerate')
+    $ffmpegArguments.Add($frameRateText)
+    $ffmpegArguments.Add('-i')
+    $ffmpegArguments.Add($frame.Path)
+}
+
+$branchFilters = [System.Collections.Generic.List[string]]::new()
+$normalizedLabels = [System.Collections.Generic.List[string]]::new()
+foreach ($index in 0..($frames.Count - 1)) {
+    $normalizedLabel = "frame$index"
+    $branchFilters.Add("[$index`:v]scale=${cellWidthText}:${cellHeightText}:force_original_aspect_ratio=decrease,pad=${cellWidthText}:${cellHeightText}:(ow-iw)/2:(oh-ih)/2:color=black,setsar=1,setpts=PTS-STARTPTS[$normalizedLabel]")
+    $normalizedLabels.Add("[$normalizedLabel]")
+}
+
+$filter = ($branchFilters -join ';') + ';' + ($normalizedLabels -join '') + "concat=n=$($frames.Count):v=1:a=0,settb=AVTB,setpts=N*$intervalText/TB,fps=$frameRateText,drawtext=fontfile='$fontForFilter':text='t=%{pts\:hms}':x=12:y=12:fontsize=28:fontcolor=white:box=1:boxcolor=black@0.75:boxborderw=8,tile=${columnsText}x${rowsText}:padding=8:margin=8:color=black"
+
+$ffmpegArguments.Add('-filter_complex')
+$ffmpegArguments.Add($filter)
+$ffmpegArguments.Add('-frames:v')
+$ffmpegArguments.Add('1')
+$ffmpegArguments.Add('-c:v')
+$ffmpegArguments.Add('png')
+if ($Overwrite) {
+    $ffmpegArguments.Add('-y')
+}
+$ffmpegArguments.Add($resolvedOutputPath)
+
+Invoke-Ffmpeg -FfmpegPath (Get-FfmpegPath) -Arguments $ffmpegArguments.ToArray() -Operation "contact sheet from $resolvedInputDirectory"
+$resultJson = Write-ResultJson -Result ([pscustomobject]@{
+        schema_version = 'agent-verification-lab.result.v1'
+        status         = 'ok'
+        kind           = $run.Kind
+        run_id         = $run.RunId
+        run_directory  = $resolvedRunDirectory
+        artifacts      = @([pscustomobject]@{ role = 'contact-sheet'; path = $resolvedOutputPath; mime = 'image/png' })
+        backend        = [pscustomobject]@{ name = 'ffmpeg'; version = $null }
+        warnings       = @()
+    })
+Write-VisualResult -RunDirectory $resolvedRunDirectory -OutputPath $resolvedOutputPath -Kind 'contact-sheet' -ResultJsonPath $resultJson

package/skills/visual-verification/scripts/desktop-discover.ps1

@@ -0,0 +1,45 @@
+[CmdletBinding()]
+param(
+    [string]$App,
+    [string]$ProcessName,
+    [string]$WindowTitle,
+    [string]$ClassName,
+    [Nullable[int]]$ProcessId,
+    [Nullable[long]]$Hwnd,
+    [Nullable[int]]$Width,
+    [Nullable[int]]$Height,
+    [string]$RunDirectory
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+. (Join-Path $PSScriptRoot 'common.ps1')
+. (Join-Path $PSScriptRoot 'winapp-common.ps1')
+
+try {
+    $version = Get-WinAppVersionInfo
+    Assert-WinAppCaptureReady -VersionInfo $version
+    $run = New-VisualRun -RunDirectory $RunDirectory -Kind 'visual'
+    $target = Get-WinAppWindowTarget -Executable $version.executable -App $App -ProcessName $ProcessName -WindowTitle $WindowTitle -ClassName $ClassName -ProcessId $ProcessId -Hwnd $Hwnd -Width $Width -Height $Height
+    $outputPath = Join-Path $run.RunDirectory 'desktop-window.json'
+    $metadata = New-WinAppOperationMetadata -Operation 'discover' -Version $version.actual -VersionClassification $version.classification -Target $target -Width $target.width -Height $target.height
+    Write-WinAppTargetDocument -Path $outputPath -Target $target -VersionInfo $version | Out-Null
+    $warnings = @()
+    if ($version.classification -eq 'UNTESTED_NEWER') { $warnings += 'WINAPP_VERSION_UNTESTED' }
+    $resultJson = Write-ResultJson -Result ([pscustomobject]@{
+            schema_version = 'agent-verification-lab.result.v1'
+            status         = 'ok'
+            kind           = $run.Kind
+            run_id         = $run.RunId
+            run_directory  = $run.RunDirectory
+            artifacts      = @([pscustomobject]@{ role = 'desktop-window'; path = $outputPath; mime = 'application/json' })
+            backend        = $metadata.backend
+            target         = $target
+            warnings       = $warnings
+        })
+    Write-VisualResult -RunDirectory $run.RunDirectory -OutputPath $outputPath -Kind 'desktop-window' -ResultJsonPath $resultJson
+}
+catch {
+    Write-WinAppFailure -ErrorRecord $_ -Operation discover
+    exit 1
+}

package/skills/visual-verification/scripts/desktop-inspect.ps1

@@ -0,0 +1,67 @@
+[CmdletBinding()]
+param(
+    [string]$App,
+    [string]$ProcessName,
+    [string]$WindowTitle,
+    [string]$ClassName,
+    [Nullable[int]]$ProcessId,
+    [Nullable[long]]$Hwnd,
+    [Nullable[int]]$Width,
+    [Nullable[int]]$Height,
+    [ValidateRange(1, 20)][int]$Depth = 6,
+    [switch]$Interactive,
+    [string]$RunDirectory
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+. (Join-Path $PSScriptRoot 'common.ps1')
+. (Join-Path $PSScriptRoot 'winapp-common.ps1')
+
+try {
+    $version = Get-WinAppVersionInfo
+    Assert-WinAppCaptureReady -VersionInfo $version
+    $run = New-VisualRun -RunDirectory $RunDirectory -Kind 'visual'
+    $target = Get-WinAppWindowTarget -Executable $version.executable -App $App -ProcessName $ProcessName -WindowTitle $WindowTitle -ClassName $ClassName -ProcessId $ProcessId -Hwnd $Hwnd -Width $Width -Height $Height
+    $outputPath = Join-Path $run.RunDirectory 'desktop-ui.json'
+    Assert-OutputAvailable -Path $outputPath
+    $arguments = New-WinAppInspectArguments -Hwnd $target.hwnd -Depth $Depth -Interactive:$Interactive
+    $response = Invoke-WinAppJson -Executable $version.executable -Arguments $arguments -Operation inspect
+    $elementCount = 0
+    foreach ($window in @(Get-WinAppPropertyValue $response.data 'windows' @())) { $elementCount += [int](Get-WinAppPropertyValue $window 'elementCount' 0) }
+    $capability = if ($elementCount -eq 0) { 'UIA_UNAVAILABLE' } elseif ($elementCount -le 1) { 'UIA_LIMITED' } else { 'UIA_RICH' }
+    $document = [pscustomobject]@{
+        schema_version = 'agent-verification-lab.desktop-ui.v1'
+        backend        = [pscustomobject]@{ name = 'winapp-cli'; version = $version.actual; tested_version = $version.tested; version_classification = $version.classification }
+        target         = $target
+        capability     = $capability
+        element_count  = $elementCount
+        upstream_tree  = $response.data
+        interaction    = [pscustomobject]@{ automatic = $false; background_guaranteed = $false; may_foreground_target = $true }
+    }
+    $targetPath = Write-WinAppTargetDocument -Path (Join-Path $run.RunDirectory 'desktop-window.json') -Target $target -VersionInfo $version
+    Write-WinAppJsonFile -Value $document -Path $outputPath | Out-Null
+    $warnings = @()
+    if ($version.classification -eq 'UNTESTED_NEWER') { $warnings += 'WINAPP_VERSION_UNTESTED' }
+    if ($capability -ne 'UIA_RICH') { $warnings += $capability }
+    $resultJson = Write-ResultJson -Result ([pscustomobject]@{
+            schema_version = 'agent-verification-lab.result.v1'
+            status         = 'ok'
+            kind           = $run.Kind
+            run_id         = $run.RunId
+            run_directory  = $run.RunDirectory
+            artifacts      = @(
+                [pscustomobject]@{ role = 'desktop-window'; path = $targetPath; mime = 'application/json' },
+                [pscustomobject]@{ role = 'desktop-ui'; path = $outputPath; mime = 'application/json' }
+            )
+            backend        = $document.backend
+            target         = $target
+            uia            = [pscustomobject]@{ capability = $capability; element_count = $elementCount; optional = $true }
+            warnings       = $warnings
+        })
+    Write-VisualResult -RunDirectory $run.RunDirectory -OutputPath $outputPath -Kind 'desktop-ui' -ResultJsonPath $resultJson
+}
+catch {
+    Write-WinAppFailure -ErrorRecord $_ -Operation inspect
+    exit 1
+}