smith-agents 0.6.0 → 0.7.0

data/lib/smith/tool_capture_failed.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "digest"
+
+require_relative "error"
+
+module Smith
+  class ToolCaptureFailed < Error
+    REASONS = %i[
+      collector_missing collector_invalid capture_empty capture_block_failed collector_failed
+    ].freeze
+    REASONS_BY_NAME = REASONS.to_h { |reason| [reason.to_s.freeze, reason] }.freeze
+    DETAIL_NAMES = %i[tool_name reason].freeze
+    DETAIL_KEYS = DETAIL_NAMES.to_h { |name| [name.to_s.freeze, name] }.freeze
+    MAX_TOOL_NAME_BYTES = 256
+    private_constant :REASONS, :REASONS_BY_NAME, :DETAIL_NAMES, :DETAIL_KEYS, :MAX_TOOL_NAME_BYTES
+
+    attr_reader :tool_name, :reason
+
+    def initialize(tool_name:, reason:)
+      @tool_name = normalize_tool_name(tool_name)
+      @reason = normalize_reason(reason)
+      super("strict result capture failed for #{@tool_name}: #{@reason}")
+    end
+
+    def details
+      { tool_name:, reason: }.freeze
+    end
+
+    def self.from_details(details)
+      values = normalize_details(details)
+      new(tool_name: values.fetch(:tool_name), reason: values.fetch(:reason))
+    end
+
+    def self.for_runtime(tool_name:, reason:)
+      new(tool_name:, reason:)
+    rescue ArgumentError
+      new(tool_name: diagnostic_tool_name(tool_name), reason:)
+    end
+
+    def self.normalize_details(details)
+      raise ArgumentError, "tool capture failure details must be a Hash" unless details.is_a?(Hash)
+
+      values = {}
+      Hash.instance_method(:each_pair).bind_call(details) do |key, value|
+        name = normalize_detail_name(key)
+        unless DETAIL_NAMES.include?(name)
+          raise ArgumentError, "tool capture failure details contain an unknown attribute"
+        end
+        raise ArgumentError, "tool capture failure details contain a duplicate attribute" if values.key?(name)
+
+        values[name] = value
+      end
+      missing = DETAIL_NAMES - values.keys
+      raise ArgumentError, "tool capture failure details are missing required attributes" if missing.any?
+
+      values
+    end
+
+    def self.normalize_detail_name(key)
+      return key if key.is_a?(Symbol)
+
+      DETAIL_KEYS[key] if key.is_a?(String)
+    end
+
+    def self.diagnostic_tool_name(value)
+      bytes = value.to_s.b
+      return "anonymous_tool" if bytes.empty?
+
+      "tool_#{Digest::SHA256.hexdigest(bytes)}"
+    end
+    private_class_method :normalize_details, :normalize_detail_name, :diagnostic_tool_name
+
+    private
+
+    def normalize_tool_name(value)
+      unless value.is_a?(String) || value.is_a?(Symbol)
+        raise ArgumentError, "tool capture failure tool name must be a String or Symbol"
+      end
+
+      name = value.to_s
+      raise ArgumentError, "tool capture failure tool name must be valid UTF-8" unless name.valid_encoding?
+
+      name = name.encode(Encoding::UTF_8)
+      raise ArgumentError, "tool capture failure tool name must be valid UTF-8" unless name.valid_encoding?
+
+      unless name.bytesize.between?(1, MAX_TOOL_NAME_BYTES)
+        raise ArgumentError, "tool capture failure tool name must be a bounded non-empty value"
+      end
+
+      name.dup.freeze
+    rescue EncodingError
+      raise ArgumentError, "tool capture failure tool name must be valid UTF-8"
+    end
+
+    def normalize_reason(value)
+      unless value.is_a?(String) || value.is_a?(Symbol)
+        raise ArgumentError, "tool capture failure reason must be a String or Symbol"
+      end
+
+      REASONS_BY_NAME.fetch(value.to_s) do
+        raise ArgumentError, "tool capture failure reason is not recognized"
+      end
+    end
+  end
+end

data/lib/smith/version.rb

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

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

@@ -12,21 +12,29 @@ module Smith
           "error_class" => :error_class,
           "error_family" => :error_family,
           "retryable" => :retryable,
-          "kind" => :kind
+          "kind" => :kind,
+          "tool_name" => :tool_name,
+          "reason" => :reason
         }.freeze
-        DETAIL_NAMES = DETAIL_KEYS.values.freeze
-        private_constant :DETAIL_KEYS, :DETAIL_NAMES
+        REQUIRED_DETAIL_NAMES = %i[branch_key error_class error_family retryable kind].freeze
+        OPTIONAL_DETAIL_NAMES = %i[tool_name reason].freeze
+        DETAIL_NAMES = (REQUIRED_DETAIL_NAMES + OPTIONAL_DETAIL_NAMES).freeze
+        private_constant :DETAIL_KEYS, :REQUIRED_DETAIL_NAMES, :OPTIONAL_DETAIL_NAMES, :DETAIL_NAMES
 
-        attr_reader :branch_key, :error_class, :error_family, :retryable, :kind, :details
+        attr_reader :branch_key, :error_class, :error_family, :retryable, :kind, :tool_name, :reason, :details
 
         def self.from_details(details)
           values = normalize_details(details)
-          error = Error.new(
+          error_attributes = {
             class_name: values.fetch(:error_class),
             family: values.fetch(:error_family),
             retryable: values.fetch(:retryable),
             kind: values.fetch(:kind)
-          )
+          }
+          OPTIONAL_DETAIL_NAMES.each do |name|
+            error_attributes[name] = values[name] if values.key?(name)
+          end
+          error = Error.new(error_attributes)
           new(branch_key: values.fetch(:branch_key), error:)
         end
 
@@ -42,7 +50,7 @@ module Smith
 
             normalized[name] = value
           end
-          missing = DETAIL_NAMES - normalized.keys
+          missing = REQUIRED_DETAIL_NAMES - normalized.keys
           raise ArgumentError, "composite branch failure details are missing required attributes" if missing.any?
 
           normalized
@@ -60,10 +68,7 @@ module Smith
         def initialize(branch_key:, error:)
           validate_arguments!(branch_key, error)
           @branch_key = branch_key.dup.freeze
-          @error_class = error.class_name.dup.freeze
-          @error_family = error.family.dup.freeze
-          @retryable = error.retryable
-          @kind = error.kind&.dup&.freeze
+          copy_error_attributes(error)
           @details = failure_details
           super("composite branch #{branch_key.inspect} failed")
         end
@@ -76,14 +81,30 @@ module Smith
           raise ArgumentError, "composite branch failure requires typed error evidence" unless error.is_a?(Error)
         end
 
+        def copy_error_attributes(error)
+          @error_class = owned_string(error.class_name)
+          @error_family = owned_string(error.family)
+          @retryable = error.retryable
+          @kind = owned_string(error.kind)
+          @tool_name = owned_string(error.tool_name)
+          @reason = owned_string(error.reason)
+        end
+
+        def owned_string(value)
+          value&.dup&.freeze
+        end
+
         def failure_details
-          {
+          values = {
             branch_key: @branch_key,
             error_class: @error_class,
             error_family: @error_family,
             retryable: @retryable,
             kind: @kind
-          }.freeze
+          }
+          values[:tool_name] = @tool_name if @tool_name
+          values[:reason] = @reason if @reason
+          values.freeze
         end
       end
     end

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

@@ -82,6 +82,12 @@ module Smith
           def serializable(values)
             values.merge(error: values[:error]&.to_h, effects: values.fetch(:effects).to_h)
           end
+
+          def legacy_serializable(values)
+            serializable(values).tap do |payload|
+              payload[:error] = payload[:error]&.except(:tool_name, :reason)
+            end
+          end
         end
 
         def initialize(attributes)
@@ -89,8 +95,7 @@ module Smith
           owned[:output] = self.class.send(:normalize_output, owned[:output])
           super(owned)
           validate_shape!
-          expected = PayloadDigest.call(self.class.send(:serializable, to_h.except(:digest)))
-          raise ArgumentError, "composite branch outcome digest does not match" unless digest == expected
+          validate_digest!
         end
 
         def succeeded? = status == :succeeded
@@ -98,6 +103,18 @@ module Smith
 
         private
 
+        def validate_digest!
+          values = to_h.except(:digest)
+          payloads = [self.class.send(:serializable, values)]
+          payloads << self.class.send(:legacy_serializable, values) if legacy_digest_allowed?
+          expected = payloads.map { PayloadDigest.call(_1) }
+          raise ArgumentError, "composite branch outcome digest does not match" unless expected.include?(digest)
+        end
+
+        def legacy_digest_allowed?
+          error.nil? || (error.tool_name.nil? && error.reason.nil?)
+        end
+
         def validate_shape!
           valid = succeeded? ? error.nil? : error && output.nil?
           raise ArgumentError, "composite branch outcome fields do not match status" unless valid

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "../../types"
+require_relative "../../tool_capture_failed"
 require_relative "payload"
 
 module Smith
@@ -8,12 +9,15 @@ module Smith
     module Composite
       class Error < Payload
         FAMILIES = %w[
-          tool_guardrail_failed deterministic_step_failure deadline_exceeded
-          agent_error workflow_error other
+          tool_capture_failed tool_guardrail_failed deterministic_step_failure
+          deadline_exceeded agent_error workflow_error other
         ].freeze
         ALWAYS_RETRYABLE_FAMILIES = %w[deadline_exceeded agent_error].freeze
         CONDITIONALLY_RETRYABLE_FAMILIES = %w[tool_guardrail_failed deterministic_step_failure].freeze
+        OPTIONAL_METADATA = %i[tool_name reason].freeze
+        STRING_METADATA = %i[kind tool_name reason].freeze
         private_constant :ALWAYS_RETRYABLE_FAMILIES, :CONDITIONALLY_RETRYABLE_FAMILIES
+        private_constant :OPTIONAL_METADATA, :STRING_METADATA
         OwnedString = Types::String.constructor { |value| value.is_a?(String) ? value.dup.freeze : value }
         private_constant :OwnedString
 
@@ -21,17 +25,43 @@ module Smith
         attribute :family, OwnedString.enum(*FAMILIES)
         attribute :retryable, Types::Bool
         attribute? :kind, OwnedString.constrained(min_size: 1, max_size: 128).optional
+        attribute? :tool_name, OwnedString.constrained(min_size: 1, max_size: 256).optional
+        attribute? :reason, OwnedString.constrained(min_size: 1, max_size: 128).optional
+
+        class << self
+          def normalize_attributes(attributes)
+            return super unless attributes.is_a?(Hash)
+
+            super(attributes_with_optional_metadata(attributes))
+          end
+
+          private
+
+          def attributes_with_optional_metadata(attributes)
+            values = {}
+            Hash.instance_method(:each_pair).bind_call(attributes) { |key, value| values[key] = value }
+            OPTIONAL_METADATA.each do |name|
+              values[name] = nil unless values.key?(name) || values.key?(name.to_s)
+            end
+            values
+          end
+        end
 
         def initialize(attributes)
-          owned = self.class.normalize_attributes(attributes)
-          owned[:kind] = owned[:kind].to_s if owned[:kind]
-          super(owned)
+          super(normalize_error_attributes(attributes))
           validate_retryability!
           validate_kind!
+          validate_tool_capture_metadata!
         end
 
         private
 
+        def normalize_error_attributes(attributes)
+          self.class.normalize_attributes(attributes).tap do |normalized|
+            STRING_METADATA.each { |name| normalized[name] = normalized[name].to_s if normalized[name] }
+          end
+        end
+
         def validate_retryability!
           valid = if ALWAYS_RETRYABLE_FAMILIES.include?(family)
                     retryable
@@ -48,6 +78,24 @@ module Smith
 
           raise ArgumentError, "composite error kind is not valid for its family"
         end
+
+        def validate_tool_capture_metadata!
+          valid = if family == "tool_capture_failed"
+                    valid_tool_capture_metadata?
+                  else
+                    tool_name.nil? && reason.nil?
+                  end
+          return if valid
+
+          raise ArgumentError, "composite error tool metadata does not match its family"
+        end
+
+        def valid_tool_capture_metadata?
+          ToolCaptureFailed.from_details(tool_name:, reason:)
+          true
+        rescue ArgumentError
+          false
+        end
       end
     end
   end

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

@@ -74,7 +74,7 @@ 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
+        Tool.current_tool_call_allowance = agent_tc ? Tool::CallAllowance.new(agent_tc) : nil
       end
 
       def clear_agent_tool_calls

data/lib/smith/workflow/fanout_execution.rb

@@ -1,12 +1,20 @@
 # frozen_string_literal: true
 
-require_relative "branch_env"
-
 module Smith
   class Workflow
     module FanoutExecution
       private
 
+      def fanout_branch_environment(branches, branch_agent_classes, prepared_input)
+        BranchEnv.new(
+          prepared_input:,
+          guardrail_sources: nil,
+          scoped_store: propagate_scoped_artifacts,
+          branch_estimates: fanout_branch_estimates(branches, branch_agent_classes),
+          deadline: wall_clock_deadline
+        )
+      end
+
       def run_guarded_fanout_step(transition)
         branches = transition.fanout_config.fetch(:branches)
         branch_agent_classes = fanout_agent_classes(transition, branches)
@@ -26,13 +34,7 @@ module Smith
       def execute_fanout_step(transition, branches: nil, branch_agent_classes: nil, prepared_input: nil)
         branches ||= transition.fanout_config.fetch(:branches)
         branch_agent_classes ||= fanout_agent_classes(transition, branches)
-        env = BranchEnv.new(
-          prepared_input: prepared_input,
-          guardrail_sources: nil,
-          scoped_store: propagate_scoped_artifacts,
-          branch_estimates: fanout_branch_estimates(branches, branch_agent_classes),
-          deadline: wall_clock_deadline
-        )
+        env = fanout_branch_environment(branches, branch_agent_classes, prepared_input)
 
         branch_calls = branches.map do |branch_key, agent_name|
           PreparedBranchExecution.instance_method(:prepared_branch).bind_call(
@@ -98,12 +100,11 @@ module Smith
       def fanout_branch_estimates(branches, branch_agent_classes)
         return {} unless @ledger
 
-        branch_count = branches.length
         branches.each_with_object({}) do |(branch_key, _agent_name), map|
           agent_class = branch_agent_classes.fetch(branch_key)
           map[branch_key] = compute_branch_estimates(
             @ledger,
-            branch_count: branch_count,
+            branch_count: branches.length,
             agent_budget: agent_class&.budget
           )
         end

data/lib/smith/workflow/parallel/cancellation_signal.rb

@@ -12,7 +12,7 @@ module Smith
 
         def cancel!(error = nil)
           @mutex.synchronize do
-            @reason ||= error
+            @reason = Parallel.preferred_error([@reason, error])
             @cancelled = true
           end
         end

data/lib/smith/workflow/parallel/root_execution.rb

@@ -73,7 +73,7 @@ module Smith
 
         def resolve(futures)
           fulfilled, values, reasons = Concurrent::Promises.zip(*futures).result
-          raise(@signal.reason || Parallel.preferred_error(reasons)) unless fulfilled
+          raise(Parallel.preferred_error([@signal.reason, *reasons])) unless fulfilled
 
           values
         end

data/lib/smith/workflow/parallel.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../errors"
+require_relative "../tool_capture_failed"
 require_relative "parallel/cancellation"
 require_relative "parallel/cancellation_signal"
 require_relative "parallel/execution_context"
@@ -36,7 +38,10 @@ module Smith
 
       def self.preferred_error(reasons)
         errors = Array(reasons).compact
-        errors.find { |error| !error.is_a?(Cancellation) } || errors.first
+        errors.find { |error| !error.is_a?(StandardError) } ||
+          errors.find { |error| error.is_a?(ToolCaptureFailed) } ||
+          errors.find { |error| !error.is_a?(Cancellation) } ||
+          errors.first
       end
     end
   end

data/lib/smith/workflow/prepared_branch_execution.rb

@@ -6,13 +6,20 @@ module Smith
       private
 
       def prepared_branch(implementation, *arguments)
+        tool_context = Tool::ScopedContext.capture
         unless @split_step_active_execution_authorization
-          return proc { |signal| __send__(implementation.name, *arguments, signal) }
+          return proc do |signal|
+            Tool::ScopedContext.around(tool_context) do
+              __send__(implementation.name, *arguments, signal)
+            end
+          end
         end
 
         proc do |signal|
           run = proc { implementation.bind_call(self, *arguments, signal) }
-          PreparedBranchExecution.instance_method(:within_prepared_branch_execution).bind_call(self, &run)
+          Tool::ScopedContext.around(tool_context) do
+            PreparedBranchExecution.instance_method(:within_prepared_branch_execution).bind_call(self, &run)
+          end
         end
       end
 

data/lib/smith/workflow/retry_execution.rb

@@ -24,6 +24,7 @@ module Smith
 
       def retry_transition_error?(config, error, attempt)
         return false if attempt >= config.fetch(:attempts)
+        return false if error.is_a?(ToolCaptureFailed)
 
         classes = config.fetch(:error_classes)
         if classes.any?

data/lib/smith/workflow/split_step_persistence/composite_branch_execution.rb

@@ -68,18 +68,27 @@ module Smith
         def composite_branch_environment(execution, input, agent_class, transition)
           branch = execution.branch
           budget = branch.budget.transform_keys(&:to_sym)
-          branch_key = fetch_composite_fanout_branch(transition, branch.key).first unless execution.kind == :parallel
-          estimates = execution.kind == :parallel ? budget : { branch_key => budget }
           BranchEnv.new(
             prepared_input: input.agent_messages,
             guardrail_sources: Tool.current_guardrails,
             scoped_store: propagate_scoped_artifacts,
-            branch_estimates: estimates,
+            branch_estimates: composite_branch_estimates(execution, transition, budget),
             deadline: wall_clock_deadline,
-            agent_class: execution.kind == :parallel ? agent_class : nil
+            agent_class: composite_parallel_agent(execution, agent_class)
           )
         end
 
+        def composite_branch_estimates(execution, transition, budget)
+          return budget if execution.kind == :parallel
+
+          branch_key = fetch_composite_fanout_branch(transition, execution.branch.key).first
+          { branch_key => budget }
+        end
+
+        def composite_parallel_agent(execution, agent_class)
+          agent_class if execution.kind == :parallel
+        end
+
         def composite_branch_ledger(branch)
           return if branch.budget.empty?
 

data/lib/smith/workflow/split_step_persistence/preparation_claim.rb

@@ -33,6 +33,8 @@ module Smith
         def finalize_split_step_preparation!(transition, transition_name, key, adapter, persistence_ttl)
           transaction_identity = TransactionIdentity.capture(adapter)
           transition_signature = TransitionContract.capture(transition)
+          namespace_preparer = PreparationClaim.instance_method(:prepare_composite_execution_namespace!)
+          namespace_preparer.bind_call(self, transition)
           @split_step_mutex.synchronize do
             unless active_split_step_preparation_claim?
               raise WorkflowError, "the split-step preparation claim is no longer active"
@@ -65,6 +67,12 @@ module Smith
             @split_step_preparation_thread.equal?(Thread.current)
         end
 
+        def prepare_composite_execution_namespace!(transition)
+          return unless transition&.parallel? || transition&.fanout?
+
+          ArtifactIntegration.instance_method(:execution_namespace).bind_call(self)
+        end
+
         def mark_split_step_prepared!(_adapter)
           @split_step_mutex.synchronize do
             phase = @split_step_transaction_identity ? :prepared_uncommitted : :prepared

data/lib/smith/workflow/thread_context_snapshot.rb

@@ -16,6 +16,7 @@ module Smith
         current_ledger
         current_tool_call_allowance
         current_tool_result_collector
+        current_invocation_context
       ].freeze
       THREAD_KEYS = %i[
         smith_call_deadline

data/lib/smith/workflow/transition.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../tool_capture_failed"
+
 module Smith
   class Workflow
     class Transition
@@ -334,6 +336,10 @@ module Smith
 
           raise WorkflowError, "retry_on error classes must inherit from StandardError"
         end
+        if error_classes.any? { |error_class| error_class <= ToolCaptureFailed }
+          message = "retry_on cannot retry Smith::ToolCaptureFailed because the tool outcome may be uncertain"
+          raise WorkflowError, message
+        end
 
         ExponentialBackoff.new(
           attempts:,

data/lib/smith/workflow.rb

@@ -38,6 +38,9 @@ module Smith
     # expose `attr_reader :retryable` only, with no setter, so kwargs
     # MUST flow through `initialize`.
     KNOWN_RECONSTRUCTORS = {
+      "Smith::ToolCaptureFailed" => ->(s) {
+        Smith::ToolCaptureFailed.from_details(s.fetch(:error_details))
+      },
       "Smith::ToolGuardrailFailed" => ->(s) {
         Smith::ToolGuardrailFailed.new(s[:error_message], retryable: s[:error_retryable])
       },
@@ -227,6 +230,7 @@ module Smith
         # so a real DSF doesn't get classified as workflow_error.
         error_family = case err
                        when Smith::DeterministicStepFailure then "deterministic_step_failure"
+                       when Smith::ToolCaptureFailed        then "tool_capture_failed"
                        when Smith::ToolGuardrailFailed      then "tool_guardrail_failed"
                        when Smith::DeadlineExceeded         then "deadline_exceeded"
                        when Smith::AgentError               then "agent_error"
@@ -378,6 +382,8 @@ module Smith
         )
       when "tool_guardrail_failed"
         Smith::ToolGuardrailFailed.new(snap[:error_message], retryable: snap[:error_retryable])
+      when "tool_capture_failed"
+        Smith::ToolCaptureFailed.from_details(snap.fetch(:error_details))
       when "deadline_exceeded" then Smith::DeadlineExceeded.new(snap[:error_message])
       when "agent_error"       then Smith::AgentError.new(snap[:error_message])
       when "workflow_error"    then Smith::WorkflowError.new(snap[:error_message])