smith-agents 0.4.4 → 0.5.0

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,102 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      module SubclassBoundary
+        class << self
+          def protect_execution_path!(workflow_class, *owners)
+            protected_method_names(owners).each do |method_name|
+              protect_method!(workflow_class, method_name)
+            end
+          end
+
+          private
+
+          def protected_method_names(owners)
+            owners.flat_map do |owner|
+              owner.private_instance_methods(false) + owner.protected_instance_methods(false)
+            end.uniq
+          end
+
+          def protect_method!(workflow_class, method_name)
+            return if boundary_method_names.include?(method_name)
+
+            implementation = workflow_class.instance_method(method_name)
+            define_method(method_name) do |*arguments, **keywords, &block|
+              active = SubclassBoundary
+                       .instance_method(:smith_prepared_execution_active?)
+                       .bind_call(self)
+              if active
+                implementation.bind_call(self, *arguments, **keywords, &block)
+              else
+                super(*arguments, **keywords, &block)
+              end
+            end
+            private method_name
+          end
+
+          def boundary_method_names
+            instance_methods(false) + private_instance_methods(false) + protected_instance_methods(false)
+          end
+        end
+
+        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 smith_prepared_execution_active?
+          root_execution = @split_step_phase == :executing &&
+                           @split_step_execution_thread.equal?(Thread.current)
+          return true if root_execution
+
+          authorization = @split_step_active_execution_authorization
+          authorization&.active_in_current_execution? == true
+        end
+
+        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 dispatch_store!(...)
+          DispatchBoundary.instance_method(:dispatch_store!).bind_call(self, ...)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      class TransactionIdentity
+        extend Dry::Initializer
+
+        param :adapter
+
+        def self.capture(adapter) = new(adapter).capture
+        def self.matches?(adapter, expected) = new(adapter).matches?(expected)
+
+        def capture
+          return unless PersistenceAdapters.supports?(adapter, :transaction_open?)
+          return unless adapter.transaction_open?
+
+          ensure_identity_capability!
+          identity = adapter.transaction_identity
+          if !identity || identity.to_s.empty?
+            raise WorkflowError, "transactional split-step persistence requires an active transaction identity"
+          end
+
+          identity.to_s.dup.freeze
+        end
+
+        def matches?(expected)
+          capture == expected
+        rescue StandardError
+          false
+        end
+
+        private
+
+        def ensure_identity_capability!
+          return if PersistenceAdapters.supports?(adapter, :transaction_identity)
+
+          raise WorkflowError, "transactional split-step persistence requires transaction_identity"
+        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

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

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      class TransitionContractFreezer
+        extend Dry::Initializer
+
+        CORE_FREEZE = Object.instance_method(:freeze)
+
+        option :value
+        option :max_depth
+        option :max_nodes
+
+        def call
+          stack = [[value, 0]]
+          seen = {}.compare_by_identity
+          nodes = 0
+          until stack.empty?
+            item, depth = stack.pop
+            nodes = visit!(nodes, depth)
+            freeze_item(item, depth, stack, seen)
+          end
+          value
+        end
+
+        private
+
+        def visit!(nodes, depth)
+          raise WorkflowError, "split-step transition contract exceeds maximum depth #{max_depth}" if depth > max_depth
+          return nodes + 1 if nodes < max_nodes
+
+          raise WorkflowError, "split-step transition contract exceeds maximum size #{max_nodes}"
+        end
+
+        def freeze_item(item, depth, stack, seen)
+          return if immutable?(item) || item.is_a?(Module) || seen.key?(item)
+
+          seen[item] = true
+          children(item).reverse_each { |child| stack << [child, depth + 1] }
+          CORE_FREEZE.bind_call(item)
+        end
+
+        def children(item)
+          return [] if leaf?(item)
+          return item.flat_map { |key, value| [key, value] } if item.is_a?(Hash)
+          return [item.begin, item.end] if item.is_a?(Range)
+
+          object_children(item)
+        end
+
+        def object_children(item)
+          return item.to_a if item.is_a?(Array) || item.is_a?(Set)
+          return member_children(item) if item.is_a?(Struct) || item.is_a?(Data)
+
+          transition_children(item)
+        end
+
+        def member_children(item)
+          item.members.map { |name| item.public_send(name) }
+        end
+
+        def transition_children(item)
+          unless item.is_a?(Workflow::Transition)
+            raise WorkflowError, "split-step transition contract contains unsupported value #{item.class}"
+          end
+
+          item.instance_variables.map { |name| item.instance_variable_get(name) }
+        end
+
+        def leaf?(item)
+          item.is_a?(String) || item.is_a?(Proc)
+        end
+
+        def immutable?(item)
+          item.nil? || item.is_a?(Symbol) || item.is_a?(Numeric) || item == true || item == false
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+require "digest"
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      class TransitionContractSignature
+        extend Dry::Initializer
+        include TransitionContractStructuredValues
+
+        option :value
+        option :max_depth
+        option :max_nodes
+        option :max_bytes
+
+        def call
+          @nodes = 0
+          @bytes = 0
+          @seen = {}.compare_by_identity
+          signature_value(value, 0)
+        end
+
+        private
+
+        def signature_value(item, depth)
+          visit!(depth)
+          reference = reference_for(item)
+          return reference if reference
+          return terminal_signature(item) if terminal?(item)
+
+          composite_signature(item, depth)
+        end
+
+        def composite_signature(item, depth)
+          case item
+          when Hash then hash_signature(item, depth)
+          when Array then collection_signature(:array, item, depth)
+          when Set then collection_signature(:set, item, depth)
+          else structured_signature(item, depth)
+          end
+        end
+
+        def terminal_signature(item)
+          case item
+          when String then string_signature(item)
+          when Module then [:module, item.name, item.object_id]
+          when Proc then proc_signature(item)
+          else item
+          end
+        end
+
+        def hash_signature(hash, depth)
+          [:hash, reference_id(hash), hash.map do |key, item|
+            [signature_value(key, depth + 1), signature_value(item, depth + 1)]
+          end]
+        end
+
+        def collection_signature(kind, collection, depth)
+          [kind, reference_id(collection), collection.map { |item| signature_value(item, depth + 1) }]
+        end
+
+        def proc_signature(callable)
+          [:proc, callable.object_id, callable.source_location, callable.parameters, callable.lambda?]
+        end
+
+        def string_signature(string)
+          @bytes += string.bytesize
+          raise WorkflowError, "split-step transition contract exceeds maximum bytes #{max_bytes}" if @bytes > max_bytes
+
+          [:string, string.bytesize, Digest::SHA256.hexdigest(string)]
+        end
+
+        def reference_for(item)
+          return unless referenceable?(item)
+          return [:reference, reference_id(item)] if @seen.key?(item)
+
+          @seen[item] = @seen.size
+          nil
+        end
+
+        def reference_id(item) = @seen.fetch(item)
+
+        def referenceable?(item)
+          !terminal?(item)
+        end
+
+        def terminal?(item)
+          case item
+          when String, Symbol, Numeric, Module, Proc, true, false, nil then true
+          else false
+          end
+        end
+
+        def visit!(depth)
+          raise WorkflowError, "split-step transition contract exceeds maximum depth #{max_depth}" if depth > max_depth
+
+          @nodes += 1
+          return if @nodes <= max_nodes
+
+          raise WorkflowError, "split-step transition contract exceeds maximum size #{max_nodes}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      module TransitionContractStructuredValues
+        private
+
+        def structured_signature(item, depth)
+          case item
+          when Struct then member_signature(:struct, item, depth)
+          when Data then member_signature(:data, item, depth)
+          when Range then range_signature(item, depth)
+          when Workflow::Transition then object_signature(item, depth)
+          else unsupported!(item)
+          end
+        end
+
+        def member_signature(kind, object, depth)
+          members = object.members.map do |name|
+            [name, signature_value(object.public_send(name), depth + 1)]
+          end
+          [kind, object.class.name, reference_id(object), members]
+        end
+
+        def object_signature(item, depth)
+          variables = item.instance_variables.sort.map do |name|
+            [name, signature_value(item.instance_variable_get(name), depth + 1)]
+          end
+          [:object, item.class.name, item.object_id, variables]
+        end
+
+        def range_signature(range, depth)
+          [
+            :range,
+            reference_id(range),
+            signature_value(range.begin, depth + 1),
+            signature_value(range.end, depth + 1),
+            range.exclude_end?
+          ]
+        end
+
+        def unsupported!(item)
+          raise WorkflowError,
+                "split-step transition contract contains unsupported value #{item.class}; " \
+                "use primitives, Hash, Array, Set, Struct, Data, Range, Module, or Proc"
+        end
+      end
+    end
+  end
+end

data/lib/smith/workflow/split_step_persistence.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+require "securerandom"
+
+require_relative "prepared_step"
+require_relative "prepared_step_dispatch"
+require_relative "prepared_step_execution_authorization"
+require_relative "prepared_step_execution_result"
+require_relative "prepared_step_recovery"
+require_relative "split_step_persistence/subclass_boundary"
+require_relative "split_step_persistence/inheritance"
+require_relative "split_step_persistence/recovery_class_methods"
+require_relative "split_step_persistence/transition_contract_structured_values"
+require_relative "split_step_persistence/transition_contract_signature"
+require_relative "split_step_persistence/transition_contract_freezer"
+require_relative "split_step_persistence/transition_contract"
+require_relative "split_step_persistence/transaction_identity"
+require_relative "split_step_persistence/canonical_payload_digest"
+require_relative "split_step_persistence/definition_boundary"
+require_relative "split_step_persistence/boundary"
+require_relative "split_step_persistence/boundary_reset"
+require_relative "split_step_persistence/state_snapshot"
+require_relative "split_step_persistence/preparation_claim"
+require_relative "split_step_persistence/preparation_recovery"
+require_relative "split_step_persistence/preparation"
+require_relative "split_step_persistence/restart_safe_adapter"
+require_relative "split_step_persistence/recovery"
+require_relative "split_step_persistence/recovery_boundary"
+require_relative "split_step_persistence/preparation_payload"
+require_relative "split_step_persistence/dispatch_boundary"
+require_relative "split_step_persistence/dispatch_claim"
+require_relative "split_step_persistence/dispatch_verification"
+require_relative "split_step_persistence/dispatch_confirmation"
+require_relative "split_step_persistence/execution_verification"
+require_relative "split_step_persistence/execution_binding_snapshot"
+require_relative "split_step_persistence/execution_authorization"
+require_relative "split_step_persistence/execution_result_capture"
+require_relative "split_step_persistence/execution"
+require_relative "split_step_persistence/checkpoint_state"
+require_relative "split_step_persistence/checkpoint"
+require_relative "split_step_persistence/payloads"
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      NO_SPLIT_TRANSITION = Object.new.freeze
+
+      def self.prepended(base)
+        base.singleton_class.prepend(Inheritance)
+        base.extend(RecoveryClassMethods)
+      end
+
+      include Boundary
+      include BoundaryReset
+      include DefinitionBoundary
+      include StateSnapshot
+      include PreparationClaim
+      include PreparationRecovery
+      include Preparation
+      include RestartSafeAdapter
+      include Recovery
+      include RecoveryBoundary
+      include PreparationPayload
+      include DispatchBoundary
+      include DispatchClaim
+      include DispatchVerification
+      include DispatchConfirmation
+      include ExecutionVerification
+      include ExecutionAuthorization
+      include ExecutionResultCapture
+      include Execution
+      include CheckpointState
+      include Checkpoint
+      include Payloads
+    end
+  end
+end

data/lib/smith/workflow/step_completion.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module StepCompletion
+      private
+
+      def complete_step(transition, output)
+        step = { transition: transition.name, from: transition.from, to: transition.to, output: output }
+        result = SplitStepPersistence
+                 .instance_method(:prepare_split_step_execution_result)
+                 .bind_call(self, step)
+        StepCompletion.instance_method(:append_accepted_output).bind_call(self, output)
+        SplitStepPersistence
+          .instance_method(:commit_split_step_execution_result!)
+          .bind_call(self, result)
+        @state = transition.to
+        @next_transition_name = @router_next_transition || transition.success_transition
+        @router_next_transition = nil
+        emit_step_completed(transition, output)
+        step
+      end
+
+      def append_accepted_output(output)
+        return unless @session_messages && !output.nil?
+
+        @session_messages << { role: :assistant, content: output }
+      end
+    end
+  end
+end

data/lib/smith/workflow/string_snapshot.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    class StringSnapshot
+      BYTESIZE = String.instance_method(:bytesize)
+      FREEZE = String.instance_method(:freeze)
+      INITIALIZE_COPY = String.instance_method(:initialize_copy)
+      private_constant :BYTESIZE, :FREEZE, :INITIALIZE_COPY
+
+      class << self
+        def bytesize(value)
+          BYTESIZE.bind_call(value)
+        end
+
+        def copy(value, freeze: false)
+          String.allocate.tap do |copy|
+            INITIALIZE_COPY.bind_call(copy, value)
+            FREEZE.bind_call(copy) if freeze
+          end
+        end
+      end
+    end
+  end
+end