Agent XP history: paginated endpoint returning all XP events for an agent

[leocagli]

Context

The XP store accumulates events but there's no way to query them. An XP history endpoint enables analytics, personal history views, and debugging XP calculation issues.

What to implement

Route: GET /api/agents/:id/xp/history

Returns paginated XP events:

{
  "agentId": "...",
  "totalXp": 1450,
  "events": [
    { "id": "...", "type": "quest_completed", "xp": 100, "questId": "...", "timestamp": "..." },
    { "id": "...", "type": "badge_unlocked", "xp": 50, "badgeId": "...", "timestamp": "..." }
  ],
  "page": 1,
  "pageSize": 20,
  "total": 47
}

Query params

• ?page=1&pageSize=20 — pagination (max pageSize: 100)
• ?type=quest_completed — filter by event type
• ?from=2026-01-01&to=2026-06-30 — date range filter

Event types

'quest_completed' | 'badge_unlocked' | 'district_unlocked' | 'manual_grant' | 'xp_decay'

Acceptance criteria

• GET /api/agents/:id/xp/history returns paginated events newest-first
• ?type= filter returns only matching events
• ?from=/to= date range filter works
• totalXp matches sum of all event XP values
• pageSize capped at 100 (returns 400 if exceeded)
• Unit tests: pagination boundaries, type filter, date filter, empty history

[Tomoya0k]

Can I work on this?