ruby-pi 0.1.8 → 0.1.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0054adb6a0863a8f296917be736df0ebfd789aa7205589b82689199d4bf4c06
-  data.tar.gz: fc79dcc61dbefce874e609807d989cf2293b0ecb45a6aa036069b11038ac5c9a
+  metadata.gz: ae334e07e1a5788bfe62b1a1d721d565885ba0142dca6d9a238656b3835454a0
+  data.tar.gz: 3f68b1f787a4fa17fd6ea68ef1b4974c5bb625b76c3898786a9b23c0999c490b
 SHA512:
-  metadata.gz: c130ada9b7ed93f5c9a0d16596c1176fec258204be26af15c61db3c18effee94bc7a8a1783620397780b0e3501e660b4e8ff48d8463e4089067edfcbf3bf9b60
-  data.tar.gz: dc179fe40cb063c4321a1c7a1aff5abb7b441d5fd87ced19908f9875c1f5b26bf2e17555b44658f603b32627577fe99feb8f34d061ed7e53eaba3c28cecd8bbb
+  metadata.gz: cc0289504d07435aa8e681a102bcdc4e27d8f4f8033ab73ea73c227e345ab64be93cc0fd8d3dd27d50c640d4758508e14a91b290fed02fd089477f73e5ea3d35
+  data.tar.gz: 031ad8a0ca080a0024f596ec05e57857bd7cab68dc9236ae5ada606f09bbeedea5e59142e01e6bdea2de032008a1624bd9ad0db78fd4ed6fc1ddcddaab53331b

data/CHANGELOG.md

@@ -5,6 +5,50 @@ 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.10] - 2026-08-28
+
+### Security
+
+- **Malformed or truncated HTTP-200 streams were accepted (High)**: Added a shared bounded SSE decoder with UTF-8 validation, standards-compliant event framing, final-buffer processing, and typed retryable protocol errors. OpenAI now requires `data: [DONE]`, Anthropic requires `message_stop`, and Gemini requires a finish reason or explicit prompt block before emitting `:done`
+- **Model-controlled tool fan-out was unbounded (High)**: Parallel execution now uses a bounded pool with a default concurrency of four, rejects more than 32 calls per execution, and enforces a process-wide cap of 16 active or timed-out-but-still-running tools. Streaming output, tool arguments, tool-call count, SSE events, and retained error bodies also have hard memory limits
+- **Malformed model arguments could enter logs (Medium)**: Provider errors no longer embed raw tool arguments, and fallback diagnostics remove control characters and cap message length
+
+### Fixed (adversarial review round 8)
+
+- **Tool timeout results falsely implied failure was final (High)**: Timed-out work is now reported as `status: :timeout_unknown` with `completion_unknown?`. Sequential execution does not start later calls after an uncertain timeout; those calls return `status: :skipped`. Arbitrary in-process Ruby blocks are still cooperative and cannot be force-terminated safely
+- **Immutable agent results could crash on valid tool values (High)**: Result snapshots are cycle-aware and never call `dup` on arbitrary application objects. Non-JSON objects become bounded frozen diagnostic strings instead of raising from `initialize_copy` or recursing indefinitely
+- **Retry/fallback reset metadata ignored tool fragments (Medium)**: Reset events now report `partial_tool_calls` and set `partial_output` whenever either text or structured tool-call output was emitted
+- **Compaction ignored structured tool metadata (Medium)**: Token estimates and summary prompts now account for assistant tool calls, IDs, names, and arguments
+- **Invalid safety limits failed deep in execution (Medium)**: Agent iteration limits, tool timeouts, call limits, and concurrency limits now reject non-finite, zero, negative, or wrong-type values at construction
+- **Release gates covered tests only (Low)**: CI now runs dependency auditing, Lint/Security checks, gem build/install, and an installed-artifact load/version smoke test alongside Ruby 3.2-3.4 tests
+
+### Known limitation
+
+- Ruby cannot safely force-terminate an arbitrary in-process block. A timed-out tool may still finish and commit side effects, so callers must treat `completion_unknown?` as an indeterminate outcome and use idempotency keys. Enforceable cancellation requires isolated worker processes or an external job backend in a future execution API
+
+## [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,12 @@ 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 partial_chars and partial_tool_calls. Always discard
+    # all text and structured tool state from the failed attempt.
+    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 +148,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 +160,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
 
@@ -235,7 +241,13 @@ registry.all                         # => [Definition, ...]
 Run tool calls in parallel or sequentially with automatic error handling and timeouts:
 
 ```ruby
-executor = RubyPi::Tools::Executor.new(registry, mode: :parallel, timeout: 30)
+executor = RubyPi::Tools::Executor.new(
+  registry,
+  mode: :parallel,
+  timeout: 30,
+  max_calls: 32,
+  max_concurrency: 4
+)
 
 results = executor.execute([
   { name: "create_post", arguments: { content: "Hello" } },
@@ -247,6 +259,7 @@ results.each do |r|
     puts "#{r.name}: #{r.value}"
   else
     puts "#{r.name} failed: #{r.error} (#{r.duration_ms}ms)"
+    reconcile_with_an_idempotency_key if r.completion_unknown?
   end
 end
 ```
@@ -258,6 +271,15 @@ end
 | `value` | Return value (on success) |
 | `error` | Error message (on failure) |
 | `duration_ms` | Execution time in milliseconds |
+| `status` | `:success`, `:error`, `:timeout_unknown`, or `:skipped` |
+| `completion_unknown?` | The deadline elapsed, but the in-process tool may still finish or commit side effects |
+| `skipped?` | Sequential execution did not start this call after an uncertain timeout |
+
+Parallel execution is bounded. A model response containing more than `max_calls`
+tool calls raises `RubyPi::ToolCallLimitError`, and the process refuses new work
+after 16 tools remain active. Ruby cannot safely kill an arbitrary
+in-process block, so use idempotency keys for side-effecting tools and treat
+`completion_unknown?` as indeterminate rather than as a confirmed rollback.
 
 ---
 
@@ -306,6 +328,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/core.rb

@@ -101,6 +101,12 @@ module RubyPi
         execution_mode: :parallel,
         tool_timeout: 30
       )
+        valid_timeout = tool_timeout.is_a?(Numeric) && !tool_timeout.is_a?(Complex) &&
+                        tool_timeout.finite? && tool_timeout.positive?
+        unless valid_timeout
+          raise ArgumentError, "tool_timeout must be a finite positive number, got #{tool_timeout.inspect}"
+        end
+
         @state = State.new(
           system_prompt: system_prompt,
           model: model,

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,54 @@ 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)
+        snapshot(value, {}.compare_by_identity).freeze
+      end
+
+      # Copies only JSON-like containers and immutable scalars. Arbitrary tool
+      # return objects are converted to a bounded diagnostic string instead of
+      # calling #dup, which may allocate resources, raise from initialize_copy,
+      # or recurse forever through cyclic structures.
+      def snapshot(value, memo)
+        if value.is_a?(Hash) || value.is_a?(Array)
+          return "[Circular]".freeze if memo.key?(value)
+
+          memo[value] = true
+        end
+
+        copy = case value
+               when Hash
+                 value.each_with_object({}) do |(key, item), result|
+                   result[snapshot(key, memo).freeze] = snapshot(item, memo).freeze
+                 end
+               when Array
+                 value.map { |item| snapshot(item, memo).freeze }
+               when String
+                 value.dup
+               when NilClass, TrueClass, FalseClass, Symbol, Numeric
+                 value
+               else
+                 safe_object_snapshot(value)
+               end
+
+        memo.delete(value) if value.is_a?(Hash) || value.is_a?(Array)
+        copy
+      end
+
+      def safe_object_snapshot(value)
+        rendered = value.to_s
+        rendered = rendered.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: "�")
+        rendered = rendered.byteslice(0, 4096).scrub if rendered.bytesize > 4096
+        "#<#{value.class}: #{rendered}>"
+      rescue StandardError
+        "#<#{value.class}: uninspectable>"
+      end
     end
   end
 end

data/lib/ruby_pi/agent/state.rb

@@ -77,10 +77,14 @@ module RubyPi
         after_tool_call: nil,
         user_data: {}
       )
+        unless max_iterations.is_a?(Integer) && max_iterations.positive?
+          raise ArgumentError, "max_iterations must be a positive integer, got #{max_iterations.inspect}"
+        end
+
         @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 +107,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 +116,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 +125,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 +172,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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "json"
+
 # lib/ruby_pi/context/compaction.rb
 #
 # RubyPi::Context::Compaction — Token estimation and context window management.
@@ -28,6 +30,7 @@ module RubyPi
       # Average characters per token — a rough heuristic that avoids the need
       # for provider-specific tokenizers. Errs on the conservative side.
       CHARS_PER_TOKEN = 4
+      SUMMARY_METADATA_LIMIT = 16_384
 
       # @return [Integer] the token threshold above which compaction triggers
       attr_reader :max_tokens
@@ -95,7 +98,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 +142,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 +162,9 @@ 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
+          metadata = msg.reject { |key, _| key == :role || key == "role" || key == :content || key == "content" }
+          total_chars += serialized_message(metadata).length unless metadata.empty?
           # Account for role and structural overhead (~10 tokens per message)
           total_chars += 40
         end
@@ -199,14 +205,28 @@ 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}: #{content}"
+          role = message_value(msg, :role).to_s.capitalize
+          content = message_value(msg, :content).to_s
+          metadata = msg.reject { |key, _| key == :role || key == "role" || key == :content || key == "content" }
+          metadata_text = metadata.empty? ? nil : serialized_message(metadata).slice(0, SUMMARY_METADATA_LIMIT)
+          ["#{role}: #{content}", ("Structured metadata: #{metadata_text}" if metadata_text)].compact.join("\n")
         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
+
+      def serialized_message(message)
+        JSON.generate(message)
+      rescue JSON::GeneratorError, TypeError
+        message.to_s
+      end
     end
   end
 end

data/lib/ruby_pi/errors.rb

@@ -39,6 +39,14 @@ module RubyPi
     end
   end
 
+  # Raised when an HTTP streaming response violates the provider's protocol.
+  # This includes malformed SSE data, invalid UTF-8, oversized events, and a
+  # connection that closes before the provider's terminal event arrives.
+  #
+  # It inherits from ApiError with a nil status code so BaseProvider treats a
+  # broken HTTP-200 stream like a transient transport failure and can retry it.
+  class StreamingProtocolError < ApiError; end
+
   # Raised when authentication fails (HTTP 401 or 403). Typically indicates
   # an invalid, expired, or missing API key.
   class AuthenticationError < ApiError
@@ -112,4 +120,12 @@ module RubyPi
       super(message || "Model returned tool calls but no tools are registered")
     end
   end
+
+  # Raised when a model asks the executor to exceed its configured per-turn
+  # tool-call safety limit.
+  class ToolCallLimitError < Error; end
+
+  # Raised when too many previously timed-out in-process tools are still
+  # running and accepting more work would risk thread exhaustion.
+  class ToolExecutionCapacityError < Error; end
 end

data/lib/ruby_pi/extensions/base.rb

@@ -72,14 +72,6 @@ module RubyPi
           end
         end
 
-        # Returns the extension name. Override in subclasses to provide
-        # a human-readable identifier.
-        #
-        # @return [String] the extension name
-        def name
-          super
-        end
-
         private
 
         # Returns the hooks hash defined directly on this class (not