riffer 0.28.0 → 0.29.0

data/lib/riffer/providers/open_ai.rb

@@ -36,9 +36,9 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
         summary: "auto"
       },
       **options.except(:reasoning, :tools, :structured_output, :web_search)
-    }
+    } #: Hash[Symbol, untyped]
 
-    openai_tools = []
+    openai_tools = [] #: Array[Hash[Symbol, untyped]]
     openai_tools.concat(tools.map { |t| convert_tool_to_openai_format(t) }) if tools && !tools.empty?
 
     if web_search
@@ -72,12 +72,12 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
   end
 
   #--
-  #: (OpenAI::Models::Responses::Response) -> Riffer::TokenUsage?
+  #: (OpenAI::Models::Responses::Response) -> Riffer::Providers::TokenUsage?
   def extract_token_usage(response)
     usage = response.usage
     return nil unless usage
 
-    Riffer::TokenUsage.new(
+    Riffer::Providers::TokenUsage.new(
       input_tokens: usage.input_tokens,
       output_tokens: usage.output_tokens
     )
@@ -89,10 +89,10 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
     text_content = ""
 
     response.output.each do |item|
-      if item.type == :message
-        text_block = item.content&.find { |c| c.type == :output_text }
-        text_content = text_block&.text || "" if text_block
-      end
+      next unless item.is_a?(::OpenAI::Models::Responses::ResponseOutputMessage)
+
+      text_block = item.content.find { |c| c.is_a?(::OpenAI::Models::Responses::ResponseOutputText) }
+      text_content = text_block.text if text_block.is_a?(::OpenAI::Models::Responses::ResponseOutputText)
     end
 
     text_content
@@ -101,16 +101,16 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
   #--
   #: (OpenAI::Models::Responses::Response) -> Array[Riffer::Messages::Assistant::ToolCall]
   def extract_tool_calls(response)
-    tool_calls = []
+    tool_calls = [] #: Array[Riffer::Messages::Assistant::ToolCall]
 
     response.output.each do |item|
-      if item.type == :function_call
-        tool_calls << Riffer::Messages::Assistant::ToolCall.new(
-          call_id: item.call_id,
-          name: decode_tool_name(item.name, tools: @current_tools),
-          arguments: item.arguments
-        )
-      end
+      next unless item.is_a?(::OpenAI::Models::Responses::ResponseFunctionToolCall)
+
+      tool_calls << Riffer::Messages::Assistant::ToolCall.new(
+        call_id: item.call_id,
+        name: decode_tool_name(item.name, tools: @current_tools),
+        arguments: item.arguments
+      )
     end
 
     tool_calls
@@ -121,7 +121,7 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
   def execute_stream(params, yielder)
     current_state = {
       tool_info: {}
-    }
+    } #: Hash[Symbol, untyped]
 
     stream = @client.responses.stream(params)
     begin
@@ -224,7 +224,7 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
     return unless usage
 
     yielder << Riffer::StreamEvents::TokenUsageDone.new(
-      token_usage: Riffer::TokenUsage.new(
+      token_usage: Riffer::Providers::TokenUsage.new(
         input_tokens: usage.input_tokens,
         output_tokens: usage.output_tokens
       )
@@ -242,11 +242,11 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
   def handle_output_item_done_web_search(event, yielder:)
     action = event.item.action
     case action
-    when OpenAI::Models::Responses::ResponseFunctionWebSearch::Action::OpenPage
+    when ::OpenAI::Models::Responses::ResponseFunctionWebSearch::Action::OpenPage
       # OpenPage carries a url but no query or sources, so it doesn't fit
       # WebSearchDone — emit as a status notification instead.
       yielder << Riffer::StreamEvents::WebSearchStatus.new("open_page", url: action.url)
-    when OpenAI::Models::Responses::ResponseFunctionWebSearch::Action::Search
+    when ::OpenAI::Models::Responses::ResponseFunctionWebSearch::Action::Search
       sources = (action.sources || []).map { |s| {title: nil, url: s.url} }
       yielder << Riffer::StreamEvents::WebSearchDone.new(action.query, sources: sources)
     end
@@ -275,6 +275,8 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
           call_id: message.tool_call_id,
           output: message.content
         }
+      else
+        raise Riffer::ArgumentError, "unsupported message type: #{message.class}"
       end
     end
   end
@@ -285,7 +287,7 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
     if message.tool_calls.empty?
       {role: "assistant", content: message.content}
     else
-      items = []
+      items = [] #: Array[Hash[Symbol, untyped]]
       items << {type: "message", role: "assistant", content: message.content} if message.content && !message.content.empty?
       message.tool_calls.each do |tc|
         items << {
@@ -300,7 +302,7 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
   end
 
   #--
-  #: (Riffer::FilePart) -> Hash[Symbol, untyped]
+  #: (Riffer::Messages::FilePart) -> Hash[Symbol, untyped]
   def convert_file_part_to_openai_format(file)
     if file.image?
       image_url = file.url? ? file.url : "data:#{file.media_type};base64,#{file.data}"

data/lib/riffer/providers/open_router.rb

@@ -0,0 +1,318 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require "json"
+
+# OpenRouter provider for the OpenRouter unified gateway (https://openrouter.ai).
+#
+# Requires the +openai+ gem to be installed. OpenRouter exposes an
+# OpenAI-compatible Chat Completions endpoint, so this provider reuses
+# the OpenAI Ruby SDK with a +base_url+ override.
+#
+# The +api_key+ falls back to <tt>Riffer.config.openrouter.api_key</tt>
+# and then to +OPENROUTER_API_KEY+.
+class Riffer::Providers::OpenRouter < Riffer::Providers::Base
+  BASE_URL = "https://openrouter.ai/api/v1" #: String
+
+  # Initializes the OpenRouter provider.
+  #
+  #--
+  #: (?api_key: String?, **untyped) -> void
+  def initialize(api_key: nil, **options)
+    depends_on "openai"
+
+    api_key ||= Riffer.config.openrouter.api_key || ENV["OPENROUTER_API_KEY"]
+
+    @client = ::OpenAI::Client.new(api_key: api_key, base_url: BASE_URL, **options)
+  end
+
+  private
+
+  #--
+  #: (Array[Riffer::Messages::Base], String?, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+  def build_request_params(messages, model, options)
+    reasoning = options[:reasoning]
+    tools = options[:tools]
+    structured_output = options[:structured_output]
+
+    params = {
+      model: model,
+      messages: convert_messages_to_chat_completions_format(messages),
+      **options.except(:reasoning, :tools, :structured_output)
+    } #: Hash[Symbol, untyped]
+
+    if reasoning
+      params[:reasoning] = reasoning.is_a?(String) ? {effort: reasoning} : reasoning
+    end
+
+    if tools && !tools.empty?
+      params[:tools] = tools.map { |t| convert_tool_to_chat_completions_format(t) }
+    end
+
+    if structured_output
+      params[:response_format] = {
+        type: "json_schema",
+        json_schema: {
+          name: "response",
+          schema: structured_output.json_schema(strict: true),
+          strict: true
+        }
+      }
+    end
+
+    params.compact
+  end
+
+  #--
+  #: (Hash[Symbol, untyped]) -> OpenAI::Models::Chat::ChatCompletion
+  def execute_generate(params)
+    @client.chat.completions.create(**params)
+  end
+
+  #--
+  #: (OpenAI::Models::Chat::ChatCompletion) -> Riffer::Providers::TokenUsage?
+  def extract_token_usage(response)
+    usage = response.usage
+    return nil unless usage
+
+    Riffer::Providers::TokenUsage.new(
+      input_tokens: usage.prompt_tokens,
+      output_tokens: usage.completion_tokens
+    )
+  end
+
+  #--
+  #: (OpenAI::Models::Chat::ChatCompletion) -> String
+  def extract_content(response)
+    response.choices.first&.message&.content || ""
+  end
+
+  #--
+  #: (OpenAI::Models::Chat::ChatCompletion) -> Array[Riffer::Messages::Assistant::ToolCall]
+  def extract_tool_calls(response)
+    message = response.choices.first&.message
+    return [] unless message
+
+    tool_calls = message.tool_calls
+    return [] if tool_calls.nil? || tool_calls.empty?
+
+    tool_calls.filter_map do |tc|
+      next unless tc.is_a?(::OpenAI::Models::Chat::ChatCompletionMessageFunctionToolCall)
+
+      Riffer::Messages::Assistant::ToolCall.new(
+        call_id: tc.id,
+        name: decode_tool_name(tc.function.name, tools: @current_tools),
+        arguments: tc.function.arguments
+      )
+    end
+  end
+
+  #--
+  #: (Hash[Symbol, untyped], Enumerator::Yielder) -> void
+  def execute_stream(params, yielder)
+    # OpenRouter omits usage from streams unless explicitly opted in.
+    stream_options = (params[:stream_options] || {}).merge(include_usage: true)
+    stream_params = params.merge(stream_options: stream_options)
+
+    state = {
+      text: +"",
+      reasoning: +"",
+      tool_calls: {}
+    } #: Hash[Symbol, untyped]
+
+    # Use stream_raw (not stream) — the latter yields a higher-level
+    # ChatChunkEvent helper that aggregates content/tool calls into typed
+    # 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)
+    begin
+      stream.each do |chunk|
+        handle_stream_chunk(chunk, state: state, yielder: yielder)
+      end
+    ensure
+      # The OpenAI SDK does not auto-close the SSE socket on iteration
+      # interrupt, so close explicitly. Idempotent and a no-op after EOF.
+      stream.close
+    end
+
+    # Chat Completions has no per-tool terminal event, so flush any leftover
+    # tool calls here in case finish_reason is missing or not "tool_calls".
+    emit_tool_call_done_events(state: state, yielder: yielder) unless state[:tool_calls].empty?
+
+    yielder << Riffer::StreamEvents::TextDone.new(state[:text]) unless state[:text].empty?
+    yielder << Riffer::StreamEvents::ReasoningDone.new(state[:reasoning]) unless state[:reasoning].empty?
+  end
+
+  #--
+  #: (OpenAI::Models::Chat::ChatCompletionChunk, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  def handle_stream_chunk(chunk, state:, yielder:)
+    choice = chunk.choices&.first
+    delta = choice&.delta
+
+    if delta
+      handle_text_delta(delta, state: state, yielder: yielder)
+      handle_reasoning_delta(delta, state: state, yielder: yielder)
+      handle_tool_call_deltas(delta, state: state, yielder: yielder)
+    end
+
+    if choice && finish_reason_is_tool_calls?(choice)
+      emit_tool_call_done_events(state: state, yielder: yielder)
+    end
+
+    return unless chunk.usage
+
+    yielder << Riffer::StreamEvents::TokenUsageDone.new(
+      token_usage: Riffer::Providers::TokenUsage.new(
+        input_tokens: chunk.usage.prompt_tokens,
+        output_tokens: chunk.usage.completion_tokens
+      )
+    )
+  end
+
+  #--
+  #: (OpenAI::Models::Chat::ChatCompletionChunk::Choice::Delta, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  def handle_text_delta(delta, state:, yielder:)
+    content = delta.content
+    return if content.nil? || content.empty?
+
+    state[:text] << content
+    yielder << Riffer::StreamEvents::TextDelta.new(content)
+  end
+
+  #--
+  #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  def handle_reasoning_delta(delta, state:, yielder:)
+    # The openai gem's typed Delta model strips fields not in OpenAI's spec
+    # (so +delta.reasoning+ raises NoMethodError), but the underlying data
+    # hash retains them. Access via +#[]+ which reads from BaseModel#@data.
+    reasoning = delta[:reasoning] if delta.respond_to?(:[])
+    return if reasoning.nil? || reasoning.empty?
+
+    state[:reasoning] << reasoning
+    yielder << Riffer::StreamEvents::ReasoningDelta.new(reasoning)
+  end
+
+  #--
+  #: (OpenAI::Models::Chat::ChatCompletionChunk::Choice::Delta, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  def handle_tool_call_deltas(delta, state:, yielder:)
+    tool_calls = delta.tool_calls
+    return if tool_calls.nil? || tool_calls.empty?
+
+    tool_calls.each do |tc|
+      entry = state[:tool_calls][tc.index] ||= {id: nil, name: nil, arguments: +""}
+      entry[:id] = tc.id if tc.id
+
+      fn = tc.function
+      next unless fn
+
+      entry[:name] = decode_tool_name(fn.name, tools: @current_tools) if fn.name
+
+      args_delta = fn.arguments
+      next if args_delta.nil? || args_delta.empty?
+
+      entry[:arguments] << args_delta
+      yielder << Riffer::StreamEvents::ToolCallDelta.new(
+        item_id: entry[:id] || "tool_#{tc.index}",
+        name: entry[:name],
+        arguments_delta: args_delta
+      )
+    end
+  end
+
+  #--
+  #: (state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
+  def emit_tool_call_done_events(state:, yielder:)
+    state[:tool_calls].each do |index, entry|
+      fallback = "tool_#{index}"
+      yielder << Riffer::StreamEvents::ToolCallDone.new(
+        item_id: entry[:id] || fallback,
+        call_id: entry[:id] || fallback,
+        name: entry[:name],
+        arguments: entry[:arguments]
+      )
+    end
+    state[:tool_calls] = {}
+  end
+
+  #--
+  #: (OpenAI::Models::Chat::ChatCompletionChunk::Choice) -> bool
+  def finish_reason_is_tool_calls?(choice)
+    choice.finish_reason.to_s == "tool_calls"
+  end
+
+  #--
+  #: (Array[Riffer::Messages::Base]) -> Array[Hash[Symbol, untyped]]
+  def convert_messages_to_chat_completions_format(messages)
+    messages.flat_map do |message|
+      case message
+      when Riffer::Messages::System
+        {role: "system", content: message.content}
+      when Riffer::Messages::User
+        if message.files.empty?
+          {role: "user", content: message.content}
+        else
+          content = [{type: "text", text: message.content}]
+          message.files.each { |file| content << convert_file_part_to_chat_completions_format(file) }
+          {role: "user", content: content}
+        end
+      when Riffer::Messages::Assistant
+        convert_assistant_to_chat_completions_format(message)
+      when Riffer::Messages::Tool
+        {role: "tool", tool_call_id: message.tool_call_id, content: message.content}
+      else
+        raise Riffer::ArgumentError, "unsupported message type: #{message.class}"
+      end
+    end
+  end
+
+  #--
+  #: (Riffer::Messages::Assistant) -> Hash[Symbol, untyped]
+  def convert_assistant_to_chat_completions_format(message)
+    msg = {role: "assistant"} #: Hash[Symbol, untyped]
+    msg[:content] = message.content if message.content && !message.content.empty?
+
+    unless message.tool_calls.empty?
+      msg[:tool_calls] = message.tool_calls.map do |tc|
+        {
+          id: tc.call_id,
+          type: "function",
+          function: {
+            name: encode_tool_name(tc.name),
+            arguments: tc.arguments.is_a?(String) ? tc.arguments : tc.arguments.to_json
+          }
+        }
+      end
+    end
+
+    msg
+  end
+
+  #--
+  #: (Riffer::Messages::FilePart) -> Hash[Symbol, untyped]
+  def convert_file_part_to_chat_completions_format(file)
+    if file.image?
+      image_url = file.url? ? file.url : "data:#{file.media_type};base64,#{file.data}"
+      {type: "image_url", image_url: {url: image_url}}
+    else
+      data_uri = "data:#{file.media_type};base64,#{file.data}"
+      block = {type: "file", file: {file_data: data_uri}} #: Hash[Symbol, untyped]
+      block[:file][:filename] = file.filename if file.filename
+      block
+    end
+  end
+
+  #--
+  #: (singleton(Riffer::Tool)) -> Hash[Symbol, untyped]
+  def convert_tool_to_chat_completions_format(tool)
+    {
+      type: "function",
+      function: {
+        name: encode_tool_name(tool.name),
+        description: tool.description,
+        parameters: tool.parameters_schema(strict: true),
+        strict: true
+      }
+    }
+  end
+end

data/lib/riffer/providers/repository.rb

@@ -10,6 +10,7 @@ class Riffer::Providers::Repository
     azure_openai: -> { Riffer::Providers::AzureOpenAI },
     gemini: -> { Riffer::Providers::Gemini },
     openai: -> { Riffer::Providers::OpenAI },
+    openrouter: -> { Riffer::Providers::OpenRouter },
     mock: -> { Riffer::Providers::Mock }
   }.freeze #: Hash[Symbol, ^() -> singleton(Riffer::Providers::Base)]
 

data/lib/riffer/{token_usage.rb → providers/token_usage.rb}

@@ -5,12 +5,12 @@
 #
 # Tracks input tokens, output tokens, and optional cache statistics.
 #
-#   token_usage = Riffer::TokenUsage.new(input_tokens: 100, output_tokens: 50)
+#   token_usage = Riffer::Providers::TokenUsage.new(input_tokens: 100, output_tokens: 50)
 #   token_usage.total_tokens  # => 150
 #
 #   combined = token_usage1 + token_usage2  # Combine multiple token usage objects
 #
-class Riffer::TokenUsage
+class Riffer::Providers::TokenUsage
   # Number of tokens in the input/prompt.
   attr_reader :input_tokens #: Integer
 
@@ -43,9 +43,9 @@ class Riffer::TokenUsage
   # Combines two TokenUsage objects for cumulative tracking.
   #
   #--
-  #: (Riffer::TokenUsage) -> Riffer::TokenUsage
+  #: (Riffer::Providers::TokenUsage) -> Riffer::Providers::TokenUsage
   def +(other)
-    Riffer::TokenUsage.new(
+    Riffer::Providers::TokenUsage.new(
       input_tokens: input_tokens + other.input_tokens,
       output_tokens: output_tokens + other.output_tokens,
       cache_creation_tokens: add_nullable(cache_creation_tokens, other.cache_creation_tokens),

data/lib/riffer/providers.rb

@@ -7,6 +7,7 @@
 # - Riffer::Providers::OpenAI - OpenAI GPT models
 # - Riffer::Providers::AzureOpenAI - Azure OpenAI GPT models
 # - Riffer::Providers::AmazonBedrock - AWS Bedrock models
+# - Riffer::Providers::OpenRouter - OpenRouter unified gateway
 # - Riffer::Providers::Mock - Mock provider for testing
 module Riffer::Providers
 end

data/lib/riffer/runner/fibers.rb

@@ -28,7 +28,7 @@ class Riffer::Runner::Fibers < Riffer::Runner
   end
 
   #--
-  #: (Array[untyped], context: Hash[Symbol, untyped]?) { (untyped) -> untyped } -> Array[untyped]
+  #: (Array[untyped], context: Riffer::Agent::Context?) { (untyped) -> untyped } -> Array[untyped]
   def map(items, context:, &block)
     return [] if items.empty?
 
@@ -37,8 +37,9 @@ class Riffer::Runner::Fibers < Riffer::Runner
 
     Async do
       barrier = Async::Barrier.new
-      parent = if @max_concurrency
-        Async::Semaphore.new(@max_concurrency, parent: barrier)
+      max = @max_concurrency
+      parent = if max
+        Async::Semaphore.new(max, parent: barrier)
       else
         barrier
       end

data/lib/riffer/runner/sequential.rb

@@ -7,7 +7,7 @@
 #
 class Riffer::Runner::Sequential < Riffer::Runner
   #--
-  #: (Array[untyped], context: Hash[Symbol, untyped]?) { (untyped) -> untyped } -> Array[untyped]
+  #: (Array[untyped], context: Riffer::Agent::Context?) { (untyped) -> untyped } -> Array[untyped]
   def map(items, context:, &block)
     items.map(&block)
   end

data/lib/riffer/runner/threaded.rb

@@ -25,7 +25,7 @@ class Riffer::Runner::Threaded < Riffer::Runner
   end
 
   #--
-  #: (Array[untyped], context: Hash[Symbol, untyped]?) { (untyped) -> untyped } -> Array[untyped]
+  #: (Array[untyped], context: Riffer::Agent::Context?) { (untyped) -> untyped } -> Array[untyped]
   def map(items, context:, &block)
     return [] if items.empty?
 

data/lib/riffer/runner.rb

@@ -19,7 +19,7 @@ class Riffer::Runner
   # Raises NotImplementedError if not implemented by subclass.
   #
   #--
-  #: (Array[untyped], context: Hash[Symbol, untyped]?) { (untyped) -> untyped } -> Array[untyped]
+  #: (Array[untyped], context: Riffer::Agent::Context?) { (untyped) -> untyped } -> Array[untyped]
   def map(items, context:, &block)
     raise NotImplementedError, "#{self.class} must implement #map"
   end

data/lib/riffer/skills/activate_tool.rb

@@ -19,13 +19,14 @@ class Riffer::Skills::ActivateTool < Riffer::Tool
 
   # Activates a skill by name and returns its body.
   #
-  # [context] tool context containing +:skills+ (a Riffer::Skills::Context).
+  # [context] the agent's +Riffer::Agent::Context+, exposing +#skills+
+  #           (a +Riffer::Skills::Context+).
   # [name] the skill name to activate.
   #
   #--
-  #: (context: Hash[Symbol, untyped]?, name: String) -> Riffer::Tools::Response
+  #: (context: Riffer::Agent::Context?, name: String) -> Riffer::Tools::Response
   def call(context:, name:)
-    skills_context = context&.dig(:skills)
+    skills_context = context&.skills
     return error("Skills not configured") unless skills_context
 
     text(skills_context.activate(name))

data/lib/riffer/skills/config.rb

@@ -66,7 +66,7 @@ class Riffer::Skills::Config
   # Returns the configured override when set, or +nil+ when unset. The
   # global fallback to <tt>Riffer.config.skills.default_activate_tool</tt>
   # is applied by the agent at resolution time (see
-  # Riffer::Agent.resolved_tool_classes), not by this getter.
+  # Riffer::Agent#resolve_tools), not by this getter.
   #
   # The override must be a subclass of Riffer::Tool.
   #

data/lib/riffer/skills/context.rb

@@ -6,8 +6,8 @@
 # Coordinates skill discovery, activation, and prompt rendering.
 # Tracks activations with caching to avoid redundant backend reads.
 #
-# Built by the agent at the start of generate/stream and passed to
-# tools via +context[:skills]+.
+# Built by the agent during +Agent.new+ and exposed to tools via
+# <tt>context.skills</tt> on the agent's +Riffer::Agent::Context+.
 #
 # See Riffer::Skills::Backend, Riffer::Skills::Frontmatter.
 class Riffer::Skills::Context
@@ -66,7 +66,7 @@ class Riffer::Skills::Context
   #: () -> String
   def system_prompt
     available = available_skills
-    parts = []
+    parts = [] #: Array[String]
     parts << @adapter.render_catalog(available) unless available.empty?
     @activated.each_value { |body| parts << body }
     parts.join("\n\n")

data/lib/riffer/skills/filesystem_backend.rb

@@ -31,8 +31,9 @@ class Riffer::Skills::FilesystemBackend < Riffer::Skills::Backend
   #--
   #: () -> Array[Riffer::Skills::Frontmatter]
   def list_skills
-    @skills_cache = {}
-    frontmatters = []
+    cache = {} #: Hash[String, String]
+    @skills_cache = cache
+    frontmatters = [] #: Array[Riffer::Skills::Frontmatter]
 
     @paths.each do |path|
       next unless File.directory?(path)
@@ -45,10 +46,10 @@ class Riffer::Skills::FilesystemBackend < Riffer::Skills::Backend
         frontmatter = Riffer::Skills::Frontmatter.parse_frontmatter(File.read(skill_file))
 
         validate_dirname_matches_name!(dirname, frontmatter.name)
-        next if @skills_cache.key?(frontmatter.name)
+        next if cache.key?(frontmatter.name)
 
         frontmatters << frontmatter
-        @skills_cache[frontmatter.name] = dir
+        cache[frontmatter.name] = dir
       end
     end
 
@@ -65,7 +66,8 @@ class Riffer::Skills::FilesystemBackend < Riffer::Skills::Backend
   #: (String) -> String
   def read_skill(name)
     list_skills unless @skills_cache
-    dir = @skills_cache[name]
+    cache = @skills_cache #: Hash[String, String]
+    dir = cache[name]
     raise Riffer::ArgumentError, "Skill not found: '#{name}'" unless dir
 
     _, body = Riffer::Skills::Frontmatter.parse(File.read(File.join(dir, SKILL_FILENAME)))

data/lib/riffer/skills/markdown_adapter.rb

@@ -15,7 +15,7 @@ class Riffer::Skills::MarkdownAdapter < Riffer::Skills::Adapter
   #--
   #: (Array[Riffer::Skills::Frontmatter]) -> String
   def render_catalog(skills)
-    lines = []
+    lines = [] #: Array[String]
     lines << "## Available Skills"
     lines << ""
     lines << "When a user's request matches a skill description below, call the `#{skill_activate_tool.name}` tool with the skill name. After activation, follow the skill's instructions."

data/lib/riffer/skills/xml_adapter.rb

@@ -16,7 +16,7 @@ class Riffer::Skills::XmlAdapter < Riffer::Skills::Adapter
   #--
   #: (Array[Riffer::Skills::Frontmatter]) -> String
   def render_catalog(skills)
-    lines = []
+    lines = [] #: Array[String]
     lines << "When a user's request matches a skill description below, call the `#{skill_activate_tool.name}` tool with the skill name. After activation, follow the skill's instructions."
     lines << ""
     lines << "<available_skills>"

data/lib/riffer/stream_events/interrupt.rb

@@ -26,7 +26,7 @@ class Riffer::StreamEvents::Interrupt < Riffer::StreamEvents::Base
   #--
   #: () -> Hash[Symbol, untyped]
   def to_h
-    h = {role: @role, interrupt: true}
+    h = {role: @role, interrupt: true} #: Hash[Symbol, untyped]
     h[:reason] = @reason if @reason
     h[:healed_tool_call_ids] = @healed_tool_call_ids unless @healed_tool_call_ids.empty?
     h

data/lib/riffer/stream_events/token_usage_done.rb

@@ -11,10 +11,10 @@
 #
 class Riffer::StreamEvents::TokenUsageDone < Riffer::StreamEvents::Base
   # The token usage data for this response.
-  attr_reader :token_usage #: Riffer::TokenUsage
+  attr_reader :token_usage #: Riffer::Providers::TokenUsage
 
   #--
-  #: (token_usage: Riffer::TokenUsage, ?role: Symbol) -> void
+  #: (token_usage: Riffer::Providers::TokenUsage, ?role: Symbol) -> void
   def initialize(token_usage:, role: :assistant)
     super(role: role)
     @token_usage = token_usage

data/lib/riffer/stream_events/web_search_status.rb

@@ -26,7 +26,7 @@ class Riffer::StreamEvents::WebSearchStatus < Riffer::StreamEvents::Base
   #--
   #: () -> Hash[Symbol, untyped]
   def to_h
-    h = {role: @role, status: @status}
+    h = {role: @role, status: @status} #: Hash[Symbol, untyped]
     h[:url] = @url if @url
     h[:query] = @query if @query
     h