smith-agents 0.4.4 → 0.5.0

data/lib/smith/errors.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "error"
+
 module Smith
   # Classification surface for host retry policies. Smith owns the
   # answer to "should the workflow attempt be retried?" so consumers
@@ -35,6 +37,7 @@ module Smith
   class DeadlineExceeded < Error; end
   class MaxTransitionsExceeded < Error; end
   class GuardrailFailed < Error; end
+
   class ToolGuardrailFailed < Error
     attr_reader :retryable
 
@@ -43,8 +46,10 @@ module Smith
       super(message)
     end
   end
+
   class ToolPolicyDenied < Error; end
   class AgentError < Error; end
+
   class BlankAgentOutputError < AgentError
     attr_reader :agent_name, :model_used
 
@@ -60,6 +65,7 @@ module Smith
       super(detail)
     end
   end
+
   class WorkflowError < Error; end
 
   class DeterministicStepFailure < WorkflowError

data/lib/smith/exponential_backoff.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Smith
+  class ExponentialBackoff
+    MAX_SLEEP_INTERVAL_SECONDS = 2_147_483_647.0
+    MAX_RANDOM_FACTOR = 1.0.prev_float
+
+    attr_reader :attempts, :base_delay, :max_delay, :jitter
+
+    def initialize(attempts:, base_delay:, max_delay:, jitter:, delay_label: "base_delay")
+      @attempt_limit = Smith.config.retry_attempt_limit
+      @attempts = validate_attempts!(attempts)
+      @base_delay = normalize_delay!(base_delay, delay_label)
+      @max_delay = normalize_optional_delay!(max_delay, "max_delay")
+      @jitter = normalize_delay!(jitter, "jitter")
+      validate_finite_schedule!
+      freeze
+    end
+
+    def delay(failed_attempt, random: Kernel.method(:rand))
+      validate_failed_attempt!(failed_attempt)
+
+      base = exponential_delay(failed_attempt - 1)
+      return base if jitter.zero? || max_delay == base
+
+      add_jitter(base, random.call)
+    end
+
+    private
+
+    def validate_attempts!(value)
+      raise ArgumentError, "attempts must be a positive integer" unless value.is_a?(Integer) && value.positive?
+      raise ArgumentError, "attempts must not exceed #{@attempt_limit}" if value > @attempt_limit
+
+      value
+    end
+
+    def normalize_optional_delay!(value, label)
+      return if value.nil?
+
+      normalize_delay!(value, label)
+    end
+
+    def normalize_delay!(value, label)
+      numeric = Float(value)
+      return numeric if numeric.finite? && numeric >= 0.0
+
+      raise ArgumentError, "#{label} must be finite and non-negative"
+    rescue TypeError, ArgumentError, RangeError
+      raise ArgumentError, "#{label} must be finite and non-negative"
+    end
+
+    def validate_finite_schedule!
+      return if attempts == 1
+
+      largest_delay = maximum_delay(attempts - 2)
+      return if largest_delay <= MAX_SLEEP_INTERVAL_SECONDS
+
+      raise ArgumentError, "retry delay exceeds supported sleep interval #{MAX_SLEEP_INTERVAL_SECONDS.to_i} seconds"
+    end
+
+    def validate_failed_attempt!(failed_attempt)
+      return if failed_attempt.is_a?(Integer) && failed_attempt.positive? && failed_attempt < attempts
+
+      raise ArgumentError, "failed_attempt must identify a retryable attempt"
+    end
+
+    def exponential_delay(exponent)
+      return 0.0 if base_delay.zero? || max_delay&.zero?
+      return uncapped_exponential_delay(exponent) unless max_delay
+
+      capped_exponential_delay(exponent)
+    end
+
+    def capped_exponential_delay(exponent)
+      base_fraction, base_exponent = Math.frexp(base_delay)
+      cap_fraction, cap_exponent = Math.frexp(max_delay)
+      scaled_exponent = base_exponent + exponent
+
+      return max_delay if scaled_exponent > cap_exponent
+      return max_delay if scaled_exponent == cap_exponent && base_fraction >= cap_fraction
+
+      [Math.ldexp(base_delay, exponent), max_delay].min
+    end
+
+    def uncapped_exponential_delay(exponent)
+      _fraction, base_exponent = Math.frexp(base_delay)
+      if base_exponent + exponent > Float::MAX_EXP
+        raise ArgumentError, "retry schedule exceeds the finite numeric range"
+      end
+
+      Math.ldexp(base_delay, exponent).tap do |value|
+        raise ArgumentError, "retry schedule exceeds the finite numeric range" unless value.finite?
+      end
+    end
+
+    def add_jitter(base, random_value)
+      factor = normalize_random_factor!(random_value)
+      sampled = jitter * factor
+      return max_delay if max_delay && sampled >= max_delay - base
+
+      base + sampled
+    end
+
+    def normalize_random_factor!(value)
+      factor = Float(value)
+      unless factor.finite? && factor >= 0.0 && factor < 1.0
+        raise ArgumentError, "random value must be finite and within 0.0...1.0"
+      end
+
+      factor
+    rescue TypeError, ArgumentError, RangeError
+      raise ArgumentError, "random value must be finite and within 0.0...1.0"
+    end
+
+    def maximum_delay(exponent)
+      base = exponential_delay(exponent)
+      return base if jitter.zero? || max_delay == base
+
+      sampled = jitter * MAX_RANDOM_FACTOR
+      return max_delay if max_delay && sampled >= max_delay - base
+
+      (base + sampled).tap do |value|
+        raise ArgumentError, "retry schedule exceeds the finite numeric range" unless value.finite?
+      end
+    end
+  end
+end

data/lib/smith/persistence_adapters/active_record_connection_errors.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Smith
+  module PersistenceAdapters
+    module ActiveRecordConnectionErrors
+      NAMES = %w[
+        ActiveRecord::ConnectionNotEstablished
+        ActiveRecord::ConnectionFailed
+        ActiveRecord::AdapterTimeout
+      ].freeze
+
+      module_function
+
+      def classes
+        NAMES.filter_map do |name|
+          Object.const_get(name)
+        rescue NameError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/smith/persistence_adapters/active_record_exact_predicate.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+module Smith
+  module PersistenceAdapters
+    class ActiveRecordExactPredicate
+      extend Dry::Initializer
+
+      option :model
+      option :column
+
+      def call(scope, expected_payload)
+        scope.where(predicate, expected_payload)
+      end
+
+      private
+
+      def predicate
+        case connection.adapter_name.downcase
+        when /postgres/
+          "convert_to(#{qualified_column}, 'UTF8') = convert_to(?, 'UTF8')"
+        when /sqlite/
+          "CAST(#{qualified_column} AS BLOB) = CAST(? AS BLOB)"
+        when /mysql|trilogy/
+          "BINARY #{qualified_column} = BINARY ?"
+        else
+          raise ArgumentError,
+                "ActiveRecordStore#replace_exact does not support byte-exact payload comparison for " \
+                "#{connection.adapter_name.inspect}"
+        end
+      end
+
+      def qualified_column
+        table = connection.quote_table_name(model.table_name)
+        attribute = connection.quote_column_name(column)
+        "#{table}.#{attribute}"
+      end
+
+      def connection = model.connection
+    end
+  end
+end

data/lib/smith/persistence_adapters/active_record_exact_store.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Smith
+  module PersistenceAdapters
+    module ActiveRecordExactStore
+      attr_reader :persistence_identity
+
+      def replace_exact(key, payload, expected_payload:, ttl: nil) # rubocop:disable Lint/UnusedMethodArgument
+        ensure_version_column!
+        ensure_locking_configuration!
+        model = model_class
+        ensure_exact_schema!(model)
+        ActiveRecordExactWrite.new(
+          model: model,
+          key_column: @key_column,
+          payload_column: @payload_column,
+          version_column: @version_column,
+          key: key,
+          payload: payload,
+          expected_payload: expected_payload
+        ).call
+      rescue *ActiveRecordConnectionErrors.classes => e
+        raise Smith::PersistenceIOError.new(operation: :replace_exact, cause: e)
+      end
+
+      private
+
+      def ensure_exact_schema!(model)
+        ensure_exact_payload_column!(model)
+        ensure_exact_key_uniqueness!(model)
+      end
+
+      def ensure_exact_payload_column!(model)
+        column = model.columns_hash.fetch(@payload_column.to_s)
+        return if %i[string text].include?(column.type)
+
+        raise ArgumentError,
+              "ActiveRecordStore#replace_exact requires a text or string payload column on " \
+              "#{model.table_name}.#{@payload_column}"
+      end
+
+      def ensure_exact_key_uniqueness!(model)
+        connection = model.connection
+        schema_cache = connection.schema_cache
+        table_name = model.table_name
+        key = @key_column.to_s
+        return if schema_cache.primary_keys(table_name).to_s == key
+        return if unconditional_unique_key_index?(schema_cache, table_name, key)
+
+        raise ArgumentError,
+              "ActiveRecordStore#replace_exact requires a unique database index on " \
+              "#{table_name}.#{@key_column}"
+      end
+
+      def unconditional_unique_key_index?(schema_cache, table_name, key)
+        schema_cache.indexes(table_name).any? do |index|
+          index.unique && Array(index.columns).map(&:to_s) == [key] && index.where.to_s.empty?
+        end
+      end
+    end
+  end
+end

data/lib/smith/persistence_adapters/active_record_exact_write.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+require_relative "active_record_exact_predicate"
+
+module Smith
+  module PersistenceAdapters
+    class ActiveRecordExactWrite
+      extend Dry::Initializer
+
+      option :model
+      option :key_column
+      option :payload_column
+      option :version_column
+      option :key
+      option :payload
+      option :expected_payload
+
+      def call
+        updated = exact_scope.update_all(update_attributes)
+        return payload if updated == 1
+
+        raise PersistencePayloadConflict.new(key:)
+      end
+
+      private
+
+      def exact_scope
+        scope = model.where(key_column => key)
+        ActiveRecordExactPredicate.new(model:, column: payload_column).call(scope, expected_payload)
+      end
+
+      def update_attributes
+        lock = model.arel_table[version_column]
+        { payload_column => payload, version_column => lock + 1 }
+      end
+    end
+  end
+end

data/lib/smith/persistence_adapters/active_record_initial_write.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Smith
+  module PersistenceAdapters
+    module ActiveRecordInitialWrite
+      module_function
+
+      def call(model:, key_column:, payload_column:, key:, payload:)
+        candidate = nil
+        record = model.create_or_find_by!(key_column => key) do |new_record|
+          candidate = new_record
+          new_record.public_send(:"#{payload_column}=", payload)
+        end
+
+        created_record?(record, candidate)
+      rescue ::ActiveRecord::RecordInvalid => e
+        raise unless key_collision?(e.record, candidate, model, key_column, key)
+
+        false
+      rescue ::ActiveRecord::RecordNotFound => e
+        raise e.cause if e.cause.is_a?(::ActiveRecord::RecordNotUnique)
+
+        raise
+      end
+
+      def created_record?(record, candidate)
+        return false unless record.equal?(candidate)
+        return true if record.persisted?
+
+        raise ::ActiveRecord::RecordNotSaved, "Active Record rolled back the workflow-state insert"
+      end
+
+      def key_collision?(record, candidate, model, key_column, key)
+        record.equal?(candidate) &&
+          record.errors.of_kind?(key_column, :taken) &&
+          model.exists?(key_column => key)
+      end
+
+      private_class_method :created_record?, :key_collision?
+    end
+  end
+end

data/lib/smith/persistence_adapters/active_record_store.rb

@@ -3,35 +3,24 @@
 module Smith
   module PersistenceAdapters
     class ActiveRecordStore
+      include ActiveRecordExactStore
+
       # AR transient errors resolved via class-name guard so Smith
       # doesn't require activerecord at load time. Hosts that use this
       # adapter already have activerecord in their dep tree.
-      TRANSIENT_ERROR_NAMES = %w[
-        ActiveRecord::ConnectionNotEstablished
-        ActiveRecord::StatementInvalid
-        ActiveRecord::TransactionIsolationConflict
-      ].freeze
-
-      def self.transient_errors
-        TRANSIENT_ERROR_NAMES.filter_map do |name|
-          Object.const_get(name)
-        rescue NameError
-          nil
-        end
-      end
-
-      def initialize(model:, key_column: :key, payload_column: :payload, version_column: :lock_version)
-        @model_source = model
-        @key_column = key_column
-        @payload_column = payload_column
-        @version_column = version_column
+      def initialize(model:, key_column: :key, payload_column: :payload, version_column: :lock_version, identity: nil)
+        @model_source = model.is_a?(String) ? model.dup.freeze : model
+        @key_column = normalize_column(key_column)
+        @payload_column = normalize_column(payload_column)
+        @version_column = normalize_column(version_column)
+        @persistence_identity = identity.to_s.dup.freeze if identity
       end
 
       def store(key, payload, ttl: nil) # rubocop:disable Lint/UnusedMethodArgument
         # TTL is deferred for ActiveRecordStore — would require an
         # `expires_at` column + a periodic sweeper job. Ignored here;
         # documented as a known limitation.
-        Retry.with_retries(operation: :store, transient: self.class.transient_errors) do
+        Retry.with_retries(operation: :store, transient: ActiveRecordConnectionErrors.classes) do
           record = model_class.find_or_initialize_by(@key_column => key)
           record.public_send(:"#{@payload_column}=", payload)
           record.save!
@@ -39,60 +28,114 @@ module Smith
       end
 
       def fetch(key)
-        Retry.with_retries(operation: :fetch, transient: self.class.transient_errors) do
+        Retry.with_retries(operation: :fetch, transient: ActiveRecordConnectionErrors.classes) do
           model_class.find_by(@key_column => key)&.public_send(@payload_column)
         end
       end
 
       def delete(key)
-        Retry.with_retries(operation: :delete, transient: self.class.transient_errors) do
+        Retry.with_retries(operation: :delete, transient: ActiveRecordConnectionErrors.classes) do
           model_class.where(@key_column => key).delete_all
         end
       end
 
+      def transaction_open? = model_class.connection.transaction_open?
+
+      def transaction_identity = model_class.respond_to?(:current_transaction) && model_class.current_transaction.uuid
+
       # Optimistic locking via Rails' built-in optimistic locking on the
       # `lock_version` column. Requires the AR model to have a
       # `lock_version` (or configured) integer column with default 0.
       # If absent, raises ArgumentError directing the host to migrate.
       def store_versioned(key, payload, expected_version:, ttl: nil) # rubocop:disable Lint/UnusedMethodArgument
-        unless model_class.column_names.include?(@version_column.to_s)
-          raise ArgumentError,
-                "ActiveRecordStore#store_versioned requires a #{@version_column} column on " \
-                "#{model_class.name}. Add via: " \
-                "add_column :#{model_class.table_name}, :#{@version_column}, :integer, default: 0"
-        end
+        ensure_version_column!
+        ensure_locking_configuration!
 
-        Retry.with_retries(operation: :store_versioned, transient: self.class.transient_errors) do
-          record = model_class.find_or_initialize_by(@key_column => key)
-          if record.persisted? && record.public_send(@version_column) != expected_version
-            raise Smith::PersistenceVersionConflict.new(
-              key: key, expected: expected_version, actual: record.public_send(@version_column)
-            )
-          end
-          record.public_send(:"#{@payload_column}=", payload)
-          record.save!
-        rescue defined?(::ActiveRecord::StaleObjectError) ? ::ActiveRecord::StaleObjectError : StandardError => e
-          raise unless defined?(::ActiveRecord::StaleObjectError) && e.is_a?(::ActiveRecord::StaleObjectError)
+        write_versioned(key, payload, expected_version)
+      rescue *ActiveRecordConnectionErrors.classes => e
+        raise Smith::PersistenceIOError.new(operation: :store_versioned, cause: e)
+      end
+
+      private
+
+      def normalize_column(column)
+        column.is_a?(String) ? column.dup.freeze : column
+      end
+
+      def ensure_version_column!
+        return if model_class.column_names.include?(@version_column.to_s)
 
-          raise Smith::PersistenceVersionConflict.new(
-            key: key, expected: expected_version, actual: :concurrent
-          )
+        raise ArgumentError,
+              "ActiveRecordStore#store_versioned requires a #{@version_column} column on " \
+              "#{model_class.name}. Add via: " \
+              "add_column :#{model_class.table_name}, :#{@version_column}, :integer, default: 0"
+      end
+
+      def ensure_locking_configuration!
+        locking_column = model_class.locking_column if model_class.respond_to?(:locking_column)
+        locking_enabled = model_class.locking_enabled? if model_class.respond_to?(:locking_enabled?)
+        return if locking_enabled && locking_column.to_s == @version_column.to_s
+
+        raise ArgumentError,
+              "ActiveRecordStore#store_versioned requires #{model_class.name}.locking_column " \
+              "to be #{@version_column.inspect} with optimistic locking enabled"
+      end
+
+      def write_versioned(key, payload, expected_version)
+        record = model_class.find_by(@key_column => key)
+        unless record
+          VersionExpectation.validate_missing!(key, expected_version)
+          return create_versioned_record(key, payload, expected_version)
         end
+
+        validate_payload_version!(record, key, expected_version)
+        record.public_send(:"#{@payload_column}=", payload)
+        record.save!
+      rescue ::ActiveRecord::StaleObjectError => e
+        raise unless e.record.equal?(record)
+
+        raise_concurrent_conflict(key, expected_version)
       end
 
-      private
+      def create_versioned_record(key, payload, expected_version)
+        created = ActiveRecordInitialWrite.call(
+          model: model_class,
+          key_column: @key_column,
+          payload_column: @payload_column,
+          key: key,
+          payload: payload
+        )
+        return true if created
+
+        raise_concurrent_conflict(key, expected_version)
+      end
+
+      def validate_payload_version!(record, key, expected_version)
+        current_version = payload_version(record)
+        return if current_version == expected_version
+
+        raise Smith::PersistenceVersionConflict.new(
+          key: key, expected: expected_version, actual: current_version
+        )
+      end
+
+      def payload_version(record) = PayloadVersion.call(record.public_send(@payload_column))
+
+      def raise_concurrent_conflict(key, expected_version)
+        raise Smith::PersistenceVersionConflict.new(
+          key: key, expected: expected_version, actual: :concurrent
+        )
+      end
 
       def model_class
-        @model_class ||= begin
-          case @model_source
-          when String
-            Object.const_get(@model_source)
-          else
-            @model_source
-          end
-        rescue NameError => e
-          raise ArgumentError, "ActiveRecord model #{@model_source.inspect} could not be resolved: #{e.message}"
+        case @model_source
+        when String
+          Object.const_get(@model_source)
+        else
+          @model_source
         end
+      rescue NameError => e
+        raise ArgumentError, "ActiveRecord model #{@model_source.inspect} could not be resolved: #{e.message}"
       end
     end
   end

data/lib/smith/persistence_adapters/cache_store.rb

@@ -17,7 +17,7 @@ module Smith
 
       def initialize(store:, namespace: "smith")
         @store_source = store
-        @namespace = namespace
+        @namespace = namespace.nil? ? nil : namespace.to_s.dup.freeze
       end
 
       def store(key, payload, ttl: Smith.config.persistence_ttl)
@@ -42,6 +42,9 @@ module Smith
         end
       end
 
+      def transaction_open? = false
+      def transaction_identity = nil
+
       def backend_name
         backend.class.name || backend.class.to_s
       end