actionagent 1.7.2 → 1.8.0

data/app/jobs/action_agent/code_session_job.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  # Runs one queued Claude Code session (CodeSession) through the sandbox
+  # backend, storing its stream-json transcript as it arrives, then the
+  # outcome Claude Code reported and the diff it left in the checkout.
+  #
+  # Not retried: a session edits the checkout and spends the owner's Claude
+  # Code usage, so running it again is not the same as running it once.
+  class CodeSessionJob < ApplicationJob
+    queue_as :sandboxes
+
+    # Longest error_message kept: a failed session's own report can be long.
+    MAX_ERROR_MESSAGE = 2_000
+
+    def perform(code_session_id)
+      code_session = CodeSession.find_by(id: code_session_id)
+      return unless code_session&.queued?
+      # Claimed atomically: a session cancelled after it was loaded, or a
+      # second job for the same one, finds it no longer queued.
+      return unless start(code_session)
+
+      # Computed once rather than per event: finding them reads the GitHub
+      # connection and the Claude Code key.
+      secrets = code_session.secrets
+      result_event = nil
+      stop_sent = false
+      orchestrator = SandboxOrchestrator.new
+      sandbox = code_session.sandbox_session
+
+      # Queued behind a Stop (the cleanup job shares this queue): never start
+      # Claude Code, with the owner's credential, in a stopped sandbox.
+      unless sandbox.reload.ready? && sandbox.active?
+        return fail!(code_session, "The sandbox was stopped before the session started")
+      end
+
+      outcome = orchestrator.run_code_session(sandbox, code_session) do |event|
+        # append_event! reloads the row under its lock, so this sees a cancel
+        # made since. The cancel's own stop can land after this job claimed
+        # the session but before the backend started Claude Code, and then
+        # has no process to stop; an event means the process exists now, so
+        # the stop is sent again, once.
+        code_session.append_event!(event, secrets: secrets)
+        if code_session.cancelled? && !stop_sent
+          stop_sent = true
+          stop(orchestrator, sandbox, code_session)
+        end
+        next unless event.is_a?(Hash) && event["type"] == "result"
+
+        result_event = event
+        code_session.record_result!(event)
+      end
+
+      finish(code_session, outcome.to_h, result_event, secrets)
+    rescue StandardError => e
+      message = SecretScrubber.scrub(e.message.to_s, secrets || safe_secrets(code_session))
+      Rails.logger.error("Claude Code session #{code_session_id} failed: #{message}")
+      fail!(code_session, message) if code_session
+    end
+
+    private
+
+    def start(code_session)
+      now = Time.current
+      claimed = CodeSession.where(id: code_session.id, status: CodeSession.statuses[:queued])
+        .update_all(status: CodeSession.statuses[:running], started_at: now, updated_at: now)
+      return false if claimed.zero?
+
+      code_session.reload
+    end
+
+    # Under the row lock, which reloads the session: a cancel that landed
+    # while it ran must not be overwritten by the outcome.
+    def finish(code_session, outcome, result_event, secrets)
+      code_session.with_lock do
+        code_session.diff = outcome[:diff]
+
+        if code_session.cancelled?
+          # Settled now, with its diff (see CodeSession#diff_pending?).
+          code_session.finished_at ||= Time.current
+        elsif succeeded?(result_event, outcome)
+          code_session.assign_attributes(status: :succeeded, finished_at: Time.current)
+        else
+          code_session.assign_attributes(
+            status: :failed,
+            error_message: failure_message(result_event, outcome, secrets),
+            finished_at: Time.current
+          )
+        end
+        code_session.save!
+      end
+    end
+
+    # Claude Code reported success and the process agreed.
+    def succeeded?(result_event, outcome)
+      result_event.present? && !reported_error?(result_event) && outcome[:exit_status] == 0
+    end
+
+    # A result event reports a failure through is_error, or through an error
+    # subtype (error_max_turns, error_during_execution): a session that ran
+    # out of turns did not finish the task, whatever its is_error says.
+    def reported_error?(result_event)
+      result_event["is_error"] != false || (result_event["subtype"] || "success") != "success"
+    end
+
+    # What went wrong, in Claude Code's own words when it reported a failure
+    # and from the process otherwise.
+    def failure_message(result_event, outcome, secrets)
+      message = reported_failure(result_event) || process_failure(result_event, outcome)
+      SecretScrubber.scrub(message, secrets).truncate(MAX_ERROR_MESSAGE)
+    end
+
+    def reported_failure(result_event)
+      return nil unless result_event && reported_error?(result_event)
+
+      errors = Array(result_event["errors"]).map { |error| error.is_a?(Hash) ? (error["message"] || error.to_json) : error.to_s }
+      result_event["result"].to_s.presence ||
+        errors.join("; ").presence ||
+        "Claude Code stopped: #{result_event['subtype']}"
+    end
+
+    def process_failure(result_event, outcome)
+      status = outcome[:exit_status]
+      headline =
+        if !status.nil? && status != 0 then "Claude Code exited with status #{status}"
+        elsif result_event.nil? then "Claude Code ended without reporting a result"
+        else "Claude Code did not finish"
+        end
+
+      [ headline, outcome[:stderr_tail].to_s.strip.presence ].compact.join(": ")
+    end
+
+    def stop(orchestrator, sandbox, code_session)
+      orchestrator.cancel_code_session(sandbox, code_session)
+    rescue StandardError => e
+      Rails.logger.warn("Failed to stop cancelled Claude Code session #{code_session.id}: #{e.message}")
+    end
+
+    # Settles a session that ended without an outcome from the backend: it
+    # raised, refused to start Claude Code, or was never asked to. A session
+    # cancelled meanwhile stays cancelled, but is settled too: no diff is
+    # coming for it (see CodeSession#diff_pending?).
+    def fail!(code_session, message)
+      # A save that raised leaves unsaved changes behind, and locking a dirty
+      # record raises: start from the row as stored.
+      code_session.reload
+      code_session.with_lock do
+        if code_session.cancelled?
+          code_session.update!(finished_at: Time.current) if code_session.finished_at.nil?
+          next
+        end
+        next if code_session.finished?
+
+        code_session.update!(status: :failed, error_message: message.truncate(MAX_ERROR_MESSAGE), finished_at: Time.current)
+      end
+    rescue ActiveRecord::RecordNotFound
+      nil
+    end
+
+    def safe_secrets(code_session)
+      code_session&.secrets || []
+    rescue StandardError
+      []
+    end
+  end
+end

data/app/jobs/action_agent/sandbox_cleanup_job.rb

@@ -11,35 +11,104 @@ module ActionAgent
 
       Rails.logger.info("Cleaning up sandbox: #{sandbox.session_id}")
 
-      # Terminate the backend resource if one was provisioned
-      if sandbox.cloud_run_job_id.present? && !Rails.env.development?
-        terminate_backend_sandbox(sandbox.cloud_run_job_id)
-      end
+      # The handle is kept until the backend confirms it let go: cleared
+      # after a failed terminate, nothing would ever know the process (or
+      # container) was still there. cleanup_expired! retries these.
+      handle = sandbox.cloud_run_job_id.presence || derived_handle(sandbox)
+      return if handle.present? && !released?(sandbox, handle)
 
       # Optionally delete old sandbox records
       # For now, keep for analytics
       sandbox.update!(cloud_run_url: nil, cloud_run_job_id: nil)
     end
 
-    # Periodic cleanup of all expired sandboxes
+    # Periodic cleanup of all expired sandboxes (rake
+    # action_agent:sandbox:reap). Expires the sessions past their expiry that
+    # are still pending, provisioning, ready or running — each one's
+    # resource is released by a job of its own — and returns how many.
+    #
+    # @return [Integer]
     def self.cleanup_expired!
+      # Expired earlier, but their backend failed to terminate them, so they
+      # still hold a handle: try again. Collected first, so the sessions
+      # expired below are not enqueued twice.
+      unreleased = SandboxSession.expired.where.not(cloud_run_job_id: [ nil, "" ]).pluck(:id)
+      unreleased += unrecorded_checkouts
+
+      count = 0
       SandboxSession.expired_sessions.active.find_each do |sandbox|
         sandbox.expire!
+        count += 1
       end
+
+      unreleased.each { |id| perform_later(id) }
+      count
+    end
+
+    # Checkouts whose boot never recorded a handle can still hold processes
+    # (see #derived_handle), and a failed terminate of one left nothing
+    # behind that says so. Retried only where the backend derives handles,
+    # and only for a day after the row last changed: a released one is
+    # indistinguishable from an unreleased one, and a terminate of a
+    # sandbox that is gone is a cheap no-op, so the window is what bounds
+    # the retries.
+    RETRY_UNRECORDED_FOR = 1.day
+    RETRY_UNRECORDED_LIMIT = 100
+
+    def self.unrecorded_checkouts
+      return [] unless SandboxOrchestrator.new.derives_handles?
+
+      SandboxSession.expired.by_type("app_runtime").where(cloud_run_job_id: [ nil, "" ])
+        .where(updated_at: RETRY_UNRECORDED_FOR.ago..)
+        .order(updated_at: :desc).limit(RETRY_UNRECORDED_LIMIT).pluck(:id)
+    rescue StandardError, LoadError => e
+      Rails.logger.warn("[ActionAgent] sandbox backend unavailable to the reaper: #{e.message}")
+      []
     end
+    private_class_method :unrecorded_checkouts
 
     private
 
+    # A checkout whose provisioning never recorded a handle (the job died
+    # while the backend was booting it) can still hold processes; a backend
+    # that can name a session's sandbox without being told answers here.
+    def derived_handle(sandbox)
+      return nil unless sandbox.app_runtime?
+
+      SandboxOrchestrator.new.handle_for(sandbox)
+    rescue StandardError => e
+      Rails.logger.warn("[ActionAgent] could not derive a sandbox handle: #{e.message}")
+      nil
+    end
+
+    # Whether the backend behind +handle+ let go of it.
+    #
+    # In development a sandbox other than a checkout was only simulated (see
+    # SandboxProvisionJob#simulate_provisioning): no backend holds its
+    # made-up handle, so there is nothing to terminate. A checkout is real
+    # everywhere — the :local backend runs it as child processes of this
+    # app, which skipping terminate in development used to orphan.
+    def released?(sandbox, handle)
+      return true if Rails.env.development? && !sandbox.app_runtime?
+
+      terminate_backend_sandbox(handle)
+    end
+
     # Through the orchestrator, like provisioning: whichever backend the
-    # host registered (Incus, Kubernetes, Cloud Run, or the built-in mock)
-    # reclaims its own resource. This used to require google/cloud/run/v2
-    # directly, which the engine does not depend on — a LoadError is a
-    # ScriptError, not a StandardError, so it escaped the rescue and the job
-    # failed on every host but the one that happened to bundle the SDK.
+    # host registered (Incus, Kubernetes, Cloud Run, the :local one or the
+    # built-in mock) reclaims its own resource. This used to require
+    # google/cloud/run/v2 directly, which the engine does not depend on — a
+    # LoadError is a ScriptError, not a StandardError, so it escaped the
+    # rescue and the job failed on every host but the one that happened to
+    # bundle the SDK.
+    #
+    # Backends disagree on what terminate returns; only an explicit false
+    # (or an error) counts as not released.
     def terminate_backend_sandbox(sandbox_id)
-      SandboxOrchestrator.new.terminate(sandbox_id)
+      SandboxOrchestrator.new.terminate(sandbox_id) != false
     rescue StandardError => e
       Rails.logger.warn("Failed to terminate sandbox #{sandbox_id}: #{e.message}")
+      false
     end
   end
 end

data/app/jobs/action_agent/sandbox_provision_job.rb

@@ -2,36 +2,65 @@
 
 module ActionAgent
   class SandboxProvisionJob < ApplicationJob
+    MAX_ERROR_MESSAGE = 8_000
     queue_as :sandboxes
 
     # 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)
-      sandbox = SandboxSession.find(sandbox_session_id)
-      return if sandbox.ready? || sandbox.expired?
+      # 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)
+      return if sandbox.nil?
 
-      # In development/test, simulate provisioning
-      if Rails.env.development? || Rails.env.test?
+      # SandboxSession#provision! moves a session to provisioning and hands it
+      # over exactly once. Any other status means it was provisioned, stopped
+      # or has failed since, and provisioning it again would boot a second
+      # sandbox for one session (and orphan the first).
+      return unless sandbox.provisioning?
+
+      # In development/test, simulate provisioning. A checkout sandbox always
+      # goes to a backend: the simulation has no checkout to boot.
+      if (Rails.env.development? || Rails.env.test?) && !sandbox.app_runtime?
         simulate_provisioning(sandbox)
         return
       end
 
       # Hand off to whichever backend this install registered — the engine
-      # ships only the in-memory one, so a real container/job comes from the
-      # host app's backend (see ActionAgent.sandbox_backends).
-      result = SandboxOrchestrator.new.create_sandbox(sandbox)
+      # 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?
 
-      sandbox.mark_ready!(
-        cloud_run_url: result[:url],
-        cloud_run_job_id: result[:sandbox_id]
-      )
+      orchestrator = SandboxOrchestrator.new
+      result = orchestrator.create_sandbox(sandbox)
+      # 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.
+      handle = result[:sandbox_id]
+
+      # Stopped (or expired) while the backend was booting it: release what
+      # was just started rather than reviving the session as ready.
+      recorded = mark_ready_unless_stopped(sandbox, result)
+      unless recorded
+        release(orchestrator, handle, sandbox.id)
+        return
+      end
 
       # Broadcast status update
       broadcast_sandbox_update(sandbox)
     rescue StandardError => e
-      Rails.logger.error("Sandbox provision failed: #{e.message}")
-      sandbox.update!(status: :failed)
-      broadcast_sandbox_update(sandbox)
+      # A backend's error can carry the checkout token (a clone URL, a git
+      # error echoing its header) or the Claude Code credential; the message
+      # is stored and served to the dashboard, so it is scrubbed first.
+      # Kept whole up to a bound (SandboxSession#error_summary shortens it
+      # for display, keeping the log tail that names the actual error).
+      message = SecretScrubber.scrub(e.message.to_s, secrets_for(sandbox)).truncate(MAX_ERROR_MESSAGE)
+      Rails.logger.error("Sandbox provision failed: #{message}")
+      # Booted, but the session never recorded the handle (marking it ready
+      # raised): nothing else knows the sandbox exists, so nothing would
+      # ever terminate it.
+      release(orchestrator, handle, sandbox.id) if handle && !recorded
+      fail_unless_stopped(sandbox, message) if sandbox
     end
 
     private
@@ -46,6 +75,85 @@ module ActionAgent
       )
     end
 
+    # The owner can disconnect GitHub, or drop the repository from their
+    # 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.
+    def ensure_checkout_available!(sandbox)
+      available = begin
+        sandbox.checkout_spec.present?
+      rescue ArgumentError
+        false
+      end
+      return if available
+
+      raise "#{sandbox.repository} is no longer available: reconnect GitHub or reselect it in Settings -> Integrations"
+    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!
+    # re-reads the row under the same lock rather than trusting the copy it
+    # loaded before the boot finished.
+    def mark_ready_unless_stopped(sandbox, result)
+      sandbox.with_lock do
+        next false unless sandbox.provisioning?
+
+        sandbox.mark_ready!(
+          cloud_run_url: result[:url],
+          cloud_run_job_id: result[:sandbox_id],
+          runtime_mcp_url: result[:mcp_url],
+          runtime_mcp_token: result[:mcp_token]
+        )
+        true
+      end
+    rescue ActiveRecord::RecordNotFound
+      false
+    end
+
+    def release(orchestrator, handle, sandbox_id)
+      return if handle.blank?
+
+      released = orchestrator.terminate(handle)
+      keep_handle(sandbox_id, handle) if released == false
+    rescue StandardError => e
+      Rails.logger.warn("Failed to release sandbox #{handle}: #{e.message}")
+      keep_handle(sandbox_id, handle)
+    end
+
+    # The backend could not release it now: record the handle on the
+    # (expired) session so the reaper retries, as SandboxCleanupJob does.
+    def keep_handle(sandbox_id, handle)
+      SandboxSession.where(id: sandbox_id).update_all(cloud_run_job_id: handle)
+    end
+
+    # A session stopped while provisioning stays expired: the failure is
+    # moot, and marking it failed would bring it back into the owner's list.
+    def fail_unless_stopped(sandbox, message)
+      sandbox.reload
+      return unless sandbox.provisioning?
+
+      sandbox.update!(status: :failed, error_message: message)
+      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.
+    def secrets_for(sandbox)
+      return [] if sandbox.nil?
+
+      spec = begin
+        sandbox.checkout_spec
+      rescue StandardError
+        nil
+      end
+      [ spec&.dig(:token), *sandbox.runtime_environment.values ].compact
+    rescue StandardError
+      []
+    end
+
     def broadcast_sandbox_update(sandbox)
       ActionCable.server.broadcast(
         "sandbox_#{sandbox.session_id}",

data/app/jobs/action_agent/sandbox_run_job.rb

@@ -31,13 +31,20 @@ module ActionAgent
         end
       rescue => e
         Rails.logger.error("Sandbox run failed: #{e.message}")
-        sandbox.update!(status: :ready, error_message: e.message)
+        back_to_ready(sandbox, error_message: e.message)
         broadcast_run_error(sandbox, run_id, provider, e.message)
       end
     end
 
     private
 
+    # Only from running: a sandbox stopped while the run was in flight stays
+    # expired rather than coming back.
+    def back_to_ready(sandbox, **attributes)
+      SandboxSession.where(id: sandbox.id, status: SandboxSession.statuses[:running])
+        .update_all(attributes.merge(status: SandboxSession.statuses[:ready], updated_at: Time.current))
+    end
+
     def execute_with_active_agent(sandbox, run_id, task, provider, started_at)
       # Use generate_now here since we're already in a background job
       # The ActiveAgent will handle the API call and callbacks
@@ -67,7 +74,7 @@ module ActionAgent
         provider: provider
       )
 
-      sandbox.update!(status: :ready)
+      back_to_ready(sandbox)
       broadcast_run_complete(sandbox, run_id, run)
 
     rescue => e
@@ -100,7 +107,7 @@ module ActionAgent
         provider: provider
       )
 
-      sandbox.update!(status: :ready)
+      back_to_ready(sandbox)
       broadcast_run_complete(sandbox, run_id, run)
     end
 

data/app/models/action_agent/agent.rb

@@ -367,11 +367,16 @@ module ActionAgent
     # before the job is enqueued, so a worker on another machine finds them
     # attached. +params+ (provider/model overrides, the context_id of a
     # conversation to continue) are kept on the run as input_params.
-    def execute(input_prompt, action: nil, attachments: [], actor: nil, **params)
+    #
+    # +runtime_sandbox+ is a "sandbox:<session_id>" key whose app runtime this
+    # 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.
+    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, status: :pending
+        actor: actor, runtime_sandbox: runtime_sandbox, status: :pending
       )
 
       # Queue the execution job
@@ -381,11 +386,11 @@ module ActionAgent
     end
 
     # Quick test execution (synchronous)
-    def test_execute(input_prompt, action: nil, attachments: [], actor: nil, **params)
+    def test_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, status: :running, started_at: Time.current
+        actor: actor, runtime_sandbox: runtime_sandbox, status: :running, started_at: Time.current
       )
       run.actor = actor
 
@@ -445,16 +450,21 @@ module ActionAgent
 
     # Refuses files before creating anything: a run that exists but lost
     # its attachments would execute against the wrong prompt.
-    def create_run(input_prompt, action:, attachments:, params:, actor: nil, **attributes)
+    def create_run(input_prompt, action:, attachments:, params:, actor: nil, runtime_sandbox: nil, **attributes)
       files = Array.wrap(attachments).compact
       raise AgentRun::AttachmentsUnavailable if files.any? && !AgentRun.attachments_available?
 
+      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)
+      end
+
       run = agent_runs.create!(
         input_prompt: input_prompt,
         action_name: normalized_action(action),
         # The caller is recorded beside the run's own parameters rather than
         # among them: a client may send provider overrides, never an actor.
-        input_params: AgentRun.params_with_actor(params, actor),
+        input_params: input_params,
         trace_id: SecureRandom.uuid,
         **attributes
       )

data/app/models/action_agent/agent_run.rb

@@ -28,6 +28,11 @@ module ActionAgent
     # Underscored so it cannot collide with a provider override, and
     # stripped from anything a client sends (see Api::AgentsController).
     ACTOR_PARAM = "_actor_gid"
+    # The key a checkout sandbox's app runtime this one run also reaches is
+    # recorded under ("sandbox:<session_id>"; never its token). Set only by
+    # 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"
 
     # +input_params+ with the caller recorded alongside them.
     #
@@ -42,7 +47,7 @@ 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)
+      params = (params || {}).to_h.except(ACTOR_PARAM, ACTOR_PARAM.to_sym, SANDBOX_PARAM, SANDBOX_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
@@ -65,6 +70,19 @@ module ActionAgent
 
     attr_writer :actor
 
+    # The "sandbox:<session_id>" runtime this run reaches beside the agent's
+    # own MCP servers, or nil.
+    # @return [String, nil]
+    def sandbox_server_key
+      key = input_params[SANDBOX_PARAM] if input_params.is_a?(Hash)
+      key.to_s.presence if SandboxSession.runtime_server_key?(key)
+    end
+
+    # The session id of that sandbox, for a summary.
+    def sandbox_id
+      sandbox_server_key&.delete_prefix(SandboxSession::RUNTIME_SERVER_PREFIX)
+    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.
@@ -247,6 +265,7 @@ module ActionAgent
         instructions_preview: output_metadata&.dig("instructions")&.truncate(120),
         attachments: attachment_manifest,
         context_id: context_id,
+        sandbox_id: sandbox_id,
         created_at: created_at,
         error: error_message
       }