legionio 1.7.16 → 1.7.17

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 60d6e7e501be5410e50a0096185b33af3f10b500ac766d2138efa67bb80908e0
-  data.tar.gz: 10d105942a000d3eb726125a6e55c3dbe1c70474623671ac09a69278a5c998db
+  metadata.gz: 6fc7545d6fe4e3dc832eba2265dc27fed7546fb3d770dec04b4375b35505479f
+  data.tar.gz: 513b2ff1093560b1d88c427b176d6f27959a6c94abd3106173d462d29f8cd69c
 SHA512:
-  metadata.gz: c3d0342c0a3131bf421c7139ed2917eb94e037713e8d3cb6183680d1c3a04ffcd1bdca68679fadaa3c68237f5c0a994b33814776e56ea9bcdb865c0931b0c5f5
-  data.tar.gz: 0df1adc61ab111c31b1c6a87ed5b3e15d4243bf112b9914b01f7e9e0d9c6dc2ac6272708ddc4337187443d028da80447fc33a97a69e296f110f95b83404b1065
+  metadata.gz: b6de374974924d397249494b4aed6ff9e99263116a36d47226530c12653d672371565d060b65913d249fce4d0ed808fd6ffae45a669a6e4b1b67d87a056dcbe8
+  data.tar.gz: 2d64efa40365a2da40fcc97de5173e2c3bfd3458e8adf861a0efde9c35514d7b876ab200f2d5648ca68f08f5de879c29dde2c4d5c3f53d9c2240ae8f4575debe

data/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 ## [Unreleased]
 
+### Added
+- `Legion::Tools::Base` - canonical tool base class with DSL
+- `Legion::Tools::Registry` - always/deferred tool classification
+- `Legion::Tools::Discovery` - auto-discovers tools from extension runners with hierarchical DSL
+- `Legion::Tools::EmbeddingCache` - 5-tier persistent embedding cache (L0 memory + Cache + Data)
+- `mcp_tools?` and `mcp_tools_deferred?` extension Core DSL
+- `runner_modules` accessor on extension builders
+- `loaded_extension_modules` accessor on `Legion::Extensions`
+- Static tools: `Do`, `Status`, `Config` with `Legion::Logging::Helper`
+
+### Changed
+- Boot registers tools into Tools::Registry after extension load
+- Embedding index build is async (non-blocking)
+- API inference reads from Tools::Registry instead of MCP
+- Capability registration methods are now no-ops (replaced by Tools::Discovery)
+
+### Removed
+- Direct MCP dependency for tool access in API inference
+
 ## [1.7.16] - 2026-04-03
 
 ### Fixed

data/lib/legion/api/llm.rb

@@ -3,36 +3,6 @@
 require 'securerandom'
 require 'open3'
 
-begin
-  require 'legion/cli/chat/tools/search_traces'
-  if defined?(Legion::LLM::ToolRegistry) && defined?(Legion::CLI::Chat::Tools::SearchTraces)
-    Legion::LLM::ToolRegistry.register(Legion::CLI::Chat::Tools::SearchTraces)
-  end
-rescue LoadError => e
-  Legion::Logging.log_exception(e, payload_summary: 'SearchTraces not available for API', component_type: :api) if defined?(Legion::Logging)
-end
-
-ALWAYS_LOADED_TOOLS = %w[
-  legion_do
-  legion_get_status
-  legion_run_task
-  legion_describe_runner
-  legion_list_extensions
-  legion_get_extension
-  legion_list_tasks
-  legion_get_task
-  legion_get_task_logs
-  legion_query_knowledge
-  legion_knowledge_health
-  legion_knowledge_context
-  legion_list_workers
-  legion_show_worker
-  legion_mesh_status
-  legion_list_peers
-  legion_tools
-  legion_search_sessions
-].freeze
-
 module Legion
   class API < Sinatra::Base
     module Routes
@@ -59,44 +29,6 @@ module Legion
               defined?(Legion::Extensions::LLM::Gateway::Runners::Inference)
             end
 
-            define_method(:cached_mcp_tools) do
-              @@cached_mcp_tools ||= begin # rubocop:disable Style/ClassVars
-                all = []
-                begin
-                  require 'legion/mcp' unless defined?(Legion::MCP) && Legion::MCP.respond_to?(:server)
-                  Legion::MCP.server if defined?(Legion::MCP) && Legion::MCP.respond_to?(:server)
-                rescue LoadError => e
-                  Legion::Logging.log_exception(e, payload_summary: 'cached_mcp_tools: failed to require legion/mcp', component_type: :api)
-                end
-                if defined?(Legion::MCP::Server) && Legion::MCP::Server.respond_to?(:tool_registry)
-                  require 'legion/llm/pipeline/mcp_tool_adapter' unless defined?(Legion::LLM::Pipeline::McpToolAdapter)
-                  Legion::Logging.info "[llm][api] cached_mcp_tools building from #{Legion::MCP::Server.tool_registry.size} MCP tools"
-                  Legion::MCP::Server.tool_registry.each do |tc|
-                    all << Legion::LLM::Pipeline::McpToolAdapter.new(tc)
-                  rescue StandardError => e
-                    Legion::Logging.log_exception(e, payload_summary: "cached_mcp_tools: failed to adapt #{tc}", component_type: :api)
-                  end
-                end
-                {
-                  always:   all.select { |t| ALWAYS_LOADED_TOOLS.include?(t.name) }.freeze,
-                  deferred: all.reject { |t| ALWAYS_LOADED_TOOLS.include?(t.name) }.freeze,
-                  all:      all.freeze
-                }.freeze
-              end
-            end
-
-            define_method(:inject_mcp_tools) do |session, requested_tools: []|
-              cache = cached_mcp_tools
-              cache[:always].each { |t| session.with_tool(t) }
-
-              return if requested_tools.empty?
-
-              requested = requested_tools.map { |n| n.to_s.tr('.', '_') }
-              cache[:deferred].each do |t|
-                session.with_tool(t) if requested.include?(t.name)
-              end
-            end
-
             define_method(:build_client_tool_class) do |tname, tdesc, tschema|
               klass = Class.new(RubyLLM::Tool) do
                 description tdesc
@@ -185,7 +117,7 @@ module Legion
 
             message = body[:message]
 
-            # Tier 0 check — serve from PatternStore if available
+            # Tier 0 check - serve from PatternStore if available
             if defined?(Legion::MCP::TierRouter)
               tier_result = Legion::MCP::TierRouter.route(
                 intent:  message,
@@ -206,8 +138,7 @@ module Legion
             model      = body[:model]
             provider   = body[:provider]
 
-            # Route through full Legion pipeline when gateway is available:
-            #   Ingress -> RBAC -> Events -> Task -> Gateway (metering + fleet) -> LLM
+            # Route through full Legion pipeline when gateway is available
             if gateway_available?
               ingress_result = Legion::Ingress.run(
                 payload:      { message: message, model: model, provider: provider,
@@ -315,7 +246,7 @@ module Legion
 
             caller_identity = env['legion.tenant_id'] || 'api:inference'
 
-            # GAIA bridge — push InputFrame to sensory buffer
+            # GAIA bridge - push InputFrame to sensory buffer
             last_user = messages.select { |m| (m[:role] || m['role']).to_s == 'user' }.last
             prompt    = (last_user || {})[:content] || (last_user || {})['content'] || ''
 
@@ -345,18 +276,7 @@ module Legion
             # Detect streaming mode
             streaming = body[:stream] == true && env['HTTP_ACCEPT']&.include?('text/event-stream')
 
-            # Inject MCP tools from daemon alongside client tools
-            all_tools = tool_classes.dup
-            begin
-              mcp_cache = cached_mcp_tools
-              mcp_to_inject = requested_tools.empty? ? mcp_cache[:always] : mcp_cache[:all]
-              all_tools.concat(mcp_to_inject) if mcp_to_inject&.any?
-              Legion::Logging.debug "[llm][api] inference mcp_injected=#{mcp_to_inject&.size || 0} total_tools=#{all_tools.size}"
-            rescue StandardError => e
-              Legion::Logging.log_exception(e, payload_summary: 'mcp tool injection failed', component_type: :api)
-            end
-
-            # Build pipeline request
+            # Executor handles all registry tool injection — API only passes client-defined tools
             require 'legion/llm/pipeline/request' unless defined?(Legion::LLM::Pipeline::Request)
             require 'legion/llm/pipeline/executor' unless defined?(Legion::LLM::Pipeline::Executor)
 
@@ -364,7 +284,7 @@ module Legion
               messages:        messages,
               system:          body[:system],
               routing:         { provider: provider, model: model },
-              tools:           all_tools,
+              tools:           tool_classes,
               caller:          { requested_by: { identity: caller_identity, type: :user, credential: :api } },
               conversation_id: body[:conversation_id],
               metadata:        { requested_tools: requested_tools },

data/lib/legion/cli/do_command.rb

@@ -15,7 +15,7 @@ module Legion
           result = try_daemon(intent, options) || try_in_process(intent) || try_llm_classify(intent)
 
           if result.nil?
-            formatter.error('No matching capability found')
+            formatter.error('No matching tool found')
             formatter.detail('Try: legion lex list  (to see available extensions)')
             raise SystemExit, 1
           end
@@ -53,37 +53,73 @@ module Legion
         end
 
         def try_in_process(intent)
-          return nil unless defined?(Legion::Extensions::Catalog::Registry)
+          return nil unless defined?(Legion::Tools::Registry)
 
-          matches = Legion::Extensions::Catalog::Registry.find_by_intent(intent)
-          return nil if matches.empty?
+          matched = Legion::Tools::Registry.all_tools.find do |t|
+            t.tool_name.include?(intent.downcase.tr(' ', '_')) ||
+              t.description.downcase.include?(intent.downcase)
+          end
+          return nil unless matched
+
+          begin
+            result = matched.call
+            normalize_in_process_result(result, matched.tool_name)
+          rescue ArgumentError
+            { matched: matched.tool_name, status: 'requires_daemon',
+              note: 'Tool requires arguments; start the daemon and retry: legion start' }
+          end
+        end
+
+        def normalize_in_process_result(result, tool_name)
+          return { matched: tool_name, result: result } unless result.is_a?(Hash)
+
+          normalized = result.dup
+          normalized[:matched] = tool_name
+          extracted = extract_tool_text(normalized)
 
-          best = matches.first
-          runner_class = build_runner_class(best.extension, best.runner)
+          if normalized[:error] == true
+            normalized[:error] = extracted.empty? ? 'Tool execution failed' : extracted
+          elsif !normalized.key?(:result) && !extracted.empty?
+            normalized[:result] = extracted
+          end
+
+          normalized
+        end
 
-          if defined?(Legion::Ingress)
-            Legion::Ingress.run(
-              payload:      { intent: intent },
-              runner_class: runner_class,
-              function:     best.function,
-              source:       'cli:do'
-            )
+        def extract_tool_text(value)
+          case value
+          when Hash
+            error_val = value[:error] || value['error']
+            return error_val.to_s unless error_val == true || error_val.nil? || error_val.to_s.empty?
+
+            %i[message result response detail content].each do |key|
+              extracted = extract_tool_text(value[key] || value[key.to_s])
+              return extracted unless extracted.empty?
+            end
+
+            ''
+          when Array
+            value.filter_map do |item|
+              text = extract_tool_text(item)
+              text unless text.empty?
+            end.join("\n")
+          when String
+            value.strip
           else
-            { matched: best.name, runner_class: runner_class, function: best.function,
-              status: 'resolved', note: 'Daemon not running; cannot execute. Start with: legion start' }
+            value.nil? ? '' : value.to_s
           end
         end
 
         def try_llm_classify(intent)
-          return nil unless defined?(Legion::Extensions::Catalog::Registry) && defined?(Legion::LLM)
+          return nil unless defined?(Legion::Tools::Registry) && defined?(Legion::LLM)
 
-          caps = Legion::Extensions::Catalog::Registry.capabilities
-          return nil if caps.empty?
+          tools = Legion::Tools::Registry.all_tools
+          return nil if tools.empty?
 
-          catalog = caps.map { |c| "#{c.name}: #{c.description || "#{c.extension} #{c.runner}##{c.function}"}" }
-          prompt = "Given these capabilities:\n#{catalog.join("\n")}\n\n" \
-                   "Which capability best matches this intent: \"#{intent}\"?\n" \
-                   'Reply with ONLY the capability name (e.g., lex-consul:health_check:run). ' \
+          catalog = tools.map { |t| "#{t.tool_name}: #{t.description}" }
+          prompt = "Given these tools:\n#{catalog.join("\n")}\n\n" \
+                   "Which tool best matches this intent: \"#{intent}\"?\n" \
+                   'Reply with ONLY the tool name (e.g., legion.do). ' \
                    'If none match, reply NONE.'
 
           response = Legion::LLM.ask(
@@ -93,12 +129,10 @@ module Legion
           chosen = response.is_a?(Hash) ? response[:response].to_s.strip : response.to_s.strip
           return nil if chosen.empty? || chosen.upcase == 'NONE'
 
-          cap = Legion::Extensions::Catalog::Registry.find(name: chosen)
-          return nil unless cap
+          tool = Legion::Tools::Registry.find(chosen)
+          return nil unless tool
 
-          runner_class = build_runner_class(cap.extension, cap.runner)
-          { matched: cap.name, runner_class: runner_class, function: cap.function,
-            status: 'resolved', source: 'llm',
+          { matched: tool.tool_name, status: 'resolved', source: 'llm',
             note: 'Daemon not running; cannot execute. Start with: legion start' }
         rescue StandardError => e
           Legion::Logging.debug("DoCommand#try_llm_classify failed: #{e.message}") if defined?(Legion::Logging)
@@ -106,26 +140,31 @@ module Legion
         end
 
         def resolve_runner_class(intent)
-          return nil unless defined?(Legion::Extensions::Catalog::Registry)
+          return nil unless defined?(Legion::Tools::Registry)
 
-          matches = Legion::Extensions::Catalog::Registry.find_by_intent(intent)
-          return nil if matches.empty?
+          matched = Legion::Tools::Registry.all_tools.find do |t|
+            t.description.downcase.include?(intent.downcase)
+          end
+          return nil unless matched.respond_to?(:extension) && matched.respond_to?(:runner)
 
-          build_runner_class(matches.first.extension, matches.first.runner)
+          build_runner_class(matched.extension, matched.runner)
         end
 
         def resolve_function(intent)
-          return nil unless defined?(Legion::Extensions::Catalog::Registry)
+          return nil unless defined?(Legion::Tools::Registry)
 
-          matches = Legion::Extensions::Catalog::Registry.find_by_intent(intent)
-          return nil if matches.empty?
+          matched = Legion::Tools::Registry.all_tools.find do |t|
+            t.description.downcase.include?(intent.downcase)
+          end
+          return nil unless matched
 
-          matches.first.function
+          matched.tool_name.split('.').last
         end
 
         def build_runner_class(extension, runner)
-          ext_part = extension.delete_prefix('lex-').split(/[-_]/).map(&:capitalize).join
-          "Legion::Extensions::#{ext_part}::Runners::#{runner}"
+          ext_part = extension.to_s.delete_prefix('lex-').split(/[-_]/).map(&:capitalize).join
+          runner_part = runner.to_s.split('_').map(&:capitalize).join
+          "Legion::Extensions::#{ext_part}::Runners::#{runner_part}"
         end
 
         def daemon_port(options)

data/lib/legion/extensions/builders/runners.rb

@@ -59,6 +59,12 @@ module Legion
           end
         end
 
+        def runner_modules
+          return [] unless defined?(@runners) && @runners.is_a?(Hash)
+
+          @runners.values.filter_map { |r| r[:runner_module] }
+        end
+
         def runner_files
           @runner_files ||= find_files('runners')
         end

data/lib/legion/extensions/core.rb

@@ -112,6 +112,14 @@ module Legion
         true
       end
 
+      def mcp_tools?
+        true
+      end
+
+      def mcp_tools_deferred?
+        true
+      end
+
       # Auto-generate AMQP message classes for each runner method that has a definition.
       # Explicit Messages::* classes in the transport directory take precedence.
       # Runs after build_runners so definitions are populated.

data/lib/legion/extensions.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require 'legion/extensions/core'
-require 'legion/extensions/capability'
 require 'legion/extensions/catalog'
 require 'legion/extensions/permissions'
 require 'legion/runner'
@@ -567,54 +566,24 @@ module Legion
 
       public
 
-      def unregister_capabilities(gem_name)
-        Extensions::Catalog::Registry.unregister_extension(gem_name)
-      end
+      def loaded_extension_modules
+        constants(false).filter_map do |const_name|
+          mod = const_get(const_name, false)
+          next nil unless mod.is_a?(Module) && mod.respond_to?(:runner_modules)
 
-      def register_absorber_capabilities(gem_name, absorbers)
-        absorbers.each_value do |absorber_meta|
-          cap = Extensions::Capability.from_absorber(
-            extension:   gem_name,
-            absorber:    absorber_meta[:absorber_module],
-            patterns:    absorber_meta[:patterns],
-            description: absorber_meta[:description]
-          )
-          Extensions::Catalog::Registry.register(cap)
+          mod
         rescue StandardError => e
-          if defined?(Legion::Logging)
-            Legion::Logging.warn(
-              "Absorber catalog registration error for #{gem_name} " \
-              "(#{absorber_meta[:absorber_module]}): #{e.message}"
-            )
-          end
+          Legion::Logging.warn("[Extensions] loaded_extension_modules: #{e.message}") if defined?(Legion::Logging)
+          nil
         end
       end
 
-      def register_capabilities(gem_name, runners)
-        runners.each_value do |runner_meta|
-          runner_name = runner_meta[:runner_name]
-          (runner_meta[:class_methods] || {}).each do |fn_name, fn_meta|
-            next if fn_name.to_s.start_with?('_')
+      # Legacy capability registration - now handled by Tools::Discovery
+      def unregister_capabilities(_gem_name); end
 
-            params = {}
-            (fn_meta[:args] || []).each do |arg|
-              type, name = arg
-              params[name] = { type: :string, required: type == :keyreq }
-            end
+      def register_absorber_capabilities(_gem_name, _absorbers); end
 
-            cap = Extensions::Capability.from_runner(
-              extension:  gem_name,
-              runner:     runner_name.to_s.split('_').map(&:capitalize).join,
-              function:   fn_name.to_s,
-              parameters: params,
-              tags:       [gem_name.delete_prefix('lex-')]
-            )
-            Extensions::Catalog::Registry.register(cap)
-          end
-        rescue StandardError => e
-          Legion::Logging.warn("Catalog registration error for #{gem_name}: #{e.message}") if defined?(Legion::Logging)
-        end
-      end
+      def register_capabilities(_gem_name, _runners); end
 
       def gem_load(entry)
         gem_name     = entry[:gem_name]

data/lib/legion/service.rb

@@ -149,6 +149,8 @@ module Legion
         setup_generated_functions
       end
 
+      register_core_tools
+
       Legion::Gaia.registry&.rediscover if gaia && defined?(Legion::Gaia) && Legion::Gaia.started?
 
       Legion::Extensions::Agentic::Memory::Trace::Helpers::ErrorTracer.setup if defined?(Legion::Extensions::Agentic::Memory::Trace::Helpers::ErrorTracer)
@@ -159,10 +161,11 @@ module Legion
       setup_metrics
       setup_task_outcome_observer
 
-      # Pre-warm MCP server in background so first inference isn't blocked by 837-tool build
+      # Pre-warm MCP server in background; async embedding build
       Thread.new do
         require 'legion/mcp' if defined?(Legion::Settings) && !defined?(Legion::MCP)
         Legion::MCP.server if defined?(Legion::MCP) && Legion::MCP.respond_to?(:server)
+        Legion::MCP::Server.populate_embedding_index if defined?(Legion::MCP::Server) && Legion::MCP::Server.respond_to?(:populate_embedding_index)
       rescue StandardError => e
         log.warn("MCP pre-warm failed: #{e.message}")
       end
@@ -607,7 +610,7 @@ module Legion
       handle_exception(e, level: :warn, operation: 'service.shutdown_api')
     end
 
-    def shutdown
+    def shutdown # rubocop:disable Metrics/CyclomaticComplexity
       log.info('Legion::Service.shutdown was called')
       @shutdown = true
       Legion::Settings[:client][:shutting_down] = true
@@ -631,6 +634,8 @@ module Legion
 
       shutdown_component('Dispatch') { Legion::Dispatch.shutdown } if defined?(Legion::Dispatch)
 
+      Legion::Tools::Registry.clear if defined?(Legion::Tools::Registry)
+
       ext_timeout = Legion::Settings.dig(:extensions, :shutdown_timeout) || 15
       shutdown_component('Extensions', timeout: ext_timeout) { Legion::Extensions.shutdown }
       Legion::Readiness.mark_not_ready(:extensions)
@@ -665,7 +670,7 @@ module Legion
       Legion::Events.emit('service.shutdown')
     end
 
-    def reload # rubocop:disable Metrics/MethodLength
+    def reload # rubocop:disable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
       return if @reloading
 
       @reloading = true
@@ -680,6 +685,9 @@ module Legion
         Legion::Readiness.mark_not_ready(:gaia)
       end
 
+      Legion::Tools::Registry.clear if defined?(Legion::Tools::Registry)
+      Legion::Tools::EmbeddingCache.clear_memory if defined?(Legion::Tools::EmbeddingCache) && Legion::Tools::EmbeddingCache.respond_to?(:clear_memory)
+
       ext_timeout = Legion::Settings.dig(:extensions, :shutdown_timeout) || 15
       shutdown_component('Extensions', timeout: ext_timeout) { Legion::Extensions.shutdown }
       Legion::Readiness.mark_not_ready(:extensions)
@@ -727,8 +735,15 @@ module Legion
       load_extensions
       Legion::Readiness.mark_ready(:extensions)
 
+      register_core_tools
+
       Legion::Crypt.cs
       setup_api if @api_enabled
+
+      if defined?(Legion::MCP)
+        Legion::MCP.reset!
+        Legion::MCP.server if Legion::MCP.respond_to?(:server)
+      end
       setup_network_watchdog
       Legion::Settings[:client][:ready] = true
       Legion::Events.emit('service.ready')
@@ -742,6 +757,20 @@ module Legion
       Legion::Extensions.hook_extensions
     end
 
+    def register_core_tools
+      require 'legion/tools'
+      Legion::Tools.register_all
+      Legion::Tools::Discovery.discover_and_register
+      Legion::Tools::EmbeddingCache.setup
+
+      log.info(
+        "Tools registered: #{Legion::Tools::Registry.tools.size} always, " \
+        "#{Legion::Tools::Registry.deferred_tools.size} deferred"
+      )
+    rescue StandardError => e
+      handle_exception(e, level: :warn, operation: 'service.register_core_tools')
+    end
+
     def setup_generated_functions
       return unless defined?(Legion::Extensions::Codegen::Helpers::GeneratedRegistry)
 

data/lib/legion/tools/base.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Legion
+  module Tools
+    class Base
+      class << self
+        # Lazy delegation instead of include Helper — Base loads at require time
+        # before Settings is initialized; Helper#log builds TaggedLogger which
+        # calls derive_log_segments -> Settings -> possible recursion.
+        # Subclass static tools (Do, Status, Config) CAN include Helper safely.
+        def log
+          Legion::Logging.respond_to?(:logger) ? Legion::Logging.logger : nil
+        end
+
+        def handle_exception(err, **opts)
+          log&.warn("[Legion::Tools] #{opts[:operation] || 'unknown'}: #{err.message}")
+        end
+
+        def tool_name(name = nil)
+          name ? @tool_name = name : @tool_name
+        end
+
+        def description(desc = nil)
+          desc ? @description = desc : (@description || '')
+        end
+
+        def input_schema(schema = nil)
+          schema ? @input_schema = schema : @input_schema
+        end
+
+        def deferred(val = nil)
+          return @deferred || false if val.nil?
+
+          @deferred = val
+        end
+
+        def deferred?
+          deferred
+        end
+
+        # Metadata that replaces Capability - Tools::Registry IS the catalog
+        def extension(val = nil)
+          return @extension if val.nil?
+
+          @extension = val
+        end
+
+        def runner(val = nil)
+          return @runner if val.nil?
+
+          @runner = val
+        end
+
+        def tags(val = nil)
+          return @tags || [] if val.nil?
+
+          @tags = val
+        end
+
+        def mcp_category(val = nil)
+          return @mcp_category if val.nil?
+
+          @mcp_category = val
+        end
+
+        def mcp_tier(val = nil)
+          return @mcp_tier if val.nil?
+
+          @mcp_tier = val
+        end
+
+        def call(**_args)
+          raise NotImplementedError, "#{name} must implement .call"
+        end
+
+        def text_response(data)
+          text = data.is_a?(String) ? data : Legion::JSON.dump(data)
+          { content: [{ type: 'text', text: text }] }
+        end
+
+        def error_response(msg)
+          { content: [{ type: 'text', text: Legion::JSON.dump({ error: msg }) }], error: true }
+        end
+      end
+    end
+  end
+end