Skip to content

Commit 8169347

Browse files
committed
Update cancellation to reflect CreateTaskResult semantics
1 parent dbc2b0a commit 8169347

File tree

5 files changed

+79
-22
lines changed

5 files changed

+79
-22
lines changed

docs/specification/draft/basic/utilities/cancellation.mdx

Lines changed: 39 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -15,9 +15,12 @@ indicate that a previously-issued request should be terminated.
1515
When a party wants to cancel an in-progress request, it sends a `notifications/cancelled`
1616
notification containing:
1717

18-
- The ID of the request to cancel
18+
- For non-task requests: The ID of the request to cancel
19+
- For task cancellation: The ID of the task to cancel
1920
- An optional reason string that can be logged or displayed
2021

22+
### Cancelling Non-Task Requests
23+
2124
```json
2225
{
2326
"jsonrpc": "2.0",
@@ -29,23 +32,49 @@ notification containing:
2932
}
3033
```
3134

35+
### Cancelling Tasks
36+
37+
For task-augmented requests, once the `CreateTaskResult` is returned, the original request is complete and `requestId` becomes ambiguous. Therefore, task cancellation **MUST** use `taskId`:
38+
39+
```json
40+
{
41+
"jsonrpc": "2.0",
42+
"method": "notifications/cancelled",
43+
"params": {
44+
"taskId": "786512e2-9e0d-44bd-8f29-789f320fe840",
45+
"reason": "User requested cancellation"
46+
}
47+
}
48+
```
49+
3250
## Behavior Requirements
3351

34-
1. Cancellation notifications **MUST** only reference requests that:
52+
### General Requirements
53+
54+
1. Cancellation notifications **MUST** only reference requests or tasks that:
3555
- Were previously issued in the same direction
3656
- Are believed to still be in-progress
3757
2. The `initialize` request **MUST NOT** be cancelled by clients
3858
3. Receivers of cancellation notifications **SHOULD**:
39-
- Stop processing the cancelled request
59+
- Stop processing the cancelled request or task
4060
- Free associated resources
41-
- Not send a response for the cancelled request
61+
- For non-task requests: Not send a response for the cancelled request
62+
- For tasks: Move the task to `cancelled` status
4263
4. Receivers **MAY** ignore cancellation notifications if:
43-
- The referenced request is unknown
44-
- Processing has already completed
45-
- The request cannot be cancelled
64+
- The referenced request or task is unknown
65+
- Processing has already completed (for non-task requests) or reached a terminal status (for tasks)
66+
- The request or task cannot be cancelled
4667
5. The sender of the cancellation notification **SHOULD** ignore any response to the
4768
request that arrives afterward
4869

70+
### Task-Specific Requirements
71+
72+
1. For task cancellation, `taskId` **MUST** be provided (not `requestId`)
73+
2. `requestId` **MUST NOT** be used for task cancellation once `CreateTaskResult` has been returned
74+
3. When a receiver receives a `notifications/cancelled` notification with a `taskId`, it **SHOULD** immediately move the task to `cancelled` status
75+
4. If a cancellation notification arrives after a task has already reached a terminal status (`completed`, `failed`, or `cancelled`), receivers **SHOULD** ignore the notification
76+
5. Requestors **SHOULD** poll with `tasks/get` after sending a cancellation notification to confirm the task has transitioned to `cancelled` status
77+
4978
## Timing Considerations
5079

5180
Due to network latency, cancellation notifications may arrive after request processing
@@ -77,9 +106,10 @@ sequenceDiagram
77106

78107
Invalid cancellation notifications **SHOULD** be ignored:
79108

80-
- Unknown request IDs
81-
- Already completed requests
109+
- Unknown request IDs or task IDs
110+
- Already completed requests or tasks in terminal status
82111
- Malformed notifications
112+
- Using `requestId` for task cancellation (should use `taskId` instead)
83113

84114
This maintains the "fire and forget" nature of notifications while allowing for race
85115
conditions in asynchronous communication.

docs/specification/draft/basic/utilities/tasks.mdx

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -420,7 +420,10 @@ stateDiagram-v2
420420
### Task Cancellation
421421

422422
1. Requestors **MAY** send `notifications/cancelled` at any time during task execution.
423-
1. When a receiver receives a `notifications/cancelled` notification for the JSON-RPC request ID of a task-augmented request, the receiver **SHOULD** immediately move the task to the `cancelled` status and cease all processing associated with that task.
423+
1. For task cancellation, the `notifications/cancelled` notification **MUST** include a `taskId` field:
424+
1. The `taskId` **MUST** correspond to a task previously created in the same direction.
425+
1. Once a task-augmented request returns `CreateTaskResult`, the original request is complete and `requestId` becomes ambiguous. Therefore, `requestId` **MUST NOT** be used for task cancellation.
426+
1. When a receiver receives a `notifications/cancelled` notification with a `taskId`, the receiver **SHOULD** immediately move the task to the `cancelled` status and cease all processing associated with that task.
424427
1. Due to the asynchronous nature of notifications, receivers **MAY** not cancel task processing instantaneously. Receivers **SHOULD** make a best-effort attempt to halt execution as quickly as possible.
425428
1. If a `notifications/cancelled` notification arrives after a task has already reached a terminal status (`completed`, `failed`, or `cancelled`), receivers **SHOULD** ignore the notification.
426429
1. After a task reaches `cancelled` status and its `keepAlive` duration has elapsed, receivers **MAY** delete the task and its metadata.
@@ -590,7 +593,7 @@ sequenceDiagram
590593
591594
Note over C,S: 3. Client Cancellation
592595
Note over C: User requests cancellation
593-
C--)S: notifications/cancelled (requestId: 42)
596+
C--)S: notifications/cancelled (taskId: task-123)
594597
595598
Note over S: Server processes cancellation
596599
Note over S: Task moves to cancelled status

docs/specification/draft/schema.mdx

Lines changed: 8 additions & 2 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)