brute 1.0.0 → 2.0.0

data/lib/brute/loop/step.rb

@@ -1,332 +0,0 @@
-# frozen_string_literal: true
-
-require "bundler/setup"
-require "brute"
-
-require "securerandom"
-require "async"
-
-module Brute
-  module Loop
-  # A first-class work object with identity, state, result/error capture,
-  # optional sub-queue, and cancellation.
-  #
-  # Users subclass Step and override #perform(task). The framework calls
-  # #call(task) which owns the state machine — subclasses never touch
-  # state transitions directly.
-  #
-  # State machine:
-  #
-  #       ┌──> completed
-  #       │
-  #   pending ──> running ──┤
-  #       │                 │
-  #       │                 ├──> failed
-  #       │                 │
-  #       └──> cancelled    └──> cancelled
-  #
-  # Three terminal states. Two non-terminal. Once terminal, stays terminal.
-  #
-  class Step
-    STATES = %i[pending running completed failed cancelled].freeze
-
-    attr_reader :id
-
-    def initialize(id: nil, **attributes)
-      @id         = id || self.class.generate_id
-      @attributes = attributes
-      @state      = :pending
-      @result     = nil
-      @error      = nil
-      @task       = nil
-      @jobs       = nil
-      @mutex      = Mutex.new
-    end
-
-    def self.generate_id
-      "#{name}-#{Process.pid}-#{Thread.current.object_id}-#{SecureRandom.hex(4)}"
-    end
-
-    # Called by the queue's worker. Subclasses override #perform instead.
-    def call(task)
-      return unless transition_to_running(task)
-
-      begin
-        result = perform(task)
-        @mutex.synchronize do
-          @result = result
-          @state  = :completed
-          @task   = nil
-        end
-
-      rescue Async::Cancel
-        # Cascade to sub-queue before we lose the reference:
-        @jobs&.cancel
-        @mutex.synchronize do
-          @state = :cancelled
-          @task  = nil
-        end
-        raise
-
-      rescue => error
-        # Continue-on-failure: record the error, do NOT re-raise.
-        @mutex.synchronize do
-          @error = error
-          @state = :failed
-          @task  = nil
-        end
-      end
-    end
-
-    # Subclasses override this.
-    def perform(task)
-      raise "#{self.class}#perform not implemented"
-    end
-
-    # Lazy accessor — creates the sub-queue parented to our running task.
-    # Only valid while the step is running (inside #perform).
-    def jobs(type: Brute::Queue::SequentialQueue)
-      @mutex.synchronize do
-        raise "Step not running; sub-queue has nothing to parent to" unless @task
-        @jobs ||= type.new(parent: @task).start
-      end
-    end
-
-    def state
-      @mutex.synchronize { @state }
-    end
-
-    def result
-      @mutex.synchronize { @result }
-    end
-
-    def error
-      @mutex.synchronize { @error }
-    end
-
-    def status
-      @mutex.synchronize do
-        { id: @id, state: @state, result: @result, error: @error }
-      end
-    end
-
-    def cancel
-      task = @mutex.synchronize do
-        case @state
-        when :pending
-          @state = :cancelled
-          nil
-        when :running
-          @task
-        else
-          return false # already finished
-        end
-      end
-
-      task&.cancel
-      true
-    end
-
-    private
-
-    def transition_to_running(task)
-      @mutex.synchronize do
-        return false if @state == :cancelled
-        @state = :running
-        @task  = task
-        true
-      end
-    end
-  end
-  end
-end
-
-test do
-  class HelloStep < Brute::Loop::Step
-    def perform(task)
-      "hello"
-    end
-  end
-
-  class FailStep < Brute::Loop::Step
-    def perform(task)
-      raise "boom"
-    end
-  end
-
-  class SlowStep < Brute::Loop::Step
-    def perform(task)
-      sleep 10
-      "done"
-    end
-  end
-
-  # -- identity --
-
-  it "generates a unique id" do
-    HelloStep.new.id.should.be.kind_of String
-  end
-
-  it "accepts a custom id" do
-    HelloStep.new(id: "custom-1").id.should == "custom-1"
-  end
-
-  # -- initial state --
-
-  it "starts in pending state" do
-    HelloStep.new.state.should == :pending
-  end
-
-  it "starts with nil result" do
-    HelloStep.new.result.should.be.nil
-  end
-
-  it "starts with nil error" do
-    HelloStep.new.error.should.be.nil
-  end
-
-  # -- successful execution --
-
-  it "transitions to completed on success" do
-    Sync do
-      step = HelloStep.new
-      step.call(Async::Task.current)
-      step.state.should == :completed
-    end
-  end
-
-  it "captures the return value as result" do
-    Sync do
-      step = HelloStep.new
-      step.call(Async::Task.current)
-      step.result.should == "hello"
-    end
-  end
-
-  # -- failed execution --
-
-  it "transitions to failed on error" do
-    Sync do
-      step = FailStep.new
-      step.call(Async::Task.current)
-      step.state.should == :failed
-    end
-  end
-
-  it "captures the exception as error" do
-    Sync do
-      step = FailStep.new
-      step.call(Async::Task.current)
-      step.error.message.should == "boom"
-    end
-  end
-
-  it "does not re-raise on failure" do
-    Sync do
-      step = FailStep.new
-      lambda { step.call(Async::Task.current) }.should.not.raise
-    end
-  end
-
-  # -- cancellation of pending step --
-
-  it "cancel returns true for pending step" do
-    HelloStep.new.cancel.should.be.true
-  end
-
-  it "transitions pending step to cancelled" do
-    step = HelloStep.new
-    step.cancel
-    step.state.should == :cancelled
-  end
-
-  it "skips perform when cancelled before call" do
-    Sync do
-      step = HelloStep.new
-      step.cancel
-      step.call(Async::Task.current)
-      step.result.should.be.nil
-    end
-  end
-
-  # -- cancellation of finished step --
-
-  it "cancel returns false for completed step" do
-    Sync do
-      step = HelloStep.new
-      step.call(Async::Task.current)
-      step.cancel.should.be.false
-    end
-  end
-
-  it "cancel returns false for failed step" do
-    Sync do
-      step = FailStep.new
-      step.call(Async::Task.current)
-      step.cancel.should.be.false
-    end
-  end
-
-  # -- status --
-
-  it "status includes id" do
-    step = HelloStep.new(id: "s1")
-    step.status[:id].should == "s1"
-  end
-
-  it "status includes state" do
-    step = HelloStep.new
-    step.status[:state].should == :pending
-  end
-
-  # -- perform not implemented --
-
-  it "raises NotImplementedError for base Step" do
-    Sync do
-      step = Brute::Loop::Step.new
-      step.call(Async::Task.current)
-      step.state.should == :failed
-    end
-  end
-
-  # -- jobs raises when not running --
-
-  it "raises when accessing jobs outside perform" do
-    lambda { HelloStep.new.jobs(type: Array) }.should.raise(RuntimeError)
-  end
-
-  # -- attributes stored --
-
-  it "stores attributes" do
-    step = HelloStep.new(url: "https://example.com")
-    step.instance_variable_get(:@attributes)[:url].should == "https://example.com"
-  end
-
-  # -- nested sub-queue --
-
-  describe "nesting" do
-    class ParentStep < Brute::Loop::Step
-      def perform(task)
-        3.times { |i| jobs(type: Brute::Queue::SequentialQueue) << HelloStep.new(id: "child-#{i}") }
-        jobs.drain
-        jobs.steps.map(&:result)
-      end
-    end
-
-    it "creates a sub-queue inside perform" do
-      Sync do
-        step = ParentStep.new
-        step.call(Async::Task.current)
-        step.result.should == ["hello", "hello", "hello"]
-      end
-    end
-
-    it "sub-steps all complete" do
-      Sync do
-        step = ParentStep.new
-        step.call(Async::Task.current)
-        step.instance_variable_get(:@jobs).steps.all? { |s| s.state == :completed }.should.be.true
-      end
-    end
-  end
-end

data/lib/brute/loop/tool_call_step.rb

@@ -1,90 +0,0 @@
-# frozen_string_literal: true
-
-require "bundler/setup"
-require "brute"
-
-module Brute
-  module Loop
-  # A Step that wraps an LLM::Function tool call.
-  #
-  # Identity comes from the function's call ID so tool results
-  # can be correlated back to the LLM's request.
-  #
-  class ToolCallStep < Step
-    attr_reader :function
-
-    def initialize(function:, **rest)
-      super(id: function.id, **rest)
-      @function = function
-    end
-
-    def perform(task)
-      @function.call
-    end
-  end
-  end
-end
-
-test do
-  FakeFunction = Struct.new(:id, :name, :arguments, :return_value) do
-    def call
-      return_value
-    end
-  end
-
-  class FailFunction
-    attr_reader :id, :name, :arguments
-    def initialize
-      @id = "fail_1"
-      @name = "fail"
-      @arguments = {}
-    end
-    def call
-      raise "tool exploded"
-    end
-  end
-
-  it "uses function id as step id" do
-    fn = FakeFunction.new("call_123", "read", {}, "content")
-    Brute::Loop::ToolCallStep.new(function: fn).id.should == "call_123"
-  end
-
-  it "calls the function in perform" do
-    Sync do
-      fn = FakeFunction.new("call_1", "read", {}, "file contents")
-      step = Brute::Loop::ToolCallStep.new(function: fn)
-      step.call(Async::Task.current)
-      step.result.should == "file contents"
-    end
-  end
-
-  it "transitions to completed on success" do
-    Sync do
-      fn = FakeFunction.new("call_2", "write", {}, "ok")
-      step = Brute::Loop::ToolCallStep.new(function: fn)
-      step.call(Async::Task.current)
-      step.state.should == :completed
-    end
-  end
-
-  it "captures function as accessor" do
-    fn = FakeFunction.new("call_3", "shell", {}, nil)
-    Brute::Loop::ToolCallStep.new(function: fn).function.should.be.identical_to fn
-  end
-
-  it "transitions to failed when function raises" do
-    Sync do
-      step = Brute::Loop::ToolCallStep.new(function: FailFunction.new)
-      step.call(Async::Task.current)
-      step.state.should == :failed
-    end
-  end
-
-  it "captures function error" do
-    Sync do
-      step = Brute::Loop::ToolCallStep.new(function: FailFunction.new)
-      step.call(Async::Task.current)
-      step.error.message.should == "tool exploded"
-    end
-  end
-end

data/lib/brute/middleware/base.rb

@@ -1,27 +0,0 @@
-# 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

@@ -1,106 +0,0 @@
-# frozen_string_literal: true
-
-require "bundler/setup"
-require "brute"
-
-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. If compaction
-    # is needed, summarizes older messages and replaces env[:messages] with
-    # the summary so the next LLM call starts with a compact history.
-    #
-    class CompactionCheck < Base
-      def initialize(app, compactor:, system_prompt:)
-        super(app)
-        @compactor = compactor
-        @system_prompt = system_prompt
-      end
-
-      def call(env)
-        response = @app.call(env)
-
-        messages = env[:messages]
-        usage = env[:metadata].dig(:tokens, :last_call)
-
-        if @compactor.should_compact?(messages, usage: usage)
-          result = @compactor.compact(messages)
-          if result
-            summary_text, _recent = result
-            env[:metadata][:compaction] = {
-              messages_before: messages.size,
-              timestamp: Time.now.iso8601,
-            }
-            # Replace the message history with the summary
-            env[:messages] = [
-              LLM::Message.new(:system, @system_prompt),
-              LLM::Message.new(:user, "[Previous conversation summary]\n\n#{summary_text}"),
-            ]
-          end
-        end
-
-        response
-      end
-    end
-  end
-end
-
-test do
-  require_relative "../../../spec/support/mock_provider"
-  require_relative "../../../spec/support/mock_response"
-
-  def build_env(**overrides)
-    { provider: MockProvider.new, model: nil, input: "test prompt", tools: [],
-      messages: [], stream: nil, params: {}, metadata: {}, callbacks: {},
-      tool_results: nil, streaming: false, should_exit: nil, pending_functions: [] }.merge(overrides)
-  end
-
-  def make_compactor(should: false, result: nil)
-    Object.new.tap do |c|
-      c.define_singleton_method(:should_compact?) { |_msgs, **_| should }
-      c.define_singleton_method(:compact) { |_msgs| result }
-    end
-  end
-
-  it "passes the response through when compaction is not needed" do
-    response = MockResponse.new(content: "compaction response")
-    compactor = make_compactor(should: false)
-    middleware = Brute::Middleware::CompactionCheck.new(->(_env) { response }, compactor: compactor, system_prompt: "sys")
-    result = middleware.call(build_env)
-    result.should == response
-  end
-
-  it "does not set compaction metadata when not needed" do
-    compactor = make_compactor(should: false)
-    middleware = Brute::Middleware::CompactionCheck.new(->(_env) { MockResponse.new }, compactor: compactor, system_prompt: "sys")
-    env = build_env
-    middleware.call(env)
-    env[:metadata][:compaction].should.be.nil
-  end
-
-  it "replaces messages with summary when compaction triggers" do
-    compactor = make_compactor(should: true, result: ["Summary of conversation", []])
-    middleware = Brute::Middleware::CompactionCheck.new(->(_env) { MockResponse.new }, compactor: compactor, system_prompt: "sys")
-    env = build_env(messages: [LLM::Message.new(:user, "hello"), LLM::Message.new(:assistant, "hi"), LLM::Message.new(:user, "how")])
-    middleware.call(env)
-    env[:metadata][:compaction][:messages_before].should == 3
-  end
-
-  it "creates two messages after compaction" do
-    compactor = make_compactor(should: true, result: ["Summary", []])
-    middleware = Brute::Middleware::CompactionCheck.new(->(_env) { MockResponse.new }, compactor: compactor, system_prompt: "sys")
-    env = build_env(messages: [LLM::Message.new(:user, "hello")])
-    middleware.call(env)
-    env[:messages].size.should == 2
-  end
-
-  it "handles compactor returning nil gracefully" do
-    compactor = make_compactor(should: true, result: nil)
-    middleware = Brute::Middleware::CompactionCheck.new(->(_env) { MockResponse.new }, compactor: compactor, system_prompt: "sys")
-    env = build_env(messages: [LLM::Message.new(:user, "hello")])
-    middleware.call(env)
-    env[:metadata][:compaction].should.be.nil
-  end
-end

data/lib/brute/middleware/doom_loop_detection.rb

@@ -1,136 +0,0 @@
-# frozen_string_literal: true
-
-require "bundler/setup"
-require "brute"
-
-module Brute
-  module Middleware
-    # Detects when the agent is stuck repeating tool call patterns and injects
-    # a corrective warning into the message history before the next LLM call.
-    #
-    # Runs PRE-call: inspects the conversation history for repeating tool call
-    # patterns. If detected, appends a warning message so the LLM sees it as
-    # input alongside the normal tool results.
-    #
-    class DoomLoopDetection < Base
-      def initialize(app, threshold: 3)
-        super(app)
-        @detector = Brute::Loop::DoomLoopDetector.new(threshold: threshold)
-      end
-
-      def call(env)
-        messages = env[:messages]
-
-        if (reps = @detector.detect(messages))
-          warning = @detector.warning_message(reps)
-          # Inject the warning as a user message so the LLM sees it
-          env[:messages] << LLM::Message.new(:user, warning)
-          env[:metadata][:doom_loop_detected] = reps
-
-          # Signal the agent loop to exit after this LLM call completes.
-          # First-writer-wins: don't overwrite if another middleware already set it.
-          env[:should_exit] ||= {
-            reason:  "doom_loop_detected",
-            message: "Agent is stuck repeating the same tool calls (#{reps} repetitions).",
-            source:  "DoomLoopDetection",
-          }
-        end
-
-        @app.call(env)
-      end
-    end
-  end
-end
-
-test do
-  require_relative "../../../spec/support/mock_provider"
-  require_relative "../../../spec/support/mock_response"
-
-  def build_env(**overrides)
-    { provider: MockProvider.new, model: nil, input: "test prompt", tools: [],
-      messages: [], stream: nil, params: {}, metadata: {}, callbacks: {},
-      tool_results: nil, streaming: false, should_exit: nil, pending_functions: [] }.merge(overrides)
-  end
-
-  FakeFunc = Struct.new(:name, :arguments, keyword_init: true)
-
-  def assistant_msg_with_functions(function_list)
-    msg = LLM::Message.new(:assistant, "tool msg", {})
-    msg.define_singleton_method(:functions) { function_list }
-    msg
-  end
-
-  it "passes through when no doom loop is detected" do
-    inner_app = ->(_env) { MockResponse.new(content: "loop check") }
-    middleware = Brute::Middleware::DoomLoopDetection.new(inner_app, threshold: 3)
-    env = build_env
-    middleware.call(env)
-    env[:metadata][:doom_loop_detected].should.be.nil
-  end
-
-  it "detects consecutive identical tool calls" do
-    inner_app = ->(_env) { MockResponse.new(content: "loop check") }
-    fn = FakeFunc.new(name: "fs_read", arguments: '{"path":"x.rb"}')
-    messages = 4.times.map { assistant_msg_with_functions([fn]) }
-    middleware = Brute::Middleware::DoomLoopDetection.new(inner_app, threshold: 3)
-    env = build_env(messages: messages)
-    middleware.call(env)
-    env[:metadata][:doom_loop_detected].should.not.be.nil
-  end
-
-  it "does not trigger below the threshold" do
-    inner_app = ->(_env) { MockResponse.new(content: "loop check") }
-    fn = FakeFunc.new(name: "fs_read", arguments: '{"path":"x.rb"}')
-    messages = 2.times.map { assistant_msg_with_functions([fn]) }
-    middleware = Brute::Middleware::DoomLoopDetection.new(inner_app, threshold: 3)
-    env = build_env(messages: messages)
-    middleware.call(env)
-    env[:metadata][:doom_loop_detected].should.be.nil
-  end
-
-  it "sets should_exit reason when doom loop detected" do
-    inner_app = ->(_env) { MockResponse.new(content: "loop check") }
-    fn = FakeFunc.new(name: "fs_read", arguments: '{"path":"x.rb"}')
-    messages = 4.times.map { assistant_msg_with_functions([fn]) }
-    middleware = Brute::Middleware::DoomLoopDetection.new(inner_app, threshold: 3)
-    env = build_env(messages: messages)
-    middleware.call(env)
-    env[:should_exit][:reason].should == "doom_loop_detected"
-  end
-
-  it "does not set should_exit when no loop detected" do
-    inner_app = ->(_env) { MockResponse.new(content: "loop check") }
-    middleware = Brute::Middleware::DoomLoopDetection.new(inner_app, threshold: 3)
-    env = build_env
-    middleware.call(env)
-    env[:should_exit].should.be.nil
-  end
-
-  it "does not overwrite should_exit if already set" do
-    inner_app = ->(_env) { MockResponse.new(content: "loop check") }
-    fn = FakeFunc.new(name: "fs_read", arguments: '{"path":"x.rb"}')
-    messages = 4.times.map { assistant_msg_with_functions([fn]) }
-    middleware = Brute::Middleware::DoomLoopDetection.new(inner_app, threshold: 3)
-    existing = { reason: "other", message: "earlier", source: "Other" }
-    env = build_env(messages: messages, should_exit: existing)
-    middleware.call(env)
-    env[:should_exit][:reason].should == "other"
-  end
-
-  it "appends a warning message when loop detected" do
-    inner_app = ->(_env) { MockResponse.new(content: "loop check") }
-    fn = FakeFunc.new(name: "fs_read", arguments: '{"path":"x.rb"}')
-    messages = 4.times.map { assistant_msg_with_functions([fn]) }
-    middleware = Brute::Middleware::DoomLoopDetection.new(inner_app, threshold: 3)
-    env = build_env(messages: messages)
-    original_count = env[:messages].size
-    middleware.call(env)
-    env[:messages].size.should == original_count + 1
-  end
-
-  it "generates warning message with repetition count" do
-    detector = Brute::Loop::DoomLoopDetector.new(threshold: 3)
-    msg = detector.warning_message(5)
-    msg.should =~ /5 times/
-  end
-end