legion-mcp 0.1.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9bef62b03828f3bda4594cb1eb2fa020da240b3df72db55412a65f854a515f40
-  data.tar.gz: fb5272985978c3d78b03c20b4dafc724cd869f20e7cf25daabdbacae715a889a
+  metadata.gz: bc7341c88afa89639cebd05ccffc1dfb00792062373fe295743f525c9c0380c9
+  data.tar.gz: d2b832be2e2942286489edad666215e13f8de19b888a32551bdedef4e70b1f7f
 SHA512:
-  metadata.gz: 46793c8c4aa53e27f5831cbfec97984209fda9233325001b2fd2f87bf34502e1ee5a7196243ac90fb79cd5dd2351f2fc3078f952680ee25c735534150bc5b984
-  data.tar.gz: 4cd1ff55314687a3d5aa7028b53393d3997c53e455bd170cf96b1a93a1486dd1b56dab51c4fba9481d194639068e44622ba991caa5b8497099f411b8b051870b
+  metadata.gz: 89874ef7825b398392ed7966573379a9c9edc55500cb874bb79897b3b1f65631ff1c594c90420948468d00d9cbe9e8a83838d482d491d7260cea76450b977358
+  data.tar.gz: 58b8e23f9a5a37a87f2d50150cdc8872deaa654524c1ce92a507ac7b157aa9b687a6b99a591d3841f94e37a567dc7f30a4922ca55e5e1646072cf84331947354

data/CHANGELOG.md

@@ -1,6 +1,36 @@
 # legion-mcp Changelog
 
-## v0.1.0
+## [0.4.0] - 2026-03-20
+
+### Added
+- PatternSchema v1: portable pattern format with trust-level confidence capping on import/export
+- PatternExchange: bulk import/export of patterns via JSON files with deduplication
+- PatternGossip: AMQP-based pattern sharing between instances (org trust level)
+- ColdStart: community pattern loading on first boot when PatternStore is empty
+
+## [0.3.0] - 2026-03-20
+
+### Added
+- GapDetector: analyzes observations for repeated manual patterns and frequent unpatched intents
+- PatternCompiler: generates compressed tool definitions and compiled workflows from promoted patterns
+- CapabilityGenerator: autonomous function generation from detected gaps with LLM code generation
+- Validation pipeline with Ruby syntax check and optional lex-eval integration
+
+## [0.2.0] - 2026-03-20
+
+### Fixed
+- Observer feedback bug: records actual matched tool name instead of 'legion.do'
+- wire_observer skips legion.do calls (feedback handled inside DoAction with correct tool name)
+
+### Added
+- Boot-time L2 → L0 pattern hydration (`PatternStore.hydrate_from_l2`)
+- Pattern confidence decay with archive threshold (`PatternStore.decay_all`)
+- Tier 1 execution: pattern-hinted local/fleet LLM routing in DoAction
+- Tier 2 execution: cloud LLM with compressed catalog context in DoAction
+- `legion.plan` meta-tool for multi-step workflow planning (36 tools total)
+- Response template learning from observed Tier 0 outputs (`PatternStore.learn_response_template`)
+
+## [0.1.0]
 
 ### Added
 - Initial extraction from LegionIO

data/lib/legion/mcp/capability_generator.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Legion
+  module MCP
+    module CapabilityGenerator
+      module_function
+
+      def generate_from_gap(gap)
+        name = infer_name(gap)
+        description = infer_description(gap)
+
+        proposal = {
+          name:         name,
+          description:  description,
+          source_gap:   gap,
+          runner_code:  nil,
+          spec_code:    nil,
+          confidence:   :sandbox,
+          generated_at: Time.now
+        }
+
+        if llm_available?
+          proposal[:runner_code] = generate_runner(name, description, gap)
+          proposal[:spec_code] = generate_spec(name, description)
+        end
+
+        proposal
+      rescue StandardError => e
+        { error: e.message, source_gap: gap }
+      end
+
+      def validate(runner_code:, spec_code:) # rubocop:disable Lint/UnusedMethodArgument
+        result = { syntax_valid: false, eval_score: nil }
+
+        result[:syntax_valid] = syntax_valid?(runner_code) if runner_code
+
+        if runner_code && defined?(Legion::Extensions::Eval::Client)
+          begin
+            client = Legion::Extensions::Eval::Client.new
+            eval_result = client.evaluate(code: runner_code, criteria: 'code_quality')
+            result[:eval_score] = eval_result[:score] if eval_result[:success]
+          rescue StandardError
+            nil
+          end
+        end
+
+        result
+      end
+
+      def infer_name(gap)
+        case gap[:type]
+        when :frequent_intent
+          gap[:sample_intents].first.to_s.gsub(/\s+/, '_').downcase.slice(0, 30)
+        when :repeated_chain
+          gap[:chain].join('_then_').slice(0, 30)
+        else
+          "generated_#{Time.now.to_i}"
+        end
+      end
+
+      def infer_description(gap)
+        case gap[:type]
+        when :frequent_intent
+          "Auto-generated from #{gap[:count]} observed intents: #{gap[:sample_intents].first(3).join(', ')}"
+        when :repeated_chain
+          "Auto-generated from #{gap[:count]} observed sequences: #{gap[:chain].join(' -> ')}"
+        else
+          'Auto-generated capability'
+        end
+      end
+
+      def generate_runner(name, description, _gap)
+        return nil unless llm_available?
+
+        prompt = "Generate a Ruby module for a LegionIO runner named '#{name}'. " \
+                 "Description: #{description}. " \
+                 'Follow the pattern: module with module_function methods returning hashes. ' \
+                 'Include proper error handling. Return ONLY the Ruby code.'
+
+        Legion::LLM.ask(prompt)
+      rescue StandardError
+        nil
+      end
+
+      def generate_spec(name, description)
+        return nil unless llm_available?
+
+        prompt = "Generate RSpec tests for a Ruby module named '#{name}'. " \
+                 "Description: #{description}. " \
+                 'Use described_class pattern. Return ONLY the Ruby code.'
+
+        Legion::LLM.ask(prompt)
+      rescue StandardError
+        nil
+      end
+
+      def syntax_valid?(code)
+        RubyVM::InstructionSequence.compile(code)
+        true
+      rescue SyntaxError
+        false
+      end
+
+      def llm_available?
+        defined?(Legion::LLM) && Legion::LLM.respond_to?(:started?) && Legion::LLM.started?
+      end
+    end
+  end
+end

data/lib/legion/mcp/cold_start.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative 'pattern_store'
+require_relative 'pattern_exchange'
+
+module Legion
+  module MCP
+    module ColdStart
+      module_function
+
+      def load_community_patterns(path: nil)
+        return { skipped: true, reason: 'store not empty' } unless PatternStore.empty?
+
+        path ||= configured_path
+        return { skipped: true, reason: 'no path configured' } unless path
+
+        PatternExchange.import_from_file(path, trust_level: :community)
+      rescue StandardError => e
+        { error: e.message, imported: 0 }
+      end
+
+      def configured_path
+        return nil unless defined?(Legion::Settings)
+
+        Legion::Settings.dig(:mcp, :cold_start, :patterns_path)
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/legion/mcp/gap_detector.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require 'digest'
+
+module Legion
+  module MCP
+    module GapDetector
+      FREQUENCY_THRESHOLD = 5
+      CHAIN_THRESHOLD = 3
+
+      module_function
+
+      def analyze
+        gaps = []
+        gaps.concat(detect_frequent_intents)
+        gaps.concat(detect_repeated_chains)
+        gaps
+      end
+
+      def detect_frequent_intents
+        intents = Observer.recent_intents(Observer::INTENT_BUFFER_MAX)
+        grouped = intents.group_by { |i| i[:matched_tool] }
+
+        grouped.filter_map do |tool, occurrences|
+          next if occurrences.size < FREQUENCY_THRESHOLD
+          next if PatternStore.pattern_exists?(Digest::SHA256.hexdigest(tool.to_s))
+
+          { type: :frequent_intent, tool: tool, count: occurrences.size,
+            sample_intents: occurrences.last(3).map { |o| o[:intent] } }
+        end
+      end
+
+      def detect_repeated_chains
+        recent = Observer.recent(Observer::RING_BUFFER_MAX)
+        chains = {}
+        recent.each_cons(2) do |a, b|
+          key = "#{a[:tool_name]}->#{b[:tool_name]}"
+          chains[key] = (chains[key] || 0) + 1
+        end
+
+        chains.filter_map do |chain, count|
+          next if count < CHAIN_THRESHOLD
+
+          { type: :repeated_chain, chain: chain.split('->'), count: count }
+        end
+      end
+
+      def reset!
+        # No persistent state to clear — analysis reads from Observer
+      end
+    end
+  end
+end

data/lib/legion/mcp/pattern_compiler.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Legion
+  module MCP
+    module PatternCompiler
+      module_function
+
+      def compile_tool_definitions
+        return [] unless defined?(Legion::MCP::Server::TOOL_CLASSES)
+
+        Legion::MCP::Server::TOOL_CLASSES.map do |klass|
+          name = klass.respond_to?(:tool_name) ? klass.tool_name : klass.name
+          desc = klass.respond_to?(:description) ? klass.description : ''
+          params = extract_params(klass)
+
+          compressed = "#{name}(#{params.join(', ')}) -- #{desc.split('.').first}"
+          { name: name, compressed: compressed.slice(0, 200), full_description: desc }
+        end
+      end
+
+      def compile_workflows
+        PatternStore.patterns.filter_map do |_hash, pattern|
+          next if (pattern[:confidence] || 0) < 0.6
+
+          {
+            intent:     pattern[:intent_text],
+            tools:      pattern[:tool_chain],
+            confidence: pattern[:confidence],
+            template:   pattern[:response_template]
+          }
+        end
+      end
+
+      def extract_params(klass)
+        return [] unless klass.respond_to?(:input_schema)
+
+        schema = klass.input_schema
+        props = if schema.is_a?(Hash)
+                  schema[:properties] || schema['properties']
+                elsif schema.respond_to?(:to_h)
+                  schema.to_h[:properties]
+                end
+        return [] unless props
+
+        props.keys.map(&:to_s)
+      rescue StandardError
+        []
+      end
+    end
+  end
+end

data/lib/legion/mcp/pattern_exchange.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'pattern_schema'
+require_relative 'pattern_store'
+
+module Legion
+  module MCP
+    module PatternExchange
+      module_function
+
+      def export_all(min_confidence: 0.5)
+        PatternStore.patterns.filter_map do |_hash, pattern|
+          next if (pattern[:confidence] || 0) < min_confidence
+
+          PatternSchema.export(pattern)
+        end
+      end
+
+      def import_all(patterns, trust_level: :community)
+        imported = 0
+        skipped = 0
+
+        Array(patterns).each do |external|
+          next unless PatternSchema.validate_schema(external)
+
+          internal = PatternSchema.import(external, trust_level: trust_level)
+          if PatternStore.pattern_exists?(internal[:intent_hash])
+            skipped += 1
+            next
+          end
+
+          PatternStore.store(internal)
+          imported += 1
+        end
+
+        { imported: imported, skipped: skipped }
+      end
+
+      def export_to_file(path, min_confidence: 0.5)
+        data = export_all(min_confidence: min_confidence)
+        File.write(path, ::JSON.pretty_generate(data))
+        { exported: data.size, path: path }
+      end
+
+      def import_from_file(path, trust_level: :community)
+        raw = File.read(path)
+        patterns = ::JSON.parse(raw, symbolize_names: true)
+        patterns = [patterns] if patterns.is_a?(Hash)
+        import_all(patterns, trust_level: trust_level)
+      rescue StandardError => e
+        { error: e.message, imported: 0 }
+      end
+    end
+  end
+end

data/lib/legion/mcp/pattern_gossip.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require_relative 'pattern_schema'
+
+module Legion
+  module MCP
+    module PatternGossip
+      EXCHANGE_NAME = 'tbi.patterns'
+      ANNOUNCE_TTL = 86_400
+
+      module_function
+
+      def announce(pattern)
+        return nil unless transport_available?
+
+        exported = PatternSchema.export(pattern)
+        message = {
+          action:     'announce',
+          pattern_id: exported[:pattern_id],
+          pattern:    exported,
+          origin:     { instance_id: instance_id },
+          ttl:        ANNOUNCE_TTL,
+          version:    1
+        }
+
+        Legion::Transport::Messages::Dynamic.new(
+          function: "#{EXCHANGE_NAME}.announce",
+          data:     message
+        ).publish
+
+        { published: true, pattern_id: exported[:pattern_id] }
+      rescue StandardError
+        nil
+      end
+
+      def receive(message)
+        return nil unless message.is_a?(Hash) && message[:pattern]
+
+        PatternSchema.import(message[:pattern], trust_level: :org)
+      rescue StandardError
+        nil
+      end
+
+      def transport_available?
+        defined?(Legion::Transport) &&
+          Legion::Transport.respond_to?(:connected?) &&
+          Legion::Transport.connected?
+      end
+
+      def instance_id
+        @instance_id ||= SecureRandom.uuid
+      end
+
+      def reset!
+        @instance_id = nil
+      end
+    end
+  end
+end

data/lib/legion/mcp/pattern_schema.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'digest'
+
+module Legion
+  module MCP
+    module PatternSchema
+      SCHEMA_VERSION = '1.0'
+      REQUIRED_FIELDS = %i[schema_version pattern_id intent capability_chain confidence metadata].freeze
+
+      TRUST_LEVELS = {
+        local:     0.5,
+        org:       0.4,
+        community: 0.3
+      }.freeze
+
+      module_function
+
+      def export(pattern)
+        {
+          schema_version:    SCHEMA_VERSION,
+          pattern_id:        pattern[:intent_hash],
+          intent:            {
+            description: pattern[:intent_text],
+            keywords:    extract_keywords(pattern[:intent_text])
+          },
+          capability_chain:  Array(pattern[:tool_chain]).map { |t| { tool: t, params_template: {} } },
+          response_template: pattern[:response_template] ? { engine: 'mustache', template: pattern[:response_template] } : nil,
+          confidence:        {
+            suggested_initial: [pattern[:confidence], 0.5].min,
+            source_hits:       pattern[:hit_count] || 0,
+            source_misses:     pattern[:miss_count] || 0
+          },
+          metadata:          {
+            source:      'local',
+            sensitivity: 'public',
+            created_at:  pattern[:created_at]&.iso8601
+          }
+        }
+      end
+
+      def import(external, trust_level: :community)
+        confidence = external.dig(:confidence, :suggested_initial) || TRUST_LEVELS.fetch(trust_level, 0.3)
+        confidence = [confidence, TRUST_LEVELS.fetch(trust_level, 0.3)].min
+
+        intent_text = external.dig(:intent, :description) || ''
+        intent_hash = external[:pattern_id] || Digest::SHA256.hexdigest(intent_text.downcase.strip)
+        tool_chain = Array(external[:capability_chain]).map { |c| c[:tool] || c.to_s }
+
+        template = external.dig(:response_template, :template)
+
+        {
+          intent_hash:          intent_hash,
+          intent_text:          intent_text,
+          intent_vector:        nil,
+          tool_chain:           tool_chain,
+          response_template:    template,
+          confidence:           confidence,
+          hit_count:            0,
+          miss_count:           0,
+          last_hit_at:          nil,
+          created_at:           Time.now,
+          context_requirements: nil
+        }
+      end
+
+      def validate_schema(data)
+        return false unless data.is_a?(Hash)
+
+        REQUIRED_FIELDS.all? { |f| data.key?(f) }
+      end
+
+      def extract_keywords(text)
+        return [] unless text
+
+        text.downcase.split(/\s+/).uniq.reject { |w| w.length < 3 }
+      end
+    end
+  end
+end

data/lib/legion/mcp/pattern_store.rb

@@ -4,10 +4,11 @@ require 'json'
 
 module Legion
   module MCP
-    module PatternStore
+    module PatternStore # rubocop:disable Metrics/ModuleLength
       CONFIDENCE_SUCCESS_DELTA = 0.02
       CONFIDENCE_FAILURE_DELTA = -0.05
       SEEDED_CONFIDENCE        = 0.5
+      DECAY_ARCHIVE_THRESHOLD  = 0.1
 
       module_function
 
@@ -129,6 +130,10 @@ module Legion
         mutex.synchronize { patterns_l0.size }
       end
 
+      def empty?
+        size.zero?
+      end
+
       def stats
         total_hits = 0
         total_conf = 0.0
@@ -149,9 +154,59 @@ module Legion
         }
       end
 
+      def learn_response_template(intent_hash, result_data, threshold: 3)
+        return unless result_data.is_a?(Hash)
+
+        template_mutex.synchronize do
+          buffer = template_observations[intent_hash] ||= []
+          buffer << result_data.keys.sort
+          buffer.shift if buffer.size > 10
+
+          return unless buffer.size >= threshold
+
+          if buffer.last(threshold).uniq.size == 1
+            keys = buffer.last.sort
+            template = keys.map { |k| "#{k}: {{#{k}}}" }.join(', ')
+            mutex.synchronize do
+              pattern = patterns_l0[intent_hash]
+              pattern[:response_template] = template if pattern
+            end
+            sync_to_persistence(intent_hash)
+          end
+        end
+      end
+
+      def decay_all(factor: 0.998)
+        archived = []
+        mutex.synchronize do
+          patterns_l0.each do |hash, pattern|
+            pattern[:confidence] = (pattern[:confidence] * factor).clamp(0.0, 1.0)
+            archived << hash if pattern[:confidence] < DECAY_ARCHIVE_THRESHOLD
+          end
+          archived.each { |hash| patterns_l0.delete(hash) }
+        end
+
+        archived.each { |hash| archive_l2(hash) }
+        sync_all_to_persistence unless archived.empty?
+      end
+
+      def hydrate_from_l2
+        return unless local_db_available?
+
+        table = ensure_local_table
+        table.each do |row|
+          pattern = deserialize_pattern(row)
+          mutex.synchronize { patterns_l0[pattern[:intent_hash]] = pattern }
+          persist_l1(pattern[:intent_hash], pattern)
+        end
+      rescue StandardError
+        nil
+      end
+
       def reset!
         mutex.synchronize { patterns_l0.clear }
         candidates_mutex.synchronize { candidates_buffer.clear }
+        template_mutex.synchronize { template_observations.clear }
       end
 
       # --- Private helpers ---
@@ -224,6 +279,19 @@ module Legion
         persist_l2(intent_hash, pattern)
       end
 
+      def archive_l2(intent_hash)
+        return unless local_db_available?
+
+        table = ensure_local_table
+        table.where(intent_hash: intent_hash).delete
+      rescue StandardError
+        nil
+      end
+
+      def sync_all_to_persistence
+        mutex.synchronize { patterns_l0.keys.dup }.each { |h| sync_to_persistence(h) }
+      end
+
       def local_db_available?
         defined?(Legion::Data::Local) &&
           Legion::Data::Local.respond_to?(:connected?) &&
@@ -298,6 +366,14 @@ module Legion
       def candidates_mutex
         @candidates_mutex ||= Mutex.new
       end
+
+      def template_observations
+        @template_observations ||= {}
+      end
+
+      def template_mutex
+        @template_mutex ||= Mutex.new
+      end
     end
   end
 end

data/lib/legion/mcp/server.rb

@@ -37,7 +37,9 @@ require_relative 'tools/rbac_assignments'
 require_relative 'tools/rbac_grants'
 require_relative 'context_compiler'
 require_relative 'embedding_index'
+require_relative 'cold_start'
 require_relative 'tools/do_action'
+require_relative 'tools/plan_action'
 require_relative 'tools/discover_tools'
 require_relative 'resources/runner_catalog'
 require_relative 'resources/extension_info'
@@ -80,6 +82,7 @@ module Legion
         Tools::RbacAssignments,
         Tools::RbacGrants,
         Tools::DoAction,
+        Tools::PlanAction,
         Tools::DiscoverTools
       ].freeze
 
@@ -110,6 +113,12 @@ module Legion
             build_filtered_tool_list.map(&:to_h)
           end
 
+          # Hydrate pattern store from L2 persistence (SQLite) on boot
+          PatternStore.hydrate_from_l2 if defined?(PatternStore)
+
+          # Cold-start: load community patterns if store is still empty after hydration
+          ColdStart.load_community_patterns if defined?(ColdStart)
+
           # Populate embedding index for semantic tool matching (lazy — no-op if LLM unavailable)
           populate_embedding_index
 
@@ -141,8 +150,11 @@ module Legion
             error:       data[:error]
           )
 
-          # Wire pattern promotion feedback loop for do_action calls
-          return unless data[:tool_name] == 'legion.do' && data[:tool_arguments]&.dig(:intent)
+          # Pattern promotion for legion.do is handled inside DoAction itself
+          # (which knows the actual resolved tool name). For other tools called
+          # directly, we record the intent+result here if an intent is present.
+          return if data[:tool_name] == 'legion.do'
+          return unless data[:tool_arguments]&.dig(:intent)
 
           Observer.record_intent_with_result(
             intent:    data[:tool_arguments][:intent],

data/lib/legion/mcp/tier_router.rb

@@ -37,6 +37,7 @@ module Legion
           results = execute_tool_chain(pattern[:tool_chain], params)
           response = generate_response(results, pattern)
           PatternStore.record_hit(intent_hash)
+          PatternStore.learn_response_template(intent_hash, results.first) if results.size == 1
 
           elapsed_ms = ((::Process.clock_gettime(::Process::CLOCK_MONOTONIC) - start_time) * 1000).round(2)
           {

data/lib/legion/mcp/tools/do_action.rb

@@ -30,35 +30,74 @@ module Legion
         )
 
         class << self
-          def call(intent:, params: {}, context: {})
-            # Try Tier 0 first (learned patterns)
+          def call(intent:, params: {}, context: {}) # rubocop:disable Metrics/CyclomaticComplexity
             tier_result = try_tier0(intent, params, context)
-            if tier_result && tier_result[:tier].zero?
+
+            case tier_result&.dig(:tier)
+            when 0
               return text_response(tier_result[:response].merge(
                                      _meta: { tier:       0,
                                               latency_ms: tier_result[:latency_ms],
                                               confidence: tier_result[:pattern_confidence] }
                                    ))
+            when 1
+              llm_result = try_tier1(intent, tier_result[:pattern])
+              if llm_result
+                return text_response({ result: llm_result,
+                                       _meta:  { tier: 1, pattern_hint: tier_result[:pattern][:intent_text] } })
+              end
+            when 2
+              llm_result = try_tier2(intent)
+              return text_response({ result: llm_result, _meta: { tier: 2 } }) if llm_result
             end
 
-            # Fall back to ContextCompiler tool matching (original behavior)
+            # Fall back to ContextCompiler tool matching
             matched = ContextCompiler.match_tool(intent)
             return error_response("No matching tool found for intent: #{intent}") if matched.nil?
 
-            Legion::MCP::Observer.record_intent(intent, matched) if defined?(Legion::MCP::Observer)
+            matched_name = matched.respond_to?(:tool_name) ? matched.tool_name : matched.to_s
 
             tool_params = params.transform_keys(&:to_sym)
-            if tool_params.empty?
-              matched.call
-            else
-              matched.call(**tool_params)
-            end
+            result = tool_params.empty? ? matched.call : matched.call(**tool_params)
+
+            record_feedback(intent, matched_name, success: true)
+            result
           rescue StandardError => e
+            record_feedback(intent, matched_name, success: false) if defined?(matched_name)
             error_response("Failed: #{e.message}")
           end
 
           private
 
+          def record_feedback(intent, tool_name, success:)
+            return unless defined?(Legion::MCP::Observer)
+
+            Legion::MCP::Observer.record_intent_with_result(
+              intent:    intent,
+              tool_name: tool_name,
+              success:   success
+            )
+          end
+
+          def try_tier1(intent, pattern)
+            return nil unless defined?(Legion::LLM) && Legion::LLM.started?
+
+            hint = "Known pattern: #{pattern[:intent_text]}. Tools: #{Array(pattern[:tool_chain]).join(', ')}. "
+            Legion::LLM.ask("#{hint}User intent: #{intent}")
+          rescue StandardError
+            nil
+          end
+
+          def try_tier2(intent)
+            return nil unless defined?(Legion::LLM) && Legion::LLM.started?
+
+            catalog = ContextCompiler.respond_to?(:compressed_catalog) ? ContextCompiler.compressed_catalog : []
+            context_str = catalog.any? ? "Available tools: #{Legion::JSON.dump(catalog)}. " : ''
+            Legion::LLM.ask("#{context_str}User intent: #{intent}")
+          rescue StandardError
+            nil
+          end
+
           def try_tier0(intent, params, context)
             return nil unless defined?(Legion::MCP::TierRouter)
 

data/lib/legion/mcp/tools/plan_action.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Legion
+  module MCP
+    module Tools
+      class PlanAction < ::MCP::Tool
+        tool_name 'legion.plan'
+        description 'Get a multi-step workflow plan for a complex goal. Returns ordered steps with tools and parameters.'
+
+        input_schema(
+          properties: {
+            goal:    { type: 'string', description: 'Natural language description of the goal' },
+            context: { type: 'object', description: 'Additional context', additionalProperties: true }
+          },
+          required:   ['goal']
+        )
+
+        class << self
+          def call(goal:, context: {}) # rubocop:disable Lint/UnusedMethodArgument
+            matched = ContextCompiler.match_tools(goal, limit: 10)
+            steps = matched.map.with_index(1) do |tool, idx|
+              { step: idx, tool: tool[:name], relevance: tool[:score].round(3) }
+            end
+
+            return text_response({ plan: nil, reason: 'no matching tools found for goal' }) if steps.empty?
+
+            plan = { goal: goal, steps: steps, tool_count: steps.size }
+            plan[:narrative] = generate_narrative(goal, steps) if llm_available?
+
+            text_response(plan)
+          rescue StandardError => e
+            error_response("Plan failed: #{e.message}")
+          end
+
+          private
+
+          def generate_narrative(goal, steps)
+            tool_list = steps.map { |s| s[:tool] }.join(', ')
+            Legion::LLM.ask("Create a brief execution plan for: #{goal}. Available tools: #{tool_list}")
+          rescue StandardError
+            nil
+          end
+
+          def llm_available?
+            defined?(Legion::LLM) && Legion::LLM.started?
+          end
+
+          def text_response(data)
+            ::MCP::Tool::Response.new([{ type: 'text', text: Legion::JSON.dump(data) }])
+          end
+
+          def error_response(msg)
+            ::MCP::Tool::Response.new([{ type: 'text', text: Legion::JSON.dump({ error: msg }) }], error: true)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/mcp/version.rb

@@ -2,6 +2,6 @@
 
 module Legion
   module MCP
-    VERSION = '0.1.0'
+    VERSION = '0.4.0'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legion-mcp
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Esity
@@ -117,10 +117,17 @@ files:
 - legion-mcp.gemspec
 - lib/legion/mcp.rb
 - lib/legion/mcp/auth.rb
+- lib/legion/mcp/capability_generator.rb
+- lib/legion/mcp/cold_start.rb
 - lib/legion/mcp/context_compiler.rb
 - lib/legion/mcp/context_guard.rb
 - lib/legion/mcp/embedding_index.rb
+- lib/legion/mcp/gap_detector.rb
 - lib/legion/mcp/observer.rb
+- lib/legion/mcp/pattern_compiler.rb
+- lib/legion/mcp/pattern_exchange.rb
+- lib/legion/mcp/pattern_gossip.rb
+- lib/legion/mcp/pattern_schema.rb
 - lib/legion/mcp/pattern_store.rb
 - lib/legion/mcp/resources/extension_info.rb
 - lib/legion/mcp/resources/runner_catalog.rb
@@ -150,6 +157,7 @@ files:
 - lib/legion/mcp/tools/list_schedules.rb
 - lib/legion/mcp/tools/list_tasks.rb
 - lib/legion/mcp/tools/list_workers.rb
+- lib/legion/mcp/tools/plan_action.rb
 - lib/legion/mcp/tools/rbac_assignments.rb
 - lib/legion/mcp/tools/rbac_check.rb
 - lib/legion/mcp/tools/rbac_grants.rb