smith-agents 0.4.2 → 0.4.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1c5a7f554819eb342aa2284fb010eba8126f22fba1348683a36fbc4fa9d5383f
-  data.tar.gz: b72e10a5415340c5b337751c0cc92f2f59ed0ddb62850e03746df217be374721
+  metadata.gz: 8b8a1ad3fc2cb40ef0287063f81e0bc01a6bca349b1625c4173daef763785202
+  data.tar.gz: b870358edea9686d15e164bb3d44e00edf8e50da8cb2d68b8a6a666bbc5d0f79
 SHA512:
-  metadata.gz: 75d149a61196f2c0cd22748ff6d5a6c4530bc9d91c61b163c027e44d555b9fd0f1ca5ef0a283c6025d6906b6d984923265fba05190fa3da37a60cfe864e5f6f8
-  data.tar.gz: 906bc56189df0f84ad62cb643ed8141a05780a328bf9a3770db55c575d71db86b94ad39e91517ba0e2d76f05942f84358dc234b2e685ad0701dba059bed65d36
+  metadata.gz: bd9dd710fb5008efc7896e950b52621d3c80dab9be902b323efdc76c3d4d12e4b1c066b2219e5e36c56edea5652add7406ecb1d740db79b320035eee9047cee6
+  data.tar.gz: 4d5e6b412d39269276096b697a399ad476dd1d4bc370792d8acfdd8f49041b567da2120e56a0fc1e090cbf4c351c9849201c8b0030fd5518f6c69495b175f534

data/CHANGELOG.md

@@ -6,7 +6,59 @@ 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
 
@@ -128,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`.
@@ -188,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

@@ -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.3", 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/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

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../../persistence_adapters"
+
 module Smith
   module Doctor
     module Checks
@@ -12,41 +14,16 @@ module Smith
       module PersistenceCapabilities
         module_function
 
-        OPTIONAL_CAPABILITIES = %i[store_versioned].freeze
+        OPTIONAL_CAPABILITIES = Smith::PersistenceAdapters::OPTIONAL_METHODS
 
         def run(report)
           adapter = resolve_adapter
-          if adapter.nil?
-            report.add(
-              name: "persistence.capabilities",
-              status: :warn,
-              message: "No persistence adapter configured",
-              detail: "Smith.config.persistence_adapter is nil and Smith.config.test_mode is false. " \
-                      "Hosts using durable workflows must set persistence_adapter."
-            )
-            return
-          end
+          return report_missing_adapter(report) if adapter.nil?
 
           missing = OPTIONAL_CAPABILITIES.reject { |cap| Smith::PersistenceAdapters.supports?(adapter, cap) }
+          return report_supported_capabilities(report, adapter) if missing.empty?
 
-          if missing.empty?
-            report.add(
-              name: "persistence.capabilities",
-              status: :pass,
-              message: "#{adapter.class.name} supports all optional persistence capabilities",
-              detail: "Supported: #{OPTIONAL_CAPABILITIES.join(', ')}"
-            )
-          else
-            report.add(
-              name: "persistence.capabilities",
-              status: :warn,
-              message: "#{adapter.class.name} missing optional capabilities: #{missing.join(', ')}",
-              detail: "Workflows using these capabilities fall back to non-versioned writes " \
-                      "with a one-time warning per adapter class. Switch to RedisStore, " \
-                      "ActiveRecordStore (with lock_version column), or the Memory adapter " \
-                      "for full coverage."
-            )
-          end
+          report_missing_capabilities(report, adapter, missing)
         end
 
         def resolve_adapter
@@ -54,6 +31,37 @@ module Smith
         rescue StandardError
           nil
         end
+
+        def report_missing_adapter(report)
+          report.add(
+            name: "persistence.capabilities",
+            status: :warn,
+            message: "No persistence adapter configured",
+            detail: "Smith.config.persistence_adapter is nil and Smith.config.test_mode is false. " \
+                    "Hosts using durable workflows must set persistence_adapter."
+          )
+        end
+
+        def report_supported_capabilities(report, adapter)
+          report.add(
+            name: "persistence.capabilities",
+            status: :pass,
+            message: "#{adapter.class.name} supports all optional persistence capabilities",
+            detail: "Supported: #{OPTIONAL_CAPABILITIES.join(", ")}"
+          )
+        end
+
+        def report_missing_capabilities(report, adapter, missing)
+          report.add(
+            name: "persistence.capabilities",
+            status: :warn,
+            message: "#{adapter.class.name} missing optional capabilities: #{missing.join(", ")}",
+            detail: "Smith will fall back where possible: non-versioned writes when store_versioned " \
+                    "is missing, and payload updated_at parsing when heartbeat methods are missing. " \
+                    "Use RedisStore or Memory for full versioning and heartbeat coverage; " \
+                    "ActiveRecordStore currently covers optimistic locking when lock_version is present."
+          )
+        end
       end
     end
   end

data/lib/smith/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Smith
-  VERSION = "0.4.2"
+  VERSION = "0.4.3"
 end

data/lib/smith/workflow/agent_result.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    # rubocop:disable Style/RedundantStructKeywordInit
+    AgentResult = Struct.new(
+      :content, :input_tokens, :output_tokens, :cost, :model_used,
+      keyword_init: true
+    ) do
+      def self.from_response(response, content, model_used: nil)
+        new(
+          content: content,
+          input_tokens: response.respond_to?(:input_tokens) ? response.input_tokens : nil,
+          output_tokens: response.respond_to?(:output_tokens) ? response.output_tokens : nil,
+          cost: nil,
+          model_used: model_used
+        )
+      end
+
+      def usage_known?
+        !input_tokens.nil? && !output_tokens.nil?
+      end
+    end
+    # rubocop:enable Style/RedundantStructKeywordInit
+  end
+end

data/lib/smith/workflow/branch_env.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    # rubocop:disable Style/RedundantStructKeywordInit
+    BranchEnv = Struct.new(
+      :prepared_input, :guardrail_sources, :scoped_store, :branch_estimates, :deadline,
+      keyword_init: true
+    ) do
+      def setup_thread
+        Smith::Tool.current_guardrails = guardrail_sources
+        Smith::Tool.current_deadline = deadline
+        Smith.scoped_artifacts = scoped_store
+      end
+
+      def teardown_thread
+        Smith::Tool.current_guardrails = nil
+        Smith::Tool.current_deadline = nil
+        Smith.scoped_artifacts = nil
+      end
+    end
+    # rubocop:enable Style/RedundantStructKeywordInit
+  end
+end

data/lib/smith/workflow/budget_integration.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "agent_result"
+
 module Smith
   class Workflow
     module BudgetIntegration

data/lib/smith/workflow/deterministic_execution.rb

@@ -29,7 +29,7 @@ module Smith
           session_messages: snapshot_value(@session_messages || []),
           tool_results: snapshot_value(@tool_results || []),
           state: @state,
-          transition_name: transition.name
+          transition: transition
         )
       end