smith-agents 0.10.0 → 0.12.0

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+module Smith
+  class Workflow
+    class Graph
+      # In an isolated session an agent step has no transcript to read, so it
+      # must declare `input:`; without one it fails at runtime. A nested
+      # workflow keeps its own session mode, so an isolated workflow that
+      # nests a shared one is reported too.
+      class IsolatedInputDiagnostic
+        extend Dry::Initializer
+
+        option :transition
+        option :workflow_class
+
+        def call
+          return unless isolated?(workflow_class)
+          return nested_shared_session if transition.nested?
+          return if transition.step_input || !transition.agent_step?
+
+          name = Reference.format(transition.name)
+          Diagnostic.new(
+            severity: :error, code: :isolated_step_without_input, transition: transition.name,
+            message: "Transition #{name} runs an agent in an isolated session without input:.",
+            suggestion: "Declare input: on transition #{name}, or use session :shared."
+          )
+        end
+
+        private
+
+        def isolated?(klass) = klass.respond_to?(:session) && klass.session == :isolated
+
+        def nested_shared_session
+          child = transition.workflow_class
+          return if isolated?(child)
+
+          label = child.name || child.inspect
+          Diagnostic.new(
+            severity: :warning, code: :isolated_workflow_nests_shared_session, transition: transition.name,
+            target: label,
+            message: "Transition #{Reference.format(transition.name)} nests #{label}, whose agents share a transcript.",
+            suggestion: "Declare session :isolated on #{label} if its agents should not read one another's output."
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -11,9 +11,12 @@ module Smith
         param :graph
         option :reports
         option :cycle_transitions, default: proc { {}.compare_by_identity }
+        # The graphs the readiness walk built, by workflow class.
+        option :graphs, default: proc { {}.compare_by_identity }
 
         def to_a
-          cycle_diagnostics + report_entries.flat_map { |entry| diagnostics_for(entry) }
+          cycle_diagnostics + waiting_child_diagnostics + inherited_untrusted_diagnostics +
+            report_entries.flat_map { |entry| diagnostics_for(entry) }
         end
 
         def child_reports
@@ -30,7 +33,7 @@ module Smith
 
         def cycle_diagnostics
           cycle_transitions.keys.map do |transition|
-            workflow_class = transition.workflow_class
+            workflow_class = transition.target_workflow_class
             cycle_diagnostic(transition, workflow_class)
           end
         end
@@ -39,7 +42,7 @@ module Smith
           @report_entries ||= nested_workflow_transitions.filter_map do |transition|
             next if cycle_transitions.key?(transition)
 
-            workflow_class = transition.workflow_class
+            workflow_class = transition.target_workflow_class
             report = reports[workflow_class]
             next unless report
 
@@ -52,7 +55,43 @@ module Smith
         end
 
         def nested_workflow_transitions
-          @nested_workflow_transitions ||= graph.reachable_transitions.select(&:nested?)
+          @nested_workflow_transitions ||= graph.reachable_transitions.select do |transition|
+            transition.nested? || transition.child_runs?
+          end
+        end
+
+        # An in-process child cannot wait: a nested workflow, or a child run
+        # the launcher runs in process (`inline?`), that reaches an await, a
+        # delay, a durable retry or a batch step fails its parent's step. A nested
+        # workflow cannot launch runs either, unless the launcher runs them
+        # in process; a child run of a queueing launcher is a run of its own
+        # and may wait.
+        def waiting_child_diagnostics
+          launcher = Smith.config.run_launcher
+          inline = launcher.respond_to?(:inline?) && launcher.inline? == true
+          report_entries.filter_map do |entry|
+            transition = entry.fetch(:transition)
+            next unless (transition.nested? || (inline && transition.child_runs?)) && waiting_child?(entry, inline)
+
+            WaitingChildDiagnostic.build(transition, workflow_label(entry.fetch(:workflow_class)))
+          end
+        end
+
+        def waiting_child?(entry, inline)
+          kinds = inline ? %i[await delay] : %i[await delay map call spawn]
+          entry.fetch(:report).topology_report.transitions.any? { waits?(_1, kinds) }
+        end
+
+        def waits?(snapshot, kinds)
+          kinds.include?(snapshot.kind) || snapshot.retry_policy&.dig(:durable) == true ||
+            %i[batch callable].include?(snapshot.mode)
+        end
+
+        def inherited_untrusted_diagnostics
+          entries = report_entries.map do |entry|
+            entry.merge(label: workflow_label(entry.fetch(:workflow_class)))
+          end
+          InheritedUntrustedDiagnostics.new(graph, entries:, graphs:).to_a
         end
 
         def cycle_diagnostic(transition, workflow_class)

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+module Smith
+  class Workflow
+    class Graph
+      # A step's `output_to:` key, or an await's `into:` key, that an explicit
+      # `persist` list leaves out fails the step at runtime.
+      class OutputKeyDiagnostic
+        extend Dry::Initializer
+
+        option :transition
+        option :workflow_class
+
+        def call
+          option, key = output_key
+          return unless key
+
+          keys = persisted_keys
+          return if keys.nil? || keys.include?(key)
+
+          Diagnostic.new(
+            severity: :error, code: :"#{option}_not_persisted", transition: transition.name, target: key,
+            message: "Transition #{Reference.format(transition.name)} writes #{Reference.format(key)} " \
+                     "(#{option}:), which the context's persist list leaves out.",
+            suggestion: "Add #{Reference.format(key)} to the context's persist list."
+          )
+        end
+
+        private
+
+        def output_key
+          return [:output_to, transition.output_to] if transition.output_to
+
+          into = transition.await_config&.fetch(:into, nil)
+          [:await_into, into] if into
+        end
+
+        # The explicit list, or nil when the workflow has none or uses
+        # `persist :auto`.
+        def persisted_keys
+          manager = workflow_class.context_manager if workflow_class.respond_to?(:context_manager)
+          return unless manager.respond_to?(:persist)
+          return if manager.respond_to?(:persist_mode) && manager.persist_mode == :auto
+
+          keys = manager.persist
+          keys.empty? ? nil : keys
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+module Smith
+  class Workflow
+    class Graph
+      # An agent declared for Anthropic whose output schema Anthropic's
+      # structured outputs cannot take (an object that allows other
+      # properties or declares none) fails before its call.
+      class OutputSchemaDiagnostic
+        extend Dry::Initializer
+
+        option :binding
+
+        def call
+          agent_class = Agent::Registry.binding_for(binding.fetch(:agent))&.fetch(:agent_class)
+          payload = anthropic_schema(agent_class)
+          return unless payload
+
+          Providers::SchemaConstraints.for_provider(payload, "anthropic")
+          nil
+        rescue Smith::WorkflowError => e
+          diagnostic(e)
+        end
+
+        private
+
+        def anthropic_schema(agent_class)
+          return unless agent_class.respond_to?(:chat_kwargs) && agent_class.chat_kwargs[:provider].to_s == "anthropic"
+
+          schema = agent_class.output_schema || (agent_class.schema if agent_class.respond_to?(:schema))
+          Providers::SchemaConstraints.json_schema(schema) if schema && !schema.is_a?(Proc)
+        end
+
+        def diagnostic(error)
+          agent = binding.fetch(:agent)
+          Diagnostic.new(
+            severity: :error, code: :output_schema_unsupported, transition: binding.fetch(:transition).name,
+            target: agent,
+            message: "Agent #{Reference.format(agent)} declares an output schema Anthropic cannot take: " \
+                     "#{error.message}.",
+            suggestion: "Give every object in the schema its properties and additionalProperties: false."
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -9,6 +9,7 @@ module Smith
         extend Dry::Initializer
 
         option :transition
+        option :workflow_class, optional: true
 
         def call
           attempts = transition.retry_config&.fetch(:attempts, nil)

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)