brute 0.1.0

data/lib/brute/middleware/retry.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Brute
+  module Middleware
+    # Retries the inner call on transient LLM errors with exponential backoff.
+    #
+    # Catches LLM::RateLimitError and LLM::ServerError, sleeps with
+    # exponential delay, and re-calls the inner app. Non-retryable errors
+    # propagate immediately.
+    #
+    # Unlike forgecode's separate retry.rs, this middleware wraps the LLM call
+    # directly — it sees the error and retries without the orchestrator knowing.
+    #
+    class Retry < Base
+      DEFAULT_MAX_ATTEMPTS = 3
+      DEFAULT_BASE_DELAY = 2 # seconds
+
+      def initialize(app, max_attempts: DEFAULT_MAX_ATTEMPTS, base_delay: DEFAULT_BASE_DELAY)
+        super(app)
+        @max_attempts = max_attempts
+        @base_delay = base_delay
+      end
+
+      def call(env)
+        attempts = 0
+        begin
+          @app.call(env)
+        rescue LLM::RateLimitError, LLM::ServerError => e
+          attempts += 1
+          if attempts >= @max_attempts
+            env[:metadata][:last_error] = e.message
+            raise
+          end
+
+          delay = @base_delay ** attempts
+          env[:metadata][:retry_attempt] = attempts
+          env[:metadata][:retry_delay] = delay
+
+          sleep(delay)
+          retry
+        end
+      end
+    end
+  end
+end

data/lib/brute/middleware/session_persistence.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Brute
+  module Middleware
+    # Saves the conversation to disk after each LLM call.
+    #
+    # Runs POST-call: delegates to Session#save. Failures are non-fatal —
+    # a broken session save should never crash the agent loop.
+    #
+    class SessionPersistence < Base
+      def initialize(app, session:)
+        super(app)
+        @session = session
+      end
+
+      def call(env)
+        response = @app.call(env)
+
+        begin
+          @session.save(env[:context])
+        rescue => e
+          warn "[brute] Session save failed: #{e.message}"
+        end
+
+        response
+      end
+    end
+  end
+end

data/lib/brute/middleware/token_tracking.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Brute
+  module Middleware
+    # Tracks cumulative token usage across all LLM calls in a session.
+    #
+    # Runs POST-call: reads usage from the response and accumulates totals
+    # in env[:metadata]. Also records per-call usage for the most recent call.
+    #
+    class TokenTracking < Base
+      def initialize(app)
+        super(app)
+        @total_input = 0
+        @total_output = 0
+        @total_reasoning = 0
+        @call_count = 0
+      end
+
+      def call(env)
+        response = @app.call(env)
+
+        if response.respond_to?(:usage) && (usage = response.usage)
+          @total_input += usage.input_tokens.to_i
+          @total_output += usage.output_tokens.to_i
+          @total_reasoning += usage.reasoning_tokens.to_i
+          @call_count += 1
+
+          env[:metadata][:tokens] = {
+            total_input: @total_input,
+            total_output: @total_output,
+            total_reasoning: @total_reasoning,
+            total: @total_input + @total_output,
+            call_count: @call_count,
+            last_call: {
+              input: usage.input_tokens.to_i,
+              output: usage.output_tokens.to_i,
+              total: usage.total_tokens.to_i,
+            },
+          }
+        end
+
+        response
+      end
+    end
+  end
+end

data/lib/brute/middleware/tool_error_tracking.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Brute
+  module Middleware
+    # Tracks per-tool error counts across LLM calls and signals when
+    # the error ceiling is reached.
+    #
+    # This middleware doesn't execute tools itself — it inspects the tool
+    # results that were sent as input to the LLM call (env[:tool_results])
+    # and counts failures.
+    #
+    # When any tool exceeds max_failures, it sets env[:metadata][:tool_error_limit_reached]
+    # so the orchestrator can decide to stop.
+    #
+    class ToolErrorTracking < Base
+      DEFAULT_MAX_FAILURES = 3
+
+      def initialize(app, max_failures: DEFAULT_MAX_FAILURES)
+        super(app)
+        @max_failures = max_failures
+        @errors = Hash.new(0) # tool_name → count
+      end
+
+      def call(env)
+        # PRE: count errors from tool results that are about to be sent
+        if (results = env[:tool_results])
+          results.each do |name, result|
+            if result.is_a?(Hash) && result[:error]
+              @errors[name] += 1
+            end
+          end
+        end
+
+        env[:metadata][:tool_errors] = @errors.dup
+        env[:metadata][:tool_error_limit_reached] = @errors.any? { |_, c| c >= @max_failures }
+
+        @app.call(env)
+      end
+
+      # Reset error counts (e.g., between user turns).
+      def reset!
+        @errors.clear
+      end
+    end
+  end
+end

data/lib/brute/middleware/tracing.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Brute
+  module Middleware
+    # Logs timing and token usage for every LLM call.
+    #
+    # Wraps the call with wall-clock timing. Logs:
+    #   PRE:  request number, message count
+    #   POST: elapsed time, token usage, finish reason
+    #
+    class Tracing < Base
+      def initialize(app, logger:)
+        super(app)
+        @logger = logger
+        @call_count = 0
+      end
+
+      def call(env)
+        @call_count += 1
+        messages = env[:context].messages.to_a
+        @logger.debug("[brute] LLM call ##{@call_count} (#{messages.size} messages in context)")
+
+        start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        response = @app.call(env)
+        elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
+
+        tokens = response.respond_to?(:usage) ? response.usage&.total_tokens : "?"
+        @logger.info("[brute] LLM response ##{@call_count}: #{tokens} tokens, #{elapsed.round(2)}s")
+
+        response
+      end
+    end
+  end
+end

data/lib/brute/orchestrator.rb

@@ -0,0 +1,297 @@
+# frozen_string_literal: true
+
+require "async"
+require "async/barrier"
+
+module Brute
+  # The core agent loop. Drives the cycle of:
+  #
+  #   prompt → LLM → tool calls → execute → send results → repeat
+  #
+  # All cross-cutting concerns (retry, compaction, doom loop detection,
+  # token tracking, session persistence, tracing, reasoning) are implemented
+  # as Rack-style middleware in the Pipeline. The orchestrator is now a
+  # thin loop that:
+  #
+  #   1. Sends input through the pipeline (which wraps the LLM call)
+  #   2. Executes any tool calls the LLM requested
+  #   3. Repeats until done or a limit is hit
+  #
+  class Orchestrator
+    MAX_REQUESTS_PER_TURN = 100
+
+    attr_reader :context, :session, :pipeline, :env, :barrier
+
+    def initialize(
+      provider:,
+      tools: Brute::TOOLS,
+      cwd: Dir.pwd,
+      session: nil,
+      compactor_opts: {},
+      reasoning: {},
+      on_content: nil,
+      on_reasoning: nil,
+      on_tool_call: nil,
+      on_tool_result: nil,
+      logger: nil
+    )
+      @provider = provider
+      @tool_classes = tools
+      @cwd = cwd
+      @session = session || Session.new
+      @logger = logger || Logger.new($stderr, level: Logger::INFO)
+
+      # Build system prompt
+      custom_rules = load_custom_rules
+      prompt_builder = SystemPrompt.new(cwd: @cwd, tools: @tool_classes, custom_rules: custom_rules)
+      @system_prompt = prompt_builder.build
+
+      # Initialize the LLM context (with streaming when callbacks provided)
+      @stream = if on_content || on_reasoning
+        AgentStream.new(
+          on_content: on_content,
+          on_reasoning: on_reasoning,
+          on_tool_call: on_tool_call,
+          on_tool_result: on_tool_result,
+        )
+      end
+      @context = LLM::Context.new(@provider, tools: @tool_classes,
+        **(@stream ? {stream: @stream} : {}))
+
+      # Build the middleware pipeline
+      compactor = Compactor.new(provider, **compactor_opts)
+      @pipeline = build_pipeline(
+        compactor: compactor,
+        session: @session,
+        logger: @logger,
+        reasoning: reasoning,
+      )
+
+      # The shared env hash — passed to every pipeline.call()
+      @env = {
+        context: @context,
+        provider: @provider,
+        tools: @tool_classes,
+        input: nil,
+        params: {},
+        metadata: {},
+        tool_results: nil,
+        streaming: !!@stream,
+        callbacks: {
+          on_content: on_content,
+          on_reasoning: on_reasoning,
+          on_tool_call: on_tool_call,
+          on_tool_result: on_tool_result,
+        },
+      }
+    end
+
+    # Run a single user turn. Loops internally until the agent either
+    # completes (no more tool calls) or hits a limit.
+    #
+    # Returns the final assistant response.
+    def run(user_message)
+      @request_count = 0
+
+      # Build the initial prompt with system message on first turn
+      input = if first_turn?
+        @context.prompt do |p|
+          p.system @system_prompt
+          p.user user_message
+        end
+      else
+        user_message
+      end
+
+      # --- First LLM call ---
+      @env[:input] = input
+      @env[:tool_results] = nil
+      last_response = @pipeline.call(@env)
+      sync_context!
+
+      # --- Agent loop ---
+      loop do
+        break if @context.functions.empty?
+
+        # Collect tool results.
+        # Streaming: tools already spawned threads during the LLM response — just join them.
+        # Non-streaming: execute manually (parallel or sequential).
+        results = if @stream && !@stream.queue.empty?
+          @context.wait(:thread)
+        else
+          execute_tool_calls
+        end
+
+        # Send results back through the pipeline
+        @env[:input] = results
+        @env[:tool_results] = extract_tool_result_pairs(results)
+        last_response = @pipeline.call(@env)
+        sync_context!
+
+        @request_count += 1
+
+        # Check limits
+        break if @context.functions.empty?
+        break if @request_count >= MAX_REQUESTS_PER_TURN
+        break if @env[:metadata][:tool_error_limit_reached]
+      end
+
+      last_response
+    end
+
+    private
+
+    # ------------------------------------------------------------------
+    # Pipeline construction
+    # ------------------------------------------------------------------
+
+    def build_pipeline(compactor:, session:, logger:, reasoning:)
+      sys_prompt = @system_prompt
+      tools = @tool_classes
+
+      Pipeline.new do
+        # Outermost: timing and logging (sees total elapsed including retries)
+        use Middleware::Tracing, logger: logger
+
+        # Retry transient errors (wraps everything below)
+        use Middleware::Retry
+
+        # Save after each successful LLM call
+        use Middleware::SessionPersistence, session: session
+
+        # Track cumulative token usage
+        use Middleware::TokenTracking
+
+        # Check context size and compact if needed
+        use Middleware::CompactionCheck,
+          compactor: compactor,
+          system_prompt: sys_prompt,
+          tools: tools
+
+        # Track per-tool errors
+        use Middleware::ToolErrorTracking
+
+        # Detect and break doom loops (pre-call)
+        use Middleware::DoomLoopDetection
+
+        # Handle reasoning params and model-switch normalization (pre-call)
+        use Middleware::ReasoningNormalizer, **reasoning unless reasoning.empty?
+
+        # Innermost: the actual LLM call
+        run Middleware::LLMCall.new
+      end
+    end
+
+    # ------------------------------------------------------------------
+    # Tool execution
+    # ------------------------------------------------------------------
+
+    def execute_tool_calls
+      pending = @context.functions.to_a
+      return execute_sequential(pending) if pending.size <= 1
+
+      execute_parallel(pending)
+    end
+
+    # Run a single tool call synchronously.
+    def execute_sequential(functions)
+      on_call = @env.dig(:callbacks, :on_tool_call)
+      on_result = @env.dig(:callbacks, :on_tool_result)
+
+      functions.map do |fn|
+        on_call&.call(fn.name, fn.arguments)
+        result = fn.call
+        on_result&.call(fn.name, result_value(result))
+        result
+      end
+    end
+
+    # Run all pending tool calls concurrently via Async::Barrier.
+    #
+    # Each tool runs in its own fiber. File-mutating tools are safe because
+    # they go through FileMutationQueue, whose Mutex is fiber-scheduler-aware
+    # in Ruby 3.4 — a fiber blocked on a per-file mutex yields to other
+    # fibers instead of blocking the thread.
+    #
+    # The barrier is stored in @barrier so abort! can cancel in-flight tools.
+    #
+    def execute_parallel(functions)
+      on_call = @env.dig(:callbacks, :on_tool_call)
+      on_result = @env.dig(:callbacks, :on_tool_result)
+
+      results = Array.new(functions.size)
+
+      Async do
+        @barrier = Async::Barrier.new
+
+        functions.each_with_index do |fn, i|
+          @barrier.async do
+            on_call&.call(fn.name, fn.arguments)
+            results[i] = fn.call
+            r = results[i]
+            on_result&.call(r.name, result_value(r))
+          end
+        end
+
+        @barrier.wait
+      ensure
+        @barrier&.stop
+        @barrier = nil
+      end
+
+      results
+    end
+
+    public
+
+    # Cancel any in-flight tool execution. Safe to call from a signal
+    # handler, another thread, or an interface layer (TUI, web, RPC).
+    #
+    # When called, Async::Stop is raised in each running fiber, unwinding
+    # through ensure blocks — so FileMutationQueue mutexes release cleanly
+    # and SnapshotStore stays consistent.
+    #
+    def abort!
+      @barrier&.stop
+    end
+
+    private
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    # After a pipeline call, the compaction middleware may have replaced
+    # the context. Sync our local reference.
+    def sync_context!
+      @context = @env[:context]
+    end
+
+    def first_turn?
+      @context.messages.to_a.empty?
+    end
+
+    def result_value(result)
+      result.respond_to?(:value) ? result.value : result
+    end
+
+    # Build [name, value] pairs from tool results for ToolErrorTracking.
+    def extract_tool_result_pairs(results)
+      results.filter_map do |r|
+        name = r.respond_to?(:name) ? r.name : "unknown"
+        val = result_value(r)
+        [name, val]
+      end
+    end
+
+    # Load AGENTS.md or .brute/rules from the working directory.
+    def load_custom_rules
+      candidates = [
+        File.join(@cwd, "AGENTS.md"),
+        File.join(@cwd, ".brute", "rules.md"),
+      ]
+      found = candidates.find { |p| File.exist?(p) }
+      found ? File.read(found) : nil
+    end
+  end
+end

data/lib/brute/patches/anthropic_tool_role.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# Monkey-patch: Fix Anthropic tool result message role.
+#
+# llm.rb stores tool results as messages with role="tool" (via @llm.tool_role).
+# Anthropic's API requires tool result messages to have role="user" with
+# tool_result content blocks. The Completion adapter already correctly formats
+# the content (Function::Return -> {type: "tool_result", ...}), but passes
+# through the "tool" role unchanged — which Anthropic rejects.
+#
+# This patch overrides adapt_message to set role="user" when the message
+# content contains tool returns.
+
+module Brute
+  module Patches
+    module AnthropicToolRole
+      private
+
+      def adapt_message
+        if message.respond_to?(:role) && message.role.to_s == "tool"
+          {role: "user", content: adapt_content(content)}
+        else
+          super
+        end
+      end
+
+      # Apply the patch lazily — LLM::Anthropic is autoloaded.
+      def self.apply!
+        return if @applied
+        @applied = true
+        LLM::Anthropic::RequestAdapter::Completion.prepend(self)
+      end
+    end
+  end
+end

data/lib/brute/patches/buffer_nil_guard.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Monkey-patch: Guard LLM::Buffer against nil entries.
+#
+# llm.rb's Context#talk can sometimes concatenate nil into the message
+# buffer (e.g. when response parsing yields a nil choice). This causes
+# NoMethodError when the buffer is iterated (assistant?, tool_return?, etc).
+#
+# This patch overrides concat to filter out nils before they enter the buffer.
+
+module Brute
+  module Patches
+    module BufferNilGuard
+      def concat(messages)
+        super(Array(messages).compact)
+      end
+    end
+  end
+end
+
+LLM::Buffer.prepend(Brute::Patches::BufferNilGuard)

data/lib/brute/pipeline.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Brute
+  # Rack-style middleware pipeline for LLM calls.
+  #
+  # Each middleware wraps the next, forming an onion model:
+  #
+  #   Tracing → Retry → DoomLoop → Reasoning → [LLM Call] → Reasoning → DoomLoop → Retry → Tracing
+  #
+  # The innermost "app" is the actual LLM call. Each middleware can:
+  #   - Modify the env (context, params) BEFORE the call   (pre-processing)
+  #   - Modify or inspect the response AFTER the call       (post-processing)
+  #   - Short-circuit (return without calling inner app)
+  #   - Retry (call inner app multiple times)
+  #
+  # ## The env hash
+  #
+  #   {
+  #     context:   LLM::Context,     # conversation state
+  #     provider:  LLM::Provider,    # the LLM provider
+  #     input:     <prompt/results>,  # what to pass to context.talk()
+  #     tools:     [Tool, ...],       # tool classes
+  #     params:    {},                # extra LLM call params (reasoning config, etc.)
+  #     metadata:  {},                # shared scratchpad for middleware state
+  #     callbacks: {},                # :on_content, :on_tool_call, :on_tool_result
+  #   }
+  #
+  # ## The response
+  #
+  #   The return value of call(env) is the LLM::Message from context.talk().
+  #
+  # ## Building a pipeline
+  #
+  #   pipeline = Brute::Pipeline.new do
+  #     use Brute::Middleware::Tracing, logger: logger
+  #     use Brute::Middleware::Retry, max_attempts: 3
+  #     use Brute::Middleware::SessionPersistence, session: session
+  #     run Brute::Middleware::LLMCall.new
+  #   end
+  #
+  #   response = pipeline.call(env)
+  #
+  class Pipeline
+    def initialize(&block)
+      @middlewares = []
+      @app = nil
+      instance_eval(&block) if block
+    end
+
+    # Register a middleware class.
+    # The class must implement `initialize(app, *args, **kwargs)` and `call(env)`.
+    def use(klass, *args, **kwargs, &block)
+      @middlewares << [klass, args, kwargs, block]
+      self
+    end
+
+    # Set the terminal app (innermost handler).
+    def run(app)
+      @app = app
+      self
+    end
+
+    # Build the full middleware chain and call it.
+    def call(env)
+      build.call(env)
+    end
+
+    # Build the chain without calling it. Useful for inspection or caching.
+    def build
+      raise "Pipeline has no terminal app — call `run` first" unless @app
+
+      @middlewares.reverse.inject(@app) do |inner, (klass, args, kwargs, block)|
+        if block
+          klass.new(inner, *args, **kwargs, &block)
+        else
+          klass.new(inner, *args, **kwargs)
+        end
+      end
+    end
+  end
+end