ruby-pi 0.1.6 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c78d37122ed67d80e61cf51b182dcd79a20a7efa77b503c8b0340963ad60b728
-  data.tar.gz: e3b147cb2b01fe28ac15c2a65d6177156992be7560601886296b16941784ee08
+  metadata.gz: b0054adb6a0863a8f296917be736df0ebfd789aa7205589b82689199d4bf4c06
+  data.tar.gz: fc79dcc61dbefce874e609807d989cf2293b0ecb45a6aa036069b11038ac5c9a
 SHA512:
-  metadata.gz: cbc0c9abddf98885bf1a22352a9cd09475c324f9aff4bcdff66ce3a6a87e06eb677ab045c966038666744cf9819d5114714c66ba5b7c676de5958d5d964a6242
-  data.tar.gz: 3f9c28b1a30d0e3ad0f1badd391c95065adea822927c1d334dc5fc5c9867e658b43e339e9307dd3eba8dd5a534043c9fae3ea8d0384bfae8eb35a1a09356f035
+  metadata.gz: c130ada9b7ed93f5c9a0d16596c1176fec258204be26af15c61db3c18effee94bc7a8a1783620397780b0e3501e660b4e8ff48d8463e4089067edfcbf3bf9b60
+  data.tar.gz: dc179fe40cb063c4321a1c7a1aff5abb7b441d5fd87ced19908f9875c1f5b26bf2e17555b44658f603b32627577fe99feb8f34d061ed7e53eaba3c28cecd8bbb

data/CHANGELOG.md

@@ -5,6 +5,46 @@ 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)

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

@@ -87,34 +87,22 @@ module RubyPi
         # call but keep the matching tool_result, the API rejects the
         # request with "tool_result without preceding tool_use".
         #
-        # The boundary between droppable and preserved can split a tool
-        # exchange in two ways:
-        #   (a) preserved starts with one or more :tool messages whose
-        #       matching assistant turn is in droppable. Strip those
-        #       orphan tool messages from the head of preserved (move
-        #       them into droppable so they are summarized, not sent).
-        #   (b) the last droppable message is an :assistant with tool_calls,
-        #       but its matching :tool result(s) are in preserved. Pull
-        #       that assistant message back into preserved so the pair
-        #       stays intact.
-        #
-        # We apply (a) first: it's the common case (preserve_last_n=4 cuts
-        # mid-pair, leaving a stranded tool message). Then (b) catches the
-        # mirror case.
+        # 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
 
-        if droppable.last &&
-           droppable.last[:role] == :assistant &&
-           droppable.last[:tool_calls].is_a?(Array) &&
-           !droppable.last[:tool_calls].empty? &&
-           preserved.first && preserved.first[:role] == :tool
-          preserved.unshift(droppable.pop)
-        end
-
-        # After the boundary fix-ups, droppable may have become empty.
-        return nil if droppable.empty?
+        # 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)
@@ -122,28 +110,42 @@ module RubyPi
         # 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
@@ -370,12 +372,19 @@ 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 = with_transport_errors do
           conn.post("/v1/messages") do |req|
@@ -394,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: ")
 
@@ -436,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: ")
@@ -562,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

@@ -78,14 +78,23 @@ module RubyPi
         rescue RubyPi::AuthenticationError
           # Authentication errors are not retryable — raise immediately
           raise
-        rescue RubyPi::RateLimitError, RubyPi::ApiError, RubyPi::TimeoutError, RubyPi::ProviderError => e
+        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.
       #

data/lib/ruby_pi/llm/fallback.rb

@@ -16,11 +16,14 @@ module RubyPi
     # Authentication errors are NOT retried with the fallback since they
     # indicate a configuration problem rather than a transient failure.
     #
-    # Issue #23: When streaming, the Fallback now buffers deltas from the
-    # primary provider. If the primary fails mid-stream, the buffered deltas
-    # are discarded and the fallback provider streams fresh from the start.
-    # This prevents the consumer from seeing partial output from the primary
-    # concatenated with the complete output from the fallback.
+    # Issue #23 + Issue #12: When streaming, events flow from the primary
+    # provider directly to the consumer in real time (no buffering), preserving
+    # the streaming UX on the happy path. If the primary fails mid-stream, a
+    # :fallback_start StreamEvent is emitted before the fallback takes over, so
+    # the consumer can discard any partial output already rendered from the
+    # failed primary. (The agent loop translates :fallback_start into a
+    # :provider_fallback event; raw Fallback consumers should handle
+    # :fallback_start themselves.)
     #
     # @example Setting up a fallback chain
     #   primary  = RubyPi::LLM.model(:gemini, "gemini-2.0-flash")
@@ -146,6 +149,19 @@ module RubyPi
       # @yield [event] the consumer's streaming block
       # @return [RubyPi::LLM::Response]
       def perform_complete_with_streaming_fallback(messages:, tools:, &block)
+        # Count the characters of text already delivered to the consumer from
+        # the primary. If the primary fails mid-stream AFTER yielding text,
+        # the fallback streams a complete fresh response — a consumer that
+        # merely appends deltas would render the primary's partial text
+        # followed by the full fallback text. The :fallback_start payload
+        # carries partial_output/partial_chars so consumers can deterministically
+        # truncate what they already rendered.
+        partial_chars = 0
+        counting_block = proc do |event|
+          partial_chars += event.data.to_s.length if event.text_delta?
+          block.call(event)
+        end
+
         begin
           # Stream primary events directly to the consumer for real-time UX.
           # No buffering — tokens appear immediately as they arrive.
@@ -153,7 +169,7 @@ module RubyPi
             messages: messages,
             tools: tools,
             stream: true,
-            &block
+            &counting_block
           )
 
           response
@@ -164,12 +180,17 @@ module RubyPi
           log_fallback(e)
 
           # Signal the consumer that the primary failed mid-stream and a
-          # fallback provider is taking over. Consumers should use this event
-          # to clear any partial output from the failed primary.
+          # fallback provider is taking over. Consumers MUST use this event
+          # to clear any partial output from the failed primary:
+          #   partial_output — true when the primary yielded any text deltas
+          #   partial_chars  — how many characters were yielded (truncate by
+          #                    this amount if appending to a shared buffer)
           block.call(StreamEvent.new(type: :fallback_start, data: {
             failed_provider: @primary.provider_name,
             error: e.message,
-            fallback_provider: @fallback.provider_name
+            fallback_provider: @fallback.provider_name,
+            partial_output: partial_chars.positive?,
+            partial_chars: partial_chars
           }))
 
           # Stream directly from the fallback to the consumer's block.

data/lib/ruby_pi/llm/gemini.rb

@@ -6,6 +6,7 @@
 # the Gemini REST API for both synchronous and streaming completions, including
 # tool/function calling support.
 
+require "json"
 require "securerandom"
 
 module RubyPi
@@ -305,9 +306,14 @@ module RubyPi
         # which may split SSE events mid-line. We accumulate a line buffer and
         # process complete lines incrementally so that deltas reach the caller
         # as soon as each SSE event is fully received.
-        sse_buffer = +""
+        # BINARY buffer: 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 holding non-ASCII text raises
+        # Encoding::CompatibilityError. Complete lines are re-encoded to
+        # UTF-8 (and scrubbed) before parsing.
+        sse_buffer = (+"").force_encoding(Encoding::BINARY)
         response_status = nil
-        error_body = +""
+        error_body = (+"").force_encoding(Encoding::BINARY)
 
         response = with_transport_errors do
           conn.post(url) do |req|
@@ -324,14 +330,17 @@ module RubyPi
             # If the HTTP status indicates an error, accumulate the body for
             # the error handler instead of parsing it as SSE events.
             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: ")
 
@@ -375,8 +384,11 @@ module RubyPi
               # Parse the actual finish reason from the streaming response
               # instead of hardcoding "stop". Gemini sends finishReason in
               # the candidate object (e.g., "STOP", "MAX_TOKENS", "SAFETY").
+              # Coerce via to_s before downcase so a non-String payload can
+              # never raise NoMethodError mid-stream (mirrors the &.to_s in
+              # the non-streaming parse path).
               if candidate["finishReason"]
-                finish_reason = candidate["finishReason"].downcase
+                finish_reason = candidate["finishReason"].to_s.downcase
               end
 
               # Capture usage metadata if present
@@ -397,7 +409,7 @@ module RubyPi
         # callback. Pass the accumulated error_body so ApiError carries the
         # full server message instead of an empty body.
         unless response.success?
-          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(response, override_body: error_body_str)
         end
 
@@ -450,8 +462,10 @@ module RubyPi
           }
         end
 
-        # Map Gemini finish reason to normalized string
-        finish_reason = candidate["finishReason"]&.downcase
+        # Map Gemini finish reason to normalized string. to_s guards against
+        # a non-String payload (mirrors the streaming path); &. keeps a
+        # missing finishReason as nil.
+        finish_reason = candidate["finishReason"]&.to_s&.downcase
 
         Response.new(
           content: content,

data/lib/ruby_pi/llm/openai.rb

@@ -6,6 +6,8 @@
 # OpenAI Chat Completions API for both synchronous and streaming completions,
 # including function/tool calling support.
 
+require "json"
+
 module RubyPi
   module LLM
     # OpenAI provider implementation. Communicates with the OpenAI Chat
@@ -318,9 +320,14 @@ module RubyPi
         # which may split SSE events mid-line. We accumulate a line buffer and
         # process complete lines incrementally so that deltas reach the caller
         # as soon as each SSE event is fully received.
-        sse_buffer = +""
+        # BINARY buffer: 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 holding non-ASCII text raises
+        # Encoding::CompatibilityError. Complete lines are re-encoded to
+        # UTF-8 (and scrubbed) before parsing.
+        sse_buffer = (+"").force_encoding(Encoding::BINARY)
         response_status = nil
-        error_body = +""
+        error_body = (+"").force_encoding(Encoding::BINARY)
 
         response = with_transport_errors do
           conn.post("/v1/chat/completions") do |req|
@@ -337,14 +344,17 @@ module RubyPi
             # If the HTTP status indicates an error, accumulate the body for
             # the error handler instead of parsing it as SSE events.
             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: ")
 
@@ -419,7 +429,7 @@ module RubyPi
         # callback. Pass the accumulated error_body so ApiError carries the
         # full server message instead of an empty body.
         unless response.success?
-          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(response, override_body: error_body_str)
         end
 

data/lib/ruby_pi/llm/tool_call.rb

@@ -6,6 +6,8 @@
 # decides to invoke a tool, it returns one or more ToolCall objects describing
 # which function to call and with what arguments.
 
+require "json"
+
 module RubyPi
   module LLM
     # A tool call extracted from an LLM response. Contains the unique call ID,

data/lib/ruby_pi/tools/definition.rb

@@ -37,16 +37,32 @@ module RubyPi
       # @return [Hash] A JSON Schema hash describing the tool's parameters.
       attr_reader :parameters
 
+      # Tool names must satisfy the strictest provider constraint (Anthropic's
+      # ^[a-zA-Z0-9_-]{1,64}$). Without this guard, a name like "send.email"
+      # registers fine and then 400s on every API request with an opaque
+      # server-side validation error that doesn't point back to the tool.
+      NAME_FORMAT = /\A[a-zA-Z0-9_-]{1,64}\z/
+
       # Creates a new tool definition.
       #
-      # @param name [String, Symbol] Unique identifier for the tool.
+      # @param name [String, Symbol] Unique identifier for the tool. Must match
+      #   NAME_FORMAT (letters, digits, underscore, hyphen; max 64 chars).
       # @param description [String] What the tool does (shown to the LLM).
       # @param category [Symbol, nil] Optional grouping category.
       # @param parameters [Hash] JSON Schema hash for the tool's input parameters.
-      # @yield [Hash] Block that implements the tool logic. Receives a hash of arguments.
-      # @raise [ArgumentError] If name or description is missing, or no block given.
+      # @yield [Hash] Block that implements the tool logic. Receives a hash of
+      #   symbol-keyed arguments, or keyword arguments if the block declares
+      #   keyword parameters (see #call).
+      # @raise [ArgumentError] If name is missing or violates NAME_FORMAT,
+      #   description is missing, or no block given.
       def initialize(name:, description:, category: nil, parameters: {}, &block)
         raise ArgumentError, "Tool name is required" if name.nil? || name.to_s.strip.empty?
+        unless name.to_s.match?(NAME_FORMAT)
+          raise ArgumentError,
+                "Tool name #{name.to_s.inspect} is invalid — provider APIs require " \
+                "names matching #{NAME_FORMAT.inspect} (letters, digits, underscore, " \
+                "hyphen; 1-64 characters)"
+        end
         raise ArgumentError, "Tool description is required" if description.nil? || description.strip.empty?
         raise ArgumentError, "Tool implementation block is required" unless block_given?
 
@@ -55,14 +71,33 @@ module RubyPi
         @category = category&.to_sym
         @parameters = parameters
         @implementation = block
+        # On Ruby 3.x a positional Hash is never auto-splatted to keywords, so
+        # a block written `{ |content:, platform:| ... }` — the natural style
+        # given named schema parameters — would fail every call with
+        # "missing keyword". Detect keyword parameters once here and splat in
+        # #call accordingly.
+        @expects_keywords = block.parameters.any? { |type, _| %i[key keyreq keyrest].include?(type) }
       end
 
       # Invokes the tool with the given arguments.
       #
+      # Blocks may be written either style:
+      #   { |args| args[:content] }            # single positional Hash
+      #   { |content:, platform: "x"| ... }    # keyword parameters
+      #
+      # When the block declares keyword parameters, the arguments hash is
+      # splatted to keywords. Note that a keyword-style block without **rest
+      # raises ArgumentError on unexpected keys — strict by design, since the
+      # keys come from the LLM.
+      #
       # @param args [Hash] The arguments to pass to the tool implementation.
       # @return [Object] Whatever the implementation block returns.
       def call(args = {})
-        @implementation.call(args)
+        if @expects_keywords
+          @implementation.call(**args)
+        else
+          @implementation.call(args)
+        end
       end
 
       # Converts this tool definition to Google Gemini function declaration format.

data/lib/ruby_pi/tools/executor.rb

@@ -115,7 +115,12 @@ module RubyPi
         end
 
         # Collect results, respecting the configured timeout for each future.
-        futures.map do |future|
+        # Zip each future with its originating call so failure Results carry
+        # the real tool name — with several tools timing out in parallel,
+        # "unknown" Results are indistinguishable in logs and extension events.
+        calls.zip(futures).map do |call, future|
+          tool_name = (call[:name] || call["name"]).to_s
+
           # Issue #10: Wait for the future to complete, then check its state
           # explicitly. Future#value returns nil both on timeout AND when the
           # block legitimately returned nil, so we cannot use || to distinguish.
@@ -128,13 +133,16 @@ module RubyPi
             else
               # Future was rejected (raised an exception within the block).
               # This shouldn't normally happen since execute_single rescues
-              # internally, but handle it defensively.
+              # internally, but handle it defensively. The actual run time is
+              # unknown here (the future failed at some point before the wait
+              # elapsed), so report 0.0 rather than a misleading full-timeout
+              # duration for what may have been an instant failure.
               error = future.reason
               Result.new(
-                name: "unknown",
+                name: tool_name,
                 success: false,
                 error: "#{error.class}: #{error.message}",
-                duration_ms: @timeout * 1000.0
+                duration_ms: 0.0
               )
             end
           else
@@ -147,9 +155,9 @@ module RubyPi
             future.cancel if future.respond_to?(:cancel)
 
             Result.new(
-              name: "unknown",
+              name: tool_name,
               success: false,
-              error: "Tool execution timed out after #{@timeout}s",
+              error: "Tool '#{tool_name}' timed out after #{@timeout}s",
               duration_ms: @timeout * 1000.0
             )
           end

data/lib/ruby_pi/tools/schema.rb

@@ -13,6 +13,16 @@
 # flag consumed by `.object` to populate the top-level "required" array.
 # It is stripped from the property's own schema hash before inclusion.
 #
+# IMPORTANT: Schemas are LLM-facing hints, NOT runtime input validation.
+# Nothing in the execution pipeline validates the model's arguments against
+# the schema before invoking the tool block: `required`, `enum`, `minimum`,
+# and type declarations constrain what the model is *asked* to produce, but a
+# misbehaving model can still omit required fields, send extra keys, or pass
+# a String where an Integer is declared — no coercion is performed. Tool
+# blocks should treat their arguments as untrusted input and validate or
+# coerce what they depend on. (This is deliberate, per the anti-framework
+# philosophy: validation policy belongs to the tool, not the harness.)
+#
 # Usage:
 #   schema = RubyPi::Schema.object(
 #     name: RubyPi::Schema.string("User's name", required: true),

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.6"
+  VERSION = "0.1.8"
 end

data/lib/ruby_pi.rb

@@ -82,6 +82,13 @@ module RubyPi
     end
   end
 
+  # Eagerly initialize the global configuration at load time. The lazy
+  # `@configuration ||= ...` in .configuration is not synchronized; two
+  # threads hitting it concurrently on first access could each construct a
+  # Configuration, with one silently discarded. Initializing here (requires
+  # run single-threaded) removes the race without adding a mutex to every read.
+  @configuration = Configuration.new
+
   # Namespace for large language model providers and related abstractions.
   module LLM
     class << self

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ruby-pi
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.1.8
 platform: ruby
 authors:
 - RubyPi Contributors
 bindir: bin
 cert_chain: []
-date: 2026-05-01 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -51,6 +51,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -157,7 +171,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.6.9
 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.