brute 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2e5a610b24378a83f8ce97c8e251a4325705e17a455aa95e9f9c14efe581845a
-  data.tar.gz: 43a0dc2f5e1c2d5d3668b00133278956d800caaeb6f955fb5824d4091da16455
+  metadata.gz: 434ac3760153b860523176d38105ee8618ec95025713a332745281cda1af4cb8
+  data.tar.gz: 3358b33334bf01bd79188c1fb488729997b090bb4617063bc2f61579358b63d6
 SHA512:
-  metadata.gz: 6482e969a2865fc56aaa24f3bf2505f7418bf4b03b7d9c96454ade03e9e715511d33ec7d878cef8d3e1dab95b9ed514bd9eb42890229f426268271ee28b8690f
-  data.tar.gz: 7d16e0ccbf71f5ed106b3a073a122668004d9b729f7efdc0d2a03b3c9a3a8483b9b7a9e57546bbb82820de6be5c361a8ae44f9cdae40e64d2b85be641ecd2e9c
+  metadata.gz: 03a3b9866b7e32cc44b260bdd8655983f2776d9c14235bc98f04a26e57f949070b9a3bae87008fb940bd44e9eb671f373f5544759f5ced71026a2c55eac6df44
+  data.tar.gz: f3896062d7c20fb622463c4af6b122b8d1281a9ff1147d2b8d8a747ea372fc8631609449652229dd10a604570b866119005449673273ac029d43ab087d9f5b5f

data/lib/brute/agent_stream.rb

@@ -1,32 +1,38 @@
 # frozen_string_literal: true
 
 module Brute
-  # Bridges llm.rb's streaming callbacks to forge-rb's callback system.
+  # Bridges llm.rb's streaming callbacks to the host application.
   #
   # Text and reasoning chunks fire immediately as the LLM generates them.
-  # Tool calls spawn threads on arrival — tools start running while the
-  # response is still streaming. on_tool_result fires as each thread finishes.
+  # Tool calls are collected but NOT executed — execution is deferred to the
+  # orchestrator after the stream completes. This ensures text is never
+  # concurrent with tool execution.
+  #
+  # After the stream finishes, the orchestrator reads +pending_tools+ to
+  # dispatch all tool calls concurrently, then fires +on_tool_call_start+
+  # once with the full batch.
   #
   class AgentStream < LLM::Stream
     # Tool call metadata recorded during streaming, used by ToolUseGuard
     # when ctx.functions is empty (nil-choice bug in llm.rb).
-    # Cleared by the guard after consumption to prevent stale data from
-    # causing duplicate synthetic assistant messages on subsequent calls.
     attr_reader :pending_tool_calls
 
-    def clear_pending_tool_calls!
-      @pending_tool_calls.clear
-    end
+    # Deferred tool/error pairs: [(LLM::Function, error_or_nil), ...]
+    # The orchestrator reads these after the stream completes.
+    attr_reader :pending_tools
 
-    def initialize(on_content: nil, on_reasoning: nil, on_tool_call: nil, on_tool_result: nil, on_question: nil)
+    def initialize(on_content: nil, on_reasoning: nil, on_question: nil)
       @on_content = on_content
       @on_reasoning = on_reasoning
-      @on_tool_call = on_tool_call
-      @on_tool_result = on_tool_result
       @on_question = on_question
       @pending_tool_calls = []
+      @pending_tools = []
     end
 
+    # The on_question callback, needed by the orchestrator to set
+    # thread/fiber-locals before tool execution.
+    attr_reader :on_question
+
     def on_content(text)
       @on_content&.call(text)
     end
@@ -35,30 +41,17 @@ module Brute
       @on_reasoning&.call(text)
     end
 
+    # Called by llm.rb per tool as it arrives during streaming.
+    # Records only — no execution, no threads, no queue pushes.
     def on_tool_call(tool, error)
       @pending_tool_calls << { id: tool.id, name: tool.name, arguments: tool.arguments }
-      @on_tool_call&.call(tool.name, tool.arguments)
-
-      if error
-        queue << error
-        @on_tool_result&.call(tool.name, error.value)
-      else
-        queue << LLM::Function::Task.new(spawn_with_callback(tool))
-      end
+      @pending_tools << [tool, error]
     end
 
-    private
-
-    def spawn_with_callback(tool)
-      on_result = @on_tool_result
-      on_question = @on_question
-      name = tool.name
-      Thread.new do
-        Thread.current[:on_question] = on_question
-        result = tool.call
-        on_result&.call(name, result.respond_to?(:value) ? result.value : result)
-        result
-      end
+    # Clear all deferred state after the orchestrator has consumed it.
+    def clear_pending!
+      @pending_tool_calls.clear
+      @pending_tools.clear
     end
   end
 end

data/lib/brute/middleware/tool_use_guard.rb

@@ -56,7 +56,7 @@ module Brute
           stream = resolve_stream(ctx)
           if stream
             data = stream.pending_tool_calls.dup
-            stream.clear_pending_tool_calls!
+            stream.clear_pending!
             data
           else
             []

data/lib/brute/orchestrator.rb

@@ -17,6 +17,11 @@ module Brute
   #   2. Executes any tool calls the LLM requested
   #   3. Repeats until done or a limit is hit
   #
+  # Tool execution is always deferred until after the LLM response (including
+  # streaming) completes. Tools then run concurrently with each other via
+  # Async::Barrier. on_tool_call_start fires once with the full batch before
+  # execution begins; on_tool_result fires per-tool as each finishes.
+  #
   class Orchestrator
     MAX_REQUESTS_PER_TURN = 100
 
@@ -33,7 +38,7 @@ module Brute
       agent_name: nil,
       on_content: nil,
       on_reasoning: nil,
-      on_tool_call: nil,
+      on_tool_call_start: nil,
       on_tool_result: nil,
       on_question: nil,
       logger: nil
@@ -62,8 +67,6 @@ module Brute
         AgentStream.new(
           on_content: on_content,
           on_reasoning: on_reasoning,
-          on_tool_call: on_tool_call,
-          on_tool_result: on_tool_result,
           on_question: on_question,
         )
       end
@@ -95,7 +98,7 @@ module Brute
         callbacks: {
           on_content: on_content,
           on_reasoning: on_reasoning,
-          on_tool_call: on_tool_call,
+          on_tool_call_start: on_tool_call_start,
           on_tool_result: on_tool_result,
           on_question: on_question,
         },
@@ -131,15 +134,28 @@ module Brute
 
       # --- Agent loop ---
       loop do
-        break if @context.functions.empty? && (!@stream || @stream.queue.empty?)
-
-        # Collect tool results.
-        # Streaming: tools already spawned threads during the LLM response — just join them.
-        # Non-streaming: execute manually (parallel or sequential).
-        results = if @stream && !@stream.queue.empty?
-          @context.wait(:thread)
-        else
-          execute_tool_calls
+        # Collect pending tools from either source:
+        # - Streaming: AgentStream deferred tools (collected during stream)
+        # - Non-streaming: ctx.functions (populated by llm.rb after response)
+        pending = collect_pending_tools
+        break if pending.empty?
+
+        # Fire on_tool_call_start ONCE with the full batch
+        on_start = @env.dig(:callbacks, :on_tool_call_start)
+        on_start&.call(pending.map { |tool, _| { name: tool.name, arguments: tool.arguments } })
+
+        # Separate errors (tool not found) from executable tools
+        errors = pending.select { |_, err| err }
+        executable = pending.reject { |_, err| err }.map(&:first)
+
+        # Execute tools concurrently, collect results
+        results = execute_tool_calls(executable)
+
+        # Append error results (tool not found, etc.)
+        errors.each do |_, err|
+          on_result = @env.dig(:callbacks, :on_tool_result)
+          on_result&.call(err.name, result_value(err))
+          results << err
         end
 
         # Send results back through the pipeline
@@ -151,7 +167,7 @@ module Brute
         @request_count += 1
 
         # Check limits
-        break if @context.functions.empty? && (!@stream || @stream.queue.empty?)
+        break if collect_pending_tools.empty?
         break if @request_count >= MAX_REQUESTS_PER_TURN
         break if @env[:metadata][:tool_error_limit_reached]
       end
@@ -222,24 +238,55 @@ module Brute
       end
     end
 
+    # ------------------------------------------------------------------
+    # Pending tool collection
+    # ------------------------------------------------------------------
+
+    # Collect pending tools from the stream (streaming) or context (non-streaming).
+    # Returns an array of [tool, error_or_nil] pairs.
+    # Clears the stream's deferred state after consumption.
+    def collect_pending_tools
+      if @stream&.pending_tools&.any?
+        tools = @stream.pending_tools.dup
+        @stream.clear_pending!
+        tools
+      elsif @context.functions.any?
+        @context.functions.to_a.map { |fn| [fn, nil] }
+      else
+        []
+      end
+    end
+
     # ------------------------------------------------------------------
     # Tool execution
     # ------------------------------------------------------------------
 
-    def execute_tool_calls
-      pending = @context.functions.to_a
-      return execute_sequential(pending) if pending.size <= 1
+    def execute_tool_calls(functions)
+      return [] if functions.empty?
+
+      # 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 = functions.partition { |fn| fn.name == "question" }
 
-      execute_parallel(pending)
+      results = []
+      results.concat(execute_sequential(questions)) if questions.any?
+      if others.size <= 1
+        results.concat(execute_sequential(others))
+      else
+        results.concat(execute_parallel(others))
+      end
+      results
     end
 
     # Run a single tool call synchronously.
     def execute_sequential(functions)
-      on_call = @env.dig(:callbacks, :on_tool_call)
       on_result = @env.dig(:callbacks, :on_tool_result)
+      on_question = @env.dig(:callbacks, :on_question)
 
       functions.map do |fn|
-        on_call&.call(fn.name, fn.arguments)
+        Thread.current[:on_question] = on_question
         result = fn.call
         on_result&.call(fn.name, result_value(result))
         result
@@ -256,8 +303,8 @@ module Brute
     # The barrier is stored in @barrier so abort! can cancel in-flight tools.
     #
     def execute_parallel(functions)
-      on_call = @env.dig(:callbacks, :on_tool_call)
       on_result = @env.dig(:callbacks, :on_tool_result)
+      on_question = @env.dig(:callbacks, :on_question)
 
       results = Array.new(functions.size)
 
@@ -266,7 +313,7 @@ module Brute
 
         functions.each_with_index do |fn, i|
           @barrier.async do
-            on_call&.call(fn.name, fn.arguments)
+            Thread.current[:on_question] = on_question
             results[i] = fn.call
             r = results[i]
             on_result&.call(r.name, result_value(r))

data/lib/brute/pipeline.rb

@@ -22,7 +22,7 @@ module Brute
   #     tools:     [Tool, ...],       # tool classes
   #     params:    {},                # extra LLM call params (reasoning config, etc.)
   #     metadata:  {},                # shared scratchpad for middleware state
-  #     callbacks: {},                # :on_content, :on_tool_call, :on_tool_result
+  #     callbacks: {},                # :on_content, :on_tool_call_start, :on_tool_result
   #   }
   #
   # ## The response

data/lib/brute/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Brute
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: brute
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Brute Contributors