smith-agents 0.12.0 → 0.12.2

data/lib/smith/workflow/remembered_calls.rb

@@ -6,16 +6,20 @@ module Smith
     # (Smith::ResponseMemo): each call takes its kept messages, if any, and
     # sends nothing when they end it (a streamed step's sink gets the reply's
     # text at once), else goes on from them, and is recorded as it goes.
-    # Kept tool results count as tools the step ran, and the live part goes
-    # on from the kept rounds (Resumed): its first request is a later round,
-    # and a pause for budget keeps the kept rounds too.
+    # Kept tool results count as tools the step ran, charged to its
+    # tool-call allowances as they were before the cut; a kept reply whose
+    # tools had not run is the answer to the live part's first request, and
+    # its tools run. The live part goes on from the kept rounds (Resumed):
+    # its first request is a later round, a pause for budget keeps the kept
+    # rounds too, and a streamed one's facts pair with its live replies.
     module RememberedCalls
       CALLS_LOCK = Mutex.new
       private_constant :CALLS_LOCK
 
-      # Where a call's live part starts: the call's first message, and the
-      # rounds its kept messages made.
-      Resumed = Data.define(:start, :rounds)
+      # Where a call's live part starts: the call's first message, the
+      # rounds its kept messages made, and its kept reply whose tools had
+      # not run (one of those rounds).
+      Resumed = Data.define(:start, :rounds, :pending)
 
       private
 
@@ -26,39 +30,68 @@ module Smith
 
         start = chat.messages.length
         kept = ResponseMemo.fetch(memo, key)
-        keep_messages(chat, kept.fetch(:messages)) if kept
+        keep_messages(chat, kept) if kept
         return replayed_completion(chat, model_reference) if kept&.fetch(:complete)
 
-        recorded_completion(chat, memo, key, Resumed.new(start:, rounds: kept_rounds(kept)), &)
+        recorded_completion(chat, memo, key, resumed(start, kept), &)
       end
 
-      def kept_rounds(kept) = kept ? kept.fetch(:messages).count { _1.role == :assistant } : 0
+      def resumed(start, kept)
+        return Resumed.new(start:, rounds: 0, pending: nil) unless kept
+
+        pending = kept.fetch(:pending)
+        Resumed.new(start:, rounds: kept.fetch(:messages).count { _1.role == :assistant } + (pending ? 1 : 0), pending:)
+      end
 
       def memo_key(chat, facts)
         ResponseMemo.key([*@memo_attempts, @step_attempt.to_i], facts[:attempt_index], next_memo_call, chat)
       end
 
       # The kept messages, after the call's own; their tool results are
-      # tools the step ran.
-      def keep_messages(chat, messages)
+      # tools the step ran, each charged as it was.
+      def keep_messages(chat, kept)
+        messages = kept.fetch(:messages)
         messages.each { chat.add_message(_1) }
-        Tool.current_tool_execution_tracker&.mark_started! if messages.any? { _1.role == :tool }
+        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))
+      end
+
+      def ran_calls(messages, ran) = messages.flat_map { _1.tool_calls&.values.to_a }.select { ran.include?(_1.id) }
+
+      # 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
+      # lowered since, or a call rejected for budget) charges nothing more.
+      def charge_kept_calls(calls)
+        allowance = Tool.current_tool_call_allowance
+        ledger = Tool.current_ledger
+        commit = -> { ledger.reconcile!(ledger.reserve!(:tool_calls, 1), 1) if ledger&.limits&.key?(:tool_calls) }
+        calls.each { allowance.is_a?(Tool::CallAllowance) ? allowance.charge!(_1.name, &commit) : commit.call }
+      rescue BudgetExceeded
+        nil
       end
 
+      # A call a tool halted ends in that tool's result, not a reply: it
+      # keeps its progress, which a replay can go on from.
       def recorded_completion(chat, memo, key, resumed)
-        live = chat.messages.length
-        result = ResponseMemo.recording(chat_provider(chat), memo, key, resumed.start) { yield(resumed) }
-        ResponseMemo.store(memo, key, chat.messages.drop(resumed.start), complete: true,
-                                                                         facts: streamed_facts(chat, live, result))
+        result = ResponseMemo.recording(chat_provider(chat), memo, key, resumed.start, resumed.pending) do
+          yield(resumed)
+        end
+        messages = chat.messages.drop(resumed.start)
+        if ResponseMemo.answer?(messages.last)
+          ResponseMemo.store(memo, key, messages, complete: true, facts: streamed_facts(messages, result))
+        end
         result
       end
 
-      # A streamed call's replies' facts, read from its stream.
-      def streamed_facts(chat, live, result)
+      # A streamed call's replies' facts, read from its stream (its kept
+      # replies, which no round of it answered, keep their own).
+      def streamed_facts(messages, result)
         stream = result[1]
         return {} unless stream.is_a?(Hash) && stream[:rounds]
 
-        replies = chat.messages.drop(live).select { _1.role == :assistant }
+        replies = messages.select { _1.role == :assistant }
         replies.zip(Providers::StreamFacts.per_message(replies, stream[:rounds], stream[:output_limit]))
                .to_h.compare_by_identity
       end

data/lib/smith/workflow/retry_execution.rb

@@ -39,6 +39,7 @@ module Smith
           attempt_scope = attempt_idempotency_scope(key_generation)
           run_attempt_under_keys(transition, attempt_scope)
         rescue StandardError => e
+          Interruptions.pass!(e)
           raise unless retry_transition_error?(config, e, attempt)
 
           key_generation += 1 if new_idempotency_key_after?(config, e, attempt_scope)

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

@@ -54,6 +54,7 @@ module Smith
           end
           [output, nil]
         rescue StandardError => e
+          Interruptions.pass!(e)
           [nil, e]
         end
 

data/lib/smith/workflow/step_context.rb

@@ -16,6 +16,7 @@ module Smith
           install_step_idempotency_scope(transition)
           Thread.handle_interrupt(Object => :immediate, &block)
         rescue StandardError => e
+          Interruptions.pass!(e)
           @outcome = nil
           GuardrailIntegration.instance_method(:handle_step_failure).bind_call(self, transition, e)
         ensure

data/lib/smith.rb

@@ -79,6 +79,14 @@ module Smith
     :response_memo, { fetch: "fetch(key)", store: "store(key, record)" }
   )
 
+  # Errors that interrupt a step instead of failing it, such as the host's
+  # database or queue out of reach (Smith::Interruptions). A step that meets
+  # one, raised in it or as the cause of an error that was, stops where it
+  # is, as if its worker had stopped: no failure route, no retry, no failure
+  # recorded, and the error reaches the caller as it was raised.
+  setting :interrupting_errors, default: [].freeze,
+                                constructor: SettingConstructors.error_classes(:interrupting_errors)
+
   # How long a provider request's hold on a host's budget ledger
   # (`budget_ledger`) lasts unsettled, in seconds: past it the request's
   # process is taken to have died, and the ledger drops the hold. It must
@@ -203,6 +211,7 @@ require_relative "smith/providers/schema_constraints"
 require_relative "smith/tool_failure_notification_failed"
 require_relative "smith/persistence_payload_conflict"
 require_relative "smith/exponential_backoff"
+require_relative "smith/interruptions"
 
 # Event system (depends on Types)
 require_relative "smith/event"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: smith-agents
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.12.2
 platform: ruby
 authors:
 - Samuel Ralak
@@ -143,9 +143,15 @@ files:
 - README.md
 - Rakefile
 - UPSTREAM_PROPOSAL.md
+- docs/AGENTS.md
+- docs/BUDGETS.md
 - docs/CONFIGURATION.md
+- docs/DEVELOPMENT.md
+- docs/ERRORS_AND_RETRIES.md
+- docs/INSPECTION.md
 - docs/PATTERNS.md
 - docs/PERSISTENCE.md
+- docs/TESTING.md
 - docs/TOOLS_AND_GUARDRAILS.md
 - docs/workflow_claim.md
 - exe/smith
@@ -255,6 +261,7 @@ files:
 - lib/smith/guardrails/url_verifier.rb
 - lib/smith/idempotency_key.rb
 - lib/smith/idempotency_key/canonical.rb
+- lib/smith/interruptions.rb
 - lib/smith/launchers/inline.rb
 - lib/smith/message.rb
 - lib/smith/models.rb