brute 3.2.2 → 4.1.0

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,43 @@ describe "brute/turn/agent_pipeline" do
     agent.start("hi")[:messages].last.content.should == "from ru"
   end
 
+  it "Brute.load_agent loads an agent from a .ru file and starts it" do
+    require "tmpdir"
+    Dir.mktmpdir do |dir|
+      path = File.join(dir, "agent.ru")
+      File.write(path, 'run ->(env) { env[:messages].assistant("from file") }')
+
+      agent = Brute.load_agent(path)
+      agent.should.be.kind_of?(Brute::Turn::AgentPipeline)
+      agent.start("hi")[:messages].last.content.should == "from file"
+    end
+  end
+
+  it "Brute.load_agent raises for a missing file" do
+    lambda { Brute.load_agent("definitely/not/here.ru") }.should.raise(ArgumentError)
+  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.2"
+  VERSION = "4.1.0"
 end

data/lib/brute/version.rb.erb

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

data/lib/brute.rb

@@ -57,6 +57,22 @@ module Brute
     Brute::Turn::AgentPipeline.new(&block)
   end
 
+  # Load an agent from a brute.ru file — the Brute analogue of `rackup`.
+  # The file is a rackup-style script using the same `use` / `run` / `map`
+  # DSL as `Brute.agent`, and what comes back is the AgentPipeline itself,
+  # so it can be started, further `.use`d, or served through
+  # Brute::Rack::Adapter:
+  #
+  #   Brute.load_agent.start("what changed?")               # ./agent.ru
+  #   Brute.load_agent("examples/agents/brute.ru").start("hi")
+  #
+  def self.load_agent(path = "agent.ru")
+    path = File.expand_path(path)
+    raise ArgumentError, "no such agent file: #{path}" unless File.file?(path)
+
+    Brute::Turn::AgentPipeline.parse_file(path)
+  end
+
   # Adapt any Brute tools (hashes, Brute::Tool, Brute::Turn::ToolPipeline,
   # SubAgent …) into a { name_sym => Brute::Tools::Adapter } hash. Each
   # adapter exposes #to_h — a neutral JSON-Schema-ish definition the inline

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: brute
 version: !ruby/object:Gem::Version
-  version: 3.2.2
+  version: 4.1.0
 platform: ruby
 authors:
 - Brute Contributors
@@ -37,6 +37,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: file-tail
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
@@ -163,6 +177,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: gem_kit-release
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
 description: Production-grade coding agent with tool execution, middleware pipeline,
   context compaction, session persistence, and multi-provider LLM support.
 executables: []
@@ -170,9 +198,14 @@ extensions: []
 extra_rdoc_files: []
 files:
 - lib/brute.rb
+- lib/brute/changelog.rb
+- lib/brute/completion/open_router.rb
+- lib/brute/contrib/log_file.rb
+- lib/brute/deprecate.rb
 - lib/brute/events/handler.rb
 - lib/brute/events/prefixed_terminal_output.rb
 - lib/brute/events/terminal_output_handler.rb
+- lib/brute/hooks.rb
 - lib/brute/message_transport.rb
 - lib/brute/message_transport/anthropic.rb
 - lib/brute/message_transport/llm.rb
@@ -190,6 +223,7 @@ files:
 - lib/brute/middleware/010_max_iterations.rb
 - lib/brute/middleware/015_otel_token_usage.rb
 - lib/brute/middleware/020_system_prompt.rb
+- lib/brute/middleware/025_skills.rb
 - lib/brute/middleware/040_compaction_check.rb
 - lib/brute/middleware/060_questions.rb
 - lib/brute/middleware/070_tool_pipeline.rb
@@ -198,6 +232,7 @@ files:
 - lib/brute/middleware/event_handler.rb
 - lib/brute/middleware/open_router.rb
 - lib/brute/middleware/user_queue.rb
+- lib/brute/prompt_template.rb
 - lib/brute/prompts.rb
 - lib/brute/prompts/autonomy.rb
 - lib/brute/prompts/base.rb
@@ -231,6 +266,7 @@ files:
 - lib/brute/prompts/text/identity/default.txt
 - lib/brute/prompts/text/identity/google.txt
 - lib/brute/prompts/text/identity/openai.txt
+- lib/brute/prompts/text/skills/default.erb
 - lib/brute/prompts/text/tone_and_style/anthropic.txt
 - lib/brute/prompts/text/tone_and_style/default.txt
 - lib/brute/prompts/text/tone_and_style/google.txt
@@ -268,6 +304,7 @@ files:
 - lib/brute/turn/tool_pipeline.rb
 - lib/brute/utils/diff.rb
 - lib/brute/version.rb
+- lib/brute/version.rb.erb
 - lib/brute_cli/providers/shell.rb
 - lib/brute_cli/providers/shell_response.rb
 homepage: https://github.com/general-intelligence-systems/brute