PIR: Add state engine models for email flexibility (#8233)

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

### Description
Adds state engine models for email flexibility.

### Steps to test this PR
Will be testable on upstream PRs once whole feature is finished.

### UI changes
No UI changes

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Model and empty handler only; no polling, transitions, or user-facing behavior until later steps.
> 
> **Overview**
> Introduces **scaffolding** in the PIR actions runner state engine for polling and storing **email-derived fields** during broker steps, parallel to the existing captcha await flow.
> 
> `PirActionsRunnerStateEngine` gains `emailExtractedData` on `State`, events `EmailDataReceived` and `RetryAwaitEmailData`, and side effect `AwaitEmailData` (broker, address, attempt id, extract fields, polling/timeout, attempt). `PirActionsRunner` routes `AwaitEmailData` to a new `handleAwaitEmailData` that is **not implemented yet** (TODO for a later step / `EmailDataResolver`).
> 
> No runtime behavior change until follow-up work wires transitions and polling.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit 9e478a8. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: landomen

pir/pir-impl/src/main/java/com/duckduckgo/pir/impl/common/PirActionsRunner.kt

@@ -271,6 +271,7 @@ class RealPirActionsRunner @AssistedInject constructor(
                 }
 
             is AwaitCaptchaSolution -> handleAwaitCaptchaSolution(effect)
+            is SideEffect.AwaitEmailData -> handleAwaitEmailData(effect)
         }
     }
 
@@ -358,6 +359,10 @@ class RealPirActionsRunner @AssistedInject constructor(
             }
         }
 
+    private suspend fun handleAwaitEmailData(effect: SideEffect.AwaitEmailData) {
+        // TODO: Implement in step 5 — poll for email data via EmailDataResolver
+    }
+
     private suspend fun handleGetCaptchaSolution(effect: GetCaptchaSolution) =
         withContext(dispatcherProvider.io()) {
             nativeBrokerActionHandler

pir/pir-impl/src/main/java/com/duckduckgo/pir/impl/common/actions/PirActionsRunnerStateEngine.kt

@@ -56,6 +56,7 @@ interface PirActionsRunnerStateEngine {
         val preseeding: Boolean = false,
         val actionRetryCount: Int = 0,
         val generatedEmailData: GeneratedEmailData? = null,
+        val emailExtractedData: Map<String, String> = emptyMap(),
         val attemptId: String = "",
         val stageStatus: PirStageStatus,
     )
@@ -137,6 +138,21 @@ interface PirActionsRunnerStateEngine {
         data class ConditionExpectationSucceeded(
             val conditionActions: List<BrokerAction>,
         ) : Event()
+
+        data class EmailDataReceived(
+            val emailExtractedData: Map<String, String>,
+        ) : Event()
+
+        data class RetryAwaitEmailData(
+            val actionId: String,
+            val brokerName: String,
+            val emailAddress: String,
+            val attemptId: String,
+            val extractFields: List<String>,
+            val pollingIntervalSeconds: Int,
+            val maxTimeoutSeconds: Int,
+            val attempt: Int,
+        ) : Event()
     }
 
     /**
@@ -181,6 +197,18 @@ interface PirActionsRunnerStateEngine {
         ) : SideEffect(),
             BrokerActionSideEffect
 
+        data class AwaitEmailData(
+            override val actionId: String,
+            val brokerName: String,
+            val emailAddress: String,
+            val attemptId: String,
+            val extractFields: List<String>,
+            val pollingIntervalSeconds: Int,
+            val maxTimeoutSeconds: Int = 60,
+            val attempt: Int = 0,
+        ) : SideEffect(),
+            BrokerActionSideEffect
+
         data class LoadUrl(
             val url: String,
         ) : SideEffect()