smith-agents 0.8.0 → 0.11.0

data/lib/smith/agent/completion_usage_recording.rb

@@ -5,9 +5,18 @@ module Smith
     module CompletionUsageRecording
       private
 
-      def record_completion_usage(agent_class, completion, attempt_kind, model_reference)
+      # Returns [invocation_cost, fully_priced]. The cost is the sum of the
+      # recorded entries' costs (nil when nothing was priced): per-response
+      # pricing is what tiered catalogs bill, so the invocation cost comes
+      # from this sum, never from pricing the aggregate token totals (which
+      # would resolve the wrong tier for multi-response tool loops).
+      # fully_priced is true only when every provider response carried usage
+      # and every usage priced; a partial sum is still returned (it is what
+      # was verifiably billed) but callers must not present it as the
+      # complete invocation cost.
+      def record_completion_usage(agent_class, completion, attempt_kind, model_reference, attempt_id: nil)
         model_reference = coerce_model_reference(model_reference)
-        completion.provider_usages.each do |usage|
+        costs = completion.provider_usages.map do |usage|
           result = Workflow::AgentResult.new(
             content: nil,
             input_tokens: usage.input_tokens,
@@ -17,8 +26,17 @@ module Smith
             provider_used: model_reference.provider
           )
           compute_agent_cost(result)
-          record_usage(agent_class, result, attempt_kind, model_reference)
+          record_usage(agent_class, result, attempt_kind, model_reference, attempt_id:)
+          result.cost
         end
+        summarize_invocation_costs(costs, completion)
+      end
+
+      def summarize_invocation_costs(costs, completion)
+        priced = costs.compact
+        invocation_cost = priced.empty? ? nil : priced.sum
+        fully_priced = completion.usage_complete && !costs.empty? && priced.length == costs.length
+        [invocation_cost, fully_priced]
       end
     end
   end

data/lib/smith/agent/fallback_configuration.rb

@@ -3,15 +3,38 @@
 module Smith
   class Agent
     module FallbackConfiguration
-      def fallback_models(*models)
+      attr_reader :fallback_models_block
+
+      def fallback_models(*models, &block)
+        return configure_dynamic_fallback_models(models, block) if block
         return @fallback_models_list if models.empty?
 
-        entries = models.flatten.compact.map { qualified_fallback_reference(_1) }
-        @fallback_models_list = entries.uniq(&:key).freeze
+        @fallback_models_block = nil
+        @fallback_models_list = qualified_fallback_references(models)
+      end
+
+      # Evaluated per invocation with the workflow context. The entries pass
+      # the static form's validation and de-duplication: O(F) time and space
+      # for F returned entries.
+      def resolve_fallback_models(context)
+        return @fallback_models_list || [].freeze unless fallback_models_block
+
+        qualified_fallback_references([fallback_models_block.call(context)])
       end
 
       private
 
+      def configure_dynamic_fallback_models(models, block)
+        raise ArgumentError, "fallback_models can take model entries OR a block, not both" if models.any?
+
+        @fallback_models_list = nil
+        @fallback_models_block = block
+      end
+
+      def qualified_fallback_references(models)
+        models.flatten.compact.map { qualified_fallback_reference(_1) }.uniq(&:key).freeze
+      end
+
       def qualified_fallback_reference(model)
         reference = ModelReference.coerce(model)
         return reference if reference.provider

data/lib/smith/agent/invocation_preparation.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "json"
+
 module Smith
   class Agent
     module InvocationPreparation
@@ -82,9 +84,31 @@ module Smith
                      else
                        message
                      end
+        attributes = provider_safe_message(attributes) if attributes.is_a?(Hash)
         chat.add_message(attributes)
       end
 
+      # A structured agent output recorded as a session message (StepCompletion#append_accepted_output)
+      # carries a Hash/Array content. RubyLLM's Message#normalize_content treats a Hash content as
+      # { text:, ...attachments } and opens each value as a file, so replaying a prior structured
+      # output to the next agent in a workflow session raises Errno::ENOENT. Serialize non-string
+      # content to JSON so the provider sees the prior output as text; the session store keeps the raw
+      # value (last_output stays structured), only this provider-facing copy is serialized. Genuine
+      # multimodal attachments are supplied through the provider's own with: mechanism, never as a bare
+      # Hash message content in a workflow session.
+      def provider_safe_message(attributes)
+        content = attributes[:content]
+        return attributes if content.nil? || content.is_a?(String)
+
+        attributes.merge(content: json_message_content(content))
+      end
+
+      def json_message_content(content)
+        JSON.generate(content)
+      rescue StandardError
+        content.to_s
+      end
+
       def message_role(message)
         message_attribute(message, :role)&.to_sym
       end

data/lib/smith/agent/lifecycle.rb

@@ -20,8 +20,10 @@ module Smith
 
       def invoke_agent(agent_class, prepared_input, output_schema: agent_class.output_schema)
         check_deadline!
-        completion, model_used = complete_with_provider(agent_class, prepared_input, output_schema:)
-        snapshot_and_finalize(agent_class, completion, model_used)
+        attempt = complete_with_provider(agent_class, prepared_input, output_schema:)
+        snapshot_and_finalize(
+          agent_class, attempt.completion, attempt.model_reference, attempt_id: attempt.attempt_id
+        )
       end
     end
   end

data/lib/smith/agent/provider_attempt.rb

@@ -4,6 +4,7 @@ require "dry-struct"
 
 require_relative "../types"
 require_relative "model_reference"
+require_relative "provider_usage"
 
 module Smith
   class Agent
@@ -11,13 +12,25 @@ module Smith
       attribute :completion, Types::Any.optional
       attribute :model_reference, Types.Instance(ModelReference)
       attribute :error, Types.Instance(StandardError).optional
+      # One attempt = one chat completion (including any provider tool loop).
+      # `attempt_id` joins the attempt's usage entries to its single measured
+      # duration; `duration_ms` is nil when the attempt failed before the
+      # completion call started.
+      attribute :attempt_id, Types::String.optional.default(nil)
+      attribute :duration_ms, Types::Integer.optional.default(nil)
+      # The candidate's position in the model chain, the registered name of
+      # the agent that made the attempt, and the provider-reported usage its
+      # usage entries record (nil when the provider reported none).
+      attribute :attempt_index, Types::Integer.optional.default(nil)
+      attribute :agent_name, (Types::Symbol | Types::String).optional.default(nil)
+      attribute :usage, Types.Instance(ProviderUsage).optional.default(nil)
 
-      def self.success(completion:, model_reference:)
-        new(completion:, model_reference:, error: nil)
+      def self.success(completion:, model_reference:, **facts)
+        new(completion:, model_reference:, error: nil, **facts)
       end
 
-      def self.failure(error:, model_reference:)
-        new(completion: nil, model_reference:, error:)
+      def self.failure(error:, model_reference:, **facts)
+        new(completion: nil, model_reference:, error:, **facts)
       end
 
       def success?

data/lib/smith/agent/provider_call_timing.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require_relative "../diagnostic_text"
+
+module Smith
+  class Agent
+    # Monotonic timing and trace emission for one provider attempt: the
+    # attempt's single measured duration wraps the whole chat completion
+    # (including any provider-side tool loop). Per-network-round timing
+    # belongs to the host's RubyLLM notification subscriptions, not Smith.
+    module ProviderCallTiming
+      EXCEPTION_CAUSE = Exception.instance_method(:cause)
+      private_constant :EXCEPTION_CAUSE
+
+      class Timer
+        def self.start
+          new
+        end
+
+        def initialize
+          @started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          @stopped_at = nil
+        end
+
+        # Idempotent: the first stop wins, so a rescue-path stop after a
+        # success-path stop cannot stretch the measurement.
+        def stop
+          @stopped_at ||= Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          self
+        end
+
+        def elapsed_ms
+          ending = @stopped_at || Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          ((ending - @started_at) * 1000).round
+        end
+      end
+
+      private
+
+      # One `:provider_call` trace per attempt: success, provider failure, or
+      # aborted (a non-provider error that re-raises). Usage entries from the
+      # same attempt share its attempt_id; join there instead of summing
+      # durations across entries. duration_ms is present only when the timed
+      # provider call actually started: a failure before dispatch (model
+      # resolution, chat construction) emits its attempt without a duration.
+      # input_tokens and output_tokens total the attempt's usage entries, so
+      # a host can record the whole attempt when it ends.
+      def record_provider_call_trace(attempt, aborted: false)
+        Smith::Trace.record(
+          type: :provider_call,
+          data: {
+            model: attempt.model_reference.model_id,
+            provider: attempt.model_reference.provider,
+            duration_ms: attempt.duration_ms,
+            attempt_id: attempt.attempt_id,
+            attempt_index: attempt.attempt_index,
+            outcome: provider_call_outcome(attempt, aborted),
+            **provider_call_error_classes(attempt.error),
+            agent_name: attempt.agent_name,
+            **provider_call_usage(attempt.usage)
+          }.compact
+        )
+      end
+
+      # Token counts are metadata, never content, so the content policy
+      # leaves them in place.
+      def provider_call_usage(usage)
+        return {} unless usage
+
+        { input_tokens: usage.input_tokens, output_tokens: usage.output_tokens }
+      end
+
+      def provider_call_outcome(attempt, aborted)
+        return :aborted if aborted
+        return :success if attempt.success?
+
+        :failure
+      end
+
+      # Class names only, never a message: the same bounded identifier the
+      # failed :transition trace carries, for the error and its direct cause.
+      def provider_call_error_classes(error)
+        return {} unless error
+
+        cause = provider_call_error_cause(error)
+        {
+          error_class: DiagnosticText.error_class_name(error),
+          error_cause_class: cause && DiagnosticText.error_class_name(cause)
+        }
+      end
+
+      # A transport error wraps what actually happened (never connected, or
+      # lost the connection after sending); Faraday keeps it as
+      # wrapped_exception when the error was not raised inside a rescue.
+      def provider_call_error_cause(error)
+        cause = EXCEPTION_CAUSE.bind_call(error)
+        cause ||= error.wrapped_exception if error.respond_to?(:wrapped_exception)
+        cause if cause.is_a?(Exception)
+      rescue StandardError
+        nil
+      end
+
+      def completed_provider_attempt(completion, observed_reference, timer, facts)
+        attempt = ProviderAttempt.success(
+          completion:, model_reference: observed_reference, duration_ms: timer.elapsed_ms,
+          usage: ProviderUsage.sum(completion.provider_usages), **facts
+        )
+        record_provider_call_trace(attempt)
+        attempt
+      end
+
+      # Aborted (non-provider) attempts emit a :provider_call too, so the
+      # prefix-accounted usage entries stamped with this attempt_id always
+      # have their join target; the error then propagates unchanged. A
+      # provider failure's own reported usage is accounted beside the
+      # completed prefix, so its trace totals both.
+      def failed_provider_attempt(error, observed_reference, timer, facts, prefix_usages)
+        aborted = !provider_failure?(error)
+        usages = aborted ? prefix_usages : [*prefix_usages, ProviderUsage.from_message(error)].compact
+        attempt = ProviderAttempt.failure(
+          error:, model_reference: observed_reference, duration_ms: timer&.elapsed_ms,
+          usage: ProviderUsage.sum(usages), **facts
+        )
+        record_provider_call_trace(attempt, aborted:)
+        attempt
+      end
+    end
+  end
+end

data/lib/smith/agent/provider_completion.rb

@@ -3,6 +3,7 @@
 require_relative "provider_failure_handling"
 require_relative "invocation_preparation"
 require_relative "provider_attempt"
+require_relative "provider_call_timing"
 require_relative "provider_candidate_sequence"
 
 module Smith
@@ -10,6 +11,7 @@ module Smith
     module ProviderCompletion
       include ProviderFailureHandling
       include InvocationPreparation
+      include ProviderCallTiming
 
       private
 
@@ -17,13 +19,14 @@ module Smith
         candidates = ProviderCandidateSequence.new(build_model_chain(agent_class))
         candidates.each do |model_reference, index|
           check_deadline! if index.positive?
-          attempt = attempt_model(agent_class, prepared_input, model_reference, output_schema:)
-          return [attempt.completion, attempt.model_reference] if attempt.success?
+          attempt = attempt_model(agent_class, prepared_input, model_reference, output_schema:, attempt_index: index)
+          return attempt if attempt.success?
 
           candidates.suppress(account_failed_provider(attempt, model_reference))
           handle_provider_failure!(
             attempt.error, attempt.model_reference, agent_class,
-            fallback_available: candidates.fallback_available?
+            fallback_available: candidates.fallback_available?,
+            attempt_id: attempt.attempt_id
           )
         end
 
@@ -65,6 +68,8 @@ module Smith
       end
 
       def fallback_model_references(agent_class)
+        return agent_class.resolve_fallback_models(@context || {}) if agent_class.fallback_models_block
+
         Array(agent_class.fallback_models).map { |model| ModelReference.coerce(model) }
       end
 
@@ -79,20 +84,33 @@ module Smith
         raise Smith::AgentError, "invalid model block result for #{agent_class}: #{e.message}"
       end
 
-      def attempt_model(agent_class, prepared_input, model_reference, output_schema:)
+      # rubocop:disable Metrics/AbcSize -- one provider attempt is a single
+      # cohesive lifecycle (identity, prepared chat, observed model, timed
+      # completion, prefix accounting on failure); splitting it would scatter
+      # the rescue-path accounting away from what it accounts for.
+      def attempt_model(agent_class, prepared_input, model_reference, output_schema:, attempt_index:)
+        facts = { attempt_id: SecureRandom.uuid, attempt_index:, agent_name: agent_class.register_as }
         chat = prepared_attempt_chat(agent_class, prepared_input, model_reference, output_schema:)
         message_count = chat_message_count(chat)
         observed_reference = observed_model_reference(chat, fallback: model_reference)
-        completion = Completion.from_messages(response: chat.complete, messages: new_chat_messages(chat, message_count))
+        timer = ProviderCallTiming::Timer.start
+        response = chat.complete
+        timer.stop
+        completion = Completion.from_messages(response: response, messages: new_chat_messages(chat, message_count))
 
-        ProviderAttempt.success(completion:, model_reference: observed_reference)
+        completed_provider_attempt(completion, observed_reference, timer, facts)
       rescue StandardError => e
+        timer&.stop
         observed_reference ||= observed_model_reference(chat, fallback: model_reference)
-        account_completed_prefix(agent_class, observed_reference, new_chat_messages(chat, message_count))
+        prefix_usages = account_completed_prefix(
+          agent_class, observed_reference, new_chat_messages(chat, message_count), attempt_id: facts[:attempt_id]
+        )
+        attempt = failed_provider_attempt(e, observed_reference, timer, facts, prefix_usages)
         raise unless provider_failure?(e)
 
-        ProviderAttempt.failure(error: e, model_reference: observed_reference)
+        attempt
       end
+      # rubocop:enable Metrics/AbcSize
 
       def observed_model_reference(chat, fallback:)
         model = observable_model(chat)

data/lib/smith/agent/provider_failure_handling.rb

@@ -21,8 +21,8 @@ module Smith
 
       private
 
-      def handle_provider_failure!(error, model_reference, agent_class, fallback_available:)
-        account_failed_attempt(error, model_reference, agent_class)
+      def handle_provider_failure!(error, model_reference, agent_class, fallback_available:, attempt_id: nil)
+        account_failed_attempt(error, model_reference, agent_class, attempt_id:)
         if completed_tool_calls?
           raise Smith::ToolOutcomeUncertain.new(
             "provider failed after tool execution began; retry or fallback could replay an uncertain outcome"

data/lib/smith/agent/provider_usage.rb

@@ -20,6 +20,12 @@ module Smith
         new(input_tokens:, output_tokens:)
       end
 
+      def self.sum(usages)
+        return if usages.empty?
+
+        new(input_tokens: usages.sum(&:input_tokens), output_tokens: usages.sum(&:output_tokens))
+      end
+
       def total_tokens
         input_tokens + output_tokens
       end

data/lib/smith/agent/usage_entry_recording.rb

@@ -5,15 +5,22 @@ module Smith
     module UsageEntryRecording
       private
 
-      def record_usage(agent_class, agent_result, attempt_kind, model_reference)
+      def record_usage(agent_class, agent_result, attempt_kind, model_reference, attempt_id: nil)
         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)
+        entry = build_usage_entry(agent_class, agent_result, attempt_kind, model_reference, attempt_id:)
         accumulate_usage(agent_result, entry)
       end
 
-      def build_usage_entry(agent_class, agent_result, attempt_kind, model_reference)
+      # Attribution (transition, branch key, optimizer round) is read from the
+      # ambient context of the recording thread, which is the thread that ran
+      # the provider call: a fan-out branch records under its own overlay.
+      # transition and branch_key are recorded as Symbols even when a host
+      # seeded Strings through Attribution.with, because from_h symbolizes
+      # them on restore: recording the same way keeps a restored entry equal
+      # to the recorded one.
+      def build_usage_entry(agent_class, agent_result, attempt_kind, model_reference, attempt_id: nil)
         Workflow::UsageEntry.new(
           usage_id: SecureRandom.uuid,
           agent_name: agent_class.register_as,
@@ -23,10 +30,26 @@ module Smith
           output_tokens: agent_result.output_tokens,
           cost: agent_result.cost,
           attempt_kind: attempt_kind,
-          recorded_at: Time.now.utc.iso8601
+          recorded_at: Time.now.utc.iso8601(6),
+          attempt_id: attempt_id,
+          **ambient_attribution_fields
         )
       end
 
+      def ambient_attribution_fields
+        attribution = Smith::Attribution.ambient
+        {
+          transition: symbolized_attribution(attribution.transition),
+          branch_key: symbolized_attribution(attribution.branch_key),
+          round: attribution.round,
+          workflow: attribution.workflow
+        }
+      end
+
+      def symbolized_attribution(value)
+        value.is_a?(String) ? value.to_sym : value
+      end
+
       def accumulate_usage(agent_result, entry)
         @usage_mutex.synchronize do
           @total_tokens = (@total_tokens || 0) + agent_result.input_tokens + agent_result.output_tokens

data/lib/smith/agent/usage_traces.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Smith
+  class Agent
+    # Trace emission for a completed agent invocation's usage facts, kept
+    # apart from the accounting itself (UsageTracking) so recording rows and
+    # emitting observability stay separate concerns.
+    module UsageTraces
+      private
+
+      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
+
+      # One :cost trace per completed agent invocation. The cost is the sum
+      # of the invocation's per-response entry costs (what tiered catalogs
+      # actually bill), never the aggregate token totals priced as one call.
+      # Token counts remain the invocation aggregates. Billed failed and
+      # partial attempts appear only in usage entries, so summing :cost
+      # traces is not a spend total. Unpriced usage emits nothing, and the
+      # caller gates out partially metered or partially priced invocations
+      # so an incomplete figure is never presented as the invocation cost.
+      def emit_cost_trace(agent_result, invocation_cost)
+        return if invocation_cost.nil?
+
+        Smith::Trace.record(
+          type: :cost,
+          data: {
+            cost: invocation_cost,
+            model: agent_result.model_used,
+            provider: agent_result.provider_used,
+            input_tokens: agent_result.input_tokens,
+            output_tokens: agent_result.output_tokens
+          }.compact
+        )
+      end
+    end
+  end
+end

data/lib/smith/agent/usage_tracking.rb

@@ -2,31 +2,36 @@
 
 require_relative "completion_usage_recording"
 require_relative "usage_entry_recording"
+require_relative "usage_traces"
 
 module Smith
   class Agent
     module UsageTracking
       include CompletionUsageRecording
       include UsageEntryRecording
+      include UsageTraces
 
       private
 
-      def account_failed_attempt(error, model_reference, agent_class)
+      def account_failed_attempt(error, model_reference, agent_class, attempt_id: nil)
         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)
+        record_failed_usage(agent_class, model_reference, input, output, attempt_id:)
       end
 
-      def account_completed_prefix(agent_class, model_reference, messages)
+      # Returns the provider usages it recorded, so the attempt's trace can
+      # carry the same totals its usage entries hold.
+      def account_completed_prefix(agent_class, model_reference, messages, attempt_id: nil)
         completion = Completion.from_messages(response: nil, messages: messages)
-        record_completion_usage(agent_class, completion, :partial_attempt, model_reference)
+        record_completion_usage(agent_class, completion, :partial_attempt, model_reference, attempt_id:)
+        completion.provider_usages
       end
 
-      def record_failed_usage(agent_class, model_reference, input_tokens, output_tokens, attempt_kind)
+      def record_failed_usage(agent_class, model_reference, input_tokens, output_tokens, attempt_id: nil)
         model_reference = coerce_model_reference(model_reference)
         cost = Smith::Pricing.compute_cost(
           model: model_reference.model_id,
@@ -44,10 +49,10 @@ module Smith
         )
         Thread.current[:smith_failed_agent_results] ||= []
         Thread.current[:smith_failed_agent_results] << agent_result
-        record_usage(agent_class, agent_result, attempt_kind, model_reference)
+        record_usage(agent_class, agent_result, :failed_attempt, model_reference, attempt_id:)
       end
 
-      def snapshot_and_finalize(agent_class, completion, model_reference)
+      def snapshot_and_finalize(agent_class, completion, model_reference, attempt_id: nil)
         model_reference = coerce_model_reference(model_reference)
         agent_result = Workflow::AgentResult.new(
           content: completion.content,
@@ -59,8 +64,7 @@ module Smith
         )
         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)
+        account_completion!(agent_class, completion, model_reference, agent_result, attempt_id)
 
         agent_result.content = run_after_completion(agent_class, agent_result.content, @context)
         raise_blank_output!(agent_class, agent_result)
@@ -83,18 +87,20 @@ module Smith
         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
+      # Records one usage entry per provider response and settles the
+      # invocation's cost from the recorded per-response sum: that sum is
+      # what tiered catalogs bill, so it becomes agent_result.cost (which
+      # budget settlement and result surfaces read) and the recorded entries,
+      # the budget ledger, and the :cost trace all agree. The trace emits
+      # only for fully metered, fully priced invocations, so a partial
+      # figure is never presented as the invocation cost; the partial sum
+      # still settles the budget because it is what was verifiably billed.
+      def account_completion!(agent_class, completion, model_reference, agent_result, attempt_id)
+        invocation_cost, fully_priced = record_completion_usage(
+          agent_class, completion, :completed_attempt, model_reference, attempt_id:
         )
+        agent_result.cost = invocation_cost
+        emit_cost_trace(agent_result, invocation_cost) if fully_priced
       end
 
       def compute_agent_cost(agent_result)

data/lib/smith/agent.rb

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