axn-ruby_llm 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c33a22550fbc081c47ad09e370ce05aa400640cfe70f2e06488d93b1507a42a6
-  data.tar.gz: 1d65bcd8eeee475aee68c7a92e380601f8c3e333629fe6664609c0e1174e2f64
+  metadata.gz: 567165990e6185d68aab836344f8aaf5f1b2891c0c6fd19442aab5908c1fa335
+  data.tar.gz: 326731c8da66d1ac1ca92bcc5bf8b4c43132aaa42580f10ba97d7d98218911ee
 SHA512:
-  metadata.gz: c9b764c927824c06c5f14d8b186ede7c63182cda2259991e444e6226f45a0277b51433f8ea5246f0438623a59e9e4827d7ee393391db53f028e00178f154de1d
-  data.tar.gz: 5cc0b5fcda8f30cf1961cc44839c08d5447787262247f6ebd460d53c4ff9478143a9b4e1b7414082917d8052b4757770113e2e3451c206283e6ad49ff5cfb754
+  metadata.gz: 6b0ba66b042f93f747523524bbf2eb33c00f8a2ad2d21f81525c2429c211896512aa96cfd2e749aec9682de68497b7d6a27e609e5bb0b2a4e5b0aeec6385a78e
+  data.tar.gz: d2d928acbe79f0c3c25757d0db23135cfa5abaad6e3c5b4d5602f2074a70ce8a6331a6583c296e96c7191b151f783448b646b6091d0dc6288ebba88a7ef158e6

data/CHANGELOG.md

@@ -1,5 +1,78 @@
 # Changelog
 
+## [0.2.1] - 2026-09-03
+
+### Added
+
+- **[FEAT] Every tool call is now stamped `invoked_via: :ruby_llm`** (PRO-3332), via
+  `Axn::Tools::Invoker.new(adapter: :ruby_llm)`. No adapter-side work required — the stamp applies to
+  the wrapped Axn and any nested sub-axn or enqueued Sidekiq job for the life of the call tree, so a
+  Datadog dashboard (or any `Axn.config.on_exception`/tracing consumer reading the resolved
+  `invoked_via` dimension) can separate tool-driven traffic from an ordinary direct `.call`.
+
+### Changed
+
+- **`record_otel_attributes!` now uses `Axn::Extensions::Tracing.annotate_span`** instead of the
+  unreliable ambient `OpenTelemetry::Trace.current_span` lookup, which could disagree with the span
+  axn's own tracer actually opened (PRO-3278) and silently drop every `gen_ai.*` attribute. Requires
+  axn `>= 0.1.0-alpha.6`.
+
+### Fixed
+
+- **[BUGFIX] `reject_opaque_exposed_values` is now resolved per tool call instead of once at wrap
+  time.** The setting is `overridable:`, so a per-tool `configure(:ruby_llm) { |c| ... }` /
+  `tool ruby_llm: { ... }` bag or a gem-wide `Axn::RubyLLM.configure` assignment is meant to be what
+  a tool honors — but `wrap` resolved the value eagerly and the built tool class closed over that
+  Boolean forever. Since the normal way to build tools is once at boot (`chat.with_tools(*Axn::RubyLLM.tools)`),
+  any change to the setting *after* that point silently did nothing to a live tool: the wrapped class
+  kept whatever the flag happened to resolve to at wrap time, with no warning and no way to tell from
+  the outside. Resolution now happens inside `#execute`, at the moment the result is rendered, so a
+  tool always reflects the currently-configured value — the same per-call semantics `axn-mcp` already
+  had. **Old vs new:** a tool wrapped while the flag was `false` and later switched to `true` used to
+  keep shipping opaque renderings; it now fails those calls with the generic tool error, as configured.
+  Only the *timing* changed — the resolution order (per-class override, then gem-wide config, then the
+  `false` default) is unchanged, so a setup that configures before wrapping (the overwhelmingly common
+  case, and every documented example) behaves exactly as before.
+
+- **A map's `additionalProperties` (and a Hash's `minProperties`/`maxProperties`) are no longer silently
+  lost at Gemini.** RubyLLM's Gemini converter rebuilds each property from a fixed whitelist that omits all
+  three, so `expects :scores, type: Hash, of: { keys: String, values: Integer }` reached the model as an empty
+  `{type: OBJECT}` — with no error raised, leaving the model to guess the value type and the call to be rejected
+  at runtime instead (PRO-3172). The adapter now restates these constraints as prose in the same node's
+  `description`, which Gemini does forward, appending after any `description:` you supplied; a structured value
+  type carries its compact JSON Schema too. The enforceable keys are still advertised unchanged, so OpenAI and
+  Anthropic are unaffected apart from the redundant sentence.
+
+- **The transport-failure guard now logs an operator hint when `reject_opaque_exposed_values` may be the
+  cause.** The tool-facing error stays generic (`"The tool could not produce a valid response"`), but the
+  logged line now names the offending tool and both places the setting could be set
+  (`configure(:ruby_llm)` / `Axn::RubyLLM.config.reject_opaque_exposed_values`) whenever the resolved
+  value is `true` — matching `axn-openapi`'s dispatcher hint and `axn-mcp`'s guard. Previously an operator
+  had to guess which knob caused a rejection since the setting is per-tool overridable.
+
+### Internal
+
+- **[INTERNAL] Adopted axn's `Axn::Tools::AdapterSerialization` mixin (PRO-2996)** in place of this
+  gem's hand-rolled copies of the same three things. `Axn::RubyLLM` now `extend`s the mixin alongside
+  `Axn::Tools::AdapterRoots` and uses `declare_reject_opaque_exposed_values! default: false` for the
+  setting, `Axn::RubyLLM.serialize_exposed(result)` for the render (which resolves the per-tool flag
+  itself — see the Fixed entry above), and `Axn::RubyLLM.guard_tool_response(axn_class, on_error:)`
+  for the transport-mapping guard. The default `tool_roots` moved to `tool_roots_default %w[agent_tools]`,
+  which drops this gem's hand-copied `AdapterRoots.validate!` lambda and validates the default eagerly
+  at gem load rather than at the registry's first read. No public API, config name, default, or
+  user-facing string changed. Two second-order effects worth knowing: the mixin's guard runs its
+  dev-mode re-raise *before* reporting (so under `best_effort_raises_in_dev` a mapping failure now
+  raises without first emitting the `reject_opaque_exposed_values` log hint — production behavior is
+  unchanged), and it rescues `SystemStackError`/`ScriptError` in addition to `StandardError`, so a
+  runaway `as_json`/`to_h` on an exposed value now becomes a tool error rather than escaping into the
+  chat.
+
+### Requires
+
+- **axn `>= 0.1.0-alpha.6`** (released), for `Axn::Tools::AdapterSerialization` (PRO-2996) and
+  `Axn::Extensions::Tracing.annotate_span` (PRO-3278). No Gemfile override needed — resolves from
+  RubyGems.
+
 ## [0.2.0] - 2026-08-05
 
 > **Upgrade notes (behavior changes):**

data/README.md

@@ -157,9 +157,9 @@ result.response # => "Created widget Sprocket (id: 42)."
 
 `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.
+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. The `Invoker` also stamps every call (including any nested sub-Axn) with the `invoked_via: :ruby_llm` dimension, so a Datadog dashboard can query tool-driven traffic separately from ordinary direct `.call`s — see [OpenTelemetry](#opentelemetry) below.
 
-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.
+On success, `execute` returns the exposed values (via `Axn::RubyLLM.serialize_exposed`, honoring `reject_opaque_exposed_values` — see below) 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):
 
@@ -288,6 +288,7 @@ The advertised tool schema is axn's reflected `input_schema`. A few things worth
 - **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.
+- **Hash maps and entry counts** — handled. A map (`expects :scores, type: Hash, of: { keys: String, values: Integer }`) reflects to `additionalProperties`, and a Hash's entry-count bounds to `minProperties`/`maxProperties`. Gemini's converter carries none of the three, so a map would otherwise arrive as an empty `{type: OBJECT}` — no error, but the model never learns what the values must be, so its guess is rejected at runtime instead. The adapter restates the constraint in that node's `description` (“An object mapping arbitrary keys to integer values. This object must not be empty.”), which Gemini does forward; a structured value type carries its compact JSON Schema alongside. The real keys are left in place for OpenAI/Anthropic, which enforce them, so the prose is redundant there rather than load-bearing. Your own `description:` is kept and the generated sentences appended after it. No action needed on your part.
 - **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
@@ -326,6 +327,7 @@ If your app uses OpenTelemetry, `axn` already wraps every action in an `axn.call
 | `gen_ai.usage.output_tokens` | Completion token count |
 | `gen_ai.usage.cost` | USD total (non-standard; useful for spend filtering) |
 | `axn.ruby_llm.stubbed` | `true` when production gating returned a stub |
+| `axn.dimension.invoked_via` | `"ruby_llm"` — set by axn core on every tool call (including nested sub-Axns), not by this gem; lets you separate tool-driven traffic from ordinary direct `.call`s in the same span schema |
 
 For LLM-level tracing (individual `RubyLLM.chat` calls, tool calls, embeddings, prompt content), add [`opentelemetry-instrumentation-ruby_llm`](https://github.com/thoughtbot/opentelemetry-instrumentation-ruby_llm) to your own Gemfile and configure it per its README. It is not a dependency of this gem.
 

data/lib/axn/ruby_llm/ask.rb

@@ -237,22 +237,14 @@ module Axn
       end
 
       def record_otel_attributes!(input_tokens:, output_tokens:, cost:, response_model:, stubbed:)
-        # 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
+        Axn::Extensions::Tracing.annotate_span(
+          "gen_ai.request.model" => resolved_model,
+          "gen_ai.response.model" => response_model,
+          "gen_ai.usage.input_tokens" => input_tokens,
+          "gen_ai.usage.output_tokens" => output_tokens,
+          "gen_ai.usage.cost" => cost,
+          "axn.ruby_llm.stubbed" => stubbed,
+        )
       end
     end
   end

data/lib/axn/ruby_llm/tool_adapter.rb

@@ -13,7 +13,13 @@ module Axn
     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
+    # `Axn::Tools::AdapterSerialization` (extended onto Axn::RubyLLM in ruby_llm.rb, which is required
+    # before this file reopens the module) owns this setting's declaration so the three adapters can't
+    # drift on it. `default:` is a required kwarg with no core-picked value on purpose: an LLM-facing
+    # adapter is better off shipping an ugly-but-honest rendering than failing the whole tool call, so
+    # ruby_llm (like axn-mcp) declares `false`, where axn-openapi's published output contract declares
+    # `true`. Must follow `config_namespace` above -- it's an `overridable:` setting.
+    declare_reject_opaque_exposed_values! default: false
 
     # 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
@@ -37,7 +43,6 @@ module Axn
             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:,
           )
 
@@ -64,7 +69,39 @@ module Axn
           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:)
+        # `guard_tool_response`'s `on_error`: the transport-native error response, plus the operator's
+        # only pointer to WHY (the tool-facing text stays generic -- see ADAPTER_FAILURE_MESSAGE).
+        # Mirrors axn-openapi's dispatcher hint / axn-mcp's Invocation guard: the config pointer lives
+        # HERE rather than in core's exception message, since core raises the same error for adapters
+        # with no such setting. Named as BOTH config levels, never just the gem-wide setter -- the
+        # value is resolved per-tool, so a `configure(:ruby_llm)` override beats `config`, and core
+        # exposes no way to ask which level supplied a resolved value. Non-committal ("if this is")
+        # because reject_opaque_exposed_values being on doesn't mean THIS failure is an opaque
+        # rejection -- it could equally be a colliding key, a non-finite Float, or a gem bug.
+        #
+        # The whole hint is built and logged INSIDE a best_effort: `axn_class` is caller code, and
+        # interpolating it (a hostile/buggy #to_s) must not raise out of `on_error` -- `guard_tool_response`
+        # reports and re-raises an on_error failure rather than substituting a response, so a raise
+        # here would cost the tool its error response entirely. Deliberately a SEPARATE best_effort
+        # from the guard's own on_exception report: a broken configured logger must not suppress that
+        # report, and a broken reporter must not suppress this diagnostic line -- each is the guard's
+        # only surviving signal when the OTHER one is what's broken.
+        def serialization_failure_response(axn_class, error)
+          Axn::Extensions.best_effort("logging a tool serialization failure hint") do
+            hint = if Axn::RubyLLM.resolve_override_for(axn_class, :reject_opaque_exposed_values)
+                     " (if this is an opaque-value rejection: reject_opaque_exposed_values resolved true for " \
+                       "#{axn_class} — unset it on the action via `configure(:ruby_llm)`, or gem-wide via " \
+                       "`Axn::RubyLLM.config.reject_opaque_exposed_values = false`, whichever is set)"
+                   else
+                     ""
+                   end
+            Axn.config.logger.error { "[axn-ruby_llm] failed to serialize successful result: #{error.class}: #{error.message}#{hint}" }
+          end
+
+          { error: ADAPTER_FAILURE_MESSAGE }
+        end
+
+        def build_tool_class(axn_class, halt_after:, provider_params:, present_as:, 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: }`
@@ -75,7 +112,11 @@ module Axn
           # 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)
+          input_schema = normalize_nullable_types(annotate_object_constraints(axn_class.input_schema))
+          # Built HERE, not inside `define_method(:execute)`: `self` in the executed block is the
+          # ::RubyLLM::Tool instance, which has no access to this module's private helpers. Closing
+          # over the lambda from build_tool_class's scope binds it to ToolAdapter instead.
+          on_serialization_failure = ->(e) { serialization_failure_response(axn_class, e) }
 
           Class.new(::RubyLLM::Tool) do
             description(axn_class.description) if axn_class.description
@@ -90,8 +131,10 @@ module Axn
               # (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)
+              # (which also keeps a bad tool call from paging on_exception). `adapter: :ruby_llm`
+              # (PRO-3332) stamps the invoked_via dimension around the call, so a Datadog dashboard can
+              # separate tool-driven traffic from ordinary direct `.call`s with no per-call work here.
+              invoker = ::Axn::Tools::Invoker.new(adapter: :ruby_llm, user_facing_input_errors: true, reject_undeclared_inputs: true)
               result = if ambient_context.equal?(NOT_SET)
                          invoker.call(axn_class, args)
                        else
@@ -110,39 +153,33 @@ module Axn
               # 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
+              # reject_opaque_exposed_values), 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. `guard_tool_response` (PRO-2996, from
+              # Axn::Tools::AdapterSerialization) is core's shared version of exactly that guard --
+              # report through the global on_exception inside a best_effort, re-raise when
+              # raises_in_dev? so a real bug surfaces loudly, else hand `on_error` the exception so
+              # this adapter builds its own transport-native error response. It is scoped to JUST the
+              # mapping step (NOT the Invoker call, which already handles + reports its own
+              # exceptions -- double-guarding would double-report on_exception), and the block's
+              # return value is #execute's.
+              Axn::RubyLLM.guard_tool_response(axn_class, on_error: on_serialization_failure) do
                 # 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.
+                #
+                # `serialize_exposed` (not `Serialization.render` directly) resolves
+                # reject_opaque_exposed_values PER CALL off the result's own action class, so a
+                # per-tool `configure(:ruby_llm)` override is honored and a config change reaches
+                # already-wrapped tools. `present_as` stays a wrap-time kwarg: it's adapter-owned, not
+                # part of the shared mixin, and `wrap` accepts it as an explicit override.
                 payload = if present_as == :message
                             result.message
                           else
-                            Axn::Extensions::Serialization.render(result, reject_opaque:).to_json
+                            Axn::RubyLLM.serialize_exposed(result).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
@@ -175,6 +212,152 @@ module Axn
             node
           end
         end
+
+        # PRO-3172. RubyLLM's Gemini converter rebuilds every property from a fixed whitelist
+        # (`convert_property`: description/enum/format/nullable/maximum/minimum/multipleOf, plus
+        # properties/required and, for an array, items/minItems/maxItems). Three keys axn emits for a
+        # Hash fall outside it: `additionalProperties` -- a map's value contract, from
+        # `of: { keys:, values: }` -- and `minProperties`/`maxProperties`, its entry-count bounds.
+        # All three are dropped with no error raised, so a map reaches Gemini as a bare
+        # `{type: OBJECT, properties: {}}`: the model never learns what the values must be, sends
+        # whatever it likes, and the Invoker rejects the call. The constraint degrades from
+        # schema-enforced to runtime-rejected, costing a wasted round trip plus a recovery the model
+        # has to work out for itself.
+        #
+        # Gemini's Schema proto has no equivalent to translate any of them to -- but `description` IS
+        # copied through, so restate them as prose there. Applied unconditionally rather than only for
+        # Gemini: the adapter has no provider to branch on (a wrapped tool class outlives the choice
+        # of chat), and on OpenAI/Anthropic -- which take `params_schema` verbatim and so still get
+        # the enforceable keys themselves -- the extra sentence is merely redundant, never wrong.
+        #
+        # Same non-mutation rule as normalize_nullable_types, for the same reason: axn may hand back
+        # a memoized input_schema, so build new Hashes/Arrays throughout.
+        def annotate_object_constraints(node)
+          case node
+          when Hash
+            rebuilt = node.to_h { |key, value| [key, annotate_object_constraints(value)] }
+            # Read the sentences off the ORIGINAL node, not `rebuilt`: map_sentence may dump the value
+            # subschema as JSON, and the original is the copy that has no generated prose in it yet.
+            # The JSON clause goes LAST: it ends in a brace rather than a period, so anything appended
+            # after it would read as a run-on (and a period placed right after `}` risks being read as
+            # part of the JSON itself).
+            return rebuilt unless object_node?(node)
+
+            sentences = [map_sentence(node), entry_count_sentence(node), value_schema_clause(node)].compact
+            return rebuilt if sentences.empty?
+
+            # merge (rather than assignment into a fresh Hash) so an author-supplied description keeps
+            # its original position in the node; the generated sentences follow the author's text.
+            rebuilt.merge(description: [node[:description], *sentences].compact.join(" "))
+          when Array
+            node.map { |value| annotate_object_constraints(value) }
+          else
+            node
+          end
+        end
+
+        # A map's value contract as prose. A bare type reads as a plain word -- "integer", "string or
+        # integer" -- which says everything the schema does; anything structured is named by its
+        # top-level type here and spelled out exactly by value_schema_clause below.
+        def map_sentence(node)
+          values = map_values(node)
+          return nil unless values
+
+          # `additionalProperties` governs only the keys `properties` does NOT match, so a map that
+          # also declares a `shape:` carries both on one node -- and Gemini keeps `properties`, which
+          # makes "arbitrary keys" actively wrong in that case.
+          lead = if node[:properties].is_a?(Hash) && node[:properties].any?
+                   "Keys other than those listed map to"
+                 else
+                   "An object mapping arbitrary keys to"
+                 end
+
+          phrase = bare_type_phrase(values)
+          phrase ? "#{lead} #{phrase} values." : "#{lead} values."
+        end
+
+        # A structured value type -- an array's `items`, a nested map, a constrained scalar -- would
+        # need hand-written English grammar to render as prose, which degrades fast with nesting
+        # depth, so carry it as compact JSON Schema instead: exact at any depth, and a form models
+        # read natively. Skipped when the type word alone already said everything.
+        def value_schema_clause(node)
+          values = map_values(node)
+          return nil if values.nil? || bare_type?(values)
+
+          "Each value must match this JSON Schema: #{JSON.generate(values)}"
+        end
+
+        # The recursion above walks every Hash in the schema, but not every Hash IS a schema node --
+        # `properties` is a name-to-schema map, so an Axn with a field named `additionalProperties` or
+        # `minProperties` puts a Hash (or an Integer) at exactly the key this pass reads. Without this
+        # gate, such a container was itself annotated, injecting a `description` key into `properties`
+        # and thereby advertising a phantom parameter named "description" -- which the model might then
+        # send and the Invoker would reject as undeclared. Requiring a declared object type also keeps
+        # object prose off a string/array node that carries these keys for any other reason.
+        def object_node?(node)
+          type = node[:type]
+          type == "object" || (type.is_a?(Array) && type.include?("object"))
+        end
+
+        # A map's value schema, or nil if this node isn't a map. axn omits `additionalProperties`
+        # entirely rather than emitting an empty one, and never emits the boolean form.
+        def map_values(node)
+          values = node[:additionalProperties]
+          values if values.is_a?(Hash) && values.any?
+        end
+
+        # True when a schema constrains nothing beyond the type itself -- exactly the case a type word
+        # conveys in full, with no JSON clause needed.
+        def bare_type?(schema)
+          case schema.keys
+          when [:type] then true
+          when [:anyOf] then schema[:anyOf].all? { |entry| entry.is_a?(Hash) && entry.keys == [:type] }
+          else false
+          end
+        end
+
+        # "integer"; "integer or null" (axn's array-valued nullable type -- annotation runs BEFORE
+        # normalize_nullable_types rewrites it to anyOf); "string or integer" (a union's anyOf). nil
+        # when no type is declared at all, which sends the caller to the JSON-only phrasing.
+        def bare_type_phrase(schema)
+          types = if schema[:type].is_a?(String)
+                    [schema[:type]]
+                  elsif schema[:type].is_a?(Array)
+                    schema[:type]
+                  elsif schema[:anyOf].is_a?(Array)
+                    schema[:anyOf].filter_map { |entry| entry[:type] if entry.is_a?(Hash) }
+                  end
+
+          return nil unless types.is_a?(Array) && types.any? && types.all?(String)
+
+          types.uniq.join(" or ")
+        end
+
+        # minProperties/maxProperties. Gemini forwards an ARRAY's minItems/maxItems but has no OBJECT
+        # equivalent, so an entry-count bound is lost whether or not the node is also a map -- a plain
+        # `expects :meta, type: Hash` already reflects `minProperties: 1` from axn's non-blank default.
+        def entry_count_sentence(node)
+          min = node[:minProperties]
+          max = node[:maxProperties]
+          # A zero minimum admits the empty object, i.e. constrains nothing -- reporting it as
+          # "must not be empty" below would state the opposite of what the schema allows.
+          min = nil unless min.is_a?(Integer) && min.positive?
+          max = nil unless max.is_a?(Integer)
+          return nil unless min || max
+
+          bound = if min && max && min == max then "exactly #{entry_count(min)}"
+                  elsif min && max then "between #{min} and #{entry_count(max)}"
+                  elsif max then "at most #{entry_count(max)}"
+                  elsif min > 1 then "at least #{entry_count(min)}"
+                  end
+
+          # A bare `minProperties: 1` is just non-emptiness, and reads far better said that way.
+          bound ? "This object must have #{bound}." : "This object must not be empty."
+        end
+
+        def entry_count(count)
+          "#{count} #{count == 1 ? "entry" : "entries"}"
+        end
       end
     end
 

data/lib/axn/ruby_llm/version.rb

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

data/lib/axn/ruby_llm.rb

@@ -12,17 +12,20 @@ module Axn
     include Axn::Mountable
     extend Axn::Configurable
     extend Axn::Tools::AdapterRoots
+    extend Axn::Tools::AdapterSerialization
 
     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
+    # `Axn::Tools::AdapterRoots` (extended above) declares `tool_roots` with core's conservative
+    # `default: []`; `tool_roots_default` re-declares it to ship the shared agent-tools dir, 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) }
+    # axn-mcp defaults to, so one Axn there is authored once and surfaces on both. Going through
+    # `tool_roots_default` rather than a hand-written `setting` keeps AdapterRoots' broad-path
+    # validation (no widening a root to `app/`/`actions`/`.`/`..`) without hand-copying its lambda, and
+    # validates the default EAGERLY at gem load instead of at the registry's first read.
+    tool_roots_default %w[agent_tools]
 
     # 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.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: axn-ruby_llm
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Kali Donovan
@@ -15,7 +15,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.0.pre.alpha.5
+        version: 0.1.0.pre.alpha.6
     - - "<"
       - !ruby/object:Gem::Version
         version: 0.2.0
@@ -25,7 +25,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.0.pre.alpha.5
+        version: 0.1.0.pre.alpha.6
     - - "<"
       - !ruby/object:Gem::Version
         version: 0.2.0