smith-agents 0.11.0 → 0.12.0

data/lib/smith/launchers/inline.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Smith
+  module Launchers
+    # Runs each child to its end, one after another, in the parent's
+    # process, and returns their results, so the parent's step completes at
+    # once. Children run under the parent's deadline but with no tool
+    # evidence or attribution of the parent's. A child left waiting, or one
+    # that raised, is reported failed (with the error's class). For tests
+    # and scripts: a long map holds the parent's step for as long as it runs.
+    class Inline
+      def inline? = true
+
+      def launch(children:, parent_key:, await_token:) # rubocop:disable Lint/UnusedMethodArgument
+        deadline = Tool.current_deadline
+        children.map { |child| run_child(child, deadline) }
+      end
+
+      private
+
+      def run_child(child, deadline)
+        workflow = child.build
+        workflow.instance_variable_set(:@inherited_deadline, deadline) if deadline
+        run = apart { workflow.run! }
+        return failed(child, workflow.state, "waiting") if workflow.waiting?
+
+        ChildRun.result(ref: child.ref, run_result: run)
+      rescue StandardError => e
+        failed(child, nil, DiagnosticText.error_class_name(e))
+      end
+
+      def failed(child, state, error)
+        { ref: child.ref, status: "failed", state: state&.to_s, output: nil,
+          error: DiagnosticText.capture(error.to_s, max_bytes: 256) }
+      end
+
+      def apart(&)
+        tracker = Tool.current_tool_execution_tracker
+        Tool.current_tool_execution_tracker = nil
+        Attribution.carrying(nil, &)
+      ensure
+        Tool.current_tool_execution_tracker = tracker
+      end
+    end
+  end
+end

data/lib/smith/message.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require_relative "content"
+require_relative "errors"
+require_relative "workflow/message_roles"
+
+module Smith
+  # Messages for a step's `input:` and the `seed_messages` builder. Content
+  # is a String, or an Array of 1 to MAX_PARTS Smith::Content parts:
+  #
+  #   Smith::Message.user("Summarize the contract.")
+  #   Smith::Message.system([Smith::Content.text(style_guide, cache: true)])
+  #
+  # A message with parts carries `"parts" => true` beside its role and
+  # content. No agent output and no message a host admits
+  # (`append_session_messages!`) can carry it, so a structured output that
+  # looks like parts stays data. Only a user message takes documents and
+  # images; system and assistant messages, and every seed message (built
+  # before the run can store an artifact), take text parts.
+  module Message
+    MAX_PARTS = 100
+
+    module_function
+
+    def user(content) = build("user", content)
+
+    def assistant(content) = build("assistant", content)
+
+    def system(content) = build("system", content)
+
+    def build(role, content)
+      return { "role" => role, "content" => content.dup.freeze }.freeze if content.is_a?(String)
+
+      check!({ "role" => role, "content" => content, "parts" => true })
+    end
+
+    # Whether a message Hash (String or Symbol keys) is one with parts.
+    def parts?(message)
+      message.is_a?(Hash) && (message["parts"] == true || message[:parts] == true)
+    end
+
+    # A seed message with parts: text parts only.
+    def check_seed!(message)
+      checked = check!(message)
+      return checked if checked["content"].all? { |part| part["type"] == "text" }
+
+      raise WorkflowError, "a seed message takes text parts only; send documents and images through a step's input:"
+    end
+
+    # A message with parts, checked and returned frozen with String keys.
+    def check!(message)
+      fields = message.is_a?(Hash) ? message.transform_keys(&:to_s) : {}
+      role = Workflow::MessageRoles.role(fields, %w[system user assistant])
+      unless role && shaped?(fields)
+        raise WorkflowError, "a message with content parts is { role:, content: [parts], parts: true } with a " \
+                             "system, user or assistant role and 1 to #{MAX_PARTS} parts"
+      end
+
+      { "role" => role, "content" => checked_parts(role, fields["content"]), "parts" => true }.freeze
+    end
+
+    def shaped?(fields)
+      content = fields["content"]
+      fields.keys.sort == %w[content parts role] && fields["parts"] == true && content.is_a?(Array) &&
+        content.length.between?(1, MAX_PARTS)
+    end
+
+    def checked_parts(role, content)
+      parts = content.map { |part| Content.check!(part) }.freeze
+      return parts if role == "user" || parts.all? { |part| part["type"] == "text" }
+
+      raise WorkflowError, "a #{role} message takes text parts only"
+    end
+    private_class_method :build, :shaped?, :checked_parts
+  end
+end

data/lib/smith/models/tool_routing.rb

@@ -15,41 +15,64 @@ module Smith
       option :profile
       option :decision_recorder
 
-      def call
-        return unless chat.respond_to?(:tools)
+      # Whether #call sends a chat of `profile` with these tools (tools or tool
+      # classes; `choice` the chat's forced tool choice) to the Responses
+      # API: thinking that needs it, or a tool only it takes, or more tools
+      # it takes. Runtime readiness asks this without a chat.
+      def self.responses?(profile:, tools:, thinking:, choice: nil)
+        return false unless profile.provider == :openai && Smith.config.openai_api_mode == :auto && tools.any?
+        return true if thinking && thinking_route?(profile)
+
+        forced = forced_endpoint(tools, choice, profile)
+        return forced == :responses if forced
+
+        compatible_count(tools, :responses, profile) > compatible_count(tools, :chat_completions, profile)
+      end
 
-        tools = chat.tools.values
-        return if tools.empty?
+      def self.thinking_route?(profile)
+        !profile.tools_with_thinking_native && profile.tools_with_thinking_route == :responses
+      end
 
-        route_tools_with_thinking if thinking_active?
-        route_tools_for_compatibility(tools)
-        drop_incompatible_tools(tools)
+      # The one endpoint that can carry a specifically forced tool.
+      def self.forced_endpoint(tools, choice, profile)
+        tool = forced_tool(tools, choice&.to_sym)
+        return unless tool
+
+        endpoints = TOOL_ENDPOINTS.select { |endpoint| compatible?(tool, endpoint, profile) }
+        endpoints.first if endpoints.one?
       end
 
-      private
+      def self.forced_tool(tools, choice)
+        return if choice.nil? || %i[auto none required].include?(choice)
+
+        tools.find { |candidate| !candidate.is_a?(Class) && candidate.name.to_sym == choice }
+      end
 
-      def route_tools_with_thinking
-        return unless profile.provider == :openai
-        return if profile.tools_with_thinking_native
-        return unless profile.tools_with_thinking_route == :responses
-        return unless Smith.config.openai_api_mode == :auto
+      def self.compatible_count(tools, endpoint, profile) = tools.count { compatible?(_1, endpoint, profile) }
+
+      def self.compatible?(tool, endpoint, profile)
+        return true unless defined?(Smith::Tool::Compatibility)
 
-        route_via_responses
+        tool_class = tool.is_a?(Class) ? tool : tool.class
+        spec = tool_class.respond_to?(:compatible_with_spec) ? tool_class.compatible_with_spec : nil
+        Smith::Tool::Compatibility.allows?(spec, profile, effective_endpoint: endpoint)
       end
+      private_class_method :thinking_route?, :forced_endpoint, :forced_tool, :compatible_count, :compatible?
 
-      def route_tools_for_compatibility(tools)
-        return unless profile.provider == :openai
-        return unless Smith.config.openai_api_mode == :auto
-        return if responses_routed?
+      def call
+        return unless chat.respond_to?(:tools)
 
-        forced_endpoint = forced_tool_endpoint(tools)
-        return if forced_endpoint == :chat_completions
-        return unless forced_endpoint == :responses ||
-                      compatible_tool_count(tools, :responses) > compatible_tool_count(tools, :chat_completions)
+        tools = chat.tools.values
+        return if tools.empty?
 
-        route_via_responses
+        if self.class.responses?(profile:, tools:, thinking: thinking_active?, choice: chat.tool_prefs[:choice])
+          route_via_responses
+        end
+        drop_incompatible_tools(tools)
       end
 
+      private
+
       def route_via_responses
         return if responses_routed?
 
@@ -78,17 +101,6 @@ module Smith
         detail
       end
 
-      def forced_tool_endpoint(tools)
-        choice = chat.tool_prefs[:choice]&.to_sym
-        return if %i[auto none required].include?(choice)
-
-        tool = tools.find { |candidate| candidate.name.to_sym == choice }
-        return unless tool
-
-        compatible_endpoints = TOOL_ENDPOINTS.select { |endpoint| tool_compatible_with?(tool, endpoint) }
-        compatible_endpoints.first if compatible_endpoints.one?
-      end
-
       def reset_invalid_tool_choice(remaining)
         choice = chat.tool_prefs[:choice]
         return unless choice
@@ -100,16 +112,7 @@ module Smith
         choice
       end
 
-      def compatible_tool_count(tools, endpoint)
-        tools.count { |tool| tool_compatible_with?(tool, endpoint) }
-      end
-
-      def tool_compatible_with?(tool, endpoint)
-        return true unless defined?(Smith::Tool::Compatibility)
-
-        spec = tool.class.respond_to?(:compatible_with_spec) ? tool.class.compatible_with_spec : nil
-        Smith::Tool::Compatibility.allows?(spec, profile, effective_endpoint: endpoint)
-      end
+      def tool_compatible_with?(tool, endpoint) = self.class.__send__(:compatible?, tool, endpoint, profile)
 
       def thinking_active?
         thinking = chat.instance_variable_get(:@thinking)

data/lib/smith/output_failure.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "diagnostic_text"
+
+module Smith
+  # An agent's response that cannot be its step's output: cut off at its
+  # output limit (OutputTruncated), refused (OutputRefused), or not the
+  # structured output the agent declares (OutputInvalid). The response was
+  # billed all the same. Not an AgentError and not retryable: the agent's
+  # own retry, fallback and repairs have run, and running the same request
+  # again would repeat the cost. Its failure family is `output_failure`;
+  # details are bounded and persist with a failed step, so a restored run
+  # raises the same error.
+  class OutputFailure < Error
+    DETAIL_NAMES = %i[agent_name model_used stop_reason problems].freeze
+    DETAIL_KEYS = DETAIL_NAMES.to_h { |name| [name.to_s.freeze, name] }.freeze
+    MAX_TEXT_BYTES = 256
+    MAX_PROBLEMS = 20
+    private_constant :DETAIL_NAMES, :DETAIL_KEYS
+
+    attr_reader :agent_name, :model_used, :stop_reason, :problems
+
+    # `message` is the persisted one when the error is restored.
+    def initialize(agent_name:, model_used:, stop_reason: nil, problems: [], message: nil)
+      @agent_name = agent_name
+      @model_used = model_used
+      @stop_reason = stop_reason
+      @problems = Array(problems).first(MAX_PROBLEMS).map { |problem| self.class.bounded(problem.to_s) }.freeze
+      super(message || describe)
+    end
+
+    def details
+      texts = %i[agent_name model_used stop_reason].to_h { |name| [name, text_detail(public_send(name))] }
+      texts.merge(problems:).freeze
+    end
+
+    class << self
+      # Each output failure class's name and its restore from persisted
+      # details, for the failure record validator and reconstructor.
+      def restorers
+        [OutputFailure, OutputTruncated, OutputRefused, OutputInvalid].to_h do |error_class|
+          [error_class.name, ->(details, message = nil) { error_class.from_details(details, message:) }]
+        end.freeze
+      end
+
+      def from_details(details, message: nil)
+        values = normalize_details(details)
+        new(agent_name: values.fetch(:agent_name)&.to_sym, model_used: values.fetch(:model_used),
+            stop_reason: values.fetch(:stop_reason), problems: values.fetch(:problems), message:)
+      end
+
+      def bounded(text) = DiagnosticText.capture(text, max_bytes: MAX_TEXT_BYTES)
+
+      private
+
+      def normalize_details(details)
+        raise ArgumentError, "output failure details must be a Hash" unless details.is_a?(Hash)
+
+        values = {}
+        Hash.instance_method(:each_pair).bind_call(details) do |key, value|
+          name = detail_name(key, values)
+          values[name] = name == :problems ? problem_list(value) : bounded_text(name, value)
+        end
+        raise ArgumentError, "output failure details are incomplete" unless values.length == DETAIL_NAMES.length
+
+        values
+      end
+
+      def detail_name(key, seen)
+        name = key.is_a?(Symbol) ? key : DETAIL_KEYS[key]
+        raise ArgumentError, "output failure details contain an unknown attribute" unless DETAIL_NAMES.include?(name)
+        raise ArgumentError, "output failure details contain a duplicate attribute" if seen.key?(name)
+
+        name
+      end
+
+      def bounded_text(name, value)
+        return value if value.nil?
+        return value if value.is_a?(String) && value.valid_encoding? && value.bytesize <= MAX_TEXT_BYTES
+
+        raise ArgumentError, "output failure detail #{name} must be bounded text"
+      end
+
+      def problem_list(value)
+        unless value.is_a?(Array) && value.length <= MAX_PROBLEMS
+          raise ArgumentError, "output failure problems must be a list of at most #{MAX_PROBLEMS}"
+        end
+
+        value.map { |problem| bounded_text(:problems, problem) }
+      end
+    end
+
+    private
+
+    def text_detail(value) = value && self.class.bounded(value.to_s)
+
+    def outcome = "could not be used"
+
+    def describe
+      [
+        "agent#{" :#{agent_name}" if agent_name} response#{" from model #{model_used}" if model_used} #{outcome}",
+        (" (stop reason #{stop_reason})" if stop_reason),
+        (": #{problems.first(3).join("; ")}" unless problems.empty?)
+      ].join
+    end
+  end
+
+  # The response stopped at its output limit.
+  class OutputTruncated < OutputFailure
+    private
+
+    def outcome = "was cut off at its output limit"
+  end
+
+  # The provider or model declined to answer.
+  class OutputRefused < OutputFailure
+    private
+
+    def outcome = "was refused"
+  end
+
+  # The output is not a JSON object, or breaks the agent's output contract
+  # or a schema constraint Smith checks itself.
+  class OutputInvalid < OutputFailure
+    private
+
+    def outcome = "is invalid"
+  end
+end

data/lib/smith/persistence_adapters/active_record_exact_store.rb

@@ -3,12 +3,16 @@
 module Smith
   module PersistenceAdapters
     module ActiveRecordExactStore
+      # Child runs are stored under 64-character keys (digests).
+      KEY_WIDTH = 64
+
       attr_reader :persistence_identity
 
       def replace_exact(key, payload, expected_payload:, ttl: nil)
         ensure_versioned_write!(ttl)
         model = model_class
         ensure_exact_schema!(model)
+        ensure_plain_payload!(model)
         ActiveRecordExactWrite.new(
           model: model,
           key_column: @key_column,
@@ -22,6 +26,28 @@ module Smith
         raise Smith::PersistenceIOError.new(operation: :replace_exact, cause: e)
       end
 
+      # Raises ArgumentError unless the model's table holds runs as their
+      # writes need: the locking column, a text payload, and a string key the
+      # database keeps unique, wide enough for child runs' keys (smith:doctor
+      # reports it). Returns self.
+      def check_schema!
+        model = model_class
+        ensure_version_column!
+        ensure_locking_configuration!
+        ensure_exact_schema!(model)
+        ensure_key_column!(model)
+        self
+      end
+
+      # Whether Rails encrypts the payload (`encrypts`): runs store and read
+      # it, but replace_exact, which compares payloads in the database,
+      # cannot.
+      def encrypted_payload?
+        model = model_class
+        attributes = model.encrypted_attributes if model.respond_to?(:encrypted_attributes)
+        Array(attributes).map(&:to_s).include?(@payload_column.to_s)
+      end
+
       private
 
       def ensure_versioned_write!(ttl)
@@ -44,6 +70,23 @@ module Smith
               "#{model.table_name}.#{@payload_column}"
       end
 
+      def ensure_key_column!(model)
+        column = model.columns_hash.fetch(@key_column.to_s)
+        return if %i[string text].include?(column.type) && (column.limit.nil? || column.limit >= KEY_WIDTH)
+
+        raise ArgumentError,
+              "ActiveRecordStore requires #{model.table_name}.#{@key_column} to be a string or text column of at " \
+              "least #{KEY_WIDTH} characters: child runs are stored under #{KEY_WIDTH}-character keys"
+      end
+
+      def ensure_plain_payload!(model)
+        return unless encrypted_payload?
+
+        raise ArgumentError,
+              "ActiveRecordStore#replace_exact compares payloads in the database, so it cannot use " \
+              "#{model.name}'s encrypted #{@payload_column}"
+      end
+
       def ensure_exact_key_uniqueness!(model)
         connection = model.connection
         schema_cache = connection.schema_cache

data/lib/smith/pricing/catalog_validation.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Smith
+  module Pricing
+    # Admission-time catalog validation, the raising surface for the rules
+    # `compute_cost` applies without raising. See Pricing.validate_catalog!.
+    module CatalogValidation
+      OPTIONAL_RATE_KEYS = %i[cache_read_cost_per_token cache_write_cost_per_token].freeze
+
+      module_function
+
+      def validate!(catalog)
+        return catalog if catalog.nil?
+        raise Smith::PricingConfigurationError, "pricing catalog must be a Hash" unless catalog.is_a?(Hash)
+
+        catalog.each_with_object({}) do |(key, entry), seen|
+          provider, model = validated_key!(key)
+          validate_entry!(key, entry)
+          reject_collision!(seen, key, provider, model)
+        end
+        catalog
+      end
+
+      def validated_key!(key)
+        provider, model = Pricing.__send__(:canonical_key, key)
+        raise Smith::PricingConfigurationError, "unrecognized pricing catalog key #{key.inspect}" unless model
+        return [provider, model] if provider
+
+        raise Smith::PricingConfigurationError, "pricing for #{model} must use a provider-qualified catalog key"
+      end
+
+      def validate_entry!(key, entry)
+        unless entry.is_a?(Hash)
+          raise Smith::PricingConfigurationError, "pricing entry for #{key.inspect} must be a Hash"
+        end
+
+        tiers = Pricing.__send__(:value_at, entry, :tiers)
+        tiers = [] unless tiers.is_a?(Array)
+        [entry, *tiers].each { |rates| validate_optional_rates!(key, rates) }
+        values_at(entry, :batch_discount).each { |discount| validate_batch_discount!(key, discount) }
+        reject_tier_batch_discount!(key, tiers)
+      end
+
+      def validate_optional_rates!(key, rates)
+        return unless rates.is_a?(Hash)
+
+        OPTIONAL_RATE_KEYS.each do |name|
+          next if values_at(rates, name).all? { |rate| non_negative_number?(rate) }
+
+          raise Smith::PricingConfigurationError, "#{name} for #{key.inspect} must be a non-negative Integer or Float"
+        end
+      end
+
+      # Every form of a key the entry carries, Symbol and String, so a
+      # malformed value cannot hide behind a valid one under the other form.
+      def values_at(source, name)
+        [name, name.to_s].select { |form| source.key?(form) }.map { |form| source[form] }.compact
+      end
+
+      def validate_batch_discount!(key, discount)
+        return if non_negative_number?(discount) && discount < 1
+
+        raise Smith::PricingConfigurationError, "batch_discount for #{key.inspect} must be at least 0 and below 1"
+      end
+
+      # A batch discount applies to a whole call, so it belongs on the entry;
+      # one inside a tier would never be read.
+      def reject_tier_batch_discount!(key, tiers)
+        return unless tiers.any? { |tier| tier.is_a?(Hash) && values_at(tier, :batch_discount).any? }
+
+        raise Smith::PricingConfigurationError, "batch_discount for #{key.inspect} belongs on the entry, not a tier"
+      end
+
+      def non_negative_number?(value)
+        (value.is_a?(Integer) || (value.is_a?(Float) && value.finite?)) && value >= 0
+      end
+
+      def reject_collision!(seen, key, provider, model)
+        previous = seen[[provider, model]]
+        if previous
+          raise Smith::PricingConfigurationError,
+                "pricing catalog keys #{previous.inspect} and #{key.inspect} collide as #{provider}/#{model}"
+        end
+
+        seen[[provider, model]] = key
+      end
+    end
+
+    private_constant :CatalogValidation
+  end
+end