smith-agents 0.7.0 → 0.10.0

data/lib/smith/errors.rb

@@ -1,12 +1,21 @@
 # frozen_string_literal: true
 
 require_relative "error"
+require_relative "persisted_failure_invalid"
+require_relative "pricing_configuration_error"
+require_relative "provider_permanent_failure"
+require_relative "tool_capture_failed"
+require_relative "tool_execution_not_admitted"
+require_relative "tool_failure_notification_failed"
 
 module Smith
   # Classification surface for host retry policies. Smith owns the
   # answer to "should the workflow attempt be retried?" so consumers
   # don't reimplement the case statement in every Execution / Job.
   module Errors
+    MODULE_MATCH = Module.instance_method(:===)
+    private_constant :MODULE_MATCH
+
     # Returns true when the host should retry the workflow attempt.
     # AgentError + DeadlineExceeded are always retryable.
     # DeterministicStepFailure + ToolGuardrailFailed honor their
@@ -16,7 +25,7 @@ module Smith
       return false if error.nil?
 
       composite_failure = defined?(Smith::Workflow::Composite::BranchFailure) &&
-                          error.is_a?(Smith::Workflow::Composite::BranchFailure)
+                          MODULE_MATCH.bind_call(Smith::Workflow::Composite::BranchFailure, error)
       return false if composite_failure
 
       case error
@@ -29,6 +38,27 @@ module Smith
       end
     end
 
+    def self.retry_forbidden?(error)
+      return false if error.nil?
+
+      retry_forbidden_classes.any? { |error_class| MODULE_MATCH.bind_call(error_class, error) }
+    end
+
+    def self.retry_forbidden_class?(error_class)
+      retry_forbidden_classes.any? { |forbidden| error_class <= forbidden }
+    end
+
+    def self.retry_forbidden_classes
+      @retry_forbidden_classes ||= [
+        Smith::ToolCaptureFailed,
+        Smith::ToolOutcomeUncertain,
+        Smith::ToolExecutionNotAdmitted,
+        Smith::ToolFailureNotificationFailed,
+        Smith::BoundedCompletionError,
+        Smith::PersistedFailureInvalid
+      ].freeze
+    end
+
     # Always-retryable error classes for explicit ActiveJob retry_on
     # allow-lists. Excludes the retryable-bearing families because
     # their retryability is per-raise, not per-class.
@@ -52,6 +82,9 @@ module Smith
   end
 
   class ToolPolicyDenied < Error; end
+  class ToolDispatchRejected < Error; end
+  class BoundedCompletionError < Error; end
+  class ToolOutcomeUncertain < Error; end
   class AgentError < Error; end
 
   class BlankAgentOutputError < AgentError

data/lib/smith/event.rb

@@ -3,9 +3,17 @@
 require "dry-struct"
 require "securerandom"
 
+require_relative "attribution"
+
 module Smith
   class Event < Dry::Struct
-    attribute(:execution_id, Types::String.default { SecureRandom.uuid })
-    attribute(:trace_id, Types::String.default { SecureRandom.uuid })
+    # Both ids default to the ambient Smith::Attribution execution key, so
+    # events emitted under one persisted run (or one host-seeded
+    # Attribution scope) share one identity a host can group by. Outside
+    # any scope, each event falls back to its own random UUID, so
+    # non-persisted, unseeded runs have no shared event identity. Callers
+    # may always pass explicit values.
+    attribute(:execution_id, Types::String.default { Smith::Attribution.ambient.execution_key || SecureRandom.uuid })
+    attribute(:trace_id, Types::String.default { Smith::Attribution.ambient.execution_key || SecureRandom.uuid })
   end
 end

data/lib/smith/events/bus.rb

@@ -18,19 +18,43 @@ module Smith
       end
     end
 
+    REGISTRY_MUTEX = Mutex.new
+    private_constant :REGISTRY_MUTEX
+
     class << self
+      # Registration-ordered snapshot of the live subscriptions. Cancelled
+      # subscriptions are detached from the registry, so this reflects only
+      # what will actually receive events.
       def subscriptions
-        @subscriptions ||= []
+        snapshot = REGISTRY_MUTEX.synchronize { registry.values.flatten }
+        snapshot.sort_by!(&:sequence_number)
       end
 
       def on(event_class, **opts, &block)
         sub = Subscription.new(event_class, handler: block, predicate: opts[:if])
-        subscriptions << sub
+        REGISTRY_MUTEX.synchronize do
+          @sequence = (@sequence || 0) + 1
+          sub.sequence_number = @sequence
+          (registry[event_class] ||= []) << sub
+        end
         sub
       end
 
+      # Removes a subscription from the registry. Called by
+      # Subscription#cancel; safe to call more than once.
+      def detach(subscription)
+        REGISTRY_MUTEX.synchronize do
+          bucket = registry[subscription.event_class]
+          next unless bucket
+
+          bucket.delete(subscription)
+          registry.delete(subscription.event_class) if bucket.empty?
+        end
+        nil
+      end
+
       def emit(event)
-        subscriptions.each { |sub| dispatch_to(sub, event) }
+        matching_subscriptions(event).each { |sub| dispatch_to(sub, event) }
       end
 
       def within
@@ -41,14 +65,48 @@ module Smith
       end
 
       def reset!
-        @subscriptions = []
+        REGISTRY_MUTEX.synchronize do
+          @registry = {}
+          @sequence = 0
+        end
       end
 
       private
 
+      def registry
+        @registry ||= {}
+      end
+
+      # Subscriptions live in per-class buckets so one emit touches only the
+      # buckets for the event's ancestors instead of scanning every
+      # subscription; `is_a?` dispatch semantics are preserved exactly
+      # because a subscription matches iff its registered class or module is
+      # among the event class's ancestors. The merged candidates are ordered
+      # by registration sequence, keeping subscription-order dispatch.
+      # Handlers run outside the registry lock so a handler may subscribe or
+      # cancel without deadlocking.
+      def matching_subscriptions(event)
+        # singleton_class.ancestors, not class.ancestors: it additionally
+        # covers modules mixed into the event instance via extend, which
+        # `is_a?` matched before the bucketed registry existed. Immediates
+        # (Integer, Symbol, Float) have no singleton class; they also cannot
+        # be extended, so their class ancestors are the complete `is_a?` set.
+        ancestors = begin
+          event.singleton_class.ancestors
+        rescue TypeError
+          event.class.ancestors
+        end
+        candidates = REGISTRY_MUTEX.synchronize do
+          ancestors.each_with_object([]) do |ancestor, found|
+            bucket = registry[ancestor]
+            found.concat(bucket) if bucket
+          end
+        end
+        candidates.sort_by!(&:sequence_number)
+      end
+
       def dispatch_to(sub, event)
         return if sub.cancelled?
-        return unless event.is_a?(sub.event_class)
         return if sub.predicate && !sub.predicate.call(event)
 
         sub.handler.call(event)

data/lib/smith/events/step_completed.rb

@@ -6,6 +6,9 @@ module Smith
       attribute :transition, Types::Strict::Symbol
       attribute :from, Types::Strict::Symbol.optional
       attribute :to, Types::Strict::Symbol
+      # The emitting workflow's class name; distinguishes nested-child steps
+      # from parent steps under the shared root execution identity.
+      attribute :workflow, Types::Strict::String.optional.default(nil)
     end
   end
 end

data/lib/smith/events/step_failed.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Smith
+  module Events
+    # Emitted from both step-failure paths (step-body failure and an
+    # unresolved transition routed to :fail), closing the success-only
+    # observation gap for failures that reach step handling. Terminal errors
+    # raised outside it (an unresolved transition with no :fail transition,
+    # transition-budget exhaustion, origin validation) still re-raise
+    # without a StepFailed. Carries bounded classification only, never raw
+    # error messages; `error_family` uses FailureRecord's taxonomy
+    # ("agent_error", "deadline_exceeded", ..., "other") and `retryable` is
+    # nil when the error does not declare retryability.
+    class StepFailed < Smith::Event
+      attribute :transition, Types::Strict::Symbol
+      attribute :from, Types::Strict::Symbol.optional
+      attribute :to, Types::Strict::Symbol.optional
+      attribute :error_class, Types::Strict::String
+      attribute :error_family, Types::Strict::String
+      attribute :retryable, Types::Strict::Bool.optional
+      # See StepCompleted#workflow.
+      attribute :workflow, Types::Strict::String.optional.default(nil)
+    end
+  end
+end

data/lib/smith/events/subscription.rb

@@ -4,6 +4,9 @@ module Smith
   module Events
     class Subscription
       attr_reader :event_class, :handler, :predicate
+      # Internal registration order, assigned by Events.on; dispatch and the
+      # subscriptions snapshot sort by it.
+      attr_accessor :sequence_number
 
       def initialize(event_class, handler:, predicate: nil)
         @event_class = event_class
@@ -12,8 +15,13 @@ module Smith
         @cancelled = false
       end
 
+      # Cancelling flags the subscription and detaches it from the registry
+      # (so it cannot leak). The flag check against an in-flight emit
+      # snapshot is best-effort: a dispatch already past the check may still
+      # deliver once after cancel returns.
       def cancel
         @cancelled = true
+        Events.detach(self)
       end
 
       def cancelled?

data/lib/smith/models/ambiguous_profile_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "../error"
+
+module Smith
+  module Models
+    class AmbiguousProfileError < Smith::Error; end
+  end
+end

data/lib/smith/models/collision_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "../error"
+
+module Smith
+  module Models
+    class CollisionError < Smith::Error; end
+  end
+end

data/lib/smith/models/inference.rb

@@ -82,6 +82,20 @@ module Smith
         [
           # ----- Anthropic -----
 
+          # Claude 5+ families (Fable/Mythos/Opus/Sonnet/Haiku): adaptive
+          # thinking, no temperature accepted (the API rejects an explicit
+          # temperature with a 400).
+          Rule.new(
+            provider: :anthropic,
+            matcher: lambda { |id|
+              m = id.match(/\Aclaude-(?:fable|mythos|opus|sonnet|haiku)-(\d+)/)
+              m && m[1].to_i >= 5
+            },
+            thinking_shape: :adaptive,
+            accepts_temperature: false,
+            tools_with_thinking_native: true,
+            tools_with_thinking_route: nil
+          ),
           # Opus 4.7+: adaptive thinking, no temperature accepted.
           Rule.new(
             provider: :anthropic,

data/lib/smith/models/normalizer.rb

@@ -2,6 +2,8 @@
 
 require "dry-initializer"
 
+require_relative "tool_routing"
+
 module Smith
   module Models
     # Per-chat-construction request shaper. Mutates a RubyLLM::Chat
@@ -96,73 +98,11 @@ module Smith
       end
 
       def normalize_tools_routing
-        # Stubbed chat objects in tests may not implement .tools; gracefully
-        # skip rather than crash on respond_to? check.
-        return unless chat.respond_to?(:tools)
-
-        tools = chat.tools.values
-        return if tools.empty?
-        return unless thinking_active?
-
-        return if profile.tools_with_thinking_native
-
-        if profile.tools_with_thinking_route == :responses &&
-           Smith.config.openai_api_mode == :auto
-          merge_params(openai_api_mode: :responses)
-          @decisions << Decision.new(kind: :routed_via_responses, model_id: profile.model_id, detail: nil)
-          return
-        end
-
-        drop_incompatible_tools(tools)
-      end
-
-      def thinking_active?
-        thinking = chat.instance_variable_get(:@thinking)
-        return true if thinking&.enabled?
-
-        # Also active if we already translated to adaptive (in which case
-        # @thinking is nil but params carry the thinking spec).
-        params = chat.instance_variable_get(:@params) || {}
-        params.key?(:thinking) || params.key?(:reasoning) || params.key?(:reasoning_effort)
-      end
-
-      def drop_incompatible_tools(tools)
-        effective_endpoint = effective_endpoint_for_compatibility
-        incompatible = tools.reject do |tool|
-          spec = tool.class.respond_to?(:compatible_with_spec) ? tool.class.compatible_with_spec : nil
-          if defined?(Smith::Tool::Compatibility)
-            Smith::Tool::Compatibility.allows?(spec, profile, effective_endpoint: effective_endpoint)
-          else
-            true
-          end
-        end
-        return if incompatible.empty?
-
-        retained = tools - incompatible
-        chat.with_tools(*retained, replace: true)
-
-        incompatible.each do |tool|
-          @decisions << Decision.new(
-            kind: :tool_dropped,
-            model_id: profile.model_id,
-            detail: { tool: tool.class.name }
-          )
-        end
-      end
-
-      # Profile.endpoint_mode reports the INTENDED endpoint (per the
-      # inference rule). Smith.config.openai_api_mode policy can downgrade
-      # the EFFECTIVE endpoint — e.g., a profile with route :responses
-      # actually uses :chat_completions when openai_api_mode is :off.
-      # The compatibility check needs the effective endpoint to make
-      # the right drop/keep decision.
-      def effective_endpoint_for_compatibility
-        if profile.tools_with_thinking_route == :responses &&
-           Smith.config.openai_api_mode != :auto
-          :chat_completions
-        else
-          profile.endpoint_mode
-        end
+        ToolRouting.new(
+          chat: chat,
+          profile: profile,
+          decision_recorder: method(:record_decision)
+        ).call
       end
 
       # with_params REPLACES @params in RubyLLM (chat.rb:96), so the
@@ -173,6 +113,10 @@ module Smith
         chat.with_params(**existing, **new_params)
       end
 
+      def record_decision(kind, model_id, detail)
+        @decisions << Decision.new(kind: kind, model_id: model_id, detail: detail)
+      end
+
       def emit_trace
         return if @decisions.empty?
         return unless defined?(Smith::Trace)

data/lib/smith/models/provider_qualified_registry.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module Smith
+  module Models
+    module ProviderQualifiedRegistry
+      def self.extended(registry)
+        registry.instance_variable_set(:@registry_monitor, Monitor.new)
+        registry.instance_variable_set(:@registry_index, {})
+      end
+
+      def find(model_id, provider: nil)
+        registry_monitor.synchronize do
+          registered_keys = registered_keys_for(model_id, provider:)
+          return nil if registered_keys.empty?
+
+          reject_ambiguous_lookup!(model_id, registered_keys)
+          resolve(registered_keys.first)
+        end
+      end
+
+      def register(profile)
+        registry_monitor.synchronize do
+          profile = normalized_profile(profile)
+          key = registry_key(profile.model_id, profile.provider)
+          existing = key?(key) ? resolve(key) : nil
+
+          return profile if existing == profile
+
+          raise_collision!(key, existing, profile) if existing
+
+          super(key, profile)
+          index_profile(profile, key)
+          profile
+        end
+      end
+
+      def all
+        registry_monitor.synchronize do
+          keys.map { |key| resolve(key) }.sort_by do |profile|
+            [profile.model_id, profile.provider.to_s]
+          end
+        end
+      end
+
+      def clear!
+        registry_monitor.synchronize do
+          @_container&.clear
+          @registry_index = {}
+        end
+      end
+
+      private
+
+      attr_reader :registry_monitor, :registry_index
+
+      def registered_keys_for(model_id, provider:)
+        normalized_id = normalize_key(model_id)
+        return registry_index.fetch(normalized_id, []) unless provider
+
+        key = registry_key(normalized_id, provider)
+        key?(key) ? [key] : []
+      end
+
+      def registry_key(model_id, provider)
+        [provider.to_sym, normalize_key(model_id)]
+      end
+
+      def reject_ambiguous_lookup!(model_id, registered_keys)
+        return unless registered_keys.length > 1
+
+        providers = registered_keys.map { |key| resolve(key).provider.to_s }.sort
+        raise AmbiguousProfileError,
+              "model #{normalize_key(model_id).inspect} has profiles for multiple providers: " \
+              "#{providers.join(", ")}; pass provider:"
+      end
+
+      def index_profile(profile, key)
+        model_id = normalize_key(profile.model_id)
+        registry_index[model_id] = [*registry_index.fetch(model_id, []), key].uniq.freeze
+      end
+
+      def normalized_profile(profile)
+        Profile.new(
+          **profile.to_h,
+          model_id: normalize_key(profile.model_id).freeze,
+          provider: profile.provider.to_sym
+        )
+      rescue NoMethodError, TypeError
+        raise ArgumentError, "model profile must expose model_id, provider, and profile attributes"
+      end
+
+      def raise_collision!(key, existing, replacement)
+        raise CollisionError,
+              "model profile collision for #{key.inspect}: existing #{existing.inspect}, " \
+              "replacement #{replacement.inspect}"
+      end
+    end
+  end
+end

data/lib/smith/models/tool_routing.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+module Smith
+  module Models
+    class ToolRouting
+      TOOL_ENDPOINTS = %i[chat_completions responses].freeze
+
+      private_constant :TOOL_ENDPOINTS
+
+      extend Dry::Initializer
+
+      option :chat
+      option :profile
+      option :decision_recorder
+
+      def call
+        return unless chat.respond_to?(:tools)
+
+        tools = chat.tools.values
+        return if tools.empty?
+
+        route_tools_with_thinking if thinking_active?
+        route_tools_for_compatibility(tools)
+        drop_incompatible_tools(tools)
+      end
+
+      private
+
+      def route_tools_with_thinking
+        return unless profile.provider == :openai
+        return if profile.tools_with_thinking_native
+        return unless profile.tools_with_thinking_route == :responses
+        return unless Smith.config.openai_api_mode == :auto
+
+        route_via_responses
+      end
+
+      def route_tools_for_compatibility(tools)
+        return unless profile.provider == :openai
+        return unless Smith.config.openai_api_mode == :auto
+        return if responses_routed?
+
+        forced_endpoint = forced_tool_endpoint(tools)
+        return if forced_endpoint == :chat_completions
+        return unless forced_endpoint == :responses ||
+                      compatible_tool_count(tools, :responses) > compatible_tool_count(tools, :chat_completions)
+
+        route_via_responses
+      end
+
+      def route_via_responses
+        return if responses_routed?
+
+        merge_params(openai_api_mode: :responses)
+        record(:routed_via_responses)
+      end
+
+      def drop_incompatible_tools(tools)
+        endpoint = responses_routed? ? :responses : :chat_completions
+        incompatible = tools.reject { |tool| tool_compatible_with?(tool, endpoint) }
+        return if incompatible.empty?
+
+        remaining = tools - incompatible
+        forced_choice = reset_invalid_tool_choice(remaining)
+        chat.with_tools(*remaining, replace: true)
+        incompatible.each_with_index do |tool, index|
+          record(:tool_dropped, dropped_tool_detail(tool, forced_choice, first: index.zero?))
+        end
+      end
+
+      def dropped_tool_detail(tool, forced_choice, first:)
+        detail = { tool: tool.class.name }
+        if forced_choice && (tool.name.to_sym == forced_choice.to_sym || (forced_choice == :required && first))
+          detail[:forced_choice_reset] = forced_choice
+        end
+        detail
+      end
+
+      def forced_tool_endpoint(tools)
+        choice = chat.tool_prefs[:choice]&.to_sym
+        return if %i[auto none required].include?(choice)
+
+        tool = tools.find { |candidate| candidate.name.to_sym == choice }
+        return unless tool
+
+        compatible_endpoints = TOOL_ENDPOINTS.select { |endpoint| tool_compatible_with?(tool, endpoint) }
+        compatible_endpoints.first if compatible_endpoints.one?
+      end
+
+      def reset_invalid_tool_choice(remaining)
+        choice = chat.tool_prefs[:choice]
+        return unless choice
+        return if %i[auto none].include?(choice)
+        return if choice == :required && remaining.any?
+        return if remaining.any? { |tool| tool.name.to_sym == choice.to_sym }
+
+        chat.tool_prefs[:choice] = nil
+        choice
+      end
+
+      def compatible_tool_count(tools, endpoint)
+        tools.count { |tool| tool_compatible_with?(tool, endpoint) }
+      end
+
+      def tool_compatible_with?(tool, endpoint)
+        return true unless defined?(Smith::Tool::Compatibility)
+
+        spec = tool.class.respond_to?(:compatible_with_spec) ? tool.class.compatible_with_spec : nil
+        Smith::Tool::Compatibility.allows?(spec, profile, effective_endpoint: endpoint)
+      end
+
+      def thinking_active?
+        thinking = chat.instance_variable_get(:@thinking)
+        return true if thinking&.enabled?
+
+        current_params.key?(:thinking) || current_params.key?(:reasoning) ||
+          current_params.key?(:reasoning_effort)
+      end
+
+      def responses_routed?
+        mode = current_params[:openai_api_mode] || current_params["openai_api_mode"]
+        mode.to_s == "responses"
+      end
+
+      def current_params
+        chat.instance_variable_get(:@params) || {}
+      end
+
+      def merge_params(**new_params)
+        chat.with_params(**current_params, **new_params)
+      end
+
+      def record(kind, detail = nil)
+        decision_recorder.call(kind, profile.model_id, detail)
+      end
+    end
+  end
+end