riffer 0.28.0 → 0.29.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 65b1a78bcc2e6e26690176a167d4b8f5a28fdc83c95ac582fb980e1d52d0d89f
-  data.tar.gz: fa3f0633c56ca64a25f4026d48f7c8366344cacb76b2bdd7f4e9ce8642045b6c
+  metadata.gz: be73ae37c66f2f6ad16acdd7b52c271a782172878086821a9c95dbbe238541d3
+  data.tar.gz: 29ea65859395f2e6daaa993d9e8c60cf1908781f1acf79b642588439f4e41781
 SHA512:
-  metadata.gz: e643b5a130b85f63bb37f51adf0fb43ea94f242af66ba379b98da8fbaf9e7389f17d9793cd2b1ff9a1b889ccce711632b02dfcd976cf323bf3c3b1300695635d
-  data.tar.gz: b01a4a3d4db8ca8ef72acf1e8c3e5b1ab01e5d47fdeca1a046c65daf8bde4e0160be8f10b2d94dc56c1dcd28e491cf6be44cf44fa12216fabe56956c327e9959
+  metadata.gz: cce21dcb1840e39b96032cf6061dcce6030e35c21c1ce8f3937138405067cd39644f4a55fd4fddfcc9623549441dccb0d76b5443e7fa890ab84ce73f6af2736d
+  data.tar.gz: 3c0e8a0fbcd42c3aceee9b4d8837188e260d444c2e22df72f1976bdfc7b05bf2669f2494d3121ca066d142baa8629bdd01c51acd294869702b5357d83943a4a6

data/.agents/architecture.md

@@ -6,6 +6,8 @@
 
 Base class for AI agents. Subclass and use DSL methods `model`, `instructions`, `structured_output`, and `skills` to configure. Orchestrates message flow, LLM calls, tool execution, structured output parsing, and skill activation via a generate/stream loop.
 
+Class-level DSL settings live on a per-class `Riffer::Agent::Config` object accessible via `MyAgent.config`. DSL methods read and mutate this Config in place. Instances read from `@config`, which defaults to `self.class.config` but can be replaced via `Agent.new(config: ...)`.
+
 ```ruby
 class EchoAgent < Riffer::Agent
   model 'openai/gpt-5-mini' # provider/model
@@ -61,11 +63,11 @@ Support for the [Agent Skills spec](https://agentskills.io/). Skills are package
 Typed message objects that extend `Riffer::Messages::Base`:
 
 - `System` - system instructions
-- `User` - user input (supports file attachments via `Riffer::FilePart`)
+- `User` - user input (supports file attachments via `Riffer::Messages::FilePart`)
 - `Assistant` - AI responses
 - `Tool` - tool execution results
 
-`Riffer::FilePart` represents file attachments (images and documents) that can be included with User messages. Supports file paths, URLs, and raw base64 data.
+`Riffer::Messages::FilePart` represents file attachments (images and documents) that can be included with User messages. Supports file paths, URLs, and raw base64 data.
 
 The `Converter` module handles hash-to-object conversion, including file hash-to-`FilePart` conversion.
 
@@ -121,7 +123,7 @@ runner = Riffer::Runner::Threaded.new(max_concurrency: 3)
 runner.map(items, context: ctx) { |item| process(item) }
 ```
 
-### ToolRuntime (`lib/riffer/tool_runtime.rb`)
+### Tools::Runtime (`lib/riffer/tools/runtime.rb`)
 
 Composes with a Runner to execute tool calls. Provides `#execute` as the public entry point and `#around_tool_call` as a hook for instrumentation. Passes the agent context through to the runner.
 
@@ -130,7 +132,7 @@ Built-in runtimes:
 - `Inline` — uses `Runner::Sequential` (default)
 - `Threaded` — uses `Runner::Threaded`
 
-Context flow: `Agent#execute_tool_calls` → `ToolRuntime#execute(tool_calls, tools:, context:)` → `Runner#map(tool_calls, context:) { dispatch }` → `Tool#call(context:, **args)`
+Context flow: `Agent#execute_tool_calls` → `Tools::Runtime#execute(tool_calls, tools:, context:)` → `Runner#map(tool_calls, context:) { dispatch }` → `Tool#call(context:, **args)`
 
 ### MCP Integration (`lib/riffer/mcp/`)
 
@@ -176,13 +178,21 @@ lib/
   riffer/
     version.rb           # VERSION constant
     config.rb            # Configuration class
-    core.rb              # Core functionality
     agent.rb             # Agent class
+    agent/
+      config.rb          # Per-class DSL configuration value object
+      session.rb         # Conversation handle (message array + invariants)
+      session/
+        repair.rb        # tool_use ↔ tool_result invariant repair
+      structured_output.rb # Structured output schema wrapper
+      structured_output/
+        result.rb        # Parse/validation result object
     messages.rb          # Messages namespace/module
     providers.rb         # Providers namespace/module
-    param.rb             # Single parameter definition (shared by tools and structured output)
     params.rb            # Parameter collection with DSL and validation
-    structured_output.rb # Structured output schema wrapper
+    params/
+      param.rb           # Single parameter definition (shared by tools and structured output)
+      boolean.rb         # Boolean sentinel type
     stream_events.rb     # Stream events namespace/module
     skills.rb            # Skills namespace/module
     skills/
@@ -195,13 +205,9 @@ lib/
       frontmatter.rb     # Parsed YAML frontmatter value object with .parse
       context.rb         # Skills context for a generation cycle
       activate_tool.rb   # Default skill_activate tool
-    structured_output/
-      result.rb          # Parse/validation result object
     helpers/
       class_name_converter.rb  # Class name conversion utilities
       dependencies.rb          # Dependency management
-      validations.rb           # Validation helpers
-    file_part.rb         # File attachment (images and documents)
     messages/
       base.rb            # Base message class
       assistant.rb       # Assistant message
@@ -209,6 +215,7 @@ lib/
       system.rb          # System message
       user.rb            # User message
       tool.rb            # Tool message
+      file_part.rb       # File attachment (images and documents)
     providers/
       base.rb            # Base provider class
       open_ai.rb         # OpenAI provider

data/.agents/code-style.md

@@ -4,7 +4,7 @@
 
 - Use StandardRB for linting and formatting
 - Custom rules are defined in `.standard.yml`
-- Run `bundle exec rake standard` to check, `bundle exec rake standard:fix` to auto-fix
+- Run `bin/lint` to check, `bin/lint --fix` to auto-fix
 
 ## Required Header
 

data/.agents/rbs-inline.md

@@ -116,8 +116,8 @@ DEFAULTS = {}.freeze #: Hash[Symbol, untyped]
 
 After changing type annotations:
 
-1. Run `bundle exec rake rbs:generate` to regenerate `sig/generated/` files
+1. Run `bin/rbs` to regenerate `sig/generated/` files
 2. Commit both the source changes and the generated `.rbs` files
 3. CI checks for drift between source annotations and committed `.rbs` files
 
-Use `bundle exec rake rbs:watch` during development to auto-regenerate on file changes.
+Use `bin/rbs-watch` during development to auto-regenerate on file changes.

data/.agents/testing.md

@@ -46,11 +46,15 @@ Record external API interactions in `test/fixtures/vcr_cassettes/`.
 
 ```bash
 # Run all tests
-bundle exec rake test
+bin/test
 
-# Run a single test file
-bundle exec ruby -Ilib:test test/riffer/agent_test.rb
+# Run a single test file (or multiple files)
+bin/test test/riffer/agent_test.rb
+bin/test test/riffer/agent_test.rb test/riffer/config_test.rb
 
-# Run a specific test by name
-bundle exec ruby -Ilib:test test/riffer/agent_test.rb --name "test_something"
+# Filter by test name (regex or substring)
+bin/test test/riffer/agent_test.rb --name /generates/
+
+# Filter across the whole suite
+bin/test --name /generates/
 ```

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.28.0"
+  ".": "0.29.0"
 }

data/AGENTS.md

@@ -5,7 +5,7 @@ Ruby gem framework for building AI-powered agents with LLM provider adapters.
 ## Quick Reference
 
 - **Ruby**: 3.3.0+ (CI: 3.3, 3.4, 4.0)
-- **Lint + Test**: `bundle exec rake`
+- **Lint + Test**: `bin/rake` (runs the default task: test + standard + steep:check)
 - **Autoloading**: Zeitwerk (file paths must match module/class names)
 - **Model format**: `provider/model` (e.g., `openai/gpt-4`)
 - **Docs**: when adding a public config option or message attribute, update the matching page in `docs/` (e.g., `docs/10_CONFIGURATION.md`, `docs/08_MESSAGES.md`). RDoc ≠ user docs.
@@ -21,12 +21,19 @@ Ruby gem framework for building AI-powered agents with LLM provider adapters.
 
 ## Commands
 
-| Command                         | Description                    |
-| ------------------------------- | ------------------------------ |
-| `bundle exec rake`              | Run tests + lint (default)     |
-| `bundle exec rake test`         | Run tests only                 |
-| `bundle exec rake standard`     | Check code style               |
-| `bundle exec rake standard:fix` | Auto-fix style issues          |
-| `bundle exec rake rbs:generate` | Generate RBS type signatures   |
-| `bundle exec rake rbs:watch`    | Watch and regenerate RBS files |
-| `bin/console`                   | Interactive console            |
+All wrappers `exec bundle exec …` under the hood.
+
+| Command         | Description                                  |
+| --------------- | -------------------------------------------- |
+| `bin/rake`      | Default task: test + standard + steep:check  |
+| `bin/test`      | Run tests                                    |
+| `bin/lint`      | Check code style (pass `--fix` to auto-fix)  |
+| `bin/typecheck` | Run Steep type checker                       |
+| `bin/rbs`       | Generate RBS type signatures                 |
+| `bin/rbs-watch` | Watch and regenerate RBS files               |
+| `bin/docs`      | Build RDoc HTML                              |
+| `bin/build`     | Build the gem package                        |
+| `bin/console`   | Interactive console                          |
+| `bin/setup`     | Install dependencies                         |
+
+`bin/rake <task>` is the escape hatch for any rake task without a named wrapper.

data/CHANGELOG.md

@@ -5,6 +5,25 @@ 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.29.0](https://github.com/janeapp/riffer/compare/riffer/v0.28.0...riffer/v0.29.0) (2026-05-29)
+
+
+### ⚠ BREAKING CHANGES
+
+* move leaf types out of root Riffer namespace ([#282](https://github.com/janeapp/riffer/issues/282))
+* Public API reshape on `Riffer::Agent`. Downstream consumers must migrate the following surfaces:
+
+### Features
+
+* add bin/ wrappers for common dev commands ([#276](https://github.com/janeapp/riffer/issues/276)) ([6812ba2](https://github.com/janeapp/riffer/commit/6812ba254d0b9220dae5ed0bbfbc4d8fee5b14e1))
+* add OpenRouter provider ([#280](https://github.com/janeapp/riffer/issues/280)) ([0d615b6](https://github.com/janeapp/riffer/commit/0d615b60ec3bb65091df16142a8e67f2afceea74))
+
+
+### Code Refactoring
+
+* extract Riffer::Agent::Run, eagerly resolve per-agent state ([#268](https://github.com/janeapp/riffer/issues/268)) ([1d9e141](https://github.com/janeapp/riffer/commit/1d9e141e8a381eaac13f107ca29b726b4d84b3f3))
+* move leaf types out of root Riffer namespace ([#282](https://github.com/janeapp/riffer/issues/282)) ([3637a53](https://github.com/janeapp/riffer/commit/3637a53ae8160e70bdaeae3d49812adfefac2c4b))
+
 ## [0.28.0](https://github.com/janeapp/riffer/compare/riffer/v0.27.2...riffer/v0.28.0) (2026-05-08)
 
 

data/README.md

@@ -68,7 +68,7 @@ For comprehensive documentation, see the [docs](docs/) directory:
 Generate the full API documentation with:
 
 ```bash
-bundle exec rake docs
+bin/docs
 ```
 
 Then open `doc/index.html` in your browser.
@@ -81,24 +81,23 @@ After checking out the repo, run:
 bin/setup
 ```
 
-Run the test suite:
+Common workflows are wrapped in `bin/`. Each is a thin `exec bundle exec …` script — use them
+instead of typing `bundle exec` yourself:
 
-```bash
-bundle exec rake test
-```
-
-Check and fix code style:
+| Command         | Description                                  |
+| --------------- | -------------------------------------------- |
+| `bin/rake`      | Default task: test + standard + steep:check  |
+| `bin/test`      | Run tests                                    |
+| `bin/lint`      | Check code style (pass `--fix` to auto-fix)  |
+| `bin/typecheck` | Run Steep type checker                       |
+| `bin/rbs`       | Generate RBS type signatures                 |
+| `bin/rbs-watch` | Watch and regenerate RBS files               |
+| `bin/docs`      | Build RDoc HTML                              |
+| `bin/build`     | Build the gem package                        |
+| `bin/console`   | Interactive console                          |
 
-```bash
-bundle exec rake standard
-bundle exec rake standard:fix
-```
-
-Run the interactive console:
-
-```bash
-bin/console
-```
+`bin/rake <task>` is the escape hatch for any rake task without a named wrapper (e.g.
+`bin/rake test:slow`, `bin/rake release`).
 
 ### Recording VCR Cassettes
 
@@ -125,7 +124,7 @@ VCR records the HTTP interactions to `test/fixtures/vcr_cassettes/` on the first
 ## Contributing
 
 1. Fork the repository and create your branch: `git checkout -b feature/foo`
-2. Run tests and linters locally: `bundle exec rake`
+2. Run tests and linters locally: `bin/rake`
 3. Submit a pull request with a clear description of the change
 
 Please follow the [Code of Conduct](https://github.com/janeapp/riffer/blob/main/CODE_OF_CONDUCT.md).

data/Steepfile

@@ -2,16 +2,22 @@ D = Steep::Diagnostic
 
 target :lib do
   signature "sig/generated"
+  signature "sig/stubs"
 
   check "lib"
 
   library "anthropic"
   library "aws-sdk-bedrockruntime"
   library "aws-sdk-core"
+  library "base64"
+  library "cgi"
+  library "json"
   library "logger"
   library "net-http"
   library "openai"
+  library "securerandom"
   library "uri"
+  library "yaml"
 
-  configure_code_diagnostics(D::Ruby.lenient)
+  configure_code_diagnostics(D::Ruby.strict)
 end

data/docs/03_AGENTS.md

@@ -84,7 +84,7 @@ end
 MyAgent.generate('Hello!', context: { name: 'Jane' })
 ```
 
-The lambda is re-evaluated on each `generate` or `stream` call, so instructions can change between calls based on runtime context.
+The lambda is evaluated once at `Agent.new` time using the context passed to the constructor. To change instructions for a new context, construct a new agent.
 
 ### identifier
 
@@ -259,11 +259,11 @@ Configures how tool calls are executed. Defaults to sequential (inline) executio
 class MyAgent < Riffer::Agent
   model 'openai/gpt-5-mini'
   uses_tools [WeatherTool, SearchTool]
-  tool_runtime Riffer::ToolRuntime::Threaded
+  tool_runtime Riffer::Tools::Runtime::Threaded
 end
 ```
 
-Accepts a `Riffer::ToolRuntime` subclass, a `Riffer::ToolRuntime` instance, or a `Proc`. Inherited by subclasses. When unset, falls back to `Riffer.config.tool_runtime`. See [Tools — Tool Runtime](07_TOOL_ADVANCED.md#tool-runtime-experimental) for details.
+Accepts a `Riffer::Tools::Runtime` subclass, a `Riffer::Tools::Runtime` instance, or a `Proc`. When unset, defaults to `Riffer.config.tool_runtime` (captured at agent class definition time). See [Tools — Tool Runtime](07_TOOL_ADVANCED.md#tool-runtime-experimental) for details.
 
 ### guardrail
 
@@ -286,6 +286,37 @@ end
 
 See [Guardrails](12_GUARDRAILS.md) for detailed documentation.
 
+## Configuration Object
+
+Every DSL setting above is stored on a `Riffer::Agent::Config` instance accessible via the class. Each subclass has its own:
+
+```ruby
+class MyAgent < Riffer::Agent
+  model 'openai/gpt-5-mini'
+  max_steps 8
+end
+
+MyAgent.config            # => #<Riffer::Agent::Config ...>
+MyAgent.config.max_steps  # => 8
+```
+
+The DSL methods read and mutate this Config in place.
+
+For advanced composition or testing, build a Config directly and pass it via `config:` to bypass class-level DSL entirely:
+
+```ruby
+config = Riffer::Agent::Config.new(
+  model: 'openai/gpt-5-mini',
+  instructions: 'You are a helpful assistant.',
+  max_steps: 4
+)
+
+agent = Riffer::Agent.new(config: config)
+agent.generate('Hello')
+```
+
+When `config:` is supplied, the class-level configuration is ignored for that instance.
+
 ## Expand Your Agent
 
 | Goal                          | Feature           | Guide                                                                |