feat(ui): proxy POST /v1/email/init (streamed provisioning) through the backend sidecar router

[itomek]

Problem

#1888 added a GET /v1/email/init proxy to the Agent UI backend's sidecar router so consumers on the recommended entry point can confirm their LEMONADE_BASE_URL wiring. The provisioning verb — POST /v1/email/init, which streams model-pull progress — is still not proxied: the integration guide has to tell consumers to call it "directly on the sidecar", which is inconsistent with the backend being the single recommended /v1/email surface.

Outcome

POST /v1/email/init works through the backend proxy with the sidecar's streamed progress passed through, and the integration guide's migration note drops the sidecar-direct caveat.

Acceptance criteria

• POST /v1/email/init on the backend forwards to the sidecar and streams the provisioning output through (chunked/SSE-style passthrough, not buffered-to-completion).
• Status codes and the terminal "re-run GET /v1/email/init" guidance pass through unchanged.
• docs/guides/email-integration.mdx migration note updated (remove "(the GAIA backend proxies only the readiness GET...)").
• Unit tests mirror the existing sidecar-router proxy tests, including a streaming passthrough assertion.

Scope & expectations

• Where: src/gaia/ui/email_sidecar/router.py, src/gaia/ui/email_sidecar/proxy.py, tests/unit/test_email_sidecar_router.py / test_email_sidecar_proxy.py, the one guide note.
• Out of scope: the sidecar's own /init implementation (feat(agent-email): add /v1/init readiness+provisioning endpoint (validate Lemonade + model) #1795/feat(agent-email): add GET /v1/email/init readiness preflight (#1795) #1813); connector OAuth write routes (deliberately never proxied).
• Constraints: preserve the proxy module's loud SidecarHTTPError boundary for non-contract statuses; the streaming passthrough must not buffer multi-minute model pulls in memory.

How to verify

HTTP API surface — curl -N -X POST http://127.0.0.1:4200/v1/email/init through the backend against a fresh Lemonade, showing streamed progress lines and the terminal guidance, plus the proxy unit-test output.

[github-actions]

Scoped correctly and worth doing — routing the streamed provisioning verb through the backend closes the last "call the sidecar directly" caveat in the integration guide. One heads-up before anyone starts: the prerequisite from #1888 (the readiness GET /v1/email/init proxy) doesn't appear to be on main yet, so this work is sequenced after it rather than a standalone add.

The streaming passthrough is also the one genuinely new mechanism here — every existing proxied route buffers the whole response to JSON, which is exactly what a multi-minute model pull must not do. So this needs a new streaming code path, not a copy of the current forward helper.

🔍 Technical details

Prerequisite not landed. On current main:

• src/gaia/ui/email_sidecar/router.py has no init route (routes stop at /health, /version).
• src/gaia/ui/email_sidecar/proxy.py has no init method — and every method funnels through _post/_get, both of which end in resp.json() (fully buffered).
• docs/guides/email-integration.mdx has no migration note containing "proxies only the readiness GET…" to delete (the /init endpoints aren't documented there at all yet — the endpoint list around email-integration.mdx:428 covers spec/version/health only).

So AC #3's find-and-remove target only exists once #1888 merges. Confirm ordering with the #1888 author.

Streaming path. _post's resp.json() buffers to completion — the exact thing AC #1 forbids. A faithful passthrough needs, on the proxy side, session.post(..., stream=True) + iterating resp.iter_content/iter_lines, and on the router side a Starlette StreamingResponse over that generator. Keep the SidecarHTTPError boundary (proxy.py:_raise_for_status) before the first chunk is yielded so a non-contract status still raises loudly instead of streaming a 4xx/5xx body as if it were progress — that preserves the _forward guarantee in router.py without buffering.

Test mirror. tests/unit/test_email_sidecar_proxy.py currently mocks a requests.Session returning .json(); the streaming test will need a mock whose iter_content/iter_lines yields multiple chunks, asserting they arrive incrementally (not concatenated post-hoc) and that a non-2xx before streaming still raises SidecarHTTPError.