smith-agents 0.4.2 → 0.4.4

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.2"
+  VERSION = "0.4.4"
 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

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)

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