smith-agents 0.6.1 → 0.8.0

data/lib/smith/workflow/failure_record_validator.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+require_relative "../errors"
+require_relative "composite/branch_failure"
+
+module Smith
+  class Workflow
+    class FailureRecordValidator
+      KNOWN_ERROR_FAMILIES = {
+        "Smith::DeterministicStepFailure" => "deterministic_step_failure",
+        "Smith::ToolGuardrailFailed" => "tool_guardrail_failed",
+        "Smith::ToolCaptureFailed" => "tool_capture_failed",
+        "Smith::ToolFailureNotificationFailed" => "tool_failure_notification_failed",
+        "Smith::ToolOutcomeUncertain" => "tool_outcome_uncertain",
+        "Smith::ToolExecutionNotAdmitted" => "tool_execution_not_admitted",
+        "Smith::BoundedCompletionError" => "bounded_completion_error",
+        "Smith::PersistedFailureInvalid" => "persisted_failure_invalid",
+        "Smith::AgentError" => "agent_error",
+        "Smith::BlankAgentOutputError" => "agent_error",
+        "Smith::DeadlineExceeded" => "deadline_exceeded",
+        "Smith::WorkflowError" => "workflow_error",
+        "Smith::UnresolvedTransitionError" => "workflow_error",
+        "Smith::Workflow::Composite::BranchFailure" => "workflow_error"
+      }.freeze
+      KNOWN_FAMILIES = %w[
+        deterministic_step_failure tool_guardrail_failed tool_failure_notification_failed tool_capture_failed
+        tool_outcome_uncertain tool_execution_not_admitted bounded_completion_error persisted_failure_invalid
+        deadline_exceeded agent_error workflow_error other
+      ].freeze
+      RETRY_FORBIDDEN_FAMILIES = %w[
+        tool_capture_failed tool_failure_notification_failed tool_outcome_uncertain tool_execution_not_admitted
+        bounded_completion_error persisted_failure_invalid
+      ].freeze
+      DETAIL_VALIDATORS = {
+        "Smith::ToolCaptureFailed" => ->(details) { Smith::ToolCaptureFailed.from_details(details) },
+        "Smith::ToolFailureNotificationFailed" => lambda { |details|
+          Smith::ToolFailureNotificationFailed.from_details(details)
+        },
+        "Smith::Workflow::Composite::BranchFailure" => lambda { |details|
+          Smith::Workflow::Composite::BranchFailure.from_details(details)
+        }
+      }.freeze
+      BOOLEAN_VALUES = [true, false].freeze
+      private_constant :KNOWN_ERROR_FAMILIES, :KNOWN_FAMILIES, :RETRY_FORBIDDEN_FAMILIES, :DETAIL_VALIDATORS,
+                       :BOOLEAN_VALUES
+
+      extend Dry::Initializer
+
+      param :snapshot
+
+      def call
+        validate_family!
+        validate_class_family!
+        validate_retry_policy!
+        validate_cause!
+        validate_details!
+        snapshot
+      rescue ArgumentError, KeyError, TypeError
+        reject!("persisted workflow failure details are invalid")
+      end
+
+      private
+
+      def family = snapshot[:error_family]
+
+      def validate_family!
+        return if KNOWN_FAMILIES.include?(family)
+
+        reject!("persisted workflow failure family is invalid")
+      end
+
+      def validate_class_family!
+        expected = KNOWN_ERROR_FAMILIES[snapshot[:error_class]]
+        return unless expected && family != expected
+
+        reject!("persisted workflow failure class and family disagree")
+      end
+
+      def validate_retry_policy!
+        forbidden = snapshot[:error_retry_forbidden]
+        return if forbidden.nil?
+
+        reject!("persisted workflow failure retry policy is invalid") unless BOOLEAN_VALUES.include?(forbidden)
+        return if forbidden == RETRY_FORBIDDEN_FAMILIES.include?(family)
+
+        reject!("persisted workflow failure retry policy disagrees with its family")
+      end
+
+      # Cause classification travels as one unit: capture writes all three
+      # attributes together for uncertainty wrappers, so a partial set is
+      # corrupt data rather than a legacy shape (legacy records omit all
+      # three).
+      def validate_cause!
+        cause_values = snapshot.values_at(:error_cause_class, :error_cause_family, :error_cause_message)
+        return if cause_values.all?(&:nil?)
+
+        reject!("persisted workflow failure cause is incomplete") if cause_values.any?(&:nil?)
+        return if KNOWN_FAMILIES.include?(snapshot[:error_cause_family])
+
+        reject!("persisted workflow failure cause family is invalid")
+      end
+
+      def validate_details!
+        validator = DETAIL_VALIDATORS[snapshot[:error_class]]
+        validator&.call(snapshot[:error_details])
+      end
+
+      def reject!(message) = raise(Smith::PersistedFailureInvalid, message)
+    end
+  end
+end

data/lib/smith/workflow/fanout_execution.rb

@@ -1,12 +1,20 @@
 # frozen_string_literal: true
 
-require_relative "branch_env"
-
 module Smith
   class Workflow
     module FanoutExecution
       private
 
+      def fanout_branch_environment(branches, branch_agent_classes, prepared_input)
+        BranchEnv.new(
+          prepared_input:,
+          guardrail_sources: nil,
+          scoped_store: propagate_scoped_artifacts,
+          branch_estimates: fanout_branch_estimates(branches, branch_agent_classes),
+          deadline: wall_clock_deadline
+        )
+      end
+
       def run_guarded_fanout_step(transition)
         branches = transition.fanout_config.fetch(:branches)
         branch_agent_classes = fanout_agent_classes(transition, branches)
@@ -26,13 +34,7 @@ module Smith
       def execute_fanout_step(transition, branches: nil, branch_agent_classes: nil, prepared_input: nil)
         branches ||= transition.fanout_config.fetch(:branches)
         branch_agent_classes ||= fanout_agent_classes(transition, branches)
-        env = BranchEnv.new(
-          prepared_input: prepared_input,
-          guardrail_sources: nil,
-          scoped_store: propagate_scoped_artifacts,
-          branch_estimates: fanout_branch_estimates(branches, branch_agent_classes),
-          deadline: wall_clock_deadline
-        )
+        env = fanout_branch_environment(branches, branch_agent_classes, prepared_input)
 
         branch_calls = branches.map do |branch_key, agent_name|
           PreparedBranchExecution.instance_method(:prepared_branch).bind_call(
@@ -98,12 +100,11 @@ module Smith
       def fanout_branch_estimates(branches, branch_agent_classes)
         return {} unless @ledger
 
-        branch_count = branches.length
         branches.each_with_object({}) do |(branch_key, _agent_name), map|
           agent_class = branch_agent_classes.fetch(branch_key)
           map[branch_key] = compute_branch_estimates(
             @ledger,
-            branch_count: branch_count,
+            branch_count: branches.length,
             agent_budget: agent_class&.budget
           )
         end

data/lib/smith/workflow/guarded_step_execution.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module GuardedStepExecution
+      private
+
+      def run_guarded_step(transition)
+        tracker = Tool::ExecutionTracker.new
+        previous_tracker = Tool.current_tool_execution_tracker
+
+        Thread.handle_interrupt(Object => :never) do
+          Tool.current_tool_execution_tracker = tracker
+          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 ToolOutcomeUncertain.new(
+              "transition failed after tool execution began; retry could replay an uncertain outcome"
+            ), cause: e
+          ensure
+            Tool.current_tool_execution_tracker = previous_tracker
+          end
+        end
+      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)
+      ensure
+        @resolved_parallel_branch_count = nil
+      end
+    end
+  end
+end

data/lib/smith/workflow/parallel/cancellation_signal.rb

@@ -12,7 +12,7 @@ module Smith
 
         def cancel!(error = nil)
           @mutex.synchronize do
-            @reason ||= error
+            @reason = Parallel.preferred_error([@reason, error])
             @cancelled = true
           end
         end

data/lib/smith/workflow/parallel/root_execution.rb

@@ -73,7 +73,7 @@ module Smith
 
         def resolve(futures)
           fulfilled, values, reasons = Concurrent::Promises.zip(*futures).result
-          raise(@signal.reason || Parallel.preferred_error(reasons)) unless fulfilled
+          raise(Parallel.preferred_error([@signal.reason, *reasons])) unless fulfilled
 
           values
         end

data/lib/smith/workflow/parallel.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../errors"
+require_relative "../tool_capture_failed"
 require_relative "parallel/cancellation"
 require_relative "parallel/cancellation_signal"
 require_relative "parallel/execution_context"
@@ -36,8 +38,22 @@ module Smith
 
       def self.preferred_error(reasons)
         errors = Array(reasons).compact
-        errors.find { |error| !error.is_a?(Cancellation) } || errors.first
+        process_fatal_error(errors) ||
+          notification_failure(errors) ||
+          terminal_execution_error(errors) ||
+          ordinary_error(errors) ||
+          errors.first
       end
+
+      def self.process_fatal_error(errors) = errors.find { !_1.is_a?(StandardError) }
+
+      def self.notification_failure(errors) = errors.find { _1.is_a?(ToolFailureNotificationFailed) }
+
+      def self.terminal_execution_error(errors) = errors.find { Smith::Errors.retry_forbidden?(_1) }
+
+      def self.ordinary_error(errors) = errors.find { !_1.is_a?(Cancellation) }
+
+      private_class_method :process_fatal_error, :notification_failure, :terminal_execution_error, :ordinary_error
     end
   end
 end

data/lib/smith/workflow/persistence.rb

@@ -48,6 +48,10 @@ module Smith
           # cycles so seed_validation can detect when the seed builder
           # has changed in code since this workflow was persisted.
           seed_digest: @seed_digest,
+          # Number of immutable seed messages at the beginning of session
+          # history. Context strategies may preserve this exact prefix while
+          # masking later workflow observations.
+          seed_message_count: @seed_message_count || 0,
           # Step-in-progress idempotency marker. Set true between
           # persist-before-advance and persist-after-advance when the
           # workflow class opts into idempotency_mode :strict. Restore
@@ -76,6 +80,7 @@ module Smith
         @ledger = rebuild_ledger(normalized[:budget_consumed] || {})
         @next_transition_name = normalized[:next_transition_name]
         @session_messages = normalized[:session_messages] || []
+        @seed_message_count = validated_seed_message_count(normalized)
         @total_cost = normalized[:total_cost] || 0.0
         @total_tokens = normalized[:total_tokens] || 0
         @outcome = normalized[:outcome]
@@ -120,6 +125,14 @@ module Smith
               "persisted workflow persistence_version must be a non-negative integer, got #{version.inspect}"
       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
+
+        raise Smith::SerializationError,
+              "persisted workflow seed_message_count must be between 0 and session message count"
+      end
+
       def validate_definition_digest!(normalized)
         stored = normalized[:definition_digest]
         return if stored.nil?
@@ -200,20 +213,11 @@ module Smith
       # values become strings).
       def restore_last_failed_step(normalized)
         raw = normalized[:last_failed_step]
-        return nil unless raw.is_a?(Hash)
-
-        h = raw.transform_keys { |k| k.is_a?(String) ? k.to_sym : k }
-        {
-          transition: normalize_transition_name(h[:transition]),
-          from: normalize_state_name(h[:from]),
-          to: normalize_state_name(h[:to]),
-          error_class: h[:error_class],
-          error_family: h[:error_family],
-          error_message: h[:error_message],
-          error_retryable: h[:error_retryable],
-          error_kind: h[:error_kind]&.to_sym,
-          error_details: h[:error_details]
-        }
+        FailureRecordRestore.new(
+          raw,
+          transition_normalizer: method(:normalize_transition_name),
+          state_normalizer: method(:normalize_state_name)
+        ).call
       end
 
       def restore_core_fields(normalized)
@@ -234,9 +238,9 @@ module Smith
         end
 
         manager = self.class.context_manager
-        if manager && manager.respond_to?(:persist_mode) && manager.persist_mode == :auto
+        if manager.respond_to?(:persist_mode) && manager.persist_mode == :auto
           ctx = normalized[:context]
-          existing = ctx.is_a?(Hash) ? ctx.keys.map { |k| k.to_sym } : []
+          existing = ctx.is_a?(Hash) ? ctx.keys.map(&:to_sym) : []
           seed = manager.persist_auto_seed.map(&:to_sym)
           @persisted_keys = ::Set.new(existing + seed)
         else
@@ -309,6 +313,7 @@ module Smith
 
       def normalize_transition_name(value)
         return if value.nil?
+
         transition = self.class.find_transition(value)
         return transition.name if transition
         return value unless value.is_a?(String)
@@ -416,9 +421,7 @@ module Smith
         manager = self.class.context_manager
         return nil unless manager
 
-        if manager.respond_to?(:persist_mode) && manager.persist_mode == :auto
-          return :auto
-        end
+        return :auto if manager.respond_to?(:persist_mode) && manager.persist_mode == :auto
 
         keys = manager.persist
         keys.empty? ? nil : keys

data/lib/smith/workflow/prepared_branch_execution.rb

@@ -6,13 +6,20 @@ module Smith
       private
 
       def prepared_branch(implementation, *arguments)
+        tool_context = Tool::ScopedContext.capture
         unless @split_step_active_execution_authorization
-          return proc { |signal| __send__(implementation.name, *arguments, signal) }
+          return proc do |signal|
+            Tool::ScopedContext.around(tool_context) do
+              __send__(implementation.name, *arguments, signal)
+            end
+          end
         end
 
         proc do |signal|
           run = proc { implementation.bind_call(self, *arguments, signal) }
-          PreparedBranchExecution.instance_method(:within_prepared_branch_execution).bind_call(self, &run)
+          Tool::ScopedContext.around(tool_context) do
+            PreparedBranchExecution.instance_method(:within_prepared_branch_execution).bind_call(self, &run)
+          end
         end
       end
 

data/lib/smith/workflow/retry_execution.rb

@@ -24,6 +24,7 @@ module Smith
 
       def retry_transition_error?(config, error, attempt)
         return false if attempt >= config.fetch(:attempts)
+        return false if terminal_retry_error?(error)
 
         classes = config.fetch(:error_classes)
         if classes.any?
@@ -33,6 +34,10 @@ module Smith
         end
       end
 
+      def terminal_retry_error?(error)
+        Smith::Errors.retry_forbidden?(error)
+      end
+
       def sleep_for_retry(schedule, failed_attempt)
         delay = retry_delay(schedule, failed_attempt)
         sleep(delay) if delay.positive?

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

@@ -68,18 +68,27 @@ module Smith
         def composite_branch_environment(execution, input, agent_class, transition)
           branch = execution.branch
           budget = branch.budget.transform_keys(&:to_sym)
-          branch_key = fetch_composite_fanout_branch(transition, branch.key).first unless execution.kind == :parallel
-          estimates = execution.kind == :parallel ? budget : { branch_key => budget }
           BranchEnv.new(
             prepared_input: input.agent_messages,
             guardrail_sources: Tool.current_guardrails,
             scoped_store: propagate_scoped_artifacts,
-            branch_estimates: estimates,
+            branch_estimates: composite_branch_estimates(execution, transition, budget),
             deadline: wall_clock_deadline,
-            agent_class: execution.kind == :parallel ? agent_class : nil
+            agent_class: composite_parallel_agent(execution, agent_class)
           )
         end
 
+        def composite_branch_estimates(execution, transition, budget)
+          return budget if execution.kind == :parallel
+
+          branch_key = fetch_composite_fanout_branch(transition, execution.branch.key).first
+          { branch_key => budget }
+        end
+
+        def composite_parallel_agent(execution, agent_class)
+          agent_class if execution.kind == :parallel
+        end
+
         def composite_branch_ledger(branch)
           return if branch.budget.empty?
 

data/lib/smith/workflow/thread_context_snapshot.rb

@@ -15,7 +15,11 @@ module Smith
         current_deadline
         current_ledger
         current_tool_call_allowance
+        current_tool_execution_tracker
         current_tool_result_collector
+        current_invocation_context
+        current_invocation_sequence
+        current_invocation
       ].freeze
       THREAD_KEYS = %i[
         smith_call_deadline
@@ -67,14 +71,14 @@ module Smith
       def restore_context!
         raise WorkflowError, "thread context snapshot has already been restored" if @restored
 
-        @tool_values.each { |attribute, value| Tool.public_send("#{attribute}=", value) }
+        @tool_values.each { |attribute, value| Tool.send("#{attribute}=", value) }
         @thread_values.each { |key, value| Thread.current[key] = value }
         Smith.scoped_artifacts = @artifact_store if scoped_artifacts
         @restored = true
       end
 
       def capture_tool_values
-        tool_attributes.to_h { |attribute| [attribute, Tool.public_send(attribute)] }.freeze
+        tool_attributes.to_h { |attribute| [attribute, Tool.send(attribute)] }.freeze
       end
 
       def capture_thread_values

data/lib/smith/workflow/transition.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../tool_capture_failed"
+
 module Smith
   class Workflow
     class Transition
@@ -334,6 +336,7 @@ module Smith
 
           raise WorkflowError, "retry_on error classes must inherit from StandardError"
         end
+        reject_retry_forbidden!(error_classes)
 
         ExponentialBackoff.new(
           attempts:,
@@ -346,6 +349,14 @@ module Smith
         raise WorkflowError, "retry_on #{e.message}"
       end
 
+      def reject_retry_forbidden!(error_classes)
+        forbidden = error_classes.find { |error_class| Smith::Errors.retry_forbidden_class?(error_class) }
+        return unless forbidden
+
+        label = forbidden.name || "an anonymous terminal tool-evidence error class"
+        raise WorkflowError, "retry_on cannot retry #{label} because the tool outcome may be uncertain"
+      end
+
       def normalize_deterministic_routes!(routes)
         return nil if routes.nil?
         raise WorkflowError, "deterministic routes must be an Array" unless routes.is_a?(Array)

data/lib/smith/workflow/usage_entry.rb

@@ -10,6 +10,7 @@ module Smith
       :usage_id,
       :agent_name,
       :model,
+      :provider,
       :input_tokens,
       :output_tokens,
       :cost,
@@ -17,11 +18,20 @@ module Smith
       :recorded_at,
       keyword_init: true
     ) do
+      def initialize(**attributes)
+        attributes = attributes.transform_values do |value|
+          value.is_a?(String) ? value.dup.freeze : value
+        end
+        super(**attributes) # rubocop:disable Style/SuperArguments
+        freeze
+      end
+
       def self.from_h(hash)
         sym = hash.transform_keys(&:to_sym)
         filtered = sym.slice(*members)
-        filtered[:agent_name] = filtered[:agent_name].to_sym if filtered[:agent_name].is_a?(String)
-        filtered[:attempt_kind] = filtered[:attempt_kind].to_sym if filtered[:attempt_kind].is_a?(String)
+        %i[agent_name provider attempt_kind].each do |attribute|
+          filtered[attribute] = filtered[attribute].to_sym if filtered[attribute].is_a?(String)
+        end
         new(**filtered)
       end
     end