smith-agents 0.4.1 → 0.4.3

data/lib/smith/doctor/checks/models_registry.rb

@@ -36,29 +36,40 @@ module Smith
           end
         end
 
-        # Walk Smith::Agent::Registry. For each agent, extract the model
-        # id from chat_kwargs (static `model "..."` form). Block-form
-        # `model do |ctx| ... end` agents are skipped because their
-        # model is resolved per-attempt and can't be enumerated at boot.
+        # Walk Smith::Agent::Registry. For each agent, extract every static
+        # model id Smith can know at boot: the primary `model "..."` value and
+        # any static fallback models. Block-form primary models are skipped
+        # because they resolve per-attempt, but their static fallbacks still
+        # need coverage checks.
         # Check whether find_or_infer returns a custom (non-default)
         # Profile — meaning either an explicit override or an inference
         # rule matched.
         def uncovered_models
           return [] unless defined?(Smith::Agent::Registry)
 
-          model_ids = []
-          Smith::Agent::Registry.each do |_key, agent|
-            next unless agent.is_a?(Class)
-            next unless agent.respond_to?(:chat_kwargs)
+          static_model_ids.uniq.reject { |model_id| covered_model?(model_id) }
+        end
 
-            id = agent.chat_kwargs[:model]
-            model_ids << id if id
+        def static_model_ids
+          Smith::Agent::Registry.each.with_object([]) do |(_key, agent), ids|
+            ids.concat(static_model_ids_for(agent)) if inspectable_agent?(agent)
           end
+        end
 
-          model_ids.uniq.reject do |model_id|
-            Smith::Models.find(model_id) ||
-              (defined?(Smith::Models::Inference) && Smith::Models::Inference.profile_for(model_id))
-          end
+        def inspectable_agent?(agent)
+          agent.is_a?(Class) && agent.respond_to?(:chat_kwargs)
+        end
+
+        def static_model_ids_for(agent)
+          [
+            agent.chat_kwargs[:model],
+            *(agent.respond_to?(:fallback_models) ? agent.fallback_models : nil)
+          ].compact
+        end
+
+        def covered_model?(model_id)
+          Smith::Models.find(model_id) ||
+            (defined?(Smith::Models::Inference) && Smith::Models::Inference.profile_for(model_id))
         end
       end
     end

data/lib/smith/doctor/checks/persistence_capabilities.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../../persistence_adapters"
+
 module Smith
   module Doctor
     module Checks
@@ -12,41 +14,16 @@ module Smith
       module PersistenceCapabilities
         module_function
 
-        OPTIONAL_CAPABILITIES = %i[store_versioned].freeze
+        OPTIONAL_CAPABILITIES = Smith::PersistenceAdapters::OPTIONAL_METHODS
 
         def run(report)
           adapter = resolve_adapter
-          if adapter.nil?
-            report.add(
-              name: "persistence.capabilities",
-              status: :warn,
-              message: "No persistence adapter configured",
-              detail: "Smith.config.persistence_adapter is nil and Smith.config.test_mode is false. " \
-                      "Hosts using durable workflows must set persistence_adapter."
-            )
-            return
-          end
+          return report_missing_adapter(report) if adapter.nil?
 
           missing = OPTIONAL_CAPABILITIES.reject { |cap| Smith::PersistenceAdapters.supports?(adapter, cap) }
+          return report_supported_capabilities(report, adapter) if missing.empty?
 
-          if missing.empty?
-            report.add(
-              name: "persistence.capabilities",
-              status: :pass,
-              message: "#{adapter.class.name} supports all optional persistence capabilities",
-              detail: "Supported: #{OPTIONAL_CAPABILITIES.join(', ')}"
-            )
-          else
-            report.add(
-              name: "persistence.capabilities",
-              status: :warn,
-              message: "#{adapter.class.name} missing optional capabilities: #{missing.join(', ')}",
-              detail: "Workflows using these capabilities fall back to non-versioned writes " \
-                      "with a one-time warning per adapter class. Switch to RedisStore, " \
-                      "ActiveRecordStore (with lock_version column), or the Memory adapter " \
-                      "for full coverage."
-            )
-          end
+          report_missing_capabilities(report, adapter, missing)
         end
 
         def resolve_adapter
@@ -54,6 +31,37 @@ module Smith
         rescue StandardError
           nil
         end
+
+        def report_missing_adapter(report)
+          report.add(
+            name: "persistence.capabilities",
+            status: :warn,
+            message: "No persistence adapter configured",
+            detail: "Smith.config.persistence_adapter is nil and Smith.config.test_mode is false. " \
+                    "Hosts using durable workflows must set persistence_adapter."
+          )
+        end
+
+        def report_supported_capabilities(report, adapter)
+          report.add(
+            name: "persistence.capabilities",
+            status: :pass,
+            message: "#{adapter.class.name} supports all optional persistence capabilities",
+            detail: "Supported: #{OPTIONAL_CAPABILITIES.join(", ")}"
+          )
+        end
+
+        def report_missing_capabilities(report, adapter, missing)
+          report.add(
+            name: "persistence.capabilities",
+            status: :warn,
+            message: "#{adapter.class.name} missing optional capabilities: #{missing.join(", ")}",
+            detail: "Smith will fall back where possible: non-versioned writes when store_versioned " \
+                    "is missing, and payload updated_at parsing when heartbeat methods are missing. " \
+                    "Use RedisStore or Memory for full versioning and heartbeat coverage; " \
+                    "ActiveRecordStore currently covers optimistic locking when lock_version is present."
+          )
+        end
       end
     end
   end

data/lib/smith/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Smith
-  VERSION = "0.4.1"
+  VERSION = "0.4.3"
 end

data/lib/smith/workflow/agent_result.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    # rubocop:disable Style/RedundantStructKeywordInit
+    AgentResult = Struct.new(
+      :content, :input_tokens, :output_tokens, :cost, :model_used,
+      keyword_init: true
+    ) do
+      def self.from_response(response, content, model_used: nil)
+        new(
+          content: content,
+          input_tokens: response.respond_to?(:input_tokens) ? response.input_tokens : nil,
+          output_tokens: response.respond_to?(:output_tokens) ? response.output_tokens : nil,
+          cost: nil,
+          model_used: model_used
+        )
+      end
+
+      def usage_known?
+        !input_tokens.nil? && !output_tokens.nil?
+      end
+    end
+    # rubocop:enable Style/RedundantStructKeywordInit
+  end
+end

data/lib/smith/workflow/branch_env.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    # rubocop:disable Style/RedundantStructKeywordInit
+    BranchEnv = Struct.new(
+      :prepared_input, :guardrail_sources, :scoped_store, :branch_estimates, :deadline,
+      keyword_init: true
+    ) do
+      def setup_thread
+        Smith::Tool.current_guardrails = guardrail_sources
+        Smith::Tool.current_deadline = deadline
+        Smith.scoped_artifacts = scoped_store
+      end
+
+      def teardown_thread
+        Smith::Tool.current_guardrails = nil
+        Smith::Tool.current_deadline = nil
+        Smith.scoped_artifacts = nil
+      end
+    end
+    # rubocop:enable Style/RedundantStructKeywordInit
+  end
+end

data/lib/smith/workflow/budget_integration.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "agent_result"
+
 module Smith
   class Workflow
     module BudgetIntegration
@@ -30,19 +32,33 @@ module Smith
       def reconcile_branch_budget(ledger, estimates, agent_result: nil)
         return unless ledger && estimates
 
-        actuals = extract_actuals(agent_result)
+        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]))
         end
       end
 
-      def extract_actuals(agent_result)
+      def extract_actuals(agent_results)
+        results = Array(agent_results).compact
+
         {
-          tokens: (agent_result&.input_tokens || 0) + (agent_result&.output_tokens || 0),
-          cost: agent_result&.cost || 0
+          tokens: results.sum { |result| (result.input_tokens || 0) + (result.output_tokens || 0) },
+          cost: results.sum { |result| result.cost || 0 }
         }
       end
 
+      def agent_results_for_settlement(agent_result = nil)
+        [*failed_billable_attempts, agent_result].compact
+      end
+
+      def failed_billable_attempts
+        Array(Thread.current[:smith_failed_agent_results])
+      end
+
+      def clear_failed_billable_attempts
+        Thread.current[:smith_failed_agent_results] = []
+      end
+
       def actual_for_dimension(dim, actual_tokens, actual_cost = 0)
         return actual_tokens if TOKEN_DIMENSIONS.include?(dim)
         return actual_cost if COST_DIMENSIONS.include?(dim)
@@ -59,7 +75,7 @@ module Smith
       def settle_budget_on_failure(ledger, estimates, agent_result)
         return unless ledger && estimates
 
-        if agent_result
+        if agent_result || failed_billable_attempts.any?
           reconcile_branch_budget(ledger, estimates, agent_result: agent_result)
         else
           release_branch_budget(ledger, estimates)
@@ -85,6 +101,12 @@ module Smith
         { branch: index, agent: transition.agent_name, output: agent_result ? agent_result.content : result }
       end
 
+      def finalize_named_branch(branch_key, agent_name, result, ledger, reserved)
+        agent_result = result.is_a?(Workflow::AgentResult) ? result : nil
+        reconcile_branch_budget(ledger, reserved, agent_result: agent_result)
+        { branch: branch_key, agent: agent_name, output: agent_result ? agent_result.content : result }
+      end
+
       def estimate_for_dimension(dim, limit, branch_count)
         return 0 unless BUDGET_DIMENSIONS.include?(dim)
 

data/lib/smith/workflow/deterministic_execution.rb

@@ -29,7 +29,7 @@ module Smith
           session_messages: snapshot_value(@session_messages || []),
           tool_results: snapshot_value(@tool_results || []),
           state: @state,
-          transition_name: transition.name
+          transition: transition
         )
       end
 

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)
@@ -91,7 +88,7 @@ module Smith
         when Hash
           deep_symbolize_evaluation(evaluation)
         when String
-          parsed = (JSON.parse(evaluation, symbolize_names: true) rescue nil)
+          parsed = parse_evaluation_json(evaluation)
           parsed.is_a?(Hash) ? parsed : evaluation
         else
           evaluation
@@ -155,9 +152,12 @@ module Smith
 
       def invoke_agent_with_budget(agent_class, prepared_input)
         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)
         end
+      ensure
+        clear_failed_billable_attempts
       end
 
       def invoke_with_call_ledger(agent_class, prepared_input)
@@ -179,12 +179,20 @@ module Smith
       # routes through on_threshold and returns the resulting value
       # (non-nil terminates the loop with that as the step output).
       def check_improvement_threshold!(evaluation, state, round)
-        return nil unless stop_for_threshold?(evaluation[:score], state.last_score, state.config[:improvement_threshold])
+        unless stop_for_threshold?(evaluation[:score], state.last_score, state.config[:improvement_threshold])
+          return nil
+        end
 
         handle_exit(state, :on_threshold,
                     "optimization improvement below threshold after round #{round + 1}")
       end
 
+      def parse_evaluation_json(evaluation)
+        JSON.parse(evaluation, symbolize_names: true)
+      rescue JSON::ParserError
+        nil
+      end
+
       def prepare_generator_input(prepared_input, round, prior_candidate, feedback)
         return prepared_input if round.zero?
 

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
@@ -8,13 +10,15 @@ module Smith
       include EvaluatorOptimizer
       include OrchestratorWorker
       include ParallelExecution
+      include FanoutExecution
+      include RetryExecution
       include DeterministicExecution
 
       private
 
       def execute_step(transition)
         setup_step_context
-        output = with_scoped_artifacts { run_guarded_step(transition) }
+        output = with_scoped_artifacts { run_with_retry_policy(transition) }
         complete_step(transition, output)
       rescue StandardError => e
         @outcome = nil
@@ -40,6 +44,7 @@ module Smith
 
       def run_guarded_step(transition)
         return dispatch_step(transition) if transition.deterministic?
+        return run_guarded_fanout_step(transition) if transition.fanout?
 
         agent_class = resolve_agent_class(transition)
         run_input_guardrails(agent_class)
@@ -93,6 +98,7 @@ module Smith
 
       def execute_serial_step(transition, prepared_input: nil)
         Thread.current[:smith_last_agent_result] = nil
+        clear_failed_billable_attempts
         ledger = effective_call_ledger
         reserved = reserve_for_serial(transition, ledger)
         begin
@@ -104,6 +110,7 @@ module Smith
         ensure
           settle_budget_on_failure(ledger, reserved, Thread.current[:smith_last_agent_result]) if reserved
           Thread.current[:smith_last_agent_result] = nil
+          clear_failed_billable_attempts
         end
       end