smith-agents 0.10.0 → 0.11.0

data/lib/smith/agent.rb

@@ -11,9 +11,10 @@ module Smith
     EXECUTION_IDENTITY_UNSET = Object.new.freeze
     TOOL_BUDGET_EXHAUSTION_UNSET = Object.new.freeze
     TOOL_BUDGET_EXHAUSTION_POLICIES = %i[raise complete].freeze
+    BUDGET_KEYS = %i[token_limit cost wall_clock tool_calls total_tokens total_cost].freeze
 
     private_constant :EXECUTION_IDENTITY_UNSET
-    private_constant :TOOL_BUDGET_EXHAUSTION_UNSET, :TOOL_BUDGET_EXHAUSTION_POLICIES
+    private_constant :TOOL_BUDGET_EXHAUSTION_UNSET, :TOOL_BUDGET_EXHAUSTION_POLICIES, :BUDGET_KEYS
 
     # Reserved input names auto-injected by the normalizer into
     # runtime_context. User-side `inputs :name` calls cannot redeclare
@@ -30,6 +31,7 @@ module Smith
         subclass.instance_variable_set(:@output_schema_class, @output_schema_class)
         subclass.instance_variable_set(:@data_volume, @data_volume)
         subclass.instance_variable_set(:@fallback_models_list, @fallback_models_list&.dup&.freeze)
+        subclass.instance_variable_set(:@fallback_models_block, @fallback_models_block)
         subclass.instance_variable_set(:@model_block, @model_block)
         subclass.instance_variable_set(:@tool_budget_exhaustion, @tool_budget_exhaustion)
         subclass.instance_variable_set(:@execution_identity, nil)
@@ -48,6 +50,12 @@ module Smith
       def budget(**opts)
         return @budget_config if opts.empty?
 
+        unknown = opts.keys - BUDGET_KEYS
+        unless unknown.empty?
+          raise ArgumentError, "agent budget does not accept #{unknown.map(&:inspect).join(", ")}; " \
+                               "accepted keys are #{BUDGET_KEYS.map(&:inspect).join(", ")}"
+        end
+
         @budget_config = opts
       end
 

data/lib/smith/budget/amount_representation.rb

@@ -2,6 +2,7 @@
 
 require "bigdecimal"
 require "dry-initializer"
+require_relative "decimal_context"
 
 module Smith
   module Budget
@@ -26,6 +27,25 @@ module Smith
         finite_float!(amount)
       end
 
+      # Remaining capacity, or one of parts equal shares of it, is reserved as
+      # read, so parts reservations of the external value must never exceed the
+      # exact amount. An Integer keeps floor division; a Float steps down until
+      # its decimal form fits, which takes O(1) steps because Float division
+      # lands within one ulp of the exact share.
+      def externalize_remaining(key, amount, parts = 1)
+        unless parts.is_a?(Integer) && parts.positive?
+          raise ArgumentError, "budget share parts must be a positive Integer"
+        end
+
+        share = externalize_amount(key, amount) / parts
+        return share unless share.is_a?(Float)
+
+        DecimalContext.call do
+          share = share.prev_float while internalize_amount(share) * parts > amount
+        end
+        share
+      end
+
       private
 
       def internalize_amount(amount)

data/lib/smith/budget/ledger.rb

@@ -58,12 +58,16 @@ module Smith
         @mutex.synchronize { release_reservation(token) }
       end
 
-      def remaining(key)
+      def remaining(key) = remaining_share(key, 1)
+
+      # One of parts equal shares of the remaining amount, taken from the exact
+      # internal value so that parts reservations of it always fit.
+      def remaining_share(key, parts)
         dimension = @amount_contract.dimension!(key)
         @amount_contract.known_dimension!(dimension)
         @mutex.synchronize do
           amount = @state_transition.remaining(@publication.state, dimension)
-          @representation.externalize_amount(dimension, amount)
+          @representation.externalize_remaining(dimension, amount, parts)
         end
       end
 

data/lib/smith/context/state_injection.rb

@@ -6,19 +6,29 @@ module Smith
       MARKER = "[smith:injected-state]"
 
       def self.inject(messages, formatter:, persisted:)
-        content = "#{MARKER}\n#{formatter.call(persisted)}"
+        text = formatter.call(persisted).to_s
+        content = "#{MARKER}\n#{text}"
 
         existing_index = messages.index do |message|
           message_content = message[:content] || message["content"]
           message_content.is_a?(String) && message_content.start_with?(MARKER)
         end
 
-        if existing_index
+        if blank?(text)
+          without_marker(messages, existing_index)
+        elsif existing_index
           messages.dup.tap { |msgs| msgs[existing_index] = { role: :system, content: content } }
         else
           messages + [{ role: :system, content: content }]
         end
       end
+
+      def self.blank?(text) = text.valid_encoding? && text.strip.empty?
+
+      def self.without_marker(messages, index)
+        index ? messages.dup.tap { |msgs| msgs.delete_at(index) } : messages
+      end
+      private_class_method :blank?, :without_marker
     end
   end
 end

data/lib/smith/diagnostic_text.rb

@@ -9,7 +9,10 @@ module Smith
     STRING_BYTESIZE = String.instance_method(:bytesize)
     STRING_BYTESLICE = String.instance_method(:byteslice)
     MODULE_MATCH = Module.instance_method(:===)
-    private_constant :TRUNCATION_MARKER, :STRING_BYTESIZE, :STRING_BYTESLICE, :MODULE_MATCH
+    MODULE_NAME = Module.instance_method(:name)
+    OBJECT_CLASS = Object.instance_method(:class)
+    private_constant :TRUNCATION_MARKER, :STRING_BYTESIZE, :STRING_BYTESLICE, :MODULE_MATCH, :MODULE_NAME,
+                     :OBJECT_CLASS
 
     extend Dry::Initializer
 
@@ -18,6 +21,12 @@ module Smith
 
     def self.capture(value, max_bytes: MAX_BYTES) = new(value, max_bytes:).call
 
+    # An error's class name, read through the native lookups so the error
+    # cannot misreport it, and bounded like any diagnostic identifier.
+    def self.error_class_name(error)
+      capture(MODULE_NAME.bind_call(OBJECT_CLASS.bind_call(error)) || "anonymous_error", max_bytes: 512)
+    end
+
     def call
       validate_limit!
       text = utf8_prefix

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

@@ -31,10 +31,26 @@ module Smith
           )
           return
         else
+          check_ttl_support(report, adapter)
           check_persist_and_restore(report, adapter)
           check_resume_after_restore(report, adapter)
         end
 
+        # ActiveRecordStore refuses every write that carries a TTL, so a
+        # configured global TTL would fail the first persisted run.
+        def self.check_ttl_support(report, adapter)
+          ttl = ::Smith.config.persistence_ttl
+          return if ttl.nil? || !adapter.is_a?(::Smith::PersistenceAdapters::ActiveRecordStore)
+
+          report.add(
+            name: "durability.ttl",
+            status: :fail,
+            message: "ActiveRecordStore cannot expire workflow state; persistence_ttl must be nil",
+            detail: "Smith.config.persistence_ttl is #{ttl.inspect}, so every persisted write refuses it. " \
+                    "Set it to nil, or use an adapter that honours TTL."
+          )
+        end
+
         def self.check_persist_and_restore(report, adapter)
           workflow_class = build_probe_class
           payload = JSON.generate(workflow_class.new.to_state)

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

@@ -17,7 +17,10 @@ module Smith
         OPTIONAL_CAPABILITIES = Smith::PersistenceAdapters::OPTIONAL_METHODS
 
         def run(report)
-          adapter = resolve_adapter
+          adapter = Smith.persistence_adapter
+        rescue StandardError => e
+          report_invalid_adapter(report, e)
+        else
           return report_missing_adapter(report) if adapter.nil?
 
           missing = OPTIONAL_CAPABILITIES.reject { |cap| capability_available?(adapter, cap) }
@@ -26,12 +29,6 @@ module Smith
           report_missing_capabilities(report, adapter, missing)
         end
 
-        def resolve_adapter
-          Smith.persistence_adapter
-        rescue StandardError
-          nil
-        end
-
         def capability_available?(adapter, capability)
           return false unless Smith::PersistenceAdapters.supports?(adapter, capability)
           return true unless capability == :persistence_identity
@@ -42,6 +39,15 @@ module Smith
           false
         end
 
+        def report_invalid_adapter(report, error)
+          report.add(
+            name: "persistence.capabilities",
+            status: :fail,
+            message: "Persistence adapter configuration is invalid",
+            detail: error.message
+          )
+        end
+
         def report_missing_adapter(report)
           report.add(
             name: "persistence.capabilities",

data/lib/smith/errors.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "diagnostic_text"
 require_relative "error"
 require_relative "persisted_failure_invalid"
 require_relative "pricing_configuration_error"
@@ -88,6 +89,11 @@ module Smith
   class AgentError < Error; end
 
   class BlankAgentOutputError < AgentError
+    DETAIL_NAMES = %i[agent_name model_used].freeze
+    DETAIL_KEYS = DETAIL_NAMES.to_h { |name| [name.to_s.freeze, name] }.freeze
+    MAX_DETAIL_BYTES = 512
+    private_constant :DETAIL_NAMES, :DETAIL_KEYS, :MAX_DETAIL_BYTES
+
     attr_reader :agent_name, :model_used
 
     def initialize(agent_name:, model_used:)
@@ -101,6 +107,46 @@ module Smith
 
       super(detail)
     end
+
+    def details
+      {
+        agent_name: agent_name && DiagnosticText.capture(agent_name.to_s, max_bytes: MAX_DETAIL_BYTES),
+        model_used: model_used && DiagnosticText.capture(model_used.to_s, max_bytes: MAX_DETAIL_BYTES)
+      }.freeze
+    end
+
+    def self.from_details(details)
+      values = normalize_details(details)
+      new(agent_name: values.fetch(:agent_name)&.to_sym, model_used: values.fetch(:model_used))
+    end
+
+    def self.normalize_details(details)
+      raise ArgumentError, "blank agent output details must be a Hash" unless details.is_a?(Hash)
+
+      values = {}
+      Hash.instance_method(:each_pair).bind_call(details) do |key, value|
+        name = key.is_a?(Symbol) ? key : DETAIL_KEYS[key]
+        unless DETAIL_NAMES.include?(name)
+          raise ArgumentError, "blank agent output details contain an unknown attribute"
+        end
+        raise ArgumentError, "blank agent output details contain a duplicate attribute" if values.key?(name)
+
+        values[name] = bounded_detail(name, value)
+      end
+      raise ArgumentError, "blank agent output details are incomplete" unless values.length == DETAIL_NAMES.length
+
+      values
+    end
+
+    def self.bounded_detail(name, value)
+      return value if value.nil?
+
+      bounded = value.is_a?(String) && value.valid_encoding? && value.bytesize <= MAX_DETAIL_BYTES
+      raise ArgumentError, "blank agent output detail #{name} must be bounded text" unless bounded
+
+      value
+    end
+    private_class_method :normalize_details, :bounded_detail
   end
 
   class WorkflowError < Error; end
@@ -185,15 +231,20 @@ module Smith
   # `idempotency_mode :strict`. Signals that a previous worker crashed
   # between `persist!` (before advance) and `persist!` (after advance);
   # the step's effects are unknown, so blindly re-running could
-  # double-execute non-idempotent agent calls or tools.
+  # double-execute non-idempotent agent calls or tools. `state` is the
+  # persisted state the interrupted step started from and `transition` the
+  # next transition the payload records; each is nil when unknown.
   class StepInProgressOnRestore < Error
-    attr_reader :workflow, :persistence_key
+    attr_reader :workflow, :persistence_key, :state, :transition
 
-    def initialize(workflow:, persistence_key:)
+    def initialize(workflow:, persistence_key:, state: nil, transition: nil)
       @workflow = workflow
       @persistence_key = persistence_key
+      @state = state.to_sym if state.is_a?(String) || state.is_a?(Symbol)
+      @transition = transition.to_sym if transition.is_a?(String) || transition.is_a?(Symbol)
       super(
-        "step in progress on restore for #{workflow} key=#{persistence_key.inspect}: " \
+        "step in progress on restore for #{workflow} key=#{persistence_key.inspect}" \
+        "#{" state=#{@state.inspect}" if @state}: " \
         "a previous worker crashed mid-step. Hosts using idempotency_mode :strict must " \
         "decide whether to clear the persisted state (idempotent re-run unsafe) or " \
         "switch to :lax (assume re-run is safe)."

data/lib/smith/persistence_adapters/active_record_exact_store.rb

@@ -5,9 +5,8 @@ module Smith
     module ActiveRecordExactStore
       attr_reader :persistence_identity
 
-      def replace_exact(key, payload, expected_payload:, ttl: nil) # rubocop:disable Lint/UnusedMethodArgument
-        ensure_version_column!
-        ensure_locking_configuration!
+      def replace_exact(key, payload, expected_payload:, ttl: nil)
+        ensure_versioned_write!(ttl)
         model = model_class
         ensure_exact_schema!(model)
         ActiveRecordExactWrite.new(
@@ -25,6 +24,12 @@ module Smith
 
       private
 
+      def ensure_versioned_write!(ttl)
+        PersistenceAdapters.refuse_active_record_ttl!(ttl)
+        ensure_version_column!
+        ensure_locking_configuration!
+      end
+
       def ensure_exact_schema!(model)
         ensure_exact_payload_column!(model)
         ensure_exact_key_uniqueness!(model)

data/lib/smith/persistence_adapters/active_record_store.rb

@@ -16,10 +16,8 @@ module Smith
         @persistence_identity = identity.to_s.dup.freeze if identity
       end
 
-      def store(key, payload, ttl: nil) # rubocop:disable Lint/UnusedMethodArgument
-        # TTL is deferred for ActiveRecordStore — would require an
-        # `expires_at` column + a periodic sweeper job. Ignored here;
-        # documented as a known limitation.
+      def store(key, payload, ttl: nil)
+        PersistenceAdapters.refuse_active_record_ttl!(ttl)
         Retry.with_retries(operation: :store, transient: ActiveRecordConnectionErrors.classes) do
           record = model_class.find_or_initialize_by(@key_column => key)
           record.public_send(:"#{@payload_column}=", payload)
@@ -47,9 +45,8 @@ module Smith
       # `lock_version` column. Requires the AR model to have a
       # `lock_version` (or configured) integer column with default 0.
       # If absent, raises ArgumentError directing the host to migrate.
-      def store_versioned(key, payload, expected_version:, ttl: nil) # rubocop:disable Lint/UnusedMethodArgument
-        ensure_version_column!
-        ensure_locking_configuration!
+      def store_versioned(key, payload, expected_version:, ttl: nil)
+        ensure_versioned_write!(ttl)
 
         write_versioned(key, payload, expected_version)
       rescue *ActiveRecordConnectionErrors.classes => e

data/lib/smith/persistence_adapters.rb

@@ -71,6 +71,16 @@ module Smith
     end
     private_class_method :build
 
+    # ActiveRecordStore's host table has no expiry column, so a TTL could
+    # only be ignored. Its writes fail closed instead of silently keeping
+    # state forever; reads and deletes never take a TTL and keep working.
+    def self.refuse_active_record_ttl!(ttl)
+      return if ttl.nil?
+
+      raise ArgumentError,
+            "ActiveRecordStore cannot expire workflow state; persistence_ttl must be nil, got #{ttl.inspect}"
+    end
+
     # Capability introspection used by Workflow#persist! to decide
     # whether the adapter supports optimistic locking via store_versioned.
     def self.supports?(adapter, capability)

data/lib/smith/provider_permanent_failure.rb

@@ -1,9 +1,15 @@
 # frozen_string_literal: true
 
+require_relative "diagnostic_text"
 require_relative "error"
 
 module Smith
   class ProviderPermanentFailure < Error
+    DETAIL_NAMES = %i[provider model_id source_error_class].freeze
+    DETAIL_KEYS = DETAIL_NAMES.to_h { |name| [name.to_s.freeze, name] }.freeze
+    MAX_DETAIL_BYTES = 512
+    private_constant :DETAIL_NAMES, :DETAIL_KEYS, :MAX_DETAIL_BYTES
+
     attr_reader :provider, :model_id, :source_error_class
 
     def initialize(message, provider:, model_id:, source_error_class:)
@@ -12,5 +18,43 @@ module Smith
       @source_error_class = source_error_class.to_s.dup.freeze
       super(message)
     end
+
+    def details
+      {
+        provider: provider && DiagnosticText.capture(provider.to_s, max_bytes: MAX_DETAIL_BYTES),
+        model_id: DiagnosticText.capture(model_id, max_bytes: MAX_DETAIL_BYTES),
+        source_error_class: DiagnosticText.capture(source_error_class, max_bytes: MAX_DETAIL_BYTES)
+      }.freeze
+    end
+
+    def self.from_details(details, message: nil)
+      new(message, **normalize_details(details))
+    end
+
+    def self.normalize_details(details)
+      raise ArgumentError, "provider failure details must be a Hash" unless details.is_a?(Hash)
+
+      values = {}
+      Hash.instance_method(:each_pair).bind_call(details) do |key, value|
+        name = key.is_a?(Symbol) ? key : DETAIL_KEYS[key]
+        raise ArgumentError, "provider failure details contain an unknown attribute" unless DETAIL_NAMES.include?(name)
+        raise ArgumentError, "provider failure details contain a duplicate attribute" if values.key?(name)
+
+        values[name] = bounded_detail(name, value)
+      end
+      raise ArgumentError, "provider failure details are incomplete" unless values.length == DETAIL_NAMES.length
+
+      values
+    end
+
+    def self.bounded_detail(name, value)
+      return value if name == :provider && value.nil?
+
+      bounded = value.is_a?(String) && value.valid_encoding? && value.bytesize <= MAX_DETAIL_BYTES
+      raise ArgumentError, "provider failure detail #{name} must be bounded text" unless bounded
+
+      value
+    end
+    private_class_method :normalize_details, :bounded_detail
   end
 end

data/lib/smith/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Smith
-  VERSION = "0.10.0"
+  VERSION = "0.11.0"
   EXECUTION_SEMANTICS_VERSION = "5"
 end

data/lib/smith/workflow/budget_integration.rb

@@ -22,7 +22,7 @@ module Smith
         return nil unless ledger
 
         ledger.limits.each_with_object({}) do |(dim, _limit), est|
-          per_branch = estimate_for_dimension(dim, ledger.remaining(dim), branch_count)
+          per_branch = estimate_for_dimension(dim, ledger.remaining_share(dim, branch_count))
           cap = agent_cap_for_dimension(dim, agent_budget)
           est[dim] = cap ? [per_branch, cap].min : per_branch
         end
@@ -117,10 +117,10 @@ module Smith
         { branch: branch_key, agent: agent_name, output: agent_result ? agent_result.content : result }
       end
 
-      def estimate_for_dimension(dim, limit, branch_count)
+      def estimate_for_dimension(dim, share)
         return 0 unless BUDGET_DIMENSIONS.include?(dim)
 
-        TOKEN_DIMENSIONS.include?(dim) ? [limit / branch_count, 1].max : limit / branch_count
+        TOKEN_DIMENSIONS.include?(dim) ? [share, 1].max : share
       end
 
       def agent_cap_for_dimension(dim, agent_budget)

data/lib/smith/workflow/deterministic_execution.rb

@@ -38,7 +38,7 @@ module Smith
         @context.merge!(step.context_writes)
         step.context_writes.each_key { |key| record_persisted_key!(key) }
         @router_next_transition = step.routed_to if step.routed_to
-        @outcome = snapshot_value(step.outcome) if step.outcome
+        @outcome = symbolize_value(snapshot_value(step.outcome)) if step.outcome
       end
 
       def emit_deterministic_trace(transition, result:, routed_to: nil, error: nil, outcome_kind: nil)

data/lib/smith/workflow/deterministic_step.rb

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

data/lib/smith/workflow/dsl.rb

@@ -3,6 +3,9 @@
 module Smith
   class Workflow
     module DSL
+      BUDGET_KEYS = %i[total_tokens token_limit total_cost tool_calls wall_clock].freeze
+      private_constant :BUDGET_KEYS
+
       def self.included(base)
         base.extend(ClassMethods)
       end
@@ -64,6 +67,12 @@ module Smith
         def budget(**opts)
           return @budget_config if opts.empty?
 
+          unknown = opts.keys - BUDGET_KEYS
+          unless unknown.empty?
+            raise ArgumentError, "workflow budget does not accept #{unknown.map(&:inspect).join(", ")}; " \
+                                 "accepted keys are #{BUDGET_KEYS.map(&:inspect).join(", ")}"
+          end
+
           @budget_config = opts
         end
 
@@ -196,11 +205,12 @@ module Smith
         #
         # Wiring contract: when the resolved TTL is non-nil,
         # Workflow#persist! forwards it to the adapter as a `ttl:`
-        # kwarg. Shipped adapters (Memory, RedisStore, CacheStore,
-        # ActiveRecordStore) accept this kwarg; external duck-typed
-        # adapters that implement only the bare REQUIRED_METHODS contract
-        # without a `ttl:` kwarg will only break when a host actually
-        # opts into TTL.
+        # kwarg. Memory, RedisStore, and CacheStore honour it;
+        # ActiveRecordStore cannot expire state and refuses a non-nil TTL
+        # before writing, which a persisted run reaches before its first
+        # step. External duck-typed adapters that implement only the bare
+        # REQUIRED_METHODS contract without a `ttl:` kwarg will only break
+        # when a host actually opts into TTL.
         def persistence_ttl(seconds = nil)
           return @persistence_ttl if seconds.nil?
 

data/lib/smith/workflow/durability.rb

@@ -389,7 +389,7 @@ module Smith
       def invoke_on_step_callback(step, callback)
         callback&.call(step)
       rescue StandardError => e
-        Smith.config.logger&.error("Smith::Workflow on_step callback error: #{e.message}")
+        Smith.config.logger&.error("Smith::Workflow on_step callback error: #{e.message} (#{e.class})")
       end
     end
   end