feat(demo): Agent Theater — live, cinematic view of the real ReAct loop

[konjoinfinity]

Agent Theater

A fourth flagship demo surface (/agent) that streams kyro's real bounded ReAct loop live over SSE — the next step after the Pipeline Theater (PR #7).

plan (decompose) → retrieve (hybrid) → observe → … → finish

The reasoning loop is the production class konjoai.agent.react.RAGAgent, run unmodified — its Thought/Action/Observation control flow, JSON action parsing, action normalization, max-step guard, tool dispatch, and step/result events all execute as-is.

What's new

• demo/agent.py — AgentEngine drives the real RAGAgent. Two clearly-labelled offline seams:
  • Planner (no LLM): DemoPlanner implements the Generator protocol and emits valid ReAct JSON; its plan is real — sub-queries from router.decompose_query.
  • Retrieve tool (offline): RAGAgent resolves hybrid_search/rerank from module globals, which we swap to the demo PipelineEngine (real BM25 + dense + reciprocal_rank_fusion) for the duration of each run via a save/restore context manager — so the global patch never leaks into the rest of the suite (test_router etc. stay green; a containment test pins this).
• demo/agent.html — SSE-driven cinematic theater: live Thought/Action/Observation step cards, the decomposed plan + a step-budget meter, the real documents pulled on each retrieve step, and a typewriter answer with sources.
• demo/server.py — GET /agent, SSE GET /api/agent/stream, GET /api/agent/analyze (bounded/clamped inputs); a _send_sse streaming helper.
• demo/pipeline.py — public hybrid() (real RRF fusion) + describe_source().
• tests/unit/test_demo_agent.py — 9 contract tests (real loop → answer, step-budget bound, step/source shape, planner JSON parses with the real react parser, patch-containment / no test bleed).
• Cross-links all four surfaces: Playground · Observatory · Pipeline · Agent.

Honesty notes

• The planner is rule-based (no LLM) and says so in every result's model field; only token generation and the storage backend are stubbed — exactly the seams a production swap isolates.
• The retrieve tool runs real BM25 + dense + RRF over the demo corpus instead of a live Qdrant/cross-encoder stack (no cross-encoder offline → RRF-fused order is the ranking).

Verification

• pytest tests/unit/test_demo_agent.py tests/unit/test_demo_pipeline.py tests/unit/test_demo_metrics.py → 25 passed, stable across multiple PYTHONHASHSEED values.
• ruff check clean on all changed files; radon cc no function above grade C; agent.py 261 lines, pipeline.py 367.
• test_router.py still green after a run (confirms the retrieve-tool patch is fully restored).
• Rendered & screenshotted headless against the live SSE server.

Run it:

python3 demo/server.py        # http://localhost:8766/agent

https://claude.ai/code/session_01WWWgV1NwxaaNdPfy4PHN1K

---

Generated by Claude Code