feat(hub): sidecar-served email-agent playground (localhost-only) (#1796)

[kovtcharov]

A developer evaluating the email agent has no zero-setup way to see it work — clone the repo, build the package, run a CLI. This adds a GAIA-styled page the sidecar serves itself at http://127.0.0.1:8131/v1/email/playground: visit it and you get a stack-health check (sidecar up + a plain-language Lemonade/model diagnosis — "Lemonade not found", "model not downloaded"), live triage and draft against the running sidecar, a button that exercises the /v1/init readiness endpoint, and copy-paste install shortcuts.

Localhost-only is structural, not a promise. The page is served same-origin (no CORS, no remote-controlled JS) and the route ships Content-Security-Policy: connect-src 'self', so the browser refuses any non-local fetch — email content can't leave the machine. Inference stays on local Lemonade.

The /init button consumes the readiness endpoint from #1795, implemented in PR #1813 (branch claudia/task-4a1065f9). This branch predates it, so /v1/email/init returns 404 here — the button fails loudly with a clear message ("update the sidecar — ships with #1795") rather than breaking, and lights up once #1795 merges. The endpoint is not duplicated here; the playground only consumes it.

Closes #1796.

Also in this PR

• Added a "Playground" section + screenshot to the email agent README (hub/agents/python/email/README.md), mirroring the npm package's architecture-diagram embed.
• Brought the sibling /v1/email/spec page on-brand. It used an off-brand orange/blue/green palette; restyled to the GAIA dark+gold tokens (matching the website + playground), self-contained (system fonts, no webfont), and added a "Convenience pages" section listing /spec and /playground.

Test plan

• PYTHONPATH=hub/agents/python/email python -m pytest tests/unit/agents/email/test_playground.py tests/unit/agents/email/test_spec_html.py tests/test_email_openapi_conformance.py -q — 56 pass (route 200, CSP pins egress to 'self', no external resources, /playground excluded from /openapi.json, spec page still self-contained).
• Start the sidecar (python hub/agents/python/email/packaging/server.py --host 127.0.0.1 --port 8131), open http://127.0.0.1:8131/v1/email/playground:
  • Stack health shows ✓ Sidecar; the Lemonade/model row diagnoses correctly (start/stop lemonade-server serve to see both states).
  • Triage + Draft run live (with Lemonade up); "Run readiness check · /v1/init" shows the graceful 404 message on this branch.
  • Response header includes Content-Security-Policy: connect-src 'self'.
• Open http://127.0.0.1:8131/v1/email/spec — renders in GAIA dark+gold, lists the playground under "Convenience pages".

[github-actions]

Summary

Clean, well-scoped feature that gives a developer a zero-setup way to see the email agent working: the sidecar serves its own GAIA-styled playground page with live health/triage/draft, and the "local-only" claim is enforced structurally via a Content-Security-Policy: connect-src 'self' header rather than merely promised. The code follows the established patterns in this package exactly (deferred renderer import like email_spec, importorskip test layout like test_spec_html.py), and the tests assert the boundary contract (CSP header present, no external resources, route excluded from OpenAPI) instead of just a 200 — exactly the "verify call validity, not just invocation" principle from CLAUDE.md. I ran the new suite locally: 6/6 pass. No blocking issues; only minor/optional notes below.

I also verified the response shapes the page's JS consumes against the real contract models — res.result.category / is_spam / is_phishing / summary / suggested_action, action_items[].description / .due_hint, and res.confirmation_token — and they all match EmailTriageResponse (result= wrapper) and EmailDraftResponse. No prompt-injection content in the diff.

Issues

🟢 Minor

CI may skip this test rather than run it (pre-existing pattern). tests/unit/agents/email/ all gate behind pytest.importorskip("gaia_agent_email"), but test_email_agent_unit.yml installs only -e ".[dev,api]" and there's no pythonpath/conftest insertion for hub/agents/python/email, so the import isn't satisfied in that job. Your test-plan command pins it explicitly (PYTHONPATH=hub/agents/python/email …), which is why it passes for you — but the PR gate would skip it (green-but-empty), as it does for the whole email suite today. This isn't introduced by this PR and shouldn't block it; worth confirming the suite actually executes in CI rather than silently skipping. (.github/workflows/test_email_agent_unit.yml:83)

Redundant innerHTML = "" on freshly-created elements. Two spots set innerHTML to empty on an element that was just createElement'd, immediately before assigning textContent — dead no-ops that read as if markup were involved. Safe to drop. (playground_html.py:310, playground_html.py:336)

    out.textContent = ""; const d = diagnose(e);
    const p = document.createElement("div");
    p.textContent = (e.status===502||e.status===0) ? ("✗ " + d.cause + " — " + d.hint + (d.cmd?(" ("+d.cmd+")"):"")) : ("✗ HTTP " + e.status + ": " + (e.body||e.message));

Optional: no doc pointer. The playground URL (/v1/email/playground) isn't mentioned in docs/guides/email.mdx. It's a self-discoverable dev page so this is low priority, but a one-line "open http://127.0.0.1:8131/v1/email/playground to try it" would aid discoverability.

Strengths

• Local-only is enforced, then tested as a contract. test_csp_pins_egress_to_self asserts the actual response header, and test_pulls_in_no_external_resources proves the page loads nothing off-box — the guarantee is structural, not aspirational.
• Graceful, loud degradation for the /v1/email/init 404 (this branch predates feat(agent-email): add /v1/init readiness+provisioning endpoint (validate Lemonade + model) #1795) — a clear "update the sidecar" message instead of a silent break, consistent with the no-silent-fallback rule. Correctly consumes feat(agent-email): add /v1/init readiness+provisioning endpoint (validate Lemonade + model) #1795's endpoint rather than duplicating it.
• XSS surface minimized: server-side HTML is fully static and every dynamic value is written via textContent, so script-src 'unsafe-inline' (needed for the self-contained inline JS/handlers) doesn't open a reflection path. Good call documenting the reasoning inline.

Verdict

Approve with suggestions — no blocking issues. The minor items (dead innerHTML lines, optional doc pointer, and confirming the CI gate runs rather than skips the suite) can be addressed in this PR or a follow-up.