smith-agents 0.7.0 → 0.10.0

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/attribution.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Smith
+  # Ambient execution attribution: an immutable, thread-local description of
+  # where execution currently is (run identity, transition, fan-out branch,
+  # optimizer round). Workflow execution scopes install it; observability
+  # consumers (traces, events, usage recording) read it, so emitted facts
+  # carry correlation without any consumer knowing about the workflow.
+  #
+  # Attribution values are opaque identifiers, never content: the trace
+  # content policy does not treat them as payload. `execution_key` defaults
+  # to the workflow's persistence key during persisted runs; hosts running
+  # non-persisted workflows can seed an outer scope explicitly:
+  #
+  #   Smith::Attribution.with(execution_key: "host-run-42") { workflow.run! }
+  #
+  # Installation inside workflow internals is a plain assignment
+  # (Attribution.install) because restoration there is owned by the
+  # surrounding ThreadContextSnapshot, which tracks the attribution thread
+  # key alongside the other per-step thread state.
+  module Attribution
+    THREAD_KEY = :smith_attribution
+
+    Context = Data.define(:execution_key, :transition, :from, :to, :branch_key, :round, :workflow) do
+      # Overlay semantics: nil overrides are ignored so an inner scope can
+      # only add or replace attribution, never blank an outer value.
+      def merge(**overrides)
+        filtered = overrides.compact
+        return self if filtered.empty?
+
+        override(**filtered)
+      end
+
+      # Replacement semantics: sets the given fields verbatim, nil included,
+      # so a scope that owns a field can reset it (a step whose transition
+      # declares no `from` must not inherit an enclosing step's `from`).
+      # Built on to_h, not Data#with, which requires Ruby 3.3 while the gem
+      # supports 3.2.
+      def override(**fields)
+        self.class.new(**to_h, **fields)
+      end
+
+      def to_fields
+        {
+          execution_key: execution_key,
+          transition: transition,
+          from: from,
+          to: to,
+          branch_key: branch_key,
+          round: round,
+          workflow: workflow
+        }.compact
+      end
+    end
+
+    EMPTY = Context.new(
+      execution_key: nil, transition: nil, from: nil, to: nil, branch_key: nil, round: nil, workflow: nil
+    )
+
+    class << self
+      def current
+        Thread.current[THREAD_KEY]
+      end
+
+      def ambient
+        current || EMPTY
+      end
+
+      # The compacted attribution fields, for merging into emitted payloads.
+      def current_fields
+        context = current
+        context ? context.to_fields : {}
+      end
+
+      # Plain installation with no restoration: callers own restoration,
+      # either through ThreadContextSnapshot (workflow internals) or an
+      # enclosing #with / #carrying block.
+      def install(context)
+        Thread.current[THREAD_KEY] = context
+      end
+
+      # Host-facing scope: overlays the ambient attribution for the block.
+      def with(**overrides, &block)
+        raise ArgumentError, "block required" unless block
+
+        swap(ambient.merge(**overrides), &block)
+      end
+
+      # Cross-thread propagation: installs a context captured on another
+      # thread (or nil, clearing any stale value on a pooled thread) for the
+      # duration of the block.
+      def carrying(context, &block)
+        raise ArgumentError, "block required" unless block
+
+        swap(context, &block)
+      end
+
+      private
+
+      # Matches the gem's scoped thread-state idiom: install and restore run
+      # interrupt-deferred, the block itself runs interruptible.
+      def swap(context, &block)
+        previous = Thread.current[THREAD_KEY]
+        Thread.handle_interrupt(Object => :never) do
+          Thread.current[THREAD_KEY] = context
+          begin
+            Thread.handle_interrupt(Object => :immediate, &block)
+          ensure
+            Thread.current[THREAD_KEY] = previous
+          end
+        end
+      end
+    end
+  end
+end

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

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

@@ -15,7 +15,12 @@ module Smith
         module_function
 
         def run(report)
-          uncovered = uncovered_models
+          uncovered, ambiguous = classified_model_references
+          report_ambiguous_models(report, ambiguous)
+          report_model_coverage(report, uncovered)
+        end
+
+        def report_model_coverage(report, uncovered)
           if uncovered.empty?
             report.add(
               name: "models.coverage",
@@ -36,23 +41,65 @@ module Smith
           end
         end
 
+        # An unqualified agent model id registered under more than one
+        # provider cannot resolve to a single profile: chat construction
+        # fails closed with AmbiguousProfileError. Doctor must report that
+        # configuration instead of crashing on it.
+        def report_ambiguous_models(report, ambiguous)
+          return if ambiguous.empty?
+
+          descriptions = ambiguous.map { |reference| ambiguous_reference_description(reference) }
+          report.add(
+            name: "models.ambiguity",
+            status: :fail,
+            message: "#{ambiguous.size} agent model id(s) match profiles from multiple registered providers",
+            detail: "Ambiguous: #{descriptions.join("; ")}. Chat construction fails closed for " \
+                    "these agents until each declares an explicit provider (for example " \
+                    "model \"gpt-5\", provider: :openai) selecting exactly one registered profile."
+          )
+        end
+
+        def ambiguous_reference_description(reference)
+          "#{reference.model_id} (providers: #{registered_providers_for(reference).join(", ")})"
+        end
+
+        def registered_providers_for(reference)
+          Smith::Models.all
+                       .select { |profile| profile.model_id == reference.model_id }
+                       .map { |profile| profile.provider.to_s }
+        end
+
         # Walk Smith::Agent::Registry. For each agent, extract every static
         # model id Smith can know at boot: the primary `model "..."` value and
         # any static fallback models. Block-form primary models are skipped
         # because they resolve per-attempt, but their static fallbacks still
         # need coverage checks.
         # Check whether find_or_infer returns a custom (non-default)
-        # Profile — meaning either an explicit override or an inference
-        # rule matched.
-        def uncovered_models
-          return [] unless defined?(Smith::Agent::Registry)
+        # Profile, meaning either an explicit override or an inference
+        # rule matched. Returns [uncovered, ambiguous] reference lists.
+        def classified_model_references
+          return [[], []] unless defined?(Smith::Agent::Registry)
 
-          static_model_ids.uniq.reject { |model_id| covered_model?(model_id) }
+          uncovered = []
+          ambiguous = []
+          static_model_references.uniq(&:key).each do |reference|
+            case model_coverage(reference)
+            when :uncovered then uncovered << reference
+            when :ambiguous then ambiguous << reference
+            end
+          end
+          [uncovered, ambiguous]
+        end
+
+        def model_coverage(reference)
+          covered_model?(reference) ? :covered : :uncovered
+        rescue Smith::Models::AmbiguousProfileError
+          :ambiguous
         end
 
-        def static_model_ids
-          Smith::Agent::Registry.each.with_object([]) do |(_key, agent), ids|
-            ids.concat(static_model_ids_for(agent)) if inspectable_agent?(agent)
+        def static_model_references
+          Smith::Agent::Registry.each.with_object([]) do |(_key, agent), references|
+            references.concat(static_model_references_for(agent)) if inspectable_agent?(agent)
           end
         end
 
@@ -60,16 +107,27 @@ module Smith
           agent.is_a?(Class) && agent.respond_to?(:chat_kwargs)
         end
 
-        def static_model_ids_for(agent)
-          [
-            agent.chat_kwargs[:model],
-            *(agent.respond_to?(:fallback_models) ? agent.fallback_models : nil)
-          ].compact
+        def static_model_references_for(agent)
+          primary = agent.chat_kwargs[:model]
+          references = Array(agent.respond_to?(:fallback_models) ? agent.fallback_models : nil).dup
+          if primary
+            references.unshift(
+              Smith::Agent::ModelReference.coerce(primary, provider: agent.chat_kwargs[:provider])
+            )
+          end
+          references
+        end
+
+        def covered_model?(reference)
+          Smith::Models.find(reference.model_id, provider: reference.provider) ||
+            inferred_profile_matches?(reference)
         end
 
-        def covered_model?(model_id)
-          Smith::Models.find(model_id) ||
-            (defined?(Smith::Models::Inference) && Smith::Models::Inference.profile_for(model_id))
+        def inferred_profile_matches?(reference)
+          return false unless defined?(Smith::Models::Inference)
+
+          profile = Smith::Models::Inference.profile_for(reference.model_id)
+          profile && (reference.provider.nil? || profile.provider.to_sym == reference.provider)
         end
       end
     end