brute 2.0.5 → 3.0.0

data/lib/brute/skill.rb

@@ -2,10 +2,14 @@
 
 require "yaml"
 
+require "bundler/setup"
+require "brute"
+
 module Brute
-  # Discovers and loads SKILL.md files from standard directories.
+  # Discovers, validates, and loads SKILL.md files from standard directories.
   #
-  # A skill is a markdown file with YAML frontmatter:
+  # A skill is a directory containing a SKILL.md markdown file with YAML
+  # frontmatter:
   #
   #   ---
   #   name: debugging
@@ -18,14 +22,28 @@ module Brute
   #   1. .brute/skills/**/SKILL.md   (project-local)
   #   2. ~/.config/brute/skills/**/SKILL.md (global)
   #
-  # The directory name containing SKILL.md becomes the skill name if frontmatter
-  # doesn't specify one.
+  # 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.
   #
   module Skill
-    Info = Struct.new(:name, :description, :location, :content, keyword_init: true)
+    Info = Struct.new(
+      :name, :description, :location, :content,
+      :license, :compatibility, :metadata, :allowed_tools,
+      keyword_init: true,
+    )
 
     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
+
+    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 = {}
@@ -62,28 +80,94 @@ module Brute
       lines.join("\n")
     end
 
-    # Parse a SKILL.md file into an Info struct.
-    # Returns nil if the file is invalid or missing required fields.
+    # Parse and validate a SKILL.md file into an Info struct.
+    # Returns nil (with a stderr warning) if the file is invalid.
     def self.load(path)
       raw = File.read(path)
-      frontmatter, content = parse_frontmatter(raw)
+      frontmatter, content = parse_frontmatter(path, raw)
       return nil unless frontmatter
 
-      name = frontmatter["name"] || File.basename(File.dirname(path))
-      description = frontmatter["description"]
-      return nil unless description && !description.strip.empty?
+      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
 
       Info.new(
-        name: name.to_s.strip,
-        description: description.to_s.strip,
+        name: frontmatter["name"].to_s.strip,
+        description: frontmatter["description"].to_s.strip,
         location: path,
         content: content.to_s.strip,
+        license: frontmatter["license"]&.to_s,
+        compatibility: frontmatter["compatibility"]&.to_s,
+        metadata: frontmatter["metadata"],
+        allowed_tools: parse_allowed_tools(frontmatter["allowed-tools"]),
       )
     rescue => e
       warn "Failed to load skill #{path}: #{e.message}"
       nil
     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)
+      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
+
+      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
+    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
+
+      []
+    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?)
+    end
+
     # Directories to scan for skills, in priority order.
     def self.scan_dirs(cwd)
       dirs = []
@@ -101,7 +185,7 @@ module Brute
 
     # Split YAML frontmatter from markdown body.
     # Returns [hash, string] or [nil, nil].
-    def self.parse_frontmatter(raw)
+    def self.parse_frontmatter(path, raw)
       return [nil, nil] unless raw.start_with?("---")
 
       parts = raw.split(/^---\s*$/, 3)
@@ -111,8 +195,101 @@ module Brute
       return [nil, nil] unless frontmatter.is_a?(Hash)
 
       [frontmatter, parts[2]]
+    rescue => e
+      warn "Failed to parse frontmatter in #{path}: #{e.message}"
+      [nil, nil]
+    end
+
+    private_class_method :scan_dirs, :parse_frontmatter,
+                         :validate, :validate_name, :validate_description, :parse_allowed_tools
+  end
+end
+
+__END__
+
+describe "brute/skill" do
+  require "tmpdir"
+  require "fileutils"
+
+  def make_skill_dir(root, dir_name, frontmatter, body: "Body.")
+    dir = File.join(root, ".brute", "skills", dir_name)
+    FileUtils.mkdir_p(dir)
+    path = File.join(dir, "SKILL.md")
+    File.write(path, "---\n#{frontmatter}\n---\n\n#{body}\n")
+    path
+  end
+
+  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"
+    end
+  end
+
+  it "defaults the name to the directory when omitted" do
+    Dir.mktmpdir do |root|
+      path = make_skill_dir(root, "deploy", "description: Deploy things")
+      Brute::Skill.load(path).name.should == "deploy"
+    end
+  end
+
+  it "skips a skill whose name does not match its directory" do
+    Dir.mktmpdir do |root|
+      path = make_skill_dir(root, "deploy", "name: shipit\ndescription: Ship it")
+      Brute::Skill.load(path).should.be.nil
+    end
+  end
+
+  it "skips a skill with an uppercase name" do
+    Dir.mktmpdir do |root|
+      path = make_skill_dir(root, "Deploy", "name: Deploy\ndescription: Deploy")
+      Brute::Skill.load(path).should.be.nil
+    end
+  end
+
+  it "skips a skill with consecutive hyphens in the name" do
+    Dir.mktmpdir do |root|
+      path = make_skill_dir(root, "a--b", "name: a--b\ndescription: nope")
+      Brute::Skill.load(path).should.be.nil
+    end
+  end
+
+  it "skips a skill without a description" do
+    Dir.mktmpdir do |root|
+      path = make_skill_dir(root, "nodesc", "name: nodesc")
+      Brute::Skill.load(path).should.be.nil
+    end
+  end
+
+  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
     end
+  end
 
-    private_class_method :scan_dirs, :parse_frontmatter
+  it "parses optional spec fields" do
+    Dir.mktmpdir do |root|
+      path = make_skill_dir(
+        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" }
+    end
+  end
+
+  it "skips a skill whose description exceeds the length bound" do
+    Dir.mktmpdir do |root|
+      path = make_skill_dir(root, "long", "name: long\ndescription: #{"x" * 1025}")
+      Brute::Skill.load(path).should.be.nil
+    end
   end
 end

data/lib/brute/system_prompt.rb

@@ -180,6 +180,8 @@ module Brute
   end
 end
 
-test do
+__END__
+
+describe "brute/system_prompt" do
   # not implemented
 end

data/lib/brute/tools/adapter.rb

@@ -0,0 +1,296 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+
+module Brute
+  module Tools
+    # Normalizes any tool shape into one neutral interface so the rest of
+    # Brute never has to care which tools library (if any) a tool was
+    # written with.
+    #
+    # This solves three problems:
+    #
+    # 1. Using any tools library — anything that quacks like a tool
+    #    (RubyLLM::Tool today, others via their own adapters) is wrapped
+    #    into the same interface.
+    # 2. Avoiding tool libraries entirely — Brute::Turn::ToolPipeline and
+    #    Tools::SubAgent work without inheriting from a library class.
+    # 3. Quickly adding tools — a plain Hash with a proc is enough:
+    #
+    #      Brute::Tools::Adapter.wrap(
+    #        name:        "echo",
+    #        description: "Echo the input back",
+    #        params:      { msg: { type: "string", required: true } },
+    #        execute:     ->(msg:) { msg },
+    #      )
+    #
+    # The neutral interface:
+    #
+    #   adapter.name        # String
+    #   adapter.description # String
+    #   adapter.params      # { key => { type:, desc:, required: } }
+    #   adapter.call(args)  # execute with a (string- or symbol-keyed) Hash
+    #
+    # Completion middlewares convert adapters into whatever their LLM
+    # library expects (e.g. #to_ruby_llm); ToolPipeline executes them via #call.
+    #
+    class Adapter
+      attr_reader :name, :description, :params
+
+      # Wrap a single tool of any supported shape. Idempotent.
+      def self.wrap(tool)
+        return tool if tool.is_a?(Adapter)
+
+        tool = tool.new if tool.is_a?(Class)
+
+        case tool
+        when Hash                then from_hash(tool)
+        when ::RubyLLM::Tool     then from_ruby_llm(tool)
+        when Brute::Tools::SubAgent then new(
+          name:        tool.name,
+          description: tool.description,
+          params:      tool.params,
+          handler:     ->(**args) { tool.execute(args) },
+          original:    tool,
+        )
+        when Brute::Turn::ToolPipeline then new(
+          name:        tool.name,
+          description: tool.description,
+          params:      tool.params,
+          handler:     ->(**args) { tool.call(**args) },
+          original:    tool,
+        )
+        else
+          from_duck_type(tool)
+        end
+      end
+
+      # Wrap a list of tools into a { name_sym => adapter } lookup hash —
+      # the shape ToolPipeline works with.
+      def self.wrap_all(tools)
+        Array(tools).each_with_object({}) do |tool, hash|
+          adapter = wrap(tool)
+          hash[adapter.name.to_sym] = adapter
+        end
+      end
+
+      # Quick inline tool: { name:, description:, params:, execute: }
+      def self.from_hash(definition)
+        definition = definition.transform_keys(&:to_sym)
+        handler = definition.fetch(:execute) { definition[:handler] }
+        raise ArgumentError, "inline tool needs an :execute proc" unless handler.respond_to?(:call)
+
+        new(
+          name:        definition.fetch(:name).to_s,
+          description: definition.fetch(:description, ""),
+          params:      definition.fetch(:params, {}),
+          handler:     ->(**args) { handler.call(**args) },
+          original:    definition,
+        )
+      end
+
+      # A RubyLLM::Tool instance (the library's own arg normalization and
+      # validation stays in play via tool.call). Tools declared with the
+      # params(...) schema DSL keep their full JSON schema.
+      def self.from_ruby_llm(tool)
+        params = tool.parameters.each_with_object({}) do |(key, param), hash|
+          hash[key.to_sym] = { type: param.type, desc: param.description, required: param.required }.compact
+        end
+
+        new(
+          name:        tool.name.to_s,
+          description: tool.description,
+          params:      params,
+          schema:      (tool.params_schema if tool.respond_to?(:params_schema)),
+          handler:     ->(**args) { tool.call(args) },
+          original:    tool,
+        )
+      end
+
+      # Anything tool-shaped: needs #name and #call or #execute. Honors
+      # #to_ruby_llm for backward compatibility with existing adapters.
+      def self.from_duck_type(tool)
+        return from_ruby_llm(tool.to_ruby_llm) if tool.respond_to?(:to_ruby_llm)
+
+        unless tool.respond_to?(:name) && (tool.respond_to?(:call) || tool.respond_to?(:execute))
+          raise ArgumentError, "don't know how to adapt #{tool.inspect} into a tool"
+        end
+
+        entry = tool.respond_to?(:execute) ? tool.method(:execute) : tool.method(:call)
+        new(
+          name:        tool.name.to_s,
+          description: tool.respond_to?(:description) ? tool.description : "",
+          params:      tool.respond_to?(:params) ? tool.params : {},
+          handler:     ->(**args) { entry.call(**args) },
+          original:    tool,
+        )
+      end
+
+      def initialize(name:, description:, params:, handler:, schema: nil, original: nil)
+        @name        = name
+        @description = description
+        @params      = params || {}
+        @schema      = schema
+        @handler     = handler
+        @original    = original
+      end
+
+      # The tool object this adapter wraps (RubyLLM::Tool, Brute::Turn::ToolPipeline,
+      # SubAgent, Hash definition, ...).
+      attr_reader :original
+
+      # Execute the tool. Accepts string- or symbol-keyed argument hashes,
+      # as delivered by LLM providers.
+      def call(arguments = {})
+        args = arguments.to_h.transform_keys(&:to_sym)
+        @handler.call(**args)
+      end
+
+      # Convert to a RubyLLM::Tool so ruby_llm-backed completion can hand
+      # the tool to its providers. Returns the wrapped tool untouched when
+      # it already is one.
+      def to_ruby_llm
+        return @original if @original.is_a?(::RubyLLM::Tool)
+
+        adapter = self
+        Class.new(::RubyLLM::Tool) do
+          description adapter.description
+          adapter.params.each { |key, opts| param key, **opts.slice(:type, :desc, :required) }
+          define_method(:name) { adapter.name }
+          define_method(:execute) { |**args| adapter.call(args) }
+        end.new
+      end
+
+      # Library-neutral tool definition (JSON-Schema-ish), for completion
+      # middlewares that talk to an HTTP API directly.
+      def to_h
+        return { name: @name, description: @description, parameters: @schema.deep_symbolize_keys } if @schema
+
+        properties = @params.transform_values do |opts|
+          {
+            type:        opts[:type] || "string",
+            description: opts[:desc] || opts[:description],
+            items:       opts[:items],
+            enum:        opts[:enum],
+          }.compact
+        end
+        required = @params.select { |_k, opts| opts[:required] }.keys
+
+        {
+          name:        @name,
+          description: @description,
+          parameters: {
+            type:       "object",
+            properties: properties,
+            required:   required.map(&:to_s),
+          },
+        }
+      end
+    end
+  end
+end
+
+__END__
+
+describe "brute/tools/adapter" do
+  it "wraps a RubyLLM::Tool class" do
+    klass = Class.new(::RubyLLM::Tool) do
+      description "test tool"
+      param :input, type: "string", desc: "the input"
+      def name; "rl_tool"; end
+      def execute(input:); "got #{input}"; end
+    end
+
+    adapter = Brute::Tools::Adapter.wrap(klass)
+    adapter.name.should == "rl_tool"
+    adapter.description.should == "test tool"
+    adapter.params[:input][:type].should == "string"
+    adapter.call("input" => "x").should == "got x"
+  end
+
+  it "wraps a Brute::Turn::ToolPipeline" do
+    t = Brute::Turn::ToolPipeline.new(name: "echo", description: "echo input") do
+      run ->(env) { env[:result] = env[:arguments][:msg] }
+    end
+
+    adapter = Brute::Tools::Adapter.wrap(t)
+    adapter.name.should == "echo"
+    adapter.call(msg: "hi").should == "hi"
+  end
+
+  it "wraps a SubAgent" do
+    sa = Brute::Tools::SubAgent.new(name: "research", description: "test") do
+      run ->(env) { env[:messages].assistant("result text") }
+    end
+
+    adapter = Brute::Tools::Adapter.wrap(sa)
+    adapter.name.should == "research"
+    adapter.call(task: "go").should == "result text"
+  end
+
+  it "wraps an inline hash definition" do
+    adapter = Brute::Tools::Adapter.wrap(
+      name:        "adder",
+      description: "Add two numbers",
+      params:      { a: { type: "number", required: true }, b: { type: "number", required: true } },
+      execute:     ->(a:, b:) { a + b },
+    )
+
+    adapter.name.should == "adder"
+    adapter.call(a: 1, b: 2).should == 3
+  end
+
+  it "is idempotent" do
+    adapter = Brute::Tools::Adapter.wrap(name: "x", description: "", execute: -> {})
+    Brute::Tools::Adapter.wrap(adapter).should == adapter
+  end
+
+  it "wrap_all keys adapters by name symbol" do
+    tools = Brute::Tools::Adapter.wrap_all([
+      { name: "a", description: "", execute: -> {} },
+      { name: "b", description: "", execute: -> {} },
+    ])
+    tools.keys.should == [:a, :b]
+    tools[:a].should.be.kind_of?(Brute::Tools::Adapter)
+  end
+
+  it "converts to a RubyLLM::Tool" do
+    adapter = Brute::Tools::Adapter.wrap(
+      name:        "echo",
+      description: "Echo",
+      params:      { msg: { type: "string", desc: "message", required: true } },
+      execute:     ->(msg:) { msg },
+    )
+
+    rl = adapter.to_ruby_llm
+    rl.should.be.kind_of?(::RubyLLM::Tool)
+    rl.name.should == "echo"
+    rl.call("msg" => "hello").should == "hello"
+  end
+
+  it "returns the original when it already is a RubyLLM::Tool" do
+    klass = Class.new(::RubyLLM::Tool) do
+      description "test tool"
+      def name; "original"; end
+      def execute; "ok"; end
+    end
+    instance = klass.new
+
+    Brute::Tools::Adapter.wrap(instance).to_ruby_llm.should == instance
+  end
+
+  it "produces a neutral JSON-schema-ish definition" do
+    adapter = Brute::Tools::Adapter.wrap(
+      name:        "echo",
+      description: "Echo",
+      params:      { msg: { type: "string", desc: "message", required: true } },
+      execute:     ->(msg:) { msg },
+    )
+
+    defn = adapter.to_h
+    defn[:name].should == "echo"
+    defn[:parameters][:properties][:msg][:type].should == "string"
+    defn[:parameters][:required].should == ["msg"]
+  end
+end

data/lib/brute/tools/fs/file_mutation_queue.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+
+module Brute
+  module Tools
+    # @namespace
+    module FS
+      # Per-file serialization queue for concurrent tool execution.
+      #
+      # When tools run in parallel (via threads or async fibers), multiple tools
+      # may target the same file simultaneously. Without serialization, a sequence
+      # like [read → patch → write] on the same file would race and lose edits.
+      #
+      # This module provides a single public method:
+      #
+      #   Brute::Tools::FS::FileMutationQueue.serialize("/path/to/file") do
+      #     # snapshot + read + modify + write — all atomic for this path
+      #   end
+      #
+      # Design (mirrors pi-mono's withFileMutationQueue):
+      #   - Operations on the SAME file are serialized (run one at a time)
+      #   - Operations on DIFFERENT files run fully in parallel (independent mutexes)
+      #   - Symlink-aware: resolves real paths so aliases share one mutex
+      #   - Error-safe: mutex is always released in `ensure`, so failures never deadlock
+      #   - Self-cleaning: per-file mutexes are removed when no longer in use
+      #
+      # Ruby 3.4's Mutex is fiber-scheduler-aware, so this works correctly with
+      # both :thread and :task (Async) concurrency strategies.
+      #
+      module FileMutationQueue
+        @mutexes = {}       # path → Mutex
+        @waiters = Hash.new(0) # path → number of threads/fibers waiting or holding
+        @guard = Mutex.new  # protects @mutexes and @waiters
+
+        class << self
+          # Serialize a block of work for a given file path.
+          #
+          # Concurrent calls targeting the same canonical path will execute
+          # sequentially in FIFO order. Calls targeting different paths
+          # proceed in parallel with zero contention.
+          #
+          # @parameter path [String] The file path to serialize on.
+          # @yields {block} The mutation work to perform (snapshot, read, write, etc.)
+          # @returns Whatever the block returns.
+          def serialize(path, &block)
+            key = canonical_path(path)
+            mutex = acquire_mutex(key)
+
+            mutex.synchronize(&block)
+          ensure
+            release_mutex(key)
+          end
+
+          # Clear all tracked mutexes. Used in tests and session resets.
+          def clear!
+            @guard.synchronize do
+              @mutexes.clear
+              @waiters.clear
+            end
+          end
+
+          # Number of file paths currently tracked (for diagnostics).
+          def size
+            @guard.synchronize { @mutexes.size }
+          end
+
+          private
+
+            # Resolve a file path to a canonical key.
+            # Uses File.realpath to follow symlinks so that aliases to the
+            # same underlying file share one mutex. Falls back to
+            # File.expand_path for files that don't exist yet (e.g., new writes).
+            def canonical_path(path)
+              resolved = File.expand_path(path)
+              begin
+                File.realpath(resolved)
+              rescue Errno::ENOENT
+                resolved
+              end
+            end
+
+            # Get (or create) a mutex for a file path and increment the waiter count.
+            def acquire_mutex(key)
+              @guard.synchronize do
+                @mutexes[key] ||= Mutex.new
+                @waiters[key] += 1
+                @mutexes[key]
+              end
+            end
+
+            # Decrement the waiter count and clean up the mutex if no one else needs it.
+            def release_mutex(key)
+              @guard.synchronize do
+                @waiters[key] -= 1
+                if @waiters[key] <= 0
+                  @mutexes.delete(key)
+                  @waiters.delete(key)
+                end
+              end
+            end
+        end
+      end
+    end
+  end
+end