brute 2.0.6 → 3.0.1

data/lib/brute/tool.rb

@@ -2,106 +2,123 @@
 
 require "bundler/setup"
 require "brute"
-require 'brute/pipeline'
 
 module Brute
-  # A Tool is a Pipeline configured for tool execution. The terminal app
-  # does the work; middleware wraps it with concerns like file mutation
-  # queueing, snapshotting, validation, logging.
+  # Base class for Brute's built-in tools — a tiny, framework-agnostic tool
+  # DSL. It intentionally mirrors the common tool-library shape (description +
+  # params) so tools read the same as they would in any LLM library, without
+  # depending on one:
   #
-  # Coexists with Brute::Tools::* (which inherit from RubyLLM::Tool).
-  # Use Brute::Tool when you want middleware. Use RubyLLM::Tool subclasses
-  # for simple cases.
+  #   class Shell < Brute::Tool
+  #     description "Execute a shell command"
+  #     param :command, type: 'string', desc: "The command", required: true
   #
-  # Usage:
+  #     def name; "shell"; end
   #
-  #   read = Brute::Tool.new(
-  #     name:        "read",
-  #     description: "Read a file's contents",
-  #     params:      { file_path: { type: "string", required: true } },
-  #   ) do
-  #     use Brute::Middleware::Tool::ValidateParams
-  #     run ->(env) {
-  #       env[:result] = File.read(File.expand_path(env[:arguments][:file_path]))
-  #     }
+  #     def execute(command:)
+  #       ...
+  #     end
   #   end
   #
-  #   read.call(file_path: "lib/brute.rb")
+  # For tools whose arguments don't fit the flat param list, pass a raw JSON
+  # schema instead:
   #
-  class Tool < Pipeline
-    attr_reader :name, :description, :params
-
-    def initialize(name:, description:, params: {}, &block)
-      @name        = name.to_s
-      @description = description
-      @params      = params
-      super(&block)
+  #   params({ type: 'object', properties: { ... }, required: [...] })
+  #
+  # Instances expose the neutral interface Brute::Tools::Adapter understands:
+  # #name, #description, #params, #params_schema, #call.
+  class Tool
+    class << self
+      def description(text = nil)
+        return @description unless text
+
+        @description = text
+      end
+
+      # Declare one parameter: param :key, type:, desc:, required:
+      def param(name, type: "string", desc: nil, required: true, **opts)
+        param_definitions[name.to_sym] = { type: type, desc: desc, required: required, **opts }.compact
+      end
+
+      def param_definitions
+        @param_definitions ||= {}
+      end
+
+      # Raw JSON-schema override for complex argument shapes.
+      def params(schema = nil)
+        return @params_schema unless schema
+
+        @params_schema = schema.deep_symbolize_keys
+      end
     end
 
-    # Execute the tool. Arguments come in as kwargs; result is whatever
-    # the terminal app puts into env[:result].
-    def call(events: NullSink.new, **arguments)
-      env = {
-        name:      @name,
-        arguments: arguments,
-        result:    nil,
-        events:    events,
-        metadata:  {},
-      }
-      super(env)
-      env[:result]
+    # Tool name; subclasses usually override with an explicit short name.
+    def name
+      self.class.name.demodulize.underscore
     end
 
-    # Adapter so the LLM can call this tool through ruby_llm.
-    # ToolCall middleware checks for to_ruby_llm and uses it if present.
-    def to_ruby_llm
-      tool = self
-      Class.new(RubyLLM::Tool) do
-        description tool.description
-        tool.params.each { |k, opts| param k, **opts }
-        define_method(:name) { tool.name }
-        define_method(:execute) { |**args| tool.call(**args) }
-      end.new
+    def description
+      self.class.description.to_s
     end
-  end
-end
 
-test do
-  it "exposes name, description, params" do
-    t = Brute::Tool.new(name: "echo", description: "echo input") do
-      run ->(env) { env[:result] = env[:arguments][:msg] }
+    # { key => { type:, desc:, required: } }
+    def params
+      self.class.param_definitions
     end
 
-    t.name.should == "echo"
-    t.description.should == "echo input"
-    t.call(msg: "hi").should == "hi"
+    # The raw JSON schema, when declared via params({...}).
+    def params_schema
+      self.class.params
+    end
+
+    # Execute with a string- or symbol-keyed argument hash, as delivered
+    # by LLM providers.
+    def call(arguments = {})
+      execute(**arguments.to_h.transform_keys(&:to_sym))
+    end
+
+    def execute(**)
+      raise NotImplementedError, "#{self.class} must implement #execute"
+    end
   end
+end
+
+__END__
 
-  it "passes arguments through env to the terminal app" do
-    captured = nil
-    t = Brute::Tool.new(name: "x", description: "x") do
-      run ->(env) { captured = env[:arguments]; env[:result] = nil }
+describe "brute/tool" do
+  it "exposes description and params from the DSL" do
+    klass = Class.new(Brute::Tool) do
+      description "test tool"
+      param :input, type: "string", desc: "the input"
+      def name; "t"; end
+      def execute(input:); "got #{input}"; end
     end
 
-    t.call(a: 1, b: 2)
-    captured.should == { a: 1, b: 2 }
+    tool = klass.new
+    tool.description.should == "test tool"
+    tool.params[:input][:type].should == "string"
+    tool.params[:input][:required].should.be.true
   end
 
-  it "runs middleware around the terminal app" do
-    log = []
-    wrap = Class.new do
-      def initialize(app, tag:); @app = app; @tag = tag; end
-      def call(env); (env[:metadata][:log] ||= []) << "in-#{@tag}"; @app.call(env); env[:metadata][:log] << "out-#{@tag}"; end
+  it "calls execute with symbolized keys" do
+    klass = Class.new(Brute::Tool) do
+      description "echo"
+      param :msg, type: "string"
+      def name; "echo"; end
+      def execute(msg:); msg; end
     end
 
-    t = Brute::Tool.new(name: "x", description: "x") do
-      use wrap, tag: "a"
-      run ->(env) { env[:metadata][:log] << "core"; env[:result] = :ok }
+    klass.new.call("msg" => "hi").should == "hi"
+  end
+
+  it "accepts a raw JSON schema via params({...})" do
+    klass = Class.new(Brute::Tool) do
+      description "schema tool"
+      params({ type: "object", properties: { a: { type: "string" } }, required: %w[a] })
+      def name; "s"; end
+      def execute(a:); a; end
     end
 
-    # Pre-seed the log on the env that gets built — tool builds its own env,
-    # so we capture via the middleware metadata channel
-    result = t.call(input: 1)
-    result.should == :ok
+    klass.new.params_schema[:properties][:a][:type].should == "string"
   end
 end

data/lib/brute/tools/adapter.rb

@@ -0,0 +1,258 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+
+module Brute
+  module Tools
+    # Normalizes any tool shape into one neutral interface so the rest of
+    # Brute never has to care which tools library (if any) a tool was
+    # written with.
+    #
+    # This solves three problems:
+    #
+    # 1. Using any tools library — anything that quacks like a tool
+    #    (#name plus #call or #execute) is wrapped into the same interface.
+    # 2. Avoiding tool libraries entirely — Brute::Tool, Brute::Turn::ToolPipeline
+    #    and Tools::SubAgent work without inheriting from a library class.
+    # 3. Quickly adding tools — a plain Hash with a proc is enough:
+    #
+    #      Brute::Tools::Adapter.wrap(
+    #        name:        "echo",
+    #        description: "Echo the input back",
+    #        params:      { msg: { type: "string", required: true } },
+    #        execute:     ->(msg:) { msg },
+    #      )
+    #
+    # The neutral interface:
+    #
+    #   adapter.name        # String
+    #   adapter.description # String
+    #   adapter.params      # { key => { type:, desc:, required: } }
+    #   adapter.call(args)  # execute with a (string- or symbol-keyed) Hash
+    #
+    # The inline `run` proc converts adapters (via #to_h) into whatever its
+    # LLM library expects; ToolPipeline executes them via #call.
+    #
+    class Adapter
+      attr_reader :name, :description, :params
+
+      # Wrap a single tool of any supported shape. Idempotent.
+      def self.wrap(tool)
+        return tool if tool.is_a?(Adapter)
+
+        tool = tool.new if tool.is_a?(Class)
+
+        case tool
+        when Hash                then from_hash(tool)
+        when ::Brute::Tool       then from_brute_tool(tool)
+        when Brute::Tools::SubAgent then new(
+          name:        tool.name,
+          description: tool.description,
+          params:      tool.params,
+          handler:     ->(**args) { tool.execute(args) },
+          original:    tool,
+        )
+        when Brute::Turn::ToolPipeline then new(
+          name:        tool.name,
+          description: tool.description,
+          params:      tool.params,
+          handler:     ->(**args) { tool.call(**args) },
+          original:    tool,
+        )
+        else
+          from_duck_type(tool)
+        end
+      end
+
+      # Wrap a list of tools into a { name_sym => adapter } lookup hash —
+      # the shape ToolPipeline works with.
+      def self.wrap_all(tools)
+        Array(tools).each_with_object({}) do |tool, hash|
+          adapter = wrap(tool)
+          hash[adapter.name.to_sym] = adapter
+        end
+      end
+
+      # Quick inline tool: { name:, description:, params:, execute: }
+      def self.from_hash(definition)
+        definition = definition.transform_keys(&:to_sym)
+        handler = definition.fetch(:execute) { definition[:handler] }
+        raise ArgumentError, "inline tool needs an :execute proc" unless handler.respond_to?(:call)
+
+        new(
+          name:        definition.fetch(:name).to_s,
+          description: definition.fetch(:description, ""),
+          params:      definition.fetch(:params, {}),
+          handler:     ->(**args) { handler.call(**args) },
+          original:    definition,
+        )
+      end
+
+      # A Brute::Tool instance. Tools declared with the params({...}) schema
+      # DSL keep their full JSON schema.
+      def self.from_brute_tool(tool)
+        new(
+          name:        tool.name.to_s,
+          description: tool.description,
+          params:      tool.params,
+          schema:      tool.params_schema,
+          handler:     ->(**args) { tool.call(args) },
+          original:    tool,
+        )
+      end
+
+      # Anything tool-shaped: needs #name and #call or #execute.
+      def self.from_duck_type(tool)
+        unless tool.respond_to?(:name) && (tool.respond_to?(:call) || tool.respond_to?(:execute))
+          raise ArgumentError, "don't know how to adapt #{tool.inspect} into a tool"
+        end
+
+        entry = tool.respond_to?(:execute) ? tool.method(:execute) : tool.method(:call)
+        new(
+          name:        tool.name.to_s,
+          description: tool.respond_to?(:description) ? tool.description : "",
+          params:      tool.respond_to?(:params) ? tool.params : {},
+          handler:     ->(**args) { entry.call(**args) },
+          original:    tool,
+        )
+      end
+
+      def initialize(name:, description:, params:, handler:, schema: nil, original: nil)
+        @name        = name
+        @description = description
+        @params      = params || {}
+        @schema      = schema
+        @handler     = handler
+        @original    = original
+      end
+
+      # The tool object this adapter wraps (Brute::Tool, Brute::Turn::ToolPipeline,
+      # SubAgent, Hash definition, ...).
+      attr_reader :original
+
+      # Execute the tool. Accepts string- or symbol-keyed argument hashes,
+      # as delivered by LLM providers.
+      def call(arguments = {})
+        args = arguments.to_h.transform_keys(&:to_sym)
+        @handler.call(**args)
+      end
+
+      # Library-neutral tool definition (JSON-Schema-ish). The inline `run`
+      # proc reshapes this into whatever its LLM library expects.
+      def to_h
+        return { name: @name, description: @description, parameters: @schema.deep_symbolize_keys } if @schema
+
+        properties = @params.transform_values do |opts|
+          {
+            type:        opts[:type] || "string",
+            description: opts[:desc] || opts[:description],
+            items:       opts[:items],
+            enum:        opts[:enum],
+          }.compact
+        end
+        required = @params.select { |_k, opts| opts[:required] }.keys
+
+        {
+          name:        @name,
+          description: @description,
+          parameters: {
+            type:       "object",
+            properties: properties,
+            required:   required.map(&:to_s),
+          },
+        }
+      end
+    end
+  end
+end
+
+__END__
+
+describe "brute/tools/adapter" do
+  it "wraps a Brute::Tool class" do
+    klass = Class.new(::Brute::Tool) do
+      description "test tool"
+      param :input, type: "string", desc: "the input"
+      def name; "brute_tool"; end
+      def execute(input:); "got #{input}"; end
+    end
+
+    adapter = Brute::Tools::Adapter.wrap(klass)
+    adapter.name.should == "brute_tool"
+    adapter.description.should == "test tool"
+    adapter.params[:input][:type].should == "string"
+    adapter.call("input" => "x").should == "got x"
+  end
+
+  it "wraps a Brute::Turn::ToolPipeline" do
+    t = Brute::Turn::ToolPipeline.new(name: "echo", description: "echo input") do
+      run ->(env) { env[:result] = env[:arguments][:msg] }
+    end
+
+    adapter = Brute::Tools::Adapter.wrap(t)
+    adapter.name.should == "echo"
+    adapter.call(msg: "hi").should == "hi"
+  end
+
+  it "wraps a SubAgent" do
+    sa = Brute::Tools::SubAgent.new(name: "research", description: "test") do
+      run ->(env) { env[:messages].assistant("result text") }
+    end
+
+    adapter = Brute::Tools::Adapter.wrap(sa)
+    adapter.name.should == "research"
+    adapter.call(task: "go").should == "result text"
+  end
+
+  it "wraps an inline hash definition" do
+    adapter = Brute::Tools::Adapter.wrap(
+      name:        "adder",
+      description: "Add two numbers",
+      params:      { a: { type: "number", required: true }, b: { type: "number", required: true } },
+      execute:     ->(a:, b:) { a + b },
+    )
+
+    adapter.name.should == "adder"
+    adapter.call(a: 1, b: 2).should == 3
+  end
+
+  it "is idempotent" do
+    adapter = Brute::Tools::Adapter.wrap(name: "x", description: "", execute: -> {})
+    Brute::Tools::Adapter.wrap(adapter).should == adapter
+  end
+
+  it "wrap_all keys adapters by name symbol" do
+    tools = Brute::Tools::Adapter.wrap_all([
+      { name: "a", description: "", execute: -> {} },
+      { name: "b", description: "", execute: -> {} },
+    ])
+    tools.keys.should == [:a, :b]
+    tools[:a].should.be.kind_of?(Brute::Tools::Adapter)
+  end
+
+  it "exposes the wrapped original" do
+    klass = Class.new(::Brute::Tool) do
+      description "test tool"
+      def name; "original"; end
+      def execute; "ok"; end
+    end
+    instance = klass.new
+
+    Brute::Tools::Adapter.wrap(instance).original.should == instance
+  end
+
+  it "produces a neutral JSON-schema-ish definition" do
+    adapter = Brute::Tools::Adapter.wrap(
+      name:        "echo",
+      description: "Echo",
+      params:      { msg: { type: "string", desc: "message", required: true } },
+      execute:     ->(msg:) { msg },
+    )
+
+    defn = adapter.to_h
+    defn[:name].should == "echo"
+    defn[:parameters][:properties][:msg][:type].should == "string"
+    defn[:parameters][:required].should == ["msg"]
+  end
+end

data/lib/brute/tools/fs/file_mutation_queue.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+
+module Brute
+  module Tools
+    # @namespace
+    module FS
+      # Per-file serialization queue for concurrent tool execution.
+      #
+      # When tools run in parallel (via threads or async fibers), multiple tools
+      # may target the same file simultaneously. Without serialization, a sequence
+      # like [read → patch → write] on the same file would race and lose edits.
+      #
+      # This module provides a single public method:
+      #
+      #   Brute::Tools::FS::FileMutationQueue.serialize("/path/to/file") do
+      #     # snapshot + read + modify + write — all atomic for this path
+      #   end
+      #
+      # Design (mirrors pi-mono's withFileMutationQueue):
+      #   - Operations on the SAME file are serialized (run one at a time)
+      #   - Operations on DIFFERENT files run fully in parallel (independent mutexes)
+      #   - Symlink-aware: resolves real paths so aliases share one mutex
+      #   - Error-safe: mutex is always released in `ensure`, so failures never deadlock
+      #   - Self-cleaning: per-file mutexes are removed when no longer in use
+      #
+      # Ruby 3.4's Mutex is fiber-scheduler-aware, so this works correctly with
+      # both :thread and :task (Async) concurrency strategies.
+      #
+      module FileMutationQueue
+        @mutexes = {}       # path → Mutex
+        @waiters = Hash.new(0) # path → number of threads/fibers waiting or holding
+        @guard = Mutex.new  # protects @mutexes and @waiters
+
+        class << self
+          # Serialize a block of work for a given file path.
+          #
+          # Concurrent calls targeting the same canonical path will execute
+          # sequentially in FIFO order. Calls targeting different paths
+          # proceed in parallel with zero contention.
+          #
+          # @parameter path [String] The file path to serialize on.
+          # @yields {block} The mutation work to perform (snapshot, read, write, etc.)
+          # @returns Whatever the block returns.
+          def serialize(path, &block)
+            key = canonical_path(path)
+            mutex = acquire_mutex(key)
+
+            mutex.synchronize(&block)
+          ensure
+            release_mutex(key)
+          end
+
+          # Clear all tracked mutexes. Used in tests and session resets.
+          def clear!
+            @guard.synchronize do
+              @mutexes.clear
+              @waiters.clear
+            end
+          end
+
+          # Number of file paths currently tracked (for diagnostics).
+          def size
+            @guard.synchronize { @mutexes.size }
+          end
+
+          private
+
+            # Resolve a file path to a canonical key.
+            # Uses File.realpath to follow symlinks so that aliases to the
+            # same underlying file share one mutex. Falls back to
+            # File.expand_path for files that don't exist yet (e.g., new writes).
+            def canonical_path(path)
+              resolved = File.expand_path(path)
+              begin
+                File.realpath(resolved)
+              rescue Errno::ENOENT
+                resolved
+              end
+            end
+
+            # Get (or create) a mutex for a file path and increment the waiter count.
+            def acquire_mutex(key)
+              @guard.synchronize do
+                @mutexes[key] ||= Mutex.new
+                @waiters[key] += 1
+                @mutexes[key]
+              end
+            end
+
+            # Decrement the waiter count and clean up the mutex if no one else needs it.
+            def release_mutex(key)
+              @guard.synchronize do
+                @waiters[key] -= 1
+                if @waiters[key] <= 0
+                  @mutexes.delete(key)
+                  @waiters.delete(key)
+                end
+              end
+            end
+        end
+      end
+    end
+  end
+end

data/lib/brute/tools/fs/snapshot_store.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+
+module Brute
+  module Tools
+    # @namespace
+    module FS
+      # Per-path stack of file snapshots used by fs_write, fs_patch, fs_remove
+      # to enable undo. Each call to .save pushes the current content (or
+      # :did_not_exist for new files). .pop retrieves the most recent snapshot.
+      module SnapshotStore
+        @snapshots = Hash.new { |h, k| h[k] = [] }
+        @mutex     = Mutex.new
+
+        class << self
+          # Push the current content of +path+ onto the snapshot stack.
+          # If the file doesn't exist yet, records +:did_not_exist+.
+          def save(path)
+            key = File.expand_path(path)
+            content = File.exist?(key) ? File.read(key) : :did_not_exist
+            @mutex.synchronize { @snapshots[key].push(content) }
+          end
+
+          # Pop and return the most recent snapshot for +path+, or +nil+
+          # if there is no history.
+          def pop(path)
+            key = File.expand_path(path)
+            @mutex.synchronize { @snapshots[key].pop }
+          end
+
+          # Clear all snapshots. Used in tests and session resets.
+          def clear!
+            @mutex.synchronize { @snapshots.clear }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/brute/tools/fs_patch.rb

@@ -6,7 +6,7 @@ require "brute/tools"
 
 module Brute
   module Tools
-    class FSPatch < RubyLLM::Tool
+    class FSPatch < Brute::Tool
       description 'Replace a specific string in a file. The old_string must match exactly ' \
                   '(including whitespace and indentation). Always read a file before patching it.'
 
@@ -19,13 +19,13 @@ module Brute
 
       def execute(file_path:, old_string:, new_string:, replace_all: false)
         path = File.expand_path(file_path)
-        Brute::Queue::FileMutationQueue.serialize(path) do
+        Brute::Tools::FS::FileMutationQueue.serialize(path) do
           raise "File not found: #{path}" unless File.exist?(path)
 
           original = File.read(path)
           raise "old_string not found in #{path}" unless original.include?(old_string)
 
-          Brute::Store::SnapshotStore.save(path)
+          Brute::Tools::FS::SnapshotStore.save(path)
 
           updated = if replace_all
                       original.gsub(old_string, new_string)
@@ -43,7 +43,9 @@ module Brute
   end
 end
 
-test do
+__END__
+
+describe "brute/tools/fs_patch" do
   require "tmpdir"
 
   it "replaces old_string with new_string" do

data/lib/brute/tools/fs_read.rb

@@ -26,9 +26,9 @@ module Brute
     # 7. File-not-found suggestions — on miss, scan the parent directory for
     #    similar names and suggest "Did you mean...?" candidates.
     # 8. Return a plain string instead of a Hash — avoids the .to_s repr
-    #    bloat when ToolCall coerces the result for the LLM message.
+    #    bloat when ToolPipeline coerces the result for the LLM message.
     #
-    class FSRead < RubyLLM::Tool
+    class FSRead < Brute::Tool
       description "Read the contents of a file. Returns file content with line numbers. " \
                   "Use start_line/end_line for partial reads of large files."
 
@@ -146,7 +146,9 @@ module Brute
   end
 end
 
-test do
+__END__
+
+describe "brute/tools/fs_read" do
   require "tmpdir"
 
   it "reads a file without error" do

data/lib/brute/tools/fs_remove.rb

@@ -7,7 +7,7 @@ require "fileutils"
 
 module Brute
   module Tools
-    class FSRemove < RubyLLM::Tool
+    class FSRemove < Brute::Tool
       description "Remove a file or empty directory."
 
       param :path, type: 'string', desc: "Path to the file or directory to remove", required: true
@@ -16,10 +16,10 @@ module Brute
 
       def execute(path:)
         target = File.expand_path(path)
-        Brute::Queue::FileMutationQueue.serialize(target) do
+        Brute::Tools::FS::FileMutationQueue.serialize(target) do
           raise "Path not found: #{target}" unless File.exist?(target)
 
-          Brute::Store::SnapshotStore.save(target) if File.file?(target)
+          Brute::Tools::FS::SnapshotStore.save(target) if File.file?(target)
 
           if File.directory?(target)
             Dir.rmdir(target)