smith-agents 0.12.3 → 0.12.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0a97b202bc606c58889517b16ffe906f8775d003b9386d371b63ea08dd725dff
-  data.tar.gz: 5ad614925043a70182362086dd2c03e9d3cc3bd6eea645b8d04b4e2d61b93719
+  metadata.gz: 663a12c4a26041ded1da57a8bd899213cc28d330eae1d42a9dc3e4fdbda4dd87
+  data.tar.gz: c997927bbcea376c0db21a92aacdc21e510ac3c8e664d4ebb1eb0f8282cd2b32
 SHA512:
-  metadata.gz: eb8e78bc96e382495c098bbb2f5e794a8efe674d5c662715d18f6d6b1b2445d2ba69198b6e447849f509f5cc58fc06ed001162f18829c485b3a1456eb843cfe0
-  data.tar.gz: 6f6112a5048ab240fe3658b6107d5e2f950945045f4518e2f07f16a72e40cb1b91a2b0ea31278df09c4fde3329132bfd5cf7dceef76040f00d5d007e01ceebea
+  metadata.gz: 27cc5f8437f8325afde26cd1816f8ca007a1c0f43b0ea02cc14cdcd49c17504cc5b2a22934c8b26ddcac132f5d2dc28f40e9e6fcde8976e01b3d4438523235b2
+  data.tar.gz: d621799d104e1b3b1ba97f14974afb6fa01c99cd179f8817471a55148d0587c9b2e333d47a0ab016855e48b8ab7739badb5db72c22e6730294f23da4947bc96d

data/CHANGELOG.md

@@ -4,6 +4,50 @@ All notable changes to Smith are documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Smith is pre-1.0 and under active development; expect occasional contract tightening between minor versions until 1.0.
 
+## [0.12.5] - 2026-10-13
+
+### Fixed
+
+- A streamed step's requests are each sent once: its chat takes a copy of
+  the agent's config (its context, or RubyLLM's) with RubyLLM's HTTP retries
+  (`max_retries`) off, its model resolved again as RubyLLM resolves a chat
+  built with a context (the same id and provider, and the agent's own
+  `assume_model_exists`, so a model RubyLLM lists keeps its output limit and
+  thinking options). Retrying a stream read the next response's error into
+  the buffer the first had filled, so the provider's words were lost: a
+  refusal for want of credit reached Smith as a bare "Invalid request"
+  (`RubyLLM::BadRequestError`) and was never classified as
+  `RubyLLM::PaymentRequiredError`, and a spend-cap 429 as a plain rate limit.
+  A stream that failed part way was sent again, its text streamed twice.
+  Every provider failure of a streamed request, a transient one at connect
+  time included, now goes straight to the step's fallbacks and retries, so
+  a streamed step that should ride out an outage declares them. Calls that
+  do not stream, and requests OpenAI's Responses route sends whole, keep
+  RubyLLM's retries. The global config and the agent's are never changed.
+
+## [0.12.4] - 2026-10-13
+
+### Changed
+
+- A provider's refusal for want of credit or past a spending limit is
+  `RubyLLM::PaymentRequiredError` whatever status it came with
+  (`Smith::BillingRefusals`), with the error RubyLLM raised as its cause. A
+  refusal is told by what the provider says it is: Anthropic's `billing_error`,
+  its tier's monthly spend cap (a 429 whose `error_code` is
+  `enforced_spend_limit_reached`), its 400s for spent credit ("Your credit
+  balance is too low") and for a spend limit the account set ("You have
+  reached your specified API usage limits"), and OpenAI's
+  `insufficient_quota`. A streamed request's refusal, which RubyLLM raises as
+  a `RubyLLM::ServerError`, is one too, and so is one met by
+  `Smith::Providers::Anthropic::Batches#submit`. It is the provider account's
+  failure, so another provider in the fallback chain is tried, and a host can
+  name `RubyLLM::PaymentRequiredError` in `interrupting_errors` to have a step
+  wait for credit instead of failing. Any other error is unchanged: a rate
+  limit that mentions a quota (Gemini's) stays a rate limit.
+- A model candidate that met an interrupting error outlasts how a later
+  fallback fails: the step is cut short, as it would have been with no
+  fallback, instead of failing on the fallback's error.
+
 ## [0.12.3] - 2026-10-12
 
 ### Changed

data/README.md

@@ -30,7 +30,7 @@ What you get:
 
 ```ruby
 # Gemfile
-gem "smith-agents", "0.12.3", require: "smith"
+gem "smith-agents", "0.12.5", require: "smith"
 ```
 
 In a Rails app:

data/docs/AGENTS.md

@@ -155,7 +155,17 @@ reason and message id, with `mode: :stream`), and a replayed step streams again
 (unless a response memo kept its reply: then its sink gets the text at once).
 Graph inspection shows the stream, and runtime readiness reports a missing sink
 (`:stream_sink_missing`) and an agent whose calls go to the Responses API
-(`:stream_whole_replies`).
+(`:stream_whole_replies`). A streamed step's requests are each sent once:
+its chat takes a copy of the agent's config with RubyLLM's HTTP retries
+(`max_retries`) off and its model resolved again as RubyLLM resolves a chat
+built with a context (a model RubyLLM lists keeps its limits), since a
+retried stream loses the first response's error body (a refusal for want of
+credit would reach Smith as a bare "Invalid request") or streams its text
+again. Every provider failure of a streamed request, a transient one at
+connect time included, takes the step's fallbacks and retries directly, so
+declare them (`fallback_models`, `retry_on Smith::AgentError`) on a streamed
+step that should ride out an outage. A request OpenAI's Responses route sends
+whole keeps the retries.
 
 ## Batch mode
 

data/docs/ERRORS_AND_RETRIES.md

@@ -99,6 +99,24 @@ next advanced; a strict run is found under way on restore
 (`Smith::StepInProgressOnRestore`), as after a crash. The instance that
 raised is not advanced again: restore the run.
 
+A provider's refusal for want of credit or past a spending limit is
+`RubyLLM::PaymentRequiredError` whatever status it came with, its cause the
+error RubyLLM raised. Smith tells one by what the provider says it is:
+Anthropic's `billing_error` (402), its tier's monthly spend cap (a 429 whose
+`error.details.error_code` is `enforced_spend_limit_reached`), its 400s for
+spent credit ("Your credit balance is too low") and for a spend limit the
+account set ("You have reached your specified API usage limits"), and
+OpenAI's `insufficient_quota` (429). RubyLLM raises a streamed request's
+refusal as a `RubyLLM::ServerError`; it is one all the same. It is the
+provider account's, so another provider in the fallback chain is tried;
+naming `RubyLLM::PaymentRequiredError` makes a step that meets it wait for
+credit instead of failing, even when a fallback then fails some other way.
+`Smith::Providers::Anthropic::Batches#submit` raises it too. Any other error
+stays as it is: a rate limit whose message mentions a quota (Gemini's) is a
+rate limit. RubyLLM's own HTTP retries (`max_retries`) may repeat a 429 of a
+call that does not stream before Smith sees it (a refused request is not
+charged); a streamed call is sent once, so its refusal reaches Smith whole.
+
 Name only errors that mean your own systems failed. A provider's own failure
 (`RubyLLM::Error`, or its HTTP client's `Faraday::Error`) is the provider's
 whatever it was raised from, so naming a low-level class such as

data/lib/smith/agent/attempt_chat.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Smith
+  class Agent
+    module AttemptChat
+      private
+
+      # An attempt's chat. A streamed step's sends each request it streams
+      # over the wire once: RubyLLM's HTTP retries would send it again on an
+      # error, its error body already read into the first request's buffer
+      # (so a refusal for want of credit reaches Smith as a bare "Invalid
+      # request", never classified) or its text already streamed (the
+      # retry's text would join it). Smith's fallbacks and the step's
+      # retries take their place. Its chat takes a copy of the agent's config
+      # (its context, or RubyLLM's) without the retries, and resolves its
+      # model again as RubyLLM builds a chat with a context (the same id and
+      # provider, and the agent's own assume_model_exists, so a model RubyLLM
+      # knows keeps its limits), before any hold attaches to its provider. A
+      # request OpenAI's Responses route sends answers whole, unstreamed,
+      # and keeps the retries.
+      def attempt_chat(agent_class, model_reference)
+        chat = agent_class.chat(**model_reference.chat_options, **bridge_workflow_inputs(agent_class))
+        return chat unless @step_stream && streams_over_the_wire?(chat)
+
+        sent_once(chat, agent_class)
+      end
+
+      def sent_once(chat, agent_class)
+        model = chat.model
+        config = (agent_class.context&.config || RubyLLM.config).dup
+        config.max_retries = 0
+        chat.with_context(RubyLLM::Context.new(config))
+        chat.with_model(model.id, provider: model.provider,
+                                  assume_exists: agent_class.chat_kwargs.fetch(:assume_model_exists, false))
+      end
+
+      def streams_over_the_wire?(chat)
+        return false unless chat.respond_to?(:with_context) && chat.respond_to?(:with_model)
+
+        (chat.params[:openai_api_mode] || chat.params["openai_api_mode"]).to_s != "responses"
+      end
+    end
+  end
+end

data/lib/smith/agent/provider_call_timing.rb

@@ -123,7 +123,9 @@ module Smith
       # have their join target; the error then propagates unchanged. A
       # provider failure's own reported usage is accounted beside the
       # completed prefix, so its trace totals both.
+      # A billing refusal is recorded as the provider account's (BillingRefusals).
       def failed_provider_attempt(error, observed_reference, timer, facts, prefix_usages)
+        error = BillingRefusals.classified(error)
         aborted = !provider_failure?(error)
         usages = aborted ? prefix_usages : [*prefix_usages, ProviderUsage.from_message(error)].compact
         attempt = ProviderAttempt.failure(

data/lib/smith/agent/provider_completion.rb

@@ -34,18 +34,16 @@ module Smith
 
       def attempt_candidates(agent_class, prepared_input, chain, shape)
         candidates = ProviderCandidateSequence.new(chain)
+        interrupted = nil
         candidates.each do |model_reference, index|
           check_deadline! if index.positive?
           withdraw_streamed(index.positive? ? :fallback : :retry)
           attempt = attempt_model(agent_class, prepared_input, model_reference, shape:, attempt_index: index)
           return attempt if attempt.success?
 
+          interrupted ||= attempt if Interruptions.find(attempt.error)
           candidates.suppress(account_failed_provider(attempt, model_reference))
-          handle_provider_failure!(
-            attempt.error, attempt.model_reference, agent_class,
-            fallback_available: candidates.fallback_available?,
-            attempt_id: attempt.attempt_id
-          )
+          fail_over!(attempt, agent_class, candidates, interrupted)
         end
 
         # Fail closed: an empty candidate chain (agent without a model)
@@ -55,6 +53,22 @@ module Smith
               "no executable model candidate for #{agent_class}; declare a model or fallback_models"
       end
 
+      # Returns when another candidate is left to try. A candidate that met
+      # an interrupting error (an account out of credit) outlasts how a later
+      # one fails: the step was cut short, not failed, and is taken again
+      # from its first candidate once the host can do its part.
+      def fail_over!(attempt, agent_class, candidates, interrupted)
+        handle_provider_failure!(
+          attempt.error, attempt.model_reference, agent_class,
+          fallback_available: candidates.fallback_available?,
+          attempt_id: attempt.attempt_id
+        )
+      rescue StandardError => e
+        raise if interrupted.nil? || Interruptions.find(e)
+
+        raise terminal_provider_error(interrupted.error, interrupted.model_reference), cause: interrupted.error
+      end
+
       # Suppression keys on the provider that actually rejected the
       # account; when the chat is unobservable the attempted reference's
       # declared provider is the best available attribution, so a dead
@@ -133,7 +147,7 @@ module Smith
       # rubocop:enable Metrics/AbcSize
 
       def prepared_attempt_chat(agent_class, prepared_input, model_reference, shape)
-        chat = agent_class.chat(**model_reference.chat_options, **bridge_workflow_inputs(agent_class))
+        chat = attempt_chat(agent_class, model_reference)
         add_prepared_input(chat, prepared_input, observed_model_reference(chat, fallback: model_reference).provider)
         continue_paused_loop(chat)
         shaped_chat(chat, model_reference, shape)

data/lib/smith/agent/provider_streaming.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "attempt_chat"
+
 module Smith
   class Agent
     # The provider calls of a streamed step (Smith::Streaming): before a
@@ -8,6 +10,8 @@ module Smith
     # reason is read from the stream (Providers::StreamFacts), as a
     # streamed reply keeps no raw body.
     module ProviderStreaming
+      include AttemptChat
+
       # Room for what a pause adds besides its messages (its retry, the
       # attempt's usage).
       PAUSE_MARGIN = 4096

data/lib/smith/billing_refusals.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "json"
+require "ruby_llm"
+
+module Smith
+  # A provider's refusal for want of credit or past a spending limit, whatever
+  # status it came with. Smith takes each as RubyLLM::PaymentRequiredError,
+  # the error RubyLLM raises for a 402 (its cause the error RubyLLM raised),
+  # so the refusal is the provider account's (another provider in the
+  # fallback chain is tried) and a host can name that one class in
+  # interrupting_errors to have a step wait for credit instead of failing.
+  #
+  # A refusal is told by what the provider says it is, never by its status
+  # alone: Anthropic's billing_error (402), its tier's monthly spend cap (429,
+  # error_code enforced_spend_limit_reached), its spent credit and a spend
+  # limit the account set (400s known only by how their message begins), and
+  # OpenAI's insufficient_quota (429). A streamed request's refusal arrives
+  # as a RubyLLM::ServerError, since RubyLLM takes every streamed error as a
+  # 500. Any other error stays as it is: a rate limit that mentions a quota
+  # (Gemini's) is a rate limit.
+  module BillingRefusals
+    CLASSES = [RubyLLM::BadRequestError, RubyLLM::RateLimitError, RubyLLM::ServerError].freeze
+    TYPES = %w[billing_error insufficient_quota].freeze
+    CODES = %w[enforced_spend_limit_reached].freeze
+    MESSAGES = [
+      /\AYour credit balance is too low/i,
+      /\AYou have reached your specified (?:workspace )?API usage limits/i
+    ].freeze
+    private_constant :CLASSES, :TYPES, :CODES, :MESSAGES
+
+    module_function
+
+    # The error as Smith takes it: a billing refusal as a
+    # RubyLLM::PaymentRequiredError, anything else unchanged.
+    def classified(error)
+      return error unless refusal?(error)
+
+      begin
+        raise RubyLLM::PaymentRequiredError.new(error.response, error.message), cause: error
+      rescue RubyLLM::PaymentRequiredError => e
+        e
+      end
+    end
+
+    def refusal?(error)
+      return false unless CLASSES.any? { error.is_a?(_1) }
+
+      said = provider_error(error)
+      details = said["details"].is_a?(Hash) ? said["details"] : {}
+
+      TYPES.include?(said["type"]) ||
+        CODES.include?(details["error_code"]) ||
+        MESSAGES.any? { error.message.to_s.match?(_1) }
+    end
+
+    # The provider's own error object in the response body, or {} when the
+    # body carries none.
+    def provider_error(error)
+      body = error.response.respond_to?(:body) ? error.response.body : nil
+      body = JSON.parse(body) if body.is_a?(String)
+      said = body["error"] if body.is_a?(Hash)
+      said.is_a?(Hash) ? said : {}
+    rescue JSON::ParserError
+      {}
+    end
+  end
+end

data/lib/smith/providers/anthropic/batches.rb

@@ -34,13 +34,13 @@ module Smith
           @connection = RubyLLM::Providers::Anthropic.new(config).connection
         end
 
-        # Submits the requests; returns the batch id.
+        # Submits the requests; returns the batch id. A refusal for want of
+        # credit raises RubyLLM::PaymentRequiredError (BillingRefusals).
         def submit(requests)
           entries = Array(requests).map { |entry| entry.transform_keys(&:to_sym) }
           body = { requests: entries.map { |entry| { custom_id: entry.fetch(:custom_id), params: params(entry) } } }
           check_batch!(entries, body)
-          headers = shared_headers(entries)
-          @connection.post(PATH, body) { |request| add_headers(request.headers, headers) }.body.fetch("id")
+          create(body, shared_headers(entries))
         end
 
         # The batch's processing status ("in_progress", "canceling" or
@@ -67,6 +67,12 @@ module Smith
 
         private
 
+        def create(body, headers)
+          @connection.post(PATH, body) { |request| add_headers(request.headers, headers) }.body.fetch("id")
+        rescue RubyLLM::Error => e
+          raise BillingRefusals.classified(e)
+        end
+
         def params(entry)
           request = entry.fetch(:request).transform_keys(&:to_s)
           raise ArgumentError, "a request for #{request["provider"]} cannot go in an Anthropic batch" unless

data/lib/smith/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Smith
-  VERSION = "0.12.3"
+  VERSION = "0.12.5"
   EXECUTION_SEMANTICS_VERSION = "7"
 end

data/lib/smith.rb

@@ -212,6 +212,7 @@ require_relative "smith/tool_failure_notification_failed"
 require_relative "smith/persistence_payload_conflict"
 require_relative "smith/exponential_backoff"
 require_relative "smith/interruptions"
+require_relative "smith/billing_refusals"
 
 # Event system (depends on Types)
 require_relative "smith/event"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: smith-agents
 version: !ruby/object:Gem::Version
-  version: 0.12.3
+  version: 0.12.5
 platform: ruby
 authors:
 - Samuel Ralak
@@ -161,6 +161,7 @@ files:
 - lib/generators/smith/install/templates/workflow_state.rb.tt
 - lib/smith.rb
 - lib/smith/agent.rb
+- lib/smith/agent/attempt_chat.rb
 - lib/smith/agent/chat_construction.rb
 - lib/smith/agent/completion.rb
 - lib/smith/agent/completion_usage_recording.rb
@@ -203,6 +204,7 @@ files:
 - lib/smith/attribution.rb
 - lib/smith/batch.rb
 - lib/smith/batch/message_shape.rb
+- lib/smith/billing_refusals.rb
 - lib/smith/budget.rb
 - lib/smith/budget/amount.rb
 - lib/smith/budget/amount_contract.rb