Skip to content

Commit 726a4db

Browse files
committed
Add tasks/delete operation
1 parent cd7c4cd commit 726a4db

File tree

4 files changed

+209
-9
lines changed

4 files changed

+209
-9
lines changed

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

Lines changed: 93 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -266,6 +266,44 @@ To retrieve a list of tasks, requestors send a `tasks/list` request. This operat
266266
}
267267
```
268268

269+
### Deleting Tasks
270+
271+
To explicitly delete a task and its associated results, requestors send a `tasks/delete` request.
272+
273+
**Request:**
274+
275+
```json
276+
{
277+
"jsonrpc": "2.0",
278+
"id": 6,
279+
"method": "tasks/delete",
280+
"params": {
281+
"taskId": "786512e2-9e0d-44bd-8f29-789f320fe840",
282+
"_meta": {
283+
"modelcontextprotocol.io/related-task": {
284+
"taskId": "786512e2-9e0d-44bd-8f29-789f320fe840"
285+
}
286+
}
287+
}
288+
}
289+
```
290+
291+
**Response:**
292+
293+
```json
294+
{
295+
"jsonrpc": "2.0",
296+
"id": 6,
297+
"result": {
298+
"_meta": {
299+
"modelcontextprotocol.io/related-task": {
300+
"taskId": "786512e2-9e0d-44bd-8f29-789f320fe840"
301+
}
302+
}
303+
}
304+
}
305+
```
306+
269307
## Behavior Requirements
270308

271309
These requirements apply to all parties that support receiving task-augmented requests.
@@ -359,6 +397,13 @@ stateDiagram-v2
359397
1. Requestors **MUST** treat cursors as opaque tokens and not attempt to parse or modify them.
360398
1. If a task is retrievable via `tasks/get` for a requestor, it **MUST** be retrievable via `tasks/list` for that requestor.
361399

400+
### Task Deletion
401+
402+
1. Receivers **MAY** accept or reject delete requests for any task at their discretion.
403+
1. If a receiver accepts a delete request, it **SHOULD** delete the task and all associated results and metadata.
404+
1. Receivers **MAY** choose not to support deletion at all, or only support deletion for tasks in certain statuses (e.g., only terminal statuses).
405+
1. Requestors **SHOULD** delete tasks containing sensitive data promptly rather than relying solely on `keepAlive` expiration for cleanup.
406+
362407
## Message Flow
363408

364409
### Basic Task Lifecycle
@@ -525,6 +570,36 @@ sequenceDiagram
525570
Note over S: After keepAlive period, task cleaned up
526571
```
527572

573+
### Task Deletion Flow
574+
575+
```mermaid
576+
sequenceDiagram
577+
participant C as Client (Requestor)
578+
participant S as Server (Receiver)
579+
580+
Note over C,S: 1. Task Creation and Completion
581+
C->>S: tools/call (task-123)
582+
S--)C: notifications/tasks/created
583+
Note over S: Task processing...
584+
C->>S: tasks/get (task-123)
585+
S->>C: completed
586+
587+
Note over C,S: 2. Result Retrieval
588+
C->>S: tasks/result (task-123)
589+
S->>C: Result content
590+
591+
Note over C,S: 3. Explicit Deletion
592+
Note over C: Client decides to clean up task
593+
C->>S: tasks/delete (task-123)
594+
S->>C: Success (empty result)
595+
596+
Note over S: Task and results immediately deleted
597+
598+
Note over C,S: 4. Verification (optional)
599+
C->>S: tasks/get (task-123)
600+
S->>C: Error: Task not found
601+
```
602+
528603
## Data Types
529604

530605
### Task
@@ -590,10 +665,11 @@ Tasks use two error reporting mechanisms:
590665

591666
Receivers **MUST** return standard JSON-RPC errors for the following protocol error cases:
592667

593-
- Invalid or nonexistent `taskId` in `tasks/get`, `tasks/list`, or `tasks/result`: `-32602` (Invalid params)
668+
- Invalid or nonexistent `taskId` in `tasks/get`, `tasks/list`, `tasks/result`, or `tasks/delete`: `-32602` (Invalid params)
594669
- Invalid or nonexistent cursor in `tasks/list`: `-32602` (Invalid params)
595670
- Request with a `taskId` that was already used for a different task (if the receiver validates task ID uniqueness): `-32602` (Invalid params)
596671
- Attempting to retrieve result when task is not in `completed` status: `-32602` (Invalid params)
672+
- Receiver rejects a `tasks/delete` request: `-32600` (Invalid request)
597673
- Internal errors: `-32603` (Internal error)
598674

599675
Receivers **SHOULD** provide informative error messages to describe the cause of errors.
@@ -656,6 +732,19 @@ Receivers are not obligated to retain task metadata indefinitely. It is complian
656732
}
657733
```
658734

735+
**Example: Task deletion rejected by receiver**
736+
737+
```json
738+
{
739+
"jsonrpc": "2.0",
740+
"id": 74,
741+
"error": {
742+
"code": -32600,
743+
"message": "Task deletion not supported for tasks in 'working' status"
744+
}
745+
}
746+
```
747+
659748
### Task Execution Errors
660749

661750
When the underlying request fails during execution, the task moves to the `failed` status. The `tasks/get` response **SHOULD** include an `error` field with details about the failure.
@@ -684,19 +773,20 @@ For tasks that wrap requests with their own error semantics (like `tools/call` w
684773
1. Receivers **SHOULD** scope task IDs to prevent unauthorized access:
685774
1. Bind tasks to the session that created them (if sessions are supported)
686775
1. Bind tasks to the authentication context (if authentication is used)
687-
1. Reject `tasks/get`, `tasks/list`, or `tasks/result` requests for tasks from different sessions or auth contexts
776+
1. Reject `tasks/get`, `tasks/list`, `tasks/result`, or `tasks/delete` requests for tasks from different sessions or auth contexts
688777
1. Receivers that do not implement session or authentication binding **SHOULD** document this limitation clearly, as task results may be accessible to any requestor that can guess the task ID.
689778
1. Receivers **SHOULD** implement rate limiting on:
690779
1. Task creation to prevent resource exhaustion
691780
1. Task status polling to prevent denial of service
692781
1. Task result retrieval attempts
693782
1. Task listing requests to prevent denial of service
783+
1. Task deletion requests to prevent abuse
694784

695785
### Resource Management
696786

697787
<Warning>
698788

699-
Task results may persist longer than the original request execution time. For sensitive operations, requestors should carefully consider the security implications of extended result retention and may want to retrieve results promptly and request shorter `keepAlive` durations.
789+
Task results may persist longer than the original request execution time. For sensitive operations, requestors should carefully consider the security implications of extended result retention and may want to retrieve results promptly and request shorter `keepAlive` durations. Requestors are encouraged to use `tasks/delete` to explicitly clean up tasks containing sensitive data rather than relying solely on `keepAlive` expiration.
700790

701791
</Warning>
702792

0 commit comments

Comments
 (0)