riffer 0.40.0 → 0.42.0

data/lib/riffer/providers/anthropic.rb

@@ -30,17 +30,28 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
   end
 
   #--
-  #: (?api_key: String?, **untyped) -> void
-  def initialize(api_key: nil, **)
-    super()
+  #: () -> void
+  def initialize
+    super
     depends_on "anthropic"
+  end
 
-    api_key ||= Riffer.config.anthropic.api_key
+  private
 
-    @client = ::Anthropic::Client.new(api_key: api_key, **)
+  #--
+  #: () -> untyped
+  def global_client
+    Riffer.config.anthropic.client
   end
 
-  private
+  # Compacted for the same reason as the other providers: never hand an SDK an
+  # explicit nil credential, so its own +ANTHROPIC_API_KEY+ resolution stays
+  # reachable regardless of how that SDK distinguishes nil from absent.
+  #--
+  #: () -> untyped
+  def build_client
+    ::Anthropic::Client.new(**{ api_key: Riffer.config.anthropic.api_key }.compact)
+  end
 
   #--
   #: (Array[Riffer::Messages::Base], String?, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
@@ -97,7 +108,7 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
   #--
   #: (Hash[Symbol, untyped]) -> untyped
   def execute_generate(params)
-    @client.messages.create(**params)
+    client.messages.create(**params)
   end
 
   #--
@@ -193,7 +204,7 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
 
     # Workaround for anthropics/anthropic-sdk-ruby#182: force identity
     # encoding so Net::HTTP/Zlib doesn't buffer SSE chunks until EOF.
-    stream = @client.messages.stream(
+    stream = client.messages.stream(
       **params,
       request_options: { extra_headers: { "accept-encoding" => "identity" } },
     )
@@ -281,6 +292,10 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
   #--
   #: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
   def handle_input_json_event(event, state:, yielder:)
+    # server_tool_use (web_search) input streams through the raw-event path
+    # (handle_raw_content_block_delta) and must not surface as tool-call deltas.
+    return if state[:web_search_json]
+
     state[:tool_call] = { id: nil, name: nil, arguments: +"" } if state[:tool_call].nil?
     state[:tool_call][:arguments] << event.partial_json
     yielder << Riffer::StreamEvents::ToolCallDelta.new(

data/lib/riffer/providers/azure_open_ai.rb

@@ -2,8 +2,8 @@
 # rbs_inline: enabled
 
 # Azure OpenAI provider for GPT models hosted on Azure. Requires the +openai+
-# gem. Credentials resolve from kwargs, then config, then
-# +AZURE_OPENAI_API_KEY+ / +AZURE_OPENAI_ENDPOINT+.
+# gem. Credentials resolve from config, then +AZURE_OPENAI_API_KEY+ /
+# +AZURE_OPENAI_ENDPOINT+.
 class Riffer::Providers::AzureOpenAI < Riffer::Providers::OpenAI
   # The GenAI semconv well-known provider name.
   #--
@@ -12,15 +12,23 @@ class Riffer::Providers::AzureOpenAI < Riffer::Providers::OpenAI
     "azure.ai.openai"
   end
 
+  private
+
+  #--
+  #: () -> untyped
+  def global_client
+    Riffer.config.azure_openai.client
+  end
+
+  # Deliberately not compacted: this borrows the OpenAI SDK to talk to Azure, so
+  # omitting an unset argument would let the SDK fall back to +OPENAI_API_KEY+
+  # and +OPENAI_BASE_URL+ — sending Azure traffic, and an OpenAI credential, to
+  # whatever those name. Passing nil raises in the SDK instead.
   #--
-  #: (**untyped) -> void
-  def initialize(**options)
-    api_key = options.fetch(:api_key) do
-      Riffer.config.azure_openai.api_key || ENV.fetch("AZURE_OPENAI_API_KEY", nil)
-    end
-    base_url = options.fetch(:base_url) do
-      Riffer.config.azure_openai.endpoint || ENV.fetch("AZURE_OPENAI_ENDPOINT", nil)
-    end
-    super(api_key: api_key, base_url: base_url, **options.except(:api_key, :base_url))
+  #: () -> untyped
+  def build_client
+    api_key = Riffer.config.azure_openai.api_key || ENV.fetch("AZURE_OPENAI_API_KEY", nil)
+    base_url = Riffer.config.azure_openai.endpoint || ENV.fetch("AZURE_OPENAI_ENDPOINT", nil)
+    ::OpenAI::Client.new(api_key: api_key, base_url: base_url)
   end
 end

data/lib/riffer/providers/base.rb

@@ -10,6 +10,8 @@ require "json"
 class Riffer::Providers::Base
   # @rbs @current_tools: Array[singleton(Riffer::Tool)]
   # @rbs @current_model: String?
+  # @rbs @client: untyped
+  # @rbs self.@semconv_provider_name: String?
 
   WIRE_SEPARATOR = "__" #: String
 
@@ -29,9 +31,11 @@ class Riffer::Providers::Base
   #: () -> String
   def self.semconv_provider_name
     class_name = name
+    # Anonymous classes stay uncached: a class assigned to a constant
+    # later must pick up its real name, not a frozen "unknown".
     return "unknown" unless class_name
 
-    Riffer::Helpers::ClassNameConverter.convert(class_name.split("::").last.to_s)
+    @semconv_provider_name ||= Riffer::Helpers::Identifier.derive(class_name.split("::").last)
   end
 
   # Generates text using the provider.
@@ -105,6 +109,33 @@ class Riffer::Providers::Base
     Riffer::Helpers::Dependencies.depends_on(gem_name)
   end
 
+  # Returns the client for the current LLM call. A configured client wins,
+  # resolved on every call so a Proc can vary the client by process or
+  # credential lifetime; otherwise the provider builds one from the configured
+  # credentials, memoized for the life of the provider.
+  #--
+  #: () -> untyped
+  def client
+    configured = global_client
+    return Riffer::Helpers::CallOrValue.resolve(configured) if configured
+
+    @client ||= build_client
+  end
+
+  # Returns the consumer-configured client for this provider; nil when none is
+  # configured, and for providers that take no configuration at all.
+  #--
+  #: () -> untyped
+  def global_client
+    nil
+  end
+
+  #--
+  #: () -> untyped
+  def build_client
+    raise NotImplementedError, "Subclasses must implement #build_client"
+  end
+
   #--
   #: (String) -> String
   def encode_tool_name(name)

data/lib/riffer/providers/gemini/client.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require "json"
+require "net/http"
+require "uri"
+
+# HTTP transport for the Gemini REST API. Riffer builds one from the
+# configured +api_key+ by default; construct your own to tune the HTTP knobs
+# and assign it to <tt>Riffer.config.gemini.client</tt>. Any object
+# implementing +post+ and +post_stream+ with these contracts works there —
+# the class is a default implementation, not a required base.
+#
+#   Riffer.configure do |config|
+#     config.gemini.client = Riffer::Providers::Gemini::Client.new(
+#       api_key: ENV["GEMINI_API_KEY"],
+#       read_timeout: 120
+#     )
+#   end
+class Riffer::Providers::Gemini::Client
+  # @rbs @api_key: String?
+  # @rbs @base_url: String
+  # @rbs @open_timeout: Integer
+  # @rbs @read_timeout: Integer
+  # @rbs @write_timeout: Integer?
+  # @rbs @proxy_address: String?
+  # @rbs @proxy_port: Integer?
+
+  DEFAULT_BASE_URL = "https://generativelanguage.googleapis.com" #: String
+  DEFAULT_OPEN_TIMEOUT = 10 #: Integer
+  DEFAULT_READ_TIMEOUT = 60 #: Integer
+
+  #: (?api_key: String?, ?base_url: String, ?open_timeout: Integer, ?read_timeout: Integer, ?write_timeout: Integer?, ?proxy_address: String?, ?proxy_port: Integer?) -> void
+  def initialize(api_key: nil, base_url: DEFAULT_BASE_URL, open_timeout: DEFAULT_OPEN_TIMEOUT,
+                 read_timeout: DEFAULT_READ_TIMEOUT, write_timeout: nil,
+                 proxy_address: nil, proxy_port: nil)
+    @api_key = api_key
+    @base_url = base_url
+    @open_timeout = open_timeout
+    @read_timeout = read_timeout
+    @write_timeout = write_timeout
+    @proxy_address = proxy_address
+    @proxy_port = proxy_port
+  end
+
+  # POSTs a JSON body to an API path and returns the parsed response hash.
+  # Raises Riffer::Error when the API responds with a non-success status.
+  #--
+  #: (String, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+  def post(path, body)
+    uri = URI("#{@base_url}/#{path}")
+    response = start_http(uri) { |http| http.request(build_request(uri, body)) }
+    handle_api_error!(response) unless response.is_a?(Net::HTTPSuccess)
+    JSON.parse(response.body, symbolize_names: true)
+  end
+
+  # POSTs a JSON body to an API path, yielding raw response body chunks as
+  # they arrive. Raises Riffer::Error when the API responds with a
+  # non-success status.
+  #--
+  #: (String, Hash[Symbol, untyped]) { (String) -> void } -> void
+  def post_stream(path, body, &block)
+    uri = URI("#{@base_url}/#{path}")
+    start_http(uri) do |http|
+      http.request(build_request(uri, body)) do |response|
+        handle_api_error!(response) unless response.is_a?(Net::HTTPSuccess)
+
+        begin
+          response.read_body(&block)
+        rescue IOError
+          # A pre-buffered body (VCR/WebMock playback) raises IOError on a
+          # streaming read; hand over the full body instead.
+          yield(response.body)
+        end
+      end
+    end
+  end
+
+  private
+
+  #--
+  #: (URI::Generic, Hash[Symbol, untyped]) -> Net::HTTP::Post
+  def build_request(uri, body)
+    request = Net::HTTP::Post.new(uri)
+    request["Content-Type"] = "application/json"
+    request["x-goog-api-key"] = @api_key
+    request.body = body.to_json
+    request
+  end
+
+  #--
+  #: [R] (URI::Generic) { (Net::HTTP) -> R } -> R
+  def start_http(uri, &)
+    host = uri.hostname #: String
+    options = {
+      use_ssl: uri.scheme == "https",
+      open_timeout: @open_timeout,
+      read_timeout: @read_timeout,
+    } #: Hash[Symbol, untyped]
+    options[:write_timeout] = @write_timeout if @write_timeout
+
+    if @proxy_address
+      Net::HTTP.start(host, uri.port, @proxy_address, @proxy_port, nil, nil, **options, &)
+    else
+      Net::HTTP.start(host, uri.port, **options, &)
+    end
+  end
+
+  #--
+  #: (Net::HTTPResponse) -> void
+  def handle_api_error!(response)
+    parsed = begin
+      JSON.parse(response.body, symbolize_names: true)
+    rescue JSON::ParserError
+      { message: response.body }
+    end
+    error_message = parsed.dig(:error, :message) || parsed[:message] || response.body
+    raise Riffer::Error, "Gemini API error (#{response.code}): #{error_message}"
+  end
+end

data/lib/riffer/providers/gemini.rb

@@ -2,20 +2,11 @@
 # rbs_inline: enabled
 
 require "json"
-require "net/http"
 require "securerandom"
-require "uri"
 
 # Google Gemini provider for Gemini models via the Gemini REST API.
 class Riffer::Providers::Gemini < Riffer::Providers::Base
-  # @rbs @api_key: String?
-  # @rbs @open_timeout: Integer
-  # @rbs @read_timeout: Integer
-
-  BASE_URI = URI("https://generativelanguage.googleapis.com") #: URI::Generic
   VALID_MODEL_PATTERN = /\A[a-zA-Z0-9._-]+\z/ #: Regexp
-  DEFAULT_OPEN_TIMEOUT = 10 #: Integer
-  DEFAULT_READ_TIMEOUT = 60 #: Integer
 
   FINISH_REASONS = {
     "STOP" => :stop,
@@ -36,17 +27,19 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
     "gcp.gemini"
   end
 
+  private
+
   #--
-  #: (?api_key: String?, ?open_timeout: Integer?, ?read_timeout: Integer?, **untyped) -> void
-  def initialize(api_key: nil, open_timeout: nil, read_timeout: nil, **_options)
-    super()
-    api_key ||= Riffer.config.gemini.api_key
-    @api_key = api_key
-    @open_timeout = open_timeout || Riffer.config.gemini.open_timeout || DEFAULT_OPEN_TIMEOUT
-    @read_timeout = read_timeout || Riffer.config.gemini.read_timeout || DEFAULT_READ_TIMEOUT
+  #: () -> untyped
+  def global_client
+    Riffer.config.gemini.client
   end
 
-  private
+  #--
+  #: () -> untyped
+  def build_client
+    Riffer::Providers::Gemini::Client.new(**{ api_key: Riffer.config.gemini.api_key }.compact)
+  end
 
   #--
   #: (Array[Riffer::Messages::Base], String?, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
@@ -89,9 +82,7 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
   def execute_generate(params)
     model = params[:model]
     body = params.except(:model)
-    response = post_request(api_path(model, "generateContent"), body)
-    handle_api_error!(response) unless response.is_a?(Net::HTTPSuccess)
-    JSON.parse(response.body, symbolize_names: true)
+    client.post(api_path(model, "generateContent"), body)
   end
 
   #--
@@ -171,13 +162,6 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
     model = params[:model]
     body = params.except(:model)
 
-    uri = URI("#{BASE_URI}/#{api_path(model, 'streamGenerateContent')}?alt=sse")
-    host = uri.hostname #: String
-    request = Net::HTTP::Post.new(uri)
-    request["Content-Type"] = "application/json"
-    request["x-goog-api-key"] = @api_key
-    request.body = body.to_json
-
     full_text = +""
     buffer = +""
     raw_finish_reason = nil #: String?
@@ -224,17 +208,8 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
       end
     end
 
-    Net::HTTP.start(host, uri.port, use_ssl: true, open_timeout: @open_timeout, read_timeout: @read_timeout) do |http|
-      http.request(request) do |response|
-        handle_api_error!(response) unless response.is_a?(Net::HTTPSuccess)
-
-        begin
-          response.read_body { |chunk| process_chunk.call(chunk) }
-        rescue IOError
-          process_chunk.call(response.body)
-        end
-      end
-    end
+    path = "#{api_path(model, 'streamGenerateContent')}?alt=sse"
+    client.post_stream(path, body) { |chunk| process_chunk.call(chunk) }
 
     yielder << Riffer::StreamEvents::TextDone.new(full_text) unless full_text.empty?
     yield_finish_reason(yielder, build_finish_reason(raw_finish_reason, tool_calls: saw_function_call))
@@ -325,18 +300,6 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
     args.is_a?(String) ? args : args.to_json
   end
 
-  #--
-  #: (String, Hash[Symbol, untyped]) -> Net::HTTPResponse
-  def post_request(path, body)
-    uri = URI("#{BASE_URI}/#{path}")
-    host = uri.hostname #: String
-    request = Net::HTTP::Post.new(uri)
-    request["Content-Type"] = "application/json"
-    request["x-goog-api-key"] = @api_key
-    request.body = body.to_json
-    Net::HTTP.start(host, uri.port, use_ssl: true, open_timeout: @open_timeout, read_timeout: @read_timeout) { |http| http.request(request) }
-  end
-
   #--
   #: (String, String) -> String
   def api_path(model, method)
@@ -370,16 +333,4 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
 
     schema
   end
-
-  #--
-  #: (Net::HTTPResponse) -> void
-  def handle_api_error!(response)
-    body = begin
-      JSON.parse(response.body, symbolize_names: true)
-    rescue JSON::ParserError
-      { message: response.body }
-    end
-    error_message = body.dig(:error, :message) || body[:message] || response.body
-    raise Riffer::Error, "Gemini API error (#{response.code}): #{error_message}"
-  end
 end

data/lib/riffer/providers/mock.rb

@@ -28,7 +28,8 @@ class Riffer::Providers::Mock < Riffer::Providers::Base
   attr_reader :calls #: Array[Hash[Symbol, untyped]]
 
   # +responses:+ pre-configures canned responses (same shape as
-  # +#stub_response+), typically set via +provider_options responses: [...]+.
+  # +#stub_response+) for standalone use; agent tests queue responses on
+  # <tt>agent.provider</tt> via +#stub_response+ instead.
   #
   #   Riffer::Providers::Mock.new(responses: [
   #     {content: "", tool_calls: [{name: "tool_a", arguments: "{}"}]},
@@ -36,10 +37,10 @@ class Riffer::Providers::Mock < Riffer::Providers::Base
   #   ])
   #
   #--
-  #: (**untyped) -> void
-  def initialize(**options)
+  #: (?responses: Array[Hash[Symbol, untyped]]) -> void
+  def initialize(responses: [])
     super()
-    @responses = (options[:responses] || []).map { |r| normalize_response(r) }
+    @responses = responses.map { |r| normalize_response(r) }
     @current_index = 0
     @calls = []
     @stubbed_responses = []

data/lib/riffer/providers/open_ai.rb

@@ -13,17 +13,32 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
   end
 
   #--
-  #: (**untyped) -> void
-  def initialize(**options)
-    super()
+  #: () -> void
+  def initialize
+    super
     depends_on "openai"
-
-    api_key = options.fetch(:api_key, Riffer.config.openai.api_key)
-    @client = ::OpenAI::Client.new(api_key: api_key, **options.except(:api_key))
   end
 
   private
 
+  #--
+  #: () -> untyped
+  def global_client
+    Riffer.config.openai.client
+  end
+
+  # Compacted so an unset value stays absent: the SDK reads +OPENAI_API_KEY+ /
+  # +OPENAI_BASE_URL+ only for a missing argument, and an explicit nil would
+  # suppress that fallback.
+  #--
+  #: () -> untyped
+  def build_client
+    ::OpenAI::Client.new(**{
+      api_key: Riffer.config.openai.api_key,
+      base_url: Riffer.config.openai.base_url,
+    }.compact)
+  end
+
   #--
   #: (Array[Riffer::Messages::Base], String?, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
   def build_request_params(messages, model, options)
@@ -81,7 +96,7 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
   #--
   #: (Hash[Symbol, untyped]) -> untyped
   def execute_generate(params)
-    @client.responses.create(params)
+    client.responses.create(params)
   end
 
   #--
@@ -190,7 +205,7 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
       tool_info: {},
     } #: Hash[Symbol, untyped]
 
-    stream = @client.responses.stream(params)
+    stream = client.responses.stream(params)
     begin
       stream.each do |event|
         case event.type

data/lib/riffer/providers/open_router.rb

@@ -5,7 +5,7 @@ require "json"
 
 # OpenRouter provider (https://openrouter.ai). Requires the +openai+ gem —
 # OpenRouter exposes an OpenAI-compatible endpoint, so this reuses the OpenAI
-# SDK with a +base_url+ override. +api_key+ falls back to config, then
+# SDK with a +base_url+ override. +api_key+ resolves from config, then
 # +OPENROUTER_API_KEY+.
 class Riffer::Providers::OpenRouter < Riffer::Providers::Base
   BASE_URL = "https://openrouter.ai/api/v1" #: String
@@ -27,17 +27,31 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
   end
 
   #--
-  #: (?api_key: String?, **untyped) -> void
-  def initialize(api_key: nil, **)
-    super()
+  #: () -> void
+  def initialize
+    super
     depends_on "openai"
+  end
 
-    api_key ||= Riffer.config.openrouter.api_key || ENV.fetch("OPENROUTER_API_KEY", nil)
+  private
 
-    @client = ::OpenAI::Client.new(api_key: api_key, base_url: BASE_URL, **)
+  #--
+  #: () -> untyped
+  def global_client
+    Riffer.config.openrouter.client
   end
 
-  private
+  # Deliberately not compacted: this borrows the OpenAI SDK to talk to a
+  # different vendor, so omitting an unset +api_key+ would let the SDK fall
+  # back to +OPENAI_API_KEY+ and send an OpenAI credential to OpenRouter.
+  # Passing nil raises in the SDK instead. +OPENROUTER_API_KEY+ is read here
+  # rather than left to the SDK for the same reason.
+  #--
+  #: () -> untyped
+  def build_client
+    api_key = Riffer.config.openrouter.api_key || ENV.fetch("OPENROUTER_API_KEY", nil)
+    ::OpenAI::Client.new(api_key: api_key, base_url: BASE_URL)
+  end
 
   #--
   #: (Array[Riffer::Messages::Base], String?, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
@@ -84,7 +98,7 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
   #--
   #: (Hash[Symbol, untyped]) -> untyped
   def execute_generate(params)
-    @client.chat.completions.create(**params)
+    client.chat.completions.create(**params)
   end
 
   #--
@@ -174,7 +188,7 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
     # events. We want raw ChatCompletionChunk objects with
     # +choices.first.delta+ so we can map deltas to Riffer::StreamEvents
     # ourselves.
-    stream = @client.chat.completions.stream_raw(**stream_params)
+    stream = client.chat.completions.stream_raw(**stream_params)
     begin
       stream.each do |chunk|
         handle_stream_chunk(chunk, state: state, yielder: yielder)

data/lib/riffer/registrable.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Registry of a class's named direct subclasses, keyed by identifier. Extend it
+# onto a base class to look up subclasses in constant time via +find+ and +all+.
+#
+#   class Riffer::Tool
+#     extend Riffer::Registrable
+#   end
+#
+#   Riffer::Tool.find("weather_tool") # => WeatherTool
+#
+# @rbs module-self Class
+module Riffer::Registrable
+  # @rbs @identifier_registry: Hash[String, Class]?
+
+  # Finds a registered subclass by identifier, or +nil+ when none matches.
+  # Only *named direct* subclasses are registered: grandchildren are not
+  # visible to a grandparent's +find+ (call +find+ on their direct parent
+  # instead), anonymous classes are never registered, and duplicate identifiers
+  # raise Riffer::DuplicateIdentifierError at first lookup.
+  #
+  #--
+  #: (String | Symbol) -> Class?
+  def find(identifier)
+    identifier_registry[identifier.to_s]
+  end
+
+  # Returns all registered subclasses. Only *named direct* subclasses are
+  # registered: grandchildren are not included (call +all+ on their direct
+  # parent instead), anonymous classes are never registered, and duplicate
+  # identifiers raise Riffer::DuplicateIdentifierError at first lookup.
+  #
+  #--
+  #: () -> Array[Class]
+  def all
+    identifier_registry.values
+  end
+
+  private
+
+  # Ruby invokes +inherited+ with +self+ bound to the direct superclass — the
+  # only registry the new subclass joins — so busting self's memo is exactly
+  # sufficient.
+  #--
+  #: (Class) -> void
+  def inherited(subclass)
+    super
+    @identifier_registry = nil
+  end
+
+  #--
+  #: () -> Hash[String, Class]
+  def identifier_registry
+    @identifier_registry ||= build_identifier_registry
+  end
+
+  #--
+  #: () -> Hash[String, Class]
+  def build_identifier_registry
+    registry = {} #: Hash[String, Class]
+    subclasses.each_with_object(registry) do |subclass, acc|
+      # Anonymous classes are skipped even with an explicit identifier — the
+      # MCP factory and serializer shells synthesize short-lived anonymous
+      # classes whose registration would flake with GC timing.
+      next if Riffer::Helpers::Identifier.for(subclass).empty?
+
+      candidate = subclass #: untyped
+      key = candidate.identifier.to_s
+      next if key.strip.empty?
+
+      existing = acc[key]
+      if existing
+        raise Riffer::DuplicateIdentifierError,
+              "Duplicate identifier #{key.inspect} for #{existing} and #{subclass}"
+      end
+
+      acc[key] = subclass
+    end.freeze
+  end
+end

data/lib/riffer/tool.rb

@@ -21,6 +21,7 @@ require "timeout"
 #
 class Riffer::Tool
   extend Riffer::Tools::Toolable
+  extend Riffer::Registrable
 
   kind :tool
 

data/lib/riffer/tools/toolable.rb

@@ -15,6 +15,7 @@
 #     end
 #   end
 #
+# @rbs module-self Module
 module Riffer::Tools::Toolable
   # @rbs self.@extenders: Array[Module]?
   # @rbs @description: String?
@@ -57,9 +58,7 @@ module Riffer::Tools::Toolable
   #--
   #: (?String?) -> String
   def identifier(value = nil)
-    if value.nil?
-      return @identifier || Riffer::Helpers::ClassNameConverter.convert(Module.instance_method(:name).bind_call(self))
-    end
+    return @identifier || Riffer::Helpers::Identifier.for(self) if value.nil?
 
     @identifier = value.to_s
   end

data/lib/riffer/version.rb

@@ -2,5 +2,5 @@
 # rbs_inline: enabled
 
 module Riffer
-  VERSION = "0.40.0" #: String
+  VERSION = "0.42.0" #: String
 end

data/lib/riffer.rb

@@ -32,6 +32,9 @@ module Riffer
   # Raised when a tool encounters an expected execution error.
   class ToolExecutionError < Error; end
 
+  # Raised when two registered subclasses share the same identifier.
+  class DuplicateIdentifierError < Error; end
+
   # Returns the Riffer configuration.
   #
   #--