Forwarding helpers for Raxol.Agent.Stream events.

Orchestrators that drive an agent stream and need to relay each event to a parent process (terminal dashboard, LiveView, MCP surface, etc.) end up writing the same boilerplate:

stream
|> Enum.reduce_while(initial, fn event, _acc ->
  send(parent, {:run_event, key, event_to_payload(event)})
  case event do
    {:done, _info} -> {:halt, :ok}
    {:error, reason} -> {:halt, {:error, reason}}
    _ -> {:cont, ...}
  end
end)

This module collapses that into one call:

Raxol.Agent.EventForwarder.to_parent(stream, parent, key)
#=> :ok | {:error, reason}

Options

• :transform (default &Stream.Event.to_payload/1) -- function applied to each event before sending. Use the identity function (&Function.identity/1) to forward raw tuples for back-compat with consumers that already pattern-match on the tuple shape.
• :tag (default :run_event) -- atom tag used in the parent message. Final shape: {tag, key, payload}.
• :halt_on_error? (default true) -- whether {:error, _} events short-circuit and return {:error, reason}.

Return value

• :ok after consuming {:done, _} (or stream ends)
• {:error, reason} after consuming {:error, reason} when halt_on_error? is true