actionagent 1.8.0 → 1.9.0

data/app/services/action_agent/agent_execution_service.rb

@@ -45,14 +45,21 @@ module ActionAgent
     HISTORY_TURN_LIMIT = 40
     HISTORY_CHAR_BUDGET = 60_000
 
-    def self.call(agent_record, run)
-      new(agent_record, run).call
+    # +resume+ continues a run that paused for input (AgentResumeJob):
+    #
+    #   checkpoint  the checkpoint the pause stored
+    #   answers     an answer per paused tool call id; false declines
+    #   secrets     the pause's `:secret` answers, scrubbed from everything
+    #               this execution records
+    def self.call(agent_record, run, resume: nil)
+      new(agent_record, run, resume: resume).call
     end
 
-    # Returns the providers in Agent::PROVIDERS a run on +owner+'s behalf has
-    # credentials for, in that order (see #available_providers).
-    def self.available_providers(owner)
-      new(nil, nil, owner: owner).available_providers
+    # Returns the providers in Agent::PROVIDERS a run on +owner+'s behalf,
+    # started by +actor+, has credentials for, in that order (see
+    # #available_providers).
+    def self.available_providers(owner, actor: nil)
+      new(nil, nil, owner: owner, actor: actor).available_providers
     end
 
     # Tool-call keywords that name the caller. The model's arguments and the
@@ -63,20 +70,35 @@ module ActionAgent
     ACTOR_KEYWORDS = %i[actor current_user].freeze
 
     # +owner+ is whose provider credentials the run uses: the agent record's
-    # owner unless given.
-    def initialize(agent_record, run, owner: nil)
+    # owner unless given. +actor+ is who those credentials are resolved for
+    # (see ProviderCredentials): the run's actor unless given. +resume+ carries
+    # a paused run's checkpoint and the secret answers it was given.
+    def initialize(agent_record, run, owner: nil, actor: nil, resume: nil)
       @agent_record = agent_record
       @run = run
       @owner = owner
+      @credentials_actor = actor
+      @resume = resume
+      @secrets = Array(resume&.dig(:secrets)).map(&:to_s)
       @tool_invocations = []
-      @event_sequence = 0
+      @event_sequence = resume ? recorded_event_count : 0
+    end
+
+    # Whether this execution continues a run that paused for input.
+    def resuming?
+      !@resume.nil?
     end
 
     # Returns the providers in Agent::PROVIDERS the owner's credentials, or
-    # the host's config, let a run use: #provider_available? for each.
+    # the host's config, let a run use: #provider_available? for each. A
+    # provider whose credentials cannot be resolved is left out.
     # @return [Array<String>]
     def available_providers
-      Agent::PROVIDERS.select { |name| provider_available?(name) }
+      Agent::PROVIDERS.select do |name|
+        provider_available?(name)
+      rescue ProviderCredentials::Unresolved
+        false
+      end
     end
 
     # The caller this run executes on behalf of, or nil when it runs
@@ -90,6 +112,7 @@ module ActionAgent
     # Emits a progress event on the run (streamed to the UI by pollers).
     # Never lets telemetry break execution.
     def emit_event(**kwargs)
+      kwargs[:detail] = scrub_secrets(kwargs[:detail]) if kwargs.key?(:detail)
       @run.append_event(**kwargs)
     rescue StandardError => e
       Rails.logger.warn("[AgentExecutionService] event emit failed: #{e.message}")
@@ -115,7 +138,9 @@ module ActionAgent
       @agent_record.ensure_executable!
       mcp_dispatcher.ensure_extra_servers_live!
       root_span = @root_span = build_root_span
-      record_prompt_span(root_span)
+      # A resumed segment sends the conversation its pause stored; the prompt
+      # span of the run's first segment already shows it.
+      record_prompt_span(root_span) unless resuming?
       llm_span = root_span.add_span(
         "llm.generate",
         span_type: :llm,
@@ -141,13 +166,17 @@ module ActionAgent
           duration_ms: ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - llm_started) * 1000).round,
           detail: "#{input} in / #{output} out tokens#{thinking.positive? ? " / #{thinking} thinking" : ""}"
         )
+        paused = response.respond_to?(:awaiting_input?) && response.awaiting_input?
         tool_calls = record_tool_spans(root_span, response)
-        persist_tool_messages(response)
+        # A paused turn's calls have no results yet; the segment that
+        # finishes the run persists the whole exchange once.
+        persist_tool_messages(response) unless paused
         sync_context_instructions
+        root_span.set_attribute("agent.awaiting_input", true) if paused
         root_span.finish
 
-        {
-          output: response.message&.content,
+        result = {
+          output: paused ? nil : response.message&.content,
           metadata: {
             provider: provider.to_s,
             model: model,
@@ -156,7 +185,7 @@ module ActionAgent
             requested_provider: @agent_record.provider,
             trace_id: root_span.trace_id,
             context_id: conversation_context&.id,
-            tool_calls: tool_calls
+            tool_calls: earlier_tool_calls + tool_calls
           },
           usage: {
             input_tokens: input,
@@ -164,6 +193,8 @@ module ActionAgent
             total_tokens: usage&.total_tokens || input + output + thinking
           }
         }
+        result.merge!(input_requests: response.input_requests, checkpoint: response.checkpoint) if paused
+        result
       rescue StandardError => e
         llm_span.record_error(e)
         llm_span.finish
@@ -173,6 +204,7 @@ module ActionAgent
         raise
       ensure
         record_trace(root_span)
+        finish_browser_recording
       end
     end
 
@@ -238,12 +270,13 @@ module ActionAgent
     # rows, keyed by tool_call_id, and this is a no-op.
     def persist_tool_invocations(context, response)
       return unless context.respond_to?(:add_tool_message)
-      return if @tool_invocations.empty?
+      return if response.try(:awaiting_input?)
+      return if completed_tool_invocations.empty?
       return if Array(response.respond_to?(:messages) ? response.messages : nil).any? do |message|
         message.respond_to?(:role) && message.role.to_s == "tool"
       end
 
-      @tool_invocations.each do |invocation|
+      completed_tool_invocations.each do |invocation|
         context.add_tool_message(
           tool_call_id: nil,
           tool_name: invocation[:name],
@@ -275,12 +308,19 @@ module ActionAgent
       @run_params ||= (@run.input_params || {}).with_indifferent_access
     end
 
+    # A resumed run keeps the provider and model it paused on: its checkpoint
+    # holds that provider's native messages, even if the agent was edited
+    # since.
     def requested_provider
-      @requested_provider ||= (run_params[:provider_override].presence || @agent_record.provider).to_s
+      @requested_provider ||= (paused_metadata["provider"].presence || run_params[:provider_override].presence || @agent_record.provider).to_s
     end
 
     def requested_model
-      @requested_model ||= run_params[:model_override].presence || @agent_record.model
+      @requested_model ||= paused_metadata["model"].presence || run_params[:model_override].presence || @agent_record.model
+    end
+
+    def paused_metadata
+      resuming? ? @run.output_metadata.to_h : {}
     end
 
     # Returns the provider used for this execution, or raises when its
@@ -316,6 +356,11 @@ module ActionAgent
     # Each call is wrapped in a live :tool span (real start/end around the
     # execution) and recorded in @tool_invocations so tool names, arguments
     # and durations reach Traces and the persisted conversation.
+    #
+    # A call that asks a person returns an ActiveAgent::InputRequest, which
+    # pauses the run: the input tools, and any tool on the agent's
+    # approval_required_tools until its call is approved. The span and the
+    # run's events mark such a call as awaiting rather than done.
     def execute_tool(name, **kwargs)
       forged = kwargs.slice(*ACTOR_KEYWORDS)
       if forged.any?
@@ -327,11 +372,12 @@ module ActionAgent
       # path the model passed — spans/events/persisted args stay unambiguous.
       kwargs[:url] = AgentToolbox.resolve_browse_url(kwargs[:url]) if name.to_s == "browse_page" && kwargs[:url]
 
+      tool_call_id = ActiveAgent::InputRequest.current_tool_call_id
       span = @root_span&.add_span("tool.#{name}", span_type: :tool)
       span&.set_attribute("tool.name", name.to_s)
       # tool.input.args is the key the Traces UI and TraceInteractionSerializer
       # read — the call's in: side.
-      span&.set_attribute("tool.input.args", kwargs.to_json.byteslice(0, 500).to_s.scrub) if kwargs.present?
+      span&.set_attribute("tool.input.args", scrub_secrets(kwargs.to_json).byteslice(0, 500).to_s.scrub) if kwargs.present?
       started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
 
       event_kind = name.to_s == "call_agent" ? "agent" : "tool"
@@ -340,39 +386,20 @@ module ActionAgent
       emit_event(eid: event_id, kind: event_kind, label: event_label, status: "started", detail: kwargs.to_json)
 
       result = begin
-        case name.to_s
-        when "save_memory"
-          entry = agent_memory.remember(
-            kwargs[:content].to_s,
-            source_agent: agent_class_name,
-            category: kwargs[:category]
-          )
-          { saved: true, id: entry.id, content: entry.content }
-        when "recall_memory"
-          entries = agent_memory.recall(limit: kwargs[:limit], category: kwargs[:category])
-          {
-            count: entries.size,
-            entries: entries.map do |entry|
-              {
-                content: entry.content,
-                category: entry.category,
-                source_agent: entry.source_agent,
-                created_at: entry.created_at&.iso8601
-              }.compact
-            end
-          }
-        when "call_agent"
-          call_agent(slug: kwargs[:slug], message: kwargs[:message])
-        else
-          # A tool one of the agent's own MCP servers serves is called there;
-          # AgentToolbox answers the rest.
-          # `actor:` comes from the run, never from kwargs (see
-          # ACTOR_KEYWORDS): it is who the run is for, not what it is about.
-          mcp_dispatcher.call(name, kwargs) || AgentToolbox.call(name, actor: actor, **kwargs)
-        end
+        approval_request(name, kwargs, tool_call_id) || dispatch_tool(name, kwargs, tool_call_id)
       rescue StandardError => e
-        Rails.logger.warn("[AgentExecutionService] Tool #{name} failed: #{e.class} - #{e.message}")
-        { error: "#{name} failed: #{e.message}" }
+        message = scrub_secrets(e.message)
+        Rails.logger.warn("[AgentExecutionService] Tool #{name} failed: #{e.class} - #{message}")
+        { error: "#{name} failed: #{message}" }
+      end
+      result = scrub_secrets(result)
+
+      if result.is_a?(ActiveAgent::InputRequest)
+        span&.set_attribute("tool.awaiting_input", true)
+        span&.finish
+        emit_event(eid: event_id, kind: event_kind, label: event_label, status: "awaiting", detail: result.prompt)
+        @tool_invocations << { name: name.to_s, arguments: kwargs, tool_call_id: tool_call_id, awaiting_input: true }
+        return result
       end
 
       duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round(2)
@@ -397,6 +424,7 @@ module ActionAgent
       @tool_invocations << {
         name: name.to_s,
         arguments: kwargs,
+        tool_call_id: tool_call_id,
         result: result,
         duration_ms: duration_ms,
         error: errored
@@ -407,6 +435,234 @@ module ActionAgent
 
     private
 
+    # -- Browser runs: recording and handoff ---------------------------------
+    #
+    # An agent with the +playwright_mcp+ tools drives the platform's browser.
+    # Its browser tool calls are written to a SessionRecording tied to the run,
+    # so Session Replay plays the run back; and when the page asks for
+    # something only a person may give, the agent calls +request_handoff+,
+    # which stores the page URL and the values entered so far on that
+    # recording. Session Replay's Take Over Session then opens that page for
+    # the person — the agent registers, the person pays.
+
+    # At most this many entered values are kept, each clipped to this length.
+    HANDOFF_FORM_VALUE_LIMIT = 40
+    HANDOFF_FORM_VALUE_LENGTH = 200
+    # A value under a key that looks like a secret is never stored: a person
+    # checks what the agent filled in, not what the agent must never see.
+    HANDOFF_SECRET_KEY = /card|cvc|cvv|expir|password|passcode|secret|token|otp|ssn|iban|account.?number/i
+
+    def browser_tools_enabled?
+      Array(@agent_record.tools).map(&:to_s).include?("playwright_mcp")
+    end
+
+    def request_handoff(reason: nil, url: nil, form_values: nil, instructions: nil)
+      unless browser_tools_enabled?
+        return { error: "request_handoff needs the browser tools (playwright_mcp) enabled on this agent" }
+      end
+      return { error: "request_handoff needs the url of the page the person continues on" } if url.blank?
+
+      middleware = browser_recorder
+      return { error: "request_handoff could not open the run's session recording" } unless middleware.recording
+
+      reason = reason.to_s.strip.presence || "a step only a person can take"
+      values = handoff_form_values(form_values)
+      middleware.capture_for_handoff(url: url.to_s, form_values: values)
+      middleware.recording_service.handoff(reason: reason, url: url.to_s, instructions: instructions.presence)
+      recording = middleware.recording_service.recording
+      @run.add_log("Handoff requested: #{reason} at #{url}")
+
+      {
+        handed_off: true,
+        recording_id: recording.id,
+        url: url.to_s,
+        reason: reason,
+        form_values: values,
+        message: "Stopped before #{reason}. A person continues from Session Replay → Take Over Session. " \
+                 "Take no further browser actions; report where you stopped and what you entered."
+      }
+    end
+
+    def handoff_form_values(values)
+      return nil unless values.respond_to?(:to_h)
+
+      values.to_h.first(HANDOFF_FORM_VALUE_LIMIT).each_with_object({}) do |(key, value), kept|
+        next if key.to_s.match?(HANDOFF_SECRET_KEY)
+        next unless value.is_a?(String) || value.is_a?(Numeric) || value == true || value == false
+
+        kept[key.to_s] = value.to_s.byteslice(0, HANDOFF_FORM_VALUE_LENGTH).to_s.scrub
+      end.presence
+    end
+
+    # Closes the run's recording when the run recorded anything. A run whose
+    # tools never touched the browser has no recording, and gets none here.
+    def finish_browser_recording
+      @browser_recorder&.complete! if @browser_recorder&.recording_started?
+    rescue StandardError => e
+      Rails.logger.warn("[AgentExecutionService] could not complete the session recording: #{e.message}")
+    end
+
+    # Routes one tool call to its implementation. A run with an engine
+    # toolset reaches that toolset and request_secret, and nothing else.
+    def dispatch_tool(name, kwargs, tool_call_id)
+      if engine_toolset
+        return request_secret(tool_call_id, kwargs) if name.to_s == "request_secret"
+
+        return engine_toolset.call(name.to_s, kwargs)
+      end
+
+      case name.to_s
+      when "ask_user" then ask_user(tool_call_id, kwargs)
+      when "request_approval" then request_approval(tool_call_id, kwargs)
+      when "request_secret" then request_secret(tool_call_id, kwargs)
+      when "save_memory"
+        entry = agent_memory.remember(
+          kwargs[:content].to_s,
+          source_agent: agent_class_name,
+          category: kwargs[:category]
+        )
+        { saved: true, id: entry.id, content: entry.content }
+      when "recall_memory"
+        entries = agent_memory.recall(limit: kwargs[:limit], category: kwargs[:category])
+        {
+          count: entries.size,
+          entries: entries.map do |entry|
+            {
+              content: entry.content,
+              category: entry.category,
+              source_agent: entry.source_agent,
+              created_at: entry.created_at&.iso8601
+            }.compact
+          end
+        }
+      when "call_agent"
+        call_agent(slug: kwargs[:slug], message: kwargs[:message])
+      when "request_handoff"
+        request_handoff(**kwargs.slice(:reason, :url, :form_values, :instructions))
+      else
+        # A tool one of the agent's own MCP servers serves is called there;
+        # AgentToolbox answers the rest. A browser action is also written to
+        # the run's session recording, so the run plays back in Session Replay
+        # and can hand off.
+        # `actor:` comes from the run, never from kwargs (see
+        # ACTOR_KEYWORDS): it is who the run is for, not what it is about.
+        browser_recorder.intercept(tool_name: name.to_s, parameters: kwargs) do
+          mcp_dispatcher.call(name, kwargs) || AgentToolbox.call(name, actor: actor, **kwargs)
+        end
+      end
+    end
+
+    # A confirm request for a call to a tool on the agent's approval list,
+    # until a person approved that call. A declined call is never dispatched
+    # again, so it does not reach this. The input tools ask on their own and
+    # are never gated.
+    def approval_request(name, kwargs, tool_call_id)
+      return nil if AgentToolbox::INPUT_FUNCTIONS.include?(name.to_s)
+      return nil unless @agent_record.approval_required_tools.include?(name.to_s)
+      return nil if ActiveAgent::InputRequest.answer_for(tool_call_id) == true
+
+      ActiveAgent::InputRequest.confirm("Allow #{name} to run?", metadata: { arguments: kwargs })
+    end
+
+    # Asks a question, or, with options, for one of them. Dispatched again
+    # with the answer, it returns that answer as the call's result.
+    def ask_user(tool_call_id, kwargs)
+      answer = ActiveAgent::InputRequest.answer_for(tool_call_id)
+      return { answer: answer } unless answer.nil?
+
+      question = kwargs[:question].to_s
+      options = Array(kwargs[:options]).map(&:to_s).reject(&:blank?)
+      return ActiveAgent::InputRequest.text(question) if options.empty?
+
+      ActiveAgent::InputRequest.choice(question, options: options)
+    end
+
+    # Asks a person to approve the action the model describes.
+    def request_approval(tool_call_id, kwargs)
+      return { approved: true } if ActiveAgent::InputRequest.answer_for(tool_call_id) == true
+
+      ActiveAgent::InputRequest.confirm(kwargs[:action].to_s, metadata: { arguments: kwargs })
+    end
+
+    # Asks a person for a secret and, dispatched again with it, hands the
+    # value to the agent's registered handler (SecretRequests). The model
+    # reads only that it was provided.
+    def request_secret(tool_call_id, kwargs)
+      handler = SecretRequests.handler_for(@agent_record)
+      return { error: "request_secret is not available to this agent" } unless handler
+
+      name = kwargs[:name].to_s
+      value = ActiveAgent::InputRequest.answer_for(tool_call_id)
+      if value.nil?
+        refusal = SecretRequests.refusal(@agent_record, run: @run, name: name)
+        return { error: refusal } if refusal
+
+        return ActiveAgent::InputRequest.secret(
+          SecretRequests.prompt(@agent_record, run: @run, name: name, prompt: kwargs[:prompt].presence || "Provide #{name}")
+        )
+      end
+
+      arguments = { run: @run, name: name, value: value.to_s }
+      arguments[:tool_call_id] = tool_call_id if takes_keyword?(handler, :tool_call_id)
+      handler.call(**arguments)
+      { provided: true, name: name }
+    end
+
+    # Whether +callable+ (a block, or an object's #call) takes +keyword+.
+    def takes_keyword?(callable, keyword)
+      parameters = callable.is_a?(Proc) ? callable.parameters : callable.method(:call).parameters
+      parameters.any? { |type, name| type == :keyrest || (%i[key keyreq].include?(type) && name == keyword) }
+    end
+
+    # The names of the tools the run's earlier segments called, for a resumed
+    # run's metadata; empty for a run's first segment.
+    def earlier_tool_calls
+      return [] unless resuming?
+
+      Array(@run.output_metadata.to_h["tool_calls"])
+    end
+
+    # How many progress events the run already holds, so a resumed segment's
+    # event ids do not repeat its earlier segments'.
+    def recorded_event_count
+      Array(@run.logs).count { |entry| entry.is_a?(Hash) && entry.key?("eid") }
+    end
+
+    # Returns +value+ with every secret answer this execution was given
+    # replaced by ActiveAgent::InputRequest::FILTERED.
+    def scrub_secrets(value)
+      @secrets.empty? ? value : ActiveAgent::InputRequest.scrub(value, @secrets)
+    end
+
+    # Returns a flattened span with the secrets scrubbed from its attribute
+    # values, status message and events. Its ids, name and every key are kept
+    # whole, so a secret can never break the span's links to its parent.
+    def scrub_span(span)
+      return span if @secrets.empty?
+
+      span.merge(
+        "attributes" => scrub_values(span["attributes"]),
+        "status_message" => scrub_secrets(span["status_message"]),
+        "events" => scrub_values(span["events"])
+      )
+    end
+
+    # Returns +value+ with the secrets scrubbed from the values at any depth
+    # of a Hash or Array, and every Hash key as it is.
+    def scrub_values(value)
+      case value
+      when Hash then value.transform_values { |item| scrub_values(item) }
+      when Array then value.map { |item| scrub_values(item) }
+      else scrub_secrets(value)
+      end
+    end
+
+    # Options added to the provider's for this run, such as a
+    # max_tool_turns cap above the provider's default.
+    def generation_options
+      {}
+    end
+
     # Maximum agent-to-agent delegation depth for the call_agent tool. A
     # thread-local counter guards it because the sub-agent runs synchronously
     # on the same thread via Agent#test_execute.
@@ -417,9 +673,34 @@ module ActionAgent
     # sub-run is a real AgentRun with its own trace.
     # One dispatcher per run, so every tool call shares the MCP sessions the
     # first call opens. A run given a checkout sandbox (an evaluation or a
-    # runner run against it) reaches that runtime too.
+    # runner run against it) reaches that runtime too, and the sandbox's
+    # browser when it was running as the run was created.
     def mcp_dispatcher
-      @mcp_dispatcher ||= MCPToolDispatcher.new(@agent_record, extra_server_keys: [ @run.try(:sandbox_server_key) ].compact)
+      @mcp_dispatcher ||= MCPToolDispatcher.new(
+        @agent_record, extra_server_keys: [ @run.try(:sandbox_server_key), @run.try(:browser_server_key) ].compact
+      )
+    end
+
+    # How many rows of each credential the recording secrets are read from.
+    RECORDING_SECRET_LOOKUP_LIMIT = 50
+
+    def browser_recorder
+      @browser_recorder ||= MCPRecordingMiddleware.new(agent_run: @run, secrets: -> { recording_secrets })
+    end
+
+    # The credentials the run's owner holds, scrubbed from the browser
+    # actions the run records: provider keys, the GitHub token, and the
+    # runtime and browser tokens of the sandbox the run reaches.
+    def recording_secrets
+      sandbox_id = @run.try(:sandbox_id)
+      sandbox = sandbox_id && SandboxSession.for_owner(owner).find_by(session_id: sandbox_id)
+      [
+        *ProviderKey.for_owner(owner).limit(RECORDING_SECRET_LOOKUP_LIMIT).pluck(:credential, :api_key).flatten,
+        *GithubConnection.for_owner(owner).limit(RECORDING_SECRET_LOOKUP_LIMIT).pluck(:access_token),
+        sandbox&.runtime_mcp_token,
+        sandbox&.browser_token,
+        *owner_provider_options(requested_provider).values_at(:access_token, :api_key)
+      ].compact
     end
 
     # Splits the offered schemas the way `tool_schemas` assembles them, so the
@@ -456,6 +737,8 @@ module ActionAgent
       Thread.current[:agent_call_depth] = depth + 1
       begin
         sub_run = target.test_execute(message.to_s)
+        return delegated_input_required(target, sub_run) if sub_run.awaiting_input?
+
         {
           agent: target.slug,
           run_id: sub_run.id,
@@ -467,6 +750,24 @@ module ActionAgent
       end
     end
 
+    # A called agent that paused to ask a person cannot be resumed from here:
+    # nothing holds its checkpoint once this call returns. Its requests are
+    # cancelled, and its questions go back to the calling model, in the
+    # shape a framework delegation that paused returns.
+    def delegated_input_required(target, sub_run)
+      questions = sub_run.input_requests.pending.order(:id).pluck(:prompt)
+      sub_run.cancel!("Paused for input, which an agent called with call_agent cannot do")
+
+      {
+        error: "input_required",
+        agent: target.slug,
+        run_id: sub_run.id,
+        questions: questions,
+        message: "#{target.slug} stopped to ask the user for input, which an agent called with call_agent cannot do. " \
+                 "Answer with the information you already have, or ask the user yourself."
+      }
+    end
+
     # Keeps the persisted context's instructions current so the Interactions
     # view can render the conversation's system message.
     def sync_context_instructions
@@ -516,6 +817,7 @@ module ActionAgent
       action = action_name
       run_trace_id = trace_id
       tool_definitions = tool_schemas
+      extra_options = generation_options
       service = self
 
       # A dashboard-authored agent has no Ruby class — it is rows: a tool
@@ -532,6 +834,7 @@ module ActionAgent
       if (host_class = resolved_host_class)
         return run_host_class(host_class, actor: actor, action: action, run_trace_id: run_trace_id)
       end
+      resume = @resume
 
       agent_class = Class.new(ActiveAgent::Base) do
         # SolidAgent persists contexts under self.class.name; anonymous
@@ -563,9 +866,9 @@ module ActionAgent
 
         if effective_provider == :mock
           # Test environment only (see #provider_available?).
-          generate_with :mock
+          generate_with :mock, **extra_options
         else
-          generate_with effective_provider, model: provider_model, **model_options
+          generate_with effective_provider, model: provider_model, **model_options, **extra_options
         end
 
         # Expose the agent's server-executable tools as public methods so the
@@ -593,7 +896,8 @@ module ActionAgent
             load_context(contextable: agent_record)
           end
 
-          options = { messages: service.prompt_messages }
+          # A resume replaces the conversation with its checkpoint's.
+          options = { messages: resume ? [] : service.prompt_messages }
           options[:instructions] = instructions if instructions.present?
           options[:tools] = tool_definitions if tool_definitions.present?
           prompt(**options)
@@ -608,6 +912,8 @@ module ActionAgent
         # run detail API finds the run's slice of the conversation), with
         # the attachment manifest alongside.
         define_method(:persist_prompt_to_context) do
+          return if resuming?
+
           text = service.user_text
           return unless context && text.present?
 
@@ -615,6 +921,16 @@ module ActionAgent
         end
         private :persist_prompt_to_context
 
+        # A paused generation has no reply yet, and its tool-call turn holds
+        # calls without results. The segment that finishes the run records
+        # the reply and the whole tool exchange.
+        define_method(:persist_generation_to_context) do
+          return if generation_response.try(:awaiting_input?)
+
+          super()
+        end
+        private :persist_generation_to_context
+
         # solid_agent persists the tool exchange from the response's
         # tool-role messages. The Responses API carries function calls as
         # items rather than messages, so that list is empty and the
@@ -631,7 +947,14 @@ module ActionAgent
       # `as` carries the caller onto the agent instance, so an agent's own
       # before_action callbacks (ActiveAgent::Authorization) authorize
       # against the same person the tools are scoped to.
-      agent_class.as(actor).public_send(action).generate_now
+      perform(agent_class.as(actor).public_send(action))
+    end
+
+    # Generates, or continues the paused generation this execution resumes.
+    def perform(generation)
+      return generation.generate_now unless resuming?
+
+      generation.resume_now(checkpoint: @resume[:checkpoint], answers: @resume[:answers])
     end
 
     # Function-calling schemas for the agent's enabled tools that have
@@ -646,15 +969,38 @@ module ActionAgent
     # rest. Without the first half a tool the agent declares is never offered to
     # the model, which then answers from memory instead of calling it. Memoized
     # because listing a server's tools is a request to that server.
+    #
+    # A run that reaches its sandbox's browser gets the browser's tools from
+    # the MCP half only: the toolbox's browser tools have the same names, and
+    # a provider refuses a tool list that names one twice.
     def tool_schema_halves
       @tool_schema_halves ||=
         if provider == :mock
           [ [], [] ]
+        elsif engine_toolset
+          [ [], engine_toolset.definitions ]
         else
-          [ mcp_dispatcher.tool_definitions, AgentToolbox.definitions_for(@agent_record.tools) ]
+          [
+            mcp_dispatcher.tool_definitions,
+            AgentToolbox.definitions_for(@agent_record.tools, browser_attached: mcp_dispatcher.browser_attached?) + secret_request_definitions
+          ]
         end
     end
 
+    # The tools of a run the engine started for an agent it defines (see
+    # ProjectSetup.toolset_for). They replace whatever tools and MCP servers
+    # the agent record names. Nil for any other run.
+    def engine_toolset
+      return @engine_toolset if defined?(@engine_toolset)
+
+      @engine_toolset = ProjectSetup.toolset_for(@agent_record, @run)
+    end
+
+    # request_secret, for an agent the engine registered a handler for.
+    def secret_request_definitions
+      SecretRequests.handler_for(@agent_record) ? [ AgentToolbox::REQUEST_SECRET_DEFINITION ] : []
+    end
+
     # Persists the tool interaction stream to the solid_agent conversation
     # context so the Interactions view shows the full agent <-> tool
     # exchange. Deduped by tool_call_id — newer solid_agent versions persist
@@ -673,8 +1019,8 @@ module ActionAgent
         next if tool_call_id.present? && context.messages.exists?(role: "tool", tool_call_id: tool_call_id)
 
         # Provider tool messages often carry no name (Ollama's don't); fall
-        # back to the service's own invocation record, matched by order.
-        invocation = @tool_invocations[index]
+        # back to the service's own invocation record.
+        invocation = tool_invocation_for(tool_call_id, index)
         name = (message.name if message.respond_to?(:name)).presence || invocation&.dig(:name)
 
         context.add_tool_message(
@@ -689,11 +1035,31 @@ module ActionAgent
       Rails.logger.error("[AgentExecutionService] Failed to persist tool messages: #{e.message}")
     end
 
+    # The calls this execution ran to a result: not the ones that asked a
+    # person and left the run paused.
+    def completed_tool_invocations
+      @tool_invocations.reject { |invocation| invocation[:awaiting_input] }
+    end
+
+    # The invocation record for a response's tool message: by tool call id
+    # when both carry one, else by position among the tool messages. A
+    # resumed segment's response also holds the tool messages of earlier
+    # segments, which have no record here, so it matches by id only.
+    def tool_invocation_for(tool_call_id, index)
+      invocations = completed_tool_invocations
+      if tool_call_id.present?
+        match = invocations.find { |invocation| invocation[:tool_call_id].to_s == tool_call_id.to_s }
+        return match if match
+      end
+
+      invocations[index] unless resuming?
+    end
+
     # Tool names for run metadata. Spans are recorded live in execute_tool;
     # the response-message scan only covers calls the provider executed
     # without routing through the service (none today, but cheap insurance).
     def record_tool_spans(root_span, response)
-      return @tool_invocations.map { |invocation| invocation[:name] } if @tool_invocations.any?
+      return completed_tool_invocations.map { |invocation| invocation[:name] } if @tool_invocations.any?
 
       messages = response.respond_to?(:messages) ? Array(response.messages) : []
       tool_messages = messages.select { |message| message.respond_to?(:role) && message.role.to_s == "tool" }
@@ -732,7 +1098,7 @@ module ActionAgent
     def run_host_class(klass, actor:, action:, run_trace_id:)
       generation = klass.as(actor).public_send(action, **host_action_arguments(klass, action))
       generation.prompt_options[:trace_id] = run_trace_id if generation.respond_to?(:prompt_options)
-      generation.generate_now
+      perform(generation)
     end
 
     # A code agent's action takes named arguments (`ask(question:)`), so the
@@ -744,6 +1110,8 @@ module ActionAgent
       keyword ? { keyword.to_sym => user_text } : {}
     end
 
+    # Unresolved credentials propagate, so the run fails with that error
+    # rather than with ProviderNotConfiguredError.
     def provider_available?(name)
       # The gem's mock provider is a test double: accepted only in the test
       # environment so app runs can never store fabricated output.
@@ -758,18 +1126,22 @@ module ActionAgent
       else
         config[:access_token].present?
       end
+    rescue ProviderCredentials::Unresolved
+      raise
     rescue StandardError
       false
     end
 
-    # Credential overrides for +name+: whatever the host app resolves for
-    # this owner first, then the dashboard's own stored ProviderKey.
+    # Credential overrides for +name+, as ProviderCredentials resolves them
+    # for this owner and actor.
     def owner_provider_options(name)
       @owner_provider_options ||= {}
-      @owner_provider_options[name.to_s] ||= begin
-        from_host = ActionAgent.provider_credentials(owner, name.to_s)
-        from_host.presence || ProviderKey.for_owner(owner).find_by(provider: name.to_s)&.generation_options || {}
-      end
+      @owner_provider_options[name.to_s] ||=
+        ProviderCredentials.resolve(owner: owner, actor: credentials_actor, provider: name).options
+    end
+
+    def credentials_actor
+      @credentials_actor || @run&.actor
     end
 
     def build_root_span
@@ -971,7 +1343,7 @@ module ActionAgent
         environment: Rails.env,
         timestamp: Time.current.iso8601(6),
         resource_attributes: { "platform.agent_id" => @agent_record.id, "platform.run_id" => @run.id },
-        spans: flatten_spans(root_span)
+        spans: flatten_spans(root_span).map { |span| scrub_span(span) }
       }.as_json
 
       sdk_info = {
@@ -983,7 +1355,13 @@ module ActionAgent
 
       trace_model = ActionAgent.trace_model
       tenant = ActionAgent.tenant_for(owner)
-      return if trace_model.for_account(tenant).exists?(trace_id: root_span.trace_id)
+      existing = trace_model.for_account(tenant).find_by(trace_id: root_span.trace_id)
+      # A resumed segment shares its run's trace id, and its spans join the
+      # trace the run's earlier segments recorded.
+      if existing
+        existing.append_segment!(payload["spans"]) if resuming? && existing.respond_to?(:append_segment!)
+        return
+      end
 
       trace_model.create_from_payload(payload, sdk_info, account: tenant, agent: @agent_record)
     rescue StandardError => e