smith-agents 0.11.0 → 0.12.1

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+module Smith
+  class Workflow
+    class Graph
+      # A map, call or spawn step needs a run launcher to start its runs.
+      class RunLauncherDiagnostic
+        extend Dry::Initializer
+
+        param :graph
+
+        def to_a
+          return [] if Smith.config.run_launcher
+
+          graph.reachable_transitions.select(&:child_runs?).map do |transition|
+            kind = transition.children_config.fetch(:kind)
+            Diagnostic.new(
+              severity: :error, code: :run_launcher_missing, transition: transition.name,
+              message: "Transition #{Reference.format(transition.name)} is a #{kind}, which starts runs through " \
+                       "Smith.config.run_launcher, and none is configured.",
+              suggestion: "Set Smith.config.run_launcher (Smith::Launchers::Inline runs children in process)."
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -22,7 +22,7 @@ module Smith
           end
 
           agent_class = registry_binding.fetch(:agent_class)
-          return if agent_class.model_configured?
+          return if agent_class.model_configured? || fallback_models?(agent_class)
           return required_model_diagnostic if model_required?
 
           model_warning
@@ -80,18 +80,24 @@ module Smith
           )
         end
 
+        # An agent with neither a model nor fallback models fails when its
+        # step runs.
         def model_warning
           Diagnostic.new(
-            severity: :warning,
+            severity: :error,
             code: :agent_without_model,
             transition: transition.name,
             target: agent,
             message: "Transition #{ref(transition.name)} references #{role} #{ref(agent)}, " \
                      "but the registered agent has no model configured.",
-            suggestion: "Configure a model for agent #{ref(agent)} if this transition should call a provider."
+            suggestion: "Configure a model (or fallback models) for agent #{ref(agent)}."
           )
         end
 
+        def fallback_models?(agent_class)
+          !agent_class.fallback_models_block.nil? || Array(agent_class.fallback_models).any?
+        end
+
         def agent
           binding.fetch(:agent)
         end

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

@@ -11,9 +11,13 @@ module Smith
         param :graph
 
         def to_a
-          agent_bindings.filter_map do |binding|
-            RuntimeBindingDiagnosticBuilder.new(graph, binding: binding).to_diagnostic
-          end
+          agent_bindings.flat_map do |binding|
+            [
+              RuntimeBindingDiagnosticBuilder.new(graph, binding: binding).to_diagnostic,
+              UntrustedInputDiagnostic.new(graph, binding:).call,
+              OutputSchemaDiagnostic.new(binding:).call
+            ]
+          end.compact
         end
 
         def agent_bindings

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

@@ -31,10 +31,17 @@ module Smith
             invalid_agent_bindings_count: diagnostic_count(:invalid_agent_binding),
             uninspectable_agent_bindings_count: diagnostic_count(:uninspectable_agent_binding),
             modelless_agent_bindings_count: diagnostic_count(:agent_without_model),
-            required_model_missing_count: diagnostic_count(:agent_without_required_model)
+            required_model_missing_count: diagnostic_count(:agent_without_required_model),
+            budget_ledger: budget_ledger_metric
           }
         end
 
+        # The scope keys of the workflow's budget_ledger, or nil for none.
+        def budget_ledger_metric
+          klass = graph.workflow_class
+          { scope_keys: klass.budget_ledger_scope_keys } if BudgetLedgerDiagnostic.declared?(klass)
+        end
+
         def binding_metrics
           {
             direct_agent_bindings_count: agent_bindings.length,

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

@@ -11,12 +11,13 @@ module Smith
         param :graph
         option :reports
         option :cycle_transitions
+        option :graphs, default: proc { {}.compare_by_identity }
 
         def call
           topology_report = graph.validate
           bindings = RuntimeBindingDiagnostics.new(graph)
-          nested = NestedReadinessDiagnostics.new(graph, reports:, cycle_transitions:)
-          diagnostics = [*bindings.to_a, *nested.to_a]
+          nested = NestedReadinessDiagnostics.new(graph, reports:, cycle_transitions:, graphs:)
+          diagnostics = runtime_diagnostics(bindings, nested)
           RuntimeReadinessReport.new(
             workflow_class: workflow_label,
             topology_report: topology_report,
@@ -27,6 +28,12 @@ module Smith
 
         private
 
+        def runtime_diagnostics(bindings, nested)
+          [*bindings.to_a, *RunLauncherDiagnostic.new(graph).to_a, *DurableRetryDiagnostic.new(graph).to_a,
+           *StreamDiagnostic.new(graph).to_a, *BatchDiagnostic.new(graph).to_a,
+           *BudgetLedgerDiagnostic.new(graph).to_a, *nested.to_a]
+        end
+
         def metrics(topology_report, diagnostics, bindings, nested)
           RuntimeReadinessMetrics.new(
             graph,

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

@@ -62,9 +62,9 @@ module Smith
         end
 
         def visit_child(parent_graph, transition, frames)
-          workflow_class = transition.workflow_class
+          workflow_class = transition.target_workflow_class
           case @states[workflow_class]
-          when :visiting then mark_cycle(parent_graph, transition)
+          when :visiting then mark_cycle(parent_graph, transition) unless transition.child_runs?
           when :done then nil
           else
             child_graph = graph_for(workflow_class)
@@ -78,7 +78,8 @@ module Smith
           @reports[workflow_class] = RuntimeReadinessReportBuilder.new(
             current_graph,
             reports: @reports,
-            cycle_transitions: cycles_for(current_graph)
+            cycle_transitions: cycles_for(current_graph),
+            graphs: @graphs
           ).call
           @states[workflow_class] = :done
         end
@@ -88,7 +89,9 @@ module Smith
         end
 
         def nested_transitions_for(current_graph)
-          @nested_transitions[current_graph] ||= current_graph.reachable_transitions.select(&:nested?).freeze
+          @nested_transitions[current_graph] ||= current_graph.reachable_transitions.select do |transition|
+            transition.nested? || transition.child_runs?
+          end.freeze
         end
 
         def mark_cycle(current_graph, transition)

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

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+module Smith
+  class Workflow
+    class Graph
+      # A streamed step needs its sink in Smith.config.stream_sinks (the
+      # step fails without it). An agent whose calls go to OpenAI's Responses
+      # API (asked for in its params, or chosen by Smith's tool routing under
+      # `openai_api_mode` :auto, as at runtime) is not streamed: its sink
+      # gets each reply as one delta.
+      class StreamDiagnostic
+        extend Dry::Initializer
+
+        param :graph
+
+        def to_a
+          graph.reachable_transitions.filter_map do |transition|
+            next unless transition.stream
+            next missing_sink(transition) unless Smith.config.stream_sinks.key?(transition.stream)
+
+            whole_replies(transition) if responses_route?(transition.agent_name)
+          end
+        end
+
+        private
+
+        def responses_route?(agent)
+          agent_class = Agent::Registry.binding_for(agent)&.fetch(:agent_class)
+          return false unless agent_class.respond_to?(:chat_kwargs)
+
+          profiles = static_models(agent_class).filter_map { profile(_1) }.select { _1.provider == :openai }
+          return false if profiles.empty?
+          return true if params(agent_class)[:openai_api_mode].to_s == "responses"
+
+          profiles.any? { |profile| routed?(profile, agent_class) }
+        end
+
+        # Tools given by a block are known only per run: they may route.
+        def routed?(profile, agent_class)
+          tools = agent_class.respond_to?(:tools) ? agent_class.tools : []
+          return Smith.config.openai_api_mode == :auto unless tools.is_a?(Array)
+
+          Smith::Models::ToolRouting.responses?(profile:, tools:, thinking: thinking?(agent_class))
+        end
+
+        def static_models(agent_class)
+          primary = agent_class.chat_kwargs[:model] &&
+                    Agent::ModelReference.new(model_id: agent_class.chat_kwargs[:model],
+                                              provider: agent_class.chat_kwargs[:provider])
+          fallbacks = agent_class.fallback_models_block ? [] : Array(agent_class.fallback_models)
+          [primary, *fallbacks.map { Agent::ModelReference.coerce(_1) }].compact
+        end
+
+        def profile(reference)
+          Smith::Models.find_or_infer(reference.model_id, provider: reference.provider&.to_sym)
+        rescue StandardError
+          nil
+        end
+
+        def params(agent_class)
+          params = agent_class.params if agent_class.respond_to?(:params)
+          params.is_a?(Hash) ? params.transform_keys(&:to_sym) : {}
+        end
+
+        def thinking?(agent_class)
+          configured = agent_class.thinking if agent_class.respond_to?(:thinking)
+          !configured.nil? || params(agent_class).keys.intersect?(%i[thinking reasoning reasoning_effort])
+        end
+
+        def missing_sink(transition)
+          Diagnostic.new(
+            severity: :error, code: :stream_sink_missing, transition: transition.name, target: transition.stream,
+            message: "Transition #{Reference.format(transition.name)} streams to #{transition.stream.inspect}, " \
+                     "which Smith.config.stream_sinks does not name.",
+            suggestion: "Register the sink: Smith.config.stream_sinks = { #{transition.stream.inspect} => sink }."
+          )
+        end
+
+        def whole_replies(transition)
+          Diagnostic.new(
+            severity: :warning, code: :stream_whole_replies, transition: transition.name,
+            target: transition.agent_name,
+            message: "Transition #{Reference.format(transition.name)} streams agent " \
+                     "#{Reference.format(transition.agent_name)}, whose calls go to OpenAI's Responses API, which " \
+                     "does not stream: its sink gets each reply as one delta.",
+            suggestion: "Accept whole replies there, or keep the agent on Chat Completions " \
+                        "(Smith.config.openai_api_mode = :off, and no openai_api_mode param)."
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -23,8 +23,17 @@ module Smith
         option :orchestrator_config, default: proc {}
         option :fanout_config, default: proc {}
         option :retry_config, default: proc {}
+        option :await_config, default: proc {}
+        option :timeout_transition, default: proc {}
+        option :step_input, default: proc { false }
+        option :output_to, default: proc {}
+        option :stream, default: proc {}
+        option :batch_mode, default: proc {}
+        option :on_request_change, default: proc {}
+        option :children_config, default: proc {}
         option :deterministic_kind, default: proc {}
         option :deterministic_routes, default: proc {}
+        option :deterministic_fallthrough, default: proc { false }
         option :deterministic, default: proc { false }
         option :parallel, default: proc { false }
         option :parallel_count, default: proc {}
@@ -41,6 +50,16 @@ module Smith
         def nested? = !workflow_class.nil?
         def routed? = !router_config.nil?
         def parallel? = parallel
+        def awaits? = !await_config.nil?
+        def delay? = await_config&.fetch(:kind) == :delay
+        def agent_step? = !agent_name.nil? || optimized? || orchestrated? || fanout?
+        def child_runs? = !children_config.nil?
+        def spawns? = children_config&.fetch(:kind) == :spawn
+        def batches? = !batch_mode.nil? && batch_mode != :sync
+
+        # The workflow class this step runs: nested in process, or launched
+        # as runs of their own.
+        def target_workflow_class = workflow_class || children_config&.fetch(:workflow)
       end
     end
   end

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

@@ -36,7 +36,9 @@ module Smith
           {
             success_transition: project(transition.success_transition),
             failure_transition: project(transition.failure_transition),
-            deterministic_routes: project_array(transition.deterministic_routes)
+            timeout_transition: project(transition.timeout_transition),
+            deterministic_routes: project_array(transition.deterministic_routes),
+            deterministic_fallthrough: transition.deterministic_fallthrough == true
           }
         end
 
@@ -45,10 +47,31 @@ module Smith
             deterministic_kind: transition.deterministic_kind,
             deterministic: transition.deterministic?,
             parallel: transition.parallel?,
-            parallel_count: static_parallel_count
+            parallel_count: static_parallel_count,
+            step_input: !transition.step_input.nil?,
+            output_to: transition.output_to,
+            **call_attributes,
+            children_config: children_config
           }
         end
 
+        # How the step's calls are made: streamed to a sink, and :sync,
+        # :batch or :callable (a mode chosen per attempt), and what a batch
+        # result does when the step renders another request by then.
+        def call_attributes
+          mode = transition.batch_mode
+          { stream: transition.stream, batch_mode: mode.respond_to?(:call) ? :callable : mode,
+            on_request_change: transition.on_request_change }
+        end
+
+        def children_config
+          config = transition.children_config
+          return unless config
+
+          items = config[:items].respond_to?(:call) ? :callable : config[:items]
+          config.slice(:kind, :workflow, :max_items, :collect, :on_item_failure).merge(items:).freeze
+        end
+
         def static_parallel_count
           return unless transition.parallel?
 

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

@@ -19,7 +19,8 @@ module Smith
             optimization_config: optimization_config,
             orchestrator_config: orchestrator_config,
             fanout_config: fanout_config,
-            retry_config: retry_config
+            retry_config: retry_config,
+            await_config: await_config
           }
         end
 
@@ -61,17 +62,37 @@ module Smith
           { branches: own_hash(branches) }.freeze if branches
         end
 
+        # The wait's kind, event, context key and timeout (`:callable` when
+        # the timeout is computed from the context); the block is not shown.
+        def await_config
+          config = transition.await_config
+          return unless config
+
+          timeout = config.fetch(:timeout)
+          {
+            kind: config.fetch(:kind), event: own(config[:event]), into: config[:into],
+            timeout: timeout.respond_to?(:call) ? :callable : timeout
+          }.compact.freeze
+        end
+
         def retry_config
           config = transition.retry_config
           return unless config
 
-          {
+          exported = {
             error_classes: config.fetch(:error_classes).dup.freeze,
             attempts: config.fetch(:attempts),
             backoff: config.fetch(:backoff),
             max_delay: config[:max_delay],
             jitter: config.fetch(:jitter)
-          }.freeze
+          }
+          exported.merge(optional_retry_fields(config)).freeze
+        end
+
+        def optional_retry_fields(config)
+          new_key_classes = config.fetch(:new_idempotency_key_on, [])
+          { new_idempotency_key_on: (new_key_classes.dup.freeze if new_key_classes.any?),
+            durable: (true if config[:durable]) }.compact
         end
 
         def own_hash(hash)

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

@@ -4,6 +4,10 @@ module Smith
   class Workflow
     class Graph
       class TransitionDiagnostics
+        TARGET_ATTRIBUTES = %i[success_transition failure_transition timeout_transition].freeze
+        DECLARATION_CHECKS = [
+          BranchLimitDiagnostic, RetryPolicyDiagnostic, IsolatedInputDiagnostic, OutputKeyDiagnostic
+        ].freeze
         attr_reader :graph
 
         def initialize(graph)
@@ -13,13 +17,11 @@ module Smith
         def to_a
           graph.transitions.values.flat_map do |transition|
             [
-              transition_target_diagnostic(transition, :success_transition, transition.success_transition),
-              transition_target_diagnostic(transition, :failure_transition, transition.failure_transition),
+              *TARGET_ATTRIBUTES.map { transition_target_diagnostic(transition, _1, transition.public_send(_1)) },
               *router_target_diagnostics(transition),
               *deterministic_route_diagnostics(transition),
               *target_state_mismatch_diagnostics(transition),
-              branch_limit_diagnostic(transition),
-              RetryPolicyDiagnostic.new(transition:).call
+              *declaration_diagnostics(transition)
             ].compact
           end
         end
@@ -63,29 +65,14 @@ module Smith
             transition.failure_transition,
             expected_state: transition.from
           )
+          timeout = target_state_mismatch_diagnostic(transition, transition.timeout_transition,
+                                                     expected_state: transition.from)
 
-          [*success, failure].compact
+          [*success, failure, timeout].compact
         end
 
-        def branch_limit_diagnostic(transition)
-          branch_count = static_branch_count(transition)
-          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 #{ref(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
-
-        def static_branch_count(transition)
-          return transition.fanout_config.fetch(:branches).length if transition.fanout?
-
-          transition.parallel_count if transition.parallel?
+        def declaration_diagnostics(transition)
+          DECLARATION_CHECKS.map { _1.new(transition:, workflow_class: graph.workflow_class).call }
         end
 
         def successful_target_names(transition)

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

@@ -29,14 +29,23 @@ module Smith
         option :parallel_count, default: proc {}
         option :success_transition, default: proc {}
         option :failure_transition, default: proc {}
+        option :timeout_transition, default: proc {}
         option :routes, default: proc {}
         option :fallback, default: proc {}
         option :deterministic_routes, default: proc {}
+        option :deterministic_fallthrough, default: proc {}
         option :fanout_branches, default: proc {}
         option :fanout, default: proc {}
         option :optimization, default: proc {}
         option :orchestration, default: proc {}
         option :retry_policy, default: proc {}
+        option :wait, default: proc {}
+        option :input, default: proc {}
+        option :output_to, default: proc {}
+        option :stream, default: proc {}
+        option :mode, default: proc {}
+        option :on_request_change, default: proc {}
+        option :children, default: proc {}
 
         def self.from_transition(transition, workflow_class: nil)
           new(**attributes_for(transition, workflow_class: workflow_class))
@@ -56,48 +65,56 @@ module Smith
           {
             success_transition: transition.success_transition,
             failure_transition: transition.failure_transition,
+            timeout_transition: transition.timeout_transition,
             routes: transition.router_config&.fetch(:routes, nil),
             fallback: transition.router_config&.fetch(:fallback, nil),
             deterministic_routes: transition.deterministic_routes,
+            deterministic_fallthrough: transition.deterministic_routes && transition.deterministic_fallthrough == true,
             fanout_branches: transition.fanout_config&.fetch(:branches, nil)
           }
         end
 
         def self.contract_attributes(transition, workflow_class:)
           {
-            fanout: fanout_for(transition, workflow_class: workflow_class),
-            optimization: optimization_for(transition, workflow_class: workflow_class),
-            orchestration: orchestration_for(transition, workflow_class: workflow_class),
-            retry_policy: retry_policy_for(transition)
+            fanout: FanoutContract.from_transition(transition, workflow_class:),
+            optimization: OptimizationContract.from_transition(transition, workflow_class:),
+            orchestration: OrchestrationContract.from_transition(transition, workflow_class:),
+            retry_policy: retry_policy_for(transition),
+            wait: transition.await_config,
+            input: (:callable if transition.step_input),
+            output_to: transition.output_to,
+            stream: transition.stream,
+            mode: transition.batch_mode,
+            on_request_change: transition.on_request_change,
+            children: children_for(transition)
           }
         end
 
-        def self.fanout_for(transition, workflow_class:)
-          FanoutContract.from_transition(transition, workflow_class: workflow_class)
-        end
-
-        def self.optimization_for(transition, workflow_class:)
-          OptimizationContract.from_transition(transition, workflow_class: workflow_class)
-        end
+        def self.retry_policy_for(transition)
+          config = transition.retry_config
+          return unless config
 
-        def self.orchestration_for(transition, workflow_class:)
-          OrchestrationContract.from_transition(transition, workflow_class: workflow_class)
+          new_key_classes = config.fetch(:new_idempotency_key_on, [])
+          { attempts: config.fetch(:attempts), error_classes: config.fetch(:error_classes).map(&:name),
+            backoff: config.fetch(:backoff), max_delay: config[:max_delay], jitter: config.fetch(:jitter),
+            new_idempotency_key_on: (new_key_classes.map(&:name) if new_key_classes.any?),
+            durable: (true if config[:durable]) }.compact
         end
 
-        def self.retry_policy_for(transition)
-          config = transition.retry_config
+        # A map, call or spawn: its child workflow (by name), bound, collect
+        # and failure modes, and its items (a context key, or :callable).
+        def self.children_for(transition)
+          config = transition.children_config
           return unless config
 
-          {
-            attempts: config.fetch(:attempts),
-            error_classes: config.fetch(:error_classes).map(&:name),
-            backoff: config.fetch(:backoff),
-            max_delay: config[:max_delay],
-            jitter: config.fetch(:jitter)
-          }.compact
+          workflow = config[:workflow]
+          config.merge(workflow: workflow.name || workflow.inspect)
         end
 
         def self.kind_for(transition)
+          return transition.children_config.fetch(:kind) if transition.child_runs?
+          return transition.await_config.fetch(:kind) if transition.awaits?
+
           kind = KINDS.find { |_name, predicate| transition.public_send(predicate) }
           return kind.first if kind
           return :agent if transition.agent_name
@@ -106,23 +123,7 @@ module Smith
         end
 
         def to_h
-          {
-            name: name,
-            from: from,
-            to: to,
-            kind: kind,
-            parallel_count: parallel_count,
-            success_transition: success_transition,
-            failure_transition: failure_transition,
-            routes: routes,
-            fallback: fallback,
-            deterministic_routes: deterministic_routes,
-            fanout_branches: fanout_branches,
-            fanout: fanout,
-            optimization: optimization,
-            orchestration: orchestration,
-            retry_policy: retry_policy
-          }.compact
+          self.class.dry_initializer.attributes(self).compact
         end
       end
     end

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+module Smith
+  class Workflow
+    class Graph
+      # An agent that names a context key the workflow's context marks
+      # untrusted among its `inputs` is refused at invocation.
+      class UntrustedInputDiagnostic
+        extend Dry::Initializer
+
+        param :graph
+        option :binding
+
+        # The context keys an agent reads as inputs: its declared `inputs`,
+        # without the reserved names Smith never reads from the context.
+        def self.context_inputs(agent_name)
+          agent_class = Agent::Registry.binding_for(agent_name)&.fetch(:agent_class)
+          inputs = agent_class.respond_to?(:inputs) ? Array(agent_class.inputs) : []
+          inputs - Agent::RESERVED_INPUT_NAMES
+        end
+
+        # The untrusted context keys a workflow class declares.
+        def self.declared_keys(workflow_class)
+          manager = workflow_class.context_manager if workflow_class.respond_to?(:context_manager)
+          manager.respond_to?(:untrusted_keys) ? manager.untrusted_keys : []
+        end
+
+        def self.suggestion(key)
+          "Pass #{Reference.format(key)} through the step's input:, wrapped with Smith::Untrusted.wrap."
+        end
+
+        def call
+          key = untrusted_input
+          return unless key
+
+          Diagnostic.new(
+            severity: :error, code: :untrusted_agent_input, transition: binding.fetch(:transition).name,
+            target: binding.fetch(:agent), message: message(key), suggestion: self.class.suggestion(key)
+          )
+        end
+
+        def untrusted_input
+          (self.class.context_inputs(binding.fetch(:agent)) & self.class.declared_keys(graph.workflow_class)).first
+        end
+
+        def message(key)
+          role = binding.fetch(:role)
+          "#{role[0].upcase}#{role[1..]} #{Reference.format(binding.fetch(:agent))} on transition " \
+            "#{Reference.format(binding.fetch(:transition).name)} declares untrusted context key " \
+            "#{Reference.format(key)} as an input."
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    class Graph
+      # An in-process child (a nested workflow, or a child run the launcher
+      # runs in process) that reaches a step that waits, or a nested
+      # workflow that launches runs of its own.
+      module WaitingChildDiagnostic
+        def self.build(transition, label)
+          runs = transition.child_runs?
+          verb = runs ? "starts in-process runs of" : "nests"
+          Diagnostic.new(
+            severity: :error, code: :nested_workflow_waits, transition: transition.name, target: label,
+            message: "Transition #{Reference.format(transition.name)} #{verb} #{label}, " \
+                     "which reaches a step that waits#{" or launches runs of its own" unless runs}.",
+            suggestion: "An in-process child cannot wait#{" or launch" unless runs}; move the step into the parent " \
+                        "workflow#{", or use a launcher that queues children" if runs}."
+          )
+        end
+      end
+    end
+  end
+end