OzMcp.Tasks (OzMcp v0.9.0)

Copy Markdown View Source

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.

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

error()

@type error() :: {:error, :no_task | :unavailable | :timeout | term()}

limit()

@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

await(instance, owner_key, task_id)

@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.

await(instance, owner_key, task_id, timeout)

@spec await(OzMcp.Instance.t(), term(), String.t(), timeout() | nil) ::
  {:ok, term()} | error()

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").

cancel(instance, owner_key, task_id)

@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}}.

create(instance, attrs)

@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.

get(instance, owner_key, task_id)

@spec get(OzMcp.Instance.t(), term(), String.t()) ::
  {:ok, OzMcp.Structs.Task.t()} | error()

Reads a task.

list(instance, owner_key, cursor, limit, principal \\ nil)

@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.

owner_key(map)

@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.

peek(instance, owner_key, task_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.