legion-llm 0.9.14 → 0.9.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cc06bf006614fbb7a1052b368912ef58744e5b6509680c163c1b7ce0009e87d8
-  data.tar.gz: 91c96c5fee56c7fb4804ea3d58eb908cec12539a75eba11348e842be26509343
+  metadata.gz: 206afbe8609bb8ed7df111d216967aafba55b0d523d5939aad024f169e43f5ef
+  data.tar.gz: 283f42c3d5b9ba07aa7857aad3e6d1f30b7559f35282f4a1d00986ea4ab2c646
 SHA512:
-  metadata.gz: fc3d9e91c66c0128bde4ffc434c19e6e75a21cb14a74cafe206235750ef402380a250c928358dfc7702f11f7259ffc46e5976a2abcf360c508bf8ceb7dca6033
-  data.tar.gz: 5d1a42619cc8e0d6e086b82245356b69790df2f7601313046e5d09e301ada70483f83ab53b4f6e592f5294c94f631904c7d46847131981542db173950e8e408c
+  metadata.gz: 54b3e821013f9ba6f73019907821e85d1aaacc766e8942767f5e6a9630d66757c1d16a8e1b6643054895b1e5de229245e45ebf562f42bdec1cfac8f609024a5c
+  data.tar.gz: 45d349d01bef14e68527aa0c8108c4d08f71e05b63c87c331e377703bdacfcee431b903fe72dc2ad48b10c2f73a67523e9c67a0da1dd46b4b9cf3e041c290671

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Legion LLM Changelog
 
+## [0.9.15] - 2026-05-08
+
+### Fixed
+- Normalize structured user message content before RAG query handling, preventing multipart API messages from crashing trivial-query detection or reaching Apollo as arrays.
+- Normalize empty string tool-call arguments to `{}` and make sticky tool history tolerate non-hash argument payloads without dropping state writes.
+- Pass non-executable API client tool calls through to callers as streaming `tool-call` events instead of dispatching them server-side as failed tool executions.
+- Add runtime logging for client tool receipt, native tool injection summaries, registry-injection skips, and returned tool-call SSE emission.
+
 ## [0.9.14] - 2026-05-08
 
 ### Fixed

data/lib/legion/llm/api/native/helpers.rb

@@ -347,6 +347,56 @@ module Legion
                 stream << "event: #{event_name}\ndata: #{Legion::JSON.dump(payload)}\n\n"
               end
 
+              define_method(:emit_response_tool_call_events) do |stream, pipeline_response|
+                tool_calls = extract_tool_calls(pipeline_response)
+                return if tool_calls.empty?
+
+                timeline_tool_call_ids = Array(pipeline_response.timeline).filter_map do |event|
+                  key = event[:key].to_s
+                  next unless key.start_with?('tool:execute:')
+
+                  data = event[:data].is_a?(Hash) ? event[:data] : {}
+                  data[:tool_call_id] || data['tool_call_id']
+                end
+
+                emitted = 0
+                skipped_timeline = 0
+                request_id = pipeline_response.respond_to?(:request_id) ? pipeline_response.request_id : 'unknown'
+                conversation_id = pipeline_response.respond_to?(:conversation_id) ? pipeline_response.conversation_id : 'none'
+
+                tool_calls.each do |tool_call|
+                  tool_call_id = tool_call[:id] || tool_call['id']
+                  if tool_call_id && timeline_tool_call_ids.include?(tool_call_id)
+                    skipped_timeline += 1
+                    next
+                  end
+
+                  tool_name = tool_call[:name] || tool_call['name']
+                  next if tool_name.to_s.empty?
+
+                  log.info(
+                    "[llm][api][tools] action=returned_tool_call_sse request_id=#{request_id || 'unknown'} " \
+                    "conversation_id=#{conversation_id || 'none'} tool_call_id=#{tool_call_id || 'none'} name=#{tool_name} " \
+                    "args_class=#{(tool_call[:arguments] || tool_call['arguments'] || {}).class}"
+                  )
+                  emit_sse_event(stream, 'tool-call', {
+                                   toolCallId: tool_call_id,
+                                   toolName:   tool_name,
+                                   args:       tool_call[:arguments] || tool_call['arguments'] || {},
+                                   timestamp:  Time.now.utc.iso8601
+                                 })
+                  emitted += 1
+                end
+
+                names = tool_calls.map { |tool_call| tool_call[:name] || tool_call['name'] }.compact
+                names = names.first(30).join(',') + (names.size > 30 ? ",+#{names.size - 30}more" : '')
+                log.info(
+                  "[llm][api][tools] action=returned_tool_calls_complete request_id=#{request_id || 'unknown'} " \
+                  "conversation_id=#{conversation_id || 'none'} total=#{tool_calls.size} emitted=#{emitted} " \
+                  "skipped_timeline=#{skipped_timeline} names=#{names.empty? ? 'none' : names}"
+                )
+              end
+
               define_method(:emit_timeline_tool_events) do |stream, pipeline_response, skip_tool_results: false|
                 timeline = Array(pipeline_response.timeline)
                 log.debug("[llm][api][helpers] emit_timeline_tool_events count=#{timeline.size} skip_tool_results=#{skip_tool_results}")

data/lib/legion/llm/api/native/inference.rb

@@ -72,7 +72,13 @@ module Legion
                 build_client_tool_class(ts[:name].to_s, ts[:description].to_s, ts[:parameters] || ts[:input_schema])
               end
 
-              log.debug("[llm][api][inference] action=tools_built client_tools=#{tool_declarations.size}")
+              client_tool_names = tool_declarations.map(&:name)
+              client_tool_summary = client_tool_names.empty? ? 'none' : client_tool_names.first(30).join(',')
+              client_tool_summary = "#{client_tool_summary},+#{client_tool_names.size - 30}more" if client_tool_names.size > 30
+              log.info(
+                "[llm][api][tools] action=client_tools_built request_id=#{request_id} " \
+                "conversation_id=#{conversation_id || 'none'} count=#{tool_declarations.size} names=#{client_tool_summary}"
+              )
 
               streaming = body[:stream] == true && request.preferred_type.to_s.include?('text/event-stream')
               effective_caller = build_server_caller(source: 'api', path: request.path, env: env,
@@ -155,6 +161,7 @@ module Legion
                     emit_sse_event(out, 'text-delta', { delta: text })
                   end
 
+                  emit_response_tool_call_events(out, pipeline_response)
                   emit_timeline_tool_events(out, pipeline_response, skip_tool_results: !executor.tool_event_handler.nil?)
 
                   enrichments = pipeline_response.enrichments

data/lib/legion/llm/call/dispatch.rb

@@ -332,11 +332,13 @@ module Legion
 
         def parse_arguments(arguments)
           return arguments unless arguments.is_a?(String)
+          return {} if arguments.strip.empty?
 
-          Legion::JSON.parse(arguments)
+          parsed = Legion::JSON.parse(arguments)
+          parsed.is_a?(Hash) ? parsed : {}
         rescue StandardError => e
           handle_exception(e, level: :debug, handled: true, operation: 'llm.dispatch.parse_arguments')
-          arguments
+          {}
         end
       end
     end

data/lib/legion/llm/inference/executor.rb

@@ -674,6 +674,7 @@ module Legion
               log.debug "[llm][executor] action=native_tool_loop.complete rounds=#{round} reason=no_tool_calls"
               return result
             end
+            return client_passthrough_tool_loop_result(result, tool_calls, round) if tool_calls.any? { |tool_call| client_passthrough_tool_call?(tool_call) }
 
             round += 1
             tool_names = tool_calls.map { |tc| tc[:name] }.join(',')
@@ -697,6 +698,7 @@ module Legion
             Array(@request.tools).each { |tool| add_native_tool_definition(definitions, tool) }
             add_registry_tool_definitions(definitions) if registry_tool_injection_requested?
             log.debug "[llm][executor] action=native_tool_definitions.built count=#{definitions.size}"
+            log_native_tool_definitions(definitions)
             definitions
           end
         end
@@ -728,9 +730,7 @@ module Legion
         end
 
         def add_registry_tool_definitions(definitions)
-          return unless Legion::Settings::Extensions.respond_to?(:tools) &&
-                        Legion::Settings::Extensions.respond_to?(:filter_tools)
-          return unless Array(Legion::Settings::Extensions.tools).any? || @triggered_tools.any?
+          return unless registry_tool_sources_available?
 
           add_settings_extensions_tool_definitions(definitions)
         rescue StandardError => e
@@ -841,7 +841,7 @@ module Legion
                        else
                          {}
                        end
-          normalized[:arguments] ||= {}
+          normalized[:arguments] = normalize_tool_arguments(normalized[:arguments])
           normalized[:id] ||= "call_#{SecureRandom.hex(12)}"
           normalized
         end

data/lib/legion/llm/inference/steps/rag_context.rb

@@ -127,11 +127,12 @@ module Legion
           def estimate_utilization
             return 0.0 if @request.tokens[:max].nil? || @request.tokens[:max].zero?
 
-            message_tokens = @request.messages.sum { |m| (m[:content]&.length || 0) / 4 }
+            message_tokens = @request.messages.sum { |m| content_text(message_content(m)).length / 4 }
             message_tokens.to_f / @request.tokens[:max]
           end
 
           def trivial_query?(query)
+            query = content_text(query)
             max_chars = rag_setting(:trivial_max_chars, 20)
             patterns  = rag_setting(:trivial_patterns, [])
 
@@ -247,7 +248,34 @@ module Legion
 
           def extract_query
             @request.messages.select { |m| Legion::LLM::Settings.config_value(m, :role).to_s == 'user' }
-                             .then { |messages| Legion::LLM::Settings.config_value(messages.last, :content) }
+                             .then { |messages| content_text(message_content(messages.last)) }
+          end
+
+          def message_content(message)
+            Legion::LLM::Settings.config_value(message, :content)
+          end
+
+          def content_text(content)
+            case content
+            when nil
+              ''
+            when String
+              content
+            when Array
+              content.filter_map { |entry| content_text(entry) }.join
+            when Hash
+              type = content[:type] || content['type']
+              return '' unless type.nil? || type.to_s == 'text'
+
+              text = if content.key?(:text) || content.key?('text')
+                       content[:text] || content['text']
+                     else
+                       content[:content] || content['content']
+                     end
+              content_text(text)
+            else
+              content.respond_to?(:text) ? content.text.to_s : content.to_s
+            end
           end
 
           def apply_gaia_context_limit(limit, strategy:)

data/lib/legion/llm/inference/steps/sticky_persist.rb

@@ -17,7 +17,7 @@ module Legion
             access_token private_key secret_key auth_token credential
           ].freeze
 
-          def step_sticky_persist # rubocop:disable Metrics/AbcSize,Metrics/MethodLength,Metrics/PerceivedComplexity
+          def step_sticky_persist # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
             return unless sticky_persist_ready?
 
             conv_id        = @request.conversation_id
@@ -100,7 +100,7 @@ module Legion
                   tool:   entry[:tool_name],
                   runner: runner_key,
                   turn:   @sticky_turn_snapshot,
-                  args:   sanitize_args(truncate_args(entry[:args] || {})),
+                  args:   sanitize_args(truncate_args(normalize_history_args(entry[:args]))),
                   result: entry[:result].to_s[0, max_result_length],
                   error:  entry[:error] || false
                 }
@@ -162,6 +162,25 @@ module Legion
             end
           end
 
+          def normalize_history_args(args)
+            case args
+            when nil
+              {}
+            when Hash
+              args
+            when String
+              return {} if args.strip.empty?
+
+              parsed = Legion::JSON.parse(args)
+              parsed.is_a?(Hash) ? parsed : {}
+            else
+              args.respond_to?(:to_h) ? args.to_h : {}
+            end
+          rescue StandardError => e
+            handle_exception(e, level: :debug, handled: true, operation: 'llm.pipeline.step_sticky_persist.normalize_args')
+            {}
+          end
+
           def sanitize_args(args)
             args.each_with_object({}) do |(k, v), h|
               h[k] = SENSITIVE_PARAM_NAMES.include?(k.to_s.downcase) ? '[REDACTED]' : v

data/lib/legion/llm/inference/steps/tool_calls.rb

@@ -32,6 +32,20 @@ module Legion
               source = find_tool_source(tool_name)
               next unless source
 
+              if client_passthrough_source?(source)
+                log.info(
+                  "[llm][tools] client_passthrough request_id=#{@request.id} " \
+                  "tool_call_id=#{tool_call_id || 'none'} name=#{tool_name}"
+                )
+                log_step_debug(
+                  :tool_calls,
+                  :client_passthrough,
+                  tool_call_id: tool_call_id || 'none',
+                  tool_name:    tool_name
+                )
+                next
+              end
+
               # Skip builtin tools; native providers handle provider-owned tools.
               if source[:type] == :builtin
                 log.info(
@@ -123,6 +137,102 @@ module Legion
             { type: :builtin }
           end
 
+          def client_passthrough_source?(source)
+            source[:type] == :client && source[:executable] != true
+          end
+
+          def client_passthrough_tool_call?(tool_call)
+            client_passthrough_source?(find_tool_source(tool_call[:name]))
+          end
+
+          def client_passthrough_tool_loop_result(result, tool_calls, round)
+            result[:tool_calls] = tool_calls
+            log.debug "[llm][executor] action=native_tool_loop.complete rounds=#{round} reason=client_passthrough"
+            result
+          end
+
+          def normalize_tool_arguments(arguments)
+            case arguments
+            when nil
+              {}
+            when Hash
+              arguments
+            when String
+              return {} if arguments.strip.empty?
+
+              parsed = Legion::JSON.parse(arguments)
+              parsed.is_a?(Hash) ? parsed : {}
+            else
+              arguments.respond_to?(:to_h) ? arguments.to_h : {}
+            end
+          rescue StandardError => e
+            handle_exception(e, level: :debug, handled: true, operation: 'llm.pipeline.normalize_tool_arguments')
+            {}
+          end
+
+          def registry_tool_sources_available?
+            unless Legion::Settings::Extensions.respond_to?(:tools) &&
+                   Legion::Settings::Extensions.respond_to?(:filter_tools)
+              log_tool_injection_skip(:settings_extensions_unavailable)
+              return false
+            end
+
+            settings_tool_count = Array(Legion::Settings::Extensions.tools).size
+            if settings_tool_count.zero? && @triggered_tools.empty?
+              log_tool_injection_skip(:no_settings_or_triggered_tools, settings_tool_count: settings_tool_count)
+              return false
+            end
+
+            true
+          end
+
+          def log_tool_injection_skip(reason, settings_tool_count: nil)
+            log.info(
+              "[llm][tools][inject] action=registry_skipped request_id=#{request_log_value(:id, 'unknown')} " \
+              "conversation_id=#{request_log_value(:conversation_id, 'none') || 'none'} reason=#{reason} " \
+              "settings_tools=#{settings_tool_count || 'unknown'} triggered_tools=#{@triggered_tools.size} " \
+              "requested_tools=#{requested_deferred_tool_names.size}"
+            )
+          rescue StandardError => e
+            handle_exception(e, level: :debug, handled: true, operation: 'llm.pipeline.log_tool_injection_skip')
+          end
+
+          def log_native_tool_definitions(definitions)
+            log.info(
+              "[llm][tools][inject] action=native_tool_definitions request_id=#{request_log_value(:id, 'unknown')} " \
+              "conversation_id=#{request_log_value(:conversation_id, 'none') || 'none'} provider=#{@resolved_provider || 'unknown'} " \
+              "model=#{@resolved_model || 'unknown'} total=#{definitions.size} sources=#{format_tool_source_counts(definitions)} " \
+              "client_request_tools=#{Array(request_log_value(:tools, [])).size} triggered_tools=#{@triggered_tools.size} " \
+              "requested_tools=#{requested_deferred_tool_names.size} names=#{format_tool_names(definitions.map(&:name))}"
+            )
+          rescue StandardError => e
+            handle_exception(e, level: :debug, handled: true, operation: 'llm.pipeline.log_native_tool_definitions')
+          end
+
+          def format_tool_source_counts(definitions)
+            counts = definitions.each_with_object(Hash.new(0)) do |definition, memo|
+              source = definition.respond_to?(:source) ? definition.source : {}
+              key = source.is_a?(Hash) ? (source[:type] || source['type'] || :unknown) : :unknown
+              memo[key] += 1
+            end
+            return 'none' if counts.empty?
+
+            counts.map { |key, count| "#{key}:#{count}" }.join(',')
+          end
+
+          def format_tool_names(names, limit = 30)
+            names = Array(names).map(&:to_s).reject(&:empty?)
+            return 'none' if names.empty?
+
+            visible = names.first(limit)
+            suffix = names.size > limit ? ",+#{names.size - limit}more" : ''
+            "#{visible.join(',')}#{suffix}"
+          end
+
+          def request_log_value(method_name, fallback)
+            @request.respond_to?(method_name) ? @request.public_send(method_name) : fallback
+          end
+
           def describe_tool_source(source)
             case source[:type]
             when :mcp

data/lib/legion/llm/version.rb

@@ -2,6 +2,6 @@
 
 module Legion
   module LLM
-    VERSION = '0.9.14'
+    VERSION = '0.9.15'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legion-llm
 version: !ruby/object:Gem::Version
-  version: 0.9.14
+  version: 0.9.15
 platform: ruby
 authors:
 - Esity