The tasks of an instance (MCP 2025-11-25, "Tasks").
Each function takes the instance as its first argument. A call that
cannot get an answer gives {:error, :unavailable} (the instance is
not running, or the process of the tasks exited) or
{:error, :timeout} (no answer in time). A task that does not exist,
or that belongs to another owner, gives {:error, :no_task}.
The owner of a task is the principal that created it, or its session
when the server has no authorization (see owner_key/1). The sessions
of one principal see the same tasks.
Summary
Types
The limit that refused a create: the name of the runtime option and
the value of :limit in the telemetry event [:limit, :reached].
Functions
Waits for the outcome of a task with no time limit: the wait ends at a terminal status, at the expiry of the task, or at the end of the session.
Waits for the outcome of a task, with a limit of time.
Cancels a task: its runner stops, its status becomes cancelled. A
task that is already terminal gives {:error, {:terminal, status}}.
Starts a task: the tool of a task-augmented tools/call runs in a
supervised runner, owned by a task process.
Reads a task.
The tasks of an owner, oldest first, with the cursor of the next page
(nil on the last page). The cursor is the opaque cursor of the previous
page (nil for the first page). The limit is a number of tasks (nil for
the page size of the instance). The page skips the expired records. A
broken cursor gives {:error, :invalid_cursor}.
The owner key of the tasks of a request: the key of the principal, or the session id.
Reads the record of a task of an owner. Nothing changes: an expired
record is reported but not removed. The scope stage of the pipeline
reads the required_scopes of the record.
Types
@type error() :: {:error, :no_task | :unavailable | :timeout | term()}
@type limit() ::
:max_tasks_per_session
| :max_tasks_per_principal
| :max_task_records_per_owner
| :max_task_bytes_per_owner
The limit that refused a create: the name of the runtime option and
the value of :limit in the telemetry event [:limit, :reached].
Functions
@spec await(OzMcp.Instance.t(), term(), String.t()) :: {:ok, term()} | error()
Waits for the outcome of a task with no time limit: the wait ends at a terminal status, at the expiry of the task, or at the end of the session.
Waits for the outcome of a task, with a limit of time.
timeout is a number of milliseconds, or nil for no limit (the same
as await/3). Gives {:error, :timeout} when the limit passes. The
result of a cancelled task is the same error that tasks/result gives
(-32800, "task was cancelled").
@spec cancel(OzMcp.Instance.t(), term(), String.t()) :: {:ok, OzMcp.Structs.Task.t()} | error()
Cancels a task: its runner stops, its status becomes cancelled. A
task that is already terminal gives {:error, {:terminal, status}}.
@spec create(OzMcp.Instance.t(), map()) :: {:ok, OzMcp.Structs.Task.t()} | {:error, {:too_many_tasks, limit()}} | error()
Starts a task: the tool of a task-augmented tools/call runs in a
supervised runner, owned by a task process.
The attributes carry :session_id, :tool (a {module, name} tuple)
and :request (required only for a task that starts a runner).
Optional keys: :ttl, :progress_token, :client_capabilities,
:principal, :required_scopes, :output_schema, :poll_interval
(the hint the tool's execution declares; the instance option
task_poll_interval_ms is the default) and :settled (a task
terminal at creation has no process and no status notification). A
create refused by a limit gives {:error, {:too_many_tasks, limit}},
with limit the name of the refusing option.
@spec get(OzMcp.Instance.t(), term(), String.t()) :: {:ok, OzMcp.Structs.Task.t()} | error()
Reads a task.
@spec list( OzMcp.Instance.t(), term(), String.t() | nil, pos_integer() | nil, OzMcp.Auth.Principal.t() | nil ) :: {:ok, [OzMcp.Structs.Task.t()], String.t() | nil} | error()
The tasks of an owner, oldest first, with the cursor of the next page
(nil on the last page). The cursor is the opaque cursor of the previous
page (nil for the first page). The limit is a number of tasks (nil for
the page size of the instance). The page skips the expired records. A
broken cursor gives {:error, :invalid_cursor}.
With a principal, the page holds only the tasks whose scopes the
principal holds and it reads more records until it has limit
visible tasks or the index ends. No principal (an open server) shows
every task.
@spec owner_key(%{ :principal => OzMcp.Auth.Principal.t() | nil, optional(:session_id) => String.t() | nil, optional(atom()) => term() }) :: term()
The owner key of the tasks of a request: the key of the principal, or the session id.
@spec peek(OzMcp.Instance.t(), term(), String.t()) :: {:ok, OzMcp.Tasks.EtsStore.t()} | error()
Reads the record of a task of an owner. Nothing changes: an expired
record is reported but not removed. The scope stage of the pipeline
reads the required_scopes of the record.