brute 2.0.6 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ca9915157a21335990328dcbf4b6104cffa72bd0835e93055ec46e8be05aee7
-  data.tar.gz: 6e7ef36a7fd32e0351563856d888f832fb4d48fad32444f937fb58c2d45baa4d
+  metadata.gz: d6308c538c9efce1d554894738361f1f07720730b3fc66aa46df9f57e2599ae4
+  data.tar.gz: 9bc51c1b3020b601bacbab282874f8a789b1420b84a9649c58f6e75c83b4b7b5
 SHA512:
-  metadata.gz: ff22892e28c30deb694b7bbea899e8b14ceb31e068fa74b27b9b462d7778ab52da06f332f743ac6c19324bf962d7ee1401e8146f1714496fc1dcba5179f6e551
-  data.tar.gz: 457fbacd0115628b002c6b274ef7c07d47a267c4841107c52c4d983d23a0967012ca68a084b50f833d5421ff013766c2aef07be5e465d8630ca61cc9c06326f5
+  metadata.gz: b7f0b0ab4859d81bdc9885824bca9baf68600ff880f4b804652e10882caf3d2449235f18490d9338ab1e4bce29cc641d8b776bd9a777dc7fd98a3bb8b9b81c94
+  data.tar.gz: 53301d50213d626fa6f7ba7e1bb0b1124aa3b4b48485302f176681eabf8d0839d493231416c1f0274f29fd5690754b8a48d6751d83f6a32cbc58a9a59f5fa1c9

data/lib/brute/events/handler.rb

@@ -25,6 +25,8 @@ module Brute
   end
 end
 
-test do
+__END__
+
+describe "brute/events/handler" do
   # not implemented
 end

data/lib/brute/events/prefixed_terminal_output.rb

@@ -67,6 +67,8 @@ module Brute
   end
 end
 
-test do
+__END__
+
+describe "brute/events/prefixed_terminal_output" do
   # not implemented
 end

data/lib/brute/events/terminal_output_handler.rb

@@ -63,6 +63,8 @@ module Brute
   end
 end
 
-test do
+__END__
+
+describe "brute/events/terminal_output_handler" do
   # not implemented
 end

data/lib/brute/messages.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+
+module Brute
+  # The in-memory conversation log is just a plain Array of RubyLLM::Message.
+  # This module adds a little sugar for appending role-tagged messages; mix it
+  # into an array via `Brute.log`. Persistence is NOT here — loading/saving the
+  # log to disk is the Brute::Middleware::SessionLog middleware's job.
+  module Messages
+    def user(content);      self << ::RubyLLM::Message.new(role: :user,      content: content); end
+    def assistant(content); self << ::RubyLLM::Message.new(role: :assistant, content: content); end
+    def system(content);    self << ::RubyLLM::Message.new(role: :system,    content: content); end
+  end
+
+  # Build a fresh conversation log (an Array + Messages sugar), optionally
+  # seeded with messages.
+  #
+  #   log = Brute.log
+  #   log.user("hello")
+  #   Brute.log(RubyLLM::Message.new(role: :user, content: "hi"))
+  def self.log(*messages)
+    [].extend(Messages).tap { |log| messages.flatten.each { |m| log << m } }
+  end
+end
+
+__END__
+
+describe "brute/messages" do
+  it "appends role-tagged messages" do
+    log = Brute.log
+    log.user("hi")
+    log.assistant("hello")
+    log.map(&:role).should == [:user, :assistant]
+    log.first.content.should == "hi"
+  end
+
+  it "seeds from given messages" do
+    m = RubyLLM::Message.new(role: :user, content: "seed")
+    Brute.log(m).should == [m]
+  end
+
+  it "is a plain Array (no special class)" do
+    Brute.log.should.be.kind_of?(Array)
+  end
+end

data/lib/brute/middleware/001_otel_span.rb

@@ -18,7 +18,7 @@ module Brute
     #   use Brute::Middleware::OTel::ToolCalls
     #   use Brute::Middleware::OTel::TokenUsage
     #   # ... existing middleware ...
-    #   run Brute::Middleware::LLMCall.new
+    #   run ->(env) { ... }   # inline LLM call proc (see Brute.agent)
     #
     class OtelSpan
       def initialize(app)
@@ -72,6 +72,8 @@ module Brute
   end
 end
 
-test do
+__END__
+
+describe "brute/middleware/001_otel_span" do
   # not implemented
 end

data/lib/brute/middleware/002_session_log.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+require "json"
+require "fileutils"
+
+module Brute
+  module Middleware
+    # The "session" is just a JSONL log of the conversation on disk. This
+    # middleware owns that log — there is no Session class.
+    #
+    #   in  -> if the file exists, prepend its messages to env[:messages] so
+    #          this turn continues the prior conversation.
+    #   out <- write the log back to disk (skipping the :system message, which
+    #          the SystemPrompt middleware re-adds each turn).
+    #
+    # Put it near the top of the stack (outermost) so history is loaded before
+    # the rest of the middleware runs and the whole turn is persisted after:
+    #
+    #   Brute.agent
+    #     .use(Brute::Middleware::SessionLog, path: "tmp/session.jsonl")
+    #     .use(Brute::Middleware::SystemPrompt)
+    #     ...
+    #
+    class SessionLog
+      def initialize(app, path:)
+        @app  = app
+        @path = path
+      end
+
+      def call(env)
+        load_into(env[:messages]) if @path && File.exist?(@path)
+        @app.call(env)
+        persist(env[:messages]) if @path
+        env
+      end
+
+      private
+
+        def load_into(messages)
+          loaded = []
+          File.foreach(@path) do |line|
+            line = line.strip
+            loaded << ::RubyLLM::Message.new(**JSON.parse(line, symbolize_names: true)) unless line.empty?
+          end
+          messages.unshift(*loaded)
+        end
+
+        def persist(messages)
+          FileUtils.mkdir_p(File.dirname(@path))
+          File.open(@path, "w") do |f|
+            messages.each do |message|
+              next if message.role == :system
+
+              f.puts(JSON.generate(message.to_h))
+            end
+          end
+        end
+    end
+  end
+end
+
+__END__
+
+describe "brute/middleware/002_session_log" do
+  require "brute/messages"
+  require "tmpdir"
+
+  it "persists the log and reloads it on the next turn" do
+    Dir.mktmpdir do |dir|
+      path = File.join(dir, "session.jsonl")
+
+      # Turn 1: no file yet; terminal appends an assistant reply.
+      turn = ->(env) { env[:messages].assistant("first reply") }
+      Brute::Middleware::SessionLog.new(turn, path: path).call(
+        { messages: Brute.log.tap { |l| l.user("hi") } }
+      )
+
+      File.exist?(path).should.be.true
+
+      # Turn 2: fresh log with a new user message; history is prepended.
+      env = { messages: Brute.log.tap { |l| l.user("again") } }
+      Brute::Middleware::SessionLog.new(->(e) { }, path: path).call(env)
+
+      env[:messages].map(&:content).should == ["hi", "first reply", "again"]
+    end
+  end
+
+  it "does not persist the system message" do
+    Dir.mktmpdir do |dir|
+      path = File.join(dir, "s.jsonl")
+      env = { messages: Brute.log.tap { |l| l.system("secret prompt"); l.user("hi") } }
+      Brute::Middleware::SessionLog.new(->(e) { }, path: path).call(env)
+
+      reloaded = File.readlines(path).map(&:strip).reject(&:empty?)
+      reloaded.any? { |line| line.include?("secret prompt") }.should.be.false
+    end
+  end
+end

data/lib/brute/middleware/004_summarize.rb

@@ -5,10 +5,10 @@ require "brute"
 
 module Brute
   module Middleware
-    # Runs a final tool-free LLM call after the ToolResultLoop completes,
+    # Runs a final tool-free LLM call after the Loop::ToolResult completes,
     # ensuring the agent produces a clean summary response.
     #
-    # This middleware sits above ToolResultLoop in the stack. After the tool
+    # This middleware sits above Loop::ToolResult in the stack. After the tool
     # loop finishes (either naturally or via MaxIterations), Summarize
     # injects a summary prompt and calls the inner stack one more time
     # with tools removed. The LLM responds with text only, giving the
@@ -17,10 +17,10 @@ module Brute
     # Stack order:
     #
     #   use Summarize
-    #   use ToolResultLoop
+    #   use Loop::ToolResult
     #   use MaxIterations
-    #   use ToolCall
-    #   run LLMCall.new
+    #   use ToolPipeline
+    #   run ->(env) { ... }   # inline LLM call proc (see Brute.agent)
     #
     class Summarize
       DEFAULT_PROMPT = "Provide your complete findings based on everything you've explored."
@@ -46,8 +46,10 @@ module Brute
   end
 end
 
-test do
-  require "brute/session"
+__END__
+
+describe "brute/middleware/004_summarize" do
+  require "brute/messages"
 
   it "produces a final assistant message after tool loop" do
     call_count = 0
@@ -64,7 +66,7 @@ test do
     end
 
     mw = Brute::Middleware::Summarize.new(inner)
-    session = Brute::Session.new
+    session = Brute.log
     session.user("explore the codebase")
     env = { messages: session, tools: [:some_tool], current_iteration: 5 }
     mw.call(env)
@@ -80,7 +82,7 @@ test do
 
     mw = Brute::Middleware::Summarize.new(inner)
     tools = [:read, :search]
-    env = { messages: Brute::Session.new, tools: tools.dup, current_iteration: 1 }
+    env = { messages: Brute.log, tools: tools.dup, current_iteration: 1 }
     env[:messages].user("hi")
     mw.call(env)
 
@@ -95,7 +97,7 @@ test do
     }
 
     mw = Brute::Middleware::Summarize.new(inner)
-    env = { messages: Brute::Session.new, tools: [], current_iteration: 99 }
+    env = { messages: Brute.log, tools: [], current_iteration: 99 }
     env[:messages].user("hi")
     mw.call(env)
 
@@ -113,7 +115,7 @@ test do
     }
 
     mw = Brute::Middleware::Summarize.new(inner)
-    env = { messages: Brute::Session.new, tools: [], current_iteration: 1 }
+    env = { messages: Brute.log, tools: [], current_iteration: 1 }
     env[:messages].user("hi")
     mw.call(env)
 
@@ -130,7 +132,7 @@ test do
     }
 
     mw = Brute::Middleware::Summarize.new(inner, prompt: "Give me the TL;DR.")
-    env = { messages: Brute::Session.new, tools: [], current_iteration: 1 }
+    env = { messages: Brute.log, tools: [], current_iteration: 1 }
     env[:messages].user("hi")
     mw.call(env)
 

data/lib/brute/middleware/006_loop.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+
+module Brute
+  module Middleware
+    # Re-invokes the inner stack as long as a condition holds — a generic loop
+    # over a turn. The condition is a proc or block that receives env and
+    # returns truthy to send control back down the chain again, falsy to stop.
+    #
+    # The inner app always runs at least once; the condition is checked after
+    # each pass (do-while).
+    #
+    #   # loop while the last message is a tool result (see Loop::ToolResult):
+    #   use Brute::Middleware::Loop, ->(env) { env[:messages].last&.role == :tool }
+    #
+    #   # block form — e.g. bump an iteration counter and stop on should_exit:
+    #   use Brute::Middleware::Loop do |env|
+    #     env[:current_iteration] += 1
+    #     !env[:should_exit] && env[:messages].last&.role == :tool
+    #   end
+    #
+    class Loop
+      def initialize(app, condition = nil, &block)
+        @app       = app
+        @condition = condition || block
+        unless @condition.respond_to?(:call)
+          raise ArgumentError, "Brute::Middleware::Loop requires a proc or block condition"
+        end
+      end
+
+      def call(env)
+        loop do
+          @app.call(env)
+          break unless @condition.call(env)
+        end
+        env
+      end
+
+      # Loops while the LLM keeps producing tool results — the standard agentic
+      # turn loop. After the inner stack runs (the LLM-call proc responds,
+      # ToolPipeline executes tools and appends :tool messages), it loops when
+      # the last message is a tool result, bumping the iteration counter. It
+      # stops when the LLM answers with text only or env[:should_exit] is set
+      # (e.g. by MaxIterations).
+      #
+      #   use Brute::Middleware::Loop::ToolResult
+      #
+      class ToolResult < Loop
+        CONDITION = lambda do |env|
+          next false if env[:should_exit]
+          next false unless env[:messages].last&.role == :tool
+
+          env[:current_iteration] += 1
+          true
+        end
+
+        def initialize(app)
+          super(app, CONDITION)
+        end
+      end
+    end
+  end
+end
+
+__END__
+
+describe "brute/middleware/006_loop" do
+  require "brute/messages"
+
+  it "runs the inner app once when the condition is immediately false" do
+    calls = 0
+    mw = Brute::Middleware::Loop.new(->(_env) { calls += 1 }, ->(_env) { false })
+    mw.call({})
+    calls.should == 1
+  end
+
+  it "loops while the condition is truthy" do
+    calls = 0
+    mw = Brute::Middleware::Loop.new(->(_env) { calls += 1 }, ->(_env) { calls < 3 })
+    mw.call({})
+    calls.should == 3
+  end
+
+  it "accepts a block condition and passes env to it" do
+    seen = []
+    mw = Brute::Middleware::Loop.new(->(env) { env[:n] += 1 }) { |env| seen << env[:n]; env[:n] < 2 }
+    env = { n: 0 }
+    mw.call(env)
+    env[:n].should == 2
+    seen.should == [1, 2]
+  end
+
+  it "returns env" do
+    env = { a: 1 }
+    Brute::Middleware::Loop.new(->(_e) {}, ->(_e) { false }).call(env).should == env
+  end
+
+  it "raises without a proc or block" do
+    lambda { Brute::Middleware::Loop.new(->(_e) {}) }.should.raise(ArgumentError)
+  end
+
+  # --- Loop::ToolResult (reimplements the old ToolResultLoop) ---
+
+  it "ToolResult loops until the last message is not a tool result" do
+    call_count = 0
+    inner = ->(env) do
+      call_count += 1
+      if call_count == 1
+        env[:messages] << RubyLLM::Message.new(role: :tool, content: "result", tool_call_id: "tc1")
+      else
+        env[:messages] << RubyLLM::Message.new(role: :assistant, content: "done")
+      end
+    end
+
+    mw = Brute::Middleware::Loop::ToolResult.new(inner)
+    env = { messages: Brute.log, current_iteration: 1 }
+    env[:messages].user("hi")
+    mw.call(env)
+
+    call_count.should == 2
+    env[:current_iteration].should == 2
+    env[:messages].last.role.should == :assistant
+  end
+
+  it "ToolResult stops when should_exit is set" do
+    call_count = 0
+    inner = ->(env) do
+      call_count += 1
+      env[:messages] << RubyLLM::Message.new(role: :tool, content: "result", tool_call_id: "tc#{call_count}")
+      env[:should_exit] = { reason: "max" } if call_count >= 2
+    end
+
+    mw = Brute::Middleware::Loop::ToolResult.new(inner)
+    env = { messages: Brute.log, current_iteration: 1 }
+    env[:messages].user("hi")
+    mw.call(env)
+
+    call_count.should == 2
+  end
+
+  it "ToolResult does not loop when last message is assistant" do
+    call_count = 0
+    inner = ->(env) do
+      call_count += 1
+      env[:messages] << RubyLLM::Message.new(role: :assistant, content: "hello")
+    end
+
+    mw = Brute::Middleware::Loop::ToolResult.new(inner)
+    env = { messages: Brute.log, current_iteration: 1 }
+    env[:messages].user("hi")
+    mw.call(env)
+
+    call_count.should == 1
+    env[:current_iteration].should == 1
+  end
+end

data/lib/brute/middleware/010_max_iterations.rb

@@ -9,7 +9,7 @@ module Brute
     #
     # When the limit is reached, injects a user message into the session
     # stating that maximum iterations have been reached. This causes
-    # ToolResultLoop to exit its loop naturally (last message is not :tool).
+    # Loop::ToolResult to exit its loop naturally (last message is not :tool).
     #
     class MaxIterations
 
@@ -40,14 +40,16 @@ module Brute
   end
 end
 
-test do
-  require "brute/session"
+__END__
+
+describe "brute/middleware/010_max_iterations" do
+  require "brute/messages"
 
   it "can be added to a stack" do
     called = false
     inner = ->(env) { called = true }
     mw = Brute::Middleware::MaxIterations.new(inner)
-    mw.call({ current_iteration: 1, messages: Brute::Session.new })
+    mw.call({ current_iteration: 1, messages: Brute.log })
     called.should.be.true
   end
 
@@ -55,7 +57,7 @@ test do
     called = false
     inner = ->(env) { called = true }
     mw = Brute::Middleware::MaxIterations.new(inner, max_iterations: 0)
-    env = { current_iteration: 1, messages: Brute::Session.new }
+    env = { current_iteration: 1, messages: Brute.log }
     mw.call(env)
     called.should.be.false
   end
@@ -63,7 +65,7 @@ test do
   it "injects a user message when max is hit" do
     inner = ->(env) { }
     mw = Brute::Middleware::MaxIterations.new(inner, max_iterations: 0)
-    session = Brute::Session.new
+    session = Brute.log
     session.user("hi")
     env = { current_iteration: 1, messages: session }
     mw.call(env)

data/lib/brute/middleware/015_otel_token_usage.rb

@@ -37,6 +37,8 @@ module Brute
   end
 end
 
-test do
+__END__
+
+describe "brute/middleware/015_otel_token_usage" do
   # not implemented
 end

data/lib/brute/middleware/020_system_prompt.rb

@@ -58,15 +58,17 @@ module Brute
   end
 end
 
-test do
-  require "brute/session"
+__END__
+
+describe "brute/middleware/020_system_prompt" do
+  require "brute/messages"
 
   def build_middleware(system_prompt: Brute::SystemPrompt.default, &inner_block)
     inner = inner_block || ->(env) { env }
     Brute::Middleware::SystemPrompt.new(inner, system_prompt: system_prompt)
   end
 
-  def base_env(messages: Brute::Session.new)
+  def base_env(messages: Brute.log)
     {
       messages: messages,
       provider: :anthropic,

data/lib/brute/middleware/040_compaction_check.rb

@@ -150,6 +150,8 @@ module Brute
   end
 end
 
-test do
+__END__
+
+describe "brute/middleware/040_compaction_check" do
   # not implemented
 end

data/lib/brute/middleware/060_questions.rb

@@ -17,6 +17,8 @@ module Brute
   end
 end
 
-test do
+__END__
+
+describe "brute/middleware/060_questions" do
   # not implemented
 end

data/lib/brute/middleware/{070_tool_call.rb → 070_tool_pipeline.rb}

@@ -54,16 +54,21 @@ module Brute
     #   one fiber runs at a time within a Sync block). No mutex needed.
     #
     # - FileMutationQueue compatibility — tools that mutate files use
-    #   Brute::Queue::FileMutationQueue.serialize, which uses Ruby 3.4's
+    #   Brute::Tools::FS::FileMutationQueue.serialize, which uses Ruby 3.4's
     #   fiber-scheduler-aware Mutex. Operations on the same file are serialized;
     #   operations on different files proceed in parallel.
     #
-    class ToolCall
-      def initialize(app)
-        @app = app
+    class ToolPipeline
+      def initialize(app, tools: [])
+        @app   = app
+        @tools = tools
       end
 
+      # in  -> advertise the tools to the turn (env[:tools], which the LLM-call
+      #        proc reads to tell the model what it can call)
+      # out <- execute the tool calls the model made and append :tool results
       def call(env)
+        env[:tools] = @tools
         @app.call(env)
 
         tools_to_run = pending_tool_calls(env[:messages].last)
@@ -126,11 +131,7 @@ module Brute
         end
 
         def resolve_tools(tools)
-          tools.each_with_object({}) do |tool, hash|
-            instance = tool.is_a?(Class) ? tool.new : tool
-            instance = instance.to_ruby_llm if instance.respond_to?(:to_ruby_llm)
-            hash[instance.name.to_sym] = instance
-          end
+          Brute::Tools::Adapter.wrap_all(tools)
         end
 
         def on_tool_call_start_event(pending_tools)
@@ -149,18 +150,19 @@ module Brute
   end
 end
 
-test do
-  require "brute/session"
+__END__
+
+describe "brute/middleware/070_tool_pipeline" do
+  require "brute/messages"
   require "brute/truncation"
 
   it "passes through when no tool calls pending" do
     inner = ->(env) {
       env[:messages] << RubyLLM::Message.new(role: :assistant, content: "hi")
     }
-    mw = Brute::Middleware::ToolCall.new(inner)
+    mw = Brute::Middleware::ToolPipeline.new(inner, tools: [])
     env = {
-      messages: Brute::Session.new,
-      tools: [],
+      messages: Brute.log,
       events: [],
     }
     env[:messages].user("hello")
@@ -168,6 +170,17 @@ test do
     env[:messages].last.content.should == "hi"
   end
 
+  it "advertises its tools on env[:tools] on the way in" do
+    seen = nil
+    inner = ->(env) { seen = env[:tools] }
+    tool = { name: "echo", description: "", execute: ->(**) { "ok" } }
+    mw = Brute::Middleware::ToolPipeline.new(inner, tools: [tool])
+    env = { messages: Brute.log, events: [] }
+    env[:messages].user("hi")
+    mw.call(env)
+    seen.should == [tool]
+  end
+
   # --- Universal output truncation ---
 
   it "truncates large tool results via Truncation" do
@@ -193,10 +206,9 @@ test do
     inner = ->(env) {
       env[:messages] << RubyLLM::Message.new(role: :assistant, content: "", tool_calls: tool_calls)
     }
-    mw = Brute::Middleware::ToolCall.new(inner)
+    mw = Brute::Middleware::ToolPipeline.new(inner, tools: [big_tool])
     env = {
-      messages: Brute::Session.new,
-      tools: [big_tool],
+      messages: Brute.log,
       events: [],
     }
     env[:messages].user("hello")
@@ -232,10 +244,9 @@ test do
     inner = ->(env) {
       env[:messages] << RubyLLM::Message.new(role: :assistant, content: "", tool_calls: tool_calls)
     }
-    mw = Brute::Middleware::ToolCall.new(inner)
+    mw = Brute::Middleware::ToolPipeline.new(inner, tools: [pre_truncated_tool])
     env = {
-      messages: Brute::Session.new,
-      tools: [pre_truncated_tool],
+      messages: Brute.log,
       events: [],
     }
     env[:messages].user("hello")

data/lib/brute/middleware/073_otel_tool_call.rb

@@ -44,6 +44,8 @@ module Brute
   end
 end
 
-test do
+__END__
+
+describe "brute/middleware/073_otel_tool_call" do
   # not implemented
 end

data/lib/brute/middleware/075_otel_tool_results.rb

@@ -41,6 +41,8 @@ module Brute
   end
 end
 
-test do
+__END__
+
+describe "brute/middleware/075_otel_tool_results" do
   # not implemented
 end