igniter 0.4.5 → 0.5.1

data/packages/igniter-core/lib/igniter/core/runtime/agent_session.rb

@@ -0,0 +1,922 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Runtime
+    class AgentSession
+      STREAM_EVENT_TYPES = %i[chunk status tool_call tool_result artifact final].freeze
+
+      class << self
+        def stream_event(type, **attributes)
+          { type: type.to_sym }.merge(compact_event_attributes(attributes))
+        end
+
+        def chunk_event(chunk: nil, text: nil, value: nil, **attributes)
+          stream_event(:chunk, chunk: chunk, text: text, value: value, **attributes)
+        end
+
+        def status_event(status:, **attributes)
+          stream_event(:status, status: status, **attributes)
+        end
+
+        def tool_call_event(name: nil, tool: nil, arguments: nil, call_id: nil, **attributes)
+          stream_event(:tool_call, name: name, tool: tool, arguments: arguments, call_id: call_id, **attributes)
+        end
+
+        def tool_result_event(name: nil, tool: nil, result: nil, value: nil, error: nil, call_id: nil, **attributes)
+          stream_event(
+            :tool_result,
+            name: name,
+            tool: tool,
+            result: result,
+            value: value,
+            error: error,
+            call_id: call_id,
+            **attributes
+          )
+        end
+
+        def artifact_event(artifact: nil, name: nil, uri: nil, **attributes)
+          stream_event(:artifact, artifact: artifact, name: name, uri: uri, **attributes)
+        end
+
+        def final_event(value: nil, result: nil, output: nil, **attributes)
+          stream_event(:final, value: value, result: result, output: output, **attributes)
+        end
+
+        private
+
+        def compact_event_attributes(attributes)
+          attributes.each_with_object({}) do |(key, value), memo|
+            memo[key] = value unless value.nil?
+          end
+        end
+      end
+
+      attr_reader :token, :node_name, :node_path, :agent_name, :message_name,
+                  :mode, :reply_mode, :waiting_on, :source_node, :trace, :payload, :turn, :phase,
+                  :messages, :last_request, :last_reply, :history, :ownership, :owner_url, :delivery_route,
+                  :execution_id, :graph, :interaction_contract
+
+      def initialize(token:, node_name:, node_path: nil, agent_name:, message_name:, mode:, # rubocop:disable Metrics/ParameterLists
+                     reply_mode: nil, waiting_on: nil, source_node: nil, trace: nil, payload: {}, turn: 1, phase: nil,
+                     messages: nil, last_request: nil, last_reply: nil, history: nil, ownership: nil, owner_url: nil,
+                     delivery_route: nil, execution_id: nil, graph: nil, interaction_contract: nil,
+                     finalizer: nil, tool_loop_policy: nil, session_policy: nil, node_url: nil,
+                     capability: nil, capability_query: nil, pinned_to: nil)
+        @token = token
+        @node_name = node_name&.to_sym
+        @node_path = node_path
+        @agent_name = agent_name&.to_sym
+        @message_name = message_name&.to_sym
+        @mode = mode&.to_sym
+        @reply_mode = reply_mode&.to_sym
+        @waiting_on = waiting_on&.to_sym
+        @source_node = source_node&.to_sym
+        @trace = trace
+        @payload = (payload || {}).freeze
+        @turn = Integer(turn || 1)
+        @history = Array(history || []).map { |entry| normalize_history_entry(entry) }.freeze
+        @messages = normalize_messages(messages)
+        @last_request = normalize_message_entry(last_request || find_last_message(:request))
+        @last_reply = normalize_message_entry(last_reply || find_last_message(:reply))
+        @phase = normalize_phase(phase || default_phase)
+        @delivery_route = normalize_delivery_route(delivery_route || delivery_route_from_trace(trace))
+        @owner_url = (owner_url || @delivery_route[:url])&.to_s
+        @ownership = normalize_ownership(ownership || default_ownership(@delivery_route, trace))
+        @execution_id = execution_id
+        @graph = graph
+        @interaction_contract = normalize_interaction_contract(
+          interaction_contract,
+          mode: @mode,
+          reply_mode: @reply_mode,
+          finalizer: finalizer,
+          tool_loop_policy: tool_loop_policy,
+          session_policy: session_policy,
+          node_url: node_url,
+          capability: capability,
+          capability_query: capability_query,
+          pinned_to: pinned_to
+        )
+        freeze
+      end
+
+      def self.from_h(data)
+        new(
+          token: value_from(data, :token),
+          node_name: value_from(data, :node_name),
+          node_path: value_from(data, :node_path),
+          agent_name: value_from(data, :agent_name),
+          message_name: value_from(data, :message_name),
+          mode: value_from(data, :mode),
+          reply_mode: value_from(data, :reply_mode),
+          waiting_on: value_from(data, :waiting_on),
+          source_node: value_from(data, :source_node),
+          trace: value_from(data, :trace),
+          payload: value_from(data, :payload) || {},
+          turn: value_from(data, :turn) || 1,
+          phase: value_from(data, :phase),
+          messages: value_from(data, :messages),
+          last_request: value_from(data, :last_request),
+          last_reply: value_from(data, :last_reply),
+          history: value_from(data, :history) || [],
+          ownership: value_from(data, :ownership),
+          owner_url: value_from(data, :owner_url),
+          delivery_route: value_from(data, :delivery_route),
+          execution_id: value_from(data, :execution_id),
+          graph: value_from(data, :graph),
+          interaction_contract: value_from(data, :interaction_contract) || value_from(data, :interaction),
+          finalizer: value_from(data, :finalizer),
+          tool_loop_policy: value_from(data, :tool_loop_policy),
+          session_policy: value_from(data, :session_policy),
+          node_url: value_from(data, :node_url) || value_from(data, :node),
+          capability: value_from(data, :capability),
+          capability_query: value_from(data, :capability_query) || value_from(data, :query),
+          pinned_to: value_from(data, :pinned_to)
+        )
+      end
+
+      def to_h
+        {
+          token: token,
+          node_name: node_name,
+          node_path: node_path,
+          agent_name: agent_name,
+          message_name: message_name,
+          mode: mode,
+          reply_mode: reply_mode,
+          waiting_on: waiting_on,
+          source_node: source_node,
+          trace: trace,
+          payload: payload,
+          turn: turn,
+          phase: phase,
+          messages: messages,
+          last_request: last_request,
+          last_reply: last_reply,
+          history: history,
+          ownership: ownership,
+          owner_url: owner_url,
+          delivery_route: delivery_route,
+          interaction_contract: interaction_contract.to_h,
+          finalizer: finalizer,
+          tool_loop_policy: tool_loop_policy,
+          session_policy: session_policy,
+          node_url: node_url,
+          capability: capability,
+          capability_query: capability_query,
+          pinned_to: pinned_to,
+          lifecycle: lifecycle,
+          execution_id: execution_id,
+          graph: graph
+        }.compact
+      end
+
+      def as_json(*)
+        to_h
+      end
+
+      def continue(payload: {}, trace: nil, token: nil, waiting_on: nil, request: nil, reply: nil, phase: nil)
+        next_token = token || self.token
+        next_waiting_on = waiting_on || self.waiting_on || node_name
+        next_trace = trace || self.trace
+        next_turn = turn + 1
+        request_message = build_request_message(turn: next_turn, payload: payload, request: request)
+        reply_message = normalize_message_entry(reply)
+        next_messages = messages.dup
+        next_messages << request_message if request_message
+        next_messages << reply_message if reply_message
+
+        self.class.new(
+          token: next_token,
+          node_name: node_name,
+          node_path: node_path,
+          agent_name: agent_name,
+          message_name: message_name,
+          mode: mode,
+          reply_mode: reply_mode,
+          waiting_on: next_waiting_on,
+          source_node: source_node || node_name,
+          trace: next_trace,
+          payload: payload,
+          turn: next_turn,
+          phase: normalize_phase(phase || default_continue_phase(reply_message)),
+          messages: next_messages,
+          last_request: request_message || last_request,
+          last_reply: reply_message || last_reply,
+          history: history + [
+            {
+              turn: next_turn,
+              event: :continued,
+              token: next_token,
+              waiting_on: next_waiting_on,
+              payload: payload,
+              phase: normalize_phase(phase || default_continue_phase(reply_message)),
+              request: request_message,
+              reply: reply_message
+            }
+          ],
+          ownership: ownership,
+          owner_url: owner_url,
+          delivery_route: delivery_route,
+          execution_id: execution_id,
+          graph: graph,
+          interaction_contract: interaction_contract
+        )
+      end
+
+      def complete(value: nil, reply: nil, trace: nil)
+        next_turn = turn + 1
+        reply_message = normalize_message_entry(reply || default_reply_message(turn: next_turn, value: value))
+
+        self.class.new(
+          token: token,
+          node_name: node_name,
+          node_path: node_path,
+          agent_name: agent_name,
+          message_name: message_name,
+          mode: mode,
+          reply_mode: reply_mode,
+          waiting_on: waiting_on,
+          source_node: source_node || node_name,
+          trace: trace || self.trace,
+          payload: payload,
+          turn: next_turn,
+          phase: :completed,
+          messages: messages + [reply_message],
+          last_request: last_request,
+          last_reply: reply_message,
+          history: history + [
+            {
+              turn: next_turn,
+              event: :completed,
+              token: token,
+              waiting_on: waiting_on,
+              phase: :completed,
+              reply: reply_message
+            }
+          ],
+          ownership: ownership,
+          owner_url: owner_url,
+          delivery_route: delivery_route,
+          execution_id: execution_id,
+          graph: graph,
+          interaction_contract: interaction_contract
+        )
+      end
+
+      def local_owned?
+        ownership == :local
+      end
+
+      def remote_owned?
+        ownership == :remote
+      end
+
+      def waiting?
+        phase == :waiting
+      end
+
+      def streaming?
+        phase == :streaming
+      end
+
+      def completed?
+        phase == :completed
+      end
+
+      def interactive?
+        reply_mode == :stream
+      end
+
+      def terminal?
+        completed?
+      end
+
+      def continuable?
+        !terminal?
+      end
+
+      def finalizer
+        interaction_contract.finalizer
+      end
+
+      def tool_loop_policy
+        interaction_contract.tool_loop_policy
+      end
+
+      def session_policy
+        interaction_contract.session_policy
+      end
+
+      def routing_mode
+        interaction_contract.routing_mode
+      end
+
+      def agent_result_contract(kind: nil)
+        Runtime::AgentResultContract.new(
+          kind: kind || infer_result_kind,
+          waiting_on: waiting_on,
+          source_node: source_node,
+          session_lifecycle_state: lifecycle_state,
+          phase: phase,
+          interaction_contract: interaction_contract.to_h,
+          tool_runtime: tool_runtime,
+          ownership: ownership,
+          owner_url: owner_url,
+          delivery_route: delivery_route,
+          interactive: interactive?,
+          terminal: terminal?,
+          continuable: continuable?,
+          routed: routed?
+        )
+      end
+
+      def node_url
+        interaction_contract.node_url
+      end
+
+      def capability
+        interaction_contract.capability
+      end
+
+      def capability_query
+        interaction_contract.capability_query
+      end
+
+      def pinned_to
+        interaction_contract.pinned_to
+      end
+
+      def routed?
+        remote_owned? || !delivery_route.empty?
+      end
+
+      def lifecycle_state
+        return :completed if completed?
+        return :streaming if streaming?
+        return :waiting if waiting?
+
+        phase
+      end
+
+      def lifecycle
+        {
+          state: lifecycle_state,
+          ownership: ownership,
+          owner_url: owner_url,
+          routed: routed?,
+          interactive: interactive?,
+          terminal: terminal?,
+          continuable: continuable?,
+          tool_loop_status: tool_loop_status,
+          tool_runtime: tool_runtime,
+          waiting_on: waiting_on,
+          turn: turn,
+          mode: mode,
+          reply_mode: reply_mode,
+          interaction_contract: interaction_contract.to_h
+        }.compact.freeze
+      end
+
+      def chunks
+        events.filter_map { |event| chunk_from_event(event) }
+      end
+
+      def events
+        messages.flat_map do |message|
+          next [] unless message[:kind] == :reply
+
+          stream_events_for_message(message)
+        end
+      end
+
+      def last_event
+        events.last
+      end
+
+      def tool_interactions
+        interactions = {}
+        sequence_by_tool = Hash.new(0)
+        open_keys_by_tool = Hash.new { |hash, key| hash[key] = [] }
+
+        events.each_with_index do |event, index|
+          next unless %i[tool_call tool_result].include?(event[:type])
+
+          tool_name = tool_name_for_event(event)
+          key = if event[:call_id]
+                  "call_id:#{event[:call_id]}"
+                elsif event[:type] == :tool_call
+                  sequence_by_tool[tool_name] += 1
+                  generated = "tool:#{tool_name}:#{sequence_by_tool[tool_name]}"
+                  open_keys_by_tool[tool_name] << generated
+                  generated
+                else
+                  open_keys_by_tool[tool_name].last || "orphan_result:#{tool_name}:#{index + 1}"
+                end
+
+          interaction = interactions[key] ||= {
+            key: key,
+            call_id: event[:call_id],
+            tool_name: tool_name,
+            call: nil,
+            results: []
+          }
+
+          if event[:type] == :tool_call
+            interaction[:call] ||= event
+            interaction[:call_id] ||= event[:call_id]
+            interaction[:tool_name] ||= tool_name
+          else
+            interaction[:results] << event
+            interaction[:tool_name] ||= tool_name
+          end
+        end
+
+        interactions.values.map do |interaction|
+          results = interaction[:results].freeze
+          call = interaction[:call]
+          status =
+            if call && !results.empty?
+              :completed
+            elsif call
+              :pending
+            else
+              :orphan_result
+            end
+
+          {
+            key: interaction[:key],
+            call_id: interaction[:call_id],
+            tool_name: interaction[:tool_name],
+            call: call,
+            results: results,
+            status: status,
+            complete: status == :completed
+          }.freeze
+        end.freeze
+      end
+
+      def pending_tool_interactions
+        tool_interactions.select { |interaction| interaction[:status] == :pending }
+      end
+
+      def completed_tool_interactions
+        tool_interactions.select { |interaction| interaction[:status] == :completed }
+      end
+
+      def orphan_tool_interactions
+        tool_interactions.select { |interaction| interaction[:status] == :orphan_result }
+      end
+
+      def all_tool_calls_resolved?
+        pending_tool_interactions.empty?
+      end
+
+      def tool_loop_consistent?
+        orphan_tool_interactions.empty?
+      end
+
+      def tool_loop_complete?
+        all_tool_calls_resolved? && tool_loop_consistent?
+      end
+
+      def tool_loop_status
+        return :idle if tool_interactions.empty?
+        return :orphaned unless tool_loop_consistent?
+        return :open unless all_tool_calls_resolved?
+
+        :complete
+      end
+
+      def tool_loop_summary
+        {
+          status: tool_loop_status,
+          total: tool_interactions.size,
+          pending: pending_tool_interactions.size,
+          completed: completed_tool_interactions.size,
+          orphaned: orphan_tool_interactions.size,
+          resolved: all_tool_calls_resolved?,
+          consistent: tool_loop_consistent?,
+          complete: tool_loop_complete?,
+          open_keys: pending_tool_interactions.map { |interaction| interaction[:key] },
+          orphan_keys: orphan_tool_interactions.map { |interaction| interaction[:key] }
+        }.freeze
+      end
+
+      def tool_runtime
+        summary = tool_loop_summary
+
+        {
+          status: summary[:status],
+          policy: tool_loop_policy,
+          finalizer: finalizer,
+          waiting_on: tool_runtime_waiting_on(summary),
+          interaction_count: summary[:total],
+          pending_count: summary[:pending],
+          completed_count: summary[:completed],
+          orphaned_count: summary[:orphaned],
+          resolved: summary[:resolved],
+          consistent: summary[:consistent],
+          complete: summary[:complete],
+          open_keys: summary[:open_keys],
+          orphan_keys: summary[:orphan_keys],
+          open_tools: pending_tool_interactions.map { |interaction| interaction[:tool_name] }.uniq.freeze,
+          completed_tools: completed_tool_interactions.map { |interaction| interaction[:tool_name] }.uniq.freeze,
+          orphan_tools: orphan_tool_interactions.map { |interaction| interaction[:tool_name] }.uniq.freeze
+        }.freeze
+      end
+
+      def ready_to_finalize_stream?(policy: :complete)
+        case policy
+        when :ignore
+          true
+        when :resolved
+          all_tool_calls_resolved?
+        when :complete, nil
+          %i[idle complete].include?(tool_loop_status)
+        else
+          raise ResolutionError, "Unsupported tool loop policy #{policy.inspect} for agent session '#{node_name}'"
+        end
+      end
+
+      def ensure_ready_to_finalize_stream!(policy: :complete)
+        return true if ready_to_finalize_stream?(policy: policy)
+
+        raise ResolutionError,
+              "Streaming agent session '#{node_name}' cannot auto-finalize while tool loop is #{tool_loop_status.inspect} under policy #{policy.inspect}"
+      end
+
+      def validate_stream_reply!(reply)
+        return if reply.nil?
+
+        reply_message = normalize_message_entry(reply)
+        payload = reply_message[:payload]
+        unless payload.is_a?(Hash)
+          raise ResolutionError, "Streaming agent session '#{node_name}' reply payload must be a Hash"
+        end
+
+        if !payload.key?(:events) && !payload.key?(:event) && !payload.key?(:chunk)
+          raise ResolutionError, "Streaming agent session '#{node_name}' replies must use payload[:event], payload[:events], or payload[:chunk]"
+        end
+
+        stream_events_for_message(reply_message)
+      end
+
+      def finalized_value(finalizer:, contract: nil, execution: nil)
+        case finalizer
+        when nil, :join
+          chunks.map(&:to_s).join
+        when :array
+          chunks.dup
+        when :last
+          chunks.last
+        when :events
+          events.dup
+        when Proc
+          finalizer.call(
+            chunks: chunks,
+            events: events,
+            messages: messages,
+            session: self,
+            contract: contract,
+            execution: execution
+          )
+        when Symbol, String
+          raise ResolutionError, "Stream finalizer #{finalizer.inspect} requires a contract instance" unless contract
+
+          contract.public_send(
+            finalizer.to_sym,
+            chunks: chunks,
+            events: events,
+            messages: messages,
+            session: self,
+            execution: execution
+          )
+        else
+          raise ResolutionError, "Unsupported stream finalizer #{finalizer.inspect}"
+        end
+      end
+
+      private
+
+      def infer_result_kind
+        reply_mode == :stream ? :stream : :deferred
+      end
+
+      def normalize_ownership(value)
+        (value || :local).to_sym
+      end
+
+      def normalize_delivery_route(route)
+        return {}.freeze unless route.is_a?(Hash)
+
+        route.each_with_object({}) do |(key, value), memo|
+          next if value.nil?
+
+          normalized_key = key.to_sym
+          memo[normalized_key] =
+            case normalized_key
+            when :routing_mode
+              value.to_sym
+            when :remote
+              truthy?(value)
+            when :capability
+              value.to_sym
+            when :query
+              value.is_a?(Hash) ? deep_symbolize_hash(value) : value
+            else
+              value
+            end
+        end.freeze
+      end
+
+      def default_ownership(route, trace)
+        return :remote if route[:remote]
+        return :remote if route[:routing_mode] && route[:routing_mode] != :local
+        return :remote if route[:url]
+        return :remote if trace.is_a?(Hash) && truthy?(trace[:remote] || trace["remote"])
+
+        :local
+      end
+
+      def delivery_route_from_trace(trace)
+        return {} unless trace.is_a?(Hash)
+
+        {
+          routing_mode: trace[:routing_mode] || trace["routing_mode"],
+          url: trace[:route_url] || trace["route_url"],
+          capability: trace[:capability] || trace["capability"],
+          query: trace[:capability_query] || trace["capability_query"],
+          pinned_to: trace[:pinned_to] || trace["pinned_to"],
+          remote: trace.key?(:remote) || trace.key?("remote") ? truthy?(trace[:remote] || trace["remote"]) : nil
+        }.reject { |_key, value| value.nil? }
+      end
+
+      def deep_symbolize_hash(value)
+        return value unless value.is_a?(Hash)
+
+        value.each_with_object({}) do |(key, nested_value), memo|
+          memo[key.to_sym] =
+            case nested_value
+            when Hash
+              deep_symbolize_hash(nested_value)
+            when Array
+              nested_value.map { |item| item.is_a?(Hash) ? deep_symbolize_hash(item) : item }
+            else
+              nested_value
+            end
+        end
+      end
+
+      def truthy?(value)
+        value == true || value.to_s == "true"
+      end
+
+      def normalize_messages(messages)
+        base_messages = Array(messages || default_messages)
+        base_messages.map { |entry| normalize_message_entry(entry) }.freeze
+      end
+
+      def normalize_history_entry(entry)
+        case entry
+        when Hash
+          entry.each_with_object({}) do |(key, value), memo|
+            memo[key.to_sym] = value
+          end.freeze
+        else
+          entry
+        end
+      end
+
+      def normalize_message_entry(entry)
+        return nil unless entry
+        return entry unless entry.is_a?(Hash)
+
+        entry.each_with_object({}) do |(key, value), memo|
+          memo[key.to_sym] = value
+        end.freeze
+      end
+
+      def normalize_phase(value)
+        (value || :waiting).to_sym
+      end
+
+      def tool_runtime_waiting_on(summary)
+        return :tool_result if summary[:status] == :open
+        return :tool_reconciliation if summary[:status] == :orphaned
+
+        waiting_on
+      end
+
+      def normalize_interaction_contract(contract, mode:, reply_mode:, finalizer:, tool_loop_policy:, session_policy:, node_url:, capability:, capability_query:, pinned_to:) # rubocop:disable Metrics/ParameterLists
+        return contract if contract.is_a?(Model::AgentInteractionContract)
+
+        interaction_data =
+          if contract.is_a?(Hash)
+            symbolize_hash(contract)
+          else
+            {}
+          end
+
+        resolved_route = interaction_route_defaults
+        Model::AgentInteractionContract.new(
+          mode: interaction_data.fetch(:mode, mode),
+          reply_mode: interaction_data.fetch(:reply, interaction_data.fetch(:reply_mode, reply_mode)),
+          finalizer: interaction_data.fetch(:finalizer, finalizer),
+          tool_loop_policy: interaction_data.fetch(:tool_loop_policy, tool_loop_policy),
+          session_policy: interaction_data.fetch(:session_policy, session_policy),
+          node_url: interaction_data.fetch(:node, interaction_data.fetch(:node_url, node_url || resolved_route[:node_url])),
+          capability: interaction_data.fetch(:capability, capability || resolved_route[:capability]),
+          capability_query: interaction_data.fetch(:query, interaction_data.fetch(:capability_query, capability_query || resolved_route[:capability_query])),
+          pinned_to: interaction_data.fetch(:pinned_to, pinned_to || resolved_route[:pinned_to])
+        )
+      end
+
+      def interaction_route_defaults
+        {
+          node_url: delivery_route[:url],
+          capability: delivery_route[:capability],
+          capability_query: delivery_route[:query],
+          pinned_to: delivery_route[:pinned_to]
+        }.freeze
+      end
+
+      def symbolize_hash(value)
+        value.each_with_object({}) do |(key, nested_value), memo|
+          memo[key.to_sym] = nested_value
+        end
+      end
+
+      def default_phase
+        return :completed if history.last.is_a?(Hash) && history.last[:event] == :completed
+        return :streaming if reply_mode == :stream
+
+        :waiting
+      end
+
+      def default_messages
+        [default_request_message(turn: turn, payload: payload, source: :contract)]
+      end
+
+      def default_request_message(turn:, payload:, source:)
+        {
+          turn: turn,
+          kind: :request,
+          name: message_name,
+          source: source,
+          reply_mode: reply_mode,
+          payload: payload
+        }
+      end
+
+      def default_reply_message(turn:, value:)
+        {
+          turn: turn,
+          kind: :reply,
+          name: message_name,
+          source: :agent,
+          reply_mode: reply_mode,
+          payload: normalize_reply_payload(value)
+        }
+      end
+
+      def build_request_message(turn:, payload:, request:)
+        return normalize_message_entry(request) if request
+        return nil if payload.nil? || payload.empty?
+
+        default_request_message(turn: turn, payload: payload, source: :continuation)
+      end
+
+      def default_continue_phase(reply_message)
+        return :streaming if reply_mode == :stream
+        return :responding if reply_message
+
+        :waiting
+      end
+
+      def normalize_reply_payload(value)
+        if reply_mode == :stream
+          return { event: self.class.final_event(value: value) }
+        end
+
+        return value if value.is_a?(Hash)
+
+        { value: value }
+      end
+
+      def find_last_message(kind)
+        messages.reverse.find { |entry| entry[:kind] == kind }
+      end
+
+      def stream_events_for_message(message)
+        payload = message[:payload]
+        return [] unless payload.is_a?(Hash)
+
+        if payload.key?(:events)
+          Array(payload[:events]).filter_map do |entry|
+            normalize_stream_event(entry, message: message)
+          end
+        elsif payload.key?(:event)
+          [normalize_stream_event(payload[:event], message: message, extra: hash_without(payload, :event))].compact
+        elsif payload.key?(:chunk)
+          [normalize_stream_event(payload, message: message, default_type: :chunk)].compact
+        else
+          []
+        end
+      end
+
+      def normalize_stream_event(entry, message:, extra: nil, default_type: nil)
+        case entry
+        when Hash
+          normalized = normalize_message_entry(entry)
+          type = normalized[:type] || normalized[:event] || default_type
+          return nil unless type
+
+          event = {
+            turn: message[:turn],
+            source: message[:source],
+            message_name: message[:name],
+            type: type.to_sym
+          }.merge(hash_without(normalized, :type, :event)).merge(extra || {})
+          validate_stream_event!(event)
+          event.freeze
+        when Symbol, String
+          event = {
+            turn: message[:turn],
+            source: message[:source],
+            message_name: message[:name],
+            type: entry.to_sym
+          }.merge(extra || {})
+          validate_stream_event!(event)
+          event.freeze
+        else
+          nil
+        end
+      end
+
+      def validate_stream_event!(event)
+        type = event[:type]&.to_sym
+        unless STREAM_EVENT_TYPES.include?(type)
+          raise ResolutionError, "Unsupported stream event type #{type.inspect} for agent session '#{node_name}'"
+        end
+
+        case type
+        when :chunk
+          return if event.key?(:chunk) || event.key?(:text) || event.key?(:value)
+
+          raise ResolutionError, "Stream :chunk events for agent session '#{node_name}' require :chunk, :text, or :value"
+        when :status
+          return if event.key?(:status)
+
+          raise ResolutionError, "Stream :status events for agent session '#{node_name}' require :status"
+        when :tool_call
+          return if event.key?(:name) || event.key?(:tool)
+
+          raise ResolutionError, "Stream :tool_call events for agent session '#{node_name}' require :name or :tool"
+        when :tool_result
+          return if event.key?(:name) || event.key?(:tool) || event.key?(:result) || event.key?(:value)
+
+          raise ResolutionError, "Stream :tool_result events for agent session '#{node_name}' require tool identity or result payload"
+        when :artifact
+          return if event.key?(:artifact) || event.key?(:name) || event.key?(:uri)
+
+          raise ResolutionError, "Stream :artifact events for agent session '#{node_name}' require :artifact, :name, or :uri"
+        when :final
+          return if event.key?(:value) || event.key?(:result) || event.key?(:output)
+
+          raise ResolutionError, "Stream :final events for agent session '#{node_name}' require :value, :result, or :output"
+        end
+      end
+
+      def hash_without(hash, *keys)
+        rejected = keys.map(&:to_sym)
+        hash.each_with_object({}) do |(key, value), memo|
+          memo[key] = value unless rejected.include?(key.to_sym)
+        end
+      end
+
+      def chunk_from_event(event)
+        return nil unless event[:type] == :chunk
+
+        return event[:chunk] if event.key?(:chunk)
+        return event[:text] if event.key?(:text)
+        return event[:value] if event.key?(:value)
+
+        nil
+      end
+
+      def tool_name_for_event(event)
+        (event[:tool] || event[:name] || :unknown_tool).to_sym
+      end
+
+      def self.value_from(data, key)
+        return nil unless data
+
+        return data[key] if data.respond_to?(:key?) && data.key?(key)
+        return data[key.to_s] if data.respond_to?(:key?) && data.key?(key.to_s)
+
+        nil
+      end
+    end
+  end
+end