robot_lab 0.2.1 → 0.2.7

data/lib/robot_lab/robot/budget.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module RobotLab
+  class Robot < RubyLLM::Agent
+    # Token/cost budget enforcement for a single Robot, backed by a
+    # RobotLab::Budget::Ledger.
+    #
+    # Two layers of enforcement:
+    # - reserve_budget!/reconcile_budget! wrap each LLM call. reserve_budget!
+    #   raises BudgetExceeded up front when a *prior* call already pushed
+    #   usage over budget, so a robot with an exhausted budget refuses
+    #   further calls instead of spending on them.
+    # - enforce_token_budget!/enforce_cost_budget! run after the call
+    #   completes and raise InferenceError when *this* call's actual usage
+    #   pushed cumulative usage over budget — unavoidable for the call that
+    #   causes the overage, since token/cost totals aren't known until the
+    #   response comes back.
+    module Budget
+      private
+
+      # @return [RobotLab::Budget::Ledger, nil] nil when neither token_budget
+      #   nor cost_budget is configured
+      def build_budget_ledger
+        limits = { tokens: @config.token_budget, cost: @config.cost_budget }.compact
+        return nil if limits.empty?
+
+        RobotLab::Budget::Ledger.new(limits: limits)
+      end
+
+      def enforce_token_budget!
+        budget = @config.token_budget
+        return unless budget && @total_input_tokens + @total_output_tokens > budget
+
+        raise InferenceError,
+              "Token budget exceeded: #{@total_input_tokens + @total_output_tokens} tokens used, budget is #{budget}"
+      end
+
+      def enforce_cost_budget!
+        budget = @config.cost_budget
+        return unless budget && @budget_ledger
+
+        consumed = @budget_ledger.consumed[:cost]
+        return unless consumed > budget
+
+        raise InferenceError,
+              format("Cost budget exceeded: $%<consumed>.6f used, budget is $%<budget>.6f",
+                     consumed: consumed, budget: budget)
+      end
+
+      # Reserves whatever remains of each configured budget dimension
+      # before attempting the LLM call.
+      #
+      # @return [Hash{Symbol=>Numeric}] the amount reserved per dimension, to pass to reconcile_budget!
+      # @raise [RobotLab::BudgetExceeded] if a dimension is already exhausted
+      def reserve_budget!
+        return {} unless @budget_ledger
+
+        @budget_ledger.limits.each_key.with_object({}) do |dimension, reservation|
+          amount = @budget_ledger.remaining(dimension)
+          @budget_ledger.reserve!(dimension, amount)
+          reservation[dimension] = amount
+        end
+      end
+
+      # Replaces a reservation from reserve_budget! with the actual usage
+      # from this call.
+      #
+      # @param reservation [Hash{Symbol=>Numeric}] the value returned by reserve_budget!
+      # @param response [Object] the raw LLM response, used to extract actual cost
+      # @param result [RobotResult] the built result, used to extract actual tokens
+      def reconcile_budget!(reservation, response:, result:)
+        return unless reservation&.any?
+
+        actual = { tokens: result.input_tokens + result.output_tokens, cost: extract_cost(response) }
+        reservation.each_pair { |dimension, amount| @budget_ledger.reconcile!(dimension, amount, actual[dimension] || 0) }
+      end
+
+      # @param response [Object] the raw LLM response
+      # @return [Float] the response's total cost, or 0.0 when unavailable (no pricing data)
+      def extract_cost(response)
+        return 0.0 unless response.respond_to?(:cost)
+
+        response.cost.total.to_f
+      rescue StandardError
+        0.0
+      end
+    end
+  end
+end

data/lib/robot_lab/robot/bus_messaging.rb

@@ -12,9 +12,15 @@ module RobotLab
     # == Delivery Serialization
     #
     # TypedBus delivers messages in concurrent Async fibers. Robots
-    # enqueue deliveries into a BusPoller rather than handling them
-    # inline. The BusPoller drains each group's queue sequentially on
-    # a dedicated OS thread, so robot.run() calls never interleave.
+    # enqueue deliveries into a shared BusPoller rather than dispatching
+    # them straight to the handler. Despite the name, BusPoller runs no
+    # background thread: `enqueue` processes the delivery inline in the
+    # caller's own execution context (Async fiber or OS thread) when the
+    # robot is idle, and otherwise queues it behind the delivery already
+    # in flight and drains it once that one returns. A mutex therefore
+    # serializes deliveries per robot, so a robot's run() calls never
+    # interleave — but nothing makes progress while the calling fiber is
+    # parked.
     #
     # Owns:    @bus, @bus_poller, @private_bus_poller, @bus_poller_group, @bus_subscriber_id, @message_counter, @outbox, @message_handler
     # Reads:   @name
@@ -29,9 +35,15 @@ 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
@@ -46,8 +58,10 @@ 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
@@ -65,6 +79,38 @@ 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 inline in the caller's execution context (BusPoller has
+      # no drain thread), and deliveries to this member are serialized, so a long
+      # turn blocks both the sender and 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.
       #
       # Creates a new Robot instance that shares this robot's bus,
@@ -88,10 +134,24 @@ module RobotLab
           template: template,
           local_tools: local_tools,
           bus: @bus,
+          **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.
       #
       # If a bus is provided, the robot joins it. If no bus is provided
@@ -112,8 +172,9 @@ module RobotLab
 
       # Assign a shared BusPoller from a Network.
       #
-      # Stops any private poller this robot auto-created, then adopts
-      # the network's shared poller for the given group.
+      # Drops any private poller this robot auto-created, then adopts
+      # the network's shared poller for the given group. Called by
+      # Network#task; groups are informational labels only.
       #
       # @param poller [BusPoller] the network's shared poller
       # @param group  [Symbol]    poller group for this robot (default: :default)
@@ -159,21 +220,21 @@ 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).
+      # Process a single delivery (called by BusPoller during its inline drain).
       def process_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
+        correlate_reply(message) if message.reply?
 
         if @message_handler.arity == 1
           delivery.ack!
@@ -186,6 +247,17 @@ module RobotLab
         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
+
+          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/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

@@ -12,18 +12,24 @@ module RobotLab
 
       # 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.
       def ensure_mcp_clients(mcp_servers)

data/lib/robot_lab/robot/template_rendering.rb

@@ -45,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,6 +64,10 @@ module RobotLab
 
       # 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.
+      #
+      # Re-rendering replaces the system message, so the inline system_prompt must be
+      # re-appended here exactly as apply_system_prompt does at construction --
+      # otherwise it would be silently dropped on any run that supplies context.
       def rerender_template(run_context)
         merged = (@build_context || {}).merge(run_context)
         resolved_ctx = resolve_context(merged, network: nil)
@@ -81,15 +85,24 @@ module RobotLab
             bodies << body if body
           end
 
-          combined = bodies.join("\n\n")
-          @chat.with_instructions(combined)
+          @chat.with_instructions(with_system_prompt_appended(bodies.join("\n\n")))
         else
           parsed = PM.parse(@template)
           rendered = parsed.to_s(**resolved_ctx)
-          @chat.with_instructions(rendered)
+          @chat.with_instructions(with_system_prompt_appended(rendered))
         end
       end
 
+      # Append the inline system_prompt to freshly rendered template text.
+      #
+      # @param rendered [String] newly rendered template body
+      # @return [String] rendered text with system_prompt appended, if one is set
+      def with_system_prompt_appended(rendered)
+        return rendered unless @system_prompt
+
+        [rendered, @system_prompt].reject { |s| s.to_s.empty? }.join("\n\n")
+      end
+
       # Orchestrate skill expansion and template application.
       #
       # @param skill_ids [Array<Symbol>] skill IDs from constructor + front matter
@@ -142,7 +155,7 @@ module RobotLab
         apply_accumulated_extras(extras)
 
         effective = accumulated_config.merge(@config)
-        effective.apply_to(@chat)
+        effective.apply_to(@chat, provider: @provider, assume_model_exists: !@provider.nil?)
 
         combined = bodies.join("\n\n")
         @chat.with_instructions(combined) unless combined.empty?