smith-agents 0.11.0 → 0.12.0

data/lib/smith/workflow/retry_execution.rb

@@ -7,29 +7,86 @@ module Smith
 
       # `@step_attempt` is the attempt under way, from 1, which the optimizer
       # names its verdicts by; transient, set here before every attempt.
+      #
+      # Every attempt sends its requests under the step's idempotency keys,
+      # so a retry after an uncertain failure (a timeout, a lost connection)
+      # cannot repeat a request that took effect. Only an attempt that
+      # failed in a way the step declares settled moves later attempts to
+      # new keys. Attempts replay in the same order after a restore, so a
+      # replay reaches the same keys as long as the receivers answer the
+      # replayed requests as before. A durable policy waits out the backoff
+      # as a wait of the run (RetryWait) and resumes at the attempt and key
+      # generation it recorded.
       def run_with_retry_policy(transition)
         config = transition.retry_config
-        @step_attempt = 1
+        position = pending_batch_position
+        @step_attempt = position ? position.first + 1 : 1
+        @step_key_generation = position ? position.last : 0
+        start_budget_pause(transition)
+        start_memo_calls
         return run_guarded_step(transition) unless config
 
+        run_attempts(transition, config, *(position || pending_retry_position(transition)))
+      end
+
+      # Attempts after the `attempt` already made, under `key_generation`.
+      def run_attempts(transition, config, attempt, key_generation)
         schedule = retry_schedule(config)
-        attempt = 0
         begin
           attempt += 1
           @step_attempt = attempt
-          run_guarded_step(transition)
+          @step_key_generation = key_generation
+          attempt_scope = attempt_idempotency_scope(key_generation)
+          run_attempt_under_keys(transition, attempt_scope)
         rescue StandardError => e
           raise unless retry_transition_error?(config, e, attempt)
 
-          sleep_for_retry(schedule, attempt)
+          key_generation += 1 if new_idempotency_key_after?(config, e, attempt_scope)
+          keep_budget_continuation(e)
+          delay = retry_delay(schedule, attempt)
+          return wait_to_retry(transition, delay, attempt + 1, key_generation, e) if config[:durable]
+
+          sleep(delay) if delay.positive?
           retry
         end
       end
 
+      def attempt_idempotency_scope(key_generation)
+        step_scope = IdempotencyKey.__send__(:current_scope)
+        return step_scope if step_scope.nil? || key_generation.zero?
+
+        step_scope.within(:key_generation, key_generation)
+      end
+
+      def run_attempt_under_keys(transition, attempt_scope)
+        return run_guarded_step(transition) if attempt_scope.equal?(IdempotencyKey.__send__(:current_scope))
+
+        IdempotencyKey.__send__(:swap, attempt_scope) { run_guarded_step(transition) }
+      end
+
+      # A `fail!(new_idempotency_key: true)` counts only when this step's own
+      # attempt raised it, never a nested workflow's step, whose flag speaks
+      # for its own requests and not for the earlier steps of the attempt.
+      def new_idempotency_key_after?(config, error, attempt_scope)
+        return true if own_settled_failure?(error, attempt_scope)
+
+        config.fetch(:new_idempotency_key_on, EMPTY_ERROR_CLASSES).any? { |error_class| error.is_a?(error_class) }
+      end
+
+      def own_settled_failure?(error, attempt_scope)
+        error.is_a?(DeterministicStepFailure) && error.new_idempotency_key &&
+          !attempt_scope.nil? && error.idempotency_scope == attempt_scope
+      end
+
+      EMPTY_ERROR_CLASSES = [].freeze
+      private_constant :EMPTY_ERROR_CLASSES
+
       def retry_transition_error?(config, error, attempt)
         return false if attempt >= config.fetch(:attempts)
         return false if terminal_retry_error?(error)
 
+        return false if retry_deadline_passed?
+
         classes = config.fetch(:error_classes)
         if classes.any?
           classes.any? { |error_class| error.is_a?(error_class) }
@@ -38,13 +95,15 @@ module Smith
         end
       end
 
-      def terminal_retry_error?(error)
-        Smith::Errors.retry_forbidden?(error)
+      # No attempt starts once the wall-clock deadline has passed: it could
+      # only fail again, after sleeping through its backoff.
+      def retry_deadline_passed?
+        deadline = effective_deadline
+        !deadline.nil? && Time.now.utc >= deadline
       end
 
-      def sleep_for_retry(schedule, failed_attempt)
-        delay = retry_delay(schedule, failed_attempt)
-        sleep(delay) if delay.positive?
+      def terminal_retry_error?(error)
+        Smith::Errors.retry_forbidden?(error)
       end
 
       def retry_delay(config_or_schedule, failed_attempt)

data/lib/smith/workflow/retry_wait.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Smith
+  class Workflow
+    # The waits of durable retries. An attempt that fails in a way a
+    # `retry_on ..., durable: true` policy retries does not sleep: the run
+    # enters a wait of kind `retry`, due when the backoff ends, and records
+    # its pending retry (the transition, the next attempt, its key
+    # generation, and the class of the error that failed the last attempt).
+    # `expire_wait!` past the deadline ends the wait without a step and
+    # leaves the transition as the run's next; the host continues the run as
+    # after any wait, and the step makes the recorded attempt under the
+    # recorded keys. A step that ends without entering a wait clears the
+    # pending retry (Workflow#advance!).
+    module RetryWait
+      PENDING_RETRY_FIELDS = %w[attempt error key_generation transition].freeze
+      private_constant :PENDING_RETRY_FIELDS
+
+      private
+
+      # Enters the wait, due after the backoff, under a token of the attempt
+      # it waits to make. Like any wait it is not a step. The pending retry
+      # is recorded before the wait, so an interrupt between the two leaves
+      # a step that ended without a wait, whose pending retry is cleared.
+      def wait_to_retry(transition, seconds, attempt, key_generation, error)
+        if @split_step_phase == :executing
+          raise WorkflowError, "a durable retry cannot wait inside split-step execution"
+        end
+
+        check_wait_ttl!(seconds)
+        error_name = DiagnosticText.error_class_name(error)
+        @pending_retry = { "transition" => transition.name.to_s, "attempt" => attempt,
+                           "key_generation" => key_generation, "error" => error_name,
+                           "continuation" => @budget_continuation }.compact.freeze
+        @retry_wait_error = error
+        @awaiting = WaitRecord.build_retry(transition, wait_token_for(transition, ["retry", attempt]), seconds,
+                                           Time.now.utc)
+        record_retry_trace(transition, :retrying, attempt:, error: error_name, deadline_at: @awaiting["deadline_at"])
+        WAIT_PENDING
+      end
+
+      # A step that ran and did not enter a wait has made its pending retry,
+      # whether it completed, failed or raised.
+      def clear_settled_pending_retry
+        @pending_retry = nil if step_work_started? && !waiting?
+      end
+
+      # [attempts already made, key generation] where the step starts: the
+      # pending retry's for its transition, else [0, 0].
+      def pending_retry_position(transition)
+        pending = @pending_retry
+        return [0, 0] unless pending && pending["transition"] == transition.name.to_s
+
+        [pending["attempt"] - 1, pending["key_generation"]]
+      end
+
+      # The backoff is over: the transition becomes the run's next step, then
+      # the wait ends; nothing counts. Returns :expired.
+      def end_retry_wait(transition)
+        @next_transition_name = transition.name
+        @updated_at = Time.now.utc.iso8601(6)
+        @awaiting = nil
+        Attribution.with(execution_key: @persistence_key, workflow: self.class.name || "anonymous") do
+          record_retry_trace(transition, :retry_due, attempt: @pending_retry&.fetch("attempt"))
+        end
+        :expired
+      ensure
+        @wait_claimed = false
+      end
+
+      def record_retry_trace(transition, outcome, **details)
+        Smith::Trace.record(
+          type: :transition,
+          data: { transition: transition.name, from: transition.from, to: transition.to, outcome:, **details }
+        )
+      end
+
+      # The error that failed the attempt a retry wait follows, while this
+      # instance holds it (for a nested child's parent).
+      def retry_wait_error = (@retry_wait_error if retry_waiting?)
+
+      # A persisted pending retry names the transition of the stored retry
+      # wait, or else the run's next one, with an attempt after the first, a
+      # key generation an earlier attempt could reach, and an error class
+      # name; a stored retry wait needs one. A malformed one raises
+      # SerializationError; one the class no longer allows (the transition
+      # declares no durable retry, or fewer attempts) is refused like an
+      # unknown position.
+      def restore_pending_retry(value, persistence_key)
+        return if value.nil? && !retry_waiting?
+
+        record = value.is_a?(Hash) ? value.transform_keys(&:to_s) : {}
+        transition = pending_retry_transition(record)
+        raise Smith::SerializationError, "persisted workflow pending_retry is invalid" unless
+          well_formed_pending_retry?(transition, record)
+
+        refuse_disallowed_pending_retry!(transition, record, persistence_key)
+        record.transform_values(&:freeze).freeze
+      end
+
+      def retry_waiting? = @awaiting&.fetch("kind") == "retry"
+
+      # The transition the record names, when it is the stored retry wait's,
+      # or the run's next while the run does not wait.
+      def pending_retry_transition(record)
+        return if @awaiting && !retry_waiting?
+
+        name = @awaiting ? @awaiting["transition"] : @next_transition_name&.to_s
+        self.class.transition_named(name) if name && record["transition"] == name
+      end
+
+      def well_formed_pending_retry?(transition, record)
+        !transition.nil? && (record.keys - ["continuation"]).sort == PENDING_RETRY_FIELDS &&
+          pending_retry_fields?(record) &&
+          (!record.key?("continuation") || Budget::Continuation.valid?(record["continuation"]))
+      end
+
+      def pending_retry_fields?(record)
+        attempt, generation, error = record.values_at("attempt", "key_generation", "error")
+        attempt.is_a?(Integer) && attempt >= 2 && generation.is_a?(Integer) && generation.between?(0, attempt - 1) &&
+          error.is_a?(String) && error.bytesize.between?(1, 256)
+      end
+
+      def refuse_disallowed_pending_retry!(transition, record, persistence_key)
+        return if transition.durable_retry? && record["attempt"] <= transition.retry_config.fetch(:attempts)
+
+        raise Smith::UnknownTransitionOnRestore.new(workflow: self.class.name, persistence_key:,
+                                                    transition: transition.name)
+      end
+    end
+  end
+end

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

@@ -35,6 +35,9 @@ module Smith
           end
           @split_step_mutex.synchronize { @split_step_phase = :checkpointed } if checkpoint_claimed
           result
+        rescue PersistedStateTooLarge
+          release_split_step_checkpoint! if checkpoint_claimed
+          raise
         rescue StandardError
           mark_split_step_checkpoint_unknown! if checkpoint_claimed
           raise

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

@@ -40,6 +40,13 @@ module Smith
           end
         end
 
+        # A checkpoint refused before anything was written may be made again.
+        def release_split_step_checkpoint!
+          @split_step_mutex.synchronize do
+            @split_step_phase = :checkpoint_retryable if @split_step_phase == :checkpointing
+          end
+        end
+
         def mark_split_step_checkpoint_unknown!
           @split_step_mutex.synchronize do
             @split_step_phase = :checkpoint_unknown if @split_step_phase == :checkpointing

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

@@ -46,7 +46,10 @@ module Smith
             # (execution key from the restored persistence key, the split
             # step's transition, then the branch overlay downstream).
             # Restoration is owned by within_raw_step_context's snapshot.
-            install_step_attribution(@split_step_transition) if @split_step_transition
+            if @split_step_transition
+              install_step_attribution(@split_step_transition)
+              install_step_idempotency_scope(@split_step_transition)
+            end
             with_scoped_artifacts(&block)
           end
           [output, nil]

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

@@ -33,8 +33,10 @@ module Smith
 
         def prepare_composite_input(authorization, transition, specs)
           ThreadContextSnapshot.new.around do
+            # The step's position, as in-process guardrails run with it.
+            install_step_idempotency_scope(transition)
             run_composite_input_guardrails(authorization, transition, specs)
-            agent_messages = build_session&.prepare!
+            agent_messages = step_prepared_input(transition)
             Composite::Input.build(agent_messages:, session_messages: snapshot_session_messages)
           end
         end

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

@@ -48,6 +48,7 @@ module Smith
         end
 
         def replace_exact_dispatch!(payload)
+          check_state_size!(@split_step_persistence_key, payload)
           @split_step_adapter.replace_exact(
             @split_step_persistence_key,
             payload,

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

@@ -70,10 +70,15 @@ module Smith
         end
 
         def prepare_claimed_persisted_step!(key, adapter)
+          raise WorkflowError, "split-step persistence cannot prepare a step while the run waits" if waiting?
+
           transition = pending_split_step_transition
           transition_name = @next_transition_name || transition&.name
           raise WorkflowError, "workflow has no pending transition" unless transition_name
 
+          refusal = "split-step persistence does not run steps that wait or launch runs"
+          raise WorkflowError, refusal if transition&.waits_or_launches?
+
           ensure_transition_budget!
           resolved_key = normalize_split_step_persistence_key(candidate_split_step_persistence_key(key))
           store = persistence_adapter!(adapter)

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

@@ -58,6 +58,7 @@ module Smith
 
         def detach_split_step_results!
           @last_output = snapshot_value(@last_output)
+          @last_transcript_output = snapshot_value(@last_transcript_output)
           @last_agent_execution = snapshot_value(@last_agent_execution)
           @last_failed_step = snapshot_value(@last_failed_step)
           @last_prepared_input = snapshot_value(@last_prepared_input)

data/lib/smith/workflow/step_completion.rb

@@ -3,24 +3,26 @@
 module Smith
   class Workflow
     module StepCompletion
+      # Room for what completing a step adds besides its output (its state,
+      # step count, last agent).
+      RESULT_MARGIN = 1024
+
       private
 
       def complete_step(transition, output)
+        StepCompletion.instance_method(:check_result_storable!).bind_call(self, output)
         step = { transition: transition.name, from: transition.from, to: transition.to, output: output }
         # Fold in the serial agent attribution captured for this step (if any),
         # then clear the transient carrier. record_step_snapshot reads these off
         # the returned step to update the durable @last_agent_execution.
-        if @pending_agent_execution
-          step[:model] = @pending_agent_execution[:model]
-          step[:provider] = @pending_agent_execution[:provider]
-        end
+        step.merge!(@pending_agent_execution.slice(:model, :provider)) if @pending_agent_execution
 
         @pending_agent_execution = nil
         fold_pending_evaluations(step)
         result = SplitStepPersistence
                  .instance_method(:prepare_split_step_execution_result)
                  .bind_call(self, step)
-        StepCompletion.instance_method(:append_accepted_output).bind_call(self, output)
+        StepCompletion.instance_method(:keep_accepted_output).bind_call(self, transition, output)
         SplitStepPersistence
           .instance_method(:commit_split_step_execution_result!)
           .bind_call(self, result)
@@ -34,10 +36,37 @@ module Smith
         step
       end
 
-      def append_accepted_output(output)
-        return unless @session_messages && !output.nil?
+      # A stored run's step whose result would take its state past
+      # persistence_max_bytes fails with PersistedStateTooLarge before the
+      # result is kept, as with any error: its usage is recorded, its
+      # on_failure taken, and its run stays storable (strict mode
+      # included), where a refused store after the step would leave it
+      # unsaved. The estimate is the state's JSON and the output's, kept
+      # twice (in the context or transcript, and as the last output).
+      def check_result_storable!(output)
+        limit = Smith.config.persistence_max_bytes
+        return unless limit && @persistence_version.to_i.positive?
+
+        bytes = JSON.generate(to_state).bytesize + (JSON.generate(output).bytesize * 2) + RESULT_MARGIN
+        raise PersistedStateTooLarge.new(key: @persistence_key, bytes:, limit:) if bytes > limit
+      rescue JSON::GeneratorError, JSON::NestingError, Encoding::UndefinedConversionError
+        nil
+      end
+
+      # Once the result is captured, so a step whose result is refused leaves
+      # neither the context nor the transcript changed.
+      def keep_accepted_output(transition, output)
+        StepIO.instance_method(:deliver_output_to).bind_call(self, transition, output) if transition.output_to
+        StepCompletion.instance_method(:append_accepted_output).bind_call(self, transition, output)
+      end
+
+      # The transcript keeps an accepted output unless the step writes it to
+      # the context (`output_to:`) or the session is isolated.
+      def append_accepted_output(transition, output)
+        return unless @session_messages && !output.nil? && transcript_output?(transition)
 
         @session_messages << { role: :assistant, content: output }
+        @last_transcript_output = output
       end
     end
   end

data/lib/smith/workflow/step_context.rb

@@ -10,14 +10,17 @@ module Smith
 
       def with_step_context(transition, &block)
         ThreadContextSnapshot.new.around do
+          start_active_clock!
           setup_step_context
           install_step_attribution(transition)
+          install_step_idempotency_scope(transition)
           Thread.handle_interrupt(Object => :immediate, &block)
         rescue StandardError => e
           @outcome = nil
           GuardrailIntegration.instance_method(:handle_step_failure).bind_call(self, transition, e)
         ensure
           teardown_step_context
+          stop_active_clock!
         end
       ensure
         flush_step_failure_emission
@@ -47,12 +50,17 @@ module Smith
         end
       end
 
+      # A durable composite branch runs here, in its own restored instance:
+      # it starts from what is left of the run's wall_clock, and its running
+      # time is not added back to the run's active_seconds.
       def within_raw_step_context(&block)
         ThreadContextSnapshot.new.around do
+          start_active_clock!
           setup_step_context
           Thread.handle_interrupt(Object => :immediate, &block)
         ensure
           teardown_step_context
+          stop_active_clock!
         end
       end
 
@@ -80,6 +88,19 @@ module Smith
         )
       end
 
+      # The step's position for idempotency keys: its number and transition
+      # in this run's namespace. A nested workflow sharing the namespace (an
+      # in-process child) is placed under the parent's current position, so
+      # a child step never takes a key a parent step already used; any other
+      # workflow started inside a step is a run of its own. Restoration is
+      # owned by the surrounding ThreadContextSnapshot.
+      def install_step_idempotency_scope(transition)
+        namespace = ArtifactIntegration.instance_method(:execution_namespace).bind_call(self)
+        outer = IdempotencyKey.__send__(:current_scope)
+        base = outer && outer.run == namespace ? outer : IdempotencyKey.__send__(:root_scope, namespace)
+        IdempotencyKey.__send__(:install, base.within(:step, @step_count + 1, transition.name.to_s))
+      end
+
       def teardown_step_context
         Tool.current_guardrails = nil
         Tool.current_deadline = nil

data/lib/smith/workflow/step_io.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require_relative "execution_result_snapshot"
+require_relative "message_batch"
+require_relative "message_value_normalizer"
+
+module Smith
+  class Workflow
+    # Per-step input and output: a step's `input:` replaces the session
+    # transcript as its messages, `output_to:` writes its output to a context
+    # key instead of the transcript, and an isolated session keeps no
+    # transcript for agents at all. Also the run's untrusted keys: its own
+    # context's, and those of every workflow it is nested in.
+    module StepIO
+      INPUT_ROLES = %w[user assistant].freeze
+      INHERITED_UNTRUSTED_KEYS = :smith_inherited_untrusted_keys
+      private_constant :INPUT_ROLES, :INHERITED_UNTRUSTED_KEYS
+
+      # Builds a nested workflow with its parent's untrusted keys in force
+      # from construction, before its seed builder runs.
+      def self.with_inherited_untrusted_keys(keys)
+        outer = Thread.current[INHERITED_UNTRUSTED_KEYS]
+        Thread.current[INHERITED_UNTRUSTED_KEYS] = untrusted_key_names!(keys)
+        yield
+      ensure
+        Thread.current[INHERITED_UNTRUSTED_KEYS] = outer
+      end
+
+      # Context key names: at most 1,000, each a Symbol or String of 1 to 256
+      # characters, as Symbols.
+      def self.untrusted_key_names!(keys)
+        valid = keys.is_a?(Array) && keys.length <= 1_000 &&
+                keys.all? { (_1.is_a?(Symbol) || _1.is_a?(String)) && _1.length.between?(1, 256) }
+        raise WorkflowError, "untrusted keys must be up to 1,000 context key names" unless valid
+
+        keys.map(&:to_sym).uniq.freeze
+      end
+
+      # The keys handed to the workflow under construction; taken once, so a
+      # workflow its constructor builds does not inherit them too.
+      def self.take_inherited_untrusted_keys
+        keys = Thread.current[INHERITED_UNTRUSTED_KEYS]
+        Thread.current[INHERITED_UNTRUSTED_KEYS] = nil
+        keys || [].freeze
+      end
+
+      private
+
+      def isolated_session? = self.class.session == :isolated
+
+      def untrusted_context_keys
+        manager = self.class.context_manager
+        own = manager.respond_to?(:untrusted_keys) ? manager.untrusted_keys : []
+        own | (@inherited_untrusted_keys || [])
+      end
+
+      # The context without its untrusted keys, as `inject_state` formatters
+      # and the `seed_messages` builder read it.
+      def trusted_context_view
+        keys = untrusted_context_keys
+        keys.empty? || !@context.is_a?(Hash) ? @context : @context.except(*keys)
+      end
+
+      # The messages an agent step sees: its `input:`, or else the session
+      # transcript (with injected state). An isolated session has no
+      # transcript to give: an agent step there must declare `input:`, and
+      # any other step gets nothing, so state is never injected.
+      def step_prepared_input(transition)
+        return step_input_messages(transition) if transition.step_input
+        return build_session&.prepare! unless isolated_session?
+        return unless transition.agent_step?
+
+        raise WorkflowError, "transition #{DiagnosticText.capture(transition.name.to_s, max_bytes: 256)} runs an " \
+                             "agent in an isolated session and must declare input:"
+      end
+
+      # A non-empty Array of at most MessageBatch::MAX_MESSAGES user and
+      # assistant messages, bounded and JSON-shaped like session messages.
+      # The callable gets a copy of the context, so it cannot change the
+      # run's.
+      def step_input_messages(transition)
+        messages = transition.step_input.call(snapshot_value(@context))
+        unless messages.is_a?(Array) && !messages.empty? && messages.length <= MessageBatch::MAX_MESSAGES
+          raise WorkflowError, "input: must return a non-empty Array of at most #{MessageBatch::MAX_MESSAGES} messages"
+        end
+
+        MessageValueNormalizer.new(messages, label: "step input").call.map { |message| step_input_message(message) }
+      end
+
+      def step_input_message(message)
+        return step_input_parts_message(message) if Message.parts?(message)
+        unless message.is_a?(Hash) && message.keys.sort == %w[content role] && INPUT_ROLES.include?(message["role"]) &&
+               !message["content"].nil?
+          raise WorkflowError, "each input: message must be { role: :user or :assistant, content: } with content"
+        end
+
+        { role: message["role"].to_sym, content: message["content"] }
+      end
+
+      # A message with content parts (Smith::Message), user or assistant.
+      def step_input_parts_message(message)
+        checked = Message.check!(message)
+        raise WorkflowError, "an input: message with content parts must be a user or assistant message" unless
+          INPUT_ROLES.include?(checked["role"])
+
+        { role: checked["role"].to_sym, content: checked["content"], parts: true }
+      end
+
+      # Checked before the step runs, so a key the persist list refuses
+      # costs no agent call.
+      def writable_output_key!(transition)
+        key = transition.output_to
+        keys = declared_persist_keys
+        raise UndeclaredContextKey.new(key:, persisted_keys: keys) if keys && !keys.include?(key)
+
+        key
+      end
+
+      # The step's output, nil included, under `output_to:`: JSON-shaped and
+      # in the context's key shape, so it reads the same live and restored.
+      def deliver_output_to(transition, output)
+        key = writable_output_key!(transition)
+        value = MessageValueNormalizer.new(output, label: "output_to: value",
+                                                   max_bytes: ExecutionResultSnapshot::MAX_BYTES).call
+        @context[key] = ContextKeys.normalize(value)
+        record_persisted_key!(key)
+      end
+
+      def transcript_output?(transition) = transition.output_to.nil? && !isolated_session?
+    end
+  end
+end

data/lib/smith/workflow/step_stream.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    # A step declared with `stream:` streams through its sink
+    # (Smith::Streaming), which hears the step's outcome: its accepted
+    # output, a durable retry's wait, or its failure. Every other step clears
+    # the stream, so none of its calls reach another step's sink; a nested
+    # workflow is a run of its own, with its own steps.
+    #
+    # The accepted output reaches the sink once the step is stored: at once
+    # for a run that is not stored (no persistence key), else when `persist!`
+    # stores it, or when the run moves on without storing it. A store that
+    # fails tells the sink the step failed, with the store's error.
+    module StepStream
+      private
+
+      def with_step_stream(transition)
+        @step_stream = transition.stream &&
+                       Streaming.open(transition.stream, execution_key: @persistence_key, transition: transition.name)
+        step = yield
+        if wait_pending?(step) then @step_stream&.suspend
+        elsif @step_stream then accept_streamed(@step_stream, step[:output])
+        end
+        step
+      rescue Exception => e # rubocop:disable Lint/RescueException -- the sink hears of every failure, then it goes on
+        @step_stream&.fail(e.class)
+        raise
+      ensure
+        @step_stream = nil
+      end
+
+      def accept_streamed(session, output)
+        return session.finish(output) unless @persistence_key
+
+        @streamed_output = [session, output]
+      end
+
+      def deliver_streamed_output
+        session, output = @streamed_output
+        @streamed_output = nil
+        session&.finish(output)
+      end
+
+      def discard_streamed_output(error_class)
+        session, = @streamed_output
+        @streamed_output = nil
+        session&.fail(error_class)
+      end
+    end
+  end
+end

data/lib/smith/workflow/thread_context_snapshot.rb

@@ -20,6 +20,7 @@ module Smith
         current_invocation_context
         current_invocation_sequence
         current_invocation
+        current_idempotency_scope
       ].freeze
       THREAD_KEYS = %i[
         smith_attribution
@@ -28,6 +29,7 @@ module Smith
         smith_failed_agent_results
         smith_last_agent_result
         smith_parallel_agent_binding
+        smith_step_depth
       ].freeze
 
       option :tool_attributes, default: proc { TOOL_ATTRIBUTES }