smith-agents 0.11.0 → 0.12.0

data/lib/smith/workflow/composite/effects.rb

@@ -20,15 +20,17 @@ module Smith
         # Required keys are the pre-attribution UsageEntry shape, so effects
         # produced by an older Smith (a mid-deploy branch worker or a
         # restored checkpoint) stay valid; allowed keys are the current
-        # member set, so unknown keys still reject. The attribution members
-        # (transition, branch_key, round, attempt_id) are optional by
-        # construction.
+        # member set, so unknown keys still reject. UsageEntry::OPTIONAL_MEMBERS
+        # (the attribution members, the cache and thinking counts, the
+        # response facts and mode) are optional by construction.
         USAGE_ALLOWED_ATTRIBUTES = Workflow::UsageEntry.members.map(&:to_s).freeze
         USAGE_REQUIRED_ATTRIBUTES =
-          (USAGE_ALLOWED_ATTRIBUTES - %w[transition branch_key round attempt_id workflow]).freeze
+          (USAGE_ALLOWED_ATTRIBUTES - Workflow::UsageEntry::OPTIONAL_MEMBERS.map(&:to_s)).freeze
+        USAGE_COUNT_ATTRIBUTES = %w[cache_read_tokens cache_write_tokens thinking_tokens].freeze
+        USAGE_MODES = %w[sync stream batch].freeze
         TOOL_REQUIRED_ATTRIBUTES = %w[tool captured].freeze
         TOOL_ALLOWED_ATTRIBUTES = (TOOL_REQUIRED_ATTRIBUTES + %w[tool_call_id]).freeze
-        private_constant :USAGE_ALLOWED_ATTRIBUTES, :USAGE_REQUIRED_ATTRIBUTES,
+        private_constant :USAGE_ALLOWED_ATTRIBUTES, :USAGE_REQUIRED_ATTRIBUTES, :USAGE_COUNT_ATTRIBUTES, :USAGE_MODES,
                          :TOOL_REQUIRED_ATTRIBUTES, :TOOL_ALLOWED_ATTRIBUTES
 
         attribute :usage_entries, Types::Array
@@ -55,6 +57,7 @@ module Smith
             validate_bounded_keys!(entry, USAGE_REQUIRED_ATTRIBUTES, USAGE_ALLOWED_ATTRIBUTES, "composite usage entry")
             validate_usage_identity!(entry)
             validate_usage_attribution!(entry)
+            validate_usage_details!(entry)
             validate_usage_amount!(entry.fetch("input_tokens"), "input_tokens")
             validate_usage_amount!(entry.fetch("output_tokens"), "output_tokens")
             validate_cost!(entry.fetch("cost"))
@@ -63,7 +66,7 @@ module Smith
         end
 
         def usage_totals(entries)
-          tokens = entries.sum { _1.fetch("input_tokens") + _1.fetch("output_tokens") }
+          tokens = entries.sum { entry_tokens(_1) }
           if tokens > PreparedStep::MAX_COUNTER_VALUE
             raise ArgumentError, "composite usage token total exceeds the signed 64-bit limit"
           end
@@ -76,6 +79,11 @@ module Smith
           [tokens, cost]
         end
 
+        def entry_tokens(entry)
+          %w[input_tokens output_tokens].sum { entry.fetch(_1) } +
+            %w[cache_read_tokens cache_write_tokens].sum { entry.fetch(_1, 0) }
+        end
+
         def validate_usage_identity!(entry)
           validate_uuid!(entry.fetch("usage_id"), "composite usage entry usage_id")
           # agent_name and provider are nil-allowed; any other value
@@ -101,6 +109,21 @@ module Smith
           validate_uuid!(entry.fetch("attempt_id"), "composite usage entry attempt_id") if entry.key?("attempt_id")
         end
 
+        # Optional usage details, bounded like the attribution keys: counts
+        # are non-negative Integers, response facts bounded Strings, and the
+        # mode one of the three call modes.
+        def validate_usage_details!(entry)
+          USAGE_COUNT_ATTRIBUTES.each do |key|
+            validate_usage_amount!(entry.fetch(key), key) if entry.key?(key)
+          end
+          %w[stop_reason provider_message_id].each do |key|
+            validate_bounded_bytes!(entry.fetch(key), "composite usage entry #{key}", 256) if entry.key?(key)
+          end
+          return if !entry.key?("mode") || USAGE_MODES.include?(entry.fetch("mode"))
+
+          raise ArgumentError, "composite usage entry mode is invalid"
+        end
+
         def validate_uuid!(value, label)
           return if value.is_a?(String) && PreparedStep::UUID_PATTERN.match?(value)
 
@@ -113,6 +136,14 @@ module Smith
           raise ArgumentError, "#{label} must be a bounded non-empty String"
         end
 
+        # Response facts are bounded in bytes where they are read, so they
+        # are checked in bytes here.
+        def validate_bounded_bytes!(value, label, max_bytes)
+          return if value.is_a?(String) && value.bytesize.between?(1, max_bytes)
+
+          raise ArgumentError, "#{label} must be a non-empty String of at most #{max_bytes} bytes"
+        end
+
         def validate_nonempty_string!(value, label)
           return if value.is_a?(String) && !value.empty?
 

data/lib/smith/workflow/composite/error.rb

@@ -10,7 +10,7 @@ module Smith
       class Error < Payload
         FAMILIES = %w[
           tool_capture_failed tool_guardrail_failed deterministic_step_failure
-          deadline_exceeded agent_error workflow_error other
+          deadline_exceeded agent_error workflow_error output_failure other
         ].freeze
         ALWAYS_RETRYABLE_FAMILIES = %w[deadline_exceeded agent_error].freeze
         CONDITIONALLY_RETRYABLE_FAMILIES = %w[tool_guardrail_failed deterministic_step_failure].freeze

data/lib/smith/workflow/composite/error_evidence.rb

@@ -3,6 +3,7 @@
 require "dry-initializer"
 
 require_relative "../../errors"
+require_relative "../../output_failure"
 require_relative "../../tool_capture_failed"
 require_relative "error"
 
@@ -10,6 +11,13 @@ module Smith
   class Workflow
     module Composite
       class ErrorEvidence
+        FAMILIES = [
+          [ToolCaptureFailed, "tool_capture_failed"], [ToolGuardrailFailed, "tool_guardrail_failed"],
+          [DeterministicStepFailure, "deterministic_step_failure"], [DeadlineExceeded, "deadline_exceeded"],
+          [OutputFailure, "output_failure"], [AgentError, "agent_error"], [WorkflowError, "workflow_error"]
+        ].freeze
+        private_constant :FAMILIES
+
         extend Dry::Initializer
 
         param :error
@@ -49,15 +57,7 @@ module Smith
         end
 
         def error_family
-          case error
-          when ToolCaptureFailed then "tool_capture_failed"
-          when ToolGuardrailFailed then "tool_guardrail_failed"
-          when DeterministicStepFailure then "deterministic_step_failure"
-          when DeadlineExceeded then "deadline_exceeded"
-          when AgentError then "agent_error"
-          when WorkflowError then "workflow_error"
-          else "other"
-          end
+          FAMILIES.find { |error_class, _family| error.is_a?(error_class) }&.last || "other"
         end
 
         def tool_capture_metadata

data/lib/smith/workflow/composite/input.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "../../types"
+require_relative "../message_roles"
 require_relative "../message_value_normalizer"
 require_relative "../prepared_step"
 require_relative "payload"
@@ -37,10 +38,16 @@ module Smith
           private
 
           def normalized_values(agent_messages:, session_messages:)
-            {
-              agent_messages: normalize(agent_messages),
-              session_messages: normalize(session_messages)
-            }.freeze
+            values = { agent_messages: normalize(agent_messages), session_messages: normalize(session_messages) }.freeze
+            values.each_value { |messages| check_roles!(messages) }
+            values
+          end
+
+          def check_roles!(messages)
+            return unless messages.is_a?(Array)
+            return if messages.all? { |message| MessageRoles.role(message) }
+
+            raise WorkflowError, "composite input messages must have the role system, user, assistant or tool"
           end
 
           def normalize(value)

data/lib/smith/workflow/context_keys.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require_relative "../diagnostic_text"
+
+module Smith
+  class Workflow
+    # The one shape a workflow context has everywhere: top-level keys are
+    # Symbols, and every Hash key inside a value is the Symbol of its String
+    # form, which is exactly what a JSON checkpoint and restore produce, so a
+    # key reads the same live and after a round trip. Values are not
+    # converted; only JSON-native values (Strings, numbers, booleans, nil,
+    # Hashes, Arrays) round-trip unchanged.
+    module ContextKeys
+      # JSON's own default nesting limit: a deeper context could not be
+      # checkpointed anyway.
+      MAX_DEPTH = 100
+
+      module_function
+
+      # A context given to `Workflow.new` or to a class-level helper that
+      # derives a persistence key from it. Top-level keys must already be
+      # Symbols, the rule `write_context` applies to every key it writes.
+      def normalize_context(context)
+        raise WorkflowError, "workflow context must be a Hash, got #{context.class}" unless context.is_a?(Hash)
+
+        context.each_key { |key| validate_top_level_key!(key) }
+        normalize(context)
+      end
+
+      def validate_top_level_key!(key)
+        return if key.is_a?(Symbol)
+
+        raise WorkflowError,
+              "workflow context keys must be Symbols, got #{bounded(key.inspect)} (#{key.class}); " \
+              "convert them before building the workflow"
+      end
+
+      # A copy of `value` with every Hash key at every depth turned into the
+      # Symbol of its String form. Raises WorkflowError when two keys of one
+      # Hash become the same Symbol, when a container contains itself, or
+      # past MAX_DEPTH. `O(N)` in the number of Hash entries and Array
+      # elements.
+      def normalize(value, path = {}.compare_by_identity, depth = 0)
+        case value
+        when Hash then within(value, path, depth) { normalize_hash(value, path, depth) }
+        when Array then within(value, path, depth) { value.map { |item| normalize(item, path, depth + 1) } }
+        else value
+        end
+      end
+
+      def normalize_hash(hash, path, depth)
+        hash.each_with_object({}) do |(key, nested), normalized|
+          symbol = key.is_a?(Symbol) ? key : key.to_s.to_sym
+          if normalized.key?(symbol)
+            raise WorkflowError, "workflow context has two keys that both become #{bounded(symbol.inspect)}"
+          end
+
+          normalized[symbol] = normalize(nested, path, depth + 1)
+        end
+      end
+
+      def within(container, path, depth)
+        raise WorkflowError, "workflow context is nested deeper than #{MAX_DEPTH} levels" if depth > MAX_DEPTH
+        raise WorkflowError, "workflow context contains itself" if path.key?(container)
+
+        path[container] = true
+        begin
+          yield
+        ensure
+          path.delete(container)
+        end
+      end
+
+      def bounded(text) = DiagnosticText.capture(text, max_bytes: 256)
+    end
+  end
+end

data/lib/smith/workflow/deadline_enforcement.rb

@@ -123,7 +123,7 @@ module Smith
 
       def compute_wall_clock_deadline
         limit = self.class.budget&.dig(:wall_clock)
-        own_deadline = limit ? Time.iso8601(@created_at) + limit : nil
+        own_deadline = limit ? active_deadline(limit) : nil
 
         return own_deadline unless @inherited_deadline
         return @inherited_deadline unless own_deadline

data/lib/smith/workflow/deterministic_execution.rb

@@ -8,19 +8,56 @@ module Smith
       def execute_deterministic_step(transition)
         check_deadline!
         step = build_deterministic_step(transition)
-        emit_deterministic_trace(transition, result: :started)
+        emit_deterministic_trace(transition, outcome: :started)
         transition.deterministic_block.call(step)
+        finish_deterministic_step!(transition, step)
+        nil
+      rescue StandardError => e
+        emit_deterministic_trace(transition, outcome: :failed, failure: deterministic_failure_fields(transition, e))
+        raise
+      end
+
+      # A write the step body rescued still fails the step, a declared route
+      # must be taken, and only then are writes applied and success traced.
+      def finish_deterministic_step!(transition, step)
+        raise step.write_violation if step.write_violation
+
+        ensure_deterministic_routed!(transition, step)
         apply_deterministic_writes!(step)
         emit_deterministic_trace(
           transition,
-          result: step.routed_to ? :routed : :success,
+          outcome: step.routed_to ? :routed : :success,
           routed_to: step.routed_to,
           outcome_kind: step.outcome&.dig(:kind)
         )
-        nil
-      rescue StandardError => e
-        emit_deterministic_trace(transition, result: :failed, error: e.message)
-        raise
+      end
+
+      # The bounded classification failed :transition traces carry, never
+      # the raw message, which may hold content. Skipped when nothing would
+      # record the trace, and never allowed to replace the step's own error.
+      def deterministic_failure_fields(transition, error)
+        return {} unless Smith::Trace.resolve_adapter
+
+        failure = FailureRecord.capture({ transition: transition.name, from: transition.from, to: transition.to,
+                                          error: error })
+        fields = { error_class: failure[:error_class], error_family: failure[:error_family] }
+        fields[:retryable] = failure[:error_retryable] unless failure[:error_retryable].nil?
+        fields
+      rescue StandardError
+        { error_class: DiagnosticText.error_class_name(error) }
+      end
+
+      # A step declaring `routes:` must route, unless it declares `on_success`,
+      # opts into `fallthrough: true`, or its target state has no outgoing
+      # transition (the run then ends there, as declared); otherwise the run
+      # would silently take the first transition from the target state.
+      # Raised before any write is applied, like any failing step.
+      def ensure_deterministic_routed!(transition, step)
+        return if step.routed_to || transition.deterministic_routes.nil?
+        return if transition.deterministic_fallthrough || transition.success_transition
+        return unless self.class.transition_from?(transition.to)
+
+        raise UnroutedDeterministicStep.new(transition: transition.name, routes: transition.deterministic_routes)
       end
 
       def build_deterministic_step(transition)
@@ -30,10 +67,21 @@ module Smith
           tool_results: snapshot_value(@tool_results || []),
           state: @state,
           transition: transition,
-          last_agent_execution: snapshot_value(@last_agent_execution)
+          last_agent_execution: snapshot_value(@last_agent_execution),
+          last_output: snapshot_value(@last_output),
+          persisted_keys: declared_persist_keys,
+          idempotency_scope: IdempotencyKey.__send__(:current_scope),
+          attempt: @step_attempt || 1
         )
       end
 
+      # The explicit `persist :a, :b` list a deterministic write must stay
+      # within, or nil when the workflow declares none or uses `persist :auto`.
+      def declared_persist_keys
+        keys = resolve_persist_keys
+        keys.is_a?(Array) ? keys : nil
+      end
+
       def apply_deterministic_writes!(step)
         @context.merge!(step.context_writes)
         step.context_writes.each_key { |key| record_persisted_key!(key) }
@@ -41,11 +89,14 @@ module Smith
         @outcome = symbolize_value(snapshot_value(step.outcome)) if step.outcome
       end
 
-      def emit_deterministic_trace(transition, result:, routed_to: nil, error: nil, outcome_kind: nil)
+      # `outcome`, not `result`: `result` is a reserved content key that the
+      # default content policy strips, matching the :transition and
+      # :provider_call vocabulary.
+      def emit_deterministic_trace(transition, outcome:, routed_to: nil, failure: nil, outcome_kind: nil)
         data = { transition: transition.name, from: transition.from, to: transition.to,
-                 kind: transition.deterministic_kind, result: result }
+                 kind: transition.deterministic_kind, outcome: outcome }
         data[:routed_to] = routed_to if routed_to
-        data[:error] = error if error
+        data.merge!(failure) if failure
         data[:outcome_kind] = outcome_kind if outcome_kind
         Smith::Trace.record(type: :deterministic_step, data: data)
       end

data/lib/smith/workflow/deterministic_step.rb

@@ -4,7 +4,9 @@ module Smith
   class Workflow
     class DeterministicStep
       attr_reader :context, :tool_results, :session_messages, :current_state, :transition_name,
-                  :context_writes, :routed_to, :outcome, :allowed_routes
+                  :context_writes, :routed_to, :outcome, :allowed_routes, :write_violation
+      # The attempt under way, from 1; above 1 only under `retry_on`.
+      attr_reader :attempt
 
       def initialize(context:, session_messages:, tool_results:, state:, **options)
         validate_options!(options)
@@ -15,7 +17,7 @@ module Smith
         @current_state = state
         @transition_name = transition ? transition.name : options.fetch(:transition_name)
         @allowed_routes = snapshot_allowed_routes(transition ? transition.deterministic_routes : options[:allowed_routes])
-        @last_agent_execution = options[:last_agent_execution]
+        assign_execution_facts(options)
         @context_writes = {}
         @routed_to = nil
         @outcome = nil
@@ -33,7 +35,11 @@ module Smith
         @last_agent_execution && @last_agent_execution[:provider]
       end
 
+      # The output of the most recent step that produced one, whether it
+      # went to the transcript or to an `output_to:` key; before any step
+      # has, the last assistant message in the transcript.
       def last_output
+        return @step_output unless @step_output.nil?
         return @last_output if defined?(@last_output)
 
         msg = session_messages.reverse.find { |m| (m[:role] || m["role"]).to_s == "assistant" }
@@ -46,10 +52,27 @@ module Smith
         @context_writes.key?(key) ? @context_writes[key] : context[key]
       end
 
+      # The value is stored in the context's key shape at once, so a
+      # `read_context` later in the same step sees what the next step will.
+      # A rejected write is remembered as well as raised, so a `rescue` in
+      # the step body cannot turn it into a silently dropped write.
       def write_context(key, value)
         raise WorkflowError, "write_context key must be a Symbol, got #{key.class}" unless key.is_a?(Symbol)
 
-        @context_writes[key] = value
+        if @persisted_keys && !@persisted_keys.include?(key)
+          reject_write!(UndeclaredContextKey.new(key:, persisted_keys: @persisted_keys))
+        end
+
+        @context_writes[key] = begin
+          ContextKeys.normalize(value)
+        rescue WorkflowError => e
+          reject_write!(e)
+        end
+      end
+
+      def reject_write!(error)
+        @write_violation ||= error
+        raise error
       end
 
       def route_to(transition_name)
@@ -65,14 +88,40 @@ module Smith
         @outcome = { kind: kind, payload: payload }
       end
 
-      def fail!(message, retryable: nil, kind: nil, details: nil)
-        raise DeterministicStepFailure.new(message, retryable: retryable, kind: kind, details: details)
+      def fail!(message, retryable: nil, kind: nil, details: nil, new_idempotency_key: false)
+        unless [true, false, nil].include?(new_idempotency_key)
+          raise ArgumentError, "fail! new_idempotency_key must be true or false"
+        end
+
+        raise DeterministicStepFailure.new(message, retryable:, kind:, details:, new_idempotency_key:,
+                                                    idempotency_scope: @idempotency_scope)
+      end
+
+      # A key for a request this step sends outside the system: the same on
+      # every attempt of the step and after a restore, unique to this run,
+      # step and `scope`. Use a scope to tell apart several requests of one
+      # step. See Smith::IdempotencyKey.
+      def idempotency_key(scope = nil)
+        unless @idempotency_scope
+          raise WorkflowError, "an idempotency key is only available inside a running workflow step"
+        end
+
+        @idempotency_scope.key(scope)
       end
 
       private
 
+      def assign_execution_facts(options)
+        @last_agent_execution = options[:last_agent_execution]
+        @step_output = options[:last_output]
+        @persisted_keys = options[:persisted_keys]&.dup&.freeze
+        @idempotency_scope = options[:idempotency_scope]
+        @attempt = options.fetch(:attempt, 1)
+      end
+
       def validate_options!(options)
-        unknown = options.keys - %i[transition transition_name allowed_routes last_agent_execution]
+        unknown = options.keys - %i[transition transition_name allowed_routes last_agent_execution last_output
+                                    persisted_keys idempotency_scope attempt]
         raise ArgumentError, "unknown keywords: #{unknown.join(", ")}" if unknown.any?
         return if options[:transition] || options.key?(:transition_name)
 

data/lib/smith/workflow/dsl.rb

@@ -24,6 +24,8 @@ module Smith
           subclass.instance_variable_set(:@transition_sequence, @transition_sequence)
           subclass.instance_variable_set(:@initial_state_name, @initial_state_name)
           subclass.instance_variable_set(:@budget_config, @budget_config&.dup)
+          subclass.instance_variable_set(:@budget_ledger_builder, @budget_ledger_builder)
+          subclass.instance_variable_set(:@budget_ledger_scope_keys, @budget_ledger_scope_keys)
           subclass.instance_variable_set(:@max_transitions_count, @max_transitions_count)
           subclass.instance_variable_set(:@guardrails_class, @guardrails_class)
           subclass.instance_variable_set(:@context_manager_class, @context_manager_class)
@@ -33,6 +35,7 @@ module Smith
           subclass.instance_variable_set(:@migrations, (@migrations || {}).dup)
           subclass.instance_variable_set(:@seed_validation_mode, @seed_validation_mode)
           subclass.instance_variable_set(:@idempotency_mode, @idempotency_mode)
+          subclass.instance_variable_set(:@session_mode, @session_mode)
           subclass.instance_variable_set(:@persistence_ttl, @persistence_ttl)
         end
 
@@ -76,6 +79,23 @@ module Smith
           @budget_config = opts
         end
 
+        # The host's budget ledger for a run (Budget::HostLedger): the block
+        # gets the run's scope, the values `scope_keys` have in its trusted
+        # context when it is created, kept with the run, and returns the
+        # ledger, or nil for none. It is built at the first request a step
+        # makes, never persisted. Each provider request a step makes is held
+        # on it first.
+        def budget_ledger(*scope_keys, &block)
+          return @budget_ledger_builder if scope_keys.empty? && !block
+          raise ArgumentError, "budget_ledger needs a block that returns the ledger" unless block
+          raise ArgumentError, "budget_ledger scope keys must be Symbols" unless scope_keys.all?(Symbol)
+
+          @budget_ledger_scope_keys = scope_keys.uniq.freeze
+          @budget_ledger_builder = block
+        end
+
+        def budget_ledger_scope_keys = @budget_ledger_scope_keys || []
+
         def max_transitions(count = nil)
           return @max_transitions_count if count.nil?
 
@@ -185,6 +205,20 @@ module Smith
         #            set, indicating a previous worker crashed mid-step
         #            and re-running could double-execute non-idempotent
         #            agent calls or tools.
+        # `:shared` (the default) keeps one transcript: each agent step sees
+        # the session and its accepted output is appended to it. `:isolated`
+        # keeps no transcript for agents: every agent step must declare
+        # `input:`, its output is never appended, and `inject_state` does
+        # not run for it.
+        def session(mode = nil)
+          return @session_mode || :shared if mode.nil?
+          unless %i[shared isolated].include?(mode)
+            raise ArgumentError, "session must be :shared or :isolated, got #{mode.inspect}"
+          end
+
+          @session_mode = mode
+        end
+
         def idempotency_mode(mode = nil)
           return @idempotency_mode || :lax if mode.nil?
 
@@ -238,6 +272,31 @@ module Smith
           (@transitions || {})[name]
         end
 
+        # The transition whose name has this String form, for a name read
+        # back from a payload. `O(T)`.
+        def transition_named(name)
+          return if name.nil?
+
+          find_transition(name) ||
+            (@transitions || {}).each_value.find { |transition| transition.name.to_s == name.to_s }
+        end
+
+        # A state this class can hold: declared with `state` (or
+        # `initial_state`), or named by any transition's `from:` or `to:`.
+        # Matched by String form, so a payload's "prepared" finds a state
+        # declared as :prepared or "prepared". `O(S + T)`.
+        def known_state?(name) = !resolve_state_name(name).nil?
+
+        # The identifier this class declares for `name` (matched by String
+        # form), or nil when the class knows no such state.
+        def resolve_state_name(name)
+          return if name.nil?
+
+          wanted = name.to_s
+          candidates = (@states || []) + (@transitions || {}).each_value.flat_map { |t| [t.from, t.to] }
+          candidates.find { |candidate| !candidate.nil? && candidate.to_s == wanted }
+        end
+
         def transition_at(index)
           (@transitions || {}).values.fetch(index)
         end