nitro_intelligence 3.0.2 → 4.0.0

data/lib/nitro_intelligence/client/factory.rb

@@ -6,8 +6,10 @@ require "nitro_intelligence/observability/project"
 module NitroIntelligence
   module Client
     class Factory
-      def initialize(observability_project_slug:)
+      def initialize(observability_project_slug:, inference_max_retries: nil, inference_timeout: nil)
         @observability_project_slug = observability_project_slug
+        @inference_max_retries = inference_max_retries
+        @inference_timeout = inference_timeout
       end
 
       def build
@@ -42,10 +44,16 @@ module NitroIntelligence
         project_client
       end
 
+      # The gateway owns failover between providers, and an upstream 429 it passes
+      # on has already been decided there, so the SDK's own retries default to off
+      # rather than to openai-ruby's two. A nil timeout keeps openai-ruby's default.
       def inference_client
+        config = NitroIntelligence.config
         @inference_client ||= OpenAI::Client.new(
-          api_key: NitroIntelligence.config.inference_api_key,
-          base_url: NitroIntelligence.config.inference_base_url
+          api_key: config.inference_api_key,
+          base_url: config.inference_base_url,
+          max_retries: @inference_max_retries.nil? ? config.inference_max_retries : @inference_max_retries,
+          **{ timeout: @inference_timeout || config.inference_timeout }.compact
         )
       end
     end

data/lib/nitro_intelligence/client/handlers/image_handler.rb

@@ -40,7 +40,9 @@ module NitroIntelligence
               },
             },
           }
-          parameters.replace(default_parameters.merge(parameters))
+          # Deep, so that request options a caller passes (headers, max_retries,
+          # timeout) sit alongside the image config rather than replacing it.
+          parameters.replace(default_parameters.deep_merge(parameters))
           Client.validate_model(parameters[:model])
         end
 

data/lib/nitro_intelligence/client/observers/langfuse_observer.rb

@@ -10,6 +10,10 @@ module NitroIntelligence
 
         MAX_STATUS_MESSAGE_LENGTH = 2000
 
+        # Attributes a handler may report off a response, each written only when it supplied
+        # one. See #record_result for why absence is left as absence.
+        RECORDED_ATTRIBUTES = %i[model model_parameters usage_details cost_details input output].freeze
+
         attr_reader :project_client
 
         def initialize(project_client:)
@@ -63,15 +67,30 @@ module NitroIntelligence
 
           handle_truncation(trace_attributes[:input], trace_attributes[:output], trace_attributes[:model])
 
-          generation.model = trace_attributes[:model] if trace_attributes[:model]
-          generation.usage_details = trace_attributes[:usage_details] if trace_attributes[:usage_details]
-          generation.cost_details = trace_attributes[:cost_details] if trace_attributes[:cost_details]
-          generation.input = trace_attributes[:input] if trace_attributes[:input]
-          generation.output = trace_attributes[:output] if trace_attributes[:output]
+          RECORDED_ATTRIBUTES.each do |name|
+            value = trace_attributes[name]
+            generation.public_send(:"#{name}=", value) if value
+          end
+
+          record_status(generation, trace_attributes)
 
           generation.update_trace(input: trace_attributes[:input], output: trace_attributes[:output])
         end
 
+        # A response the endpoint answered but did not finish -- a generation cut off at its
+        # token ceiling, say -- is neither a success worth nothing being said about nor a
+        # failure the request raised on. Recording it at WARNING leaves it findable without
+        # putting it among the errors.
+        def record_status(generation, trace_attributes)
+          status_message = trace_attributes[:status_message]
+          return if status_message.blank?
+
+          generation.update(
+            level: trace_attributes[:level] || "WARNING",
+            status_message: status_message.truncate(MAX_STATUS_MESSAGE_LENGTH)
+          )
+        end
+
         # Recorded before the request is made so that a request which raises still
         # shows what was sent. Handlers whose input is not safe to record twice
         # (image generation sends base64 payloads that are replaced with media

data/lib/nitro_intelligence/configuration.rb

@@ -13,6 +13,8 @@ module NitroIntelligence
     config_accessor :assistants_config, default: {}
     config_accessor :inference_api_key, default: ""
     config_accessor :inference_base_url, default: "https://inference.powerhome.ai"
+    config_accessor :inference_max_retries, default: 0
+    config_accessor :inference_timeout, default: nil
     config_accessor :model_config, default: {}
     config_accessor :observability_base_url, default: "https://cerebro.powerhome.ai"
     config_accessor :observability_projects, default: []

data/lib/nitro_intelligence/deprecator.rb

@@ -0,0 +1,10 @@
+require "active_support/deprecation"
+
+module NitroIntelligence
+  # Removed in the next major release. A Rails host has it registered with its own deprecators by
+  # the Railtie, so its `config.active_support` deprecation settings (log, raise, silence) apply;
+  # elsewhere it warns on stderr.
+  def self.deprecator
+    @deprecator ||= ActiveSupport::Deprecation.new("5.0", "nitro_intelligence")
+  end
+end

data/lib/nitro_intelligence/langfuse_extension.rb

@@ -4,6 +4,9 @@
 # The content of this file should eventually make its way upstream. Setting a custom trace ID is
 # already awaiting approval in https://github.com/simplepractice/langfuse-rb/pull/69.
 #
+# Explicit trace IDs create real roots here while the upstream fix awaits approval:
+# https://github.com/simplepractice/langfuse-rb/pull/128.
+#
 
 require "nitro_intelligence/langfuse_tracer_provider"
 
@@ -50,11 +53,15 @@ module NitroIntelligence
       Langfuse.send(:validate_observation_type!, as_type, type_str) unless skip_validation
 
       otel_tracer = @tracer_provider.tracer
-      otel_span = Langfuse.send(:create_otel_span,
-                                name:,
-                                start_time:,
-                                parent_span_context:,
-                                otel_tracer:)
+      otel_span = if trace_id
+                    @tracer_provider.start_root_span(name, trace_id: parent_span_context.trace_id, start_time:)
+                  else
+                    Langfuse.send(:create_otel_span,
+                                  name:,
+                                  start_time:,
+                                  parent_span_context:,
+                                  otel_tracer:)
+                  end
 
       # Serialize attributes
       # Only set attributes if span is still recording (should always be true here, but guard for safety)

data/lib/nitro_intelligence/langfuse_tracer_provider.rb

@@ -7,6 +7,7 @@
 module NitroIntelligence
   class LangfuseTracerProvider
     def initialize(config)
+      @trace_id_key = OpenTelemetry::Context.create_key("nitro-intelligence-trace-id")
       @tracer_provider = create_tracer_provider(config)
     end
 
@@ -18,6 +19,25 @@ module NitroIntelligence
       @tracer_provider.shutdown(timeout:)
     end
 
+    def start_root_span(name, trace_id:, start_time: nil)
+      # A seed identifies the trace, not a missing parent. Preserve propagated
+      # attributes while clearing the ambient span for this explicit root.
+      context = OpenTelemetry::Trace.context_with_span(OpenTelemetry::Trace::Span::INVALID)
+      context = context.set_value(@trace_id_key, trace_id)
+      # generate_trace_id has no context argument, so expose the seed through Context.current.
+      OpenTelemetry::Context.with_current(context) do
+        tracer.start_span(name, with_parent: context, start_timestamp: start_time)
+      end
+    end
+
+    def generate_trace_id
+      OpenTelemetry::Context.value(@trace_id_key) || OpenTelemetry::Trace.generate_trace_id
+    end
+
+    def generate_span_id
+      OpenTelemetry::Trace.generate_span_id
+    end
+
   private
 
     def create_tracer_provider(config)
@@ -36,7 +56,7 @@ module NitroIntelligence
         max_export_batch_size: config.batch_size
       )
 
-      tracer_provider = OpenTelemetry::SDK::Trace::TracerProvider.new
+      tracer_provider = OpenTelemetry::SDK::Trace::TracerProvider.new(id_generator: self)
       tracer_provider.add_span_processor(processor)
       span_processor = Langfuse::SpanProcessor.new(config:)
       tracer_provider.add_span_processor(span_processor)
@@ -53,6 +73,7 @@ module NitroIntelligence
       encoded = Base64.strict_encode64(credentials)
       {
         "Authorization" => "Basic #{encoded}",
+        "x-langfuse-ingestion-version" => "4",
       }
     end
   end

data/lib/nitro_intelligence/pending_review.rb

@@ -0,0 +1,222 @@
+require "active_support/core_ext/hash/indifferent_access"
+require "nitro_intelligence/review_decision"
+require "nitro_intelligence/tool_call_review_interrupt"
+require "nitro_intelligence/tool_call_review_validator"
+
+module NitroIntelligence
+  # What a paused run is waiting on: the interrupt the thread is holding, and the decisions that
+  # answer it.
+  #
+  # Assistants pauses for two kinds of review, never mixed in one interrupt:
+  #
+  # - tool calls, held by LangChain's `HumanInTheLoopMiddleware`, one action per call;
+  # - the run's final reply, a single action named `__reply__` whose `args` carry the draft's
+  #   `content`.
+  #
+  # A turn with tool calls only ever pauses on its tool calls, and the reply is the run's final
+  # message, so `#tool_calls` and `#reply` are never both present.
+  #
+  # Built from a thread state (`GET /threads/{id}/state`, which reports `interrupts`) or from the
+  # response of a paused `/runs/wait` (which reports `__interrupt__`); both carry the messages the
+  # tool calls are matched back onto.
+  class PendingReview
+    REPLY_ACTION = "__reply__".freeze
+
+    # What a reviewer may do with a reply. LangChain's `respond` supplies a tool's result, which a
+    # reply does not have, so it is never offered for one, whatever the interrupt lists.
+    REPLY_DECISIONS = %w[approve edit reject].freeze
+
+    KIND_NAMES = { tool_calls: "tool calls", reply: "a reply" }.freeze
+
+    # The draft reply a reviewer is asked to approve, edit or reject.
+    Reply = Struct.new(:content, :allowed_decisions, :description, :interrupt_id, keyword_init: true)
+
+    # The pending review in a thread state, or nil when the thread is not paused.
+    def self.from_thread_state(thread_state)
+      interrupt = Array(thread_state["interrupts"]).first
+      interrupt && new(interrupt:, messages: Array(thread_state.dig("values", "messages")))
+    end
+
+    # The pending review in a `/runs/wait` response, or nil when the run did not pause.
+    def self.from_run(run)
+      interrupt = Array(run["__interrupt__"]).first
+      interrupt && new(interrupt:, messages: Array(run["messages"]))
+    end
+
+    def initialize(interrupt:, messages:)
+      @interrupt = interrupt.to_h
+      @messages = messages
+    end
+
+    # Identifies this pause. A thread that has moved on -- a new message superseded the review, or
+    # another reviewer decided it first -- reports a different interrupt, or none.
+    def interrupt_id
+      @interrupt["id"] || @interrupt["interrupt_id"]
+    end
+
+    # `:tool_calls` or `:reply`.
+    def kind
+      action_name == REPLY_ACTION ? :reply : :tool_calls
+    end
+
+    def tool_calls?
+      kind == :tool_calls
+    end
+
+    def reply?
+      kind == :reply
+    end
+
+    # The tool calls the interrupt is holding, as `Assistants#tool_calls_under_review` reports them.
+    # Empty when the pause is on a reply.
+    def tool_calls
+      return [] unless tool_calls?
+
+      tool_call_interrupt.tool_calls
+    end
+
+    # The held draft, or nil when the pause is not on a reply.
+    def reply
+      return nil unless reply?
+
+      @reply ||= Reply.new(
+        content: action_args["content"],
+        allowed_decisions:,
+        description: action_requests.first["description"],
+        interrupt_id:
+      )
+    end
+
+    # The `command.resume` that sends `decisions` to this pause, keyed by its interrupt. LangGraph
+    # applies a keyed resume to that interrupt only: keyed by one that is no longer pending -- the
+    # thread moved on between reading this pause and resuming it -- it decides nothing, and the
+    # thread stays paused on the newer interrupt. An interrupt reported without an id can only be
+    # resumed unkeyed.
+    def resume(decisions)
+      interrupt_id.blank? ? { decisions: } : { interrupt_id => { decisions: } }
+    end
+
+    # Whether `run`, the response to a keyed resume of this pause, decided nothing because the
+    # interrupt was gone by the time the resume arrived. `run_id` is the run Assistants created for
+    # the resume, and the block reads the thread's state, only when it is needed.
+    #
+    # Such a resume comes back paused on the newer interrupt, exactly as a resume that was applied
+    # and paused again does -- a turn's tool calls decided, then the run's reply held. What tells
+    # them apart is who wrote the thread's latest checkpoint: Assistants records each run's id in
+    # the metadata of the checkpoints it writes, and a resume that decided nothing writes none, so
+    # the pause it reports still sits on a checkpoint an earlier run wrote.
+    #
+    # Best-effort, and only ever true on that evidence: without the run's id, the checkpoint's, or a
+    # state still on the reported pause (a new message may already have moved it on), or when the
+    # state cannot be read, it is false and the result stands as returned. That a stale decision is
+    # never applied is guaranteed by the keyed resume, not by this.
+    def unapplied_resume?(run:, run_id:)
+      paused_on = self.class.from_run(run)&.interrupt_id
+      return false if interrupt_id.blank? || run_id.blank? || paused_on.blank? || paused_on == interrupt_id
+
+      state = yield
+      writer = state.dig("metadata", "run_id")
+      self.class.from_thread_state(state)&.interrupt_id == paused_on && writer.present? && writer != run_id
+    rescue
+      false
+    end
+
+    # The `command.resume` decisions for a review of this pause, validated against what the
+    # interrupt allows before anything is built, raising `Assistants::ThreadResumptionError`.
+    #
+    # For a reply, `reviews` is a single review hash. For tool calls, it is either a hash of reviews
+    # keyed by tool call id, as `Assistants#review_tool_calls` has always taken them, or a list of
+    # reviews that each carry their tool call's `id`.
+    def decisions(reviews)
+      return [reply_decision(reviews)] if reply?
+
+      reviews = tool_call_reviews(reviews)
+      ToolCallReviewValidator.new.validate!(tool_calls: reviews, tool_calls_under_review: tool_calls)
+      tool_call_interrupt.decisions(reviews)
+    end
+
+  private
+
+    def tool_call_interrupt
+      @tool_call_interrupt ||= ToolCallReviewInterrupt.new(
+        "interrupts" => [@interrupt],
+        "values" => { "messages" => @messages }
+      )
+    end
+
+    def interrupt_value
+      @interrupt["value"] || {}
+    end
+
+    def action_requests
+      Array(interrupt_value["action_requests"])
+    end
+
+    def action_name
+      action_requests.first&.dig("name")
+    end
+
+    def action_args
+      action_requests.first["args"] || {}
+    end
+
+    def allowed_decisions
+      review_config = Array(interrupt_value["review_configs"]).find do |config|
+        config["action_name"] == action_name
+      end
+
+      Array(review_config&.dig("allowed_decisions")).map(&:to_s) & REPLY_DECISIONS
+    end
+
+    def tool_call_reviews(reviews)
+      return reviews unless reviews.is_a?(Array)
+
+      reviews.each_with_object({}) do |review, by_id|
+        unless review.is_a?(Hash) && review.with_indifferent_access[:id].present?
+          raise_error!("Each tool call review in a list must be a hash with the tool call's `id`")
+        end
+
+        review = review.with_indifferent_access
+        id = review[:id].to_s
+        raise_error!("Tool call `#{id}` is reviewed more than once") if by_id.key?(id)
+
+        by_id[id] = review.except(:id)
+      end
+    end
+
+    # A reply is a single action, so it is reviewed with a single hash.
+    def reply_decision(review)
+      raise_error!("The reply review must be a hash") unless review.is_a?(Hash)
+
+      review = review.with_indifferent_access
+      action = review[:action].to_s
+
+      unless allowed_decisions.include?(action)
+        raise_error!("Invalid review action `#{action}` for the reply; allowed: #{allowed_decisions.join(', ')}")
+      end
+
+      case action
+      when "approve" then ReviewDecision.approve
+      when "edit"
+        ReviewDecision.edit(REPLY_ACTION, { "content" => text!(review, :content, action:, required: true) })
+      when "reject" then ReviewDecision.reject(text!(review, :message, action:, required: false))
+      end
+    end
+
+    # A required field must be non-blank text; an optional one may be absent, but not something other
+    # than a String.
+    def text!(review, field, action:, required:)
+      value = review[field]
+      case ReviewDecision.message_problem(value, required:)
+      when :missing then raise_error!("A `#{action}` review of the reply must include a non-empty `#{field}`")
+      when :not_string then raise_error!("`#{field}` for the reply review must be a string")
+      end
+
+      value
+    end
+
+    def raise_error!(message)
+      raise Assistants::ThreadResumptionError, message
+    end
+  end
+end

data/lib/nitro_intelligence/railtie.rb

@@ -0,0 +1,9 @@
+require "nitro_intelligence/deprecator"
+
+module NitroIntelligence
+  class Railtie < ::Rails::Railtie
+    initializer "nitro_intelligence.deprecator" do |app|
+      app.deprecators[:nitro_intelligence] = NitroIntelligence.deprecator
+    end
+  end
+end

data/lib/nitro_intelligence/reporter.rb

@@ -35,12 +35,13 @@ module NitroIntelligence
       response
     end
 
-    def score(trace_id:, name:, value:, id: "#{trace_id}-#{name}")
+    def score(trace_id:, name:, value:, id: "#{trace_id}-#{name}", data_type: :numeric)
       @project_client.observability_client.create_score(
         id:,
         trace_id:,
         name:,
         value:,
+        data_type:,
         environment: NitroIntelligence.environment
       )
     end

data/lib/nitro_intelligence/review_decision.rb

@@ -0,0 +1,34 @@
+module NitroIntelligence
+  # The `command.resume` decisions a review sends, and the check on the `message` a decision
+  # carries, shared by tool call reviews and reply reviews. Each caller keeps its own
+  # error wording, so this reports what is wrong rather than raising.
+  module ReviewDecision
+  module_function
+
+    def approve
+      { "type" => "approve" }
+    end
+
+    def edit(name, args)
+      { "type" => "edit", "edited_action" => { "name" => name, "args" => args } }
+    end
+
+    # The middleware falls back to its own wording when a rejection carries no reason.
+    def reject(message)
+      message.nil? ? { "type" => "reject" } : { "type" => "reject", "message" => message }
+    end
+
+    def respond(message)
+      { "type" => "respond", "message" => message }
+    end
+
+    # What is wrong with a decision's `message`, or nil: `:missing` when a required one is absent
+    # or blank, `:not_string` when one is given as anything but a String.
+    def message_problem(message, required:)
+      return (:missing if required) if message.nil?
+      return :not_string unless message.is_a?(String)
+
+      :missing if required && message.blank?
+    end
+  end
+end

data/lib/nitro_intelligence/run_result.rb

@@ -0,0 +1,129 @@
+require "nitro_intelligence/pending_review"
+
+module NitroIntelligence
+  # The outcome of one `/runs/wait`: either the run ended, possibly with a reply, or it paused on a
+  # review.
+  #
+  # A run has at most one reply: its final message, an AI message with text and no tool calls. Text
+  # the model writes alongside tool calls is working text, never the reply. A paused run's last AI
+  # message is a draft awaiting review, so `#reply` is nil whenever the run paused; a reply is final
+  # only once a run ends without `__interrupt__`.
+  class RunResult
+    # How the platform delivered the reply through the assistant's delivery tool, read from the
+    # reply's `response_metadata.delivery` stamp. `status` is "delivered" (with `result`, what the
+    # tool returned, and `delivered_at`), "failed" (with the tool's `error` and `failed_at`), or
+    # "pending": the platform stamps a settled reply "pending" just before it delivers it, so a
+    # finished run still showing it was cut off before delivery recorded an outcome. Treat a
+    # pending reply as not sent; the next customer message removes it and the model answers both. A
+    # field the stamp does not carry, or carries as the wrong type, is nil.
+    Delivery = Struct.new(:status, :tool, :attempts, :error, :result, :delivered_at, :failed_at,
+                          keyword_init: true) do
+      def delivered?
+        status == "delivered"
+      end
+
+      def failed?
+        status == "failed"
+      end
+
+      def pending?
+        status == "pending"
+      end
+    end
+
+    # The `response_metadata.review` type the platform stamps on a draft when it pauses on it.
+    PENDING_REVIEW = "pending".freeze
+
+    # The response exactly as Assistants returned it.
+    attr_reader :raw
+
+    def initialize(run)
+      @raw = run.to_h
+    end
+
+    def interrupted?
+      Array(raw["__interrupt__"]).any?
+    end
+
+    # What the paused run is waiting on, or nil when it did not pause.
+    def review
+      return @review if defined?(@review)
+
+      @review = PendingReview.from_run(raw)
+    end
+
+    # The run's messages as Assistants reports them, oldest first.
+    def messages
+      Array(raw["messages"])
+    end
+
+    # The text of the run's reply, always a String: content given as blocks is reduced to its text.
+    # Nil while the run is paused, and when it ended without one: a rejected draft is removed,
+    # leaving a tool result or the human's message last, and an earlier turn's text is never the
+    # reply. Blank text is no reply.
+    def reply
+      reply_message && text(reply_message["content"]).presence
+    end
+
+    # The reply's delivery, or nil when the reply carries no delivery stamp: no reply, or no
+    # delivery tool configured for the assistant.
+    def delivery
+      return @delivery if defined?(@delivery)
+
+      stamp = reply_message&.dig("response_metadata", "delivery")
+      @delivery = stamp.is_a?(Hash) ? build_delivery(stamp) : nil
+    end
+
+  private
+
+    # The run's last message, when the run ended and that message is the assistant's reply: an AI
+    # message with no tool calls. A draft still stamped as awaiting review is never the reply, even
+    # in a response that reports no pause.
+    def reply_message
+      return nil if interrupted?
+
+      message = messages.last
+      return nil unless message.is_a?(Hash)
+      return nil if message["type"].present? && message["type"] != "ai"
+      return nil if Array(message["tool_calls"]).any?
+      return nil if awaiting_review?(message)
+
+      message
+    end
+
+    def awaiting_review?(message)
+      review = message.dig("response_metadata", "review")
+      review.is_a?(Hash) && review["type"] == PENDING_REVIEW
+    end
+
+    # A message's content is a string, or a list of content blocks. Its text is the string, or the
+    # bare strings and `text` blocks joined, as the platform reads it (LangChain's `message.text`);
+    # other blocks -- tool use, reasoning, images -- are not part of the reply.
+    def text(content)
+      return content if content.is_a?(String)
+      return nil unless content.is_a?(Array)
+
+      content.filter_map do |block|
+        next block if block.is_a?(String)
+
+        block["text"] if block.is_a?(Hash) && block["type"] == "text" && block["text"].is_a?(String)
+      end.join
+    end
+
+    def build_delivery(stamp)
+      Delivery.new(
+        status: string_or_nil(stamp["status"]),
+        tool: string_or_nil(stamp["tool"]),
+        attempts: stamp["attempts"].is_a?(Integer) ? stamp["attempts"] : nil,
+        error: string_or_nil(stamp["error"]),
+        result: stamp["result"],
+        delivered_at: string_or_nil(stamp["delivered_at"]),
+        failed_at: string_or_nil(stamp["failed_at"])
+      )
+    end
+
+    def string_or_nil(value)
+      value.is_a?(String) ? value : nil
+    end
+  end
+end

data/lib/nitro_intelligence/tool_call_review_interrupt.rb

@@ -1,4 +1,5 @@
 require "active_support/core_ext/hash/indifferent_access"
+require "nitro_intelligence/review_decision"
 
 module NitroIntelligence
   # The tool calls one interrupt is holding, and the resume payload that answers them.
@@ -68,14 +69,10 @@ module NitroIntelligence
       review = (review || {}).with_indifferent_access
 
       case review[:action].to_s
-      when "approve"
-        { "type" => "approve" }
-      when "edit"
-        { "type" => "edit", "edited_action" => edited_action(tool_call, review) }
-      when "reject"
-        review[:message].nil? ? { "type" => "reject" } : { "type" => "reject", "message" => review[:message] }
-      when "respond"
-        { "type" => "respond", "message" => review[:message] }
+      when "approve" then ReviewDecision.approve
+      when "edit" then ReviewDecision.edit(tool_call["name"], edited_args(tool_call, review))
+      when "reject" then ReviewDecision.reject(review[:message])
+      when "respond" then ReviewDecision.respond(review[:message])
       else
         raise Assistants::ThreadResumptionError,
               "Tool call #{tool_call['id']} has no review naming `approve`, `edit`, `reject` or `respond`"
@@ -84,11 +81,8 @@ module NitroIntelligence
 
     # Edited arguments are merged over the call the model made, so a reviewer changing one of them
     # does not have to restate the rest -- and cannot drop one by omitting it.
-    def edited_action(tool_call, review)
-      {
-        "name" => tool_call["name"],
-        "args" => tool_call["args"].merge(review[:args] || {}),
-      }
+    def edited_args(tool_call, review)
+      tool_call["args"].merge(review[:args] || {})
     end
 
     def interrupt_value

data/lib/nitro_intelligence/tool_call_review_validator.rb

@@ -1,4 +1,5 @@
 require "active_support/core_ext/hash/indifferent_access"
+require "nitro_intelligence/review_decision"
 
 module NitroIntelligence
   # The reviews a caller submitted, checked against the tool calls the interrupt is holding, before
@@ -72,15 +73,10 @@ module NitroIntelligence
     end
 
     def validate_message!(tool_call_id:, review:, required:)
-      message = review[:message]
-
-      if message.nil?
-        raise_error!("Review for tool call #{tool_call_id} must include a message") if required
-        return
+      case ReviewDecision.message_problem(review[:message], required:)
+      when :missing then raise_error!("Review for tool call #{tool_call_id} must include a message")
+      when :not_string then raise_error!("Message for tool call #{tool_call_id} must be a string")
       end
-
-      raise_error!("Message for tool call #{tool_call_id} must be a string") unless message.is_a?(String)
-      raise_error!("Review for tool call #{tool_call_id} must include a message") if required && message.blank?
     end
 
     def validate_completeness!(submitted_tool_call_ids:, tool_calls_under_review:)