smith-agents 0.4.0

data/lib/smith/workflow/evaluator_optimizer.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module EvaluatorOptimizer
+      OptimizationState = Struct.new(
+        :config, :prepared_input, :candidate, :feedback, :last_score, :generator_class, :evaluator_class
+      ) do
+        def initialize(config, prepared_input)
+          super(config, prepared_input, nil, nil, nil, nil, nil)
+        end
+      end
+
+      private
+
+      def execute_optimization_step(transition, prepared_input: nil)
+        state = OptimizationState.new(transition.optimization_config, prepared_input)
+        state.generator_class = Agent::Registry.fetch!(
+          state.config[:generator],
+          workflow_class: self.class,
+          transition_name: transition.name,
+          role: :generator
+        )
+        state.evaluator_class = Agent::Registry.fetch!(
+          state.config[:evaluator],
+          workflow_class: self.class,
+          transition_name: transition.name,
+          role: :evaluator
+        )
+        run_optimization_loop(state)
+      end
+
+      def run_optimization_loop(state)
+        state.config[:max_rounds].times do |round|
+          result = run_optimization_round(state, round)
+          return result if result
+        end
+
+        handle_exit(state, :on_exhaustion,
+                    "optimization exhausted #{state.config[:max_rounds]} rounds without acceptance")
+      end
+
+      def run_optimization_round(state, round)
+        generate_candidate!(state, round)
+        invoke_before_eval(state)
+        evaluation = normalize_evaluation(evaluate_candidate(state))
+        validate_evaluation_structure!(evaluation)
+        validate_evaluation_fields!(evaluation, state.config)
+
+        return state.candidate if evaluation[:accept]
+
+        if evaluation[:converged]
+          return handle_exit(state, :on_converged,
+                             "optimization converged without acceptance after round #{round + 1}")
+        end
+
+        threshold_exit = check_improvement_threshold!(evaluation, state, round)
+        return threshold_exit if threshold_exit
+
+        state.last_score = evaluation[:score]
+        state.feedback = evaluation[:feedback]
+        nil
+      end
+
+      # :raise => WorkflowError(message); :return_last => state.candidate;
+      # callable => mode.call(state). Default :raise preserves legacy
+      # behavior for hosts that don't opt in to graceful exits.
+      def handle_exit(state, mode_key, message)
+        mode = state.config[mode_key]
+        case mode
+        when :raise        then raise WorkflowError, message
+        when :return_last  then state.candidate
+        else
+          mode.call(state)
+        end
+      end
+
+      # Real RubyLLM schema-bound responses come back as Hash with String
+      # keys. The validate_evaluation_* helpers below expect symbol keys
+      # (test stubs use symbol keys, masking the gap). String input also
+      # arrives when an evaluator stubs raw JSON. Normalize to a uniform
+      # symbol-keyed Hash so the validators stay clean and the rest of
+      # the loop can use `evaluation[:accept]` semantics without caring
+      # which provider returned the payload.
+      #
+      # Pure-Ruby deep-symbolize: Smith doesn't depend on ActiveSupport,
+      # so `deep_symbolize_keys` isn't available. The recursion mirrors
+      # what `Hash#transform_keys` plus a nested-Hash walk would do.
+      def normalize_evaluation(evaluation)
+        case evaluation
+        when Hash
+          deep_symbolize_evaluation(evaluation)
+        when String
+          parsed = (JSON.parse(evaluation, symbolize_names: true) rescue nil)
+          parsed.is_a?(Hash) ? parsed : evaluation
+        else
+          evaluation
+        end
+      end
+
+      def deep_symbolize_evaluation(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, nested), out|
+            sym_key = key.is_a?(String) ? key.to_sym : key
+            out[sym_key] = deep_symbolize_evaluation(nested)
+          end
+        when Array
+          value.map { |item| deep_symbolize_evaluation(item) }
+        else
+          value
+        end
+      end
+
+      def generate_candidate!(state, round)
+        input = prepare_generator_input(state.prepared_input, round, state.candidate, state.feedback)
+        result = invoke_agent_with_budget(state.generator_class, input)
+        state.candidate = result
+      end
+
+      def evaluate_candidate(state)
+        input = build_evaluator_input(state)
+        invoke_with_evaluator_schema(state.evaluator_class, state.config[:evaluator_schema], input)
+      end
+
+      # evaluator_context: :inject_state appends the candidate as a
+      # user turn to the prepared_input the generator received, so the
+      # evaluator sees the same seed_messages + inject_state context.
+      # Default nil keeps the legacy candidate-only payload.
+      def build_evaluator_input(state)
+        return [{ role: :user, content: state.candidate.to_s }] unless state.config[:evaluator_context] == :inject_state
+
+        prior = Array(state.prepared_input).dup
+        prior.push(role: :user, content: state.candidate.to_s)
+      end
+
+      # Runs after candidate generation, before evaluator invocation.
+      # Receives (state, @context); @context is mutable. Return value
+      # is discarded. Raised exceptions bubble through the standard
+      # step failure path.
+      def invoke_before_eval(state)
+        callback = state.config[:before_eval]
+        return unless callback
+
+        callback.call(state, @context)
+      end
+
+      def invoke_with_evaluator_schema(evaluator_class, schema, input)
+        original_schema = evaluator_class.output_schema
+        evaluator_class.output_schema(schema)
+        invoke_agent_with_budget(evaluator_class, input)
+      ensure
+        evaluator_class.output_schema(original_schema)
+      end
+
+      def invoke_agent_with_budget(agent_class, prepared_input)
+        Thread.current[:smith_last_agent_result] = nil
+        with_agent_context(agent_class) do
+          invoke_with_call_ledger(agent_class, prepared_input)
+        end
+      end
+
+      def invoke_with_call_ledger(agent_class, prepared_input)
+        ledger = effective_call_ledger
+        reserved = reserve_serial_budget(ledger, agent_budget: agent_class&.budget)
+        begin
+          result = invoke_agent(agent_class, prepared_input)
+          agent_result = result.is_a?(AgentResult) ? result : nil
+          reconcile_branch_budget(ledger, reserved, agent_result: agent_result)
+          reserved = nil
+          agent_result ? agent_result.content : result
+        ensure
+          settle_budget_on_failure(ledger, reserved, Thread.current[:smith_last_agent_result]) if reserved
+          Thread.current[:smith_last_agent_result] = nil
+        end
+      end
+
+      # Returns nil when the threshold doesn't trip. When it does,
+      # 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])
+
+        handle_exit(state, :on_threshold,
+                    "optimization improvement below threshold after round #{round + 1}")
+      end
+
+      def prepare_generator_input(prepared_input, round, prior_candidate, feedback)
+        return prepared_input if round.zero?
+
+        (prepared_input&.dup || []).push(
+          { role: :assistant, content: prior_candidate.to_s },
+          {
+            role: :user,
+            content: "[smith:refinement-round] #{round + 1}\n[smith:evaluator-feedback]\n#{feedback}"
+          }
+        )
+      end
+
+      def validate_evaluation_structure!(evaluation)
+        raise WorkflowError, "evaluator output must be a Hash" unless evaluation.is_a?(Hash)
+        raise WorkflowError, "evaluator output missing :accept" unless evaluation.key?(:accept)
+        raise WorkflowError, "evaluator :accept must be boolean" unless [true, false].include?(evaluation[:accept])
+      end
+
+      def validate_evaluation_fields!(evaluation, config)
+        unless evaluation[:accept] || evaluation[:feedback]
+          raise WorkflowError, "evaluator must provide :feedback when not accepted"
+        end
+        return unless config[:improvement_threshold] && !evaluation[:score].is_a?(Numeric)
+
+        raise WorkflowError, "evaluator must provide numeric :score when improvement_threshold is configured"
+      end
+
+      def stop_for_threshold?(current_score, last_score, threshold)
+        threshold && last_score && current_score.is_a?(Numeric) && (current_score - last_score).abs < threshold
+      end
+    end
+  end
+end

data/lib/smith/workflow/event_integration.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module EventIntegration
+      private
+
+      def emit_step_completed(transition, _output)
+        Smith::Trace.record(
+          type: :transition,
+          data: { transition: transition.name, from: transition.from, to: transition.to }
+        )
+
+        Smith::Events.emit(
+          Events::StepCompleted.new(
+            transition: transition.name,
+            from: transition.from,
+            to: transition.to
+          )
+        )
+      end
+    end
+  end
+end

data/lib/smith/workflow/execution.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module Execution
+      include Agent::Lifecycle
+      include NestedExecution
+      include EvaluatorOptimizer
+      include OrchestratorWorker
+      include ParallelExecution
+      include DeterministicExecution
+
+      private
+
+      def execute_step(transition)
+        setup_step_context
+        output = with_scoped_artifacts { run_guarded_step(transition) }
+        complete_step(transition, output)
+      rescue StandardError => e
+        @outcome = nil
+        handle_step_failure(transition, e)
+        { transition: transition.name, from: transition.from, to: transition.to, error: e }
+      ensure
+        teardown_step_context
+      end
+
+      def setup_step_context
+        Tool.current_deadline = wall_clock_deadline
+        Tool.current_ledger = @ledger
+        Tool.current_tool_result_collector = tool_result_collector
+      end
+
+      def teardown_step_context
+        Tool.current_guardrails = nil
+        Tool.current_deadline = nil
+        Tool.current_ledger = nil
+        Tool.current_tool_result_collector = nil
+        Smith.scoped_artifacts = nil
+      end
+
+      def run_guarded_step(transition)
+        return dispatch_step(transition) if transition.deterministic?
+
+        agent_class = resolve_agent_class(transition)
+        run_input_guardrails(agent_class)
+        apply_tool_guardrails(agent_class)
+        prepared_input = build_session&.prepare!
+
+        output = with_agent_context(agent_class) do
+          dispatch_step(transition, prepared_input: prepared_input)
+        end
+
+        validate_data_volume!(output, agent_class)
+        run_output_guardrails(output, agent_class)
+        resolve_router_output(transition, output)
+      end
+
+      def complete_step(transition, output)
+        @state = transition.to
+        @next_transition_name = @router_next_transition || transition.success_transition
+        @router_next_transition = nil
+        append_accepted_output(output)
+        emit_step_completed(transition, output)
+        { transition: transition.name, from: transition.from, to: transition.to, output: output }
+      end
+
+      def append_accepted_output(output)
+        return unless @session_messages
+        return if output.nil?
+
+        @session_messages << { role: :assistant, content: output }
+      end
+
+      def resolve_router_output(transition, output)
+        return output unless transition.routed?
+
+        @router_next_transition = Router.resolve(output, transition.router_config, workflow_class: self.class)
+        nil # routed steps have no user-facing output
+      end
+
+      def execute_transition_body(transition, prepared_input: nil)
+        @last_prepared_input = prepared_input
+        return nil unless transition.agent_name
+
+        agent_class = resolve_agent_class(transition)
+        # Accepts either static `model "id"` (chat_kwargs[:model]) OR
+        # block-form `model { |ctx| ... }` (model_block). The block-form
+        # path resolves the actual id in build_model_chain at attempt time.
+        return nil unless agent_class.model_configured?
+
+        invoke_agent(agent_class, prepared_input)
+      end
+
+      def execute_serial_step(transition, prepared_input: nil)
+        Thread.current[:smith_last_agent_result] = nil
+        ledger = effective_call_ledger
+        reserved = reserve_for_serial(transition, ledger)
+        begin
+          result = execute_transition_body(transition, prepared_input: prepared_input)
+          agent_result = result.is_a?(AgentResult) ? result : nil
+          reconcile_branch_budget(ledger, reserved, agent_result: agent_result)
+          reserved = nil
+          agent_result ? agent_result.content : result
+        ensure
+          settle_budget_on_failure(ledger, reserved, Thread.current[:smith_last_agent_result]) if reserved
+          Thread.current[:smith_last_agent_result] = nil
+        end
+      end
+
+      def reserve_for_serial(transition, ledger)
+        agent_class = resolve_agent_class(transition)
+        reserve_serial_budget(ledger, agent_budget: agent_class&.budget)
+      end
+
+      def resolve_agent_class(transition)
+        return nil unless transition.agent_name
+
+        Agent::Registry.fetch!(
+          transition.agent_name,
+          workflow_class: self.class,
+          transition_name: transition.name,
+          role: :agent
+        )
+      end
+    end
+  end
+end

data/lib/smith/workflow/execution_frame.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module Smith
+  class Workflow
+    # Absorbs the five-flag bookkeeping pattern (claimed, result_obtained,
+    # recorded, intentional_retry, finalize_succeeded) duplicated across
+    # host Execution wrappers. The host yields its per-attempt work in,
+    # records lifecycle milestones via mark_*! setters, and the frame's
+    # ensure invokes on_clear / always_ensure based on the canonical
+    # decision: claimed && (finalize_succeeded || (intentional_retry &&
+    # recorded) || !result_obtained).
+    #
+    # OrderingError and AlreadyRun inherit from Smith::Error (NOT
+    # Smith::WorkflowError) so host `rescue Smith::WorkflowError` blocks
+    # cannot silently downgrade ordering bugs to handler-error states.
+    class ExecutionFrame
+      class OrderingError < Smith::Error; end
+      class AlreadyRun < Smith::Error; end
+
+      def self.run(workflow: nil, on_clear: nil, always_ensure: nil, logger: nil)
+        new(workflow: workflow, on_clear: on_clear, always_ensure: always_ensure, logger: logger).run { |frame| yield frame }
+      end
+
+      def initialize(workflow: nil, on_clear: nil, always_ensure: nil, logger: nil)
+        @workflow = workflow
+        @on_clear = on_clear
+        @always_ensure = always_ensure
+        @logger = logger
+        @claimed = false
+        @claimed_set = false
+        @result_obtained = false
+        @recorded = false
+        @intentional_retry = false
+        @finalize_succeeded = false
+        @run_invoked = false
+        @finished = false
+      end
+
+      def run
+        raise AlreadyRun, "ExecutionFrame already run" if @run_invoked
+
+        @run_invoked = true
+        result = yield(self)
+        result
+      ensure
+        finish!
+      end
+
+      def mark_claimed!(value = true)
+        if @claimed_set && @claimed != value
+          raise OrderingError, "mark_claimed! called twice with conflicting values (#{@claimed.inspect} then #{value.inspect})"
+        end
+
+        @claimed = value
+        @claimed_set = true
+        value
+      end
+
+      def mark_result_obtained!
+        raise OrderingError, "mark_result_obtained! requires prior mark_claimed!(true)" unless @claimed == true
+
+        @result_obtained = true
+      end
+
+      def mark_recorded!
+        raise OrderingError, "mark_recorded! requires prior mark_result_obtained!" unless @result_obtained
+
+        @recorded = true
+      end
+
+      def mark_intentional_retry!(value = true)
+        if @claimed_set && @claimed == false
+          raise OrderingError, "mark_intentional_retry! invalid after mark_claimed!(false)"
+        end
+
+        @intentional_retry = value
+      end
+
+      def mark_finalize_succeeded!
+        raise OrderingError, "mark_finalize_succeeded! requires prior mark_recorded!" unless @recorded
+
+        @finalize_succeeded = true
+      end
+
+      def claimed?
+        @claimed == true
+      end
+
+      def result_obtained?
+        @result_obtained
+      end
+
+      def recorded?
+        @recorded
+      end
+
+      def intentional_retry?
+        @intentional_retry
+      end
+
+      def finalize_succeeded?
+        @finalize_succeeded
+      end
+
+      def should_clear?
+        claimed? && (@finalize_succeeded || (@intentional_retry && @recorded) || !@result_obtained)
+      end
+
+      def finish!
+        return false if @finished
+
+        @finished = true
+        cleared = false
+
+        if should_clear?
+          cleared = invoke_on_clear
+        end
+
+        invoke_always_ensure if claimed?
+
+        cleared
+      end
+
+      private
+
+      def invoke_on_clear
+        if @on_clear.respond_to?(:call)
+          @on_clear.call
+          return true
+        end
+
+        target = resolve_workflow
+        if target.nil?
+          resolved_logger.warn("Smith::Workflow::ExecutionFrame: workflow resolver returned nil; skipping clear")
+          return false
+        end
+
+        target.clear_persisted!
+        true
+      rescue StandardError => e
+        resolved_logger.error("Smith::Workflow::ExecutionFrame on_clear raised: #{e.class}: #{e.message}")
+        true
+      end
+
+      def invoke_always_ensure
+        return unless @always_ensure.respond_to?(:call)
+
+        @always_ensure.call
+      rescue StandardError => e
+        resolved_logger.error("Smith::Workflow::ExecutionFrame always_ensure raised: #{e.class}: #{e.message}")
+      end
+
+      def resolve_workflow
+        return @workflow.call if @workflow.respond_to?(:call)
+
+        @workflow
+      end
+
+      def resolved_logger
+        @logger || Smith.config.logger || (@_fallback_logger ||= Logger.new($stderr))
+      end
+    end
+  end
+end

data/lib/smith/workflow/guardrail_integration.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module GuardrailIntegration
+      private
+
+      def apply_tool_guardrails(agent_class)
+        sources = [self.class.guardrails, agent_class&.guardrails].compact
+        Tool.current_guardrails = sources.empty? ? nil : sources
+      end
+
+      def run_input_guardrails(agent_class)
+        wf_guardrails = self.class.guardrails
+        Guardrails::Runner.run_inputs(wf_guardrails, @context) if wf_guardrails
+
+        agent_guardrails = agent_class&.guardrails
+        Guardrails::Runner.run_inputs(agent_guardrails, @context) if agent_guardrails
+      end
+
+      def run_output_guardrails(output, agent_class)
+        wf_guardrails = self.class.guardrails
+        Guardrails::Runner.run_outputs(wf_guardrails, output) if wf_guardrails
+
+        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
+      end
+    end
+  end
+end

data/lib/smith/workflow/nested_execution.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module NestedExecution
+      private
+
+      def execute_nested_workflow(transition)
+        check_deadline!
+        child = build_child_workflow(transition.workflow_class)
+        child_result = run_child_workflow(child)
+        handle_child_result(child_result)
+      end
+
+      def run_child_workflow(child)
+        child.run!
+      rescue Smith::Error => e
+        raise WorkflowError, "nested workflow failed: #{e.message}"
+      end
+
+      def build_child_workflow(child_class)
+        child = child_class.new(context: @context.dup, ledger: @ledger, created_at: @created_at)
+        child.instance_variable_set(:@execution_namespace, @execution_namespace)
+        child.instance_variable_set(:@inherited_deadline, wall_clock_deadline)
+        child.instance_variable_set(:@inherited_scoped_artifacts, Smith.scoped_artifacts)
+        child
+      end
+
+      # Roll up child totals AND usage_entries BEFORE the failed-step
+      # check raises. Previously the rollup only fired on child success
+      # — billable agent work inside a failed child was silently
+      # dropped from the parent's totals/entries. The drift guard at
+      # the hadithi boundary wouldn't catch it (parent rollups + entries
+      # consistently undercount the same way; sum invariant still holds
+      # incorrectly). Roll up first, then re-raise, so the parent's
+      # terminal state reflects the child's billable work even when the
+      # child failed.
+      def handle_child_result(child_result)
+        roll_up_child_totals(child_result)
+
+        failed_step = child_result.steps.find { |s| s.key?(:error) }
+        raise WorkflowError, "nested workflow failed: #{failed_step[:error]&.message}" if failed_step
+
+        child_result.output
+      end
+
+      # `@usage_mutex` is eagerly initialized in `Workflow#initialize`
+      # AND `Workflow#restore_state`, so it's always present. Single
+      # synchronize block updates totals + entries together, matching
+      # the lifecycle.rb `record_usage` pattern.
+      #
+      # Defensive deep-copy via `from_h(snapshot_value(entry.to_h))`:
+      # `Struct#dup` is shallow (shares mutable string fields like
+      # `usage_id`/`model`), and aliasing child entries into multiple
+      # parents could let later mutations corrupt earlier parents.
+      def roll_up_child_totals(child_result)
+        child_entries = (child_result.usage_entries || []).map do |entry|
+          Workflow::UsageEntry.from_h(snapshot_value(entry.to_h))
+        end
+
+        @usage_mutex.synchronize do
+          @total_cost = (@total_cost || 0.0) + (child_result.total_cost || 0.0)
+          @total_tokens = (@total_tokens || 0) + (child_result.total_tokens || 0)
+          @usage_entries.concat(child_entries)
+        end
+      end
+    end
+  end
+end