riffer 0.28.0 → 0.29.0

data/docs/08_MESSAGES.md

@@ -32,9 +32,9 @@ msg.to_h     # => {role: :user, content: "Hello, how are you?"}
 User messages can include file attachments:
 
 ```ruby
-file = Riffer::FilePart.from_path("photo.jpg")
+file = Riffer::Messages::FilePart.from_path("photo.jpg")
 msg = Riffer::Messages::User.new("Describe this image", files: [file])
-msg.files    # => [#<Riffer::FilePart ...>]
+msg.files    # => [#<Riffer::Messages::FilePart ...>]
 msg.to_h     # => {role: :user, content: "Describe this image", files: [{...}]}
 ```
 
@@ -48,7 +48,7 @@ msg = Riffer::Messages::Assistant.new("I'm doing well, thank you!")
 msg.role         # => :assistant
 msg.content      # => "I'm doing well, thank you!"
 msg.tool_calls   # => []
-msg.token_usage  # => nil or Riffer::TokenUsage
+msg.token_usage  # => nil or Riffer::Providers::TokenUsage
 
 # Response with tool calls
 msg = Riffer::Messages::Assistant.new("", tool_calls: [
@@ -118,7 +118,7 @@ msg.error_type  # => :execution_error
 
 ## File Parts
 
-`Riffer::FilePart` represents a file attachment (image or document) that can be included with user messages.
+`Riffer::Messages::FilePart` represents a file attachment (image or document) that can be included with user messages.
 
 ### Supported Media Types
 
@@ -130,18 +130,18 @@ msg.error_type  # => :execution_error
 
 ```ruby
 # From a file path (reads eagerly, detects media type from extension)
-file = Riffer::FilePart.from_path("photo.jpg")
+file = Riffer::Messages::FilePart.from_path("photo.jpg")
 file.media_type  # => "image/jpeg"
 file.filename    # => "photo.jpg"
 file.image?      # => true
 
 # From a URL (stored directly, resolved lazily if provider needs bytes)
-file = Riffer::FilePart.from_url("https://example.com/doc.pdf")
+file = Riffer::Messages::FilePart.from_url("https://example.com/doc.pdf")
 file.url?        # => true
 file.document?   # => true
 
 # From raw base64 data
-file = Riffer::FilePart.new(media_type: "image/png", data: base64_string, filename: "chart.png")
+file = Riffer::Messages::FilePart.new(media_type: "image/png", data: base64_string, filename: "chart.png")
 ```
 
 ### Hash Shorthand
@@ -183,39 +183,30 @@ This creates a `User` message internally.
 
 ### Message Arrays
 
-For multi-turn conversations, pass an array of messages:
+For multi-turn conversations restored from persisted state, construct a `Riffer::Agent::Session` with the message history and hand it to a new agent:
 
 ```ruby
-messages = [
-  {role: :user, content: "What's the weather?"},
-  {role: :assistant, content: "I'll check that for you."},
-  {role: :user, content: "Thanks, I meant in Tokyo specifically."}
-]
+session = Riffer::Agent::Session.new(messages: [
+  Riffer::Messages::User.new("What's the weather?"),
+  Riffer::Messages::Assistant.new("I'll check that for you."),
+  Riffer::Messages::User.new("Thanks, I meant in Tokyo specifically.")
+])
 
-response = agent.generate(messages)
+agent = MyAgent.new(session: session)
+response = agent.generate   # session already carries the last user turn
 ```
 
-Messages can be hashes or `Riffer::Messages::Base` objects:
-
-```ruby
-messages = [
-  Riffer::Messages::User.new("Hello"),
-  Riffer::Messages::Assistant.new("Hi there!"),
-  Riffer::Messages::User.new("How are you?")
-]
-
-response = agent.generate(messages)
-```
+`Riffer::Agent::Session.new(messages:)` accepts `Riffer::Messages::Base` objects. If your persistence layer hands back hashes, normalize them first via `Riffer::Messages::Converter#convert_to_message_object` or your own adapter (e.g. jane's `to_riffer`).
 
 ### Accessing Message History
 
-After calling `generate` or `stream`, access the full conversation:
+Conversation state lives on `agent.session` — a `Riffer::Agent::Session` instance. After calling `generate` or `stream`, access the full conversation:
 
 ```ruby
 agent = MyAgent.new
 agent.generate("Hello!")
 
-agent.messages.each do |msg|
+agent.session.messages.each do |msg|
   puts "[#{msg.role}] #{msg.content}"
 end
 # [system] You are a helpful assistant.
@@ -223,6 +214,8 @@ end
 # [assistant] Hi there! How can I help you today?
 ```
 
+`Riffer::Agent::Session` includes `Enumerable`, so `find`, `select`, `count`, `reverse_each` etc. work directly on the session without going through `.messages`.
+
 ## Tool Call Structure
 
 Tool calls in assistant messages have this structure:
@@ -264,19 +257,19 @@ Without this step, the same model can receive different input depending on the p
 When a context message is injected before the user's turn, two consecutive user messages are merged into one:
 
 ```ruby
-messages = [
+session = Riffer::Agent::Session.new(messages: [
   Riffer::Messages::System.new("You are a code reviewer."),
   Riffer::Messages::User.new("The repository uses RSpec for testing."),
   Riffer::Messages::User.new("Review this pull request.")
-]
+])
 
-agent.generate(messages)
+MyAgent.new(session: session).generate
 # The provider receives two messages:
 #   1. System  — "You are a code reviewer."
 #   2. User    — "The repository uses RSpec for testing.\n\nReview this pull request."
 ```
 
-Merging happens at serialization time only. The agent's `messages` array still contains the original separate messages for logging, evals, and debugging.
+Merging happens at serialization time only. The session's `messages` array still contains the original separate messages for logging, evals, and debugging.
 
 ## IDs
 
@@ -330,4 +323,4 @@ Subclasses implement `role` and optionally extend `to_h` with additional fields.
 
 ## Editing history after the fact
 
-The agent's `messages` array is mutable, but the message value objects themselves are immutable. To edit recorded history — truncate an assistant message, replace a tool result, fill an orphan `tool_use` — use the mutators on `Riffer::Agent`. Each mutator enforces the `tool_use` ↔ `tool_result` invariant. See [Mutating history](04_AGENT_LIFECYCLE.md#mutating-history) for the full list.
+The session's `messages` array is mutable, but the message value objects themselves are immutable. To edit recorded history — truncate an assistant message, rewrite a tool result, fill an orphan `tool_use` — use the mutators on `agent.session` (`update`, `remove`). Each one enforces the `tool_use` ↔ `tool_result` invariant. See [Mutating history](04_AGENT_LIFECYCLE.md#mutating-history) for the full list.

data/docs/09_STREAM_EVENTS.md

@@ -249,7 +249,7 @@ Emitted when token usage data is available at the end of a response:
 ```ruby
 event = Riffer::StreamEvents::TokenUsageDone.new(token_usage: token_usage)
 event.role                          # => :assistant
-event.token_usage                   # => Riffer::TokenUsage
+event.token_usage                   # => Riffer::Providers::TokenUsage
 event.token_usage.input_tokens      # => 100
 event.token_usage.output_tokens     # => 50
 event.token_usage.total_tokens      # => 150

data/docs/10_CONFIGURATION.md

@@ -61,14 +61,14 @@ Configure the default tool runtime for all agents:
 
 ```ruby
 Riffer.configure do |config|
-  config.tool_runtime = Riffer::ToolRuntime::Threaded
+  config.tool_runtime = Riffer::Tools::Runtime::Threaded
 end
 ```
 
 | Value                          | Description                                                                                       |
 | ------------------------------ | ------------------------------------------------------------------------------------------------- |
-| `Riffer::ToolRuntime` subclass | Instantiated automatically (e.g., `Riffer::ToolRuntime::Inline`, `Riffer::ToolRuntime::Threaded`) |
-| `Riffer::ToolRuntime` instance | Custom runtime with specific options                                                              |
+| `Riffer::Tools::Runtime` subclass | Instantiated automatically (e.g., `Riffer::Tools::Runtime::Inline`, `Riffer::Tools::Runtime::Threaded`) |
+| `Riffer::Tools::Runtime` instance | Custom runtime with specific options                                                              |
 | `Proc`                         | Dynamic resolution                                                                                |
 
 Per-agent configuration overrides this global default. See [Advanced Tool Configuration — Tool Runtime](07_TOOL_ADVANCED.md#tool-runtime-experimental) for details.
@@ -119,18 +119,7 @@ end
 
 When the strategy is not `:none`, every `Riffer::Messages::Base` instance — user prompts, system instructions, assistant responses, and tool results — gets an auto-generated `id` at construction time. IDs are included in `message.to_h` when present and omitted when `nil`. Provider API payloads are unaffected; the `id` stays on the Ruby side.
 
-Seeded messages passed to `agent.generate([...])` must carry their own `:id` when the strategy is enabled — Riffer never fabricates identifiers for pre-existing history:
-
-```ruby
-Riffer.configure { |c| c.message_id_strategy = :uuidv7 }
-
-agent.generate([
-  {role: :user, content: "Hi", id: "msg-001"},
-  {role: :assistant, content: "Hello!", id: "msg-002"}
-])
-```
-
-Missing ids raise `Riffer::ArgumentError` with the offending index.
+When constructing a `Riffer::Agent::Session` from persisted history with the strategy enabled, supply ids on every seeded message yourself — Riffer never fabricates identifiers for pre-existing history. Messages built via the `Riffer::Messages::*` constructors auto-generate ids per the strategy, so as long as those constructors are used at message-creation time, ids flow through.
 
 See [Messages — IDs](08_MESSAGES.md#ids) for more details.
 
@@ -148,12 +137,12 @@ end
 
 When enabled, two repairs run automatically:
 
-1. **Seeded history.** `agent.generate(messages_array)` silently drops orphaned `tool_use` exchanges (assistant `tool_call` with no matching `Tool` result) and parentless `Tool` messages from the seed before the run begins. Pending tool calls on the **resume boundary** — the last assistant whose tail is purely `Tool` results (or none) — are preserved; `execute_pending_tool_calls` runs them on the next LLM call.
+1. **Seeded session.** Passing a pre-populated `Riffer::Agent::Session` to `Agent.new(session: ...)` silently drops orphaned `tool_use` exchanges (assistant `tool_call` with no matching `Tool` result) and parentless `Tool` messages before the next inference call. Pending tool calls on the **resume boundary** — the last assistant whose tail is purely `Tool` results (or none) — are preserved; `execute_pending_tool_calls` runs them on the next LLM call.
 2. **Interrupts.** Any orphan `tool_use` left when the loop is interrupted (caller-issued `interrupt!` or the built-in `INTERRUPT_MAX_STEPS` ceiling) is filled with a placeholder `Riffer::Messages::Tool` carrying `error_type: :interrupted` and the content `"Tool call interrupted before completion."`. Filled `call_id`s are exposed on `Riffer::Agent::Response#healed_tool_call_ids` (and `Riffer::StreamEvents::Interrupt#healed_tool_call_ids` when streaming).
 
-Defaults to `false` — pre-healing behavior. Seeded arrays pass through untouched, and orphan `tool_use` left by an interrupt remain in history for `execute_pending_tool_calls` to re-run on the next call.
+Defaults to `false` — pre-healing behavior. Seeded sessions pass through untouched, and orphan `tool_use` left by an interrupt remain in history for `execute_pending_tool_calls` to re-run on the next call.
 
-There is no per-call override and no customizable placeholder. Callers needing finer control can call the `replace_tool_result` mutator after the interrupt returns to upgrade a placeholder in place. See [Agent Lifecycle — Healing pending tool results on interrupt](04_AGENT_LIFECYCLE.md#healing-pending-tool-results-on-interrupt-experimental).
+There is no per-call override and no customizable placeholder. Callers needing finer control can call `agent.session.update(tool_call_id:, ...)` after the interrupt returns to upgrade a placeholder in place. See [Agent Lifecycle — Healing pending tool results on interrupt](04_AGENT_LIFECYCLE.md#healing-pending-tool-results-on-interrupt-experimental).
 
 ## Agent-Level Configuration
 

data/docs/providers/01_PROVIDERS.md

@@ -11,6 +11,7 @@ Providers are adapters that connect Riffer to LLM services. They implement a com
 | Amazon Bedrock | `amazon_bedrock` | `aws-sdk-bedrockruntime` |
 | Anthropic      | `anthropic`      | `anthropic`              |
 | Gemini         | `gemini`         | None                     |
+| OpenRouter     | `openrouter`     | `openai`                 |
 | Mock           | `mock`           | None                     |
 
 ## Model String Format
@@ -24,6 +25,7 @@ class MyAgent < Riffer::Agent
   model 'amazon_bedrock/us.anthropic.claude-haiku-4-5-20251001-v1:0'  # Bedrock
   model 'anthropic/claude-haiku-4-5-20251001'                         # Anthropic
   model 'gemini/gemini-2.5-flash-lite'                                # Gemini
+  model 'openrouter/anthropic/claude-sonnet-4.6'                      # OpenRouter
   model 'mock/any'                                                    # Mock provider
 end
 ```
@@ -165,6 +167,9 @@ Riffer::Providers::Repository.find(:anthropic)
 Riffer::Providers::Repository.find(:gemini)
 # => Riffer::Providers::Gemini
 
+Riffer::Providers::Repository.find(:openrouter)
+# => Riffer::Providers::OpenRouter
+
 Riffer::Providers::Repository.find(:mock)
 # => Riffer::Providers::Mock
 ```
@@ -178,3 +183,4 @@ Riffer::Providers::Repository.find(:mock)
 - [Mock](06_MOCK_PROVIDER.md) - Mock provider for testing
 - [Custom Providers](07_CUSTOM_PROVIDERS.md) - Creating your own provider
 - [Gemini](08_GEMINI.md) - Gemini models via Google GenAI API
+- [OpenRouter](09_OPENROUTER.md) - Unified gateway across many vendors

data/docs/providers/06_MOCK_PROVIDER.md

@@ -121,7 +121,8 @@ class MyAgentTest < Minitest::Test
     ])
     @provider.stub_response("Done.")
 
-    @agent.generate("Do something", context: {user_id: 123})
+    agent = TestableAgent.new(context: {user_id: 123})
+    agent.generate("Do something")
 
     # Tool receives the context
   end

data/docs/providers/07_CUSTOM_PROVIDERS.md

@@ -60,7 +60,7 @@ class Riffer::Providers::MyProvider < Riffer::Providers::Base
     usage = response.usage
     return nil unless usage
 
-    Riffer::TokenUsage.new(
+    Riffer::Providers::TokenUsage.new(
       input_tokens: usage.input_tokens,
       output_tokens: usage.output_tokens
     )
@@ -234,7 +234,7 @@ Riffer::StreamEvents::WebSearchDone.new(
 
 # Token usage (emit at end of stream)
 Riffer::StreamEvents::TokenUsageDone.new(
-  token_usage: Riffer::TokenUsage.new(
+  token_usage: Riffer::Providers::TokenUsage.new(
     input_tokens: 100,
     output_tokens: 50
   )
@@ -309,7 +309,7 @@ class Riffer::Providers::MyProvider < Riffer::Providers::Base
         yielder << Riffer::StreamEvents::TextDone.new(accumulated_text)
       when :usage
         yielder << Riffer::StreamEvents::TokenUsageDone.new(
-          token_usage: Riffer::TokenUsage.new(
+          token_usage: Riffer::Providers::TokenUsage.new(
             input_tokens: event.usage.input_tokens,
             output_tokens: event.usage.output_tokens
           )
@@ -322,7 +322,7 @@ class Riffer::Providers::MyProvider < Riffer::Providers::Base
     usage = response.usage
     return nil unless usage
 
-    Riffer::TokenUsage.new(
+    Riffer::Providers::TokenUsage.new(
       input_tokens: usage.input_tokens,
       output_tokens: usage.output_tokens
     )

data/docs/providers/08_GEMINI.md

@@ -90,7 +90,7 @@ end
 params = Riffer::Params.new
 params.required(:sentiment, String)
 params.required(:score, Float)
-structured_output = Riffer::StructuredOutput.new(params)
+structured_output = Riffer::Agent::StructuredOutput.new(params)
 
 response = provider.generate_text(
   prompt: "Analyze: 'This is great!'",
@@ -125,7 +125,7 @@ response = provider.generate_text(
 Gemini supports inline base64-encoded files (images and documents):
 
 ```ruby
-file = Riffer::FilePart.new(data: base64_data, media_type: "image/png")
+file = Riffer::Messages::FilePart.new(data: base64_data, media_type: "image/png")
 response = provider.generate_text(
   prompt: "Describe this image",
   model: "gemini-2.5-flash-lite",

data/docs/providers/09_OPENROUTER.md

@@ -0,0 +1,242 @@
+# OpenRouter Provider
+
+The OpenRouter provider connects Riffer to [OpenRouter](https://openrouter.ai) — a unified gateway that exposes hundreds of LLMs from many vendors (Anthropic, OpenAI, Meta, Mistral, DeepSeek, Google, Grok, Qwen, and more) behind a single OpenAI-compatible Chat Completions endpoint.
+
+OpenRouter is useful when you want one credential, one model-string format, and access to models Riffer doesn't have a direct provider for. It also offers built-in routing, fallback, and prompt transforms.
+
+> **Note:** OpenRouter exposes only the OpenAI **Chat Completions** API, not the Responses API. That's why this provider does not subclass `Riffer::Providers::OpenAI` (which uses Responses). It implements the five hook methods independently against Chat Completions while still sharing the `openai` Ruby gem.
+
+## Installation
+
+Add the OpenAI gem to your Gemfile — OpenRouter reuses it:
+
+```ruby
+gem 'openai'
+```
+
+## Configuration
+
+Set your API key globally:
+
+```ruby
+Riffer.configure do |config|
+  config.openrouter.api_key = ENV['OPENROUTER_API_KEY']
+end
+```
+
+Or per-agent:
+
+```ruby
+class MyAgent < Riffer::Agent
+  model 'openrouter/anthropic/claude-sonnet-4.6'
+  provider_options api_key: ENV['MY_OR_KEY']
+end
+```
+
+The `api_key` resolves in order: keyword arg → `Riffer.config.openrouter.api_key` → `ENV['OPENROUTER_API_KEY']`.
+
+## Supported Models
+
+Use any OpenRouter model in the `openrouter/<openrouter-model-id>` format. The OpenRouter model ID is everything after the first slash:
+
+```ruby
+model 'openrouter/anthropic/claude-sonnet-4.6'
+model 'openrouter/openai/gpt-4o-mini'
+model 'openrouter/meta-llama/llama-3.1-70b-instruct'
+model 'openrouter/deepseek/deepseek-r1'
+model 'openrouter/mistralai/mixtral-8x22b-instruct'
+```
+
+See OpenRouter's [model catalog](https://openrouter.ai/models) for the full list.
+
+## Model Options
+
+### temperature, max_tokens, top_p, etc.
+
+Standard sampling options pass through to the underlying model:
+
+```ruby
+model_options temperature: 0.5, max_tokens: 2048
+```
+
+### reasoning
+
+For reasoning models (DeepSeek R1, OpenAI o-series via OpenRouter, etc.):
+
+```ruby
+model_options reasoning: 'high'  # 'low' | 'medium' | 'high'
+```
+
+Pass a hash for finer control:
+
+```ruby
+model_options reasoning: {effort: 'medium', max_tokens: 5000}
+```
+
+Streaming yields `Riffer::StreamEvents::ReasoningDelta` and `ReasoningDone` events when the model returns reasoning content.
+
+### provider (routing preferences)
+
+Pin which upstream provider OpenRouter should use, set allow/deny lists, or prefer a sort order:
+
+```ruby
+model_options provider: {
+  order: ['anthropic', 'openai'],
+  allow_fallbacks: false
+}
+```
+
+See OpenRouter's [provider routing docs](https://openrouter.ai/docs/provider-routing) for the full schema.
+
+### models (fallback chain)
+
+If the primary model is unavailable, OpenRouter will try the next one in the list:
+
+```ruby
+model_options models: ['openai/gpt-4o', 'anthropic/claude-sonnet-4.6']
+```
+
+### transforms
+
+Prompt transforms applied by OpenRouter (e.g. middle-out auto-truncation):
+
+```ruby
+model_options transforms: ['middle-out']
+```
+
+## Example
+
+```ruby
+Riffer.configure do |config|
+  config.openrouter.api_key = ENV['OPENROUTER_API_KEY']
+end
+
+class TranslateAgent < Riffer::Agent
+  model 'openrouter/anthropic/claude-sonnet-4.6'
+  instructions 'You translate English to French.'
+end
+
+puts TranslateAgent.new.generate('Hello, world!')
+```
+
+## Streaming
+
+```ruby
+agent.stream('Explain Ruby blocks').each do |event|
+  case event
+  when Riffer::StreamEvents::TextDelta
+    print event.content
+  when Riffer::StreamEvents::ReasoningDelta
+    print "[thinking] #{event.content}"
+  when Riffer::StreamEvents::TokenUsageDone
+    puts "\n[tokens: #{event.token_usage.total_tokens}]"
+  end
+end
+```
+
+The provider opts into `stream_options: {include_usage: true}` automatically so `TokenUsageDone` fires reliably.
+
+## Tool Calling
+
+Tools are converted to OpenAI Chat Completions function format. The provider handles tool name encoding/decoding (slashes in tool names are wire-encoded with `__`) just like the OpenAI and Anthropic providers.
+
+```ruby
+class CalculatorTool < Riffer::Tool
+  description 'Performs basic math'
+  params do
+    required :operation, String, enum: ['add', 'subtract', 'multiply', 'divide']
+    required :a, Float
+    required :b, Float
+  end
+
+  def call(context:, operation:, a:, b:)
+    result = case operation
+    when 'add' then a + b
+    when 'subtract' then a - b
+    when 'multiply' then a * b
+    when 'divide' then a / b
+    end
+    text(result.to_s)
+  end
+end
+
+class MathAgent < Riffer::Agent
+  model 'openrouter/openai/gpt-4o-mini'
+  uses_tools [CalculatorTool]
+end
+```
+
+## Reasoning Models
+
+Reasoning models surface their thought process via OpenRouter's normalised `reasoning` field. Enable it with the `reasoning` option:
+
+```ruby
+class ThinkAgent < Riffer::Agent
+  model 'openrouter/deepseek/deepseek-r1'
+  model_options reasoning: 'medium'
+end
+
+ThinkAgent.new.stream('What is 2+2? Think step by step.').each do |event|
+  case event
+  when Riffer::StreamEvents::ReasoningDelta
+    print "[reasoning] #{event.content}"
+  when Riffer::StreamEvents::TextDelta
+    print event.content
+  end
+end
+```
+
+## Routing & Fallbacks
+
+Survive an upstream outage by chaining models:
+
+```ruby
+class ResilientAgent < Riffer::Agent
+  model 'openrouter/openai/gpt-4o-mini'
+  model_options models: [
+    'openai/gpt-4o-mini',
+    'anthropic/claude-haiku-4.5',
+    'google/gemini-flash-1.5'
+  ]
+end
+```
+
+Pin to a specific upstream when consistency matters:
+
+```ruby
+model_options provider: {order: ['anthropic'], allow_fallbacks: false}
+```
+
+## Message Format
+
+Riffer messages convert to Chat Completions roles:
+
+| Riffer Message | Chat Completions Role |
+| -------------- | --------------------- |
+| `System`       | `system`              |
+| `User`         | `user`                |
+| `Assistant`    | `assistant`           |
+| `Tool`         | `tool`                |
+
+User messages with files become multi-part content (`image_url` for images, `file` for documents). Assistant tool calls go into a nested `tool_calls` array on the assistant message.
+
+## Limitations (v1)
+
+- **No unified web search.** OpenRouter doesn't expose a cross-vendor web-search tool — capability varies per upstream model.
+- **Audio and image generation models** are not supported.
+- **Responses API features** (e.g. OpenAI's `response.id` for continuation) are unavailable — OpenRouter implements only Chat Completions.
+
+## Direct Provider Usage
+
+```ruby
+provider = Riffer::Providers::OpenRouter.new(api_key: ENV['OPENROUTER_API_KEY'])
+
+response = provider.generate_text(
+  prompt: 'Hello!',
+  model: 'anthropic/claude-sonnet-4.6',
+  temperature: 0.7
+)
+
+puts response.content
+puts response.token_usage.total_tokens
+```