feat(adk-agent): standalone Google-ADK agent that listens + responds in the console

[ivanmkc]

What

Adds integrations/adk-agent/ — a standalone Python (Google ADK) agent that listens to one termchart viewer console scope and responds by rendering/updating the diagram AND posting a short text reply in the console log. It's an alternative to driving termchart from a coding harness (Claude Code / agy) via the CLI.

This is purely additive — nothing under packages/* changes. The agent speaks the existing viewer HTTP API (GET/POST /inbox, push/patch/suggest/status/focus).

How it works

human types in console ─▶ GET /inbox (long-poll) ─▶ ADK turn (Gemini)
                                                       │ render_diagram / patch_diagram
                                                       │ suggest_chips / set_status  ─▶ canvas
                                                       ▼
     incoming text reply ◀─ POST /inbox (message) ── the agent's final answer

• Loop-back guard: the agent's replies land in the same inbox it polls, so it records each reply's seq and skips it on the next read (mirrors the browser console's seenSeqs) — it never answers itself.
• CLI-parity resilience: long-poll from the cursor, back off 1s→2s→…→15s on transient errors (never exit), exit on a 4xx, forward-progress guard, clean SIGINT.
• Real (non-peek) reads, so the human sees "Read by the agent ✓".
• Vertex AI via ADC by default; the GCP project is read from env only, never hardcoded. Gemini-API-key fallback supported.
• Scope discipline: acts only on its one configured project/agent.

Layout

config.py · models.py · client.py · prompts.py (compact, self-contained diagram cheat-sheet) · tools.py · agent.py · loop.py · main.py, plus pyproject.toml, README.md, .env.example, and a path-filtered CI workflow. Root README.md + AGENTS.md gained one-line pointers.

Verification

• uv run pytest → 43 passed (hermetic: httpx.MockTransport + a scripted runner; no network, no LLM, no time.sleep).
• uv run ruff check . clean · uv run mypy src clean.
• ADK wiring verified against real google-adk 1.34.3 (caught + fixed App.name identifier requirement).
• Real-viewer E2E: human message → read (acked=1) → flow rendered into the store → text reply posted into the console → PASS; no self-reply loop.
• Config gate: exit 4 (no viewer) / exit 3 (missing scope).

The live Gemini-inference leg is for the maintainer to run (uv run termchart-adk with ADC) — it's environment/credential-dependent and intentionally not exercised in CI.