smith-agents 0.11.0 → 0.12.1

data/lib/smith/workflow/graph.rb

@@ -93,6 +93,7 @@ require_relative "graph/execution_successors"
 require_relative "graph/reachability"
 require_relative "graph/reachability_diagnostics"
 require_relative "graph/metrics"
+require_relative "graph/inherited_untrusted_diagnostics"
 require_relative "graph/nested_readiness_diagnostics"
 require_relative "graph/report"
 require_relative "graph/runtime_binding_diagnostic_builder"
@@ -104,6 +105,17 @@ require_relative "graph/optimization_contract"
 require_relative "graph/orchestration_contract"
 require_relative "graph/transition_snapshot"
 require_relative "graph/retry_policy_diagnostic"
+require_relative "graph/branch_limit_diagnostic"
+require_relative "graph/isolated_input_diagnostic"
+require_relative "graph/output_key_diagnostic"
+require_relative "graph/stream_diagnostic"
+require_relative "graph/batch_diagnostic"
+require_relative "graph/budget_ledger_diagnostic"
+require_relative "graph/untrusted_input_diagnostic"
+require_relative "graph/output_schema_diagnostic"
+require_relative "graph/run_launcher_diagnostic"
+require_relative "graph/waiting_child_diagnostic"
+require_relative "graph/durable_retry_diagnostic"
 require_relative "graph/transition_diagnostics"
 require_relative "graph/validator"
 require_relative "graph/runtime_readiness"

data/lib/smith/workflow/guarded_step_execution.rb

@@ -14,26 +14,71 @@ module Smith
           begin
             Thread.handle_interrupt(Object => :immediate) { run_tracked_guarded_step(transition) }
           rescue StandardError => e
-            raise unless tracker.started?
-            raise if terminal_retry_error?(e)
+            raise unless uncertain_after_tools?(tracker, e)
 
             raise ToolOutcomeUncertain.new(
               "transition failed after tool execution began; retry could replay an uncertain outcome"
             ), cause: e
           ensure
+            # Tool evidence travels up: a step running inside another step
+            # (a nested workflow's step) marks the enclosing step too, so the
+            # enclosing step is never retried over tools that already ran.
+            previous_tracker&.mark_started! if tracker.started?
             Tool.current_tool_execution_tracker = previous_tracker
           end
         end
       end
 
+      # A failure after a tool ran leaves its outcome uncertain, unless its
+      # retry could not run the tool again: a terminal failure, or a tool
+      # loop paused for budget, whose retry continues from its tools'
+      # results.
+      def uncertain_after_tools?(tracker, error)
+        tracker.started? && !terminal_retry_error?(error) &&
+          !(error.is_a?(BudgetUnavailable) && error.continuation)
+      end
+
       def run_tracked_guarded_step(transition)
         return apply_composite_reduction!(transition) if @composite_reduction
 
         @resolved_parallel_branch_count = preflight_branch_count(transition)
-        run_standard_guarded_step(transition)
+        context_before = @context.dup
+        output = run_standard_guarded_step(transition)
+        enforce_context_shape!(context_before)
+        output
       ensure
         @resolved_parallel_branch_count = nil
       end
+
+      # Hooks that receive the live context (`before_eval`,
+      # `after_completion`, guardrails) can write to it directly. At the end
+      # of the step every new top-level key must be a Symbol that an explicit
+      # `persist` list allows, and every new or replaced value takes the
+      # context's key shape. On a violation the context goes back to its
+      # top-level values from the start of the step, as a failed
+      # deterministic step keeps none of its writes. A value changed in place
+      # is not seen until the next restore normalizes it. `O(K)` plus the size
+      # of changed values.
+      def enforce_context_shape!(before)
+        allowed = declared_persist_keys
+        normalized = @context.each_with_object({}) do |(key, value), changed|
+          next if before.key?(key) && before[key].equal?(value)
+
+          admit_context_key!(key, new_key: !before.key?(key), allowed:)
+          changed[key] = ContextKeys.normalize(value)
+        end
+        @context.merge!(normalized)
+      rescue WorkflowError
+        @context.replace(before)
+        raise
+      end
+
+      def admit_context_key!(key, new_key:, allowed:)
+        ContextKeys.validate_top_level_key!(key)
+        return unless new_key && allowed && !allowed.include?(key)
+
+        raise UndeclaredContextKey.new(key:, persisted_keys: allowed)
+      end
     end
   end
 end

data/lib/smith/workflow/message_batch.rb

@@ -4,6 +4,7 @@ require "dry-initializer"
 
 require_relative "../errors"
 require_relative "message_admission"
+require_relative "message_roles"
 
 module Smith
   class Workflow
@@ -50,6 +51,11 @@ module Smith
         role = message["role"]
         reject!("each session message requires a non-empty role") unless
           role.is_a?(String) && !role.strip.empty?
+        reject!("session messages admitted by the host cannot have the system role") if role.strip.casecmp?("system")
+        reject!("session messages admitted by the host cannot carry content parts") if Message.parts?(message)
+        return if MessageRoles.role(message, MessageRoles::ADMITTED)
+
+        reject!("session messages admitted by the host must have the role user, assistant or tool")
       end
 
       def reject!(message)

data/lib/smith/workflow/message_roles.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    # The roles a session message may carry, matched exactly. A host admits
+    # user, assistant and tool messages; system messages come only from
+    # Smith (injected state) and the host's `seed_messages` builder.
+    module MessageRoles
+      ALL = %w[system user assistant tool].freeze
+      ADMITTED = %w[user assistant tool].freeze
+
+      module_function
+
+      # The role of a message Hash with String or Symbol keys, when it is
+      # one of `allowed`; nil otherwise.
+      def role(message, allowed = ALL)
+        return unless message.is_a?(Hash)
+
+        value = message.key?(:role) ? message[:role] : message["role"]
+        value = value.to_s if value.is_a?(Symbol)
+        value if value.is_a?(String) && allowed.include?(value)
+      end
+    end
+  end
+end

data/lib/smith/workflow/message_value_normalizer.rb

@@ -20,6 +20,7 @@ module Smith
 
       param :value
       option :label, default: proc { "session message" }
+      option :max_bytes, default: proc { MAX_BYTES }
 
       def call
         @active = {}.compare_by_identity
@@ -100,7 +101,7 @@ module Smith
 
       def copy_string(string)
         @bytes += StringSnapshot.bytesize(string)
-        reject!("#{label} exceeds maximum bytes #{MAX_BYTES}") if @bytes > MAX_BYTES
+        reject!("#{label} exceeds maximum bytes #{max_bytes}") if @bytes > max_bytes
 
         StringSnapshot.copy(string, freeze: true)
       end

data/lib/smith/workflow/nested_execution.rb

@@ -11,18 +11,55 @@ module Smith
         check_deadline!
         child = build_child_workflow(transition.workflow_class)
         child_result = run_child_workflow(child)
+        reject_waiting_child!(child, child_result)
         handle_child_result(child_result)
       end
 
+      # A child that raises passes its error to the parent unchanged, after
+      # its billable usage is rolled up. If a tool ran in the child, the
+      # parent's step already carries that evidence and turns the failure
+      # into ToolOutcomeUncertain (GuardedStepExecution).
       def run_child_workflow(child)
         child.run!
-      rescue Smith::Error => e
-        raise WorkflowError, "nested workflow failed: #{e.message}"
+      rescue StandardError
+        roll_up_child_totals(raised_child_usage(child))
+        raise
+      end
+
+      # An in-process child cannot be left waiting inside its parent's step:
+      # its usage is kept, and the parent's step fails.
+      def reject_waiting_child!(child, child_result)
+        return unless child.waiting?
+
+        roll_up_child_totals(child_result)
+        cause = RetryWait.instance_method(:retry_wait_error).bind_call(child)
+        raise WorkflowError, "a nested workflow reached a step that waits (an await, delay or durable retry); " \
+                             "an in-process child cannot wait", cause:
+      end
+
+      RaisedChildUsage = Struct.new(:usage_entries, :total_cost, :total_tokens)
+      private_constant :RaisedChildUsage
+
+      def raised_child_usage(child)
+        RaisedChildUsage.new(child.usage_entries, child.instance_variable_get(:@total_cost),
+                             child.instance_variable_get(:@total_tokens))
+      end
+
+      # A nested workflow inherits the run's untrusted keys, and charges the
+      # run's budget ledger unless it names its own.
+      def new_nested_workflow(child_class)
+        StepIO.with_inherited_untrusted_keys(untrusted_context_keys) do
+          Budget::HostLedger.inheriting(method(:run_budget_ledger)) do
+            ResponseMemo.inheriting([*@memo_attempts, @step_attempt.to_i]) do
+              child_class.new(context: @context.dup, ledger: @ledger, created_at: @created_at)
+            end
+          end
+        end
       end
 
       def build_child_workflow(child_class)
         @split_step_active_execution_authorization&.verify_workflow!(child_class)
-        child = child_class.new(context: @context.dup, ledger: @ledger, created_at: @created_at)
+        child = new_nested_workflow(child_class)
         unless child.instance_of?(child_class)
           raise WorkflowError, "nested workflow constructor returned #{child.class} instead of #{child_class}"
         end
@@ -49,8 +86,14 @@ module Smith
       def handle_child_result(child_result)
         roll_up_child_totals(child_result)
 
+        # A child that handled its failure through its own `on_failure` route
+        # has already applied its failure policy, so the parent sees a
+        # non-retryable WorkflowError, as before.
         failed_step = child_result.steps.find { |s| s.key?(:error) }
-        raise WorkflowError, "nested workflow failed: #{failed_step[:error]&.message}" if failed_step
+        if failed_step
+          raise WorkflowError,
+                "nested workflow failed: #{DiagnosticText.capture(failed_step[:error]&.message.to_s, max_bytes: 1024)}"
+        end
 
         child_result.output
       end

data/lib/smith/workflow/orchestrator_worker.rb

@@ -40,7 +40,7 @@ module Smith
 
       def run_orchestration_loop(state)
         state.config[:max_delegation_rounds].times do |round|
-          result = run_orchestration_round(state, round)
+          result = IdempotencyKey.__send__(:within, :round, round) { run_orchestration_round(state, round) }
           return result if result
         end
 
@@ -65,12 +65,18 @@ module Smith
         invoke_agent_with_budget(state.orchestrator_class, input)
       end
 
+      # A task's position is its content, not its place in the list: a
+      # replayed orchestrator may list the same tasks in another order.
       def execute_workers(state, tasks)
         runner = method(:run_worker_with_schema)
+        output_schema = state.config[:worker_output_schema]
+        copies = Hash.new(0)
         tasks.map do |task|
           validate_task!(task, state.config[:task_schema])
-          execution = WorkerExecution.run(state.worker_class, task, state.config[:worker_output_schema], runner)
-          validate_worker_output!(execution.output, state.config[:worker_output_schema])
+          execution = IdempotencyKey.__send__(:within_content, :task, task, copies) do
+            WorkerExecution.run(state.worker_class, task, output_schema, runner)
+          end
+          validate_worker_output!(execution.output, output_schema)
           { execution_id: execution.execution_id, task: execution.task, output: execution.output }
         end
       end

data/lib/smith/workflow/parallel_execution.rb

@@ -36,6 +36,7 @@ module Smith
       def run_branch(transition, index, env, ledger, signal)
         binding = ParallelAgentBinding.new(self, transition, env.agent_class)
         with_branch_context(env, ledger, parallel_agent_binding: binding) do
+          narrow_idempotency_scope(:branch, index)
           with_agent_context(env.agent_class) do
             branch_ledger = effective_call_ledger
             reserved = reserve_branch_call(branch_ledger, env, ledger)
@@ -74,6 +75,7 @@ module Smith
           # Restoration is owned by the snapshot above, which tracks the
           # attribution thread key.
           Attribution.install(Attribution.ambient.merge(**attribution_overlay)) if attribution_overlay
+          narrow_idempotency_scope(:branch, attribution_overlay[:branch_key]) if attribution_overlay&.key?(:branch_key)
 
           unless parallel_agent_binding.equal?(NO_PARALLEL_BINDING)
             Thread.current[:smith_parallel_agent_binding] = parallel_agent_binding
@@ -84,6 +86,14 @@ module Smith
         end
       end
 
+      # Each branch of a step is a position of its own, so the same request
+      # from two branches gets two keys. Restoration is owned by the
+      # branch's ThreadContextSnapshot.
+      def narrow_idempotency_scope(*segment)
+        scope = IdempotencyKey.__send__(:current_scope)
+        IdempotencyKey.__send__(:install, scope.within(*segment)) if scope
+      end
+
       def setup_branch_context(env, ledger)
         env.setup_thread
         Tool.current_ledger = ledger

data/lib/smith/workflow/persistence.rb

@@ -13,7 +13,19 @@ module Smith
           context: snapshot_value(persisted_context),
           budget_consumed: ledger_consumed,
           step_count: @step_count,
+          awaiting: @awaiting&.dup,
+          # The attempt a durable retry makes next, and its key generation.
+          pending_retry: @pending_retry&.dup,
+          pending_batch: @pending_batch&.dup,
+          # The scope the run's budget_ledger is built from.
+          budget_ledger_scope: @budget_ledger_scope&.transform_keys(&:to_s),
+          active_seconds: @active_seconds || 0.0,
+          active_step_started_at: @active_step_started_at,
           execution_namespace: @execution_namespace,
+          # Untrusted keys inherited from a parent run (a durable child's).
+          inherited_untrusted_keys: (@inherited_untrusted_keys || []).map(&:to_s),
+          # Artifact namespaces a child run may read (its ancestors').
+          inherited_artifact_namespaces: (@inherited_artifact_namespaces || []).dup,
           created_at: @created_at,
           updated_at: @updated_at,
           next_transition_name: @next_transition_name,
@@ -85,6 +97,7 @@ module Smith
         @next_transition_name = normalized[:next_transition_name]
         @session_messages = normalized[:session_messages] || []
         @seed_message_count = validated_seed_message_count(normalized)
+        validate_session_parts!
         @total_cost = normalized[:total_cost] || 0.0
         @total_tokens = normalized[:total_tokens] || 0
         @outcome = normalized[:outcome]
@@ -99,6 +112,7 @@ module Smith
         @usage_mutex = Mutex.new
         @usage_entries = restore_usage_entries(normalized)
         @last_output = restore_last_output(normalized)
+        @last_transcript_output = restored_transcript_output
         # Backward-compat: pre-patch states have no last_agent_execution key and
         # restore to nil. @pending_agent_execution and @pending_evaluations are
         # transient (nil between steps), never persisted, but must be
@@ -113,6 +127,16 @@ module Smith
         # the original store from the legacy adapter contract).
         @persistence_version = persistence_version
         validate_definition_digest!(normalized)
+        validate_restored_position!(normalized)
+        @awaiting = WaitRecord.restore(normalized[:awaiting], workflow_class: self.class,
+                                                              persistence_key: normalized[:persistence_key],
+                                                              state: @state, next_transition: @next_transition_name)
+        @pending_retry = restore_pending_retry(normalized[:pending_retry], normalized[:persistence_key])
+        @pending_batch = restore_pending_batch(normalized[:pending_batch])
+        @active_seconds = restored_active_seconds(normalized[:active_seconds])
+        charge_unfinished_step!(normalized[:active_step_started_at])
+        @wait_mutex = Mutex.new
+        @wait_claimed = false
         # Preserve the seed digest from the persisted payload so it
         # round-trips on subsequent persists. validate_seed_digest!
         # compares this against a fresh evaluation of the seed builder
@@ -126,6 +150,18 @@ module Smith
         @split_step_mutex = Mutex.new
         validate_step_in_progress!(normalized) if
           self.class.idempotency_mode == :strict && !allow_step_in_progress
+        initialize_budget_ledger
+        @memo_attempts = []
+        @budget_ledger_scope = restored_budget_ledger_scope(normalized[:budget_ledger_scope])
+      end
+
+      # The stored scope, or, for a run stored before its class declared
+      # these scope keys, the one its context gives now.
+      def restored_budget_ledger_scope(stored)
+        return unless self.class.budget_ledger
+
+        Budget::HostLedger.stored_scope(self.class.budget_ledger_scope_keys, stored) ||
+          capture_budget_ledger_scope
       end
 
       def validated_persistence_version(normalized)
@@ -136,6 +172,24 @@ module Smith
               "persisted workflow persistence_version must be a non-negative integer, got #{version.inspect}"
       end
 
+      # Content parts come only from seed messages: anywhere else in a
+      # stored session they are refused, and a seed's are checked and kept
+      # as checked (String-keyed parts), however the payload was parsed.
+      def validate_session_parts!
+        @session_messages = @session_messages.each_with_index.map do |message, index|
+          next message unless Message.parts?(message)
+
+          checked = index < @seed_message_count && begin
+            Message.check_seed!(message)
+          rescue WorkflowError
+            nil
+          end
+          raise Smith::SerializationError, "persisted session content parts must be valid seed messages" unless checked
+
+          { role: checked["role"], content: checked["content"], parts: true }
+        end
+      end
+
       def validated_seed_message_count(normalized)
         count = normalized.fetch(:seed_message_count, 0)
         return count if count.is_a?(Integer) && count >= 0 && count <= @session_messages.length
@@ -227,6 +281,14 @@ module Smith
         end
       end
 
+      # The last assistant message after the seeds: the output the run last
+      # added to its transcript, unless the host admitted one after it.
+      def restored_transcript_output
+        seeds = @seed_message_count || 0
+        message = @session_messages.drop(seeds).reverse_each.find { |item| MessageRoles.role(item) == "assistant" }
+        message && message[:content]
+      end
+
       def restore_last_agent_execution(normalized)
         value = if normalized.key?(:last_agent_execution)
           normalized[:last_agent_execution]
@@ -256,15 +318,73 @@ module Smith
         ).call
       end
 
+      # A state or pending transition the class does not know (a deploy
+      # renamed or removed it, or the payload has none) fails the restore.
+      # Restoring it would leave the run in a state with no outgoing
+      # transitions, which reads as terminal and ends the run silently. Runs
+      # after `migrate_from` and after the definition digest check, so a
+      # migration can map an old name and a digest mismatch is reported as
+      # one.
+      def validate_restored_position!(normalized)
+        validate_restored_state!(normalized[:state], normalized[:persistence_key])
+        validate_restored_transition!(normalized[:next_transition_name], normalized[:persistence_key])
+      end
+
+      def validate_restored_state!(state, persistence_key)
+        return if state.nil? && self.class.initial_state.nil?
+        return if !state.nil? && self.class.known_state?(state)
+
+        raise Smith::UnknownStateOnRestore.new(workflow: self.class.name, persistence_key:, state:)
+      end
+
+      def validate_restored_transition!(transition, persistence_key)
+        return if transition.nil? || self.class.find_transition(transition)
+
+        raise Smith::UnknownTransitionOnRestore.new(workflow: self.class.name, persistence_key:, transition:)
+      end
+
       def restore_core_fields(normalized)
         @state = normalized[:state]
         @context = filter_persisted_context(normalized[:context] || {})
         @step_count = normalized[:step_count] || 0
-        @execution_namespace = normalized[:execution_namespace]
+        @execution_namespace = restored_execution_namespace(normalized)
+        @inherited_untrusted_keys = restored_inherited_untrusted_keys(normalized)
+        @inherited_artifact_namespaces = restored_artifact_namespaces(normalized)
         @created_at = normalized[:created_at]
         @updated_at = normalized[:updated_at]
       end
 
+      def restored_inherited_untrusted_keys(normalized)
+        keys = normalized.fetch(:inherited_untrusted_keys, [])
+        unless keys.is_a?(Array) && keys.length <= 1_000 && keys.all? { untrusted_key_name?(_1) }
+          raise Smith::SerializationError, "persisted workflow inherited_untrusted_keys are invalid"
+        end
+
+        keys.map(&:to_sym).uniq.freeze
+      end
+
+      def untrusted_key_name?(key) = (key.is_a?(String) || key.is_a?(Symbol)) && key.length.between?(1, 256)
+
+      def restored_artifact_namespaces(normalized)
+        ArtifactIntegration.artifact_namespaces!(normalized.fetch(:inherited_artifact_namespaces, []))
+      rescue WorkflowError
+        raise Smith::SerializationError, "persisted workflow inherited_artifact_namespaces are invalid"
+      end
+
+      # A payload written before namespaces were assigned at construction
+      # gets one derived from its own durable facts, the same on every
+      # restore of it, until a checkpoint stores it.
+      def restored_execution_namespace(normalized)
+        namespace = normalized[:execution_namespace]
+        if namespace.nil?
+          return IdempotencyKey.__send__(:legacy_namespace, normalized[:class] || self.class.name,
+                                         normalized[:persistence_key], normalized[:created_at])
+        end
+        return namespace if namespace.is_a?(String) && PreparedStep::UUID_PATTERN.match?(namespace)
+
+        raise Smith::SerializationError, "persisted workflow execution_namespace must be a UUID"
+      end
+
       def restore_persisted_keys(normalized)
         @persisted_keys_mutex = Mutex.new
         raw = normalized[:persisted_keys]
@@ -361,24 +481,22 @@ module Smith
         symbolized
       end
 
+      # The identifier the class itself uses for a payload's state name, so a
+      # String-named state stays a String; an unknown name is symbolized.
       def normalize_state_name(value)
         return if value.nil?
-        return value if declared_state?(value)
-        return value unless value.is_a?(String)
 
-        symbolized = value.to_sym
-        return symbolized if declared_state?(symbolized)
+        resolved = self.class.resolve_state_name(value)
+        return resolved unless resolved.nil?
 
-        symbolized
-      end
-
-      def declared_state?(value)
-        states = self.class.instance_variable_get(:@states) || []
-        states.include?(value)
+        value.is_a?(String) ? value.to_sym : value
       end
 
+      # Context keys are Symbols at every depth, matching what construction
+      # and deterministic writes produce, so a nested read behaves the same
+      # before and after a restore.
       def normalize_nested_hashes!(normalized)
-        normalized[:context] = symbolize_keys(normalized[:context]) if normalized[:context].is_a?(Hash)
+        normalized[:context] = ContextKeys.normalize(normalized[:context]) if normalized[:context].is_a?(Hash)
         return unless normalized[:budget_consumed].is_a?(Hash)
 
         normalized[:budget_consumed] = symbolize_keys(normalized[:budget_consumed])
@@ -388,7 +506,12 @@ module Smith
         return unless normalized[:session_messages].is_a?(Array)
 
         normalized[:session_messages] = normalized[:session_messages].map do |msg|
-          msg.is_a?(Hash) ? symbolize_keys(snapshot_value(msg)) : snapshot_value(msg)
+          unless MessageRoles.role(msg)
+            raise Smith::SerializationError,
+                  "persisted session message must have the role system, user, assistant or tool"
+          end
+
+          symbolize_keys(snapshot_value(msg))
         end
       end
 

data/lib/smith/workflow/remembered_calls.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    # A step's provider calls through a host's response memo
+    # (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.
+    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)
+
+      private
+
+      def remembered_completion(chat, model_reference, facts, &)
+        memo = Smith.config.response_memo
+        key = memo && memo_key(chat, facts)
+        return yield(nil) unless key
+
+        start = chat.messages.length
+        kept = ResponseMemo.fetch(memo, key)
+        keep_messages(chat, kept.fetch(:messages)) if kept
+        return replayed_completion(chat, model_reference) if kept&.fetch(:complete)
+
+        recorded_completion(chat, memo, key, Resumed.new(start:, rounds: kept_rounds(kept)), &)
+      end
+
+      def kept_rounds(kept) = kept ? kept.fetch(:messages).count { _1.role == :assistant } : 0
+
+      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)
+        messages.each { chat.add_message(_1) }
+        Tool.current_tool_execution_tracker&.mark_started! if messages.any? { _1.role == :tool }
+      end
+
+      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
+      end
+
+      # A streamed call's replies' facts, read from its stream.
+      def streamed_facts(chat, live, result)
+        stream = result[1]
+        return {} unless stream.is_a?(Hash) && stream[:rounds]
+
+        replies = chat.messages.drop(live).select { _1.role == :assistant }
+        replies.zip(Providers::StreamFacts.per_message(replies, stream[:rounds], stream[:output_limit]))
+               .to_h.compare_by_identity
+      end
+
+      def replayed_completion(chat, model_reference)
+        response = chat.messages.last
+        if (stream = @step_stream)
+          stream.start(attempt: @step_attempt, model: model_reference.model_id,
+                       provider: model_reference.provider&.to_s)
+          content = response.content
+          stream.delta(content.is_a?(String) ? content : JSON.generate(content))
+        end
+        [response, nil, nil, { memo: true }]
+      end
+
+      # The call's place among its attempt's calls at its position (a
+      # fan-out's branches count their own).
+      def next_memo_call
+        slot = [IdempotencyKey.__send__(:current_scope)&.key, @step_attempt]
+        memo_calls_lock.synchronize do
+          @memo_calls ||= {}
+          @memo_calls[slot] = @memo_calls.fetch(slot, 0) + 1
+        end
+      end
+
+      def memo_calls_lock = @memo_calls_lock || CALLS_LOCK.synchronize { @memo_calls_lock ||= Mutex.new }
+
+      def start_memo_calls = memo_calls_lock.synchronize { @memo_calls = {} }
+    end
+  end
+end