brute 1.0.1 → 2.0.1

data/lib/brute/middleware/005_tracing.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+
+module Brute
+  module Middleware
+    # Logs timing and token usage for every LLM call, and tracks cumulative
+    # timing data in env[:metadata][:timing].
+    #
+    # As the outermost middleware, it sees the full pipeline elapsed time per
+    # call. It also tracks total wall-clock time across all calls in a turn
+    # (including tool execution gaps between LLM calls).
+    #
+    # A new turn is detected when env[:current_iteration] == 1 (the agent
+    # loop resets this at the start of each turn).
+    #
+    # Stores in env[:metadata][:timing]:
+    #   total_elapsed:     wall-clock since the turn began (includes tool gaps)
+    #   total_llm_elapsed: cumulative time spent inside LLM calls only
+    #   llm_call_count:    number of LLM calls so far
+    #   last_call_elapsed: duration of the most recent LLM call
+    #
+    class Tracing
+      def initialize(app, logger:)
+        @app = app
+
+        @logger = logger
+        @call_count = 0
+        @total_llm_elapsed = 0.0
+        @turn_start = nil
+      end
+
+      def call(env)
+        @call_count += 1
+
+        # Detect new turn via iteration counter
+        if env[:current_iteration] <= 1
+          @turn_start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          @total_llm_elapsed = 0.0
+        end
+
+        messages = env[:messages]
+        provider_name = env[:provider]&.respond_to?(:name) ? env[:provider].name : env[:provider].class.name
+        model_name = env[:model] || (env[:provider].default_model rescue "unknown")
+        @logger.debug("[brute] LLM call ##{@call_count} [#{provider_name}/#{model_name}] (#{messages.size} messages in context)")
+
+        start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        response = @app.call(env)
+        now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        elapsed = now - start
+
+        @total_llm_elapsed += elapsed
+
+        tokens = if response.respond_to?(:usage) && (usage = response.usage)
+          read_token(usage, :total_tokens)
+        else
+          '?'
+        end
+        @logger.debug("[brute] LLM response ##{@call_count} [#{provider_name}/#{model_name}]: #{tokens} tokens, #{elapsed.round(2)}s")
+        env[:events] << { type: :log, data: "LLM response ##{@call_count}: #{tokens} tokens, #{elapsed.round(2)}s" } if response
+
+        env[:metadata][:timing] = {
+          total_elapsed: now - (@turn_start || start),
+          total_llm_elapsed: @total_llm_elapsed,
+          llm_call_count: @call_count,
+          last_call_elapsed: elapsed
+        }
+
+        if response.respond_to?(:usage) && (u = response.usage)
+          env[:metadata][:tokens] = {
+            total:        read_token(u, :total_tokens),
+            total_input:  read_token(u, :input_tokens),
+            total_output: read_token(u, :output_tokens),
+          }
+        end
+
+        response
+      end
+
+      private
+
+      def read_token(usage, method)
+        if usage.respond_to?(method)
+          usage.send(method).to_i
+        elsif usage.respond_to?(:[])
+          (usage[method] || usage[method.to_s]).to_i
+        else
+          0
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+
+module Brute
+  module Middleware
+    # Guards against runaway tool loops by capping the number of iterations.
+    #
+    # When the limit is reached, injects a user message into the session
+    # stating that maximum iterations have been reached. This causes
+    # ToolResultLoop to exit its loop naturally (last message is not :tool).
+    #
+    class MaxIterations
+
+      DEFAULT_MAX_ITERATIONS = 100
+
+      def initialize(app, max_iterations: DEFAULT_MAX_ITERATIONS)
+        @app = app
+        @max_iterations = max_iterations
+      end
+
+      def call(env)
+        if max_iterations_reached?(env)
+          env[:messages] << RubyLLM::Message.new(
+            role: :user,
+            content: "Maximum iterations reached.",
+          )
+        else
+          @app.call(env)
+        end
+      end
+
+      private
+
+        def max_iterations_reached?(env)
+          env[:current_iteration] > @max_iterations
+        end
+    end
+  end
+end
+
+test do
+  require "brute/session"
+
+  it "can be added to a stack" do
+    called = false
+    inner = ->(env) { called = true }
+    mw = Brute::Middleware::MaxIterations.new(inner)
+    mw.call({ current_iteration: 1, messages: Brute::Session.new })
+    called.should.be.true
+  end
+
+  it "prevents execution after given max" do
+    called = false
+    inner = ->(env) { called = true }
+    mw = Brute::Middleware::MaxIterations.new(inner, max_iterations: 0)
+    env = { current_iteration: 1, messages: Brute::Session.new }
+    mw.call(env)
+    called.should.be.false
+  end
+
+  it "injects a user message when max is hit" do
+    inner = ->(env) { }
+    mw = Brute::Middleware::MaxIterations.new(inner, max_iterations: 0)
+    session = Brute::Session.new
+    session.user("hi")
+    env = { current_iteration: 1, messages: session }
+    mw.call(env)
+    env[:messages].last.role.should == :user
+    env[:messages].last.content.should =~ /Maximum iterations reached/
+  end
+end

data/lib/brute/middleware/015_otel_token_usage.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+
+module Brute
+  module Middleware
+    module OTel
+      # Records token usage from the LLM response as span attributes.
+      #
+      # Runs POST-call: reads token counts from the response usage object
+      # and sets them as attributes on the span.
+      #
+      class TokenUsage
+        def initialize(app)
+          @app = app
+        end
+
+        def call(env)
+          #response = @app.call(env)
+
+          #span = env[:span]
+          #if span && response.respond_to?(:usage) && (usage = response.usage)
+          #  span.set_attribute("gen_ai.usage.input_tokens", usage.input_tokens.to_i)
+          #  span.set_attribute("gen_ai.usage.output_tokens", usage.output_tokens.to_i)
+          #  span.set_attribute("gen_ai.usage.total_tokens", usage.total_tokens.to_i)
+
+          #  reasoning = usage.reasoning_tokens.to_i
+          #  span.set_attribute("gen_ai.usage.reasoning_tokens", reasoning) if reasoning > 0
+          #end
+
+          #response
+          @app.call(env)
+        end
+      end
+    end
+  end
+end
+
+test do
+  # not implemented
+end

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

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+
+module Brute
+  module Middleware
+    # Prepends a system message to env[:messages] before passing control
+    # down the middleware chain.
+    #
+    # By default, uses Brute::SystemPrompt.default which assembles a
+    # provider-specific prompt stack (Identity, ToneAndStyle, ToolUsage,
+    # etc.) from the Brute::Prompts modules and text files.
+    #
+    # Pass a custom Brute::SystemPrompt instance to override — useful
+    # for SubAgents that need a specialized prompt (e.g. the explore
+    # agent prompt):
+    #
+    #   use Brute::Middleware::SystemPrompt,
+    #       system_prompt: Brute::SystemPrompt.build { |p, _ctx|
+    #         p << Brute::Prompts.agent_prompt("explore")
+    #       }
+    #
+    # Skips injection when env[:messages] already contains a :system
+    # message (e.g. from session.system(...)), so manually-set system
+    # prompts are respected.
+    #
+    class SystemPrompt
+      def initialize(app, system_prompt: Brute::SystemPrompt.default)
+        @app = app
+        @system_prompt = system_prompt
+      end
+
+      def call(env)
+        unless env[:messages].any? { |m| m.role == :system }
+          ctx = build_context(env)
+          result = @system_prompt.prepare(ctx)
+          unless result.empty?
+            env[:messages].unshift(
+              RubyLLM::Message.new(role: :system, content: result.to_s)
+            )
+          end
+        end
+
+        @app.call(env)
+      end
+
+      private
+
+        def build_context(env)
+          {
+            provider_name: env[:provider].to_s,
+            model_name:    env[:model].to_s,
+            cwd:           Dir.pwd,
+          }.merge(env.fetch(:metadata, {}))
+        end
+    end
+  end
+end
+
+test do
+  require "brute/session"
+
+  def build_middleware(system_prompt: Brute::SystemPrompt.default, &inner_block)
+    inner = inner_block || ->(env) { env }
+    Brute::Middleware::SystemPrompt.new(inner, system_prompt: system_prompt)
+  end
+
+  def base_env(messages: Brute::Session.new)
+    {
+      messages: messages,
+      provider: :anthropic,
+      model:    "claude-sonnet-4-20250514",
+      metadata: {},
+    }
+  end
+
+  it "prepends a system message when none exists" do
+    mw = build_middleware
+    env = base_env
+    env[:messages].user("hi")
+
+    mw.call(env)
+
+    env[:messages].first.role.should == :system
+  end
+
+  it "skips injection when a system message already exists" do
+    mw = build_middleware
+    env = base_env
+    env[:messages].system("custom prompt")
+    env[:messages].user("hi")
+
+    mw.call(env)
+
+    env[:messages].select { |m| m.role == :system }.size.should == 1
+    env[:messages].first.content.should == "custom prompt"
+  end
+
+  it "accepts a custom system_prompt" do
+    custom = Brute::SystemPrompt.build { |p, _ctx| p << "You are a test agent." }
+    mw = build_middleware(system_prompt: custom)
+    env = base_env
+    env[:messages].user("hi")
+
+    mw.call(env)
+
+    env[:messages].first.role.should == :system
+    env[:messages].first.content.should == "You are a test agent."
+  end
+
+  it "merges metadata into context" do
+    captured_ctx = nil
+    spy_prompt = Brute::SystemPrompt.build do |p, ctx|
+      captured_ctx = ctx
+      p << "ok"
+    end
+    mw = build_middleware(system_prompt: spy_prompt)
+    env = base_env
+    env[:metadata][:agent] = "plan"
+    env[:messages].user("hi")
+
+    mw.call(env)
+
+    captured_ctx[:agent].should == "plan"
+    captured_ctx[:provider_name].should == "anthropic"
+  end
+end

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

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+
+module Brute
+  module Middleware
+    # Checks context size after each LLM call and triggers compaction
+    # when thresholds are exceeded.
+    #
+    # It should add a compaction event to the logs with the context token
+    # total listed... this way a model that supports extra context can
+    # include the compaction as well as the previous messages...
+    #
+    # Or an LLM that doesn't support it can just use the messages
+    # that come after the compaction
+    #
+    class CompactionCheck
+      def initialize(app, compactor: nil, system_prompt:, **compactor_opts)
+        @app = app
+        @compactor = compactor
+        @compactor_opts = compactor_opts
+        @system_prompt = system_prompt
+      end
+
+      def call(env)
+        #@compactor ||= Compactor.new(env[:provider], **@compactor_opts)
+
+        #messages = env[:messages]
+        #usage = env[:metadata].dig(:tokens, :last_call)
+
+        #if @compactor.should_compact?(messages, usage: usage)
+        #  result = @compactor.compact(messages)
+        #  if result
+        #    summary_text, _recent = result
+        #    env[:metadata][:compaction] = {
+        #      messages_before: messages.size,
+        #      timestamp: Time.now.iso8601,
+        #    }
+        #    # 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}"),
+        #    ]
+        #  end
+        #end
+
+        @app.call(env)
+      end
+
+      # Context compaction service. When the conversation grows past configurable
+      # thresholds, older messages are summarized into a condensed form and the
+      # original messages are dropped, keeping the context window manageable.
+      class Compactor
+        DEFAULTS = {
+          token_threshold: 100_000,   # Compact when estimated tokens exceed this
+          message_threshold: 200,     # Compact when message count exceeds this
+          retention_window: 6,        # Minimum recent messages to always keep
+          summary_model: nil,         # Model for summarization (uses agent's model if nil)
+        }.freeze
+
+        attr_reader :config
+
+        def initialize(provider, **opts)
+          @provider = provider
+          @config = DEFAULTS.merge(opts)
+        end
+
+        # Check whether compaction should run based on current context state.
+        def should_compact?(messages, usage: nil)
+          return true if messages.size > @config[:message_threshold]
+          return true if usage && (usage[:total] || 0) > @config[:token_threshold]
+          false
+        end
+
+        # Compact the message history by summarizing older messages.
+        #
+        # Returns [summary_message, kept_messages] — the caller rebuilds
+        # the context from these.
+        def compact(messages)
+          total = messages.size
+          keep_count = [@config[:retention_window], total].min
+          return nil if total <= keep_count
+
+          old_messages = messages[0...(total - keep_count)]
+          recent_messages = messages[(total - keep_count)..]
+
+          summary_text = summarize(old_messages)
+
+          [summary_text, recent_messages]
+        end
+
+        private
+
+        def summarize(messages)
+          # Build a condensed representation of the conversation for the summarizer
+          conversation_text = messages.map { |m|
+            role = if m.respond_to?(:role)
+              m.role.to_s
+            else
+              "unknown"
+            end
+            content = if m.respond_to?(:content)
+              m.content.to_s[0..1000]
+            else
+              m.to_s[0..1000]
+            end
+
+            # Include tool call info for assistant messages
+            tool_info = ""
+            if m.respond_to?(:functions) && m.functions&.any?
+              calls = m.functions.map { |f| "#{f.name}(#{f.arguments.to_s[0..200]})" }
+              tool_info = " [tools: #{calls.join(", ")}]"
+            end
+
+            "#{role}:#{tool_info} #{content}"
+          }.join("\n---\n")
+
+          prompt = <<~PROMPT
+            Summarize this conversation history for context continuity. The summary will replace
+            these messages in the context window, so include everything the agent needs to continue
+            working effectively.
+
+            Structure your summary as:
+            ## Goal
+            What the user asked for.
+
+            ## Progress
+            - Files read, created, or modified (list paths)
+            - Commands executed and their outcomes
+            - Key decisions made
+
+            ## Current State
+            Where things stand right now — what's done and what remains.
+
+            ## Next Steps
+            What should happen next based on the conversation.
+
+            ---
+            CONVERSATION:
+            #{conversation_text}
+          PROMPT
+
+          model = @config[:summary_model] || "claude-sonnet-4-20250514"
+          res = @provider.complete(prompt, model: model)
+          res.content
+        end
+      end
+    end
+  end
+end
+
+test do
+  # not implemented
+end

data/lib/brute/middleware/060_questions.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+
+module Brute
+  module Middleware
+    class Question
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        @app.call(env).tap do
+          #if env[:messages].last.tool_call?
+          #  questions = last_message.tool_calls.select { |_id, tc| tc.name == "question" }
+
+          #  if questions.any?
+          #    env[:events] << {
+          #      type: :tool_call_start,
+          #      data: questions.map { |_id, tc| { name: tc.name, call_id: tc.id, arguments: tc.arguments } }
+          #    }
+
+          #    questions.each do |_id, question|
+          #      result = question.call
+
+          #      env[:events] << { type: :tool_result, data: { name: tc.name, content: content } }
+
+          #      env[:messages] << RubyLLM::Message.new(role: :tool, content: content, tool_call_id: tc.id)
+          #    end
+          #  end
+          #end
+        end
+      end
+    end
+  end
+end
+
+test do
+  # not implemented
+end