brute 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2e5a610b24378a83f8ce97c8e251a4325705e17a455aa95e9f9c14efe581845a
-  data.tar.gz: 43a0dc2f5e1c2d5d3668b00133278956d800caaeb6f955fb5824d4091da16455
+  metadata.gz: e6fa4c53a825578634b110724522c021f089595e75e80faea05b5c53697010dd
+  data.tar.gz: 1cff09cf5e255928aada4f09a11c2f77ccf873839ee4f6d0ba24bc12beaefeba
 SHA512:
-  metadata.gz: 6482e969a2865fc56aaa24f3bf2505f7418bf4b03b7d9c96454ade03e9e715511d33ec7d878cef8d3e1dab95b9ed514bd9eb42890229f426268271ee28b8690f
-  data.tar.gz: 7d16e0ccbf71f5ed106b3a073a122668004d9b729f7efdc0d2a03b3c9a3a8483b9b7a9e57546bbb82820de6be5c361a8ae44f9cdae40e64d2b85be641ecd2e9c
+  metadata.gz: 795a6b851f47daba23755f8791f98c4c54f1c738704748767e70ff0bf25b797dca15fc25892642b7b46c7f6c8acab83d5dd110b0741e4252e8e8b1ce8798ffa1
+  data.tar.gz: 827d9628e7d5142fe1eaabc5e3de47cf04468afa5e1985a9af6b7ccc16e471ce35236953d3b746e988ef34a779df3cd4b1e6821ca9cd45815fc302785d8d1a00

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,23 @@ 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
+    # Clear only the tool call metadata (used by ToolUseGuard after it
+    # has consumed the data for synthetic message injection).
+    def clear_pending_tool_calls!
+      @pending_tool_calls.clear
+    end
 
-    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 the deferred execution queue after the orchestrator has
+    # consumed and dispatched all tool calls.
+    def clear_pending_tools!
+      @pending_tools.clear
     end
   end
 end

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 !has_pending_tools?
         break if @request_count >= MAX_REQUESTS_PER_TURN
         break if @env[:metadata][:tool_error_limit_reached]
       end
@@ -222,24 +238,62 @@ module Brute
       end
     end
 
+    # ------------------------------------------------------------------
+    # Pending tool collection
+    # ------------------------------------------------------------------
+
+    # Check whether there are pending tools without consuming them.
+    def has_pending_tools?
+      return true if @stream&.pending_tools&.any?
+      return true if @context.functions.any?
+      false
+    end
+
+    # 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!
+        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 +310,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 +320,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.4.0"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: brute
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Brute Contributors
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 1980-01-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async