PIR: Add email polling mechanism

[landomen]

Task/Issue URL: https://app.asana.com/1/137249556945/task/1213993026941871?focus=true

Description

Adds polling mechanism for getEmailData action.

Steps to test this PR

Will be testable later when feature is complete.

UI changes

No UI changes

---

Note

Medium Risk
Adds new backend polling and retry/timeout logic into the PIR actions runner and state engine flow, which can impact opt-out/scan execution timing and failure behavior.

Overview
Implements the previously stubbed getEmailData flow by introducing EmailDataResolver/RealEmailDataResolver to poll the backend for email-extracted fields (e.g. verification codes), returning Success/Pending/Failure.

Wires email polling into RealPirActionsRunner and the state engine: GetEmailData now emits an AwaitEmailData side effect (with a new EMAIL_DATA_POLL stage), pending results trigger RetryAwaitEmailData until timeout, and ready results dispatch EmailDataReceived to store extracted data and continue executing the next broker action. Tests and integration harnesses are updated/added to cover resolver behavior, new event handlers, and the new runner dependency.

^{Reviewed by Cursor Bugbot for commit 90eb151. Bugbot is set up for automated code reviews on this repo. Configure here.}

[landomen]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• PIR: Add email fallback #8656
• PIR: Add getEmailData pixel #8642
• PIR: Fix email data handling #8641
• PIR: Clear emailExtractedData on step completion #8612
• PIR: Update completeRequestData to support scans and email extracted data #8583
• PIR: Add email polling mechanism #8581 👈 (View in Graphite)
• PIR: Add handling of GenerateEmail action #8294
• PIR: Add broker step action handler logic #8282
• PIR: Add state engine models for email flexibility #8233
• PIR: Add new email flexibility action models #8232
• develop

This stack of pull requests is managed by Graphite. Learn more about stacking.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit de20666. Configure here.}

[cursor]

pollingTime likely misinterpreted as interval instead of total timeout

Medium Severity

The GetEmailData.pollingTime field is mapped to pollingIntervalSeconds (the delay between polls), while maxTimeoutSeconds is hardcoded to 60. The field name pollingTime semantically means total polling duration, consistent with its sibling EmailConfirmation.pollingTime. If the backend sends a value like "30" meaning "poll for 30 seconds total," the code instead waits 30 seconds between each poll, and maxAttempts becomes 60/30 = 2 — radically different from the intended behavior. Conversely, a pollingTime of "120" yields maxAttempts = 60/120 = 0, timing out immediately after a single attempt. pollingTime likely belongs as maxTimeoutSeconds, with a fixed constant for the interval.

Additional Locations (1)

• pir/pir-impl/src/main/java/com/duckduckgo/pir/impl/common/PirActionsRunner.kt#L377-L382

 

^{Reviewed by Cursor Bugbot for commit de20666. Configure here.}