# Next Session: Research Robust WhatsApp Automation + Implement Google Maps Tool

## Priority 1: WhatsApp Automation Research

### What
Rajesh flagged the current WhatsApp Web automation (Playwright selector-chasing) as **fragile**. Session 11 required fixing 7 selectors/bugs during deployment — every WhatsApp Web update will break things again. Research how others solve this problem robustly.

### Research Questions
1. **WAHA (WhatsApp HTTP API)** — Self-hosted Docker container that wraps WhatsApp Web. How does it handle image sending? What's the ban risk vs our Playwright approach? Does it abstract away selector changes?
2. **Baileys / whatsapp-web.js** — Protocol-level libraries that reverse-engineer WhatsApp's WebSocket protocol. No browser needed. How do they send images? What's the maintenance burden when WhatsApp updates their protocol?
3. **ADB-based alternatives** — Instead of WhatsApp Web, automate the WhatsApp Android app on Panda's Pixel via uiautomator2. Share images via Android intents (`am start -a android.intent.action.SEND`). More stable selectors?
4. **Hybrid approach** — Keep Playwright for reading messages (poll loop works), but send images via a different mechanism (ADB intent, WAHA API, etc.)?
5. **What do production WhatsApp bots use?** — Survey open-source projects that send images via WhatsApp. What patterns survive WhatsApp updates?

### Constraints (from memory)
- `memory/feedback_whatsapp_adb_only.md` — **ADB-only constraint**: No Cloud API (needs business number), no unofficial SDKs that risk bans. Zero ban risk is the hard requirement.
- Current architecture: Playwright headless Chromium on Panda, WhatsApp Web session, poll loop for reading, DOM manipulation for sending.
- The READING side (poll loop) is reasonably stable — `.message-in` class + `data-pre-plain-text` work. The SENDING side (especially image attachment) is what breaks.

### Output
Write findings to `docs/RESEARCH-WHATSAPP-ROBUST-AUTOMATION.md` with:
- Comparison table of approaches (WAHA, Baileys, ADB intent, current Playwright)
- Ban risk assessment for each
- Maintenance burden (how often does each break?)
- Recommendation for image sending specifically
- Migration path from current approach

## Priority 2: Implement Google Maps Tool

### What
After the research is saved, implement the Google Maps tool for Annie. The plan is fully reviewed (25 adversarial findings addressed).

### Plan
`~/.claude/plans/glowing-soaring-parrot.md`

Read the plan first — it has the full architecture, all review findings, and implementation order.

### Key Design Decisions (from adversarial review)
1. **httpx.AsyncClient, NOT `googlemaps` package** — sync package blocks Pipecat event loop
2. **Literal types** for search_type and travel_mode — prevents Gemma 4 hallucination
3. **Lazy home address loading** — no import-time I/O crash
4. **departure_time only for driving/transit** — API errors on other modes
5. **Privacy: generic area name in nearby URLs** — not resolved home address
6. **400 char output cap** — fits Gemma 4's token budget
7. **Add to _TOOL_LEAK_RE** — prevent speaking raw JSON tool calls
8. **Add to _SECRET_ENV_KEYS** — scrub API key from logs
9. **Observability creature "compass"** — dashboard visibility
10. **Check OVER_QUERY_LIMIT in response body** — Google returns errors inside HTTP 200

### Files to Modify
1. `services/annie-voice/maps_tools.py` — **CREATE**: httpx Google Maps handler (~250 lines)
2. `services/annie-voice/tool_schemas.py` — **ADD**: GoogleMapsInput with Literal types
3. `services/annie-voice/text_llm.py` — **ADD**: ToolSpec + _SECRET_ENV_KEYS + _SECRET_PATTERNS
4. `services/annie-voice/tool_adapters.py` — **ADD**: MapsAdapter
5. `services/annie-voice/bot.py` — **EDIT**: _TOOL_LEAK_RE + _NARRATION_PHRASES
6. `services/annie-voice/observability.py` — **EDIT**: Add "compass" creature
7. `services/annie-voice/.env.example` — **EDIT**: Add GOOGLE_MAPS_API_KEY=
8. `services/annie-voice/tests/test_maps_tools.py` — **CREATE**: Unit tests (~200 lines)

### Start Command
```bash
# Step 1: Research WhatsApp robustness
# Write findings to docs/RESEARCH-WHATSAPP-ROBUST-AUTOMATION.md

# Step 2: Read the Google Maps plan
cat ~/.claude/plans/glowing-soaring-parrot.md

# Step 3: Implement in order:
# Phase 1: Schema + URL builder + home address resolution + tests
# Phase 2: Directions API via httpx + departure_time handling + tests
# Phase 3: Nearby Places API via httpx + privacy-safe URLs + tests
# Phase 4: ToolSpec + adapter + bot.py wiring + observability + secrets
# Phase 5: Deploy (API key in .env on Titan) + E2E test
```

### Verification
1. `cd services/annie-voice && python3 -m pytest tests/test_maps_tools.py -v` — all tests pass
2. E2E voice: "Annie, how long to get to Skandagiri from home?"
3. E2E Telegram: "Find coffee shops near HSR Layout"
4. Verify Google Maps link is clickable in WhatsApp and Telegram
5. Verify `/v1/capabilities` lists google_maps
6. Verify API key not in logs (grep for AIzaSy)