brute 5.1.0 → 6.0.0

data/lib/brute/truncation.rb

@@ -40,7 +40,13 @@ module Brute
     MAX_LINE_LENGTH = 2000
     TRUNCATION_MARKER = "[Output truncated:"
 
-    TRUNCATION_DIR = File.join(Dir.home, ".local", "share", "brute", "tool-output")
+    TRUNCATION_DIR = File.join(
+      Dir.home,
+      ".local",
+      "share",
+      "brute",
+      "tool-output",
+    )
 
     # Truncate text to fit within line and byte limits.
     #
@@ -55,38 +61,48 @@ module Brute
     # @returns [String] the (possibly truncated) text
     #
     def self.truncate(text, max_lines: MAX_LINES, max_bytes: MAX_BYTES, direction: :head, truncation_dir: nil)
-      return text if text.nil? || text.empty?
-
-      # Per-line truncation first — cap individual lines
-      lines = text.lines.map { |line| truncate_line(line) }
-      text = lines.join
-
-      return text if lines.size <= max_lines && text.bytesize <= max_bytes
-
-      # Determine how many lines we can keep within both caps
-      kept = direction == :tail ? lines.last(max_lines) : lines.first(max_lines)
-
-      # Enforce byte cap
-      result_lines = []
-      bytes = 0
-      kept.each do |line|
-        break if bytes + line.bytesize > max_bytes
-        result_lines << line
-        bytes += line.bytesize
-      end
-
-      result = result_lines.join
-      total = lines.size
-      shown = result_lines.size
-
-      # Overflow to disk — save the full output so it can be inspected later
-      saved_path = save_to_disk(text, truncation_dir)
-
-      hint = "\n#{TRUNCATION_MARKER} showing #{shown} of #{total} lines]"
-      if saved_path
-        hint += "\nFull output saved to: #{saved_path}. Use Read with offset/limit to view specific sections."
+      if text.nil? || text.empty?
+        text
+      else
+        # Per-line truncation first — cap individual lines
+        lines = text.lines.map { |line| truncate_line(line) }
+        text = lines.join
+
+        if lines.size <= max_lines && text.bytesize <= max_bytes
+          text
+        else
+          # Determine how many lines we can keep within both caps
+          if direction == :tail
+            kept = lines.last(max_lines)
+          else
+            kept = lines.first(max_lines)
+          end
+
+          # Enforce byte cap
+          result_lines = []
+          bytes = 0
+          kept.each do |line|
+            if bytes + line.bytesize > max_bytes
+              break
+            end
+            result_lines << line
+            bytes += line.bytesize
+          end
+
+          result = result_lines.join
+          total = lines.size
+          shown = result_lines.size
+
+          # Overflow to disk — save the full output so it can be inspected later
+          saved_path = save_to_disk(text, truncation_dir)
+
+          hint = "\n#{TRUNCATION_MARKER} showing #{shown} of #{total} lines]"
+          if saved_path
+            hint += "\nFull output saved to: #{saved_path}. Use Read with offset/limit to view specific sections."
+          end
+          result + hint
+        end
       end
-      result + hint
     end
 
     # Check whether text already contains a truncation marker.
@@ -96,27 +112,36 @@ module Brute
 
     # Truncate a single line if it exceeds MAX_LINE_LENGTH.
     def self.truncate_line(line, max: MAX_LINE_LENGTH)
-      return line if line.length <= max
-      line[0, max] + "... (line truncated to #{max} chars)\n"
+      if line.length <= max
+        line
+      else
+        line[0, max] + "... (line truncated to #{max} chars)\n"
+      end
     end
 
     # Purge files older than retention_days from the given directory.
     def self.cleanup!(dir, retention_days: 7)
-      return unless File.directory?(dir)
-      cutoff = Time.now - (retention_days * 86400)
-      Dir.glob(File.join(dir, "*")).each do |path|
-        File.delete(path) if File.file?(path) && File.mtime(path) < cutoff
+      if File.directory?(dir)
+        cutoff = Time.now - (retention_days * 86400)
+        Dir.glob(File.join(dir, "*")).each do |path|
+          if File.file?(path) && File.mtime(path) < cutoff
+            File.delete(path)
+          end
+        end
+      else
+        nil
       end
     end
 
     # Save text to a file in truncation_dir. Returns the file path, or nil.
     def self.save_to_disk(text, truncation_dir)
       dir = truncation_dir || TRUNCATION_DIR
-      return nil unless dir
-      FileUtils.mkdir_p(dir)
-      path = File.join(dir, "tool_#{SecureRandom.hex(8)}.txt")
-      File.write(path, text)
-      path
+      if dir
+        FileUtils.mkdir_p(dir)
+        path = File.join(dir, "tool_#{SecureRandom.hex(8)}.txt")
+        File.write(path, text)
+        path
+      end
     rescue => _e
       nil
     end

data/lib/brute/turn/agent_pipeline.rb

@@ -38,8 +38,10 @@ module Brute
       # the newest message, only when it is a user message, before the rest
       # of the stack.
       def map(matcher, &block)
-        (@commands ||= []) << [check(matcher), block]
-        self
+        tap do
+          @commands ||= []
+          @commands << [check(matcher), block]
+        end
       end
 
       # Every chain starts with the commands, registry or no registry: the
@@ -50,21 +52,25 @@ module Brute
       end
       alias_method :build, :to_app
 
-      def start(input = nil, events: NullSink.new)
-        env = {
+      def start(input = nil)
+        {
           messages:          coerce_messages(input),
-          events:            events,
           metadata:          {},
           current_iteration: 1,
           commands:          @commands || [],
-        }
-        hooks.emit(TURN_START_EVENT, env)
-        begin
-          hooks.emit(TURN_DURATION_EVENT, env) { build.call(env) }
-        ensure
-          hooks.emit(TURN_END_EVENT, env)
+        }.tap do |turn|
+          Brute::Hooks::Trace.new(turn, hooks: hooks).emit_trace do |env|
+            env.emit(TURN_START_EVENT)
+            begin
+              env.emit(TURN_DURATION_EVENT) { build.call(env) }
+            rescue => error
+              env.emit(TURN_FAILURE_EVENT, error)
+              raise
+            ensure
+              env.emit(TURN_END_EVENT)
+            end
+          end
         end
-        env
       end
 
       private
@@ -86,7 +92,11 @@ module Brute
             matcher
           else
             name = matcher.to_s
-            name = name.start_with?("/") ? name : "/#{name}"
+            if name.start_with?("/")
+              name = name
+            else
+              name = "/#{name}"
+            end
             /^#{::Regexp.escape(name)}.*/
           end
         end

data/lib/brute/turn/compaction_pipeline.rb

@@ -40,18 +40,19 @@ module Brute
     class CompactionPipeline
       def initialize(&block)
         @pipeline = Pipeline.new
-        @pipeline.instance_eval(&block) if block
+        if block
+          @pipeline.instance_eval(&block)
+        end
       end
 
       # Answer a smaller conversation, or nil when nothing was given up.
-      def compact(messages, target:, events: Pipeline::NullSink.new, token_counter: nil)
+      def compact(messages, target:, token_counter: nil)
         env = {
           conversation:  messages,
           target:        target,
           token_counter: token_counter,
           applied:       [],
           messages:      Brute.log,
-          events:        events,
           metadata:      {},
         }
         @pipeline.call(env)

data/lib/brute/turn/pipeline.rb

@@ -21,32 +21,46 @@ module Brute
         #     }
         #
         # Every layer announces itself: :middleware_added when it goes on the
-        # stack, then :enter and :exit around its own work on each turn. Both
-        # of those carry the middleware instance as self, and :exit fires from
+        # stack, then :middleware_start and :middleware_end around its own work on each turn. Both
+        # of those carry the middleware instance as self, and :middleware_end fires from
         # an ensure so a layer that raises is still reported.
         def use(middleware, *args, &block)
           tap do
             super
-            hooks.emit(MIDDLEWARE_ADDED_EVENT, {}, middleware, *args)
-
-            builder = @use.pop
-            @use << lambda do |app|
-              bind_emitter(builder.call(app)).tap do |layer|
-                layer.define_singleton_method(:call) do |env|
-                  emit(ENTER_EVENT, env, self)
-
-                  # The layer's work is :duration's block, so its subscribers
-                  # are handed how long this layer took — its own work plus
-                  # everything below it. :exit then marks the layer done,
-                  # from an ensure so it lands even when the work raised.
-                  result = nil
-                  begin
-                    emit(DURATION_EVENT, env, self) { result = super(env) }
-                  ensure
-                    emit(EXIT_EVENT, env, self)
+            hooks.emit(
+              MIDDLEWARE_ADDED_EVENT,
+              {},
+              middleware,
+              *args,
+            )
+
+            @use.pop.then do |builder|
+              @use << lambda do |app|
+                builder.call(app).tap do |layer|
+                  layer.define_singleton_method(:call) do |env|
+                    result = nil
+
+                    # A layer is one call: what it emits, and what the layers
+                    # below it emit, belong to this trace.
+                    env.emit_trace do |env|
+                      env.emit(MIDDLEWARE_START_EVENT, self)
+
+                      # The layer's work is :middleware_duration's block, so its subscribers
+                      # are handed how long this layer took — its own work plus
+                      # everything below it. :middleware_end then marks the layer done,
+                      # from an ensure so it lands even when the work raised.
+                      begin
+                        env.emit(MIDDLEWARE_DURATION_EVENT, self) { result = super(env) }
+                      rescue => error
+                        env.emit(MIDDLEWARE_FAILURE_EVENT, self, error)
+                        raise
+                      ensure
+                        env.emit(MIDDLEWARE_END_EVENT, self)
+                      end
+                    end
+
+                    result
                   end
-
-                  result
                 end
               end
             end
@@ -55,11 +69,12 @@ module Brute
         # Keeps a trailing hash flagged as keywords through `super`, the way
         # Rack::Builder#use does — without it `use Mw, label: "x"` arrives at
         # the middleware's constructor as a positional Hash.
-        ruby2_keywords(:use) if respond_to?(:ruby2_keywords, true)
+        if respond_to?(:ruby2_keywords, true)
+          ruby2_keywords(:use)
+        end
 
         def run(app = nil, &block)
           tap do
-            bind_emitter(app) unless app.nil?
             super
           end
         end
@@ -69,62 +84,40 @@ module Brute
         #   Brute.agent
         #     .use(MaxProfit)
         #     .run(->(env) { ... })
-        #     .on(:before_llm) { |env| ... }
-        #     .on(:approve_tool) { |call| call[:name] != "exec" }
+        #     .on(:llm_start) { |env| ... }
+        #     .on(:tool_approve) { |call| call[:name] != "exec" }
         #
         def on(...) = tap { hooks.on(...) }
 
         private
 
-          # Bind an emit() to this builder's store, so a layer fires events at
-          # the pipeline it belongs to rather than fishing them out of env.
-          def bind_emitter(object)
-            if object.is_a?(Proc)
-              warn("brute: #{self.class} was given a lambda, which cannot be given an emit — its events will not fire")
-              return object
-            end
 
-            if object.respond_to?(:emit)
-              raise ArgumentError, "#{object.class} already defines #emit, so the pipeline will not bind its own over it"
-            end
-
-            store = hooks
-            object.define_singleton_method(:emit) do |event, env, *extras, &work|
-              store.emit(event, env, *extras, &work)
-            end
-            object
-          end
-
-        public
+          public
       end
 
       include Chainable
 
-      # Rack's `new_from_string` evaluates the script then returns `to_app` —
-      # the built callable. An agent, though, is the *builder*: you `.start` it,
-      # and it may be re-`use`d or served through the Rack adapter. So evaluate
-      # the script against a fresh builder and hand back the builder itself.
-      # This also backs `parse_file` (→ `load_file` → here), so
-      # `AgentPipeline.parse_file("agent.ru").start(prompt)` works as documented.
       def self.new_from_string(builder_script, path = "(rackup)", **options)
-        builder = new(**options)
-        eval(builder_script, ::Rack::BUILDER_TOPLEVEL_BINDING.call(builder), path) # rubocop:disable Security/Eval
-        builder
+        new(**options).tap do |builder|
+          eval(builder_script, ::Rack::BUILDER_TOPLEVEL_BINDING.call(builder), path) # rubocop:disable Security/Eval
+        end
       end
 
-      # Brute's name for Rack's `to_app`: nest the middleware around the
-      # terminal app and return the runnable callable. Raises (via `to_app`)
-      # when `run` was never called.
+      # Brute's name for Rack's `to_app`
       alias_method :build, :to_app
 
-      # The lifecycle-hook registry for this pipeline (see Brute::Hooks).
-      def hooks
-        @hooks ||= Brute::Hooks.new
+      def initialize(default_app = nil, hooks: Brute::Hooks::Registry.new, **options, &block)
+        @hooks = hooks
+        super(default_app, **options, &block)
       end
 
-      # Default null sink for env[:events] — swallows anything pushed to it.
-      class NullSink
-        def <<(_event); self; end
+      attr_reader :hooks
+
+      # Every way into a pipeline arrives at a Trace: what a caller hands over
+      # is wrapped once, and a pipeline entered from inside another keeps the
+      # trace it was already in.
+      def call(env)
+        env.is_a?(Brute::Hooks::Trace) ? super : super(Brute::Hooks::Trace.new(env, hooks: hooks))
       end
     end
   end
@@ -135,11 +128,11 @@ __END__
 describe "brute/turn/pipeline" do
   it "announces a layer when it is added, then on the way in and out of every turn" do
     seen = []
-    hooks = Brute::Hooks.new
+    hooks = Brute::Hooks::Registry.new
     hooks.on(Brute::Hooks::MIDDLEWARE_ADDED_EVENT) { |env, mw, *args| seen << [:added, env, mw, args] }
-    hooks.on(Brute::Hooks::ENTER_EVENT) { |_env, layer| seen << [:enter, layer.class] }
-    hooks.on(Brute::Hooks::DURATION_EVENT) { |_env, started, finished, layer| seen << [:duration, layer.class, finished >= started] }
-    hooks.on(Brute::Hooks::EXIT_EVENT) { |_env, layer| seen << [:exit, layer.class] }
+    hooks.on(Brute::Hooks::MIDDLEWARE_START_EVENT) { |_env, layer| seen << [:middleware_start, layer.class] }
+    hooks.on(Brute::Hooks::MIDDLEWARE_DURATION_EVENT) { |_env, started, finished, layer| seen << [:middleware_duration, layer.class, finished >= started] }
+    hooks.on(Brute::Hooks::MIDDLEWARE_END_EVENT) { |_env, layer| seen << [:middleware_end, layer.class] }
 
     labeller = Class.new do
       def initialize(app, label:); @app = app; @label = label; end
@@ -153,12 +146,12 @@ describe "brute/turn/pipeline" do
     pipeline.call({ hooks: hooks })
 
     seen.first.should == [:added, {}, labeller, [{ label: "outer" }]]
-    seen[1].should == [:enter, labeller]
-    seen[2].should == [:duration, labeller, true]
-    seen[3].should == [:exit, labeller]
+    seen[1].should == [:middleware_start, labeller]
+    seen[2].should == [:middleware_duration, labeller, true]
+    seen[3].should == [:middleware_end, labeller]
   end
 
-  it "reports a layer that raises through :exit anyway" do
+  it "reports a layer that raises through :middleware_end anyway" do
     seen = []
 
     boom = Class.new do
@@ -167,7 +160,7 @@ describe "brute/turn/pipeline" do
     end
 
     pipeline = Brute::Turn::Pipeline.new
-    pipeline.on(Brute::Hooks::EXIT_EVENT) { |_env, layer| seen << layer.class }
+    pipeline.on(Brute::Hooks::MIDDLEWARE_END_EVENT) { |_env, layer| seen << layer.class }
     pipeline.use boom
     pipeline.run Object.new.tap { |o| o.define_singleton_method(:call) { |env| env } }
     begin
@@ -179,42 +172,40 @@ describe "brute/turn/pipeline" do
     seen.should == [boom]
   end
 
-  it "binds emit to its own store, warns for a lambda, and refuses to shadow an existing emit" do
+  it "wraps what it is called with in a trace, so a layer emits without being given anything" do
     seen = []
     quiet = Class.new do
       def initialize(app); @app = app; end
-      def call(env); emit(:ping, env, :from_layer); @app.call(env); end
+      def call(env); env.emit(:ping, :from_layer); @app.call(env); end
     end
 
     pipeline = Brute::Turn::Pipeline.new
-    pipeline.on(:ping) { |env, extra| seen << [env, extra] }
+    pipeline.on(:ping) { |env, extra, id| seen << [env[:said], extra, id] }
     pipeline.use quiet
     pipeline.run Object.new.tap { |o| o.define_singleton_method(:call) { |env| env } }
-    pipeline.call({})
-    seen.should == [[{}, :from_layer]]
-
-    # A lambda cannot reach the bound method, so it is warned about, not patched.
-    warned = []
-    lambda_pipeline = Brute::Turn::Pipeline.new
-    lambda_pipeline.define_singleton_method(:warn) { |message| warned << message }
-    lambda_pipeline.run ->(env) { env }
-    warned.size.should == 1
-    warned.first.should.match(/lambda/)
-
-    # An object that already answers to emit is left alone, loudly.
-    emitter = Class.new do
-      def initialize(app); @app = app; end
-      def emit(*); end
-      def call(env); env; end
+    pipeline.call({ said: "hello" })
+
+    said, extra, id = seen.first
+    said.should == "hello"
+    extra.should == :from_layer
+    id.should.not.be.nil
+
+    # A lambda is a layer like any other now: it is handed the trace as its env.
+    answered = []
+    Brute::Turn::Pipeline.new.tap do |lambdas|
+      lambdas.on(:ping) { |_env, extra| answered << extra }
+      lambdas.run ->(env) { env.emit(:ping, :from_lambda); env }
+      lambdas.call({})
     end
-    # The layer is constructed when the stack is built, so that is when the
-    # collision is discovered.
-    shadowing = Brute::Turn::Pipeline.new
-    shadowing.use emitter
-    shadowing.run Object.new.tap { |o| o.define_singleton_method(:call) { |env| env } }
-    should.raise(ArgumentError) { shadowing.call({}) }
+    answered.should == [:from_lambda]
+
+    # Given a registry it uses that one rather than building its own, so a
+    # nested pipeline reports to the agent that owns it.
+    shared = Brute::Hooks::Registry.new
+    Brute::Turn::Pipeline.new(hooks: shared).hooks.equal?(shared).should.be.true
   end
 
+
   it "builds and calls a chain" do
     seen = []
     inc = Class.new do

data/lib/brute/turn/tool_pipeline.rb

@@ -38,15 +38,16 @@ module Brute
         @description = description
         @params      = params
         @pipeline    = Pipeline.new
-        @pipeline.instance_eval(&block) if block
+        if block
+          @pipeline.instance_eval(&block)
+        end
       end
 
-      def call(events: Pipeline::NullSink.new, **arguments)
+      def call(**arguments)
         env = {
           name:      @name,
           arguments: arguments,
           result:    nil,
-          events:    events,
           metadata:  {},
         }
         @pipeline.call(env)

data/lib/brute/usage_detection/llmrb.rb

@@ -11,20 +11,24 @@ module Brute
     # reading of the response and it is reported as given.
     module LLMrb
       def self.detect(response)
-        return nil unless response.respond_to?(:usage)
-
-        usage = response.usage
-        return nil if usage.nil?
-
-        Usage.new(
-          input:       read(usage, :input_tokens),
-          output:      read(usage, :output_tokens),
-          total:       read(usage, :total_tokens),
-          reasoning:   read(usage, :reasoning_tokens),
-          cache_read:  read(usage, :cache_read_tokens),
-          cache_write: read(usage, :cache_write_tokens),
-          raw:         usage,
-        )
+        if response.respond_to?(:usage)
+          usage = response.usage
+          if usage.nil?
+            nil
+          else
+            Usage.new(
+              input:       read(usage, :input_tokens),
+              output:      read(usage, :output_tokens),
+              total:       read(usage, :total_tokens),
+              reasoning:   read(usage, :reasoning_tokens),
+              cache_read:  read(usage, :cache_read_tokens),
+              cache_write: read(usage, :cache_write_tokens),
+              raw:         usage,
+            )
+          end
+        else
+          nil
+        end
       end
 
       def self.read(usage, name) = usage.respond_to?(name) ? usage.public_send(name) : nil

data/lib/brute/usage_detection/open_router.rb

@@ -11,23 +11,26 @@ module Brute
     # arrive nested under completion_tokens_details.
     module OpenRouter
       def self.detect(response)
-        return nil unless response.respond_to?(:usage)
-
-        usage = response.usage
-        return nil if usage.nil?
-
-        usage = usage.to_h
-        details = (usage["completion_tokens_details"] || usage[:completion_tokens_details] || {}).to_h
-
-        Usage.new(
-          input:     field(usage, "prompt_tokens"),
-          output:    field(usage, "completion_tokens"),
-          total:     field(usage, "total_tokens"),
-          reasoning: field(details, "reasoning_tokens"),
-          cache_read: field(usage, "cached_tokens"),
-          cost:      field(usage, "cost"),
-          raw:       usage,
-        )
+        if response.respond_to?(:usage)
+          usage = response.usage
+          if usage.nil?
+            nil
+          else
+            usage = usage.to_h
+            details = (usage["completion_tokens_details"] || usage[:completion_tokens_details] || {}).to_h
+            Usage.new(
+              input:      field(usage, "prompt_tokens"),
+              output:     field(usage, "completion_tokens"),
+              total:      field(usage, "total_tokens"),
+              reasoning:  field(details, "reasoning_tokens"),
+              cache_read: field(usage, "cached_tokens"),
+              cost:       field(usage, "cost"),
+              raw:        usage,
+            )
+          end
+        else
+          nil
+        end
       end
 
       # OpenRouter hands back string keys; a hand-built response may not.

data/lib/brute/usage_detection/ruby_llm.rb

@@ -11,20 +11,24 @@ module Brute
     # provider's own reported_cost when it gives one.
     module RubyLLM
       def self.detect(message)
-        return nil unless message.respond_to?(:tokens)
-
-        tokens = message.tokens
-        return nil if tokens.nil?
-
-        Usage.new(
-          input:       read(tokens, :input),
-          output:      read(tokens, :output),
-          reasoning:   read(tokens, :thinking),
-          cache_read:  read(tokens, :cache_read),
-          cache_write: read(tokens, :cache_write),
-          cost:        read(tokens, :reported_cost),
-          raw:         tokens,
-        )
+        if message.respond_to?(:tokens)
+          tokens = message.tokens
+          if tokens.nil?
+            nil
+          else
+            Usage.new(
+              input:       read(tokens, :input),
+              output:      read(tokens, :output),
+              reasoning:   read(tokens, :thinking),
+              cache_read:  read(tokens, :cache_read),
+              cache_write: read(tokens, :cache_write),
+              cost:        read(tokens, :reported_cost),
+              raw:         tokens,
+            )
+          end
+        else
+          nil
+        end
       end
 
       def self.read(tokens, name) = tokens.respond_to?(name) ? tokens.public_send(name) : nil

data/lib/brute/usage_detection/usage.rb

@@ -19,7 +19,16 @@ module Brute
   # turn are the env's business, not the reader's. A strategy answers nil when
   # the provider reported nothing at all.
   module UsageDetection
-    Usage = Data.define(:input, :output, :total, :reasoning, :cache_read, :cache_write, :cost, :raw) do
+    Usage = Data.define(
+      :input,
+      :output,
+      :total,
+      :reasoning,
+      :cache_read,
+      :cache_write,
+      :cost,
+      :raw,
+    ) do
       def initialize(input: nil, output: nil, total: nil, reasoning: nil,
                      cache_read: nil, cache_write: nil, cost: nil, raw: nil)
         super