fix: improve agent handoff and leaderboard scheduling

offline-backend-20260512/backend/app/gateway/routers/admin_users.py

@@ -72,6 +72,14 @@ _LEADERBOARD_CACHE_TTL_SECONDS = max(
     5.0,
     float(os.getenv("ADMIN_LEADERBOARD_CACHE_TTL_SECONDS", "300")),
 )
+_LEADERBOARD_QUERY_PAUSE_SECONDS = max(
+    0.0,
+    float(os.getenv("ADMIN_LEADERBOARD_QUERY_PAUSE_SECONDS", "0.05")),
+)
+_LEADERBOARD_START_DELAY_SECONDS = max(
+    0.0,
+    float(os.getenv("ADMIN_LEADERBOARD_START_DELAY_SECONDS", "0.2")),
+)
 _leaderboard_semaphore = asyncio.Semaphore(_LEADERBOARD_MAX_CONCURRENT)
 _leaderboard_jobs: dict[str, asyncio.Task] = {}
 _leaderboard_cache: dict[str, dict] = {}
@@ -1035,6 +1043,11 @@ def _leaderboard_cache_key(
     return sha256(json.dumps(payload, sort_keys=True, ensure_ascii=False).encode("utf-8")).hexdigest()
 
 
+async def _leaderboard_pause() -> None:
+    if _LEADERBOARD_QUERY_PAUSE_SECONDS > 0:
+        await asyncio.sleep(_LEADERBOARD_QUERY_PAUSE_SECONDS)
+
+
 async def _build_user_leaderboard_response(
     session_factory,
     settings,
@@ -1064,16 +1077,25 @@ async def _build_user_leaderboard_response(
             "cleanup_system_questions": settings.cleanup_system_questions,
         }
         overview = await _query_overview(session, since_dt, until_dt, **common)
+        await _leaderboard_pause()
         users = await _query_user_leaderboard(session, since_dt, until_dt, **common)
+        await _leaderboard_pause()
         skills = await _query_call_rankings(session, since_dt, until_dt, user_id=None, field="skill", limit=limit, **tool_common)
+        await _leaderboard_pause()
         tools = await _query_call_rankings(session, since_dt, until_dt, user_id=None, field="tool", limit=limit, **tool_common)
+        await _leaderboard_pause()
         models = await _query_model_rankings(session, since_dt, until_dt, user_id=None, limit=limit, **common)
         if not models:
             models = await _query_run_dimensions(session, since_dt, until_dt, user_id=None, field="model", limit=limit, **common)
+        await _leaderboard_pause()
         agents = await _query_run_dimensions(session, since_dt, until_dt, user_id=None, field="agent", limit=limit, **common)
+        await _leaderboard_pause()
         run_statuses = await _query_run_dimensions(session, since_dt, until_dt, user_id=None, field="status", limit=limit, **common)
+        await _leaderboard_pause()
         recent_questions = await _query_recent_questions(session, since_dt, until_dt, user_id=None, limit=limit, **question_common)
+        await _leaderboard_pause()
         frequent_questions = await _query_frequent_questions(session, since_dt, until_dt, limit=limit, **question_common)
+        await _leaderboard_pause()
         trends = await _query_trends(session, since_dt, until_dt, **common)
 
     return AdminLeaderboardResponse(
@@ -1113,6 +1135,8 @@ async def _refresh_leaderboard_cache(
 ) -> None:
     acquired = False
     try:
+        if _LEADERBOARD_START_DELAY_SECONDS > 0:
+            await asyncio.sleep(_LEADERBOARD_START_DELAY_SECONDS)
         await _leaderboard_semaphore.acquire()
         acquired = True
         response = await asyncio.wait_for(