riffer 0.47.1 → 0.47.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4ac69c8c20b892c53242b0fb792aee2ee1ce5da1ab02b1c53536fa8d1c006f08
-  data.tar.gz: 0fa02ebc739e1968167e517a41d4f0a2cabff5a5845862ac78980d207638c6cd
+  metadata.gz: b5e4c3861f4218fa075b5abd666be63eee6432db05c9a6fff3ab4285748ed7c5
+  data.tar.gz: a945c6c549c4c18b4e228cbcce1a03a48eb2b263a20bb18c9c1c51088c6a3e8c
 SHA512:
-  metadata.gz: 5c0363ce9dad27ccfc899d6c7f4e71123eaa9ae5ceec8e50387575f0642c7696f07de37cb987c45099aee999fe5ac39c8635f07f36efb784c3341bd8a4c6a6aa
-  data.tar.gz: 4b5d6209255a46d9abd52275021709740bf0e87676c20c3bd9240f12acddc7768a050391530970c2a2ed407dbdd27fb50a1b03e43caff8361ad6f28cc67884db
+  metadata.gz: 308010c98f1f44a9a13032b39fea4a2636977d9b6f232ccb9aa040ef6485f0b2d51ec3d66a69be0e4a522759cc86e42fa8b94eae6b2446a5c61ec6a3f6388892
+  data.tar.gz: dd7710eb0ed144e1dfaf49d063e5d4845068e590927092dd5b3f946b0cc0f49533262c3dc83e12dbb87fdc8356eb83890177ccf8eacc485028ca4ce7684ce01e

data/.claude/rules/rbs-inline.md

@@ -78,7 +78,11 @@ end
 
 ### Where stubs and stdlib deps live
 
-- `sig/_private/` — signatures that must **not** ship. RBS **skips** `_`-prefixed directories in library mode, so consumers never load them; riffer's own `steep check` does (via the `Steepfile`). Two kinds, by predictable path: external-gem signatures are named by gem at the top level (`async.rbs`, `mcp.rbs`, `zeitwerk.rbs`, `openai.rbs`, `anthropic.rbs`, `aws-sdk-core/*` — full stubs for RBS-less gems plus arity patches for the provider SDKs); riffer's own hidden stubs mirror `lib/` under `riffer/` (e.g. `riffer/providers/anthropic.rbs` narrows the private `client` method to the SDK-typed client).
+Dependency signatures come from [`rbs collection`](https://github.com/ruby/gem_rbs_collection): `rbs_collection.yaml` pins the upstream repo to a commit SHA, the gem set is derived from `Gemfile.lock`, and `rbs_collection.lock.yaml` is committed (the installed `.gem_rbs_collection/` is gitignored). Steep auto-detects the config, so the `Steepfile` declares no `library` lines. `yaml` is the one hand-listed entry under `gems:` — it's stdlib, so it never appears in `Gemfile.lock`.
+
+`bin/typecheck` runs `rbs collection update` before `steep check`, keeping the lock in sync with `Gemfile.lock`; CI fails on lock drift. So after a Dependabot gem bump, run `bin/typecheck` and commit the refreshed lock. To pull newer upstream stubs, bump `revision` in `rbs_collection.yaml` and run `bin/typecheck` — pinning is what makes `update` deterministic.
+
+- `sig/_private/` — signatures that must **not** ship. RBS **skips** `_`-prefixed directories in library mode, so consumers never load them; riffer's own `steep check` does (via the `Steepfile`). Two kinds, by predictable path: external-gem signatures are named by gem at the top level — full stubs for the gems upstream has nothing for (`mcp.rbs`, `zeitwerk.rbs`, `opentelemetry.rbs`, `rspec.rbs`, `aws-sdk-core/*`) plus arity patches for the provider SDKs (`openai.rbs`, `anthropic.rbs`); riffer's own hidden stubs mirror `lib/` under `riffer/` (e.g. `riffer/providers/anthropic.rbs` narrows the private `client` method to the SDK-typed client). A stub must be **deleted** once the collection covers that gem, or RBS raises `DuplicatedMethodDefinitionError`.
 - `sig/manual/` — hand-written riffer-only signatures that are **safe to ship**, for the few things rbs-inline can't generate _at all_ (mirroring `lib/`). In practice that's `extend self` modules (`riffer/agent/run.rbs`, `riffer/helpers/call_or_value.rbs`) and modeling an include applied dynamically (`riffer/tools/toolable.rbs`). SDK-free ivars are **not** hand-written here — declare them inline with `# @rbs` (see "Annotation Conventions"). SDK-typed signatures can't ship, so they go in `_private/riffer/providers/` (the narrowed `client`).
 - `sig/manifest.yaml` — declares the **stdlib** RBS the shipped sigs reference (`uri`, `net-http`) so `rbs -r riffer` resolves them.
 

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.47.1"
+  ".": "0.47.2"
 }

data/CHANGELOG.md

@@ -5,6 +5,14 @@ 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.47.2](https://github.com/janeapp/riffer/compare/riffer/v0.47.1...riffer/v0.47.2) (2026-09-21)
+
+
+### Bug Fixes
+
+* **providers:** raise IncompleteStreamError when a stream ends without its terminal event ([#445](https://github.com/janeapp/riffer/issues/445)) ([d142e23](https://github.com/janeapp/riffer/commit/d142e23e80d30ce73e81474eee35c71df1856c40))
+* stop relying on the transitive cgi gem for CGI.escapeHTML ([#443](https://github.com/janeapp/riffer/issues/443)) ([821f3e3](https://github.com/janeapp/riffer/commit/821f3e3e405845b2cc275f86344e526cc2cf183a))
+
 ## [0.47.1](https://github.com/janeapp/riffer/compare/riffer/v0.47.0...riffer/v0.47.1) (2026-09-11)
 
 

data/Rakefile

@@ -58,7 +58,7 @@ end
 namespace :steep do
   desc "Run Steep type checker"
   task :check do
-    sh "bundle exec steep check"
+    sh "bin/typecheck"
   end
 end
 

data/Steepfile

@@ -9,19 +9,5 @@ target :lib do
 
   check "lib"
 
-  library "anthropic"
-  library "aws-sdk-bedrockruntime"
-  library "aws-sdk-core"
-  library "base64"
-  library "cgi"
-  library "digest"
-  library "json"
-  library "logger"
-  library "net-http"
-  library "openai"
-  library "securerandom"
-  library "uri"
-  library "yaml"
-
-  configure_code_diagnostics(D::Ruby.strict)
+  configure_code_diagnostics(D::Ruby.all_error)
 end

data/docs/AGENTS.md

@@ -372,7 +372,7 @@ agent.generate("Summarize this ticket.",
 agent.stream("...", tags: {team: "growth", environment: "production"})
 ```
 
-Keys and values may be `String` or `Symbol`; both are stringified, and entries with a `nil` value are dropped. Passing a non-`Hash` raises `Riffer::ArgumentError`. An omitted or empty `tags:` is a complete no-op.
+Keys and values may be `String` or `Symbol`; both are stringified, and entries with a `nil` value are dropped. An omitted or empty `tags:` is a complete no-op.
 
 Tags propagate to **two** places:
 

data/docs/STREAM_EVENTS.md

@@ -272,6 +272,29 @@ event.to_h               # => {role: :assistant, finish_reason: :length, raw_fin
 
 The agent loop stamps this value onto the accumulated assistant message's `finish_reason`.
 
+## Incomplete Streams
+
+If a provider's stream ends before its terminal event, the enumerator raises `Riffer::IncompleteStreamError` (a `Riffer::Error` subclass) instead of finishing normally, so a truncated or empty response is never returned as a complete message. Events already yielded before the raise were delivered as usual, but nothing from the failed step is added to the session: there is no partial assistant message to resume from, and messages from earlier completed steps (tool calls and their results) are untouched.
+
+Supported on Amazon Bedrock, Anthropic, and OpenAI / Azure OpenAI.
+
+The user prompt is added to the session before the run starts and stays there after the failure, so retry with `agent.stream` and no prompt. Passing the prompt again would add a second user turn.
+
+```ruby
+attempts = 0
+prompt = "Tell me a story"
+begin
+  agent.stream(prompt).each do |event|
+    print event.content if event.is_a?(Riffer::StreamEvents::TextDelta)
+  end
+rescue Riffer::IncompleteStreamError => e
+  warn "stream ended early: #{e.message}"
+  prompt = nil # already in the session; re-run on the existing history
+  retry if (attempts += 1) < 3
+  raise
+end
+```
+
 ## Streaming with Tools
 
 When an agent uses tools during streaming, the flow is:

data/docs/providers/CUSTOM_PROVIDERS.md

@@ -274,6 +274,8 @@ For streaming, emit a `FinishReasonDone` event near the end of `execute_stream`:
 yielder << Riffer::StreamEvents::FinishReasonDone.new(finish_reason: :stop, raw_finish_reason: "done")
 ```
 
+Also have `execute_stream` raise `Riffer::IncompleteStreamError` when the stream ends without the provider's terminal event, rather than returning normally. Otherwise a connection that drops mid-response looks identical to a finished one, and the agent loop accepts a truncated message as complete.
+
 ## Trace Provider Name
 
 LLM-call and agent-run spans stamp `gen_ai.provider.name` from the `semconv_provider_name` class method. The default is your snake_cased class name; override it when a [GenAI semconv well-known value](https://opentelemetry.io/docs/specs/semconv/gen-ai/) exists for your provider:

data/lib/riffer/agent/config.rb

@@ -8,37 +8,37 @@ class Riffer::Agent::Config
   DEFAULT_MAX_STEPS = 16 #: Integer
 
   # The configured agent identifier.
-  attr_reader :identifier #: String?
+  attr_reader :identifier #: String? # @dynamic identifier
 
   # The configured model.
-  attr_reader :model #: (String | Proc)?
+  attr_reader :model #: (String | Proc)? # @dynamic model
 
   # The configured instructions.
-  attr_reader :instructions #: (String | Proc)?
+  attr_reader :instructions #: (String | Proc)? # @dynamic instructions
 
   # Options passed to generate_text/stream_text.
-  attr_accessor :model_options #: Hash[Symbol, untyped]
+  attr_accessor :model_options #: Hash[Symbol, untyped] # @dynamic model_options, model_options=
 
   # The configured structured-output schema.
-  attr_reader :structured_output #: Riffer::Params?
+  attr_reader :structured_output #: Riffer::Params? # @dynamic structured_output
 
   # The maximum number of LLM call steps in the tool-use loop.
-  attr_accessor :max_steps #: Numeric?
+  attr_accessor :max_steps #: Numeric? # @dynamic max_steps, max_steps=
 
   # The configured tools.
-  attr_accessor :tools_config #: (Array[singleton(Riffer::Tool)] | Proc)?
+  attr_accessor :tools_config #: (Array[singleton(Riffer::Tool)] | Proc)? # @dynamic tools_config, tools_config=
 
   # The accumulated +use_mcp+ tag configurations.
-  attr_reader :mcp_configs #: Array[Hash[Symbol, untyped]]
+  attr_reader :mcp_configs #: Array[Hash[Symbol, untyped]] # @dynamic mcp_configs
 
   # The configured tool runtime.
-  attr_reader :tool_runtime #: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)
+  attr_reader :tool_runtime #: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc) # @dynamic tool_runtime
 
   # The configured skills.
-  attr_accessor :skills_config #: Riffer::Skills::Config?
+  attr_accessor :skills_config #: Riffer::Skills::Config? # @dynamic skills_config, skills_config=
 
   # Registered guardrail entries keyed by phase.
-  attr_reader :guardrails #: Hash[Symbol, Array[Hash[Symbol, untyped]]]
+  attr_reader :guardrails #: Hash[Symbol, Array[Hash[Symbol, untyped]]] # @dynamic guardrails
 
   # Builds a new Config. Raises Riffer::ArgumentError if +model+ or
   # +instructions+ is invalid (e.g. an empty string).

data/lib/riffer/agent/outcome.rb

@@ -25,10 +25,10 @@ class Riffer::Agent::Outcome
             PROVIDER_STOP_REASONS).freeze #: Array[Symbol]
 
   # Why the run ended.
-  attr_reader :reason #: Symbol
+  attr_reader :reason #: Symbol # @dynamic reason
 
   # Human-readable specifics for +reason+, when there are any.
-  attr_reader :detail #: String?
+  attr_reader :detail #: String? # @dynamic detail
 
   # Raises Riffer::ArgumentError when +reason+ is outside VALUES.
   #--

data/lib/riffer/agent/response.rb

@@ -13,33 +13,33 @@
 #   end
 class Riffer::Agent::Response
   # The response content.
-  attr_reader :content #: String
+  attr_reader :content #: String # @dynamic content
 
   # How the run ended.
-  attr_reader :outcome #: Riffer::Agent::Outcome
+  attr_reader :outcome #: Riffer::Agent::Outcome # @dynamic outcome
 
   # The tripwire if execution was blocked.
-  attr_reader :tripwire #: Riffer::Guardrails::Tripwire?
+  attr_reader :tripwire #: Riffer::Guardrails::Tripwire? # @dynamic tripwire
 
   # The modifications made by guardrails during processing.
-  attr_reader :modifications #: Array[Riffer::Guardrails::Modification]
+  attr_reader :modifications #: Array[Riffer::Guardrails::Modification] # @dynamic modifications
 
   # The parsed structured output, if structured output was configured.
-  attr_reader :structured_output #: Hash[Symbol, untyped]?
+  attr_reader :structured_output #: Hash[Symbol, untyped]? # @dynamic structured_output
 
   # The aggregate token usage across this run's LLM calls, if any was reported.
-  attr_reader :token_usage #: Riffer::Providers::TokenUsage?
+  attr_reader :token_usage #: Riffer::Providers::TokenUsage? # @dynamic token_usage
 
   # The number of LLM calls made during this run (0 when a before-guardrail
   # blocks before any call). Distinct from the session's cumulative step count.
-  attr_reader :steps #: Integer
+  attr_reader :steps #: Integer # @dynamic steps
 
   # The full message history from the agent conversation.
-  attr_reader :messages #: Array[Riffer::Messages::Base]
+  attr_reader :messages #: Array[Riffer::Messages::Base] # @dynamic messages
 
   # Call ids of tool_use blocks riffer filled with placeholder results this
   # turn (when an interrupt left them unanswered and history healing is on).
-  attr_reader :healed_tool_call_ids #: Array[String]
+  attr_reader :healed_tool_call_ids #: Array[String] # @dynamic healed_tool_call_ids
 
   #--
   #: (

data/lib/riffer/agent/run.rb

@@ -461,7 +461,6 @@ module Riffer::Agent::Run
   #: (Hash[(String | Symbol), untyped]?) -> Hash[String, String]
   def normalize_tags(tags)
     return {} if tags.nil?
-    raise Riffer::ArgumentError, "tags: must be a Hash, got #{tags.class}" unless tags.is_a?(Hash)
 
     result = {} #: Hash[String, String]
     tags.each do |key, value|

data/lib/riffer/agent/session.rb

@@ -18,7 +18,7 @@ class Riffer::Agent::Session
   # @rbs @callbacks: Array[^(Riffer::Messages::Base) -> void]
 
   # The message history.
-  attr_reader :messages #: Array[Riffer::Messages::Base]
+  attr_reader :messages #: Array[Riffer::Messages::Base] # @dynamic messages
 
   #--
   #: (?messages: Array[Riffer::Messages::Base]) -> void

data/lib/riffer/agent/structured_output/result.rb

@@ -4,10 +4,10 @@
 # Wraps the result of structured output parsing and validation.
 class Riffer::Agent::StructuredOutput::Result
   # The validated object, or +nil+ on failure.
-  attr_reader :object #: Hash[Symbol, untyped]?
+  attr_reader :object #: Hash[Symbol, untyped]? # @dynamic object
 
   # The error message, or +nil+ on success.
-  attr_reader :error #: String?
+  attr_reader :error #: String? # @dynamic error
 
   #--
   #: (?object: Hash[Symbol, untyped]?, ?error: String?) -> void

data/lib/riffer/agent/structured_output.rb

@@ -7,7 +7,7 @@ require "json"
 # schema.
 class Riffer::Agent::StructuredOutput
   # The schema parameters.
-  attr_reader :params #: Riffer::Params
+  attr_reader :params #: Riffer::Params # @dynamic params
 
   #--
   #: (Riffer::Params) -> void

data/lib/riffer/agent.rb

@@ -214,44 +214,44 @@ class Riffer::Agent
   end
 
   # The conversation handle.
-  attr_reader :session #: Riffer::Agent::Session
+  attr_reader :session #: Riffer::Agent::Session # @dynamic session
 
   # The per-instance Riffer::Agent::Config.
-  attr_reader :config #: Riffer::Agent::Config
+  attr_reader :config #: Riffer::Agent::Config # @dynamic config
 
   # The system message built from the configured +instructions+, or +nil+ when
   # none are configured.
-  attr_reader :instruction_message #: Riffer::Messages::System?
+  attr_reader :instruction_message #: Riffer::Messages::System? # @dynamic instruction_message
 
   # The system message describing the configured skills catalog, or +nil+ when
   # skills are unconfigured or the catalog is empty.
-  attr_reader :skills_message #: Riffer::Messages::System?
+  attr_reader :skills_message #: Riffer::Messages::System? # @dynamic skills_message
 
   # The mutable runtime context shared with every +Riffer::Agent::Run+ this
   # agent executes and threaded through all Proc-based settings.
-  attr_reader :context #: Riffer::Agent::Context
+  attr_reader :context #: Riffer::Agent::Context # @dynamic context
 
   # The resolved provider name (the part before "/" in the model string),
   # e.g. +"openai"+.
-  attr_reader :provider_name #: String
+  attr_reader :provider_name #: String # @dynamic provider_name
 
   # The resolved model name (the part after "/" in the model string), used as
   # the model argument on every LLM call.
-  attr_reader :model_name #: String
+  attr_reader :model_name #: String # @dynamic model_name
 
   # The provider client. Public so tests can pre-queue responses on
   # +Riffer::Providers::Mock+ before calling +#generate+.
-  attr_reader :provider #: Riffer::Providers::Base
+  attr_reader :provider #: Riffer::Providers::Base # @dynamic provider
 
   # The +Riffer::Agent::StructuredOutput+ wrapping the configured schema, or
   # +nil+ when not configured.
-  attr_reader :structured_output #: Riffer::Agent::StructuredOutput?
+  attr_reader :structured_output #: Riffer::Agent::StructuredOutput? # @dynamic structured_output
 
   # The tool classes the LLM sees on every call this agent makes.
-  attr_reader :tools #: Array[singleton(Riffer::Tool)]
+  attr_reader :tools #: Array[singleton(Riffer::Tool)] # @dynamic tools
 
   # The tool runtime instance used to execute tool calls.
-  attr_reader :tool_runtime #: Riffer::Tools::Runtime
+  attr_reader :tool_runtime #: Riffer::Tools::Runtime # @dynamic tool_runtime
 
   # Initializes a new agent.
   #

data/lib/riffer/config.rb

@@ -16,11 +16,11 @@ class Riffer::Config
   class Skills
     # The tool class the LLM calls to activate a skill; defaults to
     # <tt>Riffer::Skills::ActivateTool</tt>.
-    attr_reader :default_activate_tool #: singleton(Riffer::Tool)
+    attr_reader :default_activate_tool #: singleton(Riffer::Tool) # @dynamic default_activate_tool
 
     # Default skills backend for agents that declare a +skills+ block without
     # one; defaults to +nil+.
-    attr_reader :default_backend #: (Riffer::Skills::Backend | Proc)?
+    attr_reader :default_backend #: (Riffer::Skills::Backend | Proc)? # @dynamic default_backend
 
     #--
     #: () -> void
@@ -61,17 +61,17 @@ class Riffer::Config
   class Tracing
     # Whether riffer emits OTEL spans; defaults to +true+, a no-op until a
     # host wires an OTEL SDK.
-    attr_reader :enabled #: bool
+    attr_reader :enabled #: bool # @dynamic enabled
 
     # Whether LLM-call spans capture full message content
     # (<tt>gen_ai.input.messages</tt>, <tt>gen_ai.output.messages</tt>,
     # <tt>gen_ai.system_instructions</tt>); defaults to +false+ — message
     # content routinely carries sensitive data.
-    attr_reader :capture_messages #: bool
+    attr_reader :capture_messages #: bool # @dynamic capture_messages
 
     # The backend riffer routes spans through; defaults to +nil+, a no-op.
     # Riffer auto-detects no backend; assigning one is opt-in.
-    attr_reader :backend #: untyped
+    attr_reader :backend #: untyped # @dynamic backend
 
     #--
     #: () -> void
@@ -118,17 +118,17 @@ class Riffer::Config
   # File-attachment-download policy for +Riffer::Messages::FilePart+ URL sources
   class Files
     # Allow file attachments to be downloaded to send to providers.
-    attr_reader :allow_downloads #: bool
+    attr_reader :allow_downloads #: bool # @dynamic allow_downloads
     # Maximum file size to download before failing.
-    attr_reader :max_bytes #: Integer
+    attr_reader :max_bytes #: Integer # @dynamic max_bytes
     # Maximum amount of time to spend downloading a file before failing.
-    attr_reader :timeout #: Integer
+    attr_reader :timeout #: Integer # @dynamic timeout
     # Maximum number of files to include in an individual message.
-    attr_reader :max_per_message #: Integer?
+    attr_reader :max_per_message #: Integer? # @dynamic max_per_message
     # Execution pattern for downloading files.
-    attr_reader :runner #: Riffer::Runner
+    attr_reader :runner #: Riffer::Runner # @dynamic runner
     # The object used to fetch a URL source's bytes
-    attr_reader :downloader #: untyped
+    attr_reader :downloader #: untyped # @dynamic downloader
 
     #--
     #: () -> void
@@ -215,16 +215,16 @@ class Riffer::Config
     # and +cache_write+ fall back to the +input+ rate when unset.
     class Rates
       # Input rate per million tokens.
-      attr_reader :input #: Float
+      attr_reader :input #: Float # @dynamic input
 
       # Output rate per million tokens.
-      attr_reader :output #: Float
+      attr_reader :output #: Float # @dynamic output
 
       # Cache-read rate per million tokens.
-      attr_reader :cache_read #: Float?
+      attr_reader :cache_read #: Float? # @dynamic cache_read
 
       # Cache-write rate per million tokens.
-      attr_reader :cache_write #: Float?
+      attr_reader :cache_write #: Float? # @dynamic cache_write
 
       #--
       #: (input: Float, output: Float, ?cache_read: Float?, ?cache_write: Float?) -> void
@@ -329,34 +329,34 @@ class Riffer::Config
   VALID_MESSAGE_ID_STRATEGIES = %i[none uuid uuidv7].freeze
 
   # Amazon Bedrock configuration.
-  attr_reader :amazon_bedrock #: Riffer::Config::AmazonBedrock
+  attr_reader :amazon_bedrock #: Riffer::Config::AmazonBedrock # @dynamic amazon_bedrock
 
   # Anthropic configuration.
-  attr_reader :anthropic #: Riffer::Config::Anthropic
+  attr_reader :anthropic #: Riffer::Config::Anthropic # @dynamic anthropic
 
   # Azure OpenAI configuration.
-  attr_reader :azure_openai #: Riffer::Config::AzureOpenAI
+  attr_reader :azure_openai #: Riffer::Config::AzureOpenAI # @dynamic azure_openai
 
   # Google Gemini configuration.
-  attr_reader :gemini #: Riffer::Config::Gemini
+  attr_reader :gemini #: Riffer::Config::Gemini # @dynamic gemini
 
   # OpenAI configuration.
-  attr_reader :openai #: Riffer::Config::OpenAI
+  attr_reader :openai #: Riffer::Config::OpenAI # @dynamic openai
 
   # OpenRouter configuration.
-  attr_reader :openrouter #: Riffer::Config::OpenRouter
+  attr_reader :openrouter #: Riffer::Config::OpenRouter # @dynamic openrouter
 
   # Evals configuration.
-  attr_reader :evals #: Riffer::Config::Evals
+  attr_reader :evals #: Riffer::Config::Evals # @dynamic evals
 
   # MCP configuration. +credentials+ is an optional Proc returning per-run
   # +tools/call+ headers (or +nil+ to deny); +discovery_runner+ runs tool
   # discovery.
-  attr_reader :mcp #: Riffer::Config::Mcp
+  attr_reader :mcp #: Riffer::Config::Mcp # @dynamic mcp
 
   # Global tool runtime configuration (experimental); defaults to
   # <tt>Riffer::Tools::Runtime::Inline.new</tt>.
-  attr_reader :tool_runtime #: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)
+  attr_reader :tool_runtime #: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc) # @dynamic tool_runtime
 
   # Sets the global tool runtime. Raises Riffer::ArgumentError on an invalid
   # value.
@@ -374,20 +374,20 @@ class Riffer::Config
   end
 
   # Skills-related global configuration.
-  attr_reader :skills #: Riffer::Config::Skills
+  attr_reader :skills #: Riffer::Config::Skills # @dynamic skills
 
   # Tracing-related global configuration.
-  attr_reader :tracing #: Riffer::Config::Tracing
+  attr_reader :tracing #: Riffer::Config::Tracing # @dynamic tracing
 
-  attr_reader :files #: Riffer::Config::Files
+  attr_reader :files #: Riffer::Config::Files # @dynamic files
 
   # Consumer-configured per-model token pricing.
-  attr_reader :pricing #: Riffer::Config::Pricing
+  attr_reader :pricing #: Riffer::Config::Pricing # @dynamic pricing
 
   # Strategy for auto-generating message ids: +:none+ (default), +:uuid+, or
   # +:uuidv7+. When not +:none+, messages get an +id+ at construction, and
   # seeded messages passed to +Riffer::Agent#generate+ must carry their own.
-  attr_reader :message_id_strategy #: Symbol
+  attr_reader :message_id_strategy #: Symbol # @dynamic message_id_strategy
 
   # Sets the message id strategy. Raises Riffer::ArgumentError unless the value
   # is +:none+, +:uuid+, or +:uuidv7+.
@@ -404,7 +404,7 @@ class Riffer::Config
   # Experimental: when +true+, riffer maintains the +tool_use+ ↔ +tool_result+
   # invariant itself — stripping orphaned exchanges and filling interrupted
   # ones. Defaults to +false+; the surface may change without notice.
-  attr_reader :experimental_history_healing #: bool
+  attr_reader :experimental_history_healing #: bool # @dynamic experimental_history_healing
 
   # Sets the +experimental_history_healing+ flag, coercing boolean-ish values so
   # an env-var +"false"+ (truthy in Ruby) doesn't silently enable healing.

data/lib/riffer/evals/judge.rb

@@ -28,7 +28,7 @@ class Riffer::Evals::Judge
   end
 
   # The model string (provider/model format).
-  attr_reader :model #: String
+  attr_reader :model #: String # @dynamic model
 
   # Raises Riffer::ArgumentError unless +model+ is "provider/model" format.
   #--
@@ -109,8 +109,7 @@ class Riffer::Evals::Judge
   #--
   #: (Riffer::Messages::Assistant) -> Hash[Symbol, untyped]
   def parse_tool_response(response)
-    tool_call = response.tool_calls.first
-    raise Riffer::Error, "Invalid judge response: no tool call found" unless tool_call
+    tool_call = response.tool_calls.fetch(0) { raise Riffer::Error, "Invalid judge response: no tool call found" }
 
     parsed = JSON.parse(tool_call[:arguments], symbolize_names: true)
     score = parsed[:score]

data/lib/riffer/evals/result.rb

@@ -4,23 +4,23 @@
 # Represents the result of a single evaluation.
 class Riffer::Evals::Result
   # The evaluator class that produced this result.
-  attr_reader :evaluator #: singleton(Riffer::Evals::Evaluator)
+  attr_reader :evaluator #: singleton(Riffer::Evals::Evaluator) # @dynamic evaluator
 
   # The evaluation score (0.0 to 1.0).
-  attr_reader :score #: Float
+  attr_reader :score #: Float # @dynamic score
 
   # Human-readable explanation of the score.
-  attr_reader :reason #: String?
+  attr_reader :reason #: String? # @dynamic reason
 
   # Additional metadata from the evaluation.
-  attr_reader :metadata #: Hash[Symbol, untyped]
+  attr_reader :metadata #: Hash[Symbol, untyped] # @dynamic metadata
 
   # Whether higher scores are better for this evaluator.
-  attr_reader :higher_is_better #: bool
+  attr_reader :higher_is_better #: bool # @dynamic higher_is_better
 
   # Token usage for the judge call that produced this result, when the
   # evaluator used an LLM. Nil for rule-based evaluators.
-  attr_reader :token_usage #: Riffer::Providers::TokenUsage?
+  attr_reader :token_usage #: Riffer::Providers::TokenUsage? # @dynamic token_usage
 
   # Raises Riffer::ArgumentError if +score+ is not between 0.0 and 1.0.
   #--

data/lib/riffer/evals/run_result.rb

@@ -4,7 +4,7 @@
 # Represents the complete result of an evaluation run across multiple scenarios.
 class Riffer::Evals::RunResult
   # Per-scenario evaluation results.
-  attr_reader :scenario_results #: Array[Riffer::Evals::ScenarioResult]
+  attr_reader :scenario_results #: Array[Riffer::Evals::ScenarioResult] # @dynamic scenario_results
 
   #--
   #: (scenario_results: Array[Riffer::Evals::ScenarioResult]) -> void

data/lib/riffer/evals/scenario_result.rb

@@ -4,22 +4,22 @@
 # Represents the result of evaluating a single scenario.
 class Riffer::Evals::ScenarioResult
   # The input that was evaluated.
-  attr_reader :input #: String
+  attr_reader :input #: String # @dynamic input
 
   # The agent output for this scenario.
-  attr_reader :output #: String
+  attr_reader :output #: String # @dynamic output
 
   # The ground truth used during evaluation.
-  attr_reader :ground_truth #: String?
+  attr_reader :ground_truth #: String? # @dynamic ground_truth
 
   # Individual evaluation results.
-  attr_reader :results #: Array[Riffer::Evals::Result]
+  attr_reader :results #: Array[Riffer::Evals::Result] # @dynamic results
 
   # The full message history from the agent conversation.
-  attr_reader :messages #: Array[Riffer::Messages::Base]
+  attr_reader :messages #: Array[Riffer::Messages::Base] # @dynamic messages
 
   # Token usage the agent under test spent generating this scenario's output.
-  attr_reader :token_usage #: Riffer::Providers::TokenUsage?
+  attr_reader :token_usage #: Riffer::Providers::TokenUsage? # @dynamic token_usage
 
   #--
   #: (input: String, output: String, ground_truth: String?, results: Array[Riffer::Evals::Result], ?messages: Array[Riffer::Messages::Base], ?token_usage: Riffer::Providers::TokenUsage?) -> void

data/lib/riffer/guardrails/modification.rb

@@ -4,13 +4,13 @@
 # Records a guardrail transformation event.
 class Riffer::Guardrails::Modification
   # The guardrail class that transformed data.
-  attr_reader :guardrail #: singleton(Riffer::Guardrail)
+  attr_reader :guardrail #: singleton(Riffer::Guardrail) # @dynamic guardrail
 
   # The phase when the transformation occurred (:before or :after).
-  attr_reader :phase #: Symbol
+  attr_reader :phase #: Symbol # @dynamic phase
 
   # The indices of messages that were changed.
-  attr_reader :message_indices #: Array[Integer]
+  attr_reader :message_indices #: Array[Integer] # @dynamic message_indices
 
   #--
   #: (guardrail: singleton(Riffer::Guardrail), phase: Symbol, message_indices: Array[Integer]) -> void

data/lib/riffer/guardrails/result.rb

@@ -7,13 +7,13 @@ class Riffer::Guardrails::Result
   TYPES = %i[pass transform block].freeze #: Array[Symbol]
 
   # The result type (:pass, :transform, or :block).
-  attr_reader :type #: Symbol
+  attr_reader :type #: Symbol # @dynamic type
 
   # The data (for pass/transform) or reason (for block).
-  attr_reader :data #: untyped
+  attr_reader :data #: untyped # @dynamic data
 
   # Optional metadata for block results.
-  attr_reader :metadata #: Hash[Symbol, untyped]?
+  attr_reader :metadata #: Hash[Symbol, untyped]? # @dynamic metadata
 
   class << self
     # Creates a pass result that continues with unchanged data.