riffer 0.43.0 → 0.44.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bed1103d2399d8532635b4041d4a24b8264f160b58a3110436ed67a14380fd56
-  data.tar.gz: acdaa65506e0c4887d388663be686bc02ccf668c26db281148efcec9f5772d6b
+  metadata.gz: 7f7862ed670d852eee1e076386032449773a8782424fbfc9bc80e96aab61b1e3
+  data.tar.gz: b520d7629441e6acd75a677bc3d094359f5a5b7f31c2986d6aadd51f2935b3e1
 SHA512:
-  metadata.gz: 0733aa1731a7206195862e6bfd59936b80cc3219fa913a6afce577a8de9d8f4510ca59316a6bb27c6a778706b6d231ce61cd74ebd9d63f32d2a695453b2bd5ae
-  data.tar.gz: da09bd24389e52f79c7cbe3dd977c5ada7bc9f0a923f2d09d2331245b4ca1fd079f9f688da0ab8b36eac6b1a260bd627831dc0c344ae93422f5a006c929a11e3
+  metadata.gz: '069d1d96193748ffdc48eb95a8fe22b57c6293a33e7ba4658a01fda4e5c4a7847145bb234605c0507059830c300dc2d85ec295ecf2d59de20265385644d6dc89'
+  data.tar.gz: 86bbcfb5408f3b5ba0fbb327dff9c2a98c0ee410e3ce4ab72c89a3a66d8aaa8e4d095e2ee14bc32c814caa28503cf0d099095441a60eb4cb9e11b7639f522d65

data/.release-please-manifest.json

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

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.44.0](https://github.com/janeapp/riffer/compare/riffer/v0.43.0...riffer/v0.44.0) (2026-08-28)
+
+
+### Features
+
+* file attachment downloading for user messages ([#407](https://github.com/janeapp/riffer/issues/407)) ([4e78868](https://github.com/janeapp/riffer/commit/4e78868f7d1efe59c35906fff2ba7594ccbd6de7))
+* registry liveness, explicit registration, and Riffer::Testing stub factories ([#415](https://github.com/janeapp/riffer/issues/415)) ([6935749](https://github.com/janeapp/riffer/commit/69357496b094fcfa9e72d12a525645374ef6e352))
+
 ## [0.43.0](https://github.com/janeapp/riffer/compare/riffer/v0.42.0...riffer/v0.43.0) (2026-08-27)
 
 

data/Steepfile

@@ -14,6 +14,7 @@ target :lib do
   library "aws-sdk-core"
   library "base64"
   library "cgi"
+  library "digest"
   library "json"
   library "logger"
   library "net-http"

data/docs/AGENTS.md

@@ -321,11 +321,32 @@ Riffer::Agent.find('missing')         # => nil
 Riffer::Agent.all                     # => [SupportAgent, ...]
 ```
 
-Only **named direct subclasses** are found:
+Only **named direct subclasses** are found implicitly:
 
 - Grandchildren are not visible to a grandparent's `find` or `all`. If your app defines an intermediate base class (`class ApplicationAgent < Riffer::Agent`), call `find`/`all` on the intermediate class to look up its subclasses.
-- Anonymous classes (`Class.new(Riffer::Agent)`) are never findable, even when they set an explicit `identifier`.
+- Anonymous classes (`Class.new(Riffer::Agent)`) are never findable implicitly, even when they set an explicit `identifier` — see [Registering an agent explicitly](#registering-an-agent-explicitly).
 - Two subclasses sharing an identifier raise `Riffer::DuplicateIdentifierError` at the first lookup.
+- A subclass whose constant no longer points at it — after a Zeitwerk reload or an RSpec `stub_const` — drops out of `find` and `all`. The check runs when the registry is rebuilt, which defining, registering, or unregistering a subclass triggers; removing or restoring a constant on its own does not, so lookups keep returning the old class until the next rebuild.
+
+### Registering an agent explicitly
+
+**Testing an agent that gets resolved by identifier? Use [`Riffer::Testing`](TESTING.md)** — `stub_agent` builds and registers a throwaway agent and cleans it up for you. The API below is the manual alternative, for production wiring and anything outside the stub lifecycle.
+
+`register` adds an agent to its parent's registry by hand and `unregister` removes it:
+
+```ruby
+Riffer::Agent.register(agent)   # findable until unregistered
+Riffer::Agent.unregister(agent) # no-op if it was never registered
+```
+
+Explicit registration differs from implicit in a few ways:
+
+- Anonymous classes are allowed, as long as they declare an `identifier`. A blank identifier raises `Riffer::ArgumentError`.
+- The class must be a **direct** subclass of the receiver, mirroring implicit registration. `Riffer::Agent.register(SomeAppAgent)` raises `Riffer::ArgumentError` when `SomeAppAgent` descends from an intermediate base — call `register` on that base instead.
+- Taking an identifier already held by another agent, implicit or explicit, raises `Riffer::DuplicateIdentifierError`. Re-registering the same class raises too; there is no idempotent path.
+- The registration survives until you remove it — it is never dropped for a stale constant.
+
+Registration is not synchronized. Register during boot or from a single-threaded test, before concurrent lookups begin.
 
 ## Per-Call Tags
 

data/docs/CONFIGURATION.md

@@ -182,6 +182,38 @@ end
 | `capture_messages` | Opt-in capture of full message content on LLM-call spans (`gen_ai.input.messages`, `gen_ai.output.messages`, `gen_ai.system_instructions`) as GenAI-semconv JSON. Defaults to `false` — message content routinely carries sensitive data. File attachments serialize as metadata-only stubs (media type and name, never bytes), and riffer applies no size limit of its own — cap oversized attributes with the OTEL SDK attribute length limits.                                                                                                               |
 | `backend`          | The backend riffer routes spans through. Assign `Riffer::Tracing::Otel.build` (pass `provider:` to override the global tracer provider — e.g. an in-memory provider in tests), or any object satisfying the duck-typed contract (`in_span` / `current_context` / `with_context`) to route into a non-OTEL system (e.g. Datadog APM). Defaults to `nil` — a no-op. Raises `Riffer::ArgumentError` unless the value is `nil` or responds to `in_span`. See [Tracing → Routing to a non-OpenTelemetry backend](TRACING.md#routing-to-a-non-opentelemetry-backend). |
 
+### File Downloads
+
+File-attachment-download policy lives under `config.files`. Before an LLM call, riffer resolves every `Riffer::Messages::FilePart` attached to a user message against the provider's own capability — some providers accept a URL as-is, some need the bytes inline, and some can't take an attachment at all. See [Messages — File Parts](MESSAGES.md#file-parts) for `FilePart` itself and its `sha256:` field.
+
+```ruby
+Riffer.configure do |config|
+  config.files.allow_downloads = true
+  config.files.max_bytes = 5_000_000
+  config.files.max_per_message = 4
+end
+```
+
+Per file, riffer applies this policy, in order:
+
+1. **Already inline data** — nothing to download. If `sha256:` was given, it's verified against the existing bytes regardless of any other setting below.
+2. **Provider can't accept the file at all** — raises `Riffer::FileUnsupportedError`.
+3. **Provider accepts a URL as-is** — passed straight through, untouched, *unless* `sha256:` was given, in which case riffer downloads and verifies anyway (a caller who set `sha256:` is asking for integrity verification, not a passthrough).
+4. **Provider needs the bytes inline** — riffer downloads the file, verifying `sha256:` if given.
+
+Every download in step 3 or 4 is gated by `allow_downloads`; with it `false` (the default), reaching either of those steps raises `Riffer::FileDownloadsDisabledError` instead of fetching anything. This means upgrading to a riffer version with this feature never starts downloading arbitrary URLs on your behalf — you have to opt in.
+
+| Option            | Description                                                                                                                                                                                                       |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `allow_downloads` | Whether riffer may download a `FilePart`'s URL. Accepts booleans or `'true'`/`'false'`/`'1'`/`'0'`. Defaults to `false`.                                                                                          |
+| `max_bytes`       | Maximum size, in bytes, of a downloaded file; the download is aborted once the streamed body exceeds this, independent of (and regardless of a missing/lying) `content-length` header. Defaults to `3_500_000`. |
+| `timeout`         | Open and read timeout, in seconds, for a single download attempt. Defaults to `60`.                                                                                                                               |
+| `max_per_message` | Maximum number of files allowed on a single user message; checked against each message as originally authored, before consecutive messages are merged. `nil` (default) means uncapped.                          |
+| `runner`          | A `Riffer::Runner` instance that resolves every file across a call's messages. Defaults to `Riffer::Runner::Sequential.new`; assign `Riffer::Runner::Threaded.new` (or `Riffer::Runner::Fibers.new` inside a fiber-based host) to resolve multiple files concurrently. |
+| `downloader`      | The object that fetches a URL's bytes; must respond to `#call(url, max_bytes:, timeout:)` returning the raw (not base64-encoded) file content. Riffer caches it as base64 or raw bytes, whichever the provider actually needs, rather than producing both. Defaults to `Riffer::Files::Downloader.new`, which fetches over HTTPS only, following up to 3 redirects. Assign your own to add logging/metrics, or to fetch from a non-HTTPS store (e.g. `s3://`).                          |
+
+A file that fails resolution raises a `Riffer::FileError` subclass — `Riffer::FileUnsupportedError`, `Riffer::FileDownloadsDisabledError`, `Riffer::TooManyFilesError`, `Riffer::FileChecksumMismatchError`, `Riffer::FileTooLargeError`, `Riffer::FileDownloadError`, or `Riffer::FileEncodingError` — so callers can `rescue Riffer::FileError` for any attachment problem, or a specific subclass to handle one case.
+
 ### Pricing
 
 Configure per-model token prices and riffer computes the cost of each LLM call onto its [`TokenUsage`](MESSAGES.md#token-usage-semantics). Riffer ships **no** price table — so an unconfigured model simply carries no cost (`token_usage.cost` is `nil`).

data/docs/MESSAGES.md

@@ -176,8 +176,17 @@ file.document?   # => true
 
 # From raw base64 data
 file = Riffer::Messages::FilePart.new(media_type: "image/png", data: base64_string, filename: "chart.png")
+
+# With an expected sha256 checksum of the file's contents
+file = Riffer::Messages::FilePart.from_url(
+  "https://example.com/doc.pdf",
+  sha256: "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+)
+file.sha256  # => "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
 ```
 
+`sha256:` accepts a 64-character hex digest (case-insensitive; normalized to lowercase). Raises `Riffer::ArgumentError` on any other format.
+
 ### Hash Shorthand
 
 When passing files to agents or messages, hashes are automatically converted:
@@ -189,6 +198,7 @@ When passing files to agents or messages, hashes are automatically converted:
 # URL shorthand (media_type auto-detected from extension, or provide explicitly)
 {url: "https://example.com/photo.jpg"}
 {url: "https://example.com/file", media_type: "application/pdf"}
+{url: "https://example.com/file", media_type: "application/pdf", sha256: "e3b0c4..."}
 
 # Data shorthand
 {data: base64_string, media_type: "image/png", filename: "chart.png"}

data/docs/OVERVIEW.md

@@ -133,6 +133,7 @@ Response
 - [Configuration](CONFIGURATION.md) - Global configuration
 - [Tracing](TRACING.md) - OpenTelemetry span contract and host wiring
 - [Evals](EVALS.md) - Evaluating agent quality
+- [Testing](TESTING.md) - Stubbing agents and tools in tests
 - [Guardrails](GUARDRAILS.md) - Input/output validation
 - [Skills](SKILLS.md) - Packaged agent capabilities
 - [Serialization](SERIALIZATION.md) - Persisting and transferring agent definitions

data/docs/TESTING.md

@@ -0,0 +1,129 @@
+# Testing
+
+`Riffer::Testing` builds throwaway agents and tools your suite can resolve by identifier or by constant name, and removes them again when the test ends. It exists because agents and tools are looked up by identifier at runtime (see [Looking Up Tools](TOOLS.md#looking-up-tools)) and only **named** classes are found implicitly — an anonymous `Class.new(Riffer::Tool)` never is.
+
+## Setup
+
+Require the adapter for your framework once, in your spec/test helper:
+
+```ruby
+# spec/spec_helper.rb
+require 'riffer/testing/rspec'
+```
+
+```ruby
+# test/test_helper.rb
+require 'riffer/testing/minitest'
+```
+
+Either one adds `stub_agent` and `stub_tool` to every example and cleans up after each one. Neither RSpec nor minitest is a riffer dependency; the adapter files are only loaded when you require them yourself.
+
+## Stubbing a tool
+
+```ruby
+it 'answers from the knowledge base' do
+  stub_tool('KbSearch') do
+    description 'Searches the knowledge base.'
+
+    def call(context:, **)
+      text('We are open 9-5.')
+    end
+  end
+
+  response = SupportAgent.generate('What are your hours?')
+
+  expect(response.content).to include('9-5')
+end
+```
+
+`stub_tool` returns the class, so you can assert against it or pass it to `uses_tools`:
+
+```ruby
+tool = stub_tool('KbSearch') { description 'Searches the knowledge base.' }
+
+stub_agent('FaqAgent') { uses_tools [tool] }
+```
+
+The block is evaluated in the new class, so the whole [tool DSL](TOOLS.md) is available inside it — `description`, `params`, `timeout`, `call`.
+
+## Stubbing an agent
+
+```ruby
+it 'routes to the FAQ agent' do
+  stub_agent('FaqAgent') do # identifier defaults to 'faq_agent', as for a regular agent
+    model 'mock/gpt-5-mini'
+    instructions 'You are a stub.'
+  end
+
+  TriageWorkflow.new.run('What are your hours?')
+end
+```
+
+Pair it with the [Mock provider](providers/MOCK_PROVIDER.md) to queue deterministic responses.
+
+## Naming a stub
+
+The first argument assigns a top-level constant, so the stub resolves the way a production class does — `Object.const_get('FaqAgent')`, a workflow runner that instantiates agents by class name, a class name stored in a row of data:
+
+```ruby
+stub_agent('FaqAgent')
+
+Object.const_get('FaqAgent').identifier # => 'faq_agent'
+```
+
+The identifier is derived from the name exactly as it is for a regular agent or tool, and the block can override it like any other config. Skip the name and set the identifier in the block when nothing under test needs a constant, or when the identifier can't derive from one:
+
+```ruby
+stub_tool { identifier 'kb-search' }
+```
+
+A stub needs a name, an identifier set in its block, or both; `stub_tool` with neither raises `Riffer::ArgumentError`. So does a name that isn't a simple top-level constant name (`'Legacy::Agent'` and `'legacy_agent'` are both rejected — namespaced stubs aren't supported), and so does a name that is **already defined**: riffer adds constants, it never replaces them. Use your framework's `stub_const` when you need a real class swapped out for the duration of a test.
+
+`reset!`, and the adapters that call it, remove the constants the stubs created along with their registrations.
+
+## Stubbing under an intermediate base class
+
+Both helpers take a `base:` — pass your app's intermediate class so the stub lands in the registry the code under test reads:
+
+```ruby
+stub_tool('KbSearch', base: ApplicationTool)
+```
+
+The stub is always a **direct** subclass of `base`, mirroring how implicit registration works.
+
+## Cleanup
+
+`Riffer::Testing.reset!` removes every stub built since the last reset, newest first, and forgets them. The adapters call it after each example; a no-op when nothing was stubbed.
+
+Without an adapter — a framework riffer ships no wiring for, or a suite that configures its own hooks — include the module and call `reset!` from your own teardown:
+
+```ruby
+class MyTestCase < WhateverBase
+  include Riffer::Testing
+
+  def teardown
+    Riffer::Testing.reset!
+    super
+  end
+end
+```
+
+Tracking lives on `Riffer::Testing` itself, so `Riffer::Testing.stub_tool(...)` outside an example and `stub_tool(...)` inside one share one list. Tracking is not synchronized — stub from a single-threaded test, before concurrent lookups begin.
+
+## When a stub leaks
+
+Stubbing an identifier that is already taken raises `Riffer::DuplicateIdentifierError`:
+
+```ruby
+stub_tool { identifier 'kb_search' }
+stub_tool { identifier 'kb_search' }
+# => Riffer::DuplicateIdentifierError: Duplicate identifier "kb_search" for ...
+```
+
+Seeing this on the **first** stub in a test means an earlier stub was never removed — usually a missing adapter require in the helper, or a teardown that skips `Riffer::Testing.reset!`. The same error fires when a stub collides with a real class in your app that already claims the identifier; rename the stub or stub under an intermediate `base:`.
+
+A leaked **named** stub leaves its constant behind on top of its registration, and only `reset!` takes a constant back down — so the second test to name it gets a `Riffer::ArgumentError` about the constant rather than a fresh class.
+
+## Registering without a stub
+
+For production wiring, or a test that needs a class registered outside the stub lifecycle, `Riffer::Tool.register` / `unregister` (and the `Riffer::Agent` equivalents) manage the registry by hand. See [Registering a tool explicitly](TOOLS.md#registering-a-tool-explicitly).

data/docs/TOOLS.md

@@ -154,11 +154,32 @@ Riffer::Tool.find('missing')     # => nil
 Riffer::Tool.all                 # => [SearchTool, ...]
 ```
 
-Only **named direct subclasses** are found:
+Only **named direct subclasses** are found implicitly:
 
 - Grandchildren are not visible to a grandparent's `find` or `all`. If your app defines an intermediate base class (`class ApplicationTool < Riffer::Tool`), call `find`/`all` on the intermediate class to look up its subclasses.
-- Anonymous classes (`Class.new(Riffer::Tool)`) are never findable, even when they set an explicit `identifier`.
+- Anonymous classes (`Class.new(Riffer::Tool)`) are never findable implicitly, even when they set an explicit `identifier` — see [Registering a tool explicitly](#registering-a-tool-explicitly).
 - Two subclasses sharing an identifier raise `Riffer::DuplicateIdentifierError` at the first lookup.
+- A subclass whose constant no longer points at it — after a Zeitwerk reload or an RSpec `stub_const` — drops out of `find` and `all`. The check runs when the registry is rebuilt, which defining, registering, or unregistering a subclass triggers; removing or restoring a constant on its own does not, so lookups keep returning the old class until the next rebuild.
+
+### Registering a tool explicitly
+
+**Testing a tool that gets resolved by identifier? Use [`Riffer::Testing`](TESTING.md)** — `stub_tool` builds and registers a throwaway tool and cleans it up for you. The API below is the manual alternative, for production wiring and anything outside the stub lifecycle.
+
+`register` adds a tool to its parent's registry by hand and `unregister` removes it:
+
+```ruby
+Riffer::Tool.register(tool)   # findable until unregistered
+Riffer::Tool.unregister(tool) # no-op if it was never registered
+```
+
+Explicit registration differs from implicit in a few ways:
+
+- Anonymous classes are allowed, as long as they declare an `identifier`. A blank identifier raises `Riffer::ArgumentError`.
+- The class must be a **direct** subclass of the receiver, mirroring implicit registration. `Riffer::Tool.register(SomeAppTool)` raises `Riffer::ArgumentError` when `SomeAppTool` descends from an intermediate base — call `register` on that base instead.
+- Taking an identifier already held by another tool, implicit or explicit, raises `Riffer::DuplicateIdentifierError`. Re-registering the same class raises too; there is no idempotent path.
+- The registration survives until you remove it — it is never dropped for a stale constant.
+
+Registration is not synchronized. Register during boot or from a single-threaded test, before concurrent lookups begin.
 
 ## The call Method
 

data/docs/providers/AMAZON_BEDROCK.md

@@ -163,6 +163,23 @@ class AWSAgent < Riffer::Agent
 end
 ```
 
+## File Support
+
+Bedrock accepts file attachments either as raw bytes, or as `s3://` URIs passed straight through to Converse — Bedrock fetches the S3 object itself:
+
+```ruby
+file = Riffer::Messages::FilePart.from_url("s3://my-bucket/document.pdf", media_type: "application/pdf")
+response = provider.generate_text(
+  prompt: "Summarize this document",
+  model: "us.anthropic.claude-haiku-4-5-20251001-v1:0",
+  files: [file]
+)
+```
+
+Any other URL scheme (e.g. `https://`) isn't something Bedrock accepts as a reference, so riffer downloads the file itself and sends the raw bytes — see [File Downloads](../CONFIGURATION.md#file-downloads) for the `allow_downloads` policy this requires.
+
+**A `sha256:` on an `s3://` `FilePart` is a combination that always fails with the default setup.** Setting `sha256:` forces riffer to download and verify the file itself before Bedrock ever sees it, regardless of the URL scheme — but riffer's default downloader only fetches `https://` URLs, so an `s3://` source can never be verified out of the box. Either configure a custom `Riffer.config.files.downloader` that can reach S3, or omit `sha256:` and let the `s3://` URI pass straight through to Bedrock unverified.
+
 ## Message Format
 
 The provider converts Riffer messages to Bedrock format:

data/docs/providers/GEMINI.md

@@ -145,7 +145,7 @@ response = provider.generate_text(
 
 ### File Support
 
-Gemini supports inline base64-encoded files (images and documents):
+Gemini's API only accepts inline base64-encoded files (images and documents), never a URL reference:
 
 ```ruby
 file = Riffer::Messages::FilePart.new(data: base64_data, media_type: "image/png")
@@ -156,10 +156,9 @@ response = provider.generate_text(
 )
 ```
 
-**Note:** URL-based file references are not supported. Provide base64-encoded data instead.
+A `FilePart.from_url` source works too — riffer downloads and base64-encodes it before sending, subject to the `allow_downloads` policy in [File Downloads](../CONFIGURATION.md#file-downloads).
 
 ## Limitations
 
 - **No web search** - Gemini's standard API does not include a web search tool
-- **No URL files** - Only base64 inline data is supported for file attachments
 - **Tool call IDs** - Gemini does not return unique call IDs for tool invocations; IDs are generated client-side

data/docs-site/manifest.yml

@@ -48,6 +48,9 @@ groups:
       - source: EVALS.md
         slug: evals
         description: Evaluating agent quality
+      - source: TESTING.md
+        slug: testing
+        description: Stubbing agents and tools in tests
       - source: GUARDRAILS.md
         slug: guardrails
         description: Input/output validation

data/lib/riffer/config.rb

@@ -115,6 +115,97 @@ class Riffer::Config
     end
   end
 
+  # 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
+    # Maximum file size to download before failing.
+    attr_reader :max_bytes #: Integer
+    # Maximum amount of time to spend downloading a file before failing.
+    attr_reader :timeout #: Integer
+    # Maximum number of files to include in an individual message.
+    attr_reader :max_per_message #: Integer?
+    # Execution pattern for downloading files.
+    attr_reader :runner #: Riffer::Runner
+    # The object used to fetch a URL source's bytes
+    attr_reader :downloader #: untyped
+
+    #--
+    #: () -> void
+    def initialize
+      @allow_downloads = false
+      @max_bytes = 3_500_000
+      @timeout = 60
+      @max_per_message = nil
+      @runner = Riffer::Runner::Sequential.new
+      @downloader = Riffer::Files::Downloader.new
+    end
+
+    # Sets the allow_downloads flag, coercing boolean-ish values so an env-var
+    # +"false"+ (truthy in Ruby) doesn't silently enable downloads.  Raises
+    # Riffer::ArgumentError on an unrecognized value.
+    #--
+    #: (untyped) -> void
+    def allow_downloads=(value)
+      @allow_downloads = Riffer::Helpers::Boolean.coerce(value, attribute: "allow_downloads")
+    end
+
+    # Sets max_bytes, provided value is a positive integer.
+    # Raises Riffer::ArgumentError if value is not an Integer or less than or equal to 0.
+    #--
+    #: (untyped) -> void
+    def max_bytes=(value)
+      raise Riffer::ArgumentError, "max_bytes must be a positive integer" unless value.is_a?(Integer) && value.positive?
+
+      @max_bytes = value
+    end
+
+    # Sets timeout, provided value is a positive integer.
+    # Raises Riffer::ArgumentError if value is not an Integer or is less than or equal to 0.
+    #--
+    #: (untyped) -> void
+    def timeout=(value)
+      raise Riffer::ArgumentError, "timeout must be a positive integer" unless value.is_a?(Integer) && value.positive?
+
+      @timeout = value
+    end
+
+    # Sets max_per_message, provided value is either nil or a positive integer.
+    # Raises Riffer::ArgumentError if value is not an Integer or nil, or is less than or equal to 0.
+    #--
+    #: (untyped) -> void
+    def max_per_message=(value)
+      if value.is_a?(Integer) && value.positive?
+        @max_per_message = value
+      elsif value.nil?
+        @max_per_message = nil
+      else
+        raise Riffer::ArgumentError, "max_per_message must be a positive integer or nil"
+      end
+    end
+
+    # Sets the runner used to process file downloads, provided value is a Riffer::Runner.
+    # Raises Riffer::ArgumentError if value is not a Riffer::Runner.
+    #--
+    #: (untyped) -> void
+    def runner=(value)
+      valid = value.is_a?(Riffer::Runner)
+      raise Riffer::ArgumentError, "runner must be a Riffer::Runner instance" unless valid
+
+      @runner = value
+    end
+
+    # Sets the object used to download bytes from a URL.
+    # Raises Riffer::ArgumentError if value does not respond to +#call+.
+    #--
+    #: (untyped) -> void
+    def downloader=(value)
+      raise Riffer::ArgumentError, "downloader must respond to #call" unless value.respond_to?(:call)
+
+      @downloader = value
+    end
+  end
+
   # Consumer-configured token pricing, keyed by +provider/model+ id. Riffer
   # ships no price table, so an unconfigured model carries no cost.
   class Pricing
@@ -288,6 +379,8 @@ class Riffer::Config
   # Tracing-related global configuration.
   attr_reader :tracing #: Riffer::Config::Tracing
 
+  attr_reader :files #: Riffer::Config::Files
+
   # Consumer-configured per-model token pricing.
   attr_reader :pricing #: Riffer::Config::Pricing
 
@@ -336,6 +429,7 @@ class Riffer::Config
     @tool_runtime = Riffer::Tools::Runtime::Inline.new
     @skills = Skills.new
     @tracing = Tracing.new
+    @files = Files.new
     @pricing = Pricing.new
     @message_id_strategy = :none
     @experimental_history_healing = false

data/lib/riffer/files/downloader.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require "net/http"
+require "uri"
+
+class Riffer::Files::Downloader
+  MAX_REDIRECTS = 3 #: Integer
+
+  #: (String, max_bytes: Integer, timeout: Integer) -> String
+  def call(url, max_bytes:, timeout:)
+    fetch(url, max_bytes: max_bytes, timeout: timeout, redirects_remaining: MAX_REDIRECTS)
+  rescue Riffer::Error
+    raise
+  rescue StandardError => e
+    raise Riffer::FileDownloadError, "Error downloading file: #{e.message}"
+  end
+
+  private
+
+  #: (String, max_bytes: Integer, timeout: Integer, redirects_remaining: Integer) -> String
+  def fetch(url, max_bytes:, timeout:, redirects_remaining:)
+    uri = begin
+      URI.parse(url) #: URI::HTTPS
+    rescue URI::InvalidURIError => e
+      raise Riffer::FileDownloadError, "Invalid file URL: #{e.message}"
+    end
+    raise Riffer::FileDownloadError, "Invalid file URL: missing host" if uri.host.nil?
+    raise Riffer::FileDownloadError, "Unsupported URL scheme: #{uri.scheme}" unless uri.scheme == "https"
+
+    http = Net::HTTP.new(uri.host, uri.port)
+    http.use_ssl = true
+    http.open_timeout = timeout
+    http.read_timeout = timeout
+
+    # request_get without a block reads (and discards our chance to cap) the
+    # whole body before returning; the cap/read has to happen inside the
+    # block it yields to, where the body hasn't been consumed yet.
+    redirect_location = nil #: String?
+    content = nil #: String?
+
+    http.start do
+      http.request_get(uri.request_uri) do |response|
+        case response
+        when Net::HTTPRedirection
+          raise Riffer::FileDownloadError, "Too many redirects" if redirects_remaining.zero?
+
+          redirect_location = response["location"]
+          raise Riffer::FileDownloadError, "Redirect missing Location header" if redirect_location.nil?
+        when Net::HTTPSuccess
+          content = read_capped(response, max_bytes: max_bytes)
+        else
+          raise Riffer::FileDownloadError, "File download failed, status: #{response.code}"
+        end
+      end
+    end
+
+    if redirect_location
+      return fetch(redirect_location, max_bytes: max_bytes, timeout: timeout,
+                                      redirects_remaining: redirects_remaining - 1,)
+    end
+
+    content #: String
+  end
+
+  #: (Net::HTTPResponse, max_bytes: Integer) -> String
+  def read_capped(response, max_bytes:)
+    content_length = response["content-length"]&.to_i
+    raise Riffer::FileTooLargeError, "File too large" if content_length && content_length > max_bytes
+
+    buffer = +""
+    response.read_body do |chunk|
+      buffer << chunk
+      raise Riffer::FileTooLargeError, "File too large" if buffer.bytesize > max_bytes
+    end
+    buffer
+  end
+end