robot_lab 0.0.1 → 0.0.4

data/lib/robot_lab/robot.rb

@@ -1,76 +1,57 @@
 # frozen_string_literal: true
 
 module RobotLab
-  # LLM-powered robot using ruby_llm-template for prompts
+  # LLM-powered robot built on RubyLLM::Agent
   #
-  # Robot is a thin wrapper around RubyLLM.chat that provides:
-  # - Template-based prompts via ruby_llm-template
-  # - Build-time context (static robot configuration)
-  # - Run-time context (per-request dynamic data)
-  # - Tool integration via RubyLLM::Tool
-  # - Hierarchical MCP and tools configuration
+  # Robot is a subclass of RubyLLM::Agent that adds:
+  # - Template-based prompts via prompt_manager
+  # - Shared memory (standalone or network)
+  # - Tool integration with hierarchical MCP configuration
+  # - SimpleFlow pipeline integration
   #
   # == Memory Behavior
   #
-  # Robots have two memory contexts depending on how they're used:
-  #
   # *Standalone*: Robot uses its own inherent memory (`robot.memory`).
-  # Use `robot.reset_memory` to clear it.
-  #
-  # *In a Network*: Robot uses the network's shared memory (`network.memory`).
-  # The robot's inherent memory is ignored. Use `network.reset_memory` to clear it.
-  #
-  # This allows the same robot instance to work both standalone and as part
-  # of a network, with appropriate memory isolation in each context.
+  # *In a Network*: Robot uses the network's shared memory.
   #
   # @example Simple robot with template
-  #   robot = Robot.new(
-  #     name: "helper",
-  #     template: :helper,
-  #     context: { company_name: "Acme Corp" }
-  #   )
-  #   result = robot.run(message: "Hello!", user_name: "Alice")
+  #   robot = Robot.new(name: "helper", template: :helper)
+  #   result = robot.run("Hello!")
   #
-  # @example Robot with inline system prompt (no template file needed)
-  #   robot = Robot.new(
-  #     name: "quick_bot",
-  #     system_prompt: "You are a helpful assistant. Be concise."
-  #   )
+  # @example Robot with inline system prompt
+  #   robot = Robot.new(name: "bot", system_prompt: "You are helpful.")
+  #   result = robot.run("What is 2+2?")
   #
-  # @example Robot with template and additional system prompt
-  #   robot = Robot.new(
-  #     name: "support",
-  #     template: :support_agent,
-  #     system_prompt: "Today is #{Date.today}. Current promotion: 20% off."
-  #   )
+  # @example Bare robot configured via chaining
+  #   robot = Robot.new(name: "bot")
+  #   robot.with_instructions("Be concise.").run("Hello")
   #
   # @example Robot with tools
   #   robot = Robot.new(
   #     name: "support",
   #     template: :support,
-  #     context: { policies: POLICIES },
-  #     tools: [OrderLookup, RefundProcessor]
+  #     local_tools: [OrderLookup, RefundProcessor]
   #   )
   #
-  # @example Robot with hierarchical MCP/tools config
-  #   robot = Robot.new(
-  #     name: "assistant",
-  #     template: :assistant,
-  #     mcp: :inherit,              # Inherit from network/config
-  #     tools: %w[search_code]      # Only allow search_code tool
-  #   )
-  #
-  class Robot
+  class Robot < RubyLLM::Agent
+    # Front matter keys that map to chat configuration methods
+    FRONT_MATTER_CONFIG_KEYS = %i[
+      model temperature top_p top_k max_tokens
+      presence_penalty frequency_penalty stop
+    ].freeze
+
+    # Front matter keys for robot identity and capabilities.
+    # Note: uses `robot_name` because PM::Metadata reserves `name` for the filename.
+    FRONT_MATTER_EXTRA_KEYS = %i[tools mcp robot_name description].freeze
+
     # @!attribute [r] name
     #   @return [String] the unique identifier for the robot
     # @!attribute [r] description
     #   @return [String, nil] an optional description of the robot's purpose
     # @!attribute [r] template
-    #   @return [Symbol, nil] the ERB template for the robot's prompt
+    #   @return [Symbol, nil] the prompt_manager template for the robot's prompt
     # @!attribute [r] system_prompt
     #   @return [String, nil] inline system prompt (used alone or appended to template)
-    # @!attribute [r] model
-    #   @return [String, Object] the LLM model identifier or model object
     # @!attribute [r] local_tools
     #   @return [Array] the locally defined tools for this robot
     # @!attribute [r] mcp_clients
@@ -79,7 +60,15 @@ module RobotLab
     #   @return [Array<Tool>] tools discovered from MCP servers
     # @!attribute [r] memory
     #   @return [Memory] the robot's inherent memory (used when standalone, not in network)
-    attr_reader :name, :description, :template, :system_prompt, :model, :local_tools, :mcp_clients, :mcp_tools, :memory
+    # @!attribute [rw] input
+    #   @return [IO] input stream for user interaction (default: $stdin)
+    # @!attribute [rw] output
+    #   @return [IO] output stream for user interaction (default: $stdout)
+    attr_accessor :input, :output
+
+    attr_reader :name, :description, :template, :system_prompt,
+                :local_tools, :mcp_clients, :mcp_tools, :memory,
+                :bus, :outbox
 
     # @!attribute [r] mcp_config
     #   @return [Symbol, Array] build-time MCP configuration (raw, unresolved)
@@ -90,37 +79,26 @@ module RobotLab
     # Creates a new Robot instance.
     #
     # @param name [String] the unique identifier for the robot
-    # @param template [Symbol, nil] the ERB template for the robot's prompt
-    # @param system_prompt [String, nil] inline system prompt (can be used alone or with template)
-    # @param context [Hash, Proc] variables to pass to the template at build time
-    # @param description [String, nil] an optional description of the robot's purpose
-    # @param local_tools [Array] tools defined locally for this robot
-    # @param model [String, nil] the LLM model to use (defaults to config.default_model)
+    # @param template [Symbol, nil] the prompt_manager template
+    # @param system_prompt [String, nil] inline system prompt
+    # @param context [Hash, Proc] variables to pass to the template
+    # @param description [String, nil] optional description
+    # @param local_tools [Array] tools defined locally
+    # @param model [String, nil] the LLM model to use
     # @param mcp_servers [Array] legacy parameter for MCP server configurations
-    # @param mcp [Symbol, Array] hierarchical MCP config (:none, :inherit, or array of servers)
-    # @param tools [Symbol, Array] hierarchical tools config (:none, :inherit, or array of tool names)
+    # @param mcp [Symbol, Array] hierarchical MCP config
+    # @param tools [Symbol, Array] hierarchical tools config
     # @param on_tool_call [Proc, nil] callback invoked when a tool is called
     # @param on_tool_result [Proc, nil] callback invoked when a tool returns a result
-    # @param enable_cache [Boolean] whether to enable semantic caching (default: true)
-    #
-    # @example Basic robot with template
-    #   Robot.new(name: "helper", template: :helper)
-    #
-    # @example Robot with inline system prompt
-    #   Robot.new(name: "bot", system_prompt: "You are helpful.")
-    #
-    # @example Robot with template and additional system prompt
-    #   Robot.new(name: "bot", template: :base, system_prompt: "Extra context here.")
-    #
-    # @example Robot with tools and callbacks
-    #   Robot.new(
-    #     name: "support",
-    #     template: :support,
-    #     local_tools: [OrderLookup],
-    #     on_tool_call: ->(call) { puts "Calling #{call.name}" }
-    #   )
-    #
-    # @raise [ArgumentError] if neither template nor system_prompt is provided
+    # @param enable_cache [Boolean] whether to enable semantic caching
+    # @param bus [TypedBus::MessageBus, nil] optional message bus for inter-robot communication
+    # @param temperature [Float, nil] controls randomness
+    # @param top_p [Float, nil] nucleus sampling threshold
+    # @param top_k [Integer, nil] top-k sampling
+    # @param max_tokens [Integer, nil] maximum tokens in response
+    # @param presence_penalty [Float, nil] penalize based on presence
+    # @param frequency_penalty [Float, nil] penalize based on frequency
+    # @param stop [String, Array, nil] stop sequences
     def initialize(
       name:,
       template: nil,
@@ -134,24 +112,27 @@ module RobotLab
       tools: :none,
       on_tool_call: nil,
       on_tool_result: nil,
-      enable_cache: true
+      enable_cache: true,
+      bus: nil,
+      temperature: nil,
+      top_p: nil,
+      top_k: nil,
+      max_tokens: nil,
+      presence_penalty: nil,
+      frequency_penalty: nil,
+      stop: nil
     )
-      unless template || system_prompt
-        raise ArgumentError, "Must provide either template or system_prompt"
-      end
-
       @name = name.to_s
+      @name_from_constructor = (name.to_s != "robot")
       @template = template
       @system_prompt = system_prompt
       @build_context = context
       @description = description
       @local_tools = Array(local_tools)
-      @model = model || RobotLab.configuration.default_model
       @on_tool_call = on_tool_call
       @on_tool_result = on_tool_result
 
       # Store raw config values for hierarchical resolution
-      # mcp_servers is legacy parameter, mcp is the new hierarchical one
       @mcp_config = mcp_servers.any? ? mcp_servers : mcp
       @tools_config = tools
 
@@ -160,45 +141,97 @@ module RobotLab
       @mcp_tools = []
       @mcp_initialized = false
 
+      # Bus state (optional inter-robot communication)
+      @bus = bus
+      @message_counter = 0
+      @outbox = {}
+      @message_handler = nil
+
       # Inherent memory (used when standalone, not in a network)
       @memory = Memory.new(enable_cache: enable_cache)
+
+      # Ensure config is loaded (triggers PM setup, RubyLLM config, etc.)
+      config = RobotLab.config
+
+      # Build chat kwargs for Agent's super
+      resolved_model = model || config.ruby_llm.model
+      chat_kwargs = { model: resolved_model }
+
+      # Create the persistent chat via Agent's initialize
+      super(chat: nil, **chat_kwargs)
+
+      # Apply template first (includes front matter config like model, temperature)
+      # then constructor params override — constructor is more specific than template.
+      apply_template_to_chat(context) if @template
+      @chat.with_instructions(@system_prompt) if @system_prompt
+
+      # Constructor params override template front matter
+      apply_chat_option(:with_temperature, temperature)
+      apply_chat_option(:with_top_p, top_p)
+      apply_chat_option(:with_top_k, top_k)
+      apply_chat_option(:with_max_tokens, max_tokens)
+      apply_chat_option(:with_presence_penalty, presence_penalty)
+      apply_chat_option(:with_frequency_penalty, frequency_penalty)
+      apply_chat_option(:with_stop, stop)
+
+      # Apply callbacks
+      @chat.on_tool_call(&@on_tool_call) if @on_tool_call
+      @chat.on_tool_result(&@on_tool_result) if @on_tool_result
+
+      # Set up bus channel if a bus was provided
+      setup_bus_channel if @bus
     end
 
-    # Returns the robot's local tools (alias for local_tools).
+
+    # Returns the model identifier
     #
-    # Provided for backward compatibility with earlier API versions.
+    # @return [String, nil] the LLM model ID string
+    def model
+      return nil unless @chat.respond_to?(:model)
+
+      m = @chat.model
+      m.respond_to?(:id) ? m.id : m.to_s
+    end
+
+    # Forward with_* methods to the persistent chat, returning self for chaining
+    %i[
+      with_model with_temperature with_top_p with_top_k with_max_tokens
+      with_presence_penalty with_frequency_penalty with_stop
+      with_instructions with_tool with_tools with_params
+      with_headers with_schema with_context with_thinking
+    ].each do |method|
+      define_method(method) do |*args, **kwargs, &block|
+        @chat.public_send(method, *args, **kwargs, &block)
+        self
+      end
+    end
+
+    # Apply a prompt_manager template to the robot's chat
     #
-    # @return [Array] the locally defined tools
-    def tools
-      @local_tools
+    # @param template_id [Symbol, String] the template identifier
+    # @param context [Hash] variables to pass to the template
+    # @return [self]
+    def with_template(template_id, **context)
+      @template = template_id.to_sym
+      @build_context = context
+      apply_template_to_chat(context)
+      self
     end
 
-    # Run the robot with the given context
+
+    # Send a message and get a response, with Robot's extended capabilities
     #
-    # @param network [NetworkRun, nil] Network context if running in network (legacy)
-    # @param network_memory [Memory, nil] Shared network memory (preferred)
-    # @param memory [Memory, Hash, nil] Runtime memory to merge
-    # @param mcp [Symbol, Array, nil] Runtime MCP override (:inherit, :none, nil, [], or array of servers)
-    # @param tools [Symbol, Array, nil] Runtime tools override (:inherit, :none, nil, [], or array of tool names)
-    # @param run_context [Hash] Context for rendering user template
+    # @param message [String] the user message
+    # @param network [NetworkRun, nil] network context (legacy)
+    # @param network_memory [Memory, nil] shared network memory
+    # @param memory [Memory, Hash, nil] runtime memory to merge
+    # @param mcp [Symbol, Array, nil] runtime MCP override
+    # @param tools [Symbol, Array, nil] runtime tools override
     # @return [RobotResult]
-    #
-    # @example Standalone robot with inherent memory
-    #   robot.run(message: "My name is Alice")
-    #   robot.run(message: "What's my name?")  # Memory persists
-    #
-    # @example Runtime memory injection
-    #   robot.run(message: "Hello", memory: { user_id: 123, session: "abc" })
-    #
-    # @example With network shared memory
-    #   robot.run(message: "Analyze this", network_memory: network.memory)
-    #
-    def run(network: nil, network_memory: nil, memory: nil, mcp: :none, tools: :none, **run_context)
-      # Determine which memory to use (priority order):
-      # 1. Explicit network_memory parameter
-      # 2. Network object's memory (legacy)
-      # 3. Robot's inherent memory
-      run_memory = network_memory || network&.memory || @memory
+    def run(message = nil, network: nil, network_memory: nil, memory: nil, mcp: :none, tools: :none,
+            **kwargs)
+      # Determine which memory to use
+      run_memory = resolve_active_memory(network: network, network_memory: network_memory)
 
       # Merge runtime memory if provided
       case memory
@@ -220,84 +253,219 @@ module RobotLab
         # Initialize or update MCP clients based on resolved config
         ensure_mcp_clients(resolved_mcp)
 
-        # Merge build context + run context
-        full_context = resolve_context(@build_context, network: network)
-                         .merge(run_context)
+        # Apply filtered tools to the persistent chat
+        filtered = filtered_tools(resolved_tools)
+        @chat.with_tools(*filtered) if filtered.any?
 
-        # Build chat with template, filtered tools, and semantic cache
-        chat = build_chat(full_context, allowed_tools: resolved_tools, memory: run_memory)
+        # Re-render template with run-time context merged into build-time context.
+        # Template parameters (e.g. customer: null) may require values that are
+        # only available at run time — the robot gathers them before rendering.
+        run_context = kwargs.except(:with)
+        rerender_template(run_context) if @template && run_context.any?
 
-        # Execute and return result
-        response = chat.complete
+        # Delegate to Agent's ask (which calls @chat.ask)
+        ask_kwargs = kwargs.slice(:with)
+        response = ask(message, **ask_kwargs)
 
         build_result(response, run_memory)
       ensure
-        # Restore previous writer
         run_memory.current_writer = previous_writer
       end
     end
 
-    # SimpleFlow step interface
+
+    # Reconfigure the robot for a new context
     #
-    # Allows Robot to be used directly as a step in a SimpleFlow::Pipeline.
-    # The robot receives a SimpleFlow::Result, executes, and returns a new
-    # SimpleFlow::Result with the robot's output.
+    # @param template [Symbol, nil] new template to apply
+    # @param context [Hash, nil] new context for the template
+    # @param system_prompt [String, nil] new system prompt
+    # @param model [String, nil] new model
+    # @param temperature [Float, nil] new temperature
+    # @return [self]
+    def update(template: nil, context: nil, system_prompt: nil, model: nil, temperature: nil, **kwargs)
+      if template
+        @template = template
+        ctx = context || @build_context
+        apply_template_to_chat(ctx)
+      end
+
+      @chat.with_instructions(system_prompt) if system_prompt
+      @chat.with_model(model) if model
+      apply_chat_option(:with_temperature, temperature)
+
+      kwargs.each do |key, value|
+        method = :"with_#{key}"
+        @chat.public_send(method, value) if value && @chat.respond_to?(method)
+      end
+
+      self
+    end
+
+
+    # SimpleFlow step interface
     #
     # @param result [SimpleFlow::Result] incoming result from previous step
     # @return [SimpleFlow::Result] result with robot output
-    #
-    # @example Using a robot as a pipeline step
-    #   pipeline = SimpleFlow::Pipeline.new do
-    #     step :classifier, classifier_robot, depends_on: :none
-    #     step :billing, billing_robot, depends_on: :optional
-    #   end
-    #
     def call(result)
-      robot_result = run(**extract_run_context(result))
+      run_context = extract_run_context(result)
+
+      # Extract the message from run context
+      message = run_context.delete(:message)
+
+      robot_result = run(message, **run_context)
 
       result
         .with_context(@name.to_sym, robot_result)
         .continue(robot_result)
     end
 
+
     # Reset the robot's inherent memory
     #
-    # NOTE: This only affects the robot's standalone memory. When a robot runs
-    # as part of a network, it uses the network's shared memory instead.
-    # To reset memory for network execution, use `network.reset_memory`.
-    #
     # @return [self]
+    def reset_memory
+      @memory.reset
+      self
+    end
+
+
+    # Send a message to another robot via the bus.
     #
-    # @example Standalone robot
-    #   robot.run(message: "My name is Alice")
-    #   robot.reset_memory  # Clears the conversation
-    #   robot.run(message: "What's my name?")  # Won't remember Alice
+    # @param to [String, Symbol] target robot's channel name
+    # @param content [String, Hash] message payload
+    # @return [RobotMessage] the sent message
+    # @raise [BusError] if no bus is configured
+    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: [] }
+      publish_to_bus(to.to_sym, message)
+      message
+    end
+
+
+    # Send a reply to a specific message via the bus.
     #
-    # @example Robot in network (reset_memory has no effect on network runs)
-    #   network.run(message: "Hello")
-    #   robot.reset_memory  # Does NOT affect network memory
-    #   network.run(message: "Hi")  # Network memory still intact
-    #   network.reset_memory  # Use this to reset network memory
+    # @param to [String, Symbol] target robot's channel name
+    # @param content [String, Hash] reply payload
+    # @param in_reply_to [String] composite key of the message being replied to
+    # @return [RobotMessage] the reply message
+    # @raise [BusError] if no bus is configured
+    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)
+      publish_to_bus(to.to_sym, reply)
+      reply
+    end
+
+
+    # Convenience method to reply to a RobotMessage.
     #
-    def reset_memory
-      @memory.reset
+    # @param message [RobotMessage] the message to reply to
+    # @param content [String, Hash] reply payload
+    # @return [RobotMessage] the reply message
+    def reply(message, content)
+      send_reply(to: message.from.to_sym, content: content, in_reply_to: message.key)
+    end
+
+
+    # Register a custom handler for incoming bus messages.
+    #
+    # Block arity controls delivery handling:
+    # - 1 argument `|message|`: auto-acks before calling, auto-nacks on exception
+    # - 2 arguments `|delivery, message|`: manual mode, you call ack!/nack!
+    #
+    # @yield [message] or [delivery, message]
+    # @return [self]
+    def on_message(&block)
+      @message_handler = block
       self
     end
 
-    # Disconnect all MCP clients
+
+    # Spawn a new robot on a shared bus.
+    #
+    # Creates a new Robot instance that shares this robot's bus,
+    # allowing it to immediately send and receive messages with
+    # all other robots on the bus. If no bus exists yet, one is
+    # created automatically and the parent robot is connected to it.
+    #
+    # @param name [String] unique name for the new robot
+    # @param system_prompt [String, nil] inline system prompt
+    # @param template [Symbol, nil] prompt_manager template
+    # @param local_tools [Array] tools for the new robot
+    # @param options [Hash] additional options passed to RobotLab.build
+    # @return [Robot] the newly created robot
+    #
+    # @example Spawn from a bus-less robot (bus and name created automatically)
+    #   bot  = RobotLab.build
+    #   bot2 = bot.spawn(system_prompt: "You are helpful.")
+    #
+    # @example Spawn a specialist from a message handler
+    #   on_message do |message|
+    #     specialist = spawn(
+    #       name: "fact_checker",
+    #       system_prompt: "You verify factual claims. Be concise."
+    #     )
+    #     specialist.send_message(to: name.to_sym, content: specialist.run(message.content).last_text_content)
+    #   end
+    #
+    def spawn(name: "robot", system_prompt: nil, template: nil, local_tools: [], **options)
+      ensure_bus
+
+      RobotLab.build(
+        name: name,
+        system_prompt: system_prompt,
+        template: template,
+        local_tools: local_tools,
+        bus: @bus,
+        **options
+      )
+    end
+
+
+    # Connect this robot to a message bus.
     #
-    # Call this method when done using the robot to clean up MCP connections.
+    # If a bus is provided, the robot joins it. If no bus is provided
+    # and the robot doesn't already have one, a new bus is created.
+    # No-op if the robot is already on the given bus.
     #
+    # @param bus [TypedBus::MessageBus, nil] bus to join (creates one if nil)
     # @return [self]
     #
+    # @example Join an existing bus
+    #   bot = RobotLab.build.with_bus(some_bus)
+    #
+    # @example Create a bus on demand
+    #   bot = RobotLab.build.with_bus
+    #
+    def with_bus(bus = nil)
+      return self if bus && @bus == bus
+
+      teardown_bus_channel if @bus
+      @bus = bus || @bus || TypedBus::MessageBus.new
+      setup_bus_channel
+      self
+    end
+
+
+    # Disconnect all MCP clients and bus channel.
+    #
+    # @return [self]
     def disconnect
       @mcp_clients.each_value(&:disconnect)
+      teardown_bus_channel if @bus
       self
     end
 
-    # Converts the robot to a hash representation.
+
+    # Converts the robot to a hash representation
     #
-    # @return [Hash] a hash containing the robot's configuration
+    # @return [Hash]
     def to_h
       {
         name: name,
@@ -309,24 +477,131 @@ module RobotLab
         mcp_config: @mcp_config,
         tools_config: @tools_config,
         mcp_servers: @mcp_clients.keys,
-        model: model.respond_to?(:model_id) ? model.model_id : model
+        model: model,
+        bus: @bus ? true : nil
       }.compact
     end
 
     private
 
+    # Apply a chat option if the value is non-nil
+    def apply_chat_option(method, value)
+      @chat.public_send(method, value) if value
+    end
+
+
+    # Apply a prompt_manager template to the persistent chat.
+    # If required parameters are missing, applies front matter config but
+    # defers rendering until run time when all values are available.
+    def apply_template_to_chat(context)
+      parsed = PM.parse(@template)
+
+      # Extract extra config from front matter (name, description, tools, mcp)
+      apply_front_matter_extras(parsed.metadata)
+
+      # Extract and apply LLM config to the chat (model, temperature, etc.)
+      apply_front_matter_config(parsed.metadata)
+
+      # Resolve context (could be a Proc)
+      resolved_ctx = resolve_context(context, network: nil)
+
+      # Render the template body with context
+      begin
+        rendered = parsed.to_s(**resolved_ctx)
+        @chat.with_instructions(rendered)
+      rescue ArgumentError => e
+        raise unless e.message.start_with?("Missing required parameters:")
+
+        # Required parameters not yet available; template will be
+        # fully rendered at run time via rerender_template.
+      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)
+      merged = (@build_context || {}).merge(run_context)
+      parsed = PM.parse(@template)
+      resolved_ctx = resolve_context(merged, network: nil)
+      rendered = parsed.to_s(**resolved_ctx)
+      @chat.with_instructions(rendered)
+    end
+
+
+    # Extract whitelisted config from front matter and apply to chat
+    def apply_front_matter_config(metadata)
+      FRONT_MATTER_CONFIG_KEYS.each do |key|
+        value = metadata.respond_to?(key) ? metadata.send(key) : nil
+        next unless value
+
+        method = :"with_#{key}"
+        @chat.public_send(method, value) if @chat.respond_to?(method)
+      end
+
+      # Handle model specially (may need with_model)
+      return unless metadata.respond_to?(:model) && metadata.model
+
+      @chat.with_model(metadata.model)
+
+    end
+
+
+    # Extract identity and capability keys from front matter metadata.
+    # Constructor-provided values take precedence over frontmatter.
+    def apply_front_matter_extras(metadata)
+      if metadata.respond_to?(:robot_name) && metadata.robot_name && !@name_from_constructor
+        @name = metadata.robot_name.to_s
+      end
+
+      if metadata.respond_to?(:description) && metadata.description && @description.nil?
+        @description = metadata.description.to_s
+      end
+
+      if metadata.respond_to?(:tools) && metadata.tools.is_a?(Array) && @local_tools.empty?
+        @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
+    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.
+    def resolve_frontmatter_tools(tool_names)
+      tool_names.filter_map do |name|
+        case name
+        when String
+          begin
+            const = Object.const_get(name)
+            const.is_a?(Class) && const < RubyLLM::Tool ? const.new : const
+          rescue NameError
+            RobotLab.config.logger.warn("Robot '#{@name}': tool '#{name}' not found, skipping")
+            nil
+          end
+        when Class
+          name.new
+        else
+          name
+        end
+      end
+    end
+
+
+    # Determine which memory to use
+    def resolve_active_memory(network: nil, network_memory: nil)
+      network_memory || network&.memory || @memory
+    end
+
+
     # Extract run context from SimpleFlow::Result
-    #
-    # Merges original run params (preserved in context) with current value.
-    # Extracts special parameters (mcp, tools, memory, network_memory) for Robot#run.
-    #
-    # @param result [SimpleFlow::Result] the incoming result
-    # @return [Hash] context for run method including mcp/tools config
-    #
     def extract_run_context(result)
       run_params = result.context[:run_params] || {}
 
-      # Extract robot-specific params that should be passed to run()
+      # Extract robot-specific params
       mcp = run_params.delete(:mcp) || :none
       tools = run_params.delete(:tools) || :none
       memory = run_params.delete(:memory)
@@ -347,7 +622,7 @@ module RobotLab
                  base.merge(message: result.value.to_s)
                end
 
-      # Add back the special params for run()
+      # Add back the special params
       merged[:mcp] = mcp
       merged[:tools] = tools
       merged[:memory] = memory if memory
@@ -356,6 +631,7 @@ module RobotLab
       merged
     end
 
+
     def resolve_context(context, network:)
       case context
       when Proc then context.call(network: network)
@@ -364,41 +640,10 @@ module RobotLab
       end
     end
 
-    def build_chat(context, allowed_tools:, memory:)
-      model_id = @model.respond_to?(:model_id) ? @model.model_id : @model.to_s
-
-      chat = RubyLLM.chat(model: model_id)
-
-      # Apply template and/or system_prompt
-      # - Template only: use with_template
-      # - system_prompt only: use with_instructions
-      # - Both: use with_template, then append with_instructions
-      if @template
-        chat = chat.with_template(@template, **context)
-        chat = chat.with_instructions(@system_prompt) if @system_prompt
-      else
-        chat = chat.with_instructions(@system_prompt)
-      end
-
-      # Get filtered tools based on whitelist
-      filtered = filtered_tools(allowed_tools)
-      chat = chat.with_tools(*filtered) if filtered.any?
-
-      # Add callbacks if provided
-      chat = chat.on_tool_call(&@on_tool_call) if @on_tool_call
-      chat = chat.on_tool_result(&@on_tool_result) if @on_tool_result
-
-      # NOTE: Semantic cache wrapping is disabled because the SemanticCache::Middleware
-      # only supports `ask` method, not `complete`. The caching feature needs to be
-      # re-designed to use the `ask` interface or the `fetch` pattern.
-      # See: https://github.com/ruby-llm/ruby_llm-semantic_cache
-
-      chat
-    end
 
     def build_result(response, _memory)
       output = if response.respond_to?(:content) && response.content
-                 [TextMessage.new(role: "assistant", content: response.content)]
+                 [TextMessage.new(role: 'assistant', content: response.content)]
                else
                  []
                end
@@ -413,6 +658,7 @@ module RobotLab
       )
     end
 
+
     def normalize_tool_calls(tool_calls)
       return [] unless tool_calls
 
@@ -420,7 +666,7 @@ module RobotLab
         if tc.is_a?(Hash)
           ToolResultMessage.new(
             tool: tc,
-            content: tc[:result] || tc["result"]
+            content: tc[:result] || tc['result']
           )
         else
           tc
@@ -428,57 +674,32 @@ module RobotLab
       end
     end
 
+
     # Resolve MCP hierarchy: runtime -> robot build -> network -> config
-    #
-    # @param runtime_value [Symbol, Array, nil] Runtime MCP override
-    # @param network [NetworkRun, nil] Network context
-    # @return [Array] Resolved MCP server configurations
-    #
     def resolve_mcp_hierarchy(runtime_value, network:)
-      # Get parent value (network or config)
-      parent_value = network&.network&.mcp || RobotLab.configuration.mcp
-
-      # Resolve robot build config against parent
+      parent_value = network&.network&.mcp || RobotLab.config.mcp
       build_resolved = ToolConfig.resolve_mcp(@mcp_config, parent_value: parent_value)
-
-      # Resolve runtime against build
       ToolConfig.resolve_mcp(runtime_value, parent_value: build_resolved)
     end
 
+
     # Resolve tools hierarchy: runtime -> robot build -> network -> config
-    #
-    # @param runtime_value [Symbol, Array, nil] Runtime tools override
-    # @param network [NetworkRun, nil] Network context
-    # @return [Array<String>] Resolved tool names whitelist
-    #
     def resolve_tools_hierarchy(runtime_value, network:)
-      # Get parent value (network or config)
-      parent_value = network&.network&.tools || RobotLab.configuration.tools
-
-      # Resolve robot build config against parent
+      parent_value = network&.network&.tools || RobotLab.config.tools
       build_resolved = ToolConfig.resolve_tools(@tools_config, parent_value: parent_value)
-
-      # Resolve runtime against build
       ToolConfig.resolve_tools(runtime_value, parent_value: build_resolved)
     end
 
+
     # Ensure MCP clients are initialized for the given server configs
-    #
-    # @param mcp_servers [Array] MCP server configurations
-    #
     def ensure_mcp_clients(mcp_servers)
       return if mcp_servers.empty?
 
-      # Get server names from configs
       needed_servers = mcp_servers.map { |s| s.is_a?(Hash) ? s[:name] : s.to_s }.compact
-
-      # Skip if already initialized with same servers
       return if @mcp_initialized && (@mcp_clients.keys.sort == needed_servers.sort)
 
-      # Disconnect existing clients if config changed
       disconnect if @mcp_initialized
 
-      # Initialize new clients
       @mcp_clients = {}
       @mcp_tools = []
 
@@ -489,10 +710,7 @@ module RobotLab
       @mcp_initialized = true
     end
 
-    # Initialize a single MCP client
-    #
-    # @param server_config [Hash] MCP server configuration
-    #
+
     def init_mcp_client(server_config)
       client = MCP::Client.new(server_config)
       client.connect
@@ -502,17 +720,13 @@ module RobotLab
         @mcp_clients[server_name] = client
         discover_mcp_tools(client, server_name)
       else
-        RobotLab.configuration.logger.warn(
+        RobotLab.config.logger.warn(
           "Robot '#{@name}' failed to connect to MCP server: #{server_config[:name] || server_config}"
         )
       end
     end
 
-    # Discover tools from an MCP server and add them to @mcp_tools
-    #
-    # @param client [MCP::Client] Connected MCP client
-    # @param server_name [String] Name of the MCP server
-    #
+
     def discover_mcp_tools(client, server_name)
       tools = client.list_tools
 
@@ -520,41 +734,101 @@ module RobotLab
         tool_name = tool_def[:name]
         mcp_client = client
 
-        # Create a Tool that delegates to the MCP client
-        tool = Tool.new(
+        tool = Tool.create(
           name: tool_name,
           description: tool_def[:description],
           parameters: tool_def[:inputSchema],
-          mcp: server_name,
-          handler: ->(input, **_opts) { mcp_client.call_tool(tool_name, input) }
-        )
+          mcp: server_name
+        ) { |args| mcp_client.call_tool(tool_name, args) }
 
         @mcp_tools << tool
       end
 
-      RobotLab.configuration.logger.info(
+      RobotLab.config.logger.info(
         "Robot '#{@name}' discovered #{tools.size} tools from MCP server '#{server_name}'"
       )
     end
 
-    # Get all tools (local + MCP)
-    #
-    # @return [Array] Combined array of local and MCP tools
-    #
+
     def all_tools
       @local_tools + @mcp_tools
     end
 
-    # Filter tools based on allowed tool names whitelist
-    #
-    # @param allowed_names [Array<String>] Whitelist of tool names (empty = all allowed)
-    # @return [Array] Filtered tools
-    #
+
     def filtered_tools(allowed_names)
       available = all_tools
       return available if allowed_names.empty?
 
       ToolConfig.filter_tools(available, allowed_names: allowed_names)
     end
+
+
+    # Create a bus if one doesn't exist and connect this robot to it
+    def ensure_bus
+      with_bus unless @bus
+    end
+
+
+    # Create a typed channel on the bus and subscribe to it
+    def setup_bus_channel
+      channel_name = @name.to_sym
+      @bus.add_channel(channel_name, type: RobotMessage) unless @bus.channel?(channel_name)
+      @bus_subscriber_id = @bus.subscribe(channel_name) { |delivery| handle_incoming_delivery(delivery) }
+    end
+
+
+    # Unsubscribe from the bus channel
+    def teardown_bus_channel
+      channel_name = @name.to_sym
+      @bus.unsubscribe(channel_name, @bus_subscriber_id) if @bus_subscriber_id
+      @bus_subscriber_id = nil
+    end
+
+
+    # Dispatch incoming bus delivery to handler.
+    # Auto-ack when the handler takes 1 arg (message only);
+    # manual ack/nack when the handler takes 2 args (delivery, message).
+    def handle_incoming_delivery(delivery)
+      message = delivery.message
+
+      # 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
+      else
+        handle_message_via_llm(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?
+        @bus.publish(channel_name, message)
+      else
+        Async { @bus.publish(channel_name, message) }
+      end
+    end
   end
 end