smith-agents 0.12.1 → 0.12.2

data/lib/smith/providers/stream_facts.rb

@@ -32,13 +32,15 @@ module Smith
       MARK = :@smith_stream_facts_observer
       private_constant :HELD, :MARK
 
-      # The streams of one call: its provider (nil reads any) and the facts
-      # of each of its requests.
+      # The streams of one call: its provider (nil reads any), the facts of
+      # each of its requests, and how many of its replies came kept, before
+      # them, from a response memo (no request of its own answered those).
       class Collection
-        attr_reader :rounds
+        attr_reader :rounds, :kept
 
-        def initialize(provider)
+        def initialize(provider, kept = 0)
           @provider = provider
+          @kept = kept
           @rounds = []
         end
 
@@ -64,20 +66,36 @@ module Smith
 
       # Runs the block, given the collection, collecting the facts of the
       # streams `provider` reads; returns them, one bounded Hash per round.
-      def collect(provider)
+      def collect(provider, kept: 0)
         outer = Fiber[HELD]
-        collection = Fiber[HELD] = Collection.new(provider)
+        collection = Fiber[HELD] = Collection.new(provider, kept)
         yield collection
         collection.facts
       ensure
         Fiber[HELD] = outer
       end
 
-      # The facts of each response of a streamed call, in order: each
-      # round's over its raw body's, the last settled. Rounds and responses
-      # pair up in order; a round past the last response (a request that
-      # failed) has none.
-      def per_message(messages, rounds, output_limit)
+      # The facts of the request `provider` last streamed in the collecting
+      # call, bounded; empty when it streamed none.
+      def last_round(provider)
+        collection = Fiber[HELD]
+        return {} unless collection&.owns?(provider) && !collection.rounds.empty?
+
+        collection.facts.last
+      end
+
+      # The facts of each response of a streamed call, in order: the first
+      # `kept` (a response memo's) their own; each live one its round's over
+      # its raw body's, the last settled. Rounds and live responses pair up
+      # in order; a round past the last response (a request that failed) has
+      # none.
+      def per_message(messages, rounds, output_limit, kept: 0)
+        live = messages.drop(kept)
+        own = messages.first(kept).map { ResponseFacts.from_message(_1) }
+        live.empty? ? own : [*own, *live_facts(live, rounds, output_limit)]
+      end
+
+      def live_facts(messages, rounds, output_limit)
         missing = messages.length - rounds.length
         aligned = missing.positive? ? [*Array.new(missing, {}), *rounds] : rounds.first(messages.length)
         facts = messages.zip(aligned).map { |message, round| ResponseFacts.from_message(message).merge(round) }

data/lib/smith/response_memo.rb

@@ -14,29 +14,127 @@ module Smith
   # position, the key generation), the attempts it runs under (the step's,
   # and each enclosing run's for a nested workflow), its attempt index (its
   # model in the fallback chain, or a follow-up's place), its place among
-  # the attempt's calls, and a digest of its request (model, messages,
-  # tools, schema, params). A replay reaches the same key; a call whose
-  # request changed since (a deployed prompt, another model, a date in the
-  # prompt) misses and is sent, as a miss always may be.
+  # the attempt's calls, and a digest of its request (model, messages, tools
+  # with their descriptions and parameters, schema, params). A replay
+  # reaches the same key; a call whose request changed since (a deployed
+  # prompt or tool, another model, a date in the prompt) misses and is
+  # sent, as a miss always may be.
   #
-  # Its record, `{"version" => 1, "messages" => [...], "complete" => bool}`,
-  # holds the messages the call added (Budget::Continuation, with each
-  # response's usage and facts), stored after each round's tool results and
-  # when the call ends; a complete one ends with the model's reply. Replayed,
-  # a complete call sends nothing; an unfinished one continues from its
-  # tools' results. Either way the step counts its tools as run (a retry or
-  # fallback never runs them again). A call whose messages cannot be kept
-  # (an attachment, or too many bytes) is not stored, and is logged. A record
-  # Smith does not keep is ignored, and an error from `fetch` or `store` is
-  # logged by class: a memo never fails a step. Keeping records and dropping
-  # them is the host's.
+  # Its record, `{"version" => 1 | 2, "messages" => [...], "complete" =>
+  # bool}`, holds the messages the call added (Budget::Continuation, with
+  # each response's usage and facts). It is stored when a reply calling the
+  # tools its request offered comes (before they run; version 2, the only
+  # shape a Smith before 0.12.2 cannot read), before each later request (the
+  # tools' results included), and when the call ends in the model's reply (a
+  # call a tool halted keeps only its progress). Replayed, a complete call
+  # sends nothing; an unfinished one goes on from where it was kept: a reply
+  # whose tools had not run answers the call's first request without
+  # sending it, and its tools run again, under the same keys; kept tool
+  # results count as tools the step ran (charged to its tool-call
+  # allowances, and never run again by a retry or fallback). A call whose
+  # messages cannot be kept (an attachment, or too many bytes) is not
+  # stored, and is logged. A record Smith does not keep (its shape, or tool
+  # results that do not answer its replies' calls) is ignored, and an error
+  # from `fetch` or `store` is logged by class: a memo never fails a step.
+  # Keeping records and dropping them is the host's.
   module ResponseMemo
-    VERSION = 1
+    VERSION = 2
     PROGRESS = :smith_response_memo
     INHERITED = :smith_inherited_memo_attempts
     private_constant :PROGRESS, :INHERITED
 
-    Recorder = Struct.new(:provider, :memo, :key, :start, :rounds, :busy)
+    # A provider call being recorded (`recording`): its messages from
+    # `start` are stored as its progress when a reply calling the tools its
+    # request offered comes (with the facts its stream gave), and before
+    # each later round (the round before's tool results included). A kept
+    # reply whose tools had not run (`pending`) answers its first request,
+    # and nothing is sent.
+    class Recorder
+      def initialize(provider, memo, key, start, pending)
+        @provider = provider
+        @memo = memo
+        @key = key
+        @start = start
+        @pending = pending
+        @rounds = 0
+        @busy = false
+        @facts = {}.compare_by_identity
+      end
+
+      # Whether a request `provider` is about to make is one of the call's
+      # rounds (not one made inside another, as OpenAI's hook inside the
+      # base class's).
+      def records?(provider) = provider.equal?(@provider) && !@busy
+
+      def round(messages, offered, &)
+        @rounds += 1
+        return @pending.tap { @pending = nil } if @pending
+
+        progress(messages.drop(@start)) if @rounds > 1
+        reply = busy(&)
+        return reply unless offered && ResponseMemo.calls_tools?(reply)
+
+        @facts[reply] = Providers::StreamFacts.last_round(@provider)
+        progress([*messages.drop(@start), reply])
+        reply
+      end
+
+      private
+
+      def progress(messages) = ResponseMemo.store(@memo, @key, messages, complete: false, facts: @facts)
+
+      def busy
+        @busy = true
+        yield
+      ensure
+        @busy = false
+      end
+    end
+
+    # The shape of a record Smith keeps, as JSON.
+    module Record
+      READ = [1, VERSION].freeze
+      private_constant :READ
+
+      module_function
+
+      def valid?(record)
+        record.is_a?(Hash) && record.keys.sort == %w[complete messages version] && READ.include?(record["version"]) &&
+          [true, false].include?(record["complete"]) && Budget::Continuation.valid?(record["messages"]) &&
+          paired?(record["messages"], record["complete"])
+      end
+
+      # Each tool result answers a call of the reply before it, and a reply
+      # comes only once the one before has all its results. A complete
+      # record ends with a reply calling nothing; an unfinished one with all
+      # of the last reply's results, or with that reply (its tools not run).
+      def paired?(messages, complete)
+        open = []
+        messages.each do |message|
+          if message["role"] == "tool"
+            return false unless open.delete(message["tool_call_id"])
+          else
+            return false unless open.empty?
+
+            open = Array(message["tool_calls"]).map { _1["id"] }
+          end
+        end
+        ends?(messages.last, open, complete)
+      end
+
+      def ends?(last, open, complete)
+        return reply?(last) if complete
+
+        last["role"] == "tool" ? open.empty? : last["role"] == "assistant" && !open.empty?
+      end
+
+      def reply?(entry) = entry["role"] == "assistant" && entry["tool_calls"].nil?
+
+      def version(entries, complete)
+        last = entries.last
+        !complete && last["tool_calls"] ? VERSION : 1
+      end
+    end
 
     module_function
 
@@ -51,7 +149,7 @@ module Smith
 
     def request_digest(chat)
       shape = [chat.model.id, chat.model.provider.to_s, chat.messages.map { message_shape(_1) },
-               chat.tools.keys.map(&:to_s).sort, chat.schema, chat.params]
+               tools_shape(chat.tools), chat.schema, chat.params]
       Digest::SHA256.hexdigest(JSON.generate(shape))
     rescue StandardError
       nil
@@ -68,33 +166,44 @@ module Smith
       [message.role.to_s, body, message.tool_calls&.keys, message.tool_call_id]
     end
 
-    # The call's kept messages and whether it ended, or nil.
+    def tools_shape(tools)
+      tools.map { |name, tool| [name.to_s, tool.description, tool.params_schema] }.sort_by(&:first)
+    end
+
+    # The call's kept messages, whether it ended, and its reply whose tools
+    # had not run (`pending`, taken off the messages), or nil.
     def fetch(memo, key)
       record = memo.fetch(key)
       return unless record
 
       record = JSON.parse(JSON.generate(record))
-      raise ArgumentError, "not a response memo record" unless record?(record)
+      raise ArgumentError, "not a response memo record" unless Record.valid?(record)
 
-      { messages: Budget::Continuation.load(record["messages"]), complete: record["complete"] }
+      kept(Budget::Continuation.load(record["messages"]), record["complete"])
     rescue StandardError => e
       Smith.config.logger&.error("Smith response memo fetch error: #{e.class}")
       nil
     end
 
-    def record?(record)
-      record.is_a?(Hash) && record.keys.sort == %w[complete messages version] && record["version"] == VERSION &&
-        [true, false].include?(record["complete"]) && Budget::Continuation.valid?(record["messages"]) &&
-        (!record["complete"] || reply?(record["messages"].last))
+    def kept(messages, complete)
+      pending = messages.pop if !complete && calls_tools?(messages.last)
+      { messages:, complete:, pending: }
     end
 
-    def reply?(message) = message["role"] == "assistant" && message["tool_calls"].nil?
+    def calls_tools?(message) = message.is_a?(RubyLLM::Message) && message.role == :assistant && message.tool_call?
+
+    # Whether the message is the model's reply calling nothing, as a call
+    # ends.
+    def answer?(message) = message.is_a?(RubyLLM::Message) && message.role == :assistant && !message.tool_call?
 
     # Stores the call's messages (`facts`: a streamed reply's, by message),
     # unless they cannot be kept.
     def store(memo, key, messages, complete:, facts: {})
       dumped = Budget::Continuation.dump(nil, messages, usage: true, facts:)
-      return memo.store(key, { "version" => VERSION, "messages" => dumped, "complete" => complete }) if dumped
+      if dumped
+        return memo.store(key, { "version" => Record.version(dumped, complete), "messages" => dumped,
+                                 "complete" => complete })
+      end
 
       Smith.config.logger&.info("Smith response memo: a call not kept (an attachment, or past its byte limit)")
       nil
@@ -103,33 +212,29 @@ module Smith
       nil
     end
 
-    # Runs the block with the provider's call recorded: before each of its
-    # later rounds, its messages from `start` (the round before's tool
-    # results included) are stored as its progress.
-    def recording(provider, memo, key, start)
+    # Runs the block with the provider's call recorded (Recorder) from
+    # `start`, its first request answered by `pending` if given.
+    def recording(provider, memo, key, start, pending = nil)
       outer = Fiber[PROGRESS]
-      Fiber[PROGRESS] = Recorder.new(provider, memo, key, start, 0, false)
+      Fiber[PROGRESS] = Recorder.new(provider, memo, key, start, pending)
       yield
     ensure
       Fiber[PROGRESS] = outer
     end
 
     # A request the provider is about to make, from RubyLLM's
-    # `Provider#complete` (`messages`, its chat's).
-    def round(provider, messages, &)
+    # `Provider#complete` (`messages`, its chat's, and the request's
+    # `options`), and its reply.
+    def round(provider, messages, options = {}, &)
       recorder = Fiber[PROGRESS]
-      return yield unless recorder&.provider.equal?(provider) && !recorder.busy
-
-      recorder.rounds += 1
-      store(recorder.memo, recorder.key, messages.drop(recorder.start), complete: false) if recorder.rounds > 1
-      busy(recorder, &)
+      recorder&.records?(provider) ? recorder.round(messages, tools_offered?(options), &) : yield
     end
 
-    def busy(recorder)
-      recorder.busy = true
-      yield
-    ensure
-      recorder.busy = false
+    # Whether the request offered the model tools (a finalization that took
+    # them away did not, and its reply's calls never run).
+    def tools_offered?(options)
+      tools = options[:tools]
+      tools.respond_to?(:empty?) && !tools.empty?
     end
 
     # A nested workflow built in the block runs its calls under `attempts`

data/lib/smith/setting_constructors.rb

@@ -34,6 +34,20 @@ module Smith
       end
     end
 
+    # A list of StandardError subclasses, frozen; nil is none. StandardError
+    # itself would match every error, and an error outside it never reaches
+    # a step's rescue.
+    def error_classes(name)
+      lambda do |value|
+        classes = Array(value)
+        unless classes.all? { _1.is_a?(Class) && _1 < StandardError }
+          raise ArgumentError, "Smith.config.#{name} must list subclasses of StandardError, got #{value.inspect}"
+        end
+
+        classes.uniq.freeze
+      end
+    end
+
     # A host adapter: nil, or an object that answers `calls` (each named
     # with its arguments, as the message says).
     def adapter(name, calls)

data/lib/smith/tool/chat_execution_callbacks.rb

@@ -39,7 +39,7 @@ module Smith
       def handle_managed_callback_failure(batch, dispatch_call, claim, error)
         record_batch_failure(batch, error)
         raise error unless claim
-        raise error if error.is_a?(ToolFailureNotificationFailed)
+        raise error if error.is_a?(ToolFailureNotificationFailed) || Interruptions.find(error)
 
         failure = invocation_dispatch_failure(batch, dispatch_call, error)
         notify_invocation_failure(batch, dispatch_call, failure)

data/lib/smith/tool/execution_batch.rb

@@ -75,6 +75,11 @@ module Smith
 
       def settle! = call_reservation&.settle!
 
+      # One of its calls met an interruption (Smith::Interruptions).
+      def interrupted! = @interrupted = true
+
+      def interrupted? = @interrupted == true
+
       private
 
       def initialize_failure_queues

data/lib/smith/tool/execution_failure_handling.rb

@@ -16,14 +16,19 @@ module Smith
         batch.complete_failure_notification!(tool_call)
       rescue StandardError => e
         batch.release_failure_notification!(tool_call, state)
+        pass_interruption!(batch, e)
         raise ToolFailureNotificationFailed.new(
           dispatch_error: error,
           notification_error: e
         ), cause: e
       end
 
+      # An interruption settles nothing, as a process that died settles
+      # nothing: the host reconciles the batch's unsettled requests, whichever
+      # of its calls' errors reached here first.
       def notify_unsettled_batch_failures(batch, error)
         return unless batch&.host_admitted?
+        return if Interruptions.find(error) || batch.interrupted?
 
         handler = batch.context.fetch(:current_invocation_failure_handler)
         handler_error = notify_unsettled_requests(batch, error, handler)
@@ -40,6 +45,7 @@ module Smith
             batch.complete_failure_notification!(tool_call)
           rescue StandardError => e
             batch.release_failure_notification!(tool_call, state)
+            pass_interruption!(batch, e)
             first_error ||= ToolFailureNotificationFailed.new(
               dispatch_error: failure,
               notification_error: e
@@ -49,6 +55,15 @@ module Smith
         first_error
       end
 
+      # A failure handler that met an interruption stops the batch with it, as
+      # it was raised; what it had not settled stays unsettled for the host.
+      def pass_interruption!(batch, error)
+        return unless Interruptions.find(error)
+
+        record_batch_failure(batch, error)
+        Interruptions.pass!(error)
+      end
+
       def batch_dispatch_failure(error, state)
         return error.dispatch_error if error.is_a?(ToolFailureNotificationFailed)
         return error if state == :started || exact_dispatch_failure?(error)
@@ -68,15 +83,18 @@ module Smith
       end
 
       def record_batch_failure(batch, error)
-        if !error.is_a?(StandardError)
-          batch.fatal_failures.push(error)
-        elsif error.is_a?(ToolFailureNotificationFailed)
-          batch.notification_failures.push(error)
-        elsif error.is_a?(ToolCaptureFailed)
-          batch.capture_failures.push(error)
-        elsif Smith::Errors.retry_forbidden?(error)
-          batch.terminal_failures.push(error)
-        end
+        interrupted = Interruptions.find(error)
+        batch.interrupted! if interrupted
+        batch_failure_queue(batch, error, interrupted)&.push(error)
+      end
+
+      # An interruption counts as process-fatal: nothing else is raised over it.
+      def batch_failure_queue(batch, error, interrupted)
+        return batch.fatal_failures if interrupted || !error.is_a?(StandardError)
+        return batch.notification_failures if error.is_a?(ToolFailureNotificationFailed)
+        return batch.capture_failures if error.is_a?(ToolCaptureFailed)
+
+        batch.terminal_failures if Smith::Errors.retry_forbidden?(error)
       end
 
       def prioritized_batch_failure(batch)

data/lib/smith/version.rb

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

data/lib/smith/workflow/deterministic_execution.rb

@@ -13,7 +13,11 @@ module Smith
         finish_deterministic_step!(transition, step)
         nil
       rescue StandardError => e
-        emit_deterministic_trace(transition, outcome: :failed, failure: deterministic_failure_fields(transition, e))
+        if Interruptions.find(e)
+          emit_deterministic_trace(transition, outcome: :interrupted)
+        else
+          emit_deterministic_trace(transition, outcome: :failed, failure: deterministic_failure_fields(transition, e))
+        end
         raise
       end
 

data/lib/smith/workflow/parallel.rb

@@ -39,6 +39,7 @@ module Smith
       def self.preferred_error(reasons)
         errors = Array(reasons).compact
         process_fatal_error(errors) ||
+          interruption(errors) ||
           notification_failure(errors) ||
           terminal_execution_error(errors) ||
           ordinary_error(errors) ||
@@ -47,13 +48,16 @@ module Smith
 
       def self.process_fatal_error(errors) = errors.find { !_1.is_a?(StandardError) }
 
+      def self.interruption(errors) = errors.find { Interruptions.find(_1) }
+
       def self.notification_failure(errors) = errors.find { _1.is_a?(ToolFailureNotificationFailed) }
 
       def self.terminal_execution_error(errors) = errors.find { Smith::Errors.retry_forbidden?(_1) }
 
       def self.ordinary_error(errors) = errors.find { !_1.is_a?(Cancellation) }
 
-      private_class_method :process_fatal_error, :notification_failure, :terminal_execution_error, :ordinary_error
+      private_class_method :process_fatal_error, :interruption, :notification_failure, :terminal_execution_error,
+                           :ordinary_error
     end
   end
 end

data/lib/smith/workflow/remembered_calls.rb

@@ -6,16 +6,20 @@ module Smith
     # (Smith::ResponseMemo): each call takes its kept messages, if any, and
     # sends nothing when they end it (a streamed step's sink gets the reply's
     # text at once), else goes on from them, and is recorded as it goes.
-    # Kept tool results count as tools the step ran, and the live part goes
-    # on from the kept rounds (Resumed): its first request is a later round,
-    # and a pause for budget keeps the kept rounds too.
+    # Kept tool results count as tools the step ran, charged to its
+    # tool-call allowances as they were before the cut; a kept reply whose
+    # tools had not run is the answer to the live part's first request, and
+    # its tools run. The live part goes on from the kept rounds (Resumed):
+    # its first request is a later round, a pause for budget keeps the kept
+    # rounds too, and a streamed one's facts pair with its live replies.
     module RememberedCalls
       CALLS_LOCK = Mutex.new
       private_constant :CALLS_LOCK
 
-      # Where a call's live part starts: the call's first message, and the
-      # rounds its kept messages made.
-      Resumed = Data.define(:start, :rounds)
+      # Where a call's live part starts: the call's first message, the
+      # rounds its kept messages made, and its kept reply whose tools had
+      # not run (one of those rounds).
+      Resumed = Data.define(:start, :rounds, :pending)
 
       private
 
@@ -26,39 +30,68 @@ module Smith
 
         start = chat.messages.length
         kept = ResponseMemo.fetch(memo, key)
-        keep_messages(chat, kept.fetch(:messages)) if kept
+        keep_messages(chat, kept) if kept
         return replayed_completion(chat, model_reference) if kept&.fetch(:complete)
 
-        recorded_completion(chat, memo, key, Resumed.new(start:, rounds: kept_rounds(kept)), &)
+        recorded_completion(chat, memo, key, resumed(start, kept), &)
       end
 
-      def kept_rounds(kept) = kept ? kept.fetch(:messages).count { _1.role == :assistant } : 0
+      def resumed(start, kept)
+        return Resumed.new(start:, rounds: 0, pending: nil) unless kept
+
+        pending = kept.fetch(:pending)
+        Resumed.new(start:, rounds: kept.fetch(:messages).count { _1.role == :assistant } + (pending ? 1 : 0), pending:)
+      end
 
       def memo_key(chat, facts)
         ResponseMemo.key([*@memo_attempts, @step_attempt.to_i], facts[:attempt_index], next_memo_call, chat)
       end
 
       # The kept messages, after the call's own; their tool results are
-      # tools the step ran.
-      def keep_messages(chat, messages)
+      # tools the step ran, each charged as it was.
+      def keep_messages(chat, kept)
+        messages = kept.fetch(:messages)
         messages.each { chat.add_message(_1) }
-        Tool.current_tool_execution_tracker&.mark_started! if messages.any? { _1.role == :tool }
+        ran = messages.filter_map { _1.tool_call_id if _1.role == :tool }
+        Tool.current_tool_execution_tracker&.mark_started! if ran.any?
+        charge_kept_calls(ran_calls(messages, ran))
+      end
+
+      def ran_calls(messages, ran) = messages.flat_map { _1.tool_calls&.values.to_a }.select { ran.include?(_1.id) }
+
+      # Each kept call against the agent's tool-call allowance and the
+      # workflow's `tool_calls` budget, as a call that runs is, so a replay
+      # runs no more tools than the step may. A call past them (a budget
+      # lowered since, or a call rejected for budget) charges nothing more.
+      def charge_kept_calls(calls)
+        allowance = Tool.current_tool_call_allowance
+        ledger = Tool.current_ledger
+        commit = -> { ledger.reconcile!(ledger.reserve!(:tool_calls, 1), 1) if ledger&.limits&.key?(:tool_calls) }
+        calls.each { allowance.is_a?(Tool::CallAllowance) ? allowance.charge!(_1.name, &commit) : commit.call }
+      rescue BudgetExceeded
+        nil
       end
 
+      # A call a tool halted ends in that tool's result, not a reply: it
+      # keeps its progress, which a replay can go on from.
       def recorded_completion(chat, memo, key, resumed)
-        live = chat.messages.length
-        result = ResponseMemo.recording(chat_provider(chat), memo, key, resumed.start) { yield(resumed) }
-        ResponseMemo.store(memo, key, chat.messages.drop(resumed.start), complete: true,
-                                                                         facts: streamed_facts(chat, live, result))
+        result = ResponseMemo.recording(chat_provider(chat), memo, key, resumed.start, resumed.pending) do
+          yield(resumed)
+        end
+        messages = chat.messages.drop(resumed.start)
+        if ResponseMemo.answer?(messages.last)
+          ResponseMemo.store(memo, key, messages, complete: true, facts: streamed_facts(messages, result))
+        end
         result
       end
 
-      # A streamed call's replies' facts, read from its stream.
-      def streamed_facts(chat, live, result)
+      # A streamed call's replies' facts, read from its stream (its kept
+      # replies, which no round of it answered, keep their own).
+      def streamed_facts(messages, result)
         stream = result[1]
         return {} unless stream.is_a?(Hash) && stream[:rounds]
 
-        replies = chat.messages.drop(live).select { _1.role == :assistant }
+        replies = messages.select { _1.role == :assistant }
         replies.zip(Providers::StreamFacts.per_message(replies, stream[:rounds], stream[:output_limit]))
                .to_h.compare_by_identity
       end

data/lib/smith/workflow/retry_execution.rb

@@ -39,6 +39,7 @@ module Smith
           attempt_scope = attempt_idempotency_scope(key_generation)
           run_attempt_under_keys(transition, attempt_scope)
         rescue StandardError => e
+          Interruptions.pass!(e)
           raise unless retry_transition_error?(config, e, attempt)
 
           key_generation += 1 if new_idempotency_key_after?(config, e, attempt_scope)

data/lib/smith/workflow/split_step_persistence/composite_branch_execution.rb

@@ -54,6 +54,7 @@ module Smith
           end
           [output, nil]
         rescue StandardError => e
+          Interruptions.pass!(e)
           [nil, e]
         end
 

data/lib/smith/workflow/step_context.rb

@@ -16,6 +16,7 @@ module Smith
           install_step_idempotency_scope(transition)
           Thread.handle_interrupt(Object => :immediate, &block)
         rescue StandardError => e
+          Interruptions.pass!(e)
           @outcome = nil
           GuardrailIntegration.instance_method(:handle_step_failure).bind_call(self, transition, e)
         ensure

data/lib/smith.rb

@@ -79,6 +79,14 @@ module Smith
     :response_memo, { fetch: "fetch(key)", store: "store(key, record)" }
   )
 
+  # Errors that interrupt a step instead of failing it, such as the host's
+  # database or queue out of reach (Smith::Interruptions). A step that meets
+  # one, raised in it or as the cause of an error that was, stops where it
+  # is, as if its worker had stopped: no failure route, no retry, no failure
+  # recorded, and the error reaches the caller as it was raised.
+  setting :interrupting_errors, default: [].freeze,
+                                constructor: SettingConstructors.error_classes(:interrupting_errors)
+
   # How long a provider request's hold on a host's budget ledger
   # (`budget_ledger`) lasts unsettled, in seconds: past it the request's
   # process is taken to have died, and the ledger drops the hold. It must
@@ -203,6 +211,7 @@ require_relative "smith/providers/schema_constraints"
 require_relative "smith/tool_failure_notification_failed"
 require_relative "smith/persistence_payload_conflict"
 require_relative "smith/exponential_backoff"
+require_relative "smith/interruptions"
 
 # Event system (depends on Types)
 require_relative "smith/event"