@rover-studio/answer-me 0.1.0-rc.1

package/distribution/npm/skills/answerme/scripts/wait-answerme-result.ps1

@@ -0,0 +1,908 @@
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory = $true)]
+    [string]$InteractionId,
+    [string]$ApiBaseUrl,
+    [switch]$AllowInsecureLoopbackHttpForTest,
+    [string]$CredentialPath = $env:ANSWERME_CREATOR_CREDENTIAL_PATH,
+    [string]$ResultTokenEnvironmentVariable = 'ANSWERME_RESULT_TOKEN',
+    [string]$ResultTokenStoreRoot = $env:ANSWERME_RESULT_TOKEN_STORE_ROOT,
+    [switch]$AllowNonDefaultResultTokenStore,
+    [ValidateRange(1, 60)]
+    [int]$PollSeconds = 5,
+    [double]$TimeoutSeconds = 300,
+    [switch]$ValidateOnly
+)
+
+$ErrorActionPreference = 'Stop'
+[Console]::OutputEncoding = [Text.UTF8Encoding]::new($false)
+
+$httpSupport = Join-Path $PSScriptRoot 'windows-http.ps1'
+if (-not (Test-Path -LiteralPath $httpSupport -PathType Leaf)) {
+    throw 'The AnswerMe Windows HTTP helper is missing.'
+}
+. $httpSupport
+$AnswerMeProtocolVersion = '1.1'
+$AnswerMeSkillVersion = '0.3.0'
+
+function Write-AnswerMeWaitFailure {
+    param(
+        [Parameter(Mandatory = $true)][string]$Code,
+        [Parameter(Mandatory = $true)][string]$Message,
+        [Parameter(Mandatory = $true)][int]$ExitCode,
+        [bool]$NetworkCalled = $false
+    )
+
+    [PSCustomObject]@{
+        ok = $false
+        outcome = 'failed'
+        status = 'unknown'
+        code = $Code
+        message = $Message
+        interactionId = $InteractionId
+        networkCalled = $NetworkCalled
+    } | ConvertTo-Json -Depth 5
+    exit $ExitCode
+}
+
+function Get-DefaultAnswerMeCredentialPath {
+    if ([Environment]::OSVersion.Platform -ne [PlatformID]::Win32NT) {
+        return $null
+    }
+    $localAppData = [Environment]::GetFolderPath([Environment+SpecialFolder]::LocalApplicationData)
+    if ([string]::IsNullOrWhiteSpace($localAppData)) {
+        return $null
+    }
+    return Join-Path $localAppData 'AnswerMe\creator-credential.clixml'
+}
+
+$apiBaseUrlPolicyPath = Join-Path $PSScriptRoot 'answerme-api-base-url.ps1'
+if (-not (Test-Path -LiteralPath $apiBaseUrlPolicyPath -PathType Leaf)) {
+    Write-AnswerMeWaitFailure -Code 'api-base-url-policy-missing' -Message 'The AnswerMe API base URL policy is required.' -ExitCode 3
+}
+try {
+    . $apiBaseUrlPolicyPath
+}
+catch {
+    Write-AnswerMeWaitFailure -Code 'api-base-url-policy-unavailable' -Message 'The AnswerMe API base URL policy could not be loaded.' -ExitCode 3
+}
+
+if ([string]::IsNullOrWhiteSpace($InteractionId)) {
+    Write-AnswerMeWaitFailure -Code 'interaction-id-missing' -Message 'InteractionId is required.' -ExitCode 2
+}
+
+$timeoutIsInteger = -not [double]::IsNaN($TimeoutSeconds) -and
+    -not [double]::IsInfinity($TimeoutSeconds) -and
+    [Math]::Truncate($TimeoutSeconds) -eq $TimeoutSeconds
+$effectiveTimeoutSeconds = if ($timeoutIsInteger -and
+    ($TimeoutSeconds -eq 0 -or ($TimeoutSeconds -ge 30 -and $TimeoutSeconds -le 600))) {
+    [int]$TimeoutSeconds
+}
+else {
+    0
+}
+$timeoutDecisionReason = if ($effectiveTimeoutSeconds -eq 0 -and $TimeoutSeconds -ne 0) {
+    'timeout_out_of_range'
+}
+else {
+    $null
+}
+
+$validatedApiBaseUrl = $null
+if (-not [string]::IsNullOrWhiteSpace($ApiBaseUrl)) {
+    try {
+        $validatedApiBaseUrl = Resolve-AnswerMeApiBaseUrl `
+            -ApiBaseUrl $ApiBaseUrl `
+            -AllowInsecureLoopbackHttpForTest:$AllowInsecureLoopbackHttpForTest
+    }
+    catch {
+        Write-AnswerMeWaitFailure -Code 'api-base-url-invalid' -Message $_.Exception.Message -ExitCode 2
+    }
+}
+
+if ($ValidateOnly) {
+    [PSCustomObject]@{
+        ok = $true
+        status = 'validated'
+        interactionId = $InteractionId
+        pollSeconds = $PollSeconds
+        requestedTimeoutSeconds = $TimeoutSeconds
+        effectiveTimeoutSeconds = $effectiveTimeoutSeconds
+        reason = $timeoutDecisionReason
+        protocolVersion = $AnswerMeProtocolVersion
+        skillVersion = $AnswerMeSkillVersion
+        capabilityDiscovery = $true
+        networkCalled = $false
+    } | ConvertTo-Json -Depth 4
+    exit 0
+}
+
+if ($effectiveTimeoutSeconds -eq 0) {
+    [PSCustomObject]@{
+        ok = $false
+        outcome = 'paused'
+        interactionId = $InteractionId
+        status = 'pending'
+        code = if ($null -ne $timeoutDecisionReason) { $timeoutDecisionReason } else { 'wait_not_requested' }
+        requestedTimeoutSeconds = $TimeoutSeconds
+        effectiveTimeoutSeconds = 0
+        reason = $timeoutDecisionReason
+        preserveResultToken = $true
+        recoveryReference = 'references/errors.md'
+        networkCalled = $false
+    } | ConvertTo-Json -Depth 6
+    exit 5
+}
+
+if ([string]::IsNullOrWhiteSpace($ApiBaseUrl)) {
+    if ([string]::IsNullOrWhiteSpace($CredentialPath)) {
+        $CredentialPath = Get-DefaultAnswerMeCredentialPath
+    }
+    if (-not [string]::IsNullOrWhiteSpace($CredentialPath) -and (Test-Path -LiteralPath $CredentialPath -PathType Leaf)) {
+        try {
+            $encryptedCredential = Import-Clixml -LiteralPath $CredentialPath
+            if ($encryptedCredential -isnot [PSCredential]) {
+                throw 'Encrypted credential file does not contain a PSCredential.'
+            }
+            $ApiBaseUrl = $encryptedCredential.UserName
+            $encryptedCredential = $null
+        }
+        catch {
+            Write-AnswerMeWaitFailure -Code 'credential-file-invalid' -Message 'The encrypted AnswerMe configuration cannot be read by this Windows account.' -ExitCode 3
+        }
+    }
+}
+
+if ([string]::IsNullOrWhiteSpace($ApiBaseUrl)) {
+    Write-AnswerMeWaitFailure -Code 'api-base-url-missing' -Message 'A trusted AnswerMe API base URL is required.' -ExitCode 2
+}
+$parsedBaseUrl = $validatedApiBaseUrl
+try {
+    $parsedBaseUrl = Resolve-AnswerMeApiBaseUrl `
+        -ApiBaseUrl $ApiBaseUrl `
+        -AllowInsecureLoopbackHttpForTest:$AllowInsecureLoopbackHttpForTest
+}
+catch {
+    Write-AnswerMeWaitFailure -Code 'api-base-url-invalid' -Message $_.Exception.Message -ExitCode 2
+}
+
+$resultTokenStoreAdapter = Join-Path $PSScriptRoot 'result-token-store.windows.ps1'
+if (-not (Test-Path -LiteralPath $resultTokenStoreAdapter -PathType Leaf)) {
+    Write-AnswerMeWaitFailure -Code 'result-token-store-adapter-missing' -Message 'A protected Result Token Store adapter is required.' -ExitCode 3
+}
+try {
+    . $resultTokenStoreAdapter
+    $resultToken = Get-AnswerMeResultToken `
+        -InteractionId $InteractionId `
+        -StoreRoot $ResultTokenStoreRoot `
+        -AllowNonDefaultStoreRoot:$AllowNonDefaultResultTokenStore
+    $workingToken = [Environment]::GetEnvironmentVariable($ResultTokenEnvironmentVariable, 'Process')
+    if (-not [string]::IsNullOrWhiteSpace($workingToken) -and $workingToken -cne $resultToken) {
+        throw 'The process Result Token does not match the protected credential.'
+    }
+    $resultTokenSource = 'protected-store'
+}
+catch {
+    Write-AnswerMeWaitFailure -Code 'result-token-store-unavailable' -Message $_.Exception.Message -ExitCode 3
+}
+$knownResponseSecrets = @(
+    $resultToken,
+    [Environment]::GetEnvironmentVariable('ANSWERME_CREATOR_KEY', 'Process'),
+    [Environment]::GetEnvironmentVariable('ANSWERME_TEST_CREATOR_KEY', 'Process')
+) | Where-Object { -not [string]::IsNullOrEmpty([string]$_) }
+
+function ConvertFrom-AnswerMeJsonResponse {
+    param([Parameter(Mandatory = $true)][object]$Response)
+    if ([string]::IsNullOrWhiteSpace([string]$Response.Content)) {
+        return $null
+    }
+    try {
+        if ((Get-Command ConvertFrom-Json).Parameters.ContainsKey('DateKind')) {
+            return $Response.Content | ConvertFrom-Json -DateKind String
+        }
+        return $Response.Content | ConvertFrom-Json
+    }
+    catch {
+        return $null
+    }
+}
+
+function Test-AnswerMeWaitResponseFields {
+    param(
+        [AllowNull()][object]$Body,
+        [Parameter(Mandatory = $true)][string[]]$ExpectedFields
+    )
+
+    if ($Body -isnot [PSCustomObject]) { return $false }
+    $actual = @($Body.PSObject.Properties.Name | Sort-Object)
+    $expected = @($ExpectedFields | Sort-Object)
+    return $actual.Count -eq $expected.Count -and
+        -not (Compare-Object -ReferenceObject $expected -DifferenceObject $actual -CaseSensitive)
+}
+
+function Test-AnswerMeWaitNoStoreResponse {
+    param([Parameter(Mandatory = $true)][object]$Response)
+
+    return ([string]$Response.Headers['Cache-Control']).Trim() -ceq 'no-store'
+}
+
+function Test-AnswerMeWaitCapabilitiesResponse {
+    param([AllowNull()][object]$Body)
+
+    if (-not (Test-AnswerMeWaitResponseFields -Body $Body -ExpectedFields @(
+                'protocolVersion', 'schemaVersions', 'clientProtocol', 'capabilities', 'requestId')) -or
+        $Body.protocolVersion -isnot [string] -or
+        $Body.protocolVersion -cne $AnswerMeProtocolVersion -or
+        $Body.requestId -isnot [string] -or
+        [string]::IsNullOrWhiteSpace($Body.requestId) -or
+        $Body.schemaVersions -isnot [Array] -or
+        @($Body.schemaVersions).Count -ne 1 -or
+        ($Body.schemaVersions[0] -isnot [int] -and $Body.schemaVersions[0] -isnot [long]) -or
+        $Body.schemaVersions[0] -ne 1) { return $false }
+
+    $client = $Body.clientProtocol
+    if (-not (Test-AnswerMeWaitResponseFields -Body $client -ExpectedFields @(
+                'supportedVersions', 'recommendedVersion', 'minimumCompatibleSkillVersion')) -or
+        $client.recommendedVersion -isnot [string] -or
+        $client.recommendedVersion -cne $AnswerMeProtocolVersion -or
+        $client.minimumCompatibleSkillVersion -isnot [string] -or
+        [string]::IsNullOrWhiteSpace($client.minimumCompatibleSkillVersion) -or
+        $client.supportedVersions -isnot [Array]) { return $false }
+
+    $versions = @($client.supportedVersions)
+    if ($versions.Count -eq 0 -or
+        @($versions | Where-Object { $_ -isnot [string] -or [string]::IsNullOrWhiteSpace($_) }).Count -gt 0) {
+        return $false
+    }
+    # Compatible responses follow the same frozen v1 contract as creation/enrollment.
+    # A fully typed response excluding this client may still report incompatibility.
+    if ($versions -ccontains $AnswerMeProtocolVersion -and
+        ($versions.Count -ne 2 -or $versions -cnotcontains '1.0' -or
+         $client.minimumCompatibleSkillVersion -cne '0.1.0')) { return $false }
+
+    $capabilities = $Body.capabilities
+    if (-not (Test-AnswerMeWaitResponseFields -Body $capabilities -ExpectedFields @(
+                'createInteraction', 'resultQuery', 'resultWait')) -or
+        $capabilities.createInteraction -isnot [bool] -or
+        $capabilities.resultQuery -isnot [bool]) { return $false }
+
+    $wait = $capabilities.resultWait
+    return (Test-AnswerMeWaitResponseFields -Body $wait -ExpectedFields @(
+                'enabled', 'defaultWaitSeconds', 'maxWaitSeconds')) -and
+        $wait.enabled -is [bool] -and
+        ($wait.defaultWaitSeconds -is [int] -or $wait.defaultWaitSeconds -is [long]) -and
+        $wait.defaultWaitSeconds -eq 55 -and
+        ($wait.maxWaitSeconds -is [int] -or $wait.maxWaitSeconds -is [long]) -and
+        $wait.maxWaitSeconds -eq 600
+}
+
+function Test-AnswerMeWaitDateTime {
+    param([AllowNull()][object]$Value)
+
+    if ($Value -isnot [string] -or
+        [string]$Value -cnotmatch '^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$') {
+        return $false
+    }
+    $parsed = [DateTimeOffset]::MinValue
+    return [DateTimeOffset]::TryParse(
+        [string]$Value,
+        [Globalization.CultureInfo]::InvariantCulture,
+        [Globalization.DateTimeStyles]::RoundtripKind,
+        [ref]$parsed
+    )
+}
+
+function Test-AnswerMeWaitBodyContainsSecret {
+    param(
+        [AllowNull()][object]$Value,
+        [Parameter(Mandatory = $true)][string[]]$Secrets
+    )
+
+    if ($null -eq $Value) { return $false }
+    if ($Value -is [string]) {
+        foreach ($secret in $Secrets) {
+            if (-not [string]::IsNullOrEmpty($secret) -and
+                ([string]$Value).IndexOf($secret, [StringComparison]::Ordinal) -ge 0) {
+                return $true
+            }
+        }
+        return $false
+    }
+    if ($Value -is [PSCustomObject]) {
+        foreach ($property in $Value.PSObject.Properties) {
+            if (Test-AnswerMeWaitBodyContainsSecret -Value $property.Value -Secrets $Secrets) {
+                return $true
+            }
+        }
+        return $false
+    }
+    if ($Value -is [Array]) {
+        foreach ($item in $Value) {
+            if (Test-AnswerMeWaitBodyContainsSecret -Value $item -Secrets $Secrets) {
+                return $true
+            }
+        }
+    }
+    return $false
+}
+
+function Test-AnswerMeAnswerLength {
+    param([string]$Value)
+    $count = 0
+    for ($index = 0; $index -lt $Value.Length; $index += 1) {
+        if ([char]::IsHighSurrogate($Value[$index])) {
+            if ($index + 1 -ge $Value.Length -or -not [char]::IsLowSurrogate($Value[$index + 1])) { return $false }
+            $index += 1
+        }
+        elseif ([char]::IsLowSurrogate($Value[$index])) { return $false }
+        $count += 1
+        if ($count -gt 2000) { return $false }
+    }
+    return $true
+}
+
+function ConvertTo-AnswerMeSafeQuestionnaireResult {
+    param([AllowNull()][object]$Result)
+
+    if ($Result -isnot [PSCustomObject]) { return $null }
+    $resultFields = @($Result.PSObject.Properties.Name)
+    $expectedResultFields = if ($resultFields -ccontains 'additionalContext') {
+        @('type', 'answers', 'additionalContext')
+    }
+    else {
+        @('type', 'answers')
+    }
+    if (-not (Test-AnswerMeWaitResponseFields -Body $Result -ExpectedFields $expectedResultFields) -or
+        $Result.type -isnot [string] -or
+        [string]$Result.type -cne 'questionnaire' -or
+        $Result.answers -isnot [Array] -or
+        ($expectedResultFields -ccontains 'additionalContext' -and
+            ($Result.additionalContext -isnot [string] -or
+                [string]::IsNullOrWhiteSpace([string]$Result.additionalContext) -or
+                ([string]$Result.additionalContext).Length -gt 2000))) {
+        return $null
+    }
+
+    $safeAnswers = [Collections.Generic.List[object]]::new()
+    foreach ($answer in @($Result.answers)) {
+        if ($answer -isnot [PSCustomObject] -or
+            $answer.questionId -isnot [string] -or
+            [string]::IsNullOrWhiteSpace([string]$answer.questionId)) {
+            return $null
+        }
+        $answerFields = @($answer.PSObject.Properties.Name)
+        $valueFields = @($answerFields | Where-Object { $_ -cin @('optionId', 'optionIds', 'customAnswer') })
+        if ($valueFields.Count -ne 1 -or
+            -not (Test-AnswerMeWaitResponseFields `
+                -Body $answer `
+                -ExpectedFields @('questionId', $valueFields[0]))) {
+            return $null
+        }
+        $safeAnswer = [ordered]@{ questionId = [string]$answer.questionId }
+        switch -CaseSensitive ($valueFields[0]) {
+            'optionId' {
+                if ($answer.optionId -isnot [string] -or
+                    [string]::IsNullOrWhiteSpace([string]$answer.optionId)) { return $null }
+                $safeAnswer.optionId = [string]$answer.optionId
+            }
+            'customAnswer' {
+                if ($answer.customAnswer -isnot [string] -or
+                    [string]::IsNullOrWhiteSpace([string]$answer.customAnswer) -or
+                    -not (Test-AnswerMeAnswerLength -Value $answer.customAnswer)) { return $null }
+                $safeAnswer.customAnswer = [string]$answer.customAnswer
+            }
+            'optionIds' {
+                if ($answer.optionIds -isnot [Array] -or
+                    @($answer.optionIds).Count -lt 1 -or
+                    @($answer.optionIds).Count -gt 20) { return $null }
+                $seen = [Collections.Generic.HashSet[string]]::new([StringComparer]::Ordinal)
+                $safeOptionIds = [Collections.Generic.List[string]]::new()
+                foreach ($optionId in @($answer.optionIds)) {
+                    if ($optionId -isnot [string] -or
+                        [string]::IsNullOrWhiteSpace([string]$optionId) -or
+                        -not $seen.Add([string]$optionId)) { return $null }
+                    [void]$safeOptionIds.Add([string]$optionId)
+                }
+                $safeAnswer.optionIds = @($safeOptionIds)
+            }
+            default { return $null }
+        }
+        [void]$safeAnswers.Add([PSCustomObject]$safeAnswer)
+    }
+
+    $safeResult = [ordered]@{
+        type = 'questionnaire'
+        answers = @($safeAnswers)
+    }
+    if ($expectedResultFields -ccontains 'additionalContext') {
+        $safeResult.additionalContext = [string]$Result.additionalContext
+    }
+    return [PSCustomObject]$safeResult
+}
+
+function ConvertTo-AnswerMeSafeResultResponse {
+    param(
+        [AllowNull()][object]$Body,
+        [Parameter(Mandatory = $true)][string]$Endpoint
+    )
+
+    if (-not (Test-AnswerMeWaitResponseFields `
+            -Body $Body `
+            -ExpectedFields @(
+                'interactionId', 'status', 'topic', 'createdAt', 'expiresAt',
+                'completedAt', 'purgeAt', 'result', 'requestId'
+            )) -or
+        $Body.interactionId -isnot [string] -or
+        [string]$Body.interactionId -cne $InteractionId -or
+        $Body.status -isnot [string] -or
+        [string]$Body.status -cnotin @('pending', 'submitted', 'cancelled', 'expired', 'revoked') -or
+        ($Endpoint -ceq 'wait' -and [string]$Body.status -ceq 'pending') -or
+        $Body.topic -isnot [string] -or
+        -not (Test-AnswerMeWaitDateTime -Value $Body.createdAt) -or
+        -not (Test-AnswerMeWaitDateTime -Value $Body.expiresAt) -or
+        ($null -ne $Body.completedAt -and -not (Test-AnswerMeWaitDateTime -Value $Body.completedAt)) -or
+        ($null -ne $Body.purgeAt -and -not (Test-AnswerMeWaitDateTime -Value $Body.purgeAt)) -or
+        $Body.requestId -isnot [string] -or
+        [string]::IsNullOrWhiteSpace([string]$Body.requestId)) {
+        return $null
+    }
+
+    $safeResult = $null
+    if ($null -ne $Body.result) {
+        $safeResult = ConvertTo-AnswerMeSafeQuestionnaireResult -Result $Body.result
+        if ($null -eq $safeResult) { return $null }
+    }
+    return [PSCustomObject][ordered]@{
+        interactionId = [string]$Body.interactionId
+        status = [string]$Body.status
+        topic = [string]$Body.topic
+        createdAt = [string]$Body.createdAt
+        expiresAt = [string]$Body.expiresAt
+        completedAt = if ($null -eq $Body.completedAt) { $null } else { [string]$Body.completedAt }
+        purgeAt = if ($null -eq $Body.purgeAt) { $null } else { [string]$Body.purgeAt }
+        result = $safeResult
+        requestId = [string]$Body.requestId
+    }
+}
+
+function Test-AnswerMeWaitRetryAfter {
+    param(
+        [Parameter(Mandatory = $true)][object]$Response,
+        [switch]$Required,
+        [int]$Maximum = [int]::MaxValue
+    )
+
+    $rawValue = [string]$Response.Headers['Retry-After']
+    if ([string]::IsNullOrWhiteSpace($rawValue)) { return -not $Required }
+    $parsedValue = 0
+    return [int]::TryParse($rawValue, [ref]$parsedValue) -and
+        $parsedValue -ge 1 -and
+        $parsedValue -le $Maximum
+}
+
+function ConvertTo-AnswerMeSafeErrorResponse {
+    param(
+        [Parameter(Mandatory = $true)][int]$HttpStatus,
+        [AllowNull()][object]$Body,
+        [Parameter(Mandatory = $true)][ValidateSet('query', 'wait')][string]$Endpoint,
+        [Parameter(Mandatory = $true)][object]$Response
+    )
+
+    if (-not (Test-AnswerMeWaitNoStoreResponse -Response $Response) -or
+        $Body -isnot [PSCustomObject] -or
+        $Body.requestId -isnot [string] -or
+        [string]::IsNullOrWhiteSpace([string]$Body.requestId)) {
+        return $null
+    }
+
+    $reason = $null
+    switch ($HttpStatus) {
+        400 {
+            $allowedReasons = if ($Endpoint -ceq 'wait') {
+                @('invalid_query', 'invalid_interaction_id', 'request_body_not_allowed', 'invalid_timeout_seconds')
+            }
+            else { @() }
+            if ($allowedReasons.Count -eq 0) {
+                if (-not (Test-AnswerMeWaitResponseFields -Body $Body -ExpectedFields @('code', 'requestId'))) {
+                    return $null
+                }
+            }
+            else {
+                if (-not (Test-AnswerMeWaitResponseFields -Body $Body -ExpectedFields @('code', 'requestId', 'reason')) -or
+                    $Body.reason -isnot [string] -or
+                    [string]$Body.reason -cnotin $allowedReasons) { return $null }
+                $reason = [string]$Body.reason
+            }
+            if ($Body.code -isnot [string] -or [string]$Body.code -cne 'invalid_request') { return $null }
+        }
+        404 {
+            if (-not (Test-AnswerMeWaitResponseFields -Body $Body -ExpectedFields @('code', 'requestId')) -or
+                $Body.code -isnot [string] -or
+                [string]$Body.code -cne 'interaction_not_found') { return $null }
+        }
+        409 {
+            if (-not (Test-AnswerMeWaitResponseFields `
+                    -Body $Body `
+                    -ExpectedFields @(
+                        'code', 'requestId', 'reason', 'receivedProtocolVersion',
+                        'supportedProtocolVersions', 'minimumCompatibleSkillVersion'
+                    )) -or
+                $Body.code -isnot [string] -or
+                [string]$Body.code -cne 'client_protocol_unsupported' -or
+                $Body.reason -isnot [string] -or
+                [string]$Body.reason -cne 'answerme_client_protocol_version_is_not_supported' -or
+                $Body.receivedProtocolVersion -isnot [string] -or
+                [string]::IsNullOrWhiteSpace([string]$Body.receivedProtocolVersion) -or
+                $Body.supportedProtocolVersions -isnot [Array] -or
+                @($Body.supportedProtocolVersions).Count -lt 1 -or
+                @($Body.supportedProtocolVersions | Where-Object {
+                    $_ -isnot [string] -or [string]::IsNullOrWhiteSpace([string]$_)
+                }).Count -gt 0 -or
+                $Body.minimumCompatibleSkillVersion -isnot [string] -or
+                [string]::IsNullOrWhiteSpace([string]$Body.minimumCompatibleSkillVersion)) { return $null }
+            $reason = [string]$Body.reason
+        }
+        429 {
+            if ($Endpoint -cne 'wait' -or
+                -not (Test-AnswerMeWaitResponseFields -Body $Body -ExpectedFields @('code', 'requestId', 'reason')) -or
+                $Body.code -isnot [string] -or
+                [string]$Body.code -cne 'rate_limited' -or
+                $Body.reason -isnot [string] -or
+                [string]$Body.reason -cnotin @(
+                    'result_wait_safety_global_rate_limited',
+                    'result_wait_safety_ip_rate_limited',
+                    'result_wait_interaction_capacity'
+                ) -or
+                -not (Test-AnswerMeWaitRetryAfter -Response $Response -Required -Maximum 60)) { return $null }
+            $reason = [string]$Body.reason
+        }
+        503 {
+            if ($Endpoint -ceq 'wait') {
+                if (-not (Test-AnswerMeWaitRetryAfter -Response $Response -Required)) { return $null }
+                $hasReason = @($Body.PSObject.Properties.Name) -ccontains 'reason'
+                $expectedFields = if ($hasReason) { @('code', 'requestId', 'reason') } else { @('code', 'requestId') }
+                if (-not (Test-AnswerMeWaitResponseFields -Body $Body -ExpectedFields $expectedFields) -or
+                    $Body.code -isnot [string] -or
+                    [string]$Body.code -cnotin @('result_wait_disabled', 'service_unavailable')) { return $null }
+                if ($hasReason) {
+                    if ($Body.reason -isnot [string]) { return $null }
+                    $allowedReasons = if ([string]$Body.code -ceq 'result_wait_disabled') {
+                        @('result_wait_disabled', 'result_wait_not_configured')
+                    }
+                    else {
+                        @(
+                            'capacity_pressure', 'result_wait_auth_queue_full',
+                            'result_wait_auth_queue_timeout', 'result_wait_global_capacity',
+                            'result_wait_dependency_failure'
+                        )
+                    }
+                    if ([string]$Body.reason -cnotin $allowedReasons) { return $null }
+                    $reason = [string]$Body.reason
+                }
+            }
+            else {
+                $hasReason = @($Body.PSObject.Properties.Name) -ccontains 'reason'
+                $expectedFields = if ($hasReason) { @('code', 'requestId', 'reason') } else { @('code', 'requestId') }
+                if (-not (Test-AnswerMeWaitResponseFields -Body $Body -ExpectedFields $expectedFields) -or
+                    $Body.code -isnot [string] -or
+                    [string]$Body.code -cne 'service_unavailable') { return $null }
+                if ($hasReason) {
+                    if ($Body.reason -isnot [string] -or
+                        [string]$Body.reason -cnotin @('writer_admission_full', 'writer_admission_timeout')) {
+                        return $null
+                    }
+                    $reason = [string]$Body.reason
+                }
+                if (-not (Test-AnswerMeWaitRetryAfter -Response $Response)) { return $null }
+            }
+        }
+        default { return $null }
+    }
+
+    return [PSCustomObject]@{
+        code = [string]$Body.code
+        reason = $reason
+        receivedProtocolVersion = if ($HttpStatus -eq 409) { [string]$Body.receivedProtocolVersion } else { $null }
+        supportedProtocolVersions = if ($HttpStatus -eq 409) { @($Body.supportedProtocolVersions) } else { @() }
+        minimumCompatibleSkillVersion = if ($HttpStatus -eq 409) { [string]$Body.minimumCompatibleSkillVersion } else { $null }
+    }
+}
+
+function Get-AnswerMeRetryAfterSeconds {
+    param([Parameter(Mandatory = $true)][object]$Response)
+    $rawValue = [string]$Response.Headers['Retry-After']
+    $parsedValue = 0
+    if ([int]::TryParse($rawValue, [ref]$parsedValue) -and $parsedValue -ge 0) {
+        return $parsedValue
+    }
+    return 0
+}
+
+function Start-AnswerMeBoundedSleep {
+    param(
+        [Parameter(Mandatory = $true)][DateTimeOffset]$Deadline,
+        [Parameter(Mandatory = $true)][double]$Seconds
+    )
+
+    $remainingMilliseconds = [Math]::Max(
+        0,
+        [Math]::Floor(($Deadline - [DateTimeOffset]::UtcNow).TotalMilliseconds)
+    )
+    $requestedMilliseconds = [Math]::Max(0, $Seconds * 1000)
+    $sleepMilliseconds = [int][Math]::Min(
+        [int]::MaxValue,
+        [Math]::Min($remainingMilliseconds, $requestedMilliseconds)
+    )
+    if ($sleepMilliseconds -gt 0) {
+        Start-Sleep -Milliseconds $sleepMilliseconds
+    }
+}
+
+function Get-AnswerMeBoundedRequestTimeoutSeconds {
+    param(
+        [Parameter(Mandatory = $true)][DateTimeOffset]$Deadline,
+        [Parameter(Mandatory = $true)][ValidateRange(1, 300)][int]$MaximumSeconds
+    )
+
+    $remainingSeconds = [int][Math]::Ceiling(
+        ($Deadline - [DateTimeOffset]::UtcNow).TotalSeconds
+    )
+    if ($remainingSeconds -le 0) {
+        return 0
+    }
+    return [Math]::Min($MaximumSeconds, $remainingSeconds)
+}
+
+function Write-AnswerMeWaitTimeout {
+    param(
+        [Parameter(Mandatory = $true)][string]$Status,
+        [AllowNull()][string]$LastError,
+        [Parameter(Mandatory = $true)][string]$Mode
+    )
+
+    [PSCustomObject]@{
+        ok = $false
+        outcome = 'timeout'
+        interactionId = $InteractionId
+        status = $Status
+        code = 'wait-timeout'
+        requestedTimeoutSeconds = $TimeoutSeconds
+        effectiveTimeoutSeconds = $effectiveTimeoutSeconds
+        lastError = $LastError
+        waitMode = $Mode
+        preserveResultToken = $true
+        recoveryReference = 'references/errors.md'
+        resultTokenSource = $resultTokenSource
+        networkCalled = $true
+        recovery = 'Keep the original interaction and rerun this poll while the Result Token remains available.'
+    } | ConvertTo-Json -Depth 6
+    exit 5
+}
+
+function Write-AnswerMeTerminalResult {
+    param(
+        [Parameter(Mandatory = $true)][object]$Body,
+        [Parameter(Mandatory = $true)][string]$Mode
+    )
+    [PSCustomObject]@{
+        ok = $true
+        outcome = 'terminal'
+        interactionId = $InteractionId
+        status = [string]$Body.status
+        response = $Body
+        waitMode = $Mode
+        resultTokenSource = $resultTokenSource
+        networkCalled = $true
+    } | ConvertTo-Json -Depth 32
+    exit 0
+}
+
+function Write-AnswerMeRemoteFailure {
+    param(
+        [Parameter(Mandatory = $true)][int]$HttpStatus,
+        [Parameter(Mandatory = $true)][object]$SafeError,
+        [Parameter(Mandatory = $true)][int]$ExitCode,
+        [int]$RetryAfterSeconds = 0
+    )
+    $remoteCode = [string]$SafeError.code
+    $outcome = if ($HttpStatus -eq 404) { 'not-found' } elseif ($remoteCode -eq 'client_protocol_unsupported') { 'protocol-incompatible' } else { 'failed' }
+    [object[]]$supportedProtocolVersions = @()
+    $supportedProtocolVersions = @($SafeError.supportedProtocolVersions)
+    [PSCustomObject]@{
+        ok = $false
+        outcome = $outcome
+        interactionId = $InteractionId
+        status = 'unknown'
+        code = $remoteCode
+        httpStatus = $HttpStatus
+        reason = $SafeError.reason
+        retryAfterSeconds = $RetryAfterSeconds
+        receivedProtocolVersion = $SafeError.receivedProtocolVersion
+        supportedProtocolVersions = $supportedProtocolVersions
+        minimumCompatibleSkillVersion = $SafeError.minimumCompatibleSkillVersion
+        preserveResultToken = $true
+        recoveryReference = 'references/errors.md'
+        resultTokenSource = $resultTokenSource
+        networkCalled = $true
+    } | ConvertTo-Json -Depth 10
+    exit $ExitCode
+}
+
+function Write-AnswerMeInvalidRemoteResponse {
+    param([Parameter(Mandatory = $true)][int]$HttpStatus)
+
+    [PSCustomObject]@{
+        ok = $false
+        outcome = 'failed'
+        interactionId = $InteractionId
+        status = 'unknown'
+        code = 'result-response-invalid'
+        httpStatus = $HttpStatus
+        reason = $null
+        retryAfterSeconds = 0
+        receivedProtocolVersion = $null
+        supportedProtocolVersions = @()
+        minimumCompatibleSkillVersion = $null
+        preserveResultToken = $true
+        recoveryReference = 'references/errors.md'
+        resultTokenSource = $resultTokenSource
+        networkCalled = $true
+    } | ConvertTo-Json -Depth 10
+    exit 4
+}
+
+$escapedId = [Uri]::EscapeDataString($InteractionId)
+$resultUri = ([Uri]::new($parsedBaseUrl, "/api/v1/interactions/$escapedId")).AbsoluteUri
+$capabilitiesUri = ([Uri]::new($parsedBaseUrl, '/api/v1/capabilities')).AbsoluteUri
+$capabilitiesHeaders = @{
+    Accept = 'application/json'
+    'X-AnswerMe-Protocol-Version' = $AnswerMeProtocolVersion
+    'X-AnswerMe-Skill-Version' = $AnswerMeSkillVersion
+}
+$requestHeaders = @{
+    Authorization = "Bearer $resultToken"
+    Accept = 'application/json'
+    'X-AnswerMe-Protocol-Version' = $AnswerMeProtocolVersion
+    'X-AnswerMe-Skill-Version' = $AnswerMeSkillVersion
+}
+
+$deadline = [DateTimeOffset]::UtcNow.AddSeconds($effectiveTimeoutSeconds)
+$capabilitiesTimeout = Get-AnswerMeBoundedRequestTimeoutSeconds -Deadline $deadline -MaximumSeconds 15
+if ($capabilitiesTimeout -le 0) {
+    Write-AnswerMeWaitTimeout -Status 'unknown' -LastError $null -Mode 'capability-discovery'
+}
+try {
+    $capabilitiesResponse = Invoke-AnswerMeWebRequest -Uri $capabilitiesUri -Method Get -Headers $capabilitiesHeaders -TimeoutSec $capabilitiesTimeout
+}
+catch {
+    if ([DateTimeOffset]::UtcNow -ge $deadline) {
+        Write-AnswerMeWaitTimeout -Status 'unknown' -LastError $_.Exception.Message -Mode 'capability-discovery'
+    }
+    Write-AnswerMeWaitFailure -Code 'capabilities-unavailable' -Message $_.Exception.Message -ExitCode 4 -NetworkCalled $true
+}
+$capabilitiesBody = ConvertFrom-AnswerMeJsonResponse -Response $capabilitiesResponse
+if ([int]$capabilitiesResponse.StatusCode -eq 200 -and
+    (-not (Test-AnswerMeWaitNoStoreResponse -Response $capabilitiesResponse) -or
+     (Test-AnswerMeWaitBodyContainsSecret -Value $capabilitiesBody -Secrets $knownResponseSecrets) -or
+     -not (Test-AnswerMeWaitCapabilitiesResponse -Body $capabilitiesBody))) {
+    Write-AnswerMeWaitFailure -Code 'capabilities-invalid' -Message 'AnswerMe capabilities could not be verified.' -ExitCode 4 -NetworkCalled $true
+}
+$supportedProtocolVersions = @($capabilitiesBody.clientProtocol.supportedVersions)
+if ([int]$capabilitiesResponse.StatusCode -eq 200 -and
+    $supportedProtocolVersions -notcontains $AnswerMeProtocolVersion) {
+    $protocolCompatibilityError = [PSCustomObject]@{
+        code = 'client_protocol_unsupported'
+        reason = 'answerme_client_protocol_version_is_not_supported'
+        receivedProtocolVersion = $AnswerMeProtocolVersion
+        supportedProtocolVersions = $supportedProtocolVersions
+        minimumCompatibleSkillVersion = [string]$capabilitiesBody.clientProtocol.minimumCompatibleSkillVersion
+    }
+    Write-AnswerMeRemoteFailure -HttpStatus 200 -SafeError $protocolCompatibilityError -ExitCode 6
+}
+if ([int]$capabilitiesResponse.StatusCode -ne 200 -or
+    $capabilitiesBody.capabilities.resultQuery -ne $true) {
+    if ([int]$capabilitiesResponse.StatusCode -eq 409) {
+        $safeCapabilityError = ConvertTo-AnswerMeSafeErrorResponse `
+            -HttpStatus 409 `
+            -Body $capabilitiesBody `
+            -Endpoint query `
+            -Response $capabilitiesResponse
+        if ($null -ne $safeCapabilityError -and
+            -not (Test-AnswerMeWaitBodyContainsSecret -Value $capabilitiesBody -Secrets $knownResponseSecrets)) {
+            Write-AnswerMeRemoteFailure -HttpStatus 409 -SafeError $safeCapabilityError -ExitCode 6
+        }
+    }
+    Write-AnswerMeWaitFailure -Code 'capabilities-invalid' -Message 'AnswerMe capabilities could not be verified.' -ExitCode 4 -NetworkCalled $true
+}
+
+$useActiveWait = $capabilitiesBody.capabilities.resultWait.enabled -eq $true
+$lastStatus = 'unknown'
+$lastError = $null
+
+while ([DateTimeOffset]::UtcNow -lt $deadline) {
+    $remainingSeconds = [Math]::Max(1, [int][Math]::Ceiling(($deadline - [DateTimeOffset]::UtcNow).TotalSeconds))
+    if ($useActiveWait) {
+        $windowSeconds = [Math]::Min($effectiveTimeoutSeconds, $remainingSeconds)
+        if ($windowSeconds -lt 30) {
+            Write-AnswerMeWaitTimeout -Status $lastStatus -LastError $lastError -Mode 'capability-discovery'
+        }
+        $requestUri = "$resultUri/wait?timeoutSeconds=$windowSeconds"
+        $requestTimeout = $windowSeconds + 20
+        $mode = 'active-wait'
+    }
+    else {
+        $requestUri = $resultUri
+        $requestTimeout = [Math]::Min([Math]::Max(15, $PollSeconds + 10), $remainingSeconds)
+        $mode = 'polling-compatibility'
+    }
+
+    try {
+        $response = Invoke-AnswerMeWebRequest -Uri $requestUri -Method Get -Headers $requestHeaders -TimeoutSec $requestTimeout
+    }
+    catch {
+        $lastError = $_.Exception.Message
+        Write-AnswerMeWaitFailure -Code 'result-connection-unknown' -Message $_.Exception.Message -ExitCode 4 -NetworkCalled $true
+    }
+
+    $statusCode = [int]$response.StatusCode
+    $body = ConvertFrom-AnswerMeJsonResponse -Response $response
+    $endpoint = if ($useActiveWait) { 'wait' } else { 'query' }
+    if (Test-AnswerMeWaitBodyContainsSecret -Value $body -Secrets $knownResponseSecrets) {
+        Write-AnswerMeInvalidRemoteResponse -HttpStatus $statusCode
+    }
+    if ($statusCode -eq 200) {
+        if (-not (Test-AnswerMeWaitNoStoreResponse -Response $response)) {
+            Write-AnswerMeInvalidRemoteResponse -HttpStatus 200
+        }
+        $safeResult = ConvertTo-AnswerMeSafeResultResponse -Body $body -Endpoint $endpoint
+        if ($null -eq $safeResult) {
+            Write-AnswerMeInvalidRemoteResponse -HttpStatus 200
+        }
+        $lastStatus = [string]$safeResult.status
+        $lastError = $null
+        if ($lastStatus -in @('submitted', 'cancelled', 'expired', 'revoked')) {
+            Write-AnswerMeTerminalResult -Body $safeResult -Mode $mode
+        }
+        if ($useActiveWait) {
+            Write-AnswerMeInvalidRemoteResponse -HttpStatus 200
+        }
+    }
+    elseif ($statusCode -eq 204 -and $useActiveWait) {
+        $waitReason = [string]$response.Headers['X-AnswerMe-Result-Wait-Reason']
+        if ($null -ne $body -or
+            -not (Test-AnswerMeWaitNoStoreResponse -Response $response) -or
+            $waitReason -cne 'timeout') {
+            Write-AnswerMeInvalidRemoteResponse -HttpStatus 204
+        }
+        Write-AnswerMeWaitTimeout -Status 'pending' -LastError $null -Mode 'active-wait'
+    }
+    elseif ($statusCode -in @(400, 404, 409, 429, 503)) {
+        if (($statusCode -eq 429 -and -not $useActiveWait)) {
+            Write-AnswerMeInvalidRemoteResponse -HttpStatus $statusCode
+        }
+        $safeError = ConvertTo-AnswerMeSafeErrorResponse `
+            -HttpStatus $statusCode `
+            -Body $body `
+            -Endpoint $endpoint `
+            -Response $response
+        if ($null -eq $safeError) {
+            Write-AnswerMeInvalidRemoteResponse -HttpStatus $statusCode
+        }
+        $retryAfter = Get-AnswerMeRetryAfterSeconds -Response $response
+        Write-AnswerMeRemoteFailure `
+            -HttpStatus $statusCode `
+            -SafeError $safeError `
+            -ExitCode $(if ($statusCode -eq 409) { 6 } else { 4 }) `
+            -RetryAfterSeconds $retryAfter
+    }
+    else {
+        Write-AnswerMeInvalidRemoteResponse -HttpStatus $statusCode
+    }
+
+    if (-not $useActiveWait) {
+        Start-AnswerMeBoundedSleep -Deadline $deadline -Seconds $PollSeconds
+    }
+}
+
+$timeoutMode = if ($useActiveWait) { 'active-wait' } else { 'polling-compatibility' }
+Write-AnswerMeWaitTimeout -Status $lastStatus -LastError $lastError -Mode $timeoutMode