smith-agents 0.4.2 → 0.4.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1c5a7f554819eb342aa2284fb010eba8126f22fba1348683a36fbc4fa9d5383f
-  data.tar.gz: b72e10a5415340c5b337751c0cc92f2f59ed0ddb62850e03746df217be374721
+  metadata.gz: 23c6a49b741d4ff6cfab0707ca1d917b484dc708106d1c892b4f90e2002e5b80
+  data.tar.gz: 72cfe59171b0f759f0312ff062f58c23aeb9a9f7e738f1603dfaf4a9174f9fbb
 SHA512:
-  metadata.gz: 75d149a61196f2c0cd22748ff6d5a6c4530bc9d91c61b163c027e44d555b9fd0f1ca5ef0a283c6025d6906b6d984923265fba05190fa3da37a60cfe864e5f6f8
-  data.tar.gz: 906bc56189df0f84ad62cb643ed8141a05780a328bf9a3770db55c575d71db86b94ad39e91517ba0e2d76f05942f84358dc234b2e685ad0701dba059bed65d36
+  metadata.gz: 245ac5f48372808860db62cc661bf9c9e5bf2a1a3bc4082533b16159b09c50b113bead696d4147e10e850fe0b7fff8cef775da17aa749fc4b7a5574058b765f7
+  data.tar.gz: 7837da6f0c9855f03a0936bdec22279ec6da9c8864fae27de8ab495a334b98654617147b36b7759d171dc19ad13ae80448b18fa3c7da4f16bf84f7c378c004bf

data/CHANGELOG.md

@@ -6,7 +6,85 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Version
 
 ## [Unreleased]
 
-No unreleased changes.
+## [0.4.4] - 2026-07-10
+
+Patch release for provider-safe workflow handoffs. Smith keeps accepted agent
+outputs in durable session history while adapting only the next provider call
+when a completed workflow stage would otherwise look like an unsupported
+assistant prefill.
+
+### Fixed
+
+- Adapt workflow-prepared provider input that ends with an accepted assistant
+  result by adding a non-persisted user continuation for the next agent call.
+  This preserves Smith session history while avoiding unsupported assistant
+  prefilling on provider models that require a user turn before completion.
+  Provider preparation now also reads string-keyed roles and content restored
+  through JSON host persistence. Explicit assistant-prefill seed messages remain
+  unchanged unless they match Smith's recorded accepted workflow output.
+
+### Verification
+
+- Default suite: 932 examples, 0 failures.
+- Practical gem-level JSON persistence/restore probe with a 25-branch parallel
+  handoff, provider-safe message ordering, non-persisted continuation, and
+  explicit assistant-prefill preservation.
+- Smith Runtime host verification on Ruby 4.0.1 and Rails 8.1.3: 139 tests,
+  391 assertions, 0 failures, plus a process-level restored workflow run.
+
+## [0.4.3] - 2026-07-05
+
+### Documentation
+
+- Clarify Smith's repair and wait-style loop boundaries: `retry_on` and
+  `optimize` are executable today, deterministic repair and guarded re-entry
+  are not native first-class contracts yet, and durable polling/wait semantics
+  remain host-owned unless an explicit wait contract exists.
+
+### Added
+
+- Static graph-inspection contracts for `optimize` and `orchestrate`
+  transitions, including bounded loop/delegation settings, schema labels, output
+  contracts, exit policies, dispatch semantics, and transition-level resume
+  guarantees.
+- `Workflow.runtime_readiness`, a static diagnostic report that separates graph
+  topology validity from runtime binding readiness without executing agents,
+  tools, providers, jobs, or persistence.
+- Runtime-readiness diagnostics for unresolved, invalid, lazy/uninspectable,
+  model-less, and model-required agent bindings across execute, route,
+  optimize, orchestrate, nested, and fan-out workflow shapes.
+- Runtime-readiness metrics now expose direct counts and transitive counts folded
+  in from nested workflows.
+- `Smith::Agent::Registry.binding_for` and `.bindings` expose non-resolving
+  registry inspection for diagnostics and host cleanup.
+- Richer fan-out transition snapshot metadata: branch count, join state,
+  ordered branch list, output contract, resume contract, and per-branch result
+  contracts for named branch-result output.
+- Direct doctor coverage for registered agent model-profile checks, including
+  static primary and static fallback models, making safe-default model shaping
+  explicit before hosts rely on runtime behavior.
+
+### Changed
+
+- `smith doctor --profile rails_persistence` now reports the full optional
+  persistence capability surface (`store_versioned`, `record_heartbeat`, and
+  `last_heartbeat`) instead of checking optimistic locking only.
+- Workflow runtime value objects now live in dedicated files while preserving
+  the existing public constants (`Smith::Workflow::RunResult`,
+  `AgentResult`, `UsageEntry`, `BranchEnv`, and internal execution helpers).
+- Release documentation now reflects the current heartbeat optional-capability
+  contract and the RubyLLM integration boundary.
+
+### Test coverage
+
+- Default suite: 926 examples, 0 failures.
+- Practical gem-level execution probe covering 30 varied workflows across
+  strict/lax idempotency, same-agent parallel branches, heterogeneous fan-out,
+  retry metadata, optimizer contracts, and orchestrator-worker flows.
+- Smith Studio host verification against the local Smith checkout: 186 runtime
+  tests and a 30-scenario generated-class lifecycle proof gate.
+- Built `pkg/smith-agents-0.4.3.gem` and smoke-tested `require "smith"` from
+  the unpacked package.
 
 ## [0.4.2] - 2026-07-02
 
@@ -128,7 +206,7 @@ This release tracks two thematic refactors that together harden the agent-invoca
 - `Smith::Models` registry (Dry::Container-backed) for application-side `Smith::Models::Profile` overrides; mirrors the `Smith::Agent::Registry` stale-reload-binding pattern for Rails autoreload safety.
 - `Smith::Models::Profile` immutable capability record (`Data.define`) covering thinking_shape, accepts_temperature, tools_with_thinking_native, tools_with_thinking_route, and a derived `endpoint_mode`.
 - `Smith::Models::Inference` library-shipped pattern rules describing each provider family's payload shape (Anthropic Opus 4.7+ adaptive, Anthropic 4.0-4.6 budget_tokens, OpenAI gpt-5 family reasoning_effort + responses route, OpenAI gpt-4.x, Gemini 2.5+ budget_tokens, etc.). Smith ships zero hardcoded model_ids; new model releases that match an existing pattern work without library changes.
-- `Smith::Models::Normalizer.apply!(chat, profile:)` per-attempt request shaper. Translates Anthropic Opus 4.7+ thinking to the adaptive payload shape (`@params[:thinking] = { type: "adaptive" }` + `output_config[:effort]`), nulls temperature where the resolved profile forbids it, routes `(gpt-5 + tools + thinking)` via `openai_api_mode: :responses` when supported, drops incompatible tools otherwise. Hooks at `Smith::Agent.chat()` so direct callers (e.g., InvokeCleaner-style usage outside the workflow lifecycle) are normalized too.
+- `Smith::Models::Normalizer.apply!(chat, profile:)` per-attempt request shaper. Translates Anthropic Opus 4.7+ thinking to the adaptive payload shape (`@params[:thinking] = { type: "adaptive" }` + `output_config[:effort]`), nulls temperature where the resolved profile forbids it, routes `(gpt-5 + tools + thinking)` via `openai_api_mode: :responses` when supported, drops incompatible tools otherwise. Hooks at `Smith::Agent.chat()` so direct callers outside the workflow lifecycle are normalized too.
 - `Smith::Agent::RESERVED_INPUT_NAMES = %i[model_id provider endpoint_mode]` auto-injected into `runtime_context` per attempt from the resolved profile. The `Smith::Agent.inputs` getter returns reserved ∪ user (frozen, deduplicated); the setter raises `Smith::AgentError` if a user-declared name collides with a reserved name.
 - `Smith::Tool.compatible_with(...)` DSL for declaring per-(provider, endpoint) tool compatibility. `Smith::Tool.inherited` dups the spec so subclasses inherit the parent's compatibility metadata.
 - `Smith::Tools::Think` declares `compatible_with :anthropic, :gemini, openai: :responses`. Drops gracefully on OpenAI chat-completions when `openai_api_mode = :off`, runs via `/v1/responses` when `:auto`.
@@ -188,4 +266,4 @@ This release tracks two thematic refactors that together harden the agent-invoca
 
 ## [0.1.0] - Initial public-track release
 
-Initial pre-release tagged for the Hadithi consumer's local-path dependency. No formal changelog prior to the Phase A/B refactor.
+Initial pre-release. No formal changelog prior to the Phase A/B refactor.

data/README.md

@@ -17,7 +17,7 @@ environment before calling the slice complete.
 
 ```ruby
 # Gemfile
-gem "smith-agents", "~> 0.4.2", require: "smith"
+gem "smith-agents", "0.4.4", require: "smith"
 ```
 
 ```bash
@@ -103,6 +103,21 @@ end
 
 The full pattern guide with working examples for each lives in [`docs/PATTERNS.md`](docs/PATTERNS.md).
 
+### Repair And Wait Boundaries
+
+Smith only owns repair and wait-style loop behavior when the bounds and stop
+conditions are explicit and enforceable inside the workflow step. Durable
+timers, queue delivery, and wake-up policy remain host-owned.
+For bounded dynamic delegation, use the separate Orchestrator-Worker pattern.
+
+| Contract | Status | Smith mapping |
+|---|---|---|
+| Retry loop | Executable | `retry_on`, bounded to one transition. |
+| Evaluator-Optimizer | Executable | `optimize`, bounded by `max_rounds` plus structured evaluator output. |
+| Deterministic repair | Not first-class yet | Can be handwritten with `compute` / `run` only when the workflow author owns the exact guard, repair, revalidation, and exit policy. Deterministic steps may declare inspectable `routes: [...]`, but that is not a native repair-loop contract. |
+| Guarded state re-entry | Not first-class yet | `compute` / `run` can declare and route to named transitions with `routes: [...]`, but Smith does not yet own persisted entry counts, mutation policy, or safe re-entry contracts. |
+| Polling / wait | Host-owned | Use the host app's queue/timer plus Smith persistence helpers. Smith must not model durable polling with busy-waits or sleep loops. |
+
 ## Workflow Graph Inspection
 
 Smith can inspect a workflow's declared graph without running agents or advancing state. This is useful for host apps that want to render, lint, or cache a workflow shape before execution.
@@ -118,6 +133,31 @@ report.metrics       # => state, transition, reachability, and terminal-state co
 
 Graph inspection is static and diagnostic-only. Runtime execution, persistence, progress projection, retries, and recovery remain host-owned concerns.
 
+Smith also exposes a static runtime-readiness report for checks that require
+declared runtime bindings but still do not execute the workflow:
+
+```ruby
+readiness = ReplyWorkflow.runtime_readiness
+
+readiness.ready?       # => true when no readiness/topology errors exist
+readiness.status       # => :ready, :warning, or :not_ready
+readiness.diagnostics  # => topology diagnostics + runtime binding diagnostics
+```
+
+Runtime readiness checks graph topology, registered agent bindings, model
+requirements for structured runtime roles, lazy/uninspectable bindings, invalid
+non-agent bindings, nested workflow readiness, and fan-out branch binding counts.
+It does not call providers, resolve lazy container blocks, run tools, enqueue
+jobs, or verify host-owned durability.
+
+Readiness metrics include both direct graph counts and transitive counts folded
+in from nested workflows.
+
+Transition snapshots include runtime contracts for complex primitives where
+Smith owns executable semantics: heterogeneous fan-out, evaluator-optimizer, and
+orchestrator-worker transitions expose bounded settings, output shapes, and
+transition-level resume behavior for host renderers and compilers.
+
 ## Configuration
 
 ```ruby
@@ -162,7 +202,10 @@ result = ReplyWorkflow.run_persisted!(
 )
 ```
 
-Built-in adapters (all support TTL where the backend allows; `Redis`, `ActiveRecord`, `Memory` also support optimistic locking via `store_versioned`):
+Built-in adapters (all support TTL where the backend allows; `Redis`,
+`ActiveRecord`, and `Memory` support optimistic locking via `store_versioned`;
+`Redis` and `Memory` also support heartbeat probes via `record_heartbeat` /
+`last_heartbeat`):
 
 - `:memory` — in-process Hash, intended for tests and `test_mode = true`
 - `:redis` — Redis client; uses WATCH/MULTI/EXEC for CAS

data/UPSTREAM_PROPOSAL.md

@@ -139,3 +139,22 @@ What stays Smith-owned (orchestration concerns, not provider-API concerns):
 
 - RubyLLM PR #770 (OpenAI `/v1/responses` support) is the related upstream track. Smith's vendored `Smith::Providers::OpenAI::Responses` retires when #770 merges.
 - This proposal (capability profiles + before_complete) is a separate, additive RubyLLM RFC. Once accepted, Smith files a migration PR to consume it.
+
+## Current RubyLLM Docs Check
+
+As of the release-prep audit, RubyLLM's official documentation describes a model
+registry with model capability and pricing data, Rails DB-backed model registry
+support, provider overrides, instrumentation, and concurrent tool execution.
+Smith should continue treating RubyLLM as the source of truth for provider
+communication and model inventory while keeping Smith-specific workflow
+semantics, request shaping, and tool-compatibility policy explicit.
+
+Release implication: before deleting Smith's model normalizer, Responses
+adapter, or model-profile inference layer, verify that RubyLLM exposes the
+specific public hooks Smith needs for:
+
+- clearing incompatible temperature/thinking settings without private ivar
+  mutation
+- request-shaping hooks before provider payload rendering
+- endpoint selection for tools plus thinking/reasoning combinations
+- model capability fields that distinguish Smith's workflow-relevant cases

data/docs/PATTERNS.md

@@ -276,6 +276,8 @@ What you get:
 - one shared prepared input for the transition
 - one shared transition result, so downstream joins remain explicit in the workflow
 - branch failures discard partial output and route through normal failure handling
+- graph inspection exposes the join state, branch count, ordered branch map,
+  output contract, resume contract, and per-branch named result contracts
 
 Use same-agent `parallel: true` for repeated homogeneous work. Use `fan_out` when branches are different agents with different responsibilities.
 
@@ -374,6 +376,40 @@ Why this matters:
 - acceptance criteria are structured
 - exhaustion, malformed evaluator output, and convergence without acceptance fail normally
 - costs and token usage from the full loop roll into the workflow totals
+- graph inspection exposes the generator/evaluator bindings, max rounds, schema
+  label, evaluator context, exit modes, required/conditional evaluator output
+  fields, and transition-level resume contract
+
+## Repair And Wait Boundaries
+
+Smith's workflow layer is intentionally bounded. A repair or wait-style loop is
+executable in Smith only when Smith can validate the contract and enforce
+deterministic stopping rules. This section does not restate every bounded
+workflow helper; Orchestrator-Worker is a separate bounded delegation pattern.
+Today that means:
+
+| Loop kind | Executable? | Smith primitive | Boundary |
+|---|---|---|---|
+| Retry | Yes | `retry_on` | Local transition retry only. Durable scheduling and idempotency stay with the host. |
+| Evaluator-Optimizer | Yes | `optimize` | Bounded refinement inside one transition using structured evaluator output. |
+| Deterministic repair | Not native | Handwritten `compute` / `run` when exact semantics are owned by the workflow author. Deterministic route targets can be declared with `routes: [...]`. | No first-class repair contract or persisted repair counts yet. |
+| Guarded state re-entry | Not native | Handwritten `compute` / `run` may declare and route to named transitions with `routes: [...]`. | No Smith-owned entry-count ledger, re-entry guard contract, or mutation policy yet. |
+| Polling / wait | No | Host queue/timer plus Smith persistence helpers. | Smith must not model durable polling with sleeps, busy-waits, or `max_transitions` cycling. |
+
+Do not hide a durable wait or unbounded repair policy inside `compute` / `run`.
+Those primitives are synchronous deterministic steps inside the current workflow
+runner. They are appropriate for local verification, normalization, failure
+classification, explicit routing, and bounded retry-adjacent checks; they are
+not a durable scheduler.
+
+If a host or compiler wants deterministic repair, polling/wait, or guarded
+state re-entry as reusable graph contracts, the contract must be added explicitly
+before code generation claims executability. Deterministic `routes: [...]`
+annotations make handwritten route targets inspectable, but they do not by
+themselves provide bounded repair counts, mutation policy, or durable wait
+semantics. At minimum that future contract needs bounded attempts, persisted
+state keys where appropriate, deterministic exit behavior, graph-inspection
+metadata, and practical execution coverage.
 
 ## Example 9: Orchestrator-Worker
 
@@ -454,6 +490,9 @@ Why this is valuable:
 - tasks and outputs are structured
 - worker fan-out is controlled
 - exhaustion and malformed orchestrator output fail as first-class workflow failures
+- graph inspection exposes orchestrator/worker bindings, bounds, schema labels,
+  decision/output contracts, serial worker-dispatch semantics, and
+  transition-level resume behavior
 
 Notes:
 
@@ -520,7 +559,7 @@ The yielded step object exposes a narrow, read-heavy surface:
 
 ### Behavior
 
-- **Routing**: `step.route_to` overrides `on_success`. If neither is set, normal state-based resolution applies. Named transitions that do not exist fail loudly with `WorkflowError`.
+- **Routing**: `step.route_to` overrides `on_success`. If neither is set, normal state-based resolution applies. Named transitions that do not exist fail loudly with `WorkflowError`. When a deterministic transition declares `compute(routes: [...])` or `run(routes: [...])`, `step.route_to` must target one of those names; graph inspection validates the annotated targets before runtime.
 - **Failure**: `step.fail!` raises `Smith::DeterministicStepFailure` (extends `WorkflowError`) with `retryable`, `kind`, and `details` metadata. Routes through `on_failure` like any other step failure.
 - **Outcome**: `step.write_outcome(kind:, payload:)` stores a workflow-owned terminal payload without smuggling it through context. The payload is persisted with the workflow and surfaced on `RunResult.outcome`, `RunResult.outcome_kind`, and `RunResult.outcome_payload`.
 - **Context reads**: `step.context` returns an isolated snapshot of the workflow context at step start. Mutating that snapshot does not mutate workflow state. `step.read_context(key)` returns a merged view — pending `write_context` values override the snapshot. Use `read_context` when you need read-after-write coherence within the same step.
@@ -529,3 +568,4 @@ The yielded step object exposes a narrow, read-heavy surface:
 - **Persistence**: Context writes and written outcomes survive `to_state`/`from_state`. The block itself (a Proc) lives on the class-level Transition and is never serialized.
 - **Trace**: Emits `:deterministic_step` traces for start, success/routed, and failure. When a step writes an outcome, the trace includes `outcome_kind`.
 - **Mutual exclusivity**: `compute` and `run` cannot be combined with `execute`, `route`, `workflow`, `optimize`, or `orchestrate`. A transition declares exactly one primary execution body.
+- **No hidden scheduler**: `compute` and `run` execute synchronously inside the current runner. Use them for bounded deterministic logic, not for durable polling or wake-up loops.

data/lib/smith/agent/lifecycle.rb

@@ -3,6 +3,10 @@
 module Smith
   class Agent
     module Lifecycle
+      WORKFLOW_CONTINUATION_MESSAGE =
+        "Use the preceding assistant result as input and perform your assigned workflow step."
+      private_constant :WORKFLOW_CONTINUATION_MESSAGE
+
       TRANSIENT_ERRORS = [
         RubyLLM::ServerError, RubyLLM::ServiceUnavailableError,
         RubyLLM::OverloadedError, RubyLLM::RateLimitError
@@ -111,6 +115,7 @@ module Smith
       def add_prepared_input(chat, prepared_input)
         return unless prepared_input
 
+        prepared_input = provider_safe_prepared_input(prepared_input)
         system_messages, other_messages = prepared_input.partition do |message|
           message_role(message) == :system
         end
@@ -119,6 +124,22 @@ module Smith
         other_messages.each { |message| chat.add_message(message) }
       end
 
+      def provider_safe_prepared_input(prepared_input)
+        messages = prepared_input.to_a
+        return messages unless workflow_handoff?(messages)
+
+        messages + [{ role: :user, content: WORKFLOW_CONTINUATION_MESSAGE }]
+      end
+
+      def workflow_handoff?(messages)
+        message = messages.reverse_each.find { |candidate| message_role(candidate) != :system }
+        return false unless message
+        return false unless message_role(message) == :assistant
+        return false unless defined?(@last_output) && !@last_output.nil?
+
+        message_content(message) == @last_output
+      end
+
       def merge_system_messages!(chat, prepared_system_messages)
         return prepared_system_messages.each { |message| chat.add_message(message) } unless chat.respond_to?(:messages)
 
@@ -143,19 +164,18 @@ module Smith
       end
 
       def message_role(message)
-        if message.respond_to?(:role)
-          message.role&.to_sym
-        else
-          message[:role]&.to_sym
-        end
+        message_attribute(message, :role)&.to_sym
       end
 
       def message_content(message)
-        if message.respond_to?(:content)
-          message.content
-        else
-          message[:content]
-        end
+        message_attribute(message, :content)
+      end
+
+      def message_attribute(message, name)
+        return message.public_send(name) if message.respond_to?(name)
+        return message[name] if message.respond_to?(:key?) && message.key?(name)
+
+        message[name.to_s]
       end
 
       def fallback_eligible?(error)

data/lib/smith/agent/registry/introspection.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Smith
+  class Agent
+    module Registry
+      module Introspection
+        def binding_for(name)
+          registry_monitor.synchronize do
+            key = normalize_key(name)
+            item = _container[key]
+            item ? Smith::Agent::RegistryBinding.new(key: key, item: item).to_h : nil
+          end
+        end
+
+        def bindings
+          registry_monitor.synchronize do
+            _container.each_with_object({}) do |(key, item), binding_map|
+              binding_map[key] = Smith::Agent::RegistryBinding.new(key: key, item: item).to_h
+            end.freeze
+          end
+        end
+      end
+
+      extend Introspection
+    end
+  end
+end

data/lib/smith/agent/registry.rb

@@ -2,6 +2,7 @@
 
 require "dry-container"
 require "monitor"
+require_relative "registry_binding"
 
 module Smith
   class Agent
@@ -14,14 +15,10 @@ module Smith
 
       def self.find(name)
         registry_monitor.synchronize do
-          key = normalize_key(name)
-          key?(key) ? resolve(key) : nil
+          registered_binding(normalize_key(name))
         end
       end
 
-      # Override Dry::Container::Mixin#register to route agent classes
-      # through ensure_registered while preserving full generic container
-      # semantics (block, options) for non-agent registrations.
       def self.register(key, contents = nil, options = {}, &block)
         if block_given? || !(contents.is_a?(Class) && contents <= Smith::Agent)
           registry_monitor.synchronize { super(key, contents, options, &block) }
@@ -47,7 +44,7 @@ module Smith
         key = normalize_key(name)
 
         registry_monitor.synchronize do
-          existing = key?(key) ? resolve(key) : nil
+          existing = registered_binding(key)
 
           if existing.nil?
             register_unchecked!(key, klass)
@@ -71,22 +68,15 @@ module Smith
       def self.fetch!(name, workflow_class: nil, transition_name: nil, role: :agent)
         registry_monitor.synchronize do
           key = normalize_key(name)
-          return resolve(key) if key?(key)
-
-          details = []
-          details << "workflow #{workflow_class}" if workflow_class
-          details << "transition :#{transition_name}" if transition_name
-          suffix = details.empty? ? "" : " for #{details.join(', ')}"
+          binding = registered_binding(key)
+          return binding if binding
 
-          raise Smith::WorkflowError, "unresolved #{role} :#{key}#{suffix}"
+          raise Smith::WorkflowError, "unresolved #{role} :#{key}#{fetch_suffix(workflow_class, transition_name)}"
         end
       end
 
-      # Re-entrant lock (Monitor, not Mutex) so block-backed resolve
-      # inside find/fetch! can safely re-enter the registry without
-      # deadlocking on the same thread.
       def self.registry_monitor
-        @_registry_monitor ||= Monitor.new
+        @registry_monitor ||= Monitor.new
       end
 
       def self.validate_agent_class!(klass)
@@ -115,6 +105,19 @@ module Smith
       end
       private_class_method :register_unchecked!
 
+      def self.registered_binding(key)
+        key?(key) ? resolve(key) : nil
+      end
+      private_class_method :registered_binding
+
+      def self.fetch_suffix(workflow_class, transition_name)
+        details = []
+        details << "workflow #{workflow_class}" if workflow_class
+        details << "transition :#{transition_name}" if transition_name
+        details.empty? ? "" : " for #{details.join(", ")}"
+      end
+      private_class_method :fetch_suffix
+
       def self.stale_reload_binding?(existing, klass)
         existing_name = existing.respond_to?(:name) ? existing.name : nil
         klass_name = klass.name
@@ -126,3 +129,5 @@ module Smith
     end
   end
 end
+
+require_relative "registry/introspection"

data/lib/smith/agent/registry_binding.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+module Smith
+  class Agent
+    class RegistryBinding
+      extend Dry::Initializer
+
+      option :key
+      option :item
+
+      def to_h
+        {
+          key: key,
+          agent_class: agent_class,
+          call: call?,
+          raw_binding: raw_binding
+        }.freeze
+      end
+
+      private
+
+      def agent_class
+        return unless call? == false
+
+        raw_binding if raw_binding.is_a?(Class) && raw_binding <= Smith::Agent
+      end
+
+      def call?
+        options.fetch(:call, true)
+      end
+
+      def raw_binding
+        item.instance_variable_get(:@item)
+      end
+
+      def options
+        item.instance_variable_get(:@options) || {}
+      end
+    end
+  end
+end

data/lib/smith/agent.rb

@@ -142,10 +142,9 @@ module Smith
 
       # Closes the `inputs` contract at the chat() boundary AND runs the
       # Smith::Models::Normalizer. Hook lives here (not in
-      # Lifecycle#attempt_model) so direct callers like hadithi-xl's
-      # InvokeCleaner.chat (which constructs a chat outside the workflow
-      # lifecycle) are normalized too. Without this placement, Cleaner's
-      # Opus 4.7 adaptive thinking translation would only fire for
+      # Lifecycle#attempt_model) so direct callers that construct a chat
+      # outside the workflow lifecycle are normalized too. Without this
+      # placement, model-specific request translation would only fire for
       # workflow-driven calls.
       #
       # Single profile lookup: resolved once via Models.find_or_infer and

data/lib/smith/doctor/checks/models_registry.rb

@@ -36,29 +36,40 @@ module Smith
           end
         end
 
-        # Walk Smith::Agent::Registry. For each agent, extract the model
-        # id from chat_kwargs (static `model "..."` form). Block-form
-        # `model do |ctx| ... end` agents are skipped because their
-        # model is resolved per-attempt and can't be enumerated at boot.
+        # Walk Smith::Agent::Registry. For each agent, extract every static
+        # model id Smith can know at boot: the primary `model "..."` value and
+        # any static fallback models. Block-form primary models are skipped
+        # because they resolve per-attempt, but their static fallbacks still
+        # need coverage checks.
         # Check whether find_or_infer returns a custom (non-default)
         # Profile — meaning either an explicit override or an inference
         # rule matched.
         def uncovered_models
           return [] unless defined?(Smith::Agent::Registry)
 
-          model_ids = []
-          Smith::Agent::Registry.each do |_key, agent|
-            next unless agent.is_a?(Class)
-            next unless agent.respond_to?(:chat_kwargs)
+          static_model_ids.uniq.reject { |model_id| covered_model?(model_id) }
+        end
 
-            id = agent.chat_kwargs[:model]
-            model_ids << id if id
+        def static_model_ids
+          Smith::Agent::Registry.each.with_object([]) do |(_key, agent), ids|
+            ids.concat(static_model_ids_for(agent)) if inspectable_agent?(agent)
           end
+        end
 
-          model_ids.uniq.reject do |model_id|
-            Smith::Models.find(model_id) ||
-              (defined?(Smith::Models::Inference) && Smith::Models::Inference.profile_for(model_id))
-          end
+        def inspectable_agent?(agent)
+          agent.is_a?(Class) && agent.respond_to?(:chat_kwargs)
+        end
+
+        def static_model_ids_for(agent)
+          [
+            agent.chat_kwargs[:model],
+            *(agent.respond_to?(:fallback_models) ? agent.fallback_models : nil)
+          ].compact
+        end
+
+        def covered_model?(model_id)
+          Smith::Models.find(model_id) ||
+            (defined?(Smith::Models::Inference) && Smith::Models::Inference.profile_for(model_id))
         end
       end
     end