smith-agents 0.4.5 → 0.5.0

data/lib/smith/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module Smith
-  VERSION = "0.4.5"
+  VERSION = "0.5.0"
+  EXECUTION_SEMANTICS_VERSION = "1"
 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/definition_identity/class_methods.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module DefinitionIdentity
+      module ClassMethods
+        def inherited(subclass)
+          super
+          digest = definition_identity_mutex.synchronize { @definition_digest }
+          subclass.instance_variable_set(:@definition_digest, digest)
+          subclass.instance_variable_set(:@definition_identity_mutex, Mutex.new)
+          subclass.instance_variable_set(:@definition_identity_sealed, false)
+        end
+
+        def definition_digest(value = nil)
+          return definition_identity_mutex.synchronize { @definition_digest } if value.nil?
+
+          unless Smith::Types::Sha256Hex.valid?(value)
+            raise ArgumentError, "definition_digest must be a lowercase SHA-256 hex digest"
+          end
+
+          digest = value.dup.freeze
+          definition_identity_mutex.synchronize do
+            return @definition_digest if @definition_digest == digest
+            if @definition_identity_sealed || frozen?
+              raise ArgumentError, "definition_digest is sealed for this workflow class"
+            end
+
+            @definition_digest = digest
+          end
+        end
+
+        private
+
+        def seal_definition_identity!
+          definition_identity_mutex.synchronize do
+            @definition_identity_sealed = true unless frozen?
+            @definition_digest
+          end
+        end
+
+        def definition_identity_mutex
+          @definition_identity_mutex ||= Mutex.new
+        end
+      end
+    end
+  end
+end

data/lib/smith/workflow/definition_identity.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "definition_identity/class_methods"
+
+module Smith
+  class Workflow
+    module DefinitionIdentity
+      def self.included(base)
+        base.instance_variable_set(:@definition_identity_mutex, Mutex.new)
+        base.instance_variable_set(:@definition_identity_sealed, false)
+        base.extend(ClassMethods)
+      end
+
+      private
+
+      def effective_definition_digest
+        if instance_variable_defined?(:@split_step_definition_digest)
+          @split_step_definition_digest
+        else
+          self.class.definition_digest
+        end
+      end
+    end
+  end
+end

data/lib/smith/workflow/deterministic_step.rb

@@ -23,8 +23,8 @@ module Smith
       def last_output
         return @last_output if defined?(@last_output)
 
-        msg = session_messages.reverse.find { |m| m[:role] == :assistant || m[:role] == "assistant" }
-        @last_output = msg&.dig(:content)
+        msg = session_messages.reverse.find { |m| m[:role] == :assistant || m["role"] == "assistant" }
+        @last_output = msg && (msg[:content] || msg["content"])
       end
 
       alias_method :output, :last_output

data/lib/smith/workflow/dsl.rb

@@ -12,6 +12,12 @@ module Smith
           super
           subclass.instance_variable_set(:@states, (@states || []).dup)
           subclass.instance_variable_set(:@transitions, (@transitions || {}).dup)
+          subclass.instance_variable_set(
+            :@transitions_by_state,
+            duplicate_transition_index(@transitions_by_state)
+          )
+          subclass.instance_variable_set(:@transition_order, (@transition_order || {}).dup)
+          subclass.instance_variable_set(:@transition_sequence, @transition_sequence)
           subclass.instance_variable_set(:@initial_state_name, @initial_state_name)
           subclass.instance_variable_set(:@budget_config, @budget_config&.dup)
           subclass.instance_variable_set(:@max_transitions_count, @max_transitions_count)
@@ -29,19 +35,24 @@ module Smith
         def initial_state(name = nil)
           return @initial_state_name if name.nil?
 
-          @initial_state_name = name
-          state(name)
+          @initial_state_name = own_identifier(name)
+          state(@initial_state_name)
         end
 
         def state(name)
+          name = own_identifier(name)
           @states ||= []
           @states << name unless @states.include?(name)
           generate_fail_transition if name == :failed
         end
 
         def transition(name, from:, to:, &)
+          declared = Transition.new(name, from: from, to: to, &)
+          name = declared.name
           @transitions ||= {}
-          @transitions[name] = Transition.new(name, from: from, to: to, &)
+          remove_from_transition_index(@transitions[name]) if @transitions.key?(name)
+          @transitions[name] = declared
+          insert_into_transition_index(declared)
         end
 
         def budget(**opts)
@@ -196,13 +207,25 @@ module Smith
         end
 
         def transitions_from(state)
-          (@transitions || {}).values.select { |t| t.from == state }
+          transitions_by_state.fetch(state, []).dup
+        end
+
+        def first_transition_from(state)
+          transitions_by_state.fetch(state, []).first
+        end
+
+        def transition_from?(state)
+          transitions_by_state.fetch(state, []).any?
         end
 
         def find_transition(name)
           (@transitions || {})[name]
         end
 
+        def transition_at(index)
+          (@transitions || {}).values.fetch(index)
+        end
+
         def from_state(hash)
           workflow = allocate
           workflow.send(:restore_state, hash)
@@ -211,11 +234,56 @@ module Smith
 
         private
 
+        def own_identifier(identifier)
+          Identifier.normalize(identifier, label: "workflow identifier")
+        end
+
+        def transitions_by_state
+          @transitions_by_state ||= Hash.new { |index, state| index[state] = [] }
+        end
+
+        def transition_order
+          @transition_order ||= {}
+        end
+
+        def transition_sequence
+          @transition_sequence ||= 0
+        end
+
+        def insert_into_transition_index(transition)
+          order = transition_order_for(transition.name)
+          indexed = transitions_by_state[transition.from]
+          insertion = indexed.bsearch_index { |candidate| transition_order.fetch(candidate.name) > order }
+          indexed.insert(insertion || indexed.length, transition)
+        end
+
+        def transition_order_for(name)
+          return transition_order.fetch(name) if transition_order.key?(name)
+
+          transition_order[name] = transition_sequence
+          @transition_sequence = transition_sequence + 1
+          transition_order.fetch(name)
+        end
+
+        def duplicate_transition_index(source)
+          source.to_h.each_with_object(Hash.new { |index, state| index[state] = [] }) do |(state, transitions), copy|
+            copy[state] = transitions.dup
+          end
+        end
+
+        def remove_from_transition_index(transition)
+          return unless transition
+
+          indexed = transitions_by_state[transition.from]
+          indexed.delete(transition)
+          transitions_by_state.delete(transition.from) if indexed.empty?
+        end
+
         def generate_fail_transition
           @transitions ||= {}
           return if @transitions.key?(:fail)
 
-          @transitions[:fail] = Transition.new(:fail, from: nil, to: :failed)
+          transition(:fail, from: nil, to: :failed)
         end
       end
     end

data/lib/smith/workflow/durability.rb

@@ -164,7 +164,7 @@ module Smith
 
           klass = Object.const_get(class_name)
           state = state_name_for_payload(klass, state_name)
-          klass.transitions_from(state).empty? && next_transition.nil?
+          !klass.transition_from?(state) && next_transition.nil?
         rescue JSON::ParserError, NameError, NoMethodError
           false
         end

data/lib/smith/workflow/evaluator_optimizer.rb

@@ -12,13 +12,13 @@ module Smith
 
       def execute_optimization_step(transition, prepared_input: nil)
         state = OptimizationState.new(transition.optimization_config, prepared_input)
-        state.generator_class = Agent::Registry.fetch!(
+        state.generator_class = resolve_registered_agent!(
           state.config[:generator],
           workflow_class: self.class,
           transition_name: transition.name,
           role: :generator
         )
-        state.evaluator_class = Agent::Registry.fetch!(
+        state.evaluator_class = resolve_registered_agent!(
           state.config[:evaluator],
           workflow_class: self.class,
           transition_name: transition.name,
@@ -143,28 +143,24 @@ module Smith
       end
 
       def invoke_with_evaluator_schema(evaluator_class, schema, input)
-        original_schema = evaluator_class.output_schema
-        evaluator_class.output_schema(schema)
-        invoke_agent_with_budget(evaluator_class, input)
-      ensure
-        evaluator_class.output_schema(original_schema)
+        invoke_agent_with_budget(evaluator_class, input, output_schema: schema)
       end
 
-      def invoke_agent_with_budget(agent_class, prepared_input)
+      def invoke_agent_with_budget(agent_class, prepared_input, output_schema: agent_class.output_schema)
         Thread.current[:smith_last_agent_result] = nil
         clear_failed_billable_attempts
         with_agent_context(agent_class) do
-          invoke_with_call_ledger(agent_class, prepared_input)
+          invoke_with_call_ledger(agent_class, prepared_input, output_schema:)
         end
       ensure
         clear_failed_billable_attempts
       end
 
-      def invoke_with_call_ledger(agent_class, prepared_input)
+      def invoke_with_call_ledger(agent_class, prepared_input, output_schema:)
         ledger = effective_call_ledger
         reserved = reserve_serial_budget(ledger, agent_budget: agent_class&.budget)
         begin
-          result = invoke_agent(agent_class, prepared_input)
+          result = invoke_agent(agent_class, prepared_input, output_schema:)
           agent_result = result.is_a?(AgentResult) ? result : nil
           reconcile_branch_budget(ledger, reserved, agent_result: agent_result)
           reserved = nil

data/lib/smith/workflow/execution.rb

@@ -1,10 +1,14 @@
 # frozen_string_literal: true
 
 require_relative "agent_result"
+require_relative "execution_binding_resolution"
+require_relative "step_completion"
 
 module Smith
   class Workflow
     module Execution
+      include ExecutionBindingResolution
+      include StepCompletion
       include Agent::Lifecycle
       include NestedExecution
       include EvaluatorOptimizer
@@ -19,11 +23,10 @@ module Smith
       def execute_step(transition)
         setup_step_context
         output = with_scoped_artifacts { run_with_retry_policy(transition) }
-        complete_step(transition, output)
+        StepCompletion.instance_method(:complete_step).bind_call(self, transition, output)
       rescue StandardError => e
         @outcome = nil
-        handle_step_failure(transition, e)
-        { transition: transition.name, from: transition.from, to: transition.to, error: e }
+        GuardrailIntegration.instance_method(:handle_step_failure).bind_call(self, transition, e)
       ensure
         teardown_step_context
       end
@@ -43,6 +46,7 @@ module Smith
       end
 
       def run_guarded_step(transition)
+        @resolved_parallel_branch_count = preflight_branch_count(transition)
         return dispatch_step(transition) if transition.deterministic?
         return run_guarded_fanout_step(transition) if transition.fanout?
 
@@ -58,22 +62,14 @@ module Smith
         validate_data_volume!(output, agent_class)
         run_output_guardrails(output, agent_class)
         resolve_router_output(transition, output)
+      ensure
+        @resolved_parallel_branch_count = nil
       end
 
-      def complete_step(transition, output)
-        @state = transition.to
-        @next_transition_name = @router_next_transition || transition.success_transition
-        @router_next_transition = nil
-        append_accepted_output(output)
-        emit_step_completed(transition, output)
-        { transition: transition.name, from: transition.from, to: transition.to, output: output }
-      end
-
-      def append_accepted_output(output)
-        return unless @session_messages
-        return if output.nil?
+      def preflight_branch_count(transition)
+        return Parallel.validate_branch_count!(transition.fanout_config.fetch(:branches).length) if transition.fanout?
 
-        @session_messages << { role: :assistant, content: output }
+        Parallel.resolve_branch_count(transition, @context) if transition.parallel?
       end
 
       def resolve_router_output(transition, output)
@@ -120,9 +116,11 @@ module Smith
       end
 
       def resolve_agent_class(transition)
-        return nil unless transition.agent_name
+        parallel_binding = Thread.current[:smith_parallel_agent_binding]
+        parallel_agent_class = parallel_binding&.resolve(workflow: self, transition:)
+        return parallel_agent_class if parallel_agent_class
 
-        Agent::Registry.fetch!(
+        transition.agent_name && resolve_registered_agent!(
           transition.agent_name,
           workflow_class: self.class,
           transition_name: transition.name,

data/lib/smith/workflow/execution_binding_resolution.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module ExecutionBindingResolution
+      private
+
+      def resolve_registered_agent!(name, workflow_class:, transition_name:, role:)
+        authorization = @split_step_active_execution_authorization
+        return authorization.fetch_agent!(name, workflow_class:, transition_name:, role:) if authorization
+
+        Agent::Registry.fetch!(name, workflow_class:, transition_name:, role:)
+      end
+    end
+  end
+end

data/lib/smith/workflow/execution_result_snapshot.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+require_relative "../errors"
+require_relative "string_snapshot"
+
+module Smith
+  class Workflow
+    class ExecutionResultSnapshot
+      MAX_DEPTH = 128
+      MAX_NODES = 100_000
+      MAX_BYTES = 4 * 1024 * 1024
+
+      extend Dry::Initializer
+
+      param :value
+      option :freeze_copy, default: proc { true }
+      option :preserved_error, default: proc {}
+
+      def call
+        reset
+        root = copy_value(value, depth: 0, preserve_error: true)
+        drain
+        @containers.each(&:freeze) if freeze_copy
+        root
+      end
+
+      private
+
+      def reset
+        @bytes = 0
+        @nodes = 0
+        @copies = {}.compare_by_identity
+        @containers = []
+        @pending = []
+      end
+
+      def drain
+        until @pending.empty?
+          source, copy, depth, preserve_error = @pending.pop
+          source.is_a?(Hash) ? copy_hash(source, copy, depth, preserve_error) : copy_array(source, copy, depth)
+        end
+      end
+
+      def copy_value(item, depth:, preserve_error: false)
+        visit!(depth)
+        return @copies.fetch(item) if @copies.key?(item)
+
+        case item
+        when Hash then prepare_container(item, {}, depth, preserve_error)
+        when Array then prepare_container(item, [], depth, false)
+        when String then copy_string(item)
+        when Float then copy_float(item)
+        when Symbol, Integer, true, false, nil then item
+        else
+          raise WorkflowError,
+                "prepared-step execution result contains unsupported mutable value #{item.class}"
+        end
+      end
+
+      def prepare_container(source, copy, depth, preserve_error)
+        @copies[source] = copy
+        @containers << copy
+        @pending << [source, copy, depth, preserve_error]
+        copy
+      end
+
+      def copy_hash(source, copy, depth, preserve_error)
+        source.each do |key, item|
+          copied_key = copy_hash_key(key, depth + 1)
+          copied_item = preserved_error?(copied_key, item, preserve_error) ? item : copy_value(item, depth: depth + 1)
+          copy[copied_key] = copied_item
+        end
+      end
+
+      def copy_hash_key(key, depth)
+        unless key.is_a?(String) || key.is_a?(Symbol)
+          raise WorkflowError,
+                "prepared-step execution result contains unsupported Hash key #{key.class}"
+        end
+
+        copy_value(key, depth: depth)
+      end
+
+      def copy_array(source, copy, depth)
+        source.each { |item| copy << copy_value(item, depth: depth + 1) }
+      end
+
+      def preserved_error?(key, item, permitted)
+        permitted && key == :error && item.equal?(preserved_error)
+      end
+
+      def copy_string(string)
+        @bytes += StringSnapshot.bytesize(string)
+        raise WorkflowError, "prepared-step execution result exceeds maximum bytes #{MAX_BYTES}" if
+          @bytes > MAX_BYTES
+
+        StringSnapshot.copy(string, freeze: freeze_copy)
+      end
+
+      def copy_float(float)
+        return float if float.finite?
+
+        raise WorkflowError, "prepared-step execution result contains non-finite Float"
+      end
+
+      def visit!(depth)
+        raise WorkflowError, "prepared-step execution result exceeds maximum depth #{MAX_DEPTH}" if depth > MAX_DEPTH
+
+        @nodes += 1
+        return if @nodes <= MAX_NODES
+
+        raise WorkflowError, "prepared-step execution result exceeds maximum size #{MAX_NODES}"
+      end
+    end
+  end
+end

data/lib/smith/workflow/fanout_execution.rb

@@ -109,7 +109,7 @@ module Smith
       end
 
       def resolve_fanout_agent_class(transition, agent_name)
-        Agent::Registry.fetch!(
+        resolve_registered_agent!(
           agent_name,
           workflow_class: self.class,
           transition_name: transition&.name,

data/lib/smith/workflow/graph/diagnostic.rb

@@ -1,21 +1,47 @@
 # frozen_string_literal: true
 
+require_relative "diagnostic_path"
+
 module Smith
   class Workflow
     class Graph
       class Diagnostic
-        attr_reader :severity, :code, :message, :state, :transition, :target, :suggestion
+        attr_reader :severity, :code, :state, :transition, :target, :suggestion
 
         def initialize(**attributes)
           @severity = attributes.fetch(:severity)
           @code = attributes.fetch(:code)
           @message = attributes.fetch(:message)
+          @path = attributes[:path]
           @state = attributes[:state]
           @transition = attributes[:transition]
           @target = attributes[:target]
           @suggestion = attributes[:suggestion]
         end
 
+        def message
+          return @message unless @path
+          return @rendered_message if defined?(@rendered_message)
+
+          @rendered_message = String.new.tap do |rendered|
+            @path.each_label { |label| rendered << "Nested workflow #{label}: " }
+            rendered << @message
+          end.freeze
+        end
+
+        def nested(label:, code:, transition:, target:)
+          self.class.new(
+            severity: severity,
+            code: code,
+            message: @message,
+            path: DiagnosticPath.new(label:, tail: @path),
+            state: state,
+            transition: transition,
+            target: target,
+            suggestion: suggestion
+          )
+        end
+
         def to_h
           {
             severity: severity,

data/lib/smith/workflow/graph/diagnostic_path.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+module Smith
+  class Workflow
+    class Graph
+      class DiagnosticPath
+        extend Dry::Initializer
+
+        option :label
+        option :tail, default: proc {}
+
+        def each_label
+          current = self
+          while current
+            yield current.label
+            current = current.tail
+          end
+        end
+      end
+    end
+  end
+end