smith-agents 0.6.1 → 0.8.0

data/lib/smith/agent/provider_failure_handling.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Smith
+  class Agent
+    module ProviderFailureHandling
+      TRANSIENT_ERRORS = [
+        RubyLLM::ServerError,
+        RubyLLM::ServiceUnavailableError,
+        RubyLLM::OverloadedError,
+        RubyLLM::RateLimitError
+      ].freeze
+      MODEL_UNAVAILABLE_STATUSES = [404, 410].freeze
+      PROVIDER_ACCOUNT_ERRORS = [
+        RubyLLM::UnauthorizedError,
+        RubyLLM::PaymentRequiredError
+      ].freeze
+      MODEL_PERMISSION_ERRORS = [RubyLLM::ForbiddenError].freeze
+
+      private_constant :TRANSIENT_ERRORS, :MODEL_UNAVAILABLE_STATUSES,
+                       :PROVIDER_ACCOUNT_ERRORS, :MODEL_PERMISSION_ERRORS
+
+      private
+
+      def handle_provider_failure!(error, model_reference, agent_class, fallback_available:)
+        account_failed_attempt(error, model_reference, agent_class)
+        if completed_tool_calls?
+          raise Smith::ToolOutcomeUncertain.new(
+            "provider failed after tool execution began; retry or fallback could replay an uncertain outcome"
+          ), cause: error
+        end
+        return if fallback_eligible?(error) && fallback_available
+
+        raise terminal_provider_error(error, model_reference), cause: error
+      end
+
+      def provider_failure?(error)
+        error.is_a?(RubyLLM::Error) ||
+          (defined?(RubyLLM::ModelNotFoundError) && error.is_a?(RubyLLM::ModelNotFoundError)) ||
+          error.is_a?(Faraday::TimeoutError) ||
+          error.is_a?(Faraday::ConnectionFailed)
+      end
+
+      def provider_account_failure?(error)
+        PROVIDER_ACCOUNT_ERRORS.any? { |error_class| error.is_a?(error_class) }
+      end
+
+      def completed_tool_calls?
+        Tool.current_tool_execution_tracker&.started?
+      end
+
+      def fallback_eligible?(error)
+        transient_failure?(error) ||
+          transport_failure?(error) ||
+          provider_account_failure?(error) ||
+          model_permission_failure?(error) ||
+          model_unavailable?(error)
+      end
+
+      def transient_failure?(error)
+        TRANSIENT_ERRORS.any? { |error_class| error.is_a?(error_class) }
+      end
+
+      def transport_failure?(error)
+        error.is_a?(Faraday::TimeoutError) || error.is_a?(Faraday::ConnectionFailed)
+      end
+
+      def model_permission_failure?(error)
+        MODEL_PERMISSION_ERRORS.any? { |error_class| error.is_a?(error_class) }
+      end
+
+      def model_unavailable?(error)
+        return true if defined?(RubyLLM::ModelNotFoundError) && error.is_a?(RubyLLM::ModelNotFoundError)
+        return false unless error.respond_to?(:response)
+
+        response = error.response
+        response.respond_to?(:status) && MODEL_UNAVAILABLE_STATUSES.include?(response.status.to_i)
+      rescue StandardError
+        false
+      end
+
+      def terminal_provider_error(error, model_reference)
+        return Smith::AgentError.new(error.message) if transient_failure?(error) || transport_failure?(error)
+
+        Smith::ProviderPermanentFailure.new(
+          error.message,
+          provider: model_reference.provider,
+          model_id: model_reference.model_id,
+          source_error_class: error.class.name
+        )
+      end
+    end
+  end
+end

data/lib/smith/agent/provider_usage.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "dry-struct"
+
+require_relative "../types"
+
+module Smith
+  class Agent
+    class ProviderUsage < Dry::Struct
+      attribute :input_tokens, Types::Integer
+      attribute :output_tokens, Types::Integer
+
+      def self.from_message(message)
+        return unless message.respond_to?(:input_tokens) && message.respond_to?(:output_tokens)
+
+        input_tokens = message.input_tokens
+        output_tokens = message.output_tokens
+        return unless input_tokens.is_a?(Integer) && output_tokens.is_a?(Integer)
+
+        new(input_tokens:, output_tokens:)
+      end
+
+      def total_tokens
+        input_tokens + output_tokens
+      end
+    end
+  end
+end

data/lib/smith/agent/reserved_input_bridge.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Smith
+  class Agent
+    module ReservedInputBridge
+      private
+
+      def partition_inputs(kwargs)
+        input_values, chat_options = super
+        provider = input_values[:provider]
+        chat_options[:provider] = provider if provider && provider.to_sym != :unknown
+        [input_values, chat_options]
+      end
+
+      def apply_configuration(chat_object, input_values:, persist_instructions:)
+        super(
+          chat_object,
+          input_values: reserved_inputs_for(chat_object, input_values),
+          persist_instructions:
+        )
+      end
+
+      def reserved_inputs_for(chat_object, input_values)
+        llm_chat = chat_object.respond_to?(:to_llm) ? chat_object.to_llm : chat_object
+        model = llm_chat.model if llm_chat.respond_to?(:model)
+        profile = resolve_profile(
+          model&.id || input_values[:model_id],
+          provider: actual_provider(llm_chat) || input_values[:provider]
+        )
+        return input_values unless profile
+
+        input_values.merge(
+          model_id: profile.model_id,
+          provider: profile.provider,
+          endpoint_mode: profile.endpoint_mode
+        )
+      end
+    end
+  end
+end

data/lib/smith/agent/usage_entry_recording.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Smith
+  class Agent
+    module UsageEntryRecording
+      private
+
+      def record_usage(agent_class, agent_result, attempt_kind, model_reference)
+        return unless agent_result.usage_known?
+
+        model_reference = coerce_model_reference(model_reference)
+        entry = build_usage_entry(agent_class, agent_result, attempt_kind, model_reference)
+        accumulate_usage(agent_result, entry)
+      end
+
+      def build_usage_entry(agent_class, agent_result, attempt_kind, model_reference)
+        Workflow::UsageEntry.new(
+          usage_id: SecureRandom.uuid,
+          agent_name: agent_class.register_as,
+          model: model_reference.model_id,
+          provider: model_reference.provider,
+          input_tokens: agent_result.input_tokens,
+          output_tokens: agent_result.output_tokens,
+          cost: agent_result.cost,
+          attempt_kind: attempt_kind,
+          recorded_at: Time.now.utc.iso8601
+        )
+      end
+
+      def accumulate_usage(agent_result, entry)
+        @usage_mutex.synchronize do
+          @total_tokens = (@total_tokens || 0) + agent_result.input_tokens + agent_result.output_tokens
+          @total_cost = (@total_cost || 0.0) + (agent_result.cost || 0.0)
+          @usage_entries << entry
+        end
+      end
+
+      def coerce_model_reference(value)
+        ModelReference.coerce(value)
+      end
+    end
+  end
+end

data/lib/smith/agent/usage_tracking.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require_relative "completion_usage_recording"
+require_relative "usage_entry_recording"
+
+module Smith
+  class Agent
+    module UsageTracking
+      include CompletionUsageRecording
+      include UsageEntryRecording
+
+      private
+
+      def account_failed_attempt(error, model_reference, agent_class)
+        return unless error.respond_to?(:input_tokens) && error.respond_to?(:output_tokens)
+
+        input = error.input_tokens
+        output = error.output_tokens
+        return unless input.is_a?(Integer) && output.is_a?(Integer)
+
+        record_failed_usage(agent_class, model_reference, input, output, :failed_attempt)
+      end
+
+      def account_completed_prefix(agent_class, model_reference, messages)
+        completion = Completion.from_messages(response: nil, messages: messages)
+        record_completion_usage(agent_class, completion, :partial_attempt, model_reference)
+      end
+
+      def record_failed_usage(agent_class, model_reference, input_tokens, output_tokens, attempt_kind)
+        model_reference = coerce_model_reference(model_reference)
+        cost = Smith::Pricing.compute_cost(
+          model: model_reference.model_id,
+          provider: model_reference.provider,
+          input_tokens:,
+          output_tokens:
+        )
+        agent_result = Workflow::AgentResult.new(
+          content: nil,
+          input_tokens:,
+          output_tokens:,
+          cost: cost,
+          model_used: model_reference.model_id,
+          provider_used: model_reference.provider
+        )
+        Thread.current[:smith_failed_agent_results] ||= []
+        Thread.current[:smith_failed_agent_results] << agent_result
+        record_usage(agent_class, agent_result, attempt_kind, model_reference)
+      end
+
+      def snapshot_and_finalize(agent_class, completion, model_reference)
+        model_reference = coerce_model_reference(model_reference)
+        agent_result = Workflow::AgentResult.new(
+          content: completion.content,
+          input_tokens: completion.input_tokens,
+          output_tokens: completion.output_tokens,
+          cost: nil,
+          model_used: model_reference.model_id,
+          provider_used: model_reference.provider
+        )
+        Thread.current[:smith_last_agent_result] = agent_result
+        emit_token_usage(agent_result)
+        compute_agent_cost(agent_result)
+        record_completion_usage(agent_class, completion, :completed_attempt, model_reference)
+
+        agent_result.content = run_after_completion(agent_class, agent_result.content, @context)
+        raise_blank_output!(agent_class, agent_result)
+        agent_result
+      end
+
+      def raise_blank_output!(agent_class, agent_result)
+        return unless blank_agent_output?(agent_result.content)
+
+        raise Smith::BlankAgentOutputError.new(
+          agent_name: agent_class.register_as,
+          model_used: agent_result.model_used
+        )
+      end
+
+      def blank_agent_output?(content)
+        return true if content.nil?
+        return content.strip.empty? if content.is_a?(String)
+
+        false
+      end
+
+      def emit_token_usage(agent_result)
+        return unless agent_result.usage_known?
+
+        Smith::Trace.record(
+          type: :token_usage,
+          data: {
+            input_tokens: agent_result.input_tokens,
+            output_tokens: agent_result.output_tokens,
+            model: agent_result.model_used,
+            provider: agent_result.provider_used
+          }.compact
+        )
+      end
+
+      def compute_agent_cost(agent_result)
+        return unless agent_result.usage_known?
+
+        model = agent_result.model_used
+        agent_result.cost = Smith::Pricing.compute_cost(
+          model: model,
+          provider: agent_result.provider_used,
+          input_tokens: agent_result.input_tokens,
+          output_tokens: agent_result.output_tokens
+        )
+      end
+    end
+  end
+end

data/lib/smith/agent.rb

@@ -2,10 +2,18 @@
 
 require "ruby_llm"
 
+require_relative "tool"
+
 module Smith
   class Agent < RubyLLM::Agent
+    require_relative "agent/model_reference"
+
     EXECUTION_IDENTITY_UNSET = Object.new.freeze
+    TOOL_BUDGET_EXHAUSTION_UNSET = Object.new.freeze
+    TOOL_BUDGET_EXHAUSTION_POLICIES = %i[raise complete].freeze
+
     private_constant :EXECUTION_IDENTITY_UNSET
+    private_constant :TOOL_BUDGET_EXHAUSTION_UNSET, :TOOL_BUDGET_EXHAUSTION_POLICIES
 
     # Reserved input names auto-injected by the normalizer into
     # runtime_context. User-side `inputs :name` calls cannot redeclare
@@ -21,8 +29,9 @@ module Smith
         subclass.instance_variable_set(:@guardrails_class, @guardrails_class)
         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)
+        subclass.instance_variable_set(:@fallback_models_list, @fallback_models_list&.dup&.freeze)
         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)
         subclass.instance_variable_set(:@registered_name, nil)
       end
@@ -42,6 +51,17 @@ module Smith
         @budget_config = opts
       end
 
+      def tool_budget_exhaustion(value = TOOL_BUDGET_EXHAUSTION_UNSET)
+        return @tool_budget_exhaustion || :raise if value.equal?(TOOL_BUDGET_EXHAUSTION_UNSET)
+
+        policy = value.respond_to?(:to_sym) ? value.to_sym : value
+        unless TOOL_BUDGET_EXHAUSTION_POLICIES.include?(policy)
+          raise ArgumentError, "tool_budget_exhaustion must be :raise or :complete"
+        end
+
+        @tool_budget_exhaustion = policy
+      end
+
       def guardrails(klass = nil)
         return @guardrails_class if klass.nil?
 
@@ -60,15 +80,6 @@ module Smith
         @data_volume = value
       end
 
-      def fallback_models(*models)
-        return @fallback_models_list if models.empty?
-
-        entries = models.flatten.compact.map(&:to_s)
-        raise Smith::WorkflowError, "fallback_models entries must not be blank" if entries.any?(&:empty?)
-
-        @fallback_models_list = entries.uniq
-      end
-
       def register_as(name = nil, publish: true)
         return @registered_name if name.nil?
 
@@ -85,52 +96,6 @@ module Smith
         Registry.ensure_registered(name.to_sym, self)
       end
 
-      # Extends RubyLLM::Agent.model with a block-form for context-driven
-      # resolution at chat-construction time.
-      #
-      # Static form `model "gpt-5-mini"`:
-      #   Stores into @chat_kwargs[:model] via RubyLLM's existing path.
-      #   Model id is fixed at class-load time.
-      #
-      # Block form `model { |context| ... }`:
-      #   Stores the block as @model_block. Smith's lifecycle resolves it
-      #   at chat-construction time using the workflow's @context (Hash).
-      #   Return value must be a non-empty string; non-string / empty / nil
-      #   returns surface as Smith::AgentError at the resolution point
-      #   (see Smith::Agent::Lifecycle#build_model_chain).
-      #
-      # Mutually exclusive within a single declaration: passing both a
-      # string id and a block raises ArgumentError. Redeclaring with the
-      # other form clears the previous setting (static replaces block,
-      # block replaces static).
-      #
-      # Composes with `fallback_models`: resolved primary, then declared
-      # fallbacks, in order. Same path as static-form fallback.
-      def model(model_id = nil, **options, &block)
-        if block
-          raise ArgumentError, "model can take a string id OR a block, not both" if model_id || !options.empty?
-
-          @model_block = block
-          # Clear any stale `@chat_kwargs[:model]` from a prior static-form
-          # declaration. Smith's workflow lifecycle resolves block-form
-          # correctly via `build_model_chain` (which checks @model_block
-          # first), but RubyLLM's direct `chat()` and `with_rails_chat_record`
-          # paths splat `**chat_kwargs` to the constructor; without this
-          # delete, those paths would silently use the stale static id.
-          # This is the only place Smith mutates a RubyLLM-owned ivar; the
-          # mutation is well-scoped (only :model, only on block-form
-          # declaration) and matches RubyLLM's own pattern of dup'ing
-          # @chat_kwargs through its `inherited` hook.
-          @chat_kwargs ||= {}
-          @chat_kwargs.delete(:model)
-        else
-          @model_block = nil
-          super
-        end
-      end
-
-      attr_reader :model_block
-
       private
 
       def canonical_registration_name(name)
@@ -144,13 +109,6 @@ module Smith
 
       public
 
-      # Whether this agent class has any model configured (static or block).
-      # Smith::Workflow::Execution uses this as a precondition for invoking
-      # the agent; agents declared without a model are skipped.
-      def model_configured?
-        !chat_kwargs[:model].nil? || !@model_block.nil?
-      end
-
       # MERGING override: getter always returns user-declared ∪ reserved;
       # setter validates user names against reserved + stores only user
       # names. RubyLLM's bare `@input_names = names` (agent.rb:96) REPLACES;
@@ -174,120 +132,16 @@ module Smith
 
         @input_names = user_names.freeze
       end
-
-      # Closes the `inputs` contract at the chat() boundary AND runs the
-      # Smith::Models::Normalizer. Hook lives here (not in
-      # Lifecycle#attempt_model) so direct callers that construct a chat
-      # outside the workflow lifecycle are normalized too. Without this
-      # placement, model-specific request translation would only fire for
-      # workflow-driven calls.
-      #
-      # Single profile lookup: resolved once via Models.find_or_infer and
-      # passed through both inject_reserved_inputs and Normalizer.apply!.
-      def chat(**kwargs)
-        # Resolve model from explicit kwarg first, then fall back to the
-        # class-level chat_kwargs[:model] (set by `model "..."`). The
-        # explicit kwarg path fires from Lifecycle#attempt_model (passes
-        # the resolved primary or fallback model); the chat_kwargs path
-        # fires from direct callers like `Agent.chat` with no args.
-        model_id = kwargs[:model] || chat_kwargs[:model]
-        profile = resolve_profile(model_id)
-        kwargs = inject_reserved_inputs(kwargs, profile)
-        kwargs = nil_fill_declared_inputs(kwargs)
-
-        llm_chat = super
-        Smith::Models::Normalizer.apply!(llm_chat, profile: profile) if profile
-        llm_chat
-      end
-
-      # Normalizes the |ctx| DSL across RubyLLM's block-form attribute setters.
-      #
-      # RubyLLM evaluates these blocks via `runtime.instance_exec(&block)`,
-      # which sets `self` to the runtime_context but passes NO positional
-      # arguments, so `tools do |ctx| ctx.form_kind end` would silently
-      # bind `ctx = nil` and crash on the first method call. Smith's `model`
-      # block-form already uses `block.call(@context)` (an explicit Hash arg),
-      # giving agent authors a uniform `|ctx|` mental model. These overrides
-      # carry that convention through to RubyLLM's setters by wrapping any
-      # block so `|ctx|` receives the runtime_context AND `self` is still the
-      # runtime (preserving RubyLLM's bare-method-dispatch convention for
-      # zero-arity blocks).
-      #
-      # Behavior matrix:
-      #   tools do            ... end  (arity 0): preserved as-is; bare method
-      #                                            calls dispatch to runtime via
-      #                                            instance_exec (RubyLLM idiom)
-      #   tools do |ctx|      ... end  (arity 1): wrapped; ctx receives runtime
-      #                                            AND self is runtime, so both
-      #                                            `ctx.x` and bare `x` work
-      #
-      # Lambdas with arity 0 are preserved as-is (strict-arity safe). The
-      # wrapping path uses Proc semantics, so extra args don't raise.
-      def tools(*tools, &block)
-        return super unless block
-
-        super(&wrap_runtime_block(block))
-      end
-
-      def instructions(text = nil, **prompt_locals, &block)
-        return super unless block
-
-        super(text, **prompt_locals, &wrap_runtime_block(block))
-      end
-
-      def params(**params_kwargs, &block)
-        return super unless block
-
-        super(&wrap_runtime_block(block))
-      end
-
-      def headers(**headers_kwargs, &block)
-        return super unless block
-
-        super(&wrap_runtime_block(block))
-      end
-
-      def schema(value = nil, &block)
-        return super unless block
-
-        super(&wrap_runtime_block(block))
-      end
-
-      private
-
-      def resolve_profile(model_id)
-        return nil unless model_id
-        return nil unless defined?(Smith::Models)
-
-        Smith::Models.find_or_infer(model_id)
-      end
-
-      def inject_reserved_inputs(kwargs, profile)
-        return kwargs unless profile
-
-        reserved = {
-          model_id: profile.model_id,
-          provider: profile.provider,
-          endpoint_mode: profile.endpoint_mode
-        }
-        # User-provided values win on key collision.
-        reserved.merge(kwargs)
-      end
-
-      def nil_fill_declared_inputs(kwargs)
-        inputs.each_with_object(kwargs.dup) do |name, result|
-          result[name] = nil unless result.key?(name)
-        end
-      end
-
-      def wrap_runtime_block(user_block)
-        return user_block if user_block.arity.zero?
-
-        proc do |*|
-          runtime = self
-          runtime.instance_exec(runtime, &user_block)
-        end
-      end
     end
   end
 end
+
+require_relative "agent/dynamic_configuration"
+require_relative "agent/fallback_configuration"
+require_relative "agent/reserved_input_bridge"
+require_relative "agent/chat_construction"
+
+Smith::Agent.extend(Smith::Agent::DynamicConfiguration)
+Smith::Agent.extend(Smith::Agent::FallbackConfiguration)
+Smith::Agent.extend(Smith::Agent::ReservedInputBridge)
+Smith::Agent.extend(Smith::Agent::ChatConstruction)

data/lib/smith/context/observation_masking.rb

@@ -5,17 +5,41 @@ module Smith
     module ObservationMasking
       SYSTEM_ROLES = %i[system].push("system").freeze
 
-      def self.apply(messages, strategy:)
+      def self.apply(messages, strategy:, seed_message_count: 0)
         return messages unless strategy
 
         window = strategy[:window]
         return messages unless window
 
-        system_msgs, non_system = messages.partition do |message|
-          SYSTEM_ROLES.include?(message[:role] || message["role"])
+        prefix_count = strategy[:preserve_seed] == true ? seed_message_count : 0
+        prefix = messages.first(prefix_count)
+        dynamic_messages = messages.drop(prefix_count)
+
+        prefix + system_messages(dynamic_messages) + recent_observations(dynamic_messages, window)
+      end
+
+      def self.system_message?(message)
+        SYSTEM_ROLES.include?(message[:role] || message["role"])
+      end
+
+      def self.system_messages(messages)
+        messages.select { |message| system_message?(message) }
+      end
+
+      def self.recent_observations(messages, window)
+        raise ArgumentError, "negative array size" if window.negative?
+        return [] if window.zero?
+
+        selected = []
+        messages.reverse_each do |message|
+          next if system_message?(message)
+
+          selected << message
+          break if selected.length == window
         end
-        system_msgs + non_system.last(window)
+        selected.reverse
       end
+      private_class_method :system_message?, :system_messages, :recent_observations
     end
   end
 end

data/lib/smith/context/session.rb

@@ -5,10 +5,11 @@ module Smith
     class Session
       attr_reader :messages
 
-      def initialize(messages:, context_manager:, persisted_context:)
+      def initialize(messages:, context_manager:, persisted_context:, seed_message_count: 0)
         @messages = messages
         @context_manager = context_manager
         @persisted_context = persisted_context
+        @seed_message_count = seed_message_count
       end
 
       def inject_state!
@@ -26,7 +27,11 @@ module Smith
         return @messages unless @context_manager
 
         strategy = @context_manager.session_strategy
-        ObservationMasking.apply(@messages, strategy: strategy)
+        ObservationMasking.apply(
+          @messages,
+          strategy: strategy,
+          seed_message_count: @seed_message_count
+        )
       end
 
       def prepare!