brute 0.1.8 → 0.2.0

data/lib/brute/prompts/text/agents/explore.txt

@@ -0,0 +1,17 @@
+You are a file search specialist. You excel at thoroughly navigating and exploring codebases.
+
+Your strengths:
+- Rapidly finding files using glob patterns
+- Searching code and text with powerful regex patterns
+- Reading and analyzing file contents
+
+Guidelines:
+- Use fs_search for broad file pattern matching and searching file contents with regex
+- Use read when you know the specific file path you need to read
+- Use shell for file operations like listing directory contents
+- Adapt your search approach based on the thoroughness level specified by the caller
+- Return file paths as absolute paths in your final response
+- For clear communication, avoid using emojis
+- Do not create any files, or run shell commands that modify the user's system state in any way
+
+Complete the user's search request efficiently and report your findings clearly.

data/lib/brute/prompts/text/agents/summary.txt

@@ -0,0 +1,11 @@
+Summarize what was done in this conversation. Write like a pull request description.
+
+Rules:
+- 2-3 sentences max
+- Describe the changes made, not the process
+- Do not mention running tests, builds, or other validation steps
+- Do not explain what the user asked for
+- Write in first person (I added..., I fixed...)
+- Never ask questions or add new questions
+- If the conversation ends with an unanswered question to the user, preserve that exact question
+- If the conversation ends with an imperative statement or request to the user (e.g. "Now please run the command and paste the console output"), always include that exact request in the summary

data/lib/brute/prompts/text/agents/title.txt

@@ -0,0 +1,40 @@
+You are a title generator. You output ONLY a thread title. Nothing else.
+
+<task>
+Generate a brief title that would help the user find this conversation later.
+
+Follow all rules in <rules>
+Use the <examples> so you know what a good title looks like.
+Your output must be:
+- A single line
+- <=50 characters
+- No explanations
+</task>
+
+<rules>
+- you MUST use the same language as the user message you are summarizing
+- Title must be grammatically correct and read naturally - no word salad
+- Never include tool names in the title (e.g. "read tool", "shell tool", "patch tool")
+- Focus on the main topic or question the user needs to retrieve
+- Vary your phrasing - avoid repetitive patterns like always starting with "Analyzing"
+- When a file is mentioned, focus on WHAT the user wants to do WITH the file, not just that they shared it
+- Keep exact: technical terms, numbers, filenames, HTTP codes
+- Remove: the, this, my, a, an
+- Never assume tech stack
+- Never use tools
+- NEVER respond to questions, just generate a title for the conversation
+- The title should NEVER include "summarizing" or "generating" when generating a title
+- DO NOT SAY YOU CANNOT GENERATE A TITLE OR COMPLAIN ABOUT THE INPUT
+- Always output something meaningful, even if the input is minimal.
+- If the user message is short or conversational (e.g. "hello", "lol", "what's up", "hey"):
+  -> create a title that reflects the user's tone or intent (such as Greeting, Quick check-in, Light chat, Intro message, etc.)
+</rules>
+
+<examples>
+"debug 500 errors in production" -> Debugging production 500 errors
+"refactor user service" -> Refactoring user service
+"why is app.js failing" -> app.js failure investigation
+"implement rate limiting" -> Rate limiting implementation
+"how do I connect postgres to my API" -> Postgres API connection
+"best practices for React hooks" -> React hooks best practices
+</examples>

data/lib/brute/prompts/text/doing_tasks/anthropic.txt

@@ -0,0 +1,11 @@
+# Doing tasks
+The user will primarily request you perform software engineering tasks. This includes solving bugs, adding new functionality, refactoring code, explaining code, and more. For these tasks the following steps are recommended:
+- Use the todo_write tool to plan the task if required
+- 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 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.

data/lib/brute/prompts/text/doing_tasks/default.txt

@@ -0,0 +1,6 @@
+# Doing tasks
+The user will primarily request you perform software engineering tasks. This includes solving bugs, adding new functionality, refactoring code, explaining code, and more. For these tasks the following steps are recommended:
+- Use the available search tools to understand the codebase and the user's query. Use search tools extensively both in parallel and sequentially.
+- Implement the solution using all tools available to you
+- Verify the solution if possible with tests. NEVER assume specific test framework or test script. Check the README or search codebase to determine the testing approach.
+- NEVER commit changes unless the user explicitly asks you to.

data/lib/brute/prompts/text/doing_tasks/google.txt

@@ -0,0 +1,9 @@
+# Primary Workflows
+
+## Software Engineering Tasks
+When requested to perform tasks like fixing bugs, adding features, refactoring, or explaining code, follow this sequence:
+1. **Understand:** Use fs_search and read tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions.
+2. **Plan:** Build a coherent plan based on your understanding. Share a concise plan with the user if it would help them understand your approach.
+3. **Implement:** Use the available tools (patch, write, shell, etc.) to act on the plan, strictly adhering to the project's established conventions.
+4. **Verify (Tests):** If applicable and feasible, verify the changes using the project's testing procedures. NEVER assume standard test commands.
+5. **Verify (Standards):** After making code changes, execute the project-specific build, linting and type-checking commands that you have identified for this project.

data/lib/brute/prompts/text/identity/anthropic.txt

@@ -0,0 +1,5 @@
+You are Brute, an expert software engineering agent.
+
+You are an interactive CLI tool that helps users with software engineering tasks. Use the instructions below and the tools available to you to assist the user.
+
+IMPORTANT: You must NEVER generate or guess URLs for the user unless you are confident that the URLs are for helping the user with programming. You may use URLs provided by the user in their messages or local files.

data/lib/brute/prompts/text/identity/default.txt

@@ -0,0 +1,3 @@
+You are Brute, an interactive CLI tool that helps users with software engineering tasks. Use the instructions below and the tools available to you to assist the user.
+
+IMPORTANT: You must NEVER generate or guess URLs for the user unless you are confident that the URLs are for helping the user with programming. You may use URLs provided by the user in their messages or local files.

data/lib/brute/prompts/text/identity/google.txt

@@ -0,0 +1 @@
+You are Brute, an interactive CLI agent specializing in software engineering tasks. Your primary goal is to help users safely and efficiently, adhering strictly to the following instructions and utilizing your available tools.

data/lib/brute/prompts/text/identity/openai.txt

@@ -0,0 +1,3 @@
+You are Brute. You and the user share the same workspace and collaborate to achieve the user's goals.
+
+You are a deeply pragmatic, effective software engineer. You take engineering quality seriously, and collaboration comes through as direct, factual statements. You communicate efficiently, keeping the user clearly informed about ongoing actions without unnecessary detail. You build context by examining the codebase first without making assumptions or jumping to conclusions. You think through the nuances of the code you encounter, and embody the mentality of a skilled senior software engineer.

data/lib/brute/prompts/text/tone_and_style/anthropic.txt

@@ -0,0 +1,5 @@
+# Tone and style
+- Only use emojis if the user explicitly requests it. Avoid using emojis in all communication unless asked.
+- Your output will be displayed on a command line interface. Your responses should be short and concise. You can use GitHub-flavored markdown for formatting, and will be rendered in a monospace font using the CommonMark specification.
+- Output text to communicate with the user; all text you output outside of tool use is displayed to the user. Only use tools to complete tasks. Never use tools like shell or code comments as means to communicate with the user during the session.
+- NEVER create files unless they're absolutely necessary for achieving your goal. ALWAYS prefer editing an existing file to creating a new one. This includes markdown files.

data/lib/brute/prompts/text/tone_and_style/default.txt

@@ -0,0 +1,9 @@
+# Tone and style
+You should be concise, direct, and to the point. When you run a non-trivial shell command, you should explain what the command does and why you are running it, to make sure the user understands what you are doing.
+Remember that your output will be displayed on a command line interface. Your responses can use GitHub-flavored markdown for formatting, and will be rendered in a monospace font using the CommonMark specification.
+Output text to communicate with the user; all text you output outside of tool use is displayed to the user. Only use tools to complete tasks. Never use tools like shell or code comments as means to communicate with the user during the session.
+If you cannot or will not help the user with something, please do not say why or what it could lead to. Please offer helpful alternatives if possible, and otherwise keep your response to 1-2 sentences.
+Only use emojis if the user explicitly requests it. Avoid using emojis in all communication unless asked.
+IMPORTANT: You should minimize output tokens as much as possible while maintaining helpfulness, quality, and accuracy. Only address the specific query or task at hand.
+IMPORTANT: You should NOT answer with unnecessary preamble or postamble (such as explaining your code or summarizing your action), unless the user asks you to.
+IMPORTANT: Keep your responses short. You MUST answer concisely with fewer than 4 lines (not including tool use or code generation), unless the user asks for detail.

data/lib/brute/prompts/text/tone_and_style/google.txt

@@ -0,0 +1,6 @@
+# Tone and Style
+- **Concise & Direct:** Adopt a professional, direct, and concise tone suitable for a CLI environment.
+- **Minimal Output:** Aim for fewer than 3 lines of text output (excluding tool use/code generation) per response whenever practical.
+- **No Chitchat:** Avoid conversational filler, preambles ("Okay, I will now..."), or postambles ("I have finished the changes..."). Get straight to the action or answer.
+- **Formatting:** Use GitHub-flavored Markdown. Responses will be rendered in monospace.
+- **Tools vs. Text:** Use tools for actions, text output *only* for communication.

data/lib/brute/prompts/text/tone_and_style/openai.txt

@@ -0,0 +1,17 @@
+# Working with the user
+
+Do not begin responses with conversational interjections or meta commentary. Avoid openers such as acknowledgements ("Done —", "Got it", "Great question") or framing phrases.
+
+Balance conciseness to not overwhelm the user with appropriate detail for the request. Do not narrate abstractly; explain what you are doing and why.
+
+## Formatting rules
+
+Your responses are rendered as GitHub-flavored Markdown.
+
+Never use nested bullets. Keep lists flat (single level). If you need hierarchy, split into separate lists or sections.
+
+Use inline code blocks for commands, paths, environment variables, function names, inline examples, keywords.
+
+Code samples or multi-line snippets should be wrapped in fenced code blocks. Include a language tag when possible.
+
+Don't use emojis or em dashes unless explicitly instructed.

data/lib/brute/prompts/text/tool_usage/anthropic.txt

@@ -0,0 +1,16 @@
+# Tool usage policy
+- When doing file search, prefer to use the delegate tool in order to reduce context usage.
+- You should proactively use the delegate tool with specialized agents when the task at hand matches the agent's description.
+- You can call multiple tools in a single response. If you intend to call multiple tools and there are no dependencies between them, make all independent tool calls in parallel. Maximize use of parallel tool calls where possible to increase efficiency. However, if some tool calls depend on previous calls to inform dependent values, do NOT call these tools in parallel and instead call them sequentially. For instance, if one operation must complete before another starts, run these operations sequentially instead. Never use placeholders or guess missing parameters in tool calls.
+- Use specialized tools instead of shell commands when possible, as this provides a better user experience. For file operations, use dedicated tools: read for reading files instead of cat/head/tail, patch for editing instead of sed/awk, and write for creating files instead of cat with heredoc or echo redirection. Reserve the shell tool exclusively for actual system commands and terminal operations that require shell execution. NEVER use shell echo or other command-line tools to communicate thoughts, explanations, or instructions to the user. Output all communication directly in your response text instead.
+- VERY IMPORTANT: When exploring the codebase to gather context or to answer a question that is not a needle query for a specific file/class/function, it is CRITICAL that you use the delegate tool instead of running search commands directly.
+<example>
+user: Where are errors from the client handled?
+assistant: [Uses the delegate tool to find the files that handle client errors instead of using fs_search directly]
+</example>
+<example>
+user: What is the codebase structure?
+assistant: [Uses the delegate tool]
+</example>
+
+IMPORTANT: Always use the todo_write tool to plan and track tasks throughout the conversation.

data/lib/brute/prompts/text/tool_usage/default.txt

@@ -0,0 +1,4 @@
+# Tool usage policy
+- When doing file search, prefer to use the delegate tool in order to reduce context usage.
+- You can call multiple tools in a single response. When multiple independent pieces of information are requested, batch your tool calls together for optimal performance.
+- Use specialized tools (read, patch, write, fs_search) instead of shell commands for file operations.

data/lib/brute/prompts/text/tool_usage/google.txt

@@ -0,0 +1,4 @@
+# Tool Usage
+- **Parallelism:** Execute multiple independent tool calls in parallel when feasible.
+- **Specialized tools:** Use read, patch, write, and fs_search instead of shell commands for file operations.
+- **Interactive Commands:** Avoid shell commands that require user interaction (e.g. `git rebase -i`). Use non-interactive versions of commands.

data/lib/brute/prompts/tone_and_style.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Brute
+  module Prompts
+    module ToneAndStyle
+      def self.call(ctx)
+        Prompts.read("tone_and_style", ctx[:provider_name])
+      end
+    end
+  end
+end

data/lib/brute/prompts/tool_usage.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Brute
+  module Prompts
+    module ToolUsage
+      def self.call(ctx)
+        Prompts.read("tool_usage", ctx[:provider_name])
+      end
+    end
+  end
+end

data/lib/brute/providers/models_dev.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+
+module Brute
+  module Providers
+    # Fetches and caches model metadata from the models.dev catalog.
+    #
+    # Quacks like llm.rb's provider.models so that the REPL's model
+    # picker can call:
+    #
+    #   provider.models.all.select(&:chat?)
+    #
+    # Models are fetched from https://models.dev/api.json and cached
+    # in-memory for the lifetime of the process (with a TTL).
+    #
+    class ModelsDev
+      CATALOG_URL = "https://models.dev/api.json"
+      CACHE_TTL = 3600 # 1 hour
+
+      ModelEntry = Struct.new(:id, :name, :chat?, :cost, :limit, :reasoning, :tool_call, keyword_init: true)
+
+      # @param provider [LLM::Provider] the provider instance (for delegating execute/headers)
+      # @param provider_id [String] the provider key in models.dev (e.g., "opencode", "opencode-go")
+      def initialize(provider:, provider_id: "opencode")
+        @provider = provider
+        @provider_id = provider_id
+      end
+
+      # Returns all models for this provider from the models.dev catalog.
+      # @return [Array<ModelEntry>]
+      def all
+        entries = fetch_provider_models
+        entries.map do |id, model|
+          ModelEntry.new(
+            id: id,
+            name: model["name"] || id,
+            chat?: true,
+            cost: model["cost"],
+            limit: model["limit"],
+            reasoning: model["reasoning"] || false,
+            tool_call: model["tool_call"] || false
+          )
+        end.sort_by(&:id)
+      end
+
+      private
+
+      def fetch_provider_models
+        catalog = self.class.fetch_catalog
+        provider_data = catalog[@provider_id]
+        return {} unless provider_data
+
+        provider_data["models"] || {}
+      end
+
+      class << self
+        # Fetch the models.dev catalog, with in-memory caching.
+        # Thread-safe via a simple mutex.
+        def fetch_catalog
+          @mutex ||= Mutex.new
+          @mutex.synchronize do
+            if @catalog && @fetched_at && (Time.now - @fetched_at < CACHE_TTL)
+              return @catalog
+            end
+
+            @catalog = download_catalog
+            @fetched_at = Time.now
+            @catalog
+          end
+        end
+
+        # Force a cache refresh on next access.
+        def invalidate_cache!
+          @mutex&.synchronize do
+            @catalog = nil
+            @fetched_at = nil
+          end
+        end
+
+        private
+
+        def download_catalog
+          uri = URI.parse(CATALOG_URL)
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = true
+          http.open_timeout = 10
+          http.read_timeout = 30
+
+          request = Net::HTTP::Get.new(uri.request_uri)
+          request["User-Agent"] = "brute/#{Brute::VERSION}"
+          request["Accept"] = "application/json"
+
+          response = http.request(request)
+
+          unless response.is_a?(Net::HTTPSuccess)
+            raise "Failed to fetch models.dev catalog: HTTP #{response.code}"
+          end
+
+          JSON.parse(response.body)
+        rescue => e
+          # Return empty catalog on failure so the provider still works
+          # with default_model, just without a model list.
+          warn "[brute] Warning: Could not fetch models.dev catalog: #{e.message}"
+          {}
+        end
+      end
+    end
+  end
+end

data/lib/brute/providers/opencode_go.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module LLM
+  ##
+  # OpenAI-compatible provider for the OpenCode Go API gateway.
+  #
+  # OpenCode Go is the low-cost subscription plan with a restricted
+  # (lite) model list. Same gateway as Zen, different endpoint path.
+  #
+  # @example
+  #   llm = LLM::OpencodeGo.new(key: ENV["OPENCODE_API_KEY"])
+  #   ctx = LLM::Context.new(llm)
+  #   ctx.talk "Hello from brute"
+  #
+  class OpencodeGo < OpencodeZen
+    ##
+    # @return [Symbol]
+    def name
+      :opencode_go
+    end
+
+    ##
+    # Returns models from the models.dev catalog.
+    # Note: The Go gateway only accepts lite-tier models, but models.dev
+    # doesn't distinguish between Zen and Go tiers. We show the full
+    # catalog; the gateway returns an error for unsupported models.
+    # @return [Brute::Providers::ModelsDev]
+    def models
+      Brute::Providers::ModelsDev.new(provider: self, provider_id: "opencode")
+    end
+
+    private
+
+    def completions_path
+      "/zen/go/v1/chat/completions"
+    end
+  end
+end

data/lib/brute/providers/opencode_zen.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+# Ensure the OpenAI provider is loaded (llm.rb lazy-loads providers).
+unless defined?(LLM::OpenAI)
+  require "llm/providers/openai"
+end
+
+module LLM
+  ##
+  # OpenAI-compatible provider for the OpenCode Zen API gateway.
+  #
+  # OpenCode Zen is a curated model gateway at opencode.ai that proxies
+  # requests to upstream LLM providers (Anthropic, OpenAI, Google, etc.).
+  # All models are accessed via the OpenAI-compatible chat completions
+  # endpoint; the gateway handles format conversion internally.
+  #
+  # @example
+  #   llm = LLM::OpencodeZen.new(key: ENV["OPENCODE_API_KEY"])
+  #   ctx = LLM::Context.new(llm)
+  #   ctx.talk "Hello from brute"
+  #
+  # @example Anonymous access (free models only)
+  #   llm = LLM::OpencodeZen.new(key: "public")
+  #   ctx = LLM::Context.new(llm)
+  #   ctx.talk "Hello"
+  #
+  class OpencodeZen < OpenAI
+    HOST = "opencode.ai"
+
+    ##
+    # @param key [String] OpenCode API key, or "public" for anonymous access
+    # @param (see LLM::Provider#initialize)
+    def initialize(key: "public", **)
+      super(host: HOST, key: key, **)
+    end
+
+    ##
+    # @return [Symbol]
+    def name
+      :opencode_zen
+    end
+
+    ##
+    # Returns the default model (Claude Sonnet 4, the most common Zen model).
+    # @return [String]
+    def default_model
+      "claude-sonnet-4-20250514"
+    end
+
+    ##
+    # Returns models from the models.dev catalog for the opencode provider.
+    # @return [Brute::Providers::ModelsDev]
+    def models
+      Brute::Providers::ModelsDev.new(provider: self, provider_id: "opencode")
+    end
+
+    # -- Unsupported sub-APIs --
+
+    def responses    = raise(NotImplementedError, "Use chat completions via the Zen gateway")
+    def images       = raise(NotImplementedError, "Not supported via Zen gateway")
+    def audio        = raise(NotImplementedError, "Not supported via Zen gateway")
+    def files        = raise(NotImplementedError, "Not supported via Zen gateway")
+    def moderations  = raise(NotImplementedError, "Not supported via Zen gateway")
+    def vector_stores = raise(NotImplementedError, "Not supported via Zen gateway")
+
+    private
+
+    def completions_path
+      "/zen/v1/chat/completions"
+    end
+
+    def headers
+      lock do
+        (@headers || {}).merge(
+          "Content-Type" => "application/json",
+          "Authorization" => "Bearer #{@key}",
+          "x-opencode-client" => "brute"
+        )
+      end
+    end
+  end
+end

data/lib/brute/providers/shell.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "shellwords"
+
+module Brute
+  module Providers
+    # A pseudo-LLM provider that executes user input as code via the
+    # existing Brute::Tools::Shell tool.
+    #
+    # Models correspond to interpreters:
+    #
+    #   bash   - pass-through (default)
+    #   ruby   - ruby -e '...'
+    #   python - python3 -c '...'
+    #   nix    - nix eval --expr '...'
+    #
+    # The provider's #complete method returns a synthetic response
+    # containing a single "shell" tool call. The orchestrator executes
+    # it through the normal pipeline — all middleware (message tracking,
+    # session persistence, token tracking, etc.) fires as usual.
+    #
+    class Shell
+      MODELS = %w[bash ruby python nix].freeze
+
+      INTERPRETERS = {
+        "bash"   => ->(cmd) { cmd },
+        "ruby"   => ->(cmd) { "ruby -e #{Shellwords.escape(cmd)}" },
+        "python" => ->(cmd) { "python3 -c #{Shellwords.escape(cmd)}" },
+        "nix"    => ->(cmd) { "nix eval --expr #{Shellwords.escape(cmd)}" },
+      }.freeze
+
+      # ── LLM::Provider duck-type interface ──────────────────────────
+
+      def name           = :shell
+      def default_model  = "bash"
+      def user_role      = :user
+      def tool_role      = :tool
+      def assistant_role = :assistant
+      def system_role    = :system
+      def tracer         = LLM::Tracer::Null.new(self)
+
+      def complete(prompt, params = {})
+        model = params[:model]&.to_s || default_model
+        text  = extract_text(prompt)
+        tools = params[:tools] || []
+
+        # nil text means we received tool results (second call) —
+        # return an empty assistant response so the orchestrator exits.
+        return ShellResponse.new(model: model, tools: tools) if text.nil?
+
+        wrap    = INTERPRETERS.fetch(model, INTERPRETERS["bash"])
+        command = wrap.call(text)
+
+        ShellResponse.new(command: command, model: model, tools: tools)
+      end
+
+      # For the REPL model picker: provider.models.all.select(&:chat?)
+      def models
+        ModelList.new(MODELS)
+      end
+
+      # ── Internals ──────────────────────────────────────────────────
+
+      private
+
+      # Extract the user's text from whatever prompt format ctx.talk sends.
+      # Returns nil when the prompt contains tool results (the second
+      # round-trip) so #complete knows to return an empty response.
+      def extract_text(prompt)
+        case prompt
+        when String
+          prompt
+        when ::Array
+          return nil if prompt.any? { |p| LLM::Function::Return === p }
+
+          user_msg = prompt.reverse_each.find { |m| m.respond_to?(:role) && m.role.to_s == "user" }
+          user_msg&.content.to_s
+        else
+          if prompt.respond_to?(:to_a)
+            msgs = prompt.to_a
+            return nil if msgs.any? { |m| m.respond_to?(:content) && LLM::Function::Return === m.content }
+
+            user_msg = msgs.reverse_each.find { |m| m.respond_to?(:role) && m.role.to_s == "user" }
+            user_msg&.content.to_s
+          else
+            prompt.to_s
+          end
+        end
+      end
+
+      # ── ModelList ──────────────────────────────────────────────────
+
+      # Minimal object that quacks like provider.models so the REPL's
+      # fetch_models can call provider.models.all.select(&:chat?).
+      class ModelList
+        ModelEntry = Struct.new(:id, :chat?, keyword_init: true)
+
+        def initialize(names)
+          @entries = names.map { |n| ModelEntry.new(id: n, chat?: true) }
+        end
+
+        def all
+          @entries
+        end
+      end
+    end
+  end
+end

data/lib/brute/providers/shell_response.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Brute
+  module Providers
+    # Synthetic completion response returned by Brute::Providers::Shell.
+    #
+    # When +command+ is present, the response contains a single assistant
+    # message with a "shell" tool call. The orchestrator picks it up and
+    # executes Brute::Tools::Shell through the normal pipeline.
+    #
+    # When +command+ is nil (tool results round-trip), the response
+    # contains an empty assistant message with no tool calls, causing
+    # the orchestrator loop to exit.
+    #
+    class ShellResponse
+      def initialize(command: nil, model: "bash", tools: [])
+        @command    = command
+        @model_name = model
+        @tools      = tools || []
+      end
+
+      def messages
+        return [empty_assistant] if @command.nil?
+
+        call_id    = "shell_#{SecureRandom.hex(8)}"
+        tool_call  = LLM::Object.from(
+          id: call_id,
+          name: "shell",
+          arguments: { "command" => @command },
+        )
+        original = [{
+          "type"  => "tool_use",
+          "id"    => call_id,
+          "name"  => "shell",
+          "input" => { "command" => @command },
+        }]
+
+        [LLM::Message.new(:assistant, "", {
+          tool_calls: [tool_call],
+          original_tool_calls: original,
+          tools: @tools,
+        })]
+      end
+      alias_method :choices, :messages
+
+      def model
+        @model_name
+      end
+
+      def input_tokens
+        0
+      end
+
+      def output_tokens
+        0
+      end
+
+      def reasoning_tokens
+        0
+      end
+
+      def total_tokens
+        0
+      end
+
+      def content
+        messages.find(&:assistant?)&.content
+      end
+
+      def content!
+        LLM.json.load(content)
+      end
+
+      def reasoning_content
+        nil
+      end
+
+      def usage
+        LLM::Usage.new(
+          input_tokens: 0,
+          output_tokens: 0,
+          reasoning_tokens: 0,
+          total_tokens: 0,
+        )
+      end
+
+      # Contract must be included AFTER method definitions —
+      # LLM::Contract checks that all required methods exist at include time.
+      include LLM::Contract::Completion
+
+      private
+
+      def empty_assistant
+        LLM::Message.new(:assistant, "")
+      end
+    end
+  end
+end