brute 5.0.5 → 6.0.0

data/lib/brute/completion/llmrb.rb

@@ -44,34 +44,35 @@ module Brute
       end
 
       def call(env)
-        emit(BEFORE_LLM_EVENT, env)
+        env.emit_trace do |env|
+          env.emit(LLM_START_EVENT)
 
-        # llm.rb takes the last message as the prompt and the rest as history.
-        messages = Brute::MessageTransport::LLM.dump_all(env[:messages])
-        prompt = messages.pop
+          # llm.rb takes the last message as the prompt and the rest as history.
+          messages = Brute::MessageTransport::LLM.dump_all(env[:messages])
+          prompt = messages.pop
 
-        response = nil
-        emit(LLM_DURATION_EVENT, env) { response = client(env).complete(prompt, **params(env, messages)) }
+          response = nil
+          env.emit(LLM_DURATION_EVENT) { response = client(env).complete(prompt, **params(env, messages)) }
 
-        if (usage = Brute::MessageTransport::LLM.usage_metrics(response))
-          (env[:metadata] ||= {})[:last_llm_usage] = usage
-        end
+          if (usage = Brute::MessageTransport::LLM.usage_metrics(response))
+            (env[:metadata] ||= {})[:last_llm_usage] = usage
+          end
 
-        Brute::MessageTransport::LLM.wrap_each(response) do |message|
-          env[:messages] << message
-        end
+          Brute::MessageTransport::LLM.wrap_each(response) do |message|
+            env[:messages] << message
+          end
 
-        emit(AFTER_LLM_EVENT, env)
-        env
-      rescue => error
-        emit(LLM_FAILURE_EVENT, env)
+          env.emit(LLM_END_EVENT)
+        rescue => error
+          env.emit(LLM_FAILURE_EVENT)
 
-        if defined?(::Faraday::Error) && error.is_a?(::Faraday::Error)
-          emit(FARADAY_ERROR_EVENT, env, error)
-        else
-          emit(STANDARD_ERROR_EVENT, env, error)
-        end
+          if defined?(::Faraday::Error) && error.is_a?(::Faraday::Error)
+            env.emit(FARADAY_ERROR_EVENT, error)
+          else
+            env.emit(STANDARD_ERROR_EVENT, error)
+          end
 
+        end
         env
       end
 
@@ -80,16 +81,17 @@ module Brute
         attr_reader :options
 
         def params(env, history)
-          params = {
+          {
             role:        nil,
             model:       option(env, :model),
             messages:    history,
             temperature: temperature(env),
-          }.compact
-
-          functions = functions(env)
-          params[:tools] = functions if functions.any?
-          params
+          }.compact.tap do |params|
+            functions = functions(env)
+            if functions.any?
+              params[:tools] = functions
+            end
+          end
         end
 
         def client(env)
@@ -154,8 +156,8 @@ describe "brute/completion/llmrb" do
     seen = []
     pipeline = Brute::Turn::Pipeline.new
     pipeline.run Brute::Completion::LLMrb.new(client: client, temperature: 0.1)
-    pipeline.on(Brute::Hooks::BEFORE_LLM_EVENT) { |_env| seen << :before }
-    pipeline.on(Brute::Hooks::AFTER_LLM_EVENT) { |_env| seen << :after }
+    pipeline.on(Brute::Hooks::LLM_START_EVENT) { |_env| seen << :before }
+    pipeline.on(Brute::Hooks::LLM_END_EVENT) { |_env| seen << :after }
     pipeline.call(env)
 
     env[:messages].last.role.should == :assistant

data/lib/brute/completion/open_router.rb

@@ -43,52 +43,53 @@ module Brute
       end
 
       def call(env)
-        emit(BEFORE_LLM_EVENT, env)
-
-        messages = Brute::MessageTransport::OpenRouter.dump_all(env[:messages])
-
-        ::OpenRouter::Client.new(**@config).then do |client|
-          response = nil
-          emit(LLM_DURATION_EVENT, env) { response = client.complete(messages, options(env)) }
-
-          response.then do |response|
-
-            # Expose the provider's usage for downstream accounting
-            # (goal budgets, autonomous limits, compaction thresholds, usage
-            # attribution) — additive metadata only, normalised so a reader
-            # does not have to know which provider answered.
-            if (usage = Brute::MessageTransport::OpenRouter.usage_metrics(response))
-              (env[:metadata] ||= {})[:last_llm_usage] = usage
-            end
-
-            # OpenRouter in fact only returns a single message...
-            # https://github.com/estiens/open_router_enhanced/blob/main/lib/open_router/response.rb
-            Brute::MessageTransport::OpenRouter.wrap_each(response) do |message|
-              env[:messages] << message
+        env.emit_trace do |env|
+          env.emit(LLM_START_EVENT)
+
+          messages = Brute::MessageTransport::OpenRouter.dump_all(env[:messages])
+
+          ::OpenRouter::Client.new(**@config).then do |client|
+            response = nil
+            env.emit(LLM_DURATION_EVENT) { response = client.complete(messages, options(env)) }
+
+            response.then do |response|
+
+              # Expose the provider's usage for downstream accounting
+              # (goal budgets, autonomous limits, compaction thresholds, usage
+              # attribution) — additive metadata only, normalised so a reader
+              # does not have to know which provider answered.
+              if (usage = Brute::MessageTransport::OpenRouter.usage_metrics(response))
+                (env[:metadata] ||= {})[:last_llm_usage] = usage
+              end
+
+              # OpenRouter in fact only returns a single message...
+              # https://github.com/estiens/open_router_enhanced/blob/main/lib/open_router/response.rb
+              Brute::MessageTransport::OpenRouter.wrap_each(response) do |message|
+                env[:messages] << message
+              end
             end
           end
-        end
 
-        emit(AFTER_LLM_EVENT, env)
-        env
-      # A provider call that raises is reported through the hooks rather than
-      # up the stack: :llm_failure with the turn env, then one hook naming the
-      # kind of failure. The classes are looked up defensively — the provider
-      # gem is only a dependency of the app that uses this middleware.
-      rescue => error
-        emit(LLM_FAILURE_EVENT, env)
+          env.emit(LLM_END_EVENT)
+        # A provider call that raises is reported through the hooks rather than
+        # up the stack: :llm_failure with the turn env, then one hook naming the
+        # kind of failure. The classes are looked up defensively — the provider
+        # gem is only a dependency of the app that uses this middleware.
+        rescue => error
+          env.emit(LLM_FAILURE_EVENT)
 
-        if defined?(::Faraday::Error) && error.is_a?(::Faraday::Error)
-          emit(FARADAY_ERROR_EVENT, env, error)
+          if defined?(::Faraday::Error) && error.is_a?(::Faraday::Error)
+            env.emit(FARADAY_ERROR_EVENT, error)
 
-        elsif defined?(::OpenRouter::ServerError) && error.is_a?(::OpenRouter::ServerError)
-          emit(OPEN_ROUTER_SERVER_ERROR_EVENT, env, error)
+          elsif defined?(::OpenRouter::ServerError) && error.is_a?(::OpenRouter::ServerError)
+            env.emit(OPEN_ROUTER_SERVER_ERROR_EVENT, error)
 
-        else
-          emit(STANDARD_ERROR_EVENT, env, error)
+          else
+            env.emit(STANDARD_ERROR_EVENT, error)
 
-        end
+          end
 
+        end
         env
       end
 
@@ -100,7 +101,9 @@ module Brute
 
           unless @options.tools?
             tools = tool_definitions(env)
-            overrides[:tools] = tools if tools.any?
+            if tools.any?
+              overrides[:tools] = tools
+            end
           end
 
           if !@model_given && (model = env[:model])
@@ -266,7 +269,7 @@ describe "brute/completion/open_router" do
       env[:messages].user("hi")
       pipeline = Brute::Turn::Pipeline.new
       pipeline.run Brute::Completion::OpenRouter.new
-      %i[llm_failure standard_error after_llm].each do |event|
+      %i[llm_failure standard_error llm_end].each do |event|
         pipeline.on(event) { |hook_env, extra| seen << [event, hook_env, extra] }
       end
       returned = pipeline.call(env)

data/lib/brute/completion/ruby_llm.rb

@@ -59,35 +59,36 @@ module Brute
       end
 
       def call(env)
-        emit(BEFORE_LLM_EVENT, env)
+        env.emit_trace do |env|
+          env.emit(LLM_START_EVENT)
 
-        messages = Brute::MessageTransport::RubyLLM.dump_all(env[:messages])
-        response = nil
-        emit(LLM_DURATION_EVENT, env) { response = complete(env, messages) }
+          messages = Brute::MessageTransport::RubyLLM.dump_all(env[:messages])
+          response = nil
+          env.emit(LLM_DURATION_EVENT) { response = complete(env, messages) }
 
-        unless response.nil?
-          if (usage = Brute::MessageTransport::RubyLLM.usage_metrics(response))
-            (env[:metadata] ||= {})[:last_llm_usage] = usage
+          unless response.nil?
+            if (usage = Brute::MessageTransport::RubyLLM.usage_metrics(response))
+              (env[:metadata] ||= {})[:last_llm_usage] = usage
+            end
+
+            Brute::MessageTransport::RubyLLM.wrap_each(response) do |message|
+              env[:messages] << message
+            end
           end
 
-          Brute::MessageTransport::RubyLLM.wrap_each(response) do |message|
-            env[:messages] << message
+          env.emit(LLM_END_EVENT)
+        # A provider call that raises is reported through the hooks rather than
+        # up the stack, the same way the OpenRouter completion does it.
+        rescue => error
+          env.emit(LLM_FAILURE_EVENT)
+
+          if defined?(::Faraday::Error) && error.is_a?(::Faraday::Error)
+            env.emit(FARADAY_ERROR_EVENT, error)
+          else
+            env.emit(STANDARD_ERROR_EVENT, error)
           end
-        end
 
-        emit(AFTER_LLM_EVENT, env)
-        env
-      # A provider call that raises is reported through the hooks rather than
-      # up the stack, the same way the OpenRouter completion does it.
-      rescue => error
-        emit(LLM_FAILURE_EVENT, env)
-
-        if defined?(::Faraday::Error) && error.is_a?(::Faraday::Error)
-          emit(FARADAY_ERROR_EVENT, env, error)
-        else
-          emit(STANDARD_ERROR_EVENT, env, error)
         end
-
         env
       end
 
@@ -104,7 +105,7 @@ module Brute
 
           provider_client = client(option(env, :provider))
 
-          # Streaming reports through env[:events] chunk by chunk; the final
+          # Streaming reports through :content and :reasoning chunk by chunk; the final
           # message still comes back for the log.
           if streaming?(env)
             provider_client.complete(messages, **kwargs) do |chunk|
@@ -117,11 +118,11 @@ module Brute
 
         def stream(env, chunk)
           if chunk.content && !chunk.content.to_s.empty?
-            env[:events] << { type: :content, data: chunk.content.to_s }
+            env.emit(CONTENT_EVENT, 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 }
+            env.emit(REASONING_EVENT, chunk.thinking.text)
           end
         end
 
@@ -214,8 +215,8 @@ describe "brute/completion/ruby_llm" do
 
     seen = []
     pipeline = running.call(Brute::Completion::RubyLLM.new(client: client, model: "use-this-model", temperature: 0.1))
-    pipeline.on(Brute::Hooks::BEFORE_LLM_EVENT) { |_env| seen << :before }
-    pipeline.on(Brute::Hooks::AFTER_LLM_EVENT) { |_env| seen << :after }
+    pipeline.on(Brute::Hooks::LLM_START_EVENT) { |_env| seen << :before }
+    pipeline.on(Brute::Hooks::LLM_END_EVENT) { |_env| seen << :after }
     pipeline.call(env)
 
     env[:messages].last.role.should == :assistant

data/lib/brute/contrib/otel.rb

@@ -19,8 +19,8 @@ module Brute
     # Every event it needs already exists:
     #
     #   turn_start / turn_end   the span itself
-    #   after_llm               token usage, from env[:metadata][:last_llm_usage]
-    #   before_tool / after_tool a span event per tool call and result
+    #   llm_end               token usage, from env[:metadata][:last_llm_usage]
+    #   tool_start / tool_end   a span event per tool call and result
     #
     # The tracer is injectable; without one it asks OpenTelemetry, and when
     # the SDK is not loaded `subscribe` does nothing at all.
@@ -35,33 +35,50 @@ module Brute
 
       class << self
         def subscribe(agent, tracer: default_tracer)
-          return agent if tracer.nil?
-
-          agent
-            .on(Brute::Hooks::TURN_START_EVENT) { |env| start(env, tracer) }
-            .on(Brute::Hooks::TURN_END_EVENT) { |env| finish(env) }
-            .on(Brute::Hooks::AFTER_LLM_EVENT) { |env| record_usage(env) }
-            .on(Brute::Hooks::BEFORE_TOOL_EVENT) { |env, call| tool_called(env, call) }
-            .on(Brute::Hooks::AFTER_TOOL_EVENT) { |env, call| tool_returned(env, call) }
-            .on(Brute::Hooks::LLM_FAILURE_EVENT) { |env| failed(env) }
-            .on(Brute::Hooks::DURATION_EVENT) { |env, started, finished, layer| layer_finished(env, started, finished, layer) }
-            .on(Brute::Hooks::TURN_DURATION_EVENT) { |env, started, finished| timed(env, "turn", finished - started) }
-            .on(Brute::Hooks::LLM_DURATION_EVENT) { |env, started, finished| timed(env, "llm", finished - started) }
-            .on(Brute::Hooks::TOOL_DURATION_EVENT) { |env, started, finished, call| timed(env, "tool", finished - started, "tool.name" => call[:name].to_s) }
+          if tracer.nil?
+            agent
+          else
+            agent
+              .on(Brute::Hooks::TURN_START_EVENT) { |env| start(env, tracer) }
+              .on(Brute::Hooks::TURN_END_EVENT) { |env| finish(env) }
+              .on(Brute::Hooks::LLM_END_EVENT) { |env| record_usage(env) }
+              .on(Brute::Hooks::TOOL_START_EVENT) { |env, call| tool_called(env, call) }
+              .on(Brute::Hooks::TOOL_END_EVENT) { |env, call| tool_returned(env, call) }
+              .on(Brute::Hooks::LLM_FAILURE_EVENT) { |env| failed(env) }
+              .on(Brute::Hooks::MIDDLEWARE_DURATION_EVENT) { |env, started, finished, layer| layer_finished(
+                env,
+                started,
+                finished,
+                layer,
+              ) }
+              .on(Brute::Hooks::TURN_DURATION_EVENT) { |env, started, finished| timed(env, "turn", finished - started) }
+              .on(Brute::Hooks::LLM_DURATION_EVENT) { |env, started, finished| timed(env, "llm", finished - started) }
+              .on(Brute::Hooks::TOOL_DURATION_EVENT) { |env, started, finished, call| timed(
+                env,
+                "tool",
+                finished - started,
+                "tool.name" => call[:name].to_s,
+              ) }
+          end
         end
 
         def default_tracer
-          return nil unless defined?(::OpenTelemetry)
-
-          ::OpenTelemetry.tracer_provider.tracer("brute", Brute::VERSION)
+          if defined?(::OpenTelemetry)
+            ::OpenTelemetry.tracer_provider.tracer("brute", Brute::VERSION)
+          else
+            nil
+          end
         end
 
         private
 
           def start(env, tracer)
-            env[:span] = tracer.start_span(SPAN_NAME, attributes: {
-              "brute.messages" => env[:messages]&.size,
-            }.compact)
+            env[:span] = tracer.start_span(
+              SPAN_NAME,
+              attributes: {
+                "brute.messages" => env[:messages]&.size,
+              }.compact,
+            )
           end
 
           def finish(env)
@@ -73,40 +90,55 @@ module Brute
           # arrives under the same names, and what it did not report is
           # absent rather than zero.
           def record_usage(env)
-            span = env[:span] or return
-            usage = env.dig(:metadata, :last_llm_usage) or return
-
-            {
-              "gen_ai.usage.input_tokens"     => usage.input,
-              "gen_ai.usage.output_tokens"    => usage.output,
-              "gen_ai.usage.total_tokens"     => usage.total,
-              "gen_ai.usage.reasoning_tokens" => usage.reasoning,
-              "gen_ai.usage.cache_read_tokens" => usage.cache_read,
-              "gen_ai.usage.cost"             => usage.cost,
-            }.each { |name, value| span.set_attribute(name, value) unless value.nil? }
+            span  = env[:span]
+            usage = env.dig(:metadata, :last_llm_usage)
+
+            if span && usage
+              {
+                "gen_ai.usage.input_tokens"      => usage.input,
+                "gen_ai.usage.output_tokens"     => usage.output,
+                "gen_ai.usage.total_tokens"      => usage.total,
+                "gen_ai.usage.reasoning_tokens"  => usage.reasoning,
+                "gen_ai.usage.cache_read_tokens" => usage.cache_read,
+                "gen_ai.usage.cost"              => usage.cost,
+              }.each do |name, value|
+                unless value.nil?
+                  span.set_attribute(name, value)
+                end
+              end
+            end
           end
 
           def tool_called(env, call)
-            env[:span]&.add_event("tool_call", attributes: {
-              "tool.name"      => call[:name].to_s,
-              "tool.arguments" => call[:arguments].to_s,
-            })
+            env[:span]&.add_event(
+              "tool_call",
+              attributes: {
+                "tool.name"      => call[:name].to_s,
+                "tool.arguments" => call[:arguments].to_s,
+              },
+            )
           end
 
           def tool_returned(env, call)
-            env[:span]&.add_event("tool_result", attributes: {
-              "tool.name"  => call[:name].to_s,
-              "tool.bytes" => call[:result].to_s.bytesize,
-            })
+            env[:span]&.add_event(
+              "tool_result",
+              attributes: {
+                "tool.name"  => call[:name].to_s,
+                "tool.bytes" => call[:result].to_s.bytesize,
+              },
+            )
           end
 
-          # The layer's work is :duration's block, so start and finish arrive
-          # with it rather than having to be correlated with :enter by hand.
+          # The layer's work is :middleware_duration's block, so start and finish arrive
+          # with it rather than having to be correlated with :middleware_start by hand.
           def layer_finished(env, started, finished, layer)
-            env[:span]&.add_event("middleware", attributes: {
-              "middleware.name"     => layer.class.name.to_s,
-              "middleware.duration" => finished - started,
-            })
+            env[:span]&.add_event(
+              "middleware",
+              attributes: {
+                "middleware.name"     => layer.class.name.to_s,
+                "middleware.duration" => finished - started,
+              },
+            )
           end
 
           # Every pair in the turn has a timed middle, so each one's duration
@@ -157,7 +189,7 @@ describe "brute/contrib/otel" do
     tool = { name: "echo", description: "", execute: ->(text:) { "ran:#{text}" } }
 
     agent = Brute::Turn::AgentPipeline.new
-    agent.use Brute::Middleware::ToolPipeline, tools: [tool]
+    agent.use Brute::Middleware::DefaultToolPipeline, tools: [tool]
     agent.run(Object.new.tap do |terminal|
       terminal.define_singleton_method(:call) do |env|
         # A completion records usage and announces the call; `run` bound this
@@ -170,8 +202,8 @@ describe "brute/contrib/otel" do
             tool_calls: [{ id: "tc1", name: "echo", arguments: { "text" => "hi" } }])
         end
 
-        emit(Brute::Hooks::LLM_DURATION_EVENT, env) { :provider_call }
-        emit(Brute::Hooks::AFTER_LLM_EVENT, env)
+        env.emit(Brute::Hooks::LLM_DURATION_EVENT) { :provider_call }
+        env.emit(Brute::Hooks::LLM_END_EVENT)
         env
       end
     end)
@@ -190,9 +222,9 @@ describe "brute/contrib/otel" do
     span.events.map(&:first).should.include "tool_result"
     span.events.find { |name, _| name == "tool_call" }.last["tool.name"].should == "echo"
 
-    # :exit is timed, so each layer reports its own duration.
+    # :middleware_end is timed, so each layer reports its own duration.
     layer_event = span.events.find { |name, _| name == "middleware" }
-    layer_event.last["middleware.name"].should == "Brute::Middleware::ToolPipeline"
+    layer_event.last["middleware.name"].should == "Brute::Middleware::DefaultToolPipeline"
     layer_event.last["middleware.duration"].should.be >= 0
 
     # Each pair's timed middle reports its own duration.

data/lib/brute/env.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+
+module Brute
+  # What the turn came back with, asked of the env itself.
+  #
+  #   env = agent.start("hello")
+  #   env.extend(Brute::Env)
+  #   env.reply.content if env.has_reply?
+  #
+  # A turn ends with whatever the last middleware left in env[:messages], and
+  # that is not always an answer: a turn that only ran tools, or that the
+  # provider failed, ends on something else. So the reply is the last message
+  # AND only when the assistant is the one who wrote it.
+  module Env
+    def has_reply?
+      !reply.nil?
+    end
+
+    def reply
+      messages = self[:messages]
+
+      if messages.respond_to?(:last) && messages.last&.role == :assistant
+        messages.last
+      end
+    end
+  end
+end
+
+__END__
+
+require "brute/messages"
+
+describe "brute/env" do
+  it "answers whether the turn produced a reply, and what it was" do
+    env = { messages: Brute.log }.extend(Brute::Env)
+
+    env.has_reply?.should.be.false
+
+    env[:messages].user("hello")
+    env.has_reply?.should.be.false
+
+    env[:messages].assistant("hi back")
+    env.has_reply?.should.be.true
+    env.reply.content.should == "hi back"
+
+    env[:messages] << Brute::Message.new(role: :tool, content: "ran", tool_call_id: "tc1")
+    env.has_reply?.should.be.false
+
+    {}.extend(Brute::Env).has_reply?.should.be.false
+  end
+end