ruby-pi 0.1.6 → 0.1.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c78d37122ed67d80e61cf51b182dcd79a20a7efa77b503c8b0340963ad60b728
-  data.tar.gz: e3b147cb2b01fe28ac15c2a65d6177156992be7560601886296b16941784ee08
+  metadata.gz: fbecc54fc18679e9f16a0a09c27944df82b0a98fff7ead1dee99ba1a659aad02
+  data.tar.gz: 298e084a7df3b6689e628477ddbae866057a81ac472838623ce6eefccd01a431
 SHA512:
-  metadata.gz: cbc0c9abddf98885bf1a22352a9cd09475c324f9aff4bcdff66ce3a6a87e06eb677ab045c966038666744cf9819d5114714c66ba5b7c676de5958d5d964a6242
-  data.tar.gz: 3f9c28b1a30d0e3ad0f1badd391c95065adea822927c1d334dc5fc5c9867e658b43e339e9307dd3eba8dd5a534043c9fae3ea8d0384bfae8eb35a1a09356f035
+  metadata.gz: cbb1ae3d3469f987b4ab7652cce23626e6e1a233c08636ab24dcda3c6151d0bc728d88658e575919840e393c84ce4efabbd5fa78f302c036993a0d1b3e79b354
+  data.tar.gz: 1132a860f026efc123813042eea18617242d036ec03ca425277cd2f9eba88a49f1cc2f461c6feee58fa021eeed8fbe42affee5c6f865ff6fad563809ede29479

data/CHANGELOG.md

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

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

data/lib/ruby_pi/agent/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/events.rb

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

data/lib/ruby_pi/agent/loop.rb

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

data/lib/ruby_pi/agent/result.rb

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

data/lib/ruby_pi/agent/state.rb

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

data/lib/ruby_pi/configuration.rb

@@ -37,19 +37,56 @@ 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)
+      unless value.is_a?(Integer) && value >= 0
+        raise ArgumentError, "max_retries must be a non-negative integer, got #{value.inspect}"
+      end
+
+      @max_retries = value
+    end
+
+    # @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 +115,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.is_a?(Complex) && value.finite? && value >= 0
+
+      raise ArgumentError, "#{name} must be a finite non-negative number, got #{value.inspect}"
+    end
+
     # Sets all configuration ivars to their default values. Called by both
     # initialize and reset! to ensure consistent defaults without the
     # anti-pattern of calling initialize from reset!.