feat: cursor-based pagination for messages

src/agentex/resources/messages/messages.py

@@ -28,7 +28,7 @@
 )
 from ..._base_client import make_request_options
 from ...types.task_message import TaskMessage
-from ...types.message_list_response import MessageListResponse
+from ...types.message_list_response import MessageListResponse, PaginatedMessagesResponse
 from ...types.task_message_content_param import TaskMessageContentParam
 
 __all__ = ["MessagesResource", "AsyncMessagesResource"]
@@ -182,6 +182,8 @@ def list(
         task_id: str,
         limit: int | Omit = omit,
         page_number: int | Omit = omit,
+        order_by: str | Omit = omit,
+        order_direction: str | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
@@ -190,11 +192,21 @@ def list(
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> MessageListResponse:
         """
-        List Messages
+        List Messages (returns list of TaskMessage).
+
+        For cursor-based pagination with infinite scroll support, use `list_paginated` instead.
 
         Args:
           task_id: The task ID
 
+          limit: Maximum number of messages to return (default: 50)
+
+          page_number: Page number for offset-based pagination (default: 1)
+
+          order_by: Field to order by (default: created_at)
+
+          order_direction: Order direction - "asc" or "desc" (default: desc)
+
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -215,13 +227,86 @@ def list(
                         "task_id": task_id,
                         "limit": limit,
                         "page_number": page_number,
+                        "order_by": order_by,
+                        "order_direction": order_direction,
                     },
                     message_list_params.MessageListParams,
                 ),
             ),
             cast_to=MessageListResponse,
         )
 
+    def list_paginated(
+        self,
+        *,
+        task_id: str,
+        limit: int | Omit = omit,
+        cursor: str | Omit = omit,
+        direction: str | Omit = omit,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> PaginatedMessagesResponse:
+        """
+        List Messages with cursor-based pagination.
+
+        Returns messages for a task with pagination metadata.
+        Use the `next_cursor` from the response to fetch the next page.
+
+        Args:
+          task_id: The task ID
+
+          limit: Maximum number of messages to return (default: 50)
+
+          cursor: Opaque cursor string for pagination. Pass the `next_cursor` from
+                  a previous response to get the next page.
+
+          direction: Pagination direction - "older" to get older messages (default),
+                     "newer" to get newer messages.
+
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+
+        Example:
+            # First request
+            response = client.messages.list_paginated(task_id="xxx", limit=50)
+
+            # Next page
+            if response.has_more:
+                next_page = client.messages.list_paginated(
+                    task_id="xxx",
+                    limit=50,
+                    cursor=response.next_cursor
+                )
+        """
+        return self._get(
+            "/messages/paginated",
+            options=make_request_options(
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                query=maybe_transform(
+                    {
+                        "task_id": task_id,
+                        "limit": limit,
+                        "cursor": cursor,
+                        "direction": direction,
+                    },
+                    message_list_params.MessageListPaginatedParams,
+                ),
+            ),
+            cast_to=PaginatedMessagesResponse,
+        )
+
 
 class AsyncMessagesResource(AsyncAPIResource):
     @cached_property
@@ -371,6 +456,8 @@ async def list(
         task_id: str,
         limit: int | Omit = omit,
         page_number: int | Omit = omit,
+        order_by: str | Omit = omit,
+        order_direction: str | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
@@ -379,11 +466,21 @@ async def list(
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> MessageListResponse:
         """
-        List Messages
+        List Messages (returns list of TaskMessage).
+
+        For cursor-based pagination with infinite scroll support, use `list_paginated` instead.
 
         Args:
           task_id: The task ID
 
+          limit: Maximum number of messages to return (default: 50)
+
+          page_number: Page number for offset-based pagination (default: 1)
+
+          order_by: Field to order by (default: created_at)
+
+          order_direction: Order direction - "asc" or "desc" (default: desc)
+
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -404,13 +501,86 @@ async def list(
                         "task_id": task_id,
                         "limit": limit,
                         "page_number": page_number,
+                        "order_by": order_by,
+                        "order_direction": order_direction,
                     },
                     message_list_params.MessageListParams,
                 ),
             ),
             cast_to=MessageListResponse,
         )
 
+    async def list_paginated(
+        self,
+        *,
+        task_id: str,
+        limit: int | Omit = omit,
+        cursor: str | Omit = omit,
+        direction: str | Omit = omit,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> PaginatedMessagesResponse:
+        """
+        List Messages with cursor-based pagination.
+
+        Returns messages for a task with pagination metadata.
+        Use the `next_cursor` from the response to fetch the next page.
+
+        Args:
+          task_id: The task ID
+
+          limit: Maximum number of messages to return (default: 50)
+
+          cursor: Opaque cursor string for pagination. Pass the `next_cursor` from
+                  a previous response to get the next page.
+
+          direction: Pagination direction - "older" to get older messages (default),
+                     "newer" to get newer messages.
+
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+
+        Example:
+            # First request
+            response = await client.messages.list_paginated(task_id="xxx", limit=50)
+
+            # Next page
+            if response.has_more:
+                next_page = await client.messages.list_paginated(
+                    task_id="xxx",
+                    limit=50,
+                    cursor=response.next_cursor
+                )
+        """
+        return await self._get(
+            "/messages/paginated",
+            options=make_request_options(
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                query=await async_maybe_transform(
+                    {
+                        "task_id": task_id,
+                        "limit": limit,
+                        "cursor": cursor,
+                        "direction": direction,
+                    },
+                    message_list_params.MessageListPaginatedParams,
+                ),
+            ),
+            cast_to=PaginatedMessagesResponse,
+        )
+
 
 class MessagesResourceWithRawResponse:
     def __init__(self, messages: MessagesResource) -> None:
@@ -428,6 +598,9 @@ def __init__(self, messages: MessagesResource) -> None:
         self.list = to_raw_response_wrapper(
             messages.list,
         )
+        self.list_paginated = to_raw_response_wrapper(
+            messages.list_paginated,
+        )
 
     @cached_property
     def batch(self) -> BatchResourceWithRawResponse:
@@ -450,6 +623,9 @@ def __init__(self, messages: AsyncMessagesResource) -> None:
         self.list = async_to_raw_response_wrapper(
             messages.list,
         )
+        self.list_paginated = async_to_raw_response_wrapper(
+            messages.list_paginated,
+        )
 
     @cached_property
     def batch(self) -> AsyncBatchResourceWithRawResponse:
@@ -472,6 +648,9 @@ def __init__(self, messages: MessagesResource) -> None:
         self.list = to_streamed_response_wrapper(
             messages.list,
         )
+        self.list_paginated = to_streamed_response_wrapper(
+            messages.list_paginated,
+        )
 
     @cached_property
     def batch(self) -> BatchResourceWithStreamingResponse:
@@ -494,6 +673,9 @@ def __init__(self, messages: AsyncMessagesResource) -> None:
         self.list = async_to_streamed_response_wrapper(
             messages.list,
         )
+        self.list_paginated = async_to_streamed_response_wrapper(
+            messages.list_paginated,
+        )
 
     @cached_property
     def batch(self) -> AsyncBatchResourceWithStreamingResponse:

src/agentex/types/__init__.py

@@ -50,6 +50,7 @@
 from .tool_request_content import ToolRequestContent as ToolRequestContent
 from .message_create_params import MessageCreateParams as MessageCreateParams
 from .message_list_response import MessageListResponse as MessageListResponse
+from .message_list_response import PaginatedMessagesResponse as PaginatedMessagesResponse
 from .message_update_params import MessageUpdateParams as MessageUpdateParams
 from .tool_response_content import ToolResponseContent as ToolResponseContent
 from .tracker_list_response import TrackerListResponse as TrackerListResponse

src/agentex/types/message_list_params.py

@@ -4,13 +4,37 @@
 
 from typing_extensions import Required, TypedDict
 
-__all__ = ["MessageListParams"]
+__all__ = ["MessageListParams", "MessageListPaginatedParams"]
 
 
 class MessageListParams(TypedDict, total=False):
     task_id: Required[str]
     """The task ID"""
 
     limit: int
+    """Maximum number of messages to return (default: 50)"""
 
     page_number: int
+    """Page number for offset-based pagination (default: 1)"""
+
+    order_by: str
+    """Field to order by (default: created_at)"""
+
+    order_direction: str
+    """Order direction - "asc" or "desc" (default: desc)"""
+
+
+class MessageListPaginatedParams(TypedDict, total=False):
+    task_id: Required[str]
+    """The task ID"""
+
+    limit: int
+    """Maximum number of messages to return (default: 50)"""
+
+    cursor: str
+    """Opaque cursor string for pagination. Pass the `next_cursor` from
+    a previous response to get the next page."""
+
+    direction: str
+    """Pagination direction - "older" to get older messages (default),
+    "newer" to get newer messages."""

src/agentex/types/message_list_response.py

@@ -1,10 +1,27 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-from typing import List
-from typing_extensions import TypeAlias
+from typing import List, Optional
 
+from .._models import BaseModel
 from .task_message import TaskMessage
 
-__all__ = ["MessageListResponse"]
+__all__ = ["MessageListResponse", "PaginatedMessagesResponse"]
 
-MessageListResponse: TypeAlias = List[TaskMessage]
+
+# Original response type: list of messages
+MessageListResponse = List[TaskMessage]
+
+
+class PaginatedMessagesResponse(BaseModel):
+    """Response with cursor pagination metadata."""
+
+    data: List[TaskMessage]
+    """List of messages"""
+
+    next_cursor: Optional[str] = None
+    """Cursor for fetching the next page of older messages.
+    Pass this as the `cursor` parameter in the next request.
+    None if there are no more messages."""
+
+    has_more: bool = False
+    """Whether there are more messages to fetch"""