ruby-pi 0.1.3 → 0.1.5

data/lib/ruby_pi/agent/loop.rb

@@ -31,16 +31,32 @@ module RubyPi
     #   loop = RubyPi::Agent::Loop.new(state: state, emitter: agent)
     #   result = loop.run
     class Loop
+      # Issue #18: Programming errors that should NOT be rescued by the loop.
+      # These indicate bugs in the calling code, not LLM/provider/tool failures.
+      # Rescuing them would silently swallow real bugs like typos or type mismatches.
+      PROGRAMMING_ERRORS = [
+        NoMethodError,
+        NameError,
+        ArgumentError,
+        TypeError
+      ].freeze
+
       # Creates a new Loop bound to the given state and event emitter.
       #
       # @param state [RubyPi::Agent::State] mutable agent state
       # @param emitter [#emit] object that responds to `emit(event, data)`
       # @param compaction [RubyPi::Context::Compaction, nil] optional compaction
       #   strategy for managing context window size
-      def initialize(state:, emitter:, compaction: nil)
+      # @param execution_mode [Symbol] tool execution mode (:parallel or
+      #   :sequential, default: :parallel)
+      # @param tool_timeout [Numeric] per-tool execution timeout in seconds
+      #   (default: 30)
+      def initialize(state:, emitter:, compaction: nil, execution_mode: :parallel, tool_timeout: 30)
         @state = state
         @emitter = emitter
         @compaction = compaction
+        @execution_mode = execution_mode
+        @tool_timeout = tool_timeout
         @tool_calls_made = []
         @total_usage = { input_tokens: 0, output_tokens: 0 }
       end
@@ -49,12 +65,24 @@ module RubyPi
       # Returns an Agent::Result capturing the final content, messages, tool
       # calls, usage, and turn count.
       #
+      # Issue #18: Re-raises programming errors (NoMethodError, NameError,
+      # ArgumentError, TypeError) instead of swallowing them. Only LLM/provider/
+      # tool errors are caught and wrapped in a failed Result.
+      #
+      # Issue #19: When max_iterations is reached, the Result now includes
+      # stop_reason: :max_iterations and success? returns false. Previously,
+      # the Result had no error set, so success? returned true even though
+      # the agent was forcibly stopped.
+      #
       # @return [RubyPi::Agent::Result] the outcome of the agent run
       def run
         loop do
           # Check iteration limit before starting a new turn
           if @state.max_iterations_reached?
-            return build_result(content: last_assistant_content)
+            return build_result(
+              content: last_assistant_content,
+              stop_reason: :max_iterations
+            )
           end
 
           # Apply context compaction if configured and needed
@@ -78,9 +106,14 @@ module RubyPi
           else
             # No tool calls — the LLM is done
             @emitter.emit(:turn_end, turn: @state.iteration, has_tool_calls: false)
-            return build_result(content: response.content)
+            return build_result(content: response.content, stop_reason: :complete)
           end
         end
+      rescue *PROGRAMMING_ERRORS
+        # Issue #18: Re-raise programming errors immediately. These are bugs
+        # in the calling code (typos, wrong argument counts, type mismatches)
+        # that should never be silently swallowed.
+        raise
       rescue StandardError => e
         @emitter.emit(:error, error: e, source: :agent_loop)
         Result.new(
@@ -89,14 +122,15 @@ module RubyPi
           tool_calls_made: @tool_calls_made,
           usage: @total_usage,
           turns: @state.iteration,
-          error: e
+          error: e,
+          stop_reason: :error
         )
       end
 
       private
 
       # THINK phase: applies transforms, calls the LLM, and streams text
-      # deltas back through the emitter.
+      # deltas and tool call deltas back through the emitter.
       #
       # @return [RubyPi::LLM::Response] the LLM response
       def think
@@ -123,6 +157,20 @@ module RubyPi
           if event.text_delta?
             streamed_content << event.data.to_s
             @emitter.emit(:text_delta, content: event.data)
+          elsif event.tool_call_delta?
+            # Emit tool call delta events so subscribers can observe partial
+            # tool call data as it streams in (e.g. for progress indicators
+            # or incremental JSON parsing).
+            @emitter.emit(:tool_call_delta, data: event.data)
+          elsif event.fallback_start?
+            # The primary LLM provider failed mid-stream and a Fallback
+            # provider is now taking over. Discard the partial text we
+            # accumulated from the failed primary so the agent's recorded
+            # response reflects only the fallback's output, and surface a
+            # :provider_fallback event so subscribers can clear any UI
+            # state they rendered from the discarded primary deltas.
+            streamed_content.clear
+            @emitter.emit(:provider_fallback, **event.data)
           end
         end
 
@@ -137,26 +185,48 @@ module RubyPi
       end
 
       # ACT phase: executes each tool call from the LLM response, firing
-      # lifecycle hooks and events around each execution.
+      # lifecycle hooks and events around each execution. Uses the
+      # execution_mode and tool_timeout configured on the Loop.
+      #
+      # Issue #17: Checks for nil/empty tools before creating the Executor.
+      # If the LLM hallucinates tool calls but no tools are registered,
+      # raises NoToolsRegisteredError instead of crashing with NoMethodError.
       #
       # @param response [RubyPi::LLM::Response] the LLM response with tool calls
       # @return [void]
       def act(response)
+        # Issue #17: Guard against nil tools — if the model returned tool calls
+        # but no tools are registered, raise a clear typed error.
+        if @state.tools.nil?
+          raise RubyPi::NoToolsRegisteredError,
+                "Model returned #{response.tool_calls.size} tool call(s) but no tools are registered"
+        end
+
         executor = RubyPi::Tools::Executor.new(
           @state.tools,
-          mode: :parallel,
-          timeout: 30
+          mode: @execution_mode,
+          timeout: @tool_timeout
         )
 
+        # Symbolize the JSON-parsed (string-keyed) tool_call arguments once,
+        # up front. Both the executor (which actually invokes the tool block)
+        # and the recorded `tool_calls_made` payload use this symbol-keyed
+        # form, keeping a single consistent shape across the pipeline rather
+        # than mixing string keys (raw from JSON) and symbol keys (post-
+        # symbolize) in different places.
+        symbolized = response.tool_calls.map do |tc|
+          RubyPi::Tools::Executor.deep_symbolize_keys(tc.arguments)
+        end
+
         # Prepare call hashes for the executor
-        calls = response.tool_calls.map do |tc|
-          { name: tc.name, arguments: tc.arguments }
+        calls = response.tool_calls.each_with_index.map do |tc, idx|
+          { name: tc.name, arguments: symbolized[idx] }
         end
 
         # Fire before_tool_call hooks and emit start events
-        response.tool_calls.each do |tc|
+        response.tool_calls.each_with_index do |tc, idx|
           @state.before_tool_call&.call(tc)
-          @emitter.emit(:tool_execution_start, tool_name: tc.name, arguments: tc.arguments)
+          @emitter.emit(:tool_execution_start, tool_name: tc.name, arguments: symbolized[idx])
         end
 
         # Execute all tool calls
@@ -173,15 +243,28 @@ module RubyPi
                         success: result.success?,
                         duration_ms: result.duration_ms)
 
-          # Record the tool call for the final result
+          # Record the tool call for the final result, using the symbolized
+          # arguments so callers see the same shape the tool itself received.
           @tool_calls_made << {
             tool_name: tc.name,
-            arguments: tc.arguments,
+            arguments: symbolized[idx],
             result: result.to_h
           }
 
-          # Add tool result to conversation as a tool-role message
-          result_content = result.success? ? JSON.generate(result.value) : "Error: #{result.error}"
+          # Add tool result to conversation as a tool-role message. Tools may
+          # return values containing types JSON cannot natively serialize
+          # (Time, Date, custom objects). JSON.generate would raise and abort
+          # the agent run, so fall back to a string representation in that
+          # case rather than crashing the loop.
+          result_content = if result.success?
+                             begin
+                               JSON.generate(result.value)
+                             rescue JSON::GeneratorError, TypeError
+                               result.value.to_s
+                             end
+                           else
+                             "Error: #{result.error}"
+                           end
           @state.add_message(
             role: :tool,
             content: result_content,
@@ -250,14 +333,16 @@ module RubyPi
       # Constructs the final Agent::Result from the current state.
       #
       # @param content [String, nil] the final text content
+      # @param stop_reason [Symbol] why the agent stopped (:complete, :max_iterations, :error)
       # @return [RubyPi::Agent::Result]
-      def build_result(content:)
+      def build_result(content:, stop_reason: :complete)
         Result.new(
           content: content,
           messages: @state.messages,
           tool_calls_made: @tool_calls_made,
           usage: @total_usage,
-          turns: @state.iteration
+          turns: @state.iteration,
+          stop_reason: stop_reason
         )
       end
     end

data/lib/ruby_pi/agent/result.rb

@@ -23,6 +23,12 @@ module RubyPi
     #   else
     #     puts "Error: #{result.error.message}"
     #   end
+    #
+    # @example Checking for truncation (Issue #19)
+    #   result = agent.run("Complex task")
+    #   if result.truncated?
+    #     puts "Warning: agent hit max iterations — result may be incomplete"
+    #   end
     class Result
       # @return [String, nil] the final text content from the assistant
       attr_reader :content
@@ -44,6 +50,16 @@ module RubyPi
       # @return [RubyPi::Error, StandardError, nil] the error if the run failed
       attr_reader :error
 
+      # @return [Symbol] the reason the agent stopped — :complete, :max_iterations,
+      #   or :error. Allows callers to distinguish between a clean finish and
+      #   being guillotined by the iteration limit.
+      #
+      # Issue #19: Added stop_reason to distinguish between a natural stop
+      # (LLM signaled completion) and hitting the max iteration limit. Previously,
+      # max_iterations produced a Result with no error, making success? return
+      # true even though the agent was forcibly stopped.
+      attr_reader :stop_reason
+
       # Creates a new Result instance.
       #
       # @param content [String, nil] the final assistant text
@@ -52,23 +68,43 @@ module RubyPi
       # @param usage [Hash] token usage statistics
       # @param turns [Integer] number of completed cycles
       # @param error [Exception, nil] error if the run failed
-      def initialize(content: nil, messages: [], tool_calls_made: [], usage: {}, turns: 0, error: nil)
+      # @param stop_reason [Symbol] why the agent stopped (:complete, :max_iterations, :error)
+      def initialize(content: nil, messages: [], tool_calls_made: [], usage: {}, turns: 0, error: nil, stop_reason: :complete)
         @content = content
         @messages = Array(messages).freeze
         @tool_calls_made = Array(tool_calls_made).freeze
         @usage = usage
         @turns = turns
         @error = error
+        @stop_reason = stop_reason
       end
 
-      # Returns true if the agent run completed without error.
+      # Returns true if the agent run completed without error AND was not
+      # truncated by the max iteration limit.
+      #
+      # Issue #19: Previously returned true when max_iterations was reached
+      # (because error was nil). Now returns false for truncated runs so
+      # callers can detect incomplete results.
       #
-      # @return [Boolean] true unless an error is present
+      # @return [Boolean] true only if the run completed naturally without error
       def success?
-        @error.nil?
+        @error.nil? && @stop_reason != :max_iterations
+      end
+
+      # Returns true if the agent was stopped by hitting the max iteration
+      # limit rather than completing naturally.
+      #
+      # Issue #19: Provides a convenient predicate for checking truncation
+      # without inspecting stop_reason directly.
+      #
+      # @return [Boolean] true if the run was truncated by max_iterations
+      def truncated?
+        @stop_reason == :max_iterations
       end
 
       # Returns a hash representation of the result for serialization.
+      # Includes both the error class name and message for full diagnostic
+      # context when an error is present.
       #
       # @return [Hash]
       def to_h
@@ -78,8 +114,10 @@ module RubyPi
           tool_calls_made: @tool_calls_made,
           usage: @usage,
           turns: @turns,
-          error: @error&.message,
-          success: success?
+          error: @error ? { class: @error.class.name, message: @error.message } : nil,
+          success: success?,
+          stop_reason: @stop_reason,
+          truncated: truncated?
         }
       end
 
@@ -88,10 +126,11 @@ module RubyPi
       # @return [String]
       def to_s
         status = success? ? "success" : "error"
-        parts = ["status=#{status}", "turns=#{@turns}"]
+        parts = ["status=#{status}", "turns=#{@turns}", "stop_reason=#{@stop_reason}"]
         parts << "tools=#{@tool_calls_made.size}" unless @tool_calls_made.empty?
         parts << "content=#{@content&.slice(0, 80).inspect}" if @content
         parts << "error=#{@error.class}: #{@error.message}" if @error
+        parts << "truncated=true" if truncated?
         "#<RubyPi::Agent::Result #{parts.join(', ')}>"
       end
 

data/lib/ruby_pi/agent/state.rb

@@ -134,6 +134,18 @@ module RubyPi
         @iteration += 1
       end
 
+      # Resets the iteration counter to zero.
+      #
+      # Issue #16: Provides an encapsulated way to reset the iteration counter
+      # instead of using instance_variable_set(:@iteration, 0) which bypasses
+      # encapsulation. Called at the start of both run() and continue() to
+      # ensure each invocation gets a fresh iteration budget.
+      #
+      # @return [Integer] the reset iteration count (0)
+      def reset_iteration!
+        @iteration = 0
+      end
+
       # Returns true if the iteration count has reached or exceeded max_iterations.
       #
       # @return [Boolean]

data/lib/ruby_pi/configuration.rb

@@ -5,6 +5,10 @@
 # Global configuration for the RubyPi framework. Provides a centralized place
 # to set API keys, retry behavior, timeouts, and default model preferences.
 # Configure via RubyPi.configure { |c| c.gemini_api_key = "..." }.
+#
+# Supports both global (singleton) and per-agent configuration. Pass a
+# Configuration instance to Agent::Core via the `config:` kwarg to override
+# the global defaults for that agent.
 
 module RubyPi
   # Holds all configurable settings for the RubyPi framework.
@@ -17,6 +21,11 @@ module RubyPi
   #     config.max_retries      = 5
   #     config.retry_base_delay = 2.0
   #   end
+  #
+  # @example Per-agent configuration override
+  #   custom_config = RubyPi::Configuration.new
+  #   custom_config.openai_api_key = "per-agent-key"
+  #   agent = RubyPi::Agent.new(system_prompt: "...", model: model, config: custom_config)
   class Configuration
     # @return [String, nil] API key for Google Gemini
     attr_accessor :gemini_api_key
@@ -56,6 +65,25 @@ module RubyPi
 
     # Initializes a new Configuration with sensible defaults.
     def initialize
+      set_defaults
+    end
+
+    # Resets all configuration options to their default values.
+    # Uses the shared set_defaults method to avoid calling initialize directly.
+    #
+    # @return [void]
+    def reset!
+      set_defaults
+    end
+
+    private
+
+    # Sets all configuration ivars to their default values. Called by both
+    # initialize and reset! to ensure consistent defaults without the
+    # anti-pattern of calling initialize from reset!.
+    #
+    # @return [void]
+    def set_defaults
       @gemini_api_key        = nil
       @anthropic_api_key     = nil
       @openai_api_key        = nil
@@ -69,12 +97,5 @@ module RubyPi
       @default_openai_model  = "gpt-4o"
       @logger                = nil
     end
-
-    # Resets all configuration options to their default values.
-    #
-    # @return [void]
-    def reset!
-      initialize
-    end
   end
 end

data/lib/ruby_pi/context/compaction.rb

@@ -87,9 +87,24 @@ module RubyPi
         # Emit compaction event if an emitter is available
         @emitter&.emit(:compaction, dropped_count: droppable.size, summary: summary)
 
-        # Build the compacted history: summary as a system-context message + preserved
+        # Build the compacted history: summary message + preserved.
+        #
+        # The summary role MUST NOT be :system (that would overwrite the real
+        # system prompt on Anthropic, which extracts the last :system message
+        # as the top-level `system:` parameter).
+        #
+        # The summary role must also NOT match the role of the first preserved
+        # message — consecutive same-role messages are rejected by Anthropic.
+        # We pick :user when the next preserved message is :assistant, and
+        # :assistant otherwise (covers :user, :tool, and an empty preserved).
+        # On Anthropic, :tool messages become role :user with tool_result
+        # blocks, so :assistant is the safe choice when the next message is
+        # :tool too.
+        first_preserved_role = preserved.first&.dig(:role)
+        summary_role = first_preserved_role == :assistant ? :user : :assistant
+
         summary_message = {
-          role: :system,
+          role: summary_role,
           content: "[Conversation Summary]\n#{summary}"
         }
 

data/lib/ruby_pi/context/transform.rb

@@ -10,6 +10,12 @@
 # module provides factory methods for common transform patterns (datetime
 # injection, user preferences, workspace context) and a `compose` method for
 # chaining multiple transforms into a single callable.
+#
+# IDEMPOTENCY: Each injection method uses unique marker delimiters
+# (e.g., <!-- RUBYPI_DATETIME_START --> ... <!-- RUBYPI_DATETIME_END -->) to
+# wrap injected content. Before re-adding, the transform strips any existing
+# injection matching its markers. This prevents the system prompt from
+# accumulating duplicate injections across multiple LLM calls in a loop.
 
 module RubyPi
   module Context
@@ -24,6 +30,16 @@ module RubyPi
     #   )
     #   agent = RubyPi::Agent.new(transform_context: transform, ...)
     module Transform
+      # Marker delimiters for idempotent injection. Each injection type has
+      # unique start/end markers so they can be independently stripped and
+      # re-added without affecting each other.
+      DATETIME_START_MARKER  = "<!-- RUBYPI_DATETIME_START -->"
+      DATETIME_END_MARKER    = "<!-- RUBYPI_DATETIME_END -->"
+      PREFS_START_MARKER     = "<!-- RUBYPI_PREFS_START -->"
+      PREFS_END_MARKER       = "<!-- RUBYPI_PREFS_END -->"
+      WORKSPACE_START_MARKER = "<!-- RUBYPI_WORKSPACE_START -->"
+      WORKSPACE_END_MARKER   = "<!-- RUBYPI_WORKSPACE_END -->"
+
       class << self
         # Chains multiple transform callables into a single callable that
         # executes them in order. Each transform receives the same State
@@ -44,6 +60,10 @@ module RubyPi
         # Returns a transform that appends the current date and time to the
         # system prompt. Useful for giving the LLM temporal awareness.
         #
+        # This injection is IDEMPOTENT: it strips any existing datetime
+        # injection (identified by markers) before re-adding, so calling it
+        # N times in a loop produces exactly one datetime block.
+        #
         # @return [Proc] transform callable
         #
         # @example
@@ -52,7 +72,17 @@ module RubyPi
         def inject_datetime
           ->(state) do
             timestamp = Time.now.utc.strftime("%Y-%m-%d %H:%M:%S UTC")
-            state.system_prompt += "\n\nCurrent date and time: #{timestamp}"
+
+            # Strip any existing datetime injection before re-adding.
+            # This makes the transform idempotent — calling it multiple times
+            # across loop iterations does not accumulate duplicate timestamps.
+            state.system_prompt = strip_between_markers(
+              state.system_prompt,
+              DATETIME_START_MARKER,
+              DATETIME_END_MARKER
+            )
+
+            state.system_prompt += "\n\n#{DATETIME_START_MARKER}\nCurrent date and time: #{timestamp}\n#{DATETIME_END_MARKER}"
           end
         end
 
@@ -61,6 +91,9 @@ module RubyPi
         # string or hash of preferences. If nil is returned, nothing is
         # appended.
         #
+        # This injection is IDEMPOTENT: existing preferences are stripped
+        # before re-adding.
+        #
         # @yield [state] block that extracts preferences from the state
         # @yieldparam state [RubyPi::Agent::State] the current agent state
         # @yieldreturn [String, Hash, nil] preferences to inject
@@ -71,10 +104,16 @@ module RubyPi
         def inject_user_preferences(&block)
           ->(state) do
             preferences = block.call(state)
+            # Always strip existing preferences injection first for idempotency
+            state.system_prompt = strip_between_markers(
+              state.system_prompt,
+              PREFS_START_MARKER,
+              PREFS_END_MARKER
+            )
             return if preferences.nil?
 
             prefs_text = preferences.is_a?(Hash) ? format_hash(preferences) : preferences.to_s
-            state.system_prompt += "\n\n[User Preferences]\n#{prefs_text}"
+            state.system_prompt += "\n\n#{PREFS_START_MARKER}\n[User Preferences]\n#{prefs_text}\n#{PREFS_END_MARKER}"
           end
         end
 
@@ -82,6 +121,9 @@ module RubyPi
         # prompt. The block is called with the state and should return
         # contextual information about the current workspace/project.
         #
+        # This injection is IDEMPOTENT: existing workspace context is stripped
+        # before re-adding.
+        #
         # @yield [state] block that extracts workspace context from the state
         # @yieldparam state [RubyPi::Agent::State] the current agent state
         # @yieldreturn [String, Hash, nil] workspace context to inject
@@ -92,15 +134,37 @@ module RubyPi
         def inject_workspace_context(&block)
           ->(state) do
             context = block.call(state)
+            # Always strip existing workspace injection first for idempotency
+            state.system_prompt = strip_between_markers(
+              state.system_prompt,
+              WORKSPACE_START_MARKER,
+              WORKSPACE_END_MARKER
+            )
             return if context.nil?
 
             ctx_text = context.is_a?(Hash) ? format_hash(context) : context.to_s
-            state.system_prompt += "\n\n[Workspace Context]\n#{ctx_text}"
+            state.system_prompt += "\n\n#{WORKSPACE_START_MARKER}\n[Workspace Context]\n#{ctx_text}\n#{WORKSPACE_END_MARKER}"
           end
         end
 
         private
 
+        # Strips content between (and including) the given start and end
+        # markers from the text. Used to remove a previous injection before
+        # re-adding it, ensuring idempotency.
+        #
+        # @param text [String] the text to strip markers from
+        # @param start_marker [String] the opening marker
+        # @param end_marker [String] the closing marker
+        # @return [String] text with the marked section removed
+        def strip_between_markers(text, start_marker, end_marker)
+          # Use a regex that matches the markers and everything between them,
+          # including any leading whitespace (newlines) before the start marker.
+          escaped_start = Regexp.escape(start_marker)
+          escaped_end = Regexp.escape(end_marker)
+          text.gsub(/\s*#{escaped_start}.*?#{escaped_end}/m, "")
+        end
+
         # Formats a hash into a human-readable key-value string for injection
         # into the system prompt.
         #

data/lib/ruby_pi/errors.rb

@@ -88,10 +88,28 @@ module RubyPi
 
   # Raised when a subclass does not implement a required abstract method
   # from a base class.
-  class NotImplementedError < Error
+  #
+  # Issue #14: Renamed from NotImplementedError to AbstractMethodError to
+  # avoid shadowing Ruby's stdlib NotImplementedError < ScriptError. The
+  # stdlib class is raised by Kernel#fork on platforms that don't support it,
+  # and shadowing it can cause confusing rescue behavior.
+  class AbstractMethodError < Error
     # @param method_name [String, Symbol] the name of the unimplemented method
     def initialize(method_name = nil)
       super(method_name ? "Subclass must implement ##{method_name}" : "Subclass must implement this method")
     end
   end
+
+  # Raised when the LLM returns tool calls but no tools are registered
+  # with the agent. This typically means the model hallucinated a tool
+  # invocation that cannot be fulfilled.
+  #
+  # Issue #17: Provides a clear typed error instead of a NoMethodError
+  # when nil.find is called on a nil tools registry.
+  class NoToolsRegisteredError < Error
+    # @param message [String] human-readable error description
+    def initialize(message = nil)
+      super(message || "Model returned tool calls but no tools are registered")
+    end
+  end
 end