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

Task helpers for tool authors.

Helper module over the standard tool ctx map (`OzMcp.Context.ctx()`).
There is no struct: the tool's single `ctx` argument IS the channel —
a tool has exactly one mandatory callback, `call(ctx, params)`. A
task-backed execution carries a non-nil `ctx.task_id`; a plain
synchronous call carries `task_id: nil` and every helper here returns
`{:error, :not_a_task}` without sending anything.

A task can also send a log message to its client with
`OzMcp.Notify.log(ctx, level, data)`: the message carries the
`io.modelcontextprotocol/related-task` `_meta` and goes to the owner
of the task — each open `tasks/result` stream of the task, else every
session of the owner. Each receiving session applies its own level.

## The dual-mode pattern

One tool handles BOTH execution modes through the same callback:

  * **task-backed** — progress/status helpers route through the task
    record; the progress token is owned by the task (captured at
    creation from the request `_meta.progressToken`), tools never
    pass it.
  * **plain synchronous** — `ctx.task_id` is nil; progress with a
    client-requested token goes through `ctx.progress_token` and
    `OzMcp.Notify.progress/5`.

    ```elixir
    def call(ctx, params) do
      total = 10

      for i <- 1..total do
        run_step(i)
        report(ctx, i, total)
      end

      {:ok, %CallToolResult{} |> CallToolResult.build()}
    end

    defp report(ctx, i, total) do
      cond do
        ctx.task_id != nil ->
          OzMcp.Tasks.Context.progress(ctx, i, total, "step #{i}")

        ctx.progress_token != nil ->
          OzMcp.Notify.progress(ctx.instance, ctx.session_id, ctx.progress_token, i,
            total: total, message: "step #{i}"
          )

        true ->
          :ok
      end
    end
    ```

# `ctx`

```elixir
@type ctx() :: OzMcp.Context.ctx()
```

# `progress`

```elixir
@spec progress(ctx(), number(), number() | nil, term()) ::
  :ok | {:error, :not_a_task | :not_encodable | :unavailable}
```

Emits notifications/progress for the task. The progress token is owned
by the task record (captured at creation); tools never pass it here.
This call and `OzMcp.Notify.progress/3` with the ctx of a task are the
same: both call OzMcp.Tasks.progress/5.

The `progress` value must increase with each call for the same token;
a value that does not is dropped (`:ok`, the client gets nothing, a
debug line is written). The first value can be any number; a value
that is not a number is not checked.

Returns `{:error, :not_a_task}` when `ctx.task_id` is nil,
`{:error, :not_encodable}` when a value holds a term that JSON cannot
encode and `{:error, :unavailable}` when the instance does not run.

# `status_message`

```elixir
@spec status_message(ctx(), String.t()) ::
  :ok | {:error, :not_a_task | :not_encodable | :unavailable}
```

Sets/updates the statusMessage without changing the status.

Returns `{:error, :not_a_task}` when `ctx.task_id` is nil and
`{:error, :not_encodable}` when the message is a text that JSON cannot
encode (a string that is not valid UTF-8, or a term that is not a
string): the task keeps its old message. `{:error, :unavailable}` means
that the instance does not run.

---

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