brute 5.0.5 → 6.0.0

data/lib/brute/prompts/base.rb

@@ -14,9 +14,14 @@ module Brute
     def self.read(section, provider_name)
       provider = provider_name.to_s
       path = File.join(TEXT_DIR, section, "#{provider}.txt")
-      path = File.join(TEXT_DIR, section, "default.txt") unless File.exist?(path)
-      return nil unless File.exist?(path)
-      File.read(path)
+      unless File.exist?(path)
+        path = File.join(TEXT_DIR, section, "default.txt")
+      end
+      if File.exist?(path)
+        File.read(path)
+      else
+        nil
+      end
     end
 
     # Read a named agent prompt (e.g. "explore", "compaction").
@@ -33,9 +38,11 @@ module Brute
       end
 
       def method_missing(name, *args)
-        return @ctx[name] if args.empty? && @ctx.key?(name)
-
-        super
+        if args.empty? && @ctx.key?(name)
+          @ctx[name]
+        else
+          super
+        end
       end
 
       def respond_to_missing?(name, include_private = false)
@@ -69,10 +76,12 @@ module Brute
       path = [provider, "default"]
              .map { |variant| File.join(TEXT_DIR, section, "#{variant}.erb") }
              .find { |candidate| File.exist?(candidate) }
-      return read(section, provider) unless path
-
-      erb = TEMPLATES[path] ||= ERB.new(File.read(path), trim_mode: "-")
-      erb.result(Context.new(ctx).get_binding)
+      if path
+        erb = TEMPLATES[path] ||= ERB.new(File.read(path), trim_mode: "-")
+        erb.result(Context.new(ctx).get_binding)
+      else
+        read(section, provider)
+      end
     end
   end
 end

data/lib/brute/prompts/environment.rb

@@ -12,7 +12,9 @@ module Brute
         git = File.exist?(File.join(cwd, ".git"))
 
         parts = []
-        parts << "You are powered by the model named #{model}." unless model.empty?
+        unless model.empty?
+          parts << "You are powered by the model named #{model}."
+        end
         parts << ""
         parts << "Here is some useful information about the environment you are running in:"
         parts << "<env>"

data/lib/brute/prompts/instructions.rb

@@ -8,13 +8,15 @@ module Brute
     module Instructions
       def self.call(ctx)
         rules = ctx[:custom_rules]
-        return nil if rules.nil? || rules.strip.empty?
-
-        <<~TXT
-          # Project-Specific Rules
-
-          #{rules}
-        TXT
+        if rules.nil? || rules.strip.empty?
+          nil
+        else
+          <<~TXT
+            # Project-Specific Rules
+
+            #{rules}
+          TXT
+        end
       end
     end
   end

data/lib/brute/prompts/skills.rb

@@ -16,9 +16,11 @@ module Brute
       def self.call(ctx)
         skills = ctx[:skills] || Brute::Skill.all(cwd: ctx[:cwd] || Dir.pwd)
         visible = skills.reject(&:disable_model_invocation?)
-        return nil if visible.empty?
-
-        Prompts.render("skills", ctx.merge(skills: visible))
+        if visible.empty?
+          nil
+        else
+          Prompts.render("skills", ctx.merge(skills: visible))
+        end
       end
     end
   end

data/lib/brute/rack/adapter.rb

@@ -38,7 +38,9 @@ module Brute
       # @parameter agent [#start] Anything with `start(prompt) -> env` — an
       #   AgentPipeline, a SubAgent, or any turn-shaped callable.
       def initialize(agent)
-        raise ArgumentError, "agent must respond to #start" unless agent.respond_to?(:start)
+        unless agent.respond_to?(:start)
+          raise ArgumentError, "agent must respond to #start"
+        end
 
         @agent = agent
       end
@@ -48,10 +50,12 @@ module Brute
       # (client's fault); anything the turn raises is a 500.
       def call(env)
         prompt = prompt_from(env)
-        return response_for(env, 400, "No prompt provided.") if prompt.nil? || prompt.empty?
-
-        turn = @agent.start(prompt)
-        response_for(env, 200, output_of(turn))
+        if prompt.nil? || prompt.empty?
+          response_for(env, 400, "No prompt provided.")
+        else
+          turn = @agent.start(prompt)
+          response_for(env, 200, output_of(turn))
+        end
       rescue => error
         response_for(env, 500, error.message)
       end
@@ -68,24 +72,29 @@ module Brute
         request = ::Rack::Request.new(env)
 
         if (query = request.GET["prompt"]) && !query.empty?
-          return query
-        end
-
-        body = read_body(request)
-        return nil if body.nil? || body.strip.empty?
-
-        if json?(request.media_type)
-          case data = parse_json(body)
-          when ::Hash   then return PROMPT_KEYS.filter_map { |key| data[key] }.first&.to_s || body
-          when ::String then return data
+          query
+        else
+          body = read_body(request)
+          if body.nil? || body.strip.empty?
+            nil
+          else
+            from_json = nil
+            if json?(request.media_type)
+              case data = parse_json(body)
+              when ::Hash   then from_json = PROMPT_KEYS.filter_map { |key| data[key] }.first&.to_s || body
+              when ::String then from_json = data
+              end
+            end
+
+            if from_json
+              from_json
+            elsif request.form_data? && (field = ::Rack::Utils.parse_nested_query(body)["prompt"])
+              field
+            else
+              body
+            end
           end
         end
-
-        if request.form_data? && (field = ::Rack::Utils.parse_nested_query(body)["prompt"])
-          return field
-        end
-
-        body
       end
 
       # output -> [status, headers, body]. Content-negotiated: JSON in (or an
@@ -96,7 +105,11 @@ module Brute
         text = output.to_s
 
         if wants_json?(env)
-          key = status == 200 ? :response : :error
+          if status == 200
+            key = :response
+          else
+            key = :error
+          end
           [status, {"content-type" => "application/json"}, [::JSON.generate(key => text)]]
         else
           [status, {"content-type" => "text/plain; charset=utf-8"}, [text]]
@@ -107,7 +120,11 @@ module Brute
 
         # The agent's answer is the last message it appended to the log.
         def output_of(turn)
-          messages = turn.is_a?(::Hash) ? turn[:messages] : turn
+          if turn.is_a?(::Hash)
+            messages = turn[:messages]
+          else
+            messages = turn
+          end
           messages&.last&.content.to_s
         end
 

data/lib/brute/skill.rb

@@ -34,8 +34,16 @@ module Brute
   # (https://agentskills.io/specification). A skill whose frontmatter violates
   # a rule is skipped with a stderr warning naming the rule — never raised.
   class Skill
-    attr_reader :name, :description, :file_path, :base_dir, :content,
-                :source, :license, :compatibility, :metadata, :allowed_tools
+    attr_reader :name,
+      :description,
+      :file_path,
+      :base_dir,
+      :content,
+      :source,
+      :license,
+      :compatibility,
+      :metadata,
+      :allowed_tools
 
     FILENAME = "SKILL.md"
 
@@ -74,38 +82,42 @@ module Brute
     def self.load(path, source: :path)
       raw = File.read(path)
       frontmatter, content = parse_frontmatter(path, raw)
-      return nil unless frontmatter
-
-      dir_name = File.basename(File.dirname(path))
-      # Spec requires `name`; brute keeps the convenience of defaulting to the
-      # directory name when omitted (which trivially satisfies the dir-match rule).
-      frontmatter = { "name" => dir_name }.merge(frontmatter) unless frontmatter.key?("name")
-
-      # Unknown fields are a soft violation: warn and drop them rather than
-      # reject the skill. The reference validator hard-fails here, but a runtime
-      # loader must tolerate vendor/forward extensions (e.g. `tags`), which real
-      # published skills carry, instead of silently dropping the whole skill.
-      extra = frontmatter.keys - ALLOWED_FIELDS
-      warn "Skill #{path} has unexpected frontmatter fields (ignored): #{extra.sort.join(', ')}" unless extra.empty?
-
-      errors = validate(frontmatter, dir_name)
-      unless errors.empty?
-        warn "Skipping invalid skill #{path}: #{errors.join('; ')}"
-        return nil
-      end
+      if frontmatter
+        dir_name = File.basename(File.dirname(path))
+        # Spec requires `name`; brute keeps the convenience of defaulting to the
+        # directory name when omitted (which trivially satisfies the dir-match rule).
+        unless frontmatter.key?("name")
+          frontmatter = { "name" => dir_name }.merge(frontmatter)
+        end
 
-      new(
-        name: frontmatter["name"].to_s.strip,
-        description: frontmatter["description"].to_s.strip,
-        file_path: path,
-        content: content.to_s.strip,
-        source: source,
-        license: frontmatter["license"]&.to_s,
-        compatibility: frontmatter["compatibility"]&.to_s,
-        metadata: frontmatter["metadata"],
-        allowed_tools: parse_allowed_tools(frontmatter["allowed-tools"]),
-        disable_model_invocation: frontmatter["disable-model-invocation"] == true,
-      )
+        # Unknown fields are a soft violation: warn and drop them rather than
+        # reject the skill. The reference validator hard-fails here, but a runtime
+        # loader must tolerate vendor/forward extensions (e.g. `tags`), which real
+        # published skills carry, instead of silently dropping the whole skill.
+        extra = frontmatter.keys - ALLOWED_FIELDS
+        unless extra.empty?
+          warn "Skill #{path} has unexpected frontmatter fields (ignored): #{extra.sort.join(', ')}"
+        end
+
+        errors = validate(frontmatter, dir_name)
+        if errors.empty?
+          new(
+            name:                     frontmatter["name"].to_s.strip,
+            description:              frontmatter["description"].to_s.strip,
+            file_path:                path,
+            content:                  content.to_s.strip,
+            source:                   source,
+            license:                  frontmatter["license"]&.to_s,
+            compatibility:            frontmatter["compatibility"]&.to_s,
+            metadata:                 frontmatter["metadata"],
+            allowed_tools:            parse_allowed_tools(frontmatter["allowed-tools"]),
+            disable_model_invocation: frontmatter["disable-model-invocation"] == true,
+          )
+        else
+          warn "Skipping invalid skill #{path}: #{errors.join('; ')}"
+          nil
+        end
+      end
     rescue => e
       warn "Failed to load skill #{path}: #{e.message}"
       nil
@@ -122,25 +134,28 @@ module Brute
 
       add = lambda do |path, source|
         skill = load(path, source: source)
-        return unless skill
-
-        real = realpath(path)
-        return if seen_files[real]
-
-        if (winner = skills[skill.name])
-          warn "Skill name collision: '#{skill.name}' at #{path} ignored; " \
-               "already loaded from #{winner.file_path}"
-          return
+        real  = skill && realpath(path)
+
+        if skill && !seen_files[real]
+          if (winner = skills[skill.name])
+            warn "Skill name collision: '#{skill.name}' at #{path} ignored; " \
+                 "already loaded from #{winner.file_path}"
+          else
+            seen_files[real] = true
+            skills[skill.name] = skill
+          end
         end
-
-        seen_files[real] = true
-        skills[skill.name] = skill
       end
 
       project = File.join(cwd, ".brute", "skills")
       glob(project) { |path| add.call(path, :project) }
 
-      global = File.join(Dir.home, ".config", "brute", "skills")
+      global = File.join(
+        Dir.home,
+        ".config",
+        "brute",
+        "skills",
+      )
       glob(global) { |path| add.call(path, :user) }
 
       paths.each do |raw|
@@ -163,9 +178,11 @@ module Brute
     end
 
     def self.glob(dir, &block)
-      return unless File.directory?(dir)
-
-      Dir.glob(File.join(dir, "**", FILENAME)).sort.each(&block)
+      if File.directory?(dir)
+        Dir.glob(File.join(dir, "**", FILENAME)).sort.each(&block)
+      else
+        nil
+      end
     end
 
     def self.realpath(path)
@@ -177,70 +194,100 @@ module Brute
     # Validate frontmatter against the spec. Returns an array of error strings
     # (empty means valid), each naming the violated rule.
     def self.validate(frontmatter, dir_name)
-      errors = []
-
-      errors.concat(validate_name(frontmatter["name"], dir_name))
-      errors.concat(validate_description(frontmatter["description"]))
-
-      if frontmatter.key?("compatibility")
-        compatibility = frontmatter["compatibility"]
-        if !compatibility.is_a?(String)
-          errors << "'compatibility' must be a string"
-        elsif compatibility.length > MAX_COMPATIBILITY_LENGTH
-          errors << "'compatibility' exceeds #{MAX_COMPATIBILITY_LENGTH} characters"
+      [].tap do |errors|
+        errors.concat(validate_name(frontmatter["name"], dir_name))
+        errors.concat(validate_description(frontmatter["description"]))
+
+        if frontmatter.key?("compatibility")
+          compatibility = frontmatter["compatibility"]
+          if !compatibility.is_a?(String)
+            errors << "'compatibility' must be a string"
+          elsif compatibility.length > MAX_COMPATIBILITY_LENGTH
+            errors << "'compatibility' exceeds #{MAX_COMPATIBILITY_LENGTH} characters"
+          end
         end
       end
-
-      errors
     end
 
     def self.validate_name(name, dir_name)
-      return ["missing required field 'name'"] unless name.is_a?(String) && !name.strip.empty?
-
-      name = name.strip.unicode_normalize(:nfkc)
-      errors = []
-      errors << "'name' exceeds #{MAX_NAME_LENGTH} characters" if name.length > MAX_NAME_LENGTH
-      errors << "'name' must be lowercase" if name != name.downcase
-      errors << "'name' cannot start or end with a hyphen" if name.start_with?("-") || name.end_with?("-")
-      errors << "'name' cannot contain consecutive hyphens" if name.include?("--")
-      errors << "'name' may only contain letters, digits, and hyphens" unless name.match?(/\A[\p{Alnum}\-]+\z/)
-      errors << "directory name '#{dir_name}' must match skill name '#{name}'" if dir_name.unicode_normalize(:nfkc) != name
-      errors
+      if name.is_a?(String) && !name.strip.empty?
+        name = name.strip.unicode_normalize(:nfkc)
+        errors = []
+        if name.length > MAX_NAME_LENGTH
+          errors << "'name' exceeds #{MAX_NAME_LENGTH} characters"
+        end
+        if name != name.downcase
+          errors << "'name' must be lowercase"
+        end
+        if name.start_with?("-") || name.end_with?("-")
+          errors << "'name' cannot start or end with a hyphen"
+        end
+        if name.include?("--")
+          errors << "'name' cannot contain consecutive hyphens"
+        end
+        unless name.match?(/\A[\p{Alnum}\-]+\z/)
+          errors << "'name' may only contain letters, digits, and hyphens"
+        end
+        if dir_name.unicode_normalize(:nfkc) != name
+          errors << "directory name '#{dir_name}' must match skill name '#{name}'"
+        end
+        errors
+      else
+        ["missing required field 'name'"]
+      end
     end
 
     def self.validate_description(description)
-      return ["missing required field 'description'"] unless description.is_a?(String) && !description.strip.empty?
-      return ["'description' exceeds #{MAX_DESCRIPTION_LENGTH} characters"] if description.length > MAX_DESCRIPTION_LENGTH
-
-      []
+      if description.is_a?(String) && !description.strip.empty?
+        if description.length > MAX_DESCRIPTION_LENGTH
+          ["'description' exceeds #{MAX_DESCRIPTION_LENGTH} characters"]
+        else
+          []
+        end
+      else
+        ["missing required field 'description'"]
+      end
     end
 
     # `allowed-tools` is an experimental, space-separated list of tool names.
     def self.parse_allowed_tools(value)
-      return nil if value.nil?
-
-      value.to_s.split(/\s+/).reject(&:empty?)
+      if value.nil?
+        nil
+      else
+        value.to_s.split(/\s+/).reject(&:empty?)
+      end
     end
 
     # Split YAML frontmatter from markdown body.
     # Returns [hash, string] or [nil, nil].
     def self.parse_frontmatter(path, raw)
-      return [nil, nil] unless raw.start_with?("---")
-
-      parts = raw.split(/^---\s*$/, 3)
-      return [nil, nil] if parts.length < 3
+      parts = nil
+      if raw.start_with?("---")
+        parts = raw.split(/^---\s*$/, 3)
+      end
 
-      frontmatter = YAML.safe_load(parts[1])
-      return [nil, nil] unless frontmatter.is_a?(Hash)
+      frontmatter = nil
+      if parts && parts.length >= 3
+        frontmatter = YAML.safe_load(parts[1])
+      end
 
-      [frontmatter, parts[2]]
+      if frontmatter.is_a?(Hash)
+        [frontmatter, parts[2]]
+      else
+        [nil, nil]
+      end
     rescue => e
       warn "Failed to parse frontmatter in #{path}: #{e.message}"
       [nil, nil]
     end
 
-    private_class_method :glob, :realpath, :validate, :validate_name,
-                         :validate_description, :parse_allowed_tools, :parse_frontmatter
+    private_class_method :glob,
+      :realpath,
+      :validate,
+      :validate_name,
+      :validate_description,
+      :parse_allowed_tools,
+      :parse_frontmatter
   end
 end
 

data/lib/brute/system_prompt.rb

@@ -34,11 +34,11 @@ module Brute
         # upstream model family from the model name so we use the most
         # appropriate prompt stack (e.g., anthropic stack for claude-*).
         provider = ctx[:provider_name].to_s
-        stack_key = if provider.start_with?("opencode")
-                      infer_stack_from_model(ctx[:model_name].to_s)
-                    else
-                      provider
-                    end
+        if provider.start_with?("opencode")
+          stack_key = infer_stack_from_model(ctx[:model_name].to_s)
+        else
+          stack_key = provider
+        end
         STACKS.fetch(stack_key, STACKS["default"]).each do |mod|
           prompt << mod.call(ctx)
         end
@@ -78,7 +78,7 @@ module Brute
       ],
 
       # GPT-4 / o1 / o3 — pragmatic engineer persona, editing focus, autonomy
-      "openai" => [
+      "openai"    => [
         Prompts::Identity,
         Prompts::EditingApproach,
         Prompts::Autonomy,
@@ -94,7 +94,7 @@ module Brute
       ],
 
       # Gemini — formal/structured, explicit workflows, security focus
-      "google" => [
+      "google"    => [
         Prompts::Identity,
         Prompts::Conventions,
         Prompts::DoingTasks,
@@ -109,7 +109,7 @@ module Brute
       ],
 
       # Ollama — lean stack for local models with smaller context windows
-      "ollama" => [
+      "ollama"    => [
         Prompts::Identity,
         Prompts::ToneAndStyle,
         Prompts::Conventions,
@@ -121,7 +121,7 @@ module Brute
       ],
 
       # Fallback — conservative, concise, fewer than 4 lines
-      "default" => [
+      "default"   => [
         Prompts::Identity,
         Prompts::ToneAndStyle,
         Prompts::Proactiveness,

data/lib/brute/token_counter/approximate.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+
+module Brute
+  module TokenCounter
+    # Tokens from text length, at a flat ratio of characters to tokens.
+    #
+    # Four characters to the token is the usual approximation. It needs no
+    # dependency and it is close enough to decide what to give up; put a
+    # Tiktoken counter on env[:token_counter] when the difference matters.
+    #
+    # `per_message` is what the rendering cannot see: every message is wrapped
+    # in the provider's own chat template on the way out, and that framing
+    # costs a few tokens each whatever the message says.
+    class Approximate
+      def initialize(chars_per_token: 4.0, per_message: 4)
+        unless chars_per_token.positive?
+          raise ArgumentError, "chars_per_token must be greater than 0, got #{chars_per_token}"
+        end
+
+        @chars_per_token = chars_per_token
+        @per_message = per_message
+      end
+
+      def count(messages, tools: nil)
+        text = Rendering.conversation(messages) + Rendering.tools(tools)
+
+        (text.length / @chars_per_token).to_i + (Array(messages).length * @per_message)
+      end
+    end
+  end
+end
+
+__END__
+
+describe "brute/token_counter/approximate" do
+  it "divides the rendered text by the ratio, and charges for the envelope each message rides in" do
+    log = Brute.log
+    log.user("a" * 400)
+
+    # "user: " + 400 characters, four to the token, plus the envelope.
+    Brute::TokenCounter::Approximate.new.count(log).should == 105
+
+    # The ratio and the envelope are both settings, not truths.
+    Brute::TokenCounter::Approximate.new(chars_per_token: 2.0).count(log).should == 207
+    Brute::TokenCounter::Approximate.new(per_message: 0).count(log).should == 101
+
+    Brute::TokenCounter::Approximate.new.count([]).should == 0
+
+    lambda { Brute::TokenCounter::Approximate.new(chars_per_token: 0) }.should.raise(ArgumentError)
+  end
+end