robot_lab 0.1.0 → 0.2.1

data/lib/robot_lab/robot.rb

@@ -4,6 +4,7 @@ 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'
 
 module RobotLab
   # LLM-powered robot built on RubyLLM::Agent
@@ -43,6 +44,7 @@ module RobotLab
     include Robot::MCPManagement
     include Robot::BusMessaging
     include Robot::HistorySearch
+    prepend Robot::AgentSkillMatching
 
     # @!attribute [r] name
     #   @return [String] the unique identifier for the robot
@@ -69,7 +71,8 @@ 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
+                :total_input_tokens, :total_output_tokens, :learnings,
+                :durable_store, :learn_domain
 
     # @!attribute [r] mcp_config
     #   @return [Symbol, Array] build-time MCP configuration (raw, unresolved)
@@ -77,6 +80,36 @@ module RobotLab
     #   @return [Symbol, Array] build-time tools configuration (raw, unresolved)
     attr_reader :mcp_config, :tools_config
 
+    # 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
+      }.compact
+    end
+
     # Creates a new Robot instance.
     #
     # @param name [String] the unique identifier for the robot
@@ -130,141 +163,52 @@ module RobotLab
       stop: nil,
       max_tool_rounds: nil,
       token_budget: nil,
+      doom_loop_threshold: nil,
       mcp_discovery: false,
-      config: nil
+      config: nil,
+      learn: false,
+      learn_domain: nil,
+      store_path: 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
+      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 RunConfig from explicit kwargs, merged on top of passed-in config.
-      # Explicit constructor kwargs always override the shared config.
-      explicit_fields = {
+      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,
+        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
+      configure_learning(learn: learn, learn_domain: learn_domain, store_path: store_path)
 
-      # 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,20 +219,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
@@ -301,74 +231,27 @@ module RobotLab
     # @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
+      run_memory = resolve_run_memory(memory, network: network, network_memory: network_memory)
       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)
+        prepare_tools(message: message, mcp: mcp, tools: tools,
+                      network: network, network_config: network_config)
         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)
-
+        response = invoke_ask(message: message, kwargs: kwargs, block: block)
         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
-
+        enforce_token_budget!
         result
       ensure
+        remove_doom_loop_detection
         restore_tool_call_callback if @config.max_tool_rounds
+        run_reflector if @durable_store
         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 +279,6 @@ module RobotLab
       self
     end
 
-
     # SimpleFlow step interface
     #
     # @param result [SimpleFlow::Result] incoming result from previous step
@@ -429,7 +311,6 @@ module RobotLab
         .continue(error_result)
     end
 
-
     # Reset the robot's inherent memory
     #
     # @return [self]
@@ -438,7 +319,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 +348,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 +387,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 +400,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 +463,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 +481,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 +508,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
@@ -656,7 +535,6 @@ module RobotLab
       self
     end
 
-
     # Reset cumulative token counters to zero.
     #
     # @return [self]
@@ -666,7 +544,6 @@ module RobotLab
       self
     end
 
-
     # Converts the robot to a hash representation
     #
     # @return [Hash]
@@ -690,15 +567,189 @@ module RobotLab
 
     private
 
-    # Determine which memory to use
+    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:,
+                               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,
+        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              = {}
+      @message_handler     = ->(_msg) {}
+      @bus_poller          = nil
+      @private_bus_poller  = nil
+      @bus_poller_group    = :default
+      @total_input_tokens  = 0
+      @total_output_tokens = 0
+      @learnings           = []
+    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 configure_learning(learn:, learn_domain:, store_path:)
+      return unless learn && RobotLab.extension_loaded?(:durable)
+
+      if learn_domain
+        setup_durable_learning(domain: learn_domain, store_path: store_path)
+      else
+        warn "[RobotLab] Robot '#{@name}': learn: true requires learn_domain: to be set. Durable learning disabled."
+      end
+    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)
+
+      filtered = filtered_tools(resolved_tools)
+      @chat.with_tools(*filtered) if filtered.any?
+    end
+
+    def invoke_ask(message:, kwargs:, block:)
+      effective_message = inject_learnings(message)
+      maybe_compact
+      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
+
+    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
 
     # 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
@@ -732,7 +783,6 @@ module RobotLab
       merged
     end
 
-
     def build_result(response, _memory)
       output = if response.respond_to?(:content) && response.content
                  [TextMessage.new(role: 'assistant', content: response.content)]
@@ -767,7 +817,6 @@ module RobotLab
       )
     end
 
-
     def normalize_tool_calls(tool_calls)
       return [] unless tool_calls
 
@@ -783,7 +832,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 +842,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 +859,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 +869,76 @@ 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
+    def maybe_compact
+      return if @chat.messages.empty?
+
+      compact = @config.auto_compact
+      return if compact.nil? || compact == :none
+
+      case compact
+      when :context_window
+        compact_if_over_context_window
+      when Proc
+        compact.call(self)
+      end
+    end
+
+    def compact_if_over_context_window
+      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
+
+      return if estimated_tok < window * 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 +959,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)