brute 5.0.5 → 6.0.0

data/lib/brute/turn/compaction_pipeline.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+require "brute/turn/pipeline"
+
+module Brute
+  module Turn
+    # A compactor built out of middleware.
+    #
+    # Like ToolPipeline it *composes* a Pipeline rather than inheriting: the
+    # definition block is instance_eval'd into the internal Pipeline, so `use`
+    # / `run` inside it are the builder's methods.
+    #
+    # The stack order is the policy. A layer that got the conversation under
+    # target does not call the next one, so the strategies that cost nothing
+    # sit at the top and the terminal app -- the summariser, the only thing
+    # here that spends money -- is reached only when they could not get there.
+    # That is `run` meaning what it means everywhere else in Brute: the model
+    # call, at the bottom, with the layers deciding what reaches it.
+    #
+    #   Brute::Turn::CompactionPipeline.new do
+    #     use Brute::Compaction::Middleware::ToolResults,   keep_steps: 1
+    #     use Brute::Compaction::Middleware::SlidingWindow, keep_steps: 2
+    #
+    #     run Brute::Compaction::Summarize.new(
+    #       Brute::Completion::OpenRouter.new(config: { access_token: key }),
+    #     )
+    #   end
+    #
+    # A pipeline that must never spend a call is the first two layers and
+    # `run ->(env) { env }` -- a policy said out loud rather than configured.
+    #
+    # The conversation being compacted rides on `env[:conversation]`, leaving
+    # `env[:messages]` to mean what it means to every other terminal app in
+    # Brute: the prompt going down, the reply coming back.
+    #
+    # It answers #compact, so what comes out drops into
+    # Brute::Middleware::DefaultCompactionPipeline as that turn's compactor.
+    class CompactionPipeline
+      def initialize(&block)
+        @pipeline = Pipeline.new
+        if block
+          @pipeline.instance_eval(&block)
+        end
+      end
+
+      # Answer a smaller conversation, or nil when nothing was given up.
+      def compact(messages, target:, token_counter: nil)
+        env = {
+          conversation:  messages,
+          target:        target,
+          token_counter: token_counter,
+          applied:       [],
+          messages:      Brute.log,
+          metadata:      {},
+        }
+        @pipeline.call(env)
+
+        unless env[:applied].empty?
+          env[:conversation]
+        end
+      end
+    end
+  end
+end
+
+__END__
+
+describe "brute/turn/compaction_pipeline" do
+  def said(content) = Brute::Message.new(role: :user, content: content)
+
+  def layer(name, &block)
+    Class.new(Brute::Compaction::Middleware::Strategy) do
+      define_method(:strategy) { name }
+      define_method(:rewrite) { |conversation, target:| block.call(conversation, target) }
+    end
+  end
+
+  it "composes strategies into one compactor, and only reaches run when they could not" do
+    reached = []
+    halves = layer("halves") { |c, _t| reached << "halves"; c.first(c.length / 2) }
+    never  = layer("never")  { |_c, _t| reached << "never"; nil }
+    # A terminal belongs to one pipeline: the builder binds an emit onto it
+    # and refuses to bind a second, so each pipeline gets its own.
+    terminal = lambda do
+      Object.new.tap { |it| it.define_singleton_method(:call) { |env| reached << "run"; env } }
+    end
+
+    four = [said("a" * 4_000), said("b" * 4_000), said("c" * 4_000), said("d" * 4_000)]
+
+    # Halving is enough, so the terminal -- the one that costs money -- is
+    # never reached. The stack order is the policy.
+    pipeline = Brute::Turn::CompactionPipeline.new do
+      use halves
+      run terminal.call
+    end
+    pipeline.compact(four, target: 3_000).map { |m| m.content[0, 1] }.should == ["a", "b"]
+    reached.should == ["halves"]
+
+    # A strategy that declines lets the turn fall through to it.
+    reached.clear
+    Brute::Turn::CompactionPipeline.new do
+      use never
+      run terminal.call
+    end.compact(four, target: 3_000).should.be.nil
+    reached.should == ["never", "run"]
+
+    # Nothing given up at all is nil, not the conversation it was handed --
+    # the caller applies whatever else comes back.
+    reached.clear
+    pipeline.compact(four, target: 500_000).should.be.nil
+    reached.should == []
+
+    # The conversation rides on :conversation, leaving :messages to mean what
+    # it means to every other terminal app -- the prompt down, the reply back.
+    seen = nil
+    Brute::Turn::CompactionPipeline.new do
+      run ->(env) { seen = [env[:conversation].length, env[:messages], env[:target]] }
+    end.compact(four, target: 10)
+    seen.should == [4, [], 10]
+  end
+end

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

data/lib/brute/utils/diff.rb

@@ -12,17 +12,25 @@ module Brute
       old_lines = old_text.lines
       new_lines = new_text.lines
       diffs = ::Diff::LCS.diff(old_lines, new_lines)
-      return '' if diffs.empty?
-
-      output = +''
-      file_length_difference = 0
-      diffs.each do |piece|
-        hunk = ::Diff::LCS::Hunk.new(old_lines, new_lines, piece, context, file_length_difference)
-        file_length_difference = hunk.file_length_difference
-        output << hunk.diff(:unified)
-        output << "\n"
+      if diffs.empty?
+        ''
+      else
+        output = +''
+        file_length_difference = 0
+        diffs.each do |piece|
+          hunk = ::Diff::LCS::Hunk.new(
+            old_lines,
+            new_lines,
+            piece,
+            context,
+            file_length_difference,
+          )
+          file_length_difference = hunk.file_length_difference
+          output << hunk.diff(:unified)
+          output << "\n"
+        end
+        output
       end
-      output
     end
   end
 end

data/lib/brute/version.rb

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