feat(backend): presence stats count time online from sessions in the browser time zone, capture uptime marks hours without data, presence reaches every stream of the account, message volume keeps empty days

backend/src/api/mcp/server.py

@@ -20,9 +20,19 @@ from api.mcp.download import (
 from api.mcp.format import build_transcript, load_notes, load_photos, resolve_names
 from dependencies.container import container
 from utils.files import resolve_mime
-from utils.read import annotations, chats, media, peers, presence, social, watches
+from utils.read import (
+    annotations,
+    chats,
+    media,
+    peers,
+    presence,
+    presence_stats,
+    social,
+    watches,
+)
 from utils.read.accounts import self_user_id, unknown_account_hint
 from utils.read.models import DEFAULT_LIMIT, Page
+from utils.read.period import DEFAULT_TZ, MAX_DAYS, known_timezone
 from utils.read.read_receipts import read_info
 from utils.search.models import SearchFilters
 from utils.search.repository import search_messages
@@ -335,6 +345,37 @@ async def presence_history(
     )
 
 
+@mcp.tool(name="presence_stats")
+async def presence_stats_tool(
+    account_id: int,
+    peer_id: int,
+    days: int = 30,
+    tz: str = DEFAULT_TZ,
+    limit: int = DEFAULT_LIMIT,
+    offset: int = 0,
+) -> dict[str, Any]:
+    """Time a peer spent online, from status pushes turned into online sessions.
+
+    `tz` is an IANA zone name; days and hours are counted in it. `week` holds
+    the average online minutes for each weekday (0 is Monday) and hour, null
+    where the archive has no data for that hour. `days` gives online seconds
+    per day, `gaps` the stretches when capture was down, `sessions` the latest
+    sessions (online stretches with breaks under 5 minutes), paged by
+    `limit`/`offset`. `hidden` means the peer hides their last seen time.
+    """
+    pool = await _pool()
+    if not 1 <= days <= MAX_DAYS:
+        msg = f"days must be between 1 and {MAX_DAYS}"
+        raise ToolError(msg)
+    if not await known_timezone(pool, tz):
+        msg = f"Unknown time zone: {tz}"
+        raise ToolError(msg)
+    stats = await presence_stats.presence_stats(
+        pool, account_id, peer_id, Page(limit=limit, offset=offset), days=days, tz=tz
+    )
+    return stats.model_dump(mode="json")
+
+
 @mcp.tool
 async def get_peer_history(account_id: int, peer_id: int) -> list[dict[str, Any]]:
     """Get name/username/avatar change history of a contact."""