rubyn-code 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 17b949375b6599cc1899caffd006f644a7292244982103608bfe31ad9146f549
-  data.tar.gz: 9c97ea6f5a1d73a91b220221b20f028833b86e7f6caa3904860e5000004f3fa9
+  metadata.gz: f91f304118c243f82ce9165db84f303b111d9c18daf74c75cdc7dcec4289647b
+  data.tar.gz: 2cfc8263c1532d805ea9b9592c3601033e4fdab8dc19c6b0329a0eec40316cbb
 SHA512:
-  metadata.gz: 33bd180490d02c55def1d138ee8c71607c639ddb7f66f5fc05392e31bd41feead7bbf42d6224e67e36651410aeac6b67e55afc9522f965affc2787d91cc54967
-  data.tar.gz: a55628e9fb27d9de1c9822c6fc215820fa6b639d9f9fd6f4750b79f26ab31a09c59da8def39d391ba54f3bcbe92516973904b40260c81afe0b60017746eefa3b
+  metadata.gz: 6bb339794d0cbe8d149e0b2e94c408b304d48f786aa2a297af5c8028c15c9796d4e5f0313be20c1ecf8b449c0ef80afa4263f581603c5c915b540c7a89b8257c
+  data.tar.gz: 2f1fc37549f2223a5c5f07be4817bade9a4d6466ef30b8927fb0de94cf4c78c41b1b5e9e8a3379fb69e503d34226df9d22e4988bb45231666afc49e4f325d789

data/README.md

@@ -80,7 +80,7 @@ bundle exec ruby -Ilib exe/rubyn-code
 
 </details>
 
-**Authentication:** Rubyn Code reads your Claude Code OAuth token from the macOS Keychain automatically. Just make sure you've logged into Claude Code once (`claude` in your terminal). Also supports `ANTHROPIC_API_KEY` env var.
+**Authentication:** Rubyn Code reads your Claude Code OAuth token from the macOS Keychain automatically. Just make sure you've logged into Claude Code once (`claude` in your terminal). Also supports `ANTHROPIC_API_KEY` env var. See [Authentication](#authentication) for OpenAI and other providers.
 
 ## Quick Start
 
@@ -142,7 +142,7 @@ Agent finished (23 tool calls).
 This is a Rails 7.1 e-commerce app with...
 ```
 
-## 28 Built-in Tools
+## 29 Built-in Tools
 
 | Category | Tools |
 |----------|-------|
@@ -157,6 +157,7 @@ This is a Rails 7.1 e-commerce app with...
 | **Context** | `compact`, `load_skill`, `task` |
 | **Memory** | `memory_search`, `memory_write` |
 | **Teams** | `send_message`, `read_inbox` |
+| **Interactive** | `ask_user` (ask clarifying questions mid-task) |
 
 ## 112 Best Practice Skills
 
@@ -323,6 +324,7 @@ rubyn-code --help             # Show help
 |---------|---------|
 | `/help` | Show help |
 | `/quit` | Exit (saves session + extracts learnings) |
+| `/new` | Save session and start a fresh conversation |
 | `/review [base]` | PR review against best practices |
 | `/spawn name role` | Spawn a persistent teammate |
 | `/compact` | Compress conversation context |
@@ -334,6 +336,8 @@ rubyn-code --help             # Show help
 
 ## Authentication
 
+### Anthropic (default)
+
 | Priority | Source | Setup |
 |----------|--------|-------|
 | 1 | macOS Keychain | Log into Claude Code once: `claude` |
@@ -342,6 +346,24 @@ rubyn-code --help             # Show help
 
 Works with Claude Pro, Max, Team, and Enterprise. Default model: **Claude Opus 4.6**.
 
+### OpenAI
+
+```bash
+export OPENAI_API_KEY=sk-...
+```
+
+Available models: `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.4-nano`, `gpt-4o`, `gpt-4o-mini`, `o3`, `o4-mini`
+
+### OpenAI-Compatible Providers (Groq, Together, Ollama, etc.)
+
+Set the provider-specific API key and configure via `config.yml`:
+
+```bash
+export GROQ_API_KEY=gsk-...
+```
+
+Local providers (Ollama, LM Studio) running on `localhost`/`127.0.0.1` don't require an API key.
+
 ## Architecture
 
 16-layer agentic architecture:
@@ -362,7 +384,7 @@ Works with Claude Pro, Max, Team, and Enterprise. Default model: **Claude Opus 4
 │  Layer 5:  Skills (112 best practice docs, on-demand loading) │
 │  Layer 4:  Context Management (3-layer compression pipeline)  │
 │  Layer 3:  Permissions (tiered access + deny lists + hooks)   │
-│  Layer 2:  Tool System (28 tools, dispatch map registry)      │
+│  Layer 2:  Tool System (29 tools, dispatch map registry)      │
 │  Layer 1:  THE AGENT LOOP (while tool_use → execute → repeat) │
 └──────────────────────────────────────────────────────────────┘
 ```
@@ -379,8 +401,74 @@ daily_budget: 10.00
 # .rubyn-code/config.yml (project — overrides global)
 model: claude-sonnet-4-6
 permission_mode: autonomous
+
+# Use OpenAI instead of Anthropic
+# provider: openai
+# model: gpt-4o
+
+# Use an OpenAI-compatible provider
+# provider: groq
+# provider_base_url: https://api.groq.com/openai/v1
+# model: llama-3.3-70b
+
+# Local Ollama (no API key needed)
+# provider: ollama
+# provider_base_url: http://localhost:11434/v1
+# model: llama3
+```
+
+### Multi-Provider Model Routing
+
+Rubyn can automatically route tasks to different AI models based on complexity. Simple tasks (file search, git ops) use cheap, fast models. Complex tasks (architecture, security review) use the most capable model. Configure per-provider model tiers in `config.yml`:
+
+```yaml
+# ~/.rubyn-code/config.yml
+provider: anthropic
+model: claude-opus-4-6
+
+providers:
+  anthropic:
+    env_key: ANTHROPIC_API_KEY
+    models:
+      cheap: claude-haiku-4-5      # file search, git ops, formatting
+      mid: claude-sonnet-4-6       # code gen, specs, refactors, reviews
+      top: claude-opus-4-6         # architecture, security, complex work
+
+  openai:
+    env_key: OPENAI_API_KEY
+    models:
+      cheap: gpt-5.4-nano          # lightweight tasks
+      mid: gpt-5.4-mini            # regular coding
+      top: gpt-5.4                 # complex reasoning
+
+  groq:
+    base_url: https://api.groq.com/openai/v1
+    env_key: GROQ_API_KEY
+    models:
+      cheap: llama-3-8b
+      mid: llama-3-70b
+    pricing:
+      llama-3-8b: [0.05, 0.08]    # [input_rate, output_rate] per million tokens
+      llama-3-70b: [0.59, 0.79]
+
+  ollama:
+    base_url: http://localhost:11434/v1
+    models:
+      cheap: llama3
+      mid: llama3
+      top: llama3
 ```
 
+**How it works:** When you ask Rubyn to do something, the Model Router detects the task type and picks the right tier. If you've configured model tiers for a provider, those are used first. Otherwise it falls back to the built-in defaults (Anthropic for all tiers).
+
+| Tier | Task types | Default model |
+|------|-----------|---------------|
+| **cheap** | File search, git ops, formatting, summaries | `claude-haiku-4-5` |
+| **mid** | Code generation, specs, refactors, code review, bug fixes | `claude-sonnet-4-6` |
+| **top** | Architecture, security review, complex refactors, planning | `claude-opus-4-6` |
+
+You can also set custom pricing per model so `/cost` reports accurate spending for third-party providers.
+
 ## Development
 
 Requires Ruby 4.0+.

data/lib/rubyn_code/agent/background_job_handler.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module RubynCode
+  module Agent
+    # Manages background job polling, waiting, and notification draining
+    # for the agent loop.
+    module BackgroundJobHandler
+      private
+
+      def wait_for_background_jobs
+        max_wait = 300 # 5 minutes max
+        poll_interval = 3
+
+        RubynCode::Debug.agent(
+          'Waiting for background jobs to finish ' \
+          "(polling every #{poll_interval}s, max #{max_wait}s)"
+        )
+
+        elapsed = poll_until_done(max_wait, poll_interval)
+        drain_background_notifications
+        RubynCode::Debug.agent("Background wait done (#{elapsed}s)")
+      end
+
+      def poll_until_done(max_wait, poll_interval)
+        elapsed = 0
+        while elapsed < max_wait && pending_background_jobs?
+          sleep poll_interval
+          elapsed += poll_interval
+          drain_background_notifications
+        end
+        elapsed
+      end
+
+      def drain_background_notifications
+        return unless @background_manager
+
+        notifications = @background_manager.drain_notifications
+        return if notifications.nil? || notifications.empty?
+
+        summary = notifications.map { |n| format_background_notification(n) }.join("\n\n")
+        @conversation.add_user_message("[Background job results]\n#{summary}")
+      rescue NoMethodError
+        # background_manager does not support drain_notifications yet
+      end
+
+      def pending_background_jobs?
+        return false unless @background_manager
+
+        @background_manager.active_count.positive?
+      rescue NoMethodError
+        false
+      end
+
+      def format_background_notification(notification)
+        return notification.to_s unless notification.is_a?(Hash)
+
+        status   = notification[:status] || 'unknown'
+        job_id   = notification[:job_id]&.[](0..7) || 'unknown'
+        duration = format_duration(notification[:duration])
+        result   = notification[:result] || '(no output)'
+        "Job #{job_id} [#{status}] (#{duration}):\n#{result}"
+      end
+
+      def format_duration(dur)
+        return 'unknown' unless dur
+
+        format('%.1fs', dur)
+      end
+    end
+  end
+end

data/lib/rubyn_code/agent/conversation.rb

@@ -128,64 +128,58 @@ module RubynCode
       # If a tool_use is orphaned (e.g. from Ctrl-C interruption),
       # inject a synthetic tool_result so the API doesn't reject the request.
       def repair_orphaned_tool_uses(formatted)
-        # Collect all tool_use IDs from assistant messages
-        tool_use_ids = Set.new
-        formatted.each do |msg|
-          next unless msg[:role] == 'assistant' && msg[:content].is_a?(Array)
+        orphaned = collect_tool_use_ids(formatted) - collect_tool_result_ids(formatted)
+        return formatted if orphaned.empty?
 
-          msg[:content].each do |block|
-            if block.is_a?(Hash) && (block[:type] == 'tool_use' || block['type'] == 'tool_use')
-              tool_use_ids << (block[:id] || block['id'])
-            end
-          end
+        orphan_results = orphaned.map do |id|
+          { type: 'tool_result', tool_use_id: id, content: '[interrupted]', is_error: true }
         end
 
-        # Collect all tool_result IDs from user messages
-        tool_result_ids = Set.new
+        formatted << { role: 'user', content: orphan_results }
+        formatted
+      end
+
+      def collect_tool_use_ids(formatted)
+        collect_block_ids(formatted, role: 'assistant', type: 'tool_use', id_key: :id, id_str_key: 'id')
+      end
+
+      def collect_tool_result_ids(formatted)
+        collect_block_ids(formatted, role: 'user', type: 'tool_result', id_key: :tool_use_id,
+                                     id_str_key: 'tool_use_id')
+      end
+
+      def collect_block_ids(formatted, role:, type:, id_key:, id_str_key:) # rubocop:disable Metrics/CyclomaticComplexity -- iterates blocks with type+role guards
+        ids = Set.new
         formatted.each do |msg|
-          next unless msg[:role] == 'user' && msg[:content].is_a?(Array)
+          next unless msg[:role] == role && msg[:content].is_a?(Array)
 
           msg[:content].each do |block|
-            if block.is_a?(Hash) && (block[:type] == 'tool_result' || block['type'] == 'tool_result')
-              tool_result_ids << (block[:tool_use_id] || block['tool_use_id'])
-            end
-          end
-        end
-
-        # Find orphans
-        orphaned = tool_use_ids - tool_result_ids
-        return formatted if orphaned.empty?
+            next unless block.is_a?(Hash) && block_matches_type?(block, type)
 
-        # Inject synthetic tool_results for orphans
-        orphan_results = orphaned.map do |id|
-          { type: 'tool_result', tool_use_id: id, content: '[interrupted]', is_error: true }
+            ids << (block[id_key] || block[id_str_key])
+          end
         end
+        ids
+      end
 
-        # Append as a user message after the last assistant message
-        formatted << { role: 'user', content: orphan_results }
-        formatted
+      def block_matches_type?(block, type)
+        block[:type] == type || block['type'] == type
       end
 
       # Normalize content and tool_calls into a single array of content blocks.
       def normalize_content(content, tool_calls)
-        blocks = []
+        blocks = content_to_blocks(content)
+        tool_calls.each { |tc| blocks << block_to_hash(tc) }
+        blocks
+      end
 
+      def content_to_blocks(content)
         case content
-        when Array
-          content.each { |b| blocks << block_to_hash(b) }
-        when String
-          blocks << { type: 'text', text: content } unless content.empty?
-        when Hash
-          blocks << content
-        else
-          blocks << block_to_hash(content) if content.respond_to?(:type)
+        when Array  then content.map { |b| block_to_hash(b) }
+        when String then content.empty? ? [] : [{ type: 'text', text: content }]
+        when Hash   then [content]
+        else content.respond_to?(:type) ? [block_to_hash(content)] : []
         end
-
-        tool_calls.each do |tc|
-          blocks << block_to_hash(tc)
-        end
-
-        blocks
       end
 
       # Format message content for the API. Converts Data objects to hashes.
@@ -200,25 +194,30 @@ module RubynCode
 
       def block_to_hash(block)
         return block if block.is_a?(Hash)
+        return block unless block.respond_to?(:type)
 
-        if block.respond_to?(:type)
-          case block.type.to_s
-          when 'text'
-            { type: 'text', text: block.text }
-          when 'tool_use'
-            { type: 'tool_use', id: block.id, name: block.name, input: block.input }
-          when 'tool_result'
-            h = { type: 'tool_result', tool_use_id: block.tool_use_id, content: block.content.to_s }
-            h[:is_error] = true if block.respond_to?(:is_error) && block.is_error
-            h
-          else
-            block.respond_to?(:to_h) ? block.to_h : block
-          end
+        typed_block_to_hash(block)
+      end
+
+      def typed_block_to_hash(block)
+        case block.type.to_s
+        when 'text'
+          { type: 'text', text: block.text }
+        when 'tool_use'
+          { type: 'tool_use', id: block.id, name: block.name, input: block.input }
+        when 'tool_result'
+          tool_result_block_to_hash(block)
         else
-          block
+          block.respond_to?(:to_h) ? block.to_h : block
         end
       end
 
+      def tool_result_block_to_hash(block)
+        h = { type: 'tool_result', tool_use_id: block.tool_use_id, content: block.content.to_s }
+        h[:is_error] = true if block.respond_to?(:is_error) && block.is_error
+        h
+      end
+
       # Extract text from content blocks.
       def extract_text(content)
         case content

data/lib/rubyn_code/agent/dynamic_tool_schema.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module RubynCode
+  module Agent
+    # Filters tool schemas sent to the LLM based on detected task context.
+    # Instead of sending all 28+ tool schemas on every call, only include
+    # tools relevant to the current task. This reduces per-turn system
+    # prompt overhead by 30-50%.
+    module DynamicToolSchema
+      BASE_TOOLS = %w[
+        read_file write_file edit_file glob grep bash
+      ].freeze
+
+      TASK_TOOLS = {
+        testing: %w[run_specs].freeze,
+        git: %w[git_status git_diff git_log git_commit].freeze,
+        review: %w[review_pr git_diff].freeze,
+        explore: %w[spawn_agent].freeze,
+        web: %w[web_search web_fetch].freeze,
+        memory: %w[memory_search memory_write].freeze,
+        skills: %w[load_skill].freeze,
+        tasks: %w[task].freeze,
+        teams: %w[spawn_teammate send_message read_inbox].freeze,
+        rails: %w[rails_generate db_migrate bundle_install bundle_add].freeze,
+        background: %w[background_run].freeze,
+        interaction: %w[ask_user compact].freeze
+      }.freeze
+
+      class << self
+        # Returns tool names relevant to the detected task context.
+        #
+        # @param task_context [Symbol, nil] detected task type
+        # @param discovered_tools [Set<String>] tools already discovered this session
+        # @return [Array<String>] tool names to include in the schema
+        def active_tools(task_context: nil, discovered_tools: Set.new)
+          tools = BASE_TOOLS.dup
+
+          # Always include interaction tools
+          tools.concat(TASK_TOOLS[:interaction])
+          tools.concat(TASK_TOOLS[:memory])
+
+          # Add task-specific tools
+          if task_context
+            context_tools = resolve_context_tools(task_context)
+            tools.concat(context_tools)
+          end
+
+          # Always include previously discovered tools
+          tools.concat(discovered_tools.to_a)
+
+          tools.uniq
+        end
+
+        # Detect task context from a user message.
+        #
+        # @param message [String]
+        # @return [Symbol, nil]
+        def detect_context(message) # rubocop:disable Metrics/CyclomaticComplexity -- context detection dispatch
+          msg = message.to_s.downcase
+          return :testing if msg.match?(/\b(test|spec|rspec)\b/)
+          return :git     if msg.match?(/\b(commit|push|diff|branch|merge|git)\b/)
+          return :review  if msg.match?(/\b(review|pr|pull request)\b/)
+          return :rails   if msg.match?(/\b(migrate|generate|scaffold|rails)\b/)
+          return :web     if msg.match?(/\b(search|fetch|url|http|api)\b/)
+          return :explore if msg.match?(/\b(explore|architecture|structure)\b/)
+          return :teams   if msg.match?(/\b(team|spawn|message|inbox)\b/)
+
+          nil
+        end
+
+        # Filter full tool definitions to only include active tools.
+        #
+        # @param all_definitions [Array<Hash>] full tool schema list
+        # @param active_names [Array<String>] names of active tools
+        # @return [Array<Hash>] filtered definitions
+        def filter(all_definitions, active_names:)
+          name_set = active_names.to_set
+          all_definitions.select do |defn|
+            name = defn[:name] || defn['name']
+            name_set.include?(name)
+          end
+        end
+
+        private
+
+        def resolve_context_tools(context)
+          case context
+          when Symbol
+            TASK_TOOLS.fetch(context, [])
+          when Array
+            context.flat_map { |c| TASK_TOOLS.fetch(c, []) }
+          else
+            []
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubyn_code/agent/feedback_handler.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module RubynCode
+  module Agent
+    # Detects positive/negative user feedback and reinforces learned instincts.
+    module FeedbackHandler
+      POSITIVE_PATTERNS =
+        /\b(yes that fixed it|that worked|perfect|thanks|exactly|great|nailed it|that.s right|correct)\b/i
+      NEGATIVE_PATTERNS =
+        /\b(no[, ]+use|wrong|that.s not right|instead use|don.t do that|actually[, ]+use|incorrect)\b/i
+
+      private
+
+      def check_user_feedback(user_input)
+        return unless @project_root
+
+        recent_instincts = fetch_recent_instincts
+        return if recent_instincts.empty?
+
+        reinforce_instincts(user_input, recent_instincts)
+      rescue StandardError
+        # Non-critical; don't interrupt the conversation
+      end
+
+      def fetch_recent_instincts
+        db = DB::Connection.instance
+        db.query(
+          'SELECT id FROM instincts WHERE project_path = ? ORDER BY updated_at DESC LIMIT 5',
+          [@project_root]
+        ).to_a
+      end
+
+      def reinforce_instincts(user_input, recent_instincts)
+        if user_input.match?(POSITIVE_PATTERNS)
+          reinforce_top(recent_instincts, helpful: true)
+        elsif user_input.match?(NEGATIVE_PATTERNS)
+          reinforce_top(recent_instincts, helpful: false)
+        end
+      end
+
+      def reinforce_top(instincts, helpful:)
+        db = DB::Connection.instance
+        instincts.first(2).each do |row|
+          Learning::InstinctMethods.reinforce_in_db(row['id'], db, helpful: helpful)
+        end
+      end
+    end
+  end
+end

data/lib/rubyn_code/agent/llm_caller.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module RubynCode
+  module Agent
+    # Handles LLM chat calls, option building, prompt-too-long recovery,
+    # and maintenance tasks (compaction, budget, stall detection).
+    module LlmCaller # rubocop:disable Metrics/ModuleLength -- LLM call pipeline with routing + recovery
+      private
+
+      def call_llm
+        @hook_runner.fire(:pre_llm_call, conversation: @conversation)
+
+        opts = build_llm_opts
+        log_llm_call(opts)
+        response = @llm_client.chat(**opts)
+
+        @hook_runner.fire(:post_llm_call, response: response, conversation: @conversation)
+        track_usage(response)
+        update_task_budget(response)
+        response
+      rescue LLM::Client::PromptTooLongError
+        recover_prompt_too_long(opts)
+      end
+
+      def build_llm_opts
+        opts = {
+          messages: @conversation.to_api_format,
+          tools: @plan_mode ? read_only_tool_definitions : tool_definitions,
+          system: build_system_prompt,
+          on_text: @on_text
+        }
+        opts[:max_tokens] = @max_tokens_override if @max_tokens_override
+        opts[:model] = routed_model
+        if @task_budget_remaining
+          opts[:task_budget] = {
+            total: UsageTracker::TASK_BUDGET_TOTAL, remaining: @task_budget_remaining
+          }
+        end
+        opts
+      end
+
+      # Uses ModelRouter to pick the right model for the current task.
+      # Only returns models from the active provider — never crosses
+      # provider boundaries (e.g., won't send a GPT model to Anthropic).
+      # Falls back to nil (use client's default) if routing fails.
+      def routed_model
+        last_user = last_user_message_text
+        return nil unless last_user
+
+        recent = @stall_detector.respond_to?(:recent_tools) ? @stall_detector.recent_tools : []
+        task = LLM::ModelRouter.detect_task(last_user, recent_tools: recent)
+        resolved = LLM::ModelRouter.resolve(task, client: @llm_client)
+
+        # Only use the routed model if it's from the same provider
+        active = @llm_client.respond_to?(:provider_name) ? @llm_client.provider_name : nil
+        return nil if active && resolved[:provider] != active
+
+        resolved[:model]
+      rescue StandardError
+        nil
+      end
+
+      def last_user_message_text
+        msg = @conversation.messages.reverse_each.find { |m| m[:role] == 'user' }
+        return nil unless msg
+
+        content = msg[:content]
+        content.is_a?(String) ? content : nil
+      end
+
+      def log_llm_call(opts) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- safe accessor checks
+        default_model = @llm_client.respond_to?(:model) ? @llm_client.model : 'default'
+        routed = opts[:model]
+        effective = routed || default_model
+        provider = @llm_client.respond_to?(:provider_name) ? @llm_client.provider_name : 'unknown'
+        tool_count = opts[:tools]&.size || 0
+        routed_tag = routed && routed != default_model ? " (routed from #{default_model})" : ''
+        RubynCode::Debug.llm("chat provider=#{provider} model=#{effective}#{routed_tag} tools=#{tool_count}")
+      rescue StandardError
+        nil
+      end
+
+      def recover_prompt_too_long(opts)
+        RubynCode::Debug.recovery(
+          '413 prompt too long — running emergency compaction'
+        )
+        @context_manager.check_compaction!(@conversation)
+
+        response = @llm_client.chat(**opts, messages: @conversation.to_api_format)
+        @hook_runner.fire(
+          :post_llm_call, response: response, conversation: @conversation
+        )
+        track_usage(response)
+        response
+      end
+
+      # ── Maintenance ──────────────────────────────────────────────────
+
+      def run_maintenance(_iteration)
+        run_compaction
+        check_budget
+        check_stall_detection
+      end
+
+      def run_compaction
+        before = @conversation.length
+        est = @context_manager.estimated_tokens(@conversation.messages)
+        RubynCode::Debug.token(
+          "context=#{est} tokens (~#{before} messages, " \
+          "threshold=#{Config::Defaults::CONTEXT_THRESHOLD_TOKENS})"
+        )
+
+        @context_manager.check_compaction!(@conversation)
+        log_compaction(before, est)
+      rescue NoMethodError
+        # context_manager does not implement check_compaction! yet
+      end
+
+      def log_compaction(before, est)
+        after = @conversation.length
+        return unless after < before
+
+        new_est = @context_manager.estimated_tokens(@conversation.messages)
+        RubynCode::Debug.loop_tick(
+          "Compacted: #{before} -> #{after} messages " \
+          "(#{est} -> #{new_est} tokens)"
+        )
+      end
+
+      def check_budget
+        return unless @budget_enforcer
+
+        @budget_enforcer.check!
+      rescue BudgetExceededError
+        raise
+      rescue NoMethodError
+        # budget_enforcer does not implement check! yet
+      end
+
+      def check_stall_detection
+        return unless @stall_detector.stalled?
+
+        nudge = @stall_detector.nudge_message
+        @conversation.add_user_message(nudge)
+        @stall_detector.reset!
+      end
+    end
+  end
+end