brute 5.0.4 → 5.1.0

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

@@ -2,146 +2,20 @@
 
 require "bundler/setup"
 require "brute"
-require "brute/truncation"
-require "async"
-require "async/barrier"
+require "gem_kit"
 
 module Brute
   module Middleware
-    class ToolPipeline < Brute::Middleware::Base
-      def initialize(app, tools: [])
-        @app   = app
-        @tools = tools
-      end
-
-      def call(env)
-        env[:tools] = @tools
-        @app.call(env)
-
-        response = env[:messages].last
-
-        if response.respond_to?(:tool_calls) && response.tool_calls.present?
-          tools_to_run = response.tool_calls
-
-          # tool_to_run may be an Array (Brute::ToolCall) or an id-keyed Hash (some libraries' native shape)
-          if tools_to_run.respond_to?(:values)
-            tools_to_run = tools_to_run.values
-          end
-
-          # No idea why we use Array() here... probably in case it's a hash or something...
-          # because reject would work on the hash...
-          tools_to_run = Array(tools_to_run).reject { |tc| tc.name == "question" }
-
-          available_tools = Brute::Tools::Adapter.wrap_all(env[:tools])
-          env[:events] << on_tool_call_start_event(tools_to_run)
-
-          results = []
-
-          # Async::Barrier blocks until all tasks are complete.
-          # Tasks run in parrallel.
-          #
-          Sync do
-            barrier = Async::Barrier.new
-
-            tools_to_run.each do |tool_call|
-              barrier.async do 
-                name = tool_call.name.to_sym
-                args = tool_call.arguments
-
-                # Lifecycle hooks (Brute::Hooks): before_tool may rewrite
-                # :arguments or short-circuit with a :result; approve_tool
-                # denies on a false (or String) return; after_tool may
-                # rewrite :result.
-                call_env = {
-                  name:      name.to_s,
-                  arguments: args,
-                  result:    nil,
-                  denied:    nil,
-                  events:    env[:events],
-                  metadata:  {},
-                  turn_env:  env,
-                }
-                # A subscriber takes part by mutating the call env: set
-                # :result to answer without executing, set :denied to refuse.
-                emit(BEFORE_TOOL_EVENT, env, call_env)
-
-                if call_env[:result].nil?
-                  emit(APPROVE_TOOL_EVENT, env, call_env)
-
-                  if (denial = call_env[:denied])
-                    call_env[:result] = denial.is_a?(String) ? denial : %(Tool call to "#{name}" was denied.)
-                  end
-                end
-
-                # Only the tool's own execution is timed: a call that
-                # before_tool answered, or approve_tool denied, never ran.
-                result = call_env[:result]
-
-                if result.nil?
-                  emit(TOOL_DURATION_EVENT, env, call_env) do
-                    result = available_tools[name].call(call_env[:arguments])
-                  end
-                end
-
-                call_env[:result] = result
-                emit(AFTER_TOOL_EVENT, env, call_env)
-                result = call_env[:result]
-
-                # Coerce to String so Hash results (e.g. Shell's
-                # {stdout:, stderr:, exit_code:}) serialize predictably.
-                if result.is_a?(String)
-                  content = result
-                else
-                  content = result.to_s
-                end
-
-                # Universal truncation safety net — skip if already truncated
-                unless Brute::Truncation.already_truncated?(content)
-                  content = Brute::Truncation.truncate(content)
-                end
-
-                results << [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 << [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.
-          results.sort_by! { |tool_call, _| tools_to_run.index(tool_call) }
-
-          results.each do |tool_call, content|
-            env[:events] << { type: :tool_result, data: { name: tool_call.name, content: content } }
-            env[:messages] << Brute::Message.new(role: :tool, content: content, tool_call_id: tool_call.id)
-          end
-        end
-
-        env
-      end
-
-      private
-
-        def on_tool_call_start_event(pending_tools)
-          {
-            type: :tool_call_start,
-            data: pending_tools.map { |tc|
-              {
-                name: tc.name,
-                call_id: tc.id,
-                arguments: tc.arguments
-              }
-            }
-          }
-        end
+    # The old name for DefaultToolPipeline, kept working while it is
+    # deprecated. The middleware is one particular wiring of tool dispatch and
+    # the name now says so, leaving Brute::Turn::ToolPipeline as the mechanism
+    # to compose when that wiring is not what you want.
+    #
+    #   use Brute::Middleware::DefaultToolPipeline, tools: tools
+    #
+    class ToolPipeline < DefaultToolPipeline
+      extend GemKit::Deprecate
+      superseded_by "Brute::Middleware::DefaultToolPipeline", "6.0"
     end
   end
 end
@@ -149,179 +23,39 @@ end
 __END__
 
 describe "brute/middleware/070_tool_pipeline" do
-  require "brute/messages"
-  require "brute/truncation"
-
-  it "passes through when no tool calls pending" do
-    inner = ->(env) {
-      env[:messages] << Brute::Message.new(role: :assistant, content: "hi")
-    }
-    mw = Brute::Middleware::ToolPipeline.new(inner, tools: [])
-    env = {
-      messages: Brute.log,
-      events: [],
-    }
-    env[:messages].user("hello")
-    mw.call(env)
-    env[:messages].last.content.should == "hi"
-  end
-
-  it "advertises its tools on env[:tools] on the way in" do
-    seen = nil
-    inner = ->(env) { seen = env[:tools] }
-    tool = { name: "echo", description: "", execute: ->(**) { "ok" } }
-    mw = Brute::Middleware::ToolPipeline.new(inner, tools: [tool])
-    env = { messages: Brute.log, events: [] }
-    env[:messages].user("hi")
-    mw.call(env)
-    seen.should == [tool]
-  end
-
-  # --- lifecycle hooks (Brute::Hooks) ---
-
-  # A layer only gets its emit from the builder that made it, so a hook spec
-  # builds a real pipeline rather than instantiating the middleware alone.
-  def hooked(inner, tools:, &subscribe)
-    pipeline = Brute::Turn::Pipeline.new
-    pipeline.use Brute::Middleware::ToolPipeline, tools: tools
-    pipeline.run(Object.new.tap { |o| o.define_singleton_method(:call, &inner) })
-    subscribe.call(pipeline)
-    pipeline
-  end
-
-  def hook_env
-    { messages: Brute.log, events: [] }
-  end
-
-  it "before_tool may rewrite arguments and short-circuit with a result" do
-    tool = { name: "echo", description: "", execute: ->(text:) { "ran:#{text}" } }
-    inner = ->(env) do
-      env[:messages] << Brute::Message.new(role: :assistant, content: "",
-        tool_calls: [{ id: "tc1", name: "echo", arguments: { "text" => "orig" } }])
-    end
-
-    pipeline = hooked(inner, tools: [tool]) do |p|
-      p.on(:before_tool) { |_env, call| call[:arguments] = { text: "rewritten" } }
-    end
-    env = hook_env
-    env[:messages].user("hi")
-    pipeline.call(env)
-    env[:messages].last.content.should == "ran:rewritten"
-
-    canned = hooked(inner, tools: [tool]) { |p| p.on(:before_tool) { |_env, call| call[:result] = "canned" } }
-    env2 = hook_env
-    env2[:messages].user("hi")
-    canned.call(env2)
-    env2[:messages].last.content.should == "canned" # never executed
-  end
-
-  it "approve_tool denies on false (generic message) or String (custom)" do
-    tool = { name: "exec", description: "", execute: ->(**) { "ran" } }
-    inner = ->(env) do
-      env[:messages] << Brute::Message.new(role: :assistant, content: "",
-        tool_calls: [{ id: "tc1", name: "exec", arguments: {} }])
-    end
-
-    denied = hooked(inner, tools: [tool]) { |p| p.on(:approve_tool) { |_env, call| call[:denied] = true } }
-    env = hook_env
-    env[:messages].user("hi")
-    denied.call(env)
-    env[:messages].last.content.should == %(Tool call to "exec" was denied.)
-
-    by_policy = hooked(inner, tools: [tool]) { |p| p.on(:approve_tool) { |_env, call| call[:denied] = "denied by policy" } }
-    env2 = hook_env
-    env2[:messages].user("hi")
-    by_policy.call(env2)
-    env2[:messages].last.content.should == "denied by policy"
-  end
-
-  it "after_tool may rewrite the result" do
-    tool = { name: "echo", description: "", execute: ->(**) { "raw" } }
-    inner = ->(env) do
-      env[:messages] << Brute::Message.new(role: :assistant, content: "",
-        tool_calls: [{ id: "tc1", name: "echo", arguments: {} }])
-    end
-
-    pipeline = hooked(inner, tools: [tool]) do |p|
-      p.on(:after_tool) { |_env, call| call[:result] = "rewrote(#{call[:result]})" }
-    end
-    env = hook_env
-    env[:messages].user("hi")
-    pipeline.call(env)
-    env[:messages].last.content.should == "rewrote(raw)"
-  end
-
-  # --- Universal output truncation ---
-
-  it "truncates large tool results via Truncation" do
-    # A fake tool that returns a huge string
-    big_tool = Class.new(Brute::Tool) do
-      description "test tool"
-      param :input, type: "string", desc: "input"
-      def name; "big_tool"; end
-      def execute(input:)
-        "line\n" * 3000
+  it "still dispatches tools under the old name, and says what to use instead" do
+    warned = []
+    original = GemKit::Deprecate.method(:warn)
+    GemKit::Deprecate.define_singleton_method(:warn) { |message| warned << message }
+
+    begin
+      tool = Brute::Turn::ToolPipeline.new(name: "echo", description: "echo") do
+        run ->(env) { env[:result] = "echoed" }
       end
-    end
 
-    tool_calls = [
-      Brute::ToolCall.new(
-        id: "tc_1",
-        name: "big_tool",
-        arguments: { "input" => "go" },
-      )
-    ]
-
-    inner = ->(env) {
-      env[:messages] << Brute::Message.new(role: :assistant, content: "", tool_calls: tool_calls)
-    }
-    pipeline = hooked(inner, tools: [big_tool]) { |_p| nil }
-    env = {
-      messages: Brute.log,
-      events: [],
-    }
-    env[:messages].user("hello")
-    pipeline.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 ---
+      agent = Brute.agent
+        .use(Brute::Middleware::ToolPipeline, tools: [tool])
+        .run(
+          ->(env) {
+            env[:messages] << Brute::Message.new(
+              role: :assistant,
+              content: "",
+              tool_calls: [{ id: "1", name: "echo", arguments: {} }]
+            )
+          }
+        )
 
-  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(Brute::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
+      agent.start("go")[:messages].last.content.should == "echoed"
+    ensure
+      GemKit::Deprecate.define_singleton_method(:warn, original)
     end
 
-    tool_calls = [
-      Brute::ToolCall.new(
-        id: "tc_2",
-        name: "pre_truncated_tool",
-        arguments: { "input" => "go" },
-      )
-    ]
-
-    inner = ->(env) {
-      env[:messages] << Brute::Message.new(role: :assistant, content: "", tool_calls: tool_calls)
-    }
-    pipeline = hooked(inner, tools: [pre_truncated_tool]) { |_p| nil }
-    env = {
-      messages: Brute.log,
-      events: [],
-    }
-    env[:messages].user("hello")
-    pipeline.call(env)
+    Brute::Middleware::ToolPipeline.ancestors.should.include Brute::Middleware::DefaultToolPipeline
+    warned.first.should.include "Brute::Middleware::DefaultToolPipeline"
+    warned.first.should.include "6.0"
 
-    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
+    declared = GemKit::Deprecate.registry.find { |entry| entry.name == "Brute::Middleware::ToolPipeline" }
+    declared.replacement.should == "Brute::Middleware::DefaultToolPipeline"
+    declared.removed_in.should == Gem::Version.new("6.0")
   end
 end

data/lib/brute/token_counter/approximate.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+
+module Brute
+  module TokenCounter
+    # Tokens from text length, at a flat ratio of characters to tokens.
+    #
+    # Four characters to the token is the usual approximation. It needs no
+    # dependency and it is close enough to decide what to give up; put a
+    # Tiktoken counter on env[:token_counter] when the difference matters.
+    #
+    # `per_message` is what the rendering cannot see: every message is wrapped
+    # in the provider's own chat template on the way out, and that framing
+    # costs a few tokens each whatever the message says.
+    class Approximate
+      def initialize(chars_per_token: 4.0, per_message: 4)
+        unless chars_per_token.positive?
+          raise ArgumentError, "chars_per_token must be greater than 0, got #{chars_per_token}"
+        end
+
+        @chars_per_token = chars_per_token
+        @per_message = per_message
+      end
+
+      def count(messages, tools: nil)
+        text = Rendering.conversation(messages) + Rendering.tools(tools)
+
+        (text.length / @chars_per_token).to_i + (Array(messages).length * @per_message)
+      end
+    end
+  end
+end
+
+__END__
+
+describe "brute/token_counter/approximate" do
+  it "divides the rendered text by the ratio, and charges for the envelope each message rides in" do
+    log = Brute.log
+    log.user("a" * 400)
+
+    # "user: " + 400 characters, four to the token, plus the envelope.
+    Brute::TokenCounter::Approximate.new.count(log).should == 105
+
+    # The ratio and the envelope are both settings, not truths.
+    Brute::TokenCounter::Approximate.new(chars_per_token: 2.0).count(log).should == 207
+    Brute::TokenCounter::Approximate.new(per_message: 0).count(log).should == 101
+
+    Brute::TokenCounter::Approximate.new.count([]).should == 0
+
+    lambda { Brute::TokenCounter::Approximate.new(chars_per_token: 0) }.should.raise(ArgumentError)
+  end
+end

data/lib/brute/token_counter/tiktoken.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+
+module Brute
+  module TokenCounter
+    # Tokens from OpenAI's byte-pair encoder, through the tiktoken_ruby gem.
+    #
+    #   gem "tiktoken_ruby"
+    #   use Brute::Middleware::DefaultCompactionPipeline,
+    #     window:        200_000,
+    #     token_counter: Brute::TokenCounter::Tiktoken.new
+    #
+    # Brute depends on no LLM library, and this is no exception: the gem is
+    # required the first time the counter is asked for a number, so an agent
+    # that never installs it never pays for it and never hears about it.
+    #
+    # It is exact about the text and still approximate about the request --
+    # `per_message` stands in for the chat-template framing, which is the
+    # provider's and not in any encoder.
+    class Tiktoken
+      ENCODING = "o200k_base"
+
+      def initialize(encoding: ENCODING, per_message: 4, encoder: nil)
+        @encoding = encoding
+        @per_message = per_message
+        @encoder = encoder
+      end
+
+      # Load the encoder, downloading its vocabulary if it is not cached yet.
+      def warm_up
+        @encoder ||= load_encoder
+      end
+
+      def count(messages, tools: nil)
+        warm_up
+        text = Rendering.conversation(messages) + Rendering.tools(tools)
+
+        @encoder.encode(text).length + (Array(messages).length * @per_message)
+      end
+
+      private
+
+        def load_encoder
+          begin
+            require "tiktoken_ruby"
+          rescue LoadError
+            raise LoadError, "#{self.class} needs the tiktoken_ruby gem: add `gem \"tiktoken_ruby\"` to your Gemfile"
+          end
+
+          ::Tiktoken.get_encoding(@encoding)
+        end
+    end
+  end
+end
+
+__END__
+
+describe "brute/token_counter/tiktoken" do
+  it "encodes the same rendering the approximate counter measures, and says what to install when it cannot" do
+    encoded = []
+    encoder = Object.new
+    encoder.define_singleton_method(:encode) { |text| encoded << text; text.split(/\b/) }
+
+    log = Brute.log
+    log.user("what changed?")
+
+    counter = Brute::TokenCounter::Tiktoken.new(encoder: encoder, per_message: 4)
+    counter.count(log).should == encoder.encode("user: what changed?").length + 4
+    encoded.last.should == "user: what changed?"
+
+    # The vocabulary is loaded once, on the first count rather than at boot.
+    counter.warm_up.should.equal? encoder
+
+    missing = Brute::TokenCounter::Tiktoken.new(encoding: "nothing-real")
+    missing.define_singleton_method(:require) { |_name| raise LoadError }
+    lambda { missing.count(log) }.should.raise(LoadError).message.should.include "tiktoken_ruby"
+  end
+end

data/lib/brute/token_counter.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+require "json"
+
+module Brute
+  # How big a conversation is, in tokens.
+  #
+  # A counter is anything answering `count(messages, tools: nil)`. The tools
+  # are part of the question because their schemas ride in every request
+  # alongside the messages -- an agent carrying a dozen of them is spending
+  # context on JSON Schema before anyone has said a word.
+  #
+  #   counter = Brute::TokenCounter::Approximate.new
+  #   counter.count(env[:messages], tools: env[:tools])
+  #
+  # What a turn is *currently* costing is a different question, and
+  # `estimate` answers it: the provider counted the conversation exactly when
+  # it answered, so that number is trusted and only what has been appended
+  # since is counted locally.
+  #
+  #   Brute::TokenCounter.estimate(env)
+  #
+  module TokenCounter
+    def self.default = Approximate.new
+
+    # What the whole turn costs right now.
+    #
+    # :counter defaults to the one the turn already decided on
+    # (env[:token_counter]), :tools to the ones the pipeline advertises
+    # (env[:tools]).
+    #
+    # The reported total already covers the system prompt, the tool schemas
+    # and the provider's own chat-template overhead, so the warm path adds
+    # only the messages that landed after the reply it describes -- and never
+    # the schemas, which are already inside it. Anything else double counts.
+    def self.estimate(env, counter: nil, tools: nil)
+      counter ||= env[:token_counter] || default
+      tools = env[:tools] if tools.nil?
+      messages = env[:messages] || []
+      reported = env.dig(:metadata, :last_llm_usage)&.total.to_i
+      answered = messages.rindex { |message| message.role == :assistant }
+
+      # Nothing sent yet, or a conversation the reported number no longer
+      # describes -- a compaction that left no reply behind, say. Count it all.
+      if reported.zero? || answered.nil?
+        counter.count(messages, tools: tools)
+      else
+        reported + counter.count(messages[(answered + 1)..])
+      end
+    end
+
+    # The text a counter measures.
+    #
+    # One rendering, so two counters cannot disagree about what the
+    # conversation even is -- and it is the same text a summariser reads,
+    # which is why it says who spoke and what was called rather than being
+    # the shortest thing that could be measured.
+    module Rendering
+      def self.conversation(messages) = Array(messages).map { |message| message(message) }.join("\n")
+
+      def self.message(message)
+        parts = ["#{message.role}:", message.content.to_s]
+
+        message.tool_calls&.each do |call|
+          parts << "#{call.name}(#{JSON.generate(call.arguments)}) -> #{call.id}"
+        end
+
+        unless message.tool_call_id.nil?
+          parts << "(answering #{message.tool_call_id})"
+        end
+
+        parts.reject(&:empty?).join(" ")
+      end
+
+      # The schemas as the provider is given them, which is what they cost.
+      def self.tools(tools)
+        wrapped = Brute::Tools::Adapter.wrap_all(tools || [])
+
+        if wrapped.empty?
+          ""
+        else
+          JSON.generate(wrapped.values.map(&:to_h))
+        end
+      end
+    end
+  end
+end
+
+__END__
+
+describe "brute/token_counter" do
+  def usage(total) = Brute::UsageDetection::Usage.new(total: total)
+
+  it "measures a conversation and its schemas, and trusts the provider for what it already counted" do
+    log = Brute.log
+    log.system("you are a helpful agent")
+    log.user("what changed?")
+
+    counter = Brute::TokenCounter.default
+    counter.should.be.kind_of Brute::TokenCounter::Approximate
+
+    text = Brute::TokenCounter::Rendering.conversation(log)
+    text.should == "system: you are a helpful agent\nuser: what changed?"
+
+    # A tool call and the result answering it are rendered too -- both cost
+    # tokens, and neither is in the message's content.
+    log << Brute::Message.new(
+      role: :assistant,
+      content: "",
+      tool_calls: [{ id: "tc1", name: "search", arguments: { "query" => "fed" } }]
+    )
+    log.tool("found nothing", tool_call_id: "tc1")
+    Brute::TokenCounter::Rendering.conversation(log).should.include 'search({"query":"fed"}) -> tc1'
+    Brute::TokenCounter::Rendering.conversation(log).should.include "(answering tc1)"
+
+    # Schemas ride in every request, so they are part of the question.
+    tool = Brute::Turn::ToolPipeline.new(name: "search", description: "search the web") do
+      run ->(env) { env[:result] = "" }
+    end
+    Brute::TokenCounter::Rendering.tools(nil).should == ""
+    Brute::TokenCounter::Rendering.tools([tool]).should.include "search the web"
+    counter.count(log, tools: [tool]).should > counter.count(log)
+
+    # Nothing reported yet: everything is counted, schemas included.
+    cold = { messages: log, tools: [tool], metadata: {} }
+    Brute::TokenCounter.estimate(cold).should == counter.count(log, tools: [tool])
+
+    # Reported: the provider's number, plus only what landed after the reply
+    # it describes. The schemas are already inside it.
+    log.assistant("nothing changed")
+    log.user("are you sure?")
+    warm = { messages: log, tools: [tool], metadata: { last_llm_usage: usage(9_000) } }
+    Brute::TokenCounter.estimate(warm).should == 9_000 + counter.count([log.last])
+
+    # A conversation the reported number no longer describes -- a compaction
+    # that left no reply behind -- is counted from scratch rather than added
+    # to a total for a conversation that is gone.
+    stale = { messages: Brute.log.tap { |l| l.user("only me") }, metadata: { last_llm_usage: usage(9_000) } }
+    Brute::TokenCounter.estimate(stale).should == counter.count(stale[:messages])
+
+    # The counter the turn already decided on is the one that gets used.
+    given = { messages: log, metadata: {}, token_counter: Object.new }
+    given[:token_counter].define_singleton_method(:count) { |_messages, tools: nil| 7 }
+    Brute::TokenCounter.estimate(given).should == 7
+  end
+end

data/lib/brute/tools/adapter.rb

@@ -118,6 +118,10 @@ module Brute
         )
       end
 
+      # The tool object this adapter wraps (Brute::Tool, Brute::Turn::ToolPipeline,
+      # SubAgent, Hash definition, ...).
+      attr_reader :original
+
       def initialize(name:, description:, params:, handler:, schema: nil, original: nil)
         @name        = name
         @description = description
@@ -127,10 +131,6 @@ module Brute
         @original    = original
       end
 
-      # The tool object this adapter wraps (Brute::Tool, Brute::Turn::ToolPipeline,
-      # SubAgent, Hash definition, ...).
-      attr_reader :original
-
       # Execute the tool. Accepts string- or symbol-keyed argument hashes,
       # as delivered by LLM providers.
       def call(arguments = {})

data/lib/brute/tools/skill_load.rb

@@ -40,13 +40,13 @@ module Brute
 
       FILE_LIMIT = 10
 
-      def name; "skill"; end
-
       def initialize(cwd: Dir.pwd)
         super()
         @cwd = cwd
       end
 
+      def name; "skill"; end
+
       def execute(name:)
         skill = Brute::Skill.get(name, cwd: @cwd)
         return unknown_skill(name) unless skill