MingaClaudeBridge.Session.Turn (minga_claude_bridge v0.1.0)

Copy Markdown View Source

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.

Summary

Types

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

t()

Functions

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.

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

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.

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

Returns an empty turn.

Ends the current message.

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

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

Types

message()

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

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

t()

@opaque t()

Functions

apply_assistant(turn, frame)

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(turn, arg2)

@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(turn)

@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(usage)

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

new()

@spec new() :: t()

Returns an empty turn.

stop_message(turn)

@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(turn)

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

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

usage(turn)

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

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