smith-agents 0.4.2 → 0.4.3

data/lib/smith/workflow/graph.rb

@@ -16,8 +16,14 @@ module Smith
         Validator.new(self).report
       end
 
+      def runtime_readiness(visited: nil)
+        RuntimeReadiness.new(self, visited: visited).report
+      end
+
       def transition_snapshots
-        transitions.values.map { |transition| TransitionSnapshot.from_transition(transition) }
+        transitions.values.map do |transition|
+          TransitionSnapshot.from_transition(transition, workflow_class: workflow_class)
+        end
       end
     end
   end
@@ -29,8 +35,17 @@ require_relative "graph/state_diagnostics"
 require_relative "graph/reachability"
 require_relative "graph/reachability_diagnostics"
 require_relative "graph/metrics"
+require_relative "graph/nested_readiness_diagnostics"
 require_relative "graph/report"
+require_relative "graph/runtime_binding_diagnostic_builder"
+require_relative "graph/runtime_binding_diagnostics"
+require_relative "graph/runtime_readiness_report"
+require_relative "graph/runtime_readiness_metrics"
 require_relative "graph/targets"
+require_relative "graph/fanout_contract"
+require_relative "graph/optimization_contract"
+require_relative "graph/orchestration_contract"
 require_relative "graph/transition_snapshot"
 require_relative "graph/transition_diagnostics"
 require_relative "graph/validator"
+require_relative "graph/runtime_readiness"

data/lib/smith/workflow/graph_dsl.rb

@@ -14,5 +14,9 @@ module Smith
     def self.validate_graph
       graph.validate
     end
+
+    def self.runtime_readiness
+      graph.runtime_readiness
+    end
   end
 end

data/lib/smith/workflow/guardrail_integration.rb

@@ -20,16 +20,33 @@ module Smith
         run_agent_output_guardrails(output, agent_class)
       end
 
-      def handle_step_failure(transition, _error)
+      def handle_step_failure(transition, error)
         failure_name = transition.failure_transition
-        return unless failure_name
+        raise error unless failure_name
 
         fail_transition = self.class.find_transition(failure_name)
-        return unless fail_transition
+        raise error unless fail_transition
+        validate_transition_origin!(fail_transition)
+
+        if actionable_failure_transition?(fail_transition)
+          @next_transition_name = failure_name
+          return
+        end
 
         @state = fail_transition.to
       end
 
+      def actionable_failure_transition?(transition)
+        transition.agent_name ||
+          transition.deterministic? ||
+          transition.routed? ||
+          transition.fanout? ||
+          transition.nested? ||
+          transition.optimized? ||
+          transition.orchestrated? ||
+          transition.success_transition
+      end
+
       def run_workflow_input_guardrails
         wf_guardrails = self.class.guardrails
         Guardrails::Runner.run_inputs(wf_guardrails, @context) if wf_guardrails

data/lib/smith/workflow/nested_execution.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "usage_entry"
+
 module Smith
   class Workflow
     module NestedExecution
@@ -29,10 +31,9 @@ module Smith
       # Roll up child totals AND usage_entries BEFORE the failed-step
       # check raises. Previously the rollup only fired on child success
       # — billable agent work inside a failed child was silently
-      # dropped from the parent's totals/entries. The drift guard at
-      # the hadithi boundary wouldn't catch it (parent rollups + entries
-      # consistently undercount the same way; sum invariant still holds
-      # incorrectly). Roll up first, then re-raise, so the parent's
+      # dropped from the parent's totals/entries. Simple aggregate drift
+      # checks can miss this when parent rollups and entries undercount
+      # the same way. Roll up first, then re-raise, so the parent's
       # terminal state reflects the child's billable work even when the
       # child failed.
       def handle_child_result(child_result)

data/lib/smith/workflow/optimization_state.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    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
+  end
+end

data/lib/smith/workflow/orchestration_state.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    OrchestrationState = Struct.new(
+      :config, :prepared_input, :orchestrator_class, :worker_class, :worker_results
+    ) do
+      def initialize(config, prepared_input)
+        super(config, prepared_input, nil, nil, nil)
+      end
+    end
+  end
+end

data/lib/smith/workflow/orchestrator_worker.rb

@@ -1,25 +1,13 @@
 # frozen_string_literal: true
 
 require "json"
-require "securerandom"
+
+require_relative "orchestration_state"
+require_relative "worker_execution"
 
 module Smith
   class Workflow
     module OrchestratorWorker
-      OrchestrationState = Struct.new(
-        :config, :prepared_input, :orchestrator_class, :worker_class, :worker_results
-      ) do
-        def initialize(config, prepared_input)
-          super(config, prepared_input, nil, nil, nil)
-        end
-      end
-
-      WorkerExecution = Struct.new(:execution_id, :task, :output) do
-        def self.run(worker_class, task, schema, budget_runner)
-          new(SecureRandom.uuid, task, budget_runner.call(worker_class, task, schema))
-        end
-      end
-
       private
 
       def dispatch_step(transition, prepared_input: nil)

data/lib/smith/workflow/parallel/cancellation_signal.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    class Parallel
+      CancellationSignal = Struct.new(:cancelled, :mutex) do
+        def initialize
+          super(false, Mutex.new)
+        end
+
+        def cancel!
+          mutex.synchronize { self.cancelled = true }
+        end
+
+        def cancelled?
+          mutex.synchronize { cancelled }
+        end
+      end
+    end
+  end
+end

data/lib/smith/workflow/parallel.rb

@@ -2,26 +2,17 @@
 
 require "concurrent"
 
+require_relative "parallel/cancellation_signal"
+
 module Smith
   class Workflow
     class Parallel
-      CancellationSignal = Struct.new(:cancelled, :mutex) do
-        def initialize
-          super(false, Mutex.new)
-        end
-
-        def cancel!
-          mutex.synchronize { self.cancelled = true }
-        end
-
-        def cancelled?
-          mutex.synchronize { cancelled }
-        end
-      end
-
       def self.resolve_branch_count(transition, context)
         count = transition.agent_opts[:count]
-        count.respond_to?(:call) ? count.call(context) : (count || 1)
+        resolved = count.respond_to?(:call) ? count.call(context) : (count || 1)
+        return resolved if resolved.is_a?(Integer) && resolved.positive?
+
+        raise WorkflowError, "parallel branch count must be a positive integer"
       end
 
       def self.execute(branches:)

data/lib/smith/workflow/parallel_execution.rb

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

data/lib/smith/workflow/persistence.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "usage_entry"
+
 module Smith
   class Workflow
     module Persistence
@@ -20,7 +22,7 @@ module Smith
           total_tokens: @total_tokens || 0,
           tool_results: @tool_results || [],
           outcome: snapshot_outcome,
-          # New durable fields for hadithi billing. All wrapped in
+          # Durable usage fields. All wrapped in
           # snapshot_value so non-JSON-safe runtime values (e.g.
           # custom Hash details on DeterministicStepFailure) get the
           # same deep-copy treatment as context/session_messages/etc.
@@ -163,9 +165,9 @@ module Smith
 
         h = raw.transform_keys { |k| k.is_a?(String) ? k.to_sym : k }
         {
-          transition: h[:transition]&.to_sym,
-          from: h[:from]&.to_sym,
-          to: h[:to]&.to_sym,
+          transition: normalize_transition_name(h[:transition]),
+          from: normalize_state_name(h[:from]),
+          to: normalize_state_name(h[:to]),
           error_class: h[:error_class],
           error_family: h[:error_family],
           error_message: h[:error_message],
@@ -255,7 +257,7 @@ module Smith
       end
 
       def normalize_symbol_fields!(normalized)
-        normalized[:state] = normalized[:state]&.to_sym
+        normalized[:state] = normalize_state_name(normalized[:state])
         if normalized[:outcome].is_a?(Hash) && normalized[:outcome].key?(:kind)
           normalized[:outcome][:kind] = normalized[:outcome][:kind]&.to_sym
         elsif normalized[:outcome].is_a?(Hash) && normalized[:outcome].key?("kind")
@@ -263,7 +265,36 @@ module Smith
         end
         return unless normalized.key?(:next_transition_name)
 
-        normalized[:next_transition_name] = normalized[:next_transition_name]&.to_sym
+        normalized[:next_transition_name] = normalize_transition_name(normalized[:next_transition_name])
+      end
+
+      def normalize_transition_name(value)
+        return if value.nil?
+        transition = self.class.find_transition(value)
+        return transition.name if transition
+        return value unless value.is_a?(String)
+
+        symbolized = value.to_sym
+        transition = self.class.find_transition(symbolized)
+        return transition.name if transition
+
+        symbolized
+      end
+
+      def normalize_state_name(value)
+        return if value.nil?
+        return value if declared_state?(value)
+        return value unless value.is_a?(String)
+
+        symbolized = value.to_sym
+        return symbolized if declared_state?(symbolized)
+
+        symbolized
+      end
+
+      def declared_state?(value)
+        states = self.class.instance_variable_get(:@states) || []
+        states.include?(value)
       end
 
       def normalize_nested_hashes!(normalized)

data/lib/smith/workflow/router.rb

@@ -4,16 +4,23 @@ module Smith
   class Workflow
     class Router
       def self.resolve(classifier_output, config, workflow_class:)
-        validate!(classifier_output, config)
-        transition_name = select_transition(classifier_output, config)
+        output = normalize_output(classifier_output)
+        validate!(output, config)
+        transition_name = select_transition(output, config)
         validate_transition_exists!(transition_name, workflow_class)
         transition_name
       end
 
+      def self.normalize_output(output)
+        return output unless output.is_a?(Hash)
+
+        output.transform_keys { |key| key.is_a?(String) ? key.to_sym : key }
+      end
+
       def self.validate!(output, config)
         validate_structure!(output)
         validate_confidence!(output[:confidence])
-        validate_route_key!(output[:route].to_sym, output[:confidence], config)
+        validate_route_key!(normalize_route_key(output[:route]), output[:confidence], config)
       end
 
       def self.validate_structure!(output)
@@ -37,12 +44,16 @@ module Smith
 
       def self.select_transition(output, config)
         if output[:confidence] >= config[:confidence_threshold]
-          config[:routes][output[:route].to_sym]
+          config[:routes][normalize_route_key(output[:route])]
         else
           config[:fallback]
         end
       end
 
+      def self.normalize_route_key(route)
+        route.to_s.strip.to_sym
+      end
+
       def self.validate_transition_exists!(transition_name, workflow_class)
         return if workflow_class.find_transition(transition_name)
 

data/lib/smith/workflow/run_result.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    # rubocop:disable Style/RedundantStructKeywordInit
+    RunResult = Struct.new(:state, :output, :steps, :total_cost, :total_tokens, :context, :session_messages,
+                           :tool_results, :outcome, :usage_entries, keyword_init: true) do
+      def done?
+        state_named?(:done)
+      end
+
+      def failed?
+        state_named?(:failed)
+      end
+
+      def state_named?(name)
+        state == name || state.to_s == name.to_s
+      end
+
+      def terminal_output
+        output
+      end
+
+      def outcome_kind
+        outcome&.dig(:kind)
+      end
+
+      def outcome_payload
+        outcome&.dig(:payload)
+      end
+
+      def last_error
+        steps.reverse.map { |step| step[:error] }.compact.first
+      end
+
+      def failed_transition
+        failure_detail&.fetch(:transition)
+      end
+
+      def failure_detail
+        failed_step = steps.reverse.find { |step| step[:error] }
+        return nil unless failed_step
+
+        {
+          transition: failed_step[:transition],
+          from: failed_step[:from],
+          to: failed_step[:to],
+          error: failed_step[:error]
+        }
+      end
+    end
+    # rubocop:enable Style/RedundantStructKeywordInit
+  end
+end

data/lib/smith/workflow/transition.rb

@@ -5,7 +5,8 @@ module Smith
     class Transition
       attr_reader :name, :from, :to, :agent_name, :agent_opts, :success_transition, :failure_transition,
                   :router_config, :workflow_class, :optimization_config, :orchestrator_config,
-                  :fanout_config, :retry_config, :deterministic_block, :deterministic_kind
+                  :fanout_config, :retry_config, :deterministic_block, :deterministic_kind,
+                  :deterministic_routes
 
       def initialize(name, from:, to:, &)
         @name = name
@@ -32,8 +33,12 @@ module Smith
       def route(agent_name, routes:, confidence_threshold:, fallback:)
         validate_route_conflicts!
 
-        @agent_name = agent_name
-        @router_config = { routes: routes, confidence_threshold: confidence_threshold, fallback: fallback }
+        @agent_name = normalize_agent_name!(agent_name, "router")
+        @router_config = {
+          routes: normalize_router_routes!(routes),
+          confidence_threshold: normalize_confidence_threshold!(confidence_threshold),
+          fallback: normalize_transition_reference!(fallback, "router fallback")
+        }
       end
 
       def workflow(klass)
@@ -104,12 +109,13 @@ module Smith
       end
 
       %i[compute run].each do |method_name|
-        define_method(method_name) do |&block|
+        define_method(method_name) do |routes: nil, &block|
           validate_deterministic_conflicts!
           raise WorkflowError, "#{method_name} requires a block" unless block
 
           @deterministic_block = block
           @deterministic_kind = method_name
+          @deterministic_routes = normalize_deterministic_routes!(routes)
         end
       end
 
@@ -241,6 +247,57 @@ module Smith
         normalized.freeze
       end
 
+      def normalize_agent_name!(agent_name, label)
+        value = agent_name.to_s.strip
+        raise WorkflowError, "#{label} agent must not be blank" if value.empty?
+
+        value.to_sym
+      end
+
+      def normalize_router_routes!(routes)
+        raise WorkflowError, "router routes must be a Hash" unless routes.is_a?(Hash)
+        raise WorkflowError, "router routes must not be empty" if routes.empty?
+
+        routes.each_with_object({}) do |(route_key, transition_name), map|
+          key = normalize_router_route_key!(route_key)
+          raise WorkflowError, "router route :#{key} is duplicated" if map.key?(key)
+
+          map[key] = normalize_transition_reference!(transition_name, "router route :#{key}")
+        end.freeze
+      end
+
+      def normalize_router_route_key!(route_key)
+        value = route_key.to_s.strip
+        raise WorkflowError, "router route keys must not be blank" if value.empty?
+
+        value.to_sym
+      end
+
+      def normalize_confidence_threshold!(threshold)
+        numeric = Float(threshold)
+        return numeric if numeric >= 0.0 && numeric <= 1.0
+
+        raise WorkflowError, "router confidence_threshold must be a number in 0.0..1.0"
+      rescue TypeError, ArgumentError
+        raise WorkflowError, "router confidence_threshold must be a number in 0.0..1.0"
+      end
+
+      def normalize_transition_reference!(transition_name, label)
+        case transition_name
+        when Symbol
+          raise WorkflowError, "#{label} transition must not be blank" if transition_name.to_s.empty?
+
+          transition_name
+        when String
+          value = transition_name.strip
+          raise WorkflowError, "#{label} transition must not be blank" if value.empty?
+
+          value.freeze
+        else
+          raise WorkflowError, "#{label} transition must be String or Symbol"
+        end
+      end
+
       def normalize_fanout_branch_key!(branch_key)
         key = branch_key.to_s.strip
         raise WorkflowError, "fan_out branch keys must not be blank" if key.empty?
@@ -278,6 +335,35 @@ module Smith
         validate_non_negative_numeric!(:max_delay, max_delay) unless max_delay.nil?
       end
 
+      def normalize_deterministic_routes!(routes)
+        return nil if routes.nil?
+        raise WorkflowError, "deterministic routes must be an Array" unless routes.is_a?(Array)
+        raise WorkflowError, "deterministic routes must not be empty" if routes.empty?
+
+        routes.each_with_object([]) do |route, list|
+          name = normalize_deterministic_route!(route)
+          raise WorkflowError, "deterministic route #{name.inspect} is duplicated" if list.include?(name)
+
+          list << name
+        end.freeze
+      end
+
+      def normalize_deterministic_route!(route)
+        case route
+        when Symbol
+          raise WorkflowError, "deterministic route names must not be blank" if route.to_s.empty?
+
+          route
+        when String
+          value = route.strip
+          raise WorkflowError, "deterministic route names must not be blank" if value.empty?
+
+          value.freeze
+        else
+          raise WorkflowError, "deterministic route names must be String or Symbol"
+        end
+      end
+
       def validate_non_negative_numeric!(name, value)
         numeric = Float(value)
         return if numeric >= 0.0

data/lib/smith/workflow/usage_entry.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    # One row per agent provider call. `usage_id` is a UUID generated at
+    # recording time and stable across persist/restore so hosts can use it as an
+    # idempotency anchor.
+    # rubocop:disable Style/RedundantStructKeywordInit
+    UsageEntry = Struct.new(
+      :usage_id,
+      :agent_name,
+      :model,
+      :input_tokens,
+      :output_tokens,
+      :cost,
+      :attempt_kind,
+      :recorded_at,
+      keyword_init: true
+    ) do
+      def self.from_h(hash)
+        sym = hash.transform_keys(&:to_sym)
+        filtered = sym.slice(*members)
+        filtered[:agent_name] = filtered[:agent_name].to_sym if filtered[:agent_name].is_a?(String)
+        filtered[:attempt_kind] = filtered[:attempt_kind].to_sym if filtered[:attempt_kind].is_a?(String)
+        new(**filtered)
+      end
+    end
+    # rubocop:enable Style/RedundantStructKeywordInit
+  end
+end

data/lib/smith/workflow/worker_execution.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Smith
+  class Workflow
+    WorkerExecution = Struct.new(:execution_id, :task, :output) do
+      def self.run(worker_class, task, schema, budget_runner)
+        new(SecureRandom.uuid, task, budget_runner.call(worker_class, task, schema))
+      end
+    end
+  end
+end