fix(pagination): stop skipping a page per auto-pagination iteration

Sync/AsyncOffsetPagination.next_page_info() requested the next page at
next_offset + len(items). The X-Next-Offset header already holds the
offset where the next page starts (the API computes offset + limit), so
adding the current page length skipped a full page per iteration: with
250 items at limit 100, iteration returned items 0-99 and 200-249 and
silently dropped 100-199. X-Has-More still terminated the loop, hiding
the data loss.

Use the header value directly. Absent header already terminated via the
None check, unchanged.

Hand-maintained fix: with Stainless's hosted generator winding down, the
template-level fix is not coming; this commit and its test are the
canonical behavior.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: IlyaasK

src/kernel/pagination.py

@@ -42,10 +42,9 @@ def next_page_info(self) -> Optional[PageInfo]:
         if next_offset is None:
             return None  # type: ignore[unreachable]
 
-        length = len(self._get_page_items())
-        current_count = next_offset + length
-
-        return PageInfo(params={"offset": current_count})
+        # X-Next-Offset already holds the offset where the next page starts;
+        # adding the current page length on top skips a full page per iteration.
+        return PageInfo(params={"offset": next_offset})
 
     @classmethod
     def build(cls: Type[_BaseModelT], *, response: Response, data: object) -> _BaseModelT:  # noqa: ARG003
@@ -85,10 +84,9 @@ def next_page_info(self) -> Optional[PageInfo]:
         if next_offset is None:
             return None  # type: ignore[unreachable]
 
-        length = len(self._get_page_items())
-        current_count = next_offset + length
-
-        return PageInfo(params={"offset": current_count})
+        # X-Next-Offset already holds the offset where the next page starts;
+        # adding the current page length on top skips a full page per iteration.
+        return PageInfo(params={"offset": next_offset})
 
     @classmethod
     def build(cls: Type[_BaseModelT], *, response: Response, data: object) -> _BaseModelT:  # noqa: ARG003

tests/test_pagination.py

@@ -0,0 +1,42 @@
+from typing import Any, List, Optional
+
+import httpx
+
+from kernel.pagination import SyncOffsetPagination
+
+
+def _page(
+    *, items: List[Any], next_offset: Optional[int], has_more: Optional[bool]
+) -> SyncOffsetPagination[Any]:
+    headers: dict[str, str] = {}
+    if next_offset is not None:
+        headers["X-Next-Offset"] = str(next_offset)
+    if has_more is not None:
+        headers["X-Has-More"] = "true" if has_more else "false"
+    response = httpx.Response(200, headers=headers)
+    return SyncOffsetPagination.build(response=response, data=items)
+
+
+def test_next_page_starts_at_exactly_x_next_offset() -> None:
+    # X-Next-Offset already holds the next page's start. Adding the current
+    # page length on top (the old behavior) skipped a full page per iteration.
+    page = _page(items=[{}] * 100, next_offset=100, has_more=True)
+    info = page.next_page_info()
+    assert info is not None
+    assert info.params == {"offset": 100}
+
+
+def test_stops_when_x_next_offset_absent() -> None:
+    page = _page(items=[{}] * 100, next_offset=None, has_more=True)
+    assert page.next_page_info() is None
+    assert page.has_next_page() is False
+
+
+def test_stops_when_x_has_more_false() -> None:
+    page = _page(items=[{}] * 50, next_offset=200, has_more=False)
+    assert page.has_next_page() is False
+
+
+def test_stops_on_empty_page() -> None:
+    page = _page(items=[], next_offset=300, has_more=True)
+    assert page.has_next_page() is False