smith-agents 0.12.6 → 0.13.0

data/lib/smith/agent/provider_completion.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "provider_failure_handling"
+require_relative "attempt_captures"
 require_relative "content_bytes"
 require_relative "content_parts"
 require_relative "invocation_preparation"
@@ -15,6 +16,7 @@ module Smith
   class Agent
     module ProviderCompletion
       include ProviderFailureHandling
+      include AttemptCaptures
       include InvocationPreparation
       include ContentParts
       include ProviderCallTiming
@@ -26,13 +28,14 @@ module Smith
 
       # The input's documents and images are read once (ContentBytes), and
       # its cached parts checked against every Anthropic model in the chain,
-      # before the first attempt.
-      def complete_with_provider(agent_class, prepared_input, shape:)
+      # before the first attempt. A candidate that fails over to the next
+      # joins `set_aside` (AttemptCaptures).
+      def complete_with_provider(agent_class, prepared_input, shape:, set_aside: [])
         chain = build_model_chain(agent_class).tap { check_chain_cache_breakpoints!(_1, prepared_input) }
-        ContentBytes.with(prepared_input) { attempt_candidates(agent_class, prepared_input, chain, shape) }
+        ContentBytes.with(prepared_input) { attempt_candidates(agent_class, prepared_input, chain, shape, set_aside) }
       end
 
-      def attempt_candidates(agent_class, prepared_input, chain, shape)
+      def attempt_candidates(agent_class, prepared_input, chain, shape, set_aside)
         candidates = ProviderCandidateSequence.new(chain)
         interrupted = nil
         candidates.each do |model_reference, index|
@@ -43,7 +46,7 @@ module Smith
 
           interrupted ||= attempt if Interruptions.find(attempt.error)
           candidates.suppress(account_failed_provider(attempt, model_reference))
-          fail_over!(attempt, agent_class, candidates, interrupted)
+          fail_over!(attempt, agent_class, candidates, interrupted, set_aside)
         end
 
         # Fail closed: an empty candidate chain (agent without a model)
@@ -53,16 +56,15 @@ module Smith
               "no executable model candidate for #{agent_class}; declare a model or fallback_models"
       end
 
-      # Returns when another candidate is left to try. A candidate that met
-      # an interrupting error (an account out of credit) outlasts how a later
-      # one fails: the step was cut short, not failed, and is taken again
-      # from its first candidate once the host can do its part.
-      def fail_over!(attempt, agent_class, candidates, interrupted)
-        handle_provider_failure!(
-          attempt.error, attempt.model_reference, agent_class,
-          fallback_available: candidates.fallback_available?,
-          attempt_id: attempt.attempt_id
-        )
+      # Returns when another candidate is left to try, the failed attempt's
+      # captures set aside. A candidate that met an interrupting error (an
+      # account out of credit) outlasts how a later one fails: the step was
+      # cut short, not failed, and is taken again from its first candidate
+      # once the host can do its part.
+      def fail_over!(attempt, agent_class, candidates, interrupted, set_aside)
+        handle_provider_failure!(attempt.error, attempt.model_reference, agent_class,
+                                 fallback_available: candidates.fallback_available?, attempt_id: attempt.attempt_id)
+        set_aside.concat(attempt.captures)
       rescue StandardError => e
         raise if interrupted.nil? || Interruptions.find(e)
 
@@ -126,7 +128,7 @@ module Smith
         message_count = chat_message_count(chat)
         observed_reference = observed_model_reference(chat, fallback: model_reference)
         timer = ProviderCallTiming::Timer.start
-        response, stream, mode, call_facts = complete_chat(chat, observed_reference, collected = [], facts)
+        response, stream, mode, call_facts = captured_completion(chat, observed_reference, collected = [], facts)
         timer.stop
         completion = Completion.from_messages(response:, messages: new_chat_messages(chat, message_count), stream:,
                                               mode:)

data/lib/smith/agent/provider_failure_handling.rb

@@ -23,7 +23,7 @@ module Smith
 
       def handle_provider_failure!(error, model_reference, agent_class, fallback_available:, attempt_id: nil)
         account_failed_attempt(error, model_reference, agent_class, attempt_id:)
-        if completed_tool_calls?
+        if uncertain_tool_calls?
           raise Smith::ToolOutcomeUncertain.new(
             "provider failed after tool execution began; retry or fallback could replay an uncertain outcome"
           ), cause: error
@@ -44,8 +44,10 @@ module Smith
         PROVIDER_ACCOUNT_ERRORS.any? { |error_class| error.is_a?(error_class) }
       end
 
-      def completed_tool_calls?
-        Tool.current_tool_execution_tracker&.started?
+      # A tool that is not replay-safe has run in the step: a fallback would
+      # run it again.
+      def uncertain_tool_calls?
+        Tool.current_tool_execution_tracker&.uncertain?
       end
 
       def fallback_eligible?(error)

data/lib/smith/agent/provider_streaming.rb

@@ -72,7 +72,9 @@ module Smith
 
       def paused_loop(error, chat, start)
         continuation = Budget::Continuation.dump(@budget_continuation, chat.messages.drop(start || 0))
-        BudgetUnavailable.new(error.message, continuation:) if continuation && storable_pause?(continuation)
+        return unless continuation && storable_pause?(continuation)
+
+        BudgetUnavailable.new(error.message, continuation:, paused_by: self)
       end
 
       # Whether the run's state, with the paused loop kept, stays within

data/lib/smith/errors.rb

@@ -74,12 +74,15 @@ module Smith
   # hold; nothing was sent. A BudgetExceeded, so it is not retried unless a
   # step's `retry_on` names it (a durable retry waits for budget). One that
   # paused a tool loop carries its `continuation` (Budget::Continuation),
-  # which the step's retry continues from.
+  # which the step's retry continues from, and the run whose step paused
+  # (`paused_by`): only that run's retry continues it, never a parent's,
+  # whose retry would start a nested workflow over.
   class BudgetUnavailable < BudgetExceeded
-    attr_reader :continuation
+    attr_reader :continuation, :paused_by
 
-    def initialize(message = "the budget ledger refused the request", continuation: nil)
+    def initialize(message = "the budget ledger refused the request", continuation: nil, paused_by: nil)
       @continuation = continuation
+      @paused_by = paused_by
       super(message)
     end
   end

data/lib/smith/response_memo.rb

@@ -31,7 +31,8 @@ module Smith
   # whose tools had not run answers the call's first request without
   # sending it, and its tools run again, under the same keys; kept tool
   # results count as tools the step ran (charged to its tool-call
-  # allowances, and never run again by a retry or fallback). A call whose
+  # allowances, and never run again by a retry or fallback unless each is a
+  # replay-safe tool's). A call whose
   # messages cannot be kept (an attachment, or too many bytes) is not
   # stored, and is logged. A record Smith does not keep (its shape, or tool
   # results that do not answer its replies' calls) is ignored, and an error

data/lib/smith/tool/budget_enforcement.rb

@@ -31,7 +31,7 @@ module Smith
       end
 
       def mark_tool_execution_started!
-        self.class.current_tool_execution_tracker&.mark_started!
+        self.class.current_tool_execution_tracker&.mark_started!(replay_safe: self.class.replay_safe?)
         self.class.__send__(:current_tool_dispatch_start_handler)&.call(self)
       end
     end

data/lib/smith/tool/capability_builder.rb

@@ -3,6 +3,9 @@
 module Smith
   class Tool < RubyLLM::Tool
     class CapabilityBuilder
+      REPLAY = %i[safe unsafe].freeze
+      private_constant :REPLAY
+
       def initialize
         @capabilities = {}
       end
@@ -12,7 +15,17 @@ module Smith
       def network(value)      = @capabilities[:network] = value
       def approval(value)     = @capabilities[:approval] = value
       def data_volume(value)  = @capabilities[:data_volume] = value
-      def to_h                = @capabilities
+
+      # :safe when running the tool again under the same keys does what
+      # running it once did (a lookup), so a step whose tools are all safe
+      # keeps its retries and fallbacks; :unsafe, the default, otherwise.
+      def replay(value)
+        raise ArgumentError, "replay is :safe or :unsafe" unless REPLAY.include?(value)
+
+        @capabilities[:replay] = value
+      end
+
+      def to_h = @capabilities
     end
   end
 end

data/lib/smith/tool/capability_declaration.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Smith
+  class Tool < RubyLLM::Tool
+    # What a tool class declares about itself (`capabilities do ... end`,
+    # CapabilityBuilder), read for its privilege check, its traces'
+    # sensitivity and whether a step may run it again. A subclass inherits
+    # its parent's, key by key: its own block sets or replaces only the keys
+    # it names, so a subclass is never less guarded than its parent unless
+    # it says so. `replay` alone is not inherited: whether a tool is safe to
+    # run again is a fact about its own `perform`, so a subclass is
+    # replay-safe only when it declares `replay :safe` itself.
+    module CapabilityDeclaration
+      NOT_INHERITED = %i[replay].freeze
+      private_constant :NOT_INHERITED
+
+      def capabilities(&)
+        return inherited_capabilities unless block_given?
+
+        builder = CapabilityBuilder.new
+        builder.instance_eval(&)
+        @capabilities = builder.to_h.freeze
+      end
+
+      # Whether this class itself declares `capabilities { replay :safe }`.
+      def replay_safe? = capabilities&.dig(:replay) == :safe
+
+      private
+
+      def inherited_capabilities
+        inherited = parent_capabilities
+        own = @capabilities if instance_variable_defined?(:@capabilities)
+        return own unless inherited
+
+        own ? inherited.merge(own) : inherited
+      end
+
+      # The parent's capabilities this class takes (all but `replay`), or nil.
+      def parent_capabilities
+        inherited = parent_tool&.capabilities&.except(*NOT_INHERITED)
+        inherited if inherited&.any?
+      end
+    end
+  end
+end

data/lib/smith/tool/capture_configuration.rb

@@ -2,9 +2,12 @@
 
 module Smith
   class Tool < RubyLLM::Tool
+    # A tool class's capture, inherited (Declarations) with its strictness: a
+    # subclass's own `capture_result` replaces its parent's, block and
+    # strictness together.
     module CaptureConfiguration
       def capture_result(strict: false, &block)
-        return @capture_result unless block
+        return declared(:@capture_result) unless block
 
         raise ArgumentError, "capture_result strict must be true or false" unless [true, false].include?(strict)
 
@@ -13,7 +16,7 @@ module Smith
       end
 
       def capture_result_strict?
-        @capture_result_strict == true
+        declaring_tool(:@capture_result)&.instance_variable_get(:@capture_result_strict) == true
       end
     end
   end

data/lib/smith/tool/declarations.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Smith
+  class Tool < RubyLLM::Tool
+    # A tool class's declarations, which its subclasses inherit: each reads
+    # the nearest class up the chain that declared it, so a subclass
+    # overrides one by declaring it again. Parameters add up by name (a
+    # subclass's `param` adds one or replaces its parent's of that name), up
+    # to a class that gave a schema with `params`, which replaced the ones
+    # above it; that schema gives way to a subclass's own `param`s.
+    # Capabilities (CapabilityDeclaration) merge key by key, and a capture
+    # (CaptureConfiguration) comes with its strictness. A tool none of whose
+    # classes declares `authorize` or `before_execute` runs without one, as
+    # before. `O(D)` for a chain `D` classes deep.
+    module Declarations
+      def description(text = nil)
+        return declared(:@description) unless text
+
+        @description = text
+      end
+      alias desc description
+
+      def param(name, **) = own_parameters[name] = RubyLLM::Parameter.new(name, **)
+
+      def parameters
+        parent = parent_tool
+        inherited = parent.parameters if parent && !parent.instance_variable_defined?(:@params_schema_definition)
+        inherited.nil? || inherited.empty? ? own_parameters : inherited.merge(own_parameters)
+      end
+
+      def params_schema_definition
+        return @params_schema_definition if instance_variable_defined?(:@params_schema_definition)
+
+        parent_tool&.params_schema_definition if own_parameters.empty?
+      end
+
+      def provider_params = declared(:@provider_params) || {}
+
+      def category(value = nil)
+        return declared(:@category) if value.nil?
+
+        @category = value
+      end
+
+      def authorize(&block)
+        return declared(:@authorize) unless block
+
+        @authorize = block
+      end
+
+      def before_execute(&block)
+        return declared(:@before_execute) unless block
+
+        @before_execute = block
+      end
+
+      private
+
+      def own_parameters = (@own_parameters ||= {})
+
+      def parent_tool = (superclass if superclass <= Tool)
+
+      # The nearest class from this one up that set `ivar`, or nil.
+      def declaring_tool(ivar)
+        tool = self
+        tool = tool.__send__(:parent_tool) while tool && !tool.instance_variable_defined?(ivar)
+        tool
+      end
+
+      def declared(ivar) = declaring_tool(ivar)&.instance_variable_get(ivar)
+    end
+  end
+end

data/lib/smith/tool/execution_tracker.rb

@@ -2,19 +2,30 @@
 
 module Smith
   class Tool < RubyLLM::Tool
+    # What the tools of one step attempt did: whether any began, and whether
+    # one that is not replay-safe did, which leaves the step's outcome
+    # uncertain (nothing may run its tools again).
     class ExecutionTracker
       def initialize
         @started = false
+        @uncertain = false
         @mutex = Mutex.new
       end
 
-      def mark_started!
-        @mutex.synchronize { @started = true }
+      def mark_started!(replay_safe: false)
+        @mutex.synchronize do
+          @started = true
+          @uncertain = true unless replay_safe
+        end
       end
 
       def started?
         @mutex.synchronize { @started }
       end
+
+      def uncertain?
+        @mutex.synchronize { @uncertain }
+      end
     end
   end
 end

data/lib/smith/tool.rb

@@ -2,7 +2,9 @@
 
 require "ruby_llm"
 
+require_relative "tool/declarations"
 require_relative "tool/capability_builder"
+require_relative "tool/capability_declaration"
 require_relative "tool/policy"
 require_relative "tool/call_budget"
 require_relative "tool/call_batch"
@@ -61,22 +63,14 @@ module Smith
     include ExecutionLifecycle
     include BudgetEnforcement
     include Capture
+    extend Declarations
+    extend CapabilityDeclaration
     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
-      # references safe). Subclasses can override by calling
-      # `compatible_with` again — assigns a NEW frozen Hash to its own
-      # @compatible_with_spec, leaving the parent untouched.
-      def inherited(subclass)
-        super
-        subclass.instance_variable_set(:@compatible_with_spec, @compatible_with_spec)
-      end
-
       # Declarative compatibility DSL. Examples:
       #   compatible_with :anthropic, :gemini
       #   compatible_with :anthropic, :gemini, openai: :responses
@@ -85,38 +79,14 @@ module Smith
       # Tools that NEVER declare compatible_with are universally compatible.
       # Consumed by Smith::Models::Normalizer.drop_incompatible_tools when
       # the resolved model rejects the (tools + thinking) combo and no
-      # routing fallback (e.g., openai_api_mode :auto) is available.
+      # routing fallback (e.g., openai_api_mode :auto) is available. The
+      # spec is a frozen Hash, read like the other declarations: a subclass
+      # takes the nearest one up its chain (Declarations).
       def compatible_with(*providers, except: nil, **provider_endpoints)
         @compatible_with_spec = Compatibility.parse(providers, except: except, **provider_endpoints)
       end
 
-      attr_reader :compatible_with_spec
-
-      def category(value = nil)
-        return @category if value.nil?
-
-        @category = value
-      end
-
-      def capabilities(&)
-        return @capabilities unless block_given?
-
-        builder = CapabilityBuilder.new
-        builder.instance_eval(&)
-        @capabilities = builder.to_h
-      end
-
-      def authorize(&block)
-        return @authorize unless block_given?
-
-        @authorize = block
-      end
-
-      def before_execute(&block)
-        return @before_execute unless block_given?
-
-        @before_execute = block
-      end
+      def compatible_with_spec = declared(:@compatible_with_spec)
     end
 
     def execute(**kwargs)

data/lib/smith/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Smith
-  VERSION = "0.12.6"
+  VERSION = "0.13.0"
   EXECUTION_SEMANTICS_VERSION = "7"
 end

data/lib/smith/workflow/budget_pause.rb

@@ -37,7 +37,14 @@ module Smith
       def budget_pausable? = !@budget_pause_attempts.nil? && @step_attempt.to_i < @budget_pause_attempts
 
       def keep_budget_continuation(error)
-        @budget_continuation = error.continuation if error.is_a?(BudgetUnavailable) && error.continuation
+        @budget_continuation = error.continuation if own_pause?(error)
+      end
+
+      # A tool loop this run's own step paused, which its retry continues
+      # from its tools' results. One a nested workflow paused is not: the
+      # retry starts the child over, and its tools run again.
+      def own_pause?(error)
+        error.is_a?(BudgetUnavailable) && !error.continuation.nil? && error.paused_by.equal?(self)
       end
 
       # The paused loop's messages, after the attempt's prepared input.

data/lib/smith/workflow/child_run_execution.rb

@@ -141,7 +141,8 @@ module Smith
         check_deadline!
         namespace = ArtifactIntegration.instance_method(:execution_namespace).bind_call(self)
         token = IdempotencyKey.__send__(:root_scope, namespace)
-                              .within(:step, @step_count + 1, transition.name.to_s).within(:spawn).key
+                              .within(:step, @step_count + 1, self.class.transition_key_name(transition.name))
+                              .within(:spawn).key
         launch_child_runs(transition, token)
         nil
       end

data/lib/smith/workflow/dsl.rb

@@ -33,6 +33,8 @@ module Smith
           subclass.instance_variable_set(:@persistence_key_builder, @persistence_key_builder)
           subclass.instance_variable_set(:@persistence_schema_version, @persistence_schema_version)
           subclass.instance_variable_set(:@migrations, (@migrations || {}).dup)
+          subclass.instance_variable_set(:@renamed_states, @renamed_states)
+          subclass.instance_variable_set(:@renamed_transitions, @renamed_transitions)
           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)
@@ -165,6 +167,77 @@ module Smith
           @migrations || {}
         end
 
+        # A state a later version renamed: a run persisted in `old`
+        # restores in `to` and carries on from there. Renames chain (a to
+        # b, then b to c); a name is renamed at most once and never back
+        # to a name it had. A name the class still declares is never taken
+        # for an old one (validate_graph warns of such a rename). The
+        # persisted run is mapped after migrate_from, before anything
+        # checks its names, so a rename needs no persistence_schema_version.
+        # A rename stays declared while runs persisted under its old name
+        # may remain.
+        def renamed_state(old, to:)
+          @renamed_states = renamed_name_map(renamed_states, old, to, kind: "state")
+        end
+
+        # A transition a later version renamed: a run persisted about to
+        # take `old`, or waiting in it (its wait, pending retry or batch),
+        # restores at `to`, as renamed_state. A renamed transition keeps
+        # its keys: its steps' idempotency keys and wait tokens are made
+        # under the first name in its chain (transition_key_name), so a
+        # step a deploy cut short, a retry or an early delivery meets the
+        # keys its earlier attempt used. Hence at most one name is renamed
+        # to a transition, and the rename stays declared for good: dropping
+        # it moves the transition's keys to its new name.
+        def renamed_transition(old, to:)
+          renames = renamed_name_map(renamed_transitions, old, to, kind: "transition")
+          earlier = renamed_transitions.key(renames.fetch(old.to_s))
+          if earlier
+            raise ArgumentError, "transition #{to.inspect} is already the new name of #{earlier.inspect}; a " \
+                                 "transition keeps the keys of one first name, so only one name is renamed to it"
+          end
+
+          @renamed_transitions = renames
+        end
+
+        def renamed_states
+          @renamed_states || {}.freeze
+        end
+
+        def renamed_transitions
+          @renamed_transitions || {}.freeze
+        end
+
+        # The state a persisted state name stands for now, renames
+        # followed, or nil when the class knows none. `O(R·(S + T))` for
+        # `R` renamed states.
+        def current_state_name(name)
+          return if name.nil?
+
+          resolve_state_name(follow_renames(name, renamed_states) { |candidate| resolve_state_name(candidate) })
+        end
+
+        # The transition a persisted transition name stands for now,
+        # renames followed, or nil when the class knows none. `O(R·T)` for
+        # `R` renamed transitions.
+        def current_transition_name(name)
+          return if name.nil?
+
+          transition_named(follow_renames(name, renamed_transitions) { |candidate| transition_named(candidate) })&.name
+        end
+
+        # The name a transition's steps are keyed under (their idempotency
+        # keys and wait tokens): the first name in its rename chain, so a
+        # renamed transition keeps its keys. Renames have no cycles and at
+        # most one name renamed to each, so the chain back is a line.
+        # `O(R)` for `R` renamed transitions.
+        def transition_key_name(name)
+          earlier = renamed_transitions.invert
+          current = name.to_s
+          current = earlier[current] while earlier.key?(current)
+          current
+        end
+
         # Controls whether restore validates that the seed_messages
         # builder still produces the same digest as when this workflow
         # was originally persisted.
@@ -313,6 +386,56 @@ module Smith
           Identifier.normalize(identifier, label: "workflow identifier")
         end
 
+        # The renames with `old` renamed to `to`: refused when `old` is
+        # already renamed, or when the chain from `to` leads back to `old`
+        # (a rename back), so every chain is a line. `O(R)`.
+        def renamed_name_map(renames, old, to, kind:)
+          old_name = renamed_identifier(old, kind:)
+          new_name = renamed_identifier(to, kind:)
+          check_rename!(renames, old_name, new_name, kind:)
+          renames.merge(old_name => new_name).freeze
+        end
+
+        def check_rename!(renames, old_name, new_name, kind:)
+          if old_name == new_name
+            raise ArgumentError, "a renamed #{kind} must differ from its new name, got #{old_name.inspect}"
+          end
+
+          if renames.key?(old_name)
+            raise ArgumentError, "#{kind} #{old_name.inspect} is already renamed to #{renames[old_name].inspect}; " \
+                                 "rename #{renames[old_name].inspect} instead"
+          end
+
+          return unless renamed_back?(renames, old_name, new_name)
+
+          raise ArgumentError, "#{kind} #{new_name.inspect} was renamed from #{old_name.inspect}; a #{kind} is " \
+                               "never renamed back to a name it had"
+        end
+
+        def renamed_back?(renames, old_name, new_name)
+          current = new_name
+          current = renames[current] while renames.key?(current) && current != old_name
+          current == old_name
+        end
+
+        def renamed_identifier(name, kind:)
+          unless (name.is_a?(Symbol) || name.is_a?(String)) && !name.to_s.strip.empty?
+            raise ArgumentError, "a renamed #{kind} must be a non-blank Symbol or String, got #{name.inspect}"
+          end
+
+          name.to_s
+        end
+
+        # The name `name` stands for now: itself while the class declares
+        # it (`declared` says so), else where its renames lead. Chains are
+        # lines (renamed_name_map), so the walk ends. `O(R)` calls of
+        # `declared`.
+        def follow_renames(name, renames, &declared)
+          current = name.to_s
+          current = renames[current] until declared.call(current) || !renames.key?(current)
+          current
+        end
+
         def transitions_by_state
           @transitions_by_state ||= Hash.new { |index, state| index[state] = [] }
         end

data/lib/smith/workflow/durability.rb

@@ -244,10 +244,11 @@ module Smith
           false
         end
 
-        # A state the class no longer knows can never advance or restore, so
-        # it is not terminal: an old one reports as stuck.
+        # A state the class no longer knows, renames followed, can never
+        # advance or restore, so it is not terminal: an old one reports as
+        # stuck.
         def terminal_payload_state?(klass, state_name, next_transition)
-          state = klass.resolve_state_name(state_name)
+          state = klass.current_state_name(state_name)
           !state.nil? && !klass.transition_from?(state) && next_transition.nil?
         end