feat(ui): preserve email connector grant + scope consent under Path 2 (incl. Outlook CTA)

[itomek]

Closes #1770. Part of the Path-2 email-in-Agent-UI epic #1767.

Stacked on #1774 (#1768, backend mount). Review after/with it; I'll retarget to main once #1774 merges.

Why this matters

Under Path 2 email is consumed as a backend REST surface, not an activated chat agent — but it still needs write-level OAuth scopes (gmail.modify+gmail.send+calendar.events / Mail.ReadWrite+Mail.Send+Calendars.ReadWrite). Before: consent was driven by email being a granted/activated chat agent, and the Connect CTA only offered Google (Outlook users had no path). If the user connected a mailbox without granting installed:email, write calls failed at call time. After: the Connectors panel surfaces email's requirement from the registry independent of chat activation, the CTA drives consent for both Google and Microsoft, and every insufficient/absent-scope state returns an actionable error + the Connect/Reconnect CTA — never a silent success or generic 500.

Evidence

22 Python regression tests — tests/test_ui_email_scope_consent.py (all pass) covering every AC:

• scope resolution from installed:email REQUIRED_CONNECTORS independent of chat activation
• negative (a) connected-but-not-granted → AGENT_NOT_GRANTED (Google + Microsoft)
• negative (b) mail scopes but no calendar.events → CONNECTION_MISSING_SCOPES; triage/draft/send still work
• negative (c) no mailbox → HTTP 503
• legacy builtin:email → installed:email grant migration (regression-guard [Bug]: Agent UI — connected Google account can't be used by Email Triage agent (per-agent grant missing in UI, then token 401) #1592)

$ python -m pytest tests/test_ui_email_scope_consent.py -q
22 passed

20 Vitest — EmailConnectCta.test.ts (all pass): provider-aware dual-button CTA (detectProvider, Microsoft auth-required paths). npm run build clean (2086 modules).

Real-world (in progress)

Live Gmail + Outlook consent (showing the requested email scopes) is being captured on macOS with the test accounts; cross-platform (Linux/Windows) follows. Posted as a follow-up.

Test plan

• python -m pytest tests/test_ui_email_scope_consent.py -v → 22 passed
• cd src/gaia/apps/webui && npm test -- EmailConnectCta && npm run build
• Live: connect Google + Microsoft → consent shows the mail+calendar scopes; the 3 negative states show the actionable CTA

[itomek]

Real-world (macOS) — live Google OAuth consent ✅

Verified on macOS via the Agent UI's in-app connector setup (no env vars — client creds entered in Settings → Connectors → Google, stored in the OS keyring):

• Consent requested the full mail+calendar scope set. The Google OAuth URL carried gmail.modify + gmail.send + calendar.events (plus gmail.readonly/calendar.readonly/drive) — i.e. the write/send/calendar scopes the email agent requires.
• Connected to the test account tomasz.iniewicz@gmail.com.
• The Connectors panel surfaces the email requirement independent of chat activation — a "Email Triage" per-agent grant card appears with granular toggles: Organize emails (archive/label/trash) = gmail.modify, Send emails on your behalf = gmail.send, Create & respond to calendar events = calendar.events, View calendar events = calendar.readonly. (Calendar toggles default off — the live equivalent of negative-case (b).)

Cross-platform (Linux + Windows) OAuth runs next as a coordinated pass. The three negative-scope cases remain covered by the 22 Python tests.

[github-actions]

Summary

Clean, well-scoped frontend change that makes the email Connect CTA provider-aware (Google and Microsoft) and adds a thorough Python regression suite for the email connector's grant/scope consent under Path 2. I traced the detection logic against the real format_connector_error outputs in src/gaia/connectors/formatting.py and it routes correctly for every state; the new test file imports only real symbols and its assertions match the live implementations (grant-migration idempotency, scope constants, _raise_http_for status mapping). No security concerns, no new dependencies.

The single most important thing: the test suite is almost entirely mock-based (it patches check_agent_grant / load_connection / get_provider), so it proves the control flow and HTTP mapping, not that the OAuth scope request is actually accepted by Google/Microsoft. Per CLAUDE.md's "mocks prove we called it, not that the call is valid," the pending live Gmail+Outlook consent capture is the real gate — and you've honestly flagged it as in-progress, which is the right call. Treat that evidence as the merge-blocker, not the unit tests.

Issues Found

🟢 Minor — CTA loses its "reopen sign-in" affordance (EmailConnectCta.tsx:124)

Previously the button stayed clickable after opening OAuth (disabled={busy}, label "Reopen Google sign-in"). Now it's permanently disabled once clicked (disabled={busy || done}, label "… sign-in opened"). If the user accidentally closes the OAuth tab before finishing, the only recovery is re-sending the message — they can't reopen from the CTA. If keeping the reopen path is desired, allowing a re-click restores it (clicking again just re-runs handleConnect):

                disabled={busy}
                aria-label={done ? `Reopen ${label} sign-in` : `Connect ${label}`}

(and the span text would become Reopen ${label} sign-in when done). If the disabled state is intentional — to signal the action already fired — feel free to keep it; flagging the behavior change so it's a deliberate choice.

🟢 Minor — naming drift: resolve_send_backend vs get_send_backend

The test docstrings and PR description refer to resolve_send_backend, but the actual function (and the import in the test) is get_send_backend (hub/agents/python/email/gaia_agent_email/api_routes.py:659). Cosmetic, but it'll trip up a future reader grepping for resolve_send_backend. Worth a find/replace in the docstrings in tests/test_ui_email_scope_consent.py.

🟢 Minor — unused props / belt-and-suspenders branches (no action required)

Two harmless leftovers worth a mental note, not a change:

• The connectorId prop on EmailConnectCta has no remaining callers — MessageBubble.tsx:512 is the only caller and now passes content. It's tested and safe, just speculative back-compat.
• The Microsoft branch in isAuthRequiredMessage (connectors → microsoft, etc.) only fires for un-prefixed messages; every real format_connector_error Microsoft output already carries the NOT_CONNECTED: / AGENT_NOT_GRANTED: / AUTH_REQUIRED: prefix caught earlier. It mirrors the Google branch, so keeping it for symmetry is reasonable.

Heads-up (not introduced here) — Outlook user + migration-override message

The installed:email AGENT_NOT_GRANTED override in formatting.py:40 is hardcoded Google-only ("additional Google permissions… Connectors → Google"). An Outlook-only user who somehow hit that specific override would see a Google CTA. In practice Outlook users hit the generic AGENT_NOT_GRANTED (which correctly names microsoft), and that override is keyed to the pre-#962 Google scope-addition migration — so this isn't reachable for Outlook and predates this PR. Noting it only so it's on the radar for the epic's cleanup.

Strengths

• Detection logic is correct against the source of truth. I checked every branch against format_connector_error: Microsoft NOT_CONNECTED/AGENT_NOT_GRANTED messages carry microsoft (in the prefix text and the Graph scope URIs), so detectProvider routes them to the Microsoft button; ambiguous/AUTH_REQUIRED falls back to showing both. The "never render zero buttons" design is exactly the no-silent-dead-end behavior CLAUDE.md asks for.
• Tests track real code, not a parallel reality. The grant-migration tests match migrate_legacy_agent_grants's idempotency contract line-for-line, scope assertions read from the live EmailTriageAgent.REQUIRED_CONNECTORS / OUTLOOK_*_SCOPES constants (so they can't silently drift), and the 403/503 mappings assert against the actual _raise_http_for branches.
• Honest, well-structured PR description — leads with before/after user impact, separates passing unit evidence from pending live evidence, and flags the feat(ui): serve email from the UI backend — mount gaia-agent-email REST router (Path 2) #1774/feat(ui): serve email from the UI backend — mount gaia-agent-email REST router (Path 2) #1768 stacking dependency rather than hiding it.

Verdict

Approve with suggestions. No blocking issues — the change is clean, the refactor (ProviderButton extraction) is sound, and coverage is strong. The 🟢 items are polish. Two non-code caveats for the maintainer: (1) the /v1/email tests depend on the #1768 REST mount, so they'll only go green once #1774 lands — review with/after it as you noted; and (2) the live Gmail+Outlook consent screenshots are the real proof that the negative-state CTAs fire end-to-end, so hold final sign-off on that follow-up.

The base branch was changed.

[itomek]

Thanks — addressed in 7998aae:

• CTA reopen affordance (EmailConnectCta.tsx) — fixed. The button is now disabled={busy} (not busy || done) and reads "Reopen <provider> sign-in" once opened, so a user who closes the OAuth tab can reopen it instead of re-sending the message. (20 vitest still green.)
• resolve_send_backend → get_send_backend naming drift — fixed in the test docstrings + method name to match the real api_routes.get_send_backend symbol. (22 py still green.)

For the record on the no-action items:

• Unused connectorId prop — already tightened in the earlier review pass (narrowed so an unknown value can't render zero buttons); kept as tested back-compat.
• formatting.py:40 Google-only installed:email override heads-up — confirmed not reachable for Outlook (Outlook hits the generic AGENT_NOT_GRANTED naming microsoft) and predates this PR; flagging it for the epic's cleanup.

Also retargeted this PR to main now that #1774 (the #1768 mount) has merged.