brute 1.0.1 → 2.0.0

data/lib/brute/tools/fs_write.rb

@@ -2,19 +2,21 @@
 
 require "bundler/setup"
 require "brute"
+require "brute/tools"
 require 'fileutils'
 
 module Brute
   module Tools
-    class FSWrite < LLM::Tool
-      name 'write'
+    class FSWrite < RubyLLM::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.'
 
-      param :file_path, String, 'Path to the file to write', required: true
-      param :content, String, 'The full content to write to the file', required: true
+      param :file_path, type: 'string', desc: 'Path to the file to write', required: true
+      param :content, type: 'string', desc: 'The full content to write to the file', required: true
 
-      def call(file_path:, content:)
+      def name; "write"; end
+
+      def execute(file_path:, content:)
         path = File.expand_path(file_path)
         Brute::Queue::FileMutationQueue.serialize(path) do
           old_content = File.exist?(path) ? File.read(path) : ''

data/lib/brute/tools/net_fetch.rb

@@ -1,25 +1,25 @@
 # frozen_string_literal: true
 
-if __FILE__ == $0
-  require "bundler/setup"
-  require "brute"
-end
+require "bundler/setup"
+require "brute"
+require "brute/tools"
 
 require "net/http"
 require "uri"
 
 module Brute
   module Tools
-    class NetFetch < LLM::Tool
-      name "fetch"
+    class NetFetch < RubyLLM::Tool
       description "Fetch content from a URL. Returns the response body as text."
 
-      param :url, String, "The URL to fetch", required: true
+      param :url, type: 'string', desc: "The URL to fetch", required: true
+
+      def name; "fetch"; end
 
       MAX_BODY = 50_000
       TIMEOUT = 30
 
-      def call(url:)
+      def execute(url:)
         uri = URI.parse(url)
         raise "Invalid URL scheme: #{uri.scheme}" unless %w[http https].include?(uri.scheme)
 

data/lib/brute/tools/question.rb

@@ -1,14 +1,12 @@
 # frozen_string_literal: true
 
-if __FILE__ == $0
-  require "bundler/setup"
-  require "brute"
-end
+require "bundler/setup"
+require "brute"
+require "brute/tools"
 
 module Brute
   module Tools
-    class Question < LLM::Tool
-      name "question"
+    class Question < RubyLLM::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 " \
@@ -16,25 +14,39 @@ module Brute
                   "to allow selecting more than one. If you recommend a specific option, make it " \
                   "the first option and add \"(Recommended)\" at the end of the label."
 
-      params do |s|
-        s.object(
-          questions: s.array(
-            s.object(
-              question: s.string.required,
-              header: s.string.required,
-              options: s.array(
-                s.object(
-                  label: s.string.required,
-                  description: s.string.required,
-                )
-              ).required,
-              multiple: s.boolean,
-            )
-          ).required
-        )
-      end
+      params({
+        type: 'object',
+        properties: {
+          questions: {
+            type: 'array',
+            items: {
+              type: 'object',
+              properties: {
+                question: { type: 'string' },
+                header: { type: 'string' },
+                options: {
+                  type: 'array',
+                  items: {
+                    type: 'object',
+                    properties: {
+                      label: { type: 'string' },
+                      description: { type: 'string' },
+                    },
+                    required: %w[label description],
+                  },
+                },
+                multiple: { type: 'boolean' },
+              },
+              required: %w[question header options],
+            },
+          },
+        },
+        required: %w[questions],
+      })
+
+      def name; "question"; end
 
-      def call(questions:)
+      def execute(questions:)
         handler = Thread.current[:on_question]
         unless handler
           return { error: true, message: "Cannot ask questions in non-interactive mode" }

data/lib/brute/tools/shell.rb

@@ -1,43 +1,101 @@
 # frozen_string_literal: true
 
-if __FILE__ == $0
-  require "bundler/setup"
-  require "brute"
-end
+require "bundler/setup"
+require "brute"
+require "brute/tools"
+require "brute/truncation"
 
 require "open3"
 
 module Brute
   module Tools
-    class Shell < LLM::Tool
-      name "shell"
+    # Existing features (ref: opencode bash tool):
+    #
+    # 1. Tail-mode truncation — when output exceeds limits, keep the LAST
+    #    N lines / bytes instead of the first. Command output typically has
+    #    the important info (errors, summaries) at the end.
+    # 2. Save full output to disk — when truncating, write the complete
+    #    output to a temp file and include the path in the truncated result
+    #    so the LLM can use Read with offset/limit to inspect it.
+    # 3. Align limits with universal truncation (2000 lines / 50 KB).
+    # 4. Configurable per-call timeout — accept a timeout parameter from
+    #    the LLM (defaults to 5 minutes).
+    # 5. Return a plain string instead of a Hash.
+    #
+    class Shell < RubyLLM::Tool
       description "Execute a shell command and return stdout, stderr, and exit code. " \
                   "Use for git operations, running tests, installing packages, etc."
 
-      param :command, String, "The shell command to execute", required: true
-      param :cwd, String, "Working directory for the command (defaults to project root)"
+      param :command, type: 'string', desc: "The shell command to execute", required: true
+      param :cwd, type: 'string', desc: "Working directory for the command (defaults to project root)", required: false
+      param :timeout, type: 'integer', desc: "Timeout in seconds (defaults to 300)", required: false
+
+      def name; "shell"; end
 
-      TIMEOUT = 300 # 5 minutes
-      MAX_OUTPUT = 50_000
+      DEFAULT_TIMEOUT = 300 # 5 minutes
 
-      def call(command:, cwd: nil)
+      def execute(command:, cwd: nil, timeout: nil)
         dir = cwd ? File.expand_path(cwd) : Dir.pwd
         raise "Directory not found: #{dir}" unless File.directory?(dir)
 
+        timeout_secs = timeout || DEFAULT_TIMEOUT
         stdout, stderr, status = nil
-        Timeout.timeout(TIMEOUT) do
+        Timeout.timeout(timeout_secs) do
           stdout, stderr, status = Open3.capture3("bash", "-c", command, chdir: dir)
         end
 
         out = stdout.to_s
         err = stderr.to_s
-        out = out[0...MAX_OUTPUT] + "\n...(truncated)" if out.size > MAX_OUTPUT
-        err = err[0...MAX_OUTPUT] + "\n...(truncated)" if err.size > MAX_OUTPUT
 
-        {stdout: out, stderr: err, exit_code: status.exitstatus}
+        # Combine output, preferring tail-mode truncation so errors/summaries at end are preserved
+        combined = out
+        combined += "\nSTDERR:\n#{err}" unless err.empty?
+        combined += "\n[exit code: #{status.exitstatus}]" if status.exitstatus != 0
+
+        Brute::Truncation.truncate(combined, direction: :tail)
       rescue Timeout::Error
-        {error: "Command timed out after #{TIMEOUT}s", command: command}
+        "Command timed out after #{timeout_secs}s: #{command}"
       end
     end
   end
 end
+
+test do
+  it "runs a command without error" do
+    result = Brute::Tools::Shell.new.call(command: "echo hello")
+    result.strip.should =~ /hello/
+  end
+
+  it "returns exit code" do
+    result = Brute::Tools::Shell.new.call(command: "false")
+    result.should =~ /exit code: 1/
+  end
+
+  it "returns a String, not a Hash" do
+    Brute::Tools::Shell.new.call(command: "echo hello").should.be.kind_of(String)
+  end
+
+  it "preserves the end of output when truncating (tail mode)" do
+    result = Brute::Tools::Shell.new.call(command: "seq 1 100000")
+    result.should =~ /100000/
+  end
+
+  # --- Save full output to disk ---
+
+  it "saves full output to disk when truncated" do
+    result = Brute::Tools::Shell.new.call(command: "seq 1 100000")
+    result.should =~ /Full output saved to:/
+  end
+
+  # --- Configurable timeout ---
+
+  it "accepts a timeout parameter" do
+    result = Brute::Tools::Shell.new.call(command: "sleep 0.1 && echo done", timeout: 10)
+    result.should =~ /done/
+  end
+
+  it "times out with a short timeout" do
+    result = Brute::Tools::Shell.new.call(command: "sleep 10", timeout: 1)
+    result.should =~ /timed out/i
+  end
+end

data/lib/brute/tools/todo_read.rb

@@ -1,18 +1,18 @@
 # frozen_string_literal: true
 
-if __FILE__ == $0
-  require "bundler/setup"
-  require "brute"
-end
+require "bundler/setup"
+require "brute"
+require "brute/tools"
 
 module Brute
   module Tools
-    class TodoRead < LLM::Tool
-      name "todo_read"
+    class TodoRead < RubyLLM::Tool
       description "Read the current todo list to check task status and progress."
-      param :_placeholder, String, "Unused, pass any value"
+      param :_placeholder, type: 'string', desc: "Unused, pass any value", required: false
+
+      def name; "todo_read"; end
 
-      def call(_placeholder: nil)
+      def execute(_placeholder: nil)
         {todos: Brute::Store::TodoStore.all}
       end
     end

data/lib/brute/tools/todo_write.rb

@@ -1,30 +1,37 @@
 # frozen_string_literal: true
 
-if __FILE__ == $0
-  require "bundler/setup"
-  require "brute"
-end
+require "bundler/setup"
+require "brute"
+require "brute/tools"
 
 module Brute
   module Tools
-    class TodoWrite < LLM::Tool
-      name "todo_write"
+    class TodoWrite < RubyLLM::Tool
       description "Create or update the todo list. Send the complete list each time — " \
                   "this replaces the existing list entirely."
 
-      params do |s|
-        s.object(
-          todos: s.array(
-            s.object(
-              id: s.string.required,
-              content: s.string.required,
-              status: s.string.enum("pending", "in_progress", "completed", "cancelled").required
-            )
-          ).required
-        )
-      end
+      params({
+        type: 'object',
+        properties: {
+          todos: {
+            type: 'array',
+            items: {
+              type: 'object',
+              properties: {
+                id: { type: 'string' },
+                content: { type: 'string' },
+                status: { type: 'string', enum: %w[pending in_progress completed cancelled] },
+              },
+              required: %w[id content status],
+            },
+          },
+        },
+        required: %w[todos],
+      })
+
+      def name; "todo_write"; end
 
-      def call(todos:)
+      def execute(todos:)
         items = todos.map do |t|
           t = t.transform_keys(&:to_sym) if t.is_a?(Hash)
           {id: t[:id], content: t[:content], status: t[:status]}

data/lib/brute/tools.rb

@@ -1,15 +1,11 @@
-require_relative 'tools/fs_read'
-require_relative 'tools/fs_write'
-require_relative 'tools/fs_patch'
-require_relative 'tools/fs_remove'
-require_relative 'tools/fs_search'
-require_relative 'tools/fs_undo'
-require_relative 'tools/shell'
-require_relative 'tools/net_fetch'
-require_relative 'tools/todo_write'
-require_relative 'tools/todo_read'
-require_relative 'tools/delegate'
-require_relative 'tools/question'
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+
+Dir.glob("#{__dir__}/tools/**/*.rb").sort.each do |path|
+  require path
+end
 
 module Brute
   module Tools

data/lib/brute/truncation.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+require "fileutils"
+require "securerandom"
+
+module Brute
+  # Universal tool output truncation.
+  #
+  # Every tool result passes through Truncation.truncate() before entering
+  # the LLM context. This is the primary guard against context window
+  # explosion — even if a tool has no internal limits, this module caps
+  # the output to a safe size.
+  #
+  # Existing features (ref: opencode truncate.ts):
+  #
+  # 1. Line + byte dual cap — truncate when output exceeds MAX_LINES
+  #    (2000) or MAX_BYTES (50 KB), whichever is hit first.
+  # 2. Head mode (default) — keep the first N lines / bytes. Used for
+  #    most tool output where the beginning is most relevant.
+  # 3. Tail mode — keep the last N lines / bytes. Used for shell output
+  #    where errors and summaries appear at the end.
+  # 4. Overflow to disk — when truncating, write the full text to a file
+  #    under TRUNCATION_DIR (e.g. ~/.local/share/brute/tool-output/).
+  #    Return a preview + hint pointing to the saved file.
+  # 5. Hint message — when truncated, append a contextual hint:
+  #    "Full output saved to: <path>. Use Read with offset/limit to
+  #    view specific sections."
+  # 6. Configurable limits — allow overriding MAX_LINES / MAX_BYTES
+  #    via per-call options.
+  # 7. Retention cleanup — purge saved output files older than a
+  #    configurable retention period from a truncation directory.
+  # 8. Per-line truncation — truncate individual lines longer than
+  #    MAX_LINE_LENGTH (2000 chars) with a suffix.
+  #
+  module Truncation
+    MAX_LINES = 2000
+    MAX_BYTES = 50 * 1024 # 50 KB
+    MAX_LINE_LENGTH = 2000
+    TRUNCATION_MARKER = "[Output truncated:"
+
+    TRUNCATION_DIR = File.join(Dir.home, ".local", "share", "brute", "tool-output")
+
+    # Truncate text to fit within line and byte limits.
+    #
+    # Returns the text unchanged if it fits. Otherwise returns a
+    # truncated preview with a hint message.
+    #
+    # @param text [String] the tool output to truncate
+    # @param max_lines [Integer] maximum number of lines to keep
+    # @param max_bytes [Integer] maximum byte size to keep
+    # @param direction [:head, :tail] which end to keep
+    # @param truncation_dir [String, nil] directory to save full output when truncating
+    # @return [String] the (possibly truncated) text
+    #
+    def self.truncate(text, max_lines: MAX_LINES, max_bytes: MAX_BYTES, direction: :head, truncation_dir: nil)
+      return text if text.nil? || text.empty?
+
+      # Per-line truncation first — cap individual lines
+      lines = text.lines.map { |line| truncate_line(line) }
+      text = lines.join
+
+      return text if lines.size <= max_lines && text.bytesize <= max_bytes
+
+      # Determine how many lines we can keep within both caps
+      kept = direction == :tail ? lines.last(max_lines) : lines.first(max_lines)
+
+      # Enforce byte cap
+      result_lines = []
+      bytes = 0
+      kept.each do |line|
+        break if bytes + line.bytesize > max_bytes
+        result_lines << line
+        bytes += line.bytesize
+      end
+
+      result = result_lines.join
+      total = lines.size
+      shown = result_lines.size
+
+      # Overflow to disk — save the full output so it can be inspected later
+      saved_path = save_to_disk(text, truncation_dir)
+
+      hint = "\n#{TRUNCATION_MARKER} showing #{shown} of #{total} lines]"
+      if saved_path
+        hint += "\nFull output saved to: #{saved_path}. Use Read with offset/limit to view specific sections."
+      end
+      result + hint
+    end
+
+    # Check whether text already contains a truncation marker.
+    def self.already_truncated?(text)
+      text.include?(TRUNCATION_MARKER)
+    end
+
+    # Truncate a single line if it exceeds MAX_LINE_LENGTH.
+    def self.truncate_line(line, max: MAX_LINE_LENGTH)
+      return line if line.length <= max
+      line[0, max] + "... (line truncated to #{max} chars)\n"
+    end
+
+    # Purge files older than retention_days from the given directory.
+    def self.cleanup!(dir, retention_days: 7)
+      return unless File.directory?(dir)
+      cutoff = Time.now - (retention_days * 86400)
+      Dir.glob(File.join(dir, "*")).each do |path|
+        File.delete(path) if File.file?(path) && File.mtime(path) < cutoff
+      end
+    end
+
+    # Save text to a file in truncation_dir. Returns the file path, or nil.
+    def self.save_to_disk(text, truncation_dir)
+      dir = truncation_dir || TRUNCATION_DIR
+      return nil unless dir
+      FileUtils.mkdir_p(dir)
+      path = File.join(dir, "tool_#{SecureRandom.hex(8)}.txt")
+      File.write(path, text)
+      path
+    rescue => _e
+      nil
+    end
+    private_class_method :save_to_disk
+  end
+end
+
+test do
+  require "tmpdir"
+  require "fileutils"
+
+  it "returns short text unchanged" do
+    Brute::Truncation.truncate("hello world").should == "hello world"
+  end
+
+  it "truncates text exceeding 2000 lines" do
+    big = "line\n" * 3000
+    result = Brute::Truncation.truncate(big)
+    result.lines.size.should.be < 2100
+  end
+
+  it "includes a hint when truncated" do
+    big = "line\n" * 3000
+    Brute::Truncation.truncate(big).should =~ /truncated/i
+  end
+
+  # --- Per-line truncation ---
+
+  it "truncates individual lines longer than MAX_LINE_LENGTH" do
+    long_line = "x" * 3000 + "\n"
+    result = Brute::Truncation.truncate(long_line)
+    result.lines.first.size.should.be < 2100
+  end
+
+  it "adds a suffix to truncated lines" do
+    long_line = "x" * 3000 + "\n"
+    result = Brute::Truncation.truncate(long_line)
+    result.should =~ /truncated/i
+  end
+
+  # --- Overflow to disk ---
+
+  it "saves full output to disk when truncating" do
+    Dir.mktmpdir do |dir|
+      big = "line\n" * 3000
+      result = Brute::Truncation.truncate(big, truncation_dir: dir)
+      files = Dir.glob(File.join(dir, "*"))
+      files.size.should == 1
+      File.read(files.first).should == big
+    end
+  end
+
+  it "includes saved file path in hint" do
+    Dir.mktmpdir do |dir|
+      big = "line\n" * 3000
+      result = Brute::Truncation.truncate(big, truncation_dir: dir)
+      result.should =~ /Full output saved to:/
+    end
+  end
+
+  it "does not save to disk when not truncated" do
+    Dir.mktmpdir do |dir|
+      result = Brute::Truncation.truncate("short\n", truncation_dir: dir)
+      Dir.glob(File.join(dir, "*")).size.should == 0
+    end
+  end
+
+  # --- Configurable limits ---
+
+  it "accepts custom max_lines" do
+    text = "line\n" * 50
+    result = Brute::Truncation.truncate(text, max_lines: 10)
+    result.lines.count { |l| l.strip == "line" }.should.be <= 10
+  end
+
+  it "accepts custom max_bytes" do
+    text = "line\n" * 50
+    result = Brute::Truncation.truncate(text, max_bytes: 20)
+    result.should =~ /truncated/i
+  end
+
+  # --- Retention cleanup ---
+
+  it "purges files older than retention period" do
+    Dir.mktmpdir do |dir|
+      old_file = File.join(dir, "old_output.txt")
+      File.write(old_file, "old content")
+      # Backdate the file to 8 days ago
+      old_time = Time.now - (8 * 86400)
+      File.utime(old_time, old_time, old_file)
+
+      new_file = File.join(dir, "new_output.txt")
+      File.write(new_file, "new content")
+
+      Brute::Truncation.cleanup!(dir, retention_days: 7)
+      File.exist?(old_file).should == false
+      File.exist?(new_file).should == true
+    end
+  end
+end

data/lib/brute/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Brute
-  VERSION = "1.0.1"
+  VERSION = "2.0.0"
 end