SEP-1686 (experimental): Implement Tasks

[findleyr]

Add support for SEP-1686, when it lands.

[jba]

Tasks pose a challenge for backwards compatibility. A tool call can now return its usual result, or a CreateTaskResult.

One way to deal with this would be to have separate functions and types on the server for registering a tool that might be a task. The handler's return type would be some union of CallToolResult and CreateTaskResult. We'd also need a separate function on the client.

A better idea, although it's a bit ugly, is to add a CreateTaskResult field to CallToolResult. When a tool is called as a task, it sets this field and leaves all the others empty. Callers of ClientSession.CallTool would have to recognize that state. Maybe we could have ClientSession.CallToolAsTask that returns a CreateTaskResult – no union type is needed on the client side. But that method would not be able to mark the call as being a task call: that bit is set in the call's params (arguments), not its metadata (see https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1732/files#r2524912400 for my failed pushback). In our SDK, CallToolParams.Arguments is an any, so we can't easily look at it. (One hideous possibility: we require that the arguments marshal to JSON, so we could marshal, unmarshal into a map[string]any, and set the task info.) We may be able to do better on the server side, recognizing that a call is a task call, because we already unmarshal into a map[string]any.

[LucaButBoring]

Relaying here from #general-sdk-dev:

There doesn't seem to be a central ticket for all SDK implementations of a particular change, so sharing this here for SEP-1686 -- the following revisions have been merged on top of the base specification PR for tasks:

• Clarify request lifetimes in task diagrams: PR
• Fix capability phrasing in spec: PR
• Remove an incorrectly-added field from notifications/cancelled: PR
• Adjust schema to better-communicate where tasks are valid: PR
• Rename/move annotations.taskHint to execution.taskSupport, tweak its enum values, and change a SHOULD to a MUST for the behavior when this is declared:
  • PR 1
  • PR 2
• GetTask polling clarification: PR
• SSE stream management clarification: PR

The actual functional changes should be limited to taskHint, but the rest should help clarify some details around polling.

To save the trouble of going through each of the above PRs one by one, you can also go to the file on the "Files changed" tab here, searching for docs/specification/draft/basic/utilities/tasks.mdx, and then using the "Display the rich diff" button, as shown:

[LucaButBoring]

One very last change (we're doing a hard cutoff on additional changes here): adding a lastUpdatedAt to the Task object: modelcontextprotocol/modelcontextprotocol#1875

[findleyr]

Given the number of changes here, and the fact that this is still experimental, we probably won't get to this until next week. My hope is that it still makes it into the next release.

[He-Pin]

@jba modelcontextprotocol/java-sdk#671 yes

[findleyr]

Unfortunately, I don't think this is going to make v1.2.0, for which we want a prerelease this week.

Since this is an experimental feature, that may be acceptable. However, we should land this in master shortly after cutting the release.