brute 4.0.0 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 65f8fa383e8c2d5793cc4ec00023ee6d2117e75535a81676617232b94748f154
-  data.tar.gz: 88f3794d39b79c3c7c03c96f54383fa8647850be1cfc77ae8877fb6ea42aa365
+  metadata.gz: 428a37a7f0f2e0930d1b0c901fc75606686c25e07046b54c6dc4964fbbb88433
+  data.tar.gz: 33f0b4a2956004b7e4d26790f981718fea46d2ae7cf1f54deaea250a7951edaf
 SHA512:
-  metadata.gz: 57b849d89d406b624fe26dcbc93aa84af2f9b90b12160fb57608938ec53fd7109c87aa3d2c1357620c78f88b9702f797ff106432840a5e4ccaca343f49e7035a
-  data.tar.gz: d73709348a3f205f034389e86950a5ce171d0fd0bf62a9c9e84ad587d3ac322aad211b94d059a93b9b19e16a0c1b6211baebd7f274b88435c1cf61a9a6373007
+  metadata.gz: 7c382ae2d9229bdd7524cbdb87614f94b8c54e25ae2f76ee68892198bcf8d901d35398b3555f712b07253f17c3dddd1d8d66907c44ff9eaa28dd5adca3441582
+  data.tar.gz: 1c3816fff0d6664a25a9bfcb0c44df62c6833c2ba5066b3cbec0772fd24ea1ab4e078b7e1faca3f577297842fdd92c3aca59368f376993ba88956aaf3c02d500

data/lib/brute/changelog.rb

@@ -0,0 +1,322 @@
+# frozen_string_literal: true
+
+require "date"
+
+require_relative "deprecate"
+
+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 Brute::Deprecate
+    brute_deprecate_constant "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,325 @@
+# frozen_string_literal: true
+
+require "rubygems/deprecate"
+
+# gem_kit-release is a *development* dependency: the release tooling reads the
+# registry below, but the library itself must not depend on release tooling to
+# load. So mirror into its registry when it happens to be there, and carry on
+# when it is not.
+begin
+  require "gem_kit/release/deprecate"
+rescue LoadError
+  # Not installed — this is a normal production install of Brute.
+end
+
+module Brute
+  # Brute's deprecation policy, built on Gem::Deprecate.
+  #
+  # Rubygems' own convention is the one worth copying: a deprecation names its
+  # replacement and the *version it will be removed in*, so "deprecated" is a
+  # dated promise rather than an open-ended apology. Brute adds one thing on
+  # top — a registry. Every declaration records itself, which turns the set of
+  # outstanding deprecations into data the tooling can act on:
+  #
+  #   bin/deprecations             # list everything still outstanding
+  #   bin/increment-version major  # refuses to bump past a removal deadline
+  #
+  # Deprecate a method:
+  #
+  #   class Session
+  #     extend Brute::Deprecate
+  #
+  #     def old_reset; new_reset; end
+  #     brute_deprecate :old_reset, "Session#new_reset", "5.0"
+  #   end
+  #
+  # Deprecate a whole class — a renamed or moved constant. Leave the old name
+  # in place as a subclass of the new one, then declare it:
+  #
+  #   class Completion < Brute::Completion::OpenRouter
+  #     extend Brute::Deprecate
+  #     brute_deprecate_constant "Brute::Completion::OpenRouter", "5.0"
+  #   end
+  #
+  # Both warn on use, naming the caller. Gem::Deprecate.skip_during { ... }
+  # silences them, so a test suite can exercise the old path in quiet.
+  module Deprecate
+    extend Gem::Deprecate
+
+    # One outstanding deprecation. `removed_in` is the version the old name
+    # stops existing in — the deadline both CLI commands read.
+    Entry = Struct.new(:name, :replacement, :removed_in, :declared_at, keyword_init: true) do
+      def to_s
+        "#{name} -> #{replacement == :none ? "(no replacement)" : replacement}"
+      end
+    end
+
+    class << self
+      # Every deprecation declared in the loaded library, in declaration order.
+      def registry
+        @registry ||= []
+      end
+
+      # Record a deprecation. Returns the Entry.
+      def register(name:, replacement:, removed_in:, declared_at: nil)
+        entry = Entry.new(
+          name:        name.to_s,
+          replacement: replacement,
+          removed_in:  Gem::Version.new(removed_in.to_s),
+          declared_at: declared_at || caller_locations(1, 1)&.first&.then { |l| "#{l.path}:#{l.lineno}" },
+        )
+        registry << entry
+
+        # Same shape (name, replacement, removed_in, declared_at), so
+        # `gem kit deprecations` can read Brute's entries directly.
+        if defined?(::GemKit::Release::Deprecate)
+          ::GemKit::Release::Deprecate.registry << entry
+        end
+
+        entry
+      end
+
+      # The deprecations that come due at `version` — everything whose removal
+      # deadline has arrived or passed. This is the gate: releasing `version`
+      # with any of these still present breaks the promise the warning made.
+      def pending(version)
+        target = Gem::Version.new(version.to_s)
+        registry.select { |entry| entry.removed_in <= target }
+      end
+
+      # Deprecations still in their grace period at `version`.
+      def upcoming(version)
+        target = Gem::Version.new(version.to_s)
+        registry.reject { |entry| entry.removed_in <= target }
+      end
+
+      # The default deadline: the next major version after the current one.
+      def next_major_version
+        Gem::Version.new(Brute::VERSION.split(".").first).bump.to_s
+      end
+
+      # Single funnel for every warning, so Gem::Deprecate.skip_during works
+      # across all of them and specs have one place to listen.
+      def warn(message)
+        Kernel.warn(message) unless Gem::Deprecate.skip
+      end
+
+      # Build the Gem::Deprecate-shaped message body. `origin` must be
+      # computed at the call site — one frame deeper and it names this file
+      # rather than the code that needs changing.
+      def message(target, replacement, removed_in, origin)
+        [
+          "NOTE: #{target} is deprecated",
+          replacement == :none ? " with no replacement" : "; use #{replacement} instead",
+          ". It will be removed in Brute #{removed_in}",
+          "\n#{target} called from #{origin}.",
+        ].join
+      end
+    end
+
+    # Deprecate one method. Mirrors Gem::Deprecate#rubygems_deprecate, but the
+    # deadline is explicit rather than "the next major" — a deprecation added
+    # late in a cycle usually wants the major after next.
+    def brute_deprecate(name, replacement = :none, removed_in = Brute::Deprecate.next_major_version)
+      label = singleton_class? ? "#{attached_object}.#{name}" : "#{self}##{name}"
+      Brute::Deprecate.register(
+        name:        label,
+        replacement: replacement,
+        removed_in:  removed_in,
+        declared_at: caller_locations(1, 1)&.first&.then { |l| "#{l.path}:#{l.lineno}" },
+      )
+
+      class_eval do
+        old = "_deprecated_#{name}"
+        alias_method old, name
+        define_method name do |*args, &block|
+          target = is_a?(Module) ? "#{self}.#{name}" : "#{self.class}##{name}"
+          origin = Gem.location_of_caller.join(":")
+          Brute::Deprecate.warn(Brute::Deprecate.message(target, replacement, removed_in, origin))
+          send(old, *args, &block)
+        end
+        ruby2_keywords name if respond_to?(:ruby2_keywords, true)
+      end
+    end
+
+    # Deprecate a whole constant — the renamed-or-moved case. Call it in the
+    # body of the old name (kept as a subclass of the new one); it registers
+    # the rename and warns whenever the old name is instantiated.
+    def brute_deprecate_constant(replacement, removed_in = Brute::Deprecate.next_major_version)
+      Brute::Deprecate.register(
+        name:        name || to_s,
+        replacement: replacement,
+        removed_in:  removed_in,
+        declared_at: caller_locations(1, 1)&.first&.then { |l| "#{l.path}:#{l.lineno}" },
+      )
+
+      return unless respond_to?(:new)
+
+      define_singleton_method(:new) do |*args, **options, &block|
+        origin = Gem.location_of_caller.join(":")
+        Brute::Deprecate.warn(Brute::Deprecate.message(name || to_s, replacement, removed_in, origin))
+        super(*args, **options, &block)
+      end
+    end
+  end
+end
+
+__END__
+
+describe "brute/deprecate" do
+  # Capture what Brute::Deprecate.warn emits, and keep the shared registry
+  # clean — these specs declare throwaway deprecations.
+  captured = []
+  around_each = lambda do |&block|
+    saved = Brute::Deprecate.registry.dup
+    original = Brute::Deprecate.method(:warn)
+    captured.clear
+    Brute::Deprecate.define_singleton_method(:warn) { |message| captured << message }
+    begin
+      block.call
+    ensure
+      Brute::Deprecate.define_singleton_method(:warn, original)
+      Brute::Deprecate.registry.replace(saved)
+    end
+  end
+
+  it "warns on a deprecated method, naming the replacement, version and caller" do
+    around_each.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   # still works
+      captured.size.should == 1
+      captured.first.should.match(/is deprecated/)
+      captured.first.should.match(/use Thing#new_name instead/)
+      captured.first.should.match(/removed in Brute 9\.0/)
+      captured.first.should.match(/called from /)
+    end
+  end
+
+  it "warns on a deprecated constant but keeps it working" do
+    around_each.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          # still works
+      captured.size.should == 1
+      captured.first.should.match(/Old::Name is deprecated; use New::Name instead/)
+    end
+  end
+
+  it "names the caller, not the deprecation machinery" do
+    around_each.call do
+      klass = Class.new do
+        extend Brute::Deprecate
+        def old_name = :result
+        brute_deprecate :old_name, "Thing#new_name", "9.0"
+      end
+
+      # These specs live in this file's __END__, so "the caller" is a line in
+      # deprecate.rb either way — pin the exact line to tell them apart.
+      klass.new.old_name; call_line = __LINE__
+      captured.first.should.match(/called from .*deprecate\.rb:#{call_line}\./)
+    end
+  end
+
+  it "labels a class-method deprecation by the class, not its singleton" do
+    around_each.call do
+      Class.new do
+        def self.to_s = "Demo"
+        def self.old_thing = :ok
+        class << self
+          extend Brute::Deprecate
+          brute_deprecate :old_thing, "Other.new_thing", "9.0"
+        end
+      end
+
+      Brute::Deprecate.registry.last.name.should == "Demo.old_thing"
+    end
+  end
+
+  it "registers each declaration with its deadline and source" do
+    around_each.call do
+      Class.new do
+        extend Brute::Deprecate
+        def gone = nil
+        brute_deprecate :gone, "Other#kept", "9.0"
+      end
+
+      entry = Brute::Deprecate.registry.last
+      entry.replacement.should == "Other#kept"
+      entry.removed_in.should == Gem::Version.new("9.0")
+      entry.declared_at.should.match(/deprecate\.rb:\d+/)
+    end
+  end
+
+  it "mirrors registrations into gem_kit-release's registry when it is present" do
+    # Conditional by design: gem_kit-release is a development dependency, so
+    # in a production install of Brute there is nothing to mirror into. (Also
+    # true inside a pre-commit hook, whose flake snapshot is HEAD's.)
+    next unless defined?(::GemKit::Release::Deprecate)
+
+    around_each.call do
+      saved = GemKit::Release::Deprecate.registry.dup
+      begin
+        Brute::Deprecate.register(name: "Mirrored", replacement: "New", removed_in: "9.0")
+
+        GemKit::Release::Deprecate.registry.last.name.should == "Mirrored"
+        GemKit::Release::Deprecate.registry.last.removed_in.should == Gem::Version.new("9.0")
+      ensure
+        GemKit::Release::Deprecate.registry.replace(saved)
+      end
+    end
+  end
+
+  it "splits the registry into pending (due) and upcoming at a version" do
+    around_each.call do
+      Brute::Deprecate.registry.clear
+      Brute::Deprecate.register(name: "A", replacement: "A2", removed_in: "5.0")
+      Brute::Deprecate.register(name: "B", replacement: "B2", removed_in: "6.0")
+
+      Brute::Deprecate.pending("5.0.0").map(&:name).should == ["A"]
+      Brute::Deprecate.upcoming("5.0.0").map(&:name).should == ["B"]
+      Brute::Deprecate.pending("4.9.0").should.be.empty
+      Brute::Deprecate.pending("6.1.0").map(&:name).should == ["A", "B"]
+    end
+  end
+
+  it "defaults the deadline to the next major version" do
+    around_each.call do
+      Brute::Deprecate.next_major_version.should == Gem::Version.new(Brute::VERSION.split(".").first).bump.to_s
+    end
+  end
+
+  it "stays quiet inside Gem::Deprecate.skip_during" do
+    saved = Brute::Deprecate.registry.dup
+    begin
+      klass = Class.new do
+        extend Brute::Deprecate
+        def quiet = :ok
+        brute_deprecate :quiet, "Other#loud", "9.0"
+      end
+
+      warned = []
+      original = Kernel.method(:warn)
+      Kernel.define_singleton_method(:warn) { |*args| warned << args.join }
+      begin
+        Gem::Deprecate.skip_during { klass.new.quiet.should == :ok }
+      ensure
+        Kernel.define_singleton_method(:warn, original)
+      end
+
+      warned.should.be.empty
+    ensure
+      Brute::Deprecate.registry.replace(saved)
+    end
+  end
+end

data/lib/brute/middleware/open_router.rb

@@ -1,46 +1,22 @@
 # frozen_string_literal: true
 
+require_relative "../deprecate"
+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 Brute::Deprecate and `bin/deprecations`.
+      class Completion < Brute::Completion::OpenRouter
+        extend Brute::Deprecate
+        brute_deprecate_constant "Brute::Completion::OpenRouter", "5.0"
       end
     end
   end
@@ -49,59 +25,31 @@ end
 __END__
 
 describe "brute/middleware/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
+  require "brute/completion/open_router"
 
-  FakeUsageResponse = Struct.new(:usage) do
-    def choices
-      [{ "message" => { "role" => "assistant", "content" => "hello" } }]
-    end
+  it "is the new Completion class under the old name" do
+    Brute::Middleware::OpenRouter::Completion.superclass.should == Brute::Completion::OpenRouter
   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 = Brute::Deprecate.method(:warn)
+    Brute::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)
+      Brute::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 Brute 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 = Brute::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.1.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.1.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
@@ -163,6 +177,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.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
 description: Production-grade coding agent with tool execution, middleware pipeline,
   context compaction, session persistence, and multi-provider LLM support.
 executables: []
@@ -170,6 +198,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