igniter 0.5.0 → 0.5.1

data/{lib/igniter → packages/igniter-core/lib/igniter/core}/diagnostics/report.rb

@@ -10,7 +10,7 @@ module Igniter
       def to_h
         safely_resolve_execution
 
-        {
+        report = {
           graph: execution.compiled_graph.name,
           execution_id: execution.events.execution_id,
           status: status,
@@ -20,6 +20,8 @@ module Igniter
           collection_nodes: summarize_collection_nodes,
           events: summarize_events
         }
+
+        Diagnostics.augment_report(report: report, execution: execution)
       end
 
       def as_json(*)
@@ -36,6 +38,7 @@ module Igniter
         lines << format_nodes(report[:nodes])
         lines << format_collection_nodes(report[:collection_nodes])
         lines << format_errors(report[:errors])
+        Diagnostics.append_text(report: report, lines: lines)
         lines << format_events(report[:events])
         lines.compact.join("\n")
       end
@@ -52,6 +55,7 @@ module Igniter
         unless report[:collection_nodes].empty?
           lines << "- Collections: #{report[:collection_nodes].map { |node| "#{node[:node_name]} total=#{node[:total]} succeeded=#{node[:succeeded]} failed=#{node[:failed]} status=#{node[:status]}" }.join('; ')}"
         end
+        Diagnostics.append_markdown_summary(report: report, lines: lines)
         lines << "- Events: total=#{report[:events][:total]}, latest=#{report[:events][:latest_type] || 'none'}"
 
         unless report[:errors].empty?
@@ -73,6 +77,7 @@ module Igniter
           end
         end
 
+        Diagnostics.append_markdown_sections(report: report, lines: lines)
         lines.join("\n")
       end
 
@@ -80,10 +85,6 @@ module Igniter
 
       attr_reader :execution
 
-      def execution_result
-        @execution_result ||= Runtime::Result.new(execution)
-      end
-
       def safely_resolve_execution
         execution.resolve_all
       rescue Igniter::Error
@@ -178,7 +179,6 @@ module Igniter
       end
 
       def format_nodes(nodes)
-        line = "Nodes: total=#{nodes[:total]}, succeeded=#{nodes[:succeeded]}, failed=#{nodes[:failed]}, stale=#{nodes[:stale]}"
         line = "Nodes: total=#{nodes[:total]}, succeeded=#{nodes[:succeeded]}, failed=#{nodes[:failed]}, pending=#{nodes[:pending]}, stale=#{nodes[:stale]}"
         return line if nodes[:failed_nodes].empty?
 
@@ -235,6 +235,8 @@ module Igniter
 
       def serialize_value(value)
         case value
+        when Runtime::StreamResult
+          value.as_json
         when Runtime::DeferredResult
           value.as_json
         when Runtime::Result
@@ -251,6 +253,8 @@ module Igniter
       def inline_value(value)
         case value
         when Hash
+          return summarize_serialized_deferred_hash(value) if serialized_deferred_hash?(value)
+          return summarize_serialized_failed_output_hash(value) if serialized_failed_output_hash?(value)
           return summarize_serialized_collection_hash(value) if serialized_collection_hash?(value)
           return summarize_serialized_collection_items_hash(value) if serialized_collection_items_hash?(value)
 
@@ -291,6 +295,70 @@ module Igniter
         "{mode=#{value[:mode].inspect}, total=#{summary[:total]}, succeeded=#{summary[:succeeded]}, failed=#{summary[:failed]}, status=#{summary[:status].inspect}, keys=#{items.keys.inspect}, failed_keys=#{failed_keys.inspect}}"
       end
 
+      def serialized_deferred_hash?(value)
+        (value.key?(:token) || value.key?("token")) &&
+          (value.key?(:waiting_on) || value.key?("waiting_on"))
+      end
+
+      def summarize_serialized_deferred_hash(value)
+        token = hash_value(value, :token)
+        waiting_on = hash_value(value, :waiting_on)
+        payload = hash_value(value, :payload)
+        type = hash_value(value, :type)
+        phase = hash_value(value, :phase)
+        event_count = hash_value(value, :event_count)
+        tool_call_count = hash_value(value, :tool_call_count)
+        tool_result_count = hash_value(value, :tool_result_count)
+        tool_interaction_count = hash_value(value, :tool_interaction_count)
+        pending_tool_interaction_count = hash_value(value, :pending_tool_interaction_count)
+        completed_tool_interaction_count = hash_value(value, :completed_tool_interaction_count)
+        orphan_tool_interaction_count = hash_value(value, :orphan_tool_interaction_count)
+        tool_loop_status = hash_value(value, :tool_loop_status)
+        tool_loop_complete = hash_value(value, :tool_loop_complete)
+        status_count = hash_value(value, :status_count)
+        artifact_count = hash_value(value, :artifact_count)
+        chunks = hash_value(value, :chunks)
+        routing_summary = hash_value(value, :routing_trace_summary)
+        agent_summary = hash_value(value, :agent_trace_summary)
+
+        parts = ["token=#{token.inspect}", "waiting_on=#{waiting_on.inspect}"]
+        parts << "type=#{type.inspect}" if type
+        parts << "phase=#{phase.inspect}" if phase
+        parts << "events=#{event_count}" if event_count
+        parts << "statuses=#{status_count}" if status_count.to_i.positive?
+        parts << "tool_calls=#{tool_call_count}" if tool_call_count.to_i.positive?
+        parts << "tool_results=#{tool_result_count}" if tool_result_count.to_i.positive?
+        parts << "tool_interactions=#{tool_interaction_count}" if tool_interaction_count.to_i.positive?
+        parts << "open_tool_interactions=#{pending_tool_interaction_count}" if pending_tool_interaction_count.to_i.positive?
+        parts << "completed_tool_interactions=#{completed_tool_interaction_count}" if completed_tool_interaction_count.to_i.positive?
+        parts << "orphan_tool_interactions=#{orphan_tool_interaction_count}" if orphan_tool_interaction_count.to_i.positive?
+        parts << "tool_loop=#{tool_loop_status}" if tool_loop_status
+        parts << "tool_loop_complete=#{tool_loop_complete}" unless tool_loop_complete.nil?
+        parts << "artifacts=#{artifact_count}" if artifact_count.to_i.positive?
+        parts << "chunks=#{chunks.inspect}" if chunks.is_a?(Array) && !chunks.empty?
+        parts << "payload_keys=#{payload.keys.inspect}" if payload.is_a?(Hash) && !payload.empty?
+        parts << "routing=#{routing_summary}" if routing_summary
+        parts << "agent=#{agent_summary}" if agent_summary
+        "{#{parts.join(', ')}}"
+      end
+
+      def serialized_failed_output_hash?(value)
+        (value.key?(:error) || value.key?("error")) &&
+          (value.key?(:status) || value.key?("status"))
+      end
+
+      def summarize_serialized_failed_output_hash(value)
+        status = hash_value(value, :status)
+        error = hash_value(value, :error)
+        routing_summary = hash_value(value, :routing_trace_summary)
+        agent_summary = hash_value(value, :agent_trace_summary)
+
+        parts = ["status=#{status.inspect}", "error=#{error.inspect}"]
+        parts << "routing=#{routing_summary}" if routing_summary
+        parts << "agent=#{agent_summary}" if agent_summary
+        "{#{parts.join(', ')}}"
+      end
+
       def serialized_collection_items_hash?(value)
         return false if value.empty?
 
@@ -344,6 +412,13 @@ module Igniter
           }
         end
       end
+
+      def hash_value(hash, key)
+        return hash[key] if hash.key?(key)
+        return hash[key.to_s] if hash.key?(key.to_s)
+
+        nil
+      end
     end
   end
 end

data/packages/igniter-core/lib/igniter/core/diagnostics.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative "diagnostics/report"
+require_relative "diagnostics/agent_contributor"
+require_relative "diagnostics/capability_contributor"
+require_relative "diagnostics/orchestration_contributor"
+
+module Igniter
+  module Diagnostics
+    class << self
+      def report_contributors
+        @report_contributors ||= {}
+      end
+
+      def register_report_contributor(name, contributor)
+        report_contributors[name.to_sym] = contributor
+      end
+
+      def augment_report(report:, execution:)
+        report_contributors.each_value do |contributor|
+          next unless contributor.respond_to?(:augment)
+
+          contributor.augment(report: report, execution: execution)
+        end
+
+        report
+      end
+
+      def append_text(report:, lines:)
+        report_contributors.each_value do |contributor|
+          next unless contributor.respond_to?(:append_text)
+
+          contributor.append_text(report: report, lines: lines)
+        end
+      end
+
+      def append_markdown_summary(report:, lines:)
+        report_contributors.each_value do |contributor|
+          next unless contributor.respond_to?(:append_markdown_summary)
+
+          contributor.append_markdown_summary(report: report, lines: lines)
+        end
+      end
+
+      def append_markdown_sections(report:, lines:)
+        report_contributors.each_value do |contributor|
+          next unless contributor.respond_to?(:append_markdown_sections)
+
+          contributor.append_markdown_sections(report: report, lines: lines)
+        end
+      end
+    end
+
+    register_report_contributor(:core_agents, AgentContributor)
+    register_report_contributor(:core_capabilities, CapabilityContributor)
+    register_report_contributor(:core_orchestration, OrchestrationContributor)
+  end
+end

data/{lib/igniter → packages/igniter-core/lib/igniter/core}/dsl/contract_builder.rb

@@ -264,18 +264,78 @@ module Igniter
       end
 
       def remote(name, contract:, inputs:, node: nil, timeout: 30, # rubocop:disable Metrics/MethodLength,Metrics/ParameterLists,Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
-                 capability: nil, pinned_to: nil, **metadata)
+                 capability: nil, query: nil, trust: nil, governance: nil, policy: nil, decision: nil, pinned_to: nil, **metadata)
         raise CompileError, "remote :#{name} requires inputs: Hash" unless inputs.is_a?(Hash)
         raise CompileError, "remote :#{name} requires a contract: name" if contract.nil? || contract.to_s.strip.empty?
 
-        if capability && pinned_to
-          raise CompileError, "remote :#{name}: capability: and pinned_to: are mutually exclusive"
+        if [capability, query, pinned_to].count { |value| !value.nil? } > 1
+          raise CompileError, "remote :#{name}: capability:, query:, and pinned_to: are mutually exclusive"
         end
 
-        if capability.nil? && pinned_to.nil? && (node.nil? || node.to_s.strip.empty?)
+        if trust && pinned_to
+          raise CompileError, "remote :#{name}: trust: cannot be combined with pinned_to:"
+        end
+
+        if governance && pinned_to
+          raise CompileError, "remote :#{name}: governance: cannot be combined with pinned_to:"
+        end
+
+        if policy && pinned_to
+          raise CompileError, "remote :#{name}: policy: cannot be combined with pinned_to:"
+        end
+
+        if decision && pinned_to
+          raise CompileError, "remote :#{name}: decision: cannot be combined with pinned_to:"
+        end
+
+        if trust && capability.nil? && query.nil?
+          raise CompileError, "remote :#{name}: trust: requires capability: or query:"
+        end
+
+        if governance && capability.nil? && query.nil?
+          raise CompileError, "remote :#{name}: governance: requires capability: or query:"
+        end
+
+        if policy && capability.nil? && query.nil?
+          raise CompileError, "remote :#{name}: policy: requires capability: or query:"
+        end
+
+        if decision && capability.nil? && query.nil?
+          raise CompileError, "remote :#{name}: decision: requires capability: or query:"
+        end
+
+        if trust && query.is_a?(Hash) && query.key?(:trust)
+          raise CompileError, "remote :#{name}: trust: duplicates query[:trust]"
+        end
+
+        if governance && query.is_a?(Hash) && query.key?(:governance)
+          raise CompileError, "remote :#{name}: governance: duplicates query[:governance]"
+        end
+
+        if policy && query.is_a?(Hash) && query.key?(:policy)
+          raise CompileError, "remote :#{name}: policy: duplicates query[:policy]"
+        end
+
+        if decision && query.is_a?(Hash) && query.key?(:decision)
+          raise CompileError, "remote :#{name}: decision: duplicates query[:decision]"
+        end
+
+        if capability.nil? && query.nil? && pinned_to.nil? && (node.nil? || node.to_s.strip.empty?)
           raise CompileError, "remote :#{name} requires a node: URL"
         end
 
+        capability_query =
+          if trust || governance || policy || decision
+            base_query = query ? query.dup : { all_of: [capability] }
+            base_query[:trust] = trust if trust
+            base_query[:governance] = governance if governance
+            base_query[:policy] = policy if policy
+            base_query[:decision] = decision if decision
+            base_query
+          else
+            query
+          end
+
         add_node(
           Model::RemoteNode.new(
             id: next_id,
@@ -284,7 +344,77 @@ module Igniter
             node_url: node.to_s,
             input_mapping: inputs,
             timeout: timeout,
+            capability: (trust || governance || policy || decision) ? nil : capability,
+            capability_query: capability_query,
+            pinned_to: pinned_to,
+            path: scoped_path(name),
+            metadata: with_source_location(metadata)
+          )
+        )
+      end
+
+      def agent(name, via:, message:, inputs:, timeout: 5, mode: :call, reply: nil, finalizer: nil, tool_loop_policy: nil, session_policy: nil, node: nil, capability: nil, query: nil, pinned_to: nil, **metadata) # rubocop:disable Metrics/ParameterLists
+        normalized_mode = mode.respond_to?(:to_sym) ? mode.to_sym : mode
+        normalized_reply = reply.respond_to?(:to_sym) ? reply.to_sym : reply
+        normalized_finalizer = finalizer.respond_to?(:to_sym) ? finalizer.to_sym : finalizer
+        normalized_tool_loop_policy = tool_loop_policy.respond_to?(:to_sym) ? tool_loop_policy.to_sym : tool_loop_policy
+        normalized_session_policy = session_policy.respond_to?(:to_sym) ? session_policy.to_sym : session_policy
+
+        raise CompileError, "agent :#{name} requires inputs: Hash" unless inputs.is_a?(Hash)
+        raise CompileError, "agent :#{name} requires via:" if via.nil? || via.to_s.strip.empty?
+        raise CompileError, "agent :#{name} requires message:" if message.nil? || message.to_s.strip.empty?
+        raise CompileError, "agent :#{name} timeout must be positive" unless timeout.to_f.positive?
+        raise CompileError, "agent :#{name} mode must be :call or :cast" unless Model::AgentInteractionContract::MODES.include?(normalized_mode)
+        unless normalized_reply.nil? || Model::AgentInteractionContract::REPLY_MODES.include?(normalized_reply)
+          raise CompileError, "agent :#{name} reply must be :single, :deferred, :stream, or :none"
+        end
+        if normalized_mode == :cast && !normalized_reply.nil? && normalized_reply != :none
+          raise CompileError, "agent :#{name} mode :cast only supports reply: :none"
+        end
+        if normalized_mode == :call && normalized_reply == :none
+          raise CompileError, "agent :#{name} mode :call cannot use reply: :none"
+        end
+        if !normalized_finalizer.nil? && normalized_reply != :stream
+          raise CompileError, "agent :#{name} finalizer requires reply: :stream"
+        end
+        unless normalized_finalizer.nil? || normalized_finalizer.is_a?(Symbol) || normalized_finalizer.respond_to?(:call)
+          raise CompileError, "agent :#{name} finalizer must be a Symbol, String, or callable"
+        end
+        if !normalized_tool_loop_policy.nil? && normalized_reply != :stream
+          raise CompileError, "agent :#{name} tool_loop_policy requires reply: :stream"
+        end
+        unless normalized_tool_loop_policy.nil? || Model::AgentInteractionContract::TOOL_LOOP_POLICIES.include?(normalized_tool_loop_policy)
+          raise CompileError, "agent :#{name} tool_loop_policy must be :ignore, :resolved, or :complete"
+        end
+        if !normalized_session_policy.nil? && normalized_reply != :stream
+          raise CompileError, "agent :#{name} session_policy requires reply: :stream"
+        end
+        unless normalized_session_policy.nil? || Model::AgentInteractionContract::SESSION_POLICIES.include?(normalized_session_policy)
+          raise CompileError, "agent :#{name} session_policy must be :interactive, :single_turn, or :manual"
+        end
+        if [capability, query, pinned_to].count { |value| !value.nil? } > 1
+          raise CompileError, "agent :#{name}: capability:, query:, and pinned_to: are mutually exclusive"
+        end
+        if capability.nil? && query.nil? && pinned_to.nil? && !node.nil? && node.to_s.strip.empty?
+          raise CompileError, "agent :#{name} requires a non-empty node: URL"
+        end
+
+        add_node(
+          Model::AgentNode.new(
+            id: next_id,
+            name: name.to_sym,
+            agent_name: via,
+            message_name: message,
+            input_mapping: inputs,
+            timeout: timeout,
+            mode: normalized_mode,
+            reply_mode: normalized_reply,
+            finalizer: normalized_finalizer,
+            tool_loop_policy: normalized_tool_loop_policy,
+            session_policy: normalized_session_policy,
+            node_url: node,
             capability: capability,
+            capability_query: query,
             pinned_to: pinned_to,
             path: scoped_path(name),
             metadata: with_source_location(metadata)
@@ -464,6 +594,8 @@ module Igniter
       # rubocop:enable Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
       class BranchBuilder
+        UNDEFINED_BRANCH_MATCHER = :__igniter_branch_matcher_undefined__
+
         def self.build(&block)
           new.tap { |builder| builder.instance_eval(&block) }.to_h
         end
@@ -473,8 +605,33 @@ module Igniter
           @default_contract = nil
         end
 
-        def on(match, contract:)
-          @cases << { match: match, contract: contract }
+        def on(match = UNDEFINED_BRANCH_MATCHER, contract:, eq: UNDEFINED_BRANCH_MATCHER, in: UNDEFINED_BRANCH_MATCHER, matches: UNDEFINED_BRANCH_MATCHER) # rubocop:disable Metrics/ParameterLists
+          matcher_options = {
+            eq: eq,
+            in: binding.local_variable_get(:in),
+            matches: matches
+          }.reject { |_key, value| value == UNDEFINED_BRANCH_MATCHER }
+
+          if match != UNDEFINED_BRANCH_MATCHER && matcher_options.any?
+            raise CompileError, "branch `on` cannot combine a positional match with `eq:`, `in:`, or `matches:`"
+          end
+
+          if match == UNDEFINED_BRANCH_MATCHER && matcher_options.empty?
+            raise CompileError, "branch `on` requires a positional match or one of `eq:`, `in:`, or `matches:`"
+          end
+
+          if matcher_options.size > 1
+            raise CompileError, "branch `on` supports only one matcher option at a time"
+          end
+
+          matcher, value =
+            if match != UNDEFINED_BRANCH_MATCHER
+              [:eq, match]
+            else
+              matcher_options.first
+            end
+
+          @cases << { matcher: matcher, value: value, contract: contract }
         end
 
         def default(contract:)

data/packages/igniter-core/lib/igniter/core/dto/record.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+module Igniter
+  module DTO
+    class Record
+      UNSET = Object.new
+
+      class << self
+        def field(name, required: false, allow_nil: !required, default: UNSET, coerce: nil, merge: false)
+          local_fields[name.to_sym] = {
+            name: name.to_sym,
+            required: required,
+            allow_nil: allow_nil,
+            default: default,
+            coerce: coerce,
+            merge: merge
+          }.freeze
+
+          attr_reader name unless method_defined?(name)
+        end
+
+        def from_h(attributes)
+          new(**normalize_input_attributes(attributes))
+        end
+
+        def dto_fields
+          inherited_fields.merge(local_fields)
+        end
+
+        def field_names
+          dto_fields.keys.freeze
+        end
+
+        private
+
+        def inherited_fields
+          return {} unless superclass.respond_to?(:dto_fields)
+
+          superclass.dto_fields
+        end
+
+        def local_fields
+          @local_fields ||= {}
+        end
+
+        def normalize_input_attributes(attributes)
+          symbolize_hash(attributes || {})
+        end
+
+        def symbolize_hash(hash)
+          return {} unless hash.is_a?(Hash)
+
+          hash.each_with_object({}) do |(key, value), memo|
+            memo[key.to_sym] = value
+          end
+        end
+
+        def resolve_default(spec)
+          default = spec.fetch(:default, UNSET)
+          return UNSET if default.equal?(UNSET)
+
+          value = default.respond_to?(:call) ? default.call : deep_dup(default)
+          deep_freeze(value)
+        end
+
+        def coerce_field_value(spec, value)
+          coerce = spec[:coerce]
+          return value if coerce.nil?
+
+          case coerce
+          when Symbol
+            send(coerce, value)
+          else
+            coerce.arity == 2 ? coerce.call(value, spec) : coerce.call(value)
+          end
+        end
+
+        def deep_dup(value)
+          case value
+          when Hash
+            value.each_with_object({}) do |(key, nested), memo|
+              memo[deep_dup(key)] = deep_dup(nested)
+            end
+          when Array
+            value.map { |item| deep_dup(item) }
+          else
+            value.dup
+          end
+        rescue TypeError
+          value
+        end
+
+        def deep_freeze(value)
+          case value
+          when Hash
+            value.each do |key, nested|
+              deep_freeze(key)
+              deep_freeze(nested)
+            end
+          when Array
+            value.each { |item| deep_freeze(item) }
+          end
+
+          value.freeze if value.respond_to?(:freeze)
+          value
+        end
+
+        def serialize_value(value)
+          case value
+          when Record
+            value.to_h
+          when Hash
+            value.each_with_object({}) do |(key, nested), memo|
+              memo[key] = serialize_value(nested)
+            end
+          when Array
+            value.map { |item| serialize_value(item) }
+          else
+            value
+          end
+        end
+      end
+
+      def initialize(**attributes)
+        normalized = self.class.send(:normalize_input_attributes, attributes)
+        unknown_keys = normalized.keys - self.class.field_names
+        unless unknown_keys.empty?
+          raise ArgumentError, "#{self.class} received unknown fields: #{unknown_keys.map(&:inspect).join(", ")}"
+        end
+
+        self.class.dto_fields.each do |name, spec|
+          value = if normalized.key?(name)
+                    normalized[name]
+                  else
+                    self.class.send(:resolve_default, spec)
+                  end
+
+          if value.equal?(UNSET)
+            raise ArgumentError, "#{self.class} requires #{name}" if spec[:required]
+
+            value = nil
+          end
+
+          if value.nil?
+            raise ArgumentError, "#{self.class} requires #{name}" unless spec[:allow_nil]
+          else
+            value = self.class.send(:coerce_field_value, spec, value)
+            value = self.class.send(:deep_freeze, value)
+          end
+
+          instance_variable_set(:"@#{name}", value)
+        end
+
+        freeze
+      end
+
+      def with(**overrides)
+        normalized = self.class.send(:normalize_input_attributes, overrides)
+
+        merged = self.class.dto_fields.each_with_object({}) do |(name, spec), memo|
+          current = public_send(name)
+
+          if normalized.key?(name)
+            override = normalized[name]
+            memo[name] =
+              if spec[:merge] && current.respond_to?(:merge) && override.is_a?(Hash)
+                current.merge(override)
+              else
+                override
+              end
+          else
+            memo[name] = current
+          end
+        end
+
+        self.class.new(**merged)
+      end
+
+      def to_h
+        self.class.dto_fields.each_with_object({}) do |(name, _spec), memo|
+          value = public_send(name)
+          memo[name] = self.class.send(:serialize_value, value) unless value.nil?
+        end.freeze
+      end
+
+      alias attributes to_h
+    end
+  end
+end

data/packages/igniter-core/lib/igniter/core/dto.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "dto/record"
+
+module Igniter
+  module DTO
+  end
+end

data/{lib/igniter → packages/igniter-core/lib/igniter/core}/effect.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+require_relative "errors"
+require_relative "runtime/deferred_result"
+require_relative "executor"
+
 module Igniter
   # Base class for side-effect adapters.
   #

data/{lib/igniter → packages/igniter-core/lib/igniter/core}/errors.rb

@@ -62,9 +62,32 @@ module Igniter
   class PendingDependencyError < Error
     attr_reader :deferred_result
 
-    def initialize(deferred_result, message = "Dependency is pending", context: {})
-      @deferred_result = deferred_result
-      super(message, context: context)
+    def initialize(deferred_result, message = "Dependency is pending", context: {}, token: nil, source_node: nil, waiting_on: nil, payload: nil)
+      @deferred_result, resolved_message = normalize_pending_deferred(
+        deferred_result,
+        message,
+        token: token,
+        source_node: source_node,
+        waiting_on: waiting_on,
+        payload: payload
+      )
+      super(resolved_message, context: context)
+    end
+
+    private
+
+    def normalize_pending_deferred(deferred_result, message, token:, source_node:, waiting_on:, payload:)
+      deferred_class = defined?(Igniter::Runtime::DeferredResult) ? Igniter::Runtime::DeferredResult : nil
+      return [deferred_result, message] if deferred_class && deferred_result.is_a?(deferred_class)
+
+      built_deferred = deferred_class&.build(
+        token: token,
+        source_node: source_node,
+        waiting_on: waiting_on || source_node,
+        payload: payload || {}
+      )
+
+      [built_deferred || deferred_result, deferred_result]
     end
   end