riffer 0.48.0 → 0.49.0

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,12 +1,8 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Represents one completed reasoning block during streaming; only emitted by
-# providers that support reasoning (e.g. OpenAI with the reasoning option).
 class Riffer::StreamEvents::ReasoningDone < Riffer::StreamEvents::Base
-  # The reasoning block, which the agent loop accumulates onto the assistant
-  # message. Its +text+ is the content the preceding ReasoningDelta events
-  # added up to.
+  # +text+ is the concatenation of the preceding ReasoningDelta events.
   attr_reader :part #: Riffer::Messages::Assistant::ReasoningPart # @dynamic part
 
   #--

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
 

data/lib/riffer/tools/runtime.rb

@@ -3,9 +3,6 @@
 
 require "json"
 
-# Handles tool call execution for an agent, composing with a Riffer::Runner for
-# concurrency. Subclass and override +dispatch_tool_call+ to customize dispatch
-# (e.g. HTTP, gRPC).
 class Riffer::Tools::Runtime
   # @rbs @runner: Riffer::Runner
 
@@ -20,17 +17,15 @@ class Riffer::Tools::Runtime
     @runner = runner
   end
 
-  # Executes a batch of tool calls, returning <tt>[tool_call, response]</tt> pairs.
   #--
   #: (Array[Riffer::Messages::Assistant::ToolCall], tools: Array[singleton(Riffer::Tool)], context: Riffer::Agent::Context?, ?assistant_message: Riffer::Messages::Assistant?, ?tags: Hash[String, String]) -> Array[[Riffer::Messages::Assistant::ToolCall, Riffer::Tools::Response]]
   def execute(tool_calls, tools:, context:, assistant_message: nil, tags: {})
     # Each Runner worker runs in its own thread/fiber, where the OTEL context
     # starts empty — capture here so the execute_tool span parents correctly.
-    # tags are an ordinary local captured in the block, so they reach the
-    # worker's span without re-propagation.
     trace_context = Riffer::Tracing.current_context
     @runner.map(tool_calls, context: context) do |tool_call|
       Riffer::Tracing.with_context(trace_context) do
+        # Outside around_tool_call so host enrichment spans nest beneath it.
         instrument_tool_call(tool_call, tags) do
           around_tool_call(tool_call, context: context, assistant_message: assistant_message) do
             dispatch_tool_call(tool_call, tools: tools, context: context, assistant_message: assistant_message)
@@ -40,20 +35,7 @@ class Riffer::Tools::Runtime
     end
   end
 
-  # Hook wrapping each tool call; override in subclasses to instrument or
-  # customize. Must +yield+ to continue.
-  #
-  #   class InstrumentedRuntime < Riffer::Tools::Runtime::Inline
-  #     private
-  #
-  #     def around_tool_call(tool_call, context:, assistant_message: nil)
-  #       start = Time.now
-  #       result = yield
-  #       Rails.logger.info("Tool #{tool_call.name} took #{Time.now - start}s")
-  #       result
-  #     end
-  #   end
-  #
+  # Overrides must +yield+ and return its Response.
   #--
   #: (Riffer::Messages::Assistant::ToolCall, context: Riffer::Agent::Context?, ?assistant_message: Riffer::Messages::Assistant?) { () -> Riffer::Tools::Response } -> Riffer::Tools::Response
   def around_tool_call(_tool_call, context:, assistant_message: nil)
@@ -73,6 +55,7 @@ class Riffer::Tools::Runtime
     [tool_call, result] #: [Riffer::Messages::Assistant::ToolCall, Riffer::Tools::Response]
   end
 
+  # Subclasses override this to dispatch elsewhere (e.g. HTTP, gRPC).
   #--
   #: (Riffer::Messages::Assistant::ToolCall, tools: Array[singleton(Riffer::Tool)], context: Riffer::Agent::Context?, ?assistant_message: Riffer::Messages::Assistant?) -> Riffer::Tools::Response
   def dispatch_tool_call(tool_call, tools:, context:, assistant_message: nil)
@@ -108,7 +91,6 @@ class Riffer::Tools::Runtime
     JSON.parse(arguments, symbolize_names: true)
   end
 
-  # Emitted outside +around_tool_call+ so host enrichment spans nest beneath it.
   #--
   #: [R] (Riffer::Messages::Assistant::ToolCall, ?Hash[String, String]) { ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span)) -> R } -> R
   def in_tool_span(tool_call, tags = {})
@@ -137,23 +119,20 @@ class Riffer::Tools::Runtime
     }.merge(tag_attributes(tags))
   end
 
-  # Maps normalized tags to their namespaced span attribute form. An empty map
-  # yields an empty hash, so merging it is a no-op.
   #--
   #: (Hash[String, String]) -> Hash[String, String]
   def tag_attributes(tags)
     tags.transform_keys { |key| "riffer.tag.#{key}" }
   end
 
-  # A deliberate error Response is a handled outcome, so its status stays unset.
-  # An error status is reserved for a Response carrying the exception it was
-  # folded from — the tool failed for a reason nobody anticipated.
   #--
   #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span), Riffer::Tools::Response) -> void
   def record_tool_outcome(span, result)
     error_type = result.error_type
     span.set_attribute("error.type", error_type.to_s) if error_type
 
+    # A deliberate error Response is a handled outcome, so only one carrying the
+    # exception it was folded from gets an error status.
     exception = result.exception
     if exception
       span.record_exception(exception)