# `OzMcp.Tasks`
[🔗](https://github.com/oz-elixir/oz_mcp/blob/v0.9.0/lib/oz_mcp/tasks.ex#L1)

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.

# `error`

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

# `limit`

```elixir
@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]`.

# `await`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

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

Reads a task.

# `list`

```elixir
@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`

```elixir
@spec owner_key(%{
  :principal =&gt; OzMcp.Auth.Principal.t() | nil,
  optional(:session_id) =&gt; String.t() | nil,
  optional(atom()) =&gt; term()
}) :: term()
```

The owner key of the tasks of a request: the key of the principal, or the session id.

# `peek`

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*
