smith-agents 0.7.0 → 0.8.0

data/lib/smith/tool.rb

@@ -4,23 +4,68 @@ require "ruby_llm"
 
 require_relative "tool/capability_builder"
 require_relative "tool/policy"
+require_relative "tool/call_budget"
+require_relative "tool/call_batch"
+require_relative "tool/legacy_call_allowance"
+require_relative "tool/call_allowance_counter"
 require_relative "tool/call_allowance"
+require_relative "tool/call_reservation"
+require_relative "tool/call_admission"
+require_relative "tool/execution_authority"
+require_relative "tool/execution_authorization"
+require_relative "tool/execution_tracker"
+require_relative "tool/execution_lifecycle"
+require_relative "tool/invocation"
+require_relative "tool/argument_snapshot_result"
+require_relative "tool/argument_scalar_snapshot"
+require_relative "tool/argument_container_reader"
+require_relative "tool/argument_snapshot_accounting"
+require_relative "tool/argument_snapshot_traversal"
+require_relative "tool/argument_snapshot"
+require_relative "tool/invocation_request"
+require_relative "tool/invocation_sequence"
+require_relative "tool/execution_batch_collection"
+require_relative "tool/execution_batch_invocations"
+require_relative "tool/execution_batch_source_metadata"
+require_relative "tool/execution_batch_source_call"
+require_relative "tool/execution_batch_sources"
+require_relative "tool/execution_batch_state"
+require_relative "tool/execution_batch"
+require_relative "tool/execution_batch_admission"
+require_relative "tool/execution_batch_requests"
+require_relative "tool/execution_batch_builder"
+require_relative "tool/execution_batch_registry"
 require_relative "tool/budget_enforcement"
 require_relative "tool_capture_failed"
 require_relative "tool/capture"
 require_relative "tool/capture_configuration"
 require_relative "tool/compatibility"
 require_relative "tool/scoped_context"
+require_relative "tool/bounded_completion_state"
+require_relative "tool/bounded_completion_guard"
+require_relative "tool/bounded_completion_controls"
+require_relative "tool/fail_fast_completion"
+require_relative "tool/graceful_completion"
+require_relative "tool/bounded_completion_context"
+require_relative "tool/bounded_completion_installation"
+require_relative "tool/execution_failure_handling"
+require_relative "tool/execution_dispatch"
+require_relative "tool/chat_execution_callbacks"
+require_relative "tool/execution_batch_lifecycle"
 require_relative "tool/chat_execution_context"
 
 module Smith
   class Tool < RubyLLM::Tool
     include Policy
+    include ExecutionAuthorization
+    include ExecutionLifecycle
     include BudgetEnforcement
     include Capture
     extend CaptureConfiguration
     extend ScopedContext
 
+    private_constant :ExecutionAuthority
+
     class << self
       # Tool subclasses inherit the parent's compatible_with spec by
       # reference (the spec is a frozen Hash; immutability makes shared
@@ -75,24 +120,32 @@ module Smith
     end
 
     def execute(**kwargs)
-      ensure_capture_ready!
-      run_before_execute_hook!(kwargs)
-      check_tool_deadline!
-      check_privilege!(kwargs)
-      check_authorization!(kwargs)
-      run_tool_guardrails!(kwargs)
-      check_tool_deadline!
-      charge_tool_call!
-
-      start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      result = perform(**kwargs)
-      duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
+      authorize_tool_execution!
+      kwargs.freeze
+      prepare_tool_execution!(kwargs)
+      result, duration = perform_with_duration(kwargs)
 
       emit_tool_trace(kwargs, result, duration)
       capture_result_if_configured(kwargs, result)
       result
     end
 
+    protected
+
+    def invocation_argument_error(arguments) = validate_keyword_arguments(normalize_args(arguments))
+
+    def execute_keyword_signature
+      parameters = method(:perform).parameters
+      required_keywords = parameters.filter_map { |kind, name| name if kind == :keyreq }
+      optional_keywords = parameters.filter_map { |kind, name| name if kind == :key }
+      accepts_extra_keywords = parameters.any? { |kind, _| kind == :keyrest }
+      accepts_positional_arguments = parameters.any? do |kind, _|
+        RubyLLM::Tool::POSITIONAL_PARAMETER_KINDS.include?(kind)
+      end
+
+      [required_keywords, optional_keywords, accepts_extra_keywords, accepts_positional_arguments]
+    end
+
     private
 
     def run_before_execute_hook!(kwargs)
@@ -126,6 +179,12 @@ module Smith
       raise DeadlineExceeded, "wall_clock deadline exceeded during tool execution" if Time.now.utc >= deadline
     end
 
+    def check_dispatch_deadline!
+      check_tool_deadline!
+    rescue DeadlineExceeded
+      raise ToolDispatchRejected, "tool deadline expired before dispatch"
+    end
+
     def perform(**kwargs)
       raise NotImplementedError, "#{self.class} must implement #perform"
     end

data/lib/smith/tool_execution_not_admitted.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "error"
+
+module Smith
+  class ToolExecutionNotAdmitted < Error; end
+end

data/lib/smith/tool_failure_notification_failed.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require_relative "error"
+require_relative "diagnostic_text"
+
+module Smith
+  class ToolFailureNotificationFailed < Error
+    DETAIL_NAMES = %i[
+      dispatch_error_class dispatch_error_message notification_error_class notification_error_message
+    ].freeze
+    DETAIL_KEYS = DETAIL_NAMES.to_h { |name| [name.to_s.freeze, name] }.freeze
+    EXCEPTION_MESSAGE = Exception.instance_method(:message)
+    MODULE_NAME = Module.instance_method(:name)
+    OBJECT_CLASS = Object.instance_method(:class)
+    private_constant :DETAIL_NAMES, :DETAIL_KEYS, :EXCEPTION_MESSAGE, :MODULE_NAME, :OBJECT_CLASS
+
+    attr_reader :details, :dispatch_error, :notification_error
+
+    def initialize(dispatch_error:, notification_error:)
+      @dispatch_error = dispatch_error
+      @notification_error = notification_error
+      @details = build_details
+      super(
+        "host failed to record a terminal tool outcome: " \
+        "#{@details.fetch(:notification_error_class)}: #{@details.fetch(:notification_error_message)}"
+      )
+    end
+
+    def build_details
+      {
+        dispatch_error_class: DiagnosticText.capture(error_class_name(dispatch_error), max_bytes: 512),
+        dispatch_error_message: DiagnosticText.capture(error_message(dispatch_error)),
+        notification_error_class: DiagnosticText.capture(error_class_name(notification_error), max_bytes: 512),
+        notification_error_message: DiagnosticText.capture(error_message(notification_error))
+      }.freeze
+    end
+    private :build_details
+
+    def self.from_details(details)
+      values = normalize_details(details)
+      new(
+        dispatch_error: restored_error(values, :dispatch_error),
+        notification_error: restored_error(values, :notification_error)
+      )
+    end
+
+    def self.normalize_details(details)
+      raise ArgumentError, "tool failure notification details must be a Hash" unless details.is_a?(Hash)
+
+      values = details.each_with_object({}) do |(key, value), normalized|
+        append_detail!(normalized, key, value)
+      end
+      validate_complete!(values)
+      values.freeze
+    end
+
+    def self.append_detail!(normalized, key, value)
+      name = normalize_detail_name(key)
+      raise ArgumentError, "tool failure notification details contain an unknown attribute" unless name
+      raise ArgumentError, "tool failure notification details contain a duplicate attribute" if normalized.key?(name)
+      raise ArgumentError, "tool failure notification detail values must be strings" unless value.is_a?(String)
+
+      normalized[name] = value
+    end
+
+    def self.validate_complete!(values)
+      missing = DETAIL_NAMES - values.keys
+      raise ArgumentError, "tool failure notification details are missing required attributes" if missing.any?
+    end
+
+    def self.normalize_detail_name(key)
+      return key if key.is_a?(Symbol) && DETAIL_NAMES.include?(key)
+
+      DETAIL_KEYS[key] if key.is_a?(String)
+    end
+
+    def self.restored_error(values, prefix)
+      RuntimeError.new(
+        "#{values.fetch(:"#{prefix}_class")}: #{values.fetch(:"#{prefix}_message")}"
+      )
+    end
+
+    def error_class_name(error)
+      error_class = OBJECT_CLASS.bind_call(error)
+      MODULE_NAME.bind_call(error_class) || MODULE_NAME.bind_call(error_class.superclass) || "StandardError"
+    end
+
+    def error_message(error) = EXCEPTION_MESSAGE.bind_call(error)
+    private :error_class_name, :error_message
+
+    private_class_method :normalize_details, :append_detail!, :validate_complete!, :normalize_detail_name,
+                         :restored_error
+  end
+end

data/lib/smith/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Smith
-  VERSION = "0.7.0"
-  EXECUTION_SEMANTICS_VERSION = "3"
+  VERSION = "0.8.0"
+  EXECUTION_SEMANTICS_VERSION = "5"
 end

data/lib/smith/workflow/agent_result.rb

@@ -4,16 +4,17 @@ module Smith
   class Workflow
     # rubocop:disable Style/RedundantStructKeywordInit
     AgentResult = Struct.new(
-      :content, :input_tokens, :output_tokens, :cost, :model_used,
+      :content, :input_tokens, :output_tokens, :cost, :model_used, :provider_used,
       keyword_init: true
     ) do
-      def self.from_response(response, content, model_used: nil)
+      def self.from_response(response, content, model_used: nil, provider_used: nil)
         new(
           content: content,
           input_tokens: response.respond_to?(:input_tokens) ? response.input_tokens : nil,
           output_tokens: response.respond_to?(:output_tokens) ? response.output_tokens : nil,
           cost: nil,
-          model_used: model_used
+          model_used: model_used,
+          provider_used: provider_used
         )
       end
 

data/lib/smith/workflow/artifact_integration.rb

@@ -33,7 +33,8 @@ module Smith
         Context::Session.new(
           messages: messages,
           context_manager: manager,
-          persisted_context: @context
+          persisted_context: @context,
+          seed_message_count: @seed_message_count || 0
         )
       end
     end

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

@@ -13,7 +13,7 @@ module Smith
         attr_reader :total_tokens, :total_cost
 
         USAGE_ATTRIBUTES = %w[
-          usage_id agent_name model input_tokens output_tokens cost attempt_kind recorded_at
+          usage_id agent_name model provider input_tokens output_tokens cost attempt_kind recorded_at
         ].freeze
         TOOL_ATTRIBUTES = %w[tool captured].freeze
         private_constant :USAGE_ATTRIBUTES, :TOOL_ATTRIBUTES
@@ -70,6 +70,8 @@ module Smith
         def validate_usage_identity!(entry)
           validate_usage_id!(entry.fetch("usage_id"))
           validate_agent_name!(entry.fetch("agent_name"))
+          provider = entry.fetch("provider")
+          validate_nonempty_string!(provider, "composite usage entry provider") if provider
           %w[model attempt_kind recorded_at].each do |key|
             validate_nonempty_string!(entry.fetch(key), "composite usage entry #{key}")
           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 ? Tool::CallAllowance.new(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