feat: add SSE activity monitor, settings page, agent templates & run history

- Agent Activity page with real-time SSE event stream (tool calls, LLM
  thinking, run lifecycle), filterable by run_id via URL query param
- EventBus pub/sub + StreamingCallbackHandler wired into ReAct engine
- Settings page: drag-and-drop tab reorder, hide/show toggles, icon
  picker (57 FluentUI icons), persisted to localStorage
- Agent templates dropdown (KBA from tickets, worklog stats, next step
  advisor) pre-fills the create agent form
- AgentRunPage now shows filtered run history with detail dialog and
  link to Activity page filtered by run_id
- 19 new Playwright E2E tests (8 activity + 11 settings)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: abossard

CLAUDE.md

@@ -0,0 +1,129 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+### Setup
+```bash
+./setup.sh               # Bootstrap: creates .venv, installs deps, installs Playwright
+source .venv/bin/activate
+```
+
+### Run (Development)
+```bash
+./start-dev.sh           # Starts backend (port 5001) + frontend (port 3001) together
+
+# Or manually:
+# Terminal 1 - Backend:
+source .venv/bin/activate && cd backend && python app.py
+
+# Terminal 2 - Frontend:
+cd frontend && npm run dev
+```
+
+### Run (Production / Docker)
+```bash
+docker build -t quart-react-demo .
+docker run -p 5001:5001 quart-react-demo
+# Quart serves both API + built frontend on port 5001
+```
+
+### Tests
+```bash
+# E2E tests (Playwright - requires both servers running or auto-started)
+npm run test:e2e              # Run all E2E tests (chromium, firefox, webkit)
+npm run test:e2e:ui           # Interactive UI mode
+npm run test:e2e:report       # View last HTML report
+npx playwright test tests/e2e/workbench.spec.js --project=chromium  # Single file + browser
+
+# Backend unit tests (pytest)
+cd backend
+pytest                        # All backend tests
+pytest agent_builder/tests/   # 132 agent framework tests
+pytest test_agents.py -v      # Single file, verbose
+```
+
+### Frontend Build
+```bash
+cd frontend && npm install && npm run build   # Outputs to frontend/dist/
+```
+
+## Architecture
+
+### Overview
+Full-stack teaching app: **Quart** (async Python ASGI, port 5001) + **React/Vite** (port 3001 in dev). In development, Vite proxies `/api/*` to the Quart backend. In production, Quart serves the built frontend statically.
+
+### Backend (`backend/`)
+
+**Key pattern — Unified Operation System** (`api_decorators.py`):
+```python
+@operation("create_task", "Create a task", http_method="POST", mcp_enabled=True)
+def op_create_task(data: TaskCreate) -> Task:
+    return TaskService.create_task(data)
+```
+The `@operation` decorator auto-generates: REST endpoint, MCP JSON-RPC method, JSON schema, and LangChain `StructuredTool`. Define once, used everywhere. Operations are registered in `operations.py`.
+
+**Deep module pattern**: Business logic consolidated into service classes (`TaskService`, `WorkbenchService`, `CSVTicketService`, `KBAService`) rather than scattered thin functions.
+
+**Key files:**
+- `app.py` — Quart app, route/blueprint registration, SSE streams, LLM config
+- `api_decorators.py` — `@operation` decorator implementation
+- `operations.py` — All operation definitions
+- `tasks.py` — SQLModel task models + `TaskService` (SQLite via `data/tasks.db`)
+- `csv_data.py` — `CSVTicketService`: loads CSV (`CSV/data.csv`), date parsing (German format `DD.MM.YYYY HH:MM:SS`), filtering, pagination
+- `tickets.py` — Pydantic ticket models + enums (Status, Priority, Urgency, Impact)
+- `agent_builder/` — Full agent lifecycle: `service.py` (WorkbenchService), `engine/` (ReAct loop), `persistence/` (SQLite repos), `tools/` (ToolRegistry, MCP adapters), `routes.py` (Blueprint at `/api/workbench/*`)
+- `kba_service.py` — Knowledge Base Article generation pipeline
+
+**LLM config**: LiteLLM is default (works with GitHub Copilot, no key needed); OpenAI is optional override. Config via `.env`.
+
+**MCP**: Backend exposes both REST and MCP JSON-RPC from the same `@operation` handlers. `mcp_handler.py` routes JSON-RPC to operations.
+
+### Frontend (`frontend/src/`)
+
+**Feature-first structure**: `features/<name>/` contains page component, subcomponents, utils, and local state. All backend calls go through `services/api.js`.
+
+**Key features:**
+- `workbench/` — Agent Fabric: create/run/inspect ReAct agents with live schema editor
+- `csvtickets/` — Browse/filter/sort/paginate the CSV ticket dataset
+- `tickets/` — Nivo chart visualizations (bar, sankey, stream)
+- `usecase-demo/` — Pre-built demo agent runs with custom result renderers
+- `kba-drafter/` — KBA generation UI (draft list, editor, audit trail)
+- `dashboard/` — Real-time updates via Server-Sent Events (`/api/time-stream`)
+- `agent/` — One-shot agent chat interface
+
+**UI**: FluentUI v9 (`@fluentui/react-components`) throughout. Charts via `@nivo/*`.
+
+### Testing
+
+E2E tests (`tests/e2e/`) use Playwright. `playwright.config.js` auto-starts backend + frontend via `webServer`. Tests use `data-testid` attributes. Three browser projects: chromium, firefox, webkit.
+
+Backend tests use pytest. `agent_builder/tests/` has 132 tests covering the agent framework.
+
+## Environment
+
+Copy `.env.example` to `.env`. Key variables:
+```
+# LiteLLM (default — no key required if using GitHub Copilot)
+LITELLM_MODEL=github_copilot/gpt-4o
+
+# OpenAI (optional override)
+OPENAI_API_KEY=sk-proj-...
+OPENAI_MODEL=gpt-4o-mini
+
+# KBA publishing path
+KB_FILE_BASE_PATH=./kb_published
+```
+
+## Ports
+- Backend (Quart): `http://localhost:5001`
+- Frontend dev (Vite): `http://localhost:3001`
+- In production: single port `5001` (Quart serves everything)
+
+## Docs
+- `docs/QUICKSTART.md` — 5-minute setup
+- `docs/AGENT_BUILDER.md` — Agent framework architecture with diagrams
+- `docs/UNIFIED_ARCHITECTURE.md` — REST + MCP integration patterns
+- `docs/LEARNING.md` — Design principles (Grokking Simplicity, deep modules)
+- `docs/TROUBLESHOOTING.md` — Common issues

backend/agent_builder/engine/__init__.py

@@ -1,10 +1,11 @@
 """
 Agent Builder — Engine
 
-ReAct agent execution engine: runner, callbacks, prompt building.
+ReAct agent execution engine: runner, callbacks, prompt building, event bus.
 """
 
-from .callbacks import make_llm_logging_callback, make_tool_logging_callback
+from .callbacks import make_llm_logging_callback, make_streaming_callback, make_tool_logging_callback
+from .event_bus import AgentEvent, AgentEventBus, agent_event_bus
 from .prompt_builder import (
     DEFAULT_OUTPUT_SCHEMA,
     append_markdown_instruction,
@@ -15,8 +16,11 @@
 from .react_runner import RunResult, build_llm, build_react_agent, extract_tools_used, run_react_agent
 
 __all__ = [
+    "AgentEvent",
+    "AgentEventBus",
     "DEFAULT_OUTPUT_SCHEMA",
     "RunResult",
+    "agent_event_bus",
     "append_markdown_instruction",
     "append_output_instructions",
     "build_chat_system_prompt",
@@ -25,6 +29,7 @@
     "build_react_agent",
     "extract_tools_used",
     "make_llm_logging_callback",
+    "make_streaming_callback",
     "make_tool_logging_callback",
     "run_react_agent",
 ]

backend/agent_builder/engine/callbacks.py

@@ -2,14 +2,16 @@
 Agent Builder — LLM Callbacks
 
 Logging callbacks for OpenAI LLM calls and tool invocations.
-Actions (I/O): write to logger.
+Actions (I/O): write to logger and event bus.
 """
 
 import logging
 from time import perf_counter
 from typing import Any
 from uuid import UUID
 
+from .event_bus import AgentEvent, AgentEventBus
+
 logger = logging.getLogger(__name__)
 
 
@@ -148,3 +150,103 @@ def _extract_llm_call_metadata(
                     finish_reason = finish_reason or maybe_finish
 
     return token_usage, model_name, finish_reason
+
+
+# ---------------------------------------------------------------------------
+# SSE Streaming Callback — publishes events to EventBus
+# ---------------------------------------------------------------------------
+
+def make_streaming_callback(run_id: str, event_bus: AgentEventBus) -> Any:
+    """Create a callback handler that publishes agent events to the SSE event bus."""
+    from langchain_core.callbacks import BaseCallbackHandler
+
+    class StreamingCallbackHandler(BaseCallbackHandler):
+        def __init__(self) -> None:
+            super().__init__()
+            self._start_times: dict[Any, float] = {}
+
+        def on_tool_start(
+            self,
+            serialized: dict[str, Any],
+            input_str: str,
+            *,
+            run_id: Any = None,
+            **kwargs: Any,
+        ) -> None:
+            self._start_times[run_id] = perf_counter()
+            name = serialized.get("name", "unknown")
+            preview = input_str[:500] if isinstance(input_str, str) else str(input_str)[:500]
+            event_bus.publish(AgentEvent(
+                run_id=run_id_outer,
+                event_type="tool_start",
+                data={"tool_name": name, "input": preview},
+            ))
+
+        def on_tool_end(self, output: str, *, run_id: Any = None, **kwargs: Any) -> None:
+            started = self._start_times.pop(run_id, None)
+            duration_ms = int((perf_counter() - started) * 1000) if started is not None else None
+            preview = output[:500] if isinstance(output, str) else str(output)[:500]
+            event_bus.publish(AgentEvent(
+                run_id=run_id_outer,
+                event_type="tool_end",
+                data={"tool_name": kwargs.get("name", ""), "output": preview, "duration_ms": duration_ms},
+            ))
+
+        def on_tool_error(self, error: BaseException, *, run_id: Any = None, **kwargs: Any) -> None:
+            started = self._start_times.pop(run_id, None)
+            duration_ms = int((perf_counter() - started) * 1000) if started is not None else None
+            event_bus.publish(AgentEvent(
+                run_id=run_id_outer,
+                event_type="tool_error",
+                data={"error": str(error), "duration_ms": duration_ms},
+            ))
+
+        def on_llm_start(
+            self,
+            serialized: dict[str, Any],
+            prompts: list[str],
+            *,
+            run_id: UUID = None,
+            **kwargs: Any,
+        ) -> None:
+            self._start_times[run_id] = perf_counter()
+            model_name = None
+            if isinstance(serialized, dict):
+                model_name = (
+                    serialized.get("kwargs", {}).get("model")
+                    if isinstance(serialized.get("kwargs"), dict)
+                    else None
+                )
+            event_bus.publish(AgentEvent(
+                run_id=run_id_outer,
+                event_type="llm_start",
+                data={"model": model_name or ""},
+            ))
+
+        def on_llm_end(self, response: Any, *, run_id: UUID = None, **kwargs: Any) -> None:
+            started_at = self._start_times.pop(run_id, None)
+            duration_ms = int((perf_counter() - started_at) * 1000) if started_at is not None else None
+            token_usage, model_name, finish_reason = _extract_llm_call_metadata(response)
+            event_bus.publish(AgentEvent(
+                run_id=run_id_outer,
+                event_type="llm_end",
+                data={
+                    "model": model_name or "",
+                    "duration_ms": duration_ms,
+                    "token_usage": token_usage or {},
+                    "finish_reason": finish_reason or "",
+                },
+            ))
+
+        def on_llm_error(self, error: BaseException, *, run_id: UUID = None, **kwargs: Any) -> None:
+            started_at = self._start_times.pop(run_id, None)
+            duration_ms = int((perf_counter() - started_at) * 1000) if started_at is not None else None
+            event_bus.publish(AgentEvent(
+                run_id=run_id_outer,
+                event_type="llm_error",
+                data={"error": str(error), "duration_ms": duration_ms},
+            ))
+
+    # Closure captures run_id as run_id_outer to avoid shadowing with LangChain's run_id param
+    run_id_outer = run_id
+    return StreamingCallbackHandler()

backend/agent_builder/engine/event_bus.py

@@ -0,0 +1,77 @@
+"""
+Agent Builder — Event Bus
+
+Pub/sub for real-time agent activity events.
+Subscribers receive events via asyncio.Queue; a history buffer
+provides catch-up for new SSE connections.
+
+Data: AgentEvent dataclass
+Action: publish / subscribe / unsubscribe (I/O via queues)
+"""
+
+import asyncio
+import logging
+import time
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+MAX_HISTORY = 200
+
+
+@dataclass
+class AgentEvent:
+    """A single event from an agent run."""
+    run_id: str
+    event_type: str
+    data: dict[str, Any] = field(default_factory=dict)
+    timestamp: float = field(default_factory=time.time)
+
+    def to_sse_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+class AgentEventBus:
+    """Simple in-process pub/sub for agent execution events."""
+
+    def __init__(self, max_history: int = MAX_HISTORY) -> None:
+        self._subscribers: list[asyncio.Queue[AgentEvent]] = []
+        self._history: list[AgentEvent] = []
+        self._max_history = max_history
+
+    def subscribe(self) -> asyncio.Queue[AgentEvent]:
+        q: asyncio.Queue[AgentEvent] = asyncio.Queue(maxsize=500)
+        self._subscribers.append(q)
+        logger.debug("EventBus: subscriber added (total=%d)", len(self._subscribers))
+        return q
+
+    def unsubscribe(self, q: asyncio.Queue[AgentEvent]) -> None:
+        try:
+            self._subscribers.remove(q)
+            logger.debug("EventBus: subscriber removed (total=%d)", len(self._subscribers))
+        except ValueError:
+            pass
+
+    def publish(self, event: AgentEvent) -> None:
+        """Publish an event to all subscribers and history buffer.
+
+        Synchronous — safe to call from LangChain BaseCallbackHandler methods
+        because asyncio.Queue.put_nowait() doesn't require awaiting.
+        """
+        self._history.append(event)
+        if len(self._history) > self._max_history:
+            self._history = self._history[-self._max_history:]
+
+        for q in self._subscribers:
+            try:
+                q.put_nowait(event)
+            except asyncio.QueueFull:
+                logger.warning("EventBus: subscriber queue full, dropping event")
+
+    def get_history(self) -> list[AgentEvent]:
+        return list(self._history)
+
+
+# Global singleton
+agent_event_bus = AgentEventBus()