brute 0.4.1 → 1.0.0

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/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
@@ -80,137 +89,72 @@ module Brute
   end
 end
 
-if __FILE__ == $0
-  require_relative "../../spec/spec_helper"
-
-  RSpec.describe "Middleware Pipeline Integration" do
-    let(:provider) { MockProvider.new }
-    let(:log_output) { StringIO.new }
-    let(:logger) { Logger.new(log_output) }
-    let(:session) { double("session", save: nil) }
-    let(:compactor) { double("compactor", should_compact?: false) }
-
-    describe "full orchestrator pipeline" do
-      it "passes env through all middleware and returns the response" do
-        response = MockResponse.new(content: "integrated response")
-        allow(provider).to receive(:complete).and_return(response)
-
-        ctx = LLM::Context.new(provider, tools: [])
-        prompt = ctx.prompt { |p| p.system("sys"); p.user("hello") }
-
-        pipeline = Brute::Pipeline.new
-        pipeline.use(Brute::Middleware::Tracing, logger: logger)
-        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", tools: [])
-        pipeline.use(Brute::Middleware::ToolErrorTracking)
-        pipeline.use(Brute::Middleware::DoomLoopDetection, threshold: 3)
-        pipeline.use(Brute::Middleware::ToolUseGuard)
-        pipeline.run(Brute::Middleware::LLMCall.new)
-
-        env = {
-          context: ctx,
-          provider: provider,
-          input: prompt,
-          tools: [],
-          params: {},
-          metadata: {},
-          callbacks: {},
-          tool_results: nil,
-          streaming: false,
-        }
-
-        result = pipeline.call(env)
-
-        expect(result).not_to be_nil
-        expect(env[:metadata][:timing]).to include(:llm_call_count, :total_llm_elapsed)
-        expect(env[:metadata][:tokens]).to include(:total_input, :total_output, :call_count)
-        expect(session).to have_received(:save)
-        expect(log_output.string).to include("LLM call #1")
-      end
-    end
+test do
+  require_relative "../../spec/support/mock_provider"
+  require_relative "../../spec/support/mock_response"
 
-    describe "Retry + Tracing combo" do
-      it "Tracing sees the full elapsed time including retries" do
-        call_count = 0
-        response = MockResponse.new(content: "recovered")
+  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
 
-        allow(provider).to receive(:complete) do |*_args|
-          call_count += 1
-          raise LLM::RateLimitError, "rate limited" if call_count <= 1
-          response
-        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
 
-        ctx = LLM::Context.new(provider, tools: [])
-        prompt = ctx.prompt { |p| p.system("sys"); p.user("hi") }
-
-        pipeline = Brute::Pipeline.new
-        pipeline.use(Brute::Middleware::Tracing, logger: logger)
-        pipeline.use(Brute::Middleware::Retry, max_attempts: 3, base_delay: 0)
-        pipeline.run(Brute::Middleware::LLMCall.new)
-
-        env = {
-          context: ctx,
-          provider: provider,
-          input: prompt,
-          tools: [],
-          params: {},
-          metadata: {},
-          callbacks: {},
-          tool_results: nil,
-          streaming: false,
-        }
-
-        result = pipeline.call(env)
-
-        expect(result).not_to be_nil
-        expect(env[:metadata][:timing][:llm_call_count]).to eq(1)
-      end
-    end
+  it "pipeline populates timing metadata" do
+    provider = MockProvider.new
+    session = Struct.new(:saved) { def save_messages(m); self.saved = m; end }.new
 
-    describe "TokenTracking + SessionPersistence combo" do
-      it "session receives save after tokens are tracked" do
-        response = MockResponse.new(content: "tracked and saved")
-        allow(provider).to receive(:complete).and_return(response)
-
-        ctx = LLM::Context.new(provider, tools: [])
-        prompt = ctx.prompt { |p| p.system("sys"); p.user("hi") }
-
-        save_args = []
-        allow(session).to receive(:save) { |ctx_arg| save_args << ctx_arg }
-
-        pipeline = Brute::Pipeline.new
-        pipeline.use(Brute::Middleware::SessionPersistence, session: session)
-        pipeline.use(Brute::Middleware::TokenTracking)
-        pipeline.run(Brute::Middleware::LLMCall.new)
-
-        env = {
-          context: ctx,
-          provider: provider,
-          input: prompt,
-          tools: [],
-          params: {},
-          metadata: {},
-          callbacks: {},
-          tool_results: nil,
-          streaming: false,
-        }
-
-        pipeline.call(env)
-
-        expect(env[:metadata][:tokens]).to include(:total_input)
-        expect(save_args.size).to eq(1)
-      end
-    end
+    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)
 
-    describe "Pipeline builder" do
-      it "raises when no terminal app is set" do
-        pipeline = Brute::Pipeline.new
-        pipeline.use(Brute::Middleware::TokenTracking)
+    env = make_env(provider: provider, input: "hello")
+    pipeline.call(env)
+    env[:metadata][:timing][:llm_call_count].should == 1
+  end
 
-        expect { pipeline.call({}) }.to raise_error(RuntimeError, /no terminal app/)
-      end
-    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
@@ -18,35 +21,28 @@ module Brute
   end
 end
 
-if __FILE__ == $0
-  require_relative "../../../spec/spec_helper"
-
-  RSpec.describe Brute::Prompts::BuildSwitch do
-    subject(:text) { described_class.call({}) }
-
-    it "returns a string" do
-      expect(text).to be_a(String)
-    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
-      expect(text).to include("<system-reminder>")
-      expect(text).to include("</system-reminder>")
-    end
+  it "wraps content in system-reminder tags" do
+    Brute::Prompts::BuildSwitch.call({}).should =~ /system-reminder/
+  end
 
-    it "announces the mode change from plan to build" do
-      expect(text).to include("plan to build")
-    end
+  it "announces mode change from plan to build" do
+    Brute::Prompts::BuildSwitch.call({}).should =~ /plan to build/
+  end
 
-    it "states the agent is no longer in read-only mode" do
-      expect(text).to include("no longer in read-only mode")
-    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
-      expect(text).to include("permitted to make file changes")
-    end
+  it "permits tool use" do
+    Brute::Prompts::BuildSwitch.call({}).should =~ /permitted to make file changes/
+  end
 
-    it "ignores context (static content)" do
-      expect(described_class.call({ agent_switched: "build" })).to eq(described_class.call({}))
-    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
@@ -24,49 +27,42 @@ module Brute
   end
 end
 
-if __FILE__ == $0
-  require_relative "../../../spec/spec_helper"
+test do
+  require "tmpdir"
+  require "fileutils"
 
-  RSpec.describe Brute::Prompts::Environment do
-    it "includes cwd from context" do
-      text = described_class.call(cwd: "/some/path", model_name: "test")
-      expect(text).to include("/some/path")
-    end
+  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
-      text = described_class.call(cwd: "/tmp", model_name: "claude-sonnet-4-20250514")
-      expect(text).to include("claude-sonnet-4-20250514")
-    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
-      text = described_class.call(cwd: "/tmp", model_name: "test")
-      expect(text).to include("<env>")
-      expect(text).to include("</env>")
-    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 = described_class.call(cwd: dir, model_name: "test")
-        expect(text).to include("Is directory a git repo: yes")
-      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 = described_class.call(cwd: dir, model_name: "test")
-        expect(text).to include("Is directory a git repo: no")
-      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
-      text = described_class.call(cwd: "/tmp", model_name: "test")
-      expect(text).to include(RUBY_PLATFORM)
-    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
-      text = described_class.call(model_name: "test")
-      expect(text).to include(Dir.pwd)
-    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
@@ -10,38 +13,28 @@ module Brute
   end
 end
 
-if __FILE__ == $0
-  require_relative "../../../spec/spec_helper"
-
-  RSpec.describe Brute::Prompts::Identity do
-    it "returns provider-specific text for anthropic" do
-      text = described_class.call(provider_name: "anthropic")
-      expect(text).to be_a(String)
-      expect(text).not_to be_empty
-    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 provider-specific text for openai" do
-      text = described_class.call(provider_name: "openai")
-      expect(text).to be_a(String)
-      expect(text).not_to be_empty
-    end
+  it "returns non-empty text for anthropic" do
+    Brute::Prompts::Identity.call(provider_name: "anthropic").should.not.be.empty
+  end
 
-    it "returns provider-specific text for google" do
-      text = described_class.call(provider_name: "google")
-      expect(text).to be_a(String)
-      expect(text).not_to 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.txt for unknown providers" do
-      default_text = described_class.call(provider_name: "default")
-      unknown_text = described_class.call(provider_name: "nonexistent_provider")
-      expect(unknown_text).to eq(default_text)
-    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 = described_class.call(provider_name: "anthropic")
-      openai = described_class.call(provider_name: "openai")
-      expect(anthropic).not_to eq(openai)
-    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
@@ -17,26 +20,20 @@ module Brute
   end
 end
 
-if __FILE__ == $0
-  require_relative "../../../spec/spec_helper"
-
-  RSpec.describe Brute::Prompts::Instructions do
-    it "returns nil when custom_rules is nil" do
-      expect(described_class.call(custom_rules: nil)).to be_nil
-    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
-      expect(described_class.call(custom_rules: "")).to 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
-      expect(described_class.call(custom_rules: "   \n  ")).to 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
-      text = described_class.call(custom_rules: "Always use tabs.")
-      expect(text).to include("Project-Specific Rules")
-      expect(text).to include("Always use tabs.")
-    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
@@ -29,34 +32,24 @@ module Brute
   end
 end
 
-if __FILE__ == $0
-  require_relative "../../../spec/spec_helper"
-
-  RSpec.describe Brute::Prompts::MaxSteps do
-    subject(:text) { described_class.call({}) }
-
-    it "returns a string" do
-      expect(text).to be_a(String)
-    end
-
-    it "announces maximum steps reached" do
-      expect(text).to include("MAXIMUM STEPS REACHED")
-    end
+test do
+  it "returns a string" do
+    Brute::Prompts::MaxSteps.call({}).should.be.kind_of(String)
+  end
 
-    it "states tools are disabled" do
-      expect(text).to include("Tools are disabled")
-    end
+  it "announces maximum steps reached" do
+    Brute::Prompts::MaxSteps.call({}).should =~ /MAXIMUM STEPS REACHED/
+  end
 
-    it "requires a text-only response" do
-      expect(text).to include("text ONLY")
-    end
+  it "states tools are disabled" do
+    Brute::Prompts::MaxSteps.call({}).should =~ /Tools are disabled/
+  end
 
-    it "requires summary of work done" do
-      expect(text).to include("Summary of what has been accomplished")
-    end
+  it "requires a text-only response" do
+    Brute::Prompts::MaxSteps.call({}).should =~ /text ONLY/
+  end
 
-    it "ignores context (static content)" do
-      expect(described_class.call({ max_steps_reached: true })).to eq(described_class.call({}))
-    end
+  it "ignores context (static content)" do
+    Brute::Prompts::MaxSteps.call({ max_steps_reached: true }).should == Brute::Prompts::MaxSteps.call({})
   end
 end