dexter_llm 0.1.2

data/lib/dexter_llm/agent/loop.rb

@@ -0,0 +1,256 @@
+# frozen_string_literal: true
+
+require "async"
+
+module DexterLlm::Agent
+  class Loop
+    def initialize(state:, client:, session_id:, run_id:, signal: nil, steering_queue: nil, emit_event: nil)
+      @state = state
+      @client = client
+      @session_id = session_id
+      @run_id = run_id
+      @signal = signal
+      @steering_queue = steering_queue
+      @emit_event = emit_event
+      @emit_mutex = Mutex.new
+      @turn = 0
+    end
+
+    def run(prompt, attachments: [])
+      @signal&.throw_if_cancelled!
+
+      user_content = build_user_content(prompt, attachments)
+      user_message = DexterLlm::UserMessage.new(user_content)
+
+      state = @state.add_message(user_message)
+      emit(:user_message, user_message.to_h)
+
+      loop do
+        @signal&.throw_if_cancelled!
+        raise MaxIterationsError.new(state.max_iterations) if state.max_iterations_reached?
+
+        @turn += 1
+        emit(:turn_start, { turn: @turn })
+
+        state, assistant_message = run_turn(state)
+        emit(:turn_end, { turn: @turn, stop_reason: assistant_message.stop_reason.to_s })
+
+        break unless should_continue?(assistant_message)
+      end
+
+      [ state, state.last_message ]
+    end
+
+    private
+
+    def build_user_content(prompt, attachments)
+      content = [ DexterLlm::Content::Text.new(prompt) ]
+      attachments.each { |att| content << att }
+      content
+    end
+
+    def run_turn(state)
+      assistant_message = stream_completion(state)
+      new_state = state.add_message(assistant_message)
+
+      # Execute tool calls if present
+      if assistant_message.has_tool_calls?
+        new_state = execute_tool_calls(new_state, assistant_message.tool_calls)
+      end
+
+      [ new_state, assistant_message ]
+    end
+
+    def execute_tool_calls(state, tool_calls)
+      # Filter out built-in tools (executed server-side)
+      user_tool_calls = tool_calls.reject do |tool_call|
+        tool = state.tool_by_name(tool_call.name)
+        tool&.respond_to?(:built_in?) && tool.built_in?
+      end
+
+      return state if user_tool_calls.empty?
+
+      # Collect results keyed by tool call ID to preserve ordering
+      result_messages = {}
+      results_mutex = Mutex.new
+      steered = false
+
+      # Execute all tools in parallel using fibers
+      Sync do
+        user_tool_calls.each do |tool_call|
+          # Check for steering message before starting next tool
+          if @steering_queue && !@steering_queue.empty?
+            steered = true
+            break
+          end
+
+          Async do
+            @signal&.throw_if_cancelled!
+
+            # Emit start event
+            emit(:tool_call_start, {
+              id: tool_call.id,
+              name: tool_call.name,
+              arguments: tool_call.arguments
+            })
+
+            # Execute tool
+            result_message = execute_single_tool(state, tool_call)
+
+            # Store result keyed by tool call ID (thread-safe)
+            results_mutex.synchronize do
+              result_messages[tool_call.id] = result_message if result_message
+            end
+
+            # Emit end event
+            if result_message
+              emit(:tool_call_end, {
+                id: tool_call.id,
+                name: tool_call.name,
+                is_error: result_message.is_error,
+                result: result_message.content.map { |c| c.respond_to?(:text) ? c.text : c.to_s }.join
+              })
+            end
+          end
+        end
+      end
+
+      # Add completed results to state in original tool call order
+      user_tool_calls.each do |tool_call|
+        result_message = result_messages[tool_call.id]
+        state = state.add_message(result_message) if result_message
+      end
+
+      # If steered, add synthetic error results for skipped tools and inject steering message
+      if steered
+        skipped_calls = user_tool_calls.reject { |tc| result_messages.key?(tc.id) }
+        skipped_calls.each do |tool_call|
+          state = state.add_message(
+            DexterLlm::ToolResultMessage.new(
+              tool_call_id: tool_call.id,
+              tool_name: tool_call.name,
+              content: "Tool execution skipped: user sent a steering message",
+              is_error: true
+            )
+          )
+        end
+
+        # Inject steering message as a user message
+        steering_text = @steering_queue.pop(true) rescue nil
+        if steering_text
+          user_message = DexterLlm::UserMessage.new([ DexterLlm::Content::Text.new(steering_text) ])
+          state = state.add_message(user_message)
+          emit(:user_message, user_message.to_h)
+        end
+      end
+
+      state
+    end
+
+    def execute_single_tool(state, tool_call)
+      tool = state.tool_by_name(tool_call.name)
+
+      unless tool
+        return DexterLlm::ToolResultMessage.new(
+          tool_call_id: tool_call.id,
+          tool_name: tool_call.name,
+          content: "Unknown tool: #{tool_call.name}",
+          is_error: true
+        )
+      end
+
+      # Built-in tools are executed server-side by the provider.
+      # We should not attempt to execute them locally.
+      if tool.respond_to?(:built_in?) && tool.built_in?
+        return nil
+      end
+
+      begin
+        result = tool.call(tool_call.arguments)
+        result_content = result.is_a?(String) ? result : result.to_s
+
+        DexterLlm::ToolResultMessage.new(
+          tool_call_id: tool_call.id,
+          tool_name: tool_call.name,
+          content: result_content,
+          is_error: false
+        )
+      rescue DexterLlm::ToolExecutionError => e
+        DexterLlm::ToolResultMessage.new(
+          tool_call_id: tool_call.id,
+          tool_name: tool_call.name,
+          content: e.message,
+          is_error: true
+        )
+      rescue StandardError => e
+        DexterLlm::ToolResultMessage.new(
+          tool_call_id: tool_call.id,
+          tool_name: tool_call.name,
+          content: "Error: #{e.class}: #{e.message}",
+          is_error: true
+        )
+      end
+    end
+
+    def stream_completion(state)
+      @signal&.throw_if_cancelled!
+
+      stream = @client.stream(
+        model: state.model,
+        messages: state.messages,
+        system_prompt: state.system_prompt,
+        tools: state.tools,
+        thinking_config: state.thinking_config
+      )
+
+      final_message = nil
+
+      stream.each do |event|
+        @signal&.throw_if_cancelled!
+        emit(:stream_event, event.to_h)
+
+        case event
+        when DexterLlm::StreamEvent::Done
+          final_message = event.message
+        when DexterLlm::StreamEvent::Error
+          raise event.error
+        end
+      end
+
+      raise DexterLlm::Error, "Stream completed without final message" if final_message.nil?
+
+      emit(:assistant_message, final_message.to_h)
+      final_message
+    end
+
+    def should_continue?(assistant_message)
+      # Continue if there were tool calls (agent loop continues until no more tools)
+      return true if assistant_message.has_tool_calls?
+      return true if assistant_message.stop_reason == DexterLlm::StopReason::TOOL_USE
+
+      # Stop on terminal reasons
+      return false if assistant_message.stop_reason == DexterLlm::StopReason::STOP
+      return false if assistant_message.stop_reason == DexterLlm::StopReason::LENGTH
+      return false if assistant_message.stop_reason == DexterLlm::StopReason::ERROR
+      return false if assistant_message.stop_reason == DexterLlm::StopReason::ABORTED
+
+      false
+    end
+
+    def emit(type, data)
+      return unless @emit_event
+
+      event = Event.new(
+        session_id: @session_id,
+        run_id: @run_id,
+        turn: @turn,
+        type: type.to_s,
+        data: data
+      )
+
+      @emit_mutex.synchronize do
+        @emit_event.call(event)
+      end
+    end
+  end
+end

data/lib/dexter_llm/agent/max_iterations_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module DexterLlm::Agent
+  class MaxIterationsError < Error
+    def initialize(max_iterations)
+      super("Agent exceeded maximum iterations (#{max_iterations})")
+    end
+  end
+end

data/lib/dexter_llm/agent/session.rb

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+module DexterLlm::Agent
+  class Session
+    attr_reader :agent, :session_manager, :compaction_settings
+
+    def initialize(agent:, session_manager:, compaction_settings: nil, client: nil)
+      @agent = agent
+      @session_manager = session_manager
+      @compaction_settings = compaction_settings || DexterLlm::Session::CompactionSettings.new
+      @client = client
+      @event_listeners = []
+      @last_assistant_message = nil
+      @retry_pending = false
+
+      # Subscribe to agent events for auto-persistence
+      @agent.on_event { |event| handle_agent_event(event) }
+    end
+
+    def session_id
+      @session_manager.session_id
+    end
+
+    def prompt(text, attachments: [])
+      if @retry_pending
+        @retry_pending = false
+        return @agent.prompt(text, attachments:)
+      end
+
+      begin
+        @agent.prompt(text, attachments:)
+      rescue DexterLlm::ContextOverflowError
+        handle_overflow_compaction
+        @agent.prompt(text, attachments:)
+      end
+    end
+
+    def abort(reason = "User aborted")
+      @agent.abort(reason)
+    end
+
+    def running?
+      @agent.running?
+    end
+
+    def messages
+      @agent.messages
+    end
+
+    def model
+      @agent.model
+    end
+
+    def reset
+      @agent.reset
+    end
+
+    def steer(text)
+      @agent.steer(text)
+    end
+
+    def follow_up(text)
+      @agent.follow_up(text)
+    end
+
+    def clear_steering_queue
+      @agent.clear_steering_queue
+    end
+
+    def clear_follow_up_queue
+      @agent.clear_follow_up_queue
+    end
+
+    def on_event(&handler)
+      @event_listeners << handler
+      -> { @event_listeners.delete(handler) }
+    end
+
+    def load
+      loaded = @session_manager.load
+      return loaded if loaded.empty?
+
+      # Replace agent state with loaded messages
+      new_state = State.new(
+        model: @agent.state.model,
+        messages: loaded.messages,
+        system_prompt: @agent.state.system_prompt,
+        tools: @agent.state.tools,
+        max_iterations: @agent.state.max_iterations
+      )
+
+      @agent.instance_variable_set(:@state, new_state)
+      @session_manager.instance_variable_set(:@session_initialized, true)
+
+      loaded
+    end
+
+    def compact(custom_instructions: nil)
+      # Ensure agent is not running
+      raise Agent::AgentBusyError.new if @agent.running?
+
+      entries = @session_manager.load_entries
+      return nil if entries.empty?
+
+      compaction_entry = DexterLlm::Session::Compaction.compact(
+        entries: entries,
+        model: @agent.model,
+        client: client,
+        settings: @compaction_settings,
+        custom_instructions: custom_instructions
+      )
+
+      @session_manager.save_compaction(compaction_entry)
+
+      # Reload session with compacted state
+      loaded = @session_manager.load
+
+      # Replace agent state
+      new_state = State.new(
+        model: @agent.state.model,
+        messages: loaded.messages,
+        system_prompt: @agent.state.system_prompt,
+        tools: @agent.state.tools,
+        max_iterations: @agent.state.max_iterations
+      )
+
+      @agent.instance_variable_set(:@state, new_state)
+
+      {
+        tokens_before: compaction_entry.tokens_before,
+        summary: compaction_entry.summary
+      }
+    end
+
+    private
+
+    def client
+      @client ||= @agent.instance_variable_get(:@client) || DexterLlm::Client.new
+    end
+
+    def handle_agent_event(event)
+      emit(event)
+
+      case event.type
+      when "user_message"
+        ensure_session_started!
+        save_message_from_event(event.data)
+
+      when "assistant_message"
+        ensure_session_started!
+        @last_assistant_message = create_assistant_message_from_event(event.data)
+        save_message_from_event(event.data)
+
+        # Initialize session after first exchange
+        if @session_manager.should_initialize_session?(@agent.messages)
+          @session_manager.start_session(@agent.state)
+        end
+
+      when "tool_call_end"
+        ensure_session_started!
+        # Tool results are emitted as tool_call_end events, need to construct message
+        tool_result = DexterLlm::ToolResultMessage.new(
+          tool_call_id: event.data["id"] || event.data[:id],
+          tool_name: event.data["name"] || event.data[:name],
+          content: event.data["result"] || event.data[:result],
+          is_error: event.data["is_error"] || event.data[:is_error] || false
+        )
+        @session_manager.save_message(tool_result)
+
+      when "turn_end"
+        # Check for auto-compaction after turn completes
+        check_auto_compaction if @last_assistant_message
+        @last_assistant_message = nil
+      end
+    end
+
+    def save_message_from_event(data)
+      # data is already a hash from message.to_h, reconstruct the message
+      message = DexterLlm::Session::Entry::Message.send(:deserialize_message, data)
+      @session_manager.save_message(message) if message
+    end
+
+    def ensure_session_started!
+      return if @session_manager.session_initialized?
+
+      @session_manager.start_session(@agent.state)
+    end
+
+    def create_assistant_message_from_event(data)
+      DexterLlm::Session::Entry::Message.send(:deserialize_message, data)
+    end
+
+    def check_auto_compaction
+      return unless @compaction_settings.enabled
+      return unless @last_assistant_message
+
+      message = @last_assistant_message
+      return if message.stop_reason == :aborted
+
+      context_window = @agent.model.respond_to?(:context_window) ? @agent.model.context_window : 128_000
+
+      # Case 1: Check for context overflow
+      if context_overflow?(message)
+        handle_overflow_compaction
+        return
+      end
+
+      # Case 2: Threshold exceeded - compact (no retry)
+      return if message.stop_reason == :error
+
+      estimated_prompt_tokens = DexterLlm::Session::Compaction.estimate_prompt_tokens(@agent.messages)
+      usage_prompt_tokens = DexterLlm::Session::Compaction.calculate_prompt_tokens_from_usage(message.usage)
+      prompt_tokens = [ estimated_prompt_tokens, usage_prompt_tokens ].max
+
+      if DexterLlm::Session::Compaction.should_compact?(prompt_tokens, context_window, @compaction_settings)
+        run_auto_compaction(reason: :threshold, will_retry: false)
+      end
+    end
+
+    def context_overflow?(message)
+      return false unless message.stop_reason == :error
+
+      text = message.respond_to?(:text) ? message.text : ""
+      DexterLlm::ApiError.context_overflow_body?(text)
+    end
+
+    def handle_overflow_compaction
+      # Remove the error message from agent state
+      current_messages = @agent.messages[0..-2]
+      new_state = State.new(
+        model: @agent.state.model,
+        messages: current_messages,
+        system_prompt: @agent.state.system_prompt,
+        tools: @agent.state.tools,
+        max_iterations: @agent.state.max_iterations
+      )
+      @agent.instance_variable_set(:@state, new_state)
+
+      run_auto_compaction(reason: :overflow, will_retry: true)
+    end
+
+    def run_auto_compaction(reason:, will_retry:)
+      emit_compaction_event(:auto_compaction_start, { reason: reason })
+
+      begin
+        result = compact
+        emit_compaction_event(:auto_compaction_end, { result: result, will_retry: will_retry })
+
+        @retry_pending = will_retry
+      rescue StandardError => e
+        emit_compaction_event(:auto_compaction_end, { result: nil, error: e.message })
+        raise if reason == :overflow
+      end
+    end
+
+    def emit_compaction_event(type, data)
+      event = Event.new(
+        session_id: session_id,
+        run_id: "compaction",
+        turn: 0,
+        type: type.to_s,
+        data: data
+      )
+      emit(event)
+    end
+
+    def emit(event)
+      @event_listeners.each { |l| l.call(event) }
+    end
+  end
+end

data/lib/dexter_llm/agent/state.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module DexterLlm::Agent
+  class State
+    DEFAULT_MAX_ITERATIONS = 50
+
+    attr_reader :messages, :model, :system_prompt, :tools, :max_iterations, :thinking_config
+
+    def initialize(model:, messages: [], system_prompt: nil, tools: [], max_iterations: DEFAULT_MAX_ITERATIONS, thinking_config: nil)
+      @messages = messages.freeze
+      @model = model
+      @system_prompt = system_prompt
+      @tools = tools.freeze
+      @max_iterations = max_iterations
+      @thinking_config = thinking_config
+    end
+
+    def add_message(message)
+      State.new(
+        model:,
+        messages: messages + [ message ],
+        system_prompt:,
+        tools:,
+        max_iterations:,
+        thinking_config:
+      )
+    end
+
+    def with_model(new_model)
+      State.new(
+        model: new_model,
+        messages:,
+        system_prompt:,
+        tools:,
+        max_iterations:,
+        thinking_config:
+      )
+    end
+
+    def with_system_prompt(new_prompt)
+      State.new(
+        model:,
+        messages:,
+        system_prompt: new_prompt,
+        tools:,
+        max_iterations:,
+        thinking_config:
+      )
+    end
+
+    def tool_by_name(name)
+      tools.find { |t| t.respond_to?(:name) && t.name.to_s == name.to_s }
+    end
+
+    def iteration_count
+      messages.count { |m| m.role == :assistant }
+    end
+
+    def max_iterations_reached?
+      iteration_count >= max_iterations
+    end
+
+    def last_message
+      messages.last
+    end
+
+    def last_assistant_message
+      messages.reverse_each.find { |m| m.role == :assistant }
+    end
+
+    def empty?
+      messages.empty?
+    end
+  end
+end

data/lib/dexter_llm/api.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module DexterLlm
+  module Api
+    ANTHROPIC_MESSAGES = :anthropic_messages
+    OPENAI_RESPONSES = :openai_responses
+    GOOGLE_GENERATIVE = :google_generative
+  end
+end

data/lib/dexter_llm/api_error.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module DexterLlm
+  class ApiError < Error
+    def initialize(message = nil, status: nil, body: nil)
+      @status = status&.to_i
+      @body = body
+      super(message)
+    end
+
+    attr_reader :status, :body
+
+    CONTEXT_OVERFLOW_PATTERNS = [
+      /prompt is too long/i,
+      /exceeds? the (model's )?maximum context/i,
+      /context.length.exceeded/i,
+      /maximum.context.length/i,
+      /token limit/i,
+      /input is too long/i,
+      /request too large/i,
+      /exceeds? [\d,]+ tokens?/i,
+      /content.too.large/i,
+      /max_tokens.*must be less/i,
+      /input.*exceeds.*limit/i,
+      /context window/i
+    ].freeze
+
+    def self.for_status(status, message = nil, body: nil)
+      status = status&.to_i
+
+      klass =
+        case status
+        when 400
+          context_overflow_body?(body) ? ContextOverflowError : InvalidRequestError
+        when 401, 403
+          AuthenticationError
+        when 413
+          ContextOverflowError
+        when 429
+          RateLimitError
+        else
+          ApiError
+        end
+
+      klass.new(message, status: status, body: body)
+    end
+
+    def self.context_overflow_body?(body)
+      return false if body.nil? || body.to_s.empty?
+
+      text = body.to_s
+      CONTEXT_OVERFLOW_PATTERNS.any? { |pattern| text.match?(pattern) }
+    end
+  end
+end