Skip to content

Commit 29fffbc

Browse files
committed
Make notifications include full task info
1 parent 6bcfab5 commit 29fffbc

File tree

4 files changed

+66
-87
lines changed

4 files changed

+66
-87
lines changed

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

Lines changed: 30 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -220,7 +220,7 @@ To retrieve the result of a completed task, requestors send a `tasks/result` req
220220

221221
### Task Creation Notification
222222

223-
When a receiver creates a task, it **MUST** send a `notifications/tasks/created` notification to inform the requestor that the task has been created and polling can begin.
223+
When a receiver creates a task, it **MAY** send a `notifications/tasks/created` notification to inform the requestor that the task has been created and polling can begin. This notification includes the full task state.
224224

225225
**Notification:**
226226

@@ -229,6 +229,12 @@ When a receiver creates a task, it **MUST** send a `notifications/tasks/created`
229229
"jsonrpc": "2.0",
230230
"method": "notifications/tasks/created",
231231
"params": {
232+
"taskId": "786512e2-9e0d-44bd-8f29-789f320fe840",
233+
"status": "working",
234+
"statusMessage": "The operation is now in progress.",
235+
"createdAt": "2025-11-25T10:30:00Z",
236+
"ttl": 60000,
237+
"pollInterval": 5000,
232238
"_meta": {
233239
"modelcontextprotocol.io/related-task": {
234240
"taskId": "786512e2-9e0d-44bd-8f29-789f320fe840"
@@ -238,15 +244,13 @@ When a receiver creates a task, it **MUST** send a `notifications/tasks/created`
238244
}
239245
```
240246

241-
The task ID is conveyed through the `modelcontextprotocol.io/related-task` metadata key. The notification parameters are otherwise empty.
247+
The notification includes the full `Task` object with all task metadata fields, allowing requestors to immediately access the task state without making an additional `tasks/get` request.
242248

243-
This notification resolves the race condition where a requestor might attempt to poll for a task before the receiver has finished creating it. By sending this notification immediately after task creation, the receiver signals that the task is ready to be queried via `tasks/get`.
244-
245-
Receivers that do not support tasks (and thus ignore task metadata in requests) will not send this notification, allowing requestors to fall back to waiting for the original request response.
249+
Requestors **MUST NOT** rely on receiving this notification. Requestors **SHOULD** be prepared to begin polling via `tasks/get` immediately after receiving the `CreateTaskResult` response, regardless of whether this notification is received.
246250

247251
### Task Status Notification
248252

249-
When a task's status changes, receivers **MAY** send a `notifications/tasks/status` notification to inform the requestor of the change.
253+
When a task's status changes, receivers **MAY** send a `notifications/tasks/status` notification to inform the requestor of the change. This notification includes the full task state.
250254

251255
**Notification:**
252256

@@ -255,7 +259,11 @@ When a task's status changes, receivers **MAY** send a `notifications/tasks/stat
255259
"jsonrpc": "2.0",
256260
"method": "notifications/tasks/status",
257261
"params": {
262+
"taskId": "786512e2-9e0d-44bd-8f29-789f320fe840",
258263
"status": "completed",
264+
"createdAt": "2025-11-25T10:30:00Z",
265+
"ttl": 60000,
266+
"pollInterval": 5000,
259267
"_meta": {
260268
"modelcontextprotocol.io/related-task": {
261269
"taskId": "786512e2-9e0d-44bd-8f29-789f320fe840"
@@ -265,12 +273,7 @@ When a task's status changes, receivers **MAY** send a `notifications/tasks/stat
265273
}
266274
```
267275

268-
The notification includes:
269-
270-
- `status`: The new task status
271-
- `error` (optional): Error message if the status is `failed`
272-
273-
The task ID is conveyed through the `modelcontextprotocol.io/related-task` metadata key.
276+
The notification includes the full `Task` object with all task metadata fields, including the updated `status`, `statusMessage` (if present), and `error` (if the status is `failed`). This allows requestors to access the complete task state without making an additional `tasks/get` request.
274277

275278
Requestors **MUST NOT** rely on receiving these notifications, as they are optional. Receivers are not required to send status notifications and may choose to only send them for certain status transitions. Requestors **SHOULD** continue to poll via `tasks/get` to ensure they receive status updates.
276279

@@ -430,6 +433,13 @@ stateDiagram-v2
430433
1. For example, an elicitation that a task-augmented tool call depends on **MUST** share the same related task ID with that tool call's task.
431434
1. For the `tasks/get`, `tasks/list`, `tasks/result`, and `tasks/cancel` operations, the `taskId` parameter in the request **MUST** be used as the source of truth for identifying the target task. Requestors **SHOULD NOT** include `modelcontextprotocol.io/related-task` metadata in these requests, and receivers **MUST** ignore such metadata if present in favor of the RPC method parameter.
432435

436+
### Task Notifications
437+
438+
1. Receivers **MAY** send a `notifications/tasks/created` notification after creating a task to inform the requestor that the task is ready for polling.
439+
1. Receivers **MAY** send `notifications/tasks/status` notifications when a task's status changes.
440+
1. Requestors **MUST NOT** rely on receiving either notification type, as they are both optional.
441+
1. When sent, these notifications **MUST** include the `modelcontextprotocol.io/related-task` metadata as described in "Associating Task-Related Messages".
442+
433443
### Task Progress Notifications
434444

435445
Task-augmented requests support progress notifications as defined in the progress notification specification. The `progressToken` provided in the initial request remains valid throughout the task's lifetime.
@@ -458,9 +468,9 @@ sequenceDiagram
458468
participant C as Client (Requestor)
459469
participant S as Server (Receiver)
460470
Note over C,S: 1. Task Creation
461-
C->>S: Request with task metadata (taskId, ttl)
471+
C->>S: Request with task metadata (ttl)
462472
S->>C: CreateTaskResult (taskId, status: working, ttl, pollInterval)
463-
S--)C: notifications/tasks/created
473+
S--)C: notifications/tasks/created (full Task)
464474
Note over C,S: 2. Task Polling
465475
C->>S: tasks/get (taskId)
466476
S->>C: working
@@ -490,9 +500,9 @@ sequenceDiagram
490500
LLM->>C: Request operation
491501
492502
Note over C,S: Client augments with task metadata
493-
C->>S: tools/call (task-123, ttl: 3600000)
503+
C->>S: tools/call (ttl: 3600000)
494504
S->>C: CreateTaskResult (task-123, status: working)
495-
S--)C: notifications/tasks/created
505+
S--)C: notifications/tasks/created (task-123, full Task)
496506
497507
Note over LLM,C: Client continues processing other requests<br/>while task executes in background
498508
LLM->>C: Request other operation
@@ -547,9 +557,9 @@ sequenceDiagram
547557
Note over S: Server decides to initiate request
548558
549559
Note over S,C: Server requests client operation (task-augmented)
550-
S->>C: sampling/createMessage (request-789, ttl: 3600000)
560+
S->>C: sampling/createMessage (ttl: 3600000)
551561
C->>S: CreateTaskResult (request-789, status: working)
552-
C--)S: notifications/tasks/created
562+
C--)S: notifications/tasks/created (request-789, full Task)
553563
554564
Note over S: Server continues processing<br/>while waiting for result
555565
@@ -590,9 +600,9 @@ sequenceDiagram
590600
participant S as Server (Receiver)
591601
592602
Note over C,S: 1. Task Creation
593-
C->>S: tools/call (request ID: 42, task-123)
603+
C->>S: tools/call (request ID: 42, ttl: 60000)
594604
S->>C: CreateTaskResult (task-123, status: working)
595-
S--)C: notifications/tasks/created
605+
S--)C: notifications/tasks/created (task-123, full Task)
596606
597607
Note over C,S: 2. Task Processing
598608
C->>S: tasks/get (task-123)

0 commit comments

Comments
 (0)