feat(spec): Add tasks/list method with filtering and pagination to the specification (#831)

# Description

Thank you for opening a Pull Request!
Before submitting your PR, there are a few things you can do to make
sure it goes smoothly:

- [x] Follow the [`CONTRIBUTING`
Guide](https://github.com/a2aproject/A2A/blob/main/CONTRIBUTING.md).
- [x] Make your Pull Request title in the
<https://www.conventionalcommits.org/> specification.
- [x] Ensure the tests and linter pass (Run `nox -s format` from the
repository root to format)
- [x] Appropriate docs were updated (if necessary)
- [x] Fix existing linting errors (I guess they were already on the main
upstream)

Fixes #761  🦕

---------

Signed-off-by: Eden Reich <eden.reich@gmail.com>
Co-authored-by: Holt Skinner <holtskinner@google.com>
Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
Co-authored-by: Darrel <darrmi@microsoft.com>
Co-authored-by: Amye Scavarda Perrin <amye@amye.org>

Author: 4 people

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [0.4.0](https://github.com/a2aproject/A2A/compare/v0.3.0...v0.4.0) (2025-09-15)
+
+### Features
+
+* **spec:** Add `tasks/list` method for retrieving and filtering tasks with pagination
+
 ## [0.3.0](https://github.com/a2aproject/A2A/compare/v0.2.6...v0.3.0) (2025-07-30)
 
 

docs/llms.txt

@@ -76,21 +76,61 @@ Key features of the A2A protocol include: agent discovery via Agent Cards, stand
 
 ### 2.3. A2A RPC Methods
 
--   **`message/send`:** Sends a message to initiate or continue a task. Returns a final `Task` or `Message` object.
--   **`message/stream`:** Sends a message and subscribes to real-time updates via Server-Sent Events (SSE).
--   **`tasks/get`:** Retrieves the current state of a task by its ID.
--   **`tasks/cancel`:** Requests cancellation of a running task.
--   **`tasks/pushNotificationConfig/set`:** Sets the webhook configuration for a task.
--   **`tasks/pushNotificationConfig/get`:** Retrieves the push notification configuration for a task.
--   **`tasks/resubscribe`:** Resubscribes to a task's update stream after a disconnection.
-
-### 2.4. Streaming Events (`message/stream`, `tasks/resubscribe`)
-
-When using a streaming method, the server sends a sequence of JSON-RPC 2.0 response objects. The `result` field of each response object will contain one of the following payload types:
--   **`Task`:** The initial state of the newly created task. Sent as the first event in a new task stream.
--   **`Message`:** An immediate, self-contained message from the agent.
--   **`TaskStatusUpdateEvent`:** Signals a change in the task's lifecycle state (e.g., `working`, `completed`). A final event is marked with `final: true`.
--   **`TaskArtifactUpdateEvent`:** Delivers a new or updated `Artifact` generated by the task, which can be sent in chunks.
+- **`message/send`:** (Request/Response)
+    - Sends a message to initiate or continue a task.
+    - `params`: `MessageSendParams` (includes `taskId`, `contextId`, `message`, optionally `configuration`).
+    - `result`: `Task` (final state after synchronous processing).
+- **`message/stream`:** (Request/Stream)
+    - Sends a message and subscribes to real-time updates via Server-Sent Events (SSE).
+    - `params`: `MessageSendParams`.
+    - `result` (stream events): `SendStreamingMessageResponse` containing one of: `MessageEvent`, `TaskStatusUpdateEvent`, `TaskArtifactUpdateEvent`. Final event has `final: true`.
+- **`tasks/get`:** (Request/Response)
+    - Retrieves the current state of a task.
+    - `params`: `TaskQueryParams` (includes `id`, optionally `historyLength`).
+    - `result`: `Task`.
+- **`tasks/list`:** (Request/Response)
+    - Retrieves a list of tasks with optional filtering and pagination.
+    - `params`: `ListTasksParams` (optional: `contextId`, `status`, `pageSize`, `pageToken`, `historyLength`, `lastUpdatedAfter`, `includeArtifacts`, `metadata`).
+    - `result`: `ListTasksResult` (includes `tasks[]`, `totalSize`, `pageSize`, `nextPageToken`).
+- **`tasks/cancel`:** (Request/Response)
+    - Requests cancellation of a running task.
+    - `params`: `TaskIdParams` (includes `id`).
+    - `result`: `Task` (updated state, likely 'canceled') or error if not cancelable.
+- **`tasks/pushNotificationConfig/set`:** (Request/Response)
+    - Sets or updates the push notification configuration for a task.
+    - `params`: `TaskPushNotificationConfig`.
+    - `result`: `TaskPushNotificationConfig` (confirmed configuration).
+- **`tasks/pushNotificationConfig/get`:** (Request/Response)
+    - Retrieves the current push notification configuration for a task.
+    - `params`: `TaskIdParams` (includes `taskId`).
+    - `result`: `TaskPushNotificationConfig`.
+- **`tasks/resubscribe`:** (Request/Stream)
+    - Resubscribes to task updates after a connection interruption (SSE).
+    - `params`: `TaskQueryParams`.
+    - `result` (stream events): `TaskStatusUpdateEvent` or `TaskArtifactUpdateEvent`.
+
+### 2.4. Streaming Update Events (Result of `message/stream` or `tasks/resubscribe`)
+
+- **`SendStreamingMessageResponse`:** Contains a message from the agent.
+    - `type`: "message"
+    - `message`: (`Message`) The message content.
+    - `contextId`: (string) Context identifier the message is associated with.
+    - `kind`: ("streaming-response") Type discriminator.
+    - `final`: (boolean) True if this is the final message for the task.
+- **`TaskStatusUpdateEvent`:** Signals a change in task status.
+    - `type`: "task-status"
+    - `taskId`: (string) Task ID.
+    - `contextId`: (string) Context identifier the task is associated with.
+    - `kind`: ("status-update") Type discriminator.
+    - `status`: (`TaskStatus`) The new status object.
+    - `final`: (boolean) True if this is the terminal update for the task.
+- **`TaskArtifactUpdateEvent`:** Signals a new or updated artifact.
+    - `type`: "task-artifact"
+    - `taskId`: (string) Task ID.
+    - `artifact`: (`Artifact`) The artifact data.
+    - `append`: (boolean) If true, append parts to artifact; if false (default), replace.
+    - `lastChunk`: (boolean) If true, indicates this is the final update for the artifact.
+    - `final`: (boolean) Usually false for artifacts, can signal end concurrently with status.
 
 ### 2.5. Standard Error Codes