# Next Session: Install & Sign In to WhatsApp on Annie's Pixel

**Date:** 2026-04-06
**Status:** INFRA VERIFIED — ready to implement

---

## Context

Rajesh wants Annie to install and sign in to WhatsApp on her Pixel 9a. All research is done — this session explored the full ADB automation stack, existing phone infrastructure, and designed a complete implementation plan.

## Annie's Phone Details (CONFIRMED)

- **Device:** Pixel 9a, Android 16 (API 36), serial `62271XEBF9DFD4`
- **Number:** `+917899079007`
- **Carrier:** Airtel (NOT Jio — corrected in session 380)
- **Connection:** USB ADB to Panda
- **BT MAC:** `FC:41:16:C5:AC:61`
- **PIN file:** `~/.her-os/pixel-pin`

## What Exists Already

- `services/annie-voice/phone_adb.py` — low-level ADB wrapper (`_adb()`, `unlock_screen()`, `is_screen_on()`, contacts)
- `docs/RESEARCH-APP-AUTOMATION-FOOD-ORDERING.md` §3.3 — OTP reading pattern via SMS content provider
- `docs/RESEARCH-ADB-AUTOMATION-STACK.md` — full uiautomator2 research

## Open Questions — ALL RESOLVED (Session 438)

1. **uiautomator2?** YES — already in project `.venv/` (v3.5.0). u2 atx-agent initialized on Pixel (port 9008). Connection verified: `Device: tegu Android 36`.
2. **WhatsApp installed?** NO — clean slate. APK sideload path confirmed.
3. **Google account?** YES — Play Store present. (But we're using APK sideload, not Play Store.)

## Designed Architecture (3-layer)

### Layer 1: `services/annie-voice/phone_ui.py` (NEW — reusable UI automation base)
- `connect_device()` — uiautomator2 connect with retry
- `ensure_screen_unlocked(d)` — uses phone_adb.unlock_screen()
- `wait_for_element(d, timeout, **selectors)` — element wait with logging
- `dismiss_popup(d, patterns)` — dismiss known popup patterns
- `handle_permission_popup(d, action)` — Android permission dialog handler
- `read_otp_from_sms(sender_pattern, timeout_s)` — async SMS OTP reader (polls content://sms/inbox)
- `take_screenshot(d, label)` — debug screenshots
- `get_current_screen_text(d)` — dump accessibility hierarchy text

### Layer 2: `scripts/setup_whatsapp.py` (NEW — WhatsApp setup script)
- `check_whatsapp_state(d)` → 'not_installed' | 'installed_not_signed_in' | 'signed_in'
- `install_whatsapp()` — APK sideload via `adb install`
- `launch_whatsapp()` → `d.app_start("com.whatsapp")`
- `accept_terms()` — tap "AGREE AND CONTINUE"
- `handle_permissions()` — dismiss notification/contacts/media popups
- `enter_phone_number(d, "+917899079007")` — country code auto-detected from SIM
- `wait_for_otp(d)` — WhatsApp auto-detect first (30s), fallback to SMS content provider (90s)
- `setup_profile(d, "Annie")` — set display name
- `verify_home_screen(d)` — check "Chats" tab visible

### Layer 3: Tests
- `services/annie-voice/tests/test_phone_ui.py` — mock u2 device + _adb for OTP/popup tests
- `scripts/tests/test_setup_whatsapp.py` — state detection + idempotency tests

### CLI
```bash
python scripts/setup_whatsapp.py --phone-number "+917899079007" --profile-name "Annie"
python scripts/setup_whatsapp.py --status       # check current state
python scripts/setup_whatsapp.py --dry-run       # verify infra only
```

## Key Design Decisions

1. **APK sideload over Play Store** — single `adb install` command vs navigating Play Store UI
2. **uiautomator2 over raw ADB tap** — element selectors (text/resourceId) vs fragile coordinates
3. **phone_ui.py as shared module** — reusable for Swiggy/Zomato/GPay setup scripts later
4. **OTP dual strategy** — WhatsApp auto-detect first, SMS content provider fallback
5. **Idempotent** — script checks state before each step, safe to re-run

## Implementation Order

1. ~~Verify infra (ADB + u2 + SIM) on Panda~~ ✅ DONE (session 438)
2. Download WhatsApp APK to Panda
3. Create `phone_ui.py` with reusable helpers
4. Create `setup_whatsapp.py` with step functions
5. Live test on Pixel
6. Write tests (mocked)
7. Note: uiautomator2 already in project `.venv/` — no requirements.txt change needed

## Risks

- WhatsApp UI resource IDs may differ from expected (text fallback selectors included)
- OTP auto-detect may not work (SMS content provider fallback)
- uiautomator2 atx-agent may need re-init after phone reboot