legionio 1.4.71 → 1.4.72

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e16727aaa70a3ffc2da0e6d3f3a6bce498e0052876e280c1d6cb42d50b3d594
-  data.tar.gz: 57042f5deb5a35dd8456850606e7a1bf42e0e4d5235385a4abb7987d13831894
+  metadata.gz: d9c2f9048a25ea9cff5f0b8db43aaaf49ab40bb6c388b2f892c3f952fb7233f4
+  data.tar.gz: 02225b7029518b45f1d78f632cce4fdbaee631efb9c03cade5e575ac3c96e3cf
 SHA512:
-  metadata.gz: b2c90fb0ba93a569c0dbd6c72f6e199fcebd6201fa4d003a114bc2d0f9bced639c28364ccb92aaf78f6ea1d226d1fa78b4a1c92538fa1002274f8656f1a8e0e1
-  data.tar.gz: 47dd1c952fcf6fd5f0f70d277b7c03ced2632dfa13cf9c47db2d1e0e03d6f90c005a8f13776a03ed900cbdf2c5e27aa7ec8d62e36751260f207c561878ef78ba
+  metadata.gz: 758ee671a15875e26a60fe87b10b3499c5ef47f766d5cd3d43498b7c362be4a791defe79b99bda56ccbf263558fa7a4e8450b307f3bc29734c3c3d279bba4dd4
+  data.tar.gz: 2c04803613fe2a2ba39ef4aa29865f66b96b237ba7c3f74920cd784bedfebc9bc90df91042714a016f06587a6d234ed722cf29a5727c039e8f09fbddfb322184

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Legion Changelog
 
+## [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,94 @@
+# 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
+
+      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/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'
@@ -97,12 +99,44 @@ 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
+
           Resources::RunnerCatalog.register(server)
           Resources::ExtensionInfo.register_read_handler(server)
 
           server
         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.72'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legionio
 version: !ruby/object:Gem::Version
-  version: 1.4.71
+  version: 1.4.72
 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,7 @@ files:
 - lib/legion/mcp.rb
 - lib/legion/mcp/auth.rb
 - lib/legion/mcp/context_compiler.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 +600,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