smith-agents 0.11.0 → 0.12.1

data/lib/smith/tool.rb

@@ -148,6 +148,20 @@ module Smith
 
     private
 
+    # A key for a request this tool sends outside the system: unique to the
+    # run, the step and branch the tool runs in, this tool's `name` and
+    # `scope`, and the same when a replay sends the same request. A tool can
+    # run several times in one step, and a replayed model may word or order
+    # its calls differently, so `scope` is required and should be the
+    # request's stable identity (`idempotency_key(customer_id:, invoice:)`),
+    # not free text. Renaming the tool changes its keys. Raises
+    # Smith::WorkflowError outside a workflow step.
+    def idempotency_key(scope)
+      raise WorkflowError, "an idempotency key needs a tool with a name" if name.to_s.empty?
+
+      IdempotencyKey.__send__(:current_scope!).within(:tool, name).key(scope)
+    end
+
     def run_before_execute_hook!(kwargs)
       hook = self.class.before_execute
       return unless hook

data/lib/smith/trace/logger.rb

@@ -37,7 +37,7 @@ module Smith
         when true
           data
         when :redacted
-          data.transform_values { |v| v.is_a?(String) ? "[REDACTED]" : v }
+          Smith::Trace.redact_sensitive_keys(data, CONTENT_KEYS)
         else
           data.except(*CONTENT_KEYS)
         end

data/lib/smith/trace/memory.rb

@@ -79,7 +79,7 @@ module Smith
         when true
           data
         when :redacted
-          data.transform_values { |v| v.is_a?(String) ? "[REDACTED]" : v }
+          Smith::Trace.redact_sensitive_keys(data, CONTENT_KEYS)
         else
           data.except(*CONTENT_KEYS)
         end

data/lib/smith/trace/open_telemetry.rb

@@ -91,7 +91,7 @@ module Smith
         when true
           data
         when :redacted
-          data.transform_values { |v| v.is_a?(String) ? "[REDACTED]" : v }
+          Smith::Trace.redact_sensitive_keys(data, CONTENT_KEYS)
         else
           data.except(*CONTENT_KEYS)
         end

data/lib/smith/trace.rb

@@ -72,9 +72,12 @@ module Smith
       end
     end
 
-    def self.redact_sensitive_keys(data)
+    # Masks content only: every String and Symbol inside the values of
+    # `content_keys`, at any depth. Identifiers (model, execution key, tool
+    # name, error class) stay readable.
+    def self.redact_sensitive_keys(data, content_keys = SENSITIVITY_CONTENT_KEYS)
       data.each_with_object({}) do |(key, value), filtered|
-        filtered[key] = if SENSITIVITY_CONTENT_KEYS.include?(key)
+        filtered[key] = if content_keys.include?(key)
                           redact_value(value)
                         else
                           value
@@ -82,12 +85,16 @@ module Smith
       end
     end
 
+    # Every String and Symbol leaf at any depth of Hashes and Arrays;
+    # numbers, booleans and nil are kept.
     def self.redact_value(value)
       case value
-      when String
+      when String, Symbol
         "[REDACTED]"
       when Hash
-        value.transform_values { |v| v.is_a?(String) ? "[REDACTED]" : v }
+        value.transform_values { |nested| redact_value(nested) }
+      when Array
+        value.map { |nested| redact_value(nested) }
       else
         value
       end

data/lib/smith/untrusted.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "digest"
+require "securerandom"
+
+module Smith
+  # Delimits text from outside the system (a fetched document, an inbound
+  # message) before it goes into a prompt, so the model can tell it apart
+  # from instructions:
+  #
+  #   Smith::Untrusted.wrap(document_text, source: "document")
+  #   # => <untrusted source="document" boundary="9f2c...">
+  #   #    ...text...
+  #   #    </untrusted boundary="9f2c...">
+  #
+  # The text cannot guess the boundary. Inside a workflow step it is derived
+  # from the run's namespace (a random UUID), the step's position, the
+  # source and the text, so a step that prepares its input again after a
+  # crash gets the same message; anywhere else it is random.
+  #
+  # Wrapping changes the text so it cannot close the block or pose as
+  # another turn: anything shaped like an untrusted tag (spaces, invisible
+  # characters or full-width forms included) becomes `untrusted-text`, and
+  # a role label (`system:`, `assistant:`, `user:`, `tool:`, `developer:`,
+  # `human:`, `ai:`) that opens any line gains "(quoted text)", also behind
+  # spaces, invisible characters, brackets, quotes, `#`, `>`, `*`, `_` or
+  # `-`. Ordinary text with such a line (`user: alice` in YAML) changes the
+  # same way. Markdown headings, XML-like tags such as `<system>` and
+  # look-alike letters are left as they are. Wrapping does not make text
+  # safe to act on; it only marks where it starts and ends.
+  module Untrusted
+    GAP = "\\p{Cf}*"
+    ROLE_WORDS = %w[system assistant user tool developer human ai].map { |role| role.chars.join(GAP) }.join("|")
+    ROLE_LABEL = /
+      (\A|[\n\r\v\f\u0085\u2028\u2029])
+      ([\p{Space}\p{Cf}#>\[(*_"'`-]*)
+      (#{ROLE_WORDS})
+      ([\p{Space}\p{Cf}*_\])"'`]*[:\uFF1A\uFE55])
+    /ix
+    TAG = %r{[<\uFF1C][\p{Space}\p{Cf}\p{Cc}]*([/\uFF0F]?)[\p{Space}\p{Cf}\p{Cc}]*#{"untrusted".chars.join(GAP)}}i
+    SOURCE = %r{\A[\w .:/-]{1,64}\z}
+
+    module_function
+
+    def wrap(text, source:)
+      raise ArgumentError, "untrusted text must be a String" unless text.is_a?(String)
+
+      label = source.to_s
+      unless label.is_a?(String) && SOURCE.match?(label)
+        raise ArgumentError, "untrusted source must be 1 to 64 letters, digits, spaces or . : / - _"
+      end
+
+      body = escape(text)
+      boundary = boundary_for(label, body)
+      %(<untrusted source="#{label}" boundary="#{boundary}">\n#{body}\n</untrusted boundary="#{boundary}">)
+    end
+
+    def escape(text)
+      utf8 = text.encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
+      utf8.gsub(TAG) { "<#{"/" unless Regexp.last_match(1).empty?}untrusted-text" }
+          .gsub(ROLE_LABEL) { Regexp.last_match.captures.insert(3, " (quoted text)").join }
+    end
+
+    # A position no idempotency key uses, so no key a step hands to another
+    # service gives the boundary away.
+    def boundary_for(label, body)
+      scope = IdempotencyKey.__send__(:current_scope)
+      return SecureRandom.hex(12) unless scope
+
+      scope.within(:untrusted).key([label, Digest::SHA256.hexdigest(body)])[0, 24]
+    end
+    private_class_method :boundary_for
+  end
+end

data/lib/smith/version.rb

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

data/lib/smith/workflow/active_clock.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    # `wall_clock` bounds the time the run's steps spend running, not the
+    # time since it was created: a run that waits for days, or whose host
+    # advances it step by step from a queue, spends only its active time.
+    # Each step's deadline is its start plus what is left of the budget, and
+    # the step's monotonic duration is added to the persisted
+    # `active_seconds` when it ends.
+    module ActiveClock
+      private
+
+      def start_active_clock!
+        @active_clock_started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        @active_clock_started_at = Time.now.utc
+        remove_instance_variable(:@wall_clock_deadline) if defined?(@wall_clock_deadline)
+      end
+
+      def stop_active_clock!
+        started = @active_clock_started
+        return unless started
+
+        @active_clock_started = nil
+        @active_seconds = (@active_seconds || 0.0) + (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started)
+      end
+
+      def active_deadline(limit)
+        (@active_clock_started_at || Time.now.utc) + (limit - (@active_seconds || 0.0))
+      end
+
+      # The checkpoint written before a step records when it began; the one
+      # written after clears it. A run restored with the mark still set had a
+      # step that raised or whose process died before finishing, so the time
+      # since that step began is charged, at most what is left of the budget,
+      # which keeps a run that keeps failing bounded across retries.
+      def mark_active_step_start!(running)
+        @active_step_started_at = running ? Time.now.utc.iso8601(6) : nil
+      end
+
+      def charge_unfinished_step!(started_at)
+        @active_step_started_at = nil
+        return if started_at.nil?
+
+        elapsed = [Time.now.utc - Time.iso8601(started_at.to_s), 0.0].max
+        limit = self.class.budget&.dig(:wall_clock)
+        elapsed = elapsed.clamp(0.0, [limit - @active_seconds, 0.0].max) if limit
+        @active_seconds += elapsed
+      rescue ArgumentError
+        raise Smith::SerializationError, "persisted workflow active_step_started_at must be an ISO 8601 time"
+      end
+
+      def restored_active_seconds(value)
+        return 0.0 if value.nil?
+        return value.to_f if (value.is_a?(Integer) || (value.is_a?(Float) && value.finite?)) && !value.negative?
+
+        raise Smith::SerializationError, "persisted workflow active_seconds must be a non-negative number"
+      end
+    end
+  end
+end

data/lib/smith/workflow/agent_result.rb

@@ -3,10 +3,24 @@
 module Smith
   class Workflow
     # rubocop:disable Style/RedundantStructKeywordInit
+    # `input_tokens` counts uncached input; `cache_read_tokens` and
+    # `cache_write_tokens` are the prompt-cache input beside it, and
+    # `total_tokens` adds all three to the output. `mode` is how the call was
+    # made, set by streaming and batch steps (nil for an ordinary call).
     AgentResult = Struct.new(
       :content, :input_tokens, :output_tokens, :cost, :model_used, :provider_used,
+      :cache_read_tokens, :cache_write_tokens, :thinking_tokens, :stop_reason, :provider_message_id, :mode,
       keyword_init: true
     ) do
+      # The detail members of an AgentResult taken from a ProviderUsage.
+      def self.usage_details(usage)
+        return {} unless usage
+
+        [*self::USAGE_DETAIL_MEMBERS, :mode].to_h do |member|
+          [member, usage.respond_to?(member) ? usage.public_send(member) : nil]
+        end
+      end
+
       def self.from_response(response, content, model_used: nil, provider_used: nil)
         new(
           content: content,
@@ -18,10 +32,33 @@ module Smith
         )
       end
 
+      # Not members, so they stay out of to_h, to_a and ==. metered_tokens
+      # is set on a partially metered invocation (some response reported no
+      # usage) to the tokens its metered responses recorded; cache_unpriced
+      # says cache tokens were priced at 0 for lack of a catalog rate.
+      attr_accessor :metered_tokens, :cache_unpriced
+
       def usage_known?
         !input_tokens.nil? && !output_tokens.nil?
       end
+
+      # The tokens a budget settles: the total when usage is known, the
+      # metered part of a partially metered invocation, otherwise every
+      # count that is known.
+      def billable_tokens
+        total_tokens || metered_tokens ||
+          [input_tokens, output_tokens, cache_read_tokens, cache_write_tokens].sum { |count| count || 0 }
+      end
+
+      def total_tokens
+        return unless usage_known?
+
+        input_tokens + output_tokens + (cache_read_tokens || 0) + (cache_write_tokens || 0)
+      end
     end
+    AgentResult::USAGE_DETAIL_MEMBERS = %i[
+      cache_read_tokens cache_write_tokens thinking_tokens stop_reason provider_message_id
+    ].freeze
     # rubocop:enable Style/RedundantStructKeywordInit
   end
 end

data/lib/smith/workflow/artifact_integration.rb

@@ -5,18 +5,67 @@ require "securerandom"
 module Smith
   class Workflow
     module ArtifactIntegration
+      # This run's view of the artifact store, for the host after or between
+      # its steps: read the refs the run stored (or its ancestors'), list
+      # its expired refs and delete them. Inside a step, Smith.artifacts is
+      # the same view.
+      def artifacts
+        Artifacts::ScopedStore.new(namespace: execution_namespace, readable: @inherited_artifact_namespaces || [])
+      end
+
+      # How many ancestors' artifacts a child run may read: the nearest
+      # ones, so a deep recursion reads its near ancestors and no others.
+      MAX_INHERITED_NAMESPACES = 16
+      INHERITED_NAMESPACES = :smith_inherited_artifact_namespaces
+      private_constant :INHERITED_NAMESPACES
+
+      # Builds a child run with the namespaces whose artifacts it may read
+      # in force from construction; they persist with it.
+      def self.with_inherited_artifact_namespaces(namespaces)
+        outer = Thread.current[INHERITED_NAMESPACES]
+        Thread.current[INHERITED_NAMESPACES] = artifact_namespaces!(namespaces)
+        yield
+      ensure
+        Thread.current[INHERITED_NAMESPACES] = outer
+      end
+
+      # At most MAX_INHERITED_NAMESPACES Strings of 1 to 256 characters.
+      def self.artifact_namespaces!(namespaces)
+        valid = namespaces.is_a?(Array) && namespaces.length <= MAX_INHERITED_NAMESPACES &&
+                namespaces.all? { _1.is_a?(String) && _1.length.between?(1, 256) }
+        raise WorkflowError, "artifact namespaces must be up to #{MAX_INHERITED_NAMESPACES} names" unless valid
+
+        namespaces.uniq.map { _1.dup.freeze }.freeze
+      end
+
+      # Taken once, so a workflow its constructor builds does not inherit
+      # them too.
+      def self.take_inherited_artifact_namespaces
+        namespaces = Thread.current[INHERITED_NAMESPACES]
+        Thread.current[INHERITED_NAMESPACES] = nil
+        namespaces || [].freeze
+      end
+
       private
 
+      # The step's artifacts are scoped to its run (or, in a nested
+      # workflow, its parent's), over the configured store itself even when
+      # the step runs inside another run's step (an inline child run),
+      # resolved when the step first stores or reads. The step context's
+      # snapshot restores the outer scope when the step ends.
       def with_scoped_artifacts
-        if @inherited_scoped_artifacts
-          Smith.scoped_artifacts = @inherited_scoped_artifacts
-        else
-          backend = Smith.config.artifact_store || Smith.artifacts
-          Smith.scoped_artifacts = Artifacts::ScopedStore.new(backend: backend, namespace: execution_namespace)
-        end
+        Smith.scoped_artifacts = @inherited_scoped_artifacts ||
+                                 Artifacts::ScopedStore.new(namespace: execution_namespace,
+                                                            readable: @inherited_artifact_namespaces || [])
         yield
       end
 
+      # What a child run of this run may read: this run's namespace, then
+      # the ones it may read itself, the nearest first.
+      def child_artifact_namespaces
+        [execution_namespace, *(@inherited_artifact_namespaces || [])].first(MAX_INHERITED_NAMESPACES).freeze
+      end
+
       def execution_namespace
         @execution_namespace ||= SecureRandom.uuid
       end
@@ -34,7 +83,8 @@ module Smith
           messages: messages,
           context_manager: manager,
           persisted_context: @context,
-          seed_message_count: @seed_message_count || 0
+          seed_message_count: @seed_message_count || 0,
+          untrusted_keys: untrusted_context_keys
         )
       end
     end

data/lib/smith/workflow/await_step.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    # What an `await` block receives when the step is entered. It reads the
+    # context, names the wait (`await_token`, the key the request the block
+    # sends must carry, the same each time the block runs again after a
+    # crash), and may finish the wait at once with `resolve!`. It cannot
+    # write the context: the payload `resolve!` or `resume!` delivers is
+    # written to the step's `into:` key.
+    class AwaitStep
+      attr_reader :context, :await_token, :attempt, :transition_name, :payload
+
+      def initialize(context:, await_token:, idempotency_scope:, attempt:, transition_name:)
+        @context = context
+        @await_token = await_token
+        @idempotency_scope = idempotency_scope
+        @attempt = attempt
+        @transition_name = transition_name
+        @resolved = false
+        @payload = nil
+      end
+
+      def read_context(key) = @context[key]
+
+      # A key for another request the block sends, as on any step.
+      def idempotency_key(scope = nil) = @idempotency_scope.key(scope)
+
+      # Finishes the wait inline with `payload`, which is written to `into:`
+      # as a delivered event's would be.
+      def resolve!(payload)
+        raise WorkflowError, "resolve! was already called" if @resolved
+
+        @payload = MessageValueNormalizer.new(payload, label: "wait payload").call
+        @resolved = true
+        nil
+      end
+
+      def resolved? = @resolved
+    end
+  end
+end

data/lib/smith/workflow/batch_charges.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    # What batch results cost (BatchWait). A call whose result has come is
+    # reserved for whatever the budget has left, never refused, as the money
+    # is spent; a succeeded result no call took is recorded as a billed
+    # response of its branch's agent (`:failed_attempt`, `mode: :batch`) and
+    # charged to the run's budget.
+    module BatchCharges
+      private
+
+      def reserve_estimates!(ledger, estimates)
+        return super unless batch_result_due?
+
+        Thread.current[:smith_call_reservation] = ledger.reserve_spent!(estimates)
+      end
+
+      def charge_untaken_batch_results(transition)
+        @batch_delivery.untaken.each do |branch_key, entry|
+          next unless entry.result["type"] == "succeeded"
+
+          Attribution.with(branch_key:) do
+            charge_batch_result(batch_agent_class(transition, branch_key), entry.result.fetch("message"))
+          end
+        end
+      end
+
+      def batch_agent_class(transition, branch_key)
+        return resolve_agent_class(transition) unless branch_key
+
+        resolve_fanout_agent_class(transition, transition.fanout_config.fetch(:branches).fetch(branch_key))
+      end
+
+      def charge_batch_result(agent_class, message)
+        usage = batch_reply_usage(message)
+        return unless usage
+
+        model = Agent::ModelReference.new(model_id: batch_model_id(agent_class, message), provider: "anthropic")
+        record_billed_usages(agent_class, [usage], :failed_attempt, model, attempt_id: nil)
+        settle_spent_batch_charges
+      end
+
+      # The id a call of the agent prices its usage under, as RubyLLM
+      # resolves the agent's model (an alias to its dated id), else the
+      # result's own (a model given by a block).
+      def batch_model_id(agent_class, message)
+        kwargs = agent_class.chat_kwargs
+        return message["model"] unless kwargs[:model]
+
+        RubyLLM::Models.resolve(kwargs[:model], provider: kwargs[:provider],
+                                                assume_exists: kwargs[:assume_model_exists] || false).first.id
+      rescue StandardError
+        kwargs[:model]
+      end
+
+      # A result's usage, as the provider's own parser reads its message.
+      def batch_reply_usage(message)
+        reply = RubyLLM::Providers::Anthropic.new(RubyLLM.config)
+                                             .send(:parse_completion_response,
+                                                   Providers::BatchExchange::Response.new(message.to_h))
+        Agent::ProviderUsage.from_message(reply)&.new(mode: :batch)
+      end
+
+      def settle_spent_batch_charges
+        ledger = effective_call_ledger
+        return clear_failed_billable_attempts unless ledger
+
+        reconcile_branch_budget(ledger, ledger.reserve_spent!(ledger.limits.keys.to_h { [_1, 0] }))
+        clear_failed_billable_attempts
+      end
+    end
+  end
+end

data/lib/smith/workflow/batch_execution.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Smith
+  class Workflow
+    # Batch mode (Smith::Batch). An attempt whose mode is :batch prepares its
+    # agent call as a synchronous one would, admits it against the budget,
+    # and captures the request instead of sending it (a fan-out captures each
+    # branch's, in turn). Once the step's attempt has ended without error
+    # (its context checks included), the requests go to
+    # Smith.config.batch_queue under ids of the wait's token and the run waits
+    # on `:batch_result`, recording its pending batch (the transition, the
+    # attempt, its key generation, and each request's digest). Like any wait
+    # it is not a step; BatchWait completes it. A step inside another run's
+    # step (an in-process child) cannot wait, so it never sends a batch.
+    module BatchExecution
+      # Batches end within 24 hours; the wait allows one more.
+      WAIT_SECONDS = 25 * 3600
+      # The requests an attempt captured, for the step to queue.
+      Captured = Data.define(:token, :requests, :attempt, :key_generation)
+
+      private
+
+      # The attempt sends its requests as a batch: its mode says so and no
+      # result of it is being delivered.
+      def batch_send?(transition)
+        transition.batches? && !delivering_batch? && batch_mode_for(transition) == :batch
+      end
+
+      # A delivery runs only the stored batch wait's step (BatchWait).
+      def delivering_batch? = !@batch_delivery.nil? && @pending_batch["attempt"] == (@step_attempt || 1)
+
+      def batch_mode_for(transition)
+        mode = transition.batch_mode
+        return mode unless mode.respond_to?(:call)
+
+        context = snapshot_value(@context)
+        arity = mode.is_a?(Proc) ? mode.arity : mode.method(:call).arity
+        value = arity == 1 ? mode.call(context) : mode.call(context, @step_attempt || 1)
+        return value if %i[sync batch].include?(value)
+
+        raise WorkflowError, "a mode: callable must return :sync or :batch, got #{value.inspect}"
+      end
+
+      # An agent step's batch: its one call.
+      def send_agent_batch(transition, agent_class, prepared_input)
+        send_batch(transition, nil => lambda do
+          admit_batch_call { reserve_for_serial(transition, effective_call_ledger) }
+          with_agent_context(agent_class) { capture_batch_request(agent_class, prepared_input) }
+        end)
+      end
+
+      # A fan-out's batch: each branch's call, captured in its own branch
+      # context (attribution, idempotency scope, budget share) in turn.
+      def send_fanout_batch(transition, branches, branch_agent_classes, prepared_input)
+        env = fanout_branch_environment(branches, branch_agent_classes, prepared_input)
+        captures = branches.to_h do |branch_key, _agent_name|
+          agent_class = branch_agent_classes.fetch(branch_key)
+          [branch_key, -> { capture_fanout_branch(env, branch_key, agent_class) }]
+        end
+        send_batch(transition, captures)
+      end
+
+      def capture_fanout_branch(env, branch_key, agent_class)
+        with_branch_context(env, @ledger, agent_class:, attribution_overlay: { branch_key: }) do
+          with_agent_context(agent_class) do
+            admit_batch_call do
+              reserve_fanout_branch_call(effective_call_ledger, env.branch_estimates[branch_key], agent_class)
+            end
+            capture_batch_request(agent_class, env.prepared_input)
+          end
+        end
+      end
+
+      # The budget admits the call now; what it costs is charged when its
+      # result comes.
+      def admit_batch_call
+        ledger = effective_call_ledger
+        release_branch_budget(ledger, yield)
+      end
+
+      # The request the agent's call would send (BatchExchange throws it out
+      # of the call before anything is sent), and its hold.
+      def capture_batch_request(agent_class, prepared_input)
+        @batch_capture = nil
+        request = catch(Providers::BatchExchange::CAPTURED) do
+          @batch_capturing = true
+          invoke_agent(agent_class, prepared_input)
+          nil
+        ensure
+          @batch_capturing = false
+        end
+        [request || raise(BatchModeUnavailable, "a batch step's agent made no provider request"), @batch_capture.hold]
+      end
+
+      def send_batch(transition, captures)
+        refuse_batch_wait!
+        token = wait_token_for(transition, ["batch", @step_attempt || 1])
+        captured = captures.transform_values(&:call)
+        hold_batch!(token, captured.transform_values(&:last))
+        Captured.new(token:, requests: captured.transform_values(&:first), attempt: @step_attempt || 1,
+                     key_generation: @step_key_generation || 0)
+      end
+
+      # The run can wait for a batch: a queue takes its requests, it is not
+      # inside split-step execution or another run's step (an in-process
+      # child), and the wait ends within the store's TTL.
+      def refuse_batch_wait!
+        Smith.config.batch_queue || raise(BatchQueueMissing)
+        raise WorkflowError, "a batch step cannot wait inside split-step execution" if @split_step_phase == :executing
+        raise WorkflowError, "an in-process child cannot wait for a batch" if Thread.current[:smith_step_depth].to_i > 1
+
+        check_wait_ttl!(WAIT_SECONDS)
+      end
+
+      # Hands the captured requests to the queue and waits. The batch is the
+      # attempt a pending retry waited to make, so the pending batch takes
+      # its place.
+      def queue_batch(transition, captured)
+        ids = enqueue_requests(captured)
+        @batch_holds = nil
+        @pending_retry = nil
+        @pending_batch = pending_batch_record(transition, captured, ids)
+        @awaiting = WaitRecord.build_batch(transition, captured.token, WAIT_SECONDS, Time.now.utc, ids.length)
+        record_wait_trace(transition, :waiting)
+        WAIT_PENDING
+      end
+
+      # Enqueues each captured request under its custom id; returns them by id.
+      def enqueue_requests(captured)
+        ids = captured.requests.to_h { |branch_key, request| [Batch.custom_id(captured.token, branch_key), request] }
+        ids.each do |custom_id, request|
+          Smith.config.batch_queue.enqueue(custom_id:, await_token: captured.token, request:,
+                                           execution_key: @persistence_key)
+          # Handed off, it may be sent: its hold stays until its result, or
+          # expires.
+          @batch_holds&.delete(custom_id)
+        end
+        ids
+      end
+
+      def pending_batch_record(transition, captured, ids)
+        { "transition" => transition.name.to_s, "attempt" => captured.attempt,
+          "key_generation" => captured.key_generation, "requests" => ids.transform_values { Batch.digest(_1) } }.freeze
+      end
+    end
+  end
+end