smith-agents 0.4.5 → 0.6.0

data/lib/smith/workflow/parallel_execution.rb

@@ -1,14 +1,19 @@
 # frozen_string_literal: true
 
 require_relative "branch_env"
+require_relative "parallel_agent_binding"
+require_relative "thread_context_snapshot"
 
 module Smith
   class Workflow
     module ParallelExecution
+      NO_PARALLEL_BINDING = Object.new.freeze
+      private_constant :NO_PARALLEL_BINDING
+
       private
 
       def execute_parallel_step(transition, prepared_input: nil)
-        count = Parallel.resolve_branch_count(transition, @context)
+        count = @resolved_parallel_branch_count || Parallel.resolve_branch_count(transition, @context)
         agent_class = resolve_agent_class(transition)
         estimates = compute_branch_estimates(@ledger, branch_count: count, agent_budget: agent_class&.budget)
         env = BranchEnv.new(
@@ -16,29 +21,32 @@ module Smith
           guardrail_sources: Tool.current_guardrails,
           scoped_store: propagate_scoped_artifacts,
           branch_estimates: estimates,
-          deadline: wall_clock_deadline
+          deadline: wall_clock_deadline,
+          agent_class:
         )
         ledger = @ledger
         branches = Array.new(count) do |i|
-          proc { |signal| run_branch(transition, i, env, ledger, signal) }
+          PreparedBranchExecution
+            .instance_method(:prepared_branch)
+            .bind_call(self, ParallelExecution.instance_method(:run_branch), transition, i, env, ledger)
         end
         Parallel.execute(branches: branches)
       end
 
       def run_branch(transition, index, env, ledger, signal)
-        setup_branch_context(env, ledger)
-        with_agent_context(resolve_agent_class(transition)) do
-          branch_ledger = effective_call_ledger
-          reserved = reserve_branch_call(branch_ledger, env, ledger)
-          begin
-            result = guarded_branch_call(transition, env, signal)
-            finalize_branch(transition, index, result, branch_ledger, reserved).tap { reserved = nil }
-          ensure
-            settle_budget_on_failure(branch_ledger, reserved, Thread.current[:smith_last_agent_result]) if reserved
+        binding = ParallelAgentBinding.new(self, transition, env.agent_class)
+        with_branch_context(env, ledger, parallel_agent_binding: binding) do
+          with_agent_context(env.agent_class) do
+            branch_ledger = effective_call_ledger
+            reserved = reserve_branch_call(branch_ledger, env, ledger)
+            begin
+              result = guarded_branch_call(transition, env, signal)
+              finalize_branch(transition, index, result, branch_ledger, reserved).tap { reserved = nil }
+            ensure
+              settle_budget_on_failure(branch_ledger, reserved, Thread.current[:smith_last_agent_result]) if reserved
+            end
           end
         end
-      ensure
-        teardown_branch_context(env)
       end
 
       def reserve_branch_call(branch_ledger, env, workflow_ledger)
@@ -47,6 +55,29 @@ module Smith
         reserve_serial_budget(branch_ledger) if branch_ledger
       end
 
+      def with_branch_context(
+        env,
+        ledger,
+        parallel_agent_binding: NO_PARALLEL_BINDING,
+        agent_class: nil,
+        &block
+      )
+        snapshot = ThreadContextSnapshot.new
+        snapshot.around do
+          if agent_class
+            setup_fanout_branch_context(env, ledger, agent_class)
+          else
+            setup_branch_context(env, ledger)
+          end
+          unless parallel_agent_binding.equal?(NO_PARALLEL_BINDING)
+            Thread.current[:smith_parallel_agent_binding] = parallel_agent_binding
+          end
+          Thread.handle_interrupt(Object => :immediate, &block)
+        ensure
+          teardown_branch_context(env)
+        end
+      end
+
       def setup_branch_context(env, ledger)
         env.setup_thread
         Tool.current_ledger = ledger
@@ -60,6 +91,7 @@ module Smith
         clear_failed_billable_attempts
         Tool.current_ledger = nil
         Tool.current_tool_result_collector = nil
+        Thread.current[:smith_parallel_agent_binding] = nil
         env.teardown_thread
       end
 

data/lib/smith/workflow/persistence.rb

@@ -10,17 +10,17 @@ module Smith
           class: self.class.name,
           state: @state,
           persistence_key: @persistence_key,
-          context: persisted_context,
+          context: snapshot_value(persisted_context),
           budget_consumed: ledger_consumed,
           step_count: @step_count,
           execution_namespace: @execution_namespace,
           created_at: @created_at,
           updated_at: @updated_at,
           next_transition_name: @next_transition_name,
-          session_messages: @session_messages || [],
+          session_messages: snapshot_session_messages,
           total_cost: @total_cost || 0.0,
           total_tokens: @total_tokens || 0,
-          tool_results: @tool_results || [],
+          tool_results: snapshot_value(@tool_results || []),
           outcome: snapshot_outcome,
           # Durable usage fields. All wrapped in
           # snapshot_value so non-JSON-safe runtime values (e.g.
@@ -38,6 +38,11 @@ module Smith
           # stored value lags the workflow's current
           # persistence_schema_version.
           schema_version: self.class.persistence_schema_version,
+          # Host-supplied digest of the complete executable workflow
+          # definition. Smith does not derive this from Ruby Proc or VM
+          # internals; hosts that need restart-safe prepared-step recovery
+          # must bind it to their immutable code/package identity.
+          definition_digest: effective_definition_digest,
           # SHA256 digest of the seed_messages produced at this
           # workflow's construction. Stays stable across persist/restore
           # cycles so seed_validation can detect when the seed builder
@@ -59,7 +64,9 @@ module Smith
 
       private
 
-      def restore_state(hash)
+      def restore_state(hash, allow_step_in_progress: false)
+        validate_raw_step_in_progress!(hash) if
+          self.class.idempotency_mode == :strict && !allow_step_in_progress
         migrated = migrate_if_needed(hash)
         normalized = normalize_persisted_state(migrated)
         persistence_version = validated_persistence_version(normalized)
@@ -89,6 +96,7 @@ module Smith
         # so the first persist! after restore expects version 0 (matches
         # the original store from the legacy adapter contract).
         @persistence_version = persistence_version
+        validate_definition_digest!(normalized)
         # Preserve the seed digest from the persisted payload so it
         # round-trips on subsequent persists. validate_seed_digest!
         # compares this against a fresh evaluation of the seed builder
@@ -100,7 +108,8 @@ module Smith
         # mode by raising if the marker is set on restore.
         @step_in_progress = normalized[:step_in_progress] || false
         @split_step_mutex = Mutex.new
-        validate_step_in_progress!(normalized) if self.class.idempotency_mode == :strict
+        validate_step_in_progress!(normalized) if
+          self.class.idempotency_mode == :strict && !allow_step_in_progress
       end
 
       def validated_persistence_version(normalized)
@@ -111,6 +120,18 @@ module Smith
               "persisted workflow persistence_version must be a non-negative integer, got #{version.inspect}"
       end
 
+      def validate_definition_digest!(normalized)
+        stored = normalized[:definition_digest]
+        return if stored.nil?
+
+        unless Smith::Types::Sha256Hex.valid?(stored)
+          raise Smith::SerializationError, "persisted workflow definition_digest must be a SHA-256 hex digest"
+        end
+        return if stored == self.class.definition_digest
+
+        raise Smith::WorkflowError, "persisted workflow definition does not match the current workflow class"
+      end
+
       def validate_step_in_progress!(normalized)
         return unless normalized[:step_in_progress] == true
 
@@ -120,6 +141,14 @@ module Smith
         )
       end
 
+      def validate_raw_step_in_progress!(state)
+        return unless state.is_a?(Hash)
+
+        marker = state[:step_in_progress] || state["step_in_progress"]
+        persistence_key = state[:persistence_key] || state["persistence_key"]
+        validate_step_in_progress!(step_in_progress: marker, persistence_key:)
+      end
+
       def validate_seed_digest!(normalized)
         stored_digest = normalized[:seed_digest]
         return if stored_digest.nil?
@@ -256,13 +285,13 @@ module Smith
       end
 
       def normalize_persisted_state(hash)
-        normalized = hash.transform_keys { |k| k.is_a?(String) ? k.to_sym : k }
+        normalized = snapshot_value(hash).transform_keys { |k| k.is_a?(String) ? k.to_sym : k }
+        normalized[:outcome] = symbolize_value(normalized[:outcome]) if normalized[:outcome].is_a?(Hash)
         normalize_symbol_fields!(normalized)
         normalize_nested_hashes!(normalized)
         normalize_session_messages!(normalized)
         normalize_tool_results!(normalized)
         normalize_usage_entries!(normalized)
-        normalized[:outcome] = symbolize_value(normalized[:outcome]) if normalized[:outcome].is_a?(Hash)
         normalized
       end
 
@@ -318,7 +347,7 @@ module Smith
         return unless normalized[:session_messages].is_a?(Array)
 
         normalized[:session_messages] = normalized[:session_messages].map do |msg|
-          msg.is_a?(Hash) ? symbolize_keys(msg) : msg
+          msg.is_a?(Hash) ? symbolize_keys(snapshot_value(msg)) : snapshot_value(msg)
         end
       end
 

data/lib/smith/workflow/prepared_branch_execution.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module PreparedBranchExecution
+      private
+
+      def prepared_branch(implementation, *arguments)
+        unless @split_step_active_execution_authorization
+          return proc { |signal| __send__(implementation.name, *arguments, signal) }
+        end
+
+        proc do |signal|
+          run = proc { implementation.bind_call(self, *arguments, signal) }
+          PreparedBranchExecution.instance_method(:within_prepared_branch_execution).bind_call(self, &run)
+        end
+      end
+
+      def within_prepared_branch_execution(&)
+        authorization = @split_step_active_execution_authorization
+        return yield unless authorization
+
+        PreparedStepExecutionAuthorization
+          .instance_method(:within_branch_execution!)
+          .bind_call(authorization, &)
+      end
+    end
+
+    private_constant :PreparedBranchExecution
+  end
+end

data/lib/smith/workflow/prepared_step.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "dry-struct"
+require "json"
+
+require_relative "../types"
+
+module Smith
+  class Workflow
+    class PreparedStep < Dry::Struct
+      ATTRIBUTES = %i[
+        token transition from persistence_key persistence_version step_number preparation_digest definition_digest
+      ].freeze
+      DIGEST_PATTERN = /\A[0-9a-f]{64}\z/
+      MAX_COUNTER_VALUE = (2**63) - 1
+      MAX_ATTRIBUTE_ENTRIES = 16
+      MAX_SERIALIZED_BYTES = 4 * 1024
+      UUID_PATTERN = /\A[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\z/i
+      OwnedString = Types::String.constructor do |value|
+        value.is_a?(String) ? value.dup.freeze : value
+      end
+      private_constant :OwnedString
+
+      attribute :token, OwnedString.constrained(format: UUID_PATTERN)
+      attribute :transition, OwnedString.constrained(min_size: 1)
+      attribute :from, OwnedString.constrained(min_size: 1)
+      attribute :persistence_key, OwnedString.constrained(min_size: 1)
+      attribute :persistence_version, Types::Integer.constrained(gteq: 1, lteq: MAX_COUNTER_VALUE)
+      attribute :step_number, Types::Integer.constrained(gteq: 1, lteq: MAX_COUNTER_VALUE)
+      attribute :preparation_digest, OwnedString.constrained(format: DIGEST_PATTERN)
+      attribute? :definition_digest, Types::Sha256Hex.optional
+
+      def self.deserialize(value)
+        attributes = parse_attributes(value)
+        normalized = normalize_attributes(attributes)
+        validate_attributes!(normalized)
+        validate_bounded_values!(normalized)
+        new(normalized)
+      rescue JSON::ParserError, TypeError => e
+        raise ArgumentError, "prepared step is invalid: #{e.message}"
+      end
+
+      def self.validate_attributes!(attributes)
+        unknown = attributes.keys - ATTRIBUTES
+        missing = ATTRIBUTES.first(7) - attributes.keys
+        raise ArgumentError, "prepared step contains unknown attributes: #{unknown.join(", ")}" if unknown.any?
+        raise ArgumentError, "prepared step is missing attributes: #{missing.join(", ")}" if missing.any?
+      end
+      private_class_method :validate_attributes!
+
+      def self.parse_attributes(value)
+        return validate_attribute_container!(value) if value.is_a?(Hash)
+        unless value.is_a?(String) && value.bytesize <= MAX_SERIALIZED_BYTES
+          raise ArgumentError, "prepared step must be a Hash or bounded JSON object"
+        end
+
+        parsed = JSON.parse(value)
+        return validate_attribute_container!(parsed) if parsed.is_a?(Hash)
+
+        raise ArgumentError, "prepared step JSON must contain an object"
+      end
+      private_class_method :parse_attributes
+
+      def self.validate_attribute_container!(attributes)
+        unless attributes.size <= MAX_ATTRIBUTE_ENTRIES
+          raise ArgumentError, "prepared step contains too many attributes"
+        end
+        unless attributes.keys.all? { |key| key.is_a?(String) || key.is_a?(Symbol) }
+          raise ArgumentError, "prepared step attribute names must be strings or symbols"
+        end
+
+        attributes
+      end
+      private_class_method :validate_attribute_container!
+
+      def self.validate_bounded_values!(attributes)
+        bytes = attributes.sum { |key, value| bounded_attribute_bytes(key, value) }
+        return attributes if bytes <= MAX_SERIALIZED_BYTES
+
+        raise ArgumentError, "prepared step Hash exceeds maximum bytes"
+      end
+      private_class_method :validate_bounded_values!
+
+      def self.bounded_attribute_bytes(key, value)
+        validate_scalar_value!(value)
+        key.to_s.bytesize + (value.is_a?(String) ? value.bytesize : 8)
+      end
+      private_class_method :bounded_attribute_bytes
+
+      def self.validate_scalar_value!(value)
+        unless value.nil? || value.is_a?(String) || value.is_a?(Integer)
+          raise ArgumentError, "prepared step attribute values must be scalar"
+        end
+        return unless value.is_a?(Integer) && !value.between?(1, MAX_COUNTER_VALUE)
+
+        raise ArgumentError, "prepared step integer values must fit a positive signed 64-bit counter"
+      end
+      private_class_method :validate_scalar_value!
+
+      def self.normalize_attributes(attributes)
+        normalized = attributes.each_with_object({}) do |(key, nested), result|
+          normalized_key = key.respond_to?(:to_sym) ? key.to_sym : key
+          raise ArgumentError, "prepared step contains duplicate attributes" if result.key?(normalized_key)
+
+          result[normalized_key] = nested
+        end
+        normalized[:definition_digest] = nil unless normalized.key?(:definition_digest)
+        normalized
+      end
+      private_class_method :normalize_attributes
+
+      def initialize(attributes)
+        owned = attributes.dup
+        digest = owned[:definition_digest] || owned["definition_digest"]
+        owned[:definition_digest] = digest.dup.freeze if digest.is_a?(String)
+        super(owned)
+        self.attributes.freeze
+        freeze
+      end
+    end
+  end
+end

data/lib/smith/workflow/prepared_step_dispatch.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "dry-struct"
+require "json"
+
+require_relative "../types"
+require_relative "prepared_step"
+
+module Smith
+  class Workflow
+    class PreparedStepDispatch < Dry::Struct
+      ATTRIBUTES = %i[prepared_step token dispatch_digest].freeze
+      MAX_ATTRIBUTE_ENTRIES = 8
+      MAX_SERIALIZED_BYTES = 8 * 1024
+      OwnedString = Types::String.constructor do |value|
+        value.is_a?(String) ? value.dup.freeze : value
+      end
+      private_constant :OwnedString
+
+      attribute :prepared_step, Types.Instance(PreparedStep)
+      attribute :token, OwnedString.constrained(format: PreparedStep::UUID_PATTERN)
+      attribute :dispatch_digest, OwnedString.constrained(format: PreparedStep::DIGEST_PATTERN)
+
+      def self.deserialize(value)
+        attributes = parse_attributes(value)
+        normalized = normalize_attributes(attributes)
+        validate_attributes!(normalized)
+        normalized[:prepared_step] = PreparedStep.deserialize(normalized[:prepared_step])
+        new(normalized)
+      rescue JSON::ParserError, TypeError => e
+        raise ArgumentError, "prepared-step dispatch is invalid: #{e.message}"
+      end
+
+      def self.parse_attributes(value)
+        return value if value.is_a?(Hash) && bounded_hash?(value)
+        unless value.is_a?(String) && value.bytesize <= MAX_SERIALIZED_BYTES
+          raise ArgumentError, "prepared-step dispatch must be a bounded Hash or JSON object"
+        end
+
+        parsed = JSON.parse(value)
+        return parsed if parsed.is_a?(Hash) && bounded_hash?(parsed)
+
+        raise ArgumentError, "prepared-step dispatch JSON must contain a bounded object"
+      end
+      private_class_method :parse_attributes
+
+      def self.bounded_hash?(attributes)
+        return false unless attributes.size <= MAX_ATTRIBUTE_ENTRIES
+        return false unless attributes.keys.all? { |key| key.is_a?(String) || key.is_a?(Symbol) }
+
+        attributes.sum { |key, value| key.to_s.bytesize + bounded_value_bytes(value) } <= MAX_SERIALIZED_BYTES
+      end
+      private_class_method :bounded_hash?
+
+      def self.bounded_value_bytes(value)
+        return value.bytesize if value.is_a?(String)
+        return PreparedStep::MAX_SERIALIZED_BYTES if value.is_a?(Hash)
+
+        MAX_SERIALIZED_BYTES + 1
+      end
+      private_class_method :bounded_value_bytes
+
+      def self.normalize_attributes(attributes)
+        attributes.each_with_object({}) do |(key, value), result|
+          normalized_key = key.respond_to?(:to_sym) ? key.to_sym : key
+          raise ArgumentError, "prepared-step dispatch contains duplicate attributes" if result.key?(normalized_key)
+
+          result[normalized_key] = value
+        end
+      end
+      private_class_method :normalize_attributes
+
+      def self.validate_attributes!(attributes)
+        unknown = attributes.keys - ATTRIBUTES
+        missing = ATTRIBUTES - attributes.keys
+        raise ArgumentError, "prepared-step dispatch contains unknown attributes: #{unknown.join(", ")}" if unknown.any?
+        raise ArgumentError, "prepared-step dispatch is missing attributes: #{missing.join(", ")}" if missing.any?
+      end
+      private_class_method :validate_attributes!
+
+      def initialize(attributes)
+        super
+        self.attributes.freeze
+        freeze
+      end
+    end
+  end
+end

data/lib/smith/workflow/prepared_step_execution_authorization.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require_relative "prepared_step"
+require_relative "prepared_step_dispatch"
+require_relative "prepared_step_execution_scope"
+require_relative "process_local"
+require_relative "split_step_persistence/execution_binding_snapshot"
+require_relative "../errors"
+
+module Smith
+  class Workflow
+    class PreparedStepExecutionAuthorization
+      include ProcessLocal
+
+      attr_reader :prepared_step, :dispatch_claim
+
+      def initialize(prepared_step:, dispatch_claim:, execution_bindings:)
+        unless prepared_step.is_a?(PreparedStep)
+          raise ArgumentError, "prepared_step must be a Smith::Workflow::PreparedStep"
+        end
+        unless dispatch_claim.nil? || dispatch_claim.is_a?(PreparedStepDispatch)
+          raise ArgumentError, "dispatch_claim must be a Smith::Workflow::PreparedStepDispatch or nil"
+        end
+        if dispatch_claim && dispatch_claim.prepared_step.to_h != prepared_step.to_h
+          raise ArgumentError, "dispatch claim must belong to the prepared step"
+        end
+        unless execution_bindings.is_a?(SplitStepPersistence::ExecutionBindingSnapshot)
+          raise ArgumentError, "execution_bindings must be a Smith execution binding snapshot"
+        end
+
+        @prepared_step = prepared_step
+        @dispatch_claim = dispatch_claim
+        @execution_bindings = execution_bindings
+        @execution_scope = PreparedStepExecutionScope.new
+        @process_id = Process.pid
+        freeze
+      end
+
+      def issued_in_current_process? = @process_id == Process.pid
+
+      def fetch_agent!(...)
+        ensure_binding_access!
+
+        @execution_bindings.fetch!(...)
+      end
+
+      def each_agent_binding(&block)
+        ensure_binding_access!
+        raise ArgumentError, "a block is required to inspect captured agent bindings" unless block
+
+        @execution_bindings.each_agent_binding(&block)
+        self
+      end
+
+      def verify_workflow!(workflow_class)
+        ensure_active_execution!
+        @execution_bindings.verify_workflow!(workflow_class)
+      end
+
+      def active_in_current_execution?
+        issued_in_current_process? && @execution_scope.active_for?(Thread.current, Fiber.current)
+      end
+
+      private
+
+      def within_branch_execution!(&)
+        ensure_current_process!
+        @execution_scope.within_branch(&)
+      end
+
+      def activate_execution!
+        ensure_current_process!
+        @execution_scope.activate!(Thread.current, Fiber.current)
+      end
+
+      def close_execution!
+        @execution_scope.close!(Thread.current, Fiber.current)
+      end
+
+      def ensure_active_execution!
+        return if active_in_current_execution?
+
+        raise WorkflowError, "prepared-step execution authorization is outside its active execution"
+      end
+
+      def ensure_binding_access!
+        accessible = issued_in_current_process? &&
+                     @execution_scope.binding_accessible_for?(Thread.current, Fiber.current)
+        return if accessible
+
+        raise WorkflowError, "prepared-step execution authorization is outside its binding access scope"
+      end
+
+      def ensure_current_process!
+        return if issued_in_current_process?
+
+        raise WorkflowError, "prepared-step execution authorization belongs to another process"
+      end
+    end
+  end
+end

data/lib/smith/workflow/prepared_step_execution_result.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "dry-struct"
+
+require_relative "../types"
+require_relative "execution_result_snapshot"
+
+module Smith
+  class Workflow
+    class PreparedStepExecutionResult < Dry::Struct
+      attribute :status, Types::Symbol.enum(:succeeded, :failed)
+      attribute :step, Types::Hash
+      attribute? :error, Types.Instance(StandardError).optional
+
+      def self.from_step(step)
+        error = step[:error]
+        new(status: error ? :failed : :succeeded, step:, error:)
+      end
+
+      def initialize(attributes)
+        owned = attributes.dup
+        owned[:step] = snapshot(owned.fetch(:step), freeze_copy: true, preserved_error: owned[:error])
+        super(owned)
+        validate_shape!
+        self.attributes.freeze
+        freeze
+      end
+
+      def succeeded? = status == :succeeded
+      def failed? = status == :failed
+      def step_snapshot = snapshot(step, freeze_copy: false, preserved_error: error)
+
+      private
+
+      def snapshot(value, freeze_copy:, preserved_error:)
+        ExecutionResultSnapshot.new(value, freeze_copy:, preserved_error:).call
+      end
+
+      def validate_shape!
+        valid = if failed?
+                  error && step[:error].equal?(error)
+                else
+                  error.nil? && !step.key?(:error)
+                end
+        raise ArgumentError, "prepared-step execution result fields do not match status" unless valid
+      end
+    end
+  end
+end