smith-agents 0.6.1 → 0.8.0

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

@@ -3,6 +3,7 @@
 require "dry-initializer"
 
 require_relative "../../errors"
+require_relative "../../tool_capture_failed"
 require_relative "error"
 
 module Smith
@@ -16,12 +17,14 @@ module Smith
         def self.call(error) = new(error).call
 
         def call
-          Error.new(
+          attributes = {
             class_name: error_class_name,
             family: error_family,
             retryable: retryable_error?,
             kind: error_kind
-          )
+          }
+          attributes.merge!(tool_capture_metadata) if error.is_a?(ToolCaptureFailed)
+          Error.new(attributes)
         end
 
         private
@@ -47,6 +50,7 @@ module Smith
 
         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"
@@ -55,6 +59,10 @@ module Smith
           else "other"
           end
         end
+
+        def tool_capture_metadata
+          { tool_name: error.tool_name, reason: error.reason.to_s }
+        end
       end
     end
   end

data/lib/smith/workflow/deadline_enforcement.rb

@@ -25,7 +25,7 @@ module Smith
         saved_deadline = Tool.current_deadline
         saved_call_ledger = Thread.current[:smith_call_ledger]
         snapshot = ThreadContextSnapshot.new(
-          tool_attributes: %i[current_deadline current_tool_call_allowance],
+          tool_attributes: %i[current_deadline current_tool_call_allowance current_tool_execution_tracker],
           thread_keys: %i[smith_call_deadline smith_call_ledger],
           scoped_artifacts: false
         )
@@ -41,6 +41,7 @@ module Smith
         apply_agent_deadline(agent_class)
         narrow_tool_deadline!
         apply_agent_tool_calls(agent_class)
+        Tool.current_tool_execution_tracker ||= Tool::ExecutionTracker.new
         apply_agent_call_ledger(agent_class)
       end
 
@@ -49,6 +50,7 @@ module Smith
         Thread.current[:smith_call_ledger] = call_ledger
         clear_agent_deadline
         clear_agent_tool_calls
+        Tool.current_tool_execution_tracker = nil
       end
 
       def effective_call_ledger
@@ -74,7 +76,23 @@ module Smith
 
       def apply_agent_tool_calls(agent_class)
         agent_tc = agent_class&.budget&.dig(:tool_calls)
-        Tool.current_tool_call_allowance = agent_tc ? { remaining: agent_tc } : nil
+        if agent_class&.tool_budget_exhaustion == :complete && agent_tc.nil?
+          raise AgentError, "tool_budget_exhaustion :complete requires a finite tool_calls budget"
+        end
+
+        Tool.current_tool_call_allowance = build_agent_tool_call_allowance(agent_class, agent_tc)
+      end
+
+      def build_agent_tool_call_allowance(agent_class, agent_tool_calls)
+        return unless agent_tool_calls
+
+        parent = Tool.current_tool_call_allowance
+        if parent && !parent.is_a?(Tool::CallAllowance)
+          raise AgentError, "agent tool_calls budgets cannot scope a legacy Hash tool call allowance"
+        end
+        return parent.scope(agent_tool_calls, on_exhaustion: agent_class.tool_budget_exhaustion) if parent
+
+        Tool::CallAllowance.new(agent_tool_calls, on_exhaustion: agent_class.tool_budget_exhaustion)
       end
 
       def clear_agent_tool_calls

data/lib/smith/workflow/execution.rb

@@ -2,6 +2,7 @@
 
 require_relative "agent_result"
 require_relative "execution_binding_resolution"
+require_relative "guarded_step_execution"
 require_relative "prepared_branch_execution"
 require_relative "step_completion"
 require_relative "step_context"
@@ -10,6 +11,7 @@ module Smith
   class Workflow
     module Execution
       include ExecutionBindingResolution
+      include GuardedStepExecution
       include PreparedBranchExecution
       include StepCompletion
       include StepContext
@@ -39,15 +41,6 @@ module Smith
         Tool.current_tool_result_collector = tool_result_collector
       end
 
-      def run_guarded_step(transition)
-        return apply_composite_reduction!(transition) if @composite_reduction
-
-        @resolved_parallel_branch_count = preflight_branch_count(transition)
-        run_standard_guarded_step(transition)
-      ensure
-        @resolved_parallel_branch_count = nil
-      end
-
       def run_standard_guarded_step(transition)
         return dispatch_step(transition) if transition.deterministic?
         return run_guarded_fanout_step(transition) if transition.fanout?

data/lib/smith/workflow/failure_detail_snapshot.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+require "json"
+
+require_relative "../diagnostic_text"
+require_relative "message_value_normalizer"
+
+module Smith
+  class Workflow
+    class FailureDetailSnapshot
+      OMITTED_KEY = "smith_failure_details_omitted"
+      OMITTED_REASON_BYTES = 1_024
+      private_constant :OMITTED_KEY, :OMITTED_REASON_BYTES
+
+      extend Dry::Initializer
+
+      param :value
+
+      def call
+        return if value.nil?
+
+        snapshot = MessageValueNormalizer.new(value, label: "workflow failure details").call
+        JSON.generate(snapshot)
+        snapshot
+      rescue StandardError => e
+        {
+          OMITTED_KEY => DiagnosticText.capture(e.message, max_bytes: OMITTED_REASON_BYTES)
+        }.freeze
+      end
+    end
+  end
+end

data/lib/smith/workflow/failure_reconstructor.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+require_relative "../errors"
+require_relative "failure_record_validator"
+
+module Smith
+  class Workflow
+    class FailureReconstructor
+      FAMILY_BUILDERS = {
+        "deterministic_step_failure" => ->(record) { deterministic_step_failure(record) },
+        "tool_guardrail_failed" => ->(record) { tool_guardrail_failure(record) },
+        "tool_failure_notification_failed" => ->(record) { tool_failure_notification_failure(record) },
+        "tool_capture_failed" => ->(record) { Smith::ToolCaptureFailed.from_details(record.fetch(:error_details)) },
+        "tool_outcome_uncertain" => ->(record) { Smith::ToolOutcomeUncertain.new(record[:error_message]) },
+        "tool_execution_not_admitted" => ->(record) { Smith::ToolExecutionNotAdmitted.new(record[:error_message]) },
+        "bounded_completion_error" => ->(record) { Smith::BoundedCompletionError.new(record[:error_message]) },
+        "persisted_failure_invalid" => ->(record) { Smith::PersistedFailureInvalid.new(record[:error_message]) },
+        "deadline_exceeded" => ->(record) { Smith::DeadlineExceeded.new(record[:error_message]) },
+        "agent_error" => ->(record) { Smith::AgentError.new(record[:error_message]) },
+        "workflow_error" => ->(record) { Smith::WorkflowError.new(record[:error_message]) },
+        "other" => ->(record) { RuntimeError.new(record[:error_message]) }
+      }.freeze
+      SPECIAL_CLASS_BUILDERS = {
+        "Smith::Workflow::Composite::BranchFailure" => lambda { |record|
+          Smith::Workflow::Composite::BranchFailure.from_details(record[:error_details])
+        }
+      }.freeze
+      private_constant :FAMILY_BUILDERS, :SPECIAL_CLASS_BUILDERS
+
+      extend Dry::Initializer
+
+      option :snapshot
+      option :transition_normalizer
+      option :state_normalizer
+
+      def call
+        {
+          transition: transition_normalizer.call(snapshot[:transition]),
+          from: state_normalizer.call(snapshot[:from]),
+          to: state_normalizer.call(snapshot[:to]),
+          error: reconstruct_error
+        }
+      end
+
+      private
+
+      def reconstruct_error
+        FailureRecordValidator.new(snapshot).call
+        builder = SPECIAL_CLASS_BUILDERS[snapshot[:error_class]] || FAMILY_BUILDERS.fetch(snapshot[:error_family])
+        builder.call(snapshot)
+      rescue Smith::PersistedFailureInvalid
+        raise
+      rescue ArgumentError, KeyError, TypeError
+        raise Smith::PersistedFailureInvalid, "persisted workflow failure details are invalid"
+      end
+
+      def self.deterministic_step_failure(record)
+        Smith::DeterministicStepFailure.new(
+          record[:error_message],
+          retryable: record[:error_retryable],
+          kind: record[:error_kind],
+          details: record[:error_details]
+        )
+      end
+
+      def self.tool_guardrail_failure(record)
+        Smith::ToolGuardrailFailed.new(record[:error_message], retryable: record[:error_retryable])
+      end
+
+      def self.tool_failure_notification_failure(record)
+        Smith::ToolFailureNotificationFailed.from_details(record.fetch(:error_details))
+      end
+
+      private_class_method :deterministic_step_failure, :tool_guardrail_failure, :tool_failure_notification_failure
+    end
+  end
+end

data/lib/smith/workflow/failure_record.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+require_relative "../diagnostic_text"
+require_relative "../errors"
+require_relative "failure_detail_snapshot"
+require_relative "failure_record_text"
+
+module Smith
+  class Workflow
+    class FailureRecord
+      ERROR_FAMILIES = [
+        [Smith::DeterministicStepFailure, "deterministic_step_failure"],
+        [Smith::ToolFailureNotificationFailed, "tool_failure_notification_failed"],
+        [Smith::ToolCaptureFailed, "tool_capture_failed"],
+        [Smith::ToolOutcomeUncertain, "tool_outcome_uncertain"],
+        [Smith::ToolExecutionNotAdmitted, "tool_execution_not_admitted"],
+        [Smith::BoundedCompletionError, "bounded_completion_error"],
+        [Smith::PersistedFailureInvalid, "persisted_failure_invalid"],
+        [Smith::ToolGuardrailFailed, "tool_guardrail_failed"],
+        [Smith::DeadlineExceeded, "deadline_exceeded"],
+        [Smith::AgentError, "agent_error"],
+        [Smith::WorkflowError, "workflow_error"]
+      ].freeze
+      BOOLEAN_VALUES = [true, false].freeze
+      EXCEPTION_CAUSE = Exception.instance_method(:cause)
+      EXCEPTION_MESSAGE = Exception.instance_method(:message)
+      MODULE_MATCH = Module.instance_method(:===)
+      MODULE_NAME = Module.instance_method(:name)
+      OBJECT_CLASS = Object.instance_method(:class)
+      private_constant :ERROR_FAMILIES, :BOOLEAN_VALUES, :EXCEPTION_CAUSE, :EXCEPTION_MESSAGE, :MODULE_MATCH,
+                       :MODULE_NAME, :OBJECT_CLASS
+
+      extend Dry::Initializer
+
+      option :step_result
+
+      def self.capture(step_result) = new(step_result:).call
+
+      def call
+        error = step_result.fetch(:error)
+        {
+          transition: step_result[:transition],
+          from: step_result[:from],
+          to: step_result[:to],
+          **error_attributes(error)
+        }.freeze
+      end
+
+      private
+
+      def error_attributes(error)
+        {
+          error_class: DiagnosticText.capture(error_class_name(error), max_bytes: 512),
+          error_family: error_family(error),
+          error_message: error_message(error),
+          error_retryable: retryable_value(error),
+          error_retry_forbidden: Smith::Errors.retry_forbidden?(error),
+          error_kind: error_kind(error),
+          error_details: error_details(error),
+          **cause_attributes(error)
+        }
+      end
+
+      # Uncertainty wrappers replace the causal failure at the transition
+      # boundary; without this classification a restored host cannot
+      # distinguish a deadline, cancellation, or defect behind an
+      # uncertain tool outcome.
+      def cause_attributes(error)
+        cause = uncertainty_cause(error)
+        {
+          error_cause_class: cause && DiagnosticText.capture(error_class_name(cause), max_bytes: 512),
+          error_cause_family: cause && error_family(cause),
+          error_cause_message: cause && error_message(cause)
+        }
+      end
+
+      def uncertainty_cause(error)
+        return unless MODULE_MATCH.bind_call(Smith::ToolOutcomeUncertain, error)
+
+        cause = EXCEPTION_CAUSE.bind_call(error)
+        cause if MODULE_MATCH.bind_call(Exception, cause)
+      rescue StandardError
+        nil
+      end
+
+      def error_family(error)
+        ERROR_FAMILIES.find { |error_class, _| MODULE_MATCH.bind_call(error_class, error) }&.last || "other"
+      end
+
+      def error_class_name(error)
+        error_class = OBJECT_CLASS.bind_call(error)
+        MODULE_NAME.bind_call(error_class) || "anonymous_error"
+      end
+
+      # Never captures blank text: restore requires non-empty messages, so
+      # a blank live message takes the shared deterministic placeholder.
+      def error_message(error)
+        captured = DiagnosticText.capture(EXCEPTION_MESSAGE.bind_call(error))
+        captured.empty? ? FailureRecordText::MISSING_TEXT : captured
+      rescue StandardError
+        FailureRecordText::MISSING_TEXT
+      end
+
+      def retryable_value(error)
+        return unless error.respond_to?(:retryable)
+
+        value = error.retryable
+        value if BOOLEAN_VALUES.include?(value)
+      rescue StandardError
+        nil
+      end
+
+      def error_kind(error)
+        return unless error.respond_to?(:kind)
+
+        value = error.kind
+        return unless value.is_a?(String) || value.is_a?(Symbol)
+
+        captured = DiagnosticText.capture(value.to_s, max_bytes: 256)
+        # Restore rejects blank kinds; an empty kind carries no signal.
+        captured unless captured.empty?
+      rescue StandardError
+        nil
+      end
+
+      def error_details(error)
+        return unless error.respond_to?(:details)
+
+        FailureDetailSnapshot.new(error.details).call
+      rescue StandardError => e
+        FailureDetailSnapshot.new(
+          smith_failure_details_omitted: DiagnosticText.capture(e.message, max_bytes: 1_024)
+        ).call
+      end
+    end
+  end
+end

data/lib/smith/workflow/failure_record_restore.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+require "json"
+
+require_relative "../diagnostic_text"
+require_relative "../errors"
+require_relative "failure_record_text"
+require_relative "failure_record_validator"
+require_relative "message_value_normalizer"
+
+module Smith
+  class Workflow
+    class FailureRecordRestore
+      ATTRIBUTE_NAMES = %i[
+        transition from to error_class error_family error_message error_retryable error_retry_forbidden
+        error_kind error_details error_cause_class error_cause_family error_cause_message
+      ].freeze
+      OPTIONAL_NAMES = %i[error_retry_forbidden error_cause_class error_cause_family error_cause_message].freeze
+      REQUIRED_NAMES = (ATTRIBUTE_NAMES - OPTIONAL_NAMES).freeze
+      ATTRIBUTE_KEYS = ATTRIBUTE_NAMES.to_h { |name| [name.to_s, name] }.freeze
+      MODULE_MATCH = Module.instance_method(:===)
+      HASH_EACH_PAIR = Hash.instance_method(:each_pair)
+      private_constant :ATTRIBUTE_NAMES, :OPTIONAL_NAMES, :REQUIRED_NAMES, :ATTRIBUTE_KEYS, :MODULE_MATCH,
+                       :HASH_EACH_PAIR
+
+      extend Dry::Initializer
+
+      param :raw
+      option :transition_normalizer
+      option :state_normalizer
+
+      def call
+        return if raw.nil?
+
+        reject!("persisted workflow failure record must be a Hash") unless MODULE_MATCH.bind_call(Hash, raw)
+
+        values = attributes
+        FailureRecordValidator.new(restored_record(values)).call
+      end
+
+      private
+
+      def restored_record(values)
+        identity_attributes(values).merge(error_attributes(values)).freeze
+      end
+
+      def identity_attributes(values)
+        {
+          transition: normalize_identifier(values.fetch(:transition), transition_normalizer, "transition"),
+          from: normalize_identifier(values.fetch(:from), state_normalizer, "from state"),
+          to: normalize_identifier(values.fetch(:to), state_normalizer, "to state")
+        }
+      end
+
+      def error_attributes(values)
+        {
+          error_class: bounded_string(values.fetch(:error_class), 512, "class"),
+          error_family: bounded_string(values.fetch(:error_family), 64, "family"),
+          error_message: message_string(values.fetch(:error_message), "message"),
+          error_retryable: boolean_or_nil(values.fetch(:error_retryable), "retryable"),
+          error_retry_forbidden: boolean_or_nil(values[:error_retry_forbidden], "retry policy"),
+          error_kind: normalize_kind(values.fetch(:error_kind)),
+          error_details: normalize_details(values.fetch(:error_details)),
+          **cause_attributes(values)
+        }
+      end
+
+      def cause_attributes(values)
+        {
+          error_cause_class: optional_string(values[:error_cause_class], 512, "cause class"),
+          error_cause_family: optional_string(values[:error_cause_family], 64, "cause family"),
+          error_cause_message: optional_message(values[:error_cause_message], "cause message")
+        }
+      end
+
+      def attributes
+        values = {}
+        HASH_EACH_PAIR.bind_call(raw) do |key, value|
+          name = normalize_key(key)
+          reject!("persisted workflow failure record contains a duplicate attribute") if values.key?(name)
+
+          values[name] = value
+        end
+        missing = REQUIRED_NAMES - values.keys
+        reject!("persisted workflow failure record is incomplete") if missing.any?
+        values
+      end
+
+      def normalize_key(key)
+        return key if symbol?(key) && ATTRIBUTE_NAMES.include?(key)
+        return ATTRIBUTE_KEYS.fetch(key) if string?(key) && ATTRIBUTE_KEYS.key?(key)
+
+        reject!("persisted workflow failure record contains an unknown attribute")
+      end
+
+      def normalize_identifier(value, normalizer, label)
+        bounded_string(value, 256, label).then { normalizer.call(_1) }
+      end
+
+      def normalize_kind(value)
+        return if value.nil?
+
+        bounded_string(value, 256, "kind").to_sym
+      end
+
+      def normalize_details(value)
+        return if value.nil?
+
+        snapshot = MessageValueNormalizer.new(value, label: "persisted workflow failure details").call
+        JSON.generate(snapshot)
+        snapshot
+      rescue WorkflowError, JSON::GeneratorError, EncodingError
+        reject!("persisted workflow failure details are invalid")
+      end
+
+      def bounded_string(value, limit, label)
+        FailureRecordText.capture(value, limit:, label:)
+      end
+
+      def optional_string(value, limit, label) = value.nil? ? nil : bounded_string(value, limit, label)
+
+      # Messages restore with capture normalization (placeholder for blank
+      # text, capture-identical truncation for overlong text) because legacy
+      # states persisted them unbounded; length alone never rejects restore.
+      def message_string(value, label)
+        FailureRecordText.capture(value, limit: DiagnosticText::MAX_BYTES, label:, normalize_length: true)
+      end
+
+      def optional_message(value, label) = value.nil? ? nil : message_string(value, label)
+
+      def boolean_or_nil(value, label)
+        return value if value.nil? || value == true || value == false
+
+        reject!("persisted workflow failure #{label} is invalid")
+      end
+
+      def reject!(message) = raise(Smith::PersistedFailureInvalid, message)
+
+      def string?(value) = MODULE_MATCH.bind_call(String, value)
+
+      def symbol?(value) = MODULE_MATCH.bind_call(Symbol, value)
+    end
+  end
+end

data/lib/smith/workflow/failure_record_text.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+require_relative "../diagnostic_text"
+require_relative "../errors"
+
+module Smith
+  class Workflow
+    class FailureRecordText
+      # Deterministic stand-in shared by capture and restore for failure
+      # messages that would otherwise be blank.
+      MISSING_TEXT = "failure message unavailable"
+
+      MODULE_MATCH = Module.instance_method(:===)
+      STRING_BYTESIZE = String.instance_method(:bytesize)
+      STRING_ENCODING = String.instance_method(:encoding)
+      STRING_INITIALIZE_COPY = String.instance_method(:initialize_copy)
+      STRING_VALID_ENCODING = String.instance_method(:valid_encoding?)
+      SYMBOL_TO_S = Symbol.instance_method(:to_s)
+      private_constant :MODULE_MATCH, :STRING_BYTESIZE, :STRING_ENCODING, :STRING_INITIALIZE_COPY,
+                       :STRING_VALID_ENCODING, :SYMBOL_TO_S
+
+      extend Dry::Initializer
+
+      param :value
+      option :limit
+      option :label
+      option :normalize_length, default: proc { false }
+
+      def self.capture(value, limit:, label:, normalize_length: false)
+        new(value, limit:, label:, normalize_length:).call
+      end
+
+      def call
+        text = owned_text
+        validate_encoding!(text)
+        size = STRING_BYTESIZE.bind_call(text)
+        return normalized(text, size) if normalize_length
+        raise PersistedFailureInvalid, "persisted workflow failure #{label} is invalid" unless size.between?(1, limit)
+
+        text.freeze
+      end
+
+      private
+
+      def validate_encoding!(text)
+        valid = STRING_VALID_ENCODING.bind_call(text) && STRING_ENCODING.bind_call(text) == Encoding::UTF_8
+        return if valid
+
+        raise PersistedFailureInvalid, "persisted workflow failure #{label} is invalid"
+      end
+
+      # Message fields mirror capture normalization instead of rejecting on
+      # length: legacy states persisted messages unbounded (and possibly
+      # blank), and failing the whole workflow restore for message length
+      # alone would poison otherwise valid durable state. Blank text takes
+      # the capture placeholder; overlong text truncates exactly like
+      # capture does.
+      def normalized(text, size)
+        return MISSING_TEXT if size.zero?
+        return text.freeze if size <= limit
+
+        DiagnosticText.capture(text, max_bytes: limit)
+      end
+
+      def owned_text
+        return owned_string if string?
+        return SYMBOL_TO_S.bind_call(value) if symbol?
+
+        raise PersistedFailureInvalid, "persisted workflow failure #{label} must be text"
+      end
+
+      def owned_string
+        String.allocate.tap { STRING_INITIALIZE_COPY.bind_call(_1, value) }
+      end
+
+      def string? = MODULE_MATCH.bind_call(String, value)
+
+      def symbol? = MODULE_MATCH.bind_call(Symbol, value)
+    end
+  end
+end