# `Mojentic.Realtime.Session`
[🔗](https://github.com/svetzal/mojentic-ex/blob/v1.5.0/lib/mojentic/realtime/session.ex#L1)

Stateful realtime session handle, owning a transport process.

Implemented as a GenServer that:

- subscribes to a transport (typically a `MintTransport` pid)
- receives raw OpenAI realtime events, normalises them into
  vendor-neutral `Mojentic.Realtime.Event` values, and forwards
  each to subscribers
- tracks per-turn state and dispatches `function_call` items as
  a batch via the configured `Mojentic.LLM.Tools.Runner`
- submits `function_call_output` items back through the transport
  and triggers the next `response.create`

## Tool batch execution

When `response.done` arrives with pending function calls, the
session spawns a supervised `Task` to run the batch so the GenServer
remains responsive to inbound WebSocket messages (e.g.
`input_audio_buffer.speech_started` barge-in) during execution.
The task sends `{:tool_batch_done, executions, outcomes, duration_ms}`
back to the session when it completes.

An `:atomics`-backed cancel ref is stored in the `RunContext` so
calling `interrupt/1` mid-batch signals cancellation to any tool
that has opted in via `run/3`.

This module mirrors the RealtimeSession class in the Python port.
The broker uses it to provide a single ergonomic entry point.

# `t`

```elixir
@type t() :: pid()
```

# `build_session_update`

Build the vendor-specific ``session.update`` payload from a
vendor-neutral config. Mirrors the GA shape used by mojentic-py /
mojentic-ts: ``session.type: 'realtime'``, output modalities, audio
input/output blocks, etc.

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `close`

Close the session and underlying transport.

# `commit_audio`

Manually commit the input audio buffer (push-to-talk mode).

# `initialise`

Send the initial `session.update` derived from the config. Called by the broker.

# `interrupt`

Manually cancel the in-flight assistant response.

# `send_audio_frame`

Append a PCM16 binary frame to the server's audio buffer.

# `send_text`

Send a text-mode user message and request a response.

# `start_link`

Start a session linked to the calling process.

Required opts:
- `:transport` — pid of an established transport
- `:transport_module` — module implementing the Transport behaviour
- `:config` — Mojentic.Realtime.Config struct

# `subscribe`

Subscribe to vendor-neutral events. The subscriber receives `{:realtime_event, %Event{}}`.

# `update_instructions`

Update instructions for future assistant turns.

---

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