fix(email): surface calendar truncation in the API

Author: mikemikimike

hub/agents/email/python/CHANGELOG.md

@@ -505,7 +505,9 @@ and is **Gmail-only** (a request resolving to an Outlook mailbox is rejected
 - `GET /v1/email/calendar/events` → `CalendarEventsResponse` (read-only view;
   `CalendarEvent` flattens provider start/end strings). `time_min`/`time_max`
   are optional; omitting both defaults to a forward window (now → +30 days) so
-  recurring series don't surface their oldest instances (#2162).
+  recurring series don't surface their oldest instances (#2162). The response
+  includes `count` for the returned page and `truncated: true` when the
+  provider reports another page; a truncated response is not a complete window.
 - `POST /v1/email/calendar/events/preview` → `CalendarEventPreviewResponse` mints
   a confirmation token bound to the event.
 - `POST /v1/email/calendar/events` (`CalendarCreateEventRequest`) creates the

hub/agents/email/python/CONTRACT.md

@@ -3261,7 +3261,11 @@ async def list_calendar_events(
         )
         for e in data.get("events", [])
     ]
-    return CalendarEventsResponse(events=events)
+    return CalendarEventsResponse(
+        events=events,
+        count=len(events),
+        truncated=bool(data.get("truncated", False)),
+    )
 
 
 @router.post("/calendar/events/preview", response_model=CalendarEventPreviewResponse)

hub/agents/email/python/gaia_agent_email/api_routes.py

@@ -1150,6 +1150,16 @@ class CalendarEventsResponse(_Strict):
     events: List[CalendarEvent] = Field(
         default_factory=list, description="Matching events, ordered by start time."
     )
+    count: int = Field(
+        default=0, ge=0, description="Number of events returned in this page."
+    )
+    truncated: bool = Field(
+        default=False,
+        description=(
+            "True when the provider reported another page; the events list is "
+            "not the complete calendar window."
+        ),
+    )
 
 
 class CalendarCreateEventRequest(_Strict):