brute 3.2.1 → 4.0.0

data/lib/brute/prompts/base.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "erb"
+
 require "bundler/setup"
 require "brute"
 
@@ -22,5 +24,108 @@ module Brute
       path = File.join(TEXT_DIR, "agents", "#{name}.txt")
       File.exist?(path) ? File.read(path) : nil
     end
+
+    # Template context handed to ERB templates. Context-hash keys become
+    # methods (<%= skills %>, <%= cwd %>), plus view helpers like +h+.
+    class Context
+      def initialize(ctx)
+        @ctx = ctx
+      end
+
+      def method_missing(name, *args)
+        return @ctx[name] if args.empty? && @ctx.key?(name)
+
+        super
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        @ctx.key?(name) || super
+      end
+
+      # XML-escape a value for prompt markup (& < > " ').
+      def escape_xml(value)
+        value.to_s.gsub("&", "&amp;").gsub("<", "&lt;").gsub(">", "&gt;")
+           .gsub('"', "&quot;").gsub("'", "&apos;")
+      end
+      alias h escape_xml
+
+      def get_binding
+        binding
+      end
+    end
+
+    # Compiled templates, keyed by absolute path. Compilation is idempotent,
+    # so a racy double-assign under Async is harmless.
+    TEMPLATES = {}
+
+    # Resolve and render text/<section>/<provider>.erb, falling back to
+    # default.erb, then to the legacy plain .txt files. Returns nil when the
+    # section has no template or text file at all.
+    #
+    # Templates are ERB: arbitrary Ruby. Only ship templates with the gem or
+    # load them from paths you trust.
+    def self.render(section, ctx)
+      provider = ctx[:provider_name].to_s
+      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)
+    end
+  end
+end
+
+__END__
+
+describe "brute/prompts/base" do
+  require "tmpdir"
+  require "fileutils"
+
+  it "interpolates ctx keys as methods" do
+    ctx = Brute::Prompts::Context.new(name: "debugging")
+    template = ERB.new("<%= name %>")
+    template.result(ctx.get_binding).should == "debugging"
+  end
+
+  it "escapes XML via h" do
+    ctx = Brute::Prompts::Context.new({})
+    ctx.h(%q{a<b>&"c'}).should == "a&lt;b&gt;&amp;&quot;c&apos;"
+  end
+
+  it "renders a section template with provider fallback" do
+    section = "base_test_render"
+    dir = File.join(Brute::Prompts::TEXT_DIR, section)
+    FileUtils.mkdir_p(dir)
+    File.write(File.join(dir, "default.erb"), "hello <%= thing %>")
+    begin
+      Brute::Prompts.render(section, provider_name: "nope", thing: "world").should == "hello world"
+    ensure
+      FileUtils.remove_entry(dir)
+    end
+  end
+
+  it "prefers a provider-specific template over default" do
+    section = "base_test_provider"
+    dir = File.join(Brute::Prompts::TEXT_DIR, section)
+    FileUtils.mkdir_p(dir)
+    File.write(File.join(dir, "default.erb"), "default")
+    File.write(File.join(dir, "anthropic.erb"), "anthropic")
+    begin
+      Brute::Prompts.render(section, provider_name: "anthropic").should == "anthropic"
+      Brute::Prompts.render(section, provider_name: "openai").should == "default"
+    ensure
+      FileUtils.remove_entry(dir)
+    end
+  end
+
+  it "falls back to a legacy plain text file when no template exists" do
+    Brute::Prompts.render("identity", provider_name: "anthropic").should ==
+      Brute::Prompts.read("identity", "anthropic")
+  end
+
+  it "returns nil for a section with no template or text file" do
+    Brute::Prompts.render("no_such_section_anywhere", provider_name: "x").should.be.nil
   end
 end

data/lib/brute/prompts/skills.rb

@@ -5,22 +5,20 @@ require "brute"
 
 module Brute
   module Prompts
+    # The <available_skills> system-prompt section.
+    #
+    # Uses skill objects from ctx[:skills] when present (handed in via
+    # Brute::Middleware::Skills -> env[:metadata][:skills]); falls back to
+    # scanning from ctx[:cwd] so the default stacks keep working unwired.
+    # Skills with disable_model_invocation? are loaded but hidden here.
+    # Returns nil when no skills are visible, dropping the section entirely.
     module Skills
       def self.call(ctx)
-        cwd = ctx[:cwd] || Dir.pwd
-        skills = Brute::Skill.all(cwd: cwd)
-        return nil if skills.empty?
+        skills = ctx[:skills] || Brute::Skill.all(cwd: ctx[:cwd] || Dir.pwd)
+        visible = skills.reject(&:disable_model_invocation?)
+        return nil if visible.empty?
 
-        listing = Brute::Skill.fmt(skills)
-
-        <<~TXT
-          Skills provide specialized instructions and workflows for specific tasks.
-          Use the skill tool to load a skill when a task matches its description. The tool
-          returns the skill's full instructions plus a base directory whose bundled files
-          (scripts, references, assets) you can read or run by relative path.
-
-          #{listing}
-        TXT
+        Prompts.render("skills", ctx.merge(skills: visible))
       end
     end
   end
@@ -31,9 +29,49 @@ __END__
 describe "brute/prompts/skills" do
   require "tmpdir"
 
+  def skill(name, description: "Does things", file_path: "/x/#{name}/SKILL.md", hidden: false)
+    Brute::Skill.new(
+      name: name, description: description, file_path: file_path,
+      disable_model_invocation: hidden,
+    )
+  end
+
   it "returns nil when no skills are found" do
     Dir.mktmpdir do |dir|
       Brute::Prompts::Skills.call(cwd: dir).should.be.nil
     end
   end
+
+  it "renders skill objects passed through ctx" do
+    out = Brute::Prompts::Skills.call(skills: [skill("debugging", description: "Debug things")])
+    out.should.include("<name>debugging</name>")
+    out.should.include("<description>Debug things</description>")
+    out.should.include("<location>/x/debugging/SKILL.md</location>")
+  end
+
+  it "prefers ctx[:skills] over scanning, even when empty" do
+    Dir.mktmpdir do |dir|
+      skill_dir = File.join(dir, ".brute", "skills", "debugging")
+      FileUtils.mkdir_p(skill_dir)
+      File.write(File.join(skill_dir, "SKILL.md"), "---\nname: debugging\ndescription: x\n---\n\nBody\n")
+
+      Brute::Prompts::Skills.call(cwd: dir, skills: []).should.be.nil
+      Brute::Prompts::Skills.call(cwd: dir).should.include("debugging")
+    end
+  end
+
+  it "hides disable-model-invocation skills from the listing" do
+    out = Brute::Prompts::Skills.call(skills: [skill("shown"), skill("hidden", hidden: true)])
+    out.should.include("shown")
+    out.should.not.include("hidden")
+  end
+
+  it "returns nil when every skill is hidden" do
+    Brute::Prompts::Skills.call(skills: [skill("hidden", hidden: true)]).should.be.nil
+  end
+
+  it "xml-escapes skill fields" do
+    out = Brute::Prompts::Skills.call(skills: [skill("debugging", description: %q{a<b>&"c'})])
+    out.should.include("a&lt;b&gt;&amp;&quot;c&apos;")
+  end
 end

data/lib/brute/prompts/text/skills/default.erb

@@ -0,0 +1,14 @@
+Skills provide specialized instructions and workflows for specific tasks.
+When a task matches a skill's description, read the file at its location for the
+full instructions. Relative paths in a skill resolve against its directory (the
+parent of its SKILL.md).
+
+<available_skills>
+<% skills.each do |skill| -%>
+  <skill>
+    <name><%= h skill.name %></name>
+    <description><%= h skill.description %></description>
+    <location><%= h skill.file_path %></location>
+  </skill>
+<% end -%>
+</available_skills>

data/lib/brute/skill.rb

@@ -6,7 +6,7 @@ require "bundler/setup"
 require "brute"
 
 module Brute
-  # Discovers, validates, and loads SKILL.md files from standard directories.
+  # A single skill: metadata plus the address of its SKILL.md on disk.
   #
   # A skill is a directory containing a SKILL.md markdown file with YAML
   # frontmatter:
@@ -18,71 +18,60 @@ module Brute
   #
   #   When debugging, follow these steps...
   #
-  # Skills are scanned from (in order):
-  #   1. .brute/skills/**/SKILL.md   (project-local)
-  #   2. ~/.config/brute/skills/**/SKILL.md (global)
+  # The object is a value object — it carries the parsed frontmatter, the
+  # body, and the file location, nothing else. Modeled on prime-agent's
+  # BaseSkill (packages/coding-agent/src/core/skills.ts).
   #
-  # Parsing and validation mirror the Agent Skills specification
-  # (https://agentskills.io/specification) and its reference validator
-  # (https://github.com/agentskills/agentskills/tree/main/skills-ref). A skill
-  # whose frontmatter violates a rule is skipped with a stderr warning naming
-  # the violated rule, never raised.
+  # Discovery is class-level and caller-side: Skill.all scans (in order)
+  #   1. <cwd>/.brute/skills/**/SKILL.md   (project-local, :project)
+  #   2. ~/.config/brute/skills/**/SKILL.md (global, :user)
+  #   3. explicit paths: (dirs or .md files, :path)
+  #
+  # First found wins on name collisions (with a stderr warning naming winner
+  # and loser), and the same file reached twice via symlinks is skipped.
   #
-  module Skill
-    Info = Struct.new(
-      :name, :description, :location, :content,
-      :license, :compatibility, :metadata, :allowed_tools,
-      keyword_init: true,
-    )
+  # Parsing and validation mirror the Agent Skills specification
+  # (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
 
     FILENAME = "SKILL.md"
 
     # Frontmatter keys permitted by the spec. Anything else is a violation.
-    ALLOWED_FIELDS = %w[name description license allowed-tools metadata compatibility].freeze
+    ALLOWED_FIELDS = %w[name description license allowed-tools metadata compatibility disable-model-invocation].freeze
 
     MAX_NAME_LENGTH = 64
     MAX_DESCRIPTION_LENGTH = 1024
     MAX_COMPATIBILITY_LENGTH = 500
 
-    # Scan all skill directories and return an array of Info structs.
-    def self.all(cwd: Dir.pwd)
-      skills = {}
-
-      scan_dirs(cwd).each do |dir|
-        Dir.glob(File.join(dir, "**", FILENAME)).sort.each do |path|
-          info = load(path)
-          next unless info
-          # First found wins (project-local overrides global)
-          skills[info.name] ||= info
-        end
-      end
-
-      skills.values.sort_by(&:name)
+    def initialize(name:, description:, file_path:, content: nil, source: :path,
+                   license: nil, compatibility: nil, metadata: nil,
+                   allowed_tools: nil, disable_model_invocation: false)
+      @name = name
+      @description = description
+      @file_path = file_path
+      @base_dir = File.dirname(file_path)
+      @content = content
+      @source = source
+      @license = license
+      @compatibility = compatibility
+      @metadata = metadata
+      @allowed_tools = allowed_tools
+      @disable_model_invocation = disable_model_invocation
     end
 
-    # Get a single skill by name.
-    def self.get(name, cwd: Dir.pwd)
-      all(cwd: cwd).detect { |s| s.name == name }
-    end
+    # Hidden from the prompt listing (explicit invocation only), but still
+    # handed to the agent as an object.
+    def disable_model_invocation? = @disable_model_invocation
 
-    # Format skills as XML for the system prompt.
-    def self.fmt(skills)
-      return nil if skills.empty?
+    # Back-compat alias (Tools::SkillLoad era).
+    def location = file_path
 
-      lines = ["<available_skills>"]
-      skills.each do |skill|
-        lines << "  <skill>"
-        lines << "    <name>#{skill.name}</name>"
-        lines << "    <description>#{skill.description}</description>"
-        lines << "  </skill>"
-      end
-      lines << "</available_skills>"
-      lines.join("\n")
-    end
-
-    # Parse and validate a SKILL.md file into an Info struct.
+    # Parse and validate a SKILL.md file into a Skill.
     # Returns nil (with a stderr warning) if the file is invalid.
-    def self.load(path)
+    def self.load(path, source: :path)
       raw = File.read(path)
       frontmatter, content = parse_frontmatter(path, raw)
       return nil unless frontmatter
@@ -105,21 +94,86 @@ module Brute
         return nil
       end
 
-      Info.new(
+      new(
         name: frontmatter["name"].to_s.strip,
         description: frontmatter["description"].to_s.strip,
-        location: path,
+        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,
       )
     rescue => e
       warn "Failed to load skill #{path}: #{e.message}"
       nil
     end
 
+    # Scan all skill directories and return an array of Skills, sorted by name.
+    #
+    # Precedence is first-found-wins: project-local overrides global overrides
+    # explicit paths. Name collisions warn to stderr naming winner and loser;
+    # the same file reached via different symlinks is loaded only once.
+    def self.all(cwd: Dir.pwd, paths: [])
+      skills = {}
+      seen_files = {}
+
+      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
+        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")
+      glob(global) { |path| add.call(path, :user) }
+
+      paths.each do |raw|
+        path = File.expand_path(raw.to_s.sub(/\A~(?=\/|\z)/, Dir.home))
+        if File.directory?(path)
+          glob(path) { |p| add.call(p, :path) }
+        elsif File.file?(path) && path.end_with?(".md")
+          add.call(path, :path)
+        else
+          warn "Skill path #{path} is not a directory or markdown file (ignored)"
+        end
+      end
+
+      skills.values.sort_by(&:name)
+    end
+
+    # Get a single skill by name through the same scan as .all.
+    def self.get(name, cwd: Dir.pwd, paths: [])
+      all(cwd: cwd, paths: paths).detect { |s| s.name == name }
+    end
+
+    def self.glob(dir, &block)
+      return unless File.directory?(dir)
+
+      Dir.glob(File.join(dir, "**", FILENAME)).sort.each(&block)
+    end
+
+    def self.realpath(path)
+      File.realpath(path)
+    rescue SystemCallError
+      path
+    end
+
     # 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)
@@ -168,21 +222,6 @@ module Brute
       value.to_s.split(/\s+/).reject(&:empty?)
     end
 
-    # Directories to scan for skills, in priority order.
-    def self.scan_dirs(cwd)
-      dirs = []
-
-      # Project-local
-      project = File.join(cwd, ".brute", "skills")
-      dirs << project if File.directory?(project)
-
-      # Global
-      global = File.join(Dir.home, ".config", "brute", "skills")
-      dirs << global if File.directory?(global)
-
-      dirs
-    end
-
     # Split YAML frontmatter from markdown body.
     # Returns [hash, string] or [nil, nil].
     def self.parse_frontmatter(path, raw)
@@ -200,8 +239,8 @@ module Brute
       [nil, nil]
     end
 
-    private_class_method :scan_dirs, :parse_frontmatter,
-                         :validate, :validate_name, :validate_description, :parse_allowed_tools
+    private_class_method :glob, :realpath, :validate, :validate_name,
+                         :validate_description, :parse_allowed_tools, :parse_frontmatter
   end
 end
 
@@ -222,9 +261,19 @@ describe "brute/skill" do
   it "loads a valid skill" do
     Dir.mktmpdir do |root|
       path = make_skill_dir(root, "debugging", "name: debugging\ndescription: Debug things")
-      info = Brute::Skill.load(path)
-      info.name.should == "debugging"
-      info.description.should == "Debug things"
+      skill = Brute::Skill.load(path)
+      skill.name.should == "debugging"
+      skill.description.should == "Debug things"
+    end
+  end
+
+  it "exposes file_path, base_dir, and a location alias" do
+    Dir.mktmpdir do |root|
+      path = make_skill_dir(root, "debugging", "name: debugging\ndescription: x")
+      skill = Brute::Skill.load(path)
+      skill.file_path.should == path
+      skill.base_dir.should == File.dirname(path)
+      skill.location.should == path
     end
   end
 
@@ -266,9 +315,9 @@ describe "brute/skill" do
   it "loads a skill with an unexpected frontmatter field, dropping the extra" do
     Dir.mktmpdir do |root|
       path = make_skill_dir(root, "extra", "name: extra\ndescription: x\ntags: [a, b]")
-      info = Brute::Skill.load(path)
-      info.name.should == "extra"
-      info.respond_to?(:tags).should.be.false
+      skill = Brute::Skill.load(path)
+      skill.name.should == "extra"
+      skill.respond_to?(:tags).should.be.false
     end
   end
 
@@ -278,11 +327,25 @@ describe "brute/skill" do
         root, "full",
         "name: full\ndescription: x\nlicense: MIT\ncompatibility: claude\nallowed-tools: read shell\nmetadata:\n  team: core",
       )
-      info = Brute::Skill.load(path)
-      info.license.should == "MIT"
-      info.compatibility.should == "claude"
-      info.allowed_tools.should == %w[read shell]
-      info.metadata.should == { "team" => "core" }
+      skill = Brute::Skill.load(path)
+      skill.license.should == "MIT"
+      skill.compatibility.should == "claude"
+      skill.allowed_tools.should == %w[read shell]
+      skill.metadata.should == { "team" => "core" }
+    end
+  end
+
+  it "parses disable-model-invocation" do
+    Dir.mktmpdir do |root|
+      path = make_skill_dir(root, "hidden", "name: hidden\ndescription: x\ndisable-model-invocation: true")
+      Brute::Skill.load(path).disable_model_invocation?.should.be.true
+    end
+  end
+
+  it "defaults disable_model_invocation to false" do
+    Dir.mktmpdir do |root|
+      path = make_skill_dir(root, "shown", "name: shown\ndescription: x")
+      Brute::Skill.load(path).disable_model_invocation?.should.be.false
     end
   end
 
@@ -292,4 +355,72 @@ describe "brute/skill" do
       Brute::Skill.load(path).should.be.nil
     end
   end
+
+  it "tags skills with their source" do
+    Dir.mktmpdir do |root|
+      make_skill_dir(root, "debugging", "name: debugging\ndescription: x")
+      Brute::Skill.all(cwd: root).first.source.should == :project
+    end
+  end
+
+  def with_home(dir)
+    old = ENV["HOME"]
+    ENV["HOME"] = dir
+    yield
+  ensure
+    ENV["HOME"] = old
+  end
+
+  it "project-local skills override same-named global ones" do
+    Dir.mktmpdir do |project|
+      Dir.mktmpdir do |home|
+        make_skill_dir(project, "shared", "name: shared\ndescription: project variant")
+        global_dir = File.join(home, ".config", "brute", "skills", "shared")
+        FileUtils.mkdir_p(global_dir)
+        File.write(File.join(global_dir, "SKILL.md"), "---\nname: shared\ndescription: global variant\n---\n\nBody\n")
+
+        with_home(home) do
+          skills = Brute::Skill.all(cwd: project)
+          skills.size.should == 1
+          skills.first.description.should == "project variant"
+          skills.first.source.should == :project
+        end
+      end
+    end
+  end
+
+  it "loads skills from explicit paths" do
+    Dir.mktmpdir do |root|
+      dir = File.join(root, "elsewhere", "custom")
+      FileUtils.mkdir_p(dir)
+      File.write(File.join(dir, "SKILL.md"), "---\nname: custom\ndescription: explicit\n---\n\nBody\n")
+
+      skills = Brute::Skill.all(cwd: root, paths: [File.join(root, "elsewhere")])
+      skills.map(&:name).should == ["custom"]
+      skills.first.source.should == :path
+    end
+  end
+
+  it "expands ~ in explicit paths" do
+    Dir.mktmpdir do |home|
+      dir = File.join(home, "skills", "homey")
+      FileUtils.mkdir_p(dir)
+      File.write(File.join(dir, "SKILL.md"), "---\nname: homey\ndescription: x\n---\n\nBody\n")
+
+      with_home(home) do
+        skills = Brute::Skill.all(cwd: home, paths: ["~/skills"])
+        skills.map(&:name).should.include("homey")
+      end
+    end
+  end
+
+  it "loads the same file only once when reached via a symlink" do
+    Dir.mktmpdir do |root|
+      make_skill_dir(root, "debugging", "name: debugging\ndescription: x")
+      link = File.join(root, ".brute", "skills", "linked")
+      File.symlink(File.join(root, ".brute", "skills", "debugging"), link)
+
+      Brute::Skill.all(cwd: root).size.should == 1
+    end
+  end
 end

data/lib/brute/turn/agent_pipeline.rb

@@ -45,10 +45,15 @@ module Brute
           events:            events,
           metadata:          {},
           current_iteration: 1,
+          hooks:             hooks,
         }
-        env.tap do
+        hooks.emit(:turn_start, env)
+        begin
           build.call(env)
+        ensure
+          hooks.emit(:turn_end, env)
         end
+        env
       end
 
       private
@@ -119,6 +124,27 @@ describe "brute/turn/agent_pipeline" do
     agent.start("hi")[:messages].last.content.should == "from ru"
   end
 
+  it ".on chains off the builder and fires turn hooks around the turn" do
+    fired = []
+    agent = Brute.agent
+      .run(->(env) { env[:messages].assistant("done") })
+      .on(:turn_start) { |env| fired << [:start, env[:messages].last.content] }
+      .on(:turn_end) { |env| fired << [:end, env[:messages].last.content] }
+
+    env = agent.start("go")
+    env[:messages].last.content.should == "done"
+    fired.should == [[:start, "go"], [:end, "done"]]
+  end
+
+  it "fires turn_end on error (ensure)" do
+    fired = []
+    agent = Brute.agent
+      .run(->(_env) { raise "boom" })
+      .on(:turn_end) { |_env| fired << :end }
+
+    lambda { agent.start("go") }.should.raise(RuntimeError)
+    fired.should == [:end]
+  end
   it "use in a ru string wraps the terminal" do
     script = <<~RUBY
       use AgentStubMW

data/lib/brute/turn/pipeline.rb

@@ -19,6 +19,16 @@ module Brute
         #
         def use(...) = tap { super }
         def run(...) = tap { super }
+
+        # Subscribe a lifecycle hook (see Brute::Hooks):
+        #
+        #   Brute.agent
+        #     .use(MaxProfit)
+        #     .run(->(env) { ... })
+        #     .on(:before_llm) { |env| ... }
+        #     .on(:approve_tool) { |call| call[:name] != "exec" }
+        #
+        def on(...) = tap { hooks.on(...) }
       end
 
       include Chainable
@@ -40,6 +50,11 @@ module Brute
       # when `run` was never called.
       alias_method :build, :to_app
 
+      # The lifecycle-hook registry for this pipeline (see Brute::Hooks).
+      def hooks
+        @hooks ||= Brute::Hooks.new
+      end
+
       # Default null sink for env[:events] — swallows anything pushed to it.
       class NullSink
         def <<(_event); self; end

data/lib/brute/version.rb

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

data/lib/brute/version.rb.erb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Brute
+  VERSION = "<%= version %>"
+end