brute 0.4.0 → 1.0.0

data/lib/brute/middleware/tracing.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require "bundler/setup"
+require "brute"
+
 module Brute
   module Middleware
     # Logs timing and token usage for every LLM call, and tracks cumulative
@@ -9,7 +12,7 @@ module Brute
     # call. It also tracks total wall-clock time across all calls in a turn
     # (including tool execution gaps between LLM calls).
     #
-    # A new turn is detected when env[:tool_results] is nil (the orchestrator
+    # A new turn is detected when env[:tool_results] is nil (the agent loop
     # sets this on the first call of each run()).
     #
     # Stores in env[:metadata][:timing]:
@@ -36,7 +39,7 @@ module Brute
           @total_llm_elapsed = 0.0
         end
 
-        messages = env[:context].messages.to_a
+        messages = env[:messages]
         @logger.debug("[brute] LLM call ##{@call_count} (#{messages.size} messages in context)")
 
         start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
@@ -61,3 +64,61 @@ module Brute
     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
+
+  it "passes the response through unchanged" do
+    response = MockResponse.new(content: "traced response")
+    inner_app = ->(_env) { response }
+    middleware = Brute::Middleware::Tracing.new(inner_app, logger: Logger.new(StringIO.new))
+    result = middleware.call(build_env(tool_results: nil))
+    result.should == response
+  end
+
+  it "populates timing with llm_call_count" do
+    response = MockResponse.new(content: "traced response")
+    inner_app = ->(_env) { response }
+    middleware = Brute::Middleware::Tracing.new(inner_app, logger: Logger.new(StringIO.new))
+    env = build_env(tool_results: nil)
+    middleware.call(env)
+    env[:metadata][:timing][:llm_call_count].should == 1
+  end
+
+  it "populates timing with non-negative last_call_elapsed" do
+    response = MockResponse.new(content: "traced response")
+    inner_app = ->(_env) { response }
+    middleware = Brute::Middleware::Tracing.new(inner_app, logger: Logger.new(StringIO.new))
+    env = build_env(tool_results: nil)
+    middleware.call(env)
+    (env[:metadata][:timing][:last_call_elapsed] >= 0).should.be.true
+  end
+
+  it "accumulates call count across multiple calls" do
+    response = MockResponse.new(content: "traced response")
+    inner_app = ->(_env) { response }
+    middleware = Brute::Middleware::Tracing.new(inner_app, logger: Logger.new(StringIO.new))
+    env = build_env(tool_results: nil)
+    middleware.call(env)
+    env[:tool_results] = [["read", {}]]
+    middleware.call(env)
+    middleware.call(env)
+    env[:metadata][:timing][:llm_call_count].should == 3
+  end
+
+  it "logs LLM call and response messages" do
+    response = MockResponse.new(content: "traced response")
+    inner_app = ->(_env) { response }
+    log_output = StringIO.new
+    middleware = Brute::Middleware::Tracing.new(inner_app, logger: Logger.new(log_output))
+    middleware.call(build_env(tool_results: nil))
+    log_output.string.should =~ /LLM call #1/
+  end
+end

data/lib/brute/middleware.rb

@@ -0,0 +1,18 @@
+require_relative 'middleware/base'
+require_relative 'middleware/llm_call'
+require_relative 'middleware/retry'
+require_relative 'middleware/doom_loop_detection'
+require_relative 'middleware/token_tracking'
+require_relative 'middleware/compaction_check'
+require_relative 'middleware/session_persistence'
+require_relative 'middleware/message_tracking'
+require_relative 'middleware/tracing'
+require_relative 'middleware/tool_error_tracking'
+require_relative 'middleware/reasoning_normalizer'
+require_relative "middleware/tool_use_guard"
+require_relative "middleware/otel"
+
+module Brute
+  module Middleware
+  end
+end

data/lib/brute/orchestrator/turn.rb

@@ -0,0 +1,105 @@
+module Brute
+  class Orchestrator
+    class Turn
+      def initialize(env:, pending:)
+        @env = env
+        @pending = pending
+      end
+
+      def perform
+        @env.dig(:callbacks, :on_tool_call_start).then do |on_start|
+          on_start&.call(
+            @pending.map do |tool, _|
+              {
+                name: tool.name,
+                arguments: tool.arguments
+              }
+            end
+          )
+        end
+
+        execute_tool_calls.tap do |results|
+          errors.each do |_, err|
+            on_result = @env.dig(:callbacks, :on_tool_result)
+            on_result&.call(err.name, result_value(err))
+            results << err
+          end
+        end
+      end
+
+      def errors = @pending.select { |_, err| err }
+      def executable = @pending.reject { |_, err| err }.map(&:first)
+
+      def execute_tool_calls
+        if executable.empty?
+          []
+        else
+          # Questions block execution — they must complete before other tools
+          # run, since the LLM may need the answer to inform subsequent work.
+          # Execute any question tools first (sequentially), then dispatch
+          # the remaining tools concurrently.
+          questions, others = executable.partition { _1.name == "question" }
+
+          Array.new.tap do |results|
+            if questions.any?
+              results.concat(execute_sequential(questions))
+            end
+
+            if others.size <= 1
+              results.concat(execute_sequential(others))
+            else
+              results.concat(execute_parallel(others))
+            end
+          end
+        end
+      end
+
+      # Run a single tool call synchronously.
+      def execute_sequential(functions)
+        on_result = @env.dig(:callbacks, :on_tool_result)
+        on_question = @env.dig(:callbacks, :on_question)
+
+        functions.map do |fn|
+          Thread.current[:on_question] = on_question
+          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_result = @env.dig(:callbacks, :on_tool_result)
+        on_question = @env.dig(:callbacks, :on_question)
+
+        Array.new(functions.size).tap do |results|
+          Async do
+            @barrier = Async::Barrier.new
+
+            functions.each_with_index do |fn, i|
+              @barrier.async do
+                Thread.current[:on_question] = on_question
+                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
+        end
+      end
+    end
+  end
+end

data/lib/brute/patches/buffer_nil_guard.rb

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+if __FILE__ == $0
+  require "bundler/setup"
+  require "brute"
+end
+
 # Monkey-patch: Guard LLM::Buffer against nil entries.
 #
 # llm.rb's Context#talk can sometimes concatenate nil into the message

data/lib/brute/pipeline.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require "bundler/setup"
+require "brute"
+
 module Brute
   # Rack-style middleware pipeline for LLM calls.
   #
@@ -16,13 +19,19 @@ module Brute
   # ## 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_start, :on_tool_result
+  #     provider:          LLM::Provider,    # the LLM provider
+  #     model:             String|nil,       # model override
+  #     input:             <prompt/results>, # what to pass to LLM
+  #     tools:             [Tool, ...],      # tool classes
+  #     messages:          [LLM::Message],   # conversation history (Brute-owned)
+  #     stream:            AgentStream|nil,  # streaming bridge
+  #     params:            {},               # extra LLM call params
+  #     metadata:          {},               # shared scratchpad for middleware state
+  #     callbacks:         {},               # :on_content, :on_tool_call_start, :on_tool_result
+  #     tool_results:      Array|nil,        # tool results from previous iteration
+  #     streaming:         Boolean,          # whether streaming is active
+  #     should_exit:       Hash|nil,         # exit signal from middleware
+  #     pending_functions: [LLM::Function],  # tool calls from last LLM response
   #   }
   #
   # ## The response
@@ -79,3 +88,73 @@ module Brute
     end
   end
 end
+
+test do
+  require_relative "../../spec/support/mock_provider"
+  require_relative "../../spec/support/mock_response"
+
+  def make_env(provider:, input:)
+    { provider: provider, model: nil, input: input, tools: [], messages: [],
+      stream: nil, params: {}, metadata: {}, callbacks: {}, tool_results: nil,
+      streaming: false, should_exit: nil, pending_functions: [] }
+  end
+
+  it "full pipeline passes env through all middleware" do
+    provider = MockProvider.new
+    session = Struct.new(:saved) { def save_messages(m); self.saved = m; end }.new
+    compactor = Object.new
+    compactor.define_singleton_method(:should_compact?) { |_msgs, **_| false }
+    log_output = StringIO.new
+
+    pipeline = Brute::Pipeline.new
+    pipeline.use(Brute::Middleware::Tracing, logger: Logger.new(log_output))
+    pipeline.use(Brute::Middleware::Retry, max_attempts: 3, base_delay: 2)
+    pipeline.use(Brute::Middleware::SessionPersistence, session: session)
+    pipeline.use(Brute::Middleware::TokenTracking)
+    pipeline.use(Brute::Middleware::CompactionCheck, compactor: compactor, system_prompt: "sys")
+    pipeline.use(Brute::Middleware::ToolErrorTracking)
+    pipeline.use(Brute::Middleware::DoomLoopDetection, threshold: 3)
+    pipeline.use(Brute::Middleware::ToolUseGuard)
+    pipeline.run(Brute::Middleware::LLMCall.new)
+
+    env = make_env(provider: provider, input: "hello")
+    result = pipeline.call(env)
+    result.should.not.be.nil
+  end
+
+  it "pipeline populates timing metadata" do
+    provider = MockProvider.new
+    session = Struct.new(:saved) { def save_messages(m); self.saved = m; end }.new
+
+    pipeline = Brute::Pipeline.new
+    pipeline.use(Brute::Middleware::Tracing, logger: Logger.new(StringIO.new))
+    pipeline.use(Brute::Middleware::SessionPersistence, session: session)
+    pipeline.use(Brute::Middleware::TokenTracking)
+    pipeline.run(Brute::Middleware::LLMCall.new)
+
+    env = make_env(provider: provider, input: "hello")
+    pipeline.call(env)
+    env[:metadata][:timing][:llm_call_count].should == 1
+  end
+
+  it "pipeline populates token metadata" do
+    provider = MockProvider.new
+    session = Struct.new(:saved) { def save_messages(m); self.saved = m; end }.new
+
+    pipeline = Brute::Pipeline.new
+    pipeline.use(Brute::Middleware::Tracing, logger: Logger.new(StringIO.new))
+    pipeline.use(Brute::Middleware::SessionPersistence, session: session)
+    pipeline.use(Brute::Middleware::TokenTracking)
+    pipeline.run(Brute::Middleware::LLMCall.new)
+
+    env = make_env(provider: provider, input: "hello")
+    pipeline.call(env)
+    env[:metadata][:tokens][:total_input].should.be > 0
+  end
+
+  it "raises when no terminal app is set" do
+    pipeline = Brute::Pipeline.new
+    pipeline.use(Brute::Middleware::TokenTracking)
+    lambda { pipeline.call({}) }.should.raise(RuntimeError)
+  end
+end

data/lib/brute/prompts/build_switch.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require "bundler/setup"
+require "brute"
+
 module Brute
   module Prompts
     module BuildSwitch
@@ -17,3 +20,29 @@ module Brute
     end
   end
 end
+
+test do
+  it "returns a string" do
+    Brute::Prompts::BuildSwitch.call({}).should.be.kind_of(String)
+  end
+
+  it "wraps content in system-reminder tags" do
+    Brute::Prompts::BuildSwitch.call({}).should =~ /system-reminder/
+  end
+
+  it "announces mode change from plan to build" do
+    Brute::Prompts::BuildSwitch.call({}).should =~ /plan to build/
+  end
+
+  it "states no longer in read-only mode" do
+    Brute::Prompts::BuildSwitch.call({}).should =~ /no longer in read-only mode/
+  end
+
+  it "permits tool use" do
+    Brute::Prompts::BuildSwitch.call({}).should =~ /permitted to make file changes/
+  end
+
+  it "ignores context (static content)" do
+    Brute::Prompts::BuildSwitch.call({ agent_switched: "build" }).should == Brute::Prompts::BuildSwitch.call({})
+  end
+end

data/lib/brute/prompts/environment.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require "bundler/setup"
+require "brute"
+
 module Brute
   module Prompts
     module Environment
@@ -23,3 +26,43 @@ module Brute
     end
   end
 end
+
+test do
+  require "tmpdir"
+  require "fileutils"
+
+  it "includes cwd from context" do
+    Brute::Prompts::Environment.call(cwd: "/some/path", model_name: "test").should =~ /\/some\/path/
+  end
+
+  it "includes model name from context" do
+    Brute::Prompts::Environment.call(cwd: "/tmp", model_name: "claude-sonnet").should =~ /claude-sonnet/
+  end
+
+  it "wraps environment info in env tags" do
+    Brute::Prompts::Environment.call(cwd: "/tmp", model_name: "test").should =~ /<env>/
+  end
+
+  it "detects git repo when .git exists" do
+    Dir.mktmpdir do |dir|
+      Dir.mkdir(File.join(dir, ".git"))
+      text = Brute::Prompts::Environment.call(cwd: dir, model_name: "test")
+      text.should =~ /Is directory a git repo: yes/
+    end
+  end
+
+  it "detects non-git directory" do
+    Dir.mktmpdir do |dir|
+      text = Brute::Prompts::Environment.call(cwd: dir, model_name: "test")
+      text.should =~ /Is directory a git repo: no/
+    end
+  end
+
+  it "includes the platform" do
+    Brute::Prompts::Environment.call(cwd: "/tmp", model_name: "test").should =~ /#{RUBY_PLATFORM}/
+  end
+
+  it "defaults cwd to Dir.pwd when not provided" do
+    Brute::Prompts::Environment.call(model_name: "test").should =~ /#{Regexp.escape(Dir.pwd)}/
+  end
+end

data/lib/brute/prompts/identity.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require "bundler/setup"
+require "brute"
+
 module Brute
   module Prompts
     module Identity
@@ -9,3 +12,29 @@ module Brute
     end
   end
 end
+
+test do
+  it "returns a string for anthropic" do
+    Brute::Prompts::Identity.call(provider_name: "anthropic").should.be.kind_of(String)
+  end
+
+  it "returns non-empty text for anthropic" do
+    Brute::Prompts::Identity.call(provider_name: "anthropic").should.not.be.empty
+  end
+
+  it "returns non-empty text for openai" do
+    Brute::Prompts::Identity.call(provider_name: "openai").should.not.be.empty
+  end
+
+  it "falls back to default for unknown providers" do
+    default_text = Brute::Prompts::Identity.call(provider_name: "default")
+    unknown_text = Brute::Prompts::Identity.call(provider_name: "nonexistent_provider")
+    unknown_text.should == default_text
+  end
+
+  it "returns different text for different providers" do
+    anthropic = Brute::Prompts::Identity.call(provider_name: "anthropic")
+    openai = Brute::Prompts::Identity.call(provider_name: "openai")
+    (anthropic != openai).should.be.true
+  end
+end

data/lib/brute/prompts/instructions.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require "bundler/setup"
+require "brute"
+
 module Brute
   module Prompts
     module Instructions
@@ -16,3 +19,21 @@ module Brute
     end
   end
 end
+
+test do
+  it "returns nil when custom_rules is nil" do
+    Brute::Prompts::Instructions.call(custom_rules: nil).should.be.nil
+  end
+
+  it "returns nil when custom_rules is empty" do
+    Brute::Prompts::Instructions.call(custom_rules: "").should.be.nil
+  end
+
+  it "returns nil when custom_rules is whitespace-only" do
+    Brute::Prompts::Instructions.call(custom_rules: "   \n  ").should.be.nil
+  end
+
+  it "wraps custom_rules in a Project-Specific Rules header" do
+    Brute::Prompts::Instructions.call(custom_rules: "Always use tabs.").should =~ /Project-Specific Rules/
+  end
+end

data/lib/brute/prompts/max_steps.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require "bundler/setup"
+require "brute"
+
 module Brute
   module Prompts
     module MaxSteps
@@ -28,3 +31,25 @@ module Brute
     end
   end
 end
+
+test do
+  it "returns a string" do
+    Brute::Prompts::MaxSteps.call({}).should.be.kind_of(String)
+  end
+
+  it "announces maximum steps reached" do
+    Brute::Prompts::MaxSteps.call({}).should =~ /MAXIMUM STEPS REACHED/
+  end
+
+  it "states tools are disabled" do
+    Brute::Prompts::MaxSteps.call({}).should =~ /Tools are disabled/
+  end
+
+  it "requires a text-only response" do
+    Brute::Prompts::MaxSteps.call({}).should =~ /text ONLY/
+  end
+
+  it "ignores context (static content)" do
+    Brute::Prompts::MaxSteps.call({ max_steps_reached: true }).should == Brute::Prompts::MaxSteps.call({})
+  end
+end

data/lib/brute/prompts/plan_reminder.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require "bundler/setup"
+require "brute"
+
 module Brute
   module Prompts
     module PlanReminder
@@ -38,3 +41,25 @@ module Brute
     end
   end
 end
+
+test do
+  it "returns a string" do
+    Brute::Prompts::PlanReminder.call({}).should.be.kind_of(String)
+  end
+
+  it "wraps content in system-reminder tags" do
+    Brute::Prompts::PlanReminder.call({}).should =~ /system-reminder/
+  end
+
+  it "declares READ-ONLY mode" do
+    Brute::Prompts::PlanReminder.call({}).should =~ /READ-ONLY/
+  end
+
+  it "forbids file edits" do
+    Brute::Prompts::PlanReminder.call({}).should =~ /STRICTLY FORBIDDEN/
+  end
+
+  it "ignores context (static content)" do
+    Brute::Prompts::PlanReminder.call({ agent: "plan" }).should == Brute::Prompts::PlanReminder.call({})
+  end
+end

data/lib/brute/prompts/skills.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require "bundler/setup"
+require "brute"
+
 module Brute
   module Prompts
     module Skills
@@ -20,3 +23,13 @@ module Brute
     end
   end
 end
+
+test do
+  require "tmpdir"
+
+  it "returns nil when no skills are found" do
+    Dir.mktmpdir do |dir|
+      Brute::Prompts::Skills.call(cwd: dir).should.be.nil
+    end
+  end
+end

data/lib/brute/prompts.rb

@@ -0,0 +1,28 @@
+require_relative 'prompts/base'
+require_relative 'prompts/identity'
+require_relative 'prompts/tone_and_style'
+require_relative 'prompts/objectivity'
+require_relative 'prompts/task_management'
+require_relative 'prompts/doing_tasks'
+require_relative 'prompts/tool_usage'
+require_relative 'prompts/conventions'
+require_relative 'prompts/git_safety'
+require_relative 'prompts/code_references'
+require_relative 'prompts/environment'
+require_relative 'prompts/instructions'
+require_relative 'prompts/editing_approach'
+require_relative 'prompts/autonomy'
+require_relative 'prompts/editing_constraints'
+require_relative 'prompts/frontend_tasks'
+require_relative 'prompts/proactiveness'
+require_relative 'prompts/code_style'
+require_relative 'prompts/security_and_safety'
+require_relative 'prompts/skills'
+require_relative 'prompts/plan_reminder'
+require_relative 'prompts/max_steps'
+require_relative 'prompts/build_switch'
+
+module Brute
+  module Prompts
+  end
+end