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

Requests the server sends to the client.

A callback (`tool.call/2`, `resource.read/2`, `prompt.get/2`, a task tool)
can ask the client something while it runs: `ping/2` and the client
features built on `request/4`, which `OzMcp.Client` wraps (sampling,
elicitation, roots). The guide about the requests to the client
describes each method with an example.

`request/4` sends one JSON-RPC request and blocks the calling process
until the client answers, the timeout elapses, or the session ends:

    case OzMcp.Outbound.ping(ctx) do
      {:ok, %{}} -> :alive
      {:error, reason} -> {:unreachable, reason}
    end

## Results

`{:ok, result}` when the client answered (a map). A failure gives one
of these errors: `{:error, {:rpc_error, error}}` (the client answered
with a JSON-RPC error), `{:error, :timeout}`, `{:error,
:session_terminated}`, `{:error, :session_not_found}`,
`{:error, :capability_not_supported}`, `{:error, :unsupported_method}`,
`{:error, :not_encodable}`, `{:error, :no_task}`, `{:error, :no_stream}`
and `{:error, :session_not_initialized}`. `request_task/4` adds
`{:error, :client_tasks_disabled}` (the runtime option `client_tasks`
is `false`, the default), `{:error, {:client_task_cancelled, task_id}}`
and `{:error, {:invalid_response, result}}`. The guide about the
requests to the client gives the meaning of each error and the option
`:wait_for_stream` of the `:no_stream` case.

## Capabilities

Only a method whose capability the client declared is sent: `ping`
needs none, `sampling/createMessage` needs `sampling`,
`elicitation/create` needs `elicitation`, `roots/list` needs `roots`.
Some params need a member of the capability: a `task` key needs the
task capability of the method, the modes of `elicitation/create` need
`elicitation.form` or `elicitation.url` and sampling with `tools`,
`toolChoice` or `includeContext` needs `sampling.tools` or
`sampling.context`. The guide about the requests to the client gives
the table. The three `tasks/*` methods are internal to the flow of a
client task (see `OzMcp.Client`): a callback does not send them.

## Where the request travels

The callback runs for a `POST` request, as a task, or outside a
request. A callback of a `POST` request writes the request on the
response of that `POST`, which becomes an event stream (see
OzMcp.PostStream). A callback that runs as a task
(`ctx.task_id` is set) writes the request on the `tasks/result`
streams of the task and the task is `input_required` while it waits.
In every other case the request travels on the `GET` stream of the
session and waits in the event log of the session until a stream
delivers it. The guide about the requests to the client describes each
way and the timeout of each method.

The client answers with a `POST` that carries a JSON-RPC response. The
router hands the answer to the waiting process with `deliver/2`: an
answer for a request of a task goes to the process of the task, by the
owner of the task. Any session of the owner can answer; an answer on a
session that does not own the task is ignored.

## Pending requests

A pending request of a session lives in the process of the session:
the session gives each one its id, routes its messages and hands the
answer to the process that waits. The end of the session process ends
each wait and a callback that is cancelled, stopped at its deadline
or killed leaves no pending request: the client receives
`notifications/cancelled` for it. A late answer for an unknown request
id is ignored. The request id is generated by the server and is unique
in the session; a client can answer only the requests of its own
session.

## Telemetry

Each call of `request/4` gives one `client_request` span of the events
of `:telemetry`. The guide about the telemetry describes the events.

# `ctx`

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

# `error`

```elixir
@type error() ::
  {:rpc_error, map()}
  | :timeout
  | :session_terminated
  | :session_not_found
  | :no_stream
  | :session_not_initialized
  | :capability_not_supported
  | :unsupported_method
  | :not_encodable
  | :no_task
  | :client_tasks_disabled
  | {:client_task_cancelled, String.t()}
  | {:invalid_response, map()}
```

# `outcome`

```elixir
@type outcome() :: {:ok, map()} | {:error, error()}
```

# `deliver`

```elixir
@spec deliver(
  OzMcp.Instance.t(),
  String.t(),
  String.t() | integer(),
  {:ok, map()} | {:error, map()}
) :: :ok
```

Hands the answer of the client to the process that waits for it.

`answer` is `{:ok, result}` or `{:error, error}` (the error object of the
response). Always returns `:ok`: an answer for a request that is not
pending (late, repeated, unknown, or of another session) is ignored.

This is the path to one session: the id must name a request that the
session holds. The router uses `deliver/2`, which sends the answer of a
request of a task to the task of its owner. An id of a request of a task
that reaches this function names no request of the session, so the
answer is ignored.

# `ping`

```elixir
@spec ping(ctx(), keyword()) :: outcome()
```

Sends `ping` to the client. The client answers with an empty result.

# `request`

```elixir
@spec request(ctx(), String.t(), map() | nil, keyword()) :: outcome()
```

Sends a request to the client and waits for its answer.

Options:

  * `:timeout` — milliseconds, or `:infinity`. Defaults to the timeout
    runtime option of the method (see the moduledoc).
  * `:wait_for_stream` — `true` sends a request that only the `GET` stream
    can carry even when the client has no stream open (default `false`,
    the call fails with `:no_stream`).

# `request_task`

```elixir
@spec request_task(ctx(), String.t(), map(), keyword()) :: outcome()
```

Sends a request as a task of the client and waits for the final result.
This feature is experimental and the runtime option `client_tasks` turns
it on (default `false`).

Same options as `request/4` and:

  * `:ttl` — milliseconds that the client must keep the task. Defaults to
    the timeout of the method when it is an integer; with
    `timeout: :infinity` the request carries no `ttl`.
  * `:poll_interval` — milliseconds between two `tasks/get` calls. The
    `pollInterval` of the client wins. Defaults to the
    `client_task_poll_interval_ms` runtime option.

The first request carries `params.task`. A `task` value that the params
already have is kept: the `:ttl` option applies only when the params have
no `task`. The client answers with a `CreateTaskResult` and the call
polls `tasks/get` until the task is terminal. A `completed` or `failed`
task is read with `tasks/result`; an `input_required` task calls
`tasks/result` at once; a `cancelled` task gives
`{:error, {:client_task_cancelled, task_id}}`.

The client must declare the task capability of the method
(`tasks.requests.sampling.createMessage`,
`tasks.requests.elicitation.create`), else the call gives
`{:error, :capability_not_supported}`.

---

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