smith-agents 0.7.0 → 0.8.0

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

@@ -6,8 +6,14 @@ 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
@@ -23,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
@@ -44,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?
 
@@ -62,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?
 
@@ -87,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)
@@ -146,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;
@@ -176,140 +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 = install_tool_execution_context(super)
-        Smith::Models::Normalizer.apply!(llm_chat, profile: profile) if profile
-        llm_chat
-      end
-
-      def create(**kwargs)
-        install_tool_execution_context(super)
-      end
-
-      def create!(**kwargs)
-        install_tool_execution_context(super)
-      end
-
-      def find(id, **kwargs)
-        install_tool_execution_context(super)
-      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 install_tool_execution_context(chat_object)
-        return unless chat_object
-
-        llm_chat = chat_object.respond_to?(:to_llm) ? chat_object.to_llm : chat_object
-        Tool::ChatExecutionContext.install(llm_chat)
-        chat_object
-      end
-
-      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!

data/lib/smith/diagnostic_text.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+module Smith
+  class DiagnosticText
+    MAX_BYTES = 64 * 1024
+    TRUNCATION_MARKER = "...[truncated]"
+    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
+
+    extend Dry::Initializer
+
+    param :value
+    option :max_bytes, default: proc { MAX_BYTES }
+
+    def self.capture(value, max_bytes: MAX_BYTES) = new(value, max_bytes:).call
+
+    def call
+      validate_limit!
+      text = utf8_prefix
+      return text.freeze if text.bytesize <= max_bytes
+
+      truncate(text)
+    end
+
+    private
+
+    def validate_limit!
+      return if max_bytes.is_a?(Integer) && max_bytes >= TRUNCATION_MARKER.bytesize
+
+      raise ArgumentError, "diagnostic text limit is too small"
+    end
+
+    def utf8_prefix
+      source = string_value
+      limit = (max_bytes * 4) + TRUNCATION_MARKER.bytesize
+      prefix = STRING_BYTESLICE.bind_call(source, 0, limit)
+      prefix.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: "\uFFFD")
+    rescue EncodingError
+      "unavailable diagnostic text"
+    end
+
+    def string_value
+      return value if MODULE_MATCH.bind_call(String, value)
+
+      String(value)
+    rescue StandardError
+      "unavailable diagnostic text"
+    end
+
+    def truncate(text)
+      budget = max_bytes - TRUNCATION_MARKER.bytesize
+      prefix = +""
+
+      text.each_char do |character|
+        break if prefix.bytesize + character.bytesize > budget
+
+        prefix << character
+      end
+
+      (prefix << TRUNCATION_MARKER).freeze
+    end
+  end
+end

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

@@ -43,11 +43,24 @@ module Smith
 
         def self.check_pricing(report)
           configured = ::Smith.config.pricing.is_a?(Hash) && !::Smith.config.pricing.empty?
+          unless configured
+            report.add(
+              name: "config.pricing",
+              status: :warn,
+              message: "No pricing configured",
+              detail: "RunResult.total_cost will be 0.0"
+            )
+            return
+          end
+
+          ::Smith::Pricing.validate_catalog!
+          report.add(name: "config.pricing", status: :pass, message: "Pricing configured")
+        rescue ::Smith::PricingConfigurationError => e
           report.add(
             name: "config.pricing",
-            status: configured ? :pass : :warn,
-            message: configured ? "Pricing configured" : "No pricing configured",
-            detail: configured ? nil : "RunResult.total_cost will be 0.0"
+            status: :fail,
+            message: "Pricing catalog invalid",
+            detail: e.message
           )
         end
       end