smith-agents 0.7.0 → 0.8.0

data/lib/smith/workflow/failure_record_restore.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+require "json"
+
+require_relative "../diagnostic_text"
+require_relative "../errors"
+require_relative "failure_record_text"
+require_relative "failure_record_validator"
+require_relative "message_value_normalizer"
+
+module Smith
+  class Workflow
+    class FailureRecordRestore
+      ATTRIBUTE_NAMES = %i[
+        transition from to error_class error_family error_message error_retryable error_retry_forbidden
+        error_kind error_details error_cause_class error_cause_family error_cause_message
+      ].freeze
+      OPTIONAL_NAMES = %i[error_retry_forbidden error_cause_class error_cause_family error_cause_message].freeze
+      REQUIRED_NAMES = (ATTRIBUTE_NAMES - OPTIONAL_NAMES).freeze
+      ATTRIBUTE_KEYS = ATTRIBUTE_NAMES.to_h { |name| [name.to_s, name] }.freeze
+      MODULE_MATCH = Module.instance_method(:===)
+      HASH_EACH_PAIR = Hash.instance_method(:each_pair)
+      private_constant :ATTRIBUTE_NAMES, :OPTIONAL_NAMES, :REQUIRED_NAMES, :ATTRIBUTE_KEYS, :MODULE_MATCH,
+                       :HASH_EACH_PAIR
+
+      extend Dry::Initializer
+
+      param :raw
+      option :transition_normalizer
+      option :state_normalizer
+
+      def call
+        return if raw.nil?
+
+        reject!("persisted workflow failure record must be a Hash") unless MODULE_MATCH.bind_call(Hash, raw)
+
+        values = attributes
+        FailureRecordValidator.new(restored_record(values)).call
+      end
+
+      private
+
+      def restored_record(values)
+        identity_attributes(values).merge(error_attributes(values)).freeze
+      end
+
+      def identity_attributes(values)
+        {
+          transition: normalize_identifier(values.fetch(:transition), transition_normalizer, "transition"),
+          from: normalize_identifier(values.fetch(:from), state_normalizer, "from state"),
+          to: normalize_identifier(values.fetch(:to), state_normalizer, "to state")
+        }
+      end
+
+      def error_attributes(values)
+        {
+          error_class: bounded_string(values.fetch(:error_class), 512, "class"),
+          error_family: bounded_string(values.fetch(:error_family), 64, "family"),
+          error_message: message_string(values.fetch(:error_message), "message"),
+          error_retryable: boolean_or_nil(values.fetch(:error_retryable), "retryable"),
+          error_retry_forbidden: boolean_or_nil(values[:error_retry_forbidden], "retry policy"),
+          error_kind: normalize_kind(values.fetch(:error_kind)),
+          error_details: normalize_details(values.fetch(:error_details)),
+          **cause_attributes(values)
+        }
+      end
+
+      def cause_attributes(values)
+        {
+          error_cause_class: optional_string(values[:error_cause_class], 512, "cause class"),
+          error_cause_family: optional_string(values[:error_cause_family], 64, "cause family"),
+          error_cause_message: optional_message(values[:error_cause_message], "cause message")
+        }
+      end
+
+      def attributes
+        values = {}
+        HASH_EACH_PAIR.bind_call(raw) do |key, value|
+          name = normalize_key(key)
+          reject!("persisted workflow failure record contains a duplicate attribute") if values.key?(name)
+
+          values[name] = value
+        end
+        missing = REQUIRED_NAMES - values.keys
+        reject!("persisted workflow failure record is incomplete") if missing.any?
+        values
+      end
+
+      def normalize_key(key)
+        return key if symbol?(key) && ATTRIBUTE_NAMES.include?(key)
+        return ATTRIBUTE_KEYS.fetch(key) if string?(key) && ATTRIBUTE_KEYS.key?(key)
+
+        reject!("persisted workflow failure record contains an unknown attribute")
+      end
+
+      def normalize_identifier(value, normalizer, label)
+        bounded_string(value, 256, label).then { normalizer.call(_1) }
+      end
+
+      def normalize_kind(value)
+        return if value.nil?
+
+        bounded_string(value, 256, "kind").to_sym
+      end
+
+      def normalize_details(value)
+        return if value.nil?
+
+        snapshot = MessageValueNormalizer.new(value, label: "persisted workflow failure details").call
+        JSON.generate(snapshot)
+        snapshot
+      rescue WorkflowError, JSON::GeneratorError, EncodingError
+        reject!("persisted workflow failure details are invalid")
+      end
+
+      def bounded_string(value, limit, label)
+        FailureRecordText.capture(value, limit:, label:)
+      end
+
+      def optional_string(value, limit, label) = value.nil? ? nil : bounded_string(value, limit, label)
+
+      # Messages restore with capture normalization (placeholder for blank
+      # text, capture-identical truncation for overlong text) because legacy
+      # states persisted them unbounded; length alone never rejects restore.
+      def message_string(value, label)
+        FailureRecordText.capture(value, limit: DiagnosticText::MAX_BYTES, label:, normalize_length: true)
+      end
+
+      def optional_message(value, label) = value.nil? ? nil : message_string(value, label)
+
+      def boolean_or_nil(value, label)
+        return value if value.nil? || value == true || value == false
+
+        reject!("persisted workflow failure #{label} is invalid")
+      end
+
+      def reject!(message) = raise(Smith::PersistedFailureInvalid, message)
+
+      def string?(value) = MODULE_MATCH.bind_call(String, value)
+
+      def symbol?(value) = MODULE_MATCH.bind_call(Symbol, value)
+    end
+  end
+end

data/lib/smith/workflow/failure_record_text.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+require_relative "../diagnostic_text"
+require_relative "../errors"
+
+module Smith
+  class Workflow
+    class FailureRecordText
+      # Deterministic stand-in shared by capture and restore for failure
+      # messages that would otherwise be blank.
+      MISSING_TEXT = "failure message unavailable"
+
+      MODULE_MATCH = Module.instance_method(:===)
+      STRING_BYTESIZE = String.instance_method(:bytesize)
+      STRING_ENCODING = String.instance_method(:encoding)
+      STRING_INITIALIZE_COPY = String.instance_method(:initialize_copy)
+      STRING_VALID_ENCODING = String.instance_method(:valid_encoding?)
+      SYMBOL_TO_S = Symbol.instance_method(:to_s)
+      private_constant :MODULE_MATCH, :STRING_BYTESIZE, :STRING_ENCODING, :STRING_INITIALIZE_COPY,
+                       :STRING_VALID_ENCODING, :SYMBOL_TO_S
+
+      extend Dry::Initializer
+
+      param :value
+      option :limit
+      option :label
+      option :normalize_length, default: proc { false }
+
+      def self.capture(value, limit:, label:, normalize_length: false)
+        new(value, limit:, label:, normalize_length:).call
+      end
+
+      def call
+        text = owned_text
+        validate_encoding!(text)
+        size = STRING_BYTESIZE.bind_call(text)
+        return normalized(text, size) if normalize_length
+        raise PersistedFailureInvalid, "persisted workflow failure #{label} is invalid" unless size.between?(1, limit)
+
+        text.freeze
+      end
+
+      private
+
+      def validate_encoding!(text)
+        valid = STRING_VALID_ENCODING.bind_call(text) && STRING_ENCODING.bind_call(text) == Encoding::UTF_8
+        return if valid
+
+        raise PersistedFailureInvalid, "persisted workflow failure #{label} is invalid"
+      end
+
+      # Message fields mirror capture normalization instead of rejecting on
+      # length: legacy states persisted messages unbounded (and possibly
+      # blank), and failing the whole workflow restore for message length
+      # alone would poison otherwise valid durable state. Blank text takes
+      # the capture placeholder; overlong text truncates exactly like
+      # capture does.
+      def normalized(text, size)
+        return MISSING_TEXT if size.zero?
+        return text.freeze if size <= limit
+
+        DiagnosticText.capture(text, max_bytes: limit)
+      end
+
+      def owned_text
+        return owned_string if string?
+        return SYMBOL_TO_S.bind_call(value) if symbol?
+
+        raise PersistedFailureInvalid, "persisted workflow failure #{label} must be text"
+      end
+
+      def owned_string
+        String.allocate.tap { STRING_INITIALIZE_COPY.bind_call(_1, value) }
+      end
+
+      def string? = MODULE_MATCH.bind_call(String, value)
+
+      def symbol? = MODULE_MATCH.bind_call(Symbol, value)
+    end
+  end
+end

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/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.rb

@@ -38,11 +38,22 @@ module Smith
 
       def self.preferred_error(reasons)
         errors = Array(reasons).compact
-        errors.find { |error| !error.is_a?(StandardError) } ||
-          errors.find { |error| error.is_a?(ToolCaptureFailed) } ||
-          errors.find { |error| !error.is_a?(Cancellation) } ||
+        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/retry_execution.rb

@@ -24,7 +24,7 @@ module Smith
 
       def retry_transition_error?(config, error, attempt)
         return false if attempt >= config.fetch(:attempts)
-        return false if error.is_a?(ToolCaptureFailed)
+        return false if terminal_retry_error?(error)
 
         classes = config.fetch(:error_classes)
         if classes.any?
@@ -34,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/thread_context_snapshot.rb

@@ -15,8 +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
@@ -68,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

@@ -336,10 +336,7 @@ module Smith
 
           raise WorkflowError, "retry_on error classes must inherit from StandardError"
         end
-        if error_classes.any? { |error_class| error_class <= ToolCaptureFailed }
-          message = "retry_on cannot retry Smith::ToolCaptureFailed because the tool outcome may be uncertain"
-          raise WorkflowError, message
-        end
+        reject_retry_forbidden!(error_classes)
 
         ExponentialBackoff.new(
           attempts:,
@@ -352,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