feat: complete phase 4 -- conversation replay API + analytics dashboard

- Replay models: StepType enum, ReplayStep, ReplayPage frozen dataclasses
- Checkpoint transformer: PostgresSaver JSONB -> structured timeline steps
- Replay API: GET /api/conversations (paginated), GET /api/replay/{thread_id}
- Analytics models: AgentUsage, InterruptStats, AnalyticsResult
- Analytics event recorder: Protocol + PostgresAnalyticsRecorder + NoOp
- Analytics queries: resolution_rate, agent_usage, escalation_rate, cost, interrupts
- Analytics API: GET /api/analytics?range=Xd with envelope response
- DB migration: analytics_events table + conversations column additions
- 74 new tests, 399 total passing, 92.87% coverage

backend/app/analytics/__init__.py

@@ -0,0 +1,3 @@
+"""Analytics module -- event recording and dashboard queries."""
+
+from __future__ import annotations

backend/app/analytics/api.py

@@ -0,0 +1,51 @@
+"""Analytics API router -- dashboard metrics endpoint."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import asdict
+from typing import TYPE_CHECKING, Any
+
+from fastapi import APIRouter, HTTPException, Query, Request
+
+from app.analytics.queries import get_analytics
+
+if TYPE_CHECKING:
+    from psycopg_pool import AsyncConnectionPool
+
+router = APIRouter(prefix="/api/analytics", tags=["analytics"])
+
+_RANGE_PATTERN = re.compile(r"^(\d+)d$")
+_DEFAULT_RANGE = "7d"
+
+
+async def _get_pool(request: Request) -> AsyncConnectionPool:
+    """Dependency: extract the shared pool from app state."""
+    return request.app.state.pool
+
+
+def _envelope(data: Any, *, success: bool = True, error: str | None = None) -> dict:
+    return {"success": success, "data": data, "error": error}
+
+
+def _parse_range(range_str: str) -> int:
+    """Parse 'Xd' range string to integer days. Raises 400 on invalid format."""
+    match = _RANGE_PATTERN.match(range_str)
+    if not match:
+        raise HTTPException(
+            status_code=400,
+            detail=f"Invalid range format '{range_str}'. Expected format: '<N>d' e.g. '7d', '30d'.",
+        )
+    return int(match.group(1))
+
+
+@router.get("")
+async def analytics(
+    request: Request,
+    range: str = Query(default=_DEFAULT_RANGE, alias="range"),  # noqa: A002
+) -> dict:
+    """Return aggregated analytics metrics for the given time range."""
+    range_days = _parse_range(range)
+    pool = await _get_pool(request)
+    result = await get_analytics(pool, range_days=range_days)
+    return _envelope(asdict(result))

backend/app/analytics/event_recorder.py

@@ -0,0 +1,95 @@
+"""Analytics event recorder -- Protocol and implementations."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from psycopg_pool import AsyncConnectionPool
+
+_INSERT_SQL = """
+INSERT INTO analytics_events
+    (thread_id, event_type, agent_name, tool_name, tokens_used, cost_usd,
+     duration_ms, success, error_message, metadata)
+VALUES
+    (%(thread_id)s, %(event_type)s, %(agent_name)s, %(tool_name)s,
+     %(tokens_used)s, %(cost_usd)s, %(duration_ms)s, %(success)s,
+     %(error_message)s, %(metadata)s)
+"""
+
+
+@runtime_checkable
+class AnalyticsRecorder(Protocol):
+    """Protocol for recording analytics events."""
+
+    async def record(
+        self,
+        *,
+        thread_id: str,
+        event_type: str,
+        agent_name: str | None = None,
+        tool_name: str | None = None,
+        tokens_used: int = 0,
+        cost_usd: float = 0.0,
+        duration_ms: int | None = None,
+        success: bool | None = None,
+        error_message: str | None = None,
+        metadata: dict | None = None,
+    ) -> None: ...
+
+
+class NoOpAnalyticsRecorder:
+    """No-op implementation for testing or when the DB is unavailable."""
+
+    async def record(
+        self,
+        *,
+        thread_id: str,
+        event_type: str,
+        agent_name: str | None = None,
+        tool_name: str | None = None,
+        tokens_used: int = 0,
+        cost_usd: float = 0.0,
+        duration_ms: int | None = None,
+        success: bool | None = None,
+        error_message: str | None = None,
+        metadata: dict | None = None,
+    ) -> None:
+        """Do nothing."""
+
+
+class PostgresAnalyticsRecorder:
+    """Postgres-backed analytics recorder -- INSERTs into analytics_events."""
+
+    def __init__(self, pool: AsyncConnectionPool) -> None:
+        self._pool = pool
+
+    async def record(
+        self,
+        *,
+        thread_id: str,
+        event_type: str,
+        agent_name: str | None = None,
+        tool_name: str | None = None,
+        tokens_used: int = 0,
+        cost_usd: float = 0.0,
+        duration_ms: int | None = None,
+        success: bool | None = None,
+        error_message: str | None = None,
+        metadata: dict | None = None,
+    ) -> None:
+        """Insert one analytics event row."""
+        params: dict[str, Any] = {
+            "thread_id": thread_id,
+            "event_type": event_type,
+            "agent_name": agent_name,
+            "tool_name": tool_name,
+            "tokens_used": tokens_used,
+            "cost_usd": cost_usd,
+            "duration_ms": duration_ms,
+            "success": success,
+            "error_message": error_message,
+            "metadata": metadata or {},
+        }
+        async with self._pool.connection() as conn:
+            await conn.execute(_INSERT_SQL, params)

backend/app/analytics/models.py

@@ -0,0 +1,38 @@
+"""Value objects for analytics dashboard."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class AgentUsage:
+    """Agent usage statistics within a time range."""
+
+    agent: str
+    count: int
+    percentage: float
+
+
+@dataclass(frozen=True)
+class InterruptStats:
+    """Interrupt approval/rejection statistics within a time range."""
+
+    total: int = 0
+    approved: int = 0
+    rejected: int = 0
+    expired: int = 0
+
+
+@dataclass(frozen=True)
+class AnalyticsResult:
+    """Full analytics result for a given time range."""
+
+    range: str
+    total_conversations: int
+    resolution_rate: float
+    escalation_rate: float
+    avg_turns_per_conversation: float
+    avg_cost_per_conversation_usd: float
+    agent_usage: tuple[AgentUsage, ...]
+    interrupt_stats: InterruptStats

backend/app/analytics/queries.py

@@ -0,0 +1,177 @@
+"""Analytics query functions -- all async, take pool + range_days."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from app.analytics.models import AgentUsage, AnalyticsResult, InterruptStats
+
+if TYPE_CHECKING:
+    from psycopg_pool import AsyncConnectionPool
+
+_RESOLUTION_RATE_SQL = """
+SELECT
+    CASE WHEN COUNT(*) = 0 THEN 0.0
+         ELSE COUNT(*) FILTER (WHERE resolution_type = 'resolved')::float / COUNT(*)
+    END AS rate
+FROM conversations
+WHERE created_at >= NOW() - INTERVAL '%(days)s days'
+"""
+
+_ESCALATION_RATE_SQL = """
+SELECT
+    CASE WHEN COUNT(*) = 0 THEN 0.0
+         ELSE COUNT(*) FILTER (WHERE resolution_type = 'escalated')::float / COUNT(*)
+    END AS rate
+FROM conversations
+WHERE created_at >= NOW() - INTERVAL '%(days)s days'
+"""
+
+_TOTAL_CONVERSATIONS_SQL = """
+SELECT COUNT(*) AS total
+FROM conversations
+WHERE created_at >= NOW() - INTERVAL '%(days)s days'
+"""
+
+_AVG_TURNS_SQL = """
+SELECT COALESCE(AVG(turn_count), 0.0) AS avg_turns
+FROM conversations
+WHERE created_at >= NOW() - INTERVAL '%(days)s days'
+"""
+
+_COST_PER_CONVERSATION_SQL = """
+SELECT COALESCE(AVG(total_cost_usd), 0.0) AS avg_cost
+FROM conversations
+WHERE created_at >= NOW() - INTERVAL '%(days)s days'
+"""
+
+_AGENT_USAGE_SQL = """
+SELECT
+    agent,
+    COUNT(*) AS count,
+    ROUND(COUNT(*) * 100.0 / NULLIF(SUM(COUNT(*)) OVER (), 0), 2) AS percentage
+FROM (
+    SELECT UNNEST(agents_used) AS agent
+    FROM conversations
+    WHERE created_at >= NOW() - INTERVAL '%(days)s days'
+      AND agents_used IS NOT NULL
+) sub
+GROUP BY agent
+ORDER BY count DESC
+"""
+
+_INTERRUPT_STATS_SQL = """
+SELECT
+    COUNT(*) FILTER (WHERE event_type = 'interrupt') AS total,
+    COUNT(*) FILTER (WHERE event_type = 'interrupt' AND success = TRUE) AS approved,
+    COUNT(*) FILTER (WHERE event_type = 'interrupt' AND success = FALSE
+                     AND error_message IS NULL) AS rejected,
+    COUNT(*) FILTER (WHERE event_type = 'interrupt' AND error_message = 'expired') AS expired
+FROM analytics_events
+WHERE created_at >= NOW() - INTERVAL '%(days)s days'
+"""
+
+
+async def resolution_rate(pool: AsyncConnectionPool, range_days: int) -> float:
+    """Return the fraction of resolved conversations in the given range."""
+    async with pool.connection() as conn:
+        cursor = await conn.execute(_RESOLUTION_RATE_SQL, {"days": range_days})
+        row = await cursor.fetchone()
+    if not row:
+        return 0.0
+    return float(row.get("rate") or 0.0)
+
+
+async def escalation_rate(pool: AsyncConnectionPool, range_days: int) -> float:
+    """Return the fraction of escalated conversations in the given range."""
+    async with pool.connection() as conn:
+        cursor = await conn.execute(_ESCALATION_RATE_SQL, {"days": range_days})
+        row = await cursor.fetchone()
+    if not row:
+        return 0.0
+    return float(row.get("rate") or 0.0)
+
+
+async def _total_conversations(pool: AsyncConnectionPool, range_days: int) -> int:
+    """Return the total number of conversations in the given range."""
+    async with pool.connection() as conn:
+        cursor = await conn.execute(_TOTAL_CONVERSATIONS_SQL, {"days": range_days})
+        row = await cursor.fetchone()
+    if not row:
+        return 0
+    return int(row.get("total") or 0)
+
+
+async def _avg_turns(pool: AsyncConnectionPool, range_days: int) -> float:
+    """Return the average turn count per conversation in the given range."""
+    async with pool.connection() as conn:
+        cursor = await conn.execute(_AVG_TURNS_SQL, {"days": range_days})
+        row = await cursor.fetchone()
+    if not row:
+        return 0.0
+    return float(row.get("avg_turns") or 0.0)
+
+
+async def cost_per_conversation(pool: AsyncConnectionPool, range_days: int) -> float:
+    """Return the average cost per conversation in the given range."""
+    async with pool.connection() as conn:
+        cursor = await conn.execute(_COST_PER_CONVERSATION_SQL, {"days": range_days})
+        row = await cursor.fetchone()
+    if not row:
+        return 0.0
+    return float(row.get("avg_cost") or 0.0)
+
+
+async def agent_usage(pool: AsyncConnectionPool, range_days: int) -> tuple[AgentUsage, ...]:
+    """Return per-agent usage statistics for the given range."""
+    async with pool.connection() as conn:
+        cursor = await conn.execute(_AGENT_USAGE_SQL, {"days": range_days})
+        rows = await cursor.fetchall()
+    if not rows:
+        return ()
+    return tuple(
+        AgentUsage(
+            agent=row["agent"],
+            count=int(row["count"]),
+            percentage=float(row["percentage"]),
+        )
+        for row in rows
+    )
+
+
+async def interrupt_stats(pool: AsyncConnectionPool, range_days: int) -> InterruptStats:
+    """Return interrupt approval/rejection statistics for the given range."""
+    async with pool.connection() as conn:
+        cursor = await conn.execute(_INTERRUPT_STATS_SQL, {"days": range_days})
+        row = await cursor.fetchone()
+    if not row:
+        return InterruptStats()
+    return InterruptStats(
+        total=int(row.get("total") or 0),
+        approved=int(row.get("approved") or 0),
+        rejected=int(row.get("rejected") or 0),
+        expired=int(row.get("expired") or 0),
+    )
+
+
+async def get_analytics(pool: AsyncConnectionPool, range_days: int) -> AnalyticsResult:
+    """Aggregate all analytics metrics into a single AnalyticsResult."""
+    res_rate, esc_rate, cost, usage, i_stats, total, avg_t = (
+        await resolution_rate(pool, range_days),
+        await escalation_rate(pool, range_days),
+        await cost_per_conversation(pool, range_days),
+        await agent_usage(pool, range_days),
+        await interrupt_stats(pool, range_days),
+        await _total_conversations(pool, range_days),
+        await _avg_turns(pool, range_days),
+    )
+    return AnalyticsResult(
+        range=f"{range_days}d",
+        total_conversations=total,
+        resolution_rate=res_rate,
+        escalation_rate=esc_rate,
+        avg_turns_per_conversation=avg_t,
+        avg_cost_per_conversation_usd=cost,
+        agent_usage=usage,
+        interrupt_stats=i_stats,
+    )

backend/app/db.py

@@ -34,6 +34,31 @@ CREATE TABLE IF NOT EXISTS active_interrupts (
 );
 """
 
+_ANALYTICS_EVENTS_DDL = """
+CREATE TABLE IF NOT EXISTS analytics_events (
+    id BIGSERIAL PRIMARY KEY,
+    thread_id TEXT NOT NULL,
+    event_type TEXT NOT NULL,
+    agent_name TEXT,
+    tool_name TEXT,
+    tokens_used INTEGER NOT NULL DEFAULT 0,
+    cost_usd DOUBLE PRECISION NOT NULL DEFAULT 0.0,
+    duration_ms INTEGER,
+    success BOOLEAN,
+    error_message TEXT,
+    metadata JSONB NOT NULL DEFAULT '{}',
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+"""
+
+_CONVERSATIONS_MIGRATION_DDL = """
+ALTER TABLE conversations
+    ADD COLUMN IF NOT EXISTS resolution_type TEXT,
+    ADD COLUMN IF NOT EXISTS agents_used TEXT[],
+    ADD COLUMN IF NOT EXISTS turn_count INTEGER NOT NULL DEFAULT 0,
+    ADD COLUMN IF NOT EXISTS ended_at TIMESTAMPTZ;
+"""
+
 
 async def create_pool(settings: Settings) -> AsyncConnectionPool:
     """Create an async connection pool with the required psycopg settings."""
@@ -55,7 +80,9 @@ async def create_checkpointer(pool: AsyncConnectionPool) -> AsyncPostgresSaver:
 
 
 async def setup_app_tables(pool: AsyncConnectionPool) -> None:
-    """Create application-specific tables (conversations, active_interrupts)."""
+    """Create application-specific tables and apply migrations."""
     async with pool.connection() as conn:
         await conn.execute(_CONVERSATIONS_DDL)
         await conn.execute(_INTERRUPTS_DDL)
+        await conn.execute(_ANALYTICS_EVENTS_DDL)
+        await conn.execute(_CONVERSATIONS_MIGRATION_DDL)

backend/app/main.py

@@ -10,6 +10,8 @@ from typing import TYPE_CHECKING
 from fastapi import FastAPI, WebSocket, WebSocketDisconnect
 from fastapi.staticfiles import StaticFiles
 
+from app.analytics.api import router as analytics_router
+from app.analytics.event_recorder import NoOpAnalyticsRecorder
 from app.callbacks import TokenUsageCallbackHandler
 from app.config import Settings
 from app.db import create_checkpointer, create_pool, setup_app_tables
@@ -18,9 +20,10 @@ from app.graph import build_graph
 from app.intent import LLMIntentClassifier
 from app.interrupt_manager import InterruptManager
 from app.llm import create_llm
-from app.registry import AgentRegistry
-from app.session_manager import SessionManager
 from app.openapi.review_api import router as openapi_router
+from app.registry import AgentRegistry
+from app.replay.api import router as replay_router
+from app.session_manager import SessionManager
 from app.ws_handler import dispatch_message
 
 if TYPE_CHECKING:
@@ -73,6 +76,7 @@ async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
     app.state.escalator = escalator
     app.state.settings = settings
     app.state.pool = pool
+    app.state.analytics_recorder = NoOpAnalyticsRecorder()
 
     logger.info(
         "Smart Support started: %d agents loaded, LLM=%s/%s, template=%s",
@@ -87,9 +91,11 @@ async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
     await pool.close()
 
 
-app = FastAPI(title="Smart Support", version="0.3.0", lifespan=lifespan)
+app = FastAPI(title="Smart Support", version="0.4.0", lifespan=lifespan)
 
 app.include_router(openapi_router)
+app.include_router(replay_router)
+app.include_router(analytics_router)
 
 
 @app.websocket("/ws")

backend/app/replay/__init__.py

@@ -0,0 +1,3 @@
+"""Replay module -- conversation replay API and transformer."""
+
+from __future__ import annotations

backend/app/replay/api.py

@@ -0,0 +1,103 @@
+"""Replay API router -- conversation listing and step-by-step replay."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Annotated, Any
+
+from fastapi import APIRouter, HTTPException, Query, Request
+
+if TYPE_CHECKING:
+    from psycopg_pool import AsyncConnectionPool
+
+router = APIRouter(prefix="/api", tags=["replay"])
+
+_LIST_CONVERSATIONS_SQL = """
+SELECT thread_id, created_at, last_activity, status, total_tokens, total_cost_usd
+FROM conversations
+ORDER BY last_activity DESC
+LIMIT %(limit)s OFFSET %(offset)s
+"""
+
+_GET_CHECKPOINTS_SQL = """
+SELECT thread_id, checkpoint_id, checkpoint, metadata
+FROM checkpoints
+WHERE thread_id = %(thread_id)s
+ORDER BY checkpoint_id ASC
+"""
+
+
+async def get_pool(request: Request) -> AsyncConnectionPool:
+    """Dependency: extract the shared pool from app state."""
+    return request.app.state.pool
+
+
+def _envelope(data: Any, *, success: bool = True, error: str | None = None) -> dict:
+    return {"success": success, "data": data, "error": error}
+
+
+@router.get("/conversations")
+async def list_conversations(
+    request: Request,
+    page: Annotated[int, Query(ge=1)] = 1,
+    per_page: Annotated[int, Query(ge=1, le=100)] = 20,
+) -> dict:
+    """List conversations with pagination."""
+    pool = await get_pool(request)
+    offset = (page - 1) * per_page
+    async with pool.connection() as conn:
+        cursor = await conn.execute(
+            _LIST_CONVERSATIONS_SQL,
+            {"limit": per_page, "offset": offset},
+        )
+        rows = await cursor.fetchall()
+
+    return _envelope([dict(row) for row in rows])
+
+
+@router.get("/replay/{thread_id}")
+async def get_replay(
+    thread_id: str,
+    request: Request,
+    page: Annotated[int, Query(ge=1)] = 1,
+    per_page: Annotated[int, Query(ge=1, le=100)] = 20,
+) -> dict:
+    """Return paginated replay steps for a conversation thread."""
+    from app.replay.transformer import transform_checkpoints
+
+    pool = await get_pool(request)
+    async with pool.connection() as conn:
+        cursor = await conn.execute(_GET_CHECKPOINTS_SQL, {"thread_id": thread_id})
+        rows = await cursor.fetchall()
+
+    if not rows:
+        raise HTTPException(status_code=404, detail=f"Thread '{thread_id}' not found")
+
+    all_steps = transform_checkpoints([dict(row) for row in rows])
+    total_steps = len(all_steps)
+    start = (page - 1) * per_page
+    end = start + per_page
+    page_steps = all_steps[start:end]
+
+    data = {
+        "thread_id": thread_id,
+        "total_steps": total_steps,
+        "page": page,
+        "per_page": per_page,
+        "steps": [
+            {
+                "step": s.step,
+                "type": s.type.value,
+                "timestamp": s.timestamp,
+                "content": s.content,
+                "agent": s.agent,
+                "tool": s.tool,
+                "params": s.params,
+                "result": s.result,
+                "reasoning": s.reasoning,
+                "tokens": s.tokens,
+                "duration_ms": s.duration_ms,
+            }
+            for s in page_steps
+        ],
+    }
+    return _envelope(data)

backend/app/replay/models.py

@@ -0,0 +1,52 @@
+"""Value objects for conversation replay."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class StepType(str, Enum):
+    """Types of steps in a conversation replay."""
+
+    user_message = "user_message"
+    supervisor_routing = "supervisor_routing"
+    tool_call = "tool_call"
+    tool_result = "tool_result"
+    agent_response = "agent_response"
+    interrupt = "interrupt"
+
+
+@dataclass(frozen=True)
+class ReplayStep:
+    """A single step in a conversation replay."""
+
+    step: int
+    type: StepType
+    timestamp: str
+    content: str = ""
+    agent: str | None = None
+    tool: str | None = None
+    params: dict | None = None
+    result: dict | None = None
+    reasoning: str | None = None
+    tokens: int | None = None
+    duration_ms: int | None = None
+
+    def __post_init__(self) -> None:
+        # Store params as a frozen copy to prevent mutation from the outside
+        if self.params is not None:
+            object.__setattr__(self, "params", dict(self.params))
+        if self.result is not None:
+            object.__setattr__(self, "result", dict(self.result))
+
+
+@dataclass(frozen=True)
+class ReplayPage:
+    """A paginated page of replay steps for a conversation thread."""
+
+    thread_id: str
+    total_steps: int
+    page: int
+    per_page: int
+    steps: tuple[ReplayStep, ...]

backend/app/replay/transformer.py

@@ -0,0 +1,116 @@
+"""Transforms PostgresSaver checkpoint rows into ReplayStep list."""
+
+from __future__ import annotations
+
+import logging
+
+from app.replay.models import ReplayStep, StepType
+
+logger = logging.getLogger(__name__)
+
+_EMPTY_TIMESTAMP = "1970-01-01T00:00:00Z"
+
+
+def _extract_messages(row: dict) -> list[dict]:
+    """Safely extract messages list from a checkpoint row."""
+    checkpoint = row.get("checkpoint")
+    if not checkpoint or not isinstance(checkpoint, dict):
+        return []
+    channel_values = checkpoint.get("channel_values")
+    if not channel_values or not isinstance(channel_values, dict):
+        return []
+    messages = channel_values.get("messages")
+    if not messages or not isinstance(messages, list):
+        return []
+    return messages
+
+
+def _step_from_message(msg: dict, step_number: int) -> ReplayStep | None:
+    """Convert a single message dict to a ReplayStep. Returns None for unknown types."""
+    msg_type = msg.get("type", "")
+    timestamp = msg.get("created_at") or _EMPTY_TIMESTAMP
+    content = msg.get("content") or ""
+    if isinstance(content, list):
+        # LangChain may encode content as a list of parts
+        content = " ".join(
+            part.get("text", "") if isinstance(part, dict) else str(part)
+            for part in content
+        )
+
+    if msg_type == "human":
+        return ReplayStep(
+            step=step_number,
+            type=StepType.user_message,
+            timestamp=timestamp,
+            content=content,
+        )
+
+    if msg_type == "ai":
+        tool_calls = msg.get("tool_calls") or []
+        if tool_calls:
+            first = tool_calls[0]
+            return ReplayStep(
+                step=step_number,
+                type=StepType.tool_call,
+                timestamp=timestamp,
+                content=content,
+                tool=first.get("name"),
+                params=dict(first.get("args") or {}),
+            )
+        return ReplayStep(
+            step=step_number,
+            type=StepType.agent_response,
+            timestamp=timestamp,
+            content=content,
+            agent=msg.get("name"),
+        )
+
+    if msg_type == "tool":
+        raw = content
+        result: dict | None = None
+        try:
+            import json
+
+            result = json.loads(raw)
+        except (ValueError, TypeError):
+            result = {"raw": raw}
+        return ReplayStep(
+            step=step_number,
+            type=StepType.tool_result,
+            timestamp=timestamp,
+            tool=msg.get("name"),
+            result=result,
+        )
+
+    logger.debug("Skipping unknown message type: %s", msg_type)
+    return None
+
+
+def transform_checkpoints(rows: list[dict]) -> list[ReplayStep]:
+    """Transform a list of checkpoint rows into an ordered list of ReplaySteps.
+
+    Steps are numbered sequentially starting from 1 across all rows.
+    Unknown or malformed messages are silently skipped.
+    """
+    steps: list[ReplayStep] = []
+    step_number = 1
+
+    for row in rows:
+        try:
+            messages = _extract_messages(row)
+        except Exception:  # noqa: BLE001
+            logger.exception("Error extracting messages from checkpoint row")
+            continue
+
+        for msg in messages:
+            try:
+                step = _step_from_message(msg, step_number)
+            except Exception:  # noqa: BLE001
+                logger.exception("Error converting message to ReplayStep")
+                step = None
+
+            if step is not None:
+                steps.append(step)
+                step_number += 1
+
+    return steps

backend/tests/unit/analytics/__init__.py

@@ -0,0 +1 @@
+"""Unit tests for app.analytics module."""

backend/tests/unit/analytics/test_api.py

@@ -0,0 +1,149 @@
+"""Unit tests for app.analytics.api."""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+pytestmark = pytest.mark.unit
+
+
+def _build_app() -> FastAPI:
+    from app.analytics.api import router
+
+    app = FastAPI()
+    app.include_router(router)
+    return app
+
+
+def _make_mock_pool() -> MagicMock:
+    mock_conn = AsyncMock()
+    mock_ctx = AsyncMock()
+    mock_ctx.__aenter__ = AsyncMock(return_value=mock_conn)
+    mock_ctx.__aexit__ = AsyncMock(return_value=None)
+    mock_pool = MagicMock()
+    mock_pool.connection.return_value = mock_ctx
+    return mock_pool
+
+
+def _make_analytics_result() -> object:
+    from app.analytics.models import AgentUsage, AnalyticsResult, InterruptStats
+
+    return AnalyticsResult(
+        range="7d",
+        total_conversations=50,
+        resolution_rate=0.8,
+        escalation_rate=0.1,
+        avg_turns_per_conversation=3.5,
+        avg_cost_per_conversation_usd=0.02,
+        agent_usage=(AgentUsage(agent="order_agent", count=30, percentage=60.0),),
+        interrupt_stats=InterruptStats(total=5, approved=4, rejected=1, expired=0),
+    )
+
+
+def _get_analytics(app: FastAPI, path: str = "/api/analytics", **patch_kwargs: object) -> object:
+    """Helper: patch get_analytics, make request, return (response, mock)."""
+    analytics_result = _make_analytics_result()
+    with (
+        patch("app.analytics.api.get_analytics", return_value=analytics_result) as mock_ga,
+        TestClient(app) as client,
+    ):
+        resp = client.get(path)
+    return resp, mock_ga
+
+
+class TestAnalyticsEndpoint:
+    def test_returns_200_with_default_range(self) -> None:
+        app = _build_app()
+        app.state.pool = _make_mock_pool()
+        resp, _ = _get_analytics(app)
+
+        assert resp.status_code == 200
+        body = resp.json()
+        assert body["success"] is True
+        assert body["error"] is None
+        assert body["data"]["range"] == "7d"
+
+    def test_returns_correct_analytics_structure(self) -> None:
+        app = _build_app()
+        app.state.pool = _make_mock_pool()
+        resp, _ = _get_analytics(app)
+
+        data = resp.json()["data"]
+        assert "total_conversations" in data
+        assert "resolution_rate" in data
+        assert "escalation_rate" in data
+        assert "avg_turns_per_conversation" in data
+        assert "avg_cost_per_conversation_usd" in data
+        assert "agent_usage" in data
+        assert "interrupt_stats" in data
+
+    def test_custom_range_7d(self) -> None:
+        app = _build_app()
+        app.state.pool = _make_mock_pool()
+        resp, mock_ga = _get_analytics(app, "/api/analytics?range=7d")
+
+        assert resp.status_code == 200
+        mock_ga.assert_called_once()
+        call_kwargs = mock_ga.call_args
+        assert call_kwargs[1]["range_days"] == 7 or call_kwargs[0][1] == 7
+
+    def test_custom_range_30d(self) -> None:
+        app = _build_app()
+        app.state.pool = _make_mock_pool()
+        resp, mock_ga = _get_analytics(app, "/api/analytics?range=30d")
+
+        assert resp.status_code == 200
+        call_kwargs = mock_ga.call_args
+        assert call_kwargs[1].get("range_days") == 30 or (
+            len(call_kwargs[0]) > 1 and call_kwargs[0][1] == 30
+        )
+
+    def test_invalid_range_format_returns_400(self) -> None:
+        app = _build_app()
+        app.state.pool = _make_mock_pool()
+
+        with TestClient(app) as client:
+            resp = client.get("/api/analytics?range=invalid")
+
+        assert resp.status_code == 400
+
+    def test_range_without_d_suffix_returns_400(self) -> None:
+        app = _build_app()
+        app.state.pool = _make_mock_pool()
+
+        with TestClient(app) as client:
+            resp = client.get("/api/analytics?range=7")
+
+        assert resp.status_code == 400
+
+    def test_agent_usage_in_response(self) -> None:
+        app = _build_app()
+        app.state.pool = _make_mock_pool()
+        resp, _ = _get_analytics(app)
+
+        data = resp.json()["data"]
+        assert len(data["agent_usage"]) == 1
+        assert data["agent_usage"][0]["agent"] == "order_agent"
+
+    def test_interrupt_stats_in_response(self) -> None:
+        app = _build_app()
+        app.state.pool = _make_mock_pool()
+        resp, _ = _get_analytics(app)
+
+        data = resp.json()["data"]
+        assert data["interrupt_stats"]["total"] == 5
+        assert data["interrupt_stats"]["approved"] == 4
+
+    def test_envelope_format(self) -> None:
+        app = _build_app()
+        app.state.pool = _make_mock_pool()
+        resp, _ = _get_analytics(app)
+
+        body = resp.json()
+        assert "success" in body
+        assert "data" in body
+        assert "error" in body

backend/tests/unit/analytics/test_event_recorder.py

@@ -0,0 +1,148 @@
+"""Unit tests for app.analytics.event_recorder."""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+pytestmark = pytest.mark.unit
+
+
+class TestAnalyticsRecorderProtocol:
+    def test_postgres_recorder_implements_protocol(self) -> None:
+        from app.analytics.event_recorder import PostgresAnalyticsRecorder
+
+        mock_pool = MagicMock()
+        recorder = PostgresAnalyticsRecorder(pool=mock_pool)
+        # Runtime check: has record method
+        assert hasattr(recorder, "record")
+        assert callable(recorder.record)
+
+    def test_noop_recorder_implements_protocol(self) -> None:
+        from app.analytics.event_recorder import NoOpAnalyticsRecorder
+
+        recorder = NoOpAnalyticsRecorder()
+        assert hasattr(recorder, "record")
+        assert callable(recorder.record)
+
+
+class TestNoOpAnalyticsRecorder:
+    @pytest.mark.asyncio
+    async def test_record_does_nothing(self) -> None:
+        from app.analytics.event_recorder import NoOpAnalyticsRecorder
+
+        recorder = NoOpAnalyticsRecorder()
+        # Should not raise
+        await recorder.record(
+            thread_id="t1",
+            event_type="tool_call",
+            agent_name="order_agent",
+            tool_name="get_order",
+            tokens_used=50,
+            cost_usd=0.001,
+        )
+
+    @pytest.mark.asyncio
+    async def test_record_with_all_params(self) -> None:
+        from app.analytics.event_recorder import NoOpAnalyticsRecorder
+
+        recorder = NoOpAnalyticsRecorder()
+        await recorder.record(
+            thread_id="t1",
+            event_type="agent_response",
+            agent_name="fallback",
+            tool_name=None,
+            tokens_used=100,
+            cost_usd=0.002,
+            duration_ms=150,
+            success=True,
+            error_message=None,
+            metadata={"extra": "data"},
+        )
+
+    @pytest.mark.asyncio
+    async def test_record_minimal_params(self) -> None:
+        from app.analytics.event_recorder import NoOpAnalyticsRecorder
+
+        recorder = NoOpAnalyticsRecorder()
+        # Only required params
+        await recorder.record(thread_id="t1", event_type="conversation_start")
+
+
+class TestPostgresAnalyticsRecorder:
+    @pytest.mark.asyncio
+    async def test_record_executes_insert(self) -> None:
+        from app.analytics.event_recorder import PostgresAnalyticsRecorder
+
+        mock_conn = AsyncMock()
+        mock_ctx = AsyncMock()
+        mock_ctx.__aenter__ = AsyncMock(return_value=mock_conn)
+        mock_ctx.__aexit__ = AsyncMock(return_value=None)
+        mock_pool = MagicMock()
+        mock_pool.connection.return_value = mock_ctx
+
+        recorder = PostgresAnalyticsRecorder(pool=mock_pool)
+        await recorder.record(
+            thread_id="t1",
+            event_type="tool_call",
+            agent_name="order_agent",
+            tokens_used=50,
+            cost_usd=0.001,
+        )
+        mock_conn.execute.assert_awaited_once()
+        call_args = mock_conn.execute.call_args
+        sql = call_args[0][0]
+        assert "INSERT INTO analytics_events" in sql
+
+    @pytest.mark.asyncio
+    async def test_record_passes_correct_params(self) -> None:
+        from app.analytics.event_recorder import PostgresAnalyticsRecorder
+
+        mock_conn = AsyncMock()
+        mock_ctx = AsyncMock()
+        mock_ctx.__aenter__ = AsyncMock(return_value=mock_conn)
+        mock_ctx.__aexit__ = AsyncMock(return_value=None)
+        mock_pool = MagicMock()
+        mock_pool.connection.return_value = mock_ctx
+
+        recorder = PostgresAnalyticsRecorder(pool=mock_pool)
+        await recorder.record(
+            thread_id="thread-xyz",
+            event_type="agent_response",
+            agent_name="discount_agent",
+            tool_name="apply_discount",
+            tokens_used=75,
+            cost_usd=0.002,
+            duration_ms=300,
+            success=True,
+            error_message=None,
+            metadata={"promo": "10PCT"},
+        )
+        call_args = mock_conn.execute.call_args
+        params = call_args[0][1]
+        assert params["thread_id"] == "thread-xyz"
+        assert params["event_type"] == "agent_response"
+        assert params["agent_name"] == "discount_agent"
+        assert params["tokens_used"] == 75
+
+    @pytest.mark.asyncio
+    async def test_record_stores_metadata_as_dict(self) -> None:
+        from app.analytics.event_recorder import PostgresAnalyticsRecorder
+
+        mock_conn = AsyncMock()
+        mock_ctx = AsyncMock()
+        mock_ctx.__aenter__ = AsyncMock(return_value=mock_conn)
+        mock_ctx.__aexit__ = AsyncMock(return_value=None)
+        mock_pool = MagicMock()
+        mock_pool.connection.return_value = mock_ctx
+
+        recorder = PostgresAnalyticsRecorder(pool=mock_pool)
+        await recorder.record(
+            thread_id="t1",
+            event_type="tool_call",
+            metadata={"key": "val"},
+        )
+        call_args = mock_conn.execute.call_args
+        params = call_args[0][1]
+        assert params["metadata"] == {"key": "val"}

backend/tests/unit/analytics/test_models.py

@@ -0,0 +1,106 @@
+"""Unit tests for app.analytics.models."""
+
+from __future__ import annotations
+
+import pytest
+
+pytestmark = pytest.mark.unit
+
+
+class TestAgentUsage:
+    def test_agent_usage_construction(self) -> None:
+        from app.analytics.models import AgentUsage
+
+        au = AgentUsage(agent="order_agent", count=10, percentage=50.0)
+        assert au.agent == "order_agent"
+        assert au.count == 10
+        assert au.percentage == 50.0
+
+    def test_agent_usage_is_frozen(self) -> None:
+        from app.analytics.models import AgentUsage
+
+        au = AgentUsage(agent="a", count=1, percentage=100.0)
+        with pytest.raises((AttributeError, TypeError)):
+            au.count = 2  # type: ignore[misc]
+
+
+class TestInterruptStats:
+    def test_interrupt_stats_defaults(self) -> None:
+        from app.analytics.models import InterruptStats
+
+        stats = InterruptStats()
+        assert stats.total == 0
+        assert stats.approved == 0
+        assert stats.rejected == 0
+        assert stats.expired == 0
+
+    def test_interrupt_stats_custom_values(self) -> None:
+        from app.analytics.models import InterruptStats
+
+        stats = InterruptStats(total=10, approved=7, rejected=2, expired=1)
+        assert stats.total == 10
+        assert stats.approved == 7
+        assert stats.rejected == 2
+        assert stats.expired == 1
+
+    def test_interrupt_stats_is_frozen(self) -> None:
+        from app.analytics.models import InterruptStats
+
+        stats = InterruptStats()
+        with pytest.raises((AttributeError, TypeError)):
+            stats.total = 5  # type: ignore[misc]
+
+
+class TestAnalyticsResult:
+    def test_analytics_result_construction(self) -> None:
+        from app.analytics.models import AgentUsage, AnalyticsResult, InterruptStats
+
+        result = AnalyticsResult(
+            range="7d",
+            total_conversations=100,
+            resolution_rate=0.85,
+            escalation_rate=0.05,
+            avg_turns_per_conversation=4.2,
+            avg_cost_per_conversation_usd=0.03,
+            agent_usage=(AgentUsage(agent="order_agent", count=60, percentage=60.0),),
+            interrupt_stats=InterruptStats(total=5, approved=4, rejected=1, expired=0),
+        )
+        assert result.range == "7d"
+        assert result.total_conversations == 100
+        assert result.resolution_rate == 0.85
+        assert result.escalation_rate == 0.05
+        assert result.avg_turns_per_conversation == 4.2
+        assert result.avg_cost_per_conversation_usd == 0.03
+        assert len(result.agent_usage) == 1
+        assert result.interrupt_stats.total == 5
+
+    def test_analytics_result_is_frozen(self) -> None:
+        from app.analytics.models import AnalyticsResult, InterruptStats
+
+        result = AnalyticsResult(
+            range="7d",
+            total_conversations=0,
+            resolution_rate=0.0,
+            escalation_rate=0.0,
+            avg_turns_per_conversation=0.0,
+            avg_cost_per_conversation_usd=0.0,
+            agent_usage=(),
+            interrupt_stats=InterruptStats(),
+        )
+        with pytest.raises((AttributeError, TypeError)):
+            result.range = "30d"  # type: ignore[misc]
+
+    def test_analytics_result_empty_agent_usage(self) -> None:
+        from app.analytics.models import AnalyticsResult, InterruptStats
+
+        result = AnalyticsResult(
+            range="7d",
+            total_conversations=0,
+            resolution_rate=0.0,
+            escalation_rate=0.0,
+            avg_turns_per_conversation=0.0,
+            avg_cost_per_conversation_usd=0.0,
+            agent_usage=(),
+            interrupt_stats=InterruptStats(),
+        )
+        assert result.agent_usage == ()

backend/tests/unit/analytics/test_queries.py

@@ -0,0 +1,213 @@
+"""Unit tests for app.analytics.queries."""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+pytestmark = pytest.mark.unit
+
+
+def _make_pool_with_fetchone(result: dict | None) -> MagicMock:
+    mock_cursor = AsyncMock()
+    mock_cursor.fetchone = AsyncMock(return_value=result)
+    mock_conn = AsyncMock()
+    mock_conn.execute = AsyncMock(return_value=mock_cursor)
+    mock_ctx = AsyncMock()
+    mock_ctx.__aenter__ = AsyncMock(return_value=mock_conn)
+    mock_ctx.__aexit__ = AsyncMock(return_value=None)
+    mock_pool = MagicMock()
+    mock_pool.connection.return_value = mock_ctx
+    return mock_pool
+
+
+def _make_pool_with_fetchall(result: list[dict]) -> MagicMock:
+    mock_cursor = AsyncMock()
+    mock_cursor.fetchall = AsyncMock(return_value=result)
+    mock_conn = AsyncMock()
+    mock_conn.execute = AsyncMock(return_value=mock_cursor)
+    mock_ctx = AsyncMock()
+    mock_ctx.__aenter__ = AsyncMock(return_value=mock_conn)
+    mock_ctx.__aexit__ = AsyncMock(return_value=None)
+    mock_pool = MagicMock()
+    mock_pool.connection.return_value = mock_ctx
+    return mock_pool
+
+
+class TestResolutionRate:
+    @pytest.mark.asyncio
+    async def test_returns_float(self) -> None:
+        from app.analytics.queries import resolution_rate
+
+        pool = _make_pool_with_fetchone({"rate": 0.85})
+        result = await resolution_rate(pool, range_days=7)
+        assert isinstance(result, float)
+
+    @pytest.mark.asyncio
+    async def test_zero_state_returns_zero(self) -> None:
+        from app.analytics.queries import resolution_rate
+
+        pool = _make_pool_with_fetchone(None)
+        result = await resolution_rate(pool, range_days=7)
+        assert result == 0.0
+
+    @pytest.mark.asyncio
+    async def test_returns_correct_value(self) -> None:
+        from app.analytics.queries import resolution_rate
+
+        pool = _make_pool_with_fetchone({"rate": 0.75})
+        result = await resolution_rate(pool, range_days=7)
+        assert result == 0.75
+
+
+class TestAgentUsageQuery:
+    @pytest.mark.asyncio
+    async def test_returns_tuple(self) -> None:
+        from app.analytics.queries import agent_usage
+
+        pool = _make_pool_with_fetchall([])
+        result = await agent_usage(pool, range_days=7)
+        assert isinstance(result, tuple)
+
+    @pytest.mark.asyncio
+    async def test_empty_state_returns_empty_tuple(self) -> None:
+        from app.analytics.queries import agent_usage
+
+        pool = _make_pool_with_fetchall([])
+        result = await agent_usage(pool, range_days=7)
+        assert result == ()
+
+    @pytest.mark.asyncio
+    async def test_maps_rows_to_agent_usage_objects(self) -> None:
+        from app.analytics.models import AgentUsage
+        from app.analytics.queries import agent_usage
+
+        pool = _make_pool_with_fetchall([
+            {"agent": "order_agent", "count": 10, "percentage": 66.7},
+            {"agent": "discount_agent", "count": 5, "percentage": 33.3},
+        ])
+        result = await agent_usage(pool, range_days=7)
+        assert len(result) == 2
+        assert isinstance(result[0], AgentUsage)
+        assert result[0].agent == "order_agent"
+        assert result[0].count == 10
+
+
+class TestEscalationRate:
+    @pytest.mark.asyncio
+    async def test_returns_float(self) -> None:
+        from app.analytics.queries import escalation_rate
+
+        pool = _make_pool_with_fetchone({"rate": 0.05})
+        result = await escalation_rate(pool, range_days=7)
+        assert isinstance(result, float)
+
+    @pytest.mark.asyncio
+    async def test_zero_state_returns_zero(self) -> None:
+        from app.analytics.queries import escalation_rate
+
+        pool = _make_pool_with_fetchone(None)
+        result = await escalation_rate(pool, range_days=7)
+        assert result == 0.0
+
+
+class TestCostPerConversation:
+    @pytest.mark.asyncio
+    async def test_returns_float(self) -> None:
+        from app.analytics.queries import cost_per_conversation
+
+        pool = _make_pool_with_fetchone({"avg_cost": 0.03})
+        result = await cost_per_conversation(pool, range_days=7)
+        assert isinstance(result, float)
+
+    @pytest.mark.asyncio
+    async def test_zero_state_returns_zero(self) -> None:
+        from app.analytics.queries import cost_per_conversation
+
+        pool = _make_pool_with_fetchone(None)
+        result = await cost_per_conversation(pool, range_days=7)
+        assert result == 0.0
+
+
+class TestInterruptStatsQuery:
+    @pytest.mark.asyncio
+    async def test_returns_interrupt_stats(self) -> None:
+        from app.analytics.models import InterruptStats
+        from app.analytics.queries import interrupt_stats
+
+        pool = _make_pool_with_fetchone(
+            {"total": 10, "approved": 7, "rejected": 2, "expired": 1}
+        )
+        result = await interrupt_stats(pool, range_days=7)
+        assert isinstance(result, InterruptStats)
+        assert result.total == 10
+        assert result.approved == 7
+
+    @pytest.mark.asyncio
+    async def test_zero_state_returns_zeros(self) -> None:
+        from app.analytics.models import InterruptStats
+        from app.analytics.queries import interrupt_stats
+
+        pool = _make_pool_with_fetchone(None)
+        result = await interrupt_stats(pool, range_days=7)
+        assert isinstance(result, InterruptStats)
+        assert result.total == 0
+        assert result.approved == 0
+        assert result.rejected == 0
+        assert result.expired == 0
+
+
+class TestGetAnalytics:
+    @pytest.mark.asyncio
+    async def test_returns_analytics_result(self) -> None:
+        from unittest.mock import patch
+
+        from app.analytics.models import AnalyticsResult, InterruptStats
+        from app.analytics.queries import get_analytics
+
+        mock_pool = MagicMock()
+
+        with (
+            patch("app.analytics.queries.resolution_rate", return_value=0.85),
+            patch("app.analytics.queries.escalation_rate", return_value=0.05),
+            patch("app.analytics.queries.cost_per_conversation", return_value=0.03),
+            patch("app.analytics.queries.agent_usage", return_value=()),
+            patch(
+                "app.analytics.queries.interrupt_stats",
+                return_value=InterruptStats(),
+            ),
+            patch("app.analytics.queries._total_conversations", return_value=100),
+            patch("app.analytics.queries._avg_turns", return_value=4.2),
+        ):
+            result = await get_analytics(mock_pool, range_days=7)
+
+        assert isinstance(result, AnalyticsResult)
+        assert result.range == "7d"
+        assert result.total_conversations == 100
+        assert result.resolution_rate == 0.85
+
+    @pytest.mark.asyncio
+    async def test_zero_state_returns_zeros(self) -> None:
+        from unittest.mock import patch
+
+        from app.analytics.models import AnalyticsResult, InterruptStats
+        from app.analytics.queries import get_analytics
+
+        mock_pool = MagicMock()
+
+        with (
+            patch("app.analytics.queries.resolution_rate", return_value=0.0),
+            patch("app.analytics.queries.escalation_rate", return_value=0.0),
+            patch("app.analytics.queries.cost_per_conversation", return_value=0.0),
+            patch("app.analytics.queries.agent_usage", return_value=()),
+            patch("app.analytics.queries.interrupt_stats", return_value=InterruptStats()),
+            patch("app.analytics.queries._total_conversations", return_value=0),
+            patch("app.analytics.queries._avg_turns", return_value=0.0),
+        ):
+            result = await get_analytics(mock_pool, range_days=7)
+
+        assert isinstance(result, AnalyticsResult)
+        assert result.total_conversations == 0
+        assert result.resolution_rate == 0.0
+        assert result.agent_usage == ()

backend/tests/unit/replay/__init__.py

@@ -0,0 +1 @@
+"""Unit tests for app.replay module."""

backend/tests/unit/replay/test_api.py

@@ -0,0 +1,160 @@
+"""Unit tests for app.replay.api."""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+pytestmark = pytest.mark.unit
+
+
+def _build_app() -> FastAPI:
+    from app.replay.api import router
+
+    app = FastAPI()
+    app.include_router(router)
+    return app
+
+
+def _make_mock_pool(fetchall_result: list[dict]) -> MagicMock:
+    """Build a mock pool that returns the given rows from fetchall."""
+    mock_cursor = AsyncMock()
+    mock_cursor.fetchall = AsyncMock(return_value=fetchall_result)
+
+    mock_conn = AsyncMock()
+    mock_conn.execute = AsyncMock(return_value=mock_cursor)
+
+    mock_ctx = AsyncMock()
+    mock_ctx.__aenter__ = AsyncMock(return_value=mock_conn)
+    mock_ctx.__aexit__ = AsyncMock(return_value=None)
+
+    mock_pool = MagicMock()
+    mock_pool.connection.return_value = mock_ctx
+    return mock_pool
+
+
+class TestListConversations:
+    def test_returns_200_with_empty_list(self) -> None:
+        app = _build_app()
+        app.state.pool = _make_mock_pool([])
+
+        with TestClient(app) as client:
+            resp = client.get("/api/conversations")
+        assert resp.status_code == 200
+        body = resp.json()
+        assert body["success"] is True
+        assert isinstance(body["data"], list)
+        assert body["error"] is None
+
+    def test_returns_conversations_list(self) -> None:
+        app = _build_app()
+        mock_rows = [
+            {
+                "thread_id": "t1",
+                "created_at": "2026-01-01T00:00:00",
+                "last_activity": "2026-01-01T00:01:00",
+                "status": "active",
+                "total_tokens": 100,
+                "total_cost_usd": 0.01,
+            }
+        ]
+        app.state.pool = _make_mock_pool(mock_rows)
+
+        with TestClient(app) as client:
+            resp = client.get("/api/conversations")
+        body = resp.json()
+        assert resp.status_code == 200
+        assert len(body["data"]) == 1
+        assert body["data"][0]["thread_id"] == "t1"
+
+    def test_pagination_defaults(self) -> None:
+        app = _build_app()
+        app.state.pool = _make_mock_pool([])
+
+        with TestClient(app) as client:
+            resp = client.get("/api/conversations")
+        assert resp.status_code == 200
+
+    def test_pagination_custom_params(self) -> None:
+        app = _build_app()
+        app.state.pool = _make_mock_pool([])
+
+        with TestClient(app) as client:
+            resp = client.get("/api/conversations?page=2&per_page=10")
+        assert resp.status_code == 200
+
+    def test_per_page_max_capped_at_100(self) -> None:
+        app = _build_app()
+        app.state.pool = _make_mock_pool([])
+
+        with TestClient(app) as client:
+            resp = client.get("/api/conversations?per_page=200")
+        # FastAPI validation rejects values > 100
+        assert resp.status_code in (200, 422)
+
+
+class TestGetReplay:
+    def test_thread_not_found_returns_404(self) -> None:
+        app = _build_app()
+        app.state.pool = _make_mock_pool([])
+
+        with TestClient(app) as client:
+            resp = client.get("/api/replay/nonexistent-thread")
+        assert resp.status_code == 404
+
+    def test_returns_replay_page_for_existing_thread(self) -> None:
+        app = _build_app()
+        mock_rows = [
+            {
+                "thread_id": "thread-123",
+                "checkpoint_id": "cp-001",
+                "checkpoint": {
+                    "channel_values": {
+                        "messages": [{"type": "human", "content": "Hello"}]
+                    }
+                },
+                "metadata": {},
+            }
+        ]
+        app.state.pool = _make_mock_pool(mock_rows)
+
+        with TestClient(app) as client:
+            resp = client.get("/api/replay/thread-123")
+        assert resp.status_code == 200
+        body = resp.json()
+        assert body["success"] is True
+        assert body["data"]["thread_id"] == "thread-123"
+        assert "steps" in body["data"]
+        assert "total_steps" in body["data"]
+        assert "page" in body["data"]
+        assert "per_page" in body["data"]
+
+    def test_replay_pagination_params(self) -> None:
+        app = _build_app()
+        mock_rows = [
+            {
+                "thread_id": "t1",
+                "checkpoint_id": "cp-001",
+                "checkpoint": {
+                    "channel_values": {"messages": [{"type": "human", "content": "Hi"}]}
+                },
+                "metadata": {},
+            }
+        ]
+        app.state.pool = _make_mock_pool(mock_rows)
+
+        with TestClient(app) as client:
+            resp = client.get("/api/replay/t1?page=1&per_page=5")
+        assert resp.status_code == 200
+
+    def test_error_response_has_envelope(self) -> None:
+        app = _build_app()
+        app.state.pool = _make_mock_pool([])
+
+        with TestClient(app) as client:
+            resp = client.get("/api/replay/missing")
+        body = resp.json()
+        assert "detail" in body or "error" in body or resp.status_code == 404

backend/tests/unit/replay/test_models.py

@@ -0,0 +1,134 @@
+"""Unit tests for app.replay.models."""
+
+from __future__ import annotations
+
+import pytest
+
+pytestmark = pytest.mark.unit
+
+
+class TestStepType:
+    def test_all_step_types_exist(self) -> None:
+        from app.replay.models import StepType
+
+        assert StepType.user_message
+        assert StepType.supervisor_routing
+        assert StepType.tool_call
+        assert StepType.tool_result
+        assert StepType.agent_response
+        assert StepType.interrupt
+
+    def test_step_type_values(self) -> None:
+        from app.replay.models import StepType
+
+        assert StepType.user_message.value == "user_message"
+        assert StepType.tool_call.value == "tool_call"
+        assert StepType.agent_response.value == "agent_response"
+
+
+class TestReplayStep:
+    def test_minimal_replay_step(self) -> None:
+        from app.replay.models import ReplayStep, StepType
+
+        step = ReplayStep(step=1, type=StepType.user_message, timestamp="2026-01-01T00:00:00Z")
+        assert step.step == 1
+        assert step.type == StepType.user_message
+        assert step.timestamp == "2026-01-01T00:00:00Z"
+        assert step.content == ""
+        assert step.agent is None
+        assert step.tool is None
+        assert step.params is None
+        assert step.result is None
+        assert step.reasoning is None
+        assert step.tokens is None
+        assert step.duration_ms is None
+
+    def test_full_replay_step(self) -> None:
+        from app.replay.models import ReplayStep, StepType
+
+        step = ReplayStep(
+            step=2,
+            type=StepType.tool_call,
+            timestamp="2026-01-01T00:00:01Z",
+            content="calling get_order",
+            agent="order_agent",
+            tool="get_order_status",
+            params={"order_id": "ORD-123"},
+            result={"status": "shipped"},
+            reasoning="user asked about order",
+            tokens=50,
+            duration_ms=200,
+        )
+        assert step.step == 2
+        assert step.agent == "order_agent"
+        assert step.tool == "get_order_status"
+        assert step.params == {"order_id": "ORD-123"}
+        assert step.tokens == 50
+
+    def test_replay_step_is_frozen(self) -> None:
+        from app.replay.models import ReplayStep, StepType
+
+        step = ReplayStep(step=1, type=StepType.user_message, timestamp="2026-01-01T00:00:00Z")
+        with pytest.raises((AttributeError, TypeError)):
+            step.step = 99  # type: ignore[misc]
+
+    def test_replay_step_params_is_immutable_copy(self) -> None:
+        from app.replay.models import ReplayStep, StepType
+
+        params = {"key": "value"}
+        step = ReplayStep(
+            step=1,
+            type=StepType.tool_call,
+            timestamp="2026-01-01T00:00:00Z",
+            params=params,
+        )
+        # Modifying original dict should not affect step
+        params["new_key"] = "new_value"
+        assert "new_key" not in (step.params or {})
+
+
+class TestReplayPage:
+    def test_replay_page_construction(self) -> None:
+        from app.replay.models import ReplayPage, ReplayStep, StepType
+
+        steps = (
+            ReplayStep(step=1, type=StepType.user_message, timestamp="2026-01-01T00:00:00Z"),
+            ReplayStep(step=2, type=StepType.agent_response, timestamp="2026-01-01T00:00:01Z"),
+        )
+        page = ReplayPage(
+            thread_id="thread-123",
+            total_steps=2,
+            page=1,
+            per_page=20,
+            steps=steps,
+        )
+        assert page.thread_id == "thread-123"
+        assert page.total_steps == 2
+        assert page.page == 1
+        assert page.per_page == 20
+        assert len(page.steps) == 2
+
+    def test_replay_page_is_frozen(self) -> None:
+        from app.replay.models import ReplayPage
+
+        page = ReplayPage(
+            thread_id="t1",
+            total_steps=0,
+            page=1,
+            per_page=20,
+            steps=(),
+        )
+        with pytest.raises((AttributeError, TypeError)):
+            page.page = 2  # type: ignore[misc]
+
+    def test_replay_page_empty_steps(self) -> None:
+        from app.replay.models import ReplayPage
+
+        page = ReplayPage(
+            thread_id="t1",
+            total_steps=0,
+            page=1,
+            per_page=20,
+            steps=(),
+        )
+        assert page.steps == ()

backend/tests/unit/replay/test_transformer.py

@@ -0,0 +1,155 @@
+"""Unit tests for app.replay.transformer."""
+
+from __future__ import annotations
+
+import pytest
+
+pytestmark = pytest.mark.unit
+
+
+def _make_row(messages: list[dict], metadata: dict | None = None) -> dict:
+    """Helper to build a checkpoint row with the given messages."""
+    return {
+        "thread_id": "thread-abc",
+        "checkpoint_id": "cp-001",
+        "checkpoint": {"channel_values": {"messages": messages}},
+        "metadata": metadata or {},
+    }
+
+
+class TestTransformCheckpoints:
+    def test_empty_rows_returns_empty_list(self) -> None:
+        from app.replay.transformer import transform_checkpoints
+
+        result = transform_checkpoints([])
+        assert result == []
+
+    def test_human_message_produces_user_message_step(self) -> None:
+        from app.replay.models import StepType
+        from app.replay.transformer import transform_checkpoints
+
+        rows = [_make_row([{"type": "human", "content": "Hello, I need help"}])]
+        steps = transform_checkpoints(rows)
+        assert len(steps) == 1
+        assert steps[0].type == StepType.user_message
+        assert steps[0].content == "Hello, I need help"
+        assert steps[0].step == 1
+
+    def test_ai_message_with_content_produces_agent_response(self) -> None:
+        from app.replay.models import StepType
+        from app.replay.transformer import transform_checkpoints
+
+        rows = [
+            _make_row(
+                [{"type": "ai", "content": "I can help you with that.", "tool_calls": []}],
+                metadata={"writes": {"some_agent": "response"}},
+            )
+        ]
+        steps = transform_checkpoints(rows)
+        assert len(steps) == 1
+        assert steps[0].type == StepType.agent_response
+        assert steps[0].content == "I can help you with that."
+
+    def test_ai_message_with_tool_calls_produces_tool_call_step(self) -> None:
+        from app.replay.models import StepType
+        from app.replay.transformer import transform_checkpoints
+
+        rows = [
+            _make_row(
+                [
+                    {
+                        "type": "ai",
+                        "content": "",
+                        "tool_calls": [
+                            {
+                                "name": "get_order_status",
+                                "args": {"order_id": "ORD-123"},
+                                "id": "call_abc",
+                            }
+                        ],
+                    }
+                ]
+            )
+        ]
+        steps = transform_checkpoints(rows)
+        assert len(steps) == 1
+        assert steps[0].type == StepType.tool_call
+        assert steps[0].tool == "get_order_status"
+        assert steps[0].params == {"order_id": "ORD-123"}
+
+    def test_tool_message_produces_tool_result_step(self) -> None:
+        from app.replay.models import StepType
+        from app.replay.transformer import transform_checkpoints
+
+        rows = [
+            _make_row(
+                [
+                    {
+                        "type": "tool",
+                        "content": '{"status": "shipped"}',
+                        "name": "get_order_status",
+                    }
+                ]
+            )
+        ]
+        steps = transform_checkpoints(rows)
+        assert len(steps) == 1
+        assert steps[0].type == StepType.tool_result
+        assert steps[0].tool == "get_order_status"
+
+    def test_multiple_messages_sequential_steps(self) -> None:
+        from app.replay.transformer import transform_checkpoints
+
+        rows = [
+            _make_row(
+                [
+                    {"type": "human", "content": "Help"},
+                    {"type": "ai", "content": "Sure!", "tool_calls": []},
+                ]
+            )
+        ]
+        steps = transform_checkpoints(rows)
+        assert len(steps) == 2
+        assert steps[0].step == 1
+        assert steps[1].step == 2
+
+    def test_unknown_message_type_skipped(self) -> None:
+        from app.replay.transformer import transform_checkpoints
+
+        rows = [_make_row([{"type": "unknown_type", "content": "test"}])]
+        steps = transform_checkpoints(rows)
+        # Should not crash; unknown types may be skipped
+        assert isinstance(steps, list)
+
+    def test_row_missing_checkpoint_skipped(self) -> None:
+        from app.replay.transformer import transform_checkpoints
+
+        rows = [{"thread_id": "t1", "checkpoint_id": "cp1", "checkpoint": None, "metadata": {}}]
+        steps = transform_checkpoints(rows)
+        assert isinstance(steps, list)
+
+    def test_row_missing_messages_key_skipped(self) -> None:
+        from app.replay.transformer import transform_checkpoints
+
+        rows = [{"thread_id": "t1", "checkpoint_id": "cp1", "checkpoint": {}, "metadata": {}}]
+        steps = transform_checkpoints(rows)
+        assert isinstance(steps, list)
+
+    def test_multiple_rows_steps_are_continuous(self) -> None:
+        from app.replay.transformer import transform_checkpoints
+
+        rows = [
+            _make_row([{"type": "human", "content": "Q1"}]),
+            _make_row([{"type": "ai", "content": "A1", "tool_calls": []}]),
+        ]
+        steps = transform_checkpoints(rows)
+        assert len(steps) == 2
+        assert steps[0].step == 1
+        assert steps[1].step == 2
+
+    def test_timestamps_are_strings(self) -> None:
+        from app.replay.transformer import transform_checkpoints
+
+        rows = [_make_row([{"type": "human", "content": "Hi"}])]
+        steps = transform_checkpoints(rows)
+        assert isinstance(steps[0].timestamp, str)

backend/tests/unit/test_db.py

@@ -55,7 +55,7 @@ class TestDbModule:
         from app.db import setup_app_tables
 
         await setup_app_tables(mock_pool)
-        assert mock_conn.execute.await_count == 2
+        assert mock_conn.execute.await_count == 4
 
     def test_ddl_statements_valid(self) -> None:
         assert "CREATE TABLE IF NOT EXISTS conversations" in _CONVERSATIONS_DDL

backend/tests/unit/test_db_phase4.py

@@ -0,0 +1,55 @@
+"""Phase 4 DB migration tests -- analytics_events table and conversation columns."""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+pytestmark = pytest.mark.unit
+
+
+class TestAnalyticsEventsDDL:
+    def test_analytics_events_ddl_exists(self) -> None:
+        from app.db import _ANALYTICS_EVENTS_DDL
+
+        assert "CREATE TABLE IF NOT EXISTS analytics_events" in _ANALYTICS_EVENTS_DDL
+
+    def test_analytics_events_ddl_has_required_columns(self) -> None:
+        from app.db import _ANALYTICS_EVENTS_DDL
+
+        assert "thread_id" in _ANALYTICS_EVENTS_DDL
+        assert "event_type" in _ANALYTICS_EVENTS_DDL
+        assert "agent_name" in _ANALYTICS_EVENTS_DDL
+        assert "tool_name" in _ANALYTICS_EVENTS_DDL
+        assert "tokens_used" in _ANALYTICS_EVENTS_DDL
+        assert "cost_usd" in _ANALYTICS_EVENTS_DDL
+        assert "duration_ms" in _ANALYTICS_EVENTS_DDL
+        assert "success" in _ANALYTICS_EVENTS_DDL
+        assert "error_message" in _ANALYTICS_EVENTS_DDL
+        assert "metadata" in _ANALYTICS_EVENTS_DDL
+
+    def test_conversations_migration_ddl_exists(self) -> None:
+        from app.db import _CONVERSATIONS_MIGRATION_DDL
+
+        assert "ALTER TABLE" in _CONVERSATIONS_MIGRATION_DDL
+        assert "resolution_type" in _CONVERSATIONS_MIGRATION_DDL
+        assert "agents_used" in _CONVERSATIONS_MIGRATION_DDL
+        assert "turn_count" in _CONVERSATIONS_MIGRATION_DDL
+        assert "ended_at" in _CONVERSATIONS_MIGRATION_DDL
+        assert "IF NOT EXISTS" in _CONVERSATIONS_MIGRATION_DDL
+
+    @pytest.mark.asyncio
+    async def test_setup_app_tables_executes_analytics_ddl(self) -> None:
+        mock_conn = AsyncMock()
+        mock_ctx = AsyncMock()
+        mock_ctx.__aenter__ = AsyncMock(return_value=mock_conn)
+        mock_ctx.__aexit__ = AsyncMock(return_value=None)
+        mock_pool = MagicMock()
+        mock_pool.connection.return_value = mock_ctx
+
+        from app.db import setup_app_tables
+
+        await setup_app_tables(mock_pool)
+        # Now expects 4 statements: conversations, interrupts, analytics_events, migrations
+        assert mock_conn.execute.await_count == 4

backend/tests/unit/test_main.py

@@ -13,7 +13,7 @@ class TestMainModule:
         assert app.title == "Smart Support"
 
     def test_app_version(self) -> None:
-        assert app.version == "0.3.0"
+        assert app.version == "0.4.0"
 
     def test_agents_yaml_path_exists(self) -> None:
         assert AGENTS_YAML.name == "agents.yaml"
@@ -25,3 +25,11 @@ class TestMainModule:
     def test_websocket_route_registered(self) -> None:
         routes = [r.path for r in app.routes if hasattr(r, "path")]
         assert "/ws" in routes
+
+    def test_replay_router_registered(self) -> None:
+        routes = [r.path for r in app.routes if hasattr(r, "path")]
+        assert any("replay" in p or "conversations" in p for p in routes)
+
+    def test_analytics_router_registered(self) -> None:
+        routes = [r.path for r in app.routes if hasattr(r, "path")]
+        assert any("analytics" in p for p in routes)