Adom Browser Extension

desktop_list_windows {}                       # scan titles for "Google Messages" / "Messages"
# or, if your build supports it:
desktop_find_window {titleContains:"Google Messages"}

---
name: reading-google-messages
description: How to find the Google Messages PWA on a Windows desktop and READ SMS out of it — most importantly, to retrieve a one-time 2FA / verification code so you can complete a text-message two-factor login fully automatically. Google Messages for web is usually installed as a taskbar PWA ("Messages - Google Messages for web"); its window renders BLANK to PrintWindow, so you read it with UIA (desktop_find_control), not a background screenshot. Match when the user says "read my texts", "get the SMS code", "what's the 2FA code", "check Google Messages", "find the verification code", "automate the SMS 2FA", or any login that texts a code. Part of the adom-browser-extension site-recipe set (see driving-sites).
---
Part of the **adom-browser-extension** site-recipe set → see **driving-sites**. Generic desktop/UIA
mechanics live in **driving-the-desktop**; THIS page is the Google Messages PWA's quirks.

**Why this exists:** lots of sites text a 6-digit code for 2FA (Gusto, banks, etc.). If the user runs
**Google Messages for web** as a desktop app, the AI can read that code and finish the login with **zero
human steps** — no "please type the code you got." This page is how. (Proven end-to-end on 2026-06-24:
automated a full Gusto SMS-2FA login by reading the code out of this PWA.)

## 1. Find the window (it's a taskbar PWA, not a browser tab)
Google Messages for web, "installed" from `messages.google.com/web`, runs as its **own PWA window** with
window class `Chrome_WidgetWin_1` and a title like **"Messages - Google Messages for web"** (sometimes just
"Messages"). Find its hwnd by title:
```
desktop_list_windows {}                       # scan titles for "Google Messages" / "Messages"
# or, if your build supports it:
desktop_find_window {titleContains:"Google Messages"}
```
Grab the `hwnd` (e.g. 459830). If there's NO such window, the user hasn't installed/opened the PWA — fall
back to surfacing the code request to the human (you can't read what isn't running).

## 2. ⚠️ The gotcha: PrintWindow returns BLANK — read it with UIA instead
The PWA is a heavy SPA; **`desktop_screenshot_window {hwnd}` (PrintWindow) captures an EMPTY/white frame**
when the window is in the background. Do NOT try to OCR a blank shot. Two things that DO work:
- **UIA text read (preferred — works in the BACKGROUND, no foregrounding):**
  ```
  desktop_find_control {hwnd:<msgHwnd>, contains:"verification code"}   # or "is your", or the sender
  ```
  UIA walks the accessibility tree and returns the message text even though PrintWindow can't see it. The
  freshest SMS is the **top conversation**; its preview/body holds the code. This is the money path — it
  reads the code without stealing focus from whatever you're doing.
- **Foreground screenshot (fallback):** `desktop_bring_to_front {hwnd}` → wait ~600ms →
  `desktop_screenshot_window {hwnd}` renders correctly once it's foreground. Use only if UIA text is empty.
  (Restore the user's previous window afterward.)

## 3. Extract the code
The SMS body looks like: **"64039 071276 is your Gusto verification code. We'll never call or text you..."**
(`64039` = the sender shortcode, `071276` = the code). Pull the code with a regex over the UIA text:
- Prefer a digit-run **near** the words "code"/"verification": `/(\d{4,8})(?=[^\d]*\b(?:is your|verification|code))/i`
  then fall back to the first standalone `\b\d{6}\b`.
- **Ignore the shortcode** (4–5 digits like `64039`, `22000`) — it's the SENDER, not the code. The real OTP
  is usually 6 digits. If two numbers appear, the code is the longer/6-digit one, typically the 2nd token.
- **Freshness:** make sure you're reading the NEWEST message (top of the list). If you just triggered a
  resend, wait a few seconds and re-read — codes **expire and are single-use**; a stale code reads fine but
  gets rejected. When in doubt, resend and read the newest.

## 4. Hand the code to the login (entering it)
See **driving-the-desktop** / the site recipe for entry. The hard-won bit: a React single-box OTP field often
**ignores CDP `insertText`/synthetic keys** (value stays empty) — type it with **real OS keystrokes**
(`desktop_type {text:"071276"}`) into the focused field. Always tick "remember this device" if offered so the
2FA doesn't recur.

## 5. Etiquette
- Reading the user's texts is sensitive — only do it to complete a 2FA the user asked you to automate, read
  the **minimum** (just the code), and never log/echo full message bodies you don't need.
- If you foregrounded the PWA, restore the user's prior foreground window when done.

## Quick reference
| Thing | Value |
|---|---|
| Window title | **"Messages - Google Messages for web"** (or "Messages"), class `Chrome_WidgetWin_1` |
| Read the text | `desktop_find_control {hwnd, contains:"verification code"}` (UIA — works backgrounded) |
| ⚠️ Don't | `desktop_screenshot_window` in background → BLANK (PrintWindow can't see the SPA) |
| Code shape | 6 digits; the 4–5-digit number is the **sender shortcode**, not the code |
| Newest SMS | **top** conversation; resend + re-read if a code is rejected (single-use/expiring) |
| Enter it | `desktop_type` (real keystrokes) — CDP insertText often fails on OTP boxes |