Triggers and Lifecycle

Runtime Core (SdkRuntime.kt)

Single internal orchestrator holding:

• RuntimeContext, RuntimePolicy
• PassiveTracker, BackendClient
• AndroidUiBridge (current Activity, confirm dialog)

Trigger Evaluation Flow

Passive Evaluation

Scheduled when passiveEvalEnabled and interval > 0:

SDK Passive Loop
  ↓
Backend POST /v1/assistant/trigger/evaluate
  ↓
Returns: trigger (boolean), reason, action, intervention_mode
  ↓
SDK applies TriggerStartMode

Error-Driven Evaluation

Both trackError and trackValidationFailure call maybeEvaluateTriggerAfterError:

Error Reported
  ↓
Evaluate Trigger with signals
  ↓
If trigger allowed → Apply TriggerStartMode

TriggerStartMode

Session Lifecycle

Start Flow

AI.startAssistant() OR Trigger decides to start
  ↓
Check RECORD_AUDIO permission
  ↓
POST /v1/assistant/session/start
  ↓
Backend creates LiveKit dispatch
  ↓
Returns: token, livekit_url, livekit_room
  ↓
VoiceSessionListener invoked
  ↓
App connects to LiveKit room

Stop Flow

User ends call OR AI.stopAssistant()
  ↓
POST /v1/assistant/session/stop
  ↓
Backend emits reengagement activity
  ↓
Session resources cleaned up

Lifecycle and Passive Signals

When AI.attach is used:

• onActivityResumed: binds current activity, observes screen, records interaction
• PassiveTracker derives:
  • Time on current "screen" (seconds)
  • Idle seconds from last interaction

These feed into trigger signals when enabled in TriggerSettings.

Stability Rules

• Avoid duplicate trigger prompts after user dismissal
• Keep trigger suppression flags aligned between backend and SDK
• Dismissal resets passive tracker via onInteraction()

Trigger Settings

Configure via TriggerSettings in RuntimePolicy:

Backend Trigger Flags

• trigger.v2_scoring — improved scoring algorithm
• trigger.policy_engine — policy-based rules
• trigger.intervention_modes — different UX modes
• trigger.experiments — A/B test support

Reengagement

When session stops, backend emits reengagement activity with:

• recommended — whether to re-engage
• channel — preferred channel
• reason — why reengagement is/isn't recommended
• inactivity_seconds — time since last activity