smith-agents 0.4.5 → 0.6.0

data/lib/smith/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module Smith
-  VERSION = "0.4.5"
+  VERSION = "0.6.0"
+  EXECUTION_SEMANTICS_VERSION = "2"
 end

data/lib/smith/workflow/branch_env.rb

@@ -4,7 +4,7 @@ module Smith
   class Workflow
     # rubocop:disable Style/RedundantStructKeywordInit
     BranchEnv = Struct.new(
-      :prepared_input, :guardrail_sources, :scoped_store, :branch_estimates, :deadline,
+      :prepared_input, :guardrail_sources, :scoped_store, :branch_estimates, :deadline, :agent_class,
       keyword_init: true
     ) do
       def setup_thread

data/lib/smith/workflow/budget_integration.rb

@@ -15,8 +15,7 @@ module Smith
       def reserve_branch_budget(ledger, branch_estimates:)
         return nil unless ledger && branch_estimates
 
-        branch_estimates.each { |dim, amount| ledger.reserve!(dim, amount) }
-        branch_estimates
+        reserve_estimates!(ledger, branch_estimates)
       end
 
       def compute_branch_estimates(ledger, branch_count:, agent_budget: nil)
@@ -29,13 +28,16 @@ module Smith
         end
       end
 
-      def reconcile_branch_budget(ledger, estimates, agent_result: nil)
-        return unless ledger && estimates
+      def reconcile_branch_budget(ledger, reservation, agent_result: nil)
+        return unless ledger && reservation
 
         actuals = extract_actuals(agent_results_for_settlement(agent_result))
-        estimates.each do |dim, amt|
-          ledger.reconcile!(dim, amt, actual_for_dimension(dim, actuals[:tokens], actuals[:cost]))
+        settlement = reservation.amounts.to_h do |dimension, _amount|
+          [dimension, actual_for_dimension(dimension, actuals[:tokens], actuals[:cost])]
         end
+        return ledger.reconcile_many!(reservation, actual: settlement) if settlement.length > 1
+
+        ledger.reconcile!(reservation, settlement.values.first)
       end
 
       def extract_actuals(agent_results)
@@ -66,10 +68,12 @@ module Smith
         0
       end
 
-      def release_branch_budget(ledger, estimates)
-        return unless ledger && estimates
+      def release_branch_budget(ledger, reservation)
+        return unless ledger && reservation
+
+        return ledger.release_many!(reservation) if reservation.amounts.length > 1
 
-        estimates.each { |dim, amount| ledger.release!(dim, amount) }
+        ledger.release!(reservation)
       end
 
       def settle_budget_on_failure(ledger, estimates, agent_result)
@@ -91,8 +95,14 @@ module Smith
           est[dim] = cap ? [remaining, cap].min : remaining
         end
 
-        estimates.each { |dim, amount| ledger.reserve!(dim, amount) }
-        estimates
+        reserve_estimates!(ledger, estimates)
+      end
+
+      def reserve_estimates!(ledger, estimates)
+        return ledger.reserve_many!(estimates) if estimates.length > 1
+
+        dimension, amount = estimates.first
+        ledger.reserve!(dimension, amount)
       end
 
       def finalize_branch(transition, index, result, ledger, reserved)

data/lib/smith/workflow/composite/branch.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative "../../types"
+require_relative "../message_value_normalizer"
+require_relative "../prepared_step"
+require_relative "payload"
+require_relative "payload_digest"
+
+module Smith
+  class Workflow
+    module Composite
+      class Branch < Payload
+        MAX_BUDGET_DIMENSIONS = 128
+        HASH_LENGTH = Hash.instance_method(:length)
+        HASH_EACH_PAIR = Hash.instance_method(:each_pair)
+        private_constant :HASH_LENGTH, :HASH_EACH_PAIR
+        OwnedString = Types::String.constructor { |value| value.is_a?(String) ? value.dup.freeze : value }
+        private_constant :OwnedString
+
+        attribute :ordinal, Types::Integer.constrained(gteq: 0, lteq: PreparedStep::MAX_COUNTER_VALUE)
+        attribute :key, OwnedString.constrained(min_size: 1, max_size: 256)
+        attribute :agent, OwnedString.constrained(min_size: 1, max_size: 256)
+        attribute :binding_identity, OwnedString.constrained(format: PreparedStep::DIGEST_PATTERN)
+        attribute :budget, Types::Hash
+        attribute :digest, OwnedString.constrained(format: PreparedStep::DIGEST_PATTERN)
+
+        def self.build(ordinal:, key:, agent:, binding_identity:, budget:)
+          attributes = {
+            ordinal:,
+            key: key.to_s,
+            agent: agent.to_s,
+            binding_identity:,
+            budget: normalize_budget(budget)
+          }
+          new(attributes.merge(digest: PayloadDigest.call(attributes)))
+        end
+
+        def initialize(attributes)
+          owned = self.class.normalize_attributes(attributes)
+          owned[:budget] = self.class.send(:normalize_budget, owned[:budget])
+          super(owned)
+          expected = PayloadDigest.call(to_h.except(:digest))
+          raise ArgumentError, "composite branch digest does not match" unless digest == expected
+        end
+
+        class << self
+          private
+
+          def normalize_budget(value)
+            normalized = normalized_budget(value)
+            validate_budget_dimensions!(normalized)
+            copy_budget(normalized)
+          end
+
+          def normalized_budget(value)
+            normalized = MessageValueNormalizer.new(value, label: "composite branch budget").call
+            raise ArgumentError, "composite branch budget must be a Hash" unless normalized.is_a?(Hash)
+
+            normalized
+          end
+
+          def validate_budget_dimensions!(budget)
+            return if HASH_LENGTH.bind_call(budget) <= MAX_BUDGET_DIMENSIONS
+
+            raise ArgumentError, "composite branch budget contains too many dimensions"
+          end
+
+          def copy_budget(normalized)
+            budget = {}
+            HASH_EACH_PAIR.bind_call(normalized) do |name, amount|
+              validate_budget_dimension!(name)
+              validate_budget_amount!(amount)
+              budget[name.freeze] = amount
+            end
+            budget.freeze
+          end
+
+          def validate_budget_dimension!(name)
+            return if name.length.between?(1, 256)
+
+            raise ArgumentError, "composite branch budget dimensions must be bounded non-empty strings"
+          end
+
+          def validate_budget_amount!(amount)
+            return if amount.is_a?(Numeric) && amount.finite? && amount >= 0
+
+            raise ArgumentError, "composite branch budget values must be finite non-negative numbers"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/smith/workflow/composite/branch_budget_contract.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "budget_allocator"
+require_relative "plan"
+
+module Smith
+  class Workflow
+    module Composite
+      module BranchBudgetContract
+        private
+
+        def validate_composite_branch_count!(count)
+          Plan.validate_branch_count!(count)
+        end
+
+        def composite_budget_allocator(branch_count)
+          return unless @ledger
+
+          BudgetAllocator.new(ledger: @ledger, branch_count:)
+        end
+
+        def composite_branch_budget(allocator, ordinal, agent_budget)
+          return {} unless allocator
+
+          caps = @ledger.limits.each_key.with_object({}) do |dimension, result|
+            cap = agent_cap_for_dimension(dimension, agent_budget)
+            result[dimension] = cap unless cap.nil?
+          end
+          allocator.call(ordinal:, caps:)
+        end
+
+        def composite_binding_identity!(agent_class, agent)
+          identity = agent_class&.execution_identity
+          return identity if identity
+
+          raise WorkflowError, "durable composite agent :#{agent} requires an execution_identity"
+        end
+      end
+    end
+  end
+end

data/lib/smith/workflow/composite/branch_contract.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require_relative "../parallel"
+require_relative "branch"
+require_relative "branch_budget_contract"
+require_relative "fanout_branch_contract"
+
+module Smith
+  class Workflow
+    module Composite
+      module BranchContract
+        include BranchBudgetContract
+        include FanoutBranchContract
+
+        private
+
+        def composite_branch_specs(authorization, transition, branch_count: nil)
+          return parallel_branch_specs(authorization, transition, branch_count:) if transition.parallel?
+
+          fanout_branch_specs(authorization, transition)
+        end
+
+        def parallel_branch_specs(authorization, transition, branch_count: nil)
+          validate_planned_parallel_count!(transition, branch_count) if branch_count
+          count = branch_count || Parallel.resolve_branch_count(transition, @context)
+          validate_composite_branch_count!(count)
+          agent = transition.agent_name
+          agent_class = captured_agent(authorization, transition, agent, :agent)
+          allocator = composite_budget_allocator(count)
+          Array.new(count) do |ordinal|
+            parallel_branch_spec(agent, agent_class, allocator, ordinal).merge(key: ordinal.to_s)
+          end.freeze
+        end
+
+        def parallel_branch_spec(agent, agent_class, allocator, ordinal)
+          {
+            agent: agent.to_s,
+            binding_identity: composite_binding_identity!(agent_class, agent),
+            budget: composite_branch_budget(allocator, ordinal, agent_class&.budget)
+          }.freeze
+        end
+
+        def validate_planned_parallel_count!(transition, branch_count)
+          Parallel.validate_branch_count!(branch_count)
+          configured = transition.agent_opts[:count]
+          return if configured.respond_to?(:call)
+          return if branch_count == (configured || 1)
+
+          raise WorkflowError, "composite plan branch count does not match the prepared transition"
+        end
+
+        def captured_agent(authorization, transition, agent, role)
+          authorization.fetch_agent!(
+            agent,
+            workflow_class: self.class,
+            transition_name: transition.name,
+            role:
+          )
+        end
+
+        def validate_composite_branches!(authorization, plan, transition)
+          specs = composite_branch_specs(authorization, transition, branch_count: plan.branches.length)
+          specs.each_with_index do |spec, ordinal|
+            expected = comparable_branch(Branch.build(ordinal:, **spec))
+            actual = comparable_branch(plan.branches.fetch(ordinal))
+            next if actual == expected
+
+            raise WorkflowError, "composite plan branches do not match the prepared transition"
+          end
+        end
+
+        def validate_composite_selected_branch!(authorization, execution, transition)
+          branch = execution.branch
+          spec = selected_branch_spec(authorization, execution, transition)
+          candidate = Branch.build(ordinal: branch.ordinal, **spec)
+          raise WorkflowError, "composite branch does not match the prepared transition" unless
+            comparable_branch(candidate) == comparable_branch(branch)
+        end
+
+        def selected_branch_spec(authorization, execution, transition)
+          return selected_parallel_branch_spec(authorization, execution, transition) if transition.parallel?
+
+          selected_fanout_branch_spec(authorization, execution, transition)
+        end
+
+        def selected_parallel_branch_spec(authorization, execution, transition)
+          branch = execution.branch
+          count = execution.branch_count
+          validate_planned_parallel_count!(transition, count)
+          agent = transition.agent_name
+          agent_class = captured_agent(authorization, transition, agent, :agent)
+          allocator = composite_budget_allocator(count)
+          parallel_branch_spec(agent, agent_class, allocator, branch.ordinal).merge(key: branch.ordinal.to_s)
+        end
+
+        def comparable_branch(branch)
+          [branch.ordinal, branch.key, branch.agent, branch.binding_identity, branch.budget]
+        end
+      end
+    end
+  end
+end

data/lib/smith/workflow/composite/branch_execution.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require_relative "../../types"
+require_relative "../prepared_step"
+require_relative "../prepared_step_dispatch"
+require_relative "branch"
+require_relative "enums"
+require_relative "payload"
+require_relative "payload_digest"
+require_relative "plan"
+
+module Smith
+  class Workflow
+    module Composite
+      class BranchExecution < Payload
+        VERSION = 1
+        ENUM_ATTRIBUTES = %i[kind resume_policy failure_policy reduction_policy retry_policy].freeze
+        private_constant :ENUM_ATTRIBUTES
+        OwnedString = Types::String.constructor { |value| value.is_a?(String) ? value.dup.freeze : value }
+        private_constant :OwnedString
+
+        attribute :version, Types::Integer.enum(VERSION)
+        attribute :execution_semantics_version, OwnedString.constrained(min_size: 1, max_size: 32)
+        attribute :dispatch, Types.Instance(PreparedStepDispatch)
+        attribute :plan_digest, OwnedString.constrained(format: PreparedStep::DIGEST_PATTERN)
+        attribute :kind, Types::Symbol.enum(:parallel, :fanout)
+        attribute :transition, OwnedString.constrained(min_size: 1, max_size: 256)
+        attribute :from, OwnedString.constrained(min_size: 1, max_size: 256)
+        attribute :execution_namespace, OwnedString.constrained(format: PreparedStep::UUID_PATTERN)
+        attribute :branch_count, Types::Integer.constrained(gteq: 1, lteq: Plan::MAX_BRANCHES)
+        attribute :input_digest, OwnedString.constrained(format: PreparedStep::DIGEST_PATTERN)
+        attribute :budget_state_digest, OwnedString.constrained(format: PreparedStep::DIGEST_PATTERN)
+        attribute :resume_policy, Types::Symbol.enum(Plan::RESUME_POLICY)
+        attribute :failure_policy, Types::Symbol.enum(Plan::FAILURE_POLICY)
+        attribute :reduction_policy, Types::Symbol.enum(Plan::REDUCTION_POLICY)
+        attribute :retry_policy, Types::Symbol.enum(Plan::RETRY_POLICY)
+        attribute :branch, Types.Instance(Branch)
+        attribute :digest, OwnedString.constrained(format: PreparedStep::DIGEST_PATTERN)
+
+        class << self
+          def build(plan:, branch:)
+            validate_plan_branch!(plan, branch)
+            values = execution_attributes(plan, branch)
+            new(values.merge(digest: PayloadDigest.call(serializable(values))))
+          end
+
+          def normalize_attributes(attributes)
+            normalized = super
+            normalize_dispatch!(normalized)
+            normalize_branch!(normalized)
+            ENUM_ATTRIBUTES.each { |key| normalized[key] = Enums.normalize(key, normalized[key]) }
+            normalized
+          end
+
+          def serializable(values)
+            values.merge(dispatch: values.fetch(:dispatch).to_h, branch: values.fetch(:branch).to_h)
+          end
+
+          private
+
+          def execution_attributes(plan, branch)
+            {
+              version: VERSION,
+              execution_semantics_version: plan.execution_semantics_version,
+              dispatch: plan.dispatch,
+              plan_digest: plan.plan_digest,
+              kind: plan.kind,
+              transition: plan.transition,
+              from: plan.from,
+              execution_namespace: plan.execution_namespace,
+              branch_count: plan.branches.length,
+              input_digest: plan.input_digest,
+              budget_state_digest: plan.budget_state_digest,
+              resume_policy: plan.resume_policy,
+              failure_policy: plan.failure_policy,
+              reduction_policy: plan.reduction_policy,
+              retry_policy: plan.retry_policy,
+              branch:
+            }
+          end
+
+          def validate_plan_branch!(plan, branch)
+            raise ArgumentError, "plan must be a Smith composite plan" unless plan.is_a?(Plan)
+            raise ArgumentError, "branch must be a Smith composite branch" unless branch.is_a?(Branch)
+
+            expected = plan.branches.fetch(branch.ordinal) do
+              raise ArgumentError, "composite branch ordinal is invalid"
+            end
+            raise ArgumentError, "composite branch does not belong to plan" unless expected.to_h == branch.to_h
+          end
+
+          def normalize_dispatch!(attributes)
+            value = attributes[:dispatch]
+            attributes[:dispatch] = PreparedStepDispatch.deserialize(value) unless value.is_a?(PreparedStepDispatch)
+          end
+
+          def normalize_branch!(attributes)
+            value = attributes[:branch]
+            attributes[:branch] = Branch.deserialize(value) unless value.is_a?(Branch)
+          end
+        end
+
+        def initialize(attributes)
+          owned = self.class.normalize_attributes(attributes)
+          super(owned)
+          validate_contract!
+        end
+
+        private
+
+        def validate_contract!
+          Plan.validate_branch_count!(branch_count)
+          raise ArgumentError, "composite branch ordinal exceeds branch count" if branch.ordinal >= branch_count
+          unless execution_semantics_version == Smith::EXECUTION_SEMANTICS_VERSION
+            raise ArgumentError, "composite branch execution semantics do not match"
+          end
+
+          expected = PayloadDigest.call(self.class.serializable(to_h.except(:digest)))
+          raise ArgumentError, "composite branch execution digest does not match" unless digest == expected
+        end
+      end
+    end
+  end
+end

data/lib/smith/workflow/composite/branch_failure.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require_relative "../../errors"
+require_relative "error"
+
+module Smith
+  class Workflow
+    module Composite
+      class BranchFailure < WorkflowError
+        DETAIL_KEYS = {
+          "branch_key" => :branch_key,
+          "error_class" => :error_class,
+          "error_family" => :error_family,
+          "retryable" => :retryable,
+          "kind" => :kind
+        }.freeze
+        DETAIL_NAMES = DETAIL_KEYS.values.freeze
+        private_constant :DETAIL_KEYS, :DETAIL_NAMES
+
+        attr_reader :branch_key, :error_class, :error_family, :retryable, :kind, :details
+
+        def self.from_details(details)
+          values = normalize_details(details)
+          error = Error.new(
+            class_name: values.fetch(:error_class),
+            family: values.fetch(:error_family),
+            retryable: values.fetch(:retryable),
+            kind: values.fetch(:kind)
+          )
+          new(branch_key: values.fetch(:branch_key), error:)
+        end
+
+        def self.normalize_details(details)
+          raise ArgumentError, "composite branch failure details must be a Hash" unless details.is_a?(Hash)
+
+          normalized = {}
+          Hash.instance_method(:each_pair).bind_call(details) do |key, value|
+            name = normalize_detail_key(key)
+            if normalized.key?(name)
+              raise ArgumentError, "composite branch failure details contain a duplicate attribute"
+            end
+
+            normalized[name] = value
+          end
+          missing = DETAIL_NAMES - normalized.keys
+          raise ArgumentError, "composite branch failure details are missing required attributes" if missing.any?
+
+          normalized
+        end
+
+        def self.normalize_detail_key(key)
+          name = key.is_a?(Symbol) ? key : DETAIL_KEYS.fetch(key, key)
+          return name if DETAIL_NAMES.include?(name)
+
+          raise ArgumentError, "composite branch failure details contain an unknown attribute"
+        end
+        private_class_method :normalize_details
+        private_class_method :normalize_detail_key
+
+        def initialize(branch_key:, error:)
+          validate_arguments!(branch_key, error)
+          @branch_key = branch_key.dup.freeze
+          @error_class = error.class_name.dup.freeze
+          @error_family = error.family.dup.freeze
+          @retryable = error.retryable
+          @kind = error.kind&.dup&.freeze
+          @details = failure_details
+          super("composite branch #{branch_key.inspect} failed")
+        end
+
+        private
+
+        def validate_arguments!(branch_key, error)
+          valid_key = branch_key.is_a?(String) && branch_key.length.between?(1, 256)
+          raise ArgumentError, "composite branch failure key must be a bounded non-empty String" unless valid_key
+          raise ArgumentError, "composite branch failure requires typed error evidence" unless error.is_a?(Error)
+        end
+
+        def failure_details
+          {
+            branch_key: @branch_key,
+            error_class: @error_class,
+            error_family: @error_family,
+            retryable: @retryable,
+            kind: @kind
+          }.freeze
+        end
+      end
+    end
+  end
+end

data/lib/smith/workflow/composite/branch_outcome.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require_relative "../../types"
+require_relative "../message_value_normalizer"
+require_relative "../prepared_step"
+require_relative "effects"
+require_relative "enums"
+require_relative "error"
+require_relative "payload"
+require_relative "payload_digest"
+
+module Smith
+  class Workflow
+    module Composite
+      class BranchOutcome < Payload
+        OwnedString = Types::String.constructor { |value| value.is_a?(String) ? value.dup.freeze : value }
+        private_constant :OwnedString
+
+        attribute :plan_digest, OwnedString.constrained(format: PreparedStep::DIGEST_PATTERN)
+        attribute :branch_digest, OwnedString.constrained(format: PreparedStep::DIGEST_PATTERN)
+        attribute :ordinal, Types::Integer.constrained(gteq: 0, lteq: PreparedStep::MAX_COUNTER_VALUE)
+        attribute :branch_key, OwnedString.constrained(min_size: 1, max_size: 256)
+        attribute :agent, OwnedString.constrained(min_size: 1, max_size: 256)
+        attribute :status, Types::Symbol.enum(:succeeded, :failed)
+        attribute? :output, Types::Any.optional
+        attribute? :error, Types.Instance(Error).optional
+        attribute :effects, Types.Instance(Effects)
+        attribute :digest, OwnedString.constrained(format: PreparedStep::DIGEST_PATTERN)
+
+        class << self
+          def succeeded(plan_digest:, branch:, output:, effects:)
+            build(plan_digest:, branch:, effects:, status: :succeeded, output:, error: nil)
+          end
+
+          def failed(plan_digest:, branch:, error:, effects:)
+            build(plan_digest:, branch:, effects:, status: :failed, output: nil, error:)
+          end
+
+          def normalize_attributes(attributes)
+            normalized = super
+            normalize_status!(normalized)
+            normalize_error!(normalized)
+            normalize_effects!(normalized)
+            normalized
+          end
+
+          private
+
+          def build(plan_digest:, branch:, effects:, **result)
+            values = {
+              plan_digest:,
+              branch_digest: branch.digest,
+              ordinal: branch.ordinal,
+              branch_key: branch.key,
+              agent: branch.agent,
+              status: result.fetch(:status),
+              output: normalize_output(result.fetch(:output)),
+              error: result.fetch(:error),
+              effects:
+            }
+            new(values.merge(digest: PayloadDigest.call(serializable(values))))
+          end
+
+          def normalize_status!(attributes)
+            attributes[:status] = Enums.normalize(:status, attributes[:status])
+          end
+
+          def normalize_error!(attributes)
+            error = attributes[:error]
+            attributes[:error] = Error.deserialize(error) if error && !error.is_a?(Error)
+          end
+
+          def normalize_effects!(attributes)
+            effects = attributes[:effects]
+            attributes[:effects] = Effects.deserialize(effects) unless effects.is_a?(Effects)
+          end
+
+          def normalize_output(value)
+            MessageValueNormalizer.new(value, label: "composite branch output").call
+          end
+
+          def serializable(values)
+            values.merge(error: values[:error]&.to_h, effects: values.fetch(:effects).to_h)
+          end
+        end
+
+        def initialize(attributes)
+          owned = self.class.normalize_attributes(attributes)
+          owned[:output] = self.class.send(:normalize_output, owned[:output])
+          super(owned)
+          validate_shape!
+          expected = PayloadDigest.call(self.class.send(:serializable, to_h.except(:digest)))
+          raise ArgumentError, "composite branch outcome digest does not match" unless digest == expected
+        end
+
+        def succeeded? = status == :succeeded
+        def failed? = status == :failed
+
+        private
+
+        def validate_shape!
+          valid = succeeded? ? error.nil? : error && output.nil?
+          raise ArgumentError, "composite branch outcome fields do not match status" unless valid
+        end
+      end
+    end
+  end
+end