@ludi-uni/ludi-agent-kit 0.1.0

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

@@ -0,0 +1,97 @@
+[CmdletBinding()]
+param(
+    [string]$App,
+    [string]$ProcessName,
+    [string]$WindowTitle,
+    [string]$ClassName,
+    [Nullable[int]]$ProcessId,
+    [Nullable[long]]$Hwnd,
+    [Nullable[int]]$Width,
+    [Nullable[int]]$Height,
+    [double]$Duration = 5,
+    [int]$Fps = 5,
+    [switch]$Frames,
+    [int]$MaxEdge = 1280,
+    [string]$OutputPath,
+    [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'
+    if ([string]::IsNullOrWhiteSpace($OutputPath)) { $OutputPath = Join-Path $run.RunDirectory 'recording.mp4' }
+    $resolvedOutputPath = [IO.Path]::GetFullPath($OutputPath)
+    $metadataOutputPath = Join-Path $run.RunDirectory 'recording.json'
+    $representativeOutputPath = Join-Path $run.RunDirectory 'representative-frames.json'
+    Assert-OutputAvailable -Path $resolvedOutputPath
+    Assert-OutputAvailable -Path $metadataOutputPath
+    if ($Frames) { Assert-OutputAvailable -Path $representativeOutputPath }
+    $expectedFramesDirectory = Join-Path (Split-Path -Parent $resolvedOutputPath) (([IO.Path]::GetFileNameWithoutExtension($resolvedOutputPath)) + '.frames')
+    if ($Frames -and (Test-Path -LiteralPath $expectedFramesDirectory)) { throw (New-WinAppException -Code 'RECORD_FAILED' -Message "Frame output already exists: $expectedFramesDirectory") }
+    $target = Get-WinAppWindowTarget -Executable $version.executable -App $App -ProcessName $ProcessName -WindowTitle $WindowTitle -ClassName $ClassName -ProcessId $ProcessId -Hwnd $Hwnd -Width $Width -Height $Height
+    $arguments = New-WinAppRecordArguments -Hwnd $target.hwnd -OutputPath $resolvedOutputPath -Duration $Duration -Fps $Fps -Frames:$Frames -MaxEdge $MaxEdge
+    $response = Invoke-WinAppJson -Executable $version.executable -Arguments $arguments -Operation record
+    Assert-WinAppMp4 -Path $resolvedOutputPath
+    $recordWidth = [int](Get-WinAppPropertyValue $response.data 'width' 0)
+    $recordHeight = [int](Get-WinAppPropertyValue $response.data 'height' 0)
+    if ($recordWidth -le 0 -or $recordHeight -le 0) { throw (New-WinAppException -Code 'RECORD_FAILED' -Message 'WinApp CLI returned zero recording dimensions.') }
+    if ([string](Get-WinAppPropertyValue $response.data 'codec') -ne 'h264') { throw (New-WinAppException -Code 'RECORD_FAILED' -Message 'WinApp CLI did not report an H.264 recording.') }
+
+    $artifacts = [Collections.Generic.List[object]]::new()
+    [void]$artifacts.Add([pscustomobject]@{ role = 'capture'; path = $resolvedOutputPath; mime = 'video/mp4' })
+    $representative = @()
+    $frameArtifacts = Get-WinAppPropertyValue $response.data 'frameArtifacts'
+    if ($Frames) {
+        if ($null -eq $frameArtifacts) { throw (New-WinAppException -Code 'RECORD_FAILED' -Message 'Frame artifacts were requested but not reported.') }
+        $framesDirectory = [IO.Path]::GetFullPath([string](Get-WinAppPropertyValue $frameArtifacts 'directory'))
+        $manifestPath = [IO.Path]::GetFullPath([string](Get-WinAppPropertyValue $frameArtifacts 'manifest'))
+        $indexPath = [IO.Path]::GetFullPath([string](Get-WinAppPropertyValue $frameArtifacts 'index'))
+        if (-not (Test-Path -LiteralPath $framesDirectory -PathType Container) -or -not (Test-Path -LiteralPath $manifestPath -PathType Leaf) -or -not (Test-Path -LiteralPath $indexPath -PathType Leaf)) { throw (New-WinAppException -Code 'RECORD_FAILED' -Message 'One or more requested frame artifacts are missing.') }
+        $manifest = Get-Content -LiteralPath $manifestPath -Raw | ConvertFrom-Json -ErrorAction Stop
+        if ([string](Get-WinAppPropertyValue $manifest 'status') -ne 'complete') { throw (New-WinAppException -Code 'RECORD_FAILED' -Message 'Frame manifest is not complete.') }
+        $samples = @(Get-Content -LiteralPath $indexPath | Where-Object { -not [string]::IsNullOrWhiteSpace($_) } | ForEach-Object { $_ | ConvertFrom-Json -ErrorAction Stop })
+        if ($samples.Count -eq 0) { throw (New-WinAppException -Code 'RECORD_FAILED' -Message 'frames.ndjson contains no samples.') }
+        $representative = @(Select-WinAppRepresentativeFrames -Samples $samples -FramesRoot $framesDirectory)
+        foreach ($frame in $representative) { if (-not (Test-Path -LiteralPath $frame.path -PathType Leaf)) { throw (New-WinAppException -Code 'RECORD_FAILED' -Message "Representative frame is missing: $($frame.path)") } }
+        $representativePath = Write-WinAppJsonFile -Value ([pscustomobject]@{ strategy = 'first_middle_last'; samples = $representative }) -Path $representativeOutputPath
+        [void]$artifacts.Add([pscustomobject]@{ role = 'frame-directory'; path = $framesDirectory; mime = 'application/x-directory' })
+        [void]$artifacts.Add([pscustomobject]@{ role = 'frame-manifest'; path = $manifestPath; mime = 'application/json' })
+        [void]$artifacts.Add([pscustomobject]@{ role = 'frame-index'; path = $indexPath; mime = 'application/x-ndjson' })
+        [void]$artifacts.Add([pscustomobject]@{ role = 'representative-frames'; path = $representativePath; mime = 'application/json' })
+    }
+
+    $commandResult = [pscustomobject]@{ exit_code = $response.process.exit_code; arguments = @($arguments) }
+    $metadata = New-WinAppOperationMetadata -Operation 'record' -Version $version.actual -VersionClassification $version.classification -Target $target -ArtifactPath $resolvedOutputPath -Width $recordWidth -Height $recordHeight -CommandResult $commandResult
+    $metadata | Add-Member -NotePropertyName recording -NotePropertyValue ([pscustomobject]@{
+            codec = 'h264'; duration_sec = [double](Get-WinAppPropertyValue $response.data 'durationSec' 0); fps = [double](Get-WinAppPropertyValue $response.data 'fps' 0); capture_mode = [string](Get-WinAppPropertyValue $response.data 'mode'); frames_enabled = [bool]$Frames; representative_frames = $representative
+        })
+    $targetPath = Write-WinAppTargetDocument -Path (Join-Path $run.RunDirectory 'desktop-window.json') -Target $target -VersionInfo $version
+    $metadataPath = Write-WinAppJsonFile -Value $metadata -Path $metadataOutputPath
+    [void]$artifacts.Add([pscustomobject]@{ role = 'desktop-window'; path = $targetPath; mime = 'application/json' })
+    [void]$artifacts.Add([pscustomobject]@{ role = 'recording-metadata'; path = $metadataPath; mime = 'application/json' })
+    $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      = @($artifacts)
+            backend        = $metadata.backend
+            target         = $target
+            recording      = $metadata.recording
+            warnings       = $warnings
+        })
+    Write-VisualResult -RunDirectory $run.RunDirectory -OutputPath $resolvedOutputPath -Kind 'desktop-recording' -ResultJsonPath $resultJson
+}
+catch {
+    Write-WinAppFailure -ErrorRecord $_ -Operation record
+    exit 1
+}

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

@@ -0,0 +1,65 @@
+[CmdletBinding()]
+param(
+    [string]$App,
+    [string]$ProcessName,
+    [string]$WindowTitle,
+    [string]$ClassName,
+    [Nullable[int]]$ProcessId,
+    [Nullable[long]]$Hwnd,
+    [Nullable[int]]$Width,
+    [Nullable[int]]$Height,
+    [string]$OutputPath,
+    [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'
+    if ([string]::IsNullOrWhiteSpace($OutputPath)) { $OutputPath = Join-Path $run.RunDirectory 'screenshot.png' }
+    $resolvedOutputPath = [IO.Path]::GetFullPath($OutputPath)
+    $metadataOutputPath = Join-Path $run.RunDirectory 'screenshot.json'
+    Assert-OutputAvailable -Path $resolvedOutputPath
+    Assert-OutputAvailable -Path $metadataOutputPath
+    $target = Get-WinAppWindowTarget -Executable $version.executable -App $App -ProcessName $ProcessName -WindowTitle $WindowTitle -ClassName $ClassName -ProcessId $ProcessId -Hwnd $Hwnd -Width $Width -Height $Height
+    $arguments = New-WinAppScreenshotArguments -Hwnd $target.hwnd -OutputPath $resolvedOutputPath
+    $response = Invoke-WinAppJson -Executable $version.executable -Arguments $arguments -Operation screenshot
+    $dimensions = Get-PngDimensions -Path $resolvedOutputPath
+    $reportedPath = [string](Get-WinAppPropertyValue $response.data 'filePath')
+    if (-not [string]::IsNullOrWhiteSpace($reportedPath) -and [IO.Path]::GetFullPath($reportedPath) -ne $resolvedOutputPath) {
+        throw (New-WinAppException -Code 'CAPTURE_FAILED' -Message 'WinApp CLI reported a different screenshot output path.')
+    }
+    $associated = @(Get-WinAppPropertyValue $response.data 'windows' @())
+    $commandResult = [pscustomobject]@{ exit_code = $response.process.exit_code; arguments = @($arguments) }
+    $metadata = New-WinAppOperationMetadata -Operation 'screenshot' -Version $version.actual -VersionClassification $version.classification -Target $target -ArtifactPath $resolvedOutputPath -Width $dimensions.width -Height $dimensions.height -AssociatedWindows $associated -CommandResult $commandResult
+    $targetPath = Write-WinAppTargetDocument -Path (Join-Path $run.RunDirectory 'desktop-window.json') -Target $target -VersionInfo $version
+    $metadataPath = Write-WinAppJsonFile -Value $metadata -Path $metadataOutputPath
+    $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 = 'capture'; path = $resolvedOutputPath; mime = 'image/png' },
+                [pscustomobject]@{ role = 'desktop-window'; path = $targetPath; mime = 'application/json' },
+                [pscustomobject]@{ role = 'screenshot-metadata'; path = $metadataPath; mime = 'application/json' }
+            )
+            backend        = $metadata.backend
+            target         = $target
+            capture        = [pscustomobject]@{ status = 'PASS'; semantic_verification = 'REQUIRES_VISUAL_INSPECTION'; mode = 'default_window_capture'; capture_screen = $false }
+            warnings       = $warnings
+        })
+    Write-VisualResult -RunDirectory $run.RunDirectory -OutputPath $resolvedOutputPath -Kind 'desktop-screenshot' -ResultJsonPath $resultJson
+}
+catch {
+    Write-WinAppFailure -ErrorRecord $_ -Operation screenshot
+    exit 1
+}

package/skills/visual-verification/scripts/evaluate-sync.ps1

@@ -0,0 +1,249 @@
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory)]
+    [ValidateNotNullOrEmpty()]
+    [string]$AudioEventsJson,
+    [Parameter(Mandatory)]
+    [double]$VisualEventSeconds,
+    [string]$SpeechJson,
+    [Nullable[double]]$GestureSeconds,
+    [ValidateRange(1, 1000)]
+    [double]$ToleranceMilliseconds = 60,
+    [string]$OutputJson
+)
+
+Set-StrictMode -Version Latest
+
+$toleranceMillisecondsWasExplicit = $PSBoundParameters.ContainsKey('ToleranceMilliseconds')
+$signConvention = 'audio-minus-visual; audio-late is positive and audio-early is negative'
+
+function Get-PropertyOrNull {
+    [OutputType([object])]
+    param(
+        [AllowNull()][object]$Object,
+        [Parameter(Mandatory)][string]$Name
+    )
+
+    if ($null -eq $Object) {
+        return $null
+    }
+
+    $property = $Object.PSObject.Properties[$Name]
+    if ($null -eq $property) {
+        return $null
+    }
+
+    return $property.Value
+}
+
+function ConvertTo-FiniteSeconds {
+    [OutputType([double])]
+    param(
+        [Parameter(Mandatory)][AllowNull()][object]$Value,
+        [Parameter(Mandatory)][string]$Description
+    )
+
+    try {
+        $seconds = [Convert]::ToDouble($Value, [Globalization.CultureInfo]::InvariantCulture)
+    }
+    catch {
+        throw "$Description must be a numeric timestamp in seconds."
+    }
+
+    if ([double]::IsNaN($seconds) -or [double]::IsInfinity($seconds)) {
+        throw "$Description must be a finite timestamp in seconds."
+    }
+
+    return $seconds
+}
+
+function Read-JsonDocument {
+    [OutputType([object])]
+    param(
+        [Parameter(Mandatory)][string]$Path,
+        [Parameter(Mandatory)][string]$Description
+    )
+
+    if (-not (Test-Path -LiteralPath $Path -PathType Leaf)) {
+        throw "$Description does not exist or is not a file: $Path"
+    }
+
+    try {
+        return (Get-Content -LiteralPath $Path -Raw -ErrorAction Stop | ConvertFrom-Json -ErrorAction Stop)
+    }
+    catch {
+        throw "$Description is not valid JSON: $Path. $($_.Exception.Message)"
+    }
+}
+
+function New-TimestampMeasurement {
+    [OutputType([pscustomobject])]
+    param([AllowNull()][object]$Seconds)
+
+    if ($null -eq $Seconds) {
+        return $null
+    }
+
+    return [pscustomobject]@{
+        seconds      = [Math]::Round([double]$Seconds, 6)
+        milliseconds = [Math]::Round(([double]$Seconds) * 1000, 3)
+    }
+}
+
+function New-OffsetMeasurement {
+    [OutputType([pscustomobject])]
+    param(
+        [AllowNull()][object]$MeasuredSeconds,
+        [Parameter(Mandatory)][double]$VisualSeconds
+    )
+
+    if ($null -eq $MeasuredSeconds) {
+        return $null
+    }
+
+    $offsetSeconds = ([double]$MeasuredSeconds) - $VisualSeconds
+    return [pscustomobject]@{
+        seconds      = [Math]::Round($offsetSeconds, 6)
+        milliseconds = [Math]::Round($offsetSeconds * 1000, 3)
+    }
+}
+
+function Write-NewOutputJson {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][string]$Path,
+        [Parameter(Mandatory)][string]$Json
+    )
+
+    $stream = $null
+    try {
+        # CreateNew is the final authority: it also rejects a file created after validation.
+        $stream = [IO.File]::Open($Path, [IO.FileMode]::CreateNew, [IO.FileAccess]::Write, [IO.FileShare]::None)
+    }
+    catch [IO.IOException] {
+        throw "OutputJson already exists or could not be exclusively created: $Path"
+    }
+
+    try {
+        $bytes = [Text.UTF8Encoding]::new($false).GetBytes($Json)
+        $stream.Write($bytes, 0, $bytes.Length)
+        $stream.Flush($true)
+    }
+    finally {
+        $stream.Dispose()
+    }
+}
+
+$audioEventsPath = [IO.Path]::GetFullPath($AudioEventsJson)
+$visualSeconds = ConvertTo-FiniteSeconds -Value $VisualEventSeconds -Description 'VisualEventSeconds'
+$resolvedOutputJson = $null
+if (-not [string]::IsNullOrWhiteSpace($OutputJson)) {
+    $resolvedOutputJson = [IO.Path]::GetFullPath($OutputJson)
+    $outputDirectory = Split-Path -Parent $resolvedOutputJson
+    if (-not (Test-Path -LiteralPath $outputDirectory -PathType Container)) {
+        throw "OutputJson directory does not exist: $outputDirectory"
+    }
+}
+
+$audioDocument = Read-JsonDocument -Path $audioEventsPath -Description 'AudioEventsJson'
+if ((Get-PropertyOrNull -Object $audioDocument -Name 'schema_version') -ne 'agent-verification-lab.audio-events.v1') {
+    throw "AudioEventsJson must use schema_version 'agent-verification-lab.audio-events.v1': $audioEventsPath"
+}
+
+$onsets = [System.Collections.Generic.List[double]]::new()
+foreach ($event in @(Get-PropertyOrNull -Object $audioDocument -Name 'events')) {
+    if ($null -eq $event -or (Get-PropertyOrNull -Object $event -Name 'type') -ne 'onset') {
+        continue
+    }
+
+    $eventTime = Get-PropertyOrNull -Object $event -Name 'time'
+    if ($null -eq $eventTime) {
+        throw "Audio onset in AudioEventsJson has no time: $audioEventsPath"
+    }
+    [void]$onsets.Add((ConvertTo-FiniteSeconds -Value $eventTime -Description 'Audio onset time'))
+}
+
+[Nullable[double]]$audioOnsetSeconds = $null
+if ($onsets.Count -gt 0) {
+    $audioOnsetSeconds = @($onsets | Sort-Object)[0]
+}
+
+[Nullable[double]]$speechFirstWordSeconds = $null
+$speechStatus = 'NOT_SUPPLIED'
+if (-not [string]::IsNullOrWhiteSpace($SpeechJson)) {
+    $speechPath = [IO.Path]::GetFullPath($SpeechJson)
+    $speechDocument = Read-JsonDocument -Path $speechPath -Description 'SpeechJson'
+    if ((Get-PropertyOrNull -Object $speechDocument -Name 'schema_version') -ne 'agent-verification-lab.speech.v1') {
+        throw "SpeechJson must use schema_version 'agent-verification-lab.speech.v1': $speechPath"
+    }
+
+    $wordStarts = [System.Collections.Generic.List[double]]::new()
+    foreach ($word in @(Get-PropertyOrNull -Object $speechDocument -Name 'words')) {
+        if ($null -eq $word) {
+            continue
+        }
+
+        $wordStart = Get-PropertyOrNull -Object $word -Name 'start'
+        if ($null -eq $wordStart) {
+            throw "SpeechJson word has no start timestamp: $speechPath"
+        }
+        [void]$wordStarts.Add((ConvertTo-FiniteSeconds -Value $wordStart -Description 'Speech word start'))
+    }
+
+    if ($wordStarts.Count -gt 0) {
+        $speechFirstWordSeconds = @($wordStarts | Sort-Object)[0]
+        $speechStatus = 'MEASURED'
+    }
+    else {
+        $speechStatus = 'NO_WORDS'
+    }
+}
+
+[Nullable[double]]$gestureTimestamp = $null
+if ($null -ne $GestureSeconds) {
+    $gestureTimestamp = ConvertTo-FiniteSeconds -Value $GestureSeconds -Description 'GestureSeconds'
+}
+
+$audioOffset = New-OffsetMeasurement -MeasuredSeconds $audioOnsetSeconds -VisualSeconds $visualSeconds
+$status = if ($null -eq $audioOffset) {
+    'NO_AUDIO_ONSET'
+}
+elseif ([Math]::Abs([double]$audioOffset.milliseconds) -le $ToleranceMilliseconds) {
+    'IN_TOLERANCE'
+}
+else {
+    'OUT_OF_TOLERANCE'
+}
+$toleranceText = $ToleranceMilliseconds.ToString('0.###', [Globalization.CultureInfo]::InvariantCulture)
+$toleranceBasis = if (-not $toleranceMillisecondsWasExplicit -and $ToleranceMilliseconds -eq 60) {
+    '60 ms default: 20 ms audio analysis window plus conservative timestamp quantization allowance.'
+}
+else {
+    "Caller-selected tolerance: ${toleranceText} ms."
+}
+
+$result = [pscustomobject]@{
+    schema_version                    = 'agent-verification-lab.sync.v1'
+    status                            = $status
+    sign_convention                   = $signConvention
+    tolerance                         = [pscustomobject]@{
+        seconds      = [Math]::Round($ToleranceMilliseconds / 1000.0, 6)
+        milliseconds = [Math]::Round($ToleranceMilliseconds, 3)
+        basis        = $toleranceBasis
+    }
+    visual_event                      = New-TimestampMeasurement -Seconds $visualSeconds
+    audio_onset                       = New-TimestampMeasurement -Seconds $audioOnsetSeconds
+    audio_minus_visual                = $audioOffset
+    speech_status                     = $speechStatus
+    speech_first_word                 = New-TimestampMeasurement -Seconds $speechFirstWordSeconds
+    speech_first_word_minus_visual    = New-OffsetMeasurement -MeasuredSeconds $speechFirstWordSeconds -VisualSeconds $visualSeconds
+    gesture                           = New-TimestampMeasurement -Seconds $gestureTimestamp
+    gesture_minus_visual              = New-OffsetMeasurement -MeasuredSeconds $gestureTimestamp -VisualSeconds $visualSeconds
+}
+
+$json = $result | ConvertTo-Json -Depth 6
+if ($null -ne $resolvedOutputJson) {
+    Write-NewOutputJson -Path $resolvedOutputJson -Json $json
+}
+
+Write-Output $json

package/skills/visual-verification/scripts/extract-frames.ps1

@@ -0,0 +1,79 @@
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory)]
+    [ValidateNotNullOrEmpty()]
+    [string]$InputVideo,
+    [double]$Interval = 0.5,
+    [int]$MaxFrames = 20,
+    [string]$OutputDirectory,
+    [string]$RunDirectory,
+    [switch]$Overwrite
+)
+
+$common = Join-Path $PSScriptRoot 'common.ps1'
+. $common
+
+if (-not (Test-Path -LiteralPath $InputVideo -PathType Leaf)) {
+    throw "Input video does not exist or is not a file: $InputVideo"
+}
+
+if ([double]::IsNaN($Interval) -or [double]::IsInfinity($Interval) -or $Interval -le 0) {
+    throw 'Interval must be positive.'
+}
+
+if ($MaxFrames -lt 1 -or $MaxFrames -gt 100) {
+    throw 'MaxFrames must be between 1 and 100.'
+}
+
+$resolvedInputVideo = [IO.Path]::GetFullPath($InputVideo)
+$run = New-VisualRun -RunDirectory $RunDirectory -Kind 'visual'
+$resolvedRunDirectory = $run.RunDirectory
+if ([string]::IsNullOrWhiteSpace($OutputDirectory)) {
+    $OutputDirectory = Join-Path $resolvedRunDirectory 'frames'
+}
+
+$resolvedOutputDirectory = [IO.Path]::GetFullPath($OutputDirectory)
+if (Test-Path -LiteralPath $resolvedOutputDirectory) {
+    $outputItem = Get-Item -LiteralPath $resolvedOutputDirectory -Force
+    if (-not $outputItem.PSIsContainer) {
+        throw "Output directory path is a file: $resolvedOutputDirectory"
+    }
+
+    $existingItems = @(Get-ChildItem -LiteralPath $resolvedOutputDirectory -Force)
+    if ($existingItems.Count -gt 0 -and -not $Overwrite) {
+        throw "Output directory is not empty; specify -Overwrite to replace frame outputs: $resolvedOutputDirectory"
+    }
+
+    if ($Overwrite) {
+        Get-ChildItem -LiteralPath $resolvedOutputDirectory -Filter 'frame-*.png' -File -Force | Remove-Item -Force
+    }
+}
+else {
+    New-Item -ItemType Directory -Path $resolvedOutputDirectory -ErrorAction Stop | Out-Null
+}
+
+$invariantCulture = [Globalization.CultureInfo]::InvariantCulture
+$intervalText = $Interval.ToString('G17', $invariantCulture)
+$ffmpegArguments = [string[]]@(
+    '-i', $resolvedInputVideo,
+    '-vf', "fps=1/$intervalText",
+    '-frames:v', $MaxFrames.ToString($invariantCulture),
+    '-start_number', '1'
+)
+if ($Overwrite) {
+    $ffmpegArguments += '-y'
+}
+$ffmpegArguments += (Join-Path $resolvedOutputDirectory 'frame-%03d.png')
+
+Invoke-Ffmpeg -FfmpegPath (Get-FfmpegPath) -Arguments $ffmpegArguments -Operation "frame extraction from $resolvedInputVideo"
+$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 = 'frames'; path = $resolvedOutputDirectory; mime = 'application/x-directory' })
+        backend        = [pscustomobject]@{ name = 'ffmpeg'; version = $null }
+        warnings       = @()
+    })
+Write-VisualResult -RunDirectory $resolvedRunDirectory -OutputPath $resolvedOutputDirectory -Kind 'frames' -ResultJsonPath $resultJson

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

@@ -0,0 +1,138 @@
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory)]
+    [ValidateNotNullOrEmpty()]
+    [string]$Input,
+    [string]$OutputJson
+)
+
+Set-StrictMode -Version Latest
+
+$inputPath = $PSBoundParameters['Input']
+
+function Get-PropertyOrNull {
+    [OutputType([object])]
+    param(
+        [AllowNull()]
+        [object]$Object,
+        [Parameter(Mandatory)]
+        [string]$Name
+    )
+
+    if ($null -eq $Object) {
+        return $null
+    }
+
+    $property = $Object.PSObject.Properties[$Name]
+    if ($null -eq $property) {
+        return $null
+    }
+
+    return $property.Value
+}
+
+function Get-FirstStreamOfType {
+    [OutputType([object])]
+    param(
+        [AllowNull()]
+        [object[]]$Streams,
+        [Parameter(Mandatory)]
+        [string]$CodecType
+    )
+
+    $matches = @($Streams | Where-Object { (Get-PropertyOrNull -Object $_ -Name 'codec_type') -eq $CodecType })
+    if ($matches.Count -eq 0) {
+        return $null
+    }
+
+    return $matches[0]
+}
+
+function New-StreamSummary {
+    [OutputType([pscustomobject])]
+    param(
+        [AllowNull()]
+        [object]$Stream
+    )
+
+    return [pscustomobject]@{
+        start_time = Get-PropertyOrNull -Object $Stream -Name 'start_time'
+        duration   = Get-PropertyOrNull -Object $Stream -Name 'duration'
+        time_base  = Get-PropertyOrNull -Object $Stream -Name 'time_base'
+        codec      = Get-PropertyOrNull -Object $Stream -Name 'codec_name'
+    }
+}
+
+if (-not (Test-Path -LiteralPath $inputPath -PathType Leaf)) {
+    throw "Input media file does not exist or is not a file: $inputPath"
+}
+
+$resolvedInput = [IO.Path]::GetFullPath($inputPath)
+if (-not [string]::IsNullOrWhiteSpace($OutputJson)) {
+    $resolvedOutputJson = [IO.Path]::GetFullPath($OutputJson)
+    $outputDirectory = Split-Path -Parent $resolvedOutputJson
+    if (-not (Test-Path -LiteralPath $outputDirectory -PathType Container)) {
+        throw "OutputJson directory does not exist: $outputDirectory"
+    }
+    if (Test-Path -LiteralPath $resolvedOutputJson) {
+        throw "OutputJson already exists; refusing to overwrite: $resolvedOutputJson"
+    }
+}
+
+try {
+    $ffprobeCommand = Get-Command ffprobe -ErrorAction Stop
+}
+catch {
+    throw 'ffprobe was not found on PATH.'
+}
+
+if ($ffprobeCommand.CommandType -ne [System.Management.Automation.CommandTypes]::Application) {
+    throw "ffprobe resolved to '$($ffprobeCommand.CommandType)', not an executable application."
+}
+
+$ffprobeArguments = @(
+    '-v', 'error',
+    '-show_entries', 'format=start_time,duration,size:stream=codec_type,codec_name,start_time,duration,time_base,avg_frame_rate,width,height,sample_rate',
+    '-of', 'json',
+    $resolvedInput
+)
+$ffprobeOutput = & $ffprobeCommand.Source @ffprobeArguments 2>&1
+$ffprobeExitCode = $LASTEXITCODE
+if ($ffprobeExitCode -ne 0) {
+    $diagnostics = ($ffprobeOutput | ForEach-Object { $_.ToString() }) -join [Environment]::NewLine
+    throw "ffprobe inspection failed with exit code $ffprobeExitCode for '$resolvedInput'.$([Environment]::NewLine)$diagnostics"
+}
+
+try {
+    $probe = (($ffprobeOutput | ForEach-Object { $_.ToString() }) -join [Environment]::NewLine | ConvertFrom-Json -ErrorAction Stop)
+}
+catch {
+    throw "ffprobe returned invalid JSON for '$resolvedInput': $($_.Exception.Message)"
+}
+
+$videoStream = Get-FirstStreamOfType -Streams @($probe.streams) -CodecType 'video'
+$audioStream = Get-FirstStreamOfType -Streams @($probe.streams) -CodecType 'audio'
+$video = New-StreamSummary -Stream $videoStream
+$video | Add-Member -NotePropertyName frame_rate -NotePropertyValue (Get-PropertyOrNull -Object $videoStream -Name 'avg_frame_rate')
+$video | Add-Member -NotePropertyName width -NotePropertyValue (Get-PropertyOrNull -Object $videoStream -Name 'width')
+$video | Add-Member -NotePropertyName height -NotePropertyValue (Get-PropertyOrNull -Object $videoStream -Name 'height')
+$audio = New-StreamSummary -Stream $audioStream
+$audio | Add-Member -NotePropertyName sample_rate -NotePropertyValue (Get-PropertyOrNull -Object $audioStream -Name 'sample_rate')
+
+$result = [pscustomobject]@{
+    schema_version = 'agent-verification-lab.media.v1'
+    format         = [pscustomobject]@{
+        start_time = Get-PropertyOrNull -Object $probe.format -Name 'start_time'
+        duration   = Get-PropertyOrNull -Object $probe.format -Name 'duration'
+        size       = Get-PropertyOrNull -Object $probe.format -Name 'size'
+    }
+    video          = $video
+    audio          = $audio
+}
+
+$json = $result | ConvertTo-Json -Depth 4
+if (-not [string]::IsNullOrWhiteSpace($OutputJson)) {
+    Set-Content -LiteralPath $resolvedOutputJson -Value $json -Encoding utf8NoBOM -NoNewline -ErrorAction Stop
+}
+
+Write-Output $json