# `MingaClaudeBridge.Session.Turn`
[🔗](https://github.com/jsmestad/minga-claude-bridge/blob/main/lib/minga_claude_bridge/session/turn.ex#L1)

Accumulates the assistant messages Claude Code streams for one request.

`apply_event/2` takes one main-thread stream event (see `MingaClaudeBridge.Wire.StreamEvent`) and returns the `{:text, _}` and `{:thinking, _}` events to forward. `stop_message/1` handles `message_stop`.

## Blocks

A block is tracked from `content_block_start` to `content_block_stop`. Text and thinking deltas are forwarded as they arrive. A `tool_use` block collects its `input_json_delta` fragments, and its arguments are decoded at `content_block_stop`. A tool_use block that never received `content_block_stop` is dropped at `message_stop` or at the next `message_start`: Claude Code drops such a block from its own conversation and never dispatches it, so it must not reach Minga either.

## Restreamed messages

A `message_start` while a message is still open means Claude Code abandoned that stream and is retrying it. The open message's blocks and usage are dropped. Text already forwarded from it cannot be taken back.

## Non-streaming fallback

When a stream stalls, Claude Code can ask again without streaming. The reply then arrives only as `assistant` frames (usually one per content block) under a message id that no `message_start` announced. `apply_assistant/2` forwards such frames: text and thinking become events, and `tool_use` blocks become tool calls. An open streamed message is dropped first, because Claude Code abandoned it. `assistant` frames of a message that was streamed, frames without an id, and `<synthetic>` frames (Claude Code's own error and notice reports) yield nothing. A fallback message has no `message_stop`; `end_fallback/1` ends it.

## Usage

Usage is the sum over the messages that reached `message_stop`. Each message's counts come from `message_start`, and `message_delta` overrides the counts it carries (usually `output_tokens`). `usage/1` returns `nil` when every count is zero, which is what Claude Code's `<synthetic>` messages report.

# `message`

```elixir
@type message() :: :closed | {:open, MingaClaudeBridge.Session.Event.usage()}
```

Whether a message is streaming, with the usage counts read so far for it.

# `t`

```elixir
@opaque t()
```

# `apply_assistant`

```elixir
@spec apply_assistant(t(), MingaClaudeBridge.Wire.Assistant.t()) ::
  {t(), [MingaClaudeBridge.Session.Event.t()]}
```

Applies one main-thread `assistant` frame. Returns the next turn and the events to forward. Only frames of a non-streaming fallback message yield events; see the module documentation.

# `apply_event`

```elixir
@spec apply_event(t(), term()) :: {t(), [MingaClaudeBridge.Session.Event.t()]}
```

Applies one stream event other than `message_stop`. Returns the next turn and the events to forward, in order.

# `end_fallback`

```elixir
@spec end_fallback(t()) ::
  {:tool_calls, [MingaClaudeBridge.Session.Event.tool_call()], t()}
  | {:no_tool_calls, t()}
```

Ends the open non-streaming fallback message, if any. Returns `{:tool_calls, calls, turn}` when it completed `tool_use` blocks and `{:no_tool_calls, turn}` otherwise. Its usage is added to the turn's usage.

# `event_usage`

```elixir
@spec event_usage(MingaClaudeBridge.Wire.Usage.t() | nil) ::
  MingaClaudeBridge.Session.Event.usage() | nil
```

Converts a wire usage object to event usage. Returns `nil` for `nil` and for all-zero counts.

# `new`

```elixir
@spec new() :: t()
```

Returns an empty turn.

# `stop_message`

```elixir
@spec stop_message(t()) ::
  {:tool_calls, [MingaClaudeBridge.Session.Event.tool_call()], t()}
  | {:no_tool_calls, t()}
```

Ends the current message.

Returns `{:tool_calls, calls, turn}` when the message completed one or more `tool_use` blocks, with the calls in stream order, and `{:no_tool_calls, turn}` otherwise. Blocks that never stopped are dropped.

# `stop_reason`

```elixir
@spec stop_reason(t()) :: MingaClaudeBridge.Wire.StopReason.t() | nil
```

Returns the stop reason of the last message that reported one.

# `usage`

```elixir
@spec usage(t()) :: MingaClaudeBridge.Session.Event.usage() | nil
```

Returns the summed usage of the stopped messages, or `nil` when every count is zero.

---

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