fix: taskslist error on invalid page token and response serialization (#814)

# Description

This PR addresses two main issues related to the list_tasks JSON-RPC
endpoint:

- Fixed how list_tasks formats the ListTasksResponse to ensure all
fields are explicitly printed, even when they carry default values (such
as an empty next_page_token).
- Replaced generic ValueError exceptions with A2A SDK's standard
InvalidParamsError when handling malformed or invalid pagination tokens.
This correctly surfaces -32602 Invalid params via JSON-RPC.

Author: guglielmo-san

src/a2a/server/request_handlers/jsonrpc_handler.py

@@ -373,7 +373,11 @@ async def list_tasks(
             response = await self.request_handler.on_list_tasks(
                 request, context
             )
-            result = MessageToDict(response, preserving_proto_field_name=False)
+            result = MessageToDict(
+                response,
+                preserving_proto_field_name=False,
+                always_print_fields_with_no_presence=True,
+            )
             return _build_success_response(request_id, result)
         except A2AError as e:
             return _build_error_response(request_id, e)

src/a2a/server/tasks/database_task_store.py

@@ -41,6 +41,7 @@
 from a2a.types import a2a_pb2
 from a2a.types.a2a_pb2 import Task
 from a2a.utils.constants import DEFAULT_LIST_TASKS_PAGE_SIZE
+from a2a.utils.errors import InvalidParamsError
 from a2a.utils.task import decode_page_token, encode_page_token
 
 
@@ -285,7 +286,9 @@ async def list(
                     )
                 ).scalar_one_or_none()
                 if not start_task:
-                    raise ValueError(f'Invalid page token: {params.page_token}')
+                    raise InvalidParamsError(
+                        f'Invalid page token: {params.page_token}'
+                    )
 
                 start_task_timestamp = start_task.last_updated
                 where_clauses = []

src/a2a/server/tasks/inmemory_task_store.py

@@ -7,6 +7,7 @@
 from a2a.types import a2a_pb2
 from a2a.types.a2a_pb2 import Task
 from a2a.utils.constants import DEFAULT_LIST_TASKS_PAGE_SIZE
+from a2a.utils.errors import InvalidParamsError
 from a2a.utils.task import decode_page_token, encode_page_token
 
 
@@ -135,7 +136,9 @@ async def list(
                     valid_token = True
                     break
             if not valid_token:
-                raise ValueError(f'Invalid page token: {params.page_token}')
+                raise InvalidParamsError(
+                    f'Invalid page token: {params.page_token}'
+                )
         page_size = params.page_size or DEFAULT_LIST_TASKS_PAGE_SIZE
         end_idx = start_idx + page_size
         next_page_token = (

src/a2a/utils/task.py

@@ -186,9 +186,10 @@ def decode_page_token(page_token: str) -> str:
     missing_padding = len(encoded_str) % 4
     if missing_padding:
         encoded_str += '=' * (4 - missing_padding)
-    print(f'input: {encoded_str}')
     try:
         decoded = b64decode(encoded_str.encode(_ENCODING)).decode(_ENCODING)
     except (binascii.Error, UnicodeDecodeError) as e:
-        raise ValueError('Token is not a valid base64-encoded cursor.') from e
+        raise InvalidParamsError(
+            'Token is not a valid base64-encoded cursor.'
+        ) from e
     return decoded

tests/server/request_handlers/test_jsonrpc_handler.py

@@ -214,6 +214,31 @@ async def test_on_list_tasks_error(self) -> None:
         self.assertTrue(is_error_response(response))
         self.assertEqual(response['error']['message'], 'DB down')
 
+    async def test_on_list_tasks_empty(self) -> None:
+        request_handler = AsyncMock(spec=DefaultRequestHandler)
+        handler = JSONRPCHandler(self.mock_agent_card, request_handler)
+
+        mock_result = ListTasksResponse(page_size=10)
+        request_handler.on_list_tasks.return_value = mock_result
+        from a2a.types.a2a_pb2 import ListTasksRequest
+
+        request = ListTasksRequest(page_size=10)
+        call_context = ServerCallContext(state={'foo': 'bar'})
+
+        response = await handler.list_tasks(request, call_context)
+
+        request_handler.on_list_tasks.assert_awaited_once()
+        self.assertIsInstance(response, dict)
+        self.assertTrue(is_success_response(response))
+        self.assertIn('tasks', response['result'])
+        self.assertEqual(len(response['result']['tasks']), 0)
+        self.assertIn('nextPageToken', response['result'])
+        self.assertEqual(response['result']['nextPageToken'], '')
+        self.assertIn('pageSize', response['result'])
+        self.assertEqual(response['result']['pageSize'], 10)
+        self.assertIn('totalSize', response['result'])
+        self.assertEqual(response['result']['totalSize'], 0)
+
     async def test_on_cancel_task_success(self) -> None:
         mock_agent_executor = AsyncMock(spec=AgentExecutor)
         mock_task_store = AsyncMock(spec=TaskStore)

tests/server/tasks/test_database_task_store.py

@@ -36,6 +36,7 @@
 from a2a.auth.user import User
 from a2a.server.context import ServerCallContext
 from a2a.utils.constants import DEFAULT_LIST_TASKS_PAGE_SIZE
+from a2a.utils.errors import InvalidParamsError
 
 
 class SampleUser(User):
@@ -380,7 +381,7 @@ async def test_list_tasks_fails(
     for task in tasks_to_create:
         await db_store_parameterized.save(task)
 
-    with pytest.raises(ValueError) as excinfo:
+    with pytest.raises(InvalidParamsError) as excinfo:
         await db_store_parameterized.list(params)
 
     assert expected_error_message in str(excinfo.value)

tests/server/tasks/test_inmemory_task_store.py

@@ -5,6 +5,7 @@
 from a2a.server.tasks import InMemoryTaskStore
 from a2a.types.a2a_pb2 import Task, TaskState, TaskStatus, ListTasksRequest
 from a2a.utils.constants import DEFAULT_LIST_TASKS_PAGE_SIZE
+from a2a.utils.errors import InvalidParamsError
 
 from a2a.auth.user import User
 
@@ -239,7 +240,7 @@ async def test_list_tasks_fails(
     for task in tasks_to_create:
         await store.save(task)
 
-    with pytest.raises(ValueError) as excinfo:
+    with pytest.raises(InvalidParamsError) as excinfo:
         await store.list(params)
 
     assert expected_error_message in str(excinfo.value)

tests/utils/test_task.py

@@ -21,6 +21,7 @@
     encode_page_token,
     new_task,
 )
+from a2a.utils.errors import InvalidParamsError
 
 
 class TestTask(unittest.TestCase):
@@ -214,7 +215,7 @@ def test_decode_page_token_succeeds(self):
         assert decode_page_token(self.encoded_page_token) == self.page_token
 
     def test_decode_page_token_fails(self):
-        with pytest.raises(ValueError) as excinfo:
+        with pytest.raises(InvalidParamsError) as excinfo:
             decode_page_token('invalid')
 
         assert 'Token is not a valid base64-encoded cursor.' in str(