activeagent 1.8.1 → 1.9.1

data/lib/active_agent/generation_job.rb

@@ -18,6 +18,10 @@ module ActiveAgent
 
     rescue_from StandardError, with: :handle_exception_with_agent_class
 
+    # The arguments can hold a paused generation's whole conversation and the
+    # user's answers.
+    self.log_arguments = false
+
     # +actor+ is the caller the generation runs on behalf of
     # (ActiveAgent::Authorization). ActiveJob serializes it like any other
     # argument, so a record arrives as the same record the caller passed and
@@ -28,14 +32,17 @@ module ActiveAgent
     # Agent.embed(...), which have no action to call: +agent_method+ is then
     # the synthetic +__direct_*__+ name, so the generation is rebuilt from
     # +direct_args+ and +direct_options+ instead.
+    #
+    # +resume+ holds the +checkpoint+ and +answers+ a paused generation
+    # continues from (Generation#resume_later).
     def perform(agent, agent_method, generation_method, args:, kwargs: nil, params: nil, actor: nil,
-                direct_generation_type: nil, direct_args: nil, direct_options: nil)
+                direct_generation_type: nil, direct_args: nil, direct_options: nil, resume: nil)
       if direct_generation_type
         generation = ActiveAgent::Parameterized::DirectGeneration.new(
           agent.constantize, direct_generation_type.to_sym, params || {},
           *Array(direct_args), **(direct_options || {}).symbolize_keys
         )
-        return generation.public_send(generation_method)
+        return resume ? resume_generation(generation, resume) : generation.public_send(generation_method)
       end
 
       agent_class = params ? agent.constantize.with(params) : agent.constantize
@@ -45,11 +52,15 @@ module ActiveAgent
       else
         agent_class.public_send(agent_method, *args)
       end
-      prompt.send(generation_method)
+      resume ? resume_generation(prompt, resume) : prompt.send(generation_method)
     end
 
     private
 
+    def resume_generation(generation, resume)
+      generation.resume_now(checkpoint: resume.fetch("checkpoint"), answers: resume.fetch("answers"))
+    end
+
     # "Deserialize" the agent class name by hand in case another argument
     # (like a Global ID reference) raised DeserializationError.
     def agent_class

data/lib/active_agent/input_request/resume.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+module ActiveAgent
+  class InputRequest
+    # A paused generation's checkpoint together with the user's answers,
+    # checked against each other before anything runs.
+    #
+    # Checkpoint keys, as {Providers::InputRequests#checkpoint} writes them:
+    #   - `version`            the checkpoint format, {VERSION}
+    #   - `service`, `provider` the provider service and API that paused, e.g.
+    #                          `"OpenAI"` and `"OpenAI::Chat"`
+    #   - `model`              the model of the paused request
+    #   - `action_name`        the agent action the generation ran
+    #   - `tool_turns`         tool round-trips used, counted against `max_tool_turns`
+    #   - `tool_choice_cleared` whether a forced `tool_choice` was already
+    #                          cleared because the model used the tool
+    #   - `messages`           the provider-native conversation through the
+    #                          assistant turn that made the tool calls, without
+    #                          the messages the provider derives from instructions
+    #   - `tool_call_turn_size` how many of the last `messages` make up the turn
+    #                          that made the tool calls: 1, except where the
+    #                          provider sends a turn as several items (OpenAI
+    #                          Responses' reasoning and function_call items)
+    #   - `completed_results`  each finished call's result in JSON form, by tool call id
+    #   - `input_requests`     one {InputRequest#to_h} per paused call
+    #   - `approval_tool_calls` the paused calls that wait for approval before
+    #                          their tool runs
+    #   - `approved_tool_calls` the paused calls that were already approved to
+    #                          run and paused again on the tool's own request
+    #   - `mcp_tool_calls`     the paused calls a client-side MCP server serves
+    #
+    # @api private
+    class Resume
+      VERSION = 1
+
+      # @return [Array<InputRequest>] one per paused tool call
+      attr_reader :input_requests
+
+      # @param checkpoint [Hash] string or symbol keys
+      # @param answers [Hash] an answer per paused tool call id
+      # @raise [ResumeError] when the checkpoint is malformed, or the answers
+      #   leave a paused call unanswered, name a call that is not paused, or
+      #   do not fit their request's kind
+      def initialize(checkpoint:, answers:)
+        @checkpoint = checkpoint.to_h.deep_symbolize_keys
+        @answers    = answers.to_h.transform_keys(&:to_s)
+
+        raise ResumeError, "Unsupported checkpoint version #{@checkpoint[:version].inspect}" unless @checkpoint[:version] == VERSION
+        raise ResumeError, "The checkpoint has no tool-call turn to resume from" unless valid_tool_call_turn?
+
+        @input_requests = Array(@checkpoint[:input_requests]).map { InputRequest.from_h(_1) }
+        @completed      = @checkpoint[:completed_results].to_h.transform_keys(&:to_s)
+
+        assert_answers!
+      end
+
+      # @return [String, nil]
+      def service = @checkpoint[:service]
+
+      # @return [String, nil]
+      def provider = @checkpoint[:provider]
+
+      # @return [String, nil]
+      def model = @checkpoint[:model]
+
+      # @return [String, nil]
+      def action_name = @checkpoint[:action_name]
+
+      # @return [Integer]
+      def tool_turns = @checkpoint[:tool_turns].to_i
+
+      # @return [Boolean]
+      def tool_choice_cleared? = @checkpoint[:tool_choice_cleared] == true
+
+      # Returns the conversation before the turn that made the tool calls.
+      #
+      # @return [Array<Hash>]
+      def messages = Array(@checkpoint[:messages])[0...-tool_call_turn_size]
+
+      # Returns the messages of the turn that made the tool calls.
+      #
+      # @return [Array<Hash>]
+      def tool_call_turn = Array(@checkpoint[:messages]).last(tool_call_turn_size)
+
+      # @param id [String]
+      # @return [Boolean]
+      def completed?(id) = @completed.key?(id.to_s)
+
+      # @param id [String]
+      # @return [Object] the call's result, in JSON form
+      def completed_result(id) = @completed.fetch(id.to_s)
+
+      # @param id [String]
+      # @return [Boolean]
+      def declined?(id) = pending?(id) && @answers[id.to_s] == false
+
+      # @param id [String]
+      # @return [Object, nil] the answer for a paused call; nil for any other call
+      def answer(id) = pending?(id) ? @answers[id.to_s] : nil
+
+      # Whether a paused call was approved to run before it paused again on
+      # its tool's own request.
+      #
+      # @param id [String]
+      # @return [Boolean]
+      def approved?(id) = pending?(id) && approved_ids.include?(id.to_s)
+
+      # Whether the answers approve a paused call that waited for approval
+      # before its tool ran.
+      #
+      # @param id [String]
+      # @return [Boolean]
+      def approval_given?(id) = pending?(id) && approval_ids.include?(id.to_s) && @answers[id.to_s] == true
+
+      # @param id [String]
+      # @return [Boolean] whether a client-side MCP server served the paused call
+      def mcp_tool_call?(id) = pending?(id) && Array(@checkpoint[:mcp_tool_calls]).map(&:to_s).include?(id.to_s)
+
+      # Returns the answers given to `:secret` requests, which must not reach
+      # the model, telemetry or errors.
+      #
+      # @return [Array<String>]
+      def secret_answers
+        input_requests.select(&:secret?).filter_map do |request|
+          value = answer(request.tool_call_id)
+          value.to_s unless value == false
+        end
+      end
+
+      # @param action_name [String, Symbol, nil] the action the agent ran again
+      # @raise [ResumeError] when it is not the action that paused
+      def assert_action!(action_name)
+        return if self.action_name.to_s == action_name.to_s
+
+        raise ResumeError, "This checkpoint was taken in #{self.action_name.inspect}; it cannot resume #{action_name.to_s.inspect}"
+      end
+
+      # @raise [ResumeError] when the provider or model differ from the pause's,
+      #   since the checkpoint's messages are in that provider's native format
+      def assert_provider!(service:, provider:, model:)
+        return if [ self.service, self.provider ] == [ service, provider ] && (self.model.blank? || self.model == model.to_s)
+
+        raise ResumeError, "This checkpoint was taken on #{self.provider} (#{self.model}); " \
+                           "it cannot resume on #{provider} (#{model})"
+      end
+
+      # @param ids [Array<String>] the ids of the calls in the tool-call turn
+      # @raise [ResumeError] unless every call is either completed or paused
+      def assert_tool_calls!(ids)
+        ids     = ids.map(&:to_s)
+        unknown = ids.reject { completed?(_1) || pending?(_1) }
+        lost    = pending_ids - ids
+        return if unknown.empty? && lost.empty?
+
+        raise ResumeError, "The checkpoint's tool calls do not match its results and input requests " \
+                           "(unaccounted: #{unknown.join(", ").presence || "none"}; missing: #{lost.join(", ").presence || "none"})"
+      end
+
+      private
+
+      def tool_call_turn_size = (@checkpoint[:tool_call_turn_size] || 1).to_i
+
+      def valid_tool_call_turn?
+        size = tool_call_turn_size
+        size.positive? && Array(@checkpoint[:messages]).size >= size && tool_call_turn.all?(Hash)
+      end
+
+      def approval_ids = Array(@checkpoint[:approval_tool_calls]).map(&:to_s)
+
+      def approved_ids = Array(@checkpoint[:approved_tool_calls]).map(&:to_s)
+
+      def pending_ids = input_requests.map(&:tool_call_id)
+
+      def pending?(id) = pending_ids.include?(id.to_s)
+
+      def assert_answers!
+        unknown = @answers.keys - pending_ids
+        raise ResumeError, "No input request is waiting on #{unknown.join(", ")}" if unknown.any?
+
+        missing = pending_ids.select { @answers[_1].nil? }
+        raise ResumeError, "Missing answers for #{missing.join(", ")}" if missing.any?
+
+        input_requests.each { assert_answer_fits!(_1, @answers[_1.tool_call_id]) }
+      end
+
+      def assert_answer_fits!(request, answer)
+        return if answer == false
+
+        case request.kind
+        when :confirm
+          raise ResumeError, "Answer #{request.tool_call_id} with true to approve or false to decline" unless answer == true
+        when :choice
+          allowed = request.choice_values.map(&:to_s)
+          raise ResumeError, "#{answer.inspect} is not one of the options for #{request.tool_call_id}" unless allowed.include?(answer.to_s)
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/input_request.rb

@@ -0,0 +1,279 @@
+# frozen_string_literal: true
+
+module ActiveAgent
+  # A question a tool puts to the user in the middle of a generation.
+  #
+  # A tool returns one in place of a result. It is a value, not an exception.
+  # The provider leaves that call unanswered, finishes the other calls of the turn,
+  # and ends the generation paused: the response is
+  # {Providers::Common::Responses::Prompt#awaiting_input? awaiting input},
+  # lists the requests, and carries the checkpoint {Generation#resume_now}
+  # continues from. On resume the paused call is dispatched again, and the
+  # tool reads the user's answer through {.answer_for}.
+  #
+  # Kinds:
+  #   - `:text`    free text
+  #   - `:choice`  one of `options`
+  #   - `:confirm` approve (`true`) or decline (`false`)
+  #   - `:secret`  a value the model must never see, such as a token
+  #
+  # Answering `false` declines a request of any kind: the tool is not
+  # dispatched again and the model reads {DECLINED_RESULT} as its result.
+  #
+  # `options`, `schema`, `arguments` and `metadata` are stored in their JSON
+  # form, so a request survives a round trip through {#to_h} and {.from_h}
+  # unchanged.
+  #
+  # @example A tool that asks before acting
+  #   def issue_refund(order_id:, amount:)
+  #     unless input_answer
+  #       return ActiveAgent::InputRequest.confirm("Refund #{amount} on order #{order_id}?")
+  #     end
+  #
+  #     Refund.create!(order_id:, amount:)
+  #   end
+  class InputRequest < Data.define(:kind, :prompt, :options, :schema, :tool_call_id, :tool_name, :arguments, :metadata)
+    KINDS = %i[text choice confirm secret].freeze
+
+    # What the model reads for a declined request.
+    DECLINED_RESULT = { error: "declined by user" }.freeze
+
+    # Replaces a registered secret wherever {.scrub} finds it.
+    FILTERED = "[FILTERED]"
+
+    # Raised by {Generation#resume_now} before any tool runs or any request is
+    # sent, when the answers or the checkpoint do not fit the generation.
+    class ResumeError < ArgumentError; end
+
+    # Raised when a tool returns an InputRequest under a provider whose tool
+    # loop cannot pause.
+    class UnsupportedProviderError < StandardError; end
+
+    # Stands in for an error whose message held a secret, with the secret
+    # replaced and the original error's class name at the start of the
+    # message. {.raise_scrubbed} raises it in place of a tool's error whose
+    # class builds the message from its own state, and sets it as the cause
+    # in place of a cause chain that held a secret.
+    class ScrubbedError < StandardError; end
+
+    EXECUTION_STATE_KEY = :active_agent_input_request_tool_call
+    private_constant :EXECUTION_STATE_KEY
+
+    class << self
+      # @param prompt [String] the question shown to the user
+      # @return [InputRequest]
+      def text(prompt, **attributes) = new(kind: :text, prompt:, **attributes)
+
+      # @param prompt [String]
+      # @param options [Array] the answers to choose from, as values or
+      #   `{ value:, label: }` hashes
+      # @return [InputRequest]
+      def choice(prompt, options:, **attributes) = new(kind: :choice, prompt:, options:, **attributes)
+
+      # @param prompt [String]
+      # @return [InputRequest]
+      def confirm(prompt, **attributes) = new(kind: :confirm, prompt:, **attributes)
+
+      # @param prompt [String]
+      # @return [InputRequest]
+      def secret(prompt, **attributes) = new(kind: :secret, prompt:, **attributes)
+
+      # @param hash [Hash] the output of {#to_h}, with string or symbol keys
+      # @return [InputRequest]
+      def from_h(hash)
+        attributes = hash.to_h.symbolize_keys.slice(*members)
+        new(**attributes)
+      end
+
+      # Returns the answer delivered for a tool call while that call is being
+      # dispatched again on resume; nil at any other time.
+      #
+      # @param tool_call_id [String] the provider's id for the call
+      # @return [Object, nil]
+      def answer_for(tool_call_id)
+        state = ActiveSupport::IsolatedExecutionState[EXECUTION_STATE_KEY]
+        state[:answer] if state && state[:id] == tool_call_id.to_s
+      end
+
+      # Returns the provider's id for the tool call being dispatched, so a tool
+      # can look up its own answer; nil outside a tool call.
+      #
+      # @return [String, nil]
+      def current_tool_call_id
+        ActiveSupport::IsolatedExecutionState[EXECUTION_STATE_KEY]&.fetch(:id)
+      end
+
+      # Runs a tool call with its id, and its answer when there is one, in
+      # execution state. A nil `tool_call_id` runs the block outside any tool
+      # call, so it reads no id and no answer. A nested generation inside the
+      # call sees its own calls; the outer call's state is restored when the
+      # block returns.
+      #
+      # @param tool_call_id [String, nil]
+      # @param answer [Object, nil]
+      # @return [Object] the block's result
+      # @api private
+      def dispatching(tool_call_id, answer: nil)
+        previous = ActiveSupport::IsolatedExecutionState[EXECUTION_STATE_KEY]
+        ActiveSupport::IsolatedExecutionState[EXECUTION_STATE_KEY] = tool_call_id.nil? ? nil : { id: tool_call_id.to_s, answer: }
+
+        yield
+      ensure
+        ActiveSupport::IsolatedExecutionState[EXECUTION_STATE_KEY] = previous
+      end
+
+      # Returns `value` with every secret replaced by {FILTERED}, in strings at
+      # any depth of a Hash or Array. A number or symbol is compared in its
+      # string form, and becomes a string only when it holds a secret. A value
+      # of any other class is scrubbed in its JSON form, which is what a tool
+      # result becomes on its way to the model. An InputRequest is returned as
+      # it is.
+      #
+      # Secrets are matched as substrings, so a short secret also replaces the
+      # same characters inside unrelated values.
+      #
+      # @param value [Object]
+      # @param secrets [Array<String>]
+      # @return [Object]
+      def scrub(value, secrets)
+        secrets = normalize_secrets(secrets)
+        return value if secrets.empty?
+
+        scrub_value(value, secrets)
+      end
+
+      # Raises `error` with every secret removed from its message and from the
+      # messages of its causes.
+      #
+      # Raises `error` itself when none of those messages holds a secret.
+      # Otherwise raises a copy of `error` with the secrets in its message
+      # replaced, or a {ScrubbedError} when the copy's message still holds one.
+      # A cause chain that holds a secret is replaced by a single
+      # ScrubbedError for the first cause.
+      #
+      # @param error [Exception]
+      # @param secrets [Array<String>]
+      # @raise [Exception] always
+      def raise_scrubbed(error, secrets)
+        secrets = normalize_secrets(secrets)
+        raise error unless chain_holds_secret?(error, secrets)
+
+        cause = error.cause
+        cause = scrubbed_error(cause, secrets) if chain_holds_secret?(cause, secrets)
+
+        raise scrubbed_copy(error, secrets), cause:
+      end
+
+      private
+
+      def normalize_secrets(secrets)
+        Array(secrets).map(&:to_s).reject(&:empty?).uniq.sort_by { -_1.length }
+      end
+
+      def scrub_value(value, secrets)
+        case value
+        when String
+          secrets.reduce(value) { |text, secret| text.gsub(secret, FILTERED) }
+        when Hash
+          value.to_h { |key, item| [ scrub_value(key, secrets), scrub_value(item, secrets) ] }
+        when Array
+          value.map { scrub_value(_1, secrets) }
+        when Numeric, Symbol
+          text = value.to_s
+          scrubbed = scrub_value(text, secrets)
+          scrubbed == text ? value : scrubbed
+        when InputRequest, true, false, nil
+          value
+        else
+          scrub_value(value.as_json, secrets)
+        end
+      end
+
+      def holds_secret?(text, secrets) = secrets.any? { text.to_s.include?(_1) }
+
+      def chain_holds_secret?(error, secrets)
+        seen = []
+
+        while error && seen.none? { _1.equal?(error) }
+          return true if holds_secret?(error.message, secrets)
+
+          seen << error
+          error = error.cause
+        end
+
+        false
+      end
+
+      def scrubbed_copy(error, secrets)
+        copy = error.exception(scrub_value(error.message, secrets))
+        holds_secret?(copy.message, secrets) ? scrubbed_error(error, secrets) : copy
+      end
+
+      def scrubbed_error(error, secrets)
+        ScrubbedError.new("#{error.class.name}: #{scrub_value(error.message, secrets)}").tap do |scrubbed|
+          scrubbed.set_backtrace(error.backtrace) if error.backtrace
+        end
+      end
+    end
+
+    # @param kind [Symbol, String] one of {KINDS}
+    # @param prompt [String] the question shown to the user
+    # @param options [Array, nil] the answers to choose from; required for `:choice`
+    # @param schema [Hash, nil] a JSON Schema describing the answer
+    # @param tool_call_id [String, nil] set by the provider
+    # @param tool_name [String, nil] set by the provider
+    # @param arguments [Hash, nil] the arguments the model called the tool
+    #   with; set by the provider
+    # @param metadata [Hash] anything the host wants to keep with the request
+    # @raise [ArgumentError] for an unknown kind, a blank prompt, or a choice
+    #   without options
+    def initialize(kind:, prompt:, options: nil, schema: nil, tool_call_id: nil, tool_name: nil, arguments: nil, metadata: {})
+      kind = kind.to_s.to_sym
+      raise ArgumentError, "Unknown input request kind #{kind.inspect}; expected one of #{KINDS.join(", ")}" unless KINDS.include?(kind)
+      raise ArgumentError, "An input request needs a prompt" if prompt.blank?
+      raise ArgumentError, "A :choice input request needs options" if kind == :choice && options.blank?
+
+      super(
+        kind:,
+        prompt: prompt.to_s,
+        options: options&.then { Array.wrap(_1).as_json },
+        schema: schema&.as_json,
+        tool_call_id: tool_call_id&.to_s,
+        tool_name: tool_name&.to_s,
+        arguments: arguments&.as_json,
+        metadata: (metadata || {}).as_json
+      )
+    end
+
+    # Returns a copy bound to the tool call that returned it.
+    #
+    # @param id [String]
+    # @param name [String]
+    # @param arguments [Hash, nil]
+    # @return [InputRequest]
+    # @api private
+    def for_tool_call(id:, name:, arguments: nil)
+      self.class.new(**attributes.merge(tool_call_id: id, tool_name: name, arguments:))
+    end
+
+    # @return [Boolean]
+    def secret? = kind == :secret
+
+    # Returns the values a `:choice` answer may take: each option, or its
+    # `value` when the option is a hash.
+    #
+    # @return [Array]
+    def choice_values
+      Array(options).map { _1.is_a?(Hash) ? _1.fetch("value", _1["label"]) : _1 }
+    end
+
+    # @return [Hash{Symbol => Object}] JSON-safe attributes; nil ones are left out
+    def to_h = attributes.merge(kind: kind.to_s).compact
+
+    private
+
+    def attributes = self.class.members.to_h { [ _1, public_send(_1) ] }
+  end
+end
+
+require_relative "input_request/resume"