brute 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d81acc813055cd8621c71b3d1c444b9c39cf9c316b0e4b41eddab60a3f27f85a
+  data.tar.gz: 746bd2d574c6203e80153d0c747e55cecff746b5aa61ae1b38c9471aaee8feef
+SHA512:
+  metadata.gz: c18662ee0a25508ebd7df4015454b4b6e77eb7fa7e5a3f69fe2b9b1e64a8f0392fd1478cde5e5f310c85e1a683302346cc0528cb20beab80705029331ed7e4e7
+  data.tar.gz: 60047800ecee00b2c959ca9f12385540b2be949ebfffa3f16312dc534a0342a82e5bebe0227228461e2fcba634a76a38df7d3c70bcada0c40a3be37f82c156c0

data/lib/brute/agent_stream.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Brute
+  # Bridges llm.rb's streaming callbacks to forge-rb's callback system.
+  #
+  # Text and reasoning chunks fire immediately as the LLM generates them.
+  # Tool calls spawn threads on arrival — tools start running while the
+  # response is still streaming. on_tool_result fires as each thread finishes.
+  #
+  class AgentStream < LLM::Stream
+    def initialize(on_content: nil, on_reasoning: nil, on_tool_call: nil, on_tool_result: nil)
+      @on_content = on_content
+      @on_reasoning = on_reasoning
+      @on_tool_call = on_tool_call
+      @on_tool_result = on_tool_result
+    end
+
+    def on_content(text)
+      @on_content&.call(text)
+    end
+
+    def on_reasoning_content(text)
+      @on_reasoning&.call(text)
+    end
+
+    def on_tool_call(tool, error)
+      @on_tool_call&.call(tool.name, tool.arguments)
+
+      if error
+        queue << error
+        @on_tool_result&.call(tool.name, error.value)
+      else
+        queue << LLM::Function::Task.new(spawn_with_callback(tool))
+      end
+    end
+
+    private
+
+    def spawn_with_callback(tool)
+      on_result = @on_tool_result
+      name = tool.name
+      Thread.new do
+        result = tool.call
+        on_result&.call(name, result.respond_to?(:value) ? result.value : result)
+        result
+      end
+    end
+  end
+end

data/lib/brute/compactor.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Brute
+  # Context compaction service. When the conversation grows past configurable
+  # thresholds, older messages are summarized into a condensed form and the
+  # original messages are dropped, keeping the context window manageable.
+  #
+  # Modeled after forgecode's Compactor which uses an eviction window and
+  # retention window strategy.
+  class Compactor
+    DEFAULTS = {
+      token_threshold: 100_000,   # Compact when estimated tokens exceed this
+      message_threshold: 200,     # Compact when message count exceeds this
+      retention_window: 6,        # Minimum recent messages to always keep
+      summary_model: nil,         # Model for summarization (uses agent's model if nil)
+    }.freeze
+
+    attr_reader :config
+
+    def initialize(provider, **opts)
+      @provider = provider
+      @config = DEFAULTS.merge(opts)
+    end
+
+    # Check whether compaction should run based on current context state.
+    def should_compact?(messages, usage: nil)
+      return true if messages.size > @config[:message_threshold]
+      return true if usage && (usage.total_tokens || 0) > @config[:token_threshold]
+      false
+    end
+
+    # Compact the message history by summarizing older messages.
+    #
+    # Returns [summary_message, kept_messages] — the caller rebuilds
+    # the context from these.
+    def compact(messages)
+      total = messages.size
+      keep_count = [@config[:retention_window], total].min
+      return nil if total <= keep_count
+
+      old_messages = messages[0...(total - keep_count)]
+      recent_messages = messages[(total - keep_count)..]
+
+      summary_text = summarize(old_messages)
+
+      [summary_text, recent_messages]
+    end
+
+    private
+
+    def summarize(messages)
+      # Build a condensed representation of the conversation for the summarizer
+      conversation_text = messages.map { |m|
+        role = if m.respond_to?(:role)
+          m.role.to_s
+        else
+          "unknown"
+        end
+        content = if m.respond_to?(:content)
+          m.content.to_s[0..1000]
+        else
+          m.to_s[0..1000]
+        end
+
+        # Include tool call info for assistant messages
+        tool_info = ""
+        if m.respond_to?(:functions) && m.functions&.any?
+          calls = m.functions.map { |f| "#{f.name}(#{f.arguments.to_s[0..200]})" }
+          tool_info = " [tools: #{calls.join(", ")}]"
+        end
+
+        "#{role}:#{tool_info} #{content}"
+      }.join("\n---\n")
+
+      prompt = <<~PROMPT
+        Summarize this conversation history for context continuity. The summary will replace
+        these messages in the context window, so include everything the agent needs to continue
+        working effectively.
+
+        Structure your summary as:
+        ## Goal
+        What the user asked for.
+
+        ## Progress
+        - Files read, created, or modified (list paths)
+        - Commands executed and their outcomes
+        - Key decisions made
+
+        ## Current State
+        Where things stand right now — what's done and what remains.
+
+        ## Next Steps
+        What should happen next based on the conversation.
+
+        ---
+        CONVERSATION:
+        #{conversation_text}
+      PROMPT
+
+      model = @config[:summary_model] || "claude-sonnet-4-20250514"
+      res = @provider.complete(prompt, model: model)
+      res.content
+    end
+  end
+end

data/lib/brute/doom_loop.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Brute
+  # Detects when the agent is stuck in a repeating pattern of tool calls.
+  #
+  # Two types of loops are detected:
+  #   1. Consecutive identical calls: [A, A, A] — same tool + same args
+  #   2. Repeating sequences: [A,B,C, A,B,C, A,B,C] — a pattern cycling
+  #
+  # When detected, a warning is injected into the context so the LLM
+  # can course-correct.
+  class DoomLoopDetector
+    DEFAULT_THRESHOLD = 3
+
+    attr_reader :threshold
+
+    def initialize(threshold: DEFAULT_THRESHOLD)
+      @threshold = threshold
+    end
+
+    # Extracts tool call signatures from the context's message buffer and
+    # checks for repeating patterns at the tail.
+    #
+    # Returns the repetition count if a loop is found, nil otherwise.
+    def detect(messages)
+      signatures = extract_signatures(messages)
+      return nil if signatures.size < @threshold
+
+      check_repeating_pattern(signatures)
+    end
+
+    # Build a human-readable warning message for the agent.
+    def warning_message(repetitions)
+      <<~MSG
+        SYSTEM NOTICE: Doom loop detected — the same tool call pattern has repeated #{repetitions} times.
+        You are stuck in a loop and not making progress. Stop and try a fundamentally different approach:
+        - Re-read the file to check your changes actually applied
+        - Try a different tool or strategy
+        - Break the problem into smaller steps
+        - If a command keeps failing, investigate why before retrying
+      MSG
+    end
+
+    private
+
+    # Extract [tool_name, arguments_json] pairs from assistant messages.
+    def extract_signatures(messages)
+      messages
+        .select { |m| m.respond_to?(:functions) && m.assistant? }
+        .flat_map { |m| m.functions.map { |f| [f.name.to_s, f.arguments.to_s] } }
+    end
+
+    # Check for repeating patterns of any length at the tail of the sequence.
+    # Returns the repetition count, or nil.
+    def check_repeating_pattern(sequence)
+      max_pattern_len = sequence.size / @threshold
+
+      (1..max_pattern_len).each do |pattern_len|
+        count = count_tail_repetitions(sequence, pattern_len)
+        return count if count >= @threshold
+      end
+
+      nil
+    end
+
+    # Count how many times a pattern of `length` repeats at the end of the sequence.
+    def count_tail_repetitions(sequence, length)
+      return 0 if sequence.size < length
+
+      pattern = sequence.last(length)
+      count = 1
+      pos = sequence.size - length
+
+      while pos >= length
+        candidate = sequence[(pos - length)...pos]
+        break unless candidate == pattern
+        count += 1
+        pos -= length
+      end
+
+      count
+    end
+  end
+end

data/lib/brute/file_mutation_queue.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Brute
+  # Per-file serialization queue for concurrent tool execution.
+  #
+  # When tools run in parallel (via threads or async fibers), multiple tools
+  # may target the same file simultaneously. Without serialization, a sequence
+  # like [read → patch → write] on the same file would race and lose edits.
+  #
+  # This module provides a single public method:
+  #
+  #   Brute::FileMutationQueue.serialize("/path/to/file") do
+  #     # snapshot + read + modify + write — all atomic for this path
+  #   end
+  #
+  # Design (mirrors pi-mono's withFileMutationQueue):
+  #   - Operations on the SAME file are serialized (run one at a time)
+  #   - Operations on DIFFERENT files run fully in parallel (independent mutexes)
+  #   - Symlink-aware: resolves real paths so aliases share one mutex
+  #   - Error-safe: mutex is always released in `ensure`, so failures never deadlock
+  #   - Self-cleaning: per-file mutexes are removed when no longer in use
+  #
+  # Ruby 3.4's Mutex is fiber-scheduler-aware, so this works correctly with
+  # both :thread and :task (Async) concurrency strategies.
+  #
+  module FileMutationQueue
+    @mutexes = {}       # path → Mutex
+    @waiters = Hash.new(0) # path → number of threads/fibers waiting or holding
+    @guard = Mutex.new  # protects @mutexes and @waiters
+
+    class << self
+      # Serialize a block of work for a given file path.
+      #
+      # Concurrent calls targeting the same canonical path will execute
+      # sequentially in FIFO order. Calls targeting different paths
+      # proceed in parallel with zero contention.
+      #
+      # @param path [String] The file path to serialize on.
+      # @yield The mutation work to perform (snapshot, read, write, etc.)
+      # @return Whatever the block returns.
+      def serialize(path, &block)
+        key = canonical_path(path)
+        mutex = acquire_mutex(key)
+
+        mutex.synchronize(&block)
+      ensure
+        release_mutex(key)
+      end
+
+      # Clear all tracked mutexes. Used in tests and session resets.
+      def clear!
+        @guard.synchronize do
+          @mutexes.clear
+          @waiters.clear
+        end
+      end
+
+      # Number of file paths currently tracked (for diagnostics).
+      def size
+        @guard.synchronize { @mutexes.size }
+      end
+
+      private
+
+      # Resolve a file path to a canonical key.
+      # Uses File.realpath to follow symlinks so that aliases to the
+      # same underlying file share one mutex. Falls back to
+      # File.expand_path for files that don't exist yet (e.g., new writes).
+      def canonical_path(path)
+        resolved = File.expand_path(path)
+        begin
+          File.realpath(resolved)
+        rescue Errno::ENOENT
+          resolved
+        end
+      end
+
+      # Get (or create) a mutex for a file path and increment the waiter count.
+      def acquire_mutex(key)
+        @guard.synchronize do
+          @mutexes[key] ||= Mutex.new
+          @waiters[key] += 1
+          @mutexes[key]
+        end
+      end
+
+      # Decrement the waiter count and clean up the mutex if no one else needs it.
+      def release_mutex(key)
+        @guard.synchronize do
+          @waiters[key] -= 1
+          if @waiters[key] <= 0
+            @mutexes.delete(key)
+            @waiters.delete(key)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/brute/hooks.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Brute
+  # Lifecycle hook system modeled after forgecode's Hook struct.
+  #
+  # Six lifecycle events fire during the orchestrator loop:
+  #   :start           — conversation processing begins
+  #   :end             — conversation processing ends
+  #   :request         — before each LLM API call
+  #   :response        — after each LLM response
+  #   :toolcall_start  — before a tool executes
+  #   :toolcall_end    — after a tool executes
+  #
+  # Hooks receive (event_name, context_hash) and can inspect or mutate
+  # the orchestrator state via the context hash.
+  module Hooks
+    # Base class. Subclass and override #on_<event> methods.
+    class Base
+      def call(event, **data)
+        method_name = :"on_#{event}"
+        send(method_name, **data) if respond_to?(method_name, true)
+      end
+
+      private
+
+      def on_start(**) = nil
+      def on_end(**) = nil
+      def on_request(**) = nil
+      def on_response(**) = nil
+      def on_toolcall_start(**) = nil
+      def on_toolcall_end(**) = nil
+    end
+
+    # Composes multiple hooks into one, firing them in order.
+    class Composite < Base
+      def initialize(*hooks)
+        @hooks = hooks
+      end
+
+      def call(event, **data)
+        @hooks.each { |h| h.call(event, **data) }
+      end
+
+      def <<(hook)
+        @hooks << hook
+        self
+      end
+    end
+
+    # Logs lifecycle events to a logger.
+    class Logging < Base
+      def initialize(logger)
+        @logger = logger
+      end
+
+      private
+
+      def on_start(**)
+        @logger.info("[brute] Conversation started")
+      end
+
+      def on_end(**)
+        @logger.info("[brute] Conversation ended")
+      end
+
+      def on_request(request_count: 0, **)
+        @logger.debug("[brute] LLM request ##{request_count}")
+      end
+
+      def on_response(tokens: nil, **)
+        @logger.debug("[brute] LLM response (tokens: #{tokens || "?"})")
+      end
+
+      def on_toolcall_start(tool_name: nil, **)
+        @logger.info("[brute] Tool call: #{tool_name}")
+      end
+
+      def on_toolcall_end(tool_name: nil, error: false, **)
+        status = error ? "FAILED" : "ok"
+        @logger.info("[brute] Tool result: #{tool_name} [#{status}]")
+      end
+    end
+  end
+end

data/lib/brute/middleware/base.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Brute
+  module Middleware
+    # Base class for all middleware. Provides the standard Rack-style pattern:
+    #
+    #   def call(env)
+    #     # pre-processing
+    #     response = @app.call(env)
+    #     # post-processing
+    #     response
+    #   end
+    #
+    # Subclasses MUST call @app.call(env) unless they are intentionally
+    # short-circuiting (e.g., returning a cached response).
+    #
+    class Base
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        @app.call(env)
+      end
+    end
+  end
+end

data/lib/brute/middleware/compaction_check.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Brute
+  module Middleware
+    # Checks context size after each LLM call and triggers compaction
+    # when thresholds are exceeded.
+    #
+    # Runs POST-call: inspects message count and token usage from the
+    # response. If compaction is needed, summarizes older messages and
+    # rebuilds the context with the summary + recent messages.
+    #
+    class CompactionCheck < Base
+      def initialize(app, compactor:, system_prompt:, tools:)
+        super(app)
+        @compactor = compactor
+        @system_prompt = system_prompt
+        @tools = tools
+      end
+
+      def call(env)
+        response = @app.call(env)
+
+        ctx = env[:context]
+        messages = ctx.messages.to_a.compact
+        usage = ctx.usage rescue nil
+
+        if @compactor.should_compact?(messages, usage: usage)
+          result = @compactor.compact(messages)
+          if result
+            summary_text, _recent = result
+            rebuild_context!(env, summary_text)
+            env[:metadata][:compaction] = {
+              messages_before: messages.size,
+              timestamp: Time.now.iso8601,
+            }
+          end
+        end
+
+        response
+      end
+
+      private
+
+      def rebuild_context!(env, summary_text)
+        provider = env[:provider]
+        new_ctx = LLM::Context.new(provider, tools: @tools)
+        prompt = new_ctx.prompt do |p|
+          p.system @system_prompt
+          p.user "[Previous conversation summary]\n\n#{summary_text}"
+        end
+        new_ctx.talk(prompt)
+        env[:context] = new_ctx
+      end
+    end
+  end
+end

data/lib/brute/middleware/doom_loop_detection.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Brute
+  module Middleware
+    # Detects when the agent is stuck repeating tool call patterns and injects
+    # a corrective warning into the context before the next LLM call.
+    #
+    # Runs PRE-call: inspects the conversation history for repeating tool call
+    # patterns. If detected, talks a warning message into the context so the
+    # LLM sees it as input alongside the normal tool results.
+    #
+    class DoomLoopDetection < Base
+      def initialize(app, threshold: 3)
+        super(app)
+        @detector = Brute::DoomLoopDetector.new(threshold: threshold)
+      end
+
+      def call(env)
+        ctx = env[:context]
+        messages = ctx.messages.to_a
+
+        if (reps = @detector.detect(messages))
+          warning = @detector.warning_message(reps)
+          # Inject the warning as a user message so the LLM sees it
+          ctx.talk(warning)
+          env[:metadata][:doom_loop_detected] = reps
+        end
+
+        @app.call(env)
+      end
+    end
+  end
+end

data/lib/brute/middleware/llm_call.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Brute
+  module Middleware
+    # The terminal "app" in the pipeline — performs the actual LLM call.
+    #
+    # When streaming, on_content fires incrementally via AgentStream.
+    # When not streaming, fires on_content post-hoc with the full text.
+    #
+    class LLMCall
+      def call(env)
+        ctx = env[:context]
+        response = ctx.talk(env[:input])
+
+        # Only fire on_content post-hoc when NOT streaming
+        # (streaming delivers chunks incrementally via AgentStream)
+        unless env[:streaming]
+          if (cb = env.dig(:callbacks, :on_content)) && response
+            text = response.respond_to?(:content) ? response.content : nil
+            cb.call(text) if text
+          end
+        end
+
+        response
+      end
+    end
+  end
+end

data/lib/brute/middleware/reasoning_normalizer.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Brute
+  module Middleware
+    # Handles reasoning/thinking content across model switches.
+    #
+    # PRE-call:
+    #   - If reasoning is enabled, injects provider-specific params into
+    #     the env (e.g., Anthropic thinking config, OpenAI reasoning_effort).
+    #   - Tracks which model produced each message. When the model changes,
+    #     strips reasoning_content from messages produced by the old model
+    #     (signatures are model-specific and cryptographically tied).
+    #
+    # POST-call:
+    #   - Records the current model on the response for future normalization.
+    #
+    # llm.rb exposes:
+    #   - response.reasoning_content  — the thinking text
+    #   - response.reasoning_tokens   — token count
+    #   - Provider params pass-through — we can send thinking:, reasoning_effort:, etc.
+    #
+    class ReasoningNormalizer < Base
+      # Effort levels that map to provider-specific params.
+      # Mirrors forgecode's Effort enum.
+      EFFORT_LEVELS = {
+        none: "none",
+        minimal: "low",
+        low: "low",
+        medium: "medium",
+        high: "high",
+        xhigh: "high",
+        max: "high",
+      }.freeze
+
+      def initialize(app, model_id: nil, effort: :medium, enabled: true, budget_tokens: nil)
+        super(app)
+        @model_id = model_id
+        @effort = effort
+        @enabled = enabled
+        @budget_tokens = budget_tokens
+        @message_models = [] # tracks which model produced each assistant message
+      end
+
+      def call(env)
+        if @enabled
+          inject_reasoning_params!(env)
+        end
+
+        response = @app.call(env)
+
+        # POST: record which model produced this response
+        if response
+          @message_models << @model_id
+        end
+
+        response
+      end
+
+      # Update the active model (e.g., when user switches models mid-session).
+      def model_id=(new_model)
+        @model_id = new_model
+      end
+
+      private
+
+      def inject_reasoning_params!(env)
+        env[:params] ||= {}
+        provider = env[:provider]
+
+        case provider_type(provider)
+        when :anthropic
+          if @budget_tokens
+            # Older extended thinking API (claude-3.7-sonnet style)
+            env[:params][:thinking] = {type: "enabled", budget_tokens: @budget_tokens}
+          else
+            # Newer effort-based API (claude-4 style) — pass through
+            # Anthropic handles this via the model itself
+          end
+        when :openai
+          env[:params][:reasoning_effort] = EFFORT_LEVELS[@effort] || "medium"
+        end
+      end
+
+      def provider_type(provider)
+        class_name = provider.class.name.to_s.downcase
+        if class_name.include?("anthropic")
+          :anthropic
+        elsif class_name.include?("openai")
+          :openai
+        elsif class_name.include?("google") || class_name.include?("gemini")
+          :google
+        else
+          :unknown
+        end
+      end
+    end
+  end
+end