feat: add cursor-based pagination support for messages

BREAKING CHANGE: messages.list() now returns PaginatedMessagesResponse
with {data, next_cursor, has_more} instead of list[TaskMessage].

Changes:
- Add cursor and direction params to MessageListParams
- Add PaginatedMessagesResponse type with data, next_cursor, has_more
- Update list() method signature in Messages resource
- Update tests for new response format

Author: gabrycina

src/agentex/resources/messages/messages.py

@@ -181,7 +181,11 @@ def list(
         *,
         task_id: str,
         limit: int | Omit = omit,
+        cursor: str | Omit = omit,
+        direction: str | 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,18 +194,47 @@ def list(
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> MessageListResponse:
         """
-        List Messages
+        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.
+
+          page_number: [DEPRECATED] Use cursor instead. Page number for offset pagination.
+
+          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
 
           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(task_id="xxx", limit=50)
+
+            # Next page
+            if response.has_more:
+                next_page = client.messages.list(
+                    task_id="xxx",
+                    limit=50,
+                    cursor=response.next_cursor
+                )
         """
         return self._get(
             "/messages",
@@ -214,7 +247,11 @@ def list(
                     {
                         "task_id": task_id,
                         "limit": limit,
+                        "cursor": cursor,
+                        "direction": direction,
                         "page_number": page_number,
+                        "order_by": order_by,
+                        "order_direction": order_direction,
                     },
                     message_list_params.MessageListParams,
                 ),
@@ -370,7 +407,11 @@ async def list(
         *,
         task_id: str,
         limit: int | Omit = omit,
+        cursor: str | Omit = omit,
+        direction: str | 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,18 +420,47 @@ async def list(
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> MessageListResponse:
         """
-        List Messages
+        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.
+
+          page_number: [DEPRECATED] Use cursor instead. Page number for offset pagination.
+
+          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
 
           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(task_id="xxx", limit=50)
+
+            # Next page
+            if response.has_more:
+                next_page = await client.messages.list(
+                    task_id="xxx",
+                    limit=50,
+                    cursor=response.next_cursor
+                )
         """
         return await self._get(
             "/messages",
@@ -403,7 +473,11 @@ async def list(
                     {
                         "task_id": task_id,
                         "limit": limit,
+                        "cursor": cursor,
+                        "direction": direction,
                         "page_number": page_number,
+                        "order_by": order_by,
+                        "order_direction": order_direction,
                     },
                     message_list_params.MessageListParams,
                 ),

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

@@ -12,5 +12,21 @@ class MessageListParams(TypedDict, total=False):
     """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."""
 
     page_number: int
+    """[DEPRECATED] Use cursor instead. 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)"""

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]
+
+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"""
+
+
+# Alias for backwards compatibility
+MessageListResponse = PaginatedMessagesResponse

tests/api_resources/test_messages.py

@@ -240,10 +240,17 @@ def test_method_list(self, client: Agentex) -> None:
     def test_method_list_with_all_params(self, client: Agentex) -> None:
         message = client.messages.list(
             task_id="task_id",
-            limit=0,
+            limit=50,
+            cursor="eyJ2IjoxLCJpZCI6Im1zZ18xMjMiLCJjcmVhdGVkX2F0IjoiMjAyNC0wMS0xNVQxMDozMDowMCJ9",
+            direction="older",
             page_number=0,
+            order_by="created_at",
+            order_direction="desc",
         )
         assert_matches_type(MessageListResponse, message, path=["response"])
+        # Response should have data, next_cursor, and has_more
+        assert hasattr(message, "data")
+        assert hasattr(message, "has_more")
 
     @pytest.mark.skip(reason="Prism tests are disabled")
     @parametrize
@@ -496,10 +503,17 @@ async def test_method_list(self, async_client: AsyncAgentex) -> None:
     async def test_method_list_with_all_params(self, async_client: AsyncAgentex) -> None:
         message = await async_client.messages.list(
             task_id="task_id",
-            limit=0,
+            limit=50,
+            cursor="eyJ2IjoxLCJpZCI6Im1zZ18xMjMiLCJjcmVhdGVkX2F0IjoiMjAyNC0wMS0xNVQxMDozMDowMCJ9",
+            direction="older",
             page_number=0,
+            order_by="created_at",
+            order_direction="desc",
         )
         assert_matches_type(MessageListResponse, message, path=["response"])
+        # Response should have data, next_cursor, and has_more
+        assert hasattr(message, "data")
+        assert hasattr(message, "has_more")
 
     @pytest.mark.skip(reason="Prism tests are disabled")
     @parametrize