smith-agents 0.5.0 → 0.6.0

data/lib/smith/workflow/fanout_execution.rb

@@ -35,29 +35,32 @@ module Smith
         )
 
         branch_calls = branches.map do |branch_key, agent_name|
-          proc do |signal|
-            run_fanout_branch(branch_key, agent_name, branch_agent_classes.fetch(branch_key), env, signal)
-          end
+          PreparedBranchExecution.instance_method(:prepared_branch).bind_call(
+            self,
+            FanoutExecution.instance_method(:run_fanout_branch),
+            branch_key,
+            agent_name,
+            branch_agent_classes.fetch(branch_key),
+            env
+          )
         end
 
         Parallel.execute(branches: branch_calls)
       end
 
       def run_fanout_branch(branch_key, agent_name, agent_class, env, signal)
-        setup_fanout_branch_context(env, @ledger, agent_class)
-
-        with_agent_context(agent_class) do
-          branch_ledger = effective_call_ledger
-          reserved = reserve_fanout_branch_call(branch_ledger, env.branch_estimates[branch_key], agent_class)
-          begin
-            result = guarded_fanout_branch_call(agent_class, env, signal)
-            finalize_named_branch(branch_key, agent_name, result, branch_ledger, reserved).tap { reserved = nil }
-          ensure
-            settle_budget_on_failure(branch_ledger, reserved, Thread.current[:smith_last_agent_result]) if reserved
+        with_branch_context(env, @ledger, agent_class:) do
+          with_agent_context(agent_class) do
+            branch_ledger = effective_call_ledger
+            reserved = reserve_fanout_branch_call(branch_ledger, env.branch_estimates[branch_key], agent_class)
+            begin
+              result = guarded_fanout_branch_call(agent_class, env, signal)
+              finalize_named_branch(branch_key, agent_name, 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 guarded_fanout_branch_call(agent_class, env, signal)
@@ -89,9 +92,7 @@ module Smith
       end
 
       def run_fanout_agent_input_guardrails(branch_agent_classes)
-        branch_agent_classes.each_value do |agent_class|
-          run_agent_input_guardrails(agent_class)
-        end
+        branch_agent_classes.each_value { |agent_class| run_agent_input_guardrails(agent_class) }
       end
 
       def fanout_branch_estimates(branches, branch_agent_classes)

data/lib/smith/workflow/message_value_normalizer.rb

@@ -19,6 +19,7 @@ module Smith
       extend Dry::Initializer
 
       param :value
+      option :label, default: proc { "session message" }
 
       def call
         @active = {}.compare_by_identity
@@ -50,12 +51,12 @@ module Smith
         when Float then copy_float(item)
         when true, false, nil then item
         else
-          reject!("session message contains unsupported value #{item.class}")
+          reject!("#{label} contains unsupported value #{item.class}")
         end
       end
 
       def copy_container(source)
-        reject!("session message contains a cyclic value") if @active.key?(source)
+        reject!("#{label} contains a cyclic value") if @active.key?(source)
 
         @active[source] = true
         yield
@@ -77,8 +78,8 @@ module Smith
         pairs = []
         remaining_nodes = MAX_NODES - @nodes
         HASH_EACH_PAIR.bind_call(source) do |key, nested|
-          reject!("session message batch exceeds maximum size #{MAX_NODES}") if pairs.length == remaining_nodes
-          reject!("session message Hash keys must be strings or symbols") unless key.is_a?(String) || key.is_a?(Symbol)
+          reject!("#{label} exceeds maximum size #{MAX_NODES}") if pairs.length == remaining_nodes
+          reject!("#{label} Hash keys must be strings or symbols") unless key.is_a?(String) || key.is_a?(Symbol)
 
           pairs << [copy_string(key.to_s), nested]
         end
@@ -88,7 +89,7 @@ module Smith
       def validate_unique_keys!(pairs)
         return unless pairs.each_cons(2).any? { |left, right| left.first == right.first }
 
-        reject!("session message contains duplicate canonical Hash keys")
+        reject!("#{label} contains duplicate canonical Hash keys")
       end
 
       def copy_array(source, depth:)
@@ -99,7 +100,7 @@ module Smith
 
       def copy_string(string)
         @bytes += StringSnapshot.bytesize(string)
-        reject!("session message batch exceeds maximum bytes #{MAX_BYTES}") if @bytes > MAX_BYTES
+        reject!("#{label} exceeds maximum bytes #{MAX_BYTES}") if @bytes > MAX_BYTES
 
         StringSnapshot.copy(string, freeze: true)
       end
@@ -107,22 +108,22 @@ module Smith
       def copy_integer(integer)
         return integer if INTEGER_RANGE.cover?(integer)
 
-        reject!("session message integers must fit a signed 64-bit value")
+        reject!("#{label} integers must fit a signed 64-bit value")
       end
 
       def copy_float(float)
         return float if float.finite?
 
-        reject!("session message contains a non-finite Float")
+        reject!("#{label} contains a non-finite Float")
       end
 
       def visit!(depth)
-        reject!("session message batch exceeds maximum depth #{MAX_DEPTH}") if depth > MAX_DEPTH
+        reject!("#{label} exceeds maximum depth #{MAX_DEPTH}") if depth > MAX_DEPTH
 
         @nodes += 1
         return if @nodes <= MAX_NODES
 
-        reject!("session message batch exceeds maximum size #{MAX_NODES}")
+        reject!("#{label} exceeds maximum size #{MAX_NODES}")
       end
 
       def reject!(message)

data/lib/smith/workflow/parallel_execution.rb

@@ -2,10 +2,14 @@
 
 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)
@@ -22,26 +26,27 @@ module Smith
         )
         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)
-        Thread.current[:smith_parallel_agent_binding] = ParallelAgentBinding.new(self, transition, env.agent_class)
-        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
+        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)
@@ -50,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

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_execution_authorization.rb

@@ -3,12 +3,15 @@
 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:)
@@ -55,42 +58,23 @@ module Smith
       end
 
       def active_in_current_execution?
-        issued_in_current_process? && @execution_scope.active_for?(Thread.current)
-      end
-
-      def initialize_copy(_source)
-        raise TypeError, "prepared-step execution authorizations cannot be copied"
-      end
-
-      def _dump(_depth)
-        raise TypeError, "prepared-step execution authorizations cannot be serialized"
-      end
-
-      def encode_with(_coder)
-        raise TypeError, "prepared-step execution authorizations cannot be serialized"
+        issued_in_current_process? && @execution_scope.active_for?(Thread.current, Fiber.current)
       end
 
-      def init_with(_coder)
-        raise TypeError, "prepared-step execution authorizations cannot be deserialized"
-      end
-
-      def as_json(*)
-        raise TypeError, "prepared-step execution authorizations cannot be serialized"
-      end
+      private
 
-      def to_json(*)
-        raise TypeError, "prepared-step execution authorizations cannot be serialized"
+      def within_branch_execution!(&)
+        ensure_current_process!
+        @execution_scope.within_branch(&)
       end
 
-      private
-
-      def activate_execution!(thread)
+      def activate_execution!
         ensure_current_process!
-        @execution_scope.activate!(thread)
+        @execution_scope.activate!(Thread.current, Fiber.current)
       end
 
-      def close_execution!(thread = nil)
-        @execution_scope.close!(thread)
+      def close_execution!
+        @execution_scope.close!(Thread.current, Fiber.current)
       end
 
       def ensure_active_execution!
@@ -100,7 +84,8 @@ module Smith
       end
 
       def ensure_binding_access!
-        accessible = issued_in_current_process? && @execution_scope.binding_accessible_for?(Thread.current)
+        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"

data/lib/smith/workflow/prepared_step_execution_scope.rb

@@ -1,45 +1,111 @@
 # frozen_string_literal: true
 
 require_relative "../errors"
+require_relative "process_local"
 
 module Smith
   class Workflow
     class PreparedStepExecutionScope
+      include ProcessLocal
+
       def initialize
         @mutex = Mutex.new
         @phase = :issued
         @thread = nil
+        @fiber = nil
+        @branch_fibers = {}.compare_by_identity
       end
 
-      def activate!(thread)
-        @mutex.synchronize do
-          raise WorkflowError, "prepared-step execution scope is no longer available" unless @phase == :issued
+      def activate!(thread, fiber = Fiber.current)
+        Thread.handle_interrupt(Object => :never) do
+          @mutex.synchronize do
+            raise WorkflowError, "prepared-step execution scope is no longer available" unless @phase == :issued
 
-          @phase = :active
-          @thread = thread
+            @phase = :active
+            @thread = thread
+            @fiber = fiber
+          end
         end
       end
 
-      def close!(thread = nil)
-        @mutex.synchronize do
-          if @phase == :active && thread && !@thread.equal?(thread)
-            raise WorkflowError, "prepared-step execution scope belongs to another thread"
+      def close!(thread = nil, fiber = Fiber.current)
+        Thread.handle_interrupt(Object => :never) do
+          @mutex.synchronize do
+            if @phase == :active && thread && !owner?(@thread, @fiber, thread, fiber)
+              raise WorkflowError, "prepared-step execution scope belongs to another thread or fiber"
+            end
+            raise WorkflowError, "prepared-step execution still has active branch fibers" unless @branch_fibers.empty?
+
+            @phase = :closed
+            @thread = nil
+            @fiber = nil
           end
+        end
+      end
 
-          @phase = :closed
-          @thread = nil
+      def within_branch(&block)
+        thread = Thread.current
+        fiber = Fiber.current
+        Thread.handle_interrupt(Object => :never) do
+          enter_branch!(thread, fiber)
+          begin
+            Thread.handle_interrupt(Object => :immediate, &block)
+          ensure
+            leave_branch!(thread, fiber)
+          end
         end
       end
 
-      def active_for?(thread)
-        @mutex.synchronize { @phase == :active && @thread.equal?(thread) }
+      def active_for?(thread, fiber = Fiber.current)
+        @mutex.synchronize do
+          @phase == :active && (owner?(@thread, @fiber, thread, fiber) || branch_owner?(thread, fiber))
+        end
       end
 
-      def binding_accessible_for?(thread)
+      def binding_accessible_for?(thread, fiber = Fiber.current)
         @mutex.synchronize do
-          @phase == :issued || (@phase == :active && @thread.equal?(thread))
+          @phase == :issued ||
+            (@phase == :active && (owner?(@thread, @fiber, thread, fiber) || branch_owner?(thread, fiber)))
         end
       end
+
+      private
+
+      def enter_branch!(thread, fiber)
+        @mutex.synchronize do
+          raise WorkflowError, "prepared-step execution scope is not active" unless @phase == :active
+
+          entry = @branch_fibers[fiber]
+          if entry && !entry.fetch(:thread).equal?(thread)
+            raise WorkflowError, "prepared-step branch fiber belongs to another thread"
+          end
+
+          @branch_fibers[fiber] = { thread:, count: entry ? entry.fetch(:count) + 1 : 1 }
+        end
+      end
+
+      def leave_branch!(thread, fiber)
+        @mutex.synchronize do
+          entry = @branch_fibers.fetch(fiber) do
+            raise WorkflowError, "prepared-step branch execution fiber is not active"
+          end
+          unless entry.fetch(:thread).equal?(thread)
+            raise WorkflowError, "prepared-step branch fiber belongs to another thread"
+          end
+
+          count = entry.fetch(:count)
+          count == 1 ? @branch_fibers.delete(fiber) : entry[:count] = count - 1
+        end
+      end
+
+      def branch_owner?(thread, fiber)
+        entry = @branch_fibers[fiber]
+        !!(entry && entry.fetch(:thread).equal?(thread))
+      end
+
+      def owner?(owner_thread, owner_fiber, thread, fiber)
+        owner_thread.equal?(thread) && owner_fiber.equal?(fiber)
+      end
     end
   end
 end

data/lib/smith/workflow/process_local.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module ProcessLocal
+      def initialize_copy(_source)
+        raise TypeError, "#{self.class} cannot be copied"
+      end
+
+      def _dump(_depth)
+        raise TypeError, "#{self.class} cannot be serialized"
+      end
+
+      def encode_with(_coder)
+        raise TypeError, "#{self.class} cannot be serialized"
+      end
+
+      def init_with(_coder)
+        raise TypeError, "#{self.class} cannot be deserialized"
+      end
+
+      def as_json(*)
+        raise TypeError, "#{self.class} cannot be serialized"
+      end
+
+      def to_json(*)
+        raise TypeError, "#{self.class} cannot be serialized"
+      end
+    end
+
+    private_constant :ProcessLocal
+  end
+end

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

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require_relative "../composite/contract"
+require_relative "../composite_branch_execution_authorization"
+require_relative "execution_binding_snapshot"
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      module CompositeBranchAuthorization
+        include Composite::Contract
+
+        private
+
+        def authorize_prepared_composite_branch_execution!(execution:, input:)
+          authorization = nil
+          handed_off = false
+          authorization = CompositeBranchAuthorization
+                          .instance_method(:interrupt_safe_composite_branch_authorization)
+                          .bind_call(self, execution, input)
+          handed_off = true
+          authorization
+        ensure
+          unless handed_off
+            ExecutionLifecycle
+              .instance_method(:release_failed_execution_authorization!)
+              .bind_call(self, authorization)
+          end
+        end
+
+        def with_composite_branch_authorization(execution, input)
+          Thread.handle_interrupt(Object => :never) do
+            authorization = interrupt_safe_composite_branch_authorization(execution, input)
+            begin
+              Thread.handle_interrupt(Object => :immediate) { yield(authorization) }
+            ensure
+              ExecutionLifecycle
+                .instance_method(:release_failed_execution_authorization!)
+                .bind_call(self, authorization)
+            end
+          end
+        end
+
+        def interrupt_safe_composite_branch_authorization(execution, input)
+          Thread.handle_interrupt(Object => :never) do
+            Composite::Contract
+              .instance_method(:validate_composite_branch_payload_types!)
+              .bind_call(self, execution, input)
+            verification_token = ExecutionAuthorization
+                                 .instance_method(:claim_framework_execution_verification!)
+                                 .bind_call(self)
+            begin
+              CompositeBranchAuthorization
+                .instance_method(:authorize_claimed_composite_branch_execution!)
+                .bind_call(self, verification_token, execution, input)
+            ensure
+              ExecutionAuthorization
+                .instance_method(:restore_framework_execution_verification!)
+                .bind_call(self, verification_token)
+            end
+          end
+        end
+
+        def authorize_claimed_composite_branch_execution!(verification_token, execution, input)
+          ExecutionVerification
+            .instance_method(:verify_claimed_split_step_execution!)
+            .bind_call(self, verification_token)
+          authorization = CompositeBranchAuthorization
+                          .instance_method(:build_composite_branch_execution_authorization)
+                          .bind_call(self, execution, input)
+          ExecutionAuthorization
+            .instance_method(:activate_split_step_execution_authorization!)
+            .bind_call(self, authorization, verification_token)
+          Composite::Contract
+            .instance_method(:validate_composite_branch_execution!)
+            .bind_call(self, authorization, execution, input)
+          authorization
+        end
+
+        def build_composite_branch_execution_authorization(execution, input)
+          role = execution.kind == :parallel ? :agent : :fanout_agent
+          bindings = ExecutionBindingSnapshot.capture_agent(
+            @split_step_transition,
+            workflow_class: self.class,
+            name: execution.branch.agent,
+            role:
+          )
+          CompositeBranchExecutionAuthorization.new(
+            execution:,
+            input:,
+            prepared_step: @split_step_prepared_descriptor,
+            dispatch_claim: @split_step_dispatch_descriptor,
+            execution_bindings: bindings
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "../composite/effects"
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      module CompositeBranchEffects
+        private
+
+        def composite_effect_offsets
+          usage = @usage_mutex.synchronize { @usage_entries.length }
+          tools = @tool_results_mutex.synchronize { @tool_results.length }
+          [usage, tools]
+        end
+
+        def capture_composite_branch_effects(usage_offset, tool_offset, branch)
+          usage = @usage_mutex.synchronize do
+            @usage_entries.drop(usage_offset).map { composite_usage_entry(_1, branch) }
+          end
+          tools = @tool_results_mutex.synchronize { @tool_results.drop(tool_offset) }
+          consumed = @ledger ? @ledger.consumed : {}
+          [Composite::Effects.new(usage_entries: usage, tool_results: tools, budget_consumed: consumed), nil]
+        rescue WorkflowError, ArgumentError => e
+          safe = Composite::Effects.new(usage_entries: usage || [], tool_results: [], budget_consumed: consumed || {})
+          [safe, e]
+        end
+
+        def composite_usage_entry(entry, branch)
+          attributes = entry.to_h
+          recorded_agent = attributes[:agent_name]
+          if recorded_agent && recorded_agent.to_s != branch.agent
+            raise WorkflowError, "composite usage entry does not match the executed branch agent"
+          end
+
+          attributes.merge(agent_name: branch.agent)
+        end
+      end
+    end
+  end
+end