ruby-pi 0.1.5 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 45a50058497c3e040f81e977ffdbe0030b901ea053e91002e4ddddba06c23a6f
-  data.tar.gz: 6066bc184d7f8eb951ae137595a8ed082ec41c3abc8ca84cbfe5b4206fde6f66
+  metadata.gz: b0054adb6a0863a8f296917be736df0ebfd789aa7205589b82689199d4bf4c06
+  data.tar.gz: fc79dcc61dbefce874e609807d989cf2293b0ecb45a6aa036069b11038ac5c9a
 SHA512:
-  metadata.gz: d486b3a171dca8c59bf442ba5c03f135ee450a083c47c05f075af6b23d87eb24285c72c734a9579456d71d6ac247ed4357f7bd16b813219e77655a98f44b0cc2
-  data.tar.gz: 602ed6dc493731203c9fedb8d69f118c81ce292c653ca42ac4ca0d9f8d793dc281697fa87f9df9f7601022812dd791d4420d0f22ba89ad6051119791e87f33ca
+  metadata.gz: c130ada9b7ed93f5c9a0d16596c1176fec258204be26af15c61db3c18effee94bc7a8a1783620397780b0e3501e660b4e8ff48d8463e4089067edfcbf3bf9b60
+  data.tar.gz: dc179fe40cb063c4321a1c7a1aff5abb7b441d5fd87ced19908f9875c1f5b26bf2e17555b44658f603b32627577fe99feb8f34d061ed7e53eaba3c28cecd8bbb

data/CHANGELOG.md

@@ -5,6 +5,57 @@ 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.8] - 2026-06-09
+
+### Fixed (adversarial review round 6)
+
+- **`Retry-After` header was parsed but never honored (High)**: On a 429, `handle_error_response` stored the server's `Retry-After` on `RateLimitError#retry_after`, but the retry loop in `BaseProvider#complete` always slept the local exponential backoff (capped at `retry_max_delay`) — hammering a server that asked for a longer cooldown until the retry budget burned out. The retry delay now prefers a positive `retry_after` (capped at `RETRY_AFTER_CEILING`, 60s); HTTP-date values (which parse to `0.0`) and absent headers fall through to the computed backoff
+- **Parallel executor timeout/rejection Results reported `name: "unknown"` (High)**: `execute_parallel` hardcoded `"unknown"` in the timeout and rejected-future branches, so with several tools timing out concurrently, logs and `:tool_execution_end` subscribers could not tell which tool hung. Futures are now zipped with their originating calls and failure Results carry the real tool name; the timeout message matches sequential mode (`Tool 'x' timed out after Ns`). The rejected-future branch also no longer reports a misleading full-timeout `duration_ms` for what may have been an instant failure (now `0.0`)
+- **Keyword-parameter tool blocks failed on every call (High)**: `Definition#call` passed a single positional Hash, so a block written `{ |content:, platform:| ... }` — the natural style given named schema parameters — raised `ArgumentError: missing keyword` on every invocation (surfacing as a confusing failed Result). `Definition` now detects keyword parameters at construction and splats the arguments hash to keywords; positional-Hash blocks are unchanged. Keyword blocks without `**rest` raise on unexpected keys — strict by design, since the keys come from the LLM
+- **`:compaction` event was never emitted in production (Medium)**: `Compaction#emitter` defaults to nil and nothing ever assigned it, so the documented `agent.on(:compaction)` subscription silently never fired — the only place the emitter was set was the spec itself. `Loop#initialize` now wires its emitter into the compaction strategy (an explicitly preassigned emitter is left untouched)
+- **Streaming chunks were never normalized to UTF-8 (Medium)**: Faraday delivers `on_data` chunks as ASCII-8BIT; appending a chunk to a UTF-8 SSE buffer already holding non-ASCII text raises `Encoding::CompatibilityError`, and yielded deltas could carry binary encoding into consumers' UTF-8 buffers. All three providers now buffer in BINARY and re-encode each complete SSE line to UTF-8 (with `scrub` guarding invalid bytes) before parsing, so `:text_delta` events are always valid UTF-8 — including multi-byte characters split across network chunks
+- **Streaming fallback gave consumers no way to truncate partial primary output (Medium)**: If the primary streamed text and then died mid-stream, the fallback streamed a complete fresh response — a delta-appending consumer rendered `"<partial primary><full fallback>"` with no signal of how much to discard. The `:fallback_start` payload now includes `partial_output` (Boolean) and `partial_chars` (characters already yielded), so consumers can deterministically reset
+- **Tool names were not validated against provider constraints (Medium)**: A tool named `send.email` registered fine and then 400'd on every Anthropic request with an opaque server error. `Definition` now validates names against `/\A[a-zA-Z0-9_-]{1,64}\z/` (the strictest provider constraint) and raises `ArgumentError` at definition time with a pointed message
+- **`json` was used everywhere but never declared or required (Medium)**: `JSON.parse`/`JSON.generate` are called throughout the providers and agent loop, but the gem relied on Faraday's transitive `json` dependency and the entry point's single `require "json"` — loading `agent/loop.rb` in isolation raised `NameError`, contradicting the composability principle. The gemspec now declares `json >= 2.0` and every file referencing `JSON` requires it directly (pinned by a source-scan spec)
+- **Configuration accepted negative retry/timeout values (Low)**: `max_retries = -1` silently disabled retries and a negative delay raised deep inside the retry loop's `sleep`. The numeric settings now have validated writers that raise `ArgumentError` at assignment time
+- **Global configuration first-access race (Low)**: `@configuration ||= Configuration.new` was unsynchronized; two threads racing the first call could each construct a Configuration with one silently discarded. The configuration is now eagerly initialized at require time
+- **`continue()` Result accounting documented (Docs)**: Each `run`/`continue` builds a fresh Loop, so the returned Result's `usage`/`tool_calls_made`/`turns` cover only that invocation while `messages` is cumulative — an undocumented asymmetry, now documented on `Core#continue`
+- **Schema DSL documented as LLM-facing hints, not validation (Docs)**: Nothing validates model-supplied arguments against `tool.parameters` before invoking the block — `required`/`enum`/`minimum` constrain what the model is asked to produce, with no runtime enforcement or type coercion. This is deliberate (anti-framework), but the schema header now says so loudly and directs tool blocks to treat arguments as untrusted input
+- **`State#add_message` unbounded growth documented (Docs)**: Long-lived agents calling `continue()` repeatedly accumulate messages linearly without compaction configured; documented on the method
+- **CLAUDE.md module map corrected (Docs)**: The map referenced a nonexistent `agent/agent.rb`, omitted `core.rb`/`loop.rb`/`state.rb`/`events.rb`, hardcoded version `0.1.0`, and the extension example used the one-arg `|event|` block signature instead of the actual `|data, agent|`. All corrected
+
+### Release-history note
+
+- **`[0.1.4]` below was never actually released**: `lib/ruby_pi/version.rb` went from `0.1.3` directly to `0.1.5` — the round-2 fixes documented under 0.1.4 shipped without a version bump and were first published as part of 0.1.5. There is intentionally no `v0.1.4` git tag or gem. (Discovered during round 6; the entry is kept for historical accuracy of *what* changed.)
+
+## [0.1.7] - 2026-05-28
+
+### Fixed (adversarial review round 5)
+
+- **Compaction produced an Anthropic-invalid leading `:assistant` message (Critical)**: The 0.1.6 orphan-`:tool` strip fixed tool-result splitting but left the summary-role logic (`first_preserved == :assistant ? :user : :assistant`) intact. Whenever the first preserved message was `:user` (multi-turn reuse) or the preserved window emptied out (all tool results), the summary became an `:assistant` message at the head of the conversation — which Anthropic rejects with HTTP 400 "first message must use the 'user' role". The summary is now **always** a `:user` message (valid as the first message and never overwriting the system prompt). When the first preserved message is itself `:user`, the summary is merged into it to avoid consecutive same-role messages; an empty preserved window yields a lone `:user` summary. Extracted into `Compaction#build_compacted_history`
+- **Compaction dead "mirror case" branch removed (Minor)**: The 0.1.6 `if droppable.last … && preserved.first[:role] == :tool` block was unreachable — the preceding `while` loop guarantees `preserved.first` is never `:tool`. Removed it (the originating assistant message is already in droppable alongside its now-moved tool results, so the pair is never split), eliminating misleading dead code
+- **Deterministic `ProviderError` was retried with backoff (Minor)**: 0.1.6 added `RubyPi::ProviderError` to the retryable set in `BaseProvider#complete`, but provider errors are overwhelmingly deterministic request-construction failures (missing `tool_call_id`, invalid tool-argument JSON) raised before any HTTP call — retrying only burned the backoff schedule before re-raising the identical error. `ProviderError` is no longer retried. Fallback failover is unaffected (it rescues the `RubyPi::Error` superclass)
+- **Lifecycle hooks saw string-keyed tool arguments while events saw symbols (Minor)**: `before_tool_call`/`after_tool_call` received the raw `ToolCall` (string-keyed `arguments`) while the `:tool_execution_start` event and `tool_calls_made` carried symbol keys — so a hook and an event subscriber disagreed on the key type for the same call. `Loop#act` now rebuilds each `ToolCall` with symbol-keyed arguments up front, so hooks, events, `tool_calls_made`, and the tool block all observe the identical shape
+- **Anthropic streaming `finish_reason` could be clobbered to nil (Minor)**: A trailing `message_delta` event without a `stop_reason` overwrote the previously captured value, yielding a `Response` with no `finish_reason`. The assignment is now guarded (`finish_reason = delta["stop_reason"] if delta["stop_reason"]`), matching the OpenAI/Gemini guards
+- **Gemini `finishReason` assumed a String (Minor)**: `finishReason.downcase` would raise `NoMethodError` on a non-String payload mid-stream. Both the streaming and standard paths now coerce via `to_s` before `downcase`, and remain consistent with each other
+- **Dead streamed-content accumulator removed (Cleanup)**: `Loop#think` accumulated `streamed_content` that was never read (the recorded assistant message uses `Response#content`); the `.clear` on `:fallback_start` was a no-op and its comment was inaccurate. Removed the local; the `:provider_fallback` event still fires
+- **`Fallback` class docstring corrected (Docs)**: The class-level docstring still described the removed happy-path buffering ("the Fallback now buffers deltas… buffered deltas are discarded"), contradicting the real-time direct-streaming implementation. Updated to describe direct streaming plus the `:fallback_start` signal
+
+### Investigated, no change
+
+- **Streaming HTTP error bodies via `env.status`**: A prior review raised that streaming error responses might lose their body if Faraday's `on_data` callback received a nil `env.status`. Verified against the actual stack (faraday 2.14.1 / faraday-net_http 3.3.0): the net_http adapter calls `save_http_response` (which sets `env.status`) before `response.read_body` streams chunks, and `Env#stream_response` passes that same populated `env` to the user's `on_data` proc. `env.status` is therefore reliably available before the first chunk, so the existing `error_body` recovery works. No fix needed
+
+## [0.1.6] - 2026-05-01
+
+### Fixed (adversarial review round 4)
+
+- **Faraday transport errors leaked untyped, bypassed retry (Critical)**: `BaseProvider#complete` rescued only `RubyPi::*` errors, but providers never wrapped Faraday network exceptions. A `Faraday::TimeoutError`, `Faraday::ConnectionFailed`, or `Faraday::SSLError` propagated as the raw Faraday class — breaking the documented error hierarchy and skipping the retry loop entirely (the exact case retries exist for). Added `BaseProvider#with_transport_errors` which translates `Faraday::TimeoutError` → `RubyPi::TimeoutError` and `Faraday::ConnectionFailed`/`SSLError`/other `Faraday::Error` → `RubyPi::ApiError`. Wrapped every `conn.post` call in all three providers (standard and streaming paths). `RubyPi::ProviderError` is now also retryable
+- **Gemini multi-turn tool use was broken (Critical)**: `Gemini#format_message` rendered assistant messages as text-only and silently dropped the `:tool_calls` field set by the agent loop. The next turn's `functionResponse` had no preceding `functionCall` to bind to, so Gemini rejected any conversation that included a tool call followed by a tool result. Assistant messages now emit one `functionCall` part per tool call (mirroring Anthropic's `tool_use` and OpenAI's `tool_calls` behavior). Empty text parts are also no longer emitted on tool-only assistant turns
+- **Compaction split tool_use/tool_result pairs (Critical)**: When `preserve_last_n` cut between an assistant `tool_calls` message (in droppable) and its matching `:tool` result (in preserved), Anthropic and OpenAI rejected the conversation with "tool_result without preceding tool_use". Compaction now strips orphan `:tool` messages from the head of preserved (moves them into droppable so they're summarized away). Mirror case where preserved starts with a tool result whose assistant is the last droppable message also handled
+- **`Tools::Executor` swallowed non-StandardError exceptions as nil success (Major)**: The worker thread rescued only `StandardError`. A tool block raising `Interrupt`, `SystemExit`, or any other `Exception` subclass left both `value` and `error` nil; the join then reported a *successful* `nil` result. Now rescues `Exception`, captures it as a failed `Result`. Worker thread also sets `report_on_exception = false` to avoid stderr spam
+- **Gemini tool_call IDs collided across turns (Major)**: IDs were generated as `"gemini_#{accumulated_tool_calls.length}"` — every response restarted numbering at 0, so a multi-turn conversation produced multiple tool calls all named `"gemini_0"`. Any caller using ID as a hash key (observability, result correlation) saw collisions. IDs now use `SecureRandom.hex(8)` for global uniqueness across both standard and streaming responses
+- **OpenAI passed malformed tool_call.arguments JSON verbatim (Minor)**: A non-JSON string in `tool_call.arguments` on an assistant message was forwarded unchanged to OpenAI, producing an opaque HTTP 400. Now validated up-front with `JSON.parse`; malformed input raises a typed `RubyPi::ProviderError` with the tool name and parse error before sending the request, matching Anthropic's input validation
+
 ## [0.1.5] - 2026-04-30
 
 ### Fixed (adversarial review round 3)

data/lib/ruby_pi/agent/core.rb

@@ -140,12 +140,18 @@ module RubyPi
       # the existing conversation history and appends the new prompt before
       # resuming the loop.
       #
+      # NOTE on Result accounting: each run/continue builds a fresh Loop, so
+      # the returned Result's `usage`, `tool_calls_made`, and `turns` cover
+      # ONLY this invocation — while `messages` is cumulative across the whole
+      # conversation. Sum the per-call Results if you need session totals.
+      #
       # Issue #16: Uses the encapsulated reset_iteration! method instead of
       # the old approach that bypassed encapsulation
       # and was fragile.
       #
       # @param prompt [String] the follow-up user message
       # @return [RubyPi::Agent::Result] the outcome of the continued run
+      #   (usage/tool_calls_made/turns are per-invocation; messages cumulative)
       def continue(prompt)
         @state.reset_iteration!
         @state.add_message(role: :user, content: prompt)

data/lib/ruby_pi/agent/loop.rb

@@ -10,6 +10,8 @@
 # is reached. It handles streaming, lifecycle events, compaction, and all
 # pre/post tool call hooks.
 
+require "json"
+
 module RubyPi
   module Agent
     # Executes the think-act-observe cycle against a given State, emitting
@@ -55,6 +57,14 @@ module RubyPi
         @state = state
         @emitter = emitter
         @compaction = compaction
+        # Wire the loop's emitter into the compaction strategy so the
+        # documented :compaction event actually reaches agent subscribers.
+        # Compaction#emitter defaults to nil and nothing else ever sets it —
+        # without this, `agent.on(:compaction)` never fires. An emitter that
+        # was already assigned explicitly is left untouched.
+        if @compaction.respond_to?(:emitter=) && @compaction.respond_to?(:emitter) && @compaction.emitter.nil?
+          @compaction.emitter = emitter
+        end
         @execution_mode = execution_mode
         @tool_timeout = tool_timeout
         @tool_calls_made = []
@@ -145,17 +155,16 @@ module RubyPi
         # Build tools array for the LLM
         tools = build_tools_array
 
-        # Accumulate streamed content
-        streamed_content = +""
-
-        # Call the LLM with streaming
+        # Call the LLM with streaming. The recorded assistant message uses
+        # the returned Response#content (already the final, authoritative
+        # text), so there is no need to accumulate deltas here — we only
+        # re-emit them for subscribers.
         response = @state.model.complete(
           messages: messages,
           tools: tools,
           stream: true
         ) do |event|
           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
@@ -164,12 +173,11 @@ module RubyPi
             @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
+            # provider is now taking over. Surface a :provider_fallback event
+            # so subscribers can clear any UI state they rendered from the
+            # discarded primary deltas. The recorded response is unaffected:
+            # it comes from the fallback provider's returned Response#content,
+            # never from the failed primary's partial text.
             @emitter.emit(:provider_fallback, **event.data)
           end
         end
@@ -208,32 +216,39 @@ module RubyPi
           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)
+        # Normalize each tool call's arguments to symbol keys ONCE, up front,
+        # by rebuilding the ToolCall objects. Every downstream consumer — the
+        # executor (which invokes the tool block), the before/after_tool_call
+        # hooks (which receive the ToolCall directly), the emitted
+        # :tool_execution_start event, and the recorded `tool_calls_made`
+        # payload — then observes the identical symbol-keyed shape. Carrying
+        # the symbolized form on the ToolCall itself (rather than in a side
+        # array) is what keeps the hooks consistent with everything else;
+        # previously hooks saw raw string keys while events/records saw symbols.
+        tool_calls = response.tool_calls.map do |tc|
+          RubyPi::LLM::ToolCall.new(
+            id: tc.id,
+            name: tc.name,
+            arguments: RubyPi::Tools::Executor.deep_symbolize_keys(tc.arguments)
+          )
         end
 
         # Prepare call hashes for the executor
-        calls = response.tool_calls.each_with_index.map do |tc, idx|
-          { name: tc.name, arguments: symbolized[idx] }
+        calls = tool_calls.map do |tc|
+          { name: tc.name, arguments: tc.arguments }
         end
 
         # Fire before_tool_call hooks and emit start events
-        response.tool_calls.each_with_index do |tc, idx|
+        tool_calls.each do |tc|
           @state.before_tool_call&.call(tc)
-          @emitter.emit(:tool_execution_start, tool_name: tc.name, arguments: symbolized[idx])
+          @emitter.emit(:tool_execution_start, tool_name: tc.name, arguments: tc.arguments)
         end
 
         # Execute all tool calls
         results = executor.execute(calls)
 
         # Fire after_tool_call hooks, emit end events, and add results to messages
-        response.tool_calls.each_with_index do |tc, idx|
+        tool_calls.each_with_index do |tc, idx|
           result = results[idx]
 
           @state.after_tool_call&.call(tc, result)
@@ -247,7 +262,7 @@ module RubyPi
           # arguments so callers see the same shape the tool itself received.
           @tool_calls_made << {
             tool_name: tc.name,
-            arguments: symbolized[idx],
+            arguments: tc.arguments,
             result: result.to_h
           }
 

data/lib/ruby_pi/agent/state.rb

@@ -91,6 +91,12 @@ module RubyPi
 
       # Appends a message to the conversation history.
       #
+      # NOTE: history grows without bound — there is no built-in cap. Growth
+      # per run is limited by max_iterations, but long-lived agents that call
+      # continue() repeatedly (or use a high max_iterations with large tool
+      # outputs) accumulate messages linearly. Configure
+      # Agent.new(compaction: ...) to keep the context bounded.
+      #
       # @param role [Symbol, String] the message role (:user, :assistant, :system, :tool)
       # @param content [String, nil] the text content of the message
       # @param options [Hash] additional fields (e.g., :tool_call_id, :tool_calls)

data/lib/ruby_pi/configuration.rb

@@ -37,19 +37,53 @@ module RubyPi
     attr_accessor :openai_api_key
 
     # @return [Integer] Maximum number of retry attempts for transient errors (default: 3)
-    attr_accessor :max_retries
+    attr_reader :max_retries
 
     # @return [Float] Base delay in seconds for exponential backoff (default: 1.0)
-    attr_accessor :retry_base_delay
+    attr_reader :retry_base_delay
 
     # @return [Float] Maximum delay in seconds between retries (default: 30.0)
-    attr_accessor :retry_max_delay
+    attr_reader :retry_max_delay
 
     # @return [Integer] HTTP request timeout in seconds (default: 120)
-    attr_accessor :request_timeout
+    attr_reader :request_timeout
 
     # @return [Integer] HTTP connection open timeout in seconds (default: 10)
-    attr_accessor :open_timeout
+    attr_reader :open_timeout
+
+    # Validated writers for numeric settings. A negative max_retries silently
+    # disables retries and a negative delay raises deep inside the retry
+    # loop's sleep — fail fast at assignment time instead, where the typo is.
+
+    # @param value [Integer] must be a non-negative integer
+    def max_retries=(value)
+      validate_numeric!(:max_retries, value)
+      @max_retries = value
+    end
+
+    # @param value [Numeric] must be non-negative
+    def retry_base_delay=(value)
+      validate_numeric!(:retry_base_delay, value)
+      @retry_base_delay = value
+    end
+
+    # @param value [Numeric] must be non-negative
+    def retry_max_delay=(value)
+      validate_numeric!(:retry_max_delay, value)
+      @retry_max_delay = value
+    end
+
+    # @param value [Numeric] must be non-negative
+    def request_timeout=(value)
+      validate_numeric!(:request_timeout, value)
+      @request_timeout = value
+    end
+
+    # @param value [Numeric] must be non-negative
+    def open_timeout=(value)
+      validate_numeric!(:open_timeout, value)
+      @open_timeout = value
+    end
 
     # @return [String] Default model name for Gemini provider
     attr_accessor :default_gemini_model
@@ -78,6 +112,17 @@ module RubyPi
 
     private
 
+    # Raises unless the value is a non-negative Numeric.
+    #
+    # @param name [Symbol] the setting name (for the error message)
+    # @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
+
+      raise ArgumentError, "#{name} must be a non-negative number, got #{value.inspect}"
+    end
+
     # 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!.

data/lib/ruby_pi/context/compaction.rb

@@ -75,40 +75,77 @@ module RubyPi
 
         # Split into messages to summarize and messages to keep
         preserved_count = [@preserve_last_n, messages.size].min
-        droppable = messages[0...(messages.size - preserved_count)]
-        preserved = messages[(messages.size - preserved_count)..]
+        droppable = messages[0...(messages.size - preserved_count)].dup
+        preserved = messages[(messages.size - preserved_count)..].dup
 
         # If there's nothing to drop, we can't compact further
         return nil if droppable.empty?
 
+        # Anthropic and OpenAI both require every tool_result / tool message
+        # to reference a tool_use / tool_call from a preceding assistant
+        # message. If we summarize the assistant turn that originated a tool
+        # call but keep the matching tool_result, the API rejects the
+        # request with "tool_result without preceding tool_use".
+        #
+        # When the boundary between droppable and preserved cuts mid-exchange,
+        # preserved can start with one or more orphan :tool messages whose
+        # matching assistant turn is in droppable. Strip those off the head of
+        # preserved and move them into droppable so they are summarized away
+        # rather than sent. Because the originating assistant message is older,
+        # 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
+          droppable << preserved.shift
+        end
+
+        # The orphan-strip only moves messages INTO droppable, so droppable
+        # cannot have shrunk; it is still non-empty here. preserved, however,
+        # may now be empty (the whole window was tool results) — the summary
+        # construction below handles that case.
+
         # Generate a summary of the dropped messages
         summary = summarize(droppable)
 
         # Emit compaction event if an emitter is available
         @emitter&.emit(:compaction, dropped_count: droppable.size, summary: summary)
 
-        # 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: summary_role,
-          content: "[Conversation Summary]\n#{summary}"
-        }
-
-        [summary_message] + preserved
+        build_compacted_history(summary, preserved)
+      end
+
+      # Builds the compacted history: a summary message followed by the
+      # preserved tail.
+      #
+      # The summary becomes the FIRST message of the compacted history, so it
+      # must satisfy the strictest provider constraints (Anthropic):
+      #   1. The summary role MUST NOT be :system — that would overwrite the
+      #      real system prompt on Anthropic, which promotes the last :system
+      #      message to the top-level `system:` parameter.
+      #   2. The first message MUST use role :user.
+      #   3. Consecutive same-role messages are rejected.
+      #
+      # A :user summary satisfies (1) and (2). For (3): the orphan-strip above
+      # guarantees the first preserved message is :assistant, :user, or absent
+      # (never :tool). When it is :assistant or absent, a standalone :user
+      # summary alternates correctly. When it is :user, a separate :user
+      # summary would create two consecutive user messages, so we instead
+      # merge the summary text into that existing user message — keeping the
+      # first message a single :user message with no role collision.
+      #
+      # @param summary [String] the generated summary text
+      # @param preserved [Array<Hash>] the preserved tail of messages
+      # @return [Array<Hash>] the compacted history
+      def build_compacted_history(summary, preserved)
+        summary_text = "[Conversation Summary]\n#{summary}"
+        first_preserved = preserved.first
+
+        if first_preserved && first_preserved[:role] == :user
+          merged = first_preserved.dup
+          merged[:content] = "#{summary_text}\n\n#{first_preserved[:content]}"
+          [merged] + preserved.drop(1)
+        else
+          [{ role: :user, content: summary_text }] + preserved
+        end
       end
 
       # Estimates the total token count for a system prompt and message array

data/lib/ruby_pi/llm/anthropic.rb

@@ -6,6 +6,8 @@
 # the Anthropic Messages API for both synchronous and streaming completions,
 # including tool_use block support.
 
+require "json"
+
 module RubyPi
   module LLM
     # Anthropic Claude provider implementation. Communicates with the Anthropic
@@ -330,9 +332,11 @@ module RubyPi
           headers: default_headers
         )
 
-        response = conn.post("/v1/messages") do |req|
-          req.headers["Content-Type"] = "application/json"
-          req.body = JSON.generate(body)
+        response = with_transport_errors do
+          conn.post("/v1/messages") do |req|
+            req.headers["Content-Type"] = "application/json"
+            req.body = JSON.generate(body)
+          end
         end
 
         handle_error_response(response) unless response.success?
@@ -368,18 +372,26 @@ module RubyPi
         # process complete lines incrementally so that deltas reach the caller
         # as soon as each SSE event is fully received — not after the entire
         # response has been buffered.
-        sse_buffer = +""
+        #
+        # The buffer is BINARY because chunks arrive as ASCII-8BIT and may end
+        # mid-way through a multi-byte UTF-8 character; appending such a chunk
+        # to a UTF-8 buffer that already holds non-ASCII text raises
+        # Encoding::CompatibilityError. Each complete line is re-encoded to
+        # UTF-8 (and scrubbed) before parsing, so deltas reach the caller as
+        # valid UTF-8 strings.
+        sse_buffer = (+"").force_encoding(Encoding::BINARY)
         response_status = nil
 
         # Accumulate error response body separately so ApiError gets the
         # full body even though on_data consumed the chunks.
-        error_body = +""
+        error_body = (+"").force_encoding(Encoding::BINARY)
 
-        response = conn.post("/v1/messages") do |req|
-          req.headers["Content-Type"] = "application/json"
-          req.body = JSON.generate(body)
+        response = with_transport_errors do
+          conn.post("/v1/messages") do |req|
+            req.headers["Content-Type"] = "application/json"
+            req.body = JSON.generate(body)
 
-          # Use Faraday's on_data callback for real incremental streaming.
+            # Use Faraday's on_data callback for real incremental streaming.
           # Without this, Faraday buffers the entire response body before
           # returning, which means no deltas reach the caller until the model
           # finishes generating (fake streaming).
@@ -391,14 +403,17 @@ module RubyPi
             # calls on_data for error responses too, which would otherwise
             # consume the body and leave response.body empty.
             if response_status && response_status >= 400
-              error_body << chunk
+              error_body << chunk.b
               next
             end
 
-            sse_buffer << chunk
-            # Process all complete lines in the buffer
+            sse_buffer << chunk.b
+            # Process all complete lines in the buffer. A complete line holds
+            # complete UTF-8 sequences (multi-byte characters split across
+            # chunks are repaired by the buffering), so re-encode it to UTF-8
+            # here; scrub guards against a server sending invalid bytes.
             while (line_end = sse_buffer.index("\n"))
-              line = sse_buffer.slice!(0, line_end + 1).strip
+              line = sse_buffer.slice!(0, line_end + 1).force_encoding(Encoding::UTF_8).scrub.strip
               next if line.empty?
               next unless line.start_with?("data: ")
 
@@ -424,7 +439,8 @@ module RubyPi
               finish_reason = stream_state[:finish_reason]
             end
           end
-        end
+          end # conn.post
+        end # with_transport_errors
 
         # Check for HTTP errors. When on_data was active, the response body
         # was consumed by the callback, so we pass the accumulated error_body
@@ -432,12 +448,12 @@ module RubyPi
         unless response.success?
           # Reconstruct the response body from what on_data accumulated
           error_response = response
-          error_body_str = error_body.empty? ? response.body : error_body
+          error_body_str = error_body.empty? ? response.body : error_body.force_encoding(Encoding::UTF_8).scrub
           handle_error_response(error_response, override_body: error_body_str)
         end
 
         # Process any remaining data in the buffer after the connection closes
-        sse_buffer.each_line do |line|
+        sse_buffer.force_encoding(Encoding::UTF_8).scrub.each_line do |line|
           line = line.strip
           next if line.empty?
           next unless line.start_with?("data: ")
@@ -558,7 +574,12 @@ module RubyPi
 
         when "message_delta"
           delta = data["delta"] || {}
-          finish_reason = delta["stop_reason"]
+          # Only overwrite finish_reason when this delta actually carries a
+          # stop_reason. Anthropic emits the stop_reason on a single
+          # message_delta near the end of the stream; a later message_delta
+          # without one must not clobber the captured value back to nil
+          # (which would yield a Response with no finish_reason).
+          finish_reason = delta["stop_reason"] if delta["stop_reason"]
           if data.key?("usage")
             usage_info = data["usage"]
             usage_data[:completion_tokens] = usage_info["output_tokens"]

data/lib/ruby_pi/llm/base_provider.rb

@@ -79,13 +79,22 @@ module RubyPi
           # Authentication errors are not retryable — raise immediately
           raise
         rescue RubyPi::RateLimitError, RubyPi::ApiError, RubyPi::TimeoutError => e
+          # NOTE: RubyPi::ProviderError is intentionally NOT retried. Provider
+          # errors are overwhelmingly deterministic request-construction
+          # failures (missing tool_call_id, invalid tool-argument JSON, missing
+          # tool name) raised by build_request_body BEFORE any HTTP call. They
+          # produce the identical error on every attempt, so retrying only
+          # burns the backoff schedule before surfacing the same failure.
+          # Fallback wrappers still rescue RubyPi::Error (the ProviderError
+          # superclass), so provider failover is unaffected.
+          #
           # Retry up to max_retries times AFTER the initial attempt.
           # With max_retries: 3, attempt goes 1 (initial), 2, 3, 4 — the condition
           # `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
-            delay = calculate_backoff(attempt)
+            delay = retry_delay_for(e, attempt)
             log_retry(attempt, delay, e)
             sleep(delay)
             retry
@@ -127,6 +136,29 @@ module RubyPi
         raise RubyPi::AbstractMethodError, :perform_complete
       end
 
+      # Maximum delay (seconds) honored from a server-provided Retry-After
+      # header. Caps pathological or misconfigured server values so a single
+      # 429 cannot stall the client indefinitely.
+      RETRY_AFTER_CEILING = 60.0
+
+      # Picks the delay before the next retry. A server-provided Retry-After
+      # on a 429 takes precedence over the local exponential backoff: the
+      # server knows its own cooldown window, and retrying earlier just burns
+      # the retry budget against guaranteed 429s. Retry-After parsed from an
+      # HTTP-date (rather than delta-seconds) arrives as 0.0 and falls through
+      # to the computed backoff.
+      #
+      # @param error [Exception] the error that triggered the retry
+      # @param attempt [Integer] the current attempt number (1-based)
+      # @return [Float] delay in seconds
+      def retry_delay_for(error, attempt)
+        if error.is_a?(RubyPi::RateLimitError) && error.retry_after&.positive?
+          [error.retry_after, RETRY_AFTER_CEILING].min
+        else
+          calculate_backoff(attempt)
+        end
+      end
+
       # Calculates the backoff delay for a given retry attempt using
       # exponential backoff with jitter.
       #
@@ -178,6 +210,45 @@ module RubyPi
         end
       end
 
+      # Wraps an HTTP block, translating Faraday transport-level exceptions
+      # (DNS failures, connection resets, TLS handshakes, read/write timeouts)
+      # into the RubyPi typed-error hierarchy so callers and the retry loop
+      # can rescue them uniformly.
+      #
+      # Without this wrapper, a `Faraday::TimeoutError` or
+      # `Faraday::ConnectionFailed` would propagate out of the provider as
+      # the raw Faraday class. That breaks two contracts:
+      #   1. The documented retry policy (BaseProvider#complete) only rescues
+      #      RubyPi errors, so transport failures would not be retried —
+      #      exactly the case retries exist for.
+      #   2. Callers `rescue RubyPi::TimeoutError` per the documented error
+      #      hierarchy and would not catch real network timeouts.
+      #
+      # @yield the HTTP call to wrap
+      # @return [Object] whatever the block returns
+      # @raise [RubyPi::TimeoutError] on Faraday::TimeoutError
+      # @raise [RubyPi::ApiError] on connection failures, SSL errors, or
+      #   any other Faraday::Error not otherwise classified
+      def with_transport_errors
+        yield
+      rescue Faraday::TimeoutError => e
+        raise RubyPi::TimeoutError, "#{provider_name} request timed out: #{e.message}"
+      rescue Faraday::ConnectionFailed, Faraday::SSLError => e
+        raise RubyPi::ApiError.new(
+          "#{provider_name} transport error: #{e.class}: #{e.message}",
+          status_code: nil,
+          response_body: nil
+        )
+      rescue Faraday::Error => e
+        # Catch-all for any other Faraday-level failure (parsing, adapter
+        # issues, etc.) so transport problems never leak provider internals.
+        raise RubyPi::ApiError.new(
+          "#{provider_name} HTTP client error: #{e.class}: #{e.message}",
+          status_code: nil,
+          response_body: nil
+        )
+      end
+
       # Handles HTTP error responses by raising the appropriate RubyPi error.
       # When streaming with on_data, the response body is consumed by the
       # callback and response.body may be empty. Pass override_body with the