smith-agents 0.12.6 → 0.13.0

data/lib/smith/workflow/graph/rename_diagnostics.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    class Graph
+      # Renames (renamed_state, renamed_transition) found wanting before a
+      # run restores through one: a rename leading to no name the workflow
+      # declares is an error, as a run persisted under its old name cannot
+      # restore; one whose old name the workflow still declares is a
+      # warning, as a run persisted under that name stays there.
+      # `O(R·(S + T))` for `R` renames.
+      class RenameDiagnostics
+        attr_reader :graph
+
+        def initialize(graph)
+          @graph = graph
+        end
+
+        def to_a
+          workflow = graph.workflow_class
+
+          [
+            *diagnostics_for(:state, workflow.renamed_states) do |name|
+              [workflow.resolve_state_name(name), workflow.current_state_name(name)]
+            end,
+            *diagnostics_for(:transition, workflow.renamed_transitions) do |name|
+              [workflow.transition_named(name), workflow.current_transition_name(name)]
+            end
+          ]
+        end
+
+        private
+
+        def diagnostics_for(kind, renames)
+          renames.filter_map do |old, new|
+            declared, current = yield(old)
+            if declared
+              shadowed(kind, old, new)
+            elsif current.nil?
+              leads_nowhere(kind, old, new)
+            end
+          end
+        end
+
+        def shadowed(kind, old, new)
+          Diagnostic.new(
+            severity: :warning,
+            code: :rename_shadowed,
+            kind => old,
+            message: "Renamed #{kind} #{old.inspect} is still declared, so a run persisted in it stays there " \
+                     "rather than moving to #{new.inspect}.",
+            suggestion: "Drop the rename, or move such runs with persistence_schema_version and migrate_from."
+          )
+        end
+
+        def leads_nowhere(kind, old, new)
+          Diagnostic.new(
+            severity: :error,
+            code: :"renamed_to_unknown_#{kind}",
+            kind => old,
+            message: "Renamed #{kind} #{old.inspect} leads through #{new.inspect} to no #{kind} this workflow " \
+                     "declares, so a run persisted in it cannot restore.",
+            suggestion: "Declare #{kind} #{new.inspect} or rename #{old.inspect} to a declared #{kind}."
+          )
+        end
+      end
+    end
+  end
+end

data/lib/smith/workflow/graph/validator.rb

@@ -29,6 +29,7 @@ module Smith
         def all_diagnostics
           [
             *StateDiagnostics.new(graph).to_a,
+            *RenameDiagnostics.new(graph).to_a,
             *TransitionDiagnostics.new(graph).to_a,
             *ReachabilityDiagnostics.new(graph, reachable_transition_names).to_a
           ]

data/lib/smith/workflow/graph.rb

@@ -88,6 +88,7 @@ require_relative "graph/identifier_projection"
 require_relative "graph/transition_contract"
 require_relative "graph/diagnostic"
 require_relative "graph/state_diagnostics"
+require_relative "graph/rename_diagnostics"
 require_relative "graph/targets"
 require_relative "graph/execution_successors"
 require_relative "graph/reachability"

data/lib/smith/workflow/guarded_step_execution.rb

@@ -22,20 +22,20 @@ module Smith
           ensure
             # Tool evidence travels up: a step running inside another step
             # (a nested workflow's step) marks the enclosing step too, so the
-            # enclosing step is never retried over tools that already ran.
-            previous_tracker&.mark_started! if tracker.started?
+            # enclosing step is never retried over tools that already ran,
+            # unless they were all replay-safe.
+            previous_tracker&.mark_started!(replay_safe: !tracker.uncertain?) if tracker.started?
             Tool.current_tool_execution_tracker = previous_tracker
           end
         end
       end
 
-      # A failure after a tool ran leaves its outcome uncertain, unless its
-      # retry could not run the tool again: a terminal failure, or a tool
-      # loop paused for budget, whose retry continues from its tools'
-      # results.
+      # A failure after a tool that is not replay-safe ran leaves its outcome
+      # uncertain, unless its retry could not run the tool again: a terminal
+      # failure, or a tool loop this run's step paused for budget, whose
+      # retry continues from its tools' results (BudgetPause#own_pause?).
       def uncertain_after_tools?(tracker, error)
-        tracker.started? && !terminal_retry_error?(error) &&
-          !(error.is_a?(BudgetUnavailable) && error.continuation)
+        tracker.uncertain? && !terminal_retry_error?(error) && !own_pause?(error)
       end
 
       def run_tracked_guarded_step(transition)

data/lib/smith/workflow/nested_execution.rb

@@ -16,9 +16,9 @@ module Smith
       end
 
       # A child that raises passes its error to the parent unchanged, after
-      # its billable usage is rolled up. If a tool ran in the child, the
-      # parent's step already carries that evidence and turns the failure
-      # into ToolOutcomeUncertain (GuardedStepExecution).
+      # its billable usage is rolled up. If a tool that is not replay-safe
+      # ran in the child, the parent's step already carries that evidence
+      # and turns the failure into ToolOutcomeUncertain (GuardedStepExecution).
       def run_child_workflow(child)
         child.run!
       rescue StandardError

data/lib/smith/workflow/persistence.rb

@@ -87,7 +87,7 @@ module Smith
       def restore_state(hash, allow_step_in_progress: false)
         validate_raw_step_in_progress!(hash) if
           self.class.idempotency_mode == :strict && !allow_step_in_progress
-        migrated = migrate_if_needed(hash)
+        migrated = apply_renames(migrate_if_needed(hash))
         normalized = normalize_persisted_state(migrated)
         persistence_version = validated_persistence_version(normalized)
         restore_persisted_keys(normalized)
@@ -447,6 +447,74 @@ module Smith
         payload
       end
 
+      # A run persisted under names a later version renamed
+      # (renamed_state, renamed_transition) carries on under the new
+      # ones: its state, the transition it takes next, the transition its
+      # wait, pending retry and pending batch are in, and its last failed
+      # step's names, each kept the type it was persisted as. A name the
+      # class still declares stays as it is.
+      RENAMED_RECORDS = {
+        awaiting: { transition: %w[transition] },
+        pending_retry: { transition: %w[transition] },
+        pending_batch: { transition: %w[transition] },
+        last_failed_step: { transition: %w[transition], state: %w[from to] }
+      }.freeze
+      private_constant :RENAMED_RECORDS
+
+      def apply_renames(payload)
+        return payload unless renames?
+
+        renamed = payload.dup
+        renamed[:state] = renamed_state_name(payload[:state])
+        renamed[:next_transition_name] = renamed_transition_name(payload[:next_transition_name]) if
+          payload.key?(:next_transition_name)
+        RENAMED_RECORDS.each_key { |key| renamed[key] = renamed_record(payload[key], RENAMED_RECORDS[key]) }
+        renamed
+      end
+
+      def renames? = !(self.class.renamed_states.empty? && self.class.renamed_transitions.empty?)
+
+      def renamed_state_name(name)
+        renamed_value(name) do |text|
+          self.class.send(:follow_renames, text, self.class.renamed_states) do |candidate|
+            self.class.resolve_state_name(candidate)
+          end
+        end
+      end
+
+      def renamed_transition_name(name)
+        renamed_value(name) do |text|
+          self.class.send(:follow_renames, text, self.class.renamed_transitions) do |candidate|
+            self.class.transition_named(candidate)
+          end
+        end
+      end
+
+      # A persisted name renamed, kept the type it was persisted as.
+      def renamed_value(name)
+        return name unless name.is_a?(String) || name.is_a?(Symbol)
+
+        renamed = yield(name.to_s)
+        name.is_a?(Symbol) ? renamed.to_sym : renamed
+      end
+
+      # A persisted record's name fields renamed, each by its kind
+      # (:state or :transition), under String or Symbol keys alike.
+      def renamed_record(record, fields_by_kind)
+        return record unless record.is_a?(Hash)
+
+        renamed = record.dup
+        fields_by_kind.each do |kind, fields|
+          fields.each do |field|
+            key = [field, field.to_sym].find { |candidate| renamed.key?(candidate) }
+            next if key.nil?
+
+            renamed[key] = kind == :state ? renamed_state_name(renamed[key]) : renamed_transition_name(renamed[key])
+          end
+        end
+        renamed
+      end
+
       def normalize_persisted_state(hash)
         normalized = snapshot_value(hash).transform_keys { |k| k.is_a?(String) ? k.to_sym : k }
         normalized[:outcome] = symbolize_value(normalized[:outcome]) if normalized[:outcome].is_a?(Hash)

data/lib/smith/workflow/remembered_calls.rb

@@ -53,12 +53,24 @@ module Smith
         messages = kept.fetch(:messages)
         messages.each { chat.add_message(_1) }
         ran = messages.filter_map { _1.tool_call_id if _1.role == :tool }
-        Tool.current_tool_execution_tracker&.mark_started! if ran.any?
-        charge_kept_calls(ran_calls(messages, ran))
+        calls = ran_calls(messages, ran)
+        mark_kept_tools(chat, ran, calls) if ran.any?
+        charge_kept_calls(calls)
       end
 
       def ran_calls(messages, ran) = messages.flat_map { _1.tool_calls&.values.to_a }.select { ran.include?(_1.id) }
 
+      # As the tools themselves would mark the step: replay-safe only when
+      # each kept result answers a call to a tool of the chat's that
+      # declares it.
+      def mark_kept_tools(chat, ran, calls)
+        tools = calls.to_h { [_1.id, chat.tools[_1.name.to_sym]] }
+        safe = ran.all? { replay_safe_tool?(tools[_1]) }
+        Tool.current_tool_execution_tracker&.mark_started!(replay_safe: safe)
+      end
+
+      def replay_safe_tool?(tool) = tool.is_a?(Tool) && tool.class.replay_safe?
+
       # Each kept call against the agent's tool-call allowance and the
       # workflow's `tool_calls` budget, as a call that runs is, so a replay
       # runs no more tools than the step may. A call past them (a budget

data/lib/smith/workflow/retry_execution.rb

@@ -34,9 +34,7 @@ module Smith
         schedule = retry_schedule(config)
         begin
           attempt += 1
-          @step_attempt = attempt
-          @step_key_generation = key_generation
-          attempt_scope = attempt_idempotency_scope(key_generation)
+          attempt_scope = enter_attempt(attempt, key_generation)
           run_attempt_under_keys(transition, attempt_scope)
         rescue StandardError => e
           Interruptions.pass!(e)
@@ -48,10 +46,33 @@ module Smith
           return wait_to_retry(transition, delay, attempt + 1, key_generation, e) if config[:durable]
 
           sleep(delay) if delay.positive?
+          drop_attempt_tool_results(e)
           retry
         end
       end
 
+      # The attempt under way, under `key_generation`; returns its
+      # idempotency scope. `@attempt_tool_results_from` (transient, like
+      # `@step_attempt`) is where its tool results start.
+      def enter_attempt(attempt, key_generation)
+        @step_attempt = attempt
+        @step_key_generation = key_generation
+        @attempt_tool_results_from = @tool_results_mutex.synchronize { @tool_results.length }
+        attempt_idempotency_scope(key_generation)
+      end
+
+      # Once its retry is certain (in process, or waiting), a failed attempt's
+      # tool results go: its tools were replay-safe, or it would not be
+      # retried, and the next attempt runs them again. A tool loop this
+      # run's step paused for budget keeps them, as its retry goes on from
+      # them.
+      def drop_attempt_tool_results(error)
+        from = @attempt_tool_results_from
+        return if from.nil? || own_pause?(error)
+
+        @tool_results_mutex.synchronize { @tool_results.slice!(from..) }
+      end
+
       def attempt_idempotency_scope(key_generation)
         step_scope = IdempotencyKey.__send__(:current_scope)
         return step_scope if step_scope.nil? || key_generation.zero?

data/lib/smith/workflow/retry_wait.rb

@@ -24,6 +24,7 @@ module Smith
       # it waits to make. Like any wait it is not a step. The pending retry
       # is recorded before the wait, so an interrupt between the two leaves
       # a step that ended without a wait, whose pending retry is cleared.
+      # The run waits without the failed attempt's tool captures.
       def wait_to_retry(transition, seconds, attempt, key_generation, error)
         if @split_step_phase == :executing
           raise WorkflowError, "a durable retry cannot wait inside split-step execution"
@@ -38,6 +39,7 @@ module Smith
         @awaiting = WaitRecord.build_retry(transition, wait_token_for(transition, ["retry", attempt]), seconds,
                                            Time.now.utc)
         record_retry_trace(transition, :retrying, attempt:, error: error_name, deadline_at: @awaiting["deadline_at"])
+        drop_attempt_tool_results(error)
         WAIT_PENDING
       end
 

data/lib/smith/workflow/step_context.rb

@@ -99,7 +99,8 @@ module Smith
         namespace = ArtifactIntegration.instance_method(:execution_namespace).bind_call(self)
         outer = IdempotencyKey.__send__(:current_scope)
         base = outer && outer.run == namespace ? outer : IdempotencyKey.__send__(:root_scope, namespace)
-        IdempotencyKey.__send__(:install, base.within(:step, @step_count + 1, transition.name.to_s))
+        position = base.within(:step, @step_count + 1, self.class.transition_key_name(transition.name))
+        IdempotencyKey.__send__(:install, position)
       end
 
       def teardown_step_context

data/lib/smith/workflow/wait_execution.rb

@@ -140,7 +140,8 @@ module Smith
 
       def wait_token_for(transition, scope)
         IdempotencyKey.__send__(:root_scope, ArtifactIntegration.instance_method(:execution_namespace).bind_call(self))
-                      .within(:step, @step_count + 1, transition.name.to_s).within(:wait).key(scope)
+                      .within(:step, @step_count + 1, self.class.transition_key_name(transition.name))
+                      .within(:wait).key(scope)
       end
 
       def check_wait_admissible!(transition, seconds)

data/lib/smith/workflow.rb

@@ -465,6 +465,17 @@ module Smith
       ->(entry) { @tool_results_mutex.synchronize { @tool_results << entry } }
     end
 
+    # Takes out what an attempt the step set aside had captured
+    # (Agent::AttemptCaptures), by identity, so an equal entry of another
+    # attempt or branch stays. `O(N + K)`.
+    def drop_tool_results(entries)
+      return if entries.empty?
+
+      dropped = {}.compare_by_identity
+      entries.each { dropped[_1] = true }
+      @tool_results_mutex.synchronize { @tool_results.reject! { dropped.key?(_1) } }
+    end
+
     def initialize_tool_result_state
       @tool_results = []
       @tool_results_mutex = Mutex.new

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: smith-agents
 version: !ruby/object:Gem::Version
-  version: 0.12.6
+  version: 0.13.0
 platform: ruby
 authors:
 - Samuel Ralak
@@ -161,6 +161,7 @@ files:
 - lib/generators/smith/install/templates/workflow_state.rb.tt
 - lib/smith.rb
 - lib/smith/agent.rb
+- lib/smith/agent/attempt_captures.rb
 - lib/smith/agent/attempt_chat.rb
 - lib/smith/agent/chat_construction.rb
 - lib/smith/agent/completion.rb
@@ -348,11 +349,13 @@ files:
 - lib/smith/tool/call_budget.rb
 - lib/smith/tool/call_reservation.rb
 - lib/smith/tool/capability_builder.rb
+- lib/smith/tool/capability_declaration.rb
 - lib/smith/tool/capture.rb
 - lib/smith/tool/capture_configuration.rb
 - lib/smith/tool/chat_execution_callbacks.rb
 - lib/smith/tool/chat_execution_context.rb
 - lib/smith/tool/compatibility.rb
+- lib/smith/tool/declarations.rb
 - lib/smith/tool/execution_authority.rb
 - lib/smith/tool/execution_authorization.rb
 - lib/smith/tool/execution_batch.rb
@@ -485,6 +488,7 @@ files:
 - lib/smith/workflow/graph/reachability.rb
 - lib/smith/workflow/graph/reachability_diagnostics.rb
 - lib/smith/workflow/graph/reference.rb
+- lib/smith/workflow/graph/rename_diagnostics.rb
 - lib/smith/workflow/graph/report.rb
 - lib/smith/workflow/graph/retry_policy_diagnostic.rb
 - lib/smith/workflow/graph/run_launcher_diagnostic.rb