brute 3.0.0 → 3.1.0

data/lib/brute/middleware/002_session_log.rb

@@ -42,7 +42,7 @@ module Brute
           loaded = []
           File.foreach(@path) do |line|
             line = line.strip
-            loaded << ::RubyLLM::Message.new(**JSON.parse(line, symbolize_names: true)) unless line.empty?
+            loaded << Brute::Message.new(**JSON.parse(line, symbolize_names: true)) unless line.empty?
           end
           messages.unshift(*loaded)
         end

data/lib/brute/middleware/004_summarize.rb

@@ -36,7 +36,7 @@ module Brute
         saved_tools = env[:tools]
         env[:tools] = []
         env[:current_iteration] = 1
-        env[:messages] << RubyLLM::Message.new(role: :user, content: @prompt)
+        env[:messages] << Brute::Message.new(role: :user, content: @prompt)
         @app.call(env)
         env[:tools] = saved_tools
 
@@ -59,9 +59,9 @@ describe "brute/middleware/004_summarize" do
     inner = ->(env) do
       call_count += 1
       if call_count == 1
-        env[:messages] << RubyLLM::Message.new(role: :tool, content: "some result", tool_call_id: "tc1")
+        env[:messages] << Brute::Message.new(role: :tool, content: "some result", tool_call_id: "tc1")
       else
-        env[:messages] << RubyLLM::Message.new(role: :assistant, content: "Here is my complete summary.")
+        env[:messages] << Brute::Message.new(role: :assistant, content: "Here is my complete summary.")
       end
     end
 
@@ -77,7 +77,7 @@ describe "brute/middleware/004_summarize" do
 
   it "restores tools after summary call" do
     inner = ->(env) {
-      env[:messages] << RubyLLM::Message.new(role: :assistant, content: "done")
+      env[:messages] << Brute::Message.new(role: :assistant, content: "done")
     }
 
     mw = Brute::Middleware::Summarize.new(inner)
@@ -93,7 +93,7 @@ describe "brute/middleware/004_summarize" do
     captured_iteration = nil
     inner = ->(env) {
       captured_iteration = env[:current_iteration]
-      env[:messages] << RubyLLM::Message.new(role: :assistant, content: "done")
+      env[:messages] << Brute::Message.new(role: :assistant, content: "done")
     }
 
     mw = Brute::Middleware::Summarize.new(inner)
@@ -111,7 +111,7 @@ describe "brute/middleware/004_summarize" do
     inner = ->(env) {
       call_count += 1
       messages_at_second_call = env[:messages].map(&:content) if call_count == 2
-      env[:messages] << RubyLLM::Message.new(role: :assistant, content: "done")
+      env[:messages] << Brute::Message.new(role: :assistant, content: "done")
     }
 
     mw = Brute::Middleware::Summarize.new(inner)
@@ -128,7 +128,7 @@ describe "brute/middleware/004_summarize" do
     inner = ->(env) {
       call_count += 1
       messages_at_second_call = env[:messages].map(&:content) if call_count == 2
-      env[:messages] << RubyLLM::Message.new(role: :assistant, content: "done")
+      env[:messages] << Brute::Message.new(role: :assistant, content: "done")
     }
 
     mw = Brute::Middleware::Summarize.new(inner, prompt: "Give me the TL;DR.")

data/lib/brute/middleware/006_loop.rb

@@ -108,9 +108,9 @@ describe "brute/middleware/006_loop" do
     inner = ->(env) do
       call_count += 1
       if call_count == 1
-        env[:messages] << RubyLLM::Message.new(role: :tool, content: "result", tool_call_id: "tc1")
+        env[:messages] << Brute::Message.new(role: :tool, content: "result", tool_call_id: "tc1")
       else
-        env[:messages] << RubyLLM::Message.new(role: :assistant, content: "done")
+        env[:messages] << Brute::Message.new(role: :assistant, content: "done")
       end
     end
 
@@ -128,7 +128,7 @@ describe "brute/middleware/006_loop" do
     call_count = 0
     inner = ->(env) do
       call_count += 1
-      env[:messages] << RubyLLM::Message.new(role: :tool, content: "result", tool_call_id: "tc#{call_count}")
+      env[:messages] << Brute::Message.new(role: :tool, content: "result", tool_call_id: "tc#{call_count}")
       env[:should_exit] = { reason: "max" } if call_count >= 2
     end
 
@@ -144,7 +144,7 @@ describe "brute/middleware/006_loop" do
     call_count = 0
     inner = ->(env) do
       call_count += 1
-      env[:messages] << RubyLLM::Message.new(role: :assistant, content: "hello")
+      env[:messages] << Brute::Message.new(role: :assistant, content: "hello")
     end
 
     mw = Brute::Middleware::Loop::ToolResult.new(inner)

data/lib/brute/middleware/008_checkpoint.rb

@@ -0,0 +1,268 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+require "json"
+require "securerandom"
+require "fileutils"
+
+module Brute
+  module Middleware
+    # Durable execution for the tool loop. Where SessionLog persists the
+    # conversation once per turn (outermost), Checkpoint snapshots it after
+    # every pass through the inner stack — one checkpoint per LLM call + tool
+    # execution. Place it just inside Loop::ToolResult:
+    #
+    #   use Brute::Middleware::Loop::ToolResult
+    #   use Brute::Middleware::Checkpoint, path: "tmp/checkpoints.jsonl"
+    #   use Brute::Middleware::MaxIterations
+    #   use Brute::Middleware::ToolPipeline, tools: Brute::Tools::ALL
+    #
+    # The store is just a JSONL log of snapshots — one line per checkpoint,
+    # each carrying the full message log plus its own id and the id of the
+    # parent checkpoint it grew from. That append-only chain buys three
+    # things:
+    #
+    #   resume       pass resume: :latest — a crash mid-turn costs at most
+    #                one iteration instead of the whole turn
+    #   time travel  pass resume: "<checkpoint id>" — restart from any
+    #                snapshot in the chain
+    #   forking      checkpoints written after a time-travel resume carry the
+    #                resumed id as parent_id, branching the chain in place
+    #
+    # System messages are not persisted (SystemPrompt re-adds them each
+    # turn); restored history is inserted after any leading system message
+    # and before the current turn's input.
+    class Checkpoint
+      def initialize(app, path:, resume: nil)
+        @app    = app
+        @path   = path
+        @resume = resume
+      end
+
+      def call(env)
+        restore(env) unless env[:metadata][:checkpoint]
+        @app.call(env)
+        persist(env)
+        env
+      end
+
+      # Parsed checkpoint records (symbol keys, messages as plain hashes),
+      # oldest first.
+      def self.list(path)
+        return [] unless path && File.exist?(path)
+
+        File.foreach(path).filter_map do |line|
+          line = line.strip
+          JSON.parse(line, symbolize_names: true) unless line.empty?
+        end
+      end
+
+      private
+
+        def restore(env)
+          env[:metadata][:checkpoint] = { path: @path }
+          return unless @resume
+
+          record = find_record
+          if record.nil?
+            return if @resume == :latest
+
+            raise KeyError, "no checkpoint #{@resume.inspect} in #{@path}"
+          end
+
+          history = record[:messages].map { |h| Brute::Message.new(**h) }
+          index = env[:messages].index { |m| m.role != :system } || env[:messages].size
+          env[:messages].insert(index, *history)
+          env[:metadata][:checkpoint][:id] = record[:id]
+        end
+
+        def find_record
+          records = self.class.list(@path)
+          @resume == :latest ? records.last : records.find { |r| r[:id] == @resume.to_s }
+        end
+
+        def persist(env)
+          FileUtils.mkdir_p(File.dirname(@path))
+          record = {
+            id:        SecureRandom.hex(6),
+            parent_id: env[:metadata][:checkpoint][:id],
+            ts:        Time.now.utc.iso8601,
+            iteration: env[:current_iteration],
+            messages:  env[:messages].reject { |m| m.role == :system }.map(&:to_h),
+          }
+          File.open(@path, "a") { |f| f.puts(JSON.generate(record)) }
+          env[:metadata][:checkpoint][:id] = record[:id]
+        end
+    end
+  end
+end
+
+__END__
+
+describe "brute/middleware/008_checkpoint" do
+  require "brute/messages"
+  require "tmpdir"
+
+  it "snapshots after every pass through the loop" do
+    Dir.mktmpdir do |dir|
+      path = File.join(dir, "cp.jsonl")
+      calls = 0
+      inner = ->(env) do
+        calls += 1
+        if calls < 3
+          env[:messages] << Brute::Message.new(role: :tool, content: "r#{calls}", tool_call_id: "tc#{calls}")
+        else
+          env[:messages].assistant("done")
+        end
+      end
+
+      stack = Brute::Middleware::Loop::ToolResult.new(
+        Brute::Middleware::Checkpoint.new(inner, path: path)
+      )
+      env = { messages: Brute.log.tap { |l| l.user("go") }, metadata: {}, current_iteration: 1 }
+      stack.call(env)
+
+      records = Brute::Middleware::Checkpoint.list(path)
+      records.size.should == 3
+      records.map { |r| r[:iteration] }.should == [1, 2, 3]
+      records.last[:messages].last[:content].should == "done"
+    end
+  end
+
+  it "chains checkpoints via parent_id" do
+    Dir.mktmpdir do |dir|
+      path = File.join(dir, "cp.jsonl")
+      mw = Brute::Middleware::Checkpoint.new(->(env) { env[:messages].assistant("a") }, path: path)
+      env = { messages: Brute.log.tap { |l| l.user("go") }, metadata: {}, current_iteration: 1 }
+      mw.call(env)
+      mw.call(env)
+
+      records = Brute::Middleware::Checkpoint.list(path)
+      records[0][:parent_id].should == nil
+      records[1][:parent_id].should == records[0][:id]
+    end
+  end
+
+  it "resume: :latest restores the conversation before this turn's input" do
+    Dir.mktmpdir do |dir|
+      path = File.join(dir, "cp.jsonl")
+      Brute::Middleware::Checkpoint.new(->(env) { env[:messages].assistant("first reply") }, path: path)
+        .call({ messages: Brute.log.tap { |l| l.user("hi") }, metadata: {}, current_iteration: 1 })
+
+      env = { messages: Brute.log.tap { |l| l.user("again") }, metadata: {}, current_iteration: 1 }
+      Brute::Middleware::Checkpoint.new(->(_e) {}, path: path, resume: :latest).call(env)
+
+      env[:messages].map(&:content).should == ["hi", "first reply", "again"]
+    end
+  end
+
+  it "inserts restored history after the system message" do
+    Dir.mktmpdir do |dir|
+      path = File.join(dir, "cp.jsonl")
+      Brute::Middleware::Checkpoint.new(->(env) { env[:messages].assistant("old") }, path: path)
+        .call({ messages: Brute.log.tap { |l| l.user("hi") }, metadata: {}, current_iteration: 1 })
+
+      env = { messages: Brute.log, metadata: {}, current_iteration: 1 }
+      env[:messages].system("rules")
+      env[:messages].user("new input")
+      Brute::Middleware::Checkpoint.new(->(_e) {}, path: path, resume: :latest).call(env)
+
+      env[:messages].map(&:role).should == [:system, :user, :assistant, :user]
+      env[:messages].last.content.should == "new input"
+    end
+  end
+
+  it "resumes from a specific checkpoint id (time travel)" do
+    Dir.mktmpdir do |dir|
+      path = File.join(dir, "cp.jsonl")
+      mw = Brute::Middleware::Checkpoint.new(->(env) { env[:messages].assistant("reply #{env[:messages].size}") }, path: path)
+      env = { messages: Brute.log.tap { |l| l.user("go") }, metadata: {}, current_iteration: 1 }
+      mw.call(env)
+      mw.call(env)
+
+      first = Brute::Middleware::Checkpoint.list(path).first
+      env2 = { messages: Brute.log, metadata: {}, current_iteration: 1 }
+      Brute::Middleware::Checkpoint.new(->(_e) {}, path: path, resume: first[:id]).call(env2)
+
+      env2[:messages].size.should == first[:messages].size
+    end
+  end
+
+  it "forks: checkpoints after a time-travel resume carry the resumed id as parent" do
+    Dir.mktmpdir do |dir|
+      path = File.join(dir, "cp.jsonl")
+      mw = Brute::Middleware::Checkpoint.new(->(env) { env[:messages].assistant("a") }, path: path)
+      env = { messages: Brute.log.tap { |l| l.user("go") }, metadata: {}, current_iteration: 1 }
+      mw.call(env)
+      mw.call(env)
+
+      root = Brute::Middleware::Checkpoint.list(path).first
+      Brute::Middleware::Checkpoint.new(->(env) { env[:messages].assistant("fork") }, path: path, resume: root[:id])
+        .call({ messages: Brute.log, metadata: {}, current_iteration: 1 })
+
+      Brute::Middleware::Checkpoint.list(path).last[:parent_id].should == root[:id]
+    end
+  end
+
+  it "resume: :latest with no store yet starts fresh" do
+    Dir.mktmpdir do |dir|
+      env = { messages: Brute.log.tap { |l| l.user("go") }, metadata: {}, current_iteration: 1 }
+      Brute::Middleware::Checkpoint.new(->(_e) {}, path: File.join(dir, "cp.jsonl"), resume: :latest).call(env)
+      env[:messages].map(&:content).should == ["go"]
+    end
+  end
+
+  it "raises on an unknown checkpoint id" do
+    Dir.mktmpdir do |dir|
+      path = File.join(dir, "cp.jsonl")
+      Brute::Middleware::Checkpoint.new(->(_e) {}, path: path).call(
+        { messages: Brute.log, metadata: {}, current_iteration: 1 }
+      )
+
+      lambda do
+        Brute::Middleware::Checkpoint.new(->(_e) {}, path: path, resume: "nope").call(
+          { messages: Brute.log, metadata: {}, current_iteration: 1 }
+        )
+      end.should.raise(KeyError)
+    end
+  end
+
+  it "does not persist system messages" do
+    Dir.mktmpdir do |dir|
+      path = File.join(dir, "cp.jsonl")
+      env = { messages: Brute.log, metadata: {}, current_iteration: 1 }
+      env[:messages].system("rules")
+      env[:messages].user("go")
+      Brute::Middleware::Checkpoint.new(->(_e) {}, path: path).call(env)
+
+      roles = Brute::Middleware::Checkpoint.list(path).last[:messages].map { |m| m[:role] }
+      roles.should == ["user"]
+    end
+  end
+
+  it "restores only once even though the loop re-enters" do
+    Dir.mktmpdir do |dir|
+      path = File.join(dir, "cp.jsonl")
+      Brute::Middleware::Checkpoint.new(->(env) { env[:messages].assistant("old") }, path: path)
+        .call({ messages: Brute.log.tap { |l| l.user("hi") }, metadata: {}, current_iteration: 1 })
+
+      calls = 0
+      inner = ->(env) do
+        calls += 1
+        if calls < 2
+          env[:messages] << Brute::Message.new(role: :tool, content: "r", tool_call_id: "tc1")
+        else
+          env[:messages].assistant("done")
+        end
+      end
+      stack = Brute::Middleware::Loop::ToolResult.new(
+        Brute::Middleware::Checkpoint.new(inner, path: path, resume: :latest)
+      )
+      env = { messages: Brute.log.tap { |l| l.user("again") }, metadata: {}, current_iteration: 1 }
+      stack.call(env)
+
+      env[:messages].count { |m| m.content == "old" }.should == 1
+    end
+  end
+end

data/lib/brute/middleware/010_max_iterations.rb

@@ -22,7 +22,7 @@ module Brute
 
       def call(env)
         if max_iterations_reached?(env)
-          env[:messages] << RubyLLM::Message.new(
+          env[:messages] << Brute::Message.new(
             role: :user,
             content: "Maximum iterations reached.",
           )

data/lib/brute/middleware/020_system_prompt.rb

@@ -37,7 +37,7 @@ module Brute
           result = @system_prompt.prepare(ctx)
           unless result.empty?
             env[:messages].unshift(
-              RubyLLM::Message.new(role: :system, content: result.to_s)
+              Brute::Message.new(role: :system, content: result.to_s)
             )
           end
         end

data/lib/brute/middleware/040_compaction_check.rb

@@ -39,8 +39,8 @@ module Brute
         #    }
         #    # Replace the message history with the summary
         #    env[:messages] = [
-        #      RubyLLM::Message.new(role: :system, content: @system_prompt),
-        #      RubyLLM::Message.new(role: :user, content: "[Previous conversation summary]\n\n#{summary_text}"),
+        #      Brute::Message.new(role: :system, content: @system_prompt),
+        #      Brute::Message.new(role: :user, content: "[Previous conversation summary]\n\n#{summary_text}"),
         #    ]
         #  end
         #end

data/lib/brute/middleware/070_tool_pipeline.rb

@@ -81,13 +81,13 @@ module Brute
           Sync do
             barrier = Async::Barrier.new
 
-            tools_to_run.each do |id, tool_call|
+            tools_to_run.each do |tool_call|
               barrier.async do
                 tool = available_tools[tool_call.name.to_sym]
                 result = tool.call(tool_call.arguments)
 
-                # Coerce to String so RubyLLM::Message doesn't treat Hash results
-                # (e.g. Shell's {stdout:, stderr:, exit_code:}) as attachments.
+                # Coerce to String so Hash results (e.g. Shell's
+                # {stdout:, stderr:, exit_code:}) serialize predictably.
                 content = result.is_a?(String) ? result : result.to_s
 
                 # Universal truncation safety net — skip if already truncated
@@ -95,13 +95,13 @@ module Brute
                   content = Brute::Truncation.truncate(content)
                 end
 
-                results << [id, tool_call, content]
+                results << [tool_call, content]
               rescue => e
                 # Capture the error as a tool result so the LLM can see it
                 # and reason about the failure, rather than crashing the
                 # entire middleware chain.
                 env[:events] << { type: :error, data: { error: e, message: e.message } }
-                results << [id, tool_call, "Error: #{e.class}: #{e.message}"]
+                results << [tool_call, "Error: #{e.class}: #{e.message}"]
               end
             end
 
@@ -112,12 +112,11 @@ module Brute
 
           # Append events and messages in the original tool_call order so the
           # LLM sees a deterministic sequence regardless of completion order.
-          order = tools_to_run.keys
-          results.sort_by! { |id, _, _| order.index(id) }
+          results.sort_by! { |tool_call, _| tools_to_run.index(tool_call) }
 
-          results.each do |_id, tool_call, content|
+          results.each do |tool_call, content|
             env[:events] << { type: :tool_result, data: { name: tool_call.name, content: content } }
-            env[:messages] << RubyLLM::Message.new(role: :tool, content: content, tool_call_id: tool_call.id)
+            env[:messages] << Brute::Message.new(role: :tool, content: content, tool_call_id: tool_call.id)
           end
         end
 
@@ -126,8 +125,14 @@ module Brute
 
       private
 
+        # The last message's pending tool calls as a flat list. Duck-typed:
+        # tool_calls may be an Array (Brute::ToolCall) or an id-keyed Hash
+        # (some libraries' native shape); each entry needs #id, #name and
+        # #arguments.
         def pending_tool_calls(message)
-          message.tool_calls.to_h.reject { |_id, tc| tc.name == "question" }
+          calls = message.respond_to?(:tool_calls) ? message.tool_calls : nil
+          calls = calls.values if calls.respond_to?(:values)
+          Array(calls).reject { |tc| tc.name == "question" }
         end
 
         def resolve_tools(tools)
@@ -137,7 +142,7 @@ module Brute
         def on_tool_call_start_event(pending_tools)
           {
             type: :tool_call_start,
-            data: pending_tools.map { |_id, tc|
+            data: pending_tools.map { |tc|
               {
                 name: tc.name,
                 call_id: tc.id,
@@ -158,7 +163,7 @@ describe "brute/middleware/070_tool_pipeline" do
 
   it "passes through when no tool calls pending" do
     inner = ->(env) {
-      env[:messages] << RubyLLM::Message.new(role: :assistant, content: "hi")
+      env[:messages] << Brute::Message.new(role: :assistant, content: "hi")
     }
     mw = Brute::Middleware::ToolPipeline.new(inner, tools: [])
     env = {
@@ -185,7 +190,7 @@ describe "brute/middleware/070_tool_pipeline" do
 
   it "truncates large tool results via Truncation" do
     # A fake tool that returns a huge string
-    big_tool = Class.new(RubyLLM::Tool) do
+    big_tool = Class.new(Brute::Tool) do
       description "test tool"
       param :input, type: "string", desc: "input"
       def name; "big_tool"; end
@@ -194,17 +199,16 @@ describe "brute/middleware/070_tool_pipeline" do
       end
     end
 
-    call_id = "tc_1"
-    tool_calls = {
-      call_id => RubyLLM::ToolCall.new(
-        id: call_id,
+    tool_calls = [
+      Brute::ToolCall.new(
+        id: "tc_1",
         name: "big_tool",
         arguments: { "input" => "go" },
       )
-    }
+    ]
 
     inner = ->(env) {
-      env[:messages] << RubyLLM::Message.new(role: :assistant, content: "", tool_calls: tool_calls)
+      env[:messages] << Brute::Message.new(role: :assistant, content: "", tool_calls: tool_calls)
     }
     mw = Brute::Middleware::ToolPipeline.new(inner, tools: [big_tool])
     env = {
@@ -223,7 +227,7 @@ describe "brute/middleware/070_tool_pipeline" do
 
   it "does not double-truncate already-truncated output" do
     # A fake tool that returns output already containing the truncation marker
-    pre_truncated_tool = Class.new(RubyLLM::Tool) do
+    pre_truncated_tool = Class.new(Brute::Tool) do
       description "test tool"
       param :input, type: "string", desc: "input"
       def name; "pre_truncated_tool"; end
@@ -232,17 +236,16 @@ describe "brute/middleware/070_tool_pipeline" do
       end
     end
 
-    call_id = "tc_2"
-    tool_calls = {
-      call_id => RubyLLM::ToolCall.new(
-        id: call_id,
+    tool_calls = [
+      Brute::ToolCall.new(
+        id: "tc_2",
         name: "pre_truncated_tool",
         arguments: { "input" => "go" },
       )
-    }
+    ]
 
     inner = ->(env) {
-      env[:messages] << RubyLLM::Message.new(role: :assistant, content: "", tool_calls: tool_calls)
+      env[:messages] << Brute::Message.new(role: :assistant, content: "", tool_calls: tool_calls)
     }
     mw = Brute::Middleware::ToolPipeline.new(inner, tools: [pre_truncated_tool])
     env = {

data/lib/brute/tool.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+
+module Brute
+  # Base class for Brute's built-in tools — a tiny, framework-agnostic tool
+  # DSL. It intentionally mirrors the common tool-library shape (description +
+  # params) so tools read the same as they would in any LLM library, without
+  # depending on one:
+  #
+  #   class Shell < Brute::Tool
+  #     description "Execute a shell command"
+  #     param :command, type: 'string', desc: "The command", required: true
+  #
+  #     def name; "shell"; end
+  #
+  #     def execute(command:)
+  #       ...
+  #     end
+  #   end
+  #
+  # For tools whose arguments don't fit the flat param list, pass a raw JSON
+  # schema instead:
+  #
+  #   params({ type: 'object', properties: { ... }, required: [...] })
+  #
+  # Instances expose the neutral interface Brute::Tools::Adapter understands:
+  # #name, #description, #params, #params_schema, #call.
+  class Tool
+    class << self
+      def description(text = nil)
+        return @description unless text
+
+        @description = text
+      end
+
+      # Declare one parameter: param :key, type:, desc:, required:
+      def param(name, type: "string", desc: nil, required: true, **opts)
+        param_definitions[name.to_sym] = { type: type, desc: desc, required: required, **opts }.compact
+      end
+
+      def param_definitions
+        @param_definitions ||= {}
+      end
+
+      # Raw JSON-schema override for complex argument shapes.
+      def params(schema = nil)
+        return @params_schema unless schema
+
+        @params_schema = schema.deep_symbolize_keys
+      end
+    end
+
+    # Tool name; subclasses usually override with an explicit short name.
+    def name
+      self.class.name.demodulize.underscore
+    end
+
+    def description
+      self.class.description.to_s
+    end
+
+    # { key => { type:, desc:, required: } }
+    def params
+      self.class.param_definitions
+    end
+
+    # The raw JSON schema, when declared via params({...}).
+    def params_schema
+      self.class.params
+    end
+
+    # Execute with a string- or symbol-keyed argument hash, as delivered
+    # by LLM providers.
+    def call(arguments = {})
+      execute(**arguments.to_h.transform_keys(&:to_sym))
+    end
+
+    def execute(**)
+      raise NotImplementedError, "#{self.class} must implement #execute"
+    end
+  end
+end
+
+__END__
+
+describe "brute/tool" do
+  it "exposes description and params from the DSL" do
+    klass = Class.new(Brute::Tool) do
+      description "test tool"
+      param :input, type: "string", desc: "the input"
+      def name; "t"; end
+      def execute(input:); "got #{input}"; end
+    end
+
+    tool = klass.new
+    tool.description.should == "test tool"
+    tool.params[:input][:type].should == "string"
+    tool.params[:input][:required].should.be.true
+  end
+
+  it "calls execute with symbolized keys" do
+    klass = Class.new(Brute::Tool) do
+      description "echo"
+      param :msg, type: "string"
+      def name; "echo"; end
+      def execute(msg:); msg; end
+    end
+
+    klass.new.call("msg" => "hi").should == "hi"
+  end
+
+  it "accepts a raw JSON schema via params({...})" do
+    klass = Class.new(Brute::Tool) do
+      description "schema tool"
+      params({ type: "object", properties: { a: { type: "string" } }, required: %w[a] })
+      def name; "s"; end
+      def execute(a:); a; end
+    end
+
+    klass.new.params_schema[:properties][:a][:type].should == "string"
+  end
+end