riffer 0.47.2 → 0.49.0

data/lib/riffer/mcp/registry.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Thread-safe global store for MCP server registrations, keyed by manifest name.
 module Riffer::Mcp::Registry
   extend self
 
@@ -11,8 +10,6 @@ module Riffer::Mcp::Registry
   @mutex = Mutex.new
   @store = {} #: Hash[String, Riffer::Mcp::Registration]
 
-  # Registers an MCP server and starts async tool discovery, replacing any
-  # existing registration with the same name.
   #--
   #: ((Hash[Symbol, untyped] | Riffer::Mcp::Manifest)) -> Riffer::Mcp::Registration
   def register(manifest_or_hash)
@@ -33,8 +30,6 @@ module Riffer::Mcp::Registry
     registration
   end
 
-  # Removes a registration by name.
-  #
   #--
   #: ((String | Symbol)) -> void
   def unregister(name)
@@ -42,16 +37,12 @@ module Riffer::Mcp::Registry
     removed&.retire!
   end
 
-  # Returns a frozen snapshot of all current registrations.
-  #
   #--
   #: () -> Hash[String, Riffer::Mcp::Registration]
   def registrations
     @mutex.synchronize { @store.dup.freeze }
   end
 
-  # Returns all registrations whose manifest tags intersect the given tags
-  # (normalized to symbols).
   #--
   #: (Array[Symbol]) -> Array[Riffer::Mcp::Registration]
   def find_by_tags(tags)

data/lib/riffer/mcp/search_tool.rb

@@ -1,13 +1,10 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Searches available MCP tools by name or description.
 class Riffer::Mcp::SearchTool < Riffer::Tool
   IDENTIFIER = "mcp_search"
 
-  # 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)] # @dynamic discovered_tools
 
     #--
@@ -25,7 +22,6 @@ class Riffer::Mcp::SearchTool < Riffer::Tool
     required :query, String, description: "Non-empty substring to filter tools by name or description."
   end
 
-  # Searches progressive MCP tools and returns a +Result+ with +discovered_tools+.
   #--
   #: (context: Riffer::Agent::Context?, query: String) -> Riffer::Tools::Response
   def call(context:, query:)

data/lib/riffer/mcp/tool.rb

@@ -1,23 +1,20 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Base class for MCP-generated tools.
 class Riffer::Mcp::Tool < Riffer::Tool
   # @rbs self.@mcp_server_tool_name: String?
   # @rbs self.@input_schema: Hash[Symbol, untyped]?
 
-  # Returns the unprefixed tool name used for +tools/call+ on the MCP server.
   #--
   #: () -> String
   def self.mcp_server_tool_name
     @mcp_server_tool_name || raise(NotImplementedError, "#{self} must set @mcp_server_tool_name")
   end
 
-  # Returns the server-published input schema, falling back to the params DSL.
-  # MCP schemas are server-defined, so +strict+ is not applied to them.
   #--
   #: (?strict: bool) -> Hash[Symbol, untyped]
   def self.parameters_schema(strict: false)
+    # MCP schemas are server-defined, so +strict+ is not applied to them.
     @input_schema || super
   end
 end

data/lib/riffer/mcp/tool_factory.rb

@@ -1,15 +1,9 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Generates anonymous Riffer::Mcp::Tool subclasses from MCP tool definitions.
-# Generated tools delegate +#call+ to the MCP client and skip Riffer's param
-# validation — the MCP server validates inputs.
 module Riffer::Mcp::ToolFactory
   extend self
 
-  # Builds one Riffer::Mcp::Tool subclass per tool definition, prefixing names
-  # with the manifest name to avoid cross-server collisions (e.g.
-  # +jira__search+); the server-side name stays on +.mcp_server_tool_name+.
   #--
   #: (String, Riffer::Mcp::Client, Array[Hash[Symbol, untyped]]) -> Array[singleton(Riffer::Mcp::Tool)]
   def build(manifest_name, client, tool_defs)
@@ -25,6 +19,8 @@ module Riffer::Mcp::ToolFactory
 
   #: (String, Riffer::Mcp::Client, Hash[Symbol, untyped]) -> singleton(Riffer::Mcp::Tool)
   def build_tool_class(manifest_name, client, descriptor)
+    # Prefixed to avoid cross-server collisions; the server-side name stays on
+    # mcp_server_tool_name.
     prefixed = "#{sanitize_name_component(manifest_name)}__#{sanitize_name_component(descriptor[:name])}"
 
     # steep does not model Class.new's class_eval semantics — the block body
@@ -37,6 +33,7 @@ module Riffer::Mcp::ToolFactory
       @description = descriptor[:description]
       @input_schema = descriptor[:input_schema]
 
+      # No Riffer param validation — the MCP server validates inputs.
       define_method(:call) do |context:, **kwargs|
         text(client.tools_call(self.class.mcp_server_tool_name, kwargs))
       end

data/lib/riffer/mcp.rb

@@ -1,49 +1,28 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Integration with Model Context Protocol (MCP) servers. Register servers
-# globally; agents opt-in by tag via the +use_mcp+ DSL. Tags are
-# application-defined; see +docs/MCP.md+.
-#
-#   Riffer::Mcp.register(
-#     name: "github",
-#     tags: [:github],
-#     endpoint: "https://mcp.github.com",
-#     discovery_headers: -> { {"Authorization" => "Bearer #{ENV['GITHUB_TOKEN']}"} }
-#   )
-#
-#   class MyAgent < Riffer::Agent
-#     model "openai/gpt-4o"
-#     use_mcp :github
-#   end
-#
 module Riffer::Mcp
   extend self
 
-  # Base error for all MCP-related failures.
   class Error < Riffer::Error; end
 
   # Raised when +Riffer.config.mcp.credentials+ returns +nil+ during +tools/call+
-  # after the server's tools were included for this run.
+  # after the server's tools were already included for this run.
   class CredentialsDeniedError < Error; end
 
-  # Registers an MCP server, blocking until tool discovery completes. Raises
-  # on discovery failure.
+  # Blocks until tool discovery completes.
   #--
   #: ((Hash[Symbol, untyped] | Riffer::Mcp::Manifest)) -> Riffer::Mcp::Registration
   def register(manifest_or_hash)
     Registry.register(manifest_or_hash)
   end
 
-  # Removes a registration by name; subsequent agent runs won't see its tools.
   #--
   #: (String) -> void
   def unregister(name)
     Registry.unregister(name)
   end
 
-  # Returns all current registrations keyed by name.
-  #
   #--
   #: () -> Hash[String, Riffer::Mcp::Registration]
   def registrations

data/lib/riffer/messages/assistant/reasoning_part.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Stored and replayed verbatim, never interpreted, so a provider that requires its own thinking
+# blocks back gets them unchanged.
+class Riffer::Messages::Assistant::ReasoningPart
+  TYPES = %i[text summary encrypted].freeze #: Array[Symbol]
+
+  attr_reader :type #: Symbol # @dynamic type
+  attr_reader :text #: String? # @dynamic text
+  attr_reader :data #: String? # @dynamic data
+  attr_reader :signature #: String? # @dynamic signature
+  attr_reader :id #: String? # @dynamic id
+
+  # Owned by the producing adapter (e.g. <tt>"anthropic-claude-v1"</tt>); adapters replay only the
+  # formats they recognize, so it is never validated here.
+  attr_reader :format #: String? # @dynamic format
+
+  #--
+  #: ((Hash[Symbol, untyped] | Riffer::Messages::Assistant::ReasoningPart)) -> Riffer::Messages::Assistant::ReasoningPart
+  def self.from_hash(part)
+    return part if part.is_a?(Riffer::Messages::Assistant::ReasoningPart)
+
+    new(
+      type: part[:type].to_sym,
+      text: part[:text],
+      data: part[:data],
+      signature: part[:signature],
+      id: part[:id],
+      format: part[:format],
+    )
+  end
+
+  #--
+  #: (type: Symbol, ?text: String?, ?data: String?, ?signature: String?, ?id: String?, ?format: String?) -> void
+  def initialize(type:, text: nil, data: nil, signature: nil, id: nil, format: nil)
+    unless TYPES.include?(type)
+      raise Riffer::ArgumentError,
+            "type must be one of #{TYPES.inspect}, got #{type.inspect}"
+    end
+
+    @type = type
+    @text = text
+    @data = data
+    @signature = signature
+    @id = id
+    @format = format
+  end
+
+  #--
+  #: () -> Hash[Symbol, untyped]
+  def to_h
+    { type: type, text: text, data: data, signature: signature, id: id, format: format }.compact
+  end
+
+  #--
+  #: (untyped) -> bool
+  def ==(other)
+    other.is_a?(Riffer::Messages::Assistant::ReasoningPart) && to_h == other.to_h
+  end
+
+  #--
+  #: (untyped) -> bool
+  def eql?(other)
+    self == other
+  end
+
+  #--
+  #: () -> Integer
+  def hash
+    to_h.hash
+  end
+end

data/lib/riffer/messages/assistant/tool_call.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+class Riffer::Messages::Assistant::ToolCall
+  attr_reader :call_id #: String # @dynamic call_id
+
+  attr_reader :name #: String # @dynamic name
+
+  # JSON-encoded, exactly as the provider emitted them.
+  attr_reader :arguments #: String # @dynamic arguments
+
+  #--
+  #: ((Hash[Symbol, untyped] | Riffer::Messages::Assistant::ToolCall)) -> Riffer::Messages::Assistant::ToolCall
+  def self.from_hash(call)
+    return call if call.is_a?(Riffer::Messages::Assistant::ToolCall)
+
+    if call.values_at(:call_id, :name, :arguments).any?(&:nil?)
+      raise Riffer::ArgumentError, "Tool call hash must include :call_id, :name, and :arguments"
+    end
+
+    new(call_id: call[:call_id], name: call[:name], arguments: call[:arguments])
+  end
+
+  #--
+  #: (call_id: String, name: String, arguments: String) -> void
+  def initialize(call_id:, name:, arguments:)
+    @call_id = call_id
+    @name = name
+    @arguments = arguments
+  end
+
+  #--
+  #: () -> Hash[Symbol, untyped]
+  def to_h
+    { call_id: call_id, name: name, arguments: arguments }
+  end
+
+  #--
+  #: (untyped) -> bool
+  def ==(other)
+    other.is_a?(Riffer::Messages::Assistant::ToolCall) && to_h == other.to_h
+  end
+
+  #--
+  #: (untyped) -> bool
+  def eql?(other)
+    self == other
+  end
+
+  #--
+  #: () -> Integer
+  def hash
+    to_h.hash
+  end
+end

data/lib/riffer/messages/assistant.rb

@@ -1,35 +1,45 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Represents an assistant (LLM) message in a conversation; may include tool
-# calls when the LLM requests tool execution.
 class Riffer::Messages::Assistant < Riffer::Messages::Base
-  ToolCall = Struct.new(:call_id, :name, :arguments)
+  # The other reasoning part types carry no prose.
+  REASONING_TEXT_TYPES = %i[text summary].freeze #: Array[Symbol]
+
+  #--
+  #: ((Hash[Symbol, untyped] | Riffer::Messages::Assistant)) -> Riffer::Messages::Assistant
+  def self.from_hash(msg)
+    return msg if msg.is_a?(Riffer::Messages::Assistant)
+
+    new(
+      msg[:content],
+      id: msg[:id],
+      tool_calls: (msg[:tool_calls] || []).map { |tc| Riffer::Messages::Assistant::ToolCall.from_hash(tc) },
+      reasoning: (msg[:reasoning] || []).map { |part| Riffer::Messages::Assistant::ReasoningPart.from_hash(part) },
+      token_usage: msg[:token_usage] && Riffer::Providers::TokenUsage.from_hash(msg[:token_usage]),
+      structured_output: msg[:structured_output],
+      finish_reason: msg[:finish_reason]&.to_sym,
+      finish_reason_raw: msg[:finish_reason_raw],
+    )
+  end
 
-  # Array of tool calls requested by the assistant.
   attr_reader :tool_calls #: Array[Riffer::Messages::Assistant::ToolCall] # @dynamic tool_calls
 
-  # Token usage data for this response.
+  attr_reader :reasoning #: Array[Riffer::Messages::Assistant::ReasoningPart] # @dynamic reasoning
+
   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]? # @dynamic structured_output
 
-  # Normalized reason the provider finished this response, when reported (see
-  # <tt>Riffer::Providers::FinishReason::VALUES</tt>).
   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? # @dynamic finish_reason_raw
 
-  # Raises Riffer::ArgumentError when +finish_reason+ is outside the
-  # normalized vocabulary.
   #--
   #: (
   #    String,
   #    ?id: String?,
   #    ?tool_calls: Array[Riffer::Messages::Assistant::ToolCall],
+  #    ?reasoning: Array[Riffer::Messages::Assistant::ReasoningPart],
   #    ?token_usage: Riffer::Providers::TokenUsage?,
   #    ?structured_output: Hash[Symbol, untyped]?,
   #    ?finish_reason: Symbol?,
@@ -39,6 +49,7 @@ class Riffer::Messages::Assistant < Riffer::Messages::Base
     content,
     id: nil,
     tool_calls: [],
+    reasoning: [],
     token_usage: nil,
     structured_output: nil,
     finish_reason: nil,
@@ -51,6 +62,7 @@ class Riffer::Messages::Assistant < Riffer::Messages::Base
 
     super(content, id: id)
     @tool_calls = tool_calls
+    @reasoning = reasoning
     @token_usage = token_usage
     @structured_output = structured_output
     @finish_reason = finish_reason
@@ -75,20 +87,36 @@ class Riffer::Messages::Assistant < Riffer::Messages::Base
     !@tool_calls.empty?
   end
 
+  #--
+  #: () -> bool
+  def reasoning?
+    !@reasoning.empty?
+  end
+
+  #--
+  #: () -> String?
+  def reasoning_text
+    texts = reasoning.filter_map { |part| part.text if REASONING_TEXT_TYPES.include?(part.type) }
+    texts.empty? ? nil : texts.join("\n\n")
+  end
+
   #--
   #: (Riffer::Messages::Assistant) -> Riffer::Messages::Assistant
   def +(other)
-    self.class.new("#{content}\n\n#{other.content}", tool_calls: tool_calls + other.tool_calls)
+    self.class.new(
+      "#{content}\n\n#{other.content}",
+      tool_calls: tool_calls + other.tool_calls,
+      reasoning: reasoning + other.reasoning,
+    )
   end
 
-  # Converts the message to a hash.
-  #
   #--
   #: () -> Hash[Symbol, untyped]
   def to_h
     hash = { role: role, content: content } #: Hash[Symbol, untyped]
     hash[:id] = id if id
     hash[:tool_calls] = tool_calls.map(&:to_h) unless tool_calls.empty?
+    hash[:reasoning] = reasoning.map(&:to_h) if reasoning?
     hash[:token_usage] = token_usage.to_h if token_usage
     hash[:structured_output] = structured_output if structured_output?
     hash[:finish_reason] = finish_reason if finish_reason

data/lib/riffer/messages/base.rb

@@ -3,10 +3,7 @@
 
 require "securerandom"
 
-# Base class for all message types. Subclasses must implement +role+.
 class Riffer::Messages::Base
-  # Builds the matching message subclass from a hash, or returns +msg+ unchanged
-  # when it is already a message. Raises Riffer::ArgumentError on an invalid message.
   #--
   #: ((Hash[Symbol, untyped] | Riffer::Messages::Base)) -> Riffer::Messages::Base
   def self.from_hash(msg)
@@ -15,34 +12,16 @@ class Riffer::Messages::Base
     raise Riffer::ArgumentError, "Message hash must include a 'role' key" if msg[:role].nil? || msg[:role].empty?
 
     case msg[:role].to_sym
-    when :user
-      files = (msg[:files] || []).map { |f| Riffer::Messages::FilePart.from_hash(f) }
-      Riffer::Messages::User.new(msg[:content], id: msg[:id], files: files)
-    when :assistant
-      tool_calls = (msg[:tool_calls] || []).map do |tc|
-        tc.is_a?(Riffer::Messages::Assistant::ToolCall) ? tc : Riffer::Messages::Assistant::ToolCall.new(**tc)
-      end
-      Riffer::Messages::Assistant.new(
-        msg[:content],
-        id: msg[:id],
-        tool_calls: tool_calls,
-        structured_output: msg[:structured_output],
-        finish_reason: msg[:finish_reason]&.to_sym,
-        finish_reason_raw: msg[:finish_reason_raw],
-      )
-    when :system
-      Riffer::Messages::System.new(msg[:content], id: msg[:id])
-    when :tool
-      Riffer::Messages::Tool.new(msg[:content], id: msg[:id], tool_call_id: msg[:tool_call_id], name: msg[:name])
-    else
-      raise Riffer::ArgumentError, "Unknown message role: #{msg[:role]}"
+    when :user then Riffer::Messages::User.from_hash(msg)
+    when :assistant then Riffer::Messages::Assistant.from_hash(msg)
+    when :system then Riffer::Messages::System.from_hash(msg)
+    when :tool then Riffer::Messages::Tool.from_hash(msg)
+    else raise Riffer::ArgumentError, "Unknown message role: #{msg[:role]}"
     end
   end
 
-  # The message content.
   attr_reader :content #: String # @dynamic content
 
-  # The message id, or nil when +Riffer.config.message_id_strategy+ is +:none+.
   attr_reader :id #: String? # @dynamic id
 
   #--
@@ -52,8 +31,6 @@ class Riffer::Messages::Base
     @id = id || generate_id
   end
 
-  # Converts the message to a hash.
-  #
   #--
   #: () -> Hash[Symbol, untyped]
   def to_h
@@ -62,23 +39,18 @@ class Riffer::Messages::Base
     hash
   end
 
-  # Returns the message role.
   #--
   #: () -> Symbol
   def role
     raise NotImplementedError, "Subclasses must implement #role"
   end
 
-  # Whether this message carries pending tool calls (overridden by
-  # +Riffer::Messages::Assistant+).
   #--
   #: () -> bool
   def has_tool_calls?
     false
   end
 
-  # Merges another same-role message into this one. +Tool+ messages are never
-  # merged.
   #--
   #: (untyped) -> Riffer::Messages::Base
   def +(other)

data/lib/riffer/messages/system.rb

@@ -1,8 +1,15 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Represents a system message (instructions) in a conversation.
 class Riffer::Messages::System < Riffer::Messages::Base
+  #--
+  #: ((Hash[Symbol, untyped] | Riffer::Messages::System)) -> Riffer::Messages::System
+  def self.from_hash(msg)
+    return msg if msg.is_a?(Riffer::Messages::System)
+
+    new(msg[:content], id: msg[:id])
+  end
+
   #--
   #: () -> Symbol
   def role

data/lib/riffer/messages/tool.rb

@@ -1,19 +1,25 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# 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 # @dynamic tool_call_id
+  #--
+  #: ((Hash[Symbol, untyped] | Riffer::Messages::Tool)) -> Riffer::Messages::Tool
+  def self.from_hash(msg)
+    return msg if msg.is_a?(Riffer::Messages::Tool)
+
+    new(
+      msg[:content],
+      id: msg[:id],
+      tool_call_id: msg[:tool_call_id],
+      name: msg[:name],
+      error: msg[:error],
+      error_type: msg[:error_type]&.to_sym,
+    )
+  end
 
-  # The name of the tool that was called.
+  attr_reader :tool_call_id #: String # @dynamic tool_call_id
   attr_reader :name #: String # @dynamic name
-
-  # The error message if the tool execution failed.
   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? # @dynamic error_type
 
   #--
@@ -26,8 +32,6 @@ class Riffer::Messages::Tool < Riffer::Messages::Base
     @error_type = error_type
   end
 
-  # Returns true if the tool execution resulted in an error.
-  #
   #--
   #: () -> bool
   def error?
@@ -40,8 +44,6 @@ class Riffer::Messages::Tool < Riffer::Messages::Base
     :tool
   end
 
-  # Converts the message to a hash.
-  #
   #--
   #: () -> Hash[Symbol, untyped]
   def to_h