smith-agents 0.11.0 → 0.12.0

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

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)