ExMCP.Tasks.Task (ex_mcp v1.0.0-rc.8)

Task struct and state machine validation for MCP Tasks.

Tasks represent async operations initiated by tool calls. This module provides a pure data structure and state transition validation functions. ExMCP.Tasks and ExMCP.Tasks.Store provide the optional durable lifecycle boundary; the task struct itself does not own a process.

State Machine

Valid states: :working, :input_required, :completed, :failed, :cancelled

Valid transitions:

:working -> :input_required | :completed | :failed | :cancelled
:input_required -> :working | :cancelled
:completed -> (terminal state)
:failed -> (terminal state)
:cancelled -> (terminal state)

Usage

task = ExMCP.Tasks.Task.new("my-tool", %{"arg" => "value"})
{:ok, task} = ExMCP.Tasks.Task.transition(task, :completed)

Summary

Types

state()

t()

Functions

complete(task, result)

Transitions and sets the result (for completed tasks).

fail(task, error_result)

Transitions to failed state with error info.

new(tool_name, arguments \\ %{}, opts \\ [])

Creates a new task in the :working state.

parse_state(other)

Parses a state string to a state atom.

require_input(task, input_requests)

Transitions a task to input_required with outstanding input requests.

states()

Returns all valid states.

terminal?(task)

Checks if the task is in a terminal state.

terminal_states()

Returns all terminal states.

to_map(task)

Converts a task to a map suitable for protocol serialization.

to_map(task, era_or_version)

Converts a task to the wire representation for a protocol era or version.

transition(task, new_state)

Attempts a state transition.

valid_transition?(from, to)

Checks if a transition from one state to another is valid.

Types

state()

@type state() :: :working | :input_required | :completed | :failed | :cancelled

t()

@type t() :: %ExMCP.Tasks.Task{
  arguments: map(),
  created_at: String.t(),
  error: map() | nil,
  id: String.t(),
  input_requests: map() | nil,
  last_updated_at: String.t() | nil,
  metadata: map(),
  poll_interval: integer() | nil,
  result: map() | nil,
  state: state(),
  status_message: String.t() | nil,
  tool_name: String.t(),
  ttl: integer() | nil
}

Functions

complete(task, result)

@spec complete(t(), map()) :: {:ok, t()} | {:error, String.t()}

Transitions and sets the result (for completed tasks).

fail(task, error_result)

@spec fail(t(), map()) :: {:ok, t()} | {:error, String.t()}

Transitions to failed state with error info.

new(tool_name, arguments \\ %{}, opts \\ [])

@spec new(String.t(), map(), keyword()) :: t()

Creates a new task in the :working state.

Parameters

tool_name - Name of the tool this task is executing
arguments - Tool arguments
opts - Optional fields: :id, :ttl, :metadata

parse_state(other)

@spec parse_state(String.t()) :: {:ok, state()} | {:error, String.t()}

Parses a state string to a state atom.

require_input(task, input_requests)

@spec require_input(t(), map()) :: {:ok, t()} | {:error, String.t()}

Transitions a task to input_required with outstanding input requests.

states()

@spec states() :: [state()]

Returns all valid states.

terminal?(task)

@spec terminal?(t()) :: boolean()

Checks if the task is in a terminal state.

terminal_states()

@spec terminal_states() :: [state()]

Returns all terminal states.

to_map(task)

@spec to_map(t()) :: map()

Converts a task to a map suitable for protocol serialization.

to_map(task, era_or_version)

@spec to_map(t(), :legacy | :modern | String.t()) :: map()

Converts a task to the wire representation for a protocol era or version.

transition(task, new_state)

@spec transition(t(), state()) :: {:ok, t()} | {:error, String.t()}

Attempts a state transition.

Returns {:ok, updated_task} if the transition is valid, {:error, reason} if invalid.

valid_transition?(from, to)

@spec valid_transition?(state(), state()) :: boolean()

Checks if a transition from one state to another is valid.