legionio 1.4.71 → 1.4.73

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e16727aaa70a3ffc2da0e6d3f3a6bce498e0052876e280c1d6cb42d50b3d594
-  data.tar.gz: 57042f5deb5a35dd8456850606e7a1bf42e0e4d5235385a4abb7987d13831894
+  metadata.gz: 7693068b5190222c508dd07a248424e8f9e1eff77e80059cbd8a4fc81e9e6325
+  data.tar.gz: 43cc0da2efe7d604101ab87426c21b5f8ce677a8c023aeec38e5b91018b515ae
 SHA512:
-  metadata.gz: b2c90fb0ba93a569c0dbd6c72f6e199fcebd6201fa4d003a114bc2d0f9bced639c28364ccb92aaf78f6ea1d226d1fa78b4a1c92538fa1002274f8656f1a8e0e1
-  data.tar.gz: 47dd1c952fcf6fd5f0f70d277b7c03ced2632dfa13cf9c47db2d1e0e03d6f90c005a8f13776a03ed900cbdf2c5e27aa7ec8d62e36751260f207c561878ef78ba
+  metadata.gz: a2d75a86b1646113be917a9f8ed17f8f7aa8ffb48ff371db78ee62fbfdba1929d85e675f2bf7d6a5469b077f10370f3d044eb6f5049db353d471f5be1c3cbab5
+  data.tar.gz: 2f00a29a6ddf7be18ee71839b97e1a8aeeb74f2cecd820932447bc574fcfeb595a6adce0d757909bf3e3d68909235fcbb32ad95182192b5471dea0a2f3d39a0e

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Legion Changelog
 
+## [1.4.73] - 2026-03-19
+
+### Added
+- TBI Phase 3: semantic tool retrieval via embedding vectors
+- `Legion::MCP::EmbeddingIndex` module: in-memory embedding cache with pure-Ruby cosine similarity
+- `ContextCompiler` semantic score blending: 60% semantic + 40% keyword when embeddings available, keyword-only fallback
+- `Server.populate_embedding_index`: auto-populates tool embeddings on MCP server build (no-op if LLM unavailable)
+- `legion observe embeddings` subcommand: index size, coverage, and populated status
+- 61 new specs (1666 total): EmbeddingIndex unit, ContextCompiler semantic blending, integration wiring, CLI
+
+## [1.4.72] - 2026-03-19
+
+### Added
+- TBI Phase 0+2: MCP tool observation pipeline and usage-based filtering
+- `Legion::MCP::Observer` module: in-memory tool call recording with counters, ring buffer, and intent tracking
+- `Legion::MCP::UsageFilter` module: scores tools by frequency, recency, and keyword match; prunes dead tools
+- MCP `instrumentation_callback` wiring: automatically records all `tools/call` invocations via Observer
+- MCP `tools_list_handler` wiring: dynamically filters and ranks tools per-request based on usage data
+- `legion observe` CLI command: `stats`, `recent`, `reset` subcommands for MCP tool usage inspection
+- 96 new specs covering Observer, UsageFilter, CLI command, and integration wiring
+
 ## [1.4.71] - 2026-03-19
 
 ### Added

data/lib/legion/cli/observe_command.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require 'thor'
+require 'legion/mcp/observer'
+
+module Legion
+  module CLI
+    class ObserveCommand < Thor
+      namespace :observe
+
+      desc 'stats', 'Show MCP tool usage statistics'
+      def stats
+        data = Legion::MCP::Observer.stats
+
+        if options['json']
+          puts ::JSON.pretty_generate(serialize_stats(data))
+          return
+        end
+
+        puts 'MCP Tool Observation Stats'
+        puts '=' * 40
+        puts "Total Calls:  #{data[:total_calls]}"
+        puts "Tools Used:   #{data[:tool_count]}"
+        puts "Failure Rate: #{(data[:failure_rate] * 100).round(1)}%"
+        puts "Since:        #{data[:since]&.strftime('%Y-%m-%d %H:%M:%S')}"
+        puts
+
+        return if data[:top_tools].empty?
+
+        puts 'Top Tools:'
+        puts '-' * 60
+        puts 'Tool                            Calls  Avg(ms)  Fails'
+        puts '-' * 60
+        data[:top_tools].each do |tool|
+          puts format('%-30<name>s %6<calls>d %8<avg>d %6<fails>d',
+                      name: tool[:name], calls: tool[:call_count],
+                      avg: tool[:avg_latency_ms], fails: tool[:failure_count])
+        end
+      end
+
+      desc 'recent', 'Show recent MCP tool calls'
+      method_option :limit, type: :numeric, default: 20, aliases: '-n'
+      def recent
+        calls = Legion::MCP::Observer.recent(options['limit'] || 20)
+
+        if options['json']
+          puts ::JSON.pretty_generate(calls.map { |c| serialize_call(c) })
+          return
+        end
+
+        if calls.empty?
+          puts 'No recent tool calls recorded.'
+          return
+        end
+
+        puts 'Tool                           Duration  Status Time'
+        puts '-' * 70
+        calls.reverse_each do |call|
+          status = call[:success] ? 'OK' : 'FAIL'
+          time = call[:timestamp]&.strftime('%H:%M:%S')
+          puts format('%-30<tool>s %6<dur>dms %7<st>s %<tm>s',
+                      tool: call[:tool_name], dur: call[:duration_ms], st: status, tm: time)
+        end
+      end
+
+      desc 'reset', 'Clear all observation data'
+      def reset
+        print 'Clear all observation data? (yes/no): '
+        return unless $stdin.gets&.strip&.downcase == 'yes'
+
+        Legion::MCP::Observer.reset!
+        puts 'Observation data cleared.'
+      end
+
+      desc 'embeddings', 'Show MCP tool embedding index status'
+      def embeddings
+        require 'legion/mcp/embedding_index'
+        data = {
+          index_size: Legion::MCP::EmbeddingIndex.size,
+          coverage:   Legion::MCP::EmbeddingIndex.coverage,
+          populated:  Legion::MCP::EmbeddingIndex.populated?
+        }
+
+        if options['json']
+          puts ::JSON.pretty_generate(data.transform_keys(&:to_s))
+          return
+        end
+
+        puts 'MCP Embedding Index'
+        puts '=' * 40
+        puts "Index Size: #{data[:index_size]}"
+        puts "Coverage:   #{(data[:coverage] * 100).round(1)}%"
+        puts "Populated:  #{data[:populated]}"
+      end
+
+      private
+
+      def serialize_stats(data)
+        {
+          total_calls:  data[:total_calls],
+          tool_count:   data[:tool_count],
+          failure_rate: data[:failure_rate],
+          since:        data[:since]&.iso8601,
+          top_tools:    data[:top_tools].map { |t| t.transform_keys(&:to_s) }
+        }
+      end
+
+      def serialize_call(call)
+        call.transform_keys(&:to_s).tap do |c|
+          c['timestamp'] = c['timestamp']&.iso8601 if c['timestamp']
+        end
+      end
+    end
+  end
+end

data/lib/legion/cli.rb

@@ -43,7 +43,8 @@ module Legion
     autoload :Marketplace, 'legion/cli/marketplace_command'
     autoload :Notebook,    'legion/cli/notebook_command'
     autoload :Llm,         'legion/cli/llm_command'
-    autoload :Tty,         'legion/cli/tty_command'
+    autoload :Tty,            'legion/cli/tty_command'
+    autoload :ObserveCommand, 'legion/cli/observe_command'
     autoload :Interactive, 'legion/cli/interactive'
 
     class Main < Thor
@@ -241,6 +242,9 @@ module Legion
       desc 'tty', 'Rich terminal UI (onboarding, AI chat, dashboard)'
       subcommand 'tty', Legion::CLI::Tty
 
+      desc 'observe SUBCOMMAND', 'MCP tool observation stats'
+      subcommand 'observe', Legion::CLI::ObserveCommand
+
       desc 'tree', 'Print a tree of all available commands'
       def tree
         legion_print_command_tree(self.class, 'legion', '')

data/lib/legion/mcp/context_compiler.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'embedding_index'
+
 module Legion
   module MCP
     module ContextCompiler
@@ -112,6 +114,7 @@ module Legion
       # Clears the memoized tool_index.
       def reset!
         @tool_index = nil
+        Legion::MCP::EmbeddingIndex.reset! if defined?(Legion::MCP::EmbeddingIndex)
       end
 
       def build_tool_index
@@ -131,10 +134,38 @@ module Legion
         keywords = intent_string.downcase.split
         return [] if keywords.empty?
 
+        kw_scores = keyword_score_map(keywords)
+        sem_scores = semantic_score_map(intent_string)
+        use_semantic = !sem_scores.empty?
+
         tool_index.values.map do |entry|
+          kw_raw = kw_scores[entry[:name]] || 0
+          if use_semantic
+            max_kw = kw_scores.values.max || 1
+            normalized_kw = max_kw.positive? ? kw_raw.to_f / max_kw : 0.0
+            sem = sem_scores[entry[:name]] || 0.0
+            blended = (normalized_kw * 0.4) + (sem * 0.6)
+          else
+            blended = kw_raw.to_f
+          end
+
+          { name: entry[:name], description: entry[:description], score: blended }
+        end
+      end
+
+      def keyword_score_map(keywords)
+        tool_index.values.to_h do |entry|
           haystack = "#{entry[:name].downcase} #{entry[:description].downcase}"
-          score    = keywords.count { |kw| haystack.include?(kw) }
-          { name: entry[:name], description: entry[:description], score: score }
+          score = keywords.count { |kw| haystack.include?(kw) }
+          [entry[:name], score]
+        end
+      end
+
+      def semantic_score_map(intent_string)
+        return {} unless defined?(Legion::MCP::EmbeddingIndex) && Legion::MCP::EmbeddingIndex.populated?
+
+        Legion::MCP::EmbeddingIndex.semantic_match(intent_string, limit: tool_index.size).to_h do |result|
+          [result[:name], result[:score]]
         end
       end
     end

data/lib/legion/mcp/embedding_index.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Legion
+  module MCP
+    module EmbeddingIndex
+      module_function
+
+      def build_from_tool_data(tool_data, embedder: default_embedder)
+        @embedder = embedder
+        mutex.synchronize do
+          tool_data.each do |tool|
+            composite = build_composite(tool[:name], tool[:description], tool[:params])
+            vector = safe_embed(composite, embedder)
+            next unless vector
+
+            index[tool[:name]] = {
+              name:           tool[:name],
+              composite_text: composite,
+              vector:         vector,
+              built_at:       Time.now
+            }
+          end
+        end
+      end
+
+      def semantic_match(intent, embedder: @embedder || default_embedder, limit: 5)
+        return [] if index.empty?
+
+        intent_vec = safe_embed(intent, embedder)
+        return [] unless intent_vec
+
+        scores = mutex.synchronize do
+          index.values.filter_map do |entry|
+            next unless entry[:vector]
+
+            score = cosine_similarity(intent_vec, entry[:vector])
+            { name: entry[:name], score: score }
+          end
+        end
+
+        scores.sort_by { |s| -s[:score] }.first(limit)
+      end
+
+      def cosine_similarity(vec_a, vec_b)
+        dot = vec_a.zip(vec_b).sum { |a, b| a * b }
+        mag_a = Math.sqrt(vec_a.sum { |x| x**2 })
+        mag_b = Math.sqrt(vec_b.sum { |x| x**2 })
+        return 0.0 if mag_a.zero? || mag_b.zero?
+
+        dot / (mag_a * mag_b)
+      end
+
+      def entry(tool_name)
+        mutex.synchronize { index[tool_name] }
+      end
+
+      def size
+        mutex.synchronize { index.size }
+      end
+
+      def populated?
+        mutex.synchronize { !index.empty? }
+      end
+
+      def coverage
+        mutex.synchronize do
+          return 0.0 if index.empty?
+
+          with_vectors = index.values.count { |e| e[:vector] }
+          with_vectors.to_f / index.size
+        end
+      end
+
+      def reset!
+        @embedder = nil
+        mutex.synchronize { index.clear }
+      end
+
+      def index
+        @index ||= {}
+      end
+
+      def mutex
+        @mutex ||= Mutex.new
+      end
+
+      def build_composite(name, description, params)
+        parts = [name, '--', description]
+        parts << "Params: #{params.join(', ')}" unless params.empty?
+        parts.join(' ')
+      end
+
+      def safe_embed(text, embedder)
+        return nil unless embedder
+
+        result = embedder.call(text)
+        return nil unless result.is_a?(Array) && !result.empty?
+
+        result
+      rescue StandardError
+        nil
+      end
+
+      def default_embedder
+        return nil unless defined?(Legion::LLM) && Legion::LLM.respond_to?(:started?) && Legion::LLM.started?
+
+        ->(text) { Legion::LLM.embed(text)[:vector] }
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/legion/mcp/observer.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require 'concurrent-ruby'
+
+module Legion
+  module MCP
+    module Observer
+      RING_BUFFER_MAX   = 500
+      INTENT_BUFFER_MAX = 200
+
+      module_function
+
+      def record(tool_name:, duration_ms:, success:, params_keys: [], error: nil)
+        now = Time.now
+
+        counters_mutex.synchronize do
+          entry = counters[tool_name] || { call_count: 0, total_latency_ms: 0.0, failure_count: 0,
+                                           last_used: nil, last_error: nil }
+          counters[tool_name] = {
+            call_count:       entry[:call_count] + 1,
+            total_latency_ms: entry[:total_latency_ms] + duration_ms.to_f,
+            failure_count:    entry[:failure_count] + (success ? 0 : 1),
+            last_used:        now,
+            last_error:       success ? entry[:last_error] : error
+          }
+        end
+
+        buffer_mutex.synchronize do
+          ring_buffer << {
+            tool_name:   tool_name,
+            duration_ms: duration_ms,
+            success:     success,
+            params_keys: params_keys,
+            error:       error,
+            recorded_at: now
+          }
+          ring_buffer.shift if ring_buffer.size > RING_BUFFER_MAX
+        end
+      end
+
+      def record_intent(intent, matched_tool_name)
+        intent_mutex.synchronize do
+          intent_buffer << { intent: intent, matched_tool: matched_tool_name, recorded_at: Time.now }
+          intent_buffer.shift if intent_buffer.size > INTENT_BUFFER_MAX
+        end
+      end
+
+      def tool_stats(tool_name)
+        entry = counters_mutex.synchronize { counters[tool_name] }
+        return nil unless entry
+
+        count = entry[:call_count]
+        avg   = count.positive? ? (entry[:total_latency_ms] / count).round(2) : 0.0
+
+        {
+          name:           tool_name,
+          call_count:     count,
+          avg_latency_ms: avg,
+          failure_count:  entry[:failure_count],
+          last_used:      entry[:last_used],
+          last_error:     entry[:last_error]
+        }
+      end
+
+      def all_tool_stats
+        names = counters_mutex.synchronize { counters.keys.dup }
+        names.to_h { |name| [name, tool_stats(name)] }
+      end
+
+      def stats
+        all_names = counters_mutex.synchronize { counters.keys.dup }
+        total     = all_names.sum { |n| counters_mutex.synchronize { counters[n][:call_count] } }
+        failures  = all_names.sum { |n| counters_mutex.synchronize { counters[n][:failure_count] } }
+        rate      = total.positive? ? (failures.to_f / total).round(4) : 0.0
+
+        top = all_names
+              .map { |n| tool_stats(n) }
+              .sort_by { |s| -s[:call_count] }
+              .first(10)
+
+        {
+          total_calls:  total,
+          tool_count:   all_names.size,
+          failure_rate: rate,
+          top_tools:    top,
+          since:        started_at
+        }
+      end
+
+      def recent(limit = 10)
+        buffer_mutex.synchronize { ring_buffer.last(limit) }
+      end
+
+      def recent_intents(limit = 10)
+        intent_mutex.synchronize { intent_buffer.last(limit) }
+      end
+
+      def reset!
+        counters_mutex.synchronize { counters.clear }
+        buffer_mutex.synchronize { ring_buffer.clear }
+        intent_mutex.synchronize { intent_buffer.clear }
+        @started_at = Time.now
+      end
+
+      # Internal state accessors
+      def counters
+        @counters ||= {}
+      end
+
+      def counters_mutex
+        @counters_mutex ||= Mutex.new
+      end
+
+      def ring_buffer
+        @ring_buffer ||= []
+      end
+
+      def buffer_mutex
+        @buffer_mutex ||= Mutex.new
+      end
+
+      def intent_buffer
+        @intent_buffer ||= []
+      end
+
+      def intent_mutex
+        @intent_mutex ||= Mutex.new
+      end
+
+      def started_at
+        @started_at ||= Time.now
+      end
+    end
+  end
+end

data/lib/legion/mcp/server.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'observer'
+require_relative 'usage_filter'
 require_relative 'tools/run_task'
 require_relative 'tools/describe_runner'
 require_relative 'tools/list_tasks'
@@ -34,6 +36,7 @@ require_relative 'tools/rbac_check'
 require_relative 'tools/rbac_assignments'
 require_relative 'tools/rbac_grants'
 require_relative 'context_compiler'
+require_relative 'embedding_index'
 require_relative 'tools/do_action'
 require_relative 'tools/discover_tools'
 require_relative 'resources/runner_catalog'
@@ -97,12 +100,54 @@ module Legion
             resource_templates: Resources::ExtensionInfo.resource_templates
           )
 
+          if defined?(Observer)
+            ::MCP.configure do |c|
+              c.instrumentation_callback = ->(idata) { Server.wire_observer(idata) }
+            end
+          end
+
+          server.tools_list_handler do |_params|
+            build_filtered_tool_list.map(&:to_h)
+          end
+
+          # Populate embedding index for semantic tool matching (lazy — no-op if LLM unavailable)
+          populate_embedding_index
+
           Resources::RunnerCatalog.register(server)
           Resources::ExtensionInfo.register_read_handler(server)
 
           server
         end
 
+        def populate_embedding_index(embedder: EmbeddingIndex.default_embedder)
+          return unless embedder
+
+          tool_data = ContextCompiler.tool_index.values
+          EmbeddingIndex.build_from_tool_data(tool_data, embedder: embedder)
+        end
+
+        def wire_observer(data)
+          return unless data[:method] == 'tools/call' && data[:tool_name]
+
+          duration_ms = (data[:duration].to_f * 1000).to_i
+          params_keys = data[:tool_arguments].respond_to?(:keys) ? data[:tool_arguments].keys : []
+          success     = data[:error].nil?
+
+          Observer.record(
+            tool_name:   data[:tool_name],
+            duration_ms: duration_ms,
+            success:     success,
+            params_keys: params_keys,
+            error:       data[:error]
+          )
+        end
+
+        def build_filtered_tool_list(keywords: [])
+          tool_names = TOOL_CLASSES.map { |tc| tc.respond_to?(:tool_name) ? tc.tool_name : tc.name }
+          ranked     = UsageFilter.ranked_tools(tool_names, keywords: keywords)
+          ranked.filter_map { |name| TOOL_CLASSES.find { |tc| (tc.respond_to?(:tool_name) ? tc.tool_name : tc.name) == name } }
+        end
+
         private
 
         def instructions

data/lib/legion/mcp/usage_filter.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Legion
+  module MCP
+    module UsageFilter
+      ESSENTIAL_TOOLS = %w[
+        legion.do legion.tools legion.run_task legion.get_status legion.describe_runner
+      ].freeze
+
+      FREQUENCY_WEIGHT = 0.5
+      RECENCY_WEIGHT   = 0.3
+      KEYWORD_WEIGHT   = 0.2
+      BASELINE_SCORE   = 0.1
+
+      module_function
+
+      def score_tools(tool_names, keywords: [])
+        all_stats = Observer.all_tool_stats
+        call_counts = tool_names.map { |n| all_stats.dig(n, :call_count) || 0 }
+        max_calls   = call_counts.max || 0
+
+        tool_names.each_with_object({}) do |name, hash|
+          stats = all_stats[name]
+
+          freq_score = if max_calls.positive? && stats
+                         (stats[:call_count].to_f / max_calls) * FREQUENCY_WEIGHT
+                       else
+                         0.0
+                       end
+
+          rec_score = if stats&.dig(:last_used)
+                        recency_decay(stats[:last_used]) * RECENCY_WEIGHT
+                      else
+                        0.0
+                      end
+
+          kw_score = keyword_match(name, keywords) * KEYWORD_WEIGHT
+
+          total = freq_score + rec_score + kw_score
+          total = BASELINE_SCORE if total.zero?
+
+          hash[name] = total.round(6)
+        end
+      end
+
+      def ranked_tools(tool_names, limit: nil, keywords: [])
+        scores = score_tools(tool_names, keywords: keywords)
+        ranked = tool_names.sort_by { |n| -scores.fetch(n, BASELINE_SCORE) }
+        limit ? ranked.first(limit) : ranked
+      end
+
+      def prune_dead_tools(tool_names, prune_after_seconds: 86_400 * 30)
+        stats = Observer.stats
+        window = stats[:since]
+        elapsed = window ? (Time.now - window) : 0
+
+        return tool_names if elapsed < prune_after_seconds
+
+        all_stats = Observer.all_tool_stats
+        tool_names.reject do |name|
+          next false if ESSENTIAL_TOOLS.include?(name)
+
+          calls = all_stats.dig(name, :call_count) || 0
+          calls.zero?
+        end
+      end
+
+      def recency_decay(last_used)
+        return 0.0 unless last_used
+
+        age_seconds = Time.now - last_used
+        return 1.0 if age_seconds <= 0
+
+        decay = 1.0 - (age_seconds / 86_400.0)
+        decay.clamp(0.0, 1.0)
+      end
+
+      def keyword_match(tool_name, keywords)
+        return 0.0 if keywords.nil? || keywords.empty?
+
+        hits = keywords.count { |kw| tool_name.include?(kw.to_s) }
+        hits.to_f / keywords.size
+      end
+    end
+  end
+end

data/lib/legion/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Legion
-  VERSION = '1.4.71'
+  VERSION = '1.4.73'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legionio
 version: !ruby/object:Gem::Version
-  version: 1.4.71
+  version: 1.4.73
 platform: ruby
 authors:
 - Esity
@@ -490,6 +490,7 @@ files:
 - lib/legion/cli/mcp_command.rb
 - lib/legion/cli/memory_command.rb
 - lib/legion/cli/notebook_command.rb
+- lib/legion/cli/observe_command.rb
 - lib/legion/cli/openapi_command.rb
 - lib/legion/cli/output.rb
 - lib/legion/cli/plan_command.rb
@@ -559,6 +560,8 @@ files:
 - lib/legion/mcp.rb
 - lib/legion/mcp/auth.rb
 - lib/legion/mcp/context_compiler.rb
+- lib/legion/mcp/embedding_index.rb
+- lib/legion/mcp/observer.rb
 - lib/legion/mcp/resources/extension_info.rb
 - lib/legion/mcp/resources/runner_catalog.rb
 - lib/legion/mcp/server.rb
@@ -598,6 +601,7 @@ files:
 - lib/legion/mcp/tools/update_schedule.rb
 - lib/legion/mcp/tools/worker_costs.rb
 - lib/legion/mcp/tools/worker_lifecycle.rb
+- lib/legion/mcp/usage_filter.rb
 - lib/legion/metrics.rb
 - lib/legion/process.rb
 - lib/legion/readiness.rb