smith-agents 0.10.0 → 0.12.0

data/lib/smith/workflow/failure_reconstructor.rb

@@ -18,14 +18,33 @@ module Smith
         "bounded_completion_error" => ->(record) { Smith::BoundedCompletionError.new(record[:error_message]) },
         "persisted_failure_invalid" => ->(record) { Smith::PersistedFailureInvalid.new(record[:error_message]) },
         "deadline_exceeded" => ->(record) { Smith::DeadlineExceeded.new(record[:error_message]) },
+        "provider_permanent_failure" => ->(record) { provider_permanent_failure(record) },
+        "budget_exceeded" => ->(record) { budget_exceeded(record) },
+        "guardrail_failed" => ->(record) { Smith::GuardrailFailed.new(record[:error_message]) },
         "agent_error" => ->(record) { Smith::AgentError.new(record[:error_message]) },
         "workflow_error" => ->(record) { Smith::WorkflowError.new(record[:error_message]) },
+        "output_failure" => lambda { |record|
+          Smith::OutputFailure.from_details(record.fetch(:error_details), message: record[:error_message])
+        },
+        "child_runs_failed" => lambda { |record|
+          Smith::ChildRunsFailed.from_details(record.fetch(:error_details), message: record[:error_message])
+        },
+        "wait_timed_out" => lambda { |record|
+          Smith::WaitTimedOut.from_details(record.fetch(:error_details), message: record[:error_message])
+        },
         "other" => ->(record) { RuntimeError.new(record[:error_message]) }
       }.freeze
       SPECIAL_CLASS_BUILDERS = {
         "Smith::Workflow::Composite::BranchFailure" => lambda { |record|
           Smith::Workflow::Composite::BranchFailure.from_details(record[:error_details])
-        }
+        },
+        "Smith::BlankAgentOutputError" => ->(record) { blank_agent_output_failure(record) },
+        "Smith::PersistedStateTooLarge" => lambda { |record|
+          Smith::PersistedStateTooLarge.from_details(record.fetch(:error_details), message: record[:error_message])
+        },
+        **Smith::OutputFailure.restorers.transform_values do |restore|
+          ->(record) { restore.call(record.fetch(:error_details), record[:error_message]) }
+        end
       }.freeze
       private_constant :FAMILY_BUILDERS, :SPECIAL_CLASS_BUILDERS
 
@@ -73,7 +92,27 @@ module Smith
         Smith::ToolFailureNotificationFailed.from_details(record.fetch(:error_details))
       end
 
-      private_class_method :deterministic_step_failure, :tool_guardrail_failure, :tool_failure_notification_failure
+      # A host ledger's refusal stays one, so a host can tell waiting for
+      # budget from a run whose own budget ran out.
+      def self.budget_exceeded(record)
+        error_class = record[:error_class] == "Smith::BudgetUnavailable" ? Smith::BudgetUnavailable : Smith::BudgetExceeded
+        error_class.new(record[:error_message])
+      end
+
+      def self.provider_permanent_failure(record)
+        Smith::ProviderPermanentFailure.from_details(record.fetch(:error_details), message: record[:error_message])
+      end
+
+      def self.blank_agent_output_failure(record)
+        details = record[:error_details]
+        return Smith::AgentError.new(record[:error_message]) if details.nil?
+
+        Smith::BlankAgentOutputError.from_details(details)
+      end
+
+      private_class_method :budget_exceeded, :deterministic_step_failure, :tool_guardrail_failure,
+                           :tool_failure_notification_failure, :provider_permanent_failure,
+                           :blank_agent_output_failure
     end
   end
 end

data/lib/smith/workflow/failure_record.rb

@@ -4,6 +4,8 @@ require "dry-initializer"
 
 require_relative "../diagnostic_text"
 require_relative "../errors"
+require_relative "../output_failure"
+require_relative "../child_runs_failed"
 require_relative "failure_detail_snapshot"
 require_relative "failure_record_text"
 
@@ -20,17 +22,20 @@ module Smith
         [Smith::PersistedFailureInvalid, "persisted_failure_invalid"],
         [Smith::ToolGuardrailFailed, "tool_guardrail_failed"],
         [Smith::DeadlineExceeded, "deadline_exceeded"],
+        [Smith::ProviderPermanentFailure, "provider_permanent_failure"],
+        [Smith::BudgetExceeded, "budget_exceeded"],
+        [Smith::GuardrailFailed, "guardrail_failed"],
+        [Smith::OutputFailure, "output_failure"],
         [Smith::AgentError, "agent_error"],
+        [Smith::WaitTimedOut, "wait_timed_out"],
+        [Smith::ChildRunsFailed, "child_runs_failed"],
         [Smith::WorkflowError, "workflow_error"]
       ].freeze
       BOOLEAN_VALUES = [true, false].freeze
       EXCEPTION_CAUSE = Exception.instance_method(:cause)
       EXCEPTION_MESSAGE = Exception.instance_method(:message)
       MODULE_MATCH = Module.instance_method(:===)
-      MODULE_NAME = Module.instance_method(:name)
-      OBJECT_CLASS = Object.instance_method(:class)
-      private_constant :ERROR_FAMILIES, :BOOLEAN_VALUES, :EXCEPTION_CAUSE, :EXCEPTION_MESSAGE, :MODULE_MATCH,
-                       :MODULE_NAME, :OBJECT_CLASS
+      private_constant :ERROR_FAMILIES, :BOOLEAN_VALUES, :EXCEPTION_CAUSE, :EXCEPTION_MESSAGE, :MODULE_MATCH
 
       extend Dry::Initializer
 
@@ -52,7 +57,7 @@ module Smith
 
       def error_attributes(error)
         {
-          error_class: DiagnosticText.capture(error_class_name(error), max_bytes: 512),
+          error_class: DiagnosticText.error_class_name(error),
           error_family: error_family(error),
           error_message: error_message(error),
           error_retryable: retryable_value(error),
@@ -70,7 +75,7 @@ module Smith
       def cause_attributes(error)
         cause = uncertainty_cause(error)
         {
-          error_cause_class: cause && DiagnosticText.capture(error_class_name(cause), max_bytes: 512),
+          error_cause_class: cause && DiagnosticText.error_class_name(cause),
           error_cause_family: cause && error_family(cause),
           error_cause_message: cause && error_message(cause)
         }
@@ -89,11 +94,6 @@ module Smith
         ERROR_FAMILIES.find { |error_class, _| MODULE_MATCH.bind_call(error_class, error) }&.last || "other"
       end
 
-      def error_class_name(error)
-        error_class = OBJECT_CLASS.bind_call(error)
-        MODULE_NAME.bind_call(error_class) || "anonymous_error"
-      end
-
       # Never captures blank text: restore requires non-empty messages, so
       # a blank live message takes the shared deterministic placeholder.
       def error_message(error)
@@ -131,7 +131,7 @@ module Smith
         FailureDetailSnapshot.new(error.details).call
       rescue StandardError => e
         FailureDetailSnapshot.new(
-          smith_failure_details_omitted: DiagnosticText.capture(e.message, max_bytes: 1_024)
+          smith_failure_details_omitted: DiagnosticText.capture(error_message(e), max_bytes: 1_024)
         ).call
       end
     end

data/lib/smith/workflow/failure_record_validator.rb

@@ -3,6 +3,8 @@
 require "dry-initializer"
 
 require_relative "../errors"
+require_relative "../output_failure"
+require_relative "../child_runs_failed"
 require_relative "composite/branch_failure"
 
 module Smith
@@ -19,15 +21,29 @@ module Smith
         "Smith::PersistedFailureInvalid" => "persisted_failure_invalid",
         "Smith::AgentError" => "agent_error",
         "Smith::BlankAgentOutputError" => "agent_error",
+        **Smith::OutputFailure.restorers.transform_values { "output_failure" },
         "Smith::DeadlineExceeded" => "deadline_exceeded",
-        "Smith::WorkflowError" => "workflow_error",
+        "Smith::ProviderPermanentFailure" => "provider_permanent_failure",
+        "Smith::BudgetExceeded" => "budget_exceeded", "Smith::BudgetUnavailable" => "budget_exceeded",
+        "Smith::GuardrailFailed" => "guardrail_failed",
+        "Smith::WaitTimedOut" => "wait_timed_out",
+        "Smith::ChildRunsFailed" => "child_runs_failed",
+        "Smith::WorkflowError" => "workflow_error", "Smith::PersistedStateTooLarge" => "workflow_error",
         "Smith::UnresolvedTransitionError" => "workflow_error",
         "Smith::Workflow::Composite::BranchFailure" => "workflow_error"
       }.freeze
+      # Records written before these classes had their own families carry
+      # "other" and no details; they keep restoring exactly as they did.
+      LEGACY_ERROR_FAMILIES = {
+        "Smith::ProviderPermanentFailure" => "other",
+        "Smith::BudgetExceeded" => "other",
+        "Smith::GuardrailFailed" => "other"
+      }.freeze
       KNOWN_FAMILIES = %w[
         deterministic_step_failure tool_guardrail_failed tool_failure_notification_failed tool_capture_failed
         tool_outcome_uncertain tool_execution_not_admitted bounded_completion_error persisted_failure_invalid
-        deadline_exceeded agent_error workflow_error other
+        deadline_exceeded provider_permanent_failure budget_exceeded guardrail_failed agent_error workflow_error
+        wait_timed_out output_failure child_runs_failed other
       ].freeze
       RETRY_FORBIDDEN_FAMILIES = %w[
         tool_capture_failed tool_failure_notification_failed tool_outcome_uncertain tool_execution_not_admitted
@@ -40,11 +56,17 @@ module Smith
         },
         "Smith::Workflow::Composite::BranchFailure" => lambda { |details|
           Smith::Workflow::Composite::BranchFailure.from_details(details)
-        }
+        },
+        "Smith::ProviderPermanentFailure" => ->(details) { Smith::ProviderPermanentFailure.from_details(details) },
+        **[WaitTimedOut, ChildRunsFailed, PersistedStateTooLarge].to_h { [_1.name, _1.method(:from_details)] },
+        "Smith::BlankAgentOutputError" => lambda { |details|
+          Smith::BlankAgentOutputError.from_details(details) unless details.nil?
+        },
+        **Smith::OutputFailure.restorers
       }.freeze
       BOOLEAN_VALUES = [true, false].freeze
-      private_constant :KNOWN_ERROR_FAMILIES, :KNOWN_FAMILIES, :RETRY_FORBIDDEN_FAMILIES, :DETAIL_VALIDATORS,
-                       :BOOLEAN_VALUES
+      private_constant :KNOWN_ERROR_FAMILIES, :LEGACY_ERROR_FAMILIES, :KNOWN_FAMILIES, :RETRY_FORBIDDEN_FAMILIES,
+                       :DETAIL_VALIDATORS, :BOOLEAN_VALUES
 
       extend Dry::Initializer
 
@@ -74,10 +96,13 @@ module Smith
       def validate_class_family!
         expected = KNOWN_ERROR_FAMILIES[snapshot[:error_class]]
         return unless expected && family != expected
+        return if legacy_family?
 
         reject!("persisted workflow failure class and family disagree")
       end
 
+      def legacy_family? = LEGACY_ERROR_FAMILIES[snapshot[:error_class]] == family
+
       def validate_retry_policy!
         forbidden = snapshot[:error_retry_forbidden]
         return if forbidden.nil?
@@ -103,6 +128,8 @@ module Smith
       end
 
       def validate_details!
+        return if legacy_family?
+
         validator = DETAIL_VALIDATORS[snapshot[:error_class]]
         validator&.call(snapshot[:error_details])
       end

data/lib/smith/workflow/fanout_execution.rb

@@ -20,13 +20,10 @@ module Smith
         branch_agent_classes = fanout_agent_classes(transition, branches)
         run_workflow_input_guardrails
         run_fanout_agent_input_guardrails(branch_agent_classes)
-        prepared_input = build_session&.prepare!
-        output = execute_fanout_step(
-          transition,
-          branches: branches,
-          branch_agent_classes: branch_agent_classes,
-          prepared_input: prepared_input
-        )
+        prepared_input = step_prepared_input(transition)
+        return send_fanout_batch(transition, branches, branch_agent_classes, prepared_input) if batch_send?(transition)
+
+        output = execute_fanout_step(transition, branches:, branch_agent_classes:, prepared_input:)
         run_workflow_output_guardrails(output)
         output
       end
@@ -68,7 +65,7 @@ module Smith
       def guarded_fanout_branch_call(agent_class, env, signal)
         check_cancellation!(signal)
         check_deadline!
-        result = agent_class.model_configured? ? invoke_agent(agent_class, env.prepared_input) : nil
+        result = invoke_agent(agent_class, env.prepared_input)
         output = result.is_a?(AgentResult) ? result.content : result
         validate_data_volume!(output, agent_class)
         run_agent_output_guardrails(output, agent_class)

data/lib/smith/workflow/graph/batch_diagnostic.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+module Smith
+  class Workflow
+    class Graph
+      # A step that may send its requests as a batch (`mode:`) needs
+      # Smith.config.batch_queue, and agents whose calls can go as one: a
+      # model whose provider has a batch interface in Smith (Anthropic's) and
+      # no tools (a batch request is one turn). Errors for `mode: :batch`;
+      # warnings for a mode callable, which may choose :sync, and for a
+      # model or tools given by a block, known only per run.
+      class BatchDiagnostic
+        extend Dry::Initializer
+
+        param :graph
+
+        def to_a
+          graph.reachable_transitions.select(&:batches?).flat_map do |transition|
+            severity = transition.batch_mode == :batch ? :error : :warning
+            [*queue_missing(transition), *agents(transition).filter_map { unavailable(transition, _1, severity) }]
+          end
+        end
+
+        private
+
+        def agents(transition)
+          return transition.fanout_config.fetch(:branches).values if transition.fanout?
+
+          [transition.agent_name]
+        end
+
+        def queue_missing(transition)
+          return [] if Smith.config.batch_queue
+
+          [Diagnostic.new(
+            severity: :error, code: :batch_queue_missing, transition: transition.name,
+            message: "Transition #{Reference.format(transition.name)} may send its requests as a batch, which goes " \
+                     "through Smith.config.batch_queue, and none is configured.",
+            suggestion: "Set Smith.config.batch_queue to the host's queue (enqueue(custom_id:, await_token:, " \
+                        "request:, execution_key:))."
+          )]
+        end
+
+        def unavailable(transition, agent, severity)
+          agent_class = Agent::Registry.binding_for(agent)&.fetch(:agent_class)
+          return unless agent_class.respond_to?(:chat_kwargs)
+
+          reason = unavailable_reason(agent_class)
+          return unless reason
+
+          severity = :warning if agent_class.model_block || agent_class.tools.is_a?(Proc)
+          Diagnostic.new(
+            severity:, code: :batch_unavailable, transition: transition.name, target: agent,
+            message: "Transition #{Reference.format(transition.name)} may batch agent #{Reference.format(agent)}, " \
+                     "#{reason}.",
+            suggestion: "Give the agent an Anthropic model and no tools, or keep the step synchronous."
+          )
+        end
+
+        def unavailable_reason(agent_class)
+          tools = agent_class.respond_to?(:tools) ? agent_class.tools : []
+          return "which has tools (a batch request is one turn)" unless tools.respond_to?(:empty?) && tools.empty?
+
+          provider = provider_of(agent_class)
+          "whose model's provider (#{provider || "unknown"}) has no batch interface in Smith" unless
+            provider == "anthropic"
+        end
+
+        def provider_of(agent_class)
+          model, provider = agent_class.chat_kwargs.values_at(:model, :provider)
+          return provider.to_s if provider
+          return unless model
+
+          Smith::Models.find_or_infer(model)&.provider&.to_s
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/smith/workflow/graph/branch_limit_diagnostic.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+module Smith
+  class Workflow
+    class Graph
+      # A parallel or fan-out step that declares more branches than
+      # Smith.config.parallel_branch_limit allows.
+      class BranchLimitDiagnostic
+        extend Dry::Initializer
+
+        option :transition
+        option :workflow_class, optional: true
+
+        def call
+          branch_count = static_branch_count
+          limit = Smith.config.parallel_branch_limit
+          return unless branch_count && branch_count > limit
+
+          Diagnostic.new(
+            severity: :error,
+            code: :parallel_branch_limit_exceeded,
+            transition: transition.name,
+            message: "Transition #{Reference.format(transition.name)} declares #{branch_count} parallel branches, " \
+                     "exceeding the configured limit #{limit}.",
+            suggestion: "Reduce the branch count or explicitly raise Smith.config.parallel_branch_limit."
+          )
+        end
+
+        private
+
+        def static_branch_count
+          return transition.fanout_config.fetch(:branches).length if transition.fanout?
+
+          transition.parallel_count if transition.parallel?
+        end
+      end
+    end
+  end
+end

data/lib/smith/workflow/graph/budget_ledger_diagnostic.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+module Smith
+  class Workflow
+    class Graph
+      # A workflow with a `budget_ledger` holds each provider request on it,
+      # priced from the pricing catalog under the id RubyLLM resolves the
+      # model to (as holds and Smith's own usage are): an agent whose model
+      # (or fallback model) has no price there gives the ledger holds and
+      # amounts without a cost (nil), a warning. The agents are those of each
+      # step (a fan-out's branches, an optimizer's generator and evaluator,
+      # an orchestrator and its worker) and of a nested workflow without a
+      # ledger of its own, which charges this one. A model given by a block
+      # is known only per run, and is not checked. A child run (`call`, `map`,
+      # `spawn`) is a run of its own, held on its own class's ledger: one
+      # whose class names none sends its requests unheld, also a warning.
+      class BudgetLedgerDiagnostic
+        extend Dry::Initializer
+
+        param :graph
+
+        def self.declared?(workflow_class)
+          workflow_class.respond_to?(:budget_ledger) && !workflow_class.budget_ledger.nil?
+        end
+
+        def to_a
+          return [] unless self.class.declared?(graph.workflow_class)
+
+          graph.reachable_transitions.flat_map do |transition|
+            [*agents(transition, Set[graph.workflow_class]).uniq.filter_map { unpriced(transition, _1) },
+             *unbudgeted_child(transition)]
+          end
+        end
+
+        private
+
+        def agents(transition, seen)
+          [*step_agents(transition), *(nested_agents(transition.workflow_class, seen) if transition.nested?)].compact
+        end
+
+        def step_agents(transition)
+          return transition.fanout_config.fetch(:branches).values if transition.fanout?
+          return transition.optimization_config.values_at(:generator, :evaluator) if transition.optimized?
+          return transition.orchestrator_config.values_at(:orchestrator, :worker) if transition.orchestrated?
+
+          [transition.agent_name]
+        end
+
+        def unbudgeted_child(transition)
+          child = transition.children_config&.fetch(:workflow)
+          return if child.nil? || self.class.declared?(child)
+
+          name = child.name || child.inspect
+          Diagnostic.new(
+            severity: :warning, code: :child_run_unbudgeted, transition: transition.name, target: name,
+            message: "Transition #{Reference.format(transition.name)} starts runs of #{name}, which declares no " \
+                     "budget_ledger: a child run is a run of its own, so its provider requests are held on no " \
+                     "ledger and go unapproved and uncounted.",
+            suggestion: "Declare budget_ledger on #{name}, scoped by a key the parent passes in each child's " \
+                        "input (budget_ledger(:account_id) { |scope| ... })."
+          )
+        end
+
+        # A nested workflow without its own ledger charges this one.
+        def nested_agents(workflow_class, seen)
+          return [] if seen.include?(workflow_class) || self.class.declared?(workflow_class) ||
+                       !workflow_class.respond_to?(:graph)
+
+          seen << workflow_class
+          workflow_class.graph.reachable_transitions.flat_map { agents(_1, seen) }
+        end
+
+        def unpriced(transition, agent)
+          agent_class = Agent::Registry.binding_for(agent)&.fetch(:agent_class)
+          return unless agent_class.respond_to?(:chat_kwargs)
+
+          model = models(agent_class).find { |reference| !priced?(reference) }
+          return unless model
+
+          Diagnostic.new(
+            severity: :warning, code: :budget_ledger_unpriced, transition: transition.name, target: agent,
+            message: "Transition #{Reference.format(transition.name)} holds agent #{Reference.format(agent)}'s " \
+                     "requests on the workflow's budget_ledger, and its model #{model.model_id} has no price " \
+                     "in Smith.config.pricing, so their amounts carry no cost.",
+            suggestion: "Price the model in Smith.config.pricing, or have the ledger count tokens."
+          )
+        end
+
+        # The models the agent's calls are priced under: its own and its
+        # fallbacks', as RubyLLM resolves them.
+        def models(agent_class)
+          kwargs = agent_class.chat_kwargs
+          primary = kwargs[:model] && resolved(kwargs[:model], provider_of(agent_class), kwargs[:assume_model_exists])
+          [primary, *Array(agent_class.fallback_models).map { reference(Agent::ModelReference.coerce(_1)) }].compact
+        rescue StandardError
+          []
+        end
+
+        def reference(coerced) = resolved(coerced.model_id, coerced.provider&.to_s, false)
+
+        def resolved(model_id, provider, assume)
+          info = RubyLLM::Models.resolve(model_id, provider:, assume_exists: assume || false).first
+          Agent::ModelReference.new(model_id: info.id, provider: provider || info.provider.to_s)
+        rescue StandardError
+          Agent::ModelReference.new(model_id:, provider:)
+        end
+
+        def provider_of(agent_class)
+          provider = agent_class.chat_kwargs[:provider]
+          return provider.to_s if provider
+
+          Smith::Models.find_or_infer(agent_class.chat_kwargs[:model])&.provider&.to_s
+        rescue StandardError
+          nil
+        end
+
+        def priced?(reference)
+          !Pricing.compute_cost(model: reference.model_id, provider: reference.provider&.to_s, input_tokens: 0,
+                                output_tokens: 0).nil?
+        end
+      end
+    end
+  end
+end

data/lib/smith/workflow/graph/durable_retry_diagnostic.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+module Smith
+  class Workflow
+    class Graph
+      # A durable retry waits out its backoff in the store, so its longest
+      # backoff (jitter included) must end within the persistence TTL, or
+      # the stored run would expire while it waits. At runtime such a wait
+      # fails the step only after earlier attempts and waits.
+      class DurableRetryDiagnostic
+        extend Dry::Initializer
+
+        param :graph
+
+        def to_a
+          ttl = graph.workflow_class.persistence_ttl || Smith.config.persistence_ttl
+          return [] unless ttl
+
+          graph.reachable_transitions.filter_map do |transition|
+            config = transition.retry_config
+            next unless config&.fetch(:durable, false)
+
+            longest = longest_backoff(config)
+            diagnostic(transition.name, longest, ttl) if longest >= ttl
+          end
+        end
+
+        private
+
+        def longest_backoff(config)
+          attempts = config.fetch(:attempts)
+          ExponentialBackoff.new(attempts:, base_delay: config.fetch(:backoff), max_delay: config[:max_delay],
+                                 jitter: config.fetch(:jitter), delay_label: "backoff")
+                            .delay(attempts - 1, random: -> { ExponentialBackoff::MAX_RANDOM_FACTOR })
+        end
+
+        def diagnostic(name, longest, ttl)
+          Diagnostic.new(
+            severity: :error, code: :durable_retry_outlasts_ttl, transition: name,
+            message: "Transition #{Reference.format(name)} waits up to #{longest.round(3)} seconds between attempts, " \
+                     "which does not end within the persistence TTL of #{ttl} seconds.",
+            suggestion: "Lower backoff, max_delay or jitter, or raise the persistence TTL."
+          )
+        end
+      end
+    end
+  end
+end

data/lib/smith/workflow/graph/execution_successors.rb

@@ -17,7 +17,7 @@ module Smith
         end
 
         def for(transition)
-          successful_successors(transition) + failure_successors(transition)
+          successful_successors(transition) + failure_successors(transition) + timeout_successors(transition)
         end
 
         def failure_control_marker(transition)
@@ -42,15 +42,29 @@ module Smith
           successor ? [successor] : []
         end
 
+        # An await that times out continues at its `on_timeout` transition,
+        # which starts from the await's own state.
+        def timeout_successors(transition)
+          target = executable_target(transition.timeout_transition, expected_state: transition.from)
+          target ? [target] : []
+        end
+
         def successful_target_names(transition)
           return Targets.router_for(transition) if transition.routed?
 
           names = Array(transition.deterministic_routes).dup
-          name = transition.success_transition || graph.first_transition_from(transition.to)&.name
+          name = transition.success_transition
+          name ||= graph.first_transition_from(transition.to)&.name if default_successor?(transition)
           names << name if name
           names.uniq
         end
 
+        # A step declaring `routes:` reaches only its routes and `on_success`,
+        # unless it opts into `fallthrough: true`.
+        def default_successor?(transition)
+          transition.deterministic_routes.nil? || transition.deterministic_fallthrough
+        end
+
         def executable_target(name, expected_state:)
           return if name.nil?
 

data/lib/smith/workflow/graph/inherited_untrusted_diagnostics.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+module Smith
+  class Workflow
+    class Graph
+      # A nested workflow's agents, at any depth, are refused a key the
+      # nesting workflow marks untrusted. A key a nested workflow marks
+      # untrusted itself is in that workflow's own report, so it is left out
+      # here. A child run inherits only the keys its `input:` passes under
+      # the same names, which readiness cannot see, so past a map, call or
+      # spawn the refusal is a warning.
+      class InheritedUntrustedDiagnostics
+        extend Dry::Initializer
+
+        param :graph
+        # Report entries ({ transition:, workflow_class:, label: }) for the
+        # workflows this one nests, and the graphs the readiness walk built.
+        option :entries
+        option :graphs
+
+        def to_a
+          keys = UntrustedInputDiagnostic.declared_keys(graph.workflow_class)
+          return [] if keys.empty?
+
+          entries.flat_map do |entry|
+            runs = entry.fetch(:transition).child_runs?
+            reads(entry.fetch(:workflow_class), keys, {}, runs).map { |read| diagnostic(entry, *read) }
+          end
+        end
+
+        private
+
+        # [binding, key, runs] for each agent that reads a key, where runs
+        # says a map, call or spawn lies on the way to it.
+        def reads(workflow_class, keys, seen, runs)
+          nested_graph = graphs[workflow_class]
+          return [] if nested_graph.nil? || seen.key?([workflow_class, keys, runs])
+
+          seen[[workflow_class, keys, runs]] = true
+          keys -= UntrustedInputDiagnostic.declared_keys(workflow_class)
+          return [] if keys.empty?
+
+          agent_reads(nested_graph, keys, runs) + inner_reads(nested_graph, keys, seen, runs)
+        end
+
+        def inner_reads(nested_graph, keys, seen, runs)
+          inner = nested_graph.reachable_transitions.select { _1.nested? || _1.child_runs? }
+          inner.flat_map { reads(_1.target_workflow_class, keys, seen, runs || _1.child_runs?) }
+        end
+
+        def agent_reads(nested_graph, keys, runs)
+          RuntimeBindingDiagnostics.new(nested_graph).agent_bindings.filter_map do |binding|
+            key = (UntrustedInputDiagnostic.context_inputs(binding.fetch(:agent)) & keys).first
+            [binding, key, runs] if key
+          end
+        end
+
+        def diagnostic(entry, binding, key, runs)
+          name = entry.fetch(:transition).name
+          label = entry.fetch(:label)
+          Diagnostic.new(
+            severity: runs ? :warning : :error, code: :nested_untrusted_agent_input, transition: name,
+            target: label, message: "Transition #{ref(name)} #{runs ? "starts runs of" : "nests"} #{label}, where " \
+                                    "#{binding.fetch(:role)} #{ref(binding.fetch(:agent))} on transition " \
+                                    "#{ref(binding.fetch(:transition).name)} declares #{ref(key)}, which this " \
+                                    "workflow marks untrusted, as an input#{" (refused if input: passes it)" if runs}.",
+            suggestion: UntrustedInputDiagnostic.suggestion(key)
+          )
+        end
+
+        def ref(value) = Reference.format(value)
+      end
+    end
+  end
+end