brute 2.0.6 → 3.0.1

data/lib/brute/rack/adapter.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+require "json"
+
+module Brute
+  # The mirror image of protocol-rack. Where `Protocol::Rack::Adapter` wraps a
+  # *Rack app* so an HTTP server can drive it (env in, `[status, headers, body]`
+  # out), `Brute::Rack::Adapter` wraps a *Brute agent* so a Rack server can
+  # drive it. It is itself a Rack app — `call(env) -> [status, headers, body]` —
+  # so any AgentPipeline drops straight into a config.ru and serves over HTTP
+  # behind Falcon/Puma/etc:
+  #
+  #   # config.ru
+  #   agent = Brute::Turn::AgentPipeline.parse_file("examples/agents/brute.ru")
+  #   run Brute::Rack::Adapter.for(agent)
+  #
+  #   $ curl -d 'What files are here?' localhost:9292
+  #   $ curl -H 'content-type: application/json' -d '{"prompt":"hi"}' localhost:9292
+  #   $ curl 'localhost:9292/?prompt=hi'
+  #
+  # The whole job is two pure transforms — the two directions the request named:
+  #
+  #   env    -> prompt string      (#prompt_from)   the request half
+  #   output -> [status, headers, body] (#response_for) the response half
+  #
+  # `call` just wires them together around one `agent.start`.
+  module Rack
+    class Adapter
+      # Body/JSON keys we accept a prompt under, in priority order. `prompt`
+      # is canonical; `message`/`input` are common aliases.
+      PROMPT_KEYS = %w[prompt message input].freeze
+
+      # Convenience factory so the config.ru reads `run Adapter.for(agent)`.
+      def self.for(agent) = new(agent)
+
+      # @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)
+
+        @agent = agent
+      end
+
+      # Rack entry point. Extract the prompt, run one agent turn, render the
+      # assistant's reply back as an HTTP response. A missing prompt is a 400
+      # (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))
+      rescue => error
+        response_for(env, 500, error.message)
+      end
+
+      # env -> prompt string. Four ways in, most explicit first:
+      #
+      #   1. a `?prompt=` query param (never touches the body),
+      #   2. a JSON body — a known key of an object, or a bare JSON string,
+      #   3. a form-encoded `prompt=` field,
+      #   4. otherwise the raw request body IS the prompt.
+      #
+      # Returns nil when nothing usable is present.
+      def prompt_from(env)
+        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
+          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
+      # `Accept: application/json`) gets `{"response": "..."}` back; everything
+      # else gets `text/plain`. Errors ride the same path so a 500 body is
+      # shaped like a 200 body.
+      def response_for(env, status, output)
+        text = output.to_s
+
+        if wants_json?(env)
+          key = status == 200 ? :response : :error
+          [status, {"content-type" => "application/json"}, [::JSON.generate(key => text)]]
+        else
+          [status, {"content-type" => "text/plain; charset=utf-8"}, [text]]
+        end
+      end
+
+      private
+
+        # 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
+          messages&.last&.content.to_s
+        end
+
+        def read_body(request)
+          input = request.body
+          input&.read
+        rescue
+          nil
+        end
+
+        def json?(media_type)
+          media_type.to_s.include?("json")
+        end
+
+        def parse_json(body)
+          ::JSON.parse(body)
+        rescue ::JSON::ParserError
+          nil
+        end
+
+        # Prefer JSON when the client posted JSON or explicitly accepts it.
+        def wants_json?(env)
+          json?(env["CONTENT_TYPE"]) || json?(env["HTTP_ACCEPT"])
+        end
+    end
+  end
+end
+
+__END__
+
+describe "brute/rack/adapter" do
+  require "stringio"
+  # Specs are eval'd standalone by the scampi runner, so make sure the pipeline
+  # is loaded here; otherwise `Brute.agent` may be undefined.
+  require "brute/turn/agent_pipeline"
+
+  # A tiny agent that echoes the prompt straight back through a real turn, and a
+  # (stateless, reusable) adapter wrapping it.
+  echo_agent = Brute.agent.run(->(env) { env[:messages].assistant("echo: #{env[:messages].last.content}") })
+  adapter    = Brute::Rack::Adapter.new(echo_agent)
+
+  # Build a minimal Rack env by hand (no server needed).
+  rack_env = lambda do |method: "POST", path: "/", query: "", body: "", type: nil, accept: nil|
+    env = {
+      "REQUEST_METHOD" => method,
+      "PATH_INFO"      => path,
+      "QUERY_STRING"   => query,
+      "rack.input"     => StringIO.new(body),
+    }
+    env["CONTENT_TYPE"] = type if type
+    env["HTTP_ACCEPT"]  = accept if accept
+    env
+  end
+
+  it "is a Rack app: env in, [status, headers, body] out" do
+    status, headers, body = adapter.call(rack_env.call(body: "hello"))
+    status.should == 200
+    headers["content-type"].should == "text/plain; charset=utf-8"
+    body.first.should == "echo: hello"
+  end
+
+  it "reads a raw text body as the prompt" do
+    adapter.prompt_from(rack_env.call(body: "what changed?")).should == "what changed?"
+  end
+
+  it "reads a JSON body under a known key" do
+    env = rack_env.call(body: '{"prompt":"from json"}', type: "application/json")
+    adapter.prompt_from(env).should == "from json"
+  end
+
+  it "accepts message/input JSON aliases" do
+    env = rack_env.call(body: '{"message":"aliased"}', type: "application/json")
+    adapter.prompt_from(env).should == "aliased"
+  end
+
+  it "reads a bare JSON string body" do
+    env = rack_env.call(body: '"just a string"', type: "application/json")
+    adapter.prompt_from(env).should == "just a string"
+  end
+
+  it "reads a form-encoded prompt field" do
+    env = rack_env.call(body: "prompt=formed&x=1", type: "application/x-www-form-urlencoded")
+    adapter.prompt_from(env).should == "formed"
+  end
+
+  it "reads a ?prompt= query param without consuming the body" do
+    env = rack_env.call(method: "GET", query: "prompt=queried", body: "")
+    adapter.prompt_from(env).should == "queried"
+  end
+
+  it "returns nil for an empty request" do
+    adapter.prompt_from(rack_env.call(body: "   ")).should.be.nil
+  end
+
+  it "answers a missing prompt with 400" do
+    status, _headers, body = adapter.call(rack_env.call(body: ""))
+    status.should == 400
+    body.first.should == "No prompt provided."
+  end
+
+  it "content-negotiates JSON responses" do
+    env = rack_env.call(body: '{"prompt":"hi"}', type: "application/json")
+    status, headers, body = adapter.call(env)
+    status.should == 200
+    headers["content-type"].should == "application/json"
+    JSON.parse(body.first).should == { "response" => "echo: hi" }
+  end
+
+  it "honors an Accept: application/json header" do
+    env = rack_env.call(body: "hi", accept: "application/json")
+    _status, headers, _body = adapter.call(env)
+    headers["content-type"].should == "application/json"
+  end
+
+  it "renders a raised turn as a 500 (JSON error key when negotiated)" do
+    boom = Brute.agent.run(->(_env) { raise "kaboom" })
+    env  = rack_env.call(body: '{"prompt":"hi"}', type: "application/json")
+    status, _headers, body = Brute::Rack::Adapter.new(boom).call(env)
+    status.should == 500
+    JSON.parse(body.first).should == { "error" => "kaboom" }
+  end
+
+  it ".for is a factory and #start is required" do
+    Brute::Rack::Adapter.for(echo_agent).should.be.kind_of?(Brute::Rack::Adapter)
+    lambda { Brute::Rack::Adapter.new(Object.new) }.should.raise(ArgumentError)
+  end
+end

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