smith-agents 0.4.5 → 0.6.0

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/definition_boundary.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      module DefinitionBoundary
+        private
+
+        def restart_safe_split_step? = !effective_definition_digest.nil?
+
+        def ensure_split_step_definition_current!
+          return if effective_definition_digest == self.class.definition_digest
+
+          raise WorkflowError, "the prepared workflow definition has changed"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      module DispatchBoundary
+        private
+
+        def dispatch_store!(...)
+          @split_step_dispatch_started = true if @split_step_phase == :preparing
+          super
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      module DispatchClaim
+        def claim_prepared_step_dispatch!
+          ensure_restart_safe_dispatch_claim!
+          ensure_split_step_definition_current!
+          transaction_identity = TransactionIdentity.capture(@split_step_adapter)
+          claim_dispatch_intent!
+          payload, descriptor = build_split_step_dispatch_claim
+          dispatch_started = true
+          replace_exact_dispatch!(payload)
+          accept_split_step_dispatch!(payload, descriptor, transaction_identity)
+          descriptor
+        rescue PersistencePayloadConflict
+          reject_split_step_dispatch!
+          raise
+        rescue StandardError
+          if dispatch_started
+            mark_split_step_dispatch_unknown!(payload, descriptor)
+          else
+            restore_unclaimed_dispatch!
+          end
+          raise
+        end
+
+        private
+
+        def ensure_restart_safe_dispatch_claim!
+          return if restart_safe_split_step?
+
+          raise WorkflowError, "restart-safe dispatch claiming requires a definition_digest"
+        end
+
+        def split_step_dispatch_payload(token)
+          document = JSON.parse(@split_step_preparation_payload)
+          document["split_step_phase"] = "dispatching"
+          document["split_step_dispatch_token"] = token
+          JSON.generate(document)
+        end
+
+        def build_split_step_dispatch_claim
+          token = SecureRandom.uuid.freeze
+          payload = split_step_dispatch_payload(token)
+          [payload, build_split_step_dispatch(token, payload)]
+        end
+
+        def replace_exact_dispatch!(payload)
+          @split_step_adapter.replace_exact(
+            @split_step_persistence_key,
+            payload,
+            expected_payload: @split_step_preparation_payload,
+            ttl: nil
+          )
+        end
+
+        def build_split_step_dispatch(token, payload)
+          PreparedStepDispatch.new(
+            prepared_step: @split_step_prepared_descriptor,
+            token:,
+            dispatch_digest: CanonicalPayloadDigest.call(payload)
+          )
+        end
+
+        def accept_split_step_dispatch!(payload, descriptor, transaction_identity)
+          @split_step_mutex.synchronize do
+            unless active_split_step_dispatch_claim?
+              raise WorkflowError, "the prepared dispatch claim is no longer active"
+            end
+
+            @split_step_pre_dispatch_payload = @split_step_preparation_payload
+            @split_step_preparation_payload = payload.freeze
+            @split_step_dispatch_token = descriptor.token
+            @split_step_dispatch_descriptor = descriptor
+            @split_step_dispatch_thread = nil
+            @split_step_phase = transaction_identity ? :dispatch_claimed_uncommitted : :dispatch_claimed
+          end
+        end
+
+        def reject_split_step_dispatch!
+          @split_step_mutex.synchronize do
+            next unless active_split_step_dispatch_claim?
+
+            @split_step_dispatch_thread = nil
+            @split_step_phase = :dispatch_rejected
+          end
+        end
+
+        def restore_unclaimed_dispatch!
+          @split_step_mutex.synchronize do
+            next unless active_split_step_dispatch_claim?
+
+            @split_step_dispatch_thread = nil
+            @split_step_phase = :prepared
+          end
+        end
+
+        def mark_split_step_dispatch_unknown!(payload, descriptor)
+          @split_step_mutex.synchronize do
+            next unless active_split_step_dispatch_claim?
+
+            @split_step_attempted_dispatch_payload = payload&.freeze
+            @split_step_dispatch_token = descriptor&.token
+            @split_step_attempted_dispatch_descriptor = descriptor
+            @split_step_dispatch_thread = nil
+            @split_step_phase = :dispatch_unknown
+          end
+        end
+
+        def active_split_step_dispatch_claim?
+          @split_step_phase == :claiming_dispatch && @split_step_dispatch_thread.equal?(Thread.current)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      module DispatchConfirmation
+        def confirm_prepared_step_dispatch!
+          confirmation_claimed = false
+          rolled_back = false
+          claim_dispatch_confirmation!
+          confirmation_claimed = true
+          payload = @split_step_adapter.fetch(@split_step_persistence_key)
+          return confirm_committed_dispatch! if persisted_split_step_payload?(payload, @split_step_preparation_payload)
+
+          rolled_back = recover_rolled_back_dispatch!(payload)
+          raise WorkflowError, "the persisted split-step dispatch claim is not committed"
+        rescue StandardError
+          mark_unconfirmed_dispatch_unknown! if confirmation_claimed && !rolled_back
+          raise
+        end
+
+        private
+
+        def claim_dispatch_confirmation!
+          @split_step_mutex.synchronize do
+            unless @split_step_phase == :dispatch_claimed_uncommitted
+              raise WorkflowError, "no uncommitted split-step dispatch claim is awaiting confirmation"
+            end
+            if @split_step_adapter.transaction_open?
+              raise WorkflowError, "the split-step dispatch transaction is still open"
+            end
+
+            @split_step_phase = :confirming_dispatch
+          end
+        end
+
+        def confirm_committed_dispatch!
+          @split_step_mutex.synchronize do
+            @split_step_phase = :dispatch_claimed
+            clear_split_step_dispatch_transaction!
+          end
+          self
+        end
+
+        def recover_rolled_back_dispatch!(payload)
+          return false unless persisted_split_step_payload?(payload, @split_step_pre_dispatch_payload)
+
+          @split_step_mutex.synchronize do
+            return false unless @split_step_phase == :confirming_dispatch
+
+            @split_step_preparation_payload = @split_step_pre_dispatch_payload
+            @split_step_phase = :prepared
+            clear_split_step_dispatch_transaction!
+            true
+          end
+        end
+
+        def mark_unconfirmed_dispatch_unknown!
+          @split_step_mutex.synchronize do
+            @split_step_phase = :dispatch_unknown if @split_step_phase == :confirming_dispatch
+          end
+        end
+
+        def clear_split_step_dispatch_transaction!
+          @split_step_pre_dispatch_payload = nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      module DispatchVerification
+        private
+
+        def claim_dispatch_intent!
+          @split_step_mutex.synchronize do
+            raise WorkflowError, "no persisted step is prepared" unless @split_step_phase == :prepared
+
+            ensure_prepared_split_step_transition_matches!
+            @split_step_phase = :claiming_dispatch
+            @split_step_dispatch_thread = Thread.current
+          end
+        end
+
+        def verify_split_step_dispatch_available!(verification_token)
+          payload = @split_step_adapter.fetch(@split_step_persistence_key)
+          return if persisted_split_step_payload?(payload, @split_step_preparation_payload)
+
+          @split_step_mutex.synchronize do
+            if active_split_step_execution_verification?(verification_token)
+              @split_step_phase = :dispatch_unknown
+              @split_step_execution_previous_phase = nil
+              clear_split_step_execution_verification!
+            end
+          end
+          raise PersistencePayloadConflict.new(key: @split_step_persistence_key)
+        end
+      end
+    end
+  end
+end

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

@@ -5,74 +5,38 @@ module Smith
     module SplitStepPersistence
       module Execution
         def execute_prepared_step!
-          execution_started = false
-          step = nil
-          claim_split_step_execution_verification!
-          begin
-            verify_split_step_preparation_available!
-            activate_split_step_execution!
-            execution_started = true
-            step = execute_claimed_split_step_transition!
-          ensure
-            execution_started ? finish_split_step_execution!(step) : restore_unverified_execution!
-          end
-          step
-        end
-
-        def prepared_persisted_step? = @split_step_mutex.synchronize { @split_step_phase == :prepared }
-
-        private
-
-        def claim_split_step_execution_verification!
-          @split_step_mutex.synchronize do
-            raise WorkflowError, "no persisted step is prepared" unless @split_step_phase == :prepared
-            raise WorkflowError, "the prepared transition no longer matches the workflow" unless
-              prepared_split_step_transition_matches?
-
-            @split_step_phase = :verifying_execution
+          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 prepared_split_step_transition_matches?
-          transition = pending_split_step_transition
-          transition_name = @next_transition_name || transition&.name
-          transition_name == @split_step_transition_name &&
-            transition.equal?(@split_step_transition) &&
-            split_step_transition_signature(transition) == @split_step_transition_signature
-        end
-
-        def activate_split_step_execution!
-          @split_step_mutex.synchronize do
-            unless @split_step_phase == :verifying_execution
-              raise WorkflowError, "the prepared execution claim is no longer active"
-            end
-
-            @split_step_phase = :executing
-            @split_step_execution_thread = Thread.current
-            @split_step_advance_permit = true
+        def execute_authorized_prepared_step!(authorization)
+          perform_authorized_prepared_step_execution!(authorization) do |execution_thread|
+            step = execute_claimed_split_step_transition!
+            [step, consume_split_step_execution_result!(execution_thread)]
           end
         end
 
-        def restore_unverified_execution!
+        def prepared_persisted_step?
           @split_step_mutex.synchronize do
-            @split_step_phase = :prepared if @split_step_phase == :verifying_execution
+            expected = restart_safe_split_step? ? :dispatch_claimed : :prepared
+            [expected, :execution_authorized].include?(@split_step_phase)
           end
         end
 
-        def verify_split_step_preparation_available!
-          payload = @split_step_adapter.fetch(@split_step_persistence_key)
-          durable = persisted_split_step_payload?(payload, @split_step_preparation_payload)
-          live = persisted_split_step_payload?(current_split_step_preparation_payload, @split_step_preparation_payload)
-          stable = split_step_transition_signature(@split_step_transition) == @split_step_transition_signature
-          return if durable && live && stable
+        private
 
-          raise WorkflowError, "the persisted split-step preparation is no longer available"
-        end
+        def restore_unverified_execution!(verification_token)
+          @split_step_mutex.synchronize do
+            next unless active_split_step_execution_verification?(verification_token)
 
-        def current_split_step_preparation_payload
-          split_step_preparation_payload(
-            JSON.generate(to_state.merge(persistence_version: @persistence_version))
-          )
+            @split_step_phase = @split_step_execution_previous_phase
+            @split_step_execution_previous_phase = nil
+            clear_split_step_execution_verification!
+          end
         end
 
         def execute_claimed_split_step_transition!
@@ -82,14 +46,6 @@ module Smith
           raise WorkflowError, "prepared execution did not return the claimed transition"
         end
 
-        def finish_split_step_execution!(step)
-          @split_step_mutex.synchronize do
-            @split_step_execution_thread = nil
-            @split_step_advance_permit = false
-            @split_step_phase = step ? :executed : :attempted
-          end
-        end
-
         def resolve_split_step_advance_transition
           @split_step_mutex.synchronize do
             unless @split_step_phase == :executing && @split_step_execution_thread.equal?(Thread.current)