brute 2.0.6 → 3.0.1

data/lib/brute/messages.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+
+module Brute
+  # One tool invocation requested by the model. Arguments are always a Hash.
+  ToolCall = Data.define(:id, :name, :arguments) do
+    def initialize(id:, name:, arguments: {})
+      super(id: id, name: name.to_s, arguments: arguments.to_h)
+    end
+  end
+
+  # Brute's canonical, framework-agnostic message. The rest of the stack
+  # (middleware, tool loop, persistence) never calls anything beyond
+  # #role, #content, #tool_calls, #tool_call_id and #to_h — so any object
+  # that duck-types those methods can ride in env[:messages] too. This Data
+  # class is simply the canonical implementation.
+  #
+  #   Brute::Message.new(role: :user, content: "hi")
+  #   Brute::Message.new(role: :assistant, content: "", tool_calls: [
+  #     Brute::ToolCall.new(id: "tc1", name: "shell", arguments: { "command" => "ls" }),
+  #   ])
+  #   Brute::Message.new(role: :tool, content: "result", tool_call_id: "tc1")
+  Message = Data.define(:role, :content, :tool_calls, :tool_call_id) do
+    def initialize(role:, content: nil, tool_calls: nil, tool_call_id: nil)
+      tool_calls = tool_calls&.map do |tc|
+        tc.is_a?(ToolCall) ? tc : ToolCall.new(**tc.to_h.transform_keys(&:to_sym))
+      end
+      super(role: role.to_sym, content: content, tool_calls: tool_calls, tool_call_id: tool_call_id)
+    end
+
+    def tool_call?
+      !tool_calls.nil? && !tool_calls.empty?
+    end
+
+    # Plain, JSON-ready view (nils dropped, tool calls as hashes).
+    def to_h
+      h = super
+      h[:tool_calls] = tool_calls.map(&:to_h) if tool_calls
+      h.compact
+    end
+  end
+
+  # The in-memory conversation log is just a plain Array of Brute::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 << Message.new(role: :user,      content: content); end
+    def assistant(content); self << Message.new(role: :assistant, content: content); end
+    def system(content);    self << Message.new(role: :system,    content: content); end
+
+    def tool(content, tool_call_id:)
+      self << Message.new(role: :tool, content: content, tool_call_id: tool_call_id)
+    end
+  end
+
+  # Build a fresh conversation log (an Array + Messages sugar), optionally
+  # seeded with messages.
+  #
+  #   log = Brute.log
+  #   log.user("hello")
+  #   Brute.log(Brute::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 "appends tool results" do
+    log = Brute.log
+    log.tool("result", tool_call_id: "tc1")
+    log.last.role.should == :tool
+    log.last.tool_call_id.should == "tc1"
+  end
+
+  it "seeds from given messages" do
+    m = Brute::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
+
+  it "symbolizes string roles" do
+    Brute::Message.new(role: "user", content: "hi").role.should == :user
+  end
+
+  it "coerces tool_calls hashes into ToolCall" do
+    m = Brute::Message.new(
+      role: :assistant, content: "",
+      tool_calls: [{ "id" => "tc1", "name" => "shell", "arguments" => { "command" => "ls" } }]
+    )
+    m.tool_calls.first.name.should == "shell"
+    m.tool_calls.first.arguments.should == { "command" => "ls" }
+    m.tool_call?.should.be.true
+  end
+
+  it "round-trips through to_h" do
+    m = Brute::Message.new(role: :assistant, content: "",
+                           tool_calls: [{ id: "tc1", name: "shell", arguments: {} }])
+    Brute::Message.new(**m.to_h).should == m
+  end
+
+  it "to_h drops nil fields" do
+    Brute::Message.new(role: :user, content: "hi").to_h.should == { role: :user, content: "hi" }
+  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 << Brute::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."
@@ -36,7 +36,7 @@ module Brute
         saved_tools = env[:tools]
         env[:tools] = []
         env[:current_iteration] = 1
-        env[:messages] << RubyLLM::Message.new(role: :user, content: @prompt)
+        env[:messages] << Brute::Message.new(role: :user, content: @prompt)
         @app.call(env)
         env[:tools] = saved_tools
 
@@ -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
@@ -57,14 +59,14 @@ test do
     inner = ->(env) do
       call_count += 1
       if call_count == 1
-        env[:messages] << RubyLLM::Message.new(role: :tool, content: "some result", tool_call_id: "tc1")
+        env[:messages] << Brute::Message.new(role: :tool, content: "some result", tool_call_id: "tc1")
       else
-        env[:messages] << RubyLLM::Message.new(role: :assistant, content: "Here is my complete summary.")
+        env[:messages] << Brute::Message.new(role: :assistant, content: "Here is my complete summary.")
       end
     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)
@@ -75,12 +77,12 @@ test do
 
   it "restores tools after summary call" do
     inner = ->(env) {
-      env[:messages] << RubyLLM::Message.new(role: :assistant, content: "done")
+      env[:messages] << Brute::Message.new(role: :assistant, content: "done")
     }
 
     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)
 
@@ -91,11 +93,11 @@ test do
     captured_iteration = nil
     inner = ->(env) {
       captured_iteration = env[:current_iteration]
-      env[:messages] << RubyLLM::Message.new(role: :assistant, content: "done")
+      env[:messages] << Brute::Message.new(role: :assistant, content: "done")
     }
 
     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)
 
@@ -109,11 +111,11 @@ test do
     inner = ->(env) {
       call_count += 1
       messages_at_second_call = env[:messages].map(&:content) if call_count == 2
-      env[:messages] << RubyLLM::Message.new(role: :assistant, content: "done")
+      env[:messages] << Brute::Message.new(role: :assistant, content: "done")
     }
 
     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)
 
@@ -126,11 +128,11 @@ test do
     inner = ->(env) {
       call_count += 1
       messages_at_second_call = env[:messages].map(&:content) if call_count == 2
-      env[:messages] << RubyLLM::Message.new(role: :assistant, content: "done")
+      env[:messages] << Brute::Message.new(role: :assistant, content: "done")
     }
 
     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] << Brute::Message.new(role: :tool, content: "result", tool_call_id: "tc1")
+      else
+        env[:messages] << Brute::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] << Brute::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] << Brute::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
 
@@ -22,7 +22,7 @@ module Brute
 
       def call(env)
         if max_iterations_reached?(env)
-          env[:messages] << RubyLLM::Message.new(
+          env[:messages] << Brute::Message.new(
             role: :user,
             content: "Maximum iterations reached.",
           )
@@ -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

@@ -37,7 +37,7 @@ module Brute
           result = @system_prompt.prepare(ctx)
           unless result.empty?
             env[:messages].unshift(
-              RubyLLM::Message.new(role: :system, content: result.to_s)
+              Brute::Message.new(role: :system, content: result.to_s)
             )
           end
         end
@@ -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

@@ -39,8 +39,8 @@ module Brute
         #    }
         #    # Replace the message history with the summary
         #    env[:messages] = [
-        #      RubyLLM::Message.new(role: :system, content: @system_prompt),
-        #      RubyLLM::Message.new(role: :user, content: "[Previous conversation summary]\n\n#{summary_text}"),
+        #      Brute::Message.new(role: :system, content: @system_prompt),
+        #      Brute::Message.new(role: :user, content: "[Previous conversation summary]\n\n#{summary_text}"),
         #    ]
         #  end
         #end
@@ -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