brute 2.0.6 → 3.0.0

data/lib/brute/agent.rb

@@ -1,82 +0,0 @@
-# frozen_string_literal: true
-
-require "bundler/setup"
-require "brute"
-require 'brute/pipeline'
-
-module Brute
-  DEFAULT_SYSTEM_PROMPT = "You are a helpful assistant, hellbent on taking over the world."
-
-  # An agent is a Pipeline configured for LLM turns. It carries the
-  # provider/model/tools configuration and shapes env from a Session
-  # (the conversation message log).
-  #
-  # Usage:
-  #
-  #   agent = Brute::Agent.new(
-  #     provider: Brute.provider,
-  #     model:    "claude-sonnet-4-20250514",
-  #     tools:    Brute::Tools::ALL,
-  #   ) do
-  #     use Brute::Middleware::EventHandler, handler_class: TerminalOutput
-  #     use Brute::Middleware::SystemPrompt
-  #     use Brute::Middleware::MaxIterations
-  #     use Brute::Middleware::Question
-  #     use Brute::Middleware::ToolCall
-  #     run Brute::Middleware::LLMCall.new
-  #   end
-  #
-  #   session = Brute::Session.new
-  #   session.user("fix the failing tests")
-  #   agent.call(session)
-  #
-  class Agent < Pipeline
-    attr_reader :provider, :model, :tools
-
-    def initialize(provider:, model: nil, tools: [], &block)
-      @provider = provider
-      @model    = model
-      @tools    = tools
-      super(&block)
-    end
-
-    # Run one turn against the given session. The session is mutated
-    # in place (assistant + tool messages appended). Returns the env
-    # hash so callers can access metadata (timing, tokens, etc.).
-    def call(session, events: NullSink.new)
-      env = {
-        messages:          session,
-        provider:          @provider,
-        model:             @model,
-        tools:             @tools,
-        events:            events,
-        metadata:          {},
-        system_prompt:     DEFAULT_SYSTEM_PROMPT,
-        current_iteration: 1,
-      }
-      super(env)
-      env
-    end
-  end
-end
-
-test do
-  it "runs a turn and returns the env with session in :messages" do
-    agent = Brute::Agent.new(provider: :stub) do
-      run ->(env) { env[:messages].assistant("hello") }
-    end
-    session = Brute::Session.new
-    session.user("hi")
-    env = agent.call(session)
-    env[:messages].should == session
-  end
-
-  it "passes provider/model/tools through env" do
-    captured = nil
-    capture = ->(env) { captured = env.slice(:provider, :model, :tools) }
-
-    agent = Brute::Agent.new(provider: :stub, model: "m", tools: [:a]) { run capture }
-    agent.call(Brute::Session.new)
-    captured.should == { provider: :stub, model: "m", tools: [:a] }
-  end
-end

data/lib/brute/middleware/003_tool_result_loop.rb

@@ -1,103 +0,0 @@
-# frozen_string_literal: true
-
-require "bundler/setup"
-require "brute"
-
-module Brute
-  module Middleware
-    # Re-invokes the inner stack whenever the last message is a :tool result.
-    #
-    # After the inner pipeline runs (LLMCall responds, ToolCall executes tools
-    # and appends :tool messages), this middleware checks if tool results are
-    # pending. If so, it increments the iteration counter and loops — sending
-    # the tool results back through MaxIterations → ToolCall → LLMCall so the
-    # LLM can see them.
-    #
-    # The loop breaks when:
-    #   - The LLM responds with text only (no tool calls) — last message is :assistant
-    #   - env[:should_exit] is set (e.g. by MaxIterations)
-    #
-    class ToolResultLoop
-      def initialize(app)
-        @app = app
-      end
-
-      def call(env)
-        loop do
-          @app.call(env)
-
-          break if env[:should_exit]
-          break unless env[:messages].last&.role == :tool
-
-          env[:current_iteration] += 1
-        end
-
-        env
-      end
-    end
-  end
-end
-
-test do
-  require "brute/session"
-
-  it "loops until last message is not a tool result" do
-    call_count = 0
-
-    # Fake inner app: first call appends a :tool message, second call appends :assistant
-    inner = ->(env) do
-      call_count += 1
-      if call_count == 1
-        env[:messages] << RubyLLM::Message.new(role: :tool, content: "result", tool_call_id: "tc1")
-      else
-        env[:messages] << RubyLLM::Message.new(role: :assistant, content: "done")
-      end
-    end
-
-    mw = Brute::Middleware::ToolResultLoop.new(inner)
-    env = { messages: Brute::Session.new, current_iteration: 1 }
-    env[:messages].user("hi")
-
-    mw.call(env)
-
-    call_count.should == 2
-    env[:current_iteration].should == 2
-    env[:messages].last.role.should == :assistant
-  end
-
-  it "stops when should_exit is set" do
-    call_count = 0
-
-    inner = ->(env) do
-      call_count += 1
-      env[:messages] << RubyLLM::Message.new(role: :tool, content: "result", tool_call_id: "tc#{call_count}")
-      env[:should_exit] = { reason: "max" } if call_count >= 2
-    end
-
-    mw = Brute::Middleware::ToolResultLoop.new(inner)
-    env = { messages: Brute::Session.new, current_iteration: 1 }
-    env[:messages].user("hi")
-
-    mw.call(env)
-
-    call_count.should == 2
-  end
-
-  it "does not loop when last message is assistant" do
-    call_count = 0
-
-    inner = ->(env) do
-      call_count += 1
-      env[:messages] << RubyLLM::Message.new(role: :assistant, content: "hello")
-    end
-
-    mw = Brute::Middleware::ToolResultLoop.new(inner)
-    env = { messages: Brute::Session.new, current_iteration: 1 }
-    env[:messages].user("hi")
-
-    mw.call(env)
-
-    call_count.should == 1
-    env[:current_iteration].should == 1
-  end
-end

data/lib/brute/middleware/100_llm_call.rb

@@ -1,63 +0,0 @@
-# frozen_string_literal: true
-
-require "bundler/setup"
-require "brute"
-
-module Brute
-  module Middleware
-    # Terminal middleware. Calls the LLM with the current conversation,
-    # appends the response to the session, and fires events along the way.
-    #
-    class LLMCall
-      def call(env)
-
-        available_tools = env[:tools].each_with_object({}) do |tool, hash|
-          instance = tool.is_a?(Class) ? tool.new : tool
-          instance = instance.to_ruby_llm if instance.respond_to?(:to_ruby_llm)
-          hash[instance.name.to_sym] = instance
-        end
-
-        completion_options = {
-          model: RubyLLM.models.find(env[:model], env[:provider]),
-          tools: available_tools,
-          temperature: env.fetch(:temperature, 0.7),
-        }
-
-        complete(completion_options, env).then do |response|
-          env[:messages] << response
-        end
-
-        env
-      end
-
-      private
-
-        def complete(kwargs, env)
-          provider_client = RubyLLM::Provider.resolve(env[:provider]).new(Brute.config)
-
-          if env[:streaming] == true
-            provider_client.complete(env[:messages], **kwargs) do |chunk|
-              if chunk.content && !chunk.content.to_s.empty?
-                env[:events] << { type: :content, data: chunk.content.to_s }
-              end
-
-              if chunk.respond_to?(:thinking) && chunk.thinking&.respond_to?(:text) && chunk.thinking.text
-                env[:events] << { type: :reasoning, data: chunk.thinking.text }
-              end
-            end
-          else
-            provider_client.complete(env[:messages], **kwargs).then do |response|
-              if response.content.present?
-                env[:events] << { type: :content, data: response.content }
-              end
-              response
-            end
-          end
-        end
-    end
-  end
-end
-
-test do
-  # not implemented
-end

data/lib/brute/pipeline.rb

@@ -1,97 +0,0 @@
-# frozen_string_literal: true
-
-require "bundler/setup"
-require "brute"
-
-module Brute
-  # Generic middleware machinery. Builds a chain of middleware around
-  # a terminal app, exposes `call(env)` to invoke it.
-  #
-  # Subclasses (Agent, Tool) override `call` to translate their public
-  # arguments into an env hash, then delegate to super.
-  #
-  #   class MyPipeline < Brute::Pipeline
-  #     def call(input)
-  #       env = { input: input, output: nil }
-  #       super(env)
-  #       env[:output]
-  #     end
-  #   end
-  #
-  class Pipeline
-    def initialize(&block)
-      @middlewares = []
-      @app = nil
-      instance_eval(&block) if block_given?
-    end
-
-    # Register a middleware class.
-    # The class must implement `initialize(app, *args, **kwargs)` and `call(env)`.
-    def use(klass, *args, **kwargs, &block)
-      tap { @middlewares << [klass, args, kwargs, block] }
-    end
-
-    # Set the terminal app (innermost handler).
-    # Accepts an instance (anything responding to #call(env)) or a class.
-    def run(app)
-      tap { @app = app }
-    end
-
-    # Invoke the chain. Subclasses typically override this to shape env
-    # and extract a return value.
-    def call(env)
-      build.call(env)
-    end
-
-    # Build the chain without calling it. Useful for inspection or caching.
-    def build
-      raise "Stack has no terminal app — call `run` first" unless @app
-
-      @middlewares.reverse.inject(@app) do |inner, (klass, args, kwargs, block)|
-        if block
-          klass.new(inner, *args, **kwargs, &block)
-        else
-          klass.new(inner, *args, **kwargs)
-        end
-      end
-    end
-
-    # Default null sink for env[:events] — swallows anything pushed to it.
-    class NullSink
-      def <<(_event); self; end
-    end
-  end
-end
-
-test do
-  it "builds and calls a chain" do
-    seen = []
-    inc = Class.new do
-      def initialize(app, label:); @app = app; @label = label; end
-      def call(env); env[:trace] << @label; @app.call(env); env[:trace] << "#{@label}-after"; end
-    end
-
-    pipeline = Brute::Pipeline.new do
-      use inc, label: "outer"
-      use inc, label: "inner"
-      run ->(env) { env[:trace] << "core" }
-    end
-
-    env = { trace: [] }
-    pipeline.call(env)
-    env[:trace].should == ["outer", "inner", "core", "inner-after", "outer-after"]
-  end
-
-  it "raises when run was never called" do
-    lambda { Brute::Pipeline.new.call({}) }.should.raise(RuntimeError)
-  end
-
-  it "accepts a callable as the terminal app" do
-    pipeline = Brute::Pipeline.new do
-      run ->(env) { env[:result] = 42 }
-    end
-    env = {}
-    pipeline.call(env)
-    env[:result].should == 42
-  end
-end

data/lib/brute/queue/file_mutation_queue.rb

@@ -1,102 +0,0 @@
-# frozen_string_literal: true
-
-module Brute
-  # @namespace
-  module Queue
-  # 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::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

data/lib/brute/session.rb

@@ -1,51 +0,0 @@
-# frozen_string_literal: true
-
-require "json"
-require "fileutils"
-
-module Brute
-  class Session < Array
-    attr_reader :path
-
-    def initialize(path: nil)
-      super()
-      @path = path
-      if @path
-        FileUtils.mkdir_p(File.dirname(@path))
-        if File.exist?(@path)
-          File.foreach(@path) do |line|
-            line.strip!
-            # Use push to bypass append persistence (avoids re-writing existing lines)
-            push(RubyLLM::Message.new(**JSON.parse(line, symbolize_names: true))) if line.present?
-          end
-        end
-      end
-    end
-
-    # @deprecated Use Session.new(path:) instead.
-    def self.from_jsonl(path)
-      new(path: path)
-    end
-
-    # Append a message and persist it to disk if a path is set.
-    def <<(msg)
-      super
-      if @path
-        File.open(@path, "a") { |f| f.puts(JSON.generate(msg.to_h)) }
-      end
-      self
-    end
-
-    def user(content)
-      self << RubyLLM::Message.new(role: :user, content: content)
-    end
-
-    def assistant(content)
-      self << RubyLLM::Message.new(role: :assistant, content: content)
-    end
-
-    def system(content)
-      self << RubyLLM::Message.new(role: :system, content: content)
-    end
-  end
-end

data/lib/brute/store/snapshot_store.rb

@@ -1,36 +0,0 @@
-# frozen_string_literal: true
-
-module Brute
-  # @namespace
-  module Store
-    # 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

data/lib/brute/store/todo_store.rb

@@ -1,30 +0,0 @@
-# frozen_string_literal: true
-
-module Brute
-  # @namespace
-  module Store
-  # In-memory todo list storage. The agent uses this to track multi-step tasks.
-  # The list is replaced wholesale on each todo_write call.
-  module TodoStore
-    @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

data/lib/brute/sub_agent.rb

@@ -1,106 +0,0 @@
-# frozen_string_literal: true
-
-require "bundler/setup"
-require "brute"
-require 'brute/pipeline'
-
-module Brute
-  # 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's
-  # LLMCall passes it to ruby_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::SubAgent.new(
-  #     name:        "research",
-  #     description: "Delegate a research task to a read-only sub-agent.",
-  #     provider:    Brute.provider,
-  #     model:       Brute.provider.default_model,
-  #     tools:       [Brute::Tools::FSRead, Brute::Tools::FSSearch],
-  #   ) do
-  #     use Brute::Middleware::SystemPrompt
-  #     use Brute::Middleware::MaxIterations, max_iterations: 10
-  #     use Brute::Middleware::ToolCall
-  #     run Brute::Middleware::LLMCall.new
-  #   end
-  #
-  #   main_agent = Brute::Agent.new(
-  #     provider: ...,
-  #     tools: [Brute::Tools::FSRead, researcher],   # SubAgent IS a tool
-  #   ) { ... }
-  #
-  class SubAgent < Agent
-    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, **agent_opts, &block)
-      @sub_agent_name = name.to_s
-      @description    = description
-      @params         = params
-      super(**agent_opts, &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)
-      call(session)
-      extract_result(session)
-    end
-
-    # Adapter so the parent agent's LLMCall (and ruby_llm) sees this as
-    # a regular tool. ToolCall 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 ToolCall 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::Session.new.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
-
-test do
-  it "exposes a name matching the sub-agent identifier" do
-    sa = Brute::SubAgent.new(name: "research", description: "test", provider: :stub) do
-      run ->(env) { env[:messages].assistant("done") }
-    end
-    sa.name.should == "research"
-  end
-
-  it "execute returns the last assistant message" do
-    sa = Brute::SubAgent.new(name: "research", description: "test", provider: :stub) do
-      run ->(env) { env[:messages].assistant("result text") }
-    end
-    sa.execute(task: "do something").should == "result text"
-  end
-end