axn-ruby_llm 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5339909ae113dc742efe969fb25ae90294abef8090629c5fc9f452acdb98757d
-  data.tar.gz: 8d73239e08a8ab270fc6edb980557e6b1932e63e9fdbdcd6f26bfb431b2a5c47
+  metadata.gz: c33a22550fbc081c47ad09e370ce05aa400640cfe70f2e06488d93b1507a42a6
+  data.tar.gz: 1d65bcd8eeee475aee68c7a92e380601f8c3e333629fe6664609c0e1174e2f64
 SHA512:
-  metadata.gz: 75587b0c6a29875e2de143459b0b2ac1280581cb9e3b2a080777737ed803fda05008f0703a31522a4d5bcb47ea10998ef6236e1917bc9157f10fcaf278f97f3f
-  data.tar.gz: 21d44dcc5fc6bc41615cc472648737b2c6491d05dfc1d469b7c884bed2d7a260da574f83b5f14d8b0ff97694fdf60f2428d4db72a22123fe0764b47f0606b7c4
+  metadata.gz: c9b764c927824c06c5f14d8b186ede7c63182cda2259991e444e6226f45a0277b51433f8ea5246f0438623a59e9e4827d7ee393391db53f028e00178f154de1d
+  data.tar.gz: 5cc0b5fcda8f30cf1961cc44839c08d5447787262247f6ebd460d53c4ff9478143a9b4e1b7414082917d8052b4757770113e2e3451c206283e6ad49ff5cfb754

data/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## [0.2.0] - 2026-08-05
+
+> **Upgrade notes (behavior changes):**
+> - **`Ask` failure messages changed wording.** Code that pattern-matches on `result.error` strings may need updating: unrecognized exceptions no longer include the underlying exception message, and 5xx / context-length errors now have their own more specific text (see Changed below). `result.ok?`-based control flow is unaffected.
+> - **Requires a newer `axn`** — this release depends on core reflection, the tool registry + `tool_name`, and namespaced `configure(...)` (see Requires below).
+> - No public API was removed, and no config or `wrap` option changed name or default.
+
+### Added
+
+- **Tool adapter — wrap any Axn as a `RubyLLM::Tool`.** `Axn::RubyLLM.wrap(any_axn)` turns any Axn into a `::RubyLLM::Tool` a chat can call, with no adapter-specific mixin: its name, description, and JSON Schema parameters come from the Axn's own `description`/`expects`/`exposes` contract. On success the tool returns the exposed values as JSON (or `result.message`, per `present_as:`); on failure, `{ error: <result.error> }`. Malformed tool calls — a missing/unknown/wrong-typed argument, a value outside an `inclusion` set (validated at full depth via axn's tool `Invoker`), or an injected `ambient_context:` — come back to the model as a clean `Invalid tool arguments` error and never page `on_exception`. A result core can't serialize (two Hash keys colliding on one JSON property, a non-finite Float, non-UTF-8 bytes) or one nested past the JSON encoder's `max_nesting` likewise surfaces as a tool error instead of breaking the chat. Per-tool options `halt_after:`, `provider_params:`, `present_as:` (`:structured` / `:message`), and `ambient_context:` are settable per-call, per-class via `configure(:ruby_llm) { |c| ... }` (or inline via `tool ruby_llm: { ... }`), or gem-wide via `Axn::RubyLLM.configure`. The same Axn advertises an identical tool name whether wrapped here or by `Axn::MCP.wrap`. See the README's "Tool adapter" section.
+- **Tools in `ask`.** `Axn::RubyLLM.ask(prompt:, tools: [...])` registers wrapped Axns on the chat and runs RubyLLM's tool-call loop within the single call. `tools:` takes bare Axn classes (wrapped automatically) and already-wrapped tools alike, or pass `Axn::RubyLLM.tools` for everything registered. Token counts, `cost`, and `cost_breakdown` are summed across every turn of the loop (not just the final response; `raw_message` remains the final response).
+- **Tool registry integration.** `Axn::RubyLLM.tools` returns every Axn registered under the `:ruby_llm` adapter — one whose file lives under the adapter's `tool_roots` (default `["agent_tools"]`), or that declares `tool` / `tool :ruby_llm`, or that carries a `configure(:ruby_llm)` bag, minus any `tool false` / `tool except: :ruby_llm` opt-outs — each wrapped and ready to register in stable, `tool_name`-sorted order: `chat.with_tools(*Axn::RubyLLM.tools)`. When tools declare `tool_version`, only the latest version per `tool_name` is returned. Configure the directories via `Axn::RubyLLM.configure { |c| c.tool_roots = [...] }`.
+- **`error_headline` config** (default `"LLM request failed"`) overrides the prefix on every `Ask` failure without subclassing.
+- **Adapter-boundary never-raises guard.** The wrapper's `execute`/`.call` upholds axn's non-bang "never raises" contract: if turning a *successful* result into a tool response raises in the transport step (an unserializable value, a structure past the JSON encoder's `max_nesting`, or a gem bug), the adapter reports it through `Axn.config.on_exception` and returns a generic tool error (`"The tool could not produce a valid response"`) instead of letting the exception escape and break the chat — re-raising in development (per core's `best_effort_raises_in_dev`) so real bugs surface loudly. The client-facing text is generic by design; the actionable detail rides on the reported exception. Mirrors axn-mcp's adapter-boundary guard.
+- **`reject_opaque_exposed_values` config** (default `false`; per-tool via `configure(:ruby_llm)`, per-class wins). When `true`, a tool result holding a value with no author-declared JSON form — one that would otherwise ship as an opaque blob (`"#<User:0x…>"`, or an ActiveSupport instance-variable dump under Rails) — fails as a tool error instead. Output-side only; the always-on rejections (reference cycles, non-finite Floats, non-UTF-8 bytes, colliding JSON keys) are unaffected. Mirrors axn-mcp's knob; built on `serialize_exposed(reject_opaque:)` from axn [#206](https://github.com/teamshares/axn/pull/206) (PRO-2988).
+
+### Changed
+
+- **`Ask` failures now carry a consistent `"LLM request failed: <reason>"` message, with more specific reasons.** Rate limits, transient provider errors (5xx → "Provider temporarily unavailable, try again later"), context-length-exceeded, and invalid-JSON responses each get their own wording; the provider's own message is preserved where useful. Unrecognized exceptions (likely bugs, not known RubyLLM/network failures) now fail with the bare headline and no leaked exception detail — error reporting via `Axn.config.on_exception` is unaffected. See the README's "Errors" section.
+- **OpenTelemetry attribute recording is guarded by axn's `Extensions.best_effort` helper** — a telemetry failure now warn-logs (and fails loud in development) instead of vanishing silently, while still never breaking the LLM call.
+- **Production gating: read the resolved gate via `Axn::RubyLLM.enabled?`.** axn's `Configurable` dropped its `callable:` kwarg (axn [#209](https://github.com/teamshares/axn/pull/209) / PRO-3017), so it no longer invokes an assigned `enabled` callable on read. Callable resolution moved into this gem — `Axn::RubyLLM.enabled?` invokes the callable and returns a Boolean, and is the supported reader. The DSL-generated `Axn::RubyLLM.config.enabled?` returns an assigned Proc as-is (always truthy) and must not be used for the gate.
+
+### Requires
+
+- An `axn` version providing core contract reflection, the tool registry (per-adapter `tool_roots` + union membership) with canonical `tool_name`, the tool `Invoker` (input-validation surfacing), the extension-author surface (`Axn::Extensions.best_effort` and the `Axn::Extensions::Serialization.render` result serializer — axn [#207](https://github.com/teamshares/axn/pull/207) / PRO-2992, which made `Axn::Reflection::Values.serialize_exposed` private), and namespaced per-class `configure(...)`. Satisfied by the released `axn` `0.1.0-alpha.5`, resolved from RubyGems (the gemspec pins `>= 0.1.0-alpha.5, < 0.2.0`).
+
+## [0.1.3] - 2026-06-26
+
+Adopts Axn's `Configurable` DSL for gem configuration (requires the axn version that ships `Axn::Configurable`).
+
+- Replace the hand-rolled `Configuration` class with `extend Axn::Configurable`, declaring `default_model` (default `"gpt-4o-mini"`) and `enabled` (default `true`, callable) as settings.
+- **Rename** `Axn::RubyLLM.configuration` → `Axn::RubyLLM.config` and `Axn::RubyLLM.reset_configuration!` → `Axn::RubyLLM.reset_config!`, matching the DSL's standard surface. `Axn::RubyLLM.configure { |c| ... }` is unchanged.
+- The old names are kept as **deprecated aliases** — they still work but emit a deprecation warning (`category: :deprecated`) and are scheduled for removal in the next minor version. See [DEPRECATIONS.md](DEPRECATIONS.md).
+
+Also migrates the `Ask` error-message DSL to axn's new message-presentation semantics ([axn#109](https://github.com/teamshares/axn/pull/109), [#132](https://github.com/teamshares/axn/pull/132), [#134](https://github.com/teamshares/axn/pull/134)), which replaced per-message `prefix:` with a base `error`/`success` headline plus a `standalone:` attach flag. Requires the axn version that ships these.
+
+- **`result.error` now carries a consistent `"LLM request failed: <reason>"` headline for every failure mode** (previously only unhandled exceptions were prefixed). Affected strings:
+  - Rate limit: `"LLM request failed: Rate limit reached: <message>"`
+  - Schema parse: `"LLM request failed: Schema response was not valid JSON"`
+  - JSON parse: `"LLM request failed: Response was not valid JSON"` (reason reworded from `"Failed to parse JSON from LLM response"` so it joins the headline cleanly)
+  - Unhandled exceptions: `"LLM request failed: <exception message>"` (unchanged)
+- **`result.success` now carries a meaningful headline** instead of axn's generic `"Action completed successfully"`:
+  - Normal calls: `"LLM request completed"`.
+  - Production-gated (disabled) calls: `"LLM request completed (using stubbed values - actual LLM request disabled)"`.
+
 ## [0.1.2] - 2026-06-11
 
 Requires RubyLLM >= 1.15 (minimum version bumped from 1.0).

data/README.md

@@ -1,12 +1,12 @@
 # axn-ruby_llm
 
-Call LLMs from [Axn](https://github.com/teamshares/axn) actions using [RubyLLM](https://github.com/crmne/ruby_llm), with declarative error handling, optional JSON mode, configurable defaults, and cost/token tracking.
+Call LLMs from [Axn](https://github.com/teamshares/axn) actions using [RubyLLM](https://github.com/crmne/ruby_llm), with declarative error handling, optional JSON mode, configurable defaults, and cost/token tracking — and wrap any Axn as a `RubyLLM::Tool` a chat can call.
 
 Part of the `axn-*` extension ecosystem — see also [axn-mcp](https://github.com/teamshares/axn-mcp).
 
 ### Why use this over calling RubyLLM directly?
 
-Three things you'd otherwise build at every callsite:
+Four things you'd otherwise hand-build:
 
 1. **Structured error handling.** The Axn error DSL declaratively maps `RateLimitError`, `JSON::ParserError`, and generic `StandardError` to clean failure messages. Callers check `result.ok?` instead of wrapping every call in `begin/rescue`.
 
@@ -14,7 +14,9 @@ Three things you'd otherwise build at every callsite:
 
 3. **Cost/token tracking, exposed automatically.** Every call exposes `input_tokens`, `output_tokens`, `cache_read_tokens`, `cache_write_tokens`, `prompt_tokens` (the total), `cost`, and `cost_breakdown` without you doing the `RubyLLM.models.find` lookup manually. If your app uses OpenTelemetry, these values are also set as attributes on the existing `axn.call` span — no configuration required.
 
-> **Scope note:** This gem covers the subset of RubyLLM functionality that [Teamshares](https://github.com/teamshares) uses internally — single-turn chat, structured output, and basic observability. It is intentionally minimal rather than a full-featured wrapper. Feedback and pull requests to extend it are very welcome.
+4. **Author-once tools.** `Axn::RubyLLM.wrap` turns any Axn into a `RubyLLM::Tool` your chat can call — reuse the same Axn classes you already expose through [axn-mcp](https://github.com/teamshares/axn-mcp), or plain Axns, with no rewrite. The tool's name, JSON Schema, and argument validation all come from the Axn's own contract.
+
+> **Scope note:** This gem covers the subset of RubyLLM functionality that [Teamshares](https://github.com/teamshares) uses internally — single-turn chat, structured output, basic observability, and wrapping Axns as tools. It is intentionally minimal rather than a full-featured wrapper. Feedback and pull requests to extend it are very welcome.
 
 ---
 
@@ -37,7 +39,8 @@ Optionally configure gem-level defaults:
 
 ```ruby
 Axn::RubyLLM.configure do |c|
-  c.default_model = "gpt-4o-mini" # default; override with any RubyLLM model ID
+  c.default_model = "gpt-4o-mini"          # default; override with any RubyLLM model ID
+  c.error_headline = "LLM request failed"  # default; prefixes every result.error (see Errors below)
 end
 ```
 
@@ -109,26 +112,208 @@ result.raw_message     # => #<RubyLLM::Message ...>
 
 `cost` and `cost_breakdown` are both `nil` when RubyLLM lacks pricing for the model (e.g. unknown/custom endpoints). Token counts are nil only if the provider did not return them. `prompt_tokens` is nil only if all three input token fields are nil.
 
-Errors are handled via Axn's declarative `error` DSL:
-- `JSON::ParserError` → result fails with `"Failed to parse JSON from LLM response"`
-- `RubyLLM::RateLimitError` (HTTP 429, provider-agnostic) → result fails with `"Rate limit reached: <message>"`
-- `schema:` set but LLM returned non-JSON → result fails with `"Schema response was not valid JSON"`
-- Any other `StandardError` → result fails with `"LLM request failed: <message>"`
+### Errors
+
+Errors are handled via Axn's declarative `error` DSL. Every failure shares a consistent `"LLM request failed: <reason>"` headline (the headline itself is configurable via `c.error_headline =`, e.g. to `"Something went wrong calling the LLM"`; the reasons below are unaffected):
+- `JSON::ParserError` → `"LLM request failed: Response was not valid JSON"`
+- `RubyLLM::RateLimitError` (HTTP 429, provider-agnostic) → `"LLM request failed: Rate limit reached: <message>"`
+- `RubyLLM::OverloadedError` / `ServiceUnavailableError` / `ServerError` (5xx, transient) → `"LLM request failed: Provider temporarily unavailable, try again later: <message>"`
+- `RubyLLM::ContextLengthExceededError` → `"LLM request failed: Prompt exceeds the model's context window: <message>"` (message retains the provider's token counts)
+- `schema:` set but LLM returned non-JSON → `"LLM request failed: Schema response was not valid JSON"`
+- Any other known RubyLLM error — `RubyLLM::Error` (auth, bad request, payment, etc.), `RubyLLM::ConfigurationError`, `ModelNotFoundError`, `PromptNotFoundError`, `InvalidRoleError`, `InvalidToolChoiceError`, `UnsupportedAttachmentError` — or `Faraday::Error` (network/transport failure) → `"LLM request failed: <message>"`
+- Any other `StandardError` (i.e. not a recognized RubyLLM/network failure — most likely a bug) → `"LLM request failed"`, with no exception detail leaked into the message
+
+## Tool adapter — wrap any Axn as a RubyLLM::Tool
+
+Any [Axn](https://github.com/teamshares/axn) can be exposed as a `::RubyLLM::Tool` — no adapter-specific mixin required, it's just a normal Axn:
+
+```ruby
+class CreateWidget
+  include Axn
+
+  description "Creates a widget with the given name"
+  expects :name, type: String
+  exposes :widget_id
+
+  def call
+    expose widget_id: Widget.create!(name:).id
+  end
+end
+```
+
+Pass Axns to `Axn::RubyLLM.ask` via `tools:` and the model can call them as part of the request — RubyLLM runs the tool-call loop internally and `result.response` is the model's final reply:
+
+```ruby
+result = Axn::RubyLLM.ask(
+  prompt: "Create a widget called Sprocket, then tell me its id.",
+  tools: [CreateWidget],
+)
+result.response # => "Created widget Sprocket (id: 42)."
+```
+
+`tools:` accepts a mix of **bare Axn classes** (wrapped automatically) and **already-wrapped tools** from `Axn::RubyLLM.wrap` (a class, or an instance that closed over `ambient_context:` — see below). Pass `tools: Axn::RubyLLM.tools` to expose everything registered under the `:ruby_llm` adapter (see [Enumerating tools](#enumerating-tools-from-the-registry)). The same Axn classes you expose through [axn-mcp](https://github.com/teamshares/axn-mcp) work here unchanged.
+
+> **Token/cost in a tool loop:** a tool call makes multiple model round-trips inside one `ask`. The token counts, `cost`, and `cost_breakdown` are **summed across every turn**, so they reflect the whole call — not just the final response. (`raw_message` is still the final response.)
+
+`Axn::RubyLLM.wrap` is also available directly if you're driving `RubyLLM.chat` yourself rather than going through `ask` — see [Using wrapped tools with RubyLLM directly](#using-wrapped-tools-with-rubyllm-directly).
+
+The tool's name, description, and JSON Schema parameters come straight from the Axn's own contract — the same `description`/`expects`/`exposes` you'd write for any Axn — so a minimal class just works (the tool name defaults from the class name: `CreateWidget` → `create_widget`). Arguments the model supplies are run through axn core's tool `Invoker`: wire types are coerced, and any contract violation — a missing required field, an out-of-schema argument, a wrong type, or a value outside an `inclusion` set (validated at **full depth**, not just the top-level type) — comes back to the model as a clean, correctable `{ error: "Invalid tool arguments: <reason>" }`, and does **not** page `on_exception` as though it were a bug. A model-supplied `ambient_context` is stripped before the Axn runs, so a prompt-injected context can never override the caller's — the wrap's own `ambient_context:` (below) is injected instead.
+
+On success, `execute` returns the exposed values (via `Axn::Extensions::Serialization.render`) as a JSON **string**, not a Hash — `RubyLLM::Chat#handle_tool_calls` only passes a `Content`/`Content::Raw` return through as-is, and otherwise sends `tool_payload.to_s`, which for a Hash produces Ruby's inspect syntax rather than JSON; on failure, `{ error: result.error }`. The same `CreateWidget` class can be wrapped for other transports (e.g. `Axn::MCP.wrap`) with no changes — the contract is declared once.
+
+Options, settable either per-call via `wrap` keywords or once on the Axn via axn's namespaced per-class `configure(:ruby_llm) { |c| ... }` (a `wrap` keyword wins when both are present, then the class-level `configure(:ruby_llm)` value, then this gem's own `Axn::RubyLLM.configure { |c| ... }` global, then the default below):
+
+| Option | Effect |
+|---|---|
+| `halt_after:` | When `true`, wraps a successful payload in `RubyLLM::Tool::Halt` to stop the agent loop after this call. Default `false`. |
+| `provider_params:` | Hash deep-merged into the tool definition sent to the provider (via RubyLLM's `with_params`) — an escape hatch for provider-specific tool fields RubyLLM doesn't model first-class (e.g. OpenAI `strict` function calling, Anthropic tool `cache_control`). Keys mirror that provider's tool shape. Default `{}`. |
+| `present_as:` | `:structured` (default) returns the exposed values as a JSON string; `:message` returns `result.message` instead. Same knob as axn-mcp's `present_as:`. |
+
+Set a default once on the Axn with `configure(:ruby_llm)`, and still override per call:
+
+```ruby
+class CreateWidget
+  include Axn
+  configure(:ruby_llm) { |c| c.halt_after = true }   # default for this tool
+  # ...
+end
+
+Axn::RubyLLM.wrap(CreateWidget)                      # halts after running
+Axn::RubyLLM.wrap(CreateWidget, halt_after: false)   # per-call override
+```
+
+`configure(:ruby_llm)` needs no `include` beyond `Axn` — every Axn gets it for free (core's namespaced per-class config). It's usually written in the class body as above, but since it's a plain class method you can also call it from outside — e.g. `SomeThirdPartyAxn.configure(:ruby_llm) { |c| ... }` in an initializer, to configure an Axn you don't own. Namespacing is what lets **one base Axn be configured for multiple adapters at once**, each in its own namespace, without collision even when two adapters share a setting name (both this gem and axn-mcp expose `present_as`):
+
+```ruby
+class CreateWidget
+  include Axn
+  # ...
+
+  configure(:ruby_llm) { |c| c.present_as = :message }    # how the RubyLLM tool presents its result
+  configure(:mcp)      { |c| c.present_as = :structured } # same setting name, different namespace — no collision
+end
+```
+
+Pass `ambient_context:` to close over explicit caller context (e.g. `current_user`, `company`) at wrap time, instead of relying on axn's reflective `Current`-based default resolved when the tool runs. This matters when the tool executes somewhere `Current` isn't the right context — e.g. the chat (and therefore the tool call) runs in a background job or a different thread than the request that built the tools:
+
+```ruby
+Axn::RubyLLM.wrap(CreateWidget, ambient_context: { company_id: current_company.id })
+```
+
+Passing `ambient_context:` returns a tool **instance** (closing over that context) rather than the tool class, since `chat.with_tool` accepts either.
+
+### Using wrapped tools with RubyLLM directly
+
+`Axn::RubyLLM.ask(tools:)` covers the common single-call case. When you're driving `RubyLLM.chat` yourself — multi-turn conversations, streaming, or anything else beyond `ask` — register wrapped tools with RubyLLM's own `with_tool` / `with_tools`, which accept a `RubyLLM::Tool` class or instance:
+
+```ruby
+chat = RubyLLM.chat.with_tool(Axn::RubyLLM.wrap(CreateWidget))
+chat.ask("Create a widget called Sprocket")
+
+# or register everything under the :ruby_llm adapter at once:
+chat = RubyLLM.chat.with_tools(*Axn::RubyLLM.tools)
+```
+
+### Tool naming
+
+The name is axn core's canonical, provider-safe `tool_name`: lowercased to `[a-z0-9_]`, leading configured prefixes stripped, snake_cased with single underscores, and never blank (`Admin::CreateWidget` → `admin_create_widget`; a truly anonymous Axn → `"tool"`). Declare `axn_name "..."` on the Axn to override the default. Because it's the same core derivation every adapter uses, a class wrapped by both `Axn::RubyLLM.wrap` and `Axn::MCP.wrap` advertises an identical name — the contract is declared once.
+
+### Enumerating tools from the registry
+
+Rather than wiring each tool up by hand, let axn's tool registry find them and build the whole chat tool list in one call:
+
+```ruby
+chat = RubyLLM.chat.with_tools(*Axn::RubyLLM.tools)
+```
+
+`Axn::RubyLLM.tools` returns every Axn registered under the `:ruby_llm` adapter, already wrapped as a `::RubyLLM::Tool` — sugar for `Axn::Tools.for(:ruby_llm).map { |axn| Axn::RubyLLM.wrap(axn) }`, in a stable, `tool_name`-sorted order.
+
+**Membership = (directory grant ∪ declaration grant) − exclusions.** An Axn is a `:ruby_llm` tool if either:
+
+- **Directory grant** — its file lives under one of the adapter's `tool_roots`. The default is `["agent_tools"]` (→ `app/agent_tools` in a Rails app), so **an Axn dropped in `app/agent_tools` is a tool with no declaration at all**. Configure the roots with `Axn::RubyLLM.configure { |c| c.tool_roots = ["agent_tools", "actions/tools"] }`; each entry must be a narrow subdir (`app/`, `actions`, `.`, and `..` are rejected, so you can't bulk-expose every action).
+- **Declaration grant** — it declares `tool` (every adapter), `tool :ruby_llm`, or carries a `configure(:ruby_llm)` bag.
+
+…unless it opts out: `tool false` (no adapter) or `tool except: :ruby_llm` (keep the directory grant, drop this adapter).
+
+```ruby
+class CreateWidget
+  include Axn
+  tool :ruby_llm                              # add :ruby_llm (on top of any directory grant)
+  tool ruby_llm: { present_as: :message }     # …or add it AND set per-adapter options inline
+  # ...
+end
+```
+
+Because both adapters read the registry and the same canonical `tool_name`, the identical set of Axns exposed via `Axn::MCP.tools` advertises identical names — and since both default `tool_roots` to `agent_tools`, an Axn there is authored once and is a tool on both surfaces.
+
+> **Upgrading from the pre-registry API:** `tool :ruby_llm` now **adds** to the directory grant rather than replacing it (declare all adapters, `name:`, `except:`, and per-adapter options in a single `tool` call). And the old global `Axn.config.tool_paths` is **gone** — each adapter owns its own `tool_roots`, so point `Axn::RubyLLM.config.tool_roots` (and `Axn::MCP`'s) at your tool dirs instead.
+
+### Date/Time/Symbol/Integer/Float fields — declare `coerce:`
+
+A provider always sends tool-call arguments as JSON, so a `Date`/`Time`/`DateTime`/`Symbol`/`Integer`/`Float`-typed field arrives as a **String** (e.g. `"2026-07-08"`), which the plain `type:` validator rejects — it checks `value.is_a?(klass)`, not a parse. Declare `coerce:` on that `expects` field so axn parses the wire string before validation runs:
+
+```ruby
+expects :scheduled_for, coerce: Date          # sugar for type: { klass: Date, coerce: true }
+expects :priority, type: { klass: Symbol, coerce: true } # explicit form, e.g. alongside other type: options
+```
+
+Opt-in per field — a field with no `coerce:` is unaffected. A non-String value (a direct Ruby caller's real `Date`, a JSON-native number) is left untouched either way.
+
+### Opaque exposed values — `reject_opaque_exposed_values`
+
+A tool's result is the Axn's exposed values serialized to JSON. A value with **no author-declared JSON form** — no `to_json`/`as_json` of its own — has no honest representation and can only render as an *opaque blob*: `"#<User:0x000…>"` outside Rails, or ActiveSupport's generic instance-variable dump under it. By default that blob ships, because for an LLM tool result an ugly-but-honest string usually beats a failed call.
+
+Set `reject_opaque_exposed_values` (default `false`) to reject it instead. Serialization then raises `Axn::Extensions::Serialization::UnserializableValue` (naming the path, e.g. `records[3].owner`), which the adapter's transport-boundary guard (below) turns into a generic tool error rather than shipping the blob:
+
+```ruby
+CreateWidget.configure(:ruby_llm) { |c| c.reject_opaque_exposed_values = true }   # per tool (wins)
+Axn::RubyLLM.configure           { |c| c.reject_opaque_exposed_values = true }    # gem-wide default
+```
+
+Scope:
+
+- **Output-side only.** It governs `exposes` serialization, never inbound `coerce:` on `expects`.
+- **Narrow.** Values with *no honest JSON form at all* — reference cycles, non-finite Floats, non-UTF-8 bytes, two Hash keys colliding onto one property — raise `UnserializableValue` **regardless** of this flag (and surface as a tool error). `reject_opaque_exposed_values` only adds the extra "was this rendering author-declared?" check on top.
+
+### Transport-boundary never-raises guard
+
+A wrapped Axn's own `.call` never raises — core catches action exceptions into a failed `Result` and pages `on_exception` itself. But the transport step that runs *after* the Axn settles — serializing the exposed values, encoding them to JSON — happens outside core's executor and *can* raise (an unserializable value as above, a structure past the JSON encoder's `max_nesting`, or a plain gem bug). Since RubyLLM has no rescue around a tool's `execute`, an escaping exception there would break the whole chat.
+
+So the adapter guards that mapping step (only — the Axn call already reports its own exceptions): any `StandardError` is reported through `Axn.config.on_exception` and the tool returns a **generic** error, `"The tool could not produce a valid response"`. The message is deliberately generic — the actionable detail (exception class, path) rides on the reported exception, not the tool's response. In development (per core's `best_effort_raises_in_dev`) the exception is re-raised instead, so a real bug surfaces loudly rather than being masked. This mirrors [axn-mcp](https://github.com/teamshares/axn-mcp)'s adapter-boundary guard.
+
+### Schema reflection — provider notes
+
+The advertised tool schema is axn's reflected `input_schema`. A few things worth knowing when you care how it lands at a specific provider (Gemini is the strictest — it runs a mandatory OpenAPI-subset converter; OpenAI and Anthropic pass the schema through as-is):
+
+- **Nullable/optional fields** — handled. axn reflects a nullable field as an array-valued `type` (`["integer", "null"]`); the adapter rewrites that to the equivalent `anyOf` form, because Gemini's converter can't read array-valued types and would otherwise collapse the field to `STRING`. No action needed on your part.
+- **Array fields — declare `of:`.** `expects :ids, type: Array` reflects to `{type: array}` with no `items`, so the element type isn't advertised (Gemini then assumes `string`; OpenAI *strict* mode requires `items`). Declare the element type — `expects :ids, type: Array, of: Integer` — to advertise `items` correctly.
+- **Enums are advertised — use the top-level `inclusion:` key.** `expects :color, type: String, inclusion: %w[red green blue]` (a bare Array, or the long form `inclusion: { in: %w[red green blue] }`) reflects to `{ type: "string", enum: ["red", "green", "blue"] }`, so the model is told the allowed set (an `optional:` field keeps `null` in the enum; a dynamic `in: -> { ... }` is correctly skipped rather than guessed). Note this is the **top-level `inclusion:` option**, not `validate: { inclusion: ... }` — `validate:` is axn's custom-callable hook (it needs `with:`), so that spelling neither enforces nor reflects the set.
+- **Conditional expectations** (`expects :token, if: :use_token`) reflect to a JSON Schema `allOf`/`if`/`then` clause. Gemini's converter ignores it — the field degrades to plain-optional (safe: a valid call is never wrongly rejected, but the conditional isn't conveyed to the model). This gem doesn't set OpenAI's `strict` mode, so OpenAI tolerates `allOf` by default; if you opt into strict via `provider_params`, OpenAI will reject `allOf`. Either way, encoding the rule in `description:` is the portable option.
 
 ## Testing
 
-In your specs, require the helpers and use `stub_axn_ruby_llm`:
+In your specs, require the helpers and use `stub_axn_ruby_llm` to stub RubyLLM so `Axn::RubyLLM.ask` returns a canned response without a real API call:
 
 ```ruby
 require "axn/ruby_llm/rspec"
 
 it "summarizes the thread" do
-  stub_axn_ruby_llm(response: "The team agreed to ship on Friday.")
+  stub_axn_ruby_llm("The team agreed to ship on Friday.")
   result = Axn::RubyLLM.ask(prompt: "...")
   expect(result.response).to include("ship on Friday")
 end
 ```
 
+The response is the only required argument — pass it positionally (as above) or as `response:`. A Hash response is auto-JSON-serialized for `json: true` calls; pass `schema:` to route a Hash through the schema path unparsed (and to assert the exact schema class). Token counts and cost default to zero and can be set explicitly to exercise cost/usage logic:
+
+```ruby
+stub_axn_ruby_llm({ "company_id" => 42 }, schema: CompanyMatch)
+stub_axn_ruby_llm("...", model: "gpt-4o", input_tokens: 100, output_tokens: 50, cost: 0.0023)
+stub_axn_ruby_llm("...", cache_read_tokens: 500, cache_write_tokens: 200)
+```
+
+Remaining keywords: `model:`, `schema:`, `input_tokens:`, `output_tokens:`, `cache_read_tokens:`, `cache_write_tokens:`, `cost:`. Returns the stubbed chat instance double for further assertions if you need it.
+
 ## OpenTelemetry
 
 If your app uses OpenTelemetry, `axn` already wraps every action in an `axn.call` span. This gem enriches that span with LLM-specific attributes automatically — no configuration required:
@@ -146,7 +331,7 @@ For LLM-level tracing (individual `RubyLLM.chat` calls, tool calls, embeddings,
 
 ## Production gating
 
-Set `Configuration#enabled` to gate LLM calls — useful for skipping spend in non-production environments. Accepts a Boolean or a callable (evaluated per call):
+Set the `enabled` config to gate LLM calls — useful for skipping spend in non-production environments. Accepts a Boolean or a callable (evaluated per call):
 
 ```ruby
 Axn::RubyLLM.configure do |c|
@@ -156,6 +341,8 @@ Axn::RubyLLM.configure do |c|
 end
 ```
 
+To read the resolved gate, use **`Axn::RubyLLM.enabled?`** — it invokes an assigned callable and returns a Boolean. (Don't use the DSL-generated `Axn::RubyLLM.config.enabled?`: axn's `Configurable` returns an assigned Proc as-is rather than calling it, so for a callable that predicate is always truthy.)
+
 When disabled, `Axn::RubyLLM.ask` returns a **success** result with obvious stub content, so callers don't need per-callsite branching:
 
 | Field | Stubbed value |
@@ -167,4 +354,4 @@ When disabled, `Axn::RubyLLM.ask` returns a **success** result with obvious stub
 | `cost_breakdown` | `nil` |
 | `stubbed` | `true` |
 
-Check `result.stubbed` if you need to branch on it (e.g. skip downstream writes that would otherwise persist stub LLM output). The Axn result's `message` is `"disabled - returning stubbed values"` for the same purpose.
+Check `result.stubbed` if you need to branch on it (e.g. skip downstream writes that would otherwise persist stub LLM output). `result.success` is `"LLM request completed (using stubbed values - actual LLM request disabled)"` for the same purpose; a normal (non-stubbed) call succeeds with `"LLM request completed"`.

data/lib/axn/ruby_llm/ask.rb

@@ -11,6 +11,7 @@ module Axn
       expects :model, optional: true
       expects :system_prompt, optional: true
       expects :temperature, optional: true
+      expects :tools, optional: true
 
       exposes :response
       exposes :raw_message
@@ -25,8 +26,39 @@ module Axn
 
       StubMessage = Data.define(:content, :input_tokens, :output_tokens, :cache_read_tokens, :cache_write_tokens, :model_id)
 
-      error prefix: "LLM request failed: "
-      error "Failed to parse JSON from LLM response", if: JSON::ParserError
+      # RubyLLM wraps HTTP-response-level provider errors (4xx/5xx) under RubyLLM::Error, but its
+      # non-HTTP errors (bad config, missing model/prompt/role, unsupported attachment) subclass
+      # StandardError directly -- so RubyLLM::Error alone misses them. Connection-level failures
+      # (timeout, DNS, refused) never reach RubyLLM at all and surface as raw Faraday errors. All
+      # three are "known" failure shapes safe to surface verbatim; anything outside this is a bug
+      # and must not leak its message into a user-facing result.
+      KNOWN_ERROR_CLASSES = [
+        ::RubyLLM::Error,
+        ::Faraday::Error,
+        ::RubyLLM::ConfigurationError,
+        ::RubyLLM::ModelNotFoundError,
+        ::RubyLLM::PromptNotFoundError,
+        ::RubyLLM::InvalidRoleError,
+        ::RubyLLM::InvalidToolChoiceError,
+        ::RubyLLM::UnsupportedAttachmentError,
+      ].freeze
+      KNOWN_ERROR = ->(exception:) { KNOWN_ERROR_CLASSES.any? { |k| exception.is_a?(k) } }
+      RETRYABLE_ERROR = lambda { |exception:|
+        [::RubyLLM::OverloadedError, ::RubyLLM::ServiceUnavailableError, ::RubyLLM::ServerError].any? { |k| exception.is_a?(k) }
+      }
+
+      # Base headlines for a consistent result.error / result.success surface: failures read
+      # "<error_headline>: <reason>" (configurable via Axn::RubyLLM.configure); successes read
+      # "LLM request completed", with any detail attached parenthetically via join: (e.g. the
+      # stubbed-values note on the disabled path below).
+      # Reason entries are ordered most-specific-last (axn checks most-recently-declared first), so a
+      # narrower match (retryable, context length, JSON parse) wins over the generic KNOWN_ERROR catch-all.
+      error { Axn::RubyLLM.config.error_headline }
+      error(if: KNOWN_ERROR, &:message)
+      error(if: RETRYABLE_ERROR) { |e| "Provider temporarily unavailable, try again later: #{e.message}" }
+      error(if: ::RubyLLM::ContextLengthExceededError) { |e| "Prompt exceeds the model's context window: #{e.message}" }
+      error "Response was not valid JSON", if: JSON::ParserError
+      success "LLM request completed", join: ->(base, reason) { "#{base} (#{reason})" }
 
       before do
         if disabled?
@@ -38,7 +70,8 @@ module Axn
             response_model: nil,
             stubbed: true,
           )
-          done!("disabled - returning stubbed values", **exposures)
+          # Reason attaches to the "LLM request completed" base via the parenthetical join: above.
+          done!("using stubbed values - actual LLM request disabled", **exposures)
         end
       end
 
@@ -46,20 +79,20 @@ module Axn
         expose(
           response: parsed_response,
           raw_message: llm_response,
-          input_tokens: llm_response.input_tokens,
-          output_tokens: llm_response.output_tokens,
-          cache_read_tokens: llm_response.cache_read_tokens,
-          cache_write_tokens: llm_response.cache_write_tokens,
+          input_tokens: sum_across(:input_tokens),
+          output_tokens: sum_across(:output_tokens),
+          cache_read_tokens: sum_across(:cache_read_tokens),
+          cache_write_tokens: sum_across(:cache_write_tokens),
           prompt_tokens: total_input_tokens,
           cost_breakdown:,
           cost: cost_breakdown&.total,
           stubbed: false,
         )
         record_otel_attributes!(
-          input_tokens: llm_response.input_tokens,
-          output_tokens: llm_response.output_tokens,
+          input_tokens: sum_across(:input_tokens),
+          output_tokens: sum_across(:output_tokens),
           cost: cost_breakdown&.total,
-          response_model: llm_response.model_id,
+          response_model: response_message&.model_id,
           stubbed: false,
         )
       rescue ::RubyLLM::RateLimitError => e
@@ -68,7 +101,7 @@ module Axn
 
       private
 
-      def disabled? = !Axn::RubyLLM.configuration.enabled?
+      def disabled? = !Axn::RubyLLM.enabled?
 
       def stubbed_exposures
         content = schema || json ? { "stubbed" => true } : "stubbed response value"
@@ -87,6 +120,8 @@ module Axn
       end
 
       def parsed_response
+        return halted_response if halted?
+
         if schema
           # with_schema makes RubyLLM parse the response into a Hash on success
           return llm_response.content if llm_response.content.is_a?(Hash)
@@ -96,52 +131,128 @@ module Axn
         json ? JSON.parse(llm_response.content) : llm_response.content
       end
 
+      # A halted tool (halt_after:) short-circuits the model's final turn, so with_schema/json never
+      # parsed a model response — the "response" is the tool's own payload (Halt#content). For a
+      # :structured tool that's JSON text, so parse it to honor the Hash contract a schema:/json:
+      # caller expects; fall back to the raw string for a :message tool or an unparseable payload.
+      def halted_response
+        content = llm_response.content
+        return content unless (schema || json) && content.is_a?(String)
+
+        JSON.parse(content)
+      rescue JSON::ParserError
+        content
+      end
+
+      # A tool call makes multiple model round-trips inside one `ask`; every assistant turn is
+      # accumulated on the chat and reports its OWN usage, so sum across them for the true per-call
+      # totals rather than just the final turn's. Non-response messages (the user prompt, tool
+      # results) carry no tokens — they contribute 0 to the token sums, and RubyLLM::Cost.aggregate
+      # ignores them (no `tokens?`) — so summing over every message is correct, and a plain (no-tool)
+      # ask (one assistant turn) is a no-op.
+      def usage_messages
+        chat.messages
+      end
+
+      # nil only when NO turn reported the field (preserving the "nil if the provider didn't return it"
+      # contract); otherwise the summed count, treating a missing turn as 0.
+      def sum_across(field)
+        values = usage_messages.map(&field)
+        values.all?(&:nil?) ? nil : values.sum(&:to_i)
+      end
+
       def total_input_tokens
-        vals = [llm_response.input_tokens, llm_response.cache_read_tokens, llm_response.cache_write_tokens]
+        vals = usage_messages.flat_map { |m| [m.input_tokens, m.cache_read_tokens, m.cache_write_tokens] }
         vals.all?(&:nil?) ? nil : vals.sum(&:to_i)
       end
 
-      def cost_breakdown
+      memo def cost_breakdown
         return nil unless model_info
 
-        llm_response.cost(model: model_info)
+        # chat.messages always includes the user prompt (chat.ask appends it before completing) and,
+        # in a tool loop, the tool-result messages -- none of which carry token usage. Keep only the
+        # token-bearing (billable) costs BEFORE the one?-vs-aggregate decision: a normal single-turn
+        # call then preserves the response's OWN Cost (with its tokens/model) via costs.one?, instead
+        # of being forced through aggregate -- which returns a Cost with nil tokens/model -- by the
+        # ever-present user message. `select(&:tokens?)` mirrors Cost.aggregate's own billable filter,
+        # so the multi-turn total is unchanged.
+        costs = usage_messages.map { |message| message.cost(model: model_info) }.select(&:tokens?)
+        return nil if costs.empty?
+
+        # One billable turn → its own Cost (identical to the pre-tool-loop non-tool call). Multiple →
+        # RubyLLM::Cost.aggregate sums the per-tier costs into a single breakdown.
+        costs.one? ? costs.first : ::RubyLLM::Cost.aggregate(costs)
       end
 
       memo def model_info
-        ::RubyLLM.models.find(llm_response.model_id)
+        return nil unless response_message&.model_id
+
+        ::RubyLLM.models.find(response_message.model_id)
       rescue ::RubyLLM::ModelNotFoundError
         nil
       end
 
       memo def llm_response = chat.ask(prompt)
 
+      # When a wrapped tool halts the loop (halt_after:), chat.ask returns a ::RubyLLM::Tool::Halt
+      # carrying the tool payload as #content, not a Message — and a Halt has no #model_id. Read the
+      # model (for cost lookup + OTel) from the last assistant turn accumulated on the chat in that
+      # case; for a normal response, llm_response IS that final message. Token/cost SUMS already read
+      # chat.messages, so only the model-id reads needed this indirection.
+      def response_message
+        return llm_response unless halted?
+
+        chat.messages.reverse.find { |message| message.role == :assistant }
+      end
+
+      def halted? = llm_response.is_a?(::RubyLLM::Tool::Halt)
+
       memo def chat
         ::RubyLLM.chat(model: resolved_model).tap do |c|
           c.with_instructions(system_prompt) if system_prompt
           c.with_schema(schema) if schema
           c.with_params(response_format: { type: "json_object" }) if json && !schema
           c.with_params(temperature:) if temperature
+          c.with_tools(*resolved_tools) if resolved_tools.any?
         end
       end
 
       def resolved_model
-        model || Axn::RubyLLM.configuration.default_model
+        model || Axn::RubyLLM.config.default_model
+      end
+
+      # `tools:` accepts a mix of bare Axn classes (wrapped here, so callers can pass their own Axns
+      # straight in) and already-wrapped `::RubyLLM::Tool`s -- a class or an instance, the latter being
+      # how you pass a tool that closed over explicit context via `Axn::RubyLLM.wrap(axn, ambient_context:)`.
+      # RubyLLM's `with_tools` accepts either a class or an instance, so wrapped classes register as-is.
+      def resolved_tools
+        Array(tools).map { |tool| _as_ruby_llm_tool(tool) }
+      end
+
+      def _as_ruby_llm_tool(tool)
+        return tool if tool.is_a?(::RubyLLM::Tool)
+        return tool if tool.is_a?(::Class) && tool < ::RubyLLM::Tool
+
+        Axn::RubyLLM.wrap(tool)
       end
 
       def record_otel_attributes!(input_tokens:, output_tokens:, cost:, response_model:, stubbed:)
-        return unless defined?(::OpenTelemetry::Trace)
-
-        span = ::OpenTelemetry::Trace.current_span
-        return unless span&.context&.valid?
-
-        span.set_attribute("gen_ai.request.model", resolved_model) if resolved_model
-        span.set_attribute("gen_ai.response.model", response_model) if response_model
-        span.set_attribute("gen_ai.usage.input_tokens", input_tokens) if input_tokens
-        span.set_attribute("gen_ai.usage.output_tokens", output_tokens) if output_tokens
-        span.set_attribute("gen_ai.usage.cost", cost) if cost
-        span.set_attribute("axn.ruby_llm.stubbed", stubbed) unless stubbed.nil?
-      rescue StandardError
-        # never let telemetry break the action
+        # Telemetry is a best-effort side effect: it must never break the LLM call. Route it through
+        # axn core's guard (PRO-2950) rather than a bare rescue — it swallows + warn-logs on failure
+        # (and fails loud in dev when best_effort_raises_in_dev is set) instead of silently vanishing.
+        Axn::Extensions.best_effort("recording OpenTelemetry attributes on the axn.call span") do
+          next unless defined?(::OpenTelemetry::Trace)
+
+          span = ::OpenTelemetry::Trace.current_span
+          next unless span&.context&.valid?
+
+          span.set_attribute("gen_ai.request.model", resolved_model) if resolved_model
+          span.set_attribute("gen_ai.response.model", response_model) if response_model
+          span.set_attribute("gen_ai.usage.input_tokens", input_tokens) if input_tokens
+          span.set_attribute("gen_ai.usage.output_tokens", output_tokens) if output_tokens
+          span.set_attribute("gen_ai.usage.cost", cost) if cost
+          span.set_attribute("axn.ruby_llm.stubbed", stubbed) unless stubbed.nil?
+        end
       end
     end
   end

data/lib/axn/ruby_llm/rspec.rb

@@ -6,19 +6,28 @@ module Axn
   module RubyLLM
     module RSpec
       module Helpers
-        # Stubs RubyLLM so that Ask returns a canned response.
+        UNSET = Object.new
+        private_constant :UNSET
+
+        # Stubs RubyLLM so that Ask returns a canned response. The response can be given
+        # positionally (the common case) or as `response:` — both are equivalent.
         #
         # Usage in a spec:
-        #   stub_axn_ruby_llm(response: "Here is a summary.")
-        #   stub_axn_ruby_llm(response: { "key" => "value" })  # auto-JSON-serialized for json: true calls
-        #   stub_axn_ruby_llm(response: { "k" => "v" }, schema: MySchema) # Hash passed through unparsed
-        #   stub_axn_ruby_llm(response: "...", input_tokens: 100, output_tokens: 50, cost: 0.0023)
-        #   stub_axn_ruby_llm(response: "...", cache_read_tokens: 500, cache_write_tokens: 200)
+        #   stub_axn_ruby_llm("Here is a summary.")
+        #   stub_axn_ruby_llm({ "key" => "value" })          # auto-JSON-serialized for json: true calls
+        #   stub_axn_ruby_llm({ "k" => "v" }, schema: MySchema) # Hash passed through unparsed
+        #   stub_axn_ruby_llm("...", input_tokens: 100, output_tokens: 50, cost: 0.0023)
+        #   stub_axn_ruby_llm("...", cache_read_tokens: 500, cache_write_tokens: 200)
+        #   stub_axn_ruby_llm(response: "...")               # keyword form still works
         #
         # Returns the chat instance double for further assertions if needed.
-        def stub_axn_ruby_llm(response:, model: nil, schema: nil, input_tokens: nil, output_tokens: nil,
-                              cache_read_tokens: nil, cache_write_tokens: nil, cost: nil)
-          resolved_model_id = model || Axn::RubyLLM.configuration.default_model
+        def stub_axn_ruby_llm(positional_response = UNSET, response: UNSET, model: nil, schema: nil,
+                              input_tokens: nil, output_tokens: nil, cache_read_tokens: nil,
+                              cache_write_tokens: nil, cost: nil)
+          response = positional_response unless positional_response.equal?(UNSET)
+          raise ArgumentError, "stub_axn_ruby_llm requires a response (positionally or as `response:`)" if response.equal?(UNSET)
+
+          resolved_model_id = model || Axn::RubyLLM.config.default_model
           llm_message = _stub_axn_ruby_llm_message(response, resolved_model_id, input_tokens, output_tokens,
                                                    cache_read_tokens:, cache_write_tokens:, schema:)
           chat_instance = _stub_axn_ruby_llm_chat(model, llm_message, schema:)
@@ -49,8 +58,9 @@ module Axn
           else
             allow(::RubyLLM).to receive(:chat).and_return(chat_instance)
           end
-          allow(chat_instance).to receive(:with_instructions).and_return(chat_instance)
-          allow(chat_instance).to receive(:with_params).and_return(chat_instance)
+          %i[with_instructions with_params with_tools].each do |method|
+            allow(chat_instance).to receive(method).and_return(chat_instance)
+          end
           # Always stub with_schema so specs don't blow up if production code passes schema:
           # even when the helper is called without schema:. Use a tight matcher when schema
           # is known so the stub still validates the correct class is passed.
@@ -60,6 +70,8 @@ module Axn
             allow(chat_instance).to receive(:with_schema).and_return(chat_instance)
           end
           allow(chat_instance).to receive(:ask).and_return(llm_message)
+          # Ask sums usage across the chat's assistant turns; a stubbed call is single-turn.
+          allow(chat_instance).to receive(:messages).and_return([llm_message])
           chat_instance
         end
 
@@ -69,7 +81,9 @@ module Axn
           # Default to zero cost so specs exercise the "model found, cost computed" path.
           # Pass cost: explicitly to assert a specific value.
           cost_total = cost || 0.0
-          cost_struct = instance_double(::RubyLLM::Cost, total: cost_total)
+          # tokens?: true — the stubbed message is a billable assistant turn, and Ask's cost_breakdown
+          # keeps only token-bearing (tokens?) costs before its one?-vs-aggregate decision.
+          cost_struct = instance_double(::RubyLLM::Cost, total: cost_total, tokens?: true)
           allow(llm_message).to receive(:cost).with(model: model_info).and_return(cost_struct)
         end
       end

data/lib/axn/ruby_llm/tool_adapter.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+module Axn
+  module RubyLLM
+    # Namespaced per-class config (axn's `Axn::Configurable`, PRO-2880): any Axn — with no
+    # adapter-specific mixin required — can declare `configure(:ruby_llm) { |c| c.halt_after = true }`
+    # to set these per-class, alongside e.g. `configure(:mcp) { ... }` for a different adapter on the
+    # same class, without the two colliding. `wrap` resolves them via `resolve_override_for`, which
+    # falls back to this module's own global `config` (`Axn::RubyLLM.configure { |c| ... }`) and then
+    # to each setting's default — the same class-override-then-global-then-default chain a flat
+    # `overridable: true` accessor would give a single-adapter consumer.
+    config_namespace :ruby_llm
+    setting :halt_after, default: false, overridable: true
+    setting :provider_params, default: {}, overridable: true
+    setting :present_as, default: :structured, one_of: %i[structured message], overridable: true
+    setting :reject_opaque_exposed_values, default: false, one_of: [true, false], overridable: true
+
+    # Wraps any Axn as a ::RubyLLM::Tool: schema, name, and description are read straight off the
+    # Axn's own declared contract (`input_schema` / `resolved_axn_name` / `description`, from axn's
+    # core reflection), so a tool needs no adapter-specific mixin to be wrapped.
+    module ToolAdapter
+      NOT_SET = Object.new.freeze
+
+      # Client-facing tool-error text when the transport step raises while turning a *successful*
+      # result into a response (see the guard in build_tool_class's #execute). Deliberately generic:
+      # the actionable detail (class, path) is a gem/tool bug, so it rides on the reported exception
+      # (on_exception / logs), not the tool's response — mirroring how axn keeps a failure's detail
+      # off the user-facing message, and axn-mcp's Serializer::ADAPTER_FAILURE_MESSAGE.
+      ADAPTER_FAILURE_MESSAGE = "The tool could not produce a valid response"
+
+      class << self
+        def wrap(axn_class, halt_after: nil, provider_params: nil, present_as: nil, render_as: NOT_SET, ambient_context: NOT_SET)
+          validate_present_as_kwargs!(present_as, render_as)
+
+          tool_class = build_tool_class(
+            axn_class,
+            halt_after: halt_after.nil? ? Axn::RubyLLM.resolve_override_for(axn_class, :halt_after) : halt_after,
+            provider_params: provider_params.nil? ? Axn::RubyLLM.resolve_override_for(axn_class, :provider_params) : provider_params,
+            present_as: present_as.nil? ? Axn::RubyLLM.resolve_override_for(axn_class, :present_as) : present_as,
+            reject_opaque: Axn::RubyLLM.resolve_override_for(axn_class, :reject_opaque_exposed_values),
+            ambient_context:,
+          )
+
+          ambient_context.equal?(NOT_SET) ? tool_class : tool_class.new
+        end
+
+        private
+
+        # `render_as:` (values :structured/:text) was renamed to `present_as:` (:structured/:message)
+        # to unify the knob with axn-mcp's `present_as` (see DEPRECATIONS.md). Pre-1.0, so a leftover
+        # `render_as:` is a hard error with a pointer, not a silent shim (an ignored kwarg would quietly
+        # revert a caller to :structured). `one_of:` on the setting only guards the config-set path, so
+        # validate the `present_as` kwarg here too, pointing render_as's old `:text` value at its rename.
+        def validate_present_as_kwargs!(present_as, render_as)
+          unless render_as.equal?(NOT_SET)
+            raise ArgumentError,
+                  "`render_as:` was renamed to `present_as:` and its `:text` value to `:message` " \
+                  "(e.g. `Axn::RubyLLM.wrap(..., present_as: :message)`)."
+          end
+
+          return if present_as.nil? || %i[structured message].include?(present_as)
+
+          hint = present_as == :text ? " (the `:text` value was renamed to `:message`)" : ""
+          raise ArgumentError, "present_as must be one of :structured, :message; got #{present_as.inspect}#{hint}"
+        end
+
+        def build_tool_class(axn_class, halt_after:, provider_params:, present_as:, reject_opaque:, ambient_context:)
+          # Core's canonical, provider-safe tool_name (PRO-2921): strips configured leading prefixes,
+          # snake_cases with single underscores, restricts to [a-z0-9_], and is never blank (anonymous
+          # -> "tool"). Pass the `:ruby_llm` adapter key so a per-adapter `tool ruby_llm: { name: }`
+          # override wins -- this is the SAME name `Axn::Tools.for(:ruby_llm)` keys membership,
+          # version-collapsing, and sort order on (registry.rb), so `.tools` publishes the exact name
+          # the registry selected; the zero-arg form would ignore the override and advertise a
+          # different name, so provider tool calls / forced choices on the declared name wouldn't
+          # match. Absent an override it's identical to the zero-arg name (Axn::MCP.wrap passes `:mcp`
+          # the same way -- the author-once point).
+          tool_name = axn_class.tool_name(:ruby_llm)
+          input_schema = normalize_nullable_types(axn_class.input_schema)
+
+          Class.new(::RubyLLM::Tool) do
+            description(axn_class.description) if axn_class.description
+            params(input_schema)
+            with_params(**provider_params) if provider_params.any?
+
+            define_method(:name) { tool_name }
+
+            define_method(:execute) do |**args|
+              # Run the Axn through axn core's tool Invoker (PRO-2943): input types are coerced from the
+              # wire, undeclared args are rejected, and a model-supplied `ambient_context` is stripped
+              # (the injection guard) while the wrap's own trusted context is injected in its place.
+              # Contract violations settle user-facing, so `input_invalid?` lets us hand the model a
+              # clean, correctable "Invalid tool arguments" error instead of leaking a dev-facing bug
+              # (which also keeps a bad tool call from paging on_exception).
+              invoker = ::Axn::Tools::Invoker.new(user_facing_input_errors: true, reject_undeclared_inputs: true)
+              result = if ambient_context.equal?(NOT_SET)
+                         invoker.call(axn_class, args)
+                       else
+                         invoker.call(axn_class, args, ambient_context:)
+                       end
+
+              unless result.ok?
+                next({ error: "Invalid tool arguments: #{result.error}" }) if ::Axn::Tools::Invoker.input_invalid?(result)
+
+                next({ error: result.error })
+              end
+
+              # Uphold axn's non-bang "never raises" contract at the adapter boundary. The wrapped
+              # Axn's own `.call` (run via the Invoker above) never raises -- core catches action
+              # exceptions into a failed Result and pages on_exception itself -- but the TRANSPORT
+              # step that runs AFTER it (exposed-value serialization + JSON encoding) can raise
+              # outside core's executor: a value core can't render (two Hash keys colliding on one
+              # JSON property, a non-finite Float, non-UTF-8 bytes, an opaque value under
+              # reject_opaque), a structure past the JSON encoder's max_nesting, or a gem bug.
+              # RubyLLM has no rescue around a tool's #execute, so any of these would escape and
+              # break the whole chat. Scope the guard to JUST that mapping step (NOT the Invoker call,
+              # which already handles + reports its own exceptions -- double-guarding would
+              # double-report on_exception): report through axn's global on_exception for
+              # observability, then -- honoring core's best_effort_raises_in_dev so a real bug
+              # surfaces loudly rather than being masked -- re-raise in dev, otherwise return a tool
+              # error so #execute ALWAYS yields a value. Shaped to drop into the planned shared
+              # Axn::Tools::Serialization.guard (PRO-2996 §2b) with no behavior change.
+              begin
+                # RubyLLM::Chat#handle_tool_calls only treats a Content/Content::Raw return as-is; any
+                # other object (including a plain Hash) gets `#to_s`'d before being sent to the
+                # provider -- which for a Hash produces Ruby's inspect syntax (`{"k"=>"v"}`), not
+                # JSON. Serialize structured payloads ourselves so the wire form is always valid JSON.
+                payload = if present_as == :message
+                            result.message
+                          else
+                            Axn::Extensions::Serialization.render(result, reject_opaque:).to_json
+                          end
+                halt_after ? halt(payload) : payload
+              rescue StandardError => e
+                # Report through on_exception for observability -- but the reporter is app-configured
+                # and CAN raise (a buggy hook, or one assuming `action` is a settled instance). Core
+                # normally invokes on_exception INSIDE its own best_effort; we call it directly, so a
+                # raising reporter would escape and defeat this guard's never-raises intent (aborting
+                # chat.ask in production). Wrap it in best_effort ourselves -- it swallows + warn-logs
+                # (and reraises in dev per best_effort_raises_in_dev), same as core.
+                Axn::Extensions.best_effort("reporting a tool serialization failure via on_exception") do
+                  Axn.config.on_exception(e, action: axn_class, context: { source: "Axn::RubyLLM" })
+                end
+                raise if Axn::Extensions.raises_in_dev?
+
+                { error: ADAPTER_FAILURE_MESSAGE }
+              end
+            end
+          end
+        end
+
+        # axn reflects a nullable/optional field as a JSON Schema array-valued `type`
+        # (e.g. `["integer", "null"]`). That's valid JSON Schema and OpenAI/Anthropic consume it
+        # fine, but RubyLLM's Gemini converter only recognizes anyOf-form nullability: it does
+        # `param_type_for_gemini(type)` with `type.to_s.downcase`, so an array `type` matches no
+        # case and falls through to STRING -- silently dropping both the declared type and the
+        # nullability. Rewrite every array-valued `type` into the equivalent `anyOf: [{type: ...}]`,
+        # which Gemini's `normalize_any_of_schema` collapses back to the real type + nullable, and
+        # which the other providers accept unchanged. Purely a wire-shape change: the admitted value
+        # set is identical, and the adapter's own validator (json_types_for) already reads anyOf.
+        #
+        # Builds new Hashes/Arrays throughout rather than mutating -- axn may hand back a memoized
+        # input_schema, and mutating it would corrupt every other reader.
+        def normalize_nullable_types(node)
+          case node
+          when Hash
+            rebuilt = node.to_h { |key, value| [key, normalize_nullable_types(value)] }
+            if rebuilt[:type].is_a?(Array)
+              types = rebuilt.delete(:type)
+              rebuilt[:anyOf] = types.map { |type| { type: } }
+            end
+            rebuilt
+          when Array
+            node.map { |value| normalize_nullable_types(value) }
+          else
+            node
+          end
+        end
+      end
+    end
+
+    class << self
+      def wrap(...)
+        ToolAdapter.wrap(...)
+      end
+
+      # Every Axn registered as a :ruby_llm tool -- via `tool`/`tool :ruby_llm`, residency under one of
+      # the configured `tool_roots`, or a `configure(:ruby_llm)` bag (see Axn::Tools::Registry#member?)
+      # -- each already wrapped as a ::RubyLLM::Tool, so a consumer builds its whole chat tool list in
+      # one call: `chat.with_tools(*Axn::RubyLLM.tools)`. Mirrors the shared GemName.tools contract
+      # with Axn::MCP.tools; the same Axn class resolves to the same tool_name across both surfaces.
+      def tools
+        Axn::Tools.for(:ruby_llm).map { |axn| wrap(axn) }
+      end
+    end
+  end
+end

data/lib/axn/ruby_llm/version.rb

@@ -2,6 +2,6 @@
 
 module Axn
   module RubyLLM
-    VERSION = "0.1.2"
+    VERSION = "0.2.0"
   end
 end

data/lib/axn/ruby_llm.rb

@@ -1,30 +1,82 @@
 # frozen_string_literal: true
 
+require "delegate"
 require "ruby_llm"
 require "axn"
 
 require_relative "ruby_llm/version"
-require_relative "ruby_llm/configuration"
 require_relative "ruby_llm/ask"
 
 module Axn
   module RubyLLM
     include Axn::Mountable
+    extend Axn::Configurable
+    extend Axn::Tools::AdapterRoots
+
+    setting :default_model, default: "gpt-4o-mini"
+    setting :enabled, default: true
+    setting :error_headline, default: "LLM request failed"
+
+    # `Axn::Tools::AdapterRoots` (extended above) declares `tool_roots` with `default: []`; re-declare
+    # it (core's `setting` is last-wins) to ship the shared agent-tools dir as the default, so any Axn
+    # living under `app/agent_tools` is exposed as a `:ruby_llm` tool out of the box. It's the same dir
+    # axn-mcp defaults to, so one Axn there is authored once and surfaces on both. The re-declaration
+    # keeps AdapterRoots' broad-path validation (no widening a root to `app/`/`actions`/`.`/`..`).
+    setting :tool_roots, default: ["agent_tools"], validate: ->(value) { Axn::Tools::AdapterRoots.validate!(value) }
+
+    # Register this module as the `:ruby_llm` adapter AND its config source (PRO-2948): the registry
+    # reads `Axn::RubyLLM.config.tool_roots` off the source to grant directory-based membership.
+    Axn::Tools.register_adapter(:ruby_llm, self)
 
     mount_axn :ask, Ask
 
+    # Backward-compatible view of `config` returned by the deprecated `configuration` alias. The
+    # pre-DSL `Configuration#enabled?` invoked a callable gate (`enabled = -> { ... }`); the
+    # DSL-generated `config.enabled?` returns an assigned Proc as-is (always truthy). Delegate
+    # everything to `config`, but restore the callable-resolving `enabled?` (via the module-level
+    # `enabled?`) so a compatibility caller's production gate still resolves correctly during the
+    # deprecation window instead of silently reading as enabled. Removed with the alias in 0.3.0.
+    class DeprecatedConfigProxy < SimpleDelegator
+      def enabled? = Axn::RubyLLM.enabled?
+    end
+
     class << self
-      def configuration
-        @configuration ||= Configuration.new
+      # `enabled` accepts a Boolean OR a callable — the documented production-gating idiom is
+      # `c.enabled = -> { Rails.env.production? }`. axn's Configurable used to invoke an assigned
+      # callable on read via `callable: true`; that kwarg was removed upstream (PRO-3017) and an
+      # assigned Proc is now returned as-is, so resolve it here. Without this the DSL-generated
+      # `config.enabled?` is `!!some_proc` — always true — and production gating dies silently.
+      # This (`Axn::RubyLLM.enabled?`), NOT `config.enabled?`, is the supported reader.
+      def enabled?
+        value = config.enabled
+        value.respond_to?(:call) ? !!value.call : !!value
       end
 
-      def configure
-        yield configuration
+      # DEPRECATED backward-compatible aliases for the pre-DSL API. The
+      # Axn::Configurable DSL standardizes on `.config` / `reset_config!`.
+      # These keep older callers working but emit a deprecation warning and
+      # are scheduled for removal in the next minor version (see DEPRECATIONS.md).
+      def configuration
+        _warn_deprecated_alias("Axn::RubyLLM.configuration", "Axn::RubyLLM.config")
+        DeprecatedConfigProxy.new(config)
       end
 
       def reset_configuration!
-        @configuration = nil
+        _warn_deprecated_alias("Axn::RubyLLM.reset_configuration!", "Axn::RubyLLM.reset_config!")
+        reset_config!
+      end
+
+      private
+
+      def _warn_deprecated_alias(old, new)
+        warn(
+          "[axn-ruby_llm] DEPRECATION: #{old} is deprecated and will be removed in the next minor version; use #{new} instead.",
+          category: :deprecated,
+          uplevel: 2,
+        )
       end
     end
   end
 end
+
+require_relative "ruby_llm/tool_adapter"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: axn-ruby_llm
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Kali Donovan
@@ -15,7 +15,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.0.pre.alpha.4.3
+        version: 0.1.0.pre.alpha.5
     - - "<"
       - !ruby/object:Gem::Version
         version: 0.2.0
@@ -25,7 +25,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.0.pre.alpha.4.3
+        version: 0.1.0.pre.alpha.5
     - - "<"
       - !ruby/object:Gem::Version
         version: 0.2.0
@@ -60,12 +60,11 @@ files:
 - CHANGELOG.md
 - LICENSE
 - README.md
-- Rakefile
 - lib/axn-ruby_llm.rb
 - lib/axn/ruby_llm.rb
 - lib/axn/ruby_llm/ask.rb
-- lib/axn/ruby_llm/configuration.rb
 - lib/axn/ruby_llm/rspec.rb
+- lib/axn/ruby_llm/tool_adapter.rb
 - lib/axn/ruby_llm/version.rb
 homepage: https://github.com/teamshares/axn-ruby_llm
 licenses:

data/Rakefile

@@ -1,13 +0,0 @@
-# frozen_string_literal: true
-
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
-require "rubocop/rake_task"
-
-RSpec::Core::RakeTask.new(:spec)
-
-RuboCop::RakeTask.new
-
-task default: %i[spec rubocop]
-
-Rake::Task["build"].enhance([:default])

data/lib/axn/ruby_llm/configuration.rb

@@ -1,20 +0,0 @@
-# frozen_string_literal: true
-
-module Axn
-  module RubyLLM
-    class Configuration
-      DEFAULT_MODEL = "gpt-4o-mini"
-
-      attr_accessor :default_model, :enabled
-
-      def initialize
-        @default_model = DEFAULT_MODEL
-        @enabled = true
-      end
-
-      def enabled?
-        enabled.respond_to?(:call) ? !!enabled.call : !!enabled
-      end
-    end
-  end
-end