smith-agents 0.11.0 → 0.12.1

data/lib/smith/workflow/transition.rb

@@ -8,23 +8,79 @@ module Smith
       attr_reader :name, :from, :to, :agent_name, :agent_opts, :success_transition, :failure_transition,
                   :router_config, :workflow_class, :optimization_config, :orchestrator_config,
                   :fanout_config, :retry_config, :deterministic_block, :deterministic_kind,
-                  :deterministic_routes
+                  :deterministic_routes, :deterministic_fallthrough, :await_config, :timeout_transition,
+                  :step_input, :output_to, :stream, :batch_mode, :on_request_change
 
       def initialize(name, from:, to:, &)
         @name = own_identifier(name)
         @from = own_identifier(from, allow_nil: true)
         @to = own_identifier(to)
         instance_eval(&) if block_given?
+        validate_child_run_controls!
+        validate_durable_retry!
+        validate_batch_mode!
+        validate_timeout_route!
+      end
+
+      # Waits, bounded by a required timeout, for an event the host delivers
+      # with `Workflow.resume!`, writing its payload to the context key
+      # `into:`. The optional block runs on entry with an AwaitStep and may
+      # send the request the event answers, or finish at once with
+      # `resolve!`. `timeout:` is seconds, or a callable of the context
+      # returning seconds; past it, `expire_wait!` takes `on_timeout`.
+      def await(event, into:, timeout:, &block)
+        validate_execution_primitive_conflict!("await")
+        raise WorkflowError, "await into: must be a Symbol context key" unless into.is_a?(Symbol)
+
+        @await_config = {
+          kind: :await, event: Identifier.normalize(event, label: "await event"), into:,
+          timeout: wait_seconds!(timeout, "await timeout:"), block:
+        }.freeze
+        commit_execution_primitive!("await")
+      end
+
+      # Continues to `to:` no earlier than `seconds` after the step is
+      # entered (seconds, or a callable of the context returning seconds),
+      # when the host calls `expire_wait!`.
+      def delay(seconds)
+        validate_execution_primitive_conflict!("delay")
+        @await_config = { kind: :delay, event: nil, into: nil, timeout: wait_seconds!(seconds, "delay"), block: nil }
+                        .freeze
+        commit_execution_primitive!("delay")
+      end
+
+      # The transition an `await` takes when its deadline passes.
+      def on_timeout(transition_name)
+        @timeout_transition = own_identifier(transition_name)
       end
 
-      def execute(agent_name, **opts)
+      def awaits? = !@await_config.nil?
+
+      def delay? = @await_config&.fetch(:kind) == :delay
+
+      # `input:` (on every agent primitive) is a callable of a copy of the
+      # context returning the step's messages, which replace the session
+      # transcript for this step. `output_to:` names the context key the
+      # step's output is written to, instead of the transcript.
+      # `stream:` names the sink in `Smith.config.stream_sinks` the reply's
+      # text is streamed to as the model writes it (Smith::Streaming).
+      # `mode:` is :sync (the default), :batch, or a callable of the context
+      # and the step attempt returning one: a batch step sends its request
+      # through the host's batch queue and waits for the result.
+      # `on_request_change:` says what a batch result does when the step
+      # renders another request by the time it comes (Smith::Batch).
+      def execute(agent_name, input: nil, output_to: nil, **opts)
         validate_execution_primitive_conflict!("execute")
 
         normalized_agent = normalize_agent_reference!(agent_name, "agent")
         validate_parallel_options!(opts)
+        assign_step_io!(input, output_to)
+        @stream = stream_name!(opts[:stream], opts)
+        @batch_mode = batch_mode!(opts[:mode], stream: opts[:stream], parallel: opts[:parallel] == true)
+        @on_request_change = request_change!(opts[:on_request_change])
 
         @agent_name = normalized_agent
-        @agent_opts = opts.freeze
+        @agent_opts = opts.except(:stream, :mode, :on_request_change).freeze
         commit_execution_primitive!("execute")
       end
 
@@ -40,8 +96,9 @@ module Smith
         @failure_transition = own_identifier(transition_name)
       end
 
-      def route(agent_name, routes:, confidence_threshold:, fallback:)
+      def route(agent_name, routes:, confidence_threshold:, fallback:, input: nil)
         validate_execution_primitive_conflict!("route")
+        assign_step_io!(input, nil)
         if @success_transition
           raise WorkflowError, "routed transitions cannot declare on_success; router routes select the next transition"
         end
@@ -74,8 +131,11 @@ module Smith
                    before_eval: nil,
                    on_exhaustion: :raise,
                    on_converged: :raise,
-                   on_threshold: :raise)
+                   on_threshold: :raise,
+                   input: nil,
+                   output_to: nil)
         validate_execution_primitive_conflict!("optimize")
+        assign_step_io!(input, output_to)
         validate_optimize_controls!(generator, evaluator, max_rounds, evaluator_schema)
         validate_optimize_exit_modes!(on_exhaustion: on_exhaustion, on_converged: on_converged,
                                       on_threshold: on_threshold)
@@ -98,8 +158,9 @@ module Smith
         commit_execution_primitive!("optimize")
       end
 
-      def orchestrate(**opts)
+      def orchestrate(input: nil, output_to: nil, **opts)
         validate_execution_primitive_conflict!("orchestrate")
+        assign_step_io!(input, output_to)
         validate_orchestrate_controls!(opts)
         config = opts.merge(
           orchestrator: normalize_agent_reference!(opts.fetch(:orchestrator), "orchestrator"),
@@ -110,8 +171,11 @@ module Smith
         commit_execution_primitive!("orchestrate")
       end
 
-      def fan_out(branches:)
+      def fan_out(branches:, input: nil, output_to: nil, mode: nil, on_request_change: nil)
         validate_execution_primitive_conflict!("fan_out")
+        assign_step_io!(input, output_to)
+        @batch_mode = batch_mode!(mode, stream: nil, parallel: false)
+        @on_request_change = request_change!(on_request_change)
 
         normalized = normalize_fanout_branches!(branches)
         @fanout_branch_lookup = normalized.to_h do |key, agent|
@@ -124,28 +188,69 @@ module Smith
       end
       alias fanout fan_out
 
-      def retry_on(*error_classes, attempts:, backoff: 0, max_delay: nil, jitter: 0)
+      # `new_idempotency_key_on:` names errors that show an attempt's
+      # requests took no effect (a refusal, not a timeout): the attempts
+      # after one of them use new idempotency keys. Every other retry keeps
+      # the step's keys. It is refused on a transition whose failures can
+      # come from several steps or branches (a nested workflow, parallel or
+      # fan-out branches, an optimizer or an orchestrator), where one error
+      # cannot speak for every request of the attempt.
+      #
+      # `durable: true` waits out each backoff as a wait of the run (kind
+      # `:retry`) instead of sleeping in the worker: the host wakes it with
+      # `expire_wait!` and continues the run, which makes the next attempt
+      # under the recorded attempt number and key generation.
+      # rubocop:disable Metrics/ParameterLists
+      def retry_on(*error_classes, attempts:, backoff: 0, max_delay: nil, jitter: 0, new_idempotency_key_on: [],
+                   durable: false)
         policy = normalize_retry_policy!(error_classes, attempts:, backoff:, max_delay:, jitter:)
+        new_key_classes = normalize_new_idempotency_key_on!(new_idempotency_key_on, error_classes)
+        validate_durable_policy!(durable, policy)
 
-        @retry_config = {
+        config = {
           error_classes: error_classes.freeze,
           attempts: policy.attempts,
           backoff: policy.base_delay,
           max_delay: policy.max_delay,
           jitter: policy.jitter
-        }.freeze
+        }
+        config[:new_idempotency_key_on] = new_key_classes if new_key_classes.any?
+        config[:durable] = true if durable
+        @retry_config = config.freeze
+        reject_new_idempotency_key_on_composite!
       end
+      # rubocop:enable Metrics/ParameterLists
+
+      def durable_retry? = @retry_config&.fetch(:durable, false) == true
+
+      # Whether the step may send its requests as a batch: its mode is not
+      # :sync.
+      def batches? = !@batch_mode.nil? && @batch_mode != :sync
+
+      def validate_durable_policy!(durable, policy)
+        raise WorkflowError, "retry_on durable: must be true or false" unless [true, false].include?(durable)
+        return unless durable && !(policy.attempts > 1 && policy.base_delay.positive?)
+
+        raise WorkflowError, "retry_on durable: needs at least 2 attempts and a positive backoff, so it has a wait"
+      end
+      private :validate_durable_policy!
+
+      # A step that waits (an await, delay, map or call), launches runs of
+      # its own (a spawn), or waits between attempts (a durable retry).
+      def waits_or_launches? = awaits? || child_runs? || durable_retry?
 
       %i[compute run].each do |method_name|
-        define_method(method_name) do |routes: nil, &block|
+        define_method(method_name) do |routes: nil, fallthrough: false, &block|
           validate_execution_primitive_conflict!("compute/run", declaration: method_name.to_s)
           raise WorkflowError, "#{method_name} requires a block" unless block
 
           normalized_routes = normalize_deterministic_routes!(routes)
+          validate_deterministic_fallthrough!(fallthrough, normalized_routes)
 
           @deterministic_block = block
           @deterministic_kind = method_name
           @deterministic_routes = normalized_routes
+          @deterministic_fallthrough = fallthrough
           commit_execution_primitive!("compute/run", declaration: method_name.to_s)
         end
       end
@@ -189,8 +294,110 @@ module Smith
         agent_opts&.dig(:parallel) == true
       end
 
+      # Whether the step runs an agent: `execute`, `route`, `fan_out`,
+      # `optimize` or `orchestrate`.
+      def agent_step?
+        !agent_name.nil? || optimized? || orchestrated? || fanout?
+      end
+
       private
 
+      def assign_step_io!(input, output_to)
+        raise WorkflowError, "input: must be a callable of the context" unless input.nil? || input.respond_to?(:call)
+        raise WorkflowError, "output_to: must be a Symbol context key" unless output_to.nil? || output_to.is_a?(Symbol)
+
+        @step_input = input
+        @output_to = output_to
+      end
+
+      # A batch request is one turn of one model, sent and answered apart
+      # from the step: a streamed or parallel step has nothing to send it as.
+      def batch_mode!(mode, stream:, parallel:)
+        return if mode.nil?
+        unless %i[sync batch].include?(mode) || mode.respond_to?(:call)
+          raise WorkflowError, "mode: must be :sync, :batch, or a callable of the context and attempt returning one"
+        end
+        raise WorkflowError, "mode: :batch cannot stream" if stream && mode != :sync
+        raise WorkflowError, "mode: is not available on a parallel step" if parallel
+
+        mode
+      end
+
+      # What a batch result does when the step renders another request by
+      # the time it comes: :keep it (the default), :resend the request over
+      # the wire, or :fail the step with BatchRequestChanged.
+      def request_change!(value)
+        return if value.nil?
+        unless %i[keep resend fail].include?(value)
+          raise WorkflowError, "on_request_change: must be :keep, :resend or :fail"
+        end
+        raise WorkflowError, "on_request_change: needs mode: :batch or a mode callable" unless batches?
+
+        value
+      end
+
+      # One reply streams to one sink: a parallel step has several.
+      def stream_name!(stream, opts)
+        return if stream.nil?
+        raise WorkflowError, "execute stream: must name a sink with a Symbol" unless stream.is_a?(Symbol)
+        raise WorkflowError, "execute stream: is not available on a parallel step" if opts[:parallel] == true
+
+        stream
+      end
+
+      def wait_seconds!(value, label)
+        return value if value.respond_to?(:call)
+        return value if (value.is_a?(Integer) || (value.is_a?(Float) && value.finite?)) && value.positive?
+
+        raise WorkflowError, "#{label} must be a positive number of seconds or a callable returning one"
+      end
+
+      # An await must say where its timeout goes: past its deadline it takes
+      # `on_timeout`, or else `on_failure` with Smith::WaitTimedOut. Without
+      # either, an expired wait could never end.
+      # A durable retry waits between attempts, so its step must be one a
+      # run can wait in: not a step that waits itself, nor one whose
+      # branches keep durable state of their own.
+      # Its last failure must settle the run through `on_failure`: a failure
+      # raised to the host leaves the stored run before that attempt, so a
+      # job that runs again would make the attempt again at once, past the
+      # policy's attempts.
+      def validate_durable_retry!
+        return unless durable_retry?
+
+        refuse_durable_retry_on_waiting_step!
+        return if @failure_transition
+
+        raise WorkflowError, "retry_on durable: needs on_failure, so the last failure settles the run instead of " \
+                             "being made again by a host that runs the job again"
+      end
+
+      # A batch result can fail or never come, as an await's event can: the
+      # step must say where that goes.
+      def validate_batch_mode!
+        return unless batches? && @failure_transition.nil?
+
+        raise WorkflowError, "mode: :batch needs on_failure, where a batch result that fails or never comes goes"
+      end
+
+      def refuse_durable_retry_on_waiting_step!
+        return unless awaits? || parallel? || fanout? || optimized? || orchestrated?
+
+        raise WorkflowError, "retry_on durable: is not available on await, delay, parallel, fan_out, optimize or " \
+                             "orchestrate steps"
+      end
+
+      def validate_timeout_route!
+        if @timeout_transition
+          return if @await_config && !delay?
+
+          raise WorkflowError, "on_timeout requires an await step"
+        end
+        return unless @await_config && !delay? && @failure_transition.nil?
+
+        raise WorkflowError, "an await step must declare on_timeout or on_failure for its deadline"
+      end
+
       def own_identifier(identifier, allow_nil: false)
         Identifier.normalize(identifier, label: "workflow identifier", allow_nil:)
       end
@@ -218,6 +425,17 @@ module Smith
       def commit_execution_primitive!(primitive, declaration: primitive)
         @execution_primitive = primitive
         @execution_declaration = declaration
+        reject_new_idempotency_key_on_composite!
+      end
+
+      def several_step_execution? = nested? || parallel? || fanout? || optimized? || orchestrated?
+
+      def reject_new_idempotency_key_on_composite!
+        return unless @retry_config&.key?(:new_idempotency_key_on) && several_step_execution?
+
+        raise WorkflowError,
+              "retry_on new_idempotency_key_on: cannot be declared on a nested workflow, parallel, fan_out, " \
+              "optimize or orchestrate transition, where one error cannot speak for every request of the attempt"
       end
 
       def normalize_fanout_branches!(branches)
@@ -349,12 +567,48 @@ module Smith
         raise WorkflowError, "retry_on #{e.message}"
       end
 
-      def reject_retry_forbidden!(error_classes)
+      def normalize_new_idempotency_key_on!(classes, retried_classes)
+        unless classes.is_a?(Array) && classes.all? { |error_class| standard_error_class?(error_class) }
+          raise WorkflowError, "retry_on new_idempotency_key_on: must be an Array of StandardError classes"
+        end
+
+        if classes.uniq.size != classes.size
+          raise WorkflowError, "retry_on new_idempotency_key_on: lists a class more than once"
+        end
+
+        reject_retry_forbidden!(classes, context: "move to new idempotency keys after")
+        reject_unretried_new_key_classes!(classes, retried_classes)
+        classes.dup.freeze
+      end
+
+      def standard_error_class?(value) = value.is_a?(Class) && value <= StandardError
+
+      # With no error classes the policy retries whatever Smith classifies
+      # retryable, which cannot be checked here.
+      def reject_unretried_new_key_classes!(classes, retried_classes)
+        return if retried_classes.empty?
+
+        unretried = classes.find { |error_class| retried_classes.none? { |retried| error_class <= retried } }
+        return unless unretried
+
+        raise WorkflowError, "retry_on new_idempotency_key_on: lists #{unretried.name || unretried.inspect}, " \
+                             "which this policy does not retry"
+      end
+
+      def reject_retry_forbidden!(error_classes, context: "retry")
         forbidden = error_classes.find { |error_class| Smith::Errors.retry_forbidden_class?(error_class) }
         return unless forbidden
 
         label = forbidden.name || "an anonymous terminal tool-evidence error class"
-        raise WorkflowError, "retry_on cannot retry #{label} because the tool outcome may be uncertain"
+        raise WorkflowError, "retry_on cannot #{context} #{label} because the tool outcome may be uncertain"
+      end
+
+      # `fallthrough: true` lets a step that declares `routes:` finish without
+      # routing, taking `on_success` or the first transition from its target
+      # state. It means nothing without `routes:`.
+      def validate_deterministic_fallthrough!(fallthrough, routes)
+        raise WorkflowError, "fallthrough must be true or false" unless [true, false].include?(fallthrough)
+        raise WorkflowError, "fallthrough: true requires routes:" if fallthrough && routes.nil?
       end
 
       def normalize_deterministic_routes!(routes)

data/lib/smith/workflow/transition_actionability.rb

@@ -14,6 +14,8 @@ module Smith
           transition.nested?,
           transition.optimized?,
           transition.orchestrated?,
+          transition.awaits?,
+          transition.child_runs?,
           transition.success_transition
         ].any?
       end

data/lib/smith/workflow/usage_entry.rb

@@ -18,8 +18,14 @@ module Smith
     # non-provider error emits with `outcome: :aborted` before re-raising),
     # so prefix-accounted entries always have their join target.
     # All optional members are nil on entries restored from checkpoints written by
-    # earlier Smith versions, and nil attribution members are omitted from
+    # earlier Smith versions, and nil optional members are omitted from
     # serialization so those documents re-serialize byte-identically.
+    #
+    # `input_tokens` counts uncached input; `cache_read_tokens` and
+    # `cache_write_tokens` are the prompt-cache input beside it;
+    # `thinking_tokens` are already inside `output_tokens`. `stop_reason` and
+    # `provider_message_id` come from the provider response, and `mode` is
+    # how the call was made (`:sync`, `:stream`, `:batch`).
     # rubocop:disable Style/RedundantStructKeywordInit
     UsageEntry = Struct.new(
       :usage_id,
@@ -36,6 +42,12 @@ module Smith
       :round,
       :attempt_id,
       :workflow,
+      :cache_read_tokens,
+      :cache_write_tokens,
+      :thinking_tokens,
+      :stop_reason,
+      :provider_message_id,
+      :mode,
       keyword_init: true
     ) do
       def initialize(**attributes)
@@ -51,18 +63,27 @@ module Smith
       # re-serializes byte-identically. Hosts that digest whole persisted
       # documents (exact-mutation proofs) depend on this stability.
       def to_h
-        super.reject { |key, value| value.nil? && %i[transition branch_key round attempt_id workflow].include?(key) }
+        super.reject { |key, value| value.nil? && Workflow::UsageEntry::OPTIONAL_MEMBERS.include?(key) }
+      end
+
+      # Every input token the provider processed, cached or not, plus output.
+      def total_tokens
+        input_tokens + output_tokens + (cache_read_tokens || 0) + (cache_write_tokens || 0)
       end
 
       def self.from_h(hash)
         sym = hash.transform_keys(&:to_sym)
         filtered = sym.slice(*members)
-        %i[agent_name provider attempt_kind transition branch_key].each do |attribute|
+        %i[agent_name provider attempt_kind transition branch_key mode].each do |attribute|
           filtered[attribute] = filtered[attribute].to_sym if filtered[attribute].is_a?(String)
         end
         new(**filtered)
       end
     end
+    UsageEntry::OPTIONAL_MEMBERS = %i[
+      transition branch_key round attempt_id workflow
+      cache_read_tokens cache_write_tokens thinking_tokens stop_reason provider_message_id mode
+    ].freeze
     # rubocop:enable Style/RedundantStructKeywordInit
   end
 end

data/lib/smith/workflow/wait_completion.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require "time"
+
+require_relative "message_value_normalizer"
+
+module Smith
+  class Workflow
+    # Completing a wait, by delivery or expiry: claiming it so only one
+    # completion wins, running the completion as the step, and the timeout
+    # route. Part of WaitExecution, split out for size.
+    module WaitCompletion
+      private
+
+      # The awaited transition when the delivery matches the stored wait, or
+      # when no wait is stored yet but the run stands at that await and the
+      # token is the one entering it will use.
+      def resumable_transition(event, token)
+        record = @awaiting
+        return (awaited_transition(record) if record["event"] == event && record["token"] == token) if record
+
+        transition = pending_await_transition
+        return unless transition && transition.await_config[:event].to_s == event
+        return unless await_token_for(transition) == token
+
+        transition
+      end
+
+      def pending_await_transition
+        transition = self.class.find_transition(@next_transition_name || self.class.first_transition_from(@state)&.name)
+        transition if transition&.awaits? && !transition.delay? && [nil, @state].include?(transition.from)
+      end
+
+      def claim_wait
+        (@wait_mutex ||= Mutex.new).synchronize do
+          return nil if @wait_claimed
+
+          claimed = yield
+          @wait_claimed = true if claimed
+          claimed
+        end
+      end
+
+      def expire_claimed_wait(transition, record)
+        return end_retry_wait(transition) if record["kind"] == "retry"
+        return complete_batch_wait(transition, missing_batch_results(transition), :expired) if record["kind"] == "batch"
+
+        complete_claimed_wait(transition, :expired) { expire_step(transition, record) }
+      end
+
+      def complete_claimed_wait(transition, done, &)
+        step = finish_wait(transition, &)
+        step.key?(:error) && done == :resumed ? :failed : done
+      ensure
+        @wait_claimed = false
+      end
+
+      def expire_step(transition, record)
+        return StepCompletion.instance_method(:complete_step).bind_call(self, transition, nil) if transition.delay?
+        return route_to_timeout!(transition) if transition.timeout_transition
+
+        raise WaitTimedOut.new(transition: transition.name, event: record["event"], deadline_at: record["deadline_at"])
+      end
+
+      # The await ends without reaching its `to:`; the run stays in its
+      # `from:` state and takes `on_timeout` next. Hosts see a StepCompleted
+      # whose `to` is that state.
+      def route_to_timeout!(transition)
+        name = transition.timeout_transition
+        target = self.class.find_transition(name) || raise(UnresolvedTransitionError.new(name, self.class, @state))
+        validate_transition_origin!(target)
+        @next_transition_name = name
+        record_wait_trace(transition, :timed_out)
+        emit_step_completed(TimedOutStep.new(transition.name, transition.from, @state), nil)
+        { transition: transition.name, from: transition.from, to: @state, timed_out: true }
+      end
+
+      TimedOutStep = Struct.new(:name, :from, :to)
+      private_constant :TimedOutStep
+
+      # A payload is bounded and JSON-shaped like a session message, and
+      # takes the context's key shape. It never enters the session.
+      def wait_payload(payload)
+        ContextKeys.normalize(MessageValueNormalizer.new(payload, label: "wait payload").call)
+      end
+
+      # Returns nil, the inline-resolved step's output.
+      def write_wait_payload(transition, value)
+        key = writable_wait_key!(transition)
+        @context[key] = value
+        record_persisted_key!(key)
+        nil
+      end
+
+      def writable_wait_key!(transition)
+        key = transition.await_config.fetch(:into)
+        keys = declared_persist_keys
+        raise UndeclaredContextKey.new(key:, persisted_keys: keys) if keys && !keys.include?(key)
+
+        key
+      end
+
+      def wait_time(now)
+        return now.utc if now.is_a?(Time)
+        return Time.iso8601(now).utc if now.is_a?(String)
+        return now.to_time.utc if now.respond_to?(:to_time)
+
+        raise ArgumentError, "now: must be a Time or an ISO 8601 String"
+      end
+
+      def wait_deadline(record) = Time.iso8601(record.fetch("deadline_at"))
+
+      # The completion of a wait is the step: it runs in the step's context
+      # (so its position, attribution and events are the step's), then
+      # counts. A completion that raises leaves the run waiting.
+      def finish_wait(transition, &)
+        step = with_step_context(transition, &)
+        @awaiting = nil
+        @step_count += 1
+        @updated_at = Time.now.utc.iso8601(6)
+        record_step_snapshot(step)
+        step
+      end
+
+      def awaited_transition(record)
+        self.class.transition_named(record.fetch("transition")) ||
+          raise(WorkflowError, "the awaited transition is not declared")
+      end
+    end
+  end
+end