yera.tools.mcp.task

Public lifecycle values for MCP tasks.

Symbols

class MCPTask — Represent an immediate or server-backed MCP tool execution.
class MCPTaskState — Describe one observed state of a server-backed MCP task.

MCPTask

Inherits: Generic[ResultT]

Represent an immediate or server-backed MCP tool execution.

Methods

__init__ — Create a task handle from its current state.
async_refresh — Refresh and return the latest server-reported task state.
async_cancel — Cancel this server-backed task and return its resulting state.
async_update — Submit requested input and return the resulting task state.
async_wait — Wait for completion and return the converted tool result.
refresh — Refresh and return the latest server-reported task state.
cancel — Cancel this server-backed task and return its resulting state.
update — Submit requested input and return the resulting task state.
wait — Wait synchronously for completion and return the converted result.

MCPTask.__init__

__init__(
    state: MCPTaskState,
    value: object = _MISSING,
    refresh: _TaskRefresher | None = None,
    update: _TaskUpdater | None = None,
    cancel: _TaskCanceller | None = None,
) → None

Create a task handle from its current state.

Parameters

state
type: MCPTaskState

Most recently observed task lifecycle state.

value
type: object = _MISSING

Converted result for an already-completed task.

refresh
type: _TaskRefresher | None = None

Operation used to retrieve updated server task state.

update
type: _TaskUpdater | None = None

Operation used to submit requested task input.

cancel
type: _TaskCanceller | None = None

Operation used to request server-side cancellation.

MCPTask.async_refresh

async_refresh() → MCPTaskState

Refresh and return the latest server-reported task state.

Returns

type: MCPTaskState

The latest immutable task state. Immediate tasks retain their completed local state.

Raises

RuntimeError

If a server-backed task has no refresh operation.

MCPTask.async_cancel

async_cancel() → MCPTaskState

Cancel this server-backed task and return its resulting state.

Returns

type: MCPTaskState

The task state observed after the server acknowledges cancellation.

Raises

RuntimeError

If the task is already complete or cannot be cancelled.

MCPTask.async_update

async_update(
    input_responses: InputResponses,
) → MCPTaskState

Submit requested input and return the resulting task state.

Parameters

input_responses
type: InputResponses

Responses keyed by outstanding request identity.

Returns

type: MCPTaskState

The task state observed after the server accepts the responses.

Raises

RuntimeError

If this task is not awaiting input or cannot be updated.

MCPTask.async_wait

async_wait() → ResultT

Wait for completion and return the converted tool result.

Returns

type: ResultT

The converted result of the completed task.

Raises

MCPTaskInputRequiredError

If the task requires user input before it can continue.

RuntimeError

If the task reaches a terminal state without a converted result.

Exception

If the server reports an error while executing the task.

MCPTask.refresh

refresh() → MCPTaskState

Refresh and return the latest server-reported task state.

Returns

type: MCPTaskState

The latest immutable task state.

Raises

RuntimeError

If a server-backed task has no refresh operation or the server returns state for a different task.

MCPTask.cancel

cancel() → MCPTaskState

Cancel this server-backed task and return its resulting state.

Returns

type: MCPTaskState

The task state observed after the server acknowledges cancellation.

Raises

RuntimeError

If the task is already complete or cannot be cancelled.

MCPTask.update

update(
    input_responses: InputResponses,
) → MCPTaskState

Submit requested input and return the resulting task state.

Parameters

input_responses
type: InputResponses

Responses keyed by outstanding request identity.

Returns

type: MCPTaskState

The task state observed after the server accepts the responses.

MCPTask.wait

wait() → ResultT

Wait synchronously for completion and return the converted result.

Returns

type: ResultT

The converted result of the completed task.

Raises

MCPTaskInputRequiredError

If the task requires user input before it can continue.

RuntimeError

If the task reaches a terminal state without a converted result.

Exception

If the server reports an error while executing the task.

MCPTaskState

Describe one observed state of a server-backed MCP task.

Fields

task_id
type: str | None (required)

Stable identifier minted by the MCP server.

status
type: Literal['working', 'input_required', 'completed', 'failed', 'cancelled'] (required)

Current lifecycle status.

status_message
type: str | None (required)

Optional human-readable detail supplied by the server.

created_at
type: datetime.datetime (required)

Time at which the server created the task.

last_updated_at
type: datetime.datetime (required)

Time at which the server last updated the task.

ttl
type: datetime.timedelta | None (required)

Retention duration from creation, or None when unlimited.

poll_interval
type: datetime.timedelta | None (required)

Server-recommended delay between status requests.

Methods


MCPTaskState.__init__

__init__(
    task_id: str | None,
    status: MCPTaskStatus,
    status_message: str | None,
    created_at: datetime,
    last_updated_at: datetime,
    ttl: timedelta | None,
    poll_interval: timedelta | None,
) → None