robot_lab 0.1.0 → 0.2.1

data/lib/robot_lab/robot/agent_skill_matching.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module RobotLab
+  class Robot < RubyLLM::Agent
+    # Prepended module that intercepts run() to inject relevant AgentSkills.io
+    # skills into the system prompt and tool list for the duration of each call.
+    #
+    # Owns:    @_active_agent_skills, @_agent_skill_original_instructions, @_agent_skill_injected_tools
+    # Reads:   @pending_agent_skills, @agent_skill_store, @local_tools, @chat, @name
+    # Contract: prepended (wraps super); requires TemplateRendering to have set @pending_agent_skills
+    #
+    # Skills are matched by embedding similarity between the incoming message
+    # and each pending skill's description (via DocumentStore/fastembed).
+    # Injected content is fully restored in an ensure block after run() returns.
+    module AgentSkillMatching
+      SIMILARITY_THRESHOLD = 0.70
+
+      def run(message = nil, **, &)
+        matched = match_agent_skills(message.to_s)
+        inject_agent_skills(matched) if matched.any?
+        super
+      ensure
+        restore_after_agent_skills if @_active_agent_skills&.any?
+      end
+
+      # Override to re-inject skill instructions after template re-render replaces
+      # the system prompt during a run() call with runtime kwargs.
+      def rerender_template(run_context)
+        super
+        return unless @_active_agent_skills&.any?
+
+        @_agent_skill_original_instructions = current_agent_skill_instructions
+        prepend_skill_instructions(@_active_agent_skills)
+      end
+
+      private
+
+      # Find pending AgentSkills whose descriptions are semantically similar to message.
+      #
+      # @param message [String]
+      # @param threshold [Float] cosine similarity cutoff (default SIMILARITY_THRESHOLD)
+      # @return [Array<AgentSkill>]
+      def match_agent_skills(message, threshold: SIMILARITY_THRESHOLD)
+        return [] if @pending_agent_skills.nil? || @pending_agent_skills.empty?
+
+        results = @agent_skill_store.search(message, limit: @pending_agent_skills.size)
+        results
+          .select { |r| r[:score] >= threshold }
+          .filter_map { |r| @pending_agent_skills.find { |s| s.name.to_sym == r[:key] } }
+      rescue => e
+        RobotLab.config.logger.warn(
+          "Robot '#{@name}': AgentSkill embedding failed: #{e.message}"
+        )
+        []
+      end
+
+      # Prepend skill instructions before existing system prompt content.
+      #
+      # @param skills [Array<AgentSkill>]
+      def prepend_skill_instructions(skills)
+        skill_content = skills.map(&:instructions).join("\n\n")
+        base          = @_agent_skill_original_instructions.to_s
+        combined      = [skill_content, base].reject(&:empty?).join("\n\n")
+        @chat.with_instructions(combined)
+      end
+
+      # Inject script tools and snapshot instructions before injection.
+      #
+      # @param skills [Array<AgentSkill>]
+      def inject_agent_skills(skills)
+        return if skills.empty?
+
+        @_active_agent_skills               = skills
+        @_agent_skill_original_instructions = current_agent_skill_instructions
+        prepend_skill_instructions(skills)
+        @_agent_skill_injected_tools = skills.flat_map(&:script_tools).compact
+        @local_tools += @_agent_skill_injected_tools
+      end
+
+      # Remove injected tools and restore original system prompt.
+      def restore_after_agent_skills
+        @local_tools -= @_agent_skill_injected_tools || []
+        @chat.with_instructions(@_agent_skill_original_instructions.to_s)
+        @_active_agent_skills               = nil
+        @_agent_skill_original_instructions = nil
+        @_agent_skill_injected_tools        = nil
+      end
+
+      # Read the current system message content from the underlying chat.
+      #
+      # @return [String, nil]
+      def current_agent_skill_instructions
+        messages = @chat.instance_variable_get(:@messages)
+        sys = messages&.find { |m| m.role.to_s == "system" }
+        sys&.content
+      end
+    end
+  end
+end

data/lib/robot_lab/robot/bus_messaging.rb

@@ -16,6 +16,9 @@ module RobotLab
     # inline. The BusPoller drains each group's queue sequentially on
     # a dedicated OS thread, so robot.run() calls never interleave.
     #
+    # Owns:    @bus, @bus_poller, @private_bus_poller, @bus_poller_group, @bus_subscriber_id, @message_counter, @outbox, @message_handler
+    # Reads:   @name
+    # Contract: ivars initialized by initialize_runtime_state before first bus operation
     module BusMessaging
       # Send a message to another robot via the bus.
       #
@@ -33,7 +36,6 @@ module RobotLab
         message
       end
 
-
       # Send a reply to a specific message via the bus.
       #
       # @param to [String, Symbol] target robot's channel name
@@ -50,7 +52,6 @@ module RobotLab
         reply
       end
 
-
       # Register a custom handler for incoming bus messages.
       #
       # Block arity controls delivery handling:
@@ -64,7 +65,6 @@ module RobotLab
         self
       end
 
-
       # Spawn a new robot on a shared bus.
       #
       # Creates a new Robot instance that shares this robot's bus,
@@ -79,7 +79,7 @@ module RobotLab
       # @param options [Hash] additional options passed to RobotLab.build
       # @return [Robot] the newly created robot
       #
-      def spawn(name: "robot", system_prompt: nil, template: nil, local_tools: [], **options)
+      def spawn(name: "robot", system_prompt: nil, template: nil, local_tools: [], **)
         ensure_bus
 
         RobotLab.build(
@@ -88,11 +88,10 @@ module RobotLab
           template: template,
           local_tools: local_tools,
           bus: @bus,
-          **options
+          **
         )
       end
 
-
       # Connect this robot to a message bus.
       #
       # If a bus is provided, the robot joins it. If no bus is provided
@@ -134,7 +133,6 @@ module RobotLab
         with_bus unless @bus
       end
 
-
       # Create a typed channel on the bus and subscribe to it.
       # Auto-creates a private BusPoller if none has been assigned.
       def setup_bus_channel
@@ -149,7 +147,6 @@ module RobotLab
         @bus_subscriber_id = @bus.subscribe(channel_name) { |delivery| enqueue_delivery(delivery) }
       end
 
-
       # Unsubscribe from the bus channel and stop the private poller if any.
       def teardown_bus_channel
         channel_name = @name.to_sym
@@ -162,13 +159,11 @@ module RobotLab
         @bus_poller_group   = :default
       end
 
-
       # Enqueue a delivery to the robot's assigned poller.
       def enqueue_delivery(delivery)
         @bus_poller.enqueue(robot: self, delivery: delivery, group: @bus_poller_group)
       end
 
-
       # Process a single delivery (called by BusPoller drain thread).
       def process_delivery(delivery)
         message = delivery.message
@@ -180,30 +175,17 @@ module RobotLab
           entry[:replies] << message
         end
 
-        if @message_handler
-          if @message_handler.arity == 1
-            delivery.ack!
-            @message_handler.call(message)
-          else
-            @message_handler.call(delivery, message)
-          end
+        if @message_handler.arity == 1
+          delivery.ack!
+          @message_handler.call(message)
         else
-          handle_message_via_llm(delivery, message)
+          @message_handler.call(delivery, message)
         end
       rescue => e
         delivery.nack! if delivery.pending?
         raise BusError, "Error handling bus message on robot '#{@name}': #{e.message}"
       end
 
-
-      # Default handler: interpret message via LLM and reply
-      def handle_message_via_llm(delivery, message)
-        delivery.ack!
-        result = run(message.content.to_s)
-        send_reply(to: message.from.to_sym, content: result.last_text_content, in_reply_to: message.key)
-      end
-
-
       # Publish a RobotMessage to a bus channel
       def publish_to_bus(channel_name, message)
         if defined?(Async::Task) && Async::Task.current?

data/lib/robot_lab/robot/history_search.rb

@@ -4,6 +4,10 @@ module RobotLab
   class Robot
     # Semantic search over a robot's conversation history.
     #
+    # Owns:    nothing (read-only mixin)
+    # Reads:   @chat (specifically @chat.messages)
+    # Contract: no initialization required; safe to call any time after initialize
+    #
     # Scores each message in @chat.messages against the query using stemmed
     # term-frequency cosine similarity (via the +classifier+ gem).  Returns the
     # top-N messages ranked by relevance.
@@ -61,7 +65,6 @@ module RobotLab
         case content
         when String then content
         when Array  then content.filter_map { |p| p[:text] || p["text"] }.join(" ")
-        else nil
         end
       end
     end

data/lib/robot_lab/robot/mcp_management.rb

@@ -4,9 +4,9 @@ module RobotLab
   class Robot < RubyLLM::Agent
     # MCP client lifecycle and hierarchical tool/MCP resolution.
     #
-    # Expects the including class to provide:
-    #   @mcp_config, @tools_config, @mcp_clients, @mcp_tools,
-    #   @mcp_initialized, @name, @chat, @local_tools
+    # Owns:    @mcp_clients, @mcp_tools, @mcp_initialized, @failed_mcp_configs
+    # Reads:   @mcp_config, @tools_config, @name, @chat, @local_tools
+    # Contract: ivars initialized by initialize_runtime_state; lazy init on first run
     module MCPManagement
       private
 
@@ -17,7 +17,6 @@ module RobotLab
         ToolConfig.resolve_mcp(runtime_value, parent_value: build_resolved)
       end
 
-
       # Resolve tools hierarchy: runtime -> robot build -> network -> config
       def resolve_tools_hierarchy(runtime_value, network: nil, network_config: nil)
         parent_value = network_config&.tools || network&.network&.tools || RobotLab.config.tools
@@ -25,7 +24,6 @@ module RobotLab
         ToolConfig.resolve_tools(runtime_value, parent_value: build_resolved)
       end
 
-
       # Ensure MCP clients are initialized for the given server configs.
       # On subsequent calls, retries any servers that previously failed to connect.
       def ensure_mcp_clients(mcp_servers)
@@ -50,7 +48,6 @@ module RobotLab
         @mcp_initialized = true
       end
 
-
       def init_mcp_client(server_config)
         client = MCP::Client.new(server_config)
         client.connect
@@ -74,13 +71,12 @@ module RobotLab
         )
       end
 
-
       # Retry connecting to servers that previously failed
-      def retry_failed_servers(mcp_servers, needed_servers)
+      def retry_failed_servers(_mcp_servers, needed_servers)
         return if @failed_mcp_configs.nil? || @failed_mcp_configs.empty?
 
         # Only retry servers that are still needed and still failed
-        to_retry = @failed_mcp_configs.select { |name, _| needed_servers.include?(name) }
+        to_retry = @failed_mcp_configs.slice(*needed_servers)
         return if to_retry.empty?
 
         to_retry.each do |name, server_config|
@@ -106,7 +102,6 @@ module RobotLab
         end
       end
 
-
       def discover_mcp_tools(client, server_name)
         tools = client.list_tools
 
@@ -129,7 +124,6 @@ module RobotLab
         )
       end
 
-
       def extract_server_name(server_config)
         case server_config
         when Hash

data/lib/robot_lab/robot/template_rendering.rb

@@ -1,14 +1,12 @@
 # frozen_string_literal: true
 
-require 'set'
-
 module RobotLab
   class Robot < RubyLLM::Agent
     # Template loading, rendering, and front-matter extraction.
     #
-    # Expects the including class to provide:
-    #   @chat, @template, @build_context, @name, @name_from_constructor,
-    #   @description, @local_tools, @mcp_config
+    # Owns:    @expanded_skills, @pending_agent_skills, @agent_skill_store
+    # Reads:   @chat, @template, @build_context, @name, @name_from_constructor, @description, @local_tools, @mcp_config, @config
+    # Contract: called during initialize after assign_identity_ivars and build_effective_config
     module TemplateRendering
       # Front matter keys that map to chat configuration methods
       FRONT_MATTER_CONFIG_KEYS = %i[
@@ -64,7 +62,6 @@ module RobotLab
         end
       end
 
-
       # Re-render the template with run-time context merged into build-time context.
       # prompt_manager parameters may be required (null) and only available at run time.
       def rerender_template(run_context)
@@ -93,64 +90,85 @@ module RobotLab
         end
       end
 
-
       # Orchestrate skill expansion and template application.
       #
       # @param skill_ids [Array<Symbol>] skill IDs from constructor + front matter
       # @param context [Hash, Proc] variables to pass to all templates
       def apply_skills_and_template_to_chat(skill_ids, context)
+        bodies, accumulated_config, extras = collect_prompt_content(skill_ids, context)
+        apply_prompt_to_chat(bodies, accumulated_config, extras)
+      end
+
+      # Expand skills and render all bodies, configs, and extras into plain data.
+      # Pure computation — reads ivars but does not mutate @chat.
+      #
+      # @return [Array(Array<String>, RunConfig, Hash)] bodies, merged config, extras hash
+      def collect_prompt_content(skill_ids, context)
         visited = Set.new
-        # Prevent skills from pulling in the main template
         visited.add(@template) if @template
-
         @expanded_skills = expand_skills(skill_ids, visited)
 
         extras = {}
         accumulated_config = RunConfig.new
         bodies = []
-
         resolved_ctx = resolve_context(context, network: nil)
 
-        # Process each expanded skill
         @expanded_skills.each do |skill_id|
           parsed = PM.parse(skill_id)
           accumulate_extras(parsed.metadata, extras)
-          fm_config = RunConfig.from_front_matter(parsed.metadata)
-          accumulated_config = accumulated_config.merge(fm_config)
+          accumulated_config = accumulated_config.merge(RunConfig.from_front_matter(parsed.metadata))
           body = render_body(parsed, resolved_ctx)
           bodies << body if body
         end
 
-        # Process main template if present
         if @template
           parsed = PM.parse(@template)
           accumulate_extras(parsed.metadata, extras)
-          fm_config = RunConfig.from_front_matter(parsed.metadata)
-          accumulated_config = accumulated_config.merge(fm_config)
+          accumulated_config = accumulated_config.merge(RunConfig.from_front_matter(parsed.metadata))
           body = render_body(parsed, resolved_ctx)
           bodies << body if body
         end
 
-        # Apply accumulated extras (respects constructor precedence)
+        [bodies, accumulated_config, extras]
+      end
+
+      # Apply collected prompt content to @chat.
+      # Pure mutation — takes plain data and writes to @chat.
+      #
+      # @param bodies [Array<String>] rendered template bodies
+      # @param accumulated_config [RunConfig] merged skill + template config
+      # @param extras [Hash] accumulated front-matter extras (name, description, tools, mcp)
+      def apply_prompt_to_chat(bodies, accumulated_config, extras)
         apply_accumulated_extras(extras)
 
-        # Constructor config overrides skill + template config
         effective = accumulated_config.merge(@config)
         effective.apply_to(@chat)
 
-        # Set instructions once with all bodies joined
         combined = bodies.join("\n\n")
         @chat.with_instructions(combined) unless combined.empty?
       end
 
-
       # Recursively expand skill IDs depth-first.
+      # Checks AgentSkillCatalog first; falls back to PM template lookup.
       # Returns a flat Array<Symbol> in processing order (deepest first).
       #
       # @param skill_ids [Array<Symbol>] skill IDs to expand
       # @param visited [Set<Symbol>] already-visited IDs for cycle detection
       # @return [Array<Symbol>] flat ordered list of skill IDs
       def expand_skills(skill_ids, visited = Set.new)
+        expand_skills_with_catalog(skill_ids, visited, AgentSkillCatalog.instance)
+      end
+
+      # Recursively expand skill IDs depth-first, using the given catalog.
+      # AgentSkills folder format takes priority over PM template lookup.
+      # Catalog hits are stored in @pending_agent_skills / @agent_skill_store
+      # and are NOT included in the returned Array (they are handled separately).
+      #
+      # @param skill_ids [Array<Symbol>] skill IDs to expand
+      # @param visited [Set<Symbol>] already-visited IDs for cycle detection
+      # @param catalog [AgentSkillCatalog] catalog to check first
+      # @return [Array<Symbol>] flat ordered list of PM-based skill IDs
+      def expand_skills_with_catalog(skill_ids, visited, catalog)
         result = []
 
         skill_ids.each do |skill_id|
@@ -165,21 +183,32 @@ module RobotLab
 
           visited.add(skill_id)
 
-          # Parse the skill template and check for nested skills
+          # Check catalog first: AgentSkills folder format takes priority
+          if (agent_skill = catalog.find(skill_id))
+            @pending_agent_skills ||= []
+            unless defined?(RobotLab::DocumentStore)
+              raise LoadError,
+                    "robot_lab-document_store is required to use AgentSkill catalogs. " \
+                    "Add `gem 'robot_lab-document_store'` to your Gemfile."
+            end
+            @agent_skill_store ||= RobotLab::DocumentStore.new
+            @pending_agent_skills << agent_skill
+            @agent_skill_store.store(agent_skill.name.to_sym, agent_skill.description)
+            next
+          end
+
+          # Fall back to PM template (existing behavior)
           parsed = PM.parse(skill_id)
           nested = extract_skills_from_metadata(parsed.metadata)
 
-          # Recurse on nested skills first (depth-first)
-          result.concat(expand_skills(nested, visited)) if nested.any?
+          result.concat(expand_skills_with_catalog(nested, visited, catalog)) if nested.any?
 
-          # Then append this skill
           result << skill_id
         end
 
         result
       end
 
-
       # Extract skills array from metadata.
       #
       # @param metadata [PM::Metadata] front matter metadata
@@ -190,7 +219,6 @@ module RobotLab
         Array(metadata.skills).map(&:to_sym)
       end
 
-
       # Accumulate extras from metadata into a hash.
       # Later calls overwrite earlier values (last-write-wins).
       #
@@ -209,12 +237,10 @@ module RobotLab
           extras[:tools] = metadata.tools
         end
 
-        if metadata.respond_to?(:mcp) && metadata.mcp.is_a?(Array)
-          extras[:mcp] = metadata.mcp.map { |m| m.is_a?(Hash) ? m.transform_keys(&:to_sym) : m }
-        end
+        return unless metadata.respond_to?(:mcp) && metadata.mcp.is_a?(Array)
+        extras[:mcp] = metadata.mcp.map { |m| m.is_a?(Hash) ? m.transform_keys(&:to_sym) : m }
       end
 
-
       # Apply accumulated extras to the robot, respecting constructor precedence.
       #
       # @param extras [Hash] accumulated extras from skills + main template
@@ -231,12 +257,10 @@ module RobotLab
           @local_tools = resolve_frontmatter_tools(extras[:tools])
         end
 
-        if extras[:mcp] && ToolConfig.none_value?(@mcp_config)
-          @mcp_config = extras[:mcp]
-        end
+        return unless extras[:mcp] && ToolConfig.none_value?(@mcp_config)
+        @mcp_config = extras[:mcp]
       end
 
-
       # Extract identity and capability keys from front matter metadata.
       # Constructor-provided values take precedence over frontmatter.
       def apply_front_matter_extras(metadata)
@@ -252,12 +276,10 @@ module RobotLab
           @local_tools = resolve_frontmatter_tools(metadata.tools)
         end
 
-        if metadata.respond_to?(:mcp) && metadata.mcp.is_a?(Array) && ToolConfig.none_value?(@mcp_config)
-          @mcp_config = metadata.mcp.map { |m| m.is_a?(Hash) ? m.transform_keys(&:to_sym) : m }
-        end
+        return unless metadata.respond_to?(:mcp) && metadata.mcp.is_a?(Array) && ToolConfig.none_value?(@mcp_config)
+        @mcp_config = metadata.mcp.map { |m| m.is_a?(Hash) ? m.transform_keys(&:to_sym) : m }
       end
 
-
       # Render a parsed template body, returning nil if required params are missing.
       #
       # @param parsed [PM::Parsed] the parsed template
@@ -271,7 +293,6 @@ module RobotLab
         nil
       end
 
-
       # Resolve string tool names from frontmatter to Ruby constants.
       # Tool subclasses are instantiated; instances are used as-is.
       # Unresolvable names are skipped with a warning.
@@ -294,7 +315,6 @@ module RobotLab
         end
       end
 
-
       def resolve_context(context, network:)
         case context
         when Proc then context.call(network: network)