brute 3.2.2 → 4.1.0

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/hooks.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+
+module Brute
+  # Pub/sub registry for agent lifecycle hooks, subscribed on the builder:
+  #
+  #   Brute.agent
+  #     .use(Brute::Middleware::MaxIterations)
+  #     .run(->(env) { env[:messages].assistant("done") })
+  #     .on(:before_llm) { |env| ... }
+  #     .on(:approve_tool) { |call| call[:name] != "exec" }
+  #
+  # 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)
+  #   :before_llm, :after_llm → the turn env, around every LLM call
+  #   :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
+  #
+  # 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 before_tool approve_tool after_tool].freeze
+
+    def initialize
+      @subscribers = Hash.new { |hash, key| hash[key] = [] }
+    end
+
+    def on(event, &block)
+      @subscribers[event.to_sym] << block
+      self
+    end
+
+    # 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) }
+    end
+
+    def any?(event) = @subscribers[event.to_sym].any?
+  end
+end
+
+__END__
+
+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.emit(:before_llm, 1)
+    seen.should == ["a1", "b1"]
+  end
+
+  it "returns raw results, false included (deny contract)" do
+    hooks = Brute::Hooks.new
+    hooks.on(:approve_tool) { |_call| false }
+    hooks.emit(:approve_tool, {}).should == [false]
+  end
+
+  it "answers any? and stays chainable" do
+    hooks = Brute::Hooks.new
+    hooks.any?(:turn_start).should.be.false
+    hooks.on(:turn_start) { nil }.should.equal?(hooks)
+    hooks.any?(:turn_start).should.be.true
+  end
+end

data/lib/brute/middleware/025_skills.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+
+module Brute
+  module Middleware
+    # Loads skill objects into the agent context.
+    #
+    # Skills are handed in as objects — discovery is the caller's job:
+    #
+    #   skills = Brute::Skill.all(cwd: Dir.pwd)
+    #   agent
+    #     .use(Brute::Middleware::Skills, skills: skills)
+    #     .use(Brute::Middleware::SystemPrompt)
+    #
+    # Per turn:
+    #   1. env[:skills] = the objects, for downstream middleware, tools, and
+    #      the terminal app (prime-agent's resourceLoader.getSkills() analogue)
+    #   2. env[:metadata][:skills] = the same objects, so
+    #      Middleware::SystemPrompt merges them into the prompt ctx and
+    #      Brute::Prompts::Skills renders the <available_skills> section
+    #
+    # Place it before Middleware::SystemPrompt in the stack. It never touches
+    # env[:messages] itself.
+    class Skills
+      def initialize(app, skills: [])
+        @app = app
+        @skills = skills
+      end
+
+      def call(env)
+        env[:skills] = @skills
+        env[:metadata] ||= {}
+        env[:metadata][:skills] ||= @skills
+
+        @app.call(env)
+      end
+    end
+  end
+end
+
+__END__
+
+describe "brute/middleware/025_skills" do
+  def skill(name)
+    Brute::Skill.new(name: name, description: "x", file_path: "/x/#{name}/SKILL.md")
+  end
+
+  def build_middleware(skills: [], &inner)
+    Brute::Middleware::Skills.new(inner || ->(env) { env }, skills: skills)
+  end
+
+  it "stashes skill objects in env[:skills]" do
+    skills = [skill("debugging")]
+    env = { messages: Brute.log, metadata: {} }
+
+    build_middleware(skills: skills).call(env)
+
+    env[:skills].should == skills
+  end
+
+  it "mirrors skills into env[:metadata] for the prompt layer" do
+    skills = [skill("debugging")]
+    env = { messages: Brute.log }
+
+    build_middleware(skills: skills).call(env)
+
+    env[:metadata][:skills].should == skills
+  end
+
+  it "does not clobber an explicit metadata[:skills]" do
+    explicit = [skill("explicit")]
+    env = { messages: Brute.log, metadata: { skills: explicit } }
+
+    build_middleware(skills: [skill("other")]).call(env)
+
+    env[:metadata][:skills].should == explicit
+    env[:skills].map(&:name).should == ["other"]
+  end
+
+  it "defaults to an empty list and passes control down the chain" do
+    called = false
+    env = { messages: Brute.log }
+
+    build_middleware { |e| called = true }.call(env)
+
+    env[:skills].should == []
+    called.should.be.true
+  end
+end

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

@@ -48,23 +48,56 @@ module Brute
                 name = tool_call.name.to_sym
                 args = tool_call.arguments
 
-                available_tools[name].call(args).then do |result|
-
-                  # Coerce to String so Hash results (e.g. Shell's
-                  # {stdout:, stderr:, exit_code:}) serialize predictably.
-                  if result.is_a?(String)
-                    content = result
-                  else
-                    content = result.to_s
+                # Lifecycle hooks (Brute::Hooks): before_tool may rewrite
+                # :arguments or short-circuit with a :result; approve_tool
+                # denies on a false (or String) return; after_tool may
+                # rewrite :result.
+                call_env = {
+                  name:      name.to_s,
+                  arguments: args,
+                  result:    nil,
+                  events:    env[:events],
+                  metadata:  {},
+                  turn_env:  env,
+                }
+                if (hooks = env[:hooks])
+                  responses = hooks.emit(:before_tool, call_env).compact
+                  call_env[:result] = responses.last if call_env[:result].nil? && !responses.empty?
+
+                  if call_env[:result].nil?
+                    denial = hooks.emit(:approve_tool, call_env).find { |r| r == false || r.is_a?(String) }
+                    unless denial.nil?
+                      call_env[:result] = denial.is_a?(String) ? denial : %(Tool call to "#{name}" was denied.)
+                    end
                   end
+                end
 
-                  # Universal truncation safety net — skip if already truncated
-                  unless Brute::Truncation.already_truncated?(content)
-                    content = Brute::Truncation.truncate(content)
-                  end
+                result = if call_env[:result].nil?
+                           available_tools[name].call(call_env[:arguments])
+                         else
+                           call_env[:result]
+                         end
+
+                if (hooks = env[:hooks])
+                  call_env[:result] = result
+                  hooks.emit(:after_tool, call_env)
+                  result = call_env[:result]
+                end
+
+                # Coerce to String so Hash results (e.g. Shell's
+                # {stdout:, stderr:, exit_code:}) serialize predictably.
+                if result.is_a?(String)
+                  content = result
+                else
+                  content = result.to_s
+                end
 
-                  results << [tool_call, content]
+                # Universal truncation safety net — skip if already truncated
+                unless Brute::Truncation.already_truncated?(content)
+                  content = Brute::Truncation.truncate(content)
                 end
+
+                results << [tool_call, content]
               rescue => e
                 # Capture the error as a tool result so the LLM can see it
                 # and reason about the failure, rather than crashing the
@@ -141,6 +174,70 @@ describe "brute/middleware/070_tool_pipeline" do
     seen.should == [tool]
   end
 
+  # --- lifecycle hooks (Brute::Hooks) ---
+
+  def hook_env(hooks)
+    { messages: Brute.log, events: [], hooks: hooks }
+  end
+
+  it "before_tool may rewrite arguments and short-circuit with a result" do
+    tool = { name: "echo", description: "", execute: ->(text:) { "ran:#{text}" } }
+    inner = ->(env) do
+      env[:messages] << Brute::Message.new(role: :assistant, content: "",
+        tool_calls: [{ id: "tc1", name: "echo", arguments: { "text" => "orig" } }])
+    end
+    hooks = Brute::Hooks.new
+    hooks.on(:before_tool) { |call| call[:arguments] = { text: "rewritten" }; nil }
+    mw = Brute::Middleware::ToolPipeline.new(inner, tools: [tool])
+    env = hook_env(hooks)
+    env[:messages].user("hi")
+    mw.call(env)
+    env[:messages].last.content.should == "ran:rewritten"
+
+    hooks2 = Brute::Hooks.new
+    hooks2.on(:before_tool) { |_call| "canned" }
+    mw2 = Brute::Middleware::ToolPipeline.new(inner, tools: [tool])
+    env2 = hook_env(hooks2)
+    env2[:messages].user("hi")
+    mw2.call(env2)
+    env2[:messages].last.content.should == "canned" # never executed
+  end
+
+  it "approve_tool denies on false (generic message) or String (custom)" do
+    tool = { name: "exec", description: "", execute: ->(**) { "ran" } }
+    inner = ->(env) do
+      env[:messages] << Brute::Message.new(role: :assistant, content: "",
+        tool_calls: [{ id: "tc1", name: "exec", arguments: {} }])
+    end
+    hooks = Brute::Hooks.new
+    hooks.on(:approve_tool) { |_call| false }
+    env = hook_env(hooks)
+    env[:messages].user("hi")
+    Brute::Middleware::ToolPipeline.new(inner, tools: [tool]).call(env)
+    env[:messages].last.content.should == %(Tool call to "exec" was denied.)
+
+    hooks2 = Brute::Hooks.new
+    hooks2.on(:approve_tool) { |_call| "denied by policy" }
+    env2 = hook_env(hooks2)
+    env2[:messages].user("hi")
+    Brute::Middleware::ToolPipeline.new(inner, tools: [tool]).call(env2)
+    env2[:messages].last.content.should == "denied by policy"
+  end
+
+  it "after_tool may rewrite the result" do
+    tool = { name: "echo", description: "", execute: ->(**) { "raw" } }
+    inner = ->(env) do
+      env[:messages] << Brute::Message.new(role: :assistant, content: "",
+        tool_calls: [{ id: "tc1", name: "echo", arguments: {} }])
+    end
+    hooks = Brute::Hooks.new
+    hooks.on(:after_tool) { |call| call[:result] = "rewrote(#{call[:result]})" }
+    env = hook_env(hooks)
+    env[:messages].user("hi")
+    Brute::Middleware::ToolPipeline.new(inner, tools: [tool]).call(env)
+    env[:messages].last.content.should == "rewrote(raw)"
+  end
+
   # --- Universal output truncation ---
 
   it "truncates large tool results via Truncation" do