robot_lab 0.1.0 → 0.2.6

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.
       #
@@ -26,14 +29,19 @@ module RobotLab
       def send_message(to:, content:)
         raise BusError, "No bus configured on robot '#{@name}'" unless @bus
 
-        @message_counter += 1
-        message = RobotMessage.build(id: @message_counter, from: @name, content: content)
-        @outbox[message.key] = { message: message, status: :sent, replies: [] }
+        # Counter + outbox are shared with the poller thread (reply correlation)
+        # and with other senders; mutate them under the bus mutex. Publish (which
+        # does I/O) stays outside the lock.
+        message = @bus_mutex.synchronize do
+          @message_counter += 1
+          msg = RobotMessage.build(id: @message_counter, from: @name, content: content)
+          @outbox[msg.key] = { message: msg, status: :sent, replies: [] }
+          msg
+        end
         publish_to_bus(to.to_sym, message)
         message
       end
 
-
       # Send a reply to a specific message via the bus.
       #
       # @param to [String, Symbol] target robot's channel name
@@ -44,13 +52,14 @@ module RobotLab
       def send_reply(to:, content:, in_reply_to:)
         raise BusError, "No bus configured on robot '#{@name}'" unless @bus
 
-        @message_counter += 1
-        reply = RobotMessage.build(id: @message_counter, from: @name, content: content, in_reply_to: in_reply_to)
+        reply = @bus_mutex.synchronize do
+          @message_counter += 1
+          RobotMessage.build(id: @message_counter, from: @name, content: content, in_reply_to: in_reply_to)
+        end
         publish_to_bus(to.to_sym, reply)
         reply
       end
 
-
       # Register a custom handler for incoming bus messages.
       #
       # Block arity controls delivery handling:
@@ -64,6 +73,36 @@ module RobotLab
         self
       end
 
+      # Automatically respond to inbound (non-reply) bus tasks: run +responder+ to
+      # produce a reply, and send it back to the sender. This is the symmetric
+      # counterpart to how a Cyborg answers its human — one call makes any bus
+      # member a first-class responder instead of hand-wiring {#on_message}.
+      #
+      # The responder runs on the poller drain thread, so deliveries to this member
+      # are handled one at a time (a long turn delays the next inbound message).
+      #
+      # @param auto_reply [Boolean] send the responder's result back to the sender
+      # @yield [message] the inbound task; return the reply content (nil => no reply)
+      # @return [self]
+      def respond_to_tasks(auto_reply: true, &responder)
+        on_message do |message|
+          next if message.reply?
+
+          reply = responder.call(message)
+          send_reply(to: message.from, content: reply, in_reply_to: message.key) if auto_reply && reply
+        end
+        self
+      end
+
+      # Serve inbound bus tasks by running each through this member's #run and
+      # replying with the result — the one-call way to make a Robot cooperate on
+      # the bus the way a Cyborg already does out of the box.
+      #
+      # @param auto_reply [Boolean]
+      # @return [self]
+      def serve(auto_reply: true)
+        respond_to_tasks(auto_reply: auto_reply) { |message| run(bus_task_content(message)).reply }
+      end
 
       # Spawn a new robot on a shared bus.
       #
@@ -79,7 +118,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,10 +127,23 @@ module RobotLab
           template: template,
           local_tools: local_tools,
           bus: @bus,
-          **options
+          **inherited_llm_settings,
+          **
         )
       end
 
+      # Model/provider a spawned robot inherits from its parent so a specialist
+      # runs on the SAME LLM as the robot that spawned it (e.g. a local Ollama
+      # model) instead of falling back to the global default. Caller-supplied
+      # opts override these.
+      #
+      # @return [Hash]
+      def inherited_llm_settings
+        settings = {}
+        settings[:model]    = model    if model
+        settings[:provider] = provider if provider
+        settings
+      end
 
       # Connect this robot to a message bus.
       #
@@ -134,7 +186,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 +200,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,48 +212,44 @@ module RobotLab
         @bus_poller_group   = :default
       end
 
+      # Flatten a task message's content to text for #run.
+      def bus_task_content(message)
+        content = message.content
+        content.is_a?(Hash) ? content.map { |k, v| "#{k}: #{v}" }.join("\n") : content.to_s
+      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
+        correlate_reply(message) if message.reply?
 
-        # Correlate replies with outbox entries
-        if message.reply? && @outbox.key?(message.in_reply_to)
-          entry = @outbox[message.in_reply_to]
-          entry[:status] = :replied
-          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
 
+      # Mark the sender's outbox entry replied. Shared with senders on other
+      # threads, so guard with the bus mutex.
+      def correlate_reply(message)
+        @bus_mutex.synchronize do
+          entry = @outbox[message.in_reply_to] or return
 
-      # 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)
+          entry[:status] = :replied
+          entry[:replies] << message
+        end
       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/hooking.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module RobotLab
+  class Robot < RubyLLM::Agent
+    module Hooking
+      def run(message = nil, network: nil, task: nil, network_memory: nil, network_config: nil,
+              memory: nil, mcp: :none, tools: :none, hooks: nil, **kwargs, &block)
+        run_memory = resolve_run_memory(memory, network: network, network_memory: network_memory)
+        previous_writer = run_memory.current_writer
+        run_memory.current_writer = @name
+        context = RunHookContext.new(
+          robot: self,
+          network: network,
+          task: task,
+          memory: run_memory,
+          config: @config,
+          request: message
+        )
+
+        registries = hook_registries(network)
+
+        begin
+          RobotLab.with_hook_scope(registries, hooks) do
+            RobotLab::Hooks.run(:run, context, registries: registries, per_run_hooks: hooks) do
+              run_context = kwargs.except(:with)
+              prepare_tools(message: context.request, mcp: mcp, tools: tools,
+                            network: network, network_config: network_config)
+              rerender_template(run_context) if @template && run_context.any?
+              reservation = reserve_budget!
+              response = invoke_ask(context: context, kwargs: kwargs, hooks: hooks, block: block)
+              result = build_result(response, run_memory)
+              reconcile_budget!(reservation, response: response, result: result)
+              enforce_token_budget!
+              enforce_cost_budget!
+              result
+            end
+          end
+        ensure
+          remove_doom_loop_detection
+          restore_tool_call_callback if @config.max_tool_rounds
+          run_memory.current_writer = previous_writer
+        end
+      end
+
+      def on(handler_class, context: nil)
+        @hooks.on(handler_class, context: context)
+      end
+
+      private
+
+      def hook_registries(network = nil)
+        [RobotLab.hooks, network&.hooks, @hooks]
+      end
+    end
+  end
+end

data/lib/robot_lab/robot/mcp_management.rb

@@ -4,27 +4,31 @@ 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
 
       # Resolve MCP hierarchy: runtime -> robot build -> network -> config
       def resolve_mcp_hierarchy(runtime_value, network: nil, network_config: nil)
-        parent_value = network_config&.mcp || network&.network&.mcp || RobotLab.config.mcp
+        parent_value = network_config&.mcp || network_parent_config(network)&.mcp || RobotLab.config.mcp
         build_resolved = ToolConfig.resolve_mcp(@mcp_config, parent_value: parent_value)
         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
+        parent_value = network_config&.tools || network_parent_config(network)&.tools || RobotLab.config.tools
         build_resolved = ToolConfig.resolve_tools(@tools_config, parent_value: parent_value)
         ToolConfig.resolve_tools(runtime_value, parent_value: build_resolved)
       end
 
+      def network_parent_config(network)
+        return network.config if network.respond_to?(:config)
+
+        network&.network
+      end
 
       # Ensure MCP clients are initialized for the given server configs.
       # On subsequent calls, retries any servers that previously failed to connect.
@@ -50,7 +54,6 @@ module RobotLab
         @mcp_initialized = true
       end
 
-
       def init_mcp_client(server_config)
         client = MCP::Client.new(server_config)
         client.connect
@@ -74,13 +77,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 +108,6 @@ module RobotLab
         end
       end
 
-
       def discover_mcp_tools(client, server_name)
         tools = client.list_tools
 
@@ -129,7 +130,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[
@@ -47,7 +45,7 @@ module RobotLab
         # Front matter is the base; @config (from constructor kwargs) overrides.
         fm_config = RunConfig.from_front_matter(parsed.metadata)
         effective = fm_config.merge(@config)
-        effective.apply_to(@chat)
+        effective.apply_to(@chat, provider: @provider, assume_model_exists: !@provider.nil?)
 
         # Resolve context (could be a Proc)
         resolved_ctx = resolve_context(context, network: nil)
@@ -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)
+        effective.apply_to(@chat, provider: @provider, assume_model_exists: !@provider.nil?)
 
-        # 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)