smith-agents 0.4.1 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fce22e9b87caf5c01417a5e7d8fe7a6f4ee179abebc61644074400452a078791
-  data.tar.gz: e7d2ae59746ff545f5d45215bcec20dea95ee82a37d7fa765c4ded95484d4029
+  metadata.gz: 1c5a7f554819eb342aa2284fb010eba8126f22fba1348683a36fbc4fa9d5383f
+  data.tar.gz: b72e10a5415340c5b337751c0cc92f2f59ed0ddb62850e03746df217be374721
 SHA512:
-  metadata.gz: 8d8515c459487f57c20301581e6f1d5cc786f8bfe7089b4e628548145ac56e0c9c93e9560ac37f1fa7818f95a71a1c8753cb275267b341fb39ca4bf63d5e5f3e
-  data.tar.gz: b3e05ca16fc7fec62e8172d9d6ccb84b0bc3f7546af22b9f47c8a36ce4b7e6e5bfb35b0fb47eb51c0b86cf4ab4fbe47e651406c1666fcc63d4b2c16b0ccb0bf9
+  metadata.gz: 75d149a61196f2c0cd22748ff6d5a6c4530bc9d91c61b163c027e44d555b9fd0f1ca5ef0a283c6025d6906b6d984923265fba05190fa3da37a60cfe864e5f6f8
+  data.tar.gz: 906bc56189df0f84ad62cb643ed8141a05780a328bf9a3770db55c575d71db86b94ad39e91517ba0e2d76f05942f84358dc234b2e685ad0701dba059bed65d36

data/CHANGELOG.md

@@ -8,6 +8,42 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Version
 
 No unreleased changes.
 
+## [0.4.2] - 2026-07-02
+
+Patch release for bounded fan-out and retry workflow primitives. This remains
+workflow-first and host-owned: Smith executes declared transitions and exposes
+inspection metadata, while durable scheduling, long waits, tool adapter
+contracts, and deployment packaging stay with the host application.
+
+### Added
+
+- `fan_out branches: {...}` transition DSL for bounded heterogeneous
+  multi-agent fan-out with stable branch keys and named aggregate results.
+- `retry_on` transition DSL for bounded local retries using explicit error
+  classes or Smith's built-in retryability classifier.
+- Graph inspection metadata for `:fanout` transitions and retry policy details.
+
+### Changed
+
+- Fan-out branch execution preserves branch identity, branch-specific budgets,
+  agent guardrails, tool guardrails, deadlines, and usage accounting.
+- Parallel/fan-out failure handling now prefers the initiating branch error over
+  cooperative cancellation errors.
+- Failed-but-billable provider attempts are included in budget reconciliation
+  for retry, fallback, and fan-out settlement paths.
+- Retry `max_delay` remains a hard cap even when jitter is configured.
+
+### Test coverage
+
+- Default suite: 880 examples, 0 failures.
+- Practical gem-level execution probe covering heterogeneous `fan_out`,
+  same-agent parallel execution, `retry_on`, failed-but-billable budget
+  settlement, cancellation cause preservation, branch input guardrail ordering
+  before session preparation, graph metadata, and invalid declaration rejection.
+- Added focused coverage for heterogeneous fan-out, retry policies,
+  failed-but-billable retry budget accounting, cancellation cause preservation,
+  and graph inspection metadata.
+
 ## [0.4.1] - 2026-06-28
 
 Patch release for static workflow graph inspection. This is additive and diagnostic-only: Smith exposes declared workflow topology for hosts to render, lint, or cache without executing agents, advancing state, owning progress projection, or changing durability/recovery boundaries.

data/README.md

@@ -5,11 +5,19 @@ Workflow-first multi-agent orchestration for Ruby. Smith sits on top of `RubyLLM
 > [!WARNING]
 > Smith is pre-1.0. Expect contract tightening between minor versions. Pin to an exact version in production.
 
+## Verification Discipline
+
+Tests are required, but they are never enough for runtime primitive changes.
+Every Smith workflow slice must also run practical gem-level execution probes.
+When a host application consumes unreleased Smith changes, point that host app at
+the local Smith repository and exercise the changed workflow paths in the host
+environment before calling the slice complete.
+
 ## Installation
 
 ```ruby
 # Gemfile
-gem "smith-agents", "~> 0.2.0", require: "smith"
+gem "smith-agents", "~> 0.4.2", require: "smith"
 ```
 
 ```bash
@@ -87,6 +95,7 @@ end
 | Pipeline | sequential transitions | Multi-step workflow with explicit success/failure routing. |
 | Router | `route :classifier, routes: {...}` | Branch on a classifier agent's output. |
 | Parallel fan-out | `execute :agent, parallel: true` | Concurrent agent calls under one ledger. |
+| Heterogeneous fan-out | `fan_out branches: {...}` | Concurrent calls to different agents with named branch results. |
 | Nested workflow | `workflow OtherWorkflow` | Reuse a subflow as one transition. |
 | Evaluator-Optimizer | `optimize generator:, evaluator:, ...` | Generate-then-critique refinement loops. |
 | Orchestrator-Worker | `orchestrate orchestrator:, worker:, ...` | Dynamic task fan-out with delegation rounds. |
@@ -230,6 +239,19 @@ Smith::Errors.retryable_classes
 # => [Smith::AgentError, Smith::DeadlineExceeded]  (for ActiveJob retry_on)
 ```
 
+Workflow transitions can also declare a bounded local retry policy:
+
+```ruby
+transition :draft, from: :idle, to: :done do
+  execute :writer
+  retry_on Smith::AgentError, attempts: 3, backoff: 0.1, max_delay: 1.0
+end
+```
+
+When no classes are passed, `retry_on` uses `Smith::Errors.retryable?`.
+This is a bounded local transition retry policy. Durable scheduling, long waits,
+and external idempotency guarantees remain host-owned.
+
 ## Development
 
 ```bash
@@ -238,4 +260,5 @@ bundle exec rspec
 bundle exec rubocop
 ```
 
-770 examples, MIT licensed. See [`CHANGELOG.md`](CHANGELOG.md) for the 0.2.0 surface and [`UPSTREAM_PROPOSAL.md`](UPSTREAM_PROPOSAL.md) for the vendored Responses adapter retirement path.
+880 examples, MIT licensed. See [`CHANGELOG.md`](CHANGELOG.md) for the current
+release surface.

data/docs/PATTERNS.md

@@ -239,7 +239,47 @@ Why this is valuable:
 - branch failures discard step output and route through normal failure handling
 - prepared input is reused consistently across branches
 
-## Example 6: Nested Workflows
+## Example 6: Heterogeneous Fan-Out
+
+Use heterogeneous fan-out when different specialists should run concurrently and return named branch results under one workflow transition.
+
+```ruby
+class StaticReviewAgent < Smith::Agent
+  register_as :static_review_agent
+  model "gpt-4.1-nano"
+end
+
+class SecurityReviewAgent < Smith::Agent
+  register_as :security_review_agent
+  model "gpt-4.1-nano"
+end
+
+class CodeReviewWorkflow < Smith::Workflow
+  initial_state :idle
+  state :reviewed
+  state :failed
+
+  transition :review, from: :idle, to: :reviewed do
+    fan_out branches: {
+      static: :static_review_agent,
+      security: :security_review_agent
+    }
+    on_failure :fail
+  end
+end
+```
+
+What you get:
+
+- stable branch identity in the step output
+- branch-specific agent budgets, guardrails, tools, and model configuration
+- one shared prepared input for the transition
+- one shared transition result, so downstream joins remain explicit in the workflow
+- branch failures discard partial output and route through normal failure handling
+
+Use same-agent `parallel: true` for repeated homogeneous work. Use `fan_out` when branches are different agents with different responsibilities.
+
+## Example 7: Nested Workflows
 
 Use nested workflows when one part of the system deserves to be a reusable subflow with its own states and transitions.
 
@@ -281,7 +321,7 @@ What you get:
 - nested best-known token/cost totals roll up into the parent result
 - artifact scope is preserved across nesting
 
-## Example 7: Evaluator-Optimizer
+## Example 8: Evaluator-Optimizer
 
 Use `optimize` when one agent generates candidates and another agent evaluates whether the result is acceptable.
 
@@ -335,7 +375,7 @@ Why this matters:
 - exhaustion, malformed evaluator output, and convergence without acceptance fail normally
 - costs and token usage from the full loop roll into the workflow totals
 
-## Example 8: Orchestrator-Worker
+## Example 9: Orchestrator-Worker
 
 Use `orchestrate` when you need an orchestrator that can emit structured tasks for workers and later decide when the system is done.
 
@@ -489,4 +529,3 @@ The yielded step object exposes a narrow, read-heavy surface:
 - **Persistence**: Context writes and written outcomes survive `to_state`/`from_state`. The block itself (a Proc) lives on the class-level Transition and is never serialized.
 - **Trace**: Emits `:deterministic_step` traces for start, success/routed, and failure. When a step writes an outcome, the trace includes `outcome_kind`.
 - **Mutual exclusivity**: `compute` and `run` cannot be combined with `execute`, `route`, `workflow`, `optimize`, or `orchestrate`. A transition declares exactly one primary execution body.
-

data/lib/smith/agent/lifecycle.rb

@@ -46,10 +46,10 @@ module Smith
 
       def build_model_chain(agent_class)
         primary = if agent_class.respond_to?(:model_block) && agent_class.model_block
-          resolve_dynamic_model(agent_class)
-        else
-          agent_class.chat_kwargs[:model]
-        end
+                    resolve_dynamic_model(agent_class)
+                  else
+                    agent_class.chat_kwargs[:model]
+                  end
         fallbacks = agent_class.fallback_models || []
         [primary, *fallbacks].compact
       end
@@ -103,8 +103,8 @@ module Smith
 
         declared = agent_class.inputs || []
         user_declared = declared - Smith::Agent::RESERVED_INPUT_NAMES
-        user_declared.each_with_object({}) do |name, kwargs|
-          kwargs[name] = @context[name]
+        user_declared.to_h do |name|
+          [name, @context[name]]
         end
       end
 
@@ -131,7 +131,9 @@ module Smith
 
         combined_contents = existing_system_contents + prepared_system_contents
         return if combined_contents.empty?
-        return prepared_system_messages.each { |message| chat.add_message(message) } unless combined_contents.all?(String)
+        unless combined_contents.all?(String)
+          return prepared_system_messages.each { |message| chat.add_message(message) }
+        end
 
         if chat.respond_to?(:with_instructions)
           chat.with_instructions(combined_contents.join("\n\n"))
@@ -178,6 +180,8 @@ module Smith
         agent_result = Workflow::AgentResult.new(
           content: nil, input_tokens: input, output_tokens: output, cost: cost, model_used: model_id
         )
+        Thread.current[:smith_failed_agent_results] ||= []
+        Thread.current[:smith_failed_agent_results] << agent_result
         record_usage(agent_class, agent_result, :failed_attempt, model_id)
       end
 

data/lib/smith/version.rb

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

data/lib/smith/workflow/budget_integration.rb

@@ -30,19 +30,33 @@ module Smith
       def reconcile_branch_budget(ledger, estimates, agent_result: nil)
         return unless ledger && estimates
 
-        actuals = extract_actuals(agent_result)
+        actuals = extract_actuals(agent_results_for_settlement(agent_result))
         estimates.each do |dim, amt|
           ledger.reconcile!(dim, amt, actual_for_dimension(dim, actuals[:tokens], actuals[:cost]))
         end
       end
 
-      def extract_actuals(agent_result)
+      def extract_actuals(agent_results)
+        results = Array(agent_results).compact
+
         {
-          tokens: (agent_result&.input_tokens || 0) + (agent_result&.output_tokens || 0),
-          cost: agent_result&.cost || 0
+          tokens: results.sum { |result| (result.input_tokens || 0) + (result.output_tokens || 0) },
+          cost: results.sum { |result| result.cost || 0 }
         }
       end
 
+      def agent_results_for_settlement(agent_result = nil)
+        [*failed_billable_attempts, agent_result].compact
+      end
+
+      def failed_billable_attempts
+        Array(Thread.current[:smith_failed_agent_results])
+      end
+
+      def clear_failed_billable_attempts
+        Thread.current[:smith_failed_agent_results] = []
+      end
+
       def actual_for_dimension(dim, actual_tokens, actual_cost = 0)
         return actual_tokens if TOKEN_DIMENSIONS.include?(dim)
         return actual_cost if COST_DIMENSIONS.include?(dim)
@@ -59,7 +73,7 @@ module Smith
       def settle_budget_on_failure(ledger, estimates, agent_result)
         return unless ledger && estimates
 
-        if agent_result
+        if agent_result || failed_billable_attempts.any?
           reconcile_branch_budget(ledger, estimates, agent_result: agent_result)
         else
           release_branch_budget(ledger, estimates)
@@ -85,6 +99,12 @@ module Smith
         { branch: index, agent: transition.agent_name, output: agent_result ? agent_result.content : result }
       end
 
+      def finalize_named_branch(branch_key, agent_name, result, ledger, reserved)
+        agent_result = result.is_a?(Workflow::AgentResult) ? result : nil
+        reconcile_branch_budget(ledger, reserved, agent_result: agent_result)
+        { branch: branch_key, agent: agent_name, output: agent_result ? agent_result.content : result }
+      end
+
       def estimate_for_dimension(dim, limit, branch_count)
         return 0 unless BUDGET_DIMENSIONS.include?(dim)
 

data/lib/smith/workflow/evaluator_optimizer.rb

@@ -91,7 +91,7 @@ module Smith
         when Hash
           deep_symbolize_evaluation(evaluation)
         when String
-          parsed = (JSON.parse(evaluation, symbolize_names: true) rescue nil)
+          parsed = parse_evaluation_json(evaluation)
           parsed.is_a?(Hash) ? parsed : evaluation
         else
           evaluation
@@ -155,9 +155,12 @@ module Smith
 
       def invoke_agent_with_budget(agent_class, prepared_input)
         Thread.current[:smith_last_agent_result] = nil
+        clear_failed_billable_attempts
         with_agent_context(agent_class) do
           invoke_with_call_ledger(agent_class, prepared_input)
         end
+      ensure
+        clear_failed_billable_attempts
       end
 
       def invoke_with_call_ledger(agent_class, prepared_input)
@@ -179,12 +182,20 @@ module Smith
       # routes through on_threshold and returns the resulting value
       # (non-nil terminates the loop with that as the step output).
       def check_improvement_threshold!(evaluation, state, round)
-        return nil unless stop_for_threshold?(evaluation[:score], state.last_score, state.config[:improvement_threshold])
+        unless stop_for_threshold?(evaluation[:score], state.last_score, state.config[:improvement_threshold])
+          return nil
+        end
 
         handle_exit(state, :on_threshold,
                     "optimization improvement below threshold after round #{round + 1}")
       end
 
+      def parse_evaluation_json(evaluation)
+        JSON.parse(evaluation, symbolize_names: true)
+      rescue JSON::ParserError
+        nil
+      end
+
       def prepare_generator_input(prepared_input, round, prior_candidate, feedback)
         return prepared_input if round.zero?
 

data/lib/smith/workflow/execution.rb

@@ -8,13 +8,15 @@ module Smith
       include EvaluatorOptimizer
       include OrchestratorWorker
       include ParallelExecution
+      include FanoutExecution
+      include RetryExecution
       include DeterministicExecution
 
       private
 
       def execute_step(transition)
         setup_step_context
-        output = with_scoped_artifacts { run_guarded_step(transition) }
+        output = with_scoped_artifacts { run_with_retry_policy(transition) }
         complete_step(transition, output)
       rescue StandardError => e
         @outcome = nil
@@ -40,6 +42,7 @@ module Smith
 
       def run_guarded_step(transition)
         return dispatch_step(transition) if transition.deterministic?
+        return run_guarded_fanout_step(transition) if transition.fanout?
 
         agent_class = resolve_agent_class(transition)
         run_input_guardrails(agent_class)
@@ -93,6 +96,7 @@ module Smith
 
       def execute_serial_step(transition, prepared_input: nil)
         Thread.current[:smith_last_agent_result] = nil
+        clear_failed_billable_attempts
         ledger = effective_call_ledger
         reserved = reserve_for_serial(transition, ledger)
         begin
@@ -104,6 +108,7 @@ module Smith
         ensure
           settle_budget_on_failure(ledger, reserved, Thread.current[:smith_last_agent_result]) if reserved
           Thread.current[:smith_last_agent_result] = nil
+          clear_failed_billable_attempts
         end
       end
 

data/lib/smith/workflow/fanout_execution.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module FanoutExecution
+      private
+
+      def run_guarded_fanout_step(transition)
+        branches = transition.fanout_config.fetch(:branches)
+        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
+        )
+        run_workflow_output_guardrails(output)
+        output
+      end
+
+      def execute_fanout_step(transition, branches: nil, branch_agent_classes: nil, prepared_input: nil)
+        branches ||= transition.fanout_config.fetch(:branches)
+        branch_agent_classes ||= fanout_agent_classes(transition, branches)
+        env = BranchEnv.new(
+          prepared_input: prepared_input,
+          guardrail_sources: nil,
+          scoped_store: propagate_scoped_artifacts,
+          branch_estimates: fanout_branch_estimates(branches, branch_agent_classes),
+          deadline: wall_clock_deadline
+        )
+
+        branch_calls = branches.map do |branch_key, agent_name|
+          proc do |signal|
+            run_fanout_branch(branch_key, agent_name, branch_agent_classes.fetch(branch_key), env, signal)
+          end
+        end
+
+        Parallel.execute(branches: branch_calls)
+      end
+
+      def run_fanout_branch(branch_key, agent_name, agent_class, env, signal)
+        setup_fanout_branch_context(env, @ledger, agent_class)
+
+        with_agent_context(agent_class) do
+          branch_ledger = effective_call_ledger
+          reserved = reserve_fanout_branch_call(branch_ledger, env.branch_estimates[branch_key], agent_class)
+          begin
+            result = guarded_fanout_branch_call(agent_class, env, signal)
+            finalize_named_branch(branch_key, agent_name, result, branch_ledger, reserved).tap { reserved = nil }
+          ensure
+            settle_budget_on_failure(branch_ledger, reserved, Thread.current[:smith_last_agent_result]) if reserved
+          end
+        end
+      ensure
+        teardown_branch_context(env)
+      end
+
+      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
+        output = result.is_a?(AgentResult) ? result.content : result
+        validate_data_volume!(output, agent_class)
+        run_agent_output_guardrails(output, agent_class)
+        check_cancellation!(signal)
+        result
+      end
+
+      def setup_fanout_branch_context(env, ledger, agent_class)
+        setup_branch_context(env, ledger)
+        apply_tool_guardrails(agent_class)
+      end
+
+      def reserve_fanout_branch_call(branch_ledger, branch_estimates, agent_class)
+        return reserve_branch_budget(branch_ledger, branch_estimates: branch_estimates) if @ledger
+
+        reserve_serial_budget(branch_ledger, agent_budget: agent_class&.budget) if branch_ledger
+      end
+
+      def fanout_agent_classes(transition, branches)
+        branches.to_h do |branch_key, agent_name|
+          [branch_key, resolve_fanout_agent_class(transition, agent_name)]
+        end
+      end
+
+      def run_fanout_agent_input_guardrails(branch_agent_classes)
+        branch_agent_classes.each_value do |agent_class|
+          run_agent_input_guardrails(agent_class)
+        end
+      end
+
+      def fanout_branch_estimates(branches, branch_agent_classes)
+        return {} unless @ledger
+
+        branch_count = branches.length
+        branches.each_with_object({}) do |(branch_key, _agent_name), map|
+          agent_class = branch_agent_classes.fetch(branch_key)
+          map[branch_key] = compute_branch_estimates(
+            @ledger,
+            branch_count: branch_count,
+            agent_budget: agent_class&.budget
+          )
+        end
+      end
+
+      def resolve_fanout_agent_class(transition, agent_name)
+        Agent::Registry.fetch!(
+          agent_name,
+          workflow_class: self.class,
+          transition_name: transition&.name,
+          role: :fanout_agent
+        )
+      end
+    end
+  end
+end

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

@@ -10,10 +10,12 @@ module Smith
           %i[nested_workflow nested?],
           %i[optimizer optimized?],
           %i[orchestrator orchestrated?],
+          %i[fanout fanout?],
           %i[parallel parallel?]
         ].freeze
 
-        attr_reader :name, :from, :to, :kind, :success_transition, :failure_transition, :routes, :fallback
+        attr_reader :name, :from, :to, :kind, :success_transition, :failure_transition, :routes, :fallback,
+                    :fanout_branches, :retry_policy
 
         def self.from_transition(transition)
           new(
@@ -24,10 +26,25 @@ module Smith
             success_transition: transition.success_transition,
             failure_transition: transition.failure_transition,
             routes: transition.router_config&.fetch(:routes, nil),
-            fallback: transition.router_config&.fetch(:fallback, nil)
+            fallback: transition.router_config&.fetch(:fallback, nil),
+            fanout_branches: transition.fanout_config&.fetch(:branches, nil),
+            retry_policy: retry_policy_for(transition)
           )
         end
 
+        def self.retry_policy_for(transition)
+          config = transition.retry_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
+        end
+
         def self.kind_for(transition)
           kind = KINDS.find { |_name, predicate| transition.public_send(predicate) }
           return kind.first if kind
@@ -45,6 +62,8 @@ module Smith
           @failure_transition = attributes[:failure_transition]
           @routes = attributes[:routes]
           @fallback = attributes[:fallback]
+          @fanout_branches = attributes[:fanout_branches]
+          @retry_policy = attributes[:retry_policy]
         end
 
         def to_h
@@ -56,7 +75,9 @@ module Smith
             success_transition: success_transition,
             failure_transition: failure_transition,
             routes: routes,
-            fallback: fallback
+            fallback: fallback,
+            fanout_branches: fanout_branches,
+            retry_policy: retry_policy
           }.compact
         end
       end

data/lib/smith/workflow/guardrail_integration.rb

@@ -6,34 +6,52 @@ module Smith
       private
 
       def apply_tool_guardrails(agent_class)
-        sources = [self.class.guardrails, agent_class&.guardrails].compact
+        sources = tool_guardrail_sources(agent_class)
         Tool.current_guardrails = sources.empty? ? nil : sources
       end
 
       def run_input_guardrails(agent_class)
+        run_workflow_input_guardrails
+        run_agent_input_guardrails(agent_class)
+      end
+
+      def run_output_guardrails(output, agent_class)
+        run_workflow_output_guardrails(output)
+        run_agent_output_guardrails(output, agent_class)
+      end
+
+      def handle_step_failure(transition, _error)
+        failure_name = transition.failure_transition
+        return unless failure_name
+
+        fail_transition = self.class.find_transition(failure_name)
+        return unless fail_transition
+
+        @state = fail_transition.to
+      end
+
+      def run_workflow_input_guardrails
         wf_guardrails = self.class.guardrails
         Guardrails::Runner.run_inputs(wf_guardrails, @context) if wf_guardrails
+      end
 
+      def run_agent_input_guardrails(agent_class)
         agent_guardrails = agent_class&.guardrails
         Guardrails::Runner.run_inputs(agent_guardrails, @context) if agent_guardrails
       end
 
-      def run_output_guardrails(output, agent_class)
+      def run_workflow_output_guardrails(output)
         wf_guardrails = self.class.guardrails
         Guardrails::Runner.run_outputs(wf_guardrails, output) if wf_guardrails
+      end
 
+      def run_agent_output_guardrails(output, agent_class)
         agent_guardrails = agent_class&.guardrails
         Guardrails::Runner.run_outputs(agent_guardrails, output) if agent_guardrails
       end
 
-      def handle_step_failure(transition, _error)
-        failure_name = transition.failure_transition
-        return unless failure_name
-
-        fail_transition = self.class.find_transition(failure_name)
-        return unless fail_transition
-
-        @state = fail_transition.to
+      def tool_guardrail_sources(agent_class)
+        [self.class.guardrails, agent_class&.guardrails].compact
       end
     end
   end

data/lib/smith/workflow/orchestrator_worker.rb

@@ -23,7 +23,8 @@ module Smith
       private
 
       def dispatch_step(transition, prepared_input: nil)
-        if transition.parallel? then execute_parallel_step(transition, prepared_input: prepared_input)
+        if transition.fanout? then execute_fanout_step(transition, prepared_input: prepared_input)
+        elsif transition.parallel? then execute_parallel_step(transition, prepared_input: prepared_input)
         elsif transition.nested? then execute_nested_workflow(transition)
         elsif transition.optimized? then execute_optimization_step(transition, prepared_input: prepared_input)
         elsif transition.orchestrated? then execute_orchestration_step(transition, prepared_input: prepared_input)

data/lib/smith/workflow/parallel/cancellation.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    class Parallel
+      class Cancellation < WorkflowError; end
+    end
+  end
+end

data/lib/smith/workflow/parallel.rb

@@ -39,12 +39,17 @@ module Smith
         fulfilled, values, reasons = Concurrent::Promises.zip(*futures).result
 
         unless fulfilled
-          error = reasons.compact.first
+          error = preferred_error(reasons)
           raise error
         end
 
         values
       end
+
+      def self.preferred_error(reasons)
+        errors = reasons.compact
+        errors.find { |error| !error.is_a?(Cancellation) } || errors.first
+      end
     end
   end
 end

data/lib/smith/workflow/parallel_execution.rb

@@ -50,10 +50,12 @@ module Smith
         Tool.current_ledger = ledger
         Tool.current_tool_result_collector = tool_result_collector
         Thread.current[:smith_last_agent_result] = nil
+        clear_failed_billable_attempts
       end
 
       def teardown_branch_context(env)
         Thread.current[:smith_last_agent_result] = nil
+        clear_failed_billable_attempts
         Tool.current_ledger = nil
         Tool.current_tool_result_collector = nil
         env.teardown_thread
@@ -68,7 +70,7 @@ module Smith
       end
 
       def check_cancellation!(signal)
-        raise Smith::WorkflowError, "cancelled" if signal.cancelled?
+        raise Parallel::Cancellation, "cancelled" if signal.cancelled?
       end
     end
   end

data/lib/smith/workflow/retry_execution.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module RetryExecution
+      private
+
+      def run_with_retry_policy(transition)
+        config = transition.retry_config
+        return run_guarded_step(transition) unless config
+
+        attempt = 0
+        begin
+          attempt += 1
+          run_guarded_step(transition)
+        rescue StandardError => e
+          raise unless retry_transition_error?(config, e, attempt)
+
+          sleep_for_retry(config, attempt)
+          retry
+        end
+      end
+
+      def retry_transition_error?(config, error, attempt)
+        return false if attempt >= config.fetch(:attempts)
+
+        classes = config.fetch(:error_classes)
+        if classes.any?
+          classes.any? { |error_class| error.is_a?(error_class) }
+        else
+          Smith::Errors.retryable?(error)
+        end
+      end
+
+      def sleep_for_retry(config, failed_attempt)
+        delay = retry_delay(config, failed_attempt)
+        sleep(delay) if delay.positive?
+      end
+
+      def retry_delay(config, failed_attempt)
+        delay = config.fetch(:backoff) * (2**[failed_attempt - 1, 0].max)
+        max_delay = config[:max_delay]
+        delay = [delay, max_delay].min if max_delay
+
+        jitter = config.fetch(:jitter)
+        delay += rand * jitter if jitter.positive?
+        delay = [delay, max_delay].min if max_delay
+        delay
+      end
+    end
+  end
+end

data/lib/smith/workflow/transition.rb

@@ -5,7 +5,7 @@ module Smith
     class Transition
       attr_reader :name, :from, :to, :agent_name, :agent_opts, :success_transition, :failure_transition,
                   :router_config, :workflow_class, :optimization_config, :orchestrator_config,
-                  :deterministic_block, :deterministic_kind
+                  :fanout_config, :retry_config, :deterministic_block, :deterministic_kind
 
       def initialize(name, from:, to:, &)
         @name = name
@@ -15,7 +15,7 @@ module Smith
       end
 
       def execute(agent_name, **opts)
-        raise WorkflowError, "transition cannot declare both execute and compute/run" if @deterministic_block
+        validate_execute_conflicts!
 
         @agent_name = agent_name
         @agent_opts = opts
@@ -30,7 +30,7 @@ module Smith
       end
 
       def route(agent_name, routes:, confidence_threshold:, fallback:)
-        raise WorkflowError, "transition cannot declare both route and compute/run" if @deterministic_block
+        validate_route_conflicts!
 
         @agent_name = agent_name
         @router_config = { routes: routes, confidence_threshold: confidence_threshold, fallback: fallback }
@@ -39,9 +39,16 @@ module Smith
       def workflow(klass)
         raise WorkflowError, "workflow binding must be a Class" unless klass.is_a?(Class)
         raise WorkflowError, "workflow binding must be a Smith::Workflow subclass" unless klass < Workflow
-        raise WorkflowError, "transition cannot declare both workflow and execute" if @agent_name && !@router_config
-        raise WorkflowError, "transition cannot declare both workflow and route" if @router_config
-        raise WorkflowError, "transition cannot declare both workflow and compute/run" if @deterministic_block
+
+        validate_conflicts!(
+          "workflow",
+          [
+            ["execute", @agent_name && !@router_config],
+            ["route", @router_config],
+            ["compute/run", @deterministic_block],
+            ["fan_out", @fanout_config]
+          ]
+        )
 
         @workflow_class = klass
       end
@@ -77,6 +84,25 @@ module Smith
         @orchestrator_config = opts
       end
 
+      def fan_out(branches:)
+        validate_fanout_conflicts!
+
+        @fanout_config = { branches: normalize_fanout_branches!(branches) }
+      end
+      alias fanout fan_out
+
+      def retry_on(*error_classes, attempts:, backoff: 0, max_delay: nil, jitter: 0)
+        validate_retry_controls!(error_classes, attempts:, backoff:, max_delay:, jitter:)
+
+        @retry_config = {
+          error_classes: error_classes.freeze,
+          attempts: attempts,
+          backoff: Float(backoff),
+          max_delay: max_delay.nil? ? nil : Float(max_delay),
+          jitter: Float(jitter)
+        }.freeze
+      end
+
       %i[compute run].each do |method_name|
         define_method(method_name) do |&block|
           validate_deterministic_conflicts!
@@ -95,6 +121,10 @@ module Smith
         !@orchestrator_config.nil?
       end
 
+      def fanout?
+        !@fanout_config.nil?
+      end
+
       def optimized?
         !@optimization_config.nil?
       end
@@ -113,28 +143,148 @@ module Smith
 
       private
 
+      def validate_execute_conflicts!
+        validate_conflicts!(
+          "execute",
+          [
+            ["compute/run", @deterministic_block],
+            ["fan_out", @fanout_config]
+          ]
+        )
+      end
+
+      def validate_route_conflicts!
+        validate_conflicts!(
+          "route",
+          [
+            ["compute/run", @deterministic_block],
+            ["fan_out", @fanout_config]
+          ]
+        )
+      end
+
       def validate_deterministic_conflicts!
-        raise WorkflowError, "transition cannot declare both compute/run and execute" if @agent_name && !@router_config
-        raise WorkflowError, "transition cannot declare both compute/run and route" if @router_config
-        raise WorkflowError, "transition cannot declare both compute/run and workflow" if @workflow_class
-        raise WorkflowError, "transition cannot declare both compute/run and optimize" if @optimization_config
-        raise WorkflowError, "transition cannot declare both compute/run and orchestrate" if @orchestrator_config
+        validate_conflicts!(
+          "compute/run",
+          [
+            ["execute", @agent_name && !@router_config],
+            ["route", @router_config],
+            ["workflow", @workflow_class],
+            ["optimize", @optimization_config],
+            ["orchestrate", @orchestrator_config],
+            ["fan_out", @fanout_config]
+          ]
+        )
         raise WorkflowError, "transition cannot declare both compute and run" if @deterministic_block
       end
 
       def validate_optimize_conflicts!
-        raise WorkflowError, "transition cannot declare both optimize and execute" if @agent_name && !@router_config
-        raise WorkflowError, "transition cannot declare both optimize and route" if @router_config
-        raise WorkflowError, "transition cannot declare both optimize and workflow" if @workflow_class
-        raise WorkflowError, "transition cannot declare both optimize and compute/run" if @deterministic_block
+        validate_conflicts!(
+          "optimize",
+          [
+            ["execute", @agent_name && !@router_config],
+            ["route", @router_config],
+            ["workflow", @workflow_class],
+            ["compute/run", @deterministic_block],
+            ["fan_out", @fanout_config]
+          ]
+        )
       end
 
       def validate_orchestrate_conflicts!
-        raise WorkflowError, "transition cannot declare both orchestrate and execute" if @agent_name && !@router_config
-        raise WorkflowError, "transition cannot declare both orchestrate and route" if @router_config
-        raise WorkflowError, "transition cannot declare both orchestrate and workflow" if @workflow_class
-        raise WorkflowError, "transition cannot declare both orchestrate and optimize" if @optimization_config
-        raise WorkflowError, "transition cannot declare both orchestrate and compute/run" if @deterministic_block
+        validate_conflicts!(
+          "orchestrate",
+          [
+            ["execute", @agent_name && !@router_config],
+            ["route", @router_config],
+            ["workflow", @workflow_class],
+            ["optimize", @optimization_config],
+            ["compute/run", @deterministic_block],
+            ["fan_out", @fanout_config]
+          ]
+        )
+      end
+
+      def validate_fanout_conflicts!
+        validate_conflicts!(
+          "fan_out",
+          [
+            ["execute", @agent_name && !@router_config],
+            ["route", @router_config],
+            ["workflow", @workflow_class],
+            ["optimize", @optimization_config],
+            ["orchestrate", @orchestrator_config],
+            ["compute/run", @deterministic_block]
+          ]
+        )
+      end
+
+      def validate_conflicts!(primitive, conflicts)
+        conflicts.each do |other, present|
+          raise WorkflowError, "transition cannot declare both #{primitive} and #{other}" if present
+        end
+      end
+
+      def normalize_fanout_branches!(branches)
+        raise WorkflowError, "fan_out branches must be a Hash" unless branches.is_a?(Hash)
+        raise WorkflowError, "fan_out requires at least one branch" if branches.empty?
+
+        normalized = branches.each_with_object({}) do |(branch_key, agent_name), map|
+          key = normalize_fanout_branch_key!(branch_key)
+          agent = normalize_fanout_agent_name!(agent_name, key)
+          raise WorkflowError, "fan_out branch #{key.inspect} is duplicated" if map.key?(key)
+
+          map[key] = agent
+        end
+
+        validate_distinct_fanout_agents!(normalized)
+        normalized.freeze
+      end
+
+      def normalize_fanout_branch_key!(branch_key)
+        key = branch_key.to_s.strip
+        raise WorkflowError, "fan_out branch keys must not be blank" if key.empty?
+
+        key.to_sym
+      end
+
+      def normalize_fanout_agent_name!(agent_name, branch_key)
+        value = agent_name.to_s.strip
+        raise WorkflowError, "fan_out branch #{branch_key.inspect} must declare an agent" if value.empty?
+
+        value.to_sym
+      end
+
+      def validate_distinct_fanout_agents!(branches)
+        duplicates = branches.values.tally.select { |_agent, count| count > 1 }.keys
+        return if duplicates.empty?
+
+        raise WorkflowError, "fan_out branch agents must be distinct: #{duplicates.map(&:inspect).join(", ")}"
+      end
+
+      def validate_retry_controls!(error_classes, attempts:, backoff:, max_delay:, jitter:)
+        unless attempts.is_a?(Integer) && attempts.positive?
+          raise WorkflowError, "retry_on attempts must be a positive integer"
+        end
+
+        error_classes.each do |error_class|
+          next if error_class.is_a?(Class) && error_class <= StandardError
+
+          raise WorkflowError, "retry_on error classes must inherit from StandardError"
+        end
+
+        validate_non_negative_numeric!(:backoff, backoff)
+        validate_non_negative_numeric!(:jitter, jitter)
+        validate_non_negative_numeric!(:max_delay, max_delay) unless max_delay.nil?
+      end
+
+      def validate_non_negative_numeric!(name, value)
+        numeric = Float(value)
+        return if numeric >= 0.0
+
+        raise WorkflowError, "retry_on #{name} must be non-negative"
+      rescue TypeError, ArgumentError
+        raise WorkflowError, "retry_on #{name} must be numeric"
       end
 
       def validate_orchestrate_controls!(opts)
@@ -177,7 +327,7 @@ module Smith
         raise WorkflowError, "optimize max_rounds must be a positive integer"
       end
 
-      VALID_EXIT_MODES = [:raise, :return_last].freeze
+      VALID_EXIT_MODES = %i[raise return_last].freeze
       private_constant :VALID_EXIT_MODES
 
       def validate_optimize_exit_modes!(on_exhaustion:, on_converged:, on_threshold:)

data/lib/smith.rb

@@ -243,6 +243,8 @@ require_relative "smith/workflow/nested_execution"
 require_relative "smith/workflow/evaluator_optimizer"
 require_relative "smith/workflow/orchestrator_worker"
 require_relative "smith/workflow/parallel_execution"
+require_relative "smith/workflow/fanout_execution"
+require_relative "smith/workflow/retry_execution"
 require_relative "smith/workflow/deterministic_step"
 require_relative "smith/workflow/deterministic_execution"
 require_relative "smith/workflow/execution"
@@ -252,6 +254,7 @@ require_relative "smith/workflow/execution_frame"
 require_relative "smith/workflow/pipeline"
 require_relative "smith/workflow/router"
 require_relative "smith/workflow/parallel"
+require_relative "smith/workflow/parallel/cancellation"
 
 # Conditional Rails integration
 require_relative "smith/railtie" if defined?(Rails::Railtie)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: smith-agents
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.4.2
 platform: ruby
 authors:
 - Samuel Ralak
@@ -219,6 +219,7 @@ files:
 - lib/smith/workflow/event_integration.rb
 - lib/smith/workflow/execution.rb
 - lib/smith/workflow/execution_frame.rb
+- lib/smith/workflow/fanout_execution.rb
 - lib/smith/workflow/graph.rb
 - lib/smith/workflow/graph/diagnostic.rb
 - lib/smith/workflow/graph/metrics.rb
@@ -236,9 +237,11 @@ files:
 - lib/smith/workflow/nested_execution.rb
 - lib/smith/workflow/orchestrator_worker.rb
 - lib/smith/workflow/parallel.rb
+- lib/smith/workflow/parallel/cancellation.rb
 - lib/smith/workflow/parallel_execution.rb
 - lib/smith/workflow/persistence.rb
 - lib/smith/workflow/pipeline.rb
+- lib/smith/workflow/retry_execution.rb
 - lib/smith/workflow/router.rb
 - lib/smith/workflow/transition.rb
 - script/profile_tool_results.rb