smith-agents 0.4.2 → 0.4.3

data/lib/smith/workflow/deterministic_step.rb

@@ -4,14 +4,17 @@ module Smith
   class Workflow
     class DeterministicStep
       attr_reader :context, :tool_results, :session_messages, :current_state, :transition_name,
-                  :context_writes, :routed_to, :outcome
+                  :context_writes, :routed_to, :outcome, :allowed_routes
 
-      def initialize(context:, session_messages:, tool_results:, state:, transition_name:)
+      def initialize(context:, session_messages:, tool_results:, state:, **options)
+        validate_options!(options)
+        transition = options[:transition]
         @context = context
         @session_messages = session_messages
         @tool_results = tool_results
         @current_state = state
-        @transition_name = transition_name
+        @transition_name = transition ? transition.name : options.fetch(:transition_name)
+        @allowed_routes = snapshot_allowed_routes(transition ? transition.deterministic_routes : options[:allowed_routes])
         @context_writes = {}
         @routed_to = nil
         @outcome = nil
@@ -39,7 +42,7 @@ module Smith
       def route_to(transition_name)
         raise WorkflowError, "route_to already called with :#{@routed_to}" if @routed_to
 
-        @routed_to = transition_name
+        @routed_to = route_target_for(transition_name)
       end
 
       def write_outcome(kind:, payload:)
@@ -52,6 +55,31 @@ module Smith
       def fail!(message, retryable: nil, kind: nil, details: nil)
         raise DeterministicStepFailure.new(message, retryable: retryable, kind: kind, details: details)
       end
+
+      private
+
+      def validate_options!(options)
+        unknown = options.keys - %i[transition transition_name allowed_routes]
+        raise ArgumentError, "unknown keywords: #{unknown.join(", ")}" if unknown.any?
+        return if options[:transition] || options.key?(:transition_name)
+
+        raise ArgumentError, "missing keyword: :transition"
+      end
+
+      def snapshot_allowed_routes(routes)
+        return nil if routes.nil?
+
+        routes.map { |route| route.is_a?(String) ? route.dup.freeze : route }.freeze
+      end
+
+      def route_target_for(transition_name)
+        return transition_name if allowed_routes.nil?
+
+        allowed_route = allowed_routes.find { |route| route == transition_name }
+        return allowed_route if allowed_route
+
+        raise WorkflowError, "route_to #{transition_name.inspect} is not declared in deterministic routes"
+      end
     end
   end
 end

data/lib/smith/workflow/durability.rb

@@ -32,11 +32,9 @@ module Smith
         # `store/fetch/delete`, and this peek piggybacks on `fetch`.
         # Custom adapters work without changes.
         #
-        # Hadithi uses this to skip the credits guard at execution time
-        # when persisted state already exists for a workflow key (a
-        # prior attempt's billable work is durable in Redis, OR an
-        # in-flight workflow is being resumed — either way, no NEW
-        # credit authorization is needed).
+        # Hosts can use this to distinguish a resumed workflow from a
+        # brand-new workflow when coordinating external accounting or
+        # admission-control checks.
         def persisted_state_exists?(key: nil, context: {}, adapter: Smith.persistence_adapter)
           resolved_key = resolved_persistence_key(key:, context:)
           !fetch_persisted_payload(resolved_key, adapter:).nil?
@@ -51,11 +49,9 @@ module Smith
         # the top of `run_persisted!` BEFORE the first `advance!`. A
         # worker that dies between that initial `persist!` and the
         # first model call leaves a Redis key with no billable work.
-        # If the credits guard's bypass keys on `persisted_state_exists?`
-        # alone, a zero-balance user's retry on that abandoned init
-        # state silently runs the first model call (the guard is
-        # skipped because state exists, but the state has nothing to
-        # bill — it's just the workflow's starting state).
+        # If external accounting or admission-control checks key on
+        # `persisted_state_exists?` alone, a retry on that abandoned
+        # init state can be mistaken for a billable/resumable workflow.
         #
         # `restorable_billing_state?` returns true only when there's
         # actual `usage_entries` to bill on idempotent replay. Terminal
@@ -167,11 +163,22 @@ module Smith
           return false unless state_name && class_name
 
           klass = Object.const_get(class_name)
-          klass.transitions_from(state_name.to_sym).empty? && next_transition.nil?
+          state = state_name_for_payload(klass, state_name)
+          klass.transitions_from(state).empty? && next_transition.nil?
         rescue JSON::ParserError, NameError, NoMethodError
           false
         end
 
+        def state_name_for_payload(klass, state_name)
+          states = klass.instance_variable_get(:@states) || []
+          return state_name if states.include?(state_name)
+
+          symbolized = state_name.to_sym if state_name.respond_to?(:to_sym)
+          return symbolized if states.include?(symbolized)
+
+          state_name
+        end
+
         def persistence_adapter!(adapter)
           return adapter if adapter
 
@@ -241,12 +248,19 @@ module Smith
         persist!(resolved_key, adapter:)
 
         until terminal?
+          ensure_transition_budget!
+
           if strict_idempotency?
             mark_step_in_progress!
             persist!(resolved_key, adapter:)
           end
 
-          step = advance!
+          begin
+            step = advance!
+          rescue StandardError
+            clear_pre_step_marker!(resolved_key, adapter:)
+            raise
+          end
           steps << step if step
 
           clear_step_in_progress!
@@ -261,6 +275,7 @@ module Smith
         return if terminal?
 
         resolved_key = resolve_persistence_key!(key)
+        ensure_transition_budget!
         mark_step_in_progress! if strict_idempotency?
         persist!(resolved_key, adapter:)
         step = advance!
@@ -268,6 +283,9 @@ module Smith
         persist!(resolved_key, adapter:) if step
         invoke_on_step_callback(step, on_step) if step
         step
+      rescue StandardError
+        clear_pre_step_marker!(resolved_key, adapter:) if defined?(resolved_key) && resolved_key
+        raise
       end
 
       def persist!(key = nil, adapter: Smith.persistence_adapter)
@@ -306,6 +324,14 @@ module Smith
         self.class.idempotency_mode == :strict
       end
 
+      def clear_pre_step_marker!(key, adapter:)
+        return unless strict_idempotency?
+        return if step_work_started?
+
+        clear_step_in_progress!
+        persist!(key, adapter:)
+      end
+
       # Forwards the persist payload to the adapter, splatting `ttl:`
       # only when a TTL is resolved. The empty-Hash splat is a no-op so
       # external duck-typed adapters that don't accept a `ttl:` kwarg

data/lib/smith/workflow/evaluator_optimizer.rb

@@ -1,16 +1,13 @@
 # frozen_string_literal: true
 
+require "json"
+
+require_relative "agent_result"
+require_relative "optimization_state"
+
 module Smith
   class Workflow
     module EvaluatorOptimizer
-      OptimizationState = Struct.new(
-        :config, :prepared_input, :candidate, :feedback, :last_score, :generator_class, :evaluator_class
-      ) do
-        def initialize(config, prepared_input)
-          super(config, prepared_input, nil, nil, nil, nil, nil)
-        end
-      end
-
       private
 
       def execute_optimization_step(transition, prepared_input: nil)

data/lib/smith/workflow/event_integration.rb

@@ -13,9 +13,9 @@ module Smith
 
         Smith::Events.emit(
           Events::StepCompleted.new(
-            transition: transition.name,
-            from: transition.from,
-            to: transition.to
+            transition: transition.name.to_sym,
+            from: transition.from&.to_sym,
+            to: transition.to.to_sym
           )
         )
       end

data/lib/smith/workflow/execution.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "agent_result"
+
 module Smith
   class Workflow
     module Execution

data/lib/smith/workflow/fanout_execution.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "branch_env"
+
 module Smith
   class Workflow
     module FanoutExecution

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

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    class Graph
+      module ContractHelpers
+        private
+
+        def label_for(value)
+          label = if value.respond_to?(:name) && value.name && !value.name.empty?
+                    value.name
+                  elsif value.respond_to?(:inspect)
+                    value.inspect
+                  else
+                    value.to_s
+                  end
+
+          immutable_value(label)
+        end
+
+        def idempotency_mode
+          return :unknown unless workflow_class.respond_to?(:idempotency_mode)
+
+          workflow_class.idempotency_mode
+        end
+
+        def in_flight_resume
+          return :blocked_by_step_in_progress if idempotency_mode == :strict
+          return :unknown unless %i[strict lax].include?(idempotency_mode)
+
+          :reruns_transition
+        end
+
+        def immutable_value(value)
+          return value if immediate_value?(value)
+
+          duplicate = value.dup
+          return value if duplicate.equal?(value)
+
+          duplicate.freeze
+        rescue TypeError
+          value
+        end
+
+        def immediate_value?(value)
+          value.nil? || value.is_a?(Symbol) || value.is_a?(Numeric) ||
+            value == true || value == false
+        end
+
+        def deep_freeze(value)
+          case value
+          when Hash
+            value.each_value { |nested| deep_freeze(nested) }
+            value.freeze
+          when Array
+            value.each { |nested| deep_freeze(nested) }
+            value.freeze
+          end
+
+          value
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    class Graph
+      class FanoutContract
+        attr_reader :transition, :workflow_class
+
+        def self.from_transition(transition, workflow_class: nil)
+          branches = transition.fanout_config&.fetch(:branches, nil)
+          return unless branches
+
+          new(transition, workflow_class: workflow_class).to_h
+        end
+
+        def initialize(transition, workflow_class: nil)
+          @transition = transition
+          @workflow_class = workflow_class
+        end
+
+        def to_h
+          deep_freeze(
+            branch_count: branches.length,
+            join_state: immutable_value(transition.to),
+            output_shape: :named_branch_results,
+            branch_order: :declaration_order,
+            join: join_contract,
+            output_contract: output_contract,
+            resume_contract: resume_contract,
+            branches: branch_summaries,
+            branch_contracts: branch_contracts
+          )
+        end
+
+        private
+
+        def branches
+          transition.fanout_config.fetch(:branches)
+        end
+
+        def join_contract
+          {
+            state: immutable_value(transition.to),
+            transition: immutable_value(transition.name)
+          }
+        end
+
+        def output_contract
+          {
+            collection: :array,
+            item_shape: :named_branch_result,
+            ordering: :branch_declaration_order,
+            branch_key_field: :branch,
+            agent_field: :agent,
+            output_field: :output,
+            failure: :discard_all_branch_results_on_failure
+          }
+        end
+
+        def resume_contract
+          {
+            granularity: :transition,
+            branch_checkpointing: false,
+            idempotency_mode: idempotency_mode,
+            in_flight_resume: in_flight_resume
+          }
+        end
+
+        def branch_summaries
+          branches.map do |branch, agent|
+            { branch: immutable_value(branch), agent: immutable_value(agent) }
+          end
+        end
+
+        def branch_contracts
+          branches.map do |branch, agent|
+            branch_value = immutable_value(branch)
+            agent_value = immutable_value(agent)
+
+            {
+              branch: branch_value,
+              agent: agent_value,
+              result_branch_value: branch_value,
+              result_shape: {
+                branch: branch_value,
+                agent: agent_value,
+                output: :agent_output
+              }
+            }
+          end
+        end
+
+        def immutable_value(value)
+          return value if immediate_value?(value)
+
+          duplicate = value.dup
+          return value if duplicate.equal?(value)
+
+          duplicate.freeze
+        rescue TypeError
+          # Some host-owned topology values intentionally refuse duplication.
+          # Leave them untouched; the graph contract containers are still
+          # frozen, and inspection must never mutate workflow-owned values.
+          value
+        end
+
+        def immediate_value?(value)
+          value.nil? || value.is_a?(Symbol) || value.is_a?(Numeric) ||
+            value == true || value == false
+        end
+
+        def idempotency_mode
+          return :unknown unless workflow_class&.respond_to?(:idempotency_mode)
+
+          workflow_class.idempotency_mode
+        end
+
+        def in_flight_resume
+          return :blocked_by_step_in_progress if idempotency_mode == :strict
+          return :unknown unless %i[strict lax].include?(idempotency_mode)
+
+          :reruns_transition
+        end
+
+        def deep_freeze(value)
+          case value
+          when Hash
+            value.each_value { |nested| deep_freeze(nested) }
+            value.freeze
+          when Array
+            value.each { |nested| deep_freeze(nested) }
+            value.freeze
+          end
+
+          value
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+module Smith
+  class Workflow
+    class Graph
+      class NestedReadinessDiagnostics
+        extend Dry::Initializer
+
+        param :graph
+        option :visited, default: proc {}
+
+        def to_a
+          cycle_diagnostics + report_entries.flat_map { |entry| diagnostics_for(entry) }
+        end
+
+        def child_reports
+          report_entries.map { |entry| entry.fetch(:report) }
+        end
+
+        private
+
+        def diagnostics_for(entry)
+          entry.fetch(:report).diagnostics.map do |diagnostic|
+            nested_diagnostic(entry.fetch(:transition), entry.fetch(:workflow_class), diagnostic)
+          end
+        end
+
+        def cycle_diagnostics
+          nested_workflow_transitions.filter_map do |transition|
+            workflow_class = transition.workflow_class
+            cycle_diagnostic(transition, workflow_class) if visited_workflows.include?(workflow_class)
+          end
+        end
+
+        def report_entries
+          @report_entries ||= nested_workflow_transitions.filter_map do |transition|
+            workflow_class = transition.workflow_class
+            next if visited_workflows.include?(workflow_class)
+
+            {
+              transition: transition,
+              workflow_class: workflow_class,
+              report: workflow_class.graph.runtime_readiness(visited: visited_workflows)
+            }.freeze
+          end.freeze
+        end
+
+        def nested_workflow_transitions
+          @nested_workflow_transitions ||= graph.transitions.values.select(&:nested?)
+        end
+
+        def cycle_diagnostic(transition, workflow_class)
+          label = workflow_label(workflow_class)
+
+          Diagnostic.new(
+            severity: :error,
+            code: :nested_workflow_cycle,
+            transition: transition.name,
+            target: label,
+            message: "Transition #{ref(transition.name)} nests #{label}, " \
+                     "which is already in the readiness inspection stack.",
+            suggestion: "Break the nested workflow cycle before runtime execution."
+          )
+        end
+
+        def nested_diagnostic(transition, workflow_class, diagnostic)
+          label = workflow_label(workflow_class)
+
+          Diagnostic.new(
+            severity: diagnostic.severity,
+            code: :"nested_#{diagnostic.code}",
+            transition: transition.name,
+            target: label,
+            message: "Nested workflow #{label}: #{diagnostic.message}",
+            suggestion: diagnostic.suggestion
+          )
+        end
+
+        def visited_workflows
+          @visited_workflows ||= Set.new(Array(visited)).add(graph.workflow_class)
+        end
+
+        def ref(value)
+          Reference.format(value)
+        end
+
+        def workflow_label(workflow_class)
+          name = workflow_class.name
+          return name if name && !name.empty?
+
+          workflow_class.inspect
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+require_relative "contract_helpers"
+
+module Smith
+  class Workflow
+    class Graph
+      class OptimizationContract
+        extend Dry::Initializer
+        include ContractHelpers
+
+        param :transition
+        option :workflow_class, default: proc {}
+
+        def self.from_transition(transition, workflow_class: nil)
+          new(transition, workflow_class: workflow_class).to_h if transition.optimization_config
+        end
+
+        def to_h
+          deep_freeze(
+            transition_contract.merge(
+              exit_modes: exit_modes,
+              output_contract: output_contract,
+              resume_contract: resume_contract
+            ).compact
+          )
+        end
+
+        private
+
+        def config
+          transition.optimization_config
+        end
+
+        def transition_contract
+          {
+            generator: immutable_value(config.fetch(:generator)),
+            evaluator: immutable_value(config.fetch(:evaluator)),
+            max_rounds: config.fetch(:max_rounds)
+          }.merge(evaluation_contract)
+        end
+
+        def evaluation_contract
+          {
+            evaluator_schema: label_for(config.fetch(:evaluator_schema)),
+            evaluator_context: config[:evaluator_context],
+            improvement_threshold: config[:improvement_threshold],
+            before_eval: callable_label(config[:before_eval])
+          }
+        end
+
+        def exit_modes
+          {
+            exhaustion: exit_mode_label(config.fetch(:on_exhaustion)),
+            converged: exit_mode_label(config.fetch(:on_converged)),
+            threshold: exit_mode_label(config.fetch(:on_threshold))
+          }
+        end
+
+        def output_contract
+          {
+            success: :accepted_or_configured_exit_candidate,
+            failure: :workflow_error_on_malformed_or_unaccepted_evaluation,
+            evaluator_output: {
+              required: { accept: :boolean },
+              rejection_requires: %i[feedback],
+              threshold_requires: %i[score],
+              optional: %i[score converged]
+            }
+          }
+        end
+
+        def resume_contract
+          {
+            granularity: :transition,
+            round_checkpointing: false,
+            idempotency_mode: idempotency_mode,
+            in_flight_resume: in_flight_resume
+          }
+        end
+
+        def exit_mode_label(value)
+          return value if value.is_a?(Symbol)
+
+          callable_label(value)
+        end
+
+        def callable_label(value)
+          value.respond_to?(:call) ? :callable : nil
+        end
+      end
+    end
+  end
+end