brute 1.0.0 → 2.0.0

data/lib/brute/middleware/070_tool_call.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+require "brute/truncation"
+require "async"
+require "async/barrier"
+
+module Brute
+  module Middleware
+    # Executes pending tool calls from the LLM response.
+    #
+    # Existing features (ref: opencode tool.ts wrap / truncate.ts):
+    #
+    # 1. Universal output truncation — after every tool.call(), pass the
+    #    result string through Brute::Truncation.truncate() which enforces
+    #    a 2000-line / 50 KB cap. This is a safety net so no single tool
+    #    result can blow up the context window, regardless of whether the
+    #    tool itself has internal limits.
+    # 2. Overflow to disk — when truncating, the full output is saved to
+    #    a temp file under the truncation directory. The path is included
+    #    in the truncated result with a hint.
+    # 3. Configurable limits — MAX_LINES / MAX_BYTES default to 2000 / 50 KB.
+    # 4. Skip truncation when tool already truncated — if the tool result
+    #    already contains the truncation marker (e.g. Shell or FSSearch
+    #    truncated internally), don't double-truncate.
+    #
+    # == Concurrency model (Async)
+    #
+    # Tool calls are executed concurrently using the `async` gem's fiber-based
+    # scheduler. Each tool call is dispatched as an Async::Task inside an
+    # Async::Barrier, so all tools run in parallel and we wait for every task
+    # to complete before moving on.
+    #
+    # Key design decisions:
+    #
+    # - Sync {} (not Async{}.wait) — reuses an existing event loop if one is
+    #   already running, or creates one on demand. Blocks the caller until all
+    #   inner work completes, which is what the middleware stack requires.
+    #
+    # - Async::Barrier — the idiomatic fan-out / join primitive. Each tool call
+    #   becomes a child task via barrier.async; barrier.wait blocks until every
+    #   task finishes. This is preferable to Async::Queue for a fixed batch of
+    #   work with no producer/consumer relationship.
+    #
+    # - Deterministic result ordering — tool results are collected into an array
+    #   during concurrent execution, then sorted back into the original
+    #   tools_to_run key order before appending to env[:messages]. This ensures
+    #   the LLM always sees results in a stable order regardless of which tool
+    #   finishes first.
+    #
+    # - Fiber-safe shared state — appending to the results array from multiple
+    #   fibers is safe because Async fibers are cooperatively scheduled (only
+    #   one fiber runs at a time within a Sync block). No mutex needed.
+    #
+    # - FileMutationQueue compatibility — tools that mutate files use
+    #   Brute::Queue::FileMutationQueue.serialize, which uses Ruby 3.4's
+    #   fiber-scheduler-aware Mutex. Operations on the same file are serialized;
+    #   operations on different files proceed in parallel.
+    #
+    class ToolCall
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        @app.call(env)
+
+        tools_to_run = pending_tool_calls(env[:messages].last)
+        if tools_to_run.any?
+          available_tools = resolve_tools(env[:tools])
+          env[:events] << on_tool_call_start_event(tools_to_run)
+
+          results = []
+
+          Sync do
+            barrier = Async::Barrier.new
+
+            tools_to_run.each do |id, tool_call|
+              barrier.async do
+                tool = available_tools[tool_call.name.to_sym]
+                result = tool.call(tool_call.arguments)
+
+                # Coerce to String so RubyLLM::Message doesn't treat Hash results
+                # (e.g. Shell's {stdout:, stderr:, exit_code:}) as attachments.
+                content = result.is_a?(String) ? result : result.to_s
+
+                # Universal truncation safety net — skip if already truncated
+                unless Brute::Truncation.already_truncated?(content)
+                  content = Brute::Truncation.truncate(content)
+                end
+
+                results << [id, tool_call, content]
+              rescue => e
+                # Capture the error as a tool result so the LLM can see it
+                # and reason about the failure, rather than crashing the
+                # entire middleware chain.
+                env[:events] << { type: :error, data: { error: e, message: e.message } }
+                results << [id, tool_call, "Error: #{e.class}: #{e.message}"]
+              end
+            end
+
+            barrier.wait
+          ensure
+            barrier&.cancel
+          end
+
+          # Append events and messages in the original tool_call order so the
+          # LLM sees a deterministic sequence regardless of completion order.
+          order = tools_to_run.keys
+          results.sort_by! { |id, _, _| order.index(id) }
+
+          results.each do |_id, tool_call, content|
+            env[:events] << { type: :tool_result, data: { name: tool_call.name, content: content } }
+            env[:messages] << RubyLLM::Message.new(role: :tool, content: content, tool_call_id: tool_call.id)
+          end
+        end
+
+        return env
+      end
+
+      private
+
+        def pending_tool_calls(message)
+          message.tool_calls.to_h.reject { |_id, tc| tc.name == "question" }
+        end
+
+        def resolve_tools(tools)
+          tools.each_with_object({}) do |tool, hash|
+            instance = tool.is_a?(Class) ? tool.new : tool
+            hash[instance.name.to_sym] = instance
+          end
+        end
+
+        def on_tool_call_start_event(pending_tools)
+          {
+            type: :tool_call_start,
+            data: pending_tools.map { |_id, tc|
+              {
+                name: tc.name,
+                call_id: tc.id,
+                arguments: tc.arguments
+              }
+            }
+          }
+        end
+    end
+  end
+end
+
+test do
+  require "brute/session"
+  require "brute/truncation"
+
+  it "passes through when no tool calls pending" do
+    inner = ->(env) {
+      env[:messages] << RubyLLM::Message.new(role: :assistant, content: "hi")
+    }
+    mw = Brute::Middleware::ToolCall.new(inner)
+    env = {
+      messages: Brute::Session.new,
+      tools: [],
+      events: [],
+    }
+    env[:messages].user("hello")
+    mw.call(env)
+    env[:messages].last.content.should == "hi"
+  end
+
+  # --- Universal output truncation ---
+
+  it "truncates large tool results via Truncation" do
+    # A fake tool that returns a huge string
+    big_tool = Class.new(RubyLLM::Tool) do
+      description "test tool"
+      param :input, type: "string", desc: "input"
+      def name; "big_tool"; end
+      def execute(input:)
+        "line\n" * 3000
+      end
+    end
+
+    call_id = "tc_1"
+    tool_calls = {
+      call_id => RubyLLM::ToolCall.new(
+        id: call_id,
+        name: "big_tool",
+        arguments: { "input" => "go" },
+      )
+    }
+
+    inner = ->(env) {
+      env[:messages] << RubyLLM::Message.new(role: :assistant, content: "", tool_calls: tool_calls)
+    }
+    mw = Brute::Middleware::ToolCall.new(inner)
+    env = {
+      messages: Brute::Session.new,
+      tools: [big_tool],
+      events: [],
+    }
+    env[:messages].user("hello")
+    mw.call(env)
+
+    tool_msg = env[:messages].select { |m| m.role == :tool }.last
+    tool_msg.content.lines.size.should.be < 2100
+    tool_msg.content.should =~ /truncated/i
+  end
+
+  # --- Skip double-truncation ---
+
+  it "does not double-truncate already-truncated output" do
+    # A fake tool that returns output already containing the truncation marker
+    pre_truncated_tool = Class.new(RubyLLM::Tool) do
+      description "test tool"
+      param :input, type: "string", desc: "input"
+      def name; "pre_truncated_tool"; end
+      def execute(input:)
+        "some result\n[Output truncated: showing 100 of 5000 lines]"
+      end
+    end
+
+    call_id = "tc_2"
+    tool_calls = {
+      call_id => RubyLLM::ToolCall.new(
+        id: call_id,
+        name: "pre_truncated_tool",
+        arguments: { "input" => "go" },
+      )
+    }
+
+    inner = ->(env) {
+      env[:messages] << RubyLLM::Message.new(role: :assistant, content: "", tool_calls: tool_calls)
+    }
+    mw = Brute::Middleware::ToolCall.new(inner)
+    env = {
+      messages: Brute::Session.new,
+      tools: [pre_truncated_tool],
+      events: [],
+    }
+    env[:messages].user("hello")
+    mw.call(env)
+
+    tool_msg = env[:messages].select { |m| m.role == :tool }.last
+    # Should contain exactly one truncation marker, not two
+    tool_msg.content.scan(/Output truncated/).size.should == 1
+  end
+end

data/lib/brute/middleware/073_otel_tool_call.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+
+module Brute
+  module Middleware
+    # Records tool calls the LLM requested as span events.
+    #
+    # Runs POST-call: after the LLM responds, inspects ctx.functions
+    # for any tool calls the model wants to make, and adds a span event
+    # for each one with the tool name, call ID, and arguments.
+    #
+    class OtelToolCalls
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        #response = @app.call(env)
+
+        #span = env[:span]
+        #if span
+        #  functions = env[:pending_functions]
+        #  if functions && !functions.empty?
+        #    span.set_attribute("brute.tool_calls.count", functions.size)
+
+        #    functions.each do |fn|
+        #      attrs = {
+        #        "tool.name" => fn.name.to_s,
+        #        "tool.id" => fn.id.to_s,
+        #      }
+        #      args = fn.arguments
+        #      attrs["tool.arguments"] = args.to_json if args
+        #      span.add_event("tool_call", attributes: attrs)
+        #    end
+        #  end
+        #end
+
+        #response
+        @app.call(env)
+      end
+    end
+  end
+end
+
+test do
+  # not implemented
+end

data/lib/brute/middleware/075_otel_tool_results.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+
+module Brute
+  module Middleware
+    # Records tool results as span events.
+    #
+    # Tool results are now appended directly to env[:messages] as :tool
+    # role messages. This middleware can inspect the last messages to
+    # record them as span events.
+    #
+    class OtelToolResults
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        #span = env[:span]
+
+        #if span && (results = env[:tool_results])
+        #  span.set_attribute("brute.tool_results.count", results.size)
+
+        #  results.each do |name, value|
+        #    error = value.is_a?(Hash) && value[:error]
+        #    attrs = { "tool.name" => name.to_s }
+        #    if error
+        #      attrs["tool.status"] = "error"
+        #      attrs["tool.error"] = value[:error].to_s
+        #    else
+        #      attrs["tool.status"] = "ok"
+        #    end
+        #    span.add_event("tool_result", attributes: attrs)
+        #  end
+        #end
+
+        @app.call(env)
+      end
+    end
+  end
+end
+
+test do
+  # not implemented
+end

data/lib/brute/middleware/100_llm_call.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+
+module Brute
+  module Middleware
+    # Terminal middleware. Calls the LLM with the current conversation,
+    # appends the response to the session, and fires events along the way.
+    #
+    class LLMCall
+      def call(env)
+
+        available_tools = env[:tools].each_with_object({}) do |tool, hash|
+          instance = tool.is_a?(Class) ? tool.new : tool
+          hash[instance.name.to_sym] = instance
+        end
+
+        completion_options = {
+          model: RubyLLM.models.find(env[:model], env[:provider]),
+          tools: available_tools,
+          temperature: env.fetch(:temperature, 0.7),
+        }
+
+        complete(completion_options, env).then do |response|
+          env[:messages] << response
+        end
+
+        env
+      end
+
+      private
+
+        def complete(kwargs, env)
+          provider_client = RubyLLM::Provider.resolve(env[:provider]).new(Brute.config)
+
+          if env[:streaming] == true
+            provider_client.complete(env[:messages], **kwargs) do |chunk|
+              if chunk.content && !chunk.content.to_s.empty?
+                env[:events] << { type: :content, data: chunk.content.to_s }
+              end
+
+              if chunk.respond_to?(:thinking) && chunk.thinking&.respond_to?(:text) && chunk.thinking.text
+                env[:events] << { type: :reasoning, data: chunk.thinking.text }
+              end
+            end
+          else
+            provider_client.complete(env[:messages], **kwargs).then do |response|
+              if response.content.present?
+                env[:events] << { type: :content, data: response.content }
+              end
+              response
+            end
+          end
+        end
+    end
+  end
+end
+
+test do
+  # not implemented
+end

data/lib/brute/middleware/event_handler.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'brute'
+
+module Brute
+  module Middleware
+    class EventHandler
+      def initialize(app, handler_class:, **opts)
+        @app = app
+        @handler_class = handler_class
+        @opts = opts
+      end
+
+      def call(env)
+        env[:events] = @handler_class.new(env[:events], **@opts)
+        @app.call(env)
+      end
+    end
+  end
+end
+
+test do
+  # not implemented
+end

data/lib/brute/middleware/user_queue.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+
+module Brute
+  module Middleware
+    class UserQueue
+
+      # Useful for testing...
+      # App will keep looping till all inputs are drained.
+      #
+      def initialize(app, inputs: [])
+        @app = app
+        @inputs = inputs
+      end
+
+      def call(env)
+        if @inputs.any?
+          while inputs.any?
+            inputs.shift.then do |input|
+              @app.call(env)
+            end
+          end
+        else
+          @app.call
+        end
+      end
+    end
+  end
+end
+
+test do
+  # not implemented
+end

data/lib/brute/pipeline.rb

@@ -4,79 +4,48 @@ require "bundler/setup"
 require "brute"
 
 module Brute
-  # Rack-style middleware pipeline for LLM calls.
+  # Generic middleware machinery. Builds a chain of middleware around
+  # a terminal app, exposes `call(env)` to invoke it.
   #
-  # Each middleware wraps the next, forming an onion model:
+  # Subclasses (Agent, Tool) override `call` to translate their public
+  # arguments into an env hash, then delegate to super.
   #
-  #   Tracing → Retry → DoomLoop → Reasoning → [LLM Call] → Reasoning → DoomLoop → Retry → Tracing
-  #
-  # The innermost "app" is the actual LLM call. Each middleware can:
-  #   - Modify the env (context, params) BEFORE the call   (pre-processing)
-  #   - Modify or inspect the response AFTER the call       (post-processing)
-  #   - Short-circuit (return without calling inner app)
-  #   - Retry (call inner app multiple times)
-  #
-  # ## The env hash
-  #
-  #   {
-  #     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
-  #
-  #   The return value of call(env) is the LLM::Message from context.talk().
-  #
-  # ## Building a pipeline
-  #
-  #   pipeline = Brute::Pipeline.new do
-  #     use Brute::Middleware::Tracing, logger: logger
-  #     use Brute::Middleware::Retry, max_attempts: 3
-  #     use Brute::Middleware::SessionPersistence, session: session
-  #     run Brute::Middleware::LLMCall.new
+  #   class MyPipeline < Brute::Pipeline
+  #     def call(input)
+  #       env = { input: input, output: nil }
+  #       super(env)
+  #       env[:output]
+  #     end
   #   end
   #
-  #   response = pipeline.call(env)
-  #
   class Pipeline
     def initialize(&block)
       @middlewares = []
       @app = nil
-      instance_eval(&block) if block
+      instance_eval(&block) if block_given?
     end
 
     # Register a middleware class.
     # The class must implement `initialize(app, *args, **kwargs)` and `call(env)`.
     def use(klass, *args, **kwargs, &block)
-      @middlewares << [klass, args, kwargs, block]
-      self
+      tap { @middlewares << [klass, args, kwargs, block] }
     end
 
     # Set the terminal app (innermost handler).
+    # Accepts an instance (anything responding to #call(env)) or a class.
     def run(app)
-      @app = app
-      self
+      tap { @app = app }
     end
 
-    # Build the full middleware chain and call it.
+    # Invoke the chain. Subclasses typically override this to shape env
+    # and extract a return value.
     def call(env)
       build.call(env)
     end
 
     # Build the chain without calling it. Useful for inspection or caching.
     def build
-      raise "Pipeline has no terminal app — call `run` first" unless @app
+      raise "Stack has no terminal app — call `run` first" unless @app
 
       @middlewares.reverse.inject(@app) do |inner, (klass, args, kwargs, block)|
         if block
@@ -86,75 +55,43 @@ module Brute
         end
       end
     end
+
+    # Default null sink for env[:events] — swallows anything pushed to it.
+    class NullSink
+      def <<(_event); self; end
+    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
+  it "builds and calls a chain" do
+    seen = []
+    inc = Class.new do
+      def initialize(app, label:); @app = app; @label = label; end
+      def call(env); env[:trace] << @label; @app.call(env); env[:trace] << "#{@label}-after"; 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)
+    pipeline = Brute::Pipeline.new do
+      use inc, label: "outer"
+      use inc, label: "inner"
+      run ->(env) { env[:trace] << "core" }
+    end
 
-    env = make_env(provider: provider, input: "hello")
+    env = { trace: [] }
     pipeline.call(env)
-    env[:metadata][:timing][:llm_call_count].should == 1
+    env[:trace].should == ["outer", "inner", "core", "inner-after", "outer-after"]
   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
+  it "raises when run was never called" do
+    lambda { Brute::Pipeline.new.call({}) }.should.raise(RuntimeError)
   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)
+  it "accepts a callable as the terminal app" do
+    pipeline = Brute::Pipeline.new do
+      run ->(env) { env[:result] = 42 }
+    end
+    env = {}
+    pipeline.call(env)
+    env[:result].should == 42
   end
 end

data/lib/brute/prompts/skills.rb

@@ -8,10 +8,10 @@ module Brute
     module Skills
       def self.call(ctx)
         cwd = ctx[:cwd] || Dir.pwd
-        skills = Skill.all(cwd: cwd)
+        skills = Brute::Skill.all(cwd: cwd)
         return nil if skills.empty?
 
-        listing = Skill.fmt(skills)
+        listing = Brute::Skill.fmt(skills)
 
         <<~TXT
           Skills provide specialized instructions and workflows for specific tasks.