smith-agents 0.4.5 → 0.6.0

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_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_store.rb

@@ -3,14 +3,17 @@
 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.
-      def initialize(model:, key_column: :key, payload_column: :payload, version_column: :lock_version)
+      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
@@ -36,9 +39,9 @@ module Smith
         end
       end
 
-      def transaction_open?
-        model_class.connection.transaction_open?
-      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

data/lib/smith/persistence_adapters/cache_store.rb

@@ -43,6 +43,7 @@ module Smith
       end
 
       def transaction_open? = false
+      def transaction_identity = nil
 
       def backend_name
         backend.class.name || backend.class.to_s

data/lib/smith/persistence_adapters/memory.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "monitor"
+require "securerandom"
 
 module Smith
   module PersistenceAdapters
@@ -15,7 +16,10 @@ module Smith
     # Smith.config.persistence_adapter is nil AND Smith.config.test_mode
     # is true (typically set in spec_helper.rb).
     class Memory
-      def initialize
+      attr_reader :persistence_identity
+
+      def initialize(identity: "memory:#{SecureRandom.uuid}")
+        @persistence_identity = identity.to_s.dup.freeze
         @store = {}
         @heartbeats = {}
         @monitor = Monitor.new
@@ -44,6 +48,7 @@ module Smith
       end
 
       def transaction_open? = false
+      def transaction_identity = nil
 
       def record_heartbeat(key, ttl: Smith.config.persistence_ttl)
         @monitor.synchronize do
@@ -88,6 +93,16 @@ module Smith
         end
       end
 
+      def replace_exact(key, payload, expected_payload:, ttl: Smith.config.persistence_ttl)
+        @monitor.synchronize do
+          entry = live_entry(key)
+          raise PersistencePayloadConflict.new(key:) unless entry && entry[:payload] == expected_payload
+
+          @store[key] = entry_for(payload, ttl)
+        end
+        payload
+      end
+
       def clear!
         @monitor.synchronize { @store.clear }
       end

data/lib/smith/persistence_adapters/redis_client_access.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Smith
+  module PersistenceAdapters
+    module RedisClientAccess
+      private
+
+      def client
+        return @client if instance_variable_defined?(:@client)
+
+        @client_resolution_mutex.synchronize do
+          return @client if instance_variable_defined?(:@client)
+
+          resolved = redis_client?(@redis_source) ? @redis_source : resolve_redis_source
+          raise ArgumentError, "Redis client is required" unless resolved
+
+          @client = resolved
+        end
+      end
+
+      def resolve_redis_source
+        @redis_source.respond_to?(:call) ? @redis_source.call : @redis_source
+      end
+
+      def redis_client?(candidate)
+        candidate.respond_to?(:get) && candidate.respond_to?(:set) && candidate.respond_to?(:del)
+      end
+
+      def without_reconnection
+        redis = client
+        return redis.without_reconnect { yield redis } if redis.respond_to?(:without_reconnect)
+        return redis.disable_reconnection { yield redis } if redis.respond_to?(:disable_reconnection)
+
+        raise ArgumentError, "Redis client must expose without_reconnect or disable_reconnection for CAS writes"
+      end
+    end
+  end
+end

data/lib/smith/persistence_adapters/redis_exact_write.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+module Smith
+  module PersistenceAdapters
+    class RedisExactWrite
+      extend Dry::Initializer
+
+      option :client
+      option :key
+      option :storage_key
+      option :payload
+      option :expected_payload
+      option :ttl
+
+      def call
+        result = client.watch(storage_key) do
+          validate_current!
+          enqueue_write
+        end
+        return payload unless result.nil?
+
+        raise PersistencePayloadConflict.new(key:)
+      end
+
+      private
+
+      def validate_current!
+        return if client.get(storage_key) == expected_payload
+
+        client.unwatch
+        raise PersistencePayloadConflict.new(key:)
+      end
+
+      def enqueue_write
+        client.multi do |transaction|
+          options = ttl ? { ex: ttl } : {}
+          transaction.set(storage_key, payload, **options)
+        end
+      end
+    end
+  end
+end

data/lib/smith/persistence_adapters/redis_store.rb

@@ -2,9 +2,13 @@
 
 require "time"
 
+require_relative "redis_client_access"
+
 module Smith
   module PersistenceAdapters
     class RedisStore
+      include RedisClientAccess
+
       # Redis transient errors — narrow list; non-transient errors
       # (CommandError, etc.) propagate up immediately. Pattern matches
       # Redis::BaseConnectionError if loaded (covers Connection/Timeout)
@@ -24,9 +28,13 @@ module Smith
         end + [Errno::ECONNREFUSED, Errno::ETIMEDOUT, Errno::EPIPE]
       end
 
-      def initialize(redis:, namespace: "smith")
+      attr_reader :persistence_identity
+
+      def initialize(redis:, namespace: "smith", identity: nil)
         @redis_source = redis
         @namespace = namespace.nil? ? nil : namespace.to_s.dup.freeze
+        @persistence_identity = identity.to_s.dup.freeze if identity
+        @client_resolution_mutex = Mutex.new
       end
 
       def store(key, payload, ttl: Smith.config.persistence_ttl)
@@ -52,6 +60,7 @@ module Smith
       end
 
       def transaction_open? = false
+      def transaction_identity = nil
 
       def record_heartbeat(key, ttl: Smith.config.persistence_ttl)
         Retry.with_retries(operation: :record_heartbeat, transient: self.class.transient_errors) do
@@ -79,9 +88,9 @@ module Smith
       # Smith::PersistenceVersionConflict on a stale expected_version
       # OR on EXEC failure (WATCH detected concurrent write).
       def store_versioned(key, payload, expected_version:, ttl: Smith.config.persistence_ttl)
-        Retry.with_retries(operation: :store_versioned, transient: self.class.transient_errors) do
+        without_reconnection do |redis|
           RedisVersionedWrite.new(
-            client: client,
+            client: redis,
             key: key,
             storage_key: namespaced(key),
             payload: payload,
@@ -89,19 +98,27 @@ module Smith
             ttl: ttl
           ).call
         end
+      rescue *self.class.transient_errors => e
+        raise Smith::PersistenceIOError.new(operation: :store_versioned, cause: e)
       end
 
-      private
-
-      def client
-        @client ||= begin
-          resolved = @redis_source.respond_to?(:call) ? @redis_source.call : @redis_source
-          raise ArgumentError, "Redis client is required" unless resolved
-
-          resolved
+      def replace_exact(key, payload, expected_payload:, ttl: Smith.config.persistence_ttl)
+        without_reconnection do |redis|
+          RedisExactWrite.new(
+            client: redis,
+            key: key,
+            storage_key: namespaced(key),
+            payload: payload,
+            expected_payload: expected_payload,
+            ttl: ttl
+          ).call
         end
+      rescue *self.class.transient_errors => e
+        raise Smith::PersistenceIOError.new(operation: :replace_exact, cause: e)
       end
 
+      private
+
       def namespaced(key)
         [@namespace, key].compact.join(":")
       end

data/lib/smith/persistence_adapters/retry.rb

@@ -16,27 +16,39 @@ module Smith
 
       def with_retries(operation:, transient:, policy: Smith.config.persistence_retry_policy,
                        logger: Smith.config.logger)
-        attempts = policy.fetch(:attempts, 3)
-        base = policy.fetch(:base_delay, 0.1)
-        max_delay = policy.fetch(:max_delay, 1.0)
+        schedule = schedule_for(policy)
         last_error = nil
 
-        attempts.times do |i|
+        schedule.attempts.times do |i|
           return yield
         rescue *transient => e
           last_error = e
-          break if i == attempts - 1
+          break if i == schedule.attempts - 1
 
-          delay = [base * (2**i), max_delay].min
-          logger&.warn(
-            "Smith::PersistenceAdapters::Retry #{operation} attempt #{i + 1}/#{attempts} failed: " \
-            "#{e.class}: #{e.message}; sleeping #{delay}s"
-          )
+          delay = schedule.delay(i + 1)
+          log_retry(logger, operation, e, { attempt: i + 1, attempts: schedule.attempts, delay: })
           sleep(delay)
         end
 
         raise Smith::PersistenceIOError.new(operation: operation, cause: last_error)
       end
+
+      def schedule_for(policy)
+        ExponentialBackoff.new(
+          attempts: policy.fetch(:attempts, 3),
+          base_delay: policy.fetch(:base_delay, 0.1),
+          max_delay: policy.fetch(:max_delay, 1.0),
+          jitter: 0
+        )
+      end
+
+      def log_retry(logger, operation, error, retry_context)
+        logger&.warn(
+          "Smith::PersistenceAdapters::Retry #{operation} " \
+          "attempt #{retry_context.fetch(:attempt)}/#{retry_context.fetch(:attempts)} failed: " \
+          "#{error.class}: #{error.message}; sleeping #{retry_context.fetch(:delay)}s"
+        )
+      end
     end
   end
 end

data/lib/smith/persistence_adapters.rb

@@ -3,11 +3,14 @@
 require "monitor"
 require_relative "persistence_adapters/active_record_connection_errors"
 require_relative "persistence_adapters/active_record_initial_write"
+require_relative "persistence_adapters/active_record_exact_write"
+require_relative "persistence_adapters/active_record_exact_store"
 require_relative "persistence_adapters/payload_version"
 require_relative "persistence_adapters/version_expectation"
 require_relative "persistence_adapters/cache_store"
 require_relative "persistence_adapters/rails_cache"
 require_relative "persistence_adapters/redis_versioned_write"
+require_relative "persistence_adapters/redis_exact_write"
 require_relative "persistence_adapters/redis_store"
 require_relative "persistence_adapters/active_record_store"
 require_relative "persistence_adapters/memory"
@@ -28,7 +31,10 @@ module Smith
     # check support via `supports?(adapter, capability)` and fall back
     # gracefully (e.g., Workflow#persist! warns once and uses plain
     # `store` when `store_versioned` is missing).
-    OPTIONAL_METHODS = %i[store_versioned record_heartbeat last_heartbeat transaction_open?].freeze
+    OPTIONAL_METHODS = %i[
+      store_versioned replace_exact persistence_identity record_heartbeat last_heartbeat
+      transaction_open? transaction_identity
+    ].freeze
 
     def self.resolve(adapter, **options)
       return nil if adapter.nil?
@@ -39,22 +45,7 @@ module Smith
         return validate!(instance)
       end
 
-      built_in = case adapter.to_sym
-                 when :cache_store
-                   CacheStore.new(**options)
-                 when :rails_cache, :solid_cache
-                   RailsCache.new(**options)
-                 when :redis
-                   RedisStore.new(**options)
-                 when :active_record
-                   ActiveRecordStore.new(**options)
-                 when :memory
-                   Memory.new
-                 else
-                   raise ArgumentError, "Unknown persistence adapter #{adapter.inspect}"
-                 end
-
-      validate!(built_in)
+      validate!(build(adapter, options))
     end
 
     def self.adapter_like?(adapter)
@@ -65,9 +56,21 @@ module Smith
       return adapter if adapter_like?(adapter)
 
       missing = REQUIRED_METHODS.reject { |method_name| adapter.respond_to?(method_name) }
-      raise ArgumentError, "Persistence adapter must implement #{missing.join(', ')}"
+      raise ArgumentError, "Persistence adapter must implement #{missing.join(", ")}"
     end
 
+    def self.build(adapter, options)
+      case adapter.to_sym
+      when :cache_store then CacheStore.new(**options)
+      when :rails_cache, :solid_cache then RailsCache.new(**options)
+      when :redis then RedisStore.new(**options)
+      when :active_record then ActiveRecordStore.new(**options)
+      when :memory then Memory.new(**options)
+      else raise ArgumentError, "Unknown persistence adapter #{adapter.inspect}"
+      end
+    end
+    private_class_method :build
+
     # Capability introspection used by Workflow#persist! to decide
     # whether the adapter supports optimistic locking via store_versioned.
     def self.supports?(adapter, capability)

data/lib/smith/persistence_payload_conflict.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Smith
+  class PersistencePayloadConflict < Error
+    attr_reader :key
+
+    def initialize(key:)
+      @key = key
+      super("persisted payload conflict for #{key.inspect}: the exact expected payload is no longer current")
+    end
+  end
+end

data/lib/smith/tool/budget_enforcement.rb

@@ -22,8 +22,8 @@ module Smith
 
       def commit_tool_call_charges!(ledger, allowance, workflow_active)
         if workflow_active
-          ledger.reserve!(:tool_calls, 1)
-          ledger.reconcile!(:tool_calls, 1, 1)
+          reservation = ledger.reserve!(:tool_calls, 1)
+          ledger.reconcile!(reservation, 1)
         end
 
         allowance[:remaining] -= 1 if allowance

data/lib/smith/types.rb

@@ -12,5 +12,6 @@ module Smith
     # the constants we need as direct module constants.
     const_set(:String, const_get(:String))
     const_set(:Integer, const_get(:Integer))
+    const_set(:Sha256Hex, const_get(:String).constrained(format: /\A[0-9a-f]{64}\z/))
   end
 end