riffer 0.42.0 → 0.43.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eabed1a1a6844787d92f31be0a72e210117005c19b4dd5e021a905121f83e8e1
-  data.tar.gz: 4cc6b6bde7e4b474d7ca6fb2672a3e115d4584b096f1de5d967a2b1a751f49ba
+  metadata.gz: bed1103d2399d8532635b4041d4a24b8264f160b58a3110436ed67a14380fd56
+  data.tar.gz: acdaa65506e0c4887d388663be686bc02ccf668c26db281148efcec9f5772d6b
 SHA512:
-  metadata.gz: 220febe23864053fa767e3eecc6850dc0c25ebdcb363a86d5daa58cd317c5500d08f2b50f499f133a77d7b4cf5182485c6faf0ddf36550099b22b7dd203af0c6
-  data.tar.gz: d231a4b0dc8c0468f4cba1abf9e3ace390852efc4b6adf5c23229c6729d4ad71fb0afdd5ae5b50540a188b79ec519ef58f95972357fb9854398570d0de058781
+  metadata.gz: 0733aa1731a7206195862e6bfd59936b80cc3219fa913a6afce577a8de9d8f4510ca59316a6bb27c6a778706b6d231ce61cd74ebd9d63f32d2a695453b2bd5ae
+  data.tar.gz: da09bd24389e52f79c7cbe3dd977c5ada7bc9f0a923f2d09d2331245b4ca1fd079f9f688da0ab8b36eac6b1a260bd627831dc0c344ae93422f5a006c929a11e3

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.42.0"
+  ".": "0.43.0"
 }

data/CHANGELOG.md

@@ -5,6 +5,17 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.43.0](https://github.com/janeapp/riffer/compare/riffer/v0.42.0...riffer/v0.43.0) (2026-08-27)
+
+
+### ⚠ BREAKING CHANGES
+
+* call_with_validation no longer raises Riffer::ValidationError / Riffer::TimeoutError / Riffer::Error — it always returns a Riffer::Tools::Response. Riffer::TimeoutError has been removed; delete any `rescue Riffer::TimeoutError` and check `response.error_type` instead. Custom runtimes overriding dispatch_tool_call no longer inherit rescues from the base class.
+
+### Features
+
+* tools are the error boundary — call_with_validation never raises ([#412](https://github.com/janeapp/riffer/issues/412)) ([b6db9b6](https://github.com/janeapp/riffer/commit/b6db9b6ab2885d170cbba52c7a571c63b83d892e))
+
 ## [0.42.0](https://github.com/janeapp/riffer/compare/riffer/v0.41.0...riffer/v0.42.0) (2026-08-25)
 
 

data/docs/AGENT_LOOP.md

@@ -15,13 +15,15 @@ When an agent receives a response with tool calls:
 
 ## Error Handling
 
-Tool execution errors are captured and sent back to the LLM:
+Tool execution errors never abort the loop — each is captured and sent back to the LLM as a tool result:
 
 - `unknown_tool` - Tool not found in registered tools
-- `validation_error` - Arguments failed validation
-- `execution_error` - Tool raised an exception
+- `validation_error` - Arguments failed validation or were malformed JSON
+- `timeout_error` - Tool exceeded its configured timeout
+- `execution_error` - Tool returned an error or raised `Riffer::ToolExecutionError`
+- `unhandled_error` - Tool raised an unanticipated exception
 
-The LLM can use this information to retry or respond appropriately.
+The LLM can use this information to retry or respond appropriately. See [Error Handling](TOOL_ADVANCED.md#error-handling) for details.
 
 ## Ways the Agent Loop Can Stop
 

data/docs/TOOLS.md

@@ -269,7 +269,7 @@ error("Service unavailable", type: :service_error)
 error("Rate limit exceeded", type: :rate_limit)
 ```
 
-If no type is specified, it defaults to `:execution_error`.
+If no type is specified, it defaults to `:execution_error`. Riffer reserves `:unhandled_error` for unrescued exceptions — don't set it yourself.
 
 ### Using Riffer::Tools::Response Directly
 
@@ -297,4 +297,7 @@ error_response.success?       # => false
 error_response.error?         # => true
 error_response.error_message  # => "failed"
 error_response.error_type     # => :not_found
+error_response.exception      # => nil
 ```
+
+`exception` holds the rescued exception on the `:unhandled_error` responses Riffer builds. It never appears in serialized output, so it is not visible to the LLM.

data/docs/TOOL_ADVANCED.md

@@ -16,7 +16,7 @@ class SlowExternalApiTool < Riffer::Tool
 end
 ```
 
-When a tool times out, the error is reported to the LLM with error type `:timeout_error`, allowing it to respond appropriately (e.g., suggest retrying or using a different approach).
+When a tool times out, the LLM receives an error response with type `:timeout_error` and can respond appropriately (e.g., suggest retrying or using a different approach). The timeout raises `Riffer::TimeoutError` inside `call`, so a tool can rescue it to release resources before it propagates.
 
 ## Validation
 
@@ -26,7 +26,7 @@ Arguments are automatically validated before `call` is invoked:
 - Types must match the schema
 - Enum values must be in the allowed list
 
-Validation errors are captured and sent back to the LLM as tool results with error type `:validation_error`.
+Validation errors are captured and sent back to the LLM as tool results with error type `:validation_error`, as is malformed or non-object JSON in the provider's tool-call arguments.
 
 ## JSON Schema Generation
 
@@ -95,7 +95,20 @@ rescue => e
 end
 ```
 
-Unhandled `RuntimeError` exceptions are caught by Riffer and converted to error responses with type `:execution_error`. For expected execution errors, raise `Riffer::ToolExecutionError` — these are also caught and returned to the LLM. Programming bugs (`NoMethodError`, `NameError`, `TypeError`, etc.) propagate to the caller. It's recommended to handle expected errors explicitly for better error messages.
+A tool never raises into the agent loop — every `StandardError` raised during a tool call becomes an error response:
+
+| Failure                      | Error type          | Response content                                     |
+| ---------------------------- | ------------------- | ---------------------------------------------------- |
+| Invalid arguments            | `:validation_error` | the validation message                               |
+| Timeout                      | `:timeout_error`    | `Tool execution timed out after N seconds`           |
+| `Riffer::ToolExecutionError` | `:execution_error`  | the exception message                                |
+| Any other `StandardError`    | `:unhandled_error`  | `Error executing tool: <ExceptionClass>: <message>` |
+
+An `:unhandled_error` response also carries the rescued exception on `response.exception` — never serialized, so it stays out of the message history — and its `execute_tool` span records the exception with an `ERROR` status (see [Tracing](TRACING.md)).
+
+`NotImplementedError` is not rescued: an unimplemented `#call` raises out of the run.
+
+For expected failures, return `error(...)` or raise `Riffer::ToolExecutionError` — both give the LLM a clean message rather than an `:unhandled_error`.
 
 The LLM receives the error message and can decide how to respond (retry, apologize, ask for different input, etc.).
 
@@ -222,14 +235,14 @@ class HttpToolRuntime < Riffer::Tools::Runtime
       arguments: tool_call.arguments
     })
     Riffer::Tools::Response.text(response.body)
-  rescue Riffer::ToolExecutionError => e
-    Riffer::Tools::Response.error(e.message, type: :execution_error)
-  rescue RuntimeError => e
-    Riffer::Tools::Response.error("Error executing tool: #{e.message}", type: :execution_error)
+  rescue HttpClient::Error => e
+    Riffer::Tools::Response.error("Tool service unavailable: #{e.message}", type: :execution_error)
   end
 end
 ```
 
+Anything that escapes `dispatch_tool_call` propagates out of the run — rescue whatever your transport can raise and return an error response. The base class handles only an unknown tool name and malformed argument JSON.
+
 ### Around-Call Hook
 
 Each tool call is wrapped by the `around_tool_call` method, which yields by default. Override it in a subclass to add instrumentation, logging, or other cross-cutting concerns:

data/docs/TRACING.md

@@ -168,12 +168,13 @@ Usage on this span is the run total, aggregated across every step. See [Token us
 | `gen_ai.tool.call.arguments` | string | When `capture_messages` is on (see [capture](#message-content-capture)) |
 | `gen_ai.tool.call.result`    | string | When `capture_messages` is on                                           |
 
-A tool failure comes in two shapes, distinguished by span status:
+A tool failure comes in three shapes, distinguished by span status:
 
-- **Handled error** — the tool returned an error response. `error.type` carries the category and the **span status stays unset** (the run continues). The framework's categories are `unknown_tool`, `validation_error`, `timeout_error`, and `execution_error`; a custom tool may set its own via `Riffer::Tools::Response.error(type:)`.
-- **Unhandled exception** — the dispatch raised. `error.type` is the exception class name and the **span status is `ERROR`**, with the exception recorded.
+- **Handled error** — the tool call produced a deliberate error response, from the tool itself or from the runtime (an unknown tool, malformed arguments). `error.type` carries the category and the **span status stays unset** (the run continues). The framework's categories are `unknown_tool`, `validation_error`, `timeout_error`, and `execution_error`; a custom tool may set its own via `Riffer::Tools::Response.error(type:)`.
+- **Unhandled error** — the tool raised an unanticipated `StandardError`. `error.type` is `unhandled_error`, the **span status is `ERROR`**, and the exception is recorded on the span. The run continues — the LLM receives the error response.
+- **Host code raising** around the tool call (an `around_tool_call` hook, a tracing callback) propagates out of the run. `error.type` is the exception class name and the span status is `ERROR`.
 
-This status convention is the same on `chat` and `invoke_agent`: an unhandled exception sets `error.type` to the class name and marks the span `ERROR`; everything else leaves the status unset.
+This status convention is the same on `chat` and `invoke_agent`: an unhandled exception marks the span `ERROR` with the exception recorded; a handled outcome leaves the status unset.
 
 ## `execute_guardrail {name}` — the guardrail span
 

data/lib/riffer/messages/tool.rb

@@ -12,7 +12,8 @@ class Riffer::Messages::Tool < Riffer::Messages::Base
   # The error message if the tool execution failed.
   attr_reader :error #: String?
 
-  # The type of error (:unknown_tool, :validation_error, :execution_error, :timeout_error).
+  # The type of error (:unknown_tool, :validation_error, :execution_error,
+  # :timeout_error, :unhandled_error).
   attr_reader :error_type #: Symbol?
 
   #--

data/lib/riffer/tool.rb

@@ -56,19 +56,23 @@ class Riffer::Tool
     Riffer::Tools::Response.error(message, type: type)
   end
 
-  # Executes the tool with validation and timeout (used by Agent).
-  #
-  # Raises Riffer::ValidationError if validation fails.
-  # Raises Riffer::TimeoutError if execution exceeds the configured timeout.
-  # Raises Riffer::Error if the tool does not return a Response object.
+  # 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)
     params_builder = self.class.params
-    validated_args = params_builder ? params_builder.validate(kwargs) : kwargs
 
-    result = Timeout.timeout(self.class.timeout) do
+    begin
+      validated_args = params_builder ? params_builder.validate(kwargs) : kwargs
+    rescue Riffer::ValidationError => e
+      return Riffer::Tools::Response.error(e.message, type: :validation_error)
+    end
+
+    result = Timeout.timeout(self.class.timeout, Riffer::TimeoutError) do
       call(context: context, **validated_args) #: untyped
     end
 
@@ -77,7 +81,18 @@ class Riffer::Tool
     end
 
     result
-  rescue Timeout::Error
-    raise Riffer::TimeoutError, "Tool execution timed out after #{self.class.timeout} seconds"
+  rescue Riffer::TimeoutError
+    Riffer::Tools::Response.error(
+      "Tool execution timed out after #{self.class.timeout} seconds",
+      type: :timeout_error,
+    )
+  rescue Riffer::ToolExecutionError => e
+    Riffer::Tools::Response.error(e.message, type: :execution_error)
+  rescue StandardError => e
+    Riffer::Tools::Response.error(
+      "Error executing tool: #{e.class}: #{e.message}",
+      type: :unhandled_error,
+      exception: e,
+    )
   end
 end

data/lib/riffer/tools/response.rb

@@ -28,6 +28,10 @@ class Riffer::Tools::Response
   # The error type, or +nil+ on success.
   attr_reader :error_type #: Symbol?
 
+  # 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.
+  attr_reader :exception #: Exception?
+
   # Creates a success response.
   #
   # Raises Riffer::ArgumentError if format is invalid.
@@ -62,9 +66,9 @@ class Riffer::Tools::Response
   # Creates an error response.
   #
   #--
-  #: (String, ?type: Symbol) -> Riffer::Tools::Response
-  def self.error(message, type: :execution_error)
-    new(content: message, success: false, error_message: message, error_type: type)
+  #: (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.
@@ -88,11 +92,12 @@ class Riffer::Tools::Response
   private
 
   #--
-  #: (content: String, success: bool, ?error_message: String?, ?error_type: Symbol?) -> void
-  def initialize(content:, success:, error_message: nil, error_type: nil)
+  #: (content: String, success: bool, ?error_message: String?, ?error_type: Symbol?, ?exception: Exception?) -> void
+  def initialize(content:, success:, error_message: nil, error_type: nil, exception: nil)
     @content = content
     @success = success
     @error_message = error_message
     @error_type = error_type
+    @exception = exception
   end
 end

data/lib/riffer/tools/runtime.rb

@@ -88,19 +88,20 @@ class Riffer::Tools::Runtime
     tool_instance = tool_class.new
     arguments = parse_arguments(tool_call.arguments)
 
+    unless arguments.is_a?(Hash)
+      return Riffer::Tools::Response.error(
+        "Invalid JSON in tool arguments: expected an object, got #{arguments.class}",
+        type: :validation_error,
+      )
+    end
+
     tool_instance.call_with_validation(context: context, **arguments)
-  rescue Riffer::TimeoutError => e
-    Riffer::Tools::Response.error(e.message, type: :timeout_error)
-  rescue Riffer::ValidationError => e
-    Riffer::Tools::Response.error(e.message, type: :validation_error)
-  rescue Riffer::ToolExecutionError => e
-    Riffer::Tools::Response.error(e.message, type: :execution_error)
-  rescue RuntimeError => e
-    Riffer::Tools::Response.error("Error executing tool: #{e.message}", type: :execution_error)
+  rescue JSON::ParserError => e
+    Riffer::Tools::Response.error("Invalid JSON in tool arguments: #{e.message}", type: :validation_error)
   end
 
   #--
-  #: (String?) -> Hash[Symbol, untyped]
+  #: (String?) -> untyped
   def parse_arguments(arguments)
     return {} if arguments.nil? || arguments.empty?
 
@@ -144,13 +145,21 @@ class Riffer::Tools::Runtime
     tags.transform_keys { |key| "riffer.tag.#{key}" }
   end
 
-  # A returned error Response is a handled outcome, so its status stays unset —
-  # an error span status is reserved for a raised exception.
+  # 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
+
+    exception = result.exception
+    if exception
+      span.record_exception(exception)
+      span.error!(exception.message)
+    end
+
     capture_tool_result(span, result)
   end
 

data/lib/riffer/version.rb

@@ -2,5 +2,5 @@
 # rbs_inline: enabled
 
 module Riffer
-  VERSION = "0.42.0" #: String
+  VERSION = "0.43.0" #: String
 end

data/lib/riffer.rb

@@ -26,7 +26,9 @@ module Riffer
   # Raised when tool parameter validation fails.
   class ValidationError < Error; end
 
-  # Raised when tool execution times out.
+  # Raised inside a tool's +call+ when execution exceeds the configured
+  # timeout. Rescue it in the tool to clean up; otherwise it becomes a
+  # +:timeout_error+ response.
   class TimeoutError < Error; end
 
   # Raised when a tool encounters an expected execution error.

data/sig/generated/riffer/messages/tool.rbs

@@ -11,7 +11,8 @@ class Riffer::Messages::Tool < Riffer::Messages::Base
   # The error message if the tool execution failed.
   attr_reader error: String?
 
-  # The type of error (:unknown_tool, :validation_error, :execution_error, :timeout_error).
+  # The type of error (:unknown_tool, :validation_error, :execution_error,
+  # :timeout_error, :unhandled_error).
   attr_reader error_type: Symbol?
 
   # --

data/sig/generated/riffer/tool.rbs

@@ -43,11 +43,10 @@ class Riffer::Tool
   # : (String, ?type: Symbol) -> Riffer::Tools::Response
   def error: (String, ?type: Symbol) -> Riffer::Tools::Response
 
-  # Executes the tool with validation and timeout (used by Agent).
-  #
-  # Raises Riffer::ValidationError if validation fails.
-  # Raises Riffer::TimeoutError if execution exceeds the configured timeout.
-  # Raises Riffer::Error if the tool does not return a Response object.
+  # 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

data/sig/generated/riffer/tools/response.rbs

@@ -24,6 +24,10 @@ class Riffer::Tools::Response
   # The error type, or +nil+ on success.
   attr_reader error_type: Symbol?
 
+  # 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.
+  attr_reader exception: Exception?
+
   # Creates a success response.
   #
   # Raises Riffer::ArgumentError if format is invalid.
@@ -47,8 +51,8 @@ class Riffer::Tools::Response
   # Creates an error response.
   #
   # --
-  # : (String, ?type: Symbol) -> Riffer::Tools::Response
-  def self.error: (String, ?type: Symbol) -> Riffer::Tools::Response
+  # : (String, ?type: Symbol, ?exception: Exception?) -> Riffer::Tools::Response
+  def self.error: (String, ?type: Symbol, ?exception: Exception?) -> Riffer::Tools::Response
 
   # Returns true if the tool execution succeeded.
   # --
@@ -69,6 +73,6 @@ class Riffer::Tools::Response
   private
 
   # --
-  # : (content: String, success: bool, ?error_message: String?, ?error_type: Symbol?) -> void
-  def initialize: (content: String, success: bool, ?error_message: String?, ?error_type: Symbol?) -> void
+  # : (content: String, success: bool, ?error_message: String?, ?error_type: Symbol?, ?exception: Exception?) -> void
+  def initialize: (content: String, success: bool, ?error_message: String?, ?error_type: Symbol?, ?exception: Exception?) -> void
 end

data/sig/generated/riffer/tools/runtime.rbs

@@ -44,8 +44,8 @@ class Riffer::Tools::Runtime
   def dispatch_tool_call: (Riffer::Messages::Assistant::ToolCall, tools: Array[singleton(Riffer::Tool)], context: Riffer::Agent::Context?, ?assistant_message: Riffer::Messages::Assistant?) -> Riffer::Tools::Response
 
   # --
-  # : (String?) -> Hash[Symbol, untyped]
-  def parse_arguments: (String?) -> Hash[Symbol, untyped]
+  # : (String?) -> untyped
+  def parse_arguments: (String?) -> untyped
 
   # Emitted outside +around_tool_call+ so host enrichment spans nest beneath it.
   # --
@@ -62,8 +62,9 @@ class Riffer::Tools::Runtime
   # : (Hash[String, String]) -> Hash[String, String]
   def tag_attributes: (Hash[String, String]) -> Hash[String, String]
 
-  # A returned error Response is a handled outcome, so its status stays unset —
-  # an error span status is reserved for a raised exception.
+  # 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: (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span, Riffer::Tools::Response) -> void

data/sig/generated/riffer.rbs

@@ -15,7 +15,9 @@ module Riffer
   class ValidationError < Error
   end
 
-  # Raised when tool execution times out.
+  # Raised inside a tool's +call+ when execution exceeds the configured
+  # timeout. Rescue it in the tool to clean up; otherwise it becomes a
+  # +:timeout_error+ response.
   class TimeoutError < Error
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: riffer
 version: !ruby/object:Gem::Version
-  version: 0.42.0
+  version: 0.43.0
 platform: ruby
 authors:
 - Jake Bottrall