riffer 0.40.0 → 0.42.0

data/sig/_private/riffer/providers/amazon_bedrock.rbs

@@ -1,4 +1,6 @@
-# `@client` is typed against the SDK, so this ivar stub stays in _private (never ships)
+# `client` is typed against the SDK, so this narrowing stays in _private (never ships)
 class Riffer::Providers::AmazonBedrock
-  @client: ::Aws::BedrockRuntime::Client
+  private
+
+  def client: () -> ::Aws::BedrockRuntime::Client
 end

data/sig/_private/riffer/providers/anthropic.rbs

@@ -1,4 +1,6 @@
-# `@client` is typed against the SDK, so this ivar stub stays in _private (never ships)
+# `client` is typed against the SDK, so this narrowing stays in _private (never ships)
 class Riffer::Providers::Anthropic
-  @client: ::Anthropic::Client
+  private
+
+  def client: () -> ::Anthropic::Client
 end

data/sig/_private/riffer/providers/gemini.rbs

@@ -0,0 +1,7 @@
+# Narrows the private `client` to riffer's Gemini transport, mirroring the
+# SDK-typed narrowings alongside it.
+class Riffer::Providers::Gemini
+  private
+
+  def client: () -> Riffer::Providers::Gemini::Client
+end

data/sig/_private/riffer/providers/open_ai.rbs

@@ -1,4 +1,6 @@
-# `@client` is typed against the SDK, so this ivar stub stays in _private (never ships)
+# `client` is typed against the SDK, so this narrowing stays in _private (never ships)
 class Riffer::Providers::OpenAI
-  @client: ::OpenAI::Client
+  private
+
+  def client: () -> ::OpenAI::Client
 end

data/sig/_private/riffer/providers/open_router.rbs

@@ -1,4 +1,6 @@
-# `@client` is typed against the SDK, so this ivar stub stays in _private (never ships)
+# `client` is typed against the SDK, so this narrowing stays in _private (never ships)
 class Riffer::Providers::OpenRouter
-  @client: ::OpenAI::Client
+  private
+
+  def client: () -> ::OpenAI::Client
 end

data/sig/generated/riffer/agent/config.rbs

@@ -15,9 +15,6 @@ class Riffer::Agent::Config
   # The configured instructions.
   attr_reader instructions: (String | Proc)?
 
-  # Options passed to the provider client.
-  attr_accessor provider_options: Hash[Symbol, untyped]
-
   # Options passed to generate_text/stream_text.
   attr_accessor model_options: Hash[Symbol, untyped]
 
@@ -49,7 +46,6 @@ class Riffer::Agent::Config
   #    ?identifier: String?,
   #    ?model: (String | Proc)?,
   #    ?instructions: (String | Proc)?,
-  #    ?provider_options: Hash[Symbol, untyped],
   #    ?model_options: Hash[Symbol, untyped],
   #    ?structured_output: Riffer::Params?,
   #    ?max_steps: Numeric?,
@@ -59,7 +55,7 @@ class Riffer::Agent::Config
   #    ?skills_config: Riffer::Skills::Config?,
   #    ?guardrails: Hash[Symbol, Array[Hash[Symbol, untyped]]]
   #  ) -> void
-  def initialize: (?identifier: String?, ?model: (String | Proc)?, ?instructions: (String | Proc)?, ?provider_options: Hash[Symbol, untyped], ?model_options: Hash[Symbol, untyped], ?structured_output: Riffer::Params?, ?max_steps: Numeric?, ?tools_config: (Array[singleton(Riffer::Tool)] | Proc)?, ?mcp_configs: Array[Hash[Symbol, untyped]], ?tool_runtime: singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc, ?skills_config: Riffer::Skills::Config?, ?guardrails: Hash[Symbol, Array[Hash[Symbol, untyped]]]) -> void
+  def initialize: (?identifier: String?, ?model: (String | Proc)?, ?instructions: (String | Proc)?, ?model_options: Hash[Symbol, untyped], ?structured_output: Riffer::Params?, ?max_steps: Numeric?, ?tools_config: (Array[singleton(Riffer::Tool)] | Proc)?, ?mcp_configs: Array[Hash[Symbol, untyped]], ?tool_runtime: singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc, ?skills_config: Riffer::Skills::Config?, ?guardrails: Hash[Symbol, Array[Hash[Symbol, untyped]]]) -> void
 
   # Sets +identifier+, coercing the value to String.
   # --

data/sig/generated/riffer/agent.rbs

@@ -11,6 +11,8 @@
 #   agent = MyAgent.new
 #   agent.generate('Hello!')
 class Riffer::Agent
+  extend Riffer::Registrable
+
   self.@config: Riffer::Agent::Config?
 
   INTERRUPT_MAX_STEPS: Symbol
@@ -45,12 +47,6 @@ class Riffer::Agent
   # : (?(String | Proc)?) -> (String | Proc)?
   def self.instructions: (?(String | Proc)?) -> (String | Proc)?
 
-  # Gets or sets provider options passed to the provider client.
-  #
-  # --
-  # : (?Hash[Symbol, untyped]?) -> Hash[Symbol, untyped]
-  def self.provider_options: (?Hash[Symbol, untyped]?) -> Hash[Symbol, untyped]
-
   # Gets or sets model options passed to generate_text/stream_text.
   #
   # --
@@ -110,18 +106,6 @@ class Riffer::Agent
   # : () ?{ (Riffer::Skills::Config) [self: Riffer::Skills::Config] -> void } -> Riffer::Skills::Config?
   def self.skills: () ?{ (Riffer::Skills::Config) [self: Riffer::Skills::Config] -> void } -> Riffer::Skills::Config?
 
-  # Finds an agent class by identifier.
-  #
-  # --
-  # : (String) -> singleton(Riffer::Agent)?
-  def self.find: (String) -> singleton(Riffer::Agent)?
-
-  # Returns all agent subclasses.
-  #
-  # --
-  # : () -> Array[singleton(Riffer::Agent)]
-  def self.all: () -> Array[singleton(Riffer::Agent)]
-
   # Generates a response using a new agent instance.
   # --
   # : (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?context: Hash[Symbol, untyped]?, ?tags: Hash[(String | Symbol), untyped]) -> Riffer::Agent::Response

data/sig/generated/riffer/config.rbs

@@ -7,15 +7,19 @@ class Riffer::Config
 
     attr_accessor region(): untyped
 
-    def self.new: (?untyped api_token, ?untyped region) -> instance
-                | (?api_token: untyped, ?region: untyped) -> instance
+    attr_accessor client(): untyped
+
+    def self.new: (?untyped api_token, ?untyped region, ?untyped client) -> instance
+                | (?api_token: untyped, ?region: untyped, ?client: untyped) -> instance
   end
 
   class Anthropic < Struct[untyped]
     attr_accessor api_key(): untyped
 
-    def self.new: (?untyped api_key) -> instance
-                | (?api_key: untyped) -> instance
+    attr_accessor client(): untyped
+
+    def self.new: (?untyped api_key, ?untyped client) -> instance
+                | (?api_key: untyped, ?client: untyped) -> instance
   end
 
   class AzureOpenAI < Struct[untyped]
@@ -23,33 +27,39 @@ class Riffer::Config
 
     attr_accessor endpoint(): untyped
 
-    def self.new: (?untyped api_key, ?untyped endpoint) -> instance
-                | (?api_key: untyped, ?endpoint: untyped) -> instance
+    attr_accessor client(): untyped
+
+    def self.new: (?untyped api_key, ?untyped endpoint, ?untyped client) -> instance
+                | (?api_key: untyped, ?endpoint: untyped, ?client: untyped) -> instance
   end
 
   class Gemini < Struct[untyped]
     attr_accessor api_key(): untyped
 
-    attr_accessor open_timeout(): untyped
-
-    attr_accessor read_timeout(): untyped
+    attr_accessor client(): untyped
 
-    def self.new: (?untyped api_key, ?untyped open_timeout, ?untyped read_timeout) -> instance
-                | (?api_key: untyped, ?open_timeout: untyped, ?read_timeout: untyped) -> instance
+    def self.new: (?untyped api_key, ?untyped client) -> instance
+                | (?api_key: untyped, ?client: untyped) -> instance
   end
 
   class OpenAI < Struct[untyped]
     attr_accessor api_key(): untyped
 
-    def self.new: (?untyped api_key) -> instance
-                | (?api_key: untyped) -> instance
+    attr_accessor base_url(): untyped
+
+    attr_accessor client(): untyped
+
+    def self.new: (?untyped api_key, ?untyped base_url, ?untyped client) -> instance
+                | (?api_key: untyped, ?base_url: untyped, ?client: untyped) -> instance
   end
 
   class OpenRouter < Struct[untyped]
     attr_accessor api_key(): untyped
 
-    def self.new: (?untyped api_key) -> instance
-                | (?api_key: untyped) -> instance
+    attr_accessor client(): untyped
+
+    def self.new: (?untyped api_key, ?untyped client) -> instance
+                | (?api_key: untyped, ?client: untyped) -> instance
   end
 
   class Evals < Struct[untyped]

data/sig/generated/riffer/evals/judge.rbs

@@ -3,8 +3,6 @@
 # Executes LLM-as-judge evaluations, using tool calling internally to get
 # structured output from the judge model.
 class Riffer::Evals::Judge
-  @provider_options: Hash[Symbol, untyped]
-
   @provider_instance: Riffer::Providers::Base?
 
   @provider_name: String?
@@ -23,8 +21,8 @@ class Riffer::Evals::Judge
 
   # Raises Riffer::ArgumentError unless +model+ is "provider/model" format.
   # --
-  # : (model: String, ?provider_options: Hash[Symbol, untyped]) -> void
-  def initialize: (model: String, ?provider_options: Hash[Symbol, untyped]) -> void
+  # : (model: String) -> void
+  def initialize: (model: String) -> void
 
   # Evaluates an input/output pair using the configured LLM.
   # --

data/sig/generated/riffer/helpers/identifier.rbs

@@ -0,0 +1,19 @@
+# Generated from lib/riffer/helpers/identifier.rb with RBS::Inline
+
+# Helper module for deriving snake_case identifiers from class names.
+module Riffer::Helpers::Identifier
+  # Derives a snake_case identifier from a class name string.
+  #
+  # --
+  # : (String?) -> String
+  def derive: (String?) -> String
+
+  # Derives and memoizes the identifier for a class or module. Anonymous
+  # classes return "" without caching, so a class named later still derives its
+  # real identifier — a guard that must travel with the cache, so callers never
+  # memoize their own.
+  #
+  # --
+  # : (Module) -> String
+  def for: (Module) -> String
+end

data/sig/generated/riffer/providers/amazon_bedrock.rbs

@@ -21,11 +21,22 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   def self.semconv_provider_name: () -> String
 
   # --
-  # : (?api_token: String?, ?region: String?, **untyped) -> void
-  def initialize: (?api_token: String?, ?region: String?, **untyped) -> void
+  # : () -> void
+  def initialize: () -> void
 
   private
 
+  # --
+  # : () -> untyped
+  def global_client: () -> untyped
+
+  # Compacted so an unset region stays absent: the AWS SDK resolves +AWS_REGION+
+  # and the shared config only for a missing argument, and raises
+  # +Aws::Errors::MissingRegionError+ on an explicit nil.
+  # --
+  # : () -> untyped
+  def build_client: () -> untyped
+
   # --
   # : (Array[Riffer::Messages::Base], String?, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
   def build_request_params: (Array[Riffer::Messages::Base], String?, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]

data/sig/generated/riffer/providers/anthropic.rbs

@@ -19,11 +19,22 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
   def self.semconv_provider_name: () -> String
 
   # --
-  # : (?api_key: String?, **untyped) -> void
-  def initialize: (?api_key: String?, **untyped) -> void
+  # : () -> void
+  def initialize: () -> void
 
   private
 
+  # --
+  # : () -> untyped
+  def global_client: () -> untyped
+
+  # 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: () -> untyped
+
   # --
   # : (Array[Riffer::Messages::Base], String?, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
   def build_request_params: (Array[Riffer::Messages::Base], String?, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]

data/sig/generated/riffer/providers/azure_open_ai.rbs

@@ -1,15 +1,25 @@
 # Generated from lib/riffer/providers/azure_open_ai.rb with RBS::Inline
 
 # 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.
   # --
   # : () -> String
   def self.semconv_provider_name: () -> String
 
+  private
+
+  # --
+  # : () -> untyped
+  def global_client: () -> untyped
+
+  # 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: (**untyped) -> void
+  # : () -> untyped
+  def build_client: () -> untyped
 end

data/sig/generated/riffer/providers/base.rbs

@@ -5,6 +5,10 @@
 # +extract_token_usage+, +extract_content+, +extract_tool_calls+) and the base
 # class orchestrates them.
 class Riffer::Providers::Base
+  self.@semconv_provider_name: String?
+
+  @client: untyped
+
   @current_model: String?
 
   @current_tools: Array[singleton(Riffer::Tool)]
@@ -42,6 +46,24 @@ class Riffer::Providers::Base
   # : (String) -> true
   def depends_on: (String) -> true
 
+  # 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: () -> untyped
+
+  # 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: () -> untyped
+
+  # --
+  # : () -> untyped
+  def build_client: () -> untyped
+
   # --
   # : (String) -> String
   def encode_tool_name: (String) -> String

data/sig/generated/riffer/providers/gemini/client.rbs

@@ -0,0 +1,65 @@
+# Generated from lib/riffer/providers/gemini/client.rb with RBS::Inline
+
+# 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
+  @proxy_port: Integer?
+
+  @proxy_address: String?
+
+  @write_timeout: Integer?
+
+  @read_timeout: Integer
+
+  @open_timeout: Integer
+
+  @base_url: String
+
+  @api_key: String?
+
+  DEFAULT_BASE_URL: String
+
+  DEFAULT_OPEN_TIMEOUT: Integer
+
+  DEFAULT_READ_TIMEOUT: 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: String?, ?base_url: String, ?open_timeout: Integer, ?read_timeout: Integer, ?write_timeout: Integer?, ?proxy_address: String?, ?proxy_port: Integer?) -> void
+
+  # 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: (String, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+
+  # 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: (String, Hash[Symbol, untyped]) { (String) -> void } -> void
+
+  private
+
+  # --
+  # : (URI::Generic, Hash[Symbol, untyped]) -> Net::HTTP::Post
+  def build_request: (URI::Generic, Hash[Symbol, untyped]) -> Net::HTTP::Post
+
+  # --
+  # : [R] (URI::Generic) { (Net::HTTP) -> R } -> R
+  def start_http: [R] (URI::Generic) { (Net::HTTP) -> R } -> R
+
+  # --
+  # : (Net::HTTPResponse) -> void
+  def handle_api_error!: (Net::HTTPResponse) -> void
+end

data/sig/generated/riffer/providers/gemini.rbs

@@ -2,20 +2,8 @@
 
 # Google Gemini provider for Gemini models via the Gemini REST API.
 class Riffer::Providers::Gemini < Riffer::Providers::Base
-  @read_timeout: Integer
-
-  @open_timeout: Integer
-
-  @api_key: String?
-
-  BASE_URI: URI::Generic
-
   VALID_MODEL_PATTERN: Regexp
 
-  DEFAULT_OPEN_TIMEOUT: Integer
-
-  DEFAULT_READ_TIMEOUT: Integer
-
   FINISH_REASONS: Hash[String, Symbol]
 
   # The GenAI semconv well-known provider name.
@@ -23,11 +11,15 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
   # : () -> String
   def self.semconv_provider_name: () -> String
 
+  private
+
   # --
-  # : (?api_key: String?, ?open_timeout: Integer?, ?read_timeout: Integer?, **untyped) -> void
-  def initialize: (?api_key: String?, ?open_timeout: Integer?, ?read_timeout: Integer?, **untyped) -> void
+  # : () -> untyped
+  def global_client: () -> untyped
 
-  private
+  # --
+  # : () -> untyped
+  def build_client: () -> untyped
 
   # --
   # : (Array[Riffer::Messages::Base], String?, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
@@ -89,10 +81,6 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
   # : (untyped) -> String
   def encode_tool_arguments: (untyped) -> String
 
-  # --
-  # : (String, Hash[Symbol, untyped]) -> Net::HTTPResponse
-  def post_request: (String, Hash[Symbol, untyped]) -> Net::HTTPResponse
-
   # --
   # : (String, String) -> String
   def api_path: (String, String) -> String
@@ -104,8 +92,4 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
   # --
   # : (Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
   def strip_additional_properties: (Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
-
-  # --
-  # : (Net::HTTPResponse) -> void
-  def handle_api_error!: (Net::HTTPResponse) -> void
 end

data/sig/generated/riffer/providers/mock.rbs

@@ -23,7 +23,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: "{}"}]},
@@ -31,8 +32,8 @@ class Riffer::Providers::Mock < Riffer::Providers::Base
   #   ])
   #
   # --
-  # : (**untyped) -> void
-  def initialize: (**untyped) -> void
+  # : (?responses: Array[Hash[Symbol, untyped]]) -> void
+  def initialize: (?responses: Array[Hash[Symbol, untyped]]) -> void
 
   # Stubs the next response; call repeatedly to queue several. +finish_reason+
   # defaults to +:tool_calls+ when tool calls are present, else +:stop+.

data/sig/generated/riffer/providers/open_ai.rbs

@@ -10,11 +10,22 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
   def self.semconv_provider_name: () -> String
 
   # --
-  # : (**untyped) -> void
-  def initialize: (**untyped) -> void
+  # : () -> void
+  def initialize: () -> void
 
   private
 
+  # --
+  # : () -> untyped
+  def global_client: () -> untyped
+
+  # 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: () -> untyped
+
   # --
   # : (Array[Riffer::Messages::Base], String?, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
   def build_request_params: (Array[Riffer::Messages::Base], String?, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]

data/sig/generated/riffer/providers/open_router.rbs

@@ -2,7 +2,7 @@
 
 # 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: String
@@ -15,11 +15,24 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
   def self.semconv_provider_name: () -> String
 
   # --
-  # : (?api_key: String?, **untyped) -> void
-  def initialize: (?api_key: String?, **untyped) -> void
+  # : () -> void
+  def initialize: () -> void
 
   private
 
+  # --
+  # : () -> untyped
+  def global_client: () -> untyped
+
+  # 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: () -> untyped
+
   # --
   # : (Array[Riffer::Messages::Base], String?, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
   def build_request_params: (Array[Riffer::Messages::Base], String?, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]

data/sig/generated/riffer/registrable.rbs

@@ -0,0 +1,51 @@
+# Generated from lib/riffer/registrable.rb with RBS::Inline
+
+# 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 : Class
+  @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: (String | Symbol) -> Class?
+
+  # 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: () -> Array[Class]
+
+  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: (Class) -> void
+
+  # --
+  # : () -> Hash[String, Class]
+  def identifier_registry: () -> Hash[String, Class]
+
+  # --
+  # : () -> Hash[String, Class]
+  def build_identifier_registry: () -> Hash[String, Class]
+end

data/sig/generated/riffer/tool.rbs

@@ -18,6 +18,8 @@
 class Riffer::Tool
   extend Riffer::Tools::Toolable
 
+  extend Riffer::Registrable
+
   # Executes the tool with the given arguments.
   # --
   # : (context: Riffer::Agent::Context?, **untyped) -> Riffer::Tools::Response

data/sig/generated/riffer/tools/toolable.rbs

@@ -13,7 +13,9 @@
 #       required :input, String
 #     end
 #   end
-module Riffer::Tools::Toolable
+#
+# @rbs module-self Module
+module Riffer::Tools::Toolable : Module
   @kind: Symbol?
 
   @params_builder: Riffer::Params?

data/sig/generated/riffer.rbs

@@ -23,6 +23,10 @@ module Riffer
   class ToolExecutionError < Error
   end
 
+  # Raised when two registered subclasses share the same identifier.
+  class DuplicateIdentifierError < Error
+  end
+
   # Returns the Riffer configuration.
   #
   # --

data/sig/manual/riffer/agent.rbs

@@ -0,0 +1,7 @@
+# `Riffer::Agent` extends `Riffer::Registrable`, whose generic signatures return
+# `Class`. Narrow them here so callers get the agent singleton type back.
+class Riffer::Agent
+  def self.find: (String | Symbol) -> singleton(Riffer::Agent)?
+
+  def self.all: () -> Array[singleton(Riffer::Agent)]
+end

data/sig/manual/riffer/helpers/identifier.rbs

@@ -0,0 +1,5 @@
+# `Riffer::Helpers::Identifier` uses `extend self`; rbs-inline doesn't emit
+# that, so re-extend here to expose its instance methods as singleton methods.
+module Riffer::Helpers::Identifier
+  extend ::Riffer::Helpers::Identifier
+end