Event Flow

1. User lands on screen
   ↓
2. SDK emits screen context
   ↓
3. User interacts with components
   ↓
4. SDK emits component_input / validation_failed
   ↓
5. Backend evaluates trigger policy
   ↓
6. Assistant starts with current context
   ↓
7. Voice conversation
   ↓
8. Session ends, reengagement decision

// In Activity.onResume or navigation callback
AI.setKycStep("pan_entry")

// On text change (debounced)
AI.reportComponentInput(
  componentId = "pan_field",
  hint = "ABCDE****F",
  masked = true
)

AI.trackValidationFailure(
  failureReasonCode = "pan_invalid",
  componentId = "pan_field",
  hint = "ABCDE****F",
  masked = true
)

Passive Timer / Error
  ↓
POST /v1/assistant/trigger/evaluate
  ↓
Backend Rules:
- time_spent > 20s → trigger
- errors >= 2 → trigger
- idle > 12s on critical step → trigger
  ↓
Returns: trigger, action, reason, intervention_mode

SDK receives trigger decision
  ↓
Applies TriggerStartMode:
- CONFIRM_UI → Show dialog
- IMMEDIATE → Start directly
- COOLDOWN → Wait if needed
  ↓
User confirms (or immediate)
  ↓
POST /v1/assistant/session/start
  ↓
Backend:
- Creates LiveKit room
- Dispatches agent
- Returns credentials
  ↓
VoiceSessionListener invoked
  ↓
App connects to LiveKit

Agent joins room
  ↓
GET /v1/assistant/context/{session_id}
  ↓
Backend builds context:
- Session state (screen, errors)
- Screen schema (if available)
- Component hints (redacted)
- KYC knowledge base
  ↓
Returns system prompt for LLM

User speaks
  ↓
STT → Agent receives transcript
  ↓
Agent fetches updated context (optional)
  ↓
LLM generates response
  ↓
TTS → User hears reply
  ↓
Event: voice_conversation_turn

User clicks end / AI.stopAssistant()
  ↓
POST /v1/assistant/session/stop
  ↓
Backend:
- Marks session inactive
- Evaluates reengagement
- Emits activity

User taps help button
  ↓
AI.startAssistant()
  ↓
Skip trigger evaluation
  ↓
Direct to session start

Validation fails
  ↓
AI.trackValidationFailure()
  ↓
Immediate trigger evaluation
  ↓
May offer assistance

User on screen 20+ seconds
  ↓
Passive evaluation fires
  ↓
Trigger evaluates
  ↓
May offer assistance