brute 2.0.6 → 3.0.1

data/lib/brute/tools/fs_search.rb

@@ -21,7 +21,7 @@ module Brute
     # 5. Return a plain string instead of a Hash.
     # 6. Align output cap with universal truncation (2000 lines / 50 KB).
     #
-    class FSSearch < RubyLLM::Tool
+    class FSSearch < Brute::Tool
       description "Search file contents using ripgrep (regex), or find files by glob pattern. " \
                   "Returns matching lines with file paths and line numbers."
 
@@ -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

@@ -6,7 +6,7 @@ require "brute/tools"
 
 module Brute
   module Tools
-    class FSUndo < RubyLLM::Tool
+    class FSUndo < Brute::Tool
       description "Undo the last write or patch operation on a file, restoring it to " \
                   "its previous state."
 
@@ -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

@@ -7,7 +7,7 @@ require 'fileutils'
 
 module Brute
   module Tools
-    class FSWrite < RubyLLM::Tool
+    class FSWrite < Brute::Tool
       description "Write content to a file. Creates parent directories if they don't exist. " \
                   'Use this for creating new files or completely replacing file contents.'
 
@@ -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/net_fetch.rb

@@ -9,7 +9,7 @@ require "uri"
 
 module Brute
   module Tools
-    class NetFetch < RubyLLM::Tool
+    class NetFetch < Brute::Tool
       description "Fetch content from a URL. Returns the response body as text."
 
       param :url, type: 'string', desc: "The URL to fetch", required: true

data/lib/brute/tools/question.rb

@@ -6,7 +6,7 @@ require "brute/tools"
 
 module Brute
   module Tools
-    class Question < RubyLLM::Tool
+    class Question < Brute::Tool
       description "Ask the user questions during execution. Use this to gather preferences, " \
                   "clarify ambiguous instructions, get decisions on implementation choices, or " \
                   "offer choices about direction. Users can always select \"Other\" to provide " \

data/lib/brute/tools/shell.rb

@@ -22,7 +22,7 @@ module Brute
     #    the LLM (defaults to 5 minutes).
     # 5. Return a plain string instead of a Hash.
     #
-    class Shell < RubyLLM::Tool
+    class Shell < Brute::Tool
       description "Execute a shell command and return stdout, stderr, and exit code. " \
                   "Use for git operations, running tests, installing packages, etc."
 
@@ -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 < Brute::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,101 @@
+# 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
+    #       # The LLM call, written with your library of choice. Convert
+    #       # env[:messages] to its format, call it, and append the response
+    #       # back as Brute::Message values (the MessageTransport pattern —
+    #       # see examples/ruby_llm.rb, examples/openai.rb, ...).
+    #     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
+
+      # Lets ToolPipeline treat SubAgents the same as any other tool
+      # 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

@@ -6,14 +6,14 @@ require "brute/tools"
 
 module Brute
   module Tools
-    class TodoRead < RubyLLM::Tool
+    class TodoRead < Brute::Tool
       description "Read the current todo list to check task status and progress."
       param :_placeholder, type: 'string', desc: "Unused, pass any value", required: false
 
       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

@@ -6,7 +6,7 @@ require "brute/tools"
 
 module Brute
   module Tools
-    class TodoWrite < RubyLLM::Tool
+    class TodoWrite < Brute::Tool
       description "Create or update the todo list. Send the complete list each time — " \
                   "this replaces the existing list entirely."
 
@@ -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,169 @@
+# 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 ::Brute::Message    then Brute.log(input)
+          when ::Hash              then Brute.log(Brute::Message.new(**input.transform_keys(&:to_sym)))
+          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