riffer 0.47.2 → 0.49.0

data/lib/riffer/stream_events/guardrail_modification.rb

@@ -1,9 +1,7 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Emitted when a guardrail transforms data during streaming.
 class Riffer::StreamEvents::GuardrailModification < Riffer::StreamEvents::Base
-  # The modification record.
   attr_reader :modification #: Riffer::Guardrails::Modification # @dynamic modification
 
   #--
@@ -13,26 +11,18 @@ class Riffer::StreamEvents::GuardrailModification < Riffer::StreamEvents::Base
     @modification = modification
   end
 
-  # The guardrail class that made the transformation.
-  #
   #--
   #: () -> singleton(Riffer::Guardrail)
   def guardrail = modification.guardrail
 
-  # The phase when the transformation occurred.
-  #
   #--
   #: () -> Symbol
   def phase = modification.phase
 
-  # The indices of messages that were changed.
-  #
   #--
   #: () -> Array[Integer]
   def message_indices = modification.message_indices
 
-  # Converts the event to a hash.
-  #
   #--
   #: () -> Hash[Symbol, untyped]
   def to_h

data/lib/riffer/stream_events/guardrail_tripwire.rb

@@ -1,9 +1,7 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# 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 # @dynamic tripwire
 
   #--
@@ -13,32 +11,24 @@ class Riffer::StreamEvents::GuardrailTripwire < Riffer::StreamEvents::Base
     @tripwire = tripwire
   end
 
-  # The reason for blocking.
-  #
   #--
   #: () -> String
   def reason
     tripwire.reason
   end
 
-  # The phase when blocking occurred (:before or :after).
-  #
   #--
   #: () -> Symbol
   def phase
     tripwire.phase
   end
 
-  # The guardrail class that triggered the block.
-  #
   #--
   #: () -> singleton(Riffer::Guardrail)
   def guardrail
     tripwire.guardrail
   end
 
-  # Converts the event to a hash.
-  #
   #--
   #: () -> Hash[Symbol, untyped]
   def to_h

data/lib/riffer/stream_events/interrupt.rb

@@ -1,31 +1,21 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Represents an interrupt during streaming, fired when a callback throws
-# +:riffer_interrupt+.
 class Riffer::StreamEvents::Interrupt < Riffer::StreamEvents::Base
-  # The reason provided with the interrupt, if any.
   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] # @dynamic healed_tool_call_ids
-
   #--
-  #: (?reason: (String | Symbol)?, ?healed_tool_call_ids: Array[String]) -> void
-  def initialize(reason: nil, healed_tool_call_ids: [])
+  #: (?reason: (String | Symbol)?) -> void
+  def initialize(reason: nil)
     super(role: :system)
     @reason = reason
-    @healed_tool_call_ids = healed_tool_call_ids
   end
 
-  # Converts the event to a hash.
   #--
   #: () -> Hash[Symbol, untyped]
   def to_h
     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
   end
 end

data/lib/riffer/stream_events/reasoning_delta.rb

@@ -1,10 +1,7 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Represents an incremental reasoning chunk during streaming; only emitted by
-# providers that support reasoning (e.g. OpenAI with the reasoning option).
 class Riffer::StreamEvents::ReasoningDelta < Riffer::StreamEvents::Base
-  # The incremental reasoning content.
   attr_reader :content #: String # @dynamic content
 
   #--

data/lib/riffer/stream_events/reasoning_done.rb

@@ -1,22 +1,20 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Represents completed reasoning during streaming; only emitted by providers
-# that support reasoning (e.g. OpenAI with the reasoning option).
 class Riffer::StreamEvents::ReasoningDone < Riffer::StreamEvents::Base
-  # The complete reasoning content.
-  attr_reader :content #: String # @dynamic content
+  # +text+ is the concatenation of the preceding ReasoningDelta events.
+  attr_reader :part #: Riffer::Messages::Assistant::ReasoningPart # @dynamic part
 
   #--
-  #: (String, ?role: Symbol) -> void
-  def initialize(content, role: :assistant)
+  #: (Riffer::Messages::Assistant::ReasoningPart, ?role: Symbol) -> void
+  def initialize(part, role: :assistant)
     super(role: role)
-    @content = content
+    @part = part
   end
 
   #--
   #: () -> Hash[Symbol, untyped]
   def to_h
-    { role: @role, content: @content }
+    { role: @role, part: part.to_h }
   end
 end

data/lib/riffer/stream_events/skill_activation.rb

@@ -1,10 +1,7 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Emitted when a skill is activated during streaming, via the +on_activate+
-# callback when the LLM calls the activation tool.
 class Riffer::StreamEvents::SkillActivation < Riffer::StreamEvents::Base
-  # The activated skill name.
   attr_reader :name #: String # @dynamic name
 
   #--

data/lib/riffer/stream_events/text_delta.rb

@@ -1,9 +1,7 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Represents an incremental text chunk during streaming.
 class Riffer::StreamEvents::TextDelta < Riffer::StreamEvents::Base
-  # The incremental text content.
   attr_reader :content #: String # @dynamic content
 
   #--

data/lib/riffer/stream_events/text_done.rb

@@ -1,9 +1,7 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Represents completed text generation during streaming.
 class Riffer::StreamEvents::TextDone < Riffer::StreamEvents::Base
-  # The complete text content.
   attr_reader :content #: String # @dynamic content
 
   #--

data/lib/riffer/stream_events/token_usage_done.rb

@@ -1,9 +1,7 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Final token usage for the response, emitted when the LLM finishes.
 class Riffer::StreamEvents::TokenUsageDone < Riffer::StreamEvents::Base
-  # The token usage data for this response.
   attr_reader :token_usage #: Riffer::Providers::TokenUsage # @dynamic token_usage
 
   #--

data/lib/riffer/stream_events/tool_call_delta.rb

@@ -1,16 +1,12 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Represents an incremental tool call chunk (partial argument data) during
-# streaming.
 class Riffer::StreamEvents::ToolCallDelta < Riffer::StreamEvents::Base
-  # The tool call item identifier.
   attr_reader :item_id #: String # @dynamic item_id
 
-  # The tool name (may only be present in first delta).
+  # Providers may send the name only on the first delta.
   attr_reader :name #: String? # @dynamic name
 
-  # The incremental arguments JSON fragment.
   attr_reader :arguments_delta #: String # @dynamic arguments_delta
 
   #--

data/lib/riffer/stream_events/tool_call_done.rb

@@ -1,18 +1,13 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Represents a completed tool call during streaming.
 class Riffer::StreamEvents::ToolCallDone < Riffer::StreamEvents::Base
-  # The tool call item identifier.
   attr_reader :item_id #: String # @dynamic item_id
 
-  # The call identifier for response matching.
   attr_reader :call_id #: String # @dynamic call_id
 
-  # The tool name.
   attr_reader :name #: String # @dynamic name
 
-  # The complete arguments JSON string.
   attr_reader :arguments #: String # @dynamic arguments
 
   #--

data/lib/riffer/stream_events/web_search_done.rb

@@ -1,12 +1,9 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# The result of a completed server-side web search during streaming.
 class Riffer::StreamEvents::WebSearchDone < Riffer::StreamEvents::Base
-  # The search query used.
   attr_reader :query #: String # @dynamic query
 
-  # The search result sources with title and url.
   attr_reader :sources #: Array[Hash[Symbol, String?]] # @dynamic sources
 
   #--

data/lib/riffer/stream_events/web_search_status.rb

@@ -1,16 +1,12 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# A web search status notification, emitted as a server-side web search
-# progresses.
 class Riffer::StreamEvents::WebSearchStatus < Riffer::StreamEvents::Base
-  # The web search status ("in_progress", "searching", "completed", "open_page").
+  # One of "in_progress", "searching", "open_page", or "completed".
   attr_reader :status #: String # @dynamic status
 
-  # The URL being fetched (present for "open_page" status).
   attr_reader :url #: String? # @dynamic url
 
-  # The search query (present when available during status changes).
   attr_reader :query #: String? # @dynamic query
 
   #--

data/lib/riffer/testing/minitest.rb

@@ -1,13 +1,12 @@
 # frozen_string_literal: true
 
-# rbs-inline stays disabled here: the generated signature would name Minitest,
-# which a shipped signature must never reference. The hand-written stub lives in
-# sig/_private/riffer/testing/minitest.rbs.
+# rbs-inline stays disabled: a shipped signature must never name Minitest. The
+# stub lives in sig/_private/riffer/testing/minitest.rbs.
 
 require "riffer"
 
-# Wiring only — minitest is never a riffer dependency; a consumer requires this
-# file from a test_helper that has already loaded the framework.
+# Minitest is never a riffer dependency; the consumer's test_helper loads it
+# before requiring this file.
 module Riffer::Testing::MinitestCleanup
   # Minitest reserves +after_teardown+ for library extensions; +teardown+
   # belongs to the test author.

data/lib/riffer/testing.rb

@@ -1,14 +1,6 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Builds throwaway agents and tools a test suite can resolve by identifier or
-# constant name, and removes them again. Require <tt>riffer/testing/rspec</tt>
-# or <tt>riffer/testing/minitest</tt> to get +stub_agent+/+stub_tool+ in every
-# example plus per-test cleanup; otherwise include this module and call +reset!+
-# from your own teardown, or call the methods on the module directly.
-#
-# Tracking is not synchronized — stub from a single-threaded test, before
-# concurrent lookups begin.
 module Riffer::Testing
   extend self
 
@@ -17,43 +9,18 @@ module Riffer::Testing
   CONST_NAME_PATTERN = /\A[A-Z][A-Za-z0-9_]*\z/ #: Regexp
   private_constant :CONST_NAME_PATTERN
 
-  # Builds an agent class, evaluates the optional body in it, and makes it
-  # resolvable until the next +reset!+. A +name+ assigns a top-level constant
-  # and derives the identifier; the body may set +identifier+ like any other
-  # agent config.
-  #
-  #   agent = stub_agent("SupportAgent") { model "mock/gpt-5-mini" }
-  #
-  # Raises Riffer::ArgumentError when the constant is already defined or the
-  # stub ends up with no identifier, and Riffer::DuplicateIdentifierError when
-  # another agent already holds the identifier.
-  #
   #--
   #: (?(String | Symbol)?, ?base: singleton(Riffer::Agent)) ?{ () [self: singleton(Riffer::Agent)] -> void } -> singleton(Riffer::Agent)
   def stub_agent(name = nil, base: Riffer::Agent, &body)
     build_stub(name, base: base, &body) #: singleton(Riffer::Agent)
   end
 
-  # Builds a tool class, evaluates the optional body in it, and makes it
-  # resolvable until the next +reset!+. A +name+ assigns a top-level constant
-  # and derives the identifier; the body may set +identifier+ like any other
-  # tool config.
-  #
-  #   tool = stub_tool("KbSearch") { def call(context:, **) = text("stubbed") }
-  #
-  # Raises Riffer::ArgumentError when the constant is already defined or the
-  # stub ends up with no identifier, and Riffer::DuplicateIdentifierError when
-  # another tool already holds the identifier.
-  #
   #--
   #: (?(String | Symbol)?, ?base: singleton(Riffer::Tool)) ?{ () [self: singleton(Riffer::Tool)] -> void } -> singleton(Riffer::Tool)
   def stub_tool(name = nil, base: Riffer::Tool, &body)
     build_stub(name, base: base, &body) #: singleton(Riffer::Tool)
   end
 
-  # Removes every stub built since the last reset — its registration and any
-  # constant it created — newest first, and forgets them. A no-op when nothing
-  # has been stubbed.
   #--
   #: () -> void
   def reset!
@@ -66,12 +33,12 @@ module Riffer::Testing
     tracked.clear
   end
 
-  # The stub classes awaiting cleanup. Lives on the module rather than the
-  # caller so an including test case and a direct
-  # <tt>Riffer::Testing.stub_*</tt> call share one list.
   #--
   #: () -> Array[[Class, String?]]
   def self.registrations # :nodoc:
+    # Lives on the module rather than the caller so an including test case and
+    # a direct <tt>Riffer::Testing.stub_*</tt> call share one list. Not
+    # synchronized: stub from a single-threaded test.
     @registrations ||= []
   end
 
@@ -118,11 +85,11 @@ module Riffer::Testing
     const_name
   end
 
-  # A test may have removed or replaced the constant itself, so never clobber
-  # one that no longer points at the stub.
   #--
   #: (String, Class) -> void
   def remove_stub_const(const_name, stub)
+    # A test may have removed or replaced the constant itself, so never clobber
+    # one that no longer points at the stub.
     return unless Object.const_defined?(const_name, false) && Object.const_get(const_name, false).equal?(stub)
 
     Object.send(:remove_const, const_name)

data/lib/riffer/tool.rb

@@ -3,64 +3,36 @@
 
 require "timeout"
 
-# Base class for all tools in the Riffer framework. Subclasses must implement
-# the +call+ method.
-#
-#   class WeatherLookupTool < Riffer::Tool
-#     description "Provides current weather information for a specified city."
-#
-#     params do
-#       required :city, String, description: "The city to look up"
-#       optional :units, String, default: "celsius"
-#     end
-#
-#     def call(context:, city:, units: nil)
-#       # Implementation
-#     end
-#   end
-#
 class Riffer::Tool
   extend Riffer::Tools::Toolable
   extend Riffer::Registrable
 
   kind :tool
 
-  # Executes the tool with the given arguments.
   #--
   #: (context: Riffer::Agent::Context?, **untyped) -> Riffer::Tools::Response
   def call(context:, **kwargs)
     raise NotImplementedError, "#{self.class} must implement #call"
   end
 
-  # Creates a text response.
-  #
   #--
   #: (untyped) -> Riffer::Tools::Response
   def text(result)
     Riffer::Tools::Response.text(result)
   end
 
-  # Creates a JSON response.
-  #
   #--
   #: (untyped) -> Riffer::Tools::Response
   def json(result)
     Riffer::Tools::Response.json(result)
   end
 
-  # Creates an error response.
-  #
   #--
   #: (String, ?type: Symbol) -> Riffer::Tools::Response
   def error(message, type: :execution_error)
     Riffer::Tools::Response.error(message, type: type)
   end
 
-  # Executes the tool with validation and timeout, folding every +StandardError+
-  # into an error Response. Anything outside +StandardError+ — an unimplemented
-  # +#call+ above all — still propagates, because a broken tool is a broken
-  # deploy rather than a bad request.
-  #
   #--
   #: (context: Riffer::Agent::Context?, **untyped) -> Riffer::Tools::Response
   def call_with_validation(context:, **kwargs)
@@ -88,6 +60,8 @@ class Riffer::Tool
     )
   rescue Riffer::ToolExecutionError => e
     Riffer::Tools::Response.error(e.message, type: :execution_error)
+  # Anything outside StandardError — an unimplemented #call above all — still
+  # propagates: a broken tool is a broken deploy, not a bad request.
   rescue StandardError => e
     Riffer::Tools::Response.error(
       "Error executing tool: #{e.class}: #{e.message}",

data/lib/riffer/tools/response.rb

@@ -3,39 +3,20 @@
 
 require "json"
 
-# Represents the result of a tool execution; every tool's +call+ must return one.
-#
-#   class MyTool < Riffer::Tool
-#     def call(context:, **kwargs)
-#       result = perform_operation
-#       Riffer::Tools::Response.success(result)
-#     rescue MyError => e
-#       Riffer::Tools::Response.error(e.message)
-#     end
-#   end
-#
+# Every tool's +call+ must return one.
 class Riffer::Tools::Response
   # @rbs @success: bool
 
   VALID_FORMATS = %i[text json].freeze #: Array[Symbol]
 
-  # The response content.
   attr_reader :content #: String # @dynamic content
-
-  # The error message, or +nil+ on success.
   attr_reader :error_message #: String? # @dynamic error_message
-
-  # The error type, or +nil+ on success.
   attr_reader :error_type #: Symbol? # @dynamic error_type
 
-  # The exception an unhandled failure was folded from, or +nil+. Kept out of
-  # every serialized form so it never reaches an LLM or a message payload.
+  # Kept out of every serialized form so it never reaches an LLM or a message
+  # payload.
   attr_reader :exception #: Exception? # @dynamic exception
 
-  # Creates a success response.
-  #
-  # Raises Riffer::ArgumentError if format is invalid.
-  #
   #--
   #: (untyped, ?format: Symbol) -> Riffer::Tools::Response
   def self.success(result, format: :text)
@@ -47,42 +28,32 @@ class Riffer::Tools::Response
     new(content: content, success: true)
   end
 
-  # Creates a success response with text format.
-  #
   #--
   #: (untyped) -> Riffer::Tools::Response
   def self.text(result)
     success(result, format: :text)
   end
 
-  # Creates a success response with JSON format.
-  #
   #--
   #: (untyped) -> Riffer::Tools::Response
   def self.json(result)
     success(result, format: :json)
   end
 
-  # Creates an error response.
-  #
   #--
   #: (String, ?type: Symbol, ?exception: Exception?) -> Riffer::Tools::Response
   def self.error(message, type: :execution_error, exception: nil)
     new(content: message, success: false, error_message: message, error_type: type, exception: exception)
   end
 
-  # Returns true if the tool execution succeeded.
   #--
   #: () -> bool
   def success? = @success
 
-  # Returns true if the tool execution failed.
   #--
   #: () -> bool
   def error? = !@success
 
-  # Returns a hash representation of the response.
-  #
   #--
   #: () -> Hash[Symbol, untyped]
   def to_h

data/lib/riffer/tools/runtime/fibers.rb

@@ -1,12 +1,6 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Executes tool calls concurrently using fibers via the +async+ gem.
-#
-#   class MyAgent < Riffer::Agent
-#     tool_runtime Riffer::Tools::Runtime::Fibers
-#   end
-#
 class Riffer::Tools::Runtime::Fibers < Riffer::Tools::Runtime
   #--
   #: (?max_concurrency: Integer?) -> void

data/lib/riffer/tools/runtime/inline.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Executes tool calls sequentially in the current thread — the default runtime.
 class Riffer::Tools::Runtime::Inline < Riffer::Tools::Runtime
   #--
   #: () -> void

data/lib/riffer/tools/runtime/threaded.rb

@@ -1,12 +1,6 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Executes tool calls concurrently using threads.
-#
-#   class MyAgent < Riffer::Agent
-#     tool_runtime Riffer::Tools::Runtime::Threaded
-#   end
-#
 class Riffer::Tools::Runtime::Threaded < Riffer::Tools::Runtime
   DEFAULT_MAX_CONCURRENCY = 5 #: Integer