riffer 0.47.0 → 0.47.2

data/lib/riffer/guardrails/runner.rb

@@ -5,16 +5,16 @@
 # any blocks, execution stops and a tripwire is returned.
 class Riffer::Guardrails::Runner
   # The guardrail configs to execute.
-  attr_reader :guardrail_configs #: Array[Hash[Symbol, untyped]]
+  attr_reader :guardrail_configs #: Array[Hash[Symbol, untyped]] # @dynamic guardrail_configs
 
   # The execution phase (:before or :after).
-  attr_reader :phase #: Symbol
+  attr_reader :phase #: Symbol # @dynamic phase
 
   # The context passed to guardrails.
-  attr_reader :context #: untyped
+  attr_reader :context #: untyped # @dynamic context
 
   # The normalized per-call tags, stamped as +riffer.tag.*+ on guardrail spans.
-  attr_reader :tags #: Hash[String, String]
+  attr_reader :tags #: Hash[String, String] # @dynamic tags
 
   #--
   #: (Array[Hash[Symbol, untyped]], phase: Symbol, ?context: untyped, ?tags: Hash[String, String]) -> void

data/lib/riffer/guardrails/tripwire.rb

@@ -6,16 +6,16 @@ class Riffer::Guardrails::Tripwire
   PHASES = Riffer::Guardrails::PHASES #: Array[Symbol]
 
   # The reason for blocking.
-  attr_reader :reason #: String
+  attr_reader :reason #: String # @dynamic reason
 
   # The guardrail class that triggered the block.
-  attr_reader :guardrail #: singleton(Riffer::Guardrail)
+  attr_reader :guardrail #: singleton(Riffer::Guardrail) # @dynamic guardrail
 
   # The phase when the block occurred (:before or :after).
-  attr_reader :phase #: Symbol
+  attr_reader :phase #: Symbol # @dynamic phase
 
   # Optional metadata about the block.
-  attr_reader :metadata #: Hash[Symbol, untyped]?
+  attr_reader :metadata #: Hash[Symbol, untyped]? # @dynamic metadata
 
   # Raises Riffer::ArgumentError if +phase+ is invalid.
   #--

data/lib/riffer/mcp/manifest.rb

@@ -6,20 +6,20 @@ require "uri"
 # Holds the configuration for a single MCP server.
 class Riffer::Mcp::Manifest
   # Identifier used as the registration key and generated-agent identifier.
-  attr_reader :name #: String
+  attr_reader :name #: String # @dynamic name
 
   # Tags for matching +use_mcp+.
-  attr_reader :tags #: Array[Symbol]
+  attr_reader :tags #: Array[Symbol] # @dynamic tags
 
   # HTTPS URL passed to the MCP transport.
-  attr_reader :endpoint #: String
+  attr_reader :endpoint #: String # @dynamic endpoint
 
   # Headers (or a Proc) resolved once when building the discovery client.
-  attr_reader :discovery_headers #: (Hash[String, untyped] | ::Proc)?
+  attr_reader :discovery_headers #: (Hash[String, untyped] | ::Proc)? # @dynamic discovery_headers
 
   # Optional hint (+:global+/+:tenant+/+:user+) for whether invocation
   # credentials depend on tenant/user keys in +context+.
-  attr_reader :credentials_scope #: Symbol?
+  attr_reader :credentials_scope #: Symbol? # @dynamic credentials_scope
 
   # Raises Riffer::ArgumentError unless +name+ is present and +endpoint+ is a
   # valid HTTPS URL.

data/lib/riffer/mcp/registration.rb

@@ -9,7 +9,7 @@ class Riffer::Mcp::Registration
   # @rbs @mutex: Thread::Mutex
 
   # The manifest that describes this server.
-  attr_reader :manifest #: Riffer::Mcp::Manifest
+  attr_reader :manifest #: Riffer::Mcp::Manifest # @dynamic manifest
 
   # Generated Riffer::Mcp::Tool subclasses.
   #

data/lib/riffer/mcp/search_tool.rb

@@ -8,7 +8,7 @@ class Riffer::Mcp::SearchTool < Riffer::Tool
   # Successful search response carrying the matched tool classes.
   class Result < Riffer::Tools::Response
     # Tool classes that matched the search query.
-    attr_reader :discovered_tools #: Array[singleton(Riffer::Tool)]
+    attr_reader :discovered_tools #: Array[singleton(Riffer::Tool)] # @dynamic discovered_tools
 
     #--
     #: (String, Array[singleton(Riffer::Tool)]) -> void

data/lib/riffer/messages/assistant.rb

@@ -7,21 +7,21 @@ class Riffer::Messages::Assistant < Riffer::Messages::Base
   ToolCall = Struct.new(:call_id, :name, :arguments)
 
   # Array of tool calls requested by the assistant.
-  attr_reader :tool_calls #: Array[Riffer::Messages::Assistant::ToolCall]
+  attr_reader :tool_calls #: Array[Riffer::Messages::Assistant::ToolCall] # @dynamic tool_calls
 
   # Token usage data for this response.
-  attr_reader :token_usage #: Riffer::Providers::TokenUsage?
+  attr_reader :token_usage #: Riffer::Providers::TokenUsage? # @dynamic token_usage
 
   # Parsed structured output hash, or nil when not applicable.
-  attr_reader :structured_output #: Hash[Symbol, untyped]?
+  attr_reader :structured_output #: Hash[Symbol, untyped]? # @dynamic structured_output
 
   # Normalized reason the provider finished this response, when reported (see
   # <tt>Riffer::Providers::FinishReason::VALUES</tt>).
-  attr_reader :finish_reason #: Symbol?
+  attr_reader :finish_reason #: Symbol? # @dynamic finish_reason
 
   # The provider's raw finish-reason value behind +finish_reason+, when one
   # exists on the wire.
-  attr_reader :finish_reason_raw #: String?
+  attr_reader :finish_reason_raw #: String? # @dynamic finish_reason_raw
 
   # Raises Riffer::ArgumentError when +finish_reason+ is outside the
   # normalized vocabulary.

data/lib/riffer/messages/base.rb

@@ -12,8 +12,6 @@ class Riffer::Messages::Base
   def self.from_hash(msg)
     return msg if msg.is_a?(Riffer::Messages::Base)
 
-    raise Riffer::ArgumentError, "Message must be a Hash or Message object, got #{msg.class}" unless msg.is_a?(Hash)
-
     raise Riffer::ArgumentError, "Message hash must include a 'role' key" if msg[:role].nil? || msg[:role].empty?
 
     case msg[:role].to_sym
@@ -42,10 +40,10 @@ class Riffer::Messages::Base
   end
 
   # The message content.
-  attr_reader :content #: String
+  attr_reader :content #: String # @dynamic content
 
   # The message id, or nil when +Riffer.config.message_id_strategy+ is +:none+.
-  attr_reader :id #: String?
+  attr_reader :id #: String? # @dynamic id
 
   #--
   #: (String, ?id: String?) -> void

data/lib/riffer/messages/file_part.rb

@@ -29,13 +29,13 @@ class Riffer::Messages::FilePart
   SHA256_PATTERN = /\A[0-9a-f]{64}\z/i #: Regexp
 
   # The MIME type of the file.
-  attr_reader :media_type #: String
+  attr_reader :media_type #: String # @dynamic media_type
 
   # The filename, if available.
-  attr_reader :filename #: String?
+  attr_reader :filename #: String? # @dynamic filename
 
   # The expected SHA-256 of the file contents, if the caller supplied one.
-  attr_reader :sha256 #: String?
+  attr_reader :sha256 #: String? # @dynamic sha256
 
   # Raises Riffer::ArgumentError unless +data+ or +url+ is given and
   # +media_type+ is supported.
@@ -66,8 +66,7 @@ class Riffer::Messages::FilePart
   def self.from_url(url, media_type: nil, filename: nil, sha256: nil)
     unless media_type
       ext = ::File.extname(URI.parse(url).path.to_s).downcase
-      media_type = MEDIA_TYPES[ext]
-      raise Riffer::ArgumentError, "Cannot detect media type from URL; provide media_type explicitly" unless media_type
+      media_type = MEDIA_TYPES.fetch(ext) { raise Riffer::ArgumentError, "Cannot detect media type from URL; provide media_type explicitly" }
     end
 
     new(url: url, media_type: media_type, filename: filename, sha256: sha256)
@@ -81,8 +80,6 @@ class Riffer::Messages::FilePart
   def self.from_hash(file)
     return file if file.is_a?(Riffer::Messages::FilePart)
 
-    raise Riffer::ArgumentError, "File must be a Hash or FilePart object, got #{file.class}" unless file.is_a?(Hash)
-
     url = file[:url]
     data = file[:data]
     media_type = file[:media_type]

data/lib/riffer/messages/tool.rb

@@ -4,17 +4,17 @@
 # Represents a tool execution result in a conversation.
 class Riffer::Messages::Tool < Riffer::Messages::Base
   # The ID of the tool call this result responds to.
-  attr_reader :tool_call_id #: String
+  attr_reader :tool_call_id #: String # @dynamic tool_call_id
 
   # The name of the tool that was called.
-  attr_reader :name #: String
+  attr_reader :name #: String # @dynamic name
 
   # The error message if the tool execution failed.
-  attr_reader :error #: String?
+  attr_reader :error #: String? # @dynamic error
 
   # The type of error (:unknown_tool, :validation_error, :execution_error,
   # :timeout_error, :unhandled_error).
-  attr_reader :error_type #: Symbol?
+  attr_reader :error_type #: Symbol? # @dynamic error_type
 
   #--
   #: (String, tool_call_id: String, name: String, ?id: String?, ?error: String?, ?error_type: Symbol?) -> void

data/lib/riffer/messages/user.rb

@@ -4,7 +4,7 @@
 # Represents a user message in a conversation.
 class Riffer::Messages::User < Riffer::Messages::Base
   # File attachments for this message.
-  attr_reader :files #: Array[Riffer::Messages::FilePart]
+  attr_reader :files #: Array[Riffer::Messages::FilePart] # @dynamic files
 
   #--
   #: (String, ?id: String?, ?files: Array[Riffer::Messages::FilePart]) -> void

data/lib/riffer/params/param.rb

@@ -31,28 +31,28 @@ class Riffer::Params::Param
   }.freeze #: Hash[String, Module]
 
   # The parameter name.
-  attr_reader :name #: Symbol
+  attr_reader :name #: Symbol # @dynamic name
 
   # The Ruby type.
-  attr_reader :type #: Module
+  attr_reader :type #: Module # @dynamic type
 
   # Whether the parameter is required.
-  attr_reader :required #: bool
+  attr_reader :required #: bool # @dynamic required
 
   # The parameter description, if any.
-  attr_reader :description #: String?
+  attr_reader :description #: String? # @dynamic description
 
   # Allowed values, if constrained.
-  attr_reader :enum #: Array[untyped]?
+  attr_reader :enum #: Array[untyped]? # @dynamic enum
 
   # The default value, if any.
-  attr_reader :default #: untyped
+  attr_reader :default #: untyped # @dynamic default
 
   # Element type for a typed array (+of:+).
-  attr_reader :item_type #: Module?
+  attr_reader :item_type #: Module? # @dynamic item_type
 
   # Nested Params for object / array-of-object types.
-  attr_reader :nested_params #: Riffer::Params?
+  attr_reader :nested_params #: Riffer::Params? # @dynamic nested_params
 
   # Reconstructs a Param from a single JSON Schema property. Raises
   # Riffer::ArgumentError on a type outside the Params-expressible subset.
@@ -140,10 +140,14 @@ class Riffer::Params::Param
   # params are made nullable (<tt>["type", "null"]</tt>) so strict providers
   # distinguish absent from present; optional params with an +enum+ use +anyOf+
   # instead, since providers like Anthropic reject
-  # <tt>{"type": ["string", "null"], "enum": [...]}</tt>.
+  # <tt>{"type": ["string", "null"], "enum": [...]}</tt>. Raises
+  # Riffer::ArgumentError when +strict+ and a Hash param has no block or an
+  # Array param has neither a block nor <tt>of:</tt>, since strict providers
+  # reject objects without +properties+ and arrays without +items+.
   #--
   #: (?strict: bool) -> Hash[Symbol, untyped]
   def to_json_schema(strict: false)
+    validate_strict_shape! if strict
     nullable = strict && !required
 
     if nullable && enum
@@ -168,9 +172,24 @@ class Riffer::Params::Param
     elsif self.type == Array && item_type
       schema[:items] = { type: TYPE_MAPPINGS[item_type] }
     elsif self.type == Hash && nested_params
-      schema.merge!(nested_params.to_json_schema(strict: strict))
+      # The nested schema carries its own type: "object", which would clobber a nullable union.
+      schema.merge!(nested_params.to_json_schema(strict: strict).except(:type))
     end
 
     schema
   end
+
+  private
+
+  #--
+  #: () -> void
+  def validate_strict_shape!
+    if type == Hash && nested_params.nil?
+      raise Riffer::ArgumentError,
+            "#{name}: a Hash param requires a block defining its properties under strict schemas"
+    elsif type == Array && nested_params.nil? && item_type.nil?
+      raise Riffer::ArgumentError,
+            "#{name}: an Array param requires a block or of: defining its items under strict schemas"
+    end
+  end
 end

data/lib/riffer/params.rb

@@ -11,7 +11,7 @@
 #
 class Riffer::Params
   # The defined parameters.
-  attr_reader :parameters #: Array[Riffer::Params::Param]
+  attr_reader :parameters #: Array[Riffer::Params::Param] # @dynamic parameters
 
   #--
   #: () -> void
@@ -128,6 +128,8 @@ class Riffer::Params
   # Converts all parameters to JSON Schema format. When +strict+ is true, every
   # property is listed in +required+ and optional ones are made nullable
   # instead, satisfying providers that enforce strict structured output schemas.
+  # Raises Riffer::ArgumentError when +strict+ and a Hash param (at any depth)
+  # has no block or an Array param has neither a block nor <tt>of:</tt>.
   #--
   #: (?strict: bool) -> Hash[Symbol, untyped]
   def to_json_schema(strict: false)

data/lib/riffer/providers/amazon_bedrock.rb

@@ -154,7 +154,7 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   #: (untyped) -> Hash[Symbol, untyped]
   def build_cache_point(cache_control)
     point = { type: "default" } #: Hash[Symbol, untyped]
-    ttl = cache_control.is_a?(Hash) ? cache_control[:ttl] : nil
+    ttl = cache_control[:ttl] if cache_control.is_a?(Hash)
     point[:ttl] = ttl if ttl
     point
   end
@@ -252,6 +252,8 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
       tool_call: nil,
     } #: Hash[Symbol, untyped]
 
+    stream_completed = false
+
     client.converse_stream(**params) do |stream|
       stream.on_event do |event|
         case event
@@ -264,20 +266,45 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
           handle_content_block_stop_text_delta(event, state: current_state, yielder: yielder) if current_state[:text]
           handle_content_block_stop_tool_use(event, state: current_state, yielder: yielder) if current_state[:tool_call]
         when Aws::BedrockRuntime::Types::MessageStopEvent
+          stream_completed = true
           yield_finish_reason(yielder, build_finish_reason(event.stop_reason))
         when Aws::BedrockRuntime::Types::ConverseStreamMetadataEvent
           handle_metadata_usage(event, state: current_state, yielder: yielder) if event.usage
+        when Aws::Errors::EventError
+          # The SDK turns an event-stream +:message-type: error+ frame into an
+          # EventError instance and hands it to this block as an event; it is
+          # never raised. Re-raise it here so the failure surfaces instead of
+          # truncating the stream.
+          raise_stream_event_error!(event)
         else
           raise_if_stream_exception!(event)
         end
       end
     end
+
+    return if stream_completed
+
+    raise Riffer::IncompleteStreamError, "Bedrock ConverseStream ended without a messageStop event"
+  end
+
+  # Re-raises an +Aws::Errors::EventError+ event with a message built from its
+  # error code and message. The SDK's own +#message+ is just the class name,
+  # so without this the failure would be unreadable.
+  #--
+  #: (untyped) -> void
+  def raise_stream_event_error!(event)
+    details = [event.error_code, event.error_message].compact.join(": ")
+    details = "Bedrock ConverseStream error event" if details.empty?
+
+    raise event.exception(details)
   end
 
   # Re-raises a Bedrock stream-exception event as the matching
   # +Aws::BedrockRuntime::Errors+ class. ConverseStream delivers API errors on
   # the same channel as content, so without this a mid-stream failure would
-  # silently end the stream with no content.
+  # silently end the stream with no content. Non-exception events that we do
+  # not consume (including the SDK's +:unknown_event+ struct) are ignored for
+  # forward compatibility.
   #--
   #: (untyped) -> void
   def raise_if_stream_exception!(event)

data/lib/riffer/providers/anthropic.rb

@@ -211,6 +211,8 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
       web_search_query: nil,
     } #: Hash[Symbol, untyped]
 
+    stream_completed = false
+
     # 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(
@@ -247,6 +249,7 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
             handle_content_block_stop_web_search_result(event, state: current_state, yielder: yielder)
           end
         when ::Anthropic::Helpers::Streaming::MessageStopEvent
+          stream_completed = true
           handle_message_stop(event, accumulated_message: stream.accumulated_message, yielder: yielder)
         end
       end
@@ -256,6 +259,10 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
       # socket leaks until GC. close is idempotent and a no-op after EOF.
       stream.close
     end
+
+    return if stream_completed
+
+    raise Riffer::IncompleteStreamError, "Anthropic stream ended without a message_stop event"
   end
 
   #--

data/lib/riffer/providers/base.rb

@@ -30,10 +30,9 @@ 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
+    class_name = name or return "unknown"
 
     @semconv_provider_name ||= Riffer::Helpers::Identifier.derive(class_name.split("::").last)
   end

data/lib/riffer/providers/finish_reason.rb

@@ -8,10 +8,10 @@ class Riffer::Providers::FinishReason
   VALUES = %i[stop length tool_calls content_filter context_window malformed_output error other].freeze #: Array[Symbol]
 
   # The normalized reason.
-  attr_reader :reason #: Symbol
+  attr_reader :reason #: Symbol # @dynamic reason
 
   # The provider's raw finish-reason value, when one exists on the wire.
-  attr_reader :raw #: String?
+  attr_reader :raw #: String? # @dynamic raw
 
   # Raises Riffer::ArgumentError when +reason+ is outside VALUES.
   #--

data/lib/riffer/providers/mock.rb

@@ -25,7 +25,7 @@ class Riffer::Providers::Mock < Riffer::Providers::Base
   end
 
   # Array of recorded method calls for assertions.
-  attr_reader :calls #: Array[Hash[Symbol, untyped]]
+  attr_reader :calls #: Array[Hash[Symbol, untyped]] # @dynamic calls
 
   # +responses:+ pre-configures canned responses (same shape as
   # +#stub_response+) for standalone use; agent tests queue responses on

data/lib/riffer/providers/open_ai.rb

@@ -218,6 +218,8 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
       tool_info: {},
     } #: Hash[Symbol, untyped]
 
+    stream_completed = false
+
     stream = client.responses.stream(params)
     begin
       stream.each do |event|
@@ -247,6 +249,7 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
         when :"response.output_item.done"
           handle_output_item_done_web_search(event, yielder: yielder) if event.item&.type == :web_search_call
         when :"response.completed", :"response.incomplete", :"response.failed"
+          stream_completed = true
           handle_response_finished(event, state: current_state, yielder: yielder)
         end
       end
@@ -256,6 +259,11 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
       # socket leaks until GC. close is idempotent and a no-op after EOF.
       stream.close
     end
+
+    return if stream_completed
+
+    raise Riffer::IncompleteStreamError,
+          "OpenAI Responses stream ended without a response.completed, response.incomplete, or response.failed event"
   end
 
   #--

data/lib/riffer/providers/repository.rb

@@ -27,13 +27,9 @@ module Riffer::Providers::Repository
   #
   #   Riffer::Providers::Repository.register(:jane) { MyApp::JaneProvider }
   #
-  # Raises Riffer::ArgumentError when called without a block.
-  #
   #--
   #: ((String | Symbol)) { () -> singleton(Riffer::Providers::Base) } -> void
   def register(identifier, &factory)
-    raise Riffer::ArgumentError, "register requires a block returning a provider class" unless factory
-
     @registrations[identifier.to_sym] = factory
     @key_for = nil
   end

data/lib/riffer/providers/token_usage.rb

@@ -5,19 +5,19 @@
 # meaning for every provider.
 class Riffer::Providers::TokenUsage
   # Number of tokens entering the context window, including cache reads and writes.
-  attr_reader :input_tokens #: Integer
+  attr_reader :input_tokens #: Integer # @dynamic input_tokens
 
   # Number of tokens generated by the model, including reasoning/thinking tokens.
-  attr_reader :output_tokens #: Integer
+  attr_reader :output_tokens #: Integer # @dynamic output_tokens
 
   # Subset of +input_tokens+ written to the provider's prompt cache, when the provider reports it.
-  attr_reader :cache_write_tokens #: Integer?
+  attr_reader :cache_write_tokens #: Integer? # @dynamic cache_write_tokens
 
   # Subset of +input_tokens+ read from the provider's prompt cache, when the provider reports it.
-  attr_reader :cache_read_tokens #: Integer?
+  attr_reader :cache_read_tokens #: Integer? # @dynamic cache_read_tokens
 
   # Cost of the call, set when the model is priced. For observability, not billing.
-  attr_reader :cost #: Float?
+  attr_reader :cost #: Float? # @dynamic cost
 
   #--
   #: (input_tokens: Integer, output_tokens: Integer, ?cache_write_tokens: Integer?, ?cache_read_tokens: Integer?, ?cost: Float?) -> void

data/lib/riffer/skills/adapter.rb

@@ -7,7 +7,7 @@
 # for the rendered output.
 class Riffer::Skills::Adapter
   # The activation tool class for this adapter.
-  attr_reader :skill_activate_tool #: singleton(Riffer::Tool)
+  attr_reader :skill_activate_tool #: singleton(Riffer::Tool) # @dynamic skill_activate_tool
 
   #--
   #: (skill_activate_tool: singleton(Riffer::Tool)) -> void

data/lib/riffer/skills/context.rb

@@ -11,13 +11,13 @@ class Riffer::Skills::Context
   # @rbs @preactivated: Array[String]
 
   # Skill catalog indexed by name.
-  attr_reader :skills #: Hash[String, Riffer::Skills::Frontmatter]
+  attr_reader :skills #: Hash[String, Riffer::Skills::Frontmatter] # @dynamic skills
 
   # The skill adapter used for this context.
-  attr_reader :adapter #: Riffer::Skills::Adapter
+  attr_reader :adapter #: Riffer::Skills::Adapter # @dynamic adapter
 
   # Optional callback invoked when a skill is first activated.
-  attr_accessor :on_activate #: (^(String) -> void)?
+  attr_accessor :on_activate #: (^(String) -> void)? # @dynamic on_activate, on_activate=
 
   #--
   #: (backend: Riffer::Skills::Backend, skills: Hash[String, Riffer::Skills::Frontmatter], adapter: Riffer::Skills::Adapter) -> void
@@ -106,10 +106,7 @@ class Riffer::Skills::Context
   #--
   #: (String) -> bool
   def model_invocable?(name)
-    skill = skills[name]
-    return false unless skill
-
-    !skill.disable_model_invocation
+    skills.key?(name) && !skills.fetch(name).disable_model_invocation
   end
 
   # Returns whether any skill is available for the model to activate.

data/lib/riffer/skills/filesystem_backend.rb

@@ -53,8 +53,7 @@ class Riffer::Skills::FilesystemBackend < Riffer::Skills::Backend
   def read_skill(name)
     list_skills unless @skills_cache
     cache = @skills_cache #: Hash[String, String]
-    dir = cache[name]
-    raise Riffer::ArgumentError, "Skill not found: '#{name}'" unless dir
+    dir = cache.fetch(name) { raise Riffer::ArgumentError, "Skill not found: '#{name}'" }
 
     _, body = Riffer::Skills::Frontmatter.parse(File.read(File.join(dir, SKILL_FILENAME)))
     body

data/lib/riffer/skills/frontmatter.rb

@@ -13,19 +13,19 @@ class Riffer::Skills::Frontmatter
   MAX_DESCRIPTION_LENGTH = 1024 #: Integer
 
   # The skill name (1-64 chars, lowercase alphanumeric and hyphens).
-  attr_reader :name #: String
+  attr_reader :name #: String # @dynamic name
 
   # The skill description (1-1024 chars).
-  attr_reader :description #: String
+  attr_reader :description #: String # @dynamic description
 
   # Whether the skill opts out of model-driven activation. Hidden from the
   # catalog and rejected at model activation; still reachable via programmatic
   # activation.
-  attr_reader :disable_model_invocation #: bool
+  attr_reader :disable_model_invocation #: bool # @dynamic disable_model_invocation
 
   # Metadata from the spec's +metadata+ field plus any unrecognized top-level
   # keys.
-  attr_reader :metadata #: Hash[Symbol, untyped]
+  attr_reader :metadata #: Hash[Symbol, untyped] # @dynamic metadata
 
   # Parses a raw SKILL.md string into a +[Frontmatter, body]+ pair — public so
   # custom backends needn't reimplement parsing. Raises Riffer::ArgumentError

data/lib/riffer/skills/xml_adapter.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-require "cgi"
+require "cgi/escape"
 
 # Renders a skill catalog as XML for the system prompt, optimized for
 # Anthropic/Claude.

data/lib/riffer/stream_events/base.rb

@@ -4,7 +4,7 @@
 # Base class for all streaming events. Subclasses must implement +to_h+.
 class Riffer::StreamEvents::Base
   # The message role (typically :assistant).
-  attr_reader :role #: Symbol
+  attr_reader :role #: Symbol # @dynamic role
 
   #--
   #: (?role: Symbol) -> void

data/lib/riffer/stream_events/finish_reason_done.rb

@@ -5,10 +5,10 @@
 # stream; no ordering guarantee relative to TokenUsageDone.
 class Riffer::StreamEvents::FinishReasonDone < Riffer::StreamEvents::Base
   # The normalized finish reason (see <tt>Riffer::Providers::FinishReason::VALUES</tt>).
-  attr_reader :finish_reason #: Symbol
+  attr_reader :finish_reason #: Symbol # @dynamic finish_reason
 
   # The provider's raw finish-reason value, when one exists on the wire.
-  attr_reader :raw_finish_reason #: String?
+  attr_reader :raw_finish_reason #: String? # @dynamic raw_finish_reason
 
   # Raises Riffer::ArgumentError when +finish_reason+ is outside the
   # normalized vocabulary.

data/lib/riffer/stream_events/guardrail_modification.rb

@@ -4,7 +4,7 @@
 # Emitted when a guardrail transforms data during streaming.
 class Riffer::StreamEvents::GuardrailModification < Riffer::StreamEvents::Base
   # The modification record.
-  attr_reader :modification #: Riffer::Guardrails::Modification
+  attr_reader :modification #: Riffer::Guardrails::Modification # @dynamic modification
 
   #--
   #: (Riffer::Guardrails::Modification, ?role: Symbol) -> void

data/lib/riffer/stream_events/guardrail_tripwire.rb

@@ -4,7 +4,7 @@
 # Emitted when a guardrail blocks execution during streaming.
 class Riffer::StreamEvents::GuardrailTripwire < Riffer::StreamEvents::Base
   # The tripwire containing block details.
-  attr_reader :tripwire #: Riffer::Guardrails::Tripwire
+  attr_reader :tripwire #: Riffer::Guardrails::Tripwire # @dynamic tripwire
 
   #--
   #: (Riffer::Guardrails::Tripwire, ?role: Symbol) -> void

data/lib/riffer/stream_events/interrupt.rb

@@ -5,11 +5,11 @@
 # +:riffer_interrupt+.
 class Riffer::StreamEvents::Interrupt < Riffer::StreamEvents::Base
   # The reason provided with the interrupt, if any.
-  attr_reader :reason #: (String | Symbol)?
+  attr_reader :reason #: (String | Symbol)? # @dynamic reason
 
   # Call ids of tool_use blocks riffer filled with placeholder results when the
   # interrupt fired (only when 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
 
   #--
   #: (?reason: (String | Symbol)?, ?healed_tool_call_ids: Array[String]) -> void