smith-agents 0.4.1 → 0.4.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fce22e9b87caf5c01417a5e7d8fe7a6f4ee179abebc61644074400452a078791
-  data.tar.gz: e7d2ae59746ff545f5d45215bcec20dea95ee82a37d7fa765c4ded95484d4029
+  metadata.gz: 8b8a1ad3fc2cb40ef0287063f81e0bc01a6bca349b1625c4173daef763785202
+  data.tar.gz: b870358edea9686d15e164bb3d44e00edf8e50da8cb2d68b8a6a666bbc5d0f79
 SHA512:
-  metadata.gz: 8d8515c459487f57c20301581e6f1d5cc786f8bfe7089b4e628548145ac56e0c9c93e9560ac37f1fa7818f95a71a1c8753cb275267b341fb39ca4bf63d5e5f3e
-  data.tar.gz: b3e05ca16fc7fec62e8172d9d6ccb84b0bc3f7546af22b9f47c8a36ce4b7e6e5bfb35b0fb47eb51c0b86cf4ab4fbe47e651406c1666fcc63d4b2c16b0ccb0bf9
+  metadata.gz: bd9dd710fb5008efc7896e950b52621d3c80dab9be902b323efdc76c3d4d12e4b1c066b2219e5e36c56edea5652add7406ecb1d740db79b320035eee9047cee6
+  data.tar.gz: 4d5e6b412d39269276096b697a399ad476dd1d4bc370792d8acfdd8f49041b567da2120e56a0fc1e090cbf4c351c9849201c8b0030fd5518f6c69495b175f534

data/CHANGELOG.md

@@ -6,7 +6,95 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Version
 
 ## [Unreleased]
 
-No unreleased changes.
+## [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
+
+Patch release for bounded fan-out and retry workflow primitives. This remains
+workflow-first and host-owned: Smith executes declared transitions and exposes
+inspection metadata, while durable scheduling, long waits, tool adapter
+contracts, and deployment packaging stay with the host application.
+
+### Added
+
+- `fan_out branches: {...}` transition DSL for bounded heterogeneous
+  multi-agent fan-out with stable branch keys and named aggregate results.
+- `retry_on` transition DSL for bounded local retries using explicit error
+  classes or Smith's built-in retryability classifier.
+- Graph inspection metadata for `:fanout` transitions and retry policy details.
+
+### Changed
+
+- Fan-out branch execution preserves branch identity, branch-specific budgets,
+  agent guardrails, tool guardrails, deadlines, and usage accounting.
+- Parallel/fan-out failure handling now prefers the initiating branch error over
+  cooperative cancellation errors.
+- Failed-but-billable provider attempts are included in budget reconciliation
+  for retry, fallback, and fan-out settlement paths.
+- Retry `max_delay` remains a hard cap even when jitter is configured.
+
+### Test coverage
+
+- Default suite: 880 examples, 0 failures.
+- Practical gem-level execution probe covering heterogeneous `fan_out`,
+  same-agent parallel execution, `retry_on`, failed-but-billable budget
+  settlement, cancellation cause preservation, branch input guardrail ordering
+  before session preparation, graph metadata, and invalid declaration rejection.
+- Added focused coverage for heterogeneous fan-out, retry policies,
+  failed-but-billable retry budget accounting, cancellation cause preservation,
+  and graph inspection metadata.
 
 ## [0.4.1] - 2026-06-28
 
@@ -92,7 +180,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`.
@@ -152,4 +240,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

@@ -5,11 +5,19 @@ Workflow-first multi-agent orchestration for Ruby. Smith sits on top of `RubyLLM
 > [!WARNING]
 > Smith is pre-1.0. Expect contract tightening between minor versions. Pin to an exact version in production.
 
+## Verification Discipline
+
+Tests are required, but they are never enough for runtime primitive changes.
+Every Smith workflow slice must also run practical gem-level execution probes.
+When a host application consumes unreleased Smith changes, point that host app at
+the local Smith repository and exercise the changed workflow paths in the host
+environment before calling the slice complete.
+
 ## Installation
 
 ```ruby
 # Gemfile
-gem "smith-agents", "~> 0.2.0", require: "smith"
+gem "smith-agents", "~> 0.4.3", require: "smith"
 ```
 
 ```bash
@@ -87,6 +95,7 @@ end
 | Pipeline | sequential transitions | Multi-step workflow with explicit success/failure routing. |
 | Router | `route :classifier, routes: {...}` | Branch on a classifier agent's output. |
 | Parallel fan-out | `execute :agent, parallel: true` | Concurrent agent calls under one ledger. |
+| Heterogeneous fan-out | `fan_out branches: {...}` | Concurrent calls to different agents with named branch results. |
 | Nested workflow | `workflow OtherWorkflow` | Reuse a subflow as one transition. |
 | Evaluator-Optimizer | `optimize generator:, evaluator:, ...` | Generate-then-critique refinement loops. |
 | Orchestrator-Worker | `orchestrate orchestrator:, worker:, ...` | Dynamic task fan-out with delegation rounds. |
@@ -94,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.
@@ -109,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
@@ -153,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
@@ -230,6 +282,19 @@ Smith::Errors.retryable_classes
 # => [Smith::AgentError, Smith::DeadlineExceeded]  (for ActiveJob retry_on)
 ```
 
+Workflow transitions can also declare a bounded local retry policy:
+
+```ruby
+transition :draft, from: :idle, to: :done do
+  execute :writer
+  retry_on Smith::AgentError, attempts: 3, backoff: 0.1, max_delay: 1.0
+end
+```
+
+When no classes are passed, `retry_on` uses `Smith::Errors.retryable?`.
+This is a bounded local transition retry policy. Durable scheduling, long waits,
+and external idempotency guarantees remain host-owned.
+
 ## Development
 
 ```bash
@@ -238,4 +303,5 @@ bundle exec rspec
 bundle exec rubocop
 ```
 
-770 examples, MIT licensed. See [`CHANGELOG.md`](CHANGELOG.md) for the 0.2.0 surface and [`UPSTREAM_PROPOSAL.md`](UPSTREAM_PROPOSAL.md) for the vendored Responses adapter retirement path.
+880 examples, MIT licensed. See [`CHANGELOG.md`](CHANGELOG.md) for the current
+release surface.

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

@@ -239,7 +239,49 @@ Why this is valuable:
 - branch failures discard step output and route through normal failure handling
 - prepared input is reused consistently across branches
 
-## Example 6: Nested Workflows
+## Example 6: Heterogeneous Fan-Out
+
+Use heterogeneous fan-out when different specialists should run concurrently and return named branch results under one workflow transition.
+
+```ruby
+class StaticReviewAgent < Smith::Agent
+  register_as :static_review_agent
+  model "gpt-4.1-nano"
+end
+
+class SecurityReviewAgent < Smith::Agent
+  register_as :security_review_agent
+  model "gpt-4.1-nano"
+end
+
+class CodeReviewWorkflow < Smith::Workflow
+  initial_state :idle
+  state :reviewed
+  state :failed
+
+  transition :review, from: :idle, to: :reviewed do
+    fan_out branches: {
+      static: :static_review_agent,
+      security: :security_review_agent
+    }
+    on_failure :fail
+  end
+end
+```
+
+What you get:
+
+- stable branch identity in the step output
+- branch-specific agent budgets, guardrails, tools, and model configuration
+- 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.
+
+## Example 7: Nested Workflows
 
 Use nested workflows when one part of the system deserves to be a reusable subflow with its own states and transitions.
 
@@ -281,7 +323,7 @@ What you get:
 - nested best-known token/cost totals roll up into the parent result
 - artifact scope is preserved across nesting
 
-## Example 7: Evaluator-Optimizer
+## Example 8: Evaluator-Optimizer
 
 Use `optimize` when one agent generates candidates and another agent evaluates whether the result is acceptable.
 
@@ -334,8 +376,42 @@ 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
-
-## Example 8: Orchestrator-Worker
+- 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
 
 Use `orchestrate` when you need an orchestrator that can emit structured tasks for workers and later decide when the system is done.
 
@@ -414,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:
 
@@ -480,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.
@@ -489,4 +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

@@ -46,10 +46,10 @@ module Smith
 
       def build_model_chain(agent_class)
         primary = if agent_class.respond_to?(:model_block) && agent_class.model_block
-          resolve_dynamic_model(agent_class)
-        else
-          agent_class.chat_kwargs[:model]
-        end
+                    resolve_dynamic_model(agent_class)
+                  else
+                    agent_class.chat_kwargs[:model]
+                  end
         fallbacks = agent_class.fallback_models || []
         [primary, *fallbacks].compact
       end
@@ -103,8 +103,8 @@ module Smith
 
         declared = agent_class.inputs || []
         user_declared = declared - Smith::Agent::RESERVED_INPUT_NAMES
-        user_declared.each_with_object({}) do |name, kwargs|
-          kwargs[name] = @context[name]
+        user_declared.to_h do |name|
+          [name, @context[name]]
         end
       end
 
@@ -131,7 +131,9 @@ module Smith
 
         combined_contents = existing_system_contents + prepared_system_contents
         return if combined_contents.empty?
-        return prepared_system_messages.each { |message| chat.add_message(message) } unless combined_contents.all?(String)
+        unless combined_contents.all?(String)
+          return prepared_system_messages.each { |message| chat.add_message(message) }
+        end
 
         if chat.respond_to?(:with_instructions)
           chat.with_instructions(combined_contents.join("\n\n"))
@@ -178,6 +180,8 @@ module Smith
         agent_result = Workflow::AgentResult.new(
           content: nil, input_tokens: input, output_tokens: output, cost: cost, model_used: model_id
         )
+        Thread.current[:smith_failed_agent_results] ||= []
+        Thread.current[:smith_failed_agent_results] << agent_result
         record_usage(agent_class, agent_result, :failed_attempt, model_id)
       end
 

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