brute 3.0.0 → 3.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d6308c538c9efce1d554894738361f1f07720730b3fc66aa46df9f57e2599ae4
-  data.tar.gz: 9bc51c1b3020b601bacbab282874f8a789b1420b84a9649c58f6e75c83b4b7b5
+  metadata.gz: c25e73819e947f92a37f144411ba27b09f93cc48088bc0cc474247bc81149658
+  data.tar.gz: 635eff80312c14656cf2a6168f2f4ee9279413ac285e580a58e959812a9e5d4d
 SHA512:
-  metadata.gz: b7f0b0ab4859d81bdc9885824bca9baf68600ff880f4b804652e10882caf3d2449235f18490d9338ab1e4bce29cc641d8b776bd9a777dc7fd98a3bb8b9b81c94
-  data.tar.gz: 53301d50213d626fa6f7ba7e1bb0b1124aa3b4b48485302f176681eabf8d0839d493231416c1f0274f29fd5690754b8a48d6751d83f6a32cbc58a9a59f5fa1c9
+  metadata.gz: c43c126ae04f4642df67df70ab780dfc11ef2070709580cc409d6b32652a2f0be41730d252a06d9029f8d156657877f046af6a06d5c2ba1d4ee9a2d5fda75d97
+  data.tar.gz: 26599b1c63616c87af1c8537dfe4e473be5a70ee408058b31fb8a67c5203f72b81d41a868e59ceb8831ac570a74a9132c6c2df42794b116ea91e67b70a4441dc

data/lib/brute/message_transport/anthropic.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+require "brute/message_transport"
+
+module Brute
+  class MessageTransport
+    # MessageTransport for the official anthropic gem
+    # (https://github.com/anthropics/anthropic-sdk-ruby). Brute does not
+    # require it — you do:
+    #
+    #   require "anthropic"
+    #
+    #   client = Anthropic::Client.new(api_key: ENV["ANTHROPIC_API_KEY"])
+    #   response = client.messages.create(
+    #     model:      "claude-opus-4-8",
+    #     max_tokens: 16_000,
+    #     system_:    Brute::MessageTransport::Anthropic.system_text(env[:messages]),
+    #     messages:   Brute::MessageTransport::Anthropic.dump_all(env[:messages]),
+    #     tools:      ...,
+    #   )
+    #   Brute::MessageTransport::Anthropic.wrap_each(response) { |m| env[:messages] << m }
+    #
+    # Anthropic's Messages API differs from chat-completions-shaped APIs in
+    # two ways this transport absorbs: the system prompt is a top-level
+    # parameter (not a message), and tool results are content blocks inside
+    # a user message — consecutive tool results are folded into one user
+    # turn so roles keep alternating.
+    class Anthropic < MessageTransport
+      # The :system messages' text, for the top-level `system_:` parameter.
+      def self.system_text(messages)
+        messages.select { |m| m.role == :system }.map(&:content).join("\n\n")
+      end
+
+      # Brute log -> the `messages:` array. Drops :system messages (see
+      # .system_text) and folds consecutive :tool results into one user turn.
+      def self.dump_all(messages)
+        chat = messages.reject { |m| m.role == :system }
+
+        chat.chunk_while { |a, b| a.role == :tool && b.role == :tool }.map do |group|
+          if group.first.role == :tool
+            { role: "user", content: group.map { |m| tool_result_block(m) } }
+          else
+            dump(group.first)
+          end
+        end
+      end
+
+      # Brute::Message -> an Anthropic message param hash.
+      def self.dump(message)
+        case message.role
+        when :tool
+          { role: "user", content: [tool_result_block(message)] }
+        when :assistant
+          if message.tool_call?
+            blocks = []
+            blocks << { type: "text", text: message.content } unless message.content.to_s.empty?
+            blocks += message.tool_calls.map { |tc| { type: "tool_use", id: tc.id, name: tc.name, input: tc.arguments } }
+            { role: "assistant", content: blocks }
+          else
+            { role: "assistant", content: message.content }
+          end
+        else
+          { role: message.role.to_s, content: message.content }
+        end
+      end
+
+      def self.tool_result_block(message)
+        { type: "tool_result", tool_use_id: message.tool_call_id, content: message.content.to_s }
+      end
+
+      private
+
+        # An Anthropic response (content blocks) -> one Brute::Message. Text
+        # blocks join into the content; tool_use blocks become tool calls.
+        def wrap(message)
+          blocks = message.content
+
+          text = blocks.select { |b| b.type == :text }.map(&:text).join
+          tool_calls = blocks.select { |b| b.type == :tool_use }.map do |b|
+            arguments = b.input.respond_to?(:to_h) ? b.input.to_h : b.input
+            Brute::ToolCall.new(id: b.id, name: b.name, arguments: arguments)
+          end
+
+          Brute::Message.new(
+            role:       :assistant,
+            content:    text,
+            tool_calls: (tool_calls unless tool_calls.empty?),
+          )
+        end
+    end
+  end
+end
+
+__END__
+
+describe "brute/message_transport/anthropic" do
+  require "brute/messages"
+
+  # Duck-typed stand-ins for the anthropic gem's response objects so these
+  # specs don't need the gem loaded.
+  fake_text_block = Struct.new(:type, :text, keyword_init: true)
+  fake_tool_block = Struct.new(:type, :id, :name, :input, keyword_init: true)
+  fake_response   = Struct.new(:content, keyword_init: true)
+
+  it "extracts the system prompt" do
+    log = Brute.log
+    log.system("be helpful")
+    log.user("hi")
+    Brute::MessageTransport::Anthropic.system_text(log).should == "be helpful"
+  end
+
+  it "dumps tool calls as tool_use blocks" do
+    m = Brute::Message.new(role: :assistant, content: "thinking...",
+                           tool_calls: [{ id: "tc1", name: "shell", arguments: { "command" => "ls" } }])
+    dumped = Brute::MessageTransport::Anthropic.dump(m)
+    dumped[:content].last.should == { type: "tool_use", id: "tc1", name: "shell", input: { "command" => "ls" } }
+  end
+
+  it "folds consecutive tool results into one user turn" do
+    log = Brute.log
+    log.user("go")
+    log.tool("a", tool_call_id: "tc1")
+    log.tool("b", tool_call_id: "tc2")
+
+    dumped = Brute::MessageTransport::Anthropic.dump_all(log)
+    dumped.size.should == 2
+    dumped.last[:role].should == "user"
+    dumped.last[:content].map { |b| b[:tool_use_id] }.should == %w[tc1 tc2]
+  end
+
+  it "wraps text and tool_use blocks into one assistant message" do
+    response = fake_response.new(content: [
+      fake_text_block.new(type: :text, text: "running ls"),
+      fake_tool_block.new(type: :tool_use, id: "tc1", name: "shell", input: { "command" => "ls" }),
+    ])
+
+    out = Brute::MessageTransport::Anthropic.new(response).wrap_each.to_a.first
+    out.content.should == "running ls"
+    out.tool_calls.first.name.should == "shell"
+  end
+end

data/lib/brute/message_transport/llm.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+require "brute/message_transport"
+require "json"
+
+module Brute
+  class MessageTransport
+    # MessageTransport for the llm.rb gem (https://github.com/llmrb/llm.rb).
+    # Brute does not require llm.rb — you do:
+    #
+    #   require "llm"
+    #
+    #   llm = LLM.openai(key: ENV["OPENAI_API_KEY"])
+    #   messages = Brute::MessageTransport::LLM.dump_all(env[:messages])
+    #   response = llm.complete(messages.pop, role: nil, messages: messages, tools: ...)
+    #   Brute::MessageTransport::LLM.wrap_each(response) { |m| env[:messages] << m }
+    class LLM < MessageTransport
+      # Brute::Message -> LLM::Message. Assistant tool calls carry llm.rb's
+      # `original_tool_calls` extra (the provider wire format); tool results
+      # become an LLM::Function::Return so llm.rb's request adapters emit
+      # them correctly.
+      def self.dump(message)
+        case message.role
+        when :tool
+          ::LLM::Message.new(
+            :tool,
+            ::LLM::Function::Return.new(message.tool_call_id, nil, message.content.to_s),
+          )
+        when :assistant
+          if message.tool_call?
+            wire = message.tool_calls.map do |tc|
+              { id: tc.id, type: "function", function: { name: tc.name, arguments: JSON.generate(tc.arguments) } }
+            end
+            ::LLM::Message.new(:assistant, message.content.to_s,
+                               { tool_calls: wire, original_tool_calls: wire })
+          else
+            ::LLM::Message.new(:assistant, message.content)
+          end
+        else
+          ::LLM::Message.new(message.role, message.content)
+        end
+      end
+
+      private
+
+        # LLM::Message (from an LLM::Response) -> Brute::Message.
+        def wrap(message)
+          tool_calls = if message.tool_call?
+            message.tool_calls.map do |tc|
+              Brute::ToolCall.new(id: tc.id, name: tc["name"], arguments: tc.arguments.to_h)
+            end
+          end
+
+          Brute::Message.new(
+            role:       message.role,
+            content:    message.content.to_s,
+            tool_calls: tool_calls,
+          )
+        end
+    end
+  end
+end
+
+__END__
+
+describe "brute/message_transport/llm" do
+  require "brute/messages"
+
+  # Duck-typed stand-in for a response LLM::Message so these specs don't
+  # need the gem loaded.
+  fake_tool_call = Struct.new(:id, :arguments, keyword_init: true) do
+    def [](key); key == "name" ? "shell" : nil; end
+  end
+  fake_message = Struct.new(:role, :content, :tool_calls, keyword_init: true) do
+    def tool_call?; !tool_calls.nil? && tool_calls.any?; end
+  end
+
+  it "wraps a plain assistant message" do
+    m = fake_message.new(role: "assistant", content: "hi")
+    out = Brute::MessageTransport::LLM.new(m).wrap_each.to_a.first
+    out.role.should == :assistant
+    out.content.should == "hi"
+  end
+
+  it "wraps tool calls into Brute::ToolCall" do
+    tc = fake_tool_call.new(id: "tc1", arguments: { "command" => "ls" })
+    m = fake_message.new(role: "assistant", content: nil, tool_calls: [tc])
+
+    out = Brute::MessageTransport::LLM.new(m).wrap_each.to_a.first
+    out.tool_calls.first.should == Brute::ToolCall.new(id: "tc1", name: "shell", arguments: { "command" => "ls" })
+  end
+end

data/lib/brute/message_transport/openai.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+require "brute/message_transport"
+require "json"
+
+module Brute
+  class MessageTransport
+    # MessageTransport for the official openai gem
+    # (https://github.com/openai/openai-ruby). Brute does not require it —
+    # you do:
+    #
+    #   require "openai"
+    #
+    #   client = OpenAI::Client.new(api_key: ENV["OPENAI_API_KEY"])
+    #   response = client.chat.completions.create(
+    #     model:    "gpt-5",
+    #     messages: Brute::MessageTransport::OpenAI.dump_all(env[:messages]),
+    #     tools:    ...,
+    #   )
+    #   Brute::MessageTransport::OpenAI.wrap_each(response) { |m| env[:messages] << m }
+    class OpenAI < MessageTransport
+      # Brute::Message -> a chat.completions message param hash.
+      def self.dump(message)
+        case message.role
+        when :tool
+          { role: "tool", tool_call_id: message.tool_call_id, content: message.content.to_s }
+        when :assistant
+          if message.tool_call?
+            {
+              role:       "assistant",
+              content:    (message.content unless message.content.to_s.empty?),
+              tool_calls: message.tool_calls.map { |tc|
+                { id: tc.id, type: "function", function: { name: tc.name, arguments: JSON.generate(tc.arguments) } }
+              },
+            }
+          else
+            { role: "assistant", content: message.content }
+          end
+        else
+          { role: message.role.to_s, content: message.content }
+        end
+      end
+
+      # A chat completion response's messages (one per choice).
+      def messages
+        return @result.choices.map(&:message) if @result.respond_to?(:choices)
+
+        super
+      end
+
+      private
+
+        # An OpenAI chat completion message -> Brute::Message. Tool call
+        # arguments arrive as a JSON string; parse them into a Hash.
+        def wrap(message)
+          tool_calls = message.tool_calls&.map do |tc|
+            arguments = begin
+              JSON.parse(tc.function.arguments.to_s)
+            rescue JSON::ParserError
+              {}
+            end
+            Brute::ToolCall.new(id: tc.id, name: tc.function.name, arguments: arguments)
+          end
+
+          Brute::Message.new(
+            role:       message.role,
+            content:    message.content.to_s,
+            tool_calls: tool_calls,
+          )
+        end
+    end
+  end
+end
+
+__END__
+
+describe "brute/message_transport/openai" do
+  require "brute/messages"
+
+  # Duck-typed stand-ins for the openai gem's response objects so these
+  # specs don't need the gem loaded.
+  fake_function  = Struct.new(:name, :arguments, keyword_init: true)
+  fake_tool_call = Struct.new(:id, :function, keyword_init: true)
+  fake_message   = Struct.new(:role, :content, :tool_calls, keyword_init: true)
+  fake_choice    = Struct.new(:message, keyword_init: true)
+  fake_response  = Struct.new(:choices, keyword_init: true)
+
+  it "dumps a tool result to the wire format" do
+    m = Brute::Message.new(role: :tool, content: "ok", tool_call_id: "tc1")
+    Brute::MessageTransport::OpenAI.dump(m).should ==
+      { role: "tool", tool_call_id: "tc1", content: "ok" }
+  end
+
+  it "dumps assistant tool calls with JSON-encoded arguments" do
+    m = Brute::Message.new(role: :assistant, content: "",
+                           tool_calls: [{ id: "tc1", name: "shell", arguments: { "command" => "ls" } }])
+    dumped = Brute::MessageTransport::OpenAI.dump(m)
+    dumped[:tool_calls].first[:function][:arguments].should == '{"command":"ls"}'
+  end
+
+  it "unpacks a chat completion's choices and parses arguments" do
+    tc = fake_tool_call.new(id: "tc1", function: fake_function.new(name: "shell", arguments: '{"command":"ls"}'))
+    response = fake_response.new(choices: [
+      fake_choice.new(message: fake_message.new(role: "assistant", content: nil, tool_calls: [tc])),
+    ])
+
+    out = Brute::MessageTransport::OpenAI.new(response).wrap_each.to_a.first
+    out.role.should == :assistant
+    out.tool_calls.first.arguments.should == { "command" => "ls" }
+  end
+end

data/lib/brute/message_transport/ruby_llm.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+require "brute/message_transport"
+
+module Brute
+  class MessageTransport
+    # MessageTransport for the ruby_llm gem (https://rubyllm.com).
+    # Brute does not require ruby_llm — you do:
+    #
+    #   require "ruby_llm"
+    #
+    #   response = provider.complete(
+    #     Brute::MessageTransport::RubyLLM.dump_all(env[:messages]),
+    #     tools: ..., model: model,
+    #   )
+    #   Brute::MessageTransport::RubyLLM.wrap_each(response) { |m| env[:messages] << m }
+    class RubyLLM < MessageTransport
+      # Brute::Message -> RubyLLM::Message (tool calls as ruby_llm's
+      # id-keyed hash).
+      def self.dump(message)
+        tool_calls = message.tool_calls&.each_with_object({}) do |tc, hash|
+          hash[tc.id] = ::RubyLLM::ToolCall.new(id: tc.id, name: tc.name, arguments: tc.arguments)
+        end
+
+        ::RubyLLM::Message.new(
+          role:         message.role,
+          content:      message.content,
+          tool_calls:   tool_calls,
+          tool_call_id: message.tool_call_id,
+        )
+      end
+
+      private
+
+        # RubyLLM::Message -> Brute::Message.
+        def wrap(message)
+          tool_calls = message.tool_calls&.values&.map do |tc|
+            Brute::ToolCall.new(id: tc.id, name: tc.name, arguments: tc.arguments)
+          end
+
+          Brute::Message.new(
+            role:         message.role,
+            content:      message.content.to_s,
+            tool_calls:   tool_calls,
+            tool_call_id: message.tool_call_id,
+          )
+        end
+    end
+  end
+end
+
+__END__
+
+describe "brute/message_transport/ruby_llm" do
+  require "brute/messages"
+
+  # Duck-typed stand-ins for RubyLLM::Message / RubyLLM::ToolCall so these
+  # specs don't need the gem loaded.
+  fake_tool_call = Struct.new(:id, :name, :arguments, keyword_init: true)
+  fake_message   = Struct.new(:role, :content, :tool_calls, :tool_call_id, keyword_init: true)
+
+  it "wraps a plain assistant message" do
+    m = fake_message.new(role: :assistant, content: "hi")
+    out = Brute::MessageTransport::RubyLLM.new(m).wrap_each.to_a
+    out.first.should.be.kind_of?(Brute::Message)
+    out.first.content.should == "hi"
+  end
+
+  it "wraps ruby_llm's id-keyed tool_calls hash into a flat list" do
+    tc = fake_tool_call.new(id: "tc1", name: "shell", arguments: { "command" => "ls" })
+    m = fake_message.new(role: :assistant, content: "", tool_calls: { "tc1" => tc })
+
+    out = Brute::MessageTransport::RubyLLM.new(m).wrap_each.to_a.first
+    out.tool_calls.first.should == Brute::ToolCall.new(id: "tc1", name: "shell", arguments: { "command" => "ls" })
+  end
+end

data/lib/brute/message_transport.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+
+module Brute
+  # Transports messages between an LLM library's format and Brute's format
+  # (Brute::Message). This is the seam that keeps Brute framework-agnostic:
+  # calling an LLM is trivial with any library, so Brute has no "completion
+  # middleware" — the terminal `run` proc of an agent pipeline makes the LLM
+  # call itself, and a MessageTransport translates at the boundary.
+  #
+  # Inbound (library response -> Brute), the transport wraps whatever the
+  # proc got back and yields each message as a Brute::Message; the proc
+  # appends:
+  #
+  #   response = client.complete(...)
+  #   Brute::MessageTransport::RubyLLM.new(response).wrap_each do |message|
+  #     env[:messages] << message
+  #   end
+  #
+  # Outbound (Brute -> library), `dump_all` converts env[:messages] into the
+  # shape the library's completion call expects:
+  #
+  #   client.complete(Brute::MessageTransport::RubyLLM.dump_all(env[:messages]), ...)
+  #
+  # This base class is the identity transport: it flattens the result into a
+  # list of messages and yields them untouched. Library-specific subclasses
+  # (see message_transport/*.rb) override #wrap and .dump. They reference
+  # their library lazily, so requiring the library is your job — Brute
+  # depends on none of them.
+  class MessageTransport
+    # Convenience: Brute::MessageTransport.wrap_each(result) { |m| ... }
+    def self.wrap_each(result, &block)
+      new(result).wrap_each(&block)
+    end
+
+    # Outbound: one Brute::Message in the library's format. Identity here.
+    def self.dump(message)
+      message
+    end
+
+    # Outbound: the whole log in the library's format.
+    def self.dump_all(messages)
+      messages.map { |message| dump(message) }
+    end
+
+    def initialize(result)
+      @result = result
+    end
+
+    # Yield each result message as a Brute::Message. Without a block, returns
+    # an Enumerator. The caller decides what to do with each (typically
+    # append to env[:messages]).
+    def wrap_each
+      return enum_for(:wrap_each) unless block_given?
+
+      messages.each { |message| yield wrap(message) }
+    end
+
+    # The result normalized to a flat list of the library's messages. A
+    # single message, an array, or anything transcript-shaped (responds to
+    # #messages).
+    def messages
+      case @result
+      when Array then @result.compact
+      else @result.respond_to?(:messages) ? @result.messages : [@result].compact
+      end
+    end
+
+    private
+
+      # The Brute::Message view of a single library message. Identity here —
+      # subclasses normalize their library's shape.
+      def wrap(message)
+        message
+      end
+  end
+end
+
+__END__
+
+describe "brute/message_transport" do
+  require "brute/messages"
+
+  it "wraps a single message" do
+    message = Brute::Message.new(role: :assistant, content: "hi")
+    Brute::MessageTransport.new(message).wrap_each.to_a.should == [message]
+  end
+
+  it "wraps an array of messages" do
+    a = Brute::Message.new(role: :assistant, content: "one")
+    b = Brute::Message.new(role: :tool, content: "two", tool_call_id: "tc1")
+    Brute::MessageTransport.new([a, b]).wrap_each.to_a.should == [a, b]
+  end
+
+  it "wraps a transcript-shaped object (responds to #messages)" do
+    fake_chat = Class.new do
+      attr_reader :messages
+      def initialize(messages); @messages = messages; end
+    end
+    msgs = [Brute::Message.new(role: :user, content: "hi"),
+            Brute::Message.new(role: :assistant, content: "hello")]
+
+    Brute::MessageTransport.new(fake_chat.new(msgs)).wrap_each.to_a.map(&:role).should == [:user, :assistant]
+  end
+
+  it "yields each message to the block for the caller to append" do
+    session = Brute.log
+    session.user("hello")
+    response = Brute::Message.new(role: :assistant, content: "hi there")
+
+    Brute::MessageTransport.new(response).wrap_each { |message| session << message }
+
+    session.last.role.should == :assistant
+    session.last.content.should == "hi there"
+  end
+
+  it "exposes a class-level wrap_each convenience" do
+    session = Brute.log
+    a = Brute::Message.new(role: :assistant, content: "a")
+    b = Brute::Message.new(role: :assistant, content: "b")
+
+    Brute::MessageTransport.wrap_each([a, b]) { |message| session << message }
+
+    session.map(&:content).should == ["a", "b"]
+  end
+
+  it "dump_all is the identity by default" do
+    msgs = [Brute::Message.new(role: :user, content: "hi")]
+    Brute::MessageTransport.dump_all(msgs).should == msgs
+  end
+end

data/lib/brute/messages.rb

@@ -4,14 +4,56 @@ require "bundler/setup"
 require "brute"
 
 module Brute
-  # The in-memory conversation log is just a plain Array of RubyLLM::Message.
+  # One tool invocation requested by the model. Arguments are always a Hash.
+  ToolCall = Data.define(:id, :name, :arguments) do
+    def initialize(id:, name:, arguments: {})
+      super(id: id, name: name.to_s, arguments: arguments.to_h)
+    end
+  end
+
+  # Brute's canonical, framework-agnostic message. The rest of the stack
+  # (middleware, tool loop, persistence) never calls anything beyond
+  # #role, #content, #tool_calls, #tool_call_id and #to_h — so any object
+  # that duck-types those methods can ride in env[:messages] too. This Data
+  # class is simply the canonical implementation.
+  #
+  #   Brute::Message.new(role: :user, content: "hi")
+  #   Brute::Message.new(role: :assistant, content: "", tool_calls: [
+  #     Brute::ToolCall.new(id: "tc1", name: "shell", arguments: { "command" => "ls" }),
+  #   ])
+  #   Brute::Message.new(role: :tool, content: "result", tool_call_id: "tc1")
+  Message = Data.define(:role, :content, :tool_calls, :tool_call_id) do
+    def initialize(role:, content: nil, tool_calls: nil, tool_call_id: nil)
+      tool_calls = tool_calls&.map do |tc|
+        tc.is_a?(ToolCall) ? tc : ToolCall.new(**tc.to_h.transform_keys(&:to_sym))
+      end
+      super(role: role.to_sym, content: content, tool_calls: tool_calls, tool_call_id: tool_call_id)
+    end
+
+    def tool_call?
+      !tool_calls.nil? && !tool_calls.empty?
+    end
+
+    # Plain, JSON-ready view (nils dropped, tool calls as hashes).
+    def to_h
+      h = super
+      h[:tool_calls] = tool_calls.map(&:to_h) if tool_calls
+      h.compact
+    end
+  end
+
+  # The in-memory conversation log is just a plain Array of Brute::Message.
   # This module adds a little sugar for appending role-tagged messages; mix it
   # into an array via `Brute.log`. Persistence is NOT here — loading/saving the
   # log to disk is the Brute::Middleware::SessionLog middleware's job.
   module Messages
-    def user(content);      self << ::RubyLLM::Message.new(role: :user,      content: content); end
-    def assistant(content); self << ::RubyLLM::Message.new(role: :assistant, content: content); end
-    def system(content);    self << ::RubyLLM::Message.new(role: :system,    content: content); end
+    def user(content);      self << Message.new(role: :user,      content: content); end
+    def assistant(content); self << Message.new(role: :assistant, content: content); end
+    def system(content);    self << Message.new(role: :system,    content: content); end
+
+    def tool(content, tool_call_id:)
+      self << Message.new(role: :tool, content: content, tool_call_id: tool_call_id)
+    end
   end
 
   # Build a fresh conversation log (an Array + Messages sugar), optionally
@@ -19,7 +61,7 @@ module Brute
   #
   #   log = Brute.log
   #   log.user("hello")
-  #   Brute.log(RubyLLM::Message.new(role: :user, content: "hi"))
+  #   Brute.log(Brute::Message.new(role: :user, content: "hi"))
   def self.log(*messages)
     [].extend(Messages).tap { |log| messages.flatten.each { |m| log << m } }
   end
@@ -36,12 +78,43 @@ describe "brute/messages" do
     log.first.content.should == "hi"
   end
 
+  it "appends tool results" do
+    log = Brute.log
+    log.tool("result", tool_call_id: "tc1")
+    log.last.role.should == :tool
+    log.last.tool_call_id.should == "tc1"
+  end
+
   it "seeds from given messages" do
-    m = RubyLLM::Message.new(role: :user, content: "seed")
+    m = Brute::Message.new(role: :user, content: "seed")
     Brute.log(m).should == [m]
   end
 
   it "is a plain Array (no special class)" do
     Brute.log.should.be.kind_of?(Array)
   end
+
+  it "symbolizes string roles" do
+    Brute::Message.new(role: "user", content: "hi").role.should == :user
+  end
+
+  it "coerces tool_calls hashes into ToolCall" do
+    m = Brute::Message.new(
+      role: :assistant, content: "",
+      tool_calls: [{ "id" => "tc1", "name" => "shell", "arguments" => { "command" => "ls" } }]
+    )
+    m.tool_calls.first.name.should == "shell"
+    m.tool_calls.first.arguments.should == { "command" => "ls" }
+    m.tool_call?.should.be.true
+  end
+
+  it "round-trips through to_h" do
+    m = Brute::Message.new(role: :assistant, content: "",
+                           tool_calls: [{ id: "tc1", name: "shell", arguments: {} }])
+    Brute::Message.new(**m.to_h).should == m
+  end
+
+  it "to_h drops nil fields" do
+    Brute::Message.new(role: :user, content: "hi").to_h.should == { role: :user, content: "hi" }
+  end
 end