brute 2.0.6 → 3.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ca9915157a21335990328dcbf4b6104cffa72bd0835e93055ec46e8be05aee7
-  data.tar.gz: 6e7ef36a7fd32e0351563856d888f832fb4d48fad32444f937fb58c2d45baa4d
+  metadata.gz: c25e73819e947f92a37f144411ba27b09f93cc48088bc0cc474247bc81149658
+  data.tar.gz: 635eff80312c14656cf2a6168f2f4ee9279413ac285e580a58e959812a9e5d4d
 SHA512:
-  metadata.gz: ff22892e28c30deb694b7bbea899e8b14ceb31e068fa74b27b9b462d7778ab52da06f332f743ac6c19324bf962d7ee1401e8146f1714496fc1dcba5179f6e551
-  data.tar.gz: 457fbacd0115628b002c6b274ef7c07d47a267c4841107c52c4d983d23a0967012ca68a084b50f833d5421ff013766c2aef07be5e465d8630ca61cc9c06326f5
+  metadata.gz: c43c126ae04f4642df67df70ab780dfc11ef2070709580cc409d6b32652a2f0be41730d252a06d9029f8d156657877f046af6a06d5c2ba1d4ee9a2d5fda75d97
+  data.tar.gz: 26599b1c63616c87af1c8537dfe4e473be5a70ee408058b31fb8a67c5203f72b81d41a868e59ceb8831ac570a74a9132c6c2df42794b116ea91e67b70a4441dc

data/lib/brute/events/handler.rb

@@ -25,6 +25,8 @@ module Brute
   end
 end
 
-test do
+__END__
+
+describe "brute/events/handler" do
   # not implemented
 end

data/lib/brute/events/prefixed_terminal_output.rb

@@ -67,6 +67,8 @@ module Brute
   end
 end
 
-test do
+__END__
+
+describe "brute/events/prefixed_terminal_output" do
   # not implemented
 end

data/lib/brute/events/terminal_output_handler.rb

@@ -63,6 +63,8 @@ module Brute
   end
 end
 
-test do
+__END__
+
+describe "brute/events/terminal_output_handler" do
   # not implemented
 end

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