actionagent 1.8.1 → 1.9.0

data/app/jobs/action_agent/sandbox_provision_job.rb

@@ -7,7 +7,13 @@ module ActionAgent
 
     # Provision a Cloud Run sandbox for the session
     # Each sandbox is an instance of the ActiveAgents application running in sandbox mode
-    def perform(sandbox_session_id)
+    #
+    # @param options [Hash] for a checkout, at most one of
+    #   "boot"   => how to boot it, as SandboxBootSpec.request_options
+    #               returns it; without it, "auto"
+    #   "resume" => { "from" => a step name or nil }, to continue a failed
+    #               boot its backend kept (SandboxSession#resume_boot!)
+    def perform(sandbox_session_id, options = {})
       # Deleted before the job ran: nothing to provision. `find` raised here,
       # and the rescue below then called update! on nil.
       sandbox = SandboxSession.find_by(id: sandbox_session_id)
@@ -29,10 +35,26 @@ module ActionAgent
       # Hand off to whichever backend this install registered — the engine
       # ships the in-memory one and :local, so a real container/job comes
       # from the host app's backend (see ActionAgent.sandbox_backends).
-      ensure_checkout_available!(sandbox) if sandbox.app_runtime?
+      if sandbox.app_runtime?
+        ensure_checkout_available!(sandbox)
+        mint_checkout_token!(sandbox)
+      end
 
       orchestrator = SandboxOrchestrator.new
-      result = orchestrator.create_sandbox(sandbox)
+      options = options.is_a?(Hash) ? options : {}
+      # A project's checkout boots from the project's spec, built here so its
+      # secrets' values are read in this process and never enqueued.
+      project = sandbox.app_runtime? ? sandbox.project : nil
+      result =
+        if options["resume"].is_a?(Hash)
+          orchestrator.resume_boot(sandbox, from: options["resume"]["from"].presence, boot_config: project&.boot_spec(sandbox))
+        elsif project
+          orchestrator.create_sandbox(sandbox, boot_config: project.boot_spec(sandbox))
+        elsif (spec = sandbox.app_runtime? && boot_spec(options["boot"]))
+          orchestrator.create_sandbox(sandbox, boot_config: spec)
+        else
+          orchestrator.create_sandbox(sandbox)
+        end
       # From here on the backend runs a sandbox for this session: whatever
       # goes wrong below, the rescue releases it unless the session recorded
       # its handle.
@@ -46,6 +68,7 @@ module ActionAgent
         return
       end
 
+      project&.sandbox_ready!(sandbox, app_models: result[:app_models])
       # Broadcast status update
       broadcast_sandbox_update(sandbox)
     rescue StandardError => e
@@ -65,6 +88,21 @@ module ActionAgent
 
     private
 
+    # The boot spec a checkout's boot options ask for, or nil to boot it as
+    # its sandbox.yml says. A spec "auto" asked for that cannot be built
+    # (the engine's gems come from a git URL with credentials in it) is
+    # dropped with a warning, so a checkout that bundles the engine still
+    # boots. One asked for with "always" fails the boot with the reason.
+    def boot_spec(boot)
+      boot = boot.is_a?(Hash) ? boot : {}
+      SandboxBootSpec.for_request(boot)
+    rescue SandboxBootSpec::Invalid => e
+      raise "Sandbox boot spec is invalid: #{e.message}" if %w[always true].include?(boot["bootstrap"].to_s)
+
+      Rails.logger.warn("[ActionAgent] not bootstrapping checkouts without the engine: #{e.message}")
+      nil
+    end
+
     def simulate_provisioning(sandbox)
       # Simulate a small delay for provisioning
       sleep(0.5)
@@ -79,7 +117,12 @@ module ActionAgent
     # selection, between creating the session and this job running.
     # checkout_spec answers nil for the first and raises ArgumentError for
     # the second; both mean the same thing to the owner.
+    # A GitHub App installation can also have been unlinked, or found removed
+    # or suspended by an earlier mint.
     def ensure_checkout_available!(sandbox)
+      installation = sandbox.checkout_installation
+      raise reinstall_message(sandbox, installation.removed_at ? :removed : :suspended) if installation && !installation.usable?
+
       available = begin
         sandbox.checkout_spec.present?
       rescue ArgumentError
@@ -90,6 +133,30 @@ module ActionAgent
       raise "#{sandbox.repository} is no longer available: reconnect GitHub or reselect it in Settings -> Integrations"
     end
 
+    # The one mint of a provision (see SandboxSession#mint_checkout_spec!).
+    # The token stays on +sandbox+, the object the orchestrator hands the
+    # backend and #secrets_for reads, so the backend clones with exactly the
+    # value this job scrubs.
+    def mint_checkout_token!(sandbox)
+      sandbox.mint_checkout_spec!
+    rescue GithubClient::InstallationUnavailable => e
+      raise reinstall_message(sandbox, e.reason)
+    rescue GithubClient::Error => e
+      raise "Could not get a GitHub token to check out #{sandbox.repository}: #{e.message}"
+    end
+
+    def reinstall_message(sandbox, reason)
+      installation = sandbox.checkout_installation
+      on = installation ? " on #{installation.github_account_login}" : ""
+      if reason == :suspended
+        "The GitHub App installation#{on} is suspended, so #{sandbox.repository} cannot be checked out. " \
+          "Once it is unsuspended on GitHub, use Check again in Settings -> Integrations and start the sandbox again."
+      else
+        "The GitHub App installation#{on} was removed, so #{sandbox.repository} cannot be checked out. " \
+          "Reinstall the GitHub App in Settings -> Integrations and start the sandbox again."
+      end
+    end
+
     # Marks the session ready with the backend's endpoint, under a row lock
     # so a concurrent DELETE either lands first (and this reports false) or
     # finds the session ready with a handle to terminate: SandboxSession#expire!
@@ -134,13 +201,16 @@ module ActionAgent
       return unless sandbox.provisioning?
 
       sandbox.update!(status: :failed, error_message: message)
+      sandbox.project&.sandbox_failed!(sandbox)
       broadcast_sandbox_update(sandbox)
     rescue ActiveRecord::RecordNotFound
       nil
     end
 
-    # What must never reach error_message: the checkout token and the Claude
-    # Code credential this session boots with.
+    # What must never reach error_message: the checkout token, the Claude
+    # Code credential this session boots with, and its project's secrets.
+    # Reads the checkout without minting, so a GitHub App checkout
+    # contributes the token this job minted.
     def secrets_for(sandbox)
       return [] if sandbox.nil?
 
@@ -149,16 +219,13 @@ module ActionAgent
       rescue StandardError
         nil
       end
-      [ spec&.dig(:token), *sandbox.runtime_environment.values ].compact
+      [ spec&.dig(:token), *sandbox.runtime_environment.values, *sandbox.project_scrub_values ].compact
     rescue StandardError
       []
     end
 
     def broadcast_sandbox_update(sandbox)
-      ActionCable.server.broadcast(
-        "sandbox_#{sandbox.session_id}",
-        { type: "status_update", sandbox: sandbox.summary }
-      )
+      LiveUpdates.broadcast("sandbox_#{sandbox.session_id}", type: "status_update", id: sandbox.session_id, status: sandbox.status)
     end
   end
 end

data/app/jobs/action_agent/sandbox_run_job.rb

@@ -18,7 +18,7 @@ module ActionAgent
       started_at = Time.current
 
       # Broadcast that run has started
-      broadcast_run_started(sandbox, run_id, task, provider)
+      broadcast_run_started(sandbox, run_id)
 
       begin
         # Use ActiveAgent with generate_later for async processing
@@ -32,7 +32,7 @@ module ActionAgent
       rescue => e
         Rails.logger.error("Sandbox run failed: #{e.message}")
         back_to_ready(sandbox, error_message: e.message)
-        broadcast_run_error(sandbox, run_id, provider, e.message)
+        broadcast_run_error(sandbox, run_id)
       end
     end
 
@@ -247,46 +247,18 @@ module ActionAgent
       PROMPT
     end
 
-    def broadcast_run_started(sandbox, run_id, task, provider)
-      ActionCable.server.broadcast(
-        "sandbox_#{sandbox.session_id}",
-        {
-          type: "run_started",
-          run_id: run_id,
-          provider: provider,
-          task: task,
-          started_at: Time.current.iso8601
-        }
-      )
-      Rails.logger.info "[SandboxRunJob] Broadcast run_started for #{provider} (#{run_id})"
+    # The run messages carry the job's run_id; the run itself is read back
+    # from the session.
+    def broadcast_run_started(sandbox, run_id)
+      LiveUpdates.broadcast("sandbox_#{sandbox.session_id}", type: "run_started", id: run_id, status: "running")
     end
 
     def broadcast_run_complete(sandbox, run_id, run)
-      ActionCable.server.broadcast(
-        "sandbox_#{sandbox.session_id}",
-        {
-          type: "run_complete",
-          run_id: run_id,
-          provider: run[:provider],
-          run: run,
-          sandbox: sandbox.summary
-        }
-      )
-      Rails.logger.info "[SandboxRunJob] Broadcast run_complete for #{run[:provider]} (#{run_id})"
+      LiveUpdates.broadcast("sandbox_#{sandbox.session_id}", type: "run_complete", id: run_id, status: run[:status])
     end
 
-    def broadcast_run_error(sandbox, run_id, provider, error)
-      ActionCable.server.broadcast(
-        "sandbox_#{sandbox.session_id}",
-        {
-          type: "run_error",
-          run_id: run_id,
-          provider: provider,
-          error: error,
-          sandbox: sandbox.summary
-        }
-      )
-      Rails.logger.info "[SandboxRunJob] Broadcast run_error for #{provider} (#{run_id})"
+    def broadcast_run_error(sandbox, run_id)
+      LiveUpdates.broadcast("sandbox_#{sandbox.session_id}", type: "run_error", id: run_id, status: "failed")
     end
   end
 end

data/app/jobs/action_agent/verify_evaluation_fix_job.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  class VerifyEvaluationFixJob < ApplicationJob
+    queue_as :sandboxes
+
+    def perform(id)
+      session = CodeSession.find_by(id: id)
+      return unless session&.succeeded? && session.evaluation_run_id && session.diff.present?
+      sandbox = session.sandbox_session
+      run = nil
+      # Claim the verification under the checkout's lock: the pending run is
+      # what CodeSessionsController#busy_session waits on, so no later edit
+      # can race it. The restart happens after the lock is released, since
+      # it takes as long as a boot and the lock is a database row lock.
+      sandbox.with_lock do
+        session.reload
+        return if session.verification_run_id
+        raise "No reviewable git diff was captured for this fix" unless session.diff.start_with?("diff --git ")
+        raise "The sandbox is no longer running" unless sandbox.ready? && sandbox.active?
+        raise "Agent execution is disabled" unless ActionAgent.execution_enabled?
+        EvaluationFix.check_scenarios!(session.evaluation_run.evaluation, session.fix_item)
+        owner = session.evaluation_run.evaluation.agent.owner
+        raise "The sandbox is no longer available to the agent" unless SandboxSession.runtime_server_entry(sandbox.runtime_server_key, owner: owner)
+        selection = { "sandbox_id" => sandbox.session_id, "keys" => session.fix_item.fetch("scenario_keys"), "models" => session.fix_item.fetch("models") }
+        run = session.evaluation_run.evaluation.evaluation_runs.create!(status: :pending, selection: selection)
+        session.update!(verification_run: run, verification_error: nil)
+      end
+      SandboxOrchestrator.new.refresh_runtime(sandbox)
+      EvaluationRunJob.perform_later(run.evaluation_id, run.id, run.selection)
+    rescue StandardError => error
+      message = SecretScrubber.scrub(error.message, session&.secrets).truncate(1000)
+      run&.update!(status: :failed, error_message: message, completed_at: Time.current)
+      session&.update!(verification_error: message)
+    end
+  end
+end

data/app/models/action_agent/agent.rb

@@ -88,7 +88,7 @@ module ActionAgent
     # serialize. This constant stays the built-in set so existing references
     # keep their meaning.
     AVAILABLE_TOOLS = %w[
-      terminal playwright filesystem code database slack fetch search edit translate memory agents ui
+      terminal playwright filesystem code database slack fetch search edit translate memory agents ui ask
     ].freeze
 
     # One line per capability, for the roster rows that offer them. A name
@@ -107,7 +107,8 @@ module ActionAgent
       "translate" => "Translates text through the translation agent.",
       "memory" => "Reads and writes durable notes across runs of this agent.",
       "agents" => "Delegates a task to another agent in this workspace.",
-      "ui" => "Renders a form or table back into the chat surface."
+      "ui" => "Renders a form or table back into the chat surface.",
+      "ask" => "Pauses the run to ask the user a question or for approval, and continues with the answer."
     }.freeze
 
     # Every tool an agent may enable: the built-ins plus each tool generated by
@@ -246,16 +247,28 @@ module ActionAgent
         appearance: appearance,
         instruction_sets: instruction_sets,
         tools: tools,
+        approval_required_tools: approval_required_tools,
         mcp_servers: mcp_servers,
         model_config: model_config,
         response_format: response_format
       }
     end
 
+    # The tool names whose calls wait for a person to approve them before
+    # they run: toolbox tools, schema tools and the agent's MCP servers'
+    # tools alike. Empty on an install that has not run the migration adding
+    # the column.
+    # @return [Array<String>]
+    def approval_required_tools
+      return [] unless has_attribute?(:approval_required_tools)
+
+      Array(self[:approval_required_tools]).map(&:to_s).reject(&:blank?).uniq
+    end
+
     # Restore from a version
     def restore_from_version!(version)
       config = version.configuration_snapshot
-      update!(
+      attributes = {
         instructions: config["instructions"],
         action_prompts: config["action_prompts"] || [],
         preset_type: config["preset_type"],
@@ -265,7 +278,9 @@ module ActionAgent
         mcp_servers: config["mcp_servers"],
         model_config: config["model_config"],
         response_format: config["response_format"]
-      )
+      }
+      attributes[:approval_required_tools] = config["approval_required_tools"] || [] if has_attribute?(:approval_required_tools)
+      update!(attributes)
     end
 
     # Get the latest version
@@ -405,12 +420,16 @@ module ActionAgent
     # run reaches as if the agent had it in mcp_servers, without saving it on
     # the agent. The caller checks the sandbox is theirs and live; the
     # dispatcher still resolves it among this agent's owner's sessions only.
+    #
+    # A block is given the run before its job is enqueued, so whatever it
+    # records about the run is there when the job starts.
     def execute(input_prompt, action: nil, attachments: [], actor: nil, runtime_sandbox: nil, **params)
       ensure_executable!
       run = create_run(
         input_prompt, action: action, attachments: attachments, params: params,
         actor: actor, runtime_sandbox: runtime_sandbox, status: :pending
       )
+      yield run if block_given?
 
       # Queue the execution job
       AgentExecutionJob.perform_later(run.id)
@@ -418,7 +437,9 @@ module ActionAgent
       run
     end
 
-    # Quick test execution (synchronous)
+    # Quick test execution (synchronous). A run that pauses for input comes
+    # back `awaiting_input` with its requests stored, and AgentResumeJob
+    # finishes it once they are answered.
     def test_execute(input_prompt, action: nil, attachments: [], actor: nil, runtime_sandbox: nil, **params)
       ensure_executable!
       run = create_run(
@@ -431,27 +452,9 @@ module ActionAgent
         # Build and execute the agent
         result = AgentExecutionService.call(self, run)
 
-        run.update!(
-          output: result[:output],
-          output_metadata: result[:metadata],
-          status: :complete,
-          completed_at: Time.current,
-          duration_ms: ((Time.current - run.started_at) * 1000).to_i,
-          input_tokens: result.dig(:usage, :input_tokens),
-          output_tokens: result.dig(:usage, :output_tokens),
-          total_tokens: result.dig(:usage, :total_tokens)
-        )
+        run.record_result!(result, segment_started_at: run.started_at)
       rescue => e
-        run.update!(
-          status: :failed,
-          completed_at: Time.current,
-          error_message: e.message,
-          error_backtrace: e.backtrace&.first(10)&.join("\n"),
-          # The class, not only the message: an agent that refused this
-          # caller and an agent that broke both fail the run, and only the
-          # class tells them apart without reading prose.
-          output_metadata: run.output_metadata.to_h.merge("error_class" => e.class.name)
-        )
+        run.record_failure!(e)
       end
 
       run
@@ -490,6 +493,8 @@ module ActionAgent
       input_params = AgentRun.params_with_actor(params, actor)
       if SandboxSession.runtime_server_key?(runtime_sandbox)
         input_params = input_params.merge(AgentRun::SANDBOX_PARAM => runtime_sandbox.to_s)
+        browser = running_browser_key(runtime_sandbox)
+        input_params = input_params.merge(AgentRun::BROWSER_PARAM => browser) if browser
       end
 
       run = agent_runs.create!(
@@ -562,7 +567,7 @@ module ActionAgent
 
     VERSIONED_FIELDS = %w[
       instructions action_prompts preset_type appearance instruction_sets
-      tools mcp_servers model_config response_format
+      tools approval_required_tools mcp_servers model_config response_format
     ].freeze
 
     def configuration_changed?
@@ -580,6 +585,14 @@ module ActionAgent
       )
     end
 
+    # The browser key of the sandbox +runtime_sandbox+ names, when that
+    # sandbox is this agent's owner's and its browser is running.
+    def running_browser_key(runtime_sandbox)
+      session_id = runtime_sandbox.to_s.delete_prefix(SandboxSession::RUNTIME_SERVER_PREFIX)
+      sandbox = SandboxSession.for_owner(owner).find_by(session_id: session_id)
+      sandbox.browser_server_key if sandbox&.browser_running?
+    end
+
     # Unknown action names fall back to the default rather than failing the
     # run — an action can be renamed between enqueue and execution.
     def normalized_action(action)

data/app/models/action_agent/agent_run.rb

@@ -7,6 +7,9 @@ module ActionAgent
     # time, since a run is against the agent as it is.
     belongs_to :agent_version, optional: true
     before_create { self.agent_version_id ||= agent&.latest_version&.id }
+    has_many :input_requests, as: :subject, inverse_of: :subject, dependent: :destroy
+    has_many :pending_input_requests, -> { pending.for_listing.order(:id) },
+      class_name: "ActionAgent::InputRequest", as: :subject, inverse_of: :subject
 
     # Raised when a caller hands a run files to attach in a host app that
     # has nowhere to keep them.
@@ -20,9 +23,10 @@ module ActionAgent
     # the model (images and PDFs as data URIs, text inlined) and the
     # persisted user message keeps a manifest of them.
     #
-    # Guarded like RecordingSnapshot: a host app created with
-    # --skip-active-storage has no has_many_attached to call.
-    has_many_attached :attachments if defined?(ActiveStorage)
+    # Per ActionAgent.active_storage, like RecordingSnapshot: a host app
+    # created with --skip-active-storage has no has_many_attached to call,
+    # and a host may switch attachments off.
+    has_many_attached :attachments, **ActionAgent.attachment_options if ActionAgent.active_storage_macros?
 
     # The key the caller's identity is recorded under in +input_params+.
     # Underscored so it cannot collide with a provider override, and
@@ -33,6 +37,11 @@ module ActionAgent
     # the server, after it checked the caller owns that sandbox, and
     # stripped from anything a client sends, as the actor is.
     SANDBOX_PARAM = "_sandbox_server"
+    # The key of that sandbox's browser ("browser:<session_id>"), recorded
+    # when the browser was running as the run was created, so a run whose
+    # browser stops before it executes fails rather than running without
+    # it. Set and stripped like SANDBOX_PARAM.
+    BROWSER_PARAM = "_sandbox_browser"
 
     # +input_params+ with the caller recorded alongside them.
     #
@@ -47,7 +56,8 @@ module ActionAgent
     # @param actor [Object, nil] the caller
     # @return [Hash]
     def self.params_with_actor(params, actor)
-      params = (params || {}).to_h.except(ACTOR_PARAM, ACTOR_PARAM.to_sym, SANDBOX_PARAM, SANDBOX_PARAM.to_sym)
+      params = (params || {}).to_h.except(ACTOR_PARAM, ACTOR_PARAM.to_sym, SANDBOX_PARAM, SANDBOX_PARAM.to_sym,
+        BROWSER_PARAM, BROWSER_PARAM.to_sym)
       gid = actor.respond_to?(:to_global_id) ? actor.to_global_id.to_s : nil
       gid ? params.merge(ACTOR_PARAM => gid) : params
     rescue StandardError => e
@@ -83,6 +93,14 @@ module ActionAgent
       sandbox_server_key&.delete_prefix(SandboxSession::RUNTIME_SERVER_PREFIX)
     end
 
+    # The "browser:<session_id>" key of that sandbox's browser, when it was
+    # running as the run was created, or nil.
+    # @return [String, nil]
+    def browser_server_key
+      key = input_params[BROWSER_PARAM] if input_params.is_a?(Hash)
+      key.to_s.presence if sandbox_server_key && SandboxSession.browser_server_key?(key)
+    end
+
     # Whether this run knows who it is for. A run with a recorded actor that
     # no longer resolves is *not* unattributed — it is broken, and callers
     # that care can tell the two apart.
@@ -91,14 +109,13 @@ module ActionAgent
       input_params.is_a?(Hash) && input_params[ACTOR_PARAM].present?
     end
 
-    # Whether runs can carry files in this host app: Active Storage loaded,
-    # the macro applied, and its tables migrated. Never raises — a host
-    # that skipped `rails active_storage:install` still runs agents, it
-    # just can't attach files to them.
+    # Whether runs can carry files in this host app: Active Storage on per
+    # ActionAgent.active_storage, the macro applied, and its tables
+    # migrated. Never raises — a host that skipped
+    # `rails active_storage:install` still runs agents, it just can't attach
+    # files to them.
     def self.attachments_available?
-      defined?(ActiveStorage) && method_defined?(:attachments) && ActiveStorage::Blob.table_exists?
-    rescue StandardError
-      false
+      ActionAgent.active_storage_available? && method_defined?(:attachments)
     end
 
     # How an attachment reaches the model, by MIME type with a filename
@@ -118,8 +135,9 @@ module ActionAgent
       "file"
     end
 
-    # Status enum
-    enum :status, { pending: 0, running: 1, complete: 2, failed: 3, cancelled: 4 }
+    # `awaiting_input` is a run paused until a person answers its
+    # InputRequests; AgentResumeJob continues it.
+    enum :status, { pending: 0, running: 1, complete: 2, failed: 3, cancelled: 4, awaiting_input: 5 }
 
     # Validations
     validates :trace_id, presence: true
@@ -129,6 +147,23 @@ module ActionAgent
     scope :successful, -> { where(status: :complete) }
     scope :failed_runs, -> { where(status: :failed) }
     scope :today, -> { where("created_at >= ?", Time.current.beginning_of_day) }
+    # Runs executed on behalf of +actor+, matched on the Global ID recorded
+    # under ACTOR_PARAM. None for an actor without one.
+    scope :on_behalf_of, ->(actor) {
+      gid = actor.respond_to?(:to_global_id) ? actor.to_global_id.to_s : nil
+      gid ? where("#{input_param_sql(ACTOR_PARAM)} = ?", gid) : none
+    }
+
+    # SQL reading +key+ of input_params as text on the connected database.
+    # +key+ is always a literal from this codebase, never user input.
+    def self.input_param_sql(key)
+      column = "#{quoted_table_name}.input_params"
+      case connection.adapter_name.to_s.downcase
+      when /postgres/ then "#{column} ->> '#{key}'"
+      when /mysql|trilogy/ then "JSON_UNQUOTE(JSON_EXTRACT(#{column}, '$.#{key}'))"
+      else "json_extract(#{column}, '$.#{key}')"
+      end
+    end
 
     # Callbacks
     before_validation :set_trace_id, on: :create
@@ -271,27 +306,103 @@ module ActionAgent
       }
     end
 
-    # Stream output updates via ActionCable
+    # Tells subscribers of this run's stream, and of its agent's, that the
+    # run's status changed.
     def broadcast_update
-      payload = { type: "update", run: summary }
-      ActionCable.server.broadcast("agent_run_#{id}", payload)
-      ActionCable.server.broadcast("agent_runs_#{agent_id}", payload)
+      LiveUpdates.broadcast("agent_run_#{id}", type: "update", id: id, status: status)
+      LiveUpdates.broadcast("agent_runs_#{agent_id}", type: "update", id: id, status: status)
     end
 
-    # Cancel a running execution
-    def cancel!
-      return unless in_progress?
+    # Cancels a run that is in progress or waiting for input, and every
+    # request for input it still has pending.
+    #
+    # @param reason [String] recorded as the run's error message
+    def cancel!(reason = "Cancelled by user")
+      return unless in_progress? || awaiting_input?
+
+      transaction do
+        update!(status: :cancelled, completed_at: Time.current, error_message: reason)
+        input_requests.pending.update_all(status: InputRequest.statuses[:cancelled], updated_at: Time.current)
+      end
+      broadcast_update
+    end
+
+    # Expires the run's overdue requests for input, which fails the run (see
+    # InputRequest#expire!). Returns the run, reloaded when a request
+    # expired.
+    def expire_overdue_input_requests!
+      return self unless awaiting_input?
+
+      InputRequest.expire_overdue!(input_requests).positive? ? reload : self
+    end
 
+    # Writes one execution segment's result: `complete` with its output, or,
+    # for a generation that paused, `awaiting_input` with one InputRequest
+    # per paused tool call, stored in the same transaction so an answer can
+    # never find the requests before the run waits on them. Tokens and
+    # duration add to what earlier segments of the run recorded.
+    #
+    # @param result [Hash] AgentExecutionService's result
+    # @param segment_started_at [Time] when this segment started executing
+    def record_result!(result, segment_started_at:)
+      usage = result[:usage] || {}
+      attributes = {
+        output_metadata: result[:metadata],
+        duration_ms: duration_ms.to_i + ((Time.current - segment_started_at) * 1000).to_i,
+        input_tokens: add_tokens(input_tokens, usage[:input_tokens]),
+        output_tokens: add_tokens(output_tokens, usage[:output_tokens]),
+        total_tokens: add_tokens(total_tokens, usage[:total_tokens])
+      }
+
+      transaction do
+        if result[:input_requests].present?
+          InputRequest.record_pause!(self, result[:input_requests], checkpoint: result[:checkpoint])
+          update!(attributes.merge(status: :awaiting_input))
+        else
+          update!(attributes.merge(output: result[:output], status: :complete, completed_at: Time.current))
+        end
+      end
+    end
+
+    # Fails the run with +error+, recording its class beside the message: the
+    # class is what tells a refusal from a crash without reading prose.
+    #
+    # @param error [Exception]
+    # @param message [String] the message to record, when it must differ from
+    #   the error's own
+    def record_failure!(error, message: error.message)
       update!(
-        status: :cancelled,
+        status: :failed,
         completed_at: Time.current,
-        error_message: "Cancelled by user"
+        error_message: message,
+        error_backtrace: error.backtrace&.first(10)&.join("\n"),
+        output_metadata: output_metadata.to_h.merge("error_class" => error.class.name)
       )
-      broadcast_update
+    end
+
+    # Yields under the run's row lock unless the run was cancelled meanwhile,
+    # so a cancel that arrived while the run executed is never overwritten by
+    # the result. Returns whether it yielded.
+    def unless_cancelled
+      with_lock do
+        if cancelled?
+          add_log("Execution finished after cancellation; result discarded", level: :info)
+          next false
+        end
+
+        yield
+        true
+      end
     end
 
     private
 
+    def add_tokens(recorded, segment)
+      return recorded if segment.nil?
+
+      recorded.to_i + segment.to_i
+    end
+
     def locate_actor
       return nil unless actor_recorded?
       return nil unless defined?(GlobalID::Locator)