legion-llm 0.6.27 → 0.6.28

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b85e3ef4ae750eb9aa512fcc0ce3b2de89fc13828dcdcef7ef558859a422e8f1
-  data.tar.gz: 4617e27eec5e4292146338dc4a593e4e0762838b6c1c24c925fedca472775aae
+  metadata.gz: 012c2dfa0bbf9488deb34c1207b52bf7a44a60e79f9bffcdde266b00fe342488
+  data.tar.gz: c685676026b1ab8fff5ad83dca76a01f156396f2619d9627c69c13427ea4f013
 SHA512:
-  metadata.gz: c93930484d5c716d2429490ca192bd9e758fd291aa81942a43309e8ab72c9accb1e472241a47255c24e590320748b54f8e71b678b4dc204e78ac975a1b0b7188
-  data.tar.gz: 62453e4f583641b9c2e4e714f120def689548795baa7609844c8d8069f5b577ee644025ac18b324c2ff029a7163b82bde78426996c5bb6e062573aaa0d74c170
+  metadata.gz: cf27f45ca8703a69b7b18f774298b23071ca588666aa1d5aadcb9811966203be14bbce211b1f8d26a03ae3827a1dee05883003987317f5af58e70afd6e1e6ed4
+  data.tar.gz: 6d02e8c9b4ceba43bd78611abd7e8969b2c154dd820a981ff9a464b99e43935915060419b2d0ed9400e18629dc4e126f0fe760aaa7ba10592a5b2adab4183bea

data/CHANGELOG.md

@@ -5,6 +5,14 @@
 ### Added
 - Broker soft consumer in Providers module — tries Identity::Broker before Settings for all provider credentials (Phase 8 Wave 2)
 
+## [0.6.28] - 2026-04-09
+
+### Added
+- `Legion::LLM::Tools::Interceptor` — extensible tool call interception registry
+- `Legion::LLM::Tools::Interceptors::PythonVenv` — rewrites `python3`/`pip3` commands to Legion-managed venv when available
+- ToolAdapter#execute calls Interceptor.intercept before dispatching to tool class
+- Interceptors loaded automatically during `Legion::LLM.start`
+
 ## [0.6.26] - 2026-04-09
 
 ### Changed

data/lib/legion/llm/pipeline/tool_adapter.rb

@@ -1,85 +1,13 @@
 # frozen_string_literal: true
 
-require 'ruby_llm'
-require 'legion/logging/helper'
+# Backwards-compatibility shim — canonical location is legion/llm/tools/adapter.rb
+require_relative '../tools/adapter'
 
 module Legion
   module LLM
     module Pipeline
-      class ToolAdapter < RubyLLM::Tool
-        include Legion::Logging::Helper
-
-        MAX_TOOL_NAME_LENGTH = 64
-
-        def initialize(tool_class)
-          @tool_class = tool_class
-          raw_name = tool_class.respond_to?(:tool_name) ? tool_class.tool_name : tool_class.name.to_s
-          @tool_name = sanitize_tool_name(raw_name)
-          @tool_desc = tool_class.respond_to?(:description) ? tool_class.description.to_s : ''
-          @tool_schema = tool_class.respond_to?(:input_schema) ? tool_class.input_schema : nil
-          super()
-        end
-
-        def name
-          @tool_name
-        end
-
-        def description
-          @tool_desc
-        end
-
-        def params_schema
-          return @params_schema if defined?(@params_schema)
-
-          @params_schema = (RubyLLM::Utils.deep_stringify_keys(@tool_schema) if @tool_schema.is_a?(Hash))
-        end
-
-        def execute(**args)
-          log.info("[llm][tools] adapter.execute name=#{@tool_name} arguments=#{summarize_payload(args)}")
-          result = @tool_class.call(**args)
-          content = extract_content(result)
-          log.info("[llm][tools] adapter.result name=#{@tool_name} output=#{summarize_payload(content)}")
-          content
-        rescue StandardError => e
-          handle_exception(e, level: :warn, operation: 'llm.pipeline.tool_adapter.execute', tool_name: @tool_name)
-          "Tool error: #{e.message}"
-        end
-
-        private
-
-        def extract_content(result)
-          # MCP::Tool::Response — has .content array of {type: 'text', text: '...'}
-          if result.respond_to?(:content) && result.content.is_a?(Array)
-            result.content.filter_map { |c| c[:text] || c['text'] || c.to_s }.join("\n")
-          elsif result.is_a?(Hash) && result[:content].is_a?(Array)
-            result[:content].filter_map { |c| c[:text] || c['text'] }.join("\n")
-          elsif result.is_a?(Hash)
-            Legion::JSON.dump(result)
-          elsif result.is_a?(String)
-            result
-          else
-            result.to_s
-          end
-        end
-
-        def summarize_payload(payload)
-          payload.to_s[0, 200].inspect
-        end
-
-        # Bedrock constraints: [a-zA-Z0-9_-]+ and max 64 chars.
-        # Falls back to a stable name derived from the class object_id if sanitization yields
-        # an empty string (e.g. all chars stripped), ensuring the result always satisfies the
-        # at-least-one-character requirement.
-        def sanitize_tool_name(raw)
-          name = raw.tr('.', '_')
-          name = name.gsub(/[^a-zA-Z0-9_-]/, '') # strip ?, !, etc.
-          name = name[0, MAX_TOOL_NAME_LENGTH] if name.length > MAX_TOOL_NAME_LENGTH
-          name.empty? ? "tool_#{@tool_class.object_id}" : name
-        end
-      end
-
-      # Backwards compatibility alias
-      McpToolAdapter = ToolAdapter
+      ToolAdapter = Tools::Adapter
+      McpToolAdapter = Tools::Adapter
     end
   end
 end

data/lib/legion/llm/pipeline/tool_dispatcher.rb

@@ -1,132 +1,12 @@
 # frozen_string_literal: true
 
-require 'legion/logging/helper'
+# Backwards-compatibility shim — canonical location is legion/llm/tools/dispatcher.rb
+require_relative '../tools/dispatcher'
+
 module Legion
   module LLM
     module Pipeline
-      module ToolDispatcher
-        extend Legion::Logging::Helper
-
-        module_function
-
-        def dispatch(tool_call:, source:, exchange_id: nil)
-          start_time = Time.now
-
-          # Check for settings override (LEX replaces MCP)
-          if source[:type] == :mcp
-            override = check_override(tool_call[:name])
-            if override
-              overridden_source = source
-              source = override.merge(overridden_from: overridden_source)
-            end
-          end
-
-          result = case source[:type]
-                   when :mcp
-                     mcp_result = dispatch_mcp(tool_call, source)
-                     run_shadow(tool_call, source, mcp_result)
-                     mcp_result
-                   when :extension
-                     dispatch_extension(tool_call, source)
-                   when :builtin
-                     dispatch_builtin(tool_call, source)
-                   else
-                     { status: :error, error: "Unknown tool source type: #{source[:type]}" }
-                   end
-
-          result.merge(
-            source:      source,
-            exchange_id: exchange_id,
-            duration_ms: ((Time.now - start_time) * 1000).to_i
-          )
-        rescue StandardError => e
-          handle_exception(e, level: :warn, operation: 'llm.pipeline.tool_dispatcher.dispatch_tool_call', tool_name: tool_name)
-          { status: :error, error: e.message, source: source, exchange_id: exchange_id }
-        end
-
-        def check_override(tool_name)
-          # 1. Explicit settings override
-          settings_override = check_settings_override(tool_name)
-          return settings_override if settings_override
-
-          # 2. Catalog + OverrideConfidence auto-override
-          check_catalog_override(tool_name)
-        end
-
-        def check_settings_override(tool_name)
-          overrides = Legion::Settings.dig(:mcp, :overrides) rescue nil # rubocop:disable Style/RescueModifier
-          return nil unless overrides.is_a?(Hash)
-
-          override = overrides[tool_name]
-          return nil unless override
-
-          {
-            type:     :extension,
-            lex:      override[:lex] || override['lex'],
-            runner:   override[:runner] || override['runner'],
-            function: override[:function] || override['function']
-          }
-        end
-
-        def check_catalog_override(tool_name)
-          return nil unless defined?(Legion::Extensions::Catalog::Registry)
-          return nil unless Legion::LLM::OverrideConfidence.should_override?(tool_name)
-
-          cap = Legion::Extensions::Catalog::Registry.for_override(tool_name)
-          return nil unless cap
-
-          {
-            type:     :extension,
-            lex:      cap.extension,
-            runner:   cap.runner,
-            function: cap.function
-          }
-        end
-
-        def dispatch_mcp(tool_call, source)
-          conn = ::Legion::MCP::Client::Pool.connection_for(source[:server])
-          raise "No connection for MCP server: #{source[:server]}" unless conn
-
-          raw = conn.call_tool(name: tool_call[:name], arguments: tool_call[:arguments] || {})
-          content = raw[:content]&.map { |c| c[:text] || c['text'] }&.join("\n")
-          { status: raw[:error] ? :error : :success, result: content }
-        end
-
-        def dispatch_extension(tool_call, source)
-          segments = (source[:lex] || '').delete_prefix('lex-').split('-')
-          runner_path = (%w[Legion Extensions] + segments.map(&:capitalize) + ['Runners', source[:runner]]).join('::')
-
-          runner = Kernel.const_get(runner_path)
-          fn = source[:function].to_sym
-          result = runner.send(fn, **(tool_call[:arguments] || {}))
-          { status: :success, result: result }
-        end
-
-        def dispatch_builtin(_tool_call, _source)
-          { status: :passthrough, result: nil }
-        end
-
-        def run_shadow(tool_call, _source, mcp_result)
-          tool_name = tool_call[:name]
-          return unless Legion::LLM::OverrideConfidence.should_shadow?(tool_name)
-          return unless defined?(Legion::Extensions::Catalog::Registry)
-
-          cap = Legion::Extensions::Catalog::Registry.for_override(tool_name)
-          return unless cap
-
-          shadow_source = { type: :extension, lex: cap.extension, runner: cap.runner, function: cap.function }
-          shadow_result = dispatch_extension(tool_call, shadow_source)
-
-          if shadow_result[:status] == :success && mcp_result[:status] == :success
-            Legion::LLM::OverrideConfidence.record_success(tool_name)
-          else
-            Legion::LLM::OverrideConfidence.record_failure(tool_name)
-          end
-        rescue StandardError => e
-          Legion::LLM::OverrideConfidence.record_failure(tool_name) if tool_name
-          handle_exception(e, level: :debug, operation: 'llm.pipeline.tool_dispatcher.shadow_execution', tool_name: tool_name)
-        end
-      end
+      ToolDispatcher = Tools::Dispatcher
     end
   end
 end

data/lib/legion/llm/tools/adapter.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require 'ruby_llm'
+require 'legion/logging/helper'
+require 'legion/llm/tools/interceptor'
+
+module Legion
+  module LLM
+    module Tools
+      class Adapter < RubyLLM::Tool
+        include Legion::Logging::Helper
+
+        MAX_TOOL_NAME_LENGTH = 64
+
+        def initialize(tool_class)
+          @tool_class = tool_class
+          raw_name = tool_class.respond_to?(:tool_name) ? tool_class.tool_name : tool_class.name.to_s
+          @tool_name = sanitize_tool_name(raw_name)
+          @tool_desc = tool_class.respond_to?(:description) ? tool_class.description.to_s : ''
+          @tool_schema = tool_class.respond_to?(:input_schema) ? tool_class.input_schema : nil
+          super()
+        end
+
+        def name
+          @tool_name
+        end
+
+        def description
+          @tool_desc
+        end
+
+        def params_schema
+          return @params_schema if defined?(@params_schema)
+
+          @params_schema = (RubyLLM::Utils.deep_stringify_keys(@tool_schema) if @tool_schema.is_a?(Hash))
+        end
+
+        def execute(**args)
+          args = Interceptor.intercept(@tool_name, **args)
+          log.info("[llm][tools] adapter.execute name=#{@tool_name} arguments=#{summarize_payload(args)}")
+          result = @tool_class.call(**args)
+          content = extract_content(result)
+          log.info("[llm][tools] adapter.result name=#{@tool_name} output=#{summarize_payload(content)}")
+          content
+        rescue StandardError => e
+          handle_exception(e, level: :warn, operation: 'llm.tools.adapter.execute', tool_name: @tool_name)
+          "Tool error: #{e.message}"
+        end
+
+        private
+
+        def extract_content(result)
+          if result.respond_to?(:content) && result.content.is_a?(Array)
+            result.content.filter_map { |c| c[:text] || c['text'] || c.to_s }.join("\n")
+          elsif result.is_a?(Hash) && result[:content].is_a?(Array)
+            result[:content].filter_map { |c| c[:text] || c['text'] }.join("\n")
+          elsif result.is_a?(Hash)
+            Legion::JSON.dump(result)
+          elsif result.is_a?(String)
+            result
+          else
+            result.to_s
+          end
+        end
+
+        def summarize_payload(payload)
+          payload.to_s[0, 200].inspect
+        end
+
+        def sanitize_tool_name(raw)
+          name = raw.tr('.', '_')
+          name = name.gsub(/[^a-zA-Z0-9_-]/, '')
+          name = name[0, MAX_TOOL_NAME_LENGTH] if name.length > MAX_TOOL_NAME_LENGTH
+          name.empty? ? "tool_#{@tool_class.object_id}" : name
+        end
+      end
+    end
+  end
+end

data/lib/legion/llm/tools/dispatcher.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require 'legion/logging/helper'
+
+module Legion
+  module LLM
+    module Tools
+      module Dispatcher
+        extend Legion::Logging::Helper
+
+        module_function
+
+        def dispatch(tool_call:, source:, exchange_id: nil)
+          start_time = Time.now
+
+          if source[:type] == :mcp
+            override = check_override(tool_call[:name])
+            if override
+              overridden_source = source
+              source = override.merge(overridden_from: overridden_source)
+            end
+          end
+
+          result = case source[:type]
+                   when :mcp
+                     mcp_result = dispatch_mcp(tool_call, source)
+                     run_shadow(tool_call, source, mcp_result)
+                     mcp_result
+                   when :extension
+                     dispatch_extension(tool_call, source)
+                   when :builtin
+                     dispatch_builtin(tool_call, source)
+                   else
+                     { status: :error, error: "Unknown tool source type: #{source[:type]}" }
+                   end
+
+          result.merge(
+            source:      source,
+            exchange_id: exchange_id,
+            duration_ms: ((Time.now - start_time) * 1000).to_i
+          )
+        rescue StandardError => e
+          handle_exception(e, level: :warn, operation: 'llm.tools.dispatcher.dispatch_tool_call', tool_name: tool_call[:name])
+          { status: :error, error: e.message, source: source, exchange_id: exchange_id }
+        end
+
+        def check_override(tool_name)
+          settings_override = check_settings_override(tool_name)
+          return settings_override if settings_override
+
+          check_catalog_override(tool_name)
+        end
+
+        def check_settings_override(tool_name)
+          overrides = Legion::Settings.dig(:mcp, :overrides) rescue nil # rubocop:disable Style/RescueModifier
+          return nil unless overrides.is_a?(Hash)
+
+          override = overrides[tool_name]
+          return nil unless override
+
+          {
+            type:     :extension,
+            lex:      override[:lex] || override['lex'],
+            runner:   override[:runner] || override['runner'],
+            function: override[:function] || override['function']
+          }
+        end
+
+        def check_catalog_override(tool_name)
+          return nil unless defined?(Legion::Extensions::Catalog::Registry)
+          return nil unless Legion::LLM::OverrideConfidence.should_override?(tool_name)
+
+          cap = Legion::Extensions::Catalog::Registry.for_override(tool_name)
+          return nil unless cap
+
+          {
+            type:     :extension,
+            lex:      cap.extension,
+            runner:   cap.runner,
+            function: cap.function
+          }
+        end
+
+        def dispatch_mcp(tool_call, source)
+          conn = ::Legion::MCP::Client::Pool.connection_for(source[:server])
+          raise "No connection for MCP server: #{source[:server]}" unless conn
+
+          raw = conn.call_tool(name: tool_call[:name], arguments: tool_call[:arguments] || {})
+          content = raw[:content]&.map { |c| c[:text] || c['text'] }&.join("\n")
+          { status: raw[:error] ? :error : :success, result: content }
+        end
+
+        def dispatch_extension(tool_call, source)
+          segments = (source[:lex] || '').delete_prefix('lex-').split('-')
+          runner_path = (%w[Legion Extensions] + segments.map(&:capitalize) + ['Runners', source[:runner]]).join('::')
+
+          runner = Kernel.const_get(runner_path)
+          fn = source[:function].to_sym
+          result = runner.send(fn, **(tool_call[:arguments] || {}))
+          { status: :success, result: result }
+        end
+
+        def dispatch_builtin(_tool_call, _source)
+          { status: :passthrough, result: nil }
+        end
+
+        def run_shadow(tool_call, _source, mcp_result)
+          tool_name = tool_call[:name]
+          return unless Legion::LLM::OverrideConfidence.should_shadow?(tool_name)
+          return unless defined?(Legion::Extensions::Catalog::Registry)
+
+          cap = Legion::Extensions::Catalog::Registry.for_override(tool_name)
+          return unless cap
+
+          shadow_source = { type: :extension, lex: cap.extension, runner: cap.runner, function: cap.function }
+          shadow_result = dispatch_extension(tool_call, shadow_source)
+
+          if shadow_result[:status] == :success && mcp_result[:status] == :success
+            Legion::LLM::OverrideConfidence.record_success(tool_name)
+          else
+            Legion::LLM::OverrideConfidence.record_failure(tool_name)
+          end
+        rescue StandardError => e
+          Legion::LLM::OverrideConfidence.record_failure(tool_name) if tool_name
+          handle_exception(e, level: :debug, operation: 'llm.tools.dispatcher.shadow_execution', tool_name: tool_name)
+        end
+      end
+    end
+  end
+end

data/lib/legion/llm/tools/interceptor.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Legion
+  module LLM
+    module Tools
+      module Interceptor
+        @registry = {}
+        @mutex = Mutex.new
+
+        module_function
+
+        def register(name, matcher:, &block)
+          @mutex.synchronize { @registry = @registry.merge(name.to_sym => { matcher: matcher, rewrite: block }) }
+        end
+
+        def intercept(tool_name, **args)
+          snapshot = @mutex.synchronize { @registry.dup }
+          snapshot.each do |name, entry|
+            next unless entry[:matcher].call(tool_name)
+
+            rewritten_args = entry[:rewrite].call(tool_name, **args)
+            unless rewritten_args.is_a?(Hash)
+              raise ArgumentError,
+                    "interceptor #{name.inspect} must return a Hash, got #{rewritten_args.class}"
+            end
+
+            args = rewritten_args
+          end
+          args
+        end
+
+        def registered
+          @mutex.synchronize { @registry.keys }
+        end
+
+        def reset!
+          @mutex.synchronize { @registry = {} }
+        end
+
+        def load_defaults
+          require_relative 'interceptors/python_venv'
+          Interceptors::PythonVenv.register!
+        end
+      end
+    end
+  end
+end

data/lib/legion/llm/tools/interceptors/python_venv.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Legion
+  module LLM
+    module Tools
+      module Interceptors
+        module PythonVenv
+          VENV_DIR = File.expand_path('~/.legionio/python').freeze
+          PYTHON   = "#{VENV_DIR}/bin/python3".freeze
+          PIP      = "#{VENV_DIR}/bin/pip3".freeze
+
+          TOOL_PATTERN = /\A(python3?|pip3?)\z/i
+
+          module_function
+
+          def register!
+            Interceptor.register(:python_venv, matcher: method(:match?)) do |_tool_name, **args|
+              rewrite(**args)
+            end
+          end
+
+          def match?(tool_name)
+            TOOL_PATTERN.match?(tool_name.to_s)
+          end
+
+          def venv_available?
+            File.exist?("#{VENV_DIR}/pyvenv.cfg")
+          end
+
+          def rewrite(**args)
+            return args unless venv_available?
+
+            command = args[:command]
+            return args unless command.is_a?(String)
+
+            args.merge(command: rewrite_command(command))
+          end
+
+          def rewrite_command(command)
+            command
+              .sub(/\Apython3(\s|\z)/, "#{PYTHON}\\1")
+              .sub(/\Apip3(\s|\z)/,    "#{PIP}\\1")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/llm/version.rb

@@ -2,6 +2,6 @@
 
 module Legion
   module LLM
-    VERSION = '0.6.27'
+    VERSION = '0.6.28'
   end
 end

data/lib/legion/llm.rb

@@ -70,6 +70,7 @@ module Legion
         auto_register_providers
 
         install_hooks
+        load_tool_interceptors
 
         @started = true
         Legion::Settings[:llm][:connected] = true
@@ -924,6 +925,13 @@ module Legion
         handle_exception(e, level: :debug, operation: 'llm.install_hooks')
       end
 
+      def load_tool_interceptors
+        require 'legion/llm/tools/interceptor'
+        Legion::LLM::Tools::Interceptor.load_defaults
+      rescue StandardError => e
+        handle_exception(e, level: :debug, operation: 'llm.load_tool_interceptors')
+      end
+
       def set_defaults
         default_model = settings[:default_model]
         default_provider = settings[:default_provider]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legion-llm
 version: !ruby/object:Gem::Version
-  version: 0.6.27
+  version: 0.6.28
 platform: ruby
 authors:
 - Esity
@@ -320,6 +320,10 @@ files:
 - lib/legion/llm/shadow_eval.rb
 - lib/legion/llm/structured_output.rb
 - lib/legion/llm/token_tracker.rb
+- lib/legion/llm/tools/adapter.rb
+- lib/legion/llm/tools/dispatcher.rb
+- lib/legion/llm/tools/interceptor.rb
+- lib/legion/llm/tools/interceptors/python_venv.rb
 - lib/legion/llm/transport/exchanges/audit.rb
 - lib/legion/llm/transport/exchanges/escalation.rb
 - lib/legion/llm/transport/exchanges/metering.rb