brute 2.0.5 → 3.0.0

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

@@ -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,7 +26,7 @@ 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
       description "Read the contents of a file. Returns file content with line numbers. " \
@@ -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

@@ -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)

data/lib/brute/tools/fs_search.rb

@@ -62,7 +62,9 @@ module Brute
   end
 end
 
-test do
+__END__
+
+describe "brute/tools/fs_search" do
   require "tmpdir"
 
   it "searches the current directory without error" do

data/lib/brute/tools/fs_undo.rb

@@ -16,8 +16,8 @@ module Brute
 
       def execute(path:)
         target = File.expand_path(path)
-        Brute::Queue::FileMutationQueue.serialize(target) do
-          snapshot = Brute::Store::SnapshotStore.pop(target)
+        Brute::Tools::FS::FileMutationQueue.serialize(target) do
+          snapshot = Brute::Tools::FS::SnapshotStore.pop(target)
           raise "No undo history available for: #{target}" unless snapshot
 
           if snapshot == :did_not_exist

data/lib/brute/tools/fs_write.rb

@@ -18,9 +18,9 @@ module Brute
 
       def execute(file_path:, content:)
         path = File.expand_path(file_path)
-        Brute::Queue::FileMutationQueue.serialize(path) do
+        Brute::Tools::FS::FileMutationQueue.serialize(path) do
           old_content = File.exist?(path) ? File.read(path) : ''
-          Brute::Store::SnapshotStore.save(path)
+          Brute::Tools::FS::SnapshotStore.save(path)
           FileUtils.mkdir_p(File.dirname(path))
           File.write(path, content)
           diff = Brute::Diff.unified(old_content, content)
@@ -31,7 +31,9 @@ module Brute
   end
 end
 
-test do
+__END__
+
+describe "brute/tools/fs_write" do
   require "tmpdir"
 
   it "writes content to a new file" do

data/lib/brute/tools/shell.rb

@@ -60,7 +60,9 @@ module Brute
   end
 end
 
-test do
+__END__
+
+describe "brute/tools/shell" do
   #it "runs a command without error" do
   #  result = Brute::Tools::Shell.new.call(command: "echo hello")
   #  result.strip.should =~ /hello/

data/lib/brute/tools/skill_load.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "fileutils"
+
+require "bundler/setup"
+require "brute"
+require "brute/tools"
+
+module Brute
+  module Tools
+    # The `skill` tool — stages 2 (activation) and 3 (execution) of the Agent
+    # Skills progressive-disclosure lifecycle (https://agentskills.io).
+    #
+    # Stage 1 (discovery) happens in the system prompt: Brute::Prompts::Skills
+    # lists each skill's name + description only (~100 tokens each). When a task
+    # matches, the model calls this tool with the skill name to pull the full
+    # SKILL.md body into the conversation (stage 2).
+    #
+    # The output also reports the skill's base directory and a capped listing of
+    # bundled files. That is stage 3: skills bundle scripts/, references/, and
+    # assets/ that the model runs or reads *through the agent's existing tools*
+    # (`shell`, `read`) by relative path. There is no separate skill runtime.
+    #
+    # The tool must scan the same directories as Prompts::Skills, or it would
+    # advertise skills it cannot load. Both default to Dir.pwd; agents that point
+    # the prompt at a custom root (e.g. ctx.merge(cwd: __dir__)) should build the
+    # tool with the matching cwd: Brute::Tools::SkillLoad.new(cwd: __dir__).
+    #
+    # Reference: opencode's tool/skill.ts.
+    class SkillLoad < RubyLLM::Tool
+      description "Load a specialized skill when the task at hand matches one of the " \
+                  "available skills listed in the system context. This injects the skill's " \
+                  "full instructions into the conversation, plus the skill's base directory " \
+                  "and a listing of bundled files (scripts, references, assets) that you can " \
+                  "run or read by relative path using your existing tools. The name must match " \
+                  "one of the available skills."
+
+      param :name, type: "string", desc: "The name of the skill from the available skills list", required: true
+
+      FILE_LIMIT = 10
+
+      def name; "skill"; end
+
+      def initialize(cwd: Dir.pwd)
+        super()
+        @cwd = cwd
+      end
+
+      def execute(name:)
+        skill = Brute::Skill.get(name, cwd: @cwd)
+        return unknown_skill(name) unless skill
+
+        directory = File.dirname(skill.location)
+        files = bundled_files(directory)
+
+        render(skill, directory, files)
+      end
+
+      private
+
+      def unknown_skill(name)
+        available = Brute::Skill.all(cwd: @cwd).map(&:name)
+        listing = available.empty? ? "(none)" : available.join(", ")
+        "Error: unknown skill #{name.inspect}. Available skills: #{listing}"
+      end
+
+      def bundled_files(directory)
+        Dir.glob(File.join(directory, "**", "*"), File::FNM_DOTMATCH)
+           .select { |p| File.file?(p) }
+           .reject { |p| File.basename(p) == Brute::Skill::FILENAME }
+           .map { |p| Pathname.new(p).relative_path_from(Pathname.new(directory)).to_s }
+           .sort
+           .first(FILE_LIMIT)
+      end
+
+      def render(skill, directory, files)
+        lines = [
+          "<skill name=\"#{skill.name}\">",
+          "# Skill: #{skill.name}",
+          "",
+          skill.content,
+          "",
+          "Base directory for this skill: #{directory}",
+          "Relative paths in this skill (e.g. scripts/, references/, assets/) are relative to " \
+            "this base directory. Use your existing tools (read, shell) to access them.",
+        ]
+
+        unless files.empty?
+          lines << ""
+          lines << "Bundled files (sampled, up to #{FILE_LIMIT}):"
+          files.each { |f| lines << "  #{f}" }
+        end
+
+        lines << "</skill>"
+        lines.join("\n")
+      end
+    end
+  end
+end
+
+__END__
+
+describe "brute/tools/skill_load" do
+  require "tmpdir"
+
+  def write_skill(root, name, body: "Do the thing.", frontmatter: nil)
+    dir = File.join(root, ".brute", "skills", name)
+    FileUtils.mkdir_p(dir)
+    frontmatter ||= "name: #{name}\ndescription: A skill that does #{name}"
+    File.write(File.join(dir, "SKILL.md"), "---\n#{frontmatter}\n---\n\n#{body}\n")
+    dir
+  end
+
+  it "returns the skill body and base directory" do
+    Dir.mktmpdir do |root|
+      dir = write_skill(root, "debugging", body: "Step 1. Reproduce.")
+      out = Brute::Tools::SkillLoad.new(cwd: root).call(name: "debugging")
+      out.should =~ /Step 1\. Reproduce\./
+      out.should =~ /Base directory for this skill: #{Regexp.escape(dir)}/
+    end
+  end
+
+  it "lists bundled files but not SKILL.md itself" do
+    Dir.mktmpdir do |root|
+      dir = write_skill(root, "deploy")
+      FileUtils.mkdir_p(File.join(dir, "scripts"))
+      File.write(File.join(dir, "scripts", "run.sh"), "echo hi")
+      out = Brute::Tools::SkillLoad.new(cwd: root).call(name: "deploy")
+      out.should =~ %r{scripts/run\.sh}
+      out.should.not =~ /SKILL\.md/
+    end
+  end
+
+  it "caps bundled files at FILE_LIMIT" do
+    Dir.mktmpdir do |root|
+      dir = write_skill(root, "many")
+      15.times { |i| File.write(File.join(dir, "f#{i}.txt"), "x") }
+      out = Brute::Tools::SkillLoad.new(cwd: root).call(name: "many")
+      out.scan(/^  f\d+\.txt$/).size.should.be <= Brute::Tools::SkillLoad::FILE_LIMIT
+    end
+  end
+
+  it "returns a tool-error string (not an exception) for an unknown skill" do
+    Dir.mktmpdir do |root|
+      write_skill(root, "alpha")
+      out = Brute::Tools::SkillLoad.new(cwd: root).call(name: "missing")
+      out.should =~ /unknown skill/
+      out.should =~ /alpha/
+    end
+  end
+
+  it "defaults cwd to Dir.pwd" do
+    Brute::Tools::SkillLoad.new.should.be.kind_of(Brute::Tools::SkillLoad)
+  end
+end

data/lib/brute/tools/sub_agent.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+require 'brute/turn/agent_pipeline'
+
+module Brute
+  module Tools
+    # A SubAgent is an Agent that exposes a tool-shaped facade so it can
+    # be dropped into another agent's tools list. The parent agent hands it
+    # to the LLM as a regular tool; when invoked, the SubAgent runs its own
+    # pipeline against a fresh Session built from the tool arguments, then
+    # returns the final assistant message as the tool result.
+    #
+    # Usage:
+    #
+    #   researcher = Brute::Tools::SubAgent.new(
+    #     name:        "research",
+    #     description: "Delegate a research task to a read-only sub-agent.",
+    #   ) do
+    #     use Brute::Middleware::SystemPrompt
+    #     use Brute::Middleware::Loop::ToolResult
+    #     use Brute::Middleware::MaxIterations, max_iterations: 10
+    #     use Brute::Middleware::ToolPipeline, tools: [Brute::Tools::FSRead, Brute::Tools::FSSearch]
+    #     run ->(env) do
+    #       ctx = RubyLLM.context { |c| c.ollama_api_base = ENV["OLLAMA_API_BASE"] }
+    #       model, provider = RubyLLM::Models.resolve(
+    #         "llama3.2", provider: :ollama, assume_exists: true, config: ctx.config)
+    #       response = provider.complete(env[:messages],
+    #                                    tools:       Brute.rubyllm_tools(env[:tools]),
+    #                                    temperature: 0.7,
+    #                                    model:       model)
+    #       RubyLLM::MessageTransport.new(response).wrap_each { |m| env[:messages] << m }
+    #     end
+    #   end
+    #
+    #   # The SubAgent IS a tool — hand it to a parent agent's ToolPipeline:
+    #   main_agent = Brute.agent do
+    #     use Brute::Middleware::ToolPipeline, tools: [Brute::Tools::FSRead, researcher]
+    #     run ->(env) { ... }
+    #   end
+    #   main_agent.start("delegate some research")
+    #
+    class SubAgent < Brute::Turn::AgentPipeline
+      DEFAULT_PARAMS = {
+        task: { type: "string", desc: "A clear, detailed description of the task", required: true },
+      }.freeze
+
+      attr_reader :sub_agent_name, :description, :params
+
+      def initialize(name:, description:, params: DEFAULT_PARAMS, &block)
+        @sub_agent_name = name.to_s
+        @description    = description
+        @params         = params
+        super(&block)
+      end
+
+      # Tool-shaped entry point. Builds a session from arguments, runs the
+      # agent loop, returns the last assistant message as a string.
+      def execute(arguments)
+        session = build_session(arguments)
+        start(session)
+        extract_result(session)
+      end
+
+      # Adapter so the parent agent's completion middleware (and ruby_llm)
+      # sees this as a regular tool. ToolPipeline middleware should call
+      # `to_ruby_llm` when building the tools hash if a tool responds to it.
+      def to_ruby_llm
+        sub = self
+        Class.new(::RubyLLM::Tool) do
+          description sub.description
+          sub.params.each { |k, opts| param k, **opts }
+          define_method(:name) { sub.sub_agent_name }
+          define_method(:execute) { |**args| sub.execute(args) }
+        end.new
+      end
+
+      # Lets ToolPipeline treat SubAgents the same as RubyLLM::Tool instances
+      # without checking respond_to? everywhere.
+      def name
+        @sub_agent_name
+      end
+
+      private
+
+        def build_session(arguments)
+          task = arguments[:task] || arguments["task"]
+          Brute.log.tap { |s| s.user(task) }
+        end
+
+        def extract_result(session)
+          last = session.reverse_each.find do |m|
+            m.role == :assistant && m.content.is_a?(String) && !m.content.empty?
+          end
+          last&.content || "(sub-agent completed but produced no text response)"
+        end
+    end
+  end
+end
+
+__END__
+
+describe "brute/tools/sub_agent" do
+  it "exposes a name matching the sub-agent identifier" do
+    sa = Brute::Tools::SubAgent.new(name: "research", description: "test") do
+      run ->(env) { env[:messages].assistant("done") }
+    end
+    sa.name.should == "research"
+  end
+
+  it "execute returns the last assistant message" do
+    sa = Brute::Tools::SubAgent.new(name: "research", description: "test") do
+      run ->(env) { env[:messages].assistant("result text") }
+    end
+    sa.execute(task: "do something").should == "result text"
+  end
+end

data/lib/brute/tools/todo_list/store.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+
+module Brute
+  module Tools
+    # @namespace
+    module TodoList
+      # In-memory todo list storage. The agent uses this to track multi-step
+      # tasks via the todo_read / todo_write tools. The list is replaced
+      # wholesale on each todo_write call.
+      module Store
+        @items = []
+        @mutex = Mutex.new
+
+        class << self
+          # Replace the entire todo list.
+          def replace(items)
+            @mutex.synchronize { @items = items.dup }
+          end
+
+          # Return all current items.
+          def all
+            @mutex.synchronize { @items.dup }
+          end
+
+          # Clear all items.
+          def clear!
+            @mutex.synchronize { @items.clear }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/brute/tools/todo_read.rb

@@ -13,7 +13,7 @@ module Brute
       def name; "todo_read"; end
 
       def execute(_placeholder: nil)
-        {todos: Brute::Store::TodoStore.all}
+        {todos: Brute::Tools::TodoList::Store.all}
       end
     end
   end

data/lib/brute/tools/todo_write.rb

@@ -36,7 +36,7 @@ module Brute
           t = t.transform_keys(&:to_sym) if t.is_a?(Hash)
           {id: t[:id], content: t[:content], status: t[:status]}
         end
-        Brute::Store::TodoStore.replace(items)
+        Brute::Tools::TodoList::Store.replace(items)
         {success: true, count: items.size}
       end
     end

data/lib/brute/tools.rb

@@ -20,7 +20,8 @@ module Brute
       Tools::NetFetch,
       Tools::TodoWrite,
       Tools::TodoRead,
-      Tools::Question
+      Tools::Question,
+      Tools::SkillLoad
     ].freeze
   end
 end

data/lib/brute/truncation.rb

@@ -124,7 +124,9 @@ module Brute
   end
 end
 
-test do
+__END__
+
+describe "brute/truncation" do
   require "tmpdir"
   require "fileutils"
 

data/lib/brute/turn/agent_pipeline.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+require "brute/messages"
+require "brute/turn/pipeline"
+
+module Brute
+  module Turn
+
+    #   agent = Brute.agent            # => AgentPipeline
+    #     .use(Middleware::X)          # => same AgentPipeline (.use returns self)
+    #     .run ->(env) { ... }         # => same AgentPipeline (.run returns self)
+    #
+    #   agent.start("what changed?")   # => runs the turn, returns env
+    #
+    class AgentPipeline < Pipeline
+
+      # Register a slash command:
+      #
+      #   map "/weather", "Get the weather in the following location $ARGUMENTS"
+      #   map("/weather") { "Get the weather in the following location $ARGUMENTS" }
+      #
+      def map(command, template = nil, &block)
+        command = command.to_s
+        command = command.start_with?("/") ? command : "/#{command}"
+
+        (@map ||= {})[command] = block || proc { template }
+        self
+      end
+
+      def generate_map(default_app, mapping)
+        super.tap do |routes|
+          routes.define_singleton_method(:call) do |prompt|
+            name, args = prompt.to_s.strip.split(/\s+/, 2)
+            prompt = mapping[name].call.to_s.gsub("$ARGUMENTS", args.to_s) if mapping[name]
+            default_app.call(prompt)
+          end
+        end
+      end
+
+      def start(input = nil, events: NullSink.new)
+        env = {
+          messages:          coerce_messages(input),
+          events:            events,
+          metadata:          {},
+          current_iteration: 1,
+        }
+        env.tap do
+          build.call(env)
+        end
+      end
+
+      private
+
+        def coerce_messages(input)
+          case input
+          when nil                 then Brute.log
+          when ::String            then Brute.log.tap { |log| log.user(input) }
+          when ::RubyLLM::Message  then Brute.log(input)
+          when ::Array             then input.extend(Brute::Messages)
+          else Brute.log(input)
+          end
+        end
+    end
+  end
+end
+
+__END__
+
+describe "brute/turn/agent_pipeline" do
+  require "brute/messages"
+
+  # A top-level stub middleware the eval'd scripts can reference.
+  AgentStubMW = Class.new do
+    def initialize(app); @app = app; end
+    def call(env); env[:metadata][:mw] = true; @app.call(env); end
+  end unless defined?(AgentStubMW)
+
+  it "starts a turn and returns the env with the log in :messages" do
+    agent = Brute.agent.run(->(env) { env[:messages].assistant("hello") })
+    agent.should.be.kind_of?(Brute::Turn::AgentPipeline)
+
+    env = agent.start("hi")
+    env[:messages].map(&:role).should == [:user, :assistant]
+    env[:messages].last.content.should == "hello"
+  end
+
+  it "coerces a String input into a user message" do
+    captured = nil
+    Brute.agent.run(->(env) { captured = env[:messages].dup }).start("a question")
+    captured.first.role.should == :user
+    captured.first.content.should == "a question"
+  end
+
+  it "shapes env with no config (that lives in the run proc)" do
+    captured = nil
+    Brute.agent.run(->(env) { captured = env }).start
+    captured[:current_iteration].should == 1
+    captured.key?(:provider).should.be.false
+    captured.key?(:tools).should.be.false
+  end
+
+  it "is its own builder — .use and .run both return the AgentPipeline" do
+    agent = Brute.agent.use(AgentStubMW)
+    agent.should.be.kind_of?(Brute::Turn::AgentPipeline)
+
+    agent.run { |env| env[:messages].assistant("done") }.should.equal?(agent)
+
+    env = agent.start("go")
+    env[:metadata][:mw].should.be.true
+    env[:messages].last.content.should == "done"
+  end
+
+  it "parses a ru-style string into a runnable Agent" do
+    agent = Brute::Turn::AgentPipeline.new_from_string('run ->(env) { env[:messages].assistant("from ru") }', "(test)")
+    agent.should.be.kind_of?(Brute::Turn::AgentPipeline)
+    agent.start("hi")[:messages].last.content.should == "from ru"
+  end
+
+  it "use in a ru string wraps the terminal" do
+    script = <<~RUBY
+      use AgentStubMW
+      run ->(env) { env[:messages].assistant("ok") }
+    RUBY
+    Brute::Turn::AgentPipeline.new_from_string(script, "(test)").start("go")[:metadata][:mw].should.be.true
+  end
+
+  it "builds inline from a block passed to Brute.agent" do
+    agent = Brute.agent do
+      use AgentStubMW
+      run ->(env) { env[:messages].assistant("done") }
+    end
+    agent.start("go")[:messages].last.content.should == "done"
+  end
+
+  it "map chains and to_app taps generate_map to build a (retargeted) URLMap" do
+    agent = Brute.agent
+      .map("/weather", "Get the weather in the following location $ARGUMENTS")
+      .run(->(prompt) { prompt })
+
+    agent.should.be.kind_of?(Brute::Turn::AgentPipeline)   # map returns self
+    agent.build.should.be.kind_of?(::Rack::URLMap)         # to_app tapped generate_map (super)
+  end
+
+  it "swaps a /command prompt for its template ($ARGUMENTS) and calls the app" do
+    got = nil
+    agent = Brute.agent
+      .map("/weather", "Get the weather in the following location $ARGUMENTS")
+      .map("/echo") { "you said: $ARGUMENTS" }
+      .run(->(prompt) { got = prompt })
+
+    agent.call("/weather London")
+    got.should == "Get the weather in the following location London"
+    agent.call("/echo hi there")
+    got.should == "you said: hi there"
+  end
+
+  it "passes non-commands through untouched (and normalizes the slash)" do
+    got = nil
+    agent = Brute.agent.map("weather", "W $ARGUMENTS").run(->(prompt) { got = prompt })
+
+    agent.call("just a question")
+    got.should == "just a question"
+    agent.call("/weather NYC")   # registered as "weather", normalized to "/weather"
+    got.should == "W NYC"
+  end
+end