smith-agents 0.5.0 → 0.6.1

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

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

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require_relative "../composite/contract"
+require_relative "composite_branch_effects"
+require_relative "composite_branch_outcome"
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      module CompositeBranchExecution
+        include Composite::Contract
+        include CompositeBranchEffects
+        include CompositeBranchOutcome
+
+        private
+
+        def execute_authorized_composite_branch!(authorization, execution:, input:)
+          authorization = validate_composite_authorization!(authorization)
+          perform_authorized_prepared_step_execution!(authorization) do
+            validate_composite_branch_execution!(authorization, execution, input)
+            [nil, execute_composite_branch(authorization, execution, input)]
+          end
+        end
+
+        def execute_composite_branch(authorization, execution, input)
+          branch = execution.branch
+          previous_ledger = @ledger
+          previous_execution_namespace = @execution_namespace
+          @ledger = composite_branch_ledger(branch)
+          @execution_namespace = execution.execution_namespace
+          offsets = composite_effect_offsets
+          output, error = capture_composite_branch do
+            dispatch_composite_branch(authorization, execution, input)
+          end
+          effects, effect_error = capture_composite_branch_effects(*offsets, branch)
+          composite_branch_outcome(execution, output, error || effect_error, effects)
+        ensure
+          @ledger = previous_ledger
+          @execution_namespace = previous_execution_namespace
+        end
+
+        def capture_composite_branch(&block)
+          output = within_raw_step_context { with_scoped_artifacts(&block) }
+          [output, nil]
+        rescue StandardError => e
+          [nil, e]
+        end
+
+        def dispatch_composite_branch(authorization, execution, input)
+          branch = execution.branch
+          transition = @split_step_transition
+          agent_role = execution.kind == :parallel ? :agent : :fanout_agent
+          agent_class = captured_agent(authorization, transition, branch.agent, agent_role)
+          apply_tool_guardrails(agent_class) if execution.kind == :parallel
+          environment = composite_branch_environment(execution, input, agent_class, transition)
+          execute_composite_branch_kind(execution, transition, agent_class, environment)
+        end
+
+        def execute_composite_branch_kind(execution, transition, agent_class, environment)
+          branch = execution.branch
+          signal = Parallel::CancellationSignal.new
+          return run_branch(transition, branch.ordinal, environment, @ledger, signal) if execution.kind == :parallel
+
+          branch_key, agent = fetch_composite_fanout_branch(transition, branch.key)
+          run_fanout_branch(branch_key, agent, agent_class, environment, signal)
+        end
+
+        def composite_branch_environment(execution, input, agent_class, transition)
+          branch = execution.branch
+          budget = branch.budget.transform_keys(&:to_sym)
+          branch_key = fetch_composite_fanout_branch(transition, branch.key).first unless execution.kind == :parallel
+          estimates = execution.kind == :parallel ? budget : { branch_key => budget }
+          BranchEnv.new(
+            prepared_input: input.agent_messages,
+            guardrail_sources: Tool.current_guardrails,
+            scoped_store: propagate_scoped_artifacts,
+            branch_estimates: estimates,
+            deadline: wall_clock_deadline,
+            agent_class: execution.kind == :parallel ? agent_class : nil
+          )
+        end
+
+        def composite_branch_ledger(branch)
+          return if branch.budget.empty?
+
+          Budget::Ledger.new(limits: branch.budget.transform_keys(&:to_sym))
+        end
+
+        def fetch_composite_fanout_branch(transition, branch_key)
+          Transition.instance_method(:fetch_fanout_branch!).bind_call(transition, branch_key)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "../composite/branch_outcome"
+require_relative "../composite/error_evidence"
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      module CompositeBranchOutcome
+        private
+
+        def composite_branch_outcome(execution, output, error, effects)
+          return failed_composite_branch_outcome(execution, error, effects) if error
+
+          Composite::BranchOutcome.succeeded(
+            plan_digest: execution.plan_digest,
+            branch: execution.branch,
+            output: output.fetch(:output),
+            effects:
+          )
+        rescue WorkflowError, ArgumentError => e
+          failed_composite_branch_outcome(execution, e, effects)
+        end
+
+        def failed_composite_branch_outcome(execution, error, effects)
+          Composite::BranchOutcome.failed(
+            plan_digest: execution.plan_digest,
+            branch: execution.branch,
+            error: Composite::ErrorEvidence.call(error),
+            effects:
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      module CompositeExecution
+        def prepare_composite_step!
+          ExecutionAuthorizationIssuance
+            .instance_method(:with_prepared_step_execution_authorization)
+            .bind_call(self) do |authorization|
+              CompositePreparation
+                .instance_method(:prepare_authorized_composite_step!)
+                .bind_call(self, authorization)
+            end
+        end
+
+        def execute_prepared_composite_branch!(execution:, input:)
+          CompositeBranchAuthorization
+            .instance_method(:with_composite_branch_authorization)
+            .bind_call(self, execution, input) do |authorization|
+              CompositeBranchExecution
+                .instance_method(:execute_authorized_composite_branch!)
+                .bind_call(self, authorization, execution:, input:)
+            end
+        end
+
+        def reduce_prepared_composite_step!(plan:, input:, outcomes:, primary_failure: nil)
+          ExecutionAuthorizationIssuance
+            .instance_method(:with_prepared_step_execution_authorization)
+            .bind_call(self) do |authorization|
+              CompositeReductionExecution
+                .instance_method(:reduce_authorized_composite_step!)
+                .bind_call(self, authorization, plan:, input:, outcomes:, primary_failure:)
+            end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative "../composite/contract"
+require_relative "../composite/input"
+require_relative "../composite/planner"
+require_relative "../composite/preparation"
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      module CompositePreparation
+        include Composite::Contract
+
+        private
+
+        def prepare_authorized_composite_step!(authorization)
+          authorization = validate_composite_authorization!(authorization)
+          transition = @split_step_transition
+          specs = composite_branch_specs(authorization, transition)
+          input = prepare_composite_input(authorization, transition, specs)
+          plan = Composite::Planner.new(
+            dispatch: authorization.dispatch_claim,
+            kind: composite_kind(transition),
+            transition: transition.name,
+            from: transition.from,
+            execution_namespace: execution_namespace,
+            branch_specs: specs,
+            input_digest: input.digest,
+            budget_state_digest: composite_budget_state_digest
+          ).call
+          Composite::Preparation.new(plan:, input:)
+        end
+
+        def prepare_composite_input(authorization, transition, specs)
+          ThreadContextSnapshot.new.around do
+            run_composite_input_guardrails(authorization, transition, specs)
+            agent_messages = build_session&.prepare!
+            Composite::Input.build(agent_messages:, session_messages: snapshot_session_messages)
+          end
+        end
+
+        def run_composite_input_guardrails(authorization, transition, specs)
+          if transition.parallel?
+            agent = specs.first.fetch(:agent)
+            run_input_guardrails(captured_agent(authorization, transition, agent, :agent))
+          else
+            run_workflow_input_guardrails
+            specs.each do |spec|
+              agent = spec.fetch(:agent)
+              run_agent_input_guardrails(captured_agent(authorization, transition, agent, :fanout_agent))
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require_relative "../composite/branch_failure"
+require_relative "../composite/contract"
+require_relative "../composite/effects_baseline"
+require_relative "../composite/effects_preflight"
+require_relative "../composite/reducer"
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      module CompositeReductionExecution
+        include Composite::Contract
+
+        private
+
+        def reduce_authorized_composite_step!(authorization, plan:, input:, outcomes:, primary_failure: nil)
+          authorization = validate_composite_authorization!(authorization)
+          validate_composite_reduction_plan!(authorization, plan, input)
+          reduction = Composite::Reducer.new(plan:, outcomes:, primary_failure:).call
+          effects_application = prepare_composite_effects(reduction.effects)
+          @composite_plan = plan
+          @composite_input = input
+          @composite_reduction = reduction
+          @composite_effects_application = effects_application
+          @execution_namespace = plan.execution_namespace
+          Execution.instance_method(:execute_authorized_prepared_step!).bind_call(self, authorization)
+        ensure
+          @composite_plan = nil
+          @composite_input = nil
+          @composite_reduction = nil
+          @composite_effects_application = nil
+        end
+
+        def apply_composite_reduction!(transition)
+          reduction = @composite_reduction
+          apply_composite_effects!(@composite_effects_application)
+          restore_composite_session!
+          if reduction.failed?
+            raise Composite::BranchFailure.new(
+              branch_key: reduction.failed_branch_key,
+              error: reduction.error
+            )
+          end
+
+          validate_composite_output!(transition, reduction.output)
+          reduction.output
+        end
+
+        def restore_composite_session!
+          @session_messages = snapshot_value(@composite_input.session_messages)
+          @last_prepared_input = snapshot_value(@composite_input.agent_messages)
+        end
+
+        def prepare_composite_effects(effects)
+          Composite::EffectsPreflight.new(
+            effects:,
+            baseline: composite_effect_baseline,
+            snapshotter: method(:snapshot_value)
+          ).call
+        end
+
+        def apply_composite_effects!(application)
+          Thread.handle_interrupt(Object => :never) do
+            @usage_mutex.synchronize do
+              @tool_results_mutex.synchronize do
+                validate_composite_effect_baseline!(application.baseline)
+                @usage_entries = application.usage_entries.dup
+                @total_tokens = application.total_tokens
+                @total_cost = application.total_cost
+                @tool_results = application.tool_results.dup
+                @ledger = application.ledger
+              end
+            end
+          end
+        end
+
+        def composite_effect_baseline
+          @usage_mutex.synchronize do
+            @tool_results_mutex.synchronize do
+              build_composite_effect_baseline
+            end
+          end
+        end
+
+        def build_composite_effect_baseline
+          ledger = @ledger
+          Composite::EffectsBaseline.new(
+            usage_entries: @usage_entries.dup,
+            tool_results: snapshot_value(@tool_results),
+            total_tokens: @total_tokens,
+            total_cost: @total_cost,
+            ledger:,
+            budget_consumed: ledger ? ledger.consumed : {}
+          )
+        end
+
+        def validate_composite_effect_baseline!(expected)
+          current = build_composite_effect_baseline
+          return if current == expected
+
+          raise WorkflowError, "composite effect baseline changed before application"
+        end
+
+        def validate_composite_output!(transition, output)
+          if @composite_plan.kind == :parallel
+            agent = captured_agent(
+              @split_step_active_execution_authorization,
+              transition,
+              @composite_plan.branches.first.agent,
+              :agent
+            )
+            validate_data_volume!(output, agent)
+            run_output_guardrails(output, agent)
+          else
+            run_workflow_output_guardrails(output)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -5,28 +5,19 @@ module Smith
     module SplitStepPersistence
       module Execution
         def execute_prepared_step!
-          authorization = ExecutionAuthorization
-                          .instance_method(:authorize_prepared_step_execution!)
-                          .bind_call(self)
-          result = Execution.instance_method(:execute_authorized_prepared_step!).bind_call(self, authorization)
+          result = ExecutionAuthorizationIssuance
+                   .instance_method(:with_prepared_step_execution_authorization)
+                   .bind_call(self) do |authorization|
+            Execution.instance_method(:execute_authorized_prepared_step!).bind_call(self, authorization)
+          end
           result.step_snapshot
         end
 
         def execute_authorized_prepared_step!(authorization)
-          authorization = validate_split_step_execution_authorization!(authorization)
-          step = nil
-          result = nil
-          execution_thread = Thread.current
-          execution_active = false
-          begin
-            activate_split_step_execution!(authorization, execution_thread)
-            execution_active = true
+          perform_authorized_prepared_step_execution!(authorization) do |execution_thread|
             step = execute_claimed_split_step_transition!
-            result = consume_split_step_execution_result!(execution_thread)
-          ensure
-            finish_split_step_execution!(step, authorization, execution_thread) if execution_active
+            [step, consume_split_step_execution_result!(execution_thread)]
           end
-          result
         end
 
         def prepared_persisted_step?
@@ -38,26 +29,6 @@ module Smith
 
         private
 
-        def activate_split_step_execution!(authorization, execution_thread)
-          @split_step_mutex.synchronize do
-            unless active_split_step_execution_authorization?(authorization)
-              raise WorkflowError, "the prepared-step execution authorization is no longer active"
-            end
-
-            ensure_split_step_definition_current!
-            ensure_prepared_split_step_transition_matches!
-            PreparedStepExecutionAuthorization.instance_method(:activate_execution!)
-                                              .bind_call(authorization, execution_thread)
-
-            @split_step_active_execution_authorization = authorization
-            @split_step_execution_result = nil
-            @split_step_phase = :executing
-            clear_split_step_execution_authorization!
-            @split_step_execution_thread = execution_thread
-            @split_step_advance_permit = true
-          end
-        end
-
         def restore_unverified_execution!(verification_token)
           @split_step_mutex.synchronize do
             next unless active_split_step_execution_verification?(verification_token)
@@ -75,23 +46,6 @@ module Smith
           raise WorkflowError, "prepared execution did not return the claimed transition"
         end
 
-        def finish_split_step_execution!(step, authorization, execution_thread)
-          @split_step_mutex.synchronize do
-            next unless @split_step_phase == :executing &&
-                        @split_step_execution_thread.equal?(execution_thread)
-
-            @split_step_execution_thread = nil
-            @split_step_advance_permit = false
-            @split_step_execution_previous_phase = nil
-            @split_step_active_execution_authorization = nil
-            @split_step_execution_result = nil
-            @split_step_phase = step ? :executed : :attempted
-          end
-        ensure
-          PreparedStepExecutionAuthorization.instance_method(:close_execution!)
-                                            .bind_call(authorization, execution_thread)
-        end
-
         def resolve_split_step_advance_transition
           @split_step_mutex.synchronize do
             unless @split_step_phase == :executing && @split_step_execution_thread.equal?(Thread.current)

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

@@ -4,36 +4,56 @@ module Smith
   class Workflow
     module SplitStepPersistence
       module ExecutionAuthorization
-        def authorize_prepared_step_execution!
-          verification_token = claim_split_step_execution_verification!
-          authorized = false
-          verify_claimed_split_step_execution!(verification_token)
-          authorization = build_split_step_execution_authorization
-          activate_split_step_execution_authorization!(authorization, verification_token)
-          authorized = true
-          authorization
-        ensure
-          restore_unverified_execution!(verification_token) if verification_token && !authorized
-        end
-
         def release_prepared_step_execution!(authorization)
           authorization = validate_split_step_execution_authorization!(authorization)
-          @split_step_mutex.synchronize do
-            unless active_split_step_execution_authorization?(authorization)
-              raise WorkflowError, "the prepared-step execution authorization is no longer active"
-            end
+          Thread.handle_interrupt(Object => :never) do
+            @split_step_mutex.synchronize do
+              unless active_split_step_execution_authorization?(authorization)
+                raise WorkflowError, "the prepared-step execution authorization is no longer active"
+              end
 
-            @split_step_phase = @split_step_execution_previous_phase
-            clear_split_step_execution_authorization!
+              @split_step_phase = @split_step_execution_previous_phase
+              clear_split_step_execution_authorization!
+            end
+            PreparedStepExecutionAuthorization
+              .instance_method(:close_execution!)
+              .bind_call(authorization)
           end
-          PreparedStepExecutionAuthorization
-            .instance_method(:close_execution!)
-            .bind_call(authorization)
           self
         end
 
         private
 
+        def authorize_claimed_prepared_step_execution!(verification_token)
+          ExecutionVerification
+            .instance_method(:verify_claimed_split_step_execution!)
+            .bind_call(self, verification_token)
+          authorization = ExecutionAuthorization
+                          .instance_method(:build_split_step_execution_authorization)
+                          .bind_call(self)
+          ExecutionAuthorization
+            .instance_method(:activate_split_step_execution_authorization!)
+            .bind_call(self, authorization, verification_token)
+          authorization
+        end
+
+        def claim_framework_execution_verification!
+          ExecutionVerification
+            .instance_method(:claim_split_step_execution_verification!)
+            .bind_call(self)
+        end
+
+        def restore_framework_execution_verification!(verification_token)
+          return unless verification_token
+
+          active = ExecutionAuthorization
+                   .instance_method(:active_split_step_execution_verification?)
+                   .bind_call(self, verification_token)
+          return unless active
+
+          Execution.instance_method(:restore_unverified_execution!).bind_call(self, verification_token)
+        end
+
         def build_split_step_execution_authorization
           PreparedStepExecutionAuthorization.new(
             prepared_step: @split_step_prepared_descriptor,