brute 4.0.0 → 4.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 65f8fa383e8c2d5793cc4ec00023ee6d2117e75535a81676617232b94748f154
-  data.tar.gz: 88f3794d39b79c3c7c03c96f54383fa8647850be1cfc77ae8877fb6ea42aa365
+  metadata.gz: 6016495cc66cb0d8c5b7b33aaef14eee694960355bb2d772c2d75b1aaacca844
+  data.tar.gz: 137446fd33a37736993e2d067d75169d8ca1ce83c109511054b73e768550fda5
 SHA512:
-  metadata.gz: 57b849d89d406b624fe26dcbc93aa84af2f9b90b12160fb57608938ec53fd7109c87aa3d2c1357620c78f88b9702f797ff106432840a5e4ccaca343f49e7035a
-  data.tar.gz: d73709348a3f205f034389e86950a5ce171d0fd0bf62a9c9e84ad587d3ac322aad211b94d059a93b9b19e16a0c1b6211baebd7f274b88435c1cf61a9a6373007
+  metadata.gz: 4098f01a58d7d6946fb4f362aab7d37db86cb1f6e77def51f96e08b86eddbaa8c5462e8a613d9e74ff84731baf5ed65076abd010c2ab854b5e838279b3801ee3
+  data.tar.gz: 25c4986d4beed8103eb6c0f527ad737b98de3f7c3d1e562c83f956afcc3b3267eb5c6cb669ac488cf9ffdf97c6a446888f9363a2d01bd6f3913701d7cc46c313

data/lib/brute/changelog.rb

@@ -0,0 +1,322 @@
+# frozen_string_literal: true
+
+require "date"
+
+require "gem_kit"
+
+module Brute
+  # A parser and linter for CHANGELOG.md, which follows
+  # [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+  #
+  # The changelog is the one release artefact nothing else can regenerate, so
+  # it is the one most easily forgotten. Making it machine-checkable turns
+  # "did anyone write the changelog?" into a gate: `bin/lint-changelog`
+  # validates the format, and `bin/release-gem` refuses to push a version that
+  # has no section of its own.
+  #
+  #   changelog = Brute::Changelog.load
+  #   changelog.problems              # => [] when the format is clean
+  #   changelog.release_problems("4.1.0")
+  #
+  # The shape it expects:
+  #
+  #   # Changelog
+  #
+  #   ## [Unreleased]
+  #
+  #   ## [4.1.0] - 2026-08-20
+  #
+  #   ### Added
+  #
+  #   - Something that happened.
+  #
+  class Changelog
+    # Deprecated. This moved out to the gem_kit-release gem, where the rest of
+    # the release toolchain now lives — `gem kit changelog` is the CLI over it.
+    # The implementation stays here, working, until the deadline.
+    extend GemKit::Deprecate
+    superseded_by "GemKit::Release::Changelog", "5.0"
+
+    # The six change types Keep a Changelog defines. Anything else under a
+    # version is a typo or an invention, and both are worth catching.
+    SECTIONS = %w[Added Changed Deprecated Removed Fixed Security].freeze
+
+    UNRELEASED       = "Unreleased"
+    HEADING          = /\A##\s+\[([^\]]+)\](?:\s+-\s+(.*))?\s*\z/
+    SUBHEADING       = /\A###\s+(.*?)\s*\z/
+    BULLET           = /\A[-*]\s+\S/
+    DATE             = /\A\d{4}-\d{2}-\d{2}\z/
+
+    # One `## [...]` section of the file.
+    Release = Struct.new(:version, :date, :line, :subsections, keyword_init: true) do
+      def unreleased? = version == UNRELEASED
+      def empty? = subsections.empty? || subsections.values.all?(&:empty?)
+      def to_s = unreleased? ? "[#{version}]" : "[#{version}] - #{date}"
+    end
+
+    # Load the changelog sitting beside the gem (../../CHANGELOG.md).
+    def self.load(path = File.expand_path("../../CHANGELOG.md", __dir__))
+      new(File.exist?(path) ? File.read(path) : nil, path: path)
+    end
+
+    attr_reader :path, :releases
+
+    # @parameter text [String, nil] the file's contents; nil means "no file".
+    def initialize(text, path: "CHANGELOG.md")
+      @path     = path
+      @text     = text
+      @releases = text ? parse(text) : []
+    end
+
+    def missing? = @text.nil?
+
+    def unreleased = releases.find(&:unreleased?)
+
+    def released = releases.reject(&:unreleased?)
+
+    def find(version)
+      target = Gem::Version.new(version.to_s)
+      released.find { |release| Gem::Version.new(release.version) == target rescue false }
+    end
+
+    # Everything wrong with the file's *format*, as a list of human-readable
+    # problems. Empty means it lints clean.
+    def problems
+      return ["#{path} does not exist"] if missing?
+
+      [*header_problems, *heading_problems, *ordering_problems, *content_problems]
+    end
+
+    # Everything standing between this changelog and releasing `version`.
+    # Format problems count: a file nobody can parse is not documentation.
+    def release_problems(version)
+      return problems unless problems.empty?
+
+      release = find(version)
+      return ["#{path} has no section for #{version} — run bin/update-changelog"] if release.nil?
+      return ["#{path} section for #{version} is empty"] if release.empty?
+
+      newest = released.first
+      if newest && newest.version != release.version
+        return ["#{path} lists #{newest.version} above #{version}; the release being cut must come first"]
+      end
+
+      []
+    end
+
+    private
+
+      # Split the file into `## [...]` sections, recording each one's
+      # `### Type` subsections and their top-level bullets.
+      def parse(text)
+        found   = []
+        current = nil
+        heading = nil
+
+        text.each_line.with_index(1) do |line, number|
+          case line
+          when HEADING
+            heading = nil
+            current = Release.new(version: $1, date: $2&.strip, line: number, subsections: {})
+            found << current
+          when SUBHEADING
+            next unless current
+
+            heading = $1
+            (current.subsections[heading] ||= [])
+          when BULLET
+            current.subsections[heading] << line.strip if current && heading
+          end
+        end
+
+        found
+      end
+
+      def header_problems
+        first = @text.each_line.find { |line| !line.strip.empty? }
+        return [] if first&.strip == "# Changelog"
+
+        ["#{path}:1 must start with the title `# Changelog`"]
+      end
+
+      def heading_problems
+        problems = []
+
+        @text.each_line.with_index(1) do |line, number|
+          next unless line.start_with?("## ") && !line.start_with?("###")
+
+          unless line =~ HEADING
+            problems << "#{path}:#{number} malformed version heading: #{line.strip.inspect} " \
+                        "(expected `## [Unreleased]` or `## [1.2.3] - YYYY-MM-DD`)"
+            next
+          end
+
+          version, date = $1, $2&.strip
+          next if version == UNRELEASED
+
+          problems << "#{path}:#{number} #{version} has no date (expected `## [#{version}] - YYYY-MM-DD`)" if date.nil? || date.empty?
+          problems << "#{path}:#{number} #{version} has a malformed date: #{date.inspect}" if date && !date.empty? && date !~ DATE
+          problems << "#{path}:#{number} #{version} is not a valid version number" unless valid_version?(version)
+        end
+
+        problems + subheading_problems
+      end
+
+      def subheading_problems
+        @text.each_line.with_index(1).filter_map do |line, number|
+          next unless line.start_with?("### ")
+          next if line =~ SUBHEADING && SECTIONS.include?($1)
+
+          "#{path}:#{number} unknown section #{line.sub("###", "").strip.inspect} " \
+            "(expected one of: #{SECTIONS.join(", ")})"
+        end
+      end
+
+      def ordering_problems
+        problems = []
+
+        if unreleased && releases.first&.unreleased? == false
+          problems << "#{path}:#{unreleased.line} [Unreleased] must be the first section"
+        end
+
+        seen = {}
+        released.each do |release|
+          if (first = seen[release.version])
+            problems << "#{path}:#{release.line} duplicate section for #{release.version} (also at line #{first})"
+          end
+          seen[release.version] ||= release.line
+        end
+
+        versions = released.select { |release| valid_version?(release.version) }
+        versions.each_cons(2) do |newer, older|
+          next if Gem::Version.new(newer.version) > Gem::Version.new(older.version)
+
+          problems << "#{path}:#{older.line} #{older.version} is listed below #{newer.version}; " \
+                      "releases must run newest to oldest"
+        end
+
+        problems
+      end
+
+      def content_problems
+        released.flat_map do |release|
+          if release.subsections.empty?
+            ["#{path}:#{release.line} #{release} has no #{SECTIONS.join("/")} section"]
+          else
+            release.subsections.filter_map do |heading, bullets|
+              "#{path}:#{release.line} #{release} has an empty `### #{heading}` section" if bullets.empty?
+            end
+          end
+        end
+      end
+
+      def valid_version?(version)
+        Gem::Version.correct?(version)
+      end
+  end
+end
+
+__END__
+
+describe "brute/changelog" do
+  # These specs exercise a deprecated class on purpose; skip_during keeps the
+  # warning out of the suite's output (see DEPRECATIONS.md).
+  changelog = lambda do |body|
+    Gem::Deprecate.skip_during { Brute::Changelog.new("# Changelog\n\n#{body}") }
+  end
+
+  good = <<~MD
+    ## [Unreleased]
+
+    ## [4.1.0] - 2026-08-20
+
+    ### Added
+
+    - A thing.
+
+    ## [4.0.0] - 2026-08-01
+
+    ### Removed
+
+    - An older thing.
+  MD
+
+  it "parses sections, dates and bullets" do
+    log = changelog.call(good)
+
+    log.releases.map(&:version).should == ["Unreleased", "4.1.0", "4.0.0"]
+    log.unreleased.should.be.kind_of?(Brute::Changelog::Release)
+    log.released.first.date.should == "2026-08-20"
+    log.released.first.subsections["Added"].should == ["- A thing."]
+    log.find("4.0.0").subsections["Removed"].size.should == 1
+  end
+
+  it "lints a well-formed file clean and clears it for release" do
+    log = changelog.call(good)
+
+    log.problems.should == []
+    log.release_problems("4.1.0").should == []
+  end
+
+  it "requires the `# Changelog` title" do
+    Gem::Deprecate.skip_during do
+      Brute::Changelog.new("## [1.0.0] - 2026-01-01\n\n### Added\n\n- x\n")
+        .problems.first.should.match(/must start with the title/)
+    end
+  end
+
+  it "reports a missing file" do
+    log = Gem::Deprecate.skip_during { Brute::Changelog.new(nil, path: "nope.md") }
+    log.missing?.should.be.true
+    log.problems.first.should.match(/does not exist/)
+  end
+
+  it "rejects a malformed version heading" do
+    changelog.call("## 1.0.0\n").problems.first.should.match(/malformed version heading/)
+  end
+
+  it "rejects an undated or badly dated release" do
+    changelog.call("## [1.0.0]\n\n### Added\n\n- x\n").problems.first.should.match(/has no date/)
+    changelog.call("## [1.0.0] - 20260101\n\n### Added\n\n- x\n").problems.first.should.match(/malformed date/)
+  end
+
+  it "rejects an unknown section type" do
+    changelog.call("## [1.0.0] - 2026-01-01\n\n### Improved\n\n- x\n")
+      .problems.first.should.match(/unknown section "Improved"/)
+  end
+
+  it "rejects an empty release and an empty subsection" do
+    changelog.call("## [1.0.0] - 2026-01-01\n").problems.first.should.match(/has no Added/)
+    changelog.call("## [1.0.0] - 2026-01-01\n\n### Added\n\n## [0.9.0] - 2026-01-01\n\n### Added\n\n- x\n")
+      .problems.first.should.match(/empty `### Added` section/)
+  end
+
+  it "rejects duplicates and out-of-order releases" do
+    body = "## [1.0.0] - 2026-01-02\n\n### Added\n\n- x\n\n## [1.0.0] - 2026-01-01\n\n### Added\n\n- y\n"
+    changelog.call(body).problems.first.should.match(/duplicate section for 1\.0\.0/)
+
+    body = "## [1.0.0] - 2026-01-01\n\n### Added\n\n- x\n\n## [2.0.0] - 2026-01-02\n\n### Added\n\n- y\n"
+    changelog.call(body).problems.first.should.match(/must run newest to oldest/)
+  end
+
+  it "requires [Unreleased] to come first" do
+    body = "## [1.0.0] - 2026-01-01\n\n### Added\n\n- x\n\n## [Unreleased]\n"
+    changelog.call(body).problems.first.should.match(/\[Unreleased\] must be the first section/)
+  end
+
+  it "blocks a release with no section of its own" do
+    changelog.call(good).release_problems("9.9.9").first.should.match(/no section for 9\.9\.9/)
+  end
+
+  it "blocks a release that is not the newest section" do
+    changelog.call(good).release_problems("4.0.0").first.should.match(/lists 4\.1\.0 above 4\.0\.0/)
+  end
+
+  it "reports format problems ahead of release problems" do
+    changelog.call("## nonsense\n").release_problems("4.1.0").first.should.match(/malformed version heading/)
+  end
+
+  it "loads the repo's own CHANGELOG.md" do
+    Gem::Deprecate.skip_during { Brute::Changelog.load.missing?.should.be.false }
+  end
+end

data/lib/brute/completion/open_router.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Brute
+  # Completion middlewares — the terminal step of an agent turn. Each one is a
+  # ready-made replacement for the hand-written `run` proc: it takes
+  # env[:messages], calls one provider, and appends the reply back onto the log.
+  #
+  #   Brute.agent
+  #     .use(Brute::Middleware::SystemPrompt)
+  #     .run(Brute::Completion::OpenRouter.new(model: "anthropic/claude-sonnet-4"))
+  #
+  # Brute still owns no LLM library: each class here requires only the gem for
+  # its own provider, and only when you use it.
+  module Completion
+    class OpenRouter
+      # config:   keyword arguments for OpenRouter::Client.new
+      #           (access_token:, request_timeout:, uri_base:, extra_headers:).
+      #           Defaults to OpenRouter.configuration's global settings.
+      # options:  keyword arguments for OpenRouter::CompletionOptions.new
+      #           (model:, temperature:, tools:, ...).
+      def initialize(app, config: {}, **options)
+        @app = app
+        @config = config
+        @options = ::OpenRouter::CompletionOptions.new(**options)
+      end
+
+      def call(env)
+        env[:hooks]&.emit(:before_llm, env)
+
+        messages = Brute::MessageTransport::OpenRouter.dump_all(env[:messages])
+
+        ::OpenRouter::Client.new(**@config).then do |client|
+          client.complete(messages, @options).then do |response|
+
+            # Expose the provider's usage for downstream accounting
+            # middleware (goal budgets, autonomous limits, compaction
+            # thresholds, usage attribution) — additive metadata only.
+            if response.respond_to?(:usage) && response.usage
+              (env[:metadata] ||= {})[:last_llm_usage] = response.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
+
+        env[:hooks]&.emit(:after_llm, env)
+        env
+      end
+    end
+  end
+end
+
+__END__
+
+describe "brute/completion/open_router" do
+  require "brute/messages"
+
+  # The repo suite has no open_router gem; stub the two constants the
+  # middleware touches (the transport wraps duck-typed responses fine).
+  begin
+    require "open_router"
+  rescue LoadError
+    module OpenRouter
+      CompletionOptions = Class.new { def initialize(**_opts); end }
+      Client = Class.new
+    end
+  end
+
+  FakeUsageResponse = Struct.new(:usage) do
+    def choices
+      [{ "message" => { "role" => "assistant", "content" => "hello" } }]
+    end
+  end unless defined?(FakeUsageResponse)
+
+  # Run one turn against a stubbed OpenRouter::Client and hand back the env.
+  with_fake_client = lambda do |middleware, response|
+    fake_client = Object.new
+    fake_client.define_singleton_method(:complete) { |_messages, _options| response }
+    original = OpenRouter::Client.method(:new)
+    OpenRouter::Client.define_singleton_method(:new) { |**_config| fake_client }
+    begin
+      env = { messages: Brute.log }
+      env[:messages].user("hi")
+      middleware.call(env)
+      env
+    ensure
+      OpenRouter::Client.define_singleton_method(:new, original)
+    end
+  end
+
+  it "records the provider usage into env metadata and appends the message" do
+    response = FakeUsageResponse.new({ "prompt_tokens" => 10, "completion_tokens" => 5, "total_tokens" => 15 })
+    env = with_fake_client.call(Brute::Completion::OpenRouter.new(->(e) { e }), response)
+
+    env[:messages].last.role.should == :assistant
+    env[:metadata][:last_llm_usage]["total_tokens"].should == 15
+  end
+
+  it "leaves metadata alone when the response has no usage" do
+    env = with_fake_client.call(Brute::Completion::OpenRouter.new(->(e) { e }), FakeUsageResponse.new(nil))
+
+    env.key?(:metadata).should.be.false
+  end
+
+  it "still answers to the deprecated Middleware::OpenRouter::Completion name" do
+    deprecated = Brute::Middleware::OpenRouter::Completion.new(->(e) { e })
+    deprecated.should.be.kind_of?(Brute::Completion::OpenRouter)
+
+    env = with_fake_client.call(deprecated, FakeUsageResponse.new(nil))
+    env[:messages].last.content.should == "hello"
+  end
+end

data/lib/brute/contrib/log_file.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require "file/tail"
+require "fileutils"
+
+module Brute
+  module Contrib
+    # A line-oriented, append-only log file that doubles as a work queue.
+    #
+    # Every entry is exactly one line — newlines in the input are folded to
+    # spaces on the way in — so a line is the unit of both storage and
+    # retrieval. Reads are destructive: `pop` takes the newest line off the
+    # end, `drain` yields every line oldest-first and empties the file.
+    #
+    #   log = Brute::Contrib::LogFile.new("tmp/queue.log")
+    #   log.append("something happened")
+    #   log.pop            # => "something happened"
+    #   log.drain { |line| handle(line) }
+    #
+    # Safe across both threads (a mutex) and processes (an exclusive flock),
+    # so several agents can share one file without losing lines.
+    class LogFile < File
+      include File::Tail
+
+      def initialize(path)
+        FileUtils.mkdir_p(File.dirname(path))
+        super(path, File::RDWR | File::CREAT | File::APPEND)
+        @mutex = Mutex.new
+      end
+
+      # Append one line. Blank (or whitespace-only) input is a no-op and
+      # returns nil; otherwise returns the stripped line that was written.
+      def append(line)
+        strip_whitespace(line).then do |stripped_text|
+          unless stripped_text.empty?
+            locked do
+              puts(stripped_text)
+              flush
+              stripped_text
+            end
+          end
+        end
+      end
+
+      # Remove and return the newest line, or nil when the file is empty.
+      def pop
+        locked do
+          backward(1)
+          offset = tell
+          gets&.chomp.tap { truncate(offset) }
+        end
+      end
+
+      # Yield every line oldest-first, then empty the file. Requires a block —
+      # without one there is nowhere for the lines to go, so it raises rather
+      # than discarding them.
+      def drain
+        locked do
+          if block_given?
+            backward(line_count)
+            each_line { |x| yield x.chomp }
+            truncate(0)
+          else
+            raise "No block given..."
+          end
+        end
+      end
+
+      private
+
+        def line_count
+          rewind
+          each_line.count
+        end
+
+        def strip_whitespace(line)
+          line.to_s.gsub(/\r?\n/, " ").strip
+        end
+
+        def locked
+          @mutex.synchronize do
+            flock(File::LOCK_EX)
+            yield
+          ensure
+            flock(File::LOCK_UN)
+          end
+        end
+    end
+  end
+end
+
+__END__
+
+require "tmpdir"
+
+describe "brute/contrib/log_file" do
+  it "pops the last line, then nothing" do
+    Dir.mktmpdir do |dir|
+      log = Brute::Contrib::LogFile.new(File.join(dir, "log"))
+      log.append("first")
+      log.append("second")
+
+      log.pop.should == "second"
+      log.pop.should == "first"
+      log.pop.should.be.nil
+    end
+  end
+
+  it "keeps one entry on one line" do
+    Dir.mktmpdir do |dir|
+      log = Brute::Contrib::LogFile.new(File.join(dir, "log"))
+      log.append("two\nlines")
+      log.append("   ")
+
+      log.pop.should == "two lines"
+      log.pop.should.be.nil
+    end
+  end
+
+  it "loses no line to concurrent threads" do
+    Dir.mktmpdir do |dir|
+      log = Brute::Contrib::LogFile.new(File.join(dir, "log"))
+      4.times.map { |i| Thread.new { 50.times { |j| log.append("p#{i}-#{j}") } } }.each(&:join)
+
+      popped = []
+      4.times.map { Thread.new { while (line = log.pop) do popped << line end } }.each(&:join)
+
+      popped.uniq.size.should == 200
+      File.size(log.path).should == 0
+    end
+  end
+
+  it "drains every line, oldest first, and empties the file" do
+    Dir.mktmpdir do |dir|
+      log = Brute::Contrib::LogFile.new(File.join(dir, "log"))
+      log.append("first")
+      log.append("second")
+      log.append("third")
+
+      drained = []
+      log.drain { |line| drained << line }
+
+      drained.should == ["first", "second", "third"]
+      File.size(log.path).should == 0
+      log.pop.should.be.nil
+    end
+  end
+
+  it "refuses to drain without a block, leaving the lines alone" do
+    Dir.mktmpdir do |dir|
+      log = Brute::Contrib::LogFile.new(File.join(dir, "log"))
+      log.append("first")
+      log.append("second")
+
+      lambda { log.drain }.should.raise(RuntimeError)
+
+      File.read(log.path).should == "first\nsecond\n"
+      log.pop.should == "second"
+    end
+  end
+
+  it "keeps appending after a drain" do
+    Dir.mktmpdir do |dir|
+      log = Brute::Contrib::LogFile.new(File.join(dir, "log"))
+      log.append("before")
+      log.drain { |line| line }
+      log.append("after")
+
+      log.pop.should == "after"
+      log.pop.should.be.nil
+    end
+  end
+end

data/lib/brute/deprecate.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require "gem_kit"
+
+module Brute
+  # Deprecated. This is [`GemKit::Deprecate`](https://rubygems.org/gems/gem_kit)
+  # now — the same code, extracted so that other gems could use it, and so that
+  # `gem kit deprecations` could read one registry rather than two.
+  #
+  #   extend Brute::Deprecate     ->  extend GemKit::Deprecate
+  #   brute_deprecate             ->  deprecate
+  #   brute_deprecate_constant    ->  superseded_by
+  #
+  # Extending this module still works and still registers: it warns, then
+  # extends GemKit::Deprecate for you and aliases the old method names onto the
+  # new ones. It will stop working in 5.0.
+  module Deprecate
+    REPLACEMENT = "GemKit::Deprecate"
+    REMOVED_IN  = "5.0"
+
+    # The names Brute used before the extraction. `deprecate` collides with
+    # Gem::Deprecate's own, which is why Brute's carried a prefix; GemKit's
+    # namespace does that job instead.
+    ALIASES = { brute_deprecate: :deprecate, brute_deprecate_constant: :superseded_by }.freeze
+
+    def self.extended(base)
+      origin = Gem.location_of_caller.join(":")
+      GemKit::Deprecate.warn(
+        GemKit::Deprecate.message("Brute::Deprecate", REPLACEMENT, REMOVED_IN, origin),
+      )
+
+      base.extend(GemKit::Deprecate)
+      ALIASES.each { |old, new| base.singleton_class.alias_method(old, new) }
+    end
+
+    # The registry moved with the DSL. Delegated rather than mirrored: two
+    # registries meant two answers to "what is still outstanding".
+    class << self
+      def registry            = GemKit::Deprecate.registry
+      def pending(version)    = GemKit::Deprecate.pending(version)
+      def upcoming(version)   = GemKit::Deprecate.upcoming(version)
+      def register(...)       = GemKit::Deprecate.register(...)
+      def warn(message)       = GemKit::Deprecate.warn(message)
+    end
+  end
+end
+
+# The module itself is deprecated, and a module cannot announce that the way a
+# class can — there is no `new` to wrap. Registering it by hand is what puts it
+# in `gem kit deprecations` alongside everything else.
+GemKit::Deprecate.register(
+  name:        "Brute::Deprecate",
+  replacement: Brute::Deprecate::REPLACEMENT,
+  removed_in:  Brute::Deprecate::REMOVED_IN,
+  declared_at: "#{__FILE__}:#{__LINE__ - 5}",
+)
+
+__END__
+
+describe "brute/deprecate" do
+  captured = []
+  # Capture what the shim emits, and keep the shared registry clean.
+  isolated = lambda do |&block|
+    saved    = GemKit::Deprecate.registry.dup
+    original = GemKit::Deprecate.method(:warn)
+    captured.clear
+    GemKit::Deprecate.define_singleton_method(:warn) { |message| captured << message }
+    begin
+      block.call
+    ensure
+      GemKit::Deprecate.define_singleton_method(:warn, original)
+      GemKit::Deprecate.registry.replace(saved)
+    end
+  end
+
+  it "warns when extended, naming GemKit::Deprecate" do
+    isolated.call do
+      Class.new { extend Brute::Deprecate }
+
+      captured.size.should == 1
+      captured.first.should.match(/Brute::Deprecate is deprecated/)
+      captured.first.should.match(/use GemKit::Deprecate instead/)
+      captured.first.should.match(/removed in 5\.0/)
+    end
+  end
+
+  it "still declares a method deprecation under the old name" do
+    isolated.call do
+      klass = Class.new do
+        extend Brute::Deprecate
+        def new_name = :result
+        def old_name = new_name
+        brute_deprecate :old_name, "Thing#new_name", "9.0"
+      end
+
+      klass.new.old_name.should == :result
+      GemKit::Deprecate.registry.last.replacement.should == "Thing#new_name"
+    end
+  end
+
+  it "still declares a constant deprecation under the old name" do
+    isolated.call do
+      modern = Class.new { def initialize(x); @x = x; end; attr_reader :x }
+      legacy = Class.new(modern) do
+        extend Brute::Deprecate
+        def self.name = "Old::Name"
+        brute_deprecate_constant "New::Name", "9.0"
+      end
+
+      legacy.new(42).x.should == 42
+      GemKit::Deprecate.registry.last.name.should == "Old::Name"
+    end
+  end
+
+  it "delegates the registry rather than keeping one of its own" do
+    isolated.call do
+      Brute::Deprecate.registry.should.equal?(GemKit::Deprecate.registry)
+
+      GemKit::Deprecate.register(name: "A", replacement: "A2", removed_in: "5.0")
+      Brute::Deprecate.pending("5.0.0").map(&:name).should.include?("A")
+      Brute::Deprecate.upcoming("4.0.0").map(&:name).should.include?("A")
+    end
+  end
+
+  it "registers itself, so `gem kit deprecations` lists it" do
+    entry = GemKit::Deprecate.registry.find { |e| e.name == "Brute::Deprecate" }
+
+    entry.should.not.be.nil
+    entry.replacement.should == "GemKit::Deprecate"
+    entry.removed_in.should == Gem::Version.new("5.0")
+  end
+end

data/lib/brute/middleware/open_router.rb

@@ -1,46 +1,23 @@
 # frozen_string_literal: true
 
+require "gem_kit"
+
+require_relative "../completion/open_router"
+
 module Brute
   module Middleware
     module OpenRouter
-      class Completion
-        # config:   keyword arguments for OpenRouter::Client.new
-        #           (access_token:, request_timeout:, uri_base:, extra_headers:).
-        #           Defaults to OpenRouter.configuration's global settings.
-        # options:  keyword arguments for OpenRouter::CompletionOptions.new
-        #           (model:, temperature:, tools:, ...).
-        def initialize(app, config: {}, **options)
-          @app = app
-          @config = config
-          @options = ::OpenRouter::CompletionOptions.new(**options)
-        end
-
-        def call(env)
-          env[:hooks]&.emit(:before_llm, env)
-
-          messages = Brute::MessageTransport::OpenRouter.dump_all(env[:messages])
-
-          ::OpenRouter::Client.new(**@config).then do |client|
-            client.complete(messages, @options).then do |response|
-
-              # Expose the provider's usage for downstream accounting
-              # middleware (goal budgets, autonomous limits, compaction
-              # thresholds, usage attribution) — additive metadata only.
-              if response.respond_to?(:usage) && response.usage
-                (env[:metadata] ||= {})[:last_llm_usage] = response.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
-
-          env[:hooks]&.emit(:after_llm, env)
-          env
-        end
+      # Deprecated. Completion middlewares now live under Brute::Completion,
+      # which names them for what they do (call one provider) rather than for
+      # where they happened to sit in the stack:
+      #
+      #   Brute::Middleware::OpenRouter::Completion  ->  Brute::Completion::OpenRouter
+      #
+      # The old name stays a working subclass of the new one until the deadline
+      # below; see DEPRECATIONS.md and `gem kit deprecations`.
+      class Completion < Brute::Completion::OpenRouter
+        extend GemKit::Deprecate
+        superseded_by "Brute::Completion::OpenRouter", "5.0"
       end
     end
   end
@@ -49,59 +26,31 @@ end
 __END__
 
 describe "brute/middleware/open_router" do
-  require "brute/messages"
+  require "brute/completion/open_router"
 
-  # The repo suite has no open_router gem; stub the two constants the
-  # middleware touches (the transport wraps duck-typed responses fine).
-  begin
-    require "open_router"
-  rescue LoadError
-    module OpenRouter
-      CompletionOptions = Class.new { def initialize(**_opts); end }
-      Client = Class.new
-    end
+  it "is the new Completion class under the old name" do
+    Brute::Middleware::OpenRouter::Completion.superclass.should == Brute::Completion::OpenRouter
   end
 
-  FakeUsageResponse = Struct.new(:usage) do
-    def choices
-      [{ "message" => { "role" => "assistant", "content" => "hello" } }]
-    end
-  end
-
-  it "records the provider usage into env metadata and appends the message" do
-    response = FakeUsageResponse.new({ "prompt_tokens" => 10, "completion_tokens" => 5, "total_tokens" => 15 })
-    fake_client = Object.new
-    fake_client.define_singleton_method(:complete) { |_messages, _options| response }
-    original = OpenRouter::Client.method(:new)
-    OpenRouter::Client.define_singleton_method(:new) { |**_config| fake_client }
+  it "warns on use, naming the replacement and the removal version" do
+    captured = []
+    original = GemKit::Deprecate.method(:warn)
+    GemKit::Deprecate.define_singleton_method(:warn) { |message| captured << message }
     begin
-      middleware = Brute::Middleware::OpenRouter::Completion.new(->(env) { env })
-      env = { messages: Brute.log }
-      env[:messages].user("hi")
-      middleware.call(env)
-
-      env[:messages].last.role.should == :assistant
-      env[:metadata][:last_llm_usage]["total_tokens"].should == 15
+      Brute::Middleware::OpenRouter::Completion.new(->(env) { env })
     ensure
-      OpenRouter::Client.define_singleton_method(:new, original)
+      GemKit::Deprecate.define_singleton_method(:warn, original)
     end
-  end
 
-  it "leaves metadata alone when the response has no usage" do
-    response = FakeUsageResponse.new(nil)
-    fake_client = Object.new
-    fake_client.define_singleton_method(:complete) { |_messages, _options| response }
-    original = OpenRouter::Client.method(:new)
-    OpenRouter::Client.define_singleton_method(:new) { |**_config| fake_client }
-    begin
-      middleware = Brute::Middleware::OpenRouter::Completion.new(->(env) { env })
-      env = { messages: Brute.log }
-      env[:messages].user("hi")
-      middleware.call(env)
+    captured.size.should == 1
+    captured.first.should.match(/Brute::Middleware::OpenRouter::Completion is deprecated/)
+    captured.first.should.match(/use Brute::Completion::OpenRouter instead/)
+    captured.first.should.match(/removed in 5\.0/)
+  end
 
-      env.key?(:metadata).should.be.false
-    ensure
-      OpenRouter::Client.define_singleton_method(:new, original)
-    end
+  it "is registered with its removal deadline" do
+    entry = GemKit::Deprecate.registry.find { |e| e.name == "Brute::Middleware::OpenRouter::Completion" }
+    entry.should.not.be.nil
+    entry.removed_in.should == Gem::Version.new("5.0")
   end
 end

data/lib/brute/turn/agent_pipeline.rb

@@ -124,6 +124,22 @@ describe "brute/turn/agent_pipeline" do
     agent.start("hi")[:messages].last.content.should == "from ru"
   end
 
+  it "Brute.load_agent loads an agent from a .ru file and starts it" do
+    require "tmpdir"
+    Dir.mktmpdir do |dir|
+      path = File.join(dir, "agent.ru")
+      File.write(path, 'run ->(env) { env[:messages].assistant("from file") }')
+
+      agent = Brute.load_agent(path)
+      agent.should.be.kind_of?(Brute::Turn::AgentPipeline)
+      agent.start("hi")[:messages].last.content.should == "from file"
+    end
+  end
+
+  it "Brute.load_agent raises for a missing file" do
+    lambda { Brute.load_agent("definitely/not/here.ru") }.should.raise(ArgumentError)
+  end
+
   it ".on chains off the builder and fires turn hooks around the turn" do
     fired = []
     agent = Brute.agent

data/lib/brute/version.rb

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

data/lib/brute.rb

@@ -57,6 +57,22 @@ module Brute
     Brute::Turn::AgentPipeline.new(&block)
   end
 
+  # Load an agent from a brute.ru file — the Brute analogue of `rackup`.
+  # The file is a rackup-style script using the same `use` / `run` / `map`
+  # DSL as `Brute.agent`, and what comes back is the AgentPipeline itself,
+  # so it can be started, further `.use`d, or served through
+  # Brute::Rack::Adapter:
+  #
+  #   Brute.load_agent.start("what changed?")               # ./agent.ru
+  #   Brute.load_agent("examples/agents/brute.ru").start("hi")
+  #
+  def self.load_agent(path = "agent.ru")
+    path = File.expand_path(path)
+    raise ArgumentError, "no such agent file: #{path}" unless File.file?(path)
+
+    Brute::Turn::AgentPipeline.parse_file(path)
+  end
+
   # Adapt any Brute tools (hashes, Brute::Tool, Brute::Turn::ToolPipeline,
   # SubAgent …) into a { name_sym => Brute::Tools::Adapter } hash. Each
   # adapter exposes #to_h — a neutral JSON-Schema-ish definition the inline

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: brute
 version: !ruby/object:Gem::Version
-  version: 4.0.0
+  version: 4.2.0
 platform: ruby
 authors:
 - Brute Contributors
@@ -37,6 +37,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: file-tail
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
@@ -121,6 +135,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '4.34'
+- !ruby/object:Gem::Dependency
+  name: gem_kit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -163,6 +191,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: gem_kit-release
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
 description: Production-grade coding agent with tool execution, middleware pipeline,
   context compaction, session persistence, and multi-provider LLM support.
 executables: []
@@ -170,6 +212,10 @@ extensions: []
 extra_rdoc_files: []
 files:
 - lib/brute.rb
+- lib/brute/changelog.rb
+- lib/brute/completion/open_router.rb
+- lib/brute/contrib/log_file.rb
+- lib/brute/deprecate.rb
 - lib/brute/events/handler.rb
 - lib/brute/events/prefixed_terminal_output.rb
 - lib/brute/events/terminal_output_handler.rb