smith-agents 0.8.0 → 0.10.0

data/lib/smith/workflow/composite/effects.rb

@@ -4,19 +4,32 @@ require_relative "../../types"
 require_relative "../../budget/decimal_context"
 require_relative "../message_value_normalizer"
 require_relative "../prepared_step"
+require_relative "../usage_entry"
 require_relative "payload"
 
 module Smith
   class Workflow
     module Composite
-      class Effects < Payload
+      # Length is fail-closed value validation, not logic: every key the
+      # contract admits gets a bounded value check beside the contract that
+      # admits it. Splitting the checks away from the payload they guard
+      # would trade cohesion for a metric.
+      class Effects < Payload # rubocop:disable Metrics/ClassLength
         attr_reader :total_tokens, :total_cost
 
-        USAGE_ATTRIBUTES = %w[
-          usage_id agent_name model provider input_tokens output_tokens cost attempt_kind recorded_at
-        ].freeze
-        TOOL_ATTRIBUTES = %w[tool captured].freeze
-        private_constant :USAGE_ATTRIBUTES, :TOOL_ATTRIBUTES
+        # Required keys are the pre-attribution UsageEntry shape, so effects
+        # produced by an older Smith (a mid-deploy branch worker or a
+        # restored checkpoint) stay valid; allowed keys are the current
+        # member set, so unknown keys still reject. The attribution members
+        # (transition, branch_key, round, attempt_id) are optional by
+        # construction.
+        USAGE_ALLOWED_ATTRIBUTES = Workflow::UsageEntry.members.map(&:to_s).freeze
+        USAGE_REQUIRED_ATTRIBUTES =
+          (USAGE_ALLOWED_ATTRIBUTES - %w[transition branch_key round attempt_id workflow]).freeze
+        TOOL_REQUIRED_ATTRIBUTES = %w[tool captured].freeze
+        TOOL_ALLOWED_ATTRIBUTES = (TOOL_REQUIRED_ATTRIBUTES + %w[tool_call_id]).freeze
+        private_constant :USAGE_ALLOWED_ATTRIBUTES, :USAGE_REQUIRED_ATTRIBUTES,
+                         :TOOL_REQUIRED_ATTRIBUTES, :TOOL_ALLOWED_ATTRIBUTES
 
         attribute :usage_entries, Types::Array
         attribute :tool_results, Types::Array
@@ -25,17 +38,12 @@ module Smith
         def initialize(attributes)
           owned = self.class.normalize_attributes(attributes)
           normalized = MessageValueNormalizer.new(owned, label: "composite effects").call
-          usage_entries = normalized.fetch("usage_entries")
-          tool_results = normalized.fetch("tool_results")
-          budget_consumed = normalized.fetch("budget_consumed")
+          usage_entries, tool_results, budget_consumed =
+            normalized.values_at("usage_entries", "tool_results", "budget_consumed")
           @total_tokens, @total_cost = validate_usage_entries!(usage_entries)
           validate_tool_results!(tool_results)
           validate_budget!(budget_consumed)
-          super(
-            usage_entries:,
-            tool_results:,
-            budget_consumed:
-          )
+          super(usage_entries:, tool_results:, budget_consumed:)
         end
 
         private
@@ -44,8 +52,9 @@ module Smith
           raise ArgumentError, "composite usage entries must be an Array" unless entries.is_a?(Array)
 
           entries.each do |entry|
-            validate_exact_keys!(entry, USAGE_ATTRIBUTES, "composite usage entry")
+            validate_bounded_keys!(entry, USAGE_REQUIRED_ATTRIBUTES, USAGE_ALLOWED_ATTRIBUTES, "composite usage entry")
             validate_usage_identity!(entry)
+            validate_usage_attribution!(entry)
             validate_usage_amount!(entry.fetch("input_tokens"), "input_tokens")
             validate_usage_amount!(entry.fetch("output_tokens"), "output_tokens")
             validate_cost!(entry.fetch("cost"))
@@ -68,25 +77,40 @@ module Smith
         end
 
         def validate_usage_identity!(entry)
-          validate_usage_id!(entry.fetch("usage_id"))
-          validate_agent_name!(entry.fetch("agent_name"))
-          provider = entry.fetch("provider")
-          validate_nonempty_string!(provider, "composite usage entry provider") if provider
+          validate_uuid!(entry.fetch("usage_id"), "composite usage entry usage_id")
+          # agent_name and provider are nil-allowed; any other value
+          # (false included) must be a non-empty String.
+          %w[agent_name provider].each do |key|
+            value = entry.fetch(key)
+            validate_nonempty_string!(value, "composite usage entry #{key}") unless value.nil?
+          end
           %w[model attempt_kind recorded_at].each do |key|
             validate_nonempty_string!(entry.fetch(key), "composite usage entry #{key}")
           end
         end
 
-        def validate_usage_id!(usage_id)
-          return if usage_id.is_a?(String) && PreparedStep::UUID_PATTERN.match?(usage_id)
+        # The optional attribution keys are bounded values, not just bounded
+        # keys: a present key with a wrong-typed, empty, or oversized value
+        # rejects exactly like the identity fields do. Absent keys (older
+        # producers, or nil-omitting serialization) stay valid.
+        def validate_usage_attribution!(entry)
+          %w[transition branch_key workflow].each do |key|
+            validate_bounded_string!(entry.fetch(key), "composite usage entry #{key}", 256) if entry.key?(key)
+          end
+          validate_usage_amount!(entry.fetch("round"), "round") if entry.key?("round")
+          validate_uuid!(entry.fetch("attempt_id"), "composite usage entry attempt_id") if entry.key?("attempt_id")
+        end
+
+        def validate_uuid!(value, label)
+          return if value.is_a?(String) && PreparedStep::UUID_PATTERN.match?(value)
 
-          raise ArgumentError, "composite usage entry usage_id must be a UUID"
+          raise ArgumentError, "#{label} must be a UUID"
         end
 
-        def validate_agent_name!(agent_name)
-          return if agent_name.nil?
+        def validate_bounded_string!(value, label, max_length)
+          return if value.is_a?(String) && value.length.between?(1, max_length)
 
-          validate_nonempty_string!(agent_name, "composite usage entry agent_name")
+          raise ArgumentError, "#{label} must be a bounded non-empty String"
         end
 
         def validate_nonempty_string!(value, label)
@@ -102,8 +126,7 @@ module Smith
         end
 
         def validate_cost!(cost)
-          return if cost.nil?
-          return if cost.is_a?(Numeric) && cost.finite? && cost >= 0
+          return if cost.nil? || (cost.is_a?(Numeric) && cost.finite? && cost >= 0)
 
           raise ArgumentError, "composite usage entry cost must be a finite non-negative number or nil"
         end
@@ -112,10 +135,15 @@ module Smith
           raise ArgumentError, "composite tool results must be an Array" unless entries.is_a?(Array)
 
           entries.each do |entry|
-            validate_exact_keys!(entry, TOOL_ATTRIBUTES, "composite tool result")
-            tool = entry.fetch("tool")
-            unless tool.is_a?(String) && tool.length.between?(1, 256)
-              raise ArgumentError, "composite tool result tool must be a bounded non-empty String"
+            validate_bounded_keys!(entry, TOOL_REQUIRED_ATTRIBUTES, TOOL_ALLOWED_ATTRIBUTES, "composite tool result")
+            validate_bounded_string!(entry.fetch("tool"), "composite tool result tool", 256)
+
+            # Present only for provider-batch invocations; the producer never
+            # writes a nil, so a present key must carry a real id. Provider
+            # tool-call ids are short strings; 1024 is far above any observed
+            # provider format while still bounding the payload.
+            if entry.key?("tool_call_id")
+              validate_bounded_string!(entry.fetch("tool_call_id"), "composite tool result tool_call_id", 1024)
             end
           end
         end
@@ -130,9 +158,12 @@ module Smith
           end
         end
 
-        def validate_exact_keys!(value, expected, label)
+        # Every required key present, no key outside the allowed set: older
+        # producers (missing optional keys) pass, unknown keys still reject.
+        # Passing the same set for both is an exact-keys check.
+        def validate_bounded_keys!(value, required, allowed, label)
           raise ArgumentError, "#{label} must be a Hash" unless value.is_a?(Hash)
-          return if value.keys.sort == expected.sort
+          return if (required - value.keys).empty? && (value.keys - allowed).empty?
 
           raise ArgumentError, "#{label} attributes are invalid"
         end

data/lib/smith/workflow/deterministic_execution.rb

@@ -29,7 +29,8 @@ module Smith
           session_messages: snapshot_value(@session_messages || []),
           tool_results: snapshot_value(@tool_results || []),
           state: @state,
-          transition: transition
+          transition: transition,
+          last_agent_execution: snapshot_value(@last_agent_execution)
         )
       end
 

data/lib/smith/workflow/deterministic_step.rb

@@ -15,11 +15,24 @@ module Smith
         @current_state = state
         @transition_name = transition ? transition.name : options.fetch(:transition_name)
         @allowed_routes = snapshot_allowed_routes(transition ? transition.deterministic_routes : options[:allowed_routes])
+        @last_agent_execution = options[:last_agent_execution]
         @context_writes = {}
         @routed_to = nil
         @outcome = nil
       end
 
+      # The model id / provider that actually served the most recent serial
+      # `execute :agent` step (post fallback resolution), or nil if no serial
+      # agent step has run. Symmetric with `last_output`, which returns that
+      # step's content; use these to attribute an agent output to its model.
+      def last_agent_model
+        @last_agent_execution && @last_agent_execution[:model]
+      end
+
+      def last_agent_provider
+        @last_agent_execution && @last_agent_execution[:provider]
+      end
+
       def last_output
         return @last_output if defined?(@last_output)
 
@@ -59,7 +72,7 @@ module Smith
       private
 
       def validate_options!(options)
-        unknown = options.keys - %i[transition transition_name allowed_routes]
+        unknown = options.keys - %i[transition transition_name allowed_routes last_agent_execution]
         raise ArgumentError, "unknown keywords: #{unknown.join(", ")}" if unknown.any?
         return if options[:transition] || options.key?(:transition_name)
 

data/lib/smith/workflow/dsl.rb

@@ -17,6 +17,7 @@ module Smith
             duplicate_transition_index(@transitions_by_state)
           )
           subclass.instance_variable_set(:@transition_order, (@transition_order || {}).dup)
+          subclass.instance_variable_set(:@generated_transitions, (@generated_transitions || []).dup)
           subclass.instance_variable_set(:@transition_sequence, @transition_sequence)
           subclass.instance_variable_set(:@initial_state_name, @initial_state_name)
           subclass.instance_variable_set(:@budget_config, @budget_config&.dup)
@@ -50,7 +51,12 @@ module Smith
           declared = Transition.new(name, from: from, to: to, &)
           name = declared.name
           @transitions ||= {}
-          remove_from_transition_index(@transitions[name]) if @transitions.key?(name)
+
+          if @transitions.key?(name)
+            remove_from_transition_index(@transitions[name])
+            release_generated_transition_order(name)
+          end
+
           @transitions[name] = declared
           insert_into_transition_index(declared)
         end
@@ -279,10 +285,28 @@ module Smith
           transitions_by_state.delete(transition.from) if indexed.empty?
         end
 
+        # A user redeclaration replacing a GENERATED transition takes a fresh
+        # declaration-position order; a genuine user redefinition keeps its
+        # original position (matrix-pinned redefinition semantics). Without
+        # this, the synthetic :fail generated when `state :failed` is
+        # declared keeps its early order number, and a later user-declared
+        # :fail sharing an origin state with a primary transition would sort
+        # ahead of it and shadow it at run time.
+        def release_generated_transition_order(name)
+          return unless generated_transitions.delete(name)
+
+          transition_order.delete(name)
+        end
+
+        def generated_transitions
+          @generated_transitions ||= []
+        end
+
         def generate_fail_transition
           @transitions ||= {}
           return if @transitions.key?(:fail)
 
+          generated_transitions << :fail
           transition(:fail, from: nil, to: :failed)
         end
       end

data/lib/smith/workflow/evaluator_optimizer.rb

@@ -29,7 +29,9 @@ module Smith
 
       def run_optimization_loop(state)
         state.config[:max_rounds].times do |round|
-          result = run_optimization_round(state, round)
+          # The overlay scopes every trace and usage fact from this round's
+          # generator and evaluator calls to the round that produced them.
+          result = Attribution.with(round: round) { run_optimization_round(state, round) }
           return result if result
         end
 

data/lib/smith/workflow/event_integration.rb

@@ -15,7 +15,54 @@ module Smith
           Events::StepCompleted.new(
             transition: transition.name.to_sym,
             from: transition.from&.to_sym,
-            to: transition.to.to_sym
+            to: transition.to.to_sym,
+            workflow: Attribution.ambient.workflow
+          )
+        )
+      end
+
+      # Failure-path counterpart to emit_step_completed, fired from both
+      # failure handlers before they branch or re-raise, so an observer sees
+      # exactly where execution went dark. Classification reuses
+      # FailureRecord's bounded taxonomy; raw messages are never emitted. The
+      # rescue keeps a broken instrument from altering failure semantics:
+      # the original error, not an emission error, must win.
+      def emit_step_failed(step)
+        failure = FailureRecord.capture(step)
+        record_failed_transition_trace(failure)
+        emit_step_failed_event(failure)
+      rescue StandardError => e
+        Smith.config.logger&.error("Smith failed-step emission error: #{e.message}")
+      end
+
+      # `outcome`, not `result`: `result` is a reserved content key in the
+      # trace pipeline (it carries tool results and is stripped by the
+      # default content policy). Matches the :provider_call vocabulary.
+      # `from`/`to` stay present even when nil, matching the success-trace
+      # shape: an absent key would let the ambient attribution of an
+      # enclosing scope (a parent step's `from`) show through the
+      # fields-under-data merge and fabricate a foreign state fact.
+      def record_failed_transition_trace(failure)
+        data = {
+          transition: failure[:transition], from: failure[:from], to: failure[:to],
+          outcome: :failed,
+          error_class: failure[:error_class],
+          error_family: failure[:error_family]
+        }
+        data[:retryable] = failure[:error_retryable] unless failure[:error_retryable].nil?
+        Smith::Trace.record(type: :transition, data: data)
+      end
+
+      def emit_step_failed_event(failure)
+        Smith::Events.emit(
+          Events::StepFailed.new(
+            transition: DiagnosticText.capture(failure[:transition].to_s, max_bytes: 256).to_sym,
+            from: failure[:from]&.to_sym,
+            to: failure[:to]&.to_sym,
+            error_class: failure[:error_class],
+            error_family: failure[:error_family],
+            retryable: failure[:error_retryable],
+            workflow: Attribution.ambient.workflow
           )
         )
       end

data/lib/smith/workflow/execution.rb

@@ -31,6 +31,10 @@ module Smith
       end
 
       def execute_step_body(transition)
+        # Reset the per-step agent-attribution carrier so only a serial agent
+        # step that actually runs (below) leaves model/provider for complete_step;
+        # a deterministic step never sets it and must not inherit a stale value.
+        @pending_agent_execution = nil
         output = with_scoped_artifacts { run_with_retry_policy(transition) }
         StepCompletion.instance_method(:complete_step).bind_call(self, transition, output)
       end
@@ -93,6 +97,10 @@ module Smith
         begin
           result = execute_transition_body(transition, prepared_input: prepared_input)
           agent_result = result.is_a?(AgentResult) ? result : nil
+          # Capture the model/provider that actually served this serial agent
+          # step (post fallback resolution) for complete_step to fold into the
+          # durable step record. Nil when no agent ran (e.g. unconfigured model).
+          @pending_agent_execution = agent_result && { model: agent_result.model_used, provider: agent_result.provider_used }
           reconcile_branch_budget(ledger, reserved, agent_result: agent_result)
           reserved = nil
           agent_result ? agent_result.content : result

data/lib/smith/workflow/fanout_execution.rb

@@ -51,7 +51,7 @@ module Smith
       end
 
       def run_fanout_branch(branch_key, agent_name, agent_class, env, signal)
-        with_branch_context(env, @ledger, agent_class:) do
+        with_branch_context(env, @ledger, agent_class:, attribution_overlay: { branch_key: }) do
           with_agent_context(agent_class) do
             branch_ledger = effective_call_ledger
             reserved = reserve_fanout_branch_call(branch_ledger, env.branch_estimates[branch_key], agent_class)

data/lib/smith/workflow/guardrail_integration.rb

@@ -24,6 +24,12 @@ module Smith
 
       def handle_step_failure(transition, error)
         step = { transition: transition.name, from: transition.from, to: transition.to, error: error }
+        # Staged, not emitted: this rescue runs under the step snapshot's
+        # interrupt mask, and host StepFailed handlers must not execute
+        # unkillable. with_step_context flushes after the mask closes.
+        # Staged before the split-step capture so a capture invariant
+        # failure still flushes an emission for the original error.
+        @pending_step_failure = step
         SplitStepPersistence
           .instance_method(:capture_split_step_execution_result!)
           .bind_call(self, step)
@@ -50,9 +56,28 @@ module Smith
 
         @outcome = nil
         step = { transition: error.requested_name, from: @state, to: fail_transition.to, error: error }
+
+        # A step body that raised UnresolvedTransitionError was already
+        # captured, staged, and emitted under its real transition identity
+        # by the step-failure path before advance!'s rescue reached here.
+        # Capturing or emitting again would record the same failure twice,
+        # the second time under the requested name, a transition that never
+        # executed. Routing to :fail still happens either way.
+        if error.equal?(@emitted_step_failure_error)
+          @state = fail_transition.to
+          return step
+        end
+
         SplitStepPersistence
           .instance_method(:capture_split_step_execution_result!)
           .bind_call(self, step)
+        # Unlike the step-body path, this handler runs outside any step
+        # context (advance! rescues UnresolvedTransitionError after the step
+        # unwound), so the run identity must be seeded here or the emitted
+        # facts get fallback random ids.
+        Attribution.with(execution_key: @persistence_key, workflow: self.class.name || "anonymous") do
+          emit_step_failed(step)
+        end
         @state = fail_transition.to
         step
       end

data/lib/smith/workflow/parallel_execution.rb

@@ -60,6 +60,7 @@ module Smith
         ledger,
         parallel_agent_binding: NO_PARALLEL_BINDING,
         agent_class: nil,
+        attribution_overlay: nil,
         &block
       )
         snapshot = ThreadContextSnapshot.new
@@ -69,6 +70,11 @@ module Smith
           else
             setup_branch_context(env, ledger)
           end
+
+          # Restoration is owned by the snapshot above, which tracks the
+          # attribution thread key.
+          Attribution.install(Attribution.ambient.merge(**attribution_overlay)) if attribution_overlay
+
           unless parallel_agent_binding.equal?(NO_PARALLEL_BINDING)
             Thread.current[:smith_parallel_agent_binding] = parallel_agent_binding
           end

data/lib/smith/workflow/persistence.rb

@@ -26,8 +26,12 @@ module Smith
           # snapshot_value so non-JSON-safe runtime values (e.g.
           # custom Hash details on DeterministicStepFailure) get the
           # same deep-copy treatment as context/session_messages/etc.
-          usage_entries: snapshot_value((@usage_entries || []).map(&:to_h)),
+          usage_entries: snapshot_value(usage_entries_for_state.map(&:to_h)),
           last_output: snapshot_value(@last_output),
+          # Durable { model:, provider: } of the most recent serial agent step,
+          # so a deterministic step that resumes after the agent step (across a
+          # crash) still reads its `last_agent_model` / `last_agent_provider`.
+          last_agent_execution: snapshot_value(@last_agent_execution),
           last_failed_step: snapshot_value(@last_failed_step),
           # Optimistic-locking version. Adapters that support
           # store_versioned use this to detect concurrent writes; adapters
@@ -95,6 +99,12 @@ module Smith
         @usage_mutex = Mutex.new
         @usage_entries = restore_usage_entries(normalized)
         @last_output = restore_last_output(normalized)
+        # Backward-compat: pre-patch states have no last_agent_execution key and
+        # restore to nil. @pending_agent_execution is transient (nil between
+        # steps), never persisted, but must be initialized because from_state
+        # allocates and bypasses #initialize.
+        @last_agent_execution = restore_last_agent_execution(normalized)
+        @pending_agent_execution = nil
         @last_failed_step = restore_last_failed_step(normalized)
         # Restore the optimistic-locking version from the persisted payload.
         # Backward-compat: pre-versioning payloads have no key, restore to 0
@@ -192,6 +202,17 @@ module Smith
         raw.map { |h| Workflow::UsageEntry.from_h(h) }
       end
 
+      # Serialization reads the ledger under the recording mutex so a state
+      # written mid-fan-out never captures a torn array. The mutex can be
+      # absent on an allocated-but-unrestored instance; fall back to the
+      # bare read to_state always tolerated.
+      def usage_entries_for_state
+        mutex = @usage_mutex
+        return (@usage_entries || []).dup unless mutex
+
+        mutex.synchronize { (@usage_entries || []).dup }
+      end
+
       # Use key-presence checks (NOT `||`) so a deliberately persisted
       # `false` step output round-trips correctly. Smith's existing
       # `RunResult#output` derivation uses `compact.first`, which only
@@ -204,6 +225,17 @@ module Smith
         end
       end
 
+      def restore_last_agent_execution(normalized)
+        value = if normalized.key?(:last_agent_execution)
+          normalized[:last_agent_execution]
+        elsif normalized.key?("last_agent_execution")
+          normalized["last_agent_execution"]
+        end
+        return unless value.is_a?(Hash)
+
+        symbolize_keys(value)
+      end
+
       # Symbolize ONLY the top-level keys of last_failed_step + the
       # known value-symbols (`transition`, `from`, `to`, `error_kind`).
       # `error_family` stays a String (the family_fallback compares

data/lib/smith/workflow/prepared_branch_execution.rb

@@ -7,18 +7,27 @@ module Smith
 
       def prepared_branch(implementation, *arguments)
         tool_context = Tool::ScopedContext.capture
+        # Attribution is captured on the preparing thread (where the step's
+        # context is ambient) and carried into the branch thread, exactly as
+        # the tool context is; carrying nil deliberately clears stale state
+        # on a pooled thread.
+        ambient_attribution = Attribution.current
         unless @split_step_active_execution_authorization
           return proc do |signal|
-            Tool::ScopedContext.around(tool_context) do
-              __send__(implementation.name, *arguments, signal)
+            Attribution.carrying(ambient_attribution) do
+              Tool::ScopedContext.around(tool_context) do
+                __send__(implementation.name, *arguments, signal)
+              end
             end
           end
         end
 
         proc do |signal|
           run = proc { implementation.bind_call(self, *arguments, signal) }
-          Tool::ScopedContext.around(tool_context) do
-            PreparedBranchExecution.instance_method(:within_prepared_branch_execution).bind_call(self, &run)
+          Attribution.carrying(ambient_attribution) do
+            Tool::ScopedContext.around(tool_context) do
+              PreparedBranchExecution.instance_method(:within_prepared_branch_execution).bind_call(self, &run)
+            end
           end
         end
       end

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

@@ -40,7 +40,15 @@ module Smith
         end
 
         def capture_composite_branch(&block)
-          output = within_raw_step_context { with_scoped_artifacts(&block) }
+          output = within_raw_step_context do
+            # Same ambient attribution the in-process step path installs, so
+            # durably executed branches tag usage and traces identically
+            # (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
+            with_scoped_artifacts(&block)
+          end
           [output, nil]
         rescue StandardError => e
           [nil, e]

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_agent_execution = snapshot_value(@last_agent_execution)
           @last_failed_step = snapshot_value(@last_failed_step)
           @last_prepared_input = snapshot_value(@last_prepared_input)
         end

data/lib/smith/workflow/step_completion.rb

@@ -7,6 +7,15 @@ module Smith
 
       def complete_step(transition, 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
+
+        @pending_agent_execution = nil
         result = SplitStepPersistence
                  .instance_method(:prepare_split_step_execution_result)
                  .bind_call(self, step)

data/lib/smith/workflow/step_context.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "../attribution"
 require_relative "thread_context_snapshot"
 
 module Smith
@@ -10,6 +11,7 @@ module Smith
       def with_step_context(transition, &block)
         ThreadContextSnapshot.new.around do
           setup_step_context
+          install_step_attribution(transition)
           Thread.handle_interrupt(Object => :immediate, &block)
         rescue StandardError => e
           @outcome = nil
@@ -17,6 +19,32 @@ module Smith
         ensure
           teardown_step_context
         end
+      ensure
+        flush_step_failure_emission
+      end
+
+      # Runs after the snapshot's interrupt mask has closed, so host
+      # StepFailed handlers execute interruptible, exactly as StepCompleted
+      # handlers do inside the step. The step context is gone by now, so the
+      # run identity and workflow label are seeded explicitly; the failed
+      # step's own transition facts travel in the staged step hash. Flushes
+      # on every exit of with_step_context, including the re-raise paths.
+      # The read-clear-mark triple is masked so an async interrupt cannot
+      # strand a staged failure between read and clear; the marker lets the
+      # unresolved-transition handler recognize an error this path already
+      # emitted. Only the emission itself stays interruptible.
+      def flush_step_failure_emission
+        step = nil
+        Thread.handle_interrupt(Object => :never) do
+          step = @pending_step_failure
+          @pending_step_failure = nil
+          @emitted_step_failure_error = step[:error] if step
+        end
+        return unless step
+
+        Attribution.with(execution_key: @persistence_key, workflow: self.class.name || "anonymous") do
+          emit_step_failed(step)
+        end
       end
 
       def within_raw_step_context(&block)
@@ -34,6 +62,24 @@ module Smith
         Tool.current_tool_result_collector = tool_result_collector
       end
 
+      # The ambient attribution for this step. Restoration is owned by the
+      # surrounding ThreadContextSnapshot (the attribution thread key is one
+      # of its THREAD_KEYS), so installation is a plain assignment. A nil
+      # persistence key preserves any host-seeded outer execution_key, and
+      # `workflow` is always a string ("anonymous" when the class has no
+      # name) so a nested child always overrides the parent's label. The
+      # per-step facts (transition, from, to) are replaced verbatim, nil
+      # included: a nested child's `from: nil` transition must not inherit
+      # the parent step's `from` through the nil-ignoring merge. branch_key
+      # and round inherit deliberately (a child genuinely runs within them).
+      def install_step_attribution(transition)
+        Attribution.install(
+          Attribution.ambient
+                     .merge(execution_key: @persistence_key, workflow: self.class.name || "anonymous")
+                     .override(transition: transition.name, from: transition.from, to: transition.to)
+        )
+      end
+
       def teardown_step_context
         Tool.current_guardrails = nil
         Tool.current_deadline = nil

data/lib/smith/workflow/thread_context_snapshot.rb

@@ -22,6 +22,7 @@ module Smith
         current_invocation
       ].freeze
       THREAD_KEYS = %i[
+        smith_attribution
         smith_call_deadline
         smith_call_ledger
         smith_failed_agent_results