brute 3.2.2 → 4.1.0

data/lib/brute/middleware/open_router.rb

@@ -1,37 +1,55 @@
 # frozen_string_literal: true
 
+require_relative "../deprecate"
+require_relative "../completion/open_router"
+
 module Brute
   module Middleware
     module OpenRouter
-      class Completion
-        # config:   keyword arguments for OpenRouter::Client.new
-        #           (access_token:, request_timeout:, uri_base:, extra_headers:).
-        #           Defaults to OpenRouter.configuration's global settings.
-        # options:  keyword arguments for OpenRouter::CompletionOptions.new
-        #           (model:, temperature:, tools:, ...).
-        def initialize(app, config: {}, **options)
-          @app = app
-          @config = config
-          @options = ::OpenRouter::CompletionOptions.new(**options)
-        end
-
-        def call(env)
-          messages = Brute::MessageTransport::OpenRouter.dump_all(env[:messages])
-
-          ::OpenRouter::Client.new(**@config).then do |client|
-            client.complete(messages, @options).then do |response|
-
-              # OpenRouter in fact only returns a single message...
-              # https://github.com/estiens/open_router_enhanced/blob/main/lib/open_router/response.rb
-              Brute::MessageTransport::OpenRouter.wrap_each(response) do |message|
-                env[:messages] << message
-              end
-            end
-          end
-
-          env
-        end
+      # Deprecated. Completion middlewares now live under Brute::Completion,
+      # which names them for what they do (call one provider) rather than for
+      # where they happened to sit in the stack:
+      #
+      #   Brute::Middleware::OpenRouter::Completion  ->  Brute::Completion::OpenRouter
+      #
+      # The old name stays a working subclass of the new one until the deadline
+      # below; see Brute::Deprecate and `bin/deprecations`.
+      class Completion < Brute::Completion::OpenRouter
+        extend Brute::Deprecate
+        brute_deprecate_constant "Brute::Completion::OpenRouter", "5.0"
       end
     end
   end
 end
+
+__END__
+
+describe "brute/middleware/open_router" do
+  require "brute/completion/open_router"
+
+  it "is the new Completion class under the old name" do
+    Brute::Middleware::OpenRouter::Completion.superclass.should == Brute::Completion::OpenRouter
+  end
+
+  it "warns on use, naming the replacement and the removal version" do
+    captured = []
+    original = Brute::Deprecate.method(:warn)
+    Brute::Deprecate.define_singleton_method(:warn) { |message| captured << message }
+    begin
+      Brute::Middleware::OpenRouter::Completion.new(->(env) { env })
+    ensure
+      Brute::Deprecate.define_singleton_method(:warn, original)
+    end
+
+    captured.size.should == 1
+    captured.first.should.match(/Brute::Middleware::OpenRouter::Completion is deprecated/)
+    captured.first.should.match(/use Brute::Completion::OpenRouter instead/)
+    captured.first.should.match(/removed in Brute 5\.0/)
+  end
+
+  it "is registered with its removal deadline" do
+    entry = Brute::Deprecate.registry.find { |e| e.name == "Brute::Middleware::OpenRouter::Completion" }
+    entry.should.not.be.nil
+    entry.removed_in.should == Gem::Version.new("5.0")
+  end
+end

data/lib/brute/prompt_template.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+require "erb"
+
+module Brute
+  # An ERB-backed system-prompt object for Middleware::SystemPrompt — the
+  # open alternative to Brute::SystemPrompt's built-in section stacks. You
+  # bring a template and named values; every keyword becomes an attr_accessor
+  # and an ERB local of the same name:
+  #
+  #   prompt = Brute::PromptTemplate.new(
+  #     "prompt.erb",
+  #     identity: "You are Pico.",
+  #     memory:   -> { File.read("memory/MEMORY.md") },   # zero-arity proc
+  #     env:      ->(ctx) { Brute::Prompts::Environment.call(ctx) },
+  #   )
+  #   prompt.identity = "You are Brute."   # attr_accessor per section
+  #
+  #   Brute.agent.use(Brute::Middleware::SystemPrompt, system_prompt: prompt)
+  #
+  # Proc values are re-evaluated on every prepare (zero-arity procs are
+  # called with no arguments, others receive the turn ctx), and a template
+  # path is re-read from disk each time — so file-backed sections hot-reload
+  # between turns. The prepare(ctx) -> Result(#empty?, #to_s) contract is
+  # what Middleware::SystemPrompt expects.
+  class PromptTemplate
+    Result = Struct.new(:text) do
+      def to_s = text.to_s
+      def empty? = text.to_s.strip.empty?
+    end
+
+    def initialize(template, **sections)
+      @template = template
+      @section_keys = []
+      sections.each { |key, value| self[key] = value }
+    end
+
+    def [](key)
+      public_send(key)
+    end
+
+    def []=(key, value)
+      unless respond_to?(key)
+        singleton_class.class_eval { attr_accessor key }
+        @section_keys << key
+      end
+      public_send("#{key}=", value)
+    end
+
+    # Called once per turn by Middleware::SystemPrompt.
+    def prepare(ctx = {})
+      Result.new(render(locals(ctx)))
+    end
+
+    private
+
+    def locals(ctx)
+      @section_keys.to_h do |key|
+        value = self[key]
+        resolved = value.is_a?(Proc) ? (value.arity.zero? ? value.call : value.call(ctx)) : value
+        [key, resolved]
+      end.merge(ctx: ctx)
+    end
+
+    def render(values)
+      context = binding
+      values.each { |key, value| context.local_variable_set(key, value) }
+      ERB.new(template_source, trim_mode: "-").result(context)
+    end
+
+    # A path that exists is re-read every time; anything else is treated as
+    # an inline ERB source string.
+    def template_source
+      File.exist?(@template.to_s) ? File.read(@template) : @template.to_s
+    end
+  end
+end
+
+__END__
+
+describe "brute/prompt_template" do
+  require "tmpdir"
+
+  it "renders keyword sections as ERB locals" do
+    prompt = Brute::PromptTemplate.new("Hello <%= name %>, <%= mood %> today.", name: "Pico", mood: "happy")
+    prompt.prepare.to_s.should == "Hello Pico, happy today."
+  end
+
+  it "exposes an attr_accessor per section" do
+    prompt = Brute::PromptTemplate.new("<%= name %>", name: "Pico")
+    prompt.name.should == "Pico"
+    prompt.name = "Brute"
+    prompt.prepare.to_s.should == "Brute"
+  end
+
+  it "re-evaluates zero-arity procs on every prepare" do
+    count = 0
+    prompt = Brute::PromptTemplate.new("<%= tick %>", tick: -> { count += 1 })
+    prompt.prepare.to_s.should == "1"
+    prompt.prepare.to_s.should == "2"
+  end
+
+  it "passes ctx to procs that take an argument" do
+    prompt = Brute::PromptTemplate.new("<%= who %>", who: ->(ctx) { ctx[:agent] })
+    prompt.prepare(agent: "pico").to_s.should == "pico"
+  end
+
+  it "re-reads a template file on every prepare" do
+    Dir.mktmpdir do |dir|
+      path = File.join(dir, "prompt.erb")
+      File.write(path, "v1 <%= x %>")
+      prompt = Brute::PromptTemplate.new(path, x: "a")
+      prompt.prepare.to_s.should == "v1 a"
+      File.write(path, "v2 <%= x %>")
+      prompt.prepare.to_s.should == "v2 a"
+    end
+  end
+
+  it "honours the Result contract (empty?/to_s)" do
+    Brute::PromptTemplate.new("").prepare.empty?.should.be.true
+    Brute::PromptTemplate.new("hi").prepare.empty?.should.be.false
+  end
+end

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>