Client helpers for the Tasks extension, built on Snodo.Client.

Every function here takes a Snodo.Client and sends its requests with Snodo.Client.request/4, Snodo.Client.call_tool/4, and Snodo.Client.listen/3, so it works with any client those functions work with: Snodo.Client.direct/2, stdio, and Streamable HTTP. See "Transports" below for what Streamable HTTP does not carry yet.

{:ok, client} = Snodo.Client.connect({:stdio, "my_server", []})

case Snodo.Extensions.Tasks.Client.call_tool(client, "export", %{"id" => 7}) do
  {:task, status} -> Snodo.Extensions.Tasks.Client.await(client, status)
  {:ok, result} -> {:ok, result}
  {:error, error} -> {:error, error}
end

# or, in one call
Snodo.Extensions.Tasks.Client.call_and_await(client, "export", %{"id" => 7})

Negotiation

The extension is negotiated per request: the client declares extensions["io.modelcontextprotocol/tasks"] in the request's client capabilities, and a server that serves Tasks may then answer a tools/call with a task. Each function here adds that declaration to the requests it sends, through the :meta option of Snodo.Client.request/4, on top of the client's own :client_capabilities. The client does not need to be built with it, and its other requests are unaffected: Snodo.Client.call_tool/4 on the same client still runs a tool the server marks :optional synchronously.

To declare the extension on every request instead, pass capabilities/1 as the client's :client_capabilities. server_supports?/1 reads whether the server advertises the extension.

Outcomes

await/3 and call_and_await/5 return the task's outcome:

• {:ok, result} - the task completed. result is the final CallToolResult map, string keys, as Snodo.Client.call_tool/4 would have returned it for a synchronous call. A result with "isError" => true is a tool that ran and reported its own failure.
• {:error, %Snodo.Error{}} - the task failed, with the server's JSON-RPC error as code, message, and data and the failed Snodo.Extensions.Tasks.Client.Status in cause as {:task_failed, status}; or a request failed, or the wait timed out.
• {:cancelled, status} - the task was cancelled.
• {:input_required, status} - the task is waiting for input this call did not answer. See "Input" below.

Waiting

await/3 polls tasks/get by default. Between polls it waits the task's pollIntervalMs, or :poll_interval when the server sent none, and never less than :min_poll_interval. With listen: true it opens a subscriptions/listen stream for the task instead and waits for notifications/tasks events, reading the status once with tasks/get after the stream is acknowledged so a change made before the stream opened is not missed. A stream that ends before the task does, as one from a source that sends only the current status, is followed by polling. A server without a subscription source refuses subscriptions/listen with -32601, which await/3 returns.

Either way the wait is bounded by :timeout, 60,000 ms unless set. Each request the wait sends gets the time left as its timeout, or :request_timeout (the client's timeout unless set) when that is shorter. A direct client has no request timeout, so there each tasks/get and tasks/update runs in a task that is stopped when the time is up. At the limit await/3 returns -32001 (kind: :transport) with "taskId" and "timeoutMs" in data and {:timeout, status} in cause, where status is the last status read, or nil when none was read. The task keeps running on the server; call await/3 again to keep waiting, or cancel/3.

Three parts of a wait are not cut short at the limit:

• On a direct client, listen: true waits for the stream's acknowledgement without a bound. The stream belongs to the calling process, and the direct transport opens it in that process with no timeout, so it cannot be moved to a task that is stopped at the deadline. Over stdio and Streamable HTTP the acknowledgement is bounded like any other request.
• Closing the stream at the end of a listen: true wait, which Snodo.Client.Subscription.close/1 bounds at 5,000 ms.
• Input handlers and the :input function, which run in the calling process until they return.

Input

A task that needs input reports :input_required with its outstanding requests in input_requests, keyed by the key tasks/update answers them under. await/3 answers them according to :input:

• :handlers (the default) - the client's :input_handlers, the same functions Snodo.Client answers input_required results with. An elicitation/create request goes to the :form or :url handler by its mode (:form when it has none), sampling/createMessage to :sampling, and roots/list to :roots. Each handler receives the request's params and returns {:ok, response}. When a request has no handler for its kind, no handler runs and await/3 returns {:input_required, status}.
• :return - returns {:input_required, status} at once.
• a function of one argument - called with the status, its input_requests limited to the requests not answered yet during this wait, and returns {:ok, responses}, a map from key to response, or {:error, reason}.

The responses are sent with tasks/update and the wait goes on. A handler response is checked as Snodo.Client checks it: an elicitation result needs an "action" of "accept", "decline", or "cancel", a sampling result must pass Snodo.Sampling.valid_response?/1, and a roots result Snodo.Roots.valid_response?/1. A handler or function that returns {:error, reason}, anything other than {:ok, map}, or a handler response that fails its check (reason is {:invalid_response, response}) stops the wait with -32603 (kind: :execution) and cause: {:input_handler, key, reason, status}; key is nil for the function form. An exception raised by a handler or the function propagates to the caller. To answer by hand, call update/4 with the responses and then await/3 again.

Transports

Over Streamable HTTP the server requires an Mcp-Name header that mirrors params.taskId on tasks/get, tasks/update, and tasks/cancel. Snodo.Client's HTTP transport derives the headers it sends from the core protocol dialect, which does not know the extension's methods, so it does not send that header and the server answers -32020. A task-augmented tools/call and subscriptions/listen work over HTTP; the task methods, and therefore await/3, work over Snodo.Client.direct/2 and stdio.