feat(backend): enhance search_conversation_events functions with timestamp filtering support (#695)

Author: hieptl

openhands-agent-server/openhands/agent_server/event_router.py

@@ -3,6 +3,7 @@
 """
 
 import logging
+from datetime import datetime
 from typing import Annotated
 
 from fastapi import (
@@ -31,9 +32,31 @@
 )
 logger = logging.getLogger(__name__)
 
+
 # Read methods
 
 
+def normalize_datetime_to_server_timezone(dt: datetime) -> datetime:
+    """
+    Normalize datetime to server timezone for consistent comparison.
+
+    If the datetime has timezone info, convert to server native timezone.
+    If it's naive (no timezone), assume it's already in server timezone.
+
+    Args:
+        dt: Input datetime (may be timezone-aware or naive)
+
+    Returns:
+        Datetime in server native timezone (timezone-aware)
+    """
+    if dt.tzinfo is not None:
+        # Timezone-aware: convert to server native timezone
+        return dt.astimezone(None)
+    else:
+        # Naive datetime: assume it's already in server timezone
+        return dt
+
+
 @event_router.get("/search", responses={404: {"description": "Conversation not found"}})
 async def search_conversation_events(
     page_id: Annotated[
@@ -54,12 +77,33 @@ async def search_conversation_events(
         EventSortOrder,
         Query(title="Sort order for events"),
     ] = EventSortOrder.TIMESTAMP,
+    timestamp__gte: Annotated[
+        datetime | None,
+        Query(title="Filter: event timestamp >= this datetime"),
+    ] = None,
+    timestamp__lt: Annotated[
+        datetime | None,
+        Query(title="Filter: event timestamp < this datetime"),
+    ] = None,
     event_service: EventService = Depends(get_event_service),
 ) -> EventPage:
     """Search / List local events"""
     assert limit > 0
     assert limit <= 100
-    return await event_service.search_events(page_id, limit, kind, sort_order)
+
+    # Normalize timezone-aware datetimes to server timezone
+    normalized_gte = (
+        normalize_datetime_to_server_timezone(timestamp__gte)
+        if timestamp__gte
+        else None
+    )
+    normalized_lt = (
+        normalize_datetime_to_server_timezone(timestamp__lt) if timestamp__lt else None
+    )
+
+    return await event_service.search_events(
+        page_id, limit, kind, sort_order, normalized_gte, normalized_lt
+    )
 
 
 @event_router.get("/count", responses={404: {"description": "Conversation not found"}})
@@ -70,10 +114,29 @@ async def count_conversation_events(
             title="Optional filter by event kind/type (e.g., ActionEvent, MessageEvent)"
         ),
     ] = None,
+    timestamp__gte: Annotated[
+        datetime | None,
+        Query(title="Filter: event timestamp >= this datetime"),
+    ] = None,
+    timestamp__lt: Annotated[
+        datetime | None,
+        Query(title="Filter: event timestamp < this datetime"),
+    ] = None,
     event_service: EventService = Depends(get_event_service),
 ) -> int:
     """Count local events matching the given filters"""
-    count = await event_service.count_events(kind)
+    # Normalize timezone-aware datetimes to server timezone
+    normalized_gte = (
+        normalize_datetime_to_server_timezone(timestamp__gte)
+        if timestamp__gte
+        else None
+    )
+    normalized_lt = (
+        normalize_datetime_to_server_timezone(timestamp__lt) if timestamp__lt else None
+    )
+
+    count = await event_service.count_events(kind, normalized_gte, normalized_lt)
+
     return count
 
 

openhands-agent-server/openhands/agent_server/event_service.py

@@ -1,5 +1,6 @@
 import asyncio
 from dataclasses import dataclass, field
+from datetime import datetime
 from pathlib import Path
 from uuid import UUID
 
@@ -82,10 +83,16 @@ async def search_events(
         limit: int = 100,
         kind: str | None = None,
         sort_order: EventSortOrder = EventSortOrder.TIMESTAMP,
+        timestamp__gte: datetime | None = None,
+        timestamp__lt: datetime | None = None,
     ) -> EventPage:
         if not self._conversation:
             raise ValueError("inactive_service")
 
+        # Convert datetime to ISO string for comparison (ISO strings are comparable)
+        timestamp_gte_str = timestamp__gte.isoformat() if timestamp__gte else None
+        timestamp_lt_str = timestamp__lt.isoformat() if timestamp__lt else None
+
         # Collect all events
         all_events = []
         with self._conversation._state as state:
@@ -97,6 +104,16 @@ async def search_events(
                     != kind
                 ):
                     continue
+
+                # Apply timestamp filters if provided (ISO string comparison)
+                if (
+                    timestamp_gte_str is not None
+                    and event.timestamp < timestamp_gte_str
+                ):
+                    continue
+                if timestamp_lt_str is not None and event.timestamp >= timestamp_lt_str:
+                    continue
+
                 all_events.append(event)
 
         # Sort events based on sort_order
@@ -131,11 +148,17 @@ async def search_events(
     async def count_events(
         self,
         kind: str | None = None,
+        timestamp__gte: datetime | None = None,
+        timestamp__lt: datetime | None = None,
     ) -> int:
         """Count events matching the given filters."""
         if not self._conversation:
             raise ValueError("inactive_service")
 
+        # Convert datetime to ISO string for comparison (ISO strings are comparable)
+        timestamp_gte_str = timestamp__gte.isoformat() if timestamp__gte else None
+        timestamp_lt_str = timestamp__lt.isoformat() if timestamp__lt else None
+
         count = 0
         with self._conversation._state as state:
             for event in state.events:
@@ -146,6 +169,16 @@ async def count_events(
                     != kind
                 ):
                     continue
+
+                # Apply timestamp filters if provided (ISO string comparison)
+                if (
+                    timestamp_gte_str is not None
+                    and event.timestamp < timestamp_gte_str
+                ):
+                    continue
+                if timestamp_lt_str is not None and event.timestamp >= timestamp_lt_str:
+                    continue
+
                 count += 1
 
         return count