riffer 0.47.1 → 0.48.0

data/lib/riffer/agent/config.rb

@@ -7,38 +7,37 @@
 class Riffer::Agent::Config
   DEFAULT_MAX_STEPS = 16 #: Integer
 
+  # @rbs @tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?
+
   # The configured agent identifier.
-  attr_reader :identifier #: String?
+  attr_reader :identifier #: String? # @dynamic identifier
 
   # The configured model.
-  attr_reader :model #: (String | Proc)?
+  attr_reader :model #: (String | Proc)? # @dynamic model
 
   # The configured instructions.
-  attr_reader :instructions #: (String | Proc)?
+  attr_reader :instructions #: (String | Proc)? # @dynamic instructions
 
   # Options passed to generate_text/stream_text.
-  attr_accessor :model_options #: Hash[Symbol, untyped]
+  attr_accessor :model_options #: Hash[Symbol, untyped] # @dynamic model_options, model_options=
 
   # The configured structured-output schema.
-  attr_reader :structured_output #: Riffer::Params?
+  attr_reader :structured_output #: Riffer::Params? # @dynamic structured_output
 
   # The maximum number of LLM call steps in the tool-use loop.
-  attr_accessor :max_steps #: Numeric?
+  attr_accessor :max_steps #: Numeric? # @dynamic max_steps, max_steps=
 
   # The configured tools.
-  attr_accessor :tools_config #: (Array[singleton(Riffer::Tool)] | Proc)?
+  attr_accessor :tools_config #: (Array[singleton(Riffer::Tool)] | Proc)? # @dynamic tools_config, tools_config=
 
   # The accumulated +use_mcp+ tag configurations.
-  attr_reader :mcp_configs #: Array[Hash[Symbol, untyped]]
-
-  # The configured tool runtime.
-  attr_reader :tool_runtime #: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)
+  attr_reader :mcp_configs #: Array[Hash[Symbol, untyped]] # @dynamic mcp_configs
 
   # The configured skills.
-  attr_accessor :skills_config #: Riffer::Skills::Config?
+  attr_accessor :skills_config #: Riffer::Skills::Config? # @dynamic skills_config, skills_config=
 
   # Registered guardrail entries keyed by phase.
-  attr_reader :guardrails #: Hash[Symbol, Array[Hash[Symbol, untyped]]]
+  attr_reader :guardrails #: Hash[Symbol, Array[Hash[Symbol, untyped]]] # @dynamic guardrails
 
   # Builds a new Config. Raises Riffer::ArgumentError if +model+ or
   # +instructions+ is invalid (e.g. an empty string).
@@ -52,7 +51,7 @@ class Riffer::Agent::Config
   #    ?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),
+  #    ?tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?,
   #    ?skills_config: Riffer::Skills::Config?,
   #    ?guardrails: Hash[Symbol, Array[Hash[Symbol, untyped]]]
   #  ) -> void
@@ -65,7 +64,7 @@ class Riffer::Agent::Config
     max_steps: DEFAULT_MAX_STEPS,
     tools_config: nil,
     mcp_configs: [],
-    tool_runtime: Riffer.config.tool_runtime,
+    tool_runtime: nil,
     skills_config: nil,
     guardrails: { before: [], after: [] }
   )
@@ -79,7 +78,7 @@ class Riffer::Agent::Config
     self.model = model
     self.instructions = instructions
     self.structured_output = structured_output
-    self.tool_runtime = tool_runtime
+    self.tool_runtime = tool_runtime if tool_runtime
   end
 
   # Sets +identifier+, coercing the value to String.
@@ -100,6 +99,15 @@ class Riffer::Agent::Config
     @structured_output = value
   end
 
+  # Returns the declared tool runtime, or +Riffer.config.tool_runtime+ when none
+  # was declared. Resolving the global here rather than at construction is what
+  # lets a copy tell an inherited runtime from a defaulted one.
+  #--
+  #: () -> (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)
+  def tool_runtime
+    @tool_runtime || Riffer.config.tool_runtime
+  end
+
   # Sets +tool_runtime+. Raises Riffer::ArgumentError on an invalid value.
   #--
   #: ((singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)) -> (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)
@@ -177,6 +185,22 @@ class Riffer::Agent::Config
 
   private
 
+  # +dup+ would leave the copy sharing every collection with this one, so a
+  # declaration on either would reach the other. The nesting runs deeper than one
+  # level: an mcp entry holds its own +:tags+ array, a guardrail entry its own
+  # +:options+ hash, and +model_options+ is arbitrary.
+  #--
+  #: (Riffer::Agent::Config) -> void
+  def initialize_copy(source)
+    super
+    @model_options = Riffer::Helpers::DeepDup.call(source.model_options)
+    @mcp_configs = Riffer::Helpers::DeepDup.call(source.mcp_configs)
+    @guardrails = Riffer::Helpers::DeepDup.call(source.guardrails)
+    @tools_config = Riffer::Helpers::DeepDup.call(source.tools_config)
+    @skills_config = source.skills_config&.dup
+    @structured_output = source.structured_output&.dup
+  end
+
   #--
   #: (untyped, String) -> void
   def validate_string_or_proc!(value, name)

data/lib/riffer/agent/outcome.rb

@@ -25,10 +25,10 @@ class Riffer::Agent::Outcome
             PROVIDER_STOP_REASONS).freeze #: Array[Symbol]
 
   # Why the run ended.
-  attr_reader :reason #: Symbol
+  attr_reader :reason #: Symbol # @dynamic reason
 
   # Human-readable specifics for +reason+, when there are any.
-  attr_reader :detail #: String?
+  attr_reader :detail #: String? # @dynamic detail
 
   # Raises Riffer::ArgumentError when +reason+ is outside VALUES.
   #--

data/lib/riffer/agent/response.rb

@@ -13,33 +13,37 @@
 #   end
 class Riffer::Agent::Response
   # The response content.
-  attr_reader :content #: String
+  attr_reader :content #: String # @dynamic content
 
   # How the run ended.
-  attr_reader :outcome #: Riffer::Agent::Outcome
+  attr_reader :outcome #: Riffer::Agent::Outcome # @dynamic outcome
 
   # The tripwire if execution was blocked.
-  attr_reader :tripwire #: Riffer::Guardrails::Tripwire?
+  attr_reader :tripwire #: Riffer::Guardrails::Tripwire? # @dynamic tripwire
 
   # The modifications made by guardrails during processing.
-  attr_reader :modifications #: Array[Riffer::Guardrails::Modification]
+  attr_reader :modifications #: Array[Riffer::Guardrails::Modification] # @dynamic modifications
+
+  # The reasoning parts on the final assistant message, if the provider
+  # produced any.
+  attr_reader :reasoning #: Array[Riffer::Messages::Assistant::ReasoningPart] # @dynamic reasoning
 
   # The parsed structured output, if structured output was configured.
-  attr_reader :structured_output #: Hash[Symbol, untyped]?
+  attr_reader :structured_output #: Hash[Symbol, untyped]? # @dynamic structured_output
 
   # The aggregate token usage across this run's LLM calls, if any was reported.
-  attr_reader :token_usage #: Riffer::Providers::TokenUsage?
+  attr_reader :token_usage #: Riffer::Providers::TokenUsage? # @dynamic token_usage
 
   # The number of LLM calls made during this run (0 when a before-guardrail
   # blocks before any call). Distinct from the session's cumulative step count.
-  attr_reader :steps #: Integer
+  attr_reader :steps #: Integer # @dynamic steps
 
   # The full message history from the agent conversation.
-  attr_reader :messages #: Array[Riffer::Messages::Base]
+  attr_reader :messages #: Array[Riffer::Messages::Base] # @dynamic messages
 
   # Call ids of tool_use blocks riffer filled with placeholder results this
   # turn (when an interrupt left them unanswered and history healing is on).
-  attr_reader :healed_tool_call_ids #: Array[String]
+  attr_reader :healed_tool_call_ids #: Array[String] # @dynamic healed_tool_call_ids
 
   #--
   #: (
@@ -47,6 +51,7 @@ class Riffer::Agent::Response
   #    outcome: Riffer::Agent::Outcome,
   #    ?tripwire: Riffer::Guardrails::Tripwire?,
   #    ?modifications: Array[Riffer::Guardrails::Modification],
+  #    ?reasoning: Array[Riffer::Messages::Assistant::ReasoningPart],
   #    ?structured_output: Hash[Symbol, untyped]?,
   #    ?messages: Array[Riffer::Messages::Base],
   #    ?healed_tool_call_ids: Array[String],
@@ -58,6 +63,7 @@ class Riffer::Agent::Response
     outcome:,
     tripwire: nil,
     modifications: [],
+    reasoning: [],
     structured_output: nil,
     messages: [],
     healed_tool_call_ids: [],
@@ -68,6 +74,7 @@ class Riffer::Agent::Response
     @outcome = outcome
     @tripwire = tripwire
     @modifications = modifications
+    @reasoning = reasoning
     @structured_output = structured_output
     @messages = messages
     @healed_tool_call_ids = healed_tool_call_ids

data/lib/riffer/agent/run.rb

@@ -10,7 +10,7 @@ module Riffer::Agent::Run
   # for prompt/files semantics.
   #
   #--
-  #: (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Riffer::Agent::Response
+  #: (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Riffer::Agent::Response
   def generate(agent:, prompt: nil, files: nil, tags: {})
     append_user_message(agent, prompt, files: files)
     run_loop(agent, tags: tags)
@@ -20,7 +20,7 @@ module Riffer::Agent::Run
   # for prompt/files semantics.
   #
   #--
-  #: (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Enumerator[Riffer::StreamEvents::Base, Riffer::Agent::Response]
+  #: (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Enumerator[Riffer::StreamEvents::Base, Riffer::Agent::Response]
   def stream(agent:, prompt: nil, files: nil, tags: {})
     append_user_message(agent, prompt, files: files)
     # The enumerator body runs in its own fiber, where the fiber-local OTEL
@@ -36,16 +36,17 @@ module Riffer::Agent::Run
   private
 
   # Both +generate+ and +stream+ funnel here, so this is the single place raw
-  # +tags+ are normalized. The clean <tt>String => String</tt> map is then
+  # +tags+ are normalized and merged over the default tags (a caller tag wins
+  # on a shared key). The clean <tt>String => String</tt> map is then
   # threaded to every span builder in the run as +riffer.tag.*+ and to each
   # provider call (via +merged_model_options+) for native request-metadata
   # mapping.
   #--
   #: (Riffer::Agent, ?tags: Hash[(String | Symbol), untyped]?, ?stream_yielder: Enumerator::Yielder?) -> Riffer::Agent::Response
   def run_loop(agent, tags: {}, stream_yielder: nil)
-    tags = normalize_tags(tags)
+    tags = default_tags(agent).merge(normalize_tags(tags))
     Riffer::Tracing.in_span(
-      "invoke_agent #{agent.class.identifier}",
+      "invoke_agent #{agent.identifier}",
       attributes: run_span_attributes(agent, tags),
       kind: :internal,
     ) do |span|
@@ -153,6 +154,7 @@ module Riffer::Agent::Run
   def accumulate_streamed_response(agent, stream_yielder, tags = {})
     accumulated_content = +""
     accumulated_tool_calls = [] #: Array[Riffer::Messages::Assistant::ToolCall]
+    accumulated_reasoning = [] #: Array[Riffer::Messages::Assistant::ReasoningPart]
     accumulated_token_usage = nil #: Riffer::Providers::TokenUsage?
     accumulated_finish_reason = nil #: Symbol?
     accumulated_finish_reason_raw = nil #: String?
@@ -175,6 +177,8 @@ module Riffer::Agent::Run
           name: event.name,
           arguments: event.arguments,
         )
+      when Riffer::StreamEvents::ReasoningDone
+        accumulated_reasoning << event.part
       when Riffer::StreamEvents::TokenUsageDone
         accumulated_token_usage = event.token_usage
       when Riffer::StreamEvents::FinishReasonDone
@@ -186,6 +190,7 @@ module Riffer::Agent::Run
     Riffer::Messages::Assistant.new(
       accumulated_content,
       tool_calls: accumulated_tool_calls,
+      reasoning: accumulated_reasoning,
       token_usage: accumulated_token_usage,
       finish_reason: accumulated_finish_reason,
       finish_reason_raw: accumulated_finish_reason_raw,
@@ -228,6 +233,7 @@ module Riffer::Agent::Run
       message&.content || "",
       outcome: final_outcome(message, result, interrupted: interrupted, interrupt_reason: interrupt_reason),
       modifications: all_modifications,
+      reasoning: message&.reasoning || [],
       structured_output: result&.object,
       **extra,
     )
@@ -381,6 +387,13 @@ module Riffer::Agent::Run
     opts
   end
 
+  # The tags riffer adds to every run, identifying the agent it's on behalf of.
+  #--
+  #: (Riffer::Agent) -> Hash[String, String]
+  def default_tags(agent)
+    { "kind" => "agent", "agent" => agent.identifier }
+  end
+
   #--
   #: (
   #    Riffer::Agent,
@@ -388,6 +401,7 @@ module Riffer::Agent::Run
   #    outcome: Riffer::Agent::Outcome,
   #    ?tripwire: Riffer::Guardrails::Tripwire?,
   #    ?modifications: Array[Riffer::Guardrails::Modification],
+  #    ?reasoning: Array[Riffer::Messages::Assistant::ReasoningPart],
   #    ?structured_output: Hash[Symbol, untyped]?,
   #    ?healed_tool_call_ids: Array[String],
   #    ?token_usage: Riffer::Providers::TokenUsage?,
@@ -399,6 +413,7 @@ module Riffer::Agent::Run
     outcome:,
     tripwire: nil,
     modifications: [],
+    reasoning: [],
     structured_output: nil,
     healed_tool_call_ids: [],
     token_usage: nil,
@@ -410,6 +425,7 @@ module Riffer::Agent::Run
       outcome: outcome,
       tripwire: tripwire,
       modifications: modifications,
+      reasoning: reasoning,
       structured_output: structured_output,
       messages: messages.frozen? ? messages : messages.dup.freeze,
       healed_tool_call_ids: healed_tool_call_ids,
@@ -421,12 +437,12 @@ module Riffer::Agent::Run
   # Raises when +files+ are supplied without a +prompt+ — the provider needs
   # text to anchor the attachments.
   #--
-  #: (Riffer::Agent, String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?) -> void
+  #: (Riffer::Agent, String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?) -> void
   def append_user_message(agent, prompt, files: nil)
     raise Riffer::ArgumentError, "files: requires a prompt" if files && !files.empty? && prompt.nil?
     return unless prompt
 
-    file_parts = (files || []).map { |f| Riffer::Messages::FilePart.from_hash(f) }
+    file_parts = (files || []).map { |f| Riffer::Messages::User::FilePart.from_hash(f) }
     agent.session.add(Riffer::Messages::User.new(prompt, files: file_parts), silent: true)
   end
 
@@ -451,7 +467,7 @@ module Riffer::Agent::Run
   def run_span_attributes(agent, tags = {})
     {
       "gen_ai.operation.name" => "invoke_agent",
-      "gen_ai.agent.name" => agent.class.identifier,
+      "gen_ai.agent.name" => agent.identifier,
       "gen_ai.provider.name" => agent.provider.class.semconv_provider_name,
       "gen_ai.request.model" => agent.model_name,
     }.merge(tag_attributes(tags))
@@ -461,7 +477,6 @@ module Riffer::Agent::Run
   #: (Hash[(String | Symbol), untyped]?) -> Hash[String, String]
   def normalize_tags(tags)
     return {} if tags.nil?
-    raise Riffer::ArgumentError, "tags: must be a Hash, got #{tags.class}" unless tags.is_a?(Hash)
 
     result = {} #: Hash[String, String]
     tags.each do |key, value|

data/lib/riffer/agent/session.rb

@@ -18,7 +18,7 @@ class Riffer::Agent::Session
   # @rbs @callbacks: Array[^(Riffer::Messages::Base) -> void]
 
   # The message history.
-  attr_reader :messages #: Array[Riffer::Messages::Base]
+  attr_reader :messages #: Array[Riffer::Messages::Base] # @dynamic messages
 
   #--
   #: (?messages: Array[Riffer::Messages::Base]) -> void
@@ -201,6 +201,7 @@ class Riffer::Agent::Session
         attrs.fetch(:content, old.content),
         id: attrs.fetch(:id, old.id),
         tool_calls: attrs.fetch(:tool_calls, old.tool_calls),
+        reasoning: attrs.fetch(:reasoning, old.reasoning),
         token_usage: attrs.fetch(:token_usage, old.token_usage),
         structured_output: attrs.fetch(:structured_output, old.structured_output),
         finish_reason: attrs.fetch(:finish_reason, old.finish_reason),

data/lib/riffer/agent/structured_output/result.rb

@@ -4,10 +4,10 @@
 # Wraps the result of structured output parsing and validation.
 class Riffer::Agent::StructuredOutput::Result
   # The validated object, or +nil+ on failure.
-  attr_reader :object #: Hash[Symbol, untyped]?
+  attr_reader :object #: Hash[Symbol, untyped]? # @dynamic object
 
   # The error message, or +nil+ on success.
-  attr_reader :error #: String?
+  attr_reader :error #: String? # @dynamic error
 
   #--
   #: (?object: Hash[Symbol, untyped]?, ?error: String?) -> void

data/lib/riffer/agent/structured_output.rb

@@ -7,7 +7,7 @@ require "json"
 # schema.
 class Riffer::Agent::StructuredOutput
   # The schema parameters.
-  attr_reader :params #: Riffer::Params
+  attr_reader :params #: Riffer::Params # @dynamic params
 
   #--
   #: (Riffer::Params) -> void

data/lib/riffer/agent.rb

@@ -28,6 +28,19 @@ class Riffer::Agent
     @config ||= Riffer::Agent::Config.new
   end
 
+  # +identifier+ is cleared because it is configuration here but identity on the
+  # subclass; two classes claiming one raise Riffer::DuplicateIdentifierError at
+  # the next registry lookup.
+  #--
+  #: (Class) -> void
+  def self.inherited(subclass)
+    super
+    copy = config.dup
+    copy.identifier = nil
+    subclass.instance_variable_set(:@config, copy)
+  end
+  private_class_method :inherited
+
   # Gets or sets the agent identifier.
   #
   #--
@@ -148,14 +161,14 @@ class 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
+  #: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?, ?context: Hash[Symbol, untyped]?, ?tags: Hash[(String | Symbol), untyped]) -> Riffer::Agent::Response
   def self.generate(prompt = nil, files: nil, context: nil, tags: {})
     new(context: context).generate(prompt, files: files, tags: tags)
   end
 
   # Streams 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]) -> Enumerator[Riffer::StreamEvents::Base, Riffer::Agent::Response]
+  #: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?, ?context: Hash[Symbol, untyped]?, ?tags: Hash[(String | Symbol), untyped]) -> Enumerator[Riffer::StreamEvents::Base, Riffer::Agent::Response]
   def self.stream(prompt = nil, files: nil, context: nil, tags: {})
     new(context: context).stream(prompt, files: files, tags: tags)
   end
@@ -214,44 +227,44 @@ class Riffer::Agent
   end
 
   # The conversation handle.
-  attr_reader :session #: Riffer::Agent::Session
+  attr_reader :session #: Riffer::Agent::Session # @dynamic session
 
   # The per-instance Riffer::Agent::Config.
-  attr_reader :config #: Riffer::Agent::Config
+  attr_reader :config #: Riffer::Agent::Config # @dynamic config
 
   # The system message built from the configured +instructions+, or +nil+ when
   # none are configured.
-  attr_reader :instruction_message #: Riffer::Messages::System?
+  attr_reader :instruction_message #: Riffer::Messages::System? # @dynamic instruction_message
 
   # The system message describing the configured skills catalog, or +nil+ when
   # skills are unconfigured or the catalog is empty.
-  attr_reader :skills_message #: Riffer::Messages::System?
+  attr_reader :skills_message #: Riffer::Messages::System? # @dynamic skills_message
 
   # The mutable runtime context shared with every +Riffer::Agent::Run+ this
   # agent executes and threaded through all Proc-based settings.
-  attr_reader :context #: Riffer::Agent::Context
+  attr_reader :context #: Riffer::Agent::Context # @dynamic context
 
   # The resolved provider name (the part before "/" in the model string),
   # e.g. +"openai"+.
-  attr_reader :provider_name #: String
+  attr_reader :provider_name #: String # @dynamic provider_name
 
   # The resolved model name (the part after "/" in the model string), used as
   # the model argument on every LLM call.
-  attr_reader :model_name #: String
+  attr_reader :model_name #: String # @dynamic model_name
 
   # The provider client. Public so tests can pre-queue responses on
   # +Riffer::Providers::Mock+ before calling +#generate+.
-  attr_reader :provider #: Riffer::Providers::Base
+  attr_reader :provider #: Riffer::Providers::Base # @dynamic provider
 
   # The +Riffer::Agent::StructuredOutput+ wrapping the configured schema, or
   # +nil+ when not configured.
-  attr_reader :structured_output #: Riffer::Agent::StructuredOutput?
+  attr_reader :structured_output #: Riffer::Agent::StructuredOutput? # @dynamic structured_output
 
   # The tool classes the LLM sees on every call this agent makes.
-  attr_reader :tools #: Array[singleton(Riffer::Tool)]
+  attr_reader :tools #: Array[singleton(Riffer::Tool)] # @dynamic tools
 
   # The tool runtime instance used to execute tool calls.
-  attr_reader :tool_runtime #: Riffer::Tools::Runtime
+  attr_reader :tool_runtime #: Riffer::Tools::Runtime # @dynamic tool_runtime
 
   # Initializes a new agent.
   #
@@ -284,6 +297,16 @@ class Riffer::Agent
     @session.set(Riffer::Agent::Session::Repair.prune_orphans(@session.messages))
   end
 
+  # The identifier for this agent: the instance config's identifier when set
+  # (e.g. an agent restored with +Riffer::Agent.from_h+), otherwise the class
+  # identifier.
+  #
+  #--
+  #: () -> String
+  def identifier
+    config.identifier || self.class.identifier
+  end
+
   # Generates a response from the agent.
   #
   # With +prompt+, a new user message is appended (silently — +on_message+ does
@@ -296,10 +319,11 @@ class Riffer::Agent
   # are stamped as +riffer.tag.*+ on every span the call emits. See
   # +docs/AGENTS.md+ for the per-provider mapping. The reserved key
   # +user_id+ also maps to the provider's native user identifier where one
-  # exists.
+  # exists. Riffer adds the default tags +kind+ (+"agent"+) and +agent+ (the
+  # agent identifier); a caller tag with the same key wins.
   #
   #--
-  #: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Riffer::Agent::Response
+  #: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Riffer::Agent::Response
   def generate(prompt = nil, files: nil, tags: {})
     Riffer::Agent::Run.generate(agent: self, prompt: prompt, files: files, tags: tags)
   end
@@ -311,7 +335,7 @@ class Riffer::Agent
   # Raises Riffer::ArgumentError if structured output is configured.
   #
   #--
-  #: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Enumerator[Riffer::StreamEvents::Base, Riffer::Agent::Response]
+  #: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Enumerator[Riffer::StreamEvents::Base, Riffer::Agent::Response]
   def stream(prompt = nil, files: nil, tags: {})
     if @structured_output
       raise Riffer::ArgumentError,

data/lib/riffer/config.rb

@@ -16,11 +16,11 @@ class Riffer::Config
   class Skills
     # The tool class the LLM calls to activate a skill; defaults to
     # <tt>Riffer::Skills::ActivateTool</tt>.
-    attr_reader :default_activate_tool #: singleton(Riffer::Tool)
+    attr_reader :default_activate_tool #: singleton(Riffer::Tool) # @dynamic default_activate_tool
 
     # Default skills backend for agents that declare a +skills+ block without
     # one; defaults to +nil+.
-    attr_reader :default_backend #: (Riffer::Skills::Backend | Proc)?
+    attr_reader :default_backend #: (Riffer::Skills::Backend | Proc)? # @dynamic default_backend
 
     #--
     #: () -> void
@@ -61,17 +61,17 @@ class Riffer::Config
   class Tracing
     # Whether riffer emits OTEL spans; defaults to +true+, a no-op until a
     # host wires an OTEL SDK.
-    attr_reader :enabled #: bool
+    attr_reader :enabled #: bool # @dynamic enabled
 
     # Whether LLM-call spans capture full message content
     # (<tt>gen_ai.input.messages</tt>, <tt>gen_ai.output.messages</tt>,
     # <tt>gen_ai.system_instructions</tt>); defaults to +false+ — message
     # content routinely carries sensitive data.
-    attr_reader :capture_messages #: bool
+    attr_reader :capture_messages #: bool # @dynamic capture_messages
 
     # The backend riffer routes spans through; defaults to +nil+, a no-op.
     # Riffer auto-detects no backend; assigning one is opt-in.
-    attr_reader :backend #: untyped
+    attr_reader :backend #: untyped # @dynamic backend
 
     #--
     #: () -> void
@@ -115,20 +115,20 @@ class Riffer::Config
     end
   end
 
-  # File-attachment-download policy for +Riffer::Messages::FilePart+ URL sources
+  # File-attachment-download policy for +Riffer::Messages::User::FilePart+ URL sources
   class Files
     # Allow file attachments to be downloaded to send to providers.
-    attr_reader :allow_downloads #: bool
+    attr_reader :allow_downloads #: bool # @dynamic allow_downloads
     # Maximum file size to download before failing.
-    attr_reader :max_bytes #: Integer
+    attr_reader :max_bytes #: Integer # @dynamic max_bytes
     # Maximum amount of time to spend downloading a file before failing.
-    attr_reader :timeout #: Integer
+    attr_reader :timeout #: Integer # @dynamic timeout
     # Maximum number of files to include in an individual message.
-    attr_reader :max_per_message #: Integer?
+    attr_reader :max_per_message #: Integer? # @dynamic max_per_message
     # Execution pattern for downloading files.
-    attr_reader :runner #: Riffer::Runner
+    attr_reader :runner #: Riffer::Runner # @dynamic runner
     # The object used to fetch a URL source's bytes
-    attr_reader :downloader #: untyped
+    attr_reader :downloader #: untyped # @dynamic downloader
 
     #--
     #: () -> void
@@ -215,16 +215,16 @@ class Riffer::Config
     # and +cache_write+ fall back to the +input+ rate when unset.
     class Rates
       # Input rate per million tokens.
-      attr_reader :input #: Float
+      attr_reader :input #: Float # @dynamic input
 
       # Output rate per million tokens.
-      attr_reader :output #: Float
+      attr_reader :output #: Float # @dynamic output
 
       # Cache-read rate per million tokens.
-      attr_reader :cache_read #: Float?
+      attr_reader :cache_read #: Float? # @dynamic cache_read
 
       # Cache-write rate per million tokens.
-      attr_reader :cache_write #: Float?
+      attr_reader :cache_write #: Float? # @dynamic cache_write
 
       #--
       #: (input: Float, output: Float, ?cache_read: Float?, ?cache_write: Float?) -> void
@@ -329,34 +329,34 @@ class Riffer::Config
   VALID_MESSAGE_ID_STRATEGIES = %i[none uuid uuidv7].freeze
 
   # Amazon Bedrock configuration.
-  attr_reader :amazon_bedrock #: Riffer::Config::AmazonBedrock
+  attr_reader :amazon_bedrock #: Riffer::Config::AmazonBedrock # @dynamic amazon_bedrock
 
   # Anthropic configuration.
-  attr_reader :anthropic #: Riffer::Config::Anthropic
+  attr_reader :anthropic #: Riffer::Config::Anthropic # @dynamic anthropic
 
   # Azure OpenAI configuration.
-  attr_reader :azure_openai #: Riffer::Config::AzureOpenAI
+  attr_reader :azure_openai #: Riffer::Config::AzureOpenAI # @dynamic azure_openai
 
   # Google Gemini configuration.
-  attr_reader :gemini #: Riffer::Config::Gemini
+  attr_reader :gemini #: Riffer::Config::Gemini # @dynamic gemini
 
   # OpenAI configuration.
-  attr_reader :openai #: Riffer::Config::OpenAI
+  attr_reader :openai #: Riffer::Config::OpenAI # @dynamic openai
 
   # OpenRouter configuration.
-  attr_reader :openrouter #: Riffer::Config::OpenRouter
+  attr_reader :openrouter #: Riffer::Config::OpenRouter # @dynamic openrouter
 
   # Evals configuration.
-  attr_reader :evals #: Riffer::Config::Evals
+  attr_reader :evals #: Riffer::Config::Evals # @dynamic evals
 
   # MCP configuration. +credentials+ is an optional Proc returning per-run
   # +tools/call+ headers (or +nil+ to deny); +discovery_runner+ runs tool
   # discovery.
-  attr_reader :mcp #: Riffer::Config::Mcp
+  attr_reader :mcp #: Riffer::Config::Mcp # @dynamic mcp
 
   # Global tool runtime configuration (experimental); defaults to
   # <tt>Riffer::Tools::Runtime::Inline.new</tt>.
-  attr_reader :tool_runtime #: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)
+  attr_reader :tool_runtime #: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc) # @dynamic tool_runtime
 
   # Sets the global tool runtime. Raises Riffer::ArgumentError on an invalid
   # value.
@@ -374,20 +374,20 @@ class Riffer::Config
   end
 
   # Skills-related global configuration.
-  attr_reader :skills #: Riffer::Config::Skills
+  attr_reader :skills #: Riffer::Config::Skills # @dynamic skills
 
   # Tracing-related global configuration.
-  attr_reader :tracing #: Riffer::Config::Tracing
+  attr_reader :tracing #: Riffer::Config::Tracing # @dynamic tracing
 
-  attr_reader :files #: Riffer::Config::Files
+  attr_reader :files #: Riffer::Config::Files # @dynamic files
 
   # Consumer-configured per-model token pricing.
-  attr_reader :pricing #: Riffer::Config::Pricing
+  attr_reader :pricing #: Riffer::Config::Pricing # @dynamic pricing
 
   # Strategy for auto-generating message ids: +:none+ (default), +:uuid+, or
   # +:uuidv7+. When not +:none+, messages get an +id+ at construction, and
   # seeded messages passed to +Riffer::Agent#generate+ must carry their own.
-  attr_reader :message_id_strategy #: Symbol
+  attr_reader :message_id_strategy #: Symbol # @dynamic message_id_strategy
 
   # Sets the message id strategy. Raises Riffer::ArgumentError unless the value
   # is +:none+, +:uuid+, or +:uuidv7+.
@@ -404,7 +404,7 @@ class Riffer::Config
   # Experimental: when +true+, riffer maintains the +tool_use+ ↔ +tool_result+
   # invariant itself — stripping orphaned exchanges and filling interrupted
   # ones. Defaults to +false+; the surface may change without notice.
-  attr_reader :experimental_history_healing #: bool
+  attr_reader :experimental_history_healing #: bool # @dynamic experimental_history_healing
 
   # Sets the +experimental_history_healing+ flag, coercing boolean-ish values so
   # an env-var +"false"+ (truthy in Ruby) doesn't silently enable healing.