brute 4.3.2 → 5.0.0

data/lib/brute/completion/ruby_llm.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+require "brute/hooks"
+
+module Brute
+  module Completion
+    # Completion backed by the ruby_llm gem.
+    #
+    #   Brute.agent
+    #     .use(Brute::Middleware::SystemPrompt)
+    #     .run(Brute::Completion::RubyLLM.new(provider: :ollama, model: "llama3.2:latest"))
+    #
+    # Anything not given at point of use falls back to env, so a pipeline that
+    # sets env[:provider] / env[:model] still flows through.
+    #
+    #   provider:    LLM provider name (falls back to env[:provider])
+    #   model:       model id (falls back to env[:model])
+    #   tools:       tools list, any shape Tools::Adapter accepts
+    #   temperature: sampling temperature (default 0.7)
+    #   streaming:   stream chunks as :content / :reasoning events
+    #   client:      injectable completion client (tests, custom transports);
+    #                anything responding to complete(messages, **kwargs)
+    class RubyLLM
+      include Brute::Hooks
+
+      DEFAULT_TEMPERATURE = 0.7
+
+      def initialize(**options)
+        # Brute depends on no LLM library: the provider gem is required here,
+        # at point of use, and only for this completion.
+        begin
+          require "ruby_llm"
+        rescue LoadError
+          raise LoadError, "#{self.class} needs the 'ruby_llm' gem — add `gem \"ruby_llm\"` to your Gemfile."
+        end
+
+        Brute::Completion.async_faraday!
+
+        @options = options
+      end
+
+      def call(env)
+        emit(BEFORE_LLM_EVENT, env)
+
+        messages = Brute::MessageTransport::RubyLLM.dump_all(env[:messages])
+        response = nil
+        emit(LLM_DURATION_EVENT, env) { response = complete(env, messages) }
+
+        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
+
+        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
+
+      private
+
+        attr_reader :options
+
+        def complete(env, messages)
+          kwargs = {
+            model:       resolve_model(option(env, :model), option(env, :provider)),
+            tools:       tool_adapters(env).transform_values(&:to_ruby_llm),
+            temperature: temperature(env),
+          }
+
+          provider_client = client(option(env, :provider))
+
+          # Streaming reports through env[:events] chunk by chunk; the final
+          # message still comes back for the log.
+          if streaming?(env)
+            provider_client.complete(messages, **kwargs) do |chunk|
+              stream(env, chunk)
+            end
+          else
+            provider_client.complete(messages, **kwargs)
+          end
+        end
+
+        def stream(env, chunk)
+          if chunk.content && !chunk.content.to_s.empty?
+            env[:events] << { type: :content, data: chunk.content.to_s }
+          end
+
+          if chunk.respond_to?(:thinking) && chunk.thinking.respond_to?(:text) && chunk.thinking&.text
+            env[:events] << { type: :reasoning, data: chunk.thinking.text }
+          end
+        end
+
+        def client(provider)
+          options[:client] || ::RubyLLM::Provider.resolve(provider).new(Brute.config)
+        end
+
+        # Look the model up in ruby_llm's registry; fall back to the raw id for
+        # models the registry doesn't know (custom endpoints, injected clients).
+        def resolve_model(model, provider)
+          ::RubyLLM.models.find(model, provider)
+        rescue StandardError
+          model
+        end
+
+        # Point-of-use option, falling back to env.
+        def option(env, key) = options.fetch(key) { env[key] }
+
+        def temperature(env) = options.fetch(:temperature) { env.fetch(:temperature, DEFAULT_TEMPERATURE) }
+
+        def tool_adapters(env) = Brute::Tools::Adapter.wrap_all(option(env, :tools) || [])
+
+        def streaming?(env) = options.fetch(:streaming) { env[:streaming] } == true
+    end
+  end
+end
+
+__END__
+
+describe "brute/completion/ruby_llm" do
+  require "brute/messages"
+
+  FakeRubyLLMClient = Class.new do
+    attr_reader :calls
+
+    def initialize(content = "mock response")
+      @content = content
+      @calls = []
+    end
+
+    def complete(messages, **kwargs)
+      @calls << { messages: messages.dup, kwargs: kwargs }
+      Brute::Message.new(role: :assistant, content: @content)
+    end
+  end unless defined?(FakeRubyLLMClient)
+
+  # A completion only gets its emit from the pipeline that runs it.
+  running = lambda do |completion|
+    Brute::Turn::Pipeline.new.tap { |pipeline| pipeline.run completion }
+  end
+
+  it "completes a turn, prefers point-of-use options over env, and reports failure through the hooks" do
+    client = FakeRubyLLMClient.new("hello there")
+    env = { messages: Brute.log, provider: :stub, model: "env-model", tools: [], events: [] }
+    env[:messages].user("hi")
+
+    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.call(env)
+
+    env[:messages].last.role.should == :assistant
+    env[:messages].last.content.should == "hello there"
+    seen.should == [:before, :after]
+
+    client.calls.first[:kwargs][:model].should == "use-this-model"
+    client.calls.first[:kwargs][:temperature].should == 0.1
+
+    # Unset options fall back to env, and temperature to its default.
+    fallback = FakeRubyLLMClient.new
+    fallback_env = { messages: Brute.log, provider: :stub, model: "env-model", tools: [], events: [] }
+    fallback_env[:messages].user("hi")
+    running.call(Brute::Completion::RubyLLM.new(client: fallback)).call(fallback_env)
+    fallback.calls.first[:kwargs][:model].should == "env-model"
+    fallback.calls.first[:kwargs][:temperature].should == 0.7
+
+    # A raising provider is reported, not propagated.
+    boom = Object.new
+    boom.define_singleton_method(:complete) { |_messages, **_kwargs| raise "no route to host" }
+    failed = []
+    failing = running.call(Brute::Completion::RubyLLM.new(client: boom))
+    failing.on(Brute::Hooks::LLM_FAILURE_EVENT) { |_env| failed << :failure }
+    failing.on(Brute::Hooks::STANDARD_ERROR_EVENT) { |_env, error| failed << error.message }
+
+    error_env = { messages: Brute.log, provider: :stub, tools: [], events: [] }
+    error_env[:messages].user("hi")
+    failing.call(error_env).should.be.identical_to error_env
+    failed.should == [:failure, "no route to host"]
+  end
+end

data/lib/brute/contrib/otel.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+require "brute/hooks"
+
+module Brute
+  module Contrib
+    # OpenTelemetry for a turn, as hooks rather than middleware.
+    #
+    #   Brute::Contrib::Otel.subscribe(agent)
+    #   agent.start("what changed?")
+    #
+    # These are pure observers: they read the turn and write spans, and never
+    # touch what the agent does. That is why they are subscribers and not
+    # layers — a middleware earns its place in the stack by being able to
+    # alter or skip what is below it, and telemetry never should.
+    #
+    # 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
+    #
+    # The tracer is injectable; without one it asks OpenTelemetry, and when
+    # the SDK is not loaded `subscribe` does nothing at all.
+    #
+    # Note the span is opened and finished by hand rather than through
+    # `tracer.in_span`, which wants a block around the work. OpenTelemetry's
+    # current context is fiber-local, so this does not attach the span as
+    # current: under Async a turn's LLM call and its tools may run in other
+    # fibers, and an attached-but-never-detached context leaks across them.
+    module Otel
+      SPAN_NAME = "brute.turn"
+
+      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) }
+        end
+
+        def default_tracer
+          return nil unless defined?(::OpenTelemetry)
+
+          ::OpenTelemetry.tracer_provider.tracer("brute", Brute::VERSION)
+        end
+
+        private
+
+          def start(env, tracer)
+            env[:span] = tracer.start_span(SPAN_NAME, attributes: {
+              "brute.messages" => env[:messages]&.size,
+            }.compact)
+          end
+
+          def finish(env)
+            env[:span]&.finish
+          end
+
+          # The completions record a Brute::UsageDetection::Usage, so this
+          # needs no per-provider knowledge: whatever the provider reported
+          # 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? }
+          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,
+            })
+          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,
+            })
+          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.
+          def layer_finished(env, started, finished, layer)
+            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
+          # lands as an attribute without correlating its edges.
+          def timed(env, name, duration, attributes = {})
+            env[:span]&.set_attribute("brute.#{name}.duration", duration)
+            env[:span]&.add_event("#{name}_duration", attributes: attributes.merge("duration" => duration))
+          end
+
+          def failed(env)
+            env[:span]&.add_event("llm_failure")
+          end
+      end
+    end
+  end
+end
+
+__END__
+
+describe "brute/contrib/otel" do
+  FakeSpan = Class.new do
+    attr_reader :attributes, :events, :finished
+
+    def initialize(name, attributes)
+      @name = name
+      @attributes = attributes.dup
+      @events = []
+      @finished = false
+    end
+
+    def set_attribute(name, value) = @attributes[name] = value
+    def add_event(name, attributes: {}) = @events << [name, attributes]
+    def finish = @finished = true
+  end unless defined?(FakeSpan)
+
+  FakeTracer = Class.new do
+    attr_reader :spans
+
+    def initialize = @spans = []
+
+    def start_span(name, attributes: {})
+      FakeSpan.new(name, attributes).tap { |span| @spans << span }
+    end
+  end unless defined?(FakeTracer)
+
+  it "spans a turn, records normalised usage, and notes each tool call and result" do
+    tracer = FakeTracer.new
+    tool = { name: "echo", description: "", execute: ->(text:) { "ran:#{text}" } }
+
+    agent = Brute::Turn::AgentPipeline.new
+    agent.use Brute::Middleware::ToolPipeline, 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
+        # emit to the pipeline's own store.
+        env[:metadata][:last_llm_usage] = Brute::UsageDetection::Usage.new(input: 10, output: 5, total: 15)
+
+        unless env[:called]
+          env[:called] = true
+          env[:messages] << Brute::Message.new(role: :assistant, content: "",
+            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
+      end
+    end)
+
+    Brute::Contrib::Otel.subscribe(agent, tracer: tracer)
+    agent.start("go")
+
+    span = tracer.spans.first
+    span.finished.should.be.true
+    span.attributes["gen_ai.usage.total_tokens"].should == 15
+    span.attributes["gen_ai.usage.input_tokens"].should == 10
+    # Not reported by this provider, so never set.
+    span.attributes.key?("gen_ai.usage.cost").should.be.false
+
+    span.events.map(&:first).should.include "tool_call"
+    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.
+    layer_event = span.events.find { |name, _| name == "middleware" }
+    layer_event.last["middleware.name"].should == "Brute::Middleware::ToolPipeline"
+    layer_event.last["middleware.duration"].should.be >= 0
+
+    # Each pair's timed middle reports its own duration.
+    span.attributes["brute.turn.duration"].should.be >= 0
+    span.attributes["brute.llm.duration"].should.be >= 0
+    span.attributes["brute.tool.duration"].should.be >= 0
+    span.events.find { |name, _| name == "tool_duration" }.last["tool.name"].should == "echo"
+
+    # Without a tracer — the SDK not loaded — subscribing is a no-op.
+    quiet = Brute::Turn::AgentPipeline.new
+    Brute::Contrib::Otel.subscribe(quiet, tracer: nil).should.be.identical_to quiet
+  end
+end

data/lib/brute/hooks.rb

@@ -10,49 +10,130 @@ module Brute
   #     .use(Brute::Middleware::MaxIterations)
   #     .run(->(env) { env[:messages].assistant("done") })
   #     .on(:before_llm) { |env| ... }
-  #     .on(:approve_tool) { |call| call[:name] != "exec" }
+  #     .on(:approve_tool) { |_env, call| call[:name] != "exec" }
+  #
+  # Every subscriber is called with the turn env first, followed by whatever
+  # extras that event carries. A block that only wants the env can take one
+  # argument and ignore the rest.
   #
   # Emission points and payloads:
   #
   #   :turn_start, :turn_end  → the turn env (AgentPipeline#start; turn_end
-  #                             fires from an ensure, so it also fires on error)
+  #                             fires from an ensure, so it also fires on
+  #                             error)
+  #   :turn_duration          → env, started, finished: the turn's work is
+  #                             this event's block
+  #   :middleware_added       → an empty env, then the middleware and every
+  #                             argument `use` was given (fires at build time,
+  #                             so only subscribers registered before the `use`
+  #                             see it)
+  #   :enter                  → env, the middleware instance, before the
+  #                             layer does anything
+  #   :duration               → env, started, finished, the middleware
+  #                             instance: the layer's work is this event's
+  #                             block, so it reports how long that took
+  #   :exit                   → env, the middleware instance, marking the
+  #                             layer done (from an ensure, so it fires on
+  #                             error too)
   #   :before_llm, :after_llm → the turn env, around every LLM call
+  #   :llm_duration           → env, started, finished: the provider call is
+  #                             this event's block
   #   :llm_failure            → the turn env, when the LLM call raises; the
   #                             completion middleware then emits one of
   #                             :faraday_error, :open_router_server_error or
-  #                             :standard_error with the exception itself
-  #   :before_tool            → call env {name:, arguments:, result:, events:,
-  #                             metadata:, turn_env:} — mutate :arguments to
-  #                             rewrite the call, or set :result (or return a
-  #                             value) to skip execution entirely ("respond")
-  #   :approve_tool           → call env — a false return denies the call; a
-  #                             String return denies it with that message
-  #   :after_tool             → call env — mutate :result
+  #                             :standard_error with the exception as an extra
+  #   :before_tool            → env, call env {name:, arguments:, result:,
+  #                             denied:, events:, metadata:, turn_env:} —
+  #                             mutate :arguments to rewrite the call, or set
+  #                             :result to answer it without executing
+  #   :approve_tool           → env, call env — set :denied to true to deny
+  #                             the call, or to a String to deny it with that
+  #                             message
+  #   :tool_duration          → env, started, finished, call env: the tool's
+  #                             own execution is this event's block, so a
+  #                             skipped or denied call never fires it
+  #   :after_tool             → env, call env — mutate :result
   #
   # Subscribers run inline (tool events may fire from parallel threads).
   # Exceptions propagate to the caller — layers that want fail-open semantics
   # rescue in their own subscriber.
-  class Hooks
-    EVENTS = %i[turn_start turn_end before_llm after_llm llm_failure faraday_error
-                open_router_server_error standard_error before_tool approve_tool
-                after_tool].freeze
+  # Include this in anything that emits or subscribes and the event names are
+  # first class there: ENTER_EVENT rather than Brute::Hooks::ENTER_EVENT.
+  # The registry itself is Hooks::Registry, and Brute::Hooks.new builds one.
+  module Hooks
+    TURN_START_EVENT = :turn_start
+    TURN_DURATION_EVENT = :turn_duration
+    TURN_END_EVENT = :turn_end
+    MIDDLEWARE_ADDED_EVENT = :middleware_added
+    ENTER_EVENT = :enter
+    DURATION_EVENT = :duration
+    EXIT_EVENT = :exit
+    BEFORE_LLM_EVENT = :before_llm
+    LLM_DURATION_EVENT = :llm_duration
+    AFTER_LLM_EVENT = :after_llm
+    LLM_FAILURE_EVENT = :llm_failure
+    FARADAY_ERROR_EVENT = :faraday_error
+    OPEN_ROUTER_SERVER_ERROR_EVENT = :open_router_server_error
+    STANDARD_ERROR_EVENT = :standard_error
+    BEFORE_TOOL_EVENT = :before_tool
+    APPROVE_TOOL_EVENT = :approve_tool
+    TOOL_DURATION_EVENT = :tool_duration
+    AFTER_TOOL_EVENT = :after_tool
 
-    def initialize
-      @subscribers = Hash.new { |hash, key| hash[key] = [] }
-    end
+    # The pub/sub registry a pipeline owns; `use` and `run` bind an emit to it.
+    class Registry
+      def initialize
+        @subscribers = Hash.new { |hash, key| hash[key] = [] }
+      end
 
-    def on(event, &block)
-      @subscribers[event.to_sym] << block
-      self
-    end
+      def on(event, &block)
+        @subscribers[event.to_sym] << block
+        self
+      end
+
+      # Fire an event. An emitter announces; it answers nothing, and what a
+      # subscriber's block happens to evaluate to is not a signal. A layer
+      # that wants to take part in a turn does it by mutating what it was
+      # handed, never by returning something.
+      #
+      # Given a block, the event is timed instead: the block is the work, and
+      # subscribers fire once it is done, called as
+      # `|env, started, finished, *extras|` rather than `|env, *extras|`.
+      # Both stamps are monotonic, so a clock adjustment mid-turn cannot
+      # produce a negative duration.
+      #
+      # The block is the work and nothing more: `emit` answers nothing in
+      # either form, so a caller that needs the work's value takes it inside
+      # the block.
+      #
+      #   result = nil
+      #   emit(DURATION_EVENT, env, self) { result = @app.call(env) }
+      #   # => .on(DURATION_EVENT) { |env, started, finished, layer| ... }
+      #
+      # Subscribers fire from an ensure, so work that raises is still timed
+      # and still reported before the exception carries on up.
+      def emit(event, env, *extras, &block)
+        unless block
+          @subscribers[event.to_sym].each { |subscriber| subscriber.call(env, *extras) }
+          return nil
+        end
+
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
 
-    # Fire an event; returns every subscriber's raw result (nils and false
-    # included — the deny contract distinguishes them).
-    def emit(event, payload)
-      @subscribers[event.to_sym].map { |subscriber| subscriber.call(payload) }
+        begin
+          block.call
+        ensure
+          finished = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          @subscribers[event.to_sym].each { |subscriber| subscriber.call(env, started, finished, *extras) }
+        end
+
+        nil
+      end
+
+      def any?(event) = @subscribers[event.to_sym].any?
     end
 
-    def any?(event) = @subscribers[event.to_sym].any?
+    def self.new(...) = Registry.new(...)
   end
 end
 
@@ -62,16 +143,53 @@ describe "brute/hooks" do
   it "emits to subscribers in registration order" do
     hooks = Brute::Hooks.new
     seen = []
-    hooks.on(:before_llm) { |p| seen << "a#{p}" }
-    hooks.on(:before_llm) { |p| seen << "b#{p}" }
+    hooks.on(:before_llm) { |env| seen << "a#{env}" }
+    hooks.on(:before_llm) { |env| seen << "b#{env}" }
     hooks.emit(:before_llm, 1)
     seen.should == ["a1", "b1"]
   end
 
-  it "returns raw results, false included (deny contract)" do
+  it "answers nothing: a subscriber takes part by mutating, not by returning" do
     hooks = Brute::Hooks.new
-    hooks.on(:approve_tool) { |_call| false }
-    hooks.emit(:approve_tool, {}).should == [false]
+    hooks.on(:approve_tool) { |_env, call| call[:denied] = true }
+
+    call = {}
+    hooks.emit(:approve_tool, {}, call).should.be.nil
+    call[:denied].should.be.true
+  end
+
+  it "hands every subscriber the env first and the extras after" do
+    hooks = Brute::Hooks.new
+    seen = []
+    hooks.on(:after_tool) { |env, call| seen << [env, call] }
+    hooks.emit(:after_tool, :turn, :call)
+    seen.should == [[:turn, :call]]
+  end
+
+  it "times a block, hands subscribers start and finish, and reports even when the work raises" do
+    seen = []
+    hooks = Brute::Hooks.new
+    hooks.on(:exit) { |env, started, finished, subject| seen << [env, started, finished, subject] }
+
+    ran = nil
+    hooks.emit(:exit, :env, :layer) { ran = :work_result }.should.be.nil
+    ran.should == :work_result
+    seen.size.should == 1
+    env, started, finished, subject = seen.first
+    env.should == :env
+    subject.should == :layer
+    (finished - started).should.be >= 0
+
+    # Work that raises is still timed and still reported.
+    should.raise(RuntimeError) { hooks.emit(:exit, :env, :layer) { raise "boom" } }
+    seen.size.should == 2
+
+    # Without a block it stays a point event: no timing argument.
+    args = []
+    hooks2 = Brute::Hooks.new
+    hooks2.on(:exit) { |*received| args << received }
+    hooks2.emit(:exit, :env, :layer)
+    args.should == [[:env, :layer]]
   end
 
   it "answers any? and stays chainable" do

data/lib/brute/message_transport/lang_chain.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+require "brute/message_transport"
+require "brute/message_transport/ruby_open_ai"
+
+module Brute
+  class MessageTransport
+    # MessageTransport for the langchainrb gem. Its LLM classes speak the
+    # OpenAI-style wire format, so the message conversion is RubyOpenAI's —
+    # what differs is usage, which langchainrb answers through per-provider
+    # response methods rather than a usage object.
+    class LangChain < RubyOpenAI
+      def self.usage_metrics(response)
+        Brute::UsageDetection::LangChain.detect(response)
+      end
+    end
+  end
+end
+
+__END__
+
+describe "brute/message_transport/lang_chain" do
+  LangChainUsageResponse = Struct.new(:prompt_tokens, :completion_tokens, :total_tokens) unless defined?(LangChainUsageResponse)
+
+  it "reads usage the langchainrb way and converts messages the OpenAI way" do
+    usage = Brute::MessageTransport::LangChain.usage_metrics(LangChainUsageResponse.new(10, 5, 15))
+    usage.input.should == 10
+    usage.total.should == 15
+
+    dumped = Brute::MessageTransport::LangChain.dump(Brute::Message.new(role: :user, content: "hi"))
+    dumped[:role].should == "user"
+    dumped[:content].should == "hi"
+  end
+end

data/lib/brute/message_transport/llm.rb

@@ -17,6 +17,12 @@ module Brute
     #   response = llm.complete(messages.pop, role: nil, messages: messages, tools: ...)
     #   Brute::MessageTransport::LLM.wrap_each(response) { |m| env[:messages] << m }
     class LLM < MessageTransport
+
+      # What the provider reported about this call — the transport knows its
+      # own library's shape, so it knows which detector to ask.
+      def self.usage_metrics(response)
+        Brute::UsageDetection::LLMrb.detect(response)
+      end
       # Brute::Message -> LLM::Message. Assistant tool calls carry llm.rb's
       # `original_tool_calls` extra (the provider wire format); tool results
       # become an LLM::Function::Return so llm.rb's request adapters emit

data/lib/brute/message_transport/open_router.rb

@@ -13,6 +13,12 @@ module Brute
     #
     #   require "open_router"
     class OpenRouter < MessageTransport
+
+      # What the provider reported about this call — the transport knows its
+      # own library's shape, so it knows which detector to ask.
+      def self.usage_metrics(response)
+        Brute::UsageDetection::OpenRouter.detect(response)
+      end
       def self.dump(message)
         message.to_h
       end