feat(agent-email): playground mailbox connectors + live send

[itomek]

Why this matters

Before: in the email-agent playground you could triage and draft, but Send was a dead "connector required" notice — no way to connect a mailbox or send for real. After: the playground gains a collapsible Connectors panel — paste your own Google/Microsoft OAuth client credentials, connect Gmail/Outlook through GAIA's own connector framework (the same flow the Agent UI and gaia connectors use), pick the mailbox in Send, and send live.

The connector routes are mounted unconditionally by the sidecar, next to the playground page it already always serves. They reuse gaia.connectors (already compiled into the sidecar binary via the send path — no new dependency) and are excluded from the OpenAPI contract (include_in_schema=False): a playground convenience, not part of the frozen email REST contract. This survives npm/R2 packaging — the thin npm package just fetches and spawns that same binary. The connection lives in GAIA's machine-global keyring store shared by every surface, so a real consuming app can establish it via the Agent UI / CLI and the sidecar's send just reads it. Builds on the merged playground (#1796 / #1814).

What's in it

• Connector routes (include_in_schema=False): GET /v1/email/connectors (status), POST …/{provider}/configure (start OAuth), POST …/{provider}/complete (wait, then grant the mailbox to installed:email so send resolves it), DELETE …/{provider} (full disconnect — clears tokens and per-agent grants, so a reconnect is clean).
• Connectors panel at the top of the playground: per-provider client_id/secret → connect; a Disconnect button on each connected account (the connect form returns afterward).
• Send gains an always-present From-mailbox dropdown: lists connected mailboxes alphabetically, selects the first, and passes the choice to draft (binding the send token) — so a 2-mailbox setup never hits the send API's 400 "can't choose". Empty + disabled when nothing is connected.
• Account emails are shown only when every connected mailbox has one (no mixed "Gmail · addr" / bare "Outlook"); the store's "default" no-email sentinel is never surfaced.

Send needs both a connection and a grant. connected_mailbox_providers() picks the provider by connection presence, but the actual send fetches a token via get_access_token_sync(agent_id="installed:email"), which is grant-gated (the #1592 orphan failure mode). …/complete grants to exactly that id.

Evidence

UI — captured from the live sidecar (Send itself was not fired — it dispatches a real email; account emails are suppressed in the connected shot because not every connected mailbox resolved one):

Not connected — paste your own Google/Microsoft OAuth client credentials; Send is disabled:

Connected — a Disconnect button on each account; Send picks the mailbox from a dropdown and is ready:

Always-on, out of the contract (no flag, no env):

$ python …/packaging/server.py --port 8135
$ curl -s -o /dev/null -w '%{http_code}' :8135/v1/email/connectors        # 200  (always mounted)
$ curl -s :8135/openapi.json | jq '.paths|keys|any(test("connectors"))'    # false (excluded from contract)
$ curl -s :8135/openapi.json | jq '.paths|has("/v1/email/triage")'         # true  (core contract intact)

Tests: the full email unit suite passes, incl. new connector-route, gating/contract-exclusion, disconnect, and default-sentinel coverage.

$ PYTHONPATH=hub/agents/python/email python -m pytest tests/unit/agents/email/ -q
417 passed

Test plan

• PYTHONPATH=hub/agents/python/email python -m pytest tests/unit/agents/email/test_connector_routes.py tests/unit/agents/email/test_playground.py -q
• python hub/agents/python/email/packaging/server.py --port 8131, open /v1/email/playground → connect Gmail/Outlook with your own OAuth client creds; pick the mailbox in Send → live send; Disconnect → the connect form returns.
• curl :8131/openapi.json → /v1/email/connectors is not in paths; /v1/email/triage is.

[github-actions]

Verdict: Approve with suggestions — no blocking issues.

This makes the email-agent playground's Send panel actually work: a new collapsible Connectors panel lets you connect Gmail/Outlook with your own OAuth client credentials through GAIA's existing connector framework, then pick that mailbox and send live. The routes are mounted unconditionally next to the always-served playground page and kept out of the frozen OpenAPI contract, which is the right call for a dev convenience.

The integration is correct end-to-end: connecting grants the mailbox to the email agent (so send can actually fetch a token), disconnect does a full teardown (tokens and grants, so a reconnect can't inherit stale consent), and the From-mailbox dropdown passes the chosen provider into draft so a 2-mailbox setup never trips the send API's "can't choose" error. Tests cover it well, including a real-app mount/OpenAPI-exclusion check. Only minor nits below.

One thing to keep in mind (not blocking): like the rest of the sidecar playground, these routes are unauthenticated and rely on the 127.0.0.1 bind + no-CORS for protection. That's consistent with the existing send/triage routes, but configure/disconnect now mutate connector state from that same surface — fine for a local dev tool, worth a second's thought if the sidecar bind ever widens.

🔍 Technical details

Issues

🟢 Unused module logger (connector_routes.py:58) — log = logging.getLogger("gaia_agent_email.connectors") is defined but never used anywhere in the module. Either drop it or wire it into the two except handlers (a one-line log.warning(...) before re-raising would aid debugging the live OAuth path). If kept, it's harmless dead code.

🟢 Duplicated "default" sentinel in JS (playground_html.py:361) — doSend's success line re-checks st.account_email !== "default", but the server already maps the DEFAULT_ACCOUNT sentinel to null before it reaches the page (connector_routes.py:110-112). The client-side string literal is redundant defensive coupling to the store's internal sentinel value. Minor — leaving it is safe; removing the magic string keeps the sentinel knowledge server-side only.

🟢 Empty-scope grant edge case (connector_routes.py:162-164) — scopes = list(state.get("scopes") or []) then grant_agent(provider, EMAIL_AGENT_ID, scopes). If complete_authorization ever returns a state without scopes, the agent is granted with an empty scope set and send's grant check could later fail with a less-obvious error. In practice the flow always returns scopes, so this is defensive-only — no action needed unless you want to assert non-empty here.

Verified correct

• Route delegation matches the framework contracts: configure → handler.configure → start_authorization returns {flow_id, authorization_url} (flow.py:236); complete → complete_authorization (flow.py:239) then grant_agent (grants.py:158); disconnect → handler.disconnect which calls revoke_all_grants_for (oauth_pkce.py:188), so the [Bug]: Agent UI — connected Google account can't be used by Email Triage agent (per-agent grant missing in UI, then token 401) #1592 stale-consent claim holds.
• Call-time imports (from gaia.connectors... import ... inside each handler) are what let the tests monkeypatch the framework cleanly — correct and intentional.
• Provider binding is real, not cosmetic: doSend passes provider into /v1/email/draft, and the draft/send API binds the confirmation token to that provider (api_routes.py:596-646, _resolve_backend_for_provider at :722). The dropdown choice genuinely drives the send backend.
• Boundary error translation (except Exception ... raise HTTPException(...) from e) is the allowed fail-loudly pattern (system boundary → HTTP), not a silent fallback.

Strengths

• XSS-safe by construction — the entire Connectors/Send UI is built with createElement/textContent, zero .innerHTML, and there's a test pinning that invariant (test_playground.py:68). Good discipline for injected mailbox/email strings.
• Test quality — TestSidecarMount loads the real packaging/server.py by path and asserts the routes are both mounted (200) and excluded from the OpenAPI contract, while the core /triage path stays in-schema. That's exactly the "verify the call shape, not just that we called it" bar from CLAUDE.md.
• Correct reuse — leans entirely on gaia.connectors rather than reimplementing OAuth, and the unconditional-mount + include_in_schema=False design keeps the frozen REST contract clean while still giving the always-served page a working panel.