brute 0.1.0

data/lib/brute/session.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require "securerandom"
+
+module Brute
+  # Manages session persistence. Each session is a conversation that can be
+  # saved to disk and resumed later.
+  #
+  # Sessions are stored as JSON files in a configurable directory
+  # (defaults to ~/.brute/sessions/).
+  class Session
+    attr_reader :id, :title, :path
+
+    def initialize(id: nil, dir: nil)
+      @id = id || SecureRandom.uuid
+      @dir = dir || File.join(Dir.home, ".brute", "sessions")
+      @path = File.join(@dir, "#{@id}.json")
+      @title = nil
+      @metadata = {}
+      FileUtils.mkdir_p(@dir)
+    end
+
+    # Save a context to this session file.
+    def save(context, title: nil, metadata: {})
+      @title = title if title
+      @metadata.merge!(metadata)
+
+      data = {
+        id: @id,
+        title: @title,
+        saved_at: Time.now.iso8601,
+        metadata: @metadata,
+      }
+
+      # Use llm.rb's built-in serialization
+      context.save(path: @path)
+
+      # Write metadata sidecar
+      meta_path = @path.sub(/\.json$/, ".meta.json")
+      File.write(meta_path, JSON.pretty_generate(data))
+    end
+
+    # Restore a context from this session file.
+    # Returns true if restored successfully, false if no session file found.
+    def restore(context)
+      return false unless File.exist?(@path)
+
+      context.restore(path: @path)
+
+      # Load metadata sidecar if present
+      meta_path = @path.sub(/\.json$/, ".meta.json")
+      if File.exist?(meta_path)
+        data = JSON.parse(File.read(meta_path), symbolize_names: true)
+        @title = data[:title]
+        @metadata = data[:metadata] || {}
+      end
+
+      true
+    end
+
+    # List all saved sessions, newest first.
+    def self.list(dir: nil)
+      dir ||= File.join(Dir.home, ".brute", "sessions")
+      return [] unless File.directory?(dir)
+
+      Dir.glob(File.join(dir, "*.meta.json")).map { |meta_path|
+        data = JSON.parse(File.read(meta_path), symbolize_names: true)
+        {
+          id: data[:id],
+          title: data[:title],
+          saved_at: data[:saved_at],
+          path: meta_path.sub(/\.meta\.json$/, ".json"),
+        }
+      }.sort_by { |s| s[:saved_at] || "" }.reverse
+    end
+
+    # Delete a session from disk.
+    def delete
+      File.delete(@path) if File.exist?(@path)
+      meta_path = @path.sub(/\.json$/, ".meta.json")
+      File.delete(meta_path) if File.exist?(meta_path)
+    end
+  end
+end

data/lib/brute/snapshot_store.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Brute
+  # Copy-on-write snapshot storage for file undo support.
+  # Saves the previous content of a file before mutation so it can be restored.
+  # Each file maintains a stack of snapshots, supporting multiple undo levels.
+  module SnapshotStore
+    @store = {}
+    @mutex = Mutex.new
+
+    class << self
+      # Save the current state of a file before mutating it.
+      # If the file doesn't exist, records :did_not_exist so undo can delete it.
+      def save(path)
+        path = File.expand_path(path)
+        @mutex.synchronize do
+          @store[path] ||= []
+          if File.exist?(path)
+            @store[path].push(File.read(path))
+          else
+            @store[path].push(:did_not_exist)
+          end
+        end
+      end
+
+      # Pop the most recent snapshot for a file.
+      # Returns the content string, :did_not_exist, or nil if no history.
+      def pop(path)
+        path = File.expand_path(path)
+        @mutex.synchronize do
+          @store[path]&.pop
+        end
+      end
+
+      # Check how many undo levels are available for a file.
+      def depth(path)
+        path = File.expand_path(path)
+        @mutex.synchronize do
+          @store[path]&.size || 0
+        end
+      end
+
+      # Clear all snapshots (useful for testing or session reset).
+      def clear!
+        @mutex.synchronize { @store.clear }
+      end
+    end
+  end
+end

data/lib/brute/system_prompt.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Brute
+  # Builds the system prompt dynamically based on available tools, environment,
+  # custom rules, and working directory context.
+  #
+  # Modeled after forgecode's SystemPrompt which composes a static agent
+  # personality block with dynamic environment/tool information.
+  class SystemPrompt
+    def initialize(cwd: Dir.pwd, tools: [], custom_rules: nil)
+      @cwd = cwd
+      @tools = tools
+      @custom_rules = custom_rules
+    end
+
+    def build
+      sections = []
+      sections << identity_section
+      sections << tools_section
+      sections << guidelines_section
+      sections << environment_section
+      sections << custom_rules_section if @custom_rules
+      sections.compact.join("\n\n")
+    end
+
+    private
+
+    def identity_section
+      <<~SECTION
+        # Identity
+
+        You are Brute, an expert software engineering agent. You help users with coding tasks
+        by reading, writing, and editing files, running shell commands, and searching codebases.
+        You are methodical, precise, and always verify your work.
+      SECTION
+    end
+
+    def tools_section
+      tool_list = LLM::Function.registry.filter_map { |fn|
+        "- **#{fn.name}**: #{fn.description.to_s.split(". ").first}."
+      }.join("\n")
+
+      <<~SECTION
+        # Available Tools
+
+        #{tool_list}
+      SECTION
+    end
+
+    def guidelines_section
+      <<~SECTION
+        # Guidelines
+
+        - **Always read before editing**: Use `read` to examine a file before using `patch` or `write` to modify it.
+        - **Verify your changes**: After editing, re-read the file or run tests to confirm correctness.
+        - **Use todo_write for multi-step tasks**: Break complex work into steps and track progress.
+        - **Use fs_search to find code**: Don't guess file locations — search first.
+        - **Use shell for git, tests, builds**: Run `git diff`, `git status`, test suites, etc.
+        - **Be precise with patch**: The `old_string` must match the file content exactly, including whitespace.
+        - **Prefer patch over write**: For existing files, use `patch` to change specific sections rather than rewriting the entire file.
+        - **Use undo to recover**: If a write or patch goes wrong, use `undo` to restore the previous version.
+        - **Delegate research**: Use `delegate` for complex analysis that needs focused investigation.
+      SECTION
+    end
+
+    def environment_section
+      files = Dir.entries(@cwd).reject { |f| f.start_with?(".") }.sort.first(50)
+
+      <<~SECTION
+        # Environment
+
+        - **Working directory**: #{@cwd}
+        - **OS**: #{RUBY_PLATFORM}
+        - **Ruby**: #{RUBY_VERSION}
+        - **Date**: #{Time.now.strftime("%Y-%m-%d")}
+        - **Files in cwd**: #{files.join(", ")}
+      SECTION
+    end
+
+    def custom_rules_section
+      <<~SECTION
+        # Project-Specific Rules
+
+        #{@custom_rules}
+      SECTION
+    end
+  end
+end

data/lib/brute/todo_store.rb

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

data/lib/brute/tools/delegate.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Brute
+  module Tools
+    class Delegate < LLM::Tool
+      name "delegate"
+      description "Delegate a research or analysis task to a specialist sub-agent. " \
+                  "The sub-agent can read files and search but cannot write or execute commands. " \
+                  "Use for code analysis, understanding patterns, or gathering information."
+
+      param :task, String, "A clear, detailed description of the research task", required: true
+
+      def call(task:)
+        provider = Brute.provider
+        sub = LLM::Context.new(provider, tools: [FSRead, FSSearch])
+
+        prompt = sub.prompt do
+          system "You are a research agent. Analyze code, explain patterns, and answer questions. " \
+                 "You have read-only access to the filesystem. Be thorough and precise."
+          user task
+        end
+
+        # Run a manual tool loop (max 10 rounds)
+        res = sub.talk(prompt)
+        rounds = 0
+        while sub.functions.any? && rounds < 10
+          res = sub.talk(sub.functions.map(&:call))
+          rounds += 1
+        end
+
+        {result: res.content}
+      end
+    end
+  end
+end

data/lib/brute/tools/fs_patch.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Brute
+  module Tools
+    class FSPatch < LLM::Tool
+      name "patch"
+      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."
+
+      param :file_path, String, "Path to the file to patch", required: true
+      param :old_string, String, "The exact text to find and replace", required: true
+      param :new_string, String, "The replacement text", required: true
+      param :replace_all, Boolean, "Replace all occurrences (default: false)"
+
+      def call(file_path:, old_string:, new_string:, replace_all: false)
+        path = File.expand_path(file_path)
+        Brute::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::SnapshotStore.save(path)
+
+          updated = if replace_all
+            original.gsub(old_string, new_string)
+          else
+            original.sub(old_string, new_string)
+          end
+
+          File.write(path, updated)
+          {success: true, file_path: path, replacements: replace_all ? original.scan(old_string).size : 1}
+        end
+      end
+    end
+  end
+end

data/lib/brute/tools/fs_read.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Brute
+  module Tools
+    class FSRead < LLM::Tool
+      name "read"
+      description "Read the contents of a file. Returns file content with line numbers. " \
+                  "Use start_line/end_line for partial reads of large files."
+
+      param :file_path, String, "Absolute or relative path to the file to read", required: true
+      param :start_line, Integer, "Starting line number (1-indexed). Omit to read from beginning"
+      param :end_line, Integer, "Ending line number (inclusive). Omit to read to end"
+
+      def call(file_path:, start_line: nil, end_line: nil)
+        path = File.expand_path(file_path)
+        raise "File not found: #{path}" unless File.exist?(path)
+        raise "Not a file: #{path}" unless File.file?(path)
+
+        lines = File.readlines(path)
+        first = start_line ? [start_line - 1, 0].max : 0
+        last = end_line ? [end_line - 1, lines.size - 1].min : lines.size - 1
+
+        selected = lines[first..last] || []
+        numbered = selected.each_with_index.map do |line, i|
+          "#{first + i + 1}\t#{line}"
+        end
+
+        {
+          file_path: path,
+          total_lines: lines.size,
+          showing: "#{first + 1}-#{last + 1}",
+          content: numbered.join,
+        }
+      end
+    end
+  end
+end

data/lib/brute/tools/fs_remove.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Brute
+  module Tools
+    class FSRemove < LLM::Tool
+      name "remove"
+      description "Remove a file or empty directory."
+
+      param :path, String, "Path to the file or directory to remove", required: true
+
+      def call(path:)
+        target = File.expand_path(path)
+        Brute::FileMutationQueue.serialize(target) do
+          raise "Path not found: #{target}" unless File.exist?(target)
+
+          Brute::SnapshotStore.save(target) if File.file?(target)
+
+          if File.directory?(target)
+            Dir.rmdir(target)
+          else
+            File.delete(target)
+          end
+
+          {success: true, path: target}
+        end
+      end
+    end
+  end
+end

data/lib/brute/tools/fs_search.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Brute
+  module Tools
+    class FSSearch < LLM::Tool
+      name "fs_search"
+      description "Search file contents using ripgrep (regex), or find files by glob pattern. " \
+                  "Returns matching lines with file paths and line numbers."
+
+      param :pattern, String, "Regex pattern to search for in file contents", required: true
+      param :path, String, "Directory to search in (defaults to current working directory)"
+      param :glob, String, "File glob filter, e.g. '*.rb', '*.{js,ts}'"
+      param :ignore_case, Boolean, "Case-insensitive search (default: false)"
+
+      MAX_OUTPUT = 40_000
+
+      def call(pattern:, path: nil, glob: nil, ignore_case: false)
+        dir = File.expand_path(path || Dir.pwd)
+        raise "Directory not found: #{dir}" unless File.directory?(dir)
+
+        cmd = ["rg", "--line-number", "--max-count=100", "--max-columns=200"]
+        cmd << "--ignore-case" if ignore_case
+        cmd += ["--glob", glob] if glob
+        cmd << pattern
+        cmd << dir
+
+        stdout, stderr, status = Open3.capture3(*cmd)
+
+        output = stdout.empty? ? stderr : stdout
+        output = output[0...MAX_OUTPUT] + "\n...(truncated)" if output.size > MAX_OUTPUT
+
+        {results: output, exit_code: status.exitstatus, truncated: output.size > MAX_OUTPUT}
+      end
+    end
+  end
+end

data/lib/brute/tools/fs_undo.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Brute
+  module Tools
+    class FSUndo < LLM::Tool
+      name "undo"
+      description "Undo the last write or patch operation on a file, restoring it to " \
+                  "its previous state."
+
+      param :path, String, "Path to the file to undo", required: true
+
+      def call(path:)
+        target = File.expand_path(path)
+        Brute::FileMutationQueue.serialize(target) do
+          snapshot = Brute::SnapshotStore.pop(target)
+          raise "No undo history available for: #{target}" unless snapshot
+
+          if snapshot == :did_not_exist
+            File.delete(target) if File.exist?(target)
+            {success: true, action: "deleted (file did not exist before)"}
+          else
+            File.write(target, snapshot)
+            {success: true, action: "restored", bytes: snapshot.bytesize}
+          end
+        end
+      end
+    end
+  end
+end

data/lib/brute/tools/fs_write.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Brute
+  module Tools
+    class FSWrite < LLM::Tool
+      name "write"
+      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
+
+      def call(file_path:, content:)
+        path = File.expand_path(file_path)
+        Brute::FileMutationQueue.serialize(path) do
+          Brute::SnapshotStore.save(path)
+          FileUtils.mkdir_p(File.dirname(path))
+          File.write(path, content)
+          {success: true, file_path: path, bytes: content.bytesize}
+        end
+      end
+    end
+  end
+end

data/lib/brute/tools/net_fetch.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+
+module Brute
+  module Tools
+    class NetFetch < LLM::Tool
+      name "fetch"
+      description "Fetch content from a URL. Returns the response body as text."
+
+      param :url, String, "The URL to fetch", required: true
+
+      MAX_BODY = 50_000
+      TIMEOUT = 30
+
+      def call(url:)
+        uri = URI.parse(url)
+        raise "Invalid URL scheme: #{uri.scheme}" unless %w[http https].include?(uri.scheme)
+
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = TIMEOUT
+        http.read_timeout = TIMEOUT
+
+        request = Net::HTTP::Get.new(uri)
+        request["User-Agent"] = "forge-rb/1.0"
+
+        response = http.request(request)
+        body = response.body.to_s
+        body = body[0...MAX_BODY] + "\n...(truncated)" if body.size > MAX_BODY
+
+        {status: response.code.to_i, body: body, content_type: response["content-type"]}
+      end
+    end
+  end
+end

data/lib/brute/tools/shell.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Brute
+  module Tools
+    class Shell < LLM::Tool
+      name "shell"
+      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)"
+
+      TIMEOUT = 300 # 5 minutes
+      MAX_OUTPUT = 50_000
+
+      def call(command:, cwd: nil)
+        dir = cwd ? File.expand_path(cwd) : Dir.pwd
+        raise "Directory not found: #{dir}" unless File.directory?(dir)
+
+        stdout, stderr, status = nil
+        Timeout.timeout(TIMEOUT) 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}
+      rescue Timeout::Error
+        {error: "Command timed out after #{TIMEOUT}s", command: command}
+      end
+    end
+  end
+end

data/lib/brute/tools/todo_read.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Brute
+  module Tools
+    class TodoRead < LLM::Tool
+      name "todo_read"
+      description "Read the current todo list to check task status and progress."
+      param :_placeholder, String, "Unused, pass any value"
+
+      def call(_placeholder: nil)
+        {todos: Brute::TodoStore.all}
+      end
+    end
+  end
+end

data/lib/brute/tools/todo_write.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Brute
+  module Tools
+    class TodoWrite < LLM::Tool
+      name "todo_write"
+      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
+
+      def call(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]}
+        end
+        Brute::TodoStore.replace(items)
+        {success: true, count: items.size}
+      end
+    end
+  end
+end