ruby-pi 0.1.8 → 0.1.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0054adb6a0863a8f296917be736df0ebfd789aa7205589b82689199d4bf4c06
-  data.tar.gz: fc79dcc61dbefce874e609807d989cf2293b0ecb45a6aa036069b11038ac5c9a
+  metadata.gz: fbecc54fc18679e9f16a0a09c27944df82b0a98fff7ead1dee99ba1a659aad02
+  data.tar.gz: 298e084a7df3b6689e628477ddbae866057a81ac472838623ce6eefccd01a431
 SHA512:
-  metadata.gz: c130ada9b7ed93f5c9a0d16596c1176fec258204be26af15c61db3c18effee94bc7a8a1783620397780b0e3501e660b4e8ff48d8463e4089067edfcbf3bf9b60
-  data.tar.gz: dc179fe40cb063c4321a1c7a1aff5abb7b441d5fd87ced19908f9875c1f5b26bf2e17555b44658f603b32627577fe99feb8f34d061ed7e53eaba3c28cecd8bbb
+  metadata.gz: cbb1ae3d3469f987b4ab7652cce23626e6e1a233c08636ab24dcda3c6151d0bc728d88658e575919840e393c84ce4efabbd5fa78f302c036993a0d1b3e79b354
+  data.tar.gz: 1132a860f026efc123813042eea18617242d036ec03ca425277cd2f9eba88a49f1cc2f461c6feee58fa021eeed8fbe42affee5c6f865ff6fad563809ede29479

data/CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.9] - 2026-08-28
+
+### Security
+
+- **Tool exception details crossed the LLM trust boundary (High)**: Tool failures remain available locally in execution Results and lifecycle events, but model-visible tool messages now contain a generic diagnostic notice rather than the raw exception. This prevents database errors, paths, signed URLs, tokens, and PII embedded in exception messages from being sent to an external model provider
+- **Vulnerable locked dependencies (High)**: Updated `faraday` to 2.14.3, `concurrent-ruby` to 1.3.8, and `faraday-net_http` to 3.4.4. This resolves the published Faraday stack-exhaustion and host-scoping advisories plus concurrent-ruby lock/livelock advisories; `bundle audit check` now reports no known vulnerabilities
+
+### Fixed (adversarial review round 7)
+
+- **Provider truncation and safety stops were reported as success (High)**: The agent loop previously treated every response without tool calls as a clean completion, ignoring `finish_reason`. Only an explicit `"stop"` now maps to `stop_reason: :complete`; token limits, safety/content filters, and unknown provider stops produce distinct unsuccessful Results. `truncated?` now covers both iteration and provider token limits
+- **Streaming retries concatenated failed and successful attempts (High)**: If an attempt yielded deltas before a transient failure, the retry streamed a fresh response into the same consumer with no reset signal. Providers now emit `:retry_start` with the discarded character count, and the agent translates it to `:provider_retry`. Fallback accounting resets across intra-provider retries so later failover truncation remains accurate
+- **Deterministic client errors were retried (Medium)**: HTTP 400/404/422 and other non-transient 4xx responses now fail immediately. Retries are limited to transport/protocol failures, timeouts, rate limits, selected transient 4xx statuses, and 5xx responses
+- **Successful malformed JSON bypassed retry/fallback (Medium)**: All standard provider responses now parse through a typed protocol-error path. Truncated or malformed HTTP 200 JSON raises a retryable `ApiError`, allowing normal retry and fallback behavior instead of leaking `JSON::ParserError`
+- **Infinite and fractional retry configuration (Medium)**: `max_retries` now requires a non-negative Integer, numeric retry/timeout settings must be finite, and provider constructor overrides receive the same validation. This closes the `Float::INFINITY` endless-retry path
+- **`Retry-After` HTTP dates were ignored (Medium)**: Both delta-seconds and RFC HTTP-date forms are now parsed; invalid or expired values fall back to exponential backoff
+- **String-keyed JSON histories broke compaction (Medium)**: Compaction now reads symbol- and string-keyed roles/content consistently, restoring token estimates, orphan-tool handling, and summary transcripts for JSON-round-tripped histories
+- **Result and State immutability was shallow (Medium)**: `Agent::Result` now deep-copies and freezes its observable data. `State` deep-copies message inputs/outputs so callers cannot mutate internal conversation history through retained nested references or `add_message` return values
+
+### Known limitations
+
+- In-process tool timeouts remain advisory: Ruby threads cannot be safely force-terminated, so timed-out side-effecting tools can continue running. Use idempotency and cooperative deadlines until tool isolation is redesigned
+- Streaming providers do not yet enforce provider-specific terminal SSE events; a malformed/truncated stream can omit an event without a strict EOF protocol error
+
 ## [0.1.8] - 2026-06-09
 
 ### Fixed (adversarial review round 6)

data/README.md

@@ -130,6 +130,11 @@ model.complete(messages: messages, stream: true) do |event|
     print event.data           # incremental text chunk
   when :tool_call_delta
     handle_fragment(event.data) # partial tool call JSON
+  when :retry_start
+    # A transient failure occurred after streaming may have begun. Discard
+    # the previous attempt before the provider retries from the beginning.
+    # Payload includes: { provider:, attempt:, partial_output:, partial_chars: }
+    clear_partial_output
   when :fallback_start
     # Only emitted by RubyPi::LLM::Fallback when the primary provider
     # fails mid-stream. Discard any partial output rendered from the
@@ -142,11 +147,11 @@ model.complete(messages: messages, stream: true) do |event|
 end
 ```
 
-When using `RubyPi::Agent`, the loop translates a `:fallback_start` stream
-event into an agent-level `:provider_fallback` event you can subscribe to
-with `agent.on(:provider_fallback) { |e| ... }`. The agent also discards
-any partial text it accumulated from the failed primary so the recorded
-response reflects only the fallback's output.
+When using `RubyPi::Agent`, the loop translates `:retry_start` and
+`:fallback_start` into agent-level `:provider_retry` and `:provider_fallback`
+events. Subscribe to both to clear consumer-rendered partial output before a
+fresh response begins. The recorded assistant response always comes from the
+successful final attempt.
 
 #### Response & ToolCall
 
@@ -154,7 +159,7 @@ response reflects only the fallback's output.
 |---|---|
 | `RubyPi::LLM::Response` | `content`, `tool_calls`, `usage`, `finish_reason`, `tool_calls?` |
 | `RubyPi::LLM::ToolCall` | `id`, `name`, `arguments` |
-| `RubyPi::LLM::StreamEvent` | `type`, `data`, `text_delta?`, `tool_call_delta?`, `done?` |
+| `RubyPi::LLM::StreamEvent` | `type`, `data`, `text_delta?`, `tool_call_delta?`, `retry_start?`, `fallback_start?`, `done?` |
 
 #### Fallback
 
@@ -306,6 +311,8 @@ Subscribe to lifecycle events for logging, monitoring, or custom behavior:
 agent.on(:turn_start)          { |e| puts "Turn #{e[:turn]} starting" }
 agent.on(:turn_end)            { |e| puts "Turn #{e[:turn]} ended" }
 agent.on(:text_delta)          { |e| print e[:content] }
+agent.on(:provider_retry)      { |_e| clear_partial_output }
+agent.on(:provider_fallback)   { |_e| clear_partial_output }
 agent.on(:tool_execution_start){ |e| puts "Calling #{e[:tool_name]}" }
 agent.on(:tool_execution_end)  { |e| puts "#{e[:tool_name]} => #{e[:result].value}" }
 # Note: before_tool_call and after_tool_call are constructor hooks (Procs),

data/lib/ruby_pi/agent/events.rb

@@ -26,6 +26,8 @@ module RubyPi
     #                           to backup mid-stream. Subscribers should
     #                           discard any partial text_delta output that
     #                           arrived before this event.
+    # - :provider_retry       — A provider discarded a failed streaming
+    #                           attempt and is retrying from the beginning.
     EVENTS = %i[
       text_delta
       tool_call_delta
@@ -36,6 +38,7 @@ module RubyPi
       agent_end
       error
       compaction
+      provider_retry
       provider_fallback
     ].freeze
 

data/lib/ruby_pi/agent/loop.rb

@@ -116,7 +116,10 @@ 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, stop_reason: :complete)
+            return build_result(
+              content: response.content,
+              stop_reason: agent_stop_reason(response.finish_reason)
+            )
           end
         end
       rescue *PROGRAMMING_ERRORS
@@ -179,6 +182,8 @@ module RubyPi
             # it comes from the fallback provider's returned Response#content,
             # never from the failed primary's partial text.
             @emitter.emit(:provider_fallback, **event.data)
+          elsif event.retry_start?
+            @emitter.emit(:provider_retry, **event.data)
           end
         end
 
@@ -278,7 +283,12 @@ module RubyPi
                                result.value.to_s
                              end
                            else
-                             "Error: #{result.error}"
+                             # Exception messages frequently contain database
+                             # details, paths, signed URLs, tokens, or PII. The
+                             # full error remains available locally through the
+                             # Result and lifecycle event, but it must not be
+                             # copied into the next request to the LLM provider.
+                             "Error: Tool '#{tc.name}' failed. See local diagnostics."
                            end
           @state.add_message(
             role: :tool,
@@ -321,6 +331,20 @@ module RubyPi
         @total_usage[:output_tokens] += (usage[:completion_tokens] || usage[:output_tokens] || 0)
       end
 
+      # Converts provider finish reasons into agent-level outcome semantics.
+      # Only an explicit normal stop is a successful completion; accepting a
+      # max-token, safety, content-filter, or unknown stop as success risks
+      # downstream publication or action on incomplete output.
+      def agent_stop_reason(finish_reason)
+        case finish_reason.to_s
+        when "stop" then :complete
+        when "max_tokens", "length" then :max_tokens
+        when "safety" then :safety
+        when "content_filter", "recitation", "prohibited_content" then :content_filter
+        else :unknown_provider_stop
+        end
+      end
+
       # Triggers context compaction if a compaction strategy is configured
       # and the estimated token count exceeds the threshold.
       #

data/lib/ruby_pi/agent/result.rb

@@ -51,8 +51,9 @@ module RubyPi
       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.
+      #   :max_tokens, :safety, :content_filter, :unknown_provider_stop, or
+      #   :error. Allows callers to distinguish a clean finish from truncation
+      #   or provider-enforced termination.
       #
       # Issue #19: Added stop_reason to distinguish between a natural stop
       # (LLM signaled completion) and hitting the max iteration limit. Previously,
@@ -70,10 +71,10 @@ module RubyPi
       # @param error [Exception, nil] error if the run failed
       # @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
+        @content = deep_frozen_copy(content)
+        @messages = deep_frozen_copy(Array(messages))
+        @tool_calls_made = deep_frozen_copy(Array(tool_calls_made))
+        @usage = deep_frozen_copy(usage)
         @turns = turns
         @error = error
         @stop_reason = stop_reason
@@ -88,18 +89,18 @@ module RubyPi
       #
       # @return [Boolean] true only if the run completed naturally without error
       def success?
-        @error.nil? && @stop_reason != :max_iterations
+        @error.nil? && @stop_reason == :complete
       end
 
-      # Returns true if the agent was stopped by hitting the max iteration
-      # limit rather than completing naturally.
+      # Returns true if the agent was stopped by an agent iteration limit or
+      # a provider token 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
+      # @return [Boolean] true if the run was truncated by an iteration/token limit
       def truncated?
-        @stop_reason == :max_iterations
+        %i[max_iterations max_tokens].include?(@stop_reason)
       end
 
       # Returns a hash representation of the result for serialization.
@@ -135,6 +136,33 @@ module RubyPi
       end
 
       alias_method :inspect, :to_s
+
+      private
+
+      # Agent::Result is documented as immutable. Freezing only the outer
+      # arrays still allowed callers (or later State mutations) to rewrite
+      # nested messages, tool arguments, usage, and content in place.
+      def deep_frozen_copy(value)
+        copy = case value
+               when Hash
+                 value.each_with_object({}) do |(key, item), result|
+                   result[deep_frozen_copy(key)] = deep_frozen_copy(item)
+                 end
+               when Array
+                 value.map { |item| deep_frozen_copy(item) }
+               when String
+                 value.dup
+               else
+                 begin
+                   value.dup
+                 rescue TypeError
+                   # Immutable scalar values (nil, symbols, numerics, booleans)
+                   # cannot be duplicated and are already safe to share.
+                   value
+                 end
+               end
+        copy.freeze
+      end
     end
   end
 end

data/lib/ruby_pi/agent/state.rb

@@ -80,7 +80,7 @@ module RubyPi
         @system_prompt = system_prompt
         @model = model
         @tools = tools
-        @messages = Array(messages).dup
+        @messages = deep_dup(Array(messages))
         @max_iterations = max_iterations
         @transform_context = transform_context
         @before_tool_call = before_tool_call
@@ -103,8 +103,8 @@ module RubyPi
       # @return [Array<Hash>] the updated messages array
       def add_message(role:, content: nil, **options)
         message = { role: role.to_sym, content: content }.merge(options)
-        @messages << message
-        @messages
+        @messages << deep_dup(message)
+        messages
       end
 
       # Returns a frozen copy of the conversation history. Callers cannot
@@ -112,7 +112,7 @@ module RubyPi
       #
       # @return [Array<Hash>] the full conversation history
       def messages
-        @messages.dup.freeze
+        deep_dup(@messages).freeze
       end
 
       # Replaces the entire conversation history. Used by compaction to swap
@@ -121,7 +121,7 @@ module RubyPi
       # @param new_messages [Array<Hash>] the replacement message array
       # @return [Array<Hash>] the new messages array
       def messages=(new_messages)
-        @messages = Array(new_messages).dup
+        @messages = deep_dup(Array(new_messages))
       end
 
       # Returns the current iteration count (number of completed think-act-observe
@@ -168,6 +168,26 @@ module RubyPi
           "messages=#{@messages.size} " \
           "tools=#{@tools&.size || 0}>"
       end
+
+      private
+
+      # Copies the nested message structure so callers cannot mutate state by
+      # retaining an input reference or changing a Hash/String obtained from
+      # #messages. Message payloads are JSON-like, so recursive handling of
+      # Hash, Array, and String covers the supported shapes without attempting
+      # to duplicate arbitrary application objects.
+      def deep_dup(value)
+        case value
+        when Hash
+          value.each_with_object({}) { |(key, item), copy| copy[key] = deep_dup(item) }
+        when Array
+          value.map { |item| deep_dup(item) }
+        when String
+          value.dup
+        else
+          value
+        end
+      end
     end
   end
 end

data/lib/ruby_pi/configuration.rb

@@ -57,7 +57,10 @@ module RubyPi
 
     # @param value [Integer] must be a non-negative integer
     def max_retries=(value)
-      validate_numeric!(:max_retries, value)
+      unless value.is_a?(Integer) && value >= 0
+        raise ArgumentError, "max_retries must be a non-negative integer, got #{value.inspect}"
+      end
+
       @max_retries = value
     end
 
@@ -118,9 +121,9 @@ module RubyPi
     # @param value [Object] the value being assigned
     # @raise [ArgumentError] if value is not a Numeric or is negative
     def validate_numeric!(name, value)
-      return if value.is_a?(Numeric) && value >= 0
+      return if value.is_a?(Numeric) && !value.is_a?(Complex) && value.finite? && value >= 0
 
-      raise ArgumentError, "#{name} must be a non-negative number, got #{value.inspect}"
+      raise ArgumentError, "#{name} must be a finite non-negative number, got #{value.inspect}"
     end
 
     # Sets all configuration ivars to their default values. Called by both

data/lib/ruby_pi/context/compaction.rb

@@ -95,7 +95,7 @@ module RubyPi
         # it is already in droppable, so the pair stays together there — there
         # is no mirror case to handle (once a tool result is moved across, its
         # assistant is never left stranded on the preserved side).
-        while preserved.first && preserved.first[:role] == :tool
+        while preserved.first && message_value(preserved.first, :role).to_s == "tool"
           droppable << preserved.shift
         end
 
@@ -139,9 +139,10 @@ module RubyPi
         summary_text = "[Conversation Summary]\n#{summary}"
         first_preserved = preserved.first
 
-        if first_preserved && first_preserved[:role] == :user
+        if first_preserved && message_value(first_preserved, :role).to_s == "user"
           merged = first_preserved.dup
-          merged[:content] = "#{summary_text}\n\n#{first_preserved[:content]}"
+          content_key = first_preserved.key?(:content) ? :content : "content"
+          merged[content_key] = "#{summary_text}\n\n#{message_value(first_preserved, :content)}"
           [merged] + preserved.drop(1)
         else
           [{ role: :user, content: summary_text }] + preserved
@@ -158,7 +159,7 @@ module RubyPi
         total_chars = system_prompt.to_s.length
 
         messages.each do |msg|
-          total_chars += msg[:content].to_s.length
+          total_chars += message_value(msg, :content).to_s.length
           # Account for role and structural overhead (~10 tokens per message)
           total_chars += 40
         end
@@ -199,14 +200,20 @@ module RubyPi
       # @return [String] formatted prompt for summarization
       def build_summary_prompt(messages)
         transcript = messages.map do |msg|
-          role = msg[:role].to_s.capitalize
-          content = msg[:content].to_s
+          role = message_value(msg, :role).to_s.capitalize
+          content = message_value(msg, :content).to_s
           "#{role}: #{content}"
         end.join("\n\n")
 
         "Summarize the following conversation, preserving all key facts, " \
           "decisions, and tool call results:\n\n#{transcript}"
       end
+
+      # Reads normalized symbol-keyed messages and histories loaded from JSON,
+      # whose top-level keys are strings.
+      def message_value(message, key)
+        message[key] || message[key.to_s]
+      end
     end
   end
 end

data/lib/ruby_pi/llm/anthropic.rb

@@ -340,7 +340,7 @@ module RubyPi
         end
 
         handle_error_response(response) unless response.success?
-        parse_response(JSON.parse(response.body))
+        parse_response(parse_json_response(response.body))
       end
 
       # Executes a streaming request to the Anthropic API, yielding events.

data/lib/ruby_pi/llm/base_provider.rb

@@ -7,6 +7,9 @@
 # providers (Gemini, Anthropic, OpenAI) must subclass this and implement the
 # abstract methods.
 
+require "json"
+require "time"
+
 module RubyPi
   module LLM
     # Abstract base class that defines the contract every LLM provider must
@@ -53,6 +56,8 @@ module RubyPi
         @max_retries = max_retries || @config.max_retries
         @retry_base_delay = retry_base_delay || @config.retry_base_delay
         @retry_max_delay = retry_max_delay || @config.retry_max_delay
+
+        validate_retry_configuration!
       end
 
       # Sends a completion request to the LLM provider with automatic retry
@@ -71,10 +76,20 @@ module RubyPi
       # @raise [RubyPi::TimeoutError] on request timeouts
       def complete(messages:, tools: [], stream: false, &block)
         attempt = 0
+        partial_chars = 0
+
+        attempt_block = if stream && block
+                          proc do |event|
+                            partial_chars += event.data.to_s.length if event.text_delta?
+                            block.call(event)
+                          end
+                        else
+                          block
+                        end
 
         begin
           attempt += 1
-          perform_complete(messages: messages, tools: tools, stream: stream, &block)
+          perform_complete(messages: messages, tools: tools, stream: stream, &attempt_block)
         rescue RubyPi::AuthenticationError
           # Authentication errors are not retryable — raise immediately
           raise
@@ -93,9 +108,21 @@ module RubyPi
           # `attempt <= @max_retries` allows retries on attempts 1..3, so we get
           # 3 retries + 1 initial = 4 total attempts. Previously used `< @max_retries`
           # which was off-by-one (only 2 retries with max_retries: 3).
-          if attempt <= @max_retries
+          if retryable_error?(e) && attempt <= @max_retries
             delay = retry_delay_for(e, attempt)
             log_retry(attempt, delay, e)
+
+            if stream && block
+              block.call(StreamEvent.new(type: :retry_start, data: {
+                provider: provider_name,
+                error: e.message,
+                attempt: attempt + 1,
+                partial_output: partial_chars.positive?,
+                partial_chars: partial_chars
+              }))
+              partial_chars = 0
+            end
+
             sleep(delay)
             retry
           else
@@ -159,6 +186,17 @@ module RubyPi
         end
       end
 
+      # Only transient failures should be retried. Deterministic client errors
+      # (400, 404, 422, etc.) cannot improve on an identical retry and merely
+      # waste quota and add the full backoff delay.
+      def retryable_error?(error)
+        return true if error.is_a?(RubyPi::RateLimitError) || error.is_a?(RubyPi::TimeoutError)
+        return false unless error.is_a?(RubyPi::ApiError)
+
+        status = error.status_code
+        status.nil? || status == 408 || status == 409 || status == 425 || status >= 500
+      end
+
       # Calculates the backoff delay for a given retry attempt using
       # exponential backoff with jitter.
       #
@@ -170,6 +208,27 @@ module RubyPi
         [base + jitter, @retry_max_delay].min
       end
 
+      # Validates constructor-level overrides. Configuration's writers perform
+      # the same checks, but provider keyword overrides bypass those writers.
+      # In particular, an infinite max_retries value makes the retry loop run
+      # forever because every finite attempt is <= Infinity.
+      def validate_retry_configuration!
+        unless @max_retries.is_a?(Integer) && @max_retries >= 0
+          raise ArgumentError,
+                "max_retries must be a non-negative integer, got #{@max_retries.inspect}"
+        end
+
+        {
+          retry_base_delay: @retry_base_delay,
+          retry_max_delay: @retry_max_delay
+        }.each do |name, value|
+          next if value.is_a?(Numeric) && !value.is_a?(Complex) && value.finite? && value >= 0
+
+          raise ArgumentError,
+                "#{name} must be a finite non-negative number, got #{value.inspect}"
+        end
+      end
+
       # Logs a retry attempt if a logger is configured.
       #
       # @param attempt [Integer] current attempt number
@@ -269,7 +328,7 @@ module RubyPi
             response_body: body
           )
         when 429
-          retry_after = response.headers["retry-after"]&.to_f
+          retry_after = parse_retry_after(response.headers["retry-after"])
           raise RubyPi::RateLimitError.new(
             "#{provider_name} rate limit exceeded (HTTP 429)",
             retry_after: retry_after,
@@ -284,6 +343,36 @@ module RubyPi
         end
       end
 
+      # Parses a successful JSON response into a Hash while preserving the
+      # provider error contract. A proxy can truncate a nominal HTTP 200 body;
+      # treating that as a transient ApiError allows retry/fallback instead of
+      # leaking JSON::ParserError or accepting an empty response.
+      def parse_json_response(body)
+        JSON.parse(body)
+      rescue JSON::ParserError => e
+        raise RubyPi::ApiError.new(
+          "#{provider_name} returned malformed JSON: #{e.message}",
+          status_code: nil,
+          response_body: body
+        )
+      end
+
+      # Parses both Retry-After forms allowed by HTTP: delta-seconds and an
+      # HTTP-date. Fractional seconds are retained for compatibility with API
+      # providers and fast test environments. Invalid or past dates return nil
+      # so the normal exponential backoff policy applies.
+      def parse_retry_after(value)
+        return nil if value.nil? || value.to_s.strip.empty?
+
+        seconds = Float(value, exception: false)
+        return seconds if seconds&.finite? && seconds.positive?
+
+        delay = Time.httpdate(value.to_s) - Time.now
+        delay.positive? ? delay : nil
+      rescue ArgumentError
+        nil
+      end
+
     end
   end
 end

data/lib/ruby_pi/llm/fallback.rb

@@ -158,7 +158,13 @@ module RubyPi
         # truncate what they already rendered.
         partial_chars = 0
         counting_block = proc do |event|
-          partial_chars += event.data.to_s.length if event.text_delta?
+          if event.retry_start?
+            # The provider tells consumers to discard its previous attempt,
+            # so only count text from the current attempt for a later fallback.
+            partial_chars = 0
+          elsif event.text_delta?
+            partial_chars += event.data.to_s.length
+          end
           block.call(event)
         end
 

data/lib/ruby_pi/llm/gemini.rb

@@ -281,7 +281,7 @@ module RubyPi
         end
 
         handle_error_response(response) unless response.success?
-        parse_response(JSON.parse(response.body))
+        parse_response(parse_json_response(response.body))
       end
 
       # Executes a streaming request to the Gemini API, yielding events.

data/lib/ruby_pi/llm/openai.rb

@@ -291,7 +291,7 @@ module RubyPi
         end
 
         handle_error_response(response) unless response.success?
-        parse_response(JSON.parse(response.body))
+        parse_response(parse_json_response(response.body))
       end
 
       # Executes a streaming request to the OpenAI API, yielding events.

data/lib/ruby_pi/llm/stream_event.rb

@@ -25,10 +25,10 @@ module RubyPi
     #   end
     class StreamEvent
       # Valid event types for stream events.
-      VALID_TYPES = %i[text_delta tool_call_delta done fallback_start].freeze
+      VALID_TYPES = %i[text_delta tool_call_delta done retry_start fallback_start].freeze
 
       # @return [Symbol] the type of stream event — one of :text_delta,
-      #   :tool_call_delta, :done, or :fallback_start
+      #   :tool_call_delta, :done, :retry_start, or :fallback_start
       attr_reader :type
 
       # @return [Object] the event payload. For :text_delta this is a String
@@ -38,7 +38,8 @@ module RubyPi
 
       # Creates a new StreamEvent instance.
       #
-      # @param type [Symbol] event type (:text_delta, :tool_call_delta, :done, :fallback_start)
+      # @param type [Symbol] event type (:text_delta, :tool_call_delta, :done,
+      #   :retry_start, :fallback_start)
       # @param data [Object] event payload
       # @raise [ArgumentError] if the type is not recognized
       def initialize(type:, data: nil)
@@ -71,6 +72,12 @@ module RubyPi
         @type == :done
       end
 
+      # Returns true when a failed streaming attempt is being discarded and
+      # the same provider is about to retry from the beginning.
+      def retry_start?
+        @type == :retry_start
+      end
+
       # Returns true if this is a fallback_start event, signaling that the
       # primary provider failed mid-stream and the fallback provider is
       # taking over. Consumers should clear any partial output rendered

data/lib/ruby_pi/version.rb

@@ -7,5 +7,5 @@
 
 module RubyPi
   # The current version of the RubyPi gem, following Semantic Versioning.
-  VERSION = "0.1.8"
+  VERSION = "0.1.9"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby-pi
 version: !ruby/object:Gem::Version
-  version: 0.1.8
+  version: 0.1.9
 platform: ruby
 authors:
 - RubyPi Contributors
@@ -171,7 +171,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.16
 specification_version: 4
 summary: AI agent harness for Ruby — build LLM agents with tool calling, streaming,
   and a unified interface to OpenAI, Anthropic Claude, and Google Gemini.