smith-agents 0.4.3 → 0.4.5

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

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      module Execution
+        def execute_prepared_step!
+          execution_started = false
+          step = nil
+          claim_split_step_execution_verification!
+          begin
+            verify_split_step_preparation_available!
+            activate_split_step_execution!
+            execution_started = true
+            step = execute_claimed_split_step_transition!
+          ensure
+            execution_started ? finish_split_step_execution!(step) : restore_unverified_execution!
+          end
+          step
+        end
+
+        def prepared_persisted_step? = @split_step_mutex.synchronize { @split_step_phase == :prepared }
+
+        private
+
+        def claim_split_step_execution_verification!
+          @split_step_mutex.synchronize do
+            raise WorkflowError, "no persisted step is prepared" unless @split_step_phase == :prepared
+            raise WorkflowError, "the prepared transition no longer matches the workflow" unless
+              prepared_split_step_transition_matches?
+
+            @split_step_phase = :verifying_execution
+          end
+        end
+
+        def prepared_split_step_transition_matches?
+          transition = pending_split_step_transition
+          transition_name = @next_transition_name || transition&.name
+          transition_name == @split_step_transition_name &&
+            transition.equal?(@split_step_transition) &&
+            split_step_transition_signature(transition) == @split_step_transition_signature
+        end
+
+        def activate_split_step_execution!
+          @split_step_mutex.synchronize do
+            unless @split_step_phase == :verifying_execution
+              raise WorkflowError, "the prepared execution claim is no longer active"
+            end
+
+            @split_step_phase = :executing
+            @split_step_execution_thread = Thread.current
+            @split_step_advance_permit = true
+          end
+        end
+
+        def restore_unverified_execution!
+          @split_step_mutex.synchronize do
+            @split_step_phase = :prepared if @split_step_phase == :verifying_execution
+          end
+        end
+
+        def verify_split_step_preparation_available!
+          payload = @split_step_adapter.fetch(@split_step_persistence_key)
+          durable = persisted_split_step_payload?(payload, @split_step_preparation_payload)
+          live = persisted_split_step_payload?(current_split_step_preparation_payload, @split_step_preparation_payload)
+          stable = split_step_transition_signature(@split_step_transition) == @split_step_transition_signature
+          return if durable && live && stable
+
+          raise WorkflowError, "the persisted split-step preparation is no longer available"
+        end
+
+        def current_split_step_preparation_payload
+          split_step_preparation_payload(
+            JSON.generate(to_state.merge(persistence_version: @persistence_version))
+          )
+        end
+
+        def execute_claimed_split_step_transition!
+          step = Workflow.instance_method(:advance!).bind_call(self)
+          return step if accepted_split_step_result?(step)
+
+          raise WorkflowError, "prepared execution did not return the claimed transition"
+        end
+
+        def finish_split_step_execution!(step)
+          @split_step_mutex.synchronize do
+            @split_step_execution_thread = nil
+            @split_step_advance_permit = false
+            @split_step_phase = step ? :executed : :attempted
+          end
+        end
+
+        def resolve_split_step_advance_transition
+          @split_step_mutex.synchronize do
+            unless @split_step_phase == :executing && @split_step_execution_thread.equal?(Thread.current)
+              return NO_SPLIT_TRANSITION
+            end
+
+            name = @next_transition_name
+            @next_transition_name = nil if name
+            raise UnresolvedTransitionError.new(name, self.class, @state) if name && @split_step_transition.nil?
+
+            @split_step_transition
+          end
+        end
+
+        def accepted_split_step_result?(step)
+          return false unless step.is_a?(Hash)
+          return false unless step[:transition] == @split_step_transition_name
+          return false unless step[:from] == @split_step_origin_state
+
+          step[:error] ? accepted_split_step_failure? : step.key?(:to) && @state == step[:to]
+        end
+
+        def accepted_split_step_failure?
+          failure_name = @split_step_transition&.failure_transition || :fail
+          failure_transition = self.class.find_transition(failure_name)
+          return false unless failure_transition
+
+          @state == failure_transition.to ||
+            (@state == @split_step_origin_state && @next_transition_name == failure_name)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      module Inheritance
+        def inherited(subclass)
+          super
+          subclass.prepend(SubclassBoundary)
+        end
+
+        def prepend(*features)
+          result = super
+          Module.instance_method(:prepend).bind_call(self, SubclassBoundary.guard)
+          result
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      module Payloads
+        private
+
+        def persisted_split_step_payload?(payload, expected)
+          return false unless payload
+
+          JSON.parse(payload) == JSON.parse(expected)
+        rescue JSON::ParserError, TypeError
+          false
+        end
+
+        def persisted_split_step_checkpoint?(payload)
+          return false unless payload && @split_step_checkpoint_digest
+
+          @split_step_checkpoint_digest == Digest::SHA256.hexdigest(payload)
+        end
+
+        def validate_split_step_marker!(payload, expected:)
+          marker = JSON.parse(payload).fetch("step_in_progress")
+          return if marker == expected
+
+          raise WorkflowError, "split-step persistence serialized an invalid step_in_progress marker"
+        rescue JSON::ParserError, KeyError, TypeError
+          raise WorkflowError, "split-step persistence requires an explicit step_in_progress marker"
+        end
+
+        def split_step_checkpoint_payload(payload)
+          document = JSON.parse(payload)
+          document["step_in_progress"] = false
+          JSON.generate(document)
+        end
+
+        def split_step_preparation_payload(payload)
+          document = JSON.parse(payload)
+          document["split_step_token"] = @split_step_token
+          JSON.generate(document)
+        end
+
+        def split_step_transition_signature(transition)
+          transition && TransitionContract.signature(transition)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      module Preparation
+        def prepare_persisted_step!(key = nil, adapter: Smith.persistence_adapter)
+          ensure_strict_split_step_persistence!
+          intent_claimed = claim_split_step_preparation_intent!
+          return unless intent_claimed
+
+          preparation_finalized = false
+          prepare_claimed_persisted_step!(key, adapter)
+          preparation_finalized = true
+          persist_claimed_split_step_preparation!(@split_step_persistence_key, @split_step_adapter)
+          @split_step_transition_name
+        ensure
+          release_split_step_preparation_intent! if intent_claimed && !preparation_finalized
+        end
+
+        def confirm_prepared_step!
+          confirmation_claimed = false
+          claim_split_step_confirmation!
+          confirmation_claimed = true
+          confirmed = false
+          payload = @split_step_adapter.fetch(@split_step_persistence_key)
+          raise WorkflowError, "the persisted split-step preparation is not committed" unless
+            persisted_split_step_payload?(payload, @split_step_preparation_payload)
+
+          @split_step_mutex.synchronize { @split_step_phase = :prepared }
+          confirmed = true
+          self
+        ensure
+          restore_unconfirmed_preparation! if confirmation_claimed && !confirmed
+        end
+
+        private
+
+        def ensure_strict_split_step_persistence!
+          return if strict_idempotency?
+
+          raise WorkflowError, "split-step persistence requires idempotency_mode :strict"
+        end
+
+        def prepare_claimed_persisted_step!(key, adapter)
+          transition = pending_split_step_transition
+          transition_name = @next_transition_name || transition&.name
+          raise WorkflowError, "workflow has no pending transition" unless transition_name
+
+          ensure_transition_budget!
+          resolved_key = normalize_split_step_persistence_key(candidate_split_step_persistence_key(key))
+          store = persistence_adapter!(adapter)
+          persistence_ttl = validate_split_step_adapter!(store)
+          finalize_split_step_preparation!(transition, transition_name, resolved_key, store, persistence_ttl)
+        end
+
+        def pending_split_step_transition
+          transition = if @next_transition_name
+                         self.class.find_transition(@next_transition_name)
+                       else
+                         self.class.transitions_from(@state).first
+                       end
+          validate_transition_origin!(transition) if transition
+          transition
+        end
+
+        def candidate_split_step_persistence_key(key)
+          return key unless key.nil? || blank_key?(key)
+          return @persistence_key unless blank_key?(@persistence_key)
+
+          self.class.send(:resolve_persistence_key!, key:, context: @context)
+        end
+
+        def normalize_split_step_persistence_key(key) = key.to_s.dup.freeze
+
+        def validate_split_step_adapter!(adapter)
+          unless Smith::PersistenceAdapters.supports?(adapter, :store_versioned)
+            raise WorkflowError, "split-step persistence requires an adapter with store_versioned"
+          end
+
+          unless split_step_adapter_accepts_explicit_ttl?(adapter)
+            raise WorkflowError, "split-step persistence requires store_versioned to accept ttl:"
+          end
+          return unless effective_persistence_ttl
+
+          raise WorkflowError, "split-step persistence requires non-expiring workflow persistence"
+        end
+
+        def split_step_adapter_accepts_explicit_ttl?(adapter)
+          adapter.method(:store_versioned).parameters.any? do |kind, name|
+            kind == :keyrest || (%i[key keyreq].include?(kind) && name == :ttl)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      module PreparationClaim
+        private
+
+        def claim_split_step_preparation_intent!
+          @split_step_mutex.synchronize do
+            ensure_no_split_step_boundary!
+            return false if terminal?
+
+            @split_step_phase = :claiming_preparation
+            @split_step_preparation_thread = Thread.current
+            true
+          end
+        end
+
+        def release_split_step_preparation_intent!
+          @split_step_mutex.synchronize do
+            next unless @split_step_phase == :claiming_preparation
+            next unless @split_step_preparation_thread.equal?(Thread.current)
+
+            @split_step_phase = nil
+            @split_step_preparation_thread = nil
+          end
+        end
+
+        def finalize_split_step_preparation!(transition, transition_name, key, adapter, persistence_ttl)
+          transition_signature = TransitionContract.capture(transition)
+          @split_step_mutex.synchronize do
+            unless active_split_step_preparation_claim?
+              raise WorkflowError, "the split-step preparation claim is no longer active"
+            end
+
+            @split_step_phase = :preparing
+            @split_step_transition_name = transition_name
+            @split_step_transition = transition
+            @split_step_transition_signature = transition_signature
+            @split_step_origin_state = @state
+            @split_step_token = SecureRandom.uuid.freeze
+            detach_split_step_execution_state!
+            @split_step_persistence_key = key
+            @split_step_adapter = adapter
+            @split_step_persistence_ttl = persistence_ttl
+            @persistence_key = key
+            @split_step_persist_permit = true
+          end
+        end
+
+        def active_split_step_preparation_claim?
+          @split_step_phase == :claiming_preparation &&
+            @split_step_preparation_thread.equal?(Thread.current)
+        end
+
+        def mark_split_step_prepared!(adapter)
+          @split_step_mutex.synchronize do
+            @split_step_phase = if Smith::PersistenceAdapters.supports?(adapter, :transaction_open?) &&
+                                   adapter.transaction_open?
+                                  :prepared_uncommitted
+                                else
+                                  :prepared
+                                end
+            @split_step_preparation_thread = nil
+            @split_step_persist_permit = false
+          end
+        end
+
+        def claim_split_step_confirmation!
+          @split_step_mutex.synchronize do
+            unless @split_step_phase == :prepared_uncommitted
+              raise WorkflowError, "no uncommitted split-step preparation is awaiting confirmation"
+            end
+            if @split_step_adapter.transaction_open?
+              raise WorkflowError, "the split-step preparation transaction is still open"
+            end
+
+            @split_step_phase = :confirming_preparation
+          end
+        end
+
+        def restore_unconfirmed_preparation!
+          @split_step_mutex.synchronize do
+            @split_step_phase = :prepared_uncommitted if @split_step_phase == :confirming_preparation
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      module PreparationRecovery
+        private
+
+        def persist_claimed_split_step_preparation!(resolved_key, store)
+          persist!(resolved_key, adapter: store)
+          mark_split_step_prepared!(store)
+        rescue PersistenceVersionConflict
+          handle_split_step_preparation_conflict!
+          raise
+        rescue StandardError
+          mark_split_step_preparation_unknown!
+          raise
+        end
+
+        def reset_failed_split_step_preparation!
+          return unless @split_step_phase == :preparing
+
+          clear_step_in_progress!
+          clear_split_step_boundary!
+        end
+
+        def handle_split_step_preparation_conflict!
+          payload = @split_step_adapter.fetch(@split_step_persistence_key)
+          if persisted_split_step_payload?(payload, @split_step_preparation_payload)
+            mark_split_step_preparation_unknown!
+          else
+            reset_failed_split_step_preparation!
+          end
+        rescue StandardError
+          mark_split_step_preparation_unknown!
+        end
+
+        def mark_split_step_preparation_unknown!
+          @split_step_mutex.synchronize do
+            @split_step_phase = :preparation_unknown if @split_step_phase == :preparing
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      module StateSnapshot
+        def to_state
+          state = super
+          return state unless split_step_boundary_active?
+
+          snapshot_value(state)
+        end
+
+        def session_messages
+          return super unless split_step_boundary_active?
+
+          snapshot_session_messages
+        end
+
+        def ledger
+          return super unless split_step_boundary_active?
+          return unless @ledger
+
+          snapshot_split_step_ledger
+        end
+
+        private
+
+        def effective_persistence_ttl
+          return super unless split_step_boundary_active?
+          return super unless instance_variable_defined?(:@split_step_persistence_ttl)
+
+          @split_step_persistence_ttl
+        end
+
+        def ttl_kwarg(ttl)
+          return super unless split_step_boundary_active?
+          return super unless instance_variable_defined?(:@split_step_persistence_ttl)
+
+          { ttl: ttl }
+        end
+
+        def detach_split_step_execution_state!
+          detach_split_step_collections!
+          detach_split_step_results!
+          detach_split_step_metadata!
+          @ledger = snapshot_split_step_ledger if @ledger
+        end
+
+        def detach_split_step_collections!
+          @context = snapshot_context
+          @session_messages = snapshot_session_messages
+          @tool_results = snapshot_tool_results
+          @outcome = snapshot_outcome
+          @usage_entries = snapshot_usage_entries
+          @persisted_keys = Set.new(snapshot_value((@persisted_keys || Set.new).to_a))
+        end
+
+        def detach_split_step_results!
+          @last_output = snapshot_value(@last_output)
+          @last_failed_step = snapshot_value(@last_failed_step)
+          @last_prepared_input = snapshot_value(@last_prepared_input)
+        end
+
+        def detach_split_step_metadata!
+          @created_at = snapshot_value(@created_at)
+          @updated_at = snapshot_value(@updated_at)
+          @execution_namespace = snapshot_value(@execution_namespace)
+          @seed_digest = snapshot_value(@seed_digest)
+          @router_next_transition = snapshot_value(@router_next_transition)
+        end
+
+        def snapshot_split_step_ledger
+          Budget::Ledger.new(
+            limits: snapshot_value(@ledger.limits),
+            consumed: snapshot_value(@ledger.consumed)
+          )
+        end
+
+        def split_step_boundary_active? = !@split_step_phase.nil?
+      end
+    end
+  end
+end

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

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      module SubclassBoundary
+        def self.guard
+          Module.new.tap do |guard|
+            instance_methods(false).each do |method_name|
+              guard.define_method(method_name, instance_method(method_name))
+            end
+            private_instance_methods(false).each do |method_name|
+              guard.define_method(method_name, instance_method(method_name))
+              guard.send(:private, method_name)
+            end
+          end
+        end
+
+        def to_state
+          state = super
+          split_step_boundary_active? ? snapshot_value(state) : state
+        end
+
+        def advance!
+          SplitStepPersistence.instance_method(:guard_split_step_subclass_execution!).bind_call(self)
+          super
+        end
+
+        def run!
+          SplitStepPersistence.instance_method(:guard_split_step_subclass_execution!).bind_call(self)
+          super
+        end
+
+        private
+
+        def effective_persistence_ttl
+          return super unless split_step_boundary_active?
+          return super unless instance_variable_defined?(:@split_step_persistence_ttl)
+
+          @split_step_persistence_ttl
+        end
+
+        def ttl_kwarg(ttl)
+          return super unless split_step_boundary_active?
+          return super unless instance_variable_defined?(:@split_step_persistence_ttl)
+
+          { ttl: ttl }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      class TransitionContract
+        extend Dry::Initializer
+
+        MAX_DEPTH = 128
+        MAX_NODES = 10_000
+        MAX_BYTES = 4 * 1024 * 1024
+
+        param :transition
+
+        def self.capture(transition) = new(transition).capture
+        def self.signature(transition) = new(transition).signature
+
+        def capture
+          captured = signature
+          freeze_value(transition)
+          freeze_value(captured)
+          captured
+        end
+
+        def signature
+          TransitionContractSignature.new(
+            value: transition,
+            max_depth: MAX_DEPTH,
+            max_nodes: MAX_NODES,
+            max_bytes: MAX_BYTES
+          ).call
+        end
+
+        private
+
+        def freeze_value(value)
+          TransitionContractFreezer.new(
+            value: value,
+            max_depth: MAX_DEPTH,
+            max_nodes: MAX_NODES
+          ).call
+        end
+      end
+    end
+  end
+end