robot_lab 0.1.0 → 0.2.6

data/lib/robot_lab/robot.rb

@@ -4,6 +4,9 @@ require_relative 'robot/template_rendering'
 require_relative 'robot/mcp_management'
 require_relative 'robot/bus_messaging'
 require_relative 'robot/history_search'
+require_relative 'robot/agent_skill_matching'
+require_relative 'robot/budget'
+require_relative 'robot/hooking'
 
 module RobotLab
   # LLM-powered robot built on RubyLLM::Agent
@@ -43,6 +46,15 @@ module RobotLab
     include Robot::MCPManagement
     include Robot::BusMessaging
     include Robot::HistorySearch
+    include Robot::Budget
+    include Robot::Hooking
+    include Runnable
+    prepend Robot::AgentSkillMatching
+
+    # Default ceiling on tools handed to the provider per turn. OpenAI and
+    # Anthropic both reject tool arrays longer than 128. Override per robot via
+    # RunConfig#max_tools.
+    DEFAULT_MAX_TOOLS = 128
 
     # @!attribute [r] name
     #   @return [String] the unique identifier for the robot
@@ -68,8 +80,9 @@ module RobotLab
 
     attr_reader :name, :description, :template, :system_prompt,
                 :local_tools, :mcp_clients, :mcp_tools, :memory,
-                :bus, :outbox, :config, :skills, :provider,
-                :total_input_tokens, :total_output_tokens, :learnings
+                :bus, :outbox, :config, :skills, :provider, :hooks,
+                :total_input_tokens, :total_output_tokens, :learnings,
+                :budget_ledger
 
     # @!attribute [r] mcp_config
     #   @return [Symbol, Array] build-time MCP configuration (raw, unresolved)
@@ -77,6 +90,45 @@ module RobotLab
     #   @return [Symbol, Array] build-time tools configuration (raw, unresolved)
     attr_reader :mcp_config, :tools_config
 
+    # Runnable protocol: a single robot is a crew of one. (network? defaults to
+    # false from RobotLab::Runnable.)
+    #
+    # @return [Array<Robot>]
+    def crew
+      [self]
+    end
+
+    # Returns the fully-merged configuration for this robot at runtime.
+    #
+    # Reflects the result of merging the RunConfig hierarchy (global → network →
+    # constructor kwargs → template front matter). Nil fields are omitted.
+    #
+    # @return [Hash] merged config keyed by field name
+    #
+    # @example
+    #   robot.effective_config
+    #   #=> { model: "claude-sonnet-4-6", temperature: 0.7, max_tokens: 4096 }
+    def effective_config
+      {
+        model:               @config.model,
+        temperature:         @config.temperature,
+        top_p:               @config.top_p,
+        top_k:               @config.top_k,
+        max_tokens:          @config.max_tokens,
+        presence_penalty:    @config.presence_penalty,
+        frequency_penalty:   @config.frequency_penalty,
+        stop:                @config.stop,
+        tools:               @config.tools,
+        mcp:                 @config.mcp,
+        max_tool_rounds:     @config.max_tool_rounds,
+        doom_loop_threshold: @config.doom_loop_threshold,
+        auto_compact:        @config.auto_compact,
+        compact_threshold:   @config.compact_threshold,
+        token_budget:        @config.token_budget,
+        cost_budget:         @config.cost_budget
+      }.compact
+    end
+
     # Creates a new Robot instance.
     #
     # @param name [String] the unique identifier for the robot
@@ -130,141 +182,51 @@ module RobotLab
       stop: nil,
       max_tool_rounds: nil,
       token_budget: nil,
+      cost_budget: nil,
+      doom_loop_threshold: nil,
       mcp_discovery: false,
       config: nil
     )
-      @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)
-      @skills = skills ? Array(skills).map(&:to_sym) : nil
-      @expanded_skills = nil
-      @mcp_discovery = mcp_discovery
+      validate_tools_filter!(tools)
 
-      # Build RunConfig from explicit kwargs, merged on top of passed-in config.
-      # Explicit constructor kwargs always override the shared config.
-      explicit_fields = {
+      assign_identity_ivars(name: name, template: template, system_prompt: system_prompt,
+                            context: context, description: description, local_tools: local_tools,
+                            skills: skills, mcp_discovery: mcp_discovery)
+
+      build_effective_config(
         model: model, temperature: temperature, top_p: top_p, top_k: top_k,
         max_tokens: max_tokens, presence_penalty: presence_penalty,
         frequency_penalty: frequency_penalty, stop: stop,
         on_tool_call: on_tool_call, on_tool_result: on_tool_result,
         on_content: on_content, bus: bus, enable_cache: enable_cache,
-        max_tool_rounds: max_tool_rounds, token_budget: token_budget
-      }.compact
-
-      # Only include mcp/tools if explicitly set (not the default :none sentinel)
-      resolved_mcp = mcp_servers.any? ? mcp_servers : mcp
-      explicit_fields[:mcp] = resolved_mcp unless ToolConfig.none_value?(resolved_mcp)
-      explicit_fields[:tools] = tools unless ToolConfig.none_value?(tools)
-
-      explicit_config = RunConfig.new(**explicit_fields)
-      @config = config ? config.merge(explicit_config) : explicit_config
-
-      # Extract values from effective config for backward compatibility
-      @on_tool_call = @config.on_tool_call
-      @on_tool_result = @config.on_tool_result
-      @on_content = @config.on_content
-
-      # Store raw config values for hierarchical resolution
-      @mcp_config = @config.mcp || :none
-      @tools_config = @config.tools || :none
-
-      # MCP state
-      @mcp_clients = {}
-      @mcp_tools = []
-      @mcp_initialized = false
-
-      # Bus state (optional inter-robot communication)
-      @bus               = @config.bus
-      @message_counter   = 0
-      @outbox            = {}
-      @message_handler   = nil
-      @bus_poller        = nil
-      @private_bus_poller = nil
-      @bus_poller_group  = :default
-
-      # Token tracking
-      @total_input_tokens = 0
-      @total_output_tokens = 0
-
-      # Learning accumulation
-      @learnings = []
-
-      # Inherent memory (used when standalone, not in a network)
-      cache_enabled = @config.key?(:enable_cache) ? @config.enable_cache : true
-      @memory = Memory.new(enable_cache: cache_enabled)
-
-      # Restore persisted learnings from inherent memory if present
-      persisted = @memory.get(:learnings)
-      @learnings = Array(persisted) if persisted
+        max_tool_rounds: max_tool_rounds, token_budget: token_budget, cost_budget: cost_budget,
+        doom_loop_threshold: doom_loop_threshold, mcp_servers: mcp_servers,
+        mcp: mcp, tools: tools, config: config
+      )
 
-      # Ensure config is loaded (triggers PM setup, RubyLLM config, etc.)
-      config = RobotLab.config
+      extract_config_ivars
+      initialize_runtime_state
+      initialize_memory
 
-      # Build chat kwargs for Agent's super
-      resolved_model = @config.model || config.ruby_llm.model
-      chat_kwargs = { model: resolved_model }
+      lab_config = RobotLab.config
+      resolved_model = @config.model || lab_config.ruby_llm.model
+      chat_kwargs   = { model: resolved_model }
 
-      # Pass provider through for local providers (Ollama, GPUStack, etc.)
-      # RubyLLM auto-sets assume_model_exists for local providers when
-      # provider is specified.
+      # RubyLLM auto-sets assume_model_exists for local providers when provider is specified.
       @provider = provider
       if @provider
         chat_kwargs[:provider] = @provider
         chat_kwargs[:assume_model_exists] = true
       end
 
-      # Create the persistent chat via Agent's initialize
       super(chat: nil, **chat_kwargs)
 
-      # Dynamically delegate all with_* methods from the Chat class
-      define_chat_delegators
-
-      # Gather all skill IDs from constructor + main template front matter
-      all_skill_ids = Array(@skills)
-      if @template
-        parsed_main = PM.parse(@template)
-        fm_skills = extract_skills_from_metadata(parsed_main.metadata)
-        all_skill_ids = all_skill_ids + fm_skills
-      end
-
-      if all_skill_ids.any?
-        # Skills path: expand skills, merge config, concatenate bodies
-        apply_skills_and_template_to_chat(all_skill_ids, context)
-      elsif @template
-        # Standard path: single template, no skills
-        apply_template_to_chat(context)
-      end
-
-      @chat.with_instructions(@system_prompt) if @system_prompt
-
-      # Constructor params override template front matter (use config values)
-      @chat.with_temperature(@config.temperature) if @config.temperature
-
-      # These parameters don't have dedicated with_* methods on Chat;
-      # pass them through with_params.
-      extra_params = {
-        top_p: @config.top_p,
-        top_k: @config.top_k,
-        max_tokens: @config.max_tokens,
-        presence_penalty: @config.presence_penalty,
-        frequency_penalty: @config.frequency_penalty,
-        stop: @config.stop
-      }.compact
-      @chat.with_params(**extra_params) if extra_params.any?
-
-      # 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
+      apply_template
+      apply_system_prompt
+      apply_chat_params
+      register_chat_callbacks
     end
 
-
     # Returns the model identifier
     #
     # @return [String, nil] the LLM model ID string
@@ -275,100 +237,6 @@ module RobotLab
       m.respond_to?(:id) ? m.id : m.to_s
     end
 
-    # Dynamically delegate all with_* methods from @chat, returning self for chaining.
-    # Discovered from the actual Chat class to avoid maintenance sync issues.
-    private def define_chat_delegators
-      @chat.class.public_instance_methods(false)
-        .select { |m| m.start_with?('with_') }
-        .each do |method_name|
-          define_singleton_method(method_name) do |*args, **kwargs, &block|
-            @chat.public_send(method_name, *args, **kwargs, &block)
-            self
-          end
-        end
-    end
-
-
-    # Send a message and get a response, with Robot's extended capabilities
-    #
-    # @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
-    # @yield [chunk] optional streaming block called with each content chunk
-    # @return [RobotResult]
-    def run(message = nil, network: nil, network_memory: nil, network_config: nil,
-            memory: nil, mcp: :none, tools: :none, **kwargs, &block)
-      # Determine which memory to use
-      run_memory = resolve_active_memory(network: network, network_memory: network_memory)
-
-      # Merge runtime memory if provided
-      case memory
-      when Memory
-        run_memory = memory
-      when Hash
-        run_memory.merge!(memory)
-      end
-
-      # Set current_writer so memory notifications know who wrote the value
-      previous_writer = run_memory.current_writer
-      run_memory.current_writer = @name
-
-      begin
-        # Resolve hierarchical MCP and tools configuration
-        resolved_mcp = resolve_mcp_hierarchy(mcp, network: network, network_config: network_config)
-        resolved_tools = resolve_tools_hierarchy(tools, network: network, network_config: network_config)
-
-        # Filter MCP servers by semantic relevance when discovery is enabled.
-        # Only applies on the first run (before @mcp_initialized) so connections
-        # are not torn down mid-conversation.
-        if @mcp_discovery && !@mcp_initialized && resolved_mcp.is_a?(Array)
-          resolved_mcp = MCP::ServerDiscovery.select(message.to_s, from: resolved_mcp)
-        end
-
-        # Initialize or update MCP clients based on resolved config
-        ensure_mcp_clients(resolved_mcp)
-
-        # Apply filtered tools to the persistent chat
-        filtered = filtered_tools(resolved_tools)
-        @chat.with_tools(*filtered) if filtered.any?
-
-        # 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?
-
-        # Prepend accumulated learnings to the user message
-        effective_message = inject_learnings(message)
-
-        # Install circuit breaker for this run if max_tool_rounds is configured
-        install_circuit_breaker if @config.max_tool_rounds
-
-        # Delegate to Agent's ask (which calls @chat.ask)
-        ask_kwargs = kwargs.slice(:with)
-        streaming = effective_streaming_block(block)
-        response = ask(effective_message, **ask_kwargs, &streaming)
-
-        result = build_result(response, run_memory)
-
-        # Enforce token budget if configured
-        budget = @config.token_budget
-        if 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
-
-        result
-      ensure
-        restore_tool_call_callback if @config.max_tool_rounds
-        run_memory.current_writer = previous_writer
-      end
-    end
-
-
     # Reconfigure the robot for a new context
     #
     # @param template [Symbol, nil] new template to apply
@@ -396,7 +264,6 @@ module RobotLab
       self
     end
 
-
     # SimpleFlow step interface
     #
     # @param result [SimpleFlow::Result] incoming result from previous step
@@ -429,7 +296,6 @@ module RobotLab
         .continue(error_result)
     end
 
-
     # Reset the robot's inherent memory
     #
     # @return [self]
@@ -438,7 +304,6 @@ module RobotLab
       self
     end
 
-
     # Eagerly connect to configured MCP servers and discover tools.
     # Normally MCP connections are lazy (established on first run).
     # Call this to connect early, e.g. to display connection status at startup.
@@ -468,7 +333,6 @@ module RobotLab
       self
     end
 
-
     # --- Public APIs for external MCP and history management (A4) ---
 
     # Inject pre-connected MCP clients and their tools into this robot.
@@ -508,10 +372,10 @@ module RobotLab
     def clear_messages(keep_system: true)
       if keep_system
         system_msg = @chat.messages.find { |m| m.role == :system }
-        @chat.instance_variable_set(:@messages, [])
+        @chat.reset_messages!
         @chat.add_message(system_msg) if system_msg
       else
-        @chat.instance_variable_set(:@messages, [])
+        @chat.reset_messages!
       end
       self
     end
@@ -521,7 +385,8 @@ module RobotLab
     # @param messages [Array<RubyLLM::Message>] the messages to restore
     # @return [self]
     def replace_messages(messages)
-      @chat.instance_variable_set(:@messages, messages)
+      @chat.reset_messages!
+      messages.each { |m| @chat.add_message(m) }
       self
     end
 
@@ -583,14 +448,14 @@ module RobotLab
     # @param kwargs [Hash] additional keyword args forwarded to Robot#run
     # @return [RobotResult] when async: false
     # @return [DelegationFuture] when async: true
-    def delegate(to:, task:, async: false, **kwargs)
+    def delegate(to:, task:, async: false, **)
       if async
         future = DelegationFuture.new(robot_name: to.name, delegated_by: @name)
         delegator_name = @name
 
         Thread.new do
           started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-          result = to.run(task, **kwargs)
+          result = to.run(task, **)
           result.duration     = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at
           result.delegated_by = delegator_name
           future.resolve!(result)
@@ -601,7 +466,7 @@ module RobotLab
         future
       else
         started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-        result = to.run(task, **kwargs)
+        result = to.run(task, **)
         result.duration     = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at
         result.delegated_by = @name
         result
@@ -628,7 +493,6 @@ module RobotLab
       @mcp_clients[server_name]
     end
 
-
     # Add a learning to this robot's accumulation store.
     #
     # Deduplicates by bidirectional substring matching: a new learning is
@@ -644,19 +508,24 @@ module RobotLab
       text = text.to_s.strip
       return self if text.empty?
 
-      # Remove any existing learning that is a substring of the new one
-      @learnings.reject! { |existing| text.include?(existing) }
+      ctx        = LearnHookContext.new(robot: self, text: text, learnings_before: @learnings.dup)
+      registries = [RobotLab.hooks, @hooks]
+
+      RobotLab::Hooks.run(:learn, ctx, registries: registries) do
+        @learnings.reject! { |existing| text.include?(existing) }
+
+        unless @learnings.any? { |existing| existing.include?(text) }
+          @learnings << text
+          @memory.set(:learnings, @learnings.dup)
+          ctx.stored = true
+        end
 
-      # Skip if any existing learning already covers the new one
-      unless @learnings.any? { |existing| existing.include?(text) }
-        @learnings << text
-        @memory.set(:learnings, @learnings.dup)
+        RobotLab::Hooks.call(:on_learn, ctx, registries: registries)
       end
 
       self
     end
 
-
     # Reset cumulative token counters to zero.
     #
     # @return [self]
@@ -666,7 +535,6 @@ module RobotLab
       self
     end
 
-
     # Converts the robot to a hash representation
     #
     # @return [Hash]
@@ -690,15 +558,259 @@ module RobotLab
 
     private
 
-    # Determine which memory to use
+    # `tools:` is a NAME allowlist (a filter over available tools), not a place
+    # to attach tool instances — passing instances there silently attaches
+    # nothing. Catch the mistake with a clear, actionable error.
+    def validate_tools_filter!(tools)
+      return unless tools.is_a?(Array)
+
+      offenders = tools.reject { |t| t.is_a?(String) || t.is_a?(Symbol) }
+      return if offenders.empty?
+
+      classes = offenders.map { |t| t.is_a?(Class) ? t.name : t.class.name }.uniq.join(", ")
+      raise ArgumentError,
+            "`tools:` expects tool names (String/Symbol) to allow, but received #{classes}. " \
+            "To attach tool instances or classes, pass them as `local_tools:` " \
+            "(e.g. RobotLab.build(local_tools: [MyTool.new]))."
+    end
+
+    def assign_identity_ivars(name:, template:, system_prompt:, context:, description:,
+                              local_tools:, skills:, mcp_discovery:)
+      @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)
+      @skills = skills ? Array(skills).map(&:to_sym) : nil
+      @expanded_skills = nil
+      @pending_agent_skills = []
+      @agent_skill_store    = nil
+      @mcp_discovery = mcp_discovery
+    end
+
+    # Build RunConfig from explicit kwargs, merged on top of any passed-in config.
+    # Explicit constructor kwargs always win.
+    def build_effective_config(model:, temperature:, top_p:, top_k:, max_tokens:,
+                               presence_penalty:, frequency_penalty:, stop:,
+                               on_tool_call:, on_tool_result:, on_content:,
+                               bus:, enable_cache:, max_tool_rounds:, token_budget:, cost_budget:,
+                               doom_loop_threshold:, mcp_servers:, mcp:, tools:, config:)
+      explicit_fields = {
+        model: model, temperature: temperature, top_p: top_p, top_k: top_k,
+        max_tokens: max_tokens, presence_penalty: presence_penalty,
+        frequency_penalty: frequency_penalty, stop: stop,
+        on_tool_call: on_tool_call, on_tool_result: on_tool_result,
+        on_content: on_content, bus: bus, enable_cache: enable_cache,
+        max_tool_rounds: max_tool_rounds, token_budget: token_budget, cost_budget: cost_budget,
+        doom_loop_threshold: doom_loop_threshold
+      }.compact
+
+      resolved_mcp = mcp_servers.any? ? mcp_servers : mcp
+      explicit_fields[:mcp]   = resolved_mcp unless ToolConfig.none_value?(resolved_mcp)
+      explicit_fields[:tools] = tools        unless ToolConfig.none_value?(tools)
+
+      explicit_config = RunConfig.new(**explicit_fields)
+      @config = config ? config.merge(explicit_config) : explicit_config
+    end
+
+    def extract_config_ivars
+      @on_tool_call   = @config.on_tool_call
+      @on_tool_result = @config.on_tool_result
+      @on_content     = @config.on_content
+      @mcp_config     = @config.mcp   || :none
+      @tools_config   = @config.tools || :none
+    end
+
+    def initialize_runtime_state
+      @mcp_clients         = {}
+      @mcp_tools           = []
+      @mcp_initialized     = false
+      @bus                 = @config.bus
+      @message_counter     = 0
+      @outbox              = {}
+      @bus_mutex           = Mutex.new
+      @message_handler     = ->(_msg) {}
+      @bus_poller          = nil
+      @private_bus_poller  = nil
+      @bus_poller_group    = :default
+      @total_input_tokens  = 0
+      @total_output_tokens = 0
+      @learnings           = []
+      @hooks               = HookRegistry.new
+      @budget_ledger       = build_budget_ledger
+    end
+
+    def initialize_memory
+      cache_enabled = @config.key?(:enable_cache) ? @config.enable_cache : true
+      @memory = Memory.new(enable_cache: cache_enabled)
+      persisted = @memory.get(:learnings)
+      @learnings = Array(persisted) if persisted
+    end
+
+    def apply_template
+      define_chat_delegators
+
+      all_skill_ids = Array(@skills)
+      if @template
+        parsed_main = PM.parse(@template)
+        fm_skills   = extract_skills_from_metadata(parsed_main.metadata)
+        all_skill_ids += fm_skills
+      end
+
+      if all_skill_ids.any?
+        apply_skills_and_template_to_chat(all_skill_ids, @build_context)
+      elsif @template
+        apply_template_to_chat(@build_context)
+      end
+    end
+
+    def apply_system_prompt
+      @chat.with_instructions(@system_prompt) if @system_prompt
+    end
+
+    def apply_chat_params
+      @chat.with_temperature(@config.temperature) if @config.temperature
+
+      extra_params = {
+        top_p: @config.top_p, top_k: @config.top_k,
+        max_tokens: @config.max_tokens,
+        presence_penalty: @config.presence_penalty,
+        frequency_penalty: @config.frequency_penalty,
+        stop: @config.stop
+      }.compact
+      @chat.with_params(**extra_params) if extra_params.any?
+    end
+
+    def register_chat_callbacks
+      @chat.on_tool_call(&@on_tool_call)     if @on_tool_call
+      @chat.on_tool_result(&@on_tool_result) if @on_tool_result
+      setup_bus_channel if @bus
+    end
+
+    # Dynamically delegate all with_* methods from @chat, returning self for chaining.
+    # Discovered from the actual Chat class to avoid maintenance sync issues.
+    def define_chat_delegators
+      @chat.class.public_instance_methods(false)
+           .select { |m| m.start_with?('with_') }
+           .each do |method_name|
+             define_singleton_method(method_name) do |*args, **kwargs, &block|
+               @chat.public_send(method_name, *args, **kwargs, &block)
+               self
+             end
+           end
+    end
+
     def resolve_active_memory(network: nil, network_memory: nil)
       network_memory || network&.memory || @memory
     end
 
+    def resolve_run_memory(memory, network:, network_memory:)
+      run_memory = resolve_active_memory(network: network, network_memory: network_memory)
+      case memory
+      when Memory then memory
+      when Hash   then run_memory.tap { |m| m.merge!(memory) }
+      else             run_memory
+      end
+    end
+
+    def prepare_tools(message:, mcp:, tools:, network:, network_config:)
+      resolved_mcp   = resolve_mcp_hierarchy(mcp, network: network, network_config: network_config)
+      resolved_tools = resolve_tools_hierarchy(tools, network: network, network_config: network_config)
+
+      if @mcp_discovery && !@mcp_initialized && resolved_mcp.is_a?(Array)
+        resolved_mcp = MCP::ServerDiscovery.select(message.to_s, from: resolved_mcp)
+      end
+
+      ensure_mcp_clients(resolved_mcp)
+
+      # An EXPLICIT `:none` (or literal `[]`) means "send zero tools this turn" —
+      # e.g. a relevance filter judged no tool useful for the prompt. That is
+      # distinct from `:inherit`/unset, which means "no filter, use every attached
+      # tool". Both collapse to `[]` once resolved, and `filtered_tools([])`
+      # treats an empty allowlist as "all tools", so we must branch on the raw
+      # runtime value before resolution to honor the zero-tools intent.
+      filtered = explicit_none_tools?(tools) ? [] : cap_tools(filtered_tools(resolved_tools))
+
+      # replace: true so the chat holds EXACTLY this turn's resolved+capped set.
+      # RubyLLM's with_tools appends by default; on a persistent chat that lets
+      # tools accumulate across turns, so a capped per-turn addition could still
+      # push the chat's total past the provider limit. An explicit none clears
+      # the chat's tools to zero (with_tools(replace: true) with no tools).
+      @chat.with_tools(*filtered, replace: true) if filtered.any? || explicit_none_tools?(tools)
+    end
+
+    # True when the runtime tools value explicitly requests zero tools — `:none`
+    # or a literal empty array — as opposed to `:inherit`/`nil`, which mean "no
+    # filter, use all attached tools". Lets a per-turn filter that found nothing
+    # relevant actually send no tools instead of the whole set.
+    #
+    # @param tools [Symbol, Array, nil]
+    # @return [Boolean]
+    def explicit_none_tools?(tools)
+      tools == :none || (tools.is_a?(Array) && tools.empty?)
+    end
+
+    # Clamp the resolved tool list to the provider's hard maximum. Most LLM
+    # providers reject tool arrays longer than 128 and fail the whole turn. This
+    # is the definitive choke point: tools are fully resolved (MCP connected)
+    # and about to be handed to the chat, so the cap holds no matter how the
+    # tools were configured, filtered, or connected. Cap value comes from
+    # RunConfig#max_tools, defaulting to DEFAULT_MAX_TOOLS; nil/<=0 disables it.
+    #
+    # @param tools [Array<Tool>] the resolved tools
+    # @return [Array<Tool>] at most `max_tools` tools
+    def cap_tools(tools)
+      max = effective_max_tools
+      return tools if max.nil? || tools.size <= max
+
+      RobotLab.config.logger.warn(
+        "[#{@name}] tool list (#{tools.size}) exceeds max_tools (#{max}); " \
+        "sending #{max}, dropping #{tools.size - max}"
+      )
+      tools.first(max)
+    end
+
+    # The provider tool cap: RunConfig#max_tools when set positive, else the
+    # default. Returns nil only if the default itself is disabled.
+    #
+    # @return [Integer, nil]
+    def effective_max_tools
+      configured = @config.respond_to?(:max_tools) ? @config.max_tools : nil
+      configured&.positive? ? configured : DEFAULT_MAX_TOOLS
+    end
+
+    def invoke_ask(context:, kwargs:, hooks:, block:)
+      generation_context = LlmGenerationHookContext.new(
+        robot: self,
+        network: context.network,
+        task: context.task,
+        memory: context.memory,
+        config: context.config,
+        request: context.request,
+        metadata: context.metadata
+      )
+
+      RobotLab::Hooks.run(:llm_generation, generation_context,
+                          registries: hook_registries(context.network), per_run_hooks: hooks) do
+        effective_message = inject_learnings(generation_context.request)
+        maybe_compact(network: context.network)
+        install_circuit_breaker if @config.max_tool_rounds
+        install_doom_loop_detection
+        ask_kwargs = kwargs.slice(:with)
+        streaming  = effective_streaming_block(block)
+        ask(effective_message, **ask_kwargs, &streaming)
+      end
+    end
+
+    def hook_registries(network = nil)
+      [RobotLab.hooks, network&.hooks, @hooks]
+    end
 
     # Extract run context from SimpleFlow::Result
     def extract_run_context(result)
-      run_params = result.context[:run_params] || {}
+      run_params = (result.context[:run_params] || {}).dup
 
       # Extract robot-specific params
       mcp = run_params.delete(:mcp) || :none
@@ -706,6 +818,8 @@ module RobotLab
       memory = run_params.delete(:memory)
       network_memory = run_params.delete(:network_memory)
       network_config = run_params.delete(:network_config)
+      network = run_params.delete(:network)
+      task = run_params.delete(:task)
 
       # Build base context from remaining run params
       base = run_params.dup
@@ -728,17 +842,15 @@ module RobotLab
       merged[:memory] = memory if memory
       merged[:network_memory] = network_memory if network_memory
       merged[:network_config] = network_config if network_config
+      merged[:network] = network if network
+      merged[:task] = task if task
 
       merged
     end
 
-
     def build_result(response, _memory)
-      output = if response.respond_to?(:content) && response.content
-                 [TextMessage.new(role: 'assistant', content: response.content)]
-               else
-                 []
-               end
+      text = result_text(response)
+      output = text ? [TextMessage.new(role: 'assistant', content: text)] : []
 
       tool_calls = response.respond_to?(:tool_calls) ? (response.tool_calls || []) : []
 
@@ -767,6 +879,36 @@ module RobotLab
       )
     end
 
+    # Text for the result's output. Prefers the final response's content, then
+    # falls back in order to: (1) thinking text for models that route all output
+    # through reasoning_content (e.g. qwen3 on Ollama), (2) the most recent
+    # assistant text within the current turn for models that end on a tool call
+    # with no trailing text.
+    #
+    # The chat-history fallback is scoped to messages AFTER the last user message
+    # (the current turn) to prevent a previous turn's response from being returned
+    # when a thinking-mode model emits nothing in response.content.
+    def result_text(response)
+      content = response.content if response.respond_to?(:content)
+      return content if content && !content.to_s.empty?
+
+      # Ollama routes qwen3's reasoning to reasoning_content, which ruby_llm
+      # surfaces as response.thinking (a RubyLLM::Thinking object). When content
+      # is nil and thinking is present, the thinking IS the response for that turn.
+      if response.respond_to?(:thinking) && (thinking = response.thinking)
+        thinking_text = thinking.respond_to?(:text) ? thinking.text.to_s : thinking.to_s
+        return thinking_text unless thinking_text.empty?
+      end
+
+      return nil unless @chat.respond_to?(:messages)
+
+      messages = @chat.messages
+      last_user_idx = messages.rindex { |m| m.role == :user } || -1
+      current_turn = messages[(last_user_idx + 1)..]
+
+      last = current_turn.rfind { |m| m.role == :assistant && m.content && !m.content.to_s.empty? }
+      last&.content
+    end
 
     def normalize_tool_calls(tool_calls)
       return [] unless tool_calls
@@ -783,7 +925,6 @@ module RobotLab
       end
     end
 
-
     # Merge the stored on_content callback with a runtime streaming block.
     # If both exist, both fire (stored first, then runtime block).
     #
@@ -794,15 +935,16 @@ module RobotLab
       return runtime_block unless @on_content
 
       stored = @on_content
-      proc { |chunk| stored.call(chunk); runtime_block.call(chunk) }
+      proc { |chunk|
+        stored.call(chunk)
+        runtime_block.call(chunk)
+      }
     end
 
-
     def all_tools
       @local_tools + @mcp_tools
     end
 
-
     def filtered_tools(allowed_names)
       available = all_tools
       return available if allowed_names.empty?
@@ -810,7 +952,6 @@ module RobotLab
       ToolConfig.filter_tools(available, allowed_names: allowed_names)
     end
 
-
     # Prepend accumulated learnings to a user message when learnings exist.
     def inject_learnings(message)
       return message if @learnings.empty? || message.nil?
@@ -821,6 +962,106 @@ module RobotLab
       "#{learning_block}#{message}"
     end
 
+    # Install per-run doom loop detection on @chat's execute_tool.
+    # Tracks tool call names; when a consecutive or cyclic repetition exceeds
+    # the threshold, embeds a self-correction warning in the tool result so the
+    # LLM can change strategy without requiring an external circuit breaker.
+    def install_doom_loop_detection
+      threshold = @config.doom_loop_threshold || DoomLoopDetector::DEFAULT_THRESHOLD
+      detector = DoomLoopDetector.new(threshold: threshold)
+
+      @chat.define_singleton_method(:execute_tool) do |tool_call|
+        result = super(tool_call)
+        detector.track(tool_call.name)
+
+        if detector.doom_loop?
+          warning = detector.warning_message
+          detector.reset
+          case result
+          when Hash   then result.merge(_doom_loop_warning: warning)
+          when String then "#{result}\n\n⚠️ #{warning}"
+          else             result
+          end
+        else
+          result
+        end
+      end
+    end
+
+    # Remove the doom loop detection singleton method from @chat.
+    def remove_doom_loop_detection
+      sc = @chat.singleton_class
+      sc.remove_method(:execute_tool) if sc.method_defined?(:execute_tool)
+    end
+
+    # Compact conversation history before an ask() call if auto_compact is set.
+    #
+    # :none (default) — no-op
+    # :context_window — compress when estimated tokens exceed compact_threshold
+    #                   fraction of the model's context window (default 80%)
+    # Proc            — called with self; application owns the decision and strategy
+    #
+    # Fires the :compaction hook family (before/around/after_compaction).
+    # An on_compaction handler can replace the default strategy entirely by
+    # setting ctx.compacted_messages; the core algorithm is skipped when handled.
+    def maybe_compact(network: nil)
+      return if @chat.messages.empty?
+
+      compact = @config.auto_compact
+      return if compact.nil? || compact == :none
+      return if compact == :context_window && !over_compact_threshold?
+
+      strategy = compact.is_a?(Proc) ? :custom : compact
+      ctx = CompactionHookContext.new(
+        robot:           self,
+        messages_before: @chat.messages.dup,
+        config:          @config,
+        strategy:        strategy
+      )
+
+      RobotLab::Hooks.run(:compaction, ctx, registries: hook_registries(network)) do
+        RobotLab::Hooks.call(:on_compaction, ctx, registries: hook_registries(network))
+
+        if ctx.handled?
+          replace_messages(ctx.compacted_messages)
+        else
+          case compact
+          when :context_window
+            begin
+              compress_history
+            rescue DependencyError => e
+              RobotLab.config.logger.warn("[#{@name}] auto_compact: #{e.message}; skipping compaction")
+            end
+          when Proc
+            compact.call(self)
+          end
+          ctx.compacted_messages = @chat.messages.dup
+        end
+      end
+    end
+
+    def over_compact_threshold?
+      threshold     = (@config.compact_threshold || 0.80).to_f
+      estimated_tok = @chat.messages.sum { |m| m.content.to_s.length } / 4
+
+      window = begin
+        RubyLLM.models.find(model)&.context_window || 200_000
+      rescue StandardError
+        200_000
+      end
+
+      estimated_tok >= window * threshold
+    end
+
+    def compact_if_over_context_window
+      return unless over_compact_threshold?
+
+      begin
+        compress_history
+      rescue DependencyError => e
+        RobotLab.config.logger.warn("[#{@name}] auto_compact: #{e.message}; skipping compaction")
+      end
+    end
 
     # Install a per-run circuit breaker on the chat's on_tool_call hook.
     # Raises ToolLoopError if tool calls exceed @config.max_tool_rounds.
@@ -841,7 +1082,6 @@ module RobotLab
       end
     end
 
-
     # Restore the original on_tool_call callback after a circuit-breaker run.
     def restore_tool_call_callback
       @chat.on_tool_call(&@on_tool_call)